@hegemonart/get-design-done 1.53.0 → 1.55.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.53.0"
+    "version": "1.55.0"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.53.0",
+      "version": "1.55.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.53.0",
+  "version": "1.55.0",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 59 specialized agents, 88 skills, 41 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Slack, Linear, Jira, Notion, and more), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,94 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.55.0] - 2026-06-03
+
+### Phase 55 - GDD Dashboard (Multi-Harness Control Plane + Graph Visualization + Session Surface)
+
+GDD ships to 14 runtimes and users run multi-harness sessions in parallel; a control plane is the natural way to surface
+that. Phase 55 ships a READ-ONLY dashboard: a terminal TUI (`bin/gdd-dashboard`) and an opt-in browser graph view
+(`gdd dashboard --web`) that visualizes the Phase 52 DesignContext graph. **Built fully dep-free** (maintainer Rule-4
+decision): no Ink, no React / Vite / React Flow. The ROADMAP had named those stacks (~100 packages / ~84 MB + a CI build
+gate); a footprint study plus the read-only / single-machine / opt-in scale made a hand-rolled ANSI TUI + a
+self-contained-HTML graph (extending the Phase 35.5 `build-html.cjs` precedent) the better fit, and it keeps the
+zero-new-dependency streak intact. The web layer is kept swappable, so a React Flow migration later needs no data rewrite.
+Planned and executed via the GSD pipeline (3 + 3 parallel executors).
+
+### Breaking changes
+
+- **New `bin/gdd-dashboard` + `gdd dashboard [--web]`.** A new bin (the TUI) and a new SDK CLI subcommand. Read-only by
+  design: the dashboard never mutates state (the action surface is "open this file / copy this command / run the
+  slash-skill"). The `--web` server is an ephemeral LOCAL loopback (127.0.0.1, OS-assigned port) serving a single
+  self-contained HTML file to your own browser, then exits.
+- **`gsd-health` gains a 10th check** (`dashboard_reachable`); the health check count moves 9 -> 10.
+
+### Added
+
+- **Data plane** `sdk/dashboard/data/` - `source.cjs` (`loadDashboardModel` reads state / events / graph / health via the
+  shared libs in-process, with a `.design/*` file-scrape fallback; never throws), `cost-aggregator.cjs` (per-runtime +
+  cumulative + per-cycle), `discovery.cjs` (14-runtime detection, worktree enumeration via `git worktree list`,
+  best-effort session manifests).
+- **TUI** `bin/gdd-dashboard` + `sdk/dashboard/tui/` - a hand-rolled ANSI render core (`ansi.cjs`: box/column layout,
+  width-aware truncation incl. CJK, line-diff repaint) + 5 panes (Sessions / Cycle / Cost / Findings /
+  DesignContext-tree), keyboard navigation, alt-screen, event-tail live refresh. Plain `.cjs` (no bundle, no flags).
+- **Web graph** `scripts/lib/dashboard/graph-html.cjs` (`buildGraphHtml`) - one self-contained HTML doc (inline SVG +
+  vanilla JS): layered Atomic / Molecular / Organism / Template layout with barycenter crossing-reduction, viewBox
+  pan/zoom, click-to-inspect, type/tag filters, find-consumers highlight, unreachable outline, PNG export, minimap.
+  Deterministic (hermetic byte-equal test). Launched by `gdd dashboard --web` (`node:http` loopback + browser-open;
+  headless prints the URL; `--once` writes `.design/dashboard.html`).
+- **Risk surfacing** `sdk/dashboard/data/risk-surface.cjs` - reads `risk_score`/`confidence` when present (Phase 56),
+  color-routes Allow/Review/RequireConfirmation/Block; a blank placeholder pre-56.
+
+### Notes
+
+- 6-manifest lockstep at **v1.55.0** + `OFF_CADENCE_VERSIONS.add('1.55.0')` + 37 `manifests-version.txt` baselines.
+  No new skill (the dashboard is a bin + CLI subcommand) -> skill-list / build:skills / skills.json unchanged. No new
+  agent. The dashboard's local `node:http` server is allowlisted in `scripts/security/outbound-allowlist.json` (an
+  inbound loopback read-only server, not outbound egress). Tarball golden 969 -> 979. **No new runtime dependency.**
+
+---
+
+## [1.54.0] - 2026-06-03
+
+### Phase 54 - Composable Reference Addendums (Per-DS + Per-Framework + Per-Motion-Lib)
+
+One general mapper prompt could not be stack-aware: it missed Tailwind's `@theme` tokens, shadcn's `cn()` convention,
+vanilla-extract's `style({})` shape. Phase 54 adds 18 composable prompt addendums (one per design system, framework, and
+motion library) that the explore mappers compose into their prompt at spawn time based on the detected stack. Adapted
+from Understand-Anything's per-language/per-framework addendum pattern. Maintainer-authored and vendor-cross-checked;
+no LLM-generated content. Planned and executed via the GSD pipeline (5 parallel executors + 1 integration executor).
+
+### Breaking changes
+
+- **Mappers are now stack-aware.** `scripts/lib/detect/stack.cjs` detects `{ds, framework, motion_libs[]}` from
+  package.json deps + config files + import signatures; `scripts/lib/mapper-spawn.cjs` composes the matching addendums
+  (capped at 3: one DS, one framework, one motion) into each mapper's prompt before dispatch (additive and
+  backward-compatible: no detected stack or no addendum leaves the base prompt unchanged).
+- **Registry gains a `stack-addendum` type.** `reference/registry.schema.json` adds `"stack-addendum"` to the entry
+  type enum and an optional `composes_into` field; the 18 addendums register against it with their target mappers.
+
+### Added
+
+- **Design-system addendums** (`reference/systems/`): tailwind, shadcn, radix-themes, mui, chakra, vanilla-extract,
+  styled-components, css-modules. **Framework addendums** (`reference/frameworks/`): nextjs, remix, vite-react, astro,
+  sveltekit, storybook. **Motion-lib addendums** (`reference/motion/`): framer-motion, gsap, motion-one, react-spring.
+  Each is at most 50 lines with four sections (Conventions, File patterns, Gotchas, and an Example output fragment in
+  the Phase 52 DesignContext schema).
+- **`/gdd:new-addendum <kind> <name>`** skill + `scripts/lib/new-addendum.cjs` scaffolder (mirrors `/gdd:new-skill`;
+  validates the kind and slug, defaults `composes_into` by kind, writes the 4-section skeleton).
+- **Fallback + coverage**: an unmatched stack falls back to the base prompt and flags the gap; `gsd-health` reports a
+  "N/M detected stacks have addendums" coverage row.
+
+### Notes
+
+- 6-manifest lockstep at **v1.54.0** + `OFF_CADENCE_VERSIONS.add('1.54.0')` + 37 `manifests-version.txt` baselines.
+  Re-locked: skill-list (91 -> 92, +new-addendum) + the phase-28.5 distribution (new-addendum at 81 lines, clean; warn
+  count unchanged at 10) + skill-graph + the registry-diff baseline (+18 stack-addendum entries) + resilience-primitives
+  (+mapper-spawn.cjs +new-addendum.cjs) + the phase-42 compile count (115 -> 116) + the gsd-health check count (8 -> 9).
+  Tarball golden 944 -> 969 (+25). **No new runtime dependency.**
+
+---
+
 ## [1.53.0] - 2026-06-03
 
 ### Phase 53 - Semantic Mapper Engine (Louvain Batching + neighborMap + Fingerprint Incremental)

