lfg2025/archy

archipelago 192238cbb8 docs: consolidate into PRODUCTION-MASTER-PLAN, add CLAUDE.md, prune 25 stale docs

Single authoritative hub (docs/PRODUCTION-MASTER-PLAN.md) for the app-platform
north star: every app manifest-driven (zero OS-level reliance), manifests via the
signed registry, developer-ready external marketplace; rootless/secure/robust/
100%-uptime. Repo CLAUDE.md (auto-loaded each session) points agents at it until
the 20x lifecycle gate is green. New design doc registry-manifest-design.md.

Consolidated docs 56 -> 28: deleted dated handoffs/resumes/transcripts and
superseded trackers (content folded into the master plan or already in memory).
Kept all evergreen design/reference docs + ADRs (the master links them).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-21 05:11:32 -04:00

2.5 KiB

Raw Blame History

Archipelago — agent guide

🚩 TOP PRIORITY (until production testing passes)

Read docs/PRODUCTION-MASTER-PLAN.md first. It is the authoritative plan and overrides ad-hoc direction until the production test gate is green. Goal: a world-class, developer-ready app platform where every app is manifest-driven, manifests ship via the signed registry (not OTA disk files), and third-party developers publish apps via an external/decentralized registry — all rootless, secure, robust, and 100%-uptime-capable.

Detailed sub-plans (all linked from the master):

App platform / packaging phases + security model → docs/APP-PACKAGING-MIGRATION-PLAN.md
Registry-distributed manifests (in progress) → docs/registry-manifest-design.md
External/decentralized marketplace for devs → docs/marketplace-protocol.md
Current per-app state → docs/app-registry-status-2026-06-21.md
Production test gate (exit criterion) → tests/lifecycle/TESTING.md

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. install_immich_stack (hardcoded podman run + sudo chown) 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 (.228, then .198) before any tag.

Build / verify

Rust workspace root is core/ (no Cargo.toml at repo root). 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 (build can silently no-op).
App manifests load from disk on nodes at /opt/archipelago/apps/*/manifest.yml (today); the goal is to distribute them via the signed catalog instead.

Production test gate (definition of done)

tests/lifecycle/run-20x.sh green across install / UI / stop / start / restart / reinstall / reboot-survive / archipelago-restart-survive / uninstall — 20× on .228 AND .198. Until green, the master plan is the priority.