@webpresso/agent-kit 0.21.3 → 0.21.5

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Webpresso agent-kit Claude Code plugin: blueprints, skills, hooks, MCP server",
-    "version": "0.21.0"
+    "version": "0.21.5"
   },
   "plugins": [
     {
@@ -23,5 +23,5 @@
       ]
     }
   ],
-  "version": "0.21.0"
+  "version": "0.21.5"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "webpresso",
-  "version": "0.21.0",
+  "version": "0.21.3",
   "description": "Webpresso agent-kit: blueprints, skills, lore commit protocol, tech-debt lifecycle",
   "skills": "./skills",
   "commands": "./commands",

package/README.md

@@ -1,8 +1,9 @@
 # @webpresso/agent-kit
 
-> Plug-and-play setup for AI coding agents. Run one command and every agent in
-> the repo gets the same instructions, skills, hooks, planning files, and quality
-> gates. MIT. Experimental v0.x.
+> TypeScript infrastructure for AI-agent-driven development. One `wp` runtime
+> gives agents planning, tests, mutation, e2e, CI, docs, and debt tracking —
+> all summary-first so they keep context, and enforced as contracts so docs,
+> intent, and code can't drift. MIT. Experimental v0.x.
 
 ## Install
 
@@ -25,58 +26,120 @@ If you do not want a global install, run it one-shot instead:
 npm exec --yes --package @webpresso/agent-kit@latest -- wp setup
 ```
 
-`wp setup` is safe to run again. It refreshes the webpresso-owned pieces and
+`wp setup` is safe to run again. It refreshes the webpresso-owned pieces,
+creates the default `base-kit` quality scaffold when files are absent, and
 preserves consumer-owned files.
 
-## What it gives you
+The guarantee is **zero hand-wiring**, not zero local dependencies. Fresh repos
+get starter `tsconfig`, Vitest, Oxlint, Stryker, Playwright, unit-test, and
+file-based e2e smoke assets. Repos still keep authoring-time dependencies that
+their configs and tests import directly.
 
-- **One repo brain** — major coding agents read the same operating contract.
-- **Skills that travel** — repo skills show up across supported agent surfaces.
-- **Hooks that help** — generated hooks steer common work through repo quality gates.
-- **Blueprints by default** — planning files and templates are ready when the task needs them, and Blueprint markdown stays the canonical plan while OMX handoff files remain derived metadata.
-- **Agent-friendly checks** — tests, lint, typecheck, E2E, and audits are easy to run and cite.
-- **Context-efficient evidence by default** — `wp_*` MCP wrappers return
-  compact test/lint/typecheck/audit summaries, and `wp setup` includes `rtk`
-  in its default workstation preset set.
+Default workstation presets are separate from repo bootstrap. `omx`, `omc`,
+`gstack`, `vision`, `rtk`, and `context-mode` are requested by default and
+degrade with explicit skipped/warning output when the matching host or auth is
+unavailable. The repo bootstrap is `base-kit`.
 
-## Why it exists
+### Execution-owned vs authoring-owned dependencies
+
+`wp` now owns **execution** for the generic tool lanes it manages:
+
+- test / mutation
+- e2e
+- lint
+- format
+- typecheck
 
-AI-agent repos usually grow six copies of the same thing:
+That does **not** mean every local devDependency should disappear.
 
-- one instruction file for Claude,
-- another for Codex,
-- another for Cursor,
-- separate hooks,
-- separate skills,
-- separate planning conventions.
+- Keep local dependencies that your repo **imports directly** from tests,
+  config files, or tsconfig types — for example `vitest`,
+  `@playwright/test`, `@testing-library/jest-dom`, or `typescript`.
+- Review execution-only binaries for removal **only if** they were installed
+  just to invoke them locally and nothing imports them directly — for example
+  `oxlint`, `oxfmt`, or `markdownlint-cli2`.
 
-Those copies drift. webpresso makes the repo feel like one product again:
+`wp setup` prints this migration guidance after scaffolding so consumers do not
+accidentally strip authoring-time dependencies just because `wp` can execute
+the tool.
+
+Public install claims are checked against the packed artifact with:
 
 ```bash
