@lotics/cli 0.76.0 → 0.76.1

package/README.md

@@ -197,7 +197,7 @@ lotics ui link card --remove               # finalize: PR + publish, then drop t
 
 ## App packages
 
-A maintained, versioned app library: author once, install into many workspaces, upgrade per-workspace. Any org authors its own packages (publishing is owner-org-only); Lotics-backed packages carry the `official` badge. See `docs/app_packages.md` for the model.
+A maintained, versioned app library: author once, install into many workspaces, upgrade per-workspace. Any org authors its own packages (publishing is owner-org-only); Lotics-backed packages carry the `official` badge. See `docs/packages.md` for the model.
 
 ```bash
 # Author (any org admin; the package is owned by your org)
@@ -222,6 +222,7 @@ lotics package upgrade app_...             # preview, then apply (additive; over
 lotics package fleet-upgrade apg_...       # upgrade EVERY org installation (clean ones apply; findings skip, exit 1)
 lotics package upgrade app_... --resolve fields.deal.stage=recreate   # resolve reported drift
 lotics package upgrade app_... --resolve queries.tasks=keep           # consent for a local edit (or =revert)
+lotics package upgrade app_... --resolve template.quote=revert        # a locally-edited template (clean ones auto-update; or =keep)
 lotics package eject app_...               # one-way: sever the package link
 lotics workspace doctor                    # dangling schema references across the workspace (exit 1 on findings)
 
@@ -238,6 +239,35 @@ lotics package adopt app_...               # bind the package onto the origin ap
 
 Extract writes `.lotics/adopt_binding.json` (the origin pin, excluded from published bundles); `adopt` reads it back and refuses a pin recorded for a different app. After promotion the package project is the master — iterate contract-first (`package dev`/`sync` → `publish`), never extract again.
 
+### Content packages
+
+A **content** package ships **knowledge docs and/or document templates** — no app, just the artifacts. Knowledge is the reference corpus an agent looks up by name; templates are standalone document templates. Content comes two ways: bundled *with an app* (installing the app delivers its agents' docs) or as a standalone content package (a versioned corpus). Install delivers, upgrade refreshes — preserving stable `kdc_`/`tmpl_` ids + a version snapshot per change. See `docs/packages.md` § Content.
+
+```bash
+# Author a content package (scaffolds a knowledge/ dir + manifest; add templates/ + a
+# lotics.package.templates entry per template — inline html/email or file-backed excel/word/pdf-form)
+lotics package new my-sops --kind content
+lotics package publish -m "v1: SOP corpus + templates"
+
+# Install into a workspace (a same-named local DOC collides — consent with --bind-to; templates never collide)
+lotics package install apg_...                          # app OR content, kind-branched
+lotics package 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 vs app-bundled
+
+# Refresh a standalone content install (pci_ id from install / list-content) — one gate over docs + templates
+lotics package upgrade pci_...                          # preview, then apply
+lotics package upgrade pci_... --resolve policy=apply   # a doc: apply|keep|archive|recreate|unbind
+lotics package upgrade pci_... --resolve quote=revert   # a locally-edited template: revert|keep (clean ones auto-update)
+lotics package upgrade pci_... --apply-all              # accept upstream for every doc + template (OVERWRITES local edits)
+lotics package uninstall pci_... --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 package upgrade <app_id>`) previews its bundled-knowledge changes alongside the plan and resolves them with the SAME flags: a `--resolve <alias>=apply|keep|archive|recreate|unbind` naming a bundled doc routes to the doc (anything else stays a core-artifact resolution; a name that is both errors), `--bind-to` consents an added-doc collision, `--apply-all` takes the package's version for every consent-requiring doc.
+
+To package the knowledge an existing app's agents route to, declare it in the app project's `package.json#lotics.knowledge` (`[{ alias, doc_id }]`, + `lotics.knowledge_expects` for docs the agents assume but the package doesn't own), then `lotics package extract` / `adopt` as usual.
+
 ## SDK
 
 ```typescript

package/dist/args.d.ts

@@ -50,14 +50,27 @@ export declare function parseArgs(argv: string[]): {
          * `--resolve <key>=recreate|revert|keep|<id>` (repeatable): upgrade
          * resolutions — drift entries (`<namespace.alias>`) take `recreate` or an
          * existing id; modified-core entries (`<kind>.<alias>`) take `revert` or
-         * `keep`.
+         * `keep`. For a standalone KNOWLEDGE upgrade, `<alias>=apply|keep|archive|
+         * recreate|unbind`.
          */
         resolve: string[];
+        /**
+         * `--bind-to <alias>=<kdc_id>` (repeatable): consent to adopt an existing
+         * same-named doc as package-managed — resolves a knowledge name collision at
+         * install / a created-doc collision at upgrade.
+         */
+        bindTo: string[];
+        /** `--keep-content` (`package uninstall` of a content install): retain the package-bound docs instead of archiving them. */
+        keepContent: boolean;
+        /** `--apply-all` (knowledge `package upgrade`): accept the package's version for every consent entry. */
+        applyAll: boolean;
+        /** `--kind <app|content>` (`package new`): the package project kind to scaffold (default app). */
+        kind?: string;
         /** `--config key=value` (repeatable): per-knob config overrides at `package install`. */
         config: string[];
         /** `--set key=value` (repeatable): per-knob config edits at `package config`. */
         set: string[];
-        /** `--archive-tables`: also archive the scaffolded tables at `package uninstall`. */
+        /** `--archive-tables` (`package uninstall` of an app install): also archive the scaffolded tables. */
         archiveTables: boolean;
         /** `--undo`: reverse a `package retire` / `package yank`. */
         undo: boolean;

package/dist/args.js

@@ -31,6 +31,10 @@ export function parseArgs(argv) {
         cleanup: false,
         packageVersion: undefined,
         resolve: [],
+        bindTo: [],
+        keepContent: false,
+        applyAll: false,
+        kind: undefined,
         config: [],
         set: [],
         archiveTables: false,
@@ -110,6 +114,23 @@ export function parseArgs(argv) {
                 flags.resolve.push(value);
                 break;
             }
+            case "--bind-to": {
+                const value = argv[++i];
+                if (value === undefined || value.startsWith("-")) {
+                    throw new Error("--bind-to requires a value: <alias>=<kdc_id>.");
+                }
+                flags.bindTo.push(value);
+                break;
+            }
+            case "--keep-content":
+                flags.keepContent = true;
+                break;
+            case "--apply-all":
+                flags.applyAll = true;
+                break;
+            case "--kind":
+                flags.kind = argv[++i];
+                break;
             case "--config": {
                 const value = argv[++i];
                 if (value === undefined || value.startsWith("-")) {

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, packageConfig, packageRetire, packageShow, parseInstallConfigFlags, packageEject, packageDoctor, packageUpgrade, parseResolveFlags, packageNew, packageBuild, packagePublish, packageDev, packageSync, packageReset, packageExtract, packageAdopt, packageFleetUpgrade, packageYank, } from "./package_commands.js";
+import { packageInstall, packageUninstall, packageListContent, packageConfig, packageRetire, packageShow, parseInstallConfigFlags, packageEject, packageDoctor, packageUpgrade, packageUpgradeKnowledge, parseBindToFlags, packageNew, packageBuild, packagePublish, packageDev, packageSync, packageReset, packageExtract, packageAdopt, packageFleetUpgrade, packageYank, } from "./package_commands.js";
 import { parseArgs } from "./args.js";
 import { ingestJsonArgs } from "./inputs.js";
 import { runXlsxCommand } from "./xlsx.js";
@@ -96,31 +96,41 @@ COMMANDS
   lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address
   lotics app rename "<new name>"       Rename the app's display name (launcher title)
   lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
-  lotics package new <name> [path]     Scaffold a package project (contract + app source)
+  lotics package new <name> [path] [--kind app|content]
+                                       Scaffold a package project — an app (contract + source)
+                                       or a content corpus (docs-only, no app source)
   lotics package build [path]          Build the publishable bundle (source + dist)
   lotics package publish [path]        Publish a new immutable package version
   lotics package dev [path]            Sync the package into a dev workspace + run the app
                                        dev server (--workspace <dev_ws> selects it)
   lotics package sync [path]           Re-sync (additive migrate + materialize) into a dev ws
   lotics package reset [path]          DEV-ONLY: drop scaffolded tables + re-scaffold clean
-  lotics package install <package> [--version N] [--config key=value ...]
-                                       Install an app package into this workspace
-                                       (scaffolds the data model + deploys + materializes)
-  lotics package uninstall <app_id> [--archive-tables]
-                                       Remove an installation (archives artifacts; with the
-                                       flag also archives the scaffolded tables it created)
+  lotics package install <package> [--version N] [--bind-to <alias>=<kdc_id> ...] [--config key=value ...]
+                                       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 package uninstall <app_id|pci_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 package config <app_id> [--set key=value ...]
                                        Show or edit an installation's config knobs
   lotics package show <package_id>     Registry metadata + version history
   lotics package retire <package_id> [--undo]
                                        Retire a package (refuse new installs, hide from other
                                        orgs); existing installations keep working + upgrade
-  lotics package upgrade <app_id> [--version N] [--resolve <key>=recreate|revert|keep|<id> ...]
-                                       Preview-then-apply a package upgrade; refuses while
-                                       any drift/modified finding lacks a --resolve, and
-                                       hard-stops on breaking contract changes
+  lotics package list-content          List the workspace's content installations
+                                       (standalone pci_ + app-bundled) — source for a pci_ id
+  lotics package upgrade <app_id|pci_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]
+                                       Preview-then-apply an upgrade. App: refuses while any
+                                       drift/modified/bundled-knowledge finding lacks a --resolve
+                                       (a knowledge-alias --resolve routes to the doc). Content
+                                       (pci_): --resolve <alias>=apply|keep|archive|recreate|unbind;
+                                       --apply-all accepts the package's version for every doc
   lotics package doctor [app_id]       Installation health: version pin vs latest, binding
-                                       drift, locally modified core (exit 1 on findings)
+                                       drift, locally modified core, knowledge drift/edits
+                                       (exit 1 on findings)
   lotics package rebind-role <app_id> <alias> <grp_id>
                                        Re-point a package role at a different group
                                        (re-materializes at the pinned version)
@@ -167,6 +177,12 @@ FLAGS
   --local            Pin the current directory (lotics org use / auth api-key)
   --dev              (lotics workspace create) Mark a throwaway app-package dev
                      workspace — required for "lotics package reset"
+  --kind <k>         (lotics package new) Package kind: app (default) or content
+  --bind-to <a>=<id> (lotics package install/upgrade, repeatable) Adopt an existing
+                     same-named doc as package-managed (resolves a knowledge collision)
+  --keep-content     (lotics package uninstall) Keep the docs instead of archiving them
+  --apply-all        (lotics package upgrade, knowledge) Accept the package's version
+                     for every doc (overwrites local edits)
   --all              (lotics auth logout) Remove every saved credential
   --version          Show version
 
@@ -585,10 +601,18 @@ async function main() {
     if (command === "package" && subcommand === "new") {
         const name = toolArgs;
         if (!name) {
-            console.error("Usage: lotics package new <name> [path]");
+            console.error("Usage: lotics package new <name> [path] [--kind app|content]");
             process.exit(1);
         }
-        await packageNew({ name, targetPath: restArgs[0] });
+        if (flags.kind !== undefined && flags.kind !== "app" && flags.kind !== "content") {
+            console.error(`Invalid --kind "${flags.kind}" — expected "app" or "content".`);
+            process.exit(1);
+        }
+        await packageNew({
+            name,
+            targetPath: restArgs[0],
+            kind: flags.kind === "content" ? "content" : "app",
+        });
         return;
     }
     if (command === "package" && subcommand === "build") {
@@ -703,19 +727,20 @@ async function main() {
     }
     if (command === "package" && !subcommand) {
         console.error("Usage:");
-        console.error("  lotics package new <name> [path]                 Scaffold a package project (contract + app source)");
+        console.error("  lotics package new <name> [path] [--kind app|content]   Scaffold a package project (app source, or docs-only)");
         console.error("  lotics package build [path]                      Build the publishable bundle (source + dist)");
         console.error("  lotics package publish [path] [-m <changelog>]   Publish a new immutable package version");
         console.error("  lotics package dev [path] [--workspace <ws>]     Sync into a dev workspace + run the app dev server");
         console.error("  lotics package sync [path] [--workspace <ws>]    Re-sync (additive migrate + materialize) into a dev workspace");
         console.error("  lotics package reset [path] [--workspace <ws>]   DEV-ONLY: drop scaffolded tables + re-scaffold clean");
-        console.error("  lotics package install <package> [--version N] [--config key=value ...]   Install a package into this workspace");
-        console.error("  lotics package uninstall <app_id> [--archive-tables]   Remove an installation (opt-in table archival)");
+        console.error("  lotics package install <package> [--version N] [--bind-to <alias>=<kdc_id>] [--config key=value ...]   Install a package (app or content)");
+        console.error("  lotics package uninstall <app_id|pci_id> [--archive-tables] [--keep-content]   Uninstall — dispatched by id (app vs content)");
         console.error("  lotics package config <app_id> [--set key=value ...]   Show or edit an installation's config knobs");
         console.error("  lotics package show <package_id>                 Registry metadata + version history (channel, yank, changelog)");
         console.error("  lotics package retire <package_id> [--undo]      Retire a package (refuse new installs; installs keep working)");
-        console.error("  lotics package upgrade <app_id> [--version N] [--resolve ns.alias=recreate|<id>]   Preview + apply an upgrade");
-        console.error("  lotics package doctor [app_id]                   Health: version pin vs latest + binding drift");
+        console.error("  lotics package list-content                      List the workspace's content installations (standalone + app-bundled)");
+        console.error("  lotics package upgrade <app_id|pci_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]   Preview + apply an upgrade");
+        console.error("  lotics package doctor [app_id]                   Health: version pin vs latest + binding/knowledge drift");
         console.error("  lotics package rebind-role <app_id> <alias> <grp_id>   Re-point a package role at another group");
         console.error("  lotics package eject <app_id>                    Sever an installation's package link");
         console.error("  lotics package extract <app_id> [path]           Promote a bespoke app to a draft package project");
@@ -873,7 +898,7 @@ async function main() {
         if (subcommand === "install") {
             const packageId = toolArgs;
             if (!packageId) {
-                console.error("Usage: lotics package install <package> [--version N]");
+                console.error("Usage: lotics package install <package> [--version N] [--bind-to <alias>=<kdc_id> ...]");
                 process.exit(1);
             }
             let version;
@@ -888,17 +913,29 @@ async function main() {
             await packageInstall(client, {
                 package_id: packageId,
                 version,
+                bind_to: parseBindToFlags(flags.bindTo),
                 ...(config !== undefined ? { config } : {}),
             });
             return;
         }
         if (subcommand === "uninstall") {
-            const appId = toolArgs;
-            if (!appId) {
-                console.error("Usage: lotics package uninstall <app_id> [--archive-tables]");
+            const id = toolArgs;
+            if (!id) {
+                console.error("Usage: lotics package uninstall <app_id|pci_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 install / " +
+                    "lotics package list-content; --keep-content to retain its docs).");
                 process.exit(1);
             }
-            await packageUninstall(client, { app_id: appId, archive_tables: flags.archiveTables });
+            await packageUninstall(client, {
+                id,
+                keep_content: flags.keepContent,
+                archive_tables: flags.archiveTables,
+            });
+            return;
+        }
+        if (subcommand === "list-content") {
+            await packageListContent(client);
             return;
         }
         if (subcommand === "config") {
@@ -1003,7 +1040,7 @@ async function main() {
                 console.error("Usage: lotics package rebind-role <app_id> <role_alias> <grp_id>");
                 process.exit(1);
             }
-            const result = await client.rebindAppPackageRole(appId, {
+            const result = await client.rebindPackageRole(appId, {
                 role_alias: roleAlias,
                 group_id: groupId,
             });
@@ -1013,9 +1050,9 @@ async function main() {
             return;
         }
         if (subcommand === "upgrade") {
-            const appId = toolArgs;
-            if (!appId) {
-                console.error("Usage: lotics package upgrade <app_id> [--version N] [--resolve <namespace.alias>=recreate|<id> ...]");
+            const target = toolArgs;
+            if (!target) {
+                console.error("Usage: lotics package upgrade <app_id | pci_installation_id> [--version N] [--resolve <key>=... ...]");
                 process.exit(1);
             }
             let version;
@@ -1026,10 +1063,24 @@ async function main() {
                     process.exit(1);
                 }
             }
+            // A `pci_` id is a standalone content installation (its own upgrade
+            // pipeline); everything else is an app installation.
+            if (target.startsWith("pci_")) {
+                await packageUpgradeKnowledge(client, {
+                    installation_id: target,
+                    version,
+                    resolve: flags.resolve,
+                    bind_to: parseBindToFlags(flags.bindTo),
+                    applyAll: flags.applyAll,
+                });
+                return;
+            }
             await packageUpgrade(client, {
-                app_id: appId,
+                app_id: target,
                 version,
-                resolutions: parseResolveFlags(flags.resolve),
+                resolve: flags.resolve,
+                bindTo: flags.bindTo,
+                applyAll: flags.applyAll,
             });
             return;
         }