feat: add Archipelago agent skills and app starter

2026-10-09 07:31:06 -04:00
parent 940b28dd9b
commit 820df9a196
21 changed files with 484 additions and 0 deletions
@@ -0,0 +1,49 @@
+---
+name: archipelago-app
+description: Build, package, test, and update a manifest-driven Archipelago app using the real app developer contract, rootless runtime, and lifecycle acceptance flow.
+metadata:
+  short-description: Build a real Archipelago app
+---
+
+# Archipelago app development
+
+Use this skill when creating or changing an Archipelago app, manifest, container
+build, app integration, credentials, signer flow, or app preview. Always load
+`archipelago-design` for newly authored UI.
+
+Read [app-contract.md](references/app-contract.md),
+`docs/app-developer-guide.md`, and `docs/app-manifest-spec.md` before coding.
+
+## Required loop
+
+1. Create a dedicated worktree or project directory and choose the smallest
+   useful app scope. Prefer the maintained starter and its pinned dependencies.
+2. Implement the app as a manifest, rootless container, persistent data path,
+   truthful health/readiness check, declared interface, and tests. Never add a
+   per-app Rust installer or rootful/Docker-socket shortcut.
+3. Use generated secrets or declared secret files; never put credentials in a
+   manifest, image, logs, URL, or frontend bundle. Keep production wallets and
+   app databases outside development fixtures.
+4. Validate the manifest and build context, then run the app through install,
+   start, stop, restart, manager restart, uninstall with data preservation, and
+   reinstall. Verify the real My Apps/Services launch path, not only a direct
+   port.
+5. For UI, exercise standalone and embedded modes at 320, 390, 768, and 1440px
+   plus phone landscape, keyboard navigation, loading/empty/error/retry/success,
+   safe areas, and reduced motion.
+6. Report source, disposable-node, actual-node, and release-artifact evidence
+   separately. Catalog publication is a separate request.
+
+Important runtime facts:
+
+- `/opt/archipelago/apps` is rebuilt from the runtime payload at backend start;
+  staging only there will be lost. Follow the developer guide's payload path.
+- Signed catalog entries take precedence over disk manifests for catalog apps.
+- Installed does not mean ready or launchable; use health and readiness evidence.
+- App interfaces describe the service behind the gate. Do not hard-code a node
+  IP, scheme, app path, or host frame URL into app code.
+
+## References
+
+- [app contract and acceptance](references/app-contract.md)
+- [design routing](../archipelago-design/SKILL.md)
@@ -0,0 +1,7 @@
+interface:
+  display_name: "Archipelago app"
+  short_description: "Build a real Archipelago app"
+  brand_color: "#F7931A"
+  default_prompt: "Use $archipelago-app to build and validate this Archipelago app."
+policy:
+  allow_implicit_invocation: true
@@ -0,0 +1,17 @@
+# App contract
+
+Start with `docs/app-developer-guide.md` and `docs/app-manifest-spec.md`; those
+files are authoritative for fields and launch behavior. Validate with:
+
+```bash
+./scripts/validate-app-manifest.sh apps/<id>/manifest.yml
+python3 scripts/generate-app-catalog.py
+python3 scripts/check-app-catalog-drift.py --release --strict
+```
+
+Use pinned image versions, read-only root, no-new-privileges, minimal
+capabilities, rootless Podman, declared persistent data under
+`/var/lib/archipelago/<id>`, health checks, generated/declared secrets, and
+truthful interfaces. Test install/start/stop/restart/manager-restart/uninstall
+with data preservation/reinstall on a disposable node. Do not replace the
+signed catalog to make a local test app appear.
@@ -0,0 +1,41 @@
+---
+name: archipelago-design
+description: Create or change Archipelago UI using the shared semantic tokens, components, responsive patterns, accessibility states, and embedded/standalone host contract.
+metadata:
+  short-description: Keep Archipelago UI consistent
+---
+
+# Archipelago design system
+
+Use this skill for any new or changed Archipelago UI, including app screens,
+Terminal, setup flows, dialogs, dashboards, and app wrappers. Read
+[design-contract.md](references/design-contract.md) before implementation.
+
+## Rules
+
+- Find and reuse the closest shared component and pattern before creating one.
+- Use semantic `--archy-*` tokens and the pinned kit version. A bespoke color,
+  font, radius, shadow, or z-index needs a documented reason.
+- Preserve the dark baseline, readable surfaces, 4px spacing rhythm, bottom
+  action placement, 44px touch targets, visible focus, and safe-area behavior.
+- Keep terminal/editor/tmux keys inside the terminal focus boundary; generic
+  modal Escape/arrow handlers must not consume them.
+- Implement loading, empty, offline, denied, validation-error, retry, disabled,
+  and confirmed-success states. Status color must have text or icon support.
+- Test standalone and embedded modes. Embedded apps do not duplicate the host
+  wallpaper or navigation and must work without a host handshake.
+
+## Workflow
+
+1. Read the reference screen and source; choose the matching component/pattern.
+2. Build with the shared kit and local assets, not runtime dashboard CSS or CDN
+   fonts. Keep host RPC, signer, and credential bridges behind typed adapters.
+3. Render the gallery/preview at required viewports and inspect screenshots and
+   keyboard behavior. Check contrast on the real composited surface.
+4. Record deliberate exceptions and update the kit only when a reusable need is
+   demonstrated. Do not silently accept visual-diff changes.
+
+## References
+
+- [design contract](references/design-contract.md)
+- [existing component map](references/component-map.md)
@@ -0,0 +1,7 @@
+interface:
+  display_name: "Archipelago design"
+  short_description: "Keep Archipelago UI consistent"
+  brand_color: "#F7931A"
+  default_prompt: "Use $archipelago-design to implement this UI in Archipelago's design system."
+policy:
+  allow_implicit_invocation: true
@@ -0,0 +1,15 @@
+# Existing component map
+
+Reuse these first:
+
+- Structure: `BaseModal.vue`, `BackButton.vue`, `EmptyState.vue`,
+  `SkeletonCard.vue`.
+- Controls: `ToggleSwitch.vue`, `PasswordRevealInput.vue`,
+  `AppSearchField.vue`, `CopyButton.vue`.
+- Feedback: `ToastStack.vue`, `ContainerStatus.vue`, existing upload/progress
+  components.
+- Completion: `PaymentSuccessPane.vue`, `IdentitySuccessPane.vue`.
+- App flows: `AppLauncherOverlay.vue`, `AppCredentialInterstitial.vue`.
+
+The terminal must have an explicit keyboard ownership boundary and must not be
+wrapped in the generic arrow-key modal behavior without adapting it.
@@ -0,0 +1,18 @@
+# Design contract
+
+The current baseline is defined by `neode-ui/src/style.css`,
+`neode-ui/tailwind.config.js`, `BaseModal.vue`, `AppSearchField.vue`,
+`EmptyState.vue`, `SkeletonCard.vue`, and `PaymentSuccessPane.vue`. Preserve the
+dark canvas, glass-card surface, 4px spacing scale, semantic orange accent,
+local licensed fonts, bottom card actions, 40px desktop/52px mobile search,
+44px touch targets, visible focus, dynamic viewport, safe-area and embedded
+canvas rules while the shared kit is extracted.
+
+Use semantic tokens, not raw values. New controls must document keyboard,
+focus, disabled, loading, validation, error, retry, success, responsive, and
+reduced-motion behavior. No essential action may be hover-only. Use the existing
+dialog footer/content split and restore focus after close.
+
+Visual acceptance covers 320/390/768/1440px, phone landscape, enlarged text,
+standalone/embedded modes, dark native controls, no-blur fallback, and actual
+Companion WebView behavior where applicable.
@@ -0,0 +1,53 @@
+---
+name: archipelago
+description: Configure, troubleshoot, and safely modify an Archipelago node or its developer environment using the repository's typed operations, ownership rules, and recovery workflow.
+metadata:
+  short-description: Work safely on Archipelago systems
+---
+
+# Archipelago system work
+
+Use this skill for node configuration, terminal/developer setup, service
+diagnosis, network and SSH work, supported app operations, and system changes.
+For app implementation load `archipelago-app`; for any new or changed UI also
+load `archipelago-design`.
+
+Read [system-map.md](references/system-map.md) before acting. Read `AGENTS.md`
+and the relevant project documentation in the current checkout.
+
+## Workflow
+
+1. Identify the node, repository/worktree, owner, and whether the request is
+   planning, source work, a disposable test, or a live-node operation.
+2. Inspect current state before changing it. Prefer `archy`/Archipelago RPC
+   operations and existing scripts over direct edits or ad-hoc service commands.
+3. Preserve wallets, app data, credentials, user uninstall decisions, and
+   unrelated services. Back up only the scoped state before a mutation.
+4. Make the smallest reversible change. Keep generated state separate from
+   user overrides; never edit generated or packaged files when an owned source
+   or managed override exists.
+5. Verify the actual result and report source tests, disposable integration,
+   live-node acceptance, and packaged-artifact checks separately.
+
+For repository work, use a dedicated worktree and focused branch. For backend
+unit tests use `scripts/test-backend-isolated.sh`; do not run unrestricted
+`cargo test` on a node with installed apps. Do not publish OTA, ISO, catalog,
+or Git mirrors from this skill unless that publication is explicitly requested
+and every release gate is satisfied.
+
+## Terminal and sessions
+
+Treat terminal close as detach. Resume the existing named session; never create
+a duplicate shell or replay a lost command. A reboot can restore workspace and
+Codex conversation metadata but cannot restore the old process. Distinguish
+running, detached, ended, and interrupted states in user-facing output.
+
+Keep credentials, wallet material, terminal output, and command contents out of
+diagnostics and support bundles. A terminal is a privileged capability: verify
+the authenticated owner, origin, attachment grant, and account boundary before
+any PTY bytes flow.
+
+## References
+
+- [system map and safe recipes](references/system-map.md)
+- [app and design routing](references/routing.md)
@@ -0,0 +1,7 @@
+interface:
+  display_name: "Archipelago system"
+  short_description: "Work safely on Archipelago systems"
+  brand_color: "#F7931A"
+  default_prompt: "Use $archipelago to inspect and safely change this Archipelago node."
+policy:
+  allow_implicit_invocation: true
@@ -0,0 +1,10 @@
+# Skill routing
+
+Load `archipelago-app` for manifests, containers, app previews, lifecycle,
+credentials, signer integration, or app packaging. Load `archipelago-design` for
+any newly authored or changed UI. For backend-only work, use only the system
+skill and the relevant project docs.
+
+Planning stays planning. A source change, node mutation, deployment, or
+publication requires that explicit scope from the user. A skill supplies
+workflow knowledge; it does not grant additional privileges.
@@ -0,0 +1,19 @@
+# System map and safe recipes
+
+The native backend is `core/archipelago`; the Vue dashboard is `neode-ui`; ISO
+and first-boot material lives under `image-recipe` and `scripts`; app manifests
+are under `apps/<id>/manifest.yml`. Read `CLAUDE.md`, `AGENTS.md`, and the current
+release checklist before release work.
+
+Use the existing typed RPC and orchestration layers for app lifecycle, network,
+wallet, identity, and service operations. Inspect a matching handler before
+adding an endpoint. Preserve the existing session cookie, CSRF, Origin, and
+app-gate protections.
+
+For source tests, run frontend checks from `neode-ui`. Backend unit tests run
+only through `scripts/test-backend-isolated.sh`; live host checks must be named
+and explicit. Do not touch real wallet/payment/channel state for a test fixture.
+
+Developer changes belong in a dedicated worktree. Keep generated catalog,
+runtime payload, release artifacts, and local node state separate until the
+request explicitly includes packaging or deployment.