@hegemonart/get-design-done 1.42.0 → 1.43.0

package/reference/components/tooltip.md

@@ -1,4 +1,4 @@
-# Tooltip — Benchmark Spec
+# Tooltip - Benchmark Spec
 
 **Harvested from**: WAI-ARIA APG, Radix UI, Material 3, Carbon, Mantine, Fluent 2, Atlassian, Apple HIG
 **Wave**: 2 · **Category**: Containers
@@ -43,7 +43,7 @@ A tooltip is a small, non-interactive label that appears on hover or keyboard fo
 | Light | Light background | Mantine (inverted) |
 
 **Norm** (≥7/18): 300ms show delay, 0ms hide; max-width 240px; never interactive content.
-**Diverge**: delay duration — Carbon recommends 100ms for toolbars; WAI-ARIA APG recommends ≤500ms. 300ms is the safe default.
+**Diverge**: delay duration - Carbon recommends 100ms for toolbars; WAI-ARIA APG recommends ≤500ms. 300ms is the safe default.
 
 ---
 
@@ -72,8 +72,8 @@ A tooltip is a small, non-interactive label that appears on hover or keyboard fo
 
 ## Typography
 
-- 12px/400 — tooltip text is supplemental; smaller weight and size distinguish it from primary content
-- No bold, no headings inside tooltip — it is a single line of text (≤60 chars preferred)
+- 12px/400 - tooltip text is supplemental; smaller weight and size distinguish it from primary content
+- No bold, no headings inside tooltip - it is a single line of text (≤60 chars preferred)
 - Multi-line: allowed if content genuinely requires it; still no interactive elements
 
 ---
@@ -81,11 +81,11 @@ A tooltip is a small, non-interactive label that appears on hover or keyboard fo
 ## Keyboard & Accessibility
 
 > **WAI-ARIA role**: `tooltip`
-> **Trigger attributes**: `aria-describedby="tooltip-id"` — links the supplemental label
+> **Trigger attributes**: `aria-describedby="tooltip-id"` - links the supplemental label
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -97,11 +97,11 @@ Tooltip does NOT receive focus. It is purely a visual label attached to the trig
 
 ### Accessibility Rules
 
-- Trigger MUST have `aria-describedby` pointing to the tooltip's `id` — screen readers read tooltip content as supplemental description
-- Tooltip is `role="tooltip"` — NOT `role="dialog"` (no interactivity, no focus trap)
-- Tooltip MUST appear on keyboard focus, not only on hover — keyboard-only users need access too *(WCAG 1.3.3, 2.1.1)*
-- Do NOT put interactive content inside a tooltip — use Popover (`reference/components/popover.md`)
-- Do NOT use tooltip as the only accessible name for a control — use `aria-label` on the trigger instead; tooltip supplements, not replaces, the accessible name
+- Trigger MUST have `aria-describedby` pointing to the tooltip's `id` - screen readers read tooltip content as supplemental description
+- Tooltip is `role="tooltip"` - NOT `role="dialog"` (no interactivity, no focus trap)
+- Tooltip MUST appear on keyboard focus, not only on hover - keyboard-only users need access too *(WCAG 1.3.3, 2.1.1)*
+- Do NOT put interactive content inside a tooltip - use Popover (`reference/components/popover.md`)
+- Do NOT use tooltip as the only accessible name for a control - use `aria-label` on the trigger instead; tooltip supplements, not replaces, the accessible name
 - Escape MUST dismiss the tooltip without removing focus from the trigger *(WAI-ARIA APG)*
 
 ---
@@ -112,25 +112,25 @@ Tooltip does NOT receive focus. It is purely a visual label attached to the trig
 |------------|----------|--------|-------|
 | Show | 100ms | ease-out | Fade only; no scale (too flashy for a label) |
 | Hide | 80ms | ease | Fade only; immediate on Escape |
-| Delay | 300ms | — | CSS `transition-delay` or JS timeout |
+| Delay | 300ms | - | CSS `transition-delay` or JS timeout |
 
-Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip fade, instant show/hide
+Cross-link: `reference/motion.md` - `prefers-reduced-motion`: skip fade, instant show/hide
 
 ---
 
 ## Do / Don't
 
 ### Do
-- Show on keyboard focus AND hover — not hover-only *(WAI-ARIA APG, WCAG 2.1.1)*
+- Show on keyboard focus AND hover - not hover-only *(WAI-ARIA APG, WCAG 2.1.1)*
 - Use `aria-describedby` to link trigger to tooltip *(WAI-ARIA APG)*
-- Limit tooltip content to ≤60 chars — longer content belongs in a popover *(Carbon, Material 3)*
+- Limit tooltip content to ≤60 chars - longer content belongs in a popover *(Carbon, Material 3)*
 - Apply 300ms show delay to prevent accidental triggers while cursor passes *(WAI-ARIA APG, Carbon)*
 
 ### Don't
-- Don't put interactive elements inside a tooltip *(WAI-ARIA APG — this makes it a popover)*
-- Don't use tooltip as the only accessible name — `aria-describedby` supplements, not replaces, `aria-label` *(WAI-ARIA APG)*
-- Don't trigger tooltip on click — use a popover *(Radix, WAI-ARIA APG)*
-- Don't use tooltip for critical information — it's supplemental; users on touch devices may miss it *(Material 3, Polaris)*
+- Don't put interactive elements inside a tooltip *(WAI-ARIA APG - this makes it a popover)*
+- Don't use tooltip as the only accessible name - `aria-describedby` supplements, not replaces, `aria-label` *(WAI-ARIA APG)*
+- Don't trigger tooltip on click - use a popover *(Radix, WAI-ARIA APG)*
+- Don't use tooltip for critical information - it's supplemental; users on touch devices may miss it *(Material 3, Polaris)*
 
 ---
 

package/reference/components/tree.md

@@ -1,4 +1,4 @@
-# Tree View (Hierarchical Navigation) — Benchmark Spec
+# Tree View (Hierarchical Navigation) - Benchmark Spec
 
 **Harvested from**: WAI-ARIA APG, Carbon, Atlassian, Radix, Material 3
 **Wave**: 4 · **Category**: Navigation & Data
@@ -65,8 +65,8 @@ A tree view displays hierarchical data in a collapsible structure of parent and
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| node-default | — | Icon + label; indented by level | — |
-| node-hover | pointer over | 8% overlay on row | — |
+| node-default | - | Icon + label; indented by level | - |
+| node-hover | pointer over | 8% overlay on row | - |
 | node-focus | keyboard focus | 2px focus-visible ring on row | `tabindex="0"` on focused; `-1` on rest |
 | node-selected | click or Enter/Space | Filled row highlight | `aria-selected="true"` |
 | node-expanded | toggle click or ArrowRight | Children visible; icon rotated/open | `aria-expanded="true"` |
