agemon 6.0.0 → 6.3.0

package/assets/skills/design/agemon-design/references/heuristics.md

@@ -1,28 +1,25 @@
-# Heuristics — Scored Critique Methodology
+# Heuristics — Severity-Ranked Review Methodology
 
-Any skill can list anti-patterns. A scored critique is a defensible artifact a PM can action. Every finding gets a heuristic, a score (1-5), and an impact estimate. This file is the source of truth for the `/ui-craft:heuristic` command — the rubric, the laws, the output shape.
+Any skill can list anti-patterns. A heuristic review is a defensible artifact a PM can action: every finding names a heuristic or law, the element it applies to, the viewport it was seen at, and an impact tag. This file is the source of truth for the heuristic mode of `/agemon-design review` — the checklist, the laws, the output shape. It produces findings, not numbers: a figure computed from model judgment reads as a measurement it is not.
 
 ---
 
 ## How to Use
 
-Run the full pass: Nielsen's 10 (score 1-5 each) → 6 Design Laws (PASS/FAIL each) → rank findings by impact tag. Output is a machine-parseable scorecard PMs can paste into any issue tracker.
+Run the full pass: Nielsen's 10 as a checklist → the 6 Design Laws as checks → rank findings by impact tag. Output is a findings table PMs can paste into any issue tracker.
 
-Usability is not a knob. `CRAFT_LEVEL` does not relax these scores — a 2 is a 2 at every craft level.
+Usability is not a knob. `CRAFT_LEVEL` does not relax these findings — a blocking problem is blocking at every craft level.
 
 ---
 
-## Scoring Rubric (applies to every heuristic)
+## Finding Format
 
-| Score | Meaning |
-|-------|---------|
-| **1** | Blocks users. Core task cannot complete. |
-| **2** | Severe friction. Users abandon or error repeatedly. |
-| **3** | Works but confusing. Users complete with hesitation. |
-| **4** | Works, minor polish left. No user impact. |
-| **5** | Best-in-class. Nothing to add. |
+Every finding is one row: `| Heuristic or law | Element | Viewport | Finding | Impact |`.
 
-Every finding is recorded in a row: `| Heuristic | Score | Finding | Impact |`.
+- **Element** names the specific thing: "Save button in the settings form", not "the form".
+- **Viewport** is where you saw it (desktop 1280, tablet 768, mobile 375, or "code only" if you did not render it).
+- **Finding** is concrete: quote the text, count the elements, name the broken flow. Vague findings are rejected.
+- A heuristic with nothing to report gets no row. Do not pad the table with praise.
 
 ---
 
@@ -148,7 +145,7 @@ Dialogues should not contain information that is irrelevant or rarely needed.
 **What to look for:**
 - [ ] Every section answers one question; no filler
 - [ ] Visual weight proportional to importance
-- [ ] One accent, 3-5 placements per viewport (see SKILL.md anti-slop)
+- [ ] One accent, 3-5 placements per viewport (see core-rules.md, Anti-Slop Test)
 - [ ] White space is used, not avoided
 - [ ] No decorative graphics competing with content
 
@@ -193,7 +190,7 @@ Even though it is better if the system can be used without documentation, help m
 
 ## The 6 Design Laws
 
-Each is scored PASS / FAIL with a specific detail. These are physics + psychology, not preferences — failing them has measurable UX impact.
+Each is checked against a specific element. These are physics + psychology, not preferences — breaking them has measurable UX impact.
 
 ### Fitts's Law
 
@@ -203,9 +200,9 @@ Source: Fitts, P. M. (1954). "The information capacity of the human motor system
 
 **When load-bearing:** Every tappable / clickable surface. Critical on mobile.
 
-**How to score:**
-- **PASS** — touch targets ≥ 44px on mobile, ≥ 24px on desktop; primary CTA in the natural eye/thumb path; related actions grouped
-- **FAIL** — touch targets under 44px mobile; destructive actions adjacent to primary actions; CTA placed far from where the user just looked
+**What to look for:**
+- **Holds when** touch targets ≥ 44px on mobile, ≥ 24px on desktop; primary CTA in the natural eye/thumb path; related actions grouped
+- **Breaks when** touch targets under 44px mobile; destructive actions adjacent to primary actions; CTA placed far from where the user just looked
 
 ### Hick's Law
 
@@ -215,9 +212,9 @@ Source: Hick, W. E. (1952). "On the rate of gain of information."
 
 **When load-bearing:** Menus, navigation, plan selectors, form fields, dashboards.
 
-**How to score:**
-- **PASS** — nav ≤ 7 items at any level; no field offers 20+ unfiltered options without search
-- **FAIL** — 12+ top-nav items; a single select with 200 entries and no type-ahead; dashboard with 18 metrics at equal weight
+**What to look for:**
+- **Holds when** nav ≤ 7 items at any level; no field offers 20+ unfiltered options without search
+- **Breaks when** 12+ top-nav items; a single select with 200 entries and no type-ahead; dashboard with 18 metrics at equal weight
 
 ### Doherty Threshold
 
@@ -227,9 +224,9 @@ Source: Doherty, W. J. & Thadani, A. J. (1982). "The Economic Value of Rapid Res
 
 **When load-bearing:** Every user-initiated action. Critical on data-heavy views and transitions.
 
-**How to score:**
-- **PASS** — perceived response < 400ms; optimistic UI for saves, likes, toggles; skeletons within 200ms
-- **FAIL** — form submit shows a spinner for 2s with no optimistic state; nav click waits on full server round-trip before painting anything
+**What to look for:**
+- **Holds when** perceived response < 400ms; optimistic UI for saves, likes, toggles; skeletons within 200ms
+- **Breaks when** form submit shows a spinner for 2s with no optimistic state; nav click waits on full server round-trip before painting anything
 
 ### Cleveland-McGill Hierarchy
 
@@ -239,9 +236,9 @@ Source: Cleveland, W. S. & McGill, R. (1984). "Graphical Perception: Theory, Exp
 
 **When load-bearing:** Every chart, metric card, comparative dataviz.
 
-**How to score:**
-- **PASS** — quantitative comparisons use position or length (bar, line, dot); color reserved for category; no pie or 3D
-- **FAIL** — pie chart used for comparison; donut with ≥ 5 slices; color-gradient used to encode magnitude where length would work
+**What to look for:**
+- **Holds when** quantitative comparisons use position or length (bar, line, dot); color reserved for category; no pie or 3D
+- **Breaks when** pie chart used for comparison; donut with ≥ 5 slices; color-gradient used to encode magnitude where length would work
 
 ### Miller's Law
 
@@ -251,9 +248,9 @@ Source: Miller, G. A. (1956). "The Magical Number Seven, Plus or Minus Two."
 
 **When load-bearing:** Nav depth, form section counts, onboarding flows, step counts.
 
-**How to score:**
-- **PASS** — navigation ≤ 7 items per level; forms chunked into ≤ 5 sections; multi-step flows ≤ 5 steps or with clear progress. (Wizard ceiling is 5, not 7: each step holds multiple fields, and each field consumes working-memory slots of its own.)
-- **FAIL** — 14-item top nav; a single-page form with 23 ungrouped fields; a checkout with 9 steps and no progress indicator
+**What to look for:**
+- **Holds when** navigation ≤ 7 items per level; forms chunked into ≤ 5 sections; multi-step flows ≤ 5 steps or with clear progress. (Wizard ceiling is 5, not 7: each step holds multiple fields, and each field consumes working-memory slots of its own.)
+- **Breaks when** 14-item top nav; a single-page form with 23 ungrouped fields; a checkout with 9 steps and no progress indicator
 
 ### Tesler's Law
 
@@ -263,9 +260,9 @@ Also called the Law of Conservation of Complexity. Attributed to Larry Tesler.
 
 **When load-bearing:** Feature-rich tools. Configuration-heavy flows. Anywhere you're tempted to "expose a toggle."
 
-**How to score:**
-- **PASS** — complexity absorbed by sensible defaults, automation, or backend inference; advanced controls behind progressive disclosure
-- **FAIL** — UI exposes every backend knob; user must configure 8 things before they can accomplish the primary task; no default state, only empty forms
+**What to look for:**
+- **Holds when** complexity absorbed by sensible defaults, automation, or backend inference; advanced controls behind progressive disclosure
+- **Breaks when** UI exposes every backend knob; user must configure 8 things before they can accomplish the primary task; no default state, only empty forms
 
 ---
 
@@ -284,120 +281,39 @@ Rank findings in the final output by impact tag, not by heuristic order: `blocks
 
 ---
 
-## Scoring Output Format
+## Output Format
 
-The `/ui-craft:heuristic` command outputs **exactly** this structure. Do not invent new sections. Do not merge tables. Do not drop the ranking at the end.
+The heuristic review outputs **exactly** this structure. Do not invent new sections. Do not merge tables. Do not drop the ranking at the end. Do not add a score, grade or pass/fail verdict.
 
 ```markdown
-## Heuristic Scorecard
-
-| Heuristic | Score | Finding | Impact |
-|-----------|-------|---------|--------|
-| Visibility of system status | 2 | Form submit has no loading state; users click 3-4x thinking nothing happened | adds-friction |
-| Match system and real world | 4 | Dates formatted for locale; one copy says "entity" instead of "project" | minor-polish |
-| User control and freedom | 3 | Delete has confirm but no undo after it lands | reduces-trust |
-| Consistency and standards | 4 | Primary CTA consistent; one modal has Cancel on right, rest on left | minor-polish |
-| Error prevention | 4 | Delete confirms with the resource name — good | minor-polish |
-| Recognition over recall | 3 | Cmd+K exists but not surfaced in tooltips | adds-friction |
-| Flexibility and efficiency | 2 | No bulk-select on list of 200+ items | adds-friction |
-| Aesthetic and minimalist | 3 | Hero has two competing accents | reduces-trust |
-| Error recovery | 1 | "Something went wrong" with no ID, no retry | blocks-conversion |
-| Help and documentation | 3 | Tooltips on most icons; empty state has no CTA | reduces-trust |
-
-## Design Law Audit
-
-| Law | Pass/Fail | Detail |
-|-----|-----------|--------|
-| Fitts's Law | FAIL | Primary CTA is 32px tall on mobile; expected ≥ 44px |
-| Hick's Law | PASS | 5 top-nav items — within 7±2 |
-| Doherty Threshold | FAIL | Save shows spinner for ~1.8s with no optimistic state |
-| Cleveland-McGill | PASS | Bar charts for comparison, color for category only |
-| Miller's Law | PASS | Form chunked into 4 logical sections |
-| Tesler's Law | FAIL | New user sees 8 required config fields before first action |
+## Heuristic Findings
 
