@celilo/cli 0.11.0 → 0.12.0

package/AGENTS.md

@@ -77,10 +77,13 @@ celilo module deploy <id> / update / health   # deploy + verify on the fleet
   implements (IPAM, capabilities, firewall/DNS, generator, …), with entry-point files.
 - `./CELILO_CORE_MODULES.md` — the production modules celilo ships in `modules/`
   (what each provides/requires, its role in the fleet).
-- `../../design/MODULE_DEVELOPMENT_GUIDE.md` — author a module (start here).
+- `../../reference/MODULE_DEVELOPMENT_GUIDE.md` — author a module (start here).
+- `./MODULE_PRIMITIVES.md` — the remote-ops primitives a hook uses to touch a box
+  (probe / serviceCtl / applyRenderedConfig / waitFor / …). **Modules never
+  hand-build SSH** — read this before writing any hook that reaches a remote host.
 - `./CLI_USAGE.md` — full CLI reference + workflows.
-- `../../v2/BUILD_BUS.md` — how a change reaches the fleet.
-- `../../v2/APP_CI_REFERENCE.md` — wire an app's CI/CD (the copy-me recipe).
-- `../../v2/MODULE_VERSIONING.md` — what `version` means; `version_source`.
+- `../../openspec/changes/build-bus-poll-cd/proposal.md` — how a change reaches the fleet.
+- `../../reference/APP_CI_REFERENCE.md` — wire an app's CI/CD (the copy-me recipe).
+- `../../openspec/changes/module-version-semantics/proposal.md` — what `version` means; `version_source`.
 - `../../schemas/module-manifest.schema.json` — the manifest contract.
 - `https://celilo.computer/docs` — hosted docs (LAN; the repo docs lead).

package/CELILO_CORE_MODULES.md

@@ -22,7 +22,7 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 ## Network fabric (DNS / firewall / DHCP)
 
 - **greenwave** — GreenWave C4000XG ISP router driver; port-forwarding + public-IP discovery via REST. **provides:** `firewall`, `dhcp_server`.
-- **iptables** — iptables firewall + NAT; cross-VLAN port exposure with recursive upstream delegation. **provides:** `firewall`.
+- **iptables** — iptables firewall + NAT; cross-VLAN port exposure with recursive upstream delegation. Converge model: `exposeService` registers into the shared-core port-forward registry, then renders the complete ruleset and applies it atomically via `iptables-restore` (default-DROP FORWARD + coarse zone-tier matrix; SSH-free). **provides:** `firewall`.
 - **knot-unbound-internal** — split-horizon internal DNS via Knot (authoritative) + Unbound (recursive); lightweight, plain apt, no .NET. **provides:** `dns_internal`. Ships a base-module-aspect (`modules/knot-unbound-internal/base-module-aspect/`).
 - **technitium** — internal split-horizon DNS resolver + authoritative server (web UI + HTTP API); heavier alternative to knot-unbound. **provides:** `dns_internal`. Ships a base-module-aspect (`modules/technitium/base-module-aspect/`).
 - **namecheap** — public DNS A-record management via Namecheap Dynamic DNS API (HTTP, no browser automation). **provides:** `dns_registrar`.
@@ -34,17 +34,17 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 
 ## Celilo's own infrastructure (self-hosted)
 
-- **celilo-mgmt** — the celilo management server itself, deployed as a module (replaces install.sh + `system init`; ships daemon, runs migrations, self-registers). **provides:** `celilo_event_bus`, `celilo_module_deploy_worker`. **requires:** `cross_module_read`. See `v2/MANAGEMENT_AS_NETAPP.md`.
-- **celilo-registry** — module registry server (Cargo sparse protocol); stores `.netapp` files, serves index + search/download API. **provides:** `registry_publish`. **requires:** `public_web`, `dns_registrar`.
+- **celilo-mgmt** — the celilo management server itself, deployed as a module (replaces install.sh + `system init`; ships daemon, runs migrations, self-registers). **provides:** `celilo_event_bus`, `celilo_module_deploy_worker`. **requires:** `cross_module_read`. See `openspec/specs/management-as-module/spec.md`.
+- **celilo-registry** — module registry server (Cargo sparse protocol); stores `.netapp` files, serves index + search/download API. On install it provisions a confidential introspection OIDC client via `idp.create_oidc_client` (SECURE_MODULE_PUBLISH.md §5[D-A]) and converges its issuer + introspection endpoint + creds onto the box for RFC 7662 token verification. **provides:** `registry_publish`. **requires:** `public_web`, `dns_registrar`, `idp`.
 - **celilo-apt-repo** — Debian apt repository (reprepro + Bun HTTP server) serving the celilo `.deb` at apt.celilo.computer. **provides:** `apt_publish`. **requires:** `public_web`, `dns_registrar`.
 - **celilo-website** — public docs site (static Astro) served via Caddy on celilo.computer. **requires:** `public_web`, `dns_registrar`.
 
 ## Git forge & CI pipeline
 
