opencode-gbuild 0.7.0 → 0.8.0

package/README.md

@@ -98,7 +98,7 @@ OpenCode (same order, kebab-case names):
 ```
 
 - **`plan`** creates the feature branch in its own git worktree and charts the feature into a
-  CypherLite graph store there (`.gbuild/<feature>/db/`) — `Feature`,
+  machine-local CypherLite graph store (`<git-common-dir>/gbuild/<feature>/db`) — `Feature`,
   `Acceptance`, and `GbuildNode` nodes, each node's contract as `INPUT`/`OUTPUT` `Field` nodes, and
   `FROM` edges carrying data from one node's output to the next node's input. Every dependency edge
   passes the cut test — and because data flow is explicit, the validator checks it; every node has
@@ -185,7 +185,7 @@ decision is wanted; neither guesses.
 
 ## Runtime
 
-gbuild **requires the [CypherLite](https://github.com/neo4j-labs/cypherlite) CLI**, 0.7.0 or newer:
+gbuild **requires the [CypherLite](https://github.com/neo4j-labs/cypherlite) CLI**, 0.12.0 or newer:
 
 ```bash
 curl -sSfL https://neo4j-labs.github.io/cypherlite/install.sh | bash
@@ -193,12 +193,12 @@ curl -sSfL https://neo4j-labs.github.io/cypherlite/install.sh | bash
 
 Every skill reads and writes the graph with `cypherlite` and nothing else — there is no Python and no
 direct JSON editing. The plugin ships the queries as `.cypher` files; skills pipe them into the store
