@lotics/cli 0.76.1 → 0.86.0

package/README.md

@@ -195,78 +195,83 @@ lotics ui link card --remove               # finalize: PR + publish, then drop t
 
 `app codegen` reads `package.json#lotics.queries` to decide which tables to put in `app_fields.ts`; widen the set with `package.json#lotics.codegen.tables` (an array of `tbl_…` ids) for tables the app only writes via workflows.
 
-## App packages
+## 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/packages.md` for the model.
+A maintained, versioned package library: author once, install into many workspaces, upgrade per-workspace. A package carries an app, content (knowledge docs and/or document templates), or both. **Nothing starts as a package** — build a bespoke app first (the `lotics app` loop above), then first-release it as a package when it proves worth distributing. 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)
-lotics package new my-crm                  # scaffold project + contract.json
-lotics package publish -m "v2: adds deals" # build + publish an immutable version
-
-# Dev loop against a dev workspace (created with: lotics workspace create <name> --dev)
-lotics package dev --workspace wsp_dev     # scaffold-sync + run the app dev server
-lotics package sync --workspace wsp_dev    # migrate the dev installation only
-lotics package reset --workspace wsp_dev   # DEV-ONLY: drop scaffolded tables, re-scaffold clean
-
-# Operate installations (workspace admin)
-lotics package show apg_...                # registry metadata + version history (trust badge, channel, yank)
-lotics package install apg_... --version 2 # scaffold + materialize + deploy + pin
-lotics package install apg_... --config heading="Ops board"   # per-knob overrides over contract defaults
+# 1. Make the app distributable — first-release it as a package (one call: extract
+#    an alias-keyed contract, create the registry package, publish v1 from the
+#    deployed source + dist, pin the app as installation #1). Blocking findings
+#    (a hardcoded fld_/opt_ id in src/ or a workflow body, a button field) → 409.
+lotics app publish                          # from the pulled app project (or: app publish app_...)
+lotics app publish --rename item=deal -m "v1"   # fix an auto-minted alias before v1 freezes it
+
+# 2. Iterate IN PLACE — the origin app is the permanent working copy
+lotics app pull app_...                     # the same loop as any app: pull, edit, dev
+lotics app deploy -m "Add quote drawer"     # commit a new app version
+
+# 3. Release the next package version from the origin you are happy with
+lotics app release -m "v2: adds deals"          # preview (new/changed aliases + findings)
+lotics app release -m "v2: adds deals" --yes    # publish v2 + re-pin the origin
+
+# Take it off the shelf (existing installations keep working + upgrading)
+lotics app unpublish app_... [--undo]       # by app id (resolves the package) or package id
+
+# Operate installations (workspace admin). The high-traffic verbs are top-level
+# (install / uninstall / upgrade); low-traffic ops live on `lotics package`.
+lotics package show apg_...                # registry metadata + version history (trust badge, yank)
+lotics install apg_... --version 2         # scaffold + materialize + deploy + pin
+lotics install apg_... --config heading="Ops board"           # per-knob overrides over contract defaults
 lotics package config app_... --set show_done=false           # edit a live installation's config (partial merge)
-lotics package uninstall app_... [--archive-tables]           # remove an installation; workflows stop firing
-lotics package retire apg_... [--undo]     # owner-org: refuse NEW installs (existing keep working + upgrading)
+lotics uninstall app_... [--archive-tables]                   # remove an installation; workflows stop firing
 lotics package doctor app_...              # version pin vs latest + drift + local edits (exit 1 on findings)
