@graview/skills 0.0.0-stage → 0.1.0

package/skills/graview-new-app/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: graview-new-app
+description: Start a product on Graview in its own repository — the shape of the declaration, the shell that comes for free, and the CI that keeps it honest afterwards.
+---
+
+# Start a product on Graview
+
+Graview ships as eleven packages. A product built on it lives in **its own
+repository** and depends on them the way any other consumer does. This is the
+setup that gets you from nothing to something that can tell you when you have
+broken it.
+
+## Start with the scaffolder
+
+```sh
+# from a framework checkout (the packages are not published yet):
+pnpm install && pnpm build
+pnpm graview create ../my-app --link . --name "My App" --kind thing
+# once published, from anywhere:
+npm create graview@latest my-app        # or: pnpm create graview my-app
+```
+
+Put the product BESIDE the framework, never inside its git tree; `--link`
+names it relative to where you run the command. `--workspace` writes the
+layout every real product ends up with (a root, the app under `app/`, the
+harnesses beside it); `--merge` starts in a repository that already has a
+README, naming collisions rather than writing over them.
+
+It writes exactly the shape below — one kind with `creates`, `connects`,
+`writes` and a `lifecycle`, one rule with its repair, the shell, the routed
+face, a headless test, a CI workflow — installs it, and installs these skills
+into it. Run its `verify`, then replace the first kind with the product's own.
+The rest of this skill is what each part is for.
+
+## The shape
+
+```
+src/
+  domain/            # No React in here. This is what `graview check` reads.
+    schema.ts        # defineNode × n, createSchema (z comes from @graview/core)
+    mutations.ts     # defineMutation × n — every change is a named, typed act
+    invariants.ts    # defineInvariant × n — rules that name their repairs
+    policy.ts        # who may do what, if anyone
+    brand.ts         # name, mark, typeface, palette
+    app.ts           # defineApp({ ... }) — one object, the whole surface
+  ui/
+    views.tsx        # registerDefaultViews, then your own where you care
+    app.tsx          # the provider, the scene, the workbench
+  main.tsx
+```
+
+The domain/ui split keeps the declaration inspectable by a build, a CLI and
+an agent: `graview check` reads `defineApp`, and a React import there would
+drag a UI package into the checker.
+
+## Do this
+
+1. **Install.** The scaffold already did. Reach for `@graview/render/gpu`
+   only if you want the experimental capture path; the DOM path is what ships.
+
+2. **Declare one kind, one mutation, one rule.** Not the whole domain. The
+   loop you want on day one is: declare → `graview check` → look → declare
+   more.
+
+3. **Open it empty before you believe in it.** `graview describe
+   ./dist/domain/app.js` reads out what a blank installation meets; `<Begin>`
+   is that as a surface, wired into the scaffolded home. See `graview-seed`.
+
+4. **Declare the seams that make the interface smart.** These are one-line
+   declarations on mutations and kinds, and every derived surface reads them:
+   - `creates: ["<kind>"]` on every mutation that adds a kind — the chain
+     `Begin` and `graview describe` read, and the empty card's own way in.
+   - `connects: [...]` / `severs: [...]` naming the edge kinds a mutation
+     makes or breaks — what makes drawn LINES selectable, offers the act from
+     either end, and hides a severing act with nothing to sever.
+   - `lifecycle: { field, retired }` on kinds whose members expire — counts
+     say "+N past".
+   - `subject: { kinds, arg }` on every mutation that acts on a thing.
+
+5. **Take the shell.** `Inspector`, `Standing`, `ActivityRail`, `ChatPanel`,
+   `QuickRelations`, `RelationKey`, `BackOut`, `Trail`, `OverviewButton` and
+   `Wordmark` from `@graview/primitives` are the parts of an interface that
+   are not about your domain — including a chat seat that answers from the
+   graph with no API key. A shell is about eighty lines; if yours is longer,
+   you are probably rebuilding something derived.
+
+   Search comes with `Shell`: its `FindBox` answers `/` or ⌘K from
+   anywhere, lights what the words find in whatever picture is open and
+   dims the rest, and `#q=` makes a search a stop Back returns to. A shell
+   of your own puts `<FindBox />` in its bar; nothing is declared per kind.
+
+   The routed face is one branch in `main.tsx`: when the path starts with
+   `/pages`, render `<PagesApp basename="/pages" context={{ store, brand,
+   views: views(), settings }} />` from `@graview/pages`. It lands on a
+   gallery of the app's pictures — every kind drawn as a card until you title
+   a lens, then the lens by its name — with a list, a record and a form per
+   kind, the problems and the map, at phone widths. Hand it the same `views`
+   the scene draws from, or it has no pictures to land on.
+
+6. **Register default views first, override later.** `registerDefaultViews`
+   means a new kind renders sensibly at all three fidelities before you write
+   anything. Write a custom view for a kind when the generic one is genuinely
+   wrong, not on principle.
+
+7. **Add the check to your build.** `"check": "graview check
+   ./dist/domain/app.js"`, and a `verify` that runs typecheck, test, build
+   and check in that order. The scaffold writes both.
+
+## What to make yours next
+
+The scaffold is deliberately the framework's own face. A product replaces it
+in this order, and each step has a skill and a worked chapter in
+`apps/seedbed` behind it:
+
+1. **The words.** Every edge gets `description` and `inverse` — how it reads
+   from each end — or `graview check` says `edge-without-inverse` and the
+   far end is captioned with the edge kind's name. Every mutation gets a
+   `title` and `description`; they are the button and the tool schema.
+   (`graview-node-kind`.)
+2. **A lens with a name.** A lens registered over a group with a `title` is
+   a PLACE — in the bar, on an embed's strip, one press from anywhere. Start
+   from the three that ship; write your own when the domain has a picture of
+   itself, the way the garden has a map. (`graview-lens`, chapters 10-13.)
+3. **The pages.** One page in the product's words first, then, when the
+   product needs to look like a product, every surface: the shell, the home,
+   the lists, the records, the problems — over the same store, acts, rules
+   and permissions. (`graview-pages`, chapters 9 and 13.)
+4. **A seat and a policy.** Who may do what, declared once; the strip, the
+   pages and the agent's tools all narrow from it. (`graview-permissions`,
+   `graview-agent-seat`, chapters 5 and 7.)
+5. **A brand, and shipping.** The name, the mark, the typefaces, the palette
+   the checker holds to AA; a version and a migration so a stored graph is
+   carried forward. (`graview-brand`, `graview-ship`, chapters 8 and 12.)
+
+Work with an agent beside the declaration: describe a kind, let it draft the
+edges, acts and rule, run `pnpm verify`, look, declare more.
+
+## The CI a product on Graview needs
+
+Copy the shape from the framework's own `.github/workflows/ci.yml`, minus the
+packaging steps you do not need. What earns its place:
+
+- **`tsc`** — an edge to an undeclared kind is a typecheck failure, so this
+  catches a whole class before anything runs.
+- **`graview check`** — everything `tsc` cannot see: a repair naming a mutation
+  nobody registered, a lens role bound to a missing field, a role that may do
+  nothing, a palette pair below AA. **Fail the build on errors.** Warnings are
+  a judgement call; errors are not.
+- **Headless tests** — the domain tier has no DOM in it. Test that your rules
+  fire on graphs that break them and that their repairs resolve them; that is
+  the test that catches a real regression.
+- **An accessibility run, in BOTH schemes.** Copy
+  `apps/todo/scripts/run-a11y.mjs`: the real accessibility tree through CDP,
+  plus axe-core. A light palette that clears AA in the dark is what it catches.
+
+Worth stealing later: a browser harness that walks your own acceptance
+criteria and writes a JSON verdict (the framework has several; each names
+the claim that stopped being true), and a persistence adapter test.
+
+## Supported browsers
+
+Build for the DOM path: Chromium, WebKit and Firefox, all three verified by
+the framework (`pnpm engines`). The floor is `document.adoptedStyleSheets`
+(Safari 16.4+, Firefox 101+, Chromium 99+). The altitude morph rides
+`@property` and degrades to a clean cut where that is missing — write no
+fallback. The chat's local-model rung needs WebGPU or Chrome's Prompt API;
+without either the graph still answers and the header says why. The GPU
+capture path is Chromium-only, experimental and opt-in (`attachRenderer`
+from `@graview/render/gpu`; there is no URL switch) — never a requirement.
+
+## Then find out whether it worked
+
+```sh
+pnpm verify        # typecheck, tests, build, graview check
+```
+
+Report the real output. On a new app the useful early findings are
+`mutation-untitled`, `mutation-undescribed`, `edge-without-inverse` and
+`required-invariant-unregistered` — things that look fine until somebody
+reads the interface or an agent reads a tool schema.
+
+## What the check cannot see
+
+- Whether your kinds are the right kinds. The test for each: does anything
+  point AT it, and does it have a life of its own? A colour is a field. A
+  fixture is a kind.
+- Whether your mutations are the acts a person would name. They are the labels
+  in the strip and the instructions in an agent's tool schema, so an opaque one
+  costs twice.
+- Whether the interface is any good. Run it. Run it at the size it will have: seed a
+  real catalogue, not a dozen rows. The scene draws what a person can read — a
+  relation too long for its band is grouped by its best arrangement or closes
+  on "+N more", and a thumbnail draws its 12 most relevant members — so a
+  thousand records are a picture, not a smear. What that hides is yours to
+  judge: whether the groups are the ones a person would ask for.

