@lotics/cli 0.83.0 → 0.86.1

package/dist/dev/server.js

@@ -5,11 +5,29 @@
  *   1. Vite dev server (npx vite --port <vite-port>) — child_process.spawn,
  *      stdio inherited so Vite's own logging surfaces to the developer.
  *   2. node:http server on <port> serving:
- *        GET  /        → wrapper HTML (cached: no)
- *        POST /_rpc    → JSON in, dispatched via rpc_handler, JSON out
- *        *             → 404
+ *        GET  /               → wrapper HTML (cached: no)
+ *        POST /_rpc           → JSON in, dispatched via rpc_handler, JSON out
+ *        POST /_agent_run     → SSE, piped from the run
+ *        PUT  /_upload/:id    → file bytes in  (relayed to storage)
+ *        GET  /_file/:token   → file bytes out (relayed from storage)
+ *        *                    → 404
  *
  * SIGINT (Ctrl-C) → kill Vite child, close HTTP server, exit 0.
+ *
+ * Why the byte relays exist: dev runs against the PROD bucket (there is no dev
+ * bucket), whose CORS allowlist holds the real app origins (`https://*.lotics.app`),
+ * not `http://localhost:<port>`. So a browser transfer straight to/from the presigned
+ * URL is blocked before it leaves the page — no upload could complete, and no preview
+ * engine (PDF/Word/Excel all FETCH the bytes) could read a file. Relaying through THIS
+ * server fixes both: Node has no same-origin policy, and the one cross-origin hop that
+ * remains (the app iframe reading from us) is OUR response to allow.
+ *
+ * Neither relay ever takes a destination from the client: the page sends a `file_id`
+ * or an opaque token, and the server transfers only to/from a URL IT minted or observed
+ * for that id. No client-controlled target ⇒ no SSRF surface, nothing to allowlist.
+ *
+ * Production is untouched — it transfers direct-to-storage, keeping every byte off the
+ * API server.
  */
 import http from "node:http";
 import net from "node:net";
@@ -17,6 +35,8 @@ import { spawn } from "node:child_process";
 import { ipv4ChildEnv } from "../child_env.js";
 import { dispatchRpc } from "./rpc_handler.js";
 import { buildWrapperPage } from "./wrapper_page.js";
