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.

UI/UX changes need maintainer UAT

Any PR that touches UI (neode-ui/, web/, locale strings, styles, app launch surfaces, or backend changes to UI-visible text, settings, states or errors) must start its description with this line, verbatim: Requires UI/UX UAT approval from the maintainer. It must then list the screens and flows to review. It is not merged until the maintainer approves. AGENTS.md has the full rule and what the list must cover.

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.