@hegemonart/get-design-done 1.0.7

package/connections/figma-writer.md

@@ -0,0 +1,139 @@
+# Figma Writer — Connection Specification
+
+This file is the connection specification for the figma-writer capability within the get-design-done pipeline. The figma-writer is a proposal→confirm write agent (`design-figma-writer`) that wraps the `mcp__figma__use_figma` remote MCP to write design decisions back to Figma. It is distinct from the Figma Desktop MCP read connection documented in `connections/figma.md`. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## Setup
+
+**Prerequisites:**
+
+- Figma desktop app installed and running (required for read operations via `mcp__figma-desktop__*`)
+- Dev Mode enabled in the Figma desktop app
+- Remote Figma MCP registered for write operations
+
+**Register remote MCP (Claude Code):**
+
+```
+claude mcp add figma --transport http https://mcp.figma.com/v1/sse
+```
+
+After running this command, restart the Claude Code session. The remote MCP server authenticates via OAuth at `mcp.figma.com`. On first use, Claude Code will prompt you to complete the OAuth flow.
+
+**Verification:**
+
+After session restart, run:
+
+```
+ToolSearch({ query: "select:mcp__figma__use_figma", max_results: 1 })
+```
+
+Expect a non-empty result listing `mcp__figma__use_figma`. If empty, the remote MCP is not registered — run the registration command above and restart.
+
+---
+
+## Tools
+
+All write operations use the `mcp__figma__` prefix (remote MCP). Read operations use the `mcp__figma-desktop__` prefix (desktop MCP).
+
+| Tool | Full name | Returns | Pipeline use |
+|------|-----------|---------|--------------|
+| `use_figma` | `mcp__figma__use_figma` | operation result | all write operations (annotate, tokenize, mappings) |
+
+**Important distinction:** `mcp__figma-desktop__*` tools are used for reads only (get_metadata, get_variable_defs). `mcp__figma__use_figma` is the remote MCP used exclusively for writes. The desktop MCP does NOT expose `use_figma` — it is remote-only. Do not attempt to call `mcp__figma-desktop__use_figma` — that tool does not exist.
+
+---
+
+## Three Modes
+
+The figma-writer operates in one of three modes per invocation:
+
+| Mode | Description | Source data | Figma target |
+|------|-------------|-------------|--------------|
+| `annotate` | Write design decision annotations onto Figma layer comments | D-XX decisions from DESIGN-CONTEXT.md | Layer comments on affected frames/components |
+| `tokenize` | Replace hard-coded color/spacing/type literals with Figma variable references | Color/spacing/typography values from DESIGN-CONTEXT.md; existing variables from `get_variable_defs` | Variable bindings on layer fill/stroke/spacing properties |
+| `mappings` | Write Code Connect mappings linking component instances to code file paths | Component names and file paths from DESIGN-CONTEXT.md | Code Connect entries on Figma component nodes |
+
+All three modes follow the proposal→confirm UX: the agent builds a numbered operation list and presents it to the user before executing any write. The user must confirm before `use_figma` is called.
+
+---
+
+## Which Stages Use This Connection
+
+| Stage | Agent/Skill | Tool used | Purpose |
+|-------|-------------|-----------|---------|
+| figma-write | `agents/design-figma-writer.md` | `mcp__figma__use_figma` | Write design decisions back to Figma in three modes (annotate/tokenize/mappings) |
+| design | `skills/design/SKILL.md` | (dispatch only) | Offer to spawn design-figma-writer after design-executor completes, when figma_writer: available |
+
+---
+
+## Availability Probe (ToolSearch-only)
+
+The figma-writer probe is ToolSearch-only — no live call at probe time. This matches the Refero connection pattern (opt-in tool, no live call needed to confirm availability).
+
+```
+ToolSearch({ query: "select:mcp__figma__use_figma", max_results: 1 })
+→ Empty result      → figma_writer: not_configured  (skip figma-write entirely; log to STATE.md)
+→ Non-empty result  → figma_writer: available
+```
+
+Write `figma_writer:` status to `.design/STATE.md` `<connections>` immediately after probing.
+
+Note: The status key is `figma_writer:` (with underscore). This is distinct from `figma:` (desktop MCP status) and `figma_write:` is not used — the canonical key is `figma_writer:`.
+
+---
+
+## Fallback Behavior
+
+When `figma_writer` is `not_configured`, the pipeline degrades gracefully — no error is raised.
+
+**figma-write stage:**
+- `figma_writer: not_configured` → skip with note: "Figma write skipped — remote MCP not installed. Register with: claude mcp add figma --transport http https://mcp.figma.com/v1/sse"
+
+**design stage:**
+- `figma_writer: not_configured` or absent → skip the figma-write dispatch offer entirely (no prompt, no output)
+- `figma_writer: available` → offer opt-in prompt after design-executor completes
+
+**Special case — desktop MCP present but remote absent:**
+If `figma: available` (desktop MCP) but `figma_writer: not_configured` (remote MCP absent), the figma-write capability is still not available. Desktop MCP cannot perform writes. Do not offer figma-write dispatch in this state.
+
+---
+
+## STATE.md Integration
+
+The scan stage writes the initial `figma_writer:` status. Subsequent stages read from STATE.md without re-probing.
+
+Example `<connections>` block after probing:
+
+```xml
+<connections>
+figma: available
+figma_writer: available
+refero: not_configured
+</connections>
+```
+
+**Status key:** `figma_writer:` (underscore separator)
+
+**Status values:**
+
+| Value | Meaning |
+|-------|---------|
+| `available` | ToolSearch returned non-empty for `mcp__figma__use_figma` |
+| `not_configured` | ToolSearch returned empty — remote MCP not registered |
+
+Note: There is no `unavailable` state for figma_writer — the ToolSearch-only probe cannot detect auth failures. Auth issues surface at execution time when `use_figma` is first called.
+
+---
+
+## Caveats and Pitfalls
+
+1. **`mcp__figma__use_figma` is the remote MCP only.** It is registered as server `figma` via `claude mcp add`. It is NOT the same as the desktop MCP (`mcp__figma-desktop__*`). Running ToolSearch for `figma-desktop` will NOT find `use_figma`. Always use `select:mcp__figma__use_figma` as the probe query.
+
+2. **All writes require user confirmation.** The proposal→confirm UX in design-figma-writer ensures the user reviews all operations before any write is executed. There is no auto-approve mode.
+
+3. **Use `--dry-run` to inspect the proposal without risk.** Pass `--dry-run` to emit the full operation list without calling `use_figma`. Safe to run on production Figma files.
+
+4. **Use `--confirm-shared` for team library components.** Before any write, the agent detects shared team library components via `get_metadata`. If shared components are in the operation list and `--confirm-shared` was not passed, the agent halts and requires the flag. This prevents accidental modification of team-wide design tokens.
+
+5. **Operations execute sequentially, not atomically.** If one operation fails mid-sequence, the agent logs the error and continues with remaining operations. The Figma file may be left in a partially-updated state. The summary lists all failures for manual follow-up.

