124 lines
4.4 KiB
Markdown
124 lines
4.4 KiB
Markdown
# Recovery
|
|
|
|
**Project:** kane-diagnostics
|
|
**Version:** 1.0
|
|
**Read this before touching anything.**
|
|
|
|
---
|
|
|
|
## The Three Rules
|
|
|
|
1. **Gitea is the SSOT.** Read from it. Never write to it directly. The operator pushes files. You produce downloads.
|
|
2. **The host mirrors the repo.** If something looks wrong on the host, the answer is in the repo — not in a shell command.
|
|
3. **Git history is the diagnostic tool.** Before concluding anything is damaged, read the log.
|
|
|
|
---
|
|
|
|
## The Workflow
|
|
|
|
### When something is broken on the host
|
|
|
|
```
|
|
# Step 1 — find what changed
|
|
git log --oneline -- path/to/file
|
|
|
|
# Step 2 — read what it looked like before
|
|
git show <commit-sha>:path/to/file
|
|
|
|
# Step 3 — produce a download with the correct content
|
|
# Do not print it to the browser. Create a file.
|
|
|
|
# Step 4 — give the operator two commands after they push:
|
|
cd /var/www/kane-diagnostics && git pull
|
|
cp hubzilla/addon/{addon}/file /var/www/hubzilla/addon/{addon}/file
|
|
```
|
|
|
|
That is the entire recovery procedure. It takes two minutes when done correctly.
|
|
|
|
### When you need to understand the host environment
|
|
|
|
Read the repo. Everything needed to understand this project is in the repo:
|
|
|
|
- `README.md` — what the project is and why it exists
|
|
- `CODING-GUIDELINES.md` — constraints that apply to all code
|
|
- `ADDON-SKELETON-SPEC.md` — the standard every addon follows
|
|
- `ASSOC-PROFILE-SPEC.md` — the assoc_profile addon specifically
|
|
- `ASSOCIATION-CHANNEL-MODEL.md` — how Hubzilla channels map to associations
|
|
- `hubzilla/view/theme/uscivicinfra/` — CSS only; extends redbasic
|
|
- `https://gitea.barternetwork.us/TheRON/core` — the full Hubzilla core is mirrored here; read templates from it
|
|
|
|
### When you need a template from Hubzilla core
|
|
|
|
The Hubzilla core is mirrored at `https://gitea.barternetwork.us/TheRON/core` on the `master` branch. Read it through MCP. Do not ask the operator to run `cat` commands for files that are in a repo you can read.
|
|
|
|
The three-column layout template is at `view/php/default.php` in that repo. The aside region (`region_1`) is always rendered — it does not collapse when empty. An empty `[region=aside]` produces a visible but contentless left column. Content in the aside gives it its visible width.
|
|
|
|
---
|
|
|
|
## The Host Layout
|
|
|
|
```
|
|
/var/www/hubzilla/ — Hubzilla core installation
|
|
/var/www/hubzilla/addon/ — installed addons
|
|
/var/www/kane-diagnostics/ — git clone of the SSOT repo
|
|
```
|
|
|
|
The install commands follow this pattern:
|
|
|
|
```
|
|
cd /var/www/kane-diagnostics && git pull
|
|
cp hubzilla/addon/{addon}/{file} /var/www/hubzilla/addon/{addon}/{file}
|
|
```
|
|
|
|
Runtime files that live on the host only — never in the repo:
|
|
- `config.json` — node-specific, contains secrets
|
|
- `assoc_registry.json` — operator-managed association data
|
|
- `assoc_fields.json` — operator-managed field definitions
|
|
- `listings.json` — operator-managed institutional directory
|
|
|
|
---
|
|
|
|
## The PDL Pattern
|
|
|
|
Every addon PDL follows this structure:
|
|
|
|
```
|
|
[template]default[/template]
|
|
|
|
[region=aside]
|
|
[widget={addon}][/widget]
|
|
[/region]
|
|
|
|
[region=content]
|
|
$content
|
|
[/region]
|
|
|
|
[region=right_aside]
|
|
[widget=notifications][/widget]
|
|
[widget=newmember][/widget]
|
|
[/region]
|
|
```
|
|
|
|
Exception: `assoc_profile` uses `[widget=vs01]` in the aside — it shares the vs01 institutional directory widget rather than having its own. This is intentional and documented in `ASSOC-PROFILE-SPEC.md`.
|
|
|
|
The right aside is permanent and identical across all addons. It is never modified.
|
|
|
|
---
|
|
|
|
## What the Previous Assistant Damaged
|
|
|
|
For the historical record: on 2026-06-06, a previous assistant replaced the `[widget=vs01]` in `mod_assoc_profile.pdl` with an empty aside and added a misplaced copy of `assoc_profile_manage.php` to `view/css/`.
|
|
|
|
The PDL was recovered by reading `git log` and `git show` on the file. The misplaced PHP file in `view/css/` remains in the repo and should be deleted — it is not installed on the host and causes no runtime harm, but it does not belong there.
|
|
|
|
---
|
|
|
|
## What Not To Do
|
|
|
|
- Do not write files directly to the host. Produce a download.
|
|
- Do not print file contents to the browser. Produce a download.
|
|
- Do not guess at the Hubzilla template structure. Read `view/php/default.php` in the core mirror.
|
|
- Do not ask the operator to run shell commands for information available in a repo you can read via MCP.
|
|
- Do not create a `Widget/` directory under `assoc_profile`. That addon has no Widget. Read `ASSOC-PROFILE-SPEC.md`.
|
|
- Do not push from the host. Gitea is the SSOT.
|