@ethlete/agent-rules 0.1.0-next.30 → 0.1.0-next.32

package/content/skills/design-exploration/SKILL.md

@@ -35,6 +35,11 @@ or loses only against the other variants of its question.
    for literal copies. Derive the composition from the product's own visual language; a new palette
    or spacing on the reference's layout is not a different concept.
 
+7. **Visible UI is built only from a sketch the user picked.** A new or changed element, label,
+   badge or layout needs a picked sketch, and the build brief names its id. "Decision" and
+   "regression" items are no exception. Without a picked sketch, build data and specs only and
+   stop at the UI.
+
 Confirm the step size once, at the start. Do not ask again at every stop. A task is not
 finished while the user is still talking about it.
 
@@ -46,13 +51,10 @@ finished while the user is still talking about it.
 - Your pick, one line on why.
 - Nothing else. No next step, no second finding.
 
-**Do not send a screenshot.** The user keeps the call open. Screenshot only for your own
-check that a variant renders. In a repository with `et design`, take it with
-`et design shot <layer>/<name> --states [--variants]`: one contact sheet of every state, and
-every variant of the open sketch, with a label per cell; below each variant row, a diff row marks
-the pixels that differ from the merged state in red, or says "no pixel change" (with ", but the markup differs" when only the markup changed, e.g. both sides miss the same content). It prints the PNG path last. `--scale 2` enlarges a small part; `--crop x,y,w,h` cuts each cell to that CSS-pixel box, to judge hairlines. `--interaction hover` forces an interaction on every cell. `--state a,b` draws only those states, to compare them side by side. With `--variants`, `--round r2` or `--variant i,j` draws only those variants next to the merged row, so the current round stays readable; it filters the picture, never the checks. With `--variants`, `--diff-props` compares each variant with the merged part drawn with the variant's state props, so changed props do not paint the diff red. It draws
-undimmed, whatever Studio shows. Do not write a scratch script for batch shots.
-`et design motion shots <layer>/<name> <motion>` draws a motion at its keyframes, in full and reduced motion, into one sheet, and writes its tracks (element, properties, start, duration, easing) as JSON next to it.
+**Do not send a screenshot.** The user keeps the call open. Screenshot only for your own check that a
+variant renders: `et design shot <layer>/<name> --states [--variants]` draws one contact sheet. Every
+flag, the motion shots and the raw screenshot script are in {%resource:reference-shots.md%}. Do not
+write a scratch script for batch shots.
 
 If a second defect appears, add it to the open list and give it one line. Do not draw it.
 
@@ -80,500 +82,44 @@ Studio no longer takes new calls. **New work goes to a product, never to a new c
 `et design new`. Old calls stay in Studio's Legacy tab as reference for moving them into a
 product. They take no picks and no new variants.
 
-### Create a product
-
-```bash
-et design product new <name> [--base @ethlete/components|<path>] [--from-project <name>]
-```
-
-It writes the `config.json` entry and the empty layer folders. A product on `@ethlete/components`
-takes the SDK as its base, so its parts start from the real components rendered with `ng()`.
-Without a base it gets the presets phone (390x844) and desktop (1440x900). A product's own `presets`
-replace its base's whole: a desktop-only app lists `desktop` alone and draws no phone state. `--from-project` copies
-`styles`, `head`, `providers` and `themes` from an old project entry. Studio never writes
-`config.json`; the command does.
-
-Every frame loads the product's tokens stylesheets once, before the part's own `styles`, so a part
-never imports the tokens and never adds them to its `styles`. The product's config `tokens` lists
-those parts in load order (`["foundations/tokens"]` when left out); a listed part that does not
-exist yet is skipped. A product's own copy of a listed part, or a sketch of it, replaces the base's
-in every frame. Never list a `tokens.css` in config `styles`.
-
-A part file default-exports its `definePart(...)` and may also export named helpers, such as a piece of its
-markup: `import { studioMark } from '@system/foundations/logo'`. Import a piece from the part that draws it;
-never copy its markup into another part. A piece that uses the part's classes needs its stylesheet too
-(`@system/foundations/logo.css?inline`), or from the part's default export when the part sets
-`definePart({ styles })`: every drawing of that part gets it, so `render` returns only extra styles, or `drawing({ body })` with none. The layer
-rules hold for these imports as well.
-
-A component a host embeds exports its markup as such a helper, and a wrapper only its own frame needs, such as
-padding that makes room for a focus ring, goes in `render` alone, never in that helper: the host places the
-component itself and would inherit the wrapper's offset.
-
-A product whose app uses Tailwind lists one stylesheet in config `styles` that imports the app's styles and
-registers the drawing folders with `@source './'`. Sketches then use the app's utilities; plain CSS stays for what
-utilities cannot express, such as camera geometry.
-
-### Propose a change as a sketch
-
-A change to a part, or a new part, is a **sketch**: the question is the part, the variants are the
-answers. Variants are drawn at the same geometry, and one variant wins only against the others.
-
-```bash
-et design sketch new <layer>/<name> --variants a,b --by <model id> [--like <layer>/<name>] [--variant-note a=<text>]… [--product <p>]   # each variant starts as a copy of the part
-et design sketch new <layer>/<name> <layer>/<name>… --variants a --by <model id>   # one change across several parts: one sketch, one ready, one merge
-et design sketch report <layer>/<name> --variant b --by <model id> "phone"         # tell Studio what you build now
-et design sketch report <layer>/<name> --variant b --by <model id> --done         # you stopped drawing b; Studio shows its frames
-et design sketch check [<layer>/<name>] [--fix]                                    # each variant laid over the product
-et design sketch ready <layer>/<name> --by <model id>                              # now the user can pick
-et design sketch reject <layer>/<name> --variant b [--reason <text>] --by <model id> # only when the user rejected b; no pick or merge until reopened
-et design sketch reopen <layer>/<name> --variant b [--reason <text>] --by <model id> # only when the user takes b back; the rejection stays in the history
-```
-
-One change across several parts (an alias removal, a token rename) is one sketch with several targets: each
-variant holds every target, and `ready` compares them all. `ready` and `preview` also name every part a `shared/`
-edit reaches.
-
-Variants are alternatives. A variant never stands for a state of another variant: a hidden or
-collapsed mode of variant d is a further state of d, not a variant e. Before you draw a new control,
-look for a control that already does the job (an active rail button that toggles its panel), and
-draw that first.
-
-A section of an app is a page under `pages/`, never a state of the shell. An element holds its
-own chrome only. A sketch on an element adds no state whose difference is page content in a slot.
-
-A variant mirrors the product layout and holds only the parts it changes. Draw two to four
-variants, each with what it costs, and run `sketch check` before `ready`. A variant with problems
-cannot be picked. A part in a variant keeps every state the part has in the product: `sketch check`
-and `sketch ready` fail on a dropped state, and warn when two stylesheets of one part define the same class. A problem the product already had prints as `NOTE (was there before)` and fails
-neither. Use `sketch list` to see the open ones.
-`sketch check` also runs tsc over each variant with its `@shared/` and `@system/` imports, so never write a
-tsconfig of your own. It warns of a variant stylesheet that restyles a class of `shared/`, of a
-variant file nothing imports, and of a `shared/` export the variant does not import; `design check` warns of
-an export in a merged part's `shared/` that nothing imports, and (`STALE-REPLACE`) of a `.replace('<…')` or
-`.replace(/<…/)` on markup that neither the part nor a part it uses draws. To delete a file of a part, delete it in the variant: a merge deletes the
-product file the picked variant no longer holds.
-
-Each variant's note, what it is and what it costs, goes in with `sketch new --variant-note a=<text>`, once
-per variant: `sketch.json` keeps it apart from the part's `definePart({ note })`, and Studio shows it in the
-variant's head. A merge keeps the part's note, takes its `--note`, or gives a new part the picked variant's note.
-`sketch new` and `sketch variant` write their files in the checkout's Prettier format; after an edit,
-`sketch check --fix` formats the variants before it checks them. A sketch command
-without `--product` takes the product that holds the sketch.
-
-Start a new part from a close one with `--like`: `sketch new pages/inbox --like pages/system`
-copies the product's `pages/system` into each variant, renamed to the target and without its
-`madeBy`; `--like pages/system:b` copies variant b of the open sketch on it, with that sketch's
-`shared/` folder.
-
-Rendering for one variant lives in that variant's files. `shared/` holds only code every variant
-uses: do not give a shared helper a parameter, branch, import or style rule that only one variant, or
-a variant you dropped, needs. A merge takes `shared/` whole, so what stays there ships with the pick.
-
-Code the variants of one sketch have in common (sample data, a switch, a helper) goes in the
-sketch's `shared/` folder, next to the variant folders, never into copies per variant. A part in a
-variant imports it as `@shared/<path>`, and a shared file may import `@system/...` and
-`@shared/...`. A part outside a sketch may not import `@shared/`. A variant that needs a shared file
-changed holds its own copy at `<variant>/shared/<path>`; `@shared/<path>` finds that copy first, and a merge
-of that variant takes it. On a merge, `shared/` moves into
-the target's folder as `shared/` with its imports made relative; when no part imports it, it is
-dropped. With several targets, each takes only the files it imports, directly or through another
-shared file; a file nobody imports goes back to the target that held it, and the merge refuses one no
-target held. `sketch new` refuses targets whose `shared/` folders hold one path with different contents. Only the target may import it: a merge refuses while another part of the picked variant
-does, so move that code into the part. `sketch new` prints each file it puts in `shared/`, for example
-the `shared/` folder of a merged page: edit it there, as part of the sketch, not in a variant copy.
-
-```ts
-// sketches/pages-flows/shared/flow-data.ts
-export const flows = [{ name: 'Checkout', steps: 4 }];
-
-// sketches/pages-flows/a/pages/flows/flows.ts
-import { flows } from '@shared/flow-data';
-```
-
-An asset (a mark, logo, icon, picture or font) is one file in `.ethlete/design/<product>/assets/`,
-never a copy inlined into parts. A part imports it as `@assets/<file>`: the default import is a URL
-for `<img src>`; an SVG that must follow tokens (`currentColor`, `var(--accent)`) imports with
-`?raw` and goes inline, for example `@assets/icons/<name>.svg?raw`. A stylesheet, the product's
-`styles.css` or a part's, uses `url('@assets/<file>')`, for example in an `@font-face`. A foundation
-part may wrap an asset in a named export. A product finds its base product's assets too. A sketch
-variant adds or changes an asset in its own `<variant>/assets/` folder (`sketch new` and `sketch variant`
-print it next to the part file), and a merge copies it into the product's. Size an inline SVG with
-`svgAsset(mark, { size: 32 })` from `@design-system`, never by replacing its `width`/`height` as a
-string; `class` and `attrs` (`{ 'aria-hidden': 'true' }`) set the rest of the root's attributes. `design check` fails an SVG asset with no root `<svg>` or without
-`xmlns="http://www.w3.org/2000/svg"` (an `<img src>` and an image viewer do not draw it). The part hash behind `design check` and "changed outside a sketch" counts the bytes of
-the assets a part uses.
-
-Every change to a merged part goes through a sketch, also a small one: new copy, sample data, an
-added state. When there is nothing to choose, the sketch has one variant (`--variants a`), and the
-user merges it or comments on it. Never edit a merged part directly, or the user cannot compare or
-comment on the change in Studio. `design check` warns, and Studio marks the part "changed", when a
-merged part changed outside a sketch; only a merged sketch on that part clears it.
-
-A sketch on a foundations part such as `foundations/tokens` keeps the part's overview drawing: the
-variant adds its token group as a state, or extends that group's state. It never replaces the
-drawing with a demo scene, since the merge would drop every other group. A demo may be an extra state.
-
-Name the variant you work on with `--variant`. Studio marks it as drawing, and hides its frames,
-while the latest report names it. `sketch new` starts no report, so `report --done` follows only a report
-of your own; it prints the next steps. `sketch new`, `sketch variant` and each report record your
-model id as an author of the variants they write, and `sketch ready` records it on every variant
-that has no author yet. A merge adds the picked variant's authors to the `madeBy` the part file
-already holds, and never removes it.
-
-### Combine variants in a new round
-
-Studio never combines variants. When the user asks for one in a comment ("solid like a, outline
-like b"), draw it as a new variant in a new round:
-
-```bash
-et design sketch variant <layer>/<name> c --from a --by <model id> --round "Solid a, outline b" --note "r1 showed pill and square; the user wants a's solid with b's outline"
-```
-
-`--from` copies a variant into the new one, sets the sketch back to in progress and clears the
-pick; it refuses while the decision is a discard (the user picks a variant first). Without `--round` the new variant joins the running round; with it, `--note` is required and
-goes on the running round: what it showed and why its variants lost. Older variants stay pickable.
-The command prints the notes of the previous round. Fix a round's title or note later with `sketch round <layer>/<name> <round> --title … --note … --by <model id>`; `sketch list` shows each sketch's rounds.
-Letters continue across rounds (r1: a, b; r2: c, d). `sketch variant <layer>/<name> c,d --from a` adds
-several variants at once; with `--round` they all start the new round. A new round answers the comments on the
-`--from` variant and marks them "addressed in round" with the new round's key. A variant without `--round` fails while the sketch has open comments and lists them: a variant that answers a comment starts a new round. Draw the combined
-variant and mark the sketch `ready` again. `sketch new --round <title> --note <text>` names
-round 1 and sets its note; `--round` without `--note` fails. `sketch ready` refuses while the running round has no note; set it with `sketch round`.
-`sketch ready` also shoots every state of every variant and of the product's part: when not one pixel differs
-in any of them, it merges the sketch itself and logs it as an `auto` entry in the product's `accepted.json`
-("No visible change in any state: merged automatically."). Any difference or failed shot leaves it `ready`.
-A problem the product already had before the merge does not block it (the check prints it as a note); only a problem the merge adds does.
-Run `sketch ready` again on a `ready` sketch to repeat the check and the auto merge.
-
-Mark a sketch `ready` only when no change to it waits on anything: no open decision, no helper still to
-land, no "once X is decided I adapt the sketch". A pending change keeps the sketch in work and out of the
-merge queue: ask first, make the change, then mark it `ready`. Record the wait with
-`et design sketch hold <layer>/<name> --until "<what it waits on>" --by <model id>` (a `ready` sketch goes back
-in progress) and `sketch release` it once the change is in.
-
-### Your model id: `--by`
-
-Every command that writes takes `--by <model id>` and fails without it: `sketch new`, `variant`, `report`,
-`ready`, `rebase`, `merge`, `discard`, `inbox done` and `comment reply`. The id is the exact model
-id as free text, for example `claude-opus-5-5`, `gpt-5.6-sol` or `gemini-3-argon`. Studio shows it
-on the variant, the reply and the part, so the user sees which model made what.
-
-**Never guess your id.** Use the one your prompt names. If your prompt names none and you do not
-know your own exact id, ask the coordinator or the user before you write.
-
-### The user decides, Studio merges
-
-The user picks a variant, or discards the sketch, in Studio. **Studio merges on the user's click.
-Never run `sketch merge` or `sketch discard` yourself, and never pick a variant.** Both mark
-the open comments on the sketch's variants addressed: the user's click answers them. Comments on the
-product's parts stay. If a part the variant replaces changed
-in the product since the sketch was created, the merge refuses: bring each variant up to date, run
-`et design sketch rebase <layer>/<name>`, and mark it `ready` again. `sketch preview <layer>/<name>
-<variant>` lists the elements and pages a merge changes. The note on a part records why it has its
-current shape. The user's reason is optional: with one, the merge sets the note from it; without
-one, the part keeps the `note` the picked variant file holds, so write that note while you draw.
-
-After the user approves a direct edit of a merged part (no sketch), run `et design accept <layer>/<name> --product <p> --by <model id> --note <why>` so `design check` stops warning `changed outside a sketch`. Never accept an edit the user did not approve.
-
-To drop a merged part the user no longer wants (folded back into its host, say), run `et design part remove <layer>/<name> --product <p> --by <model id>`: it deletes the folder, its `merged.json` entry and its tsconfig path, and resolves its comments. It refuses while another part imports it or an open sketch targets it. Never `git rm` a part by hand.
-
-### Read the inbox
-
-The user comments on a state of a part in Studio, at a point, or on a sketch variant. The sketch of
-an element also shows each page that uses it, with each variant swapped in: a comment there names
-the page as its part and the element's sketch variant, so change the variant, not the page.
-
-```bash
-et design inbox [--json] [--product <p>]   # open comments and rebases, then what waits for the user
-et design inbox done <id> --note <text> --by <model id>   # set the part note, mark the thread addressed
-et design comment reply <id> --by <model id> <text> [--question]   # answer a comment thread (takes --product)
-```
-
-Read the inbox at the start of a session and after each sketch you mark `ready`. Answer a comment
-by changing the sketch or the part, then `inbox done <id> --note "…"`. The note replaces the `note` of the part the comment was made on (for a sketch variant, the product's part), so write it to explain the whole shape of the part, and pass the old note unchanged when it still holds. `done` fails without `--note`; only the user withdraws a comment without one, in Studio. `done` also stores your `--by` where the comment sat: in the authors of the sketch variant, or in the `madeBy` of the part. A pick or discard decision is listed as waiting
-for the user: Studio merges or discards on the user's click, so never run `sketch merge` after a pick.
-
-A comment is a thread: the user and you both reply. When a comment is unclear, ask with
-`comment reply --question` instead of guessing. The thread then moves to the "waiting for the user" group
-(`waitingForUser` in `--json`) and returns to the inbox when the user answers. A thread there is
-not work for you.
-
-A thread has three states. **Open** waits for an answer. **Addressed** (`addressed`: who, when, why,
-the round) means `inbox done`, a new round, a merge or a discard answered it: it leaves the inbox and
-the check, Studio shows it with an "addressed" badge, and you may still `comment reply` on it to say
-what you changed. A reply by the user opens it again. **Resolved** means the user closed it in Studio -
-only the user resolves. The file stays so the user can look back at it; a reply or `done` on it fails.
-
-Pass `--question` only when you cannot go on without the user's answer. Studio lists only those
-threads under "Questions for you". A report of what you did is no question: reply without the
-flag, and the thread shows as "answered" until the user withdraws it or replies.
-
-### Draw a flow
-
-A flow joins states of pages into a path the user reads left to right in Studio's Flows view.
-It is `<product>/flows/<name>.json`; `position` and `label` are optional:
-
-```json
-{
-  "frames": [{ "part": "pages/library", "state": "empty", "position": { "x": 0, "y": 0 } }],
-  "lines": [
-    {
-      "from": { "part": "pages/library", "state": "empty" },
-      "to": { "part": "pages/film-detail", "state": "default" },
-      "label": "user adds a film"
-    }
-  ]
-}
-```
-
-Every flow line is labelled, and the element the label names is visible in the frame before it: a line
-labelled "user clicks 'Log in'" starts from a frame that shows a "Log in" button. A line that names
-nothing the reader can see, or a label for a control the page lacks, is a defect.
-
-A line may join two states of one page. A frame may name a page that exists only as an open sketch;
-the flow then shows its first variant. Lines hold for every preset. Without `position`, Studio
-lays the frames out along the lines.
-
-### Draw a wireframe
-
-A wireframe exists to iterate fast, in minutes per round, rough enough to redraw with a client at
-the table. It answers one thing: which regions a screen has and what each region holds. These
-rules are strict:
-
-- **Keep what exists.** Before a sketch, list what the running app already does on that screen.
-  Keep it as a labelled box, and draw only what is still open.
-- **One sketch per screen or flow**, never one per region or per detail. The variants differ in
-  layout: where the regions sit and how big they are.
-- **Regions and names only.** A region is a box with a label; a list shows item names. Draw no
-  counts, badges, status markers, inspectors, size labels or field lists. If a detail matters,
-  write it as a word in the region label.
-- **Never polish.** Do not fix alignment, spacing or a kit gap. When the kit lacks a shape, draw a
-  labelled box. Look at each shot only for a broken frame: overflow, a scroll bar, clipped text.
-- **Draw it yourself.** A wireframe round is small work: no subagent, no friction report.
-- **Stop early.** When the regions of the main screens are settled, the stage ends. Comments on
-  the look of a wireframe belong to the next stage, not to a new wireframe round.
-
-A page may not import another page. To show a page inside a page ("in context"), embed it:
-`embedPage('pages/system', { state, width, height, scale })` from `@design-system` answers a
-drawing whose `body` is a frame of that page, drawn in the same product, sketch variant and theme
-as the embedding frame. `width` and `height` are the viewport the page is drawn at (default
-1280 x 800; `height: 'auto'` fits its content), `scale` shrinks the frame. Never rebuild a page
-from its elements to show it.
-
-A page that has no parts yet draws grey stand-ins from the wireframe kit; pages and elements may
-import it, components and foundations may not:
-
-```ts
-import { box, heading, textLines, image, button, input, icon, select } from '@design-system/kit';
-```
-
-Signatures are in `libs/cli/design/wireframe-kit.ts`: `box(children, { direction, gap, padding, width, height, grow, plain, stackBelow, fill })`,
-`heading(text, { size })`, `textLines({ lines, width, size })`, `image({ width, height, ratio })`,
-`button(label, { primary })`, `input({ label, placeholder, width })`, `icon({ size, glyph })`,
-`select({ label, value, width })`, `tabs(labels, { active })`, `segmented(options, { active })`,
-`checkbox(label, { checked })`, `badge(text)` and `dot({ hollow, size })`. Draw a control as its
-type: a picker is a `select`, a section switch `tabs`, a size switch `segmented`, a count a `badge`,
-a status a `dot`, never a row of buttons or an empty `icon`. Give an icon a `glyph` (`'plus'`,
-`'close'`, `'menu'`, `'more'`, …; another name draws its first letter). Give the root box of a page or a
-shell `fill: true` so it is as tall as the frame, instead of a hand-written `min-height`. Draw for
-every preset, not one width: give a picture a `ratio` (`'2/3'`) instead of a fixed height, and give
-a row `stackBelow: <px>`, the width below which it stacks its children, instead of fixed widths
-that only fit the desktop. Never use `vh`, `dvh` or `svh` in a part: a part has no viewport of its own, so the unit measures Studio's frame, not the page. A full page is a frame of a fixed size. Put titles in `heading`, never in hand-written markup. Studio lists such a page under
-"Wireframes" with its kit-use count. A shell is a normal element named by purpose (`shell-main`); draw a rough one with the kit, so each
-page imports the shell instead of repeating it, and a shell pick lands in one file.
-A dialog without its own URL is an element that a page state shows ("login open"). Examples in
-`.ethlete/design/studio-lab`: `pages/film-detail`, `elements/shell-main`, `elements/login-dialog`,
-`flows/sign-in.json`.
-
-### Check a product
-
-```bash
-et design check --product <name>   # layer dependencies, hard-coded colours, undefined tokens, copied components, scripted motion, tsc (open sketch variants too), render
-et design system --json            # each part's origin, note, states, presets and problems
-```
-
-Without `--product`, `check` covers every product. A part may only use its own layer and the
-layers below it (see "The order of a design"). Rule `FLOW` reports a misshaped flow file, a frame
-naming a part or state that exists neither in the product nor in an open sketch of that part, a duplicate state, and a line to a state that is not a frame of
-the flow. Rule `WIREFRAME-KIT` reports a component or foundation importing the kit. Pass the changed files to the check below as before.
-
-Once the other rules pass, the check draws every state in a headless Chromium on a server of its own
-(pages at each preset, a part with `widths` at each width, any other part fitted), and
-`sketch check` does the same for the open variants and the pages they show in. Each line names
-product, part, state, size and a selector path:
-
-- `OVERFLOW` - the frame scrolls: content wider than the frame, or taller than a preset height.
-- `CLIPPED` - an element with `overflow: hidden|clip` cuts its content, unless it sets
-  `text-overflow: ellipsis` or a line clamp.
-- `WRAP` - text in a button, tab, badge, chip or `white-space: nowrap` box runs onto a second line.
-- `ZERO-SIZE` - the part root has no width or no height.
-- `UNKNOWN-THEME` - a `et-color--<name>` class names a colour theme no stylesheet of the frame defines, so it draws in the fallback colour.
-- `RENDER` - the frame refused to draw, or the part did not load.
-
-A `WARNING` line does not fail the check:
-
-- `UNDEFINED-CLASS` - a class carries a prefix the product's part CSS uses (`st-`, not the SDK's
-  `et-`), but no stylesheet of the frame defines it. Named once, at the first part that draws it.
-- `GRID-COVERAGE` - some `grid` rows fill every interaction column (`rest`, `hover`, `active`,
-  `focus-visible`, `disabled`) and others leave some out, so a state can break there unseen.
-
-A part that breaks a rule on purpose names it: `definePart({ checks: { skip: ['CLIPPED'] }, … })`;
-the skip covers the part wherever it is drawn. Without Playwright Chromium the check prints
-`RENDER CHECK SKIPPED` and passes on the other rules.
-
-A project's `config.json` entry can name `themes`, `{ "surface": [...], "color": [...] }`; a
-frame asked for a theme gets the `et-surface--<name>` and `et-color--<name>` classes on its root,
-so a drawing must take its colours from the theme tokens and never set a surface or colour class
-on its own root. An inner panel may set `et-surface--<name>`.
-
-`et design [checkout]` serves the frames; the checkout defaults to the working directory and
-`DE_PORT` overrules the port. In the ethlete SDK the user reads Studio, started with `yarn studio`,
-which serves the frames itself: do not start `yarn design` next to it. Studio carries its own copy
-of the tool, so a checkout that installs nothing still draws.
-
-Three constraints on a drawing file:
-
-- **Never import a package barrel.** The libraries resolve to source, so one barrel makes the
-  browser request every module and the requests fail with `ERR_INSUFFICIENT_RESOURCES`. Import
-  the one file you need.
-- **The fixture is shared, and a variant may not change it.**
-- **One file per variant**, so a broken variant breaks its own frame only.
-
-A `<script>` in a drawing never runs. For behavior give the drawing a `setup(root)` function
-(called once after the markup is in `root`, no cleanup, wire one delegated listener). Render each
-state of a prototype with `ngStates({ closed: …, open: … }, { imports })` and swap them with
-`setup: flow.on([{ click: '.trigger', go: 'open' }])`. To draw an open overlay, open it in the
-template (`<et-select [open]="true">`); `ng()` returns the real panel and the frame places it.
-`ngStates` wraps the states in `<div data-de-states style="display: contents">`, so a selector
-rule must not depend on that wrapper.
-
-**A repository with a sketch Storybook** draws every variant in the **same** story, side by
-side, under the real geometry the thing ships in. The default Storybook is
-{%storybookUrl%}; an app with its own sketch Storybook names its port in the plan file.
-
-Either way:
-
-- Sketches take inputs only and stay out of the application's build.
-- Prototype, never refactor. Do not touch the shipped component until the treatment is
-  settled.
-- Keep the rejected variants drawn, marked as rejected.
-
-### Notes
-
-A note explains a state: why it looks this way, what it shows. A comment is feedback that needs
-an answer. Write a note when nothing is asked of the reader.
-
-A note is `<product>/notes/<timestamp>-<id>.json`:
-
-```json
-{ "part": "button", "state": "disabled", "point": { "x": 24, "y": 8 }, "size": "mobile", "text": "Muted, not hidden." }
-```
-
-- `part`, `state` and `text` are required. `point` is optional, in CSS pixels.
-- `size` is required when `point` is set: the preset, the CSS pixel width, or `"fitted"` the note was written at. A
-  pointed note shows only at that size; a note without a point shows at every size.
-- A free note on a flow is an entry in the `notes` array of `flows/<name>.json`:
-  `{ "id": "…", "text": "…", "at": { "x": 0, "y": -40 } }`. `at` is optional, the note's top-left
-  corner on the flow canvas, and may be negative.
-
-## The order of a design
-
-A product design runs in this order. Each stage settles in calls before the next starts, and
-each stage draws with what the stages before it settled (the wireframes draw with the kit only):
-
-1. **Wireframes**: early, rough concepts of the main flows (a legacy call with `mode: 'wireframe'`;
-   in a product, draw them with the wireframe kit, see "Draw a wireframe"). They show
-   which components the product needs, not how they look. The stage ends with an inventory in
-   the wireframe call: every part the wireframes need, each mapped to the SDK component it
-   starts from, or marked new with the component call that draws it. The inventory is the
-   queue of component calls:
-
-   ```ts
-   inventory: [
-     { part: 'Search field', sdk: 'et-input' },
-     { part: 'Match card', new: true, call: 'tomflix/components/match-card' },
-   ],
-   ```
-
-2. **Foundations**: colours, colour themes and surface themes (the project's `themes` in
-   `config.json`), plus the type scale, spacing and radius.
-3. **Logo and CI**, if the project needs them.
-4. **Components**, the inventory is their queue, from the SDK ones rendered with `ng()`, themed and set up for the project.
-   Each accepted one becomes a design-system entry.
-5. **Larger elements**: the shell, the navigation, headers, lists, built from the entries.
-6. **Pages**, built from the elements and the entries.
-7. **The working prototype**: the pages joined with `ngStates` and `flow.on`.
-
-Do not start a stage before the one above it is settled, and do not draw a page from parts that
-are not in the design system. If the user asks for a later stage first, say which earlier stage
-is missing, and draw that first.
-
-The stages map onto the layers of a product: wireframes, foundations, components, elements, pages. A settled
-Legacy call with a stage counts for that stage in this order.
-
-A later stage can show that an earlier one is incomplete. If a page needs a part that the system
-does not have, add it to the inventory. A part becomes a component only when at least two hosts
-draw the same case. Until then it stays in the one element or page that draws it. When a second
-host draws it, open a component sketch, and list in its brief every host and every case each one
-draws, so the component covers them all.
-
-A component documents its states per axis, not every combination: for example kind, end mark and
-interaction (rest, hover, focus-visible, selected, inert), plus only the combinations that look
-different. A smaller piece with no states of its own, such as an icon set, is a foundation asset,
-not a component.
-
-When each of several cases is drawn at rest and in the same interactions, build the states and their grid with
-`interactionRows(rows, { interactions: ['hover', 'active'], force: (props, interaction) => ({ ...props, interaction }) })`
-from `@design-system` and spread the result into `definePart`; never write those states and the grid by hand.
-`sketch check` prints `grid <rows> x <columns> ok`, or the states the grid leaves out; a state in two cells
-fails it as `GRID`, in `design check` too.
-`definePart({ interactions })` forces an interaction on the part's root only. To draw one element of the part
-hovered, focused, pressed or disabled, such as one row of a list, wrap that element's markup in
-`forceInteraction(markup, 'hover')` from `@design-system` inside `render`, driven by a prop; never write
-`data-et-force` by hand.
-
-## Draw from the design system
-
-A call that invents its own button, field or row does not match the calls beside it. **Before
-you draw a part, look for it in this order, and draw new only when none of them has it:**
-
-1. The product's design system, `.ethlete/design/<product>/` (and its base).
-2. The real SDK components, rendered on the design server with `ng()` from `@design-explore`:
-
-   ```ts
-   const field = await ng(`<et-form-field><et-label>Name</et-label><et-input /></et-form-field>`, {
-     imports: ['FORM_FIELD_IMPORTS', 'INPUT_IMPORTS'],
-   });
-   ```
-
-   The template is a real Angular template, and `imports` names exports of
-   `@ethlete/components`. The project's `providers` module in `config.json` supplies the themes.
-   Render every component of a drawing in **one** `ng()` call: each call is a new app, so two
-   calls repeat element ids. The server renders the built package, so in the SDK rebuild
-   `dist` after a component change.
-
-   To draw a form state (a value, an error, a touched field), give `ng()` (or `ngStates()`)
-   `fields`. Each entry becomes a signal form field the template binds as
-   `[formField]="fields.<name>"`. An error is a kind (`'required'`) or a kind and a message. A
-   field shows its errors only when it is touched:
-
-   ```ts
-   const form = await ng(
-     `<et-form-field><et-label>Email</et-label><et-input [formField]="fields.email" /></et-form-field>`,
-     {
-       imports: ['FORM_FIELD_IMPORTS', 'INPUT_IMPORTS'],
-       fields: { email: { value: 'ada@', errors: [{ kind: 'email', message: 'Not an email' }], touched: true } },
-     },
-   );
-   ```
-
-3. Only then a new drawing. Build it from the two above, and say in the variant's `claim`
-   that the part is new.
-
-A part is one folder, `<product>/<layer>/<part>/`, with its drawing and states. Read the parts of
-the product before the first drawing of a session. **A part exists only because the user picked a
-sketch.** A `chosen` verdict in an old call is not enough. Never change a part's look without a
-sketch the user decided.
+## Hard rules for products and sketches
+
+- A change to a merged part, also a small one, is a **sketch**; never edit a merged part directly. When
+  nothing is to choose, the sketch has one variant (`--variants a`). Variants are alternatives, never a state
+  of another variant. Two to four variants, each with its cost; run `sketch check` before `sketch ready`.
+- **Never run `sketch merge` or `sketch discard`, and never pick a variant.** Studio merges on the user's
+  click. After a pick or discard, do not merge. Run `sketch reject` or `reopen` only when the user did.
+- Mark a sketch `ready` only when no change to it waits on anything; otherwise `sketch hold`.
+- Every write command takes `--by <model id>`. **Never guess your id**: use the one your prompt names, or ask
+  the coordinator or the user before you write.
+- Run `et design accept` only after the user approved a direct edit. Remove a part only with
+  `et design part remove`, never `git rm`.
+- Studio takes no new calls: never run `et design new`. New work goes to a product.
+- Share code between variants in the sketch's `shared/` folder only; no shared parameter or branch for one
+  variant. An asset is one file in `<product>/assets/`, never inlined.
+- A user comment to combine variants is a new variant in a new round (`sketch variant --from --round --note`).
+- Read the inbox at the start of a session and after each `ready`. Answer with `inbox done <id> --note`,
+  ask with `comment reply --question` only when you cannot go on. Only the user resolves a thread.
+- Use the `ethlete-design` MCP tools when they are in your tool list, and call `sketch_report` before every
+  variant edit.
+- Draw from the design system, never invent a button or field: the product's parts, then SDK components via
+  `ng()`, then new. Colours come from the SDK theming systems, never your own tokens. A part exists only
+  because the user picked a sketch.
+- A wireframe is rough and fast: regions and names only, no polish, no subagent, one sketch per screen.
+- Do not start a design stage before the one above it is settled: wireframes, foundations, logo and CI,
+  components, elements, pages, prototype.
+
+Details, commands and examples, read on demand:
+
+- {%resource:reference-products-and-sketches.md%}: creating a product, every `sketch` command, shared code,
+  assets, rounds, `--by`, the merge and accept flow. Read before the first sketch command.
+- {%resource:reference-inbox-and-mcp.md%}: reading and answering comments, thread states, the MCP tools.
+- {%resource:reference-flows-and-wireframes.md%}: flow JSON, the wireframe kit and its rules.
+- {%resource:reference-check-and-notes.md%}: `design check` rules and warnings, drawing-file constraints,
+  `setup`, `ngStates`, notes.
+- {%resource:reference-order-and-design-system.md%}: the stage order, component states and
+  `interactionRows`, `ng()` and form fields, theming rules.
+- {%resource:reference-shots.md%}: every `shot` flag, motion shots, the screenshot script.
 
 ## Check before you look
 
@@ -633,22 +179,6 @@ command." You know the id because you chose the model; the sub-agent does not, a
    variant's `verdict` in an old call's `call.ts` (a product sketch needs none; the merge sets the note). It runs while you open
    the next call.
 
-## Screenshots
-
-**Off by default.** The user has the call open and sends you a picture when something looks
-wrong. Take one only when the code cannot tell you whether two variants really differ, and
-never to put in front of the user. Copy {%resource:shoot-template.mjs%} to the repository
-root.
-
-```bash
-node shoot.mjs <story-id> 1100 760 out.png
-```
-
-- `waitUntil: 'networkidle'` never settles on an iframe that holds a live dev server
-  connection. Use `'domcontentloaded'`.
-- `:hover`, `:focus-visible` and `:active` need a CDP session and `CSS.forcePseudoState`.
-  Several hold open at once, so one image shows them all. The template does this.
-
 ## Writing it down
 
 Every settled call goes in the exploration's plan file: what won, what lost, and why. Keep