design-playbook 0.11.1 → 0.13.0

package/README.md

@@ -135,9 +135,28 @@ The Design I/O run is a **declared, host-neutral contract** over plain-Markdown
 
 Run artifacts land under `.scratch/<run>/` (`design-baseline/`, `plan.md`, `preview/`, `evidence/manifest.jsonl`, `point-back.md`); see the orchestrator skill for what lands when. That is where to look — and manually intervene — when a run stalls.
 
+### Stuck / resume
+
+```text
+python <pkg>/scripts/run_status.py .scratch/<run>          # text phases + next action
+python <pkg>/scripts/run_status.py .scratch/<run> --json   # machine-readable
+python <pkg>/scripts/run_status.py --list                  # newest runs under .scratch/
+```
+
+The status command reuses the packaged validator’s G5 confirm rules. It is part of the installed package — not monorepo-only tooling.
+
+### Doctor
+
+```text
+python <pkg>/scripts/doctor.py
+python <pkg>/scripts/doctor.py --json
+```
+
+One packaged diagnosis for interpreter, package surface, optional Playwright, and run-root configuration. Distinguishes `ok` / `degraded` / `broken` with repair actions.
+
 **Bundled MCP (v0.3+):** Preview (`mcp/preview/`) and Evidence (`mcp/evidence/`) runtimes ship inside this package and are registered by `.mcp.json` (`${CLAUDE_PLUGIN_ROOT}`). Sibling monorepo dirs remain compatibility launchers/docs. The orchestrator still **probes** MCP `tools/list` and skips `preview*` / `observe*` when tools are absent. Evidence provider writes artifacts only — never the manifest. **`DESIGN_PLAYBOOK_RUN_ROOT`:** default `"."` in `.mcp.json` is the **MCP process cwd**, not the chat workspace — for a host-app dogfood, set an **absolute** path to `.scratch/<run>/` (see [`mcp/evidence/README.md`](mcp/evidence/README.md)). Capture responses include `written_path` (absolute) so mis-rooted writes are visible without a filesystem search.
 
-What is **deterministically enforced** today: plugin install/structure (`scripts/validate.py`) and the run-artifact shape (`scripts/validate_run.py` — L1–L6 present; every top-level L6 item ordered `Given -> When -> Then`; one non-empty four-field evidence ledger row per `L6.<n>` with allowed results; four non-empty finding fields with non-empty source; exactly one explicit `## Verdict` of `Pass` or `Recirculate`; Pass requires every evidence result to be `pass` and exactly one issue-linked `0 blocking` closure per blocking finding; exit 0/`RUN OK`, exit 1/`RUN INVALID`, exit 2/`RUN ERROR`; regression-tested by `tests/test_validate_run.py`, which also validates the showcase artifacts directly; **G5** is a *conditional* preview-confirm gate — enforced only when preview artifacts exist / `--preview-dir` is used; **G6** is a *conditional* evidence-binding gate — enforced only when a ledger `observed` references an `evidence/` artifact / `--evidence-dir` is used; opt-in **strict mode** via `--require-preview` / `--require-evidence` / `--strict`). The `observe*` step probes MCP tool `execute_capture_plan` and is skipped when absent. Everything else in the pipeline is agent-executed craft judgment, not a machine gate.
+What is **deterministically enforced** today: repository install/structure CI checks and the run-artifact shape (`scripts/validate_run.py` — L1–L6 present; every top-level L6 item ordered `Given -> When -> Then`; one non-empty four-field evidence ledger row per `L6.<n>` with allowed results; four non-empty finding fields with non-empty source; exactly one explicit `## Verdict` of `Pass` or `Recirculate`; Pass requires every evidence result to be `pass` and exactly one issue-linked `0 blocking` closure per blocking finding; exit 0/`RUN OK`, exit 1/`RUN INVALID`, exit 2/`RUN ERROR`; regression-tested by `tests/test_validate_run.py`, which also validates the showcase artifacts directly; **G5** is a *conditional* preview-confirm gate — enforced only when preview artifacts exist / `--preview-dir` is used; **G6** is a *conditional* evidence-binding gate — enforced only when a ledger `observed` references an `evidence/` artifact / `--evidence-dir` is used; opt-in **strict mode** via `--require-preview` / `--require-evidence` / `--strict`). The `observe*` step probes MCP tool `execute_capture_plan` and is skipped when absent. Everything else in the pipeline is agent-executed craft judgment, not a machine gate.
 
 ## Codex
 

