@fourier-labs/harbour 0.1.47 → 0.1.48

package/README.md

@@ -33,7 +33,7 @@ harbour dev --app-root <path> [--reset]                    run the app locally o
 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 catalog --app-root <path> [--json]   the company's connections as .harbour/integrations.json names them, with approved channels/views per environment
-harbour integrations request <connection> --reason <text> --app-root <path> [--environment <env>]
+harbour integrations request <connection> --app-root <path> [--reason <text>]   one request per connection; IT approves it once for every environment (`harbour dev` and `harbour productionise` file it for you)
 harbour integrations status --app-root <path> [--json]
 harbour connect <work-email-or-start-url>                        once per company; then harbour login | logout
 harbour productionise --app-root <path> [--wait] [--json]  save + preview deployment, prints the protected link

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

@@ -195,9 +195,9 @@ 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. 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.
+- "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 the request yourself in the same turn with \`harbour integrations request <connection> --reason "<what the app does with it>" --app-root . --json\` — one request per connection; IT approves it once for every environment (development, preview and production together), and \`harbour dev\` and \`harbour productionise\` file it for you as well, so there is never a second request to make before shipping. 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\` (development may already read ready while preview and production wait: that is the company's development preapproval, and the one approval covers the rest). 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.
+- "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. It files the access request for each declared connection itself and refuses with \`INTEGRATIONS_NOT_READY\` naming what IT still has to approve — say that line and nothing more, and ship again once IT has approved it (one approval covers preview and production); 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.
 - "every day at 2pm", "run this on a schedule", "send this automatically" → create one \`jobs/<name>.ts\` file with a literal UTC cron and one default async handler. Start \`harbour dev\`, then run it immediately with \`harbour jobs run <name> --app-root . --scheduled-at <matching-UTC-time> --json\`; this checks the job against local data and safe fixtures. If the person explicitly asks to test the company action now, use \`--real\` only after the exact action has development approval. Tell them: "Your scheduled task is ready. I can test the app on your computer now. Company messages will start after the app is online and access is approved." Never use \`setInterval\`, an effect or a browser timer as a scheduler; Harbour runs the same declaration automatically after deployment.

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

@@ -50,7 +50,7 @@ export async function runChecks(root, options) {
         const lock = await readKitLock(root).catch(() => undefined);
         const { declaration, errors } = await readDeclaration(root);
         if (!lock?.appId)
-            skipped("the app is not linked yet; `harbour integrations request` links it");
+            skipped("the app is not linked yet; `harbour dev` (signed in) or `harbour integrations request` links it");
         else if (errors.length)
             skipped(`.harbour/integrations.json is invalid: ${errors[0]}`);
         else {

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

@@ -7,13 +7,13 @@ import { CLI_VERSION } from "./version.js";
 import { connectedAccount, login, logout, refreshStoredToken } from "./auth.js";
 import { connect, loadConfig, resolveConfig } from "./config.js";
 import { EMBEDDED_KIT_BUNDLE } from "./kit-bundle.js";
-import { appRoot, readKitLock } from "./kit.js";
+import { appRoot, readKitLock, requestResourceName } from "./kit.js";
 import { initKit } from "./starter.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";
-import { assertAiReady, GovernanceClient, integrationsCatalog, integrationsStatus, renderIntegrationsCatalog, requestIntegrations } from "./integrations.js";
+import { assertAiReady, GovernanceClient, groupGrants, IDENTITY_WORDS, integrationsCatalog, integrationsStatus, renderGrantGroup, renderIntegrationsCatalog, requestIntegrations } from "./integrations.js";
 import { runJob } from "./jobs.js";
 const args = process.argv.slice(2);
 const command = args[0];
@@ -34,9 +34,7 @@ const reset = args.includes("--reset");
 const upgrade = args.includes("--upgrade");
 const testIntegrations = args.includes("--integrations");
 const reason = optionValue("--reason");
-const environment = optionValue("--environment");
 const operations = optionValue("--operations");
-const expiresAt = optionValue("--expires-at");
 const scheduledAt = optionValue("--scheduled-at");
 const realJob = args.includes("--real");
 /** Seconds `productionise`, `status --wait`, `retry` and `promote` follow the operation before reporting it as still running (default: 30 minutes). */
@@ -80,13 +78,13 @@ const usage = [
     "  harbour stop --app-root <path>                             stop this app's local services, keeping its database and files",
     "  harbour check --app-root <path> [--integrations] [--json]  types, build, then the pipeline's kit gate in the local session: declaration, migrations + database gate, write probe with cross-user denial, journeys, operation coverage (+ authorised real reads)",
     "  harbour jobs run <name> --app-root <path> [--scheduled-at <UTC>] [--real] [--json]  run one scheduled job now (local fixtures; --real uses approved company access)",
-    "  harbour integrations request <connection> --reason <text> --app-root <path> [--environment <env>] [--operations a,b] [--expires-at <UTC>] [--json]",
+    "  harbour integrations request <connection> --app-root <path> [--reason <text>] [--operations a,b] [--json]   one request per connection, for every environment at once: IT approves it once (harbour dev and productionise file it for you)",
     "  harbour integrations status --app-root <path> [--json]",
     "  harbour integrations catalog --app-root <path> [--json]   the company's connections as .harbour/integrations.json names them: identifiers, allowed operations, approved channels/tables/views/mailboxes per environment (no app needed)",
     "Run `harbour connect <work-email-or-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.",
     `--max-wait bounds how long productionise, status --wait, retry and promote follow the deployment (default 30 minutes). When it passes the command exits 0 with status RUNNING, the last known deployment state, and the \`${continueCommand("<reference>")}\` that continues the same deployment: a bounded wait is not a failure and never means start another one.`,