-## Top findings (ranked by impact)
-
-1. Error recovery (score 1, blocks-conversion) — "Something went wrong" message strands users; no ID, no retry, no support path
-2. Fitts's Law (FAIL, adds-friction) — primary CTA 32px on mobile; raise to ≥ 44px
-3. Doherty Threshold (FAIL, adds-friction) — save feels broken; add optimistic UI
-4. Flexibility (score 2, adds-friction) — bulk select missing on 200+ item list
-5. Visibility (score 2, adds-friction) — submit has no loading state
-```
+| Heuristic | Element | Viewport | Finding | Impact |
+|-----------|---------|----------|---------|--------|
+| Visibility of system status | Submit button, signup form | mobile 375 | No loading state; users click 3-4x thinking nothing happened | adds-friction |
+| User control and freedom | Delete confirm dialog, project list | desktop 1280 | Confirm exists but there is no undo after it lands | reduces-trust |
+| Consistency and standards | Cancel button, billing modal | desktop 1280 | Cancel on the right here, on the left in every other modal | minor-polish |
+| Flexibility and efficiency | Invoice list, 200+ rows | desktop 1280 | No bulk select | adds-friction |
+| Error recovery | Error banner, checkout | mobile 375 | "Something went wrong" with no ID, no retry | blocks-conversion |
 
-**Notes on output:**
-- The first row of each heuristic table is the short-name version (not the verbose Nielsen title). The heuristic is unambiguous from context.
-- The `Top findings` list is a rank, not a re-listing. Include only findings at `reduces-trust` or worse. Cap at 5.
-- Scores of 4-5 don't need a finding row unless the grader wants to surface what's working. Blank findings for 4-5 rows are fine; the Score column carries the signal.
-
----
-
-## UsabilityScore (0-100) — the judged companion to UICraftScore
-
-The scorecard above is qualitative. **UsabilityScore** rolls it into one 0-100 number + letter grade so it composes with the deterministic **UICraftScore** (`evals/quality/score.mjs`) and so a PM or CI run has a single figure to track.
-
-> **Judged, not deterministic.** UsabilityScore is computed by the host agent from this rubric — it reflects judgment and *may vary run to run*. It is **not** reproducible the way UICraftScore is. Never gate CI on UsabilityScore; gate on the deterministic UICraftScore and use UsabilityScore for review depth. Always label it `(judged)` when reporting.
-
-### Formula
-
-Deterministic *given the scores* — the same scorecard always yields the same number. Only the act of scoring is judgment.
-
-```
-heuristic_base = round( ((mean(nielsen_scores) − 1) / 4) × 100 )   # 10 Nielsen scores, each 1–5
-law_penalty    = (number of FAILED design laws) × 5                # 6 laws, −5 each (max −30)
-UsabilityScore = clamp( heuristic_base − law_penalty , 0 , 100 )
-```
+## Design Law Findings
 
-Grade bands are **identical to UICraftScore** for cross-comparison: **A ≥ 90 · B ≥ 80 · C ≥ 70 · D ≥ 60 · F < 60**.
+| Law | Element | Viewport | Detail | Impact |
+|-----|---------|----------|--------|--------|
+| Fitts's Law | Primary CTA, pricing card | mobile 375 | 32px tall; expected ≥ 44px | adds-friction |
+| Doherty Threshold | Save button, settings | desktop 1280 | Spinner for ~1.8s with no optimistic state | adds-friction |
+| Tesler's Law | First-run form | desktop 1280 | 8 required config fields before the first action | reduces-trust |
 
-Properties: all-5s with all laws passing → 100 (A). All-3s, all laws pass → 50 (F). The base maps the 1–5 mean linearly onto 0–100 (1→0, 3→50, 5→100); each failed law is a flat −5 because laws are physics/psychology violations with measurable cost.
-
-### Worked example (the scorecard above)
-
-Nielsen scores `2,4,3,4,4,3,2,3,1,3` → mean `2.9` → base `round(((2.9−1)/4)×100)` = **48**.
-Failed laws: Fitts, Doherty, Tesler = 3 → penalty `15`.
-`UsabilityScore = clamp(48 − 15, 0, 100)` = **33 / F**. (A genuinely broken UI scores in the F band — as it should.)
-
-### Output
-
-Append this block to the `/ui-craft:heuristic` output, after Top findings:
-
-```markdown
-## UsabilityScore
-
-**33 / F** (judged) · heuristic base 48 − law penalty 15
-
-| Component | Value |
-|-----------|-------|
-| Nielsen mean (1–5) | 2.9 |
-| Heuristic base (0–100) | 48 |
-| Failed design laws | 3 (Fitts, Doherty, Tesler) |
-| Law penalty | −15 |
-| **UsabilityScore** | **33 / F** |
-```
-
-Machine-readable form (emit when a caller asks for `--json`, or when invoked by `/sddesign` / an extended report):
-
-```json
-{
-  "usability": { "score": 33, "grade": "F", "judged": true },
-  "components": { "nielsen_mean": 2.9, "heuristic_base": 48, "failed_laws": 3, "law_penalty": 15 },
-  "version": "usability-1.0"
-}
-```
-
-### Extended quality report (optional combine)
-
-When the user wants the full quality picture, place the judged UsabilityScore beside the deterministic UICraftScore. Get the deterministic score with `node scripts/eval.mjs <path> --json` or the `score_ui` MCP tool, then render:
-
-```markdown
-## Extended quality report
-
-| Score | Value | Reproducible? |
-|-------|-------|---------------|
-| UICraftScore | 82 / B | ✅ deterministic — identical every run |
-| UsabilityScore | 33 / F | ❌ judged — LLM judgment, may vary |
+## Top findings (ranked by impact)
 
