@isomorph.ai/cli 0.5.2 → 0.7.0

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

@@ -118,7 +118,7 @@ Rules live beside this file: \`core.md\` before the first edit; \`integrations.m
 | "run it", "show me" | \`isomorph dev --app-root . --detach --json\`; give them \`result.origin\` (the first start takes a minute or two). Locally they are a fixture user. |
 | "check it", "is it ready?" | \`isomorph check --app-root . --json\` (the output is the report). Failures in the app's code are yours: fix and re-check until clean, after every change and before every ship, unasked and never offered as a choice. |
 | "does it work?" (and before reporting anything as working) | open the dev link in your own browser, press the control you built or changed, read what the app shows; a green \`isomorph check\` is not that proof (fixtures answer AI and company systems). A Send in development is real: reuse explicit authorization or ask once. No browser: say the button is untested. |
-| "I need Slack / Gmail / the warehouse" | read \`integrations.md\` beside this skill first; then, in the same turn: catalog, declare only what the app calls, submit the request yourself, say READY or PENDING in one line. |
+| "I need Slack / Gmail / the warehouse" | read \`integrations.md\` beside this skill first; then, in the same turn: catalog, call only what it lists (literals), submit the request yourself, say READY or PENDING in one line. |
 | "summarise", "draft", "AI" | read \`ai.md\` beside this skill first; then one call behind a control they press. |
 | "ship it", "let my team try it" | show the person the three values in \`.isomorph/app.json\` (name, description, audience — "only you" when empty) and correct the file as they say; then \`isomorph deploy --app-root . --json\` (it runs the checks when needed and refuses once naming every blocker and its fix: relay that line; the app works meanwhile). Give them \`result.deployment.protectedUrl\`. \`--session-notes\`: what cost you time in Isomorph, or \`""\`. |
 | "make it live" | only after they have tried the preview: \`isomorph promote --operation <ref> --app-root . --confirm-tested --json\`. Report the production link, or that operator approval is pending. |

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

@@ -2,7 +2,7 @@ import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { CliError } from "./output.js";
 import { DEPENDENT_READ_OPERATIONS, READ_OPERATIONS, kitPaths, readDeclaration, readKitLock, resourceNames, sourceDigest } from "./kit.js";
-import { LocalRuntime, allocatePorts, ensureSdk, freePort, nodePackageCommand, readDevLock, runningOrigin } from "./local-runtime.js";
+import { LocalRuntime, allocatePorts, freePort, installDependencies, nodePackageCommand, readDevLock, runningOrigin } from "./local-runtime.js";
 import { CLI_VERSION } from "./version.js";
 /**
  * What actually failed, in the refusal itself.
@@ -45,17 +45,15 @@ export async function runChecks(root, options) {
     const previous = await readReport(root);
     if (previous && previous.sourceDigest !== (await sourceDigest(root)).digest)
         output("Source changed since the last report; the previous report is no longer valid.");
+    // A fresh clone has no node_modules: install once, and say so, before the typecheck needs the SDK's types.
+    await installDependencies(root, bundle, run, output);
     const npx = nodePackageCommand("npx", ["tsc", "--noEmit"]);
     const typecheck = await run(npx.command, npx.args, { cwd: root, quiet: true });
     record({ name: "typecheck", status: typecheck.code === 0 ? "pass" : "fail", ...(typecheck.code === 0 ? {} : { detail: lastLines(typecheck.stdout || typecheck.stderr) }) });
     const npm = nodePackageCommand("npm", ["run", "build"]);
     const build = await run(npm.command, npm.args, { cwd: root, quiet: true });
     record({ name: "build", status: build.code === 0 ? "pass" : "fail", ...(build.code === 0 ? {} : { detail: lastLines(build.stderr || build.stdout) }) });
-    // The gate runs the journeys with this node and the app's own SDK: the SDK
-    // the bundle pins, installed now if node_modules holds an older copy.
-    const sdk = await ensureSdk(root, bundle, options.env ?? process.env, run, output).catch(error => { output(error instanceof Error ? error.message : String(error)); return "missing"; });
-    if (sdk === "missing")
-        output(`The kit SDK is not installed: set ISOMORPH_KIT_SDK_TARBALL to the bundle's ${bundle.sdk.package} tarball (or use a bundle with sdk.url).`);
+    // The gate runs the journeys with this node and the SDK the app's own install put in node_modules.
     const gate = await runKitGate(root, { run, bundle, output, ...(options.fetch ? { fetch: options.fetch } : {}), ...(options.runtime ? { runtime: options.runtime } : {}), ...(options.pollMs ? { pollMs: options.pollMs } : {}) });
     for (const check of gate.checks)
         record(check);