package/codex/AGENTS.md

@@ -0,0 +1,70 @@
+# design-playbook for Codex
+
+## Install (path of record)
+
+Marketplace catalog lives at the **repo root** (same GitHub repo as Claude Code).
+
+```bash
+# published
+codex plugin marketplace add Bandersnatch0x/design-playbook
+codex plugin add design-playbook@design-playbook
+
+# local monorepo (dev)
+codex plugin marketplace add <abs-path-to-repo-root>
+codex plugin add design-playbook@design-playbook
+```
+
+Verify:
+
+```bash
+codex plugin list -m design-playbook --available --json
+# expect: design-playbook@design-playbook, enabled=true after add
+```
+
+Codex-native manifest: `packages/design-playbook/.codex-plugin/plugin.json`  
+Codex MCP (relative paths, no `CLAUDE_PLUGIN_ROOT`): `.codex-plugin/mcp.json`  
+Skills: `packages/design-playbook/skills/*`
+
+## Fallback: skills-only install
+
+If you only want skills under `~/.codex/skills` (no plugin marketplace):
+
+```bash
+# from repo root — copies/symlinks skill trees into ~/.codex/skills
+python packages/design-playbook/codex/install_skills.py --force
+# or @-reference a single skill:
+#   @packages/design-playbook/skills/design-playbook/SKILL.md
+```
+
+Manual MCP (only if not using `codex plugin add`):
+
+```toml
+# ~/.codex/config.toml
+[mcp_servers.design-playbook-preview]
+command = "python"
+args = ["<abs>/packages/design-playbook/mcp/preview/server.py"]
+
+[mcp_servers.design-playbook-evidence]
+command = "python"
+args = ["<abs>/packages/design-playbook/mcp/evidence/server.py"]
+# evidence also needs: pip install playwright && playwright install chromium
+```
+
+## Load order
+
+1. `skills/design-playbook/SKILL.md`
+2. Standard order: `design-baseline?` → `ux-spec` → `ui-picker` → `fill` → `craft-guard` → `ui-evaluator`.
+
+Native desktop order: `ux-spec` → `native-craft` → `ui-picker` → `fill` → `craft-guard` → `ui-evaluator`.
+
+Conditional entry `reference-intake?` (screenshot/URL/design/product analogy, ADR-0011) runs **before** `ux-spec?` when reference materials are present — fixed orchestrator order, not reorderable. Run `native-craft` only for an explicit native-desktop/native-feel target. Web and mobile Web skip `native-craft`; if the platform is unclear, ask before choosing the order. The orchestrator owns the decision gate, render-surface seam handoff, and fail-closed behavior.
+
+Conditional entry `design-baseline?` (ADR-0012) runs before `reference-intake?` for UI builds/fixes in repositories with meaningful existing first-party UI. Existing-product Fill requires a valid existing baseline, an accepted generated baseline, or an explicit user waiver.
+
+Mirror the orchestrator's skip narration (SKILL.md Steps preamble): when a step is skipped, output one line — step name + reason + how to enable, with the gate label when one applies, e.g. `-> preview*: adapter absent, skipped (G5 not triggered; enable via packages/design-playbook/mcp/preview/ or host MCP)`.
+
+## Compose
+
+- Style DB → ui-ux-pro-max
+- Visual risk → frontend-design
+- Pipeline + acceptance → design-playbook

