From cc1eab77947704cdb9edd73e28dc5e151f4ac9a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Padez?= Date: Thu, 13 Aug 2026 05:26:48 +0000 Subject: [PATCH] docs: a triage map of the documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 42 documents, 13,000 lines, and no way to tell from a filename which describe the system as it is and which record an afternoon in July. This sorts them: living, stale, historical, and two clusters that want consolidating. Says plainly how much was verified — mostly filenames, status lines and greps for what changed today — so it reads as a starting point rather than a verdict. Names the two obvious consolidations without performing them. Nine opencode documents for one migration that has landed (verified: `opencode serve` is in the sidecar, so the plan's "nothing here is implemented" is false), and three mobile-dav documents that are one correspondence. Both need all of them read first, which is not a 4am job. Marks the historical ones as not-to-be-rewritten. claude-sidecar-isolation.md records the officer-claude to officer-agent rename that preceded tonight's rename to officer-claude-code; editing it to match today's code would destroy the reasoning it exists to hold. And notes what most of them share: they were written when the estate was twenty processes and everything was simply present. A core install is six. The fix is usually one line — say whether the thing is core or a plugin — not a rewrite. Co-Authored-By: Claude Opus 5 (1M context) --- docs/README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..31def65f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,84 @@ +# The documentation, triaged + +**2026-08-13.** A map of what is in here, what it is for, and what should happen to it. Made because +there are 42 documents and 13,000 lines, and no way to tell from the filenames which describe the +system as it is and which are a record of an afternoon in July. + +**How much I verified:** the classifications below are from filenames, status lines, and greps for +things that changed on 2026-08-13. Where I actually read the document or checked the code, it says +so. The rest is a starting point for a conversation, not a verdict. + +--- + +## Living — these describe the system and must stay true + +| doc | state | +| --- | --- | +| `working-on-officer.md` | **updated 2026-08-13.** Operational guide. | +| `secret-store.md` | **updated 2026-08-13.** Built; rotation still open. | +| `install-variants.md` | new. The branch tree, for discussion. | +| `http-secure-context-audit.md` | new. What breaks over plain http. | +| `install-container-testing.md` | new. First container pass and its findings. | +| `per-user-linux-accounts.md` | partly updated. `OFFICER_OS_USERS` is gone; check the rest. | +| `navigation-audit.md` | authoritative on routing. Unverified against tonight's route removals. | +| `workspace-panels.md` + `workspace-panel-todo.md` | the panel framework. 1,300 lines combined — likely the biggest cleanup here. | +| `agent-coordination.md` | the north star for panel work. | +| `deprovision-os-account.md` | implemented; the `'disabled'` stage it may mention was deleted tonight. | + +## Stale — describe things that changed on 2026-08-13 + +Each of these references something that no longer exists. **Not yet corrected.** + +- `sidecar-topology.md` — "ecosystem.config.cjs is the source of truth". It is generated now, and + holds six processes. +- `sidecar-app-store.md` — derives the catalogue from `full − light`. Those files are gone, and + `catalogue.test.ts` was rewritten. +- `sidecar-bootstrapping.md` — "20 PM2 entries, 18 sidecar dirs". Six entries now. +- `mobile-api-keys.md` — partly corrected; recheck the origin-checking claims. +- `wallet-key-custody.md` — `VAULT_STORE_KEY` is now the per-purpose `wallet` key. +- `push-notifications.md` — "agreed design, 2026-07-31". Notify is a plugin and unmounted. +- `chat-session-lifetime.md`, `chat-ui-walkthrough.md` — reference `officer-agent`, renamed. + +## Historical — a record of a moment, and should stay one + +Do **not** rewrite these to match today's code. They document how a decision was reached, and +editing them destroys the reasoning. If they mislead, add a dated header pointing forward. + +- `sidecar-audit-2026-07.md` (1,377 lines) +- `claude-sidecar-isolation.md` — records the `officer-claude` → `officer-agent` rename that + preceded tonight's `officer-agent` → `officer-claude-code` +- `open-threads-after-per-user-claude.md` +- `two-agent-field-report-2026-08-12.md` +- `api-method-changes-2026-08-06.md` + +## The opencode cluster — nine documents for one migration + +`opencode-fork-decision` · `-parity` · `-api-2-assessment` · `-phase0-review` · `-phase1-report` · +`-phase1-review` · `-serve-migration-plan` · `-serve-path` · `-testing-checklist` + +**The migration landed** — `opencode serve` is in the sidecar, verified. So +`opencode-serve-migration-plan.md` saying "Nothing here is implemented" is false. + +This is the clearest consolidation candidate in the whole directory: one document recording what was +decided and what shipped, replacing nine that describe stages of getting there. I did not do it +because it needs reading all nine, and deleting documents unread is not a thing to do at 4am. + +## The mobile-dav thread — three documents, one conversation + +`mobile-dav-provisioning` · `-feedback` · `-reply`. A correspondence. Almost certainly one document. + +## Unclassified — I have not looked + +`design-language-interface` · `file-sync` · `jobs-unification` · `mobile-photo-sync-api` · +`nextcloud-replacement` · `agent-git-identity` + +--- + +## The plugin split, which affects most of the above + +A core install is six processes. **Everything else is a plugin**, switched off tonight but present on +disk. Most documents here were written when the estate was twenty processes and every one of them was +simply "there", so they describe availability that no longer holds. + +The useful rewrite is usually one line, not a rewrite: say whether the thing described is **core** or +**a plugin**, and if a plugin, that it is not mounted on a fresh install.