@isomorph.ai/cli 0.4.2 → 0.5.1

package/README.md

@@ -28,7 +28,8 @@ 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> [--upgrade]                 starter app in an empty folder, or kit files in a Vite + React app (also runs agent-setup); --upgrade re-pins the kit bundle and runs the checks
+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 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
 isomorph check --app-root <path> [--integrations] [--json]  types, build, migrations, database gate, write probe, journeys, coverage; --json prints the whole report
@@ -36,15 +37,17 @@ isomorph integrations catalog --app-root <path> [--json]   the company's connect
 isomorph integrations request <connection> --app-root <path> [--reason <text>]   one request per connection; IT approves it once for every environment (`isomorph dev` and `isomorph deploy` file it for you)
 isomorph integrations status --app-root <path> [--json]
 isomorph connect <work-email | company-start-url>                 once per company; then isomorph login | logout
-isomorph deploy --app-root <path> [--json]                  checks (when not already passed for this code), one pre-flight, save + preview deployment; prints the protected link
-isomorph status | retry | promote --operation <reference>   (promote: [--app-root <path>] [--confirm-tested])
+isomorph deploy --app-root <path> [--json]                  checks (when not already passed for this code), then one call that runs the pre-flight and opens the deployment; the package is handed over and Isomorph saves, verifies and deploys it; prints the protected link
+isomorph status | retry | promote [--app-root <path>] [--operation <reference>]   (--app-root defaults to the current folder; --operation to the deployment last started from it; promote: [--confirm-tested])
 ```
 
-`deploy` reads the app's name, description and audience from `.isomorph/app.json` (written by `init`; edit it before shipping) and prints the three values before it starts. It then asks Isomorph once whether the app can deploy — the access request for every declared connection, the company's AI setup when the app calls governed AI, and this CLI's version — and refuses with exit 2 naming every blocker and its fix (`DEPLOY_BLOCKED`, or `INTEGRATIONS_NOT_READY` / `AI_NOT_READY` / `CLI_UPGRADE_REQUIRED` when the blockers are all of one kind).
+`deploy` reads the app's name, description and audience from `.isomorph/app.json` (written by `init`; edit it before shipping) and prints the three values before it starts. It then asks Isomorph once whether the app can deploy — the access request for every declared connection, the company's AI setup when the app calls governed AI, and this CLI's version — and refuses with exit 2 naming every blocker and its fix (`DEPLOY_BLOCKED`, or `INTEGRATIONS_NOT_READY` / `AI_NOT_READY` / `CLI_UPGRADE_REQUIRED` when the blockers are all of one kind). The same package (by digest) always continues the same deployment, so running `deploy` again after an interruption resumes rather than restarts; a different package while one is still deploying is refused (`DEPLOY_IN_FLIGHT`) naming the operation to follow.
 
-`deploy`, `status --wait`, `retry` and `promote` follow the deployment for up to `--max-wait <seconds>` (default 30 minutes). Past that they exit 0 with `status: "RUNNING"` and the `isomorph status --operation <reference> --wait --max-wait 120 --json` that continues the same deployment — a bounded wait is not a failure, and never a reason to start another deploy.
+`deploy`, `status --wait`, `retry` and `promote` follow the deployment for up to `--max-wait <seconds>` (default 30 minutes). Past that they exit 0 with `status: "RUNNING"` and the `isomorph status --app-root . --operation <reference> --wait --max-wait 120 --json` that continues the same deployment — a bounded wait is not a failure, and never a reason to start another deploy.
 
-`promote` never prompts: `--confirm-tested` is the one flag that means the person has opened the preview and it works. `productionise` is still accepted as an unlisted alias of `deploy` for one release.
+`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`.
 
 `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; Vite + React app → kit files only). Node 22+, no Docker.
+- No \`.isomorph/\` yet: \`isomorph init --app-root .\` (empty folder → starter; an existing app → three choices to relay). Node 22+, no Docker.
 - Sign-in (company systems and shipping only): \`isomorph connect <work-email>\` (refused? run the command it prints), then \`isomorph login\` — the browser opens and the person finishes there (their one step; say so).
 
 ## Intent → command

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

@@ -1,8 +1,5 @@
-import { readFile, readdir, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
-import { readAppSchema } from "./app-schema.js";
-import { describeRetainedChecks, syncRetainedChecks } from "./retained-checks.js";
+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";
@@ -36,10 +33,10 @@ export const FLOW_CHECK = "flow.check-failed";
  * Runs the kit checks and writes `.isomorph/local/check-report.json`; a source
  * edit changes sourceDigest and so invalidates the previous report. The app's
  * own toolchain first (typecheck, build), then the kit gate — the pipeline's
- * gate, run by the pinned gateway image in this app's local session — whose
- * checks are reported verbatim. The retained journeys are generated inside
- * that run, from the app's tables as the gate's replayed database holds
- * them, before the gate enumerates and runs them.
+ * gate, run by the pinned native gateway in this app's local session — whose
+ * checks are reported verbatim. The gate generates `.isomorph/checks/` from
+ * the app's tables as its replayed database holds them and runs those
+ * journeys, and the builder's own `tests/*.mjs`, itself (data plane ADR 0014).
  */
 export async function runChecks(root, options) {
     const { output, run, bundle } = options;
@@ -54,12 +51,12 @@ export async function runChecks(root, options) {
     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 journeys run here with the app's own node and SDK: the SDK the bundle
-    // pins, installed now if node_modules holds an older copy.
+    // 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).`);
-    const gate = await runKitGate(root, { run, bundle, output, ...(options.fetch ? { fetch: options.fetch } : {}), ...(options.runtime ? { runtime: options.runtime } : {}) });
+    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);
     let integrations = "not tested";
@@ -91,11 +88,9 @@ export async function runChecks(root, options) {
             }
         }
     }