@@ -93,10 +93,10 @@ A tree view displays hierarchical data in a collapsible structure of parent and
 ## Typography
 
 - Node label: body-sm (13–14px), weight 400; selected node weight 500
-- Level depth: visual indentation only — no font-size reduction per level
+- Level depth: visual indentation only - no font-size reduction per level
 - Disabled node: same font size, `color: --text-disabled`
 
-Cross-link: `reference/typography.md` — body-sm
+Cross-link: `reference/typography.md` - body-sm
 
 ---
 
@@ -107,7 +107,7 @@ Cross-link: `reference/typography.md` — body-sm
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/treeview/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/treeview/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -123,14 +123,14 @@ Cross-link: `reference/typography.md` — body-sm
 
 ### Accessibility Rules
 
-- ALL expandable nodes MUST have `aria-expanded` — CSS-only expand/collapse is invisible to AT
+- ALL expandable nodes MUST have `aria-expanded` - CSS-only expand/collapse is invisible to AT
 - `aria-level` must accurately reflect nesting depth (1-based) on every `role="treeitem"`
-- Child `<ul>` MUST have `role="group"` — without it, AT cannot perceive the parent-child relationship
+- Child `<ul>` MUST have `role="group"` - without it, AT cannot perceive the parent-child relationship
 - Focus management uses roving `tabindex`: only the active node has `tabindex="0"`; all others `tabindex="-1"`
 - Lazy-loaded nodes MUST set `aria-busy="true"` while fetching; remove when complete
 - Multi-select tree MUST set `aria-multiselectable="true"` on the `role="tree"` element
 
-Cross-link: `reference/accessibility.md` — tree pattern, roving tabindex, aria-busy
+Cross-link: `reference/accessibility.md` - tree pattern, roving tabindex, aria-busy
 
 ---
 
@@ -144,9 +144,9 @@ Cross-link: `reference/accessibility.md` — tree pattern, roving tabindex, aria
 | Node selection highlight | 100ms | ease-out | Background color only |
 | Lazy-load spinner | continuous | linear | Replace with content on load |
 
-**BAN**: Do not use CSS-only `display: none` / `display: block` to toggle children without updating `aria-expanded` — both changes must happen atomically.
+**BAN**: Do not use CSS-only `display: none` / `display: block` to toggle children without updating `aria-expanded` - both changes must happen atomically.
 
-Cross-link: `reference/motion.md` — disclosure animations
+Cross-link: `reference/motion.md` - disclosure animations
 
 ---
 
@@ -159,10 +159,10 @@ Cross-link: `reference/motion.md` — disclosure animations
 - Limit tree depth to 5–6 levels to prevent cognitive overload *(Carbon, Atlassian HIG)*
 
 ### Don't
-- Don't use `<ul>/<li>` tree without `role="tree"` + `role="treeitem"` — semantically invisible to AT *(WCAG 1.3.1)*
-- Don't forget `role="group"` on child `<ul>` — AT cannot infer parent-child structure without it *(WAI-ARIA APG)*
-- Don't manage expand/collapse with CSS only (no `aria-expanded`) — blind users cannot discover collapsed state *(WCAG 4.1.2)*
-- Don't indent via `aria-level` alone — also apply visual CSS indentation for sighted users *(Material 3, Carbon)*
+- Don't use `<ul>/<li>` tree without `role="tree"` + `role="treeitem"` - semantically invisible to AT *(WCAG 1.3.1)*
+- Don't forget `role="group"` on child `<ul>` - AT cannot infer parent-child structure without it *(WAI-ARIA APG)*
+- Don't manage expand/collapse with CSS only (no `aria-expanded`) - blind users cannot discover collapsed state *(WCAG 4.1.2)*
+- Don't indent via `aria-level` alone - also apply visual CSS indentation for sighted users *(Material 3, Carbon)*
 
 ---
 
@@ -170,7 +170,7 @@ Cross-link: `reference/motion.md` — disclosure animations
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-04 | `transition: all` on tree nodes — `reference/anti-patterns.md#ban-04` |
+| BAN-04 | `transition: all` on tree nodes - `reference/anti-patterns.md#ban-04` |
 
 ---
 
@@ -220,6 +220,6 @@ grep -rn 'role="tree"' src/ | grep -v 'aria-label\|aria-labelledby'
 </ul>
 ```
 
-**Why it fails**: No `role="tree"` or `role="treeitem"`; no `aria-expanded` — screen readers cannot tell if the node is open or closed; `role="group"` missing on child list; no `aria-level`; expand/collapse is click-only (no keyboard).
+**Why it fails**: No `role="tree"` or `role="treeitem"`; no `aria-expanded` - screen readers cannot tell if the node is open or closed; `role="group"` missing on child list; no `aria-level`; expand/collapse is click-only (no keyboard).
 **Grep detection**: `grep -rn 'class.*tree\|treeview' src/ | grep '<ul\|<li' | grep -v 'role='`
 **Fix**: Add `role="tree"` to root `<ul>`; `role="treeitem"` + `aria-expanded` + `aria-level` to each node; `role="group"` to child `<ul>`; implement arrow-key navigation with roving tabindex.

package/reference/composition.md

@@ -7,17 +7,17 @@ tags: [composition, golden-ratio, fibonacci, focal-point, eye-flow]
 last_updated: 2026-05-18
 ---
 
-# Composition — Pre-Gestalt Layout Fundamentals
+# Composition - Pre-Gestalt Layout Fundamentals
 
-The existing [visual hierarchy and layout reference](./visual-hierarchy-layout.md) covers shadow, z-index, whitespace, asymmetry, and the 12-column grid — the *applied* surface of layout. This file gives the upstream foundation those rules silently assume: rule of thirds, the golden ratio and root rectangles, Fibonacci, focal-point construction, visual-weight calculus, optical-vs-mathematical centering, and the Z / F / Gutenberg eye-flow patterns. Where `visual-hierarchy-layout.md` says "place the CTA where the eye lands", this file replaces that hand-wave with explicit grids, ratios, weight formulas, and detection signatures an audit can grep for.
+The existing [visual hierarchy and layout reference](./visual-hierarchy-layout.md) covers shadow, z-index, whitespace, asymmetry, and the 12-column grid - the *applied* surface of layout. This file gives the upstream foundation those rules silently assume: rule of thirds, the golden ratio and root rectangles, Fibonacci, focal-point construction, visual-weight calculus, optical-vs-mathematical centering, and the Z / F / Gutenberg eye-flow patterns. Where `visual-hierarchy-layout.md` says "place the CTA where the eye lands", this file replaces that hand-wave with explicit grids, ratios, weight formulas, and detection signatures an audit can grep for.
 
-This is the file an agent should consult any time it is *constructing* a layout — choosing a grid, placing a focal point, balancing two halves of a composition, centering a glyph next to text, or deciding which eye-flow archetype a page should follow.
+This is the file an agent should consult any time it is *constructing* a layout - choosing a grid, placing a focal point, balancing two halves of a composition, centering a glyph next to text, or deciding which eye-flow archetype a page should follow.
 
 ---
 
 ## Rule of Thirds
 
-The rule of thirds divides any canvas into a 3×3 grid with two horizontal and two vertical lines at the 33% and 67% marks. The four intersections of those lines are the *power points* — the locations the eye lands when scanning a composition. Placing a focal element exactly on a power point produces a layout that reads as deliberate and balanced; placing it at dead-center produces a layout that reads as static and posed. The rule is not a law; it is a default that holds until a stronger compositional intent overrides it (centered hero, symmetric mirror, single-axis radial).
+The rule of thirds divides any canvas into a 3×3 grid with two horizontal and two vertical lines at the 33% and 67% marks. The four intersections of those lines are the *power points* - the locations the eye lands when scanning a composition. Placing a focal element exactly on a power point produces a layout that reads as deliberate and balanced; placing it at dead-center produces a layout that reads as static and posed. The rule is not a law; it is a default that holds until a stronger compositional intent overrides it (centered hero, symmetric mirror, single-axis radial).
 
 **Audit detection signature.** Grep for grid declarations using third-fractions, then check whether a focal element (large heading, primary CTA, hero image) sits near one of the four intersections:
 
@@ -61,17 +61,17 @@ grep -rE "grid-template-columns:\s*1fr\s+1fr\s+1fr|33%|66%|33\.33%|66\.66%" src/
 </style>
 ```
 
