@geraldmaron/construct 1.1.0 → 1.2.0

package/templates/distribution/icons/git-branch.svg

@@ -0,0 +1,17 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-git-branch"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M15 6a9 9 0 0 0-9 9V3" />
+  <circle cx="18" cy="6" r="3" />
+  <circle cx="6" cy="18" r="3" />
+</svg>

package/templates/distribution/icons/key.svg

@@ -0,0 +1,17 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-key"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="m15.5 7.5 2.3 2.3a1 1 0 0 0 1.4 0l2.1-2.1a1 1 0 0 0 0-1.4L19 4" />
+  <path d="m21 2-9.6 9.6" />
+  <circle cx="7.5" cy="15.5" r="5.5" />
+</svg>

package/templates/distribution/icons/layers.svg

@@ -0,0 +1,17 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-layers"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M12.83 2.18a2 2 0 0 0-1.66 0L2.6 6.08a1 1 0 0 0 0 1.83l8.58 3.91a2 2 0 0 0 1.66 0l8.58-3.9a1 1 0 0 0 0-1.83z" />
+  <path d="M2 12a1 1 0 0 0 .58.91l8.6 3.91a2 2 0 0 0 1.65 0l8.58-3.9A1 1 0 0 0 22 12" />
+  <path d="M2 17a1 1 0 0 0 .58.91l8.6 3.91a2 2 0 0 0 1.65 0l8.58-3.9A1 1 0 0 0 22 17" />
+</svg>

package/templates/distribution/icons/list-checks.svg

@@ -0,0 +1,19 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-list-checks"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M13 5h8" />
+  <path d="M13 12h8" />
+  <path d="M13 19h8" />
+  <path d="m3 17 2 2 4-4" />
+  <path d="m3 7 2 2 4-4" />
+</svg>

package/templates/distribution/icons/lock.svg

@@ -0,0 +1,16 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-lock"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <rect width="18" height="11" x="3" y="11" rx="2" ry="2" />
+  <path d="M7 11V7a5 5 0 0 1 10 0v4" />
+</svg>

package/templates/distribution/icons/message-square.svg

@@ -0,0 +1,15 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-message-square"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M22 17a2 2 0 0 1-2 2H6.828a2 2 0 0 0-1.414.586l-2.202 2.202A.71.71 0 0 1 2 21.286V5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2z" />
+</svg>

package/templates/distribution/icons/network.svg

@@ -0,0 +1,19 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-network"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <rect x="16" y="16" width="6" height="6" rx="1" />
+  <rect x="2" y="16" width="6" height="6" rx="1" />
+  <rect x="9" y="2" width="6" height="6" rx="1" />
+  <path d="M5 16v-3a1 1 0 0 1 1-1h12a1 1 0 0 1 1 1v3" />
+  <path d="M12 12V8" />
+</svg>

package/templates/distribution/icons/route.svg

@@ -0,0 +1,17 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-route"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <circle cx="6" cy="19" r="3" />
+  <path d="M9 19h8.5a3.5 3.5 0 0 0 0-7h-11a3.5 3.5 0 0 1 0-7H15" />
+  <circle cx="18" cy="5" r="3" />
+</svg>

package/templates/distribution/icons/scale.svg

@@ -0,0 +1,19 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-scale"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M12 3v18" />
+  <path d="m19 8 3 8a5 5 0 0 1-6 0zV7" />
+  <path d="M3 7h1a17 17 0 0 0 8-2 17 17 0 0 0 8 2h1" />
+  <path d="m5 8 3 8a5 5 0 0 1-6 0zV7" />
+  <path d="M7 21h10" />
+</svg>

package/templates/distribution/icons/search.svg

@@ -0,0 +1,16 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-search"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="m21 21-4.34-4.34" />
+  <circle cx="11" cy="11" r="8" />
+</svg>

package/templates/distribution/icons/send.svg

@@ -0,0 +1,16 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-send"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M14.536 21.686a.5.5 0 0 0 .937-.024l6.5-19a.496.496 0 0 0-.635-.635l-19 6.5a.5.5 0 0 0-.024.937l7.93 3.18a2 2 0 0 1 1.112 1.11z" />
+  <path d="m21.854 2.147-10.94 10.939" />
+</svg>