-lotics package rebind-role app_... <alias> <grp_id>  # re-point a package role at another group (re-materializes)
-lotics package upgrade app_...             # preview, then apply (additive; overlay preserved)
-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 upgrade app_...                     # preview, then apply (additive; overlay preserved)
+lotics upgrade apg_...                      # APP package → FLEET: upgrade EVERY org installation (clean ones apply; findings skip, exit 1)
+lotics upgrade app_... --resolve fields.deal.stage=recreate   # resolve reported drift
+lotics upgrade app_... --resolve queries.tasks=keep           # consent for a local edit (or =revert)
+lotics upgrade app_... --resolve template.quote=revert        # a locally-edited template (clean ones auto-update; or =keep)
+lotics upgrade app_... --resolve knowledge.playbook=apply     # a bundled knowledge doc: apply|keep|archive|recreate|unbind
+lotics upgrade app_... --resolve roles.approver=grp_...       # re-point a LIVE package role at another group
+lotics package yank apg_... 3 [--undo]     # refuse new installs/upgrades of a broken version
 lotics package eject app_...               # one-way: sever the package link
 lotics workspace doctor                    # dangling schema references across the workspace (exit 1 on findings)
-
-# Promote an EXISTING bespoke app to a package (build it in a real workspace first,
-# distribute once it proves itself — no re-authoring)
-lotics package extract app_...             # → draft project: contract + binding + templates
-                                           #   prints a findings report; always writes the draft,
-                                           #   exits 1 on error findings (fix them, publish re-validates)
-cd <slug-of-app-name>                      # review contract.json aliases
-lotics package publish -m "v1"             # publish the reviewed project
-lotics package adopt app_...               # bind the package onto the origin app (same workspace);
-                                           #   verifies the binding is faithful, then pins installation #1
 ```
 
-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.
+After the first publish **the origin is the master** — develop it in its workspace (`app pull` / `app deploy` / `app workflow set` / table tools), and `lotics app release` snapshots each version. Its **binding-aware re-extract** keeps aliases stable through the origin's current binding, so re-extraction never churns the upgrade diff (which is why extract-again is the loop, not a hazard). Release is also the **bundled-knowledge declaration surface**: run from the app project, the manifest's `lotics.knowledge` (`[{alias,doc_id}]`) re-declares which docs the package bundles — an alias added ships as a new doc, a bound alias dropped surfaces to consumers as `removed` (archive|keep), a present one re-snapshots; a bare id from elsewhere reconstructs the current corpus from the pin (never drops it). So a published app package evolves its bundled docs across versions without ejecting.
 
 ### Content packages
 
 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"
+# Publish a content package from a SET of live knowledge docs + templates — the
+# publish_content tool (there is no content-package project). Aliases + shas are
+# computed from live content; v1 is created and the origin workspace is pinned.
+lotics run publish_content '{"name":"My SOPs","knowledge_doc_ids":["kdc_..."],"template_ids":["tmpl_..."]}'
+
+# Cut the next version after editing those docs/templates in place (add "dry_run":true to preview the diff)
+lotics run release_content '{"package_id":"apg_...","changelog":"v2: revised SOPs"}'
 
 # 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)
+lotics install apg_...                          # app OR content, shape-branched
+lotics install apg_... --bind-to policy=kdc_... # adopt an existing doc as package-managed
+
+# Discover installed content (each row leads with the PACKAGE id)
+lotics package list-content                           # package id · package · version (standalone content installs)
+
+# Refresh this workspace's content install — addressed by PACKAGE id (one install per
+# package per workspace, so the package id is the address; one gate over docs + templates)
+lotics upgrade apg_...                          # CONTENT package → preview, then apply (this workspace's install)
+lotics upgrade apg_... --resolve knowledge.policy=apply   # a doc: apply|keep|archive|recreate|unbind
+lotics upgrade apg_... --resolve template.quote=revert    # a locally-edited template: revert|keep (clean ones auto-update)
+lotics upgrade apg_... --apply-all              # accept upstream for every doc + template (OVERWRITES local edits)
+lotics uninstall apg_... --keep-content            # remove the pin; keep docs + templates (default archives them)
 ```
 