package/connections/figma.md

@@ -0,0 +1,146 @@
+# Figma MCP — Connection Specification
+
+This file is the connection specification for the official Figma Desktop MCP within the get-design-done pipeline. It provides the setup guide, tool inventory, per-stage usage, probe pattern, fallback behavior, and anti-patterns. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## Setup
+
+**Prerequisites:**
+
+- Figma desktop app installed and running
+- Dev Mode enabled in the Figma desktop app (File menu → Enable Dev Mode, or toggle in the toolbar)
+
+**Install command (Claude Code):**
+
+```
+claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
+```
+
+After running this command, restart the Claude Code session. The MCP server connects via HTTP to the Figma desktop app's local MCP endpoint.
+
+**Verification:**
+
+After session restart, run:
+
+```
+ToolSearch({ query: "figma-desktop", max_results: 10 })
+```
+
+Expect non-empty results listing `mcp__figma-desktop__*` tools. If results are empty, the desktop app is not running or Dev Mode is not enabled — fix both and restart.
+
+**Warning — wrong MCP confusion:**
+
+This spec targets the **official Figma Desktop MCP** (`mcp__figma-desktop__*` prefix, server name `figma-desktop`, HTTP transport).
+
+Do NOT confuse with the southleft `figma-console-mcp` package (registered as `"figma-console"` in `~/.claude/mcp.json`, uses `figma_*` prefix). Both can be active simultaneously. The pipeline uses `mcp__figma-desktop__*` exclusively — it is stable, official, and requires no external package dependency beyond the Figma desktop app.
+
+---
+
+## Tools
+
+All tools use the `mcp__figma-desktop__` prefix.
+
+| Tool | Full name | Returns | Phase 4 use |
+|------|-----------|---------|-------------|
+| `get_variable_defs` | `mcp__figma-desktop__get_variable_defs` | Variable collection tree: collection ID, mode names, variable names (hierarchical, e.g. `colors/primary/500`), resolved values (hex for COLOR, float for FLOAT), descriptions, scopes | **In scope** — scan: token augmentation (CONN-03); discover: decisions pre-population (CONN-04) |
+| `get_design_context` | `mcp__figma-desktop__get_design_context` | Structured React+Tailwind component tree of the current Figma selection | **In scope (secondary)** — discover: existing design decisions for established Figma systems |
+| `get_screenshot` | `mcp__figma-desktop__get_screenshot` | Screenshot image of the selected Figma layer or frame | Out of scope Phase 4 |
+| `get_metadata` | `mcp__figma-desktop__get_metadata` | Lightweight XML outline: layer IDs, names, types, position/size. Works with no selection open. | **In scope** — used as the availability probe (no file must be open) |
+| `get_code_connect_map` | `mcp__figma-desktop__get_code_connect_map` | Maps Figma component instances to code implementations (file paths, framework labels) | Out of scope Phase 4 |
+| `create_design_system_rules` | `mcp__figma-desktop__create_design_system_rules` | Generates rule files for design system alignment during code generation | Out of scope Phase 4 |
+
+`get_metadata` is preferred for probing because it works without a file or selection open, keeping the probe lightweight. `get_variable_defs` is the primary workhorse for token extraction and decisions pre-population.
+
+---
+
+## Which Stages Use This Connection
+
+| Stage | Skill/Agent | Tool used | Purpose |
+|-------|------------|-----------|---------|
+| scan | `skills/scan/SKILL.md` | `get_variable_defs` | Token augmentation — supplements grep-based CSS token extraction with Figma variable definitions (CONN-03) |
+| discover | `agents/design-context-builder.md` | `get_variable_defs` | Decisions pre-population — pre-fills D-XX color/spacing/typography decisions from Figma variables before the interview (CONN-04) |
+| plan | — | — | Not currently used |
+| verify | — | — | Not currently used |
+
+Both scan and discover call `get_variable_defs` with no explicit selection to retrieve all variables in the active Figma file. If no file is open, the call errors and the stage falls back to its non-Figma path.
+
+---
+
+## Availability Probe
+
+**Call ToolSearch first — always.** In Claude Code sessions with many MCP servers, `mcp__figma-desktop__*` tools may be in the deferred tool set (not loaded into context at session start). Calling a deferred tool directly fails silently or errors. ToolSearch loads the tools into context and confirms their presence in a single call.
+
+**Figma probe sequence:**
+
+```
+Step 1 — ToolSearch check:
+  ToolSearch({ query: "select:mcp__figma-desktop__get_metadata", max_results: 1 })
+  → Empty result      → figma: not_configured  (MCP not registered or app not running)
+  → Non-empty result  → proceed to Step 2
+
+Step 2 — Live tool call:
+  call mcp__figma-desktop__get_metadata
+  → Success           → figma: available
+  → Error             → figma: unavailable
+```
+
+Write the result to `.design/STATE.md <connections>` immediately after probing.
+
+---
+
+## Fallback Behavior
+
+When figma is `not_configured` or `unavailable`, stages degrade gracefully — no error is raised.
+
+**scan stage:**
+
+- Skip Step 2A (Figma Token Augmentation)
+- Rely on grep-based CSS custom property extraction alone
+- DESIGN.md token section uses `source: CSS custom properties` (not `source: figma-variables`)
+- `figma_variables_used: false` in DESIGN.md frontmatter
+
+**discover stage (design-context-builder):**
+
+- Skip Step 0 (Figma Pre-population)
+- Populate D-XX decisions via interview only (manual elicitation from the user)
+- DESIGN-CONTEXT.md omits the "Token decisions pre-populated from Figma variables" note
+
+Neither stage appends a `<blocker>` for a missing Figma connection — Figma is an enhancement, not a requirement. If a `must_have` explicitly requires Figma data, THEN append a blocker.
+
+---
+
+## STATE.md Integration
+
+Every stage writes its probe result to `.design/STATE.md` under the `<connections>` section:
+
+```xml
+<connections>
+figma: available
+refero: not_configured
+</connections>
+```
+
+**Status values:**
+
+| Value | Meaning |
+|-------|---------|
+| `available` | `get_metadata` returned a successful response |
+| `unavailable` | Tool is in the session but errored (app offline, no file open, rate-limited) |
+| `not_configured` | ToolSearch returned empty for `figma-desktop` — MCP not registered |
+
+The `<connections>` schema is minimal by design. Traceability of which outputs came from Figma is handled via source annotations in DESIGN.md (`source: figma-variables`) and DESIGN-CONTEXT.md ("pre-populated from Figma variables"), not via richer STATE.md fields.
+
+---
+
+## Caveats and Pitfalls
+
+- **`get_variable_defs` returns resolved values, not alias chains.** If a semantic token (`colors/semantic/brand`) aliases a primitive (`colors/blue/500`), only the resolved hex is returned. When recording variables in DESIGN.md, use the variable NAME alongside the hex: `colors/semantic/brand = #3B82F6`. Add a note: "resolved value — may alias a primitive; verify in Figma if the token layer matters."
+
+- **`get_variable_defs` requires an open Figma file.** If no file is open in the desktop app, the call errors. The probe falls to `unavailable` in this case — the stage skips Figma steps and continues with non-Figma fallbacks.
+
+- **Multi-mode variables (Light/Dark).** Variables may carry values for multiple modes. When present, extract both: `#3B82F6 (light) / #60A5FA (dark)`. DESIGN.md can note dark-mode token existence in the color section.
+
+- **Deferred-tool loading.** Always call `ToolSearch` before any `mcp__figma-desktop__*` tool invocation. This applies at every stage entry, even if Figma was `available` in a previous run — tool availability can change between sessions.
+
+- **Wrong-MCP confusion.** This spec covers `mcp__figma-desktop__*` (official Figma Desktop MCP). The southleft `figma-console-mcp` uses `figma_*` prefix and serves different use cases. Do not mix them. If ToolSearch returns results prefixed `figma_` but not `mcp__figma-desktop__`, the Figma Desktop MCP is still not configured.

