tensor-grep-run-and-operate

name

tensor-grep-run-and-operate

description

Use when running the `tg` CLI day-to-day — exact syntax for orient, search --rank, defs/refs/callers/blast-radius, agent, docs-coverage, context, session open/refresh/serve/daemon, checkpoint, scan --ruleset, run, mcp, doctor, dogfood, upgrade; the symbol-command 0/1/2 exit-code contract and what an agent should branch on; bounding a scan with `--deadline` and reading `partial`/`result_incomplete`/`deadline_limit` truncation flags; excluding vendor/skill trees with `--ignore` on orient/agent/docs-coverage; `tg context --max-tokens` budgets (default 16000, 0=opt-out); where JSON artifacts and cache state land on disk; starting the MCP server; or a whole-repo `tg search` that hangs. The OPERATOR runbook (how to invoke), not theory or audit workflow.

tensor-grep run & operate

An imperative, copy-pasteable runbook for running tg (the tensor-grep CLI). Ground-truthed against src/tensor_grep/cli/main.py at released v1.96.0, re-verified 2026-07-24. Every command below is a real @app.command in that file — re-verify with the commands in Provenance and maintenance before trusting a flag on a newer version. main.py churns ~100+ lines per release, so treat every main.py:NNNN cite as an approximate anchor: grep the symbol, don't trust the raw line.

Scope — and when to use a sibling instead

You need	Use
How to type the command / where does output go	this skill
Search theory (BM25, trigram index, ripgrep internals, AST/tree-sitter concepts)	code-search-and-retrieval-reference
The blast-radius-before-editing audit workflow, callers truncation caveats	tensor-grep-code-audit
WHY the front door / registration / backend contract is shaped this way	tensor-grep-architecture-contract
Adding a tg command or search flag; gates before merging any tg change	tensor-grep-change-control
A live bug you just hit while running tg	tensor-grep-debugging-playbook
A hang/--deadline overrun on a large repo, or the unscoped-search-refusal campaign history	tensor-grep-large-repo-scale-campaign
"Has this already been tried and lost?" before re-attempting a fix	tensor-grep-failure-archaeology
Which commands accept --deadline/--ignore/--max-tokens (NOT the same set); env-var/flag axis list	tensor-grep-config-and-flags
Building from source, Rust/Python toolchain setup	tensor-grep-build-and-env
Interpreting doctor/dogfood fields or a result_incomplete/partial/deadline_limit/exit-2 payload — what it PROVES	tensor-grep-diagnostics-and-tooling
Running the pytest/ruff/mypy gates; the exit-code-contract test pattern (tests/unit/test_cli_deadline_flag.py)	tensor-grep-validation-and-qa
Claiming/reading a speed number	tensor-grep-benchmark-and-proof-toolkit
Release mechanics, publish gates, external positioning claims	tensor-grep-release-and-positioning

If you are about to change tg code rather than run it, stop and load tensor-grep-change-control first — this skill assumes the CLI surface as shipped.

0. Confirm you are running the real thing first

Every command below assumes a working, correctly-resolved tg on PATH. Windows in particular can silently resolve a stale or foreign tg (see .claude/skills/tensor-grep/SKILL.md "Start Here"). Before trusting any output:

tg --version
tg doctor --json

tg doctor --json (§8) is the single first check for launcher drift, version mismatch, and Windows shell escaping pitfalls — run it, not tg --version alone, when something looks wrong.

1. Command-anatomy quick table (the moat commands)

All symbol/orientation commands are path-first: tg <command> PATH [SYMBOL|QUERY]. PATH defaults to . (current directory) everywhere below unless noted. Add --json to any of them for machine-readable output (--json is a real per-command flag, not a global one — pass it after the command name).

