@lotics/cli 0.75.0 → 0.76.1

package/dist/package_commands.js

@@ -1,6 +1,6 @@
 /**
  * `lotics package *` subcommands — the app-package authoring + dev/test/run loop
- * (see docs/app_packages.md). An app *package* is a versioned, workspace-agnostic
+ * (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:
  *
@@ -24,10 +24,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
 import "./client.js";
-import { buildStarterTemplate, STARTER_FALLBACK_SDK_VERSION } from "./starter_template.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 } from "./app_commands.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";
@@ -37,6 +39,13 @@ const CONTRACT_FILE = "contract.json";
  * 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");
 }
@@ -65,11 +74,51 @@ export function readPackageProject(projectDir) {
             }
         }
     }
+    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/).`);
+            }
+            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 };
@@ -118,7 +167,18 @@ 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: {} },
+        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: {},
+        },
     };
 }
 /**
@@ -140,11 +200,21 @@ export function parseAdoptBindingFile(raw, expectedAppId) {
             `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).
+    // 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;
+        }
+    }
     return {
         app_id: raw.app_id,
         workspace_id: raw.workspace_id,
         binding: raw.binding,
+        knowledge_binding,
     };
 }
 /**
@@ -199,6 +269,133 @@ function readContract(projectDir) {
     }
     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
@@ -242,23 +439,39 @@ export function stagePackageSource(projectDir, sourceStage) {
     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.
+ * 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) {
-    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.`);
-    }
+    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
@@ -328,12 +541,79 @@ export function starterContract(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]` — 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`.
+ * `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));
@@ -341,6 +621,10 @@ export async function packageNew(args) {
         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
@@ -361,6 +645,12 @@ export async function packageNew(args) {
         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") {
@@ -369,7 +659,11 @@ export async function packageNew(args) {
                 id: null,
                 name: args.name,
                 description: null,
+                kind: "app",
                 version: null,
+                knowledge: {},
+                templates: {},
+                knowledge_expects: [],
                 dev: {},
             };
             pkg.lotics = { package: manifest };
@@ -378,7 +672,7 @@ export async function packageNew(args) {
             continue;
         }
         fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-        fs.writeFileSync(fullPath, file.content);
+        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);
@@ -412,12 +706,25 @@ export async function packageBuild(args) {
  */
 async function publishVersion(client, projectDir, opts) {
     const project = readPackageProject(projectDir);
-    const contract = readContract(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.createAppPackage({
+        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;
@@ -426,10 +733,11 @@ async function publishVersion(client, projectDir, opts) {
     }
     const bundle = await buildPackageBundle(projectDir);
     console.error("Publishing version...");
-    const version = await client.publishAppPackageVersion(packageId, {
+    const version = await client.publishPackageVersion(packageId, {
         contract,
         bundle,
         changelog: opts.changelog ?? null,
+        channel: opts.channel ?? "release",
     });
     project.manifest.version = version.version;
     writePackageManifest(projectDir, project);
@@ -487,8 +795,12 @@ async function syncToDevWorkspace(client, projectDir) {
     // 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);
@@ -496,17 +808,35 @@ async function syncToDevWorkspace(client, projectDir) {
     let appId;
     if (existing) {
         console.error(`Upgrading dev installation ${existing.app_id} → v${version}...`);
-        const app = await client.upgradeAppPackage(existing.app_id, { 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 app = await client.installAppPackage(package_id, { version });
-        appId = app.id;
+        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 };
 }
 /**
@@ -583,7 +913,7 @@ export async function packageReset(client, args) {
         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);
+    const app = await client.resetPackage(pin.app_id);
     console.error(`Reset ${app.name} → ${app.id}. The scaffolded tables were dropped and re-created clean.`);
 }
 /**
@@ -641,7 +971,7 @@ export function parseResolveFlags(resolve) {
  */
 export async function packageDoctor(client, args) {
     const app_id = resolveInstallationAppId(client, args.app_id);
-    const health = await client.getAppPackageHealth(app_id);
+    const health = await client.getPackageHealth(app_id);
     console.error(`${health.package_name} — installation ${health.app_id}`);
     console.error(`  Installed: v${health.installed_version}   Latest: v${health.latest_version}` +
         (health.update_available ? "   → update available" : ""));
@@ -669,17 +999,52 @@ export async function packageDoctor(client, args) {
             ` --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) {
+        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)`);
+        }
+    }
+    if (health.knowledge_drift.length > 0 || health.knowledge_modified.length > 0) {
+        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}`);
     }
 }
 /**
- * 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` 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).
  */
 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}` +
@@ -694,6 +1059,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.
@@ -707,9 +1078,31 @@ 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) {
+    // 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);
+    if (args.applyAll) {
+        for (const entry of preview.knowledge) {
+            if (knowledgeEntryNeedsConsent(entry) && knowledgeResolutions[entry.alias] === undefined) {
+                knowledgeResolutions[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);
+    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) {
@@ -722,39 +1115,505 @@ 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 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(args.resolutions).length > 0 ? { resolutions: args.resolutions } : {}),
+        ...(Object.keys(resolutions).length > 0 ? { resolutions } : {}),
+        ...(hasKnowledgeResolutions ? { knowledge_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)
+        return "official Lotics package";
+    if (pkg.owned_by_caller === true)
+        return "your organization's package";
+    return "third-party package (runs under your authority once installed)";
+}
+/**
+ * `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". Kind-agnostic — a
+ * content package shows here the same way.
+ */
+export async function packageShow(client, args) {
+    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}`);
+    if (pkg.retired_at)
+        console.error(`  RETIRED ${pkg.retired_at}`);
+    console.error(`  latest installable: ${pkg.latest_version > 0 ? `v${pkg.latest_version}` : "none"}`);
+    console.error("");
+    for (const v of versions) {
+        const marks = [
+            v.version === pkg.latest_version ? "*" : " ",
+            v.channel === "dev" ? "dev" : "   ",
+            v.yanked_at ? "YANKED" : "      ",
+        ].join(" ");
+        console.log(`${marks} v${v.version}  ${v.created_at}  ${v.changelog ?? ""}`.trimEnd());
+    }
+    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 ${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 };
+}
+/** The `--resolve <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}`;
+}
+/**
+ * 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 <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).
+ */
+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({ knowledge: { resolutions: {}, bind_to: {} }, templates: {} });
+        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)`);
+    }
+    // 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 },
+    };
+    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);
+            }
+        }
+        for (const entry of preview.templates) {
+            if (resolutions.templates[entry.alias] === undefined)
+                resolutions.templates[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);
+    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(pkg.is_official
-        ? `Installing ${pkg.name} — official Lotics package...`
-        : `Installing ${pkg.name} — third-party package (runs under your authority once installed)...`);
-    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.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 package upgrade ${installation.id}`);
+        console.error(`  Uninstall:      lotics package 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.");
+    warnMissingExpectedDocs(knowledge_warnings.missing_expected_docs);
     console.error("  Pull it for local editing:  lotics app pull " + app.id);
 }
