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

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.