archipelagoandClaude Opus 5
661f3eda25
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>
4.1 KiB
4.1 KiB
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 — setting up and using a node, from hardware to daily use
- Talking to your node — the conversational command surface
- Seed Verification — independently verify your 24-word backup
- Troubleshooting — common problems and how to resolve them
- Gamepad / Controller Navigation — driving the UI from a controller
Architecture
- Architecture — the system at a glance
- Multi-Node Architecture — how nodes relate across a fleet
- API Reference — the JSON-RPC surface
App development
- App Developer Guide — build and package a containerized app
- App Manifest Specification — the manifest schema, field by field
- Registry-Distributed Manifests — how manifests reach nodes via the signed catalog
- Decentralized Marketplace Protocol — publishing apps via an external registry
- Bitcoin RPC Relay — letting an external wallet reach the node's Bitcoin RPC
- Companion Pairing QR — the pairing handoff contract
- TV input inside iframe apps — 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_secretsmaterialisation flow. Until they land, the source of truth is the code:core/archipelago/src/container/quadlet*.rs,prod_orchestrator.rs, andcontainer::secretsrespectively.
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
- DHT Distribution
- Bitcoin Multi-Version
- Dual Ecash
- Hardware Signer
- Manifest Hooks
- Meshroller Integration
- Nostr Git Source Hosting
- Nostr Identity Import · Nostr Signer Login (research)
- Streaming Ecash (phase 4)
- App Packaging Migration
Decisions (ADRs)
- ADR-001: Podman over Docker
- ADR-002: DID Key Method for Node Identity
- ADR-003: Nostr Relays for Discovery
- ADR-004: Tor Hidden Services for Peer Communication
- ADR-005: ChaCha20-Poly1305 for Backup Encryption
- ADR-006: Nostr Relays for Marketplace Discovery
- ADR-007: DID-Based Federation Trust
- ADR-008: Dual Key Strategy (Ed25519 + Secp256k1)
- ADR-009: Manifest-Level Container Security
- ADR-011: DWN Deprioritization
Security
- Security Policy — how to report a vulnerability
- PSBT Signing Architecture
- Bitcoin RPC Proxy Exposure
- Entropy Enforcement (KEY-05)