+/**
+ * `lotics package uninstall <app_id|pci_id>` — ONE command over both installation
+ * kinds, dispatched by the id form (mirrors `package 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 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).
+ */
+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 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}` +
+            (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.");
     console.error("  Pull the pinned source for local editing:  lotics app pull " + app.id);
 }
+/**
+ * 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 →
+ * boolean, numeric → number, else string) and the server validates it against
+ * the contract.
+ */
+function parseConfigAssignment(entry, flag, knownType) {
+    const eq = entry.indexOf("=");
+    if (eq <= 0 || eq === entry.length - 1) {
+        throw new Error(`Invalid ${flag} "${entry}" — expected key=value.`);
+    }
+    const key = entry.slice(0, eq);
+    const raw = entry.slice(eq + 1);
+    if (knownType === "number") {
+        const n = Number(raw);
+        if (!Number.isFinite(n))
+            throw new Error(`Config key "${key}" is a number knob — "${raw}" is not numeric.`);
+        return { key, value: n };
+    }
+    if (knownType === "boolean") {
+        if (raw !== "true" && raw !== "false") {
+            throw new Error(`Config key "${key}" is a boolean knob — expected true or false, got "${raw}".`);
+        }
+        return { key, value: raw === "true" };
+    }
+    if (knownType === "string")
+        return { key, value: raw };
+    // Inferred (install override): the server re-validates against the contract.
+    if (raw === "true" || raw === "false")
+        return { key, value: raw === "true" };
+    if (/^-?\d+(\.\d+)?$/.test(raw))
+        return { key, value: Number(raw) };
+    return { key, value: raw };
+}
+/** `--config key=value` (install): inferred types, server-validated. */
+export function parseInstallConfigFlags(config) {
+    const out = {};
+    for (const entry of config) {
+        const { key, value } = parseConfigAssignment(entry, "--config");
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * `lotics package config <app_id>` — show the installation's effective config;
+ * with `--set key=value` (repeatable) partial-merge edits, each value parsed by
+ * the knob's current type. No `--set` prints the values.
+ */
+export async function packageConfig(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 — it has no config.`);
+    }
+    const current = app.config ?? {};
+    if (args.sets.length === 0) {
+        const keys = Object.keys(current).sort();
+        if (keys.length === 0) {
+            console.error(`${app.name} (${app.id}) — no config knobs.`);
+            return;
+        }
+        console.error(`${app.name} (${app.id}) config:`);
+        for (const key of keys)
+            console.log(`  ${key} = ${JSON.stringify(current[key])}`);
+        return;
+    }
+    const overrides = {};
+    for (const entry of args.sets) {
+        const key = entry.slice(0, Math.max(0, entry.indexOf("=")));
+        const knownType = typeof current[key];
+        const { value } = parseConfigAssignment(entry, "--set", knownType === "number" || knownType === "boolean" || knownType === "string" ? knownType : undefined);
+        overrides[key] = value;
+    }
+    const { config } = await client.updateAppPackageConfig(args.app_id, { config: overrides });
+    console.error(`Updated config for ${app.name} (${app.id}):`);
+    for (const key of Object.keys(config).sort()) {
+        const marker = key in overrides ? " *" : "";
+        console.log(`  ${key} = ${JSON.stringify(config[key])}${marker}`);
+    }
+}
+/**
+ * `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.retirePackage(args.package_id, { 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.`);
+    }
+    else {
+        console.error(`Un-retired ${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,
+ * 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
@@ -764,28 +1623,57 @@ export async function packageEject(client, args) {
  * Exits non-zero when any `error` finding exists — the draft is written, but
  * publish re-validates and nothing should ship unreviewed.
  */