@@ -69,14 +67,11 @@ export async function runChecks(root, options) {
         // failure ended the run as `fetch failed` (CLI_FAILED) with no report written.
         const skipped = (why) => record({ name: "integrations", status: "not_run", detail: why });
         const lock = await readKitLock(root).catch(() => undefined);
-        const { declaration, errors } = await readDeclaration(root);
         if (!lock?.appId)
             skipped("the app is not linked yet; `isomorph dev` (signed in) or `isomorph integrations request` links it");
-        else if (errors.length)
-            skipped(`.isomorph/integrations.json is invalid: ${errors[0]}`);
         else {
             try {
-                integrations = await testIntegrationReads(lock.appId, options.governance, declaration, output);
+                integrations = await testIntegrationReads(lock.appId, options.governance, await readDeclaration(root), output);
                 if (!integrations.length)
                     output("No READY development grants with read operations; real integrations were not exercised.");
             }
@@ -97,7 +92,7 @@ export async function runChecks(root, options) {
         createdAt: new Date().toISOString(),
         sourceDigest: source.digest,
         sourceFiles: source.entries,
-        toolchain: { node: process.version, cliVersion: CLI_VERSION, bundle: { kitVersion: bundle.kitVersion, sdkTarballSha256: bundle.sdk.tarballSha256, briefFingerprint: bundle.brief.fingerprint } },
+        toolchain: { node: process.version, cliVersion: CLI_VERSION, bundle: { kitVersion: bundle.kitVersion, sdkVersion: bundle.sdk.version, briefFingerprint: bundle.brief.fingerprint } },
         checks,
         gate,
         integrations,
@@ -252,8 +247,8 @@ function indentLines(detail) { return detail.split("\n").map((line, index) => in
  */
 export async function writeGateFiles(root, files, output) {
     for (const [path, content] of Object.entries(files)) {
-        if (!/^\.isomorph\/checks\/[A-Za-z0-9._-]+$/.test(path))
-            throw new CliError("LOCAL_RUNTIME_FAILED", `The kit gate named a file outside .isomorph/checks/: ${path}.`);
+        if (!/^\.isomorph\/(checks\/[A-Za-z0-9._-]+|integrations\.json)$/.test(path))
+            throw new CliError("LOCAL_RUNTIME_FAILED", `The kit gate named a file it does not own: ${path}.`);
         const target = join(root, path);
         if (content === null) {
             await rm(target, { force: true });

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

@@ -11,7 +11,7 @@ import { initKit } from "./starter.js";
 import { packageApp } from "./package.js";
 import { agentPaths, agentSetup } from "./agent-setup.js";
 import { detachDev, startDev } from "./dev.js";
-import { endProcess, ensureSdk, LocalRuntime, readDevLock, releaseDevLock, runCommand } from "./local-runtime.js";
+import { endProcess, installDependencies, LocalRuntime, readDevLock, releaseDevLock, runCommand } from "./local-runtime.js";
 import { CHECKS_FAILED_HINT, checksFailedMessage, runChecks } from "./check.js";
 import { assertDeployReady, companySystemsLine, GovernanceClient, groupGrants, IDENTITY_WORDS, integrationsCatalog, integrationsStatus, renderGrantGroup, renderIntegrationsCatalog, requestIntegrations } from "./integrations.js";
 import { runJob } from "./jobs.js";
@@ -87,7 +87,7 @@ const emit = (value, line) => { process.stdout.write(json ? `${JSON.stringify(va
  */
 const exitAfterWriting = (code, out, err = "") => { process.stderr.write(err, () => process.stdout.write(out, () => process.exit(code))); };
 /** Exit 2, like a usage error: nothing started and the fix is a command the maker runs (or a file the maker edits). */
-const USAGE_REFUSALS = ["APP_EXISTS", "APP_UNSUPPORTED", "KIT_APP", "DEPLOY_BLOCKED", "INTEGRATIONS_NOT_READY", "AI_NOT_READY", "CLI_UPGRADE_REQUIRED", "NOT_A_MEMBER", "TENANT_AMBIGUOUS", "NOT_A_START_LINK", "PLATFORM_UNREACHABLE", "DEPLOY_IN_FLIGHT", "OPERATION_REQUIRED"];
+const USAGE_REFUSALS = ["APP_EXISTS", "APP_UNSUPPORTED", "KIT_APP", "DEPLOY_BLOCKED", "INTEGRATIONS_NOT_READY", "AI_NOT_READY", "CLI_UPGRADE_REQUIRED", "KIT_BUNDLE_STALE", "NOT_A_MEMBER", "TENANT_AMBIGUOUS", "NOT_A_START_LINK", "PLATFORM_UNREACHABLE", "DEPLOY_IN_FLIGHT", "OPERATION_REQUIRED"];
 if (command === "--version" || command === "version") {
     process.stdout.write(`${CLI_VERSION}\n`);
     // `-h` was matched anywhere in argv while `--help` was only recognised as the
@@ -138,10 +138,8 @@ else {
                 const result = await initKit(target, bundle, { upgrade, adopt, tenantId: config?.tenantId, env: process.env, displayRoot: root });
                 for (const line of [...result.created.map(path => `created ${path}`), ...result.updated.map(path => `updated ${path}`), ...result.kept.map(path => `kept    ${path}`), ...result.bundleChanges.map(change => `bundle  ${change}`), ...["created", "updated"].flatMap(state => result.agents[state].map(path => `${state} ${path} (agent guide)`))])
                     progress(line);
-                // The SDK is not on the public registry: init installs the pinned tarball (and the app's other dependencies) itself.
-                const sdk = await ensureSdk(target, bundle, process.env, runCommand, progress);
-                if (sdk === "missing")
-                    progress(`The kit SDK was not installed: set ISOMORPH_KIT_SDK_TARBALL to the bundle's ${bundle.sdk.package} tarball (or use a bundle with sdk.url), then rerun \`isomorph init\`.`);
+                // The SDK is a normal dependency: one plain `npm install` when node_modules lacks it or holds one outside the range init wrote.
+                await installDependencies(target, bundle, runCommand, progress);
                 progress(result.mode === "starter" ? "Starter created. Next: `isomorph dev --app-root <path>`. Both agents read the Isomorph block in CLAUDE.md / AGENTS.md and the `isomorph` skill installed by agent-setup."
                     : upgrade ? (result.bundleChanges.length ? "Kit bundle upgraded; running checks." : "Kit bundle already current; running checks.")
                         : result.mode === "kit" ? `This folder is already an Isomorph kit app (any missing kit file was added; nothing else was changed). Next: \`isomorph dev --app-root ${root}\`, \`isomorph check --app-root ${root}\`, \`isomorph deploy --app-root ${root}\`.`

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

@@ -22,14 +22,15 @@ export function assertCliCurrent(config, running = CLI_VERSION) {
         return;
     throw new CliError("CLI_UPGRADE_REQUIRED", `This CLI is ${running}; the company's Isomorph platform needs ${minimum} or newer.`, undefined, `Run \`${CLI_INSTALL_COMMAND}\`, then run this again.`);
 }
+/** The numeric core and prerelease of a version string (`v1.2.3-rc.1` → `[1, 2, 3]`, `rc.1`), or `undefined` for one with no numeric core. */
+export function parseVersion(value) {
+    const match = /^\s*v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(value);
+    return match ? { core: [Number(match[1]), Number(match[2]), Number(match[3])], pre: match[4] } : undefined;
+}
 /** Numeric-core semver order; a prerelease sorts before its release. An unparseable version compares equal, so nothing is called stale on a guess. */
 export function compareCliVersions(left, right) {
-    const parse = (value) => {
-        const match = /^\s*v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(value);
-        return match ? { core: [Number(match[1]), Number(match[2]), Number(match[3])], pre: match[4] } : undefined;
-    };
-    const a = parse(left);
-    const b = parse(right);
+    const a = parseVersion(left);
+    const b = parseVersion(right);
     if (!a || !b)
         return 0;
     for (let index = 0; index < 3; index += 1)

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

@@ -6,7 +6,7 @@ import { CliError } from "./output.js";
 import { continueCommand, follow, outcomeFor, pickSourceFailure, recordedRefusal, runningLine, statusFetch, summarize } from "./operations.js";
 import { CLI_VERSION } from "./version.js";
 import { assertSafeAppRoot, readAppTree } from "./package.js";
-import { deployBlocked, ensureLinkedApp } from "./integrations.js";
+import { deployBlocked, ensureLinkedApp, kitLockBody } from "./integrations.js";
 import { describeSourceChange, kitPaths, readAppProfile, readDeclaration, readKitLock, sourceDigest } from "./kit.js";
 import { CHECKS_FAILED_HINT, checksFailedMessage, FLOW_CHECK, readReport, runChecks } from "./check.js";
 import { runCommand } from "./local-runtime.js";
@@ -50,7 +50,8 @@ async function runDeploy(rootArg, governance, output, tenantId, options) {
     assertSafeAppRoot(root);
     // Only a kit app deploys from here: the checks, the gate and the profile all
     // live in `.isomorph/`. Anything else deploys from the console.
-    if (!(await readKitLock(root)))
+    const lock = await readKitLock(root);
+    if (!lock)
         throw new CliError("KIT_REQUIRED", "This folder is not an Isomorph app: it has no .isomorph/kit.lock.json.", undefined, "Run `isomorph init --app-root .` first.");
     // The three values the person confirmed, printed so the transcript shows what
     // was recorded; recorded on the operation before anything is uploaded.
@@ -63,9 +64,7 @@ async function runDeploy(rootArg, governance, output, tenantId, options) {
     // that is blank too; this only says so before the checks spend a minute.
     if (!profile.name.trim() || !profile.description.trim())
         throw new CliError("PROFILE_INCOMPLETE", "The app needs a name and a description in .isomorph/app.json before it can deploy.", undefined, "Edit `name` and `description` in .isomorph/app.json (show them to the person first), then run this again.");
-    const { declaration, errors } = await readDeclaration(root);
-    if (errors.length && !errors[0].startsWith(".isomorph/integrations.json is missing"))
-        throw new CliError("DECLARATION_INVALID", `.isomorph/integrations.json is invalid: ${errors[0]}`);
+    const declaration = await readDeclaration(root);
     // Link first: the app's identity lands in `.isomorph/kit.lock.json`, which is
     // one of the deployable files, so a report pinned after the link stays fresh
     // through the checks and the package is built from the linked tree.
@@ -93,15 +92,16 @@ async function runDeploy(rootArg, governance, output, tenantId, options) {
         output(`Isomorph is continuing operation ${note.operationRef}; no new deployment was started.`);
     // One call opens the operation — or resumes it — and runs the deploy
     // pre-flight first: a declared connection IT has not approved, a company
-    // whose AI setup is not ready for an app that calls it, or a CLI the platform
-    // no longer accepts would only park the deployment after the save, so
-    // governance refuses here, with every blocker at once, before any operation
-    // exists. The reviewed profile rides on the same call.
+    // whose AI setup is not ready for an app that calls it, a CLI the platform
+    // no longer accepts, or a kit older than the one Isomorph publishes would
+    // only park the deployment after the save, so governance refuses here, with
+    // every blocker at once, before any operation exists. The reviewed profile
+    // and the kit lock's bundle ride on the same call.
     const body = {
         environment: "preview",
         app: { name: profile.name, description: profile.description, audience: profile.audience },
         package: { sha256: archive.digest, bytes: archive.body.byteLength, manifest: { schema: "isomorph.source-package-manifest/1.0", files: manifest.files.map(file => ({ path: file.path, size: file.bytes, sha256: file.sha256 })) } },
-        graph, cliVersion: CLI_VERSION, kitBundleVersion: bundle.kitVersion, declaration, callsAi: await appCallsAi(root)
+        graph, cliVersion: CLI_VERSION, kitBundleVersion: bundle.kitVersion, declaration, callsAi: await appCallsAi(root), kitLock: kitLockBody(lock.bundle)
     };
     let opened;
     try {

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

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { createForwarder } from "./forwarder.js";
 import { readKitLock } from "./kit.js";
 import { GovernanceClient, ensureLinkedApp, fileDeclaredRequests, IDENTITY_WORDS, renderGrantGroup } from "./integrations.js";
-import { acquireDevLock, allocatePorts, ensureSdk, LocalRuntime, nodePackageCommand, pidAlive, readDevLock, recordDevChildren, releaseDevLock, runCommand } from "./local-runtime.js";
+import { acquireDevLock, allocatePorts, installDependencies, LocalRuntime, nodePackageCommand, pidAlive, readDevLock, recordDevChildren, releaseDevLock, runCommand } from "./local-runtime.js";
 import { kitPaths } from "./kit.js";
 import { CliError, safeError } from "./output.js";
 /**
@@ -53,9 +53,7 @@ export async function startDev(root, options) {
         await releaseDevLock(root);
     };
     try {
-        const sdk = await ensureSdk(root, options.bundle, env, run, options.output);
-        if (sdk === "missing")
-            options.output(`The kit SDK is not installed: set ISOMORPH_KIT_SDK_TARBALL to the bundle's ${options.bundle.sdk.package} tarball (or use a bundle with sdk.url).`);
+        await installDependencies(root, options.bundle, run, options.output);
         await runtime.writeFiles(options.bundle, ports);
         options.output("Preparing the kit-managed native runtime (public registry, no login).");
         await runtime.pull(options.bundle);

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

@@ -53,13 +53,12 @@ Shared-read, owner-write: the same, plus \`CREATE POLICY posts_read ON posts FOR
 - \`APP_NOT_FOUND\`: clear \`appId\` and \`tenantId\` in \`.isomorph/kit.lock.json\` to relink.`,
     integrations: `# Company systems (Slack, Gmail, warehouse)
 
-## Declare
+## Call shape
 
-Company systems are reached through \`isomorph.integrations.execute(connection, { operation, resource, input })\`, declared in \`.isomorph/integrations.json\` by catalog identifier, with only the operations called. Closed set: \`slack.channel.history\` (user), \`slack.message.post\` (app or user), \`gmail.thread.list\`, \`gmail.message.read\`, \`gmail.message.send\` (user, \`inbox\`), \`warehouse.view.read\` (app). Resources are logical names, never IDs. Strict JSON.
+One call, this exact shape, never a wrapper function; \`connection\`, \`operation\`, \`resource\`, \`mode\` and \`input.columns\` are catalog literals (logical names, never IDs or variables). \`isomorph check\` derives \`.isomorph/integrations.json\` from them (committed, never edited); \`dev\`/\`deploy\` file the request.
 
-\`\`\`json
-"company-slack": { "kind": "saas", "operations": { "slack.message.post": { "identity": "app", "resources": ["team-updates"] } } },
-"sales-warehouse": { "kind": "database", "operations": { "warehouse.view.read": { "identity": "app", "resources": { "weekly_sales": { "columns": ["week", "total"] } } } } }
+\`\`\`ts
+await isomorph.integrations.execute("sales-warehouse", { operation: "warehouse.view.read", resource: "weekly_sales", input: { columns: ["week", "total"], limit: 100 } });
 \`\`\`
 
 ## Catalog
@@ -70,16 +69,6 @@ Never guess a connection, channel, table, view, mailbox or column: a guess is re
 
 \`isomorph integrations request <connection> --reason "<why>" --app-root . --json\` files the one request IT approves once for every environment (\`isomorph dev\` and \`isomorph deploy\` file it too); submit it yourself, in the same turn. \`isomorph integrations status --app-root . --json\`: READY, use it; PENDING, say "IT has to approve this; the app works meanwhile". \`RESOURCE_NOT_APPROVED\`: IT adds the channel, view or mailbox in the console (Controls & integrations); then run the same request again.
 
-## Call shape
-
-Always this exact shape, never a wrapper function: the kit gate reads the direct call.
-
-\`\`\`ts
-const report = await isomorph.integrations.execute("sales-warehouse", {
-  operation: "warehouse.view.read", resource: "weekly_sales", input: { columns: ["week", "total"], limit: 100 }
-});
-\`\`\`
-
 ## Consent
 
 Only user-identity operations need it, built in unasked: the control calls \`isomorph.integrations.connect(connection)\`, follows \`authorizationUrl\` on \`consent_required\`, and returns to a connected state. Never on page load; app-identity operations never call connect.
@@ -90,7 +79,7 @@ A send (\`slack.message.post\`, \`gmail.message.send\`) runs only from an explic
 
 ## Slack modes
 
-\`"identity": "app"\` posts as the company's bot under IT's approved \`presentation.displayName\`; \`"identity": "user"\` posts as the person after consent (\`USER_RECONNECT_REQUIRED\`: offer Connect again). Name the \`mode\` when both are approved (\`MODE_REQUIRED\`); an unapproved mode is \`MODE_NOT_GRANTED\`, never swapped. \`RESOURCE_NOT_APPROVED\` on a post: the bot is not in the channel; anyone there runs \`/invite @Isomorph AI\`.`,
+\`execute("company-slack", { …, mode: "app" })\` posts as the bot under \`slack.displayName\`/\`iconEmoji\` in \`.isomorph/app.json\`; \`mode: "user"\` posts as the person after consent (\`USER_RECONNECT_REQUIRED\`: offer Connect again). One mode per connection (\`MODE_REQUIRED\`); an unapproved mode is \`MODE_NOT_GRANTED\`, never swapped. \`RESOURCE_NOT_APPROVED\` on a post: the bot is not in the channel; \`/invite @Isomorph AI\`.`,
     ai: `# Governed AI
 
 AI goes through \`isomorph.ai\` only: one \`isomorph.ai.chat({ messages, maxTokens })\` call on the app's one client (\`src/isomorph.client.ts\`), never through a wrapper function (the gate reads only the direct call), behind a control the person presses — never on load, in an effect or a timer. Never add an OpenAI/Anthropic/Gemini key, SDK or URL: the governed AI gateway holds the key and IT sees every call. 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 not enabled an AI provider yet: say so in one line and keep the app working without AI.

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

@@ -1,7 +1,9 @@
 import { basename } from "node:path";
-import { linkIdempotencyKey, OPERATIONS, readDeclaration, readKitLock, requestResourceName, requestResources, writeKitLock, newKitLock } from "./kit.js";
+import { linkIdempotencyKey, readDeclaration, readKitLock, requestResourceName, requestResources, writeKitLock, newKitLock } from "./kit.js";
 import { CliError } from "./output.js";
 import { CLI_VERSION } from "./version.js";
+/** The lock's bundle as the preflight body carries it. */
+export const kitLockBody = (bundle) => ({ kitVersion: bundle.kitVersion, sdk: { version: bundle.sdk.version } });
 export class GovernanceClient {
     apiUrl;
     tenantId;
@@ -164,12 +166,7 @@ function settled(requests) {
  * 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(".isomorph/integrations.json is missing"))
-            return undefined;
-        throw new CliError("DECLARATION_INVALID", `.isomorph/integrations.json is invalid: ${errors[0]}`);
-    }
+    const declaration = await readDeclaration(root);
     const connections = Object.keys(declaration.connections);
     if (!connections.length)
         return undefined;
@@ -183,9 +180,7 @@ export async function fileDeclaredRequests(root, client, tenantId, bundle) {
  * 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", `.isomorph/integrations.json is invalid: ${errors[0]}`);
+    const declaration = await readDeclaration(root);
     const appId = await ensureLinkedApp(root, client, tenantId, bundle);
     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)));
@@ -341,22 +336,23 @@ export function renderGrantGroup(group, nowMs = Date.now()) {
  * governance whether this app can deploy to the environment: it files the
  * declared access requests itself and answers with every blocker at once —
  * the lanes IT still has to approve, the company's AI setup when the app calls
- * governed AI, and a CLI older than the platform's minimum. Prints each
+ * governed AI, a CLI older than the platform's minimum, and a kit older than
+ * the one Isomorph publishes. Prints each
  * blocker's sentence and refuses once, before any operation exists.
  *
  * The code is `DEPLOY_BLOCKED` when the blockers are of more than one kind;
  * when they are all of one kind it is the code readers already know for that
- * kind (`INTEGRATIONS_NOT_READY`, `AI_NOT_READY`, `CLI_UPGRADE_REQUIRED`).
+ * kind (`INTEGRATIONS_NOT_READY`, `AI_NOT_READY`, `CLI_UPGRADE_REQUIRED`,
+ * `KIT_BUNDLE_STALE` — the code intake records for the same refusal).
  * Observed before this: a builder was refused `INTEGRATIONS_NOT_READY`, fixed
  * that, then `AI_NOT_READY`, then the pipeline refused `kit_bundle_incompatible`,
  * each a separate cycle.
  */
 export async function assertDeployReady(root, client, tenantId, bundle, environment, output, callsAi) {
-    const { declaration, errors } = await readDeclaration(root);
-    if (errors.length && !errors[0].startsWith(".isomorph/integrations.json is missing"))
-        throw new CliError("DECLARATION_INVALID", `.isomorph/integrations.json is invalid: ${errors[0]}`);
+    const declaration = await readDeclaration(root);
     const appId = await ensureLinkedApp(root, client, tenantId, bundle);
-    const preflight = await client.deployPreflight(appId, { environment, callsAi, declaration, cliVersion: CLI_VERSION });
+    const lock = await readKitLock(root);
+    const preflight = await client.deployPreflight(appId, { environment, callsAi, declaration, cliVersion: CLI_VERSION, ...(lock ? { kitLock: kitLockBody(lock.bundle) } : {}) });
     if (preflight.ready && !blockersOf(preflight.blockers).length) {
         output(`Isomorph confirmed the app can deploy to ${environment}.`);
         return appId;
@@ -384,27 +380,27 @@ export function deployBlocked(value, environment, output) {
     return new CliError(code, blockers.map(blocker => blocker.sentence).join(" ") || `Isomorph cannot deploy this app to ${environment} yet.`, undefined, fixes || undefined, undefined, { layer: "governance" });
 }
 /** The code readers already know for a refusal that is all of one kind. */
-const BLOCKER_CODES = { integration: "INTEGRATIONS_NOT_READY", ai: "AI_NOT_READY", cli: "CLI_UPGRADE_REQUIRED" };
+const BLOCKER_CODES = { integration: "INTEGRATIONS_NOT_READY", ai: "AI_NOT_READY", cli: "CLI_UPGRADE_REQUIRED", kit: "KIT_BUNDLE_STALE" };
 /**
- * Splits the declared operations of one connection by identity mode — the
- * declaration's own `identity` (the gate has checked it against the closed
- * set; an operation with one mode is read as that mode). The app-mode part
- * that carries `slack.message.post` also carries the connection's declared
- * presentation, so IT sees "posts as" on the request.
+ * Splits the operations the app calls on one connection by identity mode — the
+ * derived declaration's own `identity` (the gate derived it from the call's
+ * `mode` or the operation's only identity and checked it against the closed
+ * set). The app-mode part that carries `slack.message.post` also carries the
+ * connection's presentation (from `.isomorph/app.json`), so IT sees "posts as"
+ * on the request. A connection or operation the app does not call cannot be
+ * asked for: the declaration is the source, so the fix is the call.
  */
 export function requestScope(declaration, connection, only) {
     const declared = declaration.connections[connection];
     if (!declared)
-        throw new CliError("CONNECTION_NOT_DECLARED", `${connection} is not declared in .isomorph/integrations.json.`);
+        throw new CliError("CONNECTION_NOT_CALLED", `The app does not call ${connection}; add the isomorph.integrations.execute call first, then run \`isomorph check\`.`);
     const names = (only?.length ? only : Object.keys(declared.operations));
     const unknown = names.filter(name => !declared.operations[name]);
     if (unknown.length)
-        throw new CliError("OPERATION_NOT_DECLARED", `${unknown.join(", ")} not declared for ${connection}.`);
+        throw new CliError("OPERATION_NOT_CALLED", `The app does not call ${unknown.join(", ")} on ${connection}; add the call first, then run \`isomorph check\`.`);
     const byMode = new Map();
     for (const name of names) {
-        const allowed = OPERATIONS[name]?.identities ?? [];
-        const declaredMode = declared.operations[name].identity;
-        const mode = allowed.includes(declaredMode) ? declaredMode : allowed[0];
+        const mode = declared.operations[name].identity;
         const entry = byMode.get(mode) ?? { operations: [], resources: new Map() };
         entry.operations.push(name);
         for (const resource of requestResources(declared.operations[name]))

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

@@ -1,4 +1,5 @@
 import { PUBLISHED_KIT_BUNDLE } from "./kit-bundle.manifest.js";
+import { parseVersion } from "./config.js";
 /**
  * The local stack's supporting services. Not part of the published bundle: they run only under `isomorph dev`.
  * MinIO is the exact image the pipeline's validation cell runs (data plane `transformbuild.validationMinIOImage`),
@@ -14,24 +15,35 @@ export const LOCAL_SERVICE_IMAGES = {
  * The bundle this CLI was built with: `manifest.json` of the
  * harbour-deployment-data-plane `publish-kit-bundle` artifact for the kit
  * version pinned in package.json `harbour.kitBundle`, fetched at build time
- * into `kit-bundle.manifest.ts` (the images and the tarball live in the kit's
- * public registry, `public.ecr.aws/<alias>/`, pinned by digest so no login
- * and no tag can substitute other bytes). `isomorph init` records it in the
- * app's kit.lock; `isomorph init --upgrade` shows the digest diff against it;
- * the hosted pipeline compares `sdk.tarballSha256` with the SDK it bakes.
+ * into `kit-bundle.manifest.ts` (the native runtime lives in the kit's public
+ * registry, `public.ecr.aws/<alias>/`, pinned by digest so no login and no
+ * tag can substitute other bytes; the SDK is `@isomorph.ai/app-sdk` on npm at
+ * `sdk.version`). `isomorph init` records it in the app's kit.lock and writes
+ * the SDK dependency; `isomorph init --upgrade` shows what moved and bumps the
+ * dependency range; the hosted pipeline refuses a kit.lock whose
+ * `sdk.version` is older than the SDK surface its gate drives.
  */
-export const EMBEDDED_KIT_BUNDLE = { ...PUBLISHED_KIT_BUNDLE, images: { ...LOCAL_SERVICE_IMAGES, ...PUBLISHED_KIT_BUNDLE.images } };
+export const EMBEDDED_KIT_BUNDLE = { ...PUBLISHED_KIT_BUNDLE, sdk: { package: PUBLISHED_KIT_BUNDLE.sdk.package, version: publishedSdkVersion() }, images: { ...LOCAL_SERVICE_IMAGES, ...PUBLISHED_KIT_BUNDLE.images } };
+/** The contracts type still allows a manifest without `sdk.version`; the generator refuses one, so a build that reaches here without it is a stale sync. */
+function publishedSdkVersion() {
+    const version = PUBLISHED_KIT_BUNDLE.sdk.version;
+    if (!version || !parseVersion(version))
+        throw new Error("kit-bundle.manifest.ts names no sdk.version; run `npm run kit-bundle:sync` in packages/harbour-cli");
+    return version;
+}
+/** `"^<sdk.version>"`: the dependency range `init` writes and `init --upgrade` moves. */
+export const sdkDependencyRange = (bundle) => `^${bundle.sdk.version}`;
 export function isKitBundle(value) {
     const record = value;
     return Boolean(record && typeof record === "object" && record.schema === "isomorph.kit-bundle/1.0" && typeof record.kitVersion === "string"
-        && record.sdk && typeof record.sdk.package === "string" && typeof record.sdk.tarballSha256 === "string"
+        && record.sdk && typeof record.sdk.package === "string" && typeof record.sdk.version === "string" && parseVersion(record.sdk.version) !== undefined
         && record.brief && typeof record.brief.fingerprint === "string" && record.declarationSchema === "isomorph.app-integrations/2.0");
 }
-/** Lines naming every digest that differs between two manifests, for `init --upgrade`. */
+/** Lines naming every version and digest that differs between two manifests, for `init --upgrade`. */
 export function bundleDiff(before, after) {
     const fields = [
         ["kitVersion", before.kitVersion, after.kitVersion],
-        ["sdk.tarballSha256", before.sdk.tarballSha256, after.sdk.tarballSha256],
+        ["sdk.version", before.sdk.version, after.sdk.version],
         ["brief.fingerprint", before.brief.fingerprint, after.brief.fingerprint]
     ];
     return fields.filter(([, a, b]) => a !== b).map(([name, a, b]) => `${name}: ${a ?? "(none)"} -> ${b ?? "(none)"}`);

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

@@ -1,28 +1,28 @@
 export const PUBLISHED_KIT_BUNDLE = {
     "schema": "isomorph.kit-bundle/1.0",
-    "kitVersion": "0.5.1",
+    "kitVersion": "0.7.0",
     "sdk": {
         "package": "@isomorph.ai/app-sdk",
-        "version": "1.2.1",
-        "tarballSha256": "607e3896aa4116d82d0473677d38a68fecd4855a250cd44e038780290c335c67",
-        "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:607e3896aa4116d82d0473677d38a68fecd4855a250cd44e038780290c335c67"
+        "version": "1.2.2",
+        "tarballSha256": "8953bb7eb6846bcddf48fd5407c098a13c8ad2cf249d702c35b5666d5af0ad53",
+        "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:8953bb7eb6846bcddf48fd5407c098a13c8ad2cf249d702c35b5666d5af0ad53"
     },
     "images": {
-        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:558e3aa74f315a8bf2ae18f1344be3b8fad0203286f43d14d411a4a1f3e15dc0",
-        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:578cc8d98ca687dc79d8567f46abc636db2df0b3d8a01ccf38b30d5932c43353"
+        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:3669ac07c51d5160463ba9985dbdca035b6944ae4ebbaea57ea02eeed83fb8ee",
+        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:67650669576642104b03afd97bd1463d507bc9e1e83fb7314693ce7d3bdfe373"
     },
     "nativeRuntime": {
         "darwinArm64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:e36aeea224867ebd7ae4a609284393460f707eaf6c50cb5f8ea1596926bae04b",
-            "sha256": "e36aeea224867ebd7ae4a609284393460f707eaf6c50cb5f8ea1596926bae04b"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:aa7c6b1da2a51c6c3ff98582ed3f34959a8081c6af005961f0d4737da83402cf",
+            "sha256": "aa7c6b1da2a51c6c3ff98582ed3f34959a8081c6af005961f0d4737da83402cf"
         },
         "linuxX64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:0673c75610f7fc8a5f1dbc1ec39570eee2278301430e7bbd4b4323319e7a1e6e",
-            "sha256": "0673c75610f7fc8a5f1dbc1ec39570eee2278301430e7bbd4b4323319e7a1e6e"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:2c20bb1f3ad39917e6514aef77f1588efb433996079d3e844ef2a2cb28fabde4",
+            "sha256": "2c20bb1f3ad39917e6514aef77f1588efb433996079d3e844ef2a2cb28fabde4"
         },
         "windowsX64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:8c1fc2e83d6b4cfd056b5252b9676a32e1e49e0596bb072f2c33faef63781aab",
-            "sha256": "8c1fc2e83d6b4cfd056b5252b9676a32e1e49e0596bb072f2c33faef63781aab"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:892199c64f47d1ade017e2f5c78750f0cad01516fd0bd191490a6b79c1af9ff8",
+            "sha256": "892199c64f47d1ade017e2f5c78750f0cad01516fd0bd191490a6b79c1af9ff8"
         }
     },
     "brief": {

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

@@ -5,30 +5,18 @@ import { basename, dirname, join, parse, resolve } from "node:path";
 import { scanWorkspace } from "../../../src/analyzer.js";
 import { isKitBundle } from "./kit-bundle.js";
 import { CliError } from "./output.js";
-/**
- * Closed set: each operation has one connection kind and the identity modes it
- * may run under — exactly one, except slack.message.post, which the app
- * declares (`app` posts as the company's Slack app under its IT-approved name,
- * `user` posts as the signed-in person after their consent). Gmail is
- * user-mode only (two reads and one send as the signed-in person).
- */
-export const OPERATIONS = {
-    "slack.channel.history": { identities: ["user"], kind: "saas" },
-    "slack.message.post": { identities: ["app", "user"], kind: "saas" },
-    "gmail.thread.list": { identities: ["user"], kind: "saas" },
-    "gmail.message.read": { identities: ["user"], kind: "saas" },
-    "gmail.message.send": { identities: ["user"], kind: "saas" },
-    "warehouse.view.read": { identities: ["app"], kind: "database" }
-};
 /** Explicit reads `isomorph check --integrations` may run; every other operation is a send and never runs during checks. */
 export const READ_OPERATIONS = ["slack.channel.history", "gmail.thread.list", "warehouse.view.read"];
 /** Reads whose input needs an identifier from a prior read (a message id): listed as reads, exercised only through the list. */
 export const DEPENDENT_READ_OPERATIONS = ["gmail.message.read"];
 /**
- * Reads the committed declaration as JSON. The closed rules (schema, connection
- * kinds, the operation set, identity modes, logical resource names) are the
- * kit gate's `declaration` check — the pipeline's own — so a defect is named
- * once, in the same words, by `isomorph check` and by CodeBuild.
+ * Reads the declaration `isomorph check` derived from the app's
+ * `isomorph.integrations.execute` calls and wrote to `.isomorph/integrations.json`
+ * (data plane ADR 0016). Nobody edits the file: its closed rules are the kit
+ * gate's `declaration` check, so a defect is named once, at the call site, by
+ * `isomorph check` and by CodeBuild alike. A missing file is the empty
+ * declaration (`init` writes one); a file that is not JSON is not the gate's
+ * and the fix is to run the check.
  */
 export function emptyDeclaration() { return { schema: "isomorph.app-integrations/2.0", connections: {} }; }
 export function resourceNames(operation) { return Array.isArray(operation.resources) ? operation.resources : Object.keys(operation.resources); }
@@ -42,20 +30,20 @@ export async function readDeclaration(root) {
         raw = await readFile(kitPaths(root).declaration, "utf8");
     }
     catch {
-        return { declaration: emptyDeclaration(), errors: [".isomorph/integrations.json is missing (run `isomorph init`)"] };
+        return emptyDeclaration();
     }
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        return { declaration: emptyDeclaration(), errors: [".isomorph/integrations.json is not valid JSON"] };
+        parsed = undefined;
     }
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-        return { declaration: emptyDeclaration(), errors: [".isomorph/integrations.json must be a JSON object"] };
+        throw new CliError("DECLARATION_UNREADABLE", ".isomorph/integrations.json is not the file `isomorph check` writes.", undefined, "Run `isomorph check --app-root .`: it derives the file from the app's isomorph.integrations.execute calls.");
     const record = parsed;
     const connections = record.connections && typeof record.connections === "object" && !Array.isArray(record.connections) ? record.connections : {};
-    return { declaration: { schema: record.schema, connections }, errors: [] };
+    return { schema: record.schema, connections };
 }
 export function isKitLock(value) {
     const record = value;
@@ -156,7 +144,8 @@ export async function readAppProfile(root) {
         problems.push("audience must be a list of email addresses (an empty list means only you)");
     if (problems.length)
         throw new CliError("APP_PROFILE_INVALID", `.isomorph/app.json is invalid: ${problems.join("; ")}.`, undefined, "Fix the file, then run this again.");
-    return { schema: "isomorph.app/1.0", name: record.name.trim(), description: (record.description ?? "").trim(), audience: record.audience.map(entry => entry.trim()) };
+    const slack = record.slack && typeof record.slack === "object" && typeof record.slack.displayName === "string" ? { slack: { displayName: record.slack.displayName, ...(typeof record.slack.iconEmoji === "string" ? { iconEmoji: record.slack.iconEmoji } : {}) } } : {};
+    return { schema: "isomorph.app/1.0", name: record.name.trim(), description: (record.description ?? "").trim(), audience: record.audience.map(entry => entry.trim()), ...slack };
 }
 /** Stable per-project identity for the kit-managed local state. */
 export function projectName(root, suffix = "") {

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

@@ -2,8 +2,10 @@ import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { copyFile, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { createServer } from "node:net";
-import { dirname, join, relative, win32 } from "node:path";
+import { dirname, join, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
+import { sdkDependencyRange } from "./kit-bundle.js";
+import { parseVersion } from "./config.js";
 import { kitPaths, projectName } from "./kit.js";
 import { CliError } from "./output.js";
 export function nodePackageCommand(tool, args, platform = process.platform, execPath = process.execPath) {
@@ -467,7 +469,7 @@ async function ensureNativeGateway(root, bundle) {
     const directory = join(kitPaths(root).local, "runtime");
     const target = join(directory, `isomorph-app-gateway-${runtime.sha256.slice(0, 12)}${process.platform === "win32" ? ".exe" : ""}`);
     if (!(await exists(target))) {
-        const bytes = await downloadSdk(runtime.url);
+        const bytes = await downloadBundleBlob(runtime.url);
         const digest = createHash("sha256").update(bytes).digest("hex");
         if (digest !== runtime.sha256)
             throw new CliError("KIT_BUNDLE_INCOMPATIBLE", `The native runtime digest ${digest} does not match the kit bundle ${runtime.sha256}.`);
@@ -497,59 +499,61 @@ export function parseSessionEnv(text) {
     }
     return env;
 }
-// ---- SDK tarball ---------------------------------------------------------------------------
+// ---- Dependencies and kit bundle blobs ----------------------------------------------------
 /**
- * The SDK ships in the kit bundle, not the public registry. Stages the tarball
- * named by ISOMORPH_KIT_SDK_TARBALL or downloaded from the manifest's sdk.url under
- * `.isomorph/local/sdk/` (so package.json gets a relative `file:` dependency), checks
- * its sha256 against the bundle and installs it with the app's other dependencies.
- * Returns "present" when the staged tarball is already installed, "missing" when
- * no tarball is available and node_modules lacks the package.
+ * The app's dependencies, `@isomorph.ai/app-sdk` among them, come from the public
+ * npm registry like any package (data plane ADR 0017): one plain `npm install`,
+ * nothing staged or pinned by the kit. One rule for `init`, `dev` and `check`:
+ * install when node_modules lacks the SDK (a fresh init or clone) or holds one
+ * outside the bundle's range (`init --upgrade` moved it); otherwise nothing runs.
  */
-export async function ensureSdk(root, bundle, env, run, output, fetchImpl = fetch) {
-    const installed = await readFile(join(root, "node_modules", ...bundle.sdk.package.split("/"), "package.json")).then(() => true, () => false);
-    const stageDir = join(kitPaths(root).local, "sdk");
-    const staged = join(stageDir, `isomorph-app-sdk-${bundle.sdk.tarballSha256.slice(0, 12)}.tgz`);
-    const source = env.ISOMORPH_KIT_SDK_TARBALL?.trim();
-    if (!(await exists(staged))) {
-        let bytes;
-        if (source)
-            bytes = await readFile(source).catch(() => { throw new CliError("SDK_UNAVAILABLE", `ISOMORPH_KIT_SDK_TARBALL is not readable: ${source}`); });
-        else if (bundle.sdk.url) {
-            output(`Downloading ${bundle.sdk.package} from the kit bundle (sha256 ${bundle.sdk.tarballSha256.slice(0, 12)}…).`);
-            bytes = await downloadSdk(bundle.sdk.url, fetchImpl);
-        }
-        if (!bytes)
-            return installed ? "present" : "missing";
-        const digest = createHash("sha256").update(bytes).digest("hex");
-        if (bundle.sdk.tarballSha256 !== "unknown" && digest !== bundle.sdk.tarballSha256)
-            throw new CliError("KIT_BUNDLE_INCOMPATIBLE", `The SDK tarball digest ${digest} does not match the kit bundle ${bundle.sdk.tarballSha256}. Run \`isomorph init --upgrade\` or use the matching tarball.`);
-        await mkdir(stageDir, { recursive: true });
-        await writeFile(staged, bytes);
-    }
-    else if (installed && (await readFile(join(root, "package.json"), "utf8").catch(() => "")).includes(relative(root, staged)))
+export async function installDependencies(root, bundle, run, output) {
+    if (await sdkInstalled(root, bundle))
         return "present";
-    output(`Installing ${bundle.sdk.package} from the kit bundle.`);
-    const npm = nodePackageCommand("npm", ["install", "--no-audit", "--no-fund", relative(root, staged)]);
+    output(`Installing the app's dependencies, ${bundle.sdk.package} ${sdkDependencyRange(bundle)} among them (npm install).`);
+    const npm = nodePackageCommand("npm", ["install", "--no-audit", "--no-fund"]);
     const result = await run(npm.command, npm.args, { cwd: root, quiet: true });
     if (result.code !== 0)
-        throw new CliError("SDK_INSTALL_FAILED", `npm could not install the kit SDK tarball: ${result.stderr.trim().split("\n").at(-1) ?? "npm error"}`);
+        throw new CliError("NPM_INSTALL_FAILED", `npm install failed: ${result.stderr.trim().split("\n").at(-1) ?? "npm error"}`, undefined, "Fix the dependency problem npm names (package.json, the lockfile or the registry), then run this again.");
     return "installed";
 }
+/** Whether node_modules holds the SDK at a version inside `^<bundle.sdk.version>`: same major (0.x: same minor) and not older. */
+async function sdkInstalled(root, bundle) {
+    const manifest = await readFile(join(root, "node_modules", ...bundle.sdk.package.split("/"), "package.json"), "utf8").catch(() => undefined);
+    if (manifest === undefined)
+        return false;
+    let installed;
+    try {
+        installed = parseVersion(String(JSON.parse(manifest).version ?? ""))?.core;
+    }
+    catch {
+        return false;
+    }
+    const wanted = parseVersion(bundle.sdk.version)?.core;
+    if (!installed || !wanted)
+        return false;
+    if (installed[0] !== wanted[0] || (wanted[0] === 0 && installed[1] !== wanted[1]))
+        return false;
+    for (let index = 0; index < 3; index += 1)
+        if (installed[index] !== wanted[index])
+            return installed[index] > wanted[index];
+    return true;
+}
 /**
- * Fetches the SDK tarball from the bundle's `sdk.url`. The published bundle
- * stores it as a content-addressed OCI blob on a public registry, which answers
- * an anonymous GET with a Bearer challenge naming a token endpoint that hands
- * out pull tokens without credentials; the challenge is followed once and the
- * request repeated. Redirects (a blob served from object storage) are followed;
- * the bearer token is not forwarded across origins by fetch itself. The caller
- * verifies the bytes against `sdk.tarballSha256` — a token or a redirect can
- * change where the bytes come from, never which bytes are accepted.
+ * Fetches one of the kit bundle's blobs — the native runtime binary for this
+ * platform. The published bundle stores it as a content-addressed OCI blob on a
+ * public registry, which answers an anonymous GET with a Bearer challenge naming
+ * a token endpoint that hands out pull tokens without credentials; the challenge
+ * is followed once and the request repeated. Redirects (a blob served from
+ * object storage) are followed; the bearer token is not forwarded across origins
+ * by fetch itself. The caller verifies the bytes against the manifest's sha256 —
+ * a token or a redirect can change where the bytes come from, never which bytes
+ * are accepted.
  */
-export async function downloadSdk(url, fetchImpl = fetch) {
+export async function downloadBundleBlob(url, fetchImpl = fetch) {
     if (!/^https:\/\//.test(url))
-        throw new CliError("SDK_UNAVAILABLE", `The kit bundle's sdk.url must be https: ${url}`);
-    const attempt = (headers = {}) => fetchImpl(url, { redirect: "follow", headers }).catch(error => { throw new CliError("SDK_UNAVAILABLE", `The kit SDK tarball could not be downloaded from ${url}: ${error instanceof Error ? error.message : String(error)}`); });
+        throw new CliError("KIT_RUNTIME_UNAVAILABLE", `The kit bundle's blob URL must be https: ${url}`);
+    const attempt = (headers = {}) => fetchImpl(url, { redirect: "follow", headers }).catch(error => { throw new CliError("KIT_RUNTIME_UNAVAILABLE", `The kit runtime could not be downloaded from ${url}: ${error instanceof Error ? error.message : String(error)}`); });
     let response = await attempt();
     if (response.status === 401) {
         const challenge = parseBearerChallenge(response.headers.get("www-authenticate"));
@@ -567,7 +571,7 @@ export async function downloadSdk(url, fetchImpl = fetch) {
         }
     }
     if (!response.ok)
-        throw new CliError("SDK_UNAVAILABLE", `The kit SDK tarball could not be downloaded from ${url} (HTTP ${response.status}).`);
+        throw new CliError("KIT_RUNTIME_UNAVAILABLE", `The kit runtime could not be downloaded from ${url} (HTTP ${response.status}).`);
     return new Uint8Array(await response.arrayBuffer());
 }
 /** `Bearer realm="…",service="…",scope="…"` (RFC 6750 / distribution token auth); anything else is no challenge. */

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

@@ -1,6 +1,6 @@
 import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { bundleDiff } from "./kit-bundle.js";
+import { bundleDiff, sdkDependencyRange } from "./kit-bundle.js";
 import { agentSetup, MANAGED_END, MANAGED_START, upsertManagedBlock } from "./agent-setup.js";
 import { defaultAppProfile, emptyDeclaration, newKitLock, readKitLock, renderAppProfile, writeKitLock } from "./kit.js";
 import { CliError } from "./output.js";
@@ -80,8 +80,26 @@ export async function initKit(root, bundle, options = {}) {
     }
     else
         result.kept.push(".isomorph/kit.lock.json");
+    // The SDK is a normal dependency of the app's own package.json: added when an
+    // existing app lacks it (adopt), moved to the bundle's range on --upgrade,
+    // otherwise left as the app has it. The CLI runs `npm install` afterwards.
+    if (existingPackage && await ensureSdkDependency(root, existingPackage, bundle, Boolean(options.upgrade)))
+        result.updated.push("package.json");
     return result;
 }
+/** Writes `"<sdk package>": "^<sdk.version>"` into an existing package.json when it is missing, or when `move` is set and it differs; reports whether the file changed. */
+async function ensureSdkDependency(root, pkg, bundle, move) {
+    const { package: name } = bundle.sdk;
+    const range = sdkDependencyRange(bundle);
+    const current = pkg.dependencies?.[name] ?? pkg.devDependencies?.[name];
+    if (current === range || (current !== undefined && !move))
+        return false;
+    if (pkg.devDependencies)
+        delete pkg.devDependencies[name];
+    pkg.dependencies = { ...pkg.dependencies, [name]: range };
+    await writeFile(join(root, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`);
+    return true;
+}
 function isSupportedApp(pkg) {
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     return Boolean(deps.vite && deps.react);
@@ -136,14 +154,11 @@ function kitFiles(root) {
         // Name, description and audience: what `isomorph deploy` prints before it starts and records
         // with the deployment. The folder name and an empty audience are only a starting point.
         ".isomorph/app.json": renderAppProfile(defaultAppProfile(root)),
-        // No connection. The starter calls no company system, and a connection the
-        // app does not call is a deploy that never happens: `isomorph deploy`
-        // 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 steps and the worked Slack and warehouse examples are in integrations.md
-        // beside the `isomorph` skill (guide.ts). They are not in this file: it is read
-        // with JSON.parse here and again by the pipeline's source intake, so it cannot
-        // carry comments.
+        // No connection: the starter calls no company system. The kit gate derives
+        // this file from the app's isomorph.integrations.execute calls on every
+        // `isomorph check` (data plane ADR 0016); it is committed and packaged for
+        // governance, never edited. `init` writes the empty one so a fresh app has
+        // a declaration before its first check.
         ".isomorph/integrations.json": `${JSON.stringify(emptyDeclaration(), null, 2)}\n`
     };
 }
@@ -165,10 +180,9 @@ function starterFiles(bundle) {
         "package.json": `${JSON.stringify({
             name: "isomorph-app", private: true, version: "0.1.0", type: "module",
             scripts: { dev: "vite", build: "tsc --noEmit && vite build", preview: "vite preview" },
-            // The SDK is distributed as a tarball in the kit bundle, not from the public registry:
-            // `isomorph dev` installs it from ISOMORPH_KIT_SDK_TARBALL or the manifest's sdk.url and
-            // verifies its sha256 against .isomorph/kit.lock.json before use.
-            dependencies: { [bundle.sdk.package]: bundle.sdk.version ?? "1.0.0", react: "^18.3.1", "react-dom": "^18.3.1" },
+            // The SDK is a public npm package like the rest: `init` runs `npm install` and
+            // `.isomorph/kit.lock.json` records the bundle's SDK version for the pipeline's floor.
+            dependencies: { [bundle.sdk.package]: sdkDependencyRange(bundle), react: "^18.3.1", "react-dom": "^18.3.1" },
             devDependencies: { "@types/react": "^18.3.12", "@types/react-dom": "^18.3.1", "@vitejs/plugin-react": "^4.3.4", typescript: "^5.6.3", vite: "^5.4.11" }
         }, null, 2)}\n`,
         "tsconfig.json": `${JSON.stringify({ compilerOptions: { target: "ES2022", lib: ["ES2022", "DOM", "DOM.Iterable"], module: "ESNext", moduleResolution: "Bundler", jsx: "react-jsx", strict: true, noEmit: true, skipLibCheck: true, isolatedModules: true }, include: ["src"] }, null, 2)}\n`,
@@ -196,7 +210,7 @@ Created by \`isomorph init\`: a Vite + React app that runs on Isomorph. Sign-in,
 
 The kit's rules are in the \`isomorph\` skill that \`isomorph agent-setup\` installs for Claude Code (\`~/.claude/skills/isomorph/\`) and Codex (\`~/.codex/skills/isomorph/\`): \`core.md\` (identity, data, files, realtime, commands, error codes), \`integrations.md\` (Slack, Gmail, warehouse), \`ai.md\` and \`jobs.md\`. The managed block in CLAUDE.md / AGENTS.md points there.
 
-\`.isomorph/checks/\` is regenerated on each check and gitignored — put your own checks in \`tests/<name>.mjs\`. \`.isomorph/integrations.json\` declares the company systems the app calls: none, to start. \`.isomorph/app.json\` holds the app's name, description and audience.
+\`.isomorph/checks/\` is regenerated on each check and gitignored — put your own checks in \`tests/<name>.mjs\`. \`.isomorph/integrations.json\` is derived by \`isomorph check\` from the app's \`isomorph.integrations.execute\` calls and committed, never edited. \`.isomorph/app.json\` holds the app's name, description and audience.
 `;
 const VITE_CONFIG = `import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/cli",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Isomorph development kit CLI",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
   "harbour": {
     "kitBundle": {
       "repository": "public.ecr.aws/y6t4p3i8/harbour-kit-bundle",
-      "version": "0.5.1"
+      "version": "0.7.0"
     }
   }
 }