-The CTA sits at the lower-right intersection — the natural Z-pattern terminus (see [§Eye-Flow Patterns](#eye-flow-patterns)). The headline anchors the upper-left third where reading begins.
+The CTA sits at the lower-right intersection - the natural Z-pattern terminus (see [§Eye-Flow Patterns](#eye-flow-patterns)). The headline anchors the upper-left third where reading begins.
 
 ---
 
 ## Golden Ratio and Root Rectangles
 
-Beyond thirds, four irrational ratios govern compositions that need to feel *proportional* rather than *gridded*: φ (the golden ratio), √2, √3, and √5. Each rectangle has a different subdivision behavior — when you remove the largest possible square from inside it, the remainder has a specific relationship to the original. φ produces another φ-rectangle (infinitely self-similar — the source of the golden spiral). √2 produces a rectangle that, when folded in half, is still √2 (the math behind A0 / A1 / A2 paper). √3 produces a √3 / 2 rectangle. √5 produces two squares plus a φ-rectangle and is the bridge from integer roots back to φ via the identity `φ = (1 + √5) / 2`.
+Beyond thirds, four irrational ratios govern compositions that need to feel *proportional* rather than *gridded*: φ (the golden ratio), √2, √3, and √5. Each rectangle has a different subdivision behavior - when you remove the largest possible square from inside it, the remainder has a specific relationship to the original. φ produces another φ-rectangle (infinitely self-similar - the source of the golden spiral). √2 produces a rectangle that, when folded in half, is still √2 (the math behind A0 / A1 / A2 paper). √3 produces a √3 / 2 rectangle. √5 produces two squares plus a φ-rectangle and is the bridge from integer roots back to φ via the identity `φ = (1 + √5) / 2`.
 
 ### φ-Grid (Golden Ratio)
 
-φ ≈ 1.618. A φ-rectangle has its short side to long side in ratio `1 : 1.618`. When the same ratio governs the relationship between a sidebar and main content, an image and its caption block, or a heading and its body text, the layout reads as *naturally weighted* — neither cramped nor empty. The catch is that φ is opinionated: it pulls compositions toward warmth and editorial feel, away from grid-locked rigidity. Use it where the design wants to feel hand-tuned, not where it must align to a strict baseline grid.
+φ ≈ 1.618. A φ-rectangle has its short side to long side in ratio `1 : 1.618`. When the same ratio governs the relationship between a sidebar and main content, an image and its caption block, or a heading and its body text, the layout reads as *naturally weighted* - neither cramped nor empty. The catch is that φ is opinionated: it pulls compositions toward warmth and editorial feel, away from grid-locked rigidity. Use it where the design wants to feel hand-tuned, not where it must align to a strict baseline grid.
 
 ```css
 /* φ-grid — sidebar:content ratio of 1:1.618 */
@@ -88,7 +88,7 @@ Beyond thirds, four irrational ratios govern compositions that need to feel *pro
 }
 ```
 
-### Root Rectangles — √2, √3, √5
+### Root Rectangles - √2, √3, √5
 
 | Ratio | Value  | Subdivision property                                    | UI fit                                                          |
 | ----- | ------ | ------------------------------------------------------- | --------------------------------------------------------------- |
@@ -115,35 +115,35 @@ Dynamic symmetry (Jay Hambidge, 1920) draws *armatures* inside root rectangles:
 
 ### Fibonacci
 
-The Fibonacci sequence — `1, 1, 2, 3, 5, 8, 13, 21, 34, 55, …` — approaches φ as the ratio between consecutive terms (8 / 5 = 1.6; 13 / 8 = 1.625; 21 / 13 = 1.615). The square-rectangle subdivision pattern uses Fibonacci numbers as side lengths: a 1×1 square next to a 1×1 square forms a 1×2, append a 2×2 to make a 3×2, append a 3×3 to make a 5×3, and so on — each new square's side is the previous two added together. The diagonal through these squares traces the golden spiral.
+The Fibonacci sequence - `1, 1, 2, 3, 5, 8, 13, 21, 34, 55, …` - approaches φ as the ratio between consecutive terms (8 / 5 = 1.6; 13 / 8 = 1.625; 21 / 13 = 1.615). The square-rectangle subdivision pattern uses Fibonacci numbers as side lengths: a 1×1 square next to a 1×1 square forms a 1×2, append a 2×2 to make a 3×2, append a 3×3 to make a 5×3, and so on - each new square's side is the previous two added together. The diagonal through these squares traces the golden spiral.
 
-In UI, Fibonacci numbers show up in two places: (a) spacing scales — `4 8 12 20 32 52 84` is a Fibonacci-flavored scale (and see [./visual-hierarchy-layout.md §Whitespace as Design Element](./visual-hierarchy-layout.md) for the applied scale); (b) content sizing where natural proportion matters more than strict alignment (a 5-column / 3-column / 2-column nested layout reads as proportional because consecutive Fibonacci pairs approach φ). Fibonacci is the *integer-friendly approximation of φ* — use it when you want φ's feel but need round numbers for token systems.
+In UI, Fibonacci numbers show up in two places: (a) spacing scales - `4 8 12 20 32 52 84` is a Fibonacci-flavored scale (and see [./visual-hierarchy-layout.md §Whitespace as Design Element](./visual-hierarchy-layout.md) for the applied scale); (b) content sizing where natural proportion matters more than strict alignment (a 5-column / 3-column / 2-column nested layout reads as proportional because consecutive Fibonacci pairs approach φ). Fibonacci is the *integer-friendly approximation of φ* - use it when you want φ's feel but need round numbers for token systems.
 
 ---
 
 ## Focal-Point Construction
 
-Every composition declares 0, 1, or 2+ focal points. A composition with 0 focal points reads as a pattern or texture — fine for backgrounds, wrong for content. A composition with too many focal points reads as noisy and unfocused. Choosing the right count is the first compositional decision; placing them on a power point or armature anchor is the second.
+Every composition declares 0, 1, or 2+ focal points. A composition with 0 focal points reads as a pattern or texture - fine for backgrounds, wrong for content. A composition with too many focal points reads as noisy and unfocused. Choosing the right count is the first compositional decision; placing them on a power point or armature anchor is the second.
 
 ### Single-Focal
 
-One element dominates — significantly larger, higher contrast, more isolated, or more saturated than every sibling. The eye lands once and stays. Fits archetypes where there is exactly one decision to make or one piece of information to absorb.
+One element dominates - significantly larger, higher contrast, more isolated, or more saturated than every sibling. The eye lands once and stays. Fits archetypes where there is exactly one decision to make or one piece of information to absorb.
 
 - **UI archetypes:** landing hero, empty state, error page, sign-in / sign-up form, paywall, confirmation modal, onboarding step.
 - **Audit detection:** one element scores ≥ 1.5× the visual weight of every other element on the page (see [§Visual-Weight Calculus](#visual-weight-calculus)).
-- **Common failure:** decorative imagery competing with the primary CTA — image and CTA weight scores within 10%, eye bounces between them.
+- **Common failure:** decorative imagery competing with the primary CTA - image and CTA weight scores within 10%, eye bounces between them.
 
 ### Dual-Focal
 
-Two elements compete intentionally — same weight, placed at opposite power points or mirrored across an axis. The eye is invited to compare. Fits archetypes where the user is choosing between exactly two paths.
+Two elements compete intentionally - same weight, placed at opposite power points or mirrored across an axis. The eye is invited to compare. Fits archetypes where the user is choosing between exactly two paths.
 
 - **UI archetypes:** pricing compare view (basic vs. pro), before/after slider, plan-A vs. plan-B, A/B testimonial pair, fork-in-the-road CTA (Login | Sign Up).
 - **Audit detection:** exactly two elements with visual weights within 10% of each other and weights ≥ 2× the third-heaviest element; they sit on opposing thirds-power-points or mirror axes.
-- **Common failure:** the two focal elements drift in weight as one gets a "recommended" badge — what was dual-focal becomes single-focal with a decorative competitor.
+- **Common failure:** the two focal elements drift in weight as one gets a "recommended" badge - what was dual-focal becomes single-focal with a decorative competitor.
 
 ### Distributed
 
-Three or more elements share weight — none dominates, all are roughly equal. The eye scans rather than locks on. Fits archetypes built around browse-and-select rather than read-and-act.
+Three or more elements share weight - none dominates, all are roughly equal. The eye scans rather than locks on. Fits archetypes built around browse-and-select rather than read-and-act.
 
 - **UI archetypes:** dashboard (multiple cards / KPIs / charts), gallery, product grid, settings index, file browser, kanban board.
 - **Audit detection:** ≥ 3 elements with visual weights all within 25% of each other; total visual weight is high but no single element exceeds 1.3× the median.
@@ -153,7 +153,7 @@ Three or more elements share weight — none dominates, all are roughly equal. T
 
 ## Visual-Weight Calculus
 
-Visual weight is the *perceived heaviness* of an element — how strongly the eye is pulled to it relative to neighbors. It is the product of four factors, each normalized to 0..1:
+Visual weight is the *perceived heaviness* of an element - how strongly the eye is pulled to it relative to neighbors. It is the product of four factors, each normalized to 0..1:
 
 ```text
 weight = size × contrast × isolation × complexity
@@ -162,11 +162,11 @@ weight = size × contrast × isolation × complexity
 - **Size** (0..1): the element's area normalized against the largest element on the page. A hero headline at full container width might be 1.0; a footer link at 12px might be 0.05.
 - **Contrast** (0..1): luminance contrast against the immediate background, normalized against the page's maximum contrast pair. Black on white is 1.0; mid-gray on light-gray might be 0.2.
 - **Isolation** (0..1): empty-space margin around the element, normalized against the largest margin on the page. Generous whitespace lifts the score; cramped neighbors lower it.
-- **Complexity** (0..1): internal structure — an image with detail scores higher than a flat color block of the same size; a button with an icon plus a label plus a chevron scores higher than a plain text link.
+- **Complexity** (0..1): internal structure - an image with detail scores higher than a flat color block of the same size; a button with an icon plus a label plus a chevron scores higher than a plain text link.
 
-The formula is multiplicative because each factor is necessary — an element with massive size but zero contrast (white text on white) has zero visual weight, regardless of isolation or complexity.
+The formula is multiplicative because each factor is necessary - an element with massive size but zero contrast (white text on white) has zero visual weight, regardless of isolation or complexity.
 
-### Worked Example — 3 elements in a landing hero
+### Worked Example - 3 elements in a landing hero
 
 Suppose a hero contains a headline, a primary CTA, and a secondary text link.
 
@@ -178,7 +178,7 @@ Suppose a hero contains a headline, a primary CTA, and a secondary text link.
 
 The headline dominates (weight ≈ 0.2), the CTA is secondary (≈ 0.1, half the headline), the text link is near-invisible (≈ 0.002, two orders of magnitude lighter). This is correct for a hero that wants the user to read the headline, then act on the CTA, with the text link as a low-stakes escape hatch.
 
-### "Balanced" — defined numerically
+### "Balanced" - defined numerically
 
 A two-sided composition is **balanced** when the sum of visual weights on each side of the optical center is within ~20% of the other. Three or more elements distributed are balanced when no single element exceeds 1.3× the median weight (see distributed-focal detection above).
 
@@ -193,19 +193,19 @@ A two-sided composition is **balanced** when the sum of visual weights on each s
 # 5. If left_sum > 1.5 × right_sum (or right > 1.5 × left), flag IMBALANCED.
 ```
 
-The 1.5× threshold catches obvious imbalance; the 20%-of-each-other rule is the *target* a balanced composition aims for. The gap between 20% and 50% is where a human designer's eye is needed — the formula declares "not obviously broken", not "definitively good".
+The 1.5× threshold catches obvious imbalance; the 20%-of-each-other rule is the *target* a balanced composition aims for. The gap between 20% and 50% is where a human designer's eye is needed - the formula declares "not obviously broken", not "definitively good".
 
 ---
 
 ## Optical vs. Mathematical Centering
 
-The pixel center of a bounding box is rarely the visual center of the *thing inside the box*. Glyphs have asymmetric ink distribution; icons have asymmetric stroke weight; characters have descenders, ascenders, cap-height, and x-height that do not all line up with the box edges. Mathematical centering — `display: flex; align-items: center; justify-content: center;` — produces a result that *looks* off-center to the eye in three common cases:
+The pixel center of a bounding box is rarely the visual center of the *thing inside the box*. Glyphs have asymmetric ink distribution; icons have asymmetric stroke weight; characters have descenders, ascenders, cap-height, and x-height that do not all line up with the box edges. Mathematical centering - `display: flex; align-items: center; justify-content: center;` - produces a result that *looks* off-center to the eye in three common cases:
 
 - An icon glyph with directional weight (a play triangle pointing right has more ink on the left half of its bounding box and reads as shifted-left when math-centered).
-- A button label aligned next to an icon — the label's x-height pulls the label's optical center *below* the icon's optical center.
-- Mixed cap-height + x-height text aligned to a baseline — capitals look "too high" because their cap-height extends above the x-height where the eye expects the line to live.
+- A button label aligned next to an icon - the label's x-height pulls the label's optical center *below* the icon's optical center.
+- Mixed cap-height + x-height text aligned to a baseline - capitals look "too high" because their cap-height extends above the x-height where the eye expects the line to live.
 
-### Asymmetric Glyph Weight — the −1px nudge
+### Asymmetric Glyph Weight - the −1px nudge
 
 A right-pointing play triangle visually balances when its bounding box is shifted ~1 px (or 1.5–2 px at larger sizes) to the *right* of the mathematical center. The shift accounts for the empty wedge on the triangle's right side.
 
@@ -228,7 +228,7 @@ See [./iconography.md](./iconography.md) §1 "Optical Sizing & Stroke Weight" fo
 
 ### Cap-Height vs. X-Height Alignment
 
-When a label sits next to an icon, the icon should align to the **cap-height** of capital letters in the label — not the x-height of lowercase, not the baseline. The eye reads the icon's center against the strongest vertical anchor in the type, and cap-height is that anchor. Aligning to x-height makes the icon look "low"; aligning to baseline makes it look "too low".
+When a label sits next to an icon, the icon should align to the **cap-height** of capital letters in the label - not the x-height of lowercase, not the baseline. The eye reads the icon's center against the strongest vertical anchor in the type, and cap-height is that anchor. Aligning to x-height makes the icon look "low"; aligning to baseline makes it look "too low".
 
 ```css
 /* Button with leading icon — align icon to cap-height of label */
@@ -251,7 +251,7 @@ When a label sits next to an icon, the icon should align to the **cap-height** o
    align-items: center with line-height: 1 keeps the icon at cap-center. */
 ```
 
-The cap-height anchor logic is one half of the story; the other half — modular scale, x-height ratios per typeface — lives in [./typography.md](./typography.md) §Type Scale Systems and §Modular Scale.
+The cap-height anchor logic is one half of the story; the other half - modular scale, x-height ratios per typeface - lives in [./typography.md](./typography.md) §Type Scale Systems and §Modular Scale.
 
 ---
 
@@ -259,7 +259,7 @@ The cap-height anchor logic is one half of the story; the other half — modular
 
 A page is not read pixel-by-pixel. The eye follows one of three default patterns shaped by reading direction (LTR Western languages assumed; RTL mirrors these horizontally), content density, and the kind of decision the user is making. Designing *against* the dominant pattern produces friction; designing *with* it produces effortless scanning.
 
-### Z-Pattern — landing pages, conversion flows
+### Z-Pattern - landing pages, conversion flows
 
 The Z-pattern fits sparse, hero-led pages with a clear call to action. The eye lands top-left (logo / brand), sweeps top-right (secondary nav / brand CTA), diagonals down-left (hero headline / body), then sweeps bottom-right (primary CTA terminus). Each anchor of the Z gets one element; the diagonal is the "story" connecting them.
 
@@ -279,11 +279,11 @@ The Z-pattern fits sparse, hero-led pages with a clear call to action. The eye l
 └──────────────────────────────────────────────────────────────┘
 ```
 
-Pair with single-focal-point construction (the CTA at the lower-right power point — same coordinate as the rule-of-thirds example above).
+Pair with single-focal-point construction (the CTA at the lower-right power point - same coordinate as the rule-of-thirds example above).
 
-### F-Pattern — content-heavy, scanning surfaces
+### F-Pattern - content-heavy, scanning surfaces
 
-The F-pattern fits dense pages a user scans rather than reads — search results, news feeds, documentation, settings pages, listings. The eye sweeps horizontally across the top, drops to a shorter horizontal sweep mid-page, then runs vertically down the left edge sampling row-openers. Headings, leading icons, and the first 2–3 words of each row do the heaviest signaling work; deep right-side content gets skipped.
+The F-pattern fits dense pages a user scans rather than reads - search results, news feeds, documentation, settings pages, listings. The eye sweeps horizontally across the top, drops to a shorter horizontal sweep mid-page, then runs vertically down the left edge sampling row-openers. Headings, leading icons, and the first 2–3 words of each row do the heaviest signaling work; deep right-side content gets skipped.
 
 ```txt
 ┌──────────────────────────────────────────────────────────────┐
@@ -303,9 +303,9 @@ The F-pattern fits dense pages a user scans rather than reads — search results
 
 Pair with distributed-focal-point construction. Front-load row-openers (titles, leading icons, status indicators) on the left edge. Avoid burying critical information on the right side of rows; the eye does not look there.
 
-### Gutenberg Diagram — editorial, reading-heavy
+### Gutenberg Diagram - editorial, reading-heavy
 
-The Gutenberg diagram applies to text-dense reading surfaces — long-form articles, blog posts, terms-of-service pages, documentation prose. The eye follows a *reading gravity* from the top-left (primary optical area) diagonally to the bottom-right (terminal area), and the two off-diagonal quadrants — top-right (strong fallow area) and bottom-left (weak fallow area) — receive much less attention. Placing critical information in the fallow areas guarantees it goes unread.
+The Gutenberg diagram applies to text-dense reading surfaces - long-form articles, blog posts, terms-of-service pages, documentation prose. The eye follows a *reading gravity* from the top-left (primary optical area) diagonally to the bottom-right (terminal area), and the two off-diagonal quadrants - top-right (strong fallow area) and bottom-left (weak fallow area) - receive much less attention. Placing critical information in the fallow areas guarantees it goes unread.
 
 ```txt
 ┌──────────────────────────────────────────────────────────────┐
@@ -323,7 +323,7 @@ The Gutenberg diagram applies to text-dense reading surfaces — long-form artic
 └──────────────────────────────────────────────────────────────┘
 ```
 
-Pair with single-focal-point construction. The terminal area is the natural home for a "next" action — a Read More link, a Subscribe CTA, a tip-jar button. Critical content does NOT go in either fallow area.
+Pair with single-focal-point construction. The terminal area is the natural home for a "next" action - a Read More link, a Subscribe CTA, a tip-jar button. Critical content does NOT go in either fallow area.
 
 ### Choosing the pattern
 
@@ -342,8 +342,8 @@ For RTL languages (Arabic, Hebrew, Urdu, Farsi) the Z-pattern and Gutenberg diag
 
 ## Cross-References
 
-- [./visual-hierarchy-layout.md](./visual-hierarchy-layout.md) — §Compositional Grids (responsive column + baseline grid) and §Asymmetry and Rhythm; composition is the upstream foundation that file assumes.
-- [./iconography.md](./iconography.md) — §1 Optical Sizing & Stroke Weight; the optical-centering rules in this file apply directly to icon glyphs.
-- [./typography.md](./typography.md) — §Type Scale Systems and §Modular Scale; the cap-height vs. x-height alignment rule depends on those scale relationships.
+- [./visual-hierarchy-layout.md](./visual-hierarchy-layout.md) - §Compositional Grids (responsive column + baseline grid) and §Asymmetry and Rhythm; composition is the upstream foundation that file assumes.
+- [./iconography.md](./iconography.md) - §1 Optical Sizing & Stroke Weight; the optical-centering rules in this file apply directly to icon glyphs.
+- [./typography.md](./typography.md) - §Type Scale Systems and §Modular Scale; the cap-height vs. x-height alignment rule depends on those scale relationships.
 
 Reciprocal inbound cross-links land in Phase 28-06 (additive-only, D-06).

package/reference/config-schema.md

@@ -118,7 +118,7 @@ Stages are the only code that read `.design/config.json`. When spawning an agent
 2. Injects it into the agent prompt (e.g., `model_profile: balanced`) so the agent can reason about its own budget.
 3. Selects the concrete model per the profile table above and passes it to the `Task` tool.
 
-Agents never read config directly — the profile is always injected at spawn time.
+Agents never read config directly - the profile is always injected at spawn time.
 
 ## .design/budget.json Schema (Phase 10.1)
 
@@ -205,17 +205,17 @@ Resolution order for the per-spawn cap:
 1. If `complexity_class` is in `tool_input.context.router_decision` AND `class_caps_usd[class]` is a positive finite number → use it.
 2. Otherwise → use `per_task_cap_usd`.
 
-Class `S` is special: when `complexity_class === "S"` is supplied to the hook, enforcement is skipped entirely (no cap check, no auto-downgrade) — class-S commands typically short-circuit the router upstream so this hook never runs at all; the explicit S handling is the defensive path. See `skills/router/SKILL.md` for the canonical `S → fast (short-circuited)`, `M → fast`, `L → quick`, `XL → full` mapping.
+Class `S` is special: when `complexity_class === "S"` is supplied to the hook, enforcement is skipped entirely (no cap check, no auto-downgrade) - class-S commands typically short-circuit the router upstream so this hook never runs at all; the explicit S handling is the defensive path. See `skills/router/SKILL.md` for the canonical `S → fast (short-circuited)`, `M → fast`, `L → quick`, `XL → full` mapping.
 
-`per_phase_cap_usd` is unchanged by this field — phase-cumulative enforcement always uses the global per-phase cap regardless of class.
+`per_phase_cap_usd` is unchanged by this field - phase-cumulative enforcement always uses the global per-phase cap regardless of class.
 
 ## Bootstrap behavior
 
-If `.design/budget.json` is missing when any `/gdd:*` command runs, `scripts/bootstrap.sh` writes the Default Config values (per D-12). Don't block the spawn — defaults are sensible.
+If `.design/budget.json` is missing when any `/gdd:*` command runs, `scripts/bootstrap.sh` writes the Default Config values (per D-12). Don't block the spawn - defaults are sensible.
 
 ## .design/telemetry/costs.jsonl + .design/agent-metrics.json (Phase 10.1)
 
-Phase 10.1 introduces two measurement artifacts written by `hooks/budget-enforcer.js` (PreToolUse on `Agent` spawns) and `scripts/aggregate-agent-metrics.ts` (detached child of the hook + refresh step of `/gdd:optimize`). Both files live under the gitignored `.design/` directory — they are local session state, not committed.
+Phase 10.1 introduces two measurement artifacts written by `hooks/budget-enforcer.js` (PreToolUse on `Agent` spawns) and `scripts/aggregate-agent-metrics.ts` (detached child of the hook + refresh step of `/gdd:optimize`). Both files live under the gitignored `.design/` directory - they are local session state, not committed.
 
 ### .design/telemetry/costs.jsonl
 
@@ -239,21 +239,21 @@ Append-only ledger. One JSON object per line. Written by `hooks/budget-enforcer.
 
 **Extra diagnostic fields** (optional; Phase 11 reflector ignores unknown fields gracefully):
 
-- `tier_downgraded: <bool>` — set when soft-threshold downgrade fired (D-03).
-- `enforcement_mode: <"enforce" | "warn" | "log">` — mirrors `.design/budget.json.enforcement_mode` at the time of decision.
-- `lazy_skipped: <bool>` — set when plan 10.1-04 gate agent declined to spawn the full checker.
-- `block_reason: <"per_task_cap" | "per_phase_cap">` — set when hook blocked the spawn.
+- `tier_downgraded: <bool>` - set when soft-threshold downgrade fired (D-03).
+- `enforcement_mode: <"enforce" | "warn" | "log">` - mirrors `.design/budget.json.enforcement_mode` at the time of decision.
+- `lazy_skipped: <bool>` - set when plan 10.1-04 gate agent declined to spawn the full checker.
+- `block_reason: <"per_task_cap" | "per_phase_cap">` - set when hook blocked the spawn.
 
 **Guarantees:**
 
-- Writes are `fs.appendFileSync` — OS-level atomic per line.
+- Writes are `fs.appendFileSync` - OS-level atomic per line.
 - The file is **never truncated or rotated** by the hook in v1. Log rotation is a Phase 12 concern.
-- Consumers must be tolerant of malformed lines (partial writes from crashed processes) — skip-and-continue is the canonical pattern.
-- Rows log only token counts, agent name, tier, cost, cycle, phase. **No prompt or response content is logged** — the schema is information-disclosure-safe by construction.
+- Consumers must be tolerant of malformed lines (partial writes from crashed processes) - skip-and-continue is the canonical pattern.
+- Rows log only token counts, agent name, tier, cost, cycle, phase. **No prompt or response content is logged** - the schema is information-disclosure-safe by construction.
 
 ### .design/agent-metrics.json
 
-Per-agent aggregate derived from `costs.jsonl` by `scripts/aggregate-agent-metrics.ts`. Written atomically via tmp-file + rename. Overwritten in full on every refresh — not append-only. Consumers should treat it as a snapshot.
+Per-agent aggregate derived from `costs.jsonl` by `scripts/aggregate-agent-metrics.ts`. Written atomically via tmp-file + rename. Overwritten in full on every refresh - not append-only. Consumers should treat it as a snapshot.
 
 **Schema:**
 
@@ -279,8 +279,8 @@ Per-agent aggregate derived from `costs.jsonl` by `scripts/aggregate-agent-metri
 
 **Field sources:**
 
-- `typical_duration_seconds`, `default_tier`, `parallel_safe`, `reads_only` — read from `agents/{agent}.md` frontmatter (kebab-case in the markdown; re-keyed to snake_case in JSON). Null if the agent file is absent or the field is missing.
-- `total_spawns`, `total_cost_usd`, `total_tokens_in`, `total_tokens_out` — summed across all `costs.jsonl` rows for this agent.
+- `typical_duration_seconds`, `default_tier`, `parallel_safe`, `reads_only` - read from `agents/{agent}.md` frontmatter (kebab-case in the markdown; re-keyed to snake_case in JSON). Null if the agent file is absent or the field is missing.
+- `total_spawns`, `total_cost_usd`, `total_tokens_in`, `total_tokens_out` - summed across all `costs.jsonl` rows for this agent.
 - `cache_hit_rate = cache_hits / total_spawns` (clamped when total_spawns = 0).
 - `lazy_skip_rate = lazy_skips / total_spawns` (same).
 
@@ -292,11 +292,11 @@ Both files sit inside `.design/`, which is already `.gitignore`d at the project
 
 ### Refresh cadence
 
-The aggregator is invoked as a detached child process by `hooks/budget-enforcer.js` after every telemetry row write. It is also invoked directly by `/gdd:optimize` before analysis. There is no cron, no daemon, and no scheduled task — metrics are always at most one spawn stale.
+The aggregator is invoked as a detached child process by `hooks/budget-enforcer.js` after every telemetry row write. It is also invoked directly by `/gdd:optimize` before analysis. There is no cron, no daemon, and no scheduled task - metrics are always at most one spawn stale.
 
 ## .design/cache-manifest.json Schema (Phase 10.1)
 
-Authored and maintained by `skills/cache-manager/SKILL.md`. Read by `hooks/budget-enforcer.js` (PreToolUse on Agent spawns) for short-circuiting cached spawns per D-05. Layer B of the D-08 two-layer cache. Flat KV shape — keys are SHA-256 hex of the deterministic input-hash, values are entry objects. Schema version 1.
+Authored and maintained by `skills/cache-manager/SKILL.md`. Read by `hooks/budget-enforcer.js` (PreToolUse on Agent spawns) for short-circuiting cached spawns per D-05. Layer B of the D-08 two-layer cache. Flat KV shape - keys are SHA-256 hex of the deterministic input-hash, values are entry objects. Schema version 1.
 
 ## Full Schema
 
@@ -333,28 +333,28 @@ Authored and maintained by `skills/cache-manager/SKILL.md`. Read by `hooks/budge
 
 ### `agent`
 
-String — the `agents/<name>.md` basename without extension (e.g., `design-verifier`). Human-readable debug aid; not load-bearing for lookup.
+String - the `agents/<name>.md` basename without extension (e.g., `design-verifier`). Human-readable debug aid; not essential for lookup.
 
 ### `result`
 
-String — either (a) a base64-encoded blob (for small results, typically < 16KB), or (b) a filesystem path under `.design/cache-blobs/<sha-prefix>.md` for larger results. Writers choose based on size; readers handle both transparently.
+String - either (a) a base64-encoded blob (for small results, typically < 16KB), or (b) a filesystem path under `.design/cache-blobs/<sha-prefix>.md` for larger results. Writers choose based on size; readers handle both transparently.
 
 ### `written_at`
 
-String — ISO-8601 UTC timestamp at write time. Produced by `new Date().toISOString()`.
+String - ISO-8601 UTC timestamp at write time. Produced by `new Date().toISOString()`.
 
 ### `ttl_seconds`
 
-Integer — copied from `.design/budget.json.cache_ttl_seconds` at write time (default 3600). Preserved in the entry so a later budget.json change does not retroactively invalidate or extend existing entries.
+Integer - copied from `.design/budget.json.cache_ttl_seconds` at write time (default 3600). Preserved in the entry so a later budget.json change does not retroactively invalidate or extend existing entries.
 
 ### `expires_at`
 
-String — ISO-8601 UTC timestamp equal to `written_at + ttl_seconds`. Precomputed at write time; readers never recompute. Stale entries (`Date.now() > expires_at`) are treated as misses.
+String - ISO-8601 UTC timestamp equal to `written_at + ttl_seconds`. Precomputed at write time; readers never recompute. Stale entries (`Date.now() > expires_at`) are treated as misses.
 
 ## TTL semantics
 
 - TTL default source: `.design/budget.json.cache_ttl_seconds` (default 3600s = 1 hour, per Plan 10.1-01 schema).
-- TTL is copied into each entry at write time — **not** recomputed on read. Budget.json changes do not retroactively affect existing entries.
+- TTL is copied into each entry at write time - **not** recomputed on read. Budget.json changes do not retroactively affect existing entries.
 - `expires_at` = `written_at + ttl_seconds`, computed once, stored in the entry.
 - Stale entries are **not** actively purged (lazy cleanup): they remain in the file until overwritten by a new write with the same key, or pruned manually. A proactive reaper is out of v1 scope.
 - Readers (`hooks/budget-enforcer.js`) check `Date.now() / 1000 > Date.parse(expires_at) / 1000`; if true, return miss.
@@ -362,43 +362,43 @@ String — ISO-8601 UTC timestamp equal to `written_at + ttl_seconds`. Precomput
 ## Read/Write contract
 
 - **Single writer**: `skills/cache-manager/SKILL.md` Phase 4 (`write-result-on-completion`). Other code must not write this file directly.
-- **Multiple readers**: `hooks/budget-enforcer.js`, any orchestrator that runs Phase 2 (`lookup`) for dry-run planning. Readers treat malformed JSON as "manifest absent" (empty cache) — do not throw.
+- **Multiple readers**: `hooks/budget-enforcer.js`, any orchestrator that runs Phase 2 (`lookup`) for dry-run planning. Readers treat malformed JSON as "manifest absent" (empty cache) - do not throw.
 - **Concurrency**: Claude Code agent spawns are serialized at the hook level (PreToolUse is synchronous). No file locking is needed at v1 scale. Concurrent writes from parallel orchestrators are theoretically possible but exceedingly rare; last-writer-wins is acceptable (cache miss on next read re-populates).
 
 ## Bootstrap behavior
 
-If `.design/cache-manifest.json` is missing when `hooks/budget-enforcer.js` reads it, the hook treats every lookup as a miss and the spawn proceeds normally. No bootstrap action is required — the manifest is created lazily on first successful spawn when `skills/cache-manager/SKILL.md` Phase 4 fires. Unlike `.design/budget.json`, missing cache-manifest.json is the **correct** initial state on a fresh repo.
+If `.design/cache-manifest.json` is missing when `hooks/budget-enforcer.js` reads it, the hook treats every lookup as a miss and the spawn proceeds normally. No bootstrap action is required - the manifest is created lazily on first successful spawn when `skills/cache-manager/SKILL.md` Phase 4 fires. Unlike `.design/budget.json`, missing cache-manifest.json is the **correct** initial state on a fresh repo.
 
 ## Cross-references
 
-- `skills/cache-manager/SKILL.md` — producer; documents the four-phase contract.
-- `hooks/budget-enforcer.js` (Plan 10.1-01) — reader; short-circuits spawns on hit.
-- `.design/budget.json` — provides `cache_ttl_seconds` default.
-- `.design/telemetry/costs.jsonl` (Plan 10.1-05) — records `cache_hit: true` rows with zero tokens and zero cost when the short-circuit fires.
-- D-05, D-08, D-09 in `.planning/phases/10.1-optimization-layer-cost-governance/10.1-CONTEXT.md` — decision lineage.
+- `skills/cache-manager/SKILL.md` - producer; documents the four-phase contract.
+- `hooks/budget-enforcer.js` (Plan 10.1-01) - reader; short-circuits spawns on hit.
+- `.design/budget.json` - provides `cache_ttl_seconds` default.
+- `.design/telemetry/costs.jsonl` (Plan 10.1-05) - records `cache_hit: true` rows with zero tokens and zero cost when the short-circuit fires.
+- D-05, D-08, D-09 in `.planning/phases/10.1-optimization-layer-cost-governance/10.1-CONTEXT.md` - decision lineage.
 
 ## Team collaboration (Phase 40)
 
-Three optional top-level `.design/config.json` keys enable team mode. All are absent/off by default —
+Three optional top-level `.design/config.json` keys enable team mode. All are absent/off by default -
 single-operator projects are unaffected. Full contract: `reference/multi-author-model.md`.
 
-- **`gdd_cycle_mode`** (`designer` | `dev` | `full`, default `full`) — sectional handoff. `designer`
+- **`gdd_cycle_mode`** (`designer` | `dev` | `full`, default `full`) - sectional handoff. `designer`
   permits Brief + Explore writes; `dev` permits Plan + Design + Verify; `full` = all stages.
   `scripts/lib/collab/cycle-mode.cjs` `stagePermitted(mode, stage)` gates STATE writes by stage.
-- **`permissions`** — per-section write permissions (`scripts/lib/collab/permissions.cjs`). Permissive
+- **`permissions`** - per-section write permissions (`scripts/lib/collab/permissions.cjs`). Permissive
   by default (absent = everyone `owner`). Shape: `{ default, actors: {<actor>: <role>}, rules:
   [{section, action, roles}] }`, roles in `owner|contributor|reviewer|viewer`. A rule restricts a
   `(section, action)` to its listed roles; an unruled pair is allowed. `viewer` never mutates. A CI
   gate calls `can(config, actor, section, action)` to enforce on PRs.
-- **`collab`** — `{ multi_writer_enabled (bool), lock_timeout_ms (int), sync_backend
+- **`collab`** - `{ multi_writer_enabled (bool), lock_timeout_ms (int), sync_backend
   (git|s3|git-lfs) }`. `multi_writer_enabled: true` switches the gdd-state advisory lock to the
-  team-mode policy (`scripts/lib/collab/lock-policy.cjs` — 30 s wait + 100 ms backoff);
+  team-mode policy (`scripts/lib/collab/lock-policy.cjs` - 30 s wait + 100 ms backoff);
   `sync_backend` selects the cross-machine `.design/` backend (`scripts/lib/collab/sync-backend.cjs`,
-  default `git`; `s3`/`git-lfs` are opt-in declarations — a live client is not bundled this phase).
+  default `git`; `s3`/`git-lfs` are opt-in declarations - a live client is not bundled this phase).
 
 ## CLI localization (Phase 40.5)
 
-- **`locale`** (`en`|`ru`|`uk`|`de`|`fr`|`zh`|`ja`) — overrides the language of GDD's own `--help`,
+- **`locale`** (`en`|`ru`|`uk`|`de`|`fr`|`zh`|`ja`) - overrides the language of GDD's own `--help`,
   common error messages, and skill prompt headers. Set via `/gdd:locale <code>`. Precedence: this key >
   env `LANG`/`LC_ALL` > `en`. Missing message keys fall back to English (`scripts/lib/i18n/index.cjs`,
   chain `locale → base → en`); `en` + `ru` are complete, the other five are placeholders. Full