Improve CLI workflows for coding agents

.changeset/tall-owls-check.md

@@ -0,0 +1,6 @@
+---
+"@codegraphy-dev/core": major
+"@codegraphy-dev/plugin-api": minor
+---
+
+Make `codegraphy search` discover exact live source and cached AST Symbols with deterministic natural-phrase File fallback results, add compact task-personalized `codegraphy map` File maps with typed Relationships, add `codegraphy query` overviews with prioritized declarations and Relationships, add safe workspace `settings get/set/unset` commands, reject corrupt persisted settings instead of silently replacing them with defaults, return structured data from `plugins list`, return compact partial results from Graph Scope mutations, keep successful non-verbose Indexing output on stdout only, query complete cached relationship types by default for exact targets, and resolve calls through explicit reexport Relationships to implementation Symbols.

CONTEXT.md

@@ -18,7 +18,7 @@ CodeGraphy turns a folder into an interactive Relationship Graph so people and a
 | **Plugin Node** | A Node contributed by a plugin for a concept that Core does not own. |
 | **Relationship** | A meaningful connection between two Nodes. |
 | **Edge** | A semantic Relationship record with a source, target, and Edge Type. An interface decides how to render it. |
-| **Edge Type** | The semantic category of an Edge, such as import, call, reference, inherit, contains, or nests. |
+| **Edge Type** | The semantic category of an Edge, such as import, reexport, call, reference, inherit, contains, or nests. |
 | **Edge Direction** | The source-to-target direction of a Relationship. The source initiates the import, call, reference, containment, or other relation. |
 | **Dependency** | A Relationship whose Edge Type means one Node needs another to build, run, or resolve. Do not use dependency as a synonym for every Relationship. |
 | **Downstream** | Following Edge Direction away from a Node. The Edge Type explains what the direction means. |
@@ -34,7 +34,7 @@ A **Graph Scope Capability Declaration** tells CodeGraphy which Node Types and E
 CodeGraphy narrows graph data in one order:
 
 ```text
-Relationship Graph -> Scoped Graph -> Filtered Graph -> Searched Graph -> Visible Graph
+Relationship Graph -> Scoped Graph -> Filtered Graph -> Graph View Search -> Searched Graph -> Visible Graph
 ```
 
 | Stage | Meaning |
@@ -43,13 +43,16 @@ Relationship Graph -> Scoped Graph -> Filtered Graph -> Searched Graph -> Visibl
 | **Scoped Graph** | The Relationship Graph after Graph Scope removes disabled types. |
 | **Filter** | Persisted include and exclude rules for recurring workspace noise. |
 | **Filtered Graph** | The Scoped Graph after Filter rules. |
-| **Search** | A temporary text query that narrows the current graph without changing Filter settings. |
-| **Searched Graph** | The Filtered Graph after Search. |
+| **Graph View Search** | A temporary text query that narrows the current graph without changing Filter settings. |
+| **Searched Graph** | The Filtered Graph after Graph View Search. |
+| **CLI Search** | A bounded discovery query over exact live source, cached AST Symbols, and indexed Nodes. Sparse natural multi-term phrases add deterministic all-term File candidates. It reports source and cache provenance and does not change settings. |
+| **Task Map** | A bounded task-personalized File map combining independent live terms, selected declarations, and cached typed Relationships with source-area diversity. |
+| **Target Query** | A bounded overview of one exact File or Symbol Node, including prioritized declarations and incoming/outgoing Relationships. |
 | **Visible Graph** | The graph shown on screen after Graph Scope, Filter, Search, Show Orphans, and other view projection rules. |
 | **Orphan Node** | A Node with no remaining Edges after graph narrowing. |
 | **Show Orphans** | A final Graph View setting that keeps or removes Orphan Nodes. |
 
-Graph Scope runs before Filter, Filter runs before Search, and sorting or pagination runs after those stages. Core Graph Query uses the same order. Show Orphans is a Graph View presentation setting rather than an Indexing or Graph Query input.
+Graph Scope runs before Filter, Filter runs before Graph View Search, and sorting or pagination runs after those stages. Graph Query inventories use that shaped graph. CLI Search, Target Query, Path, and exact targeted Relationship selectors instead read the complete cached Node and Edge Types unless an invocation explicitly projects that dimension with `--node-type` or `--edge-type`; path Filters still apply. This keeps Graph View preferences from hiding indexed call or reexport evidence. Show Orphans is a Graph View presentation setting rather than an Indexing or Graph Query input.
 
 ## Selection, Focus, and Collapse
 
@@ -92,7 +95,7 @@ Interaction rules:
 | **Refresh Graph** | Restart layout physics without processing source data. |
 | **Re-index Workspace** | Run Indexing, save the Graph Cache, and refresh the graph. |
 
