@lotics/cli 0.76.0 → 0.83.0

package/dist/package_commands.js

@@ -1,158 +1,76 @@
 /**
- * `lotics package *` subcommands — the app-package authoring + dev/test/run loop
- * (see docs/app_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 "./client.js";
-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";
+import { knowledgeEntryNeedsConsent, validKnowledgeResolutions, } from "@lotics/shared/schemas/packages";
 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 };
+        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 });
             }
         }
     }
-    const manifest = {
-        id: typeof pkg.id === "string" ? pkg.id : null,
-        name: pkg.name,
-        description: typeof pkg.description === "string" ? pkg.description : null,
-        version: typeof pkg.version === "number" ? pkg.version : null,
-        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 },
-    };
-}
-/**
- * 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, version: null, dev: {} },
-    };
+    return { app_id, knowledge };
 }
-/**
- * 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 map straight to the server (the validating authority).
-    return {
-        app_id: raw.app_id,
-        workspace_id: raw.workspace_id,
-        binding: raw.binding,
-    };
+/** 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 { 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"];
@@ -161,500 +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.
- */
-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"));
-}
 /**
- * (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.
+ * Resolve the installation to operate on: an explicit app id is required (there
+ * is no dev-workspace pin to fall back to).
  */
-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: `npm run build` (vite → dist/), then 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. Returns the bytes.
- */
-async function buildPackageBundle(projectDir) {
-    console.error("Building...");
-    await runNpm(["run", "build"], projectDir);
-    const 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.`);
-    }
-    // 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 {
-        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 },
-        ],
-    };
-}
-/**
- * `lotics package new <name> [path]` — scaffold a package project. 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`. The project publishes
- * with `lotics package publish` and runs against a dev workspace with
- * `lotics package dev`.
- */
-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 });
-    // 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,
-                version: null,
-                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 contract = readContract(projectDir);
-    let packageId = project.manifest.id;
-    if (packageId === null) {
-        const pkg = await client.createAppPackage({
-            name: project.manifest.name,
-            description: project.manifest.description,
-        });
-        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.publishAppPackageVersion(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.upgradeAppPackage(existing.app_id, { version });
-        appId = app.id;
-    }
-    else {
-        console.error(`Installing ${package_id} v${version} into dev workspace ${devWorkspaceId}...`);
-        const app = await client.installAppPackage(package_id, { version });
-        appId = 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.resetAppPackage(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;
 }
@@ -663,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 health = await client.getAppPackageHealth(app_id);
-    console.error(`${health.package_name} — installation ${health.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}` +
+        (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) {
@@ -676,33 +132,91 @@ 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;
     }
+    // Package-managed knowledge (bundled with this app install): drift + local edits
+    // + unmet expects. All advisory; resolved through the app's package upgrade.
+    if (health.knowledge_drift.length > 0) {
+        console.error(`  Knowledge binding drift (${health.knowledge_drift.length}):`);
+        for (const d of health.knowledge_drift) {
+            console.error(`    - ${d.alias} "${d.name}" → ${d.doc_id ?? "(unbound)"} (missing from the workspace)`);
+        }
+    }
+    if (health.knowledge_modified.length > 0) {
+        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) {
+        console.error(`  Missing expected knowledge docs (${health.missing_expected_docs.length}):`);
+        for (const name of health.missing_expected_docs) {
+            console.error(`    - "${name}" (the package's agents route to this name; no matching doc exists)`);
+        }
+    }
+    // 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 &&
+        health.knowledge_modified.length === 0 &&
+        health.missing_expected_docs.length === 0) {
+        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}`);
     }
 }
 /**
- * Preview-then-apply upgrade. Prints the additive plan + informational
- * removals; refuses (exit 1, with the exact --resolve syntax) while any
- * binding drift lacks a resolution.
+ * Preview-then-apply an app-installation upgrade. Prints the additive plan +
+ * informational removals + any bundled-knowledge changes; refuses (exit 1, with
+ * the exact --resolve syntax) while any binding drift, modified core artifact, or
+ * consent-requiring bundled-knowledge doc lacks a resolution.
+ *
+ * `--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.previewAppPackageUpgrade(args.app_id, {
+    const preview = await client.previewPackageUpgrade(args.app_id, {
         ...(args.version !== undefined ? { version: args.version } : {}),
     });
     console.error(`Upgrade v${preview.from_version} → v${preview.to_version}` +
@@ -717,6 +231,12 @@ export async function packageUpgrade(client, args) {
         console.error(`  Adds: ${added}`);
     if (removed)
         console.error(`  Unbinds (workspace data kept): ${removed}`);
+    if (preview.knowledge.length > 0) {
+        console.error(`  Knowledge docs (${preview.knowledge.length}):`);
+        for (const entry of preview.knowledge) {
+            console.error(`    ${formatKnowledgeEntryLine(entry)}`);
+        }
+    }
     // Breaking contract changes are NOT resolvable via --resolve — scaffold would
     // refuse them on a bound alias, and there is no in-flow remediation. Report
     // every entry and the only two real remedies, then hard-stop.
@@ -730,9 +250,26 @@ export async function packageUpgrade(client, args) {
             `  before making the change:  lotics package eject ${args.app_id}`);
         process.exit(1);
     }
-    const unresolvedDrift = preview.drift.filter((d) => args.resolutions[`${d.namespace}.${d.alias}`] === undefined);
-    const unresolvedModified = preview.modified.filter((m) => args.resolutions[`${m.kind}.${m.alias}`] === undefined);
-    if (unresolvedDrift.length > 0 || unresolvedModified.length > 0) {
+    // 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) && resolutions[`knowledge.${entry.alias}`] === undefined) {
+                resolutions[`knowledge.${entry.alias}`] = knowledgeAcceptResolution(entry.change);
+            }
+        }
+    }
+    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) && resolutions[`knowledge.${e.alias}`] === undefined);
+    if (unresolvedDrift.length > 0 ||
+        unresolvedModified.length > 0 ||
+        unresolvedKnowledge.length > 0) {
         if (unresolvedDrift.length > 0) {
             console.error("  Binding drift must be resolved before upgrading:");
             for (const d of unresolvedDrift) {
@@ -745,14 +282,33 @@ export async function packageUpgrade(client, args) {
                 console.error(`    --resolve ${m.kind}.${m.alias}=revert   (overwrite the local edit; or =keep to retain it)`);
             }
         }
+        if (unresolvedKnowledge.length > 0) {
+            console.error("  Bundled knowledge docs need consent before upgrading (or --apply-all to accept the package's version for all):");
+            for (const entry of unresolvedKnowledge) {
+                console.error(formatKnowledgeResolveHint(entry));
+            }
+        }
         process.exit(1);
     }
-    const app = await client.upgradeAppPackage(args.app_id, {
+    const app = await client.upgradePackage(args.app_id, {
         ...(args.version !== undefined ? { version: args.version } : {}),
-        ...(Object.keys(args.resolutions).length > 0 ? { resolutions: args.resolutions } : {}),
+        ...(Object.keys(resolutions).length > 0 ? { resolutions } : {}),
     });
     console.error(`Upgraded ${app.name} → v${app.package_version} (${app.id}).`);
 }
+/** `--apply-all`'s accept-the-package resolution for a consent-requiring entry. */
+function knowledgeAcceptResolution(change) {
+    switch (change) {
+        case "changed":
+            return "apply";
+        case "removed":
+            return "archive";
+        case "drifted":
+            return "recreate";
+        case "added":
+            return "apply"; // unreachable (added never needs consent), kept total.
+    }
+}
 /** The install-consent trust line: official > your own org > third-party. */
 function trustBadge(pkg) {
     if (pkg.is_official)
@@ -764,11 +320,12 @@ function trustBadge(pkg) {
 /**
  * `lotics package show <package_id>` — registry metadata + version history
  * (trust badge, retirement, per-version channel/yank/changelog). The read
- * surface for "what is this package and what shipped when".
+ * surface for "what is this package and what shipped when". Kind-agnostic — a
+ * content package shows here the same way.
  */
 export async function packageShow(client, args) {
-    const pkg = await client.getAppPackage(args.package_id);
-    const { versions } = await client.listAppPackageVersions(args.package_id);
+    const pkg = await client.getPackage(args.package_id);
+    const { versions } = await client.listPackageVersions(args.package_id);
     console.error(`${pkg.name} (${pkg.id}) — ${trustBadge(pkg)}`);
     if (pkg.description)
         console.error(`  ${pkg.description}`);
@@ -787,22 +344,260 @@ export async function packageShow(client, args) {
     if (versions.length === 0)
         console.error("  (no published versions)");
 }
+/**
+ * One preview line for a knowledge upgrade entry — `[change] alias "name"` with
+ * `modified` / `needs consent` marks. Shared verbatim by the standalone (`pci_`)
+ * and the app-install upgrade previews so both speak one vocabulary; the caller
+ * owns the leading indent.
+ */
+function formatKnowledgeEntryLine(entry) {
+    const marks = [
+        entry.modified ? "modified" : null,
+        knowledgeEntryNeedsConsent(entry) ? "needs consent" : null,
+    ].filter((m) => m !== null);
+    return `[${entry.change}] ${entry.alias} "${entry.name}"${marks.length ? ` (${marks.join(", ")})` : ""}`;
+}
+/**
+ * The exact `--resolve <alias>=<valid options>` remediation line for a
+ * consent-requiring knowledge entry (options from the shared
+ * `validKnowledgeResolutions`). Shared by both upgrade paths' gate output.
+ */
+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 knowledge.${entry.alias}=${validKnowledgeResolutions(entry.change).join("|")}${note}`;
+}
+/** 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 template.${entry.alias}=revert|keep${note}`;
+}
+/**
+ * Preview-then-apply a STANDALONE content installation upgrade — knowledge docs
+ * AND document templates behind one review gate. Prints the per-alias plan;
+ * refuses (exit 1, with the exact `--resolve` syntax) while any consent-requiring
+ * entry lacks a resolution — a modified knowledge change/removal or drift, or a
+ * 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 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, {
+        ...(args.version !== undefined ? { version: args.version } : {}),
+    });
+    console.error(`Content upgrade v${preview.from_version} → v${preview.to_version}` +
+        (preview.changelog ? ` — ${preview.changelog}` : ""));
+    const apply = async (resolutions) => {
+        const updated = await client.applyContentInstallationUpgrade(args.installation_id, {
+            ...(args.version !== undefined ? { version: args.version } : {}),
+            resolutions,
+        });
+        console.error(`Upgraded ${args.installation_id} → v${updated.package_version}.`);
+    };
+    if (preview.entries.length === 0 && preview.templates.length === 0) {
+        if (preview.to_version === preview.from_version) {
+            console.error("  Already up to date — no content changes.");
+            return;
+        }
+        console.error("  No changes needing consent — advancing the version pin; clean template updates apply automatically.");
+        await apply({});
+        return;
+    }
+    for (const entry of preview.entries) {
+        console.error(`  ${formatKnowledgeEntryLine(entry)}`);
+    }
+    for (const entry of preview.templates) {
+        console.error(`  [template] ${entry.alias} (modified — needs consent)`);
+    }
+    // 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.${entry.alias}`] === undefined) {
+                resolutions[`knowledge.${entry.alias}`] = knowledgeAcceptResolution(entry.change);
+            }
+        }
+        for (const entry of preview.templates) {
+            if (resolutions[`template.${entry.alias}`] === undefined) {
+                resolutions[`template.${entry.alias}`] = "revert";
+            }
+        }
+    }
+    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)
+            console.error(formatKnowledgeResolveHint(entry));
+        for (const entry of unresolvedTemplates)
+            console.error(formatTemplateResolveHint(entry));
+        process.exit(1);
+    }
+    await apply(resolutions);
+}
+/** Parse repeated `--bind-to alias=kdc_id` flags into an alias → doc-id consent map. */
+export function parseBindToFlags(bindTo) {
+    const map = {};
+    for (const entry of bindTo) {
+        const eq = entry.indexOf("=");
+        if (eq <= 0 || eq === entry.length - 1) {
+            throw new Error(`Invalid --bind-to "${entry}" — expected <alias>=<kdc_id>.`);
+        }
+        map[entry.slice(0, eq)] = entry.slice(eq + 1);
+    }
+    return map;
+}
+/** Print advisory `knowledge_expects` misses loudly (never blocks the install). */
+function warnMissingExpectedDocs(missing) {
+    if (missing.length === 0)
+        return;
+    console.error(`  ⚠ ${missing.length} expected knowledge doc(s) the package's agents route to are missing from this workspace:`);
+    for (const name of missing)
+        console.error(`      - "${name}"`);
+    console.error("    The package installed, but those agents will degrade until a doc with each name exists.");
+}
 export async function packageInstall(client, args) {
     // Surface the trust badge at the consent point: installing materializes the
-    // package's workflows/agents under YOUR authority, so say whose package it is.
-    const pkg = await client.getAppPackage(args.package_id);
-    console.error(`Installing ${pkg.name} — ${trustBadge(pkg)}...`);
-    const app = await client.installAppPackage(args.package_id, {
+    // package's workflows/agents (or its doc corpus) under YOUR authority.
+    const pkg = await client.getPackage(args.package_id);
+    const kindLabel = pkg.kind === "content" ? "content package" : "package";
+    console.error(`Installing ${pkg.name} — ${trustBadge(pkg)} (${kindLabel})...`);
+    const result = await client.installPackage(args.package_id, {
         ...(args.version !== undefined ? { version: args.version } : {}),
-        ...(args.config !== undefined ? { config: args.config } : {}),
+        ...(args.bind_to && Object.keys(args.bind_to).length > 0 ? { bind_to: args.bind_to } : {}),
+        ...(args.config && Object.keys(args.config).length > 0 ? { config: args.config } : {}),
     });
+    if (result.kind === "content") {
+        const { installation, warnings } = result;
+        const docs = installation.binding.knowledge;
+        const templates = installation.binding.templates;
+        console.error(`Installed ${pkg.name} v${installation.package_version} → content installation ${installation.id} ` +
+            `(workspace ${installation.workspace_id}).`);
+        const docAliases = Object.keys(docs);
+        if (docAliases.length > 0) {
+            console.error(`  ${docAliases.length} doc(s) live: ${docAliases.map((a) => `${a}→${docs[a]}`).join(", ")}`);
+        }
+        const templateAliases = Object.keys(templates);
+        if (templateAliases.length > 0) {
+            console.error(`  ${templateAliases.length} template(s) live: ${templateAliases.map((a) => `${a}→${templates[a]}`).join(", ")}`);
+        }
+        warnMissingExpectedDocs(warnings.missing_expected_docs);
+        console.error(`  Upgrade later:  lotics upgrade ${installation.id}`);
+        console.error(`  Uninstall:      lotics uninstall ${installation.id} [--keep-content]`);
+        return;
+    }
+    const { app, knowledge_warnings } = result;
     const versionLabel = app.package_version !== null ? `v${app.package_version}` : "(unknown version)";
     console.error(`Installed ${app.name} ${versionLabel} → ${app.id} (workspace ${app.workspace_id}).`);
     console.error("  The data model, queries, workflows, and agents are live.");
-    console.error("  Pull it for local editing:  lotics app pull " + app.id);
+    warnMissingExpectedDocs(knowledge_warnings.missing_expected_docs);
+    // 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 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.
+ *   - anything else (an `app_id`) → an APP installation: archives its workflow
+ *     artifacts and — with `--archive-tables` — the scaffolded entity tables
+ *     (provenance- + reference-gated server-side).
+ * A flag used on the wrong path is a loud error, never silently ignored.
+ */
+export async function packageUninstall(client, args) {
+    if (args.id.startsWith("pci_")) {
+        if (args.archive_tables) {
+            throw new Error("--archive-tables applies only to an app installation (<app_id>). A content installation " +
+                "(pci_) has no scaffolded tables — use --keep-content to retain its docs/templates.");
+        }
+        const result = await client.uninstallContentPackage(args.id, {
+            keep_content: args.keep_content,
+        });
+        if (args.keep_content) {
+            console.error(`Uninstalled content installation ${result.installation_id} — its docs and templates were kept as ordinary workspace content.`);
+        }
+        else {
+            console.error(`Uninstalled content installation ${result.installation_id} — archived ` +
+                `${result.archived_doc_ids.length} doc(s) and ${result.archived_template_ids.length} template(s).`);
+            for (const docId of result.archived_doc_ids)
+                console.error(`    ${docId}`);
+            for (const templateId of result.archived_template_ids)
+                console.error(`    ${templateId}`);
+        }
+        return;
+    }
+    if (args.keep_content) {
+        throw new Error("--keep-content applies only to a standalone content installation (pci_). An app installation " +
+            "(<app_id>) uses --archive-tables to also archive its scaffolded tables.");
+    }
+    const app = await client.getApp(args.id);
+    if (!app.package_id) {
+        throw new Error(`App ${args.id} is not a package installation — use the app delete flow for a bespoke app.`);
+    }
+    const lifecycleCount = Object.keys(app.binding?.workflows ?? {}).length;
+    const boundCount = Object.keys(app.workflows ?? {}).length;
+    const tableCount = Object.keys(app.binding?.entities ?? {}).length;
+    console.error(`Uninstalling ${app.name} (${app.id}):`);
+    console.error(`  Archives ${boundCount + lifecycleCount} workflow(s) (${boundCount} app, ${lifecycleCount} lifecycle).`);
+    console.error(args.archive_tables
+        ? `  Archives ${tableCount} scaffolded table(s) — refused if they were adopted or are still referenced.`
+        : `  Leaves the data model (${tableCount} table(s)) intact. Pass --archive-tables to also archive them.`);
+    const result = await client.uninstallAppPackage(args.id, {
+        archive_tables: args.archive_tables,
+    });
+    console.error(`Uninstalled ${app.name} (${app.id}).`);
+    if (result.archived_table_ids.length > 0) {
+        console.error(`  Archived tables: ${result.archived_table_ids.join(", ")}`);
+    }
+}
+/**
+ * `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();
+    if (!workspaceId) {
+        throw new Error("No workspace selected. Pass --workspace <ws> (or select one) to list its content installations.");
+    }
+    const installations = await client.listContentInstallations(workspaceId);
+    if (installations.length === 0) {
+        console.error(`No package-managed content installations in workspace ${workspaceId}.`);
+        return;
+    }
+    console.error(`Content installations in workspace ${workspaceId} (${installations.length}):`);
+    for (const inst of installations) {
+        const name = inst.package_registry?.name ?? "(unknown package)";
+        const latest = inst.package_registry?.latest_version;
+        const updateAvailable = inst.package_registry?.update_available ?? false;
+        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}` +
+            (updateAvailable ? "  → update available" : ""));
+    }
 }
 export async function packageEject(client, args) {
-    const app = await client.ejectAppPackage(args.app_id);
+    const app = await client.ejectPackage(args.app_id);
     console.error(`Ejected ${app.name} → ${app.id} (workspace ${app.workspace_id}).`);
     console.error("  The package link is severed — it's now a normal bespoke app and can no longer be upgraded.");
     console.error("  Its data model, queries, workflows, and templates are unchanged.");
@@ -811,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.
  */
@@ -889,218 +684,174 @@ export async function packageConfig(client, args) {
     }
 }
 /**
- * `lotics package uninstall <app_id> [--archive-tables]` — remove a package
- * installation. Prints what will be archived (workflow artifacts, plus the
- * scaffolded tables when the flag is set), then uninstalls.
+ * `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 packageUninstall(client, args) {
-    const app = await client.getApp(args.app_id);
-    if (!app.package_id) {
-        throw new Error(`App ${args.app_id} is not a package installation — use the app delete flow for a bespoke app.`);
-    }
-    const lifecycleCount = Object.keys(app.binding?.workflows ?? {}).length;
-    const boundCount = Object.keys(app.workflows ?? {}).length;
-    const tableCount = Object.keys(app.binding?.entities ?? {}).length;
-    console.error(`Uninstalling ${app.name} (${app.id}):`);
-    console.error(`  Archives ${boundCount + lifecycleCount} workflow(s) (${boundCount} app, ${lifecycleCount} lifecycle).`);
-    console.error(args.archive_tables
-        ? `  Archives ${tableCount} scaffolded table(s) — refused if they were adopted or are still referenced.`
-        : `  Leaves the data model (${tableCount} table(s)) intact. Pass --archive-tables to also archive them.`);
-    const result = await client.uninstallAppPackage(args.app_id, {
-        archive_tables: args.archive_tables,
-    });
-    console.error(`Uninstalled ${app.name} (${app.id}).`);
-    if (result.archived_table_ids.length > 0) {
-        console.error(`  Archived tables: ${result.archived_table_ids.join(", ")}`);
+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;
     }
-}
-/**
- * `lotics package retire <package_id> [--undo]` — retire (or un-retire) a
- * registry package. Owner-org admin-only.
- */
-export async function packageRetire(client, args) {
-    const pkg = await client.retireAppPackage(args.package_id, { undo: args.undo });
+    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/app_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).
  */
-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.`);
+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.)");
+    }
+    else {
+        console.error("  No renamable aliases.");
     }
-    const extracted = await client.extractAppPackage(args.app_id);
-    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.");
-    }
-    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 — same mechanics as `lotics app pull`
-    // (getAppVersion → presigned source URL → download → untar into the project).
-    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);
-    }
-    finally {
-        if (fs.existsSync(tmpFile))
-            fs.unlinkSync(tmpFile);
-    }
-    // Swap the app manifest (lotics.app_id/workspace_id) for a fresh, unpublished
-    // package manifest — atomic write via the existing manifest writer.
-    const appPkgJson = JSON.parse(fs.readFileSync(packageJsonPath(targetPath), "utf-8"));
-    const draft = draftPackageProjectFromApp(appPkgJson, { name: app.name, description: null });
-    // 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}`);
-    }
-    // The origin pin the `adopt` step reads back. `.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 }, 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;
     }
-    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)`);
+    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;
+    }
+    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/app_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.adoptAppPackage(args.app_id, {
-        package_id: manifest.id,
-        version,
-        binding: pin.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
@@ -1108,7 +859,7 @@ export async function packageAdopt(client, args) {
  * running. Owner-org admin-only.
  */
 export async function packageYank(client, args) {
-    const result = await client.yankAppPackageVersion(args.package_id, args.version, !args.undo);
+    const result = await client.yankPackageVersion(args.package_id, args.version, !args.undo);
     if (result.yanked_at !== null) {
         console.error(`Yanked ${result.package_id} v${result.version} (${result.yanked_at}). ` +
             `New installs/upgrades refuse it; pinned installations keep running.`);
@@ -1118,8 +869,15 @@ 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.fleetUpgradeAppPackage(args.package_id, {
+    const result = await client.fleetUpgradePackage(args.package_id, {
         ...(args.version !== undefined ? { version: args.version } : {}),
     });
     console.error(`Fleet upgrade of ${result.package_id} → v${result.target_version}:`);
@@ -1134,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}`);