From 940b28dd9b3769fa3befa45d2387287854425124 Mon Sep 17 00:00:00 2001 From: archipelago Date: Fri, 9 Oct 2026 07:15:26 -0400 Subject: [PATCH] docs: plan terminal sessions, developer setup and agent design system --- docs/archipelago-agent-design-system-spec.md | 268 ++++++++++ docs/terminal-developer-environment-spec.md | 524 +++++++++++++++++++ 2 files changed, 792 insertions(+) create mode 100644 docs/archipelago-agent-design-system-spec.md create mode 100644 docs/terminal-developer-environment-spec.md diff --git a/docs/archipelago-agent-design-system-spec.md b/docs/archipelago-agent-design-system-spec.md new file mode 100644 index 00000000..28aa6494 --- /dev/null +++ b/docs/archipelago-agent-design-system-spec.md @@ -0,0 +1,268 @@ +# Archipelago design system for agent-built apps + +Status: planning draft, 2026-10-09. Companion to the +[terminal and developer environment plan](terminal-developer-environment-spec.md). +No tokens, components, templates or installed skills are changed by this draft. + +An agent asked to build an Archipelago app should produce an app that belongs in +Archipelago by construction. Give it a maintained component kit, runnable +starters, documented screen patterns and visual references. A skill telling it +to “use glassmorphism and orange” is insufficient. + +The same foundation should drive Terminal, setup screens, first-party apps and +newly generated apps. Existing third-party applications keep their own product UI; +their Archipelago entry, launch and integration surfaces follow this contract. + +## Evidence and design authority + +At repository baseline `2cb1bae5`, the dashboard's design is distributed across +`neode-ui/src/style.css`, `neode-ui/tailwind.config.js`, Vue components, and the +short standards section of `docs/developer-guide.md`. AIUI maintains a separate +token/style definition in `aiui/packages/app/src/styles/main.css`. + +| Existing rule | Source observation | Contract to preserve or resolve | +| --- | --- | --- | +| Dark controls | Dashboard sets `color-scheme: dark` and explicit select colors | Dark baseline, including native controls | +| Glass cards | `.glass-card`: black at 0.65 alpha, white border at 0.18, 16px radius | Preserve the established surface, not a generic frosted card | +| Blur | Default card blur 18px; dashboard contexts deliberately suppress backdrop blur to avoid rendering corruption | Context-aware surface variants; never reintroduce blanket blur | +| Buttons | `.glass-button`: 44px minimum, 12px radius; established focus/hover/pressed variants | Reusable buttons with full interaction states | +| Accent | Dashboard focus/action uses `#fb923c`; AIUI accent is `#F7931A` | Named semantic tokens with explicit mapping; do not silently choose one for everything | +| Typography | Dashboard body uses Avenir Next/system fallback, headings have bundled Montserrat; AIUI uses Inter/system fallback | Approved roles, metrics, fallback behavior and licensed assets | +| Spacing | Tailwind extends a 4px grid | Shared spacing scale and layout examples | +| Search | Existing search is 40px on desktop, 52px below the 920px breakpoint; right clear control retains focus | Shared search component and documented responsive behavior | +| Card actions | Existing CSS places full-width actions at the bottom on desktop and mobile | Preserve this layout in generated card screens | +| Modal layout | `BaseModal.vue`: pinned title/footer with independently scrolling content | Shared dialog shell with tested focus and Back behavior | +| Mobile layout | Dynamic viewport, safe-area and audio-player offsets already exist | One documented inset contract; prevent double padding in embedded apps | +| Success | Shared `PaymentSuccessPane.vue` and `IdentitySuccessPane.vue` express branded completion | Reuse the relevant pattern only when its completion condition is actually met | +| Embedded canvas | AIUI embedded mode is transparent; standalone has its own background | Host owns wallpaper; apps choose explicit embedded/standalone mode | + +These observations seed a visual audit; they do not make every legacy style a +rule. Capture representative current screens in the running supported UI before +extracting components. Approve Home, Apps, app detail, Settings, forms/dialogs, +list/detail screens, Terminal and mobile examples as reference baselines. + +The source of truth becomes versioned tokens plus components and pattern docs. +Screenshots illustrate that contract and detect drift; they do not replace it. +Existing dashboard and AIUI differences need explicit migration decisions. +Preserve the current look first and make intentional design improvements visible +in review rather than introducing them incidentally through an app template. + +## Deliverable shape + +Proposed layout, to be finalized against repository packaging conventions: + +```text +packages/archipelago-design/ + tokens/ semantic definitions and generated CSS/JSON + styles/ scoped foundations and non-Vue component classes + assets/ approved fonts, icons and licenses +packages/archipelago-ui/ + components/ Vue components with documented states + patterns/ app shells and composed screen patterns +docs/design-system/ + index.md decision guide and version compatibility + foundations.md typography, color, surfaces, spacing, motion + components.md usage, states, accessibility, stable imports + patterns.md complete screen composition and behavior + examples/ reference captures and their matching source +examples/archipelago-app/ + ... working starter with manifest and tests +skills/archipelago-design/ + SKILL.md concise trigger, routing and workflow + references/ versioned design index and evaluation rubric +``` + +Build an offline component gallery with the UI kit. Every example links to its +source, token usage and applicable app pattern. A developer can run the gallery +without a node session or provider API key. It must show loading, empty, error, +success, disabled, focused, hovered and pressed states, not only the ideal screen. + +Publish packages only as part of an explicitly authorized later implementation +workflow. Until then these names and paths describe proposed deliverables. + +## Token contract + +Use framework-neutral CSS custom properties generated from a single definition. +Vue components and any Tailwind adapters consume the same values. Prefix tokens +with `--archy-`; do not expose arbitrary dashboard-global selectors to apps. + +| Token family | Required coverage | +| --- | --- | +| Color | Canvas, card, inset, overlay, border, text primary/secondary/muted, interactive accent, focus, selected, success, warning, danger and info | +| Typography | Body, heading and monospace families; type scale, weights, line heights and numeric alignment | +| Space and size | 4px-based scale, page gutters, content widths, control heights, touch targets and icon sizes | +| Shape | Card, dialog, input, button and pill radii | +| Elevation | Card/overlay shadows, border strengths, blur-permitted and no-blur surfaces | +| Motion | Durations/easing, permitted hover/press transitions and reduced-motion equivalents | +| Layering | Header, navigation, menu, popover, modal and toast layers with ownership rules | +| Viewport | Host-provided safe areas, keyboard viewport, navigation/audio offsets and embedded mode | +| Terminal | Canvas, foreground, cursor, selection and a readable 16-color ANSI palette | + +Make brand orange and interactive/focus orange distinct roles if preserving both +existing values. Status colors must communicate meaning alongside text/icons. +Name action variants by purpose: the existing orange “warning” class also serves +primary actions, so exporting that name unchanged would teach the wrong semantics. + +Typography must have predictable dimensions on Debian, Android and desktop +browsers. Use only redistributable local font assets. Referencing Avenir or Courier +New in a fallback stack does not license bundling those fonts. Freeze a tested +body/heading/mono choice and line-height matrix in the visual review; do not let +each generated app choose its own fonts or fetch a font CDN. + +Check contrast on actual composited surfaces and the brightest/darkest supported +backgrounds. Opacity values or CSS comments alone do not establish accessibility. +Small text must remain readable, and focus must remain visible where current +global styles suppress outlines. Low-power/no-backdrop-filter fallbacks retain +the same hierarchy and usable contrast. + +## Components and patterns agents can reuse + +Extract reusable behavior from existing code; avoid giving agents a second +lookalike library with slightly different interactions. Package components +without dashboard stores, router assumptions, privileged RPC clients or secrets. +Use adapters for integrations owned by the host. + +| Foundation | First required components | Existing reference | +| --- | --- | --- | +| Structure | AppShell, PageHeader, Section, Card, InsetPanel, ActionRow | Dashboard CSS, app headers, card action rules | +| Controls | Button, IconButton, TextField, PasswordField, Select, Toggle, SearchField, SegmentedControl | `ToggleSwitch.vue`, `PasswordRevealInput.vue`, `AppSearchField.vue` | +| Navigation | Tabs, Breadcrumbs, Back action, contextual menu | Dashboard navigation, `BackButton.vue`, Cloud menus | +| Feedback | StatusBadge, EmptyState, Skeleton, Progress, InlineError, Toast | `EmptyState.vue`, `SkeletonCard.vue`, `ToastStack.vue`, existing progress patterns | +| Dialogs | Dialog, ConfirmDialog, credential handoff | `BaseModal.vue`, `AppConfirmModal.vue`, `AppCredentialInterstitial.vue` | +| Data | ListRow, responsive table/list, detail key/value row, copy action | Existing app lists, `CopyButton.vue` | +| Terminal | TerminalShell, SessionList, SessionRow, ConnectionStatus, mobile key strip | New consumers of the same foundation | + +Each public component documents supported props/events/slots, sizing, keyboard +behavior, accessibility, states and examples. Shared helpers must respect context: +the current modal helper captures Escape and arrow keys, which is unsuitable +for a terminal, editor or other widget that owns those keys. Fix/reuse that +behavior through explicit contracts rather than blindly wrapping Terminal in it. + +Provide composed patterns for: + +- A searchable collection with filters, list/grid view, empty state and bottom + card actions. +- A detail screen with back navigation, metadata, status and primary action. +- Settings grouped by task, with visible validation, save progress and retry. +- A multi-step setup flow with skip/resume, honest progress and recovery. +- First launch and credential handoff, including apps with their own login. +- A destructive confirmation that names its target and data-preservation effect. +- A session picker and terminal that clearly distinguish Close from End session. + +Copywriting is part of the contract: concise task labels, useful error recovery, +explicit pending versus complete states, no raw internal exception as the sole +user message, and appropriate units/time formatting. Technical detail is +available on demand. App-generated progress must reflect actual work. + +## App shells and host integration + +Supply a preferred Vue/TypeScript starter and a small portable HTML/CSS example. +Existing React or other framework applications consume the tokens/styles and +behavior contracts; do not require a framework rewrite to package an app. +Full additional framework bindings follow actual demand and have their own +acceptance, rather than presenting CSS classes as equivalent accessible widgets. + +New starters include local assets, locked dependencies, scripts, manifest, +container definition, health check, persistent-data example, tests and a complete +reference screen. A starter must build and run from its copied location without +monorepo-only aliases. It cannot require fetching current dashboard CSS at runtime. + +The host integration contract defines: + +- Explicit standalone versus embedded appearance. Embedded apps use a transparent + canvas where appropriate; they do not add a duplicate wallpaper or navigation + shell. Standalone mode still has a complete, readable canvas. +- Versioned, non-secret theme/inset messages if runtime synchronization is needed. + Validate sender origin, source window and payload; no wildcard privileged + message bridge. An app must remain usable with no host handshake. +- Exactly one owner for top/bottom safe-area padding and fixed player/navigation + clearance. Test the actual Companion WebView, not just a mobile screenshot. +- Existing launch interfaces and app-gate behavior from the developer docs. + Asset URLs work under their supported base path and HTTP/HTTPS entry points. +- Nostr signer, media controls and credential handoff only through their supported + APIs. Visual kit installation does not give an app host management access. + +Package tokens/components with the app's pinned kit version. Evolve them with +documented compatibility and migrations. Runtime theme values may be forwarded +through the agreed contract; runtime JavaScript/CSS replacement is not the update +mechanism. A platform update must not silently break every installed app. + +## Agent workflow + +The app skill always routes new UI work through `archipelago-design`. The system +skill does the same when a system modification affects a visible screen. A +backend-only request loads no unnecessary design material. + +For relevant tasks the agent: + +1. Reads the design index, supported kit version and matching pattern; identifies + existing components before creating new ones. +2. Inspects the reference screen and its source, then selects the closest starter. +3. Implements the requested behavior using shared components and semantic tokens. +4. Exercises normal, loading, empty, invalid, failed and successful states. +5. Renders standalone and embedded previews at the required viewports; inspects + captures, keyboard behavior and actual component geometry. +6. Runs app checks and supplies the working preview, component/token provenance, + results and any deliberate design exceptions. + +Make that loop easy: `archy app new`, `archy app preview` and `archy app check` +should supply the starter, preview fixtures and relevant checks. Those are +proposed tools in the terminal plan, not currently implemented commands. +Ordinary changes within the requested task proceed through this loop without +requiring approval for every edit. A new shared design primitive or intentional +departure is identified in the review, with its use case and visual evidence. + +The skill should tell agents how to find and use the design system, not make +them recreate it from a long list of adjectives. Keep the entrypoint concise; +conditional references cover forms, layout, terminal interaction, media and +signer flows. Templates and screenshots belong in reusable assets, not prose +that the agent has to transcribe. + +## Design conformance and definition of done + +Combine targeted static checks, interaction tests and visual review. Static +checks cannot prove a coherent design; screenshots cannot prove an accessible +or correct interaction. + +| Gate | Acceptance | +| --- | --- | +| Shared foundation | New UI imports the approved kit/version; bespoke color/font/radius/z-index values need a named exception, with allowances for content such as charts and user imagery | +| Visual hierarchy | Reference-matched page width/gutters, type roles, card surfaces, action placement and density | +| Responsive layout | 320, 390, 768 and 1440px widths plus phone landscape; 200% text zoom; no accidental horizontal page overflow | +| Input | Keyboard-only use, visible focus, sensible tab order, labels, dialog focus containment/restoration and Back behavior; terminal keys remain intact | +| Touch | 44px usable targets for new mobile controls, reachable persistent actions, no essential hover-only interaction | +| States | Loading, empty, offline, denied, validation error, retry and success demonstrated with deterministic fixtures | +| Appearance | Dark native controls, foreground/background contrast, reduced motion, no-blur fallback and locally available fonts | +| Host modes | Embedded/standalone, HTTP/HTTPS where supported, software keyboard, safe areas, audio-player offsets and Companion | +| Runtime truth | Success and readiness only follow actual confirmed results; theme/state changes do not erase form or session work | +| Regression | Shared component changes compared against representative dashboard and app reference captures before release | + +Choose per-component visual-diff tolerances after baseline capture; avoid a +single permissive threshold that conceals layout regressions. Stabilize fonts, +viewport, fixture data and animations. Review intended baseline changes rather +than automatically accepting new screenshots when CI fails. + +Behavioral skill evaluation should use realistic tasks with no hidden design +brief: build a bookmarks app, add a settings form, create an app with first-run +credentials, adapt a non-Vue app, and improve Terminal's session picker. Inspect +the generated artifacts and previews for component reuse, consistent appearance, +correct manifest integration and usable failure states. Repeat on a fresh +environment to ensure success does not rely on this checkout or an agent's +conversation history. + +## Implementation order + +1. Audit representative existing screens; resolve accent/typography/blur and + embedded-mode decisions; record the approved reference set. +2. Extract semantic tokens and the first components while preserving current + dashboard rendering. Migrate a small representative slice to prove parity. +3. Build the offline gallery, app shell and working starter. Use Terminal/setup + as real consumers so the foundation is exercised immediately. +4. Package the app/design skills with matching docs and assets; run realistic + generation tasks against the starter and gallery. +5. Add scoped conformance checks to app validation and qualification; migrate + additional first-party surfaces incrementally. + +App generation cannot be called complete while agents still invent the visual +foundation. Completion means a new agent, a new workspace and an ordinary app +request reliably produce a working, recognizably Archipelago result. diff --git a/docs/terminal-developer-environment-spec.md b/docs/terminal-developer-environment-spec.md new file mode 100644 index 00000000..fa40485c --- /dev/null +++ b/docs/terminal-developer-environment-spec.md @@ -0,0 +1,524 @@ +# Archipelago terminal and developer environment plan + +Status: planning draft, 2026-10-09. No runtime implementation or installation is +part of this change. Repository baseline: `2cb1bae5ce244d387679f90951d62fd030ebf228`. + +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 +[`fcf9eeb5c454739f3f23cdfd7d57d77b12961025`](https://github.com/omacom/omarchy/tree/fcf9eeb5c454739f3f23cdfd7d57d77b12961025). +The latest published release returned during research was +[v4.0.4](https://github.com/omacom/omarchy/releases/tag/v4.0.4), published September 15, +2026, resolving to `c668141e9c42b13c80c9ca4ea108e11708c5e8a5`. +The inventory below describes the pinned default-branch source; it does not +assert that every item is present in that published release. + +“All setup capabilities” means explicit disposition of the setup surface, not +silently omitting desktop-specific features. The proposed core release covers +the terminal, system setup and development rows below. Hardware/desktop options +remain named follow-on work; completion of the core is not full Omarchy parity. + +| Omarchy capability | Proposed Archipelago equivalent | Delivery | +| --- | --- | --- | +| Owner, keyboard, hostname, timezone, optional Git name/email | Resume existing node onboarding; configure developer identity separately from appliance identity | Core | +| 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 | +| Lazy agent launchers | Codex actually bundled; optional adapters for other agent CLIs | Core Codex; provider expansion follow-on | +| Default-agent selector and starter prompts | Codex selected initially for a fresh setup; preserve existing preference; system/app/design entry prompts | Core | +| Agent account selection and usage panel | Explicit account context and supported login status; manual account profiles before considering usage automation | Follow-on | +| Local model tools | Integrate the existing Ollama app and compatible provider setup; downloads and model resource needs visible | Follow-on | +| Bundled system and app-building skills | Archipelago system, app and design skills with offline references and templates | Core | +| Development databases: MySQL, PostgreSQL, Redis, MongoDB, MariaDB, MSSQL | Scoped rootless Podman development recipes, isolated ports/data and generated credentials | Core PostgreSQL/Redis-compatible recipe; remaining recipes follow-on | +| Container tooling | Existing rootless Podman; documented Compose compatibility where tested | Core | +| DNS, Wi-Fi, network QR, SSH daemon and SSH agent setup | Existing network/SSH controls exposed through shared setup operations, with accurate connection details | Core | +| Fingerprint, FIDO2 and privilege preferences | Hardware-aware account-security setup; no copied Arch PAM configuration | Follow-on | +| Monitors, keyboard bindings, input, XCompose | Kiosk/console equivalents through existing system configuration; desktop-specific adapters separately | Core console basics; desktop follow-on | +| 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 | +| Hardware detection and vendor fixes | Existing Archipelago hardware configuration, capability detection and separately qualified device fixes | Core detection; device adapters follow-on | +| Crash diagnosis skill | Sanitized diagnostics with an explicit handoff to the chosen agent; preserve source versus live evidence | Follow-on | + +Primary source routes for the inventory: + +- [Provisioning and file layout](https://github.com/omacom/omarchy/blob/fcf9eeb5c454739f3f23cdfd7d57d77b12961025/docs/file-layout.md), + [setup form](https://github.com/omacom/omarchy/blob/fcf9eeb5c454739f3f23cdfd7d57d77b12961025/install/provisioning/setup-form.sh), + [setup and installation menu](https://github.com/omacom/omarchy/blob/fcf9eeb5c454739f3f23cdfd7d57d77b12961025/default/omarchy/omarchy-menu.jsonc). +- [Base packages](https://github.com/omacom/omarchy/blob/fcf9eeb5c454739f3f23cdfd7d57d77b12961025/install/omarchy-base.packages), + [shell initialization](https://github.com/omacom/omarchy/blob/fcf9eeb5c454739f3f23cdfd7d57d77b12961025/default/bash/init), + [terminal and tmux](https://github.com/omacom/omarchy/blob/fcf9eeb5c454739f3f23cdfd7d57d77b12961025/manual/15-terminal.md). +- [Development profiles](https://github.com/omacom/omarchy/blob/fcf9eeb5c454739f3f23cdfd7d57d77b12961025/bin/omarchy-install-dev-env), + [agent setup](https://github.com/omacom/omarchy/blob/fcf9eeb5c454739f3f23cdfd7d57d77b12961025/install/user/mise.sh), + [agent launcher implementation](https://github.com/omacom/omarchy/blob/fcf9eeb5c454739f3f23cdfd7d57d77b12961025/bin/omarchy-mise-install), + [development databases](https://github.com/omacom/omarchy/blob/fcf9eeb5c454739f3f23cdfd7d57d77b12961025/bin/omarchy-install-docker-dbs). +- [System skill](https://github.com/omacom/omarchy/blob/fcf9eeb5c454739f3f23cdfd7d57d77b12961025/default/agents/skills/omarchy/SKILL.md) + and [app skill](https://github.com/omacom/omarchy/blob/fcf9eeb5c454739f3f23cdfd7d57d77b12961025/default/agents/skills/omarchy-app/SKILL.md). + +Adapt the workflows to Debian and Archipelago's manifest-driven runtime. In +particular, Omarchy's app skill produces Qt desktop apps; Archipelago's starter +must produce an Archipelago app. Omarchy's agent launchers download tools on use; +the user's requirement here is stronger: Codex must already be installed. Its +database recipes and permission-changing aliases are not defaults to transplant. +Any reused upstream files need their original license notices and provenance. + +## Terminal experience + +Use a real PTY with a bundled terminal renderer, proposed `@xterm/xterm` with +fit/search support. It must run Bash, nano/Neovim, lazygit, tmux and Codex without +special simulated command handling. Exact dependency versions are selected and +locked during implementation qualification. + +The dashboard entry opens a large resizable terminal on desktop and a full-height +surface on mobile. It provides session name, workspace/node context, connection +status, session switcher, New, Resume, Search, copy/paste, font size, fullscreen, +and Close. End session belongs in a separate menu with a clear running-work warning. +Mobile adds an Esc/Ctrl/Tab/arrows key strip and works with the software keyboard. + +Use the shared Archipelago shell/components around an opaque, readable terminal +canvas. Terminal content uses a packaged monospace font with Unicode support; +the console gets an ASCII-compatible fallback. Apply the design plan's focus, +contrast, reduced-motion and safe-area rules. + +While terminal input has focus, F, Escape, arrows, Ctrl+C, Ctrl+D, Ctrl+R, Tab, +editor keys and tmux prefixes belong to the terminal. Closing uses a visible +control or a documented terminal-specific shortcut. Do not reuse the current +modal keyboard handler unchanged. Ctrl+C interrupts the foreground job; Ctrl+D +has normal shell semantics. Focus can move to toolbar controls and back. + +## Persistent sessions and one-click resume + +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. +Record schema version, opaque session ID, owner ID, node ID, boot ID, tmux target, +workspace ID/path, created/attached timestamps and lifecycle state. Treat tmux and +supervised process state as authority for whether a session is still alive. +After a crash, reconcile orphan sessions and interrupted creates before accepting +another create with the same request ID. + +Place workspaces and agent state on durable storage with an explicit ownership, +quota and backup policy; do not consume a small system partition accidentally. +Expose a familiar `~/Work` entrypoint while recording the actual workspace root. +Reconnecting never requires a fresh Git checkout. A missing or unmounted workspace +is a visible recovery state, not permission to create an empty replacement at the +same path. Deleting session metadata and deleting project files are distinct actions. + +Keep bounded in-memory scrollback and restore the current terminal screen from +the surviving tmux attachment. Do not assume client-side scrollback survived. +Reboot persistence covers metadata and saved files; transcript recording is a +separate opt-in setting because terminal output can include credentials. + +Initial proposed limits: eight sessions per owner, one active input controller +per session, a 10,000-line scrollback ceiling plus a byte ceiling, and bounded +per-connection queues. Do not kill detached work because a browser idle timer +expired. Make resource use visible and allow explicit stop/cleanup. Qualify CPU, +memory and disk limits on the smallest supported node before choosing defaults. + +Input is never automatically replayed after reconnect: a lost acknowledgement +does not establish whether Enter or a command reached the shell. Resize events +are idempotent. A newly attached terminal redraws from the current PTY state. +Revoke the previous writer before granting a new writer lease; read-only views +can be a later addition. User labels and working directories must never be +interpolated into shell command strings. + +## Execution and connection architecture + +Proposed components and responsibility boundaries: + +```text +Dashboard terminal entry / SSH / local console + | + authenticated attachment + | +Terminal session service -- session metadata and ownership + | + supervised developer user + tmux + PTY + | + Bash / editor / Codex / project toolchains + | + archy CLI -- existing typed management operations +``` + +Add a small terminal session service with a local Unix-socket control interface. +The existing management backend validates owner authorization and brokers +short-lived attachments; it does not execute arbitrary shell strings in an RPC +handler. Use typed arguments and fixed executable paths for session creation. +An implementation spike must verify PTY allocation, systemd ownership, tmux +reattachment and Codex rendering before committing to the broker library. + +Prefer a dedicated developer Unix account, separate from the existing +`archipelago` service account, with its own home, rootless container storage and +no mounts of production wallets/secrets. Keep the current service account and +data ownership intact. The inspected ISO builder grants the service account broad +passwordless sudo; using that account for a browser shell would grant equivalent +host authority. A new developer account alone is not proof of isolation: test +actual filesystem permissions, sockets, groups and sudo policy. + +Provide an explicit System administration context for system changes. Routine +supported operations should use the same typed management operations as the UI; +arbitrary host-shell administration needs a distinct authenticated operator +session. These boundaries must still permit authorized agents to configure the +system efficiently. Do not require repeated consent for each step of an already +authorized operation, or treat a skill as an access-control mechanism. + +Initial web access is for the node owner. Public app sessions, guests, peer +identities and iframe signers do not imply terminal authorization. Multi-user +workspace sharing is outside the first release; reject unsupported mappings. + +Prefer a dedicated terminal browser origin with a minimal self-hosted bundle, +no app iframes or external scripts, and narrow authenticated handoff from the +dashboard. A same-origin subpage reduces bundle complexity but does not isolate +it from same-origin scripts. Resolve origin, certificate and Companion handling +in the connection spike before shipping. The +[xterm.js integration guide](https://xtermjs.org/docs/guides/security/) specifically +requires application-level WebSocket authentication/origin handling and careful +treatment of terminal output. + +Remote terminal transport requires verified HTTPS/WSS. Existing plain-HTTP +dashboard users get a working secure-terminal entry and SSH alternative; do not +force a global dashboard HTTPS migration as a side effect. Retain current private +management ingress controls, IPv6 support and explicit proxy trust. Never infer +terminal authorization from a forwarded hostname or a private IP alone. + +The protocol contract must include: + +- Create/list/rename/end session operations with CSRF checks, stable owner + binding and idempotent create/end behavior. +- A single-use, short-lived attachment grant bound to session, owner and exact + terminal origin. No reusable dashboard cookie or API key in a query string. +- An authenticated WebSocket with bounded pre-auth time and no PTY output before + authorization; validate Origin separately from CORS and revalidate on reconnect. +- Input bytes, output bytes, resize, connection state and exit messages; bounded + frame sizes, queue backpressure and slow-reader behavior. +- Immediate attachment revocation on logout/credential revocation. No automatic + input replay, automatic command rerun or unauthenticated reconnect. +- Process-group cleanup only for explicit termination; metadata-only audit logs, + excluding command contents, keystrokes, credentials and terminal output. +- Terminal titles/links treated as untrusted text; external links require a user + gesture; clipboard escape sequences cannot silently read/write the clipboard. + +## Setup and tool distribution + +Provide a searchable `archy` CLI and matching setup TUI; the existing +`archipelago` executable remains the backend daemon. All `archy` commands in +this document are proposed interfaces, not commands available today. + +| Proposed command | Purpose | +| --- | --- | +| `archy setup` | Resume setup, show installed/available/deferred items | +| `archy commands --json` | Agent-readable command descriptions, inputs, privileges and side effects | +| `archy doctor` | Read-only, bounded health checks with actionable findings | +| `archy session list` / `resume ` | Discover and attach to existing work | +| `archy dev setup ` | Install a declared, versioned toolchain profile | +| `archy agent` | Launch selected agent in the selected workspace | +| `archy app new ` | Create from a maintained Archipelago starter | +| `archy app check ` | Manifest, build, integration and design checks | +| `archy app preview ` | Start an isolated local preview and return its URL | +| `archy app install --node ` | Explicit candidate deployment through supported orchestration | +| `archy system ` | Discoverable adapters to supported system operations | +| `archy skills status` | Show installed skill/doc/kit versions and local overrides | + +Use one command catalog for the CLI, setup menu and skill references. Each entry +declares what it reads/changes, required privilege, supported machines, expected +output, progress and rollback/recovery behavior. Structured status is for agents; +the human menu uses clear task names. Missing capability is a visible explanation. + +First-run sequence: verify network/time/access status; create or select a workspace; +set optional Git identity and editor; confirm installed tools; offer toolchain +profiles; sign in to Codex; offer a sample app or system task. Users can skip and +resume individual steps. Authentication is never an ISO build step. Run nothing +interactive in noninteractive shells, SCP/SFTP, remote command execution or CI. + +Ship offline: shell essentials, tmux, Git/ngit, Codex binary, local documentation, +skills and design-kit assets. Developer profiles add the complete Node/frontend, +Rust/backend or Python environment and build prerequisites. Offline capability +must be stated precisely: shell/docs/Codex launch can work offline; model calls, +uncached dependencies and external login require connectivity. Plan a full +offline developer bundle as a separate profile if all build caches are required. + +Use signed/versioned payloads and per-architecture hashes. Debian packages and +user toolchains have separate ownership. Core tools update through qualified +releases; opening a shell or running `codex` must not silently update binaries. +Optional tool installs show download size, source, version and progress. Respect +package-manager locks and existing mise/rustup/nvm installations. Do not prune a +binary version beneath a running session. + +State is versioned per machine and per user with pending/running/done/failed/skipped +steps; write completion only after verification. Concurrent setup is serialized. +Preserve user dotfiles through small managed includes and explicit overrides; +preview changes and back up touched configuration during an explicit reset. +Network interruption, disk exhaustion and reboot leave resumable state. + +## Codex integration + +Bundle a qualified stable Codex release for each supported architecture, verified +against a pinned artifact. The official +[CLI installation documentation](https://learn.chatgpt.com/docs/codex/cli) +documents standalone and npm installation; the release implementation should +resolve exact packaging and pin it rather than executing an unversioned installer +on every node. + +Use normal Codex authentication in the developer user's private environment. +Support browser login and the official device-code option for remote/headless +sessions when available; API-key login is another explicit option. The +[authentication documentation](https://learn.chatgpt.com/docs/auth) describes +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 +[Codex skill guidance](https://learn.chatgpt.com/docs/build-skills) supports +repository `.agents/skills`, user `~/.agents/skills`, administrator +`/etc/codex/skills`, and symlinked skill directories. Qualify discovery with the +pinned CLI, including from outside this repository. Preserve local skills and +overrides; avoid duplicate skill names from multiple discovery paths. + +Each bundle records the source revision, supported Archipelago version, manifest +schema and design-kit version. Installed skills use matching offline docs; +repository development uses that checkout's docs. Version mismatch is visible. +Future command names in this plan must not be taught as available until shipped. + +## App creation and design integration + +The default new app is a Vue/TypeScript app using the shared Archipelago UI kit, +with a pinned container build, manifest, icon, tests and local preview. Supply a +framework-neutral CSS/token starter for existing non-Vue apps; port semantic +behavior deliberately instead of depending on dashboard globals. + +Provide a complete example app with a useful list/detail/settings flow, persistent +data, loading/empty/error/success states, a manifest and lifecycle evidence. +Extend it with optional signer/media examples only when those features are used. +The starter must render correctly both embedded and standalone. A third-party +upstream app can retain its own UI; the consistency contract governs the app's +Archipelago wrapper and newly authored Archipelago screens. + +Local development data and ports are separate from production apps. Bind previews +to loopback by default and provide an authenticated preview path for remote users. +Development databases get unique project-scoped names, persistent volumes and +credentials; they must not attach to live Bitcoin/LND or production app databases. + +## Delivery sequence + +| Phase | Deliverable | Exit evidence | +| --- | --- | --- | +| 0 | Finalize command/session contracts, origin/account choice and design baseline | Reviewed wireframes, reference screens, privilege map and pinned Omarchy inventory | +| 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.