@isomorph.ai/cli 0.10.10 → 0.11.1

package/README.md

@@ -28,7 +28,7 @@ The only step you do yourself is the company sign-in: when the agent runs `isomo
 
 ```
 isomorph agent-setup                                        install the `isomorph` skill for Claude Code and Codex; idempotent
-isomorph init --app-root <path> [--adopt] [--upgrade] [--json]   starter app in an empty folder (also runs agent-setup); a folder with an app and no kit is refused with three choices (APP_EXISTS); --adopt adds the kit files to a Vite + React app in place; --upgrade re-pins the kit bundle and runs the checks
+isomorph init --app-root <path> [--adopt] [--upgrade] [--json]   starter app in an empty folder or around data files (also runs agent-setup); a folder with an app and no kit is refused with the choices that can succeed (APP_EXISTS); --adopt adds the kit files to a Vite + React app in place; --upgrade re-pins the kit bundle and runs the checks
 isomorph package --app-root <path> [--out <file>] [--json]  zip an app built without the kit for the console's Upload package (local; .env files included, node_modules/build output/.git left out)
 isomorph dev --app-root <path> [--reset] [--detach] [--json]  run the app locally on one loopback origin; --detach starts it in the background and prints {origin, pid} once it answers
 isomorph stop --app-root <path>                             stop local services, keep data
@@ -47,7 +47,7 @@ isomorph status | retry | promote [--app-root <path>] [--operation <reference>]
 
 `promote` never prompts: `--confirm-tested` is the one flag that means the person has opened the preview and it works. (`productionise`, the command's name until 0.3.4, was accepted as an alias for one release and is no longer a command.)
 
-There are two ways onto Isomorph and `init` is where the folder decides. An empty folder (or one holding only `.git`, a README, a licence or editor and agent files) gets the starter. A folder that already is a kit app (it has `.isomorph/kit.lock.json`) is kept as it is and told its next commands (`dev`, `check`, `deploy`). A folder with an app and no kit is never adopted silently: `init` refuses with exit 2, `APP_EXISTS`, and the three choices — `isomorph init --app-root <dir> --adopt` (add the kit in place; Vite + React only, otherwise `APP_UNSUPPORTED`), `isomorph init --app-root <new-empty-folder>` (start a new kit app), or `isomorph package --app-root <dir>` (package the app as it is for the console import). With `--json` the choices are in `error.details.choices` as `{ id, command, description }`, so an agent relays them and runs the one the person picks. `package` is local (no company, no sign-in): it scans the tree the way `deploy` does, includes the app's `.env` files (the console reads their values into encrypted defaults and never commits the files), refuses private keys and other secret-bearing paths, and writes a deterministic `isomorph-import.zip` (or `--out <file>`) whose result names the path, file count, bytes, sha256 and the one next step: upload it in the console (Add app → Upload package), or connect the repository there instead. A kit app is refused (`KIT_APP`): it deploys with `isomorph deploy`.
+There are two ways onto Isomorph and `init` is where the folder decides. An empty folder (or one holding only `.git`, a README, a licence, `node_modules` or editor and agent files) gets the starter. So does a folder that holds only data — no `package.json`, no `src/`, no index or source file (`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.html`): the starter is created around the files, none is overwritten, and one line names them (`Kept 2 existing files (data.csv, rows.csv); read them from the app.`). A folder that already is a kit app (it has `.isomorph/kit.lock.json`) is kept as it is and told its next commands (`dev`, `check`, `deploy`). A folder with an app and no kit is never adopted silently: `init` refuses with exit 2, `APP_EXISTS`, and the choices that can succeed, in order — `isomorph init --app-root <dir> --adopt` (add the kit in place; offered only when `package.json` depends on vite and react, otherwise `APP_UNSUPPORTED`), `isomorph init --app-root <new-empty-folder>` (start a new kit app), then `isomorph package --app-root <dir>` (package the app as it is for the console import). With `--json` the choices are in `error.details.choices` as `{ id, command, description }`, so an agent relays them and runs the one the person picks. `package` is local (no company, no sign-in): it scans the tree the way `deploy` does, includes the app's `.env` files (the console reads their values into encrypted defaults and never commits the files), refuses private keys and other secret-bearing paths, and writes a deterministic `isomorph-import.zip` (or `--out <file>`) whose result names the path, file count, bytes, sha256 and the one next step: upload it in the console (Add app → Upload package), or connect the repository there instead. A kit app is refused (`KIT_APP`): it deploys with `isomorph deploy`.
 
 `isomorph --help` prints the full usage. Local commands need no company sign-in; integrations and shipping do.
 

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

@@ -108,7 +108,7 @@ Rules live beside this file: \`core.md\` before the first edit; \`integrations.m
 
 ## Getting ready
 
-- No \`.isomorph/\` yet: \`isomorph init --app-root .\` (empty folder → starter; an existing app → three choices to relay). Node 22+, no Docker. Then write the app's \`name\` and \`description\` into \`.isomorph/app.json\` from what they asked and tell them both: IT sees the app under exactly these, once, on its first approval.
+- No \`.isomorph/\` yet: \`isomorph init --app-root .\` (an existing app: relay its choices and ask; never run \`package\` unasked). Node 22+, no Docker. The starter is a notes-and-files placeholder: before the first \`dev\`, replace \`src/App.tsx\`, \`index.html\`'s title and \`migrations/0001_notes.sql\` with what they asked, and say so in one line (applied migrations freeze after the first deploy). Then propose a \`name\` and one-sentence \`description\` from the request, write them into \`.isomorph/app.json\`, and show both in your next reply asking for corrections: IT sees the app under exactly these, once, on its first approval.
 - Sign-in, only when a command answers \`CONFIG_REQUIRED\` or \`AUTH_REQUIRED\` (most machines already are): \`isomorph connect <work-email>\`, then \`isomorph login\` — the browser opens and the person finishes there (their one step; say so).
 
 ## Intent → command
@@ -120,7 +120,7 @@ Rules live beside this file: \`core.md\` before the first edit; \`integrations.m
 | "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: catalog, write the call (literals only), \`isomorph check\`, then submit the request; 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\` and \`result.consoleUrl\` (its live checks). \`--session-notes\`: what cost you time in Isomorph, or \`""\`. |
+| "ship it", "let my team try it" | show the person the three values in \`.isomorph/app.json\` (name, description, audience — "only you" when empty), ask who else should be able to open it (colleagues' work emails only; no groups or whole company yet) 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). To give someone access later: add their email to \`audience\`, then \`isomorph share --app-root . --json\`, never \`deploy\`. Give them \`result.deployment.protectedUrl\` as "your app, a private preview — open it and try it" and \`result.consoleUrl\` as "the Isomorph console page for this deployment: its checks and status". If \`result.ai\` is present, relay it in one line. \`--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. |
 | "stop it" | \`isomorph stop --app-root .\` (data kept); \`isomorph dev --app-root . --reset\` only when they ask to start over. |
 | "every day at 2pm", "send this automatically" | read \`jobs.md\` beside this skill first (follow its in-conversation owner approval steps); write the job, run it once with \`isomorph jobs run\`, and report what was verified. |

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

@@ -5,6 +5,15 @@ import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import { spawn } from "node:child_process";
 export const requestedOAuthScopes = "mcp";
+/**
+ * The loopback ports the company sign-in returns to. Cognito matches redirect
+ * URIs exactly and allows plain http only on loopback, so the port cannot be
+ * random: the platform registers exactly `http://127.0.0.1:<port>/callback`
+ * for these two on every company's client (the second is for a second
+ * `isomorph login` on the same machine). `ISOMORPH_LOGIN_PORT` names one other
+ * port, for an operator who registered it.
+ */
+export const CLI_LOGIN_PORTS = [47821, 47822];
 export function tokenStorePath(env = process.env) {
     return join(env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config"), "isomorph", "tokens.json");
 }
@@ -52,7 +61,10 @@ export async function clearStoredToken(mcpUrl, tenant, path = tokenStorePath())
         await rm(path, { force: true });
     return token;
 }