-Indexing runs File Discovery, Tree-sitter Analysis, Plugin Analysis, and Graph Projection. The Graph Cache stores unscoped analysis facts so Graph Scope can hide data without deleting it. Active Filters and Git ignored state exclude files from fresh analysis and the file budget; facts cached while those files were eligible remain reusable but stay out of the current graph. Expensive facts such as Symbol or plugin-owned tiers can load when their scope needs them and remain cached for reuse.
+Indexing runs File Discovery, Tree-sitter Analysis, Plugin Analysis, and Graph Projection. JavaScript-family reexports are explicit Relationships; renamed exports are Alias Symbol Nodes, so calls can resolve through barrels to implementation Symbols across full and incremental Indexing. The Graph Cache stores unscoped analysis facts so Graph Scope can hide data without deleting it. Active Filters and Git ignored state exclude files from fresh analysis and the file budget; facts cached while those files were eligible remain reusable but stay out of the current graph. Expensive facts such as Symbol or plugin-owned tiers can load when their scope needs them and remain cached for reuse.
 
 The Graph View can use a whole-view loading state before its first graph payload. Graph Cache Sync, Live Update, plugin changes, and Re-index keep the current graph visible after that first render and use graph-local progress.
 
@@ -105,12 +108,14 @@ The Graph View can use a whole-view loading state before its first graph payload
 | **tldraw Interface** | `@codegraphy-dev/tldraw` owns its launcher, tldraw document lifecycle, native shapes, controls, and adapters over Core and renderer physics. |
 | **Graph Renderer** | `@codegraphy-dev/graph-renderer` owns WebGPU drawing and deterministic WebAssembly physics. It does not own product settings, persistence, or plugins. |
 | **CodeGraphy CLI** | The terminal interface installed by `@codegraphy-dev/core`. It targets the current directory unless `-C, --workspace <path>` selects another workspace. |
-| **Graph Query CLI** | `nodes`, `search`, `edges`, `dependencies`, `dependents`, and `path`, all with bounded JSON output. |
-| **CodeGraphy Agent Skill** | Instructions that teach shell-capable agents when to index, which Graph Query command to choose, and when to inspect source. |
+| **CodeGraphy Exploration CLI** | `search` combines exact evidence with deterministic all-term fallback ranking for natural phrases; `map` builds a compact task-personalized File map; `query` inspects one exact File or Symbol with prioritized declarations and Relationships. All return bounded JSON with provenance. |
+| **CodeGraphy Settings CLI** | `settings`, `settings get`, `settings set`, and `settings unset` read or safely mutate supported workspace settings without silently repairing corrupt persisted input. |
+| **Graph Query CLI** | `nodes`, `edges`, `dependencies`, `dependents`, and `path`, all with bounded JSON output over the shaped Relationship Graph. |
+| **CodeGraphy Agent Skill** | Generalized instructions that explain the Relationship Graph, lifecycle, query surfaces, machine-readable output, freshness, shaping, and limits so a shell-capable agent can choose its own navigation strategy. |
 | **Core Plugin API** | `@codegraphy-dev/plugin-api` contracts for headless Core analysis and semantic graph extensions. |
 | **Extension Plugin API** | `@codegraphy-dev/extension-plugin-api` contracts for VS Code Extension and Graph View extensions. |
 
-The CLI never searches parent directories for a workspace. Indexing and Graph Query are separate operations, so a query does not perform Indexing. Agents run Indexing when their task may have changed cached knowledge, then choose the narrowest query that answers the question.
+The CLI never searches parent directories for a workspace. Indexing and exploration are separate operations, so `search` and `query` never perform Indexing. CLI Search reads source text live from eligible indexed File Nodes and labels cached Symbol provenance as fresh or stale. When Indexing reports a file-budget cap, agents can inspect or raise `maxFiles`, adjust durable filters, and explicitly re-index before querying. Persisted known settings fields are validated strictly; malformed input is reported and never replaced by defaults during mutation. The Agent Skill describes available evidence and its tradeoffs without prescribing a command sequence, call budget, search wording, or stopping rule. The agent chooses how CodeGraphy fits the task. Clean implementation benchmarks compare raw agents with CodeGraphy-plus-skill agents on the same fresh structural feature-change fixture, using three repetitions per condition and cumulative model tokens per correct task as the primary acceptance metric. A CLI candidate must also be selected by treatment agents before aggregate differences can be attributed to it. Personalized Task Map passed a direct adopted A/B after the required raw comparison; see ADR 0011, ADR 0012, and ADR 0013.
 
 ## Plugins
 