package/README.md

@@ -267,6 +267,10 @@ All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `ag
 
 **Semantic mapper engine (v1.53.0).** Mappers get smart about scale and re-runs on top of the Phase 52 graph. Louvain community batching (`scripts/lib/mappers/compute-batches.mjs`, dep-free, deterministic) groups files that import each other so each parallel mapper sees a coherent slice; a neighborMap sidecar (`neighbor-map.mjs`) hands each batch its 1-hop external symbols so cross-batch edges emit without rereading other batches. SHA-256 fingerprinting (`sdk/fingerprint/`) classifies each re-run as SKIP / PARTIAL / ARCHITECTURE / FULL, so `/gdd:discover` (now incremental by default, `--full` to override) only re-discovers what actually changed. A graph-context-reviewer agent runs nine checks on the assembled graph (hard-reject on schema or referential breakage, soft-warn otherwise). Node builtins only, no `graphology`, no embeddings. **No new runtime dependency.**
 
+**Composable reference addendums (v1.54.0).** One general mapper prompt cannot know Tailwind's `@theme` tokens from shadcn's `cn()` from vanilla-extract's `style({})`. Phase 54 adds 18 stack-specific addendums (8 design systems, 6 frameworks, 4 motion libraries) under `reference/{systems,frameworks,motion}/`, each at most 50 lines with Conventions / File patterns / Gotchas / Example-output sections. `scripts/lib/detect/stack.cjs` detects the project stack from dependencies plus config files and import signatures; `scripts/lib/mapper-spawn.cjs` composes the matching addendums (capped at one DS + one framework + one motion) into each explore mapper's prompt at spawn time, additively, so a project on an unknown stack just keeps the base prompt and `gsd-health` reports the coverage gap. A `/gdd:new-addendum` scaffolder adds more. Maintainer-authored, vendor-cross-checked, no LLM-generated content. **No new runtime dependency.**
+
+**GDD dashboard (v1.55.0).** A read-only multi-harness control plane. `gdd-dashboard` opens a terminal TUI with five panes (sessions per runtime, current cycle, cost telemetry, findings, a DesignContext tree); `gdd dashboard --web` opens an interactive browser view of the Phase 52 graph (layered Atomic/Molecular/Organism/Template layout, pan/zoom, click-to-inspect, type/tag filters, find-consumers highlight, PNG export, minimap). It is **built fully dep-free** (a maintainer decision over the roadmap's Ink + React Flow + Vite stack, which would have added ~100 packages): the TUI is a hand-rolled ANSI renderer, the graph view is a self-contained HTML file (inline SVG + vanilla JS, extending the export builder), and the data plane reads GDD state through the existing shared libraries in-process. Read-only by design (the action surface is open-file / copy-command / run-skill); the `--web` server is a local loopback that serves to your own browser and exits. **No new runtime dependency.**
+
 Verify with:
 
 ```