Command	Positional form	Purpose
tg orient PATH	PATH	One-call codebase orientation: central files by import in-degree, entry points, symbol map, AST snippets
tg search PATTERN PATH --rank	PATTERN PATH	Text search with a real hit re-ranked by BM25 relevance instead of grep order
tg find PATH "query"	PATH QUERY	Whole-repo natural-language hybrid search (BM25 [+ CPU dense] -> RRF -> budget-fitted file:line); v1.77.0, #189
tg defs PATH SYMBOL	PATH SYMBOL	Exact definition locations
tg source PATH SYMBOL	PATH SYMBOL	Full source block for a symbol
tg refs PATH SYMBOL	PATH SYMBOL	References to a symbol
tg callers PATH SYMBOL	PATH SYMBOL	Call sites + likely impacted tests
tg blast-radius PATH SYMBOL	PATH SYMBOL	Callers + transitive file/test impact
tg imports FILE	FILE	Forward file-dependency edges (#74; O(1), no repo scan)
tg importers FILE [ROOT]	FILE [ROOT]	Reverse file-dependency edges (bounded scan; --deadline on large roots)
tg evidence emit PATH	PATH + --capsule/--manifest	Aggregate prior outputs into an EvidenceReceipt
tg codemap PATH	PATH	Browsable folder→file→symbol map (--out; slow — prefer /tmp)
tg map PATH	PATH

2. Orientation and content search

tg orient C:\repo --json
tg orient C:\repo --max-tokens 6000 --max-central-files 15          # widen the capsule
tg orient C:\repo --ignore "vendor/**" --ignore "core/skills/**"    # drop vendor/skill trees from ranking

orient (grep -n "^def orient" src/tensor_grep/cli/main.py -- :9422 as of 2026-08-14, was :8761) takes path (default .), --max-tokens (default 3000, orient's snippet-token budget — not the same axis as context --max-tokens, §14), --max-central-files (default 10), --ignore (repeatable glob), --json.

--ignore GLOB (repeatable) excludes a subtree from the centrality ranking so vendor/skill CODE trees do not outrank real hubs on a harness or monorepo. The glob matches the file basename or the repo-relative path (--ignore 'seo/**' --ignore 'core/skills/**'). Receipt: shipped for orient in #392 after a ~1900-file TS repo dogfood showed a central-skills tree crowding out the real code hubs; the twin flag on tg agent (#397) is below. This is a ranking exclusion, not a scan exclusion — the files are still walked, just kept out of the "central files" / "primary target" list. (Note: tg search --ignore is a different, boolean flag — "respect ignore files" — not this glob; tg docs-coverage --ignore (§13) is a coverage exclusion. See tensor-grep-config-and-flags.)

orient's JSON also carries a suggested_ignore field (orient_capsule.py:1094, _suggested_ignore_from_deweighted_trees) -- ready-to-paste --ignore globs for whatever auto-de-weighted vendor/skill trees it found (de-weight, never hard-exclude, by default). v1.75.0 (#593, "M1+M2") broadened this from narrow nested-manifest islands to whole vendor/skill trees: a new STRONG-0 promotion fires on 5 unambiguous vendor-dir basenames alone (node_modules, vendor, third_party, _vendored, external_repos -- no manifest needed), and a new STRONG-3 shape heuristic detects a whole skills/-named tree whose children look like independent leaf skills with no imports crossing out of the tree (a genuine imported skills/ package stays un-deweighted). M2 in the same PR also added suggested_ignore parity to tg agent --json, which previously never surfaced it at all even though tg agent runs the identical de-weight during ranking -- additive-only, mirroring suggested_scope's convention (present only when non-empty).

tg search "invoice tax" C:\repo --rank --json

--rank (alias --bm25, main.py:7062) re-ranks ripgrep hits by BM25 lexical relevance — pure CPU, no API key, no model download. Default --format for plain search is rg (exact ripgrep-style text); use tg search PATTERN PATH --format rg --json for ripgrep JSON Lines, or --json alone for tensor-grep's own aggregate JSON object, or --ndjson for tensor-grep's flattened streaming rows. These three JSON shapes are not interchangeable — --json is NOT rg's JSON Lines schema (--json/--rank/--ndjson/--format at main.py:7054-7202, in search_command).

tg agent C:\repo "change invoice tax rounding" --json

agent (grep -n "^def agent" src/tensor_grep/cli/main.py -- :10331 as of 2026-08-14, was :9640) is opt-in and takes path then positional query (not --query, which is a hidden deprecated alias, main.py:9341-9468). Key flags: --max-files (3), --max-sources (5), --max-tokens (1200), --max-repo-files (2000, _DEFAULT_AGENT_REPO_SCAN_LIMIT; raised from the old 512 — see §11a's exit-code history below), --provider native|lsp|hybrid, --gpu-device-ids (opt-in native GPU evidence only — sidecar-routed GPU is reported unsupported), and --ignore GLOB (repeatable, main.py:9386) — the same vendor/skill-tree ranking exclusion as orient above, here keeping a vendor/skill tree from being picked as the capsule's primary target on a harness repo (#397). Before editing from a capsule, check top-level ambiguity.status: "tie_requires_confirmation" is a hard stop for autonomous edits.

TG_CAPSULE_INLINE_CALLERS (default-OFF, v1.92.0/#697): prepends # tg: callers=N (top: a, b) to the primary snippet's source and adds an additive snippets[i].inline_structural_annotation field, reusing already-collected blast-radius evidence (no new scan) at a ~+2.8% token cost. See tensor-grep-config-and-flags for the full env-var entry.

2a. One-call edit readiness — tg prepare

tg prepare C:\repo\src "improve session daemon timeout" --json
tg prepare C:\repo\src "task" --claim --json      # also submits an advisory ledger claim
tg prepare C:\repo\src "task" --out capsule.json --json   # persists the capsule to FILE, byte-identical to stdout JSON

prepare (grep -n "^def prepare" src/tensor_grep/cli/main.py -- :11144 as of 2026-08-14, was :10862) composes the orient→search→agent→route-test→callers→evidence→ledger loop into one call: path then positional query, default 60s deadline (DEFAULT_AGENT_CLI_DEADLINE_SECONDS, same class as tg agent's cold-path default), --claim (opt-in only, submits an advisory tg ledger claim), --out FILE (main.py:10562, v1.93.0/#705 — atomic write, refuses a symlink/ dangling-symlink/directory destination, works with --text too). Response carries primary_target + confidence + ask_user_before_editing, validation_commands, a blast_radius_floor (callers_count/top_callers/trust summary), and coordination.claim/coordination.evidence hooks so a caller doesn't have to guess the follow-up argv. A truncated/deadline-partial result reuses the same symbol-command exit contract as §11a below (exit 2 on any partial/result_incomplete, regardless of whether a primary target was found) via _scan_incomplete.

2b. Multi-agent coordination — tg ledger (EXPERIMENTAL, advisory)

tg ledger claim C:\repo --symbol open_session --agent-id "$AGENT_ID" --json
tg ledger list C:\repo --json              # rolls scope UP -- any subtree PATH under the same repo sees it
tg ledger release C:\repo --symbol open_session --agent-id "$AGENT_ID" --json
tg ledger record C:\repo --receipt receipt.json --artifact-kind evidence-receipt --symbol open_session --agent-id "$AGENT_ID" --json
tg ledger find C:\repo --symbol open_session --artifact-kind evidence-receipt --fresh-only --json

Never blocks an edit — a claim is advisory, and overlaps are reported for the caller to decide, not enforced. Slice 1 (claim/release/list -- main.py's ledger_claim/ledger_release/ledger_list) canonicalizes its store to the nearest .git ancestor (worktree-aware; v1.93.0/#706 — before this, each command resolved the store from the literal PATH argument, so claim core/hooks + list . silently used two different stores). Slice 2 (ledger_record -- grep -n "^def ledger_record" src/tensor_grep/cli/main.py, :17510 as of 2026-08-14, was :17323; ledger_find -- grep -n "^def ledger_find" src/tensor_grep/cli/main.py, :17604 as of 2026-08-14, was :17417) got the SAME fix in #850 (v1.101.16): both call _ledger_physical_root, so record core/hooks + find . now hit one store. This line said "unchanged and still literal-path-rooted" for three releases after it stopped being true -- a reader would treat a subtree miss as expected instead of a regression, or avoid Slice 2 entirely. Re-grep the main.py:NNNNN cites; they drift every release. find's exit contract is a distinct 3-state family from §11a's symbol-command contract: 0 = at least one fresh finding (revision matches, safe to reuse); 1 = nothing matched, or matches exist but none are fresh (recompute); 2 = fail-closed (missing --symbol, corrupt index/blob). Full command reference: tensor-grep-ledger.

3. Symbol navigation (defs / source / refs / callers / blast-radius)

tg defs C:\repo open_file --json
tg source C:\repo open_file --json
tg refs C:\repo open_file --json
tg callers C:\repo open_file --json
tg blast-radius C:\repo open_file --json

All five share the same positional contract: path then symbol_arg, both optional Typer arguments (defs (grep -n "^def defs" src/tensor_grep/cli/main.py -- :11924 as of 2026-08-14, was :11475) and blast-radius (grep -n "^def blast_radius" src/tensor_grep/cli/main.py -- :12813 as of 2026-08-14, was :12047)). If you type them reversed (tg defs SYMBOL PATH), the CLI auto-detects it — path that fails Path(path).exists() and a present symbol_arg get swapped, with a warning on stderr — but write path-first to avoid the extra hint round-trip (_maybe_swap_reversed_positionals -- grep -n "^def _maybe_swap_reversed_positionals" src/tensor_grep/cli/main.py, :11795 as of 2026-08-14, was :11346; called from _resolve_path_and_symbol -- grep -n "^def _resolve_path_and_symbol" src/tensor_grep/cli/main.py, :11862 as of 2026-08-14, was :11413). A bare tg defs SYMBOL (single arg) resolves against the current directory.

A hidden --symbol / --query flag still works and prints a deprecation warning to stderr (main.py:11056) — treat it as legacy, not the contract; the positional form is canonical.

Common flags: --provider native|lsp|hybrid (default native), --max-repo-files (2000, _DEFAULT_AGENT_REPO_SCAN_LIMIT — raised from the old 512 the #398→#399 exit-code history below calls out as "the actual friction"), --json. callers/refs/impact/blast-radius also take --deadline SECONDS to wall-clock-bound the scan (§12) — and so do defs/source (plus orient/context/docs-coverage); the #232/#585 waves extended it well past the original graph-commands-only set. Derive it, don't trust this sentence: tg defs --help | grep deadline. (This line read "defs/source do not" until 2026-08-01, while §12's own table listed both as taking it and the pitfall table below explicitly warned against believing a stale "these don't take it" claim — the doc carried its own correction and its own error at the same time. The --deadline option on defs even carries an in-source comment naming the v1.71.3 dogfood fix that added it. A contradiction inside one document is not resolved by whichever half you read first.) blast-radius additionally takes --max-depth (3), --max-callers (25), --max-files (25) (in the blast_radius def, grep -n "^def blast_radius" src/tensor_grep/cli/main.py -- :12813 as of 2026-08-14, was :12047+). defs additionally takes --class TEXT to disambiguate a common method name by its enclosing class (main.py:11128).

Truncation contract (read §11 before scripting an exit code): when a callers/refs/impact/ blast-radius JSON payload carries "result_incomplete": true (a scan cap) or "partial": true (a --deadline cutoff), the scan did not finish — treat the list as a floor, never as proof of zero callers. The exit code encodes this too, and truncation trumps found: main.py:11344-11470 raises typer.Exit(2) on ANY partial/result_incomplete (found OR empty) BEFORE the not-found check, and the comment at main.py:11334-11466 records #399's "found-but-truncated exits 0" as tried and overturned by a unanimous design council (§11). The full audit decision procedure (P2 = truncation, P7 = "zero callers != dead code") lives in tensor-grep-code-audit; this skill covers how to invoke the command and how to branch on its exit/flags.

tg callers is Python-first — prefer tg refs for TS/JS symbol navigation. Call-site resolution matches Python AST call nodes most reliably and can under-match or run for minutes on large TypeScript/JS repos. Dogfood receipt (v1.19.3, AGENTS.md): on a TS-heavy repo, tg refs returned 14 reference sites for a symbol where tg callers returned 1. Prefer tg refs there — and still cross-check with tg scan/grep, because the call graph cannot see set/list/decorator/dispatch-table registration sites, so even a COMPLETE zero-caller result is not proof of dead code.

4. Session lifecycle — open, refresh, serve, daemon

Sessions cache the repo-map so repeated context/edit-plan/blast-radius calls skip re-indexing.

tg session open C:\repo --json                    # returns session_id; capture it
tg session list                                    # sessions for the current root (no ID)
tg session show SESSION_ID
tg session refresh SESSION_ID C:\repo              # after file changes
tg session context-render SESSION_ID C:\repo "query"
tg session edit-plan SESSION_ID C:\repo "query"
tg session blast-radius SESSION_ID C:\repo SYMBOL
tg session serve SESSION_ID C:\repo                # reads JSONL requests from stdin, --jsonl is default-on
tg session daemon start C:\repo --json             # start/reuse the warm localhost daemon
tg session daemon status C:\repo --json
tg session daemon stop C:\repo --json

session open (main.py:12284) takes path (default .) and --max-repo-files (default 512, the agent-safe cap — this literal is unrelated to the agent-family 2000 default in §2/§3, still 512 as of this pass). session refresh (main.py:12477) and every session <subcmd> SESSION_ID [PATH] command require session_id as the first positional argument — it is not implicit. session serve (main.py:13155) additionally accepts --refresh-on-stale to refresh once and retry a request when file changes are detected mid-stream; passing --no-jsonl errors (JSONL is currently the only serve mode, main.py:13173). session context-render / session context accept --max-tokens (default 16000, 0 = unbounded) — see §14.

session daemon start/status/stop (session_daemon_app, main.py:238) each take only PATH — there is no CLI flag for the daemon's idle/uptime limits; those are environment-only: TG_SESSION_DAEMON_IDLE_SECONDS and TG_SESSION_DAEMON_MAX_UPTIME_SECONDS. daemon start prints host:port and pid; daemon status/stop report whether a daemon is currently running for that root. tg session list and tg session daemon status will discover nearby session scopes when the current directory has no direct session metadata of its own.

5. Checkpoints (rewind before a risky rewrite)

tg checkpoint create C:\repo --json
tg checkpoint list C:\repo --json                  # one detected scope
tg checkpoint list C:\repo --discover --json        # bounded child-scope discovery
tg checkpoint list C:\repo --discover-full --json   # exhaustive, can be slow on broad roots
tg checkpoint undo CHECKPOINT_ID C:\repo --json
tg checkpoint undo --last C:\repo --json            # restore the newest checkpoint in scope

checkpoint undo (main.py:13362) takes checkpoint_id as an optional positional, or --last to restore the newest checkpoint for path without naming an ID — do not pass both (main.py:13381/13510). If checkpoint_id resolves to an existing filesystem path, the error message suggests --last explicitly (main.py's checkpoint_undo), which is a strong signal the two positionals (checkpoint_id, path) got confused.

6. AST scan (built-in rule packs) and structural run/rewrite

tg rulesets --json                                          # list built-in packs
tg scan --ruleset RULESET_NAME --path C:\repo\api --json    # narrowest useful root first
tg scan --config sgconfig.yml --json                        # custom ast-grep project config
tg scan --rule my-rule.yml --json                            # single custom rule, no sgconfig

scan (grep -n "^def scan" src/tensor_grep/cli/main.py -- :14533 as of 2026-08-14, was :14000) accepts positional PATHS, or --path (default .) when using a built-in ruleset — the two are mutually exclusive (main.py's scan), as are --rule, --ruleset, and --inline-rules with each other (the same guard in scan). Useful narrowing flags: --glob/-g, --type/-t, --max-depth, --filter/-f (regex over loaded rule IDs). Baseline workflow: --baseline FILE / --write-baseline FILE compare or snapshot matched-finding fingerprints; --suppressions FILE / --write-suppressions FILE mark or record accepted findings (writing suppressions requires --justification TEXT). --allow-broad-generated-scan opts into an otherwise-refused scan of a generated/cache/dependency/multi-project root — prefer scoping first.

--ruleset also accepts a handful of RESOLVE-ONLY 1:1 mental-model aliases on top of the 6 canonical pack names (rule_packs.py's _RULE_PACK_ALIASES): auth->auth-safe, secrets->secrets-basic, crypto->crypto-safe, tls/ssl->tls-safe, subprocess->subprocess-safe, deserialize/deserialization->deserialization-safe. A real pack name always wins over an alias; aliases never appear in tg rulesets/list_rule_packs(). security names the shared category all 6 packs belong to, not one pack, so it raises an actionable error listing the 6 packs instead of guessing.

tg run "function_definition" C:\repo\src --lang python --json
tg run --pattern 'def $NAME($$$ARGS): $$$BODY' --rewrite 'def $NAME($$$ARGS) -> None: $$$BODY' C:\repo --apply --verify

run (grep -n "^def run" src/tensor_grep/cli/main.py -- :17740 as of 2026-08-14, was :17149) takes the AST pattern positionally (or via --pattern/-p) and an optional PATH; supplying only a path that exists with no pattern is a hard error (main.py's run, typer.Exit(2)), not a silent zero-match. --rewrite/-r sets the replacement, --apply writes it, --verify runs tests after applying, --checkpoint wraps the apply in a checkpoint, -U/--update-all is an ast-grep-compatible alias for apply-all (requires --rewrite). Read-only structural-search extras: --selector, --strictness, --stdin, --globs (repeatable, prefix ! to exclude), --filter (text regex over matched nodes), --files-with-matches. PowerShell users must single-quote patterns containing $ captures (e.g. 'def $NAME($$$ARGS): $$$BODY') or PowerShell expands $NAME before tg sees it.

KEY FACT: tg run already IS ast-grep when the sg binary is on PATH -- AstGrepWrapperBackend delegates the pattern to sg run -p <pattern> verbatim (ast_wrapper_backend.py:146), so $NAME/$$$ARGS/--selector/--strictness are already 100% ast-grep-compatible with no translation layer. When sg is absent, a native-shaped pattern (no $) still runs through tg's own tree-sitter AstBackend, but that backend speaks a DIFFERENT query DSL than ast-grep (task #141) -- a $-metavariable pattern is never silently rerouted there (that would silently mistranslate and return wrong matches, worse than an honest empty result). Instead _select_ast_backend_for_pattern raises a fail-closed ConfigurationError, which run_command now catches and reports as a clean Error: ... message + exit 2 (mirroring the Task #166 ConfigurationError handling in main.py's search path), never a raw Python traceback. A zero-match tg run (exit 1, not an error) additionally emits static/heuristic remediation via _emit_ast_run_remediation -- idiom shapes (def $NAME($$$ARGS): $$$BODY, function $NAME($$$) { $$$ }), a tg ast-info pointer, and cheap "no $" / "no --lang" hints -- on stderr for text modes and as an additive "remediation" --json key; this is tg run-only and never fires on tg scan (a 0-finding scan is a clean pass, exit 0).

7. MCP server

tg mcp

Starts a stdio MCP server (FastMCP("tensor-grep"), mcp_server.py:120, anyio.run over _run_mcp_stdio_async -- grep -n "def _run_mcp_stdio_async" src/tensor_grep/cli/mcp_server.py, :7951 as of 2026-08-14, was :7847-7859) — it is meant to be launched by an MCP client (Claude Desktop, an agent harness), not run interactively and left open in a terminal.

Call tg_mcp_capabilities first in any new client/sandbox — it reports which tools work without a standalone native tg binary versus which require one (mcp_server.py:1948).

Representative tool names (58 advertised with the default TG_MCP_LEGACY_TOOLS ON — but the surface was REORGANIZED post-v1.96.0, #98 MCP consolidation Phase-1, verified 2026-08-12: 46 legacy tools (the individual names below) are gated behind TG_MCP_LEGACY_TOOLS (default ON; _legacy_tools_enabled() / _register_legacy_tool in mcp_server.py); 10 task-shaped meta-tools (tg_navigate, tg_impact, tg_query, tg_context, tg_explore, tg_session, tg_scan, tg_audit, tg_checkpoint, tg_rewrite — the _META_MCP_TOOLS tuple) compose the legacy tools by an action selector param and are ALWAYS registered regardless of the flag; plus 2 always-on singletons (tg_mcp_capabilities, tg_classify_logs — _SINGLETON_MCP_TOOLS). 46 + 10 + 2 = 58. Flipping TG_MCP_LEGACY_TOOLS OFF de-advertises the 46 legacy names but keeps the 10 meta + 2 singletons (the meta tools' dispatch bodies call the legacy functions in-process either way). Re-derive the shape with grep -n "_META_MCP_TOOLS\|_SINGLETON_MCP_TOOLS\|def _legacy_tools_enabled" src/tensor_grep/cli/mcp_server.py; the full advertised set below — the legacy individual names first, the 10 meta-tools and tg_classify_logs singleton at the end): tg_search, tg_find (whole-repo hybrid NL search, agent-callable form of tg find, v1.78.0/#189/#627 — see docs/harness_api.md), tg_ast_search, tg_symbol_defs, tg_symbol_source, tg_symbol_refs, tg_symbol_callers, tg_symbol_impact, tg_symbol_blast_radius, tg_symbol_blast_radius_render, tg_symbol_blast_radius_plan, tg_context_pack, tg_context_render, tg_edit_plan, tg_agent_capsule, tg_ruleset_scan, , , , , , , , , , , / / , / / / / / / , , , , / , , , , , , , , , , .

Gap worth knowing: neither tg prepare nor tg ledger has an MCP tool counterpart as of v1.96.0 — both are CLI-only. An agent driving tg over MCP cannot reach the one-call edit-readiness CUJ or the advisory ledger the way a CLI-driven agent can; this is a real surface gap, not an oversight to route around silently.

tg_rewrite_apply refuses free-form lint_cmd/test_cmd (they shell-execute on the host) unless the operator opts in with TG_MCP_ALLOW_VALIDATION_COMMANDS=1, returning code="unsupported_option" otherwise. The primary native rg passthrough now inserts a -- end-of-options sentinel before user/LLM-controlled paths (CWE-88 / the MCP-276 CVE class) — shipped and unit-tested in #370 (rust_core/src/rg_passthrough.rs:574-598, ripgrep_operand_args). It is not solved forever: a second native rg-invocation path is the open follow-up (#49), so any new MCP tool or argv builder that shells out to tg/rg must still insert -- before positionals itself. See AGENTS.md "Security Hardening Patterns" and tensor-grep-debugging-playbook / tensor-grep-change-control before adding a new MCP tool that shells out.

8. Diagnostics and operational health — doctor, dogfood, upgrade, repair-launcher

tg doctor --json                       # full diagnostics, LSP included by default
tg doctor --no-lsp --json              # skip external LSP provider probes
tg doctor C:\repo --config sgconfig.yml --json

doctor (grep -n "^def doctor" src/tensor_grep/cli/main.py -- :15329 as of 2026-08-14, was :14763) takes path (default .), --config (default sgconfig.yml), --with-lsp/--no-lsp (default on), --json. Inspect path_tg_first_launcher_kind, fresh_shell_path_tg_first_launcher_kind, python_subprocess_path_tg_first_launcher_kind, shell_escaping_guidance, and any *_is_foreign field before trusting a Windows timing or routing claim — see .claude/skills/tensor-grep/SKILL.md "Start Here" for the full field list and tensor-grep-diagnostics-and-tooling for interpreting them in depth.

session_daemon.autostart (v1.93.0/#705, A12(b)): when session_daemon.running is false, doctor additively reports why — "on-first-use (not yet warmed)" for a daemon that hasn't been touched yet, or a "disabled (...)" reason string when autostart itself is off — instead of a bare running: false that reads as broken.

tg dogfood --output artifacts/dogfood_readiness.json
tg dogfood --json --root C:\repo --timeout-s 170

dogfood (grep -n "^def dogfood" src/tensor_grep/cli/main.py -- :15059 as of 2026-08-14, was :14493) runs the agent-readiness gate and prints a one-page verdict; it "writes only explicit --output and a sibling readiness report" next to it — it does not write anywhere by default with no --output given (docstring on main.py's dogfood). Flags: --root (default .), --output PATH, --expected-version (defaults to pyproject.toml), --json, --progress auto|always|never (stderr only), --progress-interval-s (30.0), --timeout-s (170.0, the nested agent_readiness.py child budget), --no-shell-probes, --no-wsl-probe. A non-zero exit means at least one readiness check failed — read failed_checks in the verdict before treating a release or a change as safe.

tg upgrade

upgrade (grep -n "^def upgrade" src/tensor_grep/cli/main.py -- :15435 as of 2026-08-14, was :14869) upgrades the installed tensor-grep package to the latest PyPI release. It tries, in order: uv tool install --force first only when the running Python is a uv tool-managed venv (_is_uv_tool_managed_python -- grep -n "^def _is_uv_tool_managed_python" src/tensor_grep/cli/main.py, :15355 as of 2026-08-14, was :14789, detects .../uv/tools/ in sys.executable), then uv pip install --upgrade --refresh-package tensor-grep, then pip install --upgrade --no-cache-dir. This is the source-aware upgrade path shipped to fix a WSL uv-tool install getting stranded at a stale version — see tensor-grep-failure-archaeology for the incident. tg upgrade also verifies the sidecar import/version post-upgrade and schedules a managed native front-door refresh when the sidecar version moved ahead of the native binary.

tg repair-launcher --json
tg repair-launcher --allow-foreign-rename --json     # only for a foreign tg.exe you own

repair-launcher (main.py's repair_launcher, Windows-relevant) removes a verified or self-identifying stale tensor-grep Python Scripts\tg.exe launcher that shadows the managed native front door on PATH. --allow-foreign-rename additionally moves aside a foreign (non-tensor-grep) tg.exe — use it only when you own that binary.

9. Artifact conventions — where state and JSON reports actually land

Location	What lives there	Created by	Tracked in git?
.tensor-grep/sessions/	index.json + per-session repo-map payloads	tg session open	No — /.tensor-grep/ is gitignored (.gitignore:51)
.tensor-grep/checkpoints/	index.json, per-checkpoint metadata.json + snapshot/ tree	tg checkpoint create	No — same .tensor-grep/ ignore rule
.tg_semantic_index/ (or $TG_SEMANTIC_INDEX_DIR)	Experimental semantic (dense) index shards	opt-in semantic-search paths	Not committed; experimental subsystem
artifacts/	--output JSON from tg dogfood, scripts/agent_readiness.py, benchmarks/run_*.py	explicit --output PATH only — nothing is written here by default	No — artifacts/ in .gitignore:61 is gitignored

None of these directories are portable outputs to hand to another agent/process by default — treat them as local cache/scratch. If you need a durable artifact, pass an explicit --output and copy it somewhere tracked (or attach it to a PR) yourself; tg dogfood/benchmark scripts will not do that for you.

sgconfig.yml (used by tg scan --config) is a project-level ast-grep config file, not a tensor-grep cache directory — it lives wherever you point --config, typically the repo root.

10. Unscoped tg search — fail-fast/refuse, not a hang (shipped: #400/v1.40.3, #413/v1.42.0)

tg search PATTERN with no path argument (or --glob X -l without a scoped path) used to walk the whole tree and could burn the full ripgrep-subprocess timeout before returning. That is now shipped, released fail-fast/refuse behavior, not an open hang — four layered guards catch the unscoped case before it reaches a slow walk, plus a wall-clock backstop if all four miss:

1. Vendored-root refusal (_should_refuse_unbounded_vendored_root_scan -- grep -n "^def _should_refuse_unbounded_vendored_root_scan" src/tensor_grep/cli/main.py, :5527 as of 2026-08-14, was :5094) — a root with a top-level node_modules/vendor/external_repos/third_party dir exits 2 instantly (no scan at all) unless --allow-broad-generated-scan opts in.
2. Workspace-root refusal (_should_refuse_unbounded_workspace_root_scan -- grep -n "^def _should_refuse_unbounded_workspace_root_scan" src/tensor_grep/cli/main.py, :5469 as of 2026-08-14, was :5036) — a root with >=3 sibling project directories (a monorepo/workspace parent) is refused the same way.
3. Large single-project-root refusal (_should_refuse_unbounded_large_root_scan -- grep -n "^def _should_refuse_unbounded_large_root_scan" src/tensor_grep/cli/main.py, :5701 as of 2026-08-14, was :5204, #413, dogfood v1.42.0) — closes the remaining gap: a large but non-vendored, non-workspace single-project root (matches neither guard above) refuses instantly via a bounded scandir probe — it checks the already-collected candidate-file count against a 1500-file ceiling (gated identically on --allow-broad-generated-scan/glob-type-depth scope) rather than falling through to the slow per-file Python match loop.
4. Flag-less bootstrap-passthrough refusal (bootstrap._search_paths_include_oversized_implicit_root, bootstrap.py:804, v1.92.3/#702, A9) — closes a DEFAULT-path gap the three guards above never covered: bootstrap._run_rg_passthrough (bootstrap.py:1088, the plain flag-less search front door that runs before main.py's Typer app is ever reached) had no walk ceiling at all until this shipped — natively reproduced, not a WSL artifact. It fires only when paths_defaulted (no explicit PATH given) and the implicit root is over IMPLICIT_SEARCH_WALK_FILE_CEILING = 1500 (now defined in io/scan_limits.py:106, re-exported for backward compat from io/directory_scanner.py:34) — the guards 1-3 above and the Rust all import, so all four doors agree on one ceiling. Exits 2 in ~1.7s (was a silent ~60s timeout before this shipped).

TG_RG_TIMEOUT_SECONDS (default 60.0 seconds, subprocess_policy.py:75, lowered from 600s in #288) remains the ripgrep-subprocess-level backstop for the plain rg-passthrough path, but the five guards above mean an unscoped vendored, workspace, or large root — scoped or not, flag-bearing or flag-less — now fails in well under two seconds; you should rarely see the 60s subprocess timeout actually fire on a repo shaped like this one anymore.

Best practice — still scope to a path (cheaper than even the refusal-probe cost, and the only way to get real results instead of an instant refusal):

tg search "pattern" C:\repo             # ~0.4s
tg search "pattern" --glob "*.py" C:\repo
# Avoid: tg search "pattern" --glob "*.py" -l     (no path -- triggers a refusal or a bounded walk)

Same rule for file listing — prefer a scoped root over tg search --files . --hidden --no-ignore across a large workspace; see .claude/skills/tensor-grep/SKILL.md for the broad-generated-scan guardrail (--allow-broad-generated-scan). Task #390's warm-daemon deadline gap is CLOSED: session_store.WARM_DAEMON_DEFAULT_DEADLINE_SECONDS bounds those requests. Residual deadline overruns are separate findings, not evidence that the daemon path is unbounded. For remaining large-repo campaign history, see tensor-grep-large-repo-scale-campaign.

11. Exit codes — the layered contract (READ THIS before scripting tg)

There is no single 0/1/2 table any more. Exit codes are layered by command family. The old "1 = no match, 2 = error" table is materially misleading for symbol commands — those now use a three-state agent contract where 2 means "incomplete", not "usage error".

11a. Symbol commands — callers / refs / impact / blast-radius / defs / source

A three-state contract (authoritative source: docs/CONTRACTS.md:114; implemented in _emit_symbol_command_result -- grep -n "^def _emit_symbol_command_result" src/tensor_grep/cli/main.py, :11722 as of 2026-08-14, was :11298, and blast-radius's own copy):

Exit	Meaning	What an agent may conclude
0	Complete result you can trust. The scan covered the repo — not truncated.	Use the result as the full answer.
1	Genuine not-found on a COMPLETE scan. The symbol/result truly is absent.	Safe to treat as "absent".
2	INCOMPLETE. The scan was truncated (by --deadline → partial:true, or a --max-repo-files cap → result_incomplete:true), so the result — whether it found things or not — is NOT the full answer.	Do not treat the (possibly partial, possibly empty) list as complete. Read the JSON; retry with a larger --deadline/--max-repo-files, or a narrower PATH, for the full set.

The #398 → #399 → revert history (do not get this wrong): #398 (v1.40.0) shipped exit-2-on-any-truncated result. #399 (v1.40.2) briefly narrowed it to "exit 2 only when the truncated result is ALSO empty" (a found-but-capped result exited 0). A unanimous design council overturned #399 (2026-07-05): truncation trumps found, because a truncated caller-set silently trusted as exhaustive is a wrong-blast-radius/refactor risk, and forking the symbol commands away from tg search's "exit 2 on result_incomplete" convention creates two contradictory contracts. The "every big-repo query exits 2" friction is a default-cap miscalibration (512 at the time) — since fixed: the agent-family --max-repo-files default is now 2000 (_DEFAULT_AGENT_REPO_SCAN_LIMIT, re-verified this pass; see §2/§3), which was the separate fix this note originally deferred, not a reason to fork the contract. The restored, current rule: any partial/result_incomplete → exit 2, regardless of whether results were found:

if payload.get("partial") or payload.get("result_incomplete"):
    raise typer.Exit(2)  # truncated (found OR empty) -> INCOMPLETE, never reads as complete
if not_found:
    raise typer.Exit(1)  # complete + empty -> real not-found
# complete + found -> exit 0

blast-radius follows the same rule with one extra distinction: an output cap (--max-callers/--max-files, which trims a complete analysis for display) stays exit 0 and is flagged callers_truncated/files_truncated; only a scan cap (partial or scan_limit.possibly_truncated) exits 2.

Not every exit-2 cause is budget-remediable — branch on incomplete_reason_class before advising a retry (closed vocabulary, docs/CONTRACTS.md). result_incomplete: true payloads additively carry incomplete_reason_class — a CLOSED vocabulary: "unreadable_path", "scan_limit", "deadline", "timeout", "workspace_root_refused" (re-derive: grep -n "incomplete_reason_class" docs/CONTRACTS.md). "scan_limit"/"deadline"/"timeout" are answered by raising --max-repo-files/--deadline or narrowing scope; "workspace_root_refused" by scoping (--glob/--type/--max-depth/explicit path) or --allow-broad-generated-scan, never by raising a file-cap; and "unreadable_path" is NOT budget-remediable at all — no --deadline/--max-repo-files value makes a permission-denied or missing path readable, so the correct remediation there is to make the path readable or scope the request away from it. Never advise "raise the budget" for an exit-2 payload whose class is "unreadable_path" — or an unrecognized class (fail closed: unknown causes are never budget-remediable). (A hyphenated TWIN vocabulary, scan_limit.truncation_cause = project-files/deadline/unreadable-path, covers tg inventory/tg docs-coverage — same remediability split, deliberately different spelling; do not unify them.)

11b. Search family — tg search / tg run

Mirrors ripgrep's convention: 0 = match, 1 = clean no-match, 2 = usage/argument error (typer.Exit(code=2)) or unhandled error. Do not treat exit 1 from tg search as a failure in a script — check the output/JSON. Scan truncation surfaces as result_incomplete in the JSON payload (this is the "2 = result_incomplete convention" docs/CONTRACTS.md:114 says the symbol contract mirrors), not via a special exit code on a found search.

11c. Other commands

tg docs-coverage --check exits 1 on doc drift (uncovered files, or --stale references) — a CI gate (§13). Plain command/usage/argument errors across the CLI exit 2 (typer.Exit(code=2)); handled runtime errors exit 1.

tg find (v1.77.0, #189) has its own hybrid contract, closer to the symbol-command shape than to plain tg search (main.py:4588-4672, in find): a BackendExecutionError (e.g. a corrupt dense model) is caught at the command boundary and exits 2 (JSON error envelope with code="find_backend_error" under --json, else a tg: ... stderr line) — never a raw traceback. An empty result exits 2 if result_incomplete else 1. A found result that is ALSO result_incomplete (a --deadline/--max-repo-files/internal chunk-cap truncation) prints the ranked partial results then exits 2 — truncation trumps found, same rule as §11a's symbol commands, not §11b's plain search-family convention.

11d. What an agent/script should branch on

$json = tg callers C:\repo QueryEngine --deadline 8 --json
$rc = $LASTEXITCODE
switch ($rc) {
  0 { <# trust it; if $json has result_incomplete/partial, it is a FLOOR -- raise the budget for MORE #> }
  1 { <# genuine not-found on a COMPLETE scan -> safe to treat the symbol as absent #> }
  2 { <# INCOMPLETE (found OR empty -- truncation trumps found) -> do NOT conclude "absent" and do NOT trust a partial list as complete; retry: bigger --deadline / --max-repo-files, or narrower PATH #> }
}

Rule of thumb: branch on the exit code first, then parse the JSON for result_incomplete / partial / deadline_limit when completeness actually matters (e.g. before deciding a symbol has no callers). Interpreting those fields in depth is tensor-grep-diagnostics-and-tooling's territory; the exit-code contract test pattern lives in tensor-grep-validation-and-qa (tests/unit/test_cli_deadline_flag.py).

12. Bounding a scan with --deadline

--deadline SECONDS (float, min=0.1) wall-clock-bounds the underlying repo scan and returns whatever was found so far instead of running unbounded. The table below is a SUBSET, not the full set — it lists 12 of the 21 "--deadline" option sites in main.py (derived 2026-08-12 at base 568065a with grep -c '"--deadline"' src/tensor_grep/cli/main.py; an earlier pass said "on these commands only", which was false even of that pass's own table). Re-derive the full set before trusting it (grep -n '"--deadline"' src/tensor_grep/cli/main.py — tensor-grep-config-and-flags owns the authoritative list):

Command	--deadline line	Notes
tg callers	main.py:11631	bounds the caller-scan traversal (#393)
tg refs	main.py:11524	bounds the reference-file scan
tg impact	main.py:11319	bounds both the impact pass and its caller sub-pass
tg blast-radius	main.py:11962	bounds the graph traversal
tg inventory	main.py:8299	bounds the single-pass walk
tg defs	main.py:11151	bounds the definition scan
tg source	main.py:11252	bounds the source-block scan (was undefined pre-CEO-campaign #232; fixed same wave as docs-coverage/blast-radius-plan)
tg orient	main.py:8492	bounds the orientation scan; no exit-2 contract — a truncated orient still exits 0, surfacing partial/deadline_limit as informational only, never a retry signal
tg context	main.py:8724	bounds the context-pack scan
tg docs-coverage	main.py:8368	bounds the coverage walk
tg agent	main.py:9395	cold path (no running session daemon) defaults to 60s; pass --no-deadline to disable
tg prepare	main.py:10541	same 60s cold-path default as tg agent; reuses the §11a symbol-command exit contract

This list has grown well past the older "graph commands only" framing — a CEO-driven campaign (#232, #585) extended --deadline to source/docs-coverage/blast-radius-plan and several others gained it in earlier waves; re-verify the current set yourself with grep -n '"--deadline"' src/tensor_grep/cli/main.py before trusting this table on a later release — tensor-grep-config-and-flags owns the authoritative list. Exit-code behavior on truncation is NOT uniform across this set: symbol commands (callers/refs/impact/blast-radius/defs/source) and prepare follow §11a's exit-2-on-any-truncation contract; orient/context/docs-coverage do not — check the command's own help text for its specific exit contract before scripting around it.

tg callers C:\big-repo QueryEngine --deadline 8 --json
tg inventory C:\big-repo --deadline 5 --json

What a partial result looks like in --json (the truncation is always flagged; it is never a silent short answer — #394 stamps the honesty flags at payload-assembly time so MCP/*_json consumers see them too, via _mark_result_incomplete, repo_map.py):

• Graph commands (callers/refs/impact/blast-radius) on a deadline cutoff add "partial": true (the one field an agent's parser must check) and a "deadline_limit" object whose stable key is "deadline_exceeded": true; its counter keys are named per command — caller_files_scanned/caller_files_total for callers, reference_files_* for refs, files_* for the context/parse path — telling you how far it got. callers/blast-radius also downgrade "graph_completeness": "partial", and the payload additionally carries "result_incomplete": true + "scan_remediation" (a human-readable "raise the budget" hint).
• tg inventory on a deadline cutoff labels scan_limit.truncation_cause = "deadline"; the file/byte/language counts are a floor, not a total.

Exit interaction (§11): any deadline/cap-truncated symbol result exits 2 — whether or not it found something (council-verified B, 2026-07-05; the found→0 narrowing in #399 was reverted). A script keying on the exit code will correctly treat a truncated result as incomplete; parse partial/result_incomplete in the JSON to decide whether to raise the budget or narrow the PATH.

OPEN caveat (do not oversell --deadline). Each stage honors the deadline in isolation, but the pipeline end-to-end is not reliably bounded on a very large repo yet (task #52, receipt 2026-07-05: tg callers QueryEngine --deadline 10 took ~25s on a 1884-file TS repo because the caller-scan re-parses ~1941 files through the slow regex TS parser; #396 added a re-parse + Path.resolve() cache for a 7.9x win on central symbols but did not fully close it). Separately, daemon-served graph queries (tg session … --daemon, run against the cached session repo-map) are not bounded by the scan deadline at all (#390). Treat --deadline as a best-effort upper-ish bound, not a hard SLA, until those close.

13. tg docs-coverage — find source files no governing doc references

New command (postdates most of the skill library; #358, v1.21.0). It lists source files that no governing doc (CLAUDE.md / README* / AGENTS.md) references — by path or basename. It is deliberately reference-existence only (does a doc mention the file at all?), which is far cheaper and less noisy than the deferred semantic diff-docs (#38, deferred after a real-corpus dogfood produced 20,060 findings / 2,727 false "high" — reference-existence avoids that trap).

docs_coverage (grep -n "^def docs_coverage" src/tensor_grep/cli/main.py -- :9290 as of 2026-08-14, was :8629) takes path (default .) plus:

Flag	Effect
--max-repo-files	walk cap (default 50000)
--ignore GLOB (repeatable, #366)	exclude a stub/vendor group so it stops dragging coverage_pct (matches basename or repo-relative path)
--json	machine-readable payload
--fix (#365)	emit a paste-ready Markdown table (path / size / first line) of undocumented files
--stale (#367)	inverse mode: report governing-doc references to files that no longer exist (with a fictional-path guard)
--check (#368)	exit 1 on drift (uncovered files, or with --stale any stale reference) — the CI doc-drift gate; respects --ignore

Worked example — text output then a CI gate:

tg docs-coverage C:\repo\src
# Docs coverage for C:\repo\src
# source_files=214  covered=190  uncovered=24  coverage=88.8%  docs=3
# Undocumented source files (24):
#   cli/docs_coverage.py
#   ...

tg docs-coverage C:\repo\src --ignore "**/_generated/*" --json   # drop generated stubs from the count

CI doc-drift gate (fails the job when any source file is undocumented):

# .github/workflows/ci.yml — doc-drift gate
- name: docs coverage
  run: tg docs-coverage src --ignore "**/migrations/*" --check

The --json payload carries totals.{source_files, covered, uncovered, coverage_pct, doc_files}, uncovered_files[], applied_ignore[], and scan_limit.{max_files, possibly_truncated, truncation_cause}.

Trap fixed in #371 (round-6 HIGH): the excluded-dir check once matched absolute ancestor path parts, so a checkout living under a directory literally named build/, venv/, or target/ excluded every file → source_files=0 → coverage_pct=100.0, a silent false-green. It now matches the repo-relative path. If an old tg reports 100% coverage with 0 source files, suspect this, not a clean repo. The doc-authoring side of docs-coverage (which doc owns which contract) lives in tensor-grep-docs-and-writing; the flag catalog in tensor-grep-config-and-flags.

14. Context budgets — tg context --max-tokens (and its mirrors)

tg context PATH "query" --max-tokens N returns a ranked context pack for edit planning, bounded by default so it is safe to inject into a prompt. Default 16000, min=0, and 0 = explicit unbounded opt-out (main.py:8717, mirrors repo_map._DEFAULT_CONTEXT_MAX_TOKENS — re-verify the current line with grep -n _DEFAULT_CONTEXT_MAX_TOKENS src/tensor_grep/cli/repo_map.py). The bound exists because an unbounded pack ballooned past 1MB (dogfood v1.19.9).

tg context C:\repo "invoice tax rounding" --json                 # ~16k-token pack (default)
tg context C:\repo "invoice tax rounding" --max-tokens 0 --json  # unbounded (opt-out; can be huge)

The same 16000-default / 0=opt-out budget is enforced on every context surface, so a large pack cannot sneak in through a side door:

Surface	Cap	Receipt
tg context (standalone)	16000, 0=off	main.py:8717
tg context-render / tg session context-render / tg session context (incl. --daemon)	16000, 0=off	mirrored #364; daemon path capped #373 (dogfood 1.27.0: session context --daemon was UNBOUNDED at ~557KB / 384 files)
MCP context tools (tg_context_pack / tg_context_render)	_DEFAULT_MCP_CONTEXT_MAX_TOKENS = 16000, 0/None=off	mcp_server.py:188; added #372 (round-6 HIGH) after #359's CLI cap never reached the MCP surface

Do not conflate this axis with the other --max-tokens flags. orient --max-tokens (default 3000) is a snippet budget for the orientation capsule; agent --max-tokens (default 1200) is the capsule snippet-token budget. Only context/context-render/session context*/MCP context tools use the 16000 pack budget. What the budget proves (vs. what it just bounds) is tensor-grep-diagnostics-and-tooling's territory.

15. Common mistakes

Mistake	Correction
Running tg search PATTERN with no path in a large repo	Always scope to a path (§10) — a vendored/large/workspace root now refuses in <1s (shipped), and the 60s ripgrep-subprocess timeout is only the last-resort backstop, not the primary behavior
Reading tg search --json as ripgrep JSON Lines	It is tensor-grep's own aggregate JSON object; use --format rg --json for rg's JSON Lines schema
Passing SYMBOL PATH (reversed) to defs/refs/callers/blast-radius	Auto-corrected with a stderr warning, but write PATH SYMBOL — the canonical, documented order
Reading a symbol-command exit 2 as "usage/argument error"	On callers/refs/impact/blast-radius it means INCOMPLETE — whether or not anything was found (§11a: truncation trumps found; _emit_symbol_command_result raises Exit(2) on ANY partial/result_incomplete BEFORE the not-found check) — retry with a bigger --deadline/--max-repo-files or narrower PATH, don't abort
Using tg callers for TS/JS symbol navigation	callers is Python-first and can under-match/run long on TS/JS — prefer tg refs there (v1.19.3 receipt: refs 14 vs callers 1), cross-checking with tg scan/grep (§3)
Treating a symbol-command exit 0 as "the complete set"	If the JSON carries result_incomplete/partial, it is a floor — raise the budget for MORE (§11a, §12)
Treating callers=0 / result_incomplete: true as "no callers"	Truncated ≠ dead; widen scope or raise the cap — see tensor-grep-code-audit and §11
Trusting --deadline as a hard end-to-end wall-clock SLA on a huge repo

Provenance and maintenance

Facts here were re-verified 2026-07-24 against released v1.96.0 by reading src/tensor_grep/cli/main.py, mcp_server.py, repo_map.py, orient_capsule.py, docs_coverage.py, subprocess_policy.py, cpu_backend.py, bootstrap.py, io/directory_scanner.py, io/scan_limits.py, ast_wrapper_backend.py, rg_passthrough.rs, and docs/CONTRACTS.md (pyproject.toml = 1.96.0; previously re-verified 2026-07-22 against v1.93.2). Eleven tagged releases separate the two passes (v1.93.3 through v1.96.0 — git tag --sort=-creatordate), most notably the three symbol-graph language additions (v1.94.0/#725 Java, v1.95.0/#724 PHP, v1.96.0/#726 C#) and an optimization wave (v1.93.9/#719, v1.93.10/#723). None of them touch main.py's CLI surface directly, but main.py still drifted non-uniformly by roughly 50 to over 5000 lines depending on region (the defs/source/refs/ callers/blast-radius/run/scan cluster shifted the most, the unscoped-search-refusal guards around line 5000 the least) — every def/flag/error-string citation in §1-§14 was re-grepped and corrected against the new positions; none were spot-checked. Two substantive (not just line-number) corrections came out of this pass:

• The agent-family --max-repo-files default is now 2000, not 512 (_DEFAULT_AGENT_REPO_SCAN_LIMIT, main.py:82; confirmed on agent/context-render/edit-plan/route-test/defs/source/impact/ refs/callers/importers/blast-radius* and their session mirrors). tg session open's own --max-repo-files literal is unaffected and is still 512. This appears to be the fix the §11a "default-cap miscalibration (512), to fix separately" note was waiting on.
• IMPLICIT_SEARCH_WALK_FILE_CEILING moved from a literal in io/directory_scanner.py to io/scan_limits.py:106 (value unchanged at 1500); directory_scanner.py:34 now only re-exports it for backward compatibility, so a citation or grep pinned to the old file alone will miss the definition.

Everything else held steady: the docs/CONTRACTS.md three-state-contract bullet moved 108→114 but its text is unchanged; the MCP tool list and count (58) are unchanged (spot-verified: every name in §7's "representative" list, plus tg_prepare/tg_ledger's continued absence, still resolves); the exit-code contracts, --deadline command set, and artifact directory conventions are unchanged in substance. This pass did not find the "header says v1.91.0 but the MCP count/provenance sections say v1.49.3" self-contradiction a prior audit pass flagged for this file — the version stamps were already internally consistent (all pinned to v1.93.2) before this pass touched them, so that specific claim looks like it was made against a stale copy of this document, not the version in origin/main. The unscoped-tg search hang fix (§10) is shipped and released (#400 in v1.40.3, #413 in v1.42.0, #702/A9 in v1.92.3) — it is no longer an in-flight branch. main.py moves ~100+ lines per release, so re-grep the symbol before trusting a cite:

# Version currently installed / current tag
tg --version --verbose
grep -n "^version" pyproject.toml

# Full, current @app.command surface (compare against SS 1-8 above)
grep -n "@app.command\|@session_app.command\|@session_daemon_app.command\|@checkpoint_app.command\|@review_bundle_app.command" src/tensor_grep/cli/main.py

# Full, current MCP tool surface (compare against SS 7)
# NOTE: `grep -A1 "@mcp.tool" | grep "^def "` is BROKEN -- ripgrep/grep's `-A1` context lines are
# prefixed "NNNN-", not "NNNN:", so `^def ` never matches and this silently returns 0. Count the
# tool FUNCTION DEFINITIONS directly instead (58 as of the 2026-08-12 re-verify = 46 legacy +
# 10 meta + 2 singletons). NOTE this count is NO LONGER "== the @mcp.tool decorator count" as an
# earlier pass claimed: since the #98 consolidation only ~13 bare `@mcp.tool` decorators remain
# (verify: `rg -c "@mcp\.tool" src/tensor_grep/cli/mcp_server.py`) -- the 46 legacy tools register
# via `_register_legacy_tool`'s CONDITIONAL `mcp.tool()` call (gated on TG_MCP_LEGACY_TOOLS), and
# the meta/singletons via explicit registration, so decorator-counting under-counts the surface:
grep -n "^def tg_\|^async def tg_" src/tensor_grep/cli/mcp_server.py | wc -l

# tg prepare / tg ledger still have no MCP tool counterpart? (re-check before citing as a gap)
grep -n "^def tg_prepare\|^def tg_ledger" src/tensor_grep/cli/mcp_server.py

# Symbol-command exit contract (SS 11) -- narrative + implementation
grep -n "three-state agent contract\|Symbol-command exit codes" docs/CONTRACTS.md
grep -n "def _emit_symbol_command_result\|Exit(2)\|Exit(1)" src/tensor_grep/cli/main.py

# Which commands accept --deadline (SS 12) and the partial-payload flags
grep -n '"--deadline"' src/tensor_grep/cli/main.py
grep -n "_mark_result_incomplete\|\"deadline_limit\"\|\"partial\"\|truncation_cause" src/tensor_grep/cli/repo_map.py

# docs-coverage flags (SS 13) and context --max-tokens defaults (SS 14)
grep -n "def docs_coverage\|\"--fix\"\|\"--stale\"\|\"--check\"\|\"--ignore\"" src/tensor_grep/cli/main.py
grep -n "_DEFAULT_CONTEXT_MAX_TOKENS\|_DEFAULT_MCP_CONTEXT_MAX_TOKENS\|16000" src/tensor_grep/cli/main.py src/tensor_grep/cli/mcp_server.py src/tensor_grep/cli/repo_map.py

# --ignore on orient/agent (SS 2) -- repeatable ranking glob, NOT the search boolean
grep -n "def orient\|def agent" src/tensor_grep/cli/main.py

# TG_RG_TIMEOUT_SECONDS default + the 4 unscoped-search refusal guards + the native-walk deadline (SS 10)
grep -n "_configured_positive_float(\"TG_RG_TIMEOUT_SECONDS\"" src/tensor_grep/cli/subprocess_policy.py
grep -n "_should_refuse_unbounded_vendored_root_scan\|_should_refuse_unbounded_workspace_root_scan\|_should_refuse_unbounded_large_root_scan" src/tensor_grep/cli/main.py
grep -n "_search_paths_include_oversized_implicit_root\|_run_rg_passthrough" src/tensor_grep/cli/bootstrap.py
grep -n "IMPLICIT_SEARCH_WALK_FILE_CEILING" src/tensor_grep/io/scan_limits.py src/tensor_grep/io/directory_scanner.py

# tg prepare / tg ledger (SS 2a/2b)
grep -n "^def prepare\|^def _emit_symbol_command_result" src/tensor_grep/cli/main.py
grep -n "@ledger_app.command" src/tensor_grep/cli/main.py
grep -n "compute_native_walk_deadline\|native_walk_deadline_exceeded" src/tensor_grep/backends/cpu_backend.py

# Artifact directory names (compare against SS 9)
grep -n "_TG_DIRNAME\|_SESSIONS_SUBDIR\|_CHECKPOINTS_SUBDIR" src/tensor_grep/cli/session_store.py src/tensor_grep/cli/checkpoint_store.py
grep -n "^artifacts/\|^/\.tensor-grep/" .gitignore

# Registration-completeness gate (if a command/flag was added/removed since this was written)
grep -n "KNOWN_COMMANDS\|PUBLIC_TOP_LEVEL_COMMANDS" src/tensor_grep/cli/commands.py tests/e2e/test_routing_parity.py

Open uncertainties this skill does not resolve: the exact current MCP tool count drifts every release (48 as of v1.78.1 — re-run the grep above, don't trust the stamped number); whether --symbol/--query hidden flags have since been removed (still present and working, with a deprecation warning, at v1.78.1 — re-grep main.py for the deprecation-warning call site, the line number drifts); and the exact set of SEARCH_PYTHON_PASSTHROUGH_FLAGS / _TG_ONLY_SEARCH_FLAGS (that pairing is tensor-grep-config-and-flags' territory, not re-enumerated here).