-(`.gbuild/<feature>/db` inside the feature's worktree — examples below run from there):
+(`<git-common-dir>/gbuild/<feature>/db` — machine-local, never committed):
 
 ```bash
-cypherlite .gbuild/<feature>/db --mode jsonl < plugins/gbuild/cypher/validate.cypher   # format gate: no output = valid
-cypherlite .gbuild/<feature>/db --mode jsonl < plugins/gbuild/cypher/progress.cypher   # one row per wave: counts + open nodes
-cypherlite .gbuild/<feature>/db --mode jsonl "MATCH (n:GbuildNode {status: 'failed'}) RETURN n.slug"   # anything else
+cypherlite query --read-only --database <git-common-dir>/gbuild/<feature>/db --mode jsonl < plugins/gbuild/cypher/validate.cypher   # format gate: no output = valid
+cypherlite query --read-only --database <git-common-dir>/gbuild/<feature>/db --mode jsonl < plugins/gbuild/cypher/progress.cypher   # one row per wave: counts + open nodes
+cypherlite query --read-only "MATCH (n:GbuildNode {status: 'failed'}) RETURN n.slug" --database <git-common-dir>/gbuild/<feature>/db --mode jsonl   # anything else
 ```
 
 Reads are deliberately narrow so a run doesn't pay for the whole graph on every step: `run` claims a
@@ -233,10 +233,10 @@ plugins/gbuild/
 ```
 
 State lives outside the plugin, in the project: one CypherLite store per feature at
-`.gbuild/<feature>/db/` inside the feature's own git worktree. It holds the plan, every node's status
-and output values, and the full review
-history. Only `db/graph.json` (CypherLite's JSON snapshot, kept current by every write) and the store's
-own `.gitignore` are committed (on the feature branch). All of a feature's worktrees live under
+`<git-common-dir>/gbuild/<feature>/db` — machine-local, never committed and never carried by a clone.
+It holds the plan, every node's status and output values, and the full review history; CypherLite
+checkpoints the store on exit, so `db/graph.json` is just the engine's local snapshot. All of a
+feature's worktrees live under
 `.git/gbuild/<feature>/` — never in `git status`: `tree/` is the feature worktree itself, created by
 `plan` and kept until the feature is done, and during a run each file-touching node gets a `<node>/`
 worktree that is removed the moment its node is accepted (merged into the feature branch, in `tree/`)

package/agents/gbuild-auditor.md

@@ -7,7 +7,7 @@ description: Strict end-of-feature maintainability auditor for a gbuild feature
 
 Unusually strict review of implementation quality, maintainability, and abstraction health. Push for **ambitious** restructurings — "code judo" moves that preserve behavior while making the code dramatically simpler, smaller, and more direct. Delete complexity; don't rearrange it.
 
-The caller passes you the resolved feature slug, the **feature worktree** path, and the feature context it read from the gbuild store: the `destination` and the acceptance bar (each criterion with the nodes covering it). Use the context for scoping only — you are auditing the branch's code, not re-grading individual nodes (`gbuild-reviewer` already did that per node, against each node's own contract; your job is the thing no per-node pass can see — what the accumulated diff did to the codebase as a whole). The feature branch is checked out in the feature worktree: every file read, every check, and every git command runs there (`git -C <worktree> …` or with it as your working directory), never in the main tree. Do not open `.gbuild/` or run `cypherlite` — the caller owns the store. Do NOT write any file — output your audit as your final message exclusively.
+The caller passes you the resolved feature slug, the **feature worktree** path, and the feature context it read from the gbuild store: the `destination` and the acceptance bar (each criterion with the nodes covering it). Use the context for scoping only — you are auditing the branch's code, not re-grading individual nodes (`gbuild-reviewer` already did that per node, against each node's own contract; your job is the thing no per-node pass can see — what the accumulated diff did to the codebase as a whole). The feature branch is checked out in the feature worktree: every file read, every check, and every git command runs there (`git -C <worktree> …` or with it as your working directory), never in the main tree. Do not open the gbuild store or run `cypherlite` — the caller owns the store. Do NOT write any file — output your audit as your final message exclusively.
 
 ## Run the branch's checks first
 

package/agents/gbuild-reviewer.md

@@ -22,7 +22,7 @@ flag them here. Three things belong to you: the contract, the acceptance criteri
 - For `code`/`test`/`chore` nodes: the git diff for this node's work (`git diff HEAD`, or
   `git diff --staged`, or `git log -1 -p` if it already committed).
 
-Everything you need is in your prompt — do not open `.gbuild/` or run `cypherlite`; the caller owns the
+Everything you need is in your prompt — do not open the gbuild store or run `cypherlite`; the caller owns the
 store and records your verdict.
 
 ## REVIEW OBJECTIVE

package/cypher/attention.cypher

@@ -3,7 +3,7 @@
 //   in_progress        claimed but not recorded; if no run is active, an interrupted wave left it
 //   blocked-by-failed  pending behind a failed node, so it can never unblock on its own;
 //                      `detail` = the failed nodes it waits on
-//   cypherlite .gbuild/<slug>/db --mode jsonl < cypher/attention.cypher
+//   cypherlite query --read-only --database <git-common-dir>/gbuild/<slug>/db --mode jsonl < cypher/attention.cypher
 CALL {
   MATCH (n:GbuildNode {status: 'failed'})
   RETURN n.slug AS slug, 'failed' AS reason,

package/cypher/dispatch.cypher

@@ -5,7 +5,7 @@
 // external, and its `shape` says where to find it. No rows = nothing is
 // ready (the graph is done or stuck — ask progress.cypher / attention.cypher).
 // For a router, cancel the unselected branches with set-status.cypher first.
-//   cypherlite .gbuild/<slug>/db --mode jsonl < cypher/dispatch.cypher
+//   cypherlite query --database <git-common-dir>/gbuild/<slug>/db --mode jsonl < cypher/dispatch.cypher
 MATCH (n:GbuildNode {status: 'pending'})
 WHERE NOT EXISTS { MATCH (n)-[:DEPENDS_ON]->(d:GbuildNode) WHERE NOT d.status IN ['completed', 'cancelled'] }
 SET n.status = 'in_progress'
@@ -28,4 +28,3 @@ RETURN n.slug AS slug,
          RETURN {name: f.name, shape: f.shape}
        } AS outputs
 ORDER BY slug;
-.checkpoint

package/cypher/feature.cypher

@@ -2,7 +2,7 @@
 // nodes that cover each criterion. What review hands the auditor and what pr
 // builds the description from. Per-node output values are not included — get
 // one node's with node.cypher if you actually need it.
-//   cypherlite .gbuild/<slug>/db --mode jsonl < cypher/feature.cypher
+//   cypherlite query --read-only --database <git-common-dir>/gbuild/<slug>/db --mode jsonl < cypher/feature.cypher
 MATCH (f:Feature)
 RETURN f.feature AS feature,
        f.destination AS destination,

package/cypher/node.cypher

@@ -3,7 +3,7 @@
 // external (from the codebase / environment): its `from` and `value` are null.
 // Used for reopen and ad-hoc inspection; run gets its definitions from
 // dispatch.cypher instead.
-//   cypherlite .gbuild/<slug>/db --mode jsonl --param 'slug="<node-slug>"' < cypher/node.cypher
+//   cypherlite query --read-only --database <git-common-dir>/gbuild/<slug>/db --mode jsonl --param 'slug="<node-slug>"' < cypher/node.cypher
 MATCH (n:GbuildNode {slug: $slug})
 RETURN n.slug AS slug,
        n.title AS title,

package/cypher/progress.cypher

@@ -2,7 +2,7 @@
 // that wave not yet completed or cancelled. A wave with `open: []` is done;
 // the graph is done when every row's `open` is empty. `wave` is the longest
 // DEPENDS_ON chain below a node (0 = no dependencies).
-//   cypherlite .gbuild/<slug>/db --mode jsonl < cypher/progress.cypher
+//   cypherlite query --read-only --database <git-common-dir>/gbuild/<slug>/db --mode jsonl < cypher/progress.cypher
 MATCH (n:GbuildNode)
 OPTIONAL MATCH p = (n)-[:DEPENDS_ON*]->()
 WITH n, coalesce(max(length(p)), 0) AS wave

package/cypher/record.cypher

@@ -7,7 +7,7 @@
 // you sent. Output values must be scalars or lists of scalars — one nested
 // value rejects the whole batch (InvalidPropertyType); JSON-encode it and
 // resend.
-//   cypherlite .gbuild/<slug>/db --mode jsonl --param 'results=[
+//   cypherlite query --database <git-common-dir>/gbuild/<slug>/db --mode jsonl --param 'results=[
 //     {"slug": "a", "verdict": "pass", "failed_criteria": [], "outputs": {"value": 7},
 //      "started_at": "<iso>", "completed_at": "<iso>"},
 //     {"slug": "b", "verdict": "fail", "failed_criteria": ["<criterion>"]}
@@ -35,4 +35,3 @@ FOREACH (_ IN CASE WHEN ok THEN [1] ELSE [] END |
   SET n.status = 'completed', n.started_at = r.started_at, n.completed_at = r.completed_at)
 RETURN n.slug AS slug, attempt, review.verdict AS verdict, ok AS completed, missing AS missing_outputs
 ORDER BY slug;
-.checkpoint

package/cypher/schema.cypher

@@ -1,5 +1,5 @@
 // gbuild store schema. Run once, when plan creates the store:
-//   cypherlite .gbuild/<slug>/db --snapshot-format json < cypher/schema.cypher
+//   cypherlite query --database <git-common-dir>/gbuild/<slug>/db --snapshot-format json < cypher/schema.cypher
 // Everything the engine can enforce at write time lives here; the rest of the
 // contract is checked by validate.cypher.
 CREATE CONSTRAINT feature_name FOR (n:Feature) REQUIRE n.feature IS :: STRING;
@@ -42,4 +42,3 @@ CREATE CONSTRAINT review_verdict_exists FOR (n:Review) REQUIRE n.verdict IS NOT
 CREATE CONSTRAINT review_at FOR (n:Review) REQUIRE n.at IS :: STRING;
 CREATE CONSTRAINT review_at_exists FOR (n:Review) REQUIRE n.at IS NOT NULL;
 CREATE CONSTRAINT review_failed_criteria FOR (n:Review) REQUIRE n.failed_criteria IS :: LIST<STRING NOT NULL>;
-.checkpoint

package/cypher/set-status.cypher

@@ -3,7 +3,7 @@
 // retry/repair, stop), or `pending` (reset nodes an interrupted run left
 // in_progress). `completed` is rejected — only record.cypher may set it, so it
 // can require a passing review and every output value.
-//   cypherlite .gbuild/<slug>/db --mode jsonl --param 'slugs=["a","b"]' --param 'status="cancelled"' \
+//   cypherlite query --database <git-common-dir>/gbuild/<slug>/db --mode jsonl --param 'slugs=["a","b"]' --param 'status="cancelled"' \
 //     < cypher/set-status.cypher
 UNWIND $slugs AS s
 MATCH (n:GbuildNode {slug: s})
@@ -11,4 +11,3 @@ WHERE $status IN ['pending', 'in_progress', 'failed', 'cancelled']
 SET n.status = $status
 RETURN n.slug AS slug, n.status AS status
 ORDER BY slug;
-.checkpoint

package/cypher/status.cypher

@@ -4,7 +4,7 @@
 //   otherwise = the stored status (in_progress, completed, failed, cancelled)
 // `wave` is the longest DEPENDS_ON chain below the node (0 = no dependencies),
 // so nodes sharing a wave are safe to run concurrently.
-//   cypherlite .gbuild/<slug>/db --mode jsonl < cypher/status.cypher
+//   cypherlite query --read-only --database <git-common-dir>/gbuild/<slug>/db --mode jsonl < cypher/status.cypher
 MATCH (n:GbuildNode)
 OPTIONAL MATCH p = (n)-[:DEPENDS_ON*]->()
 WITH n, coalesce(max(length(p)), 0) AS wave

package/cypher/validate.cypher

@@ -1,5 +1,5 @@
 // gbuild format gate. Zero rows = valid; every row is one violation.
-//   cypherlite .gbuild/<slug>/db --mode jsonl < cypher/validate.cypher
+//   cypherlite query --read-only --database <git-common-dir>/gbuild/<slug>/db --mode jsonl < cypher/validate.cypher
 // Required properties, their types and slug/acceptance-id uniqueness are
 // engine constraints (schema.cypher) — a write that breaks them never lands.
 // This query checks everything the engine can't: enums, label/type agreement,

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-gbuild",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "OpenCode plugin for gbuild — graph-native task planning and execution with concurrent fan-out, per-node review, and durable checkpoints.",
   "type": "module",
   "license": "MIT",

package/reference/checklist.md

@@ -1,6 +1,6 @@
 # Ship checklist
 
-`plan` runs this checklist against the graph it just wrote, before committing the store. Any item that
+`plan` runs this checklist against the graph it just wrote, before handing off to `run`. Any item that
 fails means revise the graph (with Cypher), not add a caveat in prose.
 
 1. **Risky assumptions are resolved, not deferred.** Every assumption that would invalidate nodes or

package/reference/cypher.md

@@ -1,13 +1,14 @@
 # Talking to the gbuild store
 
-Every gbuild skill reads and writes the feature store (`.gbuild/<feature>/db/` inside the feature's git
-worktree, modelled in
-`reference/graph-format.md`) with the `cypherlite` CLI and nothing else. This file is the full operating
-manual; the skills that only run plugin scripts carry the short version of these rules inline.
+Every gbuild skill reads and writes the feature store (modelled in `reference/graph-format.md`) with the
+`cypherlite` CLI and nothing else. `DB` throughout is the store path:
+`<git-common-dir>/gbuild/<feature>/db` — beside the feature worktree, machine-local, never committed.
+This file is the full operating manual; the skills that only run plugin scripts carry the short version
+of these rules inline.
 
 ## Requirement
 
-`cypherlite` 0.7.0 or newer must be on PATH. Check first, in every skill:
+`cypherlite` 0.12.0 or newer must be on PATH. Check first, in every skill:
 
 ```
 cypherlite --version
@@ -17,42 +18,47 @@ If the command is missing, stop and tell the user gbuild needs it:
 `curl -sSfL https://neo4j-labs.github.io/cypherlite/install.sh | bash`. Never fall back to reading or
 editing `graph.json` by hand.
 
+The floor is the ADR-0200 CLI cutover: the store path is a flag (`-d` / `--database PATH`), the first
+positional is the Cypher statement (never the database), and piped scripts and the interactive shell
+require the explicit `query` verb. The old path-first form — database as the first argument — hard-fails.
+
 ## One writer, one command at a time
 
 CypherLite takes an exclusive lock on the store while a process has it open. A second process — reader
-or writer — fails with `storage locked` (exit 1). So:
+or writer — fails with `storage locked` (exit 5). So:
 
 - **Only the skill running in the main context runs `cypherlite` against the store.** Subagents never
   do: give them what they need in their prompt, have them report results in their final message, and
   record those results yourself.
 - **Never run two `cypherlite` commands against the same store at once** — no parallel tool calls on it.
   Fan-out is for agents, not for store access.
-- On `storage locked`, another process holds the store (another gbuild command, a REPL left open). Wait a
-  few seconds and retry, up to 3 times; then stop and report. Never delete `.cypherlite.lock`.
+- On `storage locked` (exit 5), another process holds the store (another gbuild command, a REPL left
+  open). Wait a few seconds and retry, up to 3 times; then stop and report. Never delete
+  `.cypherlite.lock`.
 
 ## Invocation
 
 Always pass `--mode jsonl`: one compact JSON object per row, one row per line, and no output at all when
-there are no rows. `DB` below is the feature store: `.gbuild/<feature>/db` inside the feature worktree
-(`<git-common-dir>/gbuild/<feature>/tree/`), or in the main tree for a feature charted before the
-worktree layout.
+there are no rows. Every call is `cypherlite query [STATEMENT] --database DB …`; with no STATEMENT the
+piped stdin is the script list. Pure reads add `--read-only`: no exit flush, a shared lock, and a
+fail-fast on a wrong path — a read-only call never creates a missing store. Writes (schema creation,
+dispatch, record, set-status, authored heredocs) go without.
 
 ```
-# a plugin script
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
+# a plugin read script
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
 
-# a plugin script with parameters
-cypherlite DB --mode jsonl --param 'slug="b-consume-doubled"' < ${CLAUDE_PLUGIN_ROOT}/cypher/node.cypher
+# a plugin read script with parameters
+cypherlite query --read-only --database DB --mode jsonl --param 'slug="b-consume-doubled"' < ${CLAUDE_PLUGIN_ROOT}/cypher/node.cypher
 
 # an ad-hoc read — return only the columns you need, and keep a LIMIT on anything that can grow
-cypherlite DB --mode jsonl "MATCH (n:GbuildNode {status: 'failed'}) RETURN n.slug LIMIT 20"
+cypherlite query "MATCH (n:GbuildNode {status: 'failed'}) RETURN n.slug LIMIT 20" --read-only --database DB --mode jsonl
 
 # a write you author (plan, reopen, fixes) — quoted heredoc delimiter, so the shell expands nothing
-cypherlite DB <<'CYPHER'
+cypherlite query --database DB <<'CYPHER'
 .begin
 MATCH (n:GbuildNode {slug: 'b-consume-doubled'}) SET n.title = 'Consume the value, double it';
 .commit
-.checkpoint
 CYPHER
 ```
 
@@ -66,33 +72,46 @@ CYPHER
   Bare values that start with a digit — timestamps, `01-…` slugs — are rejected, so always quote.
 - **String literals** in Cypher you author: single quotes by default; double quotes when the text
   contains an apostrophe (`"gbuild's"`); backslash-escape (`\'`, `\"`) when it contains both.
-- **Authored writes are atomic and checkpointed.** Wrap them in `.begin` / `.commit` — if any statement
-  fails, the whole transaction is discarded — and end with `.checkpoint` so `graph.json` on disk (what
-  git commits) is always current. The plugin write scripts already do both.
+- **Authored writes are atomic.** Wrap them in `.begin` / `.commit` — if any statement fails, the whole
+  transaction is discarded. The plugin write scripts already do. Never write `.checkpoint`: a writable
+  session checkpoints on exit by itself.
 - **Values are scalars or lists of scalars.** CypherLite cannot store a map as a property value;
   JSON-encode anything nested into a string.
 - **Read the result.** The plugin write scripts are guarded and return what they actually changed.
   Compare it with what you asked for; never assume a write landed.
-- **Exit code 1 is a failure** — lock, constraint violation (`ConstraintValidationFailed`), syntax. Read
-  stderr, fix, retry the whole transaction.
+- **Check the exit code.** `0` is success (an empty result included). `5` is `storage locked` or a
+  write conflict — wait and retry as above. `6` is a rejected statement — syntax, semantic, or type
+  error, including `ConstraintValidationFailed` and writes on a `--read-only` store — read stderr, fix,
+  retry the whole transaction. `2` is a usage error — fix the invocation, not the data. `1` is any other
+  runtime failure. With `--mode jsonl` a failure also prints one JSON error envelope on stdout, after
+  any rows already written: `{"error":{"code","exit_code","kind","message","retryable"}}`.
+- **Agent output is capped at 100 rows.** Under a detected agent harness with non-terminal stdout —
+  gbuild skills always are — a statement prints at most 100 rows, warns on stderr, and still exits `0`.
+  Keep a `LIMIT` on anything that can grow; when you genuinely need every row, pass `--max-rows 0` (or
+  set `CYPHERLITE_MAX_ROWS=0`).
 
 ## Creating a store
 
-Only `plan` does this, once per feature, with `DB` = `.gbuild/<feature>/db` inside the feature worktree
-it just created:
+Only `plan` does this, once per feature:
 
 ```
 mkdir -p DB
-cypherlite DB --snapshot-format json < ${CLAUDE_PLUGIN_ROOT}/cypher/schema.cypher
-printf '*\n!.gitignore\n!graph.json\n' > DB/.gitignore
+cypherlite query --database DB --snapshot-format json < ${CLAUDE_PLUGIN_ROOT}/cypher/schema.cypher
 ```
 
 `--snapshot-format json` belongs on this first call only (it applies to an empty directory). It installs
-the schema constraints and pins the JSON codec, so `graph.json` exists from the start.
+the schema constraints and pins the JSON codec for cross-build compatibility: a parquet-enabled
+CypherLite build defaults a new store to Parquet, and a JSON-pinned store opens in every build.
+
+## Migrating an old store
+
+Stores charted by gbuild ≤ 0.7.1 live at `<tree>/.gbuild/<slug>/db` and are git-tracked. Migrate with
+`git rm -r --cached .gbuild` (commit the removal) and
+`mv <tree>/.gbuild/<slug>/db <git-common-dir>/gbuild/<slug>/db`.
 
 ## Script catalog
 
-All in `${CLAUDE_PLUGIN_ROOT}/cypher/`. Writes end with `.checkpoint`.
+All in `${CLAUDE_PLUGIN_ROOT}/cypher/`.
 
 | script               | params                    | returns                                                        | used by |
 | -------------------- | ------------------------- | -------------------------------------------------------------- | ------- |

package/reference/graph-format.md

@@ -2,12 +2,12 @@
 
 This file is normative. Where a skill disagrees with this doc, this doc wins.
 
-One CypherLite store per feature: `.gbuild/<feature>/db/` inside the feature's git worktree
-(`<git-common-dir>/gbuild/<feature>/tree/` — `plan` creates the worktree; a feature charted before the
-worktree layout keeps its store in the main tree). `plan` creates and charts it, `run` records
-progress in it, and every skill reads it — **all through Cypher**. No skill reads or writes `graph.json`
-directly; it is CypherLite's snapshot of the store. How to talk to the store (the single-writer rule,
-invocation, quoting, the script catalog) is in `reference/cypher.md`.
+One CypherLite store per feature: `<git-common-dir>/gbuild/<feature>/db/`, beside the feature worktree
+(`<git-common-dir>/gbuild/<feature>/tree/`, which `plan` creates) — untracked, machine-local, never
+committed. `plan` creates and charts it, `run` records progress in it, and every skill reads it — **all
+through Cypher**. No skill reads or writes `graph.json` directly; it is CypherLite's local snapshot of
+the store, not a gbuild artifact. How to talk to the store (the single-writer rule, invocation, quoting,
+the script catalog) is in `reference/cypher.md`.
 
 `templates/example.cypher` is a complete worked example — a 4-node diamond — written exactly the way
 `plan` writes a new feature.
