@celilo/cli 0.8.1 → 0.9.0

package/AGENTS.md

@@ -0,0 +1,86 @@
+# AGENTS.md — `@celilo/cli`
+
+Celilo is a **home-lab orchestration system**: you describe infrastructure as
+**modules**, and celilo deploys them onto a fleet (Proxmox LXC/VM) and wires them
+together through versioned **capabilities**. This file orients an AI agent to
+build and ship apps on celilo. **Read the local docs below before searching the
+web** — they are the source of truth; the hosted copies at
+`https://celilo.computer/docs` lag them.
+
+## Mental model (learn these five things)
+
+- **Module** — a directory with a `manifest.yml` and `celilo/scripts/` hooks,
+  packaged into a `.netapp` artifact and published to **celilo-registry**.
+  Everything celilo deploys is a module.
+- **Capability** — a module `provides:` capabilities (e.g. `public_web`, `idp`,
+  `source_forge`) at a **versioned contract**, and consumers `requires:` them.
+  Consumers bind to the **capability** version (`provides.capabilities[].version`)
+  — *not* the module's own `version`. Bump the capability version on a contract
+  change; that's the load-bearing semver.
+- **Hook** — a lifecycle script (`on_install`, `health_check`, `on_backup`, …) in
+  `celilo/scripts/`, written with `defineHook(...)` from `@celilo/capabilities`.
+  Hooks receive typed clients for the capabilities they `requires`/`optional`.
+- **Build bus** — app repo CI publishes a `.netapp` to celilo-registry →
+  celilo-mgr **polls** → `module upgrade` → deploy → verify. No manual hop.
+- **Versioning** — `manifest.yml#version` is the **payload** version; `+N` is the
+  recipe revision; `version_source` declares how the version is set. See below.
+
+## Building an app (the happy path)
+
+An **app** is a module that provides no capability (it serves content), so set
+`version_source: { kind: changeset }`.
+
+1. **`manifest.yml`** — `id` (kebab-case), `celilo_contract: "1.0"`, `version`,
+   the capabilities you `requires:` (e.g. `public_web`, `idp`), `variables`,
+   `hooks`, and `version_source`. Keep the schema directive on line 1 so your
+   editor validates:
+   `# yaml-language-server: $schema=../../schemas/module-manifest.schema.json`
+2. **Hooks** in `celilo/scripts/` — at least `on_install` (provision) and
+   `health_check`. Use `defineHook`; required capabilities are typed non-null.
+3. **CI/CD** — copy the reference workflows + add the `register-forge` deploy
+   hook so your repo gets a scoped publish token (see `APP_CI_REFERENCE.md`).
+4. **Version with changesets** — `celilo module changeset --bump <major|minor|
+   patch>` in each behaviour-changing PR; `celilo module version` stamps
+   `manifest.yml#version` + CHANGELOG at release. Pick the bump by deploy **blast
+   radius** (major ⇒ safe deploy w/ backup; patch ⇒ fast).
+5. **Ship** — `celilo module check .` then `celilo module publish .`. On the
+   fleet: `module update` (registry sweep) → `module deploy <id>` → `module
+   health`.
+
+## CLI you'll use
+
+```
+celilo module import <name|path>        # pull a module
+celilo module check [dir]               # validate: schema, capabilities, git-hygiene
+celilo module changeset --bump <b> -m … # author a version changeset (module-id keyed)
+celilo module version [dir]             # stamp version+CHANGELOG from changesets
+celilo module publish [dir]             # build .netapp + publish to celilo-registry
+celilo module deploy <id> / update / health   # deploy + verify on the fleet
+```
+
+## Conventions / rules
+
+- Module `id` is **kebab-case**; pin `celilo_contract: "1.0"`.
+- **`version_source`** picks how `version` is sourced: `changeset` (apps/content —
+  authored via changesets, ordered by `+N`), `pin` (wraps upstream software —
+  `version` = the installed upstream version, resolver-checked), `recipe`
+  (config-only modules — no payload version; `+N` orders). Default `recipe`.
+- The capability **contract** semver lives in `provides.capabilities[].version`,
+  independent of the module `version`. Don't conflate them.
+- **Never hand-edit `schemas/module-manifest.schema.json`** — it's generated from
+  `src/manifest/schema.ts` via `bun run export:schema`.
+- Validate before publishing; `celilo module check` mirrors the publish gates.
+
+## Doc map (read in this order)
+
+- `./CELILO_SUBSYSTEMS.md` — map of the infrastructure primitives celilo already
+  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).
+- `./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`.
+- `../../schemas/module-manifest.schema.json` — the manifest contract.
+- `https://celilo.computer/docs` — hosted docs (LAN; the repo docs lead).

