baldart 5.0.1 → 5.2.0

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

@@ -1,221 +1,44 @@
 ---
 name: frontend-design
-effort: medium
-version: 1.0.0
-description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
+effort: low
+version: 2.0.0
+description: "ROUTER (retired generator, since framework v5.2.0). Historically triggered for building web components, pages, dashboards, landing pages, HTML/CSS layouts, or styling/beautifying any web UI — those triggers still land here, and this skill immediately routes them to the right BALDART surface: /ui-design (design, mockups, prototyping, restyling), /ui-implement (approved mockup → code), the ui-expert agent (direct in-code UI work). Do not follow this skill for design guidance; its design intelligence moved to ui-design/references/ (craft-standards, anti-slop, design-directions)."
 license: Complete terms in LICENSE.txt
 ---
 
-This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
-
-## Project Context
-
-**Reads from `baldart.config.yml`:** `paths.design_system`, `paths.ui_guidelines`, `identity.design_philosophy`, `stack.charting.canonical`, `stack.animation.canonical`.
-**Gated by features:** `features.has_design_system` (when `true`, the BLOCKING reads in the next section are mandatory; when `false`, fall back to `paths.ui_guidelines` alone — the BOLD aesthetic direction is then driven by `identity.design_philosophy` only).
-**Overlay:** loads `.baldart/overlays/frontend-design.md` if present — project-specific aesthetic mandates, forbidden patterns, illustration-motion contract.
-**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
-
-The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
-
-## Effort
-
-**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
-`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
-reasoning depth for this run — detect it once at kickoff and strip the token
-before consuming user input. Level→behavior mapping, parsing contract, and
-precedence caveats: `framework/agents/effort-protocol.md`.
-
-
-## Design Thinking
-
-Before coding, understand the context and commit to a BOLD aesthetic direction:
-- **Purpose**: What problem does this interface solve? Who uses it?
-- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
-- **Constraints**: Technical requirements (framework, performance, accessibility).
-- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
-
-**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
-
-Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
-- Production-grade and functional
-- Visually striking and memorable
-- Cohesive with a clear aesthetic point-of-view
-- Meticulously refined in every detail
-
-## Frontend Aesthetics Guidelines
-
-Focus on:
-- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
-- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
-- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
-- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
-- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
-
-NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
-
-Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
-
-**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
-
-Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
-
-## MANDATORY Pre-Work Read (project design-system override)
-
-The registry-first cascade below is the consumer view of the SSOT in
-[`framework/agents/design-system-protocol.md`](../../../agents/design-system-protocol.md).
-When the cascade rules diverge between this file and the protocol module,
-the protocol module wins.
-
-When operating inside a repo that ships a design-system SSOT, the generic
-creative guidance above is BLOCKED by the project design-system until the
-reads below are complete. MANDATORY pre-work reads (skipping any of them is
-a protocol violation when the docs exist):
-
-1. **MANDATORY / BLOCKING** — `${paths.design_system}/INDEX.md`. Authoritative component index + Canonical Authority Matrix. Discover existing primitives there BEFORE inventing new ones.
-2. **MANDATORY / BLOCKING** — `${paths.design_system}/tokens-reference.md`. Human-readable token contract (colors, spacing, radius, shadows, typography). Never hardcode hex colors, shadow pixel tuples, or border widths not defined in the design-system doc.
-3. **MANDATORY** — `${paths.design_system}/components/<Name>.md` for every primitive in scope, and `${paths.design_system}/patterns/*.md` (overlays, theming, animations, platform quirks) for the pattern involved.
-4. **MANDATORY / BLOCKING** — `${paths.ui_guidelines}`. Brand philosophy, aesthetic rules, SVG rules, accessibility constraints.
-5. **MANDATORY for generated marketing illustrations/videos** — `the project's illustration-motion pattern doc (listed in `.baldart/overlays/frontend-design.md` if present)` (if your project has one). Canonical illustration language, product-variant vocabulary, and surgical element-by-element video prompt contract.
-
-Non-negotiable constraints typical of mature design-system SSOTs (adapt to your project):
-
-- Token consumption: only via the project's design-token mechanism (e.g. CSS custom properties, Tailwind theme, Stitches tokens). Never hardcode values outside this contract.
-- **Themed-surface text/bg pairing rule (MANDATORY / BLOCKING)** when the design-system defines a primary theme color: any text rendered over the themed primary background MUST pair with the project's theme-primary-text token (e.g. `text-[var(--theme-primary-text,#000)]` on `bg-[var(--theme-primary)]`).
-- Do NOT create new overlay systems if the project already catalogs an overlay decision tree — pick from the existing options.
-- **Chart library (MANDATORY / BLOCKING)** when the project standardizes a chart stack: use only the approved library and the project's wrappers, never call the underlying chart library from feature code. Banned libraries (typical): `chart.js`, `echarts`, `victory`, `visx`, `d3` standalone, `observable-plot`, `tremor`. Exceptions require an ADR.
-
-Within those bounds, creative choices (typography nuance, composition, motion intensity) are welcome — but the design-system token contract and themed-surface pairing are non-negotiable.
-
----
-
-## Performance Gates (Core Web Vitals 2026)
-
-Production-grade frontend is not just "looks good" — it ships within the CWV
-thresholds. Every page / component / route MUST be designed against these
-budgets, not retrofitted after Lighthouse complains.
-
-### Thresholds (p75, CrUX dataset)
-
-| Metric | Good | Poor | What it measures |
-|---|---|---|---|
-| **LCP** | ≤ 2.5s | > 4.0s | Largest Contentful Paint — usually the hero image or H1 |
-| **INP** | ≤ 200ms | > 500ms | Interaction to Next Paint — replaced FID in Mar 2024 |
-| **CLS** | ≤ 0.1 | > 0.25 | Cumulative Layout Shift |
-| TTFB | ≤ 0.8s | > 1.8s | Subset of LCP (~40% of budget) |
-| FCP | ≤ 1.8s | > 3.0s | Diagnostic only |
-
-A page passes CWV when all three (LCP/INP/CLS) are *good* at p75. INP is the
-hardest of the three on JS-heavy apps and the most commonly failed (~43% of
-sites globally).
-
-### LCP image: the only correct pattern
-
-```html
-<!-- in <head> — preload + fetchpriority for the hero -->
-<link rel="preload" as="image"
-      href="/hero.avif"
-      imagesrcset="/hero-800.avif 800w, /hero-1600.avif 1600w"
-      imagesizes="100vw"
-      fetchpriority="high">
-
-<!-- in body — picture with AVIF/WebP/fallback + explicit dimensions -->
-<picture>
-  <source srcset="/hero.avif" type="image/avif">
-  <source srcset="/hero.webp" type="image/webp">
-  <img src="/hero.jpg" alt="..."
-       fetchpriority="high"
-       width="1600" height="900">
-</picture>
-```
-
-**Never** apply `loading="lazy"` to the LCP image. **Never** render the LCP
-image via client-side JS after hydration — server-render it or preload it.
-
-### INP fixes
-
-- Break any task > 50ms into `await scheduler.yield()` chunks (Chrome 129+;
-  fallback `await new Promise(r => setTimeout(r, 0))`).
-- Debounce input handlers to one frame (~16ms) when they trigger expensive
-  recomputes. Throttle scroll/resize to `requestAnimationFrame`.
-- Move CPU-bound work (parsing, transforming, encoding) off the main thread
-  with Web Workers when latency matters.
-- Avoid `setInterval` polling for data — use SWR / React Query / TanStack
-  Query with stale-while-revalidate.
-
-### CLS budget — zero unexpected shift
-
-- Every `<img>`, `<iframe>`, `<video>` declares `width` + `height` or
-  `aspect-ratio` CSS.
-- Web fonts: `font-display: optional` (no FOIT/FOUT shift, accept fallback
-  on first load) OR `size-adjust` + matching `ascent-override` /
-  `descent-override` / `line-gap-override` to produce a metric-compatible
-  fallback font.
-- Skeleton screens mirror the real layout dimensions exactly — a skeleton
-  that's the wrong height *causes* CLS instead of preventing it.
-- Inserted UI (banners, cookie notices, ads) must reserve space upfront via
-  `min-height` — never push existing content down post-paint.
-
-## Modern CSS (2025–2026)
-
-Default to platform features instead of JS shims:
-
-- **Container queries** (`@container` + `container-type: inline-size`) —
-  default for any component that lives in variable-width contexts (sidebar,
-  grid cell, modal). Component decides its own breakpoint, independent of
-  viewport. Use viewport-based `@media` only for app-shell-level layout.
-- **`:has()`** — collapse `useState` that exists *only for styling*
-  (e.g. label color reacting to input invalid state). Never put business
-  logic into `:has()` — only visual reactions to DOM state.
-- **View Transitions API** — `document.startViewTransition()` for SPA
-  navigation and `view-transition-name` for shared-element morphs. See
-  `motion-design/reference/accessibility-and-modern-apis.md` for the full
-  pattern.
-- **Subgrid** — children align to the parent grid without re-declaring
-  tracks. Fixes the long-standing "card content alignment across rows"
-  problem.
-- **Logical properties** — `margin-inline-start` / `padding-block` instead
-  of `margin-left` / `padding-top` whenever the project might add RTL or
-  vertical-writing-mode locales. Free i18n with zero overhead.
-- **`color-mix()`** — derive hover / focus / disabled states from semantic
-  tokens without inventing new tokens
-  (`color-mix(in oklch, var(--color-action-primary) 90%, black)`).
-- **`@scope`** — scope CSS to a subtree without selector specificity wars or
-  CSS-in-JS. Useful when migrating off CSS Modules / styled-components.
-
-## Form quality (always-on requirements)
-
-These apply to every form, every project — they are not "nice to have":
-
-- `<label>` associated to input via `htmlFor` / `id` (never wrap-only — fails
-  some screen readers).
-- `autocomplete=` filled for every personal-data field
-  (`email | tel | given-name | family-name | street-address | postal-code |
-  cc-number | one-time-code` …). Required by WCAG 2.1 SC 1.3.5.
-- Validation **on blur**, not on every keystroke. Re-validate on submit.
-- Error messages are **actionable** ("Email manca @ — esempio:
-  nome@dominio.it"), never generic ("Invalid input").
-- `aria-invalid` + `aria-describedby` linking the input to its error
-  element. Error element has `role="alert"` only when it appears
-  dynamically.
-- `inputMode=` set when it differs from `type` (e.g. `type="text"
-  inputMode="numeric"` for SMS codes — keeps the field text-shaped but
-  triggers the numeric keypad).
-- Paste handling normalizes whitespace and format BEFORE validating
-  (cc-number without spaces, tel without separators).
-- Submit button disabled only **after** a failed attempt — never blocked
-  pre-emptively; users should be allowed to try and receive feedback.
-
----
-
-## Standalone Prototypes and Demos
-
-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
-
-**`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.
+# frontend-design — router (retired generator)
+
+Since framework v5.2.0 this skill no longer generates or styles UI. Its
+design intelligence (aesthetic direction, craft rules, anti-slop bans,
+Performance Gates/CWV, Modern CSS, form quality) was superseded and moved to
+the **`ui-design`** skill's references, which are the single SSOT:
+
+- `ui-design/references/craft-standards.md` — always-on craft + **Performance
+  Gates (CWV 2026)** + Modern CSS + form quality (the sections that used to
+  live in this file).
+- `ui-design/references/anti-slop.md` — the anti-generic-AI Tells catalog.
+- `ui-design/references/design-directions.md` — aesthetic directions, font
+  and palette discipline.
+
+## Route the request (do this instead of proceeding here)
+
+| The task is… | Route to |
+|---|---|
+| Designing, prototyping, exploring options, restyling/redesigning a page or component — any *design decision* work | **`/ui-design`** (the local design studio) |
+| Implementing an ALREADY-APPROVED mockup (image / HTML / Claude Design link / `mockups/_src/`) into the codebase | **`/ui-implement`** |
+| A direct in-code UI change with no new design decision (fix a layout, restyle within the existing language, build a specified component) | delegate to the **`ui-expert`** agent per `AGENTS.md` § delegation (registry-first cascade applies) |
+| Motion/animation specs | **`/motion-design`** |
+| A standalone one-off artifact not tied to this project (poster, demo page) | **`/ui-design`** in exploration regime |
+
+Announce the reroute in one line (e.g. "frontend-design è stato ritirato a
+router — proseguo con /ui-design") and continue seamlessly with the target
+surface. Do NOT stop to ask permission for the reroute; do NOT apply design
+guidance from any earlier version of this file.
+
+## Consumer overlays
+
+If this project carries `.baldart/overlays/frontend-design.md` (aesthetic
+mandates, illustration-motion contract), those opinions belong on the design
+studio now — port them to `.baldart/overlays/ui-design.md` (the `/overlay`
+skill scaffolds it). Until ported, honor them when routing lands on
+`/ui-design`.

package/framework/.claude/skills/gamification-design/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.0.1 — 2026-07-03
+
+- Related Skills: `ui-ux-pro-max` (superseded) sostituito con `ui-design` v2
+  (design-directions + craft-standards references). Framework v5.2.0.
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,7 +1,7 @@
 ---
 name: gamification-design
 effort: medium
-version: 1.0.0
+version: 1.0.1
 description: Use when designing or analyzing points systems, reward loops, progression mechanics, engagement features, or loyalty programs. Triggers include "points system," "rewards design," "progression," "engagement loop," "battle pass," "loyalty mechanics," "gamification," or "retention hooks." For B2C customer-facing features in this codebase, this skill invokes the hyper-gamification-designer agent.
 ---
 
@@ -133,7 +133,7 @@ Before invoking the agent, verify you have:
 
 - `prd-planning`: For full PRD with gamification section
 - `copywriting`: For reward/achievement messaging
-- `ui-ux-pro-max`: For gamification UI patterns
+- `ui-design`: For designing gamification UI (mockups/options; its `references/design-directions.md` + `craft-standards.md` replace the retired `ui-ux-pro-max`)
 
 ## Project Integration
 

package/framework/.claude/skills/prd/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.4.0 — 2026-07-03
+
+- **Research-profile contract + library (framework v5.1.0)**: Step 2.5 now
+  spawns `senior-researcher` with `PROFILE=decision` (`PROFILE=regulatory` on
+  signal S2) per `framework/agents/research-protocol.md` — the per-topic,
+  recommendation-first contract that matches "Processing Findings"
+  byte-for-byte (the old prompt asked for a light format while the agent's
+  contract mandated the full §0–§11 report: two conflicting SSOTs, now one).
+  /prd PRE-ALLOCATES the output path — the research library
+  (`${paths.research_dir}/<category>/RES-<YYYYMMDD>-<slug>.md`) when
+  configured, legacy `${paths.prd_dir}` fallback otherwise — and the agent
+  ALWAYS writes a file there (`FULL_REUSE` → pointer stub), so the 10-minute
+  exit-check poll stays deterministic and prior research is reused instead of
+  re-paid. Same token in the discovery-phase background launch (parallel
+  location, updated together).
+
 ## 1.3.0 — 2026-07-02
 
 - **Analysis-profile contract (framework v4.94.0)**: the discovery-loop targeted architect question now passes `PROFILE=discovery`, and the Step 2 ISA scan passes `PROFILE=impact` (structural tier primary) — per `framework/agents/analysis-profiles.md`. Prompt semantics otherwise unchanged.

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

@@ -1,7 +1,7 @@
 ---
 name: prd
 effort: high
-version: 1.3.0
+version: 1.4.0
 description: "Structured PRD creation skill. Use when the user says /prd, 'crea un prd', 'nuova funzionalita', 'pianifica feature', or wants to plan a new feature end-to-end. Also handles /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint' for change requests on active PRD sessions — runs ICIAS impact analysis to determine which phases need SKIP/PATCH/REDO. Produces PRD + UI design + backlog cards, all validated and committed. Multi-turn conversation: asks questions, waits for answers, iterates through discovery, design, spec writing, card creation, and validation phases."
 ---
 

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

@@ -972,7 +972,11 @@ source is authoritative — do NOT issue a separate file-read mid-discovery.)
 
 **SEMANTIC decision:**
 - **2+ signals OR regulatory (S2) OR user uncertainty (S5)** → HIGH confidence
-  → launch `senior-researcher` in **background immediately**, continue discovery.
+  → launch `senior-researcher` in **background immediately** with
+  `PROFILE=decision` (`PROFILE=regulatory` when S2 is the trigger) and the
+  pre-allocated output path — spawn prompt + output contract in
+  `research-phase.md` § "Research Execution" (do NOT improvise a variant here);
+  continue discovery.
   Update progress bar: `Ricerca: 🔍 in corso (background)`.
 - **1 non-critical signal** → MEDIUM confidence → note for later (ask at exit).
 - **No signals** → skip research. Update progress bar: `Ricerca: ⏭️ non necessaria`.

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

@@ -78,12 +78,26 @@ Trigger as soon as confidence is HIGH (typically at ~75% comprehension).
    > `BACKGROUND_RUN=true` directive so the agent knows to begin research
    > immediately. Add this as the first line of the prompt.
 
+   > **Profile + output path (v5.1.0)**: the researcher runs `PROFILE=decision`
+   > (`PROFILE=regulatory` when signal S2 matched) — the per-topic,
+   > recommendation-first contract of `agents/research-protocol.md
+   > SECTION=profiles`, which matches "Processing Findings" below byte-for-byte.
+   > /prd PRE-ALLOCATES the exact output path so the exit-check poll stays
+   > deterministic: when `paths.research_dir` is set, the report lands in the
+   > research library — `${paths.research_dir}/<category>/RES-<YYYYMMDD>-<slug>.md`
+   > (pick the closest category: architecture | integrations | regulatory |
+   > ux-patterns | algorithms | tooling); when the key is missing/empty
+   > (consumer not yet reconfigured post-update), fall back to the legacy path
+   > `${paths.prd_dir}/<slug>/research-<slug>-<session-id>.md`. Either way the
+   > prompt carries ONE known path.
+
    ```
    Task tool:
      subagent_type: "senior-researcher"
      run_in_background: true
      prompt: |
        BACKGROUND_RUN=true — skip the FIRST MESSAGE TEMPLATE preamble entirely.
+       PROFILE=decision   (use PROFILE=regulatory when launched off signal S2)
        Begin research immediately without waiting for acknowledgment.
 
        Research the following topics for a PRD we're writing for feature
@@ -99,20 +113,16 @@ Trigger as soon as confidence is HIGH (typically at ~75% comprehension).
        1. <question>
        2. <question>
 
-       For each topic, provide:
-       - Summary of best practices (with sources)
-       - Recommended approach for the project stack above
-       - Key gotchas or anti-patterns to avoid
-       - If applicable: regulatory checklist or compliance requirements
-
        OUTPUT CONTRACT (mandatory):
        Write your complete research report to the file:
-         ${paths.prd_dir}/<slug>/research-<slug>-<session-id>.md
-       where <session-id> is a short UUID you generate at start.
-       Log the exact output path as the FIRST line of your report:
+         <pre-allocated path — library path, or the prd_dir fallback above>
+       Log the exact output path as the FIRST line of the report body
+       (right after the frontmatter):
          RESEARCH_OUTPUT_PATH: <full path>
-       This path is how the PRD orchestrator will read your findings.
-       Be concise but thorough.
+       ALWAYS write a file at that path — on FULL_REUSE, write the pointer
+       stub defined in agents/research-protocol.md SECTION=reuse instead of
+       a new report. This path is how the PRD orchestrator will read your
+       findings. Be concise but thorough.
    ```
 
 3. **Continue discovery** — do NOT wait for the researcher. Ask remaining
@@ -200,6 +210,11 @@ Questo aggiunge qualche minuto ma produce decisioni piu informate.
 
 When `senior-researcher` returns:
 
+0. **Reuse stub?** If the file at the pre-allocated path is a `FULL_REUSE`
+   pointer stub (`REUSE: FULL_REUSE -> <path>`), read the pointed report —
+   the library already had this research, treat it as an instant completion.
+   A `DELTA` report reads normally (it IS the updated research).
+
 1. **Store findings** in state file under `## Research Findings`:
    ```
    ## Research Findings
@@ -208,15 +223,20 @@ When `senior-researcher` returns:
    Topics researched: [list]
 
    ### Topic 1: <title>
+   **Recommended approach**: <for our stack — the report's recommendation line>
    **Best practice**: <summary>
-   **Recommended approach**: <for our stack>
    **Gotchas**: <anti-patterns to avoid>
+   **Contradictions & Unknowns**: <where evidence disagrees or is missing — or "none">
    **Sources**: <references>
 
    ### Topic 2: <title>
    ...
    ```
 
+   (mirrors the `decision`-profile report structure — recommendation first,
+   contradictions never dropped: they are the findings that change a design
+   direction.)
+
 2. **Evaluate if findings reveal gaps** in the discovery:
    - Do the findings introduce new dimensions or considerations NOT covered
      by existing discovery answers?

package/framework/.claude/skills/research/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog — research skill
+
+## 1.0.0 — 2026-07-03 (framework v5.1.0)
+
+- Initial release. Interactive orchestrator over the research library:
+  scoping → profile/nature routing → reuse pre-flight → senior-researcher
+  launch (parallel fan-out on Claude, sequential on Codex) → filing +
+  INDEX ownership → source-matrix growth loop. THIN — all rules live in
+  `agents/research-protocol.md`, all report forms in `assets/`.

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

@@ -0,0 +1,94 @@
+---
+name: research
+effort: medium
+version: 1.0.0
+description: >
+  Interactive research orchestrator over the research library. Scopes the
+  question with the user, routes it to the right profile (decision / deep /
+  compare / regulatory) and source policy by research NATURE (scientific →
+  papers; dev → docs+forums; regulatory → normative texts; ux; market), checks
+  the library INDEX for reusable prior research BEFORE searching, then launches
+  the senior-researcher agent (parallel fan-out for composite questions), files
+  the report in ${paths.research_dir} and keeps INDEX.md correct. Closes the
+  source-matrix growth loop (SOURCE_MATRIX_CANDIDATE → local SOURCES.md and/or
+  upstream BALDART prompt). A THIN orchestrator — cites
+  agents/research-protocol.md for every rule, never duplicates it. Use when the
+  user says /research, "fai una ricerca", "ricerca best practice", "confronta X
+  e Y", "ricerca scientifica su", "è già stato ricercato?", "cosa dice la
+  letteratura su". NOT for /prd's embedded research step (prd spawns the agent
+  directly) and NOT a replacement for the agent (which stays directly
+  spawnable).
+---
+
+# Research — orchestrated research over the library
+
+## Project Context
+
+**Reads from baldart.config.yml:** `paths.research_dir` (the library),
+`paths.docs_dir` (degrade target), `stack.*` (stack signature for the
+recommendation binding).
+**Writes:** research reports + INDEX rows under `${paths.research_dir}`;
+optionally `SOURCES.md` `## Local additions`.
+**Gated by features:** none — research is universal.
+**On missing/empty keys:** `paths.research_dir` empty/absent → offer
+`npx baldart configure` (or ask for a path and suggest persisting it); the
+user may decline and run library-less (reports go to `${paths.docs_dir}/`,
+no reuse pre-flight). Never hard-abort.
+Protocol: `framework/agents/project-context.md`.
+
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+## Invocation
+
+```
+/research <topic>                      # scoping → routed research
+/research PROFILE=<decision|deep|compare|regulatory> <topic>
+/research DEPTH=<1..3> <topic>         # deep-profile iterative loop
+/research status                       # library health: INDEX + expiring reports
+```
+
+## Flow
+
+THIN orchestration — every rule below is DEFINED in
+`agents/research-protocol.md` (read the cited SECTION only) and every output
+FORM in `assets/`; this skill only sequences them. Full step-by-step detail,
+scoping questions and recovery: `references/playbook.md`.
+
+1. **Scoping** — clarify question, research nature and purpose with the user
+   (max 3 questions via AskUserQuestion; ZERO when the request is already
+   specific). Build the stack signature from `stack.*`.
+2. **Routing** — purpose → `PROFILE=` (`SECTION=profiles`); nature → source
+   policy row (`SECTION=sources`). State the routing in one line before
+   launching.
+3. **Reuse check** — read `${paths.research_dir}/INDEX.md`, match per
+   `SECTION=reuse`. On a hit, present FULL_REUSE / DELTA to the user before
+   any new research is paid for.
+4. **Launch** — pre-allocate id + output path (`SECTION=library`) and spawn
+   `senior-researcher` with `PROFILE=` (+ `DEPTH=` if given), the stack
+   signature, the pre-allocated path, and `FILING=orchestrator` (this skill
+   owns the INDEX rows). Composite questions (2+ independent sub-questions) →
+   parallel fan-out, one spawn per sub-question, each with its own
+   pre-allocated path. **Codex**: no parallel subagent fan-out — spawn
+   sequentially by name (`agents/runtime-portability-protocol.md`).
+5. **Filing** — verify each report exists at its pre-allocated path with valid
+   frontmatter; append the INDEX rows (serialized, one writer: this skill).
+   On any mismatch run `scripts/rebuild-research-index.mjs` to reconcile.
+6. **Matrix loop** — if a report contains `## SOURCE_MATRIX_CANDIDATE`
+   (`SECTION=sources`), offer both: (a) apply it now to
+   `${paths.research_dir}/SOURCES.md` under `## Local additions`; (b) show the
+   ready-to-paste BALDART prompt for upstreaming the change to the framework
+   default matrix.
+7. **Return** — recommendation headline + `Report: <path>` (+ reuse decision,
+   + matrix candidate note). The report body stays on disk.
+
+## `/research status`
+
+Read INDEX.md only: report totals per category, reports past `valid_until`
+(refresh candidates → offer a DELTA run), and any INDEX↔frontmatter drift
+(offer `scripts/rebuild-research-index.mjs`).

package/framework/.claude/skills/research/assets/report-compare.template.md

@@ -0,0 +1,50 @@
+---
+id: RES-YYYYMMDD-slug
+title: ""
+category: tooling
+tags: []
+profile: compare
+nature: market
+stack_signature: ""
+date: YYYY-MM-DD
+valid_until: YYYY-MM-DD
+status: current
+questions: []
+sources_count: 0
+related: []
+---
+
+RESEARCH_OUTPUT_PATH: <this file's path>
+REUSE: NEW | DELTA -> <prior report path>   <!-- a FULL_REUSE run writes the pointer stub (SECTION=reuse), not this template -->
+
+# <Title> — <Option A> vs <Option B> [vs <Option C>]
+
+## Recommendation
+
+<one decisive paragraph, bound to the stack signature; name the runner-up and when it wins instead>
+
+## Comparison matrix
+
+<!-- Fixed axes; keep ≤ 8 columns — split rows, not columns, when options exceed the width. -->
+
+| Axis | <Option A> | <Option B> | <Option C> |
+|---|---|---|---|
+| Performance | | | |
+| Cost | | | |
+| Complexity | | | |
+| Risk | | | |
+| Maturity | | | |
+| Adoption | | | |
+
+<!-- Every non-obvious cell claim carries a citation + evidence label. -->
+
+## When NOT to use
+
+- **<Option A>**: <disqualifying conditions>
+- **<Option B>**: …
+
+## Contradictions & Unknowns
+
+## Sources
+
+- [Source Year] <title> — <url> (<date>) [evidence label]

package/framework/.claude/skills/research/assets/report-decision.template.md

@@ -0,0 +1,42 @@
+---
+id: RES-YYYYMMDD-slug
+title: ""
+category: architecture   # architecture|integrations|regulatory|ux-patterns|algorithms|tooling
+tags: []
+profile: decision
+nature: dev              # scientific|dev|regulatory|ux|market
+stack_signature: ""
+date: YYYY-MM-DD
+valid_until: YYYY-MM-DD  # date + category TTL (research-protocol.md SECTION=reuse)
+status: current
+questions: []
+sources_count: 0
+related: []
+---
+
+RESEARCH_OUTPUT_PATH: <this file's path>
+REUSE: NEW | DELTA -> <prior report path>   <!-- a FULL_REUSE run writes the pointer stub (SECTION=reuse), not this template -->
+
+# <Title>
+
+<!-- One block per research question. Recommendation FIRST — the reader is
+     mid-decision; everything else is supporting material. -->
+
+## Topic 1: <question>
+
+**Recommendation (for this stack):** <one decisive paragraph — what to do and why, bound to the stack signature>
+
+**Best practices:**
+- <practice> [Source Year] [STRONG|MODERATE|WEAK|OPINION]
+
+**Gotchas / anti-patterns:**
+- <gotcha and its cost> [Source Year]
+
+**Contradictions & Unknowns:** <!-- MANDATORY, even when empty: say "None found — evidence is consistent." -->
+- <where evidence disagrees or is missing, and what would resolve it>
+
+**Sources:**
+- [Source Year] <title> — <url> (<date>) [evidence label]
+
+## Topic 2: <question>
+…