Improve agent-oriented Codegraph outputs

README.md

@@ -28,16 +28,17 @@ Use Codegraph when you need fast structural answers about a repo without relying
 - Export graph data as JSON, Mermaid, DOT, or SQLite, then inspect it from scripts or the browser graph viewer app.
 - Keep one workflow across source languages, monorepos, and graph-first document and template formats instead of stitching together separate tools.
 
-For a first pass, run `doctor`, then `orient --root . --budget small --json`.
-Use `inspect`, `search`, `packet get`, `impact`, and `review` as follow-ups when you need deeper architecture, symbol, or change context.
+For a first pass, run `orient --root . --budget small --pretty`.
+Use `packet get`, `search`, `explain`, `impact`, and `review` from the recommended next commands when you need deeper architecture, symbol, or change context.
+For PR, worktree, or sweeping review tasks, start with `review --base HEAD --head WORKTREE --summary` or `impact --base HEAD --head WORKTREE --pretty`.
 Detailed command contracts and JSON shapes live in [docs/cli.md](./docs/cli.md).
 
 ## Features
 
 - Multi-language dependency graphs, including imports, re-exports, `require()`, dynamic imports, workspace resolution, document links, stylesheet imports, and SFC script dependencies.
 - Per-file symbol indexes with locals, exports, docstrings, line spans, and lightweight complexity metadata.
 - Cross-file go-to-definition and find-references support across the shared source-language pipeline.
-- Deterministic agent orientation, packet retrieval, search, bounded explanations, portable artifact bundles, and MCP tools across files, symbols, chunks, SQL objects, graph neighborhoods, and review ranges with stable follow-up handles.
+- Deterministic agent orientation, packet retrieval, search, bounded explanations, portable artifact bundles, and MCP tools across files, symbols, chunks, SQL objects, graph neighborhoods, and review ranges with stable follow-up targets.
 - Semantic chunking for code and text files, including Vue and Svelte single-file component block splitting.
 - Duplicate and near-duplicate detection over indexed symbols, semantic chunks, text chunks, token fingerprints, and AST shape hashes when parser context is available.
 - AST grep, public API summaries, unresolved import reports, hotspot analysis, cycle detection, and shortest dependency paths.
@@ -76,22 +77,22 @@ npm run build
 
 `npm run build` always rebuilds `dist/`. If Cargo is available, it also requires the local native workspace build to succeed; if Cargo is unavailable, it still completes with the JavaScript build output and a warning.
 
-Then start with orientation and follow the returned handles or commands:
+Then start with orientation and follow the returned commands:
 
 ```bash
-# confirm runtime and artifact state
-node ./dist/cli.js doctor
-
 # initial repo orientation with next-step suggestions
-node ./dist/cli.js orient --root . --budget small --json
+node ./dist/cli.js orient --root . --budget small --pretty
+
+# optional runtime and artifact health check
+node ./dist/cli.js doctor
 
 # optional broader architecture summary
 node ./dist/cli.js inspect ./src --limit 20
 
 # find and explain a concrete anchor
-node ./dist/cli.js packet get <handle-from-orient> --json
+node ./dist/cli.js packet get src/cli.ts --pretty
 node ./dist/cli.js search "graph json" --json
-node ./dist/cli.js explain src/cli.ts --json
+node ./dist/cli.js explain src/cli.ts
 
 # build a graph for product code
 node ./dist/cli.js graph --root . ./src --compact-json --output codegraph.json
@@ -122,10 +123,10 @@ Use these as starting points, then see [docs/cli.md](./docs/cli.md) for all flag
 
 ```bash
 # repo orientation and bounded follow-up
-codegraph orient --root . --budget small --json
-codegraph packet get <handle-from-orient> --json
+codegraph orient --root . --budget small --pretty
+codegraph packet get src/cli/graph.ts --pretty
 codegraph search "graph json" --json
-codegraph explain file:src/cli/graph.ts --json
+codegraph explain file:src/cli/graph.ts
 
 # semantic navigation
 codegraph goto <file> <line> <column>

codegraph-skill/codegraph/SKILL.md

@@ -21,15 +21,18 @@ Do not use Codegraph as the only evidence for runtime behavior; pair it with tes
 Start bounded:
 
 ```bash
-codegraph doctor
-codegraph orient --root . --budget small --json
+codegraph orient --root . --budget small --pretty
 ```
 
+Use `doctor` only when install, native-runtime, or artifact health is the task.
+
+For PR, worktree, or sweeping review tasks, start with `codegraph review --base HEAD --head WORKTREE --summary` or `codegraph impact --base HEAD --head WORKTREE --pretty` instead.
+
 Then choose the smallest useful follow-up:
 
-- packet: `codegraph packet get <handle> --json`
+- packet: `codegraph packet get <file|symbol|sql-object|handle> --pretty`
 - search: `codegraph search "auth user" --json`
-- explain: `codegraph explain <file|symbol|handle> --json`
+- explain: `codegraph explain <file|symbol|sql-object|handle>`
 - architecture: `codegraph inspect ./src --limit 20`
 - dependencies: `codegraph deps <file>` or `codegraph rdeps <file>`
 - path: `codegraph path <from> <to>`