package/connections/graphify.md

@@ -0,0 +1,197 @@
+# Graphify — Connection Specification
+
+This file is the connection specification for Graphify within the get-design-done pipeline. Graphify builds a queryable knowledge graph over the codebase — mapping component↔token↔decision relationships via Tree-sitter static analysis and LLM semantic extraction. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## Setup
+
+**Prerequisites:**
+- Python 3.9+ available on PATH
+- GSD framework with `graphify.enabled = true` in `.planning/config.json`
+
+**Install:**
+```
+pip install graphifyy
+graphify install        # installs skill files into ~/.claude/skills/graphify/
+```
+
+**Enable in GSD config:**
+```
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-set graphify.enabled true
+```
+
+**Build the graph (initial):**
+```
+graphify .              # run in project root; produces graphify-out/graph.json
+# or via GSD tools:
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify build
+```
+
+**Recommended: auto-rebuild after commits:**
+```
+graphify hook install
+```
+
+**Verification:**
+After building, run:
+```
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status
+```
+Expect: `{ enabled: true, graph_path: "...", node_count: N, edge_count: N, stale: false }`
+
+**Note:** Graphify is an optional external dependency. It requires Python and takes 1-5 minutes to build on a large codebase. Do NOT add to plugin bootstrap — users opt in manually.
+
+---
+
+## Graph Schema
+
+### Node Types
+
+| Node type | Source | ID pattern |
+|-----------|--------|-----------|
+| component | `.stories.tsx` / `src/components/*.tsx` | `component:<name>` |
+| token:color | CSS custom properties / Figma variables | `token:color/<name>` |
+| token:spacing | CSS custom properties | `token:spacing/<name>` |
+| token:typography | CSS custom properties | `token:typography/<name>` |
+| token:motion | CSS animation variables | `token:motion/<name>` |
+| page/route | `src/app/` or `src/pages/` | `page:<path>` |
+| decision | DESIGN-CONTEXT.md D-XX entries | `decision:D-<nn>` |
+| must-have | DESIGN-CONTEXT.md M-XX entries | `must-have:M-<nn>` |
+| debt-item | DESIGN-DEBT.md entries | `debt:<id>` |
+| anti-pattern | DESIGN-CONTEXT.md anti-patterns | `antipattern:<name>` |
+| a11y-finding | DESIGN-VERIFICATION.md violations | `a11y:<rule-name>` |
+| figma-variable | Figma `get_variable_defs` output | `figma-var:<name>` |
+
+### Edge Types
+
+| Edge | From | To | Meaning |
+|------|------|-----|---------|
+| `uses` | component | token | Component references this token |
+| `renders` | page | component | Page renders this component |
+| `violates` | debt-item | decision | Debt item contradicts this decision |
+| `derives-from` | a11y-finding | component | A11y finding originates in this component |
+| `maps-to` | figma-variable | token | Figma variable corresponds to CSS token |
+| `detected-at` | anti-pattern | component | Anti-pattern found in this component |
+
+### graph.json structure
+
+```json
+{
+  "nodes": [
+    { "id": "component:Button", "label": "Button", "type": "component",
+      "description": "Primary interactive element", "source": "src/components/Button.tsx" }
+  ],
+  "edges": [
+    { "source": "component:Button", "target": "token:color/primary/500",
+      "label": "uses", "confidence": "EXTRACTED", "confidence_score": 0.95 }
+  ]
+}
+```
+
+Edge confidence tiers: EXTRACTED (found in source), INFERRED (semantic inference), AMBIGUOUS (flagged for review).
+
+---
+
+## Which Stages Use This Connection
+
+| Stage | Agent | Usage | Purpose |
+|-------|-------|-------|---------|
+| plan | `agents/design-planner.md` | Pre-scope token query | Count affected components before scoping a token change task |
+| verify | `agents/design-integration-checker.md` | Pre-search D-XX query | Find components and tokens connected to each decision before grep |
+
+Graphify is NOT called during scan, discover, or design. It is a read-only pre-search oracle for planner and verifier agents.
+
+---
+
+## Availability Probe
+
+Unlike MCP connections, Graphify has no ToolSearch check. The probe is file-existence + config-flag based.
+
+**Graphify probe sequence (execute at agent entry, before using graph):**
+
+Step G1 — Config check:
+```
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status
+→ Error or { enabled: false }  → graphify: not_configured  (skip all graph steps)
+→ { enabled: true }            → proceed to Step G2
+```
+
+Step G2 — Graph file check:
+```
+Check if graphify-out/graph.json exists in project root
+→ Absent                       → graphify: unavailable  (graph not built yet)
+→ Present                      → graphify: available
+```
+
+Write graphify status to `.design/STATE.md` `<connections>`.
+
+**Note:** Agents check `.design/STATE.md` `<connections>` FIRST before running the probe. If a prior stage already wrote `graphify: available`, skip the probe and use the cached status.
+
+---
+
+## Pre-Search Consultation Pattern
+
+This is the canonical pre-search pattern for agents. Copy inline — SKILL.md and agent files have no include mechanism.
+
+**For decision-based queries (design-integration-checker):**
+
+Step 1: Query graph for decision node and its neighbors
+```
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify query "decision:D-<nn>" --budget 1500
+→ Returns: connected components + tokens as JSON
+→ Use returned component IDs as grep seed list (reduces false-negative "not found")
+```
+
+Step 2: Grep each returned component for the decision pattern
+(then continue to standard grep behavior if graph returned nothing)
+
+**For token-based queries (design-planner):**
+
+Step 1: Query graph for token node and its neighbors
+```
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify query "<token-name>" --budget 1500
+→ Returns: all components that reference this token
+→ Annotate planned task with "N components affected" before scoping
+```
+
+Step 2: Include component list in the task description
+(then continue standard planning behavior)
+
+**Budget note:** Use `--budget 1500` for pre-search queries. High confidence_score edges (>= 0.8) are more reliable; AMBIGUOUS edges are hints only.
+
+---
+
+## Fallback
+
+| Status | Behavior |
+|--------|----------|
+| `graphify: available` | Agents query graph before grep; annotate results with graph context |
+| `graphify: unavailable` | Agents skip graph steps; log "graphify query skipped — graph not built" in output; fall back to grep |
+| `graphify: not_configured` | Same as unavailable; no user-visible error (opt-in feature) |
+
+The graph is a performance optimization and accuracy enhancer. It is never a hard requirement. All agents MUST produce valid output via grep alone.
+
+---
+
+## Anti-Patterns
+
+- **Do NOT use graphify to replace grep.** The graph is a seed list, not a complete index. Always grep after querying the graph.
+- **Do NOT embed graph.json contents in agent context.** Query specific nodes via gsd-tools; never read graph.json directly.
+- **Do NOT query the graph during scan or design stages.** The graph is read-only and only useful when decisions already exist (plan, verify).
+- **Do NOT block on graph build time.** If `graphify build` takes >30 seconds mid-session, log "graphify build deferred — run /gdd:graphify build manually" and continue without graph.
+- **Do NOT assume graph covers .design/ artifacts.** Graphify analyzes source code (src/, components/). DESIGN-CONTEXT.md and DESIGN-PLAN.md are not graph nodes unless explicitly indexed.
+
+---
+
+## /gdd:graphify Commands
+
+| Subcommand | GSD tools call | Purpose |
+|------------|----------------|---------|
+| `build` | `gsd-tools graphify build` | Build or rebuild the knowledge graph |
+| `query <term>` | `gsd-tools graphify query "<term>" --budget 2000` | Query the graph for a node and its neighbors |
+| `status` | `gsd-tools graphify status` | Check graph age, node count, enabled status |
+| `diff` | `gsd-tools graphify diff` | Show topology changes since last build |
+
+If `graphify.enabled = false` in `.planning/config.json`, the skill prompts:
+"Graphify is not enabled. Enable with: gsd-tools config-set graphify.enabled true — then run /gdd:graphify build."