-wp setup
+vp run public:consumer-smoke -- --setup-only
 ```
 
-## Why agents keep more useful context
+Use the full smoke without `--setup-only` when you want to install the generated
+starter dependencies and run the generated quality commands.
+
+## What it does
+
+`wp` is the toolkit agents use to do real work in a repo. Every piece is built
+on two properties that make it *agent-grade* rather than yet-another-bundle:
+its output is **summary-first** (agents keep context) and it is **enforced**
+(pre-commit + CI gates, not just available).
+
+### The toolkit
+
+- **Planning** — blueprints: markdown plans with a lifecycle
+  (`wp audit blueprint-lifecycle`) and a dependency-aware task graph.
+  `wp_blueprint_depgraph` returns its dependency graph (nodes + edges), and
+  optional runtime adapters (OMX `/pll`) use those dependencies to run
+  independent tasks in parallel.
+  Authoring now has a structured control plane: `wp_blueprint_put` writes the
+  blueprint from typed input and `wp_blueprint_transition` advances lifecycle
+  state with revision-aware optimistic concurrency. A future MCP Apps editor is
+  explicitly a follow-on enhancement layered on top of those tools, not a
+  separate required write surface. See [`docs/lifecycle.md`](docs/lifecycle.md).
+- **Tests, types, lint** — `wp_test`, `wp_typecheck`, `wp_lint` over your
+  vitest/oxlint setup.
+- **Mutation testing** — `wp audit mutation` (Stryker) catches tests that pass
+  without actually asserting.
+- **End-to-end** — `wp_e2e` runs suite-aware Playwright flows.
+- **CI, locally** — `wp_ci_act` runs your GitHub Actions through `act` behind
+  the repo secret contract.
+- **Docs** — `wp docs lint` and `wp audit docs-frontmatter` keep docs
+  structured and current.
+- **Tech-debt** — `wp tech-debt` tracks debt through a status lifecycle
+  (accepted → needs-remediation → monitoring → resolved), auto-filed from
+  failing audits.
+
+### What makes it agent-grade
+
+- **Summary-first output** — the `wp_*` MCP wrappers return summary-first JSON
+  with clipped raw output and budget metadata (`bytes`, `tokensSaved`), and
+  `wp setup` wires the `rtk` and `context-mode` output-filtering lanes by
+  default (skipped in CI and via `WP_SKIP_RTK=1` / `WP_SKIP_CONTEXT_MODE=1`;
+  never bundled in the package). Agents reason over the failure set, not the
+  thousand-line log. See [`docs/qa-output.md`](docs/qa-output.md).
+- **Enforced as contracts** — `wp audit vision` keeps `VISION.md` current,
+  `wp audit architecture-drift` keeps architecture docs aligned with the
+  implementation they describe, `wp audit bundle-budget` caps client output,
+  and the Lore commit protocol (`wp audit commit-message --require-lore`)
+  records the *why* behind each change. Every audit runs as a `wp_audit` MCP
+  tool **and** as a pre-commit and CI gate — so intent, docs, and code can't
+  silently diverge.
+- **One operating contract, managed for you** — `wp` generates and keeps your
+  `AGENTS.md`, `CLAUDE.md`, and each agent's command, skill, and hook surfaces
+  in sync, emitted through rulesync across every supported runtime (see
+  [`catalog/agent/rules/supported-agent-clis.md`](catalog/agent/rules/supported-agent-clis.md)).
+  `AGENTS.md` is the standard; `wp` keeps everything around it coherent.
 
-Coding agents waste context in two predictable ways: duplicated repo guidance and
-verbose tool output. Agent Kit attacks both:
+## Why it exists
+
+Sharing instructions across agents is largely solved: `AGENTS.md` is the
+standard, and emitters like rulesync fan one source out to every runtime. `wp`
+manages that layer for you — but the hard part of agent-driven development isn't
+a missing instruction file. It is keeping agents **effective** (they burn the
+context window on verbose tool output) and keeping the repo **correct** (docs,
+plans, and code drift apart as agents move fast).
 
-- **Default compact quality evidence:** `wp_test`, `wp_lint`, `wp_typecheck`, `wp_qa`,
-  `wp_e2e`, and `wp_audit` are MCP-first wrappers that return summary-first
-  JSON, clipped raw output, and budget metadata such as `bytes` and
-  `tokensSaved`. See [`docs/qa-output.md`](docs/qa-output.md).
-- **Default RTK shell filtering lane:** `wp setup` includes `rtk` in its
-  default preset set. The setup command skips RTK in CI and when
-  `WP_SKIP_RTK=1` is set. See [`docs/add-ons.md`](docs/add-ons.md).
-- **Default context-mode lane:** `wp setup` includes `context-mode` in its
-  default preset set. The setup command skips context-mode in CI and when
-  `WP_SKIP_CONTEXT_MODE=1` is set, and the published package still does not
-  bundle the external tool. See
-  [`docs/migration/context-mode-default.md`](docs/migration/context-mode-default.md).
+`wp` is the TypeScript layer for both: summary-first tooling so the window goes
+to code, and enforced contracts so the work stays coherent.
 
-The result: agents spend more of the window on code, plans, decisions, and
-errors that matter, and less on repeated instructions or thousand-line command
-logs.
+```bash
+wp setup
+```
 
 ## Add-ons
 
@@ -92,6 +155,7 @@ If you need config subpaths or dependency references, use the appendix:
 
 - [Getting started](docs/getting-started.md)
 - [Is webpresso for me?](docs/is-agent-kit-for-me.md)
+- [Blueprint lifecycle](docs/lifecycle.md)
 - [Add-ons](docs/add-ons.md)
 - [Blueprint format](docs/blueprint-format.md)
 - [Skills catalog](docs/skills-catalog.md)

package/catalog/AGENTS.md.tpl

@@ -166,7 +166,9 @@ All packages in the webpresso public umbrella use **Changesets**. Never push
 To ship a change:
 1. `vp run changeset` — describe the change and select the bump type.
 2. Commit the generated `.changeset/<name>.md` alongside your code.
-3. Merge to `main`. The release workflow versions the package and publishes it
+3. Merge to `main`. The release workflow opens or updates a **Version Packages**
+   PR.
+4. Merge the **Version Packages** PR. The workflow then publishes the package
    to the public npm registry.
 
 ```bash

