@unbrained/pm-cli 2026.5.11 → 2026.5.12

package/dist/sdk/index.d.ts

@@ -1,4 +1,5 @@
 import { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES, type ExtensionApi, type ExtensionManifest } from "../core/extensions/loader.js";
+export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, collectPackageExtensionDirectories, readPmPackageManifest, type PmPackageManifest, type PmPackageResourceKind, type PmPackageResourceMap, } from "../core/packages/manifest.js";
 export * from "./cli-contracts.js";
 /**
  * Canonical extension capability names accepted by pm.

package/dist/sdk/index.js

@@ -1,4 +1,5 @@
 import { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES, KNOWN_EXTENSION_CAPABILITIES, KNOWN_EXTENSION_POLICY_MODES, KNOWN_EXTENSION_POLICY_SURFACES, KNOWN_EXTENSION_SANDBOX_PROFILES, KNOWN_EXTENSION_TRUST_MODES, } from "../core/extensions/loader.js";
+export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, collectPackageExtensionDirectories, readPmPackageManifest, } from "../core/packages/manifest.js";
 export * from "./cli-contracts.js";
 /**
  * Canonical extension capability names accepted by pm.

package/dist/sdk/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"/","sources":["sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,qCAAqC,EACrC,mCAAmC,EACnC,4BAA4B,EAC5B,4BAA4B,EAC5B,+BAA+B,EAC/B,gCAAgC,EAChC,2BAA2B,GAG5B,MAAM,8BAA8B,CAAC;AACtC,cAAc,oBAAoB,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AAGnE;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AACnE,MAAM,CAAC,MAAM,yBAAyB,GAAG,+BAA+B,CAAC;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AACjE,MAAM,CAAC,MAAM,0BAA0B,GAAG,gCAAgC,CAAC;AAM3E;;GAEG;AACH,OAAO,EAAE,6BAA6B,EAAE,qCAAqC,EAAE,mCAAmC,EAAE,CAAC;AAarH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAkC,MAAe;IAC9E,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import {\n  EXTENSION_CAPABILITY_CONTRACT,\n  EXTENSION_CAPABILITY_CONTRACT_VERSION,\n  EXTENSION_CAPABILITY_LEGACY_ALIASES,\n  KNOWN_EXTENSION_CAPABILITIES,\n  KNOWN_EXTENSION_POLICY_MODES,\n  KNOWN_EXTENSION_POLICY_SURFACES,\n  KNOWN_EXTENSION_SANDBOX_PROFILES,\n  KNOWN_EXTENSION_TRUST_MODES,\n  type ExtensionApi,\n  type ExtensionManifest,\n} from \"../core/extensions/loader.js\";\nexport * from \"./cli-contracts.js\";\n\n/**\n * Canonical extension capability names accepted by pm.\n *\n * Extension manifests should declare one or more of these values in\n * `capabilities`.\n */\nexport const EXTENSION_CAPABILITIES = KNOWN_EXTENSION_CAPABILITIES;\nexport type ExtensionCapability = (typeof EXTENSION_CAPABILITIES)[number];\n\n/**\n * Canonical extension governance policy modes and registration surfaces.\n */\nexport const EXTENSION_POLICY_MODES = KNOWN_EXTENSION_POLICY_MODES;\nexport const EXTENSION_POLICY_SURFACES = KNOWN_EXTENSION_POLICY_SURFACES;\nexport const EXTENSION_TRUST_MODES = KNOWN_EXTENSION_TRUST_MODES;\nexport const EXTENSION_SANDBOX_PROFILES = KNOWN_EXTENSION_SANDBOX_PROFILES;\nexport type ExtensionPolicyMode = (typeof EXTENSION_POLICY_MODES)[number];\nexport type ExtensionPolicySurface = (typeof EXTENSION_POLICY_SURFACES)[number];\nexport type ExtensionTrustMode = (typeof EXTENSION_TRUST_MODES)[number];\nexport type ExtensionSandboxProfile = (typeof EXTENSION_SANDBOX_PROFILES)[number];\n\n/**\n * Versioned capability contract metadata emitted by runtime diagnostics.\n */\nexport { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES };\n\nexport interface ExtensionModule {\n  /**\n   * Optional in-module metadata mirror.\n   *\n   * The authoritative manifest remains on-disk `manifest.json`; this field is\n   * useful when authors want colocated metadata for tooling/tests.\n   */\n  manifest?: ExtensionManifest;\n  activate(api: ExtensionApi): void | Promise<void>;\n}\n\n/**\n * Typed identity helper for extension module exports.\n *\n * Use as:\n * `export default defineExtension({ activate(api) { ... } })`\n */\nexport function defineExtension<TModule extends ExtensionModule>(module: TModule): TModule {\n  return module;\n}\n\nexport type {\n  AfterCommandHook,\n  AfterCommandHookContext,\n  BeforeCommandHook,\n  BeforeCommandHookContext,\n  CommandDefinition,\n  ExtensionCommandArgumentDefinition,\n  CommandHandler,\n  CommandHandlerContext,\n  CommandOverride,\n  CommandOverrideContext,\n  ExtensionServiceName,\n  Exporter,\n  ExtensionActivationResult,\n  ExtensionApi,\n  ExtensionCommandRegistry,\n  ExtensionDiagnostic,\n  ExtensionDiscoveryResult,\n  ExtensionLoadResult,\n  ExtensionManifest,\n  ExtensionGovernancePolicy,\n  ExtensionPolicyOverride,\n  ExtensionProvenanceMetadata,\n  ExtensionRuntimePermissionDeclaration,\n  ExtensionSearchMode,\n  ExtensionParserRegistry,\n  ExtensionPreflightRegistry,\n  ExtensionRegistrationRegistry,\n  ExtensionRendererRegistry,\n  ExtensionServiceRegistry,\n  FlagValueType,\n  FlagDefinition,\n  ImportExportContext,\n  Importer,\n  OnIndexHook,\n  OnIndexHookContext,\n  OnReadHook,\n  OnReadHookContext,\n  OnWriteHook,\n  OnWriteHookContext,\n  OutputRendererFormat,\n  ParserOverride,\n  ParserOverrideContext,\n  ParserOverrideDelta,\n  PreflightOverride,\n  PreflightOverrideContext,\n  PreflightOverrideDelta,\n  PreflightRuntimeDecision,\n  RendererOverride,\n  RendererOverrideContext,\n  SchemaFieldDefinition,\n  SchemaItemTypeCommandOptionPolicyDefinition,\n  SchemaItemTypeOptionDefinition,\n  SchemaItemTypeDefinition,\n  SchemaMigrationDefinition,\n  SchemaMigrationRunContext,\n  SchemaMigrationRunner,\n  SearchProviderEmbedBatchContext,\n  SearchProviderEmbedContext,\n  SearchProviderDefinition,\n  SearchProviderHit,\n  SearchProviderQueryContext,\n  SearchProviderQueryResult,\n  ServiceOverride,\n  ServiceOverrideContext,\n  VectorStoreAdapterDefinition,\n  VectorStoreDeleteContext,\n  VectorStoreQueryContext,\n  VectorStoreQueryHit,\n  VectorStoreUpsertContext,\n  VectorStoreUpsertPoint,\n} from \"../core/extensions/loader.js\";\n\nexport type { GlobalOptions } from \"../core/shared/command-types.js\";\nexport type { ItemDocument, ItemFrontMatter, ItemStatus, ItemType, PmSettings } from \"../types/index.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"/","sources":["sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,qCAAqC,EACrC,mCAAmC,EACnC,4BAA4B,EAC5B,4BAA4B,EAC5B,+BAA+B,EAC/B,gCAAgC,EAChC,2BAA2B,GAG5B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,sCAAsC,EACtC,yBAAyB,EACzB,kCAAkC,EAClC,qBAAqB,GAItB,MAAM,8BAA8B,CAAC;AACtC,cAAc,oBAAoB,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AAGnE;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AACnE,MAAM,CAAC,MAAM,yBAAyB,GAAG,+BAA+B,CAAC;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AACjE,MAAM,CAAC,MAAM,0BAA0B,GAAG,gCAAgC,CAAC;AAM3E;;GAEG;AACH,OAAO,EAAE,6BAA6B,EAAE,qCAAqC,EAAE,mCAAmC,EAAE,CAAC;AAarH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAkC,MAAe;IAC9E,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import {\n  EXTENSION_CAPABILITY_CONTRACT,\n  EXTENSION_CAPABILITY_CONTRACT_VERSION,\n  EXTENSION_CAPABILITY_LEGACY_ALIASES,\n  KNOWN_EXTENSION_CAPABILITIES,\n  KNOWN_EXTENSION_POLICY_MODES,\n  KNOWN_EXTENSION_POLICY_SURFACES,\n  KNOWN_EXTENSION_SANDBOX_PROFILES,\n  KNOWN_EXTENSION_TRUST_MODES,\n  type ExtensionApi,\n  type ExtensionManifest,\n} from \"../core/extensions/loader.js\";\nexport {\n  PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS,\n  PM_PACKAGE_RESOURCE_KINDS,\n  collectPackageExtensionDirectories,\n  readPmPackageManifest,\n  type PmPackageManifest,\n  type PmPackageResourceKind,\n  type PmPackageResourceMap,\n} from \"../core/packages/manifest.js\";\nexport * from \"./cli-contracts.js\";\n\n/**\n * Canonical extension capability names accepted by pm.\n *\n * Extension manifests should declare one or more of these values in\n * `capabilities`.\n */\nexport const EXTENSION_CAPABILITIES = KNOWN_EXTENSION_CAPABILITIES;\nexport type ExtensionCapability = (typeof EXTENSION_CAPABILITIES)[number];\n\n/**\n * Canonical extension governance policy modes and registration surfaces.\n */\nexport const EXTENSION_POLICY_MODES = KNOWN_EXTENSION_POLICY_MODES;\nexport const EXTENSION_POLICY_SURFACES = KNOWN_EXTENSION_POLICY_SURFACES;\nexport const EXTENSION_TRUST_MODES = KNOWN_EXTENSION_TRUST_MODES;\nexport const EXTENSION_SANDBOX_PROFILES = KNOWN_EXTENSION_SANDBOX_PROFILES;\nexport type ExtensionPolicyMode = (typeof EXTENSION_POLICY_MODES)[number];\nexport type ExtensionPolicySurface = (typeof EXTENSION_POLICY_SURFACES)[number];\nexport type ExtensionTrustMode = (typeof EXTENSION_TRUST_MODES)[number];\nexport type ExtensionSandboxProfile = (typeof EXTENSION_SANDBOX_PROFILES)[number];\n\n/**\n * Versioned capability contract metadata emitted by runtime diagnostics.\n */\nexport { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES };\n\nexport interface ExtensionModule {\n  /**\n   * Optional in-module metadata mirror.\n   *\n   * The authoritative manifest remains on-disk `manifest.json`; this field is\n   * useful when authors want colocated metadata for tooling/tests.\n   */\n  manifest?: ExtensionManifest;\n  activate(api: ExtensionApi): void | Promise<void>;\n}\n\n/**\n * Typed identity helper for extension module exports.\n *\n * Use as:\n * `export default defineExtension({ activate(api) { ... } })`\n */\nexport function defineExtension<TModule extends ExtensionModule>(module: TModule): TModule {\n  return module;\n}\n\nexport type {\n  AfterCommandHook,\n  AfterCommandHookContext,\n  BeforeCommandHook,\n  BeforeCommandHookContext,\n  CommandDefinition,\n  ExtensionCommandArgumentDefinition,\n  CommandHandler,\n  CommandHandlerContext,\n  CommandOverride,\n  CommandOverrideContext,\n  ExtensionServiceName,\n  Exporter,\n  ExtensionActivationResult,\n  ExtensionApi,\n  ExtensionCommandRegistry,\n  ExtensionDiagnostic,\n  ExtensionDiscoveryResult,\n  ExtensionLoadResult,\n  ExtensionManifest,\n  ExtensionGovernancePolicy,\n  ExtensionPolicyOverride,\n  ExtensionProvenanceMetadata,\n  ExtensionRuntimePermissionDeclaration,\n  ExtensionSearchMode,\n  ExtensionParserRegistry,\n  ExtensionPreflightRegistry,\n  ExtensionRegistrationRegistry,\n  ExtensionRendererRegistry,\n  ExtensionServiceRegistry,\n  FlagValueType,\n  FlagDefinition,\n  ImportExportContext,\n  Importer,\n  OnIndexHook,\n  OnIndexHookContext,\n  OnReadHook,\n  OnReadHookContext,\n  OnWriteHook,\n  OnWriteHookContext,\n  OutputRendererFormat,\n  ParserOverride,\n  ParserOverrideContext,\n  ParserOverrideDelta,\n  PreflightOverride,\n  PreflightOverrideContext,\n  PreflightOverrideDelta,\n  PreflightRuntimeDecision,\n  RendererOverride,\n  RendererOverrideContext,\n  SchemaFieldDefinition,\n  SchemaItemTypeCommandOptionPolicyDefinition,\n  SchemaItemTypeOptionDefinition,\n  SchemaItemTypeDefinition,\n  SchemaMigrationDefinition,\n  SchemaMigrationRunContext,\n  SchemaMigrationRunner,\n  SearchProviderEmbedBatchContext,\n  SearchProviderEmbedContext,\n  SearchProviderDefinition,\n  SearchProviderHit,\n  SearchProviderQueryContext,\n  SearchProviderQueryResult,\n  ServiceOverride,\n  ServiceOverrideContext,\n  VectorStoreAdapterDefinition,\n  VectorStoreDeleteContext,\n  VectorStoreQueryContext,\n  VectorStoreQueryHit,\n  VectorStoreUpsertContext,\n  VectorStoreUpsertPoint,\n} from \"../core/extensions/loader.js\";\n\nexport type { GlobalOptions } from \"../core/shared/command-types.js\";\nexport type { ItemDocument, ItemFrontMatter, ItemStatus, ItemType, PmSettings } from \"../types/index.js\";\n"]}

