@event4u/agent-config 14.23.0 → 16.0.0

package/dist/agent-src/guidelines/design-fidelity-mechanics.md

@@ -0,0 +1,293 @@
+# Design Fidelity — Mechanics
+
+> Surgical-edit discipline, asset & imagery floor, and the failure-mode catalog for the `design-fidelity` rule
+
+_Origin: migrated from `src/rules/design-fidelity.md` per the P4 pattern of `road-to-kernel-and-router.md`. The Iron Law, the `design.fidelity_mode` strictness table, and the fire/not-fire scope stay in the rule; this file carries the illustrative depth._
+
+## Data-basis ladder
+
+```
+WHENEVER SOURCE IS REACHABLE, THE SOURCE IS THE DATA BASIS.
+A SCREENSHOT IS VALIDATION, NEVER THE INPUT YOU BUILD FROM,
+WHILE ANY HIGHER RUNG IS REACHABLE.
+```
+
+Four rungs, highest first. Take the highest one you can reach; a lower rung is
+a fallback you name, not a preference you exercise.
+
+| # | Rung | What it is | When it is the right rung |
+|---|---|---|---|
+| 1 | **Provided source files** | The artifact itself — an archive, an attached `design.html`, a token sidecar, a repo the user pointed at | Whenever the user handed something over. Read it *before* the first write. |
+| 2 | **Source read through any channel** | The same code reached indirectly — a repository read, or DOM / stylesheets / scripts pulled through the user's own connected browser tools | The artifact is live rather than attached (a URL, a staging page, a preview build) |
+| 3 | **Structured snapshot** | An accessibility tree or equivalent structured dump — text, roles, hierarchy, no pixels | Source is genuinely unreachable, but structure is not |
+| 4 | **Screenshot** | Rendered pixels | Nothing above is reachable, **or** the thing being checked only exists once rendered |
+
+**What rung 4 is legitimately for**, and this is not a grudging exception:
+visual validation after building, layout collisions, contrast as actually
+rendered, and content that only exists dynamically. The failure this ladder
+names is not *using* a screenshot — it is using one **as the data basis while
+rung 1 or 2 was sitting right there**, which is how a port ends up with the
+right colours and none of the behaviour.
+
+**The ladder governs where data comes from, never whether defects may be
+fixed.** Reading the source and improving it is allowed and often correct;
+reading the source is what makes an improvement a decision rather than a guess.
+
+Two consequences worth stating because they are the ones agents get backwards:
+
+- **A rendered HTML file is still a code artifact.** Opening it in a browser
+  does not demote it to rung 4; the file is still rung 1. What the browser adds
+  is validation, not input.
+- **Degrading is honest, silence is not.** When you build from rung 3 or 4, say
+  which rung you used and why the higher ones were unreachable. An unscoped
+  "matches the design" over a screenshot-derived build is a verdict without
+  evidence (`design-review` § verdict scoping).
+
+Regression witness: `daf-source-over-screenshot`.
+
+## URL / live-page handover — extraction into files, before the first UI write
+
+```
+A HANDOVER THAT ARRIVES AS A URL IS STILL RUNG 2, NOT RUNG 4.
+EXTRACT THROUGH THE USER'S CONNECTED BROWSER TOOLS INTO FILES
+BEFORE ANY UI WRITE. A SCREENSHOT TAKEN DURING EXTRACTION
+CARRIES QA DUTY ONLY — IT IS NEVER THE THING YOU BUILD FROM.
+```
+
+A published artifact link, a builder's share link, a staging or `localhost`
+page: rung 2 above is reachable, so rung 4 is not the fallback it looks like.
+Extraction lands in the existing `design-system.json` contract under the
+`.claude/design-system/` prefix the rule already routes on — no new artifact
+shape — and the offline `/design-system:import` adapter consumes it. The package
+ships the contract, the adapter and the instructions; it ships no crawler,
+Playwright runtime or font-bundler.
+
+Where the extraction goes, what consumes it, the retrieval order that keeps the
+source alive across sessions, the producer sentence, and the honest coverage
+gap: [`design-handover-extraction`](design-handover-extraction.md).
+
+## Adopt the code — re-derivation is a deviation
+
+Where the artifact's own markup, CSS, or JS is stack-compatible, **adapting that
+code is the default**. Writing an equivalent from scratch is a **deviation** and
+carries the same obligation as a swapped control: surface it, get confirmation,
+do not just do it.
+
+Stack translation is not re-derivation. Porting the artifact's structure into
+Blade, JSX or a template language translates *that* structure — it does not
+license a new one. If your output's element tree cannot be walked next to the
+artifact's, you re-derived.
+
+Why this needs saying at all: the visible half of a port (colours, type,
+spacing) is what a reviewer checks, and it survives a from-scratch rewrite. The
+half that does not survive is the behaviour — event handlers, keyframes, ARIA
+wiring, focus order — and its absence is invisible in a screenshot comparison.
+"HTML not adopted, worse markup written from scratch, missing JavaScript" is one
+failure, not three.
+
+### The scope line — where `code-provenance` ends and this begins
+
+```
+A USER-SUPPLIED DESIGN ARTIFACT IS THE USER'S OWN MATERIAL, NOT THIRD-PARTY
+EXTERNAL CODE. ADOPTING IT IS NOT A BORROW.
+THIRD-PARTY CODE THAT MERELY ARRIVES THROUGH A HANDOVER STAYS UNDER
+`code-provenance` IN FULL.
+```
+
+Without this line the two rules contradict each other on the same act:
+[`code-provenance`](../rules/code-provenance.md) opens with `NEVER ADOPT
+EXTERNAL CODE VERBATIM` and routes any conscious borrow through a licence check
+plus a ledger entry, while the duty above says adapt the artifact's code.
+Whichever the agent followed, it would be violating a rule, and no gate can
+arbitrate between two Iron Laws.
+
+The resolution weakens neither, and it is not new: it is the carve-out
+[`content-quoting-floor`](../rules/content-quoting-floor.md) already
+makes for user-owned text — *"content the user wrote, pasted, or explicitly
+authorized for verbatim use is not an external source"*. A design artifact the
+user hands over is that same category, in markup.
+
+**What stays under `code-provenance` in full**, so the carve-out cannot be read
+as a hole:
+
+- A vendored component, a licensed template, or a third-party library that
+  happens to be *inside* the handover. Arriving through a design handover
+  changes nothing about its licence.
+- Code the artifact itself borrowed from somewhere identifiable.
+- Anything you reach for *beyond* the artifact while implementing it.
+
+The discriminator is authorship, not delivery: did the user hand you their own
+material, or did they hand you a container with someone else's material in it?
+
+Regression witness: `daf-rederive-is-deviation`.
+
+## Surgical visual edits
+
+A request to change one visual thing — a colour, a label, a single element — is
+a **targeted edit**, not a redesign licence. Apply the same
+`minimal-safe-diff` discipline to design work that backend edits have
+always owed.
+
+- **Change only the semantic target.** Preserve the surrounding layout,
+  spacing, typography, dimensions, content, animation, and interaction states.
+  Do not rewrite the component, reflow the section, or "modernise" neighbours
+  while you are in there. (fixtures: `daf-edit-preservation`, `daf-unwanted-variations`.)
+- **A broader redesign needs an explicit trigger.** Only phrases like *"new
+  direction"*, *"from scratch"*, *"make it feel premium"*, *"rework the flow"*,
+  or *"give me variations / options"* license a from-scratch rework. Absent such
+  a phrase, a "fix / change / update the X" request is surgical — when unsure
+  which, ask (`ask-when-uncertain`). (fixture: `daf-redesign-trigger`.)
+- **Preserve stable anchors.** Where the host exposes DOM/comment metadata, keep
+  comment anchors and screen labels intact so the edit stays locatable. Where
+  the host has no such surface, preserve stable semantic anchors already present
+  in source comments / `data-*` attributes — never strip them, and do not invent
+  new ones.
+
+## Asset & imagery discipline
+
+Visual artifacts carry **real assets or honest placeholders — never fabricated
+brand evidence**. The design-surface instance of the no-invented-facts floor.
+
+Owned-asset paths, the third-party delivery decision this repository pins to
+self-hosting ([`ADR-205`](../decisions/ADR-205-webfont-delivery-ownership.md)),
+the real-imagery-as-proof floor, the iconography floor and the
+no-unrequested-filler clause — each with its `daf-*` fixture:
+[`design-asset-discipline`](design-asset-discipline.md).
+
+## Artefact maturity — the second axis
+
+The Iron Law and both discriminator clauses stay in
+[`design-fidelity`](../rules/design-fidelity.md) § Two axes; this is the table.
+
+| The artefact declares | The spec is | The spec is NOT |
+|---|---|---|
+| low fidelity — greyscale, box-and-line, placeholder copy | layout · element set · hierarchy · states shown | grays · placeholder text · borders · exact spacing |
+| finished — colour, real copy, real assets | everything visible (the 1:1 floor, unchanged) | — |
+
+Grounded in [`wireframe`](../skills/wireframe/SKILL.md) § Gotchas. The near-miss
+class is pinned in `ROUTING_MATRIX`, its rationale beside the assertions in
+`design_fidelity_routing.test.ts`.
+
+## Provided-artifact precedence
+
+```
+PROVIDED ARTIFACT  >  ANTI-SLOP  >  HOUSE TASTE
+                   >  ANY GENERATIVE DESIGN-SYSTEM TOOLING, FIRST- OR THIRD-PARTY.
+THE EXEMPTION COVERS ONLY DECISIONS THE ARTIFACT ACTUALLY COVERS.
+IT NEVER COVERS GENERATIVE WORK IN THE SAME RUN.
+```
+
+The anti-slop catalog exists to stop an agent's *first impulse* from becoming
+the design. A handed-over artifact is not a first impulse — it is a decision
+the user already made. Applied to a port, the catalog inverts: it argues the
+agent out of the spec it was told to reproduce.
+
+Concretely, a faithful port of a cream/terracotta artifact trips
+`slop-c5-cream-palette`, and the artifact's own copy trips
+`slop-cp1-em-dash`. Both findings are **correct about the pattern and wrong
+about the action**. On a port they are cited as *"matches provided spec"* and
+nothing acts on them.
+
+**Scope — three things this does NOT license:**
+
+1. **Decisions the artifact does not cover.** A port usually needs states the
+   source never showed (loading, error, empty). Those are generative, and the
+   full anti-slop scan applies to them. "The artifact was cream" does not
+   exempt an invented empty state from L1 or V1.
+2. **Silence.** An artifact-covered finding stays in the review output with its
+   rule id, marked informational. Suppressing it outright would hide from the
+   user that their spec carries a known tell — which they may want to know
+   before shipping it.
+3. **Registered brand tokens.** A supplied artifact outranks house taste, not
+   the consumer's own brand (`brand-source-of-truth`). Artifact-vs-brand
+   conflicts are surfaced, never merged.
+
+### The precedence chain's fourth member, and why it is not obvious
+
+A generative design-system
+skill — this suite's own or a third party's installed beside it — can carry an
+instruction of the shape *"always generate a design system first"*. On a
+greenfield brief that is right. On a **port** it is the same error the anti-slop
+catalog makes: it argues the agent out of a decision the user already made, and
+it does so from a step that runs *before* the artifact is even read, so nothing
+downstream ever gets the chance to override it. A generative step's output may
+inform decisions the artifact leaves open — states it never showed, a breakpoint
+it never specified — and nothing more. It never re-opens a decision the artifact
+carries.
+
+This is a precedence clause, not a ban: the generative tooling stays correct
+where it was already correct. What it loses is the authority to run *instead of*
+reading a supplied artifact.
+
+**The mechanical half.** A review finding carries `artifact_covered: true`, and
+the polish gate drops those from the round-driving set *before* the ceiling
+check, so a port cannot burn its two rounds on findings it was never allowed to
+act on (`directives/ui/polish.ts`, `partition_artifact_covered`). Marking rather
+than deleting is deliberate: the finding stays visible, only its authority to
+force a round is removed. The burden sits with whoever sets the flag — an
+unmarked finding is treated as actionable, so the default failure direction is
+"we asked" rather than "we silently kept it".
+
+Regression witness: `daf-slop-vs-provided`.
+
+**Why the default is what it is, and why the 2026-07-31 council lock over this
+loop cannot be discharged by measuring it:**
+[`design-reconciliation § The 2026-07-31 lock`](design-reconciliation.md).
+
+## Value-level provenance — the finer grain beside the flag
+
+The block above is finding-level and stays the default: `artifact_covered` is a
+boolean on a **finding**, and every consumer of it — `partition_artifact_covered`
+and the ceiling check it feeds — is unchanged by this section.
+
+What a per-finding boolean cannot answer is *"where did this `16px` come from"*.
+The flag says a finding is answered by the artifact; it does not say which value
+carried the expectation, so two rows that disagree about the same element look
+identical to a reviewer.
+
+`src/scripts/schemas/fidelity-measurement-sheet.schema.json` adds that grain and
+nothing else: each measurement row carries `expectation_source` — a `kind`
+ordered by authority (`provided_artifact` › `design_token` › `brand_token` ›
+`house_heuristic` › `agent_inference`) plus a `ref` naming the token, `file:line`
+or artefact anchor. `agent_inference` is the row a reviewer filters for.
+
+Two boundaries, because this is an addition and not a replacement:
+
+- **The coarse flag stays the default channel.** A row's optional
+  `expectation_source.artifact_covered` mirrors the flag for one value; it never
+  substitutes for setting the flag on the finding, and no gate reads it.
+- **The ordering above is a mirror, not a second source of truth.** Precedence
+  is decided in the block above; a `kind` that disagreed with it would be a
+  defect in the schema, not a competing chain.
+
+## Failure modes
+
+- Swapping the prototype's font / typeface because another "reads better".
+- Replacing a specified control (slider, stepper, chip) with a different control.
+- Dropping or adding an element the prototype shows ("+", a send→stop toggle, a warning chip).
+- Restructuring layout or moving sections "because the flow is better".
+- Treating an internal "honesty gate" or "stub" concern as licence to redesign the UI.
+- Re-running a redesign after the user already said "match the prototype".
+
+## How to surface a deviation — do NOT execute it
+
+Name what the spec shows, what you would change, and why — as a numbered option
+per `user-interaction`. The user picks. Honesty about **behaviour** (a control
+not yet wired) never licenses changing the **design**: a faithful visual plus a
+labelled "not wired yet" note beats an invented redesign.
+
+## Fixtures
+
+Behavioral baseline: the `daf-*` fixtures named above (edit preservation,
+unwanted variations, redesign trigger, missing asset, external asset URL,
+invented screenshot), plus the port family this guideline governs —
+`daf-source-over-screenshot` (data basis), `daf-adhoc-port-coverage` (loss
+reporting outside the engine), `daf-rederive-is-deviation` (adopt the code),
+and `daf-handoff-bundle`, the bundle shape where a token sidecar makes
+"honoured the contract" and "eyeballed the CSS" produce different artefacts.
+
+## See also
+
+- `design-fidelity` (rule) — Iron Law + `design.fidelity_mode` strictness table.
+- `brand-source-of-truth` / `brand-consistency` — same precedence shape, for registered brand tokens.
+- [`design-modes.md`](design-modes.md) — brand vs product register discriminator.