package/CELILO_CORE_MODULES.md

@@ -0,0 +1,61 @@
+# Celilo Core Modules
+
+**What this is:** the production modules celilo ships in `modules/` — the infrastructure celilo
+actually *deploys*. Companion to [CELILO_SUBSYSTEMS.md](./CELILO_SUBSYSTEMS.md) (which maps
+celilo's own engine). Use this to know what already exists before building a new module, and to
+understand how the fleet wires together via capabilities.
+
+Each entry: `module id` — what it is — **provides** / **requires** capabilities. Its source is
+`modules/<id>/manifest.yml`; capability contracts are listed in
+[CELILO_SUBSYSTEMS.md](./CELILO_SUBSYSTEMS.md).
+
+> **Paths below are relative to the celilo source-repo root** (e.g. `modules/caddy/manifest.yml`)
+> — references into the source tree, not links relative to this file (this doc also ships inside
+> the `@celilo/cli` npm package). Re-grep manifests if an entry looks stale.
+
+> How the graph closes: a public app (`requires: public_web`) is served by **caddy**, which
+> `requires: dns_registrar` (**namecheap**) to publish its name and `firewall` (**greenwave** /
+> **iptables**) to open the port. Internal name resolution comes from a **dns_internal** provider
+> (**knot-unbound-internal** / **technitium**). Identity comes from **authentik** (`idp`). That's
+> the whole edge: DNS + firewall + ingress + identity, each a swappable provider module.
+
+## 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`.
+- **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`.
+
+## Public edge (ingress / identity)
+
+- **caddy** — reverse proxy with automatic HTTPS (HTTP-01 ACME); the standard HTTPS ingress. **provides:** `public_web`. **requires:** `dns_registrar`, `firewall`.
+- **authentik** — Authentik identity provider with OIDC (Docker Compose: server, worker, Postgres, Redis). **provides:** `idp`. **requires:** `public_web`, `dns_registrar`, `firewall`.
+
+## 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-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-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 as a pass-through disk cache (proxies upstream). **requires:** `public_web`, `dns_registrar`. See `v2/NPM_CACHE_NODE.md`.
+
+## Applications
+
+- **homebridge** — HomeKit bridge for smart-home devices (VeSync, Leviton, Lutron, TP-Link, Tuya). No capabilities (leaf app).
+
+## E2E fixtures & probes (not production apps)
+
+- **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.
+
+## Archived / superseded
+
+`modules/archive/` holds retired modules — **dns-external** (VPS authoritative DNS + WireGuard, superseded by the `dns_internal`/`dns_registrar` split), **gmail** (email-reading capability), **namecheap-api** (registrar-config via Namecheap API, superseded by the **namecheap** DDNS module). Reference only; not deployed.

package/CELILO_SUBSYSTEMS.md

@@ -0,0 +1,83 @@
+# Celilo Subsystem Inventory
+
+**What this is:** a map of infrastructure primitives celilo **already implements**, with the
+entry-point file for each. It exists so agents stop reinventing features (the trigger case:
+IP/VMID allocation, which is already IPAM).
+
+**The rule:** Assume celilo already provides any infrastructure primitive (IP/VMID
+allocation, secrets, DNS, firewall, cross-module data, packaging, event scheduling).
+Before proposing to build one — or asking the operator how to do it — grep this
+inventory / the codebase and cite what you found. Only raise a question if the search
+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)
+(the production modules celilo ships).
+
+> **All file paths below are relative to the celilo source-repo root** (e.g.
+> `apps/celilo/src/ipam/allocator.ts`). They are references into the source tree, not links
+> relative to this file — this doc also ships inside the `@celilo/cli` npm package, where the
+> wider repo isn't present. Paths drift; if an entry looks wrong, re-grep and fix it here.
+
+---
+
+## Allocation & infrastructure selection
+
+- **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.
+
+## Capability system (cross-module data & functions)
+
+- **Define a capability function** — `packages/capabilities/src/define-capability-function.ts` — `defineCapabilityFunction`.
+- **Canonical capability registry** — `packages/capabilities/src/capability-registry.ts` — `KNOWN_CAPABILITY_NAMES` (the authoritative list), `CapabilityRegistry` type. Public surface: `packages/capabilities/src/index.ts`.
+- **Loader (wires provider factories into hook contexts)** — `apps/celilo/src/hooks/capability-loader.ts` — `loadCapabilityFunctions`, `resolveFirewallNatIp`.
+- **Ledger wrappers (stateful capabilities)** — `apps/celilo/src/services/dns-registrations.ts` (`withDnsRegistrationLedger`), `apps/celilo/src/services/dns-internal-records.ts` (`withDnsInternalLedger`).
+
+### Known capabilities (impl → provider module)
+
+| capability | impl | provider module(s) |
+|---|---|---|
+| `public_web` | `packages/capabilities/src/public-web.ts` (`createPublicWeb`) | 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 |
+| `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) |
+
+## 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`.
+- **Deploy pipeline** — `apps/celilo/src/services/module-deploy.ts`.
+- **DNS provider backfill** (re-emit registrations when a provider deploys) — `apps/celilo/src/services/dns-provider-backfill.ts` — `isDnsInternalProvider`, `backfillProviderDns`.
+- **Base-module aspects (fan-out across the fleet)** — `apps/celilo/src/services/aspect-runner.ts` — `planAspectFanOut`, `runAspectFanOut`, `maybeRunAspectForTrigger`. Aspect content lives in `modules/<m>/base-module-aspect/` (e.g. knot-unbound-internal, technitium).
+
+## Generation & templating
+
+- **Generator** — `apps/celilo/src/templates/generator.ts` — `generateTemplates` (orchestration), plus Terraform/Ansible file handling.
+- **Variable resolution** — `apps/celilo/src/variables/resolver.ts` (parser: `apps/celilo/src/variables/parser.ts`). Supported prefixes: `$self`, `$system`, `$secret`, `$system_secret`, `$capability`, `$infra`.
+
+## Secrets
+
+- **Vault / encryption** — `apps/celilo/src/secrets/vault.ts` (`deriveVaultPassword`, `getVaultPassword` — Ansible Vault) and `apps/celilo/src/secrets/encryption.ts` (`encryptSecret`/`decryptSecret`, AES-256-GCM).
+
+## Packaging, registry & publish
+
+- **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).
+
+## Persistence
+
+- **DB schema** — `apps/celilo/src/db/schema.ts`. Client: `apps/celilo/src/db/client.ts`. Migration runner: `apps/celilo/src/db/migrate.ts`. Migrations: `apps/celilo/drizzle/`.
+
+## Events
+
+- **Event bus** — `packages/event-bus/src/index.ts` — `Bus`, `openBus`, `defineEvents`, `defineHandler`, `runDispatcher`, pattern matching + timer ticks (`emitDueTimerTicks`, `retentionSweep`).
+
+## E2E simulation
+
+- **cele2e harness** — `packages/e2e/src/` — `runner.ts`, `container-manager.ts` (`startNetwork`, `reconnectNetwork`), `network-builder.ts` (`NetworkBuilder`).
+- **Run wrapper** — `infra/scripts/cele2e-run.sh` lives in the separate `infra/` clone, **not** in this repo. See the cele2e section of the repo-root `CLAUDE.md` for the operator workflow.

