@lotics/cli 0.86.1 → 0.86.2

package/dist/cli.js

@@ -127,7 +127,7 @@ COMMANDS
                                        <alias>=apply|keep|archive|recreate|unbind); an APP package
                                        FLEET-upgrades every installation across your org (clean
                                        apply, findings skip). --apply-all accepts the package's version
-  lotics package doctor [app_id]       Installation health: version pin vs latest, binding
+  lotics package doctor [app_id|package_id]  Installation health: version pin vs latest, binding
                                        drift, locally modified core, knowledge drift/edits
                                        (exit 1 on findings)
   lotics package config <app_id> [--set key=value ...]
@@ -717,7 +717,7 @@ async function main() {
         console.error("    lotics install <package_id> [--version N] [--bind-to <alias>=<kdc_id>] [--config key=value ...]   Install a package (app or content)");
         console.error("    lotics uninstall <app_id|package_id> [--archive-tables] [--keep-content]   Uninstall — dispatched by id (app vs content)");
         console.error("    lotics upgrade <app_id|package_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]   Upgrade — app install / content install / whole app fleet (apg_)");
-        console.error("  lotics package doctor [app_id]                   Health: version pin vs latest + binding/knowledge drift");
+        console.error("  lotics package doctor [app_id|package_id]        Health: version pin vs latest + binding/knowledge drift (apg_ = this workspace's content install)");
         console.error("  lotics package config <app_id> [--set key=value ...]   Show or edit an installation's config knobs");
         console.error("  lotics package eject <app_id>                    Sever an installation's package link");
         console.error("  lotics package show <package_id>                 Registry metadata + version history (channel, yank, changelog)");

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeUpgradeEntry, ModifiedArtifact, PackageContentBinding, UpgradeResolutions } from "@lotics/shared/schemas/packages";
+import type { ContractConfigEntry, KnowledgeUpgradeEntry, ModifiedArtifact, PackageContentBinding, UpgradeResolutions } from "@lotics/shared/schemas/packages";
 /**
  * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
  * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any
@@ -385,6 +385,7 @@ export declare class LoticsClient {
                 breaking: number;
                 drift: number;
                 modified: number;
+                knowledge: number;
             };
             message?: string;
         }>;
@@ -555,6 +556,8 @@ export declare class LoticsClient {
             alias: string;
             doc_id: string;
         }>;
+        /** Config knob declarations re-declaring the config (from the manifest). */
+        config?: ContractConfigEntry[];
     }): Promise<{
         package_id: string;
         version: number;
@@ -566,6 +569,12 @@ export declare class LoticsClient {
             removed: string[];
             changed: string[];
         };
+        /** Absent from a pre-declaration server (deploy skew) — treat as empty delta. */
+        config?: {
+            added: string[];
+            removed: string[];
+            changed: string[];
+        };
         findings: ExtractFinding[];
     }>;
     /**
@@ -585,6 +594,8 @@ export declare class LoticsClient {
             alias: string;
             doc_id: string;
         }>;
+        /** Config knob declarations re-declaring the config (from the manifest). */
+        config?: ContractConfigEntry[];
     }): Promise<{
         package_id: string;
         version: number;
@@ -596,6 +607,12 @@ export declare class LoticsClient {
             removed: string[];
             changed: string[];
         };
+        /** Absent from a pre-declaration server (deploy skew) — treat as empty delta. */
+        config?: {
+            added: string[];
+            removed: string[];
+            changed: string[];
+        };
     }>;
     /**
      * Dry-run preview of a first-release — the `GET` behind `lotics app publish`
@@ -615,6 +632,8 @@ export declare class LoticsClient {
             alias: string;
             doc_id: string;
         }>;
+        /** Config knob declarations v1 would freeze (from the manifest's `lotics.config`). */
+        config?: ContractConfigEntry[];
     }): Promise<{
         app_id: string;
         package_name: string;
@@ -649,6 +668,8 @@ export declare class LoticsClient {
             alias: string;
             doc_id: string;
         }>;
+        /** Config knob declarations v1 freezes (from the manifest's `lotics.config`). */
+        config?: ContractConfigEntry[];
     }): Promise<{
         package_id: string;
         version: number;

package/dist/client.js

@@ -365,6 +365,9 @@ export class LoticsClient {
         if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
             params.set("knowledge", JSON.stringify(opts.knowledge));
         }
+        if (opts.config !== undefined) {
+            params.set("config", JSON.stringify(opts.config));
+        }
         const query = params.toString();
         return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-release${query ? `?${query}` : ""}`);
     }
@@ -394,6 +397,9 @@ export class LoticsClient {
         if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
             params.set("knowledge", JSON.stringify(opts.knowledge));
         }
+        if (opts.config !== undefined && opts.config.length > 0) {
+            params.set("config", JSON.stringify(opts.config));
+        }
         if (opts.renames !== undefined && opts.renames.length > 0) {
             params.set("renames", JSON.stringify(opts.renames));
         }

package/dist/package_commands.d.ts

@@ -1,13 +1,17 @@
 import { LoticsClient, type ExtractFinding } from "./client.js";
-import { type UpgradeResolutions } from "@lotics/shared/schemas/packages";
+import { type ContractConfigEntry, type UpgradeResolutions } from "@lotics/shared/schemas/packages";
 /**
  * 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.
+ * `lotics.knowledge` + `lotics.config`) — what `lotics app pull` writes.
+ * `lotics app publish` / `release` run from a pulled app project resolve the app
+ * id from it and forward the package-managed knowledge declaration AND the config
+ * knob declarations to the server — both are declarations extract cannot invert
+ * from artifacts (agents reference docs by free text; a config knob has no concrete
+ * artifact), so the author declares them. Each `lotics.config` entry is validated
+ * against the shared `contractConfigEntrySchema` so a malformed knob fails LOUDLY
+ * client-side naming the alias, never silently dropped. Returns null when the dir
+ * has no package.json. `app_id` is null when the manifest is a package/non-app
+ * project.
  */
 export declare function readLocalAppManifest(projectDir: string): {
     app_id: string | null;
@@ -15,6 +19,7 @@ export declare function readLocalAppManifest(projectDir: string): {
         alias: string;
         doc_id: string;
     }>;
+    config: ContractConfigEntry[];
 } | null;
 /** Parse repeated `--rename old=new` flags into `{ from, to }[]` (first-publish alias fixes). */
 export declare function parseRenameFlags(renames: string[]): Array<{
@@ -43,7 +48,9 @@ export declare function formatExtractReport(report: ExtractFinding[]): {
 export declare function parseResolveFlags(resolve: string[]): UpgradeResolutions;
 /**
  * Health check: version pin vs. registry latest + binding drift. Exits
- * non-zero when drift is found so scripts can gate on it.
+ * non-zero when drift is found so scripts can gate on it. An `apg_` PACKAGE id
+ * resolves THIS workspace's standalone content installation — the same
+ * package-id addressing `upgrade`/`uninstall` speak.
  */
 export declare function packageDoctor(client: LoticsClient, args: {
     app_id?: string;

package/dist/package_commands.js

@@ -21,7 +21,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import "./client.js";
-import { knowledgeEntryNeedsConsent, validKnowledgeResolutions, } from "@lotics/shared/schemas/packages";
+import { contractConfigEntrySchema, knowledgeEntryNeedsConsent, validKnowledgeResolutions, } from "@lotics/shared/schemas/packages";
 function packageJsonPath(projectDir) {
     return path.join(projectDir, "package.json");
 }
@@ -30,12 +30,16 @@ function isPlainObject(value) {
 }
 /**
  * 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.
+ * `lotics.knowledge` + `lotics.config`) — what `lotics app pull` writes.
+ * `lotics app publish` / `release` run from a pulled app project resolve the app
+ * id from it and forward the package-managed knowledge declaration AND the config
+ * knob declarations to the server — both are declarations extract cannot invert
+ * from artifacts (agents reference docs by free text; a config knob has no concrete
+ * artifact), so the author declares them. Each `lotics.config` entry is validated
+ * against the shared `contractConfigEntrySchema` so a malformed knob fails LOUDLY
+ * client-side naming the alias, never silently dropped. 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);
@@ -54,7 +58,19 @@ export function readLocalAppManifest(projectDir) {
             }
         }
     }
-    return { app_id, knowledge };
+    const config = [];
+    if (Array.isArray(lotics.config)) {
+        for (const entry of lotics.config) {
+            const result = contractConfigEntrySchema.safeParse(entry);
+            if (!result.success) {
+                const alias = isPlainObject(entry) && typeof entry.alias === "string" ? entry.alias : "?";
+                throw new Error(`Invalid lotics.config knob "${alias}" in package.json: ` +
+                    result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; "));
+            }
+            config.push(result.data);
+        }
+    }
+    return { app_id, knowledge, config };
 }
 /** Parse repeated `--rename old=new` flags into `{ from, to }[]` (first-publish alias fixes). */
 export function parseRenameFlags(renames) {
@@ -115,9 +131,15 @@ export function parseResolveFlags(resolve) {
 }
 /**
  * Health check: version pin vs. registry latest + binding drift. Exits
- * non-zero when drift is found so scripts can gate on it.
+ * non-zero when drift is found so scripts can gate on it. An `apg_` PACKAGE id
+ * resolves THIS workspace's standalone content installation — the same
+ * package-id addressing `upgrade`/`uninstall` speak.
  */
 export async function packageDoctor(client, args) {
+    if (args.app_id !== undefined && args.app_id.startsWith("apg_")) {
+        await contentDoctor(client, args.app_id);
+        return;
+    }
     const app_id = resolveInstallationAppId(args.app_id);
     const health = await client.getPackageHealth(app_id);
     console.error(`${health.package_name} — installation ${health.app_id}` +
@@ -376,6 +398,47 @@ function formatTemplateResolveHint(entry) {
         : "   (a local edit — revert overwrites it with the package's version; keep retains it)";
     return `    --resolve template.${entry.alias}=revert|keep${note}`;
 }
+/**
+ * Health report for a STANDALONE content installation, addressed by PACKAGE id.
+ * Composed client-side from the surfaces the consumer verbs already speak: the
+ * list row (pin vs registry latest) and the upgrade preview against latest
+ * (which carries per-alias drift + local-edit detection even when the pin is
+ * current — the repair view). Exits non-zero on drift, mirroring the app
+ * doctor's gate semantics.
+ */
+async function contentDoctor(client, package_id) {
+    const installation = await resolveWorkspaceContentInstallation(client, package_id);
+    const preview = await client.previewContentInstallationUpgrade(installation.id, {});
+    const name = installation.package_registry?.name ?? package_id;
+    console.error(`${name} — content installation of ${package_id} (this workspace)`);
+    console.error(`  Installed: v${preview.from_version}   Latest: v${preview.to_version}` +
+        (preview.to_version > preview.from_version ? "   → update available" : ""));
+    const drifted = preview.entries.filter((e) => e.change === "drifted");
+    if (drifted.length === 0) {
+        console.error("  Binding: healthy — every bound doc resolves.");
+    }
+    else {
+        console.error(`  Binding drift (${drifted.length}):`);
+        for (const entry of drifted) {
+            console.error(`    - knowledge.${entry.alias} "${entry.name}" (bound doc is gone)`);
+        }
+        console.error(`  Resolve while upgrading:\n    lotics upgrade ${package_id}` +
+            ` --resolve knowledge.<alias>=recreate|unbind   (or --bind-to <alias>=<kdc_id> to re-point)`);
+        process.exitCode = 1;
+    }
+    const editedDocs = preview.entries.filter((e) => e.modified);
+    const editedTemplates = preview.templates;
+    if (editedDocs.length === 0 && editedTemplates.length === 0) {
+        console.error("  Content: pristine — no local edits an upgrade would ask about.");
+    }
+    else {
+        console.error(`  Local edits (${editedDocs.length + editedTemplates.length}) — each takes a keep/overwrite consent at upgrade:`);
+        for (const entry of editedDocs)
+            console.error(`    - knowledge.${entry.alias} "${entry.name}"`);
+        for (const entry of editedTemplates)
+            console.error(`    - template.${entry.alias}`);
+    }
+}
 /**
  * Resolve a STANDALONE content package's installation in the CURRENT workspace
  * from its PACKAGE id. `UNIQUE (workspace_id, package_id)` means the package id
@@ -816,16 +879,17 @@ export async function appPublish(client, args) {
         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.
+    // Forward the app's package-managed knowledge + config declarations ONLY when the
+    // local manifest is this app's own project (both are declarations extract can't
+    // invert, so the author declares them). A bare id published from elsewhere ships
+    // without them — publish from the app dir to include them.
     const knowledge = local && local.app_id === appId ? local.knowledge : [];
+    const config = local && local.app_id === appId ? local.config : [];
     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 preview = await client.previewPublishAppPackage(appId, { renames, knowledge, config });
     const { lines, hasError } = formatExtractReport(preview.findings);
     console.error(`Publish preview — ${appId} as new package "${preview.package_name}" (v1):`);
     const groups = [
@@ -847,6 +911,9 @@ export async function appPublish(client, args) {
     else {
         console.error("  No renamable aliases.");
     }
+    if (config.length > 0) {
+        console.error(`  Config knobs (${config.length}): ${config.map((c) => `${c.alias} (${c.type})`).join(", ")}`);
+    }
     if (lines.length > 0) {
         console.error(`  Findings (${preview.findings.length}):`);
         for (const line of lines)
@@ -870,6 +937,7 @@ export async function appPublish(client, args) {
         renames,
         changelog: args.changelog ?? null,
         knowledge,
+        config,
     });
     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:`);
