archy/CLAUDE.md

Archipelago — contributor guide

This file orients anyone (human or AI) working in this repository: the invariants that must hold, how to build and verify, and where the deeper design docs live. The authoritative behaviour is always the code in core/.

Read docs/ROADMAP.md for where the project is going and docs/README.md for the full documentation index.

The north star: a world-class, developer-ready app platform — every app manifest-driven, rootless, secure, and 100%-uptime-capable, with third-party developers publishing via an external/decentralized registry.

Detailed sub-plans:

• App platform / packaging phases + security model → docs/APP-PACKAGING-MIGRATION-PLAN.md
• Registry-distributed manifests → docs/registry-manifest-design.md
• External/decentralized marketplace for devs → docs/marketplace-protocol.md
• App manifest schema → docs/app-manifest-spec.md
• Production test gate → tests/lifecycle/TESTING.md

Commit & push every unit of work

Work is not "done" until it is committed and pushed. Finished work has been lost by sitting uncommitted in a shared tree across sessions. To prevent that:

• Commit each feature/fix the moment it works — one focused, self-contained commit per logical change (it compiles and its targeted tests pass). Don't let unrelated changes accumulate uncommitted.
• Push immediately after committing so nothing lives only on one machine.
• Never leave a stack of finished work uncommitted overnight or when handing off — if you must pause mid-change, commit a clearly-labelled WIP checkpoint rather than leaving the tree dirty.
• Stage explicitly by path (git add <paths>) when another contributor's uncommitted work shares the tree — never git add -A / git commit -a, which clobbers or entangles their changes.
• Never commit secrets (mnemonics, private keys, API tokens). Signing is done offline; artifacts (catalog/manifest) are signed, not the keys.

Invariants (never violate)

• Rootless Podman only. No rootful, no Docker-socket mounts, no privileged containers unless explicitly approved.
• No per-app Rust installers / no OS-level reliance. Apps are declarative; the orchestrator owns the lifecycle. A hardcoded podman run + sudo chown installer is the anti-pattern being deleted, not a template.
• Secrets are manifest-declared (generated_secrets, materialised by container::secrets, 0600/rootless) — never hardcoded, per-app, or logged.
• Migrations never destroy data — preserve /var/lib/archipelago/<app>, secrets, credentials, ports, and adoption container names; keep a rollback path.
• Verify on a real node before any release tag.

Build / verify

• Rust workspace root is core/ (no Cargo.toml at repo root). Run cargo from core/.
• If a cargo test/build hits rust-lld: undefined hidden symbol, it's incremental-cache corruption — rebuild with CARGO_INCREMENTAL=0.
• Frontend: neode-ui/ → npm run build outputs to web/dist/neode-ui/. Grep the built bundle for new strings before shipping (the build can silently no-op).
• App manifests are delivered inside the signed catalog (releases/app-catalog.json), whose entry overrides the on-disk /opt/archipelago/apps/*/manifest.yml (origin-wins; disk is the fallback). Editing a disk manifest alone does not change a catalog-covered app — regenerate and re-sign the catalog.

Production test gate (definition of done)

tests/lifecycle/run-gate.sh must be green across install / UI / stop / start / restart / reinstall / reboot-survive / archipelago-restart-survive / uninstall. Run the gate on the node (it uses local podman/systemctl/bitcoin probes), not via RPC from another host, and re-run it after any orchestrator/lifecycle change. Multinode / fleet testing is a separate pass. See tests/lifecycle/TESTING.md.