@ethlete/agent-rules 0.1.0-next.26 → 0.1.0-next.28

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

@@ -11,15 +11,19 @@ vars: [storybookUrl]
 A design exploration is a dialog. **The user is the designer. You find and frame. The user
 chooses.** A finding is not a licence to pick the fix.
 
-The unit of work is a **call**: one open question, with every answer drawn side by side at
-the same geometry. A variant wins or loses only against the other variants of its call.
+The unit of work is one open question, with every answer drawn side by side at the same
+geometry: a **sketch** on a product, or a **call** in a repository with the old setup. A variant wins
+or loses only against the other variants of its question.
 
 ## The rules
 
 1. **One open call at a time.** Take one question. Draw its variants. Stop.
 2. **Put the variants in the call, then name your pick.** Two to four variants, drawn for
-   real, side by side, labelled, with what each one costs. Your pick is a proposal.
-3. **Commit only when the user says commit.**
+   real, side by side, labelled, with what each one costs. Your pick is a proposal. Never ask
+   a yes/no question about content, and never ask the user what they want: deliver strong
+   variants, and the user picks.
+3. **Commit only when the user says commit.** A merge the user makes in Ethlete Studio counts as
+   that word for the merged part: commit the part, not the open sketches.
 4. **A clear rejection starts the next call.** Settle and record the rejected call, then draw
    the next focused question automatically, within the user's original scope. Stop only when the
    user asks to pause or end the exploration, or when their feedback leaves no grounded next
@@ -32,13 +36,17 @@ finished while the user is still talking about it.
 ## What one stop looks like
 
 - The question, in one sentence.
-- The call slug to look at.
+- The sketch (or call slug) to look at.
 - The variants, labelled A, B, C, one line each.
 - 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.
+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.
 
 If a second defect appears, add it to the open list and give it one line. Do not draw it.
 
@@ -46,108 +54,375 @@ If a second defect appears, add it to the open list and give it one line. Do not
 
 The exploration's plan file names the tool. Two shapes exist.
 
-**A repository with a `.ethlete/design` folder** draws each variant of a call in its own
-frame, and the user reads the call in Ethlete Studio. The tool is `et design`, from `@ethlete/cli`, so the repository itself needs no design
-tooling. A call argues in the repository it is about:
+**A repository with a `.ethlete/design` folder** keeps one design system per **product**, and the
+user reads and decides in Ethlete Studio. The tool is `et design`, from `@ethlete/cli`; run
+`et design --help` for every command, `et design <command> [<subcommand>] --help` for one.
+In the SDK checkout, `yarn design` builds the CLI before each call; in a check-and-shot loop,
+build once and call `node dist/libs/cli/src/index.js design` instead.
 
 ```
 .ethlete/design/
-  config.json     the port, the default call, and one entry per project
-  calls/<project>/<group>/<slug>/
-    call.ts       the eyebrow, the headline, the intro, frameWidth, the variants and the round prose
-    fixture.ts    the data every variant shares
-    variant-a.ts  one default-exported drawing per variant
-    variant-b.ts
+  config.json                         the port and one `products` entry each
+  <product>/<layer>/<part>/           layer: foundations, components, elements, pages
+  <product>/flows/<name>.json         a flow: pages and their states joined by lines
+  <product>/sketches/<layer>-<name>/  an open sketch: sketch.json and one folder per variant
+  <product>/comments/<id>.json        a comment the user wrote in Studio
+  calls/                              old calls: Legacy, read-only
 ```
 
-The first segment of a slug is the **project**. `config.json` gives each project its own
-`styles` and its own `head`, so one project's type scale and fonts never reach another's
-drawings. A project the config names not draws bare.
+Studio no longer takes new calls. **New work goes to a product, never to a new call**; do not run
+`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.
 
-A project can also name `themes`: `{ "surface": ["light", "dark"], "color": ["brand", …] }`; the
-first name of each list is the default. A frame asked for a theme gets the
-`et-surface--<name>` and `et-color--<name>` classes on its root, so a drawing in such a project
-must not set a surface or colour class on its own root, and must take its colours from the theme
-tokens. An inner panel may set `et-surface--<name>`, to put a dark and a light panel side by side
-or to draw an elevated card. To try another value of a colour theme, a variant calls `themeCss()`
-in its own `styles`; it never changes the project's providers.
+### Create a product
 
-### Make and track a call
+```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.
 