-- **forgejo** — self-hosted Forgejo git forge (git-over-SSH, OIDC, public ingress). **provides:** `source_forge`. **requires:** `public_web`, `idp`, `firewall`, `dns_registrar`. See `v2/CI_PIPELINE.md`.
-- **forgejo-runner** — host-mode (LXC) Forgejo Actions runner for unit/lint jobs; outbound-only, lives in dmz. **requires:** `source_forge`. See `v2/FORGEJO_RUNNER.md`.
+- **forgejo** — self-hosted Forgejo git forge (git-over-SSH, OIDC, public ingress). **provides:** `source_forge`. **requires:** `public_web`, `idp`, `firewall`, `dns_registrar`. See `openspec/specs/forgejo-runner/spec.md`.
+- **forgejo-runner** — host-mode (LXC) Forgejo Actions runner for unit/lint jobs; outbound-only, lives in dmz. **requires:** `source_forge`. See `openspec/specs/forgejo-runner/spec.md`.
 - **forgejo-builder** — VM-based, Docker-capable Forgejo Actions runner (`requires.system.type: vm`) for hermetic release builds + the cele2e suite. **requires:** `source_forge`.
-- **npm-cache-node** — self-hosted npm registry: a pass-through disk cache (proxies upstream) plus a `PUT /<pkg>` publish endpoint that stores locally published `@celilo/*` tarballs as authoritative local-origin (never overwritten by upstream). PUT is gated on a static operator-set publish token (`publish_tokens` secret, SHA-256 model; fail-closed — absent/bad token → 401); reads stay open (it's a mirror). **requires:** `public_web`, `dns_registrar`. See `v2/NPM_CACHE_NODE.md`.
+- **npm-cache-node** — self-hosted npm registry: a pass-through disk cache (proxies upstream) plus a `PUT /<pkg>` publish endpoint that stores locally published `@celilo/*` tarballs as authoritative local-origin (never overwritten by upstream). PUT is gated on a static operator-set publish token (`publish_tokens` secret, SHA-256 model; fail-closed — absent/bad token → 401); reads stay open (it's a mirror). **requires:** `public_web`, `dns_registrar`. See `openspec/changes/private-npm-registry/proposal.md`.
 
 ## Applications
 
@@ -52,6 +52,7 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 
 ## E2E fixtures & probes (not production apps)
 
+- **hello-foo** / **hello-bar** — hostless single-page sites (one hand-written `site/index.html`, no build step) published at a configurable `domain` + `path`. They exist so the caddy route-lifecycle e2e can put several independent routes on one caddy and watch them interact — celilo-website is the only other static-site module, and one site can't answer "does removing `/` break `/foo`?". **requires:** `public_web`, `dns_registrar`.
 - **source-forge-probe** — hostless e2e probe that exercises the `source_forge` capability (issue/revoke runner token) against a deployed Forgejo. **requires:** `source_forge`.
 - **test-ansible-output** — e2e fixture that runs 25×1s sleep tasks to assert Ansible output streams in real time. Not a real app.
 - **vm-smoke** — throwaway module proving celilo's generic `type: vm` deploy path end-to-end (template clone → cloud-init → Ansible reach). No capabilities.

package/CELILO_SUBSYSTEMS.md

@@ -11,7 +11,7 @@ inventory / the codebase and cite what you found. Only raise a question if the s
 is genuinely empty, or the real choice is between existing mechanisms.
 
 This is an *implemented-feature* map. For terminology see `GLOSSARY.md`; for architecture
-see `design/README.md`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MODULES.md)
+see `openspec/specs/`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MODULES.md)
 (the production modules celilo ships).
 
 > **All file paths below are relative to the celilo source-repo root** (e.g.
@@ -26,6 +26,7 @@ see `design/README.md`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MO
 - **IPAM (IP/VMID allocation)** — `apps/celilo/src/ipam/allocator.ts` — `allocateIPFromSubnet`, `allocateVMID`, `reserveIP`/`unreserveIP`, `inferZoneFromIP`, `getAllocation`. Auto-wrapper: `apps/celilo/src/ipam/auto-allocator.ts` — `allocateForModule` / `deallocateForModule`.
 - **Infrastructure selection (container-service vs machine pool)** — `apps/celilo/src/services/machine-pool.ts` (`getMachineByHostname`, `addMachine`, `assignModuleToMachine`) and `apps/celilo/src/services/container-service.ts` (`getContainerServiceByName`, `addContainerService`, `verifyContainerService`). Provider API clients: `apps/celilo/src/api-clients/proxmox.ts`, `apps/celilo/src/api-clients/digitalocean.ts`.
 - **Zone detection / system config** — `apps/celilo/src/services/zone-detector.ts` — `detectZoneFromIp` reads `network.<zone>.subnet` from the `systemConfig` table.
+- **Host discovery ("which host serves module X?")** — `apps/celilo/src/cli/commands/module-where.ts` (`celilo module where <id> [--json]`, MCP `celilo_module_where`) — reads deployed hosts from `module_systems` via `getModuleSystems`, reconciles the live Proxmox node via `reconcilePlacement`, and adds a role-based reachability hint per zone. CI/build infra (builder VM, Forgejo runners) is out of scope (not in `module_systems`).
 
 ## Capability system (cross-module data & functions)
 
@@ -38,16 +39,53 @@ see `design/README.md`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MO
 
 | capability | impl | provider module(s) |
 |---|---|---|
-| `public_web` | `packages/capabilities/src/public-web.ts` (`createPublicWeb`) | caddy |
+| `public_web` | `packages/capabilities/src/public-web.ts` (`createPublicWeb`). **Route lifecycle** is framework-owned at both ends, not per-module: removing a consumer runs `apps/celilo/src/services/web-route-cleanup.ts` (delete rows → reclaim `/srv/www/<slug>` → emit `routes_changed`) whether or not the module has an `on_uninstall`; deploying a provider runs `apps/celilo/src/services/public-web-republish.ts` (re-run every static consumer's `on_install`) so a provider rebuild refills the web roots it destroyed. | caddy |
 | `idp` | `packages/capabilities/src/idp.ts` | authentik |
 | `dns_registrar` | `packages/capabilities/src/dns-registrar.ts` (`registerHost`) | namecheap |
-| `firewall` | `packages/capabilities/src/firewall.ts` (`exposeService`, `unexposeService`, `listExposedServices`) | greenwave, iptables |
+| `firewall` | `packages/capabilities/src/firewall.ts` (`exposeService`, `unexposeService`, `listExposedServices`). **Converge model**: register into the shared-core port-forward registry → render the complete ruleset → apply atomically (see the firewall converge note below). | greenwave, iptables |
 | `dns_internal` | `packages/capabilities/src/dns-internal.ts` | knot-unbound-internal, technitium |
 | `dhcp_server` | `packages/capabilities/src/dhcp-server.ts` | greenwave |
 | `source_forge` | `packages/capabilities/src/source-forge.ts` | forgejo |
 | `registry_publish` | `packages/capabilities/src/registry-publish.ts` | celilo-registry |
 | `cross_module_read` | `packages/capabilities/src/cross-module-read.ts` | framework (read other modules' capability data) |
 
+## Remote-ops primitives (the SSH seam — modules never hand-build SSH)
+
+Module hooks reach a remote box ONLY through these typed primitives
+(openspec/changes/unified-management-no-ssh/proposal.md); a raw `ssh` string / `node:child_process` in
+`modules/**/scripts/` is a defect. Impl: `packages/capabilities/src/remote.ts`
+(exported from `packages/capabilities/src/index.ts`).
+
+- **`remoteExec`** — the ONE ssh seam (`ssh root@<target> <cmd>`); everything else builds on it.
+- **`probe`** — read-only health checks: `systemd` / `http` / `command`.
+- **`serviceCtl`** — systemctl start/stop/restart/reload/enable/disable.
+- **`runAppCommand` / `runAppCommandWithSecret`** — escape-hatch on-box command; the secret variant feeds the secret on **stdin** (`$SECRET`), never argv.
+- **`streamBackup` / `streamRestore` / `fetchFile` / `pushFile`** — binary-safe streaming via local shell redirect/pipe.
+- **`waitFor`** — predicate-poll combinator.
+- **`applyRenderedConfig`** — converge: write rendered config → validate → apply → rollback (one round-trip). Used by caddy (Caddyfile), knot (views), iptables (ruleset).
+- **`tailLog` / `grepLog`** — journald reads (regex / ignoreCase).
+
+Target = `RemoteTarget` (`{ ipv4_address }`; `DeployedSystem` satisfies it). The
+runner seam (`execRunner` real / `createMockRunner` for tests) lives in
+`packages/capabilities/src/testing.ts`. Authoring guide: `MODULE_PRIMITIVES.md`
+(ships in `@celilo/cli`).
+
+## Firewall converge & port-forward registry
+
+- **Port-forward registry (desired state)** — `port_forwards` DB table
+  (`apps/celilo/src/db/schema.ts`, migration `0014`) + the injectable
+  `PortForwardStore` (`apps/celilo/src/services/port-forwards.ts`,
+  `buildPortForwardStore`). Shared-core so any firewall provider reconciles
+  against one store; injected by the capability-loader into the firewall factory.
+- **Ruleset renderer (pure)** — `modules/iptables/scripts/ruleset-renderer.ts`
+  (`renderRuleset`): registry + firewall state → a complete `iptables-restore`
+  file. Default-DROP FORWARD + established/related + egress + the coarse
+  zone-tier matrix (dmz→app, app→secure from `network.<zone>.subnet`) + per-service DNAT allows.
+- **Converge** — `modules/iptables/scripts/firewall-functions.ts` (`converge`):
+  `exposeService`/`unexposeService` register into the store, then render + apply
+  atomically via `applyRenderedConfig` (`iptables-restore`). Replaces the old
+  per-rule `iptables -A`; the registry (not `iptables -L`) is the source of truth.
+
 ## Hooks & deploy
 
 - **Hook executor / ABI** — `apps/celilo/src/hooks/executor.ts` (`invokeHook`, `executeHookScript`, `checkRequiredCapabilities`), types in `apps/celilo/src/hooks/types.ts` (`HookContext`, `HookDefinition`, `HookName`). Named-hook runner: `apps/celilo/src/hooks/run-named-hook.ts`. Manifest hook config: `apps/celilo/src/hooks/load-hook-config.ts`.
@@ -68,6 +106,10 @@ see `design/README.md`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MO
 
 - **Module packaging** — `apps/celilo/src/module/packaging/` — `build.ts` (`buildModule`), `extract.ts`, `checksum.ts`, `signature.ts` (`signChecksums`/`verifySignature`), `release-metadata.ts`, `audit.ts`.
 - **Publish driver** — `scripts/publish.ts` shims to `apps/celilo/src/cli/commands/publish/` (workspace npm packages via `bun publish` + module registry; preflight stale-version/stale-manifest gates).
+- **Registry publish-token admin (append-safe)** — `apps/celilo/src/cli/commands/registry-token.ts` — `celilo registry token add/rm <token>` read-modify-write the celilo-registry `publish_tokens` secret (newline-separated bootstrap/admin list). Avoids the `module secret set` full-overwrite that clobbered other holders. Runs on-mgr where the master key lives; runtime-minted scoped tokens are handled separately by the registry-server.
+- **Contributor identity tokens (idp-issued, per-user)** — `apps/celilo/src/cli/commands/token.ts` — `celilo token obtain|list|revoke` mints/lists/revokes per-user API tokens via the `idp` capability (`create_token`/`list_tokens`/`revoke_token` on authentik). A module contributor authenticates publishes AS THEMSELVES (SECURE_MODULE_PUBLISH.md §6) — no admin/shared token on their machine; the token feeds `celilo author init`. Shown once at mint; the idp stores it hashed, celilo persists nothing. Runs on-mgr where the idp provider lives. Distinct from `registry token add/rm` (raw bootstrap list, different trust model).
+- **Registry token verification (opaque + idp introspection)** — `packages/registry-server/src/auth.ts` (`TokenAuth` — opaque SHA-256 publish tokens, admin/per-package scope) + `packages/registry-server/src/introspection.ts` (`IntrospectionVerifier` — RFC 7662 verify-bridge, SECURE_MODULE_PUBLISH.md §5[D-A]). `authorizePackage()` in `server.ts` tries the opaque set first (unchanged), then, for a token unknown to it, `identify()`s it via the idp introspection endpoint using the registry's confidential OIDC client creds (`OIDC_INTROSPECTION_ENDPOINT`/`OIDC_CLIENT_ID`/`OIDC_CLIENT_SECRET`, provisioned on install — ce-7aa), reading `{active, sub, groups, exp}`. Fails CLOSED on any introspection error; never logs tokens/secrets. Instant revocation: revoke at the idp → next publish sees `active:false` → 401.
+- **Registry module-owner table (hybrid group + owner authz — ce-1ch, D-C)** — `packages/registry-server/src/module-owner-store.ts` (`ModuleOwnerStore` — JSON-persisted `{moduleName, ownerSub, claimedAt, sourceGroup}`, `REGISTRY_OWNERS_FILE`/`dataDir/module-owners.json`). The verified `groups` claim gates *whether* an identity may publish (`REGISTRY_ADMIN_GROUP`→publish/reassign anything; `REGISTRY_PUBLISHER_GROUP`, default `celilo-authors`, configurable→claim+publish owned); the owner table gates *which names*. First-publish-claims: the first verified publisher of an unclaimed name owns it; a *different* publisher is then DENIED (confused-deputy defense — Author-A cannot publish Author-B's module). Admin HTTP endpoints `GET /api/v1/modules/owners`, `GET|POST /api/v1/modules/owners/{name}` (reassign). Operator front door: `celilo registry owner list|show|set` (`apps/celilo/src/cli/commands/registry-owner.ts`), admin token resolved from the local `publish_tokens` bootstrap list.
 
 ## Persistence
 
@@ -79,14 +121,18 @@ see `design/README.md`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MO
 
 ## Remote API (drive the CLI over the wire)
 
-Run any celilo command on celilo-mgr over SSH instead of screen-scraping `ssh <host> celilo …`. Typed, streamed, per-operation authz, mid-run interviews. Design: `v2/API_COMMUNICATION.md`.
+Run any celilo command on celilo-mgr over SSH instead of screen-scraping `ssh <host> celilo …`. Typed, streamed, per-operation authz, mid-run interviews. Design: `openspec/changes/replace-ssh-cli-api/proposal.md`.
 
-- **Wire protocol** — `apps/celilo/src/api/protocol.ts` — versioned NDJSON tagged union (`command`/`progress`/`log`/`result`/`error`/`interview`/`answer`) + `translateOutputLine`.
+- **Lightweight core (`@celilo/core`)** — `packages/core/src/` — the transport primitives lifted out of `@celilo/cli` so a consumer (e.g. the MCP server) can reach the wire without dragging Ink/React/drizzle/aws-sdk: `command-registry.ts` (`COMMANDS` + `CommandDef`/`ArgDef`/`FlagDef`), `protocol.ts`, `remote-client.ts`. Public surface: `packages/core/src/index.ts`.
+- **Wire protocol** — `packages/core/src/protocol.ts` (`@celilo/core`) — versioned NDJSON tagged union (`command`/`progress`/`log`/`result`/`error`/`interview`/`answer`) + `translateOutputLine`.
+- **Registry serialization** — `apps/celilo/src/cli/commands/commands-json.ts` — `celilo commands --json` prints the full `COMMANDS` tree as JSON; the live source of truth the MCP fetches to generate its tool surface (so it mirrors whatever celilo version the server runs). `service list --json` similarly exposes configured providers for MCP auto-detect. `module list --json` prints the module roster (id/version/state) as stable JSON — the backbone the MCP composite troubleshooting tools correlate `audit --json` findings against.
 - **Server** — `apps/celilo/src/api/serve.ts` (`apiServeMode`); the `celilo api-serve --principal=<id>` sshd forced-command entry point (dispatched in `apps/celilo/src/cli/index.ts`). Authorizes per principal, runs the command as a protocol-mode child, streams output, audits to stderr.
-- **Client** — `apps/celilo/src/api/remote-client.ts` — `resolveRemote` (`--remote <dest>` / `CELILO_REMOTE`), `runRemoteClient` (`ssh -T`, renders progress via the local ProgressDisplay, answers interviews via clack).
+- **Client** — `packages/core/src/remote-client.ts` (`@celilo/core`) — `resolveRemote` (`--remote <dest>` / `CELILO_REMOTE`), `runRemoteClient` (`ssh -T`, renders progress via the local ProgressDisplay, answers interviews via clack).
 - **Access control** — `apps/celilo/src/services/api-access.ts` — `grantPrincipal`, `isAuthorized` (deny-by-default, `command:subcommand` grants), `renderAuthorizedKeys`. Table: `api_principals` (`apps/celilo/src/db/schema.ts`). CLI: `apps/celilo/src/cli/commands/api.ts` (`api grant|list|revoke|authorized-keys|key new`).
 - **Mid-run interview bridge (`kind:daemon` responder)** — `apps/celilo/src/services/remote-responder.ts` — `startRemoteResponder` bridges bus `interview.required.*` ↔ wire.
 - **Server provisioning** — the `celilo-bootstrap` deb (`packaging/celilo-bootstrap/scripts/postinst`) creates the non-root `celilo-api` landing account + sshd; membership in the `celilo` group + `/etc/sudoers.d/celilo` (`!use_pty`) gives api-serve DB access via the wrapper's sudo-drop.
+- **Self-upgrade (apt)** — `celilo apt-upgrade` (`apps/celilo/src/cli/commands/apt-upgrade.ts`) upgrades the deb-installed `celilo`/`celilo-bootstrap` packages (`apt-get update` → `--only-upgrade install`) then spawns a fresh `celilo system migrate` (ISS-0100). It's the RW target behind the MCP's registry-derived `celilo_apt_upgrade` tool; the celilo user's two apt invocations are scoped-sudo'd by `/etc/sudoers.d/celilo-apt-upgrade`, shipped by `celilo-bootstrap`.
+- **MCP service (`@celilo/mcp`)** — `packages/mcp/src/` — an operator-facing stdio MCP server (official `@modelcontextprotocol/sdk`, bin `celilo-mcp`) that drives a remote celilo server over the Remote API for an AI client. Two-item config (`config.ts`: `server` + `defaultUser`, env or `~/.config/celilo-mcp/config.json`). Dual-principal auth (`auth.ts`: `celilo-mcp auth setup` enrolls read-only `celilo-mcp-ro` + full `celilo-mcp-rw` ed25519 keypairs, prints the exact `celilo api grant` lines the operator runs server-side). Transport (`transport.ts`): reuses `@celilo/core` `runRemoteClient`, selecting the principal by `ssh -i <key>` and capturing structured output. Tool surface is generated LIVE from the server's command registry — `registry-fetch.ts` fetches `celilo commands --json` (+ `service list --json` for configured providers) over the RO principal on connect; `tools-from-registry.ts` (pure) projects that into one tool per runnable leaf, grouped by top-level command (`celilo_module_*`, `celilo_proxmox_*`, …), each with a Zod input schema from the leaf's args/flags and a read/write tag → RO/RW routing, plus a generic `celilo_run` escape hatch. Auto-detect hides provider-gated groups (e.g. `celilo_proxmox_*` until a Proxmox service is configured) and re-detects on a timer, emitting `notifications/tools/list_changed` when the surface changes. Coverage gate (`tests/coverage.test.ts`) asserts every registry leaf maps to a tool. Composite RO troubleshooting tools (`troubleshoot.ts` pure correlation + `troubleshoot-tools.ts` thin adapters): `celilo_assess_module <id>` and `celilo_fleet_status` correlate `celilo audit --json` (the drift backbone) with the `module list --json` roster into a per-module / fleet-wide verdict. Design: `openspec/changes/celilo-mcp-service/proposal.md`. (Distinct from the dev/ops `@celilo/mcp-server` below.)
 
 ## E2E simulation
 

package/MODULE_PRIMITIVES.md

@@ -0,0 +1,164 @@
+# Module Primitives — the remote-ops toolkit for module hooks
+
+**The one rule: modules never hand-build SSH.** A module hook that needs to touch
+a deployed box does it through a typed primitive from `@celilo/capabilities` —
+never a raw `ssh root@…` string, never `node:child_process`. SSH lives in exactly
+one place (the `remoteExec` seam) and in Ansible's transport. A raw ssh/exec in
+`modules/**/scripts/` is a defect (and a publish/lint gate flags it).
+
+Why: hand-rolled ssh strings re-invent host-key handling, escaping, timeouts, and
+secret-hygiene every time — and can't be unit-tested. The primitives give you one
+correct, mockable implementation of each shape of remote work.
+
+```ts
+import { probe, serviceCtl, applyRenderedConfig } from '@celilo/capabilities';
+```
+
+---
+
+## The two things every primitive shares
+
+**Target** — a `RemoteTarget` is just `{ ipv4_address: string }`. A
+`DeployedSystem` (what your hook gets in `context.systems`) satisfies it directly;
+for a machine addressed by config, pass `{ ipv4_address: ip }`.
+
+**Runner** — every primitive takes an optional trailing `runner` (default
+`execRunner`, which really shells out). In unit tests pass `createMockRunner([…])`
+so you assert on the command strings/stdin without touching a box. A non-zero
+remote exit comes back as `{ ok: false, … }` — **failure is data, never a throw** —
+so your hook decides whether it's fatal (a deploy) or best-effort (a teardown).
+
+```ts
+// test
+import { createMockRunner } from '@celilo/capabilities';
+const { run, calls } = createMockRunner([
+  { match: 'systemctl is-active caddy', result: { ok: true, stdout: 'active', stderr: '' } },
+]);
+expect(probe(sys, { kind: 'systemd', unit: 'caddy' }, run).healthy).toBe(true);
+```
+
+---
+
+## Which primitive when
+
+| You want to… | Use | Not |
+|---|---|---|
+| Check a box is healthy (read-only) | `probe` | `ssh … systemctl is-active` |
+| Start/stop/restart a systemd unit | `serviceCtl` | `ssh … systemctl restart` |
+| Push a config whose content you computed from celilo's DB | `applyRenderedConfig` (converge) | `ssh … cat > file` |
+| Wait for a condition to come true | `waitFor` | `sleep` / `setTimeout` |
+| Back up / restore app state (binary) | `streamBackup` / `streamRestore` | `ssh … | base64` |
+| Read a unit's journal | `tailLog` / `grepLog` | `ssh … journalctl` |
+| Run a secret on a command line | `runAppCommandWithSecret` | secret on argv |
+| Anything else with no capability/HTTP/converge path | `runAppCommand` (+ `// escape-hatch:`) | a raw ssh string |
+
+**Reach for a capability method first.** If another module already provides the
+thing (open a port → `firewall.exposeService`; register a route →
+`public_web.registerReverseProxy`; mint a token → `idp`/`source_forge`), call
+that, not a primitive. The primitives are for the module's *own* box.
+
+---
+
+## The primitives
+
+### `probe(target, check, runner?, opts?) → { healthy, detail }`
+Read-only health check. Never mutates. `check` is one of:
+- `{ kind: 'systemd', unit }` — unit is `active`.
+- `{ kind: 'http', url, expectStatus?, headers? }` — curl runs **on the box**, so
+  it doesn't depend on Caddy/public DNS. `expectStatus` defaults to 200; pass a
+  list (e.g. `[200, 308]`) or `headers: { Host: 'app.example.com' }` for a vhost.
+- `{ kind: 'command', command, expectStdoutIncludes? }`.
+```ts
+probe(sys, { kind: 'http', url: 'http://localhost', headers: { Host: fqdn }, expectStatus: [200, 308] }, run);
+```
+
+### `serviceCtl(target, unit, action, runner?, opts?) → RunResult`
+systemd control. `action ∈ start|stop|restart|reload|enable|disable`. Mutating —
+for liveness use `probe`.
+```ts
+serviceCtl(sys, 'caddy', 'reload', run);
+```
+
+### `applyRenderedConfig({ target, path, content, validate, apply, runner?, timeoutMs? }) → RunResult`
+**The converge primitive.** For config whose *content* your hook computes at
+deploy-time from celilo's DB (caddy's Caddyfile from `web_routes`, knot's views
+from the DNS ledger, the firewall ruleset from the port-forward registry) —
+content a static Ansible render can't know. One atomic on-box script, one SSH
+round-trip: back up → write (`content` rides **stdin**, newline-safe) → `validate`
+(rolled back + not activated if it fails) → `apply` (rolled back if it fails).
+`{path}` is substituted into `validate`/`apply`.
+```ts
+applyRenderedConfig({
+  target: sys, path: '/etc/caddy/Caddyfile', content: rendered,
+  validate: 'caddy validate --config {path} --adapter caddyfile',
+  apply: 'caddy reload --config {path} --force', runner: run,
+});
+```
+
+### `waitFor(predicate, { attempts?, intervalMs?, onAttempt? }) → Promise<boolean>`
+Poll an async predicate until true or exhausted (default 30 × 5s). A combinator —
+it never touches the remote; wrap a `probe`/`runAppCommand` thunk. Use
+`onAttempt` to emit a heartbeat so a long wait doesn't trip the hook idle-timeout.
+Never `sleep`.
+```ts
+await waitFor(() => probe(sys, { kind: 'http', url }, run).healthy,
+  { onAttempt: (n) => logger.info(`waiting… ${n * 5}s`) });
+```
+
+### `tailLog(q & { lines? }) / grepLog(q & { grep }) → RunResult`
+Read a systemd unit's journal. `q = { target, unit, grep?, regex?, ignoreCase? }`.
+`grepLog` requires `grep`; `regex: true` uses `grep -E`.
+```ts
+grepLog({ target: sys, unit: 'caddy', grep: 'certificate obtained', regex: true });
+```
+
+### `streamBackup / streamRestore / fetchFile / pushFile → RunResult`
+Binary-safe streaming — bytes flow through the local shell redirect/pipe, never
+Node's string capture, so tar/pg_dump/sqlite snapshots survive byte-for-byte.
+```ts
+streamBackup(sys, 'tar -cf - -C /var/lib/forgejo repositories', '/backup/repos.tar', run);
+streamRestore(sys, '/restore/repos.tar', 'tar -xf - -C /var/lib/forgejo', run);
+fetchFile(sys, '/etc/app/id', '/local/id', run);   // pull
+pushFile(sys, '/local/cert.pem', '/etc/app/cert.pem', run);  // push
+```
+
+### `runAppCommandWithSecret(target, command, secret, runner?, opts?) → RunResult`
+For a command needing a secret on its **command line** (token mint, credential
+register) where the app has no HTTP API. The secret rides **stdin** into shell var
+`SECRET` — never argv, so it's absent from logs/history/the recorded call.
+Reference it as `"$SECRET"`. Escape-hatch discipline applies (comment required).
+```ts
+// escape-hatch: act_runner registers only via CLI; no HTTP API.
+runAppCommandWithSecret(sys, 'act_runner register --token "$SECRET"', token, run);
+```
+
+### `runAppCommand(target, command, runner?, opts?) → RunResult`
+**The escape hatch.** Only when the work is neither a capability, HTTP, converge,
+nor a service action (e.g. removing app state on teardown). **Every call site MUST
+carry an inline `// escape-hatch: <why no capability/HTTP/converge path>` comment**
+— the recurrence-gate lint flags an uncommented one.
+```ts
+// escape-hatch: purge app data dir on teardown; no capability owns this.
+runAppCommand(sys, 'rm -rf /var/lib/app/*', run);
+```
+
+### `remoteExec(target, command, opts?, runner?) → RunResult`
+The single SSH seam every other primitive builds on. You almost never call this
+directly — prefer the specific primitive. `opts` is `{ input?, timeoutMs? }`.
+
+---
+
+## Rules of thumb
+
+- **Failure is data.** Check `.ok`; decide fatal vs best-effort. Don't wrap in
+  try/catch expecting throws.
+- **Unit-test with `createMockRunner`.** Assert on `calls[].cmd` and `calls[].input`.
+  Controlled identifiers (systemd unit names) are passed unescaped; the outer
+  `remoteExec` escapes the whole command, so assert on bare substrings.
+- **Secrets never on argv** — `runAppCommandWithSecret`, or a capability method.
+- **No `sleep`** — `waitFor` on the real condition.
+- **Computed config → `applyRenderedConfig`**, not `ssh cat >`. It validates and
+  rolls back; a broken config never goes live.
+
+See also: `CELILO_SUBSYSTEMS.md` (the primitive impls + the firewall converge),
+`openspec/changes/unified-management-no-ssh/proposal.md` (the design), `reference/MODULE_DEVELOPMENT_GUIDE.md`.

package/README.md

@@ -247,7 +247,7 @@ celilo ipam ip list-reservations
 - ✅ **Bridge** - From `network.{zone}.bridge` system config
 - ✅ **VM Resources** - cores, memory, disk, storage from manifest defaults
 
-See [../../design/MODULE_DEVELOPMENT_GUIDE.md](../../design/MODULE_DEVELOPMENT_GUIDE.md) for complete zero-config documentation.
+See [../../reference/MODULE_DEVELOPMENT_GUIDE.md](../../reference/MODULE_DEVELOPMENT_GUIDE.md) for complete zero-config documentation.
 
 ### Database Location
 
@@ -262,7 +262,7 @@ See [../../design/MODULE_DEVELOPMENT_GUIDE.md](../../design/MODULE_DEVELOPMENT_G
 
 ### Testing Strategy
 
-**Three test tiers** (see [TESTING_STRATEGY.md](../../design/TESTING_STRATEGY.md) for details):
+**Three test tiers** (see [TESTING_STRATEGY.md](../../reference/TESTING_STRATEGY.md) for details):
 
 **Tier 1: Unit Tests** (< 1 second)
 ```bash
@@ -1539,9 +1539,9 @@ When debugging issues, check:
 
 **Documentation**:
 - [CLAUDE.md](../../CLAUDE.md) - Engineering standards
-- [TESTING_STRATEGY.md](../../design/TESTING_STRATEGY.md) - Testing approach
-- [IDENTIFIER_NAMING_CONVENTIONS.md](../../design/IDENTIFIER_NAMING_CONVENTIONS.md) - Naming rules
-- [TEMPLATE_VARIABLE_SYNTAX.md](../../design/TEMPLATE_VARIABLE_SYNTAX.md) - Variable syntax
+- [TESTING_STRATEGY.md](../../reference/TESTING_STRATEGY.md) - Testing approach
+- [IDENTIFIER_NAMING_CONVENTIONS.md](../../reference/IDENTIFIER_NAMING_CONVENTIONS.md) - Naming rules
+- [TEMPLATE_VARIABLE_SYNTAX.md](../../reference/TEMPLATE_VARIABLE_SYNTAX.md) - Variable syntax
 
 **Debugging Tools**:
 - Drizzle Studio: `bun run db:studio`

package/drizzle/0015_port_forwards.sql

@@ -0,0 +1,12 @@
+CREATE TABLE `port_forwards` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`firewall_ip` text NOT NULL,
+	`internal_ip` text NOT NULL,
+	`port` integer NOT NULL,
+	`protocol` text NOT NULL,
+	`ingress_ip` text,
+	`description` text DEFAULT '' NOT NULL,
+	`created_at` integer DEFAULT (unixepoch()) NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `port_forwards_unique_idx` ON `port_forwards` (`firewall_ip`,`internal_ip`,`port`,`protocol`,`ingress_ip`);

package/drizzle/meta/_journal.json

@@ -106,6 +106,13 @@
       "when": 1783000000000,
       "tag": "0014_api_principals",
       "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "6",
+      "when": 1783100000000,
+      "tag": "0015_port_forwards",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -14,9 +14,16 @@
     "tsconfig.json",
     "AGENTS.md",
     "CELILO_SUBSYSTEMS.md",
-    "CELILO_CORE_MODULES.md"
+    "CELILO_CORE_MODULES.md",
+    "MODULE_PRIMITIVES.md"
+  ],
+  "keywords": [
+    "celilo",
+    "homelab",
+    "orchestration",
+    "ansible",
+    "terraform"
   ],
-  "keywords": ["celilo", "homelab", "orchestration", "ansible", "terraform"],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -49,9 +56,10 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1024.0",
-    "@celilo/capabilities": "^0.6.0",
-    "@celilo/cli-display": "^0.1.9",
-    "@celilo/event-bus": "^0.1.7",
+    "@celilo/capabilities": "workspace:^",
+    "@celilo/cli-display": "workspace:^",
+    "@celilo/core": "workspace:^",
+    "@celilo/event-bus": "workspace:^",
     "@clack/prompts": "^1.1.0",
     "ajv": "^8.18.0",
     "drizzle-orm": "^0.36.4",

package/schemas/system_config.json

@@ -13,7 +13,7 @@
     "network.dmz.subnet": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}/\\d{1,2}$",
-      "description": "DMZ subnet CIDR (not defaulted — appears only when a firewall module provides this zone; see v2/NETWORK_CONFIG_TO_FIREWALL.md)"
+      "description": "DMZ subnet CIDR (not defaulted — appears only when a firewall module provides this zone; see openspec/specs/progressive-zone-disclosure/spec.md)"
     },
     "network.dmz.gateway": {
       "type": "string",

package/src/ansible/inventory.test.ts

@@ -97,7 +97,7 @@ describe('generateHostsIni', () => {
 
   test('emits ansible_connection=local for a local machine (no SSH host/key)', () => {
     // The management box deploying to itself uses Ansible's local
-    // connection (v2/CELILO_BOOTSTRAP_VIRTUAL_PACKAGE.md).
+    // connection (openspec/specs/bootstrap-meta-package/spec.md).
     const hosts: InventoryHost[] = [
       {
         hostname: 'celilo-mgr',

package/src/ansible/inventory.ts

@@ -30,7 +30,7 @@ export interface InventoryHost {
   /**
    * The management box deploying to itself (127.0.0.1) uses Ansible's
    * local connection — no SSH, no ansible_host/key. See
-   * v2/CELILO_BOOTSTRAP_VIRTUAL_PACKAGE.md.
+   * openspec/specs/bootstrap-meta-package/spec.md.
    */
   local?: boolean;
 }
@@ -201,7 +201,7 @@ export function buildHostVars(moduleId: string, db: DbClient): Record<string, un
   }
 
   // The host's IP is sourced from the deployed-systems model now, not a
-  // `target_ip` config row (v2/MODULE_SYSTEMS_ADDRESSING.md). Emit it as the
+  // `target_ip` config row (openspec/specs/module-systems-addressing/spec.md). Emit it as the
   // `target_ip` host_var so Ansible templates that reference `{{ target_ip }}`
   // (zone files, DNS record tasks) keep working. Single-system modules have one.
   const recordedSystems = getModuleSystems(moduleId, db);
@@ -266,7 +266,7 @@ export function extractInventoryHost(moduleId: string, db: DbClient): InventoryH
   }
 
   // The host's IP now comes from the deployed-systems model, not a `target_ip`
-  // config row (v2/MODULE_SYSTEMS_ADDRESSING.md). Inject it so the
+  // config row (openspec/specs/module-systems-addressing/spec.md). Inject it so the
   // ansible_host derivation below and the Ansible `{{ target_ip }}` host_var
   // (zone files, DNS record tasks) resolve. Single-system modules have one.
   const recordedSystems = getModuleSystems(moduleId, db);

package/src/api/protocol.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { translateOutputLine } from './protocol';
+import { translateOutputLine } from '@celilo/core';
 
 describe('translateOutputLine', () => {
   test('start marker → progress start', () => {

package/src/api/remote-client.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { type RemoteTransport, resolveRemote, runRemoteClient } from './remote-client';
+import { type RemoteTransport, resolveRemote, runRemoteClient } from '@celilo/core';
 
 const argv = (rest: string[]) => ['bun', 'celilo', ...rest];
 

package/src/api/serve.ts

@@ -12,16 +12,16 @@
  */
 
 import { createInterface } from 'node:readline';
-import { parseArguments } from '../cli/parser';
-import { getEventBusPath } from '../config/paths';
-import { isAuthorized } from '../services/api-access';
-import { type WireInterview, startRemoteResponder } from '../services/remote-responder';
 import {
   API_PROTOCOL_VERSION,
   ClientMessageSchema,
   type ServerMessage,
   translateOutputLine,
-} from './protocol';
+} from '@celilo/core';
+import { parseArguments } from '../cli/parser';
+import { getEventBusPath } from '../config/paths';
+import { isAuthorized } from '../services/api-access';
+import { type WireInterview, startRemoteResponder } from '../services/remote-responder';
 
 /** Exit code returned to the client when authz denies a command. */
 const EXIT_PERMISSION_DENIED = 126;