package/skills/graview-node-kind/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: graview-node-kind
+description: Add a node kind to a Graview app — fields, edges, label, plural and field roles — and verify it with graview check rather than claiming it worked.
+---
+
+# Add a node kind
+
+A kind is the unit of everything here. Declaring one gets you, without another
+line: a place in the layout, a card at three fidelities, an aggregate view, an
+accessibility label, a hue, a slot in the kinds plane, and inclusion in every
+agent tool that walks the graph.
+
+## Do this
+
+1. **Find the schema.** It is the file calling `createSchema`. Usually
+   `src/domain/schema.ts`.
+
+2. **Declare the kind.** Zod is the single source of runtime validation,
+   TypeScript types and JSON Schema — there is no second place to describe a
+   field.
+
+   ```ts
+   export const fixture = defineNode("fixture", {
+     fields: z.object({
+       // A NAME, and bounded. Every derived surface draws `label` — on a
+       // card, in a list, on a plan — and `z.string().min(1)` permits a
+       // paragraph. That is fine while a person is typing it; a model asked
+       // to survey a garden wrote "Pea-gravel corner with river-rock
+       // border, log seats and a fire bowl", which is a true sentence and a
+       // terrible name, and it was never told otherwise because the prompt
+       // is generated from this file. `graview check` notes
+       // `label-unbounded` on any kind a declared provider may create.
+       label: z.string().min(1).max(60),
+       kickOff: z.string(),
+       opponent: z.string(),
+     }),
+     plural: "Fixtures",
+     description: "A match, and the team you intend to put out for it.",
+     edges: {
+       // One edge, two readings: the fixture's page says who is in the
+       // team; the player's page says which fixtures they are picked for.
+       "picked-for": {
+         to: ["player"],
+         description: "who is in the team",
+         inverse: "the fixtures they are picked for",
+       },
+     },
+     // Lets a lens ask for "the start time" without knowing your field names.
+     fieldRoles: { start: "kickOff" },
+   });
+   ```
+
+3. **Add it to `createSchema([...])`.** An edge pointing at a kind that is not
+   in that array is a *typecheck* failure, not a runtime one — `createSchema`'s
+   `ValidateEdgeTargets` sees it.
+
+4. **Say what a node of it is called.** `label` defaults to a `label` field and
+   then to the id. An id in the interface is a bug you shipped, not a
+   placeholder. And say what ONE of the kind is called where its id does not:
+   `noun: "staff member"` on a kind called `staff`, or every sentence about
+   one reads "Change the staff".
+
+   An id is still a name a caller may choose: every act that declares
+   `creates: ["fixture"]` takes an optional `id` argument the framework adds,
+   so a seed being synced or an agent that will refer to the node next call
+   gets exactly the id it asked for, or a refusal by name. Never hardcode a
+   bootstrap id — `"today"`, `"u-nick"` — inside a mutation body or an
+   invariant; bind a role, a flag or an edge instead, so a store seeded
+   differently still works. And every kind gets `remove-<kind>` derived,
+   permitted through the acts that create it.
+
+5. **Give it verbs.** A kind with no mutation naming it as a subject renders
+   fine and can have nothing done to it, and the actions strip will say so out
+   loud. If that is not what you meant, see `graview-invariant` for the rule
+   shape and add at least one mutation whose `subject.kinds` includes it.
+
+6. **Let the fields be changed, or say why not.** A field you could set at
+   creation, you can change: every settable field no mutation writes is
+   covered by a derived act per kind (`edit-<kind>`, "Change the drill"),
+   editable where it is shown and logged like any other. Two declarations
+   shape it. `writes: ["done"]` on a mutation says which fields it sets when
+   its arguments do not (`finish()` writing `done`) — and a mutation whose
+   argument merely shares a field's name should say `writes: []`. `fixed:
+   { text: "the client's words, as sent" }` on the kind says a field never
+   changes, and why; the sentence is the documentation. The checker warns
+   `field-without-writer` when a field is still out of everyone's reach,
+   and refuses `writes-unknown-field`, `fixed-unknown-field` and a
+   `fixed-but-written` contradiction.
+
+## Worked examples
+
+- `apps/todo/src/domain/schema.ts` — four kinds, including a `rule` kind whose
+  `spec` makes the rules a domain enforces into data, and `fieldRoles` binding
+  the timeline lens to a task's own field names
+- `apps/seedbed/src/domain/schema.ts` — a kind with a declared `lifecycle`, so
+  the past is a horizon rather than a delete
+
+## The declarations that keep paying
+
+- **`creates`** on the mutation that adds this kind (`creates: ["fixture"]`):
+  the empty kind card then offers "Add a fixture" by derivation — the blank
+  graph onboards itself, FROM THE ROOT OF THE CHAIN. An act that also takes
+  a `nodeRef` has no candidates on an empty graph, so it is withheld (a
+  picker with nothing in it is worse than no button) and the district says
+  what it is waiting for instead: *"Place a feature" cannot begin until there
+  is a zone.* Expect exactly one way in on a blank installation, and check
+  that it is the one you meant — this only ever shows up on the graph nobody
+  tests against.
+- **`fromTheOtherEnd`** on the act that makes or breaks the edge. An act
+  declaring `connects` or `severs` is offered from BOTH ends of the tie, and
+  `title` is written from the subject's side: "Name a caretaker", offered on
+  the gardener, reads as naming hers. Say how it reads standing there
+  (`fromTheOtherEnd: "Take on a plot"`) — `graview check` warns
+  `act-without-far-end-reading` and names the end it has no words for.
+- **`lifecycle`** when members expire — `{ field: "status", retired:
+  ["played"] }` or `{ field: "until", retired: "date" }`. Every count then
+  aggregates over the horizon ("4, +12 past") instead of drowning, and
+  `graview check` refuses a lifecycle reading a missing field.
+- **A figure**, which is line art of the THING at the city's own three-quarter
+  angle — a person, a plot of ground, a gutter — drawn wherever the kind is
+  drawn. Nine ship; any domain that is not an abstract tracker runs out of
+  them at once, so draw the rest:
+  `graview figure ./dist/domain/app.js --kind gutter --from "a gutter along a
+  roof edge"` prints the brief (the rules, the angle, a shipped figure as the
+  style), and `--judge <file>` reads the answer back, holds it to the rules
+  `graview check` holds a figure to, and prints the line to paste. Then look
+  at it at twenty pixels, which is the size a chip gives it.
+- **A declared hue** in the brand (`accents: { fixture: 210 }`) if this kind
+  should wear a chosen colour rather than a stable hash — every chip dot,
+  district roof and the focus tag follow.
+
+## Then find out whether it worked
+
+```sh
+pnpm build && npx graview check ./dist/domain/app.js
+```
+
+Report **the actual output**, including warnings. What it catches here:
+
+- `edge-target-undeclared` — an edge to a kind nobody declared
+- `edge-without-inverse` — a relation with words for one of its two readings
+- `edge-name-shared` — one edge name declared on two kinds in two sets of
+  words (`by` on a song and on an album); every surface treats a name as ONE
+  relation, so name each its own
+- `act-without-far-end-reading` — an act offered on an end it has no words for
+- `field-role-missing-field` — a role pointing at a field that is not there
+- `required-invariant-unregistered` — `requiresInvariant` naming no rule
+- `mutation-untitled` / `mutation-undescribed` — a verb nobody can read
+
+## What the check cannot see
+
+Say so rather than implying otherwise:
+
+- Whether the kind is a *kind* at all, or should have been a field on an
+  existing one. The test: does anything point AT it, and does it have a life of
+  its own? A colour is a field. A fixture is a kind.
+- Whether the default views read well. Run the app and look.
+- Whether the plural reads naturally in a sentence — "3 Fixtures" is fine,
+  "3 Person" is not.