-`et design --help` lists every command. Start a call with the tool, never by hand:
+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 new <project>/<group>/<name> --stage component --variants a,b --feature <name>
-et design status <slug> drawing   # while you draw; check sets checking, then ready or failed
+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 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
 ```
 
-`new` writes `call.ts`, `fixture.ts` and one variant file per key, and the call renders at
-once. `stage` in `call.ts` names the stage of the design (see "The order of a design"). Every
-call needs one: `new` refuses to start without `--stage`, and `et design check --call` fails on a
-call without it. Ethlete Studio groups the calls by it, and the check warns when an element, page
-or prototype call imports nothing from the design system. The status shows on the call's row in Studio.
-
-`feature: '<name>'` in `call.ts` groups a call under a feature in Studio. Set it at creation with
-`new --feature <name>`. A call without one shows under "No feature".
-
-`et design [checkout]` serves the frames on the port `config.json` names. The
-checkout defaults to the working directory, and `DE_PORT` overrules the config, so two
-checkouts can be drawn at once. A repository that builds the tool rather than installing it
-wraps this in a script - in the ethlete SDK, `yarn design:check`. There, the user reads the
-calls in Ethlete Studio, started with `yarn studio`, and Studio serves the frames itself. Do not
-start `yarn design` next to it.
-
-Ethlete Studio carries its own copy of the tool, so it draws a checkout that installs nothing.
-The machine still needs Node, and the render stage still needs `playwright` where the copy in
-use can reach it.
-
-`call.ts` calls `defineCall` from `@design-explore`. Each variant carries a `key`, a `name`,
-a `claim`, a `cost`, an optional `verdict` of `chosen` or `rejected`, and a `load` that
-imports its own module.
-
-In a call that runs past about a dozen variants, every variant names the pass that drew it with
-`round: 'r3'`. **That tag is the only thing that makes a round exist**, in the order the variants introduce
-them. A round whose variants all carry a verdict is **settled**.
-
-`rounds` is prose only. Each entry gives a `key`, a `title` and a `note` saying what came out
-of that pass, which is how the intro stays short and each pass reads as a reply to the one
-before. An untagged round still draws - it says the bare key until somebody writes the entry. A
-`rounds` entry that no variant names is stale prose, and the check reports it. Write the note in the same pass that sets the verdicts, never
-before the user rules.
-
-A call with one variant and no `claim` is a **view**: one reference picture, drawn full
-width with no verdict tag. Use it for a picture that answers no question.
-
-Two call-level fields take a call out of the open list:
-
-- `closed: 'shipped'` once the app implements the call, `closed: 'superseded'` once another
-  call replaced it. A closed call counts as settled, even with unruled variants.
-- `waitsFor: '<slug>'`, the full slug of another call, when this call is parked on it. Studio lists
-  it under "On hold" and leaves it out of the open counts until that call settles. Then it is
-  open again by itself, so remove the field only when the reason changes.
-
-Three constraints the tool puts on a variant file:
-
-- **Never import a package barrel.** The libraries resolve to source, so one barrel makes
-  the browser request every module in the library, 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.** Variants drawn at three
-  geometries cannot be compared.
-- **One file per variant**, so a broken variant breaks its own frame only.
+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.
+
+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. 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:
 
-A `<script>` in a drawing's `body` never runs. For behavior - a play button that restarts a
-CSS animation, a click that toggles a class - give the drawing a `setup(root)` function. The
-frame calls it once, after the markup is in `root`. `setup` has no cleanup hook, because each
-frame load is fresh. Wire behavior with one delegated listener on `root`. `setup` can also be an array of functions, run in order. If one throws, the
-markup stays and the error shows on top of it.
+```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.
+
+### 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';
+```
 
-For a prototype with states, render each state with `ngStates({ closed: …, open: … }, { imports })`
-and put its `body` in the drawing. `setup: flow.on([{ click: '.trigger', go: 'open' }])` swaps the
-states on a click, in a View Transition. To draw an open overlay, open it in
-the template (`<et-select [open]="true">`, `<div etMenu [open]="true">`): `ng()` returns the real
-panel, and the frame places it below its trigger. See `components/ssr/02-open-overlays`. `ngStates` wraps the states in a
-`<div data-de-states style="display: contents">` host. So `flow.body` must be the drawing's body,
-or contain it. A selector rule must not depend on that wrapper. See `components/ssr/01-states`.
+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
@@ -160,15 +435,31 @@ Either way:
   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:
+each stage draws with what the stages before it settled (the wireframes draw with the kit only):
 
-1. **Foundations**: colours, colour themes and surface themes (the project's `themes` in
-   `config.json`), plus the type scale, spacing and radius.
-2. **Logo and CI**, if the project needs them.
-3. **Wireframes**: early, rough concepts of the main flows (`mode: 'wireframe'`). They show
+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
@@ -181,7 +472,10 @@ each stage draws with what the stages before it settled:
    ],
    ```
 
