@fourier-labs/harbour 0.1.21 → 0.1.22

package/README.md

@@ -10,7 +10,11 @@ You describe the app in plain English inside Claude Code or Codex; the agent ins
 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:
+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.
+
+That `npx` line runs the current release, but `harbour init`, `dev` and `check` afterwards run whatever `harbour` is installed on this machine. So `agent-setup` also compares the two and says, in its output and in `result.cli` of `--json` (`state`, `upgradeRequired`, `remediation`), when the installed CLI is missing or behind — a stale one carries an old kit bundle and builds an app the deployment pipeline refuses. The fix is always `npm i -g @fourier-labs/harbour@stable`.
+
+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.
@@ -23,7 +27,7 @@ The only step you do yourself is the company sign-in: when the agent runs `harbo
 ## Commands
 
 ```
-harbour agent-setup                                        install the agent guide (Claude Code skill + Codex AGENTS.md block); idempotent
+harbour agent-setup                                        install the agent guide (Claude Code skill + Codex AGENTS.md block); idempotent; reports a missing or stale installed CLI
 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

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

@@ -1,8 +1,15 @@
+import { execFile } from "node:child_process";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { CLI_VERSION } from "./version.js";
+const execFileAsync = promisify(execFile);
 export const MANAGED_START = "<!-- harbour:kit:start -->";
 export const MANAGED_END = "<!-- harbour:kit:end -->";
+/** The one command that installs or upgrades the CLI; every instruction in the kit names this tag. */
+export const CLI_INSTALL_COMMAND = "npm i -g @fourier-labs/harbour@stable";
 /** 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();
@@ -14,15 +21,92 @@ export function agentPaths(env = process.env) {
 /**
  * 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.
+ * in that file is kept). Idempotent: unchanged files are reported as kept. Also
+ * reports which `harbour` the agent's next command will run (`result.cli`), because
+ * this command is routinely reached through `npx` while everything after it is not.
  */
-export async function agentSetup(env = process.env) {
+export async function agentSetup(env = process.env, lookups = {}) {
     const paths = agentPaths(env);
-    const result = { created: [], updated: [], kept: [] };
+    const result = { created: [], updated: [], kept: [], cli: await checkCliVersion(lookups) };
     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;
 }
+/** Compares the globally resolvable `harbour` with the package this process runs from. */
+export async function checkCliVersion(lookups = {}) {
+    const running = await (lookups.runningCliVersion ?? runningPackageVersion)();
+    // No `harbour` on PATH, output with no version in it, a non-zero exit or a hang all
+    // mean the same thing: there is no installed CLI whose version can be trusted.
+    const installed = parseVersion(await (lookups.installedCliVersion ?? installedCliVersion)() ?? "");
+    const consequence = "carries an old kit bundle, so the app it creates passes every local check and is then refused by the deployment pipeline (kit_bundle_incompatible)";
+    if (!installed)
+        return { running, state: "missing", upgradeRequired: true, remediation: CLI_INSTALL_COMMAND, message: `No \`harbour\` command is installed on this machine; this package is ${running}. \`harbour init\`, \`dev\` and \`check\` run the installed CLI, not this one, and a missing or stale CLI ${consequence}.` };
+    const order = compareCliVersions(installed, running);
+    if (order < 0)
+        return { running, installed, state: "stale", upgradeRequired: true, remediation: CLI_INSTALL_COMMAND, message: `The installed \`harbour\` command is ${installed}, older than this package (${running}). \`harbour init\`, \`dev\` and \`check\` run the installed CLI, not this one, and a stale CLI ${consequence}.` };
+    if (order > 0)
+        return { running, installed, state: "ahead", upgradeRequired: false, message: `The installed \`harbour\` command is ${installed}, newer than this package (${running}); the installed one is what runs.` };
+    return { running, installed, state: "current", upgradeRequired: false, message: `The installed \`harbour\` command is ${installed}, the same version as this package.` };
+}
+/** What `agent-setup` and `init` print about the installed CLI; an upgrade is impossible to miss in a scrolling log. */
+export function cliVersionLines(check) {
+    if (!check.upgradeRequired)
+        return [check.message];
+    return ["", "!!! UPGRADE THE HARBOUR CLI BEFORE `harbour init` OR ANY OTHER HARBOUR COMMAND !!!", check.message, `Run: ${check.remediation}`, ""];
+}
+/** Numeric-core semver order; a prerelease sorts before its release. An unparseable version compares equal, so nothing is called stale on a guess. */
+export function compareCliVersions(left, right) {
+    const parse = (value) => {
+        const match = /^\s*v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(value);
+        return match ? { core: [Number(match[1]), Number(match[2]), Number(match[3])], pre: match[4] } : undefined;
+    };
+    const a = parse(left);
+    const b = parse(right);
+    if (!a || !b)
+        return 0;
+    for (let index = 0; index < 3; index += 1)
+        if (a.core[index] !== b.core[index])
+            return a.core[index] < b.core[index] ? -1 : 1;
+    if (a.pre === b.pre)
+        return 0;
+    if (a.pre === undefined)
+        return 1;
+    if (b.pre === undefined)
+        return -1;
+    return a.pre < b.pre ? -1 : 1;
+}
+/** Whatever the globally resolvable `harbour` prints for `--version`; undefined when running it is not possible at all. */
+async function installedCliVersion() {
+    try {
+        const { stdout } = await execFileAsync("harbour", ["--version"], { timeout: 20_000, windowsHide: true });
+        return stdout;
+    }
+    catch (error) {
+        return error.stdout;
+    }
+}
+function parseVersion(text) {
+    return /(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/.exec(text.trim())?.[1];
+}
+/**
+ * The version of the package this process runs from: the nearest package.json named
+ * `@fourier-labs/harbour`, walking up from this file. That is `packages/harbour-cli/`
+ * in the repository and the package root once published (the entry point is
+ * `dist/packages/harbour-cli/src/cli.js`), so no environment variable is involved.
+ */
+async function runningPackageVersion() {
+    let directory = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 12; depth += 1) {
+        const manifest = await readFile(join(directory, "package.json"), "utf8").then(text => JSON.parse(text), () => undefined);
+        if (manifest?.name === "@fourier-labs/harbour" && typeof manifest.version === "string")
+            return manifest.version;
+        const parent = dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return CLI_VERSION;
+}
 /**
  * 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
@@ -60,7 +144,7 @@ The person you are working with may not be a developer. They say what they want
 
 ## 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.
+1. CLI, before \`harbour init\` or anything else: compare the installed CLI with the current release and upgrade it whenever it is behind. A CLI that merely runs is not good enough — only a current one is. \`harbour agent-setup\` prints both versions and says plainly when the installed one is missing or older (its \`--json\` result carries \`cli.upgradeRequired\` and \`cli.remediation\`); without that output, compare \`harbour --version\` with \`npx -y @fourier-labs/harbour@stable --version\` yourself. If either says the installed one is missing or older, run \`npm i -g @fourier-labs/harbour@stable\` and confirm \`harbour --version\` now matches, then continue. Every later command runs the *installed* CLI, so a stale one builds an app that passes every local check and is then refused by the deployment pipeline (\`kit_bundle_incompatible\`) minutes later, with nothing in the app to fix. 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.
 
@@ -68,7 +152,7 @@ The person you are working with may not be a developer. They say what they want
 
 - "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.
+- "I need Slack / Gmail / the warehouse / company data" → a fresh \`harbour init\` declares no connection at all, which is why a new app ships with nothing waiting on IT. 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.

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

@@ -9,7 +9,7 @@ import { connect, loadConfig, resolveConfig } from "./config.js";
 import { EMBEDDED_KIT_BUNDLE } from "./kit-bundle.js";
 import { appRoot } from "./kit.js";
 import { initKit } from "./starter.js";
-import { agentPaths, agentSetup } from "./agent-setup.js";
+import { agentPaths, agentSetup, cliVersionLines } from "./agent-setup.js";
 import { startDev } from "./dev.js";
 import { ensureSdk, LocalRuntime, readDevLock, releaseDevLock, runCommand } from "./local-runtime.js";
 import { runChecks } from "./check.js";
@@ -91,10 +91,15 @@ else if (!command || command === "help" || command === "--help" || args.includes
 }
 else if (command === "agent-setup") {
     const result = await agentSetup(process.env);
-    for (const [state, paths] of Object.entries(result))
-        for (const path of paths)
+    for (const state of ["created", "updated", "kept"])
+        for (const path of result[state])
             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.");
+    // Which `harbour` the next command will run. This command is usually reached through
+    // `npx …@stable`, which tells you nothing about the CLI that does the actual work.
+    if (result.cli)
+        for (const line of cliVersionLines(result.cli))
+            progress(line);
     emit(summaryEnvelope({ ...result, paths: agentPaths(process.env) }));
 }
 else if (!["connect", "login", "logout", "productionise", "integrations", ...LOCAL_COMMANDS, ...OPERATION_COMMANDS].includes(command)
@@ -126,6 +131,11 @@ else {
                 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);
+                // Silent while the installed CLI is current; loud when `init` came from a
+                // newer package than the CLI that will run `dev`, `check` and `productionise`.
+                if (result.agents.cli?.upgradeRequired)
+                    for (const line of cliVersionLines(result.agents.cli))
+                        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);
                 if (sdk === "missing")

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

@@ -90,6 +90,7 @@ export function managedBlock() {
         "",
         "- Identity, data and files go through `@harbour/app-sdk` only: `harbour.identity.current()`, `harbour.data.from(table)`, `harbour.files.*`. Never open a database, storage bucket or company system from browser code, and never `fetch` a company URL directly.",
         "- Company systems (Slack, Gmail, warehouse views) are reached only through `harbour.integrations.execute(connection, {operation, resource, input})` with the connection and operation declared in `.harbour/integrations.json`. Operations are a closed set: `slack.channel.history` (user identity), `slack.message.post` (app identity), `gmail.thread.list` and `gmail.message.read` (user identity, read-only, resource `inbox`), `warehouse.view.read` (app identity). Resources are logical names, never IDs, URLs or tokens.",
+        "- `.harbour/integrations.json` starts with `\"connections\": {}` and stays that way until the app really calls a company system. Adding one is two steps: declare the connection with only the operations the app calls, then `harbour integrations request <connection> --reason \"<why>\" --app-root .` (and the same command with `--environment preview` before shipping). Every declared connection blocks the deploy until IT grants it, so a connection the app does not call is a deploy that never happens; a connection that is not declared cannot be requested at all (`CONNECTION_NOT_DECLARED`), so it never gets a grant. The file is strict JSON and cannot hold comments; the worked Slack and warehouse examples are in README.md and in the comment in `src/App.tsx`.",
         "- A Slack message is sent only after the person presses an explicit Send control; pass a fresh UUID `idempotencyKey` per send action and reuse the same key when retrying that action. Never send from an effect, a timer or a background queue, and never send during checks.",
         "- Consent is a user action: call `harbour.integrations.connect(connection)` and, when it returns `consent_required`, open `authorizationUrl`. Missing consent never falls back to another account.",
         "- 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)`.",
@@ -109,21 +110,22 @@ description: Build, run and check this Harbour app with the Harbour CLI (dev, ch
 Follow the "Harbour development kit" block in CLAUDE.md / AGENTS.md. Workflow:
 
 1. \`harbour dev --app-root .\` starts Postgres, storage and one Harbour gateway (session identities, fixtures, realtime) plus Vite behind one loopback origin printed in the banner.
-2. Edit \`src/\`, \`migrations/\` and \`.harbour/integrations.json\`. Use the SDK only; declare integrations before calling them.
+2. Edit \`src/\` and \`migrations/\`. Use the SDK only. \`.harbour/integrations.json\` starts with no connections and gains one only when the app really calls a company system: declare it with only the operations the app calls, then request access (step 4). A declared connection the app does not call blocks every deploy until IT grants it; an undeclared one cannot be requested, so it never gets a grant. README.md has the worked Slack and warehouse examples — the file itself is strict JSON and cannot hold comments.
 3. \`harbour check --app-root .\` before every hand-off; read \`.harbour/local/check-report.json\`. Real integrations are reported as not tested unless \`--integrations\` is passed (read operations only).
 4. \`harbour integrations request <connection> --reason "<why>" --app-root .\` asks IT for development access; pending is not ready.
 5. \`harbour productionise --app-root .\` saves and deploys the preview; \`harbour promote\` after the person has tested it.
 `;
 function kitFiles() {
     return {
-        ".harbour/integrations.json": `${JSON.stringify({
-            schema: "harbour.app-integrations/2.0",
-            connections: {
-                // Only connections the app really calls belong here: productionise
-                // refuses to deploy until every declared one has a preview grant.
-                "company-slack": { kind: "saas", operations: { "slack.channel.history": { identity: "user", resources: ["team-updates"] }, "slack.message.post": { identity: "app", resources: ["team-updates"] } } }
-            }
-        }, null, 2)}\n`,
+        // No connection. The starter calls no company system, and a connection the
+        // app does not call is a deploy that never happens: `harbour productionise`
+        // refuses to start until every declared connection holds a preview grant
+        // from IT. One is added when the app really calls it — the two steps and the
+        // worked Slack and warehouse examples are in README.md, in the "Harbour
+        // development kit" block of AGENTS.md / CLAUDE.md and in src/App.tsx. They
+        // are not in this file: it is read with JSON.parse here and again by the
+        // pipeline's source intake, so it cannot carry comments.
+        ".harbour/integrations.json": `${JSON.stringify({ schema: "harbour.app-integrations/2.0", connections: {} }, null, 2)}\n`,
         "migrations/0001_notes.sql": MIGRATION,
         // One retained check per capability the starter's UI uses: the pipeline's
         // flow gate refuses an app whose checks never exercise a declared capability.
@@ -152,10 +154,51 @@ function starterFiles(bundle) {
         "src/main.tsx": `import { StrictMode } from "react";\nimport { createRoot } from "react-dom/client";\nimport { App } from "./App";\n\ncreateRoot(document.getElementById("root")!).render(<StrictMode><App /></StrictMode>);\n`,
         "src/harbour.client.ts": HARBOUR_CLIENT,
         "src/App.tsx": APP,
-        "src/SlackPanel.tsx": SLACK_PANEL,
-        "README.md": "# Harbour app\n\nCreated by `harbour init`. Run `harbour dev --app-root .` and open the printed origin. See CLAUDE.md / AGENTS.md for the kit rules.\n\n`.harbour/checks/` holds one journey per capability the app uses (`notes-journey.mjs` for data, `files-journey.mjs` for files) and `notes-cross-user.mjs`, which proves a second signed-in person cannot read, update or delete another person's note — the same denial the deployment pipeline's write probe asserts; `harbour check` and the deployment pipeline refuse an app whose checks never exercise an operation its own code performs, so a new feature needs its own retained check.\n\n`.harbour/integrations.json` declares `company-slack` only. Declare a connection only when the app calls it: `harbour productionise` refuses to deploy until every declared connection has a preview grant (`harbour integrations request <connection> --environment preview --reason \"<why>\" --app-root .`). The warehouse example (`sales-warehouse` / `warehouse.view.read`) is in a comment in `src/App.tsx`.\n"
+        "README.md": STARTER_README
     };
 }
+const STARTER_README = `# Harbour app
+
+Created by \`harbour init\`. Run \`harbour dev --app-root .\` and open the printed origin. See CLAUDE.md / AGENTS.md for the kit rules.
+
+\`.harbour/checks/\` holds one journey per capability the app uses (\`notes-journey.mjs\` for data, \`files-journey.mjs\` for files) and \`notes-cross-user.mjs\`, which proves a second signed-in person cannot read, update or delete another person's note — the same denial the deployment pipeline's write probe asserts; \`harbour check\` and the deployment pipeline refuse an app whose checks never exercise an operation its own code performs, so a new feature needs its own retained check.
+
+## Adding a company system (Slack, Gmail, a warehouse view)
+
+\`.harbour/integrations.json\` ships with no connections:
+
+\`\`\`json
+{ "schema": "harbour.app-integrations/2.0", "connections": {} }
+\`\`\`
+
+That is deliberate. Every declared connection blocks the deploy until IT grants it — \`harbour productionise\` refuses to start while one is missing — so a connection the app does not call is a deploy that never happens. The file is strict JSON and cannot hold comments, which is why this note lives here.
+
+Add one in two steps, when the app really calls it:
+
+1. Declare the connection and only the operations the app calls, under \`connections\`. Slack:
+
+   \`\`\`json
+   "company-slack": { "kind": "saas", "operations": { "slack.channel.history": { "identity": "user", "resources": ["team-updates"] }, "slack.message.post": { "identity": "app", "resources": ["team-updates"] } } }
+   \`\`\`
+
+   A warehouse view:
+
+   \`\`\`json
+   "sales-warehouse": { "kind": "database", "operations": { "warehouse.view.read": { "identity": "app", "resources": { "weekly_sales": { "columns": ["week", "total"] } } } } }
+   \`\`\`
+
+2. Ask IT for access: \`harbour integrations request <connection> --reason "<why>" --app-root .\` for local development, and the same command with \`--environment preview\` for the preview grant every declared connection needs before \`harbour productionise\` will deploy. \`harbour integrations status --app-root .\` says where each request stands; PENDING is not ready.
+
+Then call it from the app through \`integrations()\` in \`src/harbour.client.ts\`:
+
+\`\`\`ts
+const report = await integrations().execute<{ rows: Array<{ week: string; total: number }> }>("sales-warehouse", {
+  operation: "warehouse.view.read", resource: "weekly_sales", input: { columns: ["week", "total"], limit: 100 }
+});
+\`\`\`
+
+A send (\`slack.message.post\`) runs only when the person presses an explicit Send control, with a fresh UUID \`idempotencyKey\` per press — never from an effect, a timer or a check. Consent is a user action: \`integrations().connect(connection)\`, and open its \`authorizationUrl\` when it answers \`consent_required\`. Anything the app calls needs its own retained check under \`.harbour/checks/\`.
+`;
 const VITE_CONFIG = `import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
 
@@ -187,7 +230,12 @@ export type Integrations = {
   execute<T>(connection: string, call: IntegrationCall): Promise<T>;
 };
 
-/** Typed access to the SDK's integrations surface (kit bundle SDK); throws a clear error on an older SDK. */
+/**
+ * Typed access to the SDK's integrations surface (kit bundle SDK); throws a clear
+ * error on an older SDK. The starter calls no company system, so nothing uses this
+ * yet: it is the entry point for the first one you add (declare the connection in
+ * .harbour/integrations.json, then \`harbour integrations request\` — see README.md).
+ */
 export function integrations(): Integrations {
   const surface = (harbour as { integrations?: Integrations }).integrations;
   if (!surface) throw new Error("This @harbour/app-sdk build has no integrations surface; run harbour init --upgrade.");
@@ -202,7 +250,6 @@ export function errorCode(error: unknown): string {
 const APP = `import { useCallback, useEffect, useState } from "react";
 import type { HarbourUser } from "@harbour/app-sdk";
 import { harbour } from "./harbour.client";
-import { SlackPanel } from "./SlackPanel";
 
 type Note = { id: number; title: string; done: boolean; created_at: string };
 type StoredFile = { path?: string; name?: string; size?: number };
@@ -237,13 +284,22 @@ export function App() {
   const remove = async (note: Note) => { await harbour.data.from("notes").delete().eq("id", note.id); await loadNotes(); };
   const upload = async (file: File) => { await harbour.files.upload(\`private/\${file.name}\`, file); await loadFiles(); };
 
-  // Warehouse example. Declare the connection in .harbour/integrations.json first —
-  // every declared connection needs a preview grant before productionise will deploy:
-  //   "sales-warehouse": { "kind": "database", "operations": { "warehouse.view.read": { "identity": "app", "resources": { "weekly_sales": { "columns": ["week", "total"] } } } } }
-  // then request access (harbour integrations request sales-warehouse --reason "<why>" --app-root .) and uncomment:
+  // Company systems are not part of the starter: .harbour/integrations.json declares
+  // nothing, so nothing about this app waits on IT. Add one only when the app really
+  // calls it, in two steps (README.md has the same two steps in full).
+  // 1. Declare the connection and only the operations this app calls, under
+  //    "connections" in .harbour/integrations.json — every declared connection blocks
+  //    the deploy until IT grants it:
+  //      "sales-warehouse": { "kind": "database", "operations": { "warehouse.view.read": { "identity": "app", "resources": { "weekly_sales": { "columns": ["week", "total"] } } } } }
+  //      "company-slack": { "kind": "saas", "operations": { "slack.channel.history": { "identity": "user", "resources": ["team-updates"] }, "slack.message.post": { "identity": "app", "resources": ["team-updates"] } } }
+  // 2. Request access (harbour integrations request sales-warehouse --reason "<why>" --app-root .,
+  //    and again with --environment preview before harbour productionise), then import
+  //    { integrations } from "./harbour.client" and uncomment:
   // const report = await integrations().execute<{ rows: Array<{ week: string; total: number }> }>("sales-warehouse", {
   //   operation: "warehouse.view.read", resource: "weekly_sales", input: { columns: ["week", "total"], limit: 100 }
   // });
+  // A Slack send runs only when the person presses an explicit Send control, with a
+  // fresh UUID idempotencyKey per press — never from an effect, a timer or a check.
 
   return (
     <main style={{ fontFamily: "system-ui", maxWidth: 720, margin: "2rem auto", padding: "0 1rem" }}>
@@ -272,83 +328,10 @@ export function App() {
         <input type="file" aria-label="Upload file" onChange={event => { const file = event.target.files?.[0]; if (file) void upload(file); }} />
         <ul>{files.map((file, index) => <li key={index}>{file.path ?? file.name}{file.size !== undefined ? \` (\${file.size} bytes)\` : ""}</li>)}</ul>
       </section>
-
-      <SlackPanel connection="company-slack" channel="team-updates" />
     </main>
   );
 }
 `;
-const SLACK_PANEL = `import { useState } from "react";
-import { errorCode, integrations, type ConnectResult } from "./harbour.client";
-
-type Message = { id: string; text: string; authorId: string; createdAt: string };
-type SendState = { kind: "idle" } | { kind: "sending" } | { kind: "sent"; messageId: string } | { kind: "unknown" } | { kind: "rate_limited"; retryAfterSeconds?: number } | { kind: "failed"; code: string };
-const SEND_KEY = "harbour.slack.sendActionId";
-
-/** One channel: connect (consent), load history, draft, explicit Send with a stable idempotency key. */
-export function SlackPanel({ connection, channel }: { connection: string; channel: string }) {
-  const [link, setLink] = useState<ConnectResult | { status: "reconnect_required" } | { status: "unknown" }>({ status: "unknown" });
-  const [history, setHistory] = useState<Message[]>([]);
-  const [draft, setDraft] = useState("");
-  const [send, setSend] = useState<SendState>({ kind: "idle" });
-  const [note, setNote] = useState<string | null>(null);
-
-  const connect = async () => {
-    try { setLink(await integrations().connect(connection)); setNote(null); }
-    catch (error) { setNote(\`Connect failed: \${errorCode(error)}\`); }
-  };
-  const loadHistory = async () => {
-    try {
-      const result = await integrations().execute<{ messages: Message[]; hasMore: boolean }>(connection, { operation: "slack.channel.history", resource: channel, input: { limit: 15 } });
-      setHistory(result.messages); setNote(null);
-    } catch (error) {
-      const code = errorCode(error);
-      if (code === "USER_CONNECTION_REQUIRED") setLink({ status: "unknown" });
-      else if (code === "USER_RECONNECT_REQUIRED") setLink({ status: "reconnect_required" });
-      setNote(\`History unavailable: \${code}\`);
-    }
-  };
-
-  // The key is created when the person presses Send and survives retries of that
-  // same action (component state + sessionStorage); a new draft gets a new key.
-  const sendDraft = async () => {
-    if (!draft.trim() || send.kind === "sending") return;
-    let key = sessionStorage.getItem(SEND_KEY);
-    if (!key) { key = crypto.randomUUID(); sessionStorage.setItem(SEND_KEY, key); }
-    setSend({ kind: "sending" });
-    try {
-      const result = await integrations().execute<{ messageId: string }>(connection, { operation: "slack.message.post", resource: channel, input: { text: draft }, idempotencyKey: key });
-      sessionStorage.removeItem(SEND_KEY);
-      setSend({ kind: "sent", messageId: result.messageId }); setDraft("");
-    } catch (error) {
-      const code = errorCode(error);
-      const retryAfterSeconds = (error as { details?: { retryAfterSeconds?: number } })?.details?.retryAfterSeconds;
-      if (code === "SEND_OUTCOME_UNKNOWN") setSend({ kind: "unknown" });
-      else if (code === "PROVIDER_RATE_LIMITED" || code === "RATE_LIMITED") setSend({ kind: "rate_limited", retryAfterSeconds });
-      else setSend({ kind: "failed", code });
-    }
-  };
-
-  return (
-    <section>
-      <h2>Slack: #{channel}</h2>
-      {link.status === "connected" && <p>Connected as {link.accountLabel}.</p>}
-      {link.status === "consent_required" && <p>Slack needs your consent: <a href={link.authorizationUrl}>connect your Slack account</a>.</p>}
-      {link.status === "reconnect_required" && <p>Your Slack connection expired. <button type="button" onClick={() => void connect()}>Reconnect</button></p>}
-      {link.status === "unknown" && <button type="button" onClick={() => void connect()}>Connect Slack</button>}
-      <p><button type="button" onClick={() => void loadHistory()}>Load history</button></p>
-      <ul>{history.map(message => <li key={message.id}><code>{message.authorId}</code> {message.text}</li>)}</ul>
-      <textarea value={draft} onChange={event => { setDraft(event.target.value); if (send.kind !== "sending") { sessionStorage.removeItem(SEND_KEY); setSend({ kind: "idle" }); } }} placeholder="Draft a message (nothing is sent until you press Send)" rows={3} style={{ width: "100%" }} />
-      <p><button type="button" onClick={() => void sendDraft()} disabled={send.kind === "sending" || !draft.trim()}>Send</button></p>
-      {send.kind === "sent" && <p>Sent (message {send.messageId}).</p>}
-      {send.kind === "unknown" && <p>Harbour could not confirm whether the message was sent. Retry sends the same action, not a duplicate. <button type="button" onClick={() => void sendDraft()}>Retry</button></p>}
-      {send.kind === "rate_limited" && <p>Slack is rate limiting; try again{send.retryAfterSeconds ? \` in \${send.retryAfterSeconds}s\` : " shortly"}.</p>}
-      {send.kind === "failed" && <p>Send failed: {send.code}.</p>}
-      {note && <p>{note}</p>}
-    </section>
-  );
-}
-`;
 const MIGRATION = `-- Notes table for the starter. Ownership comes from the gateway's transaction-local
 -- settings (harbour.user_id / harbour.user_email); the browser never supplies it.
 CREATE TABLE IF NOT EXISTS notes (

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

@@ -1 +1 @@
-export const CLI_VERSION = "0.1.21";
+export const CLI_VERSION = "0.1.22";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Harbour productionisation helper",
   "type": "module",
   "bin": {