+/**
+ * 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 extracted = await client.extractAppPackage(args.app_id);
-    const { lines, hasError } = formatExtractReport(extracted.report);
-    if (lines.length > 0) {
-        console.error(`Extraction report (${extracted.report.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).
+    // 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`);
@@ -799,10 +1687,31 @@ export async function packageExtract(client, args) {
         if (fs.existsSync(tmpFile))
             fs.unlinkSync(tmpFile);
     }
+    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}):`);
+        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 appPkgJson = JSON.parse(fs.readFileSync(packageJsonPath(targetPath), "utf-8"));
     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).
@@ -865,11 +1774,26 @@ export async function packageExtract(client, args) {
             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.
+    // 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 }, null, 2) + "\n");
+    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);
@@ -887,7 +1811,7 @@ export async function packageExtract(client, args) {
 }
 /**
  * `lotics package adopt <app_id> [path]` — bind the published package project
- * onto the origin app (docs/app_packages.md § Promotion). Reads the 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
@@ -910,10 +1834,15 @@ export async function packageAdopt(client, args) {
             `"lotics package extract" recorded — run extract to produce this project.`);
     }
     const pin = parseAdoptBindingFile(JSON.parse(fs.readFileSync(bindingPath, "utf-8")), args.app_id);
-    const app = await client.adoptAppPackage(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}`);
@@ -932,7 +1861,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.`);
@@ -943,7 +1872,7 @@ export async function packageYank(client, args) {
     console.error(`  Latest installable version: ${result.latest_version === 0 ? "none" : `v${result.latest_version}`}`);
 }
 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}:`);