-export async function login(mcpUrl, tenant, output) {
+export async function login(mcpUrl, tenant, output, options = {}) {
+    if (options.login)
+        return cognitoLogin(mcpUrl, tenant, output, options.login, options);
+    const open = options.open ?? openBrowser;
     const metadata = await discover(mcpUrl);
     if (!metadata.registration_endpoint || !metadata.authorization_endpoint || !metadata.token_endpoint)
         throw new Error("Isomorph sign-in is not available on this endpoint yet.");
@@ -67,17 +79,52 @@ export async function login(mcpUrl, tenant, output) {
         const authorize = new URL(metadata.authorization_endpoint);
         authorize.search = new URLSearchParams({ response_type: "code", client_id: registered.client_id, redirect_uri: callback.redirectUri, scope: requestedOAuthScopes, state, resource: mcpUrl, code_challenge: challenge, code_challenge_method: "S256" }).toString();
         output("Isomorph is opening your browser to sign in.");
-        openBrowser(authorize.toString());
+        open(authorize.toString());
         output(`If it does not open, visit: ${authorize}`);
         const code = await callback.wait(state);
         const response = await token(metadata.token_endpoint, { grant_type: "authorization_code", client_id: registered.client_id, code, redirect_uri: callback.redirectUri, code_verifier: verifier });
-        await saveStoredToken(mcpUrl, tenant, { ...response, clientId: registered.client_id, tokenEndpoint: metadata.token_endpoint, ...(metadata.revocation_endpoint ? { revocationEndpoint: metadata.revocation_endpoint } : {}) });
+        await saveStoredToken(mcpUrl, tenant, { accessToken: response.accessToken, ...(response.refreshToken ? { refreshToken: response.refreshToken } : {}), ...(response.accessTokenExpiresAt ? { accessTokenExpiresAt: response.accessTokenExpiresAt } : {}), clientId: registered.client_id, tokenEndpoint: metadata.token_endpoint, ...(metadata.revocation_endpoint ? { revocationEndpoint: metadata.revocation_endpoint } : {}) }, options.path);
         output("Isomorph sign-in is complete.");
     }
     finally {
         callback.close();
     }
 }
+/**
+ * Sign-in to the company's own Cognito client, as the console does: the
+ * authorization-code + PKCE flow against the profile's endpoints, no dynamic
+ * registration, and the ID token kept as the bearer. Every governance route
+ * the CLI calls accepts it, including the maker routes the console uses
+ * (`share`), which the adapter's opaque token never reached.
+ */
+async function cognitoLogin(mcpUrl, tenant, output, login, options) {
+    const open = options.open ?? openBrowser;
+    const callback = await loopbackCallback(loginPorts(options.env ?? process.env));
+    try {
+        const verifier = randomBytes(32).toString("base64url");
+        const state = randomBytes(24).toString("base64url");
+        const challenge = createHash("sha256").update(verifier).digest("base64url");
+        const authorize = new URL(login.authorizationEndpoint);
+        authorize.search = new URLSearchParams({ response_type: "code", client_id: login.clientId, redirect_uri: callback.redirectUri, scope: login.scope, state, code_challenge: challenge, code_challenge_method: "S256" }).toString();
+        output("Isomorph is opening your browser to sign in.");
+        open(authorize.toString());
+        output(`If it does not open, visit: ${authorize}`);
+        const code = await callback.wait(state);
+        const response = await token(login.tokenEndpoint, { grant_type: "authorization_code", client_id: login.clientId, code, redirect_uri: callback.redirectUri, code_verifier: verifier });
+        if (!response.idToken)
+            throw new Error("Isomorph sign-in did not return an identity token.");
+        await saveStoredToken(mcpUrl, tenant, { kind: "cognito", accessToken: response.idToken, ...(response.refreshToken ? { refreshToken: response.refreshToken } : {}), ...(response.accessTokenExpiresAt ? { accessTokenExpiresAt: response.accessTokenExpiresAt } : {}), clientId: login.clientId, tokenEndpoint: login.tokenEndpoint, revocationEndpoint: `${new URL(login.tokenEndpoint).origin}/oauth2/revoke` }, options.path);
+        output("Isomorph sign-in is complete.");
+    }
+    finally {
+        callback.close();
+    }
+}
+/** The ports to try, in order: the operator's one, or the two the platform registers. */
+function loginPorts(env) {
+    const override = Number(env.ISOMORPH_LOGIN_PORT?.trim() || "");
+    return Number.isInteger(override) && override > 0 && override < 65_536 ? [override] : CLI_LOGIN_PORTS;
+}
 /**
  * The account this device is already signed in as, or undefined: a stored
  * token that still answers the userinfo endpoint. `login` stops here instead
@@ -107,8 +154,12 @@ export async function refreshStoredToken(mcpUrl, tenant, path = tokenStorePath()
         return stored.accessToken;
     try {
         const refreshed = await token(stored.tokenEndpoint, { grant_type: "refresh_token", client_id: stored.clientId, refresh_token: stored.refreshToken });
-        await saveStoredToken(mcpUrl, tenant, { ...stored, ...refreshed, refreshToken: refreshed.refreshToken ?? stored.refreshToken }, path);
-        return refreshed.accessToken;
+        // Cognito answers a refresh with a new ID token and access token and no refresh token: the stored one stays.
+        const bearer = stored.kind === "cognito" ? refreshed.idToken : refreshed.accessToken;
+        if (!bearer)
+            throw new Error("Isomorph sign-in did not return an identity token.");
+        await saveStoredToken(mcpUrl, tenant, { ...stored, accessToken: bearer, refreshToken: refreshed.refreshToken ?? stored.refreshToken, ...(refreshed.accessTokenExpiresAt ? { accessTokenExpiresAt: refreshed.accessTokenExpiresAt } : {}) }, path);
+        return bearer;
     }
     catch {
         const rotated = await loadStoredToken(mcpUrl, tenant, path);
@@ -126,6 +177,16 @@ export async function logout(mcpUrl, tenant, path = tokenStorePath()) {
     const stored = await clearStoredToken(mcpUrl, tenant, path);
     if (!stored?.revocationEndpoint)
         return;
+    if (stored.kind === "cognito") {
+        // Cognito's revoke takes the refresh token only (and revokes what was minted from it); the ID token expires on its own within the hour.
+        if (!stored.refreshToken)
+            return;
+        try {
+            await fetch(stored.revocationEndpoint, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ token: stored.refreshToken, client_id: stored.clientId }), redirect: "error" });
+        }
+        catch { /* as below */ }
+        return;
+    }
     for (const [token, hint] of [[stored.refreshToken, "refresh_token"], [stored.accessToken, "access_token"]]) {
         if (!token)
             continue;
@@ -135,11 +196,21 @@ export async function logout(mcpUrl, tenant, path = tokenStorePath()) {
         catch { /* Local credentials are removed even if offline revocation cannot complete. */ }
     }
 }
