Initialise a grove project: create .grove/state.lock, index.md and glossary.md under the project root. Run once per project; every other tool fails until the lock exists, and a second run refuses rather than overwrites. id-stride, id-offset and id-width tune numeric id allocation for new nodes. Returns the initialised .grove path.

Create one node of the given kind and return its assigned id (for example W-12); nothing else is printed. Only kind and title are always required; other fields apply per kind (goals and theme for w, surface or why for y, fitness for g, supersedes for d, targets for q and b) and invalid combinations are rejected on write. To modify an existing node use set or field; to connect nodes use link.

Apply one guarded transition of a scalar attribute on a node: status, cynefin, type, title, fitness_kind, fitness_target, area or requires_coverage. Illegal transitions (a status skip, a work item whose DoR is not met) are rejected with the reason and a pointer to dor; success is silent. For list-valued fields such as ac or evidence use field.

Edit one list-valued field of a node (ac, hypothesis, evidence_strategy, evidence, outcome, goals, surface, and so on): op add appends value, rm removes the entry at the 1-based index given in value, clear empties the field. Success is silent. For scalar attributes use set; for done-work proof on a work item prefer evidence.

Create a directed edge from one node to another with a label: blocks, implements, asks, tests, targets, produces, causes, supersedes or distills. Edges feed the ready, next, path, deps and impact analytics and are checked by invariants, so invalid combinations are rejected; success is silent. To remove an edge use unlink.

Remove one directed edge identified by its from node, label and to node. Refuses when the removal would break graph invariants; success is silent. To create an edge use link.

Append one evidence line to a work item's evidence field: the canonical way to record done-work proof, which dor, gate and distill read. Success is silent. Equivalent to field with field=evidence and op=add, but self-documenting.

Record how much one work item contributes toward one goal: the per-goal delta, where +N advances the goal, 0 is neutral and -N regresses it. Typically set at creation and re-set when scope changes (the last write wins); the deltas surface in dor breakdowns and execution packets. Success is silent; an unknown work item or goal id fails with missing: <id> (exit 5). Use set for scalar attributes and field for list fields; this tool only edits the delta.

Archive a verified goal together with its exclusive subgraph (w, d, q, b, t) by setting their archived flag; archived nodes stay in the lock but leave active views, so this is a soft removal, not a deletion, and hard to reverse. Requires distillation first: a linked Discovery or a null-distill attestation from distill; gate reports whether the goal is due.

Print the distillation worksheet for a verified goal: what its subgraph produced and what should survive in Discoveries before archive. Refuses with the current status when the goal is not verified. Read-only unless null=true, which appends a null-distill attestation to the audit journal; state.lock itself is not mutated. Run this before archive when no Discovery captures the goal.

Regenerate index.md from the current state.lock. Idempotent, safe to re-run and silent on success; most mutating tools already auto-render, so use it after out-of-band edits or when index.md looks stale.

Accept whatever is currently in state.lock and recompute its checksum; confirm=true is required. Last resort when check reports a checksum mismatch after a manual edit or merge: it blesses the file as-is, so inspect the contents first.

List work items in status ready, one line per item (id, title, and a [crit] marker when the item sits on the critical path), critical-path first. Use this for the whole queue; use next when you want a single recommendation, or packet for one item's full context.

Propose the single next work item to execute and return its full execution packet: the same markdown bundle packet produces, prefixed by the skill banner. The start-of-session default; ready shows the whole queue instead, and packet fetches an arbitrary work item.

Full execution packet for one work item as markdown: record, goals and fitness contribution, hypotheses, linked decisions, blocking questions and the outcome of every blocker. Fetch this before starting or resuming any work item; next returns the same bundle only for its single proposal, and show prints the bare record without execution context. cone=true appends multi-hop structural context over blocks edges (cone-depth default 4, cone-max default 50 nodes); deps returns just the blocker ids. An unknown id fails with not found (exit 5).

Transitive predecessors over blocks edges: every node that must finish before the given node can start, returned as one id per line in dependency order. impact is the downstream mirror; path shows the whole critical chain.

