@lotics/cli 0.83.0 → 0.86.0

package/README.md

@@ -227,7 +227,7 @@ lotics package config app_... --set show_done=false           # edit a live inst
 lotics uninstall app_... [--archive-tables]                   # remove an installation; workflows stop firing
 lotics package doctor app_...              # version pin vs latest + drift + local edits (exit 1 on findings)
 lotics upgrade app_...                     # preview, then apply (additive; overlay preserved)
-lotics upgrade apg_...                      # FLEET: upgrade EVERY org installation (clean ones apply; findings skip, exit 1)
+lotics upgrade apg_...                      # APP package → FLEET: upgrade EVERY org installation (clean ones apply; findings skip, exit 1)
 lotics upgrade app_... --resolve fields.deal.stage=recreate   # resolve reported drift
 lotics upgrade app_... --resolve queries.tasks=keep           # consent for a local edit (or =revert)
 lotics upgrade app_... --resolve template.quote=revert        # a locally-edited template (clean ones auto-update; or =keep)
@@ -238,7 +238,7 @@ lotics package eject app_...               # one-way: sever the package link
 lotics workspace doctor                    # dangling schema references across the workspace (exit 1 on findings)
 ```
 
-After the first publish **the origin is the master** — develop it in its workspace (`app pull` / `app deploy` / `app workflow set` / table tools), and `lotics app release` snapshots each version. Its **binding-aware re-extract** keeps aliases stable through the origin's current binding, so re-extraction never churns the upgrade diff (which is why extract-again is the loop, not a hazard).
+After the first publish **the origin is the master** — develop it in its workspace (`app pull` / `app deploy` / `app workflow set` / table tools), and `lotics app release` snapshots each version. Its **binding-aware re-extract** keeps aliases stable through the origin's current binding, so re-extraction never churns the upgrade diff (which is why extract-again is the loop, not a hazard). Release is also the **bundled-knowledge declaration surface**: run from the app project, the manifest's `lotics.knowledge` (`[{alias,doc_id}]`) re-declares which docs the package bundles — an alias added ships as a new doc, a bound alias dropped surfaces to consumers as `removed` (archive|keep), a present one re-snapshots; a bare id from elsewhere reconstructs the current corpus from the pin (never drops it). So a published app package evolves its bundled docs across versions without ejecting.
 
 ### Content packages
 
@@ -257,15 +257,16 @@ lotics run release_content '{"package_id":"apg_...","changelog":"v2: revised SOP
 lotics install apg_...                          # app OR content, shape-branched
 lotics install apg_... --bind-to policy=kdc_... # adopt an existing doc as package-managed
 
-# Discover installed content (the source for a pci_ id — install prints it once)
-lotics package list-content                           # id · package · version (standalone content installs)
+# Discover installed content (each row leads with the PACKAGE id)
+lotics package list-content                           # package id · package · version (standalone content installs)
 
-# Refresh a standalone content install (pci_ id from install / list-content) — one gate over docs + templates
-lotics upgrade pci_...                          # preview, then apply
-lotics upgrade pci_... --resolve knowledge.policy=apply   # a doc: apply|keep|archive|recreate|unbind
-lotics upgrade pci_... --resolve template.quote=revert    # a locally-edited template: revert|keep (clean ones auto-update)
-lotics upgrade pci_... --apply-all              # accept upstream for every doc + template (OVERWRITES local edits)
-lotics uninstall pci_... --keep-content            # remove the pin; keep docs + templates (default archives them)
+# Refresh this workspace's content install — addressed by PACKAGE id (one install per
+# package per workspace, so the package id is the address; one gate over docs + templates)
+lotics upgrade apg_...                          # CONTENT package → preview, then apply (this workspace's install)
+lotics upgrade apg_... --resolve knowledge.policy=apply   # a doc: apply|keep|archive|recreate|unbind
+lotics upgrade apg_... --resolve template.quote=revert    # a locally-edited template: revert|keep (clean ones auto-update)
+lotics upgrade apg_... --apply-all              # accept upstream for every doc + template (OVERWRITES local edits)
+lotics uninstall apg_... --keep-content            # remove the pin; keep docs + templates (default archives them)
 ```
 
 A package's knowledge can also arrive **bundled with an app**. Upgrading such an app (`lotics upgrade <app_id>`) previews its bundled-knowledge changes alongside the plan and resolves them in the SAME namespaced grammar — `--resolve knowledge.<alias>=apply|keep|archive|recreate|unbind` (the flags pass to the server verbatim; no routing, no ambiguity), `--bind-to` consents an added-doc collision, `--apply-all` takes the package's version for every consent-requiring doc.

