From 661f3eda252e490ef4a260919d9fdeb425ac4398 Mon Sep 17 00:00:00 2001 From: archipelago Date: Fri, 7 Aug 2026 18:11:05 -0400 Subject: [PATCH] docs: add a grouped documentation index; fix references to now-local-only docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- README.md | 3 ++ docs/README.md | 78 ++++++++++++++++++++++++++++++++++++++ docs/ROADMAP.md | 5 +-- tests/lifecycle/TESTING.md | 8 ++-- 4 files changed, 87 insertions(+), 7 deletions(-) create mode 100644 docs/README.md diff --git a/README.md b/README.md index 74ade98e..dd5a11be 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,9 @@ python3 scripts/check-app-catalog-drift.py --release --strict ## Documentation map +The full, grouped index lives at **[docs/README.md](docs/README.md)**. The most +common entry points: + | Doc | Purpose | |-----|---------| | [Architecture](docs/architecture.md) | System layers, crates, data paths, security model | diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..982a46a6 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,78 @@ +# Archipelago documentation + +Start here. This index groups the docs by what you're trying to do. The +authoritative behaviour is always the code in `core/`; where a doc and the code +disagree, the code wins and the doc is a bug. + +## Getting started + +- [User Walkthrough](user-walkthrough.md) — setting up and using a node, from hardware to daily use +- [Talking to your node](COMMANDS.md) — the conversational command surface +- [Seed Verification](SEED-VERIFICATION.md) — independently verify your 24-word backup +- [Troubleshooting](troubleshooting.md) — common problems and how to resolve them +- [Gamepad / Controller Navigation](GAMEPAD-NAV.md) — driving the UI from a controller + +## Architecture + +- [Architecture](architecture.md) — the system at a glance +- [Multi-Node Architecture](multi-node-architecture.md) — how nodes relate across a fleet +- [API Reference](api-reference.md) — the JSON-RPC surface + +## App development + +- [App Developer Guide](app-developer-guide.md) — build and package a containerized app +- [App Manifest Specification](app-manifest-spec.md) — the manifest schema, field by field +- [Registry-Distributed Manifests](registry-manifest-design.md) — how manifests reach nodes via the signed catalog +- [Decentralized Marketplace Protocol](marketplace-protocol.md) — publishing apps via an external registry +- [Bitcoin RPC Relay](bitcoin-rpc-relay.md) — letting an external wallet reach the node's Bitcoin RPC +- [Companion Pairing QR](companion-pairing-qr.md) — the pairing handoff contract +- [TV input inside iframe apps](tv-input-iframe-apps.md) — keyboard/gamepad routing into embedded apps + +> **Known gap (tracked):** three app-developer references named in the +> open-source plan are not yet written — how a manifest compiles to a +> Quadlet/systemd unit, the container-lifecycle reconciler state machine, and +> the `generated_secrets` materialisation flow. Until they land, the source of +> truth is the code: `core/archipelago/src/container/quadlet*.rs`, +> `prod_orchestrator.rs`, and `container::secrets` respectively. + +## Design docs + +These record why a thing is built the way it is. They are design records, not +step-by-step guides, and some predate the current implementation. + +- [Registry-Distributed Manifests](registry-manifest-design.md) +- [DHT Distribution](dht-distribution-design.md) +- [Bitcoin Multi-Version](bitcoin-multi-version-design.md) +- [Dual Ecash](dual-ecash-design.md) +- [Hardware Signer](hardware-signer-design.md) +- [Manifest Hooks](manifest-hooks-design.md) +- [Meshroller Integration](meshroller-integration-design.md) +- [Nostr Git Source Hosting](nostr-git-source-hosting.md) +- [Nostr Identity Import](nostr-identity-import-plan.md) · [Nostr Signer Login (research)](nostr-signer-login-research.md) +- [Streaming Ecash (phase 4)](phase4-streaming-ecash-plan.md) +- [App Packaging Migration](APP-PACKAGING-MIGRATION-PLAN.md) + +## Decisions (ADRs) + +- [ADR-001: Podman over Docker](adr/001-podman-over-docker.md) +- [ADR-002: DID Key Method for Node Identity](adr/002-did-key-method.md) +- [ADR-003: Nostr Relays for Discovery](adr/003-nostr-for-discovery.md) +- [ADR-004: Tor Hidden Services for Peer Communication](adr/004-tor-for-peer-communication.md) +- [ADR-005: ChaCha20-Poly1305 for Backup Encryption](adr/005-chacha20-backup-encryption.md) +- [ADR-006: Nostr Relays for Marketplace Discovery](adr/006-nostr-marketplace-discovery.md) +- [ADR-007: DID-Based Federation Trust](adr/007-did-federation-trust.md) +- [ADR-008: Dual Key Strategy (Ed25519 + Secp256k1)](adr/008-dual-key-strategy.md) +- [ADR-009: Manifest-Level Container Security](adr/009-manifest-container-security.md) +- [ADR-011: DWN Deprioritization](adr/011-dwn-deprioritization.md) + +## Security + +- [Security Policy](../SECURITY.md) — how to report a vulnerability +- [PSBT Signing Architecture](security/PSBT-SIGNING-ARCHITECTURE.md) +- [Bitcoin RPC Proxy Exposure](security/BITCOIN-RPC-PROXY-EXPOSURE.md) +- [Entropy Enforcement (KEY-05)](security/KEY-05-ENTROPY-ENFORCEMENT.md) + +## Roadmap & history + +- [Roadmap](ROADMAP.md) — where the project is going +- [archive/](archive/README.md) — superseded design and status documents, kept for provenance diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index de37a58e..2da4c686 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -49,9 +49,8 @@ security-first. ## 🔄 In progress - **Multinode pass** — run the same production gate across the whole test - fleet, plus cross-node federation/mesh suites - ([`multinode-testing-plan.md`](multinode-testing-plan.md)). This is the - current exit criterion. + fleet, plus cross-node federation/mesh suites. This is the current exit + criterion. - **Quadlet default flip** — flip the validated Quadlet path from opt-in to default fleet-wide; eliminates the last container-flapping root cause. - **Container-flapping elimination** — reconciler churn and failed-unit diff --git a/tests/lifecycle/TESTING.md b/tests/lifecycle/TESTING.md index afac9138..c018a390 100644 --- a/tests/lifecycle/TESTING.md +++ b/tests/lifecycle/TESTING.md @@ -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`