docs: add a grouped documentation index; fix references to now-local-only docs

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>
This commit is contained in:
archipelago
2026-08-07 18:11:05 -04:00
co-authored by Claude Opus 5
parent bf76955114
commit 661f3eda25
4 changed files with 87 additions and 7 deletions
+4 -4
View File
@@ -28,7 +28,7 @@ The migration's aim, restated as **five pillars** (every app must satisfy all fi
(install / UI reachable / stop / start / restart / reinstall / reboot-survive
/ archipelago-restart-survive / uninstall) **5× green on .228** — run ON the node
(`ARCHY_ITERATIONS=5`).
(Multinode / fleet `docs/multinode-testing-plan.md`, separate.)
(Multinode / fleet testing is tracked separately.)
before any release.
4. **Data-driven apps** — install/uninstall needs only the app's manifest +
catalog entry. **No host OS changes** (no apt, no /etc, no host units) and
@@ -44,7 +44,7 @@ The migration's aim, restated as **five pillars** (every app must satisfy all fi
green on .228 (run ON the node) → catalog/registry updated (`app-catalog/catalog.json`
+ `releases/app-catalog.json`, rebuilt image pushed to the mirror) → tracker
cell ticked. Only then move to the next app. (Fleet/multinode verification is a
separate pass`docs/multinode-testing-plan.md`.)
separate pass, tracked internally.)
**.228 testing constraint:** do NOT touch `bitcoin-knots`, `electrumx`, or
`lnd` on .228 — they are synced and healthy; destructive cycles there would
@@ -75,7 +75,7 @@ don't add session logs here.
| L6 — Performance | Cold install latency, reconcile-tick cost, podman call count per lifecycle event | timed bats + Prometheus (TBD) | ~60s per benchmark |
Release gate: **L0+L1+L2+L3 green × 20 iterations** on .228 (run ON the node; 5× for
now). Multinode/fleet `docs/multinode-testing-plan.md`. L4+L5+L6 are quality gates
now). Multinode/fleet testing is a separate pass. L4+L5+L6 are quality gates
we add as they mature; not blocking the v1.7.52 tag.
## Coverage matrix — current state
@@ -241,7 +241,7 @@ priority-ordered list of what's still open across these):
1. ☑ Bitcoin-stops fix verified live on a fresh node (`tests/lifecycle/bats/bitcoin-knots.bats`
stop/restart tier, part of the green single-node gate)
2.`ARCHY_ITERATIONS=5 tests/lifecycle/run-gate.sh` returns 0 **run ON .228** — GREEN 2026-06-23, 5/5, 0 failures
3. ☐ Multinode/fleet (.198 + others) — tracked separately in `docs/multinode-testing-plan.md`,
3. ☐ Multinode/fleet — tracked separately,
the actual next exit criterion, NOT satisfied yet
4. ☐ The L3 `backend-survives-archipelago-restart` suite passes fleet-wide default-on
(Phase 3 Quadlet is merged + validated but still opt-in via `ARCHIPELAGO_USE_QUADLET_BACKENDS`