dreamcontext 0.17.1 → 0.18.0

package/skill-packs/catalog.json

@@ -164,7 +164,7 @@
     },
     {
       "name": "council",
-      "description": "Load when the user wants to debate a non-trivial decision, asks for a second opinion, says 'help me decide', 'run this by council', or invokes /council. Orchestrates 3\u201310 persona sub-agents across multiple rounds, then a synthesizer writes a final decision report.",
+      "description": "Load when the user wants to debate a non-trivial decision, asks for a second opinion, says 'help me decide', 'run this by council', or invokes /council. Orchestrates 3–10 persona sub-agents across multiple rounds, then a synthesizer writes a final decision report.",
       "tags": [
         "council",
         "debate",
@@ -223,7 +223,7 @@
     },
     {
       "name": "goal-skill",
-      "description": "Load when the user wants to drive a non-trivial goal to completion under sub-agent orchestration, or invokes /goal-skill. Triggers: 'drive this goal to completion', 'subagent-driven development', 'SDD', 'orchestrate this build', 'run this end-to-end with reviewers'. For multi-step features/fixes too large or risky for a single straight-line pass.",
+      "description": "Load when the user wants to drive a non-trivial goal to completion under sub-agent orchestration, or invokes /goal-skill. Triggers: 'drive this goal to completion', 'subagent-driven development', 'SDD', 'orchestrate this build', 'run this end-to-end with reviewers'. For multi-step features/fixes too large or risky for a single straight-line pass. v2: CLI builder sessions fork once and resume per round, clean fresh judges, a tier router (S/M/L) scales ceremony, and dependency-map waves parallelize implementation.",
       "tags": [
         "goal",
         "orchestration",
@@ -234,7 +234,7 @@
         "validation"
       ],
       "alwaysApply": false,
-      "base": "Subagent-driven goal completion: the main agent orchestrates plan -> plan-review -> task-doc -> implement -> code-review -> validate, iterating each gate (cap 3, then escalate) until validation passes against user-agreed criteria. Reuses the engineering reviewer for code review and the dreamcontext task system as the working doc.",
+      "base": "Subagent-driven goal completion: builders (planner, implementers) run as CLI sessions that fork once and resume per round, while judges (plan-reviewers, code reviewer, validator) stay clean and fresh each round, meeting the work only through the task doc. A tier router (S/M/L, with a hot-path override for auth/crypto/env/migrations) scales ceremony to goal size; a dependency-map table drives wave-parallel implementation; loops iterate to convergence by signal (new findings resume the builder, repeated findings trigger one re-fork, then escalate) rather than a fixed iteration count, until validation passes against user-agreed criteria. Reuses the engineering reviewer for code review and the dreamcontext task system as the working doc.",
       "subSkills": [],
       "relatedAgents": [
         "goal-planner",
@@ -245,6 +245,16 @@
       ],
       "crossPackDeps": [
         "engineering (planner/implementer/reviewer load engineering standards)"
+      ],
+      "assets": [
+        {
+          "file": "assets/goal-skill-viewer.cjs",
+          "dest": "goal-skill-viewer.cjs"
+        },
+        {
+          "file": "assets/goal-skill-demo.cjs",
+          "dest": "goal-skill-demo.cjs"
+        }
       ]
     }
   ],
@@ -338,7 +348,7 @@
         "marketing-monitor",
         "marketing-creative"
       ],
-      "corpus_status": "9 videos \u00b7 4 speakers \u00b7 draft \u00b7 agent roster: 2 active (strategy, monitor) + 1 stubbed (creative)"
+      "corpus_status": "9 videos · 4 speakers · draft · agent roster: 2 active (strategy, monitor) + 1 stubbed (creative)"
     },
     {
       "name": "system-prompts",
@@ -356,7 +366,7 @@
     {
       "name": "excalidraw",
       "file": "excalidraw/SKILL.md",
-      "description": "Generate or extend Obsidian Excalidraw (.excalidraw.md) boards — lay out images/screenshots, text, shapes, arrows, frames, lanes and grids — by writing a small JSON spec and running a deterministic script that emits valid plugin markup (near-zero tokens, always renders). Embeds local images via the plugin's sha1 wikilink trick (no base64). Triggers: 'draw this in excalidraw', 'make an excalidraw board', 'excalidraw diagram', 'funnel map board', 'embed screenshots into excalidraw', 'excalidraw çiz', 'excalidraw board oluştur'.",
+      "description": "Generate or extend Obsidian Excalidraw (.excalidraw.md) boards — charts (line/bar/compare/stacked/gantt/quadrant/donut/heatmap/table/timeline/KPI/sparkline), funnels, wireframes and real-proportion device mockups (iPhone/iPad/Mac), flowcharts, images/screenshots, shapes, arrows, frames, lanes and grids — by passing DATA to ~44 ready-made deterministic builders that emit valid plugin markup (near-zero tokens, always renders). Every builder works from JS or straight from a JSON spec; the build audits the scene for overlaps, buried labels and over-long lines. Embeds local images via the plugin's sha1 wikilink trick (no base64). Triggers: 'draw this in excalidraw', 'make an excalidraw board', 'excalidraw diagram', 'chart', 'gantt', 'funnel map board', 'wireframe', 'iphone mockup', 'embed screenshots into excalidraw', 'excalidraw çiz', 'excalidraw board oluştur', 'grafik çiz', 'wireframe çiz'.",
       "tags": [
         "excalidraw",
         "obsidian",
@@ -453,7 +463,7 @@
       "name": "marketing-strategy",
       "file": "agents/marketing-strategy.md",
       "pack": "meta-marketing",
-      "description": "Strategy Optimizer for Meta ads \u2014 plans cohort hypotheses (shape-validated), drafts campaign briefs grounded in the meta-marketing skill-pack corpus, always asks for budget, never launches.",
+      "description": "Strategy Optimizer for Meta ads — plans cohort hypotheses (shape-validated), drafts campaign briefs grounded in the meta-marketing skill-pack corpus, always asks for budget, never launches.",
       "tags": [
         "meta",
         "ads",
@@ -468,7 +478,7 @@
       "name": "marketing-monitor",
       "file": "agents/marketing-monitor.md",
       "pack": "meta-marketing",
-      "description": "Performance Monitor for live Meta campaigns \u2014 reads insights, applies post-launch rules from account-ops.md \u00a74, writes hypothesis-ledger entries to per-day learnings, recommends moves but never auto-mutates.",
+      "description": "Performance Monitor for live Meta campaigns — reads insights, applies post-launch rules from account-ops.md §4, writes hypothesis-ledger entries to per-day learnings, recommends moves but never auto-mutates.",
       "tags": [
         "meta",
         "ads",
@@ -482,7 +492,7 @@
       "name": "marketing-creative",
       "file": "agents/marketing-creative.md",
       "pack": "meta-marketing",
-      "description": "Creative Director for Meta ads \u2014 STUBBED in v0. Refuses all requests until marketing.creative_director.enabled = true. v1 will merge brainstorming + copy + asset generation.",
+      "description": "Creative Director for Meta ads — STUBBED in v0. Refuses all requests until marketing.creative_director.enabled = true. v1 will merge brainstorming + copy + asset generation.",
       "tags": [
         "meta",
         "ads",
@@ -509,7 +519,7 @@
       "name": "review-security",
       "file": "agents/review-security.md",
       "pack": "multi-review",
-      "description": "Security specialist in the multi-review team. Reviews ONLY for security defects \u2014 exploitable vulnerabilities, secret leakage, auth/authz gaps, injection, SSRF/CSRF/XSS, env-var exposure, weak crypto, insecure deserialization. Outputs a bounded greptile-style report.",
+      "description": "Security specialist in the multi-review team. Reviews ONLY for security defects — exploitable vulnerabilities, secret leakage, auth/authz gaps, injection, SSRF/CSRF/XSS, env-var exposure, weak crypto, insecure deserialization. Outputs a bounded greptile-style report.",
       "tags": [
         "review",
         "security",
@@ -523,7 +533,7 @@
       "name": "review-cloud-functions",
       "file": "agents/review-cloud-functions.md",
       "pack": "multi-review",
-      "description": "Cloud Functions specialist in the multi-review team. Reviews ONLY Firebase Cloud Functions and serverless function changes \u2014 idempotency, infinite-loop risk, scaling/concurrency, cold-start cost, retry semantics, secrets handling, unbounded fan-out, billing footguns, trigger-loop hazards.",
+      "description": "Cloud Functions specialist in the multi-review team. Reviews ONLY Firebase Cloud Functions and serverless function changes — idempotency, infinite-loop risk, scaling/concurrency, cold-start cost, retry semantics, secrets handling, unbounded fan-out, billing footguns, trigger-loop hazards.",
       "tags": [
         "review",
         "cloud-functions",
@@ -537,7 +547,7 @@
       "name": "review-frontend",
       "file": "agents/review-frontend.md",
       "pack": "multi-review",
-      "description": "Frontend specialist in the multi-review team. Reviews ONLY frontend changes (React/Vue/Svelte/Next/web components/CSS) \u2014 file-size scalability, hook correctness, accessibility, bundle bloat, render perf, state management, design-token discipline, i18n, and frontend-specific security (XSS sinks, token storage).",
+      "description": "Frontend specialist in the multi-review team. Reviews ONLY frontend changes (React/Vue/Svelte/Next/web components/CSS) — file-size scalability, hook correctness, accessibility, bundle bloat, render perf, state management, design-token discipline, i18n, and frontend-specific security (XSS sinks, token storage).",
       "tags": [
         "review",
         "frontend",
@@ -551,7 +561,7 @@
       "name": "review-edge-cases",
       "file": "agents/review-edge-cases.md",
       "pack": "multi-review",
-      "description": "Edge-case and production-risk specialist in the multi-review team. The paranoid one. Enumerates failure modes the other specialists don't own \u2014 empty/null/undefined inputs, off-by-one, concurrency, partial successes, retries, network failures, clock skew, timezone bugs, locale assumptions, state machine gaps, error swallowing. Always included for tier >= Lite.",
+      "description": "Edge-case and production-risk specialist in the multi-review team. The paranoid one. Enumerates failure modes the other specialists don't own — empty/null/undefined inputs, off-by-one, concurrency, partial successes, retries, network failures, clock skew, timezone bugs, locale assumptions, state machine gaps, error swallowing. Always included for tier >= Lite.",
       "tags": [
         "review",
         "edge-cases",
@@ -565,7 +575,7 @@
       "name": "biv-researcher",
       "file": "agents/biv-researcher.md",
       "pack": "business-idea-validation",
-      "description": "Research specialist for BIV pipeline. Executes Stage 1 (Problem Discovery \u2014 Reddit mining, forum analysis, Google Trends) and Stage 4 (Competitive Intelligence \u2014 competitor dossiers, gap analysis, 2x2 matrix). Heavy web research.",
+      "description": "Research specialist for BIV pipeline. Executes Stage 1 (Problem Discovery — Reddit mining, forum analysis, Google Trends) and Stage 4 (Competitive Intelligence — competitor dossiers, gap analysis, 2x2 matrix). Heavy web research.",
       "tags": [
         "biv",
         "research",
@@ -579,7 +589,7 @@
       "name": "biv-customer-analyst",
       "file": "agents/biv-customer-analyst.md",
       "pack": "business-idea-validation",
-      "description": "Customer analysis specialist for BIV pipeline. Executes Stage 2 (Customer Analysis \u2014 segmentation, personas, beachhead selection) and Stage 5 (AI-simulated Customer Validation from forum data).",
+      "description": "Customer analysis specialist for BIV pipeline. Executes Stage 2 (Customer Analysis — segmentation, personas, beachhead selection) and Stage 5 (AI-simulated Customer Validation from forum data).",
       "tags": [
         "biv",
         "customer",
@@ -593,7 +603,7 @@
       "name": "biv-market-analyst",
       "file": "agents/biv-market-analyst.md",
       "pack": "business-idea-validation",
-      "description": "Market sizing specialist for BIV pipeline. Executes Stage 3 (Market Sizing \u2014 TAM/SAM/SOM via top-down and bottom-up analysis, ambition-level gating).",
+      "description": "Market sizing specialist for BIV pipeline. Executes Stage 3 (Market Sizing — TAM/SAM/SOM via top-down and bottom-up analysis, ambition-level gating).",
       "tags": [
         "biv",
         "market",
@@ -608,7 +618,7 @@
       "name": "biv-strategist",
       "file": "agents/biv-strategist.md",
       "pack": "business-idea-validation",
-      "description": "Strategy specialist for BIV pipeline. Executes Stage 6 (Synthesis & Hypothesis \u2014 opportunity snapshot, riskiest assumptions, testable hypothesis, RICE features), Stage 7 (GTM Strategy \u2014 channels, messaging, first-100-users plan), and optional Lean Canvas capstone.",
+      "description": "Strategy specialist for BIV pipeline. Executes Stage 6 (Synthesis & Hypothesis — opportunity snapshot, riskiest assumptions, testable hypothesis, RICE features), Stage 7 (GTM Strategy — channels, messaging, first-100-users plan), and optional Lean Canvas capstone.",
       "tags": [
         "biv",
         "strategy",
@@ -622,7 +632,7 @@
       "name": "biv-financial-analyst",
       "file": "agents/biv-financial-analyst.md",
       "pack": "business-idea-validation",
-      "description": "Financial viability specialist for BIV pipeline. Executes Stage 8 (Year 1 P&L, unit economics \u2014 CAC/LTV/LTV:CAC, sensitivity analysis, Year 2 outlook).",
+      "description": "Financial viability specialist for BIV pipeline. Executes Stage 8 (Year 1 P&L, unit economics — CAC/LTV/LTV:CAC, sensitivity analysis, Year 2 outlook).",
       "tags": [
         "biv",
         "financial",
@@ -636,7 +646,7 @@
       "name": "biv-decision-gate",
       "file": "agents/biv-decision-gate.md",
       "pack": "business-idea-validation",
-      "description": "Final decision specialist for BIV pipeline. Executes Stage 9 (Go/No-Go \u2014 scores 8 dimensions across Desirability/Feasibility/Viability, applies risk penalties, produces verdict: GO/PIVOT/NO-GO with specific next steps).",
+      "description": "Final decision specialist for BIV pipeline. Executes Stage 9 (Go/No-Go — scores 8 dimensions across Desirability/Feasibility/Viability, applies risk penalties, produces verdict: GO/PIVOT/NO-GO with specific next steps).",
       "tags": [
         "biv",
         "decision",
@@ -649,7 +659,7 @@
       "name": "goal-planner",
       "file": "agents/goal-planner.md",
       "pack": "goal-skill",
-      "description": "Planning specialist for goal-skill. Produces a rigorous file-by-file implementation plan by reading the codebase + dreamcontext context. Does not write code or the task doc. Dispatched at Phase 1.",
+      "description": "Planning specialist for goal-skill. Runs as a CLI builder session (fork once, resume per revision round) and produces a rigorous file-by-file plan plus a dependency-map table (task/files owned/depends on/wave/contract) by reading the codebase + dreamcontext context, thinking xhigh. Does not write code or the task doc. Dispatched at Phase 1.",
       "tags": [
         "goal",
         "planning",
@@ -662,7 +672,7 @@
       "name": "goal-plan-reviewer",
       "file": "agents/goal-plan-reviewer.md",
       "pack": "goal-skill",
-      "description": "Plan reviewer for goal-skill. Critiques a prose plan (pre-code) from one lens (pragmatist/critic/security) and returns SOLID or NEEDS_WORK with blocking findings. Distinct from the code reviewer. Dispatched in parallel at Phase 2.",
+      "description": "Plan reviewer for goal-skill. Dispatched clean and fresh every round, fed only the plan text from the task doc (never the planner's session), and critiques it from one lens (pragmatist/critic/security), returning SOLID or NEEDS_WORK with blocking findings. Distinct from the code reviewer. Dispatched in parallel at Phase 2.",
       "tags": [
         "goal",
         "plan-review",
@@ -675,7 +685,7 @@
       "name": "goal-implementer",
       "file": "agents/goal-implementer.md",
       "pack": "goal-skill",
-      "description": "Implementation specialist for goal-skill. Builds strictly to a validated task's acceptance criteria, logs progress, does not expand scope, stops+reports if the plan is wrong. Dispatched at Phase 4.",
+      "description": "Implementation specialist for goal-skill. Forked from the planner's CLI session for exactly one task/lane of the dependency map, thinking high; builds strictly to that lane's owned files and the validated task's acceptance criteria, logs progress, does not expand scope or edit the dependency map, and stops+reports if the plan is wrong. Dispatched per wave at Phase 4 (fork once, resume per fix).",
       "tags": [
         "goal",
         "implementation",

package/skill-packs/excalidraw/SKILL.md

@@ -1,13 +1,22 @@
 ---
 name: excalidraw
 description: >-
-  Generate or extend Obsidian Excalidraw (.excalidraw.md) boards in this vault — lay out
-  images/screenshots, text labels, shapes, arrows, frames, lanes and grids — by writing a small
-  JSON spec and letting a deterministic script emit valid plugin markup (so it costs ~no tokens and
-  always renders). Embeds local images via the plugin's sha1 wikilink trick (no base64). Triggers:
-  '/excalidraw', 'draw this in excalidraw', 'make an excalidraw board', 'excalidraw diagram',
-  'funnel map board', 'embed screenshots into excalidraw', 'add images to an excalidraw file',
-  'excalidraw çiz', 'excalidraw board oluştur', 'ekran görüntülerini excalidraw a ekle'.
+  Generate or extend Obsidian Excalidraw (.excalidraw.md) boards in this vault — visual-first diagrams,
+  charts (line/bar/comparison/stacked/gantt/quadrant/donut/heatmap/table/timeline/KPI/sparkline),
+  funnels, device mockups (iPhone/iPad/Mac) and wireframes/prototypes, flowcharts, image/screenshot
+  layouts, shapes, arrows, frames, lanes and grids — by passing DATA to ~44 ready-made deterministic
+  builders and letting a script emit valid plugin markup (so it costs ~no tokens and always renders).
+  Every builder works from JS or straight from a JSON spec. Text wraps to a readable measure; the build
+  audits the scene for overlaps, buried labels and over-long lines. Embeds local images via the plugin's
+  sha1 wikilink trick (no base64). Triggers: '/excalidraw', 'draw this in excalidraw', 'make an
+  excalidraw board', 'excalidraw diagram', 'chart', 'line chart', 'bar chart', 'compare before/after',
+  'gantt', 'timeline', 'quadrant', 'impact effort matrix', 'heatmap', 'KPI tiles', 'dashboard board',
+  'funnel', 'conversion funnel', 'wireframe', 'prototype', 'mockup', 'app/web screen mockup', 'iphone
+  mockup', 'ipad mockup', 'mac app mockup', 'ui kit', 'icon button', 'funnel map board', 'embed
+  screenshots into excalidraw', 'add images to an excalidraw file', 'excalidraw çiz', 'excalidraw board
+  oluştur', 'grafik çiz', 'çizgi grafik', 'bar grafik', 'karşılaştırma grafiği', 'zaman çizelgesi',
+  'funnel çiz', 'wireframe çiz', 'prototip çiz', 'iphone ekranı çiz', 'ekran tasarımı çiz', 'ekran
+  görüntülerini excalidraw a ekle'.
 ---
 
 # Excalidraw board generator (Obsidian)
@@ -17,6 +26,37 @@ Write `.excalidraw.md` files that render natively in this vault's Obsidian Excal
 frontmatter, `## Text Elements`, `## Embedded Files`, and the `%% ## Drawing … %%` JSON, with
 correct sha1 image links, fractional z-indices, and deterministic seeds (clean git diffs).
 
+## Design principles (read first)
+
+Excalidraw's strength is **pictures, not paragraphs**. Four rules keep a board clean, readable, and
+visually rich — the primitives below enforce them, so lean on them instead of placing raw text/shapes:
+
+1. **Use a primitive; don't hand-roll one.** There are ~44 ready builders (charts, house style,
+   devices/UI) covering most of what a board needs — pass DATA, get correct geometry. This is the rule
+   the other three depend on: hand-rolled composites are where boards break. Reach for `charts.js` /
+   `wireframe.js` / `style.js` **before** writing rects + text yourself, and only drop to raw elements
+   when nothing fits. Every builder is also a spec JSON `type`, so a whole board can be pure JSON.
+2. **Visual-first.** Explain complex things with *structure you can see*: a `funnel()` of trapezoid
+   bands, a `device()` of the actual screen, a `lineChart()` of the trend, a `hub()`/flow of `card()`s.
+   Reach for a picture before a sentence. When you must write, keep it to labels and short notes.
+3. **Readable measure — text never runs edge-to-edge.** Every text primitive wraps to a bounded width
+   (`READ_W ≈ 620px`, ~60 chars). Use `prose()` for body copy, `bullets()` for lists, `callout()` for
+   titled notes, `sectionTitle()` for headers — they cap + wrap for you. A raw `text` element **must**
+   carry a `width` (it then wraps and the newlines are baked in, so it renders at that measure). Long
+   unbounded text is the #1 readability killer, and the build now **enforces** this (`longLines`).
+4. **No overlap — flow the layout, don't hand-place.** Build with `stack()` (top-to-bottom) and `row()`
+   (left-to-right): each block is placed after the previous one's *measured* size, so boxes can't
+   collide. Every build audits the finished scene and reports
+   `overlaps=N buriedText=N longLines=N` — any non-zero count is a real defect (see **Layout rules**).
+
+Everything downstream (the primitives, the auditors, the wrap-baking) exists to make these four cheap.
+
+> **A clean audit is necessary, not sufficient — render the board and LOOK at it.** This is not a
+> platitude: in practice most defects that reach a finished board are ones the audit cannot see —
+> a mis-scaled axis, an axis caption wrapping one glyph per line, a sentence torn across a gap,
+> content escaping a device bezel, a row label silently truncated. The audit catches geometry it can
+> measure; your eyes catch the rest. See **Verify** for the headless render command.
+
 ## The one trick that makes images work
 An image element references `fileId` = **sha1 of the image file**. The `## Embedded Files` section
 maps `<sha1>: [[image.png]]`. The plugin resolves the picture from the vault via that wikilink —
@@ -28,7 +68,10 @@ maps `<sha1>: [[image.png]]`. The plugin resolves the picture from the vault via
 ```bash
 node .claude/skills/excalidraw/scripts/build_excalidraw.js <spec.json> [--out <path.excalidraw.md>]
 ```
-Write a spec JSON, then run it. The script prints `elements/images/texts` counts on success.
+Write a spec JSON, then run it. On success it prints
+`elements=… images=… texts=… overlaps=… buriedText=… longLines=…` — the last three must all be **0**.
+A spec element's `type` may be a primitive OR any of the ~44 composites (charts, house style, devices,
+`stack`/`row`), so a whole board can be pure JSON with no generator script.
 
 ### JS API (for pipelines that generate many boards)
 ```js
@@ -120,6 +163,14 @@ Key conventions:
   "attachDir": "Attachments",                 // external images get copied here (relative to board dir)
   "wikilinkMode": "basename",                 // "basename" (default) or "path" (vault-relative)
   "background": "#ffffff",
+
+  // frontmatter — REQUIRED for a board that lives in knowledge/ (dreamcontext indexes name +
+  // description + tags; without them the board is effectively unrecallable). Omit for scratch boards.
+  "name": "recall-engine-v2",
+  "description": "One paragraph on what this board visualises. Long prose is fine — it is emitted as a folded YAML block.",
+  "tags": ["architecture", "excalidraw"],
+  "frontmatter": { "any-extra-key": "value" },   // optional passthrough
+
   "elements": [ /* ElementSpec… */ ]
 }
 ```
@@ -128,6 +179,11 @@ Key conventions:
 hardcode absolute paths. This keeps the generator portable: move the folder and it still runs.
 
 ### Element types
+A `type` is either a **primitive** (below) or any **composite** — every chart (`lineChart`, `barCompare`,
+`gantt`, `quadrant`, `heatmap`, `table`, `kpi`, `callout`, …), house-style widget (`card`, `funnel`,
+`windowFrame`, `chip`, …) or layout (`stack`, `row`, which nest via `items`). Composites expand to
+primitives before the build, so the JSON surface is as capable as the JS API. See **Charts** below.
+
 - `text`     — `{ x, y, text, fontSize?, color?, width?, align?, fontFamily? }` (fontFamily 1=hand, 2=normal, 3=code). **Set `width` for any caption/label that must stay inside a column or card** → the text WRAPS to that width (autoResize off) and its height is computed from the wrapped line count. Omit `width` only for short single-line text you want sized to content (it renders on one line and will overlap neighbours if long).
 - `image`    — `{ x, y, path, width? , height? }` — give ONE of width/height; the other is derived from aspect. `path` is an absolute file path.
 - `rectangle`/`ellipse`/`diamond` — `{ x, y, width, height, strokeColor?, backgroundColor?, fillStyle?(solid|hachure|cross-hatch), strokeWidth?, roundness?(true=rounded) }`
@@ -179,11 +235,162 @@ Match the team's look by default. The builder now defaults text to **Excalifont
 - **`bullets({x,y,items})`** → one left-aligned bulleted text block (their spec-list pattern).
 - Edge helpers `center/rightOf/leftOf/topOf/bottomOf(x,y,w,h)` to wire connectors to card edges.
 
-Compose these into a `buildExcalidraw({ out, elements })` call. Runnable example: `examples/style_board.js`.
+### Readable text + flow layout (use these, don't hand-place)
+Every builder below returns an `ElementSpec[]` that also carries `.x/.y/.w/.h/.nextX/.nextY`, so the
+layout helpers can measure and place blocks for you — no coordinate math, no overlap.
+- **`prose({x,y,text,fontSize,width})`** → a wrapped paragraph. `width` defaults to `READ_W` (~60 chars);
+  text can never exceed it. This is THE body-copy primitive. Height is derived from the wrapped lines.
+- **`bullets({x,y,items,width})`** → left-aligned list; each item wraps to `width` with a hanging indent.
+- **`sectionTitle({x,y,text,fontSize,maxWidth})`** → big header; long titles wrap to `maxWidth`.
+- **`stack({x,y,gap,items})`** → flow blocks TOP-TO-BOTTOM. Each item is a factory `(x,y)=>els` (draws
+  itself at the running cursor) or a pre-built `els` array (gets shifted down). Returns `.nextY`.
+- **`row({x,y,gap,valign,items})`** → flow blocks LEFT-TO-RIGHT (same contract). Returns `.nextX`.
+- `READ_W` / `NOTE_W` are the exported reading measures; `translate(els,dx,dy)` / `bbox(els)` are the
+  low-level helpers the layout uses.
+
+## Charts (`scripts/lib/charts.js`) — data in, correct geometry out
+
+**Never hand-roll a chart from rects + text.** These builders own the axes, scales, wrapping, label
+thinning and collision-avoidance; you supply DATA only. Same contract as `style.js` (return an
+`ElementSpec[]` carrying `.x/.y/.w/.h/.nextY`), so they drop straight into `stack()`/`row()`. Nothing
+is random or time-dependent — same input ⇒ same bytes. Each chart is **grouped**, so it moves as one
+unit and the auditors treat its internals as intentional.
+
+| builder | use it for |
+|---|---|
+| **`lineChart({series,xLabels,area,markers})`** | trend over time — DAU, spend, error rate. `series[].points` is a `number[]` aligned to `xLabels` (or `[{x,y}]` for irregular spacing) |
+| **`barChart({bars,horizontal})`** | one value per category. `horizontal:true` when labels are long — they get their own gutter instead of being crammed under vertical bars |
+| **`barCompare({groups,seriesLabels})`** | the "did it move?" chart — same categories across 2+ scenarios (W1↔W2, before/after, plan/actual) |
+| **`stackedBar({groups,seriesLabels})`** | composition per category (revenue by plan, traffic by source); segments stack to each group's total |
+| **`gantt({tasks,today})`** | timeline bars over a date axis. `start`/`end` take `'YYYY-MM-DD'`; `done:0..1` overlays progress; `milestone:true` draws a diamond |
+| **`quadrant({items,xAxis,yAxis,quadrantLabels})`** | 2×2 positioning map (impact×effort, RICE). `items[]` carry `{label,x,y}` in 0..1; top-right is tinted as the "go" quadrant |
+| **`donut({slices,inner})`** / **`pie`** | composition of a whole. Keep to ≤ ~6 slices — beyond that `barChart` reads better |
+| **`sparkline({points})`** | a tiny trend with no axes, for inside a KPI tile or table cell. A glyph, not a chart |
+| **`heatmap({rows,cols,values})`** | matrix of intensities (cohort×day retention). Cell tint interpolates, and the label flips to white on dark cells |
+| **`table({headers,rows,align})`** | a real grid — column widths derive from content, so cells never spill. A cell may be `{text,color}` |
+| **`timeline({events})`** | milestones on a track; labels alternate above/below so they can't collide |
+| **`kpi({label,value,delta,spark})`** | the metric tile: three type sizes for hierarchy, optional sparkline footer |
+| **`callout({title,text,sideTitle})`** | a titled note band. Body copy is **always** bounded to `READ_W`; a wide band puts its heading *beside* the text rather than stretching one line |
+
+**`w` is a MAXIMUM, not a target.** `callout()` sizes itself to its own wrapped text — hand it 1080px for
+620px of copy and it returns ~780px, not a band with 27% dead space. The title gutter hugs the title too.
+That is what makes a primitive atomic: the caller says *at most this wide*, the builder works out the rest.
+Pin `titleW` only to align the gutters of several stacked callouts; pass `fit: false` for a deliberate
+full-width band. `prose()` already hugs the same way. (`card()`/`kpi()` stay caller-sized on purpose —
+a row of tiles should be uniform.)
+
+Helpers for custom charts: `linScale`, `niceScale`, `fmtNum`, `plotFrame`, `chartHead`, `xTickLabels`.
+
+**Never split short copy into newspaper columns.** A 1–2 line "column" reads as a sentence torn across
+a gap — worse than a long line. `callout()` handles this for you.
+
+### Declarative charts — any composite works as a spec `type`
+Every chart and house-style widget is also a **spec JSON element type**, expanded to primitives before
+the build. An agent can draw a whole board without writing a generator — `stack`/`row` nest as JSON too:
+```jsonc
+{ "out": "./Board.excalidraw.md", "elements": [
+  { "type": "stack", "x": 40, "y": 40, "gap": 40, "items": [
+    { "type": "sectionTitle", "text": "Weekly review", "fontSize": 34 },
+    { "type": "row", "gap": 24, "items": [
+      { "type": "kpi", "w": 260, "label": "D0 ROAS", "value": "0.25", "delta": "flat", "color": "red" },
+      { "type": "lineChart", "w": 620, "h": 300, "xLabels": ["3","5","7"],
+        "series": [{ "label": "DAU", "color": "blue", "points": [58, 69, 32] }] }
+    ]}
+  ]}
+]}
+```
+Reach for the JS API instead when you need loops, data mapping, or many boards from one data set.
+Runnable: `node examples/chart_board.js` (every builder) · `node scripts/build_excalidraw.js examples/chart.spec.json` (pure JSON).
+
+### Funnel
+- **`funnel({x,y,w,stageH,stages,topW,botW})`** → a conversion/marketing funnel: filled trapezoid bands
+  narrowing top→bottom, one per `stages[]` entry `{ label, note?, color? }`. Labels auto-fit; an optional
+  `note` (a metric / drop-off) is placed in the right margin with a short non-crossing connector. Colors
+  cycle through the semantic palette unless you set `color`. Returns `.nextY`.
+
+## Devices + product UI (`scripts/lib/wireframe.js`) — sketch a real screen
+
+For **app/product** wireframes. One require gives the whole UI kit (it re-exports style.js's wireframe
+bits too). Every builder is also a spec JSON `type`.
+
+- **`device({kind,x,y,w?,label?,dark?,content?})`** → a device shell at **real proportions**
+  (`iphone` 393×852 · `ipad` 834×1194 · `mac` 1440×900), with status bar, dynamic island / camera /
+  notch, home indicator, Mac menu bar + laptop foot. Returns **`.inner`** — the safe content region
+  (inside the bezel, below the island, above the home indicator) — and `.screen`.
+  **Pass `content: (inner) => els`**: it's the only place overflow can be caught. The build audit is
+  blind here — a device shell is a filled polygon and `isOpaqueBox()` only knows rect/ellipse/diamond/
+  image — so a hardcoded child width silently renders *outside the bezel*. `content` warns instead.
+- **`appBar({title,back,actions})`** · **`tabBar({items,active})`** — mobile top/bottom chrome.
+- **`icon({name,size})`** — 31 line-drawn glyphs. `iconNames()` lists them; an unknown name draws a
+  box so a typo is visible rather than silently absent.
+- **`iconButton({icon,shape,variant,color})`** — `shape`: circle/square/rounded · `variant`: solid/outline/ghost.
+- **`listRow({title,subtitle,leading,trailing})`** — `leading` an icon name or `'avatar'`; `trailing`
+  an icon name, `'toggle'`, or text.
+- **`toggle({on})`** · **`segmented({items,active})`** · **`slider({value})`** · **`searchField({placeholder})`**
+- Plus the generic bits: `windowFrame` (browser/app chrome), `navbar`, `button`, `input`, `textRows`,
+  `imagePlaceholder`, `avatar`, `chip`, `divider`.
+
+```js
+const { device, appBar, tabBar, listRow } = require('.../lib/wireframe.js');
+P(device({ kind: 'iphone', x: 60, y: 80, label: 'Ayarlar', content: (inner) => stack({
+  x: inner.x, y: inner.y, gap: 0, items: [
+    (x, y) => appBar({ x, y, w: inner.w, title: 'Ayarlar', back: true }),
+    (x, y) => listRow({ x, y, w: inner.w, leading: 'bell', title: 'Bildirimler', trailing: 'toggle' }),
+  ],
+})}));
+```
+Runnable: `node examples/wireframe_board.js` — three devices, every control, the full icon set.
+
+**Corner radius gotcha**: `roundness:true` maps to Excalidraw's ADAPTIVE_RADIUS, capped at ~32px —
+too tight for a phone (an iPhone's is ~14% of its width). Device shells are therefore filled
+**polygons** with exact arc corners (`roundRect()` is exported if you need the same trick).
+
+### Generic UI bits (grayscale — sketch a UI, not decoration)
+These live in `style.js` and are re-exported by `wireframe.js`, so `require` either one. Use them
+inside a `device()` for an app screen, or a `windowFrame()` for a web page.
+- **`windowFrame({x,y,w,h,kind,url,title})`** → a browser (`kind:'browser'`, draws a URL bar) or app
+  (`kind:'app'`, centered title) window with traffic-light chrome. **Returns `.inner = {x,y,w,h}`** — the
+  safe content region; place children there (via `stack`/`row`) and they won't hit the chrome.
+  For an **iPhone/iPad/Mac** shell with real proportions, use `device()` above instead.
+- **`navbar({x,y,w,brand,items,cta})`** → top nav: brand left, links right, optional CTA button.
+- **`button({x,y,w,h,text,color,variant})`** → solid CTA (default) or `variant:'outline'`.
+- **`input({x,y,w,h,placeholder,label})`** → a form field with a muted placeholder + optional label.
+- **`textRows({x,y,w,rows})`** → grey bars standing in for body copy — VISUAL filler, no real text. Use
+  these instead of lorem ipsum so a wireframe never becomes a wall of text.
+- **`imagePlaceholder({x,y,w,h,label})`** → the universal box-with-an-X where a screenshot would go.
+- **`avatar({cx,cy,r})`** → round user placeholder. **`chip({x,y,text,color})`** → a pill/tag/badge.
+  **`divider({x,y,w})`** → a thin rule.
+
 Conventions: color nodes by ROLE, label every arrow, put specs in side-annotations, use big plain
-section titles to break the board into "slides", keep one idea per card.
+section titles to break the board into "slides", keep one idea per card, and **prefer a picture to a
+paragraph**.
+
+### Which lib?
+| file | owns | reach for it when |
+|---|---|---|
+| `lib/style.js` | house style + layout: `card`, `node`, `connector`, `hub`, `column`, `funnel`, `prose`, `bullets`, `sectionTitle`, `chip`, `divider`, **`stack`/`row`**, `READ_W`, `measureText`, `wrapToWidth`, `fitText` | diagrams, flows, any board's skeleton |
+| `lib/charts.js` | data viz + copy: `lineChart`, `barChart`, `barCompare`, `stackedBar`, `gantt`, `quadrant`, `donut`/`pie`, `sparkline`, `heatmap`, `table`, `timeline`, `kpi`, `callout` | anything with numbers |
+| `lib/wireframe.js` | product UI: `device`, `appBar`, `tabBar`, `icon`, `iconButton`, `listRow`, `toggle`, `segmented`, `slider`, `searchField` (+ re-exports style.js's UI bits) | app/screen mockups |
+
+All three share one contract — an `ElementSpec[]` carrying `.x/.y/.w/.h/.nextX/.nextY` — so anything
+composes inside `stack()`/`row()`, and everything is also a spec JSON `type`.
 
 ### Layout rules that keep boards clean
+- **Flow the layout with `stack()` / `row()`; never eyeball coordinates for a column or a grid.** They
+  place each block after the previous one's measured size, so nothing overlaps by construction. Reserve
+  hand-picked `x/y` for a handful of top-level anchors (where a funnel goes vs where a window goes).
+- **Heed the audit — all three checks.** Every build reports `overlaps=N buriedText=N longLines=N`, and
+  prints a `[excalidraw]` warning naming the offenders. Any non-zero count is a real defect:
+  - `overlaps` — two filled boxes collide (intentional nesting like a button inside a window is ignored).
+  - `buriedText` — a text LINE is >30% swallowed by a box it isn't grouped with, i.e. an unreadable
+    label. Box-vs-box cannot see this: a section title eaten by a card is text-vs-box.
+  - `longLines` — body copy past the reading measure (`READ_W`, +10% tolerance; display type ≥28px is
+    exempt). This is the skill's headline rule, and it is now enforced rather than merely documented.
+
+  Fix by flowing that region through `stack()`/`row()`, or by using the primitives that cap the measure
+  (`prose`/`bullets`/`callout`). Opt out with `spec.audit === false` only if you *know* it's deliberate.
+  **A clean audit is necessary, not sufficient — always render the board and LOOK at it.** The audit
+  cannot see a chart with a mis-scaled axis, a torn sentence, or a layout that is merely ugly.
 - **Size boxes for their text.** A card guarantees the label stays *inside*, but it does so by shrinking
   the font — a long label in a small box ends up tiny. Give wide/long labels a wider `w` (or more `h`),
   or split the idea across two cards. Watch for `[excalidraw]` fit warnings on the console.
@@ -214,8 +421,24 @@ so they work in any project):
 cd .claude/skills/excalidraw
 node scripts/build_excalidraw.js examples/hello.spec.json   # spec-driven: text/shapes/image → examples/Hello Excalidraw.excalidraw.md
 node examples/style_board.js                                # JS API: card/connector/lane house style → examples/Style Demo.excalidraw.md
+node examples/visual_board.js                              # visual-first kit: funnel + browser prototype + readable prose
+node examples/chart_board.js                               # every chart in the kit, one board (smoke test)
+node scripts/build_excalidraw.js examples/chart.spec.json  # charts declaratively, pure JSON, no generator
+node examples/atomic_check.js                             # every type from ONE spec element + degenerate input
+node examples/wireframe_board.js                          # devices (iPhone/iPad/Mac) + every UI control + icon set
+```
+`atomic_check.js` is the guard on the kit's core promise: each type must draw from a **single spec
+element with data only**, and must not throw on degenerate input (empty series, one point, all-equal
+values). Add a chart to `charts.js` but forget to register it in `COMPOSITES` and this fails. It exits
+non-zero, so it can be wired into CI.
+Each build prints `overlaps=N buriedText=N longLines=N` — a clean board reports **0 for all three**.
+
+**Then LOOK at the board.** A clean audit is necessary, not sufficient: it cannot see a mis-scaled
+axis, a sentence torn across a gap, or a layout that is simply ugly. Either open it in Obsidian
+(Excalidraw view), or render it headlessly and inspect the PNG:
+```bash
+node scripts/diagrams/render-excalidraw.mjs <board.excalidraw.md> /tmp/out.png 1   # (in this repo)
 ```
-Then open the resulting board in Obsidian (Excalidraw view) to confirm it renders.
 
 See `reference/format.md` for the exact `.excalidraw.md` anatomy reverse-engineered from this vault.
 
@@ -233,8 +456,16 @@ JSON).
 
 ### Required frontmatter
 
-Every board MUST have `name:` and `description:`. Boards with no `## Text Elements` content rely
-entirely on description for recall — make it descriptive.
+Every board MUST have `name:` and `description:` — **pass them to `buildExcalidraw`** and it emits
+them for you (long descriptions become a folded YAML block; `tags` defaults to `[excalidraw]`).
+Do NOT hand-patch the generated file afterwards.
+
+```js
+buildExcalidraw({ out, elements, name: 'recall-engine-v2', tags: ['architecture', 'excalidraw'],
+  description: 'How recall ranks and merges hits across the vault and consenting peers…' });
+```
+Memory indexes frontmatter + `## Text Elements` and never the scene JSON, so a board with few labels
+leans entirely on `description` for recall — make it descriptive.
 
 ```yaml
 ---