baldart 4.76.0 → 4.76.1

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.76.1] - 2026-06-26
+
+**`/design-system-init` offers a render surface (opt-in Storybook scaffold).** The render harness (Stage C) needs a Storybook, and a registry-only project has none — so the harness was a silent no-op with nowhere to go. Now `/design-system-init`, after scaffolding the registry, OFFERS (default-NO, JS/TS stacks only) to run the **official `npx storybook init`** so the harness has a surface. It **never hand-writes a per-stack render surface and never auto-wires the project's providers** — that "auto-provider-shim" is the refuted false-fidelity trap; instead it leaves a `.storybook/preview` decorator TODO so **the user owns the context-shimming** (theme/i18n/router), which is how Storybook does it correctly. `/ds-render`'s no-op message now points here. Declined / Codex / non-JS → skipped (publish still works via static-spec cards).
+
+**PATCH** — opt-in, no behaviour change for projects that decline or already have Storybook; no new config key.
+
+### Changed
+- **`/design-system-init` step 7b** (`framework/.claude/skills/design-system-init/SKILL.md`) — opt-in `npx storybook init` offer + the user-owned-decorator TODO; cross-ref `/ds-render`.
+- **`/ds-render` no-Storybook message** (`framework/.claude/skills/ds-render/SKILL.md`) — points to the init offer instead of a dead no-op.
+
 ## [4.76.0] - 2026-06-26
 
 **Closed-loop design system: BALDART ⇄ Claude Design.** BALDART owns the design system; Claude Design is where designers draw mockups. The two **diverge** over time — v4.75 made every new mockup born on the project's tokens, but that alignment decays as the in-repo registry evolves and the satellite stays frozen. This release adds the machinery to keep them in sync with **ONE authority** (the in-repo registry — `.tokens.json` + `components/<Name>.md` HEAD + INDEX/Selection-Policy + `ds-gate`); Claude Design is a **satellite mirror**, never a 2nd SSOT. Planned via a multi-agent workflow (map → per-axis design → adversarial refutation → completeness/SSOT critic → synthesis) which **refuted** the obvious-but-wrong pieces before any code.

package/VERSION

@@ -1 +1 @@
-4.76.0
+4.76.1

package/framework/.claude/skills/design-system-init/SKILL.md

@@ -234,9 +234,28 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    `paths.design_system: <target>`, and (when tokens bootstrapped)
    `paths.design_tokens` + `design_tokens.outputs`. Use the same YAML write path
    as `configure` (preserve user values, never clobber unrelated keys).
+7b. **Offer a render surface — OPT-IN, never forced (closed-loop Stage C enabler).**
+   A registry documents components but cannot RENDER them in isolation — the render
+   harness (`baldart render` / `/ds-render`) needs a Storybook. If **no `.storybook/`
+   exists** AND the stack is JS/TS (`stack.framework` is react/vue/svelte/etc.),
+   ASK the user (one consolidated question, default-NO): *"Vuoi che inizializzi
+   Storybook così il render harness può montare i primitivi in isolamento? (serve
+   per la verifica di qualità isolata e per il render dei componenti)"*. On YES:
+   - **Delegate to the official scaffolder** — run `npx storybook init` (stack-aware;
+     installs the right `@storybook/<framework>` devDeps + writes `.storybook/main`
+     + `preview`). NEVER hand-write a per-stack render surface and NEVER auto-wire
+     the project's providers — that "auto-provider-shim" is the REFUTED false-fidelity
+     trap. Instead leave a **TODO in `.storybook/preview`**: *"add your ThemeProvider
+     / i18n provider / router here as a decorator so isolated primitives render with
+     real context"* — **the user owns the decorators** (that is how Storybook does the
+     context-shimming correctly).
+   - On Codex / non-JS stack / user declines → skip silently; the harness simply
+     stays a no-op (publish still works via static-spec cards). This is an offer, not
+     a requirement.
 8. **Print next-steps.** Specs needing agentic review (empty fields), the
    round-trip token diff if non-empty, suggested follow-up (`/design-review` on a
-   key route).
+   key route); if Storybook was initialized, the `.storybook/preview` decorator TODO
+   + `/ds-render` to render the primitives.
 
 ## Workflow
 

package/framework/.claude/skills/ds-render/SKILL.md

@@ -43,7 +43,11 @@ Baseline `medium`. Honor an inline `effort=<level>` override.
 
 1. **Build the surface.** `baldart render build [--full]` → emits
    `render-manifest.json` (from the component HEADs) + generates the adapter render
-   surface (ephemeral `.baldart.stories.tsx`). No Storybook → STOP (clean no-op).
+   surface (ephemeral `.baldart.stories.tsx`). **No Storybook → STOP (clean no-op)**
+   and tell the user the harness needs a render surface: offer to run
+   `/design-system-init` (which proposes `npx storybook init`, opt-in — § step 7b)
+   or to `npx storybook init` directly, then re-run `/ds-render`. Never auto-install
+   Storybook from this skill.
 2. **Run the screenshot loop** (this skill owns the browser via `playwright-skill`):
    `npx storybook build -o .harness/storybook-static`, then for each story
    `iframe.html?id=<storyId>&viewMode=story` capture a PNG into `.harness/shots/`.

package/package.json

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