@geraldmaron/construct 1.2.1 → 1.2.2

package/rules/common/review-before-change.md

@@ -44,7 +44,7 @@ For artifacts that go through a review cycle (strategy, PRD, ADR, RFC), the fram
 - Writing a new rule that paraphrases an existing one.
 - Adding a new template alongside `templates/docs/strategy.md` because the existing one "needed a couple of tweaks."
 - Drafting an ADR for a decision already captured in an existing ADR.
-- Producing a recipe in `docs/cookbook/` for a workflow already documented in `docs/concepts/`.
+- Producing a recipe in `docs/guides/cookbook/` for a workflow already documented in `docs/guides/concepts/`.
 
 ## Related
 

package/scripts/sync-specialists.mjs

@@ -55,6 +55,7 @@ import {
   getOpenCodeMcpId,
 } from "../lib/mcp-platform-config.mjs";
 import { loadConstructEnv } from "../lib/env-config.mjs";
+import { configDir } from "../lib/config/xdg.mjs";
 import { inlineRoleAntiPatterns, PROMPT_WORD_CAP } from "../lib/role-preload.mjs";
 import { inlineValidationContract } from "../lib/prompt-validation-contract.mjs";
 import { loadManifest } from "../lib/roles/manifest.mjs";
@@ -852,7 +853,7 @@ ${buildPrompt(entry, allEntries, "claude")}
 
 /**
  * Rewrite the home-mode hook command pattern
- *   node "$HOME/.construct/lib/hooks/<name>.mjs"
+ *   node "$HOME/.config/construct/lib/hooks/<name>.mjs"
  * into the project-portable form
  *   node .construct/run.mjs hook <name>
  * so the resulting settings.json works on any clone where the project ships
@@ -866,7 +867,7 @@ function makeHooksPortable(hooksJson) {
   // Operate on the in-memory object so we don't fight JSON string escaping.
   const replaceCommand = (cmd) => {
     if (typeof cmd !== 'string') return cmd;
-    const m = cmd.match(/^node\s+"?\$HOME\/\.construct\/lib\/hooks\/([a-z0-9-]+)\.mjs"?\s*(.*)$/);
+    const m = cmd.match(/^node\s+"?\$HOME\/\.config\/construct\/lib\/hooks\/([a-z0-9-]+)\.mjs"?\s*(.*)$/);
     if (!m) return cmd;
     const [, name, rest] = m;
     return `node .construct/run.mjs hook ${name}${rest ? ' ' + rest.trim() : ''}`;
@@ -1044,13 +1045,15 @@ ${personaList}
       if (fs.existsSync(templatePath)) {
         const template = JSON.parse(fs.readFileSync(templatePath, "utf8"));
         if (template.hooks) {
-          // Resolve $HOME/.construct to the real path so hook commands survive
-          // symlink traversal inside Claude Code's hook runner environment.
-          const constructReal = (() => {
-            try { return fs.realpathSync(path.join(home, ".construct")); } catch { return path.join(home, ".construct"); }
+          // Resolve the $HOME/.config/construct token to the real config dir so
+          // hook commands survive symlink traversal inside Claude Code's hook
+          // runner environment, and honor a custom XDG_CONFIG_HOME at sync time.
+          const configReal = (() => {
+            const dir = configDir(home);
+            try { return fs.realpathSync(dir); } catch { return dir; }
           })();
           const hookStr = JSON.stringify(filterGlobalClaudeHooks(template.hooks))
-            .replace(/\$HOME\/\.construct/g, constructReal.replace(/\\/g, "/"));
+            .replace(/\$HOME\/\.config\/construct/g, configReal.replace(/\\/g, "/"));
           settings.hooks = JSON.parse(hookStr);
         }
       }
@@ -1445,7 +1448,7 @@ function syncCursor(targetDir = null, wants = true) {
 
     // Glob-scoped language rules land as managed per-rule .mdc files only when
     // the project's own files match their globs — Cursor's native auto-attach
-    // convention. See docs/concepts/rules-delivery.md.
+    // convention. See docs/guides/concepts/rules-delivery.md.
     try {
       emitCursorRules({ rulesDir: path.join(root, "rules"), targetDir, dryRun: DRY_RUN });
     } catch (err) {

package/skills/docs/adr-workflow.md

@@ -18,14 +18,14 @@ Use when: an architectural decision is made that affects the system structure, d
 ## Steps
 
 1. **cx-architect** or **cx-engineer** identifies the decision
-2. **Write to `docs/adr/ADR-{NNN}-{slug}.md`** using the template from `get_template("adr")`: resolves `.cx/templates/docs/adr.md` (override) then `templates/docs/adr.md` (shipped)
+2. **Write to `docs/decisions/adr/ADR-{NNN}-{slug}.md`** using the template from `get_template("adr")`: resolves `.cx/templates/docs/adr.md` (override) then `templates/docs/adr.md` (shipped)
    - NNN = next sequential number (check existing files)
 3. **Also write a shorter entry to `.cx/decisions/`** for session context
 4. **cx-docs-keeper** updates `.cx/context.md` Architecture Notes with a one-line summary and link
 
 ## File naming
-- `docs/adr/ADR-001-use-postgres-over-mysql.md`
-- `docs/adr/ADR-002-jwt-auth-strategy.md`
+- `docs/decisions/adr/ADR-001-use-postgres-over-mysql.md`
+- `docs/decisions/adr/ADR-002-jwt-auth-strategy.md`
 
 ## Cross-referencing
 - If this ADR supersedes another: update the old ADR's status field

package/skills/docs/init-docs.md

@@ -54,7 +54,7 @@ When run interactively, `construct init --docs-preset=*` renders a keyboard-driv
 - **Enter**: confirm and scaffold
 - Follow-up choices use the same menu pattern instead of free-text answers
 
-If the user selects the `intake` lane, `construct init` should also create `.cx/inbox/`. Both `.cx/inbox/` and `docs/intake/` act as drop zones for ingestable files, while `docs/intake/` also serves as the durable paper trail lane.
+The single canonical drop zone for ingestable files is `inbox/` at the project root (ADR-0045 §C); `construct init` scaffolds it with a gitignored `inbox/.staging/` for atomic handoff. The `intake` docs lane (`docs/intake/`) is a separate, optional durable paper-trail lane for intake batch records — it is not a watched drop zone.
 
 When run non-interactively (`--yes` or piped stdin), the lean default set is used unless `--docs=` is supplied. `--docs=lean|product|full` or `--docs=adrs,prds,rfcs` both work.
 
@@ -64,18 +64,18 @@ When run non-interactively (`--yes` or piped stdin), the lean default set is use
 
 | Lane         | Directory       | What goes here |
 |--------------|-----------------|----------------|
-| adrs         | `docs/adr/`         | Architecture decisions that have already been made |
+| adrs         | `docs/decisions/adr/`         | Architecture decisions that have already been made |
 | briefs       | `docs/briefs/`      | Research, evidence, signals, one-pagers, customer profiles |
 | changelogs   | `docs/changelogs/`  | User-facing release notes and version history entries |
 | intake       | `docs/intake/`      | Intake batch records that explain what arrived, why it matters, and how it should be ingested |
-| memos        | `docs/memos/`       | Decision memos and internal arguments for alignment |
-| meetings     | `docs/meetings/`    | Meeting notes, minutes, standups, retros, agendas, and session summaries |
+| memos        | `docs/notes/memos/`       | Decision memos and internal arguments for alignment |
+| meetings     | `docs/notes/meetings/`    | Meeting notes, minutes, standups, retros, agendas, and session summaries |
 | notes        | `docs/notes/`       | Working notes and lightweight durable context outside formal docs or meetings |
 | onboarding   | `docs/onboarding/`  | Runnable setup guides and first-day workflows |
 | postmortems  | `docs/postmortems/` | Blameless incident reports with root cause and corrective actions |
-| prds         | `docs/prds/`        | Product and capability requirement documents |
-| rfcs         | `docs/rfcs/`        | Architecture and implementation proposals needing review |
-| runbooks     | `docs/runbooks/`    | Operational procedures, diagnostics, escalation paths |
+| prds         | `templates/docs/prds/`        | Product and capability requirement documents |
+| rfcs         | `templates/docs/rfcs/`        | Architecture and implementation proposals needing review |
+| runbooks     | `docs/operations/runbooks/`    | Operational procedures, diagnostics, escalation paths |
 
 ### Guidance: which lanes to suggest
 
@@ -152,7 +152,7 @@ Last updated: [date]
 
 ## Key decisions
 
-Link to `docs/adr/` or the canonical project decision log used in this repo.
+Link to `docs/decisions/adr/` or the canonical project decision log used in this repo.
 ```
 
 ---
@@ -188,7 +188,7 @@ Stack: [stack]
 
 After completing the docs init:
 - If the user has architecture questions → `@cx-explorer` or `@cx-docs-keeper` to explore and update `docs/architecture/`
-- If the user wants to document a decision → record it in `docs/adr/` using the ADR template
+- If the user wants to document a decision → record it in `docs/decisions/adr/` using the ADR template
 - If the user wants to add API docs → `@cx-docs-keeper` to generate stubs from code
 - If the user wants to file an incident report → use `docs/postmortems/` with the incident-report template
 - If the user wants to document a release → use `docs/changelogs/` with the changelog-entry template

package/skills/docs/prd-workflow.md

@@ -33,12 +33,12 @@ Style constraint: do not produce a wall of bullets. Use paragraphs for reasoning
 
    | Template | Output path |
    |---|---|
-   | `prd` | `docs/prd/{YYYY-MM-DD}-{slug}.md` |
+   | `prd` | `docs/specs/prd/{YYYY-MM-DD}-{slug}.md` |
    | `prd-platform` | `docs/prd-platform/{YYYY-MM-DD}-{slug}.md` |
    | `prd-business` | `docs/prd-business/{YYYY-MM-DD}-{slug}.md` |
    | `meta-prd` | `docs/meta-prd/{YYYY-MM-DD}-{slug}.md` |
-   | `rfc` | `docs/rfc/{YYYY-MM-DD}-{slug}.md` |
-   | `rfc-platform` | `docs/rfc/{YYYY-MM-DD}-{slug}.md` |
+   | `rfc` | `docs/decisions/rfc/{YYYY-MM-DD}-{slug}.md` |
+   | `rfc-platform` | `docs/decisions/rfc/{YYYY-MM-DD}-{slug}.md` |
 5. **cx-devil-advocate** runs the FMEA challenge pass (`roles/reviewer.devil-advocate`) on the draft; highest-RPN failure modes need a mitigation or explicit accept-with-rationale before ship. Their specialist id must appear in `.cx/agent-log.jsonl` (manifest `releaseGate.requiredReviewers` for PRD-family types).
 6. **cx-docs-keeper** updates `.cx/context.md` with a link to the PRD
 
@@ -47,11 +47,11 @@ Run `construct artifact validate <path> --type=<type>` before marking the artifa
 ## File naming
 - `docs/{template-type}/{YYYY-MM-DD}-{slug}.md`
 - Examples:
-  - `docs/prd/2026-04-search-autocomplete.md`
+  - `docs/specs/prd/2026-04-search-autocomplete.md`
   - `docs/prd-platform/2026-04-events-api-v2.md`
   - `docs/prd-business/2026-04-enterprise-tier.md`
   - `docs/meta-prd/2026-04-product-intelligence-workflow.md`
-  - `docs/rfc/2026-04-storage-backend-migration.md`
+  - `docs/decisions/rfc/2026-04-storage-backend-migration.md`
 
 ## PRD lifecycle
 - Draft → stakeholder review → approved → link to implementation tasks

package/skills/docs/product-intelligence-review.md

@@ -17,7 +17,7 @@ Score each dimension as pass, warning, or fail:
 - Acceptance criteria: observable and pass/fail.
 - Scope discipline: goals, non-goals, and tradeoffs are explicit.
 - Approval safety: external writes and approved status are gated.
-- Storage readiness: artifact path is under `.cx/knowledge/`, `docs/prd/`, or `docs/meta-prd/` so hybrid retrieval can index it.
+- Storage readiness: artifact path is under `.cx/knowledge/`, `docs/specs/prd/`, or `docs/meta-prd/` so hybrid retrieval can index it.
 - Readability: balanced paragraphs, tables, and bullets. Few em dashes.
 
 ## Output

package/skills/docs/product-intelligence-workflow.md

@@ -54,9 +54,9 @@ Load the core product-manager role guidance and the selected overlay before draf
 
 ## Storage
 
-Write working artifacts under `.cx/knowledge/` unless they are docs of record. Approved PRDs live in `docs/prd/`; approved Meta PRDs live in `docs/meta-prd/`.
+Write working artifacts under `.cx/knowledge/` unless they are docs of record. Approved PRDs live in `docs/specs/prd/`; approved Meta PRDs live in `docs/meta-prd/`.
 
-The hybrid storage layer indexes `.cx/knowledge/`, `docs/prd/`, and `docs/meta-prd/`. When Postgres is configured, `construct storage sync` can persist these artifacts into shared SQL rows. The vector layer scores the same documents for local, remote, or file-backed semantic retrieval.
+The hybrid storage layer indexes `.cx/knowledge/`, `docs/specs/prd/`, and `docs/meta-prd/`. When Postgres is configured, `construct storage sync` can persist these artifacts into shared SQL rows. The vector layer scores the same documents for local, remote, or file-backed semantic retrieval.
 
 ## Approval boundaries
 

package/skills/docs/product-signal-workflow.md

@@ -57,7 +57,7 @@ After grouping evidence, check `.cx/knowledge/decisions/strategy/` for any decla
 |---|---|
 | Signal brief | `.cx/knowledge/internal/signals/` |
 | Evidence brief | `.cx/knowledge/internal/evidence-briefs/` |
-| PRD | `docs/prd/` |
+| PRD | `docs/specs/prd/` |
 | PRFAQ | `docs/prfaq/` |
 | Meta PRD | `docs/meta-prd/` |
 | Backlog proposal | pending approval gate: do not file until explicit user approval |

package/skills/docs/runbook-workflow.md

@@ -12,14 +12,14 @@ Use when: creating operational procedures for services, alerts, or recurring ope
 ## Steps
 
 1. **cx-sre** or **cx-release-manager** identifies the need
-2. **Write to `docs/runbooks/{service}-{operation}.md`** using the template from `get_template("runbook")`: resolves `.cx/templates/docs/runbook.md` (override) then `templates/docs/runbook.md` (shipped)
+2. **Write to `docs/operations/runbooks/{service}-{operation}.md`** using the template from `get_template("runbook")`: resolves `.cx/templates/docs/runbook.md` (override) then `templates/docs/runbook.md` (shipped)
 3. **Link from the relevant alert** or monitoring dashboard
 4. **cx-docs-keeper** adds to `.cx/context.md` if it's a critical path runbook
 
 ## File naming
-- `docs/runbooks/telemetry-restart.md`
-- `docs/runbooks/db-migration.md`
-- `docs/runbooks/incident-response.md`
+- `docs/operations/runbooks/telemetry-restart.md`
+- `docs/operations/runbooks/db-migration.md`
+- `docs/operations/runbooks/incident-response.md`
 
 ## Review cadence
 - Runbooks should be tested (table-top or live) at least quarterly

package/skills/exploration/unknown-codebase-onboarding.md

@@ -71,7 +71,7 @@ grep -r 'process\.env\.\|os\.environ\|getenv' --include='*.js' --include='*.py'
 - Leaf nodes are safe to modify; hub changes have blast radius.
 
 **Read the ADRs and postmortems:**
-- Architecture decisions (`docs/adr/`, `decisions/`, `DECISIONS.md`) explain why the code is shaped the way it is.
+- Architecture decisions (`docs/decisions/adr/`, `decisions/`, `DECISIONS.md`) explain why the code is shaped the way it is.
 - Postmortems explain what has already broken and how the system defends against it. Don't break a defense you don't understand.
 
 **Find the test coverage gaps:**

package/skills/operating/orchestration-reference.md

@@ -17,7 +17,7 @@ Construct is the underlying orchestration system for the **current project**. Tr
 The two task-shaped surfaces are siblings, not duplicates:
 
 - **`.cx/workflow.json`**: single project-wide workflow file. Holds the cross-cutting task ledger and intent / category metadata. Drives `workflow_status` and `project_context` MCP tools.
-- **`.cx/task-graphs/<id>.json`**: per-incoming-signal plan generated by `construct graph from-intake <intake-id>`. One graph per triaged inbox file, one node per persona in the recommendedChain, evidence records gating `done`. See [Concepts → Intake and triage](/concepts/intake-and-triage).
+- **`.cx/task-graphs/<id>.json`**: per-incoming-signal plan generated by `construct graph from-intake <intake-id>`. One graph per triaged inbox file, one node per persona in the recommendedChain, evidence records gating `done`. See [Concepts → Intake and triage](/guides/concepts/intake-and-triage).
 
 A signal that becomes durable cross-session work crosses over: the graph nodes are executed, the resulting work is tracked in `.cx/workflow.json` and in beads. The intake queue and task graphs are how new signals enter the loop; the workflow ledger and beads are how durable work is carried.
 

package/skills/routing.md

@@ -126,11 +126,11 @@ Read the matching skill file before responding when the user's request matches t
 | product intelligence, customer notes, field notes, product signals, customer profile, evidence brief, signal brief, backlog proposal | `skills/docs/product-intelligence-workflow.md` | Product Intelligence workflow: evidence to product artifacts |
 | strategy, product strategy, strategic bet, non-bet, north star, time horizon, competitive positioning | `skills/docs/strategy-workflow.md` | Product strategy: read, update, and reason about the strategy store |
 | ingest evidence, ingest customer notes, ingest Slack thread, ingest support ticket, normalize field notes | `skills/docs/evidence-ingest-workflow.md` | Evidence ingest workflow: raw source to .cx/knowledge/ |
-| write a PRD, create requirements, spec out, requirements document, Meta PRD, platform PRD | `skills/docs/prd-workflow.md` | PRD workflow: requirements to docs/prd/ or docs/meta-prd/ |
+| write a PRD, create requirements, spec out, requirements document, Meta PRD, platform PRD | `skills/docs/prd-workflow.md` | PRD workflow: requirements to docs/specs/prd/ or docs/meta-prd/ |
 | write a PRFAQ, working backwards doc, press release FAQ | `skills/docs/prfaq-workflow.md` | PRFAQ workflow: launch narrative from PRD or evidence |
 | create Jira proposal, update Linear, backlog proposal, issue proposal | `skills/docs/backlog-proposal-workflow.md` | Backlog proposal workflow: approval-gated issue tracker changes |
-| record this decision, create an ADR, architecture decision | `skills/docs/adr-workflow.md` | ADR workflow: decision to docs/adr/ file |
-| write a runbook, document this operation, operational procedure | `skills/docs/runbook-workflow.md` | Runbook workflow: operation to docs/runbooks/ file |
+| record this decision, create an ADR, architecture decision | `skills/docs/adr-workflow.md` | ADR workflow: decision to docs/decisions/adr/ file |
+| write a runbook, document this operation, operational procedure | `skills/docs/runbook-workflow.md` | Runbook workflow: operation to docs/operations/runbooks/ file |
 | init project, new project setup, join project, set up doc structure | `skills/docs/init-project.md` | Project initialization via `construct init --docs-preset=*` |
 
 ## Routing Rules

package/specialists/prompts/cx-architect.md

@@ -61,7 +61,7 @@ DATA MODELS: schema with types, constraints, relationships, and migration plan
 DEPENDENCY GRAPH: modules and their directions; flag cycles
 TEST IMPACTS: what needs unit, integration, or E2E coverage
 
-Decision persistence: ask cx-docs-keeper to create or update `docs/adr/ADR-{NNN}-{slug}.md` and `.cx/decisions/{date}-{slug}.md`. If workspace writes aren't available, include the full DECISION rationale inline for docs-keeper to persist.
+Decision persistence: ask cx-docs-keeper to create or update `docs/decisions/adr/ADR-{NNN}-{slug}.md` and `.cx/decisions/{date}-{slug}.md`. If workspace writes aren't available, include the full DECISION rationale inline for docs-keeper to persist.
 
 When producing an implementation plan, use the canonical task format:
 `### T{N}: {title}` sections with **Owner**, **Phase**, **Files**, **Depends on**, **Read first**, **Do not change**, and **Acceptance criteria** fields. This keeps `plan.md` and tracker-linked task slices explicit and preserves the single-writer boundary for each file.

package/specialists/prompts/cx-docs-keeper.md

@@ -72,7 +72,7 @@ Memory write-back: after updating docs, call `create_entities` or `add_observati
 
 Maintenance: keep `.cx/context.md` under 100 lines. Summarize and archive older entries. Check for documentation drift before work is declared complete.
 
-Doc structure: skills at skills/docs/ define the workflow for each doc type. Product Intelligence working artifacts live under .cx/knowledge/. Research: .cx/research/{slug}.md. ADRs: docs/adr/ADR-{NNN}-{slug}.md. PRDs: docs/prd/{date}-{slug}.md. Meta PRDs: docs/meta-prd/{date}-{slug}.md. Runbooks: docs/runbooks/{service}-{operation}.md. Always use the matching template as the starting structure.
+Doc structure: skills at skills/docs/ define the workflow for each doc type. Product Intelligence working artifacts live under .cx/knowledge/. Research: .cx/research/{slug}.md. ADRs: docs/decisions/adr/ADR-{NNN}-{slug}.md. PRDs: docs/specs/prd/{date}-{slug}.md. Meta PRDs: docs/meta-prd/{date}-{slug}.md. Runbooks: docs/operations/runbooks/{service}-{operation}.md. Always use the matching template as the starting structure.
 
 ## Document Quality Loop (Evaluator-Optimizer)
 

package/specialists/prompts/cx-researcher.md

@@ -68,7 +68,7 @@ When querying search engines or paper indexes, always filter or sort by date: ne
 
 ### Step 4: Check internal evidence
 
-Before going external, search: `.cx/research/`, `.cx/knowledge/`, `docs/prd/`, `docs/meta-prd/`, ADRs, runbooks, and ingested artifacts. If a prior research brief exists for the topic, cite and extend it rather than redoing the search from scratch.
+Before going external, search: `.cx/research/`, `.cx/knowledge/`, `docs/specs/prd/`, `docs/meta-prd/`, ADRs, runbooks, and ingested artifacts. If a prior research brief exists for the topic, cite and extend it rather than redoing the search from scratch.
 
 ### Step 5: Verify every URL
 

package/specialists/prompts/cx-sre.md

@@ -100,7 +100,7 @@ Every alert MUST include:
 Alert: service_error_rate
 Trigger: error_rate > 1% for 5m
 Severity: critical
-Runbook: docs/runbooks/service-error-rate.md
+Runbook: docs/operations/runbooks/service-error-rate.md
 Immediate Action: Check error logs, verify dependencies
 Escalation: On-call SRE → Service owner → Incident commander
 Rollback: If deployment-related, revert to last known good

package/specialists/role-manifests.json

@@ -6,7 +6,7 @@
       "events": ["push_gate.fail", "service.down", "mcp.unhealthy.persistent", "edit_loop.stuck"],
       "severityImmediate": ["service.down"],
       "fence": {
-        "allowedPaths": ["docs/runbooks/**", "docs/incidents/**", "docs/postmortems/**"],
+        "allowedPaths": ["docs/operations/runbooks/**", "docs/runbooks/**", "docs/operations/incidents/**", "docs/incidents/**", "docs/postmortems/**"],
         "allowedBdLabels": ["incident", "sre", "reliability"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd link", "bd label"],
         "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:specialists/**"]
@@ -86,7 +86,7 @@
       "events": ["handoff.received", "adr.requested", "arch.boundary.violated"],
       "severityImmediate": [],
       "fence": {
-        "allowedPaths": ["docs/adr/**", "docs/rfc/**", "docs/concepts/architecture.md", "docs/system-design/**"],
+        "allowedPaths": ["docs/decisions/adr/**", "docs/adr/**", "docs/decisions/rfc/**", "docs/rfc/**", "docs/guides/concepts/architecture.md", "docs/concepts/architecture.md", "docs/system-design/**"],
         "allowedBdLabels": ["architecture", "adr", "rfc", "design"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd label"],
         "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:specialists/**"]
@@ -112,7 +112,7 @@
       "events": ["handoff.received", "release.candidate", "version.bump.needed"],
       "severityImmediate": [],
       "fence": {
-        "allowedPaths": ["docs/releases/**", "CHANGELOG.md"],
+        "allowedPaths": ["docs/operations/releases/**", "docs/releases/**", "CHANGELOG.md"],
         "allowedBdLabels": ["release", "version", "shipping"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd label"],
         "approvalRequired": ["commit", "push", "edit:package.json", "edit:lib/**", "edit:bin/**"]
@@ -125,7 +125,7 @@
       "events": ["handoff.received", "backlog.stale", "prd.requested"],
       "severityImmediate": [],
       "fence": {
-        "allowedPaths": ["docs/prd/**", "docs/meta-prd/**", "docs/prfaq/**", "docs/one-pager/**", ".cx/knowledge/**"],
+        "allowedPaths": ["docs/specs/prd/**", "docs/prd/**", "docs/meta-prd/**", "docs/prfaq/**", "docs/one-pager/**", ".cx/knowledge/**"],
         "allowedBdLabels": ["product", "prd", "backlog", "feature"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd label", "bd priority"],
         "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**"]
@@ -197,7 +197,7 @@
       "events": ["handoff.received", "research.requested", "evidence.requested"],
       "severityImmediate": [],
       "fence": {
-        "allowedPaths": ["docs/research/**", ".cx/research/**", "docs/evidence-briefs/**", "docs/signal-briefs/**"],
+        "allowedPaths": ["docs/notes/research/**", "docs/research/**", ".cx/research/**", "docs/evidence-briefs/**", "docs/signal-briefs/**"],
         "allowedBdLabels": ["research", "evidence", "investigation"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd label"],
         "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**"]
@@ -210,7 +210,7 @@
     "explorer": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/explorations/**", ".cx/explorations/**"], "allowedBdLabels": ["exploration", "spike"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["exploration"], "docTypes": ["memo"] }, "handoffCandidates": ["engineer", "architect", "researcher"], "killSwitchEnv": "CONSTRUCT_ROLE_EXPLORER" },
     "operations": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/ops/**", "docs/operations/**"], "allowedBdLabels": ["ops", "operations"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["ops"], "docTypes": ["memo", "runbook"] }, "handoffCandidates": ["sre", "platform-engineer", "release-manager"], "killSwitchEnv": "CONSTRUCT_ROLE_OPERATIONS" },
     "orchestrator": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/**", "plan.md", ".cx/context.md"], "allowedBdLabels": ["orchestration", "workflow", "dispatch"], "allowedCommands": ["bd create", "bd note", "bd update", "bd label", "bd link"], "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:specialists/**"] }, "outputs": { "bdLabels": ["orchestration", "dispatch"], "docTypes": ["memo"] }, "handoffCandidates": ["product-manager", "architect", "engineer", "security", "qa", "sre"], "killSwitchEnv": "CONSTRUCT_ROLE_ORCHESTRATOR" },
-    "rd-lead": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/research/**", "docs/experiments/**", ".cx/experiments/**"], "allowedBdLabels": ["rd", "research", "experiment"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["rd"], "docTypes": ["memo", "research-brief"] }, "handoffCandidates": ["researcher", "architect", "ai-engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_RD_LEAD" },
+    "rd-lead": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/notes/research/**", "docs/research/**", "docs/experiments/**", ".cx/experiments/**"], "allowedBdLabels": ["rd", "research", "experiment"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["rd"], "docTypes": ["memo", "research-brief"] }, "handoffCandidates": ["researcher", "architect", "ai-engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_RD_LEAD" },
     "legal-compliance": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/legal/**", "docs/compliance/**", "docs/security/**", ".cx/knowledge/**"], "allowedBdLabels": ["legal", "compliance", "privacy"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["legal", "compliance"], "docTypes": ["memo"] }, "handoffCandidates": ["security", "product-manager"], "killSwitchEnv": "CONSTRUCT_ROLE_LEGAL_COMPLIANCE" },
     "devil-advocate": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/critiques/**"], "allowedBdLabels": ["critique", "devil-advocate"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["critique"], "docTypes": ["memo"] }, "handoffCandidates": ["architect", "product-manager", "engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_DEVIL_ADVOCATE" }
   }

package/templates/docs/README.md

@@ -0,0 +1,125 @@
+# Doc Templates & Role Anti-Patterns
+
+See `../prompt-surfaces.md` for the canonical public-vs-internal prompt surface model. This document covers only templates and internal role overlays.
+
+Construct specialists produce standard documents (PRDs, ADRs, runbooks, memos, etc.) from shared templates, and they self-check against shared role anti-patterns. Both can be overridden per-project.
+
+## Templates
+
+Shipped templates live in [`templates/docs/`](../../templates/docs/):
+
+| Layer | Path | Purpose |
+|---|---|---|
+| Specialist source | `templates/docs/{name}.md` | Canonical shape for `get_template()` MCP |
+| Init lane starters | `docs/{lane}/templates/` | Copied into downstream projects by `construct init --docs-preset=*` |
+| Project override | `.cx/templates/docs/{name}.md` | Per-project template override at fetch time |
+
+Do not duplicate starters at `docs/{lane}/_template.md` — lane READMEs link only to `./templates/`.
+
+| Template | Produced by | Purpose |
+|---|---|---|
+| `prd.md` | cx-product-manager | Product requirements doc |
+| `meta-prd.md` | cx-product-manager, cx-docs-keeper | Requirements for product operating systems, agent workflows, document standards, and evaluation loops |
+| `prfaq.md` | cx-product-manager, cx-business-strategist | Working-backwards press release and FAQ |
+| `evidence-brief.md` | cx-product-manager, cx-ux-researcher, cx-researcher | Product evidence synthesis before decisions |
+| `signal-brief.md` | cx-product-manager, cx-researcher | Weak or emerging product signal preservation |
+| `customer-profile.md` | cx-product-manager, cx-docs-keeper | Durable customer/account product memory |
+| `product-intelligence-report.md` | cx-product-manager, cx-business-strategist | Cross-source product intelligence synthesis |
+| `backlog-proposal.md` | cx-product-manager | Approval-gated external tracker proposal |
+| `memo.md` | cx-business-strategist | Strategy memo (~1 page) |
+| `one-pager.md` | cx-product-manager, cx-business-strategist | Executive one-pager |
+| `adr.md` | cx-architect, cx-rd-lead | Architecture decision record |
+| `research-brief.md` | cx-researcher, cx-ux-researcher, cx-explorer | Research findings |
+| `runbook.md` | cx-sre, cx-operations | Operational runbook |
+| `incident-report.md` | cx-sre, cx-operations, cx-release-manager | Post-mortem |
+
+### How specialists use them
+
+Each specialist prompt points to the template via an MCP call:
+
+```markdown
+**Template**: call `get_template("prd")` when drafting a product PRD, or `get_template("meta-prd")` when drafting a Meta PRD, ...
+```
+
+The `get_template(name)` MCP tool (see [`lib/mcp/server.mjs`](../../lib/mcp/server.mjs)) resolves:
+
+1. `.cx/templates/docs/{name}.md`: **project override** (preferred if present)
+2. `templates/docs/{name}.md`: **shipped default** (fallback)
+
+Use `list_templates` to see both shipped and overridden names.
+
+### Overriding a template
+
+Drop a file at `.cx/templates/docs/{name}.md` inside your project. That's it: next time a specialist drafts that doc type, they'll pick up your version. No sync, no restart.
+
+Example: reshape the PRD to lead with success metrics:
+
+```bash
+mkdir -p .cx/templates/docs
+cp templates/docs/prd.md .cx/templates/docs/prd.md
+# edit .cx/templates/docs/prd.md to your shape
+```
+
+Ask Construct for a PRD; it'll follow the new shape.
+
+## Role Anti-Patterns
+
+Each specialist is cognitively rooted in a **role** (product-manager, engineer, architect, etc.) with a core set of failure modes to avoid. Flavored specialists extend the core with an overlay.
+
+Core roles live in [`skills/roles/`](../../skills/roles/):
+
+| Core role | Flavors | Applied to |
+|---|---|---|
+| `engineer` | `engineer.ai`, `engineer.data`, `engineer.platform` | cx-engineer, cx-ai-engineer, cx-data-engineer, cx-platform-engineer |
+| `reviewer` | `reviewer.devil-advocate`, `reviewer.evaluator`, `reviewer.trace` | cx-reviewer, cx-devil-advocate, cx-evaluator, cx-trace-reviewer |
+| `researcher` | `researcher.ux`, `researcher.explorer` | cx-researcher, cx-ux-researcher, cx-explorer |
+| `operator` | `operator.sre`, `operator.release`, `operator.docs` | cx-sre, cx-release-manager, cx-operations, cx-docs-keeper |
+| `product-manager` | `product-manager.product`, `product-manager.platform`, `product-manager.enterprise`, `product-manager.ai-product`, `product-manager.growth`, `product-manager.business-strategy` | cx-product-manager, cx-business-strategist |
+| `designer` | `designer.accessibility` | cx-designer, cx-accessibility |
+| `security` | `security.legal-compliance` | cx-security, cx-legal-compliance |
+| `qa` | `qa.test-automation` | cx-qa, cx-test-automation |
+| `architect` |: | cx-architect, cx-rd-lead |
+| `debugger` |: | cx-debugger |
+| `data-analyst` |: | cx-data-analyst |
+| `orchestrator` |: | cx-orchestrator |
+
+### How they're loaded
+
+Unlike templates, role anti-patterns are **inlined at sync time** (not fetched at runtime). The specialist source prompt carries a marker:
+
+```markdown
+**Anti-patterns**: call `get_skill("roles/engineer.ai")` before drafting.
+```
+
+`construct sync` (via [`lib/role-preload.mjs`](../../lib/role-preload.mjs)) replaces that line with the full core role body + flavor overlay under `## Role anti-patterns`. The content is always present in the final platform prompt: no runtime dependency, no chance for the model to skip the pre-work.
+
+### Editing or adding roles
+
+- **Edit a role**: change the file under `skills/roles/`, then run `construct sync` to propagate to all platforms.
+- **Add a flavor**: create `skills/roles/{core}.{flavor}.md` with YAML frontmatter:
+  ```yaml
+  ---
+  role: {core}.{flavor}
+  applies_to: [cx-...]
+  inherits: {core}
+  version: 1
+  ---
+  ```
+  Update the corresponding `cx-*.md` source prompt to reference the new flavor name, then `construct sync`.
+- **No project-level override for roles** today: roles are platform-wide and curated. If you need per-project role overrides, open a request.
+
+## Verification
+
+After editing either surface, run:
+
+```bash
+npm test                 # tests/agent-prompts.test.mjs covers both
+node scripts/sync-agents.mjs   # regenerate platform adapters
+construct doctor         # health check
+```
+
+Spot-check propagation:
+
+```bash
+grep -l "## Role anti-patterns" ~/.claude/agents/cx-*.md
+```

package/templates/docs/construct_guide.md

@@ -33,11 +33,10 @@ Generated tooling (`.construct/`, `.claude/`, `.cx/`, `plan.md`) is gitignored;
 
 ## Where to drop information you want Construct to use
 
-Three intake paths, ordered by formality:
+Two 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 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.
+1. **`inbox/`** — the single canonical drop zone. 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. For large or slowly-written files, stage under `inbox/.staging/` and rename in so the watcher never sees a half-written file.
+2. **`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:
 

package/templates/docs/persona-artifact.md

@@ -1,6 +1,6 @@
 # <Role display name>
 
-> Anchor doc for the <role-id> persona. Methodology: `docs/concepts/persona-research.md`. This file is generated by `construct profile create` and is part of the discover + frame phases. The persona is not promotable until every section below is filled from evidence, not opinion.
+> Anchor doc for the <role-id> persona. Methodology: `docs/guides/concepts/persona-research.md`. This file is generated by `construct profile create` and is part of the discover + frame phases. The persona is not promotable until every section below is filled from evidence, not opinion.
 
 ## Goals
 

package/templates/docs/prds/README.md

@@ -0,0 +1,25 @@
+---
+cx_doc_id: 019ddb68-5aeb-7c30-9c7e-0d994ab6c06b
+created_at: "2026-04-29T22:42:22.571Z"
+updated_at: "2026-04-29T22:42:22.572Z"
+generator: construct/init-docs
+body_hash: "sha256:64607fda2fa55def5dd8af0e31f88cf190f68841da0223b45f0d36db83221669"
+---
+<!--
+templates/docs/prds/README.md: lane guide for PRDs.
+
+Generated from the Construct documentation lane templates. Keep this lane focused on one document
+family. If it no longer has a distinct purpose, prune it or merge it elsewhere.
+-->
+
+# PRDs
+
+Product and capability requirement documents.
+
+## Starter templates
+
+- [_template.md](./templates/_template.md)
+- [meta-prd.template.md](./templates/meta-prd.template.md)
+- [prd-business.template.md](./templates/prd-business.template.md)
+- [prd-platform.template.md](./templates/prd-platform.template.md)
+- [prfaq.template.md](./templates/prfaq.template.md)