-A package's knowledge can also arrive **bundled with an app**. Upgrading such an app (`lotics 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.
+A package's knowledge can also arrive **bundled with an app**. Upgrading such an app (`lotics upgrade <app_id>`) previews its bundled-knowledge changes alongside the plan and resolves them in the SAME namespaced grammar — `--resolve knowledge.<alias>=apply|keep|archive|recreate|unbind` (the flags pass to the server verbatim; no routing, no ambiguity), `--bind-to` consents an added-doc collision, `--apply-all` takes the package's version for every consent-requiring doc.
 
-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.
+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 app publish` from the app project — it forwards the declaration, and the docs ship with the package.
 
 ## SDK
 

package/dist/app_commands.d.ts

@@ -137,10 +137,15 @@ export declare function writeAppDts(projectDir: string, manifest: {
  * `lotics app codegen [path]` — regenerate every `.lotics/` artifact from the
  * manifest + workspace schema, WITHOUT a deploy. The `.d.ts` companions are
  * always written (synchronous, no network). When a `client` is available, the
- * runtime `app_fields.ts` is also regenerated from the live schema of the tables
- * the app's queries reference (+ the allowlist); a network failure is non-fatal
- * (warn, keep the last-generated file) — so codegen still does useful work
- * offline, mirroring `app create`'s tolerance of an offline npm registry.
+ * runtime `app_fields.ts` is also regenerated — **branched on whether the app is
+ * a package installation** (`getApp().package_id` set): a **linked/published**
+ * app emits the BINDING-resolved form (`F`/`OPT`/`ROLE` resolved from the live
+ * binding at module load via `getAppBinding()`, so the source stays portable
+ * across every install), a **bespoke** app emits the baked form (this
+ * workspace's concrete `fld_…`/`opt_…` ids, from the live schema of the tables
+ * its queries reference + the allowlist). A network failure is non-fatal (warn,
+ * keep the last-generated file) — so codegen still does useful work offline,
+ * mirroring `app create`'s tolerance of an offline npm registry.
  */
 export declare function appCodegen(args: {
     projectDir?: string;

package/dist/app_commands.js

@@ -23,6 +23,7 @@ import { generateAppAgentsDts } from "./generate_app_agents_dts.js";
 import { generateAppQueriesDts } from "./generate_app_queries_dts.js";
 import { collectQueryTableIds } from "@lotics/shared/app_query_ast";
 import { generateAppFields } from "./generate_app_fields.js";
+import { generatePackageAppFields } from "./generate_package_fields.js";
 import { loadProjectTypescript, checkWorkflowBodies, } from "./app_workflow_check.js";
 /**
  * Resolve the latest published version of a package from the npm registry.
@@ -442,14 +443,33 @@ function writeAppFields(projectDir, tables) {
     fs.writeFileSync(file, generateAppFields(tables));
     return file;
 }
+/**
+ * Write the BINDING-resolved `.lotics/app_fields.ts` for a package installation
+ * — the portable twin of `writeAppFields`. Instead of baking this workspace's
+ * concrete ids, the module resolves `F`/`OPT`/`ROLE` from the installation's
+ * live binding at load (`getAppBinding()`), so a published origin's source runs
+ * unchanged in every workspace that installs the package. Returns the path.
+ */
+function writeBindingAppFields(projectDir, binding) {
+    const dotLotics = path.join(projectDir, ".lotics");
+    fs.mkdirSync(dotLotics, { recursive: true });
+    const file = path.join(dotLotics, "app_fields.ts");
+    fs.writeFileSync(file, generatePackageAppFields(binding));
+    return file;
+}
 /**
  * `lotics app codegen [path]` — regenerate every `.lotics/` artifact from the
  * manifest + workspace schema, WITHOUT a deploy. The `.d.ts` companions are
  * always written (synchronous, no network). When a `client` is available, the
- * runtime `app_fields.ts` is also regenerated from the live schema of the tables
- * the app's queries reference (+ the allowlist); a network failure is non-fatal
- * (warn, keep the last-generated file) — so codegen still does useful work
- * offline, mirroring `app create`'s tolerance of an offline npm registry.
+ * runtime `app_fields.ts` is also regenerated — **branched on whether the app is
+ * a package installation** (`getApp().package_id` set): a **linked/published**
+ * app emits the BINDING-resolved form (`F`/`OPT`/`ROLE` resolved from the live
+ * binding at module load via `getAppBinding()`, so the source stays portable
+ * across every install), a **bespoke** app emits the baked form (this
+ * workspace's concrete `fld_…`/`opt_…` ids, from the live schema of the tables
+ * its queries reference + the allowlist). A network failure is non-fatal (warn,
+ * keep the last-generated file) — so codegen still does useful work offline,
+ * mirroring `app create`'s tolerance of an offline npm registry.
  */
 export async function appCodegen(args) {
     const projectDir = path.resolve(args.projectDir ?? process.cwd());
@@ -467,18 +487,32 @@ export async function appCodegen(args) {
             "Run authenticated (or set LOTICS_API_KEY) to regenerate field/option ids.");
         return;
     }
-    const tableIds = resolveCodegenTableIds(projectDir, meta.queries ?? {});
     try {
-        const tables = await args.client.getWorkspaceSchema(tableIds);
-        const fieldsPath = writeAppFields(projectDir, tables);
-        console.error(`Regenerated ${fieldsPath} (${tables.length} table${tables.length === 1 ? "" : "s"})`);
+        // Branch on linked-ness: a package installation (its own published origin OR
+        // an install of another org's package) must ship PORTABLE source, so
+        // app_fields resolves F/OPT/ROLE from the live binding at module load; a
+        // bespoke app bakes this workspace's concrete ids. getApp is the authority —
+        // `package_id` is set iff the app is a package installation.
+        const app = await args.client.getApp(meta.app_id);
+        if (app.package_id) {
+            const binding = await args.client.appBinding(meta.app_id);
+            const fieldsPath = writeBindingAppFields(projectDir, binding);
+            const count = Object.keys(binding.fields).length;
+            console.error(`Regenerated ${fieldsPath} (binding form — ${count} field alias${count === 1 ? "" : "es"} resolved per-install)`);
+        }
+        else {
+            const tableIds = resolveCodegenTableIds(projectDir, meta.queries ?? {});
+            const tables = await args.client.getWorkspaceSchema(tableIds);
+            const fieldsPath = writeAppFields(projectDir, tables);
+            console.error(`Regenerated ${fieldsPath} (${tables.length} table${tables.length === 1 ? "" : "s"})`);
+        }
     }
     catch (err) {
         // Non-fatal: keep the last-generated app_fields.ts so an offline/transient
         // failure doesn't strip the app's field aliases (same tolerance as the npm
         // registry lookup on `app create`).
-        console.error(`⚠ Could not fetch the workspace schema (${err instanceof Error ? err.message : String(err)}). ` +
-            `Kept the existing .lotics/app_fields.ts.`);
+        console.error(`⚠ Could not regenerate .lotics/app_fields.ts (${err instanceof Error ? err.message : String(err)}). ` +
+            `Kept the existing file.`);
     }
     // Refresh each bound workflow's ambient globals + re-wrap its EXISTING local
     // body in the current envelope (GAP-59). Codegen never re-fetches the body

package/dist/app_commands.test.js

@@ -206,6 +206,75 @@ describe("appCodegen (.d.ts-only path)", () => {
         expect(second.equals(first)).toBe(true);
     });
 });
+/**
+ * `appCodegen` (with a client) branches the runtime `app_fields.ts` on whether
+ * the app is a package installation: a LINKED app (`getApp().package_id` set)
+ * emits the binding-resolved form (portable — resolves through `getAppBinding()`
+ * at load); a BESPOKE app bakes this workspace's concrete ids from the schema.
+ */
+describe("appCodegen app_fields branch (linked vs bespoke)", () => {
+    let workDir;
+    beforeEach(() => {
+        workDir = fs.mkdtempSync(path.join(tmpdir(), "lotics-codegen-branch-"));
+        vi.spyOn(console, "error").mockImplementation(() => undefined);
+    });
+    afterEach(() => {
+        fs.rmSync(workDir, { recursive: true, force: true });
+        vi.restoreAllMocks();
+    });
+    function writeManifest() {
+        fs.writeFileSync(path.join(workDir, "package.json"), JSON.stringify({
+            name: "sample-app",
+            lotics: {
+                app_id: "app_1",
+                workspace_id: "wks_1",
+                current_version_id: "apv_1",
+                version_number: 1,
+                queries: { all: { ast: { kind: "from_table", table_id: "tbl_1" } } },
+            },
+        }, null, 2));
+    }
+    const readFields = () => fs.readFileSync(path.join(workDir, ".lotics", "app_fields.ts"), "utf-8");
+    it("emits the BAKED form for a bespoke app (no package_id)", async () => {
+        writeManifest();
+        const client = {
+            getApp: async () => ({ package_id: null }),
+            getWorkspaceSchema: async () => [
+                { id: "tbl_1", name: "Tasks", fields: [{ id: "fld_title", name: "Title" }] },
+            ],
+        };
+        await appCodegen({ projectDir: workDir, client });
+        const src = readFields();
+        expect(src).not.toContain("getAppBinding");
+        // Concrete id baked into the value position.
+        expect(src).toContain('"fld_title"');
+        expect(src).toMatch(/TASKS: \{/);
+    });
+    it("emits the BINDING form for a linked/published app (package_id set)", async () => {
+        writeManifest();
+        const client = {
+            getApp: async () => ({ package_id: "apg_1" }),
+            appBinding: async () => ({
+                fields: { "tasks.title": "fld_title" },
+                options: {},
+                roles: { approver: "grp_x" },
+            }),
+            // Must NOT be consulted on the linked branch — a call would fail the type
+            // shape it returns, and the assertions below prove the baked path is dead.
+            getWorkspaceSchema: async () => {
+                throw new Error("getWorkspaceSchema must not run for a linked app");
+            },
+        };
+        await appCodegen({ projectDir: workDir, client });
+        const src = readFields();
+        expect(src).toContain('import { getAppBinding } from "@lotics/app-sdk";');
+        expect(src).toContain("const binding = await getAppBinding();");
+        expect(src).toContain('title: bound(binding.fields, "tasks.title", "field")');
+        expect(src).toContain('approver: bound(binding.roles, "approver", "role")');
+        // No concrete id baked into any value position.
+        expect(src).not.toMatch(/"(fld|opt|tbl|grp)_/);
+    });
+});
 /**
  * `appUiLink` edits the app's vite.config.ts resolve.alias to dev-link
  * @lotics/ui at packages/ui/src — auto-found in a monorepo checkout, or given

package/dist/args.d.ts

@@ -30,8 +30,6 @@ export declare function parseArgs(argv: string[]): {
         message?: string;
         local: boolean;
         all: boolean;
-        /** `--dev`: mark a workspace as an app-package dev workspace (`workspace create`). */
-        dev: boolean;
         /** `--yes` (alias `-y`): confirm a destructive command (e.g. `workspace delete`) non-interactively. */
         yes: boolean;
         /** `--print-created` (alias `--report-effects`): print the honest post-run side-effect harvest. */
@@ -39,7 +37,7 @@ export declare function parseArgs(argv: string[]): {
         /** `--cleanup`: also delete the harvested created records (records only). */
         cleanup: boolean;
         /**
-         * `--version <n>`: a package version number (`lotics package install … --version 2`).
+         * `--version <n>`: a package version number (`lotics install … --version 2`).
          * Distinct from the boolean `version` flag below: `--version` followed by an
          * integer captures the number; a bare `--version` (or `-v`) prints the CLI
          * version. No other command takes a numeric value after `--version`, so the
@@ -64,8 +62,11 @@ export declare function parseArgs(argv: string[]): {
         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;
+        /**
+         * `--rename <old>=<new>` (repeatable, `lotics app publish`): fix an auto-minted
+         * alias before the package's v1 contract freezes it.
+         */
+        rename: 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`. */