package/SKILL.md

@@ -2,7 +2,7 @@
 name: get-design-done
 short_name: gdd
 description: "Master design pipeline for Claude Code. 5-stage workflow: Brief → Explore → Plan → Design → Verify. Run 'brief' first in any new project to capture the design problem, then 'explore' to inventory the codebase and interview for context. Invoke without arguments for status and auto-routing."
-argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|live|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|new-skill|instinct|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
+argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|live|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|new-skill|new-addendum|instinct|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
 user-invocable: true
 ---
 
@@ -94,6 +94,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `unpin <skill>` | `get-design-done:gdd-unpin` | Phase 46 - remove pinned aliases for a skill (only files carrying the gdd-pinned-skill marker) |
 | `list-pins` | `get-design-done:gdd-list-pins` | Phase 46 - show pinned aliases per harness with their source skill and last-pinned timestamp |
 | `new-skill <name>` | `get-design-done:gdd-new-skill` | Phase 50 - interactive scaffolder for a new Phase 28.5 + v3-compliant skill (multi-paragraph description, lifecycle stage, optional composes_with); writes source/skills/<name>/SKILL.md |
+| `new-addendum <kind> <name>` | `get-design-done:gdd-new-addendum` | Phase 54 - scaffold a composable reference addendum (kind = system\|framework\|motion); validates the slug, defaults composes_into by kind, writes a 4-section skeleton at reference/{systems\|frameworks\|motion}/<name>.md that an explore mapper composes at spawn time |
 | `instinct [list\|query <kw>\|promote <id>]` | `get-design-done:gdd-instinct` | Phase 51 - inspect and manage atomic instinct learning units (project + global stores); list, search by keyword, or promote a vetted project instinct to global once it clears the cross-project gate |
 | `quality-gate` | `get-design-done:quality-gate` | Phase 25 - parallel lint/type/test/visual command runner; classifies failures via quality-gate-runner agent |
 | `turn-closeout` | `get-design-done:turn-closeout` | Phase 25 - Stop-hook mirror skill; finalizes per-turn STATE blocks and emits closeout events |

package/agents/component-taxonomy-mapper.md

@@ -18,6 +18,9 @@ writes:
 
 # component-taxonomy-mapper
 
+<!-- {{addendum_block}} -->
+Stack-specific guidance (a `## Stack-specific guidance` block for the detected DS / framework / motion library) is appended here at spawn time by `scripts/lib/mapper-spawn.cjs`. When present, follow it as an extension of the rules below.
+
 ## Role
 
 You inventory the component taxonomy of the codebase. Zero session memory. You do not modify source code or spawn other agents.

