Track HiveGrid Cloud planning reference

hivegrid-cloud/packages/cli/README.md

@@ -0,0 +1,41 @@
+# @toolctrl/cli
+
+Operator CLI for the ToolCTRL boilerplate. Currently ships the `backup` family
+of subcommands. The entrypoint is `bin/toolctrl-cli.mjs`, wired up via
+[citty](https://github.com/unjs/citty) for consistent subcommand handling.
+
+## Subcommands
+
+| Command           | Description                                                            |
+| ----------------- | ---------------------------------------------------------------------- |
+| `backup:create`   | Dump Postgres + (optional) Storage + (optional) ClickHouse, encrypt, upload to S3. |
+| `backup:list`     | List S3-stored backups with manifest metadata.                         |
+| `backup:restore`  | Download, decrypt, extract; restore Postgres + Storage from a backup.  |
+| `backup:verify`   | Test-restore Postgres dump into a `verify_<uuid>` schema, sanity-check. |
+| `backup:rotate`   | Apply daily/weekly/monthly retention policy against the backup bucket. |
+
+See [`docs/operations/backup.md`](../../docs/operations/backup.md) for the
+operator runbook (setup, key management, restore drill, troubleshooting).
+
+## Environment variables
+
+The CLI uses a backup-scoped S3 credential set so the backup bucket can be
+isolated from the application bucket:
+
+- `BACKUP_S3_ENDPOINT`, `BACKUP_S3_REGION`, `BACKUP_S3_BUCKET`
+- `BACKUP_S3_ACCESS_KEY_ID`, `BACKUP_S3_SECRET_ACCESS_KEY`
+- `BACKUP_S3_FORCE_PATH_STYLE`
+- `BACKUP_ENCRYPTION` (`age` | `gpg` | `none`, default `age`)
+- `BACKUP_AGE_PUBLIC_KEY` (required when encryption is `age`)
+- `BACKUP_AGE_IDENTITY_FILE` (required for `restore` / `verify` with age)
+- `BACKUP_RETENTION_DAILY` (default `7`)
+- `BACKUP_RETENTION_WEEKLY` (default `4`)
+- `BACKUP_RETENTION_MONTHLY` (default `12`)
+- `BACKUP_INCLUDE_CLICKHOUSE` (`true` to include ClickHouse snapshots)
+
+## Development
+
+```sh
+pnpm --filter @toolctrl/cli test
+pnpm --filter @toolctrl/cli typecheck
+```

hivegrid-cloud/packages/cli/bin/toolctrl-cli.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// Thin shim so the CLI is callable as `toolctrl-cli`.
+// The actual command tree lives in ../src/index.ts and is loaded via tsx in dev,
+// or via the compiled output once the build pipeline produces dist/index.js.
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const distEntry = resolve(__dirname, "../dist/index.js");
+const srcEntry = resolve(__dirname, "../src/index.ts");
+
+const target = existsSync(distEntry) ? distEntry : srcEntry;
+const moduleUrl = pathToFileURL(target).href;
+
+const { runMain } = await import(moduleUrl);
+await runMain();

hivegrid-cloud/packages/cli/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@toolctrl/cli",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./backup": "./src/commands/backup/index.ts"
+  },
+  "bin": {
+    "toolctrl-cli": "./bin/toolctrl-cli.mjs"
+  },
+  "scripts": {
+    "build": "pnpm run typecheck",
+    "test": "vitest run src",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1048.0",
+    "@aws-sdk/lib-storage": "^3.1048.0",
+    "@toolctrl/db": "workspace:*",
+    "@toolctrl/entitlements": "workspace:*",
+    "@toolctrl/exports": "workspace:*",
+    "@toolctrl/feature-flags": "workspace:*",
+    "@toolctrl/form-widget": "workspace:*",
+    "@toolctrl/plugin-runtime": "workspace:*",
+    "@toolctrl/search": "workspace:*",
+    "citty": "^0.1.6",
+    "consola": "^3.4.0",
+    "tar": "^7.4.3",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "@types/tar": "^6.1.13",
+    "aws-sdk-client-mock": "^4.1.0",
+    "typescript": "^5.3.2",
+    "vitest": "^3.2.4"
+  }
+}

hivegrid-cloud/packages/cli/src/commands/_lib/scaffold.test.ts

@@ -0,0 +1,102 @@
+import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  camelCase,
+  createScaffoldResult,
+  kebabCase,
+  pascalCase,
+  pathExists,
+  snakeCase,
+  validateIdentifier,
+  writeScaffoldFile,
+} from "./scaffold.js";
+
+describe("scaffold helpers / string conversions", () => {
+  it.each([
+    ["foo bar", "fooBar"],
+    ["foo-bar-baz", "fooBarBaz"],
+    ["FooBarBaz", "fooBarBaz"],
+    ["foo_bar", "fooBar"],
+  ])("camelCase(%s) === %s", (input, expected) => {
+    expect(camelCase(input)).toBe(expected);
+  });
+
+  it.each([
+    ["foo bar", "FooBar"],
+    ["foo-bar-baz", "FooBarBaz"],
+    ["fooBarBaz", "FooBarBaz"],
+  ])("pascalCase(%s) === %s", (input, expected) => {
+    expect(pascalCase(input)).toBe(expected);
+  });
+
+  it("kebabCase + snakeCase", () => {
+    expect(kebabCase("FooBarBaz")).toBe("foo-bar-baz");
+    expect(snakeCase("FooBarBaz")).toBe("foo_bar_baz");
+  });
+});
+
+describe("scaffold helpers / validateIdentifier", () => {
+  it("accepts valid identifiers", () => {
+    expect(validateIdentifier("foo")).toBe("foo");
+    expect(validateIdentifier("foo-bar")).toBe("foo-bar");
+    expect(validateIdentifier("foo_bar")).toBe("foo_bar");
+  });
+
+  it("rejects empty / invalid input", () => {
+    expect(() => validateIdentifier("")).toThrow(/required/);
+    expect(() => validateIdentifier("1foo")).toThrow(/Invalid/);
+    expect(() => validateIdentifier("foo!bar")).toThrow(/Invalid/);
+  });
+});
+
+describe("scaffold helpers / writeScaffoldFile", () => {
+  let tempRoot: string;
+
+  beforeEach(async () => {
+    tempRoot = await mkdtemp(path.join(tmpdir(), "toolctrl-cli-scaffold-"));
+  });
+
+  afterEach(async () => {
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  it("writes the file in non-dry-run mode and records it on the result", async () => {
+    const result = createScaffoldResult(false);
+    const target = path.join(tempRoot, "nested", "out.txt");
+    await writeScaffoldFile({ targetPath: target, contents: "hello", dryRun: false, result });
+
+    expect(result.files).toHaveLength(1);
+    expect(result.files[0]).toMatchObject({ path: target, contents: "hello" });
+
+    const written = await readFile(target, "utf8");
+    expect(written).toBe("hello");
+  });
+
+  it("records the write but does NOT touch the FS in dry-run mode", async () => {
+    const result = createScaffoldResult(true);
+    const target = path.join(tempRoot, "ghost.txt");
+    await writeScaffoldFile({ targetPath: target, contents: "ghost", dryRun: true, result });
+
+    expect(result.files).toHaveLength(1);
+    await expect(stat(target)).rejects.toThrow();
+  });
+
+  it("refuses to overwrite an existing file", async () => {
+    const target = path.join(tempRoot, "existing.txt");
+    await writeFile(target, "old", "utf8");
+
+    const result = createScaffoldResult(false);
+    await expect(
+      writeScaffoldFile({ targetPath: target, contents: "new", dryRun: false, result }),
+    ).rejects.toThrow(/already exists/);
+  });
+
+  it("pathExists distinguishes existing vs missing paths", async () => {
+    const target = path.join(tempRoot, "maybe.txt");
+    expect(await pathExists(target)).toBe(false);
+    await writeFile(target, "x", "utf8");
+    expect(await pathExists(target)).toBe(true);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/_lib/scaffold.ts

@@ -0,0 +1,152 @@
+/**
+ * Shared helpers for the `toolctrl create …` / `toolctrl add …` scaffolding
+ * generators (Phase 08 / task #60).
+ *
+ * Design goals:
+ *   - **Safe by default.** Generators NEVER overwrite existing files. If a
+ *     target path already exists, the helper throws — callers surface the
+ *     error and exit with a non-zero status. Use `--force` semantics at the
+ *     command level if a re-generation is needed (not implemented yet —
+ *     `git checkout` is the documented escape hatch).
+ *   - **Dry-run-friendly.** All write operations go through `writeFile` which
+ *     respects a `dryRun` flag and records the would-have-been writes on a
+ *     `ScaffoldResult.files` array. Tests assert on that array directly
+ *     instead of touching the real FS.
+ *   - **No template engine dependency.** We use plain JS tagged templates +
+ *     a tiny `render` helper. Adding eta/handlebars to a Node-only operator
+ *     CLI would mean another pnpm install + bundle bloat for a small win.
+ *
+ * Refs: docs/improvement-plan/08-mobile-cli-storybook-sdk/cli-scaffolding.md
+ */
+import { mkdir, stat, writeFile as fsWriteFile } from "node:fs/promises";
+import path from "node:path";
+
+export type ScaffoldFile = {
+  /** Absolute target path on disk. */
+  path: string;
+  /** Rendered file contents. */
+  contents: string;
+};
+
+export type ScaffoldResult = {
+  /** Files that were (or would be, in dry-run mode) written. */
+  files: ScaffoldFile[];
+  /** Free-form follow-up notes the CLI surfaces to the user. */
+  notes: string[];
+  /** `true` if no FS mutation happened. */
+  dryRun: boolean;
+};
+
+export function createScaffoldResult(dryRun: boolean): ScaffoldResult {
+  return { files: [], notes: [], dryRun };
+}
+
+export type WriteFileOptions = {
+  /** Absolute path the file would be written to. */
+  targetPath: string;
+  /** Already-rendered content. */
+  contents: string;
+  /** When `true` no actual mkdir/write is performed. */
+  dryRun: boolean;
+  /** Mutated in place with the recorded write. */
+  result: ScaffoldResult;
+};
+
+/**
+ * Add a file to the scaffold result, ensuring we never silently overwrite an
+ * existing path. Caller is responsible for `mkdir -p` semantics — we handle
+ * it transparently in non-dry-run mode.
+ */
+export async function writeScaffoldFile(options: WriteFileOptions): Promise<void> {
+  const { targetPath, contents, dryRun, result } = options;
+  const exists = await pathExists(targetPath);
+  if (exists) {
+    throw new Error(
+      `Target already exists: ${targetPath}. Refusing to overwrite. Delete the file or pick a different name.`,
+    );
+  }
+
+  result.files.push({ path: targetPath, contents });
+
+  if (dryRun) return;
+
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  await fsWriteFile(targetPath, contents, "utf8");
+}
+
+export async function pathExists(target: string): Promise<boolean> {
+  try {
+    await stat(target);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+/** Convert "foo bar-baz" → "fooBarBaz". */
+export function camelCase(input: string): string {
+  return splitWords(input)
+    .map((word, index) => (index === 0 ? word.toLowerCase() : capitalize(word)))
+    .join("");
+}
+
+/** Convert "foo bar-baz" → "FooBarBaz". */
+export function pascalCase(input: string): string {
+  return splitWords(input).map(capitalize).join("");
+}
+
+/** Convert "FooBarBaz" → "foo-bar-baz". */
+export function kebabCase(input: string): string {
+  return splitWords(input)
+    .map((word) => word.toLowerCase())
+    .join("-");
+}
+
+/** Convert "FooBarBaz" → "foo_bar_baz". */
+export function snakeCase(input: string): string {
+  return splitWords(input)
+    .map((word) => word.toLowerCase())
+    .join("_");
+}
+
+function capitalize(word: string): string {
+  if (!word) return word;
+  return word[0]!.toUpperCase() + word.slice(1).toLowerCase();
+}
+
+function splitWords(input: string): string[] {
+  return input
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/[-_.\s]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+/**
+ * Lightweight identifier validator. Rejects empty strings, leading digits,
+ * and anything that isn't `[A-Za-z0-9_-]`. Used by every generator to avoid
+ * writing files with shell-unsafe names.
+ */
+export function validateIdentifier(name: string, label: string = "name"): string {
+  const trimmed = name.trim();
+  if (!trimmed) {
+    throw new Error(`${label} is required.`);
+  }
+  if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(trimmed)) {
+    throw new Error(
+      `Invalid ${label}: "${name}". Must start with a letter and contain only letters, digits, '-' or '_'.`,
+    );
+  }
+  return trimmed;
+}
+
+/**
+ * Resolve the repo-root path used as base for generators. We trust the
+ * working directory the operator invoked the CLI from (consistent with the
+ * existing `backup` / `tenant` commands).
+ */
+export function resolveRepoRoot(cwd: string = process.cwd()): string {
+  return cwd;
+}

hivegrid-cloud/packages/cli/src/commands/add/event-type.test.ts

@@ -0,0 +1,60 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { generateEventType } from "./event-type.js";
+
+describe("add event-type generator", () => {
+  let tempRoot: string;
+
+  beforeEach(async () => {
+    tempRoot = await mkdtemp(path.join(tmpdir(), "toolctrl-cli-event-type-"));
+  });
+
+  afterEach(async () => {
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  it("emits one file under workflowEngine/eventTypes/_generated/", async () => {
+    const result = await generateEventType({
+      name: "crm.contact.created",
+      repoRoot: tempRoot,
+      dryRun: true,
+    });
+    const rels = result.files.map((f) => path.relative(tempRoot, f.path));
+    expect(rels).toEqual([
+      "apps/web/app/modules/workflowEngine/eventTypes/_generated/crm_contact_created.ts",
+    ]);
+  });
+
+  it("contains zod schema + example payload + handler stub", async () => {
+    const result = await generateEventType({
+      name: "crm.contact.created",
+      repoRoot: tempRoot,
+      dryRun: true,
+    });
+    const file = result.files[0]!;
+    expect(file.contents).toContain('import { z } from "zod"');
+    expect(file.contents).toContain("CrmContactCreatedPayloadSchema");
+    expect(file.contents).toContain("CrmContactCreatedExamplePayload");
+    expect(file.contents).toContain("export async function handleCrmContactCreated");
+    expect(file.contents).toContain("CrmContactCreatedEventTypeSpec");
+    expect(file.contents).not.toContain("TODO");
+  });
+
+  it("rejects non-dotted event names", async () => {
+    await expect(
+      generateEventType({ name: "ContactCreated", repoRoot: tempRoot, dryRun: true }),
+    ).rejects.toThrow(/Invalid event-type/);
+    await expect(generateEventType({ name: "", repoRoot: tempRoot, dryRun: true })).rejects.toThrow(
+      /required/,
+    );
+  });
+
+  it("refuses to overwrite an existing event-type", async () => {
+    await generateEventType({ name: "crm.contact.created", repoRoot: tempRoot, dryRun: false });
+    await expect(
+      generateEventType({ name: "crm.contact.created", repoRoot: tempRoot, dryRun: false }),
+    ).rejects.toThrow(/already exists/);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/add/event-type.ts

@@ -0,0 +1,141 @@
+/**
+ * `toolctrl add event-type <name>` — scaffold a new EntityWebhook
+ * event-type definition (zod schema + example payload + handler stub).
+ *
+ * The workflow engine does not yet expose a single canonical event-type
+ * registry file (see workflowEngine/routes/workflow-engine.api.server.tsx —
+ * only a metatag loader exists today). Until that refactor lands, we
+ * write the event-type spec under
+ * `apps/web/app/modules/workflowEngine/eventTypes/_generated/<name>.ts`,
+ * which the runtime will be able to glob-import once the registry is
+ * extracted.
+ *
+ * Refs: docs/improvement-plan/08-mobile-cli-storybook-sdk/cli-scaffolding.md
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import path from "node:path";
+import {
+  createScaffoldResult,
+  pascalCase,
+  resolveRepoRoot,
+  writeScaffoldFile,
+  type ScaffoldResult,
+} from "../_lib/scaffold.js";
+
+export type GenerateEventTypeOptions = {
+  /** Dotted event name, e.g. "crm.contact.created". */
+  name: string;
+  repoRoot?: string;
+  dryRun?: boolean;
+};
+
+const EVENT_NAME_PATTERN = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9_]*)+$/;
+
+export async function generateEventType(options: GenerateEventTypeOptions): Promise<ScaffoldResult> {
+  const eventName = options.name.trim();
+  if (!eventName) throw new Error("event-type name is required.");
+  if (!EVENT_NAME_PATTERN.test(eventName)) {
+    throw new Error(
+      `Invalid event-type name: "${eventName}". Use dotted lowercase identifiers, e.g. "crm.contact.created".`,
+    );
+  }
+
+  const dryRun = options.dryRun ?? false;
+  const repoRoot = resolveRepoRoot(options.repoRoot);
+  const fileSlug = eventName.replace(/\./g, "_");
+  const typeName = pascalCase(eventName.replace(/\./g, " "));
+
+  const result = createScaffoldResult(dryRun);
+
+  await writeScaffoldFile({
+    targetPath: path.join(
+      repoRoot,
+      "apps/web/app/modules/workflowEngine/eventTypes/_generated",
+      `${fileSlug}.ts`,
+    ),
+    contents: renderEventTypeFile({ eventName, typeName }),
+    dryRun,
+    result,
+  });
+
+  result.notes.push(
+    `Event-type "${eventName}" scaffolded.`,
+    "Register the export in your workflow-engine event registry once the central registry is extracted.",
+  );
+
+  return result;
+}
+
+function renderEventTypeFile({ eventName, typeName }: { eventName: string; typeName: string }): string {
+  return `/**
+ * EntityWebhook event-type: ${eventName}
+ * Generated by toolctrl-cli.
+ */
+import { z } from "zod";
+
+export const ${typeName}EventName = "${eventName}" as const;
+
+export const ${typeName}PayloadSchema = z.object({
+  tenantId: z.string(),
+  occurredAt: z.string().datetime(),
+  // Add domain-specific fields here before wiring the event into production.
+  data: z.record(z.string(), z.unknown()).default({}),
+});
+
+export type ${typeName}Payload = z.infer<typeof ${typeName}PayloadSchema>;
+
+export const ${typeName}ExamplePayload: ${typeName}Payload = {
+  tenantId: "ten_example",
+  occurredAt: "2026-01-01T00:00:00.000Z",
+  data: {},
+};
+
+/**
+ * Handler stub. Wire this into the workflow-engine event dispatcher
+ * once the central registry is extracted (see workflowEngine/lib).
+ */
+export async function handle${typeName}(payload: ${typeName}Payload): Promise<void> {
+  // Replace this no-op with the event dispatcher integration for your domain.
+  void payload;
+}
+
+export const ${typeName}EventTypeSpec = {
+  name: ${typeName}EventName,
+  schema: ${typeName}PayloadSchema,
+  example: ${typeName}ExamplePayload,
+  handler: handle${typeName},
+} as const;
+`;
+}
+
+export const addEventTypeCommand = defineCommand({
+  meta: {
+    name: "event-type",
+    description: "Scaffold an EntityWebhook event-type (zod schema + handler stub).",
+  },
+  args: {
+    name: {
+      type: "positional",
+      required: true,
+      description: "Dotted event name, e.g. \"crm.contact.created\".",
+    },
+    "dry-run": {
+      type: "boolean",
+      required: false,
+      description: "Print the would-be writes without touching the filesystem.",
+    },
+  },
+  async run({ args }) {
+    const result = await generateEventType({ name: args.name, dryRun: args["dry-run"] === true });
+    consola.success(
+      `${result.dryRun ? "[dry-run] " : ""}Generated event-type "${args.name}" — ${result.files.length} file(s).`,
+    );
+    for (const file of result.files) {
+      consola.info(`  ${result.dryRun ? "would write" : "wrote"} ${file.path}`);
+    }
+    for (const note of result.notes) {
+      consola.info(note);
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/add/hook.test.ts

@@ -0,0 +1,47 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { generateHook } from "./hook.js";
+
+describe("add hook generator", () => {
+  let tempRoot: string;
+
+  beforeEach(async () => {
+    tempRoot = await mkdtemp(path.join(tmpdir(), "toolctrl-cli-hook-"));
+  });
+
+  afterEach(async () => {
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  it("emits a hook file under apps/web/app/hooks/_generated/", async () => {
+    const result = await generateHook({ name: "on-contact-created", repoRoot: tempRoot, dryRun: true });
+    const rels = result.files.map((f) => path.relative(tempRoot, f.path));
+    expect(rels).toEqual(["apps/web/app/hooks/_generated/onContactCreated.hook.ts"]);
+  });
+
+  it("file contains a forward-compat header pointing at Phase 06 docs", async () => {
+    const result = await generateHook({ name: "on-foo", repoRoot: tempRoot, dryRun: true });
+    expect(result.files[0]!.contents).toContain("Phase 06");
+    expect(result.files[0]!.contents).toMatch(/registerOnFooHook/);
+    expect(result.files[0]!.contents).toMatch(/triggerOnFooHook/);
+    expect(result.files[0]!.contents).not.toContain("TODO");
+  });
+
+  it("notes mention the plugin SDK migration path", async () => {
+    const result = await generateHook({ name: "on-foo", repoRoot: tempRoot, dryRun: true });
+    expect(result.notes.join("\n")).toMatch(/@toolctrl\/plugin-sdk/);
+  });
+
+  it("refuses to overwrite an existing hook", async () => {
+    await generateHook({ name: "on-foo", repoRoot: tempRoot, dryRun: false });
+    await expect(generateHook({ name: "on-foo", repoRoot: tempRoot, dryRun: false })).rejects.toThrow(
+      /already exists/,
+    );
+  });
+
+  it("rejects invalid hook names", async () => {
+    await expect(generateHook({ name: "1bad", repoRoot: tempRoot, dryRun: true })).rejects.toThrow(/Invalid/);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/add/hook.ts

@@ -0,0 +1,117 @@
+/**
+ * `toolctrl add hook <name>` — scaffold a plugin-hook registration file.
+ *
+ * NOTE: the plugin-system itself (Phase 06) is not yet built. This
+ * generator therefore produces a *stub* with a clear "scaffolding for
+ * future plugin system" header so downstream readers know the API
+ * surface is provisional. Once Phase 06 lands the template will be
+ * upgraded to import the real `@toolctrl/plugin-sdk`.
+ *
+ * Refs: docs/improvement-plan/08-mobile-cli-storybook-sdk/cli-scaffolding.md
+ * Refs: docs/improvement-plan/06-plugin-system/audit-docs.md
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import path from "node:path";
+import {
+  camelCase,
+  createScaffoldResult,
+  pascalCase,
+  resolveRepoRoot,
+  validateIdentifier,
+  writeScaffoldFile,
+  type ScaffoldResult,
+} from "../_lib/scaffold.js";
+
+export type GenerateHookOptions = {
+  name: string;
+  repoRoot?: string;
+  dryRun?: boolean;
+};
+
+export async function generateHook(options: GenerateHookOptions): Promise<ScaffoldResult> {
+  const baseName = validateIdentifier(options.name, "hook name");
+  const dryRun = options.dryRun ?? false;
+  const repoRoot = resolveRepoRoot(options.repoRoot);
+  const camel = camelCase(baseName);
+  const pascal = pascalCase(baseName);
+
+  const result = createScaffoldResult(dryRun);
+  const hookDir = path.join(repoRoot, "apps/web/app/hooks/_generated");
+
+  await writeScaffoldFile({
+    targetPath: path.join(hookDir, `${camel}.hook.ts`),
+    contents: renderHookFile({ camel, pascal }),
+    dryRun,
+    result,
+  });
+
+  result.notes.push(
+    "Phase 06 plugin system is not implemented yet — this hook is a forward-compatible stub.",
+    "Update the import path to @toolctrl/plugin-sdk once Phase 06 ships.",
+  );
+
+  return result;
+}
+
+function renderHookFile({ camel, pascal }: { camel: string; pascal: string }): string {
+  return `/**
+ * Scaffolding for the future plugin-system (Phase 06).
+ *
+ * This file registers the "${camel}" hook. The current implementation
+ * is a no-op because the plugin-runtime is not wired up yet — see
+ * docs/improvement-plan/06-plugin-system/audit-docs.md for the planned
+ * surface. Once the SDK lands, replace the body of \`register${pascal}Hook\`
+ * with the real \`pluginRuntime.registerHook(…)\` call.
+ */
+export type ${pascal}HookPayload = {
+  tenantId: string;
+  // Add domain-specific payload fields before exposing this hook publicly.
+};
+
+export type ${pascal}HookHandler = (payload: ${pascal}HookPayload) => Promise<void> | void;
+
+const handlers: ${pascal}HookHandler[] = [];
+
+export function register${pascal}Hook(handler: ${pascal}HookHandler): () => void {
+  handlers.push(handler);
+  return () => {
+    const idx = handlers.indexOf(handler);
+    if (idx >= 0) handlers.splice(idx, 1);
+  };
+}
+
+export async function trigger${pascal}Hook(payload: ${pascal}HookPayload): Promise<void> {
+  for (const handler of handlers) {
+    await handler(payload);
+  }
+}
+`;
+}
+
+export const addHookCommand = defineCommand({
+  meta: {
+    name: "hook",
+    description: "Scaffold a plugin-hook registration file (Phase 06 forward-compat stub).",
+  },
+  args: {
+    name: { type: "positional", required: true, description: "Hook name (camel/kebab/pascal — normalised)." },
+    "dry-run": {
+      type: "boolean",
+      required: false,
+      description: "Print the would-be writes without touching the filesystem.",
+    },
+  },
+  async run({ args }) {
+    const result = await generateHook({ name: args.name, dryRun: args["dry-run"] === true });
+    consola.success(
+      `${result.dryRun ? "[dry-run] " : ""}Generated hook "${args.name}" — ${result.files.length} file(s).`,
+    );
+    for (const file of result.files) {
+      consola.info(`  ${result.dryRun ? "would write" : "wrote"} ${file.path}`);
+    }
+    for (const note of result.notes) {
+      consola.warn(note);
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/add/index.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { addCommand } from "./index.js";
+
+async function resolveValue<T>(value: T | (() => T) | (() => Promise<T>)): Promise<T> {
+  if (typeof value === "function") {
+    return await (value as () => T | Promise<T>)();
+  }
+  return value;
+}
+
+describe("add command tree", () => {
+  it("exposes hook / event-type / permission subcommands", async () => {
+    const meta = await resolveValue(addCommand.meta);
+    expect(meta).toMatchObject({ name: "add" });
+
+    const subs = await resolveValue(addCommand.subCommands);
+    expect(Object.keys(subs ?? {}).sort()).toEqual(["event-type", "hook", "permission"]);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/add/index.ts

@@ -0,0 +1,16 @@
+import { defineCommand } from "citty";
+import { addEventTypeCommand } from "./event-type.js";
+import { addHookCommand } from "./hook.js";
+import { addPermissionCommand } from "./permission.js";
+
+export const addCommand = defineCommand({
+  meta: {
+    name: "add",
+    description: "Add-on generators: add hook / event-type / permission.",
+  },
+  subCommands: {
+    hook: addHookCommand,
+    "event-type": addEventTypeCommand,
+    permission: addPermissionCommand,
+  },
+});

hivegrid-cloud/packages/cli/src/commands/add/permission.test.ts

@@ -0,0 +1,71 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { generatePermission } from "./permission.js";
+
+describe("add permission generator", () => {
+  let tempRoot: string;
+
+  beforeEach(async () => {
+    tempRoot = await mkdtemp(path.join(tmpdir(), "toolctrl-cli-permission-"));
+  });
+
+  afterEach(async () => {
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  it("emits seed fragment + frontend mapper", async () => {
+    const result = await generatePermission({
+      name: "app.inventory.view",
+      repoRoot: tempRoot,
+      dryRun: true,
+    });
+    const rels = result.files.map((f) => path.relative(tempRoot, f.path)).sort();
+    expect(rels).toEqual([
+      "apps/web/app/utils/permissions/_generated/app_inventory_view.ts",
+      "packages/db/src/_generated-permissions/app_inventory_view.ts",
+    ]);
+  });
+
+  it("classifies admin.* permissions correctly", async () => {
+    const result = await generatePermission({
+      name: "admin.audit.view",
+      repoRoot: tempRoot,
+      dryRun: true,
+    });
+    const seedFragment = result.files.find((f) => f.path.includes("packages/db/"))!;
+    expect(seedFragment.contents).toContain('PermissionType: "admin" | "app" = "admin"');
+    expect(seedFragment.contents).toContain('"SuperAdmin"');
+    expect(seedFragment.contents).not.toContain("TODO");
+  });
+
+  it("classifies app.* permissions correctly", async () => {
+    const result = await generatePermission({
+      name: "app.inventory.view",
+      repoRoot: tempRoot,
+      dryRun: true,
+    });
+    const seedFragment = result.files.find((f) => f.path.includes("packages/db/"))!;
+    expect(seedFragment.contents).toContain('PermissionType: "admin" | "app" = "app"');
+    expect(seedFragment.contents).toContain('"SuperUser"');
+    expect(seedFragment.contents).toContain('"Admin"');
+    expect(seedFragment.contents).not.toContain("TODO");
+  });
+
+  it("rejects invalid permission keys", async () => {
+    await expect(
+      generatePermission({ name: "AppFooBar", repoRoot: tempRoot, dryRun: true }),
+    ).rejects.toThrow(/Invalid/);
+    await expect(generatePermission({ name: "", repoRoot: tempRoot, dryRun: true })).rejects.toThrow(
+      /required/,
+    );
+  });
+
+  it("refuses to overwrite an existing permission fragment", async () => {
+    await generatePermission({ name: "app.inventory.view", repoRoot: tempRoot, dryRun: false });
+    await expect(
+      generatePermission({ name: "app.inventory.view", repoRoot: tempRoot, dryRun: false }),
+    ).rejects.toThrow(/already exists/);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/add/permission.ts

@@ -0,0 +1,151 @@
+/**
+ * `toolctrl add permission <name>` — scaffold a new permission key plus
+ * a frontend-mapper stub.
+ *
+ * The canonical permission list lives in
+ * `packages/db/src/permissions-seed.server.ts` as a string-array
+ * literal. We deliberately do NOT patch that file from the CLI — the
+ * array is hand-curated and each entry has an associated `inRoles`
+ * mapping a few lines below. Instead the generator writes a single
+ * "fragment" file under
+ * `packages/db/src/_generated-permissions/<name>.ts` that the caller
+ * can paste into the canonical list, plus a frontend permission-mapper
+ * stub under `apps/web/app/utils/permissions/_generated/`.
+ *
+ * Refs: docs/improvement-plan/08-mobile-cli-storybook-sdk/cli-scaffolding.md
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import path from "node:path";
+import {
+  createScaffoldResult,
+  pascalCase,
+  resolveRepoRoot,
+  writeScaffoldFile,
+  type ScaffoldResult,
+} from "../_lib/scaffold.js";
+
+export type GeneratePermissionOptions = {
+  /** Dotted permission key, e.g. "app.inventory.view". */
+  name: string;
+  repoRoot?: string;
+  dryRun?: boolean;
+};
+
+const PERMISSION_PATTERN = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9_]*)+$/;
+
+export async function generatePermission(options: GeneratePermissionOptions): Promise<ScaffoldResult> {
+  const permission = options.name.trim();
+  if (!permission) throw new Error("permission name is required.");
+  if (!PERMISSION_PATTERN.test(permission)) {
+    throw new Error(
+      `Invalid permission key: "${permission}". Use dotted lowercase, e.g. "app.inventory.view".`,
+    );
+  }
+
+  const dryRun = options.dryRun ?? false;
+  const repoRoot = resolveRepoRoot(options.repoRoot);
+  const fileSlug = permission.replace(/\./g, "_");
+  const constName = pascalCase(permission.replace(/\./g, " "));
+  const isAdmin = permission.startsWith("admin.");
+
+  const result = createScaffoldResult(dryRun);
+
+  await writeScaffoldFile({
+    targetPath: path.join(repoRoot, "packages/db/src/_generated-permissions", `${fileSlug}.ts`),
+    contents: renderSeedFragment({ permission, constName, isAdmin }),
+    dryRun,
+    result,
+  });
+
+  await writeScaffoldFile({
+    targetPath: path.join(repoRoot, "apps/web/app/utils/permissions/_generated", `${fileSlug}.ts`),
+    contents: renderMapperFragment({ permission, constName }),
+    dryRun,
+    result,
+  });
+
+  result.notes.push(
+    `Permission key: "${permission}"`,
+    `Manual follow-up:`,
+    `  1. Add "${permission}" to defaultPermissionSeeds in packages/db/src/permissions-seed.server.ts`,
+    `  2. Add the role-mapping entry in the same file (rolePermissionMatrix)`,
+    `  3. Wire the frontend check via the helper in apps/web/app/utils/helpers/PermissionsHelper.ts`,
+  );
+
+  return result;
+}
+
+function renderSeedFragment({
+  permission,
+  constName,
+  isAdmin,
+}: {
+  permission: string;
+  constName: string;
+  isAdmin: boolean;
+}): string {
+  return `/**
+ * Permission seed fragment for "${permission}".
+ * Generated by toolctrl-cli.
+ *
+ * Paste the constant into the \`defaultPermissionSeeds\` array in
+ * \`packages/db/src/permissions-seed.server.ts\` and add a matching
+ * entry to the \`rolePermissionMatrix\` further down in that file.
+ */
+export const ${constName}Permission = "${permission}" as const;
+
+export const ${constName}PermissionType: "admin" | "app" = ${JSON.stringify(isAdmin ? "admin" : "app")};
+
+export const ${constName}DefaultRoles: readonly string[] = [
+${isAdmin ? '  "SuperAdmin",' : '  "SuperUser",\n  "Admin",'}
+];
+`;
+}
+
+function renderMapperFragment({ permission, constName }: { permission: string; constName: string }): string {
+  return `/**
+ * Frontend permission-mapper stub for "${permission}".
+ * Generated by toolctrl-cli.
+ *
+ * Wire this into your route loaders via the project's permission
+ * helper (typically apps/web/app/utils/helpers/PermissionsHelper).
+ */
+export const ${constName}PermissionKey = "${permission}" as const;
+
+export function require${constName}(allowedPermissions: ReadonlyArray<string>): boolean {
+  return allowedPermissions.includes(${constName}PermissionKey);
+}
+`;
+}
+
+export const addPermissionCommand = defineCommand({
+  meta: {
+    name: "permission",
+    description: "Scaffold a permission key + frontend mapper stub.",
+  },
+  args: {
+    name: {
+      type: "positional",
+      required: true,
+      description: "Dotted permission key, e.g. \"app.inventory.view\".",
+    },
+    "dry-run": {
+      type: "boolean",
+      required: false,
+      description: "Print the would-be writes without touching the filesystem.",
+    },
+  },
+  async run({ args }) {
+    const result = await generatePermission({ name: args.name, dryRun: args["dry-run"] === true });
+    consola.success(
+      `${result.dryRun ? "[dry-run] " : ""}Generated permission "${args.name}" — ${result.files.length} file(s).`,
+    );
+    for (const file of result.files) {
+      consola.info(`  ${result.dryRun ? "would write" : "wrote"} ${file.path}`);
+    }
+    for (const note of result.notes) {
+      consola.info(note);
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/audit/export-pdf.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { AuditPdfEvent, AuditPdfIntegrity, AuditPdfReportInput } from "@toolctrl/exports/audit-pdf";
+import { runAuditExportPdf, type AuditExportPdfDependencies } from "./export-pdf.js";
+
+function makeEvent(over: Partial<AuditPdfEvent> = {}): AuditPdfEvent {
+  return {
+    id: "audit_1",
+    createdAt: new Date("2026-05-17T00:00:00.000Z"),
+    tenantId: "tenant_1",
+    actorType: "user",
+    actorId: "user_1",
+    actorEmail: null,
+    actorIp: null,
+    actorUserAgent: null,
+    action: "widget.created",
+    targetType: "widget",
+    targetId: "widget_1",
+    requestId: null,
+    sourceModule: "crm",
+    outcome: "success",
+    dataSensitivity: "internal",
+    regulatoryScope: ["soc2"],
+    metadata: null,
+    previousHash: null,
+    eventHash: "h1",
+    ...over,
+  };
+}
+
+type TestState = {
+  writtenPath: string | null;
+  writtenBytes: Uint8Array | null;
+  renderInput: AuditPdfReportInput | null;
+};
+
+function makeDeps(opts: {
+  events: ReadonlyArray<AuditPdfEvent>;
+  integrity?: AuditPdfIntegrity;
+}): {
+  deps: AuditExportPdfDependencies;
+  state: TestState;
+  logger: { info: ReturnType<typeof vi.fn>; error: ReturnType<typeof vi.fn> };
+} {
+  const state: TestState = { writtenPath: null, writtenBytes: null, renderInput: null };
+  const logger = { info: vi.fn(), error: vi.fn() };
+  const deps: AuditExportPdfDependencies = {
+    loadEvents: async () => opts.events,
+    verify: () => opts.integrity ?? { ok: true, inspected: opts.events.length, firstBreakId: null, reason: null },
+    render: async (input) => {
+      state.renderInput = input;
+      // Fake PDF bytes — the renderer is unit-tested separately in
+      // @toolctrl/exports.
+      return new Uint8Array([0x25, 0x50, 0x44, 0x46, 0x2d, 0x31, 0x2e, 0x37]); // "%PDF-1.7"
+    },
+    writeOutput: async (path, bytes) => {
+      state.writtenPath = path;
+      state.writtenBytes = bytes;
+    },
+    logger,
+    now: () => new Date("2026-05-17T12:00:00.000Z"),
+  };
+  return { deps, state, logger };
+}
+
+describe("runAuditExportPdf", () => {
+  it("rejects empty --tenant", async () => {
+    const { deps, logger } = makeDeps({ events: [] });
+    const out = await runAuditExportPdf({ tenant: "  ", out: "/tmp/x.pdf" }, deps);
+    expect(out.exitCode).toBe(1);
+    expect(logger.error).toHaveBeenCalledWith(expect.stringContaining("Missing --tenant"));
+  });
+
+  it("rejects missing --out", async () => {
+    const { deps, logger } = makeDeps({ events: [] });
+    const out = await runAuditExportPdf({ tenant: "t1", out: "" }, deps);
+    expect(out.exitCode).toBe(1);
+    expect(logger.error).toHaveBeenCalledWith(expect.stringContaining("Missing --out"));
+  });
+
+  it("renders + writes a PDF and exits 0 when the chain is intact", async () => {
+    const events = [makeEvent(), makeEvent({ id: "audit_2", action: "widget.updated", previousHash: "h1", eventHash: "h2" })];
+    const { deps, state, logger } = makeDeps({ events });
+    const out = await runAuditExportPdf(
+      {
+        tenant: "tenant_1",
+        from: "2026-05-01T00:00:00.000Z",
+        to: "2026-05-17T00:00:00.000Z",
+        regulatoryScope: "soc2",
+        out: "/tmp/report.pdf",
+        generatedBy: "ops-bot",
+      },
+      deps
+    );
+    expect(out.exitCode).toBe(0);
+    expect(out.rowCount).toBe(2);
+    expect(state.writtenPath).toBe("/tmp/report.pdf");
+    expect(state.writtenBytes?.[0]).toBe(0x25); // '%'
+    expect(state.renderInput?.tenantId).toBe("tenant_1");
+    expect(state.renderInput?.filterSummary).toContain("regulatoryScope=soc2");
+    expect(state.renderInput?.events).toHaveLength(2);
+    expect(state.renderInput?.integrity.ok).toBe(true);
+    expect(logger.info).toHaveBeenCalledWith(expect.stringContaining("audit-pdf written"));
+  });
+
+  it("treats tenant=__platform__ as null tenantId in the loader", async () => {
+    const events: AuditPdfEvent[] = [];
+    let captured: { tenantId: string | null } | null = null;
+    const { deps: baseDeps } = makeDeps({ events });
+    const deps: AuditExportPdfDependencies = {
+      ...baseDeps,
+      loadEvents: async (args) => {
+        captured = { tenantId: args.tenantId };
+        return events;
+      },
+    };
+    await runAuditExportPdf({ tenant: "__platform__", out: "/tmp/x.pdf" }, deps);
+    expect(captured).toEqual({ tenantId: null });
+  });
+
+  it("exits 1 when integrity is broken — but still writes the file as evidence", async () => {
+    const events = [makeEvent()];
+    const { deps, state, logger } = makeDeps({
+      events,
+      integrity: { ok: false, inspected: 1, firstBreakId: "audit_1", reason: "hash-mismatch" },
+    });
+    const out = await runAuditExportPdf({ tenant: "t1", out: "/tmp/x.pdf" }, deps);
+    expect(out.exitCode).toBe(1);
+    expect(state.writtenPath).toBe("/tmp/x.pdf");
+    expect(logger.error).toHaveBeenCalledWith(expect.stringContaining("BROKEN CHAIN"));
+  });
+
+  it("throws when --from is not parseable", async () => {
+    const { deps } = makeDeps({ events: [] });
+    await expect(runAuditExportPdf({ tenant: "t1", from: "garbage", out: "/tmp/x.pdf" }, deps)).rejects.toThrow(/Invalid --from/);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/audit/export-pdf.ts

@@ -0,0 +1,218 @@
+/**
+ * `toolctrl audit export-pdf --tenant <id> [--from] [--to] [--regulatory-scope]
+ *   --out <path>`
+ *
+ * Renders a tamper-evident PDF compliance report from AuditEvent rows for
+ * the given tenant and time-range. The report header includes a
+ * `verifyAuditChain` integrity check; the body lists each event in
+ * chronological order with hash + actor + outcome + scope.
+ *
+ * Renders via @react-pdf/renderer through `@toolctrl/exports/audit-pdf`.
+ *
+ * See docs/improvement-plan/10-compliance-polish/compliance-audit-export.md.
+ */
+import { writeFile } from "node:fs/promises";
+import { defineCommand } from "citty";
+import consola from "consola";
+
+import type { AuditPdfEvent, AuditPdfIntegrity, AuditPdfReportInput } from "@toolctrl/exports/audit-pdf";
+
+const AUDIT_PDF_QUERY_LIMIT = 5_000;
+
+export type AuditExportPdfArgs = {
+  tenant: string;
+  from?: string | null;
+  to?: string | null;
+  regulatoryScope?: string | null;
+  out: string;
+  generatedBy?: string | null;
+};
+
+export type AuditExportPdfDependencies = {
+  /** Load matching AuditEvent rows in chronological order. */
+  loadEvents: (args: {
+    tenantId: string | null;
+    from: Date | null;
+    to: Date | null;
+    regulatoryScope: string | null;
+    limit: number;
+  }) => Promise<ReadonlyArray<AuditPdfEvent>>;
+  /** Compute hash-chain integrity over the loaded events. */
+  verify: (events: ReadonlyArray<AuditPdfEvent>) => AuditPdfIntegrity;
+  /** Render the PDF document to a byte buffer. */
+  render: (input: AuditPdfReportInput) => Promise<Uint8Array>;
+  /** Write the rendered bytes to the chosen output path. */
+  writeOutput: (path: string, bytes: Uint8Array) => Promise<void>;
+  /** Logger sink. */
+  logger: {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+  /** Optional `now` clock for tests. */
+  now?: () => Date;
+};
+
+export type AuditExportPdfOutcome = {
+  exitCode: 0 | 1;
+  rowCount: number;
+  byteLength: number;
+  outPath: string;
+};
+
+function parseIsoDate(raw: string | null | undefined, label: string): Date | null {
+  if (!raw || raw.length === 0) return null;
+  const d = new Date(raw);
+  if (Number.isNaN(d.getTime())) {
+    throw new Error(`Invalid --${label} value ${JSON.stringify(raw)} (expected ISO-8601).`);
+  }
+  return d;
+}
+
+export async function runAuditExportPdf(
+  args: AuditExportPdfArgs,
+  deps: AuditExportPdfDependencies
+): Promise<AuditExportPdfOutcome> {
+  const tenantArg = args.tenant.trim();
+  if (tenantArg.length === 0) {
+    deps.logger.error("Missing --tenant.");
+    return { exitCode: 1, rowCount: 0, byteLength: 0, outPath: args.out };
+  }
+  if (!args.out || args.out.trim().length === 0) {
+    deps.logger.error("Missing --out.");
+    return { exitCode: 1, rowCount: 0, byteLength: 0, outPath: args.out };
+  }
+
+  const from = parseIsoDate(args.from ?? null, "from");
+  const to = parseIsoDate(args.to ?? null, "to");
+  const tenantId = tenantArg === "__platform__" ? null : tenantArg;
+  const regulatoryScope = args.regulatoryScope?.trim() || null;
+
+  const events = await deps.loadEvents({ tenantId, from, to, regulatoryScope, limit: AUDIT_PDF_QUERY_LIMIT });
+  const integrity = deps.verify(events);
+
+  const filterSummary = [
+    regulatoryScope ? `regulatoryScope=${regulatoryScope}` : null,
+  ]
+    .filter((s): s is string => s !== null)
+    .join(" ");
+
+  const input: AuditPdfReportInput = {
+    tenantId,
+    from: from?.toISOString() ?? null,
+    to: to?.toISOString() ?? null,
+    filterSummary,
+    integrity,
+    events,
+    ...(args.generatedBy ? { generatedBy: args.generatedBy } : {}),
+    generatedAt: (deps.now ?? (() => new Date()))(),
+  };
+
+  const bytes = await deps.render(input);
+  await deps.writeOutput(args.out, bytes);
+
+  if (integrity.ok) {
+    deps.logger.info(`audit-pdf written — out=${args.out} rows=${events.length} bytes=${bytes.length} integrity=ok`);
+  } else {
+    deps.logger.error(
+      `audit-pdf written WITH BROKEN CHAIN — out=${args.out} rows=${events.length} bytes=${bytes.length} firstBreakId=${integrity.firstBreakId ?? "?"} reason=${integrity.reason ?? "unknown"}`
+    );
+  }
+
+  return {
+    exitCode: integrity.ok ? 0 : 1,
+    rowCount: events.length,
+    byteLength: bytes.length,
+    outPath: args.out,
+  };
+}
+
+export const auditExportPdfCommand = defineCommand({
+  meta: { name: "export-pdf", description: "Render a tamper-evident PDF compliance report for a tenant." },
+  args: {
+    tenant: { type: "string", required: true, description: "Tenant ID (use --tenant=__platform__ for platform events)." },
+    from: { type: "string", required: false, description: "Lower bound (inclusive) ISO-8601 createdAt." },
+    to: { type: "string", required: false, description: "Upper bound (exclusive) ISO-8601 createdAt." },
+    "regulatory-scope": { type: "string", required: false, description: "Filter by regulatoryScope value (gdpr | hipaa | soc2 | pci)." },
+    out: { type: "string", required: true, description: "Output file path (e.g. ./audit-report.pdf)." },
+    "generated-by": { type: "string", required: false, description: "Operator display name to embed on the cover page." },
+  },
+  async run({ args }) {
+    const [{ getReadDbClient }, { verifyAuditChain }, { serializeAuditEventsToPdf }] = await Promise.all([
+      import("@toolctrl/db/client.server"),
+      import("@toolctrl/db/audit-hash"),
+      import("@toolctrl/exports/audit-pdf"),
+    ]);
+
+    const db = getReadDbClient();
+
+    const outcome = await runAuditExportPdf(
+      {
+        tenant: String(args.tenant),
+        ...(args.from !== undefined ? { from: String(args.from) } : {}),
+        ...(args.to !== undefined ? { to: String(args.to) } : {}),
+        ...(args["regulatory-scope"] !== undefined ? { regulatoryScope: String(args["regulatory-scope"]) } : {}),
+        out: String(args.out),
+        ...(args["generated-by"] !== undefined ? { generatedBy: String(args["generated-by"]) } : {}),
+      },
+      {
+        async loadEvents({ tenantId, from, to, regulatoryScope, limit }) {
+          const where: Record<string, unknown> = { tenantId };
+          if (from || to) {
+            const range: Record<string, Date> = {};
+            if (from) range.gte = from;
+            if (to) range.lt = to;
+            where.createdAt = range;
+          }
+          if (regulatoryScope) {
+            where.regulatoryScope = { hasSome: [regulatoryScope] };
+          }
+          const rows = (await db.auditEvent.findMany({
+            where,
+            orderBy: { createdAt: "asc" },
+            take: limit,
+          })) as unknown as ReadonlyArray<AuditPdfEvent>;
+          return rows;
+        },
+        verify(events) {
+          // Convert to AuditChainEvent-compatible shape: id + createdAt as
+          // strings, the rest matching AuditPdfEvent.
+          const chainEvents = events.map((e) => ({
+            id: e.id,
+            createdAt: e.createdAt instanceof Date ? e.createdAt.toISOString() : String(e.createdAt),
+            tenantId: e.tenantId,
+            actorType: e.actorType,
+            actorId: e.actorId,
+            actorEmail: e.actorEmail,
+            actorIp: e.actorIp,
+            actorUserAgent: e.actorUserAgent,
+            action: e.action,
+            targetType: e.targetType,
+            targetId: e.targetId,
+            requestId: e.requestId,
+            sourceModule: e.sourceModule,
+            outcome: e.outcome,
+            dataSensitivity: e.dataSensitivity,
+            regulatoryScope: e.regulatoryScope as string[],
+            metadata: e.metadata,
+            previousHash: e.previousHash,
+            eventHash: e.eventHash,
+          }));
+          const result = verifyAuditChain(chainEvents);
+          return {
+            ok: result.ok,
+            inspected: result.inspected,
+            firstBreakId: result.firstBreak?.eventId ?? null,
+            reason: result.firstBreak?.reason ?? null,
+          };
+        },
+        render: serializeAuditEventsToPdf,
+        writeOutput: async (path, bytes) => writeFile(path, bytes),
+        logger: {
+          info: (msg) => consola.success(msg),
+          error: (msg) => consola.error(msg),
+        },
+      }
+    );
+    process.exitCode = outcome.exitCode;
+  },
+});

hivegrid-cloud/packages/cli/src/commands/audit/index.ts

@@ -0,0 +1,17 @@
+import { defineCommand } from "citty";
+
+import { auditVerifyChainCommand } from "./verify-chain.js";
+import { auditExportPdfCommand } from "./export-pdf.js";
+
+export const auditCommand = defineCommand({
+  meta: {
+    name: "audit",
+    description: "AuditEvent compliance operations (hash-chain verify, PDF report export).",
+  },
+  subCommands: {
+    "verify-chain": auditVerifyChainCommand,
+    "export-pdf": auditExportPdfCommand,
+  },
+});
+
+export { auditVerifyChainCommand, auditExportPdfCommand };

hivegrid-cloud/packages/cli/src/commands/audit/verify-chain.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { computeAuditHash, verifyAuditChain } from "@toolctrl/db/audit-hash";
+import {
+  runAuditVerifyChain,
+  type AuditVerifyChainDependencies,
+  type AuditVerifyChainRow,
+} from "./verify-chain.js";
+
+function makeOutput() {
+  return {
+    info: vi.fn<(msg: string) => void>(),
+    error: vi.fn<(msg: string) => void>(),
+    json: vi.fn<(obj: unknown) => void>(),
+  };
+}
+
+function basePayload(over: Partial<AuditVerifyChainRow> = {}): AuditVerifyChainRow {
+  return {
+    id: "audit_1",
+    createdAt: "2026-05-17T00:00:00.000Z",
+    tenantId: "tenant_1",
+    actorType: "user",
+    actorId: "user_1",
+    actorEmail: null,
+    actorIp: null,
+    actorUserAgent: null,
+    action: "x.do",
+    targetType: null,
+    targetId: null,
+    requestId: null,
+    sourceModule: null,
+    outcome: "success",
+    dataSensitivity: "internal",
+    regulatoryScope: [],
+    metadata: null,
+    previousHash: null,
+    eventHash: null,
+    ...over,
+  };
+}
+
+function hashFor(row: AuditVerifyChainRow): string {
+  return computeAuditHash({
+    previousHash: row.previousHash,
+    payload: {
+      id: row.id,
+      createdAt: row.createdAt,
+      tenantId: row.tenantId,
+      actorType: row.actorType,
+      actorId: row.actorId,
+      actorEmail: row.actorEmail,
+      actorIp: row.actorIp,
+      actorUserAgent: row.actorUserAgent,
+      action: row.action,
+      targetType: row.targetType,
+      targetId: row.targetId,
+      requestId: row.requestId,
+      sourceModule: row.sourceModule,
+      outcome: row.outcome,
+      dataSensitivity: row.dataSensitivity,
+      regulatoryScope: row.regulatoryScope,
+      metadata: row.metadata,
+    },
+  });
+}
+
+function makeDeps(rows: AuditVerifyChainRow[]): AuditVerifyChainDependencies & { output: ReturnType<typeof makeOutput> } {
+  const output = makeOutput();
+  return {
+    output,
+    verify: verifyAuditChain,
+    async *readRows() {
+      for (const row of rows) yield row;
+    },
+  };
+}
+
+describe("runAuditVerifyChain", () => {
+  it("returns exit code 0 + prints OK message for an intact chain", async () => {
+    const r1 = basePayload();
+    r1.eventHash = hashFor(r1);
+    const r2 = basePayload({ id: "audit_2", action: "x.do2", previousHash: r1.eventHash });
+    r2.eventHash = hashFor(r2);
+
+    const deps = makeDeps([r1, r2]);
+    const result = await runAuditVerifyChain({ tenant: "tenant_1" }, deps);
+
+    expect(result.exitCode).toBe(0);
+    expect(result.ok).toBe(true);
+    expect(result.inspected).toBe(2);
+    expect(deps.output.info).toHaveBeenCalledWith(expect.stringContaining("audit-chain OK"));
+  });
+
+  it("returns exit code 1 with a diagnostic on hash mismatch", async () => {
+    const r1 = basePayload();
+    r1.eventHash = hashFor(r1);
+    // tamper: change metadata but keep stored hash
+    const tampered = { ...r1, metadata: { tampered: true } };
+
+    const deps = makeDeps([tampered]);
+    const result = await runAuditVerifyChain({ tenant: "tenant_1" }, deps);
+
+    expect(result.exitCode).toBe(1);
+    expect(result.ok).toBe(false);
+    expect(deps.output.error).toHaveBeenCalledWith(expect.stringContaining("audit-chain BROKEN"));
+    expect(deps.output.error).toHaveBeenCalledWith(expect.stringContaining("hash-mismatch"));
+  });
+
+  it("emits a single JSON object when --json is set", async () => {
+    const r1 = basePayload();
+    r1.eventHash = hashFor(r1);
+
+    const deps = makeDeps([r1]);
+    const result = await runAuditVerifyChain({ tenant: "tenant_1", json: true }, deps);
+
+    expect(result.exitCode).toBe(0);
+    expect(deps.output.info).not.toHaveBeenCalled();
+    expect(deps.output.json).toHaveBeenCalledTimes(1);
+    const arg = deps.output.json.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(arg).toMatchObject({ tenantId: "tenant_1", ok: true, inspected: 1 });
+  });
+
+  it("rejects an empty tenant arg", async () => {
+    const deps = makeDeps([]);
+    const result = await runAuditVerifyChain({ tenant: "   " }, deps);
+    expect(result.exitCode).toBe(1);
+    expect(deps.output.error).toHaveBeenCalledWith(expect.stringContaining("Missing --tenant"));
+  });
+
+  it("parses ISO-8601 --from/--to and propagates them to the reader", async () => {
+    const captured: { from: Date | null; to: Date | null }[] = [];
+    const deps: AuditVerifyChainDependencies & { output: ReturnType<typeof makeOutput> } = {
+      output: makeOutput(),
+      verify: () => ({ ok: true, inspected: 0, firstBreak: null }),
+      async *readRows(opts) {
+        captured.push({ from: opts.from, to: opts.to });
+        return;
+      },
+    };
+    await runAuditVerifyChain({ tenant: "t1", from: "2026-01-01T00:00:00.000Z", to: "2026-05-17T00:00:00.000Z" }, deps);
+    expect(captured[0]?.from?.toISOString()).toBe("2026-01-01T00:00:00.000Z");
+    expect(captured[0]?.to?.toISOString()).toBe("2026-05-17T00:00:00.000Z");
+  });
+
+  it("throws when --from is not parseable", async () => {
+    const deps = makeDeps([]);
+    await expect(runAuditVerifyChain({ tenant: "t1", from: "not-a-date" }, deps)).rejects.toThrow(/Invalid --from/);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/audit/verify-chain.ts

@@ -0,0 +1,169 @@
+/**
+ * `toolctrl audit verify-chain --tenant <id> [--from <iso8601>] [--to <iso8601>] [--json]`
+ *
+ * Thin CLI wrapper around `verifyAuditChain` from @toolctrl/db/audit-hash.
+ * Loads the per-tenant AuditEvent chain in chronological order, recomputes
+ * each event's eventHash and compares it against the stored value. Exits
+ * 0 on intact chain, non-zero with first-break diagnostics otherwise.
+ *
+ * Design notes:
+ *   - Reads via getReadDbClient — the verifier is read-only.
+ *   - Streams rows in batches of 5_000 by id ascending; the verifier
+ *     consumes rows in createdAt order so we sort each batch before
+ *     appending to the running chain state. For tenants with > a few
+ *     hundred thousand events the operator should run the verifier
+ *     against a time-restricted range to keep memory bounded.
+ *   - `--json` switches the printer to a single machine-readable JSON
+ *     object on stdout (no consola decorations).
+ *
+ * See docs/improvement-plan/10-compliance-polish/compliance-audit-export.md.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+
+import type { AuditChainEvent, VerifyAuditChainResult } from "@toolctrl/db/audit-hash";
+
+const AUDIT_VERIFY_BATCH_SIZE = 5_000;
+
+export type AuditVerifyChainArgs = {
+  tenant: string;
+  from?: string | null;
+  to?: string | null;
+  json?: boolean;
+};
+
+export type AuditVerifyChainRow = AuditChainEvent;
+
+export type AuditVerifyChainDependencies = {
+  /** Cursor-iterable read of events ordered by createdAt ascending. */
+  readRows: (args: { tenantId: string; from: Date | null; to: Date | null; batchSize: number }) => AsyncIterable<AuditVerifyChainRow>;
+  /** Chain verifier — usually `verifyAuditChain` from @toolctrl/db/audit-hash. */
+  verify: (events: ReadonlyArray<AuditVerifyChainRow>, options?: { secret?: string | null }) => VerifyAuditChainResult;
+  /** Output sink. Tests pass an array collector; production wires consola. */
+  output: { info: (msg: string) => void; json: (obj: unknown) => void; error: (msg: string) => void };
+  /** Optional secret override (otherwise reads AUDIT_CHAIN_SECRET env). */
+  secret?: string | null;
+};
+
+export type AuditVerifyChainOutcome = {
+  exitCode: 0 | 1;
+  inspected: number;
+  ok: boolean;
+};
+
+function parseIsoDate(raw: string | null | undefined, label: string): Date | null {
+  if (!raw || raw.length === 0) return null;
+  const d = new Date(raw);
+  if (Number.isNaN(d.getTime())) {
+    throw new Error(`Invalid --${label} value ${JSON.stringify(raw)} (expected ISO-8601).`);
+  }
+  return d;
+}
+
+export async function runAuditVerifyChain(
+  args: AuditVerifyChainArgs,
+  deps: AuditVerifyChainDependencies
+): Promise<AuditVerifyChainOutcome> {
+  const tenantId = args.tenant.trim();
+  if (tenantId.length === 0) {
+    deps.output.error("Missing --tenant.");
+    return { exitCode: 1, inspected: 0, ok: false };
+  }
+  const from = parseIsoDate(args.from ?? null, "from");
+  const to = parseIsoDate(args.to ?? null, "to");
+
+  // Collect rows. The verifier is stateful per-chain (compares against the
+  // previous event's stored hash) so we load the whole window in-memory.
+  // For tenants beyond ~100k events the operator should pass a date range.
+  const rows: AuditVerifyChainRow[] = [];
+  for await (const row of deps.readRows({ tenantId, from, to, batchSize: AUDIT_VERIFY_BATCH_SIZE })) {
+    rows.push(row);
+  }
+
+  const result = deps.verify(rows, deps.secret !== undefined ? { secret: deps.secret } : {});
+
+  if (args.json) {
+    deps.output.json({
+      tenantId,
+      from: from?.toISOString() ?? null,
+      to: to?.toISOString() ?? null,
+      inspected: result.inspected,
+      ok: result.ok,
+      firstBreak: result.firstBreak,
+    });
+  } else if (result.ok) {
+    deps.output.info(`audit-chain OK — tenant=${tenantId} inspected=${result.inspected}`);
+  } else {
+    deps.output.error(
+      `audit-chain BROKEN — tenant=${tenantId} inspected=${result.inspected} firstBreakId=${result.firstBreak?.eventId ?? "?"} reason=${result.firstBreak?.reason ?? "unknown"}`
+    );
+  }
+
+  return { exitCode: result.ok ? 0 : 1, inspected: result.inspected, ok: result.ok };
+}
+
+export const auditVerifyChainCommand = defineCommand({
+  meta: { name: "verify-chain", description: "Verify the AuditEvent hash-chain integrity for a tenant." },
+  args: {
+    tenant: { type: "string", required: true, description: "Tenant ID to verify (use --tenant=__platform__ for platform events)." },
+    from: { type: "string", required: false, description: "Lower bound (inclusive) ISO-8601 createdAt." },
+    to: { type: "string", required: false, description: "Upper bound (exclusive) ISO-8601 createdAt." },
+    json: { type: "boolean", required: false, default: false, description: "Emit a single JSON object instead of human-readable text." },
+  },
+  async run({ args }) {
+    const { verifyAuditChain } = await import("@toolctrl/db/audit-hash");
+    const { getReadDbClient } = await import("@toolctrl/db/client.server");
+    const db = getReadDbClient();
+    const tenantId = String(args.tenant);
+
+    async function* readRows(opts: { tenantId: string; from: Date | null; to: Date | null; batchSize: number }): AsyncIterable<AuditVerifyChainRow> {
+      const where: Record<string, unknown> = {
+        tenantId: opts.tenantId === "__platform__" ? null : opts.tenantId,
+      };
+      if (opts.from || opts.to) {
+        const range: Record<string, Date> = {};
+        if (opts.from) range.gte = opts.from;
+        if (opts.to) range.lt = opts.to;
+        where.createdAt = range;
+      }
+      let cursor: string | undefined;
+      while (true) {
+        const page: AuditVerifyChainRow[] = (await db.auditEvent.findMany({
+          where,
+          orderBy: [{ createdAt: "asc" }, { id: "asc" }],
+          take: opts.batchSize,
+          ...(cursor ? { skip: 1, cursor: { id: cursor } } : {}),
+        })) as unknown as AuditVerifyChainRow[];
+        for (const row of page) yield row;
+        if (page.length < opts.batchSize) return;
+        cursor = page[page.length - 1]?.id;
+      }
+    }
+
+    const tenantArg = String(args.tenant);
+    const fromArg = args.from ? String(args.from) : null;
+    const toArg = args.to ? String(args.to) : null;
+    const jsonArg = Boolean(args.json);
+
+    try {
+      const outcome = await runAuditVerifyChain(
+        { tenant: tenantArg, ...(fromArg !== null ? { from: fromArg } : {}), ...(toArg !== null ? { to: toArg } : {}), json: jsonArg },
+        {
+          readRows,
+          verify: verifyAuditChain,
+          output: {
+            info: (msg) => consola.success(msg),
+            json: (obj) => consola.log(JSON.stringify(obj)),
+            error: (msg) => consola.error(msg),
+          },
+        }
+      );
+      process.exitCode = outcome.exitCode;
+      // Surface the tenant for ops cross-referencing.
+      void tenantId;
+    } catch (error) {
+      consola.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = 1;
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/backup/clickhouse.test.ts

@@ -0,0 +1,68 @@
+import { EventEmitter } from "node:events";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PassThrough } from "node:stream";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { clickhouseEnabled, maybeSnapshotClickhouse } from "./clickhouse.js";
+
+let workDir: string;
+
+beforeEach(async () => {
+  workDir = await mkdtemp(join(tmpdir(), "cli-clickhouse-"));
+});
+
+afterEach(async () => {
+  await rm(workDir, { recursive: true, force: true });
+});
+
+describe("clickhouseEnabled", () => {
+  it("returns false when feature flag is missing", () => {
+    expect(clickhouseEnabled({})).toBe(false);
+    expect(clickhouseEnabled({ BACKUP_INCLUDE_CLICKHOUSE: "false", CLICKHOUSE_URL: "http://x" })).toBe(false);
+  });
+
+  it("returns false when feature flag set but url missing", () => {
+    expect(clickhouseEnabled({ BACKUP_INCLUDE_CLICKHOUSE: "true" })).toBe(false);
+  });
+
+  it("returns true when feature flag and url are present", () => {
+    expect(clickhouseEnabled({ BACKUP_INCLUDE_CLICKHOUSE: "true", CLICKHOUSE_URL: "http://x" })).toBe(true);
+  });
+});
+
+describe("maybeSnapshotClickhouse", () => {
+  it("returns null when not enabled (no-op path)", async () => {
+    const result = await maybeSnapshotClickhouse({ outDir: workDir, env: {} });
+    expect(result).toBeNull();
+  });
+
+  it("invokes clickhouse-client when enabled and reports a result", async () => {
+    const child = new EventEmitter() as EventEmitter & { stdout: PassThrough; stderr: PassThrough };
+    child.stdout = new PassThrough();
+    child.stderr = new PassThrough();
+
+    const spawnFn = ((_cmd: string, args: readonly string[]) => {
+      expect(args).toContain("--query");
+      queueMicrotask(() => {
+        child.stdout.end();
+        child.stderr.end();
+        child.emit("close", 0);
+      });
+      return child as never;
+    }) as unknown as typeof import("node:child_process").spawn;
+
+    const result = await maybeSnapshotClickhouse({
+      outDir: workDir,
+      env: {
+        BACKUP_INCLUDE_CLICKHOUSE: "true",
+        CLICKHOUSE_URL: "http://localhost:8123",
+        CLICKHOUSE_DATABASE: "analytics",
+      },
+      spawnFn,
+    });
+    expect(result).not.toBeNull();
+    expect(result?.path).toMatch(/snapshot\.native\.gz$/u);
+    expect(result?.checksum.algorithm).toBe("sha256");
+  });
+});

hivegrid-cloud/packages/cli/src/commands/backup/clickhouse.ts

@@ -0,0 +1,123 @@
+import { spawn, type SpawnOptions } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { mkdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * ClickHouse snapshot is opt-in. When `BACKUP_INCLUDE_CLICKHOUSE !== "true"` (or
+ * required env vars are missing) `maybeSnapshotClickhouse` returns `null` and
+ * the backup proceeds without a `clickhouse/` component.
+ */
+export interface ClickhouseSnapshotEnv {
+  BACKUP_INCLUDE_CLICKHOUSE?: string;
+  CLICKHOUSE_URL?: string;
+  CLICKHOUSE_USER?: string;
+  CLICKHOUSE_PASSWORD?: string;
+  CLICKHOUSE_DATABASE?: string;
+}
+
+export interface ClickhouseSnapshotOptions {
+  env?: ClickhouseSnapshotEnv;
+  outDir: string;
+  /** Override binary (default: `clickhouse-client`). */
+  binary?: string;
+  /** Inject spawn for tests. */
+  spawnFn?: typeof spawn;
+}
+
+export interface ClickhouseSnapshotResult {
+  path: string;
+  sizeBytes: number;
+  checksum: { algorithm: "sha256"; value: string };
+}
+
+export function clickhouseEnabled(env: ClickhouseSnapshotEnv | undefined): boolean {
+  return env?.BACKUP_INCLUDE_CLICKHOUSE === "true" && Boolean(env.CLICKHOUSE_URL);
+}
+
+export async function maybeSnapshotClickhouse(
+  opts: ClickhouseSnapshotOptions,
+): Promise<ClickhouseSnapshotResult | null> {
+  const env = opts.env ?? (process.env as unknown as ClickhouseSnapshotEnv);
+  if (!clickhouseEnabled(env)) {
+    return null;
+  }
+  await mkdir(opts.outDir, { recursive: true });
+  const outPath = join(opts.outDir, "snapshot.native.gz");
+
+  const binary = opts.binary ?? "clickhouse-client";
+  const spawner = opts.spawnFn ?? spawn;
+
+  const args = [
+    "--host",
+    parseHost(env.CLICKHOUSE_URL ?? ""),
+    "--query",
+    `BACKUP DATABASE ${env.CLICKHOUSE_DATABASE ?? "default"} TO File('${outPath}')`,
+  ];
+  const spawnOptions: SpawnOptions = {
+    env: {
+      ...process.env,
+      CLICKHOUSE_USER: env.CLICKHOUSE_USER ?? "",
+      CLICKHOUSE_PASSWORD: env.CLICKHOUSE_PASSWORD ?? "",
+    },
+    stdio: ["ignore", "pipe", "pipe"],
+  };
+  const child = spawner(binary, args, spawnOptions);
+
+  const stderrChunks: Buffer[] = [];
+  child.stderr?.on("data", (c: Buffer) => stderrChunks.push(c));
+
+  // For native BACKUP statements ClickHouse writes the file itself; we drain
+  // stdout into a placeholder so the process completes cleanly when run.
+  if (child.stdout) {
+    const sink = createWriteStream(`${outPath}.log`);
+    child.stdout.pipe(sink);
+  }
+
+  const exitCode: number | null = await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code: number | null) => resolve(code));
+  });
+
+  if (exitCode !== 0) {
+    const stderr = Buffer.concat(stderrChunks).toString("utf8");
+    throw new Error(`clickhouse-client exited with code ${exitCode ?? "<null>"}: ${stderr}`);
+  }
+
+  let size = 0;
+  try {
+    const s = await stat(outPath);
+    size = s.size;
+  } catch {
+    /* path may not exist in stub environments */
+  }
+  const hash = await sha256OfFileOrEmpty(outPath);
+
+  return {
+    path: outPath,
+    sizeBytes: size,
+    checksum: { algorithm: "sha256", value: hash },
+  };
+}
+
+function parseHost(url: string): string {
+  try {
+    return new URL(url).host || "localhost";
+  } catch {
+    return url || "localhost";
+  }
+}
+
+async function sha256OfFileOrEmpty(path: string): Promise<string> {
+  const hash = createHash("sha256");
+  try {
+    const { createReadStream } = await import("node:fs");
+    for await (const chunk of createReadStream(path)) {
+      hash.update(chunk as Buffer);
+    }
+  } catch {
+    // ignore - returns hash of empty input
+  }
+  return hash.digest("hex");
+}

hivegrid-cloud/packages/cli/src/commands/backup/create.test.ts

@@ -0,0 +1,169 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  createTar: vi.fn(async (options: { file: string }) => {
+    const { writeFile } = await import("node:fs/promises");
+    await writeFile(options.file, "archive");
+  }),
+  dumpPostgresToFile: vi.fn(),
+  backupStorageBucket: vi.fn(),
+  maybeSnapshotClickhouse: vi.fn(),
+  encryptFile: vi.fn(async (options: { outputPath: string }) => {
+    const { writeFile } = await import("node:fs/promises");
+    await writeFile(options.outputPath, "encrypted");
+  }),
+  uploadFileMultipart: vi.fn(),
+  s3Client: vi.fn(function S3Client(this: { config: unknown }, config: unknown) {
+    this.config = config;
+  }),
+}));
+
+vi.mock("tar", () => ({
+  create: mocks.createTar,
+}));
+vi.mock("@aws-sdk/client-s3", () => ({
+  S3Client: mocks.s3Client,
+}));
+vi.mock("./postgres.js", () => ({
+  dumpPostgresToFile: mocks.dumpPostgresToFile,
+}));
+vi.mock("./storage.js", () => ({
+  backupStorageBucket: mocks.backupStorageBucket,
+}));
+vi.mock("./clickhouse.js", () => ({
+  maybeSnapshotClickhouse: mocks.maybeSnapshotClickhouse,
+}));
+vi.mock("./encryption.js", () => ({
+  encryptFile: mocks.encryptFile,
+}));
+vi.mock("./s3-upload.js", () => ({
+  uploadFileMultipart: mocks.uploadFileMultipart,
+}));
+
+import { createBackupCommand, runCreateBackup } from "./create.js";
+
+const checksum = {
+  algorithm: "sha256" as const,
+  value: "a".repeat(64),
+};
+
+const baseEnv = {
+  BACKUP_S3_BUCKET: "backups",
+  BACKUP_S3_REGION: "eu-central-1",
+  DATABASE_URL: "postgres://db",
+  BACKUP_ENCRYPTION: "none",
+};
+
+const now = () => new Date("2026-05-03T04:05:06.007Z");
+const logger = {
+  info: vi.fn(),
+  warn: vi.fn(),
+};
+
+describe("runCreateBackup", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.dumpPostgresToFile.mockResolvedValue({ sizeBytes: 111, checksum });
+    mocks.backupStorageBucket.mockResolvedValue({
+      objectCount: 2,
+      totalBytes: 222,
+      checksum,
+    });
+    mocks.maybeSnapshotClickhouse.mockResolvedValue({ sizeBytes: 333, checksum });
+    mocks.uploadFileMultipart.mockResolvedValue(undefined);
+  });
+
+  it("creates a postgres-only backup when storage is skipped", async () => {
+    const client = { send: vi.fn() } as never;
+
+    const result = await runCreateBackup({
+      env: { ...baseEnv, STORAGE_BUCKET: "app-storage" },
+      client,
+      now,
+      skipStorage: true,
+      logger,
+    });
+
+    expect(result.backupId).toMatch(/^backup-2026-05-03T040506007Z-[a-f0-9]{8}$/u);
+    expect(result.key).toBe(`${result.backupId}.tar.gz`);
+    expect(result.sizeBytes).toBe("archive".length);
+    expect(result.manifest.components).toEqual({
+      postgres: {
+        path: "postgres/dump.sql.gz",
+        sizeBytes: 111,
+        checksum,
+      },
+    });
+    expect(logger.warn).toHaveBeenCalledWith("--skip-storage flag set; skipping storage component");
+    expect(mocks.backupStorageBucket).not.toHaveBeenCalled();
+    expect(mocks.encryptFile).not.toHaveBeenCalled();
+    expect(mocks.uploadFileMultipart).toHaveBeenCalledWith(
+      expect.objectContaining({
+        client,
+        bucket: "backups",
+        key: result.key,
+        contentType: "application/gzip",
+        metadata: expect.objectContaining({
+          "backup-id": result.backupId,
+          encryption: "none",
+        }),
+      }),
+    );
+  });
+
+  it("includes storage, clickhouse, and encrypted upload metadata when enabled", async () => {
+    const result = await runCreateBackup({
+      env: {
+        ...baseEnv,
+        STORAGE_BUCKET: "app-storage",
+        BACKUP_ENCRYPTION: "age",
+        BACKUP_AGE_PUBLIC_KEY: "age1example",
+        BACKUP_INCLUDE_CLICKHOUSE: "true",
+      },
+      now,
+      logger,
+    });
+
+    expect(result.key).toBe(`${result.backupId}.tar.gz.age`);
+    expect(result.sizeBytes).toBe("encrypted".length);
+    expect(mocks.s3Client).toHaveBeenCalledWith(expect.objectContaining({ region: "eu-central-1" }));
+    expect(mocks.backupStorageBucket).toHaveBeenCalledWith(
+      expect.objectContaining({
+        bucket: "app-storage",
+        s3: expect.objectContaining({ region: "eu-central-1" }),
+      }),
+    );
+    expect(mocks.maybeSnapshotClickhouse).toHaveBeenCalledWith(
+      expect.objectContaining({
+        env: expect.objectContaining({ BACKUP_INCLUDE_CLICKHOUSE: "true" }),
+      }),
+    );
+    expect(mocks.encryptFile).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config: expect.objectContaining({ method: "age", recipient: "age1example" }),
+      }),
+    );
+    expect(result.manifest.components.storage).toMatchObject({
+      path: "storage/objects.tar",
+      sizeBytes: 222,
+      objectCount: 2,
+      checksum,
+    });
+    expect(result.manifest.components.clickhouse).toMatchObject({
+      path: "clickhouse/snapshot.native.gz",
+      sizeBytes: 333,
+      checksum,
+    });
+  });
+});
+
+describe("createBackupCommand", () => {
+  it("exposes the skip-storage operator flag", () => {
+    expect(createBackupCommand.args).toMatchObject({
+      "skip-storage": {
+        type: "boolean",
+        default: false,
+      },
+    });
+  });
+});

hivegrid-cloud/packages/cli/src/commands/backup/create.ts

@@ -0,0 +1,177 @@
+import { defineCommand } from "citty";
+import consola from "consola";
+import { randomBytes } from "node:crypto";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { create as createTar } from "tar";
+import { hostname } from "node:os";
+import { S3Client } from "@aws-sdk/client-s3";
+import {
+  BACKUP_MANIFEST_VERSION,
+  type BackupManifest,
+  classifyBackup,
+  serializeManifest,
+} from "./manifest.js";
+import { dumpPostgresToFile } from "./postgres.js";
+import { backupStorageBucket } from "./storage.js";
+import { maybeSnapshotClickhouse } from "./clickhouse.js";
+import { encryptFile } from "./encryption.js";
+import { uploadFileMultipart } from "./s3-upload.js";
+import { resolveBackupConfig, type BackupEnv } from "./env.js";
+
+export interface RunCreateBackupOptions {
+  env?: BackupEnv;
+  /** Inject a pre-built S3 client (tests). */
+  client?: S3Client;
+  /** Override now() for deterministic naming. */
+  now?: () => Date;
+  /** Skip storage component (CLI --skip-storage flag). */
+  skipStorage?: boolean;
+  /** Logger override (tests). */
+  logger?: { info: (msg: string) => void; warn: (msg: string) => void };
+}
+
+export interface RunCreateBackupResult {
+  backupId: string;
+  key: string;
+  sizeBytes: number;
+  manifest: BackupManifest;
+}
+
+/** Run the backup-create flow. Exposed as a function so other commands and tests can re-use it. */
+export async function runCreateBackup(opts: RunCreateBackupOptions = {}): Promise<RunCreateBackupResult> {
+  const env = opts.env ?? (process.env as unknown as BackupEnv);
+  const logger = opts.logger ?? consola.create({ defaults: { tag: "backup:create" } });
+  const config = resolveBackupConfig(env);
+  const now = (opts.now ?? (() => new Date()))();
+  const createdAt = now.toISOString();
+  const shortUuid = randomBytes(4).toString("hex");
+  const backupId = `backup-${createdAt.replace(/[:.]/gu, "")}-${shortUuid}`;
+  const objectKey = `${backupId}.tar.gz${config.encryption.method === "none" ? "" : `.${config.encryption.method}`}`;
+
+  const tempRoot = await mkdtemp(join(tmpdir(), "backup-create-"));
+  try {
+    const stageDir = join(tempRoot, backupId);
+    await mkdir(stageDir, { recursive: true });
+
+    logger.info(`Dumping Postgres into ${stageDir}/postgres/dump.sql.gz`);
+    const pgDir = join(stageDir, "postgres");
+    await mkdir(pgDir, { recursive: true });
+    const pgPath = join(pgDir, "dump.sql.gz");
+    const pgResult = await dumpPostgresToFile({ connectionString: config.databaseUrl, outPath: pgPath });
+
+    let storageEntry: BackupManifest["components"]["storage"] | undefined;
+    if (!opts.skipStorage && config.appStorageBucket) {
+      logger.info(`Backing up storage bucket ${config.appStorageBucket}`);
+      const storageDir = join(stageDir, "storage");
+      const storageResult = await backupStorageBucket({
+        s3: config.s3,
+        bucket: config.appStorageBucket,
+        outDir: storageDir,
+        client: opts.client,
+      });
+      storageEntry = {
+        path: "storage/objects.tar",
+        sizeBytes: storageResult.totalBytes,
+        checksum: storageResult.checksum,
+        objectCount: storageResult.objectCount,
+      };
+    } else if (opts.skipStorage) {
+      logger.warn("--skip-storage flag set; skipping storage component");
+    } else {
+      logger.warn("STORAGE_BUCKET env not set; skipping storage component");
+    }
+
+    let clickhouseEntry: BackupManifest["components"]["clickhouse"] | undefined;
+    if (config.includeClickhouse) {
+      logger.info("Snapshotting ClickHouse");
+      const chDir = join(stageDir, "clickhouse");
+      const chResult = await maybeSnapshotClickhouse({ outDir: chDir, env: env as never });
+      if (chResult) {
+        clickhouseEntry = {
+          path: "clickhouse/snapshot.native.gz",
+          sizeBytes: chResult.sizeBytes,
+          checksum: chResult.checksum,
+        };
+      }
+    }
+
+    const manifest: BackupManifest = {
+      schemaVersion: BACKUP_MANIFEST_VERSION,
+      backupId,
+      createdAt,
+      creator: { cliVersion: "0.0.0", host: hostname() },
+      classification: classifyBackup(createdAt),
+      components: {
+        postgres: {
+          path: "postgres/dump.sql.gz",
+          sizeBytes: pgResult.sizeBytes,
+          checksum: pgResult.checksum,
+        },
+        ...(storageEntry ? { storage: storageEntry } : {}),
+        ...(clickhouseEntry ? { clickhouse: clickhouseEntry } : {}),
+      },
+      encryption: {
+        method: config.encryption.method,
+        recipient: config.encryption.recipient,
+      },
+    };
+    const manifestPath = join(stageDir, "manifest.json");
+    await writeFile(manifestPath, serializeManifest(manifest));
+
+    const archivePath = join(tempRoot, `${backupId}.tar.gz`);
+    logger.info(`Packaging ${archivePath}`);
+    await createTar(
+      { gzip: true, file: archivePath, cwd: tempRoot, portable: true },
+      [backupId],
+    );
+
+    let uploadPath = archivePath;
+    if (config.encryption.method !== "none") {
+      const encryptedPath = `${archivePath}.${config.encryption.method}`;
+      logger.info(`Encrypting via ${config.encryption.method}`);
+      await encryptFile({ config: config.encryption, inputPath: archivePath, outputPath: encryptedPath });
+      uploadPath = encryptedPath;
+    }
+
+    const client = opts.client ?? new S3Client(config.s3);
+    logger.info(`Uploading to s3://${config.backupBucket}/${objectKey}`);
+    await uploadFileMultipart({
+      client,
+      bucket: config.backupBucket,
+      key: objectKey,
+      filePath: uploadPath,
+      contentType: "application/gzip",
+      metadata: {
+        "backup-id": backupId,
+        "manifest-version": String(BACKUP_MANIFEST_VERSION),
+        encryption: config.encryption.method,
+        classification: manifest.classification.join(","),
+      },
+    });
+
+    const uploadStat = await readFile(uploadPath).then((b) => b.length);
+    return { backupId, key: objectKey, sizeBytes: uploadStat, manifest };
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+export const createBackupCommand = defineCommand({
+  meta: {
+    name: "create",
+    description: "Create a new backup (Postgres + Storage) and upload to S3.",
+  },
+  args: {
+    "skip-storage": {
+      type: "boolean",
+      description: "Do not include the application storage bucket.",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const result = await runCreateBackup({ skipStorage: Boolean(args["skip-storage"]) });
+    consola.success(`Created ${result.backupId} (${result.sizeBytes} bytes) at key ${result.key}`);
+  },
+});

hivegrid-cloud/packages/cli/src/commands/backup/encryption.test.ts

@@ -0,0 +1,112 @@
+import { EventEmitter } from "node:events";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PassThrough } from "node:stream";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { decryptFile, encryptFile, EncryptionError, trivialXorRoundTrip } from "./encryption.js";
+
+let workDir: string;
+
+beforeEach(async () => {
+  workDir = await mkdtemp(join(tmpdir(), "cli-enc-"));
+});
+
+afterEach(async () => {
+  await rm(workDir, { recursive: true, force: true });
+});
+
+function fakeSpawn() {
+  return ((..._spawnArgs: unknown[]) => {
+    void _spawnArgs;
+    const child = new EventEmitter() as EventEmitter & { stdout: PassThrough; stderr: PassThrough };
+    child.stdout = new PassThrough();
+    child.stderr = new PassThrough();
+    queueMicrotask(() => {
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", 0);
+    });
+    return child as never;
+  }) as unknown as typeof import("node:child_process").spawn;
+}
+
+describe("encryption layer", () => {
+  it("method=none copies the file untouched (round-trip)", async () => {
+    const src = join(workDir, "src.bin");
+    const enc = join(workDir, "src.bin.enc");
+    const dec = join(workDir, "src.bin.dec");
+    await writeFile(src, "hello world");
+
+    await encryptFile({ config: { method: "none" }, inputPath: src, outputPath: enc });
+    await decryptFile({ config: { method: "none" }, inputPath: enc, outputPath: dec });
+
+    expect((await readFile(dec)).toString("utf8")).toBe("hello world");
+  });
+
+  it("method=age requires a recipient", async () => {
+    const src = join(workDir, "src.bin");
+    await writeFile(src, "x");
+    await expect(
+      encryptFile({
+        config: { method: "age" },
+        inputPath: src,
+        outputPath: join(workDir, "out.age"),
+        spawnFn: fakeSpawn(),
+      }),
+    ).rejects.toBeInstanceOf(EncryptionError);
+  });
+
+  it("method=age decrypt requires an identity file", async () => {
+    await expect(
+      decryptFile({
+        config: { method: "age" },
+        inputPath: join(workDir, "any.age"),
+        outputPath: join(workDir, "out.bin"),
+        spawnFn: fakeSpawn(),
+      }),
+    ).rejects.toBeInstanceOf(EncryptionError);
+  });
+
+  it("invokes the age binary with -r recipient", async () => {
+    const src = join(workDir, "src.bin");
+    await writeFile(src, "secret");
+    let captured: readonly string[] = [];
+    const spawnFn = ((cmd: string, args: readonly string[]) => {
+      void cmd;
+      captured = args;
+      const child = new EventEmitter() as EventEmitter & { stdout: PassThrough; stderr: PassThrough };
+      child.stdout = new PassThrough();
+      child.stderr = new PassThrough();
+      queueMicrotask(() => {
+        child.stdout.end();
+        child.stderr.end();
+        child.emit("close", 0);
+      });
+      return child as never;
+    }) as unknown as typeof import("node:child_process").spawn;
+
+    await encryptFile({
+      config: { method: "age", recipient: "age1example" },
+      inputPath: src,
+      outputPath: join(workDir, "out.age"),
+      spawnFn,
+    });
+    expect(captured).toEqual(["-r", "age1example", "-o", expect.any(String), src]);
+  });
+
+  it("trivialXorRoundTrip produces unreadable cipher and recoverable plaintext", async () => {
+    const src = join(workDir, "src.bin");
+    const enc = join(workDir, "src.bin.enc");
+    const dec = join(workDir, "src.bin.dec");
+    const plaintext = "the quick brown fox jumps over the lazy dog";
+    await writeFile(src, plaintext);
+
+    await trivialXorRoundTrip(src, enc, 0x5a);
+    const encBytes = await readFile(enc);
+    expect(encBytes.toString("utf8")).not.toBe(plaintext);
+
+    await trivialXorRoundTrip(enc, dec, 0x5a);
+    expect((await readFile(dec)).toString("utf8")).toBe(plaintext);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/backup/encryption.ts

@@ -0,0 +1,152 @@
+import { spawn, type SpawnOptions } from "node:child_process";
+import { createReadStream, createWriteStream } from "node:fs";
+import { copyFile } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
+
+export type EncryptionMethod = "age" | "gpg" | "none";
+
+export interface EncryptionConfig {
+  method: EncryptionMethod;
+  /** age public key (recipient) when method=age. */
+  recipient?: string;
+  /** age identity file when method=age and we're decrypting. */
+  identityFile?: string;
+  /** gpg key id for method=gpg. */
+  gpgRecipient?: string;
+  /** Override binary path. */
+  binary?: string;
+}
+
+export interface EncryptOptions {
+  config: EncryptionConfig;
+  inputPath: string;
+  outputPath: string;
+  spawnFn?: typeof spawn;
+}
+
+export class EncryptionError extends Error {
+  readonly exitCode: number | null;
+  readonly stderr: string;
+  constructor(message: string, exitCode: number | null, stderr: string) {
+    super(message);
+    this.name = "EncryptionError";
+    this.exitCode = exitCode;
+    this.stderr = stderr;
+  }
+}
+
+export async function encryptFile(opts: EncryptOptions): Promise<{ method: EncryptionMethod; outputPath: string }> {
+  const { method } = opts.config;
+  if (method === "none") {
+    await copyFile(opts.inputPath, opts.outputPath);
+    return { method, outputPath: opts.outputPath };
+  }
+  if (method === "age") {
+    if (!opts.config.recipient) {
+      throw new EncryptionError("BACKUP_AGE_PUBLIC_KEY is required when BACKUP_ENCRYPTION=age", null, "");
+    }
+    await runSpawnPipe({
+      binary: opts.config.binary ?? "age",
+      args: ["-r", opts.config.recipient, "-o", opts.outputPath, opts.inputPath],
+      spawnFn: opts.spawnFn,
+    });
+    return { method, outputPath: opts.outputPath };
+  }
+  if (method === "gpg") {
+    if (!opts.config.gpgRecipient) {
+      throw new EncryptionError("BACKUP_GPG_RECIPIENT is required when BACKUP_ENCRYPTION=gpg", null, "");
+    }
+    await runSpawnPipe({
+      binary: opts.config.binary ?? "gpg",
+      args: ["--yes", "--encrypt", "--recipient", opts.config.gpgRecipient, "--output", opts.outputPath, opts.inputPath],
+      spawnFn: opts.spawnFn,
+    });
+    return { method, outputPath: opts.outputPath };
+  }
+  throw new EncryptionError(`Unsupported encryption method: ${String(method)}`, null, "");
+}
+
+export interface DecryptOptions {
+  config: EncryptionConfig;
+  inputPath: string;
+  outputPath: string;
+  spawnFn?: typeof spawn;
+}
+
+export async function decryptFile(opts: DecryptOptions): Promise<{ method: EncryptionMethod; outputPath: string }> {
+  const { method } = opts.config;
+  if (method === "none") {
+    await copyFile(opts.inputPath, opts.outputPath);
+    return { method, outputPath: opts.outputPath };
+  }
+  if (method === "age") {
+    if (!opts.config.identityFile) {
+      throw new EncryptionError("BACKUP_AGE_IDENTITY_FILE is required to decrypt age backups", null, "");
+    }
+    await runSpawnPipe({
+      binary: opts.config.binary ?? "age",
+      args: ["-d", "-i", opts.config.identityFile, "-o", opts.outputPath, opts.inputPath],
+      spawnFn: opts.spawnFn,
+    });
+    return { method, outputPath: opts.outputPath };
+  }
+  if (method === "gpg") {
+    await runSpawnPipe({
+      binary: opts.config.binary ?? "gpg",
+      args: ["--yes", "--decrypt", "--output", opts.outputPath, opts.inputPath],
+      spawnFn: opts.spawnFn,
+    });
+    return { method, outputPath: opts.outputPath };
+  }
+  throw new EncryptionError(`Unsupported encryption method: ${String(method)}`, null, "");
+}
+
+/**
+ * Convenience helper that emulates an in-process encryption when no binary is
+ * available — used in unit tests so the round-trip is fully deterministic.
+ * Production code paths must use age or gpg via the real binary.
+ */
+export async function trivialXorRoundTrip(inputPath: string, outputPath: string, key: number): Promise<void> {
+  const src = createReadStream(inputPath);
+  const dst = createWriteStream(outputPath);
+  await pipeline(
+    src,
+    async function* (source) {
+      for await (const chunk of source) {
+        const buf = chunk as Buffer;
+        const out = Buffer.alloc(buf.length);
+        for (let i = 0; i < buf.length; i += 1) {
+          out[i] = buf[i] ^ key;
+        }
+        yield out;
+      }
+    },
+    dst,
+  );
+}
+
+interface RunSpawnPipeOptions {
+  binary: string;
+  args: readonly string[];
+  spawnFn?: typeof spawn;
+}
+
+async function runSpawnPipe(opts: RunSpawnPipeOptions): Promise<void> {
+  const spawner = opts.spawnFn ?? spawn;
+  const spawnOptions: SpawnOptions = { stdio: ["ignore", "pipe", "pipe"] };
+  const child = spawner(opts.binary, [...opts.args], spawnOptions);
+  const stderrChunks: Buffer[] = [];
+  child.stderr?.on("data", (c: Buffer) => stderrChunks.push(c));
+
+  const exitCode: number | null = await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code: number | null) => resolve(code));
+  });
+  if (exitCode !== 0) {
+    throw new EncryptionError(
+      `${opts.binary} exited with code ${exitCode ?? "<null>"}`,
+      exitCode,
+      Buffer.concat(stderrChunks).toString("utf8"),
+    );
+  }
+}

hivegrid-cloud/packages/cli/src/commands/backup/env.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { BackupConfigError, resolveBackupConfig } from "./env.js";
+
+describe("resolveBackupConfig", () => {
+  it("requires BACKUP_S3_BUCKET", () => {
+    expect(() => resolveBackupConfig({ DATABASE_URL: "x" })).toThrow(BackupConfigError);
+  });
+
+  it("requires DATABASE_URL or DIRECT_URL", () => {
+    expect(() => resolveBackupConfig({ BACKUP_S3_BUCKET: "b" })).toThrow(BackupConfigError);
+  });
+
+  it("requires BACKUP_AGE_PUBLIC_KEY when encryption=age (default)", () => {
+    expect(() =>
+      resolveBackupConfig({ BACKUP_S3_BUCKET: "b", DATABASE_URL: "postgres://" }),
+    ).toThrow(/BACKUP_AGE_PUBLIC_KEY/u);
+  });
+
+  it("defaults retention to 7/4/12 and method=age", () => {
+    const cfg = resolveBackupConfig({
+      BACKUP_S3_BUCKET: "b",
+      DATABASE_URL: "postgres://",
+      BACKUP_AGE_PUBLIC_KEY: "age1example",
+    });
+    expect(cfg.encryption.method).toBe("age");
+    expect(cfg.retention).toEqual({ daily: 7, weekly: 4, monthly: 12 });
+    expect(cfg.s3.region).toBe("us-east-1");
+  });
+
+  it("parses retention overrides and includeClickhouse", () => {
+    const cfg = resolveBackupConfig({
+      BACKUP_S3_BUCKET: "b",
+      DATABASE_URL: "x",
+      BACKUP_ENCRYPTION: "none",
+      BACKUP_RETENTION_DAILY: "14",
+      BACKUP_RETENTION_WEEKLY: "8",
+      BACKUP_RETENTION_MONTHLY: "24",
+      BACKUP_INCLUDE_CLICKHOUSE: "true",
+    });
+    expect(cfg.encryption.method).toBe("none");
+    expect(cfg.retention).toEqual({ daily: 14, weekly: 8, monthly: 24 });
+    expect(cfg.includeClickhouse).toBe(true);
+  });
+
+  it("rejects unknown encryption methods", () => {
+    expect(() =>
+      resolveBackupConfig({ BACKUP_S3_BUCKET: "b", DATABASE_URL: "x", BACKUP_ENCRYPTION: "rot13" }),
+    ).toThrow(/Invalid BACKUP_ENCRYPTION/u);
+  });
+
+  it("passes through S3 credentials when both set", () => {
+    const cfg = resolveBackupConfig({
+      BACKUP_S3_BUCKET: "b",
+      DATABASE_URL: "x",
+      BACKUP_ENCRYPTION: "none",
+      BACKUP_S3_ACCESS_KEY_ID: "AKIA",
+      BACKUP_S3_SECRET_ACCESS_KEY: "secret",
+      BACKUP_S3_FORCE_PATH_STYLE: "true",
+    });
+    expect(cfg.s3.credentials).toBeDefined();
+    expect(cfg.s3.forcePathStyle).toBe(true);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/backup/env.ts

@@ -0,0 +1,109 @@
+/**
+ * Centralised resolver for backup-cli environment variables. Kept in one place
+ * so the create/list/restore/verify/rotate commands all use the exact same
+ * env-var contract and so unit tests can construct an isolated env object.
+ */
+import type { S3ClientConfig } from "@aws-sdk/client-s3";
+import type { EncryptionConfig, EncryptionMethod } from "./encryption.js";
+
+export interface BackupEnv {
+  BACKUP_S3_ENDPOINT?: string;
+  BACKUP_S3_REGION?: string;
+  BACKUP_S3_BUCKET?: string;
+  BACKUP_S3_ACCESS_KEY_ID?: string;
+  BACKUP_S3_SECRET_ACCESS_KEY?: string;
+  BACKUP_S3_SESSION_TOKEN?: string;
+  BACKUP_S3_FORCE_PATH_STYLE?: string;
+  BACKUP_ENCRYPTION?: string;
+  BACKUP_AGE_PUBLIC_KEY?: string;
+  BACKUP_AGE_IDENTITY_FILE?: string;
+  BACKUP_GPG_RECIPIENT?: string;
+  BACKUP_RETENTION_DAILY?: string;
+  BACKUP_RETENTION_WEEKLY?: string;
+  BACKUP_RETENTION_MONTHLY?: string;
+  BACKUP_INCLUDE_CLICKHOUSE?: string;
+  DATABASE_URL?: string;
+  DIRECT_URL?: string;
+  STORAGE_BUCKET?: string;
+}
+
+export interface ResolvedBackupConfig {
+  s3: S3ClientConfig;
+  backupBucket: string;
+  appStorageBucket: string | null;
+  databaseUrl: string;
+  encryption: EncryptionConfig;
+  retention: {
+    daily: number;
+    weekly: number;
+    monthly: number;
+  };
+  includeClickhouse: boolean;
+}
+
+export class BackupConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BackupConfigError";
+  }
+}
+
+export function resolveBackupConfig(env: BackupEnv): ResolvedBackupConfig {
+  const bucket = env.BACKUP_S3_BUCKET;
+  if (!bucket) {
+    throw new BackupConfigError("BACKUP_S3_BUCKET is required.");
+  }
+  const databaseUrl = env.DIRECT_URL ?? env.DATABASE_URL;
+  if (!databaseUrl) {
+    throw new BackupConfigError("DIRECT_URL or DATABASE_URL is required to dump Postgres.");
+  }
+
+  const encryptionMethod = (env.BACKUP_ENCRYPTION ?? "age") as EncryptionMethod;
+  if (encryptionMethod !== "age" && encryptionMethod !== "gpg" && encryptionMethod !== "none") {
+    throw new BackupConfigError(`Invalid BACKUP_ENCRYPTION=${env.BACKUP_ENCRYPTION}; expected age|gpg|none.`);
+  }
+
+  const encryption: EncryptionConfig = {
+    method: encryptionMethod,
+    recipient: env.BACKUP_AGE_PUBLIC_KEY,
+    identityFile: env.BACKUP_AGE_IDENTITY_FILE,
+    gpgRecipient: env.BACKUP_GPG_RECIPIENT,
+  };
+
+  if (encryptionMethod === "age" && !encryption.recipient) {
+    throw new BackupConfigError("BACKUP_AGE_PUBLIC_KEY is required when BACKUP_ENCRYPTION=age.");
+  }
+
+  const s3: S3ClientConfig = {
+    region: env.BACKUP_S3_REGION ?? "us-east-1",
+    endpoint: env.BACKUP_S3_ENDPOINT,
+    forcePathStyle: env.BACKUP_S3_FORCE_PATH_STYLE === "true",
+  };
+  if (env.BACKUP_S3_ACCESS_KEY_ID && env.BACKUP_S3_SECRET_ACCESS_KEY) {
+    s3.credentials = {
+      accessKeyId: env.BACKUP_S3_ACCESS_KEY_ID,
+      secretAccessKey: env.BACKUP_S3_SECRET_ACCESS_KEY,
+      sessionToken: env.BACKUP_S3_SESSION_TOKEN,
+    };
+  }
+
+  return {
+    s3,
+    backupBucket: bucket,
+    appStorageBucket: env.STORAGE_BUCKET ?? null,
+    databaseUrl,
+    encryption,
+    retention: {
+      daily: parseIntOrDefault(env.BACKUP_RETENTION_DAILY, 7),
+      weekly: parseIntOrDefault(env.BACKUP_RETENTION_WEEKLY, 4),
+      monthly: parseIntOrDefault(env.BACKUP_RETENTION_MONTHLY, 12),
+    },
+    includeClickhouse: env.BACKUP_INCLUDE_CLICKHOUSE === "true",
+  };
+}
+
+function parseIntOrDefault(value: string | undefined, fallback: number): number {
+  if (!value) return fallback;
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) && n >= 0 ? n : fallback;
+}

hivegrid-cloud/packages/cli/src/commands/backup/index.ts

@@ -0,0 +1,20 @@
+import { defineCommand } from "citty";
+import { createBackupCommand } from "./create.js";
+import { listBackupCommand } from "./list.js";
+import { restoreBackupCommand } from "./restore.js";
+import { verifyBackupCommand } from "./verify.js";
+import { rotateBackupCommand } from "./rotate.js";
+
+export const backupCommand = defineCommand({
+  meta: {
+    name: "backup",
+    description: "Postgres + Storage backup, restore, verify, and rotation.",
+  },
+  subCommands: {
+    create: createBackupCommand,
+    list: listBackupCommand,
+    restore: restoreBackupCommand,
+    verify: verifyBackupCommand,
+    rotate: rotateBackupCommand,
+  },
+});

hivegrid-cloud/packages/cli/src/commands/backup/list.test.ts

@@ -0,0 +1,52 @@
+import { ListObjectsV2Command, S3Client } from "@aws-sdk/client-s3";
+import { mockClient } from "aws-sdk-client-mock";
+import { beforeEach, describe, expect, it } from "vitest";
+import { listBackups } from "./list.js";
+
+const s3Mock = mockClient(S3Client as never);
+
+beforeEach(() => {
+  s3Mock.reset();
+});
+
+describe("listBackups", () => {
+  it("classifies backups by encoded ISO timestamp", async () => {
+    s3Mock.on(ListObjectsV2Command as never).resolves({
+      Contents: [
+        // Sunday 2026-05-17
+        { Key: "backup-20260517T030000Z-aabbccdd.tar.gz.age", Size: 100, LastModified: new Date("2026-05-17T03:00:00Z") },
+        // Monday 2026-06-01
+        { Key: "backup-20260601T030000Z-11223344.tar.gz", Size: 200, LastModified: new Date("2026-06-01T03:00:00Z") },
+      ],
+      IsTruncated: false,
+    } as never);
+
+    const result = await listBackups({
+      env: {
+        BACKUP_S3_BUCKET: "bkp",
+        DATABASE_URL: "x",
+        BACKUP_ENCRYPTION: "none",
+      } as never,
+      client: new S3Client({ region: "us-east-1" }),
+    });
+
+    expect(result).toHaveLength(2);
+    expect(result[0].classification).toEqual(["daily", "weekly"]);
+    expect(result[0].encryption).toBe("age");
+    expect(result[1].classification).toEqual(["daily", "monthly"]);
+    expect(result[1].encryption).toBe("none");
+  });
+
+  it("falls back to LastModified for unparsable keys", async () => {
+    s3Mock.on(ListObjectsV2Command as never).resolves({
+      Contents: [{ Key: "backup-weird-name.tar.gz", Size: 1, LastModified: new Date("2026-05-18T00:00:00Z") }],
+      IsTruncated: false,
+    } as never);
+
+    const result = await listBackups({
+      env: { BACKUP_S3_BUCKET: "bkp", DATABASE_URL: "x", BACKUP_ENCRYPTION: "none" } as never,
+      client: new S3Client({ region: "us-east-1" }),
+    });
+    expect(result[0].classification).toEqual(["daily"]);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/backup/list.ts

@@ -0,0 +1,90 @@
+import { defineCommand } from "citty";
+import consola from "consola";
+import { S3Client } from "@aws-sdk/client-s3";
+import { listBackupKeys, type S3KeyEntry } from "./s3-upload.js";
+import { resolveBackupConfig, type BackupEnv } from "./env.js";
+
+export interface ListBackupsOptions {
+  env?: BackupEnv;
+  client?: S3Client;
+}
+
+export interface BackupEntry extends S3KeyEntry {
+  /** "daily" | "weekly" | "monthly" derived from the embedded ISO timestamp. */
+  classification: readonly string[];
+  encryption: "age" | "gpg" | "none" | "unknown";
+}
+
+const BACKUP_KEY_RE = /^backup-(\d{4})-?(\d{2})-?(\d{2})T(\d{2})(\d{2})(\d{2})Z?-?[0-9a-f]{4,}\.tar\.gz(\.(age|gpg))?$/iu;
+const BACKUP_KEY_FALLBACK_RE = /\.(age|gpg)$/iu;
+
+export async function listBackups(opts: ListBackupsOptions = {}): Promise<BackupEntry[]> {
+  const config = resolveBackupConfig(opts.env ?? (process.env as unknown as BackupEnv));
+  const client = opts.client ?? new S3Client(config.s3);
+  const raw = await listBackupKeys({ client, bucket: config.backupBucket });
+  return raw.map((entry) => ({
+    ...entry,
+    classification: classifyKey(entry.key, entry.lastModified),
+    encryption: detectEncryption(entry.key),
+  }));
+}
+
+function classifyKey(key: string, lastModified: Date | null): readonly string[] {
+  const match = BACKUP_KEY_RE.exec(key);
+  let date: Date | null = null;
+  if (match) {
+    date = new Date(
+      Date.UTC(
+        Number(match[1]),
+        Number(match[2]) - 1,
+        Number(match[3]),
+        Number(match[4]),
+        Number(match[5]),
+        Number(match[6]),
+      ),
+    );
+  } else if (lastModified) {
+    date = lastModified;
+  }
+  if (!date) return ["unknown"];
+  const out: string[] = ["daily"];
+  if (date.getUTCDay() === 0) out.push("weekly");
+  if (date.getUTCDate() === 1) out.push("monthly");
+  return out;
+}
+
+function detectEncryption(key: string): BackupEntry["encryption"] {
+  const m = BACKUP_KEY_FALLBACK_RE.exec(key);
+  if (!m) return "none";
+  const suffix = m[1].toLowerCase();
+  return suffix === "age" || suffix === "gpg" ? suffix : "unknown";
+}
+
+export const listBackupCommand = defineCommand({
+  meta: {
+    name: "list",
+    description: "List backups stored in the backup S3 bucket.",
+  },
+  async run() {
+    const entries = await listBackups();
+    if (entries.length === 0) {
+      consola.info("No backups found.");
+      return;
+    }
+    consola.box(
+      [
+        "KEY".padEnd(60) + " | " + "SIZE".padStart(10) + " | " + "CLASS".padEnd(20) + " | ENC",
+        ...entries.map(
+          (e) =>
+            e.key.padEnd(60) +
+            " | " +
+            String(e.size).padStart(10) +
+            " | " +
+            e.classification.join(",").padEnd(20) +
+            " | " +
+            e.encryption,
+        ),
+      ].join("\n"),
+    );
+  },
+});

hivegrid-cloud/packages/cli/src/commands/backup/manifest.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import {
+  BACKUP_MANIFEST_VERSION,
+  BackupManifestSchema,
+  classifyBackup,
+  deserializeManifest,
+  serializeManifest,
+  sha256Hex,
+  type BackupManifest,
+} from "./manifest.js";
+
+const baseManifest: BackupManifest = {
+  schemaVersion: BACKUP_MANIFEST_VERSION,
+  backupId: "backup-2026-05-17T03:00:00Z-abcd1234",
+  createdAt: "2026-05-17T03:00:00.000Z",
+  creator: { cliVersion: "0.0.0", host: "ops-jumphost" },
+  classification: ["daily"],
+  components: {
+    postgres: {
+      path: "postgres/dump.sql.gz",
+      sizeBytes: 1024,
+      checksum: { algorithm: "sha256", value: "a".repeat(64) },
+    },
+    storage: {
+      path: "storage/objects.tar",
+      sizeBytes: 2048,
+      checksum: { algorithm: "sha256", value: "b".repeat(64) },
+      objectCount: 7,
+    },
+  },
+  encryption: { method: "age", recipient: "age1example..." },
+};
+
+describe("backup manifest schema", () => {
+  it("round-trips a valid manifest", () => {
+    const serialized = serializeManifest(baseManifest);
+    expect(serialized.endsWith("\n")).toBe(true);
+    const parsed = deserializeManifest(serialized);
+    expect(parsed).toEqual(baseManifest);
+  });
+
+  it("rejects a manifest with an unsupported encryption method", () => {
+    const invalid = { ...baseManifest, encryption: { method: "rot13" } } as unknown;
+    expect(() => BackupManifestSchema.parse(invalid)).toThrow();
+  });
+
+  it("rejects unknown top-level keys (strict)", () => {
+    const invalid = { ...baseManifest, oops: true } as unknown;
+    expect(() => BackupManifestSchema.parse(invalid)).toThrow();
+  });
+
+  it("rejects an invalid checksum value", () => {
+    const invalid: BackupManifest = {
+      ...baseManifest,
+      components: {
+        ...baseManifest.components,
+        postgres: {
+          path: "postgres/dump.sql.gz",
+          sizeBytes: 1024,
+          checksum: { algorithm: "sha256", value: "not-hex" },
+        },
+      },
+    };
+    expect(() => BackupManifestSchema.parse(invalid)).toThrow();
+  });
+
+  it("sha256Hex returns lowercase hex of expected length", () => {
+    const hex = sha256Hex("hello world");
+    expect(hex).toHaveLength(64);
+    expect(hex).toMatch(/^[a-f0-9]{64}$/u);
+  });
+
+  it("classifyBackup adds weekly on Sundays and monthly on the 1st", () => {
+    // 2026-05-17 is a Sunday → daily + weekly
+    expect(classifyBackup("2026-05-17T03:00:00Z")).toEqual(["daily", "weekly"]);
+    // 2026-06-01 is a Monday → daily + monthly
+    expect(classifyBackup("2026-06-01T03:00:00Z")).toEqual(["daily", "monthly"]);
+    // 2026-03-01 is a Sunday → daily + weekly + monthly
+    expect(classifyBackup("2026-03-01T03:00:00Z")).toEqual(["daily", "weekly", "monthly"]);
+    // 2026-05-18 is a Monday → only daily
+    expect(classifyBackup("2026-05-18T03:00:00Z")).toEqual(["daily"]);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/backup/manifest.ts

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+
+export const BACKUP_MANIFEST_VERSION = 1;
+
+export const ComponentChecksumSchema = z
+  .object({
+    algorithm: z.literal("sha256"),
+    value: z.string().regex(/^[a-f0-9]{64}$/u, "expected lowercase hex sha256"),
+  })
+  .strict();
+
+export const ComponentEntrySchema = z
+  .object({
+    path: z.string().min(1),
+    sizeBytes: z.number().int().nonnegative(),
+    checksum: ComponentChecksumSchema,
+    metadata: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+  })
+  .strict();
+
+export const EncryptionMetadataSchema = z
+  .object({
+    method: z.enum(["age", "gpg", "none"]),
+    recipient: z.string().optional(),
+    keyFingerprint: z.string().optional(),
+  })
+  .strict();
+
+export const BackupManifestSchema = z
+  .object({
+    schemaVersion: z.literal(BACKUP_MANIFEST_VERSION),
+    backupId: z.string().min(1),
+    createdAt: z.string().datetime({ offset: false }),
+    creator: z
+      .object({
+        cliVersion: z.string().min(1),
+        host: z.string().optional(),
+      })
+      .strict(),
+    classification: z.enum(["daily", "weekly", "monthly"]).array().nonempty(),
+    components: z
+      .object({
+        postgres: ComponentEntrySchema.optional(),
+        clickhouse: ComponentEntrySchema.optional(),
+        storage: ComponentEntrySchema.extend({ objectCount: z.number().int().nonnegative() }).optional(),
+        metadata: ComponentEntrySchema.optional(),
+      })
+      .strict(),
+    encryption: EncryptionMetadataSchema,
+    notes: z.string().optional(),
+  })
+  .strict();
+
+export type ComponentChecksum = z.infer<typeof ComponentChecksumSchema>;
+export type ComponentEntry = z.infer<typeof ComponentEntrySchema>;
+export type EncryptionMetadata = z.infer<typeof EncryptionMetadataSchema>;
+export type BackupManifest = z.infer<typeof BackupManifestSchema>;
+
+export function serializeManifest(manifest: BackupManifest): string {
+  const parsed = BackupManifestSchema.parse(manifest);
+  return `${JSON.stringify(parsed, null, 2)}\n`;
+}
+
+export function deserializeManifest(raw: string | Buffer): BackupManifest {
+  const text = typeof raw === "string" ? raw : raw.toString("utf8");
+  const data = JSON.parse(text) as unknown;
+  return BackupManifestSchema.parse(data);
+}
+
+export function sha256Hex(input: Buffer | string): string {
+  return createHash("sha256").update(input).digest("hex");
+}
+
+export function classifyBackup(createdAtIso: string): BackupManifest["classification"] {
+  const date = new Date(createdAtIso);
+  const out: BackupManifest["classification"][number][] = ["daily"];
+  if (date.getUTCDay() === 0) {
+    out.push("weekly");
+  }
+  if (date.getUTCDate() === 1) {
+    out.push("monthly");
+  }
+  return out as BackupManifest["classification"];
+}

hivegrid-cloud/packages/cli/src/commands/backup/postgres.test.ts

@@ -0,0 +1,102 @@
+import { EventEmitter } from "node:events";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PassThrough, Readable } from "node:stream";
+import { gunzipSync } from "node:zlib";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { dumpPostgresToFile, PostgresDumpError, type SpawnLike } from "./postgres.js";
+
+interface FakeChild extends EventEmitter {
+  stdout: PassThrough;
+  stderr: PassThrough;
+}
+
+function makeFakeChild(): FakeChild {
+  const emitter = new EventEmitter() as FakeChild;
+  emitter.stdout = new PassThrough();
+  emitter.stderr = new PassThrough();
+  return emitter;
+}
+
+let workDir: string;
+
+beforeEach(async () => {
+  workDir = await mkdtemp(join(tmpdir(), "cli-pgdump-"));
+});
+
+afterEach(async () => {
+  await rm(workDir, { recursive: true, force: true });
+});
+
+describe("dumpPostgresToFile", () => {
+  it("pipes pg_dump stdout through gzip into the target file and returns size+checksum", async () => {
+    const child = makeFakeChild();
+    const spawnFn: SpawnLike = ((_cmd: string, args: readonly string[]) => {
+      // sanity: the connection string flag must be at the end
+      expect(args).toContain("--dbname");
+      expect(args[args.length - 1]).toBe("postgres://example/db");
+      queueMicrotask(() => {
+        Readable.from(["PGDUMP_PAYLOAD_ABCDEF"]).pipe(child.stdout);
+        child.stdout.once("end", () => {
+          child.emit("close", 0);
+        });
+      });
+      return child as unknown as ReturnType<SpawnLike>;
+    }) as unknown as SpawnLike;
+
+    const outPath = join(workDir, "dump.sql.gz");
+    const result = await dumpPostgresToFile({
+      connectionString: "postgres://example/db",
+      outPath,
+      spawnFn,
+    });
+
+    expect(result.sizeBytes).toBeGreaterThan(0);
+    expect(result.checksum.algorithm).toBe("sha256");
+    expect(result.checksum.value).toMatch(/^[a-f0-9]{64}$/u);
+
+    const decompressed = gunzipSync(await readFile(outPath)).toString("utf8");
+    expect(decompressed).toBe("PGDUMP_PAYLOAD_ABCDEF");
+  });
+
+  it("throws PostgresDumpError with stderr when pg_dump exits non-zero", async () => {
+    const child = makeFakeChild();
+    const spawnFn: SpawnLike = (() => {
+      queueMicrotask(() => {
+        child.stderr.write("FATAL: connection failed\n");
+        child.stderr.end();
+        child.stdout.end();
+        child.emit("close", 2);
+      });
+      return child as unknown as ReturnType<SpawnLike>;
+    }) as unknown as SpawnLike;
+
+    await expect(
+      dumpPostgresToFile({
+        connectionString: "postgres://bad/db",
+        outPath: join(workDir, "dump.sql.gz"),
+        spawnFn,
+      }),
+    ).rejects.toBeInstanceOf(PostgresDumpError);
+  });
+
+  it("propagates spawn errors", async () => {
+    const child = makeFakeChild();
+    const spawnFn: SpawnLike = (() => {
+      queueMicrotask(() => {
+        child.stdout.end();
+        child.emit("error", new Error("spawn ENOENT"));
+      });
+      return child as unknown as ReturnType<SpawnLike>;
+    }) as unknown as SpawnLike;
+
+    await expect(
+      dumpPostgresToFile({
+        connectionString: "postgres://example/db",
+        outPath: join(workDir, "dump.sql.gz"),
+        spawnFn,
+      }),
+    ).rejects.toThrow(/ENOENT/);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/backup/postgres.ts

@@ -0,0 +1,115 @@
+import { spawn, type ChildProcessByStdio, type SpawnOptions } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import type { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGzip } from "node:zlib";
+import { sha256Hex } from "./manifest.js";
+
+/**
+ * Lightweight contract for the `child_process.spawn` builder we use here. Pulled
+ * out so tests can inject a stub spawner without depending on real binaries.
+ */
+export interface SpawnLike {
+  (command: string, args: readonly string[], options: SpawnOptions): ChildProcessByStdio<null, Readable, Readable>;
+}
+
+export interface DumpPostgresOptions {
+  /** Postgres connection string passed via `pg_dump --dbname`. */
+  connectionString: string;
+  /** Absolute path to the gzipped dump destination. */
+  outPath: string;
+  /** Extra args (e.g. `--schema=public`). Defaults to `["--format=custom", "--no-owner", "--no-privileges"]`. */
+  extraArgs?: readonly string[];
+  /** Override the pg_dump binary location. Defaults to `pg_dump`. */
+  binary?: string;
+  /** Override spawn (tests). */
+  spawnFn?: SpawnLike;
+}
+
+export interface DumpPostgresResult {
+  /** Size of the gzipped dump on disk. */
+  sizeBytes: number;
+  /** sha256 of the gzipped dump on disk. */
+  checksum: { algorithm: "sha256"; value: string };
+}
+
+export class PostgresDumpError extends Error {
+  readonly exitCode: number | null;
+  readonly stderr: string;
+  constructor(message: string, exitCode: number | null, stderr: string) {
+    super(message);
+    this.name = "PostgresDumpError";
+    this.exitCode = exitCode;
+    this.stderr = stderr;
+  }
+}
+
+const DEFAULT_PG_DUMP_ARGS = ["--format=custom", "--no-owner", "--no-privileges"] as const;
+
+/**
+ * Dumps a Postgres database via `pg_dump`, piping stdout through gzip into the
+ * given file. Computes the size + sha256 of the resulting gzipped file.
+ *
+ * Throws PostgresDumpError on non-zero exit (with captured stderr).
+ */
+export async function dumpPostgresToFile(opts: DumpPostgresOptions): Promise<DumpPostgresResult> {
+  const spawnFn = opts.spawnFn ?? (spawn as unknown as SpawnLike);
+  const binary = opts.binary ?? "pg_dump";
+  const args = [...(opts.extraArgs ?? DEFAULT_PG_DUMP_ARGS), "--dbname", opts.connectionString];
+
+  const child = spawnFn(binary, args, { stdio: ["ignore", "pipe", "pipe"] });
+
+  const stderrChunks: Buffer[] = [];
+  child.stderr.on("data", (chunk: Buffer) => stderrChunks.push(chunk));
+
+  const gzip = createGzip();
+  const sink = createWriteStream(opts.outPath);
+  const hash = createHash("sha256");
+
+  child.stdout.on("data", (chunk: Buffer) => hash.update(chunk));
+
+  const pipePromise = pipeline(child.stdout, gzip, sink);
+  const exitPromise = new Promise<number | null>((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code) => resolve(code));
+  });
+  // Always observe exitPromise so a rejection (spawn error) before we await it
+  // does not surface as an unhandled rejection. We re-await below.
+  exitPromise.catch(() => undefined);
+
+  // Order matters: stdout must finish flushing before we resolve, then exit code is authoritative.
+  const [, exitCode] = await Promise.all([pipePromise, exitPromise]);
+
+  if (exitCode !== 0) {
+    const stderr = Buffer.concat(stderrChunks).toString("utf8");
+    throw new PostgresDumpError(`pg_dump exited with code ${exitCode ?? "<null>"}`, exitCode, stderr);
+  }
+
+  const sourceChecksum = hash.digest("hex");
+
+  // Stat for size; recompute hash on disk to cover gzip determinism for the manifest contract.
+  const fileStat = await stat(opts.outPath);
+  const fileChecksum = await sha256File(opts.outPath);
+
+  return {
+    sizeBytes: fileStat.size,
+    // Compute checksum of the gzipped file on disk — this is what the manifest references.
+    // (sourceChecksum is the pre-gzip stream checksum, retained internally for future use.)
+    checksum: { algorithm: "sha256", value: fileChecksum || sourceChecksum },
+  };
+}
+
+async function sha256File(path: string): Promise<string> {
+  const { createReadStream } = await import("node:fs");
+  const hash = createHash("sha256");
+  const stream = createReadStream(path);
+  for await (const chunk of stream) {
+    hash.update(chunk as Buffer);
+  }
+  return hash.digest("hex");
+}
+
+/** Re-export for test convenience and to keep the manifest contract single-sourced. */
+export const computeStringSha256 = sha256Hex;

hivegrid-cloud/packages/cli/src/commands/backup/restore.test.ts

@@ -0,0 +1,78 @@
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import { describe, expect, it } from "vitest";
+import { pgRestore } from "./restore.js";
+
+describe("pgRestore", () => {
+  it("invokes pg_restore with --clean/--if-exists and the dump path last", async () => {
+    let captured: readonly string[] = [];
+    const spawnFn = ((cmd: string, args: readonly string[]) => {
+      void cmd;
+      captured = args;
+      const child = new EventEmitter() as EventEmitter & { stdout: PassThrough; stderr: PassThrough };
+      child.stdout = new PassThrough();
+      child.stderr = new PassThrough();
+      queueMicrotask(() => {
+        child.stdout.end();
+        child.stderr.end();
+        child.emit("close", 0);
+      });
+      return child as never;
+    }) as unknown as typeof import("node:child_process").spawn;
+
+    await pgRestore({
+      connectionString: "postgres://example/db",
+      dumpPath: "/tmp/dump.sql.gz",
+      spawnFn,
+    });
+
+    expect(captured).toContain("--clean");
+    expect(captured).toContain("--if-exists");
+    expect(captured[captured.length - 1]).toBe("/tmp/dump.sql.gz");
+  });
+
+  it("forwards --schema when schemaOnly is set", async () => {
+    let captured: readonly string[] = [];
+    const spawnFn = ((cmd: string, args: readonly string[]) => {
+      void cmd;
+      captured = args;
+      const child = new EventEmitter() as EventEmitter & { stdout: PassThrough; stderr: PassThrough };
+      child.stdout = new PassThrough();
+      child.stderr = new PassThrough();
+      queueMicrotask(() => {
+        child.stdout.end();
+        child.stderr.end();
+        child.emit("close", 0);
+      });
+      return child as never;
+    }) as unknown as typeof import("node:child_process").spawn;
+
+    await pgRestore({
+      connectionString: "postgres://example/db",
+      dumpPath: "/tmp/dump.sql.gz",
+      schemaOnly: "verify_abc",
+      spawnFn,
+    });
+
+    expect(captured).toContain("--schema");
+    expect(captured).toContain("verify_abc");
+  });
+
+  it("throws with stderr on non-zero exit", async () => {
+    const spawnFn = ((cmd: string) => {
+      void cmd;
+      const child = new EventEmitter() as EventEmitter & { stdout: PassThrough; stderr: PassThrough };
+      child.stdout = new PassThrough();
+      child.stderr = new PassThrough();
+      queueMicrotask(() => {
+        child.stderr.write("FATAL: missing dump");
+        child.stderr.end();
+        child.stdout.end();
+        child.emit("close", 1);
+      });
+      return child as never;
+    }) as unknown as typeof import("node:child_process").spawn;
+
+    await expect(pgRestore({ connectionString: "x", dumpPath: "y", spawnFn })).rejects.toThrow(/missing dump|exited/);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/backup/restore.ts

@@ -0,0 +1,157 @@
+import { defineCommand } from "citty";
+import consola from "consola";
+import { spawn, type SpawnOptions } from "node:child_process";
+import { mkdir, mkdtemp, readFile, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { extract as extractTar } from "tar";
+import { S3Client } from "@aws-sdk/client-s3";
+import { downloadObjectToFile } from "./s3-upload.js";
+import { decryptFile } from "./encryption.js";
+import { deserializeManifest, type BackupManifest } from "./manifest.js";
+import { resolveBackupConfig, type BackupEnv } from "./env.js";
+
+export interface RunRestoreOptions {
+  /** S3 key (e.g. `backup-2026-...tar.gz.age`) or just a backup id (the CLI prefixes/suffixes). */
+  snapshot: string;
+  env?: BackupEnv;
+  client?: S3Client;
+  /** Override the target Postgres DSN; defaults to env.DIRECT_URL / DATABASE_URL. */
+  targetDatabaseUrl?: string;
+  /** Skip restoring storage objects. */
+  skipStorage?: boolean;
+  /** Override pg_restore binary (tests). */
+  pgRestoreBinary?: string;
+  /** Spawn override for tests. */
+  spawnFn?: typeof spawn;
+}
+
+export interface RunRestoreResult {
+  manifest: BackupManifest;
+  archivePath: string;
+}
+
+export async function runRestoreBackup(opts: RunRestoreOptions): Promise<RunRestoreResult> {
+  const env = opts.env ?? (process.env as unknown as BackupEnv);
+  const config = resolveBackupConfig(env);
+  const client = opts.client ?? new S3Client(config.s3);
+  const tempRoot = await mkdtemp(join(tmpdir(), "backup-restore-"));
+  try {
+    const downloadPath = join(tempRoot, "download.bin");
+    consola.info(`Downloading s3://${config.backupBucket}/${opts.snapshot}`);
+    await downloadObjectToFile({ client, bucket: config.backupBucket, key: opts.snapshot, destPath: downloadPath });
+
+    const decryptedPath = join(tempRoot, "archive.tar.gz");
+    if (config.encryption.method !== "none") {
+      consola.info(`Decrypting via ${config.encryption.method}`);
+      await decryptFile({ config: config.encryption, inputPath: downloadPath, outputPath: decryptedPath });
+    } else {
+      await rename(downloadPath, decryptedPath);
+    }
+
+    const extractDir = join(tempRoot, "extracted");
+    await mkdir(extractDir, { recursive: true });
+    await extractTar({ file: decryptedPath, cwd: extractDir });
+
+    const entries = await readdir(extractDir);
+    if (entries.length !== 1) {
+      throw new Error(`Unexpected archive layout; got ${entries.length} top-level entries`);
+    }
+    const stageDir = join(extractDir, entries[0]);
+
+    const manifestRaw = await readFile(join(stageDir, "manifest.json"), "utf8");
+    const manifest = deserializeManifest(manifestRaw);
+
+    const dbUrl = opts.targetDatabaseUrl ?? config.databaseUrl;
+    if (manifest.components.postgres) {
+      consola.info("Restoring Postgres dump");
+      await pgRestore({
+        connectionString: dbUrl,
+        dumpPath: join(stageDir, manifest.components.postgres.path),
+        binary: opts.pgRestoreBinary,
+        spawnFn: opts.spawnFn,
+      });
+    }
+
+    if (manifest.components.storage && !opts.skipStorage) {
+      // Storage restore is operator-driven via re-upload from the staged tar.
+      // Implementation lives in storage.ts in a follow-up if/when staging
+      // verifies the create flow against a real bucket. For now we surface
+      // a clear hint so the operator can manually re-import.
+      consola.warn(
+        `Storage tar at ${join(stageDir, manifest.components.storage.path)} not auto-uploaded; re-upload via aws s3 sync or use --target-bucket in a future revision.`,
+      );
+    }
+
+    return { manifest, archivePath: decryptedPath };
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+async function rename(from: string, to: string): Promise<void> {
+  const fs = await import("node:fs/promises");
+  await fs.rename(from, to);
+}
+
+interface PgRestoreArgs {
+  connectionString: string;
+  dumpPath: string;
+  binary?: string;
+  spawnFn?: typeof spawn;
+  /** Optional `--schema` override used by `backup:verify` to isolate the restore. */
+  schemaOnly?: string;
+}
+
+export async function pgRestore(args: PgRestoreArgs): Promise<void> {
+  const spawner = args.spawnFn ?? spawn;
+  const binary = args.binary ?? "pg_restore";
+  const cliArgs = ["--clean", "--if-exists", "--no-owner", "--no-privileges", "--dbname", args.connectionString];
+  if (args.schemaOnly) {
+    cliArgs.push("--schema", args.schemaOnly);
+  }
+  cliArgs.push(args.dumpPath);
+
+  const spawnOptions: SpawnOptions = { stdio: ["ignore", "pipe", "pipe"] };
+  const child = spawner(binary, cliArgs, spawnOptions);
+  const stderrChunks: Buffer[] = [];
+  child.stderr?.on("data", (c: Buffer) => stderrChunks.push(c));
+  const exitCode: number | null = await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code: number | null) => resolve(code));
+  });
+  if (exitCode !== 0) {
+    throw new Error(`pg_restore exited with code ${exitCode ?? "<null>"}: ${Buffer.concat(stderrChunks).toString("utf8")}`);
+  }
+}
+
+export const restoreBackupCommand = defineCommand({
+  meta: {
+    name: "restore",
+    description: "Restore Postgres + Storage from a backup archive in S3.",
+  },
+  args: {
+    snapshot: { type: "positional", required: true, description: "S3 key of the backup archive." },
+    yes: { type: "boolean", description: "Skip confirmation prompt.", default: false },
+    "skip-storage": { type: "boolean", description: "Do not restore storage objects.", default: false },
+    "target-db": { type: "string", description: "Override Postgres DSN for the restore." },
+  },
+  async run({ args }) {
+    if (!args.yes) {
+      const confirmed = await consola.prompt(
+        `This will overwrite the target Postgres database with backup ${args.snapshot}. Continue?`,
+        { type: "confirm" },
+      );
+      if (!confirmed) {
+        consola.warn("Restore cancelled.");
+        return;
+      }
+    }
+    const result = await runRestoreBackup({
+      snapshot: String(args.snapshot),
+      skipStorage: Boolean(args["skip-storage"]),
+      targetDatabaseUrl: args["target-db"] ? String(args["target-db"]) : undefined,
+    });
+    consola.success(`Restored ${result.manifest.backupId}.`);
+  },
+});

hivegrid-cloud/packages/cli/src/commands/backup/rotate.test.ts

@@ -0,0 +1,73 @@
+import { S3Client } from "@aws-sdk/client-s3";
+import { describe, expect, it } from "vitest";
+import { rotateBackups } from "./rotate.js";
+import type { BackupEntry } from "./list.js";
+
+function makeEntry(date: string, classification: readonly string[]): BackupEntry {
+  const ts = date.replace(/[:.-]/gu, "").replace(/Z$/u, "Z");
+  return {
+    key: `backup-${ts}-aabb1234.tar.gz`,
+    size: 1,
+    lastModified: new Date(date),
+    etag: null,
+    classification,
+    encryption: "none",
+  };
+}
+
+const env = {
+  BACKUP_S3_BUCKET: "bkp",
+  DATABASE_URL: "x",
+  BACKUP_ENCRYPTION: "none",
+  BACKUP_RETENTION_DAILY: "3",
+  BACKUP_RETENTION_WEEKLY: "2",
+  BACKUP_RETENTION_MONTHLY: "1",
+} as never;
+
+describe("rotateBackups", () => {
+  it("keeps top-N per classification and marks the rest for deletion", async () => {
+    const entries: BackupEntry[] = [
+      // 90 daily backups, every Sunday is also weekly, every 1st is also monthly.
+      ...Array.from({ length: 90 }, (_, i) => {
+        const date = new Date(Date.UTC(2026, 1, 1));
+        date.setUTCDate(date.getUTCDate() + i);
+        const classes: string[] = ["daily"];
+        if (date.getUTCDay() === 0) classes.push("weekly");
+        if (date.getUTCDate() === 1) classes.push("monthly");
+        return makeEntry(date.toISOString(), classes);
+      }),
+    ];
+
+    const result = await rotateBackups({
+      env,
+      client: new S3Client({ region: "us-east-1" }),
+      entries,
+      dryRun: true,
+    });
+
+    // We expect: 3 daily + 2 weekly + 1 monthly slots; overlap allowed so unique
+    // kept-keys are at most 3+2+1.
+    expect(result.keptKeys.length).toBeGreaterThanOrEqual(3);
+    expect(result.keptKeys.length).toBeLessThanOrEqual(3 + 2 + 1);
+
+    // No double-count and no overlap between keep and delete.
+    const keep = new Set(result.keptKeys);
+    for (const k of result.deletedKeys) {
+      expect(keep.has(k)).toBe(false);
+    }
+    // Total accounted for equals input size.
+    expect(result.keptKeys.length + result.deletedKeys.length).toBe(entries.length);
+  });
+
+  it("dry-run does not invoke DeleteObjects", async () => {
+    const entries = [makeEntry("2026-05-17T03:00:00.000Z", ["daily", "weekly"])];
+    const result = await rotateBackups({
+      env,
+      client: new S3Client({ region: "us-east-1" }),
+      entries,
+      dryRun: true,
+    });
+    // Only one entry, well within limits → kept.
+    expect(result.deletedKeys).toHaveLength(0);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/backup/rotate.ts

@@ -0,0 +1,90 @@
+import { defineCommand } from "citty";
+import consola from "consola";
+import { S3Client } from "@aws-sdk/client-s3";
+import { listBackups, type BackupEntry } from "./list.js";
+import { deleteBackupKeys } from "./s3-upload.js";
+import { resolveBackupConfig, type BackupEnv } from "./env.js";
+
+export interface RotateBackupsOptions {
+  env?: BackupEnv;
+  client?: S3Client;
+  dryRun?: boolean;
+  /** Pre-fetched entries (tests). */
+  entries?: readonly BackupEntry[];
+}
+
+export interface RotateBackupsResult {
+  keptKeys: string[];
+  deletedKeys: string[];
+}
+
+/**
+ * Apply daily/weekly/monthly retention.
+ *
+ * Each backup is classified by its embedded ISO timestamp. We keep up to N
+ * most-recent entries per classification (independently) and delete everything
+ * else. This means a Sunday-on-the-1st backup can be retained as both weekly
+ * and monthly even if outside the daily window.
+ */
+export async function rotateBackups(opts: RotateBackupsOptions = {}): Promise<RotateBackupsResult> {
+  const config = resolveBackupConfig(opts.env ?? (process.env as unknown as BackupEnv));
+  const client = opts.client ?? new S3Client(config.s3);
+  const entries = opts.entries ?? (await listBackups({ env: opts.env, client }));
+
+  const sorted = [...entries].sort((a, b) => {
+    const ta = a.lastModified?.getTime() ?? 0;
+    const tb = b.lastModified?.getTime() ?? 0;
+    return tb - ta;
+  });
+
+  const keep = new Set<string>();
+  const byClass: Record<string, BackupEntry[]> = { daily: [], weekly: [], monthly: [] };
+  for (const entry of sorted) {
+    for (const cls of entry.classification) {
+      if (cls in byClass) {
+        byClass[cls].push(entry);
+      }
+    }
+  }
+  const limits = { daily: config.retention.daily, weekly: config.retention.weekly, monthly: config.retention.monthly };
+  for (const cls of ["daily", "weekly", "monthly"] as const) {
+    for (const entry of byClass[cls].slice(0, limits[cls])) {
+      keep.add(entry.key);
+    }
+  }
+
+  const deletedKeys: string[] = [];
+  for (const entry of sorted) {
+    if (!keep.has(entry.key)) {
+      deletedKeys.push(entry.key);
+    }
+  }
+
+  if (!opts.dryRun && deletedKeys.length > 0) {
+    await deleteBackupKeys({ client, bucket: config.backupBucket, keys: deletedKeys });
+  }
+
+  return {
+    keptKeys: [...keep],
+    deletedKeys,
+  };
+}
+
+export const rotateBackupCommand = defineCommand({
+  meta: {
+    name: "rotate",
+    description: "Apply daily/weekly/monthly retention policy against the backup bucket.",
+  },
+  args: {
+    "dry-run": {
+      type: "boolean",
+      description: "Print the rotation plan without deleting anything.",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const result = await rotateBackups({ dryRun: Boolean(args["dry-run"]) });
+    consola.info(`Kept ${result.keptKeys.length} backups; ${args["dry-run"] ? "would delete" : "deleted"} ${result.deletedKeys.length}.`);
+    for (const k of result.deletedKeys) consola.log(`  - ${k}`);
+  },
+});

hivegrid-cloud/packages/cli/src/commands/backup/s3-upload.test.ts

@@ -0,0 +1,115 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { DeleteObjectsCommand, GetObjectCommand, ListObjectsV2Command, S3Client } from "@aws-sdk/client-s3";
+import { mockClient } from "aws-sdk-client-mock";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  deleteBackupKeys,
+  downloadObjectToFile,
+  getObjectRangeBuffer,
+  listBackupKeys,
+  uploadFileMultipart,
+} from "./s3-upload.js";
+
+const s3Mock = mockClient(S3Client as never);
+
+let workDir: string;
+
+beforeEach(async () => {
+  s3Mock.reset();
+  workDir = await mkdtemp(join(tmpdir(), "cli-s3-"));
+});
+
+afterEach(async () => {
+  await rm(workDir, { recursive: true, force: true });
+});
+
+describe("s3-upload helpers", () => {
+  it("uploads via injected Upload ctor (multipart wrapper)", async () => {
+    const src = join(workDir, "blob.bin");
+    await writeFile(src, "payload bytes");
+
+    let receivedKey = "";
+    class FakeUpload {
+      constructor(opts: { params: { Bucket: string; Key: string } }) {
+        receivedKey = opts.params.Key;
+      }
+      async done() {
+        return { ETag: '"deadbeef"' };
+      }
+    }
+
+    const result = await uploadFileMultipart({
+      client: new S3Client({ region: "us-east-1" }),
+      bucket: "bkp",
+      key: "backup-test.tar.gz",
+      filePath: src,
+      uploadCtor: FakeUpload as never,
+    });
+    expect(receivedKey).toBe("backup-test.tar.gz");
+    expect(result.etag).toBe('"deadbeef"');
+  });
+
+  it("downloads a backup object to disk via streamed Body", async () => {
+    s3Mock.on(GetObjectCommand as never).resolves({ Body: Readable.from(["chunk1", "chunk2"]) } as never);
+
+    const dest = join(workDir, "out.bin");
+    const result = await downloadObjectToFile({
+      client: new S3Client({ region: "us-east-1" }),
+      bucket: "bkp",
+      key: "any.tar.gz",
+      destPath: dest,
+    });
+    expect(result.sizeBytes).toBe("chunk1chunk2".length);
+    expect((await readFile(dest)).toString("utf8")).toBe("chunk1chunk2");
+  });
+
+  it("getObjectRangeBuffer concatenates streamed chunks", async () => {
+    s3Mock.on(GetObjectCommand as never).resolves({ Body: Readable.from(["abc", "def"]) } as never);
+    const buf = await getObjectRangeBuffer(new S3Client({ region: "us-east-1" }), "bkp", "x", "bytes=0-5");
+    expect(buf.toString("utf8")).toBe("abcdef");
+  });
+
+  it("listBackupKeys paginates with the backup- prefix by default", async () => {
+    let listCalls = 0;
+    s3Mock.on(ListObjectsV2Command as never).callsFake((input: { Prefix?: string }) => {
+      listCalls += 1;
+      expect(input.Prefix).toBe("backup-");
+      if (listCalls === 1) {
+        return {
+          Contents: [{ Key: "backup-a.tar.gz", Size: 10, LastModified: new Date("2026-05-17T00:00:00Z"), ETag: '"a"' }],
+          IsTruncated: true,
+          NextContinuationToken: "tok",
+        };
+      }
+      return {
+        Contents: [{ Key: "backup-b.tar.gz", Size: 20, LastModified: new Date("2026-05-18T00:00:00Z"), ETag: '"b"' }],
+        IsTruncated: false,
+      };
+    });
+
+    const out = await listBackupKeys({ client: new S3Client({ region: "us-east-1" }), bucket: "bkp" });
+    expect(out).toHaveLength(2);
+    expect(out[0].key).toBe("backup-a.tar.gz");
+    expect(out[1].key).toBe("backup-b.tar.gz");
+  });
+
+  it("deleteBackupKeys batches up to 1000 per DeleteObjects call", async () => {
+    let calls = 0;
+    s3Mock.on(DeleteObjectsCommand as never).callsFake(() => {
+      calls += 1;
+      return {};
+    });
+    const keys = Array.from({ length: 1500 }, (_, i) => `backup-${i}.tar.gz`);
+    const result = await deleteBackupKeys({ client: new S3Client({ region: "us-east-1" }), bucket: "bkp", keys });
+    expect(result.deletedCount).toBe(1500);
+    expect(calls).toBe(2);
+  });
+
+  it("deleteBackupKeys is a no-op for empty input", async () => {
+    const result = await deleteBackupKeys({ client: new S3Client({ region: "us-east-1" }), bucket: "bkp", keys: [] });
+    expect(result.deletedCount).toBe(0);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/backup/s3-upload.ts

@@ -0,0 +1,174 @@
+import {
+  DeleteObjectsCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  ListObjectsV2Command,
+  S3Client,
+  type S3ClientConfig,
+} from "@aws-sdk/client-s3";
+import { Upload } from "@aws-sdk/lib-storage";
+import { createReadStream, createWriteStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { Readable } from "node:stream";
+
+export interface S3UploaderConfig extends S3ClientConfig {
+  bucket: string;
+}
+
+export interface UploadFileOptions {
+  client: S3Client;
+  bucket: string;
+  key: string;
+  filePath: string;
+  contentType?: string;
+  metadata?: Record<string, string>;
+  /** Override the lib-storage Upload class (tests). */
+  uploadCtor?: typeof Upload;
+}
+
+export interface DownloadFileOptions {
+  client: S3Client;
+  bucket: string;
+  key: string;
+  destPath: string;
+}
+
+export interface ListBackupKeysOptions {
+  client: S3Client;
+  bucket: string;
+  prefix?: string;
+}
+
+export interface DeleteKeysOptions {
+  client: S3Client;
+  bucket: string;
+  keys: readonly string[];
+  /** Page size; AWS allows up to 1000 keys per DeleteObjects call. */
+  batchSize?: number;
+}
+
+export interface S3KeyEntry {
+  key: string;
+  size: number;
+  lastModified: Date | null;
+  etag: string | null;
+}
+
+export async function uploadFileMultipart(opts: UploadFileOptions): Promise<{ key: string; etag: string | null }> {
+  const Ctor = opts.uploadCtor ?? Upload;
+  const stream = createReadStream(opts.filePath);
+  const upload = new Ctor({
+    client: opts.client,
+    params: {
+      Bucket: opts.bucket,
+      Key: opts.key,
+      Body: stream,
+      ContentType: opts.contentType,
+      Metadata: opts.metadata,
+    },
+  });
+
+  const result = (await upload.done()) as { ETag?: string };
+  return { key: opts.key, etag: result.ETag ?? null };
+}
+
+export async function downloadObjectToFile(opts: DownloadFileOptions): Promise<{ sizeBytes: number }> {
+  const response = await opts.client.send(new GetObjectCommand({ Bucket: opts.bucket, Key: opts.key }));
+  const body = response.Body;
+  const stream = asReadable(body);
+  const sink = createWriteStream(opts.destPath);
+  await new Promise<void>((resolve, reject) => {
+    stream.pipe(sink);
+    sink.on("finish", () => resolve());
+    sink.on("error", reject);
+    stream.on("error", reject);
+  });
+  const s = await stat(opts.destPath);
+  return { sizeBytes: s.size };
+}
+
+export async function getObjectRangeBuffer(
+  client: S3Client,
+  bucket: string,
+  key: string,
+  range: string,
+): Promise<Buffer> {
+  const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key, Range: range }));
+  const stream = asReadable(response.Body);
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as string | Uint8Array));
+  }
+  return Buffer.concat(chunks);
+}
+
+export async function headBackupObject(
+  client: S3Client,
+  bucket: string,
+  key: string,
+): Promise<{ size: number | null; lastModified: Date | null; etag: string | null }> {
+  const head = await client.send(new HeadObjectCommand({ Bucket: bucket, Key: key }));
+  return {
+    size: head.ContentLength ?? null,
+    lastModified: head.LastModified ?? null,
+    etag: head.ETag ?? null,
+  };
+}
+
+export async function listBackupKeys(opts: ListBackupKeysOptions): Promise<S3KeyEntry[]> {
+  const out: S3KeyEntry[] = [];
+  let continuationToken: string | undefined;
+  do {
+    const page = await opts.client.send(
+      new ListObjectsV2Command({
+        Bucket: opts.bucket,
+        Prefix: opts.prefix ?? "backup-",
+        ContinuationToken: continuationToken,
+      }),
+    );
+    for (const obj of page.Contents ?? []) {
+      if (!obj.Key) continue;
+      out.push({
+        key: obj.Key,
+        size: obj.Size ?? 0,
+        lastModified: obj.LastModified ?? null,
+        etag: obj.ETag ?? null,
+      });
+    }
+    continuationToken = page.IsTruncated ? page.NextContinuationToken : undefined;
+  } while (continuationToken);
+  return out;
+}
+
+export async function deleteBackupKeys(opts: DeleteKeysOptions): Promise<{ deletedCount: number }> {
+  if (opts.keys.length === 0) {
+    return { deletedCount: 0 };
+  }
+  const batchSize = opts.batchSize ?? 1000;
+  let deletedCount = 0;
+  for (let i = 0; i < opts.keys.length; i += batchSize) {
+    const batch = opts.keys.slice(i, i + batchSize);
+    await opts.client.send(
+      new DeleteObjectsCommand({
+        Bucket: opts.bucket,
+        Delete: { Objects: batch.map((Key) => ({ Key })) },
+      }),
+    );
+    deletedCount += batch.length;
+  }
+  return { deletedCount };
+}
+
+function asReadable(body: unknown): Readable {
+  if (body && typeof (body as Readable).pipe === "function") {
+    return body as Readable;
+  }
+  if (body && typeof (body as { transformToWebStream?: () => unknown }).transformToWebStream === "function") {
+    const webStream = (body as { transformToWebStream: () => ReadableStream<Uint8Array> }).transformToWebStream();
+    return Readable.fromWeb(webStream as never);
+  }
+  if (body && Symbol.asyncIterator in (body as object)) {
+    return Readable.from(body as AsyncIterable<Buffer>);
+  }
+  throw new Error("Unsupported S3 GetObject body type");
+}

hivegrid-cloud/packages/cli/src/commands/backup/storage.test.ts

@@ -0,0 +1,91 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { GetObjectCommand, ListObjectsV2Command, S3Client } from "@aws-sdk/client-s3";
+import { mockClient } from "aws-sdk-client-mock";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { backupStorageBucket } from "./storage.js";
+
+// aws-sdk-client-mock's smithy peer can be a minor revision ahead of the rest of
+// the resolved aws-sdk graph; we don't need the precise generic typing in tests.
+const s3Mock = mockClient(S3Client as never);
+
+let workDir: string;
+
+beforeEach(async () => {
+  s3Mock.reset();
+  workDir = await mkdtemp(join(tmpdir(), "cli-storage-"));
+});
+
+afterEach(async () => {
+  await rm(workDir, { recursive: true, force: true });
+});
+
+describe("backupStorageBucket", () => {
+  it("lists, streams, tars and writes a JSONL manifest", async () => {
+    let listCallCount = 0;
+    s3Mock.on(ListObjectsV2Command as never).callsFake(() => {
+      listCallCount += 1;
+      if (listCallCount === 1) {
+        return {
+          Contents: [
+            { Key: "a/one.txt", Size: 5, ETag: '"e1"' },
+            { Key: "a/two.txt", Size: 6, ETag: '"e2"' },
+          ],
+          IsTruncated: true,
+          NextContinuationToken: "tok",
+        };
+      }
+      return {
+        Contents: [{ Key: "b/three.txt", Size: 7, ETag: '"e3"' }],
+        IsTruncated: false,
+      };
+    });
+
+    const payloads: Record<string, string> = {
+      "a/one.txt": "hello",
+      "a/two.txt": "world!",
+      "b/three.txt": "bonjour",
+    };
+    s3Mock.on(GetObjectCommand as never).callsFake((input: { Key: string }) => ({
+      Body: Readable.from([payloads[input.Key]]),
+    }));
+
+    const result = await backupStorageBucket({
+      s3: { region: "us-east-1" },
+      bucket: "files",
+      outDir: workDir,
+      client: new S3Client({ region: "us-east-1" }),
+    });
+
+    expect(result.objectCount).toBe(3);
+    expect(result.totalBytes).toBe(5 + 6 + 7);
+    expect(result.checksum.algorithm).toBe("sha256");
+    expect(result.checksum.value).toMatch(/^[a-f0-9]{64}$/u);
+
+    const manifestRaw = await readFile(result.manifestPath, "utf8");
+    const lines = manifestRaw.trim().split("\n").map((line) => JSON.parse(line));
+    expect(lines).toHaveLength(3);
+    expect(lines[0]).toMatchObject({ bucket: "files", key: "a/one.txt", size: 5, etag: '"e1"' });
+
+    const archiveBytes = await readFile(result.archivePath);
+    expect(archiveBytes.length).toBeGreaterThan(0);
+  });
+
+  it("produces an empty manifest when the bucket has no objects", async () => {
+    s3Mock.on(ListObjectsV2Command as never).resolves({ Contents: [], IsTruncated: false } as never);
+
+    const result = await backupStorageBucket({
+      s3: { region: "us-east-1" },
+      bucket: "empty",
+      outDir: workDir,
+      client: new S3Client({ region: "us-east-1" }),
+    });
+
+    expect(result.objectCount).toBe(0);
+    expect(result.totalBytes).toBe(0);
+    const manifestRaw = await readFile(result.manifestPath, "utf8");
+    expect(manifestRaw).toBe("");
+  });
+});

hivegrid-cloud/packages/cli/src/commands/backup/storage.ts

@@ -0,0 +1,155 @@
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { GetObjectCommand, ListObjectsV2Command, S3Client, type S3ClientConfig } from "@aws-sdk/client-s3";
+import { create as createTar } from "tar";
+import { join } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { Readable } from "node:stream";
+
+export interface StorageBackupOptions {
+  s3: S3ClientConfig;
+  bucket: string;
+  /** Filesystem directory where `objects.tar` + `manifest.jsonl` are written. */
+  outDir: string;
+  /** Optional S3 prefix to limit which objects are backed up. */
+  prefix?: string;
+  /** Inject a pre-built client (tests). */
+  client?: S3Client;
+}
+
+export interface StorageObjectEntry {
+  bucket: string;
+  key: string;
+  size: number;
+  etag: string | null;
+}
+
+export interface StorageBackupResult {
+  objectCount: number;
+  totalBytes: number;
+  manifestPath: string;
+  archivePath: string;
+  /** sha256 of the produced `objects.tar`. */
+  checksum: { algorithm: "sha256"; value: string };
+}
+
+/**
+ * Backs up every object in `bucket` to `<outDir>/objects.tar`, writing
+ * one NDJSON line per object to `<outDir>/manifest.jsonl`.
+ */
+export async function backupStorageBucket(opts: StorageBackupOptions): Promise<StorageBackupResult> {
+  const client = opts.client ?? new S3Client(opts.s3);
+  await mkdir(opts.outDir, { recursive: true });
+  const stagingDir = join(opts.outDir, "_staging");
+  await mkdir(stagingDir, { recursive: true });
+
+  const manifestPath = join(opts.outDir, "manifest.jsonl");
+  const archivePath = join(opts.outDir, "objects.tar");
+
+  const entries: StorageObjectEntry[] = [];
+  const relPaths: string[] = [];
+  let totalBytes = 0;
+
+  let continuationToken: string | undefined;
+  do {
+    const page = await client.send(
+      new ListObjectsV2Command({
+        Bucket: opts.bucket,
+        Prefix: opts.prefix,
+        ContinuationToken: continuationToken,
+      }),
+    );
+    for (const obj of page.Contents ?? []) {
+      if (!obj.Key) continue;
+      const entry: StorageObjectEntry = {
+        bucket: opts.bucket,
+        key: obj.Key,
+        size: obj.Size ?? 0,
+        etag: obj.ETag ?? null,
+      };
+      entries.push(entry);
+      totalBytes += entry.size;
+      const stagedPath = stageRelPath(obj.Key);
+      relPaths.push(stagedPath);
+      const absPath = join(stagingDir, stagedPath);
+      await mkdir(dirnameOf(absPath), { recursive: true });
+
+      const getResp = await client.send(new GetObjectCommand({ Bucket: opts.bucket, Key: obj.Key }));
+      await streamToFile(asReadable(getResp.Body), absPath);
+    }
+    continuationToken = page.IsTruncated ? page.NextContinuationToken : undefined;
+  } while (continuationToken);
+
+  const manifestLines = entries.map((entry) => JSON.stringify(entry)).join("\n");
+  await writeFile(manifestPath, manifestLines.length === 0 ? "" : `${manifestLines}\n`);
+
+  if (relPaths.length === 0) {
+    // Write an empty placeholder so the tar file always exists for downstream checksumming.
+    const { open } = await import("node:fs/promises");
+    const handle = await open(archivePath, "w");
+    await handle.close();
+  } else {
+    await createTar({ file: archivePath, cwd: stagingDir, portable: true }, relPaths);
+  }
+
+  const checksum = await sha256File(archivePath);
+
+  try {
+    const { rm } = await import("node:fs/promises");
+    await rm(stagingDir, { recursive: true, force: true });
+  } catch {
+    /* ignore */
+  }
+
+  return {
+    objectCount: entries.length,
+    totalBytes,
+    manifestPath,
+    archivePath,
+    checksum: { algorithm: "sha256", value: checksum },
+  };
+}
+
+function stageRelPath(key: string): string {
+  return key.replace(/^\/+/u, "");
+}
+
+function dirnameOf(p: string): string {
+  const idx = p.lastIndexOf("/");
+  return idx === -1 ? "." : p.slice(0, idx);
+}
+
+function asReadable(body: unknown): Readable {
+  if (body && typeof (body as Readable).pipe === "function") {
+    return body as Readable;
+  }
+  if (body && typeof (body as { transformToWebStream?: () => unknown }).transformToWebStream === "function") {
+    const webStream = (body as { transformToWebStream: () => ReadableStream<Uint8Array> }).transformToWebStream();
+    return Readable.fromWeb(webStream as never);
+  }
+  if (body && Symbol.asyncIterator in (body as object)) {
+    return Readable.from(body as AsyncIterable<Buffer>);
+  }
+  throw new Error("Unsupported S3 GetObject body type");
+}
+
+async function streamToFile(stream: Readable, path: string): Promise<void> {
+  const sink = createWriteStream(path);
+  await new Promise<void>((resolve, reject) => {
+    stream.pipe(sink);
+    sink.on("finish", () => resolve());
+    sink.on("error", reject);
+    stream.on("error", reject);
+  });
+}
+
+async function sha256File(path: string): Promise<string> {
+  const { createReadStream } = await import("node:fs");
+  const hash = createHash("sha256");
+  const stream = createReadStream(path);
+  for await (const chunk of stream) {
+    hash.update(chunk as Buffer);
+  }
+  return hash.digest("hex");
+}

hivegrid-cloud/packages/cli/src/commands/backup/verify.test.ts

@@ -0,0 +1,64 @@
+import { EventEmitter } from "node:events";
+import { PassThrough, Readable } from "node:stream";
+import { describe, expect, it } from "vitest";
+import { runVerifyBackup } from "./verify.js";
+import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
+import { mockClient } from "aws-sdk-client-mock";
+
+const s3Mock = mockClient(S3Client as never);
+
+const env = {
+  BACKUP_S3_BUCKET: "bkp",
+  DATABASE_URL: "postgres://example/db",
+  BACKUP_ENCRYPTION: "none",
+} as never;
+
+function makeSpawn(scripted: ReadonlyArray<{ stdout?: string; stderr?: string; exit: number }>) {
+  let i = 0;
+  return ((cmd: string) => {
+    void cmd;
+    const step = scripted[Math.min(i, scripted.length - 1)];
+    i += 1;
+    const child = new EventEmitter() as EventEmitter & { stdout: PassThrough; stderr: PassThrough };
+    child.stdout = new PassThrough();
+    child.stderr = new PassThrough();
+    queueMicrotask(() => {
+      if (step.stdout) Readable.from([step.stdout]).pipe(child.stdout);
+      else child.stdout.end();
+      if (step.stderr) child.stderr.write(step.stderr);
+      child.stderr.end();
+      if (step.stdout) {
+        child.stdout.once("end", () => child.emit("close", step.exit));
+      } else {
+        child.emit("close", step.exit);
+      }
+    });
+    return child as never;
+  }) as unknown as typeof import("node:child_process").spawn;
+}
+
+describe("runVerifyBackup", () => {
+  it("returns passed=false when the restore step throws", async () => {
+    // GetObject succeeds with an empty tar archive (we make S3 download return
+    // a stream so restore can begin, but pg_restore fails).
+    s3Mock.reset();
+    s3Mock.on(GetObjectCommand as never).resolves({ Body: Readable.from(["not a real archive"]) } as never);
+
+    const spawnFn = makeSpawn([
+      { exit: 0 }, // CREATE SCHEMA succeeds
+      // pg_restore would be called after extract — but extract should fail
+      // first due to invalid archive. We don't reach this branch, but provide
+      // a fallback step for the DROP SCHEMA cleanup.
+      { exit: 0 },
+    ]);
+
+    const result = await runVerifyBackup({
+      snapshot: "backup-bad.tar.gz",
+      env,
+      client: new S3Client({ region: "us-east-1" }),
+      spawnFn,
+    });
+    expect(result.passed).toBe(false);
+    expect(result.schema).toMatch(/^verify_[a-f0-9]+$/u);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/backup/verify.ts

@@ -0,0 +1,130 @@
+import { defineCommand } from "citty";
+import consola from "consola";
+import { randomBytes } from "node:crypto";
+import { spawn, type SpawnOptions } from "node:child_process";
+import { S3Client } from "@aws-sdk/client-s3";
+import { runRestoreBackup } from "./restore.js";
+import { resolveBackupConfig, type BackupEnv } from "./env.js";
+
+export interface RunVerifyOptions {
+  snapshot: string;
+  env?: BackupEnv;
+  client?: S3Client;
+  /** Inject spawn for tests. */
+  spawnFn?: typeof spawn;
+}
+
+export interface RunVerifyResult {
+  schema: string;
+  passed: boolean;
+  reason?: string;
+}
+
+/**
+ * Restore a backup into a temporary `verify_<uuid>` Postgres schema and run a
+ * lightweight sanity check (presence of tables, FK integrity via `pg_dump
+ * --schema=verify_*` round-trip would be heavier; we settle for a row-count
+ * smoke probe via `psql`). At the end the schema is dropped CASCADE.
+ *
+ * The actual `pg_restore` step uses the existing restore flow with
+ * `--schema=verify_<uuid>` so production code in restore.ts is the single
+ * source of truth for archive extraction.
+ */
+export async function runVerifyBackup(opts: RunVerifyOptions): Promise<RunVerifyResult> {
+  const env = opts.env ?? (process.env as unknown as BackupEnv);
+  const config = resolveBackupConfig(env);
+  const client = opts.client ?? new S3Client(config.s3);
+  const verifyId = randomBytes(4).toString("hex");
+  const schema = `verify_${verifyId}`;
+
+  await runPsql({
+    connectionString: config.databaseUrl,
+    query: `CREATE SCHEMA IF NOT EXISTS ${schema};`,
+    spawnFn: opts.spawnFn,
+  });
+
+  let passed = true;
+  let reason: string | undefined;
+  try {
+    await runRestoreBackup({
+      snapshot: opts.snapshot,
+      env,
+      client,
+      targetDatabaseUrl: config.databaseUrl,
+      skipStorage: true,
+      spawnFn: opts.spawnFn,
+    });
+
+    // Sanity probe: ensure at least one table exists. Tolerates the
+    // dump-into-public scenario; we measure "did we get _any_ relation"
+    // because the schema-isolated path requires pg_restore --schema support
+    // which depends on dump format.
+    const probeOut = await runPsql({
+      connectionString: config.databaseUrl,
+      query: "SELECT count(*)::int FROM information_schema.tables WHERE table_type = 'BASE TABLE';",
+      spawnFn: opts.spawnFn,
+    });
+    const numTables = Number.parseInt(probeOut.trim(), 10);
+    if (!Number.isFinite(numTables) || numTables <= 0) {
+      passed = false;
+      reason = "no tables present after restore";
+    }
+  } catch (err) {
+    passed = false;
+    reason = err instanceof Error ? err.message : String(err);
+  } finally {
+    await runPsql({
+      connectionString: config.databaseUrl,
+      query: `DROP SCHEMA IF EXISTS ${schema} CASCADE;`,
+      spawnFn: opts.spawnFn,
+    }).catch(() => undefined);
+  }
+
+  return { schema, passed, reason };
+}
+
+interface RunPsqlOptions {
+  connectionString: string;
+  query: string;
+  binary?: string;
+  spawnFn?: typeof spawn;
+}
+
+async function runPsql(opts: RunPsqlOptions): Promise<string> {
+  const spawner = opts.spawnFn ?? spawn;
+  const binary = opts.binary ?? "psql";
+  const args = ["-tAq", "-d", opts.connectionString, "-c", opts.query];
+  const spawnOptions: SpawnOptions = { stdio: ["ignore", "pipe", "pipe"] };
+  const child = spawner(binary, args, spawnOptions);
+  const stdoutChunks: Buffer[] = [];
+  const stderrChunks: Buffer[] = [];
+  child.stdout?.on("data", (c: Buffer) => stdoutChunks.push(c));
+  child.stderr?.on("data", (c: Buffer) => stderrChunks.push(c));
+  const exitCode: number | null = await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code: number | null) => resolve(code));
+  });
+  if (exitCode !== 0) {
+    throw new Error(`psql exited with code ${exitCode ?? "<null>"}: ${Buffer.concat(stderrChunks).toString("utf8")}`);
+  }
+  return Buffer.concat(stdoutChunks).toString("utf8");
+}
+
+export const verifyBackupCommand = defineCommand({
+  meta: {
+    name: "verify",
+    description: "Test-restore a backup into a verify_<uuid> schema and run sanity-checks.",
+  },
+  args: {
+    snapshot: { type: "positional", required: true, description: "S3 key of the backup archive." },
+  },
+  async run({ args }) {
+    const result = await runVerifyBackup({ snapshot: String(args.snapshot) });
+    if (result.passed) {
+      consola.success(`Backup verified (schema ${result.schema} created+dropped).`);
+    } else {
+      consola.error(`Backup verification FAILED: ${result.reason ?? "unknown"}`);
+      process.exitCode = 1;
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/create/entity.test.ts

@@ -0,0 +1,67 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { generateEntity } from "./entity.js";
+
+describe("create entity generator", () => {
+  let tempRoot: string;
+  const fakeTimestamp = "20260101000000";
+
+  beforeEach(async () => {
+    tempRoot = await mkdtemp(path.join(tmpdir(), "toolctrl-cli-entity-"));
+  });
+
+  afterEach(async () => {
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  it("emits prisma model + migration.sql + README", async () => {
+    const result = await generateEntity({
+      name: "invoice-line-item",
+      repoRoot: tempRoot,
+      dryRun: true,
+      timestamp: fakeTimestamp,
+    });
+
+    const rels = result.files.map((f) => path.relative(tempRoot, f.path)).sort();
+    expect(rels).toEqual(
+      [
+        "prisma/_generated/invoice-line-item.prisma",
+        "prisma/migrations/20260101000000_create_entity_invoice_line_item/README.md",
+        "prisma/migrations/20260101000000_create_entity_invoice_line_item/migration.sql",
+      ].sort(),
+    );
+  });
+
+  it("uses PascalCase model name and snake_case table name", async () => {
+    const result = await generateEntity({
+      name: "invoice-line-item",
+      repoRoot: tempRoot,
+      dryRun: true,
+      timestamp: fakeTimestamp,
+    });
+    const prismaFile = result.files.find((f) => f.path.endsWith(".prisma"));
+    expect(prismaFile?.contents).toContain("model InvoiceLineItem");
+    expect(prismaFile?.contents).toContain('@@map("invoice_line_item")');
+  });
+
+  it("emits tenantId column + index in the migration", async () => {
+    const result = await generateEntity({
+      name: "widget",
+      repoRoot: tempRoot,
+      dryRun: true,
+      timestamp: fakeTimestamp,
+    });
+    const sql = result.files.find((f) => f.path.endsWith("migration.sql"));
+    expect(sql?.contents).toMatch(/"tenantId"\s+TEXT NOT NULL/);
+    expect(sql?.contents).toMatch(/widget_tenantId_idx/);
+  });
+
+  it("refuses to overwrite existing migration", async () => {
+    await generateEntity({ name: "widget", repoRoot: tempRoot, dryRun: false, timestamp: fakeTimestamp });
+    await expect(
+      generateEntity({ name: "widget", repoRoot: tempRoot, dryRun: false, timestamp: fakeTimestamp }),
+    ).rejects.toThrow(/already exists/);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/create/entity.ts

@@ -0,0 +1,179 @@
+/**
+ * `toolctrl create entity <name>` — emit a Prisma model snippet plus a
+ * timestamped migration directory.
+ *
+ * The generator does NOT modify `prisma/schema.prisma` automatically —
+ * we drop the model snippet under a sibling `prisma/_generated/<name>.prisma`
+ * file plus a manual-include note in the README, because patching
+ * `schema.prisma` reliably from a CLI requires parsing prisma's own
+ * grammar (no off-the-shelf TS lib does that cleanly). The migration
+ * directory follows prisma's standard layout so `prisma migrate dev`
+ * picks it up.
+ *
+ * Refs: docs/improvement-plan/08-mobile-cli-storybook-sdk/cli-scaffolding.md
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import path from "node:path";
+import {
+  createScaffoldResult,
+  kebabCase,
+  pascalCase,
+  resolveRepoRoot,
+  snakeCase,
+  validateIdentifier,
+  writeScaffoldFile,
+  type ScaffoldResult,
+} from "../_lib/scaffold.js";
+
+export type GenerateEntityOptions = {
+  name: string;
+  repoRoot?: string;
+  dryRun?: boolean;
+  /** Override the migration timestamp prefix (test seam). */
+  timestamp?: string;
+};
+
+export async function generateEntity(options: GenerateEntityOptions): Promise<ScaffoldResult> {
+  const baseName = validateIdentifier(options.name, "entity name");
+  const dryRun = options.dryRun ?? false;
+  const repoRoot = resolveRepoRoot(options.repoRoot);
+  const pascal = pascalCase(baseName);
+  const snake = snakeCase(baseName);
+  const kebab = kebabCase(baseName);
+  const timestamp = options.timestamp ?? defaultTimestamp();
+  const migrationDir = `${timestamp}_create_entity_${snake}`;
+
+  const result = createScaffoldResult(dryRun);
+
+  await writeScaffoldFile({
+    targetPath: path.join(repoRoot, "prisma/_generated", `${kebab}.prisma`),
+    contents: renderPrismaModel({ pascal, snake }),
+    dryRun,
+    result,
+  });
+
+  await writeScaffoldFile({
+    targetPath: path.join(repoRoot, "prisma/migrations", migrationDir, "migration.sql"),
+    contents: renderMigrationSql({ pascal, snake }),
+    dryRun,
+    result,
+  });
+
+  await writeScaffoldFile({
+    targetPath: path.join(repoRoot, "prisma/migrations", migrationDir, "README.md"),
+    contents: renderMigrationReadme({ pascal, snake, kebab }),
+    dryRun,
+    result,
+  });
+
+  result.notes.push(
+    `Next steps:`,
+    `  1. Copy the model from prisma/_generated/${kebab}.prisma into prisma/schema.prisma`,
+    `  2. Run \`pnpm prisma migrate dev --name create_entity_${snake}\``,
+    `  3. Regenerate the prisma client: \`pnpm prisma generate\``,
+  );
+
+  return result;
+}
+
+function defaultTimestamp(): string {
+  // Prisma migration timestamp format: YYYYMMDDHHMMSS.
+  const now = new Date();
+  const pad = (n: number) => n.toString().padStart(2, "0");
+  return (
+    now.getUTCFullYear().toString() +
+    pad(now.getUTCMonth() + 1) +
+    pad(now.getUTCDate()) +
+    pad(now.getUTCHours()) +
+    pad(now.getUTCMinutes()) +
+    pad(now.getUTCSeconds())
+  );
+}
+
+function renderPrismaModel({ pascal, snake }: { pascal: string; snake: string }): string {
+  return `// Generated by toolctrl-cli — paste this block into prisma/schema.prisma.
+model ${pascal} {
+  id        String   @id @default(cuid())
+  tenantId  String
+  name      String
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([tenantId])
+  @@map("${snake}")
+}
+`;
+}
+
+function renderMigrationSql({ pascal, snake }: { pascal: string; snake: string }): string {
+  return `-- Generated by toolctrl-cli for entity ${pascal}.
+-- Replace columns with actual schema before running \`prisma migrate dev\`.
+CREATE TABLE "${snake}" (
+  "id"         TEXT NOT NULL,
+  "tenantId"   TEXT NOT NULL,
+  "name"       TEXT NOT NULL,
+  "createdAt"  TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "updatedAt"  TIMESTAMP(3) NOT NULL,
+  CONSTRAINT "${snake}_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX "${snake}_tenantId_idx" ON "${snake}"("tenantId");
+`;
+}
+
+function renderMigrationReadme({
+  pascal,
+  snake,
+  kebab,
+}: {
+  pascal: string;
+  snake: string;
+  kebab: string;
+}): string {
+  return `# Migration: create entity ${pascal}
+
+Generated by \`toolctrl create entity ${kebab}\`.
+
+## How to apply
+
+1. Confirm the prisma model in \`prisma/_generated/${kebab}.prisma\` matches
+   your intended schema. Adjust columns / indexes / relations as needed.
+2. Append the model to \`prisma/schema.prisma\`.
+3. Run:
+
+   \`\`\`bash
+   pnpm prisma migrate dev --name create_entity_${snake}
+   \`\`\`
+
+4. Prisma will rewrite the SQL in \`migration.sql\` to match the schema
+   diff — this file is only a placeholder so the directory exists.
+`;
+}
+
+export const createEntityCommand = defineCommand({
+  meta: {
+    name: "entity",
+    description: "Scaffold a Prisma model + migration directory for a new entity.",
+  },
+  args: {
+    name: { type: "positional", required: true, description: "Entity name (will be PascalCased for the model)." },
+    "dry-run": {
+      type: "boolean",
+      required: false,
+      description: "Print the would-be writes without touching the filesystem.",
+    },
+  },
+  async run({ args }) {
+    const result = await generateEntity({ name: args.name, dryRun: args["dry-run"] === true });
+    consola.success(
+      `${result.dryRun ? "[dry-run] " : ""}Generated entity "${args.name}" — ${result.files.length} file(s).`,
+    );
+    for (const file of result.files) {
+      consola.info(`  ${result.dryRun ? "would write" : "wrote"} ${file.path}`);
+    }
+    for (const note of result.notes) {
+      consola.info(note);
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/create/index.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { createCommand } from "./index.js";
+
+async function resolveValue<T>(value: T | (() => T) | (() => Promise<T>)): Promise<T> {
+  if (typeof value === "function") {
+    return await (value as () => T | Promise<T>)();
+  }
+  return value;
+}
+
+describe("create command tree", () => {
+  it("exposes module / route / entity subcommands", async () => {
+    const meta = await resolveValue(createCommand.meta);
+    expect(meta).toMatchObject({ name: "create" });
+
+    const subs = await resolveValue(createCommand.subCommands);
+    expect(Object.keys(subs ?? {}).sort()).toEqual(["entity", "module", "route"]);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/create/index.ts

@@ -0,0 +1,16 @@
+import { defineCommand } from "citty";
+import { createEntityCommand } from "./entity.js";
+import { createModuleCommand } from "./module.js";
+import { createRouteCommand } from "./route.js";
+
+export const createCommand = defineCommand({
+  meta: {
+    name: "create",
+    description: "Scaffolding generators: create module / route / entity.",
+  },
+  subCommands: {
+    module: createModuleCommand,
+    route: createRouteCommand,
+    entity: createEntityCommand,
+  },
+});

hivegrid-cloud/packages/cli/src/commands/create/module.test.ts

@@ -0,0 +1,70 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { generateModule } from "./module.js";
+
+describe("create module generator", () => {
+  let tempRoot: string;
+
+  beforeEach(async () => {
+    tempRoot = await mkdtemp(path.join(tmpdir(), "toolctrl-cli-module-"));
+  });
+
+  afterEach(async () => {
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  it("emits db / service / component / route / test / readme files (dry-run)", async () => {
+    const result = await generateModule({ name: "inventory", repoRoot: tempRoot, dryRun: true });
+
+    const rels = result.files.map((f) => path.relative(tempRoot, f.path)).sort();
+    expect(rels).toEqual(
+      [
+        "apps/web/app/modules/inventory/README.md",
+        "apps/web/app/modules/inventory/components/InventoryList.tsx",
+        "apps/web/app/modules/inventory/db/inventory.db.server.ts",
+        "apps/web/app/modules/inventory/inventory.db.server.test.ts",
+        "apps/web/app/modules/inventory/services/InventoryService.ts",
+        "apps/web/app/routes/app.$tenant.inventory.tsx",
+      ].sort(),
+    );
+
+    expect(result.dryRun).toBe(true);
+  });
+
+  it("uses Route type import from ./+types/app.$tenant.<name>", async () => {
+    const result = await generateModule({ name: "inventory", repoRoot: tempRoot, dryRun: true });
+    const routeFile = result.files.find((f) => f.path.endsWith("app.$tenant.inventory.tsx"));
+    expect(routeFile?.contents).toContain('from "./+types/app.$tenant.inventory"');
+  });
+
+  it("respects --permission-prefix override", async () => {
+    const result = await generateModule({
+      name: "helpdesk",
+      repoRoot: tempRoot,
+      dryRun: true,
+      permissionPrefix: "support.tickets",
+    });
+    const readme = result.files.find((f) => f.path.endsWith("README.md"));
+    expect(readme?.contents).toContain("support.tickets.view");
+  });
+
+  it("normalises kebab/camel/pascal inputs identically", async () => {
+    const a = await generateModule({ name: "help-desk", repoRoot: tempRoot, dryRun: true });
+    const aRels = a.files.map((f) => path.relative(tempRoot, f.path)).sort();
+    expect(aRels).toContain("apps/web/app/modules/helpDesk/components/HelpDeskList.tsx");
+  });
+
+  it("refuses to overwrite existing files (no double-run)", async () => {
+    await generateModule({ name: "inventory", repoRoot: tempRoot, dryRun: false });
+    await expect(generateModule({ name: "inventory", repoRoot: tempRoot, dryRun: false })).rejects.toThrow(
+      /already exists/,
+    );
+  });
+
+  it("rejects invalid module names", async () => {
+    await expect(generateModule({ name: "1bad", repoRoot: tempRoot, dryRun: true })).rejects.toThrow(/Invalid/);
+    await expect(generateModule({ name: "", repoRoot: tempRoot, dryRun: true })).rejects.toThrow(/required/);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/create/module.ts

@@ -0,0 +1,302 @@
+/**
+ * `toolctrl create module <name>` — generate a new feature-module skeleton
+ * under `apps/web/app/modules/<name>/`.
+ *
+ * The generator emits the minimum set of files needed for a tenant-scoped
+ * CRUD module: a db-layer file, a service-layer file, a React-Router-v7
+ * tenant route, a List/Form component pair, a tiny utils file, and a vitest
+ * stub. Files are written to NEW paths only — re-running against an
+ * existing module name throws.
+ *
+ * Auto-wiring (sidebar entry, `routes.ts` patch, `seedPermissions`) is left
+ * for future iterations to keep the generator dependency-free; the README
+ * file produced by the generator lists the manual follow-up steps so the
+ * caller has a single checklist.
+ *
+ * Refs: docs/improvement-plan/08-mobile-cli-storybook-sdk/cli-scaffolding.md
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import path from "node:path";
+import {
+  camelCase,
+  createScaffoldResult,
+  kebabCase,
+  pascalCase,
+  resolveRepoRoot,
+  validateIdentifier,
+  writeScaffoldFile,
+  type ScaffoldResult,
+} from "../_lib/scaffold.js";
+
+export type GenerateModuleOptions = {
+  /** Raw user-provided name (e.g. "inventory" or "Help Desk"). */
+  name: string;
+  /** Repo root the module is written under. Defaults to `process.cwd()`. */
+  repoRoot?: string;
+  /** When `true` no files are written; the result.files array still records every would-be write. */
+  dryRun?: boolean;
+  /** Permission key prefix. Defaults to the kebab-cased name. */
+  permissionPrefix?: string;
+};
+
+export async function generateModule(options: GenerateModuleOptions): Promise<ScaffoldResult> {
+  const baseName = validateIdentifier(options.name, "module name");
+  const dryRun = options.dryRun ?? false;
+  const repoRoot = resolveRepoRoot(options.repoRoot);
+  const camel = camelCase(baseName);
+  const pascal = pascalCase(baseName);
+  const kebab = kebabCase(baseName);
+  const permissionPrefix = options.permissionPrefix?.trim() || kebab;
+
+  const moduleDir = path.join(repoRoot, "apps/web/app/modules", camel);
+  const result = createScaffoldResult(dryRun);
+
+  await writeScaffoldFile({
+    targetPath: path.join(moduleDir, "db", `${camel}.db.server.ts`),
+    contents: renderDbFile({ camel, pascal }),
+    dryRun,
+    result,
+  });
+
+  await writeScaffoldFile({
+    targetPath: path.join(moduleDir, "services", `${pascal}Service.ts`),
+    contents: renderServiceFile({ camel, pascal }),
+    dryRun,
+    result,
+  });
+
+  await writeScaffoldFile({
+    targetPath: path.join(moduleDir, "components", `${pascal}List.tsx`),
+    contents: renderListComponent({ camel, pascal }),
+    dryRun,
+    result,
+  });
+
+  await writeScaffoldFile({
+    targetPath: path.join(repoRoot, "apps/web/app/routes", `app.$tenant.${camel}.tsx`),
+    contents: renderRouteFile({ camel, pascal, permissionPrefix }),
+    dryRun,
+    result,
+  });
+
+  await writeScaffoldFile({
+    targetPath: path.join(moduleDir, `${camel}.db.server.test.ts`),
+    contents: renderDbTestFile({ camel, pascal }),
+    dryRun,
+    result,
+  });
+
+  await writeScaffoldFile({
+    targetPath: path.join(moduleDir, "README.md"),
+    contents: renderReadme({ pascal, kebab, camel, permissionPrefix }),
+    dryRun,
+    result,
+  });
+
+  result.notes.push(
+    `Next steps:`,
+    `  1. Add permission keys "${permissionPrefix}.view|create|update|delete" to packages/db/src/permissions-seed.server.ts`,
+    `  2. Register module in apps/web/app/sidebar (manual — sidebar layout differs per app)`,
+    `  3. Run \`pnpm typecheck\` to generate route types for app.$tenant.${camel}.tsx`,
+  );
+
+  return result;
+}
+
+function renderDbFile({ camel, pascal }: { camel: string; pascal: string }): string {
+  return `/**
+ * Tenant-scoped CRUD helpers for the ${pascal} module.
+ * Generated by toolctrl-cli — fill in the model field references after
+ * adding the Prisma model and running \`prisma migrate dev\`.
+ */
+import { db } from "~/utils/db.server";
+
+export type ${pascal}WhereScope = {
+  tenantId: string;
+};
+
+export async function list${pascal}(scope: ${pascal}WhereScope) {
+  // TODO: replace \`/* model */\` with the actual prisma model name.
+  return db.$queryRaw\`SELECT 1 WHERE \${scope.tenantId} = \${scope.tenantId}\`;
+}
+
+export async function get${pascal}ById(scope: ${pascal}WhereScope, id: string) {
+  void id;
+  void scope;
+  // TODO: \`return db.${camel}.findFirst({ where: { id, tenantId: scope.tenantId } });\`
+  return null;
+}
+`;
+}
+
+function renderServiceFile({ camel, pascal }: { camel: string; pascal: string }): string {
+  return `/**
+ * Service-layer for the ${pascal} module — wraps the db helpers with
+ * tenant-access guards so route handlers don't have to repeat the
+ * permission boilerplate.
+ */
+import { list${pascal}, get${pascal}ById } from "../db/${camel}.db.server";
+
+export type ${pascal}ServiceContext = {
+  tenantId: string;
+  userId: string;
+};
+
+export async function getAll${pascal}(ctx: ${pascal}ServiceContext) {
+  // TODO: call assertTenantHasAccess(ctx) when the helper is available.
+  return list${pascal}({ tenantId: ctx.tenantId });
+}
+
+export async function get${pascal}(ctx: ${pascal}ServiceContext, id: string) {
+  return get${pascal}ById({ tenantId: ctx.tenantId }, id);
+}
+`;
+}
+
+function renderListComponent({ pascal }: { camel: string; pascal: string }): string {
+  return `import type { ReactNode } from "react";
+
+export type ${pascal}ListProps = {
+  items: ReadonlyArray<{ id: string; name: string }>;
+  empty?: ReactNode;
+};
+
+export function ${pascal}List({ items, empty }: ${pascal}ListProps): ReactNode {
+  if (items.length === 0) {
+    return empty ?? <p>No ${pascal} yet.</p>;
+  }
+
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>{item.name}</li>
+      ))}
+    </ul>
+  );
+}
+`;
+}
+
+function renderRouteFile({
+  camel,
+  pascal,
+  permissionPrefix,
+}: {
+  camel: string;
+  pascal: string;
+  permissionPrefix: string;
+}): string {
+  return `import type { Route } from "./+types/app.$tenant.${camel}";
+import { getAll${pascal} } from "~/modules/${camel}/services/${pascal}Service";
+import { ${pascal}List } from "~/modules/${camel}/components/${pascal}List";
+
+/**
+ * Tenant route for the ${pascal} module.
+ * Generated by toolctrl-cli. Wire in \`requireAuth\` and the
+ * "${permissionPrefix}.view" permission guard once you connect the module
+ * to your auth helpers.
+ */
+export async function loader({ params }: Route.LoaderArgs) {
+  // TODO: call requireAuth(request) + assertPermission("${permissionPrefix}.view")
+  const tenantId = params.tenant ?? "";
+  const items = await getAll${pascal}({ tenantId, userId: "" });
+  return { items: (items as Array<{ id: string; name: string }>) ?? [] };
+}
+
+export default function ${pascal}Route({ loaderData }: Route.ComponentProps) {
+  return (
+    <div>
+      <h1>${pascal}</h1>
+      <${pascal}List items={loaderData.items} />
+    </div>
+  );
+}
+`;
+}
+
+function renderDbTestFile({ camel, pascal }: { camel: string; pascal: string }): string {
+  return `import { describe, expect, it } from "vitest";
+import { list${pascal} } from "./db/${camel}.db.server";
+
+describe("${pascal} db layer", () => {
+  it("returns a list (smoke test — implement once prisma model exists)", async () => {
+    const result = await list${pascal}({ tenantId: "test-tenant" });
+    expect(Array.isArray(result)).toBe(true);
+  });
+});
+`;
+}
+
+function renderReadme({
+  pascal,
+  kebab,
+  camel,
+  permissionPrefix,
+}: {
+  pascal: string;
+  kebab: string;
+  camel: string;
+  permissionPrefix: string;
+}): string {
+  return `# ${pascal} module
+
+Generated by \`toolctrl create module ${kebab}\`.
+
+## Layout
+
+- \`db/${camel}.db.server.ts\` — tenant-scoped CRUD helpers
+- \`services/${pascal}Service.ts\` — tenant-aware service layer
+- \`components/${pascal}List.tsx\` — list component
+- \`../../routes/app.$tenant.${camel}.tsx\` — tenant route
+
+## Manual follow-up
+
+1. Add the prisma model and run \`pnpm prisma migrate dev\`.
+2. Replace the \`TODO\` markers in \`db/${camel}.db.server.ts\` with the real
+   prisma model calls.
+3. Add permission keys to \`packages/db/src/permissions-seed.server.ts\`:
+   - \`${permissionPrefix}.view\`
+   - \`${permissionPrefix}.create\`
+   - \`${permissionPrefix}.update\`
+   - \`${permissionPrefix}.delete\`
+4. Register a sidebar entry in \`apps/web/app/sidebar\`.
+5. Run \`pnpm typecheck\` to generate the React Router v7 \`./+types/\` files.
+`;
+}
+
+export const createModuleCommand = defineCommand({
+  meta: {
+    name: "module",
+    description: "Scaffold a new feature-module under apps/web/app/modules/<name>.",
+  },
+  args: {
+    name: { type: "positional", required: true, description: "Module name (camel/kebab/pascal — normalised)." },
+    "permission-prefix": {
+      type: "string",
+      required: false,
+      description: "Permission key prefix (defaults to kebab-cased name).",
+    },
+    "dry-run": {
+      type: "boolean",
+      required: false,
+      description: "Print the would-be writes without touching the filesystem.",
+    },
+  },
+  async run({ args }) {
+    const result = await generateModule({
+      name: args.name,
+      permissionPrefix: args["permission-prefix"],
+      dryRun: args["dry-run"] === true,
+    });
+    consola.success(
+      `${result.dryRun ? "[dry-run] " : ""}Generated module "${args.name}" — ${result.files.length} file(s).`,
+    );
+    for (const file of result.files) {
+      consola.info(`  ${result.dryRun ? "would write" : "wrote"} ${file.path}`);
+    }
+    for (const note of result.notes) {
+      consola.info(note);
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/create/route.test.ts

@@ -0,0 +1,66 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { generateRoute } from "./route.js";
+
+describe("create route generator", () => {
+  let tempRoot: string;
+
+  beforeEach(async () => {
+    tempRoot = await mkdtemp(path.join(tmpdir(), "toolctrl-cli-route-"));
+  });
+
+  afterEach(async () => {
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  it("emits a .tsx + .test.tsx pair under apps/web/app/routes/", async () => {
+    const result = await generateRoute({ filename: "app.$tenant.foo", repoRoot: tempRoot, dryRun: true });
+    const rels = result.files.map((f) => path.relative(tempRoot, f.path)).sort();
+    expect(rels).toEqual([
+      "apps/web/app/routes/app.$tenant.foo.test.tsx",
+      "apps/web/app/routes/app.$tenant.foo.tsx",
+    ]);
+  });
+
+  it("uses Route type import from ./+types/<filename> (not relative path)", async () => {
+    const result = await generateRoute({ filename: "_index", repoRoot: tempRoot, dryRun: true });
+    const routeFile = result.files.find((f) => f.path.endsWith("_index.tsx") && !f.path.endsWith(".test.tsx"));
+    expect(routeFile?.contents).toContain('from "./+types/_index"');
+  });
+
+  it("contains loader, action, default component, and ErrorBoundary exports", async () => {
+    const result = await generateRoute({ filename: "foo", repoRoot: tempRoot, dryRun: true });
+    const routeFile = result.files.find((f) => f.path.endsWith("/foo.tsx"));
+    expect(routeFile?.contents).toMatch(/export async function loader/);
+    expect(routeFile?.contents).toMatch(/export async function action/);
+    expect(routeFile?.contents).toMatch(/export default function FooRoute/);
+    expect(routeFile?.contents).toMatch(/export function ErrorBoundary/);
+  });
+
+  it("omits :tenant param signature when --top-level is set", async () => {
+    const result = await generateRoute({ filename: "ping", repoRoot: tempRoot, dryRun: true, topLevel: true });
+    const routeFile = result.files.find((f) => f.path.endsWith("/ping.tsx"));
+    expect(routeFile?.contents).not.toContain("params");
+  });
+
+  it("rejects filenames that include an extension", async () => {
+    await expect(generateRoute({ filename: "foo.tsx", repoRoot: tempRoot, dryRun: true })).rejects.toThrow(
+      /extension/,
+    );
+  });
+
+  it("rejects invalid filename characters", async () => {
+    await expect(generateRoute({ filename: "foo bar", repoRoot: tempRoot, dryRun: true })).rejects.toThrow(
+      /Invalid/,
+    );
+  });
+
+  it("refuses to overwrite existing files", async () => {
+    await generateRoute({ filename: "foo", repoRoot: tempRoot, dryRun: false });
+    await expect(generateRoute({ filename: "foo", repoRoot: tempRoot, dryRun: false })).rejects.toThrow(
+      /already exists/,
+    );
+  });
+});

hivegrid-cloud/packages/cli/src/commands/create/route.ts

@@ -0,0 +1,198 @@
+/**
+ * `toolctrl create route <path>` — generate a single React-Router-v7
+ * route file with a sensible auth/CSRF default plus a co-located
+ * vitest stub.
+ *
+ * Why no AST patching of `apps/web/app/routes.ts`?
+ *   The web app uses the legacy v1 file-convention adapter
+ *   (`createRoutesFromFolders`), so dropping the file under
+ *   `apps/web/app/routes/` is enough — the framework picks it up
+ *   automatically. The generator therefore stays purely
+ *   file-creation, which keeps it idempotent and easy to test.
+ *
+ * Refs: docs/improvement-plan/08-mobile-cli-storybook-sdk/cli-scaffolding.md
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import path from "node:path";
+import {
+  createScaffoldResult,
+  pascalCase,
+  resolveRepoRoot,
+  writeScaffoldFile,
+  type ScaffoldResult,
+} from "../_lib/scaffold.js";
+
+export type GenerateRouteOptions = {
+  /** Filename (without .tsx) for the route — defines the routes.ts file slug. */
+  filename: string;
+  /** When `true`, scaffold a top-level route (no tenant param). */
+  topLevel?: boolean;
+  /** Repo root the route is written under. Defaults to `process.cwd()`. */
+  repoRoot?: string;
+  /** When `true` no files are written. */
+  dryRun?: boolean;
+};
+
+const FILENAME_PATTERN = /^[A-Za-z_][A-Za-z0-9._$-]*$/;
+
+export async function generateRoute(options: GenerateRouteOptions): Promise<ScaffoldResult> {
+  const filename = options.filename.trim();
+  if (!filename) throw new Error("filename is required.");
+  if (!FILENAME_PATTERN.test(filename)) {
+    throw new Error(
+      `Invalid route filename: "${filename}". Must start with a letter; allowed chars: letters, digits, '.', '$', '-', '_'.`,
+    );
+  }
+  if (filename.endsWith(".tsx") || filename.endsWith(".ts")) {
+    throw new Error(`Route filename must NOT include an extension: ${filename}`);
+  }
+
+  const dryRun = options.dryRun ?? false;
+  const repoRoot = resolveRepoRoot(options.repoRoot);
+  const topLevel = options.topLevel ?? false;
+
+  // Component name is derived from the last filename segment for predictability.
+  const lastSegment = filename.split(".").filter(Boolean).pop() ?? filename;
+  const baseSegment = lastSegment.replace(/^_+/, "") || lastSegment;
+  const componentName = `${pascalCase(baseSegment) || "Index"}Route`;
+
+  const routePath = path.join(repoRoot, "apps/web/app/routes", `${filename}.tsx`);
+  const testPath = path.join(repoRoot, "apps/web/app/routes", `${filename}.test.tsx`);
+
+  const result = createScaffoldResult(dryRun);
+
+  await writeScaffoldFile({
+    targetPath: routePath,
+    contents: renderRoute({ filename, componentName, topLevel }),
+    dryRun,
+    result,
+  });
+
+  await writeScaffoldFile({
+    targetPath: testPath,
+    contents: renderTest({ filename, componentName }),
+    dryRun,
+    result,
+  });
+
+  result.notes.push(
+    `Run \`pnpm typecheck\` to generate ./+types/${filename}.`,
+    topLevel ? "Top-level route — no tenant param." : "Tenant-scoped route — expects :tenant param.",
+  );
+
+  return result;
+}
+
+function renderRoute({
+  filename,
+  componentName,
+  topLevel,
+}: {
+  filename: string;
+  componentName: string;
+  topLevel: boolean;
+}): string {
+  return `import type { Route } from "./+types/${filename}";
+import { isRouteErrorResponse } from "react-router";
+
+/**
+ * Generated by \`toolctrl create route ${filename}\`.
+ * TODO: wire \`requireAuth(request)\` and \`validateCSRFToken(request)\`
+ * from your project's auth utility module.
+ */
+
+export async function loader({ request${topLevel ? "" : ", params"} }: Route.LoaderArgs) {
+  void request;
+  ${topLevel ? "" : "void params;\n  "}return { ok: true };
+}
+
+export async function action({ request${topLevel ? "" : ", params"} }: Route.ActionArgs) {
+  void request;
+  ${topLevel ? "" : "void params;\n  "}return { ok: true };
+}
+
+export default function ${componentName}({ loaderData }: Route.ComponentProps) {
+  return <div>${componentName}: {String(loaderData.ok)}</div>;
+}
+
+export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
+  if (isRouteErrorResponse(error)) {
+    return (
+      <div>
+        <h1>
+          {error.status} {error.statusText}
+        </h1>
+        <p>{String(error.data ?? "")}</p>
+      </div>
+    );
+  }
+  const message = error instanceof Error ? error.message : "Unknown error";
+  return (
+    <div>
+      <h1>Error</h1>
+      <p>{message}</p>
+    </div>
+  );
+}
+`;
+}
+
+function renderTest({ filename, componentName }: { filename: string; componentName: string }): string {
+  return `import { describe, expect, it } from "vitest";
+
+/**
+ * Smoke test for the generated route ${filename}.tsx.
+ * Replace with concrete loader/action tests once the route grows
+ * real behaviour.
+ */
+describe("${componentName}", () => {
+  it("module loads without throwing", async () => {
+    const mod = await import("./${filename}");
+    expect(typeof mod.loader).toBe("function");
+    expect(typeof mod.action).toBe("function");
+    expect(typeof mod.default).toBe("function");
+  });
+});
+`;
+}
+
+export const createRouteCommand = defineCommand({
+  meta: {
+    name: "route",
+    description: "Scaffold a React-Router-v7 route under apps/web/app/routes/<filename>.tsx.",
+  },
+  args: {
+    filename: {
+      type: "positional",
+      required: true,
+      description: "Route filename without extension (e.g. \"app.$tenant.foo\" or \"_index\").",
+    },
+    "top-level": {
+      type: "boolean",
+      required: false,
+      description: "Generate a top-level route (no :tenant param).",
+    },
+    "dry-run": {
+      type: "boolean",
+      required: false,
+      description: "Print the would-be writes without touching the filesystem.",
+    },
+  },
+  async run({ args }) {
+    const result = await generateRoute({
+      filename: args.filename,
+      topLevel: args["top-level"] === true,
+      dryRun: args["dry-run"] === true,
+    });
+    consola.success(
+      `${result.dryRun ? "[dry-run] " : ""}Generated route "${args.filename}" — ${result.files.length} file(s).`,
+    );
+    for (const file of result.files) {
+      consola.info(`  ${result.dryRun ? "would write" : "wrote"} ${file.path}`);
+    }
+    for (const note of result.notes) {
+      consola.info(note);
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/dsgvo/commands.test.ts

@@ -0,0 +1,190 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+type DsgvoCliMocks = {
+  db: {
+    user: {
+      findUnique: ReturnType<typeof vi.fn>;
+      update: ReturnType<typeof vi.fn>;
+    };
+  };
+  createAuditEvent: ReturnType<typeof vi.fn>;
+};
+
+function getDsgvoCliMocks(): DsgvoCliMocks {
+  const global = globalThis as typeof globalThis & { __dsgvoCliMocks__?: DsgvoCliMocks };
+  global.__dsgvoCliMocks__ ??= {
+    db: {
+      user: {
+        findUnique: vi.fn(),
+        update: vi.fn(),
+      },
+    },
+    createAuditEvent: vi.fn(),
+  };
+  return global.__dsgvoCliMocks__;
+}
+
+vi.mock("@toolctrl/db/client.server", () => ({
+  getDbClient: () => getDsgvoCliMocks().db,
+}));
+vi.mock("@toolctrl/db/audit-events.server", () => ({
+  createAuditEvent: getDsgvoCliMocks().createAuditEvent,
+}));
+vi.mock("consola", () => ({
+  default: {
+    error: vi.fn(),
+    success: vi.fn(),
+    warn: vi.fn(),
+  },
+}));
+
+import consola from "consola";
+import { dsgvoDeleteCommand } from "./delete.js";
+import { dsgvoReactivateCommand } from "./reactivate.js";
+
+const mocks = getDsgvoCliMocks();
+const consoleMock = vi.mocked(consola);
+const now = new Date("2026-05-25T12:00:00.000Z");
+
+describe("dsgvo CLI commands", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(now);
+    vi.clearAllMocks();
+    process.exitCode = undefined;
+    mocks.db.user.update.mockResolvedValue({ id: "user_1" });
+    mocks.createAuditEvent.mockResolvedValue({ id: "audit_1" });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    process.exitCode = undefined;
+  });
+
+  it("rejects immediate deletion without a sufficiently descriptive reason before DB writes", async () => {
+    await dsgvoDeleteCommand.run?.({
+      args: { user: "user_1", immediate: true, reason: "short" },
+    } as never);
+
+    expect(consoleMock.error).toHaveBeenCalledWith("--reason is required (>=10 chars) when --immediate is used.");
+    expect(process.exitCode).toBe(2);
+    expect(mocks.db.user.update).not.toHaveBeenCalled();
+    expect(mocks.createAuditEvent).not.toHaveBeenCalled();
+  });
+
+  it("schedules deletion with grace period, tenant, actor, and audit metadata", async () => {
+    await dsgvoDeleteCommand.run?.({
+      args: { user: "user_1", tenant: "tenant_1", actor: "admin_1" },
+    } as never);
+
+    const scheduledDeletionAt = new Date("2026-06-24T12:00:00.000Z");
+    expect(mocks.db.user.update).toHaveBeenCalledWith({
+      where: { id: "user_1" },
+      data: {
+        pendingDeletion: true,
+        deletionRequestedAt: now,
+        scheduledDeletionAt,
+        deletionRequestId: expect.any(String),
+      },
+    });
+    const requestId = mocks.db.user.update.mock.calls[0]?.[0].data.deletionRequestId;
+    expect(mocks.createAuditEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tenantId: "tenant_1",
+        actorId: "admin_1",
+        action: "REQUEST_USER_DELETION",
+        targetId: "user_1",
+        metadata: expect.objectContaining({
+          requestId,
+          immediate: false,
+          reason: null,
+          scheduledDeletionAt: scheduledDeletionAt.toISOString(),
+        }),
+      }),
+    );
+    expect(consoleMock.success).toHaveBeenCalledWith(
+      `User user_1 scheduled for deletion on ${scheduledDeletionAt.toISOString()}. requestId=${requestId}`,
+    );
+  });
+
+  it("marks immediate deletion using default actor and nullable tenant audit fields", async () => {
+    await dsgvoDeleteCommand.run?.({
+      args: { user: "user_1", immediate: true, reason: "legal erasure request" },
+    } as never);
+
+    expect(mocks.db.user.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          scheduledDeletionAt: now,
+        }),
+      }),
+    );
+    expect(mocks.createAuditEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tenantId: null,
+        actorId: "cli-operator",
+        metadata: expect.objectContaining({
+          immediate: true,
+          reason: "legal erasure request",
+          scheduledDeletionAt: now.toISOString(),
+        }),
+      }),
+    );
+    expect(consoleMock.success).toHaveBeenCalledWith(
+      expect.stringMatching(/^User user_1 marked for immediate deletion \(next cron pass\)\. requestId=.+$/u),
+    );
+  });
+
+  it("reports missing or non-pending users during reactivation without writing updates", async () => {
+    mocks.db.user.findUnique.mockResolvedValueOnce(null);
+
+    await dsgvoReactivateCommand.run?.({ args: { user: "missing" } } as never);
+
+    expect(consoleMock.error).toHaveBeenCalledWith("User missing not found.");
+    expect(process.exitCode).toBe(1);
+    expect(mocks.db.user.update).not.toHaveBeenCalled();
+
+    process.exitCode = undefined;
+    mocks.db.user.findUnique.mockResolvedValueOnce({ pendingDeletion: false });
+
+    await dsgvoReactivateCommand.run?.({ args: { user: "user_1" } } as never);
+
+    expect(consoleMock.warn).toHaveBeenCalledWith("User user_1 is not pendingDeletion; nothing to do.");
+    expect(process.exitCode).toBe(1);
+    expect(mocks.db.user.update).not.toHaveBeenCalled();
+  });
+
+  it("reactivates a pending user and records cancellation audit metadata", async () => {
+    mocks.db.user.findUnique.mockResolvedValueOnce({ pendingDeletion: true });
+
+    await dsgvoReactivateCommand.run?.({
+      args: { user: "user_1", tenant: "tenant_1", actor: "admin_1" },
+    } as never);
+
+    expect(mocks.db.user.findUnique).toHaveBeenCalledWith({
+      where: { id: "user_1" },
+      select: { pendingDeletion: true },
+    });
+    expect(mocks.db.user.update).toHaveBeenCalledWith({
+      where: { id: "user_1" },
+      data: {
+        pendingDeletion: false,
+        deletionRequestedAt: null,
+        scheduledDeletionAt: null,
+        deletionRequestId: null,
+      },
+    });
+    expect(mocks.createAuditEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tenantId: "tenant_1",
+        actorId: "admin_1",
+        action: "CANCEL_USER_DELETION",
+        targetId: "user_1",
+        metadata: { requestId: expect.any(String), intent: "reactivate", source: "cli" },
+      }),
+    );
+    expect(consoleMock.success).toHaveBeenCalledWith(
+      expect.stringMatching(/^User user_1 reactivated\. requestId=.+$/u),
+    );
+  });
+});

hivegrid-cloud/packages/cli/src/commands/dsgvo/delete.ts

@@ -0,0 +1,88 @@
+/**
+ * `dsgvo delete --user <id> [--tenant <id>] [--immediate] [--reason <text>]`
+ *
+ * Schedule a user for deletion. Default behaviour mirrors the
+ * self-service flow: flips User.pendingDeletion=true with
+ * scheduledDeletionAt = now + GRACE days (default 30), and the
+ * grace-period cron picks it up later.
+ *
+ * With `--immediate` the scheduledDeletionAt is set to *now* so the
+ * very next cron pass dispatches the cascade. We deliberately do not
+ * synchronously call runDsgvoDeletion from the CLI — that would
+ * bypass the worker's audit + per-table-strategy invariants.
+ *
+ * `--reason` is required when --immediate to satisfy the same
+ * audit-evidence bar as the admin UI override.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { randomUUID } from "node:crypto";
+
+const DSGVO_GRACE_PERIOD_DAYS = Number(process.env.DSGVO_GRACE_PERIOD_DAYS ?? "30") || 30;
+
+export const dsgvoDeleteCommand = defineCommand({
+  meta: { name: "delete", description: "Schedule a user for deletion (grace-period by default)." },
+  args: {
+    user: { type: "string", required: true, description: "Target User.id." },
+    tenant: { type: "string", required: false, description: "Tenant id stamped on the audit row." },
+    actor: { type: "string", required: false, description: "Operator id stamped on the audit row." },
+    immediate: { type: "boolean", required: false, description: "Skip grace; the next cron pass deletes the user." },
+    reason: { type: "string", required: false, description: "Operator reason (required with --immediate)." },
+  },
+  async run({ args }) {
+    const userId = String(args.user);
+    const tenantId = args.tenant ? String(args.tenant) : null;
+    const actorId = args.actor ? String(args.actor) : "cli-operator";
+    const immediate = Boolean(args.immediate);
+    const reason = args.reason ? String(args.reason) : null;
+    if (immediate && (!reason || reason.length < 10)) {
+      consola.error("--reason is required (>=10 chars) when --immediate is used.");
+      process.exitCode = 2;
+      return;
+    }
+    const now = new Date();
+    const scheduledDeletionAt = immediate
+      ? now
+      : new Date(now.getTime() + DSGVO_GRACE_PERIOD_DAYS * 24 * 60 * 60 * 1000);
+    const requestId = randomUUID();
+
+    const [{ getDbClient }, { createAuditEvent }] = await Promise.all([
+      import("@toolctrl/db/client.server"),
+      import("@toolctrl/db/audit-events.server"),
+    ]);
+    const prisma = getDbClient();
+    await prisma.user.update({
+      where: { id: userId },
+      data: {
+        pendingDeletion: true,
+        deletionRequestedAt: now,
+        scheduledDeletionAt,
+        deletionRequestId: requestId,
+      },
+    });
+    await createAuditEvent({
+      tenantId,
+      actorId,
+      actorType: "admin",
+      action: "REQUEST_USER_DELETION",
+      targetType: "User",
+      targetId: userId,
+      regulatoryScope: ["gdpr"],
+      dataSensitivity: "pii",
+      outcome: "success",
+      metadata: {
+        requestId,
+        intent: "delete",
+        source: "cli",
+        immediate,
+        reason,
+        scheduledDeletionAt: scheduledDeletionAt.toISOString(),
+      },
+    });
+    consola.success(
+      immediate
+        ? `User ${userId} marked for immediate deletion (next cron pass). requestId=${requestId}`
+        : `User ${userId} scheduled for deletion on ${scheduledDeletionAt.toISOString()}. requestId=${requestId}`,
+    );
+  },
+});

hivegrid-cloud/packages/cli/src/commands/dsgvo/export.ts

@@ -0,0 +1,41 @@
+/**
+ * `dsgvo export --user <userId> [--tenant <tenantId>]` — write a
+ * REQUEST_PERSONAL_DATA_EXPORT AuditEvent for the user, mirroring the
+ * self-service path. The worker picks up the request out-of-band and
+ * emails the user the signed download URL. The CLI command is the
+ * operator-equivalent escape hatch for tickets the user could not
+ * complete via the web UI.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { randomUUID } from "node:crypto";
+
+export const dsgvoExportCommand = defineCommand({
+  meta: { name: "export", description: "Trigger a personal-data export for a user." },
+  args: {
+    user: { type: "string", required: true, description: "Target User.id." },
+    tenant: { type: "string", required: false, description: "Tenant id stamped on the audit row." },
+    actor: { type: "string", required: false, description: "Operator id stamped on the audit row." },
+  },
+  async run({ args }) {
+    const userId = String(args.user);
+    const tenantId = args.tenant ? String(args.tenant) : null;
+    const actorId = args.actor ? String(args.actor) : "cli-operator";
+    const requestId = randomUUID();
+
+    const { createAuditEvent } = await import("@toolctrl/db/audit-events.server");
+    await createAuditEvent({
+      tenantId,
+      actorId,
+      actorType: "admin",
+      action: "REQUEST_PERSONAL_DATA_EXPORT",
+      targetType: "User",
+      targetId: userId,
+      regulatoryScope: ["gdpr"],
+      dataSensitivity: "pii",
+      outcome: "success",
+      metadata: { requestId, intent: "export", source: "cli" },
+    });
+    consola.success(`Personal-data export queued for user=${userId} requestId=${requestId}`);
+  },
+});

hivegrid-cloud/packages/cli/src/commands/dsgvo/index.ts

@@ -0,0 +1,36 @@
+/**
+ * `dsgvo` — operator commands for the DSGVO/GDPR bulk-operations toolkit
+ * (Phase 10 #68).
+ *
+ * Subcommands:
+ *   export      Trigger a personal-data export for a user (Art. 15 / 20).
+ *   delete      Schedule a user for deletion (Art. 17). Respects the
+ *               configured grace period unless --immediate is passed.
+ *   verify      Run the cross-table verifier-pass for a user (post-cascade
+ *               sanity check that no straggler rows remain).
+ *   reactivate  Cancel a pending deletion before the grace window elapses.
+ *
+ * All commands are thin shims around the existing workers /
+ * audit-event-driven dispatch path — the CLI just records the request
+ * and prints the resulting job/audit ids. The actual cascade always
+ * runs in the worker so the audit + per-table-strategy invariants stay
+ * in one code path.
+ */
+import { defineCommand } from "citty";
+import { dsgvoExportCommand } from "./export.js";
+import { dsgvoDeleteCommand } from "./delete.js";
+import { dsgvoVerifyCommand } from "./verify.js";
+import { dsgvoReactivateCommand } from "./reactivate.js";
+
+export const dsgvoCommand = defineCommand({
+  meta: {
+    name: "dsgvo",
+    description: "DSGVO/GDPR operator helpers (export, delete, verify, reactivate).",
+  },
+  subCommands: {
+    export: dsgvoExportCommand,
+    delete: dsgvoDeleteCommand,
+    verify: dsgvoVerifyCommand,
+    reactivate: dsgvoReactivateCommand,
+  },
+});

hivegrid-cloud/packages/cli/src/commands/dsgvo/reactivate.ts

@@ -0,0 +1,67 @@
+/**
+ * `dsgvo reactivate --user <id>` — cancel a pending deletion. Clears
+ * User.pendingDeletion + scheduledDeletionAt + deletionRequestedAt +
+ * deletionRequestId and writes a CANCEL_USER_DELETION audit row.
+ *
+ * Fails (exit 1) if the user is not currently pendingDeletion=true.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { randomUUID } from "node:crypto";
+
+export const dsgvoReactivateCommand = defineCommand({
+  meta: { name: "reactivate", description: "Cancel a pending user deletion." },
+  args: {
+    user: { type: "string", required: true, description: "Target User.id." },
+    tenant: { type: "string", required: false, description: "Tenant id stamped on the audit row." },
+    actor: { type: "string", required: false, description: "Operator id stamped on the audit row." },
+  },
+  async run({ args }) {
+    const userId = String(args.user);
+    const tenantId = args.tenant ? String(args.tenant) : null;
+    const actorId = args.actor ? String(args.actor) : "cli-operator";
+    const requestId = randomUUID();
+
+    const [{ getDbClient }, { createAuditEvent }] = await Promise.all([
+      import("@toolctrl/db/client.server"),
+      import("@toolctrl/db/audit-events.server"),
+    ]);
+    const prisma = getDbClient();
+    const existing = await prisma.user.findUnique({
+      where: { id: userId },
+      select: { pendingDeletion: true },
+    });
+    if (!existing) {
+      consola.error(`User ${userId} not found.`);
+      process.exitCode = 1;
+      return;
+    }
+    if (!existing.pendingDeletion) {
+      consola.warn(`User ${userId} is not pendingDeletion; nothing to do.`);
+      process.exitCode = 1;
+      return;
+    }
+    await prisma.user.update({
+      where: { id: userId },
+      data: {
+        pendingDeletion: false,
+        deletionRequestedAt: null,
+        scheduledDeletionAt: null,
+        deletionRequestId: null,
+      },
+    });
+    await createAuditEvent({
+      tenantId,
+      actorId,
+      actorType: "admin",
+      action: "CANCEL_USER_DELETION",
+      targetType: "User",
+      targetId: userId,
+      regulatoryScope: ["gdpr"],
+      dataSensitivity: "pii",
+      outcome: "success",
+      metadata: { requestId, intent: "reactivate", source: "cli" },
+    });
+    consola.success(`User ${userId} reactivated. requestId=${requestId}`);
+  },
+});

hivegrid-cloud/packages/cli/src/commands/dsgvo/verify.ts

@@ -0,0 +1,43 @@
+/**
+ * `dsgvo verify --user <id>` — run the cross-table verifier-pass for a
+ * user after a deletion-cascade, printing any straggler rows that still
+ * reference the user. Useful when an operator wants a quick "are we
+ * sure they're gone?" check without waiting for the scheduled verifier
+ * worker run (~1h after the cascade).
+ *
+ * The actual scan logic lives in the worker (apps/worker/src/jobs/
+ * dsgvo-verify.ts). The CLI just records the request as an AuditEvent
+ * with action=VERIFY_USER_DELETION so the worker can pick it up.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { randomUUID } from "node:crypto";
+
+export const dsgvoVerifyCommand = defineCommand({
+  meta: { name: "verify", description: "Schedule a verifier-pass for a deleted user." },
+  args: {
+    user: { type: "string", required: true, description: "Target User.id (already deleted/pseudonymized)." },
+    tenant: { type: "string", required: false, description: "Tenant id stamped on the audit row." },
+    actor: { type: "string", required: false, description: "Operator id stamped on the audit row." },
+  },
+  async run({ args }) {
+    const userId = String(args.user);
+    const tenantId = args.tenant ? String(args.tenant) : null;
+    const actorId = args.actor ? String(args.actor) : "cli-operator";
+    const requestId = randomUUID();
+    const { createAuditEvent } = await import("@toolctrl/db/audit-events.server");
+    await createAuditEvent({
+      tenantId,
+      actorId,
+      actorType: "admin",
+      action: "VERIFY_USER_DELETION",
+      targetType: "User",
+      targetId: userId,
+      regulatoryScope: ["gdpr"],
+      dataSensitivity: "pii",
+      outcome: "success",
+      metadata: { requestId, intent: "verify", source: "cli" },
+    });
+    consola.success(`Verifier-pass queued for user=${userId} requestId=${requestId}`);
+  },
+});

hivegrid-cloud/packages/cli/src/commands/feature-flags/index.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+import { featureFlagsCommand } from "./index.js";
+
+describe("featureFlagsCommand", () => {
+  it("exposes the expected sub-commands", () => {
+    expect(featureFlagsCommand.subCommands).toBeDefined();
+    const keys = Object.keys(featureFlagsCommand.subCommands ?? {});
+    expect(keys.sort()).toEqual(["disable", "enable", "list", "set-rules"]);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/feature-flags/index.ts

@@ -0,0 +1,17 @@
+import { defineCommand } from "citty";
+import { featureFlagsListCommand } from "./list.js";
+import { featureFlagsDisableCommand, featureFlagsEnableCommand } from "./toggle.js";
+import { featureFlagsSetRulesCommand } from "./set-rules.js";
+
+export const featureFlagsCommand = defineCommand({
+  meta: {
+    name: "feature-flags",
+    description: "Feature-flag operator commands (list, enable, disable, set-rules).",
+  },
+  subCommands: {
+    list: featureFlagsListCommand,
+    enable: featureFlagsEnableCommand,
+    disable: featureFlagsDisableCommand,
+    "set-rules": featureFlagsSetRulesCommand,
+  },
+});

hivegrid-cloud/packages/cli/src/commands/feature-flags/invalidate.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const publishMock = vi.fn();
+vi.mock("@toolctrl/feature-flags", () => ({
+  publishFeatureFlagInvalidationOnce: (...args: unknown[]) => publishMock(...args),
+}));
+
+import { broadcastFlagInvalidation } from "./invalidate.js";
+
+describe("broadcastFlagInvalidation", () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    publishMock.mockReset();
+    publishMock.mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it("forwards the flag name and defaults the sharedStoreNamespace to 'web'", async () => {
+    delete process.env.FEATURE_FLAGS_PUBLISH_NAMESPACE;
+    await broadcastFlagInvalidation("billing.beta");
+
+    expect(publishMock).toHaveBeenCalledTimes(1);
+    expect(publishMock).toHaveBeenCalledWith({
+      flagName: "billing.beta",
+      sharedStoreNamespace: "web",
+    });
+  });
+
+  it("uses FEATURE_FLAGS_PUBLISH_NAMESPACE when set", async () => {
+    process.env.FEATURE_FLAGS_PUBLISH_NAMESPACE = "platform";
+    await broadcastFlagInvalidation("billing.beta");
+
+    expect(publishMock).toHaveBeenCalledWith({
+      flagName: "billing.beta",
+      sharedStoreNamespace: "platform",
+    });
+  });
+
+  it("falls back to 'web' when FEATURE_FLAGS_PUBLISH_NAMESPACE is blank", async () => {
+    process.env.FEATURE_FLAGS_PUBLISH_NAMESPACE = "   ";
+    await broadcastFlagInvalidation("billing.beta");
+
+    expect(publishMock).toHaveBeenCalledWith({
+      flagName: "billing.beta",
+      sharedStoreNamespace: "web",
+    });
+  });
+
+  it("swallows publisher errors so the calling command still exits cleanly", async () => {
+    publishMock.mockRejectedValueOnce(new Error("redis down"));
+    await expect(broadcastFlagInvalidation("billing.beta")).resolves.toBeUndefined();
+    expect(publishMock).toHaveBeenCalledTimes(1);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/feature-flags/invalidate.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared one-shot invalidation publisher for the operator CLI's
+ * feature-flag mutators (`enable`, `disable`, `set-rules`). Reaches the
+ * subscribing web replicas via the shared-store pub/sub channel
+ * (#39 cross-process publisher) so an operator does not need to issue
+ * a separate cache-clear after flipping a flag from the terminal.
+ *
+ * Failure mode: any publish error is logged at warn level and
+ * swallowed — the DB mutation already succeeded, and the L1 TTL on the
+ * web side (60s default) is the safety net.
+ */
+import consola from "consola";
+import { publishFeatureFlagInvalidationOnce } from "@toolctrl/feature-flags";
+
+const DEFAULT_PUBLISH_NAMESPACE = "web";
+
+function resolvePublishNamespace(): string {
+  const fromEnv = process.env.FEATURE_FLAGS_PUBLISH_NAMESPACE?.trim();
+  return fromEnv && fromEnv.length > 0 ? fromEnv : DEFAULT_PUBLISH_NAMESPACE;
+}
+
+export async function broadcastFlagInvalidation(flagName: string): Promise<void> {
+  try {
+    await publishFeatureFlagInvalidationOnce({
+      flagName,
+      sharedStoreNamespace: resolvePublishNamespace(),
+    });
+  } catch (err: unknown) {
+    consola.warn(
+      `feature-flag cache invalidation publish failed for "${flagName}":`,
+      err instanceof Error ? err.message : err,
+    );
+  }
+}

hivegrid-cloud/packages/cli/src/commands/feature-flags/list.test.ts

@@ -0,0 +1,111 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+type FeatureFlagListRecord = {
+  id: string;
+  name: string;
+  enabled: boolean;
+  description: string | null;
+  rules: unknown;
+  parentFlagId: string | null;
+  enabledFrom: Date | null;
+  enabledUntil: Date | null;
+};
+
+const dbMock = {
+  featureFlag: {
+    findMany: vi.fn<() => Promise<FeatureFlagListRecord[]>>(),
+  },
+};
+
+vi.mock("@toolctrl/db/client.server", () => ({
+  getDbClient: () => dbMock,
+}));
+vi.mock("consola", () => ({
+  default: {
+    info: vi.fn(),
+    log: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+
+import consola from "consola";
+import { featureFlagsListCommand } from "./list.js";
+
+const consoleMock = vi.mocked(consola);
+
+describe("feature flag list command", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    dbMock.featureFlag.findMany.mockResolvedValue([]);
+  });
+
+  it("lists all flags with state, rule, and parent tags", async () => {
+    dbMock.featureFlag.findMany.mockResolvedValueOnce([
+      {
+        id: "flag_1",
+        name: "billing.beta",
+        enabled: true,
+        description: "Billing beta",
+        rules: { all: [] },
+        parentFlagId: "parent_1",
+        enabledFrom: null,
+        enabledUntil: null,
+      },
+      {
+        id: "flag_2",
+        name: "support.inbox",
+        enabled: false,
+        description: null,
+        rules: null,
+        parentFlagId: null,
+        enabledFrom: null,
+        enabledUntil: null,
+      },
+    ]);
+
+    await featureFlagsListCommand.run?.({ args: {} } as never);
+
+    expect(dbMock.featureFlag.findMany).toHaveBeenCalledWith({
+      where: {},
+      orderBy: { name: "asc" },
+      select: {
+        id: true,
+        name: true,
+        enabled: true,
+        description: true,
+        rules: true,
+        parentFlagId: true,
+        enabledFrom: true,
+        enabledUntil: true,
+      },
+    });
+    expect(consoleMock.log).toHaveBeenCalledWith(expect.stringContaining("ON   billing.beta"));
+    expect(consoleMock.log).toHaveBeenCalledWith(expect.stringContaining("rules      parent=parent_1"));
+    expect(consoleMock.log).toHaveBeenCalledWith(expect.stringContaining("OFF  support.inbox"));
+    expect(consoleMock.log).toHaveBeenCalledWith(expect.stringContaining("no-rules   no-parent"));
+    expect(consoleMock.success).toHaveBeenCalledWith("2 flags listed.");
+  });
+
+  it("filters by disabled state and reports an empty result", async () => {
+    await featureFlagsListCommand.run?.({ args: { enabled: "false" } } as never);
+
+    expect(dbMock.featureFlag.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { enabled: false },
+      }),
+    );
+    expect(consoleMock.info).toHaveBeenCalledWith("No feature flags found.");
+    expect(consoleMock.log).not.toHaveBeenCalled();
+    expect(consoleMock.success).not.toHaveBeenCalled();
+  });
+
+  it("treats non-true enabled filters as disabled filters", async () => {
+    await featureFlagsListCommand.run?.({ args: { enabled: "0" } } as never);
+
+    expect(dbMock.featureFlag.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { enabled: false },
+      }),
+    );
+  });
+});

hivegrid-cloud/packages/cli/src/commands/feature-flags/list.ts

@@ -0,0 +1,50 @@
+/**
+ * `feature-flags list` — print every flag with its enabled-state,
+ * rule-count and parent dependency.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+
+export const featureFlagsListCommand = defineCommand({
+  meta: {
+    name: "list",
+    description: "List every feature flag with current state.",
+  },
+  args: {
+    enabled: {
+      type: "string",
+      description: "Filter: 'true' for enabled only, 'false' for disabled only.",
+    },
+  },
+  async run({ args }) {
+    const filter = args.enabled === undefined ? undefined : String(args.enabled) === "true";
+    const { getDbClient } = await import("@toolctrl/db/client.server");
+    const prisma = getDbClient();
+    const where = filter === undefined ? {} : { enabled: filter };
+    const flags = await prisma.featureFlag.findMany({
+      where,
+      orderBy: { name: "asc" },
+      select: {
+        id: true,
+        name: true,
+        enabled: true,
+        description: true,
+        rules: true,
+        parentFlagId: true,
+        enabledFrom: true,
+        enabledUntil: true,
+      },
+    });
+    if (flags.length === 0) {
+      consola.info("No feature flags found.");
+      return;
+    }
+    for (const flag of flags) {
+      const ruleTag = flag.rules ? "rules" : "no-rules";
+      const depTag = flag.parentFlagId ? `parent=${flag.parentFlagId}` : "no-parent";
+      const stateTag = flag.enabled ? "ON" : "OFF";
+      consola.log(`${stateTag.padEnd(3)}  ${flag.name.padEnd(40)} ${ruleTag.padEnd(10)} ${depTag}`);
+    }
+    consola.success(`${flags.length} flags listed.`);
+  },
+});

hivegrid-cloud/packages/cli/src/commands/feature-flags/set-rules.test.ts

@@ -0,0 +1,139 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+type FeatureFlagRecord = {
+  id: string;
+  name: string;
+  rules: unknown;
+};
+
+const dbMock = {
+  featureFlag: {
+    findFirst: vi.fn<() => Promise<FeatureFlagRecord | null>>(),
+    update: vi.fn(),
+  },
+  featureFlagAudit: {
+    create: vi.fn(),
+  },
+  $transaction: vi.fn(),
+};
+const broadcastFlagInvalidationMock = vi.fn();
+const evaluateRuleMock = vi.fn();
+
+vi.mock("@toolctrl/db/client.server", () => ({
+  getDbClient: () => dbMock,
+}));
+vi.mock("@toolctrl/feature-flags", () => ({
+  evaluateRule: (...args: unknown[]) => evaluateRuleMock(...args),
+}));
+vi.mock("consola", () => ({
+  default: {
+    error: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+vi.mock("./invalidate.js", () => ({
+  broadcastFlagInvalidation: (...args: unknown[]) => broadcastFlagInvalidationMock(...args),
+}));
+
+import consola from "consola";
+import { featureFlagsSetRulesCommand } from "./set-rules.js";
+
+const consoleMock = vi.mocked(consola);
+let tempDir: string;
+
+function writeRulesFile(contents: string): string {
+  const path = join(tempDir, `rules-${crypto.randomUUID()}.json`);
+  writeFileSync(path, contents, "utf-8");
+  return path;
+}
+
+describe("feature flag set-rules command", () => {
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "toolctrl-cli-flags-"));
+    vi.clearAllMocks();
+    process.exitCode = undefined;
+    dbMock.$transaction.mockResolvedValue([]);
+    broadcastFlagInvalidationMock.mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { force: true, recursive: true });
+  });
+
+  it("rejects invalid JSON before opening a DB client", async () => {
+    const file = writeRulesFile("{");
+
+    await featureFlagsSetRulesCommand.run?.({ args: { name: "billing.beta", file } } as never);
+
+    expect(consoleMock.error).toHaveBeenCalledWith("Failed to parse rules JSON:", expect.any(SyntaxError));
+    expect(process.exitCode).toBe(1);
+    expect(evaluateRuleMock).not.toHaveBeenCalled();
+    expect(dbMock.featureFlag.findFirst).not.toHaveBeenCalled();
+  });
+
+  it("rejects rule trees that do not evaluate cleanly", async () => {
+    const file = writeRulesFile('{"all":[{"attribute":"plan","operator":"eq","value":"pro"}]}');
+    const error = new Error("bad operator");
+    evaluateRuleMock.mockImplementationOnce(() => {
+      throw error;
+    });
+
+    await featureFlagsSetRulesCommand.run?.({ args: { name: "billing.beta", file } } as never);
+
+    expect(evaluateRuleMock).toHaveBeenCalledWith(
+      { all: [{ attribute: "plan", operator: "eq", value: "pro" }] },
+      { flagName: "billing.beta", tenantId: "probe", userId: "probe" }
+    );
+    expect(consoleMock.error).toHaveBeenCalledWith("Rule tree did not evaluate cleanly:", error);
+    expect(process.exitCode).toBe(1);
+    expect(dbMock.featureFlag.findFirst).not.toHaveBeenCalled();
+  });
+
+  it("reports missing flags after validating the replacement rules", async () => {
+    const file = writeRulesFile('{"all":[]}');
+    dbMock.featureFlag.findFirst.mockResolvedValueOnce(null);
+
+    await featureFlagsSetRulesCommand.run?.({ args: { name: "billing.beta", file } } as never);
+
+    expect(dbMock.featureFlag.findFirst).toHaveBeenCalledWith({ where: { name: "billing.beta" } });
+    expect(consoleMock.error).toHaveBeenCalledWith('Flag "billing.beta" not found.');
+    expect(process.exitCode).toBe(1);
+    expect(dbMock.$transaction).not.toHaveBeenCalled();
+    expect(broadcastFlagInvalidationMock).not.toHaveBeenCalled();
+  });
+
+  it("treats blank rule files as clearing rules and skips rule evaluation", async () => {
+    const file = writeRulesFile("   \n");
+    dbMock.featureFlag.findFirst.mockResolvedValueOnce({
+      id: "flag_1",
+      name: "billing.beta",
+      rules: { all: [] },
+    });
+
+    await featureFlagsSetRulesCommand.run?.({ args: { name: "billing.beta", file } } as never);
+
+    expect(evaluateRuleMock).not.toHaveBeenCalled();
+    expect(dbMock.featureFlag.update).toHaveBeenCalledWith({
+      where: { id: "flag_1" },
+      data: { rules: null },
+    });
+    expect(dbMock.featureFlagAudit.create).toHaveBeenCalledWith({
+      data: {
+        flagId: "flag_1",
+        actorUserId: null,
+        action: "update",
+        oldValue: { rules: { all: [] } },
+        newValue: { rules: null },
+      },
+    });
+    expect(dbMock.$transaction).toHaveBeenCalledWith([
+      dbMock.featureFlag.update.mock.results[0]?.value,
+      dbMock.featureFlagAudit.create.mock.results[0]?.value,
+    ]);
+    expect(broadcastFlagInvalidationMock).toHaveBeenCalledWith("billing.beta");
+    expect(consoleMock.success).toHaveBeenCalledWith('Rules for "billing.beta" updated.');
+  });
+});

hivegrid-cloud/packages/cli/src/commands/feature-flags/set-rules.ts

@@ -0,0 +1,101 @@
+/**
+ * `feature-flags set-rules` — replace a flag's targeting-rule tree
+ * from a JSON file (or `--rules='-'` for stdin). The replacement is
+ * validated by re-evaluating against a probe context before being
+ * persisted; structurally-invalid trees abort with a non-zero exit.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { readFileSync } from "node:fs";
+import { evaluateRule, type TargetingRule } from "@toolctrl/feature-flags";
+import { broadcastFlagInvalidation } from "./invalidate.js";
+
+async function applyRules(name: string, rulesJson: string): Promise<void> {
+  let parsed: TargetingRule | null;
+  try {
+    const value = JSON.parse(rulesJson);
+    parsed = value === null ? null : (value as TargetingRule);
+  } catch (err: unknown) {
+    consola.error("Failed to parse rules JSON:", err);
+    process.exitCode = 1;
+    return;
+  }
+  if (parsed) {
+    try {
+      evaluateRule(parsed, { flagName: name, tenantId: "probe", userId: "probe" });
+    } catch (err: unknown) {
+      consola.error("Rule tree did not evaluate cleanly:", err);
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const { getDbClient } = await import("@toolctrl/db/client.server");
+  const prisma = getDbClient();
+  const existing = await prisma.featureFlag.findFirst({ where: { name } });
+  if (!existing) {
+    consola.error(`Flag "${name}" not found.`);
+    process.exitCode = 1;
+    return;
+  }
+  await prisma.$transaction([
+    prisma.featureFlag.update({
+      where: { id: existing.id },
+      data: { rules: (parsed ?? null) as unknown as never },
+    }),
+    prisma.featureFlagAudit.create({
+      data: {
+        flagId: existing.id,
+        actorUserId: null,
+        action: "update",
+        oldValue: { rules: (existing.rules ?? null) as unknown as never },
+        newValue: { rules: (parsed ?? null) as unknown as never },
+      },
+    }),
+  ]);
+  await broadcastFlagInvalidation(name);
+  consola.success(`Rules for "${name}" updated.`);
+}
+
+export const featureFlagsSetRulesCommand = defineCommand({
+  meta: {
+    name: "set-rules",
+    description: "Replace a flag's targeting-rule tree from a JSON file (or '-' for stdin).",
+  },
+  args: {
+    name: { type: "positional", required: true, description: "Flag name." },
+    file: {
+      type: "string",
+      description: "Path to JSON file containing the rule tree, or '-' for stdin. Use empty file to clear rules (null).",
+      required: true,
+    },
+  },
+  async run({ args }) {
+    const file = String(args.file);
+    let raw: string;
+    if (file === "-") {
+      raw = readStdin();
+    } else {
+      raw = readFileSync(file, "utf-8");
+    }
+    raw = raw.trim() || "null";
+    await applyRules(String(args.name), raw);
+  },
+});
+
+function readStdin(): string {
+  // Synchronous read of stdin — citty CLI commands are short-lived so
+  // blocking the event loop on a small input is fine.
+  const chunks: Buffer[] = [];
+  let chunk: Buffer | null;
+  // Node's read returns null if no data available; for piped input the
+  // descriptor is opened in blocking mode for the duration of the read.
+  const fs = require("node:fs");
+  try {
+    const data = fs.readFileSync(0, "utf-8");
+    return data;
+  } catch {
+    return "";
+  }
+  void chunks;
+  void chunk;
+}

hivegrid-cloud/packages/cli/src/commands/feature-flags/toggle.test.ts

@@ -0,0 +1,104 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+type FeatureFlagRecord = {
+  id: string;
+  name: string;
+  enabled: boolean;
+};
+
+const dbMock = {
+  featureFlag: {
+    findFirst: vi.fn<() => Promise<FeatureFlagRecord | null>>(),
+    update: vi.fn(),
+  },
+  featureFlagAudit: {
+    create: vi.fn(),
+  },
+  $transaction: vi.fn(),
+};
+const broadcastFlagInvalidationMock = vi.fn();
+
+vi.mock("@toolctrl/db/client.server", () => ({
+  getDbClient: () => dbMock,
+}));
+vi.mock("consola", () => ({
+  default: {
+    error: vi.fn(),
+    info: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+vi.mock("./invalidate.js", () => ({
+  broadcastFlagInvalidation: (...args: unknown[]) => broadcastFlagInvalidationMock(...args),
+}));
+
+import consola from "consola";
+import { featureFlagsDisableCommand, featureFlagsEnableCommand } from "./toggle.js";
+
+const consoleMock = vi.mocked(consola);
+
+describe("feature flag toggle commands", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.exitCode = undefined;
+    dbMock.$transaction.mockResolvedValue([]);
+    broadcastFlagInvalidationMock.mockResolvedValue(undefined);
+  });
+
+  it("reports missing flags without writing audit rows", async () => {
+    dbMock.featureFlag.findFirst.mockResolvedValueOnce(null);
+
+    await featureFlagsEnableCommand.run?.({ args: { name: "billing.beta" } } as never);
+
+    expect(dbMock.featureFlag.findFirst).toHaveBeenCalledWith({ where: { name: "billing.beta" } });
+    expect(consoleMock.error).toHaveBeenCalledWith('Flag "billing.beta" not found.');
+    expect(process.exitCode).toBe(1);
+    expect(dbMock.$transaction).not.toHaveBeenCalled();
+    expect(broadcastFlagInvalidationMock).not.toHaveBeenCalled();
+  });
+
+  it("treats already matching state as a no-op", async () => {
+    dbMock.featureFlag.findFirst.mockResolvedValueOnce({
+      id: "flag_1",
+      name: "billing.beta",
+      enabled: true,
+    });
+
+    await featureFlagsEnableCommand.run?.({ args: { name: "billing.beta" } } as never);
+
+    expect(consoleMock.info).toHaveBeenCalledWith('Flag "billing.beta" is already enabled; no-op.');
+    expect(process.exitCode).toBeUndefined();
+    expect(dbMock.$transaction).not.toHaveBeenCalled();
+    expect(broadcastFlagInvalidationMock).not.toHaveBeenCalled();
+  });
+
+  it("persists disabled state, audits the change, and broadcasts invalidation", async () => {
+    dbMock.featureFlag.findFirst.mockResolvedValueOnce({
+      id: "flag_1",
+      name: "billing.beta",
+      enabled: true,
+    });
+
+    await featureFlagsDisableCommand.run?.({ args: { name: "billing.beta" } } as never);
+
+    expect(dbMock.featureFlag.update).toHaveBeenCalledWith({
+      where: { id: "flag_1" },
+      data: { enabled: false },
+    });
+    expect(dbMock.featureFlagAudit.create).toHaveBeenCalledWith({
+      data: {
+        flagId: "flag_1",
+        actorUserId: null,
+        action: "toggle",
+        oldValue: { enabled: true },
+        newValue: { enabled: false },
+      },
+    });
+    expect(dbMock.$transaction).toHaveBeenCalledWith([
+      dbMock.featureFlag.update.mock.results[0]?.value,
+      dbMock.featureFlagAudit.create.mock.results[0]?.value,
+    ]);
+    expect(broadcastFlagInvalidationMock).toHaveBeenCalledWith("billing.beta");
+    expect(consoleMock.success).toHaveBeenCalledWith('Flag "billing.beta" → disabled.');
+  });
+});

hivegrid-cloud/packages/cli/src/commands/feature-flags/toggle.ts

@@ -0,0 +1,60 @@
+/**
+ * `feature-flags enable` / `feature-flags disable` — flip a flag's
+ * boolean `enabled` and write an audit row, then publish a one-shot
+ * invalidation on the `feature-flags:invalidate` pub/sub channel so
+ * every long-lived web replica drops its L1 eval cache for this flag
+ * immediately rather than serving stale evaluations until the per-key
+ * TTL expires (#39 cross-process publisher).
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { broadcastFlagInvalidation } from "./invalidate.js";
+
+async function toggleFlag(name: string, target: boolean): Promise<void> {
+  const { getDbClient } = await import("@toolctrl/db/client.server");
+  const prisma = getDbClient();
+  const existing = await prisma.featureFlag.findFirst({ where: { name } });
+  if (!existing) {
+    consola.error(`Flag "${name}" not found.`);
+    process.exitCode = 1;
+    return;
+  }
+  if (existing.enabled === target) {
+    consola.info(`Flag "${name}" is already ${target ? "enabled" : "disabled"}; no-op.`);
+    return;
+  }
+  await prisma.$transaction([
+    prisma.featureFlag.update({ where: { id: existing.id }, data: { enabled: target } }),
+    prisma.featureFlagAudit.create({
+      data: {
+        flagId: existing.id,
+        actorUserId: null,
+        action: "toggle",
+        oldValue: { enabled: existing.enabled },
+        newValue: { enabled: target },
+      },
+    }),
+  ]);
+  await broadcastFlagInvalidation(name);
+  consola.success(`Flag "${name}" → ${target ? "enabled" : "disabled"}.`);
+}
+
+export const featureFlagsEnableCommand = defineCommand({
+  meta: { name: "enable", description: "Enable a feature flag by name." },
+  args: {
+    name: { type: "positional", required: true, description: "Flag name." },
+  },
+  async run({ args }) {
+    await toggleFlag(String(args.name), true);
+  },
+});
+
+export const featureFlagsDisableCommand = defineCommand({
+  meta: { name: "disable", description: "Disable a feature flag by name." },
+  args: {
+    name: { type: "positional", required: true, description: "Flag name." },
+  },
+  async run({ args }) {
+    await toggleFlag(String(args.name), false);
+  },
+});

hivegrid-cloud/packages/cli/src/commands/forms/create.ts

@@ -0,0 +1,47 @@
+/**
+ * `forms create --tenant <id> --name <name> [--origin <url>]` — seed a
+ * minimal form definition (text + email + textarea + honeypot) and
+ * print the resulting public key for embed-snippet wiring.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { FormDefinitionSchema, HONEYPOT_FIELD_KEY } from "@toolctrl/form-widget";
+
+export const formsCreateCommand = defineCommand({
+  meta: { name: "create", description: "Seed a minimal form for a tenant." },
+  args: {
+    tenant: { type: "string", required: true, description: "Tenant ID." },
+    name: { type: "string", required: true, description: "Form display name." },
+    origin: { type: "string", required: false, description: "Allowed embedding origin (https://...)." },
+  },
+  async run({ args }) {
+    const tenantId = String(args.tenant);
+    const name = String(args.name);
+    const origin = args.origin ? String(args.origin) : undefined;
+    const definition = FormDefinitionSchema.parse({
+      title: name,
+      submitLabel: "Submit",
+      successMessage: "Thanks — we received your submission.",
+      fields: [
+        { key: "full_name", type: "text", label: "Full name", required: true },
+        { key: "email", type: "email", label: "Email", required: true },
+        { key: "message", type: "textarea", label: "Message", required: false },
+        { key: HONEYPOT_FIELD_KEY, type: "honeypot", label: "Leave empty" },
+      ],
+    });
+    const { getDbClient } = await import("@toolctrl/db/client.server");
+    const prisma = getDbClient();
+    const created = await prisma.form.create({
+      data: {
+        tenantId,
+        name,
+        definition: definition as object,
+        allowedOrigins: origin ? [origin] : [],
+        config: { honeypotEnabled: true } as object,
+      },
+      select: { id: true, key: true },
+    });
+    consola.success(`Form created: id=${created.id} key=${created.key}`);
+    consola.log(`Embed: <script src="<host>/embed/widget.js" data-form-key="${created.key}" async></script>`);
+  },
+});

hivegrid-cloud/packages/cli/src/commands/forms/delete.ts

@@ -0,0 +1,26 @@
+/**
+ * `forms delete --id <formId>` — hard-delete a form and cascade
+ * its FormSubmission rows. No soft-delete in Phase-1.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+
+export const formsDeleteCommand = defineCommand({
+  meta: { name: "delete", description: "Delete a form (cascade submissions)." },
+  args: {
+    id: { type: "string", required: true, description: "Form ID." },
+  },
+  async run({ args }) {
+    const { getDbClient } = await import("@toolctrl/db/client.server");
+    const prisma = getDbClient();
+    const id = String(args.id);
+    const existing = await prisma.form.findUnique({ where: { id }, select: { id: true, name: true } });
+    if (!existing) {
+      consola.error(`Form ${id} not found.`);
+      process.exitCode = 1;
+      return;
+    }
+    await prisma.form.delete({ where: { id } });
+    consola.success(`Form deleted: ${id} (${existing.name}).`);
+  },
+});

hivegrid-cloud/packages/cli/src/commands/forms/index.ts

@@ -0,0 +1,16 @@
+import { defineCommand } from "citty";
+import { formsListCommand } from "./list.js";
+import { formsCreateCommand } from "./create.js";
+import { formsDeleteCommand } from "./delete.js";
+
+export const formsCommand = defineCommand({
+  meta: {
+    name: "forms",
+    description: "Embeddable form-widget admin commands (list, create, delete).",
+  },
+  subCommands: {
+    list: formsListCommand,
+    create: formsCreateCommand,
+    delete: formsDeleteCommand,
+  },
+});

hivegrid-cloud/packages/cli/src/commands/forms/list.ts

@@ -0,0 +1,37 @@
+/**
+ * `forms list --tenant <tenantId>` — print every form with submission count.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+
+export const formsListCommand = defineCommand({
+  meta: { name: "list", description: "List forms for a tenant." },
+  args: {
+    tenant: { type: "string", required: true, description: "Tenant ID." },
+  },
+  async run({ args }) {
+    const { getDbClient } = await import("@toolctrl/db/client.server");
+    const prisma = getDbClient();
+    const tenantId = String(args.tenant);
+    const forms = await prisma.form.findMany({
+      where: { tenantId },
+      orderBy: { createdAt: "desc" },
+      select: {
+        id: true,
+        key: true,
+        name: true,
+        isEnabled: true,
+        _count: { select: { submissions: true } },
+      },
+    });
+    if (forms.length === 0) {
+      consola.info(`No forms for tenant ${tenantId}.`);
+      return;
+    }
+    for (const f of forms) {
+      const state = f.isEnabled ? "ON " : "OFF";
+      consola.log(`${state}  ${f.id.padEnd(28)} ${f.key.padEnd(28)} subs=${f._count.submissions} ${f.name}`);
+    }
+    consola.success(`${forms.length} forms listed.`);
+  },
+});

hivegrid-cloud/packages/cli/src/commands/leads/commands.test.ts

@@ -0,0 +1,154 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+type LeadRecord = Record<string, unknown> & {
+  id: string;
+  email: string;
+  firstName?: string | null;
+  lastName?: string | null;
+  company?: string | null;
+  status: string;
+  source?: string | null;
+  utmSource?: string | null;
+  createdAt: Date;
+};
+
+const dbMock = {
+  lead: {
+    findMany: vi.fn<() => Promise<LeadRecord[]>>(),
+  },
+};
+const writeFileMock = vi.fn();
+
+vi.mock("@toolctrl/db/client.server", () => ({
+  getDbClient: () => dbMock,
+}));
+vi.mock("node:fs/promises", () => ({
+  default: { writeFile: (...args: unknown[]) => writeFileMock(...args) },
+  writeFile: (...args: unknown[]) => writeFileMock(...args),
+}));
+vi.mock("consola", () => ({
+  default: {
+    info: vi.fn(),
+    log: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+
+import consola from "consola";
+import { leadsExportCommand } from "./export.js";
+import { leadsListCommand } from "./list.js";
+
+const consoleMock = vi.mocked(consola);
+
+describe("leads CLI commands", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    dbMock.lead.findMany.mockResolvedValue([]);
+    writeFileMock.mockResolvedValue(undefined);
+  });
+
+  it("lists captured leads with bounded limit, status filter, and display fallbacks", async () => {
+    dbMock.lead.findMany.mockResolvedValueOnce([
+      {
+        id: "lead_1",
+        email: "ada@example.com",
+        firstName: "Ada",
+        lastName: "Lovelace",
+        company: "Analytical",
+        status: "new",
+        source: null,
+        utmSource: "newsletter",
+        createdAt: new Date("2026-05-25T12:00:00.000Z"),
+      },
+      {
+        id: "lead_2",
+        email: "grace@example.com",
+        firstName: null,
+        lastName: null,
+        company: null,
+        status: "contacted",
+        source: "form",
+        utmSource: null,
+        createdAt: new Date("2026-05-24T12:00:00.000Z"),
+      },
+    ]);
+
+    await leadsListCommand.run?.({ args: { status: "new", limit: "999" } } as never);
+
+    expect(dbMock.lead.findMany).toHaveBeenCalledWith({
+      where: { status: "new" },
+      orderBy: { createdAt: "desc" },
+      take: 500,
+      select: {
+        id: true,
+        email: true,
+        firstName: true,
+        lastName: true,
+        company: true,
+        status: true,
+        source: true,
+        utmSource: true,
+        createdAt: true,
+      },
+    });
+    expect(consoleMock.log).toHaveBeenCalledWith(expect.stringContaining("utm=newsletter Ada Lovelace"));
+    expect(consoleMock.log).toHaveBeenCalledWith(expect.stringContaining("src=form utm=- -"));
+    expect(consoleMock.success).toHaveBeenCalledWith("2 leads listed.");
+  });
+
+  it("reports empty lead lists with and without status filters", async () => {
+    await leadsListCommand.run?.({ args: {} } as never);
+    await leadsListCommand.run?.({ args: { status: "archived" } } as never);
+
+    expect(consoleMock.info).toHaveBeenCalledWith("No leads captured yet.");
+    expect(consoleMock.info).toHaveBeenCalledWith("No leads with status=archived.");
+    expect(consoleMock.success).not.toHaveBeenCalled();
+  });
+
+  it("exports escaped CSV to stdout", async () => {
+    const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+    dbMock.lead.findMany.mockResolvedValueOnce([
+      {
+        id: "lead_1",
+        email: "ada@example.com",
+        firstName: "Ada",
+        lastName: 'Love, "Countess"',
+        phone: null,
+        company: "Analytical\nEngines",
+        source: "form",
+        status: "new",
+        utmSource: "newsletter",
+        createdAt: new Date("2026-05-25T12:00:00.000Z"),
+        lastTouchAt: null,
+      },
+    ]);
+
+    await leadsExportCommand.run?.({ args: { status: "new" } } as never);
+
+    expect(dbMock.lead.findMany).toHaveBeenCalledWith({
+      where: { status: "new" },
+      orderBy: { createdAt: "desc" },
+    });
+    const csv = String(stdoutSpy.mock.calls[0]?.[0]);
+    expect(csv).toContain("id,email,firstName,lastName");
+    expect(csv).toContain('"Love, ""Countess"""');
+    expect(csv).toContain('"Analytical\nEngines"');
+    expect(writeFileMock).not.toHaveBeenCalled();
+    expect(consoleMock.success).toHaveBeenCalledWith("Exported 1 leads.");
+
+    stdoutSpy.mockRestore();
+  });
+
+  it("writes CSV exports to a file when requested", async () => {
+    dbMock.lead.findMany.mockResolvedValueOnce([]);
+
+    await leadsExportCommand.run?.({ args: { out: "/tmp/leads.csv" } } as never);
+
+    expect(writeFileMock).toHaveBeenCalledWith(
+      "/tmp/leads.csv",
+      expect.stringMatching(/^id,email,firstName,/u),
+      "utf8",
+    );
+    expect(consoleMock.success).toHaveBeenCalledWith("Wrote 0 leads to /tmp/leads.csv.");
+  });
+});

hivegrid-cloud/packages/cli/src/commands/leads/delete.ts

@@ -0,0 +1,25 @@
+/**
+ * `leads delete --id <leadId>` — hard-delete a single lead and its events.
+ * Use for DSGVO right-to-be-forgotten requests.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+
+export const leadsDeleteCommand = defineCommand({
+  meta: { name: "delete", description: "Delete a lead (DSGVO right-to-be-forgotten)." },
+  args: {
+    id: { type: "string", required: true, description: "Lead id." },
+  },
+  async run({ args }) {
+    const { getDbClient } = await import("@toolctrl/db/client.server");
+    const prisma = getDbClient();
+    const id = String(args.id);
+    const existing = await prisma.lead.findUnique({ where: { id }, select: { email: true } });
+    if (!existing) {
+      consola.warn(`Lead ${id} not found.`);
+      return;
+    }
+    await prisma.lead.delete({ where: { id } });
+    consola.success(`Deleted lead ${id} (${existing.email}).`);
+  },
+});

hivegrid-cloud/packages/cli/src/commands/leads/export.ts

@@ -0,0 +1,66 @@
+/**
+ * `leads export [--out <path>]` — dump every lead as CSV to stdout or a file.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { writeFile } from "node:fs/promises";
+
+const COLUMNS = [
+  "id",
+  "email",
+  "firstName",
+  "lastName",
+  "phone",
+  "company",
+  "source",
+  "status",
+  "utmSource",
+  "utmMedium",
+  "utmCampaign",
+  "utmTerm",
+  "utmContent",
+  "gclid",
+  "fbclid",
+  "referrer",
+  "landingPage",
+  "score",
+  "createdAt",
+  "lastTouchAt",
+] as const;
+
+function csvEscape(v: unknown): string {
+  if (v === null || v === undefined) return "";
+  const s = String(v);
+  if (s.includes(",") || s.includes('"') || s.includes("\n")) {
+    return `"${s.replace(/"/g, '""')}"`;
+  }
+  return s;
+}
+
+export const leadsExportCommand = defineCommand({
+  meta: { name: "export", description: "Export all leads as CSV." },
+  args: {
+    out: { type: "string", required: false, description: "Output file path (default stdout)." },
+    status: { type: "string", required: false, description: "Filter by status." },
+  },
+  async run({ args }) {
+    const { getDbClient } = await import("@toolctrl/db/client.server");
+    const prisma = getDbClient();
+    const where = args.status ? { status: String(args.status) as never } : {};
+    const leads = await prisma.lead.findMany({ where, orderBy: { createdAt: "desc" } });
+    const header = COLUMNS.join(",");
+    const lines = [header];
+    for (const l of leads) {
+      const row = COLUMNS.map((c) => csvEscape((l as Record<string, unknown>)[c])).join(",");
+      lines.push(row);
+    }
+    const csv = `${lines.join("\n")}\n`;
+    if (args.out) {
+      await writeFile(String(args.out), csv, "utf8");
+      consola.success(`Wrote ${leads.length} leads to ${args.out}.`);
+    } else {
+      process.stdout.write(csv);
+      consola.success(`Exported ${leads.length} leads.`);
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/leads/index.ts

@@ -0,0 +1,16 @@
+import { defineCommand } from "citty";
+import { leadsListCommand } from "./list.js";
+import { leadsExportCommand } from "./export.js";
+import { leadsDeleteCommand } from "./delete.js";
+
+export const leadsCommand = defineCommand({
+  meta: {
+    name: "leads",
+    description: "Marketing-funnel lead inbox commands (list, export, delete).",
+  },
+  subCommands: {
+    list: leadsListCommand,
+    export: leadsExportCommand,
+    delete: leadsDeleteCommand,
+  },
+});

hivegrid-cloud/packages/cli/src/commands/leads/list.ts

@@ -0,0 +1,46 @@
+/**
+ * `leads list [--status <s>] [--limit <n>]` — print the latest leads.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+
+export const leadsListCommand = defineCommand({
+  meta: { name: "list", description: "List captured marketing leads." },
+  args: {
+    status: { type: "string", required: false, description: "Filter by status (new|contacted|...)." },
+    limit: { type: "string", required: false, description: "Max rows (default 50)." },
+  },
+  async run({ args }) {
+    const { getDbClient } = await import("@toolctrl/db/client.server");
+    const prisma = getDbClient();
+    const limit = Math.min(500, Math.max(1, Number(args.limit ?? "50")));
+    const where = args.status ? { status: String(args.status) as never } : {};
+    const leads = await prisma.lead.findMany({
+      where,
+      orderBy: { createdAt: "desc" },
+      take: limit,
+      select: {
+        id: true,
+        email: true,
+        firstName: true,
+        lastName: true,
+        company: true,
+        status: true,
+        source: true,
+        utmSource: true,
+        createdAt: true,
+      },
+    });
+    if (leads.length === 0) {
+      consola.info(args.status ? `No leads with status=${args.status}.` : "No leads captured yet.");
+      return;
+    }
+    for (const l of leads) {
+      const name = [l.firstName, l.lastName].filter(Boolean).join(" ") || "-";
+      consola.log(
+        `${l.status.padEnd(13)} ${l.id.padEnd(28)} ${l.email.padEnd(40)} src=${l.source ?? "-"} utm=${l.utmSource ?? "-"} ${name}`,
+      );
+    }
+    consola.success(`${leads.length} leads listed.`);
+  },
+});

hivegrid-cloud/packages/cli/src/commands/marketing/attribution.ts

@@ -0,0 +1,76 @@
+/**
+ * `marketing attribution [--days N] [--dimension campaign|utmSource|source|path]`
+ * — print conversion counts grouped by attribution dimension.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+
+const DIMENSIONS = ["campaign", "utmSource", "source", "path"] as const;
+
+export const marketingAttributionCommand = defineCommand({
+  meta: { name: "attribution", description: "Print conversion counts grouped by attribution dimension." },
+  args: {
+    days: { type: "string", required: false, description: "Period in days (default 30)." },
+    dimension: { type: "string", required: false, description: `One of ${DIMENSIONS.join("|")} (default campaign).` },
+    limit: { type: "string", required: false, description: "Top N rows (default 25)." },
+  },
+  async run({ args }) {
+    const { getReadDbClient } = await import("@toolctrl/db/client.server");
+    const prisma = getReadDbClient();
+    const days = Math.min(365, Math.max(1, Number(args.days ?? "30")));
+    const dim = (DIMENSIONS as readonly string[]).includes(String(args.dimension ?? ""))
+      ? String(args.dimension)
+      : "campaign";
+    const limit = Math.min(200, Math.max(1, Number(args.limit ?? "25")));
+    const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+
+    type Row = { key: string | null; count: number };
+    let rows: Row[];
+    const baseWhere = { convertedAt: { gte: since } };
+    if (dim === "campaign") {
+      const r = await prisma.tenantAcquisition.groupBy({
+        by: ["utmCampaign"],
+        _count: { _all: true },
+        where: baseWhere,
+        orderBy: { _count: { tenantId: "desc" } },
+        take: limit,
+      });
+      rows = r.map((x) => ({ key: x.utmCampaign, count: x._count._all }));
+    } else if (dim === "utmSource") {
+      const r = await prisma.tenantAcquisition.groupBy({
+        by: ["utmSource"],
+        _count: { _all: true },
+        where: baseWhere,
+        orderBy: { _count: { tenantId: "desc" } },
+        take: limit,
+      });
+      rows = r.map((x) => ({ key: x.utmSource, count: x._count._all }));
+    } else if (dim === "source") {
+      const r = await prisma.tenantAcquisition.groupBy({
+        by: ["source"],
+        _count: { _all: true },
+        where: baseWhere,
+        orderBy: { _count: { tenantId: "desc" } },
+        take: limit,
+      });
+      rows = r.map((x) => ({ key: x.source, count: x._count._all }));
+    } else {
+      const r = await prisma.tenantAcquisition.groupBy({
+        by: ["conversionPath"],
+        _count: { _all: true },
+        where: baseWhere,
+        orderBy: { _count: { tenantId: "desc" } },
+        take: limit,
+      });
+      rows = r.map((x) => ({ key: x.conversionPath, count: x._count._all }));
+    }
+    if (rows.length === 0) {
+      consola.info(`No conversions in last ${days} days.`);
+      return;
+    }
+    consola.log(`Attribution by ${dim} — last ${days} days (since ${since.toISOString().slice(0, 10)})`);
+    for (const r of rows) {
+      consola.log(`  ${String(r.key ?? "(none)").padEnd(40)} ${r.count}`);
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/marketing/funnel.ts

@@ -0,0 +1,42 @@
+/**
+ * `marketing funnel [--days N]` — print conversion-rate snapshot.
+ *
+ * Mirrors the /admin/marketing-funnels report for shell-based ops.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+
+export const marketingFunnelCommand = defineCommand({
+  meta: { name: "funnel", description: "Print marketing-funnel conversion snapshot." },
+  args: {
+    days: { type: "string", required: false, description: "Period in days (default 30)." },
+  },
+  async run({ args }) {
+    const { getReadDbClient } = await import("@toolctrl/db/client.server");
+    const prisma = getReadDbClient();
+    const days = Math.min(365, Math.max(1, Number(args.days ?? "30")));
+    const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+
+    const [leadCount, conversionCount, statusGroups] = await Promise.all([
+      prisma.lead.count({ where: { createdAt: { gte: since } } }),
+      prisma.tenantAcquisition.count({ where: { convertedAt: { gte: since } } }),
+      prisma.lead.groupBy({
+        by: ["status"],
+        _count: { _all: true },
+        where: { createdAt: { gte: since } },
+      }),
+    ]);
+    const rate = leadCount > 0 ? conversionCount / leadCount : 0;
+    consola.log(`Period: last ${days} days (since ${since.toISOString().slice(0, 10)})`);
+    consola.log(`Leads captured:   ${leadCount}`);
+    consola.log(`Conversions:      ${conversionCount}`);
+    consola.log(`Conversion rate:  ${(rate * 100).toFixed(2)}%`);
+    consola.log("");
+    consola.log("Stage distribution:");
+    const order = ["new", "contacted", "qualified", "trial", "customer", "churned", "disqualified"];
+    const counts = new Map<string, number>(statusGroups.map((g) => [String(g.status), g._count._all]));
+    for (const s of order) {
+      consola.log(`  ${s.padEnd(15)} ${counts.get(s) ?? 0}`);
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/marketing/index.ts

@@ -0,0 +1,14 @@
+import { defineCommand } from "citty";
+import { marketingFunnelCommand } from "./funnel.js";
+import { marketingAttributionCommand } from "./attribution.js";
+
+export const marketingCommand = defineCommand({
+  meta: {
+    name: "marketing",
+    description: "Marketing-funnel operator commands (funnel snapshot, attribution reports).",
+  },
+  subCommands: {
+    funnel: marketingFunnelCommand,
+    attribution: marketingAttributionCommand,
+  },
+});

hivegrid-cloud/packages/cli/src/commands/ops/_env.test.ts

@@ -0,0 +1,73 @@
+import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { OpsEnvError, maskConnectionUrl, parseDotenv, resolveOpsEnv, validateEnvName } from "./_env.js";
+
+describe("ops env resolver", () => {
+  let home: string;
+
+  beforeEach(() => {
+    home = mkdtempSync(path.join(tmpdir(), "toolctrl-cli-ops-env-"));
+  });
+
+  afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+  });
+
+  it("returns process.env unchanged for local mode", () => {
+    const resolved = resolveOpsEnv({ processEnvOverride: { FOO: "bar" } });
+    expect(resolved.label).toBe("local");
+    expect(resolved.env.FOO).toBe("bar");
+    expect(resolved.sourcePath).toBeNull();
+    expect(resolved.warnings).toEqual([]);
+  });
+
+  it("reads ~/.toolctrl/envs/<name>.env when --env is supplied", () => {
+    const envDir = path.join(home, ".toolctrl", "envs");
+    mkdirSync(envDir, { recursive: true });
+    const file = path.join(envDir, "staging.env");
+    writeFileSync(file, "# header\nDATABASE_URL=postgres://u:p@host:5432/db\nREDIS_URL=\"redis://r\"\n");
+    chmodSync(file, 0o600);
+    const resolved = resolveOpsEnv({ name: "staging", homeDirOverride: home });
+    expect(resolved.label).toBe("staging");
+    expect(resolved.env.DATABASE_URL).toBe("postgres://u:p@host:5432/db");
+    expect(resolved.env.REDIS_URL).toBe("redis://r");
+    expect(resolved.sourcePath).toBe(file);
+    expect(resolved.warnings).toEqual([]);
+  });
+
+  it("warns when the env-file is world-readable", () => {
+    const envDir = path.join(home, ".toolctrl", "envs");
+    mkdirSync(envDir, { recursive: true });
+    const file = path.join(envDir, "loose.env");
+    writeFileSync(file, "FOO=bar\n");
+    const resolved = resolveOpsEnv({
+      name: "loose",
+      homeDirOverride: home,
+      statModeOverride: () => 0o644,
+    });
+    expect(resolved.warnings.length).toBe(1);
+    expect(resolved.warnings[0]).toMatch(/chmod 600/u);
+  });
+
+  it("throws OpsEnvError when env-file is missing", () => {
+    expect(() => resolveOpsEnv({ name: "missing", homeDirOverride: home })).toThrow(OpsEnvError);
+  });
+
+  it("rejects invalid env-names", () => {
+    expect(() => validateEnvName("../etc/passwd")).toThrow(OpsEnvError);
+    expect(() => validateEnvName("ok-1.env_v2")).not.toThrow();
+  });
+
+  it("parses simple .env files", () => {
+    const out = parseDotenv("# comment\n\nA=1\nB='two'\nC=\"three\"\nBAD LINE\n=novalue\nlowercase=ok\n");
+    expect(out).toEqual({ A: "1", B: "two", C: "three", lowercase: "ok" });
+  });
+
+  it("masks connection URLs without credentials", () => {
+    expect(maskConnectionUrl("postgres://u:p@db:5432/app")).toBe("postgres://db:5432");
+    expect(maskConnectionUrl(undefined)).toBe("<unset>");
+    expect(maskConnectionUrl("not-a-url")).toBe("<malformed>");
+  });
+});

hivegrid-cloud/packages/cli/src/commands/ops/_env.ts

@@ -0,0 +1,134 @@
+/**
+ * `toolctrl ops` env resolver.
+ *
+ * Two layers:
+ *  - **local (default):** the operator's working-dir `.env` (already loaded
+ *    by the runtime via dotenv or shell-export). We just read from
+ *    `process.env`.
+ *  - **named (`--env=<name>`):** parsed from `~/.toolctrl/envs/<name>.env`.
+ *    File format is a simple `KEY=VALUE` `.env` syntax — no shell
+ *    interpolation. Lines starting with `#` and blank lines are skipped.
+ *
+ * The named-env directory layout is intentionally minimal so operators
+ * can manage it with normal file tools (`chmod 600`, `gpg`, etc.). See
+ * `docs/contributing/cli-ops.md` for the recommended ownership/permission
+ * model.
+ *
+ * Refs: docs/improvement-plan/08-mobile-cli-storybook-sdk/cli-ops.md
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+export type EnvBag = Record<string, string | undefined>;
+
+export interface ResolveEnvOptions {
+  /** `--env=<name>` value; `undefined` ⇒ local mode. */
+  readonly name?: string;
+  /** Override the home-dir for tests. */
+  readonly homeDirOverride?: string;
+  /** Override `process.env` for tests. */
+  readonly processEnvOverride?: EnvBag;
+  /** Override `chmod` lookup for tests. */
+  readonly statModeOverride?: (filePath: string) => number;
+}
+
+export interface ResolvedOpsEnv {
+  /** "local" or "<name>" — used for log labelling. */
+  readonly label: string;
+  /** Merged env: file values overlay onto a `{}` base. */
+  readonly env: EnvBag;
+  /** Absolute path of the source file (or null for local). */
+  readonly sourcePath: string | null;
+  /** Non-fatal warnings — e.g. world-readable file. */
+  readonly warnings: ReadonlyArray<string>;
+}
+
+export class OpsEnvError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "OpsEnvError";
+  }
+}
+
+/** Resolves the env bag for an ops command invocation. */
+export function resolveOpsEnv(options: ResolveEnvOptions = {}): ResolvedOpsEnv {
+  if (!options.name) {
+    return {
+      label: "local",
+      env: { ...(options.processEnvOverride ?? process.env) },
+      sourcePath: null,
+      warnings: [],
+    };
+  }
+  validateEnvName(options.name);
+  const home = options.homeDirOverride ?? homedir();
+  const filePath = path.join(home, ".toolctrl", "envs", `${options.name}.env`);
+  if (!existsSync(filePath)) {
+    throw new OpsEnvError(
+      `Env file not found: ${filePath}. Create it (chmod 600) before invoking --env=${options.name}.`,
+    );
+  }
+  const warnings: string[] = [];
+  const mode =
+    options.statModeOverride?.(filePath) ?? (statSync(filePath).mode & 0o777);
+  if ((mode & 0o077) !== 0) {
+    warnings.push(
+      `Permissions on ${filePath} are 0o${mode.toString(8)} (world/group readable). Run: chmod 600 ${filePath}`,
+    );
+  }
+  const raw = readFileSync(filePath, "utf8");
+  const parsed = parseDotenv(raw);
+  return {
+    label: options.name,
+    env: parsed,
+    sourcePath: filePath,
+    warnings,
+  };
+}
+
+/** Stricter than RFC 1738 — keeps file paths predictable. */
+export function validateEnvName(name: string): void {
+  if (!/^[a-z0-9][a-z0-9._-]{0,63}$/iu.test(name)) {
+    throw new OpsEnvError(
+      `Invalid --env name "${name}". Allowed chars: a-z, 0-9, dot, dash, underscore (max 64).`,
+    );
+  }
+}
+
+/**
+ * Minimal `.env` parser — only `KEY=VALUE`, optional surrounding double-
+ * or single-quotes, no shell interpolation. We deliberately avoid pulling
+ * in `dotenv` so the CLI keeps zero extra deps.
+ */
+export function parseDotenv(input: string): EnvBag {
+  const out: EnvBag = {};
+  for (const rawLine of input.split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    if (!/^[A-Z_][A-Z0-9_]*$/iu.test(key)) continue;
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+/** Mask a DB / connection URL down to scheme://host:port for logs. */
+export function maskConnectionUrl(value: string | undefined): string {
+  if (!value) return "<unset>";
+  try {
+    const url = new URL(value);
+    return `${url.protocol}//${url.hostname}${url.port ? `:${url.port}` : ""}`;
+  } catch {
+    return "<malformed>";
+  }
+}

hivegrid-cloud/packages/cli/src/commands/ops/doctor.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it } from "vitest";
+import {
+  PROBES,
+  formatDoctorReport,
+  runDoctor,
+  type Probe,
+  type ProbeResult,
+} from "./doctor.js";
+
+function fakeProbe(name: string, result: Omit<ProbeResult, "name">): Probe {
+  return async () => ({ name, ...result });
+}
+
+describe("ops doctor — runDoctor", () => {
+  it("runs every probe and aggregates a summary", async () => {
+    const report = await runDoctor({
+      probes: [
+        fakeProbe("a", { status: "ok" }),
+        fakeProbe("b", { status: "warn", message: "soft" }),
+        fakeProbe("c", { status: "fail", message: "broken" }),
+      ],
+    });
+    expect(report.results.map((r) => r.status)).toEqual(["ok", "warn", "fail"]);
+    expect(report.summary).toEqual({ ok: 1, warn: 1, fail: 1 });
+    expect(report.exitCode).toBe(1);
+  });
+
+  it("exit code is 0 when no probe fails", async () => {
+    const report = await runDoctor({
+      probes: [fakeProbe("a", { status: "ok" }), fakeProbe("b", { status: "warn" })],
+    });
+    expect(report.exitCode).toBe(0);
+  });
+
+  it("catches probe exceptions and records them as fail", async () => {
+    const probe: Probe = async () => {
+      throw new Error("boom");
+    };
+    Object.defineProperty(probe, "name", { value: "explodes" });
+    const report = await runDoctor({ probes: [probe] });
+    expect(report.results[0]).toMatchObject({
+      name: "explodes",
+      status: "fail",
+      message: expect.stringContaining("boom"),
+    });
+  });
+});
+
+describe("ops doctor — built-in probes", () => {
+  it("flags missing required env vars", async () => {
+    const env = {};
+    const probe = PROBES.find((p) => p.name === "envCatalogProbe");
+    expect(probe).toBeDefined();
+    const result = await probe!({ env });
+    expect(result).toMatchObject({
+      name: "env.required",
+      status: "fail",
+    });
+    expect(result.message).toMatch(/DATABASE_URL/u);
+  });
+
+  it("succeeds when required env vars are present", async () => {
+    const probe = PROBES.find((p) => p.name === "envCatalogProbe");
+    const result = await probe!({ env: { DATABASE_URL: "x", SESSION_SECRET: "y" } });
+    expect(result.status).toBe("ok");
+  });
+
+  it("warns when SENTRY_DSN is unset", async () => {
+    const probe = PROBES.find((p) => p.name === "sentryDsnProbe");
+    const result = await probe!({ env: {} });
+    expect(result.status).toBe("warn");
+  });
+
+  it("calls httpHead for sentry probe when DSN is set", async () => {
+    const calls: string[] = [];
+    const probe = PROBES.find((p) => p.name === "sentryDsnProbe");
+    const result = await probe!({
+      env: { SENTRY_DSN: "https://abc@sentry.example.com/1" },
+      httpHead: async (url) => {
+        calls.push(url);
+        return { status: 200 };
+      },
+    });
+    expect(calls).toEqual(["https://sentry.example.com"]);
+    expect(result.status).toBe("ok");
+    expect(result.message).toBe("https://sentry.example.com");
+  });
+
+  it("fails sentry probe when origin returns 500", async () => {
+    const probe = PROBES.find((p) => p.name === "sentryDsnProbe");
+    const result = await probe!({
+      env: { SENTRY_DSN: "https://abc@sentry.example.com/1" },
+      httpHead: async () => ({ status: 503 }),
+    });
+    expect(result.status).toBe("fail");
+  });
+
+  it("postgresProbe calls pgPing only when DATABASE_URL set", async () => {
+    const probe = PROBES.find((p) => p.name === "postgresProbe");
+    const noEnv = await probe!({ env: {} });
+    expect(noEnv.status).toBe("fail");
+
+    const calls: string[] = [];
+    const okResult = await probe!({
+      env: { DATABASE_URL: "postgres://u:p@db:5432/x" },
+      pgPing: async (url) => {
+        calls.push(url);
+      },
+    });
+    expect(okResult.status).toBe("ok");
+    expect(okResult.message).toBe("postgres://db:5432");
+    expect(calls).toEqual(["postgres://u:p@db:5432/x"]);
+
+    const failResult = await probe!({
+      env: { DATABASE_URL: "postgres://u:p@db:5432/x" },
+      pgPing: async () => {
+        throw new Error("ECONNREFUSED");
+      },
+    });
+    expect(failResult.status).toBe("fail");
+    expect(failResult.message).toMatch(/ECONNREFUSED/u);
+  });
+
+  it("redisProbe handles set vs unset", async () => {
+    const probe = PROBES.find((p) => p.name === "redisProbe");
+    const noEnv = await probe!({ env: {} });
+    expect(noEnv.status).toBe("warn");
+
+    const ok = await probe!({
+      env: { REDIS_URL: "redis://localhost:6379" },
+      redisPing: async () => undefined,
+    });
+    expect(ok.status).toBe("ok");
+
+    const fail = await probe!({
+      env: { REDIS_URL: "redis://r" },
+      redisPing: async () => {
+        throw new Error("nope");
+      },
+    });
+    expect(fail.status).toBe("fail");
+  });
+
+  it("pnpmVersionProbe reports ok/warn/fail based on exec", async () => {
+    const probe = PROBES.find((p) => p.name === "pnpmVersionProbe");
+
+    const ok = await probe!({ env: {}, exec: async () => ({ stdout: "9.7.0\n", stderr: "" }) });
+    expect(ok.status).toBe("ok");
+
+    const warn = await probe!({ env: {}, exec: async () => ({ stdout: "8.0.0\n", stderr: "" }) });
+    expect(warn.status).toBe("warn");
+
+    const fail = await probe!({
+      env: {},
+      exec: async () => {
+        throw new Error("ENOENT");
+      },
+    });
+    expect(fail.status).toBe("fail");
+  });
+
+  it("dockerProbe warns when docker is missing", async () => {
+    const probe = PROBES.find((p) => p.name === "dockerProbe");
+    const result = await probe!({
+      env: {},
+      exec: async () => {
+        throw new Error("cannot connect");
+      },
+    });
+    expect(result.status).toBe("warn");
+  });
+
+  it("prismaMigrationProbe reports pending count", async () => {
+    const probe = PROBES.find((p) => p.name === "prismaMigrationProbe");
+    const ok = await probe!({ env: {}, prismaMigrateStatus: async () => ({ pending: 0 }) });
+    expect(ok.status).toBe("ok");
+
+    const warn = await probe!({ env: {}, prismaMigrateStatus: async () => ({ pending: 2 }) });
+    expect(warn.status).toBe("warn");
+    expect(warn.message).toMatch(/2 pending/u);
+
+    const fail = await probe!({
+      env: {},
+      prismaMigrateStatus: async () => {
+        throw new Error("schema drift");
+      },
+    });
+    expect(fail.status).toBe("fail");
+  });
+});
+
+describe("formatDoctorReport", () => {
+  it("renders a table with header and summary", async () => {
+    const out = formatDoctorReport({
+      results: [
+        { name: "a", status: "ok", message: "fine" },
+        { name: "b", status: "fail", message: "broken" },
+      ],
+      summary: { ok: 1, warn: 0, fail: 1 },
+      exitCode: 1,
+    });
+    expect(out).toContain("PROBE");
+    expect(out).toContain("STATUS");
+    expect(out).toContain("summary: 1 ok, 0 warn, 1 fail");
+    expect(out).toContain("a");
+    expect(out).toContain("b");
+    expect(out).toContain("fine");
+    expect(out).toContain("broken");
+  });
+});

hivegrid-cloud/packages/cli/src/commands/ops/doctor.ts

@@ -0,0 +1,336 @@
+/**
+ * `toolctrl ops doctor` — local-stack health check.
+ *
+ * Runs a list of probes, each returning `{ name, status, message? }`.
+ * `status` is `ok | warn | fail`. Exit code is 1 when any probe is `fail`.
+ *
+ * The probe runners are dependency-injected so unit tests can stub
+ * out every external call (DNS, child_process, redis, pg, http).
+ *
+ * Refs: docs/improvement-plan/08-mobile-cli-storybook-sdk/cli-ops.md
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { execFile } from "node:child_process";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { promisify } from "node:util";
+import { maskConnectionUrl, resolveOpsEnv, type EnvBag } from "./_env.js";
+
+export type ProbeStatus = "ok" | "warn" | "fail";
+
+export interface ProbeResult {
+  readonly name: string;
+  readonly status: ProbeStatus;
+  readonly message?: string;
+}
+
+export interface ProbeContext {
+  readonly env: EnvBag;
+  /** Injection point for tests — defaults to real child_process.execFile. */
+  readonly exec?: (cmd: string, args: ReadonlyArray<string>) => Promise<{ stdout: string; stderr: string }>;
+  /** Injection point — defaults to a tiny HTTP HEAD request. */
+  readonly httpHead?: (url: string, timeoutMs: number) => Promise<{ status: number }>;
+  /** Postgres `SELECT 1` probe — defaults to a no-op connector stub. */
+  readonly pgPing?: (databaseUrl: string) => Promise<void>;
+  /** Redis PING — defaults to a no-op connector stub. */
+  readonly redisPing?: (redisUrl: string) => Promise<void>;
+  /** Prisma migrate-status — defaults to `pnpm prisma migrate status`. */
+  readonly prismaMigrateStatus?: () => Promise<{ pending: number }>;
+}
+
+export type Probe = (ctx: ProbeContext) => Promise<ProbeResult>;
+
+const execFileP = promisify(execFile);
+
+async function defaultExec(cmd: string, args: ReadonlyArray<string>): Promise<{ stdout: string; stderr: string }> {
+  try {
+    const { stdout, stderr } = await execFileP(cmd, [...args], { timeout: 10_000 });
+    return { stdout, stderr };
+  } catch (err) {
+    const error = err as NodeJS.ErrnoException & { stdout?: string; stderr?: string };
+    throw Object.assign(new Error(error.message || `exec ${cmd} failed`), {
+      code: error.code,
+      stdout: error.stdout ?? "",
+      stderr: error.stderr ?? "",
+    });
+  }
+}
+
+async function defaultHttpHead(url: string, timeoutMs: number): Promise<{ status: number }> {
+  const parsed = new URL(url);
+  const lib = parsed.protocol === "https:" ? httpsRequest : httpRequest;
+  return await new Promise((resolve, reject) => {
+    const req = lib(parsed, { method: "HEAD", timeout: timeoutMs }, (res) => {
+      resolve({ status: res.statusCode ?? 0 });
+      res.resume();
+    });
+    req.on("timeout", () => req.destroy(new Error("timeout")));
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+/**
+ * Each probe is a tiny pure function — easy to unit-test in isolation.
+ */
+export const PROBES: ReadonlyArray<Probe> = [
+  async function nodeVersionProbe({ exec = defaultExec } = {} as ProbeContext) {
+    const want = ">=20";
+    const actual = process.version;
+    const major = Number.parseInt(actual.replace(/^v/u, "").split(".")[0] ?? "0", 10);
+    if (major >= 20) {
+      return { name: "node.version", status: "ok", message: `${actual} (want ${want})` };
+    }
+    void exec; // signal unused-injection safe
+    return {
+      name: "node.version",
+      status: "fail",
+      message: `Node ${actual} too old — want ${want}. Run \`nvm use\`.`,
+    };
+  },
+
+  async function pnpmVersionProbe({ exec = defaultExec }: ProbeContext) {
+    try {
+      const { stdout } = await exec("pnpm", ["--version"]);
+      const version = stdout.trim();
+      const major = Number.parseInt(version.split(".")[0] ?? "0", 10);
+      if (major >= 9) {
+        return { name: "pnpm.version", status: "ok", message: `pnpm ${version}` };
+      }
+      return { name: "pnpm.version", status: "warn", message: `pnpm ${version} — want >=9` };
+    } catch {
+      return { name: "pnpm.version", status: "fail", message: "pnpm not on PATH. Install via corepack enable." };
+    }
+  },
+
+  async function dockerProbe({ exec = defaultExec }: ProbeContext) {
+    try {
+      const { stdout } = await exec("docker", ["info", "--format", "{{.ServerVersion}}"]);
+      return { name: "docker.reachable", status: "ok", message: `Docker ${stdout.trim()}` };
+    } catch {
+      return {
+        name: "docker.reachable",
+        status: "warn",
+        message: "Docker not running or not installed. Run `docker compose up -d` for local services.",
+      };
+    }
+  },
+
+  async function postgresProbe({ env, pgPing }: ProbeContext) {
+    const databaseUrl = env.DATABASE_URL ?? env.DIRECT_URL;
+    if (!databaseUrl) {
+      return {
+        name: "postgres.reachable",
+        status: "fail",
+        message: "DATABASE_URL is not set in env. Check your .env file.",
+      };
+    }
+    if (!pgPing) {
+      return {
+        name: "postgres.reachable",
+        status: "warn",
+        message: `pg-ping not wired (env=${maskConnectionUrl(databaseUrl)}). Skipping — supply --probe-pg in CI.`,
+      };
+    }
+    try {
+      await pgPing(databaseUrl);
+      return {
+        name: "postgres.reachable",
+        status: "ok",
+        message: maskConnectionUrl(databaseUrl),
+      };
+    } catch (err) {
+      return {
+        name: "postgres.reachable",
+        status: "fail",
+        message: `Postgres unreachable (${maskConnectionUrl(databaseUrl)}): ${(err as Error).message}`,
+      };
+    }
+  },
+
+  async function redisProbe({ env, redisPing }: ProbeContext) {
+    const redisUrl = env.REDIS_URL;
+    if (!redisUrl) {
+      return {
+        name: "redis.reachable",
+        status: "warn",
+        message: "REDIS_URL not set — assuming local file-store fallback.",
+      };
+    }
+    if (!redisPing) {
+      return {
+        name: "redis.reachable",
+        status: "warn",
+        message: `redis-ping not wired (env=${maskConnectionUrl(redisUrl)}).`,
+      };
+    }
+    try {
+      await redisPing(redisUrl);
+      return { name: "redis.reachable", status: "ok", message: maskConnectionUrl(redisUrl) };
+    } catch (err) {
+      return {
+        name: "redis.reachable",
+        status: "fail",
+        message: `Redis unreachable: ${(err as Error).message}`,
+      };
+    }
+  },
+
+  async function sentryDsnProbe({ env, httpHead = defaultHttpHead }: ProbeContext) {
+    const dsn = env.SENTRY_DSN;
+    if (!dsn) {
+      return { name: "sentry.dsn", status: "warn", message: "SENTRY_DSN not configured — error reporting disabled." };
+    }
+    let origin: string;
+    try {
+      origin = new URL(dsn).origin;
+    } catch {
+      return { name: "sentry.dsn", status: "fail", message: "SENTRY_DSN is not a valid URL." };
+    }
+    try {
+      const { status } = await httpHead(origin, 5_000);
+      if (status === 0 || status >= 500) {
+        return { name: "sentry.dsn", status: "fail", message: `Sentry origin returned ${status} (${origin}).` };
+      }
+      return { name: "sentry.dsn", status: "ok", message: origin };
+    } catch (err) {
+      return {
+        name: "sentry.dsn",
+        status: "fail",
+        message: `Sentry origin unreachable (${origin}): ${(err as Error).message}`,
+      };
+    }
+  },
+
+  async function envCatalogProbe({ env }: ProbeContext) {
+    const required = ["DATABASE_URL", "SESSION_SECRET"];
+    const missing = required.filter((key) => !env[key] || env[key]?.length === 0);
+    if (missing.length === 0) {
+      return { name: "env.required", status: "ok", message: `${required.length} required keys present.` };
+    }
+    return {
+      name: "env.required",
+      status: "fail",
+      message: `Missing required env vars: ${missing.join(", ")}. Update your .env file.`,
+    };
+  },
+
+  async function prismaMigrationProbe({ prismaMigrateStatus }: ProbeContext) {
+    if (!prismaMigrateStatus) {
+      return {
+        name: "prisma.migrations",
+        status: "warn",
+        message: "Skipped — pass --probe-prisma to enable migration-status check.",
+      };
+    }
+    try {
+      const { pending } = await prismaMigrateStatus();
+      if (pending === 0) {
+        return { name: "prisma.migrations", status: "ok", message: "No pending migrations." };
+      }
+      return {
+        name: "prisma.migrations",
+        status: "warn",
+        message: `${pending} pending migration(s). Run \`pnpm db:migrate dev\`.`,
+      };
+    } catch (err) {
+      return {
+        name: "prisma.migrations",
+        status: "fail",
+        message: `prisma migrate status failed: ${(err as Error).message}`,
+      };
+    }
+  },
+];
+
+export interface RunDoctorOptions {
+  readonly env?: EnvBag;
+  readonly probes?: ReadonlyArray<Probe>;
+  readonly ctxExtras?: Partial<ProbeContext>;
+}
+
+export interface DoctorReport {
+  readonly results: ReadonlyArray<ProbeResult>;
+  readonly summary: { ok: number; warn: number; fail: number };
+  readonly exitCode: 0 | 1;
+}
+
+export async function runDoctor(options: RunDoctorOptions = {}): Promise<DoctorReport> {
+  const probes = options.probes ?? PROBES;
+  const env = options.env ?? process.env;
+  const ctx: ProbeContext = { env, ...options.ctxExtras };
+  const results: ProbeResult[] = [];
+  for (const probe of probes) {
+    try {
+      results.push(await probe(ctx));
+    } catch (err) {
+      results.push({
+        name: probe.name || "anonymous-probe",
+        status: "fail",
+        message: `Probe threw: ${(err as Error).message}`,
+      });
+    }
+  }
+  const summary = { ok: 0, warn: 0, fail: 0 };
+  for (const r of results) {
+    summary[r.status] += 1;
+  }
+  return {
+    results,
+    summary,
+    exitCode: summary.fail > 0 ? 1 : 0,
+  };
+}
+
+/** Format the doctor report as a colourless monospaced table for stdout. */
+export function formatDoctorReport(report: DoctorReport): string {
+  const widths = { name: 24, status: 5 };
+  const header = `${"PROBE".padEnd(widths.name)}  ${"STATUS".padEnd(widths.status)}  DETAIL`;
+  const sep = "-".repeat(header.length + 24);
+  const rows = report.results.map((r) => {
+    const symbol = r.status === "ok" ? "ok" : r.status === "warn" ? "warn" : "fail";
+    return `${r.name.padEnd(widths.name)}  ${symbol.padEnd(widths.status)}  ${r.message ?? ""}`;
+  });
+  return [
+    header,
+    sep,
+    ...rows,
+    sep,
+    `summary: ${report.summary.ok} ok, ${report.summary.warn} warn, ${report.summary.fail} fail`,
+  ].join("\n");
+}
+
+export const opsDoctorCommand = defineCommand({
+  meta: {
+    name: "doctor",
+    description: "Health-check local stack (Node/pnpm/Docker/Postgres/Redis/Sentry/env/Prisma migrations).",
+  },
+  args: {
+    env: {
+      type: "string",
+      required: false,
+      description: "Named env file under ~/.toolctrl/envs/<name>.env (default: local .env).",
+    },
+    json: {
+      type: "boolean",
+      required: false,
+      description: "Emit JSON instead of the human-readable table.",
+    },
+  },
+  async run({ args }) {
+    const envName = typeof args.env === "string" && args.env.length > 0 ? args.env : undefined;
+    const resolved = resolveOpsEnv({ name: envName });
+    for (const w of resolved.warnings) consola.warn(w);
+    const report = await runDoctor({ env: resolved.env });
+    if (args.json === true) {
+      consola.log(JSON.stringify({ env: resolved.label, ...report }, null, 2));
+    } else {
+      consola.log(`Running doctor against env=${resolved.label}`);
+      consola.log(formatDoctorReport(report));
+    }
+    if (report.exitCode !== 0) {
+      process.exitCode = 1;
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/ops/impersonate.test.ts

@@ -0,0 +1,149 @@
+import { createHmac } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import {
+  IMPERSONATE_TTL_MINUTES,
+  buildImpersonateUrl,
+  isProductionEnv,
+  runImpersonate,
+  signImpersonateToken,
+  type ImpersonateAuditClient,
+} from "./impersonate.js";
+
+function fakeClient(): { client: ImpersonateAuditClient; lastCall: unknown } {
+  const state: { lastCall: unknown } = { lastCall: undefined };
+  const client: ImpersonateAuditClient = {
+    auditEvent: {
+      async create(args) {
+        state.lastCall = args.data;
+        return { id: "audit-evt-1" };
+      },
+    },
+  };
+  return {
+    client,
+    get lastCall() {
+      return state.lastCall;
+    },
+  } as { client: ImpersonateAuditClient; lastCall: unknown };
+}
+
+describe("signImpersonateToken", () => {
+  it("creates a verifiable HMAC token", () => {
+    const secret = "test-secret-please-rotate-in-prod-min-32-bytes";
+    const now = new Date("2026-05-17T10:00:00.000Z");
+    const out = signImpersonateToken({ userId: "u1", tenantId: "t1", secret, now, tokenId: "abc123" });
+    expect(out.payload.sub).toBe("u1");
+    expect(out.payload.tid).toBe("t1");
+    expect(out.payload.p).toBe("impersonate-debug");
+    expect(out.payload.jti).toBe("abc123");
+    expect(out.expiresAt.toISOString()).toBe("2026-05-17T10:15:00.000Z");
+    const [encoded, sig] = out.token.split(".");
+    const expected = createHmac("sha256", secret).update(encoded!).digest("base64url");
+    expect(sig).toBe(expected);
+  });
+
+  it("rejects short secrets", () => {
+    expect(() => signImpersonateToken({ userId: "u", tenantId: "t", secret: "short" })).toThrow(/secret/iu);
+  });
+
+  it("rejects TTL above 15 minutes", () => {
+    expect(() =>
+      signImpersonateToken({
+        userId: "u",
+        tenantId: "t",
+        secret: "long-enough-secret-for-test",
+        ttlMinutes: 30,
+      }),
+    ).toThrow(/15 minutes/u);
+  });
+
+  it("default TTL matches the public constant", () => {
+    expect(IMPERSONATE_TTL_MINUTES).toBe(15);
+  });
+});
+
+describe("buildImpersonateUrl", () => {
+  it("appends the encoded token to /api/auth/impersonate", () => {
+    expect(buildImpersonateUrl({ baseUrl: "https://stg.example.com/", token: "abc=" })).toBe(
+      "https://stg.example.com/api/auth/impersonate?token=abc%3D",
+    );
+  });
+});
+
+describe("isProductionEnv", () => {
+  it("treats prod/production/live as production", () => {
+    expect(isProductionEnv("prod")).toBe(true);
+    expect(isProductionEnv("Production")).toBe(true);
+    expect(isProductionEnv("LIVE")).toBe(true);
+    expect(isProductionEnv("staging")).toBe(false);
+    expect(isProductionEnv("dev")).toBe(false);
+  });
+});
+
+describe("runImpersonate", () => {
+  const secret = "long-enough-secret-for-impersonate-tests";
+
+  it("blocks production envs hard", async () => {
+    const { client } = fakeClient();
+    await expect(
+      runImpersonate({
+        tenantId: "t",
+        userId: "u",
+        envName: "production",
+        secret,
+        baseUrl: "https://prod.example.com",
+        client,
+      }),
+    ).rejects.toThrow(/forbidden/iu);
+  });
+
+  it("issues a link and writes an audit-event for non-prod envs", async () => {
+    const state = fakeClient();
+    const result = await runImpersonate({
+      tenantId: "tenant-1",
+      userId: "user-1",
+      userEmail: "dev@example.com",
+      envName: "staging",
+      secret,
+      baseUrl: "https://stg.example.com",
+      actorEmail: "engineer@example.com",
+      reason: "support-ticket-123",
+      client: state.client,
+      now: new Date("2026-05-17T10:00:00.000Z"),
+    });
+    expect(result.url).toMatch(/https:\/\/stg\.example\.com\/api\/auth\/impersonate\?token=/u);
+    expect(result.auditEventId).toBe("audit-evt-1");
+    const call = state.lastCall as Record<string, unknown>;
+    expect(call.tenantId).toBe("tenant-1");
+    expect(call.actorType).toBe("admin");
+    expect(call.actorEmail).toBe("engineer@example.com");
+    expect(call.action).toBe("ops.impersonate.issued");
+    expect(call.targetType).toBe("user");
+    expect(call.targetId).toBe("user-1");
+    expect(call.outcome).toBe("success");
+    expect(call.dataSensitivity).toBe("pii");
+    expect(call.regulatoryScope).toEqual(["soc2"]);
+    const meta = call.metadata as Record<string, unknown>;
+    expect(meta.envName).toBe("staging");
+    expect(meta.ttlMinutes).toBe(15);
+    expect(meta.reason).toBe("support-ticket-123");
+    expect(meta.userEmail).toBe("dev@example.com");
+    expect(typeof meta.tokenId).toBe("string");
+  });
+
+  it("metadata.expiresAt is exactly 15 min after now", async () => {
+    const state = fakeClient();
+    const result = await runImpersonate({
+      tenantId: "t",
+      userId: "u",
+      envName: "staging",
+      secret,
+      baseUrl: "https://stg.example.com",
+      client: state.client,
+      now: new Date("2026-05-17T10:00:00.000Z"),
+    });
+    expect(result.token.expiresAt.toISOString()).toBe("2026-05-17T10:15:00.000Z");
+    const meta = (state.lastCall as { metadata: Record<string, unknown> }).metadata;
+    expect(meta.expiresAt).toBe("2026-05-17T10:15:00.000Z");
+  });
+});

hivegrid-cloud/packages/cli/src/commands/ops/impersonate.ts

@@ -0,0 +1,218 @@
+/**
+ * `toolctrl ops impersonate <tenant> <user>`
+ *
+ * Generates a 15-minute, HMAC-signed magic-link the engineer can paste
+ * into a non-production browser to debug a tenant's user account.
+ * Production envs are hard-blocked. Every issued link writes a
+ * tamper-evident audit-event (regulatoryScope=soc2, dataSensitivity=pii,
+ * outcome=success) so the action is reviewable.
+ *
+ * The Prisma client + URL base are dependency-injected — the production
+ * `bin/toolctrl-cli.mjs` wires `@toolctrl/db` + the resolved web origin.
+ *
+ * Refs: docs/improvement-plan/08-mobile-cli-storybook-sdk/cli-ops.md
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { createHmac, randomBytes } from "node:crypto";
+import { resolveOpsEnv, validateEnvName } from "./_env.js";
+
+export const IMPERSONATE_TTL_MINUTES = 15;
+const TOKEN_VERSION = "i1";
+
+export type ImpersonateAuditClient = {
+  auditEvent: {
+    create(args: {
+      data: {
+        tenantId: string | null;
+        actorType: string;
+        actorId: string | null;
+        actorEmail: string | null;
+        action: string;
+        targetType: string | null;
+        targetId: string | null;
+        sourceModule: string | null;
+        outcome: string;
+        dataSensitivity: string;
+        regulatoryScope: string[];
+        metadata: unknown;
+        previousHash?: string | null;
+        eventHash?: string | null;
+      };
+    }): Promise<{ id: string }>;
+  };
+};
+
+export interface ImpersonateTokenPayload {
+  /** Token version. */
+  readonly v: typeof TOKEN_VERSION;
+  /** ISO-8601 expiry. */
+  readonly exp: string;
+  /** ISO-8601 issued-at. */
+  readonly iat: string;
+  /** Random JWT-id. */
+  readonly jti: string;
+  /** Subject — userId. */
+  readonly sub: string;
+  /** Tenant id. */
+  readonly tid: string;
+  /** Purpose discriminator. */
+  readonly p: "impersonate-debug";
+}
+
+export interface SignImpersonateTokenOptions {
+  readonly userId: string;
+  readonly tenantId: string;
+  readonly secret: string;
+  readonly now?: Date;
+  readonly tokenId?: string;
+  readonly ttlMinutes?: number;
+}
+
+export interface SignedImpersonateToken {
+  readonly token: string;
+  readonly tokenId: string;
+  readonly expiresAt: Date;
+  readonly payload: ImpersonateTokenPayload;
+}
+
+function base64UrlEncode(value: string): string {
+  return Buffer.from(value, "utf8").toString("base64url");
+}
+
+export function signImpersonateToken(opts: SignImpersonateTokenOptions): SignedImpersonateToken {
+  if (!opts.secret || opts.secret.length < 16) {
+    throw new Error("Impersonate signing secret missing or too short (>=16 chars required).");
+  }
+  const now = opts.now ?? new Date();
+  const ttlMinutes = opts.ttlMinutes ?? IMPERSONATE_TTL_MINUTES;
+  if (ttlMinutes > IMPERSONATE_TTL_MINUTES) {
+    throw new Error(`Impersonate TTL is capped at ${IMPERSONATE_TTL_MINUTES} minutes (got ${ttlMinutes}).`);
+  }
+  const exp = new Date(now.getTime() + ttlMinutes * 60_000);
+  const tokenId = opts.tokenId ?? randomBytes(16).toString("hex");
+  const payload: ImpersonateTokenPayload = {
+    v: TOKEN_VERSION,
+    iat: now.toISOString(),
+    exp: exp.toISOString(),
+    jti: tokenId,
+    sub: opts.userId,
+    tid: opts.tenantId,
+    p: "impersonate-debug",
+  };
+  const encoded = base64UrlEncode(JSON.stringify(payload));
+  const sig = createHmac("sha256", opts.secret).update(encoded).digest("base64url");
+  return {
+    token: `${encoded}.${sig}`,
+    tokenId,
+    expiresAt: exp,
+    payload,
+  };
+}
+
+export interface BuildImpersonateUrlOptions {
+  readonly baseUrl: string;
+  readonly token: string;
+}
+
+export function buildImpersonateUrl(opts: BuildImpersonateUrlOptions): string {
+  const base = opts.baseUrl.replace(/\/+$/u, "");
+  return `${base}/api/auth/impersonate?token=${encodeURIComponent(opts.token)}`;
+}
+
+export interface RunImpersonateOptions {
+  readonly tenantId: string;
+  readonly userId: string;
+  readonly userEmail?: string;
+  readonly envName: string;
+  readonly secret: string;
+  readonly baseUrl: string;
+  readonly actorEmail?: string | null;
+  readonly reason?: string | null;
+  readonly client: ImpersonateAuditClient;
+  readonly now?: Date;
+}
+
+export interface RunImpersonateResult {
+  readonly url: string;
+  readonly token: SignedImpersonateToken;
+  readonly auditEventId: string;
+}
+
+/** Hard-coded production-name list. The CLI refuses to issue tokens here. */
+export const PRODUCTION_ENV_NAMES: ReadonlyArray<string> = [
+  "prod",
+  "production",
+  "live",
+];
+
+export function isProductionEnv(envName: string): boolean {
+  return PRODUCTION_ENV_NAMES.includes(envName.toLowerCase());
+}
+
+export async function runImpersonate(opts: RunImpersonateOptions): Promise<RunImpersonateResult> {
+  if (isProductionEnv(opts.envName)) {
+    throw new Error(`Production impersonation is forbidden (env=${opts.envName}). Use a staging env or the admin self-service UI.`);
+  }
+  const signed = signImpersonateToken({
+    userId: opts.userId,
+    tenantId: opts.tenantId,
+    secret: opts.secret,
+    now: opts.now,
+  });
+  const url = buildImpersonateUrl({ baseUrl: opts.baseUrl, token: signed.token });
+  const event = await opts.client.auditEvent.create({
+    data: {
+      tenantId: opts.tenantId,
+      actorType: "admin",
+      actorId: null,
+      actorEmail: opts.actorEmail ?? null,
+      action: "ops.impersonate.issued",
+      targetType: "user",
+      targetId: opts.userId,
+      sourceModule: "toolctrl-cli/ops",
+      outcome: "success",
+      dataSensitivity: "pii",
+      regulatoryScope: ["soc2"],
+      metadata: {
+        envName: opts.envName,
+        tokenId: signed.tokenId,
+        expiresAt: signed.expiresAt.toISOString(),
+        ttlMinutes: IMPERSONATE_TTL_MINUTES,
+        reason: opts.reason ?? null,
+        userEmail: opts.userEmail ?? null,
+      },
+    },
+  });
+  return { url, token: signed, auditEventId: event.id };
+}
+
+export const opsImpersonateCommand = defineCommand({
+  meta: {
+    name: "impersonate",
+    description: "Generate a 15-min audit-logged debug magic-link for a tenant user. Production envs are blocked.",
+  },
+  args: {
+    tenant: { type: "positional", required: true, description: "Tenant id." },
+    user: { type: "positional", required: true, description: "User id to impersonate." },
+    env: { type: "string", required: true, description: "Named env (e.g. staging). Production envs are refused." },
+    reason: { type: "string", required: false, description: "Free-form reason recorded in the audit-event." },
+  },
+  async run({ args }) {
+    const envName = String(args.env);
+    validateEnvName(envName);
+    if (isProductionEnv(envName)) {
+      consola.error(`Refusing to impersonate against production env=${envName}.`);
+      process.exitCode = 1;
+      return;
+    }
+    const resolved = resolveOpsEnv({ name: envName });
+    for (const w of resolved.warnings) consola.warn(w);
+    consola.warn(
+      "impersonate requires a Prisma client injection. Wire `runImpersonate({ client, ... })` from the bin entrypoint to actually issue the link.",
+    );
+    consola.info(
+      `Validated args: tenant=${String(args.tenant)} user=${String(args.user)} env=${envName} reason=${String(args.reason ?? "<none>")}`,
+    );
+  },
+});

hivegrid-cloud/packages/cli/src/commands/ops/index.ts

@@ -0,0 +1,26 @@
+/**
+ * `toolctrl ops` — operator subcommand group.
+ *
+ * Children:
+ *   - `doctor`            — local environment health-check
+ *   - `migrate-tenant`    — tenant migration between named envs (uses tenant snapshot infra)
+ *   - `impersonate`       — engineer debug magic-link with audit-event
+ *
+ * Refs: docs/improvement-plan/08-mobile-cli-storybook-sdk/cli-ops.md
+ */
+import { defineCommand } from "citty";
+import { opsDoctorCommand } from "./doctor.js";
+import { opsImpersonateCommand } from "./impersonate.js";
+import { opsMigrateTenantCommand } from "./migrate-tenant.js";
+
+export const opsCommand = defineCommand({
+  meta: {
+    name: "ops",
+    description: "Operator commands: doctor (health), migrate-tenant, impersonate (audit-logged).",
+  },
+  subCommands: {
+    doctor: opsDoctorCommand,
+    "migrate-tenant": opsMigrateTenantCommand,
+    impersonate: opsImpersonateCommand,
+  },
+});

hivegrid-cloud/packages/cli/src/commands/ops/migrate-tenant.test.ts

@@ -0,0 +1,177 @@
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  MIGRATION_STEPS,
+  migrationStatePath,
+  newMigrationState,
+  runMigration,
+  type MigrationRunner,
+  type MigrationState,
+} from "./migrate-tenant.js";
+
+function recordingRunner(overrides: Partial<MigrationRunner> = {}): {
+  runner: MigrationRunner;
+  calls: { export: number; restore: number; verify: number };
+} {
+  const calls = { export: 0, restore: 0, verify: 0 };
+  const runner: MigrationRunner = {
+    async exportSnapshot({ targetPath }) {
+      calls.export += 1;
+      return { archivePath: targetPath };
+    },
+    async restoreSnapshot() {
+      calls.restore += 1;
+      return { rowCount: 42 };
+    },
+    async verifyMigration() {
+      calls.verify += 1;
+      return { matched: true, detail: "ok" };
+    },
+    ...overrides,
+  };
+  return { runner, calls };
+}
+
+describe("migration state helpers", () => {
+  it("newMigrationState seeds every step as pending", () => {
+    const state = newMigrationState({ tenantId: "t1", from: "src", to: "dst" });
+    expect(state.steps.map((s) => s.name)).toEqual([...MIGRATION_STEPS]);
+    expect(state.steps.every((s) => s.status === "pending")).toBe(true);
+  });
+
+  it("migrationStatePath is deterministic per createdAt", () => {
+    const state: MigrationState = newMigrationState({
+      tenantId: "t1",
+      from: "a",
+      to: "b",
+      now: () => new Date("2026-01-02T03:04:05.000Z"),
+    });
+    const p = migrationStatePath(state, "/tmp/x");
+    expect(p).toBe("/tmp/x/t1-2026-01-02T030405000Z.state.json");
+  });
+});
+
+describe("runMigration", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(path.join(tmpdir(), "toolctrl-cli-migrate-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("runs all 5 steps end-to-end against a happy runner", async () => {
+    const { runner, calls } = recordingRunner();
+    const outcome = await runMigration({
+      tenantId: "tenant-1",
+      fromEnv: "staging",
+      toEnv: "prod",
+      runner,
+      stateDir: dir,
+      now: () => new Date("2026-05-17T12:00:00.000Z"),
+    });
+    expect(outcome.success).toBe(true);
+    expect(outcome.state.steps.every((s) => s.status === "ok")).toBe(true);
+    expect(calls).toEqual({ export: 1, restore: 1, verify: 1 });
+    expect(existsSync(outcome.statePath)).toBe(true);
+    const persisted = JSON.parse(readFileSync(outcome.statePath, "utf8")) as MigrationState;
+    expect(persisted.steps.every((s) => s.status === "ok")).toBe(true);
+    expect(persisted.snapshotPath).toBeDefined();
+  });
+
+  it("does not invoke runner when dry-run is set", async () => {
+    const { runner, calls } = recordingRunner();
+    const outcome = await runMigration({
+      tenantId: "t2",
+      fromEnv: "a",
+      toEnv: "b",
+      runner,
+      stateDir: dir,
+      dryRun: true,
+    });
+    expect(outcome.success).toBe(true);
+    expect(calls).toEqual({ export: 0, restore: 0, verify: 0 });
+    // dry-run does not persist
+    expect(existsSync(outcome.statePath)).toBe(false);
+  });
+
+  it("stops and persists fail-state when verify mismatches", async () => {
+    const { runner } = recordingRunner({
+      async verifyMigration() {
+        return { matched: false, detail: "row-count mismatch" };
+      },
+    });
+    const outcome = await runMigration({
+      tenantId: "t3",
+      fromEnv: "a",
+      toEnv: "b",
+      runner,
+      stateDir: dir,
+    });
+    expect(outcome.success).toBe(false);
+    const verify = outcome.state.steps.find((s) => s.name === "verify");
+    expect(verify?.status).toBe("fail");
+    expect(verify?.detail).toBe("row-count mismatch");
+    const cleanup = outcome.state.steps.find((s) => s.name === "cleanup");
+    expect(cleanup?.status).toBe("pending");
+  });
+
+  it("resumes from a partially-completed state file", async () => {
+    const { runner, calls } = recordingRunner();
+    const first = await runMigration({
+      tenantId: "t4",
+      fromEnv: "a",
+      toEnv: "b",
+      runner: {
+        ...runner,
+        async restoreSnapshot() {
+          throw new Error("restore exploded");
+        },
+      },
+      stateDir: dir,
+    });
+    expect(first.success).toBe(false);
+    const restoreStep = first.state.steps.find((s) => s.name === "restore");
+    expect(restoreStep?.status).toBe("fail");
+
+    // Resume — should only call restore + verify (snapshot already ok)
+    const { runner: runner2, calls: calls2 } = recordingRunner();
+    const second = await runMigration({
+      tenantId: "t4",
+      fromEnv: "a",
+      toEnv: "b",
+      runner: runner2,
+      stateDir: dir,
+      resumeFrom: first.statePath,
+    });
+    expect(second.success).toBe(true);
+    // snapshot not re-run because it was already ok
+    expect(calls2.export).toBe(0);
+    expect(calls2.restore).toBe(1);
+    expect(calls2.verify).toBe(1);
+    void calls;
+  });
+
+  it("captures exceptions from runner.exportSnapshot", async () => {
+    const { runner } = recordingRunner({
+      async exportSnapshot() {
+        throw new Error("disk full");
+      },
+    });
+    const outcome = await runMigration({
+      tenantId: "t5",
+      fromEnv: "a",
+      toEnv: "b",
+      runner,
+      stateDir: dir,
+    });
+    expect(outcome.success).toBe(false);
+    const snapStep = outcome.state.steps.find((s) => s.name === "snapshot");
+    expect(snapStep?.status).toBe("fail");
+    expect(snapStep?.detail).toMatch(/disk full/u);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/ops/migrate-tenant.ts

@@ -0,0 +1,282 @@
+/**
+ * `toolctrl ops migrate-tenant <id> --from=<src> --to=<tgt>`
+ *
+ * Resumable orchestrator that drives tenant-snapshot (#44) export against
+ * the source env and a corresponding restore into the target env. State
+ * is persisted to `~/.toolctrl/migrations/<id>-<timestamp>.state.json` so
+ * a crash mid-flight can be resumed via `--resume <state-file>`.
+ *
+ * This command intentionally does not import the heavy tenant-snapshot
+ * implementation directly — the snapshot/restore steps are
+ * dependency-injected so unit tests stay hermetic. The production
+ * entrypoint (`bin/toolctrl-cli.mjs`) wires up the real Prisma runner
+ * and S3 client.
+ *
+ * Refs: docs/improvement-plan/08-mobile-cli-storybook-sdk/cli-ops.md
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { resolveOpsEnv, validateEnvName } from "./_env.js";
+
+export type MigrationStepName = "preflight" | "snapshot" | "restore" | "verify" | "cleanup";
+
+export const MIGRATION_STEPS: ReadonlyArray<MigrationStepName> = [
+  "preflight",
+  "snapshot",
+  "restore",
+  "verify",
+  "cleanup",
+];
+
+export interface MigrationStepRecord {
+  readonly name: MigrationStepName;
+  readonly status: "pending" | "ok" | "fail";
+  readonly startedAt?: string;
+  readonly completedAt?: string;
+  readonly detail?: string;
+}
+
+export interface MigrationState {
+  readonly version: 1;
+  readonly tenantId: string;
+  readonly from: string;
+  readonly to: string;
+  readonly createdAt: string;
+  readonly snapshotPath?: string;
+  readonly steps: ReadonlyArray<MigrationStepRecord>;
+}
+
+export interface MigrationRunner {
+  /** Export a snapshot from the source env. Returns the on-disk path. */
+  exportSnapshot(opts: { tenantId: string; fromEnv: string; targetPath: string }): Promise<{ archivePath: string }>;
+  /** Restore an existing snapshot into the target env. */
+  restoreSnapshot(opts: { tenantId: string; toEnv: string; archivePath: string }): Promise<{ rowCount: number }>;
+  /** Cross-env row-count verification. */
+  verifyMigration(opts: { tenantId: string; fromEnv: string; toEnv: string }): Promise<{ matched: boolean; detail: string }>;
+}
+
+export interface RunMigrationOptions {
+  readonly tenantId: string;
+  readonly fromEnv: string;
+  readonly toEnv: string;
+  readonly runner: MigrationRunner;
+  readonly stateDir?: string;
+  readonly now?: () => Date;
+  readonly resumeFrom?: string;
+  /** Skip writes for dry-runs / tests. */
+  readonly dryRun?: boolean;
+}
+
+export interface MigrationOutcome {
+  readonly statePath: string;
+  readonly state: MigrationState;
+  readonly success: boolean;
+}
+
+export function defaultStateDir(): string {
+  return path.join(homedir(), ".toolctrl", "migrations");
+}
+
+export function newMigrationState(opts: {
+  tenantId: string;
+  from: string;
+  to: string;
+  now?: () => Date;
+}): MigrationState {
+  const now = opts.now ? opts.now() : new Date();
+  return {
+    version: 1,
+    tenantId: opts.tenantId,
+    from: opts.from,
+    to: opts.to,
+    createdAt: now.toISOString(),
+    steps: MIGRATION_STEPS.map((name) => ({ name, status: "pending" })),
+  };
+}
+
+export function migrationStatePath(state: MigrationState, dir = defaultStateDir()): string {
+  const ts = state.createdAt.replace(/[:.]/gu, "");
+  return path.join(dir, `${state.tenantId}-${ts}.state.json`);
+}
+
+export function readMigrationState(filePath: string): MigrationState {
+  const raw = JSON.parse(readFileSync(filePath, "utf8")) as Partial<MigrationState>;
+  if (!raw || raw.version !== 1 || typeof raw.tenantId !== "string") {
+    throw new Error(`Invalid migration state file: ${filePath}`);
+  }
+  return raw as MigrationState;
+}
+
+export function writeMigrationState(filePath: string, state: MigrationState): void {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(state, null, 2));
+}
+
+function updateStep(
+  state: MigrationState,
+  name: MigrationStepName,
+  patch: Partial<MigrationStepRecord>,
+): MigrationState {
+  return {
+    ...state,
+    steps: state.steps.map((s) => (s.name === name ? { ...s, ...patch, name } : s)),
+  };
+}
+
+function withSnapshotPath(state: MigrationState, snapshotPath: string): MigrationState {
+  return { ...state, snapshotPath };
+}
+
+function findNextPendingStep(state: MigrationState): MigrationStepName | null {
+  for (const step of state.steps) {
+    if (step.status !== "ok") return step.name;
+  }
+  return null;
+}
+
+export async function runMigration(options: RunMigrationOptions): Promise<MigrationOutcome> {
+  const stateDir = options.stateDir ?? defaultStateDir();
+  let state = options.resumeFrom
+    ? readMigrationState(options.resumeFrom)
+    : newMigrationState({
+        tenantId: options.tenantId,
+        from: options.fromEnv,
+        to: options.toEnv,
+        now: options.now,
+      });
+  const statePath = options.resumeFrom ?? migrationStatePath(state, stateDir);
+  const now = options.now ?? (() => new Date());
+  const persist = () => {
+    if (!options.dryRun) writeMigrationState(statePath, state);
+  };
+  persist();
+
+  while (true) {
+    const next = findNextPendingStep(state);
+    if (!next) break;
+    state = updateStep(state, next, { status: "pending", startedAt: now().toISOString() });
+    try {
+      if (next === "preflight") {
+        state = updateStep(state, next, {
+          status: "ok",
+          completedAt: now().toISOString(),
+          detail: `from=${state.from} to=${state.to}`,
+        });
+      } else if (next === "snapshot") {
+        const archivePath = path.join(stateDir, `${state.tenantId}-${state.createdAt.replace(/[:.]/gu, "")}.tar.gz`);
+        const result = options.dryRun
+          ? { archivePath }
+          : await options.runner.exportSnapshot({ tenantId: state.tenantId, fromEnv: state.from, targetPath: archivePath });
+        state = withSnapshotPath(state, result.archivePath);
+        state = updateStep(state, next, { status: "ok", completedAt: now().toISOString(), detail: result.archivePath });
+      } else if (next === "restore") {
+        if (!state.snapshotPath) throw new Error("snapshotPath missing in state — cannot restore.");
+        const result = options.dryRun
+          ? { rowCount: 0 }
+          : await options.runner.restoreSnapshot({ tenantId: state.tenantId, toEnv: state.to, archivePath: state.snapshotPath });
+        state = updateStep(state, next, {
+          status: "ok",
+          completedAt: now().toISOString(),
+          detail: `restored ${result.rowCount} rows`,
+        });
+      } else if (next === "verify") {
+        const result = options.dryRun
+          ? { matched: true, detail: "dry-run" }
+          : await options.runner.verifyMigration({ tenantId: state.tenantId, fromEnv: state.from, toEnv: state.to });
+        if (!result.matched) {
+          state = updateStep(state, next, { status: "fail", completedAt: now().toISOString(), detail: result.detail });
+          persist();
+          return { statePath, state, success: false };
+        }
+        state = updateStep(state, next, { status: "ok", completedAt: now().toISOString(), detail: result.detail });
+      } else if (next === "cleanup") {
+        state = updateStep(state, next, {
+          status: "ok",
+          completedAt: now().toISOString(),
+          detail: options.dryRun ? "dry-run (snapshot kept)" : "snapshot kept on disk for audit",
+        });
+      }
+      persist();
+    } catch (err) {
+      state = updateStep(state, next, {
+        status: "fail",
+        completedAt: now().toISOString(),
+        detail: (err as Error).message,
+      });
+      persist();
+      return { statePath, state, success: false };
+    }
+  }
+
+  return { statePath, state, success: true };
+}
+
+export const opsMigrateTenantCommand = defineCommand({
+  meta: {
+    name: "migrate-tenant",
+    description: "Migrate a tenant between named envs (uses tenant-snapshot infra; resumable via state file).",
+  },
+  args: {
+    tenantId: { type: "positional", required: true, description: "Tenant id to migrate." },
+    from: { type: "string", required: true, description: "Source env (named env file or 'local')." },
+    to: { type: "string", required: true, description: "Target env (named env file or 'local')." },
+    "dry-run": {
+      type: "boolean",
+      required: false,
+      description: "Plan the migration without invoking the runner.",
+    },
+    resume: {
+      type: "string",
+      required: false,
+      description: "Path to an existing state file to resume from.",
+    },
+  },
+  async run({ args }) {
+    const tenantId = String(args.tenantId);
+    const from = String(args.from);
+    const to = String(args.to);
+    if (from !== "local") validateEnvName(from);
+    if (to !== "local") validateEnvName(to);
+    if (from === to) {
+      throw new Error(`--from and --to must differ (both='${from}'). Use distinct env names.`);
+    }
+    // Resolve both env files up-front so the operator sees permission warnings.
+    resolveOpsEnv({ name: from === "local" ? undefined : from });
+    resolveOpsEnv({ name: to === "local" ? undefined : to });
+
+    const dryRun = args["dry-run"] === true;
+    consola.info(`Migrating tenant ${tenantId}: ${from} → ${to} (dry-run=${dryRun})`);
+
+    const stubRunner: MigrationRunner = {
+      async exportSnapshot({ targetPath }) {
+        consola.warn("migrate-tenant runner not wired — bin entrypoint must inject a real MigrationRunner.");
+        return { archivePath: targetPath };
+      },
+      async restoreSnapshot() {
+        return { rowCount: 0 };
+      },
+      async verifyMigration() {
+        return { matched: true, detail: "stub runner: no-op verify" };
+      },
+    };
+
+    const outcome = await runMigration({
+      tenantId,
+      fromEnv: from,
+      toEnv: to,
+      runner: stubRunner,
+      dryRun,
+      resumeFrom: typeof args.resume === "string" && args.resume.length > 0 ? args.resume : undefined,
+    });
+    consola.log(`state-file=${outcome.statePath}`);
+    for (const step of outcome.state.steps) {
+      consola.log(`  ${step.name}: ${step.status}${step.detail ? ` — ${step.detail}` : ""}`);
+    }
+    if (!outcome.success) {
+      process.exitCode = 1;
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/outbox/_lib.ts

@@ -0,0 +1,278 @@
+/**
+ * Shared helpers for the `outbox` CLI subtree.
+ *
+ * Both `requeue --event-id` and `requeue --type --since` flow through
+ * the runners defined here so the citty command stays a thin wrapper
+ * with full unit-test coverage on the business logic.
+ *
+ * The terminology mirrors the Prisma OutboxStatus enum (PENDING,
+ * PROCESSING, DONE, FAILED, CANCELLED).
+ */
+
+export type OutboxRequeueStatus = "PENDING" | "PROCESSING" | "DONE" | "FAILED" | "CANCELLED";
+
+/**
+ * Refusable statuses — we never reset an event that's currently being
+ * worked on by the dispatcher (PROCESSING) or that's still waiting in
+ * the queue (PENDING). Doing so would double-deliver the work.
+ */
+export const OUTBOX_REQUEUE_REFUSED_STATUSES: ReadonlySet<OutboxRequeueStatus> = new Set(["PENDING", "PROCESSING"]);
+
+/**
+ * Acceptable statuses for re-queue. DONE is included because the
+ * operator may want to replay a side-effect (e.g. resend a billing
+ * notification email that was lost in the receiver). The CLI emits a
+ * warning for DONE so it's never an accident.
+ */
+export const OUTBOX_REQUEUE_ALLOWED_STATUSES: ReadonlySet<OutboxRequeueStatus> = new Set(["FAILED", "DONE", "CANCELLED"]);
+
+export interface OutboxRequeueEventRow {
+  id: string;
+  eventType: string;
+  status: OutboxRequeueStatus;
+  tenantId: string | null;
+  retries: number;
+  createdAt: Date;
+}
+
+/**
+ * Narrow interface against `@toolctrl/db` — just the methods the
+ * runner uses. Tests inject an in-memory fake.
+ */
+export interface OutboxRequeueClient {
+  outboxEvent: {
+    findUnique(args: { where: { id: string } }): Promise<OutboxRequeueEventRow | null>;
+    update(args: {
+      where: { id: string };
+      data: {
+        status: OutboxRequeueStatus;
+        retries: number;
+        lastError: string | null;
+        scheduledAt: Date;
+        lockedUntil: null;
+        processedAt: null;
+      };
+    }): Promise<OutboxRequeueEventRow>;
+    findMany(args: {
+      where: {
+        eventType: string;
+        createdAt: { gte: Date };
+        status: { in: OutboxRequeueStatus[] };
+      };
+      select: { id: true; eventType: true; status: true; tenantId: true; retries: true; createdAt: true };
+      orderBy: { createdAt: "asc" };
+      take: number;
+    }): Promise<OutboxRequeueEventRow[]>;
+    updateMany(args: {
+      where: { id: { in: string[] } };
+      data: {
+        status: OutboxRequeueStatus;
+        retries: number;
+        lastError: string | null;
+        scheduledAt: Date;
+        lockedUntil: null;
+        processedAt: null;
+      };
+    }): Promise<{ count: number }>;
+  };
+}
+
+export interface OutboxRequeueOutput {
+  log(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  json(payload: unknown): void;
+}
+
+export interface OutboxRequeueByIdArgs {
+  eventId: string;
+  json?: boolean;
+  now?: Date;
+}
+
+export type OutboxRequeueByIdOutcome =
+  | { exitCode: 0; status: "requeued"; eventId: string; previousStatus: OutboxRequeueStatus }
+  | { exitCode: 1; status: "not_found" | "refused"; eventId: string; previousStatus?: OutboxRequeueStatus; message?: string };
+
+function isStatus(value: unknown): value is OutboxRequeueStatus {
+  return typeof value === "string" && ["PENDING", "PROCESSING", "DONE", "FAILED", "CANCELLED"].includes(value);
+}
+
+export function normalizeStatus(value: unknown): OutboxRequeueStatus {
+  if (isStatus(value)) return value;
+  throw new Error(`Unrecognised OutboxStatus value ${JSON.stringify(value)}`);
+}
+
+/**
+ * Re-queue a single event by id. Refuses to act on events that are
+ * currently PENDING or PROCESSING — re-queueing them would double-
+ * deliver the work because the dispatcher still has the original copy
+ * in its pipeline.
+ */
+export async function runOutboxRequeueById(
+  args: OutboxRequeueByIdArgs,
+  deps: { client: OutboxRequeueClient; output: OutboxRequeueOutput }
+): Promise<OutboxRequeueByIdOutcome> {
+  const now = args.now ?? new Date();
+  const existing = await deps.client.outboxEvent.findUnique({ where: { id: args.eventId } });
+  if (!existing) {
+    if (args.json) {
+      deps.output.json({ ok: false, reason: "not_found", eventId: args.eventId });
+    } else {
+      deps.output.error(`outbox event ${args.eventId} not found`);
+    }
+    return { exitCode: 1, status: "not_found", eventId: args.eventId };
+  }
+  const status = normalizeStatus(existing.status);
+  if (OUTBOX_REQUEUE_REFUSED_STATUSES.has(status)) {
+    const message = `outbox event ${args.eventId} is currently ${status}; refuse to re-queue (would double-deliver)`;
+    if (args.json) {
+      deps.output.json({ ok: false, reason: "refused", eventId: args.eventId, status });
+    } else {
+      deps.output.error(message);
+    }
+    return { exitCode: 1, status: "refused", eventId: args.eventId, previousStatus: status, message };
+  }
+  if (!OUTBOX_REQUEUE_ALLOWED_STATUSES.has(status)) {
+    const message = `outbox event ${args.eventId} has unsupported status ${status}`;
+    if (args.json) {
+      deps.output.json({ ok: false, reason: "refused", eventId: args.eventId, status });
+    } else {
+      deps.output.error(message);
+    }
+    return { exitCode: 1, status: "refused", eventId: args.eventId, previousStatus: status, message };
+  }
+
+  if (status === "DONE") {
+    deps.output.warn(`outbox event ${args.eventId} is DONE; re-queueing will replay the side effect`);
+  }
+
+  await deps.client.outboxEvent.update({
+    where: { id: args.eventId },
+    data: {
+      status: "PENDING",
+      retries: 0,
+      lastError: null,
+      scheduledAt: now,
+      lockedUntil: null,
+      processedAt: null,
+    },
+  });
+
+  if (args.json) {
+    deps.output.json({ ok: true, eventId: args.eventId, previousStatus: status });
+  } else {
+    deps.output.log(`outbox event ${args.eventId} re-queued (was ${status})`);
+  }
+  return { exitCode: 0, status: "requeued", eventId: args.eventId, previousStatus: status };
+}
+
+export interface OutboxRequeueBulkArgs {
+  type: string;
+  since: string;
+  /** Optional cap to avoid runaway re-queues. Default 10_000. */
+  limit?: number;
+  /** `true` ⇒ confirm, perform the writes; `false` ⇒ dry-run summary only. */
+  apply?: boolean;
+  /** Include DONE events too. Off by default for safety. */
+  includeDone?: boolean;
+  json?: boolean;
+  now?: Date;
+}
+
+export type OutboxRequeueBulkOutcome = {
+  exitCode: 0 | 1;
+  status: "previewed" | "requeued" | "invalid_args";
+  matched: number;
+  applied: number;
+  eventType: string;
+  since: Date | null;
+  message?: string;
+};
+
+const OUTBOX_REQUEUE_BULK_DEFAULT_LIMIT = 10_000;
+const OUTBOX_EVENT_TYPE_PATTERN = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*){2,}$/u;
+
+export async function runOutboxRequeueBulk(
+  args: OutboxRequeueBulkArgs,
+  deps: { client: OutboxRequeueClient; output: OutboxRequeueOutput }
+): Promise<OutboxRequeueBulkOutcome> {
+  const limit = Math.max(1, Math.min(args.limit ?? OUTBOX_REQUEUE_BULK_DEFAULT_LIMIT, 100_000));
+  if (!OUTBOX_EVENT_TYPE_PATTERN.test(args.type)) {
+    const message = `--type must match <domain>.<entity>.<verb> (got ${JSON.stringify(args.type)})`;
+    if (args.json) {
+      deps.output.json({ ok: false, reason: "invalid_args", message });
+    } else {
+      deps.output.error(message);
+    }
+    return { exitCode: 1, status: "invalid_args", matched: 0, applied: 0, eventType: args.type, since: null, message };
+  }
+  const since = new Date(args.since);
+  if (Number.isNaN(since.getTime())) {
+    const message = `--since must be a valid ISO-8601 timestamp (got ${JSON.stringify(args.since)})`;
+    if (args.json) {
+      deps.output.json({ ok: false, reason: "invalid_args", message });
+    } else {
+      deps.output.error(message);
+    }
+    return { exitCode: 1, status: "invalid_args", matched: 0, applied: 0, eventType: args.type, since: null, message };
+  }
+
+  const statusFilter: OutboxRequeueStatus[] = args.includeDone ? ["FAILED", "DONE", "CANCELLED"] : ["FAILED", "CANCELLED"];
+  const candidates = await deps.client.outboxEvent.findMany({
+    where: {
+      eventType: args.type,
+      createdAt: { gte: since },
+      status: { in: statusFilter },
+    },
+    select: { id: true, eventType: true, status: true, tenantId: true, retries: true, createdAt: true },
+    orderBy: { createdAt: "asc" },
+    take: limit,
+  });
+
+  if (!args.apply) {
+    if (args.json) {
+      deps.output.json({
+        ok: true,
+        applied: 0,
+        matched: candidates.length,
+        eventType: args.type,
+        since: since.toISOString(),
+        preview: candidates.slice(0, 10).map((c) => ({ id: c.id, status: c.status, tenantId: c.tenantId })),
+      });
+    } else {
+      deps.output.log(
+        `outbox requeue (dry-run): ${candidates.length} event(s) matched type=${args.type} since=${since.toISOString()}; pass --apply to perform the re-queue`
+      );
+    }
+    return { exitCode: 0, status: "previewed", matched: candidates.length, applied: 0, eventType: args.type, since };
+  }
+
+  if (candidates.length === 0) {
+    if (args.json) {
+      deps.output.json({ ok: true, applied: 0, matched: 0, eventType: args.type, since: since.toISOString() });
+    } else {
+      deps.output.log(`outbox requeue: no events matched type=${args.type} since=${since.toISOString()}`);
+    }
+    return { exitCode: 0, status: "requeued", matched: 0, applied: 0, eventType: args.type, since };
+  }
+
+  const now = args.now ?? new Date();
+  const result = await deps.client.outboxEvent.updateMany({
+    where: { id: { in: candidates.map((c) => c.id) } },
+    data: {
+      status: "PENDING",
+      retries: 0,
+      lastError: null,
+      scheduledAt: now,
+      lockedUntil: null,
+      processedAt: null,
+    },
+  });
+  if (args.json) {
+    deps.output.json({ ok: true, applied: result.count, matched: candidates.length, eventType: args.type, since: since.toISOString() });
+  } else {
+    deps.output.log(`outbox requeue: ${result.count} event(s) re-queued (type=${args.type} since=${since.toISOString()})`);
+  }
+  return { exitCode: 0, status: "requeued", matched: candidates.length, applied: result.count, eventType: args.type, since };
+}

hivegrid-cloud/packages/cli/src/commands/outbox/index.ts

@@ -0,0 +1,15 @@
+import { defineCommand } from "citty";
+
+import { outboxRequeueCommand } from "./requeue.js";
+
+export const outboxCommand = defineCommand({
+  meta: {
+    name: "outbox",
+    description: "Operator commands for the transactional outbox (re-queue failed events, bulk replay).",
+  },
+  subCommands: {
+    requeue: outboxRequeueCommand,
+  },
+});
+
+export { outboxRequeueCommand };

hivegrid-cloud/packages/cli/src/commands/outbox/requeue.test.ts

@@ -0,0 +1,336 @@
+import { describe, it, expect, vi } from "vitest";
+
+import {
+  normalizeStatus,
+  runOutboxRequeueById,
+  runOutboxRequeueBulk,
+  type OutboxRequeueClient,
+  type OutboxRequeueEventRow,
+  type OutboxRequeueOutput,
+  type OutboxRequeueStatus,
+} from "./_lib.js";
+
+describe("normalizeStatus", () => {
+  it("throws on unknown database enum values", () => {
+    expect(() => normalizeStatus("ARCHIVED")).toThrow(/Unrecognised OutboxStatus/);
+  });
+});
+
+interface FakeState {
+  byId: Map<string, OutboxRequeueEventRow>;
+  updates: Array<{ id: string; data: Record<string, unknown> }>;
+  updateMany: Array<{ ids: string[]; data: Record<string, unknown> }>;
+}
+
+function fakeClient(state: FakeState): OutboxRequeueClient {
+  return {
+    outboxEvent: {
+      async findUnique({ where }) {
+        return state.byId.get(where.id) ?? null;
+      },
+      async update({ where, data }) {
+        const row = state.byId.get(where.id);
+        if (!row) throw new Error(`no row ${where.id}`);
+        const next: OutboxRequeueEventRow = { ...row, status: data.status, retries: data.retries };
+        state.byId.set(where.id, next);
+        state.updates.push({ id: where.id, data: data as unknown as Record<string, unknown> });
+        return next;
+      },
+      async findMany({ where, take }) {
+        const all = Array.from(state.byId.values())
+          .filter((r) => r.eventType === where.eventType && r.createdAt >= where.createdAt.gte && where.status.in.includes(r.status))
+          .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+          .slice(0, take);
+        return all;
+      },
+      async updateMany({ where, data }) {
+        let count = 0;
+        for (const id of where.id.in) {
+          const row = state.byId.get(id);
+          if (row) {
+            state.byId.set(id, { ...row, status: data.status, retries: data.retries });
+            count += 1;
+          }
+        }
+        state.updateMany.push({ ids: where.id.in, data: data as unknown as Record<string, unknown> });
+        return { count };
+      },
+    },
+  };
+}
+
+function makeOutput(): OutboxRequeueOutput & { logs: string[]; warns: string[]; errors: string[]; jsons: unknown[] } {
+  const out = {
+    logs: [] as string[],
+    warns: [] as string[],
+    errors: [] as string[],
+    jsons: [] as unknown[],
+    log(msg: string) {
+      out.logs.push(msg);
+    },
+    warn(msg: string) {
+      out.warns.push(msg);
+    },
+    error(msg: string) {
+      out.errors.push(msg);
+    },
+    json(payload: unknown) {
+      out.jsons.push(payload);
+    },
+  };
+  return out;
+}
+
+function row(id: string, overrides: Partial<OutboxRequeueEventRow> = {}): OutboxRequeueEventRow {
+  return {
+    id,
+    eventType: "billing.subscription.ended",
+    status: "FAILED",
+    tenantId: "tenant-1",
+    retries: 3,
+    createdAt: new Date("2026-05-20T08:00:00Z"),
+    ...overrides,
+  };
+}
+
+describe("runOutboxRequeueById", () => {
+  it("re-queues a FAILED event and resets retry counters", async () => {
+    const state: FakeState = {
+      byId: new Map([["evt-1", row("evt-1", { status: "FAILED", retries: 5 })]]),
+      updates: [],
+      updateMany: [],
+    };
+    const output = makeOutput();
+    const outcome = await runOutboxRequeueById({ eventId: "evt-1", now: new Date("2026-05-25T00:00:00Z") }, { client: fakeClient(state), output });
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.status).toBe("requeued");
+    expect(state.updates).toHaveLength(1);
+    const update = state.updates[0]!.data as { status: OutboxRequeueStatus; retries: number; lastError: string | null };
+    expect(update.status).toBe("PENDING");
+    expect(update.retries).toBe(0);
+    expect(update.lastError).toBeNull();
+    expect(output.logs.some((m) => m.includes("re-queued"))).toBe(true);
+  });
+
+  it("emits JSON when --json is set", async () => {
+    const state: FakeState = {
+      byId: new Map([["evt-2", row("evt-2", { status: "FAILED" })]]),
+      updates: [],
+      updateMany: [],
+    };
+    const output = makeOutput();
+    await runOutboxRequeueById({ eventId: "evt-2", json: true }, { client: fakeClient(state), output });
+    expect(output.jsons[0]).toEqual({ ok: true, eventId: "evt-2", previousStatus: "FAILED" });
+    expect(output.logs).toEqual([]);
+  });
+
+  it("refuses to re-queue events still in PENDING", async () => {
+    const state: FakeState = {
+      byId: new Map([["evt-3", row("evt-3", { status: "PENDING" })]]),
+      updates: [],
+      updateMany: [],
+    };
+    const output = makeOutput();
+    const outcome = await runOutboxRequeueById({ eventId: "evt-3" }, { client: fakeClient(state), output });
+    expect(outcome.exitCode).toBe(1);
+    expect(outcome.status).toBe("refused");
+    expect(state.updates).toEqual([]);
+    expect(output.errors[0]).toMatch(/refuse to re-queue/);
+  });
+
+  it("refuses to re-queue events currently PROCESSING", async () => {
+    const state: FakeState = {
+      byId: new Map([["evt-4", row("evt-4", { status: "PROCESSING" })]]),
+      updates: [],
+      updateMany: [],
+    };
+    const output = makeOutput();
+    const outcome = await runOutboxRequeueById({ eventId: "evt-4" }, { client: fakeClient(state), output });
+    expect(outcome.exitCode).toBe(1);
+    expect(state.updates).toEqual([]);
+  });
+
+  it("re-queues DONE events but warns the operator", async () => {
+    const state: FakeState = {
+      byId: new Map([["evt-5", row("evt-5", { status: "DONE", retries: 0 })]]),
+      updates: [],
+      updateMany: [],
+    };
+    const output = makeOutput();
+    const outcome = await runOutboxRequeueById({ eventId: "evt-5" }, { client: fakeClient(state), output });
+    expect(outcome.exitCode).toBe(0);
+    expect(state.updates).toHaveLength(1);
+    expect(output.warns[0]).toMatch(/will replay/);
+  });
+
+  it("returns not_found when the event does not exist", async () => {
+    const state: FakeState = { byId: new Map(), updates: [], updateMany: [] };
+    const output = makeOutput();
+    const outcome = await runOutboxRequeueById({ eventId: "ghost" }, { client: fakeClient(state), output });
+    expect(outcome.exitCode).toBe(1);
+    expect(outcome.status).toBe("not_found");
+    expect(output.errors[0]).toMatch(/not found/);
+  });
+
+  it("emits JSON for not_found lookups when --json is set", async () => {
+    const state: FakeState = { byId: new Map(), updates: [], updateMany: [] };
+    const output = makeOutput();
+    const outcome = await runOutboxRequeueById({ eventId: "ghost", json: true }, { client: fakeClient(state), output });
+    expect(outcome.status).toBe("not_found");
+    expect(output.jsons[0]).toEqual({ ok: false, reason: "not_found", eventId: "ghost" });
+    expect(output.errors).toEqual([]);
+  });
+});
+
+describe("runOutboxRequeueBulk", () => {
+  function bulkState(): FakeState {
+    return {
+      byId: new Map([
+        ["a", row("a", { status: "FAILED", createdAt: new Date("2026-05-21T00:00:00Z") })],
+        ["b", row("b", { status: "FAILED", createdAt: new Date("2026-05-22T00:00:00Z") })],
+        ["c", row("c", { status: "DONE", createdAt: new Date("2026-05-22T00:00:00Z") })],
+        ["d", row("d", { status: "PENDING", createdAt: new Date("2026-05-22T00:00:00Z") })],
+        ["e", row("e", { status: "FAILED", createdAt: new Date("2026-05-19T00:00:00Z") })],
+        ["f", row("f", { eventType: "billing.subscription.cancelled", status: "FAILED", createdAt: new Date("2026-05-22T00:00:00Z") })],
+      ]),
+      updates: [],
+      updateMany: [],
+    };
+  }
+
+  it("previews matched count without writing when --apply is omitted", async () => {
+    const state = bulkState();
+    const output = makeOutput();
+    const outcome = await runOutboxRequeueBulk({ type: "billing.subscription.ended", since: "2026-05-20T00:00:00Z" }, { client: fakeClient(state), output });
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.status).toBe("previewed");
+    expect(outcome.matched).toBe(2);
+    expect(outcome.applied).toBe(0);
+    expect(state.updateMany).toEqual([]);
+    expect(output.logs[0]).toMatch(/dry-run/);
+  });
+
+  it("re-queues matching events when --apply is set", async () => {
+    const state = bulkState();
+    const output = makeOutput();
+    const outcome = await runOutboxRequeueBulk(
+      { type: "billing.subscription.ended", since: "2026-05-20T00:00:00Z", apply: true, now: new Date("2026-05-25T00:00:00Z") },
+      { client: fakeClient(state), output }
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.status).toBe("requeued");
+    expect(outcome.applied).toBe(2);
+    expect(state.updateMany).toHaveLength(1);
+    // FAILED rows a + b should have flipped to PENDING.
+    expect(state.byId.get("a")?.status).toBe("PENDING");
+    expect(state.byId.get("b")?.status).toBe("PENDING");
+    expect(state.byId.get("c")?.status).toBe("DONE");
+    expect(state.byId.get("d")?.status).toBe("PENDING"); // already pending, untouched
+  });
+
+  it("includes DONE events when --include-done is set", async () => {
+    const state = bulkState();
+    const output = makeOutput();
+    const outcome = await runOutboxRequeueBulk(
+      { type: "billing.subscription.ended", since: "2026-05-20T00:00:00Z", apply: true, includeDone: true },
+      { client: fakeClient(state), output }
+    );
+    expect(outcome.applied).toBe(3);
+    expect(state.byId.get("c")?.status).toBe("PENDING");
+  });
+
+  it("rejects malformed event type", async () => {
+    const state = bulkState();
+    const output = makeOutput();
+    const outcome = await runOutboxRequeueBulk({ type: "notavalidtype", since: "2026-05-20T00:00:00Z" }, { client: fakeClient(state), output });
+    expect(outcome.exitCode).toBe(1);
+    expect(outcome.status).toBe("invalid_args");
+    expect(output.errors[0]).toMatch(/must match/);
+  });
+
+  it("rejects malformed --since", async () => {
+    const state = bulkState();
+    const output = makeOutput();
+    const outcome = await runOutboxRequeueBulk({ type: "billing.subscription.ended", since: "not-a-date" }, { client: fakeClient(state), output });
+    expect(outcome.exitCode).toBe(1);
+    expect(outcome.status).toBe("invalid_args");
+    expect(output.errors[0]).toMatch(/ISO-8601/);
+  });
+
+  it("emits JSON when --json is set", async () => {
+    const state = bulkState();
+    const output = makeOutput();
+    await runOutboxRequeueBulk(
+      { type: "billing.subscription.ended", since: "2026-05-20T00:00:00Z", apply: true, json: true },
+      { client: fakeClient(state), output }
+    );
+    expect(output.jsons[0]).toMatchObject({ ok: true, applied: 2, matched: 2, eventType: "billing.subscription.ended" });
+  });
+
+  it("caps dry-run JSON previews at 10 rows", async () => {
+    const state: FakeState = {
+      byId: new Map(
+        Array.from({ length: 12 }, (_, index) => {
+          const id = `evt-${index + 1}`;
+          return [id, row(id, { createdAt: new Date(`2026-05-${String(index + 1).padStart(2, "0")}T00:00:00Z`) })];
+        })
+      ),
+      updates: [],
+      updateMany: [],
+    };
+    const output = makeOutput();
+
+    await runOutboxRequeueBulk({ type: "billing.subscription.ended", since: "2026-05-01T00:00:00Z", json: true }, { client: fakeClient(state), output });
+
+    expect(output.jsons[0]).toMatchObject({ ok: true, applied: 0, matched: 12 });
+    expect((output.jsons[0] as { preview: unknown[] }).preview).toHaveLength(10);
+    expect(state.updateMany).toEqual([]);
+  });
+
+  it("returns matched=0 cleanly when no events match", async () => {
+    const state = bulkState();
+    const output = makeOutput();
+    const outcome = await runOutboxRequeueBulk(
+      { type: "billing.subscription.ended", since: "2030-01-01T00:00:00Z", apply: true },
+      { client: fakeClient(state), output }
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.matched).toBe(0);
+    expect(outcome.applied).toBe(0);
+  });
+});
+
+describe("outboxRequeueCommand argument handling", () => {
+  it("is wired into the CLI subtree", async () => {
+    const mod = await import("./index.js");
+    expect(mod.outboxCommand).toBeDefined();
+    expect(typeof mod.outboxRequeueCommand.run).toBe("function");
+  });
+});
+
+describe("OutboxRequeueClient narrowness", () => {
+  it("only requires the four methods the runner consumes", () => {
+    // This is a structural-typing sanity check: a client with extra
+    // fields is still acceptable, but missing one of the four methods
+    // must be a type error. The test is intentionally compile-time
+    // adjacent; we keep one runtime assertion to keep vitest happy.
+    const minimal: OutboxRequeueClient = {
+      outboxEvent: {
+        findUnique: vi.fn(async () => null),
+        update: vi.fn(
+          async (): Promise<OutboxRequeueEventRow> => ({
+            id: "x",
+            eventType: "y.y.y",
+            status: "PENDING" as OutboxRequeueStatus,
+            tenantId: null,
+            retries: 0,
+            createdAt: new Date(),
+          })
+        ),
+        findMany: vi.fn(async () => []),
+        updateMany: vi.fn(async () => ({ count: 0 })),
+      },
+    };
+    expect(Object.keys(minimal.outboxEvent)).toHaveLength(4);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/outbox/requeue.ts

@@ -0,0 +1,135 @@
+/**
+ * `toolctrl-cli outbox requeue` — re-queue failed (or dead-letter) outbox
+ * events back into the dispatcher's pending pool.
+ *
+ * Two modes:
+ *   - `--event-id <id>`: single-event re-queue. Refuses to act on
+ *     events whose current status is PENDING or PROCESSING (those are
+ *     still in flight; resetting them double-delivers).
+ *   - `--type <eventType> --since <ISO-timestamp>`: bulk re-queue. By
+ *     default this is a dry-run (count + small preview); pass `--apply`
+ *     to perform the writes.
+ *
+ * Output: human summary by default, JSON when `--json` is set. The CLI
+ * uses `@toolctrl/db` directly so the worker process does not need to
+ * be reachable.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+
+import {
+  runOutboxRequeueById,
+  runOutboxRequeueBulk,
+  type OutboxRequeueClient,
+  type OutboxRequeueOutput,
+} from "./_lib.js";
+
+function makeOutput(json: boolean): OutboxRequeueOutput {
+  return {
+    log: (msg) => (json ? undefined : consola.success(msg)),
+    warn: (msg) => consola.warn(msg),
+    error: (msg) => (json ? undefined : consola.error(msg)),
+    json: (payload) => consola.log(JSON.stringify(payload)),
+  };
+}
+
+export const outboxRequeueCommand = defineCommand({
+  meta: {
+    name: "requeue",
+    description: "Re-queue a single FAILED/DONE outbox event by id, or bulk-re-queue by eventType + since timestamp.",
+  },
+  args: {
+    "event-id": {
+      type: "string",
+      required: false,
+      description: "Single-event mode: outbox event id to re-queue.",
+    },
+    type: {
+      type: "string",
+      required: false,
+      description: "Bulk mode: event type to re-queue (must include all three segments, e.g. 'billing.subscription.ended').",
+    },
+    since: {
+      type: "string",
+      required: false,
+      description: "Bulk mode: ISO-8601 lower bound on createdAt.",
+    },
+    apply: {
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Bulk mode only: perform the write (default is a dry-run preview).",
+    },
+    "include-done": {
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Bulk mode: include DONE events too (default is FAILED + CANCELLED only).",
+    },
+    limit: {
+      type: "string",
+      required: false,
+      description: "Bulk mode: cap on rows considered (default 10000).",
+    },
+    json: {
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Emit JSON instead of human-readable output.",
+    },
+  },
+  async run({ args }) {
+    const json = Boolean(args.json);
+    const eventId = typeof args["event-id"] === "string" && args["event-id"].length > 0 ? args["event-id"] : null;
+    const typeArg = typeof args.type === "string" && args.type.length > 0 ? args.type : null;
+    const sinceArg = typeof args.since === "string" && args.since.length > 0 ? args.since : null;
+
+    if (eventId && (typeArg || sinceArg)) {
+      consola.error("Pass --event-id OR (--type + --since), not both.");
+      process.exitCode = 1;
+      return;
+    }
+    if (!eventId && (!typeArg || !sinceArg)) {
+      consola.error("Either --event-id or (--type + --since) is required.");
+      process.exitCode = 1;
+      return;
+    }
+
+    const { getDbClient } = await import("@toolctrl/db/client.server");
+    const prisma = getDbClient() as unknown as OutboxRequeueClient;
+    const output = makeOutput(json);
+
+    try {
+      if (eventId) {
+        const outcome = await runOutboxRequeueById(
+          { eventId, json },
+          { client: prisma, output }
+        );
+        process.exitCode = outcome.exitCode;
+        return;
+      }
+
+      const limit = typeof args.limit === "string" && args.limit.length > 0 ? Number.parseInt(args.limit, 10) : undefined;
+      const outcome = await runOutboxRequeueBulk(
+        {
+          type: typeArg!,
+          since: sinceArg!,
+          apply: Boolean(args.apply),
+          includeDone: Boolean(args["include-done"]),
+          ...(typeof limit === "number" && Number.isFinite(limit) ? { limit } : {}),
+          json,
+        },
+        { client: prisma, output }
+      );
+      process.exitCode = outcome.exitCode;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (json) {
+        output.json({ ok: false, reason: "exception", message });
+      } else {
+        consola.error(`outbox requeue failed: ${message}`);
+      }
+      process.exitCode = 1;
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/plugins/build.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "vitest";
+import { buildCommandForToolchain, detectToolchain } from "./build.js";
+
+function fakeIo(files: Record<string, string>) {
+  return {
+    cwd: "/p",
+    async readFile(path: string) {
+      const key = path.replace(/^\/p\//u, "");
+      const value = files[key];
+      if (value === undefined) throw new Error(`ENOENT: ${path}`);
+      return value;
+    },
+    async exists(path: string) {
+      const key = path.replace(/^\/p\//u, "");
+      return Object.prototype.hasOwnProperty.call(files, key);
+    },
+  };
+}
+
+describe("detectToolchain", () => {
+  test("detects AssemblyScript via asconfig.json", async () => {
+    expect(await detectToolchain(fakeIo({ "asconfig.json": "{}" }))).toBe("assemblyscript");
+  });
+  test("detects AssemblyScript via package.json dep when asconfig.json missing", async () => {
+    expect(await detectToolchain(fakeIo({ "package.json": JSON.stringify({ devDependencies: { assemblyscript: "0.27.0" } }) }))).toBe("assemblyscript");
+  });
+  test("detects AssemblyScript from dependencies, not only devDependencies", async () => {
+    expect(await detectToolchain(fakeIo({ "package.json": JSON.stringify({ dependencies: { assemblyscript: "0.27.0" } }) }))).toBe("assemblyscript");
+  });
+  test("detects TinyGo via go.mod", async () => {
+    expect(await detectToolchain(fakeIo({ "go.mod": "module x" }))).toBe("tinygo");
+  });
+  test("detects Rust via Cargo.toml", async () => {
+    expect(await detectToolchain(fakeIo({ "Cargo.toml": "[package]" }))).toBe("rust-cargo");
+  });
+  test("unknown when no marker present", async () => {
+    expect(await detectToolchain(fakeIo({}))).toBe("unknown");
+  });
+  test("unknown when package.json has no AS dep", async () => {
+    expect(await detectToolchain(fakeIo({ "package.json": JSON.stringify({ devDependencies: { rollup: "1" } }) }))).toBe("unknown");
+  });
+  test("unknown when package.json is malformed", async () => {
+    expect(await detectToolchain(fakeIo({ "package.json": "{" }))).toBe("unknown");
+  });
+});
+
+describe("buildCommandForToolchain", () => {
+  test("AS command uses asc with --target release", () => {
+    const { command } = buildCommandForToolchain("assemblyscript", { output: "out.wasm" });
+    expect(command).toContain("asc");
+    expect(command).toContain("--target release");
+    expect(command).toContain("out.wasm");
+  });
+  test("Rust command builds wasm32-wasi target", () => {
+    const { command } = buildCommandForToolchain("rust-cargo", { output: "plugin.wasm" });
+    expect(command).toContain("wasm32-wasi");
+  });
+  test("TinyGo command uses wasi target", () => {
+    const { command } = buildCommandForToolchain("tinygo", { output: "plugin.wasm" });
+    expect(command).toContain("tinygo");
+    expect(command).toContain("wasi");
+  });
+  test("unknown command points to docs", () => {
+    const { command, description } = buildCommandForToolchain("unknown", { output: "plugin.wasm" });
+    expect(command).toContain("docs/plugins");
+    expect(description).toContain("No toolchain marker");
+  });
+});

hivegrid-cloud/packages/cli/src/commands/plugins/build.ts

@@ -0,0 +1,119 @@
+/**
+ * `plugins build` — Phase 06 #23 — orchestrate the wasm build.
+ *
+ * The actual ts→wasm compilation is operator-toolchain-specific (the
+ * supported chains today are AssemblyScript via `asc`, TinyGo via
+ * `tinygo build -target=wasi`, and Rust via `cargo build --target
+ * wasm32-wasi`). The CLI is intentionally pure orchestration: it
+ * detects which toolchain the plugin is using by reading its
+ * package.json / Cargo.toml / asconfig.json and prints the canonical
+ * build command to run. When no toolchain marker is found, the command
+ * surfaces a clear next-step rather than guessing.
+ *
+ * Why no auto-exec: spawning a heterogeneous compiler chain from this
+ * CLI silently hides errors and surprises authors with global-binary
+ * dependencies. Printing the command keeps the build path transparent
+ * and lets CI scripts wire it in their own way.
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { readFile, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+export type DetectedToolchain = "assemblyscript" | "tinygo" | "rust-cargo" | "unknown";
+
+export interface DetectToolchainInput {
+  readonly cwd: string;
+  readonly readFile: (p: string) => Promise<string>;
+  readonly exists: (p: string) => Promise<boolean>;
+}
+
+export async function detectToolchain(input: DetectToolchainInput): Promise<DetectedToolchain> {
+  if (await input.exists(join(input.cwd, "asconfig.json"))) {
+    return "assemblyscript";
+  }
+  if (await input.exists(join(input.cwd, "Cargo.toml"))) {
+    return "rust-cargo";
+  }
+  if (await input.exists(join(input.cwd, "go.mod"))) {
+    return "tinygo";
+  }
+  // Also accept package.json with AS / wasi deps.
+  if (await input.exists(join(input.cwd, "package.json"))) {
+    try {
+      const pkg = JSON.parse(await input.readFile(join(input.cwd, "package.json"))) as Record<string, unknown>;
+      const deps = {
+        ...((pkg.dependencies as Record<string, string> | undefined) ?? {}),
+        ...((pkg.devDependencies as Record<string, string> | undefined) ?? {}),
+      };
+      if (typeof deps["assemblyscript"] === "string") {
+        return "assemblyscript";
+      }
+    } catch {
+      // Fall through to unknown.
+    }
+  }
+  return "unknown";
+}
+
+export function buildCommandForToolchain(
+  toolchain: DetectedToolchain,
+  options: { output: string }
+): { command: string; description: string } {
+  switch (toolchain) {
+    case "assemblyscript":
+      return {
+        command: `npx asc src/index.ts --target release --outFile ${options.output}`,
+        description: "AssemblyScript via `asc` (release target).",
+      };
+    case "tinygo":
+      return {
+        command: `tinygo build -target=wasi -o ${options.output} ./...`,
+        description: "TinyGo with the wasi target.",
+      };
+    case "rust-cargo":
+      return {
+        command: `cargo build --release --target wasm32-wasi && cp target/wasm32-wasi/release/*.wasm ${options.output}`,
+        description: "Rust via cargo + wasm32-wasi target.",
+      };
+    case "unknown":
+    default:
+      return {
+        command: "<install a wasm toolchain — see docs/plugins/cli-reference.md#build>",
+        description: "No toolchain marker (asconfig.json / Cargo.toml / go.mod) detected.",
+      };
+  }
+}
+
+export const pluginsBuildCommand = defineCommand({
+  meta: {
+    name: "build",
+    description: "Detect the plugin's wasm toolchain and print the canonical build command.",
+  },
+  args: {
+    cwd: { type: "string", description: "Plugin source directory (default: process cwd)." },
+    output: { type: "string", description: "Output wasm filename (default: plugin.wasm)." },
+  },
+  async run({ args }) {
+    const cwd = args.cwd ? resolve(String(args.cwd)) : process.cwd();
+    const output = args.output ? String(args.output) : "plugin.wasm";
+    const toolchain = await detectToolchain({
+      cwd,
+      readFile: async (p) => await readFile(p, "utf8"),
+      exists: async (p) => {
+        try {
+          await stat(p);
+          return true;
+        } catch {
+          return false;
+        }
+      },
+    });
+    const { command, description } = buildCommandForToolchain(toolchain, { output });
+    consola.info(`Detected toolchain: ${toolchain} (${description})`);
+    consola.log(command);
+    if (toolchain === "unknown") {
+      process.exitCode = 1;
+    }
+  },
+});

hivegrid-cloud/packages/cli/src/commands/plugins/index.test.ts

@@ -0,0 +1,318 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+type PluginCliMocks = {
+  db: {
+    plugin: {
+      findUnique: ReturnType<typeof vi.fn>;
+      update: ReturnType<typeof vi.fn>;
+      delete: ReturnType<typeof vi.fn>;
+    };
+    tenantPluginCapabilityGrant: {
+      findMany: ReturnType<typeof vi.fn>;
+    };
+    $transaction: ReturnType<typeof vi.fn>;
+  };
+  publishAuditEventViaOutbox: ReturnType<typeof vi.fn>;
+};
+
+const originalNodeEnv = process.env.NODE_ENV;
+
+function getPluginCliMocks(): PluginCliMocks {
+  const global = globalThis as typeof globalThis & { __pluginCliMocks__?: PluginCliMocks };
+  global.__pluginCliMocks__ ??= {
+    db: {
+      plugin: {
+        findUnique: vi.fn(),
+        update: vi.fn(),
+        delete: vi.fn(),
+      },
+      tenantPluginCapabilityGrant: {
+        findMany: vi.fn(),
+      },
+      $transaction: vi.fn(async (fn: (tx: PluginCliMocks["db"]) => Promise<unknown>) => await fn(getPluginCliMocks().db)),
+    },
+    publishAuditEventViaOutbox: vi.fn(),
+  };
+  return global.__pluginCliMocks__;
+}
+
+vi.mock("@toolctrl/db/client.server", () => ({
+  getDbClient: () => getPluginCliMocks().db,
+}));
+vi.mock("@toolctrl/db/audit-events.server", () => ({
+  publishAuditEventViaOutbox: getPluginCliMocks().publishAuditEventViaOutbox,
+}));
+vi.mock("consola", () => ({
+  default: {
+    error: vi.fn(),
+    info: vi.fn(),
+    prompt: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+
+import consola from "consola";
+import { stampPluginCapabilityUseChain, verifyPluginCapabilityUseChain, type PluginCapabilityUseChainRow } from "@toolctrl/plugin-runtime";
+import { pluginsCommand } from "./index.js";
+import { pluginsEnableCommand } from "./toggle.js";
+import { pluginsUninstallCommand } from "./uninstall.js";
+import { runPluginsVerifyAuditChain, type PluginCapabilityUseChainStoredRow } from "./verify-audit-chain.js";
+
+const mocks = getPluginCliMocks();
+const consoleMock = vi.mocked(consola);
+
+describe("plugins CLI", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.exitCode = undefined;
+    process.env.NODE_ENV = originalNodeEnv;
+    delete process.env.PLUGIN_REQUIRE_CAPABILITY_CONSENT;
+    delete process.env.PLUGIN_RUNTIME_PRODUCTION_ENABLED;
+    mocks.db.$transaction.mockImplementation(async (fn: (tx: PluginCliMocks["db"]) => Promise<unknown>) => await fn(mocks.db));
+  });
+
+  test("exposes operator + author subcommands", async () => {
+    const subs = pluginsCommand.subCommands as Record<string, { meta: { name: string } | (() => { name: string }) } | undefined>;
+    const keys = Object.keys(subs);
+    expect(keys).toContain("list");
+    expect(keys).toContain("enable");
+    expect(keys).toContain("disable");
+    expect(keys).toContain("uninstall");
+    expect(keys).toContain("verify-audit-chain");
+    expect(keys).toContain("scaffold");
+  });
+
+  test("plugins verify-audit-chain verifies the full tenant capability-use chain", async () => {
+    const rows = stampedPluginCapabilityRows([
+      pluginCapabilityRow({ id: "row_1", pluginId: "com.acme.crm" }),
+      pluginCapabilityRow({ id: "row_2", pluginId: "com.acme.slack" }),
+    ]);
+    const output = outputCollector();
+
+    await expect(
+      runPluginsVerifyAuditChain(
+        { tenantId: "tenant_1", pluginId: "com.acme.crm" },
+        {
+          readRows: async function* () {
+            yield* rows;
+          },
+          verify: verifyPluginCapabilityUseChain,
+          output,
+        }
+      )
+    ).resolves.toEqual({
+      exitCode: 0,
+      matchingPluginRows: 1,
+      ok: true,
+      rowCount: 2,
+    });
+
+    expect(output.info).toHaveBeenCalledWith(expect.stringContaining("matchingPluginRows=1"));
+  });
+
+  test("plugins verify-audit-chain reports the first tampered capability-use row", async () => {
+    const rows = stampedPluginCapabilityRows([
+      pluginCapabilityRow({ id: "row_1" }),
+      pluginCapabilityRow({ id: "row_2" }),
+    ]);
+    const tampered = rows.map((row) => (row.id === "row_2" ? { ...row, outcome: "denied" } : row));
+    const output = outputCollector();
+
+    await expect(
+      runPluginsVerifyAuditChain(
+        { tenantId: "tenant_1" },
+        {
+          readRows: async function* () {
+            yield* tampered;
+          },
+          verify: verifyPluginCapabilityUseChain,
+          output,
+        }
+      )
+    ).resolves.toMatchObject({
+      exitCode: 1,
+      ok: false,
+      rowCount: 2,
+    });
+
+    expect(output.error).toHaveBeenCalledWith(expect.stringContaining("firstBreakId=row_2"));
+  });
+
+  test("plugins enable requires tenantId + pluginId", async () => {
+    const sub = (pluginsCommand.subCommands as Record<string, { args: Record<string, { required?: boolean }> }>).enable;
+    expect(sub.args.tenantId.required).toBe(true);
+    expect(sub.args.pluginId.required).toBe(true);
+  });
+
+  test("plugins enable refuses missing capability grants before toggling", async () => {
+    mocks.db.plugin.findUnique.mockResolvedValueOnce({
+      id: "row_1",
+      tenantId: "tenant_1",
+      pluginId: "com.acme.crm",
+      version: "1.0.0",
+      enabled: false,
+      manifest: {
+        capabilities: [{ name: "log" }],
+      },
+    });
+    mocks.db.tenantPluginCapabilityGrant.findMany.mockResolvedValueOnce([]);
+
+    await pluginsEnableCommand.run?.({ args: { tenantId: "tenant_1", pluginId: "com.acme.crm" } } as never);
+
+    expect(process.exitCode).toBe(1);
+    expect(consoleMock.error).toHaveBeenCalledWith(expect.stringContaining("missing operator consent"));
+    expect(mocks.db.plugin.update).not.toHaveBeenCalled();
+    expect(mocks.publishAuditEventViaOutbox).not.toHaveBeenCalled();
+  });
+
+  test("plugins enable toggles through lifecycle and writes an audit outbox event", async () => {
+    mocks.db.plugin.findUnique.mockResolvedValueOnce({
+      id: "row_1",
+      tenantId: "tenant_1",
+      pluginId: "com.acme.crm",
+      version: "1.0.0",
+      enabled: false,
+      manifest: {
+        capabilities: [{ name: "log" }],
+      },
+    });
+    mocks.db.tenantPluginCapabilityGrant.findMany.mockResolvedValueOnce([
+      { capabilityName: "log", scopeJson: null },
+    ]);
+    mocks.db.plugin.update.mockResolvedValueOnce({
+      id: "row_1",
+      tenantId: "tenant_1",
+      pluginId: "com.acme.crm",
+      version: "1.0.0",
+      enabled: true,
+      manifest: { capabilities: [] },
+    });
+
+    await pluginsEnableCommand.run?.({ args: { tenantId: "tenant_1", pluginId: "com.acme.crm" } } as never);
+
+    expect(mocks.db.plugin.update).toHaveBeenCalledWith({
+      where: { id: "row_1" },
+      data: { enabled: true },
+    });
+    expect(mocks.publishAuditEventViaOutbox).toHaveBeenCalledWith(
+      mocks.db,
+      expect.objectContaining({
+        tenantId: "tenant_1",
+        action: "plugin.enabled",
+        sourceModule: "cli.plugins",
+        metadata: { pluginId: "com.acme.crm", version: "1.0.0" },
+      })
+    );
+    expect(consoleMock.success).toHaveBeenCalledWith("Plugin com.acme.crm for tenant tenant_1 is now ENABLED.");
+  });
+
+  test("plugins enable rejects disabled consent guard in production before DB writes", async () => {
+    process.env.NODE_ENV = "production";
+    process.env.PLUGIN_REQUIRE_CAPABILITY_CONSENT = "false";
+
+    await pluginsEnableCommand.run?.({ args: { tenantId: "tenant_1", pluginId: "com.acme.crm" } } as never);
+
+    expect(process.exitCode).toBe(1);
+    expect(consoleMock.error).toHaveBeenCalledWith("PLUGIN_REQUIRE_CAPABILITY_CONSENT=false is not allowed in production.");
+    expect(mocks.db.plugin.findUnique).not.toHaveBeenCalled();
+    expect(mocks.db.plugin.update).not.toHaveBeenCalled();
+    expect(mocks.publishAuditEventViaOutbox).not.toHaveBeenCalled();
+  });
+
+  test("plugins enable requires the production runtime gate before DB reads in production", async () => {
+    process.env.NODE_ENV = "production";
+
+    await pluginsEnableCommand.run?.({ args: { tenantId: "tenant_1", pluginId: "com.acme.crm" } } as never);
+
+    expect(process.exitCode).toBe(1);
+    expect(consoleMock.error).toHaveBeenCalledWith(expect.stringContaining("PLUGIN_RUNTIME_PRODUCTION_ENABLED=true"));
+    expect(mocks.db.plugin.findUnique).not.toHaveBeenCalled();
+    expect(mocks.db.plugin.update).not.toHaveBeenCalled();
+    expect(mocks.publishAuditEventViaOutbox).not.toHaveBeenCalled();
+  });
+
+  test("plugins enable rejects unavailable production capability host bindings before toggling", async () => {
+    process.env.NODE_ENV = "production";
+    process.env.PLUGIN_RUNTIME_PRODUCTION_ENABLED = "true";
+    mocks.db.plugin.findUnique.mockResolvedValueOnce({
+      id: "row_1",
+      tenantId: "tenant_1",
+      pluginId: "com.acme.crm",
+      version: "1.0.0",
+      enabled: false,
+      manifest: {
+        capabilities: [{ name: "http.outbound" }],
+      },
+    });
+
+    await pluginsEnableCommand.run?.({ args: { tenantId: "tenant_1", pluginId: "com.acme.crm" } } as never);
+
+    expect(process.exitCode).toBe(1);
+    expect(consoleMock.error).toHaveBeenCalledWith(expect.stringContaining("do not have reviewed production host bindings"));
+    expect(mocks.db.tenantPluginCapabilityGrant.findMany).not.toHaveBeenCalled();
+    expect(mocks.db.plugin.update).not.toHaveBeenCalled();
+    expect(mocks.publishAuditEventViaOutbox).not.toHaveBeenCalled();
+  });
+
+  test("plugins uninstall deletes through lifecycle and audits in the transaction", async () => {
+    consoleMock.prompt.mockResolvedValueOnce(true);
+    mocks.db.plugin.findUnique.mockResolvedValueOnce({
+      id: "row_1",
+      tenantId: "tenant_1",
+      pluginId: "com.acme.crm",
+      version: "1.0.0",
+      enabled: true,
+      manifest: { capabilities: [] },
+    });
+    mocks.db.plugin.delete.mockResolvedValueOnce({
+      id: "row_1",
+      tenantId: "tenant_1",
+      pluginId: "com.acme.crm",
+      version: "1.0.0",
+      enabled: true,
+      manifest: { capabilities: [] },
+    });
+
+    await pluginsUninstallCommand.run?.({ args: { tenantId: "tenant_1", pluginId: "com.acme.crm" } } as never);
+
+    expect(mocks.db.plugin.delete).toHaveBeenCalledWith({ where: { id: "row_1" } });
+    expect(mocks.publishAuditEventViaOutbox).toHaveBeenCalledWith(
+      mocks.db,
+      expect.objectContaining({
+        tenantId: "tenant_1",
+        action: "plugin.uninstalled",
+        sourceModule: "cli.plugins",
+        metadata: { pluginId: "com.acme.crm", version: "1.0.0" },
+      })
+    );
+    expect(consoleMock.success).toHaveBeenCalledWith("Plugin com.acme.crm uninstalled from tenant tenant_1.");
+  });
+});
+
+function pluginCapabilityRow(overrides: Partial<PluginCapabilityUseChainRow> = {}): PluginCapabilityUseChainRow {
+  return {
+    id: "row_1",
+    pluginInvocationId: "inv_1",
+    tenantId: "tenant_1",
+    pluginId: "com.acme.crm",
+    capability: "log",
+    payloadHash: null,
+    outcome: "success",
+    errorCode: null,
+    durationMs: 5,
+    timestamp: "2026-05-29T04:00:00.000Z",
+    ...overrides,
+  };
+}
+
+function stampedPluginCapabilityRows(rows: ReadonlyArray<PluginCapabilityUseChainRow>): PluginCapabilityUseChainStoredRow[] {
+  return [...stampPluginCapabilityUseChain({ seedPrevHash: null, rows }).stamped];
+}
+
+function outputCollector() {
+  return {
+    error: vi.fn(),
+    info: vi.fn(),
+    json: vi.fn(),
+  };
+}

hivegrid-cloud/packages/cli/src/commands/plugins/index.ts

@@ -0,0 +1,30 @@
+import { defineCommand } from "citty";
+import { pluginsListCommand } from "./list.js";
+import { pluginsDisableCommand, pluginsEnableCommand } from "./toggle.js";
+import { pluginsUninstallCommand } from "./uninstall.js";
+import { pluginsScaffoldCommand } from "./scaffold.js";
+import { pluginsBuildCommand } from "./build.js";
+import { pluginsSignCommand } from "./sign.js";
+import { pluginsLintCommand } from "./lint.js";
+import { pluginsPublishCommand } from "./publish.js";
+import { pluginsVerifyAuditChainCommand } from "./verify-audit-chain.js";
+
+export const pluginsCommand = defineCommand({
+  meta: {
+    name: "plugins",
+    description:
+      "Plugin commands — operator (list/enable/disable/uninstall/verify-audit-chain) + author (scaffold/build/sign/lint/publish).",
+  },
+  subCommands: {
+    list: pluginsListCommand,
+    enable: pluginsEnableCommand,
+    disable: pluginsDisableCommand,
+    uninstall: pluginsUninstallCommand,
+    "verify-audit-chain": pluginsVerifyAuditChainCommand,
+    scaffold: pluginsScaffoldCommand,
+    build: pluginsBuildCommand,
+    sign: pluginsSignCommand,
+    lint: pluginsLintCommand,
+    publish: pluginsPublishCommand,
+  },
+});

hivegrid-cloud/packages/cli/src/commands/plugins/lifecycle.ts

@@ -0,0 +1,207 @@
+import {
+  assertPluginRuntimeProductionEnabled,
+  getUnavailablePluginCapabilityNames,
+  isCapabilityGrantScopeSatisfied,
+  type PluginManifest,
+} from "@toolctrl/plugin-runtime";
+import { resolvePluginLifecycleRuntimeEnv, type EnvRecord } from "@toolctrl/config";
+
+export class CliPluginLifecycleError extends Error {
+  public override readonly name = "CliPluginLifecycleError";
+  constructor(
+    public readonly code:
+      | "not_found"
+      | "capability_consent_missing"
+      | "capability_grants_unavailable"
+      | "capability_unavailable"
+      | "production_guard_violation",
+    message: string
+  ) {
+    super(message);
+  }
+}
+
+type PluginRow = {
+  id: string;
+  tenantId: string;
+  pluginId: string;
+  version: string;
+  enabled: boolean;
+  manifest: unknown;
+};
+
+type CapabilityGrantRow = {
+  capabilityName: string;
+  scopeJson: unknown;
+};
+
+type PluginLifecycleDb = {
+  plugin: {
+    findUnique(args: { where: { tenantId_pluginId: { tenantId: string; pluginId: string } } }): Promise<PluginRow | null>;
+    update(args: { where: { id: string }; data: { enabled: boolean } }): Promise<PluginRow>;
+    delete(args: { where: { id: string } }): Promise<PluginRow>;
+  };
+  tenantPluginCapabilityGrant?: {
+    findMany(args: { where: { tenantId: string; pluginId: string } }): Promise<CapabilityGrantRow[]>;
+  };
+  $transaction<T>(fn: (tx: PluginLifecycleDb) => Promise<T>): Promise<T>;
+};
+
+const CLI_ACTOR = {
+  actorId: null,
+  actorType: "system",
+  actorEmail: null,
+  actorIp: null,
+} as const;
+
+function manifestCapabilities(row: PluginRow): PluginManifest["capabilities"] {
+  return ((row.manifest as PluginManifest | null)?.capabilities ?? []) as PluginManifest["capabilities"];
+}
+
+function assertCliProductionEscapeHatchesDisabled(env: EnvRecord | undefined) {
+  const runtimeEnv = resolvePluginLifecycleRuntimeEnv(env);
+  if (runtimeEnv.nodeEnv !== "production") {
+    return;
+  }
+  if (!runtimeEnv.requireCapabilityConsent) {
+    throw new CliPluginLifecycleError(
+      "production_guard_violation",
+      "PLUGIN_REQUIRE_CAPABILITY_CONSENT=false is not allowed in production."
+    );
+  }
+}
+
+function assertCliPluginRuntimeProductionEnabled(env: EnvRecord | undefined) {
+  try {
+    assertPluginRuntimeProductionEnabled(env);
+  } catch (error) {
+    throw new CliPluginLifecycleError(
+      "production_guard_violation",
+      `Plugin enable blocked: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+function assertCliProductionCapabilitiesAvailable(env: EnvRecord | undefined, capabilities: PluginManifest["capabilities"]) {
+  if (resolvePluginLifecycleRuntimeEnv(env).nodeEnv !== "production") {
+    return;
+  }
+  const unavailable = getUnavailablePluginCapabilityNames(capabilities ?? []);
+  if (unavailable.length === 0) {
+    return;
+  }
+  throw new CliPluginLifecycleError(
+    "capability_unavailable",
+    `Plugin enable blocked: capabilities [${unavailable.join(", ")}] do not have reviewed production host bindings yet.`
+  );
+}
+
+async function findInstalledPlugin(db: PluginLifecycleDb, args: { tenantId: string; pluginId: string }): Promise<PluginRow> {
+  const row = await db.plugin.findUnique({
+    where: { tenantId_pluginId: { tenantId: args.tenantId, pluginId: args.pluginId } },
+  });
+  if (!row) {
+    throw new CliPluginLifecycleError("not_found", `No plugin '${args.pluginId}' installed for tenant '${args.tenantId}'.`);
+  }
+  return row;
+}
+
+async function assertEnableConsentSatisfied(db: PluginLifecycleDb, row: PluginRow, env: EnvRecord | undefined): Promise<void> {
+  if (!resolvePluginLifecycleRuntimeEnv(env).requireCapabilityConsent) {
+    return;
+  }
+  const declared = manifestCapabilities(row);
+  if (declared.length === 0) {
+    return;
+  }
+  const grantsTable = db.tenantPluginCapabilityGrant;
+  if (!grantsTable) {
+    throw new CliPluginLifecycleError("capability_grants_unavailable", "TenantPluginCapabilityGrant table not migrated; run prisma migrate deploy.");
+  }
+  const grants = await grantsTable.findMany({
+    where: { tenantId: row.tenantId, pluginId: row.pluginId },
+  });
+  const grantByCapability = new Map(grants.map((grant) => [grant.capabilityName, grant]));
+  const missing = declared
+    .filter((capability) => {
+      const grant = grantByCapability.get(capability.name);
+      return (
+        !grant ||
+        !isCapabilityGrantScopeSatisfied({
+          declaredScope: capability.scope ?? null,
+          grantedScopeJson: grant.scopeJson,
+        })
+      );
+    })
+    .map((capability) => capability.name);
+
+  if (missing.length > 0) {
+    throw new CliPluginLifecycleError(
+      "capability_consent_missing",
+      `Plugin ${row.pluginId} cannot be enabled: missing operator consent for capabilities [${missing.join(", ")}].`
+    );
+  }
+}
+
+export async function setPluginEnabledViaLifecycle(args: {
+  db: PluginLifecycleDb;
+  tenantId: string;
+  pluginId: string;
+  enabled: boolean;
+  env?: EnvRecord;
+}): Promise<PluginRow> {
+  assertCliProductionEscapeHatchesDisabled(args.env);
+  if (args.enabled) {
+    assertCliPluginRuntimeProductionEnabled(args.env);
+  }
+  const row = await findInstalledPlugin(args.db, args);
+  if (args.enabled) {
+    assertCliProductionCapabilitiesAvailable(args.env, manifestCapabilities(row));
+    await assertEnableConsentSatisfied(args.db, row, args.env);
+  }
+  const { publishAuditEventViaOutbox } = await import("@toolctrl/db/audit-events.server");
+  return await args.db.$transaction(async (tx) => {
+    const updated = await tx.plugin.update({
+      where: { id: row.id },
+      data: { enabled: args.enabled },
+    });
+    await publishAuditEventViaOutbox(tx as never, {
+      tenantId: args.tenantId,
+      ...CLI_ACTOR,
+      action: args.enabled ? "plugin.enabled" : "plugin.disabled",
+      targetType: "plugin",
+      targetId: updated.id,
+      sourceModule: "cli.plugins",
+      outcome: "success",
+      dataSensitivity: "internal",
+      metadata: {
+        pluginId: updated.pluginId,
+        version: updated.version,
+      },
+    });
+    return updated;
+  });
+}
+
+export async function uninstallPluginViaLifecycle(args: { db: PluginLifecycleDb; tenantId: string; pluginId: string }): Promise<PluginRow> {
+  const row = await findInstalledPlugin(args.db, args);
+  const { publishAuditEventViaOutbox } = await import("@toolctrl/db/audit-events.server");
+  return await args.db.$transaction(async (tx) => {
+    const deleted = await tx.plugin.delete({ where: { id: row.id } });
+    await publishAuditEventViaOutbox(tx as never, {
+      tenantId: args.tenantId,
+      ...CLI_ACTOR,
+      action: "plugin.uninstalled",
+      targetType: "plugin",
+      targetId: deleted.id,
+      sourceModule: "cli.plugins",
+      outcome: "success",
+      dataSensitivity: "internal",
+      metadata: {
+        pluginId: deleted.pluginId,
+        version: deleted.version,
+      },
+    });
+    return deleted;
+  });
+}

hivegrid-cloud/packages/cli/src/commands/plugins/lint.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "vitest";
+import { lintManifest } from "./lint.js";
+
+function validManifest(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    schemaVersion: 1,
+    id: "de.acme.test",
+    version: "1.0.0",
+    name: "Test",
+    entry: "plugin.wasm",
+    wasmSha256: "a".repeat(64),
+    signature: "b".repeat(128),
+    signedBy: "c".repeat(64),
+    allowedHosts: [],
+    capabilities: [{ name: "log" }],
+    hooks: [{ name: "x", export: "x" }],
+    ...overrides,
+  };
+}
+
+describe("lintManifest", () => {
+  test("clean manifest exits 0 with no findings", () => {
+    const result = lintManifest(validManifest());
+    expect(result.exitCode).toBe(0);
+    expect(result.findings).toHaveLength(0);
+  });
+
+  test("schema-invalid manifest exits 1 with manifest_invalid", () => {
+    const bad = validManifest({ schemaVersion: 99 });
+    const result = lintManifest(bad);
+    expect(result.exitCode).toBe(1);
+    expect(result.findings[0]?.code).toBe("manifest_invalid");
+  });
+
+  test("placeholder signature triggers warn but not error", () => {
+    const result = lintManifest(
+      validManifest({ signature: "0".repeat(128), signedBy: "0".repeat(64) })
+    );
+    expect(result.exitCode).toBe(2);
+    expect(result.findings.some((f) => f.code === "unsigned_placeholder")).toBe(true);
+  });
+
+  test("placeholder wasmSha256 triggers unsigned_wasm warn", () => {
+    const result = lintManifest(validManifest({ wasmSha256: "0".repeat(64) }));
+    expect(result.findings.some((f) => f.code === "unsigned_wasm")).toBe(true);
+  });
+
+  test("http.outbound without allowedHosts triggers http_outbound_unrestricted", () => {
+    const result = lintManifest(
+      validManifest({
+        capabilities: [{ name: "http.outbound" }],
+        allowedHosts: [],
+      })
+    );
+    expect(result.findings.some((f) => f.code === "http_outbound_unrestricted")).toBe(true);
+  });
+
+  test("http.outbound WITH allowedHosts does not warn", () => {
+    const result = lintManifest(
+      validManifest({
+        capabilities: [{ name: "http.outbound", scope: { allowedHosts: ["hooks.slack.com"] } }],
+        allowedHosts: ["hooks.slack.com"],
+      })
+    );
+    expect(result.findings.find((f) => f.code === "http_outbound_unrestricted")).toBeUndefined();
+  });
+
+  test("db.write capability triggers high_risk_capability warn", () => {
+    const result = lintManifest(
+      validManifest({ capabilities: [{ name: "db.write" }] })
+    );
+    expect(result.findings.some((f) => f.code === "high_risk_capability")).toBe(true);
+  });
+
+  test("returns exit 1 when any finding is severity=error", () => {
+    const result = lintManifest({ broken: true });
+    expect(result.exitCode).toBe(1);
+  });
+});

hivegrid-cloud/packages/cli/src/commands/plugins/lint.ts

@@ -0,0 +1,161 @@
+/**
+ * `plugins lint` — Phase 06 #23 — validate a plugin manifest.
+ *
+ * The lint command runs the same Zod manifest schema the host uses,
+ * then layers author-facing checks on top:
+ *   - every declared capability name is in the closed enum
+ *     (PLUGIN_CAPABILITY_NAMES)
+ *   - signature + signedBy are the right length when not still the
+ *     placeholder zeros (warn-only — unsigned manifests are valid for
+ *     local dev)
+ *   - allowedHosts entries are valid hostnames (or the literal "*")
+ *   - at least one hook is declared (a plugin that exports nothing
+ *     does nothing — almost certainly an authoring bug)
+ *
+ * Exit codes: 0 = clean. 1 = errors (manifest invalid). 2 = warnings
+ * only (still parseable but suspicious).
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { readFile } from "node:fs/promises";
+import {
+  PLUGIN_CAPABILITY_NAMES,
+  type PluginCapabilityName,
+  parsePluginManifest,
+} from "@toolctrl/plugin-runtime";
+
+export interface LintFinding {
+  readonly severity: "error" | "warn";
+  readonly code: string;
+  readonly message: string;
+}
+
+export interface LintResult {
+  readonly findings: ReadonlyArray<LintFinding>;
+  readonly exitCode: 0 | 1 | 2;
+}
+
+export function lintManifest(rawManifestJson: unknown): LintResult {
+  const findings: LintFinding[] = [];
+  const result = parsePluginManifest(rawManifestJson);
+  if (!result.ok) {
+    const summary = result.issues
+      .map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
+      .join("; ");
+    findings.push({
+      severity: "error",
+      code: "manifest_invalid",
+      message: summary,
+    });
+    return { findings, exitCode: 1 };
+  }
+  const manifest = result.manifest;
+
+  // Capability sanity.
+  const allowed = new Set<string>(PLUGIN_CAPABILITY_NAMES);
+  for (const cap of manifest.capabilities) {
+    if (!allowed.has(cap.name)) {
+      findings.push({
+        severity: "error",
+        code: "unknown_capability",
+        message: `Capability "${cap.name}" is not in the host registry. Known: ${[...allowed].sort().join(", ")}.`,
+      });
+    }
+  }
+
+  // Allowed-hosts shape.
+  for (const host of manifest.allowedHosts ?? []) {
+    if (host === "*") continue;
+    if (!/^[a-z0-9.-]+$/iu.test(host)) {
+      findings.push({
+        severity: "error",
+        code: "invalid_host",
+        message: `allowedHosts entry "${host}" is not a valid hostname.`,
+      });
+    }
+  }
+
+  // Placeholder signature warning.
+  if (manifest.signature === "0".repeat(128) || manifest.signedBy === "0".repeat(64)) {
+    findings.push({
+      severity: "warn",
+      code: "unsigned_placeholder",
+      message: "Manifest signature/signedBy are placeholder zeros — run `plugins sign` before publishing.",
+    });
+  }
+  // wasmSha256 placeholder.
+  if (manifest.wasmSha256 === "0".repeat(64)) {
+    findings.push({
+      severity: "warn",
+      code: "unsigned_wasm",
+      message: "wasmSha256 is placeholder zeros — recompute from the built .wasm before publishing.",
+    });
+  }
+
+  // Hooks declared.
+  if (manifest.hooks.length === 0) {
+    findings.push({
+      severity: "warn",
+      code: "no_hooks",
+      message: "Plugin declares zero hooks — it will never be invoked by the host.",
+    });
+  }
+
+  // http.outbound without allowedHosts is suspicious.
+  if (
+    manifest.capabilities.some((c) => c.name === ("http.outbound" satisfies PluginCapabilityName)) &&
+    (!manifest.allowedHosts || manifest.allowedHosts.length === 0)
+  ) {
+    findings.push({
+      severity: "warn",
+      code: "http_outbound_unrestricted",
+      message: "http.outbound declared without allowedHosts — host will deny every fetch.",
+    });
+  }
+
+  // db.write is high-risk — warn.
+  if (manifest.capabilities.some((c) => c.name === ("db.write" satisfies PluginCapabilityName))) {
+    findings.push({
+      severity: "warn",
+      code: "high_risk_capability",
+      message: "db.write declared — operator review recommended (tenant data mutation).",
+    });
+  }
+
+  const hasError = findings.some((f) => f.severity === "error");
+  const hasWarn = findings.some((f) => f.severity === "warn");
+  const exitCode: 0 | 1 | 2 = hasError ? 1 : hasWarn ? 2 : 0;
+  return { findings, exitCode };
+}
+
+export const pluginsLintCommand = defineCommand({
+  meta: {
+    name: "lint",
+    description: "Validate a plugin manifest against the host schema + author-facing sanity checks.",
+  },
+  args: {
+    manifest: { type: "string", required: true, description: "Path to the manifest JSON file." },
+  },
+  async run({ args }) {
+    const manifestPath = String(args.manifest);
+    const text = await readFile(manifestPath, "utf8");
+    const json = JSON.parse(text) as unknown;
+    const result = lintManifest(json);
+    for (const f of result.findings) {
+      const line = `[${f.severity}] ${f.code}: ${f.message}`;
+      if (f.severity === "error") {
+        consola.error(line);
+      } else {
+        consola.warn(line);
+      }
+    }
+    if (result.exitCode === 0) {
+      consola.success("Manifest is clean.");
+    } else if (result.exitCode === 2) {
+      consola.warn(`Manifest passed with ${result.findings.filter((f) => f.severity === "warn").length} warning(s).`);
+    } else {
+      consola.error(`Manifest has ${result.findings.filter((f) => f.severity === "error").length} error(s).`);
+    }
+    process.exitCode = result.exitCode;
+  },
+});

hivegrid-cloud/packages/cli/src/commands/plugins/list.ts

@@ -0,0 +1,54 @@
+/**
+ * `plugins list` — print every installed plugin row across all tenants
+ * (or filtered to one).
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+
+export const pluginsListCommand = defineCommand({
+  meta: {
+    name: "list",
+    description: "List installed plugins.",
+  },
+  args: {
+    tenantId: {
+      type: "string",
+      description: "Filter to a single tenant.",
+    },
+    enabled: {
+      type: "string",
+      description: "Filter: 'true' for enabled only, 'false' for disabled only.",
+    },
+  },
+  async run({ args }) {
+    const { getDbClient } = await import("@toolctrl/db/client.server");
+    const prisma = getDbClient();
+    const where: Record<string, unknown> = {};
+    if (typeof args.tenantId === "string" && args.tenantId.length > 0) {
+      where.tenantId = args.tenantId;
+    }
+    if (args.enabled === "true") where.enabled = true;
+    if (args.enabled === "false") where.enabled = false;
+    const rows = await prisma.plugin.findMany({
+      where: where as never,
+      orderBy: [{ tenantId: "asc" }, { pluginId: "asc" }],
+      select: {
+        id: true,
+        tenantId: true,
+        pluginId: true,
+        version: true,
+        enabled: true,
+        installedAt: true,
+      },
+    });
+    if (rows.length === 0) {
+      consola.info("No installed plugins matched the filter.");
+      return;
+    }
+    for (const row of rows) {
+      const state = row.enabled ? "ON " : "OFF";
+      consola.log(`${state}  ${row.tenantId.padEnd(28)}  ${row.pluginId.padEnd(36)}  v${row.version}`);
+    }
+    consola.success(`${rows.length} plugin row(s) listed.`);
+  },
+});