# graview-node-kind

`graview-node-kind` is one of Graview's 31 authoring skills: instructions an AI coding assistant such as Claude Code or Codex reads before it changes a Graview app. What it teaches: 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.

Installed into a project by `graview skills install .`, and read by whichever assistant is working beside you.

## The skill

## 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, and inclusion in every agent tool that walks the graph.

How its card, row and page read as data, and the values worked out from others that they show, is `graview-view-specs`.

### Do this

1. **Find the schema.** It is the file calling `createSchema`. Usually `src/domain/schema.ts`.

1. **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 surface draws `label`, and `min(1)` // alone permits a paragraph — a model surveying a garden named a // corner with a whole sentence, because the prompt is generated // from this file (`graview check`: `label-unbounded`). label: z.string().min(1).max(60), kickOff: z.string(), opponent: z.string(), // Host-kept file ("image"/"video"/"file"); appLinkField() another app // (its records: graview-linked-records); phoneField(), placeField(), // timeField() (a time of day, "15:00", no day and no zone). crest: imageField().optional(), }), 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. // Kinds sharing an edge name word their own end. "picked-for": { to: ["player"], description: "who is in the team", inverse: "the fixtures they are picked for", }, }, // Its time (`who`: its author): lists, glances, timelines read it. fieldRoles: { when: "kickOff" }, }); ```

**In a document** (`app.json`, `"format": "graview-document"`) it is `kinds.fixture`: `{ "label": "{name}", "fields": { "name": { "type": "string", "required": true } }, "edges": { "pickedFor": { "to": ["player"] } } }`. Kinds are kebab-case (`tool-note`), fields and relations camelCase (`pickedFor`). A choice that takes several of its options at once is `{ "type": "enum", "multiple": true, "options": [...] }` (`z.array(z.enum([...]))`): checkboxes in forms, filtered by one option. **The type is the control.** A record draws and changes each field by its type: a boolean is a switch, a date says its weekday and how far off it is, an enum of up to four short options is those options side by side (more, a menu), and a relation is a row of chips — one held alone (`cardinality: "one"`, or set by an act that also severs it) a chip with its own picker. A `"yes"`/`"no"` string is a text box. A blank the seat's act writes says how to fill it ("Pick a day"); one nothing writes stays unsaid. Every key, lens and block is in `node_modules/@graview/core/dist/document.schema.json` (its `$schema`).

1. **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.

1. **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"` — in a mutation body or an invariant; bind a role, a flag or an edge, so a store seeded differently still works. And every kind gets `remove-<kind>` derived, permitted through the acts that create it; every relation `connect-<kind>-<relation>` and `disconnect-` unless your acts do.

1. **Give it verbs.** A kind no mutation names as a subject can have nothing done to it, and the strip says so. Unless you meant that, add a mutation whose `subject.kinds` includes it (the rule shape: `graview-invariant`).

1. **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: []` (a document's act is read, not guessed); the edit refuses an argument it does not take. A number's bounds (`.int().min(1).max(5)`; a document's `min`, `max`, `step`) bound every form, tool and apply. `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` (a `rule` kind whose `spec` makes rules data; `fieldRoles` for the timeline); `apps/seedbed/src/domain/schema.ts` (a `lifecycle`: the past is a horizon, not 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.
- **`display.page`** when a record should not read in declared order: `page: { fields: ["subject", "draft"], groups: [{ title: "Schedule", fields: ["due"] }] }` puts those first, the rest under "Details" (a document's `kinds.<kind>.page`; `{ op: "set-page-fields" }`). A string allowed past 500 characters (`.max(5000)`, a `text`) is prose: full width, paragraphs and lists kept, edited in a text area.
- **`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**, line art of the THING at the city's 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 }`) for a chosen color, not a stable hash: every chip dot, roof and focus tag follows.
- **What it follows**, when its records copy another kind's (an event of its plan item): `"derives": { "from": "plan-item", "via": "source", "set": { "title": { "expr": "name" } } }`. The store keeps each linked record in step in the same change as either side's edit: a field set from a source field as it is goes back, one worked out otherwise is flagged in `store.findings()`, and archiving the source archives it.
- **`cites`** on a value somebody looked up (a population, a quote): the field or relation of the kind that holds its citation, `"population": { "type": "integer", "cites": "source" }` (in code, `markCites(z.number(), "source")`). The check refuses one naming nothing (`field-cites`), and warns of each record in `--seed` or a template's seed with the value and no citation (`field-uncited`); `dream` reports them as `uncited` and says them; a declared view flags one with `uncited('population')`, a worker view with `graview.cite`.

### Then find out whether it worked

```sh
pnpm build && npx graview check ./dist/domain/app.js
npx graview check --document app.json   # a document
```

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
- `act-without-far-end-reading` — an act offered on an end it has no words for
- `field-role-missing-field`, `field-role-ill-typed` — a role naming no field; a `when` no date, a `who` no name
- `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 color is a field. A fixture is a kind.
- Whether the default views read well, and the plural in a sentence ("3 Fixtures", never "3 Person"). Run the app and look.

---

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.

The page: https://graview.dev/docs/skills/graview-node-kind.html · Every Graview docs page, for a model: https://graview.dev/llms.txt
