@unbrained/pm-cli 2026.6.22 → 2026.6.24

package/docs/COMMANDS.md

@@ -65,6 +65,7 @@ pm package                     # bare command defaults to --explore (list instal
 pm install '*' --project
 pm package catalog --project
 pm install npm:@scope/pm-package --project
+pm package describe --project   # by-name surface map of every loaded package
 pm package doctor --project --detail summary
 pm upgrade --dry-run
 pm upgrade --packages-only

package/docs/EXTENSIONS.md

@@ -87,7 +87,7 @@ Package roots declare resources in `package.json` under `pm`:
 
 Installation activates `pm.extensions`. `pm.docs`, `pm.examples`, `pm.assets`, and `pm.prompts` are catalog metadata (metadata-only — they are discovered and surfaced in the catalog but not executed). Declare agent-facing prompt/slash-command markdown under `pm.prompts` and non-code assets (images, skills, fixtures) under `pm.assets`; their conventional roots are `prompts/` (also `.agents/pm/prompts/`) and `assets/` (also `.agents/pm/assets/`).
 
-`pm package init` emits a root extension (`"extensions": ["."]`) so local package installs can activate without dependency bootstrapping. The default `--capability commands` scaffold registers a starter command and a colocated `node:test` suite. `--capability hooks` keeps the starter command and adds an `after_command` lifecycle hook plus SDK testing coverage with `assertRegisteredHook` and `runRegisteredHookForTest`, giving package authors a runnable template for reacting to pm mutations when project management is context management. `--capability search` keeps the starter command and adds a deterministic search provider/vector-store adapter pair plus SDK tests with `assertRegisteredSearchProvider`, `assertRegisteredVectorStoreAdapter`, `runRegisteredSearchProviderForTest`, and `runRegisteredVectorStoreAdapterForTest`, giving retrieval packages a copyable context-management primitive without external services. `--capability importers` keeps the starter command and adds paired import/export command registrations plus SDK tests with `assertRegisteredImporter`, `assertRegisteredExporter`, `runRegisteredImporterForTest`, and `runRegisteredExporterForTest`, giving integration packages a copyable context-movement primitive for synchronizing external project systems; the generated manifest declares both `importers` and `schema` because the starter includes schema-governed flag metadata. Starter manifests use the same least-privilege policy metadata as pure first-party command packages: `trusted: true`, `sandbox_profile: "strict"`, and explicit `false` permissions for `fs_read`, `fs_write`, `network`, `env_read`, `env_write`, and `process_spawn`. Larger packages may point at nested extension directories after declaring runtime dependencies, relaxing only the permissions they actually need, and validating with `pm package doctor`.
+`pm package init` emits a root extension (`"extensions": ["."]`) authored fully in TypeScript (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon)): a typed `index.ts`, a strict `tsconfig.json`, and `build`/`test` scripts, with the manifest `entry` pointing at the compiled `./index.js`. Run `npm install && npm run build` to produce that entry before `pm install`. The generated README shows how to author exported command/hook definitions with the SDK [define* builders](../.agents/pm/decisions/pm-3mph.toon). The default `--capability commands` scaffold registers a starter command and a colocated `node:test` suite. `--capability hooks` keeps the starter command and adds an `after_command` lifecycle hook plus SDK testing coverage with `assertRegisteredHook` and `runRegisteredHookForTest`, giving package authors a runnable template for reacting to pm mutations when project management is context management. `--capability search` keeps the starter command and adds a deterministic search provider/vector-store adapter pair plus SDK tests with `assertRegisteredSearchProvider`, `assertRegisteredVectorStoreAdapter`, `runRegisteredSearchProviderForTest`, and `runRegisteredVectorStoreAdapterForTest`, giving retrieval packages a copyable context-management primitive without external services. `--capability importers` keeps the starter command and adds paired import/export command registrations plus SDK tests with `assertRegisteredImporter`, `assertRegisteredExporter`, `runRegisteredImporterForTest`, and `runRegisteredExporterForTest`, giving integration packages a copyable context-movement primitive for synchronizing external project systems; the generated manifest declares both `importers` and `schema` because the starter includes schema-governed flag metadata. Starter manifests use the same least-privilege policy metadata as pure first-party command packages: `trusted: true`, `sandbox_profile: "strict"`, and explicit `false` permissions for `fs_read`, `fs_write`, `network`, `env_read`, `env_write`, and `process_spawn`. Larger packages may point at nested extension directories after declaring runtime dependencies, relaxing only the permissions they actually need, and validating with `pm package doctor`.
 
 Package tests can pair `readPmPackageManifest(packageRoot)` with
 `assertPackageManifest(manifest, { resources: ... })` from
@@ -112,7 +112,7 @@ Runtime path overrides:
 - `PM_PATH`: project tracker root
 - `PM_GLOBAL_PATH`: global profile root
 
-A minimal standalone extension has a `manifest.json` and an import-free entrypoint. Standalone entries are loaded by file URL from the extension directory, so they should not import `@unbrained/pm-cli` unless the extension is installed as a package with its own dependencies.
+Extensions are authored fully in TypeScript (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon)): a minimal standalone extension has a `manifest.json` and a TypeScript `index.ts` entrypoint compiled to the `./index.js` the loader imports by file URL. Author against the SDK types with `import type { ExtensionApi }` — the type-only import is erased at compile time, so the emitted `index.js` carries **no runtime import** of `@unbrained/pm-cli` (standalone entries are loaded outside any `node_modules`, so a runtime SDK import would fail). Compile with `npx tsc` after installing `typescript` and `@unbrained/pm-cli` for the type resolution.
 
 ```json
 {
@@ -136,9 +136,10 @@ A minimal standalone extension has a `manifest.json` and an import-free entrypoi
 }
 ```
 
-```js
-/** @param {import("@unbrained/pm-cli/sdk").ExtensionApi} api */
-export function activate(api) {
+```ts
+// index.ts — `import type` is erased at compile; the emitted index.js has no runtime import.
+import type { ExtensionApi } from "@unbrained/pm-cli/sdk";
+export function activate(api: ExtensionApi): void {
   api.registerCommand({
     name: "hello",
     description: "Print a deterministic hello payload.",
@@ -151,9 +152,9 @@ export function activate(api) {
 }
 ```
 
-Package-backed extensions can use the SDK helper after declaring `@unbrained/pm-cli` in `package.json` and installing dependencies. Registry installs satisfy that SDK import from the running host CLI instead of downloading a nested CLI copy into each project extension directory, so package authors can declare `@unbrained/pm-cli` as a peer dependency without adding the CLI's own telemetry/runtime dependencies to every workspace. Use this shape for packages published to npm or installed from a package root:
+Package-backed extensions can also import the SDK's runtime helpers (e.g. `defineExtension`, `composeExtension`) after declaring `@unbrained/pm-cli` in `package.json` and installing dependencies. Registry installs satisfy that SDK import from the running host CLI instead of downloading a nested CLI copy into each project extension directory, so package authors can declare `@unbrained/pm-cli` as a peer dependency without adding the CLI's own telemetry/runtime dependencies to every workspace. Use this shape for packages published to npm or installed from a package root:
 
-```js
+```ts
 import { defineExtension } from "@unbrained/pm-cli/sdk";
 
 export default defineExtension({
@@ -196,7 +197,7 @@ Rules:
 - `manifest_version` is an optional integer identifying the manifest schema generation. Runtime contracts currently support manifest versions `1` and `2`, and first-party runnable examples use `2`. First-party packages declare it; the manifest governance test requires it on every first-party package.
 - `pm_min_version` is an inclusive minimum pm CLI version. If the running CLI is older, discovery emits `extension_pm_min_version_unmet:<layer>:<name>:required=<version>:current=<version>` and skips the extension before import.
 - `pm_max_version` is an optional inclusive maximum pm CLI version (the upper compatibility bound). If the running CLI is newer than this value, discovery emits `extension_pm_max_version_exceeded:<layer>:<name>:allowed=<version>:current=<version>` and skips the extension before import. Use it to stop a CLI major release from loading a stale package that would crash at activation. Operators can temporarily set `extensions.policy.pm_max_version_exceeded_mode` to `"warn"` (or `{ "project": "warn" }`) during controlled upgrade windows; the default remains `"block"`.
-- Both bounds share the same warning-code shapes: `*_invalid` blocks, `*_unchecked` allows with a warning, and `extension_pm_min_version_unmet` / `extension_pm_max_version_exceeded` blocks unless the max-version warn mode is enabled.
+- Both bounds share the same warning-code shapes: `*_invalid` blocks, `*_unchecked` allows with a warning, and `extension_pm_min_version_unmet` / `extension_pm_max_version_exceeded` blocks unless the max-version warn mode is enabled. Verify the supported window at author time — before publishing — with the `checkExtensionManifestCompatibility` SDK helper (or its throwing `assertExtensionManifestCompatible` test guard), which mirrors these exact outcomes against a target pm version. To check the version window, the blueprint lint, and the synthesized manifest in one call, use the `preflightExtension` capstone (or its throwing `assertExtensionPreflight` CI guard).
 - An empty-string or non-string `pm_min_version`/`pm_max_version` makes the whole manifest malformed (`extension_manifest_invalid:<layer>:<name>`). Omit the field instead of leaving it blank.
 - Optional `engines.pm` and `engines.node` metadata is accepted for tooling, but `pm_min_version`/`pm_max_version` are the loader-enforced compatibility fields.
 - Declare only capabilities the extension actually uses. Declaring a capability it never registers against is over-broad: `pm package doctor` emits an advisory `extension_capability_unused:<layer>:<name>:<capability>` warning (never blocking) so you can trim the manifest, while the inverse — registering a surface whose capability is undeclared — is the blocking `extension_capability_missing` activation failure. Catch over-declaration earlier with the `assertExtensionCapabilityUsage` SDK testing helper.
@@ -287,7 +288,7 @@ Doctor JSON also includes `triage.collision_plan` with grouped surfaces, ranked
 
 Use the public SDK barrel. Do not deep-import from `src/core` or `dist/core`.
 
-```js
+```ts
 import { defineExtension } from "@unbrained/pm-cli/sdk";
 ```
 
@@ -334,11 +335,12 @@ surface guarantees.
 
 ## Lifecycle Commands
 
-Explore installed runtime entries:
+Explore installed runtime entries, or describe exactly what each loaded package registers (commands, hooks, item types, providers, overrides) as a by-name surface map:
 
 ```bash
 pm package explore --project
-pm package explore --project --json
+pm package describe --project          # every loaded package
+pm package describe my-extension       # one package's surface map
 ```
 
 Run diagnostics:
@@ -414,14 +416,16 @@ If a package-owned command is invoked before installation, usage guidance includ
 
 Third-party packages should import only stable public SDK subpaths:
 
-```js
+```ts
 import { defineExtension, createPmCliExpectedError } from "@unbrained/pm-cli/sdk";
-import { activateExtensionForTest, assertRegisteredCommandContract } from "@unbrained/pm-cli/sdk/testing";
+import { createExtensionTestHarness, activateExtensionForTest } from "@unbrained/pm-cli/sdk/testing";
 ```
 
 Use `createPmCliExpectedError(message, { exitCode, context })` for expected user/action failures from package commands. It creates an `Error` named `PmCliError` with a structural `exitCode`, so separately installed package code still gets expected-error handling and Sentry filtering.
 
-Use `activateExtensionForTest(module)` in package unit tests when you need an `activation.registrations` or `activation.hooks` object for assertion helpers. Then `runRegisteredCommandForTest(activation.commands, { command })` invokes a registered command handler through pm's real dispatch engine to assert behavior, not just wiring; the matching `runRegisteredHookForTest` (lifecycle hooks), `runRegistered{Parser,Preflight,Command,Renderer,Service}OverrideForTest` (override surfaces), and `runRegistered{SearchProvider,VectorStoreAdapter,Migration,Importer,Exporter}ForTest` (executable registrations — the importer/exporter helpers take the whole `activation` and resolve by name, deriving the command path internally) helpers extend that invoke verb to every other runtime surface. Keep `pm package doctor --project --detail deep --trace` and runtime contracts for integration tests against installed packages.
+Prefer the `define*` builders for exported registration definitions (`defineCommand`, `defineFlag`, `defineSearchProvider`, `defineAfterCommandHook`, and the matching override/import/export/hook helpers; see ADR [pm-3mph](../.agents/pm/decisions/pm-3mph.toon)). They are zero-cost identity functions that preserve object literal types and contextually type function parameters before the definitions reach `api.register*`; runtime validation remains in the loader, and behavior validation remains in `sdk/testing`.
+
+Prefer `createExtensionTestHarness(module, { capabilities })` in package unit tests: it activates the module once and returns a fluent fixture whose `assert*`/`run*` methods are already bound to the right activation sub-registry (so you never thread `activation.registrations` vs `activation.commands` vs `activation.hooks` by hand), plus a `deactivate()` that runs the real teardown engine — e.g. `harness.assertCommandContract({ command })`, `await harness.runCommand({ command })`, `await harness.deactivate()`. The methods do not use `this`, so they are safe to destructure. For finer control, the standalone helpers remain public: `activateExtensionForTest(module)` returns the raw `activation`, then `runRegisteredCommandForTest(activation.commands, { command })` invokes a registered command handler through pm's real dispatch engine to assert behavior, not just wiring; the matching `runRegisteredHookForTest` (lifecycle hooks), `runRegistered{Parser,Preflight,Command,Renderer,Service}OverrideForTest` (override surfaces), and `runRegistered{SearchProvider,VectorStoreAdapter,Migration,Importer,Exporter}ForTest` (executable registrations — the importer/exporter helpers take the whole `activation` and resolve by name, deriving the command path internally) helpers extend that invoke verb to every other runtime surface. Keep `pm package doctor --project --detail deep --trace` and runtime contracts for integration tests against installed packages.
 
 `PM_CLI_PACKAGE_ROOT` is first-party only. Bundled packages in this repository use it to find the running CLI's `dist/sdk/runtime.js` before they are published or installed independently. External packages must not read this environment variable or import from `dist/` or `src/core`; use `@unbrained/pm-cli/sdk`, `@unbrained/pm-cli/sdk/runtime`, and `@unbrained/pm-cli/sdk/testing`. During `pm install npm:<package>`, pm links the installed package's `@unbrained/pm-cli` dependency back to the running host CLI so SDK imports resolve without a duplicate nested CLI install.
 

package/docs/SDK.md

@@ -36,6 +36,13 @@ Source of truth:
 Common authoring exports:
 
 - `defineExtension`
+- `composeExtension` / `deriveExtensionCapabilities`
+- `mergeExtensionBlueprints` (combine partial blueprints into one for modular authoring)
+- `composeExtensionPackage` (author-once capstone: returns both the module and its synthesized manifest)
+- `synthesizeExtensionManifest` (generate a complete least-privilege manifest from a blueprint)
+- `describeExtensionBlueprint` (static surface map of a blueprint) / `lintExtensionBlueprint` (author-time preflight)
+- `checkExtensionManifestCompatibility` (author-time `pm_min_version`/`pm_max_version` check against a target pm version)
+- `preflightExtension` (one-call capstone: lint + manifest synthesis + version-compat in a single consolidated report)
 - `EXTENSION_CAPABILITIES`
 - `EXTENSION_CAPABILITY_CONTRACT`
 - `EXTENSION_CAPABILITY_CONTRACT_VERSION`
@@ -48,6 +55,14 @@ Common authoring exports:
 - `createPmCliExpectedError`
 - `isPmCliExpectedError`
 
+Registration builders (`define*`, zero-cost identity — see [Authoring Builders](#authoring-builders)):
+
+- `defineCommand` / `defineFlag` / `defineItemType` / `defineItemField` / `defineMigration`
+- `defineSearchProvider` / `defineVectorStoreAdapter`
+- `defineCommandOverride` / `defineParserOverride` / `definePreflightOverride` / `defineServiceOverride` / `defineRendererOverride`
+- `defineImporter` / `defineExporter`
+- `defineBeforeCommandHook` / `defineAfterCommandHook` / `defineOnWriteHook` / `defineOnReadHook` / `defineOnIndexHook`
+
 Package manifest exports:
 
 - `PM_PACKAGE_RESOURCE_KINDS` (`extensions`, `docs`, `examples`, `assets`, `prompts`)
@@ -73,6 +88,7 @@ Command/action contract exports:
 
 Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 
+- `createExtensionTestHarness`
 - `activateExtensionForTest`
 - `deactivateExtensionForTest`
 - `runRegisteredCommandForTest`
@@ -105,6 +121,26 @@ Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 - `assertRegisteredServiceOverride`
 - `assertRegisteredMigration`
 - `assertExtensionCapabilityUsage`
+- `assertExtensionBlueprint` (throwing preflight; pairs with `lintExtensionBlueprint`)
+- `assertExtensionManifestMatchesBlueprint` (strict manifest↔blueprint capability guard)
+- `assertExtensionManifestCompatible` (throwing version-bound guard; pairs with `checkExtensionManifestCompatibility`)
+- `assertExtensionPreflight` (one-line throwing capstone over `preflightExtension`; replaces chaining the three asserts above)
+- `describeExtensionActivation`
+- `describeExtensionBlueprint` / `lintExtensionBlueprint` (also surfaced here for the full author → describe → preflight → test loop)
+
+`createExtensionTestHarness(module, options)` is the recommended entry point and
+the ergonomic capstone over every standalone helper below: it activates the
+module once and returns a fluent `ExtensionTestHarness` whose `assert*`/`run*`
+methods are pre-bound to the correct activation sub-registry, so a package author
+never threads `activation.registrations` vs `activation.commands` vs
+`activation.hooks` (etc.) by hand — picking the wrong one is a common footgun that
+surfaces as a confusing `available: (none)` error. Write
+`const ext = await createExtensionTestHarness(module, { capabilities: ["commands"] })`,
+then `ext.assertCommandContract({ command })`, `await ext.runCommand({ command })`,
+and `await ext.deactivate()`. The methods do not use `this`, so they remain safe
+to destructure (`const { runCommand } = ext;`), and the raw `ext.activation`
+stays public as an escape hatch to the standalone helpers for any surface a
+convenience method does not cover.
 
 `assertExtensionCapabilityUsage(activation, { declared })` is the least-privilege
 counterpart of the per-surface `assertRegistered*` helpers: pass the same
@@ -208,6 +244,51 @@ importer / exporter is registered (and, for providers and adapters, implements t
 requested operation), so a typo surfaces as a descriptive error rather than a
 silent no-op. All invoke helpers are `async`, so a test always `await`s them.
 
+`describeExtensionActivation(activation, { extensionName })` is the **describe**
+(enumerate-all) verb that complements the `assertRegistered*` (verify-one) and
+`runRegistered*ForTest` (invoke-one) helpers. The activation result already
+carries per-surface *counts*; this returns the *names*. It walks every
+sub-registry once and returns a flat `ExtensionActivationSummary` whose arrays
+are de-duplicated and locale-sorted (except `hooks`, emitted in canonical
+lifecycle order to mirror `hook_counts`) of every registered surface's
+identifiers — command paths, hook kinds, item-type /
+field names, migration ids, importer / exporter / provider / adapter names,
+overridden service names and renderer formats, flag target-commands, and the
+preflight-override count — plus the `capabilities` those surfaces exercise. Two
+uses:
+
+```ts
+import { describeExtensionActivation } from "@unbrained/pm-cli/sdk/testing";
+
+const summary = describeExtensionActivation(activation);
+// Least-privilege check: assert the WHOLE registration surface in one deepEqual.
+assert.deepEqual(summary.commands, ["greet hello"]);
+assert.deepEqual(summary.hooks, ["after_command"]);
+assert.deepEqual(summary.capabilities, ["commands", "hooks"]);
+```
+
+Without `extensionName` the summary unions every extension in the activation;
+with it (matched case-insensitively after trimming, like
+`collectUsedExtensionCapabilities`) only that extension's registrations
+contribute. The three command fields capture distinct dimensions and can
+overlap: `commands` lists definitions declared via `registerCommand(definition)`,
+`command_handlers` lists every command path backed by an extension handler (a
+superset that also includes the synthesized `"<name> import"` / `"<name> export"`
+importer/exporter paths), and `command_overrides` lists built-in commands
+replaced via `registerCommand(name, override)`. For agents, one call returns the
+entire surface instead of traversing fifteen-plus sub-registries — keeping the context
+window lean ("project management = context management").
+
+The same verb is reachable from the CLI and MCP without writing a test:
+`pm extension describe [name]` / `pm package describe [name]` (and `pm_run` with
+`action: "extension"`/`"package"` and `describe: true`) activate the workspace's
+extensions and return each loaded extension's `ExtensionActivationSummary` under
+`details.extensions[].surfaces`, plus a deduplicated `details.union`. Omit the name
+to map every loaded package; pass one to scope to it. This is the agent-facing answer
+to "what does this installed package add to my context?" — distinct from
+`pm package doctor` (errors/policy) and `pm package manage` (update metadata), which
+report only command/action paths, not the full registration surface.
+
 Commander option contract exports:
 
 - `CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS`
@@ -243,6 +324,7 @@ the registration surfaces a package actually exercises at activation):
 Common types:
 
 - `ExtensionApi`
+- `ExtensionActivationSummary`
 - `ExtensionManifest`
 - `ExtensionManifestEngines`
 - `CommandDefinition`
@@ -320,26 +402,18 @@ assertPackageManifest(manifest, {
 ```
 
 Package tests can also assert extension registrations without importing private
-loader internals. Use `activateExtensionForTest` plus the targeted assertion for
-the surface your package owns:
+loader internals. Prefer `createExtensionTestHarness` — its `assert*`/`run*`
+methods bind to the right sub-registry for you:
 
 ```ts
-import {
-  activateExtensionForTest,
-  assertRegisteredCommandContract,
-  assertRegisteredFlags,
-} from "@unbrained/pm-cli/sdk/testing";
+import { createExtensionTestHarness } from "@unbrained/pm-cli/sdk/testing";
 
-const activation = await activateExtensionForTest(extensionModule);
+const ext = await createExtensionTestHarness(extensionModule, { capabilities: ["commands", "schema"] });
 
-assertRegisteredCommandContract(activation.registrations, {
-  command: "incident triage",
-  flags: ["--severity"],
-});
-assertRegisteredFlags(activation.registrations, {
-  targetCommand: "list",
-  flags: ["--incident-filter"],
-});
+ext.assertCommandContract({ command: "incident triage", flags: ["--severity"] });
+ext.assertFlags({ targetCommand: "list", flags: ["--incident-filter"] });
+const { result } = await ext.runCommand({ command: "incident triage", options: { severity: "high" } });
+await ext.deactivate();
 ```
 
 For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat and avoids advanced schema constructs such as root `oneOf`.
@@ -560,6 +634,265 @@ import { createPmCliExpectedError } from "@unbrained/pm-cli/sdk/runtime";
 
 `PM_CLI_PACKAGE_ROOT` is reserved for first-party packages bundled inside this repository. Those packages use it to locate the running CLI's `dist/sdk/runtime.js` before they are installed as independent npm packages. External packages must not depend on `PM_CLI_PACKAGE_ROOT`, `dist/` paths, or `src/core/...`; declare `@unbrained/pm-cli` as a dependency or peer dependency and import the public SDK subpaths instead. When pm installs a registry package, it links that dependency to the running host CLI so the package gets the active SDK without downloading a second CLI copy into the project.
 
+## Authoring Builders
+
+Tracked: [pm-12tj](../.agents/pm/features/pm-12tj.toon) (design rationale: ADR [pm-3mph](../.agents/pm/decisions/pm-3mph.toon)).
+
+The `define*` builders are the authoring half of the `author → register → test`
+loop: they type a registration definition where you write it, before it ever
+reaches `api.register*`. Each is a zero-cost identity function (it returns its
+argument unchanged), exactly like `defineExtension` and the wider
+`defineConfig`/`defineComponent` ecosystem convention — the value is entirely at
+the type level.
+
+pm packages are authored fully in TypeScript (ADR
+[pm-2c28](../.agents/pm/decisions/pm-2c28.toon)). A bare `const cmd = { ... }`
+satisfies the registration types only structurally and widens its literals;
+wrapping it in a builder checks the object against the contract *and* preserves
+the narrow literal types, while inferring the nested handler's `context`
+parameter from the builder signature — the same ergonomics `defineConfig` gives a
+Vite config. It also lets you colocate, export, reuse, and unit-test a definition
+apart from `activate`:
+
+```ts
+import { defineCommand, defineAfterCommandHook } from "@unbrained/pm-cli/sdk";
+import type { ExtensionApi } from "@unbrained/pm-cli/sdk";
+
+// `context` is inferred from the builder signature; the literal name/action are preserved.
+export const greetCommand = defineCommand({
+  name: "greet hello",
+  action: "greet-hello",
+  description: "Say hello.",
+  run: (context) => ({ greeting: `hi ${context.args[0] ?? "world"}` }),
+});
+
+export const auditHook = defineAfterCommandHook((context) => {
+  if (!context.ok) return;
+  // react to context.affected — "project management = context management"
+});
+
+export function activate(api: ExtensionApi): void {
+  api.registerCommand(greetCommand);
+  api.hooks.afterCommand(auditHook);
+}
+```
+
+Object-definition builders (`defineExtensionManifest`, `defineCommand`,
+`defineFlag`, `defineItemType`, `defineItemField`, `defineMigration`,
+`defineSearchProvider`, `defineVectorStoreAdapter`) preserve the narrow literal
+type. `defineExtensionManifest` additionally contract-checks the in-module
+manifest mirror where it is authored and pairs with `deriveExtensionCapabilities`
+(see [Declarative Authoring](#declarative-authoring)). Function-definition
+builders (`defineCommandOverride`, `defineParserOverride`,
+`definePreflightOverride`, `defineServiceOverride`, `defineRendererOverride`,
+`defineImporter`, `defineExporter`, and the five hook builders
+`defineBeforeCommandHook` / `defineAfterCommandHook` / `defineOnWriteHook` /
+`defineOnReadHook` / `defineOnIndexHook`) are non-generic so a bare arrow's
+parameter is contextually typed instead of falling back to `any`. The
+[`assertRegistered*`](#testing-helpers) helpers below verify these same
+definitions once registered.
+
+## Declarative Authoring
+
+Tracked: [pm-iqq0](../.agents/pm/features/pm-iqq0.toon).
+
+`composeExtension` is the capstone of the `author → register → test` loop. Instead
+of hand-wiring each `api.register*` call inside an imperative `activate(api)`
+body — calling the right method, in the right order, without forgetting one —
+describe **what** to register as a plain `ExtensionBlueprint` object and let the
+SDK generate the `activate` for you. Every field is optional; populate the
+surfaces you use (ideally with `define*`-authored definitions) and leave the rest
+out:
+
+```ts
+import { composeExtension, defineCommand, deriveExtensionCapabilities } from "@unbrained/pm-cli/sdk";
+import type { ExtensionBlueprint } from "@unbrained/pm-cli/sdk";
+
+const echo = defineCommand({
+  name: "command-kit echo",
+  action: "command-kit-echo",
+  description: "Echo a message as structured output.",
+  run: (context) => ({ message: context.args.join(" ") }),
+});
+
+const blueprint: ExtensionBlueprint = {
+  commands: [echo],
+  parsers: { "command-kit echo": (context) => ({ options: context.options }) },
+  flags: { list: [{ long: "--kit-note", value_type: "string", value_name: "text" }] },
+};
+
+// The generated `activate` registers commands → overrides → flags → parsers →
+// renderers → services → preflights → item types → item fields → migrations →
+// search providers → vector store adapters → importers → exporters → hooks, then
+// awaits any imperative `activate` you also pass (an escape hatch run last).
+export default composeExtension(blueprint);
+```
+
+`deriveExtensionCapabilities(blueprint)` returns the exact least-privilege
+capability set the blueprint exercises (sorted, de-duplicated), so you can author
+`manifest.json` `capabilities` with zero declared-but-unused or used-but-undeclared
+drift. It is the author-time inverse of the runtime
+[`reconcileExtensionCapabilityUsage`](#capability-requirements) check, and the set
+it returns is the set `composeExtension`'s generated `activate` requires — they
+agree by construction:
+
+```ts
+deriveExtensionCapabilities(blueprint); // ["commands", "parser", "schema"]
+```
+
+The blueprint's record-keyed fields (`commandOverrides`, `flags`, `parsers`,
+`renderers`, `services`) map a routing key to its handler, mirroring the
+two-argument `api.register*` overloads; `hooks` groups the five lifecycle kinds.
+`composeExtension` is a pure assembler: it does not validate definitions —
+per-surface contract enforcement stays in `api.register*` and the loader, so a
+malformed definition surfaces the same activation diagnostic as a hand-written
+`activate`. The bundled first-party packages intentionally keep import-free
+hand-written `activate` bodies so they load in extension-only installs; reach for
+`composeExtension` in npm package-mode authoring where the SDK is a dependency.
+
+### Modular blueprints
+
+Tracked: [pm-high](../.agents/pm/tasks/pm-high.toon),
+[pm-nvgy](../.agents/pm/tasks/pm-nvgy.toon).
+
+A large extension's surface does not have to live in one object. `mergeExtensionBlueprints(...blueprints)`
+combines several partial blueprints into one — a commands module, a search module,
+a hooks module — so each concern is authored (and tested) in its own file and
+assembled at the entry point. Wrap each fragment in `defineExtensionBlueprint(...)`
+so it is contract-checked at its own definition site (with editor completion) —
+the blueprint-level companion to `defineExtension` (a whole module) and
+`defineExtensionManifest` (a manifest):
+
+```ts
+// commands.ts
+import { defineExtensionBlueprint } from "@unbrained/pm-cli/sdk";
+export const commandsModule = defineExtensionBlueprint({
+  commands: [{ name: "kit run", action: "kit-run", run: () => ({ ok: true }) }],
+});
+```
+
+```ts
+// index.ts — NodeNext import specifiers keep the .js extension; they resolve to the .ts source.
+import { composeExtension, mergeExtensionBlueprints } from "@unbrained/pm-cli/sdk";
+import { commandsModule } from "./commands.js";
+import { searchModule } from "./search.js";
+
+export default composeExtension(mergeExtensionBlueprints(commandsModule, searchModule));
+```
+
+The merge is pure, deterministic, and never mutates an input. Each surface combines
+the way its `api.register*` call composes: array surfaces (`commands`, `itemTypes`,
+`migrations`, `searchProviders`, `importers`, …) concatenate in order; `flags`
+concatenates the flag arrays of a shared target command; single-handler records
+(`commandOverrides`, `parsers`, `renderers`, `services`) take last-defined-wins
+precedence on a key collision; `hooks` concatenate per lifecycle kind; imperative
+`activate` hatches chain forward (acquisition order) while `deactivate` hooks chain
+in reverse (LIFO teardown); the `manifest` mirror is last-defined-wins. Because the
+result is an ordinary blueprint, every downstream helper (`deriveExtensionCapabilities`,
+`describeExtensionBlueprint`, `lintExtensionBlueprint`, `preflightExtension`) reads it
+exactly as it would a hand-written one — a command two modules both define survives
+as a duplicate and `lintExtensionBlueprint` flags it. Merging zero blueprints returns
+an empty blueprint (`{}`).
+
+### Generate the manifest (author once)
+
+Tracked: [pm-u5le](../.agents/pm/features/pm-u5le.toon).
+
+`deriveExtensionCapabilities` gives you only the capability set; every other
+manifest field is still yours to hand-write. `synthesizeExtensionManifest(blueprint, identity)`
+closes that gap — it is the **generate** verb that completes the declarative loop
+(`compose → derive → describe/lint → synthesize`). Supply the identity fields a
+blueprint cannot determine (`name`, `version`, `entry`, `priority`, plus any
+optional `engines`/`permissions`/version floors/etc.) and it returns a complete
+`ExtensionManifest` with `capabilities` derived, sorted, and de-duplicated. Write
+the blueprint once; never hand-sync `capabilities` again:
+
+```ts
+import { synthesizeExtensionManifest } from "@unbrained/pm-cli/sdk";
+
+const manifest = synthesizeExtensionManifest(blueprint, {
+  name: "command-kit",
+  version: "1.0.0",
+  entry: "./index.js",
+  priority: 0,
+});
+manifest.capabilities; // ["commands", "parser", "schema"] — derived, not hand-written
+```
+
+Where `defineExtensionManifest` only *types* a manifest you wrote by hand, this
+*generates* it. For the rare surface registered through the imperative `activate`
+escape hatch (invisible to static derivation — e.g. a renderer wired in
+`activate`), pass `additionalCapabilities` and they are unioned in (legacy-alias
+resolved, unknown names dropped). Use the result as the on-disk `manifest.json`
+content or the in-module `manifest` mirror; guard a hand-maintained manifest
+against drift with `assertExtensionManifestMatchesBlueprint` (below).
+
+### Ship both halves (author once)
+
+Tracked: [pm-cn0c](../.agents/pm/tasks/pm-cn0c.toon).
+
+`composeExtension` produces the runtime module; `synthesizeExtensionManifest`
+produces the manifest. `composeExtensionPackage(blueprint, identity)` is the
+author-once capstone that returns both halves of a shippable package from one call,
+with the synthesized manifest set as the module's authoritative in-module mirror —
+so the runtime module and the on-disk `manifest.json` are generated from one source
+and cannot drift:
+
+```ts
+import { composeExtensionPackage } from "@unbrained/pm-cli/sdk";
+
+const { module, manifest } = composeExtensionPackage(blueprint, {
+  name: "command-kit",
+  version: "1.0.0",
+  entry: "./index.js",
+  priority: 0,
+});
+export default module;          // the package entry's default export
+// write `manifest` verbatim as manifest.json — capabilities derived, never hand-synced
+```
+
+It is a pure assembler (no validation, loading, or filesystem access), exactly like
+the two functions it composes; pair it with `preflightExtension` /
+`assertExtensionPreflight` for the author-time verify step. Combined with
+`mergeExtensionBlueprints`, the full declarative loop is: author each concern with
+`define*`, assemble them modularly with `mergeExtensionBlueprints`, then ship both
+halves with `composeExtensionPackage`.
+
+### Author-time introspection and preflight
+
+Tracked: [pm-tlpv](../.agents/pm/features/pm-tlpv.toon),
+[pm-9ect](../.agents/pm/features/pm-9ect.toon),
+[pm-4oio](../.agents/pm/decisions/pm-4oio.toon).
+
+Two pure, no-activation helpers complete the loop, so a blueprint is fully
+inspectable and verifiable before it is ever loaded — the author-time inverse of
+the runtime guardrails (the same discipline as `deriveExtensionCapabilities`
+inverting [`reconcileExtensionCapabilityUsage`](#capability-requirements)):
+
+```ts
+import { describeExtensionBlueprint, lintExtensionBlueprint } from "@unbrained/pm-cli/sdk";
+
+// describeExtensionBlueprint returns the same ExtensionActivationSummary shape as
+// the runtime describeExtensionActivation — but from the blueprint data alone, no
+// activation. It is to the named surfaces what deriveExtensionCapabilities is to
+// the capability set.
+describeExtensionBlueprint(blueprint).command_handlers; // ["command-kit echo", ...]
+
+// lintExtensionBlueprint preflights for the footguns activation would otherwise
+// surface late: a capability a surface exercises but the manifest omits is an
+// `error` (the loader throws extension_capability_missing); a declared-but-unused
+// capability, a duplicate command, a command/override conflict, and a present-but-
+// empty surface are `warning`s. Pass declaredCapabilities or set manifest.capabilities.
+const report = lintExtensionBlueprint(blueprint, { declaredCapabilities: ["commands", "parser", "schema"] });
+report.ok;       // false if any error-severity finding
+report.findings; // [{ code, severity, message, capability?/command?/field? }, ...]
+```
+
+Both read only the declarative data, so the imperative `activate` escape hatch is
+invisible to them — a blueprint that registers everything through that hatch
+summarizes as empty and lints clean. In a package test, `assertExtensionBlueprint`
+(below) turns the lint into a one-line CI guard.
+
 ## Testing Helpers
 
 Package tests can assert registration contracts without depending on Vitest-specific
@@ -607,6 +940,102 @@ guardrails, but it does not discover files or install packages. Use it for unit
 tests of extension registration shape; keep `pm package doctor` and runtime
 contracts in integration tests.
 
+For declarative (`composeExtension`) packages, `assertExtensionBlueprint(blueprint, options?)`
+is the `assert*` family member that preflights the blueprint *without* activating
+it — it runs `lintExtensionBlueprint` and throws if any finding is error-severity
+(today: a capability a surface exercises but the declared set omits, which would
+fail activation with `extension_capability_missing`). It returns the full
+`ExtensionBlueprintLintResult` on success so a test can still inspect advisory
+warnings:
+
+```ts
+import { assertExtensionBlueprint } from "@unbrained/pm-cli/sdk/testing";
+
+// Throws if the blueprint and its declared capabilities have drifted; otherwise
+// returns the lint result (including any non-blocking warnings) for inspection.
+const report = assertExtensionBlueprint(blueprint);
+```
+
+`assertExtensionManifestMatchesBlueprint(manifest, blueprint)` is the **strict**
+bookend to that lenient preflight: where `assertExtensionBlueprint` only fails on
+an *undeclared* capability and merely warns on an unused one, this assertion fails
+on **both** — so a hand-maintained `manifest.json` stays exactly the least-privilege
+set the blueprint requires (assert what `synthesizeExtensionManifest` would
+otherwise generate). Only `capabilities` are reconciled, since that is the one
+manifest field a blueprint determines:
+
+```ts
+import { assertExtensionManifestMatchesBlueprint } from "@unbrained/pm-cli/sdk/testing";
+
+// Throws if manifest.capabilities is missing any capability the blueprint uses, or
+// declares any the blueprint never exercises. Returns { used, declared, missing,
+// unused, findings } on an exact match.
+assertExtensionManifestMatchesBlueprint(manifest, blueprint);
+```
+
+Where the blueprint guards `capabilities`, a manifest's `pm_min_version` /
+`pm_max_version` bounds guard *which pm CLI versions the package supports*.
+Tracker references: `pm-knma` introduced `checkExtensionManifestCompatibility`;
+`pm-hng2` introduced `assertExtensionManifestCompatible`.
+`checkExtensionManifestCompatibility(manifest, { pmVersion, pmMaxVersionExceededMode? })`
+is the author-time inverse of the loader's runtime version gate: it takes the pm
+version you target and returns structured per-bound findings (the same
+`extension_pm_*_version_*` outcomes the loader emits), so you can verify the window
+without installing the package against a real CLI. `assertExtensionManifestCompatible`
+is the throwing CI guard — it fails on a blocking incompatibility (a malformed
+bound, a `pm_min_version` the target is below, or a `block`-mode `pm_max_version`
+the target exceeds) and stays quiet on advisory `*_unchecked` / `*_exceeded_warn`
+warnings, which still load:
+
+```ts
+import { checkExtensionManifestCompatibility } from "@unbrained/pm-cli/sdk";
+import { assertExtensionManifestCompatible } from "@unbrained/pm-cli/sdk/testing";
+
+// Inspect every bound outcome against a target version…
+const report = checkExtensionManifestCompatibility(manifest, { pmVersion: "2026.6.23" });
+//   report.compatible === false, report.findings[0].code === "pm_min_version_unmet", …
+
+// …or fail the package's own suite when a bound would block the load.
+assertExtensionManifestCompatible(manifest, { pmVersion: "2026.6.23" });
+```
+
+Tracked: [pm-ozaf](../.agents/pm/features/pm-ozaf.toon).
+
+`preflightExtension(blueprint, { identity?, target?, declaredCapabilities? })` is the
+author-time **capstone** that runs all of the above in one call — the static analog
+of `createExtensionTestHarness`, which unified the runtime-test helpers. Rather than
+chaining `lintExtensionBlueprint`, `synthesizeExtensionManifest`, and
+`checkExtensionManifestCompatibility` (and reconciling their separate results)
+before publishing, you read one `ExtensionPreflightReport`: the blueprint is always
+linted; when `identity` is given the complete least-privilege manifest is synthesized
+and returned; when `target` is given the synthesized bounds (or, absent an identity,
+the blueprint's in-module `manifest` mirror) are version-checked. The per-stage
+results are exposed unmodified (`report.blueprint` / `report.manifest` /
+`report.compatibility`) alongside a flattened `report.findings` where each entry is
+tagged by `source` (`"blueprint"` | `"compatibility"`); `report.ok` is `false` if any
+stage produced an `error`. `assertExtensionPreflight(blueprint, options?)` is the
+throwing one-line CI guard over it — it fails listing every blocking finding tagged
+`[source:code]` and stays quiet on advisory warnings, returning the full report on
+success:
+
+```ts
+import { preflightExtension } from "@unbrained/pm-cli/sdk";
+import { assertExtensionPreflight } from "@unbrained/pm-cli/sdk/testing";
+
+// Inspect every author-time stage in one report…
+const report = preflightExtension(blueprint, {
+  identity: { name: "command-kit", version: "1.0.0", entry: "./index.js", priority: 0 },
+  target: { pmVersion: "2026.6.23" },
+});
+//   report.manifest.capabilities (derived), report.compatibility.compatible, report.findings[]
+
+// …or guard the whole package in one CI line.
+assertExtensionPreflight(blueprint, {
+  identity: { name: "command-kit", version: "1.0.0", entry: "./index.js", priority: 0 },
+  target: { pmVersion: "2026.6.23" },
+});
+```
+
 Invoke a registered command handler to assert its behavior (not just that it was
 registered). `runRegisteredCommandForTest` dispatches through pm's real engine and
 returns the `CommandHandlerResult`: