baldart 4.0.4 → 4.1.0

package/framework/.claude/agents/prd.md

@@ -49,12 +49,12 @@ When the feature being planned is for **Customers** (B2C users), you MUST invoke
 - The Implementation Plan - add gamification-specific validation steps
 
 **Repository Scan** (always perform):
-- Read AGENTS.md, agents/index.md, and docs/references/project-status.md
-- Examine docs/references/data-model.md for schema understanding
-- Review docs/references/api/index.md for API surface
-- Check docs/references/ui/index.md for UI structure
-- Scan backlog/*.yml for existing cards and naming conventions
-- Review docs/decisions/*.md for architectural decisions
+- Read AGENTS.md, agents/index.md, and ${paths.references_dir}/project-status.md
+- Examine ${paths.references_dir}/data-model.md for schema understanding
+- Review ${paths.references_dir}/api/index.md for API surface
+- Check ${paths.references_dir}/ui/index.md for UI structure
+- Scan ${paths.backlog_dir}/*.yml for existing cards and naming conventions
+- Review ${paths.adrs_dir}/*.md for architectural decisions
 - Check src/ structure for code organization
 - Look at package.json for dependencies and scripts
 
@@ -473,7 +473,7 @@ This means cards 04 and 05 run in parallel, card 06 depends on both.
 
 Every implementation plan MUST include these cards (as the last steps):
 
-1. **Documentation card** (owner: `doc-reviewer`) — update `docs/references/*` to reflect the new feature
+1. **Documentation card** (owner: `doc-reviewer`) — update `${paths.references_dir}/*` to reflect the new feature
 2. **Code review card** (owner: `code-reviewer`) — review all implementation cards before marking DONE
 
 These can be a single combined card for small features.
@@ -498,7 +498,7 @@ Create protocol-compliant backlog cards for every actionable step. Cards MUST fo
 
 #### 4.1 — NAMING CONVENTIONS
 
-Before creating cards, scan `backlog/*.yml` to determine the next available number. File naming rules:
+Before creating cards, scan `${paths.backlog_dir}/*.yml` to determine the next available number. File naming rules:
 
 | Prefix | When to use | Example |
 |--------|-------------|---------|
@@ -516,7 +516,7 @@ When a feature requires multiple cards, create a **parent card** (epic) and **ch
 
 **Parent card** (epic): Contains the full feature overview, PRD link, and lists all child cards.
 ```yaml
-# File: backlog/FEAT-NNNN-feature-name.yml  (parent/epic)
+# File: ${paths.backlog_dir}/FEAT-NNNN-feature-name.yml  (parent/epic)
 id: FEAT-NNNN
 title: "[Feature Name] — Epic"
 status: TODO
@@ -535,7 +535,7 @@ child_cards:
   - FEAT-NNNN-03  # [Brief description]
 
 links:
-  prd: docs/prd/FEAT-NNNN-feature-name.md
+  prd: ${paths.prd_dir}/FEAT-NNNN-feature-name.md
 
 notes: |
   Parent epic. See child cards for implementation.
@@ -543,7 +543,7 @@ notes: |
 
 **Child card**: References parent, declares dependencies on sibling cards.
 ```yaml
-# File: backlog/FEAT-NNNN-NN-child-slug.yml
+# File: ${paths.backlog_dir}/FEAT-NNNN-NN-child-slug.yml
 id: FEAT-NNNN-NN
 title: "[Imperative title for this piece]"
 status: TODO  # TODO | READY | IN_PROGRESS | BLOCKED | DONE
@@ -563,7 +563,7 @@ git_strategy:                        # OBJECT (per card-template.yml SSOT), neve
 #### 4.3 — CARD TEMPLATE (FEATURE CARDS)
 
 ```yaml
-# File: backlog/FEAT-NNNN-NN-slug.yml
+# File: ${paths.backlog_dir}/FEAT-NNNN-NN-slug.yml
 id: FEAT-NNNN-NN
 title: "[Imperative title]"
 status: TODO  # TODO | READY | IN_PROGRESS | BLOCKED | DONE
@@ -582,7 +582,7 @@ git_strategy:                        # OBJECT (per card-template.yml SSOT), neve
 context: |
   [Background, motivation, and links to PRD requirement IDs: FR-001, NFR-002]
   PRD Reference: [FR-XXX to FR-YYY]
-  Epic: backlog/FEAT-NNNN-feature-name.yml
+  Epic: ${paths.backlog_dir}/FEAT-NNNN-feature-name.yml
 
 scope:
   summary: "[1-2 sentence description]"
@@ -607,7 +607,7 @@ files_likely_touched:
 definition_of_done:
   - "[ ] Code implemented and reviewed"
   - "[ ] CI checks pass on PR"
-  - "[ ] docs/references/* updated (api-surface, data-model, ui-pages, project-status)"
+  - "[ ] ${paths.references_dir}/* updated (api-surface, data-model, ui-pages, project-status)"
   - "[ ] No build errors"
 
 test_plan: |
@@ -624,7 +624,7 @@ assumptions:
   - "[A-1] Assumption made — mark ASSUMED with rationale per AGENTS.md"
 
 links:
-  prd: docs/prd/FEAT-NNNN-feature-name.md
+  prd: ${paths.prd_dir}/FEAT-NNNN-feature-name.md
   related_features: []
 
 notes: ""
@@ -639,7 +639,7 @@ metadata:
 Bug cards have additional mandatory fields per AGENTS.md (mandatory clarity analysis):
 
 ```yaml
-# File: backlog/BUG-NNNN-issue-NNN-slug.yml
+# File: ${paths.backlog_dir}/BUG-NNNN-issue-NNN-slug.yml
 id: BUG-NNNN
 title: "[Fix: imperative description]"
 status: TODO
@@ -694,7 +694,7 @@ Record `git_strategy` as an OBJECT in every card — `{ branch: "feat/FEAT-NNNN-
 
 - One card per atomic deliverable (no mega-cards)
 - **Break large cards into smaller scoped tasks** — each card should be completable in a single agent session with a clean build/test/lint cycle. If a card touches more than 5-7 files or spans multiple concerns (e.g., API + UI + docs), split it.
-- Scan `backlog/*.yml` to determine the next available number in the sequence
+- Scan `${paths.backlog_dir}/*.yml` to determine the next available number in the sequence
 - Each card must be independently testable
 - Each card's acceptance criteria MUST include build/lint/test passing
 - Link to PRD requirement IDs (FR-###, NFR-###) in the `context` field

package/framework/.claude/agents/security-reviewer.md

@@ -269,7 +269,7 @@ When you need to examine code, use Glob/Grep to find actual file paths before re
 
 - Respect `AGENTS.md` as authoritative.
 - Use `codebase-architect` for architecture discovery before broad security recommendations that depend on current structure.
-- Treat `docs/references/project-status.md` as transient coordination context, not canonical feature truth.
+- Treat `${paths.references_dir}/project-status.md` as transient coordination context, not canonical feature truth.
 - When you find a security issue that implies doc or ADR drift, flag the required follow-up explicitly.
 
 **Update your agent memory** as you discover security patterns, recurring vulnerabilities, authorization model details, trust boundaries, secrets handling patterns, and attack surface characteristics in this codebase. This builds institutional security knowledge across reviews.

package/framework/.claude/agents/senior-researcher.md

@@ -18,7 +18,7 @@ You are **Senior Researcher**, a web-native research specialist with 20+ years o
 Before external web searches, check if the answer exists in the project's documentation:
 
 1. Use `search_docs` MCP tool (if available) with `mode: "hybrid"` to query the project's Obsidian-first LightRAG index semantically. Treat Obsidian hits as primary knowledge and verify implementation/stateful claims against repo docs/code before relying on them.
-2. If MCP is unavailable, fall back to targeted canonical docs plus `rg` over `docs/`, `backlog/`, and `.claude/agents/`.
+2. If MCP is unavailable, fall back to targeted canonical docs plus `rg` over `${paths.docs_dir}/`, `${paths.backlog_dir}/`, and `.claude/agents/`.
 3. Internal findings should be cited alongside external research.
 
 ## MISSION

package/framework/.claude/agents/skill-improver.md

@@ -19,7 +19,7 @@ findings and automatically improve the skill/agent instructions to prevent recur
 
 **MUST NOT MODIFY:**
 - Any file under `src/` — no application code
-- `backlog/`, `docs/prd/`, `docs/decisions/` — no product docs
+- `${paths.backlog_dir}/`, `${paths.prd_dir}/`, `${paths.adrs_dir}/` — no product docs
 - `.claude/settings.json` — no infra config changes
 
 ## Weekly Analysis Process

package/framework/.claude/agents/visual-designer.md

@@ -15,16 +15,16 @@ You are the Visual Designer, an expert in visual design and API-driven image gen
 
 ## Authoritative Style Reference
 
-**MUST read `docs/references/ui-guidelines.md` before any design work.** This is the single source of truth for ALL visual style decisions: brand identity, color palette, design system rules, component patterns, SVG illustration standards, image format requirements, and text embedding policy.
+**MUST read `${paths.references_dir}/ui-guidelines.md` before any design work.** This is the single source of truth for ALL visual style decisions: brand identity, color palette, design system rules, component patterns, SVG illustration standards, image format requirements, and text embedding policy.
 
 **Never hard-code style rules in your reasoning.** Always derive visual decisions (colors, strokes, shadows, shapes, DO/DON'T rules) from the guidelines document. If the guidelines don't cover a case, flag it and propose an addition.
 
 ## YOUR ROLE & BOUNDARIES
 
-You design and generate visual assets according to the style defined in `docs/references/ui-guidelines.md`. You directly call the configured image generation API to generate images, poll for completion, download results, and prepare both original and WebP-optimized versions.
+You design and generate visual assets according to the style defined in `${paths.references_dir}/ui-guidelines.md`. You directly call the configured image generation API to generate images, poll for completion, download results, and prepare both original and WebP-optimized versions.
 
 **You DO:**
-- Create visual style guides derived from `docs/references/ui-guidelines.md`
+- Create visual style guides derived from `${paths.references_dir}/ui-guidelines.md`
 - Design asset inventories for pages and sections
 - Write and execute image generation API requests
 - Poll for task completion and download results
@@ -41,7 +41,7 @@ You design and generate visual assets according to the style defined in `docs/re
 Before generating assets, you need:
 1. Messaging framework (ICP, value prop, proof, tone)
 2. UI page structure + section list (from ui-expert agent)
-3. Brand constraints (read from `docs/references/ui-guidelines.md`, plus any brand-specific overrides)
+3. Brand constraints (read from `${paths.references_dir}/ui-guidelines.md`, plus any brand-specific overrides)
 
 If any of these are missing, ask at most 5 targeted questions, then proceed with clearly labeled [ASSUMPTION] tags.
 
@@ -50,7 +50,7 @@ If any of these are missing, ask at most 5 targeted questions, then proceed with
 You MUST produce these deliverables in this exact order:
 
 ### 1) VISUAL_STYLE_GUIDE
-- Style interpretation for the specific brand/context, derived from `docs/references/ui-guidelines.md`
+- Style interpretation for the specific brand/context, derived from `${paths.references_dir}/ui-guidelines.md`
 - Primary and accent color definitions with hex codes (from guidelines palette)
 - Composition rules (grid, alignment, spacing)
 - Illustration rules (stroke weight, fill style, shadow treatment)
@@ -164,7 +164,7 @@ When generation produces weak results:
 ## QUALITY CONTROL
 
 Before finalizing any asset:
-1. Verify style compliance against `docs/references/ui-guidelines.md`
+1. Verify style compliance against `${paths.references_dir}/ui-guidelines.md`
 2. **Verify transparent background** — all illustrations MUST have no background. If the generated image has a solid/colored background, regenerate with stronger transparency instructions
 3. Check contrast ratios for accessibility
 4. Confirm no text is embedded in image

package/framework/.claude/agents/wiki-curator.md

@@ -1,6 +1,6 @@
 ---
 name: wiki-curator
-description: "Maintain the derived LLM wiki surface under docs/wiki/. Use when the team needs compiled concept pages, synthesis pages, dashboards, or reading guides that sit on top of canonical SSOT docs (and optionally an Obsidian vault + RAG layer) without becoming canonical themselves."
+description: "Maintain the derived LLM wiki surface under ${paths.wiki_dir}/. Use when the team needs compiled concept pages, synthesis pages, dashboards, or reading guides that sit on top of canonical SSOT docs (and optionally an Obsidian vault + RAG layer) without becoming canonical themselves."
 model: sonnet
 color: blue
 ---
@@ -14,7 +14,7 @@ Maintain the derived wiki overlay without weakening SSOT discipline.
 ## Responsibilities
 
 - Read canonical repo docs and approved Obsidian notes.
-- Create or update derived wiki pages under `docs/wiki/`.
+- Create or update derived wiki pages under `${paths.wiki_dir}/`.
 - Prefer compact synthesis over duplication.
 - Preserve explicit provenance and canonical references on every page.
 - Keep pages small enough to recompile quickly.
@@ -35,7 +35,7 @@ the project's `search_docs` (or equivalent) MUST pass an invoker tag so
 telemetry attributes wiki-curation queries to this agent. After each call,
 inspect the telemetry verdict: if it is `weak`, `empty`, or `fallback_degraded`,
 append one entry to a log file under your wiki overlay (typically
-`docs/wiki/log.md`) via the project's log helper (e.g. `tools/<rag-impl>/wiki_log.py`).
+`${paths.wiki_dir}/log.md`) via the project's log helper (e.g. `tools/<rag-impl>/wiki_log.py`).
 
 Example call shape:
 
@@ -71,8 +71,8 @@ During nightly wiki-review, scan recent ADRs and PRDs (last 14 days):
 
 - For ADRs with significant architectural impact (touches >3 modules, marked as architectural pivot, or under categories: provider swap / DB schema / auth / API contract) → propose a synthesis page candidate.
 - For PRD-led multi-card epics (≥4 cards in same parent epic) → propose an overview synthesis.
-- For RAG queries with `verdict=weak|empty` repeated ≥3 times in `docs/wiki/log.md` → the topic is a documentation gap, propose synthesis.
-- Output candidates by appending to `docs/wiki/log.md` with `entry_type: synthesis_candidate` and including: title, source refs, expected scope, agent who triggered.
+- For RAG queries with `verdict=weak|empty` repeated ≥3 times in `${paths.wiki_dir}/log.md` → the topic is a documentation gap, propose synthesis.
+- Output candidates by appending to `${paths.wiki_dir}/log.md` with `entry_type: synthesis_candidate` and including: title, source refs, expected scope, agent who triggered.
 
 ## Frontmatter Discipline
 
@@ -128,7 +128,7 @@ Telemetry parity: pass `invoker_agent: "wiki-curator"` on every call; the
 existing `wiki_log` weak-verdict instrumentation applies unchanged.
 
 The community detector also appends `entry_type: graph_community_candidate`
-entries to `docs/wiki/log.md` for newly-detected clusters (≥10 entities) that
+entries to `${paths.wiki_dir}/log.md` for newly-detected clusters (≥10 entities) that
 do not yet have a synthesis page. These are first-class candidates for the
 next nightly wiki-review.
 

package/framework/.claude/commands/check.md

@@ -15,7 +15,7 @@ Look for backlog cards with status `TODO` or `READY` that need pre-development v
 - If cards are identifiable from the conversation context → use those.
 - If not → ask the user which card IDs to check (accept same formats as `/new`: space-separated, comma-separated, or hyphen-range).
 
-Read each card from `/backlog/*.yml` to understand scope, requirements, acceptance criteria, and planned changes.
+Read each card from `${paths.backlog_dir}/*.yml` to understand scope, requirements, acceptance criteria, and planned changes.
 
 ## Step 2 — Choose Audit Profile
 

package/framework/.claude/commands/codexreview.md

@@ -18,7 +18,7 @@ If card IDs are provided as arguments, use them directly and skip this step.
 If `/codexreview` is invoked **without card IDs**, infer them from context in this order:
 
 1. **Recent git commits on current branch**: run `git log --oneline -10` and extract card IDs from commit messages matching patterns `[FEAT-\d+]`, `[BUG-\d+]`, `[TECH-\d+]`, `[UI-\d+]` (and any other project-specific prefixes — adapt to your taxonomy).
-2. **In-progress backlog cards**: run `grep -rl "status: IN_PROGRESS" /backlog/*.yml` and read their `id` fields.
+2. **In-progress backlog cards**: run `grep -rl "status: IN_PROGRESS" ${paths.backlog_dir}/*.yml` and read their `id` fields.
 3. **Current branch name**: parse the branch name (e.g. `feat/FEAT-0123-slug` → `FEAT-0123`).
 
 The patterns above (`FEAT-`, `BUG-`, `TECH-`, `UI-`) are BALDART's default taxonomy; consumer
@@ -81,7 +81,7 @@ inherits a stale lean contract from a prior `/new` run. Record the resolved mode
 
 For each provided card ID:
 
-1. Resolve the card file with Glob in `/backlog/*.yml`.
+1. Resolve the card file with Glob in `${paths.backlog_dir}/*.yml`.
 2. Read the card YAML and extract at minimum:
    - `id`, `title`, `status`
    - `acceptance_criteria`

package/framework/.claude/commands/qa.md

@@ -20,7 +20,7 @@ You are the **QA Orchestrator**. When the user invokes `/qa [profile] [--card FE
 **Auto-detect card** (in order, stop at first match):
 1. Extract from current branch: `git rev-parse --abbrev-ref HEAD` → pattern `feat/FEAT-XXXX-*` or `codex/FEAT-XXXX-*` or `claude/FEAT-XXXX-*` → capture ID.
 2. Extract from latest commit: `git log -1 --pretty=%s` → pattern `[FEAT-XXXX]` or `[DIO-XXXX]` → capture ID.
-3. Scan `/backlog/*.yml` for a card with `status: IN_PROGRESS` assigned to current work context.
+3. Scan `${paths.backlog_dir}/*.yml` for a card with `status: IN_PROGRESS` assigned to current work context.
 4. Fallback: use timestamp session ID `session-YYYYMMDD-HHMM` (compute from current date/time).
 
 ---

package/framework/.claude/skills/bug/SKILL.md

@@ -16,7 +16,7 @@ Argument: optional bug description (e.g., `/bug feature X is not saving`).
 
 ## Project Context
 
-**Reads from `baldart.config.yml`:** `paths.design_system`, `paths.references_dir`.
+**Reads from `baldart.config.yml`:** `paths.design_system`, `paths.references_dir`, `paths.wiki_dir` (Phase 0 doc-rag `rg` fallback target).
 **Gated by features:** `features.has_design_system` (when `true`, Phase 4's design-system reads become BLOCKING for UI-touching bugs).
 **Overlay:** loads `.baldart/overlays/bug.md` if present — project-specific debug entry points (e.g. SWR debug switches, env summary helpers, error-code modules). The base skill stays generic; project-specific code paths live in the overlay.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
@@ -29,7 +29,7 @@ See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for th
 - `mcp__playwright__browser_*` (`browser_navigate`, `browser_take_screenshot`, `browser_console_messages`, `browser_network_requests`, `browser_evaluate`) — Phase 1 reproduction for **UI/Client** bugs. Without it the skill cannot capture deterministic state and Phase 1 degrades to "ask the user to reproduce manually and paste console logs". Phase 2's client-side `window.fetch` interception is impossible without `browser_evaluate`.
 
 **Optional** (the skill benefits if present, has a documented fallback):
-- `mcp__doc-rag__search_docs` — Phase 0 lookup for known patterns and error codes. Fallback: targeted `rg` over the project's error-code module (path listed in `.baldart/overlays/bug.md`) and `docs/wiki/`.
+- `mcp__doc-rag__search_docs` — Phase 0 lookup for known patterns and error codes. Fallback: targeted `rg` over the project's error-code module (path listed in `.baldart/overlays/bug.md`) and `${paths.wiki_dir}/`.
 - `mcp__plugin_firebase_firebase__firestore_*` (or the project's DB MCP, when `stack.database.primary` is set) — Phase 1 inspection of runtime data state for **Data** bugs. Fallback: ask the user for a document export, or read the relevant code path and infer.
 - `codebase-architect` agent (always available, listed for completeness) — Phase 0 code-path mapping. Not an MCP per se but is treated as a required dependency by this skill.
 

package/framework/.claude/skills/doc-writing-for-rag/references/line-count-targets.md

@@ -1,5 +1,7 @@
 # Line Count Targets — Dense Documentation Sizing
 
+<!-- contamination-scan: skip — file is 100% illustrative sample-domain examples (fenced split-strategy snippets, bash commands); the docs/references/api/ literals are intentional teaching, not portable contamination. See the disclaimer blockquote below. -->
+
 Soglie validate su 45 file riscritti. Obiettivo: mantenere chunks LightRAG gestibili e signal/noise alto.
 
 > File path examples below (`docs/references/api/booking.md`, ecc.) are taken

package/framework/.claude/skills/doc-writing-for-rag/references/schemas-and-errors.md

@@ -1,5 +1,7 @@
 # Schemas & Errors — Central Reference Files
 
+<!-- contamination-scan: skip — illustrative SAMPLE-domain reference (see disclaimer below); every docs/references/ literal is a worked example or a documented default of the already-tokenized ${paths.api_schemas}/${paths.api_errors}, not portable contamination. -->
+
 > **Illustrative sample domain.** Error codes, routes, and entity names in the
 > examples below are a SAMPLE domain — substitute your own. Only the protocol
 > (central schema/error files, anchor cross-referencing) is normative.

package/framework/.claude/skills/new/SKILL.md

@@ -279,7 +279,7 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
    ```
 
    **Variable interpolation**:
-   - `${CARD_PATHS}`: newline-separated list of all `- backlog/FEAT-XXXX-*.yml` paths in the batch
+   - `${CARD_PATHS}`: newline-separated list of all `- ${paths.backlog_dir}/FEAT-XXXX-*.yml` paths in the batch
    - `${FILE_OWNERSHIP_MAP}`: the file-ownership map built in step 3b
 
    > `<SESSION-ID>` is the current session id (e.g. `$CLAUDE_CODE_SESSION_ID`, or a run UUID if unset). The task-scoped unique name prevents two concurrent `/new` sessions on the same day from clobbering each other's findings (a date-only name silently collides). Record the exact `$AUDIT_FILE` path in the tracker under `## Cross-Card Conflicts (Codex)` so the result-handling step reads the SAME path — never re-derive it by wildcard/timestamp.
@@ -1460,7 +1460,7 @@ The detector (Step A) is bash + grep — guaranteed to run, no LLM skip. The dow
 28. **Mark card DONE (MANDATORY — do NOT skip)**:
     a. Edit the backlog YAML (`${paths.backlog_dir}/<CARD-ID>.yml`): set `status: DONE`, add `completed_date: <today>`.
     b. Add implementation notes summarizing what was built.
-    c. **Update `${paths.references_dir}/ssot-registry.md`** — add/update the entry for this card's feature area. The pre-commit doc-freshness hook BLOCKS commits that touch `backlog/` without a corresponding ssot-registry update. Always include ssot-registry.md in the same commit as the backlog YAML.
+    c. **Update `${paths.references_dir}/ssot-registry.md`** — add/update the entry for this card's feature area. The pre-commit doc-freshness hook BLOCKS commits that touch `${paths.backlog_dir}/` without a corresponding ssot-registry update. Always include ssot-registry.md in the same commit as the backlog YAML.
     d. **Verify the write**: re-read the YAML file and confirm `status: DONE` is present. If not, retry the edit.
     e. Stage BOTH the updated YAML AND ssot-registry.md, then commit (or as an immediate follow-up commit if the Phase 4 implementation commit already happened). When this produces a SECOND commit for the card, record BOTH hashes in the tracker (`commit: <impl-hash> + <done-hash>`) so traceability/bisect is unambiguous.
 29. **Update tracker**: move card to `## Completed Cards` with commit hash(es), summary, flags, **and `card_status: DONE (verified)`**.
@@ -1800,9 +1800,9 @@ The most common failure mode is leaving cards IN_PROGRESS after merge. This crea
    b. **Stage backlog YAMLs AND related docs** (pre-commit hook requires doc updates):
       ```bash
       # Stage only the force-updated backlog YAMLs
-      git add backlog/CARD-001.yml backlog/CARD-002.yml
+      git add ${paths.backlog_dir}/CARD-001.yml ${paths.backlog_dir}/CARD-002.yml
       # If ssot-registry.md was modified during the batch, stage it too
-      # (doc-freshness hook blocks commits that touch backlog/ without ssot-registry.md)
+      # (doc-freshness hook blocks commits that touch ${paths.backlog_dir}/ without ssot-registry.md)
       git diff --name-only ${paths.references_dir}/ssot-registry.md && git add ${paths.references_dir}/ssot-registry.md || true
       ```
    c. **Commit with explicit file list**:

package/framework/.claude/skills/prd/assets/card-template.yml

@@ -27,7 +27,7 @@ git_strategy:
 context: |
   {{Background and motivation. Reference PRD sections.}}
 
-  PRD: docs/prd/{{slug}}/PRD.md ({{FR/NFR refs}})
+  PRD: ${paths.prd_dir}/{{slug}}/PRD.md ({{FR/NFR refs}})
 
 business_rationale: |
   {{2-3 righe che spiegano PERCHÉ questa feature esiste: motivazione di business +
@@ -124,8 +124,8 @@ files_likely_touched:
   - {{path}} ({{NEW|MODIFY}})
 
 links:
-  prd: "docs/prd/{{slug}}/PRD.md"
-  design: "docs/prd/{{slug}}/design.html"  # REQUIRED for UI cards, omit for API-only cards
+  prd: "${paths.prd_dir}/{{slug}}/PRD.md"
+  design: "${paths.prd_dir}/{{slug}}/design.html"  # REQUIRED for UI cards, omit for API-only cards
 
 # --- Canonical Docs (REQUIRED for cards generated from a PRD) ---
 # Traces which SSOT documents informed this card's requirements.

package/framework/.claude/skills/prd/assets/epic-template.yml

@@ -56,8 +56,8 @@ context: |
    - come è strutturato lo storage / data model ad alto livello (1 paragrafo)
   }}
 
-  PRD: docs/prd/{{slug}}/PRD.md
-  Design: docs/prd/{{slug}}/design.html
+  PRD: ${paths.prd_dir}/{{slug}}/PRD.md
+  Design: ${paths.prd_dir}/{{slug}}/design.html
   Cards: {{FEAT-XXXX-01}} .. {{FEAT-XXXX-NN}} ({{N}} sub-card, {{K}} livelli di esecuzione)
 
 business_rationale: |
@@ -148,9 +148,9 @@ execution_strategy:
 # =============================================================================
 
 canonical_docs:
-  prd_ref: docs/prd/{{slug}}/PRD.md
-  design_ref: docs/prd/{{slug}}/design.html
-  traceability_ref: docs/prd/{{slug}}/traceability.md
+  prd_ref: ${paths.prd_dir}/{{slug}}/PRD.md
+  design_ref: ${paths.prd_dir}/{{slug}}/design.html
+  traceability_ref: ${paths.prd_dir}/{{slug}}/traceability.md
   ssot_registry_entry: "{{Feature Name as registered/to-register in ssot-registry.md}}"
   data_model_refs:
     - ${paths.references_dir}/collections/{{collection}}.md
@@ -181,7 +181,7 @@ documentation_impact:
     action: "{{component registration}}"
     owner_card: {{FEAT-XXXX-NN}}
   - file: ${paths.references_dir}/ssot-registry.md
-    action: "Aggiungi riga '{{Feature Name}}' → docs/prd/{{slug}}/PRD.md"
+    action: "Aggiungi riga '{{Feature Name}}' → ${paths.prd_dir}/{{slug}}/PRD.md"
     owner_card: {{FEAT-XXXX-NN-last}}  # tipicamente l'ultima card (E2E o docs-sync)
 
 # =============================================================================

package/framework/.claude/skills/prd/assets/prd-template.md

@@ -10,7 +10,7 @@ freshness_status: fresh
 # {{Feature Name}} PRD
 
 **Version**: 1.0
-**Owner**: Antonio Baldassarre
+**Owner**: {{Owner}}
 **Date**: {{YYYY-MM-DD}}
 **Status**: Draft
 **Feature ID**: {{FEAT-ID}}
@@ -51,7 +51,7 @@ Backlog cards to be created after PRD approval.
 
 **Mockup status:** {{provided | partial | none | n/a}}
 **Step 3 mode:** {{full | hybrid | skipped}}
-**Design entry point:** {{`docs/prd/<slug>/design.html` | `docs/prd/<slug>/mockups/` | both}}
+**Design entry point:** {{`${paths.prd_dir}/<slug>/design.html` | `${paths.prd_dir}/<slug>/mockups/` | both}}
 
 ### Screen inventory
 

package/framework/.claude/skills/prd/references/audit-phase.md

@@ -226,7 +226,7 @@ Suppress findings where the strongest false-positive argument is convincing.
 ```
 
 **Variable interpolation** (build the command string before execution; read all values from the session tracker written at Phase 0 — never guess):
-- `${CARD_PATHS}`: newline-separated list of `- backlog/FEAT-XXXX-*.yml` paths from Step 5
+- `${CARD_PATHS}`: newline-separated list of `- ${paths.backlog_dir}/FEAT-XXXX-*.yml` paths from Step 5
 - `${PRD_PATH}`: the PRD file path from the session state
 - `${ADJACENT_CARD_PATHS}`: newline-separated list from Step 6.4
 - `${CARD_ID_SLUG}`: hyphen-separated list of card IDs being audited (e.g. `FEAT-0042-FEAT-0043`) — written to session tracker at Phase 0

package/framework/.claude/skills/prd/references/backlog-phase.md

@@ -89,13 +89,13 @@ Every PRD generates **1 epic card + N children**, regardless of N. The
 `prd-card-writer` agent enforces this; the skill MUST verify it post-generation
 and HALT if violated.
 
-- **Epic**: `backlog/FEAT-XXXX-00-<slug>-epic.yml` — tracker only (no code work);
+- **Epic**: `${paths.backlog_dir}/FEAT-XXXX-00-<slug>-epic.yml` — tracker only (no code work);
   contains AC-EPIC, execution_strategy with parallel groups, documentation_impact
   map.
-- **Children**: `backlog/FEAT-XXXX-NN-<sub-slug>.yml` for N=1..M — atomic
+- **Children**: `${paths.backlog_dir}/FEAT-XXXX-NN-<sub-slug>.yml` for N=1..M — atomic
   implementation cards. `group.parent: FEAT-XXXX-00`, `group.sequence: N`.
 
-**Forbidden** (post-write verification: skill MUST `ls backlog/FEAT-XXXX-*.yml`
+**Forbidden** (post-write verification: skill MUST `ls ${paths.backlog_dir}/FEAT-XXXX-*.yml`
 and confirm a `-00-...-epic.yml` exists, plus at least one `-NN-` child):
 
 - Flat cards `FEAT-XXXX-<slug>.yml` (no `-NN-` segment).

package/framework/.claude/skills/prd/references/prd-writing-phase.md

@@ -6,7 +6,7 @@ Mark task 3 as `in_progress`.
 
 ## Write PRD
 
-1. Create directory `docs/prd/<slug>/` if it doesn't exist.
+1. Create directory `${paths.prd_dir}/<slug>/` if it doesn't exist.
 2. **Obsidian spec note (if present):** if the state file contains `## Obsidian Spec Note`,
    add a row to the Canonical Sources table in the PRD:
    `| Obsidian spec | [[Note Name]] |`
@@ -93,7 +93,7 @@ Mark task 3 as `in_progress`.
    - If regulatory findings exist: add a dedicated "Compliance Requirements" section.
    - Include a "Research-Informed Decisions" subsection listing decisions influenced
      by research, with brief rationale and source reference.
-5. Write `docs/prd/<slug>/PRD.md` using the template from `assets/prd-template.md`.
+5. Write `${paths.prd_dir}/<slug>/PRD.md` using the template from `assets/prd-template.md`.
 
 ### PRD sections checklist
 

package/framework/.claude/skills/worktree-manager/SKILL.md

@@ -709,7 +709,7 @@ internal structure (tables, key/value blocks, code).
 | **Structured registries** | `project-status.md`, `ssot-registry.md`, `field-registry.*`, `traceability-matrix.md`, `REGISTRY.md` | Strip markers, then **structural validation** — if valid, accept; if invalid, abort | The auto-strip "keep both sides" usually produces an additive result (new bullet rows appended to a table or section). The validation step catches the rare case where the two sides modified the same row. See `validate_structured_md` below. |
 | **JSONL logs under `${paths.metrics}/`** | `${paths.metrics}/*.jsonl`, `${paths.metrics}/**/*.jsonl` | Auto-resolve: strip markers, keep both sides | JSONL is line-oriented and additive — duplicating both branches' lines yields a valid file. (`paths.metrics` default `docs/metrics`.) |
 | **Other `.jsonl`** | `*.jsonl` outside `${paths.metrics}/` | STOP — abort and report | Fixtures, seeds, training data: auto-strip can corrupt them. The user must inspect. |
-| **Docs/config** | `docs/**/*.md`, `backlog/*.yml`, `*.md` outside `src/`, `*.json`/`*.yml` outside `src/` (excluding rows above) | Auto-resolve: strip markers, keep both sides | The canonical additive case. |
+| **Docs/config** | `${paths.docs_dir}/**/*.md`, `${paths.backlog_dir}/*.yml`, `*.md` outside `src/`, `*.json`/`*.yml` outside `src/` (excluding rows above) | Auto-resolve: strip markers, keep both sides | The canonical additive case. |
 | **Code** | `src/**/*.ts`, `*.tsx`, `*.js`, `*.jsx` | STOP — abort rebase, report to user | |
 | **Tests** | `*.test.*`, `*.spec.*` | Manual only — report to user | |
 
@@ -784,7 +784,7 @@ for FILE in $CONFLICTED; do
 
   # 4. Generic docs/config — additive merge
   case "$FILE" in
-    docs/*|backlog/*|*.md|*.json|*.yml)
+    ${paths.docs_dir}/*|${paths.backlog_dir}/*|*.md|*.json|*.yml)
       sed -i '' '/^<<<<<<< /d; /^=======/d; /^>>>>>>> /d' "$FILE"
       git add "$FILE" ;;
   esac

package/framework/agents/project-context.md

@@ -174,6 +174,7 @@ When `base_agent_version` in the overlay is older than the installed framework v
 | Backlog | `backlog/*.yml` count > 0 | `paths.backlog_dir: backlog`, `features.has_backlog: true` |
 | ADR | `docs/decisions/ADR-*.md` count > 0 | `paths.adrs_dir: docs/decisions`, `features.has_adrs: true` |
 | PRD | `docs/prd/` exists | `paths.prd_dir: docs/prd`, `features.has_prd_workflow: true` |
+| Docs root | `docs/` exists | `paths.docs_dir: docs` |
 | References dir | `docs/references/` exists | `paths.references_dir: docs/references` |
 | LLM wiki | `docs/wiki/` exists | `paths.wiki_dir: docs/wiki`, `features.has_wiki_overlay: true` |
 | E2E tests | first match of `tests/e2e`, `e2e`, `tests/playwright`, `tests/cypress` | `paths.e2e_tests_dir: <found>` |

package/framework/docs/PROJECT-CONFIGURATION.md

@@ -105,6 +105,7 @@ Empty string `""` means the concept doesn't exist in your project. Skills gated
 | `backlog_dir` | `backlog` | new, prd, context-primer |
 | `adrs_dir` | `docs/decisions` | prd, prd-add |
 | `prd_dir` | `docs/prd` | prd, prd-add, ui-design |
+| `docs_dir` | `docs` | code-reviewer, senior-researcher, worktree-manager (rg-search fallback root) |
 | `references_dir` | `docs/references` | new, prd, context-primer, doc-writing-for-rag, simplify |
 | `wiki_dir` | `docs/wiki` | capture, context-primer |
 | `e2e_tests_dir` | `tests/e2e` | playwright-skill, e2e-review (v3.18.0) |

package/framework/routines/ds-drift.routine.yml

@@ -11,21 +11,21 @@ schedule:
 agent: doc-reviewer
 
 prompt: |
-  Run the weekly design-system drift check (only if `docs/design-system/`
+  Run the weekly design-system drift check (only if `${paths.design_system}/`
   exists in the project — exit cleanly if absent):
 
-  1. **INDEX coverage**: compare `docs/design-system/INDEX.md` component
+  1. **INDEX coverage**: compare `${paths.design_system}/INDEX.md` component
      index against the actual shared-component inventory. Flag
      `DS_INDEX_DRIFT` for any mismatch.
-  2. **Per-component accuracy**: for each `docs/design-system/components/<Name>.md`,
+  2. **Per-component accuracy**: for each `${paths.design_system}/components/<Name>.md`,
      verify it lines up with the source file (variants, props, exported
      constants). Flag `DS_COMPONENT_STALE` for docs not re-verified in >7
      days where the source has changed in git.
-  3. **Animations reconciliation**: `docs/design-system/patterns/animations.md`
+  3. **Animations reconciliation**: `${paths.design_system}/patterns/animations.md`
      must match keyframes in the project's global styles. Flag
      `DS_ANIMATIONS_DRIFT`.
   4. **Tokens reconciliation**: when tokens source files changed, verify
-     `docs/design-system/tokens-reference.md` is in sync and the relevant
+     `${paths.design_system}/tokens-reference.md` is in sync and the relevant
      CSS custom properties still exist. Flag `DS_TOKENS_DRIFT`.
   5. Emit a consolidated report under
      `docs/reports/{{YYYYMMDD}}-ds-drift.md`.
@@ -41,7 +41,7 @@ output:
     branch: main
 
 required_artifacts:
-  - docs/design-system/
+  - ${paths.design_system}/
   - .claude/agents/doc-reviewer.md
 
 optional: true   # routine is silently skipped when artifacts missing

package/framework/routines/wiki-review.routine.yml

@@ -1,5 +1,5 @@
 name: wiki-review
-description: Nightly review of the derived LLM wiki overlay (docs/wiki/) — synthesis candidates, anchor validation, drift detection.
+description: Nightly review of the derived LLM wiki overlay (${paths.wiki_dir}/) — synthesis candidates, anchor validation, drift detection.
 since_version: 2.1.0
 
 schedule:
@@ -16,8 +16,8 @@ prompt: |
   1. Scan ADRs and PRDs from the last 14 days. For each architectural pivot
      (provider swap, schema change, auth change, API contract, multi-card
      epic) propose a synthesis page candidate and append it to
-     `docs/wiki/log.md` with `entry_type: synthesis_candidate`.
-  2. Read `docs/wiki/log.md` for RAG queries with verdict=weak|empty
+     `${paths.wiki_dir}/log.md` with `entry_type: synthesis_candidate`.
+  2. Read `${paths.wiki_dir}/log.md` for RAG queries with verdict=weak|empty
      repeated ≥3 times. These are documentation gaps — propose a synthesis.
   3. Validate anchor slugs across all wiki pages (internal and cross-file).
      Flag `WIKI_ANCHOR_BROKEN` and fix in-place when possible.
@@ -36,7 +36,7 @@ output:
 
 required_artifacts:
   # Routine is silently skipped if these are missing.
-  - docs/wiki/
+  - ${paths.wiki_dir}/
   - .claude/agents/wiki-curator.md
 
 backend_hints:

package/framework/templates/baldart.config.template.yml

@@ -39,6 +39,7 @@ paths:
   backlog_dir: ""             # e.g. backlog
   adrs_dir: ""                # e.g. docs/decisions
   prd_dir: ""                 # e.g. docs/prd
+  docs_dir: ""                # e.g. docs   (umbrella docs root; rg-search fallback used by code-reviewer / senior-researcher / worktree-manager)
   references_dir: ""          # e.g. docs/references
   wiki_dir: ""                # e.g. docs/wiki   (LLM-wiki overlay)
 

package/framework/templates/overlays/commands/codexreview.example.md

@@ -4,6 +4,8 @@ base_command_version: 3.8.0
 mode: extend
 ---
 
+<!-- contamination-scan: skip — starter overlay EXAMPLE the user copies and rewrites; ships intentional sample literals (project build names, CTP-NNNN ids, backlog/, src/lib/...) by design. Overlays hold verbatim user opinions and are NOT runtime-resolved against baldart.config.yml. -->
+
 > Copy to `.baldart/overlays/commands/codexreview.md` and adapt freely.
 > Same merge model as agent overlays: `[OVERRIDE]` / `[APPEND]` / `[PREPEND]`
 > with H2 heading matching, plus untagged H2 sections appended at the end.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.0.4",
+  "version": "4.1.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/configure.js

@@ -370,6 +370,7 @@ function detect(cwd = process.cwd()) {
       backlog_dir: exists('backlog') ? 'backlog' : '',
       adrs_dir: countMatches('docs/decisions', /^ADR-.*\.md$/) > 0 ? 'docs/decisions' : '',
       prd_dir: exists('docs/prd') ? 'docs/prd' : '',
+      docs_dir: exists('docs') ? 'docs' : '',
       references_dir: exists('docs/references') ? 'docs/references' : '',
       wiki_dir: exists('docs/wiki') ? 'docs/wiki' : '',
       e2e_tests_dir: e2eTestsDir,
@@ -640,6 +641,7 @@ async function interactivePrompts(merged, detected) {
     ['backlog_dir', 'Backlog directory', () => merged.features.has_backlog],
     ['adrs_dir', 'ADR directory', () => merged.features.has_adrs],
     ['prd_dir', 'PRD directory', () => merged.features.has_prd_workflow],
+    ['docs_dir', 'Docs root directory (rg-search umbrella)', () => true],
     ['references_dir', 'References docs root', () => true],
     ['wiki_dir', 'Wiki overlay directory', () => merged.features.has_wiki_overlay],
     ['e2e_tests_dir', 'E2E tests directory', () => true],