@@ -47,11 +50,11 @@ For `orient`, `drift`, and positional graph commands, positional paths are inclu
 ## Output Choice
 
 Use readable output when a human or model will read the result.
-Use JSON when the next step needs exact fields, handles, counts, or filtering.
+Use JSON when the next step needs exact fields, counts, or filtering.
 
 Current high-value surfaces:
 
-- `orient --json`: stable handles and omission counts
+- `orient --pretty`: ranked first-turn focus targets with copyable follow-ups
 - `impact --pretty`: ranked "what could this break?" map
 - `review --summary`: compact reviewer handoff
 - `duplicates --profile cleanup`: refactor ROI ordering

docs/agent-workflows.md

@@ -6,21 +6,23 @@ Use Codegraph for structural repo questions: architecture, dependency direction,
 
 ## Start here
 
-For an unfamiliar repo, keep the first loop bounded:
+For an unfamiliar repo, keep the first loop bounded and actionable:
 
 ```bash
-codegraph doctor
-codegraph orient --root . --budget small --json
-codegraph packet get <handle-from-orient> --json
+codegraph orient --root . --budget small --pretty
+codegraph packet get <file-from-orient> --pretty
 ```
 
+For PR, worktree, or sweeping review tasks, start with `codegraph review --base HEAD --head WORKTREE --summary` or `codegraph impact --base HEAD --head WORKTREE --pretty` instead of orientation.
+
+Use `doctor` only when package/runtime state or an existing artifact path is the question.
 Use `search` when the agent has a query but no handle, `explain` when it already knows a file/symbol/SQL object/handle, and `inspect` for a human-readable architecture summary.
 Use `artifact build` for durable handoff directories and `mcp serve` when repeated follow-up calls should share one warm repo session.
 
 Choose output by the next consumer:
 
 - Use `--pretty` or `--summary` when the next consumer is a person or language model reading the result.
-- Use `--json`, MCP tools, or library APIs when the next step needs exact handles, ranges, schema fields, or filtering.
+- Use `--json`, MCP tools, or library APIs when the next step needs exact fields, ranges, schema fields, or filtering.
 - Do not parse pretty text to recover fields already present in structured output.
 
 For durable repo-local scan scope, add `codegraph.config.json` at the project root. `discovery.ignoreGlobs` keeps large fixture, generated, or vendored folders out of agent search, MCP sessions, graphing, unresolved-import checks, impact, and review unless a command explicitly changes scan scope.
@@ -32,19 +34,19 @@ For raw command flags and output contracts, see [docs/cli.md](./cli.md). For lib
 Start with `orient` when an agent needs compact repo context without flooding the first prompt:
 
 ```bash
-codegraph orient --root . --budget small --json
-codegraph orient --root . ./src --budget medium --pretty
-codegraph packet get file:src%2Fcli.ts --json
-codegraph packet get <handle-from-orient> --max-symbols 25 --json
+codegraph orient --root . --budget small --pretty
+codegraph orient --root . ./src --budget medium --json
+codegraph packet get src/cli.ts --pretty
+codegraph packet get <file-from-orient> --max-symbols 25 --json
 ```
 
-Orientation returns summary bullets, a bounded tree, hotspot modules, budgeted health counts, stable packet handles, omitted counts, and recommended next commands.
-Use `orient --pretty` for compact model-readable triage and `orient --json` when follow-up tools need exact handles or omission counts.
+Orientation returns summary bullets, ranked `focus` targets, a bounded tree, budgeted health counts, omitted counts, and recommended next commands.
+Use `orient --pretty` or MCP `orient` for compact model-readable triage and `orient --json` when follow-up tools need exact focus reasons, limits, or omission counts.
 Small orientation packets default to cheap health analysis; use larger budgets only when cycle, unresolved-import, or duplicate counts matter.
 
 ## Search anchors
 