package/docs/ARCHITECTURE.md

@@ -193,7 +193,7 @@ Command/action metadata is centralized in `src/sdk/cli-contracts.ts` and used by
 - CLI option normalization
 - help output
 - completion generation
-- Pi wrapper schema
+- provider-safe tool schemas
 - `pm contracts`
 - extension command/action contract exposure
 

package/docs/COMMANDS.md

@@ -31,7 +31,7 @@ Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 | Verification | `test`, `test-all`, `test-runs`, `validate`, `gc` | run linked tests and repository checks |
 | History | `history`, `activity`, `restore`, `stats` | inspect and recover item state |
 | Calendar | `calendar`, `cal` | project deadlines, reminders, and events |
-| Extensions | `extension`, extension command groups | install, manage, and run extension commands |
+| Packages | `install`, `upgrade`, `package`, `packages`, `extension`, package/extension command groups | install, upgrade, manage, and run package-backed extension commands |
 | Machines | `guide`, `contracts`, `completion`, `help` | local docs routing plus command contracts and shell helpers |
 
 ## Bootstrap
@@ -44,6 +44,19 @@ pm health --check-only
 
 `pm init` creates `.agents/pm`. `pm health --check-only` inspects without refreshing optional search artifacts.
 
+## Packages
+
+```bash
+pm install '*' --project
+pm install npm:@scope/pm-package --project
+pm package doctor --project --detail summary
+pm upgrade --dry-run
+pm upgrade --packages-only
+pm upgrade --cli-only --repair
+```
+
+`pm install` and `pm package` are the preferred package-first workflow. `pm install '*'`, shell-expanded `pm install *`, and `pm install all` install bundled first-party packages. `pm extension` remains as a compatibility command for direct extension lifecycle operations.
+
 ## Triage
 
 ```bash

package/docs/EXTENSIONS.md

@@ -1,25 +1,58 @@
-# Extensions
+# Packages and Extensions
+
+Packages let you add or override `pm` runtime behavior without modifying core `pm-cli` sources. A package can currently contain one or more runtime extensions, and the package-first command surface is the preferred user-facing workflow.
 
-Extensions let you add or override `pm` runtime behavior without modifying core `pm-cli` sources.
+`pm extension ...` remains supported for compatibility. New scripts and docs should prefer `pm install ...` and `pm package ...`.
 
-This document is the canonical extension reference for manifest contracts, governance policy, trust and sandbox controls, reload workflows, and diagnostics.
+This document is the canonical package/extension reference for manifest contracts, governance policy, trust and sandbox controls, reload workflows, and diagnostics.
 
 ## Quick Start
 
 ```bash