@@ -15,17 +15,17 @@ invocation, quoting, the script catalog) is in `reference/cypher.md`.
 ## Store layout
 
 ```
-.gbuild/<feature>/db/
-  graph.json          CypherLite JSON snapshot — committed; always current (every write ends with .checkpoint)
-  .gitignore          "*", "!.gitignore", "!graph.json" — committed
-  manifest.json       engine files — ignored
+<git-common-dir>/gbuild/<feature>/db/
+  graph.json          CypherLite JSON snapshot — the engine's local snapshot; gbuild never reads or writes it
+  manifest.json       engine files
   wal/
   .cypherlite.lock
 ```
 
-The store is created with the JSON codec (`--snapshot-format json`, see `reference/cypher.md`) so
-`graph.json` diffs are reviewable in a PR, and a clone holding only `graph.json` is a complete store —
-data **and** constraints.
+The store lives outside every checkout: untracked, machine-local, never committed. It is created with
+the JSON codec (`--snapshot-format json`, see `reference/cypher.md`) for cross-build compatibility: a
+parquet-enabled CypherLite build defaults a new store to Parquet, and a JSON-pinned store opens in every
+build.
 
 ## Nodes
 
@@ -41,7 +41,7 @@ data **and** constraints.
 
 | property       | type           | meaning                                              |
 | -------------- | -------------- | ---------------------------------------------------- |