-Use `search` when an agent has a query but no packet handle and needs a compact starting point before calling `goto`, `refs`, `deps`, `rdeps`, `chunk`, or later explanation tooling:
+Use `search` when an agent has a query but no file target or search handle and needs a compact starting point before calling `goto`, `refs`, `deps`, `rdeps`, `chunk`, or later explanation tooling:
 
 ```bash
 codegraph search "validate user" --json

docs/cli.md

@@ -114,9 +114,9 @@ codegraph index --threads 8 --cache disk
 codegraph index --workers --threads 8 --cache disk
 
 # Search for agent-ready anchors across symbols, paths, chunks, SQL objects, and graph context
-codegraph orient --root . --budget small --json
-codegraph orient --root . ./src --budget medium --pretty
-codegraph packet get <handle-from-orient> --json
+codegraph orient --root . --budget small --pretty
+codegraph orient --root . ./src --budget medium --json
+codegraph packet get src/cli.ts --pretty
 codegraph search "validate user" --json
 codegraph search "public users" --mode sql --json
 codegraph search "handle login" --from src/auth.ts --mode graph --depth 1 --json
@@ -227,10 +227,10 @@ Short JSON shape:
 
 #### Agent orientation and packets
 
-- Use `orient --pretty` as the compact first-turn reading surface for people or models.
-- Use `orient --json` when follow-up tools need exact handles, limits, and omitted counts.
+- Use `orient --pretty` as the compact first-turn reading surface for people or models; it prints the ranked `focus` targets and their follow-up commands before the scope sketch.
+- Use `orient --json` when follow-up tools need exact focus reasons, limits, and omitted counts. Orient suppresses index rebuild warnings so stdout stays parseable.
 - Small orientation budgets default to `--health skip`. Medium and large default to `--health summary`, which counts cycles and unresolved imports while omitting duplicate health; use `--health full` when exhaustive duplicate counts matter.
-- Use `packet get` with file, symbol, chunk, SQL, graph, or review handles to retrieve bounded evidence plus follow-up commands.
+- Use `packet get` with file paths, symbol names, SQL object names, file/symbol/chunk/SQL/graph handles, or review handles to retrieve bounded evidence plus follow-up commands.
 - Agent commands reuse the incremental index path and default to disk cache. Use shared index flags such as `--cache`, `--cache-strict`, `--cache-verify`, `--threads`, `--native`, `--workers`, `--include-glob`, `--ignore-glob`, and `--no-gitignore` when the packet should match a specific scan mode.
 
 `search` is deterministic and vectorless. `explain` resolves file paths, symbol names, SQL object names, and search handles into bounded packets with symbols, graph context, references, snippets, duplicate context, SQL facts, review tasks, candidate tests, limits, omissions, and follow-ups. Use `--max-duplicates` to tune duplicate context in `explain` and `packet get`; duplicate context also uses an internal pair budget and reports skipped duplicate work through omission counts.

docs/library-api.md

@@ -80,7 +80,7 @@ compatibility exports.
 
 ## Agent packets
 
-`orientCodegraph()` returns a compact first-turn packet for an agent, and `getCodegraphPacket()` retrieves bounded evidence by stable handle:
+`orientCodegraph()` returns compact first-turn context for an agent, and `getCodegraphPacket()` retrieves bounded evidence by file path, symbol name, SQL object name, or stable target:
 
 ```ts
 import { getCodegraphPacket, orientCodegraph } from "@lzehrung/codegraph";
@@ -91,18 +91,18 @@ const orientation = await orientCodegraph({
   budget: "small",
 });
 
-const handle = orientation.handles[0]?.handle;
-if (handle) {
+const target = orientation.focus.find((entry) => entry.file);
+if (target?.file) {
   const packet = await getCodegraphPacket({
     root: process.cwd(),
-    handle,
+    target: target.file,
     maxSymbols: 25,
   });
-  console.log(packet.kind, packet.followUps);
+  console.log(target.why, packet.kind, packet.followUps);
 }
 ```
 
-Use orientation before broad search when a caller needs repo context but has no query yet. Packet handles cover files, symbols, chunks, SQL objects, graph neighborhoods, and review ranges.
+Use orientation before broad search when a caller needs repo context but has no query yet. `focus` ranks file targets that should be tried first, with graph-central hotspots ahead of shallow root files. Search and explain still expose stable handles for symbols, chunks, SQL objects, graph neighborhoods, and review ranges.
 Small orientation budgets default to `health: "skip"` and set health fields to `null` while recording the omission. Medium and large default to `health: "summary"`, which counts cycles and unresolved imports while omitting duplicate health. Use `health: "full"` when exhaustive duplicate counts are needed.
 
 ## Agent search
@@ -170,7 +170,7 @@ const handlers = createCodegraphMcpHandlers({
 
 const search = await handlers.search({ query: "auth user", limit: 5 });
 const orient = await handlers.orient({ includeRoots: ["src"], budget: "small" });
-const packet = await handlers.packet_get({ handle: orient.handles[0]!.handle });
+const packet = await handlers.packet_get({ target: orient.focus.find((entry) => entry.file)!.file! });
 const refs = await handlers.refs({ handle: search.results[0]!.handle });
 const rows = await handlers.query_sqlite({ query: "select path from files", limit: 5 });
 console.log(packet.kind, refs.references, rows.rows);

docs/mcp.md

@@ -36,7 +36,7 @@ Use stdio for a client-owned subprocess. Use HTTP for one long-running Codegraph
 The server exposes the same bounded primitives as the CLI and library session layer:
 
 - `orient`: compact first-turn repo context.
-- `packet_get`: bounded evidence packet by stable handle.
+- `packet_get`: bounded evidence packet by file path, symbol name, SQL object name, or stable target.
 - `search`: deterministic ranked search across paths, symbols, chunks, SQL objects, and graph context.
 - `get_file`: bounded project file read.
 - `get_symbol`: resolve a stable search or explain handle.

src/agent.ts

@@ -7,6 +7,7 @@ export type {
   AgentOrientHealthMode,
   AgentOrientRequest,
   AgentOrientResponse,
+  AgentOrientationFocus,
   AgentPacketCommand,
   AgentPacketHandle,
   AgentTreeEntry,