-Gate CI on UICraftScore. Use UsabilityScore to prioritize review depth — a high deterministic score with a low UsabilityScore means the code is clean but the *experience* has friction the static rules can't see.
+1. Error recovery (blocks-conversion) — "Something went wrong" banner strands users in checkout on mobile; no ID, no retry, no support path
+2. Fitts's Law (adds-friction) — primary CTA on the pricing card is 32px on mobile; raise to ≥ 44px
+3. Doherty Threshold (adds-friction) — save feels broken on desktop; add optimistic UI
+4. Flexibility and efficiency (adds-friction) — bulk select missing on the 200+ row invoice list
+5. Visibility of system status (adds-friction) — signup submit has no loading state on mobile
 ```
 
-The two scores are intentionally **not** averaged into one figure: one is reproducible and one is judged, and collapsing them would hide that distinction — the exact property the deterministic score exists to protect.
+**Notes on output:**
+- Use the short name for each heuristic (not the verbose Nielsen title). The heuristic is unambiguous from context.
+- The `Top findings` list is a rank, not a re-listing. Include only findings at `reduces-trust` or worse. Cap at 5.
+- Laws and heuristics that hold up get no row. If you want to say what is working, say it in one line after the ranking, not in the tables.

package/assets/skills/design/agemon-design/references/inspiration.md

@@ -61,7 +61,7 @@ Positioning statement centered above a bento grid of product surfaces. Each card
 - Typography: headline centered above the grid
 
 ### Archetype E — Editorial figure
-Value propositions presented as numbered editorial figures ("FIG 0.2", "FIG 0.3"). Gives a technical publication feel. Strong for developer-focused products where "serious" positioning outweighs "approachable."
+Value propositions presented as numbered editorial figures, labelled in the subject's own vocabulary (its real parts, stages or sections), not a generic figure label. Gives a technical publication feel. Strong for developer-focused products where "serious" positioning outweighs "approachable."
 
 - Section labels: uppercase monospace or small-caps
 - Layout: each figure gets a distinct visual treatment
@@ -143,10 +143,10 @@ Concrete patterns observed in production. Each stands as a reusable technique.
 - **Bento card sizing ratio**: ~2:1 dominant card to minor cards; never all cards equal size
 
 ### Typography signatures
-- **Display italics**: italicized hero headline as a typographic accent — distinctive without added color
+- **Display italics**: a common generated look (see [tells-2026-11.md](tells-2026-11.md)); use only when the content calls for emphasis, never as a habit
 - **Negative letter-spacing on all headings** (see Section 7 for exact values)
 - **Font weight distribution skewed to medium**: `font-weight: 500` as the dominant weight across UI, `600` for emphasis only, `700` reserved for hero scale
-- **Editorial section labels**: uppercase, tracked-out, small — "FIG 0.2" or "01 / OVERVIEW" style
+- **Section labels**: small, tracked-out uppercase labels are a common generated look ([tells-2026-11.md](tells-2026-11.md)); use one only when it names a real section the way the subject would, otherwise sentence case
 
 ### Color signatures
 - **One accent, used sparingly**: accent color appears in CTAs and key interactive elements only — not in decorative elements
@@ -281,7 +281,7 @@ Property targeting:   box-shadow, transform, opacity — never transition: all
 
 **Font pairing pattern** (display + system + mono):
 ```
