# 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.