package/agents/motion-mapper.md

@@ -18,6 +18,7 @@ writes:
 
 # motion-mapper
 
+<!-- {{addendum_block}}: a `## Stack-specific guidance` block for the detected DS / framework / motion library is appended here at spawn time by scripts/lib/mapper-spawn.cjs. When present, follow it as an extension of the rules below. -->
 ## Role
 
 You inventory motion and animation patterns. Zero session memory. You do not modify source code and do not spawn other agents.

package/agents/token-mapper.md

@@ -18,6 +18,9 @@ writes:
 
 # token-mapper
 
+<!-- {{addendum_block}} -->
+Stack-specific guidance (a `## Stack-specific guidance` block for the detected DS / framework / motion library) is appended here at spawn time by `scripts/lib/mapper-spawn.cjs`. When present, follow it as an extension of the rules below.
+
 ## Role
 
 You map design tokens from the codebase. Zero session memory - everything you need is in the prompt and `<required_reading>`. You do not modify source code or spawn other agents.

package/bin/gdd-dashboard

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// bin/gdd-dashboard — Phase 55 (GDD Dashboard, DEP-FREE), TUI-01 (executor D).
+//
+// CJS trampoline that launches the terminal dashboard
+// (sdk/dashboard/tui/index.cjs) under `node`, forwarding argv + the child's
+// exit code / signal. Windows-safe.
+//
+// SIMPLER than bin/gdd-sdk (R8): the TUI is plain `.cjs` (Node builtins only),
+// so there is NO esbuild bundle and NO `--experimental-strip-types` flag — we
+// just `node <entry>`. The only reason this is a spawning trampoline (rather
+// than a direct require) is the same one gdd-sdk documents: npm's
+// auto-generated Windows `.cmd` shim invokes `node bin/gdd-dashboard` and we
+// want a single, platform-uniform launch path that cleanly forwards the exit
+// code and re-raises a terminating signal (so Ctrl-C tears down correctly).
+//
+// Sibling resolution uses a PACKAGE-ROOT WALK-UP (the Phase 53/54 lesson, D7),
+// never a fixed `__dirname`-relative cross-tree jump: we climb from this file's
+// directory to the GDD package root (package.json with name
+// "get-design-done") and resolve `sdk/dashboard/tui/index.cjs` from there. This
+// keeps the bin correct even if it is copied/relocated within the tree.
+
+'use strict';
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Walk up from `startDir` to the GDD package root: the first ancestor whose
+ * package.json declares `name === "get-design-done"`. Falls back to the first
+ * ancestor that has any package.json, then to `startDir`. Bounded climb.
+ * @param {string} startDir
+ * @returns {string} absolute package-root directory
+ */
+function findPackageRoot(startDir) {
+  let dir = path.resolve(startDir);
+  let firstWithPkg = null;
+  for (let i = 0; i < 12; i++) {
+    const pkgPath = path.join(dir, 'package.json');
+    let pkg = null;
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    } catch {
+      pkg = null;
+    }
+    if (pkg) {
+      if (firstWithPkg === null) firstWithPkg = dir;
+      if (pkg.name === 'get-design-done') return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return firstWithPkg || path.resolve(startDir);
+}
+
+const root = findPackageRoot(__dirname);
+const entry = path.join(root, 'sdk', 'dashboard', 'tui', 'index.cjs');
+
+if (!fs.existsSync(entry)) {
+  // eslint-disable-next-line no-console
+  console.error(`gdd-dashboard: TUI entry not found at ${entry}`);
+  process.exit(3);
+}
+
+const child = spawn(process.execPath, [entry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  shell: false,
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise the signal so the parent shell sees the same termination mode
+    // (e.g. Ctrl+C propagates as SIGINT). Falls back to a non-zero exit if the
+    // self-signal cannot be delivered.
+    try {
+      process.kill(process.pid, signal);
+    } catch {
+      process.exit(1);
+    }
+    return;
+  }
+  process.exit(typeof code === 'number' ? code : 0);
+});
+
+child.on('error', (err) => {
+  // Failure to spawn node itself — extremely rare; surface to stderr.
+  // eslint-disable-next-line no-console
+  console.error('gdd-dashboard: failed to launch the TUI:', err.message);
+  process.exit(3);
+});

