Recovery

Project: kane-diagnostics
Version: 1.0
Read this before touching anything.

The Three Rules

Gitea is the SSOT. Read from it. Never write to it directly. The operator pushes files. You produce downloads.
The host mirrors the repo. If something looks wrong on the host, the answer is in the repo — not in a shell command.
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.

4.4 KiB Raw Blame History