-/** Email of the signed-in company account, from the OAuth userinfo endpoint beside the token endpoint; undefined when unavailable. */
+/**
+ * Email of the signed-in company account; undefined when unavailable. A Cognito
+ * record carries it in the ID token itself, read locally (Cognito's userinfo
+ * wants the access token, which is not kept; the server verifies the signature
+ * on every request, so the CLI only needs the label). An adapter record asks
+ * the OAuth userinfo endpoint beside the token endpoint.
+ */
 export async function connectedAccount(mcpUrl, tenant, accessToken, path = tokenStorePath()) {
     const stored = await loadStoredToken(mcpUrl, tenant, path);
     if (!stored)
         return undefined;
+    if (stored.kind === "cognito") {
+        const claims = idTokenClaims(accessToken);
+        return typeof claims?.email === "string" && typeof claims.exp === "number" && claims.exp * 1_000 > Date.now() ? claims.email : undefined;
+    }
     try {
         const response = await fetch(stored.tokenEndpoint.replace(/\/token$/, "/userinfo"), { headers: { authorization: `Bearer ${accessToken}` }, redirect: "error" });
         const body = response.ok ? await response.json() : {};
@@ -162,18 +233,48 @@ async function discover(mcpUrl) {
         throw new Error("Isomorph sign-in metadata is incomplete.");
     return { authorization_endpoint: metadata.authorization_endpoint, token_endpoint: metadata.token_endpoint, registration_endpoint: metadata.registration_endpoint, revocation_endpoint: metadata.revocation_endpoint ?? "" };
 }
+/** The payload of a JWT, decoded without verification; undefined for anything that is not one. */
+function idTokenClaims(token) {
+    try {
+        const payload = token.split(".")[1];
+        const claims = payload ? JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) : undefined;
+        return claims && typeof claims === "object" && !Array.isArray(claims) ? claims : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function token(endpoint, values) {
     const response = await json(endpoint, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams(values), redirect: "error" });
     if (!response.access_token)
         throw new Error("Isomorph sign-in did not return an access token.");
-    return { accessToken: response.access_token, ...(response.refresh_token ? { refreshToken: response.refresh_token } : {}), ...(typeof response.expires_in === "number" && response.expires_in > 0 ? { accessTokenExpiresAt: Date.now() + response.expires_in * 1_000 } : {}) };
+    return { accessToken: response.access_token, ...(response.id_token ? { idToken: response.id_token } : {}), ...(response.refresh_token ? { refreshToken: response.refresh_token } : {}), ...(typeof response.expires_in === "number" && response.expires_in > 0 ? { accessTokenExpiresAt: Date.now() + response.expires_in * 1_000 } : {}) };
 }
 async function json(url, init) { const response = await fetch(url, { ...init, redirect: "error" }); if (!response.ok)
     throw new Error(`Isomorph sign-in request failed (${response.status}).`); return response.json(); }
 export function authorizationServerMetadataUrl(server) { return `${server.replace(/\/$/, "")}/.well-known/oauth-authorization-server`; }
-function validToken(value) { return Boolean(value && typeof value === "object" && typeof value.accessToken === "string" && typeof value.clientId === "string" && typeof value.tokenEndpoint === "string"); }
+function validToken(value) { return Boolean(value && typeof value === "object" && typeof value.accessToken === "string" && typeof value.clientId === "string" && typeof value.tokenEndpoint === "string" && (value.kind === undefined || value.kind === "cognito")); }
 function isMissing(error) { return Boolean(error && typeof error === "object" && error.code === "ENOENT"); }
-function loopbackCallback() {
+/**
+ * The local page the sign-in returns to. With `ports`, the first of them that is
+ * free is bound (the company client registers exactly those); with none, any
+ * free port (the adapter registers the CLI's redirect per sign-in).
+ */
+async function loopbackCallback(ports) {
+    if (!ports)
+        return listenCallback(0);
+    for (const port of ports) {
+        try {
+            return await listenCallback(port);
+        }
+        catch (error) {
+            if (error.code !== "EADDRINUSE")
+                throw error;
+        }
+    }
+    throw new Error(`Isomorph could not start local sign-in: ${ports.length > 1 ? `ports ${ports.join(" and ")} are both` : `port ${ports[0]} is`} in use. Another \`isomorph login\` may be running; finish or stop it, or set ISOMORPH_LOGIN_PORT to a port your Isomorph admin registered.`);
+}
+function listenCallback(port) {
     return new Promise((resolve, reject) => {
         const server = createServer();
         const timer = setTimeout(() => { server.close(); reject(new Error("Isomorph sign-in timed out. Run `isomorph login` again.")); }, 5 * 60_000);
@@ -186,7 +287,7 @@ function loopbackCallback() {
             if (code && state)
                 server.callback = { code, state };
         });
-        server.listen(0, "127.0.0.1", () => {
+        server.listen(port, "127.0.0.1", () => {
             const address = server.address();
             if (!address || typeof address === "string") {
                 reject(new Error("Isomorph could not start local sign-in."));
@@ -200,7 +301,7 @@ function loopbackCallback() {
                         done(callback.code); }, 25);
                 }), close: () => { clearTimeout(timer); server.close(); } });
         });
-        server.on("error", reject);
+        server.on("error", error => { clearTimeout(timer); reject(error); });
     });
 }
 export function openBrowser(url) { const command = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open"; const args = platform() === "win32" ? ["/c", "start", "", url] : [url]; const child = spawn(command, args, { detached: true, stdio: "ignore" }); child.unref(); child.on("error", () => { }); }

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

@@ -57,6 +57,13 @@ export async function runChecks(root, options) {
     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);
+    // A green ai journey reads as "AI works here" unless it is said what answered
+    // it (a builder was told the check "simulated the AI reply" and could not
+    // tell whether AI was integrated, 2026-09-26). The gate's own detail names
+    // the canned reply; this is the one plain line that says what that means.
+    const ai = gate.checks.some(cannedAi) ? "canned" : "not tested";
+    if (ai === "canned")
+        output(AI_CANNED_LINE);
     let integrations = "not tested";
     if (options.governance) {
         // Reads that could not run are one check the report carries as not_run with
@@ -96,12 +103,16 @@ export async function runChecks(root, options) {
         checks,
         gate,
         integrations,
-        ai: "not tested",
+        ai,
         passed: checks.every(check => check.status !== "fail") && (integrations === "not tested" || integrations.every(item => item.status !== "fail"))
     };
     await writeFile(kitPaths(root).report, `${JSON.stringify(report, null, 2)}\n`).catch(() => undefined);
     return report;
 }
+/** What the check's canned AI reply means, in the builder's terms, printed once after the gate. */
+export const AI_CANNED_LINE = "AI in this check: answered by a canned reply (call shape checked, not a real model). Real AI runs when you use the app from `isomorph dev` or the preview link.";
+/** The gate's own wording for a journey whose governed AI call the canned fixture answered (data plane kit_gate.go `fixtureAnsweredDetail`). */
+const cannedAi = (check) => check.name.startsWith("journey:") && check.status === "pass" && (check.detail ?? "").includes("governed AI was answered by the gate's canned completion");
 function renderCheck(check) {
     const mark = check.status === "pass" ? "ok  " : check.status === "fail" ? "FAIL" : "skip";
     return `${mark} ${check.name}${check.detail ? ` — ${indentLines(check.detail)}` : ""}`;

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

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-import { appCallsAi, deploy, readDeployNote } from "./deploy.js";
+import { appCallsAi, deploy, describeAi, readDeployNote } from "./deploy.js";
 import { continueCommand, follow, promoteToProduction, retryDeployment, statusFetch, summarize } from "./operations.js";
 import { CliError, failureEnvelope, operationEnvelope, renderFailure, renderSummary } from "./output.js";
 import { CLI_VERSION } from "./version.js";
-import { alreadySignedIn, connectedAccount, login, logout, openBrowser, refreshStoredToken } from "./auth.js";
+import { alreadySignedIn, connectedAccount, loadStoredToken, login, logout, openBrowser, refreshStoredToken } from "./auth.js";
 import { assertCliCurrent, CLI_INSTALL_COMMAND, cliStaleness, companyLabel, connect, loadConfig, resolveConfig } from "./config.js";
 import { EMBEDDED_KIT_BUNDLE } from "./kit-bundle.js";
 import { appRoot, assertLockCompany, readAppProfile, readKitLock, requestResourceName } from "./kit.js";
-import { initKit } from "./starter.js";
+import { initKit, keptDataLine } from "./starter.js";
 import { packageApp } from "./package.js";
 import { agentPaths, agentSetup } from "./agent-setup.js";
 import { detachDev, startDev } from "./dev.js";
@@ -15,6 +15,7 @@ import { endProcess, installDependencies, LocalRuntime, readDevLock, releaseDevL
 import { CHECKS_FAILED_HINT, checksFailedMessage, runChecks } from "./check.js";
 import { connectIntegration, assertDeployReady, companySystemsLine, GovernanceClient, groupGrants, IDENTITY_WORDS, integrationsCatalog, integrationsStatus, renderGrantGroup, renderIntegrationsCatalog, requestIntegrations } from "./integrations.js";
 import { runJob } from "./jobs.js";
+import { renderShare, shareApp } from "./share.js";
 const args = process.argv.slice(2);
 // `productionise` (the command's name until 0.3.4) was an alias of `deploy` for one release; it is no longer a command and falls through to the usage error.
 const command = args[0];
@@ -32,7 +33,7 @@ const reset = args.includes("--reset");
 /** `dev --detach`: start the services, print the origin, exit while they keep running. */
 const detach = args.includes("--detach");
 const upgrade = args.includes("--upgrade");
-/** `init --adopt`: add the kit to the app already in the folder (Vite + React only). Without it a folder with an app and no kit is refused with its three choices. */
+/** `init --adopt`: add the kit to the app already in the folder (Vite + React only). Without it a folder with an app and no kit is refused with its choices. */
 const adopt = args.includes("--adopt");
 /** `package --out`: where the console import package is written (default `<app-root>/isomorph-import.zip`). */
 const out = optionValue("--out");
@@ -56,12 +57,13 @@ const usage = [
     "  isomorph connect <work-email | company-start-url>",
     "  isomorph login | logout",
     "  isomorph agent-setup [--json]                               install the plain-English Isomorph skill for Claude Code (~/.claude/skills/isomorph) and Codex (~/.codex/skills/isomorph)",
-    "  isomorph init --app-root <path> [--adopt] [--upgrade] [--json]   create the starter in an empty folder (also runs agent-setup); a folder with an app and no kit is refused with three choices; --adopt adds the kit files to a Vite + React app in place; --upgrade re-pins the kit bundle and runs the checks",
+    "  isomorph init --app-root <path> [--adopt] [--upgrade] [--json]   create the starter in an empty folder, or around data files (CSVs and the like are kept and named; also runs agent-setup); a folder with an app (package.json or source files) and no kit is refused with the choices that can succeed; --adopt adds the kit files to a Vite + React app in place; --upgrade re-pins the kit bundle and runs the checks",
     "  isomorph package --app-root <path> [--out <file>] [--json]  zip an app built without the kit for the Isomorph console's Upload package (local, no sign-in; .env files included, node_modules/build output/.git left out; kit apps use deploy)",
     "  isomorph dev --app-root <path> [--reset] [--detach] [--json]  run the app locally on one loopback origin (--reset deletes this app's local data; --detach starts it in the background and prints the origin and pid once it answers)",
     "  isomorph stop --app-root <path>                             stop this app's local services, keeping its database and files",
     "  isomorph 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)",
     "  isomorph deploy --app-root <path> [--session-notes <text>] [--no-wait] [--max-wait <seconds>] [--json]   deploy the private preview: name, description and audience come from .isomorph/app.json (--no-wait returns once Isomorph has the package, with the command that follows it)",
+    "  isomorph share --app-root <path> [--json]                   give the audience in .isomorph/app.json access to the deployed preview without a new release (deploy carries the audience too; share is for an audience-only change)",
     "  isomorph status [--app-root <path>] [--operation <reference>] [--wait] [--max-wait <seconds>] [--json]   (--app-root defaults to the current folder; --operation to the deployment last started from it)",
     "  isomorph retry [--app-root <path>] [--operation <reference>] [--no-wait] [--max-wait <seconds>] [--json]",
     "  isomorph promote [--app-root <path>] [--operation <reference>] [--confirm-tested] [--no-wait] [--max-wait <seconds>] [--json]   (--confirm-tested: the person has tried the preview; the company's AI setup is confirmed for production when the app calls governed AI)",
@@ -91,7 +93,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", "KIT_BUNDLE_STALE", "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", "INDIVIDUAL_SHARING_DISABLED", "EXTERNAL_EMAIL_NOT_ALLOWED", "INVALID_SHARE_EMAILS"];
 if (command === "--version" || command === "version") {
     process.stdout.write(`${CLI_VERSION}\n`);
     // `-h` was matched anywhere in argv while `--help` was only recognised as the
@@ -112,10 +114,10 @@ else if (command === "agent-setup") {
     progress("Claude Code and Codex: the `isomorph` skill is installed. Each agent uses it only for an Isomorph app (a folder with .isomorph/, or an app you ask it to build) and works as usual everywhere else. Say what you want to build; the agent installs and runs the kit itself.");
     emit(summaryEnvelope({ ...result, paths: agentPaths(process.env) }));
 }
-else if (!["connect", "login", "logout", "deploy", "integrations", ...LOCAL_COMMANDS, ...OPERATION_COMMANDS].includes(command)
+else if (!["connect", "login", "logout", "deploy", "share", "integrations", ...LOCAL_COMMANDS, ...OPERATION_COMMANDS].includes(command)
     || (command === "connect" && (!connectUrl || connectUrl.startsWith("--")))
     || (["deploy", "integrations", ...OPERATION_COMMANDS].includes(command) && optionError)
-    || (command === "deploy" && !root)
+    || ((command === "deploy" || command === "share") && !root)
     || (LOCAL_COMMANDS.includes(command) && !root)
     || (command === "jobs" && (subcommand !== "run" || !args[2] || args[2].startsWith("--")))
     || (command === "integrations" && (!root || !subcommand || !["request", "status", "catalog", "connect"].includes(subcommand) || (["request", "connect"].includes(subcommand) && (!args[2] || args[2].startsWith("--")))))) {
@@ -148,7 +150,9 @@ else {
                     progress(line);
                 // 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."
+                if (result.dataFiles.length)
+                    progress(keptDataLine(result.dataFiles));
+                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. The starter page is a placeholder for the app you asked for."
                     : 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}\`.`
                             : "Kit files added; existing files were kept.");
@@ -228,9 +232,14 @@ else {
                 // every unattended builder five minutes (auth.ts loopbackCallback), and
                 // when the sign-in could not complete, agents escalated to `logout`
                 // — which signs the whole machine out (bench, 2026-09-16).
-                const already = await alreadySignedIn(url, tenant);
+                // A device still holding the adapter's token for a company that now
+                // signs the CLI in through its own Cognito client (0.11.0) re-signs:
+                // that token cannot open the console's routes (`share`), and "already
+                // signed in" would send the agent to `logout` to switch.
+                const stale = Boolean(config.login) && (await loadStoredToken(url, tenant))?.kind !== "cognito";
+                const already = stale ? undefined : await alreadySignedIn(url, tenant);
                 if (!already)
-                    await login(url, tenant, progress);
+                    await login(url, tenant, progress, { ...(config.login ? { login: config.login } : {}) });
                 else
                     progress(`Already signed in to ${companyLabel(config)} as ${already}; nothing to do. Run \`isomorph logout\` first to sign in as someone else.`);
                 const signedIn = await signedInDetails(config);
@@ -248,7 +257,15 @@ else {
                 // The client re-resolves per request so a token rotated by a sibling process mid-poll is picked up.
                 const governance = new GovernanceClient(config.apiUrl, resolveToken, tenant);
                 let envelope;
-                if (command === "integrations") {
+                /** The human form, for a command whose result is a sentence rather than a summary. */
+                let line;
+                if (command === "share") {
+                    // An explicit ISOMORPH_TOKEN is the operator's to vouch for; a stored record must be the company sign-in.
+                    const shared = await shareApp(appRoot(root), governance, tenant, EMBEDDED_KIT_BUNDLE, explicitToken ? undefined : (await loadStoredToken(url, tenant)) ?? {});
+                    envelope = summaryEnvelope(shared.outcome);
+                    line = renderShare(shared.audience);
+                }
+                else if (command === "integrations") {
                     const target = appRoot(root);
                     const result = subcommand === "connect"
                         ? await connectIntegration(target, governance, args[2], optionValue("--return-url"))
@@ -283,19 +300,23 @@ else {
                     if (!ref)
                         throw new CliError("OPERATION_REQUIRED", "No deployment has been started from this folder yet.", undefined, "Run `isomorph deploy --app-root .`, or pass --operation <reference>.");
                     let summary;
+                    let ai;
                     if (command === "status")
                         summary = wait ? await follow(statusFetch(governance, appId, ref), ref, progress, waitOptions) : summarize(await governance.deploymentStatus(appId, ref));
                     else if (command === "retry")
                         summary = await retryDeployment(governance, appId, ref, progress, { wait: !noWait, waitOptions });
                     else {
                         // Production has its own lane and its own AI mode: the same one-call pre-flight runs for production before promoting.
-                        await assertDeployReady(target, governance, tenant, EMBEDDED_KIT_BUNDLE, "production", progress, await appCallsAi(target));
+                        const callsAi = await appCallsAi(target);
+                        await assertDeployReady(target, governance, tenant, EMBEDDED_KIT_BUNDLE, "production", progress, callsAi);
+                        if (callsAi)
+                            ai = await describeAi(governance, appId, "production", progress);
                         const profile = await readAppProfile(target);
                         summary = await promoteToProduction(governance, appId, ref, { name: profile.name, description: profile.description, audience: profile.audience }, progress, { wait: !noWait, waitOptions, confirmedTested: confirmTested });
                     }
-                    envelope = operationEnvelope(summary, ref, CLI_VERSION);
+                    envelope = operationEnvelope({ ...summary, ...(ai ? { ai } : {}) }, ref, CLI_VERSION);
                 }
-                process.stdout.write(json ? `${JSON.stringify(envelope)}\n` : renderSummary(envelope));
+                emit(envelope, line);
             }
         }
     }

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

@@ -121,6 +121,7 @@ export async function connect(startUrl, path = configPath(), fetchImpl = fetch)
     if (body.schema !== "harbour.tenant-start/1.0")
         throw new Error("This is not an Isomorph connection profile.");
     const minimum = minimumCliVersion(body);
+    const login = tenantLogin(body);
     const config = {
         schema: "isomorph.cli-config/1.0",
         tenantId: String(body.tenantId ?? ""),
@@ -128,7 +129,8 @@ export async function connect(startUrl, path = configPath(), fetchImpl = fetch)
         mcpUrl: String(body.mcpUrl ?? ""),
         ...(typeof body.uploadUrl === "string" ? { uploadUrl: body.uploadUrl } : {}),
         ...(typeof body.apiUrl === "string" ? { apiUrl: body.apiUrl } : {}),
-        ...(minimum ? { minimumCliVersion: minimum } : {})
+        ...(minimum ? { minimumCliVersion: minimum } : {}),
+        ...(login ? { login } : {})
     };
     if (!validConfig(config))
         throw new Error("This is not the expected Isomorph connection profile.");
@@ -140,6 +142,20 @@ function minimumCliVersion(body) {
     const kit = isRecord(body.kit) ? body.kit : undefined;
     return typeof kit?.minimumCliVersion === "string" && kit.minimumCliVersion.trim() ? kit.minimumCliVersion.trim() : undefined;
 }
+/** The `login` block of a tenant-start profile, verbatim; undefined when absent or incomplete (the adapter path stands then). */
+function tenantLogin(body) {
+    const login = body.login;
+    if (!validLogin(login))
+        return undefined;
+    return { clientId: login.clientId, authorizationEndpoint: login.authorizationEndpoint, tokenEndpoint: login.tokenEndpoint, ...(typeof login.issuer === "string" ? { issuer: login.issuer } : {}), scope: login.scope };
+}
+function validLogin(value) {
+    return isRecord(value) && typeof value.clientId === "string" && value.clientId.length > 0
+        && typeof value.authorizationEndpoint === "string" && /^https?:\/\//.test(value.authorizationEndpoint)
+        && typeof value.tokenEndpoint === "string" && /^https?:\/\//.test(value.tokenEndpoint)
+        && (value.issuer === undefined || typeof value.issuer === "string")
+        && typeof value.scope === "string" && value.scope.length > 0;
+}
 function platformOrigin() {
     return process.env.ISOMORPH_PLATFORM_URL?.trim() || "https://platform.isomorph.ai";
 }
@@ -179,7 +195,7 @@ export function resolveConfig(env, saved) {
     if (!mcpUrl || !tenantId)
         return undefined;
     // The saved name belongs to the saved tenant; an ISOMORPH_TENANT override names another company.
-    return { schema: "isomorph.cli-config/1.0", tenantId, ...(saved?.displayName && tenantId === saved.tenantId ? { displayName: saved.displayName } : {}), mcpUrl, ...(saved?.uploadUrl ? { uploadUrl: saved.uploadUrl } : {}), apiUrl: env.ISOMORPH_API_URL?.trim() || saved?.apiUrl || apiUrlFromMcpUrl(mcpUrl), ...(saved?.minimumCliVersion && tenantId === saved.tenantId ? { minimumCliVersion: saved.minimumCliVersion } : {}) };
+    return { schema: "isomorph.cli-config/1.0", tenantId, ...(saved?.displayName && tenantId === saved.tenantId ? { displayName: saved.displayName } : {}), mcpUrl, ...(saved?.uploadUrl ? { uploadUrl: saved.uploadUrl } : {}), apiUrl: env.ISOMORPH_API_URL?.trim() || saved?.apiUrl || apiUrlFromMcpUrl(mcpUrl), ...(saved?.minimumCliVersion && tenantId === saved.tenantId ? { minimumCliVersion: saved.minimumCliVersion } : {}), ...(saved?.login && tenantId === saved.tenantId ? { login: saved.login } : {}) };
 }
 /** The company as the CLI names it: `Fourier (fourier)`, or the id twice when the profile carried no name. */
 export function companyLabel(config) {
@@ -202,7 +218,8 @@ function validConfig(value) {
         && /^https?:\/\//.test(value.mcpUrl)
         && (value.uploadUrl === undefined || typeof value.uploadUrl === "string")
         && (value.apiUrl === undefined || (typeof value.apiUrl === "string" && /^https?:\/\//.test(value.apiUrl)))
-        && (value.minimumCliVersion === undefined || typeof value.minimumCliVersion === "string"));
+        && (value.minimumCliVersion === undefined || typeof value.minimumCliVersion === "string")
+        && (value.login === undefined || validLogin(value.login)));
 }
 function isRecord(value) {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));

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

@@ -124,15 +124,22 @@ async function runDeploy(rootArg, governance, output, tenantId, options) {
         throw error;
     }
     const { operationRef } = opened;
+    // The preflight passed, so a company whose AI setup is not ready has already
+    // been refused; what the builder never heard is the affirmative. Said once, here.
+    const ai = body.callsAi ? await describeAi(governance, appId, "preview", output) : undefined;
     await writeDeployNote(root, { schema: "isomorph.deploy-note/1.0", tenantId, operationRef, sha256: archive.digest });
     if (opened.resumed && note?.sha256 !== archive.digest)
         output(`Isomorph is continuing operation ${operationRef}; no new deployment was started.`);
     output(`Isomorph operation saved. Continue with ${continueCommand(operationRef)}.`);
     // Everything Isomorph checks, fixes and provisions for this version is shown
-    // live in the console; the builder is sent there the moment it starts.
+    // live in the console. The browser is opened only on the app's first deploy
+    // from this folder for this company (no deploy note yet): in an agent's
+    // build loop nearly every deploy is a new operation — any edit, even a re-run
+    // of `check`, changes the package digest — and a tab per operation left a
+    // builder with four in one day. Later deploys print the link only.
     const consoleUrl = consoleOperationUrl(tenantId, appId, operationRef);
     output(`Watch Isomorph check, secure and deploy this app: ${consoleUrl}`);
-    if (!opened.resumed) {
+    if (!opened.resumed && !note) {
         try {
             options.openConsole?.(consoleUrl);
         }
@@ -167,7 +174,7 @@ async function runDeploy(rootArg, governance, output, tenantId, options) {
             }
             output(outcomeLine(summary));
         }
-        return { cliVersion: CLI_VERSION, operationRef, result: { ...summary, consoleUrl } };
+        return { cliVersion: CLI_VERSION, operationRef, result: { ...summary, consoleUrl, ...(ai ? { ai } : {}) } };
     }
     catch (error) {
         throw await operationFailure(fetch, operationRef, error);
@@ -355,6 +362,34 @@ export async function appCallsAi(root) {
     const callsites = report?.gate?.inventory?.aiCallsites;
     return Array.isArray(callsites) && callsites.length > 0;
 }
+/**
+ * One plain line on whether this app's AI calls are real once it is deployed
+ * to the environment, printed for an app that calls governed AI. A builder was
+ * told by their agent that the check "simulated the AI reply" and could not
+ * tell whether AI was integrated (2026-09-26): the check's journey is answered
+ * by a canned reply, `deploy` refused a company without AI (`AI_NOT_READY`)
+ * but said nothing when the setup was fine. Grounded in governance's readiness
+ * route, which answers the same question the preflight asked and its
+ * `plainEnglish` when the answer is no. The readiness call is best-effort: a
+ * platform without the route, or a transport fault, falls back to what the
+ * passed preflight already established, and says that it is inferred.
+ */
+export async function describeAi(governance, appId, environment, output) {
+    const link = environment === "preview" ? "the preview link" : "the production link";
+    let readiness;
+    try {
+        readiness = await governance.aiReadiness(appId, environment);
+    }
+    catch {
+        readiness = undefined;
+    }
+    if (readiness && !readiness.ready) {
+        output(`AI: not enabled for this company's ${environment} apps — ${readiness.plainEnglish}`);
+        return { enabled: false, environment, reason: readiness.plainEnglish };
+    }
+    output(`AI: enabled for this company's ${environment} apps${readiness ? "" : " (inferred: the deploy pre-flight passed)"} — this app's AI calls are real from ${link}.`);
+    return { enabled: true, environment };
+}
 /** The three values as the command prints them before it starts. */
 export function describeProfile(profile) {
     return [`App name: ${profile.name}`, `Description: ${profile.description || "(none yet)"}`, `Audience: ${profile.audience.length ? profile.audience.join(", ") : "only you"}`];

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

@@ -88,7 +88,7 @@ AI goes through \`isomorph.ai\` only: one \`isomorph.ai.chat({ messages, maxToke
 const reply = await isomorph.ai.chat({ messages: [{ role: "user", content: \`Summarise these notes in three lines:\\n\${notes.map(n => n.title).join("\\n")}\` }], maxTokens: 200 });
 \`\`\`
 
-The starter calls no AI; add the one call when the person asks. The check's generated ai journey makes a real governed call locally through the development route with your \`isomorph login\`; in the pipeline it is answered by a canned completion and reported as not tested.`,
+The starter calls no AI; add the one call when the person asks. The check's generated ai journey is answered by a canned reply everywhere (locally and in the pipeline): it proves the call shape, never a model. Real AI runs from the app under \`isomorph dev\` and from the preview link.`,
     jobs: `# Scheduled jobs
 
 Jobs run as the app. Gmail and user-mode Slack require the current owner's connected account, an approved integration grant and explicit background permission in each environment. App-mode Slack needs no personal background consent.

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

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { basename } from "node:path";
 import { linkIdempotencyKey, readDeclaration, readKitLock, readReviewedAppProfile, requestResourceName, requestResources, writeKitLock, newKitLock } from "./kit.js";
 import { CliError } from "./output.js";
@@ -46,6 +47,10 @@ export class GovernanceClient {
     deployPreflight(appId, body) {
         return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/deploy-preflight`, body);
     }
+    /** Read-only: would the company's AI setup let this app's deployment PLAN pass for the environment? The same seam the deploy preflight asks beside the other blockers; `deploy` and `promote` read it to say in plain words whether the app's AI calls are real once deployed. */
+    aiReadiness(appId, environment) {
+        return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/ai/readiness`, { environment });
+    }
     /**
      * What the building agent says cost it time in Isomorph itself. Never blocks a
      * deployment: the caller discards every failure, and an empty note files nothing.
@@ -74,8 +79,18 @@ export class GovernanceClient {
     retryDeployment(appId, operationRef) {
         return this.call("POST", `${deployments(appId)}/${encodeURIComponent(operationRef)}/retry`, {});
     }
-    async call(method, path, body) {
-        return (await this.exchange(method, path, body)).data;
+    /**
+     * Who may open the app: the console's own audience route, called with the
+     * company sign-in (a Cognito ID token) this CLI holds since 0.11.0. It changes
+     * the access policy only — no release. The route's refusals are a bare
+     * `{ error: "<code>" }`, unlike the `/v1/development/*` envelope, and a
+     * 401 is the gateway refusing a token of the old adapter kind.
+     */
+    share(appId, emails) {
+        return this.call("PUT", `/v1/maker/${encodeURIComponent(this.tenantId)}/apps/${encodeURIComponent(appId)}/access`, { emails }, { headers: { "x-harbour-idempotency-key": randomUUID() }, refusals: SHARE_REFUSALS, unauthorized: SHARE_SIGN_IN });
+    }
+    async call(method, path, body, options) {
+        return (await this.exchange(method, path, body, options)).data;
     }
     /**
      * One request, with governance's refusal carried whole: its code (or category,
@@ -85,26 +100,40 @@ export class GovernanceClient {
      * 5xx are named as such (`GOVERNANCE_UNREACHABLE`, `HTTP_5xx`) so a long poll
      * can tell a transient fault from a refusal; see `waitForSettled`.
      */
-    async exchange(method, path, body) {
+    async exchange(method, path, body, options = {}) {
         const url = `${this.apiUrl.replace(/\/$/, "")}${path}`;
-        let response = await this.send(url, method, body);
+        let response = await this.send(url, method, body, options.headers);
         if (response.status === 401)
-            response = await this.send(url, method, body);
+            response = await this.send(url, method, body, options.headers);
         const parsed = await response.json().catch(() => ({}));
         if (response.status === 401)
-            throw new CliError("AUTH_REQUIRED", "Please sign in to Isomorph with `isomorph login`.", undefined, undefined, undefined, { layer: "governance" });
+            throw new CliError("AUTH_REQUIRED", options.unauthorized ?? "Please sign in to Isomorph with `isomorph login`.", undefined, undefined, undefined, { layer: "governance" });
+        // The maker routes (the console's) refuse with `{ error: "<code>" }` and no sentence: the CLI's own words for each code.
+        if (!response.ok && typeof parsed.error === "string")
+            throw new CliError(parsed.error.toUpperCase(), options.refusals?.[parsed.error] ?? "Isomorph governance rejected the request.", undefined, undefined, undefined, { layer: "governance" });
         if (!response.ok) {
-            const { code, remediationHint, ...details } = parsed.error?.details ?? {};
-            throw new CliError(code ?? parsed.error?.category ?? `HTTP_${response.status}`, parsed.error?.message || "Isomorph governance rejected the request.", undefined, typeof remediationHint === "string" && remediationHint.trim() ? remediationHint.trim() : undefined, undefined, { layer: "governance", ...(Object.keys(details).length ? { details } : {}) });
+            const failure = typeof parsed.error === "object" ? parsed.error : undefined;
+            const { code, remediationHint, ...details } = failure?.details ?? {};
+            throw new CliError(code ?? failure?.category ?? `HTTP_${response.status}`, failure?.message || "Isomorph governance rejected the request.", undefined, typeof remediationHint === "string" && remediationHint.trim() ? remediationHint.trim() : undefined, undefined, { layer: "governance", ...(Object.keys(details).length ? { details } : {}) });
         }
         return { status: response.status, data: (parsed.data ?? parsed) };
     }
-    async send(url, method, body) {
+    async send(url, method, body, headers = {}) {
         const token = await this.token();
-        return this.fetchImpl(url, { method, headers: { ...(token ? { authorization: `Bearer ${token}` } : {}), "x-harbour-tenant": this.tenantId, accept: "application/json", ...(body ? { "content-type": "application/json" } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}), redirect: "error" })
+        return this.fetchImpl(url, { method, headers: { ...(token ? { authorization: `Bearer ${token}` } : {}), "x-harbour-tenant": this.tenantId, accept: "application/json", ...(body ? { "content-type": "application/json" } : {}), ...headers }, ...(body ? { body: JSON.stringify(body) } : {}), redirect: "error" })
             .catch((error) => { throw new CliError("GOVERNANCE_UNREACHABLE", `Isomorph governance at ${new URL(url).host} could not be reached: ${transportFailure(error)}.`); });
     }
 }
+/** The console's refusals of an audience change, in the words it shows (makerAppActionPlainEnglish). */
+export const SHARE_REFUSALS = {
+    app_access_not_owned: "Only the builder who registered this app can change it.",
+    individual_sharing_disabled: "This company has not enabled sharing apps with named colleagues. Confirm an empty audience, or ask an administrator.",
+    external_email_not_allowed: "Only email addresses on the company's approved domains can be given access.",
+    invalid_share_emails: "Audience must be a list of up to 100 company email addresses.",
+    app_not_found: "Isomorph has no registered app for this operation."
+};
+/** A 401 from the audience route, or a stored sign-in of the adapter kind: the maker routes take only the company sign-in. */
+export const SHARE_SIGN_IN = "Sign in again with `isomorph login`: sharing needs the company sign-in this CLI now uses.";
 const deployments = (appId) => `/v1/development/apps/${encodeURIComponent(appId)}/deployments`;
 /**
  * What actually failed under a `fetch` rejection. undici reports every transport

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

@@ -1,6 +1,6 @@
 export const PUBLISHED_KIT_BUNDLE = {
     "schema": "isomorph.kit-bundle/1.0",
-    "kitVersion": "0.10.6",
+    "kitVersion": "0.11.1",
     "sdk": {
         "package": "@isomorph.ai/app-sdk",
         "version": "1.4.3",
@@ -8,21 +8,21 @@ export const PUBLISHED_KIT_BUNDLE = {
         "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:56489ae64e0765e0576172c5f0997230a3663cbe033608239de232c11aab0791"
     },
     "images": {
-        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:0b9c97b37eee8fa9cf3b1edac148efd521a4a68ce32f66e821ab3bc72fbe55c1",
-        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:11e88e41b526b3ad7a9a7271ed13bef7c171301e05c55ca5f93c7bffd9523103"
+        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:a22dfa2b2ff5780e0e2ea7e949216c1703123442f8e2d1e519d5a8493bb5a450",
+        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:9ad3a92fed4584bc2b43ebb5819ae729d333f8ed8c9930faabeaf8c0d15924ce"
     },
     "nativeRuntime": {
         "darwinArm64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:5f0cd4de0d4e82817c89857b411ef56d926851d96f64a3bf6ef0ce86317b1933",
-            "sha256": "5f0cd4de0d4e82817c89857b411ef56d926851d96f64a3bf6ef0ce86317b1933"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:f753062e2cf21f52f7010152fbcb1d46d1d4e9cf819c608f0e66afaa39e61cd0",
+            "sha256": "f753062e2cf21f52f7010152fbcb1d46d1d4e9cf819c608f0e66afaa39e61cd0"
         },
         "linuxX64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:782d93aafc712f8d7c5994d78f5b282a9a6f43c9b8ff0812f6904034495d584f",
-            "sha256": "782d93aafc712f8d7c5994d78f5b282a9a6f43c9b8ff0812f6904034495d584f"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:1938c28a92fd3fe5054c6b732bc6fe1a6a31728f9a0e416d653db1ef3726317f",
+            "sha256": "1938c28a92fd3fe5054c6b732bc6fe1a6a31728f9a0e416d653db1ef3726317f"
         },
         "windowsX64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:ea1b013f842c0a01291f0b6a1241117ebf3f1385e97c0ee447f1e04fa576b7dd",
-            "sha256": "ea1b013f842c0a01291f0b6a1241117ebf3f1385e97c0ee447f1e04fa576b7dd"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:244a255159a0c641875b22aa550622ff5345e5c129c40802d7609bf375245c1b",
+            "sha256": "244a255159a0c641875b22aa550622ff5345e5c129c40802d7609bf375245c1b"
         }
     },
     "brief": {

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

@@ -197,11 +197,31 @@ function activity(status) {
         return "deploying the app";
     return saveInFlight(status) ? "saving the app" : "preparing the deployment";
 }
+/**
+ * The deployment as a builder reads it: which of four steps is running and
+ * roughly how long it takes. Keyed by `deployment.status`, the data plane's
+ * version state (`deploymentStatuses` in governance); the control plane's own
+ * phase sentence rides along in parentheses so an agent, and anyone debugging,
+ * still sees the finer phase. A status outside the table — LIVE, FAILED,
+ * WAITING_INPUT, or none at all — keeps the plain line.
+ */
+const DEPLOYMENT_STEPS = [
+    [["QUEUED", "ANALYZING"], "Step 1 of 4: Isomorph is getting a build slot ready, usually under a minute"],
+    [["TRANSFORMING", "VALIDATING", "BUILDING"], "Step 2 of 4: Isomorph is building the app and re-running its checks in the cloud, about 3–5 minutes"],
+    [["VERIFYING"], "Step 3 of 4: Isomorph is setting up the app's database, files and sign-in"],
+    [["GATING"], "Step 4 of 4: final security check, then the preview link switches on"]
+];
+/** One line for a deployment in flight: the builder's step when the status names one, then the server's phase in parentheses. */
+export function deploymentProgressLine(deployment) {
+    const step = DEPLOYMENT_STEPS.find(([statuses]) => statuses.includes(deployment.status ?? ""))?.[1] ?? "Isomorph is deploying the app";
+    return `${step}${deployment.message ? ` (${deployment.message})` : ""}.`;
+}
 /** What the server is doing right now, as one line; printed when it changes. */
 function progressLine(status) {
-    const stage = status.production ?? status.deployment;
-    if (stage)
-        return `Isomorph is ${activity(status)}${stage.message ? ` (${stage.message})` : ""}.`;
+    if (status.production)
+        return `Isomorph is ${activity(status)}${status.production.message ? ` (${status.production.message})` : ""}.`;
+    if (status.deployment)
+        return deploymentProgressLine(status.deployment);
     switch (status.operation?.stage) {
         case "inspection": return "Isomorph is inspecting the app package.";
         case "verification": return "Isomorph is verifying the saved app.";

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

@@ -0,0 +1,25 @@
+import { describeProfile } from "./deploy.js";
+import { ensureLinkedApp, SHARE_SIGN_IN } from "./integrations.js";
+import { assertLockCompany, readKitLock, readReviewedAppProfile } from "./kit.js";
+import { CliError } from "./output.js";
+/**
+ * `isomorph share`: the audience in `.isomorph/app.json`, sent as the app's
+ * access policy without a release. `deploy` carries the same audience with the
+ * package; this is the path for the builder who only changed who may open the
+ * app. The route is the console's, behind the company sign-in: a record of the
+ * adapter kind is refused here, before the network, rather than by a 401.
+ */
+export async function shareApp(root, governance, tenantId, bundle, signedIn) {
+    if (signedIn && signedIn.kind !== "cognito")
+        throw new CliError("AUTH_REQUIRED", SHARE_SIGN_IN, undefined, "Run `isomorph logout` then `isomorph login`.");
+    const profile = await readReviewedAppProfile(root);
+    assertLockCompany(await readKitLock(root), tenantId);
+    const appId = await ensureLinkedApp(root, governance, tenantId, bundle);
+    const outcome = await governance.share(appId, profile.audience);
+    return { audience: profile.audience, outcome };
+}
+/** The audience line `deploy` prints, then what did (and did not) happen. */
+export function renderShare(audience) {
+    const line = describeProfile({ schema: "isomorph.app/1.0", name: "", description: "", audience }).find(entry => entry.startsWith("Audience:"));
+    return `${line}\nIsomorph updated who can open the preview; no new release was made.\n`;
+}

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

@@ -1,51 +1,75 @@
 import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { dirname, extname, join } from "node:path";
 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";
 export { MANAGED_END, MANAGED_START };
 /**
- * Files and folders that do not make a folder "an app": what an editor, git or an
- * agent leaves in an otherwise empty folder. Anything else is content, and content
- * without a kit lock is an app that was built without the kit.
+ * Files and folders that do not make a folder "an app": what an editor, git, npm or
+ * an agent leaves in an otherwise empty folder.
  */
-const IGNORABLE_ENTRIES = new Set([".git", ".DS_Store", ".gitignore", "README.md", "LICENSE", "CLAUDE.md", "AGENTS.md", ".claude", ".codex", ".vscode", ".idea"]);
-/** The three ways forward for a folder with an app and no kit, as the `APP_EXISTS` refusal carries them (`details.choices`). */
-export function appExistsChoices(dir) {
+const IGNORABLE_ENTRIES = new Set([".git", ".DS_Store", ".gitignore", "README.md", "LICENSE", "CLAUDE.md", "AGENTS.md", ".claude", ".codex", ".vscode", ".idea", "node_modules"]);
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".html"]);
+/**
+ * Whether a top-level entry makes the folder "an app that was built without the
+ * kit": a package manifest, a `src/` folder, an index file or a source file. Anything
+ * else (CSVs, JSON, images, notes) is data the starter is created around.
+ */
+function isAppEntry(name) {
+    return name === "package.json" || name === "src" || /^index\./.test(name) || SOURCE_EXTENSIONS.has(extname(name));
+}
+/**
+ * The ways forward for a folder with an app and no kit, as the `APP_EXISTS` refusal
+ * carries them (`details.choices`), in the order they can succeed: `adopt` only when
+ * the app is one the kit can be added to (package.json depends on vite and react),
+ * then a new kit app in a new folder, then the console import of the app as it is.
+ */
+export function appExistsChoices(dir, adoptable) {
     return [
-        { id: "adopt", command: `isomorph init --app-root ${dir} --adopt`, description: "add the kit to this app in place; Vite + React only" },
+        ...(adoptable ? [{ id: "adopt", command: `isomorph init --app-root ${dir} --adopt`, description: "add the kit to this Vite + React app in place" }] : []),
         { id: "new", command: "isomorph init --app-root <new-empty-folder>", description: "start a new kit app in a new empty folder" },
         { id: "package", command: `isomorph package --app-root ${dir}`, description: "package this app as it is for import in the Isomorph console" }
     ];
 }
+/** The one line `init` prints for a starter created around existing data files, so the person and the agent know they are there. */
+export function keptDataLine(dataFiles) {
+    return `Kept ${dataFiles.length} existing file${dataFiles.length === 1 ? "" : "s"} (${dataFiles.join(", ")}); read them from the app.`;
+}
 /**
- * Creates the starter in an empty directory, adds the missing kit files to an
- * existing Vite + React app (`adopt`), or keeps a kit app as it is. A folder
- * with an app and no kit is never adopted silently: the refusal names the
- * three choices and the agent relays them to the person. User files are never
- * overwritten: a path that exists is reported as kept. Instruction files get a
- * managed block that points at the rules, and the user-level agent guide (the
- * rules themselves) is installed so the agents know the kit from any folder.
+ * Creates the starter in an empty directory or one that holds only data (no
+ * package.json, no source: the data stays and is named), adds the missing kit
+ * files to an existing Vite + React app (`adopt`), or keeps a kit app as it is.
+ * A folder with an app and no kit is never adopted silently: the refusal names
+ * the choices that can succeed and the agent relays them to the person. User
+ * files are never overwritten: a path that exists is reported as kept.
+ * Instruction files get a managed block that points at the rules, and the
+ * user-level agent guide (the rules themselves) is installed so the agents know
+ * the kit from any folder.
  */
 export async function initKit(root, bundle, options = {}) {
     await mkdir(root, { recursive: true });
     const existingPackage = await readJson(join(root, "package.json"));
     const previous = await readKitLock(root);
-    const emptyDir = (await readdir(root)).every(name => IGNORABLE_ENTRIES.has(name));
+    const entries = (await readdir(root)).filter(name => !IGNORABLE_ENTRIES.has(name)).sort();
+    const appHere = entries.some(isAppEntry);
+    // No app and no kit here: the starter is created, around whatever data the folder holds.
+    const starter = !previous && !appHere;
     const unsupported = () => new CliError("APP_UNSUPPORTED", "isomorph init supports an empty directory or an existing Vite + React app (package.json must depend on vite and react).", undefined, "Run `isomorph init --app-root <new-empty-folder>` to start a Vite + React app, then move this app's code into it.");
-    if (!emptyDir && !previous && !options.upgrade) {
+    const adoptable = Boolean(existingPackage && isSupportedApp(existingPackage));
+    if (appHere && !previous && !options.upgrade) {
         // Refused before anything is written, here or in the person's home: the choice is theirs.
-        const dir = options.displayRoot ?? root;
-        const choices = appExistsChoices(dir);
+        const choices = appExistsChoices(options.displayRoot ?? root, adoptable);
         if (!options.adopt)
-            throw new CliError("APP_EXISTS", "This folder already has an app and no Isomorph kit.", undefined, "Choose one of the three commands below: add the kit to this app in place (--adopt, Vite + React only), start a new kit app in an empty folder, or package this app as it is for the console import.", undefined, { details: { choices } });
-        if (!existingPackage || !isSupportedApp(existingPackage))
+            throw new CliError("APP_EXISTS", "This folder already has an app and no Isomorph kit.", undefined, adoptable
+                ? "Choose one of the three commands below: add the kit to this app in place (--adopt), start a new kit app in an empty folder, or package this app as it is for the console import."
+                : "Choose one of the two commands below: start a new kit app in an empty folder, or package this app as it is for the console import. --adopt does not apply: it needs a package.json that depends on vite and react.", undefined, { details: { choices } });
+        if (!adoptable)
             throw unsupported();
     }
-    else if (existingPackage && !isSupportedApp(existingPackage))
+    else if (existingPackage && !adoptable)
         throw unsupported();
-    const result = { root, created: [], kept: [], updated: [], mode: options.upgrade ? "upgrade" : previous ? "kit" : emptyDir ? "starter" : "existing", bundleChanges: [], agents: options.env ? await agentSetup(options.env) : { created: [], updated: [], kept: [], removed: [] } };
+    const result = { root, created: [], kept: [], updated: [], mode: options.upgrade ? "upgrade" : previous ? "kit" : starter ? "starter" : "existing", bundleChanges: [], dataFiles: starter ? entries : [], agents: options.env ? await agentSetup(options.env) : { created: [], updated: [], kept: [], removed: [] } };
     const write = async (path, content) => {
         const absolute = join(root, path);
         if (await exists(absolute)) {
@@ -58,7 +82,7 @@ export async function initKit(root, bundle, options = {}) {
     };
     // The starter (its source and schema) is created only when there is no app here
     // yet; kit infrastructure is written on every path, including `--upgrade`.
-    const appFiles = emptyDir ? starterFiles(bundle) : {};
+    const appFiles = starter ? starterFiles(bundle) : {};
     for (const [path, content] of Object.entries({ ...appFiles, ...kitFiles(root) }))
         await write(path, content);
     await appendManaged(root, ".gitignore", GITIGNORE_LINES, result, "\n");
@@ -199,12 +223,14 @@ function starterFiles(bundle) {
 /** The starter's README, for the people who open the folder: what it is, the three commands, and where the rules are. Rule text lives in the `isomorph` skill only. */
 export const STARTER_README = `# Isomorph app
 
+The first page — a notes list and a private-files card — is a placeholder the agent replaces with the app you asked for.
+
 Created by \`isomorph init\`: a Vite + React app that runs on Isomorph. Sign-in, data, files and company systems come from the platform through \`@isomorph.ai/app-sdk\`, so the app has no backend of its own.
 
 ## Three commands
 
 - \`isomorph dev --app-root . --detach --json\` — starts the app on this machine with a local database, file store and gateway; open the printed link.
-- \`isomorph check --app-root . --json\` — the same gates the deployment pipeline runs (types, build, schema, journeys); the output is the report.
+- \`isomorph check --app-root . --json\` — the same gates the deployment pipeline runs (types, build, schema, journeys).
 - \`isomorph deploy --app-root . --json\` — deploys a private preview for the people named in \`.isomorph/app.json\`; \`isomorph promote\` makes it live for everyone once they have tried it.
 
 ## Where the rules are
@@ -213,7 +239,7 @@ The kit's rules are in the \`isomorph\` skill that \`isomorph agent-setup\` inst
 
 ## Look and feel
 
-\`src/styles.css\` is the whole look: plain CSS, no UI library, light and dark. Change it freely — the starter is a readable floor, not a design.
+\`src/styles.css\` is the whole look: plain CSS, no UI library, light and dark. Change it freely.
 
 \`.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.
 `;
@@ -289,8 +315,9 @@ export function App() {
   return (
     <main className="app">
       <header className="app-header">
-        <h1>Isomorph starter</h1>
-        <p className="muted">Signed in as <strong>{user ? user.email : "…"}</strong> (identity from Isomorph; locally the fixture user).</p>
+        <h1>Isomorph starter (placeholder)</h1>
+        <p className="muted">This page is a placeholder; your app replaces it.</p>
+        <p className="muted">Signed in as <strong>{user ? user.email : "…"}</strong> (a test user while running locally).</p>
       </header>
       {error && <p role="alert" className="alert">{error}</p>}
 

package/package.json

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