package/codex/install_skills.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Cross-platform Codex skill installer for design-playbook.
+
+Creates (or refreshes) symlinks under ``~/.codex/skills/<name>`` pointing at
+this package's ``skills/*`` directories. Falls back to directory copy when
+symlinks are unavailable (common on Windows without Developer Mode).
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+from pathlib import Path
+
+PACKAGE = Path(__file__).resolve().parents[1]
+SKILLS_SRC = PACKAGE / "skills"
+DEFAULT_DEST = Path.home() / ".codex" / "skills"
+
+
+def install_one(src: Path, dest: Path, *, force: bool) -> str:
+    if not src.is_dir():
+        return f"skip {src.name}: source missing"
+    if dest.exists() or dest.is_symlink():
+        if not force:
+            return f"skip {src.name}: {dest} exists (pass --force)"
+        if dest.is_symlink() or dest.is_file():
+            dest.unlink()
+        else:
+            shutil.rmtree(dest)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        os.symlink(src, dest, target_is_directory=True)
+        return f"link {src.name} -> {dest}"
+    except OSError:
+        shutil.copytree(src, dest)
+        return f"copy {src.name} -> {dest}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Install design-playbook skills for Codex")
+    parser.add_argument(
+        "--dest",
+        type=Path,
+        default=DEFAULT_DEST,
+        help=f"skills directory (default: {DEFAULT_DEST})",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="replace existing skill directories/links",
+    )
+    args = parser.parse_args(argv)
+
+    if not SKILLS_SRC.is_dir():
+        print(f"skills source missing: {SKILLS_SRC}", file=sys.stderr)
+        return 2
+
+    print(f"source: {SKILLS_SRC}")
+    print(f"dest:   {args.dest}")
+    for skill in sorted(p for p in SKILLS_SRC.iterdir() if p.is_dir()):
+        print(" ", install_one(skill, args.dest / skill.name, force=args.force))
+    print("done. Load design-playbook via Codex skills or @ references.")
+    print("MCP: see packages/design-playbook/codex/AGENTS.md")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/commands/doctor.md

@@ -0,0 +1,15 @@
+---
+description: Diagnose installed design-playbook capability and repairs
+---
+
+# doctor
+
+One packaged diagnosis entry for install/runtime capability.
+
+```text
+python <plugin>/scripts/doctor.py
+python <plugin>/scripts/doctor.py --json
+python <plugin>/scripts/doctor.py --run-root .scratch/<run>
+```
+
+Reports `ok` / `degraded` / `broken`. Failed checks include a concrete repair. Optional adapters (Playwright, run-root env) degrade rather than hard-fail the install.

package/commands/run-status.md

@@ -0,0 +1,21 @@
+---
+description: Report Design I/O run phase, blocker, and next resume action
+---
+
+# run-status
+
+Inspect a stopped Design I/O run without reconstructing state from scratch files by hand.
+
+## Usage
+
+```text
+python <plugin>/scripts/run_status.py [.scratch/<run>] [--json] [--list] [--scratch <dir>]
+```
+
+- Omit the run path to pick the newest directory under `--scratch` (default `.scratch/`).
+- `--json` emits machine-readable stages + `next` action.
+- `--list` only lists discovered runs.
+
+## Done when
+
+The command names completed stage markers, any active blocker (preview floor, baseline gate, recirculate verdict), and the single next valid resume action. It reuses `validate_run` judgments for G5 confirm validity rather than inventing a second state machine.

package/design_playbook.py

