baldart 3.41.0 → 4.0.1

package/framework/.claude/skills/context-primer/SKILL.md

@@ -15,8 +15,8 @@ Load structured, task-adaptive context about a topic into the conversation befor
 
 ## Project Context
 
-**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `paths.prd_dir`, `paths.wiki_dir`, `paths.adrs_dir`.
-**Gated by features:** `features.has_backlog` (skip backlog grep when `false`), `features.has_wiki_overlay` (skip wiki search), `features.has_adrs` (skip ADR includes), `features.has_prd_workflow` (skip PRD reads).
+**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `paths.prd_dir`, `paths.wiki_dir`, `paths.adrs_dir`, `paths.wiki_log`.
+**Gated by features:** `features.has_backlog` (skip backlog grep when `false`), `features.has_wiki_overlay` (skip wiki search AND the wiki-log instrumentation tap), `features.has_adrs` (skip ADR includes), `features.has_prd_workflow` (skip PRD reads).
 **Overlay:** loads `.baldart/overlays/context-primer.md` if present — project-specific topic vocabulary, must-include canonical docs.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
@@ -59,7 +59,15 @@ SEARCH STRATEGY — RAG-first, verify-only-if-needed:
    Pass invoker_agent="context-primer" — this OVERRIDES your own default
    (codebase-architect) for every call you make on behalf of this skill,
    so telemetry attributes the query to the initiating skill, not the subagent.
-   Check rag_telemetry.verdict in the response:
+
+   NOTE: the search_docs MCP tool and its rag_telemetry.verdict field only
+   exist when a RAG/Obsidian doc-search layer is connected. If search_docs is
+   NOT available (no MCP tool), or it returns no rag_telemetry block, treat the
+   verdict as "empty" and go straight to the full manual search (steps 2-3) —
+   do NOT fabricate a verdict or stall waiting for a field that will never
+   appear. Emit no error; this is the normal no-RAG path.
+
+   When the field IS present, check rag_telemetry.verdict in the response:
    - "useful" → RAG is your PRIMARY source. Go to step 4.
    - "weak"/"fallback_degraded" → supplement with steps 2-3.
    - "empty" → full manual search (steps 2-3).
@@ -132,15 +140,28 @@ Return output in this EXACT XML format (30-50 lines max):
     <note acquired="YYYY-MM-DD">Note content</note>
     <note acquired="YYYY-MM-DD" stale="true">Old note [STALE — verify]</note>
   </memory_notes>
+  <!-- If no RAG layer was available, set verdict="unavailable" count="0" mode="none" -->
   <rag_quality verdict="{rag_telemetry.verdict}" count="{count}" mode="{mode}"/>
 </context_primer>
 
 WIKI LOG INSTRUMENTATION (FEAT-0805 — tap point of the auto-learning loop):
-After every search_docs call, inspect the returned rag_telemetry.verdict.
-If verdict ∈ {"weak", "empty", "fallback_degraded"}, log one entry to the
-wiki log so the nightly wiki-review can detect coverage gaps:
-
-  python3 -c "import sys; sys.path.insert(0, 'tools/doc-rag'); \
+This tap is GATED. Only attempt it when `features.has_wiki_overlay: true` AND
+`paths.wiki_log` is set in `baldart.config.yml` (it points at the project's
+wiki-log tap MODULE FILE, e.g. `tools/doc-rag/wiki_log.py` — there is no
+hardcoded `tools/doc-rag` default; that path is one consumer's layout and does
+not resolve elsewhere). If either is absent, SKIP the tap entirely and emit a
+single stderr WARNING
+"wiki_log skipped: features.has_wiki_overlay/paths.wiki_log not configured" —
+never silently no-op, and never assume a default path.
+
+When enabled: after every search_docs call, inspect the returned
+rag_telemetry.verdict. If verdict ∈ {"weak", "empty", "fallback_degraded"},
+log one entry to the wiki log so the nightly wiki-review can detect coverage
+gaps. Resolve `<wiki_log_dir>` as the PARENT DIRECTORY of `paths.wiki_log`
+(i.e. `dirname` — the importable package dir; `paths.wiki_log` itself is the
+`wiki_log.py` file):
+
+  python3 -c "import sys; sys.path.insert(0, '<wiki_log_dir>'); \
     from wiki_log import append_entry; \
     append_entry(entry_type='query', title='<query_short>', \
       agent='context-primer', \

package/framework/.claude/skills/doc-writing-for-rag/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: doc-writing-for-rag
-description: "Scrive documentazione di reference ad alta densità ottimizzata per RAG indexing. Usa template compatti, frontmatter minimal, cross-reference a schemas.md/errors.md (paths da `paths.api_schemas`/`paths.api_errors` in `baldart.config.yml`). Carica questa skill quando crei o riscrivi file in `${paths.references_dir}`, `${paths.prd_dir}`, o quando senti 'template endpoint', 'compattare docs', 'doc per RAG', 'dense documentation', 'signal/noise ratio'."
+description: "Writes high-density reference documentation optimized for RAG indexing. Uses compact templates, minimal frontmatter, cross-references to schemas.md/errors.md (paths from `paths.api_schemas`/`paths.api_errors` in `baldart.config.yml`). Load this skill when creating or rewriting files in `${paths.references_dir}`, `${paths.prd_dir}`, or when you hear 'endpoint template', 'compact docs', 'doc for RAG', 'dense documentation', 'signal/noise ratio'."
 ---
 
 # Doc Writing for RAG
 
