@geraldmaron/construct 1.2.1 → 1.2.3

package/platforms/claude/settings.template.json

@@ -9,7 +9,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/session-start.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/session-start.mjs\"",
             "timeout": 10
           }
         ],
@@ -23,7 +23,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/policy-engine.mjs\" PreToolUse",
+            "command": "node \"$HOME/.config/construct/lib/hooks/policy-engine.mjs\" PreToolUse",
             "timeout": 10
           }
         ],
@@ -35,7 +35,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/orchestration-dispatch-guard.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/orchestration-dispatch-guard.mjs\"",
             "timeout": 5
           }
         ],
@@ -47,7 +47,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/block-no-verify.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/block-no-verify.mjs\"",
             "timeout": 5
           }
         ],
@@ -59,7 +59,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/pre-push-gate.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/pre-push-gate.mjs\"",
             "timeout": 180
           }
         ],
@@ -71,7 +71,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/guard-bash.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/guard-bash.mjs\"",
             "timeout": 5
           }
         ],
@@ -83,7 +83,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/config-protection.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/config-protection.mjs\"",
             "timeout": 5
           }
         ],
@@ -95,7 +95,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/mcp-health-check.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/mcp-health-check.mjs\"",
             "timeout": 3
           }
         ],
@@ -107,7 +107,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/edit-guard.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/edit-guard.mjs\"",
             "timeout": 5
           }
         ],
@@ -133,7 +133,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/scan-secrets.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/scan-secrets.mjs\"",
             "timeout": 10
           }
         ],
@@ -145,7 +145,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/adaptive-lint.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/adaptive-lint.mjs\"",
             "timeout": 30,
             "async": true
           }
@@ -158,7 +158,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/comment-lint.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/comment-lint.mjs\"",
             "timeout": 15
           }
         ],
@@ -170,7 +170,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/brand-prose-lint.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/brand-prose-lint.mjs\"",
             "timeout": 15
           }
         ],
@@ -182,7 +182,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/artifact-release-gate.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/artifact-release-gate.mjs\"",
             "timeout": 15
           }
         ],
@@ -194,7 +194,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/doc-coupling-check.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/doc-coupling-check.mjs\"",
             "timeout": 5
           }
         ],
@@ -206,7 +206,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/graph-impact-advisory.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/graph-impact-advisory.mjs\"",
             "timeout": 10
           }
         ],
@@ -218,7 +218,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/edit-accumulator.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/edit-accumulator.mjs\"",
             "timeout": 3
           }
         ],
@@ -230,7 +230,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/registry-sync.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/registry-sync.mjs\"",
             "timeout": 15,
             "async": true
           }
@@ -243,7 +243,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/dep-audit.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/dep-audit.mjs\"",
             "timeout": 35,
             "async": true
           }
@@ -256,7 +256,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/audit-reads.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/audit-reads.mjs\"",
             "timeout": 3,
             "async": true
           }
@@ -269,7 +269,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/mcp-audit.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/mcp-audit.mjs\"",
             "timeout": 3,
             "async": true
           }
@@ -282,7 +282,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/agent-tracker.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/agent-tracker.mjs\"",
             "timeout": 3,
             "async": true
           }
@@ -295,7 +295,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/bash-output-logger.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/bash-output-logger.mjs\"",
             "timeout": 5
           }
         ],
@@ -307,7 +307,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/test-watch.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/test-watch.mjs\"",
             "timeout": 5,
             "async": true
           }
@@ -320,7 +320,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/post-merge-docs-check.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/post-merge-docs-check.mjs\"",
             "timeout": 5,
             "async": true
           }
@@ -333,7 +333,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/post-merge-tracking.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/post-merge-tracking.mjs\"",
             "timeout": 5,
             "async": true
           }
@@ -346,7 +346,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/audit-trail.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/audit-trail.mjs\"",
             "timeout": 5
           }
         ],
@@ -358,7 +358,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/orchestration-dispatch-guard.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/orchestration-dispatch-guard.mjs\"",
             "timeout": 5
           }
         ],
@@ -372,7 +372,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/model-fallback.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/model-fallback.mjs\"",
             "timeout": 130,
             "async": true
           }
@@ -385,7 +385,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/mcp-health-check.mjs\" --mark-failure",
+            "command": "node \"$HOME/.config/construct/lib/hooks/mcp-health-check.mjs\" --mark-failure",
             "timeout": 3
           }
         ],
@@ -397,7 +397,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/context-window-recovery.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/context-window-recovery.mjs\"",
             "timeout": 60,
             "async": true
           }
@@ -410,7 +410,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/edit-error-recovery.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/edit-error-recovery.mjs\"",
             "timeout": 15,
             "async": true
           }
@@ -425,7 +425,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/pre-compact.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/pre-compact.mjs\"",
             "timeout": 15
           }
         ],