package/catalog/agent/rules/changeset-release.md

@@ -50,24 +50,20 @@ Steps 2-3 happen on the feature branch alongside the code change. There is
 no manual `vp run changeset version` or `vp run changeset publish` step in the
 normal path — CI owns those for this repository.
 
-## How releases work (CI-driven, direct-publish on push to `main`)
-
-**This repo uses a direct-publish flow — there is no \"Version Packages\" PR.**
+## How releases work (CI-driven Version PR + publish on merge)
 
 When a feature branch with a `.changeset/<slug>.md` file merges to `main`,
 `release.yml` runs the following sequence automatically:
 
-1. `vp run version` — runs `changeset version &&
-   vp run sync-marketplace-version`. This bumps `package.json`, updates
-   `CHANGELOG.md`, removes the consumed `.changeset/<slug>.md` files, and
-   syncs `.claude-plugin/marketplace.json` to match the new version.
-2. `npm publish --provenance --access public` — publishes
-   `@webpresso/agent-kit` to the public npm registry using the workflow-owned
-   publish path.
-3. `git push` — commits the version bump back to `main` only after publish
-   succeeds or the version is already published.
-4. CI creates a `release/v<version>` branch with compiled `dist/` committed
-   for Claude Code marketplace consumers.
+1. `changesets/action` opens or updates a **Version Packages** PR.
+2. The action runs `pnpm run version`, which preserves the canonical version
+   path: `changeset version && vp run sync-marketplace-version`.
+3. When the Version PR is merged, CI runs `pnpm run release:publish`, which
+   calls `npm publish --provenance --access public`.
+4. After publish, CI verifies the `v<version>` tag on the mainline version-bump
+   commit and creates `release/v<version>` as the separate dist-carrying
+   compatibility branch for marketplace consumers.
+5. GitHub Release objects are disabled in the initial rollout.
 
 The workflow supports a manual dry-run trigger:
 ```bash
@@ -102,8 +98,9 @@ git add .changeset/ && git commit -m "chore: add initial changeset"
 ```
 
 **Do NOT run `vp run changeset version` or `vp run changeset publish` manually**
-for established repos — CI owns both steps. Manual execution bypasses the
-`sync-marketplace-version` script and the release branch flow.
+for established repos — CI owns both steps through `changesets/action`. Manual
+execution bypasses the Version PR flow, the release branch contract, and the
+evidence gates.
 
 ## Release workflow (self-contained Changesets)
 

package/catalog/agent/skills/plan-refine/SKILL.md

@@ -16,10 +16,11 @@ description: Methodology for refining, fact-checking, and hardening implementati
 >
 > Blueprint hardening and lifecycle infrastructure are production-ready:
 >