-    // After the gate, because `.isomorph/checks/*.mjs` is part of the deployed
-    // tree (kit.ts `sourceDigest`) and the gate may have regenerated it: the
-    // report has to pin the tree the journeys actually ran against, or
-    // `isomorph deploy` would refuse the very tree this check just passed
-    // as CHECKS_STALE.
+    // `.isomorph/checks/` is generated output outside the deployable tree
+    // (kit.ts `sourceDigest`), so the digest pinned here is the one `deploy`
+    // recomputes whether or not the gate regenerated the directory.
     const source = await sourceDigest(root);
     const report = {
         schema: "isomorph.check-report/1.0",
@@ -119,13 +114,13 @@ function renderCheck(check) {
 /**
  * Runs the pipeline's kit gate in this app's local session: the pinned
  * native gateway's `gate` subcommand as a one-shot process using the local
- * session's scratch database and files. The gate's control API drives two things
- * from here: the `checks` phase, where the gate hands over the app's tables
- * as its replayed database holds them and `.isomorph/checks/` is regenerated
- * from them (retained-checks.ts) and handed back as the set to run; and the
- * journeys, run here — the app's own node and SDK — one at a time as the
- * gate asks for them. The session services are started when `isomorph dev`
- * is not running and stopped again afterwards.
+ * session's scratch database and files. The gate does the whole run itself —
+ * derivation, database, the generation of `.isomorph/checks/` and the journeys
+ * (generated and `tests/*.mjs`) with this node and the app's SDK — so this is
+ * a status loop: `GET /_gate/session` for the progress line, `GET /_gate/report`
+ * for the result, whose `files` is `.isomorph/checks/` as generated and is
+ * applied to the app before the report is returned. The session services are
+ * started when `isomorph dev` is not running and stopped again afterwards.
  */
 export async function runKitGate(root, options) {
     const { run, bundle, output } = options;
@@ -136,111 +131,48 @@ export async function runKitGate(root, options) {
     const base = `http://127.0.0.1:${port}`;
     const deadline = Date.now() + (options.timeoutMs ?? 10 * 60_000);
     const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
-    const request = async (path, init) => { try {
-        return await fetchImpl(`${base}${path}`, init);
+    const request = async (path) => { try {
+        return await fetchImpl(`${base}${path}`);
     }
     catch {
         return undefined;
     } };
-    const post = (path, body) => request(path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
     // Everything after the session is up runs under one `finally`: a gate
-    // gate process that fails to start is exactly the case that could leave a
+    // process that fails to start is exactly the case that could leave a
     // session this run had started still running.
-    let container;
+    let gate;
     try {
-        container = await runtime.startGate(bundle, port, base);
-        let announced = false;
+        gate = await runtime.startGate(bundle, port);
+        let announced;
         while (Date.now() < deadline) {
             const done = await request("/_gate/report");
             if (done?.status === 200) {
                 const result = await done.json();
                 if (result.report) {
-                    // The app is mounted read-only and the gate works on a mirror, so
-                    // what it authored for the app to ship comes home here — today the
-                    // governed-AI inventory (`.isomorph/ai-inventory.json`), which the
-                    // pipeline verifies against the source and which only the gate may
-                    // write. Written before the caller pins the tree digest, like the
-                    // regenerated retained checks.
                     await writeGateFiles(root, result.files ?? {}, output);
                     return result.report;
                 }
                 throw new CliError("LOCAL_RUNTIME_FAILED", `The kit gate could not run: ${result.error ?? "no report"}.`);
             }
-            if (!(await runtime.gateRunning(container)))
-                throw new CliError("LOCAL_RUNTIME_FAILED", `The kit gate stopped before reporting: ${await runtime.gateLogs(container)}`);
+            if (!(await runtime.gateRunning(gate)))
+                throw new CliError("LOCAL_RUNTIME_FAILED", `The kit gate stopped before reporting: ${await runtime.gateLogs(gate)}`);
             const session = await request("/_gate/session");
             const state = session?.status === 200 ? await session.json() : undefined;
-            if (state?.status === "checks") {
-                const files = await regenerateRetainedChecks(root, state.catalog, state.capabilities, output);
-                const posted = await post("/_gate/checks", { files });
-                if (posted?.status !== 200)
-                    throw new CliError("LOCAL_RUNTIME_FAILED", "The kit gate did not accept the retained checks.");
-                continue;
-            }
-            if (state?.status === "journeys" && state.current && state.environment) {
-                if (!announced) {
-                    announced = true;
-                    output("Running the retained journeys against the gate's App Gateway.");
-                }
-                const name = state.current;
-                const result = await run("node", [join(kitPaths(root).checks, name)], { cwd: root, quiet: true, env: { ...state.environment, ISOMORPH_SDK_MODULE: sdkModuleSpecifier(root, bundle), NODE_NO_WARNINGS: "1" } });
-                const posted = await post(`/_gate/journeys/${encodeURIComponent(name)}`, { code: result.code, output: `${result.stdout}${result.stderr}`.slice(-4000) });
-                if (posted?.status !== 200)
-                    throw new CliError("LOCAL_RUNTIME_FAILED", `The kit gate did not accept the result of ${name}.`);
-                continue;
+            if (state?.status === "journeys" && state.current && state.current !== announced) {
+                announced = state.current;
+                output(`Running journey ${state.current}`);
             }
             await sleep(options.pollMs ?? 500);
         }
         throw new CliError("LOCAL_RUNTIME_FAILED", "The kit gate did not finish within its budget.");
     }
     finally {
-        if (container)
-            await runtime.stopGate(container);
+        if (gate)
+            await runtime.stopGate(gate);
         if (started)
             await runtime.down();
     }
 }
-/**
- * The SDK a generated journey imports, as a `file://` URL rather than a path.
- *
- * The journey does `await import(process.env.ISOMORPH_SDK_MODULE)`, and on
- * Windows a bare absolute path is not a specifier `import()` accepts: Node
- * reads the drive letter in `D:\\app\\node_modules\\…` as a URL scheme and
- * refuses it with ERR_UNSUPPORTED_ESM_URL_SCHEME. Every journey on Windows
- * therefore failed before it reached its first assertion. It went unseen
- * because `isomorph check` reported those failures and still exited 0 (a
- * dependency's `beforeExit` hook overwrote `process.exitCode`, fixed in
- * 0.3.1-rc.1), so the Windows lane read the run as a pass.
- */
-export function sdkModuleSpecifier(root, bundle) {
-    return pathToFileURL(join(root, "node_modules", ...bundle.sdk.package.split("/"), "dist", "index.js")).href;
-}
-/**
- * `.isomorph/checks/` is generated from what the app declares — the tables the
- * gate's replayed database holds, the capabilities the gate derived from the
- * source (the set its coverage gate will demand evidence for) —
- * before the gate reads it, so a check for a feature the app dropped cannot
- * survive a single `isomorph check`, and a feature it added arrives with its
- * journey. This is not one of the gates: it writes files and reports what it
- * did, and the gate's coverage check still decides. Files Isomorph did not
- * write, and generated files the builder has edited, are never touched — and
- * when the catalog is not one, nothing is touched at all. Resolves to the
- * complete set the gate is to run.
- */
-async function regenerateRetainedChecks(root, catalog, capabilities, output) {
-    const schema = await readAppSchema(typeof catalog === "string" ? catalog : JSON.stringify(catalog ?? null), root);
-    if (schema)
-        for (const line of describeRetainedChecks(await syncRetainedChecks(root, schema, Array.isArray(capabilities) ? capabilities : undefined)))
-            output(line);
-    else
-        output(".isomorph/checks/ was left as it is: the app's tables could not be read from the gate's database, so there was nothing to generate from.");
-    const directory = kitPaths(root).checks;
-    const names = (await readdir(directory).catch(() => [])).filter(name => /\.(mjs|js|cjs)$/.test(name)).sort();
-    const files = {};
-    for (const name of names)
-        files[name] = await readFile(join(directory, name), "utf8");
-    return files;
-}
 /** Brings the session services up when `isomorph dev` is not running; resolves to whether they were started here (and so are taken down again after the gate, data kept). */
 async function ensureSession(root, runtime, bundle, output) {
     const lock = await readDevLock(root);
@@ -311,17 +243,24 @@ export async function readReport(root) {
 function lastLines(text, count = 5) { return text.trim().split("\n").slice(-count).join(" | ").slice(0, 600); }
 /** A multi-line detail (one gate violation per line) keeps its lines, each under the check name. */
 function indentLines(detail) { return detail.split("\n").map((line, index) => index ? `      ${line}` : line).join("\n"); }
-/** Files the gate authored for the app (path → content, or null to remove), confined to `.isomorph/`. */
+/**
+ * `.isomorph/checks/` as the gate generated it (path → content, or null for a
+ * file this run did not generate), applied to the app. Confined to that
+ * directory: it is generated output, gitignored by `init` and outside the
+ * deployable tree; the builder's own checks live in `tests/*.mjs`, which the
+ * gate runs and never writes.
+ */
 export async function writeGateFiles(root, files, output) {
     for (const [path, content] of Object.entries(files)) {
-        if (!/^\.isomorph\/[A-Za-z0-9._-]+$/.test(path))
-            throw new CliError("LOCAL_RUNTIME_FAILED", `The kit gate named a file outside .isomorph/: ${path}.`);
+        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}.`);
         const target = join(root, path);
         if (content === null) {
             await rm(target, { force: true });
             output(`Removed ${path}: the app no longer needs it.`);
         }
         else {
+            await mkdir(dirname(target), { recursive: true });
             await writeFile(target, content);
             output(`Wrote ${path}.`);
         }

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

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
-import { RemoteMcpClient } from "./remote-mcp-client.js";
-import { appCallsAi, deploy } from "./deploy.js";
-import { continueCommand, fetchStatus, follow, promoteToProduction, retryDeployment, summarize } from "./operations.js";
+import { appCallsAi, deploy, 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 { connectedAccount, login, logout, refreshStoredToken } from "./auth.js";
 import { assertCliCurrent, companyLabel, connect, loadConfig, resolveConfig } from "./config.js";
 import { EMBEDDED_KIT_BUNDLE } from "./kit-bundle.js";
-import { appRoot, requestResourceName } from "./kit.js";
+import { appRoot, readAppProfile, readKitLock, requestResourceName } from "./kit.js";
 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";
@@ -16,8 +16,8 @@ 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";
 const args = process.argv.slice(2);
-// `productionise` was the command's name until 0.3.4: it is accepted for one release, unlisted, and behaves exactly as `deploy`.
-const command = args[0] === "productionise" ? "deploy" : args[0];
+// `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];
 const connectUrl = args[1];
 const root = optionValue("--app-root");
 const operationRef = optionValue("--operation");
@@ -32,6 +32,10 @@ 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. */
+const adopt = args.includes("--adopt");
+/** `package --out`: where the console import package is written (default `<app-root>/isomorph-import.zip`). */
+const out = optionValue("--out");
 const testIntegrations = args.includes("--integrations");
 const reason = optionValue("--reason");
 const operations = optionValue("--operations");
@@ -49,25 +53,26 @@ 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> [--upgrade]                 create the starter or add the kit files (also runs agent-setup); --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 (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 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",
-    "  isomorph status --operation <reference> [--wait] [--max-wait <seconds>] [--json]",
-    "  isomorph retry --operation <reference> [--no-wait] [--max-wait <seconds>] [--json]",
-    "  isomorph promote --operation <reference> [--app-root <path>] [--confirm-tested] [--no-wait] [--max-wait <seconds>] [--json]   (--confirm-tested: the person has tried the preview; --app-root: also confirm the company's AI setup for production when the app calls governed AI)",
+    "  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 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)",
     "  isomorph jobs run <name> --app-root <path> [--scheduled-at <UTC>] [--real] [--json]  run one scheduled job now (local fixtures; --real uses approved company access)",
     "  isomorph integrations request <connection> --app-root <path> [--reason <text>] [--operations a,b] [--json]   one request per connection, for every environment at once: IT approves it once (isomorph dev and deploy file it for you)",
     "  isomorph integrations status --app-root <path> [--json]",
     "  isomorph integrations catalog --app-root <path> [--json]   the company's connections as .isomorph/integrations.json names them: identifiers, allowed operations, approved channels/tables/views/mailboxes per environment (no app needed)",
     "Run `isomorph connect <work-email>` once; sign in with `isomorph login` when Isomorph asks.",
-    "deploy runs the checks when they have not passed for this exact code, then asks Isomorph once whether the app can deploy (the access request for every connection in .isomorph/integrations.json, which IT approves once for every environment; the company's AI setup when the app calls governed AI; this CLI's version) and refuses with exit 2 naming every blocker and its fix; then it saves the app, follows its deployment and prints the protected preview link. promote sends a tested preview to production after the same question for production.",
+    "deploy runs the checks when they have not passed for this exact code, then asks Isomorph once whether the app can deploy (the access request for every connection in .isomorph/integrations.json, which IT approves once for every environment; the company's AI setup when the app calls governed AI; this CLI's version) and refuses with exit 2 naming every blocker and its fix; then it hands the app package to Isomorph, which saves it, verifies it and deploys it, and prints the protected preview link. The same package always continues the same deployment. promote sends a tested preview to production after the same question for production.",
     `--max-wait bounds how long deploy, status --wait, retry and promote follow the deployment (default 30 minutes). When it passes the command exits 0 with status RUNNING, the last known deployment state, and the \`${continueCommand("<reference>")}\` that continues the same deployment: a bounded wait is not a failure and never means start another one.`,
     ""
 ].join("\n");
 const OPERATION_COMMANDS = ["status", "retry", "promote"];
-const LOCAL_COMMANDS = ["init", "dev", "stop", "check", "jobs"];
+const LOCAL_COMMANDS = ["init", "package", "dev", "stop", "check", "jobs"];
 const progress = (message) => { process.stderr.write(`${message}\n`); };
 /** Envelope for commands that start no Isomorph operation (local kit commands, integrations). */
 const summaryEnvelope = (result) => ({ schema: "isomorph.cli-result/1.0", cliVersion: CLI_VERSION, status: "SUCCEEDED", operationStarted: false, result });
@@ -81,8 +86,8 @@ const emit = (value, line) => { process.stdout.write(json ? `${JSON.stringify(va
  * which is how an agent or a CI job reads this CLI. Both writes flush first.
  */
 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. */
-const USAGE_REFUSALS = ["DEPLOY_BLOCKED", "INTEGRATIONS_NOT_READY", "AI_NOT_READY", "CLI_UPGRADE_REQUIRED", "NOT_A_MEMBER", "TENANT_AMBIGUOUS", "NOT_A_START_LINK", "PLATFORM_UNREACHABLE"];
+/** 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"];
 if (command === "--version" || command === "version") {
     process.stdout.write(`${CLI_VERSION}\n`);
     // `-h` was matched anywhere in argv while `--help` was only recognised as the
@@ -105,12 +110,11 @@ else if (command === "agent-setup") {
 }
 else if (!["connect", "login", "logout", "deploy", "integrations", ...LOCAL_COMMANDS, ...OPERATION_COMMANDS].includes(command)
     || (command === "connect" && (!connectUrl || connectUrl.startsWith("--")))
-    || (["deploy", "status", "retry", "promote"].includes(command) && optionError)
+    || (["deploy", ...OPERATION_COMMANDS].includes(command) && optionError)
     || (command === "deploy" && !root)
     || (LOCAL_COMMANDS.includes(command) && !root)
     || (command === "jobs" && (subcommand !== "run" || !args[2] || args[2].startsWith("--")))
-    || (command === "integrations" && (!root || !subcommand || !["request", "status", "catalog"].includes(subcommand) || (subcommand === "request" && (!args[2] || args[2].startsWith("--")))))
-    || (OPERATION_COMMANDS.includes(command) && !operationRef)) {
+    || (command === "integrations" && (!root || !subcommand || !["request", "status", "catalog"].includes(subcommand) || (subcommand === "request" && (!args[2] || args[2].startsWith("--")))))) {
     exitAfterWriting(2, "", `${optionError ? `${optionError}\n` : ""}${usage}`);
 }
 else {
@@ -125,15 +129,23 @@ else {
             const target = appRoot(root);
             const config = resolveConfig(process.env, await loadConfig());
             const companyToken = async () => config ? (explicitToken || await refreshStoredToken(config.mcpUrl, config.tenantId)) : undefined;
-            if (command === "init") {
-                const result = await initKit(target, bundle, { upgrade, tenantId: config?.tenantId, env: process.env });
+            if (command === "package") {
+                // Purely local: no company, no sign-in, no kit — the person uploads the file in the console.
+                const result = await packageApp(root, progress, { ...(out ? { out } : {}) });
+                emit(summaryEnvelope(result), `${result.path}\nNext: ${result.nextStep}\n`);
+            }
+            else if (command === "init") {
+                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\`.`);
-                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.") : "Kit files added; existing files were kept.");
+                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}\`.`
+                            : "Kit files added; existing files were kept.");
                 if (upgrade) {
                     const report = await runChecks(target, { run: runCommand, bundle, output: progress });
                     emit(summaryEnvelope({ ...result, report }));
@@ -202,6 +214,7 @@ else {
             // Before any network call: a CLI the company's platform no longer accepts is refused
             // here, in under a second, with the install command, instead of by the pipeline.
             assertCliCurrent(config);
+            // Sign-in is discovered from the MCP endpoint's OAuth metadata; every command here talks REST to the same API.
             const url = config.mcpUrl;
             const tenant = config.tenantId;
             if (command === "login") {
@@ -216,15 +229,13 @@ else {
             }
             else {
                 const resolveToken = async () => explicitToken || await refreshStoredToken(url, tenant);
-                const token = await resolveToken();
-                if (!token)
+                if (!(await resolveToken()))
                     throw new CliError("AUTH_REQUIRED", "Please sign in to Isomorph with `isomorph login`.");
                 // The client re-resolves per request so a token rotated by a sibling process mid-poll is picked up.
-                const client = new RemoteMcpClient(url, resolveToken, tenant);
+                const governance = new GovernanceClient(config.apiUrl, resolveToken, tenant);
                 let envelope;
                 if (command === "integrations") {
                     const target = appRoot(root);
-                    const governance = new GovernanceClient(config.apiUrl, token, tenant);
                     const result = subcommand === "status"
                         ? await integrationsStatus(target, governance)
                         : subcommand === "catalog"
@@ -235,23 +246,32 @@ else {
                         progress(subcommand === "status" ? renderIntegrationsStatus(result) : subcommand === "catalog" ? renderIntegrationsCatalog(result) : renderRequest(result));
                 }
                 else if (command === "deploy") {
-                    // The access requests are filed and the preview lane checked (and the app linked) before any operation starts, so deploy never mints a second app for the same root.
-                    const result = await deploy(root, client, progress, tenant, { waitForDeployment: !noWait, waitOptions, integrations: { governance: new GovernanceClient(config.apiUrl, token, tenant), bundle: EMBEDDED_KIT_BUNDLE }, ...(sessionNotes ? { sessionNotes } : {}) });
+                    const result = await deploy(root, governance, progress, tenant, { waitForDeployment: !noWait, waitOptions, bundle: EMBEDDED_KIT_BUNDLE, ...(sessionNotes ? { sessionNotes } : {}) });
                     envelope = operationEnvelope(result.result, result.operationRef, CLI_VERSION);
                 }
                 else {
+                    // The deployment routes are addressed by the app, so these read its identity
+                    // from the folder (the current one unless --app-root says otherwise) and,
+                    // without --operation, follow the deployment last started from it.
+                    const target = appRoot(root ?? ".");
+                    const appId = (await readKitLock(target))?.appId;
+                    if (!appId)
+                        throw new CliError("KIT_REQUIRED", `${root ? "That folder" : "The current folder"} is not a deployed Isomorph app: it has no .isomorph/kit.lock.json with an app identity.`, undefined, "Run this from the app's folder, or pass --app-root <path>.");
+                    const ref = operationRef ?? (await readDeployNote(target, tenant))?.operationRef;
+                    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;
                     if (command === "status")
-                        summary = wait ? await follow(client, operationRef, progress, waitOptions) : summarize(await fetchStatus(client, operationRef));
+                        summary = wait ? await follow(statusFetch(governance, appId, ref), ref, progress, waitOptions) : summarize(await governance.deploymentStatus(appId, ref));
                     else if (command === "retry")
-                        summary = await retryDeployment(client, operationRef, progress, { wait: !noWait, waitOptions });
+                        summary = await retryDeployment(governance, appId, ref, progress, { wait: !noWait, waitOptions });
                     else {
-                        // Production has its own lane and its own AI mode: with the app root in hand, the same one-call pre-flight runs for production before promoting.
-                        if (root)
-                            await assertDeployReady(appRoot(root), new GovernanceClient(config.apiUrl, token, tenant), tenant, EMBEDDED_KIT_BUNDLE, "production", progress, await appCallsAi(appRoot(root)));
-                        summary = await promoteToProduction(client, operationRef, progress, { wait: !noWait, waitOptions, confirmedTested: confirmTested });
+                        // 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 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, operationRef, CLI_VERSION);
+                    envelope = operationEnvelope(summary, ref, CLI_VERSION);
                 }
                 process.stdout.write(json ? `${JSON.stringify(envelope)}\n` : renderSummary(envelope));
             }