@fourier-labs/harbour 0.1.14 → 0.1.17

package/README.md

@@ -0,0 +1,42 @@
+# @fourier-labs/harbour
+
+The Harbour CLI: sets up, runs, checks and ships an Isomorph app. It is meant to be driven by an AI coding agent (Claude Code or Codex) on your behalf; you can also use it directly.
+
+## Quick start (no coding needed)
+
+You describe the app in plain English inside Claude Code or Codex; the agent installs and runs everything. One paste, once per computer:
+
+```
+npx -y @fourier-labs/harbour@stable agent-setup
+```
+
+Paste that line into Claude Code or Codex (or a terminal). It teaches both agents the kit: it writes the `isomorph` skill for Claude Code (`~/.claude/skills/isomorph/SKILL.md`) and a fenced block in your global Codex instructions (`~/.codex/AGENTS.md`), and never touches your other skills or instructions. Then, in an empty folder:
+
+1. Say what you want, for example "Build me a small app where my team can vote on lunch options and see the results live."
+2. Say "run it" — the agent starts it and gives you a link to open.
+3. Say "check it" — the agent runs the checks and tells you in plain words what passed and what it fixed.
+4. Say "I need Slack" (or Gmail, or the warehouse) — the agent asks IT for access and tells you when it is approved.
+5. Say "ship it" — the agent puts a private preview online and gives you the link; "make it live for everyone" promotes it after you have tried it.
+
+The only step you do yourself is the company sign-in: when the agent runs `harbour login`, your browser opens and you sign in there. You need Node 22+ and Docker Desktop; the agent tells you if either is missing. Full walkthrough: [docs/vibecoding.md](../../docs/vibecoding.md).
+
+## Commands
+
+```
+harbour agent-setup                                        install the agent guide (Claude Code skill + Codex AGENTS.md block); idempotent
+harbour init --app-root <path> [--upgrade]                 starter app in an empty folder, or kit files in a Vite + React app (also runs agent-setup)
+harbour dev --app-root <path> [--reset]                    run the app locally on one loopback origin
+harbour stop --app-root <path>                             stop local services, keep data
+harbour check --app-root <path> [--integrations] [--json]  declaration, types, build, migrations, journeys; report in .harbour/local/check-report.json
+harbour integrations request <connection> --reason <text> --app-root <path> [--environment <env>]
+harbour integrations status --app-root <path> [--json]
+harbour connect <company-start-url>                        once per company; then harbour login | logout
+harbour productionise --app-root <path> [--wait] [--json]  save + preview deployment, prints the protected link
+harbour status | retry | promote | setup | profile | audience | secrets … --operation <reference>
+```
+
+`harbour --help` prints the full usage. Local commands need no company sign-in; integrations and shipping do.
+
+## Development
+
+Built from the [governance control plane](https://github.com/Fourier-Labs-AI/harbour-governance-control-plane) repository: `npm ci`, `npm run build --prefix packages/harbour-cli`, tests in `tests/cli-kit.test.ts` and `tests/cli-packaging-contract.test.ts`. Releases are tagged `cli-v<version>` (a `-rc.N` candidate first, then the stable tag).

package/dist/packages/harbour-cli/src/agent-setup.js

@@ -0,0 +1,87 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const MANAGED_START = "<!-- harbour:kit:start -->";
+export const MANAGED_END = "<!-- harbour:kit:end -->";
+/** Where the two agents read their user-level instructions from; both honour the tools' own override variables. */
+export function agentPaths(env = process.env) {
+    const home = env.HARBOUR_AGENT_HOME?.trim() || homedir();
+    return {
+        claudeSkill: join(env.CLAUDE_CONFIG_DIR?.trim() || join(home, ".claude"), "skills", "isomorph", "SKILL.md"),
+        codexAgents: join(env.CODEX_HOME?.trim() || join(home, ".codex"), "AGENTS.md")
+    };
+}
+/**
+ * Installs the user-level Isomorph guide for Claude Code (a skill file, wholly owned
+ * by the kit) and Codex (a marker-fenced block in ~/.codex/AGENTS.md, everything else
+ * in that file is kept). Idempotent: unchanged files are reported as kept.
+ */
+export async function agentSetup(env = process.env) {
+    const paths = agentPaths(env);
+    const result = { created: [], updated: [], kept: [] };
+    result[await upsertManagedBlock(paths.claudeSkill, `${SKILL_FRONTMATTER}\n${AGENT_GUIDE}`, {})].push(paths.claudeSkill);
+    result[await upsertManagedBlock(paths.codexAgents, [MANAGED_START, AGENT_GUIDE, MANAGED_END].join("\n"), { start: MANAGED_START, end: MANAGED_END, separator: "\n\n" })].push(paths.codexAgents);
+    return result;
+}
+/**
+ * Writes `block` to `file`: creates the file, replaces the text between the markers
+ * when both are present, or appends the block after the existing content. Without
+ * markers the whole file is the managed block and is rewritten only when it differs.
+ */
+export async function upsertManagedBlock(file, block, options) {
+    const current = await readFile(file, "utf8").catch(() => undefined);
+    if (current === undefined) {
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, `${block}\n`);
+        return "created";
+    }
+    const { start, end } = options;
+    let next;
+    if (start && end && current.includes(start) && current.includes(end))
+        next = current.replace(new RegExp(`${escape(start)}[\\s\\S]*?${escape(end)}`), () => block);
+    else if (start && end)
+        next = `${current.replace(/\n*$/, "")}${options.separator ?? "\n\n"}${block}\n`;
+    else
+        next = `${block}\n`;
+    if (next === current)
+        return "kept";
+    await writeFile(file, next);
+    return "updated";
+}
+const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const SKILL_FRONTMATTER = `---
+name: isomorph
+description: Build, run, check and ship a company app on Isomorph (Harbour) from plain English. Use whenever someone wants an app for their team, says "run it", "check it", "I need Slack/Gmail/company data", "ship it" or "make it live", or when a folder has a .harbour/ directory.
+---`;
+/** One guide, shared by the Claude Code skill and the Codex AGENTS.md block. Written for an agent working with a non-developer. */
+export const AGENT_GUIDE = `# Isomorph app kit
+
+The person you are working with may not be a developer. They say what they want in plain English; you build it with the Harbour kit and run every command yourself. Never ask them to type a terminal command (the one exception is sign-in, below). Never paste JSON, logs, stack traces or file contents at them. Turn every failure into one sentence about what happened and one about what happens next. Prefer \`--json\` output and read it yourself.
+
+## Getting ready (do this yourself, once per machine and folder)
+
+1. CLI: if \`harbour --version\` fails, run \`npm i -g @fourier-labs/harbour@stable\`. The kit needs Node 22+ and Docker Desktop running; if Docker is missing, that is the one thing to tell them to install, in one line.
+2. Folder: if the current folder has no \`.harbour/\` directory, run \`harbour init --app-root .\` — an empty folder gets a small starter app, an existing Vite + React app gets the kit files added and nothing overwritten. Then read the "Harbour development kit" block in CLAUDE.md / AGENTS.md; it holds the per-app rules.
+3. Sign-in, needed only for company systems and shipping: run \`harbour login\`. It opens the browser and the person finishes the sign-in there — the one step they do themselves; tell them so in one line. If login says the company is not connected yet, ask them for the Harbour link their IT/admin gave them and run \`harbour connect <link>\` first.
+
+## What they say → what you do
+
+- "run it", "show me", "let me try it" → start \`harbour dev --app-root .\` in the background (it keeps running; the first start pulls images and takes a minute or two). Wait for the line \`Harbour dev is running: http://127.0.0.1:<port>\` and give them that link. Locally they are a fixture user; no company sign-in is needed.
+- "check it", "is it ok?", "is it ready?" → with dev running, \`harbour check --app-root . --json\`, then read \`.harbour/local/check-report.json\`. Say in plain words what passed, what failed, and the one thing to do. Failures in the app's code are yours to fix — fix, then check again.
+- "I need Slack / Gmail / the warehouse / company data" → declare the connection and only the operations the app really calls in \`.harbour/integrations.json\` (the closed set is in the per-app block), then \`harbour integrations request <connection> --reason "<what the app does with it>" --app-root . --json\`. READY means use it now. PENDING means IT has to approve it: say "IT has to approve this; the app works without it until then", and check later with \`harbour integrations status --app-root . --json\`. Never declare a connection the app does not call — every declared one blocks shipping until IT approves it.
+- "ship it", "put it online", "let my team try it" → each declared connection first needs a preview grant (\`harbour integrations request <connection> --environment preview --reason "…" --app-root . --json\`). Then \`harbour productionise --app-root . --wait --json\` and give them \`result.deployment.protectedUrl\`: a private preview that they, and the people they name, open after company sign-in. Keep \`operationRef\`; \`harbour setup --operation <ref> --json\` lists what is still missing (name, audience, secrets) and \`harbour profile\` / \`harbour audience\` / \`harbour secrets set\` fill it in. Tell them shipping takes a few minutes and what it is doing.
+- "make it live for everyone", "go to production" → only after they have tried the preview: \`harbour promote --operation <ref> --json\` with the operation reference from productionise. Report the production link, or that an operator approval is pending.
+- "stop it" → \`harbour stop --app-root .\` (local data kept). \`harbour dev --reset --app-root .\` deletes local data — only when they explicitly ask to start over.
+
+## Building the app
+
+- Identity, data and files go through \`@harbour/app-sdk\` only: \`harbour.identity.current()\`, \`harbour.data.from(table)\`, \`harbour.files.*\`. Company systems go only through \`harbour.integrations.execute\` with declared operations. Never open a database, bucket or company URL from browser code, and never add another backend, auth library or deployment config: the kit is the whole path.
+- Authentication is Harbour SSO: no login forms, no roles or ids trusted from the browser; row ownership is decided in SQL through \`current_setting('harbour.user_id', true)\`. Every route needs a signed-in person; no public routes.
+- Schema changes are SQL files in \`migrations/\` with row-level security and GRANTs to \`harbour_app_gateway\`; \`harbour dev\` and \`harbour check\` apply them.
+- A Slack message is sent only when the person presses an explicit Send control, with a fresh UUID \`idempotencyKey\` per press (reused only to retry that press). Never send from an effect, a timer, a queue or during checks. Consent is a user action (\`harbour.integrations.connect\`); missing consent never falls back to another account.
+- No secrets, tokens, \`.env\` values or fetched company content in source. \`.harbour/local/\` is never committed; \`.harbour/integrations.json\` and \`.harbour/kit.lock.json\` are.
+
+## Talking to the person
+
+- Plain words, short: "Your app is running at <link>.", "All 6 checks passed.", "One check failed: votes were not being saved — fixed, checking again.", "IT has to approve Slack; the app works without it until then."
+- Say what happens next and roughly how long it takes. Report only what you observed; if something is unknown, say so.`;