@@ -901,11 +969,12 @@ export async function appRelease(client, args) {
     if (appId === null) {
         throw new Error("No app id. Run this from a pulled app project (lotics app pull <app_id>), or pass an app id explicitly.");
     }
-    // Forward the manifest's knowledge DECLARATION only from this app's own project
-    // AND only when it lists docs — an empty/absent declaration is "no change"
-    // (reconstruct from the pin), never "drop the bundle".
+    // Forward the manifest's knowledge + config DECLARATIONS only from this app's own
+    // project AND only when non-empty — an empty/absent declaration is "no change"
+    // (reconstruct knowledge from the pin / carry config forward), never "drop them".
     const knowledge = local && local.app_id === appId && local.knowledge.length > 0 ? local.knowledge : undefined;
-    const preview = await client.previewPackageRelease(appId, { knowledge });
+    const config = local && local.app_id === appId && local.config.length > 0 ? local.config : undefined;
+    const preview = await client.previewPackageRelease(appId, { knowledge, config });
     const { lines, hasError } = formatExtractReport(preview.findings);
     console.error(`Release preview — ${appId} → ${preview.package_id} v${preview.version}:`);
     if (preview.added_aliases.length > 0) {
@@ -914,7 +983,15 @@ export async function appRelease(client, args) {
     if (preview.changed_artifacts.length > 0) {
         console.error(`  Changed (${preview.changed_artifacts.length}): ${preview.changed_artifacts.join(", ")}`);
     }
-    // Deploy-skew boundary: a pre-knowledge-declaration server omits the field.
+    // Deploy-skew boundary: a pre-declaration server omits the echo field. Silent
+    // skew is dangerous exactly when a declaration was SENT — the server ignored it
+    // and the preview would misread as "no changes"; say so loudly, per surface.
+    if (preview.knowledge === undefined && knowledge !== undefined) {
+        console.error("  WARNING: the server ignored the knowledge declaration (it predates bundled-knowledge releases) — the bundle will NOT change. Retry after the platform deploy completes.");
+    }
+    if (preview.config === undefined && config !== undefined) {
+        console.error("  WARNING: the server ignored the config declaration (it predates manifest config declarations) — the knobs will NOT change. Retry after the platform deploy completes.");
+    }
     const k = preview.knowledge ?? { added: [], removed: [], changed: [] };
     if (k.added.length > 0 || k.removed.length > 0 || k.changed.length > 0) {
         const parts = [
@@ -924,11 +1001,23 @@ export async function appRelease(client, args) {
         ].filter((p) => p !== null);
         console.error(`  Knowledge: ${parts.join("; ")}`);
     }
+    const cfg = preview.config ?? { added: [], removed: [], changed: [] };
+    if (cfg.added.length > 0 || cfg.removed.length > 0 || cfg.changed.length > 0) {
+        const parts = [
+            cfg.added.length > 0 ? `+${cfg.added.join(", ")}` : null,
+            cfg.removed.length > 0 ? `dropped ${cfg.removed.join(", ")}` : null,
+            cfg.changed.length > 0 ? `changed ${cfg.changed.join(", ")}` : null,
+        ].filter((p) => p !== null);
+        console.error(`  Config: ${parts.join("; ")}`);
+    }
     if (preview.added_aliases.length === 0 &&
         preview.changed_artifacts.length === 0 &&
         k.added.length === 0 &&
         k.removed.length === 0 &&
-        k.changed.length === 0) {
+        k.changed.length === 0 &&
+        cfg.added.length === 0 &&
+        cfg.removed.length === 0 &&
+        cfg.changed.length === 0) {
         console.error("  No contract changes since the current version (a fresh code/dist snapshot still ships).");
     }
     if (lines.length > 0) {
@@ -947,7 +1036,7 @@ export async function appRelease(client, args) {
         process.exitCode = 1;
         return;
     }
-    const result = await client.releasePackage(appId, { changelog: args.changelog, knowledge });
+    const result = await client.releasePackage(appId, { changelog: args.changelog, knowledge, config });
     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}`);
 }
@@ -990,7 +1079,7 @@ async function packageFleetUpgrade(client, args) {
         const from = inst.from_version === null ? "?" : `v${inst.from_version}`;
         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(`${line}: breaking=${inst.blockers.breaking} drift=${inst.blockers.drift} modified=${inst.blockers.modified} knowledge=${inst.blockers.knowledge}`);
             console.error(`      resolve via:  lotics upgrade ${inst.app_id} --version ${result.target_version} ...`);
         }
         else if (inst.message) {

package/dist/package_commands.test.js

@@ -2,7 +2,7 @@ import { describe, it, expect, vi } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import { tmpdir } from "node:os";
-import { parseResolveFlags, parseBindToFlags, parseRenameFlags, readLocalAppManifest, formatExtractReport, appRelease, packageUpgradeByPackageId, } from "./package_commands.js";
+import { parseResolveFlags, parseBindToFlags, parseRenameFlags, readLocalAppManifest, formatExtractReport, appRelease, packageUpgradeByPackageId, packageDoctor, } from "./package_commands.js";
 import { parseArgs } from "./args.js";
 describe("parseRenameFlags", () => {
     it("parses old=new pairs", () => {
@@ -20,21 +20,42 @@ describe("parseRenameFlags", () => {
     });
 });
 describe("readLocalAppManifest", () => {
-    it("reads app_id + knowledge from a pulled app project", () => {
+    function withManifest(lotics, fn) {
         const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-app-test-"));
         try {
-            fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({
-                name: "crm",
-                lotics: { app_id: "app_x", knowledge: [{ alias: "sop", doc_id: "kdc_1" }] },
-            }));
-            expect(readLocalAppManifest(dir)).toEqual({
-                app_id: "app_x",
-                knowledge: [{ alias: "sop", doc_id: "kdc_1" }],
-            });
+            fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({ name: "crm", lotics }));
+            return fn(dir);
         }
         finally {
             fs.rmSync(dir, { recursive: true, force: true });
         }
+    }
+    it("reads app_id + knowledge + config from a pulled app project", () => {
+        withManifest({
+            app_id: "app_x",
+            knowledge: [{ alias: "sop", doc_id: "kdc_1" }],
+            config: [{ alias: "page_size", label: "Page size", type: "number", default: 25 }],
+        }, (dir) => {
+            expect(readLocalAppManifest(dir)).toEqual({
+                app_id: "app_x",
+                knowledge: [{ alias: "sop", doc_id: "kdc_1" }],
+                config: [{ alias: "page_size", label: "Page size", type: "number", default: 25 }],
+            });
+        });
+    });
+    it("defaults knowledge + config to empty arrays when the manifest omits them", () => {
+        withManifest({ app_id: "app_x" }, (dir) => {
+            expect(readLocalAppManifest(dir)).toEqual({ app_id: "app_x", knowledge: [], config: [] });
+        });
+    });
+    it("validates each config knob against the shared schema, throwing NAMING the bad alias", () => {
+        withManifest({
+            app_id: "app_x",
+            // A select knob with no `options` — the shared schema rejects it.
+            config: [{ alias: "theme", label: "Theme", type: "select", default: "light" }],
+        }, (dir) => {
+            expect(() => readLocalAppManifest(dir)).toThrow(/lotics\.config knob "theme"/);
+        });
     });
     it("returns null when the dir has no package.json", () => {
         const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-empty-"));
@@ -146,27 +167,30 @@ describe("parseArgs — package list-content", () => {
         expect(flags.workspace).toBe("wsp_dev");
     });
 });
-describe("appRelease — knowledge declaration forwarding", () => {
+describe("appRelease — knowledge + config declaration forwarding", () => {
+    const pageSizeKnob = { alias: "page_size", label: "Page size", type: "number", default: 25 };
     const previewResult = {
         package_id: "apg_1",
         version: 2,
         added_aliases: [],
         changed_artifacts: [],
         knowledge: { added: ["guide"], removed: [], changed: [] },
+        config: { added: ["page_size"], removed: [], changed: [] },
         findings: [],
     };
-    /** A mock client capturing the knowledge forwarded to preview + release. */
-    function mockClient() {
+    /** A mock client capturing the knowledge + config forwarded to preview + release. */
+    function mockClient(overridePreview) {
         const preview = [];
         const release = [];
+        const result = { ...previewResult, ...overridePreview };
         const client = {
             previewPackageRelease: async (app_id, opts = {}) => {
                 preview.push({ app_id, opts });
-                return previewResult;
+                return result;
             },
             releasePackage: async (app_id, body) => {
                 release.push({ app_id, body });
-                return { ...previewResult, findings: undefined };
+                return { ...result, findings: undefined };
             },
         };
         return { client, preview, release };
@@ -176,33 +200,53 @@ describe("appRelease — knowledge declaration forwarding", () => {
         fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({ name: "app", lotics }));
         return fn(dir).finally(() => fs.rmSync(dir, { recursive: true, force: true }));
     }
-    it("forwards the manifest's knowledge declaration from the app's own project", async () => {
+    it("forwards the manifest's knowledge + config declarations from the app's own project", async () => {
         vi.spyOn(console, "error").mockImplementation(() => undefined);
         const { client, preview, release } = mockClient();
-        await withManifestDir({ app_id: "app_x", knowledge: [{ alias: "guide", doc_id: "kdc_1" }] }, async (dir) => {
+        await withManifestDir({ app_id: "app_x", knowledge: [{ alias: "guide", doc_id: "kdc_1" }], config: [pageSizeKnob] }, async (dir) => {
             await appRelease(client, { app_id: ".", changelog: "ship", yes: true, projectDir: dir });
         });
-        expect(preview[0]).toEqual({ app_id: "app_x", opts: { knowledge: [{ alias: "guide", doc_id: "kdc_1" }] } });
-        expect(release[0].body).toEqual({ changelog: "ship", knowledge: [{ alias: "guide", doc_id: "kdc_1" }] });
+        expect(preview[0]).toEqual({
+            app_id: "app_x",
+            opts: { knowledge: [{ alias: "guide", doc_id: "kdc_1" }], config: [pageSizeKnob] },
+        });
+        expect(release[0].body).toEqual({
+            changelog: "ship",
+            knowledge: [{ alias: "guide", doc_id: "kdc_1" }],
+            config: [pageSizeKnob],
+        });
         vi.restoreAllMocks();
     });
-    it("omits knowledge (reconstruct from the pin) when the manifest declares none", async () => {
+    it("omits knowledge + config (reconstruct/carry-forward) when the manifest declares neither", async () => {
         vi.spyOn(console, "error").mockImplementation(() => undefined);
         const { client, preview, release } = mockClient();
         await withManifestDir({ app_id: "app_x" }, async (dir) => {
             await appRelease(client, { app_id: ".", changelog: "ship", yes: true, projectDir: dir });
         });
-        expect(preview[0].opts).toEqual({ knowledge: undefined });
-        expect(release[0].body).toEqual({ changelog: "ship", knowledge: undefined });
+        expect(preview[0].opts).toEqual({ knowledge: undefined, config: undefined });
+        expect(release[0].body).toEqual({ changelog: "ship", knowledge: undefined, config: undefined });
         vi.restoreAllMocks();
     });
-    it("omits knowledge for a bare app id whose manifest is a DIFFERENT app", async () => {
+    it("omits knowledge + config for a bare app id whose manifest is a DIFFERENT app", async () => {
         vi.spyOn(console, "error").mockImplementation(() => undefined);
         const { client, preview } = mockClient();
-        await withManifestDir({ app_id: "app_other", knowledge: [{ alias: "guide", doc_id: "kdc_1" }] }, async (dir) => {
+        await withManifestDir({ app_id: "app_other", knowledge: [{ alias: "guide", doc_id: "kdc_1" }], config: [pageSizeKnob] }, async (dir) => {
             await appRelease(client, { app_id: "app_x", changelog: "ship", yes: true, projectDir: dir });
         });
-        expect(preview[0]).toEqual({ app_id: "app_x", opts: { knowledge: undefined } });
+        expect(preview[0]).toEqual({ app_id: "app_x", opts: { knowledge: undefined, config: undefined } });
+        vi.restoreAllMocks();
+    });
+    it("warns LOUDLY when a SENT config declaration is ignored by a pre-declaration server (deploy skew)", async () => {
+        const errs = [];
+        vi.spyOn(console, "error").mockImplementation((msg) => {
+            errs.push(String(msg));
+        });
+        // A pre-declaration server omits `config` from the preview echo.
+        const { client } = mockClient({ config: undefined });
+        await withManifestDir({ app_id: "app_x", config: [pageSizeKnob] }, async (dir) => {
+            await appRelease(client, { app_id: ".", changelog: "ship", yes: true, projectDir: dir });
+        });
+        expect(errs.some((e) => /server ignored the config declaration/.test(e))).toBe(true);
         vi.restoreAllMocks();
     });
 });
@@ -307,3 +351,65 @@ describe("formatExtractReport", () => {
         expect(formatExtractReport([])).toEqual({ lines: [], hasError: false });
     });
 });
+describe("packageDoctor — content package-id form", () => {
+    function mockClient(preview) {
+        return {
+            getWorkspaceId: () => "wsp_1",
+            listContentInstallations: async () => [
+                {
+                    id: "pci_1",
+                    package_id: "apg_corpus",
+                    workspace_id: "wsp_1",
+                    package_version: preview.from_version,
+                    app_id: null,
+                    binding: { knowledge: {}, templates: {} },
+                    installed_by: null,
+                    created_at: "",
+                    updated_at: "",
+                    package_registry: {
+                        name: "Ops corpus",
+                        kind: "content",
+                        is_official: false,
+                        latest_version: preview.to_version,
+                        update_available: preview.to_version > preview.from_version,
+                    },
+                },
+            ],
+            previewContentInstallationUpgrade: async () => preview,
+        };
+    }
+    it("reports a healthy, pristine install without failing the check", async () => {
+        const lines = [];
+        vi.spyOn(console, "error").mockImplementation((msg) => void lines.push(msg));
+        const before = process.exitCode;
+        await packageDoctor(mockClient({ from_version: 3, to_version: 3, entries: [], templates: [] }), { app_id: "apg_corpus" });
+        expect(lines.join("\n")).toContain("Ops corpus — content installation of apg_corpus");
+        expect(lines.join("\n")).toContain("Installed: v3   Latest: v3");
+        expect(lines.join("\n")).toContain("Binding: healthy");
+        expect(lines.join("\n")).toContain("Content: pristine");
+        expect(process.exitCode).toBe(before);
+        vi.restoreAllMocks();
+    });
+    it("reports drift (non-zero exit) and local edits with their consent framing", async () => {
+        const lines = [];
+        vi.spyOn(console, "error").mockImplementation((msg) => void lines.push(msg));
+        await packageDoctor(mockClient({
+            from_version: 2,
+            to_version: 3,
+            entries: [
+                { alias: "sop", name: "SOP", change: "drifted", modified: false, doc_id: null },
+                { alias: "pricing", name: "Pricing", change: "changed", modified: true, doc_id: "kdc_2" },
+            ],
+            templates: [{ kind: "template", alias: "bien_ban" }],
+        }), { app_id: "apg_corpus" });
+        const out = lines.join("\n");
+        expect(out).toContain("→ update available");
+        expect(out).toContain('knowledge.sop "SOP" (bound doc is gone)');
+        expect(out).toContain("--resolve knowledge.<alias>=recreate|unbind");
+        expect(out).toContain('knowledge.pricing "Pricing"');
+        expect(out).toContain("template.bien_ban");
+        expect(process.exitCode).toBe(1);
+        process.exitCode = 0;
+        vi.restoreAllMocks();
+    });
+});

package/dist/src/cli.js

@@ -29960,6 +29960,9 @@ var LoticsClient = class {
     if (opts.knowledge !== void 0 && opts.knowledge.length > 0) {
       params.set("knowledge", JSON.stringify(opts.knowledge));
     }
+    if (opts.config !== void 0) {
+      params.set("config", JSON.stringify(opts.config));
+    }
     const query = params.toString();
     return this.request(
       "GET",
@@ -29992,6 +29995,9 @@ var LoticsClient = class {
     if (opts.knowledge !== void 0 && opts.knowledge.length > 0) {
       params.set("knowledge", JSON.stringify(opts.knowledge));
     }
+    if (opts.config !== void 0 && opts.config.length > 0) {
+      params.set("config", JSON.stringify(opts.config));
+    }
     if (opts.renames !== void 0 && opts.renames.length > 0) {
       params.set("renames", JSON.stringify(opts.renames));
     }
@@ -50377,7 +50383,20 @@ function readLocalAppManifest(projectDir) {
       }
     }
   }
-  return { app_id, knowledge };
+  const config2 = [];
+  if (Array.isArray(lotics.config)) {
+    for (const entry of lotics.config) {
+      const result = contractConfigEntrySchema.safeParse(entry);
+      if (!result.success) {
+        const alias = isPlainObject2(entry) && typeof entry.alias === "string" ? entry.alias : "?";
+        throw new Error(
+          `Invalid lotics.config knob "${alias}" in package.json: ` + result.error.issues.map((i2) => `${i2.path.join(".") || "(root)"}: ${i2.message}`).join("; ")
+        );
+      }
+      config2.push(result.data);
+    }
+  }
+  return { app_id, knowledge, config: config2 };
 }
 function parseRenameFlags(renames) {
   return renames.map((entry) => {
@@ -50416,6 +50435,10 @@ function parseResolveFlags(resolve2) {
   return resolutions;
 }
 async function packageDoctor(client, args) {
+  if (args.app_id !== void 0 && args.app_id.startsWith("apg_")) {
+    await contentDoctor(client, args.app_id);
+    return;
+  }
   const app_id = resolveInstallationAppId(args.app_id);
   const health = await client.getPackageHealth(app_id);
   console.error(
@@ -50635,6 +50658,38 @@ function formatTemplateResolveHint(entry) {
   const note = entry.baseline_unknown ? "   (can't verify the local edit \u2014 older package version; revert overwrites, keep retains)" : "   (a local edit \u2014 revert overwrites it with the package's version; keep retains it)";
   return `    --resolve template.${entry.alias}=revert|keep${note}`;
 }
+async function contentDoctor(client, package_id) {
+  const installation = await resolveWorkspaceContentInstallation(client, package_id);
+  const preview = await client.previewContentInstallationUpgrade(installation.id, {});
+  const name = installation.package_registry?.name ?? package_id;
+  console.error(`${name} \u2014 content installation of ${package_id} (this workspace)`);
+  console.error(
+    `  Installed: v${preview.from_version}   Latest: v${preview.to_version}` + (preview.to_version > preview.from_version ? "   \u2192 update available" : "")
+  );
+  const drifted = preview.entries.filter((e) => e.change === "drifted");
+  if (drifted.length === 0) {
+    console.error("  Binding: healthy \u2014 every bound doc resolves.");
+  } else {
+    console.error(`  Binding drift (${drifted.length}):`);
+    for (const entry of drifted) {
+      console.error(`    - knowledge.${entry.alias} "${entry.name}" (bound doc is gone)`);
+    }
+    console.error(
+      `  Resolve while upgrading:
+    lotics upgrade ${package_id} --resolve knowledge.<alias>=recreate|unbind   (or --bind-to <alias>=<kdc_id> to re-point)`
+    );
+    process.exitCode = 1;
+  }
+  const editedDocs = preview.entries.filter((e) => e.modified);
+  const editedTemplates = preview.templates;
+  if (editedDocs.length === 0 && editedTemplates.length === 0) {
+    console.error("  Content: pristine \u2014 no local edits an upgrade would ask about.");
+  } else {
+    console.error(`  Local edits (${editedDocs.length + editedTemplates.length}) \u2014 each takes a keep/overwrite consent at upgrade:`);
+    for (const entry of editedDocs) console.error(`    - knowledge.${entry.alias} "${entry.name}"`);
+    for (const entry of editedTemplates) console.error(`    - template.${entry.alias}`);
+  }
+}
 async function resolveWorkspaceContentInstallation(client, package_id) {
   const workspaceId = client.getWorkspaceId();
   if (!workspaceId) {
@@ -50992,8 +51047,9 @@ async function appPublish(client, args) {
     );
   }
   const knowledge = local && local.app_id === appId ? local.knowledge : [];
+  const config2 = local && local.app_id === appId ? local.config : [];
   const renames = parseRenameFlags(args.renames);
-  const preview = await client.previewPublishAppPackage(appId, { renames, knowledge });
+  const preview = await client.previewPublishAppPackage(appId, { renames, knowledge, config: config2 });
   const { lines, hasError } = formatExtractReport(preview.findings);
   console.error(`Publish preview \u2014 ${appId} as new package "${preview.package_name}" (v1):`);
   const groups = [
@@ -51015,6 +51071,11 @@ async function appPublish(client, args) {
   } else {
     console.error("  No renamable aliases.");
   }
+  if (config2.length > 0) {
+    console.error(
+      `  Config knobs (${config2.length}): ${config2.map((c) => `${c.alias} (${c.type})`).join(", ")}`
+    );
+  }
   if (lines.length > 0) {
     console.error(`  Findings (${preview.findings.length}):`);
     for (const line of lines) console.error(line);
@@ -51039,7 +51100,8 @@ Re-run with --yes to publish v1:`);
   const result = await client.publishAppAsPackage(appId, {
     renames,
     changelog: args.changelog ?? null,
-    knowledge
+    knowledge,
+    config: config2
   });
   console.error(`Published ${result.package_id} v${result.version} from app ${appId}.`);
   console.error(`  The app is now installation #1 \u2014 develop it in place, then release the next version:`);
@@ -51058,7 +51120,8 @@ async function appRelease(client, args) {
     );
   }
   const knowledge = local && local.app_id === appId && local.knowledge.length > 0 ? local.knowledge : void 0;
-  const preview = await client.previewPackageRelease(appId, { knowledge });
+  const config2 = local && local.app_id === appId && local.config.length > 0 ? local.config : void 0;
+  const preview = await client.previewPackageRelease(appId, { knowledge, config: config2 });
   const { lines, hasError } = formatExtractReport(preview.findings);
   console.error(`Release preview \u2014 ${appId} \u2192 ${preview.package_id} v${preview.version}:`);
   if (preview.added_aliases.length > 0) {
@@ -51067,6 +51130,16 @@ async function appRelease(client, args) {
   if (preview.changed_artifacts.length > 0) {
     console.error(`  Changed (${preview.changed_artifacts.length}): ${preview.changed_artifacts.join(", ")}`);
   }
+  if (preview.knowledge === void 0 && knowledge !== void 0) {
+    console.error(
+      "  WARNING: the server ignored the knowledge declaration (it predates bundled-knowledge releases) \u2014 the bundle will NOT change. Retry after the platform deploy completes."
+    );
+  }
+  if (preview.config === void 0 && config2 !== void 0) {
+    console.error(
+      "  WARNING: the server ignored the config declaration (it predates manifest config declarations) \u2014 the knobs will NOT change. Retry after the platform deploy completes."
+    );
+  }
   const k = preview.knowledge ?? { added: [], removed: [], changed: [] };
   if (k.added.length > 0 || k.removed.length > 0 || k.changed.length > 0) {
     const parts = [
@@ -51076,7 +51149,16 @@ async function appRelease(client, args) {
     ].filter((p) => p !== null);
     console.error(`  Knowledge: ${parts.join("; ")}`);
   }
-  if (preview.added_aliases.length === 0 && preview.changed_artifacts.length === 0 && k.added.length === 0 && k.removed.length === 0 && k.changed.length === 0) {
+  const cfg = preview.config ?? { added: [], removed: [], changed: [] };
+  if (cfg.added.length > 0 || cfg.removed.length > 0 || cfg.changed.length > 0) {
+    const parts = [
+      cfg.added.length > 0 ? `+${cfg.added.join(", ")}` : null,
+      cfg.removed.length > 0 ? `dropped ${cfg.removed.join(", ")}` : null,
+      cfg.changed.length > 0 ? `changed ${cfg.changed.join(", ")}` : null
+    ].filter((p) => p !== null);
+    console.error(`  Config: ${parts.join("; ")}`);
+  }
+  if (preview.added_aliases.length === 0 && preview.changed_artifacts.length === 0 && k.added.length === 0 && k.removed.length === 0 && k.changed.length === 0 && cfg.added.length === 0 && cfg.removed.length === 0 && cfg.changed.length === 0) {
     console.error("  No contract changes since the current version (a fresh code/dist snapshot still ships).");
   }
   if (lines.length > 0) {
@@ -51095,7 +51177,7 @@ Re-run with --yes to publish v${preview.version}:`);
     process.exitCode = 1;
     return;
   }
-  const result = await client.releasePackage(appId, { changelog: args.changelog, knowledge });
+  const result = await client.releasePackage(appId, { changelog: args.changelog, knowledge, config: config2 });
   console.error(`Released ${result.package_id} v${result.version}.`);
   console.error(`  The origin was re-pinned to v${result.version} \u2014 verify:  lotics package doctor ${appId}`);
 }
@@ -51126,7 +51208,7 @@ async function packageFleetUpgrade(client, args) {
     const line = `  [${inst.outcome}] ${inst.workspace_name} \u2014 ${inst.app_name} (${from} \u2192 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}`
+        `${line}: breaking=${inst.blockers.breaking} drift=${inst.blockers.drift} modified=${inst.blockers.modified} knowledge=${inst.blockers.knowledge}`
       );
       console.error(
         `      resolve via:  lotics upgrade ${inst.app_id} --version ${result.target_version} ...`
@@ -68016,7 +68098,7 @@ COMMANDS
                                        <alias>=apply|keep|archive|recreate|unbind); an APP package
                                        FLEET-upgrades every installation across your org (clean
                                        apply, findings skip). --apply-all accepts the package's version
-  lotics package doctor [app_id]       Installation health: version pin vs latest, binding
+  lotics package doctor [app_id|package_id]  Installation health: version pin vs latest, binding
                                        drift, locally modified core, knowledge drift/edits
                                        (exit 1 on findings)
   lotics package config <app_id> [--set key=value ...]
@@ -68545,7 +68627,7 @@ async function main() {
     console.error("    lotics install <package_id> [--version N] [--bind-to <alias>=<kdc_id>] [--config key=value ...]   Install a package (app or content)");
     console.error("    lotics uninstall <app_id|package_id> [--archive-tables] [--keep-content]   Uninstall \u2014 dispatched by id (app vs content)");
     console.error("    lotics upgrade <app_id|package_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]   Upgrade \u2014 app install / content install / whole app fleet (apg_)");
-    console.error("  lotics package doctor [app_id]                   Health: version pin vs latest + binding/knowledge drift");
+    console.error("  lotics package doctor [app_id|package_id]        Health: version pin vs latest + binding/knowledge drift (apg_ = this workspace's content install)");
     console.error("  lotics package config <app_id> [--set key=value ...]   Show or edit an installation's config knobs");
     console.error("  lotics package eject <app_id>                    Sever an installation's package link");
     console.error("  lotics package show <package_id>                 Registry metadata + version history (channel, yank, changelog)");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.86.1",
+  "version": "0.86.2",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {