@unbrained/pm-cli 2026.6.23 → 2026.6.30

package/docs/SDK.md

@@ -37,7 +37,13 @@ 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)
+- `renderExtensionSurfaceMarkdown` (render a describe summary to a drift-free Markdown reference doc for a package README)
+- `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`
@@ -53,11 +59,29 @@ Common authoring exports:
 Registration builders (`define*`, zero-cost identity — see [Authoring Builders](#authoring-builders)):
 
 - `defineCommand` / `defineFlag` / `defineItemType` / `defineItemField` / `defineMigration`
+- `defineProjectProfile` (archetype bundle of types/statuses/fields/workflows/config/templates/packages — powers `pm profile`)
 - `defineSearchProvider` / `defineVectorStoreAdapter`
 - `defineCommandOverride` / `defineParserOverride` / `definePreflightOverride` / `defineServiceOverride` / `defineRendererOverride`
 - `defineImporter` / `defineExporter`
 - `defineBeforeCommandHook` / `defineAfterCommandHook` / `defineOnWriteHook` / `defineOnReadHook` / `defineOnIndexHook`
 
+Project profiles:
+
+- `defineProjectProfile` / `BUILTIN_PROFILES` / `PROFILE_NAMES` / `resolveProfile` / `listProfiles` / `normalizeProfileName`
+- `describeProjectProfile` (pure composition summary — per-dimension counts plus resolved entry identifiers; the project-profile analogue of `describeExtensionBlueprint`) and `describeProfileComposition`
+- `lintProjectProfile` (pure, tracker-independent author-time consistency check that grades findings `error`/`warning` across every dimension — invalid/duplicate types, statuses, fields; workflows governing undeclared types or referencing undeclared statuses; unknown/invalid config knobs; templates creating undeclared types; empty package specs) and its `ProjectProfileLintReport` / `ProjectProfileLintFinding` types
+- `assertProjectProfile` (the throwing test counterpart: fails on any `error` finding, or on warnings too with `{ strict: true }` — the profile analogue of `assertExtensionBlueprint`)
+- `planProfileApplication` (pure, idempotent diff of a profile against the current tracker state) and its `ProfileApplicationPlan` / `ProfileCurrentState` types
+- The bundled [pm-kanban exemplar](../packages/pm-kanban/README.md) ships a complete archetype as an installable package: it registers the live schema (`Card` type + flow fields) and exports a `ProjectProfileDefinition` the planner can stage, all on public SDK primitives.
+
+Author-time lifecycle: `defineProjectProfile` → `lintProjectProfile` / `assertProjectProfile` (validate before registering) → `api.registerProfile` → `describeProjectProfile` / `planProfileApplication` (preview) → `pm profile apply`. Validate a profile in a package test before it ships:
+
+```ts
+import { assertProjectProfile } from "@unbrained/pm-cli/sdk/testing";
+
+assertProjectProfile(kanbanProfile); // throws on any error finding
+```
+
 Package manifest exports:
 
 - `PM_PACKAGE_RESOURCE_KINDS` (`extensions`, `docs`, `examples`, `assets`, `prompts`)
@@ -113,12 +137,17 @@ Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 - `assertRegisteredVectorStoreAdapter`
 - `assertRegisteredItemField`
 - `assertRegisteredItemType`
+- `assertRegisteredProfile`
 - `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)
+- `renderExtensionSurfaceMarkdown` (render the describe summary to a drift-free Markdown reference; powers `describe --markdown`)
 
 `createExtensionTestHarness(module, options)` is the recommended entry point and
 the ergonomic capstone over every standalone helper below: it activates the
@@ -129,8 +158,13 @@ never threads `activation.registrations` vs `activation.commands` vs
 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`
+`ext.activationSummary()`, `ext.renderMarkdown({ title: "My package" })`, and
+`await ext.deactivate()`. `activationSummary()` returns the same
+`ExtensionActivationSummary` as `describeExtensionActivation(ext.activation)`;
+`renderMarkdown()` feeds that summary through `renderExtensionSurfaceMarkdown`,
+with an optional `extensionName` filter for scoped package docs. The methods do
+not use `this`, so they remain safe to destructure
+(`const { runCommand, renderMarkdown } = 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.
 
@@ -281,6 +315,33 @@ 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.
 
+`renderExtensionSurfaceMarkdown(summary, options?)` is the **render** leg of the
+describe verb: it projects any `ExtensionActivationSummary` to a deterministic
+Markdown reference document — a title heading, a one-line capabilities summary,
+and a section per registered surface. Pipe `describeExtensionBlueprint(blueprint)`
+straight into it during a build or test step and embed the result in your
+README, and the "commands & capabilities" reference can never drift from the
+surface the loader actually registers ("project management = context
+management"). `options.title` / `options.headingLevel` (an integer in `[1, 6]`,
+default `2`; section headings render one level deeper) control nesting, and
+`options.includeEmpty` renders every section (as `_None._`) rather than omitting
+empty ones.
+
+```ts
+import { describeExtensionBlueprint, renderExtensionSurfaceMarkdown } from "@unbrained/pm-cli/sdk";
+
+const reference = renderExtensionSurfaceMarkdown(describeExtensionBlueprint(blueprint), { title: "my-pkg", headingLevel: 2 });
+// → "## my-pkg\n\nCapabilities: `commands`, `schema`\n\n### Commands\n\n- `greet hello`\n…"
+```
+
+The same renderer powers `pm extension describe --markdown` / `pm package
+describe --markdown`, which compose a per-extension section plus a union section
+across every loaded extension. Add `--output docs/package-reference.md` to write
+the generated Markdown directly to a file for README/reference-doc refreshes.
+`--markdown` is a presentation format (it cannot be combined with `--json`);
+MCP `describe` keeps returning the structured summary, which a caller can hand to
+`renderExtensionSurfaceMarkdown` itself.
+
 Commander option contract exports:
 
 - `CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS`
@@ -405,6 +466,8 @@ const ext = await createExtensionTestHarness(extensionModule, { capabilities: ["
 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" } });
+const summary = ext.activationSummary();
+const reference = ext.renderMarkdown({ title: "incident package surfaces" });
 await ext.deactivate();
 ```
 
@@ -420,6 +483,7 @@ For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat
 | `registerItemFields` | `schema` |
 | `registerItemTypes` | `schema` |
 | `registerMigration` | `schema` |
+| `registerProfile` | `schema` |
 | `registerImporter` | `importers` |
 | `registerExporter` | `importers` |
 | `registerParser` | `parser` |
@@ -470,7 +534,7 @@ Manifest:
 {
   "name": "hello",
   "version": "0.1.0",
-  "entry": "./index.js",
+  "entry": "./index.ts",
   "pm_min_version": "2026.5.31",
   "trusted": true,
   "sandbox_profile": "strict",
@@ -494,7 +558,7 @@ Manifest typing also accepts optional `engines` metadata:
 {
   "engines": {
     "pm": ">=2026.5.31",
-    "node": ">=20"
+    "node": ">=22.18"
   }
 }
 ```
@@ -519,7 +583,59 @@ scaffold paired import/export commands with example flag metadata and a runnable
 `node:test` file that exercises `assertRegisteredImporter`,
 `assertRegisteredExporter`, `runRegisteredImporterForTest`, and
 `runRegisteredExporterForTest`; the generated manifest declares both `importers`
-and `schema` because extension flag metadata is schema-governed.
+and `schema` because extension flag metadata is schema-governed. Pass
+`--capability schema` to scaffold a command plus a custom item type, item field,
+and migration (via `registerItemTypes`/`registerItemFields`/`registerMigration`)
+and a runnable `node:test` file that exercises `assertRegisteredItemType`,
+`assertRegisteredItemField`, `assertRegisteredMigration`, and
+`runRegisteredMigrationForTest` — a copyable starting point for modeling a
+project domain. Pass `--capability profile` to scaffold a command plus a complete
+project-profile archetype (item types, statuses, fields, a per-type workflow,
+config, a create template, and package recommendations via `registerProfile`) and
+a `node:test` file exercising the harness-bound `assertProfile` (the public
+`assertRegisteredProfile`); it omits
+`activation.commands` (granted by the same `schema` capability) so the contributed
+profile resolves through `pm profile list/show/apply` and `pm profile apply <name>`
+tailors a fresh tracker in one shot — the broadest customization primitive in one
+copyable starter.
+
+The four override surfaces complete the matrix to one starter per SDK
+registration capability. Pass `--capability renderers` to scaffold a `toon`
+output renderer override (via `registerRenderer`, scoped to its own command so
+other output passes through) with a `node:test` file exercising
+`assertRegisteredRendererOverride` and `runRegisteredRendererOverrideForTest`;
+`--capability parser` for a parser override (via `registerParser`) that rewrites
+the command's parsed options — the starter command declares matching
+`--shout`/`--upper` flags (so the manifest also declares `schema`) and surfaces
+the normalized value, making the override runnable through `pm <command> --shout`
+— exercising `assertRegisteredParserOverride` and
+`runRegisteredParserOverrideForTest`; `--capability preflight` for a preflight
+override (via `registerPreflight`) over pm's pre-run migration/format gate
+decision, exercising `assertRegisteredPreflightOverride` and
+`runRegisteredPreflightOverrideForTest`; and `--capability services` for an
+`output_format` service override (via `registerService`, scoped to its own
+command), exercising `assertRegisteredServiceOverride` and
+`runRegisteredServiceOverrideForTest`.
+
+Every command-bearing variant's generated `manifest.json` also declares
+`activation.commands` — the exact command paths the starter registers — so pm
+activates the package lazily, importing and running `activate` only when an
+invoked command matches. This mirrors every first-party bundled package and is
+the contract authors keep in sync with their registrations: an omitted or stale
+entry means the matching command will not dispatch from the CLI (globally-scoped
+surfaces such as hooks and search providers for built-in search commands still
+activate regardless). The `schema` starter is the deliberate exception: it omits
+`activation.commands` so its custom item type — a global contribution that
+built-in commands like `pm create <type>` must see — activates conservatively for
+every command rather than gating on the package's own commands.
+
+Each `--capability` starter authors an imperative `activate` body. To scaffold the
+declarative `composeExtension` form instead, pass `--declarative` to
+`pm package init` / `pm package scaffold` (it is an init/scaffold flag, package-mode
+only — every `--capability` variant emits its blueprint form, since `composeExtension`
+is a runtime SDK value import that only package-mode authoring links) — see
+[Declarative Authoring](#declarative-authoring). See [EXTENSIONS.md](EXTENSIONS.md)
+for the manifest-field reference.
 
 ## Self-Identity and Lifecycle
 
@@ -637,17 +753,20 @@ argument unchanged), exactly like `defineExtension` and the wider
 `defineConfig`/`defineComponent` ecosystem convention — the value is entirely at
 the type level.
 
-This matters most in **plain-JavaScript packages** (the default `pm package init`
-scaffold). A bare `const cmd = { ... }` is unchecked because JS has no type
-annotations; wrapping it in a builder restores full contract checking and infers
-the nested handler's `context` parameter through the editor's TypeScript language
-service. It also lets you colocate, export, reuse, and unit-test a definition
+pm packages are authored **and loaded** as TypeScript (ADR
+[pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.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`:
 
-```js
+```ts
 import { defineCommand, defineAfterCommandHook } from "@unbrained/pm-cli/sdk";
+import type { ExtensionApi } from "@unbrained/pm-cli/sdk";
 
-// `context` is inferred even though this is a .js file with no annotations.
+// `context` is inferred from the builder signature; the literal name/action are preserved.
 export const greetCommand = defineCommand({
   name: "greet hello",
   action: "greet-hello",
@@ -660,7 +779,7 @@ export const auditHook = defineAfterCommandHook((context) => {
   // react to context.affected — "project management = context management"
 });
 
-export function activate(api) {
+export function activate(api: ExtensionApi): void {
   api.registerCommand(greetCommand);
   api.hooks.afterCommand(auditHook);
 }
@@ -693,8 +812,9 @@ 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:
 
-```js
+```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",
@@ -703,7 +823,7 @@ const echo = defineCommand({
   run: (context) => ({ message: context.args.join(" ") }),
 });
 
-const blueprint = {
+const blueprint: ExtensionBlueprint = {
   commands: [echo],
   parsers: { "command-kit echo": (context) => ({ options: context.options }) },
   flags: { list: [{ long: "--kit-note", value_type: "string", value_name: "text" }] },
@@ -724,7 +844,7 @@ drift. It is the author-time inverse of the runtime
 it returns is the set `composeExtension`'s generated `activate` requires — they
 agree by construction:
 
-```js
+```ts
 deriveExtensionCapabilities(blueprint); // ["commands", "parser", "schema"]
 ```
 
@@ -738,6 +858,124 @@ malformed definition surfaces the same activation diagnostic as a hand-written
 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.
 
+For a generated starting point, `pm package init <path> --declarative` scaffolds
+this loop end to end for any `--capability`: an `index.ts` that authors a
+`defineExtensionBlueprint` blueprint (the capability's surfaces wired through the
+`define*` builders) and exports `composeExtension(blueprint)`, plus an
+`index.test.ts` that guards it with the author-time `assertExtensionPreflight`
+capstone and exercises the composed module through `createExtensionTestHarness`. It
+is package-mode only (`composeExtension` is a runtime SDK value import, so it belongs
+in package-mode authoring where the SDK is a linked dependency, not the import-free
+extension-only starters).
+
+### 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 — the manifest entry; import sibling .ts modules by their real extension (loaded directly via native type stripping).
+import { composeExtension, mergeExtensionBlueprints } from "@unbrained/pm-cli/sdk";
+import { commandsModule } from "./commands.ts";
+import { searchModule } from "./search.ts";
+
+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.ts",
+  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.ts",
+  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),
@@ -749,7 +987,7 @@ inspectable and verifiable before it is ever loaded — the author-time inverse
 the runtime guardrails (the same discipline as `deriveExtensionCapabilities`
 inverting [`reconcileExtensionCapabilityUsage`](#capability-requirements)):
 
-```js
+```ts
 import { describeExtensionBlueprint, lintExtensionBlueprint } from "@unbrained/pm-cli/sdk";
 
 // describeExtensionBlueprint returns the same ExtensionActivationSummary shape as
@@ -793,7 +1031,7 @@ const activation = await activateExtensionForTest({
   manifest: {
     name: "hello-ext",
     version: "0.1.0",
-    entry: "./index.js",
+    entry: "./index.ts",
     priority: 0,
     capabilities: ["commands", "schema"],
   },
@@ -836,6 +1074,86 @@ import { assertExtensionBlueprint } from "@unbrained/pm-cli/sdk/testing";
 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.ts", 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.ts", 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`:
@@ -1034,9 +1352,58 @@ const migration = assertRegisteredMigration(activation.registrations, {
 // migration.definition is the normalized SchemaMigrationDefinition
 ```
 
+### Project profiles (`registerProfile`)
+
+Tracked: [pm-08sv](../.agents/pm/features/pm-08sv.toon).
+
+A **project profile** is the broadest customization primitive a package can ship:
+one declarative `ProjectProfileDefinition` that bundles item types, custom
+statuses, fields, per-type workflows, config knobs, create templates, and package
+recommendations into a single archetype `pm profile apply` stages idempotently.
+The three core archetypes (`agile`/`ops`/`research`) are baked in; a package adds
+its own with `api.registerProfile(profile)` under the `schema` capability:
+
+```ts
+import { defineProjectProfile, type ExtensionApi } from "@unbrained/pm-cli/sdk";
+
+export const kanbanProfile = defineProjectProfile({
+  name: "kanban",
+  title: "Kanban continuous flow",
+  summary: "WIP-limited flow with a verifying stage.",
+  types: [{ name: "Card", folder: "cards" }],
+  statuses: [{ id: "doing", roles: ["active"] }],
+  fields: [{ key: "wip_limit", type: "number", commands: ["create", "update"] }],
+  workflows: [{ type: "Card", allowed_transitions: [["open", "doing"]] }],
+  config: [{ key: "search_provider", value: "bm25", summary: "Offline lexical search." }],
+  templates: [{ name: "card", options: { type: "Card" } }],
+  packages: [{ spec: "templates", reason: "Reusable card shapes." }],
+});
+
+export function activate(api: ExtensionApi): void {
+  api.registerProfile(kanbanProfile);
+}
+```
+
+Once the package is active, the profile resolves by name through `pm profile list`
+(labelled with its source package), `pm profile show <name>`, and
+`pm profile apply <name>` — exactly like a core archetype, with no consumer code.
+Built-in names are reserved: a registered profile that collides with a core name
+(or another package's profile) is ignored with a warning rather than shadowing it.
+Profiles flow through the declarative loop too — `composeExtension({ profiles: [...] })`
+auto-wires `registerProfile`, and `deriveExtensionCapabilities` maps a `profiles`
+surface to `schema`. Prove a profile registered with `assertRegisteredProfile`:
+
+```ts
+import { assertRegisteredProfile } from "@unbrained/pm-cli/sdk/testing";
+
+const { profile } = assertRegisteredProfile(activation.registrations, { profile: "kanban" });
+// profile is the normalized ProjectProfileDefinition
+```
+
 Together these complete the SDK assertion surface: every extension `register*`
-method now has a matching `assertRegistered*` helper, so packages can prove any
-registration without importing private registry internals.
+method (including `registerProfile`) now has a matching `assertRegistered*`
+helper, so packages can prove any registration without importing private registry
+internals.
 
 The three executable registration surfaces add `runRegistered*ForTest` invoke
 helpers on top of those assertions, so a package can exercise the real behavior of

package/docs/TESTING.md

@@ -20,6 +20,7 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ```bash
 pnpm build
+pnpm lint
 pnpm typecheck
 node scripts/run-tests.mjs test
 node scripts/run-tests.mjs coverage
@@ -27,6 +28,17 @@ node scripts/run-tests.mjs coverage
 
 `node scripts/run-tests.mjs` wraps Vitest in temporary tracker roots, then cleans them up.
 
+`pnpm lint` is the local CodeFactor parity check. It layers ESLint rules for
+shipped source, package, plugin, and script surfaces that match the CodeFactor
+maintainability findings this repo tracks (`complexity`,
+`no-unsafe-optional-chaining`, and the relevant `eslint-plugin-unicorn`
+mechanical rules), jscpd duplicate detection across source and tests, and the
+repo-specific `quality:static` gate. The dedicated `quality:static` gate remains
+authoritative for source/exported docstring coverage, orphan-module checks,
+directory-load caps, and the TypeScript-aware duplicate/complexity checks that
+are tailored to pm's source layout; `pnpm lint` delegates to it instead of
+running a second threshold profile.
+
 ## Focused Test Runs
 
 ```bash

package/docs/examples/policy-restricted-extension/README.md

@@ -2,6 +2,12 @@
 
 This example demonstrates governance policy behavior with real registrations.
 
+It is authored **and loaded** as TypeScript (ADR pm-2c28 / pm-m1uz): `index.ts` is
+both the source and the manifest `entry`, imported directly via Node's native type
+stripping — there is no compile step and no committed `index.js`. Edit `index.ts`
+and the change takes effect on the next install/reload; run `npx tsc --noEmit` to
+type-check.
+
 The extension declares:
 
 - `commands` (handler registration)

package/docs/examples/policy-restricted-extension/index.ts

@@ -0,0 +1,40 @@
+/**
+ * @module docs/examples/policy-restricted-extension
+ *
+ * Minimal TypeScript-first reference extension for governance-policy demos. It
+ * registers exactly three surfaces — a command handler, a `beforeCommand` hook,
+ * and an `output_format` service override — so an operator can enforce policy
+ * that keeps the command and hook allowed while blocking the service override
+ * (see the accompanying README).
+ *
+ * As with the starter example, the source is authored in TypeScript against the
+ * published SDK types and is itself the `./index.ts` manifest entry the loader
+ * imports directly via Node's native type stripping (ADR pm-2c28 / pm-m1uz) — no
+ * compile step and no committed `.js`. Typing `activate(api: ExtensionApi)` is
+ * enough for the service override's `context` parameter to be inferred as a
+ * `ServiceOverrideContext`, which is why this handler returns `context.payload`
+ * (the value to format) rather than the whole context object.
+ */
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+import type { ExtensionApi } from "@unbrained/pm-cli/sdk";
+
+export default defineExtension({
+  activate(api: ExtensionApi): void {
+    api.registerCommand({
+      name: "policy demo",
+      action: "policy-demo",
+      description: "Emit a deterministic payload to validate policy-gated activation.",
+      run: async (context) => ({
+        ok: true,
+        command: context.command,
+        source: "policy-restricted-extension",
+      }),
+    });
+
+    api.hooks.beforeCommand(() => {});
+
+    // This registration is intentionally useful for policy demos: an identity
+    // output_format override that returns the formatting payload unchanged.
+    api.registerService("output_format", (context) => context.payload);
+  },
+});

package/docs/examples/policy-restricted-extension/manifest.json

@@ -1,9 +1,9 @@
 {
   "name": "policy-restricted-extension",
   "version": "0.1.0",
-  "entry": "./index.js",
+  "entry": "./index.ts",
   "manifest_version": 2,
-  "pm_min_version": "2026.5.0",
+  "pm_min_version": "2026.6.24",
   "trusted": true,
   "provenance": {
     "source": "docs/examples/policy-restricted-extension",