-Protocollo di scrittura per reference docs ottimizzate per LightRAG indexing. Validato su 45 file in 3 wave di compressione (-48% linee medio, signal/noise da 45% a 80%+).
+Writing protocol for reference docs optimized for LightRAG indexing. Validated on 45 files across 3 compression waves (−48% average lines, signal/noise from 45% to 80%+).
 
 ## Project Context
 
@@ -16,35 +16,35 @@ Protocollo di scrittura per reference docs ottimizzate per LightRAG indexing. Va
 
 ## When to Use
 
-Carica questa skill quando:
+Load this skill when:
 
-- **Nuovo reference doc** da scrivere (es. nuovo dominio API, UI page, collection)
-- **Major rewrite** di file esistente >1500 linee o con S/N basso
-- **Nuovo endpoint API** da documentare in file esistente
-- **Extending** `schemas.md` o `errors.md` con nuovi schemi/codes
+- **New reference doc** to write (e.g. new API domain, UI page, collection)
+- **Major rewrite** of an existing file >1500 lines or with low signal/noise ratio
+- **New API endpoint** to document in an existing file
+- **Extending** `schemas.md` or `errors.md` with new schemas/codes
 
-NON caricare per:
-- Review incrementale di file esistenti (usa doc-reviewer-support)
-- Scrittura di ADR (diversi, già densi, vedi writing-guide)
-- PRD discovery/ideation (usa prd skill)
-- Business/marketing copy (usa copywriting skill)
+Do NOT load for:
+- Incremental review of existing files (use `doc-reviewer-support` if installed — see Related Skills)
+- Writing ADRs (different format, already dense — see writing-guide)
+- PRD discovery/ideation (use the `prd` skill)
+- Business/marketing copy (use the `copywriting` skill)
 
 ## Core Principles
 
-1. **Cross-reference over repetition**: un concetto spiegato UNA VOLTA, linkato altrove
-2. **Tables > prose** per info strutturate (endpoint params, error codes, schemas)
-3. **Frontmatter minimo**: 4 campi (doc_type, domain, canonicality, last_updated). Niente audit_notes, freshness_status, stale_*, owner, status (derivabili da git)
-4. **Central support files**: `schemas.md` per JSON schemas riusabili, `errors.md` per error codes
+1. **Cross-reference over repetition**: one concept explained ONCE, linked elsewhere
+2. **Tables > prose** for structured information (endpoint params, error codes, schemas)
+3. **Minimal frontmatter**: 4 fields (doc_type, domain, canonicality, last_updated). No audit_notes, freshness_status, stale_*, owner, status (derivable from git)
+4. **Central support files**: `schemas.md` for reusable JSON schemas, `errors.md` for error codes
 5. **Line count targets**: API ref <1500, PRD <1500, ADR <200, index <500
-6. **Descrittivo ma denso**: preserva TUTTA l'info semantica, comprimi solo verbosità
+6. **Descriptive but dense**: preserve ALL semantic information, compress only verbosity
 
-## Workflow — Nuovo endpoint API
+## Workflow — New API Endpoint
 
-1. **Check schemas.md** (`${paths.api_schemas}`): lo schema response esiste già? Se sì, riusalo. Se no, definiscilo DOPO aver scritto l'endpoint, in APPEND alla sezione di dominio appropriata. (Skip when `features.has_api_docs: false`.)
+1. **Check schemas.md** (`${paths.api_schemas}`): does the response schema already exist? If yes, reuse it. If no, define it AFTER writing the endpoint, APPENDed to the appropriate domain section. (Skip when `features.has_api_docs: false`.)
 
-2. **Check errors.md** (`${paths.api_errors}`): gli error codes esistono già nella domain section? Se sì, riusali. Se no, aggiungili APPEND in domain section. (Skip when `features.has_api_docs: false`.)
+2. **Check errors.md** (`${paths.api_errors}`): do the error codes already exist in the domain section? If yes, reuse them. If no, APPEND them in the domain section. (Skip when `features.has_api_docs: false`.)
 
-3. **Scrivi endpoint con template compatto**:
+3. **Write endpoint using compact template**:
    ```markdown
    ### POST /api/v1/domain/resource
 
@@ -60,16 +60,16 @@ NON caricare per:
    **Errors**: RESOURCE_NOT_FOUND, INVALID_NAME ([errors.md](../errors.md#domain-domain))
    ```
 
-4. **Path relativi corretti** (dipende dalla location del file):
+4. **Correct relative paths** (depends on file location):
    - `api/*.md` → `./schemas.md` + `../errors.md`
    - `api/booking/*.md` → `../schemas.md` + `../../errors.md`
    - `api/survey/*.md` → `../schemas.md` + `../../errors.md`
 
