@lotics/cli 0.76.1 → 0.86.0

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, packageRetire, packageShow, parseInstallConfigFlags, packageEject, packageDoctor, packageUpgrade, packageUpgradeKnowledge, parseBindToFlags, packageNew, packageBuild, packagePublish, packageDev, packageSync, packageReset, packageExtract, packageAdopt, 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";
@@ -71,10 +71,22 @@ COMMANDS
   cat args.json | lotics run <tool>    Read JSON args from stdin (large payloads)
   lotics app create <name> [path]      Create a new custom-code app + scaffold locally
   lotics app pull <app_id> [path]      Bootstrap full local env (source + npm install + types)
-  lotics app deploy -m <message>       Build + upload current dir as a new version
-                                       (-m is required — it's the version's audit trail)
-                                       (code + queries only — workflow bindings are
+  lotics app deploy -m <message>       Build + upload current dir as a new version — COMMIT
+                                       (-m is required — it's the version's audit trail;
+                                       carries code + queries only — workflow bindings are
                                        managed by set_app_workflow / remove_app_workflow)
+  lotics app publish [app_id|.] [--rename old=new ...] [-m <changelog>] [--yes]
+                                       Make the app DISTRIBUTABLE — first-release it (v1) as a
+                                       package; later versions ship via "lotics app release".
+                                       Previews the auto-minted aliases + findings; --yes applies
+                                       (extract → create → publish v1 → pin origin). --rename fixes
+                                       an alias before v1 freezes; -m is an optional v1 changelog
+  lotics app release [app_id|.] -m <changelog> [--yes]
+                                       RELEASE the next package version from the origin app you
+                                       are happy with (preview; --yes publishes + re-pins)
+  lotics app unpublish <app_id|package_id> [--undo]
+                                       Take the published package off the shelf (installations
+                                       keep working); --undo restores it
   lotics app versions [app_id]         Show deploy history newest-first (version,
                                        timestamp, deployer, build status, -m message;
                                        * marks the currently served version)
@@ -96,57 +108,42 @@ 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] [--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] [--bind-to <alias>=<kdc_id> ...] [--config key=value ...]
+  # PACKAGES — consumer verbs are top-level; low-traffic ops live on "lotics package"
+  #            (author verbs live on "lotics app")
+  lotics install <package_id> [--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]
+  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 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 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
+                                       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. 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)
-  lotics package rebind-role <app_id> <alias> <grp_id>
-                                       Re-point a package role at a different group
-                                       (re-materializes at the pinned version)
+  lotics package config <app_id> [--set key=value ...]
+                                       Show or edit an installation's config knobs
   lotics package eject <app_id>        Sever an installation's package link
                                        (re-deploys the pinned source as a bespoke app)
-  lotics package extract <app_id> [path]   Promote a bespoke app to a draft package
-                                       project (contract + binding + templates); always
-                                       writes the draft, exits 1 on error findings
-  lotics package adopt <app_id> [path]     Bind the published package project onto the
-                                       origin app (reads .lotics/adopt_binding.json;
-                                       --version N pins a specific version)
-  lotics package fleet-upgrade <package_id> [--version N]
+  lotics package show <package_id>     Registry metadata + version history
+  lotics package list-content          List the workspace's content installations
+                                       (standalone content installs) — each row leads with
+                                       the package id for upgrade/uninstall
   lotics package yank <package_id> <version> [--undo]
-                                       Upgrade EVERY installation of the package across
-                                       your org: applies where the preview is clean,
-                                       skips + reports findings (exit 1 unless all current)
+                                       Refuse new installs/upgrades of a broken published
+                                       version (pinned installations keep running)
+  lotics run publish_content '{"name":"…","knowledge_doc_ids":[…],"template_ids":[…]}'
+                                       Publish a SET of live docs + templates as a content
+                                       package (v1 + origin pin); release_content cuts the next
   lotics ui link <component> [--ui-src <path>] [--remove]
                                        Dev-link @lotics/ui to packages/ui/src (Vite alias
                                        + tsc paths) for live HMR + typecheck. Monorepo apps