package/templates/distribution/icons/server.svg

@@ -0,0 +1,18 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-server"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <rect width="20" height="8" x="2" y="2" rx="2" ry="2" />
+  <rect width="20" height="8" x="2" y="14" rx="2" ry="2" />
+  <line x1="6" x2="6.01" y1="6" y2="6" />
+  <line x1="6" x2="6.01" y1="18" y2="18" />
+</svg>

package/templates/distribution/icons/shield-check.svg

@@ -0,0 +1,16 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-shield-check"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z" />
+  <path d="m9 12 2 2 4-4" />
+</svg>

package/templates/distribution/icons/users.svg

@@ -0,0 +1,18 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-users"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2" />
+  <path d="M16 3.128a4 4 0 0 1 0 7.744" />
+  <path d="M22 21v-2a4 4 0 0 0-3-3.87" />
+  <circle cx="9" cy="7" r="4" />
+</svg>

package/templates/distribution/icons/webhook.svg

@@ -0,0 +1,17 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-webhook"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M18 16.98h-5.99c-1.1 0-1.95.94-2.48 1.9A4 4 0 0 1 2 17c.01-.7.2-1.4.57-2" />
+  <path d="m6 17 3.13-5.78c.53-.97.1-2.18-.5-3.1a4 4 0 1 1 6.89-4.06" />
+  <path d="m12 6 3.13 5.73C15.66 12.7 16.9 13 18 13a4 4 0 0 1 0 8" />
+</svg>

package/templates/distribution/icons/workflow.svg

@@ -0,0 +1,17 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-workflow"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <rect width="8" height="8" x="3" y="3" rx="2" />
+  <path d="M7 11v4a2 2 0 0 0 2 2h4" />
+  <rect width="8" height="8" x="13" y="13" rx="2" />
+</svg>

package/templates/distribution/icons/wrench.svg

@@ -0,0 +1,15 @@
+<!-- @license lucide-static v1.21.0 - ISC -->
+<svg
+  class="lucide lucide-wrench"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#0a0c10"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.106-3.105c.32-.322.863-.22.983.218a6 6 0 0 1-8.259 7.057l-7.91 7.91a1 1 0 0 1-2.999-3l7.91-7.91a6 6 0 0 1 7.057-8.259c.438.12.54.662.219.984z" />
+</svg>

package/templates/distribution/run.mjs

@@ -58,6 +58,19 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
+
+// npm 11.2+ warns on unknown npm_config_* keys. Cursor injects devdir for
+// node-gyp cache routing; strip before npm spawns (inline — no repo imports).
+
+function sanitizeNpmSpawnEnv(env = process.env) {
+  const next = { ...env };
+  for (const key of Object.keys(next)) {
+    if (/^npm_config_devdir$/i.test(key) || key === 'NPM_CONFIG_DEVDIR') {
+      delete next[key];
+    }
+  }
+  return next;
+}
 const PROJECT_ROOT = resolve(HERE, '..');
 const VERSION_FILE = join(HERE, 'version');
 const CACHE_BIN_DIR = join(HERE, 'cache', 'bin');