package/dist/args.js

@@ -25,7 +25,6 @@ export function parseArgs(argv) {
         message: undefined,
         local: false,
         all: false,
-        dev: false,
         yes: false,
         printCreated: false,
         cleanup: false,
@@ -34,7 +33,7 @@ export function parseArgs(argv) {
         bindTo: [],
         keepContent: false,
         applyAll: false,
-        kind: undefined,
+        rename: [],
         config: [],
         set: [],
         archiveTables: false,
@@ -89,9 +88,6 @@ export function parseArgs(argv) {
             case "--local":
                 flags.local = true;
                 break;
-            case "--dev":
-                flags.dev = true;
-                break;
             case "--all":
                 flags.all = true;
                 break;
@@ -128,9 +124,14 @@ export function parseArgs(argv) {
             case "--apply-all":
                 flags.applyAll = true;
                 break;
-            case "--kind":
-                flags.kind = argv[++i];
+            case "--rename": {
+                const value = argv[++i];
+                if (value === undefined || value.startsWith("-")) {
+                    throw new Error("--rename requires a value: old=new (an alias to rename before v1 freezes it).");
+                }
+                flags.rename.push(value);
                 break;
+            }
             case "--config": {
                 const value = argv[++i];
                 if (value === undefined || value.startsWith("-")) {
@@ -155,18 +156,18 @@ export function parseArgs(argv) {
                 break;
             case "--version":
             case "-v": {
-                // Inside a `package` command, `--version` carries a value (the
-                // package version to install) and the value is REQUIRED — a bare or
-                // malformed `--version` here must never fall back to the CLI-version
-                // early-exit boolean, which would print the CLI version and exit 0
-                // (a provisioning script reads that as a successful install). The
-                // value is captured raw; the consuming command validates
-                // integer-ness with a loud error. Outside `package`, this is the
-                // CLI-version boolean.
+                // For a package version-taking command (`package …`, or the top-level
+                // consumer verbs `install` / `upgrade`), `--version` carries a value
+                // (the package version) and the value is REQUIRED — a bare or malformed
+                // `--version` here must never fall back to the CLI-version early-exit
+                // boolean, which would print the CLI version and exit 0 (a provisioning
+                // script reads that as a successful install). The value is captured raw;
+                // the consuming command validates integer-ness with a loud error.
+                // Everywhere else, this is the CLI-version boolean.
                 const next = argv[i + 1];
-                if (command === "package") {
+                if (command === "package" || command === "install" || command === "upgrade") {
                     if (next === undefined || next.startsWith("-")) {
-                        throw new Error("--version requires a version number for package commands (e.g. --version 2).");
+                        throw new Error("--version requires a version number for install/upgrade/package commands (e.g. --version 2).");
                     }
                     flags.packageVersion = next;
                     i++;

package/dist/args.test.js

@@ -23,15 +23,21 @@ describe("parseArgs", () => {
         const r = parseArgs(["app", "deploy"]);
         expect(r.flags.message).toBeUndefined();
     });
-    it("captures --version <int> as packageVersion, not the boolean version flag", () => {
-        const r = parseArgs(["package", "install", "apg_123", "--version", "2"]);
-        expect(r.command).toBe("package");
-        expect(r.subcommand).toBe("install");
-        expect(r.toolArgs).toBe("apg_123");
+    it("captures --version <int> as packageVersion on the top-level install verb", () => {
+        const r = parseArgs(["install", "apg_123", "--version", "2"]);
+        expect(r.command).toBe("install");
+        expect(r.subcommand).toBe("apg_123");
         expect(r.flags.packageVersion).toBe("2");
         expect(r.flags.version).toBe(false);
         expect(r.restArgs).toEqual([]);
     });
+    it("captures --version <int> as packageVersion on the top-level upgrade verb", () => {
+        const r = parseArgs(["upgrade", "app_1", "--version", "3"]);
+        expect(r.command).toBe("upgrade");
+        expect(r.subcommand).toBe("app_1");
+        expect(r.flags.packageVersion).toBe("3");
+        expect(r.flags.version).toBe(false);
+    });
     it("treats a bare --version as the boolean CLI-version flag", () => {
         const r = parseArgs(["--version"]);
         expect(r.flags.version).toBe(true);
@@ -42,14 +48,13 @@ describe("parseArgs", () => {
         expect(r.flags.version).toBe(true);
         expect(r.flags.packageVersion).toBeUndefined();
     });
-    it("captures a non-integer --version value under package commands for loud command-level validation", () => {
-        const r = parseArgs(["package", "install", "apg_123", "--version", "2.0"]);
+    it("captures a non-integer --version value under version-taking commands for loud command-level validation", () => {
+        const r = parseArgs(["install", "apg_123", "--version", "2.0"]);
         expect(r.flags.packageVersion).toBe("2.0");
         expect(r.flags.version).toBe(false);
     });
     it("collects repeated --resolve values", () => {
         const r = parseArgs([
-            "package",
             "upgrade",
             "app_1",
             "--resolve",
@@ -60,11 +65,11 @@ describe("parseArgs", () => {
         expect(r.flags.resolve).toEqual(["fields.deal.stage=recreate", "templates.quote=dtl_abc"]);
     });
     it("errors on --resolve without a value", () => {
-        expect(() => parseArgs(["package", "upgrade", "app_1", "--resolve"])).toThrow(/--resolve requires a value/);
+        expect(() => parseArgs(["upgrade", "app_1", "--resolve"])).toThrow(/--resolve requires a value/);
     });
-    it("errors loudly on a bare --version under package commands instead of printing the CLI version", () => {
-        expect(() => parseArgs(["package", "install", "apg_123", "--version"])).toThrow(/requires a version number/);
-        expect(() => parseArgs(["package", "install", "apg_123", "--version", "--json"])).toThrow(/requires a version number/);
+    it("errors loudly on a bare --version under version-taking commands instead of printing the CLI version", () => {
+        expect(() => parseArgs(["install", "apg_123", "--version"])).toThrow(/requires a version number/);
+        expect(() => parseArgs(["install", "apg_123", "--version", "--json"])).toThrow(/requires a version number/);
     });
     it("parses --workspace as a value flag", () => {
         const r = parseArgs(["run", "query_tables", "{}", "--workspace", "wsp_123"]);
@@ -106,11 +111,14 @@ describe("parseArgs", () => {
         expect(parseArgs(["app", "workflow", "run", "wf"]).flags.cleanup).toBe(false);
         expect(parseArgs(["app", "workflow", "run", "wf"]).flags.printCreated).toBe(false);
     });
-    it("parses --dev as a boolean flag (default false)", () => {
-        expect(parseArgs(["workspace", "create", "Dev WS", "--dev"]).flags.dev).toBe(true);
-        expect(parseArgs(["workspace", "create", "Dev WS"]).flags.dev).toBe(false);
-        // The boolean flag does not consume the workspace name positional.
-        expect(parseArgs(["workspace", "create", "Dev WS", "--dev"]).toolArgs).toBe("Dev WS");
+    it("collects repeated --rename old=new flags (default empty)", () => {
+        const r = parseArgs(["app", "publish", ".", "--rename", "item=deal", "--rename", "don_hang=orders"]);
+        expect(r.flags.rename).toEqual(["item=deal", "don_hang=orders"]);
+        expect(r.toolArgs).toBe(".");
+        expect(parseArgs(["app", "publish"]).flags.rename).toEqual([]);
+    });
+    it("throws when --rename has no value", () => {
+        expect(() => parseArgs(["app", "publish", "--rename"])).toThrow(/--rename requires a value/);
     });
     it("parses --yes and -y as the same boolean confirmation flag (default false)", () => {
         expect(parseArgs(["workspace", "delete", "wsp_1", "--yes"]).flags.yes).toBe(true);