package/dist/cli.js

@@ -14,7 +14,7 @@ import { LoticsClient, API_BASE_URL } from "./client.js";
 import { resolveContext, deleteConfig, getConfigPath, loadGlobalConfig, saveGlobalConfig, loadLocalConfig, upsertProfile, removeProfile, setActiveOrg, setSelectedWorkspace, resolveProfileByNameOrId, checkForUpdate, } from "./config.js";
 import { VERSION } from "./version.js";
 import { appCreate, appPull, appDeploy, appDev, appSetSubdomain, appRename, appVersions, appCodegen, appExecuteWorkflow, appWorkflowSet, appWorkflowPull, appWorkflowCheck, appQuerySet, appUiLink, } from "./app_commands.js";
-import { packageInstall, packageUninstall, packageListContent, packageConfig, packageShow, parseInstallConfigFlags, packageEject, packageDoctor, packageUpgrade, packageUpgradeKnowledge, parseBindToFlags, appPublish, appRelease, appUnpublish, packageFleetUpgrade, packageYank, } from "./package_commands.js";
+import { packageInstall, packageUninstall, packageListContent, packageConfig, packageShow, parseInstallConfigFlags, packageEject, packageDoctor, packageUpgrade, packageUpgradeByPackageId, redirectContentPciForm, parseBindToFlags, appPublish, appRelease, appUnpublish, packageYank, } from "./package_commands.js";
 import { parseArgs } from "./args.js";
 import { ingestJsonArgs } from "./inputs.js";
 import { runXlsxCommand } from "./xlsx.js";
@@ -114,18 +114,19 @@ COMMANDS
                                        Install a package (app: scaffolds/deploys/materializes,
                                        --config sets its knobs; content: installs the doc corpus,
                                        --bind-to consents to adopt a same-named doc on a collision)
-  lotics uninstall <app_id|pci_id> [--archive-tables] [--keep-content]
+  lotics uninstall <app_id|package_id> [--archive-tables] [--keep-content]
                                        Uninstall — dispatched by id. App (app_id): archives
                                        artifacts (+ --archive-tables also archives scaffolded
-                                       tables). Content (pci_): archives its package-bound docs
-                                       unless --keep-content
-  lotics upgrade <app_id|pci_id|package_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]
+                                       tables). Content package (apg_): archives its package-bound
+                                       docs unless --keep-content
+  lotics upgrade <app_id|package_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]
                                        Preview-then-apply an upgrade, dispatched by id. App
                                        (app_id): refuses while any drift/modified/bundled-knowledge
-                                       finding lacks a --resolve. Content (pci_): --resolve
-                                       <alias>=apply|keep|archive|recreate|unbind. Package (apg_):
-                                       FLEET — every installation across your org (clean apply,
-                                       findings skip). --apply-all accepts the package's version
+                                       finding lacks a --resolve. Package (apg_): a CONTENT package
+                                       upgrades THIS workspace's install (--resolve
+                                       <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
                                        drift, locally modified core, knowledge drift/edits
                                        (exit 1 on findings)
@@ -135,7 +136,8 @@ COMMANDS
                                        (re-deploys the pinned source as a bespoke app)
   lotics package show <package_id>     Registry metadata + version history
   lotics package list-content          List the workspace's content installations
-                                       (standalone content installs) — source for a pci_ id
+                                       (standalone content installs) — each row leads with
+                                       the package id for upgrade/uninstall
   lotics package yank <package_id> <version> [--undo]
                                        Refuse new installs/upgrades of a broken published
                                        version (pinned installations keep running)