@@ -0,0 +1,20 @@
+"""Namespace alias: absolute ``design_playbook.*`` imports inside this plugin.
+
+The plugin directory is ``design-playbook`` (hyphen), so Python's import
+system cannot load it under the identifier ``design_playbook`` — FileFinder
+matches directory names literally. This module aliases the package root onto
+``design_playbook.__path__`` so that, once the one bootstrap (ADR-0022) puts
+the package root on ``sys.path``, absolute imports such as
+``design_playbook.mcp.preview.integrity`` and
+``design_playbook.scripts.stages`` resolve to the real ``mcp/`` and
+``scripts/`` trees below.
+
+The alias also keeps the import seam namespaced: a bare ``mcp.*`` import
+would collide with the PyPI ``mcp`` SDK when the host has it installed.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+__path__ = [str(Path(__file__).resolve().parent)]
+__all__: list[str] = []

package/examples/README.md

@@ -0,0 +1,11 @@
+# examples
+
+Self-authored samples for onboarding and dogfood. **Not** ports of any upstream playbook.
+
+| File | Use |
+| --- | --- |
+| [ops-list-spec.md](ops-list-spec.md) | Minimal six-layer spec (ops delivery log) |
+| [settings-decision-report.md](settings-decision-report.md) | ui-picker decision report before code |
+| [point-back-findings.md](point-back-findings.md) | evaluator output shape + recirculate |
+
+Agent-loaded SSOT remains `../skills/*/references/*`. These files are human-facing packs you can paste into a session.

package/examples/craft-detectors/composition-contrast.md

@@ -0,0 +1,16 @@
+# Composition detector contrast cases
+
+Authored worked cases for CRAFT-01 through CRAFT-05. Each case combines a rendered observation with independent source evidence. `Expected` is advisory detector status, not evaluator severity or verdict.
+
+| Case | ID | Expected | Rendered evidence | Source evidence | Exception check | Owner hint | Positive fix |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| competing-actions-hit | CRAFT-01 | hit | Header exposes Create, Import, and Export with equal filled emphasis | All three actions use primary Button variant | Spec names Create as main task; no equal-choice exception | craft | Keep Create primary and group Import/Export as secondary actions |
+| equal-choice-clear | CRAFT-01 | clear | Two plan options receive equal weight in a deliberate comparison | Shared selectable-card primitive applies same selected affordance | Spec requires neutral side-by-side choice before Continue | craft | - |
+| queue-card-wall-hit | CRAFT-02 | hit | Twelve equal cards make status and owner hard to compare | Queue records map directly to Card wrappers | Records are operational rows, not independent browse objects | template | Replace card wall with table/list and stable comparison columns |
+| card-collection-clear | CRAFT-02 | clear | Gallery cards represent independent templates with image, owner, and open action | TemplateCard owns preview and item-level interaction | Browsable independent objects fit card semantics | template | - |
+| nested-panels-hit | CRAFT-03 | hit | Page section floats as a shadowed card containing three more bordered cards | Card wraps section and nested Cards provide spacing only | No modal, tool, or repeated-item semantics justify frames | template | Flatten section, group with spacing/dividers, retain frame only for tool |
+| drawer-tool-clear | CRAFT-03 | clear | Unframed page contains one bounded detail drawer | Drawer primitive owns focus and dismiss behavior; no nested Card | Detail drawer is a genuine framed tool | components | - |
+| blue-everywhere-hit | CRAFT-04 | hit | Canvas, surfaces, actions, charts, and state badges use blue variants | Single blue ramp fills surface, action, success, and selected roles | No verified monochrome baseline or semantic role separation | design | Restore neutral surfaces and assign distinct semantic state roles |
+| semantic-color-clear | CRAFT-04 | clear | Neutral surfaces dominate; cyan marks selection, amber warning, red failure | Tokens map each semantic role independently | Brand accent remains selective and states stay distinguishable | design | - |
+| pill-everything-hit | CRAFT-05 | hit | Tabs, buttons, fields, filters, and section labels all use pill silhouettes | Global radius-full token applies across unrelated controls | No baseline or semantic grouping justifies uniform pill geometry | components | Restore control-specific shapes and reserve pills for compact tags |
+| status-pill-clear | CRAFT-05 | clear | Compact pills appear only for status and removable filter chips | Badge and Chip primitives use pill shape; buttons use restrained radius | Shape communicates status/grouping and is not page-wide | components | - |

package/examples/craft-detectors/existing-brand-contrast.md

@@ -0,0 +1,22 @@
+# Existing-brand baseline contrast
+
+## Verified baseline exception
+
+- Detector: CRAFT-05
+- Generic signal: product uses pill geometry across navigation and compact actions.
+- Rendered evidence: pill silhouette is consistent, sparse, readable, and does not obscure control state.
+- Source evidence: confirmed project radius token and shared primitives apply the geometry consistently.
+- Verified baseline: project `DESIGN.md` explicitly names capsule geometry as a first-party brand convention; binding status is `ready`.
+- Baseline disposition: clear
+- Reason: verified project choice wins generic detector taste.
+
+## Override boundary
+
+- Detector: CRAFT-07
+- Generic signal: dangerous account deletion is represented by an unlabeled trash icon.
+- Rendered evidence: destructive action has no text, consequence, or confirmation cue.
+- Source evidence: IconButton invokes deletion directly without confirmation Dialog.
+- Verified baseline: project uses icon-only toolbars.
+- Override disposition: hit
+- Reason: safety, usability, and explicit dangerous-action declarations override baseline consistency.
+- Positive fix: retain baseline icon treatment for ordinary tools, but use explicit destructive text and confirmation for account deletion.

package/examples/craft-detectors/landing-product-contrast.md

@@ -0,0 +1,12 @@
+# Landing and product detector contrast cases
+
+Authored worked cases for CRAFT-06 through CRAFT-08. Each result is advisory and leaves declaration mapping, severity, and verdict to `ui-evaluator`.
+
+| Case | ID | Expected | Rendered evidence | Source evidence | Exception check | Owner hint | Positive fix |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| dashboard-display-type-hit | CRAFT-06 | hit | Compact metrics panel uses 72px heading that crowds values below | Panel heading references display-hero token | Surface is an operational panel, not a literal hero | design | Use panel title role and preserve hierarchy through grouping and weight |
+| product-hero-clear | CRAFT-06 | clear | Product name leads first viewport while next section remains visible | H1 uses display token within bounded responsive hero | Literal product hero warrants display scale and text fits target viewports | design | - |
+| verbose-toolbar-hit | CRAFT-07 | hit | Toolbar repeats Undo, Redo, Save, Zoom in, and Zoom out as wide text pills | Generic Button renders familiar tool actions despite icon library availability | Actions are familiar and low-risk; accessible icon labels are possible | components | Use icon buttons with accessible names and tooltips; keep text for ambiguous commands |
+| destructive-text-clear | CRAFT-07 | clear | Delete workspace remains an explicit text action with consequence copy | Destructive Button opens confirmation Dialog | High-risk action benefits from explicit language | components | - |
+| looping-decoration-hit | CRAFT-08 | hit | CTA badge bounces continuously without state change | Infinite keyframes animate translateY and ignore reduced-motion | No game or immersive intent is declared | craft | Remove loop and use short transform/opacity feedback only for a named state change |
+| state-transition-clear | CRAFT-08 | clear | Saved indicator fades in after persistence and stays stable | 160ms opacity transition follows saved state and reduced-motion disables it | Motion explains persistence completion | craft | - |

package/examples/craft-detectors/saas-dashboard.md

@@ -0,0 +1,29 @@
+# SaaS dashboard detector contrast
+
+Worked fixture for detector protocol validation. Rendered and source descriptions are independent authored observations, not validator-generated expectations.
+
+## Input
+
+- Rendered surface: desktop operations dashboard at 1440 x 900.
+- Source surface: React page using shared Button, Table, Card, Badge, and motion tokens.
+- Baseline: none.
+
+## Detector ledger
+
+| ID | Status | Rendered evidence | Source evidence | Exception check | Positive fix |
+| --- | --- | --- | --- | --- | --- |
+| CRAFT-01 | hit | Header has three equally filled primary actions | Three Button instances use `variant="primary"` | No equal-choice flow in spec | Keep Create run primary; move Import and Export to secondary/menu actions |
+| CRAFT-02 | hit | Twelve equal cards hide queue comparison | Queue records map directly to Card wrappers | Records are comparable operational rows, not independent browse objects | Use a table/list with stable columns and one framed detail tool |
+| CRAFT-03 | clear | Page bands are unframed; detail drawer alone is framed | Card is not nested and Drawer owns detail | Drawer is a genuine framed tool | - |
+| CRAFT-04 | clear | Neutral surfaces carry most area; amber and red have named state roles | Semantic tokens map warning and failure independently | No monochrome exception needed | - |
+| CRAFT-05 | clear | Pills appear only for status badges | Badge uses pill radius; buttons and inputs use control-specific shape | Status grouping warrants compact pill | - |
+| CRAFT-06 | clear | Panel headings fit dense dashboard hierarchy | Display type token is absent inside panels | No hero context claimed | - |
+| CRAFT-07 | clear | Refresh and close use named icon buttons; destructive action keeps text | IconButton has accessible labels and destructive Button remains explicit | High-risk action needs text | - |
+| CRAFT-08 | blocked | Static capture cannot prove transition purpose or reduced-motion behavior | Motion source was not included in review input | No exception can be checked without source | Provide motion source and interaction trace before complete craft Pass |
+
+## Expected contract observations
+
+- All eight stable IDs appear exactly once.
+- Ledger contains `hit`, `clear`, and `blocked`.
+- Hit rows carry rendered evidence, source evidence, exception check, and positive fix.
+- No row assigns declaration source, severity, or verdict.

package/examples/ops-list-spec.md

@@ -0,0 +1,44 @@
+# Ops delivery log — sample spec.md
+
+Illustrative only. Replace domain terms for your product.
+
+## L1 定位与意图
+
+- 一句话定义：查看某端点的 webhook 投递记录，并对失败项触发重试。
+- 目标用户：集成开发者。
+- 场景：日常排查投递失败；批量重试一段窗口内的失败。
+- 非目标：不在此配置端点密钥；不做全站日志检索。
+- 行为边界：重试 = 询问后；删除投递记录 = 永不（本页）。
+
+## L2 信息架构
+
+- 顶栏：端点选择、时间范围、状态筛选。
+- 主区：投递列表（状态、HTTP、耗时、时间、操作）。
+- 侧/展开：单次请求/响应摘要（默认脱敏）。
+- 批量条：选中失败项后的重试入口。
+
+## L3 核心链路
+
+- pending → delivered
+- pending → failed → retry → pending
+- failed → ignore（仅隐藏于默认筛选，不删数据）
+
+## L4 组件功能细节
+
+- 状态 Badge：pending / delivered / failed。
+- 行操作：查看详情、重试（loading / disabled / error）。
+- 批量重试：二次确认后并行触发，逐行回写结果。
+
+## L5 边界条件
+
+- 空态：该端点暂无投递；说明如何触发一次测试投递。
+- 加载：表结构骨架，不塌布局。
+- 错误：列表拉取失败 → 原因 + 重试；单条重试失败 → 行内错误 + 可再试。
+- 权限：只读角色禁用重试，并说明所需权限。
+
+## L6 验收标准
+
+- Given 一条 failed，When 打开详情，Then 可见状态码/错误摘要且敏感字段脱敏。
+- Given 一条 failed，When 重试成功，Then 行转为 pending 且可刷新到 delivered。
+- Given 无数据，Then 非白屏空态。
+- Given 只读用户，Then 无法触发重试且有原因。

package/examples/point-back-findings.md

@@ -0,0 +1,29 @@
+# Sample point-back findings + recirculate
+
+Illustrative `ui-evaluator` output. Every issue names a declaration.
+
+```text
+issue:    update payment has no confirm step
+source:   domain
+fix:      Dialog with consequence copy before submit
+severity: high
+
+issue:    full card number rendered in form summary
+source:   domain
+fix:      mask to last-4; explicit reveal only if product allows
+severity: high
+
+issue:    empty invoice table is a blank white region
+source:   spec
+fix:      empty state copy + CTA to billing history help
+severity: med
+```
+
+## Recirculate (blocking)
+
+1. Open owning declaration (`domain` / `spec` / …).
+2. Patch only that layer.
+3. Resume pipeline from the step that consumes it (fill or craft).
+4. Re-run evaluator → **Done when** zero high/blocking remain (or each remaining item is explicitly accepted by the user).
+
+Do not whole-page restyle to “clear” blocking findings.

package/examples/reference-intake/README.md

@@ -0,0 +1,11 @@
+# reference-intake examples
+
+Three minimal fixtures for ADR-0011. They are **shape samples**, not live run artifacts.
+
+| Fixture | Source kind | Shows |
+| --- | --- | --- |
+| `screenshot/` | local image | evidence + file sha256 inventory |
+| `url/` | absolute URL | structure notes without shipping third-party chrome |
+| `product-analogy/` | named product taste | Keep/Change/Do not copy without a file |
+
+Real runs write the same filenames under `.scratch/<run>/reference/`.

package/examples/reference-intake/product-analogy/contract.md

@@ -0,0 +1,53 @@
+# Reference contract — product-analogy fixture
+
+## Source summary
+
+- Ask (one line): Agent ops dashboard that feels as scannable as Linear's issue list, but for our agent runs.
+- Sources (ids matching `manifest.json`): src-1 (product analogy)
+- Captured at (ISO-8601; may match `manifest.json` top-level `captured_at`): 2026-07-22T10:10:00+08:00
+
+## Evidence (observed)
+
+- User provided no screenshot; only the product name "Linear" as a taste anchor.
+- Requested qualities in chat: scannable rows, keyboard-friendly, low decoration.
+
+## Inferred (labeled)
+
+- Prefer tight row height and muted meta columns | confidence: medium | why: common Linear-list reading of "scannable"
+- Avoid kanban as default | confidence: medium | why: user said list, not board
+
+## Keep
+
+- Scannable list semantics: identity column + sparse meta + quiet density
+
+## Change
+
+- Domain objects are agent runs, not issues; columns and empty states follow our L2 duties
+- Keyboard map must match our app, not Linear shortcuts
+
+## Do not copy
+
+- Linear wordmark, issue ID format, and any trademarked product chrome
+- Distinctive empty-state illustration or onboarding checklist copy
+
+## Functional constraints for ux-spec
+
+- Goal / scene hints: operator scans agent runs and opens one run detail
+- States or edges implied: empty fleet, filtered-empty, run failure badge
+- Non-goals implied by Do not copy: not a Linear clone; no issue-tracker information architecture
+- always / ask / never hints: always show run state chip; ask before bulk cancel; never use Linear keyboard map as default
+
+## Visual cues for ui-picker
+
+- Density: console-tight
+- Scene class hints: list / agent-admin
+- Region weight / hierarchy: main = run table; side optional filters; status = run state chip
+- Explicit exclusions: marketing hero, board/kanban default
+
+## License / brand risks
+
+- Product analogy only. Do not download or embed Linear brand assets. If a later screenshot is added, re-run reference-intake and tighten Do not copy.
+
+## Unresolved questions
+
+- Which columns are mandatory for v0 agent-run list?

package/examples/reference-intake/product-analogy/manifest.json

@@ -0,0 +1,15 @@
+{
+  "schema": "design-playbook.reference.manifest/v1",
+  "run_id": "fixture-product-analogy",
+  "captured_at": "2026-07-22T10:10:00+08:00",
+  "tool": "reference-intake",
+  "sources": [
+    {
+      "id": "src-1",
+      "kind": "product_analogy",
+      "locator": "Linear (product analogy; no asset)",
+      "sha256": null,
+      "note": "taste anchor only"
+    }
+  ]
+}

package/examples/reference-intake/screenshot/assets/README.md

@@ -0,0 +1 @@
+Fixture placeholder. Real runs store the referenced screenshot bytes here.

package/examples/reference-intake/screenshot/contract.md

@@ -0,0 +1,55 @@
+# Reference contract — screenshot fixture
+
+## Source summary
+
+- Ask (one line): Rebuild the ops alert list so empty/error states match this screenshot's information hierarchy, without copying brand chrome.
+- Sources (ids matching `manifest.json`): src-1 (local screenshot)
+- Captured at (ISO-8601; may match `manifest.json` top-level `captured_at`): 2026-07-22T10:00:00+08:00
+
+## Evidence (observed)
+
+- Dense console list: primary column is alert title; secondary meta is severity + time.
+- Empty state is a centered panel with one primary action, not a blank table body only.
+- Severity uses a compact status chip left of the title, not a colored full-row background.
+
+## Inferred (labeled)
+
+- Operators scan severity before title | confidence: medium | why: chip is left-aligned in the first 80px of each row
+- Empty-state action creates a new alert rule | confidence: low | why: button label not fully legible in the crop
+
+## Keep
+
+- Severity-before-title scan order
+- Empty state with a single primary recovery action
+
+## Change
+
+- Replace third-party product name and iconography with our product voice
+- Map severity chip to our status role tokens, not the reference palette
+
+## Do not copy
+
+- Product logo, wordmark, and distinctive empty-state illustration
+- Exact marketing microcopy on the primary button
+
+## Functional constraints for ux-spec
+
+- Goal / scene hints: operator can triage alerts and recover from empty/error
+- States or edges implied: default list, empty, error reload
+- Non-goals implied by Do not copy: do not reproduce vendor branding or illustration system
+- always / ask / never hints: always show empty recovery action; ask before bulk-dismiss; never auto-delete alerts
+
+## Visual cues for ui-picker
+
+- Density: console-tight
+- Scene class hints: list
+- Region weight / hierarchy: main = table; action = top-right primary; status = per-row chip
+- Explicit exclusions: no marketing hero, no full-row severity paint
+
+## License / brand risks
+
+- Screenshot appears to be a third-party product UI; treat as unlicensed reference only. Do not ship cropped brand assets into Fill or public demos.
+
+## Unresolved questions
+
+- Exact empty-state button label is illegible in the crop; confirm with product owner

package/examples/reference-intake/screenshot/manifest.json

@@ -0,0 +1,15 @@
+{
+  "schema": "design-playbook.reference.manifest/v1",
+  "run_id": "fixture-screenshot",
+  "captured_at": "2026-07-22T10:00:00+08:00",
+  "tool": "reference-intake",
+  "sources": [
+    {
+      "id": "src-1",
+      "kind": "screenshot",
+      "locator": "assets/ops-alert-list.png",
+      "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+      "note": "fixture placeholder hash; real runs must hash the file"
+    }
+  ]
+}

package/examples/reference-intake/url/contract.md

@@ -0,0 +1,55 @@
+# Reference contract — URL fixture
+
+## Source summary
+
+- Ask (one line): Settings page for notification channels; use the linked docs site IA as reference, not as a skin.
+- Sources (ids matching `manifest.json`): src-1 (URL)
+- Captured at (ISO-8601; may match `manifest.json` top-level `captured_at`): 2026-07-22T10:05:00+08:00
+
+## Evidence (observed)
+
+- Left nav groups settings into Account / Notifications / Integrations.
+- Notifications page uses a definition-list of channels with a trailing toggle, not a multi-column form grid.
+- Destructive actions stay outside the per-channel row.
+
+## Inferred (labeled)
+
+- Toggle is optimistic with toast rollback | confidence: low | why: network behavior not visible from static docs page
+- Integrations is out of scope for this ask | confidence: high | why: user named notifications only
+
+## Keep
+
+- Grouped left nav with a single active section highlight
+- Channel rows as label + short description + trailing control
+
+## Change
+
+- Replace docs-site content width with our app shell widths
+- Use our settings template regions instead of docs sidebar chrome
+
+## Do not copy
+
+- Vendor site logo, docs search widget, and marketing CTA footer
+- Exact section titles that are product-trademark phrases
+
+## Functional constraints for ux-spec
+
+- Goal / scene hints: user enables/disables notification channels and understands delivery target
+- States or edges implied: loading channel list, save error, permission denied
+- Non-goals implied by Do not copy: no docs search, no marketing footer, no integrations subtree in this run
+- always / ask / never hints: always show channel delivery target; ask before disabling the last channel; never bury destructive actions in the row
+
+## Visual cues for ui-picker
+
+- Density: console-tight
+- Scene class hints: settings
+- Region weight / hierarchy: side = section nav; main = channel list; action = page-level save if required
+- Explicit exclusions: docs-site header/footer patterns
+
+## License / brand risks
+
+- Public marketing/docs URL is third-party. Capture only structure notes; do not mirror proprietary illustration or trademarked slogans into Fill.
+
+## Unresolved questions
+
+- none

package/examples/reference-intake/url/manifest.json

@@ -0,0 +1,15 @@
+{
+  "schema": "design-playbook.reference.manifest/v1",
+  "run_id": "fixture-url",
+  "captured_at": "2026-07-22T10:05:00+08:00",
+  "tool": "reference-intake",
+  "sources": [
+    {
+      "id": "src-1",
+      "kind": "url",
+      "locator": "https://example.com/docs/settings/notifications",
+      "sha256": null,
+      "note": "example.com placeholder for fixture shape only"
+    }
+  ]
+}