docs: plan terminal sessions, developer setup and agent design system

2026-10-09 07:15:26 -04:00
parent 2cb1bae5ce
commit 940b28dd9b
2 changed files with 792 additions and 0 deletions
@@ -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.
@@ -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 <id>` | Discover and attach to existing work |
 | `archy dev setup <profile>` | Install a declared, versioned toolchain profile |
 | `archy agent` | Launch selected agent in the selected workspace |
 | `archy app new <id>` | Create from a maintained Archipelago starter |
 | `archy app check <path>` | Manifest, build, integration and design checks |
 | `archy app preview <path>` | Start an isolated local preview and return its URL |
 | `archy app install <path> --node <target>` | Explicit candidate deployment through supported orchestration |
 | `archy system <operation>` | 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.