-| `feature`      | string         | the slug — matches the `.gbuild/<feature>/` dir in the feature worktree, immutable |
+| `feature`      | string         | the slug — matches the `<feature>` segment of the store path, immutable |
 | `destination`  | string         | one line: what is true once this is done             |
 | `context`      | string         | why this exists, one or two lines                    |
 | `out_of_scope` | list of string | bullets, may be empty                                |

package/reference/queries.md

@@ -1,9 +1,9 @@
 # Ad-hoc queries
 
 The plugin scripts (`reference/cypher.md` § Script catalog) cover everything the skills do. These are for
-the questions in between. Run them with `cypherlite DB --mode jsonl "<query>"`, one at a
-time — `DB` is the feature store (`.gbuild/<feature>/db` inside the feature worktree);
-return only the columns you need and keep a `LIMIT` on anything that can grow.
+the questions in between. Run them with `cypherlite query "<query>" --read-only --database DB --mode
+jsonl`, one at a time — `DB` is the feature store (`reference/cypher.md`); return only the columns you
+need and keep a `LIMIT` on anything that can grow.
 
 ```cypher
 -- the whole plan with progress

package/skills/plan/SKILL.md

@@ -24,23 +24,24 @@ inform the choices below. `${CLAUDE_PLUGIN_ROOT}/reference/checklist.md` is the
 | a description, link, or file path             | **Chart** — new feature |
 | an existing feature slug with `--add "<req>"` | **Reopen**              |
 
-A bare slug with no store is a description, not a slug — chart it. A slug's store lives in its feature
-worktree at `<git-common-dir>/gbuild/<slug>/tree/.gbuild/<slug>/db` (a feature charted before the
-worktree layout keeps its store at `.gbuild/<slug>/db` in the main tree).
+A bare slug with no store is a description, not a slug — chart it. A slug's store lives beside its
+feature worktree at `<git-common-dir>/gbuild/<slug>/db`, machine-local and never committed (a gbuild ≤ 0.7.1
+store needs the move in `reference/cypher.md`).
 
 ## Chart
 
 ### 1. Slug, branch, and feature worktree
 
 Derive the feature slug from `$ARGUMENTS`: kebab-case, ≤4 words, names the outcome not the mechanism
-(`oauth-device-flow`, not `add-some-auth-stuff`). It's the `.gbuild/<slug>/` directory name and the
+(`oauth-device-flow`, not `add-some-auth-stuff`). It's the `gbuild/<slug>/` directory name and the
 `Feature` node's `feature` property — immutable once charted.
 
 gbuild never changes the branch of the user's checkout: the feature branch lives in its own **feature
 worktree**, so several features can be charted and run in parallel without racing each other's `HEAD`,
-and uncommitted work in the main tree is irrelevant — there is no dirty-tree check. Resolve two paths,
-both absolute: `GC` = `git rev-parse --git-common-dir` (resolve it to an absolute path), and `FT` =
-`GC/gbuild/<slug>/tree` — the feature worktree, the one place the feature branch is checked out. Then:
+and uncommitted work in the main tree is irrelevant — there is no dirty-tree check. Resolve these paths,
+all absolute: `GC` = `git rev-parse --git-common-dir` (resolve it to an absolute path), `WT` =
+`GC/gbuild/<slug>` — the feature's worktree root, inside `.git/` so nothing under it is ever committed —
+and `FT` = `WT/tree`, the feature worktree, the one place the feature branch is checked out. Then:
 
 - `FT` is already a registered worktree (`git worktree list --porcelain`) → reuse it, say so.
 - A branch named `<slug>` or ending `/<slug>` already exists → if it's checked out somewhere (a feature
@@ -55,14 +56,13 @@ both absolute: `GC` = `git rev-parse --git-common-dir` (resolve it to an absolut
   Take `<prefix>` from the repo's convention — project or user instructions first, else the dominant
   pattern in `git branch --list` — and fall back to `gbuild` when there is none.
 
-Report the branch and `FT`. Everything below happens in `FT`; `DB` below is
-`FT/.gbuild/<slug>/db`.
+Report the branch and `FT`. Everything below happens in `FT`; `DB` below is `WT/db`.
 
 ### 2. Analyse the codebase
 
 Read the project manifest(s), directory structure, `README.md`, and — for related in-flight work — the
-`Feature` of every existing store (`feature.cypher` against each `GC/gbuild/*/tree/.gbuild/*/db`, plus
-any legacy `.gbuild/*/db` in the main tree, one at a time). Resolve
+`Feature` of every existing store (`feature.cypher` with `--read-only` against each `GC/gbuild/*/db`,
+one at a time). Resolve
 file paths or URLs in `$ARGUMENTS`; if a reference fails to load, say so and ask.
 
 ### 3. Validate and explore
@@ -146,16 +146,16 @@ design, don't annotate around a failing item.
 
 ### 8. Create the store and write the graph
 
-Create the store exactly as `reference/cypher.md` § Creating a store shows (`mkdir`, `schema.cypher` with
-`--snapshot-format json`, the `db/.gitignore`).
+Create the store exactly as `reference/cypher.md` § Creating a store shows (`mkdir -p DB`, then
+`schema.cypher` with `--snapshot-format json`).
 
 Then write the whole graph as **one** Cypher script, piped through a quoted heredoc.
 `${CLAUDE_PLUGIN_ROOT}/templates/example.cypher` is a complete worked example — follow its structure:
 `.begin`, a single statement of `CREATE` clauses (so variables like `a1` or `a_value` stay in scope for
-the edges), `.commit`, `.checkpoint`.
+the edges), `.commit`.
 
 ```
