graview-studio

graview-studio 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: Open an app's declaration as a graph in Graview's own interface, change it with ordinary acts, let graview check judge the result before it is applied, migrate a stored graph, and write the declaration back as the files graview create writes.

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

The skill

Work the declaration in the studio

The declaration — kinds, fields, edges, acts, rules, roles, grants, lenses, brand — is itself a graph. @graview/studio declares that graph with the same defineNode an app uses, so a change to the declaration is an act with an author, an intent and an inverse, judged by the same checker, undone like any other.

Do this

  1. Open the studio over the app, in a test, a script or a page:

``ts import { createStudio, createStudioLens } from "@graview/studio"; const studio = createStudio(app); // the declaration, as a store ``

The store's nodes have stable ids: declared:plot (not kind:plot, which is the layout's name for the district), field:plot.label, edge:plot.tended-by, act:tend, rule:every-plot-tended, role:coordinator, grant:2, lens:coverage, brand.

  1. Change it with acts, not by hand:

``ts studio.store.apply({ name: "add-field", args: { kind: "declared:plot", label: "soil", type: "enum", required: true, options: ["clay", "loam"] } }, { author: june, intent: "Plots have soil" }); studio.store.apply({ name: "add-act", args: { kind: "declared:plot", label: "resize", title: "Resize", writes: ["size"] } }); studio.store.apply({ name: "add-rule", args: { kind: "declared:plot", label: "sized", description: "A plot has a size." } }); studio.store.apply({ name: "name-repair", args: { rule: "rule:sized", act: "act:resize" } }); ``

The acts: add-kind, rename-kind, remove-kind, add-field, rename-field, remove-field, retype-field, set-required, set-options, describe-field (a field changed in place: { id: "field:vendor.notes", type: "string" }), add-edge, and to another app's kind { name: "add-edge-to-another-app", args: { kind, label, to: "@nick/house/house" } }, remove-edge, add-act, remove-act, add-rule, remove-rule, name-repair, forget-repair, add-role, grant, revoke-grant, and the derived edit-<kind> for what no act names (an inverse, a title, a lifecycle).

  1. Check before you apply. studio.check() is graview check on the declaration as it now stands. studio.apply() refuses while there are errors and says which; otherwise it hands back { app, migration } — the migration is null when a stored graph needs nothing, else a { from, to, title, apply } to append to the app's migrations (the new app already carries it and the bumped version).

Opened on a document (createStudio(compileDocument(d).app), with compileDocument from @graview/core/check), the studio hands back a document, not TypeScript. studio.edits() is the change as editDocument's own ops (add-field, rename-field, set-required, set-options, add-relation, remove-act, add-rule, and a grant, a sight or the people kind as add-grant, remove-grant, add-sight, remove-sight and set-people …); studio.document() is the opened document with them applied, every act, label, brand and money field untouched. check(), would() and apply() judge by compiling that document, and apply() hands back document with app compiled from it. A copied app, or one with its policy swapped, says it: createStudio(app, { document }); without one, whyNoDocument() says why. A change no op says yet — a relation's cardinality, a lifecycle, a role, retyping a money field — comes back as documentFindings, one sentence each, and no document. Ask ahead what it keeps but will not change: uneditable(document) is one note per format, unit or list item type (kinds.vendor.fields.quote).

Without the studio, editDocument covers the rest of a document too: add-lens (replace retitles; at puts one back), remove-lens, { op: "set-lens-hidden" } (hidden: true keeps a lens off the bar and the page list, still reached by its address, a link or navigate), set-home, arrange-pages (order, hide, first, scene and pages — the switch's words; null clears), set-computed (expr: null removes it and what reads it), set-format (a number's format — money, percent, duration — and unit, or a text field's markdown; null clears; said in words, "money in USD — 10000 reads $10,000"), and set-view for a kind's slot, slot: "home", or lens: "<title>". Blocks are checked as they are set. A rename reaches lenses, the home, pages and computed expressions through the parser; removing a field or relation a lens draws by is refused, naming the lens. Computed fields are studio nodes, kept on hand-back and written-back TypeScript.

  1. Write it back. studio.files({ schemaVar: "gardenSchema" }) is src/domain/schema.ts, mutations.ts, invariants.ts and, with roles, policy.ts — the files graview create writes. Shape is what a graph carries: an act the studio declared gets a body from what it says (create, connect, sever, write); an act the checkout wrote keeps the checkout's body under the studio's declaration; a rule the studio declared judges nothing until the checkout gives it an evaluate. Read the files before you commit them, and keep a hand-written body where the comment says so.
  1. Let an agent propose. studio.propose(call, agentPrincipal, intent) applies under the agent's seat in a batch of its own; studio.proposals() lists what stands; studio.decline(batchId) undoes one; accepting is applying. In the interface, the trail shows the agent's turn with its undo, like any turn. The app's own conversation proposes the same way from words ("we also need who's driving"): @graview/tools/reshape reads them as traits to add and parts to drop, the person accepts a card, and the host's onProposeChange composes the edits (composeReshape, @graview/core/compose) and applies them — offered to whoever the studio's door is offered to (mayChangeDeclaration), and to nobody else.
  1. Put it on a page. The studio is an app: mount studioApp() with declarationToGraph(app) as the seed, and register createStudioLens(app).View over kind with a title — a place, "What the checker says", one press from anywhere.

Then find out whether it worked

Run graview check on the app the studio applied, and the checkout's own verify on the files it wrote. Say what they said.

What the check cannot see

  • Whether a body the studio wrote does what the person meant. It does what the act declares — create, connect, sever, write — and nothing more.
  • Whether a rule the studio declared is right. It judges nothing until the checkout gives it an evaluate; the checker sees a rule, not a judgment.
  • Whether a migration is safe for data it has not met. It is computed against the stored graph when it runs; look at the primitives on a copy.
  • Whether the files should replace the checkout's. Read them; a hand-written body is the checkout's to keep.