@@ -713,8 +715,8 @@ async function main() {
         console.error("Usage (low-traffic consumer / registry ops — author verbs live on `lotics app`):");
         console.error("  The high-traffic consumer verbs are top-level:");
         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|pci_id> [--archive-tables] [--keep-content]   Uninstall — dispatched by id (app vs content)");
-        console.error("    lotics upgrade <app_id|pci_id|package_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]   Upgrade — app / content / whole fleet (apg_)");
+        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 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");
@@ -902,12 +904,17 @@ async function main() {
     if (command === "uninstall") {
         const id = subcommand;
         if (!id) {
-            console.error("Usage: lotics uninstall <app_id|pci_id> [--archive-tables] [--keep-content]");
+            console.error("Usage: lotics uninstall <app_id|package_id> [--archive-tables] [--keep-content]");
             console.error("Dispatched by id: an app installation (app_id; --archive-tables to also archive its " +
-                "scaffolded tables) or a standalone content installation (pci_ id from `lotics install` / " +
+                "scaffolded tables) or a content package (apg_ id from `lotics install` / " +
                 "lotics package list-content; --keep-content to retain its docs).");
             process.exit(1);
         }
+        // A `pci_` resource id is retired from human sight — redirect to the package-id form.
+        if (id.startsWith("pci_")) {
+            await redirectContentPciForm(client, id, "uninstall");
+            return;
+        }
         await packageUninstall(client, {
             id,
             keep_content: flags.keepContent,
@@ -918,9 +925,9 @@ async function main() {
     if (command === "upgrade") {
         const target = subcommand;
         if (!target) {
-            console.error("Usage: lotics upgrade <app_id | pci_id | package_id> [--version N] [--resolve <key>=... ...] [--bind-to ...] [--apply-all]");
-            console.error("Dispatched by id: an app installation (app_id), a standalone content installation (pci_ id), " +
-                "or a package id (apg_ — fleet-upgrades every installation across your org).");
+            console.error("Usage: lotics upgrade <app_id | package_id> [--version N] [--resolve <key>=... ...] [--bind-to ...] [--apply-all]");
+            console.error("Dispatched by id: an app installation (app_id), or a package id (apg_) — a CONTENT package " +
+                "upgrades this workspace's install; an APP package fleet-upgrades every installation across your org.");
             process.exit(1);
         }
         let version;
@@ -931,22 +938,24 @@ async function main() {
                 process.exit(1);
             }
         }
-        // A package id fleet-upgrades every installation across the org; a `pci_` id
-        // is a standalone content installation; anything else is an app installation.
-        if (target.startsWith("apg_")) {
-            await packageFleetUpgrade(client, { package_id: target, version });
+        // A `pci_` resource id is retired from human sight — redirect to the package-id form.
+        if (target.startsWith("pci_")) {
+            await redirectContentPciForm(client, target, "upgrade");
             return;
         }
-        if (target.startsWith("pci_")) {
-            await packageUpgradeKnowledge(client, {
-                installation_id: target,
+        // A package id (apg_) is kind-branched: a content package upgrades THIS
+        // workspace's install; an app package fleet-upgrades the whole org.
+        if (target.startsWith("apg_")) {
+            await packageUpgradeByPackageId(client, {
+                package_id: target,
                 version,
                 resolve: flags.resolve,
-                bind_to: parseBindToFlags(flags.bindTo),
+                bindTo: flags.bindTo,
                 applyAll: flags.applyAll,
             });
             return;
         }
+        // Anything else is an app installation (addressed by its app id).
         await packageUpgrade(client, {
             app_id: target,
             version,
@@ -1019,8 +1028,8 @@ async function main() {
         // `lotics package <verb>` forms loudly with a redirect, never a silent no-op.
         const movedVerbs = {
             install: "lotics install <package_id>",
-            uninstall: "lotics uninstall <app_id|pci_id>",
-            upgrade: "lotics upgrade <app_id|pci_id|package_id>",
+            uninstall: "lotics uninstall <app_id|package_id>",
+            upgrade: "lotics upgrade <app_id|package_id>",
             "fleet-upgrade": "lotics upgrade <package_id>",
         };
         if (subcommand !== undefined && subcommand in movedVerbs) {
@@ -1330,8 +1339,10 @@ async function main() {
                 console.log(JSON.stringify({ error: result.error }, null, 2));
             }
             else {
+                // Execution errors (not-found, refusals) carry the server's message;
+                // the input already passed schema validation, so no schema hint —
+                // validation 400s bring the server's own hint via throwResponseError.
                 console.error(result.error);
-                console.error(`\nHint: run "lotics tools ${toolName}" to see the expected input schema.`);
             }
             process.exit(1);
         }

package/dist/cli_dispatch.test.js

@@ -104,8 +104,8 @@ describe("lotics top-level consumer-verb dispatch", () => {
     // bare invocation — reaching it fires before any network work.
     const usageCases = [
         ["install", /Usage: lotics install <package_id>/],
-        ["uninstall", /Usage: lotics uninstall <app_id\|pci_id>/],
-        ["upgrade", /Usage: lotics upgrade <app_id \| pci_id \| package_id>/],
+        ["uninstall", /Usage: lotics uninstall <app_id\|package_id>/],
+        ["upgrade", /Usage: lotics upgrade <app_id \| package_id>/],
     ];
     for (const [verb, usage] of usageCases) {
         it(`routes top-level "${verb}" to its handler (usage on missing id)`, () => {
@@ -115,6 +115,19 @@ describe("lotics top-level consumer-verb dispatch", () => {
             expect(status).toBe(1);
         });
     }
+    // CLEAN BREAK: content installs are addressed by their PACKAGE id — an explicit
+    // `pci_` resource id must get a loud redirect to the package-id form. The redirect
+    // header prints SYNCHRONOUSLY (before the best-effort list-content resolution that
+    // spells out the exact command), so it is observable without a live registry; the
+    // process exits 1 either way (best-effort resolution fails on the fake key).
+    for (const verb of ["upgrade", "uninstall"]) {
+        it(`redirects an explicit pci_ id on "${verb}" to the package-id form`, () => {
+            const { status, stderr } = runCli([verb, "pci_dispatch_smoke_fake"]);
+            expect(stderr).toMatch(/addressed by their PACKAGE id now/);
+            expect(stderr).not.toMatch(/Unknown command/);
+            expect(status).toBe(1);
+        });
+    }
 });
 describe("lotics app author-verb dispatch", () => {
     // `app publish` (no id, empty cwd) must fail on the missing local app

package/dist/client.d.ts

@@ -542,31 +542,60 @@ export declare class LoticsClient {
     /**
      * Preview a release — the dry run behind `lotics app release`. Runs the
      * binding-aware extract of the origin (aliases stable through the app's current
-     * binding) and reports the next version number, the new + changed aliases, and
-     * any extract findings (an `error` blocks the apply). No writes. Admin,
+     * binding) and reports the next version number, the new + changed aliases, the
+     * bundled-knowledge delta, and any extract findings (an `error` blocks the
+     * apply). An optional `knowledge` declaration (from the pulled app manifest)
+     * re-declares the bundle set — added/dropped/changed docs surface in the delta;
+     * omitted, the current corpus is reconstructed from the pin. No writes. Admin,
      * owning-org only.
      */
-    previewPackageRelease(app_id: string): Promise<{
+    previewPackageRelease(app_id: string, opts?: {
+        /** alias → doc_id re-declaring the bundled-knowledge set (from the manifest). */
+        knowledge?: Array<{
+            alias: string;
+            doc_id: string;
+        }>;
+    }): Promise<{
         package_id: string;
         version: number;
         added_aliases: string[];
         changed_artifacts: string[];
+        /** Absent from a pre-declaration server (deploy skew) — treat as empty delta. */
+        knowledge?: {
+            added: string[];
+            removed: string[];
+            changed: string[];
+        };
         findings: ExtractFinding[];
     }>;
     /**
      * Release — snapshot the origin app into the next registry version. The server
      * binding-aware-extracts it, repackages its deployed source + dist as the
      * bundle, publishes the next `release`-channel version with the changelog, and
-     * re-pins the origin. Error findings from extract surface as a 409. Admin,
+     * re-pins the origin. An optional `knowledge` declaration re-declares the
+     * bundled-knowledge set (added/dropped/re-snapshotted docs; omitted preserves
+     * the current corpus). Error findings from extract surface as a 409; a
+     * missing/archived declared doc is a 400, a foreign-package doc a 409. Admin,
      * owning-org only. Backs `lotics app release --yes`.
      */
     releasePackage(app_id: string, body: {
         changelog: string;
+        /** alias → doc_id re-declaring the bundled-knowledge set (from the manifest). */
+        knowledge?: Array<{
+            alias: string;
+            doc_id: string;
+        }>;
     }): Promise<{
         package_id: string;
         version: number;
         added_aliases: string[];
         changed_artifacts: string[];
+        /** Absent from a pre-declaration server (deploy skew) — treat as empty delta. */
+        knowledge?: {
+            added: string[];
+            removed: string[];
+            changed: string[];
+        };
     }>;
     /**
      * Dry-run preview of a first-release — the `GET` behind `lotics app publish`

package/dist/client.js

@@ -353,18 +353,29 @@ export class LoticsClient {
     /**
      * Preview a release — the dry run behind `lotics app release`. Runs the
      * binding-aware extract of the origin (aliases stable through the app's current
-     * binding) and reports the next version number, the new + changed aliases, and
-     * any extract findings (an `error` blocks the apply). No writes. Admin,
+     * binding) and reports the next version number, the new + changed aliases, the
+     * bundled-knowledge delta, and any extract findings (an `error` blocks the
+     * apply). An optional `knowledge` declaration (from the pulled app manifest)
+     * re-declares the bundle set — added/dropped/changed docs surface in the delta;
+     * omitted, the current corpus is reconstructed from the pin. No writes. Admin,
      * owning-org only.
      */
-    async previewPackageRelease(app_id) {
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-release`);
+    async previewPackageRelease(app_id, opts = {}) {
+        const params = new URLSearchParams();
+        if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
+            params.set("knowledge", JSON.stringify(opts.knowledge));
+        }
+        const query = params.toString();
+        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-release${query ? `?${query}` : ""}`);
     }
     /**
      * Release — snapshot the origin app into the next registry version. The server
      * binding-aware-extracts it, repackages its deployed source + dist as the
      * bundle, publishes the next `release`-channel version with the changelog, and
-     * re-pins the origin. Error findings from extract surface as a 409. Admin,
+     * re-pins the origin. An optional `knowledge` declaration re-declares the
+     * bundled-knowledge set (added/dropped/re-snapshotted docs; omitted preserves
+     * the current corpus). Error findings from extract surface as a 409; a
+     * missing/archived declared doc is a 400, a foreign-package doc a 409. Admin,
      * owning-org only. Backs `lotics app release --yes`.
      */
     async releasePackage(app_id, body) {

package/dist/generate_app_workflows_dts.js

@@ -127,7 +127,12 @@ function inputDeclToTsType(decl) {
                 return null;
             })
                 .filter((v) => v !== null);
-            const inner = literals.length > 0 ? literals.join(" | ") : "string";
+            // The literal union keeps autocomplete for hand-typed ids, but a package
+            // app addresses options through the runtime-resolved OPT map (typed
+            // string — consumer workspaces bind DIFFERENT concrete ids), so the
+            // input must also accept string. `(string & {})` widens without
+            // collapsing the union in intellisense.
+            const inner = literals.length > 0 ? `${literals.join(" | ")} | (string & {})` : "string";
             return decl.multi === true ? `ReadonlyArray<${inner}>` : inner;
         }
         case "date_range":
@@ -193,7 +198,11 @@ function outputDeclToTsType(decl) {
                 ? JSON.stringify(o.value)
                 : null)
                 .filter((v) => v !== null);
-            const inner = literals.length > 0 ? literals.join(" | ") : "string";
+            // Same widening on the READ side: a package app's runtime output value is
+            // the CONSUMER workspace's concrete opt_ id, not the origin's literal —
+            // exhaustive narrowing over origin literals would be unsound. `(string & {})`
+            // keeps autocomplete without lying about the value space.
+            const inner = literals.length > 0 ? `${literals.join(" | ")} | (string & {})` : "string";
             return decl.multi === true ? `ReadonlyArray<${inner}>` : inner;
         }
         case "object": {

package/dist/generate_app_workflows_dts.test.js

@@ -77,8 +77,8 @@ describe("generateAppWorkflowsDts", () => {
         });
         expect(dts).toContain("record_id: string;"); // required → NOT nullable
         expect(dts).toContain("due?: string | null;"); // optional scalar → clearable
-        expect(dts).toContain('status?: "opt_done" | null;');
-        expect(dts).toContain('tags?: ReadonlyArray<"opt_a"> | null;'); // optional multi
+        expect(dts).toContain('status?: "opt_done" | (string & {}) | null;');
+        expect(dts).toContain('tags?: ReadonlyArray<"opt_a" | (string & {})> | null;'); // optional multi
         // The object itself is a top-level optional → nullable; its NESTED optional
         // field mirrors the backend's plain `.optional()` (no `| null`).
         expect(dts).toContain("note?: string;");
@@ -94,7 +94,7 @@ describe("generateAppWorkflowsDts", () => {
                 },
             },
         });
-        expect(dts).toContain('owner: string; tags: ReadonlyArray<"a" | "b">');
+        expect(dts).toContain('owner: string; tags: ReadonlyArray<"a" | "b" | (string & {})>');
     });
     it("types a multi file input as ReadonlyArray<string>, single file as string", () => {
         const dts = generateAppWorkflowsDts({

package/dist/package_commands.d.ts

@@ -79,24 +79,28 @@ export declare function packageShow(client: LoticsClient, args: {
     package_id: string;
 }): Promise<void>;
 /**
- * Preview-then-apply a STANDALONE content installation upgrade — knowledge docs
- * AND document templates behind one review gate. Prints the per-alias plan;
- * refuses (exit 1, with the exact `--resolve` syntax) while any consent-requiring
- * entry lacks a resolution — a modified knowledge change/removal or drift, or a
- * locally-edited changed template. `--apply-all` auto-resolves EVERY consent entry
- * by accepting the package's version (knowledge changed→apply, removed→archive,
- * drifted→recreate; template→revert) — an explicit bulk "take upstream" that
- * discards local edits. `--resolve knowledge.<alias>=<value>` /
- * `--resolve template.<alias>=revert|keep` and `--bind-to <alias>=<kdc_id>`
- * resolve entries individually — the ONE namespaced grammar, passed to the
- * server verbatim.
+ * CLEAN BREAK for an explicit `pci_` argument on `upgrade` / `uninstall`: the
+ * `pci_` resource id is retired from human sight — content installs are addressed
+ * by their PACKAGE id. Prints a loud redirect, best-effort resolving the `pci_`
+ * back to its package id (via list-content) so the exact command is spelled out.
+ * The header prints synchronously first, so the redirect is observable even when
+ * the best-effort resolution can't reach the registry.
  */
-export declare function packageUpgradeKnowledge(client: LoticsClient, args: {
-    installation_id: string;
+export declare function redirectContentPciForm(client: LoticsClient, pci_id: string, verb: "upgrade" | "uninstall"): Promise<never>;
+/**
+ * `lotics upgrade <apg_>` — the package-id upgrade path, kind-branched. `kind` is a
+ * DERIVED display hint (`contractHasAppSurface`): `'content'` means no app surface.
+ *   - a CONTENT package upgrades THIS workspace's standalone content installation
+ *     (resolved from the package id — the anchor is unique per workspace, so the
+ *     `pci_` never surfaces), through the same content review gate.
+ *   - an APP-surface package FLEET-upgrades every installation across the org
+ *     (unchanged) — the resolve/bind/apply-all flags don't apply to a fleet run.
+ */
+export declare function packageUpgradeByPackageId(client: LoticsClient, args: {
+    package_id: string;
     version?: number;
-    /** Raw `--resolve <alias>=<value>` flags, routed to knowledge/templates after the preview. */
     resolve: string[];
-    bind_to: Record<string, string>;
+    bindTo: string[];
     applyAll: boolean;
 }): Promise<void>;
 /** Parse repeated `--bind-to alias=kdc_id` flags into an alias → doc-id consent map. */
@@ -110,9 +114,11 @@ export declare function packageInstall(client: LoticsClient, args: {
     config?: Record<string, string | number | boolean>;
 }): Promise<void>;
 /**
- * `lotics uninstall <app_id|pci_id>` — ONE top-level command over both installation
- * kinds, dispatched by the id form (mirrors `lotics upgrade`):
- *   - a `pci_` id → a STANDALONE CONTENT installation: deletes the row and (unless
+ * `lotics uninstall <app_id|package_id>` — ONE top-level command over both
+ * installation kinds, dispatched by the id form (mirrors `lotics upgrade`):
+ *   - a package id (`apg_`) → THIS workspace's STANDALONE CONTENT installation
+ *     (content installs are addressed by package id, UNIQUE per workspace, so the
+ *     `pci_` resource id never surfaces): 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
@@ -129,8 +135,9 @@ export declare function packageUninstall(client: LoticsClient, args: {
  * `lotics package list-content` — list the selected workspace's STANDALONE
  * content installations (an app-bundled corpus rides its app's
  * `binding.knowledge` and shows on the Apps surface instead), each with its
- * registry status. The read surface that surfaces a `pci_` id for
- * `upgrade` / `uninstall` (install prints it once; nothing else did before).
+ * registry status. The what-is-installed listing: each row leads with the PACKAGE
+ * id — the address for `lotics upgrade <package_id>` / `lotics uninstall
+ * <package_id>` (the `pci_` resource id stays hidden).
  */
 export declare function packageListContent(client: LoticsClient): Promise<void>;
 export declare function packageEject(client: LoticsClient, args: {
@@ -185,9 +192,15 @@ export declare function appPublish(client: LoticsClient, args: {
  * § Promotion). The origin is the permanent working copy; a release binding-aware-
  * extracts it (stable aliases), repackages its DEPLOYED source + dist as the
  * bundle, publishes the next version, and re-pins the origin. Prints the preview
- * first (next version, new + changed aliases, findings); applies only with
- * `--yes`, else exits 1 so a review step can't be skipped. An `error` finding
- * blocks the apply.
+ * first (next version, new + changed aliases, the bundled-knowledge delta,
+ * findings); applies only with `--yes`, else exits 1 so a review step can't be
+ * skipped. An `error` finding blocks the apply.
+ *
+ * Run from the pulled app project, the manifest's `lotics.knowledge` (alias →
+ * doc_id) is the bundle DECLARATION — it re-declares which docs the package owns
+ * (add/drop/re-snapshot). Forwarded only when non-empty; empty (or a bare id from
+ * elsewhere) sends nothing, so the current corpus is reconstructed from the pin
+ * (never silently dropped).
  */
 export declare function appRelease(client: LoticsClient, args: {
     app_id?: string;
@@ -206,14 +219,3 @@ export declare function packageYank(client: LoticsClient, args: {
     version: number;
     undo: boolean;
 }): Promise<void>;
-/**
- * `lotics upgrade <package_id> [--version N]` (fleet path) — bring every
- * installation of the package across the caller's org to the target version.
- * Hands-off applies only where the preview is clean; skipped/failed
- * installations are reported per line and the process exits 1 so a release
- * script can gate on "fleet fully current".
- */
-export declare function packageFleetUpgrade(client: LoticsClient, args: {
-    package_id: string;
-    version?: number;
-}): Promise<void>;