-cypherlite DB <<'CYPHER'
+cypherlite query --database DB <<'CYPHER'
 .begin
 CREATE (f:Feature {feature: '<slug>', destination: '...', context: '...', out_of_scope: ['...']})
 CREATE (a1:Acceptance {id: 'a-1', text: '...'})
@@ -168,7 +168,6 @@ CREATE (m)-[:DEPENDS_ON]->(n)
 CREATE (m)-[:INPUT]->(:Field {name: '...', shape: '<...>'})-[:FROM]->(n_out)
 CREATE (m)-[:SATISFIES]->(a1);
 .commit
-.checkpoint
 CYPHER
 ```
 
@@ -178,30 +177,26 @@ slug) fails the transaction and writes nothing — fix the script and run it aga
 ### 9. Validate
 
 ```
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/validate.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/validate.cypher
 ```
 
 No output means valid. Every row is a violation (`check`, `detail`): fix it with Cypher — a `.begin` …
-`.commit` … `.checkpoint` script of `MATCH … SET/CREATE/DELETE` — and re-run until it prints nothing. Never
-hand off or commit a graph that fails validation, and never edit `graph.json` directly.
+`.commit` script of `MATCH … SET/CREATE/DELETE` — and re-run until it prints nothing. Never
+hand off a graph that fails validation, and never edit `graph.json` directly.
 
 Then confirm run-readiness:
 
 ```
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
 ```
 
 One row per wave: each row's `open` slugs are the decomposition, and the `frontier` counts are what
 `run` claims first. Nodes you expected to run together should share a wave.
 
-### 10. Commit and stop
+### 10. Report and stop
 
-Commit `.gbuild/<slug>/` on the feature branch unless the repo ignores it (`git -C FT check-ignore -q
-.gbuild/`; if true, don't stage anything under it). The store's own `.gitignore` limits that to
-`db/graph.json` and `db/.gitignore`. Stage and commit from the feature worktree:
-`git -C FT add .gbuild/<slug>` and `git -C FT commit -m "<slug>: chart graph"`.
-
-Report the branch, `FT`, the waves, and the frontier. Close with `next: /gbuild:run <slug>`.
+There is nothing to commit — the store is machine-local, outside every checkout. Report the branch,
+`FT`, the waves, and the frontier. Close with `next: /gbuild:run <slug>`.
 
 ## Reopen
 
@@ -220,7 +215,7 @@ Report the branch, `FT`, the waves, and the frontier. Close with `next: /gbuild:
 3. Write it as one script that `MATCH`es what it connects to and `CREATE`s the rest:
 
    ```
-   cypherlite DB <<'CYPHER'
+   cypherlite query --database DB <<'CYPHER'
    .begin
    MATCH (f:Feature), (up:GbuildNode {slug: '<existing-slug>'})-[:OUTPUT]->(up_out:Field {name: '<field>'})
    CREATE (f)-[:HAS_ACCEPTANCE]->(a:Acceptance {id: 'a-3', text: '...'})
@@ -230,13 +225,11 @@ Report the branch, `FT`, the waves, and the frontier. Close with `next: /gbuild:
    CREATE (n)-[:OUTPUT]->(:Field {name: '...', shape: '<...>'})
    CREATE (n)-[:SATISFIES]->(a);
    .commit