+import { createUploadRelay } from "./upload_relay.js";
+import { createFileRelay } from "./file_relay.js";
 const DEFAULT_PORT = 5174;
 const DEFAULT_VITE_PORT = 5173;
 /**
@@ -84,6 +104,28 @@ export async function startDevServer(args) {
         }
     };
     process.once("exit", killViteOnExit);
+    const uploads = createUploadRelay();
+    // The app iframe is served from Vite's origin, so the file URLs it receives must be
+    // absolute against THIS server, and its byte reads are cross-origin to us — which is
+    // ours to allow (unlike the storage bucket's policy, which is not).
+    const wrapperOrigin = `http://localhost:${wrapperPort}`;
+    const viteOrigin = `http://localhost:${vitePort}`;
+    const files = createFileRelay(wrapperOrigin);
+    const fileCors = {
+        "Access-Control-Allow-Origin": viteOrigin,
+        "Access-Control-Allow-Headers": "range, content-type",
+        "Access-Control-Expose-Headers": "content-length, content-range, accept-ranges, content-type, content-disposition, etag",
+    };
+    // Headers a byte-reader actually needs: the type to decode, the length/range to seek.
+    const PASS_THROUGH = [
+        "content-type",
+        "content-length",
+        "content-range",
+        "accept-ranges",
+        "etag",
+        "last-modified",
+        "content-disposition",
+    ];
     // ── HTTP server ────────────────────────────────────────────────────────
     const server = http.createServer(async (req, res) => {
         const url = req.url ?? "/";
@@ -110,7 +152,9 @@ export async function startDevServer(args) {
                 const ms = Date.now() - startedAt;
                 process.stderr.write(`[rpc] ${body.op} ${ms}ms\n`);
                 res.writeHead(200, { "Content-Type": "application/json" });
-                res.end(serializeRpcResult(result));
+                // `upload_url` mints a PUT destination (upload relay); every other op may carry
+                // presigned file URLs the app will read bytes from (file relay).
+                res.end(serializeRpcResult(body.op === "upload_url" ? uploads.rewriteMint(result) : files.rewrite(result)));
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -171,12 +215,138 @@ export async function startDevServer(args) {
             }
             return;
         }
+        // File relay — the app reads file bytes from here instead of straight from storage,
+        // whose CORS doesn't admit a localhost origin. The app is on Vite's origin, so this
+        // IS cross-origin — but it's our response, so we allow it. Serving from here also
+        // means <img>/<video> and openExternal keep working unchanged.
+        if (pathname.startsWith("/_file/")) {
+            if (req.method === "OPTIONS") {
+                res.writeHead(204, fileCors);
+                res.end();
+                return;
+            }
+            if (req.method !== "GET" && req.method !== "HEAD") {
+                res.writeHead(405, { ...fileCors, Allow: "GET, HEAD, OPTIONS" });
+                res.end();
+                return;
+            }
+            const token = decodeURIComponent(pathname.slice("/_file/".length));
+            const destination = files.destinationFor(token);
+            if (!destination) {
+                // Not a URL this server handed out (or its presign has aged out). Reading from
+                // anywhere else is the thing this design refuses to do.
+                process.stderr.write(`[file] ERROR unknown or expired token ${token}\n`);
+                res.writeHead(404, { ...fileCors, "Content-Type": "application/json" });
+                res.end(JSON.stringify({ message: "No file for this token" }));
+                return;
+            }
+            try {
+                // Forward Range verbatim: a PDF reader seeks rather than reading the whole file,
+                // and media scrubbing depends on 206s coming back intact.
+                const range = req.headers.range;
+                const upstream = await fetch(destination, {
+                    method: req.method,
+                    headers: range ? { Range: range } : undefined,
+                });
+                const headers = { ...fileCors };
+                for (const name of PASS_THROUGH) {
+                    const value = upstream.headers.get(name);
+                    if (value)
+                        headers[name] = value;
+                }
+                // Same one-line-per-transfer visibility as [rpc] and [upload] — a preview that
+                // silently serves nothing is exactly the thing this relay exists to make legible.
+                const size = headers["content-length"] ?? "?";
+                process.stderr.write(`[file] ${token} ${upstream.status} ${size}B\n`);
+                res.writeHead(upstream.status, headers);
+                if (req.method === "HEAD" || !upstream.body) {
+                    res.end();
+                    return;
+                }
+                const reader = upstream.body.getReader();
+                for (;;) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    res.write(Buffer.from(value));
+                }
+                res.end();
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[file] ERROR ${token} ${message}\n`);
+                if (!res.headersSent) {
+                    res.writeHead(502, { ...fileCors, "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ message }));
+                }
+                else {
+                    res.end();
+                }
+            }
+            return;
+        }
+        // Upload relay — the wrapper page PUTs the bytes here (same-origin, so the
+        // browser never applies CORS), and Node forwards them to the presigned URL.
+        if (req.method === "PUT" && pathname.startsWith("/_upload/")) {
+            const fileId = decodeURIComponent(pathname.slice("/_upload/".length));
+            const destination = uploads.destinationFor(fileId);
+            if (!destination) {
+                // Not a URL this server minted (or its presign has aged out). Relaying
+                // anywhere else is exactly the thing this design refuses to do.
+                process.stderr.write(`[upload] ERROR unknown or expired file_id ${fileId}\n`);
+                res.writeHead(404, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ message: `No presigned upload pending for ${fileId}` }));
+                return;
+            }
+            try {
+                // Buffer rather than stream: the presign signs `content-length`, and a
+                // streamed body would go out chunked and fail the signature. Dev-only,
+                // and the size ceiling is the API's own upload limit.
+                const chunks = [];
+                for await (const chunk of req)
+                    chunks.push(chunk);
+                const bytes = Buffer.concat(chunks);
+                const startedAt = Date.now();
+                const upstream = await fetch(destination, {
+                    method: "PUT",
+                    body: bytes,
+                    headers: { "Content-Type": req.headers["content-type"] ?? "application/octet-stream" },
+                });
+                const ms = Date.now() - startedAt;
+                if (upstream.ok) {
+                    uploads.settle(fileId);
+                    process.stderr.write(`[upload] ${fileId} ${bytes.length}B ${ms}ms\n`);
+                }
+                else {
+                    // Keep the mint: the wrapper retries 5xx, and the presign is still valid.
+                    process.stderr.write(`[upload] ERROR ${fileId} storage returned ${upstream.status}\n`);
+                }
+                res.writeHead(upstream.status);
+                res.end();
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[upload] ERROR ${fileId} ${message}\n`);
+                if (!res.headersSent) {
+                    res.writeHead(502, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ message }));
+                }
+                else {
+                    res.end();
+                }
+            }
+            return;
+        }
         res.writeHead(404, { "Content-Type": "text/plain" });
         res.end("Not Found");
     });
     await new Promise((resolve, reject) => {
         server.once("error", reject);
-        server.listen(wrapperPort, () => {
+        // Loopback ONLY — never 0.0.0.0. `/_rpc` dispatches with the developer's API key, so a
+        // server bound to every interface hands anyone on the same network full read/write on the
+        // workspace (and, since the relays, the file bytes too). Vite already binds loopback; this
+        // socket is strictly more sensitive than that one.
+        server.listen(wrapperPort, "127.0.0.1", () => {
             server.off("error", reject);
             resolve();
         });

package/dist/dev/upload_relay.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Dev-only upload relay: the bookkeeping that lets `lotics app dev` upload a file.
+ *
+ * Dev runs against the PROD bucket (there is no dev bucket), whose CORS allowlist
+ * holds the real app origins (`https://*.lotics.app`), not `http://localhost:<port>`.
+ * A browser PUT straight to the presigned URL is blocked before it leaves the page,
+ * so without a relay no file-touching app can be exercised locally at all.
+ *
+ * The dev server therefore relays the bytes: the wrapper page PUTs same-origin (no
+ * preflight, no CORS) and Node — which has no same-origin policy — forwards them on.
+ *
+ * The security property, and the reason the page never names its destination: a
+ * relay that forwarded to a client-supplied URL would be an open proxy. So the page
+ * sends only a `file_id`, and the relay writes ONLY to a presigned URL it minted
+ * itself for that id, moments earlier, via its own authenticated API call. There is
+ * no client-controlled target — hence nothing to allowlist, and no SSRF surface.
+ *
+ * Production is untouched: it PUTs direct-to-storage, keeping every byte off the
+ * API server.
+ */
+export interface UploadRelay {
+    /**
+     * Record the presigned PUT from an `upload_url` mint and return the result the
+     * page should see — identical but for a same-origin `upload_url`. A result that
+     * carries no mint passes through untouched: nothing is recorded, nothing is
+     * rewritten, and the page's PUT fails loudly rather than uploading into a void.
+     */
+    rewriteMint(result: unknown): unknown;
+    /** The presigned URL minted for this id — `null` if unknown or expired. */
+    destinationFor(fileId: string): string | null;
+    /** Drop a mint once its bytes have landed. One presign, one object. */
+    settle(fileId: string): void;
+    /** Outstanding mints — for tests. */
+    size(): number;
+}
+export declare function createUploadRelay(now?: () => number): UploadRelay;

