baldart 4.78.2 → 4.80.0

package/framework/.claude/skills/ds-handoff/references/field-extraction.md

@@ -0,0 +1,78 @@
+# Field extraction — locating and reading the real fields
+
+How `ds-handoff` Step 3 grounds the field inventory in the project's actual data
+schemas. This is **retrieval composition + a mapping table**, NOT a new parser.
+The skill ships no Zod/AST extractor (that would be over-scoped and fragile across
+stacks; contrast `design-system-init`'s `extract-one.mjs`, justified only because a
+manifest HEAD must be byte-deterministic — a prose handoff tolerates LLM extraction
+behind the Step 5 coverage gate).
+
+## Retrieval order (each with silent fallback)
+
+Resolve the backing schema/type/form for each entity from Step 2, top to bottom.
+Stop at the first tier that returns the field set; degrade silently down the list.
+
+1. **Code-graph** — when `features.has_code_graph: true`. Use it to find the
+   schema/type/form definition and (bonus) which screens consume it. DELEGATE
+   `framework/agents/code-graph-protocol.md`.
+2. **LSP** — when `features.has_lsp_layer: true`. `go-to-definition` /
+   `find-references` on the entity symbol (e.g. `supplierSchema`) to jump straight
+   to the definition without grepping a common name. DELEGATE
+   `framework/agents/code-search-protocol.md`.
+3. **`codebase-architect`** (Task tool) — the workhorse. Ask it to locate the
+   entity's Zod schema / TS interface / form schema (react-hook-form, Formik, a
+   server action's input) and **return the field facts as structured data** (one
+   row per field with the columns below). Read-only exploration; it does not parse
+   ASTs for you — it reads the source and reports. Honor its return contract
+   (`framework/agents/return-contract-protocol.md`).
+4. **Grep** — last resort / Codex. Patterns: `z.object(`, `interface .*Props`,
+   `type .* = {`, `useForm`, `zodResolver`, `createInsertSchema` (drizzle-zod),
+   the entity name. Read the matched file directly.
+
+**Exclude framework noise** from every tier: `.framework/`, `.baldart/`,
+generated/telemetry files. These never back a product screen.
+
+## Per-field capture (the 9 inventory columns)
+
+For each field, capture exactly what the template's field-inventory table needs.
+Anything you cannot ground in code is the **literal `da definire`** — never a guess.
+
+| Column | Source in code | If ungrounded |
+|---|---|---|
+| **Campo (label)** | Humanize the field name; or the i18n registry source string when `features.has_i18n: true` (`paths.i18n_registry`); or an explicit `label`/JSDoc. | humanized name + note |
+| **Controllo** | The control-type mapping below. | `da definire` |
+| **Required** | `sì` unless `.optional()` / `.nullish()` / `?` / `.partial()`. | `da definire` |
+| **Validazione/Vincoli** | `.min()`/`.max()`/`.length()`/`.regex()`/`.email()`/`.url()`/`.int()`/`.positive()`/refinements. | `—` if none |
+| **Default** | `.default(x)` / a form `defaultValues` entry. | `—` if none |
+| **Opzioni / sorgente enum** | `z.enum([...])` / `z.nativeEnum` literals verbatim; a `z.string()` whose options come from a runtime query → `"query runtime — da definire"`. | `—` / `da definire` |
+| **Helper text** | JSDoc on the field; the i18n `context` for the key; an existing form description. | `da definire` |
+| **Mode** | `editable` by default; `readonly` for server-set / computed fields (see below). | `editable` |
+| **Card/gruppo** | From `mockup_analysis.screens[].layout` when present, else the reconciliation decision (Step 4). | `da definire` |
+
+## Control-type mapping (applied by the agent, not a CLI)
+
+A documented heuristic — apply it, but prefer an explicit signal (an existing
+component binding, a form control already in code) over the heuristic when present.
+
+| Schema / type shape | Control |
+|---|---|
+| `z.enum([...])` / `z.nativeEnum` / union of string literals | `select` (or `radio` for ≤ 3 options / `segmented` per project convention) |
+| `z.boolean()` | `toggle` (or `checkbox`) |
+| `z.string()` short (no/small `.max`) | `text input` |
+| `z.string()` long (`.max` ≥ ~200, or named `notes`/`description`/`body`) | `textarea` |
+| `z.string().email()` | `email input` |
+| `z.string().url()` | `url input` |
+| `z.string()` matching a phone/postal regex | typed input (`phone`/`postal`) |
+| `z.number()` / `z.coerce.number()` | `number input` (or `price`/`percent` per unit) |
+| `z.date()` / `z.string().datetime()` | `date picker` — **readonly** if server-set/computed |
+| `z.array(...)` of a sub-object | repeatable group / multi-row editor |
+| `z.array(z.string())` from a known set | `multi-select` |
+| `z.object(...)` nested | a sub-group / sub-card |
+
+## Readonly detection
+
+Mark a field **readonly** (static text, no editable control) when it is not
+user-authored: server-set timestamps (`created_at`, `updated_at`), derived/computed
+values, IDs, audit fields, anything the schema marks server-generated or that the
+form's `defaultValues` sets but the UI never edits. A field drawn as an input when
+it is in truth readonly is the classic Claude Design hallucination this prevents.