package/connections/pinterest.md

@@ -0,0 +1,153 @@
+# Pinterest MCP — Connection Specification
+
+This file is the connection specification for Pinterest MCP within the get-design-done pipeline. Its primary role is to provide visual reference collection in the discover stage — users search Pinterest for design patterns, color palettes, and UI inspiration that feed into the research-synthesizer as reference inputs. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## Setup
+
+**Prerequisites:**
+
+- Pinterest MCP installed and registered in Claude Code. The recommended package is `terryso/mcp-pinterest` (headless scraping, no API key required).
+
+**Install command (Claude Code):**
+
+```
+npx -y @smithery/cli install mcp-pinterest --client claude
+```
+
+This registers the server with the name `mcp-pinterest`. After running, restart the Claude Code session.
+
+**Alternative package:**
+
+```
+npx @iflow-mcp/pinterest-mcp-server
+```
+
+If using the alternative, the server name may differ — run the verification step below to confirm.
+
+**Verification:**
+
+After session restart, run:
+
+```
+ToolSearch({ query: "mcp-pinterest", max_results: 5 })
+```
+
+Expect non-empty results listing `mcp__mcp-pinterest__*` tools. If results are empty, the Pinterest MCP is not registered — run the install command above and restart.
+
+**Warning — prefix depends on registration name:**
+
+Pinterest MCP tool names in Claude Code follow the pattern `mcp__<server-name>__<tool-name>`. The default Smithery install uses `mcp-pinterest` as the server name, giving the prefix `mcp__mcp-pinterest__`. However, if registered with a different name (e.g., `pinterest`), the prefix becomes `mcp__pinterest__`. **Always verify via ToolSearch at runtime — never hardcode the prefix.** The stage probe handles this automatically.
+
+---
+
+## Tools
+
+Tool names below assume the default `mcp-pinterest` server registration. Actual names may differ — confirm via ToolSearch.
+
+| Tool shortname | Expected full name | Returns | Pipeline use |
+|----------------|-------------------|---------|--------------|
+| `pinterest_search` | `mcp__mcp-pinterest__pinterest_search` | Array of pin objects (url, title, image_url, description) | **Primary discover tool** — search by keyword for design inspiration |
+| `pinterest_get_image_info` | `mcp__mcp-pinterest__pinterest_get_image_info` | Pin metadata (title, description, board, creator, tags) | Detail enrichment for a specific pin URL |
+| `pinterest_search_and_download` | `mcp__mcp-pinterest__pinterest_search_and_download` | Search results + local image downloads | Heavy mode — only use if offline image analysis is required |
+
+**Recommended for pipeline use:** `pinterest_search` only. It returns pin metadata without downloading images, keeping token cost and latency low. `pinterest_get_image_info` is used when a specific pin needs deeper attribution. `pinterest_search_and_download` should only be used when the user explicitly needs local image files.
+
+---
+
+## Which Stages Use This Connection
+
+| Stage | Skill/Agent | Tools used | Purpose |
+|-------|------------|------------|---------|
+| discover | `agents/design-research-synthesizer.md` | `pinterest_search` | Search for visual inspiration matching the project's design direction; results feed into `<connection_sources>` section of DESIGN-CONTEXT.md |
+
+Pinterest is a reference source only — it feeds the synthesizer alongside Refero, awesome-design-md, and Figma variables. It does NOT modify STATE.md decisions directly.
+
+---
+
+## Availability Probe
+
+**Pinterest uses the ToolSearch-only probe pattern** — identical to Refero. No live tool call is needed to confirm availability.
+
+```
+Step P1 — ToolSearch check (discover stage entry):
+  ToolSearch({ query: "mcp-pinterest", max_results: 5 })
+  → Empty result      → pinterest: not_configured  (skip Pinterest; fall through to Refero)
+  → Non-empty result  → pinterest: available
+```
+
+**No live call at probe time.** Unlike Preview (which calls `preview_list`), Pinterest requires no live probe call. ToolSearch presence is sufficient — the tool will be called only when a search query is needed.
+
+Write the result to `.design/STATE.md <connections>` immediately after probing in scan stage.
+
+**Fallback chain (discover stage):**
+
+Pinterest falls into the reference-source fallback chain as the first tier:
+
+```
+Pinterest (if available)
+  → Refero (if available)
+    → awesome-design-md (always available — static curated list in reference/)
+```
+
+When Pinterest is available, search it first. When Pinterest is `not_configured`, skip silently and proceed to Refero. The synthesizer uses whichever sources are available — there is no minimum required source count.
+
+---
+
+## Fallback Behavior
+
+When Pinterest is `not_configured`:
+
+- Skip the Pinterest search step in the synthesizer entirely
+- Do NOT emit a warning or blocker to the user — Pinterest is an enhancement, not a requirement
+- Proceed to Refero in the fallback chain
+- The `<connection_sources>` section of DESIGN-CONTEXT.md should note: `pinterest: not_configured — skipped`
+
+When Pinterest is `available` but `pinterest_search` returns an error or empty results:
+
+- Log the error in DESIGN-CONTEXT.md `<connection_sources>` section
+- Set `pinterest: unavailable` in STATE.md `<connections>`
+- Proceed to Refero
+
+---
+
+## STATE.md Integration
+
+Scan stage probes Pinterest at pipeline entry and writes the result to `<connections>`:
+
+```xml
+<connections>
+figma: available
+refero: not_configured
+preview: available
+storybook: not_configured
+chromatic: not_configured
+figma_writer: not_configured
+graphify: not_configured
+pinterest: available
+claude_design: not_configured
+</connections>
+```
+
+**Status values:**
+
+| Value | Meaning |
+|-------|---------|
+| `available` | ToolSearch returned non-empty results for `mcp-pinterest` |
+| `not_configured` | ToolSearch returned empty — Pinterest MCP not registered in this session |
+| `unavailable` | Tool is present but `pinterest_search` errored or returned empty on first call |
+
+---
+
+## Caveats and Pitfalls
+
+1. **Headless scraping may be rate-limited.** `terryso/mcp-pinterest` uses headless browser scraping, not the official Pinterest API. Rate limits or IP blocks are possible if too many searches are made in quick succession. Limit to 2-3 searches per discover session. The pipeline naturally constrains this by searching once per design concern (color, typography, layout) rather than repeatedly.
+
+2. **No authentication required — but content is public only.** Pinterest MCP accesses only public pins. Private boards and pins are not accessible. This is by design for the pipeline use case — design inspiration should be sourced from publicly shareable references.
+
+3. **Tool prefix uncertainty — always use ToolSearch.** Never call `mcp__mcp-pinterest__pinterest_search` directly without first confirming via ToolSearch that the tool exists under that name. If the user registered the server as `pinterest` (no `mcp-` prefix), the tool would be `mcp__pinterest__pinterest_search`. The probe pattern above handles this automatically.
+
+4. **Image URLs may be ephemeral.** Pinterest image URLs (CDN links) can expire or change. Do not cache image URLs in STATE.md or DESIGN-CONTEXT.md for more than one session. Reference search results by pin title and query context, not by image URL.
+
+5. **Results are inspiration, not specifications.** Pinterest references are inputs to the synthesizer, which extracts design signals (dominant colors, typography patterns, spacing density). Do not treat a Pinterest search result as a binding design decision — it informs the D-XX discussion in the discover stage.