package/dist/agent-src/guidelines/design-fidelity-routing.md

@@ -0,0 +1,78 @@
+# Design-fidelity routing mechanics — how the trigger set is authored
+
+Split out of [`design-fidelity-mechanics`](design-fidelity-mechanics.md) on
+2026-09-09 under `check_depth_budget`'s 16,000-character per-file ceiling. It is
+also a genuinely different subject: that guideline is read while PORTING an
+artifact, and this one is read while EDITING the rule's own trigger set — which
+happens rarely, by a maintainer, and never during a port.
+
+## Routing mechanics
+
+Migrated out of `design-fidelity.md` on 2026-09-09 under the council verdict on
+`blocker: rule-body-cap` — a semantic migration that frees rule-body lines for
+the operative pointers the same verdict requires, not an arbitrary line cut. The
+rule keeps the obligations; this holds the reasoning behind them.
+
+### The withdrawn builder-URL trigger
+
+A page built in Lovable / v0 / bolt and handed over as a share link is a
+finished spec, and `design-fidelity` does not route it. The obvious trigger was
+tried and **withdrawn**: matching is plain lower-cased substring containment, so
+`https://v0.dev/` also fires on `https://v0.dev/docs`, on a pricing page, and on
+a changelog link — it would treat every mention of the tool's own site as a spec
+handover. That is exactly the `claude.ai` failure the capability-URL trigger
+exists to avoid, and by the rule's own standard it is worse than the gap it
+closes. The alternatives are a bare-host keyword (broader still) or guessing
+each vendor's share-path segment, and a trigger built on a guessed path is not
+evidence.
+
+**What closes it:** a verified share-path segment per vendor, or a
+handover-word co-occurrence the matcher cannot express today. Until then the
+class needs one word in the prompt, like any other unlisted filename.
+`near-bare-host-mention` in `ROUTING_MATRIX` pins the bare-host direction silent
+so a future attempt cannot reintroduce the broad form unnoticed.
+
+### The trigger set, class by class
+
+Phrase-heavy on the German side and on `artifact` deliberately: a bare
+`artifact` keyword fires on *"the CI build artifact is 40 MB"*, which is CI
+vocabulary and not a handover. `ROUTING_MATRIX` pins both halves — every class
+that must route, and every near-miss that must stay silent (fixture
+`daf-port-trigger-de`).
+
+Each shipped class carries its own near-miss row, and the pairing is the
+contract rather than a courtesy:
+
+| Class | Its near-miss row | The direction that row tests |
+|---|---|---|
+| `phrase: claude.site/artifacts` | `near-claude-ai-chat-link` | a bare `claude.ai` chat link is a conversation reference, not a spec |
+| `path_prefix: .claude/design-system/` | `near-generic-design-system-dir` | a bare `design-system/` is a normal source folder in a large fraction of frontend repos |
+| `file_pattern: *.dc.html` | `near-plain-html-open-file`, `near-dc-in-a-filename` | an ordinary `.html` file in the tree; a filename that merely contains the letters |
+| the withdrawn builder URL | `near-bare-host-mention` | left behind on purpose, so the broad form stays pinned silent |
+
+### Write the near-miss row first — and test the right direction
+
+Extending the trigger set without adding a near-miss row is how an over-broad
+trigger lands. The stronger half of the contract is *which* near-miss:
+
+**The row must test the direction the NEW trigger opens, not a direction that
+was already closed.** The withdrawn class is the worked example. Its first
+near-miss row tested a protocol-less mention — silent *before* the change, and
+therefore incapable of catching the over-broadness the change introduced. The
+row that would have caught it is `near-builder-host-non-handover-url`, a
+documentation URL on the same host, and it exists only because a review asked
+for it after the trigger had already shipped.
+
+Applied on the next trigger to land: `*.dc.html` (the Claude Design canvas
+artboard, which `*design.html` cannot match because it compiles to
+`^(?:.*design\.html)$`) shipped with `near-plain-html-open-file` and
+`near-dc-in-a-filename` written **before** it, both testing the direction it
+opens — an ordinary `.html` file in the tree, and a filename that merely
+contains the letters. Both were confirmed red-then-green against the real
+matcher rather than asserted.
+
+## See also
+
+- [`design-fidelity-mechanics`](design-fidelity-mechanics.md) — the porting half.
+- `tests/scripts/design_fidelity_routing.test.ts` — `ROUTING_MATRIX`, which is
+  the measurement this file describes rather than a second copy of it.

package/dist/agent-src/guidelines/design-handover-extraction.md

@@ -0,0 +1,117 @@
+# Design Handover — URL / live-page extraction
+
+> Where a URL handover gets extracted to, what consumes it, and in what order it is read back
+
+_Split out of [`design-fidelity-mechanics`](design-fidelity-mechanics.md) § URL / live-page handover, which carries the obligation surface and routes here. The split is the per-file depth ceiling doing its job: the mechanics file sat at 14.2k of its 16k budget, and compressing this material to fit would have cost the parts that make it actionable._
+
+```
+A HANDOVER THAT ARRIVES AS A URL IS STILL RUNG 2, NOT RUNG 4.
+EXTRACT THROUGH THE USER'S CONNECTED BROWSER TOOLS INTO FILES
+BEFORE ANY UI WRITE. A SCREENSHOT TAKEN DURING EXTRACTION
+CARRIES QA DUTY ONLY — IT IS NEVER THE THING YOU BUILD FROM.
+```
+
+When the artifact is handed over as a **URL** rather than a file — a published
+artifact link, a builder's share link, a staging or `localhost` page — rung 2 of
+the [data-basis ladder](design-fidelity-mechanics.md#data-basis-ladder) is
+reachable and rung 4 is not the fallback it looks like. Pull the DOM,
+stylesheets, scripts and assets through the browser tools the user has
+connected, and land them as files first.
+
+## Where the extraction lands
+
+Into `design-system.json` under `.claude/design-system/` — the `path_prefix` the
+`design-fidelity` rule already routes on. That file is an **existing contract**,
+specified in
+[`design-system-json.md`](../skills/design-system-capture/references/design-system-json.md);
+this guideline defines no format of its own. Raw source files land beside it,
+and screenshots taken while extracting land in a references directory next to
+them.
+
+## What consumes it
+
+[`/design-system:import`](../../src/domains/engineering-base/design-system/import/command.md)
+runs the extraction output through the three-lane adapter
+(`native` / `dtcg` / `dembrandt`) into the contract shape, then hands it to
+`design-system-capture`'s per-field import. The adapter is **offline** — it
+reads a file and writes the contract shape; it never fetches, crawls, or
+launches a browser.
+
+## The lock boundary — stated here because this is where an agent would cross it
+
+The package ships the contract, the adapter, and the instructions. It does
+**not** ship the crawler, the Playwright runtime, or a font-bundler. Extraction
+runs through the user's own connected tooling, and its output is *observed, not
+authoritative*: every field is confirmed by the human, and a value conflicting
+with a registered brand token is flagged rather than applied
+(`brand-source-of-truth`).
+
+## Retrieval order — so the source survives the session
+
+Check in this order and stop at the first hit. The point is that the next
+session reads a file instead of re-screenshotting the same page.
+
+| # | Source | Why it ranks here |
+|---|---|---|
+| 1 | The project's own `design-system.json` | Already confirmed by a human in an earlier session — the only rung whose values someone signed off on |
+| 2 | A previous extraction artifact under `.claude/design-system/` | Observed and file-backed; re-reading it costs nothing and re-extracting may drift |
+| 3 | The live page | Authoritative for *today's* page, but only reachable while it is up and the tooling is connected |
+
+**Persistence is not restated here.** Skip-if-exists unless explicitly forced,
+and never silently discarding a prior confirmed decision, are owned by
+[`/design-system:generate`](../../src/domains/engineering-base/design-system/generate/command.md)
+— *"never overwrite a confirmed `DESIGN.md`"*, *"Never persist silently."* This
+guideline states the order; that command states what happens on a collision, and
+stating it twice is how the two drift apart.
+
+## The producer sentence
+
+The documented easy path is a connected extractor MCP, attached once and reused.
+Where none is available, the manual Chrome-DevTools-MCP channel is the fallback,
+and where neither is reachable the handover degrades to rung 3 or 4 — which the
+ladder requires you to **name**, not to pass off as a source-based build.
+
+## Coverage — stated honestly
+
+No fixture scores this class yet. `daf-source-over-screenshot` scores the rung
+choice on an *attached* artifact, not a URL handover.
+
+**Its blocking reason changed on 2026-08-23 and the new one is narrower.** It was
+SKIPPED since 2026-08-13 "for want of a page-reaching capture primitive". That
+primitive now exists — `agent-config ui:render`, a Class-A headless capture at
+desktop / 375 px / 320 px, executed against a real fixture. So the fixture is no
+longer blocked on a missing capability; it is **unscored**, pending a live eval
+run that puts an agent through an artifact port and judges the rung it chose.
+
+The discipline is unchanged and still binds: claiming a regression witness before
+that run would be the fabrication this package's evidence discipline exists to
+prevent. What moved is which sentence is true — "we cannot measure this" became
+"we have not measured this yet", and those are different claims.
+
+### The skip register — every fixture gated on the same primitive
+
+`daf-source-over-screenshot` is no longer the only one, so the reason string is
+recorded once here rather than restated per fixture. Every row below is
+**SKIPPED** with `b-page-capture-primitive` as its reason, and none is silently
+absent:
+
+| Fixture | Registered | Reason |
+|---|---|---|
+| `daf-source-over-screenshot` | 2026-08-13 | `b-page-capture-primitive` |
+| `daf-render-absent-scoped` | 2026-08-23 | `b-page-capture-primitive` — its render-dependent assertions only; the static-scope assertions run and pass |
+| `daf-render-absent-control` | 2026-08-23 | `b-page-capture-primitive` — synthesises `render_ok: true` as state rather than rendering, and says so |
+
+**Probed, not assumed** (2026-08-23). The `playwright` library resolves in this
+tree, which reads as a capture primitive until you run it: launching chromium
+fails with *"Executable doesn't exist at
+…/chromium_headless_shell-1234/chrome-headless-shell"*. The library is present
+and **no browser binary is installed**, so the primitive is
+`not-available: headless-browser-binary`. Recorded as execution evidence because
+"playwright is in node_modules" is exactly the inference that would have made a
+fabricated witness look justified.
+
+## See also
+
+- [`design-fidelity-mechanics`](design-fidelity-mechanics.md) — the data-basis ladder this operationalises, and the adopt-the-code duty that governs what you do with the extracted source.
+- [`design-fidelity`](../rules/design-fidelity.md) — the rule; a provided artifact is the spec.
+- [`design-system-capture`](../skills/design-system-capture/SKILL.md) — the per-field import the adapter hands off to.

package/dist/agent-src/guidelines/design-modes.md

@@ -0,0 +1,143 @@
+# Design Modes — Brand vs Product
+
+> Reference doc. Pull this when deciding which design skills to prioritize
+> or when the brief is ambiguous about the design register.
+
+## The two registers
+
+Every design task operates in one of two registers. Getting the register
+wrong is the root cause of most AI-generated design failures:
+
+| | Brand mode | Product mode |
+|---|---|---|
+| **Core thesis** | The impression IS the product | Design serves the task |
+| **Primary failure** | Flatness / genericness — looks like every other AI startup | Strangeness without purpose — "clever" choices that obscure the tool |
+| **The user's question** | "How was this made?" (genuine curiosity) | "Where do I click?" (the tool disappears into the task) |
+| **Key skill cluster** | `brand-identity`, `iconography`, `fe-design § Aesthetic direction`, `design-intelligence` | `accessibility-auditor`, `ui-component-architect`, `fe-design § Table/Form Design` |
+| **Typography strategy** | Distinctive pairing — two contrasting families, deliberate tracking | One reliable family — predictable hierarchy. A default AI font pick (Inter, Roboto, DM Sans, Geist, Space Grotesk, Instrument Serif) is a legitimate product-register choice, and [`design-antipatterns` T7](design-antipatterns.md) scopes itself accordingly — but the register is the reason, so state it: an undeclared Inter is still an undeclared font choice. |
+| **Color strategy** | Brand identity — often unexpected; the palette IS the differentiator | Semantic function — primary/danger/success/neutral; predictable meaning |
+| **Motion strategy** | Expressive — motion reinforces the brand's personality | Utilitarian — motion confirms state changes; nothing decorative |
+| **Spacing strategy** | Breathing room; generous whitespace as a brand signal | Dense/efficient; optimize for information density |
+| **Success criterion** | Originality test: a skeptic can't guess "which AI made this?" | Earned familiarity: the tool disappears; users focus on their task |
+
+## How to determine the register
+
+Ask: **What is the output of this UI being used for?**
+
+- A consumer-facing surface where the FIRST impression determines whether the
+  user trusts/buys → **Brand mode**. The product has 3 seconds; every pixel
+  contributes to the brand's identity.
+
+- An internal tool, dashboard, admin panel, or workflow-critical surface where
+  users return dozens of times per day → **Product mode**. Strangeness wastes
+  their time; predictability builds trust.
+
+- A marketing landing page → **Brand mode**. It has one job: create desire.
+
+- A data entry form → **Product mode**. It has one job: accept correct data.
+
+**Ambiguous cases:** many products have both (a brand-heavy landing page +
+a product-mode dashboard). The register applies per-surface, not per-product.
+When unclear: ask — *"Is the user here to be impressed, or to accomplish a
+task?"*
+
+## The second axis — surface job
+
+The register answers *how expressive may this be*. It does not answer *what is
+this surface for*, and conflating the two is why a persuade surface inside a
+product repo gets dense, utilitarian defaults. So there are two axes, and they
+are independent.
+
+| Surface job | The user's situation | Density | Hierarchy | Expressiveness |
+|---|---|---|---|---|
+| `persuade` | arrived, deciding, will leave in seconds | generous | one dominant claim per viewport | high — this is the job |
+| `operate` | returning, task in mind, wants it done | dense | scannable, predictable, repeated | low — strangeness costs time |
+| `read` | sustained attention on prose or data | measured | typographic, not chrome-led | restrained |
+| `experience` | exploring, no task, willing to be surprised | spacious | narrative, sequential | high, and sequenced |
+
+```
+SURFACE JOB IS PER-SURFACE AND LIVES IN THE SURFACE BRIEF.
+IT IS NEVER READ OFF PRODUCT.md, AND A RUN NEVER WRITES IT THERE.
+```
+
+**Why not in PRODUCT.md.** PRODUCT.md describes the product, and a product has
+many surfaces with different jobs — an investor one-pager and an ops console
+belong to the same product and share no defaults. A run that resolves the job
+from PRODUCT.md flattens the persuade surface into the product register, which
+is the `surface-mode-not-product-mode` near-miss in
+`tests/eval/frontend-corpus/near-miss/`.
+
+**Register stays.** The two axes compose: a `persuade` surface in the `brand`
+register and a `persuade` surface in the `product` register are both persuade
+surfaces, and the register decides how far the expressiveness may go.
+
+**Quality floors do not vary by either axis.** Density, hierarchy and
+expressiveness defaults move; contrast, minimum font size, line length,
+reduced-motion, heading order and focus visibility do not. A floor that moved
+with the surface job would be a preference wearing a floor's name.
+
+The machine-readable form is `surface_mode` in
+[`ui-authority`](../contracts/ui-authority.md), which is also the one place the
+precedence between an explicit instruction, the brief and these defaults is
+written down.
+
+## Brand-mode failure modes
+
+- **Genericness:** Choosing the safe AI-slop palette (cream + brass, purple/violet gradient, three equal cards). The product is invisible in its category. Cross-check with `docs/guidelines/design-antipatterns.md` § Color and Visual.
+- **Inconsistency:** Brand direction picked for the hero, abandoned for the body. The page reads as two different products.
+- **Aesthetics-without-function:** Beautiful but confusing navigation, stunning hero with no CTA clarity.
+
+## Product-mode failure modes
+
+- **Strangeness-without-purpose:** A clever typographic choice that makes the CTA harder to scan. A gradient background on a data table. An animated page transition in an admin panel.
+- **Premature originality:** Reinventing a standard UI pattern (data table, form validation, dropdown) when the standard is what users expect.
+- **Over-engineering:** Five different card elevations in a dashboard that needs two.
+
+## The AI-slop originality self-test (applies to brand mode primarily)
+
+Run BOTH tiers before approving a brand-mode design direction:
+
+**Tier 1 — Category test:**
+Would a designer seeing 20 AI-generated [product category] UIs recognize this
+aesthetic as part of that category's default? (e.g., "SaaS → dark mode + purple
+gradient"; "health app → teal + rounded sans serif + white space").
+- If YES: rework the concept. The design is invisible in its category.
+- If NO: proceed to Tier 2.
+
+**Tier 2 — Anti-reference test:**
+Given the category AND three explicit aesthetics you've avoided — could a
+skeptic still guess the direction? (e.g., "fintech that's not navy-and-gold,
+not minimal white, not brutalist → everyone picks terminal dark").
+- If YES: dig deeper. "Avoiding the worst cliché" is not differentiation.
+- If NO: the direction is genuinely distinctive.
+
+**The bar:** a visitor should ask "how was this made?" not "which AI made this?"
+
+## Routing to skills by mode
+
+**Brand mode brief:**
+1. `design-intelligence` (grounded style/palette/typography selection — run the corpus first)
+2. `brand-identity` (archetype → token system)
+3. `iconography` (icon system selection for brand expression)
+4. `fe-design § Aesthetic direction` (direction → composition → typography → color)
+
+**Product mode brief:**
+1. `existing-ui-audit` (mandatory — inventory first)
+2. `accessibility-auditor` (WCAG compliance from the start)
+3. `ui-component-architect` (reuse existing primitives)
+4. `fe-design § Component Architecture, Form Design, Table Design` (standard patterns)
+
+**Both modes:** `design-antipatterns` (always pull), `design-review` (with anti-slop check)
+
+**Exploration front-ends (either mode, before committing):**
+`wireframe` (lo-fi structure exploration, disposable greyscale) →
+`design-variations` (3+ substantive hi-fi options, basic→bold, single file
+with tweak controls). Decks are their own medium → `html-deck`
+(fixed-canvas slides), not the responsive-UI routing above.
+
+## See also
+
+- `docs/guidelines/design-antipatterns.md` — the slop-tell catalog; brand mode especially needs this
+- `brand-source-of-truth` — when a registered brand profile is present, it governs
+- `brand-consistency` — validates emitted artifacts against the brand profile
+- `design-system-capture` — DESIGN.md/PRODUCT.md capture the mode's decisions for cross-task consistency