@@ -175,13 +172,12 @@ FLAGS
                      is_current_member / row-scoping resolve to them (also
                      LOTICS_VIEW_AS env; admin key only; writes stay yours)
   --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
+  --rename <old>=<new> (lotics app publish, repeatable) Fix an auto-minted alias before
+                     the package's v1 contract freezes it
+  --bind-to <a>=<id> (lotics 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
+  --keep-content     (lotics uninstall) Keep the docs instead of archiving them
+  --apply-all        (lotics upgrade, knowledge) Accept the package's version
                      for every doc (overwrites local edits)
   --all              (lotics auth logout) Remove every saved credential
   --version          Show version
@@ -597,28 +593,6 @@ async function main() {
         console.error("Usage: lotics ui link <component> [--ui-src <abs path>] [--remove]");
         process.exit(1);
     }
-    // --- lotics package new / build — local scaffold + build, no auth required ---
-    if (command === "package" && subcommand === "new") {
-        const name = toolArgs;
-        if (!name) {
-            console.error("Usage: lotics package new <name> [path] [--kind app|content]");
-            process.exit(1);
-        }
-        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") {
-        await packageBuild({ projectDir: toolArgs });
-        return;
-    }
     // --- lotics app workflow check [alias] — local typecheck, no auth, no network ---
     // Reads src/workflows/*.ts + .lotics/workflows/*.globals.d.ts and the app's own
     // typescript; builds one isolated program per alias. Handled before the auth
@@ -701,7 +675,16 @@ async function main() {
         return;
     }
     // --- Validate command before auth ---
-    if (command !== "tools" && command !== "upload" && command !== "run" && command !== "download" && command !== "workspace" && command !== "app" && command !== "package") {
+    if (command !== "tools" &&
+        command !== "upload" &&
+        command !== "run" &&
+        command !== "download" &&
+        command !== "workspace" &&
+        command !== "app" &&
+        command !== "package" &&
+        command !== "install" &&
+        command !== "uninstall" &&
+        command !== "upgrade") {
         console.error(`Unknown command: ${command}`);
         console.error('Run "lotics --help" for usage.');
         process.exit(1);
@@ -723,30 +706,27 @@ async function main() {
         console.error("  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address");
         console.error("  lotics app rename \"<new name>\"        Rename the app's display name (launcher title)");
         console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
+        console.error("  lotics app publish [app_id|.] [--rename old=new ...] [-m <changelog>] [--yes]   First-release the app as a package (v1; preview, --yes applies)");
+        console.error("  lotics app release [app_id|.] -m <changelog> [--yes]   Release the next package version from the origin");
+        console.error("  lotics app unpublish <app_id|package_id> [--undo]      Take a published package off the shelf (any kind — app or content)");
         process.exit(1);
     }
     if (command === "package" && !subcommand) {
-        console.error("Usage:");
-        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] [--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 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("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|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 rebind-role <app_id> <alias> <grp_id>   Re-point a package role at another group");
+        console.error("  lotics package config <app_id> [--set key=value ...]   Show or edit an installation's config knobs");
         console.error("  lotics package eject <app_id>                    Sever an installation's package link");
-        console.error("  lotics package extract <app_id> [path]           Promote a bespoke app to a draft package project");
-        console.error("  lotics package adopt <app_id> [path]             Bind the published project onto the origin app");
-        console.error("  lotics package fleet-upgrade <package_id> [--version N]   Upgrade every org installation (clean ones apply; findings skip)");
+        console.error("  lotics package show <package_id>                 Registry metadata + version history (channel, yank, changelog)");
+        console.error("  lotics package list-content                      List the workspace's content installations (standalone content installs)");
         console.error("  lotics package yank <package_id> <version> [--undo]       Refuse new installs/upgrades of a broken published version (pinned installations keep running)");
+        console.error("  A content package (a SET of live docs + templates) — publish + release with the tools, retire on `lotics app`:");
+        console.error("    lotics run publish_content '{\"name\":\"…\",\"knowledge_doc_ids\":[…],\"template_ids\":[…]}'   Publish v1 (a fixed set)");
+        console.error("    lotics run release_content '{\"package_id\":\"apg_…\",\"changelog\":\"…\"}'   Cut the next version (add \"dry_run\":true to preview)");
+        console.error("    lotics app unpublish <package_id>   Take the whole package off the shelf (kind-agnostic — retires content too)");
         process.exit(1);
     }
     if (command === "run" && !subcommand) {
@@ -820,11 +800,11 @@ async function main() {
         if (subcommand === "create") {
             const name = toolArgs;
             if (!name) {
-                console.error('Usage: lotics workspace create <name> [--timezone <tz>] [--dev]');
+                console.error('Usage: lotics workspace create <name> [--timezone <tz>]');
                 process.exit(1);
             }
             const timezone = flags.timezone;
-            const created = await client.createWorkspace({ name, timezone, is_dev: flags.dev || undefined });
+            const created = await client.createWorkspace({ name, timezone });
             setSelectedWorkspace(created.id);
             client.setWorkspaceId(created.id);
             if (flags.json) {
@@ -893,47 +873,103 @@ async function main() {
     }
     // Ensure workspace is resolved for all remaining commands
     await resolveWorkspace(client, ctx);
-    // lotics package install <package> [--version N]
-    if (command === "package") {
-        if (subcommand === "install") {
-            const packageId = toolArgs;
-            if (!packageId) {
-                console.error("Usage: lotics package install <package> [--version N] [--bind-to <alias>=<kdc_id> ...]");
+    // --- lotics install / uninstall / upgrade — top-level CONSUMER verbs ---
+    // The high-traffic operator surface reads noun-less: `lotics install <pkg>`,
+    // `lotics uninstall <id>`, `lotics upgrade <id>`. Low-traffic ops keep their
+    // `lotics package <verb>` home. The package id is the SECOND positional at top
+    // level, which the parser puts in `subcommand` (not `toolArgs`).
+    if (command === "install") {
+        const packageId = subcommand;
+        if (!packageId) {
+            console.error("Usage: lotics install <package_id> [--version N] [--bind-to <alias>=<kdc_id> ...] [--config key=value ...]");
+            process.exit(1);
+        }
+        let version;
+        if (flags.packageVersion !== undefined) {
+            version = Number(flags.packageVersion);
+            if (!Number.isInteger(version) || version <= 0) {
+                console.error(`Invalid --version "${flags.packageVersion}" — expected a positive integer.`);
                 process.exit(1);
             }
-            let version;
-            if (flags.packageVersion !== undefined) {
-                version = Number(flags.packageVersion);
-                if (!Number.isInteger(version) || version <= 0) {
-                    console.error(`Invalid --version "${flags.packageVersion}" — expected a positive integer.`);
-                    process.exit(1);
-                }
-            }
-            const config = flags.config.length > 0 ? parseInstallConfigFlags(flags.config) : undefined;
-            await packageInstall(client, {
-                package_id: packageId,
-                version,
-                bind_to: parseBindToFlags(flags.bindTo),
-                ...(config !== undefined ? { config } : {}),
-            });
+        }
+        const config = flags.config.length > 0 ? parseInstallConfigFlags(flags.config) : undefined;
+        await packageInstall(client, {
+            package_id: packageId,
+            version,
+            bind_to: parseBindToFlags(flags.bindTo),
+            ...(config !== undefined ? { config } : {}),
+        });
+        return;
+    }
+    if (command === "uninstall") {
+        const id = subcommand;
+        if (!id) {
+            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 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;
         }
-        if (subcommand === "uninstall") {
-            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).");
+        await packageUninstall(client, {
+            id,
+            keep_content: flags.keepContent,
+            archive_tables: flags.archiveTables,
+        });
+        return;
+    }
+    if (command === "upgrade") {
+        const target = subcommand;
+        if (!target) {
+            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;
+        if (flags.packageVersion !== undefined) {
+            version = Number(flags.packageVersion);
+            if (!Number.isInteger(version) || version <= 0) {
+                console.error(`Invalid --version "${flags.packageVersion}" — expected a positive integer.`);
                 process.exit(1);
             }
-            await packageUninstall(client, {
-                id,
-                keep_content: flags.keepContent,
-                archive_tables: flags.archiveTables,
+        }
+        // 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;
+        }
+        // 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,
+                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,
+            resolve: flags.resolve,
+            bindTo: flags.bindTo,
+            applyAll: flags.applyAll,
+        });
+        return;
+    }
+    // lotics package <verb> — the low-traffic consumer / registry surface. The
+    // high-traffic install / uninstall / upgrade / fleet-upgrade verbs moved to
+    // the top level above; they are refused here (below) so the old forms fail
+    // loudly instead of silently doing nothing.
+    if (command === "package") {
         if (subcommand === "list-content") {
             await packageListContent(client);
             return;
@@ -947,15 +983,6 @@ async function main() {
             await packageConfig(client, { app_id: appId, sets: flags.set });
             return;
         }
-        if (subcommand === "retire") {
-            const packageId = toolArgs;
-            if (!packageId) {
-                console.error("Usage: lotics package retire <package_id> [--undo]");
-                process.exit(1);
-            }
-            await packageRetire(client, { package_id: packageId, undo: flags.undo });
-            return;
-        }
         if (subcommand === "show") {
             const packageId = toolArgs;
             if (!packageId) {
@@ -974,34 +1001,6 @@ async function main() {
             await packageEject(client, { app_id: appId });
             return;
         }
-        if (subcommand === "extract") {
-            const appId = toolArgs;
-            if (!appId) {
-                console.error("Usage: lotics package extract <app_id> [path]");
-                console.error("Promotes a bespoke app to a draft package project (contract + binding + templates).");
-                process.exit(1);
-            }
-            await packageExtract(client, { app_id: appId, targetPath: restArgs[0] });
-            return;
-        }
-        if (subcommand === "adopt") {
-            const appId = toolArgs;
-            if (!appId) {
-                console.error("Usage: lotics package adopt <app_id> [path]");
-                console.error("Binds the published package project (this dir, or [path]) onto the origin app.");
-                process.exit(1);
-            }
-            let version;
-            if (flags.packageVersion !== undefined) {
-                version = Number(flags.packageVersion);
-                if (!Number.isInteger(version) || version <= 0) {
-                    console.error(`Invalid --version "${flags.packageVersion}" — expected a positive integer.`);
-                    process.exit(1);
-                }
-            }
-            await packageAdopt(client, { app_id: appId, version, projectDir: restArgs[0] });
-            return;
-        }
         if (subcommand === "yank") {
             const packageId = toolArgs;
             const version = Number(restArgs[0]);
@@ -1012,106 +1011,30 @@ async function main() {
             await packageYank(client, { package_id: packageId, version, undo: flags.undo });
             return;
         }
-        if (subcommand === "fleet-upgrade") {
-            const packageId = toolArgs;
-            if (!packageId) {
-                console.error("Usage: lotics package fleet-upgrade <package_id> [--version N]");
-                process.exit(1);
-            }
-            let version;
-            if (flags.packageVersion !== undefined) {
-                version = Number(flags.packageVersion);
-                if (!Number.isInteger(version) || version <= 0) {
-                    console.error(`Invalid --version "${flags.packageVersion}" — expected a positive integer.`);
-                    process.exit(1);
-                }
-            }
-            await packageFleetUpgrade(client, { package_id: packageId, version });
-            return;
-        }
         if (subcommand === "doctor") {
             await packageDoctor(client, { app_id: toolArgs });
             return;
         }
+        // Re-pointing a live role rides the upgrade's ONE resolutions grammar —
+        // redirect the removed verb loudly, never a silent unknown-command fall-through.
         if (subcommand === "rebind-role") {
             const appId = toolArgs;
             const [roleAlias, groupId] = restArgs;
-            if (!appId || !roleAlias || !groupId) {
-                console.error("Usage: lotics package rebind-role <app_id> <role_alias> <grp_id>");
-                process.exit(1);
-            }
-            const result = await client.rebindPackageRole(appId, {
-                role_alias: roleAlias,
-                group_id: groupId,
-            });
-            console.error(`Rebound role "${result.role_alias}" → ${result.group_id}` +
-                (result.previous_group_id ? ` (was ${result.previous_group_id})` : "") +
-                ". Package workflows/agents were re-materialized against the new group.");
-            return;
-        }
-        if (subcommand === "upgrade") {
-            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;
-            if (flags.packageVersion !== undefined) {
-                version = Number(flags.packageVersion);
-                if (!Number.isInteger(version) || version <= 0) {
-                    console.error(`Invalid --version "${flags.packageVersion}" — expected a positive integer.`);
-                    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: target,
-                version,
-                resolve: flags.resolve,
-                bindTo: flags.bindTo,
-                applyAll: flags.applyAll,
-            });
-            return;
-        }
-        if (subcommand === "publish") {
-            await packagePublish(client, { projectDir: toolArgs, changelog: flags.message });
-            return;
-        }
-        if (subcommand === "sync") {
-            await packageSync(client, { projectDir: toolArgs });
-            return;
-        }
-        if (subcommand === "reset") {
-            await packageReset(client, { projectDir: toolArgs });
-            return;
+            console.error("`lotics package rebind-role` was folded into the upgrade grammar. Re-point a live role with:\n" +
+                `  lotics upgrade ${appId ?? "<app_id>"} --resolve roles.${roleAlias ?? "<alias>"}=${groupId ?? "<grp_id>"}`);
+            process.exit(1);
         }
-        if (subcommand === "dev") {
-            // First positional is an optional project path; --port / --vite-port
-            // override the wrapper / Vite ports (same shape as `lotics app dev`).
-            const projectDir = toolArgs;
-            let port;
-            let vitePort;
-            for (const a of restArgs) {
-                const portMatch = /^--port=(\d+)$/.exec(a);
-                const vitePortMatch = /^--vite-port=(\d+)$/.exec(a);
-                if (portMatch)
-                    port = Number(portMatch[1]);
-                else if (vitePortMatch)
-                    vitePort = Number(vitePortMatch[1]);
-            }
-            await packageDev(client, { projectDir, port, vitePort });
-            return;
+        // The high-traffic consumer verbs moved to the top level. Refuse the old
+        // `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|package_id>",
+            upgrade: "lotics upgrade <app_id|package_id>",
+            "fleet-upgrade": "lotics upgrade <package_id>",
+        };
+        if (subcommand !== undefined && subcommand in movedVerbs) {
+            console.error(`\`lotics package ${subcommand}\` moved to the top level — run \`${movedVerbs[subcommand]}\` instead.`);
+            process.exit(1);
         }
         console.error(`Unknown package subcommand: ${subcommand}`);
         console.error("Run 'lotics package' for usage.");
@@ -1152,6 +1075,40 @@ async function main() {
             await appDeploy(client, { message });
             return;
         }
+        if (subcommand === "publish") {
+            // First-release a bespoke app AS a package. Positional app id (`.`/omitted →
+            // the local app project manifest). Previews the minted aliases + findings,
+            // then applies only with `--yes` (mirrors `app release`). `--rename old=new`
+            // fixes an auto-minted alias before v1 freezes it; `-m` is an optional v1 changelog.
+            await appPublish(client, {
+                app_id: toolArgs,
+                renames: flags.rename,
+                changelog: flags.message,
+                yes: flags.yes,
+            });
+            return;
+        }
+        if (subcommand === "release") {
+            // -m <changelog> is REQUIRED — each release is a version row read back by
+            // `lotics package show`, so a blank changelog loses the audit trail.
+            if (!flags.message) {
+                console.error("Usage: lotics app release [app_id|.] -m <changelog> [--yes]");
+                console.error("Snapshots the origin app into its next package version (preview, then --yes to publish).");
+                process.exit(1);
+            }
+            await appRelease(client, { app_id: toolArgs, changelog: flags.message, yes: flags.yes });
+            return;
+        }
+        if (subcommand === "unpublish") {
+            const id = toolArgs;
+            if (!id) {
+                console.error("Usage: lotics app unpublish <app_id|package_id> [--undo]");
+                console.error("Takes a published package off the shelf; existing installations keep working.");
+                process.exit(1);
+            }
+            await appUnpublish(client, { id, undo: flags.undo });
+            return;
+        }
         if (subcommand === "subdomain") {
             const newSubdomain = toolArgs;
             if (!newSubdomain) {
@@ -1382,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);
         }