-    "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, asks governance whether the company's AI setup is ready when the app calls governed AI (exit 2, AI_NOT_READY, with the IT step), then runs the pipeline's kit gate in the local session and refuses (KIT_GATE_FAILED) what CodeBuild would refuse. promote asks the same AI question for production when --app-root names the app.",
+    "For kit apps, productionise first files the access request for every connection in .harbour/integrations.json (one per connection; IT approves it once for every environment) and exits 2 (INTEGRATIONS_NOT_READY) naming what IT still has to approve, asks governance whether the company's AI setup is ready when the app calls governed AI (exit 2, AI_NOT_READY, with the IT step), then runs the pipeline's kit gate in the local session and refuses (KIT_GATE_FAILED) what CodeBuild would refuse. promote asks the same AI question for production when --app-root names the app.",
     "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");
@@ -123,7 +121,7 @@ else if (!["connect", "login", "logout", "productionise", "integrations", ...LOC
     || (command === "productionise" && !root)
     || (LOCAL_COMMANDS.includes(command) && !root)
     || (command === "jobs" && (subcommand !== "run" || !args[2] || args[2].startsWith("--")))
-    || (command === "integrations" && (!root || !subcommand || !["request", "status", "catalog"].includes(subcommand) || (subcommand === "request" && (!args[2] || args[2].startsWith("--") || !reason))))
+    || (command === "integrations" && (!root || !subcommand || !["request", "status", "catalog"].includes(subcommand) || (subcommand === "request" && (!args[2] || args[2].startsWith("--")))))
     || (OPERATION_COMMANDS.includes(command) && !operationRef)
     || (command === "secrets" && (!subcommand || !["list", "set", "dismiss"].includes(subcommand) || (subcommand !== "list" && !secretName)))) {
     if (optionError)
@@ -202,7 +200,7 @@ else {
                 emit(summaryEnvelope(result));
             }
             else {
-                const started = await startDev(target, { bundle, output: progress, reset, company: config ? { apiUrl: config.apiUrl, tenantId: config.tenantId, accessToken: companyToken, account: async () => { const token = await companyToken(); return token ? connectedAccount(config.mcpUrl, config.tenantId, token) : undefined; } } : undefined });
+                const started = await startDev(target, { bundle, output: progress, reset, company: config ? { apiUrl: config.apiUrl, tenantId: config.tenantId, accessToken: companyToken, account: token => connectedAccount(config.mcpUrl, config.tenantId, token) } : undefined });
                 let stopping = false;
                 const shutdown = () => { if (stopping)
                     return; stopping = true; progress("Stopping local Harbour services (data kept)."); void started.stop().finally(() => process.exit(0)); };
@@ -242,13 +240,13 @@ else {
                         ? await integrationsStatus(target, governance)
                         : subcommand === "catalog"
                             ? await integrationsCatalog(governance)
-                            : await requestIntegrations(target, governance, tenant, EMBEDDED_KIT_BUNDLE, { connection: args[2], reason: reason, environment, operations: operations?.split(",").map(value => value.trim()).filter(Boolean), expiresAt });
+                            : await requestIntegrations(target, governance, tenant, EMBEDDED_KIT_BUNDLE, { connection: args[2], ...(reason ? { reason } : {}), operations: operations?.split(",").map(value => value.trim()).filter(Boolean) });
                     envelope = summaryEnvelope(result);
                     if (!json)
                         progress(subcommand === "status" ? renderIntegrationsStatus(result) : subcommand === "catalog" ? renderIntegrationsCatalog(result) : renderRequest(result));
                 }
                 else if (command === "productionise") {
-                    // Kit apps: preview grants are checked (and the app linked) before any operation starts, so productionise never mints a second app for the same root.
+                    // Kit apps: the access requests are filed and the preview lane checked (and the app linked) before any operation starts, so productionise never mints a second app for the same root.
                     const confirmedAppSetup = profileName && profileDescription
                         ? { displayName: profileName, description: profileDescription, audienceEmails: audienceEmails ? audienceEmails.split(",").map(value => value.trim()).filter(Boolean) : [] }
                         : undefined;
@@ -297,23 +295,19 @@ else {
         process.exit(envelope.error?.code === "INTEGRATIONS_NOT_READY" || envelope.error?.code === "AI_NOT_READY" ? 2 : 1);
     }
 }
+/** One line per (connection, identity): the three lanes are one approval, so they are read together. */
 function renderIntegrationsStatus(status) {
     if (!status.linked)
-        return "This app is not linked yet; `harbour integrations request` links it.";
-    const lines = [`App ${status.appId}`];
-    for (const grant of status.grants) {
-        lines.push(`  ${grant.connection} [${grant.environment}, ${grant.identityMode}] ${grant.status} — ${grant.readiness}${grant.expiresAt ? ` until ${grant.expiresAt}` : ""}: ${grant.operations.join(", ")}`);
-        if (grant.failure)
-            lines.push(`    ${grant.failure.message} ${grant.failure.remediation}`);
-    }
+        return "This app is not linked yet; `harbour dev` (signed in) or `harbour integrations request` links it.";
+    const lines = [`App ${status.appId}`, ...groupGrants(status.grants).flatMap(group => renderGrantGroup(group).map(line => `  ${line}`))];
     for (const request of status.requests)
-        lines.push(`  request ${request.requestId}: ${request.state} (${request.reason})`);
+        lines.push(`  request ${request.requestId}: ${request.state}${request.reason ? ` (${request.reason})` : ""}`);
     if (!status.grants.length && !status.requests.length)
         lines.push("  no grants or requests yet");
     return lines.join("\n");
 }
 function renderRequest(result) {
-    return [`App ${result.appId}: ${result.connection} (${result.environment})`, ...result.requests.map(item => `  ${item.identityMode} identity — ${item.operations.join(", ")} on ${item.resources.join(", ")}${item.presentation ? ` (posts as "${item.presentation.displayName}")` : ""}: ${item.state === "READY" ? "READY" : item.state === "PENDING" ? "PENDING (not ready; IT approval or provider setup is outstanding)" : item.state}${item.readiness && item.readiness !== "ready" && item.readiness !== "pending" ? ` (${item.readiness})` : ""}`)].join("\n");
+    return [`App ${result.appId}: ${result.connection}`, ...result.requests.map(item => `  ${IDENTITY_WORDS[item.identityMode]} — ${item.operations.join(", ")} on ${item.resources.map(requestResourceName).join(", ")}${item.presentation ? ` (posts as "${item.presentation.displayName}")` : ""}: ${item.state} — ${item.summary}`)].join("\n");
 }
 function optionValue(flag) {
     const index = args.indexOf(flag);

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

@@ -1,9 +1,33 @@
 import { spawn } from "node:child_process";
 import { createForwarder } from "./forwarder.js";
 import { readKitLock } from "./kit.js";
-import { GovernanceClient, ensureLinkedApp } from "./integrations.js";
+import { GovernanceClient, ensureLinkedApp, fileDeclaredRequests, IDENTITY_WORDS, renderGrantGroup } from "./integrations.js";
 import { acquireDevLock, allocatePorts, ensureSdk, LocalRuntime, nodePackageCommand, releaseDevLock, runCommand } from "./local-runtime.js";
-import { CliError } from "./output.js";
+import { CliError, safeError } from "./output.js";
+/**
+ * Signed in at startup: link the app and file the access request for every
+ * declared connection — one per connection, approved by IT once for every
+ * environment; the same filing `productionise` does — so IT's queue holds the
+ * ask from the first run and no command stands between the builder and the
+ * approval. Returns the banner lines saying where each connection stands.
+ * Never throws: `harbour dev` runs without company access.
+ */
+export async function companyAccessAtStartup(root, client, tenantId, bundle) {
+    try {
+        const filed = await fileDeclaredRequests(root, client, tenantId, bundle);
+        // Nothing declared: still link, so governed AI has the app's identity from its first call.
+        if (!filed)
+            return { appId: await ensureLinkedApp(root, client, tenantId, bundle), lines: [] };
+        const lines = filed.groups.flatMap(group => renderGrantGroup(group));
+        for (const item of filed.requests)
+            if (item.error)
+                lines.push(`${item.connection} [${IDENTITY_WORDS[item.identityMode]}] not requested: ${item.error.message}`);
+        return { appId: filed.appId, lines };
+    }
+    catch (error) {
+        return { lines: [`Company access could not be checked (${safeError(error).message}); the app runs without it until the next start.`] };
+    }
+}
 /**
  * Starts the kit-managed Postgres and App Gateway, applies migrations, then
  * starts Vite and the loopback origin. Stopping retains the app's local data.
@@ -71,16 +95,27 @@ export async function startDev(root, options) {
         const refreshLock = setInterval(() => { void readKitLock(root).then(lock => { lockAppId = lock?.appId || undefined; }).catch(() => undefined); }, 5_000);
         refreshLock.unref();
         await new Promise((resolve, reject) => { forwarder.on("error", reject); forwarder.listen(ports.origin, "127.0.0.1", resolve); });
-        const account = company ? await company.account().catch(() => undefined) : undefined;
+        const token = company ? await company.accessToken().catch(() => undefined) : undefined;
+        const governance = company && token ? new GovernanceClient(company.apiUrl, token, company.tenantId) : undefined;
+        const account = company && token ? await company.account(token).catch(() => undefined) : undefined;
+        const linkedAtStart = lockAppId;
         options.output([
             "",
             `Harbour dev is running: ${origin}`,
             `  App identity (local session): ${session.HARBOUR_LOCAL_USER_EMAIL ?? "local-user@example.test"}; second user for cross-user checks: ${session.HARBOUR_LOCAL_SECOND_USER_EMAIL ?? "teammate@example.test"}`,
             `  Company account for integrations: ${account ?? (company ? "not signed in — run `harbour login`" : "not connected — run `harbour connect`")}`,
-            lockAppId ? `  Linked app: ${lockAppId}` : "  App not linked yet (harbour integrations request links it).",
+            ...(linkedAtStart ? [`  Linked app: ${linkedAtStart}`] : governance ? [] : ["  App not linked yet: the next `harbour dev` after `harbour login` links it and files its access requests (so does `harbour integrations request`)."]),
             "  Ctrl-C or `harbour stop` stops the services and keeps local data; `harbour dev --reset` deletes it.",
             ""
         ].join("\n"));
+        // Signed in: link now and file the app-wide requests — after the link is out, so governance's round-trips never hold it — and say where each connection stands.
+        if (governance && company) {
+            const access = await companyAccessAtStartup(root, governance, company.tenantId, options.bundle);
+            lockAppId = access.appId ?? lockAppId;
+            const lines = [...(access.appId && !linkedAtStart ? [`Linked app: ${access.appId}`] : []), ...access.lines];
+            if (lines.length)
+                options.output(lines.map(line => `  ${line}`).join("\n"));
+        }
         return { origin, stop };
     }
     catch (error) {

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

@@ -71,7 +71,7 @@ async function answerLocally(request, response, path, host, origin, options) {
     // Governed AI needs the app's identity for its trace; a signed-in builder's app is linked on first use.
     const appId = options.appId() ?? (ai && options.linkApp ? await options.linkApp().catch(() => undefined) : undefined);
     if (!appId) {
-        reject(response, 409, "CONFLICT", ai ? "This app could not be linked with Harbour yet; check `harbour login` and try again." : "This app is not linked yet. Run `harbour integrations request <connection> --reason <text>` once.", "APP_NOT_LINKED");
+        reject(response, 409, "CONFLICT", ai ? "This app could not be linked with Harbour yet; check `harbour login` and try again." : "This app is not linked yet: restart `harbour dev` now that you are signed in, or run `harbour integrations request <connection> --app-root .` once.", "APP_NOT_LINKED");
         return;
     }
     if (body === undefined) {

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

@@ -1,5 +1,5 @@
 import { basename } from "node:path";
-import { linkIdempotencyKey, OPERATIONS, readDeclaration, readKitLock, requestResources, writeKitLock, newKitLock } from "./kit.js";
+import { linkIdempotencyKey, OPERATIONS, readDeclaration, readKitLock, requestResourceName, requestResources, writeKitLock, newKitLock } from "./kit.js";
 import { CliError } from "./output.js";
 export class GovernanceClient {
     apiUrl;
@@ -15,6 +15,7 @@ export class GovernanceClient {
     link(input) {
         return this.call("POST", "/v1/development/apps/link", { tenantId: this.tenantId, ...input });
     }
+    /** One app-wide request per (connection, identity): no environment and no expiry — IT approves once for every lane and sets any expiry itself. */
     request(appId, input) {
         return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/integration-requests`, { tenantId: this.tenantId, ...input });
     }
@@ -72,41 +73,92 @@ export async function ensureLinkedApp(root, client, tenantId, bundle) {
     return linked.appId;
 }
 export const ENVIRONMENTS = ["development", "preview", "production"];
+export const IDENTITY_WORDS = { app: "as the company bot", user: "as the signed-in person" };
+/** A refusal about the leg rather than the ask — signed out, unreachable, an answer with no code — is nobody's ask and stops the run. */
+const legFailure = (code) => code === "AUTH_REQUIRED" || code === "GOVERNANCE_UNREACHABLE" || code.startsWith("HTTP_");
+/** One request per identity mode of the connection. A refusal of an ask is returned beside the others, not thrown, so a caller can report every connection at once. */
+async function submitRequests(client, appId, declaration, root, connection, reason, only) {
+    return Promise.all(requestScope(declaration, connection, only).map(async (part) => {
+        const ask = { connection, ...part };
+        try {
+            return { ...ask, outcome: await client.request(appId, { connection, identityMode: part.identityMode, operations: part.operations, resources: part.resources, ...(part.presentation ? { presentation: part.presentation } : {}), ...(reason?.trim() ? { reason: reason.trim() } : {}) }) };
+        }
+        catch (error) {
+            const refusal = unregisteredResourceGuidance(error, declaration, connection, root);
+            if (!(refusal instanceof CliError) || legFailure(refusal.code))
+                throw refusal;
+            return { ...ask, error: refusal };
+        }
+    }));
+}
+/** The filed asks with every refusal thrown, for the commands that cannot go on past one. */
+function settled(requests) {
+    return requests.map(item => { if (item.error)
+        throw item.error; return item; });
+}
 /**
- * One request per identity mode from the declaration's scope (or the named subset).
- * Polls the grant list for up to 30 s; PENDING is reported as pending, never as ready.
+ * Files the app-wide request for every connection the app declares, one per
+ * identity mode — what `harbour dev` (signed in) and `productionise` do before
+ * anything else, so IT's queue holds the ask from the first run and no command
+ * stands between a builder and an approval. Idempotent: governance answers
+ * READY for a scope IT has approved and PENDING with the existing request for
+ * one it is still deciding, so a repeat opens nothing. Links the app first
+ * (the same key as `integrations request`) and reads the lanes back, grouped.
+ * An app with no declaration or no connections is left alone: nothing to ask,
+ * so governance is not called.
+ */
+export async function fileDeclaredRequests(root, client, tenantId, bundle) {
+    const { declaration, errors } = await readDeclaration(root);
+    if (errors.length) {
+        if (errors[0].startsWith(".harbour/integrations.json is missing"))
+            return undefined;
+        throw new CliError("DECLARATION_INVALID", `.harbour/integrations.json is invalid: ${errors[0]}`);
+    }
+    const connections = Object.keys(declaration.connections);
+    if (!connections.length)
+        return undefined;
+    const appId = await ensureLinkedApp(root, client, tenantId, bundle);
+    const requests = (await Promise.all(connections.map(connection => submitRequests(client, appId, declaration, root, connection)))).flat();
+    return { appId, requests, groups: groupGrants((await client.list(appId)).grants) };
+}
+/**
+ * `harbour integrations request`: the request for one connection (or the named
+ * subset of its operations) now, one per identity mode. Polls the grant list
+ * for up to 30 s; PENDING is reported as pending, never as ready.
  */
 export async function requestIntegrations(root, client, tenantId, bundle, options) {
     const { declaration, errors } = await readDeclaration(root);
     if (errors.length)
         throw new CliError("DECLARATION_INVALID", `.harbour/integrations.json is invalid: ${errors[0]}`);
-    const environment = options.environment ?? "development";
-    if (!ENVIRONMENTS.includes(environment))
-        throw new CliError("USAGE", "--environment must be development, preview or production.");
-    if (!options.reason.trim())
-        throw new CliError("USAGE", "--reason <text> is required.");
-    if (options.expiresAt && Number.isNaN(Date.parse(options.expiresAt)))
-        throw new CliError("USAGE", "--expires-at must be an ISO-8601 UTC timestamp.");
-    const scope = requestScope(declaration, options.connection, options.operations);
     const appId = await ensureLinkedApp(root, client, tenantId, bundle);
-    const submitted = await Promise.all(scope.map(async (part) => ({ ...part, ...await client.request(appId, { connection: options.connection, environment, identityMode: part.identityMode, operations: part.operations, resources: part.resources, ...(part.presentation ? { presentation: part.presentation } : {}), ...(options.expiresAt ? { expiresAt: options.expiresAt } : {}), reason: options.reason }).catch((error) => { throw unregisteredResourceGuidance(error, declaration, options.connection, environment, options.reason, root); }) })));
+    const submitted = settled(await submitRequests(client, appId, declaration, root, options.connection, options.reason, options.operations)).map(item => ({ ...item, state: item.outcome.state }));
     const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
     const pollMs = options.pollMs ?? 3_000;
     let grants = [];
-    for (let waited = 0; submitted.some(item => item.state === "PENDING") && waited < 30_000; waited += pollMs) {
-        await sleep(pollMs);
+    for (let waited = 0;; waited += pollMs) {
         grants = (await client.list(appId)).grants;
         // A grant that already serves an older scope reads "ready" while this request (an expansion, a renewal,
         // a changed per-app name) is still attached to it as pending: READY only once the grant no longer waits on it.
         for (const item of submitted) {
-            const grant = grants.find(candidate => candidate.grantId === item.grantId);
-            if (grant?.failure)
-                throw new CliError(grant.failure.code, `${grant.failure.message} ${grant.failure.remediation}`);
-            if (grant?.readiness === "ready" && grant.pendingRequestId !== item.requestId)
+            const grant = grants.find(candidate => candidate.grantId === item.outcome.grantId);
+            // Guidance also rides on a grant that is still being retried ("attempt 1 of 3 …"); only a failed readiness ends the wait.
+            if (grant?.failure && grant.readiness === "failed")
+                throw failureError(grant.failure);
+            if (grant?.readiness === "ready" && grant.pendingRequestId !== item.outcome.requestId)
                 item.state = "READY";
         }
+        if (!submitted.some(item => item.state === "PENDING") || waited >= 30_000)
+            break;
+        await sleep(pollMs);
     }
-    return { appId, connection: options.connection, environment, requests: submitted.map(item => ({ identityMode: item.identityMode, operations: item.operations, resources: item.resources, ...(item.presentation ? { presentation: item.presentation } : {}), requestId: item.requestId, grantId: item.grantId, state: item.state, readiness: item.state === "PENDING" ? "pending" : grants.find(grant => grant.grantId === item.grantId)?.readiness ?? (item.state === "READY" ? "ready" : "denied") })) };
+    const groups = groupGrants(grants);
+    return { appId, connection: options.connection, requests: submitted.map(item => ({
+            identityMode: item.identityMode, operations: item.operations, resources: item.resources, ...(item.presentation ? { presentation: item.presentation } : {}),
+            ...(item.outcome.requestId ? { requestId: item.outcome.requestId } : {}), grantId: item.outcome.grantId, state: item.state,
+            readiness: item.state === "PENDING" ? "pending" : grants.find(grant => grant.grantId === item.outcome.grantId)?.readiness ?? (item.state === "READY" ? "ready" : "denied"),
+            // The three lanes in one sentence, as `integrations status` prints them (the request itself names the anchor lane's grant).
+            summary: laneSummary(findGroup(groups, options.connection, item.identityMode), item.outcome.requestId)
+        })) };
 }
 const UNREGISTERED_RESOURCE = /^resource "([^"]+)" is not registered for \S+ on "([^"]+)"$/;
 /**
@@ -117,7 +169,7 @@ const UNREGISTERED_RESOURCE = /^resource "([^"]+)" is not registered for \S+ on
  * up. The code is kept for `--json`; the sentence names the resource, the one
  * console place where IT adds it, and the command to run again afterwards.
  */
-export function unregisteredResourceGuidance(error, declaration, connection, environment, reason, root) {
+export function unregisteredResourceGuidance(error, declaration, connection, root) {
     if (!(error instanceof CliError) || error.code !== "RESOURCE_NOT_APPROVED")
         return error;
     const match = UNREGISTERED_RESOURCE.exec(error.message);
@@ -128,55 +180,123 @@ export function unregisteredResourceGuidance(error, declaration, connection, env
     const operations = Object.keys(declared?.operations ?? {});
     const provider = operations.some(name => name.startsWith("gmail.")) ? "Gmail" : operations.some(name => name.startsWith("slack.")) ? "Slack" : connection;
     const place = declared?.kind === "database"
-        ? `Controls & integrations → Databases → ${connection} → Data resources for ${environment}`
+        ? `Controls & integrations → Databases → ${connection} → Data resources`
         : `Controls & integrations → API integrations → ${provider} → Configure → ${provider === "Gmail" ? "the mailbox" : "Channels"}`;
-    const command = `harbour integrations request ${connection} --reason "${reason}" --app-root ${root}${environment === "development" ? "" : ` --environment ${environment}`}`;
-    return new CliError(error.code, `IT has to add ${resource} to the ${connection} connection first (in the Harbour console: ${place}); the app works without it until then, and once it is added run \`${command}\` again.`, error.operationRef);
+    return new CliError(error.code, `IT has to add ${resource} to the ${connection} connection first (in the Harbour console: ${place}); the app works without it until then, and once it is added run \`harbour integrations request ${connection} --app-root ${root}\` again (\`harbour dev\` and \`harbour productionise\` file the request too).`, error.operationRef);
+}
+export function groupGrants(grants) {
+    const groups = new Map();
+    for (const grant of grants) {
+        const key = `${grant.identityMode}:${grant.connection}`;
+        const group = groups.get(key) ?? { connection: grant.connection, identityMode: grant.identityMode, lanes: {} };
+        if (ENVIRONMENTS.includes(grant.environment))
+            group.lanes[grant.environment] = grant;
+        groups.set(key, group);
+    }
+    return [...groups.values()].sort((a, b) => a.connection.localeCompare(b.connection) || a.identityMode.localeCompare(b.identityMode));
 }
+/** The group of one ask, or an empty one (no lane on file yet). */
+export function findGroup(groups, connection, identityMode) {
+    return groups.find(group => group.connection === connection && group.identityMode === identityMode) ?? { connection, identityMode, lanes: {} };
+}
+/** The open request of a group: it sits on the production lane (the anchor), so whichever lane record carries one names it. */
+export function openRequestId(lanes) {
+    return ENVIRONMENTS.map(lane => lanes[lane]?.pendingRequestId).find(Boolean);
+}
+/** A granted lane past IT's expiry (the server reads it as failed; the sentence says why). */
+const expired = (grant, nowMs) => grant.status === "GRANTED" && Boolean(grant.expiresAt && Date.parse(grant.expiresAt) <= nowMs);
+/** A lane a deploy can run on: granted, unexpired, not still provisioning or failed (a person's consent is asked in the app, at runtime). */
+const laneReady = (grant, nowMs) => grant.status === "GRANTED" && !expired(grant, nowMs) && grant.readiness !== "pending" && grant.readiness !== "failed";
+/** Builder-safe failure guidance as one sentence: what failed, then what to do. */
+export const failureSentence = (failure) => `${failure.message} ${failure.remediation}`;
+const failureError = (failure) => new CliError(failure.code, failureSentence(failure));
 /**
- * `productionise` pre-check: the preview deploy holds until every declared
- * connection has a GRANTED, unexpired preview grant per identity mode, so the
- * CLI checks first and names the exact request to make. Links the app when
- * needed (same idempotency key as `integrations request`) so both commands
- * share one appId. Returns the kit appId, or undefined for a non-kit app.
+ * One sentence for the three lanes: `ready in development, preview, production`
+ * when they agree, otherwise the lanes that differ — `development ready
+ * (preapproved until <ts>); preview, production waiting for IT (request <id>)`.
+ * A lane with no record yet is waiting on the group's open request (the list
+ * read right after filing may not carry the anchor yet, so the filing's own
+ * request id is the fallback). Development ready while another lane waits is
+ * the connection's development preapproval: the server writes that lane at
+ * filing time and keeps the request open for IT.
  */
-export async function assertPreviewIntegrationsReady(root, client, tenantId, bundle, output) {
-    const lock = await readKitLock(root);
-    const { declaration, errors } = await readDeclaration(root);
-    if (errors.length) {
-        if (errors[0].startsWith(".harbour/integrations.json is missing"))
-            return lock?.appId || undefined;
-        throw new CliError("DECLARATION_INVALID", `.harbour/integrations.json is invalid: ${errors[0]}`);
+export function laneSummary(group, requestHint, nowMs = Date.now()) {
+    const { lanes } = group;
+    const open = openRequestId(lanes) ?? requestHint;
+    const waitingOn = (lane) => { const grant = lanes[lane]; return grant ? (grant.readiness === "pending" ? grant.pendingRequestId ?? requestHint : undefined) : open; };
+    const word = (lane) => {
+        const grant = lanes[lane];
+        const request = waitingOn(lane);
+        if (!grant)
+            return { base: request ? `waiting for IT (request ${request})` : "not requested", suffix: "" };
+        if (expired(grant, nowMs))
+            return { base: `expired ${grant.expiresAt}`, suffix: "" };
+        const until = grant.expiresAt ? ` until ${grant.expiresAt}` : "";
+        switch (grant.readiness) {
+            case "ready": return { base: "ready", suffix: lane === "development" && ENVIRONMENTS.some(other => other !== lane && waitingOn(other)) ? ` (preapproved${until})` : until };
+            case "consent_required": return { base: "approved", suffix: " (connect your account in the app)" };
+            case "reconnect_required": return { base: "approved", suffix: " (reconnect your account in the app)" };
+            case "pending": return { base: request ? `waiting for IT (request ${request})` : "being set up", suffix: "" };
+            case "failed": return { base: grant.status === "DENIED" ? "denied" : grant.status === "REVOKED" ? "revoked" : "failed", suffix: "" };
+        }
+    };
+    const segments = [];
+    for (const lane of ENVIRONMENTS) {
+        const { base, suffix } = word(lane);
+        const segment = segments.find(candidate => candidate.base === base && candidate.suffix === suffix);
+        if (segment)
+            segment.lanes.push(lane);
+        else
+            segments.push({ base, suffix, lanes: [lane] });
     }
-    const connections = Object.keys(declaration.connections);
-    if (!connections.length)
-        return lock?.appId || undefined;
-    const appId = await ensureLinkedApp(root, client, tenantId, bundle);
-    const grants = (await client.list(appId)).grants;
-    const nowMs = Date.now();
-    const missing = [];
-    for (const connection of connections) {
-        for (const { identityMode } of requestScope(declaration, connection)) {
-            const grant = grants.find(candidate => candidate.connection === connection && candidate.environment === "preview" && candidate.identityMode === identityMode);
-            const why = !grant ? "no preview grant requested"
-                : grant.status !== "GRANTED" ? `preview grant is ${grant.status}${grant.readiness === "pending" ? " (waiting for IT)" : ""}`
-                    : grant.expiresAt && Date.parse(grant.expiresAt) <= nowMs ? `preview grant expired ${grant.expiresAt}`
-                        : grant.readiness === "pending" || grant.readiness === "failed" ? `preview grant is ${grant.readiness}`
-                            : undefined;
-            if (why)
-                missing.push({ connection, identityMode, why });
+    return segments.length === 1 ? `${segments[0].base} in ${ENVIRONMENTS.join(", ")}${segments[0].suffix}` : segments.map(segment => `${segment.lanes.join(", ")} ${segment.base}${segment.suffix}`).join("; ");
+}
+/** The group's line — `company-slack [as the company bot] ready in development, preview, production` — plus the failure guidance of any lane, once per distinct failure. */
+export function renderGrantGroup(group, nowMs = Date.now()) {
+    const lines = [`${group.connection} [${IDENTITY_WORDS[group.identityMode]}] ${laneSummary(group, undefined, nowMs)}`];
+    const seen = new Set();
+    for (const lane of ENVIRONMENTS) {
+        const failure = group.lanes[lane]?.failure;
+        if (failure && !seen.has(failure.message)) {
+            seen.add(failure.message);
+            lines.push(`  ${failureSentence(failure)}`);
         }
     }
-    if (!missing.length)
-        return appId;
-    const unresolved = [...new Set(missing.map(item => item.connection))];
-    output(`Harbour cannot deploy the preview yet: ${missing.length} integration grant${missing.length === 1 ? " is" : "s are"} missing.`);
-    for (const item of missing)
-        output(`  ${item.connection} (${item.identityMode} identity): ${item.why}`);
-    output("Request each one, then rerun productionise:");
-    for (const connection of unresolved)
-        output(`  harbour integrations request ${connection} --environment preview --reason "<why>" --app-root ${root}`);
-    throw new CliError("INTEGRATIONS_NOT_READY", `Preview grants are missing for ${unresolved.join(", ")}. Run the \`harbour integrations request … --environment preview\` commands above, then rerun productionise.`);
+    return lines;
+}
+/**
+ * `productionise` pre-check. Files the app-wide request for every declared
+ * connection (idempotent: READY comes straight back once IT has approved), then
+ * reads the preview lane — the one this deploy runs in — and refuses before any
+ * operation exists, naming exactly what is still waiting. Links the app when
+ * needed (the same key as `integrations request`) so both share one appId.
+ * Returns the kit appId, or undefined for a non-kit app.
+ */
+export async function assertPreviewIntegrationsReady(root, client, tenantId, bundle, output) {
+    const filed = await fileDeclaredRequests(root, client, tenantId, bundle);
+    if (!filed)
+        return (await readKitLock(root))?.appId || undefined;
+    const nowMs = Date.now();
+    const waiting = [];
+    for (const item of settled(filed.requests)) {
+        const group = findGroup(filed.groups, item.connection, item.identityMode);
+        const preview = group.lanes.preview;
+        // Guidance also rides on a lane that is still being retried; only a failed readiness is a refusal in its own words.
+        if (preview?.failure && preview.readiness === "failed")
+            throw failureError(preview.failure);
+        if (preview && laneReady(preview, nowMs))
+            continue;
+        const requestId = item.outcome.requestId ?? openRequestId(group.lanes);
+        waiting.push(requestId
+            ? `Waiting for IT: ${item.connection} ${IDENTITY_WORDS[item.identityMode]} (request ${requestId}).`
+            : `${item.connection} ${IDENTITY_WORDS[item.identityMode]} is not ready for the preview (${laneSummary(group, undefined, nowMs)}); ask IT to review this app's access in the Harbour console.`);
+    }
+    if (!waiting.length)
+        return filed.appId;
+    output("Harbour cannot deploy the preview yet:");
+    for (const line of waiting)
+        output(`  ${line}`);
+    throw new CliError("INTEGRATIONS_NOT_READY", `${waiting.join(" ")} IT approves a request once, for every environment; rerun productionise when it is approved.`);
 }
 /**
  * `productionise` / `promote` pre-check for an app that calls governed AI
@@ -219,7 +339,7 @@ export function requestScope(declaration, connection, only) {
         const entry = byMode.get(mode) ?? { operations: [], resources: new Map() };
         entry.operations.push(name);
         for (const resource of requestResources(declared.operations[name]))
-            entry.resources.set(typeof resource === "string" ? resource : resource.name, resource);
+            entry.resources.set(requestResourceName(resource), resource);
         byMode.set(mode, entry);
     }
     return [...byMode.entries()].map(([identityMode, entry]) => ({

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

@@ -32,6 +32,7 @@ export const DEPENDENT_READ_OPERATIONS = ["gmail.message.read"];
  */
 export function emptyDeclaration() { return { schema: "harbour.app-integrations/2.0", connections: {} }; }
 export function resourceNames(operation) { return Array.isArray(operation.resources) ? operation.resources : Object.keys(operation.resources); }
+export const requestResourceName = (resource) => typeof resource === "string" ? resource : resource.name;
 export function requestResources(operation) {
     return Array.isArray(operation.resources) ? operation.resources : Object.entries(operation.resources).map(([name, spec]) => ({ name, columns: [...spec.columns] }));
 }

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

@@ -72,8 +72,8 @@ export async function productionise(rootArg, client, output, tenantId, includePa
         await assertChecksPassedForTree(root, output);
     const files = pending?.uploaded ? [] : await Promise.all(graph.deploymentScope.includedFiles.map(async (path) => ({ path, content: new Uint8Array(await readFile(resolve(root, path))) })));
     output(`Harbour found ${graph.deploymentScope.includedFiles.length} app files.`);
-    // A declared connection without its preview grant would only park the
-    // deployment after the save; refuse here, before any operation exists.
+    // A declared connection IT has not approved yet would only park the
+    // deployment after the save; file the request and refuse here, before any operation exists.
     const kitAppId = pending?.appId ?? (options.integrations ? await assertPreviewIntegrationsReady(root, options.integrations.governance, tenantId, options.integrations.bundle, output) : options.appId);
     // An app that calls governed AI needs the company's AI setup to pass the
     // deployment PLAN; ask governance now rather than discover it on the deployed button.

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

@@ -92,7 +92,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` (declared per app: `app` posts as the company's Slack bot, Isomorph AI, under the name IT approved; `user` posts as the signed-in person after their consent), `gmail.thread.list`, `gmail.message.read` and `gmail.message.send` (user identity — reads and one plain-text send as the signed-in person, 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 — by the identifier `harbour integrations catalog --app-root .` lists, with only the operations the app calls and only channels, views and mailboxes the catalog shows as approved; never a guessed name — 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. Before a real integration test, read `harbour integrations status --app-root . --json`: show pending IT approval separately from personal consent, and test ready destinations independently. After a partial send, retry only the failed destination with its original idempotency key; do not regenerate or resend a successful destination. 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`.",
+        "- `.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 — by the identifier `harbour integrations catalog --app-root .` lists, with only the operations the app calls and only channels, views and mailboxes the catalog shows as approved; never a guessed name — then ask for access — one request per connection, which IT approves once for every environment (development, preview and production together): `harbour dev` and `harbour productionise` file it for you, and `harbour integrations request <connection> --reason \"<why>\" --app-root .` files it now. 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. Before a real integration test, read `harbour integrations status --app-root . --json`: show pending IT approval separately from personal consent, and test ready destinations independently. After a partial send, retry only the failed destination with its original idempotency key; do not regenerate or resend a successful destination. 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`.",
         "- Scheduled work lives only in `jobs/<name>.ts`: export one literal UTC cron as `schedule` and one default async handler. Test it immediately with `harbour jobs run <name> --app-root . --scheduled-at <UTC> --json`; this uses local data and safe fixtures. If the person explicitly asks for a company-action test, use `--real` only after the exact action has development approval. Tell them: \"Your scheduled task is ready. I can test the app on your computer now. Company messages will start after the app is online and access is approved.\" Harbour runs the same declaration automatically after deployment; never use `setInterval`, an effect or a browser timer as a scheduler.",
         "- In browser code, 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 or browser timer, and never send during checks. A `jobs/*.ts` handler is the only scheduled-send path and acts as the app: only an app-mode operation may run there, after the person explicitly requested it and IT granted its exact destination for that environment. Use a deterministic idempotency key for the business period and destination; local job runs and checks use fixtures and send nothing.",
         "- 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.",
@@ -121,7 +121,7 @@ Follow the "Harbour development kit" block in CLAUDE.md / AGENTS.md. Workflow:
 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 5). 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/checks/\` is generated, not written by hand: \`harbour check\` reads \`migrations/\` and \`src/\` and writes one retained journey per capability the app's own code uses (plus a cross-user denial per owner-scoped table), deleting the ones the app no longer needs — so run it in the same edit that changes the app instead of adding or deleting these files yourself. It reports anything it cannot generate (\`actions\`, \`realtime\`, a table with no migration) for you to write. Edit a generated check and it becomes yours: Harbour keeps it, stops managing it and never removes it, so deleting it when the feature goes is then your job. \`harbour check\` and the deployment pipeline replay these checks against a real App Gateway and refuse the app (\`flow.check-failed\`) in both directions — a capability no check exercises, and a check that exercises something the code no longer does.
 4. \`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); a retained check that calls \`harbour.integrations.execute\` is answered by the gate's fixture (the contract's shape for what the app declared, nothing sent or read) and the passed check says so. A governed AI call (\`harbour.ai.chat\`) is exercised for real through the development route while \`harbour dev\` is up; the pipeline answers it with a canned completion and reports it as not tested.
-5. \`harbour integrations request <connection> --reason "<why>" --app-root .\` asks IT for development access; pending is not ready.
+5. \`harbour integrations request <connection> --reason "<why>" --app-root .\` asks IT for access now — one request per connection, approved once for every environment; \`harbour dev\` (signed in) and \`harbour productionise\` file it for you. Pending is not ready.
 6. \`harbour productionise --app-root .\` saves and deploys the preview; \`harbour promote\` after the person has tested it.
 `;
 /**
@@ -134,8 +134,8 @@ function kitFiles() {
     return {
         // 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
+        // files the access request for every declared connection and refuses to
+        // start until IT has approved 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
@@ -240,7 +240,7 @@ Add one in two steps, when the app really calls it:
    "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.
+2. Ask IT for access: one request per connection, and IT approves it once for every environment (development, preview and production together). \`harbour dev\` (signed in) and \`harbour productionise\` file it for you; \`harbour integrations request <connection> --reason "<why>" --app-root .\` files it now. \`harbour integrations status --app-root .\` says where each connection stands in every environment; PENDING is not ready, and \`harbour productionise\` will not deploy until IT has approved every declared connection.
 
 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:
 
@@ -348,8 +348,9 @@ export function App() {
   //    (slack.message.post "identity": "app" posts as the company's Slack bot, Isomorph AI, under the
   //    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 uncomment
+  // 2. Request access — one request per connection, which IT approves once for every
+  //    environment; harbour dev and harbour productionise file it for you, or file it now with
+  //    harbour integrations request sales-warehouse --reason "<why>" --app-root . — 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 }

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

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

package/package.json

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