@@ -439,7 +439,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/policy-engine.mjs\" Stop",
+            "command": "node \"$HOME/.config/construct/lib/hooks/policy-engine.mjs\" Stop",
             "timeout": 15
           }
         ],
@@ -451,7 +451,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/stop-typecheck.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/stop-typecheck.mjs\"",
             "timeout": 120,
             "async": true
           }
@@ -464,7 +464,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/readme-age-check.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/readme-age-check.mjs\"",
             "timeout": 5,
             "async": true
           }
@@ -477,7 +477,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/stop-notify.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/stop-notify.mjs\"",
             "timeout": 10,
             "async": true
           }
@@ -490,7 +490,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/pre-compact.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/pre-compact.mjs\"",
             "timeout": 15,
             "async": true
           }
@@ -503,7 +503,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/session-optimize.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/session-optimize.mjs\"",
             "timeout": 600,
             "async": true
           }
@@ -516,7 +516,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/session-reflect.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/session-reflect.mjs\"",
             "timeout": 5,
             "async": true
           }
@@ -529,7 +529,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/session-tracking-refresh.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/session-tracking-refresh.mjs\"",
             "timeout": 5,
             "async": true
           }
@@ -544,7 +544,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/context-watch.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/context-watch.mjs\"",
             "timeout": 5
           }
         ],
@@ -556,7 +556,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/ci-status-check.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/ci-status-check.mjs\"",
             "timeout": 5
           }
         ],

package/rules/common/no-fabrication.md

@@ -55,7 +55,7 @@ Fabrication is the single largest threat to trust in an agent system. A persona
 
 ## Enforcement
 
-- `lib/comment-lint.mjs` enforces a subset of these patterns on artifact paths (`docs/prd/**`, `docs/adr/**`, `docs/rfc/**`, `docs/research/**`, `.cx/knowledge/**`, `.cx/handoffs/**`, `.cx/research/**`). PostToolUse warns; `npm run lint:comments`, `construct lint:comments`, and the release gate block.
+- `lib/comment-lint.mjs` enforces a subset of these patterns on artifact paths (`docs/specs/prd/**`, `docs/decisions/adr/**`, `docs/decisions/rfc/**`, `docs/notes/research/**`, `.cx/knowledge/**`, `.cx/handoffs/**`, `.cx/research/**`). PostToolUse warns; `npm run lint:comments`, `construct lint:comments`, and the release gate block.
 - `specialists/contracts.json` postconditions check structural requirements (mandatory sections, intake traceability, citation density). `lib/contracts/validate.mjs#validateHandoff` blocks handoffs that fail validation; binary postconditions in `lib/specialists/postconditions.mjs` block rubber-stamp reviews, post-hoc threat models, symptom-only fixes, stale-doc PRs, and post-hoc accessibility. Enforcement is hard-default `block`.
 - `construct intake done <id> --output=<path>` stamps `intake_id`, `intake_confidence`, and `intake_rationale` into the artifact's frontmatter so every intake-derived artifact carries verifiable provenance.
 

package/rules/common/release-gates.md

@@ -42,7 +42,7 @@ For every non-trivial change:
 
 1. **A Beads issue exists.** `bd ready` to find or create one. `bd show <id>` to read context. `bd update <id> --claim` to claim before editing files.
 2. **`plan.md` reflects the work.** Even though `plan.md` is local-only and gitignored, it stays the human-readable working plan. Mark items `done` when they ship; add new rows for work that wasn't previously tracked.
-3. **Doc updates land in the same change as code.** If runtime shape, contracts, boundaries, or major dependencies changed, update `docs/concepts/architecture.md` in the same commit. If the docs surface or maintenance contract changed, update `docs/README.md`. If active work, decisions, or assumptions changed, update `.cx/context.md` and `.cx/context.json`. Always add a `CHANGELOG.md` entry.
+3. **Doc updates land in the same change as code.** If runtime shape, contracts, boundaries, or major dependencies changed, update `docs/guides/concepts/architecture.md` in the same commit. If the docs surface or maintenance contract changed, update `docs/README.md`. If active work, decisions, or assumptions changed, update `.cx/context.md` and `.cx/context.json`. Always add a `CHANGELOG.md` entry.
 4. **Beads close on green.** `bd close <id>` happens after CI is green and the work is verified: not before.
 
 ## Hard rules

package/rules/common/research.md

@@ -47,7 +47,7 @@ Start with the narrowest authoritative source that can answer the question:
 1. **Local project evidence first**
    - `.cx/research/`
    - `.cx/knowledge/`
-   - `docs/prd/`, `docs/meta-prd/`, `docs/adr/`, `docs/runbooks/`
+   - `docs/specs/prd/`, `docs/meta-prd/`, `docs/decisions/adr/`, `docs/operations/runbooks/`
    - ingested markdown artifacts under `.cx/knowledge/`
    - repo code, tests, configs, and existing decisions
 2. **Primary external sources second**

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:**