@unbrained/pm-cli 2026.8.26 → 2026.8.27

package/dist/sdk/cli-contracts/flag-contracts.js

@@ -7,7 +7,7 @@
  * flag surface stays single-sourced across the CLI, SDK, and MCP boundaries.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6664bc8f-e5da-5593-a2df-ac45f1cef09e")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="76fe6260-2386-52c5-8f94-aad48dec33f9")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
 import { PM_POSITIONAL_ACTION_CONTRACTS, } from "./grammar-contracts.js";
@@ -219,7 +219,7 @@ export const AGGREGATE_FLAG_CONTRACTS = [
 /** Public contract for comments flag contracts, shared by SDK and presentation-layer consumers. */
 export const COMMENTS_FLAG_CONTRACTS = [
     { flag: "--id", value_name: "item-id" },
-    { flag: "--add", aliases: ["--comment", "--body"] },
+    { flag: "--add", aliases: ["--comment", "--body", "--text"] },
     { flag: "--stdin" },
     { flag: "--file" },
     { flag: "--edit" },
@@ -238,7 +238,7 @@ function withCursorSemantics(contracts, presentationFlags) {
 /** Public contract for notes flag contracts, shared by SDK and presentation-layer consumers. */
 export const NOTES_FLAG_CONTRACTS = [
     { flag: "--id", value_name: "item-id" },
-    { flag: "--add", aliases: ["--note"] },
+    { flag: "--add", aliases: ["--note", "--text"] },
     { flag: "--add-json" },
     { flag: "--stdin" },
     { flag: "--file" },
@@ -256,7 +256,7 @@ export const NOTES_FLAG_CONTRACTS = [
 /** Public contract for learnings flag contracts, shared by SDK and presentation-layer consumers. */
 export const LEARNINGS_FLAG_CONTRACTS = [
     { flag: "--id", value_name: "item-id" },
-    { flag: "--add", aliases: ["--learning"] },
+    { flag: "--add", aliases: ["--learning", "--text"] },
     { flag: "--limit" },
     { flag: "--full-history" },
     { flag: "--author" },
@@ -1884,6 +1884,10 @@ export function resolveSubcommandFlagContractsForCommand(commandName) {
         rootCommand === "packages") &&
         lifecycleSubcommand !== undefined &&
         extraParts.length === 0) {
+        if ((rootCommand === "package" || rootCommand === "packages") &&
+            lifecycleSubcommand === "upgrade") {
+            return withSubcommandGlobalFlags(UPGRADE_FLAG_CONTRACTS);
+        }
         return withSubcommandGlobalFlags(resolveExtensionLifecycleFlagContracts(rootCommand, lifecycleSubcommand));
     }
     const contracts = SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND.get(normalized) ?? [];
@@ -1908,4 +1912,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=6664bc8f-e5da-5593-a2df-ac45f1cef09e
+//# debugId=76fe6260-2386-52c5-8f94-aad48dec33f9

package/dist/sdk/cli-contracts/grammar-contracts.d.ts

@@ -6,11 +6,11 @@
  * this checked-in table in both directions so adding or removing a command
  * cannot silently bypass the architecture decision.
  */
-import type { PmCommandAliasContract } from "./command-aliases.js";
+import { type PmCommandAliasContract } from "./command-aliases.js";
 /** Canonical top-level domains an agent must retain to route pm operations. */
 export declare const PM_CLI_GRAMMAR_NOUNS: readonly ["item", "list", "context", "search", "graph", "history", "workspace", "package", "ops", "plan", "contracts", "help"];
 /** Shared verbs whose meaning transfers across domain nouns. */
-export declare const PM_CLI_SHARED_VERBS: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "reopen", "repair", "restore", "run", "show", "uninstall", "verify"];
+export declare const PM_CLI_SHARED_VERBS: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "reopen", "repair", "restore", "run", "show", "uninstall", "upgrade", "verify"];
 /** Why a current command is permitted while the grammar migration proceeds. */
 export type PmCommandDestinationDisposition = "target_noun" | "consolidation" | "package_owned" | "keep_as_is";
 /** Exact destination decision for one command emitted by runtime contracts. */
@@ -78,7 +78,7 @@ export declare const PM_COMMAND_POSITIONAL_CONTRACTS: readonly PmCommandPosition
 /** Immutable grammar policy used by contracts and the CI gate. */
 export declare const PM_CLI_GRAMMAR_CONTRACT: {
     readonly nouns: readonly ["item", "list", "context", "search", "graph", "history", "workspace", "package", "ops", "plan", "contracts", "help"];
-    readonly shared_verbs: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "reopen", "repair", "restore", "run", "show", "uninstall", "verify"];
+    readonly shared_verbs: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "reopen", "repair", "restore", "run", "show", "uninstall", "upgrade", "verify"];
     readonly scope_before_verb: true;
     readonly visible_top_level_ceiling: 69;
     readonly ceiling_raise_requires_pm_item: true;

package/dist/sdk/cli-contracts/grammar-contracts.js

@@ -1,6 +1,15 @@
-/** Canonical top-level domains an agent must retain to route pm operations. */
+/**
+ * @module sdk/cli-contracts/grammar-contracts
+ *
+ * Declares and verifies the agent-facing noun–verb grammar. The destination
+ * census is intentionally exact: live command contracts are compared with
+ * this checked-in table in both directions so adding or removing a command
+ * cannot silently bypass the architecture decision.
+ */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="21495fd2-6abb-5a4f-965c-e7b9c8f87dff")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d0f4c030-0028-5acb-a438-210666118074")}catch(e){}}();
+import { resolvePmCommandAlias, } from "./command-aliases.js";
+/** Canonical top-level domains an agent must retain to route pm operations. */
 export const PM_CLI_GRAMMAR_NOUNS = [
     "item",
     "list",
@@ -49,6 +58,7 @@ export const PM_CLI_SHARED_VERBS = [
     "run",
     "show",
     "uninstall",
+    "upgrade",
     "verify",
 ];
 function positionalSlot(name, valueKind, required, options = {}) {
@@ -391,12 +401,6 @@ const EXPLICIT_POSITIONAL_SLOTS = new Map([
     ["deps", [ITEM_ID]],
     ["docs", [ITEM_ID]],
     ["event", [positionalSlot("title", "string", true)]],
-    [
-        "extension",
-        [positionalSlot("target", "string", false, { polymorphic: true })],
-    ],
-    ["extension list", []],
-    ["extension scaffold", [positionalSlot("target", "string", true)]],
     ["files", [ITEM_ID]],
     ["files discover", [ITEM_ID]],
     [
@@ -422,7 +426,6 @@ const EXPLICIT_POSITIONAL_SLOTS = new Map([
         "init",
         [positionalSlot("prefix-or-path", "string", false, { polymorphic: true })],
     ],
-    ["install", [positionalSlot("targets", "string", false, { variadic: true })]],
     ["item complete", [ITEM_ID, positionalSlot("reason", "string", false)]],
     ["item reopen", [ITEM_ID, positionalSlot("reason", "string", true)]],
     ["learnings", [ITEM_ID, OPTIONAL_TEXT]],
@@ -444,12 +447,14 @@ const EXPLICIT_POSITIONAL_SLOTS = new Map([
     ],
     ["package list", []],
     ["package scaffold", [positionalSlot("target", "string", true)]],
+    ["package upgrade", [positionalSlot("target", "string", false)]],
     [
         "packages",
         [positionalSlot("target", "string", false, { polymorphic: true })],
     ],
     ["packages list", []],
     ["packages scaffold", [positionalSlot("target", "string", true)]],
+    ["packages upgrade", [positionalSlot("target", "string", false)]],
     ["pause-task", [ITEM_ID]],
     [
         "plan",
@@ -494,7 +499,6 @@ const EXPLICIT_POSITIONAL_SLOTS = new Map([
     ],
     ["test", [ITEM_ID]],
     ["update", [ITEM_ID]],
-    ["upgrade", [positionalSlot("target", "string", false)]],
     [
         "workspace snapshot",
         [
@@ -528,7 +532,13 @@ function normalizePositionalCommandPath(command) {
 /** Resolve one declared signature without treating arbitrary object keys as commands. */
 export function resolvePmCommandPositionalContract(command) {
     const normalized = normalizePositionalCommandPath(command);
-    return PM_COMMAND_POSITIONAL_CONTRACTS.find((contract) => contract.command === normalized);
+    const direct = PM_COMMAND_POSITIONAL_CONTRACTS.find((contract) => contract.command === normalized);
+    if (direct)
+        return direct;
+    const canonical = resolvePmCommandAlias(normalized)?.canonical;
+    if (!canonical)
+        return undefined;
+    return PM_COMMAND_POSITIONAL_CONTRACTS.find((contract) => contract.command === canonical);
 }
 /** Resolve one action-specific help/contract view. */
 export function resolvePmPositionalActionContract(command) {
@@ -654,9 +664,9 @@ export const PM_COMMAND_DESTINATION_CONTRACTS = [
         "package reload",
         "package scaffold",
         "package uninstall",
+        "package upgrade",
     ]),
     ...destinationRows("package", "package", "consolidation", "pm-tnud", [
-        "extension",
         "extension activate",
         "extension adopt",
         "extension adopt-all",
@@ -667,13 +677,10 @@ export const PM_COMMAND_DESTINATION_CONTRACTS = [
         "extension explore",
         "extension init",
         "extension install",
-        "extension list",
         "extension manage",
         "extension migrate",
         "extension reload",
-        "extension scaffold",
         "extension uninstall",
-        "install",
         "packages",
         "packages activate",
         "packages adopt",
@@ -691,7 +698,7 @@ export const PM_COMMAND_DESTINATION_CONTRACTS = [
         "packages reload",
         "packages scaffold",
         "packages uninstall",
-        "upgrade",
+        "packages upgrade",
     ]),
     ...destinationRows("package", "package", "package_owned", "package:beads", [
         "beads import",
@@ -958,4 +965,4 @@ export function verifyPmCliGrammar(commands, aliases = [], destinations = PM_COM
     };
 }
 //# sourceMappingURL=grammar-contracts.js.map
-//# debugId=21495fd2-6abb-5a4f-965c-e7b9c8f87dff
+//# debugId=d0f4c030-0028-5acb-a438-210666118074

package/dist/sdk/cli-contracts/runtime-contracts.js

@@ -4,7 +4,7 @@
  * Implements the pm contracts command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="428a19d2-be42-548a-a328-aa0e476b8a71")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a4c43fa6-9f2e-515c-ab47-d21ef5d7878e")}catch(e){}}();
 import { EXIT_CODE, SETTINGS_DEFAULTS, PmCliError, activateExtensions, getActiveExtensionRegistrations, loadExtensions, pathExists, commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
 import { buildMcpToolContracts, } from "../../mcp/tool-definitions.js";
 import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, ASSURANCE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_REOPEN_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_OUTPUT_DEGRADATION_STEPS, PLAN_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_DEPRECATED_TOOL_ACTIONS, PM_TOOL_ACTIONS, PM_TOOL_PARAMETERS_SCHEMA, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, compactFlagAliasContracts, PM_COMMAND_ALIAS_CONTRACTS, PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS, resolvePmCommandOutputBudget, } from "../cli-contracts.js";
@@ -217,7 +217,7 @@ const CANONICAL_COMMAND_ALIASES = [
     },
     {
         canonical: "package",
-        aliases: ["extension", "packages", "install"],
+        aliases: ["extension", "packages"],
     },
 ];
 const COMMAND_ALIAS_TO_CANONICAL = new Map(CANONICAL_COMMAND_ALIASES.flatMap((entry) => entry.aliases.map((alias) => [alias, entry.canonical])));
@@ -313,11 +313,9 @@ const COMMAND_INTENTS = new Map([
     ["history-redact", "Redact sensitive history values."],
     ["history-repair", "Repair history integrity."],
 ]);
-// Lifecycle subcommand flag contracts for `pm extension`. Only `init` differs
-// between extension and package: `pm package init` / `pm packages init`
-// additionally accept the package-only `--declarative` flag, so the package
-// variant swaps in PACKAGE_INIT_FLAG_CONTRACTS while every other subcommand is
-// shared verbatim.
+// Lifecycle subcommand flag contracts for `pm extension`. Package lifecycle
+// swaps in the declarative init contract and adds the package-only upgrade
+// command; every shared extension/package subcommand remains byte-identical.
 const EXTENSION_LIFECYCLE_FLAG_CONTRACTS = [
     ["init", EXTENSION_INIT_FLAG_CONTRACTS],
     ["install", EXTENSION_INSTALL_FLAG_CONTRACTS],
@@ -334,9 +332,12 @@ const EXTENSION_LIFECYCLE_FLAG_CONTRACTS = [
     ["deactivate", EXTENSION_DEACTIVATE_FLAG_CONTRACTS],
     ["migrate", EXTENSION_MIGRATE_FLAG_CONTRACTS],
 ];
-const PACKAGE_LIFECYCLE_FLAG_CONTRACTS = EXTENSION_LIFECYCLE_FLAG_CONTRACTS.map(([subcommand, flags]) => subcommand === "init"
-    ? [subcommand, PACKAGE_INIT_FLAG_CONTRACTS]
-    : [subcommand, flags]);
+const PACKAGE_LIFECYCLE_FLAG_CONTRACTS = [
+    ...EXTENSION_LIFECYCLE_FLAG_CONTRACTS.map(([subcommand, flags]) => subcommand === "init"
+        ? [subcommand, PACKAGE_INIT_FLAG_CONTRACTS]
+        : [subcommand, flags]),
+    ["upgrade", UPGRADE_FLAG_CONTRACTS],
+];
 const CORE_COMMAND_FLAG_CONTRACT_ENTRIES = [
     ...EXTENSION_LIFECYCLE_FLAG_CONTRACTS.map(([subcommand, flags]) => [`extension ${subcommand}`, flags]),
     ...PACKAGE_LIFECYCLE_FLAG_CONTRACTS.flatMap(([subcommand, flags]) => [
@@ -1686,6 +1687,7 @@ const COMMAND_OPERATION_INTENTS = new Map([
     ["run", "Run"],
     ["snapshot", "Manage snapshots for"],
     ["uninstall", "Uninstall"],
+    ["upgrade", "Upgrade"],
 ]);
 const COMMAND_INTENT_SUBJECT_OVERRIDES = new Map([
     ["extension adopt-all", "extensions"],
@@ -2082,4 +2084,4 @@ export const _testOnlyContractsCommand = {
     toRuntimeShortFlagToken,
 };
 //# sourceMappingURL=runtime-contracts.js.map
-//# debugId=428a19d2-be42-548a-a328-aa0e476b8a71
+//# debugId=a4c43fa6-9f2e-515c-ab47-d21ef5d7878e

package/dist/sdk/cli-contracts/tool-schema.js

@@ -7,7 +7,7 @@
  * consumers from a single source of truth.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b54b0565-3968-59ea-b5f9-8ae52731473a")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0b302ca6-1333-532f-a55e-e8e984636456")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { TOOL_CREATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, } from "./tool-option-contracts.js";
@@ -152,7 +152,8 @@ const PM_TOOL_ACTION_NESTED_OPTION_COMPATIBILITY_KEYS = Object.freeze({
         "no_checkpoint",
         "filterAssignee_filter",
     ],
-    ...Object.fromEntries(PM_TOOL_ACTIONS.filter((action) => action === "install" ||
+    ...Object.fromEntries(PM_TOOL_ACTIONS.filter((action) => action === "upgrade" ||
+        action === "install" ||
         action === "extension" ||
         action === "package" ||
         action.startsWith("extension-") ||
@@ -412,6 +413,18 @@ const SCHEDULING_ACTION_SCHEMA_CONTRACT = {
         "message",
     ],
 };
+const UPGRADE_ACTION_SCHEMA_CONTRACT = {
+    optional: [
+        "target",
+        "scope",
+        "dryRun",
+        "cliOnly",
+        "packagesOnly",
+        "repair",
+        "tag",
+        "packageName",
+    ],
+};
 const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
     init: {
         optional: [
@@ -442,22 +455,12 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
     },
     ...managedLifecycleSchemaContracts("extension"),
     ...managedLifecycleSchemaContracts("package"),
+    "package-upgrade": UPGRADE_ACTION_SCHEMA_CONTRACT,
     install: {
         optional: ["target", "github", "scope", "ref"],
         anyOfRequired: [["target"], ["github"]],
     },
-    upgrade: {
-        optional: [
-            "target",
-            "scope",
-            "dryRun",
-            "cliOnly",
-            "packagesOnly",
-            "repair",
-            "tag",
-            "packageName",
-        ],
-    },
+    upgrade: UPGRADE_ACTION_SCHEMA_CONTRACT,
     create: {
         required: [
             "title",
@@ -1613,4 +1616,4 @@ export const _testOnlyCliContracts = {
     withFlagAliasMetadata,
 };
 //# sourceMappingURL=tool-schema.js.map
-//# debugId=b54b0565-3968-59ea-b5f9-8ae52731473a
+//# debugId=0b302ca6-1333-532f-a55e-e8e984636456

package/dist/sdk/cli-contracts.d.ts

@@ -14,7 +14,7 @@ export type { CommanderOptionAliasContract, CommanderOptionRegistrationContract,
 export { EXECUTABLE_COMMAND_ALIASES, PM_COMMAND_ALIAS_CONTRACTS, renderPmCommandAliasMigrationHint, resolvePmCommandAlias, type PmCommandAliasContract, type PmCommandAliasLifecycle, type PmCommandAliasRegistration, } from "./cli-contracts/command-aliases.js";
 export { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, readFirstValueFromCommanderOptions, readFirstStringFromCommanderOptions, readStringArrayFromCommanderOptions, } from "./cli-contracts/commander-types.js";
 export { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, } from "./cli-contracts/commander-mutation-options.js";
-export { MERGE_SUBCOMMAND_VALUES, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_ITEM_ACTION_SUBCOMMANDS, PM_DEPRECATED_TOOL_ACTIONS, PM_DISCOVERABLE_TOOL_ACTIONS, PM_TOOL_ACTIONS, analyzePmToolActionParity, isPmToolAction, isPmExtensionCapabilityContract, isPmExtensionServiceNameContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, } from "./cli-contracts/enum-contracts.js";
+export { MERGE_SUBCOMMAND_VALUES, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_PACKAGE_ONLY_ACTION_SUBCOMMANDS, PM_ITEM_ACTION_SUBCOMMANDS, PM_DEPRECATED_TOOL_ACTIONS, PM_DISCOVERABLE_TOOL_ACTIONS, PM_TOOL_ACTIONS, analyzePmToolActionParity, isPmToolAction, isPmExtensionCapabilityContract, isPmExtensionServiceNameContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, } from "./cli-contracts/enum-contracts.js";
 export type { MergeSubcommand, PmExtensionCapabilityContract, PmExtensionServiceNameContract, PmExtensionPolicyModeContract, PmExtensionTrustModeContract, PmExtensionSandboxProfileContract, PmExtensionPolicySurfaceContract, PmToolAction, } from "./cli-contracts/enum-contracts.js";
 export { TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, verifyToolOptionCliParity, type ToolOptionCliParityFinding, type ToolOptionCliParityReport, } from "./cli-contracts/tool-option-contracts.js";
 export type { OptionsFromContracts, PmBulkMutationControlOptions, PmBulkMutationFilterOptions, PmCloseActionOptions, PmCloseManyActionOptions, PmCreateActionOptions, PmMutationAttributionOptions, PmOptionScalar, PmUpdateActionOptions, PmUpdateManyActionOptions, } from "./cli-contracts/typed-action-inputs.js";

package/dist/sdk/cli-contracts.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c008aee5-ffe9-5da2-b1d9-6fb9fb6684c5")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="167b98d4-a5b5-581d-ac0a-17e8e3bfc490")}catch(e){}}();
 export { EXECUTABLE_COMMAND_ALIASES, PM_COMMAND_ALIAS_CONTRACTS, renderPmCommandAliasMigrationHint, resolvePmCommandAlias, } from "./cli-contracts/command-aliases.js";
 export { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, readFirstValueFromCommanderOptions, readFirstStringFromCommanderOptions, readStringArrayFromCommanderOptions, } from "./cli-contracts/commander-types.js";
 export { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, } from "./cli-contracts/commander-mutation-options.js";
@@ -7,7 +7,7 @@ export { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEAT
 // tables live in sibling modules and are re-exported here so existing import
 // sites (sdk/index.ts, mcp/server.ts, commands/contracts.ts, completion.ts, …)
 // keep importing everything from "./cli-contracts.js" unchanged.
-export { MERGE_SUBCOMMAND_VALUES, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_ITEM_ACTION_SUBCOMMANDS, PM_DEPRECATED_TOOL_ACTIONS, PM_DISCOVERABLE_TOOL_ACTIONS, PM_TOOL_ACTIONS, analyzePmToolActionParity, isPmToolAction, isPmExtensionCapabilityContract, isPmExtensionServiceNameContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, } from "./cli-contracts/enum-contracts.js";
+export { MERGE_SUBCOMMAND_VALUES, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_PACKAGE_ONLY_ACTION_SUBCOMMANDS, PM_ITEM_ACTION_SUBCOMMANDS, PM_DEPRECATED_TOOL_ACTIONS, PM_DISCOVERABLE_TOOL_ACTIONS, PM_TOOL_ACTIONS, analyzePmToolActionParity, isPmToolAction, isPmExtensionCapabilityContract, isPmExtensionServiceNameContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, } from "./cli-contracts/enum-contracts.js";
 export { TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, verifyToolOptionCliParity, } from "./cli-contracts/tool-option-contracts.js";
 export { PM_COMMAND_POSITIONAL_CONTRACTS, PM_POSITIONAL_ACTION_CONTRACTS, } from "./cli-contracts/grammar-contracts.js";
 export { withFlagAliasMetadata, compactFlagAliasContracts, resolvePmPositionalActionFlagContracts, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, ASSURANCE_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_REOPEN_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, hasSubcommandFlagContractsForCommand, resolveSubcommandFlagContractsForCommand, toCompletionFlagString, } from "./cli-contracts/flag-contracts.js";
@@ -15,4 +15,4 @@ export { buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES,
 export { analyzeSdkCliParameterCompleteness, } from "./cli-contracts/completeness.js";
 export { PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_DIAGNOSTIC_DEGRADATION_STEPS, PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS, PM_DIAGNOSTIC_OUTPUT_CLASSES, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, projectPmDiagnosticOutput, projectPmDiagnosticText, resolvePmDiagnosticOutputBudget, resolvePmCommandOutputBudget, } from "./cli-contracts/agent-output-contracts.js";
 //# sourceMappingURL=cli-contracts.js.map
-//# debugId=c008aee5-ffe9-5da2-b1d9-6fb9fb6684c5
+//# debugId=167b98d4-a5b5-581d-ac0a-17e8e3bfc490

package/dist/sdk/cli-program.js

@@ -4,7 +4,7 @@
  * Builds the reusable Commander root that embeds pm's universal global contracts.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="03d46cbf-73bc-50c9-b4e6-e7329ee53076")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="31e820a7-aa60-5e37-846d-c62b81b47587")}catch(e){}}();
 import { Command } from "commander";
 import { writeStdout } from "../core/output/output.js";
 /** Create a fresh pm root program suitable for one-shot CLI or embedded hosts. */
@@ -41,9 +41,10 @@ export function createPmCliProgram(version) {
         .option("--no-extensions", "Disable extension loading")
         .option("--no-pager", "Disable pager integration for help and long output")
         .option("--explain", "Render extended rationale and examples in help output")
+        .option("--all", "Reveal every public command and compatibility alias")
         .option("--profile", "Print deterministic timing diagnostics")
         .option("--author <id>", "Override mutation author for this invocation")
         .exitOverride();
 }
 //# sourceMappingURL=cli-program.js.map
-//# debugId=03d46cbf-73bc-50c9-b4e6-e7329ee53076
+//# debugId=31e820a7-aa60-5e37-846d-c62b81b47587

package/dist/sdk/completion.js

@@ -4,11 +4,11 @@
  * Implements the pm completion command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="48da3e98-ab96-54de-8993-7de0c4edf19b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c8446891-4e65-54c3-9826-eb40f4922f3b")}catch(e){}}();
 import { EXIT_CODE, PmCliError } from "./runtime-primitives.js";
 import { listPmCommandsForTier } from "./agent-capability-contracts.js";
 import { SCAFFOLD_CAPABILITIES } from "./extension/scaffold.js";
-import { AGGREGATE_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, PM_COMMAND_ALIAS_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, toCompletionFlagString, } from "./cli-contracts.js";
+import { AGGREGATE_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, PM_COMMAND_ALIAS_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, toCompletionFlagString, } from "./cli-contracts.js";
 import { BUILTIN_ITEM_TYPE_VALUES, STATUS_VALUES } from "../types/index.js";
 import { listGuideTopicIds } from "./guide-topics.js";
 const VALID_SHELLS = ["bash", "zsh", "fish"];
@@ -49,9 +49,11 @@ const PLAN_SUBCOMMANDS_LIST = "create show add-step update-step complete-step bl
 const COMPLETION_FLAGS = toCompletionFlagString(COMPLETION_FLAG_CONTRACTS);
 const COMPLETION_SHELL_CHOICES = `${COMPLETION_FLAGS} bash zsh fish`;
 const GUIDE_TOPIC_CHOICES = joinCompletionValues(listGuideTopicIds());
-const LIFECYCLE_ACTIONS = "init scaffold install uninstall explore manage describe reload doctor catalog adopt adopt-all activate deactivate";
+const EXTENSION_LIFECYCLE_ACTIONS = "init scaffold install uninstall explore manage describe reload doctor catalog adopt adopt-all activate deactivate migrate";
+const PACKAGE_LIFECYCLE_ACTIONS = `${EXTENSION_LIFECYCLE_ACTIONS} upgrade`;
 const EXTENSION_LIFECYCLE_FLAGS = toCompletionFlagString(EXTENSION_FLAG_CONTRACTS);
 const PACKAGE_LIFECYCLE_FLAGS = toCompletionFlagString(PACKAGE_FLAG_CONTRACTS);
+const UPGRADE_FLAGS = toCompletionFlagString(UPGRADE_FLAG_CONTRACTS);
 const MUTATION_FLAGS = "--author --message --force --json --quiet --no-changed-fields --id-only --pm-path --path --no-extensions --no-pager --profile --help";
 const DELETE_MUTATION_FLAGS = "--dry-run --author --message --force --json --quiet --no-changed-fields --id-only --pm-path --path --no-extensions --no-pager --profile --help";
 const CLOSE_MUTATION_FLAGS = "--author --message --validate-close --duplicate-of --force --json --quiet --no-changed-fields --id-only --pm-path --path --no-extensions --no-pager --profile --help";
@@ -59,7 +61,6 @@ const RELEASE_MUTATION_FLAGS = "--author --message --force --json --quiet --no-c
 const COMMAND_COMPLETION_DESCRIPTIONS = [
     ["init", "Initialize pm storage for the current workspace"],
     ["config", "Read or update pm settings"],
-    ["extension", "Manage extension lifecycle operations"],
     ["package", "Manage package lifecycle operations"],
     ["packages", "Alias for package"],
     ["create", "Create a new project management item"],
@@ -515,13 +516,13 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         "",
         ...(useEagerTagExpansion
             ? [
-                '  if [[ "$prev" == "--tag" || "$prev" == "--tags" ]]; then',
+                '  if [[ ( "$prev" == "--tag" || "$prev" == "--tags" ) && ! ( ( "${COMP_WORDS[1]}" == "package" || "${COMP_WORDS[1]}" == "packages" ) && "${COMP_WORDS[2]}" == "upgrade" ) ]]; then',
                 `    COMPREPLY=(${compgen(tagValues)})`,
                 "    return 0",
                 "  fi",
             ]
             : [
-                '  if [[ "$prev" == "--tag" || "$prev" == "--tags" ]]; then',
+                '  if [[ ( "$prev" == "--tag" || "$prev" == "--tags" ) && ! ( ( "${COMP_WORDS[1]}" == "package" || "${COMP_WORDS[1]}" == "packages" ) && "${COMP_WORDS[2]}" == "upgrade" ) ]]; then',
                 "    local now ttl cache_ts tag_values",
                 '    now="$(date +%s 2>/dev/null || echo 0)"',
                 '    ttl="${PM_COMPLETION_TAG_TTL:-120}"',
@@ -537,6 +538,11 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
                 "  fi",
             ]),
         "",
+        '  if [[ "$prev" == "--tag" && ( ( "${COMP_WORDS[1]}" == "package" || "${COMP_WORDS[1]}" == "packages" ) && "${COMP_WORDS[2]}" == "upgrade" ) ]]; then',
+        "    COMPREPLY=()",
+        "    return 0",
+        "  fi",
+        "",
         '  local cmd="${COMP_WORDS[1]}"',
         "",
         '  case "$cmd" in',
@@ -589,10 +595,10 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         `      COMPREPLY=(${compgen("--criterion --clear-criteria --format --policy --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    extension)",
-        `      COMPREPLY=(${compgen(`${LIFECYCLE_ACTIONS} ${EXTENSION_LIFECYCLE_FLAGS}`)})`,
+        `      COMPREPLY=(${compgen(`${EXTENSION_LIFECYCLE_ACTIONS} ${EXTENSION_LIFECYCLE_FLAGS}`)})`,
         "      ;;",
         "    package|packages)",
-        `      COMPREPLY=(${compgen(`${LIFECYCLE_ACTIONS} ${PACKAGE_LIFECYCLE_FLAGS}`)})`,
+        `      COMPREPLY=(${compgen(`${PACKAGE_LIFECYCLE_ACTIONS} ${PACKAGE_LIFECYCLE_FLAGS} ${UPGRADE_FLAGS}`)})`,
         "      ;;",
         "    comments)",
         `      COMPREPLY=(${compgen("--add --body --stdin --file --edit --delete --limit --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
@@ -706,6 +712,9 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         `      COMPREPLY=(${compgen(GLOBAL_FLAGS)})`,
         "      ;;",
         "  esac",
+        '  if [[ "$cmd" == "comments" || "$cmd" == "notes" || "$cmd" == "learnings" ]]; then',
+        `    COMPREPLY+=(${compgen("--text")})`,
+        "  fi",
         "  return 0",
         "}",
         "",
@@ -778,6 +787,7 @@ _pm() {
   local context state line
   _arguments -C \\
     '--json[Output JSON instead of TOON]' \\
+    '--all[Reveal every public command and compatibility alias]' \\
     '--quiet[Suppress stdout output]' \\
     '--output-include[Retain comma-separated read fields or sections]:selectors' \\
     '--output-limit[Set the universal read row ceiling]:limit' \\
@@ -1353,6 +1363,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
         comments)
           _arguments \\
             '--add[Add one entry (plain text, text=<value>, markdown pairs, or - for stdin)]:text' \\
+            '--text[Alias for --add]:text' \\
             '--stdin[Read comment text from stdin (supports multiline markdown)]' \\
             '--file[Read comment text from file (supports multiline markdown)]:path' \\
             '--edit[Replace the comment at 1-based index (text from positional/--add/--stdin/--file)]:index' \\
@@ -1368,6 +1379,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
         notes)
           _arguments \\
             '--add[Add one entry (plain text, text=<value>, markdown pairs, or - for stdin)]:text' \\
+            '--text[Alias for --add]:text' \\
             '--add-json[Append one validated JSON context event]:json' \\
             '--stdin[Read entry text from stdin]' \\
             '--file[Read entry text from file]:path' \\
@@ -1387,6 +1399,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
         learnings)
           _arguments \\
             '--add[Add one entry (plain text, text=<value>, markdown pairs, or - for stdin)]:text' \\
+            '--text[Alias for --add]:text' \\
             '--stdin[Read entry text from stdin]' \\
             '--file[Read entry text from file]:path' \\
             '--edit[Replace the entry at a 1-based index]:index' \\
@@ -1665,7 +1678,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
           ;;
         extension)
           _arguments \\
-            '1:extension_action:(init scaffold install uninstall explore manage describe reload doctor catalog adopt adopt-all activate deactivate)' \\
+            '1:extension_action:(${EXTENSION_LIFECYCLE_ACTIONS})' \\
             '--init[Generate a starter extension scaffold at target path]' \\
             '--scaffold[Alias for --init]' \\
             '--capability[Capability the init scaffold targets]:capability:(${SCAFFOLD_CAPABILITIES.join(" ")})' \\
@@ -1704,7 +1717,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
           ;;
         package|packages)
           _arguments \\
-            '1:package_action:(init scaffold install uninstall explore manage describe reload doctor catalog adopt adopt-all activate deactivate)' \\
+            '1:package_action:(${PACKAGE_LIFECYCLE_ACTIONS})' \\
             '--init[Generate a starter package scaffold at target path]' \\
             '--scaffold[Alias for --init]' \\
             '--capability[Capability the init scaffold targets]:capability:(${SCAFFOLD_CAPABILITIES.join(" ")})' \\
@@ -1738,6 +1751,12 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--ignore-global[Alias for --isolated]' \\
             '--strict-exit[Return non-zero exit when doctor warnings are present]' \\
             '--fail-on-warn[Alias for --strict-exit (doctor)]' \\
+            '--dry-run[Plan upgrades without mutating]' \\
+            '--cli-only[Upgrade only the pm CLI/SDK npm package]' \\
+            '--packages-only[Upgrade only managed pm packages]' \\
+            '--repair[Force npm global reinstall for the CLI/SDK]' \\
+            '--tag[npm version or dist-tag for upgrades]:tag' \\
+            '--package-name[Override the CLI package name]:package_name' \\
             '--json[Output JSON]' \\
             '--quiet[Suppress stdout]' \\
             '*:target_or_name:_files -/'
@@ -1818,6 +1837,7 @@ complete -c pm -f
 
 # Global flags (available for all subcommands)
 complete -c pm -l json -d 'Output JSON instead of TOON'
+complete -c pm -l all -d 'Reveal every public command and compatibility alias'
 complete -c pm -l quiet -d 'Suppress stdout output'
 complete -c pm -l output-include -d 'Retain comma-separated read fields or sections' -r
 complete -c pm -l output-limit -d 'Set the universal read row ceiling' -r
@@ -2423,6 +2443,7 @@ complete -c pm -n '__fish_seen_subcommand_from graph' -l summary -d 'Return coun
 
 # comments / notes / learnings flags
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l add -d 'Add one entry (text=<value> or plain text)' -r
+complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l text -d 'Alias for --add' -r
 complete -c pm -n '__fish_seen_subcommand_from notes' -l add-json -d 'Append one validated JSON context event' -r
 complete -c pm -n '__fish_seen_subcommand_from notes' -l since -d 'Return structured events at or after an ISO timestamp' -r
 complete -c pm -n '__fish_seen_subcommand_from notes' -l event-type -d 'Return structured events with this top-level type' -r
@@ -2666,7 +2687,7 @@ complete -c pm -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish' -d
 complete -c pm -n '__fish_seen_subcommand_from templates' -a 'save list show' -d 'Templates command'
 
 # extension lifecycle flags
-complete -c pm -n '__fish_seen_subcommand_from extension' -a '${LIFECYCLE_ACTIONS}' -d 'Extension action subcommand'
+complete -c pm -n '__fish_seen_subcommand_from extension' -a '${EXTENSION_LIFECYCLE_ACTIONS}' -d 'Extension action subcommand'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l init -d 'Generate starter extension scaffold'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l scaffold -d 'Alias for --init'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l capability -d 'Capability the init scaffold targets' -r -a '${SCAFFOLD_CAPABILITIES.join(" ")}'
@@ -2702,7 +2723,7 @@ complete -c pm -n '__fish_seen_subcommand_from extension' -l fail-on-warn -d 'Al
 
 # package lifecycle flags
 for package_cmd in package packages
-  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -a '${LIFECYCLE_ACTIONS}' -d 'Package action subcommand'
+  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -a '${PACKAGE_LIFECYCLE_ACTIONS}' -d 'Package action subcommand'
   complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l init -d 'Generate starter package scaffold'
   complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l scaffold -d 'Alias for --init'
   complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l capability -d 'Capability the init scaffold targets' -r -a '${SCAFFOLD_CAPABILITIES.join(" ")}'
@@ -2736,6 +2757,12 @@ for package_cmd in package packages
   complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l ignore-global -d 'Alias for --isolated'
   complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l strict-exit -d 'Return non-zero exit when doctor warnings are present'
   complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l fail-on-warn -d 'Alias for --strict-exit (doctor)'
+  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l dry-run -d 'Plan upgrades without mutating'
+  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l cli-only -d 'Upgrade only the pm CLI/SDK npm package'
+  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l packages-only -d 'Upgrade only managed pm packages'
+  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l repair -d 'Force npm global reinstall for the CLI/SDK'
+  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l tag -d 'npm version or dist-tag for upgrades' -r
+  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l package-name -d 'Override the CLI package name' -r
 end`;
 }
 const SETUP_HINTS = {
@@ -2767,4 +2794,4 @@ export function runCompletion(shell, itemTypes = [], tags = [], eagerTagExpansio
     };
 }
 //# sourceMappingURL=completion.js.map
-//# debugId=48da3e98-ab96-54de-8993-7de0c4edf19b
+//# debugId=c8446891-4e65-54c3-9826-eb40f4922f3b