Transitive successors over blocks edges: every node the given node blocks from starting, returned as one id per line. deps is the upstream mirror.

Print the critical path: the longest chain of unfinished blocks edges, as one id per line in chain order. Use it to see the current bottleneck end to end; deps and impact cover a single node's neighborhood.

Rank open work items by discovery need in a table (coverage, chi-square, fragility, suggestion). Read-only advisory input for deciding which work item needs a Discovery next; gate is the pass-or-fail check on the project.

Definition-of-Ready breakdown for one work item: one line per conjunct with its current pass or fail and a final result line. Run it before resume to confirm a work item is actually startable; set status=progress consults the same conjuncts.

Dump one node's full record as plain text: kind, status, timestamps, every populated field and incident edges. An unknown id fails with no output (exit code 5). list filters many nodes by kind or status; packet wraps a work item's record in execution context.

List nodes filtered by required kind (g, w, d, q, b, t, y or a), one tab-separated line per node: id, status, title. Optional status and cynefin filters (cynefin = the clear/complicated/complex/chaotic complexity class) narrow the set; when nothing matches, nothing is printed. show dumps one record in full; status summarises the whole project.

Render the whole graph as a fenced mermaid flowchart block: one node per id with status classes and labelled edges. Read-only; deps and impact give a single node's neighborhood.

Verify the state.lock checksum and all structural invariants. Returns ok on success, otherwise the first failing invariant; on a checksum mismatch after a deliberate edit see repair.

One-screen markdown project summary: work in progress, alignment triggers and invariant notes, prefixed by the embedded-skill banner. stats is the historical counterpart; check is pass-or-fail on invariants.

Read-only telemetry computed from the journal and the lock, in metric sections: record and mutation counts, cycle time, DoR first-pass rate, bets, discovery, undo and surprise. status summarises current state instead.

Structural diff of nodes and edges against a git ref (since, default HEAD): grove structures, not text hunks. Requires the project root to be a git repository; outside one it fails with a not a git repository error naming the root. log shows who changed what and when.

Timeline of node and edge timestamps plus raw journal records, newest first, one line each; optional id filter and limit (default 200 rows, 0 for unlimited). stats aggregates the same history into metrics.

Change a node's id and rewrite every reference to it across the graph. Refuses while the old id appears in done-work evidence; success is silent. Journal-recorded, but ids quoted in external documents will dangle.

Adopt this session's token on a progress work item, taking ownership of it: on success the item stays in progress with the session id and timestamp stamped on it (visible as session= in show output) and nothing is printed. Refuses when the item is not in progress. handoff transfers ownership to another session; revert drops the claim and returns the work item to ready.

Transfer ownership of a progress work item to another session token; only the current holder can. resume is how the receiving session picks the item up.

Return a progress work item to ready and clear its session claim (holder or stale claim only); refuses when the item is not in progress. For rolling back graph mutations use undo.

Roll back the last N mutations (steps, default 1) by truncating the journal and replaying it. Destructive to audit history: the undone journal records are gone for good, and success is silent. For session claims use revert instead.

Report whether the project passes the distillation gate: baseline, treewidth delta, work items done since baseline and what would distill (thresholds theta default 0 and n default 5). Appends a gate record to the audit journal but never mutates state.lock; distill is the worksheet and archive is the action.

Move a stale Discovery back to active by paying a fresh anchor: new surface paths and/or provenance ids. Success is silent; the Discovery's new status and revalidation log are visible via show. An unknown id fails with not found (exit 5). To copy a Discovery into another project use promote.

Atomically rename one glossary term in glossary.md and rewrite the Discovery tags that reference it: both halves change together or not at all. Refuses when the term is unknown.

List the project registry, one line per project: name, path and last-opened time. Entries are created and refreshed automatically as grove commands run inside a project; this server is bound to a single root at startup.

Copy a Discovery into another project (registry name or directory) with origin provenance; the copy arrives as proposed and the target project's state is written, unlike revalidate, which refreshes in place.

Print the embedded agent skill (the SKILL.md workflow guide with frontmatter), or install it as a skill directory when install names one. The same content is also readable as the grove://skill resource.