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

package/content/skills/design-exploration/reference-check-and-notes.md

@@ -0,0 +1,92 @@
+# Design exploration: checking a product, drawing files and notes
+
+### 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.

package/content/skills/design-exploration/reference-flows-and-wireframes.md

@@ -0,0 +1,78 @@
+# Design exploration: flows and wireframes
+
+### 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`.

package/content/skills/design-exploration/reference-inbox-and-mcp.md

@@ -0,0 +1,54 @@
+# Design exploration: the inbox and the MCP server
+
+### 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.
+
+### The `ethlete-design` MCP server
+
+`ethlete-agents sync` registers `et design mcp` as `ethlete-design` in `.mcp.json` and
+`.codex/config.toml` when `@ethlete/cli` is installed. When the tools are in your tool list, use them
+instead of the CLI: each runs the `et design` command of the same name in the session's working
+directory, takes its flags as arguments, and every write takes `by` (your model id). `product` may be
+left out when the workspace has one. `shot` and `motion_shots` return the sheet image itself, so you
+look at it without opening a PNG path.
+
+- **Read:** `parts` (every part, as JSON), `call` (a call's `call.ts`, `fixture.ts`, the variant file to draw into and the frame URL; never change the fixture).
+- **Check:** `check` (a product; with `call` and `variant` it lints, type-checks and renders that variant - run it after every edit of a variant), `sketch_check` (each variant laid over the product), `sketch_preview` (what a merge of a variant changes).
+- **Shots:** `shot` (a part's states, `variants` for the open sketch), `motion_shots` (a motion at its keyframes, full and reduced, plus its tracks as JSON).
+- **Sketch lifecycle:** `sketch_new`, `sketch_variant`, `sketch_round`, `sketch_report`, `sketch_ready`, `sketch_rebase`, `sketch_list`. `sketch_merge` and `sketch_discard` exist, but Studio runs them on the user's click; do not call them.
+- **Comments:** `inbox` (what waits for you, then for the user), `comment_reply` (`question` waits for the user's answer), `inbox_done` (needs the new part `note`).
+
+Part files are written with your own file tools; the server has no write tool for them. Call
+`sketch_report` before every variant edit: it tells Studio what you build. It refuses a `ready` sketch: only when the
+user asks for a change, run `et design sketch report … --reopen`, which moves the sketch back to in progress, and call
+`sketch_ready` again when you are done. `sketch_ready` runs the
+render check and refuses on any render issue; mark an element that renders wrong on purpose with
+`data-et-skip="<rule>"`. A tool that fails returns the CLI's output; fix it and call again.

package/content/skills/design-exploration/reference-order-and-design-system.md

@@ -0,0 +1,124 @@
+# Design exploration: the order of a design and drawing from the design system
+
+## 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.
+Interaction states (a state name whose last word is hover, focus, pressed, active or selected, such as `row-hover`) live only on a control
+part, one whose `controls` declare a control of a checked kind. On a shell, element or page they fail as
+`CONTROL-STATE`: declare the component's controls (Q164), or extract the button or row as its own control part and draw its states there.
+A drawn `button`, `a[href]`, `input`, `select`, `textarea` or control role without `data-et-control` on it or around
+it is `CONTROL-PART-INPUT`: no control check sees it. Wrap it in `control(markup, name)` from
+`@ethlete/components/design/control` and declare the name in `controls`; a sketch fails on one it adds,
+`design check` only warns of one a merged part already draws. On a reused control part's render,
+`control(drawn.body, name)` renames its control: never string-replace `data-et-control`.
+`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 = ng(`<et-form-field><et-label>Name</et-label><et-input /></et-form-field>`, {
+     imports: ['FORM_FIELD_IMPORTS', 'INPUT_IMPORTS'],
+   });
+
+   export default field.then((body) => drawing({ body }));
+   ```
+
+   Never `await` at the top level of a design module: WebKit can hang for good when a frame is
+   removed while the module evaluates, and `et design check` fails it with `TOP-LEVEL-AWAIT`. A
+   call default-exports a promise of its drawing; a part awaits inside its `render`.
+
+   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 = 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.
+
+**Colours come from the two SDK theming systems, never from tokens of your own.** A raised or
+floating area sets a surface scope (`data-et-surface` or a surface scope class) and takes its
+background, text, border and interaction states from the `et-surface` tokens of that scope. An
+accent, a warning or a danger colour comes from the SDK colour theming (`--et-theme-color-*` under a
+colour theme scope). Foundations define only the inputs of these themes. Never add a tier class
+(`bg-surface-raised`), an accent utility or a `var(--accent)` to a part or to the product
+stylesheet. Give a raised or floating area `data-et-auto-surface` and an interactive one
+`data-et-surface-interactive`, never a picked `et-surface--<name>` class: the frame resolves them by elevation like
+`etAutoSurface` and `etSurfaceInteractive`. Give a warning, error or success accent
+`data-et-semantic-color="<type>"`, never a picked `et-color--<name>` class: the frame resolves it by type like
+`injectSemanticColorTheme`. Read the theming skill of the SDK before the first colour in a drawing. `et design check` reports
+a denied class from the product's `deniedClasses` list in `config.json`.
+
+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.

package/content/skills/design-exploration/reference-products-and-sketches.md

@@ -0,0 +1,199 @@
+# Design exploration: products, sketches and rounds
+
+### 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 target add <layer>/<name> <layer>/<name> --by <model id>   # add a part to an open sketch's targets, seeded into each variant
+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-6.1-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.

package/content/skills/design-exploration/reference-shots.md

@@ -0,0 +1,25 @@
+# Design exploration: shots and screenshots
+
+**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.
+
+## 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 `shoot-template.mjs` from this skill folder 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.

package/content/skills/git-commit/SKILL.md

@@ -30,4 +30,14 @@ Commits are **lean** and follow {%commitRuleSource%}:
   refuses an untracked file: run `git add -N <that file>` for that one path
   first. Pass a formatter or `eslint --fix` the exact paths you changed, never a
   list from `git diff` or `git status` - that list holds other sessions' files.
+- **Few commits.** One commit per finished slice of work: the code, its specs, its
+  changeset and its plan note ("as built") go in together. Fix format, lint and
+  review findings before that commit, not in a follow-up commit.
+- **Notes are not commits of their own.** A plan, finding or status note rides
+  with the slice it belongs to; a note-only session commits once per finished
+  round, never once per finding or status line.
+- **Sketches:** one commit per finished round and one per merge.
+- **Never rewrite shared history.** No rebase, no `--fixup`, no `--amend` in a
+  checkout that other sessions share: it rewrites their commits too.
+- Brief every subagent with these commit rules.
 - Don't push unless asked.

package/content/skills/grilling/SKILL.md

@@ -47,5 +47,6 @@ This section is ours, not upstream.
 - **Check the facts before you recommend.** A recommendation built on an assumed file format or
   an assumed existing tool is worse than none. Look it up first, and say in the round when a
   look-up proved an earlier recommendation wrong.
+- **Decide technical questions yourself.** Put only product and UX questions to the user.
 - **Close with the shared state.** When the frontier is empty, list every decision in one short
   summary and ask the user to confirm it before you write it anywhere.