package/dist/packages/harbour-cli/src/check.js

@@ -1,13 +1,15 @@
 import { readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { loadDatabaseGate } from "./database-gate.js";
+import { CliError } from "./output.js";
 import { DEPENDENT_READ_OPERATIONS, READ_OPERATIONS, kitPaths, readDeclaration, readKitLock, resourceNames, sourceDigest } from "./kit.js";
-import { LocalRuntime, runningOrigin } from "./local-runtime.js";
+import { LOCAL, LocalRuntime, runCommand, runningOrigin } from "./local-runtime.js";
 import { CLI_VERSION } from "./version.js";
 /** Runs the kit checks and writes `.harbour/local/check-report.json`; a source edit changes sourceDigest and so invalidates the previous report. */
 export async function runChecks(root, options) {
     const { output, run, bundle } = options;
     const checks = [];
-    const record = (name, status, detail) => { checks.push({ name, status, ...(detail ? { detail } : {}) }); output(`${status === "pass" ? "ok  " : status === "fail" ? "FAIL" : "skip"} ${name}${detail ? ` — ${detail}` : ""}`); };
+    const record = (name, status, detail) => { checks.push({ name, status, ...(detail ? { detail } : {}) }); output(`${status === "pass" ? "ok  " : status === "fail" ? "FAIL" : "skip"} ${name}${detail ? ` — ${indentLines(detail)}` : ""}`); };
     const source = await sourceDigest(root);
     const previous = await readReport(root);
     if (previous && previous.sourceDigest !== source.digest)
@@ -27,9 +29,20 @@ export async function runChecks(root, options) {
         await throwaway.up();
         const applied = await throwaway.migrate();
         record("migrations", "pass", `${applied.length} file(s) applied to a disposable database`);
+        // The pipeline's database gate, on the database those files just built:
+        // the same script the in-loop probe runs after its replay, so the defect
+        // CodeBuild would name is named here, in seconds.
+        if (!applied.length)
+            record("database_gate", "not_run", "no migrations/*.sql to gate");
+        else {
+            const gate = await loadDatabaseGate(bundle, run);
+            const violations = await throwaway.databaseGate(gate.sql);
+            record("database_gate", violations.length ? "fail" : "pass", violations.length ? violations.join("\n") : `row-level security, policy verbs and grants verified for ${LOCAL.gatewayRole} (gate from ${gate.source === "fixture" ? "the pinned session fixture" : "this CLI release"})`);
+        }
     }
     catch (error) {
         record("migrations", "fail", error instanceof Error ? error.message : String(error));
+        record("database_gate", "not_run", "the migrations did not replay");
     }
     finally {
         await throwaway.down();
@@ -108,6 +121,41 @@ async function testIntegrationReads(appId, client, declaration, output) {
     }
     return results;
 }
+/**
+ * `productionise` pre-flight for a kit app with migrations: replays them on a
+ * throwaway database and runs the pipeline's database gate before any
+ * operation exists. A gate violation or a migration that will not replay is
+ * refused here — the pipeline would refuse it minutes later in CodeBuild. A
+ * local runtime that cannot start (no Docker) is reported and skipped: the
+ * pipeline gate still runs.
+ */
+export async function preflightDatabaseGate(root, bundle, output, run = runCommand) {
+    const lock = await readKitLock(root).catch(() => undefined);
+    const migrations = (await readdir(join(root, "migrations")).catch(() => [])).filter(name => name.endsWith(".sql"));
+    if (!lock || !migrations.length)
+        return "skipped";
+    const throwaway = LocalRuntime.forCheck(root, run);
+    try {
+        await throwaway.writeCheckFiles(bundle);
+        try {
+            await throwaway.up();
+        }
+        catch (error) {
+            output(`The migrations were not replayed locally (${error instanceof Error ? error.message : String(error)}); the pipeline's database gate will run in CodeBuild.`);
+            return "skipped";
+        }
+        await throwaway.migrate();
+        const gate = await loadDatabaseGate(bundle, run);
+        const violations = await throwaway.databaseGate(gate.sql);
+        if (violations.length)
+            throw new CliError("DATABASE_GATE_FAILED", `The migrations fail the pipeline's database gate (${violations.length} violation(s)):\n${violations.map(line => `  - ${line}`).join("\n")}\nFix migrations/ and run \`harbour check\`; the pipeline would refuse this deployment as kit.check-failed: aurora.database-gate.`);
+        output(`Migrations replayed and the database gate passed locally (${migrations.length} file(s), gate from ${gate.source === "fixture" ? "the pinned session fixture" : "this CLI release"}).`);
+        return "passed";
+    }
+    finally {
+        await throwaway.down();
+    }
+}
 export async function readReport(root) {
     try {
         return JSON.parse(await readFile(kitPaths(root).report, "utf8"));
@@ -117,3 +165,5 @@ export async function readReport(root) {
     }
 }
 function lastLines(text, count = 5) { return text.trim().split("\n").slice(-count).join(" | ").slice(0, 600); }
+/** A multi-line detail (one gate violation per line) keeps its lines, each under the check name. */
+function indentLines(detail) { return detail.split("\n").map((line, index) => index ? `      ${line}` : line).join("\n"); }

package/dist/packages/harbour-cli/src/cli.js

@@ -9,6 +9,7 @@ import { connect, loadConfig, resolveConfig } from "./config.js";
 import { loadKitBundle } from "./kit-bundle.js";
 import { appRoot } from "./kit.js";
 import { initKit } from "./starter.js";
+import { agentPaths, agentSetup } from "./agent-setup.js";
 import { startDev } from "./dev.js";
 import { ensureSdk, LocalRuntime, readDevLock, releaseDevLock, runCommand } from "./local-runtime.js";
 import { runChecks } from "./check.js";
@@ -63,15 +64,16 @@ const usage = [
     "  harbour secrets list --operation <reference> [--json]",
     "  harbour secrets set --operation <reference> --name <NAME> [--personal] [--value-stdin]",
     "  harbour secrets dismiss --operation <reference> --name <NAME>",
-    "  harbour init --app-root <path> [--upgrade]                 create the starter or add the kit files; --upgrade re-pins the kit bundle",
+    "  harbour agent-setup [--json]                               install the plain-English Isomorph guide for Claude Code (~/.claude/skills/isomorph) and Codex (~/.codex/AGENTS.md)",
+    "  harbour init --app-root <path> [--upgrade]                 create the starter or add the kit files; --upgrade re-pins the kit bundle (also runs agent-setup)",
     "  harbour dev --app-root <path> [--reset]                    run the app locally on one loopback origin (--reset deletes this app's local data)",
     "  harbour stop --app-root <path>                             stop this app's local services, keeping data",
-    "  harbour check --app-root <path> [--integrations] [--json]  declaration, types, build, migrations, journeys (+ authorised real reads)",
+    "  harbour check --app-root <path> [--integrations] [--json]  declaration, types, build, migrations + the pipeline's database gate (RLS, policy verbs, grants to harbour_app_gateway), journeys (+ authorised real reads)",
     "  harbour integrations request <connection> --reason <text> --app-root <path> [--environment <env>] [--operations a,b] [--expires-at <UTC>] [--json]",
     "  harbour integrations status --app-root <path> [--json]",
     "Run `harbour connect <company-start-url>` once, then sign in when Harbour asks.",
     "productionise saves the app, follows its deployment, and prints the protected preview link; promote sends a tested preview to production.",
-    "For kit apps, productionise first checks that every connection in .harbour/integrations.json has a preview grant and exits 2 (INTEGRATIONS_NOT_READY) with the requests to make.",
+    "For kit apps, productionise first checks that every connection in .harbour/integrations.json has a preview grant and exits 2 (INTEGRATIONS_NOT_READY) with the requests to make, then replays migrations/ on a throwaway database and refuses (DATABASE_GATE_FAILED) what the pipeline's database gate would refuse.",
     "secrets set reads the value from your terminal with echo off (or from stdin with --value-stdin); it is never printed or passed to any other program.",
     ""
 ].join("\n");
@@ -87,6 +89,14 @@ if (command === "--version" || command === "version") {
 else if (!command || command === "help" || command === "--help" || args.includes("-h")) {
     process.stdout.write(usage);
 }
+else if (command === "agent-setup") {
+    const result = await agentSetup(process.env);
+    for (const [state, paths] of Object.entries(result))
+        for (const path of paths)
+            progress(`${state.padEnd(7)} ${path}`);
+    progress("Claude Code: the `isomorph` skill is available in every folder. Codex: the block is in your global AGENTS.md. Say what you want to build; the agent installs and runs the kit itself.");
+    emit(summaryEnvelope({ ...result, paths: agentPaths(process.env) }));
+}
 else if (!["connect", "login", "logout", "productionise", "integrations", ...LOCAL_COMMANDS, ...OPERATION_COMMANDS].includes(command)
     || (command === "connect" && (!connectUrl || connectUrl.startsWith("--")))
     || (command === "productionise" && (optionError || !root))
@@ -113,8 +123,8 @@ else {
             const config = resolveConfig(process.env, await loadConfig());
             const companyToken = async () => config ? (explicitToken || await refreshStoredToken(config.mcpUrl, config.tenantId)) : undefined;
             if (command === "init") {
-                const result = await initKit(target, bundle, { upgrade, tenantId: config?.tenantId });
-                for (const line of [...result.created.map(path => `created ${path}`), ...result.updated.map(path => `updated ${path}`), ...result.kept.map(path => `kept    ${path}`), ...result.bundleChanges.map(change => `bundle  ${change}`)])
+                const result = await initKit(target, bundle, { upgrade, tenantId: config?.tenantId, env: process.env });
+                for (const line of [...result.created.map(path => `created ${path}`), ...result.updated.map(path => `updated ${path}`), ...result.kept.map(path => `kept    ${path}`), ...result.bundleChanges.map(change => `bundle  ${change}`), ...["created", "updated"].flatMap(state => result.agents[state].map(path => `${state} ${path} (agent guide)`))])
                     progress(line);
                 // The SDK is not on the public registry: init installs the pinned tarball (and the app's other dependencies) itself.
                 const sdk = await ensureSdk(target, bundle, process.env, runCommand, progress);

package/dist/packages/harbour-cli/src/database-gate.js

@@ -0,0 +1,53 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Where the session fixture image carries the gate (data plane build/session-fixture-image/Dockerfile). */
+export const DATABASE_GATE_IMAGE_PATH = "/harbour/kit/database-gate.sql";
+/**
+ * The kit database gate: the pipeline's own assertions over a replayed
+ * migration set, run by the in-loop probe (harbour-deployment-data-plane
+ * packages/toolkit/transformbuild/kit_database_gate.sql, embedded by
+ * containerprobe.go) right after the migrations replay. `harbour check`
+ * runs the copy the pinned session fixture image ships at
+ * DATABASE_GATE_IMAGE_PATH; this is the verbatim copy from data plane
+ * 0.73.1.0 for a fixture that predates the file. It raises one exception
+ * naming every violation (table / policy / grant) on its own line with the fix.
+ */
+export const DATABASE_GATE_SQL = "-- Harbour kit database gate.\n--\n-- Runs after a kit app's migrations replayed on a scratch PostgreSQL that\n-- carries the platform role harbour_app_gateway (NOLOGIN, NOBYPASSRLS): the\n-- role the App Gateway executes every application statement as. It asserts,\n-- against the catalog rather than the migration text, the contract that role\n-- lives under:\n--\n--   1. every application table has row-level security enabled;\n--   2. an RLS-enabled table has at least one policy that applies to the\n--      gateway role (RLS with no policy is default-deny: the app sees no rows);\n--   3. every verb a policy allows is GRANTed to harbour_app_gateway — a policy\n--      without its grant is a feature that fails with permission-denied only\n--      for real users (`poll_votes`, 2026-09-10);\n--   4. tables, views and sequences are granted only to their owner and to\n--      harbour_app_gateway; the platform creates no other role, so any other\n--      grantee (PUBLIC included) is a silent production no-op at best.\n--\n-- The platform's own schema harbour_runtime (the realtime outbox) is not the\n-- app's and is skipped. One script, executed by the pipeline's in-loop probe\n-- (packages/toolkit/transformbuild/containerprobe.go) and, byte for byte, by\n-- `harbour check` from /harbour/kit/database-gate.sql in the session fixture\n-- image. It raises one exception naming every violation on its own line, with\n-- the fix; a clean database returns silently.\n\\set ON_ERROR_STOP 1\n\\set VERBOSITY terse\nDO $harbour_gate$\nDECLARE\n  gateway CONSTANT text := 'harbour_app_gateway';\n  violations text[] := ARRAY[]::text[];\n  rec record;\n  verb text;\nBEGIN\n  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = gateway) THEN\n    RAISE EXCEPTION 'harbour database gate: the platform role % does not exist on this database; the probe bootstrap must create it before the migrations replay', gateway;\n  END IF;\n\n  -- 1. Row-level security on every application table.\n  FOR rec IN\n    SELECT n.nspname AS schema_name, c.relname AS table_name, c.relrowsecurity AS rls\n    FROM pg_class c\n    JOIN pg_namespace n ON n.oid = c.relnamespace\n    WHERE c.relkind IN ('r', 'p')\n      AND n.nspname NOT IN ('pg_catalog', 'information_schema', 'harbour_runtime')\n      AND n.nspname NOT LIKE 'pg\\_toast%' AND n.nspname NOT LIKE 'pg\\_temp%'\n    ORDER BY 1, 2\n  LOOP\n    IF NOT rec.rls THEN\n      violations := violations || format(\n        'table %I.%I: row-level security is not enabled, so every signed-in person would see every row — fix: ALTER TABLE %I.%I ENABLE ROW LEVEL SECURITY; then CREATE POLICY ... ON %I.%I USING (...) WITH CHECK (...)',\n        rec.schema_name, rec.table_name, rec.schema_name, rec.table_name, rec.schema_name, rec.table_name);\n    -- 2. A policy the gateway role is subject to.\n    ELSIF NOT EXISTS (\n      SELECT 1 FROM pg_policy p\n      JOIN pg_class c ON c.oid = p.polrelid\n      JOIN pg_namespace n ON n.oid = c.relnamespace\n      WHERE n.nspname = rec.schema_name AND c.relname = rec.table_name\n        AND (p.polroles = '{0}'::oid[] OR (SELECT oid FROM pg_roles WHERE rolname = gateway) = ANY (p.polroles))\n    ) THEN\n      violations := violations || format(\n        'table %I.%I: row-level security is enabled but no policy applies to %s, so the app sees no rows and every write is refused — fix: CREATE POLICY %I ON %I.%I USING (owner_subject = current_setting(''harbour.user_id'', true)) WITH CHECK (owner_subject = current_setting(''harbour.user_id'', true))',\n        rec.schema_name, rec.table_name, gateway, rec.table_name || '_owner', rec.schema_name, rec.table_name);\n    END IF;\n  END LOOP;\n\n  -- 3. Every verb a policy allows is granted to the gateway role.\n  FOR rec IN\n    SELECT n.nspname AS schema_name, c.relname AS table_name, c.oid AS table_oid, p.polname AS policy_name,\n           CASE p.polcmd WHEN 'r' THEN ARRAY['SELECT'] WHEN 'a' THEN ARRAY['INSERT'] WHEN 'w' THEN ARRAY['UPDATE'] WHEN 'd' THEN ARRAY['DELETE']\n                         ELSE ARRAY['SELECT', 'INSERT', 'UPDATE', 'DELETE'] END AS verbs,\n           p.polroles = '{0}'::oid[] OR (SELECT oid FROM pg_roles WHERE rolname = gateway) = ANY (p.polroles) AS applies,\n           (SELECT string_agg(r.rolname, ', ' ORDER BY r.rolname) FROM pg_roles r WHERE r.oid = ANY (p.polroles)) AS role_names\n    FROM pg_policy p\n    JOIN pg_class c ON c.oid = p.polrelid\n    JOIN pg_namespace n ON n.oid = c.relnamespace\n    WHERE n.nspname NOT IN ('pg_catalog', 'information_schema', 'harbour_runtime')\n    ORDER BY 1, 2, 4\n  LOOP\n    IF NOT rec.applies THEN\n      violations := violations || format(\n        'policy %I on %I.%I: applies to role(s) %s, not to %s, so the App Gateway never satisfies it — fix: recreate the policy without a TO clause (or add TO %s)',\n        rec.policy_name, rec.schema_name, rec.table_name, coalesce(rec.role_names, '(none)'), gateway, gateway);\n      CONTINUE;\n    END IF;\n    FOREACH verb IN ARRAY rec.verbs LOOP\n      IF NOT has_table_privilege(gateway, rec.table_oid, verb) THEN\n        violations := violations || format(\n          'policy %I on %I.%I: allows %s but %s is never GRANTed %s on it, so the feature fails with permission-denied for real users — fix: GRANT %s ON %I.%I TO %s',\n          rec.policy_name, rec.schema_name, rec.table_name, verb, gateway, verb, verb, rec.schema_name, rec.table_name, gateway);\n      END IF;\n    END LOOP;\n  END LOOP;\n\n  -- 4. Grants go only to the owner and the gateway role.\n  FOR rec IN\n    SELECT n.nspname AS schema_name, c.relname AS object_name,\n           CASE c.relkind WHEN 'S' THEN 'SEQUENCE' WHEN 'v' THEN 'VIEW' WHEN 'm' THEN 'VIEW' ELSE 'TABLE' END AS object_kind,\n           coalesce(g.rolname, 'PUBLIC') AS grantee,\n           string_agg(a.privilege_type, ', ' ORDER BY a.privilege_type) AS privileges\n    FROM pg_class c\n    JOIN pg_namespace n ON n.oid = c.relnamespace\n    CROSS JOIN LATERAL aclexplode(c.relacl) a\n    LEFT JOIN pg_roles g ON g.oid = a.grantee\n    WHERE c.relkind IN ('r', 'p', 'v', 'm', 'S')\n      AND n.nspname NOT IN ('pg_catalog', 'information_schema', 'harbour_runtime')\n      AND n.nspname NOT LIKE 'pg\\_toast%' AND n.nspname NOT LIKE 'pg\\_temp%'\n      AND a.grantee <> c.relowner\n      AND coalesce(g.rolname, '') <> gateway\n    GROUP BY 1, 2, 3, 4\n    ORDER BY 1, 2, 4\n  LOOP\n    violations := violations || format(\n      'grant %s on %s %I.%I to %s: only the platform role %s may be granted, the platform never creates %s — fix: REVOKE %s ON %s %I.%I FROM %s',\n      rec.privileges, lower(rec.object_kind), rec.schema_name, rec.object_name, rec.grantee, gateway, rec.grantee,\n      rec.privileges, rec.object_kind, rec.schema_name, rec.object_name, rec.grantee);\n  END LOOP;\n\n  IF coalesce(array_length(violations, 1), 0) > 0 THEN\n    RAISE EXCEPTION 'harbour database gate: % violation(s)%', array_length(violations, 1), E'\\n' || array_to_string(violations, E'\\n');\n  END IF;\nEND\n$harbour_gate$;\n";
+/**
+ * The gate script from the pinned session fixture image when the image is
+ * present locally and carries it (`docker create --pull never` + `docker cp`;
+ * the image is distroless, so there is no shell to cat it), else the vendored
+ * copy. Never pulls: `harbour check` must stay a local, seconds-long step.
+ */
+export async function loadDatabaseGate(bundle, run) {
+    const vendored = { sql: DATABASE_GATE_SQL, source: "vendored" };
+    const created = await run("docker", ["create", "--pull", "never", bundle.images.sessionFixture], { quiet: true });
+    const id = created.code === 0 ? created.stdout.trim().split("\n").at(-1)?.trim() ?? "" : "";
+    if (!id)
+        return vendored;
+    const dir = await mkdtemp(join(tmpdir(), "harbour-database-gate-"));
+    try {
+        const target = join(dir, "database-gate.sql");
+        const copied = await run("docker", ["cp", `${id}:${DATABASE_GATE_IMAGE_PATH}`, target], { quiet: true });
+        if (copied.code !== 0)
+            return vendored;
+        const sql = await readFile(target, "utf8").catch(() => undefined);
+        return sql && sql.includes("harbour database gate") ? { sql, source: "fixture" } : vendored;
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+        await run("docker", ["rm", "-f", id], { quiet: true });
+    }
+}
+/** The violation lines of a failed gate (`<table|policy|grant>: <problem> — fix: <statement>`), psql's framing dropped. */
+export function gateViolations(stderr) {
+    const lines = stderr.split("\n").map(line => line.trim()).filter(Boolean);
+    const start = lines.findIndex(line => line.includes("harbour database gate:"));
+    const body = (start >= 0 ? lines.slice(start + 1) : lines).filter(line => !/^(CONTEXT:|NOTICE:|DO$)/.test(line));
+    if (body.length)
+        return body;
+    if (start >= 0)
+        return [lines[start].replace(/^.*?ERROR:\s*/, "")];
+    return [lines.at(-1) ?? "psql error"];
+}

package/dist/packages/harbour-cli/src/dev.js

@@ -33,9 +33,14 @@ export async function startDev(root, options) {
         await runtime.pull(options.bundle);
         options.output("Starting local Harbour services (postgres, storage, realtime, identity fixture, app gateway).");
         await runtime.up();
+        // The fixture writes the session env and the app's realtime outbox
+        // migration together, so waiting for the session also waits for the SQL.
+        const session = await runtime.sessionEnv();
         const applied = await runtime.migrate();
         options.output(`Applied ${applied.length} migration file(s).`);
-        const session = await runtime.sessionEnv();
+        const watched = await runtime.installRealtimeOutbox();
+        if (watched > 0)
+            options.output(`Installed the Harbour realtime outbox for ${watched} table(s) (harbour.realtime change events).`);
         const origin = `http://127.0.0.1:${ports.origin}`;
         vite = spawn("npm", ["run", "dev"], { cwd: root, env: { ...env, HARBOUR_LOCAL_ORIGIN: origin, HARBOUR_VITE_PORT: String(ports.vite) }, stdio: ["ignore", "inherit", "inherit"] });
         vite.on("error", () => options.output("Vite could not be started; is npm installed and `npm install` done?"));

package/dist/packages/harbour-cli/src/forwarder.js

@@ -103,10 +103,22 @@ function pipe(request, response, port, extraHeaders = {}) {
     upstream.on("error", () => reject(response, 502, "UNAVAILABLE", "The local service is not responding."));
     request.pipe(upstream);
 }
+/**
+ * An upgrade keeps the browser's own `Host` — this origin's — instead of the
+ * internal target port. A WebSocket server's same-origin defence compares
+ * `Origin` against `Host`: the App Gateway's `websocket.Accept` answers
+ * `403 request Origin "…" is not authorized for Host "…"` when they differ, so
+ * rewriting `Host` to the gateway's published port broke `/_harbour/realtime`
+ * (live updates fell back to polling) while every plain `/_harbour/*` call, which
+ * has no such check, kept working. Both targets listen on loopback and route by
+ * path, never by `Host`, and `sameOrigin` above has already rejected anything
+ * whose `Host`/`Origin` is not exactly this origin — forwarding the real pair is
+ * what lets the gateway's check do its job rather than defeating it.
+ */
 function tunnel(request, socket, head, port, extraHeaders) {
     const upstream = connect(port, "127.0.0.1", () => {
         const lines = [`${request.method} ${request.url} HTTP/1.1`];
-        for (const [name, value] of Object.entries({ ...request.headers, ...extraHeaders, host: `127.0.0.1:${port}` }))
+        for (const [name, value] of Object.entries({ ...request.headers, ...extraHeaders }))
             if (value !== undefined)
                 for (const item of Array.isArray(value) ? value : [value])
                     lines.push(`${name}: ${item}`);

package/dist/packages/harbour-cli/src/kit-bundle.js

@@ -10,7 +10,7 @@ import { readFile } from "node:fs/promises";
  */
 export const EMBEDDED_KIT_BUNDLE = {
     schema: "harbour.kit-bundle/1.0",
-    kitVersion: "0.1.14",
+    kitVersion: "0.1.16",
     sdk: {
         package: "@harbour/app-sdk",
         version: "1.0.0",
@@ -18,8 +18,8 @@ export const EMBEDDED_KIT_BUNDLE = {
         url: "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:62954161ec29148c20223316d83367b781dd9291665ea16f74a003b16e304a3b"
     },
     images: {
-        appGateway: "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:387f51c7a824fc839044a2582fc3271acf2ff2b704d9ca6bb6d1edb06a845def",
-        sessionFixture: "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:a64025be110e592927b5c2a1ef5312e24624208e9427e74deb3873453512b0ca",
+        appGateway: "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:4c8d359ee18f1fa6f96dde80379fa30a3c5a7675b6e9c2150e56d5ec41ba3e7c",
+        sessionFixture: "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:32cbb4f1820fd84b9e790b8559db5aae632b3deb77a7de87b916f75a4ca37ddc",
         postgres: "postgres:16-alpine",
         minio: "minio/minio:RELEASE.2025-07-23T15-54-02Z",
         nats: "nats:2.11.17-alpine"

package/dist/packages/harbour-cli/src/local-runtime.js

@@ -1,8 +1,9 @@
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { createServer } from "node:net";
 import { join, relative } from "node:path";
+import { gateViolations } from "./database-gate.js";
 import { kitPaths, projectName } from "./kit.js";
 import { CliError } from "./output.js";
 export const runCommand = (command, args, options = {}) => new Promise(resolve => {
@@ -35,7 +36,9 @@ export const LOCAL = {
 /**
  * Compose file for one project: every port bound to 127.0.0.1, named volumes
  * prefixed with the project name, images pinned from the bundle manifest.
- * The fixture writes the session env (identity token) to the shared state dir.
+ * The fixture writes the session env (identity token) and the platform's
+ * realtime outbox migration (generated from the app's migrations, staged under
+ * state/migrations) to the shared state dir.
  */
 export function composeFile(project, bundle, ports, stateDir) {
     const images = bundle.images;
@@ -62,7 +65,7 @@ export function composeFile(project, bundle, ports, stateDir) {
         `    ports: ["127.0.0.1:${ports.nats}:4222"]`,
         "  fixture:",
         `    image: ${images.sessionFixture}`,
-        "    command: [\"--listen\", \"0.0.0.0:8080\", \"--session\", \"" + project + "\", \"--base-url\", \"http://127.0.0.1:" + ports.fixture + "\", \"--tenant\", \"" + LOCAL.tenant + "\", \"--app\", \"" + LOCAL.app + "\", \"--user-id\", \"" + LOCAL.userId + "\", \"--email\", \"" + LOCAL.email + "\", \"--metadata-file\", \"/state/session.json\", \"--env-file\", \"/state/session.env\", \"--display-directory\", \"" + stateDir + "\"]",
+        "    command: [\"--listen\", \"0.0.0.0:8080\", \"--session\", \"" + project + "\", \"--base-url\", \"http://127.0.0.1:" + ports.fixture + "\", \"--tenant\", \"" + LOCAL.tenant + "\", \"--app\", \"" + LOCAL.app + "\", \"--user-id\", \"" + LOCAL.userId + "\", \"--email\", \"" + LOCAL.email + "\", \"--metadata-file\", \"/state/session.json\", \"--env-file\", \"/state/session.env\", \"--display-directory\", \"" + stateDir + "\", \"--migrations-dir\", \"/state/migrations\", \"--realtime-outbox-file\", \"/state/realtime-outbox.sql\"]",
         "    environment:",
         `      HARBOUR_LOCAL_COMPOSE_PROJECT: ${project}`,
         `      HARBOUR_LOCAL_S3_INTERNAL_ENDPOINT: http://minio:9000`,
@@ -92,6 +95,26 @@ export function composeFile(project, bundle, ports, stateDir) {
         `    ports: ["127.0.0.1:${ports.gateway}:8080"]`,
         `    volumes: ["${stateDir}/app-gateway.json:/config/app-gateway.json:ro"]`,
         "    depends_on: { postgres: { condition: service_healthy }, minio: { condition: service_healthy }, fixture: { condition: service_started } }",
+        // The relay that moves committed rows from harbour_runtime.event_outbox to
+        // JetStream (docs/local-kit.md "Outbox relay container"): the hosted
+        // gateway starts it per app, the static local configuration does not.
+        // It shares the gateway's configuration and so fetches the fixture's JWKS
+        // before it reaches its own mode, even though a relay verifies no token:
+        // it therefore waits for the fixture like the gateway does, and restarts
+        // when it still wins the race (the fixture opens its listener only after
+        // its bucket is ready, so `service_started` is not `serving`).
+        "  outbox:",
+        `    image: ${images.appGateway}`,
+        "    environment:",
+        "      HARBOUR_APP_GATEWAY_MODE: outbox",
+        "      HARBOUR_APP_GATEWAY_CONFIG_FILE: /config/app-gateway.json",
+        "      HARBOUR_APP_GATEWAY_UPLOAD_KEY: " + uploadKey(project),
+        "      HARBOUR_NATS_URL: nats://nats:4222",
+        "      AWS_REGION: us-east-1",
+        "      AWS_EC2_METADATA_DISABLED: \"true\"",
+        `    volumes: ["${stateDir}/app-gateway.json:/config/app-gateway.json:ro"]`,
+        "    restart: on-failure",
+        "    depends_on: { postgres: { condition: service_healthy }, nats: { condition: service_started }, fixture: { condition: service_started } }",
         "volumes:",
         `  postgres-data: { name: ${project}-postgres }`,
         `  minio-data: { name: ${project}-minio }`,
@@ -122,6 +145,10 @@ export function gatewayConfig(ports) {
             }]
     };
 }
+/** `migrations/*.sql` in name order — what `harbour dev` applies and what the fixture derives the outbox from. */
+async function migrationNames(root) {
+    return (await readdir(join(root, "migrations")).catch(() => [])).filter(name => name.endsWith(".sql")).sort();
+}
 function internalDatabaseUrl(user = LOCAL.dbUser) { return `postgresql://${user}:${LOCAL.dbPassword}@postgres:5432/${LOCAL.database}?sslmode=disable`; }
 function uploadKey(project) { return createHash("sha256").update(`upload-key:${project}`).digest("base64"); }
 // ---- Ports and lock ------------------------------------------------------------------
@@ -197,6 +224,15 @@ export class LocalRuntime {
         await mkdir(paths.state, { recursive: true });
         await writeFile(paths.compose, composeFile(this.project, bundle, ports, paths.state));
         await writeFile(join(paths.state, "app-gateway.json"), `${JSON.stringify(gatewayConfig(ports), null, 2)}\n`);
+        // The fixture derives the realtime outbox from the app's migrations; they
+        // are staged into the state dir (already mounted at /state) rather than
+        // bind-mounting migrations/, which Docker would create as root if absent.
+        const staged = join(paths.state, "migrations");
+        await rm(staged, { recursive: true, force: true });
+        await mkdir(staged, { recursive: true });
+        for (const name of await migrationNames(this.root))
+            await copyFile(join(this.root, "migrations", name), join(staged, name));
+        await rm(join(paths.state, "realtime-outbox.sql"), { force: true });
     }
     /**
      * Pulls the pinned images before `up`, so a registry problem is named as such
@@ -230,8 +266,8 @@ export class LocalRuntime {
     /** Applies `migrations/*.sql` in name order through psql inside the postgres container, after ensuring the runtime role. */
     async migrate() {
         const dir = join(this.root, "migrations");
-        const names = (await readdir(dir).catch(() => [])).filter(name => name.endsWith(".sql")).sort();
-        const psql = (sql) => this.compose(["exec", "-T", "postgres", "psql", "-v", "ON_ERROR_STOP=1", "-U", LOCAL.dbUser, "-d", LOCAL.database], { stdin: sql, quiet: true });
+        const names = await migrationNames(this.root);
+        const psql = (sql) => this.psql(sql);
         const role = await psql(`DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${LOCAL.gatewayRole}') THEN CREATE ROLE ${LOCAL.gatewayRole} LOGIN PASSWORD '${LOCAL.dbPassword}'; END IF; END $$;`);
         if (role.code !== 0)
             throw new CliError("MIGRATION_FAILED", "Could not prepare the local database role.");
@@ -242,6 +278,35 @@ export class LocalRuntime {
         }
         return names;
     }
+    /**
+     * Runs the kit database gate (one psql script, see database-gate.ts) against
+     * this project's database after `migrate()`. Resolves to the violation lines,
+     * empty when the schema satisfies the App Gateway role's contract.
+     */
+    async databaseGate(sql) {
+        const result = await this.psql(sql);
+        return result.code === 0 ? [] : gateViolations(result.stderr);
+    }
+    psql(sql) {
+        return this.compose(["exec", "-T", "postgres", "psql", "-v", "ON_ERROR_STOP=1", "-U", LOCAL.dbUser, "-d", LOCAL.database], { stdin: sql, quiet: true });
+    }
+    /**
+     * Applies the platform's realtime outbox migration the session fixture
+     * generated for this app's tables (state/realtime-outbox.sql: the data
+     * plane's one generator, the same text the hosted pipeline appends to the
+     * app's bundle) — after the app's migrations, idempotent on every start.
+     * Returns the number of watched tables; 0 when the app has no tables.
+     */
+    async installRealtimeOutbox() {
+        const path = join(kitPaths(this.root).state, "realtime-outbox.sql");
+        const sql = await readFile(path, "utf8").catch(() => "");
+        if (!sql.trim())
+            return 0;
+        const result = await this.psql(sql);
+        if (result.code !== 0)
+            throw new CliError("MIGRATION_FAILED", `The realtime outbox migration failed: ${result.stderr.trim().split("\n").at(-1) ?? "psql error"}`);
+        return (sql.match(/harbour_runtime\.watch_table\(/g) ?? []).length;
+    }
     /** The fixture's session env (identity token for the local app user) once the fixture has written it. */
     async sessionEnv(attempts = 60) {
         const path = join(kitPaths(this.root).state, "session.env");

package/dist/packages/harbour-cli/src/productionise.js

@@ -11,6 +11,7 @@ import { CLI_VERSION } from "./version.js";
 import { isProhibitedSecretPath } from "../../../src/secret-paths.js";
 import { assertPreviewIntegrationsReady } from "./integrations.js";
 import { recordKitAppId } from "./kit.js";
+import { preflightDatabaseGate } from "./check.js";
 export async function productionise(rootArg, client, output, tenantId, includePaths = [], options = {}) {
     const root = resolve(rootArg);
     output(`Harbour is checking ${basename(root)}.`);
@@ -26,6 +27,12 @@ export async function productionise(rootArg, client, output, tenantId, includePa
     // A declared connection without its preview grant would only park the
     // deployment after the save; refuse here, before any operation exists.
     const kitAppId = options.integrations ? await assertPreviewIntegrationsReady(root, options.integrations.governance, tenantId, options.integrations.bundle, output) : options.appId;
+    // A kit migration set the pipeline's database gate would refuse (a table
+    // without RLS, a policy verb never granted, a grant to a role the platform
+    // never creates) is refused here, before the save, with the same wording.
+    const gate = options.databaseGate === false ? undefined : options.databaseGate ?? (options.integrations ? { bundle: options.integrations.bundle } : undefined);
+    if (gate)
+        await preflightDatabaseGate(root, gate.bundle, output, gate.run);
     try {
         await client.initialize();
     }

package/dist/packages/harbour-cli/src/starter.js

@@ -1,12 +1,15 @@
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { bundleDiff } from "./kit-bundle.js";
+import { agentSetup, MANAGED_END, MANAGED_START, upsertManagedBlock } from "./agent-setup.js";
 import { newKitLock, readKitLock, writeKitLock } from "./kit.js";
 import { CliError } from "./output.js";
+export { MANAGED_END, MANAGED_START };
 /**
  * Creates the starter in an empty directory, or adds the missing kit files to
  * an existing Vite + React app. User files are never overwritten: a path that
- * exists is reported as kept. Instruction files get a managed block appended.
+ * exists is reported as kept. Instruction files get a managed block appended, and
+ * the user-level agent guide is installed so the agents know the kit from any folder.
  */
 export async function initKit(root, bundle, options = {}) {
     await mkdir(root, { recursive: true });
@@ -14,7 +17,7 @@ export async function initKit(root, bundle, options = {}) {
     const emptyDir = !existingPackage && !(await exists(join(root, "src")));
     if (existingPackage && !isSupportedApp(existingPackage))
         throw new CliError("APP_UNSUPPORTED", "harbour init supports an empty directory or an existing Vite + React app (package.json must depend on vite and react).");
-    const result = { root, created: [], kept: [], updated: [], mode: options.upgrade ? "upgrade" : emptyDir ? "starter" : "existing", bundleChanges: [] };
+    const result = { root, created: [], kept: [], updated: [], mode: options.upgrade ? "upgrade" : emptyDir ? "starter" : "existing", bundleChanges: [], agents: options.env ? await agentSetup(options.env) : { created: [], updated: [], kept: [] } };
     const write = async (path, content) => {
         const absolute = join(root, path);
         if (await exists(absolute)) {
@@ -56,35 +59,26 @@ function isSupportedApp(pkg) {
 }
 async function appendManaged(root, file, block, result, separator, start, end) {
     const absolute = join(root, file);
+    if (start && end) {
+        result[await upsertManagedBlock(absolute, block, { start, end, separator })].push(file);
+        return;
+    }
     const current = await readFile(absolute, "utf8").catch(() => undefined);
     if (current === undefined) {
         await writeFile(absolute, `${block}\n`);
         result.created.push(file);
         return;
     }
-    if (start && end && current.includes(start) && current.includes(end)) {
-        const next = current.replace(new RegExp(`${escape(start)}[\\s\\S]*?${escape(end)}`), block);
-        if (next !== current) {
-            await writeFile(absolute, next);
-            result.updated.push(file);
-        }
-        else
-            result.kept.push(file);
-        return;
-    }
-    if (!start && block.split("\n").every(line => current.split("\n").includes(line))) {
+    if (block.split("\n").every(line => current.split("\n").includes(line))) {
         result.kept.push(file);
         return;
     }
     await writeFile(absolute, `${current.replace(/\n*$/, "")}${separator}${block}\n`);
     result.updated.push(file);
 }
-const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 const exists = (path) => stat(path).then(() => true, () => false);
 const readJson = (path) => readFile(path, "utf8").then(text => JSON.parse(text), () => undefined);
 // ---- Templates -----------------------------------------------------------------
-export const MANAGED_START = "<!-- harbour:kit:start -->";
-export const MANAGED_END = "<!-- harbour:kit:end -->";
 const GITIGNORE_LINES = ["node_modules/", "dist/", ".harbour/local/"].join("\n");
 /** Condensed from the pipeline briefs (browser-sdk-to-harbour, route-auth-policy, auth-local-to-harbour-sso) for a kit app. */
 export function managedBlock() {
@@ -101,9 +95,9 @@ export function managedBlock() {
         "- Authentication is owned by Harbour SSO. Do not add login forms, JWT handling, or trust a role, owner id or tenant id supplied by the browser. Row ownership is decided in SQL through `current_setting('harbour.user_id', true)` and `current_setting('harbour.user_email', true)`.",
         "- Every route needs a signed-in human by default; do not add public routes or wildcard exceptions to make something work.",
         "- No secrets, tokens, `.env` values or fetched company content in source. `.harbour/local/` is ignored and never committed; `.harbour/integrations.json` and `.harbour/kit.lock.json` are committed.",
-        "- Schema changes are SQL files in `migrations/`, applied by `harbour dev` and `harbour check`. Grant browser-path table privileges to `harbour_app_gateway`.",
-        "- Commands: `harbour dev --app-root .` (local runtime), `harbour check --app-root .` (declaration, types, build, migrations, journeys), `harbour integrations request <connection> --reason <text> --app-root .`, `harbour integrations status --app-root .`, `harbour productionise --app-root .`. Company calls in `dev` use the account from `harbour login`; the local fixture user is only the app's identity.",
-        "- Codex reads this AGENTS.md block; Claude Code also reads `.claude/skills/harbour-kit/SKILL.md`.",
+        "- Schema changes are SQL files in `migrations/`, applied by `harbour dev` and `harbour check`. Every table: ENABLE ROW LEVEL SECURITY + a policy; GRANT every verb a policy allows to `harbour_app_gateway` and to no other role — `harbour check` runs the pipeline's database gate and names any table/policy/grant that breaks this, with the fix.",
+        "- Commands: `harbour dev --app-root .` (local runtime), `harbour check --app-root .` (declaration, types, build, migrations + the pipeline's database gate, journeys), `harbour integrations request <connection> --reason <text> --app-root .`, `harbour integrations status --app-root .`, `harbour productionise --app-root .`. Company calls in `dev` use the account from `harbour login`; the local fixture user is only the app's identity.",
+        "- Codex reads this AGENTS.md block; Claude Code also reads `.claude/skills/harbour-kit/SKILL.md`. The plain-English workflow (what to run when the person says \"run it\", \"check it\", \"ship it\") is in the user-level `isomorph` skill / `~/.codex/AGENTS.md` block installed by `harbour agent-setup`.",
         MANAGED_END
     ].join("\n");
 }

package/dist/packages/harbour-cli/src/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "0.1.14";
+export const CLI_VERSION = "0.1.17";

package/dist/src/analyzer.js

@@ -4,7 +4,7 @@ import { existsSync } from "node:fs";
 import { lstat, readFile, readdir, stat } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { sha256 } from "./digest.js";
-import { isEnvExamplePath, isSourceIntakeExcludedPath } from "./secret-paths.js";
+import { isEnvExamplePath, isKitCommittedPath, isSourceIntakeExcludedPath } from "./secret-paths.js";
 const ANALYZER_VERSION = "0.1.0";
 const MAX_FILES = 600;
 const MAX_FILE_BYTES = 256_000;
@@ -12,8 +12,9 @@ const MAX_FILE_BYTES = 256_000;
 // application files. Keeping them out also makes reruns idempotent after a
 // previous save has written a receipt into the selected workspace.
 const IGNORED_DIRS = new Set([".git", ".harbour", ".next", ".nuxt", ".svelte-kit", ".turbo", "coverage", "dist", "build", "node_modules", "vendor"]);
-/** The development kit commits exactly these two files under `.harbour`; everything else there (local state, checks evidence, generated control files) stays out of the package. */
-const KIT_COMMITTED_FILES = new Set([".harbour/integrations.json", ".harbour/kit.lock.json"]);
+/** The development kit commits its declaration, lock and journey checks under `.harbour` (see `isKitCommittedPath`); everything else there (local state, checks evidence, generated control files) stays out of the package. */
+const KIT_CONTROL_FILES = [".harbour/integrations.json", ".harbour/kit.lock.json"];
+const KIT_CHECKS_DIR = ".harbour/checks";
 const SECRET_FILE_NAMES = new Set([".env", ".env.local", ".env.production", ".env.development", ".npmrc"]);
 const TEXT_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".json", ".html", ".css", ".py", ".rb", ".go", ".rs", ".java", ".cs", ".php", ".md", ".toml", ".yaml", ".yml", ".sh"]);
 function normalizeIncludePath(value) {
@@ -29,7 +30,7 @@ function normalizeIncludePath(value) {
 async function collectIncludedFiles(root, includePaths, output, unknowns) {
     const normalized = [...new Set(includePaths.map(normalizeIncludePath))];
     for (const include of normalized) {
-        if (include.split("/").some(part => IGNORED_DIRS.has(part)) && !KIT_COMMITTED_FILES.has(include))
+        if (include.split("/").some(part => IGNORED_DIRS.has(part)) && !isKitCommittedPath(include))
             continue;
         const absolute = include ? join(root, ...include.split("/")) : root;
         let info;
@@ -87,7 +88,20 @@ async function collectFiles(root, current, output, unknowns) {
     }
 }
 async function collectKitFiles(root, output) {
-    for (const path of [...KIT_COMMITTED_FILES].sort()) {
+    const paths = [...KIT_CONTROL_FILES];
+    let checks = [];
+    try {
+        checks = await readdir(join(root, ...KIT_CHECKS_DIR.split("/")), { withFileTypes: true });
+    }
+    catch {
+        checks = [];
+    }
+    for (const entry of checks) {
+        const path = `${KIT_CHECKS_DIR}/${entry.name}`;
+        if (isKitCommittedPath(path))
+            paths.push(path);
+    }
+    for (const path of paths.sort()) {
         const absolute = join(root, ...path.split("/"));
         let info;
         try {

package/dist/src/secret-paths.js

@@ -17,11 +17,17 @@ export function isSourceIntakeExcludedPath(path) {
     return /(^|\/)(?:__MACOSX)(?:\/|$)|(^|\/)\.DS_Store$/i.test(path)
         || /(^|\/)\.github\/workflows\//i.test(path);
 }
-/** The development kit commits exactly these two files under `.harbour`; everything else there stays local. */
+/**
+ * The development kit commits exactly these files under `.harbour`: the
+ * integrations declaration, the kit lock, and the journey checks directly in
+ * `.harbour/checks/` as `.mjs`, `.js` or `.cjs` modules (no subdirectories, no
+ * other extensions — evidence and reports written next to them stay local).
+ * Everything else there (local state, generated control files) stays local.
+ */
 export function isKitCommittedPath(path) {
-    return /(^|\/)\.harbour\/(?:integrations\.json|kit\.lock\.json)$/.test(path);
+    return /(^|\/)\.harbour\/(?:integrations\.json|kit\.lock\.json|checks\/[^/]+\.(?:mjs|js|cjs))$/.test(path);
 }
-/** Dependency and internal directories the intake never stages — `.harbour` except its two committed kit files. */
+/** Dependency and internal directories the intake never stages — `.harbour` except its committed kit files. */
 export function isInternalSourcePath(path) {
     return /(^|\/)(?:node_modules|\.git)(?:\/|$)/i.test(path) || (/(^|\/)\.harbour(?:\/|$)/i.test(path) && !isKitCommittedPath(path));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour",
-  "version": "0.1.14",
+  "version": "0.1.17",
   "description": "Harbour productionisation helper",
   "type": "module",
   "bin": { "harbour": "./dist/packages/harbour-cli/src/cli.js" },