package/dist/dev/upload_relay.js

@@ -0,0 +1,61 @@
+/**
+ * Dev-only upload relay: the bookkeeping that lets `lotics app dev` upload a file.
+ *
+ * Dev runs against the PROD bucket (there is no dev bucket), whose CORS allowlist
+ * holds the real app origins (`https://*.lotics.app`), not `http://localhost:<port>`.
+ * A browser PUT straight to the presigned URL is blocked before it leaves the page,
+ * so without a relay no file-touching app can be exercised locally at all.
+ *
+ * The dev server therefore relays the bytes: the wrapper page PUTs same-origin (no
+ * preflight, no CORS) and Node — which has no same-origin policy — forwards them on.
+ *
+ * The security property, and the reason the page never names its destination: a
+ * relay that forwarded to a client-supplied URL would be an open proxy. So the page
+ * sends only a `file_id`, and the relay writes ONLY to a presigned URL it minted
+ * itself for that id, moments earlier, via its own authenticated API call. There is
+ * no client-controlled target — hence nothing to allowlist, and no SSRF surface.
+ *
+ * Production is untouched: it PUTs direct-to-storage, keeping every byte off the
+ * API server.
+ */
+/**
+ * How long a mint is worth keeping. This is a pruning window, not a correctness gate —
+ * storage is the authority on whether a presign is still valid (an expired one is refused
+ * there, and the wrapper surfaces that). It only needs to outlive the presign (~10 min) so
+ * the relay never 404s a PUT that storage would still have accepted.
+ */
+const PRESIGN_TTL_MS = 15 * 60 * 1000;
+export function createUploadRelay(now = Date.now) {
+    const minted = new Map();
+    const prune = (at) => {
+        for (const [id, entry] of minted) {
+            if (at - entry.mintedAt > PRESIGN_TTL_MS)
+                minted.delete(id);
+        }
+    };
+    return {
+        rewriteMint(result) {
+            const mint = result;
+            if (typeof mint?.file_id !== "string" || typeof mint?.upload_url !== "string")
+                return result;
+            const at = now();
+            prune(at);
+            minted.set(mint.file_id, { url: mint.upload_url, mintedAt: at });
+            return { ...mint, upload_url: `/_upload/${encodeURIComponent(mint.file_id)}` };
+        },
+        destinationFor(fileId) {
+            const entry = minted.get(fileId);
+            if (!entry)
+                return null;
+            if (now() - entry.mintedAt > PRESIGN_TTL_MS) {
+                minted.delete(fileId);
+                return null;
+            }
+            return entry.url;
+        },
+        settle(fileId) {
+            minted.delete(fileId);
+        },
+        size: () => minted.size,
+    };
+}

