@graview/skills 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,96 @@
+Elastic License 2.0
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key
+functionality in the software, and you may not remove or obscure any
+functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not
+licensed, and your licenses will automatically terminate. If the licensor
+provides you with a notice of your violation, and you cease all violation of
+this license no later than 30 days after you receive that notice, your
+licenses will be reinstated retroactively. However, if you violate these
+terms after such reinstatement, any additional violation of these terms will
+cause your licenses to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control
+over, are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your
+licenses.
+
+**trademark** means trademarks, service marks, and similar rights.
+
+---
+
+Copyright 2025-2026 En Dash Consulting

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @graview/skills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Skills that teach an assistant how to build with Graview — and, more usefully,
+how to find out whether it worked.
+
+```sh
+npx graview skills install .    # into .claude/skills and .agents/skills
+npx graview skills list
+```
+
+The command line is the `graview` package; this one ships the skills and
+the move, and `graview skills` dispatches here.
+
+## Why this framework is worth having skills for
+
+Most skills end in a claim: "you have added a node kind." That is worth very
+little, because the assistant writing it is the same one that just decided it
+was done.
+
+Graview can answer the question itself. `graview check` reads the declaration
+and reports an edge to a kind nobody wrote, an invariant scoped to a kind that
+does not exist, a repair naming a mutation nobody registered, a lens role
+bound to a missing field, a mutation with no title, a palette pair that fails
+WCAG AA, a role that may do nothing. So every skill here **ends in a check and
+reports the real verdict** — including when the verdict is bad.
+
+A skill that cannot verify its own outcome says so. That is the rule, and the
+skills say which parts of their work the checker cannot see.
+
+## The skills
+
+| Skill | The move it teaches |
+|---|---|
+| `graview-node-kind` | Add a node kind: fields, edges, plural, roles, and what renders for free |
+| `graview-invariant` | Write a rule that names the mutations that would repair it |
+| `graview-lens` | Build a lens that binds roles rather than field names, so another domain can reuse it |
+| `graview-agent-seat` | Wire an agent seat that shares the interface's actions rather than shadowing them |
+| `graview-permissions` | Declare who may do what, once, and let the strip and the seat narrow themselves |
+| `graview-brand` | Put someone's name on an installation without forking a package |
+| `graview-new-app` | Start a product on Graview in its own repository, with the CI that keeps it honest |
+| `graview-pages` | The routed face: derived pages, one page in the app's words, a product design over every surface, and the embed |
+| `graview-port-app` | Port an existing application onto Graview, deciding what is a node and what is a field |
+| `graview-studio` | Open the declaration as a graph, change it with acts, check before applying, migrate, and write it back as the scaffold's files |
+
+The worked examples live in `apps/` in the framework repository. The skills
+point at them rather than restating them — a skill that copies an example goes
+stale the moment the example changes.

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `graview skills` — installs the skills where Claude Code and Codex look
+ * for them.
+ *
+ * Copies rather than symlinks: a symlink into `node_modules` breaks the moment
+ * somebody prunes or reinstalls, and a skill that silently stops existing is
+ * worse than one that is a little stale. `install` is idempotent and replaces
+ * what it wrote before.
+ *
+ * Reached through the `graview` command line, which dispatches here; this
+ * package ships the skills and the move, not a bin of its own.
+ */
+export declare const SKILLS_USAGE: string;
+export declare function skills(argv: readonly string[]): number;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,YAAY,QAGxB,CAAC;AAEF,wBAAgB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAiCtD"}

package/dist/cli.js

@@ -0,0 +1,54 @@
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { readSkills, SKILLS_DIR, SKILL_DESTINATIONS } from "./index.js";
+/**
+ * `graview skills` — installs the skills where Claude Code and Codex look
+ * for them.
+ *
+ * Copies rather than symlinks: a symlink into `node_modules` breaks the moment
+ * somebody prunes or reinstalls, and a skill that silently stops existing is
+ * worse than one that is a little stale. `install` is idempotent and replaces
+ * what it wrote before.
+ *
+ * Reached through the `graview` command line, which dispatches here; this
+ * package ships the skills and the move, not a bin of its own.
+ */
+export const SKILLS_USAGE = `  graview skills install [dir]   copy the skills into ${SKILL_DESTINATIONS.join(" and ")}
+  graview skills list            what is in this package
+  graview skills path            where the skill files live
+`;
+export function skills(argv) {
+    const [command = "help", target = process.cwd()] = argv;
+    const root = resolve(target);
+    if (command === "list") {
+        for (const skill of readSkills()) {
+            process.stdout.write(`${skill.name.padEnd(22)} ${skill.description}\n`);
+        }
+        return 0;
+    }
+    if (command === "path") {
+        process.stdout.write(`${SKILLS_DIR}\n`);
+        return 0;
+    }
+    if (command === "install") {
+        const all = readSkills();
+        for (const destination of SKILL_DESTINATIONS) {
+            const dir = join(root, destination);
+            mkdirSync(dir, { recursive: true });
+            for (const skill of all) {
+                const into = join(dir, skill.name);
+                // Replace rather than merge: a stale file left behind from an older
+                // version of a skill is a instruction nobody meant to give.
+                if (existsSync(into))
+                    rmSync(into, { recursive: true, force: true });
+                cpSync(join(SKILLS_DIR, skill.name), into, { recursive: true });
+            }
+            process.stdout.write(`${all.length} skills → ${relative(root, dir) || destination}\n`);
+        }
+        process.stdout.write("\nEvery one of them ends in `graview check` and reports what it actually said.\n");
+        return 0;
+    }
+    process.stdout.write(`graview skills — the authoring moves, each ending in a real check\n\n${SKILLS_USAGE}`);
+    return command === "help" ? 0 : 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,yDAAyD,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC;;;CAGpH,CAAC;AAEF,MAAM,UAAU,MAAM,CAAC,IAAuB;IAC5C,MAAM,CAAC,OAAO,GAAG,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IACxD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE7B,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,EAAE,CAAC;YACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,WAAW,IAAI,CAAC,CAAC;QAC1E,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,UAAU,IAAI,CAAC,CAAC;QACxC,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;QACzB,KAAK,MAAM,WAAW,IAAI,kBAAkB,EAAE,CAAC;YAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YACpC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACpC,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;gBACxB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;gBACnC,oEAAoE;gBACpE,4DAA4D;gBAC5D,IAAI,UAAU,CAAC,IAAI,CAAC;oBAAE,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACrE,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAClE,CAAC;YACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,MAAM,aAAa,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,WAAW,IAAI,CAAC,CAAC;QACzF,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kFAAkF,CAAC,CAAC;QACzG,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wEAAwE,YAAY,EAAE,CAAC,CAAC;IAC7G,OAAO,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Where the skill files live, relative to this module.
+ *
+ * `dist/` sits one level below the package root and `skills/` sits at it, so
+ * this resolves the same whether it is running from source or from an
+ * installed tarball — both of which ship `skills/`.
+ */
+export declare const SKILLS_DIR: string;
+export interface SkillFile {
+    readonly name: string;
+    readonly description: string;
+    readonly path: string;
+    readonly body: string;
+}
+/** Every skill this package ships, read from disk. */
+export declare function readSkills(dir?: string): readonly SkillFile[];
+/**
+ * Where each assistant looks for skills.
+ *
+ * Both, always. A skill installed for one and not the other is a skill that
+ * works until somebody opens the project in the other editor, and finding out
+ * that way is worse than not having it.
+ */
+export declare const SKILL_DESTINATIONS: readonly [".claude/skills", ".agents/skills"];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,QAItB,CAAC;AAEF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAgBD,sDAAsD;AACtD,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAmB,GAAG,SAAS,SAAS,EAAE,CAezE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,+CAAgD,CAAC"}

package/dist/index.js

@@ -0,0 +1,53 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Where the skill files live, relative to this module.
+ *
+ * `dist/` sits one level below the package root and `skills/` sits at it, so
+ * this resolves the same whether it is running from source or from an
+ * installed tarball — both of which ship `skills/`.
+ */
+export const SKILLS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "skills");
+/** Reads the frontmatter a skill is required to carry. */
+function frontmatter(text) {
+    if (!text.startsWith("---\n"))
+        return {};
+    const end = text.indexOf("\n---", 4);
+    if (end === -1)
+        return {};
+    const fields = {};
+    for (const line of text.slice(4, end).split("\n")) {
+        const colon = line.indexOf(":");
+        if (colon === -1)
+            continue;
+        fields[line.slice(0, colon).trim()] = line.slice(colon + 1).trim();
+    }
+    return fields;
+}
+/** Every skill this package ships, read from disk. */
+export function readSkills(dir = SKILLS_DIR) {
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => {
+        const path = join(dir, entry.name, "SKILL.md");
+        const body = readFileSync(path, "utf8");
+        const fields = frontmatter(body);
+        return {
+            name: fields["name"] ?? entry.name,
+            description: fields["description"] ?? "",
+            path,
+            body,
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Where each assistant looks for skills.
+ *
+ * Both, always. A skill installed for one and not the other is a skill that
+ * works until somebody opens the project in the other editor, and finding out
+ * that way is worse than not having it.
+ */
+export const SKILL_DESTINATIONS = [".claude/skills", ".agents/skills"];
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAC/B,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EACvC,IAAI,EACJ,QAAQ,CACT,CAAC;AASF,0DAA0D;AAC1D,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACrC,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1B,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAClD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,SAAS;QAC3B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACrE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,UAAU,CAAC,MAAc,UAAU;IACjD,OAAO,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;SAC7C,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;SACtC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACb,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAC/C,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QACjC,OAAO;YACL,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI;YAClC,WAAW,EAAE,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE;YACxC,IAAI;YACJ,IAAI;SACL,CAAC;IACJ,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAU,CAAC"}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@graview/skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Skills that teach an assistant the authoring moves, each ending in a real graview check verdict.",
+  "keywords": [
+    "graview",
+    "context-graph",
+    "typed-graph",
+    "interface",
+    "declarative",
+    "claude-code",
+    "agent-skills",
+    "ai-assistant"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/en-dash-consulting/graview.git",
+    "directory": "packages/skills"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Elastic-2.0",
+  "homepage": "https://graview.dev/docs/packages/skills.html",
+  "bugs": {
+    "url": "https://github.com/en-dash-consulting/graview/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
 }

package/skills/graview-agent-seat/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: graview-agent-seat
+description: Wire an agent seat into a Graview app that shares the interface's own actions rather than shadowing them, and verify the diffs are identical rather than assuming they are.
+---
+
+# Wire an agent seat
+
+There is no agent API to build. The tools generate from the same mutation
+declarations a person's buttons come from, which is why an agent's edit
+produces literally the same diff, lands in the same op log with an author, and
+is undone by the same control. If you find yourself writing a second code path
+for the agent, stop: that path is the one that will drift.
+
+## Do this
+
+1. **Create the runtime with a principal.**
+
+   ```ts
+   const runtime = createToolRuntime(store, {
+     author: { kind: "agent", id: "claude", session: "ui", roles: ["analyst"] },
+   });
+   ```
+
+   The author is a `Principal` — an author with roles — so what the log blames
+   and what the policy judged are one object. A seat's tools narrow to what
+   that principal may run, with no second list to keep in step. See
+   `graview-permissions`.
+
+2. **Pick a transport.** `createInAppAdapter(runtime)` for a seat inside the
+   interface; `createMcpAdapter(runtime)` for an external client. Both are thin
+   wrappers over the same runtime — that is the whole design.
+
+3. **Show the calls.** `runtime.onCall(listener)` announces every call as it
+   starts and as it settles. Feed it to `ActivityRail`. A diff says what
+   changed and never what was *considered*, so an agent turn without this is a
+   spinner and a toast.
+
+4. **Report what it READ.** `useAttention(runtime)` pipes a settled read-only
+   call's node ids into the picture, so a kind lights faintly where the agent
+   looked. That is the half a diff cannot show, and the half that says whether
+   to trust what it then did.
+
+5. **Find by name with `search_graph`, before `get_graph`.** It is the Find
+   box's matcher: hits with why they matched, `key:value` conditions
+   (`done:false`, `is:any` for the past, `kind:task`), and the records it
+   names counted as reads. Reading the whole graph to scan it is the move a
+   person with a search box never makes.
+
+6. **Prefer `get_affordances` over composing calls by hand.** The tool
+   descriptions say so, and it matters: derived affordances cannot name an
+   action that does not exist or is not legal on this selection.
+
+7. **Host the seat where the data is, for an agent outside the page.** An
+   editor's assistant or a scheduled worker does not need glue of its own:
+
+   ```sh
+   graview mcp ./dist/domain/app.js --data ./data --as cursor --roles keeper
+   graview mcp ./dist/domain/app.js --remote-url http://localhost:5196 --roles keeper
+   graview apply ./dist/domain/app.js --data ./data --roles keeper \
+     --call add-task --args '{"listId":"today","label":"Book the van","id":"t-van"}'
+   ```
+
+   `mcp` is MCP over stdio around this same runtime; `apply` is one act, a
+   plan of many as one batch, or an undo, from a shell. Both open the store
+   `graview serve` opens — a folder, SQLite, or a running server — and act
+   under the seat you name, so the policy refuses there what it refuses here.
+   Put `serve` and `mcp` in the app's scripts so the door is always there,
+   and tell the agent the seed is a first-install snapshot: it changes the
+   live graph through these, never by editing `example.json` and wiping.
+   `graview mcp <entry> --list --roles …` prints the seat's tools as
+   `tools/list` JSON — the catalog a host registers without writing one.
+
+## Worked examples
+
+- `apps/todo/src/ui/app.tsx` — the seat, the runtime, and an agent that finds
+  what it will change with `search_graph` before it moves
+- `packages/tools/src/agent/tools.ts` — how the tools generate, and what a
+  read-only call reports about what it looked at
+
+## Then find out whether it worked
+
+```sh
+pnpm build && npx graview check ./dist/domain/app.js
+```
+
+The checker verifies the mutations behind the tools: `mutation-untitled`,
+`mutation-undescribed`, `mutation-title-ambiguous`. A tool description that
+falls back to a title is a LABEL where an instruction belongs, and an agent
+reads that string to decide whether to reach for it.
+
+**And prove the paths are one path**, which is the claim this design exists to
+support:
+
+```ts
+it("produces the same diff whether a human or an agent acts", async () => {
+  const byHand = human.apply({ name: "reassign", args });
+  const byAgent = await seat.call("reassign", args);
+  // A refusal is a RESULT, so `ToolResult` is a union: establish there was a
+  // diff before claiming anything about it, or this does not compile.
+  if (!byAgent.ok) throw new Error(byAgent.error);
+  expect(byAgent.diff).toEqual(byHand.diff);
+});
+```
+
+**And prove the seat is bounded**, if it holds a restricted principal: call a
+mutation it was not given a tool for and check it is refused by the STORE
+rather than merely absent from the schema.
+
+## What the check cannot see
+
+- Whether the agent's turn is legible while it is happening. Open the app and
+  watch one; `pnpm watching` measures the marks but not whether they read.
+- Whether the tool descriptions are good instructions. They are prose an agent
+  reasons from, and "get the graph" is worse than "read the whole graph: start
+  here when you need the shape of the domain rather than one thing in it".
+- Whether the agent should be doing this at all.
+
+## The seat is one of four surfaces on one seam
+
+Everything intelligent travels the same contract — validated proposed calls
+to declared mutations — so adding AI is choosing a provider, never a second
+path to the store:
+
+- **Providers** whisper suggestions into the companion's acts
+  (`insightProvider` ships in the defaults; `intelligenceProvider(...)`
+  wraps any `Intelligence`).
+- **The seat** (this skill) runs one-press turns.
+- **The companion** — `<Companion />`, the scene's left rail — is the one
+  place the seat lives: it names its subject (the selection, else the pick
+  the pointer settled on, else where you are), lists that subject's acts,
+  its relations, the conversation and the key. Right-click opens the same
+  acts at the pointer, so the context menu and the assistant are one
+  construct. The seat has no figure in the picture; other people's agents
+  still have theirs. `useSubject()` gives the same answer to any surface.
+- **The conversation** — a section of that rail — answers questions in words.
+  Keyless it answers from the graph (`graphResponder`: standings, named
+  things, when/who, mutations phrased in their own titles); a model plugs in
+  through one completion function (`llmResponder`, `xaiCompletion`,
+  `localCompletion`), chosen by the person in the panel's gear. **Your own
+  responder goes in through the shell**: `<Shell chat={{ respond }} />`,
+  which hands it to the companion.
+  "Why do I still have mosquitoes?" is a walk through THIS graph, and the
+  generic answer to it is a plausible paragraph about gardens.
+- **External agents** arrive over the derived tool surface with a scoped
+  principal.
+- **A desk** — the model INSIDE the product, taking photographs or words and
+  proposing a plan somebody reviews. That is `graview-desk`; this skill is
+  the seat beside the product rather than the surface in it.
+
+Declare what runs where on the app: `intelligence: [{ name, kind:
+"graph" | "llm" | "external" | "decision", may: [...mutations] }]` —
+`graview check` refuses an allowlist naming a mutation nobody registered,
+refuses a `"decision"` provider (one that answers typed questions — a
+choice, a truth, a score — and never prose) any act whose required
+arguments want text, and the STORE
+enforces it: hand the store `intelligence` and an author
+`{ kind: "agent", id: "<provider name>" }` is refused anything outside its
+`may`, on `apply` as on a tool call. `openStore` and the embed pass it
+through for you.