package/framework/.claude/skills/prd/references/ui-design-phase.md

@@ -30,35 +30,50 @@ unchanged. No other side-effect of Step 3.0.
 
 ### Branch B — Claude Design handoff
 
-1. **Collect context from the state file + config + overlays:**
-   - `feature_title`, `feature_objective_one_sentence` from `## Feature Description`.
-   - `user_flow_summary`, `primary_personas` from `## Discovery Log` (dimensions 1 + 2).
-   - `screens_in_scope[]` from `## UI Design` (derive from User Stories + ISA touchpoints if not yet populated — same logic as Hybrid mode § "Build the per-screen routing table").
-   - `brand_voice` from `.baldart/overlays/prd.md` if present (skip section otherwise).
-   - When `features.has_design_system: true`: read `${paths.design_system}/INDEX.md` (primitive list) + `${paths.design_system}/tokens-reference.md` (tokens excerpt). When `false`: omit § 5 of the prompt entirely.
-   - `stack.framework`, `stack.charting`, `stack.animation` from `baldart.config.yml`.
-   - `output_format_preference` derived from `stack.framework` (Next/Remix → React+Tailwind; vanilla → HTML/CSS; otherwise ask the user).
-   - Numeric token tables (type scale, spacing, radius, contrast, motion durations) from `framework/agents/design-system-protocol.md` — cite verbatim.
-
-2. **Render the prompt** by populating
-   [../assets/claude-design-handoff-prompt.template.md](../assets/claude-design-handoff-prompt.template.md)
-   with the collected context. Strip empty conditional sections.
-
-3. **Present the rendered prompt** to the user inside a fenced markdown
-   code-block, prefixed with this instruction (verbatim):
+The handoff prompt is owned by the **`ds-handoff` skill** (the single SSOT). `/prd`
+decides to hand off; `/ds-handoff` builds the field-level, 1:1 brief — it grounds
+every screen's fields in the real data schemas and runs a coverage gate **before**
+emitting, so Claude Design does not have to imagine the fields. (This is the same
+delegate-or-else-inline contract as `/prd` → `/ds-new`.)
+
+1. **Delegate to `/ds-handoff`.** Invoke it in *delegated* mode, passing the
+   resolved context so it skips its own screen-resolution prompt:
+   - the state-file path;
+   - `feature_title`, `feature_objective_one_sentence` (from `## Feature Description`);
+   - `user_flow_summary`, `primary_personas` (from `## Discovery Log` dimensions 1 + 2);
+   - `screens_in_scope[]` from `## UI Design` (derive from User Stories + ISA
+     touchpoints if not yet populated — same logic as Hybrid mode § "Build the
+     per-screen routing table");
+   - `mockup_analysis` from `## UI Design` if present (the skill reads its
+     `layout / component_props / states / responsive` as input);
+   - the `features.has_design_system` flag (the skill omits § 5 when `false`).
+
+   `/ds-handoff` runs field extraction + the coverage gate + the mandatory template
+   and returns the **rendered prompt** plus the **`field-inventory.md` path**.
+
+   **Graceful fallback** — if `/ds-handoff` is unavailable (Codex without it linked,
+   or an older install): render a **coarse** brief inline from `screens_in_scope[]`
+   (per-screen: scopo / stati / azioni primarie / dati visualizzati) and the same
+   top-level sections (obiettivo, user flow, brand, design system, stack, cosa
+   restituirmi). State explicitly to the user: *"field-level brief non disponibile →
+   brief coarse"*, so the lost fidelity is visible, not silent.
+
+2. **Present the returned prompt** to the user inside a fenced markdown code-block,
+   prefixed with this instruction (verbatim):
 
    > Incolla il prompt qui sotto in Claude Design. Quando hai i mockup pronti,
    > tornami con i **path locali** dei file (PNG, HTML, TSX, o link Figma) e
    > riprendo da qui — copio i file nella cartella del PRD, li analizzo come
    > al solito (Step 1.6 Mockup Intake), e Step 3 entra in Hybrid mode.
 
-4. **Update state file** before stopping:
+3. **Update state file** before stopping:
    - `mockups.status: pending_external`
    - `mockups.source: claude-design`
    - `mockups.handoff_prompt_path: ${paths.prd_dir}/<slug>/handoff/claude-design-prompt.md` (save the rendered prompt to disk so it survives session restarts).
+   - `mockups.field_inventory_path: ${paths.prd_dir}/<slug>/mockups/field-inventory.md` (the path `/ds-handoff` returned; omit on the coarse fallback).
    - `step_3_mode: pending_external_handoff` (transitional — overwritten when user returns).
 
-5. **STOP.** Wait for the user to return with local paths.
+4. **STOP.** Wait for the user to return with local paths.
 
 ### Re-entry from handoff (user returns with paths)
 

package/framework/AGENTS.md

@@ -103,8 +103,8 @@ Conflict steps (must follow in order):
 ### 4.a — Universal MUST (apply to every project)
 
 - MUST treat `AGENTS.md` as authoritative for agent rules.
-- MUST invoke `codebase-architect` agent (via Task tool) whenever you need to understand codebase structure, existing patterns, or code architecture before planning or implementing changes; do not proceed with planning or implementation without first understanding the existing system through codebase-architect.
-- MUST NOT silently fall back when an `Agent` (a.k.a. `Task`) tool call returns empty (`0 tool uses · Done`), times out, or fails with `permissionDecision: deny`. This pattern indicates a Claude Code sub-agent failure (see anthropics/claude-code#56869) or a discovery miss / blocked agent (see #20931 and BALDART's own `agent-discovery-gate` PreToolUse hook), NOT a signal to substitute another agent. STOP, report to the user verbatim: "Agent `<name>` non discoverato o fallito in questa sessione — riavvia Claude Code e verifica con `npx baldart doctor`", and wait for direction. Never auto-route to `feature-dev:*`, `general-purpose`, or any other marketplace/built-in agent as a replacement. **This rule is the ONLY defense against bug #56869 (which BALDART cannot patch from outside Claude Code); deviating from it reintroduces the exact failure mode the rule exists to prevent.**
+- MUST invoke the `codebase-architect` agent whenever you need to understand codebase structure, existing patterns, or code architecture before planning or implementing changes; do not proceed with planning or implementation without first understanding the existing system through codebase-architect. **The agent exists on both tools** — Claude Code spawns it via the Task/Agent tool with `subagent_type: "codebase-architect"`; Codex spawns the `codebase-architect` custom agent **by name** (BALDART installs it at `.codex/agents/codebase-architect.toml`, transpiled from the same `.md` source). Only if your environment genuinely exposes NEITHER subagent mechanism (a stripped tool host) do you degrade — explicitly — to inline structural retrieval (code-graph → LSP → Grep → direct file reads per `agents/code-search-protocol.md`), and SAY SO; never silently skip the understanding step.
+- MUST NOT silently substitute a *different* agent when an agent invocation returns empty (`0 tool uses · Done`), times out, or fails with `permissionDecision: deny`. On **Claude Code** this pattern indicates a sub-agent failure (see anthropics/claude-code#56869) or a discovery miss / blocked agent (see #20931 and BALDART's own `agent-discovery-gate` PreToolUse hook): STOP, report to the user verbatim: "Agent `<name>` non discoverato o fallito in questa sessione — riavvia Claude Code e verifica con `npx baldart doctor`", and wait for direction. Never auto-route to `feature-dev:*`, `general-purpose`, or any other marketplace/built-in agent as a replacement. **This rule is the ONLY defense against bug #56869 (which BALDART cannot patch from outside Claude Code); deviating from it reintroduces the exact failure mode the rule exists to prevent.** On **Codex** the named-agent spawn is the equivalent; the same no-silent-substitution rule holds (the #56869 specifics are Claude-only, the principle is universal).
 - MUST NOT work on files/components already claimed by another agent; multiple agents allowed if working on independent areas.
 - MUST perform a mandatory clarity analysis before fixing any issue labeled `bug`; confirm that the issue description, proposed correct behavior, and edge cases are unambiguous, document any resolved doubts, and only start fix work once every zone of uncertainty is covered.
 - MUST mark missing info as UNKNOWN and ask the user; if blocked, set `BLOCKED` with a blocker.

package/framework/agents/skills-mapping.md

@@ -24,6 +24,10 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 > This map references **only skills shipped under `framework/.claude/skills/`**.
 > Confirm a skill exists (its directory is present) before routing to it; never
 > route to a skill name that has no directory.
+>
+> **Gating.** Many skills are gated on a `features.*` flag in `baldart.config.yml`
+> (noted per entry). When the flag is `false` the skill REFUSES — do not route to
+> it; resolve the gate first (e.g. `/design-system-init` for `has_design_system`).
 
 ## Core Development Skills
 
@@ -43,6 +47,19 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "Nuova funzionalità"
 - "How should I scope..."
 
+### prd-add
+
+**When to use**:
+
+- A new requirement lands on an ACTIVE `/prd` session (change request)
+- "serve anche…", a missing endpoint/sub-feature surfaces mid-discovery
+- Runs ICIAS impact analysis to decide which PRD phases SKIP / PATCH / REDO
+
+**Triggers**:
+
+- "/prd-add"
+- "Aggiungi requisito" / "Serve anche" / "Manca un endpoint"
+
 ### context-primer
 
 **When to use**:
@@ -68,6 +85,20 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "Implementa le card"
 - "Esegui le card"
 
+### new2
+
+**When to use**:
+
+- EXPERIMENTAL workflow-hosted variant of `/new` (A/B testing context economy)
+- The whole card batch runs in a background dynamic workflow (subagent output never
+  enters the main context); every `/new` gate becomes a deterministic policy
+- **Claude-only** (needs the `Workflow` tool)
+
+**Triggers**:
+
+- "/new2 CARD-IDS"
+- "Implementa le card con workflow"
+
 ### bug
 
 **When to use**:
@@ -82,6 +113,30 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "Fix [bug]"
 - "Non funziona" / "Why is [X] not working?"
 
+### worktree-manager
+
+**When to use**:
+
+- Parallel coding agents needing fully independent git worktrees
+- Create / merge (→ PR) / list / cleanup isolated workspaces
+- Used programmatically by `/new` for per-card worktree ops
+
+**Triggers**:
+
+- "/nw" (new) · "/mw" (merge) · "/lw" (list) · "/cw" (cleanup)
+- "New worktree" / "Merge worktree"
+
+### issue-review
+
+**When to use**:
+
+- Triage / planning a GitHub issue (summary + priority + plan + tests)
+
+**Triggers**:
+
+- "/issue-review"
+- "Triage this issue" / "Review issue [N]"
+
 ## Code Quality Skills
 
 ### simplify
@@ -136,7 +191,129 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 > standalone invocable BALDART skill. Route UI work through `ui-design` /
 > `ui-expert`, not to `ui-ux-pro-max` directly.
 
-## Testing Skills
+### motion-design
+
+**When to use**:
+
+- Animations, transitions, micro-interactions, loading/page transitions
+- Scroll-triggered effects, choreography, timing/easing decisions
+- Works with CSS / Framer Motion / GSAP / Lottie / Spring
+
+**Triggers**:
+
+- "/motion-design"
+- "Anima…" / "transition" / "micro-interaction"
+
+### gamification-design
+
+**When to use**:
+
+- Points systems, reward loops, progression mechanics, loyalty/retention
+- B2C customer-facing engagement features
+
+**Triggers**:
+
+- "/gamification-design"
+- "Punti / reward / progression / battle pass / loyalty"
+
+## Design System Skills
+
+> All gated on `features.has_design_system: true`. Without a registry, bootstrap
+> first with `/design-system-init`.
+
+### design-system-init
+
+**When to use**:
+
+- GREENFIELD: bootstrap a component registry (INDEX.md + DTCG tokens + per-component specs) and flip `has_design_system`
+- UPGRADE: regenerate machine-readable HEADs / DTCG tokens on an existing prose-only registry
+- SEED: a registry born in Claude Design (design-led)
+
+**Triggers**:
+
+- "/design-system-init"
+- "Crea design system" / "inizializza registro componenti" / "aggiorna le spec"
+- `baldart doctor` nudges (specs missing / prose-only)
+
+### ds-new
+
+**When to use**:
+
+- Create ONE canonical element (a component OR a token) end-to-end: reuse-first → optional scaffold → document + register + govern + verify
+- The on-the-fly twin of the bulk `design-system-init`; callable by `/prd` when reconciliation confirms a NEW component
+
+**Triggers**:
+
+- "/ds-new" · "/ds-new token [id]"
+- "Nuovo componente design system" / "registra una primitive" / "aggiungi un token"
+
+### ds-edit
+
+**When to use**:
+
+- Deliberately edit ONE existing element: resync / extend-variant / breaking / re-govern
+- Regenerates the spec preserving agentic fields + prose
+- NOT for the automatic mechanical doc-resync after a code change (that's already automatic via the `DS_COMPONENT_STALE` gate)
+
+**Triggers**:
+
+- "/ds-edit"
+- "Aggiungi una variante" / "modifica un componente" / "breaking change su un componente"
+
+### ds-render
+
+**When to use**:
+
+- Render design-system primitives in ISOLATION (one component × variant) to a PNG each
+- Feeds isolated QUALITY verification (`/e2e-review` Phase 4b/4c) — never a fidelity diff
+- Rides on a detected Storybook (clean no-op otherwise)
+
+**Triggers**:
+
+- "/ds-render"
+- "Render i componenti" / "screenshot dei primitivi"
+
+### ds-handoff
+
+**When to use**:
+
+- Produce the FIELD-LEVEL, 1:1 Claude Design handoff prompt — every screen's real fields (label / control / required / validation / default / enum / helper / readonly), grounded in the project's data schemas, coverage-gated before emission
+- The single SSOT for the Claude Design prompt; `/prd` Step 3.0 Branch B delegates here
+- Standalone for an ad-hoc orchestrator + `ui-expert` run
+
+**Triggers**:
+
+- "/ds-handoff [screens-or-feature]"
+- "Handoff a Claude Design" / "prompt per Claude Design" / "brief field-level"
+
+### design-sync
+
+**When to use**:
+
+- Mirror the in-repo registry (SSOT) UP to its Claude Design satellite (the code→design half of the closed loop)
+- `publish` / `bootstrap` / `drift` modes; delegates every write to the DesignSync MCP; refuse-on-divergence
+- Claude-only; interactive-auth (`/design-login`); no-op without a bound satellite
+
+**Triggers**:
+
+- "/design-sync"
+- "Pubblica il design system" / "mirror su Claude Design" / "il designer ha cambiato qualcosa"
+
+## Testing & Review Skills
+
+### e2e-review
+
+**When to use**:
+
+- Deterministic BLOCKING end-to-end review after a feature is implemented
+- Functional E2E (Playwright) + visual fidelity diff + design-quality critic, under a severity gate + bounded self-heal
+- Auto-called by `/new` Phase 2.6; invocable manually
+- Gated on `features.has_e2e_review`
+
+**Triggers**:
+
+- "/e2e-review CARD-ID"
+- "Verifica end-to-end" / "review schermate" / "controlla i mockup"
 
 ### playwright-skill
 
@@ -166,7 +343,7 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - Integration testing
 - Server management needed
 
-## Documentation Skills
+## Documentation & Knowledge Skills
 
 ### doc-writing-for-rag
 
@@ -180,6 +357,64 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "doc per RAG" / "dense documentation"
 - "template endpoint" / "compattare docs"
 
+### capture
+
+**When to use**:
+
+- Distill a cross-document synthesis of the recent conversation into a reusable wiki synthesis page
+- Implements Karpathy's query→wiki file-back loop
+- Gated on `features.has_wiki_overlay`
+
+**Triggers**:
+
+- "/capture"
+- "Salva sintesi" / "distilla conversazione" / "questa conversazione in wiki"
+
+### graph-align
+
+**When to use**:
+
+- On-demand documentation alignment via the Graphify code knowledge graph
+- Surface core code with no doc coverage, stale docs, drift vs the SSOT registry
+- The interactive twin of the nightly `doc-graph-align` routine
+- Gated on `features.has_code_graph`
+
+**Triggers**:
+
+- "/graph-align"
+- "Allinea la documentazione" / "check doc coverage"
+
+## Internationalization Skills
+
+> Gated on `features.has_i18n: true`.
+
+### i18n
+
+**When to use**:
+
+- Audit the i18n context registry against `t()` calls + native locale files (drift codes)
+- Context-aware translation of missing/stale labels via the `i18n-translator` agent
+- The interactive twin of the weekly `i18n-align` routine
+
+**Triggers**:
+
+- "/i18n"
+- "Traduci le label" / "audit i18n" / "allinea le traduzioni"
+
+### i18n-adopt
+
+**When to use**:
+
+- One-shot migration that externalizes ALL hardcoded user-facing strings on an existing codebase (the i18n analogue of `/design-system-init`)
+- Full-auto on a dedicated branch, idempotent + resumable; never auto-merges
+
+**Triggers**:
+
+- "/i18n-adopt"
+- "Migra a i18n" / "adotta i18n" / "externalize all strings"
+
+## Product & Content Skills
+
 ### copywriting
 
 **When to use**:
@@ -193,6 +428,152 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "Migliora il testo"
 - Landing/marketing content
 
+### seo-audit
+
+**When to use**:
+
+- Audit / diagnose technical + on-page SEO issues on a site
+
+**Triggers**:
+
+- "/seo-audit"
+- "SEO audit" / "why am I not ranking" / "meta tags review"
+
+### api-design-principles
+
+**When to use**:
+
+- Designing a new API, reviewing an API spec, establishing API design standards (REST / GraphQL)
+
+**Triggers**:
+
+- "/api-design-principles"
+- "Design this API" / "review API spec"
+
+## Integration Skills
+
+### kie-ai
+
+**When to use**:
+
+- Generate images / videos / audio via Kie.ai (80+ models), upscaling, background removal, TTS/SFX
+
+**Triggers**:
+
+- "/kie" / "/generate-image" / "/generate-video"
+- "Genera immagine / video", model names ("nano banana", "veo", "kling", "suno"…)
+
+### remotion-best-practices
+
+**When to use**:
+
+- Building video in React with Remotion (best practices guidance)
+
+**Triggers**:
+
+- "Remotion" / "video in React"
+
+## Retrieval & Toolchain Bootstrap Skills
+
+> Install/verify opt-in layers. Each is gated on its `features.*` flag and is
+> idempotent (re-running re-verifies + reports drift).
+
+### lsp-bootstrap
+
+**When to use**:
+
+- Install + verify the LSP symbol-search layer (language servers, `lsp.installed_servers`)
+- After enabling `features.has_lsp_layer`
+
+**Triggers**:
+
+- "/lsp-bootstrap"
+- "Install LSP" / "set up symbol search"
+
+### graphify-bootstrap
+
+**When to use**:
+
+- Install + verify + wire the Graphify code-knowledge-graph layer (CLI, offline graph build, auto-rebuild hook, MCP)
+- After enabling `features.has_code_graph`
+
+**Triggers**:
+
+- "/graphify-bootstrap"
+- "Install graphify" / "set up the code graph"
+
+### toolchain-bootstrap
+
+**When to use**:
+
+- Install + verify + wire the curated dev toolchain (Biome / Vitest / tsc / Lefthook) as devDeps
+- After enabling `features.has_toolchain`
+
+**Triggers**:
+
+- "/toolchain-bootstrap"
+- "Install the toolchain" / "set up biome"
+
+## Framework Maintenance & Meta Skills
+
+### baldart-update
+
+**When to use**:
+
+- Bring the BALDART framework up-to-date in a consumer repo (seamless `npx baldart update --yes`)
+- The skill narrates the CLI; it never re-implements it
+
+**Triggers**:
+
+- "/baldart-update"
+- "Aggiorna baldart" / "update del framework"
+
+### baldart-push
+
+**When to use**:
+
+- Contribute local framework improvements upstream to the BALDART repo
+- Hands off to `npx baldart push` (interactive); never pushes project-specific customizations
+
+**Triggers**:
+
+- "/baldart-push"
+- "Contribuisci al framework" / "push del framework"
+
+### overlay
+
+**When to use**:
+
+- Author `.baldart/overlays/` — the per-project customisation layer for skills / agents / commands
+- Scaffolds + validates + surfaces drift via the CLI; often the answer when the `framework-edit-gate` hook blocked a direct edit
+
+**Triggers**:
+
+- "/overlay"
+- "Customizza skill" / "override agent" / "personalizza comando"
+
+### skill-creator
+
+**When to use**:
+
+- Create a new skill, or modify/optimize/measure an existing one
+
+**Triggers**:
+
+- "/skill-creator"
+- "Crea una skill" / "improve this skill"
+
+### find-skills
+
+**When to use**:
+
+- Discover/install agent skills when a needed capability might already exist as a skill
+
+**Triggers**:
+
+- "/find-skills"
+- "Is there a skill that…" / "how do I do X"
+
 ## Project-Specific Skills
 
 Add your project-specific skills here:
@@ -214,7 +595,8 @@ START: User gives a task
   |
   v
 Is it a new feature needing scope/plan?
-  |-- YES --> /prd (scopes + plans + writes cards)
+  |-- YES --> /prd (scopes + plans + writes cards; UI phase delegates the
+  |           Claude Design prompt to /ds-handoff)
   |           Then /new (implements the cards end-to-end)
   |
   v
@@ -223,11 +605,22 @@ Is it a bug fix?
   |
   v
 Is it UI/visual work?
-  |-- YES --> /ui-design (mockups/options) or frontend-design
+  |-- YES --> /ui-design (mockups/options) or frontend-design;
+  |           motion → /motion-design
   |
   v
-Is it browser testing?
-  |-- YES --> playwright-skill or webapp-testing (E2E via /e2e-review)
+Is it design-system work (a component / token / handoff)?
+  |-- YES --> /ds-new (create) · /ds-edit (change) · /ds-render (isolate) ·
+  |           /ds-handoff (Claude Design prompt) · /design-sync (mirror)
+  |           (bootstrap the registry first with /design-system-init)
+  |
+  v
+Is it internationalization?
+  |-- YES --> /i18n (audit + translate) or /i18n-adopt (one-shot migration)
+  |
+  v
+Is it browser/E2E testing or review?
+  |-- YES --> playwright-skill / webapp-testing / /e2e-review (blocking)
   |
   v
 Is it cleanup/complexity reduction?
@@ -250,7 +643,15 @@ Common skill chains (all skills below are shipped under `.claude/skills/`):
 3. **UI Feature**:
    - /prd → /ui-design → /new → playwright-skill (or /e2e-review for blocking E2E)
 
-4. **Refactoring**:
+4. **UI Feature via Claude Design handoff**:
+   - /prd (Branch B) → /ds-handoff (field-level prompt) → [design in Claude Design]
+     → /prd re-entry (mockup intake) → /new → /e2e-review
+
+5. **Design System**:
+   - /design-system-init (bootstrap) → /ds-new / /ds-edit (evolve) → /ds-render
+     (verify isolated) → /design-sync (mirror to the satellite)
+
+6. **Refactoring**:
    - /simplify (identify + apply cleanups) → /new gates re-run lint/tsc/tests
 
 ## Anti-Patterns
@@ -263,6 +664,7 @@ Common skill chains (all skills below are shipped under `.claude/skills/`):
 - Claim completion before the `/new` review + gate cycle passes
 - Use wrong skill for the task
 - Route to a skill name that has no directory under `.claude/skills/`
+- Route to a feature-gated skill when its `features.*` flag is `false`
 
 **Do**: