Archipelago should let an owner open a real terminal, resume previous work,
configure their system, and ask a preinstalled coding agent to build an app that
looks and behaves like Archipelago. The experience must work from the dashboard,
local console, and SSH, with the same tools and discoverable commands.
The user requirements are:
- Bring Omarchy's initial setup and development capabilities to Archipelago.
- Ship Codex ready to launch, with guided personal authentication.
- Make closing and resuming terminal sessions easy and reliable.
- Ship local skills that help agents modify the system and build apps using the
actual developer documentation.
- Make visual and interaction consistency an enforced part of app creation.
- Plan in a separate worktree, without conflicting with current release work.
The companion [agent design system plan](archipelago-agent-design-system-spec.md)
defines the shared UI kit, agent workflow, app templates, and visual acceptance.
That work is a dependency of the app-building experience, not finishing polish.
## Product outcome
On a newly installed node, Terminal opens to a usable shell with a small welcome
panel offering Setup, Resume, Build an app, Work on Archipelago, and Help. The
shell is immediately usable; onboarding is dismissible and resumable. Existing
owners get the same environment through an upgrade that preserves their files,
configuration, credentials, and uninstall decisions.
A representative first session:
1. Open Terminal from the dashboard or launch it locally.
2. See the node, workspace, account, and any existing sessions clearly identified.
3. Run the setup guide, select editor/toolchains, and sign in to Codex.
4. Choose Build an app and describe the app. The agent loads Archipelago's app
and design guidance and starts from the maintained starter.
5. Review a working local preview, including mobile and failure states.
6. Close Terminal while a build or agent task runs.
7. Reopen it, select the named session, and continue where it was left.
8. Install the candidate through the existing app lifecycle on a chosen test
node, then contribute through ngit when publication is requested.
## Current implementation and gaps
These are source findings, not live-node acceptance results.
| Surface | Current source | Required change |
| --- | --- | --- |
| Dashboard terminal | `neode-ui/src/components/CLIPopup.vue`: development-only simulated commands; production SSH instructions and a literal default password | Real terminal and session picker; connection information derived from actual setup state |
| Terminal state | `neode-ui/src/stores/cli.ts`: open/close boolean | Server-owned session inventory; client UI state independent of process lifetime |
| Keyboard | `neode-ui/src/App.vue`: global F and other shortcuts; `useModalKeyboard.ts` captures arrows and Escape | A terminal focus boundary so shell, editor and agent keys reach the PTY |
| Console setup | `image-recipe/archipelago-scripts/archipelago-menu.sh`: legacy menu, eager installer-tool installation, direct container setup | Shared command catalog and current orchestration; opening a menu does not install software |
| Shell onboarding | `scripts/welcome-banner.sh`: banner and SSH information, including literal default password; may wait for networking | Short local welcome, accurate access state, fast offline shell startup |
| ISO | `image-recipe/build-debian-iso.sh` invokes a relocated copy of `_archived/build-auto-installer-iso.sh` | Integrate the actual active build path, despite its archived filename |
| Upgrade | `scripts/self-update.sh`, `core/archipelago/src/bootstrap.rs`, runtime assets | One versioned environment payload and repeatable migration shared with ISO |
| Existing development access | Pinned ngit installer and GitWorkshop app already exist | Reuse these; keep ngit the contribution platform |
| App packaging | `docs/app-developer-guide.md`, manifest spec and Rust parser | Turn existing contracts into agent workflows, validated starters and development commands |
| Design | Dashboard CSS/Tailwind, reusable Vue components, separate AIUI CSS | Extract and document a coherent shared contract; see companion plan |
The backend uses Hyper/Tokio and existing WebSocket handlers; the developer guide
currently calls it Axum. Several contributor documents also show unrestricted
`cargo test`, conflicting with `AGENTS.md`. Correct those documentation examples
before packaging them as agent instructions. On a live node, backend execution
must use `scripts/test-backend-isolated.sh`.
## Omarchy reference and capability mapping
Research baseline: the official [Omarchy repository](https://github.com/omacom/omarchy),
formerly reached through `basecamp/omarchy`. Its default branch was `quattro` at
| Deferred provisioning for another owner | Leave personal developer credentials unset; first owner completes setup | Core |
| Separate packaged defaults, user finalization and migrations | Versioned system payload, per-user setup receipts, explicit reset with backup | Core |
| First-login welcome, shortcuts, network/update guidance | Welcome and searchable help shared by terminal and dashboard | Core |
| Bash completion, history, prompt, fuzzy finding and directory navigation | Bash, completion, Starship, fzf and zoxide with readable console fallback | Core |
| File/search/system tools | ripgrep, fd, bat, eza, jq, less, man, tldr, btop and fastfetch | Core |
| Terminal selection: Foot, Alacritty, Ghostty, Kitty | Browser terminal plus console/SSH; local emulator adapters compatible with the actual kiosk display stack | Browser/console core; native choices follow-on |
| tmux sessions, panes, developer layouts | Named persistent sessions and editor/agent/shell layouts; same sessions accessible by SSH | Core |
| Neovim and selectable editors | nano available immediately; maintained Neovim profile and editor preference; GUI editors when desktop support exists | Core terminal editors; GUI follow-on |
| Mise development environments | Versioned Node/npm, Rust, Python/uv profiles first; project-local versions | Core |
| Ruby/Rails, Bun, Deno, Go, PHP/Laravel/Symfony, Elixir/Phoenix, Java, Zig, OCaml, .NET, Clojure, Scala | Optional profiles in the same installer catalog, each with architecture and verification metadata | Parity follow-on |
| Git, lazygit, GitHub CLI | Git/lazygit and ngit/GitWorkshop first-class; gh optional for other upstream projects | Core |
| Browser, terminal, editor and dictation defaults | Editor/agent/terminal choices first; browser/dictation surfaced when relevant to the device | Core subset; follow-on adapters |
| Themes, fonts, background and prompt | Shared Archipelago tokens and terminal palette; preserve owner customization | Core |
| Shell plugins and customization hooks | Versioned extension points and documented user overrides; dashboard extensions require a separate supported contract | User overrides core; plugins follow-on |
| Package, TUI, web-app and development installation menus | Curated tool catalog plus existing Archipelago app catalog; distinguish developer tools from managed apps | Core |
| Commercial services, GUI apps, gaming, Windows VM | Individual optional app/desktop integrations, inventoried as a separate parity backlog | Follow-on, not preinstalled on nodes |
| Update, reset, snapshots, direct boot | Integrate Archipelago update/recovery choices; explicit reset scope and backup | Core existing operations; new boot/snapshot features follow-on |
This is a core release criterion, including the first usable terminal milestone.
Session execution lives on the node in a dedicated, supervised user environment.
Use tmux as the initial persistence engine; a browser WebSocket is an attachment,
not the owner of the shell process. Keep the tmux server and worker scope outside
the dashboard/backend service's kill group. Ordinary manager deployment must not
tear down developer sessions.
Prefer one tmux server/socket and supervised process scope per managed session,
so ending one session cannot kill a shared server containing other work. Keep
those sockets private to the developer account. SSH and local-console resume use
the same session registry and attachment helper rather than guessing tmux names.
Cross-device resume refers to browsers connected to the same node; moving live
processes between different nodes is outside this contract.
| Event | Required behavior |
| --- | --- |
| Close terminal panel, navigate away, close tab, kill browser | Detach; shell, build and agent continue |
| Reopen Terminal | Show running and recent sessions; Resume most recent available in one action; do not auto-create duplicates |
| Switch session | Detach the old view and attach the selected session |
| Network drop or mobile sleep | Show Reconnecting; reauthenticate if needed, then attach to the existing session |
| Dashboard reload or backend restart | Session survives; rediscover it from node state |
| Second browser/device | Same authenticated owner sees sessions; explicit transfer of input control |
| Logout/session expiry | Revoke browser attachments immediately; background work remains; a fresh owner login is required to reattach |
| Explicit End session | Confirm when work is active, terminate that session's process scope, record ended state; do not remove its files |
| Shell exits | Show ended status and exit information where available; offer a new shell in that workspace |
| Broker crash | tmux/process scope survives if its supervisor survives; reconcile inventory, without replaying input |
| Node reboot/power failure | Processes stop. Keep workspace/session metadata and offer Reopen workspace and Resume Codex conversation; never label this a live process resume |
The picker shows a user-editable name, workspace, creation/last-attachment time,
Running/Detached/Ended/Interrupted state, and optional pinned status. Scope every
entry to a node and stable owner identity. LocalStorage may remember selection;
it is never the authoritative session registry.
Persist metadata atomically under the workspace account's private state directory.
these flows. Do not collect credentials in an Archipelago transcript or copy the
node's wallet identity into agent configuration. The UI reports Installed,
Sign-in required, Ready or Error based on actual results.
Honor the user's Codex configuration, permissions and model choice. A launcher
selects a workspace and skill context; it does not inject unrestricted execution
flags. A local skill is local guidance, not a claim that Codex inference is local.
Explain the selected provider and what workspace content may be sent to it during
setup, alongside any self-hosted alternative.
During an ordinary disconnect, resume the same running Codex process in tmux.
After an ended session or reboot, offer the official `codex resume` workflow in
the matching workspace. Do not automatically reissue the last task. Preserve
agent history/configuration separately from disposable build caches, and keep
credentials out of ordinary app export/support bundles.
## Local skills that enable real work
Ship a small coordinated skill family with one obvious entrypoint. Keep the
instructions actionable and references focused; avoid copying the whole manual
into every prompt. The skill-creator guidance informs this structure: precise
triggers, reusable resources, progressive disclosure and behavioral validation.
| Skill | Trigger and outcome | Required resources |
| --- | --- | --- |
| `archipelago` | Configure, troubleshoot or change an Archipelago system; route app/UI work to the companion skills | System map, command catalog, config ownership, task recipes and recovery |
| `archipelago-app` | Build, package, test or update an Archipelago app using the developer contract | Developer docs, manifest schema, starter assets, launch/auth/signer examples, lifecycle checks |
| `archipelago-design` | Create or change an Archipelago UI, including apps, setup and Terminal | Shared tokens/components, pattern gallery, app shells, screenshots and visual checks |
For a system task, the agent should locate the correct config/operation, inspect
current state, make the requested scoped change, validate it and report the result.
Teach recipes for networking, SSH, tool installation, terminal preferences,
service diagnosis and supported app configuration. Prefer maintained management
commands; when direct configuration is necessary, explain owned versus generated
files, the minimal affected service and reversal. Repository changes go into a
separate branch/worktree; installed-node changes target an explicitly identified
node and retain a scoped backup. Planning requests stay planning requests.
For an app task, the agent reads `docs/app-developer-guide.md` and
`docs/app-manifest-spec.md`, follows the design plan, chooses a starter, implements
the requested behavior, validates it and supplies a runnable preview. Package
with pinned images/build contexts, rootless execution, declared storage/secrets,
health checks and truthful interfaces. Include HTTP/HTTPS, iframe/Companion,
first-run credentials and Nostr signer behavior where relevant. Publication and
live installation are distinct requested steps.
The skill must explain non-obvious runtime facts: manifests copied only into
`/opt/archipelago/apps` are replaced at backend start; runtime payload promotion
and signed-catalog precedence matter. Installed status is not launch readiness.
Pre-catalog testing must not replace the signed catalog. Test uninstall/reinstall
with data preservation on a disposable target. Use `AGENTS.md` over stale testing
examples. Payments, wallets and uninstall decisions retain their existing
invariants; a generic repair must not reset them.
Proposed source layout: `skills/archipelago*` plus a versioned reference bundle and
app starter assets. Ship managed copies under a versioned read-only system path
and expose one discoverable link per skill per agent. Current official
| 1A | Persistent terminal service and browser/SSH attachment | Real shell + Codex TUI; close/reopen, network loss, manager restart and ownership tests |
| 1B | Shared design foundation, gallery and starter | Dashboard-derived tokens/components; consistent app at desktop/mobile sizes |
| 2 | Core setup/tool payload and Codex onboarding | Fresh/offline/upgrade/retry matrix; correct account state and user override preservation |
| 3 | System/app/design skills and app-development commands | Realistic agent tasks produce correct scoped system changes and a consistent packaged app |
| 4 | Integrated candidate qualification | Real node and Companion resume/design acceptance, resource tests and packaged ISO/OTA checks |
| 5 | Remaining Omarchy parity adapters | Each inventory row supported or explicitly retained with reason and acceptance target |
1A and 1B can be independent implementation workstreams once phase 0 contracts
are agreed. This planning session has not launched implementation agents.
App-generation functionality is incomplete until 1B and the skill acceptance pass.
Expected code boundaries: Terminal UI/store/keyboard handling; new terminal
service and typed management routes; shared CLI/setup catalog; versioned tool and
skill packaging; design-kit extraction; app starter/validation; ISO and OTA
integration. Keep each in a focused contribution. Coordinate shared frontend
styles, backend routing and packaging files before implementation starts.
## Acceptance criteria
| ID | Required proof |
| --- | --- |
| TERM-01 | Real PTY supports editors, completion, colors, Unicode, signals and Codex; no fake production commands |
| TERM-02 | Start a long-running fixture and edit a file, close Terminal/tab/browser, reopen and resume the exact session and process |
| TERM-03 | Offline/reconnect, mobile sleep, frontend reload, backend restart and attachment-service restart do not duplicate execution |
| TERM-04 | A second device resumes after owner authentication; writer transfer is atomic; another identity cannot list/attach/terminate |
| TERM-05 | End session stops only its process scope; logout revokes access; neither operation deletes workspace files |
| TERM-06 | Reboot retains workspace metadata, labels interrupted sessions accurately and offers Codex conversation resume without rerunning commands |
| TERM-07 | Terminal keyboard ownership, focus, text selection, paste, resize, mobile keyboard and screen-reader mode work |
| AUTH-01 | Missing/expired/replayed grants, cross-origin sockets, forged proxy headers and app/guest credentials fail before shell I/O |
| AUTH-02 | Developer user cannot read production wallets/secrets or control production container sockets; authorized system workflow works |
| SETUP-01 | Fresh install and existing-node upgrade deliver the same core capabilities; Codex version works before network access |
| SETUP-02 | Failed download, package lock, low disk, reboot and concurrent setup recover without false completion or broken existing tools |
| SETUP-03 | Existing dotfiles, editor/agent choices, credentials, app data and uninstall decisions are preserved |
| AGENT-01 | A system-change task uses the correct operation/config, verifies its result and preserves unrelated services |
| AGENT-02 | An app-building task follows actual developer docs and passes manifest/build/launch/lifecycle checks |
| DESIGN-01 | Agent-built apps satisfy the companion design plan using shared assets/components, including failure and mobile states |
| PKG-01 | Exact candidate OTA and ISO contain matching tools, docs, skills and UI-kit versions; restore previous payload without removing user work |
Backend unit execution uses `scripts/test-backend-isolated.sh`. PTY/process and
account-isolation integration tests run in disposable users/VMs, not a funded
production node. Terminal continuity tests use observable process IDs/output and
file checks, not a mocked “resumed” label. UI tests include 320/390/768/1440 pixel
layouts, landscape, enlarged text and actual Companion input on a device.
Record source tests, disposable integration, actual-node acceptance and packaged
artifact results separately. Preserve unfinished requirements in
`docs/post-1.8.22-regressions-20261001.md` and the current release acceptance ledger;
this feature plan closes none of them. Later publication follows ngit review and
merge, then identical accepted main/tag objects on both ngit and Gitea, with the
required mirror checks. No release version or publication date is reserved here.
## Decisions to resolve during design review
The proposed defaults are a dedicated developer account, tmux persistence,
minimal terminal origin, bundled Codex, Bash, and a Vue starter with portable
design tokens. The implementation review must settle terminal-origin/certificate
handling on every supported ingress, the supported operator-shell model, the
exact first-release tool profile, and the approved visual baseline. Native
terminal emulators and the broader desktop parity backlog need separate device
compatibility decisions. None of these questions prevents reviewing this plan.