-   .checkpoint
    CYPHER
    ```
 
-4. **Re-run `validate.cypher`** until it prints nothing, then `progress.cypher`. Commit in `FT`
-   (`git -C FT commit -m "<slug>: reopen graph — <what was added>"` after staging `.gbuild/<slug>`,
-   same ignore rule as Chart's step 10), report the new frontier.
+4. **Re-run `validate.cypher`** until it prints nothing, then `progress.cypher`, and report the new
+   frontier.
 
 If the requirement needs no new nodes (an existing node's contract already covers it), say so and stop
 — don't manufacture graph churn.

package/skills/pr/SKILL.md

@@ -12,9 +12,9 @@ This skill MUST run in the **main conversation context**. It MUST NOT be invoked
 
 `$ARGUMENTS` is free-form text: an optional feature slug and an optional `--max-rounds N` flag.
 
-- **slug**: the first token that isn't a flag. If absent, infer it — if exactly one feature worktree exists (`<git-common-dir>/gbuild/*/tree`), that's the slug; otherwise fall back to the most recently modified `graph.json` under `<git-common-dir>/gbuild/*/tree/.gbuild/*/db` (or, for features charted before the worktree layout, `.gbuild/*/db/graph.json` in the main tree). If neither resolves, leave `<slug>` unresolved (the auto-fix step degrades gracefully — see Step 4).
+- **slug**: the first token that isn't a flag. If absent, infer it — if exactly one feature worktree exists (`<git-common-dir>/gbuild/*/tree`), that's the slug; otherwise fall back to the most recently modified `graph.json` under `<git-common-dir>/gbuild/*/db`. If neither resolves, leave `<slug>` unresolved (the auto-fix step degrades gracefully — see Step 4).
 
-When `<slug>` resolved, every graph read below goes through `cypherlite`: run `cypherlite --version` first (missing → stop; gbuild needs it), one command at a time, always `--mode jsonl` (no output = no rows), and on `storage locked` wait and retry up to 3 times. Anything else: `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md`. `DB` below is `FT/.gbuild/<slug>/db` (see Step 1 for `FT`).
+When `<slug>` resolved, every graph read below goes through `cypherlite`: run `cypherlite --version` first (missing → stop; gbuild needs it), one command at a time, always `--read-only --mode jsonl` (no output = no rows — this skill only reads the store), and on `storage locked` wait and retry up to 3 times. Anything else: `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md`. `DB` below is `<git-common-dir>/gbuild/<slug>/db`, beside the feature worktree (a gbuild ≤ 0.7.1 store needs the move in `reference/cypher.md`).
 - **max_rounds**: the value of `--max-rounds N` (also accept `--max-rounds=N`). Default `3` when absent.
 
 ## Step 1: Preconditions
@@ -27,7 +27,7 @@ Verify the environment before touching the remote. Stop with a clear, actionable
 4. **Feature worktree and branch.** Resolve `FT` (the feature worktree) and `<branch>` (the feature branch checked out there) exactly as `/gbuild:run`'s step 0 describes — the registered worktree at `<git-common-dir>/gbuild/<slug>/tree`, a legacy feature whose branch is in the main tree, or attach a branch that is checked out nowhere. When `<slug>` is unresolved, use the main tree's current branch as `<branch>` and its root as `FT`. If `<branch>` equals `<base>`, stop — there is nothing to open a PR for.
 5. **Clean tree.** Check for uncommitted changes in the feature worktree (`git -C FT status --porcelain`). `/gbuild:run` commits each node's work as it goes, so it should be clean. If there are uncommitted changes, warn the user and ask whether to proceed (they may want to commit first).
 6. **Commits ahead of base.** Confirm the branch has commits the base lacks (`git log <base>..<branch> --oneline`). If empty, stop — nothing to push.
-7. **Graph finished.** When `<slug>` resolved, run `cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher`. If any row's `open` is non-empty, warn that the graph isn't finished (name the open nodes) and ask whether to open the PR anyway. If any row has `failed` > 0, get their names from `attention.cypher` and name them — a PR built on an escalated node is usually premature.
+7. **Graph finished.** When `<slug>` resolved, run `cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher`. If any row's `open` is non-empty, warn that the graph isn't finished (name the open nodes) and ask whether to open the PR anyway. If any row has `failed` > 0, get their names from `attention.cypher` and name them — a PR built on an escalated node is usually premature.
 
 ## Step 2: Determine the remote & push
 
@@ -48,7 +48,7 @@ Gather context from:
 
 - Commit subjects: `git log <base>..<branch> --oneline`.
 - File overview: `git diff <base>...<branch> --stat`.
-- When `<slug>` resolved: `cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/feature.cypher` — the `destination` and the acceptance bar (with the nodes covering each criterion).
+- When `<slug>` resolved: `cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/feature.cypher` — the `destination` and the acceptance bar (with the nodes covering each criterion).
 
 Derive a concise, conventional-commit-style title from the feature/branch and the changes (e.g. `feat(auth): add OAuth login`).
 
@@ -103,4 +103,6 @@ next: /gbuild:status <slug>
 ```
 
 The feature worktree `FT` keeps the branch checked out until removed — once the PR is merged and the
