The index covered users, architecture and app development but had no entry
point for "I want to work on Archipelago itself" — so eight tracked docs were
reachable only by guessing filenames, including the two that matter most to a
newcomer: developer-guide.md (how to build the workspace, the frontend and an
ISO) and LICENSE-COMPLIANCE-AUDIT.md (dependency licensing, which is exactly
what a reader checks first on an open-source repo).
Added a "Contributing to Archipelago itself" section covering those plus
bulletproof-containers, the signing runbook, the 1.8.0 hardening plan and
CLAUDE.md; filed pine-voice-commands under Getting started and demo-build-info
under contributing.
Also noted that ADR-010 was never issued — verified across all history, so the
009 → 011 gap is not a missing file — and added the two archived session logs
(HANDOVER-2026-07-02, SESSION-1.8.0-OTA-PROGRESS) to the archive table, which
already claimed to cover completed session logs but listed none.
Link check re-run across docs/: 0 broken. Only RELEASE_NOTES_BACKLOG.md is now
deliberately unindexed (internal working list).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The open-source plan flagged three references as "the real gaps for app
developers", and the docs index named them as not-yet-written. Written now,
each from the code rather than stubbed:
- secrets.md — generated_secrets/secret_env: the two halves, the four kinds
(hex16/hex32/base64/bcrypt) and which files each writes, the idempotent
self-healing 0600 materialisation, and the rules a developer must not break
(no hardcoded fallbacks, one canonical name, right encoding). From
container/secrets.rs and the manifest schema.
- quadlet-compilation.md — manifest -> .container unit: the full directive
mapping (including Secret= by reference, never value, and Pull=never), where
units land (~/.config/containers/systemd, systemctl --user), the
render/write/enable/disable lifecycle with write-if-changed, and how to
inspect one. From container/quadlet.rs, scoped accurately to the companion-UI
path it drives today.
- container-lifecycle.md — the level-triggered 30s reconciler: desired state
from user-stopped/user-uninstalled/manifest set, the operations table, the
self-heal-vs-respect-a-deliberate-stop rule, and migrations-never-destroy-data.
From prod_orchestrator.rs and boot_reconciler.rs.
Index updated to link all three under App development and the "known gap" note
removed. Every link across the docs tree resolves.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two concrete, verifiable documentation gaps from the open-source review:
- docs/ had no index. Adds docs/README.md grouping the 60-odd published docs by
task — getting started, architecture, app development, design docs, ADRs,
security, roadmap — in the bitcoin/bitcoin doc/ style the plan called for.
Every link in it resolves (checked). The top-level README now points at it as
the front door rather than duplicating the list.
- ROADMAP.md and tests/lifecycle/TESTING.md linked docs/multinode-testing-plan.md,
which moved to local-only (it is a fleet node inventory, not published). Those
references now describe the scope split in prose instead of pointing at a file
that is not in the public tree.
The index is honest about what is missing: it names the three app-developer
docs the plan flagged as gaps (quadlet compilation, container lifecycle,
secrets materialisation) as not-yet-written, and points at the authoritative
code for each rather than pretending they exist.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