-# 1) Scaffold an extension
-pm extension --init ./my-extension
+# 1) Scaffold a package extension
+pm package init ./my-package-extension
 
 # 2) Install in project scope
-pm extension --install --project ./my-extension
+pm install ./my-package --project
+
+# Or install all bundled first-party packages
+pm install '*' --project
 
 # 3) Run diagnostics
-pm extension --doctor --project --detail summary
+pm package doctor --project --detail summary
 
-# 4) Reload runtime modules after local edits
-pm extension --reload --project
+# 4) Plan CLI/SDK and package upgrades
+pm upgrade --dry-run
+
+# 5) Reload runtime modules after local edits
+pm package reload --project
+```
+
+Compatibility equivalents:
+
+```bash
+pm extension init ./my-package
+pm extension install ./my-package --project
+pm extension doctor --project --detail summary
+pm extension reload --project
 ```
 
+## Upgrade Workflow
+
+`pm upgrade` is the package-first update entrypoint:
+
+```bash
+pm upgrade --dry-run              # plan CLI/SDK and project package updates
+pm upgrade                        # update the global pm CLI/SDK, then refresh project packages
+pm upgrade --packages-only        # refresh managed packages without changing the CLI
+pm upgrade todos --dry-run        # plan one managed package refresh
+pm upgrade --cli-only --repair    # force a global CLI/SDK reinstall through npm
+```
+
+CLI/SDK upgrades use `npm install -g @unbrained/pm-cli@<tag>`.
+Managed package upgrades reuse the source recorded at install time, including `npm:`, GitHub, local, and first-party package paths.
+Use `--tag <version-or-dist-tag>` to target a registry tag such as `latest` or `next`.
+
 ## Extension Locations
 
 - project scope: `.agents/pm/extensions/<name>/`
@@ -31,6 +64,62 @@ Runtime path overrides:
 - `PM_PATH`: project tracker root override
 - `PM_GLOBAL_PATH`: global profile root override
 
+## Package Sources
+
+`pm install` accepts these package sources:
+
+```bash
+pm install ./local-package
+pm install /absolute/path/to/package
+pm install npm:@scope/package
+pm install npm:package@1.2.3
+pm install https://github.com/org/repo
+pm install --github org/repo/path --ref main
+```
+
+Package roots can expose resources with a `pm` manifest in `package.json`:
+
+```json
+{
+  "name": "my-pm-package",
+  "keywords": ["pm-package"],
+  "pm": {
+    "extensions": ["extensions/my-extension"]
+  }
+}
+```
+
+The SDK exposes this project-management package model through `PM_PACKAGE_RESOURCE_KINDS`, `PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS`, and `readPmPackageManifest`. Package installation activates runtime extension resources. Agent-specific bundles such as prompts, skills, and MCP servers should live in separate agent adapter packages rather than the core `pm` package contract.
+
+When no manifest is present, `pm` discovers conventional extension directories:
+
+- `.agents/pm/extensions/`
+- `extensions/`
+- `.custom/pm-extensions/`
+- `.custom/pm-extension/`
+
+If a package contains multiple extension manifests, install the exact extension path so the managed state has one deterministic package target.
+
+First-party optional packages are shipped as package roots under `packages/`:
+
+```bash
+pm install '*' --project
+pm install all --project
+pm install packages/pm-beads --project
+pm install packages/pm-todos --project
+```
+
+`pm install '*'` and `pm install all` install every bundled first-party package in deterministic alias order. If your shell expands `pm install *`, pm recognizes that expansion and treats it as the same bundled-package install-all request.
+
+Compatibility aliases remain available:
+
+```bash
+pm install beads --project
+pm install todos --project
+```
+
+Those aliases install package-shipped extension sources. They are then tracked in managed package state and can be refreshed with `pm upgrade --packages-only`.
+
 ## Manifest Contract
 
 ### Manifest v1 (supported)
@@ -184,13 +273,13 @@ pm extension --doctor --project --detail deep --trace
 Management commands:
 
 ```bash