-> - Kahn's Algorithm DAG analysis (fully tested)
-> - `ParallelExecutor` concurrency engine with abort, timeout, per-type limits
-> - Blueprint dependency format and validation
-> - Failed tasks block dependents automatically
+> - Blueprint dependency parsing, format validation, and the lifecycle state
+>   machine with evidence-gated task completion (fully tested, in-package)
+> - Parallel execution is delegated to the `/pll` runtime adapter (OMX), which
+>   batches independent tasks by dependency order and blocks dependents of
+>   failed tasks
 >
 > **Remaining gaps:** execution docs and wrappers must stay aligned with the currently shipped runtime and CLI surface.
 

package/catalog/base-kit/commitlint.config.ts.tmpl

@@ -1,6 +1,4 @@
-import type { UserConfig } from '@commitlint/types'
-
-const config: UserConfig = {
+const config = {
   extends: ['@commitlint/config-conventional'],
 }
 

package/catalog/base-kit/e2e/fixtures/smoke.html.tmpl

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Agent Kit smoke page</title>
+  </head>
+  <body>
+    <main>
+      <h1>Agent Kit quality scaffold</h1>
+      <p data-testid="status">ready</p>
+    </main>
+  </body>
+</html>

package/catalog/base-kit/e2e/smoke.spec.ts.tmpl

@@ -0,0 +1,13 @@
+import { expect, test } from '@playwright/test'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const smokePagePath = join(process.cwd(), 'e2e', 'fixtures', 'smoke.html')
+
+test('checks the file-based smoke page', async () => {
+  const html = await readFile(smokePagePath, 'utf8')
+
+  expect(html).toContain('Agent Kit quality scaffold')
+  expect(html).toContain('data-testid="status"')
+  expect(html).toContain('ready')
+})

package/catalog/base-kit/oxlint.config.ts.tmpl

@@ -0,0 +1,26 @@
+import { config } from '@webpresso/agent-kit/oxlint'
+
+const oxlintConfig: Record<string, unknown> = {
+  ...config,
+  env: {
+    builtin: true,
+    node: true,
+  },
+  ignorePatterns: [
+    'dist',
+    'node_modules',
+    'reports',
+    '.stryker-tmp',
+    '.agent',
+    '.agents',
+    '.claude',
+    '.codex',
+    '.cursor',
+    '.gemini',
+    '.opencode',
+    '.omx',
+    '.windsurf',
+  ],
+}
+
+export default oxlintConfig

package/catalog/base-kit/playwright.config.ts.tmpl

@@ -0,0 +1,10 @@
+import { defineConfig } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  reporter: [['list']],
+  use: {
+    trace: 'retain-on-failure',
+  },
+})

package/catalog/base-kit/src/quality-sample.test.ts.tmpl

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+
+import { add, clamp } from './quality-sample.js'
+
+describe('quality sample', () => {
+  it('adds two numbers', () => {
+    expect(add(2, 3)).toBe(5)
+  })
+
+  it('clamps values below, inside, and above the range', () => {
+    expect(clamp(-1, 0, 10)).toBe(0)
+    expect(clamp(5, 0, 10)).toBe(5)
+    expect(clamp(11, 0, 10)).toBe(10)
+  })
+
+  it('rejects an invalid range', () => {
+    expect(() => clamp(1, 10, 0)).toThrow(RangeError)
+  })
+})

package/catalog/base-kit/src/quality-sample.ts.tmpl

@@ -0,0 +1,11 @@
+export function add(left: number, right: number): number {
+  return left + right
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  if (min > max) {
+    throw new RangeError('min must be less than or equal to max')
+  }
+
+  return Math.min(Math.max(value, min), max)
+}

package/catalog/base-kit/stryker.config.ts.tmpl

@@ -0,0 +1,14 @@
+import { baseConfig } from '@webpresso/agent-kit/stryker'
+
+export default {
+  ...baseConfig,
+  thresholds: {
+    high: 0,
+    low: 0,
+    break: 0,
+  },
+  vitest: {
+    configFile: 'vitest.config.ts',
+  },
+  mutate: ['src/**/*.ts', '!src/**/*.test.ts', '!src/**/*.d.ts'],
+}

package/catalog/base-kit/tsconfig.json.tmpl