-Display headings: Satoshi or equivalent geometric sans
-Body:             Inter or equivalent neutral sans
-Code/technical:   Geist Mono or equivalent monospace
+Display headings: a face chosen for the brief's subject
+Body:             a readable sans or serif chosen for the same brief
+Code/technical:   a monospace, only if the content has code
 ```

package/assets/skills/design/agemon-design/references/loops.md

@@ -1,6 +1,6 @@
 # Loop Engine
 
-Run→evaluate→fix one→re-evaluate→stop. A loop is not a review pass — it iterates until a binary gate passes or the budget runs out. A loop NEVER hard-depends on a renderer, NEVER auto-installs anything, and ALWAYS degrades with an explicit notice when visual evaluation is unavailable. The budget is non-negotiable: when it is exhausted the engine stops and reports, even if the gate has not passed.
+Run→evaluate→fix one→re-evaluate→stop. A loop is not a review pass — it iterates until its stop condition holds or the budget runs out. A stop condition is an objective check (items present, values found by search) or a count of severity-ranked findings; a general impression never passes it. A loop NEVER hard-depends on a renderer, NEVER auto-installs anything, and ALWAYS degrades with an explicit notice when visual evaluation is unavailable. The budget is non-negotiable: when it is exhausted the engine stops and reports, even if the stop condition has not been met.
 
 ---
 
@@ -12,7 +12,7 @@ Every preset declares all five fields. None is optional.
 |-------|---------------|-------------|
 | `target` | `new-build` \| `existing-surface` \| `user-screenshot` | The artifact being evaluated |
 | `lens` | one or more reference file paths / sections | Reference content that drives evaluation |
-| `gate` | `checklist-all-green` \| `zero-critical` \| `zero-off-system` | Binary pass condition |
+| `gate` | `checklist-all-green` \| `zero-critical` \| `zero-off-system` | Stop condition: an objective check or a severity-finding count, never an overall impression |
 | `renderer` | `required` \| `none` | Renderer dependency level — `required` degrades to code-only if unavailable; `none` means static analysis only (always available) |
 | `budget` | integer 1–5 (default 3, hard cap 5) | Maximum iterations allowed |
 
@@ -22,12 +22,12 @@ Every preset declares all five fields. None is optional.
 
 The agent executes this numbered procedure for every iteration:
 
-1. **Read** the target AND `.ui-craft/brief.md` §6 (learned constraints = override registry). Brief §6 overrides preset gates; the a11y/correctness floor is never overridden.
+1. **Read** the target AND the brief's §6 (learned constraints = override registry). Brief §6 overrides preset gates; the a11y/correctness floor is never overridden.
 2. **Detect renderer** (see Renderer Detection Ladder below) and emit the pre-flight cost notice — preset name, budget, "will run up to N iterations; each iteration runs one full evaluate → fix → re-evaluate cycle." MUST emit before any iteration begins.
 3. **Evaluate** the target through the preset's lens → produce a severity-ranked findings list.
 4. **Select ONE highest-impact fix.** Ranking: Critical before Major; tiebreaker within the same tier = earlier-numbered finish-bar pass / earlier-listed state in the state-design lattice / earlier-cited finding in the brief; for token-consistency: within the same tier, apply layer order — primitive token violations before semantic, semantic before component. MUST NOT apply more than one fix per iteration.
 5. **Apply** the selected fix.
-6. **Re-evaluate** — run the gate check on the updated state.
+6. **Re-evaluate** — re-run the stop-condition check on the updated state.
 7. **Stop** when the gate passes OR the iteration count reaches the budget, whichever comes first. On budget exhaustion: STOP, print final gate state, and list all open findings as "Unresolved within budget:". MUST NOT silently extend the budget.
 
 **Anti-thrash rule:** a fix that introduces a new violation is caught in the NEXT iteration — no inline re-validation. It counts against the budget.
@@ -82,15 +82,15 @@ Every loop report MUST state:
 
 | Preset | target | lens | gate | renderer | maps to |
 |--------|--------|------|------|----------|---------|
-| `visual-anti-slop` | new-build \| existing-surface | SKILL.md Anti-Slop Test + finish-bar.md Pass 1 + Pass 9 | zero-critical (Major: absent or explicitly user-confirmed — no self-accept, silence ≠ accepted) | required — degrades to code-only | `/finalize` |
-| `state-coverage` | new-build \| existing-surface | state-design.md lattice, knob-gated to CRAFT_LEVEL | checklist-all-green (all required states present) | none | `/unhappy` |
-| `token-consistency` | new-build \| existing-surface | tokens.md 3-layer contract + SKILL.md Anti-Slop Minor items | zero-off-system | none (static scan) | `/tokens audit` |
+| `visual-anti-slop` | new-build \| existing-surface | core-rules.md Anti-Slop Test + finish-bar.md Pass 1 + Pass 9 | zero-critical (Major: absent or explicitly user-confirmed — no self-accept, silence ≠ accepted) | required — degrades to code-only | pre-ship pass |
+| `state-coverage` | new-build \| existing-surface | state-design.md lattice, knob-gated to CRAFT_LEVEL | checklist-all-green (all required states present) | none | `/agemon-design harden` |
+| `token-consistency` | new-build \| existing-surface | tokens.md 3-layer contract + core-rules.md Anti-Slop Minor items | zero-off-system | none (static scan) | `/agemon-design tokens` audit |
 
 ---
 
 ## visual-anti-slop — eliminate AI-template signals until the gate passes
 
-**Lens:** SKILL.md Anti-Slop Test (Critical + Major items) + `finish-bar.md` Pass 1 (hierarchy) + Pass 9 (pixel honesty).
+**Lens:** core-rules.md Anti-Slop Test (Critical + Major items) + `finish-bar.md` Pass 1 (hierarchy) + Pass 9 (pixel honesty).
 **Gate:** all Critical Anti-Slop items absent AND all Major items absent or explicitly user-confirmed. A Major is "accepted" ONLY when the user explicitly confirms it (during pre-flight or mid-loop); absent explicit confirmation it stays OPEN and counts against the gate. No self-accept, no "not found on re-eval = accepted".
 **Renderer:** required — degrades to code-only (partial confidence) if unavailable. The gate is reported as "partial — visual rendering unverified" when renderer=none. MUST NOT claim full pass on visual criteria without a renderer.
 **Highest-impact ranking:** Critical Anti-Slop findings first; within Major, earlier-numbered finish-bar pass wins.
@@ -120,7 +120,7 @@ Every loop report MUST state:
 
 ## token-consistency — iterate until zero off-system values remain
 
-**Lens:** `tokens.md` 3-layer contract (per tokens.md 3-layer contract — see that file for canonical layer definitions) + SKILL.md Anti-Slop Minor items for hardcoded values.
+**Lens:** `tokens.md` 3-layer contract (per tokens.md 3-layer contract — see that file for canonical layer definitions) + core-rules.md Anti-Slop Minor items for hardcoded values.
 **Gate:** zero off-system values — any color, radius, or spacing value not drawn from the project's token system.
 **Renderer:** none — static code scan; always available.
 **Highest-impact ranking:** Critical token violations (raw hex colors) before Major (arbitrary radii, magic spacing); tiebreaker = order of appearance in the file.

package/assets/skills/design/agemon-design/references/motion.md

@@ -421,7 +421,7 @@ Map the project's animation library to the token names, not raw values — when
 
 ## Cross-Refs
 
-- `stack.md` — Motion / GSAP / Three.js library specifics (opt-in during Discovery).
+- `stack.md` — Motion / GSAP / Three.js library specifics (opt-in during intake).
 - `modern-css.md` — `@starting-style` for enter-on-mount, View Transitions API.
 - `accessibility.md` — reduced-motion + full interaction rules (keyboard, focus, touch).
 - `../examples/animation-storyboard.md` — multi-stage sequenced animations pattern.

package/assets/skills/design/agemon-design/references/personas.md

@@ -1,6 +1,6 @@
 # Personas — Walkthrough Checklists
 
-Five personas, five journeys. A heuristic score says what's wrong in the abstract. A persona walkthrough says *who* it breaks for. Use these as overlays on top of `heuristics.md`: same UI, five different lenses.
+Five personas, five journeys. A heuristic finding says what's wrong in the abstract. A persona walkthrough says *who* it breaks for. Use these as overlays on top of `heuristics.md`: same UI, five different lenses.
 
 Each persona has a checklist. Every un-ticked box is a finding. Rank findings using the same impact tags from `heuristics.md` (`blocks-conversion`, `adds-friction`, `reduces-trust`, `minor-polish`).
 
@@ -190,7 +190,7 @@ Each persona has a checklist. Every un-ticked box is a finding. Rank findings us
 
 ## How to Use
 
-Invoked by `/ui-craft:heuristic <target> --persona=<name>`:
+Invoked by a heuristic review (`/agemon-design review`) that names a persona:
 
 | Arg | Persona | Loads |
 |-----|---------|-------|
@@ -201,6 +201,6 @@ Invoked by `/ui-craft:heuristic <target> --persona=<name>`:
 | `--persona=margo` | One-thumb Margo | Section 5 |
 | `--persona=all` | All five | All sections |
 
-Output format: same scorecard shape as `heuristics.md` (rows of `| Checklist item | Pass/Fail | Finding | Impact |`). End with top 3-5 findings ranked by impact tag.
+Output format: same findings shape as `heuristics.md` (rows of `| Checklist item | Element | Viewport | Finding | Impact |`), one row per problem found. End with top 3-5 findings ranked by impact tag.
 
-Persona walkthroughs do not replace the Nielsen + Design Laws pass — they supplement it. A UI can score well on Nielsen and still fail Kwame.
+Persona walkthroughs do not replace the Nielsen + Design Laws pass — they supplement it. A UI can hold up on Nielsen and still break for Kwame.

package/assets/skills/design/{agemon-design-dashboard/SKILL.md → agemon-design/references/preset-dashboard.md}

@@ -1,10 +1,6 @@
----
-name: agemon-design-dashboard
-description: "Dense dashboard / admin / Bloomberg / Retool / data-heavy internal tools. Locked knobs: CRAFT=7, MOTION=3, DENSITY=9. IBM Plex + mono numbers, semantic palette, 4/8px grid, sparklines, tabular-nums. Trigger on: dashboard, admin panel, data-dense, analytics, Bloomberg-like, Retool-like."
-argument-hint: "[action: build|review|polish] [target]"
----
+# Preset: Dense dashboard
 
-# UI Craft — Dense Dashboard
+Use this preset only when the user names this look. It is a starting vocabulary for that request, never a default, and the project's brand still wins.
 
 Pre-committed dense style: data-first, keyboard-first, operator tools. Bloomberg, Retool, Linear issues view, admin panels. Every pixel earns its place.
 
@@ -14,7 +10,7 @@ Pre-committed dense style: data-first, keyboard-first, operator tools. Bloomberg
 - **MOTION_INTENSITY = 3** — micro-only. Row hover, row active tint, inline confirm. No scroll reveals in table areas.
 - **VISUAL_DENSITY = 9** — tight 4/8px grid; whitespace earns its place.
 
-Do not re-ask these in Discovery. Confirm brand accent + dark/light preference only.
+Do not re-ask these during intake. Confirm brand accent + dark/light preference only.
 
 ## Style anchors
 
@@ -29,13 +25,13 @@ Do not re-ask these in Discovery. Confirm brand accent + dark/light preference o
 
 ## Base rules (inherited)
 
-All rules in `../agemon-design/SKILL.md` apply. This file overrides knob defaults and adds style-specific guidance below. The anti-slop and craft tests still apply in full.
+The hard rules in `SKILL.md` and [core-rules.md](core-rules.md) apply. This file overrides knob defaults and adds style-specific guidance below. The anti-slop and craft tests still apply in full.
 
 ## Style-specific overrides
 
 **Typography**
 
-- UI: IBM Plex Sans or Inter, 400 / 500.
+- UI: the project's UI font. With none, choose a face built for dense data from the brief and say why; 400 / 500.
 - Mono: IBM Plex Mono or Geist Mono for IDs, hashes, timestamps, code, version numbers, kbd.
 - Body size: 13-14px default; 12px in dense tables is fine.
 - `tabular-nums` on every numeric column, metric card, timestamp, duration.
@@ -88,7 +84,7 @@ All rules in `../agemon-design/SKILL.md` apply. This file overrides knob default
 
 ## Reference files to read first
 
-Load these from `../agemon-design/references/`:
+Load these from this folder:
 
 - `dashboard.md` — primary reference; metric cards, charts, sidebar, tables
 - `typography.md` — tabular-nums, mono pairing, scale
@@ -99,14 +95,14 @@ Skip `inspiration.md` (landing-page focused), `sound.md`.
 
 ## Anti-patterns for THIS style
 
-- Serif fonts anywhere in chrome or data. Editorial is a different variant.
+- Serif fonts anywhere in chrome or data. Editorial is a different preset.
 - Proportional figures in numeric columns — always `tabular-nums`.
 - Saturated hues — reads as consumer app, not operator tool.
 - Colored pills on every delta — plain text in semantic color.
 - Pie charts, donut charts, 3D charts. Ever.
 - Vertical bar chart for time-series — use area/line.
 - Uniform colored top borders on metric cards.
-- Card grids with heavy whitespace — if it feels airy, wrong variant.
+- Card grids with heavy whitespace — if it feels airy, wrong preset.
 - Full-dark sidebar (common AI pattern) — subtle tint only.
 - Scroll-triggered reveals or stagger animations in table areas.
 - Hidden keyboard shortcuts — always surface `⌘K`, row shortcuts, help trigger.

package/assets/skills/design/{agemon-design-editorial/SKILL.md → agemon-design/references/preset-editorial.md}

@@ -1,10 +1,6 @@
----
-name: agemon-design-editorial
-description: "Editorial / magazine / long-form / Medium / Substack / content-heavy UIs. Locked knobs: CRAFT=9, MOTION=4, DENSITY=3. Serif display + humanist body, wide reading column, drop caps, OpenType. Trigger on: editorial, magazine, long-form, blog, Medium-like, Substack-like."
-argument-hint: "[action: build|review|polish] [target]"
----
+# Preset: Editorial
 
-# UI Craft — Editorial
+Use this preset only when the user names this look. It is a starting vocabulary for that request, never a default, and the project's brand still wins.
 
 Pre-committed editorial style: magazine, long-form, content-first. Typography carries the hierarchy; layout serves the reading experience.
 
@@ -14,7 +10,7 @@ Pre-committed editorial style: magazine, long-form, content-first. Typography ca
 - **MOTION_INTENSITY = 4** — reading-aware: fade on reveal, link hovers, no entrance stagger.
 - **VISUAL_DENSITY = 3** — wide reading column, generous vertical rhythm, 1 item per row for features.
 
-Do not re-ask these in Discovery. Confirm accent + serif/sans pairing only.
+Do not re-ask these during intake. Confirm accent + serif/sans pairing only.
 
 ## Style anchors
 
@@ -29,7 +25,7 @@ Do not re-ask these in Discovery. Confirm accent + serif/sans pairing only.
 
 ## Base rules (inherited)
 
-All rules in `../agemon-design/SKILL.md` apply. This file overrides knob defaults and adds style-specific guidance below. The anti-slop and craft tests still apply in full.
+The hard rules in `SKILL.md` and [core-rules.md](core-rules.md) apply. This file overrides knob defaults and adds style-specific guidance below. The anti-slop and craft tests still apply in full.
 
 ## Style-specific overrides
 
@@ -75,7 +71,7 @@ All rules in `../agemon-design/SKILL.md` apply. This file overrides knob default
 
 ## Reference files to read first
 
-Load these from `../agemon-design/references/`:
+Load these from this folder:
 
 - `typography.md` — the primary reference for this style
 - `layout.md` — reading column, rhythm, hierarchy

package/assets/skills/design/{agemon-design-minimal/SKILL.md → agemon-design/references/preset-minimal.md}

@@ -1,10 +1,6 @@
----
-name: agemon-design-minimal
-description: "Minimal / clean / Linear / Notion / Vercel / whitespace-heavy UIs. Locked knobs: CRAFT=8, MOTION=3, DENSITY=2. Monochrome + one accent, Inter/Geist, hairline borders over shadows. Trigger on: minimal, clean, Linear-like, Notion-like, Vercel-like, whitespace-heavy."
-argument-hint: "[action: build|review|polish] [target]"
----
+# Preset: Minimal
 
-# UI Craft — Minimal
+Use this preset only when the user names this look. It is a starting vocabulary for that request, never a default, and the project's brand still wins.
 
 Pre-committed minimal style: editorial clean, Linear / Notion / Vercel. Whitespace is the composition. One accent, hairline borders, almost no motion.
 
@@ -14,12 +10,12 @@ Pre-committed minimal style: editorial clean, Linear / Notion / Vercel. Whitespa
 - **MOTION_INTENSITY = 3** — hover + modal enter/exit only. No scroll reveals, no page transitions, no stagger.
 - **VISUAL_DENSITY = 2** — whitespace-heavy, 1-2 items per row, generous gutters.
 
-Do not re-ask these in Discovery. Skip straight to accent + font confirmation if ambiguous.
+Do not re-ask these during intake. Skip straight to accent + font confirmation if ambiguous.
 
 ## Style anchors
 
 - Black or near-black type on white or near-white canvas. Monochrome + ONE accent.
-- Inter / Geist for body — never a display font.
+- A neutral sans for body, taken from the project or chosen from the brief (state why) — never a display font.
 - Section padding 120-200px vertical, 40-80px gutters.
 - Hairline borders `1px solid oklch(92% 0.005 250)` in place of shadows.
 - Typography is the hierarchy. No decorative gradients, patterns, or glass.
@@ -29,13 +25,13 @@ Do not re-ask these in Discovery. Skip straight to accent + font confirmation if
 
 ## Base rules (inherited)
 
-All rules in `../agemon-design/SKILL.md` apply. This file overrides knob defaults and adds style-specific guidance below. The anti-slop and craft tests still apply in full.
+The hard rules in `SKILL.md` and [core-rules.md](core-rules.md) apply. This file overrides knob defaults and adds style-specific guidance below. The anti-slop and craft tests still apply in full.
 
 ## Style-specific overrides
 
 **Typography**
 
-- Body: Inter or Geist, 400 weight. UI emphasis: 500. Never 600/700 in body copy.
+- Body: the project's sans, or one chosen from the brief, 400 weight. UI emphasis: 500. Never 600/700 in body copy.
 - `system-ui, -apple-system` as fallback stack.
 - Headings: `tracking-tight` / `-0.02em` above 24px, 500 or 600 max.
 - `text-wrap: balance` on headings, `text-wrap: pretty` on paragraphs.
@@ -75,7 +71,7 @@ All rules in `../agemon-design/SKILL.md` apply. This file overrides knob default
 
 ## Reference files to read first
 
-Keep the reading list tight. Load only these from `../agemon-design/references/`:
+Keep the reading list tight. Load only these from this folder:
 
 - `layout.md` — spacing, hierarchy, composition
 - `typography.md` — scale, readability, weight
@@ -92,6 +88,6 @@ Skip `dashboard.md`, `stack.md`, `sound.md` unless explicitly relevant.
 - Scroll-triggered reveals, stagger, page transitions — even "subtle" ones.
 - Uniform 3-column icon-heading-text feature grids.
 - Colored shadows or glows as affordances.
-- Dense layouts. If density feels right, this is the wrong variant — switch to `agemon-design-dashboard`.
+- Dense layouts. If density feels right, this is the wrong preset — switch to [preset-dashboard.md](preset-dashboard.md).
 - Pill backgrounds on nav links or buttons by default; prefer text + underline.
 - Section padding under 96px on desktop.

package/assets/skills/design/agemon-design/references/principles-catalog.md

@@ -1,6 +1,6 @@
 # Principles Catalog
 
-A worked-example bank of opinionated design principles, organized by product category. Use as seed material for the principles workshop in `/brief`. Do not adopt these literally — adapt to your specific product, user, and constraints. The point is to see what opinionated, actionable, distinctive principles look like in practice. Many entries are product-specific manifestations of the heuristics in `heuristics.md` — they complement the scored methodology, they don't replace it.
+A worked-example bank of opinionated design principles, organized by product category. Use as seed material for the principles workshop in `/agemon-design brief`. Do not adopt these literally — adapt to your specific product, user, and constraints. The point is to see what opinionated, actionable, distinctive principles look like in practice. Many entries are product-specific manifestations of the heuristics in `heuristics.md` — they complement the checklist, they don't replace it.
 
 ---
 
@@ -155,7 +155,7 @@ Test against past decisions. Take three real design calls that were debated. Wou
 
 #### "Comparison is the unit of understanding"
 **Statement:** a number without context is noise; every metric shows its comparison.
-**Implication:** primary metrics always show period-over-period change (vs. prior week, vs. target). Sparklines on every metric card. Trend direction is signaled by color and icon, not just a number. Tables have inline comparison columns. No standalone counts without a denominator or a delta.
+**Implication:** primary metrics always show period-over-period change (vs. prior week, vs. target). A sparkline only where the trend is the point; otherwise the delta as text. Trend direction is signaled by color and icon, not just a number. Tables have inline comparison columns. No standalone counts without a denominator or a delta.
 **Opposite ruled out:** "show current state; let users query for comparison" — requiring users to manually request comparison on every visit is an analysis tax. Comparison belongs in the default view.
 
 #### "Drill-down is always one click"
@@ -275,7 +275,7 @@ These are platitudes that masquerade as principles. They look opinionated but ru
 - **"Modern design"** — modern compared to what, when? This is an aesthetic preference with no design resolution power.
 - **"We care about our users"** — a mission statement, not a principle. Put it in the README, not the brief.
 
-A principle that produces no design implication and rules out no alternative is a slogan. Slogans go in marketing copy, not in `.ui-craft/brief.md`.
+A principle that produces no design implication and rules out no alternative is a slogan. Slogans go in marketing copy, not in the brief.
 
 ---