package/dist/claude-code/.claude/skills/new-addendum/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: gdd-new-addendum
+description: "Scaffolds a new Phase-54 composable reference addendum for a design-system, framework, or motion library: validates the kind and the slug, defaults composes_into by kind, and writes a 4-section skeleton at reference/{systems|frameworks|motion}/<name>.md from the pure generator. Use when adding stack-specific guidance that an explore mapper should compose at spawn time and you want the frontmatter, the composes_into wiring, and the mandatory sections correct from the first commit. Activates for requests involving authoring a reference addendum, adding stack-specific mapper guidance, scaffolding a systems or frameworks or motion doc, or registering a new design-system."
+argument-hint: "<kind> <name>"
+tools: Read, Write, Bash, AskUserQuestion
+user-invocable: true
+---
+
+# /gdd:new-addendum
+
+**Role:** Scaffold a contract-compliant stack addendum. Validate the kind and the name, then write `reference/{systems|frameworks|motion}/<name>.md` from the pure generator at `scripts/lib/new-addendum.cjs`. This skill writes ONE reference file. It does NOT touch `reference/registry.json` and does NOT run any build; it prints the exact follow-up steps instead.
+
+An addendum is a registry entry, not a skill. Read `reference/registry.json` for the `type:"stack-addendum"` entry shape and `scripts/lib/mapper-spawn.cjs` for how `composes_into` selects an addendum at spawn time. Read one shipped example first, for instance `reference/systems/tailwind.md`, to match the house style.
+
+## Step 1 - Gather the fields
+
+1. **kind**: the first token of `$ARGUMENTS` if present, else ask. Must be one of `system`, `framework`, or `motion`. This picks the target subdir and the default `composes_into`.
+2. **name**: the second token of `$ARGUMENTS` if present, else ask. Must match `^[a-z0-9][a-z0-9-._]*$`. The basename is also the matcher key in `mapper-spawn.cjs`, so it must equal the value `detectStack` reports for this stack (for example `tailwind`, `nextjs`, `framer-motion`). Reject a `reference/{dir}/<name>.md` collision.
+3. **composes_into** (optional): accept the kind default, or override with a comma list of mapper names. Defaults: `system` to `token-mapper, component-taxonomy-mapper`; `framework` to `component-taxonomy-mapper, visual-hierarchy-mapper`; `motion` to `motion-mapper`.
+
+Resolve the target path and check for a collision:
+
+```bash
+node -e "
+const a = require('./scripts/lib/new-addendum.cjs');
+console.log(a.targetPathFor(process.argv[1], process.argv[2]));
+" "<kind>" "<name>"
+```
+
+If that path already exists, stop and tell the user to edit the existing file instead.
+
+## Step 2 - Write the file
+
+Build the record and render the skeleton with the pure generator, then write it with the Write tool (not shell redirection):
+
+```bash
+node -e "
+const a = require('./scripts/lib/new-addendum.cjs');
+const rec = a.buildAddendumRecord({
+  kind: process.env.AD_KIND,
+  name: process.env.AD_NAME,
+  composesInto: process.env.AD_COMPOSES || undefined,
+});
+process.stdout.write(a.renderAddendumMd(rec));
+"
+```
+
+`buildAddendumRecord` throws on an invalid kind, an invalid name, or a malformed composes_into list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to the path from Step 1 via the Write tool.
+
+## Step 3 - Fill the four sections
+
+The skeleton ships four mandatory sections with TODO placeholders: Conventions, File patterns, Gotchas, Example output. Replace every TODO with terse vendor-checked bullets (keep the file at or under about 50 lines). Rules:
+
+- Lead with the real vendor docs URL in the attribution comment.
+- The Example output block uses ONLY the Phase 52 DesignContext schema (node types token / component / variant / state / motion-fragment / screen / layer; edge types uses-token / composes / extends / transitions-to / mirrors).
+- Tags must come from `reference/design-context-tag-vocab.md`; drop any tag not in that vocabulary.
+- For a motion addendum, reuse the `reference/motion-transition-taxonomy.md` duration classes (instant / quick / standard / slow / narrative) and call out the seconds-vs-ms-vs-no-duration unit trap.
+- No em dashes anywhere (the `lint:prose` gate scans `reference/`).
+
+## Step 4 - Tell the user the follow-up
+
+The skill stops here by contract. Print the next steps for the maintainer to run:
+
+```
+1. Add a registry entry for "<name>" to reference/registry.json
+   (name addendum-<kind>-<name>, path, type "stack-addendum", phase 54, kind, composes_into, description).
+2. node -e "require('./scripts/lib/reference-registry.cjs').validateRegistry({cwd:process.cwd()})"
+   must report ok:true (the round-trip scan picks up the new subdir file).
+3. npm test (the reference-registry + phase-54 suites must stay green).
+```
+
+The registry round-trip test stays red until the registry entry exists; that is expected and is the maintainer's step.
+
+## Do Not
+
+- Do not edit `reference/registry.json`, `package.json`, or `scripts/lib/manifest/skills.json`.
+- Do not run a build or the registry generator for the user; print the steps.
+- Do not write the file with shell redirection; use the Write tool so the content is exact.
+- Do not invent vendor facts; the addendum content must be vendor-checked.
+
+## NEW-ADDENDUM COMPLETE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.53.0",
+  "version": "1.55.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -34,6 +34,7 @@
     "NOTICE"
   ],
   "bin": {
+    "gdd-dashboard": "./bin/gdd-dashboard",
     "gdd-detect": "./bin/gdd-detect",
     "gdd-events": "./scripts/cli/gdd-events.mjs",
     "gdd-graph": "./bin/gdd-graph",

package/reference/frameworks/astro.md

@@ -0,0 +1,43 @@
+---
+name: astro
+kind: framework
+composes_into: [component-taxonomy-mapper, visual-hierarchy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://docs.astro.build. -->
+
+# Astro
+
+## Conventions
+
+- An `.astro` file is a script fence (the `---` code fence runs at build or on the server) plus an HTML template; props arrive via `Astro.props`.
+- File routing lives in `src/pages/` (`.astro` and `.md`). Framework components are static by default; `client:load`, `client:idle`, `client:visible`, and `client:only` directives mark hydration, which is the interactivity signal.
+- `<style>` is scoped by default; `is:global` or `:global()` escapes the scope. Content collections are typed Markdown or MDX in `src/content/`, configured by `content.config.ts` with Zod.
+
+## File patterns
+
+- `src/pages/**/*.astro`, `src/layouts/*.astro`, `src/components/*.astro`, `content.config.ts`, `astro.config.mjs`.
+- Identify via: astro in deps plus a `src/pages/` directory.
+
+## Gotchas
+
+- Most `.astro` files ship zero js; only `client:*`-directed islands are interactive, so motion attaches only to hydrated islands.
+- Scoped `<style>` rewrites class names locally; treat those names as component-local, not global tokens.
+- `src/pages/*.astro` files are screens; layouts wrap them via a `<slot/>` (emit a composes edge).
+- Global tokens enter via an `is:global` block or a stylesheet imported in a layout.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "scr.index", "type": "screen", "name": "/", "summary": "Home page from src/pages/index.astro.", "complexity": "simple", "tags": ["navigation"] },
+    { "id": "lay.base", "type": "layer", "subtype": "Template", "name": "BaseLayout", "summary": "Layout wrapping pages via slot, holds global styles.", "complexity": "moderate", "tags": ["template", "layout"] },
+    { "id": "cmp.counter", "type": "component", "name": "Counter", "summary": "Hydrated island marked client:visible, interactive.", "complexity": "moderate", "tags": ["interactive"] }
+  ],
+  "edges": [
+    { "source": "lay.base", "target": "scr.index", "type": "composes", "direction": "forward", "weight": 0.9 }
+  ]
+}
+```

package/reference/frameworks/nextjs.md

@@ -0,0 +1,44 @@
+---
+name: nextjs
+kind: framework
+composes_into: [component-taxonomy-mapper, visual-hierarchy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://nextjs.org/docs/app. -->
+
+# Next.js
+
+## Conventions
+
+- Two routers. App Router (`app/`): folder names are URL segments; `page.tsx` is the routable surface (a screen node). `layout.tsx` wraps and nests its segment; the root layout owns `<html>`/`<body>` and imports `globals.css`.
+- Special files: `loading`, `error`, `template`, `route`. Server Components are the default; `'use client'` marks the client boundary, and only client components are interactive.
+- Pages Router (legacy `pages/`): one file is one route; `_app`/`_document` are shells; data via `getServerSideProps`/`getStaticProps`.
+
+## File patterns
+
+- App Router: `app/**/page.tsx`, `app/**/layout.tsx`, `app/globals.css`.
+- Pages Router: `pages/**`, `pages/_app.tsx`, `pages/_document.tsx`.
+- Identify via: next in deps plus an `app/` or `pages/` directory.
+
+## Gotchas
+
+- Screen nodes are `page.tsx` files; set the node path to the route, not the file path.
+- A `layout.tsx` plus `page.tsx` in one folder is one screen and its layout; emit a composes edge layout to page.
+- Without `'use client'`, a component is not a motion or hover candidate; the boundary gates interactivity.
+- Global tokens enter at the root-layout `globals.css`.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "scr.dashboard", "type": "screen", "name": "/dashboard", "summary": "Routable dashboard page from app/dashboard/page.tsx.", "complexity": "moderate", "tags": ["navigation", "layout"] },
+    { "id": "lay.root", "type": "layer", "subtype": "Template", "name": "RootLayout", "summary": "Root layout owning html and body, imports global tokens.", "complexity": "moderate", "tags": ["template", "layout"] },
+    { "id": "cmp.chart", "type": "component", "name": "Chart", "summary": "Client component marked use client, interactive.", "complexity": "complex", "tags": ["interactive", "data-display"] }
+  ],
+  "edges": [
+    { "source": "lay.root", "target": "scr.dashboard", "type": "composes", "direction": "forward", "weight": 0.9 }
+  ]
+}
+```

package/reference/frameworks/remix.md

@@ -0,0 +1,44 @@
+---
+name: remix
+kind: framework
+composes_into: [component-taxonomy-mapper, visual-hierarchy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://remix.run/docs/en/main/file-conventions/routes (Remix v2 / React Router v7 framework mode). -->
+
+# Remix
+
+## Conventions
+
+- `app/routes/` uses file conventions; `app/root.tsx` is the root layout and renders an `Outlet`.
+- Flat-routes v2: dot-delimited filenames nest, so `concerts.$city.tsx` is a child of `concerts.tsx` and renders inside its `Outlet`. A trailing `_` opts a segment out of layout nesting; a leading `_` marks a pathless layout.
+- Each route module co-locates a `loader` (server read), an `action` (server mutation), and a default-export component (the screen).
+- Global styles ship via an exported `links` array or a CSS import in `root.tsx`.
+
+## File patterns
+
+- `app/root.tsx`, `app/routes/*.tsx` (dot-segment names).
+- Identify via: @remix-run/* or react-router in deps plus an `app/routes/` directory.
+
+## Gotchas
+
+- A route file is a screen; parse the dot-naming to recover the layout tree and emit composes edges parent to child.
+- `loader` and `action` are server data functions, not components; do not map them as nodes.
+- A trailing `_` breaks visual nesting even when the dot path looks nested; respect it when building edges.
+- Tokens enter via the `root.tsx` global stylesheet.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "lay.root", "type": "layer", "subtype": "Template", "name": "Root", "summary": "Root layout with Outlet and global links.", "complexity": "moderate", "tags": ["template", "layout"] },
+    { "id": "scr.concerts", "type": "screen", "name": "concerts", "summary": "Parent route screen rendering nested city Outlet.", "complexity": "moderate", "tags": ["navigation"] },
+    { "id": "scr.concerts.city", "type": "screen", "name": "concerts.$city", "summary": "Child route screen nested in concerts via dot naming.", "complexity": "simple", "tags": ["navigation"] }
+  ],
+  "edges": [
+    { "source": "scr.concerts", "target": "scr.concerts.city", "type": "composes", "direction": "forward", "weight": 0.8 }
+  ]
+}
+```

package/reference/frameworks/storybook.md

@@ -0,0 +1,44 @@
+---
+name: storybook
+kind: framework
+composes_into: [component-taxonomy-mapper, visual-hierarchy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://storybook.js.org/docs/writing-stories. -->
+
+# Storybook
+
+## Conventions
+
+- The richest source of variant and state nodes. A `*.stories.tsx` file in CSF3 has a default export (the meta, typed `Meta<typeof X>`, with `component`, `title`, `args`, `argTypes`) and named exports (the stories, typed `StoryObj`, mostly `args`).
+- Each named story is a concrete variant or state of one component (Primary, Disabled, Loading, Small).
+- `argTypes` declares the controllable prop space; its enumerated `options` describe the full variant axis. `decorators` wrap a story; `play` scripts an interaction.
+
+## File patterns
+
+- `*.stories.@(tsx|jsx|ts|mdx)`, `.storybook/main.ts`, `.storybook/preview.ts` or `preview.tsx`.
+- Identify via: @storybook/* in deps plus any `*.stories.*` file.
+
+## Gotchas
+
+- Map each named story to a variant node, or a state node when the name or args set hover, focus, disabled, active, or loading; link it back to `meta.component` via composes or extends.
+- `argTypes.options` enumerates the full variant space and is richer than a source scan; prefer it.
+- The meta default export is metadata, not a component; decorators are wrappers, not nodes.
+- Handle CSF2 (a `template.bind({})` story) the same as CSF3.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "cmp.button", "type": "component", "name": "Button", "summary": "Component referenced by the stories meta.", "complexity": "moderate", "tags": ["interactive", "atom"] },
+    { "id": "var.button.primary", "type": "variant", "name": "Primary", "summary": "Primary variant story of Button.", "complexity": "simple", "tags": ["interactive"] },
+    { "id": "st.button.disabled", "type": "state", "name": "Disabled", "summary": "Disabled state story of Button.", "complexity": "simple", "tags": ["disabled", "state"] }
+  ],
+  "edges": [
+    { "source": "var.button.primary", "target": "cmp.button", "type": "extends", "direction": "forward", "weight": 0.9 },
+    { "source": "st.button.disabled", "target": "cmp.button", "type": "extends", "direction": "forward", "weight": 0.9 }
+  ]
+}
+```

package/reference/frameworks/sveltekit.md

@@ -0,0 +1,43 @@
+---
+name: sveltekit
+kind: framework
+composes_into: [component-taxonomy-mapper, visual-hierarchy-mapper]
+phase: 54
+---
+<!-- Vendor docs: https://svelte.dev/docs/kit/routing. -->
+
+# SvelteKit
+
+## Conventions
+
+- `src/routes/` uses file routing: `+page.svelte` is a screen, `+layout.svelte` is a wrapper (hierarchical, via `<slot/>` or `{@render children()}`), `+page.ts`/`+page.server.ts` hold `load`, and `+server.ts` is an endpoint.
+- `<style>` in a `.svelte` file is auto-scoped; `:global()` escapes the scope.
+- Shared code lives in `src/lib/` behind the `$lib` alias. Global CSS (`app.css`) is imported once in the root `+layout.svelte`. `src/app.html` is the document shell.
+
+## File patterns
+
+- `src/routes/**/+page.svelte`, `+layout.svelte`, `src/lib/`, `src/app.css`, `svelte.config.js`.
+- Identify via: @sveltejs/kit in deps plus a `src/routes/` directory.
+
+## Gotchas
+
+- Only `+page`-prefixed and `+layout`-prefixed files are routes; a sibling `+page.server.ts` is data, not a screen.
+- Layout nesting follows directory depth; emit one composes edge per level from layout to page.
+- Scoped styles are component-local; do not promote those class names to global tokens.
+- Tokens live in `app.css` under `:root` or a `$lib` theme module; a `$lib` import is a depends-on edge.
+
+## Example output
+
+```json
+{
+  "schema_version": "52.0",
+  "nodes": [
+    { "id": "scr.home", "type": "screen", "name": "/", "summary": "Home screen from src/routes/+page.svelte.", "complexity": "simple", "tags": ["navigation"] },
+    { "id": "lay.root", "type": "layer", "subtype": "Template", "name": "RootLayout", "summary": "Root +layout.svelte wrapping pages, imports app.css.", "complexity": "moderate", "tags": ["template", "layout"] },
+    { "id": "tok.color.bg", "type": "token", "subtype": "color", "name": "--bg", "summary": "Surface color token declared in app.css :root.", "complexity": "simple", "tags": ["color", "surface"] }
+  ],
+  "edges": [
+    { "source": "lay.root", "target": "scr.home", "type": "composes", "direction": "forward", "weight": 0.9 }
+  ]
+}
+```