Docs pass: ARCHITECTURE.md + README.md catch up to v0.3.21 (part of #80) #84

Merged

Cordy merged 1 commit from docs-pass into main

2026-07-30 15:01:16 +00:00

Cordy commented

2026-07-30 14:59:54 +00:00

Owner

First part of #80 — the Cairn repo docs. Site and license-server docs follow in their own PRs.

§5.4 renamed to "Authorization and data governance" and given the four features that shipped API-first and were undocumented:

Read-only spaces (#64) — the -ro group-name convention, storage.ErrReadOnly, and that the UI badge is advisory while scope enforces.
Audit logging (#61) — monthly JSONL, retainMonths prune, what is and isn't recorded (never List/Stat), and that it covers public share reads via the unscoped store.
Legal holds (#63) — binds admins too, bidirectional containment, set/lift are themselves audited.
Retention + trash auto-purge (#63/#77) — longest-prefix retention, and the three auto-purge guard rails.

Decorator order is now written down, which it wasn't anywhere. I verified it against cmd/cairnd/main.go rather than trusting memory — and it's worth flagging that it is base → encrypt → quota → trash → hold → audit → scope, i.e. audit sits above trash (a user delete logs as delete, not the rename trash does beneath it) and hold sits under audit. My own working notes had recorded "hold → audit → trash", which was wrong; the doc follows the code.

§7 gains the admin/audit and admin/holds endpoints, and the stale "Planned additions: quota enforcement" line is corrected (enforcement shipped in v0.3.1).

§9 scaling posture: the role-split is no longer hypothetical — documented the shipped --target=all|api|crypto (#33) and the remoteUrl/remoteToken offload.

§10 milestones: v0.3 now lists the governance features, crypto split, and auto-purge; v0.4 marks license server + site as live and leaves only the GitHub mirror pending.

README gains one Data-governance feature bullet.

Scope note: I deliberately left §4.3's pre-implementation "design task before any implementation" encryption bullets untouched — that's a separate contradiction (the section intro already reflects the shipped probe) and outside this issue's list. Flagging it rather than fixing it blind. SYNC.md I reviewed in full and it is accurate to current behaviour (app passwords, .249, per-user homes) — no change needed; the "interop matrix" I worried about in the issue text doesn't live there.

First part of #80 — the Cairn repo docs. Site and license-server docs follow in their own PRs. **§5.4 renamed to "Authorization and data governance"** and given the four features that shipped API-first and were undocumented: - **Read-only spaces** (#64) — the `-ro` group-name convention, `storage.ErrReadOnly`, and that the UI badge is advisory while scope enforces. - **Audit logging** (#61) — monthly JSONL, `retainMonths` prune, what is and isn't recorded (never List/Stat), and that it covers public share reads via the unscoped store. - **Legal holds** (#63) — binds admins too, bidirectional containment, set/lift are themselves audited. - **Retention + trash auto-purge** (#63/#77) — longest-prefix retention, and the three auto-purge guard rails. **Decorator order is now written down**, which it wasn't anywhere. I verified it against `cmd/cairnd/main.go` rather than trusting memory — and it's worth flagging that it is **base → encrypt → quota → trash → hold → audit → scope**, i.e. audit sits *above* trash (a user delete logs as `delete`, not the rename trash does beneath it) and hold sits *under* audit. My own working notes had recorded "hold → audit → trash", which was wrong; the doc follows the code. **§7** gains the `admin/audit` and `admin/holds` endpoints, and the stale "Planned additions: quota enforcement" line is corrected (enforcement shipped in v0.3.1). **§9** scaling posture: the role-split is no longer hypothetical — documented the shipped `--target=all|api|crypto` (#33) and the `remoteUrl`/`remoteToken` offload. **§10** milestones: v0.3 now lists the governance features, crypto split, and auto-purge; v0.4 marks license server + site as live and leaves only the GitHub mirror pending. **README** gains one Data-governance feature bullet. Scope note: I deliberately left §4.3's pre-implementation "design task before any implementation" encryption bullets untouched — that's a separate contradiction (the section intro already reflects the shipped probe) and outside this issue's list. Flagging it rather than fixing it blind. SYNC.md I reviewed in full and it is accurate to current behaviour (app passwords, `.249`, per-user homes) — no change needed; the "interop matrix" I worried about in the issue text doesn't live there.

Cordy added 1 commit

2026-07-30 14:59:55 +00:00