README.md

@@ -76,8 +76,11 @@ The terminal CLI supports Node.js 20 through 22. Node 22 LTS is recommended.
 
 ```bash
 npm install -g @codegraphy-dev/core
+codegraphy settings get maxFiles
+codegraphy settings set maxFiles 2500
 codegraphy index
 codegraphy search SettingsPanel
+codegraphy query packages/extension/src/webview/app/shell/view.tsx
 codegraphy dependencies packages/extension/src/webview/app/shell/view.tsx
 ```
 
@@ -123,11 +126,14 @@ All `codegraphy ...` commands are published by `@codegraphy-dev/core`. Data comm
 
 | Command | Result |
 |---|---|
-| `codegraphy status` | Reports fresh, stale, missing, or unusable Graph Cache state. |
+| `codegraphy status` | Reports fresh, stale, or missing Graph Cache state. |
 | `codegraphy doctor` | Checks runtime, settings, Graph Cache schema, integrity, foreign keys, counts, and plugin state. |
-| `codegraphy index` | Makes the selected workspace Graph Cache current. |
+| `codegraphy index` | Makes the Graph Cache current and reports actionable file-budget truncation. |
+| `codegraphy settings [get|set|unset]` | Safely reads or changes validated workspace settings such as `maxFiles`. |
 | `codegraphy nodes` | Lists bounded Nodes from saved Graph Scope. |
-| `codegraphy search <text>` | Searches Nodes. |
+| `codegraphy search <pattern>` | Finds exact evidence and uses deterministic all-term File ranking for sparse natural multi-term phrases. |
+| `codegraphy map <task>` | Builds a compact task-personalized File map with declarations and typed connecting Relationships. |
+| `codegraphy query <node>` | Inspects one exact File or Symbol with prioritized declarations and incoming/outgoing Relationships. |
 | `codegraphy edges` | Lists bounded Edges. |
 | `codegraphy dependencies <node>` | Lists outgoing Relationships for a file or exact Symbol Node. |
 | `codegraphy dependents <node>` | Lists incoming Relationships for a file or exact Symbol Node. |
@@ -136,11 +142,11 @@ All `codegraphy ...` commands are published by `@codegraphy-dev/core`. Data comm
 | `codegraphy filter` | Reads or changes persisted filter patterns. |
 | `codegraphy plugins` | Registers, links, lists, enables, or disables plugins. |
 
-Run `codegraphy <command> --help` for exact arguments. Query, settings, Indexing, and diagnostic commands keep machine-readable JSON on stdout. Verbose diagnostics go to stderr.
+Target Query, Path, and exact targeted Relationship selectors use complete cached Node and Edge Types by default rather than saved Graph View Scope; explicit `--node-type` or `--edge-type` arguments still constrain that dimension. JavaScript-family `reexport` Relationships let calls through barrels terminate at implementation Symbols. Run `codegraphy <command> --help` for exact arguments. Query, settings, Indexing, and diagnostic commands keep machine-readable JSON on stdout. Verbose diagnostics go to stderr.
 
 ### Agent Skill
 
-The [CodeGraphy Agent Skill](./skills/codegraphy/SKILL.md) teaches shell-capable agents to keep the index current and choose a bounded Graph Query before reading source. Install it from a clone of this repo:
+The [CodeGraphy Agent Skill](./skills/codegraphy/SKILL.md) explains the Relationship Graph, lifecycle, query surfaces, JSON output, freshness, shaping, and limits so shell-capable agents can choose their own navigation strategy. Clean coding benchmarks compare fresh raw agents against CodeGraphy-plus-skill agents on the same feature change and use cumulative model tokens per correct task as the primary acceptance metric; see [ADR 0011](./docs/adr/0011-agents-choose-their-codegraphy-strategy.md). Install the skill from a clone of this repo:
 
 ```bash
 npx skills@latest add ./skills/codegraphy

docs/adr/0003-cli-and-agent-skill-replace-mcp.md

@@ -1,6 +1,6 @@
 # CLI and Agent Skill replace MCP
 
-**Status:** Accepted
+**Status:** Accepted; exploration vocabulary amended by ADR 0007
 
 CodeGraphy's agent interface will use the Core-owned `codegraphy` CLI and a distributable Agent Skill. Delete the `@codegraphy-dev/mcp` package and MCP-specific product surface.
 
@@ -14,7 +14,7 @@ CodeGraphy's agent interface will use the Core-owned `codegraphy` CLI and a dist
 
 Add a small positional JSON Graph Query surface to the Core CLI. Expose the extension's persisted Graph Scope, Filter, and plugin controls through the same workspace settings. Make `codegraphy index` reuse and patch compatible persisted cache data. Publish a general `codegraphy` Agent Skill and delete MCP.
 
-The public Graph Query vocabulary is `nodes`, `search`, `edges`, `dependencies`, `dependents`, and `path`. Symbols remain Node Types, and Relationships remain Edges. `nodes`, `search`, `edges`, `dependencies`, and `dependents` use a default limit of 100 and accept `--limit` plus `--offset` for bounded continuation. `path` uses fixed depth and path-count bounds instead of pagination. Commands target the current directory unless the global `-C, --workspace <path>` option selects another CodeGraphy Workspace.
+The original public Graph Query vocabulary was `nodes`, `search`, `edges`, `dependencies`, `dependents`, and `path`. ADR 0007 later deepens `search`, adds executable Target Query, and leaves `nodes`, `edges`, `dependencies`, `dependents`, and `path` as graph navigation commands. Symbols remain Node Types, and Relationships remain Edges. `nodes`, `search`, `edges`, `dependencies`, and `dependents` use a default limit of 100 and accept `--limit` plus `--offset` for bounded continuation. `path` uses fixed depth and path-count bounds instead of pagination. Commands target the current directory unless the global `-C, --workspace <path>` option selects another CodeGraphy Workspace.
 
 Every query accepts repeatable, comma-separated `--filter`, `--node-type`, and `--edge-type` options. These are one-off projections layered over persisted workspace settings for that invocation. A child `--node-type` enables the parent Node Types needed to evaluate Graph Scope. Node Type matching follows the Graph Scope hierarchy and symbol meaning: a parent includes matching descendants, and overlapping types can match the same symbol. Each result keeps its most specific stored `nodeType`. These options do not write `.codegraphy/settings.json`; durable changes still use `codegraphy filter` and `codegraphy scope`.
 

docs/adr/0006-batch-queries-share-one-graph-snapshot.md

@@ -0,0 +1,41 @@
+# Batch queries share one Graph Cache snapshot
+
+**Status:** Superseded by ADR 0007
+
+## Context
+
+Coding agents frequently need several independent Graph Query results at once, such as outgoing and incoming Relationships for a known File Node. Running each existing CLI command separately repeats Node process startup, workspace status checks, settings reads, and Graph Cache hydration.
+
+A two-query benchmark on the TypeScript example workspace measured separate `dependencies` and `dependents` processes at 293.5 ms median and 299.9 ms p95. A batch against one prepared graph snapshot measured 150.9 ms median and 155.9 ms p95. Compact output grew from 683 bytes to 741 bytes, so batching improves latency and round trips rather than response size.
+
+## Decision
+
+Add `codegraphy batch` as a transport over the six existing Graph Query commands. It does not add a Graph Query report or change the public Graph Query vocabulary accepted by ADR 0003.
+
+`batch` reads one bounded JSON document from standard input:
+
+```json
+{
+  "queries": [
+    { "id": "uses", "argv": ["dependencies", "src/app.ts"] },
+    { "id": "used-by", "argv": ["dependents", "src/app.ts"] }
+  ]
+}
+```
+
+Each `argv` uses the existing parser for `nodes`, `search`, `edges`, `dependencies`, `dependents`, or `path`. Existing defaults, bounds, one-off Graph Scope and Filter projections, and selector safety therefore stay on one forward path.
+
+The complete input is validated before Graph Query execution. Query IDs are unique strings. A batch contains 1 through 100 queries and at most 1 MiB of UTF-8 JSON. The public Core batch request enforces the same query-count bound; the byte bound belongs to the stdin transport. The command resolves one CodeGraphy Workspace, reads one Graph Cache snapshot, then applies each query's projection against that snapshot.
+
+Success results preserve input order and include their caller-provided IDs. Failure is all-or-nothing: the CLI returns a failed outer envelope, discards sibling results, and identifies the failed query ID, command, code, and message in `error.details`.
+
+Batch remains read-only. It never performs Indexing, mutates settings, executes non-query commands, refers to an earlier result, or searches parent directories for a workspace. Agents continue to run explicit Indexing when cached knowledge may be outdated.
+
+## Consequences
+
+- Agents can group independent, already-known Graph Queries to reduce process startup and Graph Cache reads.
+- Dependent exploration still uses separate calls: a batch is not a pipeline or query language.
+- Single queries keep their existing commands and result shapes.
+- Batch input costs some additional bytes and its output can be slightly larger than separate envelopes. Agents should use it for latency and round-trip reduction, not assume token savings.
+- Core exposes a batch workspace request that prepares query source data once and projects it independently for every item.
+- A future compound `inspect` operation remains a separate semantic decision. Batch does not justify adding hidden traversal or inference behavior.