# graview-new-app

`graview-new-app` 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: 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.

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

## The skill

## Start a product on Graview

Graview ships as packages that share one version. 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, installs these skills into it, and makes the first commit ("My App, on Graview"; staged instead when git has no identity). `AGENTS.md` at the root says the loop, the rules and the skills, and `CLAUDE.md` imports it; `verify` rewrites `docs/agents.md` and `docs/llms.txt`, which are committed. 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

```text
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
```

`graview check` reads `defineApp`; a React import in `domain/` would drag a UI package into the checker.

**Or as one JSON document:** `app.json` (`"format": "graview-document"`, `$schema` `node_modules/@graview/core/dist/document.schema.json`, which types lenses and view blocks), then `graview check --document app.json`, `graview describe --document app.json`, `graview preview app.json --seed seed.json`. Kinds, acts and rules are kebab-case (`tool-note`), fields and relations camelCase (`supersededBy`). `preview --data` holds its folder: stop it to `sync-seed --apply`. In a framework checkout, `pnpm graview:link` puts `graview` on PATH.

### Do this

1. **Install.** The scaffold already did.

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

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

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

1. **Take the shell.** `Shell` from `@graview/primitives` is everything not about your domain: the one app bar an embed wears too (the name and its app menu, the scene's pictures, Find, the inbox, the standing, the person), the scene, its key, the quick ask (⌘K, where the host gives a model) and the acts at the pointer. Its parts (`AppBar`, `Inspector`, `Standing`, `Inbox`, `Trail`, `OverviewButton`) are exported for a shell of your own; one is about eighty lines, and a longer one is probably rebuilding something derived. `firstLook` on `Shell` and `PagesApp` (`true` or `{ seen, onDone, steps }`) points a newcomer at the app's own controls once; write no tour.

Search comes with `Shell`: Find 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. 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.

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

1. **Keep content in the graph.** What a page shows — a pitch's sections, a chart's tags — is records of a kind, seeded, never a JSON file a view imports: `graview check` names a face module that reads one (`face-reads-content-beside-the-graph`). A declaration change that loses nothing is made without asking; git keeps the way back.

1. **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. **Who it is for.** `purpose: { for, jobs }` on `defineApp` or the document: the questions its people bring, each a `kind`, a rule-language `where`, a `sort` and the next `act`. `graview check` holds each (`job-*`); describe and the seat read them (`@graview/core/jobs`).
2. **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`.)
3. **A lens with a name.** A lens registered over a group with a `title` is a PLACE — a tab on the app bar, 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.)
4. **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.)
5. **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.)
6. **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, 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 judgment 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.

### Supported browsers

Chromium, WebKit and Firefox, all verified (`pnpm engines`); the floor is `document.adoptedStyleSheets` (Safari 16.4+, Firefox 101+, Chromium 99+). The altitude morph rides `@property` and cuts cleanly where it is missing — write no fallback. `ai.onDevice` needs WebGPU or Chrome's Prompt API, else the seat says AI isn't available. The GPU is never a requirement.

### Then find out whether it worked

```sh
pnpm verify        # typecheck, tests, build, graview check
graview doctor     # one Graview release everywhere; React's pair; PATH from a checkout
```

Run the project's own `graview`, not `npx -y graview@<pin>`: inside a pnpm workspace holding the release, npx finds no bin.

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 color 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 at the size it will have: seed a real catalog, not a dozen rows. The scene groups a relation too long for its band or closes it on "+N more", so a thousand records are a picture; whether the groups are the ones a person would ask for is yours to judge.

---

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.

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