@@ -138,7 +151,11 @@ function tryNpx(version) {
   // so that failure can never fall through to the global/cache/Docker resolvers below.
   // Confirm the spec resolves first; on a miss, defer instead of dead-ending the chain.
 
-  const probe = spawnSync('npm', ['view', spec, 'version'], { stdio: 'ignore', timeout: 8000 });
+  const probe = spawnSync('npm', ['view', spec, 'version'], {
+    stdio: 'ignore',
+    timeout: 8000,
+    env: sanitizeNpmSpawnEnv(process.env),
+  });
   if (probe.status !== 0) return false;
   runForeground('npx', ['-p', spec, '--', 'construct', ...process.argv.slice(2)]);
   return true;

package/templates/docs/adr.md

@@ -37,6 +37,13 @@ Should reference:
 ## Context
 <!-- Forces at play beyond the core problem. What else is true today that bounds the decision space? Prior ADRs, architectural constraints, external commitments. -->
 
+```mermaid
+flowchart LR
+  A[Current state] --> B[Decision]
+  B --> C[Target state]
+  D[Rejected alt] -.-> B
+```
+
 ## Decision
 <!-- The position taken, in one or two sentences. State it as a commitment, not a proposal. -->
 

package/templates/docs/construct_guide.md

@@ -35,8 +35,8 @@ Generated tooling (`.construct/`, `.claude/`, `.cx/`, `plan.md`) is gitignored;
 
 Three intake paths, ordered by formality:
 
-1. **`.cx/inbox/`** (drop a file here (URL, screenshot, paste, anything). The embed daemon watches the directory; when a file lands, it ingests it into the local knowledge base within a second or two and writes a triage packet to `.cx/intake/pending/` describing the new content, its R&D classification (intake type, stage, owner persona, recommended chain), its suggested docs lane, and existing docs that overlap. The agent surfaces pending intake at the next session start and you can ask it to process them) propose updates to existing PRDs/RFCs/ADRs or scaffold new ones: based on the prepared context.
-2. **`docs/intake/`**: for proper intake batches (research notes, evidence from a meeting, raw source material). Has a template. Survives in git history.
+1. **`.cx/inbox/`** — drop a file here (URL, screenshot, paste, anything). The embed daemon watches the directory; when a file lands, it ingests it into the local knowledge base within a second or two and writes a triage packet to `.cx/intake/pending/` describing the new content, its classification (intake type, stage, owner persona, recommended chain), its suggested docs lane, and existing docs that overlap. The agent surfaces pending items at the next session start and you can ask it to process them.
+2. **`docs/intake/`** — for proper intake batches (research notes, evidence from a meeting, raw source material). Has a template. Survives in git history.
 3. **`AGENTS.md`**: for rules and conventions you want the agent to follow every time. "We prefer functional components. Don't introduce new dependencies without flagging." Read at session start.
 
 For URLs or quick notes, the easiest path is to drop a file into `~/Downloads` and run:
@@ -109,15 +109,15 @@ All ports bind to `127.0.0.1` only; nothing is reachable from other machines on
 | `construct config [mode <m>]` | Show active deployment mode (solo / team / enterprise) or set a new one |
 | `construct doctor` | Health check across config, services, agents, hooks |
 | `construct sync` | Regenerate platform adapters (Claude Code, OpenCode, Codex, Cursor) |
-| `construct up` / `construct down` | Start / stop local services |
+| `construct dev` / `construct stop` | Start / stop local services |
 | `construct status` | Live runtime status (services, providers, daemons) |
-| `construct intake list / show / done / skip / reopen` | Drive the R&D intake queue produced from `.cx/inbox/` |
+| `construct intake list / show / done / skip / reopen` | Drive the active profile's intake queue (label varies — run `construct intake --help`) |
 | `construct graph from-intake <id>` | Generate a task graph from a triaged intake packet |
 | `construct drop` | Ingest the most recent downloaded file |
 | `construct search "..."` | Hybrid file + SQL + semantic search over project state |
 | `construct uninstall` | Interactive teardown: never touches Docker or your code |
 
-Full reference: <https://geraldmaron.github.io/construct/docs/reference/cli>
+Full reference: <https://geraldmaron.github.io/construct/reference/cli>
 
 ## Updating Construct
 
@@ -131,16 +131,16 @@ That refreshes the agents, hooks, and slash commands in `.claude/` and `.constru
 
 ```bash
 construct doctor              # most issues surface here with a fix hint
-construct down && construct up  # restart local services
+construct stop && construct dev  # restart local services
 ```
 
-Troubleshooting guide: <https://geraldmaron.github.io/construct/docs/operations/troubleshooting>
+Troubleshooting guide: <https://geraldmaron.github.io/construct/runbooks/>
 
 ## Next steps
 
-- [Connect your editor](https://geraldmaron.github.io/construct/docs/start/connect-your-editor) if you haven't already.
-- [Run your first task](https://geraldmaron.github.io/construct/docs/start/first-task) to feel the flow.
-- Skim [the architecture](https://geraldmaron.github.io/construct/docs/concepts/architecture) when you have 10 minutes: it'll save you hours later.
+- [Connect your editor](https://geraldmaron.github.io/construct/start/connect-your-editor) if you haven't already.
+- [Run your first task](https://geraldmaron.github.io/construct/start/first-task) to feel the flow.
+- Skim [the architecture](https://geraldmaron.github.io/construct/concepts/architecture) when you have 10 minutes: it'll save you hours later.
 
 If you'd rather have a teammate walk you through it, the persona itself can:
 

package/templates/docs/customer-profile.md

@@ -21,6 +21,10 @@ asks for cleanup. Keep facts tied to source evidence.
 ## Open asks
 <!-- Table: ask, first raised, times mentioned, source, linked issue, status. -->
 
+| Ask | First raised | Status |
+|---|---|---|
+| {customer ask} | {YYYY-MM-DD} | open / blocked / done |
+
 ## Key contacts
 <!-- Roles and responsibilities. Avoid unnecessary personal data. -->
 

package/templates/docs/one-pager.md

@@ -17,6 +17,10 @@
 ## Success measure
 <!-- The single metric that tells us this worked. Numeric, time-bound. -->
 
+| Measure | Baseline | Target | By when |
+|---|---|---|---|
+| {metric} | {today} | {goal} | {YYYY-MM-DD} |
+
 ## Cost
 <!-- People, time, money. Rough order of magnitude. -->
 

package/templates/docs/postmortem.md

@@ -0,0 +1,31 @@
+# Postmortem: {incident title}
+
+- **Date**: {YYYY-MM-DD}
+- **Owner**: {name or on-call rotation}
+- **Severity**: SEV-1 | SEV-2 | SEV-3
+
+<!-- Same structure as incident-report.md. Blameless tone required. -->
+
+## Summary
+
+## Severity rationale
+
+## Impact
+
+## Timeline
+
+| Time (UTC) | Event |
+|---|---|
+| {HH:MM} | {what happened} |
+
+## Trigger
+
+## Root cause
+
+## Contributing factors
+
+## Action items
+
+| Priority | Action | Owner | Due |
+|---|---|---|---|
+| P0 | {corrective action} | {name} | {date} |

package/templates/docs/prd-platform.md

@@ -25,6 +25,15 @@ operator. "Developer" is too broad.
 ## Goals and non-goals
 <!-- Goals: what success looks like for the consumers. Non-goals: explicitly scoped out. -->
 
+## Platform flow
+
+```mermaid
+flowchart TD
+  A[Consumer] --> B[Platform API]
+  B --> C[Core service]
+  C --> D[Response / event]
+```
+
 ## API and interface contract
 <!-- The surface being defined: endpoints, schemas, SDK methods, event payloads, config shapes, permission models. Number each contract item (C-1, C-2, …). -->
 
@@ -49,6 +58,16 @@ operator. "Developer" is too broad.
 ## Success metrics
 <!-- How we know this worked: adoption, error rate, latency, support ticket reduction. Leading vs. lagging. -->
 
+| Metric | Baseline | Target |
+|---|---|---|
+| {name} | {current} | {goal} |
+
+## Risks and mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| {risk} | low / med / high | low / med / high | {mitigation} |
+
 ## Consumer impact
 <!-- What changes for existing consumers. What breaks, what degrades, what stays the same. Link to migration guide if needed. -->
 

package/templates/docs/prd.md

@@ -75,6 +75,17 @@ A reader should be able to compare the current state (Background) to this
 section and see the delta in plain language.
 -->
 
+## User flow
+
+```mermaid
+flowchart TD
+  A[User starts] --> B{Current friction?}
+  B -->|Yes| C[Proposed path]
+  B -->|No| D[Existing path]
+  C --> E[Success outcome]
+  D --> E
+```
+
 ## In scope and out of scope
 
 | | Description |
@@ -163,6 +174,10 @@ How we will know this worked in production over time, beyond the per-requirement
 acceptance criteria. Leading vs. lagging. Avoid vanity metrics.
 -->
 
+| Metric | Baseline | Target |
+|---|---|---|
+| {name} | {current} | {goal} |
+
 ## Constraints
 <!--
 Budget, timeline, platform, team, legal, technical debt: anything that shapes

package/templates/docs/prfaq.md

@@ -15,6 +15,13 @@ or directly from evidence, but it must not invent customer demand.
 ## Problem statement
 <!-- Two or three paragraphs grounded in evidence. Explain the customer problem, why now, and what is missing today. -->
 
+```mermaid
+flowchart LR
+  A[Customer need] --> B[Current workaround]
+  B --> C[Proposed capability]
+  C --> D[Outcome after launch]
+```
+
 ## Press release
 <!-- Write as if the capability has shipped. Focus on customer outcome, not implementation. Include a spokesperson quote and a customer quote — mark a hypothetical quote as such; never invent an attributed one (rules/common/no-fabrication.md). -->
 

package/templates/docs/qa-strategy.md

@@ -0,0 +1,103 @@
+# QA Strategy: {feature or system name}
+
+- **Date**: {YYYY-MM-DD}
+- **Owner**: {name or role}
+- **Status**: draft | in-review | approved | executed
+- **Related**: {PRD / ADR paths or none}
+
+<!--
+Use this when a feature, migration, or system change needs a deliberate
+verification strategy before it ships. The plan is the contract between
+what was specified and what will be proven; every scenario below must
+trace to a requirement or an observed risk, never to guesswork.
+
+Before drafting, read rules/common/framing.md and rules/common/no-fabrication.md.
+Acceptance criteria must be binary pass/fail. If a criterion cannot be
+checked without asking the author, it is not done. Cite the requirement
+(FR/NFR id, ADR decision, ticket) each scenario verifies.
+-->
+
+## Scope
+<!--
+What is under test and what is explicitly not. Name the components, surfaces,
+or behaviors covered. The out-of-scope list protects reviewer attention and
+makes coverage gaps deliberate rather than accidental.
+-->
+
+| | Description |
+|---|---|
+| **In scope** | <what this plan verifies> |
+| **Out of scope** | <related behavior deliberately not tested here, and why> |
+
+## Test strategy
+<!--
+The levels of testing applied and why each is justified. Map levels to risk:
+unit for logic, integration for contracts and boundaries, end-to-end for
+user-visible flows, manual/exploratory for what automation cannot reach.
+State what each level is responsible for so coverage gaps are visible.
+-->
+
+| Level | What it covers | Why it lives at this level |
+|---|---|---|
+| Unit | <logic, pure functions, edge cases> | <reason> |
+| Integration | <contracts, boundaries, data access> | <reason> |
+| End-to-end | <user-visible flows> | <reason> |
+| Manual / exploratory | <what automation cannot reach> | <reason> |
+
+## Coverage
+
+| Scenario | Type | Priority |
+|---|---|---|
+| TC-1 | unit / integration / e2e | P0 / P1 / P2 |
+| TC-2 | <...> | <...> |
+
+## Key scenarios
+<!--
+The scenarios that prove the change works. Each scenario names the requirement
+it verifies, the setup, the action, and the binary acceptance criterion. A
+reviewer must be able to run or read the scenario and decide pass/fail without
+asking the author.
+-->
+
+| ID | Scenario | Verifies | Acceptance (binary pass/fail) |
+|---|---|---|---|
+| TC-1 | <setup, action, expected result> | <FR/NFR id or risk> | <observable condition> |
+| TC-2 | <...> | <...> | <...> |
+
+## Risks and edge cases
+<!--
+The failure modes and boundary conditions worth explicit attention: empty
+inputs, concurrency, partial failure, large data, permission boundaries,
+rollback. For each, state how the plan covers it or why the residual risk
+is accepted.
+-->
+
+| Risk / edge case | Likelihood | Impact | Coverage or accepted reason |
+|---|---|---|---|
+| <condition> | low / med / high | low / med / high | <how it is tested, or why accepted> |
+
+## Environments and data
+<!--
+Where tests run and what data they use. Name the environments, fixtures,
+seed data, and any external dependencies (sandboxes, stubs, recorded
+responses). Flag data that must be synthetic or anonymized.
+-->
+
+## Entry and exit criteria
+<!--
+Entry: what must be true before testing starts (build available, environment
+provisioned, dependencies stubbed). Exit: what must be true to call testing
+done (all blocking scenarios pass, known issues triaged, coverage threshold
+met). Both are checklists a reviewer can verify.
+-->
+
+**Entry criteria**
+
+- <condition that must hold before execution begins>
+
+**Exit criteria**
+
+- <condition that must hold to declare the plan executed>
+
+## References
+<!-- PRD, ADR, RFC, related test plans, prior incidents. -->