package/skills/graview-pages/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: graview-pages
+description: Give a Graview app the routed face it wants — from the derived pages, to one page in the app's own words, to a product design that replaces every surface.
+---
+
+# The pages face
+
+A Graview app has two faces over one store. The scene is the picture. The
+pages face is the same declaration routed as an ordinary web application:
+a home, a list per kind, a record per node, forms for every act, and a
+problems page — derived, then replaceable one surface at a time, all the way
+to a product design of its own. The ladder ends where the framework's own
+example does: `apps/seedbed`, chapters nine and thirteen.
+
+## What comes for free
+
+```tsx
+// main.tsx — one branch: the path decides the face
+if (location.pathname.startsWith("/pages")) {
+  root.render(<PagesApp basename="/pages" context={{ store, brand, principal, sceneHref: "/" }} />);
+}
+```
+
+`PagesApp` renders with no registry at all:
+
+- `/` — a GALLERY. The standing as the headline ("2 gardeners, 3 plots and
+  1 planting.", or "Nothing here yet." and which act begins it), then every
+  picture as a large live card, two across at a desk, one on a phone, then
+  the kinds as a row of counts, a line to the map, and Recently. A kind
+  with no titled lens gets a contact sheet of its members, so a new app
+  lands on a gallery; titling a lens replaces that card with the
+  lens by its name. An empty picture names the act that fills it.
+- `/<plural>` — a list per kind, marking trouble, with the creating acts
+  beneath it.
+- `/<plural>/<id>` — a record: its facts, its relations captioned in the
+  declaration's words, what can be done, what has happened.
+- `/problems` — every broken rule with its repairs.
+
+The shell is one row — pictures (home), kinds, Map, Problems — scrolling
+sideways on a phone. Shell and gallery are 1160px wide; read pages, 760.
+
+**Hand it `views`** (the scene's registry, plus `settings`/`presence`) —
+`graview create` does — and the face puts the scene's provider
+under its routes, which buys three things at once:
+
+- `/places`, `/places/<as>` — every named lens as a page (fullscreen, over
+  the kind's members, siblings one press away, the beginning acts beneath)
+  and the gallery again. A kind's page lists its pictures; a pick in a lens
+  travels to the record.
+- `/map` — `kindMap(store)`: every declared relation in its words with
+  its live count, also a section on the home page. A kind's list says what
+  it relates to and arranges itself in the shared words (`?sort=due:desc`,
+  `?filter=done:false`, `?group=due:month`, `?q=tape`) a lens carries in
+  its fragment, so an arrangement is a link; `?by=`, `?<edge>=<id>`,
+  `?with=` and `?past=1` still land. A record links back.
+- `/search?q=` — the Find box's matcher: hits by kind, each with why; a
+  nav box narrows a list, else lands here. Find and the way back ("Take
+  back “…”", ⌘Z) are on every face: a shell that places `<PageFind>` or
+  `<PageUndo>` says where, one that does not gets them drawn around it,
+  and `surface("shell", Shell, { without: ["find"] })` goes without.
+- **The assistant**, on every route: one control opens the scene's own
+  `Companion` in a drawer, and the ROUTE is what "this" means. Grounded
+  questions before anybody types; proposals apply through the same runtime,
+  attributed and undoable, withheld ones struck through. Open questions are
+  listed on `/problems`; the rung that answers is chosen in the footer.
+
+Everything a page shows is a derivation the scene also uses: `recordFacts`,
+`deriveAffordances`, `store.permits`. **A page never decides what an act is
+or who may take it** — it strikes through what the seat may not, and says why.
+
+**At a phone's width this face is the answer.** The scene still holds there —
+districts stay legible, panels scroll — but
+a 134px card in a 390px viewport is a city through a letterbox. `Shell`
+carries `pagesHref`.
+
+## Rung one: a page in the app's own words
+
+`createPageRegistry(schema)` replaces pages per kind and surfaces per app:
+
+```tsx
+import { createPageRegistry, DerivedForm, kindFacts, PageMain, pageStyles, recordFacts, spatialHref, useStoreTick } from "@graview/pages";
+
+function PlotPage({ context }: { context: PageContext<S> }) {
+  const { store, principal } = context;
+  useStoreTick(store);                                   // re-render on every op
+  const id = decodeURIComponent(useParams()["id"] ?? "");
+  const facts = recordFacts(store, id, { principal });   // the same derivations
+  return (
+    <PageMain context={context}>
+      <h1 style={pageStyles.h1}>{facts.label}</h1>
+      <a href={spatialHref(id)}>See it in the scene ↗</a>
+      <DerivedForm store={store} mutation={sow} prefilled={{ plotId: id }} />
+    </PageMain>
+  );
+}
+
+export const pages = createPageRegistry<S, PageComponent<S>>(schema)
+  .register("plot", "record", PlotPage)
+  .route("/survey", SurveyDesk);   // about nothing in the schema
+```
+
+`.route(path, Component)` gives a page that is NOT about a kind an address —
+onboarding, settings, import — matched before `/:plural`. **Every `to` is
+basename-relative** (`to="/survey"`, never `to="/pages/survey"`), and so is
+`initialPath`, so a test renders the hrefs a browser will.
+
+Rules for a page at this rung:
+
+1. **`PageMain`, not `<main>`** — inside an embed the host owns the one
+   `main`, and a hand-written one is a duplicate landmark.
+2. **`useStoreTick(store)`** at the top of every page that reads the graph,
+   or it goes stale after the first act.
+3. **`pageStyles`** for the parts you did not design, so one custom page
+   still reads as the same face as the derived ones.
+4. **Prefill, never wire.** `DerivedForm` with `prefilled` is how a record
+   offers an act about itself; the form asks for the rest.
+5. **Read permission before drawing an act.** `store.permits({ name, args },
+   principal)`, struck through with `verdict.refusal.message`. A form that
+   refuses on submit is the bug this prevents.
+6. **Link to a PICTURE, not only to a node.** `spatialHref(id)` opens the
+   scene on one thing; `placeHref(as)` — `/#view=the-grounds`, the title
+   through `placeSlug` — opens it on one named place, group in focus, not on
+   a default view that says "press The grounds".
+7. **Take the act LIST from the derivation, not from the mutations.**
+   `recordFacts(store, id, { principal }).actions` is the same `AffordanceSet`
+   the scene's strip reads: `affordances` are the acts that can actually act
+   here, each with its `args` already decided and its `open` questions left,
+   and `withheld` are the ones this seat may not take, with the reason.
+   Filtering `store.allMutations()` is not equivalent: it offers acts with
+   nothing to act on. A **list** page asks it of a kind instead —
+   `kindFacts(store, kind, { principal }).actions`, the acts that can BEGIN it.
+
+## Rung two: a product design
+
+The registry has three surfaces and two page types, and replacing all of them
+is a product:
+
+```tsx
+createPageRegistry<S, PageComponent<S>>(schema)
+  .surface("shell", Shell)        // the frame around every route: nav, masthead, standing
+  .surface("home", Home)
+  .surface("problems", Problems)
+  .register("plot", "list", Plots).register("plot", "record", PlotRecord)
+  .register("gardener", "list", Gardeners).register("gardener", "record", GardenerRecord)
+  // ... every kind
+```
+
+The shell surface receives `{ context, children }`. Two worked examples. `apps/todo/src/ui/design.tsx` is the FINISHED one, and
+what makes it finished is not the type — it is that everything a person
+tries there works: sort, filter and group come from `ArrangeBar` and live
+in `useSearchParams` in the shared words (a list you arranged is a link); a record edits where it is
+shown, heading included, through `editableFields(store, id)`; an act's form
+opens where the act is, prefilled, with the store's own refusal said at the
+press; the problems page is an inbox, its repairs ordered by
+`rankedRepairs`; and every empty state offers the way out of itself.
+`apps/seedbed/src/ui/design.tsx` is the other end — an almanac whose own
+drawing has two homes, the page and the scene's lens reading one model.
+
+What every design must keep doing:
+
+- **Read the graph through one model.** `readGarden(store)` turns nodes,
+  edges and violations into the design's words; every page reads it and none
+  reaches for `store.graph`. The scene's lens reads the same model.
+- **Style through the theme's tokens** (`--graview-ground`, `-panel`, `-ink`,
+  `-edge`, `-warn`, `-accent`, `-font-display`, `-font-body`), tinted with
+  `color-mix` for the design's own paper. Never a colour that works in one
+  scheme only.
+- **Keep landmarks and targets honest.** One `main` — a `section` when
+  `context.embedded`, and UNNAMED, or a page holding two embeds has two
+  regions with one name. Controls at least 24px, AA contrast.
+  Every size in `rem`: at 200% text a flex or grid item's automatic minimum
+  is its CONTENT's, so one un-wrappable row pushes the whole column off the
+  screen — `minmax(0, 1fr)` and `min-width: 0` on the column, `flex-wrap` on
+  the row. Measure rather than trust: `-ink-faint` fails AA on an 11px
+  label, and the accent fails on the warning ground. `node
+  scripts/verify-pages.mjs` runs axe over every route, both widths, both
+  schemes.
+- **Withhold, do not hide.** Rule 7 again, at every surface: struck through
+  with the policy's own sentence rather than dropped.
+
+## On somebody else's page
+
+The embed mounts the app — this face included (`face: "pages"`, `path`) —
+into one element of any page. That is its own skill: `graview-embed`.
+
+## Then find out whether it worked
+
+```sh
+pnpm build && npx graview check ./dist/domain/app.js   # the declaration is still whole
+pnpm test                                               # render every page you registered
+```
+
+Render each registered page with `PagesApp` and `initialPath` in a test —
+`apps/seedbed/tests/integration/chapters.test.ts` does. Then open it: a
+design that passes its tests and reads like an admin panel has replaced
+nothing.
+
+## What the check cannot see
+
+- Whether the design's words are the domain's. The derived pages use the
+  declaration's `description` and `inverse`; a design that writes its own
+  sentences must keep them true as the declaration changes.
+- Whether a page still offers everything the seat may do. Listing acts by
+  NAME misses the one declared after it was written; scanning the mutations
+  offers acts that cannot act. `facts.actions` is neither — but only a
+  person can see whether the page gives them room.