-pm extension --explore
-pm extension --manage --project
-pm extension --manage --project --probe-runtime
-pm extension --manage --project --adopt-unmanaged
-pm extension --activate my-extension --project
-pm extension --deactivate my-extension --project
-pm extension --uninstall my-extension --project
+pm package explore
+pm package manage --project
+pm package manage --project --runtime-probe
+pm package manage --project --fix-managed-state
+pm package activate my-extension --project
+pm package deactivate my-extension --project
+pm package uninstall my-extension --project
 ```
 
 Common warning prefixes:
@@ -214,7 +303,7 @@ Common warning prefixes:
 
 ```bash
 pm contracts --json
-pm extension --doctor --project --detail summary --strict-exit
+pm package doctor --project --detail summary --strict-exit
 ```
 
 6. Resolve warnings before enforcing `mode=enforce` and `trust_mode=enforce`.
@@ -726,9 +815,9 @@ pm extension scaffold ./my-extension
 Install:
 
 ```bash
-pm extension install ./my-extension --project
-pm extension install github.com/unbraind/pm-cli/.agents/pm/extensions/todos --project
-pm extension --install --project todos
+pm package install ./my-package --project
+pm package install github.com/unbraind/pm-cli/packages/pm-todos --project
+pm install todos --project
 ```
 
 Inspect and manage:
@@ -898,7 +987,7 @@ pm health --check-only
 
 ## Bundled Managed Extensions
 
-`pm-cli` ships bundled extension sources that are not auto-installed:
+`pm-cli` ships optional first-party package roots that are not auto-installed:
 
 | Alias | Commands after install | Purpose |
 |-------|------------------------|---------|
@@ -908,16 +997,10 @@ pm health --check-only
 Install:
 
 ```bash
-pm extension --install --project beads
-pm extension --install --project todos
+pm install beads --project
+pm install todos --project
 ```
 
 ## Starter Extension
 
 See [examples/starter-extension](examples/starter-extension/README.md) for a compact extension that demonstrates all capability categories through the public SDK.
-
-## Pi Wrapper
-
-The Pi wrapper source is `.pi/extensions/pm-cli/index.ts`. It is an agent wrapper, not a runtime extension managed by `pm extension`.
-
-Use [AGENTS.md](../AGENTS.md) for repository-specific Pi wrapper operating rules.

package/docs/QUICKSTART.md

@@ -23,10 +23,10 @@ pm --version
 For updates, use the registry package again:
 
 ```bash
-npm install -g @unbrained/pm-cli@latest
+pm upgrade --cli-only
 ```
 
-Do not use the GitHub git URL as the normal global update path. If a previous git-sourced install left a stale `pm` shim, run `bash scripts/install.sh --repair` from a checkout or uninstall the package before reinstalling from npm.
+`pm upgrade` uses `npm install -g @unbrained/pm-cli@latest` for the CLI/SDK and can also refresh installed pm packages. Do not use the GitHub git URL as the normal global update path. If a previous git-sourced install left a stale `pm` shim, run `pm upgrade --cli-only --repair`, run `bash scripts/install.sh --repair` from a checkout, or uninstall the package before reinstalling from npm.
 
 For one-off use:
 
@@ -34,6 +34,14 @@ For one-off use:
 npx @unbrained/pm-cli --help
 ```
 
+Optional first-party packages are installable on demand:
+
+```bash
+pm install '*' --project
+pm install all --project
+pm package doctor --project --detail summary
+```
+
 ## Initialize a Repository
 
 ```bash

package/docs/README.md

@@ -21,8 +21,7 @@ pm guide release --json
 | New user | [Quickstart](QUICKSTART.md) | [Command Reference](COMMANDS.md) |
 | Coding agent | [Agent Guide](AGENT_GUIDE.md) | [Configuration](CONFIGURATION.md), then command help |
 | Maintainer | [Contributing](../CONTRIBUTING.md) | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.md) |
-| Extension author | [Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
-| Pi user | [Pi Package](PI_PACKAGE.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
+| Package author | [Packages and Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
 | Codex user | [Codex Plugin](CODEX_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
 | Machine client | `pm guide commands` | [Command Reference](COMMANDS.md#machine-contracts), then `pm contracts --json` |
 
@@ -34,9 +33,8 @@ pm guide release --json
 - [Configuration](CONFIGURATION.md) - settings, storage formats, output, search, validation, and environment variables.
 - [Testing](TESTING.md) - sandbox-safe local tests and linked-test orchestration.
 - [Architecture](ARCHITECTURE.md) - contributor internals: storage, mutation flow, search, extensions, and command contracts.
-- [Extensions](EXTENSIONS.md) - runtime extension lifecycle and API reference.
+- [Packages and Extensions](EXTENSIONS.md) - package install workflows, runtime extension lifecycle, and API reference.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
-- [Pi Package](PI_PACKAGE.md) - official Pi package install, native tool, skills, prompts, and workflows.
 - [Codex Plugin](CODEX_PLUGIN.md) - native MCP plugin install, tools, skills, and safety notes.
 - [Releasing](RELEASING.md) - maintainer release checklist and failure handling.
 - [starter extension](examples/starter-extension/README.md) - compact extension scaffold reference.
@@ -49,7 +47,7 @@ pm guide release --json
 | `commands` | [Command Reference](COMMANDS.md), [Configuration](CONFIGURATION.md) |
 | `workflows` | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md) |
 | `sdk` | [SDK](SDK.md), [Architecture](ARCHITECTURE.md) |
-| `extensions` | [Extensions](EXTENSIONS.md), [starter extension](examples/starter-extension/README.md) |
+| `extensions`, `packages` | [Packages and Extensions](EXTENSIONS.md), [starter extension](examples/starter-extension/README.md) |
 | `skills` | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/*` |
 | `harnesses` | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/HARNESS_COMPATIBILITY.md` |
 | `release` | [Releasing](RELEASING.md), [CHANGELOG](../CHANGELOG.md) |
@@ -68,7 +66,7 @@ Community files:
 2. Use [Command Reference](COMMANDS.md) for command families, not exhaustive flag memory.
 3. Use `pm <command> --help --json` or `pm contracts --command <name> --flags-only --json` for exact flags.
 4. Use [Architecture](ARCHITECTURE.md) only when changing internals or debugging behavior.
-5. Use [SDK](SDK.md) and [Extensions](EXTENSIONS.md) only when authoring or troubleshooting extensions.
+5. Use [SDK](SDK.md) and [Packages and Extensions](EXTENSIONS.md) only when authoring or troubleshooting packages/extensions.
 
 ## Tracker References
 

package/docs/SDK.md

@@ -29,9 +29,11 @@ npm install @unbrained/pm-cli
 - `PM_CORE_COMMAND_NAMES`
 - `PM_TOOL_ACTIONS`
 - `PM_TOOL_PARAMETERS_SCHEMA`
-- `PM_PI_TOOL_PARAMETERS_SCHEMA`
+- `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`
 - `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
 
+`PM_TOOL_ACTIONS` includes the package lifecycle actions and `upgrade`, so agents and apps can discover `pm upgrade` through `pm contracts` instead of hard-coding flags.
+
 ### Runtime contract constants
 
 - `PM_EXTENSION_CAPABILITY_CONTRACTS`
@@ -91,7 +93,7 @@ Use runtime contracts for extension-aware schemas:
 ```bash
 pm contracts --json
 pm contracts --schema-only --json
-pm contracts --command extension --flags-only --json
+pm contracts --command package --flags-only --json
 pm contracts --action create --schema-only --json
 ```
 
@@ -101,7 +103,7 @@ Minimal script pattern:
 import { PM_TOOL_ACTION_PARAMETER_CONTRACTS, isPmToolAction } from "@unbrained/pm-cli/sdk";
 import { spawnSync } from "node:child_process";
 
-const action = "extension-reload";
+const action = "package-reload";
 if (!isPmToolAction(action)) throw new Error("Unsupported action");
 const contract = PM_TOOL_ACTION_PARAMETER_CONTRACTS[action];
 console.log(contract.required, contract.optional);
@@ -174,7 +176,7 @@ npm install @unbrained/pm-cli
 - `PM_CORE_COMMAND_NAMES`
 - `PM_TOOL_ACTIONS`
 - `PM_TOOL_PARAMETERS_SCHEMA`
-- `PM_PI_TOOL_PARAMETERS_SCHEMA`
+- `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`
 - `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
 
 ### Extension Runtime Contract Constants
@@ -310,7 +312,7 @@ Command/action contract exports:
 - `PM_CORE_COMMAND_NAMES`
 - `PM_TOOL_ACTIONS`
 - `PM_TOOL_PARAMETERS_SCHEMA`
-- `PM_PI_TOOL_PARAMETERS_SCHEMA`
+- `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`
 - `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
 
 Extension runtime contract exports:
@@ -353,7 +355,7 @@ export default defineExtension({
       description: "Collect release readiness diagnostics.",
       intent: "provide deterministic audit payloads for CI gates",
       examples: ["pm release audit --strict"],
-      failure_hints: ["Run pm extension --doctor --detail deep --trace on activation failures."],
+      failure_hints: ["Run pm package doctor --detail deep --trace on activation failures."],
       flags: [{ long: "--strict", description: "Enable strict gate mode." }],
       run: async (context) => ({
         ok: true,
@@ -372,7 +374,7 @@ Use runtime `pm contracts` for extension-aware schemas:
 ```bash
 pm contracts --json
 pm contracts --schema-only --json
-pm contracts --command extension --flags-only --json
+pm contracts --command package --flags-only --json
 pm contracts --action create --schema-only --json
 ```
 
@@ -402,7 +404,7 @@ Recommended gate sequence:
 ```bash
 pnpm build
 pm contracts --schema-only --json > /tmp/pm-contracts.json
-pm extension --doctor --project --detail summary --strict-exit
+pm package doctor --project --detail summary --strict-exit
 node scripts/run-tests.mjs test -- tests/unit/contracts-command.spec.ts
 node scripts/run-tests.mjs coverage
 ```
@@ -411,11 +413,9 @@ Reference workflow file:
 
 - `docs/examples/ci/github-actions-pm-extension-gate.yml`
 
-## Pi / Tooling Compatibility
-
-For provider-safe schemas, use `PM_PI_TOOL_PARAMETERS_SCHEMA`. It is flat, non-`oneOf`, and designed for tool providers that reject advanced schema constructs.
+## Tooling Compatibility
 
-The bundled Pi wrapper (`.pi/extensions/pm-cli/index.js`) consumes this schema directly to reduce contract drift.
+For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat, non-`oneOf`, and designed for tool providers that reject advanced schema constructs. Agent-specific adapters should consume this SDK export from their own packages instead of adding agent runtime code to the main `pm` CLI.
 
 ## Related Docs
 
@@ -460,6 +460,10 @@ Common authoring exports:
 - `EXTENSION_CAPABILITY_CONTRACT`
 - `EXTENSION_CAPABILITY_CONTRACT_VERSION`
 - `EXTENSION_CAPABILITY_LEGACY_ALIASES`
+- `PM_PACKAGE_RESOURCE_KINDS`
+- `PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS`
+- `readPmPackageManifest`
+- `collectPackageExtensionDirectories`
 - `PM_CORE_COMMAND_NAMES`
 - `PM_TOOL_ACTIONS`
 - `PM_TOOL_PARAMETERS_SCHEMA`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.5.11",
+  "version": "2026.5.12",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -48,16 +48,15 @@
     "docs/**",
     ".claude-plugin/**",
     "plugins/**",
-    ".pi/**",
-    ".agents/skills/**",
-    ".agents/pm/extensions/**",
+    "packages/pm-beads/**",
+    "packages/pm-todos/**",
     "scripts/install.sh",
     "scripts/install.ps1",
     "marketplace.json"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc -p tsconfig.packages.json",
     "start": "node dist/cli.js",
     "dev": "tsx src/cli.ts",
     "test": "node scripts/run-tests.mjs test",
@@ -88,36 +87,19 @@
     "git-native",
     "typescript",
     "task-tracker",
-    "coding-agents",
-    "pi-package",
-    "pi-extension"
+    "coding-agents"
   ],
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
-  "pi": {
-    "extensions": [
-      "./.pi/extensions/pm-cli/index.js"
-    ],
-    "skills": [
-      "./.pi/skills"
-    ],
-    "prompts": [
-      "./.pi/prompts"
-    ]
-  },
   "engines": {
     "node": ">=20"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
   "peerDependenciesMeta": {
-    "@earendil-works/pi-coding-agent": {
-      "optional": true
-    },
     "typebox": {
       "optional": true
     }

package/packages/pm-beads/README.md

@@ -0,0 +1,10 @@
+# pm Beads Package
+
+First-party pm package for importing Beads JSONL records.
+
+```bash
+pm install ./packages/pm-beads --project
+pm beads import --file .beads/issues.jsonl
+```
+
+The package exposes the `beads import` extension command through the `pm.extensions` package manifest. Runtime sources are authored in TypeScript and shipped with JavaScript entry artifacts for Node extension loading.

package/{.agents/pm → packages/pm-beads}/extensions/beads/index.js

@@ -1,7 +1,8 @@
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+const CURRENT_EXTENSION_ROOT = path.dirname(fileURLToPath(import.meta.url));
 
 export const manifest = {
   name: "builtin-beads-import",
@@ -48,17 +49,31 @@ function resolvePackageRootCandidates() {
 async function loadRuntimeModule() {
   const attempted = [];
   for (const packageRoot of resolvePackageRootCandidates()) {
-    const modulePath = path.join(packageRoot, ".agents", "pm", "extensions", "beads", "runtime.js");
-    attempted.push(modulePath);
-    try {
-      return await import(pathToFileURL(modulePath).href);
-    } catch {
-      // Try the next package-root candidate.
+    const modulePaths = [
+      path.join(packageRoot, ".agents", "pm", "extensions", "beads", "runtime.js"),
+      path.join(packageRoot, "packages", "pm-beads", "extensions", "beads", "runtime.js"),
+    ];
+    for (const modulePath of modulePaths) {
+      attempted.push(modulePath);
+      try {
+        return await import(pathToFileURL(modulePath).href);
+      } catch {
+        // Try the next package-root candidate.
+      }
     }
   }
+
+  const localRuntimePath = path.join(CURRENT_EXTENSION_ROOT, "runtime.js");
+  attempted.push(localRuntimePath);
+  try {
+    return await import(pathToFileURL(localRuntimePath).href);
+  } catch {
+    // Fall through to the diagnostic below.
+  }
+
   throw new Error(
-    "Unable to resolve bundled beads extension runtime module. " +
-      `Tried: ${attempted.join(", ")}. Ensure PM_CLI_PACKAGE_ROOT points to an installed pm package root.`,
+    "Unable to resolve packaged beads extension runtime module. " +
+      `Tried: ${attempted.join(", ")}. Ensure the installed extension includes runtime.js or PM_CLI_PACKAGE_ROOT points to an installed pm package root.`,
   );
 }