package/dist/dev/upload_relay.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dev/upload_relay.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest";
+import { createUploadRelay } from "./upload_relay.js";
+const MINT = {
+    file_id: "fil_abc",
+    file_storage_key: "org/files/fil_abc/photo.jpg",
+    upload_url: "https://production.r2.cloudflarestorage.com/org/files/fil_abc/photo.jpg?X-Amz-Signature=deadbeef",
+};
+describe("upload relay — the page PUTs same-origin", () => {
+    it("hands the page a same-origin URL and keeps everything else it needs to finalize", () => {
+        const relay = createUploadRelay();
+        const seen = relay.rewriteMint(MINT);
+        expect(seen.upload_url).toBe("/_upload/fil_abc");
+        // file_storage_key + file_id still reach the page — `upload_complete` needs both.
+        expect(seen.file_id).toBe("fil_abc");
+        expect(seen.file_storage_key).toBe(MINT.file_storage_key);
+    });
+    it("does not mutate the mint it was handed", () => {
+        const relay = createUploadRelay();
+        relay.rewriteMint(MINT);
+        expect(MINT.upload_url).toContain("r2.cloudflarestorage.com");
+    });
+});
+describe("upload relay — it writes ONLY where it was told to by itself", () => {
+    it("relays to the presigned URL it minted for that id", () => {
+        const relay = createUploadRelay();
+        relay.rewriteMint(MINT);
+        expect(relay.destinationFor("fil_abc")).toBe(MINT.upload_url);
+    });
+    it("refuses an id it never minted — there is no client-supplied destination to honour", () => {
+        const relay = createUploadRelay();
+        expect(relay.destinationFor("fil_never_seen")).toBeNull();
+    });
+    it("refuses a mint that has aged past its presign", () => {
+        let clock = 1_000_000;
+        const relay = createUploadRelay(() => clock);
+        relay.rewriteMint(MINT);
+        clock += 16 * 60 * 1000; // presigns die at ~10 min; the relay holds 15
+        expect(relay.destinationFor("fil_abc")).toBeNull();
+    });
+});
+describe("upload relay — lifecycle", () => {
+    it("forgets a mint once its bytes have landed", () => {
+        const relay = createUploadRelay();
+        relay.rewriteMint(MINT);
+        relay.settle("fil_abc");
+        expect(relay.destinationFor("fil_abc")).toBeNull();
+        expect(relay.size()).toBe(0);
+    });
+    it("keeps the mint on a failed PUT so the page's retry can reuse it", () => {
+        const relay = createUploadRelay();
+        relay.rewriteMint(MINT);
+        // No settle() — the storage PUT 5xx'd and the wrapper page retries.
+        expect(relay.destinationFor("fil_abc")).toBe(MINT.upload_url);
+    });
+    it("prunes dead mints instead of growing forever across a long dev session", () => {
+        let clock = 0;
+        const relay = createUploadRelay(() => clock);
+        relay.rewriteMint({ ...MINT, file_id: "fil_old" });
+        clock += 16 * 60 * 1000;
+        relay.rewriteMint({ ...MINT, file_id: "fil_new" });
+        expect(relay.size()).toBe(1); // the stale one was swept on the next mint
+        expect(relay.destinationFor("fil_new")).toBe(MINT.upload_url);
+    });
+});
+describe("upload relay — a response that carries no mint", () => {
+    it("passes through untouched rather than inventing a relay for it", () => {
+        const relay = createUploadRelay();
+        const odd = { message: "upstream changed shape" };
+        expect(relay.rewriteMint(odd)).toBe(odd);
+        expect(relay.size()).toBe(0);
+    });
+    it("tolerates null without throwing", () => {
+        const relay = createUploadRelay();
+        expect(relay.rewriteMint(null)).toBeNull();
+    });
+});

package/dist/dev/wrapper_page.js

@@ -120,7 +120,13 @@ export function buildWrapperPage(args) {
 
       // The iframe SDK sends one "upload" op carrying a File. A File can't
       // cross the JSON /_rpc hop, so the upload runs here in the browser:
-      // mint a presigned URL, PUT the bytes to storage, then finalize.
+      // mint an upload URL, PUT the bytes, then finalize.
+      //
+      // In dev the minted URL is same-origin (/_upload/<file_id>) — the dev
+      // server relays the bytes to storage on our behalf, because the prod
+      // bucket's CORS does not admit a localhost origin. Production PUTs the
+      // presigned storage URL directly. Same three lines either way: the page
+      // PUTs wherever the mint points.
       //
       // Retry policy parity with the production SDK
       // (packages/app-sdk/src/upload/transport.ts): 3 PUT attempts with

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>;