@lotics/cli 0.76.1 → 0.83.0

package/dist/package_commands.js

@@ -1,228 +1,76 @@
 /**
- * `lotics package *` subcommands — the app-package authoring + dev/test/run loop
- * (see docs/packages.md). An app *package* is a versioned, workspace-agnostic
- * blueprint Lotics maintains once and installs into many workspaces. This module
- * implements the full harness:
+ * The package CONSUMER + registry surface (see docs/packages.md). Nothing starts
+ * as a package, and nothing is authored as a local package PROJECT: an app is
+ * first-released with `lotics app publish`, and a content package (a SET of live
+ * knowledge docs + templates) is published with the `publish_content` /
+ * `release_content` tools (`lotics run publish_content …`). This module
+ * implements only what operates published packages + installations:
  *
- *   new      scaffold a package project (contract + app source).
- *   build    build the publishable bundle (source + dist).
- *   publish  create a new immutable package version from the contract + bundle.
- *   dev      scaffold-sync the package into a dev workspace (install/upgrade) and
- *            run the existing app dev server against the resulting installation.
- *   sync     re-run the scaffold-sync (additive migrate + materialize) without dev.
- *   reset    DEV-ONLY, hard-gated: drop the scaffolded tables + re-scaffold clean.
- *   install  materialize a published version into the current workspace.
- *   eject    sever an installation's package link (last rung of customization).
+ *   install / uninstall / upgrade   the high-traffic consumer verbs, dispatched
+ *     from the TOP LEVEL (`lotics install|uninstall|upgrade`). `upgrade` folds in
+ *     the whole-fleet path (a `package_id` upgrades every org installation).
+ *   doctor / eject / config / list-content / yank / show   the low-traffic
+ *     ops, under `lotics package <verb>`. (Re-pointing a live role rides
+ *     `upgrade --resolve roles.<alias>=<grp_id>` — no separate verb.)
  *
- * The dev loop reuses the *published* path end-to-end: `dev`/`sync` build →
- * publish a new version → install (first time) or upgrade (subsequent) into the
- * dev workspace, so the dev installation goes through the exact scaffold +
- * materialize the real install/upgrade run (no parallel dev-only materializer).
- * The local installation pin per dev workspace is recorded in the project
- * manifest so a re-sync upgrades in place.
+ * Author verbs live on `lotics app` (`publish` / `release` / `unpublish`), and the
+ * app-development loop lives entirely in `lotics app *`: pull an installed origin
+ * (`lotics app pull <app_id>`), edit + `lotics app deploy`, then
+ * `lotics app release <app_id>` cuts the next version.
  */
 import fs from "node:fs";
 import path from "node:path";
-import { tmpdir } from "node:os";
-import { createHash } from "node:crypto";
 import "./client.js";
 import { knowledgeEntryNeedsConsent, validKnowledgeResolutions, } from "@lotics/shared/schemas/packages";