package/drizzle/0012_module_systems_sizing.sql

@@ -0,0 +1,3 @@
+ALTER TABLE `module_systems` ADD `cpu` integer;--> statement-breakpoint
+ALTER TABLE `module_systems` ADD `memory` integer;--> statement-breakpoint
+ALTER TABLE `module_systems` ADD `disk` integer;

package/drizzle/0013_dns_view_overrides.sql

@@ -0,0 +1 @@
+ALTER TABLE `dns_internal_records` ADD `zone_routable_ip` text;

package/drizzle/meta/_journal.json

@@ -85,6 +85,20 @@
       "when": 1781481660000,
       "tag": "0011_backups_name",
       "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "6",
+      "when": 1781481720000,
+      "tag": "0012_module_systems_sizing",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "6",
+      "when": 1782456724000,
+      "tag": "0013_dns_view_overrides",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -11,7 +11,10 @@
     "src/",
     "drizzle/",
     "schemas/",
-    "tsconfig.json"
+    "tsconfig.json",
+    "AGENTS.md",
+    "CELILO_SUBSYSTEMS.md",
+    "CELILO_CORE_MODULES.md"
   ],
   "keywords": [
     "celilo",
@@ -52,7 +55,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1024.0",
-    "@celilo/capabilities": "^0.5.0",
+    "@celilo/capabilities": "^0.6.0",
     "@celilo/cli-display": "^0.1.9",
     "@celilo/event-bus": "^0.1.7",
     "@clack/prompts": "^1.1.0",

package/src/capabilities/well-known.test.ts

@@ -27,7 +27,9 @@ describe('Well-Known Capabilities Registry', () => {
     test('should have dns_internal capability', () => {
       expect(WELL_KNOWN_CAPABILITIES.dns_internal).toBeDefined();
       expect(WELL_KNOWN_CAPABILITIES.dns_internal.canonical_hostname).toBe('dns-int');
-      expect(WELL_KNOWN_CAPABILITIES.dns_internal.required_zone).toBe('internal');
+      // ISS-0156: the resolver moved to a protected zone (dmz) so it can see
+      // protected-zone query sources for split-horizon views.
+      expect(WELL_KNOWN_CAPABILITIES.dns_internal.required_zone).toBe('dmz');
       expect(WELL_KNOWN_CAPABILITIES.dns_internal.zone_enforced).toBe(true);
     });
 
@@ -140,10 +142,11 @@ describe('Well-Known Capabilities Registry', () => {
       expect(result.error).toContain("Capability 'auth' requires zone='secure'");
     });
 
-    test('should validate correct zone for dns_internal', () => {
-      const result = validateZoneRequirement('dns_internal', 'internal');
-
-      expect(result.valid).toBe(true);
+    test('should validate correct zone for dns_internal (dmz — ISS-0156)', () => {
+      expect(validateZoneRequirement('dns_internal', 'dmz').valid).toBe(true);
+      // The old `internal` placement is now rejected — the resolver must be in a
+      // protected zone to see protected-zone query sources for split-horizon.
+      expect(validateZoneRequirement('dns_internal', 'internal').valid).toBe(false);
     });
 
     test('should allow dns_registrar in any zone (zone_enforced=false)', () => {
@@ -231,8 +234,10 @@ describe('Well-Known Capabilities Registry', () => {
       expect(WELL_KNOWN_CAPABILITIES.database.required_zone).toBe('secure');
     });
 
-    test('internal services must be in internal zone', () => {
-      expect(WELL_KNOWN_CAPABILITIES.dns_internal.required_zone).toBe('internal');
+    test('the internal DNS resolver lives in the dmz (ISS-0156)', () => {
+      // Moved out of `internal`: the resolver must see protected-zone query
+      // sources for source-based split-horizon views (v2/INTERNAL_DNS_ZONE_VIEWS.md).
+      expect(WELL_KNOWN_CAPABILITIES.dns_internal.required_zone).toBe('dmz');
     });
   });
 });

package/src/capabilities/well-known.ts

@@ -74,12 +74,20 @@ export const WELL_KNOWN_CAPABILITIES: Record<string, WellKnownCapability> = {
 
   /**
    * dns_internal - Internal DNS resolver
-   * Example: Technitium DNS server for split-horizon LAN resolution
-   * Security: Internal zone (backbone service reachable from all zones)
+   * Example: Technitium / knot-unbound for split-horizon DNS
+   * Security: a PROTECTED zone (dmz), NOT `internal` (ISS-0156,
+   * v2/INTERNAL_DNS_ZONE_VIEWS.md). The resolver must see each querying client's
+   * real source IP to serve source-based split-horizon views; fw-main NATs
+   * protected↔`internal`, so an `internal`-placed resolver sees every protected
+   * query as fw-main's address and can't tell the zones apart. Placed in `dmz`
+   * (a protected zone — protected↔protected is not NAT'd) it sees real
+   * protected-zone sources; `internal` devices reach it via a firewall
+   * DNS-ingress DNAT. The operator accepted the modest posture change (the
+   * `internal` zone is itself un-managed). zone_enforced stays true — just to dmz.
    */
   dns_internal: {
     canonical_hostname: 'dns-int',
-    required_zone: 'internal',
+    required_zone: 'dmz',
     zone_enforced: true,
     data_schema: {
       server: {

package/src/cli/command-registry.ts

@@ -1090,7 +1090,7 @@ export const COMMANDS: CommandDef[] = [
   },
   {
     name: 'proxmox',
-    description: 'Proxmox cluster introspection (nodes, capacity)',
+    description: 'Proxmox cluster introspection (nodes, capacity, instance sizing)',
     subcommands: [
       {
         name: 'node',
@@ -1103,6 +1103,70 @@ export const COMMANDS: CommandDef[] = [
           },
         ],
       },
+      {
+        name: 'vm',
+        description: 'celilo-provisioned VM sizing',
+        subcommands: [
+          {
+            name: 'list',
+            description: 'List celilo VMs with desired vs actual size',
+            args: [{ name: 'service-id', description: 'Proxmox service (optional if only one)' }],
+          },
+          {
+            name: 'resize',
+            description: 'Resize a celilo VM (canonical size + reconcile)',
+            args: [{ name: 'name', description: 'Instance name (module/hostname)' }],
+            flags: [
+              { name: 'memory', description: 'New RAM in MB', takesValue: true },
+              { name: 'cpu', description: 'New vCPU count', takesValue: true },
+              { name: 'force', description: 'Override the node capacity check', takesValue: false },
+              {
+                name: 'allow-reboot',
+                description: 'Approve the stop/start a resize needs',
+                takesValue: false,
+              },
+              { name: 'skip-backup', description: 'Skip the pre-resize backup', takesValue: false },
+              {
+                name: 'yes',
+                description: 'Auto-approve reboot + backup (headless)',
+                takesValue: false,
+              },
+            ],
+          },
+        ],
+      },
+      {
+        name: 'ct',
+        description: 'celilo-provisioned container (LXC) sizing',
+        subcommands: [
+          {
+            name: 'list',
+            description: 'List celilo containers with desired vs actual size',
+            args: [{ name: 'service-id', description: 'Proxmox service (optional if only one)' }],
+          },
+          {
+            name: 'resize',
+            description: 'Resize a celilo container (canonical size + reconcile)',
+            args: [{ name: 'name', description: 'Instance name (module/hostname)' }],
+            flags: [
+              { name: 'memory', description: 'New RAM in MB', takesValue: true },
+              { name: 'cpu', description: 'New vCPU count', takesValue: true },
+              { name: 'force', description: 'Override the node capacity check', takesValue: false },
+              {
+                name: 'allow-reboot',
+                description: 'Approve the stop/start a resize needs',
+                takesValue: false,
+              },
+              { name: 'skip-backup', description: 'Skip the pre-resize backup', takesValue: false },
+              {
+                name: 'yes',
+                description: 'Auto-approve reboot + backup (headless)',
+                takesValue: false,
+              },
+            ],
+          },
+        ],
+      },
     ],
   },
   {

package/src/cli/commands/module-upgrade.test.ts

@@ -1,11 +1,20 @@
 import { describe, expect, test } from 'bun:test';
+import type { ModuleManifest } from '../../manifest/schema';
 import {
   type PollCandidate,
+  needsPreUpgradeBackup,
   pickAutoUpgrade,
   pickUpgradePolicy,
   selectPollTargets,
 } from './module-upgrade';
 
+/** Minimal manifest fixture; only `hooks` matters for the backup gate. */
+function manifest(hooks?: ModuleManifest['hooks']): ModuleManifest {
+  return { id: 'forgejo', name: 'Forgejo', version: '0.3.0', hooks } as ModuleManifest;
+}
+const withBackupHook = manifest({ on_backup: { script: './scripts/backup.ts', timeout: 300000 } });
+const noBackupHook = manifest({ on_install: { script: './scripts/setup.ts', timeout: 180000 } });
+
 describe('pickUpgradePolicy (ISS-0138 — config override > manifest default > by-semver)', () => {
   test('operator config wins over the manifest default', () => {
     expect(pickUpgradePolicy('always-safe', 'always-fast')).toBe('always-safe');
@@ -80,3 +89,23 @@ describe('selectPollTargets (ISS-0139 — opted-in + a newer registry version)',
     expect(targets.map((t) => t.moduleId)).toEqual(['a']);
   });
 });
+
+describe('needsPreUpgradeBackup (ISS-0168 — gate on the TARGET version manifest)', () => {
+  // The regression: the upgrade that FIRST adds on_backup must still back up.
+  // The installed version lacked the hook; the target (passed here) adds it.
+  test('safe posture + target adds on_backup → backs up', () => {
+    expect(needsPreUpgradeBackup('safe', withBackupHook)).toBe(true);
+  });
+
+  test('safe posture + target has no on_backup → does not back up', () => {
+    expect(needsPreUpgradeBackup('safe', noBackupHook)).toBe(false);
+  });
+
+  test('fast posture (patch/revision) never backs up, even with on_backup', () => {
+    expect(needsPreUpgradeBackup('fast', withBackupHook)).toBe(false);
+  });
+
+  test('safe posture + no hooks block at all → does not back up', () => {
+    expect(needsPreUpgradeBackup('safe', manifest(undefined))).toBe(false);
+  });
+});

package/src/cli/commands/module-upgrade.ts

@@ -21,7 +21,11 @@ import { modules } from '../../db/schema';
 import type { ModuleManifest } from '../../manifest/schema';
 import { RegistryClient } from '../../registry/client';
 import { createModuleBackup } from '../../services/backup-create';
-import { type UpgradePolicy, resolveDeployPosture } from '../../services/deploy-posture';
+import {
+  type DeployPosture,
+  type UpgradePolicy,
+  resolveDeployPosture,
+} from '../../services/deploy-posture';
 import { runModuleHealthCheck } from '../../services/health-runner';
 import { getModuleConfigValue } from '../../services/module-config';
 import { deployModule } from '../../services/module-deploy';
@@ -62,6 +66,23 @@ export function pickAutoUpgrade(
   return fromManifest ?? false;
 }
 
+/**
+ * Pure (Rule 10): does this upgrade need a pre-deploy backup? Yes IFF the
+ * posture is "safe" (a minor/major bump) AND the TARGET version's manifest
+ * declares an on_backup hook.
+ *
+ * The `targetManifest` MUST be the version being upgraded TO (read back after
+ * the def is refreshed), never the installed one — gating on the installed
+ * manifest skips the backup on the very upgrade that introduces the hook
+ * (ISS-0168).
+ */
+export function needsPreUpgradeBackup(
+  posture: DeployPosture,
+  targetManifest: ModuleManifest,
+): boolean {
+  return posture === 'safe' && Boolean(targetManifest.hooks?.on_backup);
+}
+
 export interface PollCandidate {
   moduleId: string;
   installed: string;
@@ -116,13 +137,34 @@ async function upgradeOneModule(
   flags: Record<string, string | boolean>,
 ): Promise<CommandResult> {
   const moduleId = mod.id;
-  const manifest = mod.manifestData as ModuleManifest;
 
-  // Posture.
+  // Update FIRST (refresh stored def). Every downstream decision — the
+  // backup gate and the posture policy — must consult the TARGET version's
+  // manifest, not the installed one. Gating on the pre-update manifest skipped
+  // the on_backup hook on the very upgrade that INTRODUCES it (e.g. a stateful
+  // module that first ships backup support doesn't protect its own next
+  // upgrade) — ISS-0168.
+  const updated = await fetchAndUpdate(client, moduleId, targetVersion, db, flags);
+  if (updated.status !== 'success') {
+    const why = updated.status === 'failed' ? updated.error : updated.reason;
+    return { success: false, error: `Update failed for ${moduleId}: ${why}` };
+  }
+
+  // Read the target def back: fetchAndUpdate persisted it but doesn't return
+  // the manifest. Fall back to the pre-update manifest only if the row somehow
+  // vanished (it won't on the success path).
+  const updatedRow = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  const targetManifest =
+    (updatedRow?.manifestData as ModuleManifest | undefined) ??
+    (mod.manifestData as ModuleManifest);
+
+  // Posture. Version delta is installed→target; the policy comes from the
+  // TARGET manifest (the version being installed declares its upgrade risk),
+  // with an operator config override still winning.
   const configPolicy = getModuleConfigValue(moduleId, 'upgrade_policy');
   const modulePolicy = pickUpgradePolicy(
     typeof configPolicy?.value === 'string' ? configPolicy.value : undefined,
-    (manifest as ModuleManifest & { upgrade_policy?: string }).upgrade_policy,
+    (targetManifest as ModuleManifest & { upgrade_policy?: string }).upgrade_policy,
   );
   // Per-release deploy_posture override lives in the .netapp release metadata;
   // reading it requires fetching the package first. Deferred — the classifier
@@ -135,27 +177,18 @@ async function upgradeOneModule(
   });
   log.info(`Upgrading ${moduleId} ${mod.version} → ${targetVersion} (${posture} — ${reason})`);
 
-  // Update (refresh stored def).
-  const updated = await fetchAndUpdate(client, moduleId, targetVersion, db, flags);
-  if (updated.status !== 'success') {
-    const why = updated.status === 'failed' ? updated.error : updated.reason;
-    return { success: false, error: `Update failed for ${moduleId}: ${why}` };
-  }
-
-  // Safe → back up first (when there's a backup hook).
-  if (posture === 'safe') {
-    if (manifest.hooks?.on_backup) {
-      const backup = await createModuleBackup(moduleId);
-      if (!backup.success) {
-        return {
-          success: false,
-          error: `Pre-upgrade backup failed for ${moduleId}: ${backup.error}`,
-        };
-      }
-      log.success(`Backed up ${moduleId} before deploy`);
-    } else {
-      log.warn(`${moduleId} has no on_backup hook — proceeding without a pre-upgrade backup`);
+  // Safe → back up first, gated on the TARGET manifest's on_backup hook.
+  if (needsPreUpgradeBackup(posture, targetManifest)) {
+    const backup = await createModuleBackup(moduleId);
+    if (!backup.success) {
+      return {
+        success: false,
+        error: `Pre-upgrade backup failed for ${moduleId}: ${backup.error}`,
+      };
     }
+    log.success(`Backed up ${moduleId} before deploy`);
+  } else if (posture === 'safe') {
+    log.warn(`${moduleId} has no on_backup hook — proceeding without a pre-upgrade backup`);
   }
 
   // Deploy (idempotent).