# Archipelago documentation

Start with the smallest set for your task. This index distinguishes current
entry points from proposals and dated evidence. Code and the root
[`AGENTS.md`](../AGENTS.md) govern actual behavior and authority; a dated plan,
passing test or historical node receipt does not certify a newer build.

## New developer path

1. [Project README](../README.md) — what ships and which installer and update
   releases are published.
2. [Contribution guide](../CONTRIBUTING.md) and [developer guide](developer-guide.md)
   — canonical ngit workflow, source map and safe local checks.
3. [OS architecture](architecture.md) ([visual HTML guide](architecture.html))
   — browser, backend, rootless apps, data, trust and protected host maintenance.
4. [Release & Testing](../Release%20%26%20Testing/README.md) — current scope,
   evidence levels and open acceptance gates.

## Work by area

| Area | Read first | Then, if relevant |
| --- | --- | --- |
| Backend/API | [Developer guide](developer-guide.md) | [RPC overview](api-reference.md), [container lifecycle](container-lifecycle.md) |
| Frontend | [Developer guide](developer-guide.md) | [Gamepad navigation](GAMEPAD-NAV.md), [TV input](tv-input-iframe-apps.md) |
| App packaging | [App developer guide](app-developer-guide.md) | [Manifest spec](app-manifest-spec.md), [Quadlet compilation](quadlet-compilation.md), [app secrets](secrets.md), [catalog distribution](registry-manifest-design.md) |
| Installer and updates | [Image recipe](../image-recipe/README.md) | [OS updates](os-updates.md), [protected executor contract](OS-OTA-CONTRACT-20261103.md), [system-level OTA design](system-level-ota-design.md) |
| Network and fleet | [Multi-node architecture](multi-node-architecture.md) | [Peering trust](peering-trust-model.md), [external access and websites](external-access-and-websites.md), [OpenWrt setup](openwrt-gateway-setup.md) |
| Security | [Security policy](../SECURITY.md) | [2.1 beta audit matrix](security/2.1-beta-audit-acceptance-matrix.md), [Bitcoin RPC exposure](security/BITCOIN-RPC-PROXY-EXPOSURE.md), [PSBT signing](security/PSBT-SIGNING-ARCHITECTURE.md) |
| Release operations | [Release & Testing](../Release%20%26%20Testing/README.md) | [Candidate catalog qualification](candidate-catalog-qualification.md), [target-specific OS manifests](target-specific-release-manifests.md) |

The API overview is hand-maintained. Verify exact method behavior in
`core/archipelago/src/api/rpc/` and its tests. App and OS changes require their
separate acceptance contracts; do not treat a generic build or UI mock as an
installed-node pass.

## Users and operators

- [User walkthrough](user-walkthrough.md) and [troubleshooting](troubleshooting.md).
- [Seed verification](SEED-VERIFICATION.md) and [talking to your node](COMMANDS.md).
- [Pine voice commands](pine-voice-commands.md) and
  [Companion pairing QR](companion-pairing-qr.md).

## Dated designs and evidence

The [public roadmap](ROADMAP.md) records direction, not an active release
checklist. [`TODO.md`](TODO.md) holds unscoped follow-ups; the current
release plan and failure gates are in [Release & Testing](../Release%20%26%20Testing/README.md).

Other design documents in `docs/` describe proposed or historical behavior.
Read their date and status before using them. The [`adr/`](adr/) directory
records design decisions; [`archive/`](archive/README.md) and Git history retain
superseded material. Dated release acceptance and incident records remain
version-specific evidence, not instructions to rerun their old actions. Old
deployment runbooks and completed checklists removed from the active tree are
available in Git history.