-import { buildStarterTemplate, buildPackageStarterOverrides, STARTER_FALLBACK_SDK_VERSION, } from "./starter_template.js";
-import { generatePackageAppFields, } from "./generate_package_fields.js";
-import { appDirName, fetchLatestNpmVersion, runNpm, runTar, writeAppDts } from "./app_commands.js";
-import { writeFileAtomic } from "./file_command_io.js";
-import { startDevServer, openBrowser } from "./dev/server.js";
-const CONTRACT_FILE = "contract.json";
-/**
- * The origin pin `lotics package extract` writes and `lotics package adopt`
- * reads back: `{ app_id, workspace_id, binding }`. Lives under `.lotics/`, which
- * is in `SOURCE_STAGE_EXCLUDES` — so it never rides along in a published bundle.
- */
-const ADOPT_BINDING_FILE = "adopt_binding.json";
-const PACKAGE_TEMPLATE_KINDS = new Set([
-    "html",
-    "email",
-    "excel",
-    "word",
-    "pdf-form",
-]);
 function packageJsonPath(projectDir) {
     return path.join(projectDir, "package.json");
 }
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** Read the package project's manifest, failing loud when the dir isn't one. */
-export function readPackageProject(projectDir) {
+/**
+ * Read the local APP project's manifest (`package.json#lotics.app_id` +
+ * `lotics.knowledge`) — what `lotics app pull` writes. `lotics app publish` /
+ * `release` run from a pulled app project resolve the app id from it, and
+ * `publish` forwards the package-managed knowledge declaration to the server
+ * (agents reference docs by free text, so the author declares which the package
+ * owns). Returns null when the dir has no package.json. `app_id` is null when the
+ * manifest is a package/non-app project.
+ */
+export function readLocalAppManifest(projectDir) {
     const pkgPath = packageJsonPath(projectDir);
-    if (!fs.existsSync(pkgPath)) {
-        throw new Error(`No package.json in ${projectDir}. Run this inside a package project (lotics package new <name>).`);
-    }
+    if (!fs.existsSync(pkgPath))
+        return null;
     const parsed = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
     if (!isPlainObject(parsed))
-        throw new Error(`Malformed package.json in ${projectDir}.`);
-    const lotics = parsed.lotics;
-    const pkg = isPlainObject(lotics) ? lotics.package : undefined;
-    if (!isPlainObject(pkg) || typeof pkg.name !== "string") {
-        throw new Error(`${pkgPath} has no lotics.package manifest — not a package project. Use "lotics package new <name>".`);
-    }
-    const dev = {};
-    if (isPlainObject(pkg.dev)) {
-        for (const [ws, entry] of Object.entries(pkg.dev)) {
-            if (isPlainObject(entry) && typeof entry.app_id === "string" && typeof entry.version === "number") {
-                dev[ws] = { app_id: entry.app_id, version: entry.version };
-            }
-        }
-    }
-    const knowledge = {};
-    if (isPlainObject(pkg.knowledge)) {
-        for (const [alias, entry] of Object.entries(pkg.knowledge)) {
-            if (!isPlainObject(entry) || typeof entry.name !== "string" || entry.name.length === 0) {
-                throw new Error(`${pkgPath}: lotics.package.knowledge.${alias} must be an object with a non-empty "name".`);
-            }
-            knowledge[alias] = {
-                name: entry.name,
-                description: typeof entry.description === "string" ? entry.description : null,
-                active_by_default: typeof entry.active_by_default === "boolean" ? entry.active_by_default : true,
-            };
-        }
-    }
-    const templates = {};
-    if (isPlainObject(pkg.templates)) {
-        for (const [alias, entry] of Object.entries(pkg.templates)) {
-            if (!isPlainObject(entry) ||
-                typeof entry.name !== "string" ||
-                entry.name.length === 0 ||
-                typeof entry.type !== "string" ||
-                !PACKAGE_TEMPLATE_KINDS.has(entry.type) ||
-                typeof entry.file !== "string" ||
-                entry.file.length === 0) {
-                throw new Error(`${pkgPath}: lotics.package.templates.${alias} must be an object with a non-empty "name", ` +
-                    `a "type" of html|email|excel|word|pdf-form, and a non-empty "file" (a name in templates/).`);
+        return null;
+    const lotics = isPlainObject(parsed.lotics) ? parsed.lotics : {};
+    const app_id = typeof lotics.app_id === "string" ? lotics.app_id : null;
+    const knowledge = [];
+    if (Array.isArray(lotics.knowledge)) {
+        for (const entry of lotics.knowledge) {
+            if (isPlainObject(entry) && typeof entry.alias === "string" && typeof entry.doc_id === "string") {
+                knowledge.push({ alias: entry.alias, doc_id: entry.doc_id });
             }
-            templates[alias] = {
-                name: entry.name,
-                type: entry.type,
-                file: entry.file,
-            };
         }
     }
-    const knowledge_expects = Array.isArray(pkg.knowledge_expects)
-        ? pkg.knowledge_expects.filter((v) => typeof v === "string")
-        : [];
-    const manifest = {
-        id: typeof pkg.id === "string" ? pkg.id : null,
-        name: pkg.name,
-        description: typeof pkg.description === "string" ? pkg.description : null,
-        kind: pkg.kind === "content" ? "content" : "app",
-        version: typeof pkg.version === "number" ? pkg.version : null,
-        knowledge,
-        templates,
-        knowledge_expects,
-        dev,
-    };
-    return { pkgJson: parsed, manifest };
-}
-/** Persist an updated manifest back into the project's package.json (atomic write). */
-export function writePackageManifest(projectDir, project) {
-    const next = {
-        ...project.pkgJson,
-        lotics: {
-            ...(isPlainObject(project.pkgJson.lotics) ? project.pkgJson.lotics : {}),
-            package: project.manifest,
-        },
-    };
-    // Atomic write: a torn plain write could corrupt package.json and lose the
-    // stamped registry `package_id` — which would orphan the published package
-    // and create a duplicate on the next publish retry.
-    writeFileAtomic(packageJsonPath(projectDir), new TextEncoder().encode(JSON.stringify(next, null, 2) + "\n"));
-}
-/**
- * The package.json to ship INSIDE `source.tar.gz`: the on-disk manifest with the
- * author-local `lotics.package.dev` map stripped. `dev` is the author's private
- * dev-workspace → installation bookkeeping; it must never reach a consumer (every
- * install carries the source, and `lotics app pull` ejects it). Returns a
- * sanitized copy — the on-disk package.json is left untouched. `id`/`name`/
- * `description`/`version` are the package's stable identity and stay.
- */
-export function sanitizePackageJsonForSource(pkgJson) {
-    const lotics = isPlainObject(pkgJson.lotics) ? pkgJson.lotics : {};
-    const pkg = isPlainObject(lotics.package) ? lotics.package : {};
-    const { dev: _dev, ...pkgWithoutDev } = pkg;
-    return {
-        ...pkgJson,
-        lotics: { ...lotics, package: pkgWithoutDev },
-    };
+    return { app_id, knowledge };
 }
-/**
- * Transform an app project's package.json (the source archive `lotics app pull`
- * downloads, carrying the `lotics.app_id`/`workspace_id` app manifest) into a
- * package project's `PackageProjectFile`: the app manifest is stripped ENTIRELY
- * and a fresh, unpublished `lotics.package` manifest (id/version null) is
- * grafted. Pure — returns a new value, never mutates the input;
- * `writePackageManifest` writes it (atomic). The bespoke→package promotion's
- * manifest inversion.
- */
-export function draftPackageProjectFromApp(appPkgJson, args) {
-    const { lotics: _appManifest, ...rest } = appPkgJson;
-    return {
-        pkgJson: rest,
-        manifest: {
-            id: null,
-            name: args.name,
-            description: args.description,
-            // Extraction promotes a bespoke APP to a package — always app kind.
-            kind: "app",
-            version: null,
-            knowledge: {},
-            templates: {},
-            knowledge_expects: [],
-            dev: {},
-        },
-    };
-}
-/**
- * Parse + validate `.lotics/adopt_binding.json` against the app being adopted.
- * REFUSES a pin recorded for a different app: a binding maps ONE workspace's
- * concrete ids, so replaying it onto another app would bind the wrong objects.
- * Pure; the CLI never interprets the binding, only round-trips it to the server.
- */
-export function parseAdoptBindingFile(raw, expectedAppId) {
-    if (!isPlainObject(raw) ||
-        typeof raw.app_id !== "string" ||
-        typeof raw.workspace_id !== "string" ||
-        !isPlainObject(raw.binding)) {
-        throw new Error("Malformed .lotics/adopt_binding.json — expected { app_id, workspace_id, binding }.");
-    }
-    if (raw.app_id !== expectedAppId) {
-        throw new Error(`.lotics/adopt_binding.json records app ${raw.app_id}, but you are adopting ${expectedAppId}. ` +
-            `A binding maps one app's concrete ids and must never be applied to another — ` +
-            `run "lotics package extract ${expectedAppId}" to produce the right pin.`);
-    }
-    // Boundary adapter: the file is untyped JSON; `isPlainObject` proved the shape
-    // and the CLI passes the maps straight to the server (the validating authority).
-    // `knowledge_binding` is optional (absent for a pre-knowledge extract / an app
-    // with no package-managed docs) → defaults to {}.
-    const knowledge_binding = {};
-    if (isPlainObject(raw.knowledge_binding)) {
-        for (const [alias, id] of Object.entries(raw.knowledge_binding)) {
-            if (typeof id === "string")
-                knowledge_binding[alias] = id;
+/** Parse repeated `--rename old=new` flags into `{ from, to }[]` (first-publish alias fixes). */
+export function parseRenameFlags(renames) {
+    return renames.map((entry) => {
+        const eq = entry.indexOf("=");
+        if (eq <= 0 || eq === entry.length - 1) {
+            throw new Error(`Invalid --rename "${entry}" — expected old=new (an alias to rename before v1 freezes it).`);
         }
-    }
-    return {
-        app_id: raw.app_id,
-        workspace_id: raw.workspace_id,
-        binding: raw.binding,
-        knowledge_binding,
-    };
+        return { from: entry.slice(0, eq), to: entry.slice(eq + 1) };
+    });
 }
 /**
- * Render an extraction report grouped by severity (errors, then warnings, then
- * info), one `  [<severity>] <area>: <message>` line each, and classify whether
- * any `error` finding is present. An `error` ⇒ the draft is not publishable
- * as-is, so `lotics package extract` exits non-zero. Pure — the command prints
- * `lines` to stderr and gates on `hasError`.
+ * Render a package-extract report grouped by severity (errors, then warnings,
+ * then info), one `  [<severity>] <area>: <message>` line each, and classify
+ * whether any `error` finding is present. Shared by the release preview display.
+ * Pure — the command prints `lines` to stderr and gates on `hasError`.
  */
 export function formatExtractReport(report) {
     const order = ["error", "warning", "info"];
@@ -231,737 +79,37 @@ export function formatExtractReport(report) {
         .map((f) => `  [${f.severity}] ${f.area}: ${f.message}`));
     return { lines, hasError: report.some((f) => f.severity === "error") };
 }
-function dotLoticsDirEnsured(projectDir) {
-    const dir = path.join(projectDir, ".lotics");
-    fs.mkdirSync(dir, { recursive: true });
-    return dir;
-}
-/** Numeric "x.y.z" compare — no semver dep (the CLI has zero runtime deps). */
-function cmpVersions(a, b) {
-    const pa = a.split(".").map(Number);
-    const pb = b.split(".").map(Number);
-    for (let i = 0; i < 3; i++) {
-        const d = (pa[i] || 0) - (pb[i] || 0);
-        if (d !== 0)
-            return d;
-    }
-    return 0;
-}
 /**
- * The `@lotics/app-sdk` range a package project needs: the live npm latest,
- * clamped to never fall below `STARTER_FALLBACK_SDK_VERSION` — the release
- * that ships `getAppBinding`, which the generated `.lotics/app_fields.ts`
- * imports. A `^0.x` caret range never crosses a minor, so pinning below the
- * floor (offline, or npm not yet carrying the release) would permanently
- * scaffold projects that cannot compile their own generated code.
+ * Resolve the installation to operate on: an explicit app id is required (there
+ * is no dev-workspace pin to fall back to).
  */
-function packageSdkRange(sdkLatest) {
-    const version = sdkLatest !== null && cmpVersions(sdkLatest, STARTER_FALLBACK_SDK_VERSION) > 0
-        ? sdkLatest
-        : STARTER_FALLBACK_SDK_VERSION;
-    return `^${version}`;
-}
-/** Read + JSON-parse the project's contract.json (the alias-keyed declaration). */
-function readContract(projectDir) {
-    const contractPath = path.join(projectDir, CONTRACT_FILE);
-    if (!fs.existsSync(contractPath)) {
-        throw new Error(`No ${CONTRACT_FILE} in ${projectDir}. A package project declares its data model there.`);
-    }
-    return JSON.parse(fs.readFileSync(contractPath, "utf-8"));
-}
-/**
- * Fold a package project's knowledge corpus into its contract before publish:
- * per `lotics.package.knowledge` alias, read `knowledge/<alias>.md`, sha256 the
- * bytes, and emit the contract's `knowledge` namespace (alias → {name,
- * description, content_ref, content_sha256, active_by_default}) +
- * `knowledge_expects` (from `lotics.package.knowledge_expects`). This is the ONE
- * place the sha is computed — it can't be hand-authored, which is why knowledge
- * (unlike a template `bytes_ref`) is derived rather than written into
- * contract.json. The content files themselves ride in `source.tar.gz`
- * automatically: `knowledge/` is a top-level dir, so `stagePackageSource` copies
- * it like any other source (the same mechanism that carries template bytes). Pure
- * w.r.t. `contract` — returns a new object; the server re-validates the folded
- * namespace at publish.
- */
-export function foldKnowledgeIntoContract(projectDir, project, contract) {
-    const aliases = Object.keys(project.manifest.knowledge);
-    const expects = project.manifest.knowledge_expects;
-    if (aliases.length === 0 && expects.length === 0)
-        return contract;
-    const knowledge = {};
-    for (const alias of aliases) {
-        const entry = project.manifest.knowledge[alias];
-        const contentRef = `knowledge/${alias}.md`;
-        const filePath = path.join(projectDir, "knowledge", `${alias}.md`);
-        if (!fs.existsSync(filePath)) {
-            throw new Error(`Declared knowledge doc "${alias}" (lotics.package.knowledge) has no ${contentRef} in the project. ` +
-                `Create the file, or remove the manifest entry.`);
-        }
-        const bytes = fs.readFileSync(filePath);
-        knowledge[alias] = {
-            name: entry.name,
-            description: entry.description ?? "",
-            content_ref: contentRef,
-            content_sha256: createHash("sha256").update(bytes).digest("hex"),
-            active_by_default: entry.active_by_default,
-        };
-    }
-    return { ...contract, knowledge, knowledge_expects: expects };
-}
-/**
- * Fold a CONTENT package's manifest-declared templates into its contract before
- * publish: per `lotics.package.templates` alias, an INLINE kind (html/email) reads
- * `templates/<file>` into the contract template's `content`; a FILE-BACKED kind
- * (excel/word/pdf-form) records `bytes_ref: templates/<file>` (the bytes ride in
- * `source.tar.gz` — `templates/` is a top-level dir `stagePackageSource` copies,
- * the same mechanism that carries knowledge content + app-package template bytes).
- * The per-template `content_sha256` is NOT computed here — `foldTemplateShasIntoContract`
- * runs after and derives it (inline: the utf-8 content; file-backed: the file bytes).
- *
- * Appends to any templates the contract already declares (an app package authors
- * templates in `contract.json` directly; the manifest path is how a content
- * package — with no `contract.json` templates — declares them). An alias in BOTH
- * is a loud error. Pure w.r.t. `contract` — returns a new object.
- */
-export function foldTemplatesIntoContract(projectDir, project, contract) {
-    if (!isPlainObject(contract)) {
-        throw new Error(`${CONTRACT_FILE} in ${projectDir} must be a JSON object.`);
-    }
-    const aliases = Object.keys(project.manifest.templates);
-    if (aliases.length === 0)
-        return contract;
-    const existing = Array.isArray(contract.templates) ? contract.templates : [];
-    const existingAliases = new Set(existing
-        .filter((t) => isPlainObject(t))
-        .map((t) => t.alias)
-        .filter((a) => typeof a === "string"));
-    const folded = aliases.map((alias) => {
-        if (existingAliases.has(alias)) {
-            throw new Error(`Template alias "${alias}" is declared in both lotics.package.templates and ${CONTRACT_FILE} — ` +
-                `declare each template once.`);
-        }
-        const entry = project.manifest.templates[alias];
-        const filePath = path.join(projectDir, "templates", entry.file);
-        if (!fs.existsSync(filePath)) {
-            throw new Error(`Declared template "${alias}" (lotics.package.templates) has no templates/${entry.file} in the project. ` +
-                `Stage the file, then rebuild.`);
-        }
-        if (entry.type === "html" || entry.type === "email") {
-            return { alias, label: entry.name, type: entry.type, content: fs.readFileSync(filePath, "utf-8") };
-        }
-        return { alias, label: entry.name, type: entry.type, bytes_ref: `templates/${entry.file}` };
-    });
-    return { ...contract, templates: [...existing, ...folded] };
-}
-/**
- * Fold a freshly-computed `content_sha256` into every template of a package
- * contract before publish — the modified-detection reference the install/upgrade
- * flow compares live content against. Like knowledge's sha (foldKnowledge…), it
- * can't be hand-authored: an INLINE template's sha covers its utf-8 `content`; a
- * FILE-BACKED template's sha covers the `bytes_ref` file's bytes (the same bytes
- * that ride in `source.tar.gz` and install stores verbatim). Always recomputed
- * (never trusted from contract.json), so the published contract's sha is exact.
- * Pure w.r.t. `contract` — returns a new object; the server re-validates.
- */
-export function foldTemplateShasIntoContract(projectDir, contract) {
-    const templates = contract.templates;
-    if (!Array.isArray(templates) || templates.length === 0)
-        return contract;
-    const withShas = templates.map((template) => {
-        if (!isPlainObject(template) ||
-            typeof template.type !== "string" ||
-            typeof template.alias !== "string") {
-            // Malformed — leave as-is; the server's contract validator rejects it.
-            return template;
-        }
-        if (template.type === "html" || template.type === "email") {
-            if (typeof template.content !== "string") {
-                throw new Error(`Inline template "${template.alias}" must carry a string "content".`);
-            }
-            return {
-                ...template,
-                content_sha256: createHash("sha256").update(Buffer.from(template.content, "utf-8")).digest("hex"),
-            };
-        }
-        if (typeof template.bytes_ref !== "string") {
-            throw new Error(`File-backed template "${template.alias}" must carry a string "bytes_ref".`);
-        }
-        const filePath = path.join(projectDir, template.bytes_ref);
-        if (!fs.existsSync(filePath)) {
-            throw new Error(`Template "${template.alias}" references "${template.bytes_ref}", which is not in the project. ` +
-                `Stage the file, then rebuild.`);
-        }
-        const bytes = fs.readFileSync(filePath);
-        return { ...template, content_sha256: createHash("sha256").update(bytes).digest("hex") };
-    });
-    return { ...contract, templates: withShas };
-}
-/**
- * (Re)generate the package project's `.lotics/app_fields.ts` from its
- * contract.json — the runtime-resolving F/OPT/ROLE surface (see
- * `generate_package_fields.ts`). Runs on new/extract and on every dev/sync so
- * contract edits keep the aliases addressable. `.lotics` is in
- * SOURCE_STAGE_EXCLUDES: the compiled module ships inside `dist/`, and a
- * post-eject `lotics app pull` regenerates the bespoke (baked) variant.
- */
-function writePackageAppFields(projectDir) {
-    const contract = readContract(projectDir);
-    const dotLotics = path.join(projectDir, ".lotics");
-    fs.mkdirSync(dotLotics, { recursive: true });
-    fs.writeFileSync(path.join(dotLotics, "app_fields.ts"), generatePackageAppFields(contract));
-    console.error("Wrote .lotics/app_fields.ts (contract-derived, runtime-resolved)");
-}
-/** Top-level project entries that never ship in the source archive. */
-const SOURCE_STAGE_EXCLUDES = new Set([
-    "node_modules",
-    "dist",
-    ".lotics",
-    ".git",
-    "bundle.tar.gz",
-    "package.json",
-]);
-/**
- * Copy the project's source tree into `sourceStage` with explicit TOP-LEVEL
- * excludes, writing a sanitized `package.json` in place of the on-disk one.
- * Deliberately not tar `--exclude` flags: those match at any depth (a nested
- * `templates/dist/` would be silently dropped) and GNU tar vs bsdtar (macOS)
- * disagree on `./`-prefixed patterns, which broke the sanitized-package.json
- * graft on macOS.
- */
-export function stagePackageSource(projectDir, sourceStage) {
-    const project = readPackageProject(projectDir);
-    fs.mkdirSync(sourceStage, { recursive: true });
-    for (const entry of fs.readdirSync(projectDir)) {
-        if (SOURCE_STAGE_EXCLUDES.has(entry) || entry.endsWith(".tsbuildinfo"))
-            continue;
-        fs.cpSync(path.join(projectDir, entry), path.join(sourceStage, entry), { recursive: true });
-    }
-    fs.writeFileSync(path.join(sourceStage, "package.json"), JSON.stringify(sanitizePackageJsonForSource(project.pkgJson), null, 2) + "\n");
-}
-/**
- * Build the publishable bundle: a gzipped tarball carrying `source.tar.gz` (the
- * pullable project tree) + `dist.tar.gz` (the prebuilt assets) as its two
- * top-level members — the publish↔install contract the backend's
- * `extractPackageBundle` reads (both members are required). Returns the bytes.
- *
- * An `app` package compiles its frontend (`npm run build` → `dist/`). A
- * `content` package has NO app source to compile, so the build is skipped and a
- * minimal placeholder `dist.tar.gz` is shipped: the bundle format requires the
- * member, but a content install never deploys a frontend (it only reads the
- * `knowledge/*.md` files from `source.tar.gz`), so nothing ever reads it.
- */
-async function buildPackageBundle(projectDir) {
-    const { manifest } = readPackageProject(projectDir);
-    // Stage the two member archives in a temp dir, then tar them into the bundle.
-    const stage = fs.mkdtempSync(path.join(tmpdir(), "lotics-pkg-"));
-    const bundlePath = path.join(tmpdir(), `lotics-bundle-${Date.now()}.tar.gz`);
-    try {
-        let distDir;
-        if (manifest.kind === "content") {
-            console.error("Content package — skipping app build.");
-            distDir = path.join(stage, "empty-dist");
-            fs.mkdirSync(distDir, { recursive: true });
-            fs.writeFileSync(path.join(distDir, ".content-package"), "Content package — no frontend bundle. Content ships in source.tar.gz under knowledge/.\n");
-        }
-        else {
-            console.error("Building...");
-            await runNpm(["run", "build"], projectDir);
-            distDir = path.join(projectDir, "dist");
-            if (!fs.existsSync(distDir)) {
-                throw new Error(`Build did not produce a dist/ directory in ${projectDir}. ` +
-                    `Check that 'npm run build' is configured correctly.`);
-            }
-        }
-        console.error("Packaging source...");
-        // Stage a copy of the source tree with EXPLICIT top-level excludes, then
-        // tar the stage with no --exclude flags at all. tar exclude patterns are
-        // the wrong tool twice over: they match at ANY depth (a nested
-        // `templates/dist/` would be silently dropped from the bundle), and GNU
-        // tar vs bsdtar (macOS) disagree on whether `./package.json` and
-        // `package.json` are the same pattern — bsdtar strips the leading `./`,
-        // which would also exclude the sanitized package.json grafted below.
-        //
-        // The on-disk package.json carries the author-local `lotics.package.dev`
-        // map; the stage gets a sanitized copy in its place, so that bookkeeping
-        // never ships to a consumer nor lands in an `lotics app pull` eject.
-        const sourceStage = path.join(stage, "source");
-        stagePackageSource(projectDir, sourceStage);
-        await runTar(["-czf", path.join(stage, "source.tar.gz"), "-C", sourceStage, "."], projectDir);
-        console.error("Packaging dist...");
-        await runTar(["-czf", path.join(stage, "dist.tar.gz"), "-C", distDir, "."], projectDir);
-        console.error("Bundling...");
-        await runTar(["-czf", bundlePath, "source.tar.gz", "dist.tar.gz"], stage);
-        return fs.readFileSync(bundlePath);
-    }
-    finally {
-        fs.rmSync(stage, { recursive: true, force: true });
-        if (fs.existsSync(bundlePath))
-            fs.unlinkSync(bundlePath);
-    }
-}
-/** The minimal, valid starting contract a `package new` scaffold ships. */
-export function starterContract(name) {
-    return {
-        entities: [
-            {
-                alias: "item",
-                label: name,
-                description: `Records managed by the ${name} package.`,
-                fields: [
-                    { alias: "name", label: "Name", type: "text", required: true },
-                    { alias: "notes", label: "Notes", type: "text" },
-                    {
-                        alias: "status",
-                        label: "Status",
-                        type: "select",
-                        options: [
-                            { alias: "open", label: "Open", color: "blue" },
-                            { alias: "done", label: "Done", color: "green" },
-                        ],
-                    },
-                ],
-            },
-        ],
-        roles: [],
-        templates: [],
-        queries: [
-            {
-                alias: "items",
-                ast: {
-                    kind: "from_table",
-                    from_entity: "item",
-                    sort: [{ field_key: "name", order: "asc" }],
-                },
-            },
-        ],
-        workflows: [],
-        agents: [],
-        config: [
-            { alias: "heading", label: "List heading", type: "text", default: name },
-        ],
-    };
-}
-/** An empty contract — all app namespaces empty (knowledge is folded in at build). */
-function emptyContract() {
-    return {
-        entities: [],
-        roles: [],
-        templates: [],
-        queries: [],
-        workflows: [],
-        agents: [],
-        config: [],
-    };
-}
-/**
- * Scaffold a CONTENT package project — a standalone doc corpus, NO app source.
- * Just a `lotics.package` manifest (kind: "content"), an empty base
- * `contract.json` (the app namespaces MUST stay empty for a content package;
- * `build` folds the docs into the `knowledge` namespace), and a `knowledge/` dir
- * with one example doc wired into the manifest so the scaffold is immediately
- * publishable (publish refuses a content package with zero docs). No npm
- * install — a content package has no dependencies to compile.
- */
-function scaffoldContentPackage(name, targetPath) {
-    const exampleAlias = "overview";
-    const manifest = {
-        id: null,
-        name,
-        description: null,
-        kind: "content",
-        version: null,
-        knowledge: {
-            [exampleAlias]: {
-                name: `${name} Overview`,
-                description: "What this corpus covers — replace with your doc's summary.",
-                active_by_default: true,
-            },
-        },
-        // A content package can also ship standalone document templates — declare them
-        // under `lotics.package.templates` with the files in a `templates/` dir. See
-        // the commented example printed by the scaffold + docs/packages.md § Content.
-        templates: {},
-        knowledge_expects: [],
-        dev: {},
-    };
-    const pkgJson = {
-        name: appDirName(name),
-        private: true,
-        version: "0.0.0",
-        lotics: { package: manifest },
-    };
-    fs.writeFileSync(packageJsonPath(targetPath), JSON.stringify(pkgJson, null, 2) + "\n");
-    fs.writeFileSync(path.join(targetPath, CONTRACT_FILE), JSON.stringify(emptyContract(), null, 2) + "\n");
-    const knowledgeDir = path.join(targetPath, "knowledge");
-    fs.mkdirSync(knowledgeDir, { recursive: true });
-    fs.writeFileSync(path.join(knowledgeDir, `${exampleAlias}.md`), `# ${name}\n\nReplace this file with the corpus content. Structure it under clear\n` +
-        `Markdown headers so an agent can outline and read it by section.\n`);
-    console.error(`Scaffolded a content package into ${targetPath}`);
-    console.error(`\nReady. Next steps:`);
-    console.error(`  cd ${path.relative(process.cwd(), targetPath) || "."}`);
-    console.error(`  # add docs: create knowledge/<alias>.md + a lotics.package.knowledge.<alias> entry`);
-    console.error(`  #           (name/description/active_by_default), then publish:`);
-    console.error(`  # add templates: create templates/<file> + a lotics.package.templates.<alias> entry:`);
-    console.error(`  #   "templates": { "quote": { "name": "Quote", "type": "html", "file": "quote.html" } }`);
-    console.error(`  #   inline kinds html|email read templates/<file> as content; file-backed`);
-    console.error(`  #   excel|word|pdf-form pack the bytes into the bundle (bytes_ref = templates/<file>).`);
-    console.error(`  lotics package publish -m "v1"`);
-    console.error(`  lotics package install <package_id>`);
-}
-/**
- * `lotics package new <name> [path] [--kind content]` — scaffold a package
- * project. An `app` package reuses the app starter (Vite+React+TS) for the code
- * surface, swaps its app manifest for a package manifest, and adds a starter
- * `contract.json`; a `content` package scaffolds a docs-only corpus (no app
- * source). The project publishes with `lotics package publish`.
- */
-export async function packageNew(args) {
-    const targetPath = path.resolve(args.targetPath ?? appDirName(args.name));
-    if (fs.existsSync(targetPath) && fs.readdirSync(targetPath).length > 0) {
-        throw new Error(`Target directory ${targetPath} is not empty.`);
-    }
-    fs.mkdirSync(targetPath, { recursive: true });
-    if ((args.kind ?? "app") === "content") {
-        scaffoldContentPackage(args.name, targetPath);
-        return;
-    }
-    // The starter bakes an app manifest (app_id/workspace_id) into package.json;
-    // a package is workspace-agnostic, so those placeholders are replaced with the
-    // package manifest below. The rest of the starter (config, src, tests) is the
-    // package's code surface verbatim.
-    // Resolve the live @lotics/ui + @lotics/app-sdk versions like `app create`
-    // does — the generated .lotics/app_fields.ts imports `getAppBinding`, and a
-    // ^0.x caret range never crosses a minor, so a stale starter fallback would
-    // permanently pin the project below the API it needs (offline still works
-    // off STARTER_FALLBACK_*, kept ≥ that floor).
-    const [uiLatest, sdkLatest] = await Promise.all([
-        fetchLatestNpmVersion("@lotics/ui"),
-        fetchLatestNpmVersion("@lotics/app-sdk"),
-    ]);
-    const files = buildStarterTemplate({
-        app_name: args.name,
-        app_id: "",
-        workspace_id: "",
-        ui_version: uiLatest ? `^${uiLatest}` : undefined,
-        sdk_version: packageSdkRange(sdkLatest),
-    });
-    // Package-specific code surface swapped in BY PATH (same mechanism as the
-    // package.json manifest swap below): the shared app starter's App.tsx demos
-    // in-app routing over static data, wrong for a package. The package starter's
-    // App.tsx exercises the binding (F/OPT + useQuery/useConfig), its test mocks the
-    // SDK boundary, and its README carries the contract reference.
-    const overrides = new Map(buildPackageStarterOverrides({ app_name: args.name }).map((f) => [f.path, f.content]));
-    for (const file of files) {
-        const fullPath = path.join(targetPath, file.path);
-        if (file.path === "package.json") {
-            const pkg = JSON.parse(file.content);
-            const manifest = {
-                id: null,
-                name: args.name,
-                description: null,
-                kind: "app",
-                version: null,
-                knowledge: {},
-                templates: {},
-                knowledge_expects: [],
-                dev: {},
-            };
-            pkg.lotics = { package: manifest };
-            fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-            fs.writeFileSync(fullPath, JSON.stringify(pkg, null, 2) + "\n");
-            continue;
-        }
-        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-        fs.writeFileSync(fullPath, overrides.get(file.path) ?? file.content);
-    }
-    fs.writeFileSync(path.join(targetPath, CONTRACT_FILE), JSON.stringify(starterContract(args.name), null, 2) + "\n");
-    writePackageAppFields(targetPath);
-    console.error(`Scaffolded ${files.length + 1} files into ${targetPath}`);
-    console.error("Installing npm dependencies...");
-    await runNpm(["install"], targetPath);
-    console.error(`\nReady. Next steps:`);
-    console.error(`  cd ${path.relative(process.cwd(), targetPath) || "."}`);
-    console.error(`  # edit contract.json + src/App.tsx, then run it against a dev workspace:`);
-    console.error(`  lotics workspace create "<name> dev" --dev`);
-    console.error(`  lotics package dev --workspace <dev_ws>`);
-}
-/**
- * `lotics package build [path]` — build the publishable bundle and write it to
- * `bundle.tar.gz` in the project. Mostly a local sanity check / CI artifact;
- * `publish` and `dev`/`sync` build the bundle in memory directly.
- */
-export async function packageBuild(args) {
-    const projectDir = path.resolve(args.projectDir ?? process.cwd());
-    readPackageProject(projectDir); // assert it's a package project
-    const bundle = await buildPackageBundle(projectDir);
-    const out = path.join(projectDir, "bundle.tar.gz");
-    fs.writeFileSync(out, bundle);
-    console.error(`Built ${out} (${(bundle.byteLength / 1024).toFixed(1)} KB)`);
-}
-/**
- * Build + publish a new immutable package version from the project's contract +
- * bundle. Creates the registry package on first publish (stamping its id into
- * the manifest), then publishes the next monotonic version. Returns the new
- * version number and the resolved package id.
- */
-async function publishVersion(client, projectDir, opts) {
-    const project = readPackageProject(projectDir);
-    const rawContract = readContract(projectDir);
-    if (!isPlainObject(rawContract)) {
-        throw new Error(`${CONTRACT_FILE} in ${projectDir} must be a JSON object.`);
-    }
-    // Fold the manifest-declared templates + the knowledge corpus + the per-template
-    // content shas into the contract before it is sent. Order: manifest templates
-    // FIRST (so their bytes/content land in the contract), then knowledge, then the
-    // sha fold LAST (it hashes whatever templates now exist — manifest-folded +
-    // contract-authored). All shas are derived (never hand-authored) so the
-    // published contract's modified-detection references are exact.
-    const contract = foldTemplateShasIntoContract(projectDir, foldKnowledgeIntoContract(projectDir, project, foldTemplatesIntoContract(projectDir, project, rawContract)));
-    let packageId = project.manifest.id;
-    if (packageId === null) {
-        const pkg = await client.createPackage({
-            name: project.manifest.name,
-            description: project.manifest.description,
-            // Kind is fixed at package creation and immutable after — a knowledge
-            // package must be created as such so publish enforces its constraint.
-            kind: project.manifest.kind,
-        });
-        packageId = pkg.id;
-        project.manifest.id = packageId;
-        writePackageManifest(projectDir, project);
-        console.error(`Created package ${pkg.name} (${pkg.id}).`);
-    }
-    const bundle = await buildPackageBundle(projectDir);
-    console.error("Publishing version...");
-    const version = await client.publishPackageVersion(packageId, {
-        contract,
-        bundle,
-        changelog: opts.changelog ?? null,
-        channel: opts.channel ?? "release",
-    });
-    project.manifest.version = version.version;
-    writePackageManifest(projectDir, project);
-    return { package_id: packageId, version: version.version };
-}
-/**
- * `lotics package publish [path] [-m <changelog>]` — publish a new version.
- */
-export async function packagePublish(client, args) {
-    const projectDir = path.resolve(args.projectDir ?? process.cwd());
-    const { package_id, version } = await publishVersion(client, projectDir, {
-        changelog: args.changelog,
-    });
-    console.error(`Published ${package_id} v${version}.`);
-    console.error(`  Install it:  lotics package install ${package_id} --version ${version}`);
-}
-/**
- * Fail loud unless `workspace` is a throwaway dev workspace. The dev/sync
- * scaffold path publishes a new version and scaffold-installs package tables into
- * the resolved workspace, so the target MUST be a dev workspace — this mirrors
- * the server-side `package reset` gate so a forgotten `--workspace` (prod
- * selected) can never scaffold package tables into prod. Fails closed: an absent
- * `is_dev` (a server that doesn't yet serialize it) is treated as non-dev.
- */
-export function assertDevWorkspace(workspace) {
-    if (workspace.is_dev === true)
-        return;
-    throw new Error(`Workspace "${workspace.name}" (${workspace.id}) is not a dev workspace. ` +
-        `"lotics package dev"/"sync" scaffold package tables into the target workspace, so it must be a throwaway dev workspace. ` +
-        `Create one with "lotics workspace create <name> --dev" and pass --workspace <dev_ws>.`);
-}
-/**
- * Scaffold-sync the local package into the dev workspace: publish the current
- * contract + bundle as a new version, then install it (first time) or upgrade
- * the recorded installation (subsequent runs) so the dev workspace goes through
- * the exact scaffold + materialize the real install/upgrade run. Records the
- * installation pin per dev workspace in the manifest. Returns the dev
- * installation's app id + name.
- */
-async function syncToDevWorkspace(client, projectDir) {
-    const devWorkspaceId = client.getWorkspaceId();
-    if (!devWorkspaceId) {
-        throw new Error("No dev workspace selected. Pass --workspace <dev_ws> (a workspace created with --dev).");
-    }
-    // Guard BEFORE publishing: dev/sync scaffold-installs package tables into the
-    // resolved workspace, so it must be a throwaway dev workspace — a developer who
-    // forgot --workspace with prod selected would otherwise scaffold into prod.
-    // Mirrors the server-side `package reset` gate (which refuses any non-`is_dev`
-    // workspace).
-    const workspace = await client.getWorkspaceInfo(devWorkspaceId);
-    if (!workspace) {
-        throw new Error(`Workspace ${devWorkspaceId} is not accessible with these credentials. Pass --workspace <dev_ws> (a workspace created with --dev).`);
-    }
-    assertDevWorkspace(workspace);
-    // Contract may have been edited since the last sync — regenerate the
-    // runtime F/OPT/ROLE surface before the build that publishVersion runs.
-    writePackageAppFields(projectDir);
-    // 'dev' channel: a real immutable version this dev installation pins by
-    // number, but never what "install latest" resolves to — a broken
-    // mid-iteration contract must not become the org-wide installable default.
-    const { package_id, version } = await publishVersion(client, projectDir, {
-        changelog: "dev sync",
-        channel: "dev",
-    });
-    // Re-read after publish (publishVersion may have stamped the package id).
-    const project = readPackageProject(projectDir);
-    const existing = project.manifest.dev[devWorkspaceId];
-    let appId;
-    if (existing) {
-        console.error(`Upgrading dev installation ${existing.app_id} → v${version}...`);
-        const app = await client.upgradePackage(existing.app_id, { version });
-        appId = app.id;
-    }
-    else {
-        console.error(`Installing ${package_id} v${version} into dev workspace ${devWorkspaceId}...`);
-        const result = await client.installPackage(package_id, { version });
-        // The dev/sync loop scaffolds an APP installation to run the dev server
-        // against; a content package has no app to run.
-        if (result.kind !== "app") {
-            throw new Error(`Package ${package_id} is a content package — "lotics package dev/sync" run an app installation. ` +
-                `Install a content package with "lotics package install ${package_id}".`);
-        }
-        appId = result.app.id;
-    }
-    project.manifest.dev[devWorkspaceId] = { app_id: appId, version };
-    writePackageManifest(projectDir, project);
-    const installed = await client.getApp(appId);
-    // Regenerate the typed `.lotics/app_{queries,workflows,agents}.d.ts` companions
-    // from the live installation — the SAME maps (`apps.queries`/`workflows`/`agents`,
-    // keyed by the contract's runtime aliases) `lotics app pull` codegens from — so
-    // `useQuery("items")` / `useWorkflow` are typed in the package dev loop, not just
-    // in pulled app projects. (`.lotics/app_fields.ts`, the runtime F/OPT surface, was
-    // already refreshed from the contract before publish.) `writeAppDts` also heals the
-    // tsconfig include/exclude so the generated `.d.ts` actually load.
-    writeAppDts(projectDir, {
-        workflows: installed.workflows ?? undefined,
-        queries: installed.queries ?? undefined,
-        agents: installed.agents ?? undefined,
-    });
-    return { app_id: appId, app_name: installed.name, workspace_id: devWorkspaceId, version };
-}
-/**
- * `lotics package sync [path]` — re-run the scaffold-sync into the dev workspace
- * (the continuous loop: edit contract → sync additively migrates + re-materializes).
- */
-export async function packageSync(client, args) {
-    const projectDir = path.resolve(args.projectDir ?? process.cwd());
-    const result = await syncToDevWorkspace(client, projectDir);
-    console.error(`Synced ${result.app_name} v${result.version} → ${result.app_id} (workspace ${result.workspace_id}).`);
-}
-/**
- * `lotics package dev [path] [--workspace <dev_ws>] [--view-as <member>]` —
- * scaffold-sync the package into the dev workspace, then run the existing app
- * dev server against the resulting installation (HMR over the local source, RPC
- * forwarded to the live installation). The inner loop: edit contract → re-run to
- * sync; edit code → hot reload.
- */
-export async function packageDev(client, args) {
-    const projectDir = path.resolve(args.projectDir ?? process.cwd());
-    const synced = await syncToDevWorkspace(client, projectDir);
-    const handle = await startDevServer({
-        projectDir,
-        app_id: synced.app_id,
-        app_name: synced.app_name,
-        workspace_id: synced.workspace_id,
-        api_url: client.baseUrl,
-        port: args.port,
-        vitePort: args.vitePort,
-        client,
-    });
-    await handle.ready;
-    const url = `http://localhost:${handle.port}`;
-    console.error(`\n  lotics package dev`);
-    console.error(`  package:   ${synced.app_name} (dev installation ${synced.app_id} v${synced.version})`);
-    console.error(`  workspace: ${synced.workspace_id} (dev)`);
-    if (client.viewAsMemberId) {
-        console.error(`  view as:   ${client.viewAsMemberId}`);
-    }
-    console.error(`  vite:      http://localhost:${handle.vitePort}/`);
-    console.error(`  open:      ${url}`);
-    console.error(`  rpc:       ${client.baseUrl} (via Bearer API key)\n`);
-    console.error(`  Edit contract.json then re-run "lotics package dev" / "lotics package sync" to migrate.`);
-    console.error(`  Ctrl-C to stop.\n`);
-    openBrowser(url);
-    await new Promise((resolve) => {
-        const onSig = () => {
-            process.off("SIGINT", onSig);
-            process.off("SIGTERM", onSig);
-            resolve();
-        };
-        process.on("SIGINT", onSig);
-        process.on("SIGTERM", onSig);
-    });
-    console.error("\nStopping…");
-    await handle.stop();
-}
-/**
- * `lotics package reset [path]` — DEV-ONLY, hard-gated. Drops the dev
- * installation's package-owned scaffolded tables and re-scaffolds them clean. The
- * backend refuses any workspace not flagged as a dev workspace, so this can never
- * erase a real workspace's data. The dev installation is resolved from the
- * project manifest's pin for the selected workspace.
- */
-export async function packageReset(client, args) {
-    const projectDir = path.resolve(args.projectDir ?? process.cwd());
-    const devWorkspaceId = client.getWorkspaceId();
-    if (!devWorkspaceId) {
-        throw new Error("No dev workspace selected. Pass --workspace <dev_ws> (a workspace created with --dev).");
-    }
-    const { manifest } = readPackageProject(projectDir);
-    const pin = manifest.dev[devWorkspaceId];
-    if (!pin) {
-        throw new Error(`No dev installation recorded for workspace ${devWorkspaceId}. Run "lotics package dev --workspace ${devWorkspaceId}" first.`);
-    }
-    console.error(`Resetting dev installation ${pin.app_id} in workspace ${devWorkspaceId}...`);
-    const app = await client.resetPackage(pin.app_id);
-    console.error(`Reset ${app.name} → ${app.id}. The scaffolded tables were dropped and re-created clean.`);
-}
-/**
- * Resolve the installation to operate on: an explicit app id wins; otherwise
- * fall back to the project manifest's dev pin for the selected workspace (the
- * same resolution `package reset` uses).
- */
-function resolveInstallationAppId(client, explicit) {
+function resolveInstallationAppId(explicit) {
     if (explicit)
         return explicit;
-    const workspaceId = client.getWorkspaceId();
-    if (!workspaceId) {
-        throw new Error("Pass an app id (lotics package doctor <app_id>) or select a workspace.");
-    }
-    let manifest;
-    try {
-        ({ manifest } = readPackageProject(path.resolve(process.cwd())));
-    }
-    catch {
-        // CLI usage boundary: translate "this directory isn't a package project"
-        // into the action the caller actually needs.
-        throw new Error("No app id given and the current directory is not a package project. " +
-            "Pass one explicitly: lotics package doctor <app_id>.");
-    }
-    const pin = manifest.dev[workspaceId];
-    if (!pin) {
-        throw new Error(`No app id given and no dev installation recorded for workspace ${workspaceId}. ` +
-            "Pass one explicitly: lotics package doctor <app_id>.");
-    }
-    return pin.app_id;
+    throw new Error("Pass an app id — e.g. lotics package doctor <app_id>.");
 }
+const RESOLVE_VERBS = new Set(["recreate", "revert", "keep", "apply", "archive", "unbind"]);
 /**
- * Parse repeated `--resolve <key>=<value>` flags. Drift entries
- * (`<namespace>.<alias>`) take `recreate` or an existing id; modified
- * artifacts (`<kind>.<alias>`) take `revert` or `keep`. Any other value is a
- * bind_to id; the server validates value-kind against what the key resolves.
+ * Parse repeated `--resolve <key>=<value>` flags into the ONE namespaced
+ * resolutions map every upgrade wire takes. Keys pass through verbatim — a
+ * drifted binding entry (`<namespace>.<alias>`), a modified artifact
+ * (`<kind>.<alias>`), a bundled/standalone knowledge doc (`knowledge.<alias>`),
+ * or a live-role re-point (`roles.<alias>`). A value that is one of the
+ * resolution verbs stays a verb; anything else is a `{ bind_to }` id. The
+ * server validates value-kind against what each key resolves.
  */
 export function parseResolveFlags(resolve) {
     const resolutions = {};
     for (const entry of resolve) {
         const eq = entry.indexOf("=");
         if (eq <= 0 || eq === entry.length - 1) {
-            throw new Error(`Invalid --resolve "${entry}" — expected <key>=recreate|revert|keep or <key>=<existing_id>.`);
+            throw new Error(`Invalid --resolve "${entry}" — expected <key>=<verb> (recreate|revert|keep|apply|archive|unbind) or <key>=<existing_id>.`);
         }
         const key = entry.slice(0, eq);
         const value = entry.slice(eq + 1);
-        resolutions[key] =
-            value === "recreate" || value === "revert" || value === "keep" ? value : { bind_to: value };
+        resolutions[key] = RESOLVE_VERBS.has(value)
+            ? value
+            : { bind_to: value };
     }
     return resolutions;
 }
@@ -970,9 +118,10 @@ export function parseResolveFlags(resolve) {
  * non-zero when drift is found so scripts can gate on it.
  */
 export async function packageDoctor(client, args) {
-    const app_id = resolveInstallationAppId(client, args.app_id);
+    const app_id = resolveInstallationAppId(args.app_id);
     const health = await client.getPackageHealth(app_id);
-    console.error(`${health.package_name} — installation ${health.app_id}`);
+    console.error(`${health.package_name} — installation ${health.app_id}` +
+        (health.is_origin ? " (origin — this app IS installation #1, the release working copy)" : ""));
     console.error(`  Installed: v${health.installed_version}   Latest: v${health.latest_version}` +
         (health.update_available ? "   → update available" : ""));
     if (health.drift.length === 0) {
@@ -983,19 +132,30 @@ export async function packageDoctor(client, args) {
         for (const d of health.drift) {
             console.error(`    - ${d.namespace}.${d.alias} → ${d.id} (missing from the workspace)`);
         }
-        console.error(`  Resolve while upgrading:\n    lotics package upgrade ${app_id}` +
+        console.error(`  Resolve while upgrading:\n    lotics upgrade ${app_id}` +
             ` --resolve <namespace.alias>=recreate   (or =<existing_id> to re-point)`);
         process.exitCode = 1;
     }
     if (health.modified.length === 0) {
-        console.error("  Package artifacts: pristine — no local edits an upgrade would revert.");
+        console.error(health.is_origin
+            ? "  Package artifacts: no changes since the last release."
+            : "  Package artifacts: pristine — no local edits an upgrade would revert.");
+    }
+    else if (health.is_origin) {
+        // The origin IS the author's working copy — edits since the last release are
+        // the NEXT release's payload, not consumer drift, and never fail the check.
+        console.error(`  Changed since v${health.installed_version} (${health.modified.length}) — a release will publish these:`);
+        for (const m of health.modified) {
+            console.error(`    - ${m.kind}.${m.alias}`);
+        }
+        console.error(`  Cut the next version:  lotics app release ${app_id} -m "<what changed>"`);
     }
     else {
         console.error(`  Locally modified package artifacts (${health.modified.length}):`);
         for (const m of health.modified) {
             console.error(`    - ${m.kind}.${m.alias} (an upgrade overwrites this unless kept)`);
         }
-        console.error(`  Consent while upgrading:\n    lotics package upgrade ${app_id}` +
+        console.error(`  Consent while upgrading:\n    lotics upgrade ${app_id}` +
             ` --resolve <kind.alias>=revert   (or =keep to retain the edit)`);
         process.exitCode = 1;
     }
@@ -1008,9 +168,17 @@ export async function packageDoctor(client, args) {
         }
     }
     if (health.knowledge_modified.length > 0) {
-        console.error(`  Locally edited package knowledge (${health.knowledge_modified.length}):`);
-        for (const m of health.knowledge_modified) {
-            console.error(`    - ${m.alias} "${m.name}" (an upgrade overwrites this unless kept)`);
+        if (health.is_origin) {
+            console.error(`  Knowledge changed since v${health.installed_version} (${health.knowledge_modified.length}) — a release will re-snapshot these:`);
+            for (const m of health.knowledge_modified) {
+                console.error(`    - ${m.alias} "${m.name}"`);
+            }
+        }
+        else {
+            console.error(`  Locally edited package knowledge (${health.knowledge_modified.length}):`);
+            for (const m of health.knowledge_modified) {
+                console.error(`    - ${m.alias} "${m.name}" (an upgrade overwrites this unless kept)`);
+            }
         }
     }
     if (health.missing_expected_docs.length > 0) {
@@ -1019,7 +187,9 @@ export async function packageDoctor(client, args) {
             console.error(`    - "${name}" (the package's agents route to this name; no matching doc exists)`);
         }
     }
-    if (health.knowledge_drift.length > 0 || health.knowledge_modified.length > 0) {
+    // Drift is genuine breakage on the origin too (a bound id vanished); edited
+    // knowledge on the origin is staged release work, not a failure.
+    if (health.knowledge_drift.length > 0 || (health.knowledge_modified.length > 0 && !health.is_origin)) {
         process.exitCode = 1;
     }
     if (health.knowledge_drift.length === 0 &&
@@ -1028,7 +198,7 @@ export async function packageDoctor(client, args) {
         console.error("  Knowledge: healthy — bound docs resolve, none locally edited, expects met.");
     }
     if (health.update_available) {
-        console.error(`  Upgrade: lotics package upgrade ${app_id}`);
+        console.error(`  Upgrade: lotics upgrade ${app_id}`);
     }
 }
 /**
@@ -1037,11 +207,13 @@ export async function packageDoctor(client, args) {
  * the exact --resolve syntax) while any binding drift, modified core artifact, or
  * consent-requiring bundled-knowledge doc lacks a resolution.
  *
- * `--resolve` is shared across the finding classes: a key naming a bundled
- * knowledge doc routes to `knowledge_resolutions` (apply|keep|archive|recreate|
- * unbind), everything else to core `resolutions`; `--bind-to` consents an
- * added-knowledge-doc name collision; `--apply-all` accepts the package's version
- * for every consent-requiring knowledge doc (overwriting local edits).
+ * `--resolve` speaks ONE namespaced grammar, passed to the server verbatim: a
+ * drifted binding entry (`<namespace>.<alias>`), a modified artifact
+ * (`<kind>.<alias>`), a bundled knowledge doc (`knowledge.<alias>` —
+ * apply|keep|archive|recreate|unbind), or a live-role re-point
+ * (`roles.<alias>=<grp_id>`). `--bind-to` consents an added-knowledge-doc name
+ * collision; `--apply-all` accepts the package's version for every
+ * consent-requiring knowledge doc (overwriting local edits).
  */
 export async function packageUpgrade(client, args) {
     const preview = await client.previewPackageUpgrade(args.app_id, {
@@ -1078,28 +250,23 @@ export async function packageUpgrade(client, args) {
             `  before making the change:  lotics package eject ${args.app_id}`);
         process.exit(1);
     }
-    // Route the shared --resolve flags: a knowledge-doc alias resolves the doc, a
-    // core artifact key resolves the artifact; a key that is BOTH throws.
-    const coreKeys = new Set([
-        ...preview.drift.map((d) => `${d.namespace}.${d.alias}`),
-        ...preview.modified.map((m) => `${m.kind}.${m.alias}`),
-    ]);
-    const { coreResolve, knowledgeResolutions } = routeAppUpgradeResolve(args.resolve, preview.knowledge, coreKeys);
-    const resolutions = parseResolveFlags(coreResolve);
+    // ONE namespaced grammar — the flags pass to the server verbatim. `--bind-to`
+    // is sugar for `knowledge.<alias>={bind_to}`; `--apply-all` fills the
+    // remaining consent-requiring knowledge entries with the accept verb.
+    const resolutions = parseResolveFlags(args.resolve);
+    for (const [alias, id] of Object.entries(parseBindToFlags(args.bindTo))) {
+        resolutions[`knowledge.${alias}`] = { bind_to: id };
+    }
     if (args.applyAll) {
         for (const entry of preview.knowledge) {
-            if (knowledgeEntryNeedsConsent(entry) && knowledgeResolutions[entry.alias] === undefined) {
-                knowledgeResolutions[entry.alias] = knowledgeAcceptResolution(entry.change);
+            if (knowledgeEntryNeedsConsent(entry) && resolutions[`knowledge.${entry.alias}`] === undefined) {
+                resolutions[`knowledge.${entry.alias}`] = knowledgeAcceptResolution(entry.change);
             }
         }
     }
-    const knowledge_resolutions = {
-        resolutions: knowledgeResolutions,
-        bind_to: parseBindToFlags(args.bindTo),
-    };
     const unresolvedDrift = preview.drift.filter((d) => resolutions[`${d.namespace}.${d.alias}`] === undefined);
     const unresolvedModified = preview.modified.filter((m) => resolutions[`${m.kind}.${m.alias}`] === undefined);
-    const unresolvedKnowledge = preview.knowledge.filter((e) => knowledgeEntryNeedsConsent(e) && knowledgeResolutions[e.alias] === undefined);
+    const unresolvedKnowledge = preview.knowledge.filter((e) => knowledgeEntryNeedsConsent(e) && resolutions[`knowledge.${e.alias}`] === undefined);
     if (unresolvedDrift.length > 0 ||
         unresolvedModified.length > 0 ||
         unresolvedKnowledge.length > 0) {
@@ -1123,12 +290,9 @@ export async function packageUpgrade(client, args) {
         }
         process.exit(1);
     }
-    const hasKnowledgeResolutions = Object.keys(knowledge_resolutions.resolutions).length > 0 ||
-        Object.keys(knowledge_resolutions.bind_to).length > 0;
     const app = await client.upgradePackage(args.app_id, {
         ...(args.version !== undefined ? { version: args.version } : {}),
         ...(Object.keys(resolutions).length > 0 ? { resolutions } : {}),
-        ...(hasKnowledgeResolutions ? { knowledge_resolutions } : {}),
     });
     console.error(`Upgraded ${app.name} → v${app.package_version} (${app.id}).`);
 }
@@ -1202,99 +366,14 @@ function formatKnowledgeResolveHint(entry) {
     const note = entry.change === "changed" || entry.change === "removed"
         ? "   (a local edit — apply/archive overwrites it; keep retains it)"
         : "   (bound doc is gone; recreate from the package, or unbind)";
-    return `    --resolve ${entry.alias}=${validKnowledgeResolutions(entry.change).join("|")}${note}`;
-}
-/**
- * Route an app-install upgrade's `--resolve` entries into the core-artifact
- * bucket vs the bundled-knowledge bucket. `--resolve` is shared between the two
- * finding classes, so each key is matched against the preview: a key that names a
- * bundled knowledge doc resolves that doc (its value validated against the doc's
- * change class here — the app path has no separate knowledge-only parser);
- * anything else stays a core resolution (a `<namespace>.<alias>` drift, a
- * `<kind>.<alias>` modified core, or a key the server validates). A key that is
- * BOTH a knowledge alias and a core-artifact key is ambiguous — throw rather than
- * guess which the operator meant.
- */
-export function routeAppUpgradeResolve(resolve, knowledgeEntries, coreKeys) {
-    const byAlias = new Map(knowledgeEntries.map((e) => [e.alias, e]));
-    const coreResolve = [];
-    const knowledgeResolutions = {};
-    for (const entry of resolve) {
-        const eq = entry.indexOf("=");
-        if (eq <= 0 || eq === entry.length - 1) {
-            throw new Error(`Invalid --resolve "${entry}" — expected <key>=<value>.`);
-        }
-        const key = entry.slice(0, eq);
-        const value = entry.slice(eq + 1);
-        const known = byAlias.get(key);
-        if (known && coreKeys.has(key)) {
-            throw new Error(`--resolve "${key}" is ambiguous — it names both a bundled knowledge doc and a core artifact in this upgrade. ` +
-                `Rename one alias so it is unambiguous; refusing to guess.`);
-        }
-        if (known) {
-            const valid = validKnowledgeResolutions(known.change);
-            const match = valid.find((v) => v === value);
-            if (match === undefined) {
-                throw new Error(`Invalid --resolve value "${value}" for knowledge doc "${key}" (${known.change}) — expected ${valid.join("|")}.`);
-            }
-            knowledgeResolutions[key] = match;
-        }
-        else {
-            coreResolve.push(entry);
-        }
-    }
-    return { coreResolve, knowledgeResolutions };
-}
-/**
- * Route a STANDALONE content upgrade's shared `--resolve <alias>=<value>` flags
- * into the knowledge vs templates buckets by matching each alias against the two
- * preview namespaces. A doc alias takes apply|keep|archive|recreate|unbind; a
- * template alias takes revert|keep. An alias present in BOTH namespaces is
- * ambiguous → loud error (no guess). An alias in NEITHER → error. The value is
- * validated against the namespace it routes to. Exported for testing.
- */
-export function routeContentResolveFlags(resolve, knowledgeAliases, templateAliases) {
-    const knowledge = {};
-    const templates = {};
-    const knowledgeValid = new Set(["apply", "keep", "archive", "recreate", "unbind"]);
-    const templateValid = new Set(["revert", "keep"]);
-    for (const entry of resolve) {
-        const eq = entry.indexOf("=");
-        if (eq <= 0 || eq === entry.length - 1) {
-            throw new Error(`Invalid --resolve "${entry}" — expected <alias>=<value>.`);
-        }
-        const key = entry.slice(0, eq);
-        const value = entry.slice(eq + 1);
-        const isKnowledge = knowledgeAliases.has(key);
-        const isTemplate = templateAliases.has(key);
-        if (isKnowledge && isTemplate) {
-            throw new Error(`--resolve "${key}" is ambiguous — it names both a knowledge doc and a template in this upgrade. ` +
-                `Rename one alias in the package so the two content namespaces are disjoint.`);
-        }
-        if (isTemplate) {
-            if (!templateValid.has(value)) {
-                throw new Error(`Invalid --resolve value "${value}" for template "${key}" — expected revert|keep.`);
-            }
-            templates[key] = value;
-            continue;
-        }
-        if (isKnowledge) {
-            if (!knowledgeValid.has(value)) {
-                throw new Error(`Invalid --resolve value "${value}" for knowledge alias "${key}" — expected apply|keep|archive|recreate|unbind.`);
-            }
-            knowledge[key] = value;
-            continue;
-        }
-        throw new Error(`--resolve "${key}" does not name a knowledge doc or template in this upgrade.`);
-    }
-    return { knowledge, templates };
+    return `    --resolve knowledge.${entry.alias}=${validKnowledgeResolutions(entry.change).join("|")}${note}`;
 }
-/** The `--resolve <alias>=revert|keep` remediation line for a consent-requiring template. */
+/** The `--resolve template.<alias>=revert|keep` remediation line for a consent-requiring template. */
 function formatTemplateResolveHint(entry) {
     const note = entry.baseline_unknown
         ? "   (can't verify the local edit — older package version; revert overwrites, keep retains)"
         : "   (a local edit — revert overwrites it with the package's version; keep retains it)";
-    return `    --resolve ${entry.alias}=revert|keep${note}`;
+    return `    --resolve template.${entry.alias}=revert|keep${note}`;
 }
 /**
  * Preview-then-apply a STANDALONE content installation upgrade — knowledge docs
@@ -1304,9 +383,10 @@ function formatTemplateResolveHint(entry) {
  * locally-edited changed template. `--apply-all` auto-resolves EVERY consent entry
  * by accepting the package's version (knowledge changed→apply, removed→archive,
  * drifted→recreate; template→revert) — an explicit bulk "take upstream" that
- * discards local edits. `--resolve <alias>=<value>` and `--bind-to <alias>=<kdc_id>`
- * resolve entries individually (`--resolve` is routed to the right namespace by
- * matching the alias against the preview).
+ * discards local edits. `--resolve knowledge.<alias>=<value>` /
+ * `--resolve template.<alias>=revert|keep` and `--bind-to <alias>=<kdc_id>`
+ * resolve entries individually — the ONE namespaced grammar, passed to the
+ * server verbatim.
  */
 export async function packageUpgradeKnowledge(client, args) {
     const preview = await client.previewContentInstallationUpgrade(args.installation_id, {
@@ -1327,7 +407,7 @@ export async function packageUpgradeKnowledge(client, args) {
             return;
         }
         console.error("  No changes needing consent — advancing the version pin; clean template updates apply automatically.");
-        await apply({ knowledge: { resolutions: {}, bind_to: {} }, templates: {} });
+        await apply({});
         return;
     }
     for (const entry of preview.entries) {
@@ -1336,26 +416,27 @@ export async function packageUpgradeKnowledge(client, args) {
     for (const entry of preview.templates) {
         console.error(`  [template] ${entry.alias} (modified — needs consent)`);
     }
-    // Route the shared --resolve flags across the two namespaces (loud on an alias
-    // in both), then optionally bulk-accept every remaining consent entry.
-    const routed = routeContentResolveFlags(args.resolve, new Set(preview.entries.map((e) => e.alias)), new Set(preview.templates.map((t) => t.alias)));
-    const resolutions = {
-        knowledge: { resolutions: { ...routed.knowledge }, bind_to: { ...args.bind_to } },
-        templates: { ...routed.templates },
-    };
+    // ONE namespaced grammar — the flags pass to the server verbatim. `--bind-to`
+    // is sugar for `knowledge.<alias>={bind_to}`; `--apply-all` fills the
+    // remaining consent entries with the accept verb (template → revert).
+    const resolutions = parseResolveFlags(args.resolve);
+    for (const [alias, id] of Object.entries(args.bind_to)) {
+        resolutions[`knowledge.${alias}`] = { bind_to: id };
+    }
     if (args.applyAll) {
         for (const entry of preview.entries) {
-            if (knowledgeEntryNeedsConsent(entry) && resolutions.knowledge.resolutions[entry.alias] === undefined) {
-                resolutions.knowledge.resolutions[entry.alias] = knowledgeAcceptResolution(entry.change);
+            if (knowledgeEntryNeedsConsent(entry) && resolutions[`knowledge.${entry.alias}`] === undefined) {
+                resolutions[`knowledge.${entry.alias}`] = knowledgeAcceptResolution(entry.change);
             }
         }
         for (const entry of preview.templates) {
-            if (resolutions.templates[entry.alias] === undefined)
-                resolutions.templates[entry.alias] = "revert";
+            if (resolutions[`template.${entry.alias}`] === undefined) {
+                resolutions[`template.${entry.alias}`] = "revert";
+            }
         }
     }
-    const unresolvedKnowledge = preview.entries.filter((entry) => knowledgeEntryNeedsConsent(entry) && resolutions.knowledge.resolutions[entry.alias] === undefined);
-    const unresolvedTemplates = preview.templates.filter((entry) => resolutions.templates[entry.alias] === undefined);
+    const unresolvedKnowledge = preview.entries.filter((entry) => knowledgeEntryNeedsConsent(entry) && resolutions[`knowledge.${entry.alias}`] === undefined);
+    const unresolvedTemplates = preview.templates.filter((entry) => resolutions[`template.${entry.alias}`] === undefined);
     if (unresolvedKnowledge.length > 0 || unresolvedTemplates.length > 0) {
         console.error("  These need a resolution before upgrading (or pass --apply-all to accept the package's version for all):");
         for (const entry of unresolvedKnowledge)
@@ -1413,8 +494,8 @@ export async function packageInstall(client, args) {
             console.error(`  ${templateAliases.length} template(s) live: ${templateAliases.map((a) => `${a}→${templates[a]}`).join(", ")}`);
         }
         warnMissingExpectedDocs(warnings.missing_expected_docs);
-        console.error(`  Upgrade later:  lotics package upgrade ${installation.id}`);
-        console.error(`  Uninstall:      lotics package uninstall ${installation.id} [--keep-content]`);
+        console.error(`  Upgrade later:  lotics upgrade ${installation.id}`);
+        console.error(`  Uninstall:      lotics uninstall ${installation.id} [--keep-content]`);
         return;
     }
     const { app, knowledge_warnings } = result;
@@ -1422,11 +503,16 @@ export async function packageInstall(client, args) {
     console.error(`Installed ${app.name} ${versionLabel} → ${app.id} (workspace ${app.workspace_id}).`);
     console.error("  The data model, queries, workflows, and agents are live.");
     warnMissingExpectedDocs(knowledge_warnings.missing_expected_docs);
-    console.error("  Pull it for local editing:  lotics app pull " + app.id);
+    // Follow-up ops key on the NEW installation id (app_), not the package id typed
+    // at `install` — signpost each one with the id inlined (the content branch above
+    // does the same), so the id switch is never a silent trap.
+    console.error(`  Pull it for local editing:  lotics app pull ${app.id}`);
+    console.error(`  Upgrade later:              lotics upgrade ${app.id}`);
+    console.error(`  Health / uninstall:         lotics package doctor ${app.id}  ·  lotics uninstall ${app.id} [--archive-tables]`);
 }
 /**
- * `lotics package uninstall <app_id|pci_id>` — ONE command over both installation
- * kinds, dispatched by the id form (mirrors `package upgrade`):
+ * `lotics uninstall <app_id|pci_id>` — ONE top-level command over both installation
+ * kinds, dispatched by the id form (mirrors `lotics upgrade`):
  *   - a `pci_` id → a STANDALONE CONTENT installation: deletes the row and (unless
  *     `--keep-content`) archives its package-bound docs AND templates, listing each
  *     archived id.
@@ -1482,10 +568,11 @@ export async function packageUninstall(client, args) {
     }
 }
 /**
- * `lotics package list-content` — list the selected workspace's package-managed
- * content installations (standalone `pci_` corpora + app-bundled ones), each
- * with its registry status. The read surface that surfaces a standalone `pci_` id
- * for `upgrade` / `uninstall` (install prints it once; nothing else did before).
+ * `lotics package list-content` — list the selected workspace's STANDALONE
+ * content installations (an app-bundled corpus rides its app's
+ * `binding.knowledge` and shows on the Apps surface instead), each with its
+ * registry status. The read surface that surfaces a `pci_` id for
+ * `upgrade` / `uninstall` (install prints it once; nothing else did before).
  */
 export async function packageListContent(client) {
     const workspaceId = client.getWorkspaceId();
@@ -1502,11 +589,10 @@ export async function packageListContent(client) {
         const name = inst.package_registry?.name ?? "(unknown package)";
         const latest = inst.package_registry?.latest_version;
         const updateAvailable = inst.package_registry?.update_available ?? false;
-        const source = inst.app_id === null ? "standalone" : `app-bundled (${inst.app_id})`;
         const versionLabel = latest !== undefined && latest !== inst.package_version
             ? `v${inst.package_version} → latest v${latest}`
             : `v${inst.package_version}`;
-        console.error(`  ${inst.id}  ${name}  ${versionLabel}  ${source}` +
+        console.error(`  ${inst.id}  ${name}  ${versionLabel}` +
             (updateAvailable ? "  → update available" : ""));
     }
 }
@@ -1520,7 +606,7 @@ export async function packageEject(client, args) {
 /**
  * Parse one `key=value` config assignment. When the knob's type is known (from
  * the stored value at `package config --set`) the value is parsed to that type
- * loudly; otherwise (`package install --config`) it is inferred (true/false →
+ * loudly; otherwise (`lotics install --config`) it is inferred (true/false →
  * boolean, numeric → number, else string) and the server validates it against
  * the contract.
  */
@@ -1598,262 +684,174 @@ export async function packageConfig(client, args) {
     }
 }
 /**
- * `lotics package retire <package_id> [--undo]` — retire (or un-retire) a
- * registry package. Owner-org admin-only.
+ * `lotics app unpublish <app_id|package_id> [--undo]` — take a published package
+ * off the shelf (or `--undo` restore it): new installs refuse it and it hides
+ * from other orgs, while existing installations keep working and may still
+ * upgrade. Given an app id (an installation of the package) it resolves the
+ * package from the app; a package id targets it directly. Owner-org admin-only.
  */
-export async function packageRetire(client, args) {
-    const pkg = await client.retirePackage(args.package_id, { undo: args.undo });
+export async function appUnpublish(client, args) {
+    let packageId = args.id;
+    if (args.id.startsWith("app_")) {
+        const app = await client.getApp(args.id);
+        if (!app.package_id) {
+            throw new Error(`App ${args.id} is not a package installation — it has no package to unpublish. ` +
+                `Pass the package id directly.`);
+        }
+        packageId = app.package_id;
+    }
+    const pkg = await client.retirePackage(packageId, { undo: args.undo });
     if (pkg.retired_at !== null) {
-        console.error(`Retired ${pkg.name} (${pkg.id}). New installs refuse it and it is hidden from other orgs; ` +
-            `existing installations keep working and may still upgrade.`);
+        console.error(`Unpublished ${pkg.name} (${pkg.id}). New installs refuse it and it is hidden from other orgs; ` +
+            `existing installations keep working and may still upgrade. Undo: lotics app unpublish ${pkg.id} --undo`);
     }
     else {
-        console.error(`Un-retired ${pkg.name} (${pkg.id}) — installable again.`);
+        console.error(`Re-published ${pkg.name} (${pkg.id}) — installable again.`);
     }
 }
 /**
- * `lotics package extract <app_id> [path]` — promote a bespoke app to a DRAFT
- * package project (docs/packages.md § Promotion). Calls the extract read,
- * prints the findings report grouped by severity, then ALWAYS emits the draft
- * project (a broken contract is still the reviewable starting point): the app's
- * current source archive (same mechanics as `lotics app pull`) with the app
- * manifest swapped for an unpublished package manifest, `contract.json`, the
- * file-backed templates staged at their `bytes_ref` paths, and
- * `.lotics/adopt_binding.json` (the origin pin the `adopt` step reads back).
- * Exits non-zero when any `error` finding exists — the draft is written, but
- * publish re-validates and nothing should ship unreviewed.
+ * `lotics app publish [app_id|.] [--rename old=new ...] [-m <changelog>] [--yes]` —
+ * FIRST-RELEASE a bespoke app as a package (docs/packages.md § Promotion). Nothing
+ * starts as a package. Mirrors `app release`'s preview→apply UX: it first shows the
+ * dry-run preview (GET, no writes) — the package name, the auto-minted RENAMABLE
+ * aliases (the exact `--rename` keys, so v1's frozen aliases are inspected first,
+ * never a blind publish), and the extract findings — then APPLIES only with
+ * `--yes` (else exits 1 with the re-run hint). On apply the server extracts the
+ * contract, creates the registry package, publishes v1 from the DEPLOYED source +
+ * dist, and pins the origin as installation #1. `--rename old=new` fixes an
+ * auto-minted alias before v1 freezes it; an `error` finding blocks the apply. An
+ * already-linked app releases with `lotics app release` instead. The app id is the
+ * positional (`.`/omitted → resolved from the local app project manifest).
  */
-/**
- * Read an APP project's package.json `lotics.knowledge` (`[{ alias, doc_id }]`)
- * + `lotics.knowledge_expects` (`string[]`) authoring declaration — the docs the
- * package will own + the doc NAMES its agents route to but do not own. Distinct
- * from a PACKAGE project's `lotics.package.knowledge` (a metadata record).
- */
-function readAppKnowledgeDeclaration(appPkgJson) {
-    const lotics = isPlainObject(appPkgJson.lotics) ? appPkgJson.lotics : {};
-    const knowledge = [];
-    if (Array.isArray(lotics.knowledge)) {
-        for (const entry of lotics.knowledge) {
-            if (isPlainObject(entry) && typeof entry.alias === "string" && typeof entry.doc_id === "string") {
-                knowledge.push({ alias: entry.alias, doc_id: entry.doc_id });
-            }
-        }
-    }
-    const knowledge_expects = Array.isArray(lotics.knowledge_expects)
-        ? lotics.knowledge_expects.filter((v) => typeof v === "string")
-        : [];
-    return { knowledge, knowledge_expects };
-}
-/** Derive the package project's `lotics.package.knowledge` metadata from the extracted contract's knowledge namespace. */
-function knowledgeManifestFromContract(contract) {
-    const out = {};
-    if (!isPlainObject(contract) || !isPlainObject(contract.knowledge))
-        return out;
-    for (const [alias, entry] of Object.entries(contract.knowledge)) {
-        if (!isPlainObject(entry) || typeof entry.name !== "string")
-            continue;
-        out[alias] = {
-            name: entry.name,
-            description: typeof entry.description === "string" ? entry.description : null,
-            active_by_default: typeof entry.active_by_default === "boolean" ? entry.active_by_default : true,
-        };
-    }
-    return out;
-}
-export async function packageExtract(client, args) {
-    const app = await client.getApp(args.app_id);
-    if (!app.current_version_id) {
-        throw new Error(`App ${app.id} has no deployed version — extract stages its source archive, so deploy it first.`);
-    }
-    const targetPath = path.resolve(args.targetPath ?? appDirName(app.name));
-    if (fs.existsSync(targetPath) && fs.readdirSync(targetPath).length > 0) {
-        throw new Error(`Target directory ${targetPath} is not empty.`);
-    }
-    fs.mkdirSync(targetPath, { recursive: true });
-    // Pull the app's current source archive FIRST — same mechanics as `lotics app
-    // pull` (getAppVersion → presigned source URL → download → untar). The app's
-    // package.json (in the archive) carries the `lotics.knowledge` declaration
-    // extract needs, so the download precedes the extract call.
-    const version = await client.getAppVersion(app.id, app.current_version_id);
-    const sourceUrl = await client.getAppVersionSourceUrl(app.id, version.id);
-    const tmpFile = path.join(tmpdir(), `lotics-extract-${app.id}-${Date.now()}.tar.gz`);
-    console.error("Downloading source archive...");
-    await client.downloadFile(sourceUrl, tmpFile);
-    try {
-        console.error(`Extracting to ${targetPath}...`);
-        await runTar(["-xzf", tmpFile, "-C", targetPath], targetPath);
+export async function appPublish(client, args) {
+    const projectDir = path.resolve(args.projectDir ?? process.cwd());
+    const local = readLocalAppManifest(projectDir);
+    const explicit = args.app_id !== undefined && args.app_id !== "." ? args.app_id : undefined;
+    const appId = explicit ?? local?.app_id ?? null;
+    if (appId === null) {
+        throw new Error("No app id. Run `lotics app publish` from a pulled app project (lotics app pull <app_id>), " +
+            "or pass one: lotics app publish <app_id>.");
+    }
+    // Forward the app's package-managed knowledge declaration ONLY when the local
+    // manifest is this app's own project (agents reference docs by free text, so the
+    // author declares which the package owns). A bare id published from elsewhere
+    // ships without a bundled corpus — publish from the app dir to include it.
+    const knowledge = local && local.app_id === appId ? local.knowledge : [];
+    const renames = parseRenameFlags(args.renames);
+    // Preview first (GET, no writes) — the same preview→--yes flow as `app release`,
+    // so the aliases v1 freezes forever are never a blind publish and `--rename`
+    // targets are inspectable before committing.
+    const preview = await client.previewPublishAppPackage(appId, { renames, knowledge });
+    const { lines, hasError } = formatExtractReport(preview.findings);
+    console.error(`Publish preview — ${appId} as new package "${preview.package_name}" (v1):`);
+    const groups = [
+        ["entities", preview.renamable_aliases.entities],
+        ["fields", preview.renamable_aliases.fields],
+        ["options", preview.renamable_aliases.options],
+        ["roles", preview.renamable_aliases.roles],
+        ["templates", preview.renamable_aliases.templates],
+        ["workflows", preview.renamable_aliases.workflows],
+    ];
+    if (groups.some(([, vals]) => vals.length > 0)) {
+        console.error("  Auto-minted aliases — rename any with --rename <alias>=<new> before v1 freezes them:");
+        for (const [label, vals] of groups) {
+            if (vals.length > 0)
+                console.error(`    ${`${label}:`.padEnd(11)} ${vals.join(", ")}`);
+        }
+        console.error("  (query / app-workflow / agent runtime aliases are fixed — the shipped source calls them verbatim.)");
     }
-    finally {
-        if (fs.existsSync(tmpFile))
-            fs.unlinkSync(tmpFile);
+    else {
+        console.error("  No renamable aliases.");
     }
-    const appPkgJson = JSON.parse(fs.readFileSync(packageJsonPath(targetPath), "utf-8"));
-    const appKnowledge = readAppKnowledgeDeclaration(appPkgJson);
-    // Agents reference docs in free text (uninvertible), so the author DECLARED the
-    // package-managed docs in the app manifest; pass them to extract, which loads
-    // each live doc + emits its content bytes to write locally.
-    const extracted = await client.extractPackage(args.app_id, {
-        knowledge: appKnowledge.knowledge,
-    });
-    const { lines, hasError } = formatExtractReport(extracted.report);
     if (lines.length > 0) {
-        console.error(`Extraction report (${extracted.report.length}):`);
+        console.error(`  Findings (${preview.findings.length}):`);
         for (const line of lines)
             console.error(line);
     }
-    else {
-        console.error("Extraction report: no findings.");
-    }
-    // Swap the app manifest (lotics.app_id/workspace_id) for a fresh, unpublished
-    // package manifest — atomic write via the existing manifest writer.
-    const draft = draftPackageProjectFromApp(appPkgJson, { name: app.name, description: null });
-    // Fold the extracted knowledge metadata + the app's `knowledge_expects` into the
-    // package manifest (the content bytes are written to knowledge/<alias>.md below;
-    // build re-derives the shas from them).
-    draft.manifest.knowledge = knowledgeManifestFromContract(extracted.contract);
-    draft.manifest.knowledge_expects = appKnowledge.knowledge_expects;
-    // The origin app's package.json rides in the source archive with ITS OWN
-    // @lotics/app-sdk range — raise it to the getAppBinding floor the generated
-    // .lotics/app_fields.ts needs (never lower an already-newer range).
-    const deps = isPlainObject(draft.pkgJson.dependencies) ? draft.pkgJson.dependencies : {};
-    const originRange = typeof deps["@lotics/app-sdk"] === "string" ? deps["@lotics/app-sdk"] : null;
-    const originFloor = originRange?.replace(/^[\^~]/, "") ?? null;
-    if (originFloor === null || cmpVersions(originFloor, STARTER_FALLBACK_SDK_VERSION) < 0) {
-        const raised = packageSdkRange(await fetchLatestNpmVersion("@lotics/app-sdk"));
-        draft.pkgJson.dependencies = { ...deps, "@lotics/app-sdk": raised };
-        console.error(`Raised @lotics/app-sdk to ${raised} (generated app_fields needs getAppBinding)`);
-    }
-    writePackageManifest(targetPath, draft);
-    // The alias-keyed draft contract — the reviewable master. Pretty + trailing newline.
-    fs.writeFileSync(path.join(targetPath, CONTRACT_FILE), JSON.stringify(extracted.contract, null, 2) + "\n");
-    console.error(`Wrote ${CONTRACT_FILE}`);
-    // The origin's baked `.lotics/app_fields.ts` (concrete ids) never travels —
-    // regenerate it contract-derived so `F`/`OPT` resolve per-install at runtime
-    // and the extracted source compiles unchanged.
-    writePackageAppFields(targetPath);
-    // vite.config.ts is starter-owned machinery — refresh it wholesale so the
-    // package project carries the current starter config (notably
-    // `build.target: "es2022"`, which the generated app_fields' top-level await
-    // requires). Origin-side dev customizations (e.g. `lotics ui link` aliases)
-    // don't belong in a package.
-    const starterViteConfig = buildStarterTemplate({
-        app_name: app.name,
-        app_id: "",
-        workspace_id: "",
-    }).find((f) => f.path === "vite.config.ts");
-    if (starterViteConfig === undefined) {
-        throw new Error("starter template is missing vite.config.ts — cannot refresh the package project");
-    }
-    const viteConfigPath = path.join(targetPath, "vite.config.ts");
-    const originViteConfig = fs.existsSync(viteConfigPath)
-        ? fs.readFileSync(viteConfigPath, "utf-8")
-        : null;
-    fs.writeFileSync(viteConfigPath, starterViteConfig.content);
-    if (originViteConfig !== null && originViteConfig !== starterViteConfig.content) {
-        // The origin may carry legitimate customizations (optimizeDeps entries,
-        // plugins) beyond the dev-links that must not ship — never destroy them
-        // silently: stash the original for manual re-application.
-        const stash = path.join(dotLoticsDirEnsured(targetPath), "vite.config.origin.ts");
-        fs.writeFileSync(stash, originViteConfig);
-        console.error("Refreshed vite.config.ts from the starter (build.target es2022). The origin app's config " +
-            "differed — its original was saved to .lotics/vite.config.origin.ts; re-apply any " +
-            "custom optimizeDeps/plugins entries you still need (never dev-link aliases).");
-    }
-    else {
-        console.error("Refreshed vite.config.ts from the starter (build.target es2022)");
-    }
-    // Stage each file-backed template at the `bytes_ref` the contract references.
-    // The download lands in the target dir (fresh, so no name collision) under the
-    // file's own name; rename it to the exact `bytes_ref` basename the contract
-    // points at. Processed sequentially so a prior rename frees the name.
-    for (const tf of extracted.template_files) {
-        const dest = path.join(targetPath, tf.bytes_ref);
-        fs.mkdirSync(path.dirname(dest), { recursive: true });
-        const { path: downloaded } = await client.downloadFileById(tf.file_id, path.dirname(dest));
-        if (path.resolve(downloaded) !== path.resolve(dest))
-            fs.renameSync(downloaded, dest);
-        console.error(`Wrote ${tf.bytes_ref}`);
-    }
-    // Write each package-managed knowledge doc's content at `knowledge/<alias>.md`
-    // (the path the contract's content_ref names) — build re-derives the sha from
-    // these bytes, so they are the reviewable master alongside contract.json.
-    for (const kf of extracted.knowledge_files) {
-        const dest = path.join(targetPath, kf.content_ref);
-        fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.writeFileSync(dest, kf.content);
-        console.error(`Wrote ${kf.content_ref}`);
-    }
-    // The origin pin the `adopt` step reads back — incl. the knowledge binding
-    // (alias → origin kdc_ id) so adopt can pin the corpus as installation #1.
-    // `.lotics` is in SOURCE_STAGE_EXCLUDES, so this never ships in a published bundle.
-    const dotLotics = path.join(targetPath, ".lotics");
-    fs.mkdirSync(dotLotics, { recursive: true });
-    fs.writeFileSync(path.join(dotLotics, ADOPT_BINDING_FILE), JSON.stringify({
-        app_id: app.id,
-        workspace_id: app.workspace_id,
-        binding: extracted.binding,
-        knowledge_binding: extracted.knowledge_binding,
-    }, null, 2) + "\n");
-    console.error(`Wrote .lotics/${ADOPT_BINDING_FILE}`);
-    console.error("Installing npm dependencies...");
-    await runNpm(["install"], targetPath);
     if (hasError) {
-        console.error("\nExtraction produced error findings — the draft is written but NOT publishable as-is.");
-        console.error("Fix the reported items above, then publish (which re-validates the contract).");
+        console.error("\nExtract found error findings — the app cannot be published as-is. Fix them in the app, redeploy, and retry.");
+        process.exitCode = 1;
+        return;
+    }
+    if (!args.yes) {
+        const idArg = explicit ?? ".";
+        const renameArgs = args.renames.map((r) => ` --rename ${r}`).join("");
+        const mArg = args.changelog ? ` -m ${JSON.stringify(args.changelog)}` : "";
+        console.error(`\nRe-run with --yes to publish v1:`);
+        console.error(`  lotics app publish ${idArg}${renameArgs}${mArg} --yes`);
         process.exitCode = 1;
         return;
     }
-    console.error("\nDraft package project written. Next steps:");
-    console.error(`  cd ${path.relative(process.cwd(), targetPath) || "."}`);
-    console.error("  # review the aliases in contract.json, then:");
-    console.error(`  lotics package publish -m "v1"`);
-    console.error(`  lotics package adopt ${app.id}   (from this project, same workspace)`);
+    const result = await client.publishAppAsPackage(appId, {
+        renames,
+        changelog: args.changelog ?? null,
+        knowledge,
+    });
+    console.error(`Published ${result.package_id} v${result.version} from app ${appId}.`);
+    console.error(`  The app is now installation #1 — develop it in place, then release the next version:`);
+    console.error(`    lotics app pull ${appId}   # edit, then lotics app deploy`);
+    console.error(`    lotics app release ${appId} -m "<what changed>"`);
+    console.error(`  Install it elsewhere:  lotics install ${result.package_id}`);
 }
 /**
- * `lotics package adopt <app_id> [path]` — bind the published package project
- * onto the origin app (docs/packages.md § Promotion). Reads the project
- * manifest (must be published — refuses otherwise), resolves the version
- * (`--version N` else the manifest's), and reads `.lotics/adopt_binding.json`,
- * REFUSING a pin recorded for a different app. On success the app becomes
- * installation #1 and is upgradeable again; a server ConflictError (naming the
- * unfaithful aliases) surfaces verbatim.
+ * Resolve the release/publish target app id: an explicit `<app_id>` wins; `.` (or
+ * no positional) resolves the local app project manifest's `lotics.app_id` — the
+ * project `lotics app pull` writes — so a release from the pulled app dir needs
+ * no id.
  */
-export async function packageAdopt(client, args) {
+function resolveOriginAppId(projectDir, explicit) {
+    if (explicit !== undefined && explicit !== ".")
+        return explicit;
+    const local = readLocalAppManifest(projectDir);
+    if (local?.app_id)
+        return local.app_id;
+    throw new Error("No app id. Run this from a pulled app project (lotics app pull <app_id>), or pass an app id explicitly.");
+}
+/**
+ * `lotics app release [app_id|.] -m <changelog> [--yes]` — snapshot an
+ * adopted/installed origin app into its next registry version (docs/packages.md
+ * § Promotion). The origin is the permanent working copy; a release binding-aware-
+ * extracts it (stable aliases), repackages its DEPLOYED source + dist as the
+ * bundle, publishes the next version, and re-pins the origin. Prints the preview
+ * first (next version, new + changed aliases, findings); applies only with
+ * `--yes`, else exits 1 so a review step can't be skipped. An `error` finding
+ * blocks the apply.
+ */
+export async function appRelease(client, args) {
     const projectDir = path.resolve(args.projectDir ?? process.cwd());
-    const { manifest } = readPackageProject(projectDir);
-    if (manifest.id === null) {
-        throw new Error("This package project has never been published (no package id). Publish first:\n  lotics package publish");
+    const appId = resolveOriginAppId(projectDir, args.app_id);
+    const preview = await client.previewPackageRelease(appId);
+    const { lines, hasError } = formatExtractReport(preview.findings);
+    console.error(`Release preview — ${appId} → ${preview.package_id} v${preview.version}:`);
+    if (preview.added_aliases.length > 0) {
+        console.error(`  New (${preview.added_aliases.length}): ${preview.added_aliases.join(", ")}`);
     }
-    const version = args.version ?? manifest.version;
-    if (version === null) {
-        throw new Error("No version to adopt — publish this project first (lotics package publish) or pass --version N.");
+    if (preview.changed_artifacts.length > 0) {
+        console.error(`  Changed (${preview.changed_artifacts.length}): ${preview.changed_artifacts.join(", ")}`);
     }
-    const bindingPath = path.join(projectDir, ".lotics", ADOPT_BINDING_FILE);
-    if (!fs.existsSync(bindingPath)) {
-        throw new Error(`No .lotics/${ADOPT_BINDING_FILE} in ${projectDir}. Adopt binds the origin app that ` +
-            `"lotics package extract" recorded — run extract to produce this project.`);
+    if (preview.added_aliases.length === 0 && preview.changed_artifacts.length === 0) {
+        console.error("  No contract changes since the current version (a fresh code/dist snapshot still ships).");
     }
-    const pin = parseAdoptBindingFile(JSON.parse(fs.readFileSync(bindingPath, "utf-8")), args.app_id);
-    const app = await client.adoptPackage(args.app_id, {
-        package_id: manifest.id,
-        version,
-        binding: pin.binding,
-        // The origin knowledge binding (empty when the app owns no package-managed
-        // docs) — the server verifies it maps the contract's knowledge aliases faithfully.
-        ...(Object.keys(pin.knowledge_binding).length > 0
-            ? { knowledge_binding: pin.knowledge_binding }
-            : {}),
-    });
-    console.error(`Adopted ${app.name} → installation of ${app.package_id} v${app.package_version}.`);
-    console.error(`  Verify the installation:  lotics package doctor ${app.id}`);
+    if (lines.length > 0) {
+        console.error(`  Findings (${preview.findings.length}):`);
+        for (const line of lines)
+            console.error(line);
+    }
+    if (hasError) {
+        console.error("\nExtract found error findings — the origin cannot be released as-is. Fix them in the app and retry.");
+        process.exitCode = 1;
+        return;
+    }
+    if (!args.yes) {
+        console.error(`\nRe-run with --yes to publish v${preview.version}:`);
+        console.error(`  lotics app release ${args.app_id ?? "."} -m ${JSON.stringify(args.changelog)} --yes`);
+        process.exitCode = 1;
+        return;
+    }
+    const result = await client.releasePackage(appId, { changelog: args.changelog });
+    console.error(`Released ${result.package_id} v${result.version}.`);
+    console.error(`  The origin was re-pinned to v${result.version} — verify:  lotics package doctor ${appId}`);
 }
-/**
- * `lotics package fleet-upgrade <package_id> [--version N]` — bring every
- * installation of the package across the caller's org to the target version.
- * Hands-off applies only where the preview is clean; skipped/failed
- * installations are reported per line and the process exits 1 so a release
- * script can gate on "fleet fully current".
- */
 /**
  * `lotics package yank <package_id> <version> [--undo]` — mark a published
  * version uninstallable (or restore it). New installs/upgrades/adopts refuse a
@@ -1871,6 +869,13 @@ export async function packageYank(client, args) {
     }
     console.error(`  Latest installable version: ${result.latest_version === 0 ? "none" : `v${result.latest_version}`}`);
 }
+/**
+ * `lotics upgrade <package_id> [--version N]` (fleet path) — bring every
+ * installation of the package across the caller's org to the target version.
+ * Hands-off applies only where the preview is clean; skipped/failed
+ * installations are reported per line and the process exits 1 so a release
+ * script can gate on "fleet fully current".
+ */
 export async function packageFleetUpgrade(client, args) {
     const result = await client.fleetUpgradePackage(args.package_id, {
         ...(args.version !== undefined ? { version: args.version } : {}),
@@ -1887,7 +892,7 @@ export async function packageFleetUpgrade(client, args) {
         const line = `  [${inst.outcome}] ${inst.workspace_name} — ${inst.app_name} (${from} → v${result.target_version})`;
         if (inst.outcome === "skipped" && inst.blockers) {
             console.error(`${line}: breaking=${inst.blockers.breaking} drift=${inst.blockers.drift} modified=${inst.blockers.modified}`);
-            console.error(`      resolve via:  lotics package upgrade ${inst.app_id} --version ${result.target_version} ...`);
+            console.error(`      resolve via:  lotics upgrade ${inst.app_id} --version ${result.target_version} ...`);
         }
         else if (inst.message) {
             console.error(`${line}: ${inst.message}`);