baldart 4.80.1 → 4.82.0

package/CHANGELOG.md

@@ -5,6 +5,50 @@ 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.82.0] - 2026-07-01
+
+**Mockup→code extracted into a dedicated self-verifying skill `/ui-implement` + skills are now versioned.** The mockup→code fidelity knowledge (v4.73→v4.78) was **inlined inside `/new`**: the "Design Reference" briefing (image/HTML/code-src branching), the design-source declaration + Step 7b grounding, and the Phase 2.6 `/e2e-review` invocation. This release **externalizes** it into one specialized, self-verifying skill and, separately, introduces **per-skill versioning + a canonical structure** across all skills.
+
+`/ui-implement` takes an ALREADY-APPROVED mockup and (1) **dispatches on the input channel** via `references/playbook.md` — a Claude Design handoff link (→ pull the screen's source read-only via the DesignSync MCP into `mockups/_src/`, then build-from-code — the primary standalone channel), finished code already on disk (`links.design_src`/`mockups/_src/` → build-from-code, reuse-first), image (→ load-image, pixels are the target), HTML (→ read-html, decode a Claude Design offline bundle via `extract-mockup-design.mjs`); **no Figma channel** (this project never uses Figma); (2) runs the registry-first cascade + component reconciliation; (3) builds via the **`ui-expert`** agent + grounds the design-source declaration; (4) reconciles the Post-Intervention Coherence; (5) **self-verifies fidelity** by folding in `/e2e-review` (structural + visual + design-quality trio + its own self-heal). A **THIN orchestrator** that cites `design-system-protocol.md`, `ui-expert.md`, `/e2e-review` and the verifier trio, never duplicating them (no dual-SSOT). Its scope is **fidelity ONLY** — `/new` still owns code-quality/doc/QA/ownership for a mixed card (no review hole); a pure-graphics card already skips those. `/new` **delegates** a UI card's implement+fidelity to it (programmatic, COMPACT JSON, same `status` contract as `/e2e-review`), retiring `implement.md`'s mockup detail to a thin pointer + **coarse inline fallback** (delegate-or-else-inline, the `/prd`→`/ds-handoff` model). Usable standalone (`/ui-implement <mockup-path-or-CARD-ID>`). `new2.js` keeps its inline path this release (parity is a follow-up after the context-economy measurement).
+
+Every shipped skill now carries a **`version:` SemVer** (starting `1.0.0`, the skill's own line of evolution) + a **separate per-skill `CHANGELOG.md`** (deliberately NOT a `SKILL.md` section, so version history never burns context on load). Canonical structure: `SKILL.md` + `CHANGELOG.md` required; `references/`/`assets/`/`scripts/` on demand only. `skill-creator` is the SSOT (`init_skill.py` scaffolds `version` + `CHANGELOG.md` and drops placeholder-dir noise; `quick_validate.py` allows `effort`/`version` and warns non-fatally on missing `version`/`effort`/`CHANGELOG.md`; full rule in `references/skill-structure.md`).
+
+**MINOR** — adds a skill (40 → 41) + a skill-metadata convention. No new `baldart.config.yml` key (`version` is skill-frontmatter metadata, `/ui-implement` rides on `features.has_design_system` + `features.has_e2e_review`) → the schema-change propagation rule does NOT apply. Additive + degrades to no-op / coarse fallback everywhere it can't run.
+
+### Added
+
+- **`framework/.claude/skills/ui-implement/`** — new skill: `SKILL.md` (thin orchestrator), `references/playbook.md` (input-type → build-workflow dispatch), `references/integration.md` (delegation contract from `/new`/`new2` + standalone), `CHANGELOG.md`.
+- **`framework/.claude/skills/skill-creator/references/skill-structure.md`** — the canonical-structure + versioning SSOT.
+- **`framework/.claude/skills/*/CHANGELOG.md`** — a per-skill changelog for all 41 skills (baseline `1.0.0`).
+
+### Changed
+
+- **`framework/.claude/skills/*/SKILL.md`** — added/normalized `version: 1.0.0` in every skill's frontmatter.
+- **`framework/.claude/skills/new/references/implement.md`** — the Design-Reference block now leads with a **delegation gate** to `/ui-implement` and compresses the mockup-specific detail into a coarse fallback that cites the playbook + `ui-expert.md`; registry-first cascade + Post-Intervention Coherence left intact (they apply to every UI card).
+- **`framework/.claude/skills/new/references/review-cycle.md`** — Phase 2.6 skips when the card was delegated to `/ui-implement` (the skill already ran the fidelity verify) + a maintainers' drift note (new2 keeps the inline path).
+- **`framework/.claude/skills/skill-creator/scripts/init_skill.py`** — template frontmatter gains `effort` + `version`; generates `CHANGELOG.md`; no longer scaffolds placeholder `scripts/`/`references/`/`assets/` dirs; updated next-steps.
+- **`framework/.claude/skills/skill-creator/scripts/quick_validate.py`** — `effort`/`version` are allowed frontmatter keys; non-fatal warnings when `version`/`effort`/`CHANGELOG.md` are missing.
+- **`framework/.claude/skills/skill-creator/SKILL.md`** — `CHANGELOG.md` is now the documented exception to "what not to include" (required); Step 3/4 describe the new scaffold behaviour; frontmatter section adds `version` + the no-angle-brackets rule.
+- **`framework/agents/skills-mapping.md`** — new `### ui-implement` entry (UI/UX Skills) + a "Skill Versioning & Canonical Structure" section.
+- **`CLAUDE.md`**, **`README.md`** — skill count 40 → 41, `ui-implement` in the inventory, two new convention entries (the dedicated skill + skill versioning).
+
+## [4.81.0] - 2026-06-29
+
+**Playwright capture is CLI-only — no Playwright MCP anywhere in the framework.** BALDART already used the **Playwright Test CLI** for its main capture pipeline (`/e2e-review` Phase 3→4, `playwright-skill`, `webapp-testing`'s headless Python scripts), but three surfaces still drove the **Playwright MCP** interactively: the `bug` skill (Phase 1 UI reproduction via `browser_navigate`/`browser_take_screenshot`/`browser_console_messages`/`browser_network_requests`/`browser_evaluate`), the `/design-review` command (`allowed-tools` declared the four `mcp__playwright__*` tools + relied on `localhost:9221`), and the `/qa` DEEP tier ("Use MCP Playwright if available"). For **deterministic capture** the MCP is pure token overhead — every action round-trips a result (often a full a11y-tree snapshot) into context, accumulating per-step; a headless CLI script enters context once and writes screenshots/console/network to disk, read back only when needed. This release converts those three surfaces to the CLI so **no Playwright MCP is ever loaded into the agent context**.
+
+The `bug` skill's interactive `browser_evaluate` instrumentation (fetch interceptor, SWR mutation tracker) is preserved with **zero loss of capability** by moving it into `page.addInitScript(() => { … })` inside the headless capture script — same injection, headless and reproducible, with the forwarded `console.*` collected via `page.on('console', …)` and read from disk.
+
+**MINOR** — behaviour change across `bug`, `/design-review`, `/qa` (the Playwright MCP dependency is removed; capture is now CLI). No new config key, no install-layout change. The Codex broker's leaked Playwright-MCP orphans (spawned from the user's `~/.codex/config.toml`, independent of BALDART) remain handled by the `baldart doctor` orphan reaper — untouched.
+
+### Changed
+
+- **`framework/.claude/skills/bug/SKILL.md`** — frontmatter, "MCP dependencies" (Playwright MCP required → "None required for browser capture"; CLI via webapp-testing), Phase 0 triage tool, Phase 1 UI reproduction (browser_* steps → headless capture script writing screenshot/console/network to disk), Phase 2 client-side logging (`browser_evaluate` → `page.addInitScript`), Phase 3 evidence collection, Phase 5 verify, Tools Quick Reference.
+- **`framework/.claude/skills/bug/references/logging-patterns.md`** — "Playwright MCP Debug Patterns" → "Playwright CLI Debug Patterns"; `// browser_evaluate:` → `page.addInitScript()` in the capture script.
+- **`framework/.claude/commands/design-review.md`** — removed the four `mcp__playwright__*` tools from `allowed-tools`; the route capture is now a headless Playwright CLI screenshot (Bash) read back as a PNG, instead of opening the MCP browser on `localhost:9221`.
+- **`framework/.claude/commands/qa.md`** — DEEP-tier UI quality checks use a headless Playwright CLI screenshot script (when `@playwright/test` is installed) instead of MCP Playwright.
+- **`framework/.claude/skills/playwright-skill/SKILL.md`** — the cross-reference to `bug` no longer says it "requires `mcp__playwright__browser_*`"; both use the CLI.
+- **`framework/docs/MCP-INTEGRATION.md`** — "Browser automation" catalog entry: Playwright MCP → **Playwright CLI**, with the token-economy rationale and the note that the Codex-broker orphan reaper is independent; the section-authoring example tool prefix swapped off `mcp__playwright__browser_navigate` (now a Firebase example) so the doc no longer implies BALDART uses the Playwright MCP.
+
 ## [4.80.1] - 2026-06-29
 
 **Self-heal payload drift on an already-current install + a Codex-correct "agent not found" message.** Shipping v4.80.0 surfaced two gaps in the field, both from the same incident: a consumer's Codex session emitted the AGENTS.md STOP message for `codebase-architect`, yet the framework was already at v4.80.0. Two root causes:

package/README.md

@@ -212,14 +212,16 @@ Skills always-ask when required keys are missing — never silently default.
 never overwrites your file. Full guide:
 [`framework/docs/PROJECT-CONFIGURATION.md`](framework/docs/PROJECT-CONFIGURATION.md).
 
-### Skills (40 portable skills)
+### Skills (41 portable skills)
 
-Skills live under `.claude/skills/` and are auto-discovered by Claude Code.
+Skills live under `.claude/skills/` and are auto-discovered by Claude Code. Every
+skill is **versioned** (`version:` in frontmatter) and ships a per-skill
+`CHANGELOG.md` (v4.82.0 — see [skill-structure.md](framework/.claude/skills/skill-creator/references/skill-structure.md)).
 Bundled skills:
 
 - **Workflow**: `new`, `new2` (v4.16.0 — EXPERIMENTAL workflow-hosted `/new`, Claude-only, for A/B testing context economy), `prd`, `prd-add`, `bug`, `simplify`, `worktree-manager`, `issue-review`, `context-primer`
 - **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`, `lsp-bootstrap` (v3.10.0), `graphify-bootstrap` (v4.21.0 — code knowledge graph), `graph-align` (v4.21.0 — doc↔graph alignment), `toolchain-bootstrap` (v4.41.0 — curated dev toolchain), `e2e-review` (v3.18.0)
-- **Design**: `frontend-design`, `ui-design`, `motion-design`, `gamification-design`, `design-system-init` (v3.11.0 — bulk registry bootstrap/upgrade), `ds-new` (v4.69.0 — single-element guided creation: one component or token, reuse-first → optional scaffold → document + register + govern + verify; the on-the-fly twin of `design-system-init`), `ds-edit` (v4.70.0 — deliberate edit of one existing element: resync / extend-variant / breaking / re-govern; regenerates the spec preserving agentic fields + prose, same canonical template), `ds-render` (v4.76.0 — render primitives in isolation to PNG via Storybook+Playwright), `design-sync` (v4.76.0 — mirror the registry to its Claude Design satellite), `ds-handoff` (v4.79.0 — field-level 1:1 Claude Design handoff brief: grounds every screen's fields in the real data schemas + coverage-gates before emitting; the SSOT for the Claude Design prompt, delegated from `/prd`)
+- **Design**: `frontend-design`, `ui-design`, `ui-implement` (v4.82.0 — implement an approved mockup end-to-end + self-verify fidelity; the mockup→code playbook SSOT, delegated from `/new`), `motion-design`, `gamification-design`, `design-system-init` (v3.11.0 — bulk registry bootstrap/upgrade), `ds-new` (v4.69.0 — single-element guided creation: one component or token, reuse-first → optional scaffold → document + register + govern + verify; the on-the-fly twin of `design-system-init`), `ds-edit` (v4.70.0 — deliberate edit of one existing element: resync / extend-variant / breaking / re-govern; regenerates the spec preserving agentic fields + prose, same canonical template), `ds-render` (v4.76.0 — render primitives in isolation to PNG via Storybook+Playwright), `design-sync` (v4.76.0 — mirror the registry to its Claude Design satellite), `ds-handoff` (v4.79.0 — field-level 1:1 Claude Design handoff brief: grounds every screen's fields in the real data schemas + coverage-gates before emitting; the SSOT for the Claude Design prompt, delegated from `/prd`)
 - **Product**: `seo-audit`, `copywriting`, `api-design-principles`
 - **Knowledge**: `doc-writing-for-rag`, `capture` (LLM wiki overlay)
 - **Internationalization**: `i18n` (v4.52.0 — audit the context registry + context-aware translation into native locale files), `i18n-adopt` (v4.52.0 — one-shot migration that externalizes all hardcoded strings on an existing codebase); both gated on `features.has_i18n`

package/VERSION

@@ -1 +1 @@
-4.80.1
+4.82.0

package/framework/.claude/commands/design-review.md

@@ -1,9 +1,9 @@
 ---
-description: Trigger the design-review subagent with MCP Playwright for the specified route.
-allowed-tools: Bash, Grep, LS, Read, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash, ListMcpResourcesTool, ReadMcpResourceTool, mcp__playwright__browser_navigate, mcp__playwright__browser_click, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_console_messages
+description: Trigger the design-review subagent with the Playwright CLI for the specified route.
+allowed-tools: Bash, Grep, LS, Read, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash
 ---
 
-You are the design-review subagent. Ensure `npm run design-review` is running before continuing so Playwright MCP can expose `localhost:9221` to Claude.
+You are the design-review subagent. Ensure the dev server is running, then capture each route with a **headless Playwright CLI screenshot** (a short script run via Bash, e.g. `npx playwright screenshot` or an inline `.mjs` using `@playwright/test`'s `chromium`) — no Playwright MCP. Read the saved PNG back to reason over it.
 
 ## Invocation Modes (since v3.18.1)
 
@@ -110,7 +110,7 @@ When the user invokes `/design-review`, do the following (in both modes — only
    - Read `${paths.design_system}/tokens-reference.md`.
    - Read `${paths.design_system}/components/<Name>.md` for every primitive expected on the route.
    When the flag is `false`, skip the registry reads. In Mode A flag the gap in the final report and recommend `/design-system-init`. In Mode B add the gap to the `gaps[]` array of the JSON output.
-1. Start with the route or component specified (e.g., `/dashboard`) and open it in the MCP browser. In Mode B, use the `dev_server_port` from the input envelope to construct `http://localhost:<port><route>`.
+1. Start with the route or component specified (e.g., `/dashboard`) and capture it with a headless Playwright CLI screenshot script (run via Bash), then Read the PNG back. In Mode B, use the `dev_server_port` from the input envelope to construct `http://localhost:<port><route>`.
 2. Follow the Quick Visual Check in `agents/design-review.md` and run Phases 0‑7 (interaction, responsiveness, polish, accessibility, robustness, code health, content/console).
 3. Capture at least one full-page screenshot at the viewport from the input (default 1440px) and note console errors. In Mode B save the screenshot at `/tmp/design-review/<route-slug>.png` and cite it in `evidence.screenshot_path`.
 4. **Mode A**: report findings using the Markdown template in `agents/design-review.md` (Blockers/High/Medium/Nitpicks). **Mode B**: assemble the JSON output described above, normalizing severity per the table.

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

@@ -169,7 +169,7 @@ Run everything in BALANCED, plus:
 - If NO: log in findings file: "E2E framework not configured — recommend setting up e2e smoke suite. No e2e tests run."
 
 **UI quality checks:**
-- Use MCP Playwright (if available) to open key flows related to the diff and take screenshots, checking for console errors and visual regressions.
+- Use a headless Playwright CLI screenshot script (when `@playwright/test` is installed) to open key flows related to the diff and take screenshots, checking for console errors and visual regressions — no Playwright MCP.
 - Validate: login/auth flow, critical navigation, any flow directly touched by the diff.
 
 Run the e2e pass in parallel with the `qa-sentinel` FULL-tier gate run (launch both as sub-agents simultaneously). This inline two-agent launch is the DEEP default; escalate to the team-based strategy (Step 4) ONLY when 3+ clearly independent risk tracks exist [DESIGN-CHOICE: below this threshold, TeamCreate overhead exceeds benefit; two inline Task spawns are sufficient]. A DEEP run with fewer than 3 tracks stays on this inline path and does NOT create a team.

package/framework/.claude/skills/api-design-principles/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — api-design-principles
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/api-design-principles/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: api-design-principles
 effort: medium
+version: 1.0.0
 description: Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.
 ---
 

package/framework/.claude/skills/baldart-push/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — baldart-push
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/baldart-push/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: baldart-push
 effort: medium
+version: 1.0.0
 description: "Guidance for contributing local framework improvements upstream to the BALDART repository. Use when the user says /baldart-push, 'contribuisci al framework', 'push del framework', 'manda upstream', 'pusha le modifiche al framework', or wants to share local improvements made to .framework/. The skill walks the user through the contribution flow and hands off to `npx baldart push` (which must run in the user's terminal because the CLI is interactive). Never pushes baldart.config.yml, .baldart/overlays/, or .claude/hooks/ customizations — only generic framework payload."
 contamination_scan: skip
 ---

package/framework/.claude/skills/baldart-update/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — baldart-update
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/baldart-update/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: baldart-update
 effort: medium
+version: 1.0.0
 description: "Guidance for updating BALDART framework to the latest version in a consumer repo. Use when the user says /baldart-update, 'aggiorna baldart', 'aggiorna framework', 'update del framework', 'pull baldart latest', or wants to bring the framework up-to-date. The update is SEAMLESS (v4.8.0+): a single `npx baldart update --yes` auto-stashes non-framework work, auto-resolves divergence (overlay-covered edits → clean reinstall that re-applies overlays; uncovered edits → auto-captured into overlays and verified), reconciles + commits BALDART-managed artifacts, and re-applies the stash — zero prompts in the happy path. The skill only narrates and reports; it never re-implements the CLI or replicates its prompts. Two modes, auto-detected: INTERACTIVE (a human is present) and AUTONOMOUS (unattended — CI / scheduled routine, signalled by BALDART_AUTONOMOUS / CI / GITHUB_ACTIONS env, uses --json). The CLI stops ONCE only when an edit cannot be captured+verified (a section deletion, a frontmatter/preamble change, a src/ change) — the skill surfaces that single pause. Always asserts post-flight that .framework/VERSION actually changed. For non-update drift, defers to `npx baldart` (smart doctor)."
 contamination_scan: skip
 ---

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

@@ -0,0 +1,7 @@
+# Changelog — bug
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,13 +1,14 @@
 ---
 name: bug
 effort: medium
+version: 1.0.0
 description: >
   Structured bug investigation and resolution workflow (framework-agnostic; project-specific entry points are loaded from `.baldart/overlays/bug.md`).
   Use when: the user says /bug, 'debug', 'c e un bug', 'non funziona', 'errore', 'broken',
   'investigate', or reports unexpected behavior. Accepts optional bug description as argument.
   Enforces a disciplined 5-phase debugging protocol that prevents blind guessing:
   (1) Reproduce & observe, (2) Enhanced logging if stuck, (3) Data-driven analysis,
-  (4) Hypothesis & minimal fix, (5) Verify. Leverages Playwright MCP for browser capture,
+  (4) Hypothesis & minimal fix, (5) Verify. Leverages the Playwright CLI (headless capture scripts via webapp-testing) for browser capture,
   codebase-architect for code path tracing, `rg` over docs for known patterns, git bisect for regressions.
 ---
 
@@ -35,8 +36,7 @@ precedence caveats: `framework/agents/effort-protocol.md`.
 
 See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for the BALDART MCP integration contract and the rationale behind this section.
 
-**Required** (skill cannot complete its task without these MCPs for the relevant bug class):
-- `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`.
+**None required for browser capture.** UI/Client reproduction uses the **Playwright CLI**, NOT an MCP: write a short headless capture script (via the [webapp-testing](../webapp-testing/SKILL.md) toolkit) that navigates, screenshots, and dumps console + network to disk, then read the artifacts back. Nothing is driven interactively, so **no Playwright MCP is ever loaded into the agent context** (deliberate token-economy choice — see `framework/docs/MCP-INTEGRATION.md`). The `addInitScript` instrumentation in Phase 2 replaces the old live `browser_evaluate` injection with zero loss of capability.
 
 **Optional** (the skill benefits if present, has a documented fallback):
 - `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.
@@ -54,7 +54,7 @@ See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for th
 
 1. Parse the bug description from args (or ask user if missing)
 2. Classify the bug domain:
-   - **UI/Client** → Playwright MCP is primary tool
+   - **UI/Client** → Playwright CLI capture script (via webapp-testing) is primary tool
    - **API/Server** → dev server logs + route handler analysis
    - **Data/Datastore** → the project's datastore inspection tooling per `stack.database` (e.g. the Firebase MCP for `firestore`, a SQL client for `postgres`/`supabase`, the Mongo shell for `mongodb`) + transaction tracing
    - **Auth** → the project's auth middleware/guard + auth error codes (per `stack.auth_provider`)
@@ -82,13 +82,16 @@ See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for th
 
 Goal: get a reliable reproduction that you can re-run after fixing.
 
-**For UI bugs:**
-1. Navigate with Playwright MCP: `browser_navigate` to the affected page
-2. Capture baseline: `browser_take_screenshot`
-3. Capture console state: `browser_console_messages`
-4. Capture network: `browser_network_requests`
-5. Reproduce the bug step-by-step, capturing after each action
-6. Record the exact sequence that triggers the bug
+**For UI bugs (Playwright CLI capture — no MCP):**
+Write a short **headless capture script** to scratch (e.g. `scratch/bug-repro.mjs`, or a Python helper via the [webapp-testing](../webapp-testing/SKILL.md) toolkit) and run it with Bash — never drive the browser interactively. The script:
+1. Navigates to the affected page (build the URL from the project baseURL / dev-server port)
+2. Captures a baseline screenshot to disk: `await page.screenshot({ path: 'scratch/repro.png', fullPage: true })`
+3. Dumps console to a file: `page.on('console', m => fs.appendFileSync('scratch/console.log', m.text()+'\n'))`
+4. Dumps network to a file: `page.on('response', r => fs.appendFileSync('scratch/network.log', `${r.status()} ${r.url()}\n`))` (or record a HAR via `browser.newContext({ recordHar: { path: 'scratch/repro.har' } })`)
+5. Performs the repro steps (`click`/`fill`), screenshotting after each action
+6. Then **Read the artifact files back** and record the exact sequence that triggers the bug
+
+Delete the scratch script + artifacts in Phase 5.
 
 **For API bugs:**
 1. Identify the route handler file from the URL pattern
@@ -141,10 +144,12 @@ await firestore.runTransaction(async (tx) => {
 console.log(`[DEBUG:tx] done in ${attempt} attempts`); // DEBUG:
 ```
 
-### Client-side logging (via Playwright MCP — zero code changes)
+### Client-side logging (via the Playwright CLI capture script — zero app code changes)
 
-Use `browser_evaluate` to inject runtime instrumentation:
+Inject runtime instrumentation with `page.addInitScript(() => { ... })` (runs before the page's own scripts) inside the capture script — same effect as a live `evaluate`, but headless and reproducible. The forwarded `console.*` is collected by the script's `page.on('console', …)` handler and written to disk; read the file back after the run:
 ```javascript
+// inside the capture script, before page.goto():
+await page.addInitScript(() => {
 // Intercept all fetch calls
 const origFetch = window.fetch;
 window.fetch = async (...args) => {
@@ -163,8 +168,9 @@ window.fetch = async (...args) => {
     throw e;
   }
 };
+}); // end addInitScript
 ```
-Then capture everything: `browser_console_messages` after reproducing.
+Then run the script and read the console artifact file back after reproducing.
 
 ### Cache/data-fetch debug mode
 
@@ -179,8 +185,8 @@ If the project exposes an env-summary helper (listed in `.baldart/overlays/bug.m
 1. Reproduce the bug AGAIN with enhanced logging active
 2. Collect ALL output:
    - Server terminal (grep for `[DEBUG:`)
-   - `browser_console_messages` from Playwright
-   - `browser_network_requests` from Playwright
+   - the console artifact file written by the capture script
+   - the network artifact file (or HAR) written by the capture script
    - Screenshots before/after
 3. Analyze:
    - **Timeline**: what happened in what order?
@@ -216,7 +222,7 @@ If the project exposes an env-summary helper (listed in `.baldart/overlays/bug.m
    ```
    Remove every line found. Run grep again to confirm zero results.
 5. Revert any temporary cache/data-fetch debug switches enabled in Phase 2
-6. Final Playwright screenshot to confirm visually
+6. Re-run the Playwright CLI capture script for a final screenshot to confirm visually, then delete the scratch script + artifacts
 
 ## TOOLS QUICK REFERENCE
 
@@ -224,7 +230,7 @@ If the project exposes an env-summary helper (listed in `.baldart/overlays/bug.m
 |------|------|---------|
 | `codebase-architect` agent | Phase 0 | Map affected code paths |
 | `rg` over docs / error-code module | Phase 0 | Search known patterns/errors |
-| `mcp__playwright__browser_*` | Phase 1-5 | Navigate, screenshot, console, network |
+| Playwright CLI capture script (webapp-testing) | Phase 1-5 | Navigate, screenshot, console, network — headless, artifacts to disk (no MCP) |
 | Project DB MCP (if available) | Phase 1 | Inspect storage state (e.g. firestore/postgres tools) |
 | `git log/blame/bisect` | Phase 0, 3 | Find regression commits |
 | Project-specific entry points | various | Listed in `.baldart/overlays/bug.md` — error-code module, env-summary helper, cache debug switch |

package/framework/.claude/skills/bug/references/logging-patterns.md

@@ -115,11 +115,16 @@ const analysis = await query.explain({ analyze: true });
 `debug()` in Firestore rules works ONLY in the emulator, no-op in production.
 Use `@firebase/rules-unit-testing` (already in devDeps) for rule testing.
 
-## Playwright MCP Debug Patterns
+## Playwright CLI Debug Patterns
 
-### Inject fetch interceptor (zero code changes)
+> Headless capture scripts only — no Playwright MCP. Inject the instrumentation
+> with `page.addInitScript(() => { ... })` (runs before the page's own scripts),
+> collect the forwarded `console.*` with `page.on('console', …)`, and write it to
+> disk; read the artifact back after the run.
+
+### Inject fetch interceptor (zero app code changes)
 ```javascript
-// browser_evaluate:
+// inside the capture script: await page.addInitScript(() => {
 const origFetch = window.fetch;
 window.fetch = async (...args) => {
   const url = typeof args[0] === 'string' ? args[0] : args[0]?.url;
@@ -143,7 +148,7 @@ window.fetch = async (...args) => {
 
 ### Inject SWR mutation tracker
 ```javascript
-// browser_evaluate:
+// inside the capture script: await page.addInitScript(() => {
 const origMutate = window.__SWR_MUTATE__;
 if (origMutate) {
   window.__SWR_MUTATE__ = (...args) => {
@@ -161,7 +166,7 @@ const context = await browser.newContext({ recordHar: { path: 'debug.har', mode:
 
 ## CDP (Chrome DevTools Protocol) via Playwright
 
-For deep debugging beyond MCP tools:
+For deep debugging beyond the basic capture script:
 ```typescript
 const session = await context.newCDPSession(page);
 await session.send('Runtime.enable');

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

@@ -0,0 +1,7 @@
+# Changelog — capture
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -2,7 +2,7 @@
 name: capture
 effort: medium
 description: Distilla una sintesi cross-document della conversazione recente in una synthesis page riusabile del wiki overlay (path da `paths.wiki_dir`/syntheses/ in `baldart.config.yml`). Usare quando l'utente invoca `/capture`, dice "capture synthesis", "salva sintesi", "distilla conversazione", "save this as wiki", "questa conversazione in wiki", o quando chiede di trasformare un ragionamento cross-document appena fatto in una pagina stabile. Due modalità — manual (sempre funzionante) e proactive (conditional sui candidati in `.claude/capture-queue/`). Implementa il loop query→wiki file-back di Karpathy.
-version: 0.1.0
+version: 1.0.0
 ---
 
 # /capture — Synthesis Capture Skill

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

@@ -0,0 +1,7 @@
+# Changelog — context-primer
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,6 +1,7 @@
 ---
 name: cont
 effort: medium
+version: 1.0.0
 description: >
   Load codebase context silently before starting work, optimized for LLM
   comprehension using research-backed structured formatting.

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

@@ -0,0 +1,7 @@
+# Changelog — copywriting
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -0,0 +1,7 @@
+# Changelog — design-sync
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,6 +1,7 @@
 ---
 name: design-sync
 effort: high
+version: 1.0.0
 description: >
   Keep the in-repo design system (the SSOT) and its Claude Design satellite
   "mirror" project in sync — the code→design half of the closed loop. Three modes:

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

@@ -0,0 +1,7 @@
+# Changelog — design-system-init
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,6 +1,7 @@
 ---
 name: design-system-init
 effort: medium
+version: 1.0.0
 description: >
   Bootstrap OR upgrade a component registry / design system. GREENFIELD: scaffolds
   ${paths.design_system}/INDEX.md (a thin generated router), a DTCG

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

@@ -0,0 +1,7 @@
+# Changelog — doc-writing-for-rag
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,6 +1,7 @@
 ---
 name: doc-writing-for-rag
 effort: medium
+version: 1.0.0
 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'."
 ---
 

package/framework/.claude/skills/ds-edit/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — ds-edit
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,6 +1,7 @@
 ---
 name: ds-edit
 effort: medium
+version: 1.0.0
 description: >
   Update ONE existing canonical design-system element correctly — the deliberate
   edit twin of /ds-new. Classifies the change (resync the spec to changed source /

package/framework/.claude/skills/ds-handoff/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — ds-handoff
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,6 +1,7 @@
 ---
 name: ds-handoff
 effort: medium
+version: 1.0.0
 description: >
   Produce a FIELD-LEVEL, 1:1, interaction-complete handoff brief for Claude Design
   — every screen's real fields (label, control type, required, validation, default,

package/framework/.claude/skills/ds-new/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — ds-new
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,6 +1,7 @@
 ---
 name: ds-new
 effort: medium
+version: 1.0.0
 description: >
   Create ONE canonical design-system element — a component OR a token — end to
   end with the full discipline: reuse-first research, (optional) scaffold, then

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

@@ -0,0 +1,7 @@
+# Changelog — ds-render
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,6 +1,7 @@
 ---
 name: ds-render
 effort: medium
+version: 1.0.0
 description: >
   Render the design-system primitives in ISOLATION (one component × variant at a
   time) and capture a PNG per entry — the render harness BALDART never had (today

package/framework/.claude/skills/e2e-review/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — e2e-review
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/e2e-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: e2e-review
 effort: medium
+version: 1.0.0
 description: >
   Deterministic, BLOCKING end-to-end review run after a feature is implemented.
   Combines functional E2E (Playwright spec written by `coder`, executed via

package/framework/.claude/skills/find-skills/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — find-skills
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/find-skills/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: find-skills
 effort: medium
+version: 1.0.0
 description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
 ---
 

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

@@ -0,0 +1,7 @@
+# Changelog — frontend-design
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,6 +1,7 @@
 ---
 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.
 license: Complete terms in LICENSE.txt
 ---

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

@@ -0,0 +1,7 @@
+# Changelog — gamification-design
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/graph-align/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — graph-align
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/graph-align/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: graph-align
 effort: medium
+version: 1.0.0
 description: >
   On-demand documentation alignment via the Graphify code knowledge graph.
   Rebuilds the graph offline (graphify update .), then cross-checks graph

package/framework/.claude/skills/graphify-bootstrap/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — graphify-bootstrap
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.