@graview/skills 0.0.0-stage → 0.1.0

package/skills/graview-brand/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: graview-brand
+description: Put an installation's own name, mark, typeface and palette on a Graview app without forking a package, and let graview check measure the contrast rather than trusting it.
+---
+
+# Brand an installation
+
+Every primitive reads a custom property and `themeCss(scheme, brand)` emits
+them, so a brand is a DECLARATION rather than a fork. The part worth getting
+right is that a custom palette can be wrong in ways nobody notices until
+somebody with a bright office files a bug — so the framework measures it.
+
+## Do this
+
+1. **Declare the brand in your domain layer**, so `graview check` reads it:
+
+   ```ts
+   import { brandFromAccent, DARK, LIGHT, type Brand } from "@graview/core";
+
+   const derived = brandFromAccent({ accent: "#7a4bd0", base: { dark: DARK, light: LIGHT } });
+   if (!derived.ok) {
+     throw new Error(`Needs ${derived.missing.join(", ")} — ${derived.why}`);
+   }
+
+   export const brand: Brand = {
+     name: "Acme Bids",
+     // Inline SVG using currentColor: one file works in both schemes.
+     logo: '<svg viewBox="0 0 24 24" ... stroke="currentColor">...</svg>',
+     typography: { body: '"Inter", ui-sans-serif, system-ui, sans-serif' },
+     schemes: derived.schemes,
+   };
+   ```
+
+2. **Expect the refusal path to be real.** No single colour can be accent TEXT
+   in both schemes — 4.5:1 on white needs a lightness under about 0.18 and
+   4.5:1 on a dark panel needs one over about 0.24, and those do not overlap.
+   So `brandFromAccent` keeps the hue and saturation, which are the brand's,
+   and moves the lightness the smallest distance that clears AA. When that
+   distance is far enough that the colour has stopped being theirs, it refuses
+   and names what to supply. **Do not catch that and carry on with a guess** —
+   shipping a colour they did not choose under their own name is worse than
+   asking.
+
+3. **Hand it to `themeCss` and to the provider.**
+   `sheet.replaceSync(themeCss(scheme, brand))` for the tokens;
+   `<GraviewProvider brand={brand}>` so `Wordmark` and anything else that asks
+   can read the name and the mark.
+
+4. **Declare it on the app too:** `defineApp({ ..., brand })`.
+
+5. **Colour the kinds themselves.** Every surface that colours by kind —
+   chips, districts, calendar spans, rosters — reads `brand.accents`, a hue
+   in degrees per kind, before falling back to the stable hash:
+
+   ```ts
+   accents: { gardener: 28, plot: 42, planting: 122, rule: 210 },
+   ```
+
+   `graview check` refuses an accent naming a kind nobody declared (a typo
+   would otherwise silently hash) and a value that is not a number.
+
+6. **Dress the lines: the kit.** Everything the scene draws that is not a
+   view is declared on `brand.kit` — any part, the rest as shipped:
+
+   ```ts
+   kit: {
+     connectors: {
+       all: { route: "orthogonal" },                       // curve | straight | orthogonal
+       byEdge: { "tended-by": { colour: "#1d3f8a", pattern: "dashed" }, "grows-in": { visible: false } },
+     },
+     captions: { visible: true }, grid: { visible: false }, lattice: { size: 46 },
+     tags: { visible: true }, emphasis: { dim: 0.34 }, marks: { flag: "⚠" },
+   },
+   ```
+
+   A route or a pattern is a named strategy, one case in one file
+   (`@graview/react` `routes.ts`, `@graview/render` `connectors.ts`), so
+   the next one is one more case. `graview check` holds an explicit line
+   colour to 3:1 against both grounds in both schemes
+   (`kit-contrast-below-aa`); a kind kept quiet is still on the inspector.
+   An embed's `handle.setBrand({ ...brand, kit })` re-dresses it live.
+
+## Styling by conversation
+
+This skill is built to be DRIVEN IN NATURAL LANGUAGE — "warmer", "more
+editorial", "our green is #1B4332", "make people amber and money green" —
+because the whole look is one serialisable declaration:
+
+- **palette** → change `accent` (or supply explicit scheme tokens) and let
+  `brandFromAccent` move lightness the minimum distance that clears AA;
+- **lines** → `kit.connectors` ("right-angled lines", "hide the grows-in
+  lines", "make tended-by dashed and navy") and the ground's `kit.grid`;
+- **feel** → `shape.radius` (square = formal) and `shape.density` (tight =
+  dense) — one number each;
+- **voice** → `typography.body/display/mono` with real fallback stacks;
+- **kind colours** → `accents` hues per kind;
+- **per-kind layout** → register a view over the registry cell, the same
+  authoring move as everything else (see graview-node-kind).
+
+The loop for each request: edit ONLY the declaration file, run `pnpm check`
+(the framework measures contrast rather than trusting either of you), then
+`pnpm survey` and show the before/after screenshots from `docs/survey/`
+side by side. Never edit a component to achieve a look a token can carry —
+if a look genuinely needs one, that is a missing token to raise, not a fork
+to make.
+
+## Worked example
+
+- `apps/todo/src/domain/brand.ts` — "Things" from one accent, one mark and one
+  typeface, with the refusal path left live
+
+## Then find out whether it worked
+
+```sh
+pnpm build && npx graview check ./dist/domain/app.js
+```
+
+`theme-contrast-below-aa` names the exact token pair, the scheme and where it
+is drawn — "a field name", "text on a filled accent" — because "your theme has
+a contrast problem" is not something anyone can act on.
+`theme-token-unreadable` reports a value the checker could not parse rather
+than passing it silently, which is the failure mode a contrast check exists to
+prevent.
+
+**And look at it, in both schemes.** The checker measures contrast and nothing
+else. Run the app with `?theme=light` and `?theme=dark`, and run axe against
+both — the framework's harnesses do this and report zero violations, which is
+the bar a branded installation should also clear.
+
+## What the check cannot see
+
+- Whether it looks like the brand. Contrast is measurable; taste is not.
+- Whether the logo reads at 18 pixels. Most do not.
+- Whether the typeface is loaded. A declared face with no `@font-face` and no
+  web font silently falls back, and the fallback is usually fine — which is why
+  nobody notices for months.
+- Anything about a value it cannot parse. It says so; believe it.

package/skills/graview-desk/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: graview-desk
+description: Put a model INSIDE a Graview product — a surface that takes photographs or words, reaches the model through a declared door, and turns the answer into a plan somebody reviews before it touches the graph.
+---
+
+# A desk a model works at
+
+`graview-agent-seat` is the model BESIDE the product: a seat in the bar that
+answers questions and proposes a change. A desk is the model INSIDE it — the
+surface a person brings something to. Photographs of a property, a paragraph
+about a season, a spreadsheet somebody was sent. It is often the feature the
+product is for, and it is four seams, all of which the framework ships.
+
+## The four seams
+
+1. **Intake** — getting the something in. `<Intake onPhotos={...} />` hands
+   back data URLs.
+2. **A door** — reaching the model. Declared, not hard-wired:
+   ```ts
+   intelligence: [{
+     name: "surveyor",
+     kind: "llm",
+     reach: ["paste", "local"],
+     bridge: "/__graview/local",
+     keyStorage: "in this browser only, never in the repository",
+     may: ["stake-out", "place-feature"],
+   }]
+   ```
+   `<Door provider="surveyor" prompt={...} photos={...} onProposals={...} />`
+   draws exactly the doors declared. **Paste is the floor** — a prompt out, an
+   answer back, no key and no network — and a product reachable that way is a
+   product anybody can run. `local` is the machine under the dev server
+   (`localIntelligence()` from `@graview/ship/dev`), offered only when
+   something is actually answering there.
+3. **A plan** — what came back, as an object rather than a list: ordered by
+   the chain, judged against the policy and the provider's `may`, reviewable.
+   `planFrom(store, proposals, { app, principal })`.
+4. **A review** — `<PlanReview plan={plan} onApplied={...} />`. Applied as one
+   turn, so `store.undo(batch)` takes the whole thing back.
+
+## Do this
+
+1. **Write the prompt from the graph.** What kinds exist, what acts exist and
+   what they take — `generateLlmsTxt(app)` writes that — plus what is already
+   there. A model that cannot see the graph invents a second Back Lawn.
+
+2. **Ask for proposals, not prose.** One JSON object with a `proposals` array
+   of `{ mutation, args, as?, why? }`. `firstJsonObject` finds it inside
+   whatever the model wrapped it in; `validateProposals` drops what this app
+   does not have and what the provider may not do.
+
+3. **Declare the allowlist and mean it.** `may` is enforced by the store now,
+   on every path including your own code. A surveyor that may describe the
+   ground and may not touch the record is a promise the runtime keeps.
+
+4. **Never a second path to the store.** The desk's answer becomes ordinary
+   mutations, applied by the same store, judged by the same policy, in the
+   same log, with the same undo. "Add AI" is an entry in the declaration,
+   never a way around it.
+
+5. **Say what it did in the product's words.** `why` on each proposal is the
+   sentence the review shows; a plan of eleven calls with no reasons is a
+   thing nobody can approve.
+
+## Then find out whether it worked
+
+```sh
+pnpm build:domain && npx graview check ./dist/domain/app.js
+```
+
+The checker verifies every act in `may` exists, warns on a `local` reach with
+no bridge and a `key` reach with no storage story, and `graview describe`
+lists the doors. Then drive it: a test that feeds a canned answer through
+`planFrom` and asserts the plan's order, its refusals and what the graph
+holds afterwards costs ten lines and catches the whole class.
+
+## What the check cannot see
+
+- Whether the model can actually see what you sent. A photograph a model was
+  never handed produces a confident description of nothing.
+- Whether a refusal is legible. The store refuses in a sentence; if the desk
+  swallows it, a person meets a button that does nothing.
+- Whether the answer is TRUE. Everything here makes a proposal safe, ordered
+  and reversible. None of it makes it right, which is why a person reads it.

package/skills/graview-embed/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: graview-embed
+description: Put a Graview app on somebody else's page — a picture in an article, a chapter in the docs, a live demo in a landing page — with its own theme scoped to one element, and nothing on the host touched.
+---
+
+# The embed: an app on somebody else's page
+
+`@graview/embed` mounts an app into any element on any page. It brings its
+own theme scoped to that element, the brand's fonts, and a strip with the
+faces and the places — no `Shell`, no router, nothing of the host's styled
+or listened to. It is the same declaration, the same store and the same acts
+as the app itself; only the frame is the host's.
+
+```ts
+import { mount } from "@graview/embed";
+
+const handle = mount(el, {
+  app, store,                     // or `seed`, and one is made
+  views,                          // the app's own registry, in its own schema
+  stop: "#focus=agg:plot",        // the fragment the app would put in its address bar
+  scheme: "auto",                 // the host's data-theme, else the system's
+  label: "Chapter 13",            // names every landmark inside
+});
+handle.setFace("pages"); handle.setStop("#focus=plot-2"); handle.unmount();
+```
+
+`graview create` writes this as `src/embed.tsx` and an `embed.html` host, so
+the project's own `pnpm typecheck` covers the embed surface from day one.
+
+## The moves
+
+1. **Say where it opens with the stop, not with code.** `stop` is exactly
+   the fragment the app writes — `#overview=1`, `#focus=agg:plot`,
+   `#view=the-week` — so a link you copied from the app is an embed's
+   starting point. `face` follows the stop unless you name one.
+2. **Pick the face for the page.** `"scene"` and `"graview"` are the app;
+   `"pages"` is the routed face, opened at `path`; `"picture"` is ONE named
+   lens alone (`stop: "#view=the-week"`), no bar and no rail — a page
+   about a lens shows the lens. `toggle: false` drops the strip too.
+3. **Name it.** Two embeds on one page carry the same landmarks — the
+   relation key, the inspector, the pages' navigation — and a landmark must
+   be unique by role and name. `label` names every one of them after the
+   embed; leave it off and two embeds are one confusing region twice.
+4. **Let the host decide the look.** `scheme: "auto"` follows the host's
+   `data-theme` stamp; `setScheme` follows a host toggle; `fonts: false`
+   when the host already loads them; `brand` / `setBrand` to dress it.
+5. **Make the policy felt, if the page is about it.** `seats` lists the
+   principals a reader may take — each a label and a `Principal` — on the
+   strip; the acts, the pages and the strip narrow the moment one sits
+   down, and `setSeat` does it from the host. See `graview-permissions`.
+6. **Many on one page: mount when near.** `mountWhenNear(elements,
+   mountOne)` mounts each as the reader scrolls toward it, so a page of
+   sixteen chapters costs one at a time. Share a `store` between embeds
+   only when they are meant to be one app seen twice.
+7. **Presence is opt-in.** An embed broadcasts nothing and draws nobody
+   unless it is handed a `presence` channel: putting a graph on a page does
+   not tell its readers about each other.
+
+## Worked examples
+
+- `apps/seedbed/src/site-embed.ts` — the docs site's chapters, many to a
+  page, mounted as the reader nears them, the rota's seats on the strip
+- `apps/rota/src/embed.ts` — two embeds of one app on one host page, each
+  named for what it shows
+- `packages/core/src/scaffold/ui.ts` — what `graview create` writes
+
+## Then find out whether it worked
+
+```sh
+pnpm build && npx graview check ./dist/domain/app.js   # the declaration is still whole
+pnpm typecheck                                          # the embed takes the app's own views, no casts
+```
+
+Then open the host page at a phone's width and with two embeds on it: each
+names its own landmarks, neither pushes the page sideways, and pressing a
+place in one moves only that one. `packages/embed/tests/unit/embed.test.ts`
+holds the contracts; copy its shape for a host of your own.
+
+## What the check cannot see
+
+- Whether the host's CSS reaches in. The embed scopes its own theme; a host
+  rule like `button { … }` on the whole page still applies, and only looking
+  at the page finds it.
+- Whether the stop still lands. A stop names ids and places; rename a place
+  or seed different ids and an embed opens somewhere it resolves to rather
+  than where the article says it does.

package/skills/graview-invariant/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: graview-invariant
+description: Write a Graview invariant that judges the graph and NAMES the mutations that would repair it, then verify it with graview check and by making it actually fire.
+---
+
+# Write a rule that names its own repairs
+
+An invariant is not a validator. A validator says no; an invariant says what is
+wrong, which nodes are implicated, and **which mutations would fix it** — and
+that last part is the seam the whole affordance system rides on. A repair
+naming a mutation is why selecting an out-of-balance set of duties surfaces
+"rebalance" without anyone writing a rule to produce that suggestion.
+
+## Do this
+
+1. **Scope it to a kind, or to the graph.** `scope: { kind: "session" }` runs it
+   once per session; `scope: "graph"` runs it once. Use `match` to narrow
+   further — the worked examples scope to a `rule` kind and match on the rule
+   node's own `spec.type`, so the rules a domain enforces are *data* rather
+   than code, and a coach can be told which rule fired by name.
+
+2. **Declare `repairs` statically.** The array of mutation names this rule may
+   propose. `graview check` verifies every one exists, so a repair pointing at
+   a renamed mutation is a build failure rather than a surprise the first time
+   the rule fires.
+
+3. **Return violations that carry their implications.**
+
+   ```ts
+   export const sessionFits = defineInvariant("session-fits", {
+     scope: { kind: "rule", match: (node) => node.spec.type === "session-fits" },
+     repairs: ["cut-drill"],
+     evaluate({ graph, subject }) {
+       // ... find the session and its drills ...
+       if (planned <= budget) return [];
+       return [{
+         invariant: "session-fits",
+         subjectId: subject.id,
+         label: subject.label,
+         // In the app's own words. This is shown in the strip verbatim.
+         message: `${session.label} plans ${planned} minutes into ${budget} — ${planned - budget} over`,
+         // Every node this is ABOUT. Views light these wherever they are
+         // drawn, and selecting the rule lights them — which is the only
+         // reason selecting a rule changes the picture at all.
+         nodeIds: [session.id, ...drills.map((d) => d.id)],
+         repairs: drills.map((drill) => ({
+           mutation: "cut-drill",
+           args: { sessionId: session.id, drillId: drill.id },
+           label: `Cut "${drill.label}" — ${drill.minutes} minutes back`,
+         })),
+       }];
+     },
+   });
+   ```
+
+4. **Keep `evaluate` pure.** Same graph and context in, same violations out. No
+   clock, no random source, no DOM. That purity is what lets the whole tier run
+   headlessly, and what lets `preview` say what a change *would* break before
+   it happens.
+
+5. **Fill in `missing` for a repair that cannot be complete.** A repair still
+   needing an argument lists it, and the framework offers real candidates for
+   it — the interface never wires up a picker per mutation.
+
+## The horizon
+
+A scoped invariant judges only CURRENT subjects — nodes retired under their
+kind's declared `lifecycle` are skipped, because a rule about last term's
+agreement is noise, not a violation. An invariant that genuinely audits
+history says so with `judgesPast: true`.
+
+So a rule about the past and the present — "nothing closed may still depend
+on something open" — is written from the side that is still current: the
+subject is the OPEN thing, the violation names what closed against it, and
+the repair acts on the subject, because that is the node a person can still
+act on. Judging the closed one would put the violation behind the horizon
+and the repair on a thing that has already left the picture.
+
+## Then find out whether it worked
+
+```sh
+pnpm build && npx graview check ./dist/domain/app.js
+```
+
+The checker catches `repair-unknown-mutation`, `invariant-scope-undeclared` and
+`required-invariant-unregistered`. Report the real output, warnings included.
+
+**And make it fire.** A rule that never returns a violation passes every check
+and does nothing. Write a test that builds a graph which breaks it:
+
+```ts
+it("catches an over-long session and offers a way back", () => {
+  const store = createStore({ snapshot: overbooked });
+  const violation = store.violations().find((v) => v.invariant === "session-fits")!;
+  expect(violation.nodeIds).toContain("s-tue");
+  // And the repair actually resolves it, which is the claim that matters.
+  const repair = violation.repairs[0]!;
+  store.apply({ name: repair.mutation, args: repair.args! });
+  expect(store.violations().some((v) => v.invariant === "session-fits")).toBe(false);
+});
+```
+
+## What the check cannot see
+
+Say so rather than implying otherwise:
+
+- Whether the message reads as something a person would say.
+- Whether `nodeIds` names everything the rule is genuinely about. Too few and
+  the picture does not change when you select the rule; too many and it lights
+  the whole screen.
+- Whether the repair is one a person would actually want. A technically
+  resolving repair nobody would choose is worse than no repair at all.

package/skills/graview-lens/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: graview-lens
+description: Build a Graview lens that binds ROLES rather than field names, so a second domain can reuse it unchanged — and prove the reuse rather than asserting it.
+---
+
+# Build a lens
+
+A lens is a picture that knows nothing about your domain. The timeline does not
+know what a duty is; it knows there is a `start`, an `end` and a column. The
+coverage matrix does not know what a requirement is; it knows there are rows,
+columns and an edge that fills a cell. That indirection is the entire point: a
+lens written for one app is used unchanged by another.
+
+The framework ships five, each built from the public primitives — which makes
+them the worked example of the authoring API rather than privileged insiders.
+Read one before writing your own:
+
+- `packages/primitives/src/lens/timeline.tsx` — intervals in columns
+- `packages/primitives/src/lens/calendar.tsx` — the same intervals, by date
+- `packages/primitives/src/lens/coverage.tsx` — a bipartite mapping
+- `packages/primitives/src/lens/board.tsx` — position given by the domain
+  (discs for codes of three characters, tokens for words; `arrange: "shelf"`
+  when the x and y are categories rather than coordinates)
+- `packages/primitives/src/lens/plan.tsx` — an outline, with points inside it
+
+(`reach.tsx` sits beside them and is not one: no factory, no roles to
+rebind. A view that ships is still a view.)
+
+The plan is the one to read if yours draws anything, because it is the one
+that learned what drawing costs. A name is fitted to the shape it names —
+`fitLabel` and `spanAt` from `@graview/layout`, which give the width of a
+shape AT A HEIGHT rather than its bounding box, because the shapes that
+overflow are the long thin ones. Names are painted after everything else,
+because a marker dot took the first letter off two of them. Whatever will
+not fit goes in a key underneath. And `useDrawnSize` answers the question a
+scalable drawing hides: at THIS size, can a person read it, or press it? A
+one-pixel target with a keyboard stop and an ARIA label is not an accessible
+control; it is an inaccessible one that has been described.
+
+Start it with the scaffolder — `graview lens grounds-map --roles regions,markers
+--binds entities` — which writes all eight rules below already in place, and
+the reuse test beside it, red on purpose.
+
+## Do this
+
+1. **Name the roles, not the fields.** A lens declares
+   `requiredRoles: ["start", "end"]`; an app says which of ITS fields fill them.
+   If your lens names `dutyId` anywhere, it is not a lens.
+
+2. **Choose which shape of binding you need.** There are two, and assuming
+   there was one is how the first version of this got it wrong:
+   - **fields** — a kind's own field names onto roles
+     (`{ session: { start: "start", end: "end" } }`). The timeline.
+   - **entities** — roles onto whole kinds and edges
+     (`{ rows: { kind: "skill" }, link: { edge: "develops" } }`). The matrix.
+     A relationship that IS a node — a concern addressed by a practice,
+     applied by a routine, covering a ground — binds
+     `link: { path: ["covers", "applies", "addresses"] }`, column end first;
+     each cell then carries the nodes it walked through, which is what you
+     actually want to press.
+
+3. **Fail loudly on a bad binding.** Throw a named error saying which role and
+   what was missing. A lens that renders empty when misbound costs an hour.
+   Loud means THE PANEL SAYS SO, not the application is gone: every view host
+   sits behind an error boundary, so a throw draws the error's own message in
+   the view's place — named with the kind and the view — and leaves the bar,
+   the districts and every other view standing. Give the error a `hint`
+   property and the panel prints it under the message, which is where a
+   sentence about what to bind instead belongs.
+
+4. **Mark every real thing as a target.** Anything standing for a node gets
+   `data-graview-pick={id}`. That one attribute is the whole contract: the host
+   routes a click on it to that node, gives it a tab stop and a role, and a
+   single click selects it in place while a double click travels. A span you
+   cannot click is the bug this prevents.
+
+   **Drawing in SVG? The framework sets the role; you set the `aria-label`.**
+   A `<g>`, `<polygon>`, `<circle>`, `<rect>`, `<path>`, `<ellipse>`,
+   `<polyline>`, `<line>` or `<use>` carrying the mark becomes a button like
+   any `<span>` — but a shape has no text inside it to be named by, so
+   without a label it is a stop that announces nothing, which is worse for a
+   keyboard than not being reachable at all. Name it after the thing it
+   stands for.
+
+5. **Read `implicated` and `flagged`.** Empty means "no emphasis", NOT "nothing
+   is related". Expose what you decide as `data-graview-emphasis` so it can be
+   checked — a claim about a picture that exists only as a colour cannot be
+   checked by anything, not a test and not a person reading the tree.
+
+6. **Render at three fidelities.** `glyph` is a chip; `summary` is denser
+   content, not the same content scaled down; `full` is the picture.
+
+7. **`nodes` is THE GROUP'S MEMBERS, and nothing else.** A lens mounted over
+   a kind's `many` cell receives that kind's members in `ViewProps.nodes` —
+   not the graph. Every interesting lens draws more than one kind (a board
+   has slots and occupants, a matrix has rows and columns, a map has regions
+   and markers), and every other kind comes from `store.graph`, narrowed back
+   to `nodes` for the group's own kind so the scene's horizon still applies.
+   Built from `nodes` alone, a map drew every piece of ground with nothing
+   standing in it: no error, no empty state, a complete, tidy, wrong picture,
+   which is the worst failure a lens has. The framework's own board lens had
+   this exact bug.
+
+   **`budget` is the most to draw.** A drive-in thumbnail hands a lens its 12
+   most relevant members with `budget` and `total`: hold what you read from
+   the store to it too, and say "+N more" (`withMore` does). A real catalogue
+   is thousands; a lens that draws them all at 6% stalls the city.
+
+8. **Take an arrangement, and say what you have no place for.** Every
+   picture over a kind can be sorted, filtered and grouped from the
+   declaration alone — `arrangeable(schema, kind)` offers the fields by
+   type, the edges by far end, the lifecycle and the standing — and the
+   choice travels in the stop as `in.sort`, `in.filter`, `in.group` and
+   `in.q`, beside the calendar's own `in.at`. In your lens's component:
+
+   ```tsx
+   const { nodes, arranged, bar } = useArranging(props, {
+     lensAllows: { group: false },        // a board has nowhere to group
+     allow: options.arranging,            // the app's say: false, or per part
+     arrangedBy: options.arrangedBy,      // how the picture opens
+   });
+   return <>{bar}<Picture nodes={nodes} /></>;
+   ```
+
+   `bar` is the framework's own row (`ArrangeBar`), drawn at full fidelity
+   unless declined; `nodes` are the members as arranged; `arranged.groups`
+   are there when the picture has a place for headings, as the calendar's
+   agenda does. Declare `arrangedBy` on the app's `lenses` entry too, in the
+   grammar (`{ group: "held-at" }`), so `graview check` holds it to the
+   bound kind and `graview describe` can say it. A person who arranged the
+   list can ask your picture the same thing in the same words.
+
+9. **Give it a name when you register it.** A lens mounted over a group is
+   registered on that kind's `many` cells, and the fourth argument names it:
+   `registry.register("gardener", { cardinality: "many", fidelity: "full" },
+   TendingView, { title: "Who tends what" })`. A titled group view is a
+   PLACE — the bar and an embed's strip list it by name, press it from
+   anywhere, and show it pressed while you are there. Without the title the
+   lens is reachable only by focusing the group, and once someone clicks
+   into a member nothing on screen says it exists.
+
+## Roles live in two places, and they do different jobs
+
+`defineNode("shift", { fieldRoles: { start: "from" } })` is what everything
+that is NOT a lens reads: the graph's own responder answering "when is it",
+the generated docs. A lens reads `bindings` and only `bindings`. Neither
+overrides the other, because neither is looking at the other — so bind the
+lens, and declare `fieldRoles` because the rest of the app wants them too.
+
+`graview check` NOTES it when the two disagree about one role. Often that is
+a mistake; sometimes it is right, because a role name belongs to a lens and
+`fieldRoles` has one namespace for all of them: a rota means the hour a shift
+starts by `start`, and its calendar means the day. Look once, then decide.
+
+## Then find out whether it worked
+
+```sh
+pnpm build && npx graview check ./dist/domain/app.js
+```
+
+The checker reads `lenses` in `defineApp` and reports `lens-role-unbound`,
+`lens-binding-missing-field` and `lens-binding-undeclared-kind`. Report the output.
+
+**And prove the reuse.** This is the claim a lens exists to support, and the one
+the checker cannot make for you — it NOTES every lens in `lenses` that the
+framework did not ship (`lens-authored-here`) so the question gets asked out
+loud, and the answer is yours. Write a test that builds it against a domain it
+was not designed for, then point at it with `provenBy: "tests/lens-reuse.test.ts"`
+and the note stands down:
+
+```ts
+it("works in a domain nothing here is about", () => {
+  // The board lens, pointed at a seating plan.
+  const built = buildBoard(nodes, edges, { slots: { kind: "seat" } }, schema);
+  expect(built.empty).toEqual(["seat-4"]);
+});
+```
+
+If you cannot write that test, say so plainly: you have written a view rather
+than a lens, and that is a legitimate thing to have written.
+
+## What the check cannot see
+
+- Whether the picture is legible. Run it and look, in both schemes.
+- Whether it survives being drawn small. The Graview renders the focused view
+  at natural size and scales it; `pnpm shrunk` measures whether it clips.
+- Whether the roles you chose generalise, or merely rename your own fields.