@@ -0,0 +1,9 @@
+{
+  "extends": "./node_modules/@webpresso/agent-kit/tsconfig/base.json",
+  "compilerOptions": {
+    "types": ["node", "vitest/globals"],
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts", "e2e/**/*.ts", "*.config.ts"],
+  "exclude": ["node_modules", "dist", "reports", ".stryker-tmp"]
+}

package/catalog/base-kit/vitest.config.ts.tmpl

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    exclude: ['e2e/**', 'node_modules/**', '.stryker-tmp/**'],
+  },
+})

package/catalog/docs/templates/adr.md

@@ -1,6 +1,6 @@
 ---
 type: adr
-last_updated: "YYYY-MM-DD"
+last_updated: "2026-05-27"
 ---
 
 # ADR NNNN: {{Title}}

package/catalog/docs/templates/blueprint.md

@@ -6,6 +6,7 @@ created: '2026-04-22'
 last_updated: '2026-04-22'
 progress: '0% (drafted)'
 depends_on: []
+cross_repo_depends_on: []
 tags: []
 ---
 

package/catalog/docs/templates/blueprint.yaml

@@ -21,12 +21,15 @@ frontmatter:
       format: YYYY-MM-DD
       description: Last modification date
   optional:
-    parent:
+    parent_roadmap:
       type: string
-      description: Path to parent epic (e.g., ../README.md)
+      description: Local parent-roadmap slug/path in the same repo
     depends_on:
       type: array
-      description: Dependencies on other plans
+      description: Local blueprint dependencies in the same repo
+    cross_repo_depends_on:
+      type: array
+      description: Cross-repo blueprint dependencies expressed as { repo, slug, require_status? }
 
 sections:
   required: []

package/catalog/docs/templates/guide.md

@@ -1,6 +1,6 @@
 ---
 type: guide
-last_updated: "YYYY-MM-DD"
+last_updated: "2026-05-27"
 ---
 
 # {{Title}}

package/catalog/docs/templates/postmortem.md

@@ -1,6 +1,6 @@
 ---
 type: postmortem
-last_updated: "YYYY-MM-DD"
+last_updated: "2026-05-27"
 ---
 
 # Postmortem: {{Incident Title}}

package/catalog/docs/templates/research.md

@@ -1,6 +1,6 @@
 ---
 type: research
-last_updated: "YYYY-MM-DD"
+last_updated: "2026-05-27"
 ---
 
 # {{Research Title}}

package/catalog/docs/templates/runbook.md

@@ -1,6 +1,6 @@
 ---
 type: runbook
-last_updated: "YYYY-MM-DD"
+last_updated: "2026-05-27"
 ---
 
 # Runbook: {{Scenario}}

package/catalog/docs/templates/system.md

@@ -1,6 +1,6 @@
 ---
 type: system
-last_updated: "YYYY-MM-DD"
+last_updated: "2026-05-27"
 ---
 
 # {{System Name}}
@@ -11,8 +11,17 @@ last_updated: "YYYY-MM-DD"
 
 ## Architecture
 
