@fourier-labs/harbour 0.1.46 → 0.1.47

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

@@ -195,8 +195,8 @@ 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 downloads the native runtime 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. Do this unasked as soon as the first check is green — they should always have the 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\`. Failures in the app's code are yours to fix — fix, then check again until it is clean. Run the checks yourself after every change and before every ship, without being asked and without offering them as a choice.
 - "does it work?", and before you report anything as working → open the dev link in your own browser when you have one, press the control you built or changed, and read what the app shows. A green \`harbour check\` is not that proof: it answers governed AI and company systems from fixtures, so the refusals that matter (a field the company's AI route does not accept, a consent the operation does not need, a channel that is not approved) appear only when the control is really pressed. Test rendering, navigation, fixtures and approved reads automatically. In development a Send sends a real email or Slack message: reuse explicit authorization for that bounded test, or ask once if none exists; IT access approval alone is not permission to send. Never ask again for the same authorized test. Before a real integration test, run \`harbour integrations status --app-root . --json\`; explain pending IT approval or missing personal consent before pressing Send, and test the ready parts independently. If you have no browser, say that the button itself is untested.
-- "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. Never guess a connection, channel, table, view, mailbox or warehouse column — a guessed name is refused before IT's queue ever sees it. Run \`harbour integrations catalog --app-root . --json\` first and use only what it lists. A warehouse resource whose catalog columns are \`["*"]\` is declared and read with \`["*"]\`; do not invent a friendlier schema or ask the person to get IT to confirm one. Declare only connections and operations the app really calls, then submit both development and preview requests yourself in the same turn with \`harbour integrations request <connection> --reason "<what the app does with it>" --app-root . --json\` and the same command with \`--environment preview\`. Never tell the person to ask IT before you have submitted the request. 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\`. A refusal with \`RESOURCE_NOT_APPROVED\` means the named resource is not on the connection yet: IT adds it in the Harbour console under Controls & integrations, and then you run the same request again. Never declare a connection the app does not call — every declared one blocks shipping until IT approves it.
-- "summarise", "draft", "explain", "AI" → one \`harbour.ai.chat\` call (through \`ai()\` in \`src/harbour.client.ts\`) behind a control the person presses; never an OpenAI/Anthropic key, SDK or URL. \`harbour check\` writes its journey. Send \`messages\` and \`maxTokens\` and nothing else: a refusal with \`unsupported_request_capability\` names a field the company's AI route does not accept — remove that field. A refusal with \`AI_NOT_ENABLED\` means IT has to enable an AI provider: say so in one line and keep the app working without 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. Never guess a connection, channel, table, view, mailbox or warehouse column — a guessed name is refused before IT's queue ever sees it. Before writing a warehouse query or mapping response fields, run \`harbour integrations catalog --app-root . --json\`, select a listed table or view, and copy its listed column names exactly. If the required object or column is absent, report that catalog gap instead of substituting a plausible name. A warehouse resource whose catalog columns are \`["*"]\` is declared and read with \`["*"]\`; inspect the returned row keys before mapping them and do not invent a friendlier schema or ask the person to get IT to confirm one. Declare only connections and operations the app really calls, then submit both development and preview requests yourself in the same turn with \`harbour integrations request <connection> --reason "<what the app does with it>" --app-root . --json\` and the same command with \`--environment preview\`. Never tell the person to ask IT before you have submitted the request. 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\`. A refusal with \`RESOURCE_NOT_APPROVED\` means the named resource is not on the connection yet: IT adds it in the Harbour console under Controls & integrations, and then you run the same request again. Never declare a connection the app does not call — every declared one blocks shipping until IT approves it.
+- "summarise", "draft", "explain", "AI" → one \`harbour.ai.chat\` call (on the \`harbour\` client from \`src/harbour.client.ts\`, never through a wrapper function) behind a control the person presses; never an OpenAI/Anthropic key, SDK or URL. \`harbour check\` writes its journey. Send \`messages\` and \`maxTokens\` and nothing else: a refusal with \`unsupported_request_capability\` names a field the company's AI route does not accept — remove that field. A refusal with \`AI_NOT_ENABLED\` means IT has to enable an AI provider: say so in one line and keep the app working without it.
 - "ship it", "put it online", "let my team try it" → run \`harbour check --app-root . --json\` first and fix everything it finds, every time, unasked: the same gates run again in the cloud, where each failed attempt costs minutes instead of the seconds it costs here. Before sharing or deploying the private preview, show the person the exact proposed app name, description and audience that will be passed to Harbour (say "only you" when the audience is empty) and ask for one confirmation or correction covering all three; do not run \`productionise\` until they confirm. Pass that confirmed setup in the same command: \`harbour productionise --app-root . --name "<app name>" --description "<description>" --emails "<comma-separated audience>" --wait --json\`; omit \`--emails\` for "only you". The command records the confirmed setup before uploading or deploying the app. Then each declared connection needs a preview grant (\`harbour integrations request <connection> --environment preview --reason "…" --app-root . --json\`); when the app calls governed AI, \`productionise\` also asks whether the company's AI setup is ready and refuses with \`AI_NOT_READY\` and the one IT step — say that line and nothing more; the app works without AI until then. The command gives them \`result.deployment.protectedUrl\`: a private preview that they, and the people they confirmed, open after company sign-in. If your tool cuts the command off before it finishes, \`${continueCommand("<ref>")}\` continues the same deployment — never start another one to find out what happened. For kit apps, describe \`TRANSFORMING\` as building and checking the app; it does not mean a transformation AI is running. The CLI saves \`operationRef\` in \`.harbour/local/productionise.json\`; repeating \`productionise\` continues that operation. 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.
 - "make it live for everyone", "go to production" → only after they have tried the preview. Before \`harbour promote --operation <ref> --json\`, show the exact app name, description and production audience again and ask for one confirmation or correction covering all three; never promote a profile or audience the person has not just seen and confirmed. Then promote 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/kit-bundle.manifest.js

@@ -1,6 +1,6 @@
 export const PUBLISHED_KIT_BUNDLE = {
     "schema": "harbour.kit-bundle/1.0",
-    "kitVersion": "0.1.42",
+    "kitVersion": "0.1.47",
     "sdk": {
         "package": "@harbour/app-sdk",
         "version": "1.1.2",
@@ -8,21 +8,21 @@ export const PUBLISHED_KIT_BUNDLE = {
         "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:aa6dd568b8580ef239c32b7470e79681a54363ce7808f687e389697ef8f56d94"
     },
     "images": {
-        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:771d71975a503214fa63f94534c77483f06797f8089d7fdc027ca30e26983039",
-        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:c3c84639da9d98c08009bacaf4017ad597bc5528acda4cee9ad0917cee35afdb"
+        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:cce105d4f01d1389c57c50786e2d64216ef26ac6d36fbbc0f0e12b05fea22d8a",
+        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:7a14aeb938c815f6f42a1a850e8b470f8a0e3b532c1391a73377ce72931023b3"
     },
     "nativeRuntime": {
         "darwinArm64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:2e83e6dd8747859ffabb6a832a759e95fc68aad9b374c0e16007da84aca49580",
-            "sha256": "2e83e6dd8747859ffabb6a832a759e95fc68aad9b374c0e16007da84aca49580"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:2a28ad794fa976d5e50f410dc88ab474544fb0686727fd41339d145b825d78d4",
+            "sha256": "2a28ad794fa976d5e50f410dc88ab474544fb0686727fd41339d145b825d78d4"
         },
         "linuxX64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:02ce306b179db95c16e1d3cedf6ad01d8dfba5810a2df14a03dcd2fd024478ef",
-            "sha256": "02ce306b179db95c16e1d3cedf6ad01d8dfba5810a2df14a03dcd2fd024478ef"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:cb47104e302ab5cc2363f08d3d778c10f0c41845f22f1fba102c152859f82e44",
+            "sha256": "cb47104e302ab5cc2363f08d3d778c10f0c41845f22f1fba102c152859f82e44"
         },
         "windowsX64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:2cee6b4521cd7a6d6bcf7b4806e18ac26ada150f13bf45dfda06346a96a47d75",
-            "sha256": "2cee6b4521cd7a6d6bcf7b4806e18ac26ada150f13bf45dfda06346a96a47d75"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:35c3912f8af054594d8c0fd4cf157be4ccfdbacf7ab0da4783c9179d80ebb927",
+            "sha256": "35c3912f8af054594d8c0fd4cf157be4ccfdbacf7ab0da4783c9179d80ebb927"
         }
     },
     "brief": {

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

@@ -210,6 +210,14 @@ export function outcomeFor(status, operationRef) {
     }
     if (status.deployment)
         return { ...summary, outcome: "running" };
+    // No deployment yet has two very different causes. A save that stalled or
+    // failed (RETRYABLE_FAILURE, FAILED) is resumed by running `productionise`
+    // again — observed 2026-09-14 (fourier "Dad Jokes"): a builder read the
+    // administrator sentence for a save that was simply resumable. Only a
+    // SUCCEEDED save with no deployment behind it is the company-setup case.
+    const save = status.sourceSave?.status;
+    if (save && save !== "SUCCEEDED")
+        return { ...summary, outcome: "no_deployment", nextStep: summary.nextStep ?? `Harbour has not finished saving the app (${save}). Run \`harbour productionise\` again for this app: it resumes the same save and deploys; nothing is deployed twice.` };
     return { ...summary, outcome: "no_deployment", nextStep: summary.nextStep ?? "Harbour saved the app but has not started a deployment for this company yet. Ask your Harbour administrator to connect deployment." };
 }
 /**

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

@@ -432,11 +432,18 @@ function outcomeLine(summary) {
     }
 }
 const readApproval = readLine;
-/** The local gate's inventory says whether the app calls governed AI (`.harbour/local/check-report.json`, `gate.inventory.capabilities`). */
+/**
+ * Whether the app really calls governed AI: the gate's inventory of
+ * `harbour.ai.*` call sites (`.harbour/local/check-report.json`,
+ * `gate.inventory.aiCallsites`). Not the capability word — a starter that
+ * merely carried an `ai()` accessor was derived as `ai` and would have been
+ * refused `AI_NOT_READY` at a company without AI for an app that never asks
+ * for it (2026-09-14). The call sites are what the deployment PLAN sees.
+ */
 export async function appCallsAi(root) {
     const report = await readReport(root);
-    const capabilities = report?.gate?.inventory?.capabilities;
-    return Array.isArray(capabilities) && capabilities.includes("ai");
+    const callsites = report?.gate?.inventory?.aiCallsites;
+    return Array.isArray(callsites) && callsites.length > 0;
 }
 async function finishDeployment(client, operationRef, output, options, verification = {}) {
     let summary;

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

@@ -50,11 +50,10 @@ const VERB_ORDER = ["insert", "upsert", "select", "update", "delete"];
  * Regenerates `.harbour/checks/` in place from the app's code and its own
  * database, and reports every decision. `declared`, when given, is the
  * capability set the kit gate derived from the source — the set its coverage
- * gate will demand evidence for — and it is the authority: the kit lane traces
- * a namespace wrapper (`export function ai() { return harbour.ai }`) to the
- * capability it wraps whether or not anything calls it, which a call-site
- * reading of the source never sees. Without it (tests, no gate) the source
- * reading decides.
+ * gate will demand evidence for — and it is the authority: the kit lane and
+ * this reading agree on the one call shape the starter teaches
+ * (`harbour.<namespace>.<method>(`), for which the lane's derivation is exact.
+ * Without it (tests, no gate) the source reading decides.
  */
 export async function syncRetainedChecks(root, schema, declared) {
     const plan = await planRetainedChecks(root, schema, declared);

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

@@ -108,7 +108,7 @@ export async function sourceTableVerbs(root) {
  */
 export async function capabilityUsage(root) {
     const files = await sourceFiles(root);
-    const texts = await Promise.all(files.map(path => readFile(path, "utf8").catch(() => "")));
+    const texts = (await Promise.all(files.map(path => readFile(path, "utf8").catch(() => "")))).map(maskNonCode);
     const clients = new Set();
     for (const text of texts)
         for (const match of text.matchAll(CLIENT_BINDING))
@@ -155,8 +155,8 @@ const appPath = (root, path) => relative(root, path).split(sep).join("/");
  * receiver makes this a superset of that set — every call site the pipeline can
  * trace, plus ones it cannot — so a capability this cannot see is one the kit
  * lane cannot declare either, and the reverse gate refuses only trees the
- * pipeline already refuses. Where it errs it errs by staying quiet: a
- * commented-out call still counts here, and the pipeline masks comments.
+ * pipeline already refuses. Comments and string bodies are masked first,
+ * exactly as the pipeline masks them, so a quoted example never counts.
  */
 export async function capabilityCallSurface(root) {
     const surface = new Set();
@@ -165,7 +165,75 @@ export async function capabilityCallSurface(root) {
             surface.add(capability);
     return surface;
 }
+/**
+ * The pipeline's reading masks comments and string bodies before it looks for
+ * call shapes (transformbuild maskJavaScriptNonCode); this reading does the
+ * same, so a call shape quoted in a comment — the starter's own examples —
+ * or inside a string never counts as a use. Offsets are preserved (masked
+ * bytes become spaces), so nothing that reports a position drifts.
+ */
+export function maskNonCode(source) {
+    const out = source.split("");
+    let state = "code";
+    for (let i = 0; i < source.length; i += 1) {
+        const c = source[i], n = source[i + 1];
+        if (state === "code") {
+            if (c === "/" && n === "/") {
+                state = "line";
+                out[i] = " ";
+                continue;
+            }
+            if (c === "/" && n === "*") {
+                state = "block";
+                out[i] = " ";
+                continue;
+            }
+            if (c === "'")
+                state = "single";
+            else if (c === "\"")
+                state = "double";
+            else if (c === "`")
+                state = "template";
+            continue;
+        }
+        if (state === "line") {
+            if (c === "\n")
+                state = "code";
+            else
+                out[i] = " ";
+            continue;
+        }
+        if (state === "block") {
+            if (c === "*" && n === "/") {
+                state = "code";
+                out[i] = " ";
+                out[i + 1] = " ";
+                i += 1;
+            }
+            else if (c !== "\n")
+                out[i] = " ";
+            continue;
+        }
+        // A string body: keep the quotes (the shape around them stays readable), mask what is inside.
+        const quote = state === "single" ? "'" : state === "double" ? "\"" : "`";
+        if (c === "\\") {
+            out[i] = " ";
+            if (n !== undefined && n !== "\n") {
+                out[i + 1] = " ";
+                i += 1;
+            }
+            continue;
+        }
+        if (c === quote) {
+            state = "code";
+            continue;
+        }
+        if (c !== "\n")
+            out[i] = " ";
+    }
+    return out.join("");
+}
 /** The same reading of one piece of text, so a retained check is judged by exactly the rule the app's own source is read with (retained-checks.ts). */
 export function capabilitiesCalled(text) {
-    return new Set([...text.matchAll(CAPABILITY_CALL)].map(match => match[1]));
+    return new Set([...maskNonCode(text).matchAll(CAPABILITY_CALL)].map(match => match[1]));
 }

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

@@ -98,7 +98,7 @@ export function managedBlock() {
         "- A Slack message is posted either as the app (the company's Slack bot, Isomorph AI, under the IT-approved name: declare `\"presentation\": { \"displayName\": \"<app name>\" }` on the Slack connection, optional `iconEmoji`; every app-mode post ends with \"Posted by <app> on Isomorph\") or as the person (`\"identity\": \"user\"` on `slack.message.post`, their own consent; an older consent answers `USER_RECONNECT_REQUIRED` — offer Connect again) — never pretend one is the other. The declaration is the mode you request access for; when the app is approved for both, every post says which with `mode: \"app\"` or `mode: \"user\"` on the call (`MODE_REQUIRED` otherwise), and a mode IT has not approved is refused with `MODE_NOT_GRANTED`, never swapped. A post needs the bot in the channel: `/invite @Isomorph AI` there first.",
         "- Consent is only for user-identity operations (`slack.channel.history`, `gmail.*`, and `slack.message.post` declared `\"identity\": \"user\"`): call `harbour.integrations.connect(connection)` and, when it returns `consent_required`, open `authorizationUrl`. App-identity operations (`slack.message.post` declared `\"identity\": \"app\"`, `warehouse.view.read`) never call connect — it is refused as unapproved user access. Missing consent never falls back to another account.",
         "- A retained check that calls `harbour.integrations.execute` is answered, under `harbour check` and in the deployment pipeline alike, by the gate's fixture: the contract's result shape for a connection, operation and resource the app declared (one canned Slack message, one canned Gmail thread, a warehouse view with no rows), a refusal with the platform's own code for anything undeclared, and nothing is ever sent or read. The passed check says so in the report; real access is exercised only by `harbour check --integrations` (reads) and the preview's own smoke test.",
-        "- AI goes through `harbour.ai` only — `ai().chat({ messages, maxTokens })` from `src/harbour.client.ts` — behind an explicit control the person presses (never on load, in an effect or a timer). Never add an OpenAI/Anthropic/Gemini key, SDK or URL: the platform's governed AI gateway holds the key and IT sees every call. The starter calls no AI; add the one call when the person asks for it (README.md has the \"Summarise my notes\" example) and `harbour check` writes `.harbour/checks/ai-journey.mjs` for it. A refusal with code `AI_NOT_ENABLED` means IT has not enabled an AI provider yet; the app must still work without AI.",
+        "- AI goes through `harbour.ai` only — `harbour.ai.chat({ messages, maxTokens })` on the `harbour` client from `src/harbour.client.ts`, never through a wrapper function (the gate reads only the direct call) — behind an explicit control the person presses (never on load, in an effect or a timer). Never add an OpenAI/Anthropic/Gemini key, SDK or URL: the platform's governed AI gateway holds the key and IT sees every call. The starter calls no AI; add the one call when the person asks for it (README.md has the \"Summarise my notes\" example) and `harbour check` writes `.harbour/checks/ai-journey.mjs` for it. A refusal with code `AI_NOT_ENABLED` means IT has not enabled an AI provider yet; the app must still work without AI.",
         "- 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.",
@@ -196,14 +196,14 @@ The checks and the code are one pair, and \`harbour check\` and the deployment p
 
 ## Adding AI ("Summarise my notes")
 
-The starter calls no AI. When the person asks for it, add one call through \`ai()\` from \`src/harbour.client.ts\`, behind a control they press — never on load, in an effect or a timer — and never an OpenAI/Anthropic/Gemini key, SDK or URL: the platform's governed AI gateway holds the key, IT enables the provider and sees every call.
+The starter calls no AI. When the person asks for it, add one call — \`harbour.ai.chat(...)\` on the \`harbour\` client from \`src/harbour.client.ts\` — behind a control they press — never on load, in an effect or a timer — and never an OpenAI/Anthropic/Gemini key, SDK or URL: the platform's governed AI gateway holds the key, IT enables the provider and sees every call.
 
 \`\`\`tsx
 import { ai, errorCode } from "./harbour.client";
 
 const summarise = async () => {
   try {
-    const reply = await ai().chat({ messages: [{ role: "user", content: \`Summarise these notes in three lines:\\n\${notes.map(n => n.title).join("\\n")}\` }], maxTokens: 200 });
+    const reply = await harbour.ai.chat({ messages: [{ role: "user", content: \`Summarise these notes in three lines:\\n\${notes.map(n => n.title).join("\\n")}\` }], maxTokens: 200 });
     setSummary(reply.content);
   } catch (error) {
     setError(errorCode(error) === "AI_NOT_ENABLED" ? "AI is not enabled for this company yet; ask IT to connect a provider." : "The summary could not be produced.");
@@ -242,15 +242,15 @@ Add one in two steps, when the app really calls it:
 
 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\`:
+Then call it from the app on the \`harbour\` client from \`src/harbour.client.ts\` — always this exact shape, never a wrapper function, because the kit gate derives what the app uses from it:
 
 \`\`\`ts
-const report = await integrations().execute("sales-warehouse", {
+const report = await harbour.integrations.execute("sales-warehouse", {
   operation: "warehouse.view.read", resource: "weekly_sales", input: { columns: ["week", "total"], limit: 100 }
 });
 \`\`\`
 
-In browser code, a send (\`slack.message.post\`, \`gmail.message.send\`) runs only from an explicit Send control, pressed by the person or by the AI tool for an explicitly authorized test, with a fresh UUID \`idempotencyKey\` per press — never from an effect, a browser timer or a check. Scheduled work lives in \`jobs/<name>.ts\`; its handler acts as the app, so only app-mode sends may run there, with an approved destination and a deterministic idempotency key for the business period and destination. Test the schedule immediately with \`harbour jobs run <name> --app-root . --scheduled-at <UTC> --json\`; local job runs and checks use fixtures and send nothing, and the deployed Kubernetes schedule owns the real clock. Consent is only for user-identity operations (\`slack.channel.history\`, \`gmail.*\`, and \`slack.message.post\` declared \`"identity": "user"\`): \`integrations().connect(connection)\`, and open its \`authorizationUrl\` when it answers \`consent_required\`; app-identity operations (\`slack.message.post\` declared \`"identity": "app"\`, \`warehouse.view.read\`) never call connect. Anything the app calls needs its own retained check under \`.harbour/checks/\`, and anything it stops calling loses its check in the same edit. Keep request construction in an app function that both the button and its retained check call, so the check exercises the actual payload. Do not bypass the SDK types with a generic string/unknown wrapper. A check that calls \`integrations().execute\` is answered by the gate's fixture — the contract's result shape for the declared connection, operation and resource, nothing sent or read, and the report says so; \`harbour check --integrations\` is what exercises real access.
+In browser code, a send (\`slack.message.post\`, \`gmail.message.send\`) runs only from an explicit Send control, pressed by the person or by the AI tool for an explicitly authorized test, with a fresh UUID \`idempotencyKey\` per press — never from an effect, a browser timer or a check. Scheduled work lives in \`jobs/<name>.ts\`; its handler acts as the app, so only app-mode sends may run there, with an approved destination and a deterministic idempotency key for the business period and destination. Test the schedule immediately with \`harbour jobs run <name> --app-root . --scheduled-at <UTC> --json\`; local job runs and checks use fixtures and send nothing, and the deployed Kubernetes schedule owns the real clock. Consent is only for user-identity operations (\`slack.channel.history\`, \`gmail.*\`, and \`slack.message.post\` declared \`"identity": "user"\`): \`harbour.integrations.connect(connection)\`, and open its \`authorizationUrl\` when it answers \`consent_required\`; app-identity operations (\`slack.message.post\` declared \`"identity": "app"\`, \`warehouse.view.read\`) never call connect. Anything the app calls needs its own retained check under \`.harbour/checks/\`, and anything it stops calling loses its check in the same edit. Keep request construction in an app function that both the button and its retained check call, so the check exercises the actual payload. Do not bypass the SDK types with a generic string/unknown wrapper. A check that calls \`harbour.integrations.execute\` is answered by the gate's fixture — the contract's result shape for the declared connection, operation and resource, nothing sent or read, and the report says so; \`harbour check --integrations\` is what exercises real access.
 `;
 const VITE_CONFIG = `import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
@@ -275,37 +275,24 @@ const HARBOUR_CLIENT = `import { createClient } from "@harbour/app-sdk";
 // the same calls work locally (harbour dev) and in preview/production.
 export const harbour = createClient();
 
-// Keep the SDK's operation-specific inputs and inferred results intact.
-export type Integrations = typeof harbour.integrations;
-export function integrations(): Integrations { return harbour.integrations; }
-
+// One call shape, everywhere: the SDK's own namespaces on this client —
+// harbour.integrations.execute(...), harbour.ai.chat(...), harbour.data.from(...),
+// harbour.files.* — and no wrapper functions around them. The kit gate derives
+// what the app uses from exactly these calls; a wrapper would hide them.
+//
 // Gmail sends plain text as the signed-in person, after IT approval and personal consent.
 // Inside an authorized Send handler (use the catalog's actual connection and mailbox):
-// await integrations().execute("company-gmail", {
+// await harbour.integrations.execute("company-gmail", {
 //   operation: "gmail.message.send", resource: "inbox",
 //   input: { to: ["recipient@example.com"], subject: "Update", text: "Your message" },
 //   idempotencyKey: crypto.randomUUID()
 // });
-
-export type AiMessage = { role: "system" | "user" | "assistant"; content: string };
-export type AiChatResult = { content: string; model: string; finishReason: string; usage: { inputTokens: number; outputTokens: number }; traceId?: string };
-export type Ai = {
-  chat(request: { messages: AiMessage[]; model?: string; maxTokens?: number; temperature?: number }): Promise<AiChatResult>;
-  embed(request: { input: string | string[]; model?: string }): Promise<{ embeddings: number[][]; model: string }>;
-};
-
-/**
- * Governed AI through the platform's LLM gateway (kit bundle SDK): the app never holds a
- * provider key and IT governs every call. The starter calls no AI; this is the entry point
- * for the one call you add when the person asks for it — behind an explicit control they
- * press, never on load. README.md has the "Summarise my notes" example. A HarbourError whose
- * errorCode() is AI_NOT_ENABLED means IT has not enabled a provider yet: keep the app working.
- */
-export function ai(): Ai {
-  const surface = (harbour as { ai?: Ai }).ai;
-  if (!surface) throw new Error("This @harbour/app-sdk build has no ai surface; run harbour init --upgrade.");
-  return surface;
-}
+//
+// Governed AI through the platform's LLM gateway: the app never holds a provider key and
+// IT sees every call. The starter calls no AI; when the person asks for it, add the one
+// call — harbour.ai.chat({ messages, maxTokens }) — behind an explicit control they press,
+// never on load. README.md has the "Summarise my notes" example. A HarbourError whose
+// errorCode() is AI_NOT_ENABLED means IT has not enabled a provider yet: keep the app working.
 
 export function errorCode(error: unknown): string {
   const details = (error as { details?: { code?: string } } | undefined)?.details;
@@ -362,19 +349,19 @@ export function App() {
   //    IT-approved presentation name; "identity": "user" posts as the signed-in person after their consent.
   //    A post may name the approved mode it runs under — { ..., mode: "app" } — and must once IT approved both.)
   // 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("sales-warehouse", {
+  //    and again with --environment preview before harbour productionise), then uncomment
+  //    (the harbour client is already imported from "./harbour.client"):
+  // const report = await harbour.integrations.execute("sales-warehouse", {
   //   operation: "warehouse.view.read", resource: "weekly_sales", input: { columns: ["week", "total"], limit: 100 }
   // });
   // A Slack send runs only from an explicit Send control, pressed by the person or by the AI tool for an explicitly authorized test, with a
   // fresh UUID idempotencyKey per press — never from an effect, a timer or a check.
   //
   // Governed AI is not part of the starter either. When the person asks for it, add ONE
-  // call through ai() from "./harbour.client" behind a control they press (README.md
+  // call harbour.ai.chat on the client from "./harbour.client" behind a control they press (README.md
   // "Adding AI"), never an OpenAI/Anthropic key or SDK; harbour check then writes
   // .harbour/checks/ai-journey.mjs for it, and deletes it again if the call goes:
-  // const summary = await ai().chat({ messages: [{ role: "user", content: \`Summarise these notes in three lines:\\n\${notes.map(n => n.title).join("\\n")}\` }], maxTokens: 200 });
+  // const summary = await harbour.ai.chat({ messages: [{ role: "user", content: \`Summarise these notes in three lines:\\n\${notes.map(n => n.title).join("\\n")}\` }], maxTokens: 200 });
 
   return (
     <main style={{ fontFamily: "system-ui", maxWidth: 720, margin: "2rem auto", padding: "0 1rem" }}>

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

@@ -1 +1 @@
-export const CLI_VERSION = "0.1.46";
+export const CLI_VERSION = "0.1.47";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour",
-  "version": "0.1.46",
+  "version": "0.1.47",
   "description": "Harbour productionisation helper",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
   "harbour": {
     "kitBundle": {
       "repository": "public.ecr.aws/y6t4p3i8/harbour-kit-bundle",
-      "version": "0.1.42"
+      "version": "0.1.47"
     }
   }
 }