-4. **Components**, from the SDK ones rendered with `ng()`, themed and set up for the project.
+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.
@@ -191,27 +485,36 @@ Do not start a stage before the one above it is settled, and do not draw a page
 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.
 
-A quick exploration of an idea does not run this order: start it with `--stage sketch`. A
-sketch needs no settled stage before it, and Studio lists it apart from the seven stages. When
-the idea holds, draw it again at its real stage.
-
-A call made before the stage was required carries `legacy: true`, which
-`et design legacy <project>` writes once. It also writes the stage its group folder implies:
-`foundations` is `themes`, `components` is `component`, `pages` is `page`; another folder gets
-none. Run it again to add the stage to an old legacy call; a stage already there stays. A
-settled legacy call with a stage counts for that stage in this order. Never add `legacy` to a
-new call.
+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 and open a component call for it. Never draw the part
-inline in the page.
+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 project's design system, `.ethlete/design/system/<project>/`.
+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
@@ -244,22 +547,10 @@ you draw a part, look for it in this order, and draw new only when none of them
 3. Only then a new drawing. Build it from the two above, and say in the variant's `claim`
    that the part is new.
 
-One entry is one folder:
-
-```
-.ethlete/design/system/<project>/<entry>/
-  <entry>.ts    exports the drawing function, with typed options; built from the SDK mocks
-  entry.md      what it is, when to use it, which SDK parts and options, do and do not
-```
-
-Its preview is a view call at `.ethlete/design/calls/<project>/system/<entry>/`, because the
-tool reads calls from `calls/` only. A variant imports the entry with a relative path. Read
-every `entry.md` of the project before the first drawing of a session.
-
-**An entry exists only because the user accepted it.** A `chosen` verdict is not enough: a
-chosen variant is often a layout or a one-off. When the user says to accept a part into the
-system, extract it in one commit: the entry folder, its preview call, and the source call's
-variant changed to import it. Never change an entry's look without a call the user settled.
+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.
 
 ## Check before you look
 
@@ -273,7 +564,8 @@ With `et design`, run the checker from the checkout it draws:
 et design check --lint <changed files> --tsconfig
 ```
 
-`--tsconfig` with no path types every call of the checkout. `--checkout <path>` names another
+`--tsconfig` with no path types every call of the checkout. `--tsconfig` also types each variant of
+an open sketch and prints the tsc output of a failing one. `--checkout <path>` names another
 one.
 
 With a Storybook, copy {%resource:check-story.mjs%} to the **repository root** first:
@@ -293,11 +585,13 @@ et design check --call <slug> --variant b # one of them
 node check-story.mjs --tsconfig <path> --story <story-id>
 ```
 
-## Delegating a call
+## Delegating a sketch
 
-Every brief names `model: opus`.
+Every brief names `model: opus`, and every prompt names the exact model id the sub-agent runs on,
+for example "Your model id is `claude-opus-5-5`; pass `--by claude-opus-5-5` to every write
+command." You know the id because you chose the model; the sub-agent does not, and must not guess.
 
-1. **One agent per call.** It draws all the variants of the call. Give it the call folder, the
+1. **One agent per sketch.** It draws all the variants of the sketch. Give it the sketch folder, the
    fixture it must not change, and the claim of each variant. Do not spawn one agent per
    variant: each would re-read the skill, the call, the fixture and the example, about 45-57k
    tokens each, so the cost is several times higher. Calls are independent, so several calls
@@ -305,9 +599,9 @@ Every brief names `model: opus`.
 2. **One check-and-fix agent, after the drawing agents return.** Give it the changed files
    and the call slug. It runs the check above, fixes what it reports, and repeats until the
    check says `ok`. It may not change what a variant draws, only what stops it rendering.
-3. **One write-up agent, once the user settles the call.** Give it the verdict in the
+3. **One write-up agent, once the user settles the sketch in Studio.** Give it the verdict in the
    user's own words and the plan file. It records what won, what lost and why, it sets each
-   variant's `verdict` in `call.ts`, and it writes that round's `note`. It runs while you open
+   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