@lotics/cli 0.76.1 → 0.86.0

package/dist/generate_package_fields.test.js

@@ -1,24 +1,24 @@
 import { describe, expect, it } from "vitest";
 import { generatePackageAppFields } from "./generate_package_fields.js";
-const contract = {
-    entities: [
-        {
-            alias: "tasks",
-            fields: [
-                { alias: "title" },
-                {
-                    alias: "status",
-                    options: [{ alias: "to_do" }, { alias: "doing" }, { alias: "done" }],
-                },
-            ],
-        },
-        { alias: "projects", fields: [{ alias: "name" }] },
-    ],
-    roles: [{ alias: "approver" }],
+// A live installation binding — fully-qualified alias → concrete id. The
+// generator sources the alias SET here (never a contract file); the emitted
+// module resolves the SAME keys through `getAppBinding()` at runtime.
+const binding = {
+    fields: {
+        "tasks.title": "fld_title",
+        "tasks.status": "fld_status",
+        "projects.name": "fld_name",
+    },
+    options: {
+        "tasks.status:to_do": "opt_todo",
+        "tasks.status:doing": "opt_doing",
+        "tasks.status:done": "opt_done",
+    },
+    roles: { approver: "grp_approver" },
 };
 describe("generatePackageAppFields", () => {
-    it("emits runtime-resolved F/OPT/ROLE keyed by contract aliases", () => {
-        const src = generatePackageAppFields(contract);
+    it("emits runtime-resolved F/OPT/ROLE keyed by the binding's aliases", () => {
+        const src = generatePackageAppFields(binding);
         // Resolves through the SDK binding at module load (top-level await).
         expect(src).toContain('import { getAppBinding } from "@lotics/app-sdk";');
         expect(src).toContain("const binding = await getAppBinding();");
@@ -31,21 +31,29 @@ describe("generatePackageAppFields", () => {
         expect(src).toContain('to_do: bound(binding.options, "tasks.status:to_do", "option")');
         expect(src).toContain('done: bound(binding.options, "tasks.status:done", "option")');
         expect(src).not.toContain('"tasks.title:');
-        // ROLE map from contract roles.
+        // ROLE map from the binding's roles.
         expect(src).toContain('approver: bound(binding.roles, "approver", "role")');
         // No concrete id in any VALUE position — the module is workspace-agnostic.
         // (Doc comments legitimately name the id prefixes, so match quoted ids.)
         expect(src).not.toMatch(/"(fld|opt|tbl|grp)_/);
     });
-    it("emits valid empty maps for an empty contract", () => {
-        const src = generatePackageAppFields({});
+    it("emits valid empty maps for an empty binding", () => {
+        const src = generatePackageAppFields({ fields: {}, options: {}, roles: {} });
         expect(src).toContain("export const F = {} as const;");
         expect(src).toContain("export const OPT = {} as const;");
         expect(src).toContain("export const ROLE = {} as const;");
         // Still imports the SDK so the module shape is uniform.
         expect(src).toContain("const binding = await getAppBinding();");
     });
-    it("is deterministic — same contract, same bytes", () => {
-        expect(generatePackageAppFields(contract)).toBe(generatePackageAppFields(contract));
+    it("quotes an alias that is not a valid identifier", () => {
+        const src = generatePackageAppFields({
+            fields: { "tasks.2nd_field": "fld_x" },
+            options: {},
+            roles: {},
+        });
+        expect(src).toContain('"2nd_field": bound(binding.fields, "tasks.2nd_field", "field")');
+    });
+    it("is deterministic — same binding, same bytes", () => {
+        expect(generatePackageAppFields(binding)).toBe(generatePackageAppFields(binding));
     });
 });

package/dist/package_commands.d.ts

@@ -1,262 +1,46 @@
-import { LoticsClient, type PackageBinding, type ExtractFinding } from "./client.js";
-import { type KnowledgeUpgradeEntry, type KnowledgeResolution, type ModificationResolution } from "@lotics/shared/schemas/packages";
-/** One dev workspace's pinned installation of this package (manifest bookkeeping). */
-interface PackageDevInstallation {
-    app_id: string;
-    version: number;
-}
-/**
- * One package-managed knowledge doc's authoring metadata, from
- * `package.json#lotics.package.knowledge` (alias → this). The content lives in a
- * sibling `knowledge/<alias>.md` file; `build`/`publish` sha256 the file and fold
- * both into the contract's `knowledge` namespace. Round-trips through the manifest
- * so a manifest write (e.g. stamping the package id on first publish) never drops
- * it — and it therefore ships in `source.tar.gz` for eject/extract.
- */
-interface PackageKnowledgeManifestEntry {
-    name: string;
-    description: string | null;
-    active_by_default: boolean;
-}
-/** The 5 document-template kinds a package template may declare (== the contract's). */
-export type PackageTemplateKind = "html" | "email" | "excel" | "word" | "pdf-form";
-/**
- * One package-managed document template's authoring metadata, from
- * `package.json#lotics.package.templates` (alias → this). The template file lives
- * at `templates/<file>`; `build`/`publish` fold it into the contract's
- * `templates` namespace — an inline kind (html/email) reads the file as `content`,
- * a file-backed kind (excel/word/pdf-form) records `bytes_ref: templates/<file>`
- * (the bytes ride in `source.tar.gz`, like a knowledge doc's content) — then
- * `foldTemplateShasIntoContract` computes each `content_sha256`. This is how a
- * CONTENT package declares standalone templates (an app package authors them in
- * `contract.json` directly). Round-trips through the manifest so a manifest write
- * never drops it.
- */
-interface PackageTemplateManifestEntry {
-    name: string;
-    type: PackageTemplateKind;
-    /** The template file's name within the project's `templates/` dir. */
-    file: string;
-}
-/**
- * The `package.json#lotics.package` block of a package project. `id` is null
- * until the first publish (which creates the registry package); `version` tracks
- * the latest version this project has published; `dev` maps a dev workspace id to
- * the installation it scaffold-syncs into.
- */
-/** A package project's kind — mirrors the registry `packages.kind` (immutable after create). */
-export type PackageKind = "app" | "content";
-interface PackageManifest {
-    id: string | null;
-    name: string;
-    description: string | null;
-    /**
-     * 'app' (the full materialized blueprint) | 'content' (a standalone content
-     * package). Threaded to `createPackage` on first publish and used locally to
-     * gate the build (a content package has no app source to compile). Defaults to
-     * 'app' for a manifest written before content packaging.
-     */
-    kind: PackageKind;
-    version: number | null;
-    /** alias → knowledge-doc authoring metadata (content in `knowledge/<alias>.md`). */
-    knowledge: Record<string, PackageKnowledgeManifestEntry>;
-    /** alias → document-template authoring metadata (file in `templates/<file>`). */
-    templates: Record<string, PackageTemplateManifestEntry>;
-    /**
-     * Doc NAMES the package's agents route to but the package does not own —
-     * install/health WARN when a name has no doc in the workspace. Lives under
-     * `lotics.package` (one coherent home for everything package-related), NOT a
-     * sibling of it.
-     */
-    knowledge_expects: string[];
-    dev: Record<string, PackageDevInstallation>;
-}
-interface PackageProjectFile {
-    /** Parsed package.json, carrying the `lotics.package` manifest under `lotics`. */
-    pkgJson: Record<string, unknown>;
-    manifest: PackageManifest;
-}
-/** Read the package project's manifest, failing loud when the dir isn't one. */
-export declare function readPackageProject(projectDir: string): PackageProjectFile;
-/** Persist an updated manifest back into the project's package.json (atomic write). */
-export declare function writePackageManifest(projectDir: string, project: PackageProjectFile): void;
-/**
- * The package.json to ship INSIDE `source.tar.gz`: the on-disk manifest with the
- * author-local `lotics.package.dev` map stripped. `dev` is the author's private
- * dev-workspace → installation bookkeeping; it must never reach a consumer (every
- * install carries the source, and `lotics app pull` ejects it). Returns a
- * sanitized copy — the on-disk package.json is left untouched. `id`/`name`/
- * `description`/`version` are the package's stable identity and stay.
- */
-export declare function sanitizePackageJsonForSource(pkgJson: Record<string, unknown>): Record<string, unknown>;
-/**
- * Transform an app project's package.json (the source archive `lotics app pull`
- * downloads, carrying the `lotics.app_id`/`workspace_id` app manifest) into a
- * package project's `PackageProjectFile`: the app manifest is stripped ENTIRELY
- * and a fresh, unpublished `lotics.package` manifest (id/version null) is
- * grafted. Pure — returns a new value, never mutates the input;
- * `writePackageManifest` writes it (atomic). The bespoke→package promotion's
- * manifest inversion.
- */
-export declare function draftPackageProjectFromApp(appPkgJson: Record<string, unknown>, args: {
-    name: string;
-    description: string | null;
-}): PackageProjectFile;
-/**
- * Parse + validate `.lotics/adopt_binding.json` against the app being adopted.
- * REFUSES a pin recorded for a different app: a binding maps ONE workspace's
- * concrete ids, so replaying it onto another app would bind the wrong objects.
- * Pure; the CLI never interprets the binding, only round-trips it to the server.
- */
-export declare function parseAdoptBindingFile(raw: unknown, expectedAppId: string): {
-    app_id: string;
-    workspace_id: string;
-    binding: PackageBinding;
-    knowledge_binding: Record<string, string>;
-};
-/**
- * Render an extraction report grouped by severity (errors, then warnings, then
- * info), one `  [<severity>] <area>: <message>` line each, and classify whether
- * any `error` finding is present. An `error` ⇒ the draft is not publishable
- * as-is, so `lotics package extract` exits non-zero. Pure — the command prints
- * `lines` to stderr and gates on `hasError`.
+import { LoticsClient, type ExtractFinding } from "./client.js";
+import { 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.
+ */
+export declare function readLocalAppManifest(projectDir: string): {
+    app_id: string | null;
+    knowledge: Array<{
+        alias: string;
+        doc_id: string;
+    }>;
+} | null;
+/** Parse repeated `--rename old=new` flags into `{ from, to }[]` (first-publish alias fixes). */
+export declare function parseRenameFlags(renames: string[]): Array<{
+    from: string;
+    to: string;
+}>;
+/**
+ * Render a package-extract report grouped by severity (errors, then warnings,
+ * then info), one `  [<severity>] <area>: <message>` line each, and classify
+ * whether any `error` finding is present. Shared by the release preview display.
+ * Pure — the command prints `lines` to stderr and gates on `hasError`.
  */
 export declare function formatExtractReport(report: ExtractFinding[]): {
     lines: string[];
     hasError: boolean;
 };
 /**
- * Fold a package project's knowledge corpus into its contract before publish:
- * per `lotics.package.knowledge` alias, read `knowledge/<alias>.md`, sha256 the
- * bytes, and emit the contract's `knowledge` namespace (alias → {name,
- * description, content_ref, content_sha256, active_by_default}) +
- * `knowledge_expects` (from `lotics.package.knowledge_expects`). This is the ONE
- * place the sha is computed — it can't be hand-authored, which is why knowledge
- * (unlike a template `bytes_ref`) is derived rather than written into
- * contract.json. The content files themselves ride in `source.tar.gz`
- * automatically: `knowledge/` is a top-level dir, so `stagePackageSource` copies
- * it like any other source (the same mechanism that carries template bytes). Pure
- * w.r.t. `contract` — returns a new object; the server re-validates the folded
- * namespace at publish.
- */
-export declare function foldKnowledgeIntoContract(projectDir: string, project: PackageProjectFile, contract: Record<string, unknown>): Record<string, unknown>;
-/**
- * Fold a CONTENT package's manifest-declared templates into its contract before
- * publish: per `lotics.package.templates` alias, an INLINE kind (html/email) reads
- * `templates/<file>` into the contract template's `content`; a FILE-BACKED kind
- * (excel/word/pdf-form) records `bytes_ref: templates/<file>` (the bytes ride in
- * `source.tar.gz` — `templates/` is a top-level dir `stagePackageSource` copies,
- * the same mechanism that carries knowledge content + app-package template bytes).
- * The per-template `content_sha256` is NOT computed here — `foldTemplateShasIntoContract`
- * runs after and derives it (inline: the utf-8 content; file-backed: the file bytes).
- *
- * Appends to any templates the contract already declares (an app package authors
- * templates in `contract.json` directly; the manifest path is how a content
- * package — with no `contract.json` templates — declares them). An alias in BOTH
- * is a loud error. Pure w.r.t. `contract` — returns a new object.
- */
-export declare function foldTemplatesIntoContract(projectDir: string, project: PackageProjectFile, contract: unknown): Record<string, unknown>;
-/**
- * Fold a freshly-computed `content_sha256` into every template of a package
- * contract before publish — the modified-detection reference the install/upgrade
- * flow compares live content against. Like knowledge's sha (foldKnowledge…), it
- * can't be hand-authored: an INLINE template's sha covers its utf-8 `content`; a
- * FILE-BACKED template's sha covers the `bytes_ref` file's bytes (the same bytes
- * that ride in `source.tar.gz` and install stores verbatim). Always recomputed
- * (never trusted from contract.json), so the published contract's sha is exact.
- * Pure w.r.t. `contract` — returns a new object; the server re-validates.
- */
-export declare function foldTemplateShasIntoContract(projectDir: string, contract: Record<string, unknown>): Record<string, unknown>;
-/**
- * Copy the project's source tree into `sourceStage` with explicit TOP-LEVEL
- * excludes, writing a sanitized `package.json` in place of the on-disk one.
- * Deliberately not tar `--exclude` flags: those match at any depth (a nested
- * `templates/dist/` would be silently dropped) and GNU tar vs bsdtar (macOS)
- * disagree on `./`-prefixed patterns, which broke the sanitized-package.json
- * graft on macOS.
- */
-export declare function stagePackageSource(projectDir: string, sourceStage: string): void;
-/** The minimal, valid starting contract a `package new` scaffold ships. */
-export declare function starterContract(name: string): Record<string, unknown>;
-/**
- * `lotics package new <name> [path] [--kind content]` — scaffold a package
- * project. An `app` package reuses the app starter (Vite+React+TS) for the code
- * surface, swaps its app manifest for a package manifest, and adds a starter
- * `contract.json`; a `content` package scaffolds a docs-only corpus (no app
- * source). The project publishes with `lotics package publish`.
- */
-export declare function packageNew(args: {
-    name: string;
-    targetPath?: string;
-    kind?: PackageKind;
-}): Promise<void>;
-/**
- * `lotics package build [path]` — build the publishable bundle and write it to
- * `bundle.tar.gz` in the project. Mostly a local sanity check / CI artifact;
- * `publish` and `dev`/`sync` build the bundle in memory directly.
- */
-export declare function packageBuild(args: {
-    projectDir?: string;
-}): Promise<void>;
-/**
- * `lotics package publish [path] [-m <changelog>]` — publish a new version.
- */
-export declare function packagePublish(client: LoticsClient, args: {
-    projectDir?: string;
-    changelog?: string;
-}): Promise<void>;
-/**
- * Fail loud unless `workspace` is a throwaway dev workspace. The dev/sync
- * scaffold path publishes a new version and scaffold-installs package tables into
- * the resolved workspace, so the target MUST be a dev workspace — this mirrors
- * the server-side `package reset` gate so a forgotten `--workspace` (prod
- * selected) can never scaffold package tables into prod. Fails closed: an absent
- * `is_dev` (a server that doesn't yet serialize it) is treated as non-dev.
- */
-export declare function assertDevWorkspace(workspace: {
-    id: string;
-    name: string;
-    is_dev?: boolean;
-}): void;
-/**
- * `lotics package sync [path]` — re-run the scaffold-sync into the dev workspace
- * (the continuous loop: edit contract → sync additively migrates + re-materializes).
- */
-export declare function packageSync(client: LoticsClient, args: {
-    projectDir?: string;
-}): Promise<void>;
-/**
- * `lotics package dev [path] [--workspace <dev_ws>] [--view-as <member>]` —
- * scaffold-sync the package into the dev workspace, then run the existing app
- * dev server against the resulting installation (HMR over the local source, RPC
- * forwarded to the live installation). The inner loop: edit contract → re-run to
- * sync; edit code → hot reload.
- */
-export declare function packageDev(client: LoticsClient, args: {
-    projectDir?: string;
-    port?: number;
-    vitePort?: number;
-}): Promise<void>;
-/**
- * `lotics package reset [path]` — DEV-ONLY, hard-gated. Drops the dev
- * installation's package-owned scaffolded tables and re-scaffolds them clean. The
- * backend refuses any workspace not flagged as a dev workspace, so this can never
- * erase a real workspace's data. The dev installation is resolved from the
- * project manifest's pin for the selected workspace.
- */
-export declare function packageReset(client: LoticsClient, args: {
-    projectDir?: string;
-}): Promise<void>;
-export type UpgradeResolutionValue = "recreate" | "revert" | "keep" | {
-    bind_to: string;
-};
-/**
- * Parse repeated `--resolve <key>=<value>` flags. Drift entries
- * (`<namespace>.<alias>`) take `recreate` or an existing id; modified
- * artifacts (`<kind>.<alias>`) take `revert` or `keep`. Any other value is a
- * bind_to id; the server validates value-kind against what the key resolves.
+ * Parse repeated `--resolve <key>=<value>` flags into the ONE namespaced
+ * resolutions map every upgrade wire takes. Keys pass through verbatim — a
+ * drifted binding entry (`<namespace>.<alias>`), a modified artifact
+ * (`<kind>.<alias>`), a bundled/standalone knowledge doc (`knowledge.<alias>`),
+ * or a live-role re-point (`roles.<alias>`). A value that is one of the
+ * resolution verbs stays a verb; anything else is a `{ bind_to }` id. The
+ * server validates value-kind against what each key resolves.
  */
-export declare function parseResolveFlags(resolve: string[]): Record<string, UpgradeResolutionValue>;
+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.
@@ -270,11 +54,13 @@ export declare function packageDoctor(client: LoticsClient, args: {
  * the exact --resolve syntax) while any binding drift, modified core artifact, or
  * consent-requiring bundled-knowledge doc lacks a resolution.
  *
- * `--resolve` is shared across the finding classes: a key naming a bundled
- * knowledge doc routes to `knowledge_resolutions` (apply|keep|archive|recreate|
- * unbind), everything else to core `resolutions`; `--bind-to` consents an
- * added-knowledge-doc name collision; `--apply-all` accepts the package's version
- * for every consent-requiring knowledge doc (overwriting local edits).
+ * `--resolve` speaks ONE namespaced grammar, passed to the server verbatim: a
+ * drifted binding entry (`<namespace>.<alias>`), a modified artifact
+ * (`<kind>.<alias>`), a bundled knowledge doc (`knowledge.<alias>` —
+ * apply|keep|archive|recreate|unbind), or a live-role re-point
+ * (`roles.<alias>=<grp_id>`). `--bind-to` consents an added-knowledge-doc name
+ * collision; `--apply-all` accepts the package's version for every
+ * consent-requiring knowledge doc (overwriting local edits).
  */
 export declare function packageUpgrade(client: LoticsClient, args: {
     app_id: string;
@@ -293,50 +79,28 @@ export declare function packageShow(client: LoticsClient, args: {
     package_id: string;
 }): Promise<void>;
 /**
- * Route an app-install upgrade's `--resolve` entries into the core-artifact
- * bucket vs the bundled-knowledge bucket. `--resolve` is shared between the two
- * finding classes, so each key is matched against the preview: a key that names a
- * bundled knowledge doc resolves that doc (its value validated against the doc's
- * change class here — the app path has no separate knowledge-only parser);
- * anything else stays a core resolution (a `<namespace>.<alias>` drift, a
- * `<kind>.<alias>` modified core, or a key the server validates). A key that is
- * BOTH a knowledge alias and a core-artifact key is ambiguous — throw rather than
- * guess which the operator meant.
- */
-export declare function routeAppUpgradeResolve(resolve: string[], knowledgeEntries: KnowledgeUpgradeEntry[], coreKeys: ReadonlySet<string>): {
-    coreResolve: string[];
-    knowledgeResolutions: Record<string, KnowledgeResolution>;
-};
-/**
- * Route a STANDALONE content upgrade's shared `--resolve <alias>=<value>` flags
- * into the knowledge vs templates buckets by matching each alias against the two
- * preview namespaces. A doc alias takes apply|keep|archive|recreate|unbind; a
- * template alias takes revert|keep. An alias present in BOTH namespaces is
- * ambiguous → loud error (no guess). An alias in NEITHER → error. The value is
- * validated against the namespace it routes to. Exported for testing.
+ * 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 routeContentResolveFlags(resolve: string[], knowledgeAliases: ReadonlySet<string>, templateAliases: ReadonlySet<string>): {
-    knowledge: Record<string, KnowledgeResolution>;
-    templates: Record<string, ModificationResolution>;
-};
+export declare function redirectContentPciForm(client: LoticsClient, pci_id: string, verb: "upgrade" | "uninstall"): Promise<never>;
 /**
- * Preview-then-apply a STANDALONE content installation upgrade — knowledge docs
- * AND document templates behind one review gate. Prints the per-alias plan;
- * refuses (exit 1, with the exact `--resolve` syntax) while any consent-requiring
- * entry lacks a resolution — a modified knowledge change/removal or drift, or a
- * locally-edited changed template. `--apply-all` auto-resolves EVERY consent entry
- * by accepting the package's version (knowledge changed→apply, removed→archive,
- * drifted→recreate; template→revert) — an explicit bulk "take upstream" that
- * discards local edits. `--resolve <alias>=<value>` and `--bind-to <alias>=<kdc_id>`
- * resolve entries individually (`--resolve` is routed to the right namespace by
- * matching the alias against the preview).
+ * `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 packageUpgradeKnowledge(client: LoticsClient, args: {
-    installation_id: string;
+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. */
@@ -350,9 +114,11 @@ export declare function packageInstall(client: LoticsClient, args: {
     config?: Record<string, string | number | boolean>;
 }): Promise<void>;
 /**
- * `lotics package uninstall <app_id|pci_id>` — ONE command over both installation
- * kinds, dispatched by the id form (mirrors `package upgrade`):
- *   - a `pci_` id → a STANDALONE CONTENT installation: deletes the row and (unless
+ * `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
@@ -366,10 +132,12 @@ export declare function packageUninstall(client: LoticsClient, args: {
     archive_tables: boolean;
 }): Promise<void>;
 /**
- * `lotics package list-content` — list the selected workspace's package-managed
- * content installations (standalone `pci_` corpora + app-bundled ones), each
- * with its registry status. The read surface that surfaces a standalone `pci_` id
- * for `upgrade` / `uninstall` (install prints it once; nothing else did before).
+ * `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 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: {
@@ -387,38 +155,59 @@ export declare function packageConfig(client: LoticsClient, args: {
     sets: string[];
 }): Promise<void>;
 /**
- * `lotics package retire <package_id> [--undo]` — retire (or un-retire) a
- * registry package. Owner-org admin-only.
+ * `lotics app unpublish <app_id|package_id> [--undo]` — take a published package
+ * off the shelf (or `--undo` restore it): new installs refuse it and it hides
+ * from other orgs, while existing installations keep working and may still
+ * upgrade. Given an app id (an installation of the package) it resolves the
+ * package from the app; a package id targets it directly. Owner-org admin-only.
  */
-export declare function packageRetire(client: LoticsClient, args: {
-    package_id: string;
+export declare function appUnpublish(client: LoticsClient, args: {
+    id: string;
     undo: boolean;
 }): Promise<void>;
-export declare function packageExtract(client: LoticsClient, args: {
-    app_id: string;
-    targetPath?: string;
-}): Promise<void>;
 /**
- * `lotics package adopt <app_id> [path]` — bind the published package project
- * onto the origin app (docs/packages.md § Promotion). Reads the project
- * manifest (must be published — refuses otherwise), resolves the version
- * (`--version N` else the manifest's), and reads `.lotics/adopt_binding.json`,
- * REFUSING a pin recorded for a different app. On success the app becomes
- * installation #1 and is upgradeable again; a server ConflictError (naming the
- * unfaithful aliases) surfaces verbatim.
- */
-export declare function packageAdopt(client: LoticsClient, args: {
-    app_id: string;
-    version?: number;
+ * `lotics app publish [app_id|.] [--rename old=new ...] [-m <changelog>] [--yes]` —
+ * FIRST-RELEASE a bespoke app as a package (docs/packages.md § Promotion). Nothing
+ * starts as a package. Mirrors `app release`'s preview→apply UX: it first shows the
+ * dry-run preview (GET, no writes) — the package name, the auto-minted RENAMABLE
+ * aliases (the exact `--rename` keys, so v1's frozen aliases are inspected first,
+ * never a blind publish), and the extract findings — then APPLIES only with
+ * `--yes` (else exits 1 with the re-run hint). On apply the server extracts the
+ * contract, creates the registry package, publishes v1 from the DEPLOYED source +
+ * dist, and pins the origin as installation #1. `--rename old=new` fixes an
+ * auto-minted alias before v1 freezes it; an `error` finding blocks the apply. An
+ * already-linked app releases with `lotics app release` instead. The app id is the
+ * positional (`.`/omitted → resolved from the local app project manifest).
+ */
+export declare function appPublish(client: LoticsClient, args: {
+    app_id?: string;
+    renames: string[];
+    changelog?: string;
+    yes: boolean;
     projectDir?: string;
 }): Promise<void>;
 /**
- * `lotics package fleet-upgrade <package_id> [--version N]` — bring every
- * installation of the package across the caller's org to the target version.
- * Hands-off applies only where the preview is clean; skipped/failed
- * installations are reported per line and the process exits 1 so a release
- * script can gate on "fleet fully current".
+ * `lotics app release [app_id|.] -m <changelog> [--yes]` — snapshot an
+ * adopted/installed origin app into its next registry version (docs/packages.md
+ * § Promotion). The origin is the permanent working copy; a release binding-aware-
+ * extracts it (stable aliases), repackages its DEPLOYED source + dist as the
+ * bundle, publishes the next version, and re-pins the origin. Prints the preview
+ * first (next version, new + changed aliases, 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;
+    changelog: string;
+    yes: boolean;
+    projectDir?: string;
+}): Promise<void>;
 /**
  * `lotics package yank <package_id> <version> [--undo]` — mark a published
  * version uninstallable (or restore it). New installs/upgrades/adopts refuse a
@@ -430,8 +219,3 @@ export declare function packageYank(client: LoticsClient, args: {
     version: number;
     undo: boolean;
 }): Promise<void>;
-export declare function packageFleetUpgrade(client: LoticsClient, args: {
-    package_id: string;
-    version?: number;
-}): Promise<void>;
-export {};