-graph is no longer needed, `git worktree remove FT` (and `git branch -d <branch>`) cleans up.
+graph is no longer needed, `git worktree remove WT/tree && rm -rf WT && git branch -d <branch>` (with
+`WT` = `<git-common-dir>/gbuild/<slug>`) cleans up: the whole `WT`, store included, dies with the
+feature.

package/skills/review/SKILL.md

@@ -12,21 +12,22 @@ missed abstractions that only exist *between* nodes, which no per-node review ca
 
 `$ARGUMENTS` is optional. If present, treat it as the feature slug. If absent, infer it — if exactly one
 feature worktree exists (`<git-common-dir>/gbuild/*/tree`), that's the slug; otherwise fall back to the
-most recently modified `graph.json` under `<git-common-dir>/gbuild/*/tree/.gbuild/*/db` (or, for
-features charted before the worktree layout, `.gbuild/*/db/graph.json` in the main tree). Do NOT write
+most recently modified `graph.json` under `<git-common-dir>/gbuild/*/db`. Do NOT write
 any file — this skill outputs to chat exclusively.
 
 Resolve `FT`, the feature worktree, exactly as `/gbuild:run`'s step 0 describes (reuse the registered
-worktree, attach if the feature branch is checked out nowhere). `DB` below is `FT/.gbuild/<slug>/db`.
+worktree, attach if the feature branch is checked out nowhere). `DB` below is
+`<git-common-dir>/gbuild/<slug>/db`, beside the worktree (a gbuild ≤ 0.7.1 store needs the move in
+`reference/cypher.md`).
 
 Store rules: run `cypherlite --version` first (missing → stop; gbuild needs it). One `cypherlite`
-command at a time, always `--mode jsonl` (no output = no rows); on `storage locked` wait and retry up to
-3 times. Anything else: `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md`.
+command at a time, always `--read-only --mode jsonl` (no output = no rows — this skill only reads); on
+`storage locked` wait and retry up to 3 times. Anything else: `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md`.
 
 Check the graph is finished — one row per wave, cheap:
 
 ```
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
 ```
 
 If any row's `open` is non-empty, say the graph isn't finished (name the open nodes) and ask whether to
@@ -38,7 +39,7 @@ address.
 Fetch the feature context:
 
 ```
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/feature.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/feature.cypher
 ```
 
 Launch the `gbuild-auditor` subagent (agents/gbuild-auditor.md — this plugin's own copy, gbuild does not

package/skills/run/SKILL.md

@@ -2,8 +2,8 @@
 description: Executes a gbuild graph — dispatches every ready-and-independent node in the current wave concurrently, each file-touching node in its own git worktree, reviews each node's output with gbuild-reviewer before merging its branch and recording it complete, and resumes only the remaining frontier on re-invocation. Use after /gbuild:plan has charted the graph.
 ---
 
-Run the graph for the feature `$ARGUMENTS` (the slug; step 0 resolves `DB`, the store — it lives in
-the feature's own worktree, so this skill never changes the branch of the user's checkout).
+Run the graph for the feature `$ARGUMENTS` (the slug; step 0 resolves `DB`, the store — the feature
+branch lives in its own worktree, so this skill never changes the branch of the user's checkout).
 
 **CRITICAL: this skill must run in the main context, not inside a forked agent.** It dispatches its own
 subagents per node; a subagent cannot itself fan out further subagents reliably. It is also the store's
@@ -17,6 +17,8 @@ back in their final message, and this skill records it.
 - One `cypherlite` command at a time against `DB` — never parallel tool calls on it, never from a subagent.
 - Always `--mode jsonl`: one JSON object per row, no output = no rows. Every `--param` value is JSON,
   single-quoted for the shell (`--param 'slugs=["a","b"]'`).
+- Pure reads (validate, attention, progress below) open the store `--read-only`; the writes (dispatch,
+  set-status, record) stay writable — the CLI checkpoints a writable store on exit itself.
 - `storage locked` → another process holds the store: wait a few seconds, retry up to 3 times, then stop.
   Exit code 1 = failure; read stderr. Anything beyond the scripts below: `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md`.
 - Never re-read what you already hold. The claimed wave's definitions stay valid for its retries.
@@ -28,7 +30,7 @@ Default to `git`. Resolve these facts first, absolute paths, and reuse them thro
 - `GC` = `git rev-parse --git-common-dir`, resolved to an absolute path; `WT` = `GC/gbuild/$ARGUMENTS`
   (the worktree root — inside `.git/`, so worktrees never appear in `git status` or get committed).
 - `FT` = the feature worktree and `BRANCH` = the feature branch — the one place `BRANCH` is checked
-  out, and where every merge and store commit below lands:
+  out, and where every merge below lands:
   1. `WT/tree` is a registered worktree (`git worktree list --porcelain`) → `FT` = it, `BRANCH` =
      `git -C FT branch --show-current`.
   2. Else a worktree whose branch is `$ARGUMENTS` or ends `/$ARGUMENTS` → `FT` = that worktree's path
@@ -36,14 +38,14 @@ Default to `git`. Resolve these facts first, absolute paths, and reuse them thro
   3. Else such a branch exists but is checked out nowhere → attach it: `git worktree add WT/tree
      <branch>`, `FT` = `WT/tree`.
   4. Else → stop: there is no feature branch for `$ARGUMENTS` — chart it with `/gbuild:plan` first.
-- `DB` = `FT/.gbuild/$ARGUMENTS/db`. `git -C FT check-ignore -q .gbuild/` tells you whether to commit
-  the store at all.
+- `DB` = `WT/db` — the feature's store, beside the worktree: machine-local, never committed (a gbuild ≤ 0.7.1
+  store needs the move in `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md`).
 
 Then check and recover:
 
 ```
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/validate.cypher
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/attention.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/validate.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/attention.cypher
 ```
 
 - `validate` printing anything → stop and report the rows; do not run a graph `plan` didn't finish
@@ -55,7 +57,7 @@ cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/attention.cypher
   them all in one call so they re-dispatch, and mention it in the report:
 
   ```
-  cypherlite DB --mode jsonl --param 'slugs=["<slug>", ...]' --param 'status="pending"' \
+  cypherlite query --database DB --mode jsonl --param 'slugs=["<slug>", ...]' --param 'status="pending"' \
     < ${CLAUDE_PLUGIN_ROOT}/cypher/set-status.cypher
   ```
 
@@ -87,7 +89,7 @@ behavior this plugin replaces.
 1. **CLAIM.**
 
    ```
-   cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/dispatch.cypher
+   cypherlite query --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/dispatch.cypher
    ```
 
    It moves the whole frontier to `in_progress` and prints one row per claimed node with everything its
@@ -122,7 +124,7 @@ behavior this plugin replaces.
      nested into a string;
    - record its own UTC start and finish (`date -u +%Y-%m-%dT%H:%M:%SZ`) and end its final message with
      `{"started_at": "...", "completed_at": "...", "outputs": {...}}`;
-   - **not** run `cypherlite` or touch `.gbuild/`.
+   - **not** run `cypherlite` or touch the store.
 
 3. **REVIEW.** Once IMPLEMENT returns, spawn a `gbuild-reviewer` per node, again all in one message
    (`agents/gbuild-reviewer.md` — this plugin's own copy, gbuild does not depend on hone-ai being
@@ -151,7 +153,7 @@ behavior this plugin replaces.
    `VERDICT:` line, `failed_criteria` from its `[fail]` lines:
 
    ```
-   cypherlite DB --mode jsonl --param 'results=[
+   cypherlite query --database DB --mode jsonl --param 'results=[
      {"slug": "<slug>", "verdict": "pass", "failed_criteria": [], "outputs": {...},
       "started_at": "<iso>", "completed_at": "<iso>"},
      {"slug": "<slug>", "verdict": "fail", "failed_criteria": ["<criterion>"]}
@@ -186,15 +188,13 @@ user) changing branches in their own checkouts cannot race them.
 
 ## Step 3: Next wave
 
-If `.gbuild/` isn't ignored, commit the store in the feature worktree: `git -C FT add
-.gbuild/<feature>/db` and `git -C FT commit -m "<feature>: record wave <n>"`. Then claim again (step 2).
-Keep going until a claim returns no rows.
+Claim again (step 2). Keep going until a claim returns no rows.
 
 ## Step 4: Report and stop
 
 ```
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/attention.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/attention.cypher
 ```
 
 Every `progress` row with `open: []` → the graph is done. Otherwise `attention` names what's stuck

package/skills/status/SKILL.md

@@ -3,16 +3,17 @@ description: Reports a gbuild feature's graph — frontier, blocked, in-flight,
 ---
 
 Report status for `$ARGUMENTS`. This skill only reads the store. `DB` below is the feature's store:
-`FT/.gbuild/<feature>/db`, where `FT` is the feature worktree at `<git-common-dir>/gbuild/<feature>/tree`
-(a feature charted before the worktree layout keeps its store at `.gbuild/<feature>/db` in the main
-tree). Status never creates or attaches worktrees — if neither store exists, say the feature's worktree
-is gone and that `git worktree add <git-common-dir>/gbuild/<feature>/tree <branch>` reattaches it.
+`<git-common-dir>/gbuild/<feature>/db`, beside the feature worktree `FT` at
+`<git-common-dir>/gbuild/<feature>/tree` — machine-local, never committed (a gbuild ≤ 0.7.1 store needs the
+move in `reference/cypher.md`). Status never creates or attaches worktrees — if the store is missing,
+the feature is gone (or was never charted here); say so.
 
 ## Store rules
 
 - `cypherlite --version` first. If it's missing, stop: gbuild needs it
   (`curl -sSfL https://neo4j-labs.github.io/cypherlite/install.sh | bash`).
 - One `cypherlite` command at a time — never parallel tool calls on the same store.
+- Always `--read-only`: status never writes, and a missing store fails fast instead of being created.
 - Always `--mode jsonl`: one JSON object per row, no output = no rows.
 - `storage locked` → another process (likely a running `/gbuild:run`) holds the store: wait a few
   seconds, retry up to 3 times, then say so. Anything else: `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md`.
@@ -31,8 +32,8 @@ This is the human-facing report, so it's the one place that reads every node.
 ### 1. Load
 
 ```
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/status.cypher
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/validate.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/status.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/validate.cypher
 ```
 
 One call after the other. `status.cypher` gives one row per node with its derived `state`
@@ -80,11 +81,11 @@ don't let silence be ambiguous between "checked, clear" and "not checked."
 
 ## All-features mode
 
-Don't read every node of every feature. For each store found — `<git-common-dir>/gbuild/*/tree/.gbuild/*/db`,
-plus any legacy `.gbuild/*/db` in the main tree — one store at a time:
+Don't read every node of every feature. For each store found — `<git-common-dir>/gbuild/*/db` — one
+store at a time:
 
 ```
-cypherlite DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
+cypherlite query --read-only --database DB --mode jsonl < ${CLAUDE_PLUGIN_ROOT}/cypher/progress.cypher
 ```
 
 Print one line per feature: slug, node counts by state summed over its waves, and whether it's done

package/templates/example.cypher

@@ -1,7 +1,7 @@
 // A worked 4-node diamond: A produces a value, B and C each consume it
 // independently, D joins both. This is exactly the script plan writes for a
 // new feature — one atomic statement, piped into the store:
-//   cypherlite .gbuild/<slug>/db < plan.cypher
+//   cypherlite query --database <git-common-dir>/gbuild/<slug>/db < plan.cypher
 // Variables (f, a1, a, a_value, ...) are only scoped to this one statement, so
 // the whole graph is created in a single CREATE chain.
 .begin
@@ -54,4 +54,3 @@ CREATE (d)-[:INPUT]->(:Field {name: 'squared', shape: '<integer>'})-[:FROM]->(c_
 CREATE (d)-[:OUTPUT]->(:Field {name: 'sum', shape: '<integer>'})
 CREATE (d)-[:SATISFIES]->(a2);
 .commit
-.checkpoint