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/.

Start with AGENTS.md for the current workflow and authority, docs/README.md for the documentation index, and Release & Testing/README.md for current release scope. docs/ROADMAP.md is a dated public overview.

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:

• Current app packaging contract → docs/app-developer-guide.md and docs/app-manifest-spec.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

Preserve work and follow publication authority

• Keep focused commits and a clear checkpoint for unfinished work. Follow AGENTS.md for review, mirror and publication gates; a commit does not by itself authorize a push, merge or release.
• Preserve other contributors' dirty work and recorded failures. Do not create a WIP commit merely to make a shared tree clean.
• 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.