-5. **Verifica line count**: se il file supera 1500 linee → split in sub-files per dominio.
+5. **Verify line count**: if the file exceeds 1500 lines → split into sub-files per domain.
 
-## Template snippets inline
+## Template Snippets
 
-### Frontmatter minimo (mandatory)
+### Minimal frontmatter (mandatory)
 
 ```yaml
 ---
@@ -80,7 +80,7 @@ last_updated: 2026-04-05
 ---
 ```
 
-Altri campi (owner, status, audit_notes, freshness_status, stale_*) sono **derivabili** da git blame / tooling → **non scriverli**.
+Other fields (owner, status, audit_notes, freshness_status, stale_*) are **derivable** from git blame / tooling → **do not write them**.
 
 ### Compact endpoint (mandatory)
 
@@ -89,15 +89,15 @@ Altri campi (owner, status, audit_notes, freshness_status, stale_*) sono **deriv
 
 **Auth**: hook  |  **Access**: roles
 
-**Body** / **Query** / **Params**: tabella 4 colonne
+**Body** / **Query** / **Params**: 4-column table
 
 **Returns**: [Schema](schemas#anchor)
 **Errors**: CODE1, CODE2 ([errors.md](errors#domain))
 ```
 
-### Cross-reference section (per concetti ripetuti)
+### Cross-reference section (for repeated concepts)
 
-Spiegazione completa **una sola volta** nella intro del file, poi:
+Full explanation **once** in the file intro, then:
 ```markdown
 See [§Store Access Control](#store-access-control) for gating details.
 ```
@@ -106,14 +106,14 @@ See [§Store Access Control](#store-access-control) for gating details.
 
 | Reference | When to load |
 |-----------|--------------|
-| `references/compact-templates.md` | Scrittura nuovo endpoint/UI/PRD/collection |
-| `references/schemas-and-errors.md` | Estensione di schemas.md o errors.md |
-| `references/frontmatter-minimal.md` | Definire frontmatter di un nuovo file |
-| `references/line-count-targets.md` | File > soglia, decidere se splittare |
-| `references/before-after-examples.md` | Vuoi esempi concreti Wave 1+2+3 |
+| `references/compact-templates.md` | Writing new endpoint/UI/PRD/collection |
+| `references/schemas-and-errors.md` | Extending schemas.md or errors.md |
+| `references/frontmatter-minimal.md` | Defining frontmatter for a new file |
+| `references/line-count-targets.md` | File > threshold, deciding whether to split |
+| `references/before-after-examples.md` | Want concrete Wave 1+2+3 examples |
 
 ## Related Skills
 
-- `doc-reviewer-support`: review checklists, invariant tables, navigation audit
-- `prd`: PRD discovery & ideation (diverso scope)
+- `doc-reviewer-support` (OPTIONAL — not shipped with the framework): review checklists, invariant tables, navigation audit. If present, use its format; if absent, proceed without it and perform review inline.
+- `prd`: PRD discovery & ideation (different scope)
 - `copywriting`: marketing/UX copy

package/framework/.claude/skills/frontend-design/SKILL.md

@@ -196,13 +196,15 @@ These apply to every form, every project — they are not "nice to have":
 
 ---
 
-## Prototipi Standalone e Demo
+## Standalone Prototypes and Demos
 
-Quando il task richiede un prototipo HTML interattivo, demo animata, slide deck, mockup iOS/app, o design exploration **NON legato alla codebase Next.js** (nessun contesto `src/app/`), invocare la skill `huashu-design` in aggiunta o al posto di questa skill. Essa fornisce:
-- App Prototype shell (AppPhone state manager, tappabile, iPhone frame)
-- Tweaks panel per varianti in-page
-- Export animazioni → MP4/GIF (25fps base, 60fps interpolato)
-- 5 flussi × 20 filosofie di design per design exploration
-- Validazione Playwright click-test prima della consegna
+When the task calls for an interactive HTML prototype, animated demo, slide deck, iOS/app mockup, or design exploration **not tied to the project codebase**, the `huashu-design` skill can supplement or replace this skill. It provides:
+- App Prototype shell (AppPhone state manager, tappable, iPhone frame)
+- Tweaks panel for in-page variants
+- Animation export → MP4/GIF (25fps base, 60fps interpolated)
+- 5 flows × 20 design philosophies for design exploration
+- Playwright click-test validation before delivery
 
-**Regola del Filesystem (ASSOLUTA):** ogni output HTML/prototipo deve essere scritto su disco con il tool `Write` PRIMA di aprirlo in Safari o condividerlo con l'utente. Non è sufficiente outputtare blocchi di codice inline.
+**`huashu-design` is OPTIONAL** — it is a user-installed skill, not shipped with the framework. If it is not present, proceed with this skill alone and notify the user: "huashu-design not found; continuing with frontend-design only. Install huashu-design for advanced prototype tooling."
+
+**Filesystem Rule (ABSOLUTE):** every HTML output/prototype must be written to disk with the `Write` tool BEFORE opening it in a browser or sharing it with the user. Outputting inline code blocks is not sufficient.