-```text
-[Diagram showing the main components and their edges]
+```mermaid
+flowchart LR
+  A[Main component] --> B[Dependency or downstream system]
+```
+
+## Infrastructure / deployment
+
+```mermaid
+flowchart LR
+  CI[Deploy entry point] --> RUNTIME[Runtime surface]
+  INFRA[Durable infrastructure owner] --> STATE[(Stateful resource)]
 ```
 
 ## Key invariants

package/catalog/docs/templates/tech-debt.md

@@ -5,6 +5,7 @@ severity: '{{severity}}'
 category: '{{category}}'
 review_cadence: quarterly
 last_reviewed: '{{date}}'
+last_updated: '2026-05-27'
 created: '{{date}}'
 linked_blueprints: []
 affected_modules: []

package/commands/blueprint.md

@@ -8,6 +8,8 @@ Use the focused blueprint MCP tools.
 - `wp_blueprint_get` — fetch one blueprint with freshness metadata
 - `wp_blueprint_context` — assemble bounded task context
 - `wp_blueprint_create` — create a draft blueprint; requires `project_id` and accepts optional `request_id` and `head_at_ingest` for retry-safe, stale-write-safe creation
+- `wp_blueprint_put` — whole-document structured authoring; writes the canonical blueprint markdown from typed input and returns revision metadata
+- `wp_blueprint_transition` — optimistic-concurrency lifecycle transition; requires `expected_version` and returns updated revision metadata
 - `wp_blueprint_task_next` — return the next ready task; accepts optional `project_id` when the current cwd is a multi-repo workspace container
 - `wp_blueprint_task_advance` — change task status (non-`done`); requires `project_id` and accepts optional `request_id` and `head_at_ingest` for retry-safe mutation
 - `wp_blueprint_task_verify` — mark a task `done` with evidence; accepts optional `request_id` and `head_at_ingest` for retry-safe verification
@@ -15,14 +17,45 @@ Use the focused blueprint MCP tools.
 
 Mutation guidance:
 
-- Use `request_id` on `wp_blueprint_create`, `wp_blueprint_task_advance`, and
-  `wp_blueprint_task_verify` when the caller may retry the same request.
+- V1 structured authoring is limited to `wp_blueprint_put + wp_blueprint_transition`.
+- Use `request_id` on `wp_blueprint_create`, `wp_blueprint_put`,
+  `wp_blueprint_task_advance`, and `wp_blueprint_task_verify` when the caller
+  may retry the same request.
 - Prefer passing `project_id` from `wp_blueprint_projects` whenever the current
   working directory can see more than one blueprint-bearing repo.
 - Carry `head_at_ingest` from `wp_blueprint_list`, `wp_blueprint_get`, or
-  `wp_blueprint_context` into mutation calls when the caller needs stale-write
-  protection across retries or multi-agent handoff.
+  `wp_blueprint_context` into `wp_blueprint_create`, `wp_blueprint_put`, and
+  other mutation calls when the caller needs stale-write protection across
+  retries or multi-agent handoff.
 - Reusing the same `request_id` with the same payload is idempotent.
 - Reusing the same `request_id` with a different payload is rejected.
 - If `head_at_ingest` is stale, the mutation is rejected and points the caller
   back to a canonical `wp_*` refresh path.
+- `wp_blueprint_transition` uses `expected_version` (the current
+  `content_hash`) for blueprint-scoped optimistic concurrency.
+
+Deferred patch boundary:
+
+- `wp_blueprint_patch` is **not** part of the v1 canonical surface.
+- If/when added, the patch model must be **semantic**, not raw markdown
+  mutation.
+- Minimum deferred operations:
+  - `add_task`
+  - `update_task`
+  - `set_summary`
+  - `replace_decision`
+- Until then, whole-document `wp_blueprint_put` is the canonical authoring path.
+
+Deferred UI/editor boundary:
+
+- A future MCP Apps blueprint editor is an **enhancement**, not part of the v1
+  correctness path.
+- Any UI flow must layer on top of `wp_blueprint_put + wp_blueprint_transition`
+  instead of introducing a parallel write surface.
+- Hosts without MCP Apps support must still complete the full authoring flow
+  through the structured tools alone.
+- Minimum v2 editor contract:
+  - capability detection for MCP Apps support
+  - structured form/editor over the full blueprint document
+  - non-UI fallback guidance that routes back to `wp_blueprint_put` and
+    `wp_blueprint_transition`

package/dist/esm/audit/resolve-audit-script.d.ts

@@ -0,0 +1,24 @@
+export interface ResolveAuditScriptDeps {
+    /** `import.meta.url` of the calling module (`cli/commands/audit` or `mcp/tools/audit`). */
+    moduleUrl: string;
+    /** Existence probe; defaults to `fs.existsSync`. Injected in tests to model each layout. */
+    exists?: (url: URL) => boolean;
+}
+/**
+ * Resolve the absolute path of a Bun audit script (`audit-tph.ts`,
+ * `audit-tph-e2e.ts`) living in the sibling `audit/` directory two levels up
+ * from the caller.
+ *
+ * `../../audit/` is correct relative to the caller in BOTH layouts:
+ *   - dev:       `src/{cli,mcp}/.../audit.ts` → `src/audit/`
+ *   - published: `dist/esm/{cli,mcp}/.../audit.js` → `dist/esm/audit/`
+ *
+ * The npm tarball ships only `dist/` (never `src/`), so the dev `.ts` source is
+ * absent there — fall back to the compiled `.js` sibling the build emits. The
+ * previous CLI resolver instead hand-rolled a `<bundle>/src/audit/<name>.ts`
+ * path that does not exist in dist, which made `bun` fail with
+ * "Module not found"; the MCP twin reached for the unshipped `src/audit/` via
+ * `resolvePackageAsset` and failed the same way.
+ */
+export declare function resolveAuditScriptPath(name: string, { moduleUrl, exists }: ResolveAuditScriptDeps): string;
+//# sourceMappingURL=resolve-audit-script.d.ts.map