> ## Documentation Index > Fetch the complete documentation index at: https://graph.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Changelog #### Track review findings as living threads The `github` pack now includes `gh_pr_review_threads` and `gh_pr_thread_sync`, letting plans read and sync GitHub PR review threads. `graph_review_9000` findings are recorded as ongoing review threads rather than one-off comments, so review state stays current across plan runs. #### Changelog docs are generated by graph itself The release changelog page is now published in lockstep with each release, with summaries and migration prompts inferred by a `graph` plan and rendered as themed prose rather than raw commit dumps. The page now reuses changelog snippets instead of embedding duplicate content, and the old shell-script based changelog process has been replaced entirely by graph plans. #### Smoother releases The release script now keeps the docs `release_version` in step with the actual release, and the `changelog_entry` instruction no longer leaks literal template syntax into generated output. ### Added * add gh\_pr\_review\_threads and gh\_pr\_thread\_sync to the github pack * track graph\_review\_9000 findings as living review threads ### Documentation * publish a release changelog page, generated in lockstep with releases * correct the escaping-mechanism comment in cliff-docs.toml * infer a per-release summary and migration prompt via a graph plan * keep inferred summaries MDX-safe * drop the changelog page description and intro line * replace the changelog shell scripts with graph plans * place the migration prompt between summary and commit lists * restyle changelog summaries as themed prose * reference changelog snippets instead of embedding them ### Fixed * release script keeps the docs release\_version in step * keep literal template syntax out of the changelog\_entry instruction #### Run plans from anywhere graph now serves its plans over MCP, so editors, agents, and other MCP clients can run and author plans without touching the terminal. #### Smarter control flow Plans can pause to ask a person for input — and declare what happens when nobody is there — and can narrow a list down before working through it, which keeps automations from tripping over items they can't handle. #### Sharper diff awareness Changed-file listings now say what happened to each file, not just that it changed. #### A cleaner scripting surface Command output is structured and consistent across the CLI; scripts that scraped the old text output should switch to `--json`. Existing plans may need updating. Copy this prompt into your coding agent in the repository that carries your plans: ````markdown theme={null} # Migrate graph plans to v0.10.0 You are upgrading the graph plans in this repository — and, if the user asks, their global library in `~/.config/graph/plans/` — to graph v0.10.0. The release is fully backward compatible: any plan you leave untouched keeps working. But one common composition is *latently broken* and must be migrated wherever it appears, and two workaround patterns can now be simplified. Be conservative: apply only the migrations below; do not restructure unrelated steps. ## Prerequisites - `graph --version` must be ≥ 0.10.0 wherever these plans run. - If plans run in CI from the container image (`ghcr.io/tylerdavis/graph:vX.Y.Z`), the image pin must move to ≥ v0.10.0 **in the same PR** as any plan change that uses the new features — plans load from the repo checkout, but the engine comes from the pinned image, so they must move atomically. Check `.github/workflows/` for pins. ## What v0.10.0 adds (facts to work from) **1. A `filter` control step** — partitions a list by evaluating a gate once per element: ```yaml - id: E2 tool_name: filter input: over: "{{E1.changes}}" # must render to an array where: # per-element; {{item}}/{{index}} in scope value: "{{item.status}}" op: ne # eq|ne|gt|lt|gte|lte|empty|not_empty|contains to: deleted ``` - Exactly one of `where` (logical, zero LLM calls) or `infer` (a yes/no question judged per element — costs one judge call per item; optional `concurrency`, and `model` to pin the verdict model). - Result: `{items: […], count, dropped: […], dropped_count}` — both halves, input order. Empty input or an empty result is a value, not an error. - `filter` is the one control step allowed **inside** `decide`/`map`/`reduce` bodies. There, its own `{{item}}`/`{{index}}` shadow the enclosing body's inside the gate — reference the outer element only in `over`. - A gate referencing a field an element lacks fails the step (plans fail hard). Filter before iterating rather than expecting per-item failures. **2. `builtin__git_changed_files` now returns `changes`** alongside the unchanged `files`/`count`: one object per file — `{path, status, old_path, additions, deletions, binary}` — where `status` is `added|modified|deleted|renamed|copied|type_changed` and `old_path` is set for renames/copies. Rename detection is now pinned on (`-M`): a rename is always a single `renamed` entry for its new path, no longer varying with the machine's `diff.renames` config. ## Migration 1 — REQUIRED: reading changed files at a ref Find every plan where `git_changed_files` output feeds a `map` over `builtin__git_file` (or any tool that reads a path at a ref). Grep for plans containing both `git_changed_files` and `git_file`, and for `over:` referencing `.files`. This composition crashes on any diff containing a deletion (the path no longer exists at `head`). Before: ```yaml - id: E1 tool_name: builtin__git_changed_files input: { base: "{{input.base}}", head: "{{input.head}}", prefix: "" } - id: E4 tool_name: map input: over: "{{E1.files}}" do: tool_name: builtin__git_file input: { path: "{{item}}", ref: "{{input.head}}" } ``` After (insert a filter; note `{{item}}` becomes `{{item.path}}`): ```yaml - id: E1 tool_name: builtin__git_changed_files input: { base: "{{input.base}}", head: "{{input.head}}", prefix: "" } - id: E1b tool_name: filter input: over: "{{E1.changes}}" where: { value: "{{item.status}}", op: ne, to: deleted } - id: E4 tool_name: map input: over: "{{E1b.items}}" do: tool_name: builtin__git_file input: { path: "{{item.path}}", ref: "{{input.head}}" } ``` **Critical companion fix:** if a later prompt/template enumerates the file list and pairs it positionally with the map's results ("numbered to match the contents below"), rebuild that numbered list from the SAME array the map iterates (`{{#E1b.items}}{{@index}}. {{path}}{{/E1b.items}}`) — never from `{{E1.files}}`, which would desynchronize paths from contents. Keep deletions visible by adding a separate overview section iterating `{{#E1.changes}}` (path, status, `+{{additions}}/-{{deletions}}`) so the migration adds context rather than hiding it. ## Migration 2 — RECOMMENDED: retire selection workarounds - **User exec tools that exist only to filter** a prior step's list (jq/grep wrappers, e.g. around `git diff --diff-filter`): replace with a `filter` step over the structured field, and delete the tool if nothing else uses it. - **Whole-list LLM selection** (an `infer` step asked "which of these are X?" returning a subset): replace with `filter` + `infer` asking the question per item. Mind the cost — one judge call per element — and set `concurrency`. Keep whole-list inference only for genuinely cross-item questions (ranking, dedup). - Do NOT soften tools that fail loudly on missing data as a substitute — loud failure on a truly unexpected path is the designed behavior; `filter` exists so plans stop asking for paths that cannot exist. ## Migration 3 — AWARENESS: rename semantics If any plan gates on `count` or pattern-matches `files` in a repo where `diff.renames` was disabled, note that renames now surface as one entry (new path) instead of a delete+add pair. `old_path` on the `renamed` entry carries the origin. ## Verify 1. `graph plan validate ` for every plan you touched — must pass. 2. Where feasible, run the plan against a scratch input in a repo that contains a deletion and a rename (use `GRAPH_STORAGE=memory` and a temp `.graph/config.toml` to keep real state out of the run). 3. Report per plan: what pattern was found, what changed, and validation status. List plans you inspected and deliberately left alone, with the reason. ```` ### Added * add --json to graph tools list * add --json to graph tools show * serve graph's plans and authoring commands over MCP * stream progress and honor cancellation * ask steps — put a question to the user from inside a plan * filter steps — partition a list with a per-item gate * per-file change objects on git\_changed\_files ### Changed * return outcomes from the plan commands instead of printing * convert the remaining commands and make --json uniform ### Documentation * add a plan authoring skill for the CLI commands * point the authoring loop and quickstart at the plan authoring skill * make the authoring skill draft-first * frame the skill around the whole plan lifecycle * document graph as an MCP server * close out the MCP roadmap and point the skill at the server * explain why the draft arm cannot use and\_then ### Fixed * write every plan field in snake\_case, at every depth * remove revision-by-redraft from both authoring surfaces * don't load a project the user never pointed at * honour the documented ask retry budget * serve the control steps from the tool catalog * keep MCP writes inside the server's own config layer #### Ride out provider outages Model entries can declare fallbacks, so a failing provider fails over to the next instead of failing your run. #### Let a step figure it out The new agent step runs a bounded tool-calling loop inside a plan for the parts you cannot script ahead of time — and still returns typed results the rest of the plan can reference. #### More places to plug in GitHub release and log tools, a Slack pack for posting messages, and full plan management from the command line. ### Added * model fallbacks for provider outage failover (#67) * add the agent control step * add gh\_release and git\_log to the github pack * add slack pack with slack\_post\_message * manage plans from the command line ### Changed * lift plan authoring rules into graph-core * draft plans one validated step at a time, always ### Documentation * rework intro/quickstart, add project-setup skill, tidy release asset names (#65) * escape curly braces in template-language frontmatter (#66) * reorganize the docs — plans-first IA, one owner per fact * coherence pass after the reorg — catalog table parity, models links * restructure the workbench page; split the exit-gates opener * generate workbench screenshots from executed sessions * inline Frame embeds — Mintlify snippets don't interpolate props into JSX attributes * place workbench screenshots across the reorganized pages * rewrite quickstart manual setup to mirror the fast path * replace the introduction's plan-run snippet with a workbench hero shot * document the agent control step * document the plan authoring commands * ship an app manifest and a one-click create-app button ### Fixed * show never-run steps as skipped after a fired exit gate * add fallbacks field to the shots harness ModelChoice * close the agent step's validation, path, and boundary gaps * enable the slack pack in the repo-carried config * carry exit codes back to main instead of exiting in place * keep plan list and validate off stdout * stop re-rendering caller-supplied reshape shapes A plan's root node in the workbench now shows its metadata, inputs, and finish up front, alongside a handful of scrolling and selection fixes. ### Added * show plan metadata, input schema, and finish on the root node (#61) ### Fixed * wheel over steps/tool list moves selection (#60) * gh\_pr\_ticket default pattern requires a separator (#62) * wheel scrolls the steps/tool list view (#63) * hide list highlight when selection scrolls out of view (#64) #### Steadier plan drafting Drafts are built incrementally — an outline, then one validated step at a time — and invalid drafts can be edited or repaired instead of discarded. #### Pick the right model per call Prompt tools, inference steps, and gates can each name a model, so cheap checks stay cheap and hard calls get the strong model. #### Sturdier CI reviews The PR-review building blocks grew marker-keyed comments, ticket extraction, and file reading at a ref, and tool resolution is now checked before a plan spends a single step. ### Added * write the built-in system prompts into the config init starter (#44) * steer check plans to explicit exits and list inference to map (#45) * named models selectable from prompt tools and builtin\_\_infer (#46) * marker-keyed PR comments, ticket extraction, and file/grep at a ref (#47) * catalog-aware tool resolution before any step runs (#49) * incremental draft strategy — outline, then one validated step per inference (#50) * edit input\_schema, requires\_servers, and silent finish via update\_metadata (#51) * mouse support — click to focus, switch tabs, select rows, wheel-scroll (#55) * add data pack with builtin\_\_reshape for shape projection (#58) * optional per-gate model override on exit/decide infer (#59) ### Documentation * add graph-github-actions-setup skill for coding agents (#42) ### Fixed * render sub-text and borders with the terminal's dim modifier (#43) * PR reviewer no longer emits absence false positives on truncated diffs (#40) * paste literally, edit invalid drafts, repair bad drafts, fence agent-only tools (#48) * separate outline and drafting phases in workbench trace (#52) * show span start time on the left and duration on the right; surface outline call duration (#53) * order trace chronologically so draft\_plan brackets its phases; fix outline duration origin (#54) * carry failing tool error into aborted run result (#56) * default output\_schema type + reset workbench iteration budget on progress (#57) #### A workbench for plans A dual-pane TUI for drafting and test-running plans: research the project, make precise step-level edits, and watch runs unfold without leaving the terminal. #### Simpler storage Plan and thread state now lives in plain files — nothing to install or run alongside graph. #### Projects carry their setup Config discovery is project-first, so a repository can ship its own graph setup, and step ids can be any descriptive identifier. ### Added * replace LadybugDB with file-based storage (#24) * plan workbench — dual-pane TUI for drafting and test-running plans (#25) * workbench debug logging to \/workbench.log (#28) * workbench step view shows body sub-steps and the finish stage (#30) * workbench read\_file/grep/glob tools for researching the project (#29) * step ids are any unique identifier, not just E-numbers (#31) * workbench tools for precise plan edits: update\_metadata, add\_step, update\_step, delete\_step (#33) * \[prompts] config overrides for the chat prompt and workbench addendum (#37) * project-first config — config init and default search paths target ./.graph (#38) * draft safety, control-step guidance, turn-failure recovery (#36) ### Documentation * cookbook covers a custom bot identity for the CI reviewer (#23) * add @emichy to special thanks (#26) * require worktrees for all coding work in CLAUDE.md (#39) ### Fixed * scrolling reaches wrapped content; PgUp/PgDn is the one scroll binding (#27) * draft saves can no longer overwrite a different plan's file (#32) * section-scoped bare keys are not roots in plan validation (#34) * a broken plan file no longer takes down the whole catalog (#35) #### Branch execution with decide steps Plans can now include `decide` steps that fork execution into `then` and `else` branches based on a gate, letting you author plans with conditional logic instead of separate plans per outcome. The gate keyword for a `decide` step is `if`. #### Iterate over lists with map and reduce `map` and `reduce` steps run a body of steps over each item in a list, so repetitive per-item work no longer needs to be unrolled manually in the plan. #### Inline PR review comments The `pr_review` tool now anchors its findings as inline diff comments on the pull request, rather than only surfacing them elsewhere. ### Added * decide steps fork plan execution into then/else branches (#15) * decide gates read if/then/else — the logical gate keyword is now if (#17) * map and reduce steps iterate a body over a list (#18) * pr\_review anchors findings as inline diff comments (#20) #### Clearer tool listings `graph tools list` now groups related tools together and displays them in a tighter, easier-to-scan layout. ### Added * grouped listing for graph tools list, tighter layout (#14) `graph mcp tools` now groups its output by server, and release publishing is atomic — assets can no longer go missing from a published release. ### Added * group graph mcp tools output by server (#11) ### Documentation * rewrite README, add MIT license (#12) ### Fixed * create releases atomically — assets can't be added after publish (#13) #### Run graph without building it Published container images make graph drop-in for CI and containerized environments, and search extensions are vendored into the binary so nothing needs installing alongside it. #### Built-ins, organized Bundled tools now live under one namespace with a dedicated docs page, and new cookbook sections collect worked examples by solution. ### Added * publish a container image with each release (#4) * vendor lbug fts/vector extensions into the binary (#9) * builtin\_\_ namespace for bundled tool packs, Built-ins docs page (#10) ### Documentation * CI cookbook — the dogfooded plans and workflow, annotated (#7) * cookbook as a section — pages by solution category (#8) #### Bundled tool packs and CI failure annotations `graph` now ships with tool packs included, so plans can call common tools without separate setup. Running plans in GitHub Actions also produces failure annotations, making it easier to spot what went wrong directly in the workflow run. ### Added * bundled tool packs and GitHub Actions failure annotations (#2) ### Fixed * portable version bump in release.sh; align workspace version with v0.2.0 #### End plans early, on purpose Plans can now use exit gates to stop execution with an explicit success or error state, instead of running to the end or failing on an unrelated step. #### Build plans from other plans Plans can now call other plans, so you can compose larger workflows out of smaller, reusable pieces rather than duplicating steps across files. ### Added * exit gates — end a plan early with success or error state * plan composability — plans call plans ### Documentation * bring CLAUDE.md current — composability, exit gates, storage, build story, conventions The first release of graph: author plans — YAML pipelines of tool calls with data flowing between steps — validate them, and run them from the terminal. A built-in agent loop backs `ask` and `chat` for conversational work, tools come from your own definitions or any MCP server, and configuration is layered so a repository can carry its own setup. ### Added * ladybug spike (validated) + layered config crate * clap command tree, tracing, working config show/init/path * provider trait, Anthropic + OpenAI-compat providers, structured output with repair, role router * rmcp manager — stdio + streamable-http transports, lazy connect, tool discovery with namespacing and overrides, ToolRegistry impl * ReAct loop + ask/chat/tools commands * thread persistence + observed-shape cache (phase 3) * unify thread continuation under --thread * strict typed template engine for the \{\{Ex.path}} dialect * plan pipeline — planner/validation/execution/solver with bus-driven replanning * YAML plan docs, plans-as-tools, plan\_and\_execute (phase 4 complete) * JSON input documents for plan run and tools test * nested tool display, pipeline progress, streamed solver * optional solver — plans can render structured output or run silently * backend abstraction — dyn Store everywhere, memory backend * user-defined tools — exec, cypher, and prompt kinds * schema defaults for plan/tool inputs; fmt fixes * codify release process — semver bump, git-cliff changelog, tag-driven binaries * run traces — tools\_used in ask envelope, GRAPH\_EVENTS=jsonl event stream ### Documentation * Mintlify documentation site (25 pages) + CLAUDE.md * point repository URLs at the real remote * fix clone directory in installation * touch content to trigger first build * remove build-trigger scratch line * plans-first framing of core concepts * quickstart — freeze-into-a-plan step * plan-first nav order and README framing; drop unverified heading anchors ### Fixed * shut down servers before runtime teardown; silence child stderr * read the shape cache at each planning attempt * steps\_executed excludes the input root * replace RUSTFLAGS with per-target build.rs link directives ## Related topics - [Built-ins](/tools/builtins.md)