# Tensor Grep Code Audit

> Use tensor-grep (tg) as the default code-audit path — callers/blast-radius/scan/doctor/map for fast AST-aware impact analysis before touching shared code. Carries the per-version CLI-contract re-verify rule.

- Skill: `oimiragieo/tensor-grep-code-audit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oimiragieo/tensor-grep-code-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oimiragieo/tensor-grep-code-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: oimiragieo (https://skillmd.com/u/oimiragieo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oimiragieo/tensor-grep-code-audit

---


# Tensor-Grep Code Audit

> **Authority: `tg --help`**. Verified against **tg 1.76.6** (`tg doctor`).
> tg is a superset of grep/ripgrep: rg-compatible text search **plus** native AST
> search/rewrite, symbol intelligence, persisted query acceleration, optional GPU
> routing, MCP server, and agent context capsules. **Default to `tg` over raw grep/rg**
> for any non-trivial code search or pre-edit audit.

## When to use
- Before editing any shared symbol — run symbol intelligence first (`tg callers`,
  `tg blast-radius`, or `tg impact`).
- At session start / after worktree switch — `tg doctor`.
- For repo orientation on an unfamiliar tree — `tg orient PATH` or `tg map PATH`
  (**scope PATH** on doc-heavy repos; see P10).
- On every `tg` version change — re-verify CLI contract (`tg <subcmd> --help`).
- NOT a substitute for `codebase-audit` (architectural survey).
- NOT needed for single-file edits with no external callers.
- NOT a substitute for **gotcontext.ai MCP** on large blobs, remote URLs, verbose CLI
  output, or PR diffs — use `use-gotcontext` for compression; `tg` for local disk.

## gotcontext.ai vs tg

| Job | Tool |
|-----|------|
| Local symbol intel, pre-edit blast-radius | `tg callers`, `tg blast-radius` |
| Large pasted doc, remote URL, git diff, pytest -v | gotcontext MCP (`use-gotcontext` skill) |
| MCP tools/list bloat | `gc_compress_manifest` (gotcontext plugin) |

The gotcontext MCP is remote and cannot read your local files. Local repo work stays on `tg`.

## Command map (from `tg --help`)

### Text search (rg-compatible subset)
```bash
tg PATTERN [PATH ...]                    # bare pattern → treated as tg search
tg search [OPTIONS] PATTERN [PATH ...] # validated common rg-compatible subset
tg search --format rg --json PATH        # ripgrep JSON Lines events
tg search --json PATH                    # tensor-grep aggregate JSON
```
See `tg search --help` for the current validated flag subset (stable contract in
`docs/CONTRACTS.md` per top-level help). Notes:
- `-e`/`-f` multi-pattern; `-F` fixed-strings; `-s` case-sensitive; `--engine pcre2`
- `--smart-case`, `--hidden`, `--max-depth`, `--text` honored on CPU/sidecar paths
- `--format rg --sort path` for deterministic rg-shaped output
- **GPU search is experimental/opt-in** via `--gpu-device-ids`; CPU/ripgrep is the
  default speed baseline (1.58+ help wording). Current installs often ship the
  **CPU** native front door (`tg-*-amd64-cpu`); with `--gpu-device-ids`, search may
  CPU-fallback (`routing_reason: gpu-auto-fallback-cpu`, `gpu_proof: false`) rather
  than accelerate. To request a CUDA front door: set
  `TENSOR_GREP_NATIVE_FRONTDOOR_FLAVOR=nvidia` then `tg upgrade` (only if an nvidia
  asset is published for that release — CHECKSUMS may be CPU-only). On WSL, doctor /
  `agent --gpu-device-ids` probes can report `failed_probe_path` /
  `native_error_kind: path_not_found` when the Windows native binary cannot see a
  Linux tempfile — not the same as "GPU missing".
- **Broad scans are refused or bounded** unless scoped with paths, `--glob`, `--type`,
  `--max-depth`, or explicit `--allow-broad-generated-scan`. Unscoped whole-repo search
  may **timeout** (~60s default) with an actionable stderr message naming
  `TG_RG_TIMEOUT_SECONDS` / `TG_SUBPROCESS_TIMEOUT_SECONDS` (exit 124) — always pass
  a PATH; `--glob` alone on a large repo may still timeout (use
  `tg search PATTERN PATH/` or `PATH --glob '*.py'`).
  Aggregate `--json` uses `total_matches`, `total_files`, `matched_file_paths`,
  `match_counts_by_file` (1.51+).

### Symbol intelligence — `[PATH] [SYMBOL_ARG]` (PATH defaults to `.`)
```bash
tg defs        [PATH] SYMBOL   # exact definition locations (--class to disambiguate)
tg source      [PATH] SYMBOL   # exact source blocks for a definition
tg refs        [PATH] SYMBOL   # Python-first symbol references
tg callers     [PATH] SYMBOL   # JSON key `callers` (list) + likely tests — not `call_sites`
tg impact      [PATH] SYMBOL   # planning signal: `files`/`tests`/`callers` (+ preferred_command)
tg blast-radius [PATH] SYMBOL --json   # callers + caller_tree + affected_files + score (use --json)
                                     # --mermaid alone: Mermaid graph TD on stdout
                                     # --json --mermaid (1.74.4+): JSON graph + `mermaid` string field
tg blast-radius-render [PATH] SYMBOL   # prose paste-in bundle (not the machine graph)
tg blast-radius-plan   [PATH] SYMBOL --json  # planning bundle, no source snippets (--deadline)
tg imports     FILE --json             # forward file deps for ONE file (O(1), no repo scan)
                                     # 1.71+: resolves sys.path.insert sibling modules
                                     # (provenance: sys-path-insert; per-edge `resolved`
                                     # + top-level `resolved_files`)
tg importers   FILE [ROOT] --json      # reverse file deps (#74 primitive; bounded scan)
                                     # FILE resolves against cwd, NEVER joined onto ROOT
                                     # (dogfood #104 / 1.63+). ROOT is scan boundary only.
                                     # may exit 0 or non-zero when not_found:true — still parse stdout
                                     # 1.71+: finds reverse edges for sys.path-hacked siblings
```
Common options: `--provider native|lsp|hybrid` (default `native` on symbol cmds),
`--max-repo-files N` (default **2000** on most 1.42+ symbol/agent commands; `map`
defaults to **512** — verify per `tg <cmd> --help`), `--json`.
**`--deadline` (1.74.0+):** effectively universal (min **0.1**) across symbol + AI +
coverage cmds — including `defs` / `source` / `refs` / `callers` / `impact` /
`blast-radius` / `blast-radius-plan` / `importers` / `imports` / `inventory` /
`codemap` / `orient` / `map` / `agent` / `edit-plan` / `context` / `context-render` /
`docs-coverage`. Partial JSON may include `partial: true` /
`deadline_limit.deadline_exceeded`; may exit non-zero — still parse stdout.
**`imports --deadline` is a documented NO-OP** (O(1) single-file parse; accepted for
interface parity so agents do not Click-exit-2). Prefer real bounds on scan-backed cmds.
`callers` also exposes `--max-tests N` (default 25) and `--max-tokens N`
(default 16000; `0` = unbounded) on 1.58+.

**Positional contract (1.28+):** `PATH` defaults to `.`. Preferred form is always
**`tg <cmd> PATH SYMBOL`** — scope `PATH` to a subdirectory on large/doc-heavy repos.
Shorthand `tg callers SYMBOL` works (symbol with default root `.`). A lone directory
without a symbol errors (`tg callers core/hooks` → missing symbol).
`--symbol` is **deprecated** (still accepted; warning text updated in 1.35) — pass
SYMBOL as positional: `tg callers SYMBOL` or `tg callers PATH SYMBOL`.

### AI / agent workflows — `[PATH] [QUERY_ARG]`
```bash
tg orient      [PATH]              # one-call orientation capsule (central files, entry points)
                                     # --ignore GLOB (repeatable) hard-excludes vendor/skill trees
                                     # --no-auto-deweight (1.71.3+): auto de-weight of detected
                                     # vendor/skill/generated CODE subtrees is ON by default
                                     # (lowers score only; never excludes — JSON: auto_deweight,
                                     # deweighted_trees). Hard exclude still needs --ignore.
                                     # --deadline
tg map         [PATH]              # deterministic repo map (files/symbols/imports/tests)
                                     # --deadline
tg codemap     [PATH]              # persisted browsable folder→file→symbol map (1.68+)
                                     # --out DIR (default /docs/code-map), --check (freshness),
                                     # --ignore GLOB (repeatable, 1.69+), --deadline, --json
tg inventory   [PATH]              # single-pass inventory (files, bytes, languages)
                                     # --json: totals.files / totals.bytes (not file_count)
                                     # --deadline SECONDS (min 0.1) for partial manifest on huge trees
tg docs-coverage [PATH]            # source files not in CLAUDE.md/README/AGENTS.md
                                     # --ignore GLOB (repeatable), --fix, --stale, --check,
                                     # --deadline (1.74.0+)
tg context     [PATH] "query"      # ranked context pack for edit planning (--deadline)
tg context-render [PATH] "query"   # prompt-ready context bundle (--deadline/--profile)
tg agent       [PATH] "task" --json # actionable capsule: targets, snippets,
                                    # validation_commands, validation_plan,
                                    # suggested_validation_commands, rollback,
                                    # confidence, ambiguity, ask_user_before_editing,
                                    # scan_limit, scan_remediation
                                    # --ignore GLOB (repeatable); --deadline
tg edit-plan   [PATH] "change" --json # machine-readable edit plan +
                                    # validation_commands, validation_plan (1.72.1+),
                                    # suggested_validation_commands,
                                    # confidence + ask_user_before_editing (1.74.0+)
                                    # --deadline; --profile (1.54+)
```
`agent`, `context-render`, and `edit-plan` expose top-level `validation_commands` and
`suggested_validation_commands` (1.42+). Prefer `validation_plan` when present (on both
`agent` and `edit-plan` since 1.72.1+).
Templates may quote `$file` or `{file}` — spawned directly (no shell), so pipes/`&&`
are not interpreted. **1.39+** lexical repo-map retrieval bridges camelCase,
snake_case, and source-term queries (e.g. `readBlockEnabled` → `read_block_enabled`).

**Confidence shape (1.40+):** `agent` / `edit-plan` JSON use
`confidence: {overall: float, downgrade_reasons: [...]}` — read `overall`, not a bare
float. Treat `overall < 0.75` as a hard stop unless `validation_plan` is populated
and `ask_user_before_editing.required` is `false`; inspect `downgrade_reasons` for
token-budget vs wrong-primary signals. **1.61+ / 1.71.3+:** scoped and root `agent`
with a strong `validation_plan` commonly return `overall: 0.9` and empty
`downgrade_reasons`. **1.74.0+:** `edit-plan` also returns structured `confidence`
and `ask_user_before_editing` (same hard-stop rules as `agent`). **Truncation caveat:**
low `--max-repo-files` on `agent` can still yield `overall: 0.9` with downgrades like
`repository scan truncated…` and `ask_user_before_editing.required: true` (hard stop)
plus `suggested_scope` — may exit non-zero; still parse stdout.

**Validation (1.40.4+):** prefer `validation_plan` over bare `validation_commands` when
present — each entry has `{command, scope, runner, confidence, detection, target}`.
`validation_commands` is the flat command list derived from the plan.
`suggested_validation_commands` (1.42+) is a secondary hint list when the primary plan
is empty. **1.51+:** root `agent` on harness repos often populates `validation_plan`
with detected `pytest` commands (`{command, scope, runner, confidence, detection, target}`).
**1.54.6+:** scoped `agent` also populates `validation_plan` (including `scope: symbol`
with `-k` pytest selectors when a matching test exists).
**1.72.1+:** scoped `edit-plan` also populates structured `validation_plan` (same
shape as `agent`) plus flat `validation_commands`. **1.74.0+:** prefer either command
for plan + confidence/`ask_user_before_editing` gates. When `validation_plan` /
`validation_commands` is non-empty, `ask_user_before_editing.required` is often
`false` (1.54.6+) — except under scan truncation. Cross-check `primary_target` before
running suggested tests. `ask_user_before_editing.reasons` may include
`no validation command evidence` when the plan is empty.

**Agent guardrails (1.40.4+):**
- `ambiguity` — tie resolution metadata (`status` e.g. `tie_resolved` /
  `tie_requires_confirmation`, `tied_alternative_targets`, `resolution_evidence`);
  inspect when `requires_confirmation: true`.
- `ask_user_before_editing` — `{required: bool, reasons: [...]}`; treat `required: true`
  as a hard stop before editing.
- `context_consistency`, `omissions`, `route_rationale` (1.54+) — extra ranking/trust
  metadata; read when confidence is downgraded.
- `call_site_evidence` / `related_call_sites` (1.54+) — optional caller context on agent.
- `capsule_kind` / `capsule_schema_version` (1.54+) — capsule envelope versioning.
- `scan_limit` / `scan_remediation` on `agent` (1.47+) — same truncation metadata as
  symbol commands (`max_repo_files`, `scanned_files`, `possibly_truncated`); read
  `scan_remediation` when `possibly_truncated: true`.

**Agent scoping (1.28+):** on harness repos, root `tg orient .` may still rank bundled
skill/vendor scripts as central even with auto-deweight (1.71.3+) — use `--ignore` or
scope PATH for a hard exclude. Root `tg agent` with a specific query often ranks
correctly in 1.42+, but `--ignore` remains the safe default on harness repos:
`tg agent . "task" --ignore 'core/skills/**' --max-files 5`.
**1.71.3+ `suggested_scope`:** when the repo scan truncates, `agent` may return
`suggested_scope: {dirs: [...], confidence: "heuristic"}` (and may cite
`repository scan truncated before ranking completed` in `downgrade_reasons`). **1.72.1
dogfood:** truncation also sets `ask_user_before_editing.required: true` (and may
exit non-zero) even when `confidence.overall` is still `0.9` — treat as hard stop and
re-run scoped / with higher `--max-repo-files`. Field is often `null` when the scan
completes. **1.76.6+ `suggested_ignore`:** root `orient` / root `agent` commonly
emit whole-tree globs such as `["core/skills/**"]` when auto-deweight detects a
skill/vendor island (`deweighted_trees` reasons include `skill-tree-shape`,
`import-island`, `name-prior:skills`). Prefer applying those globs (or pass
`--ignore` yourself). With that in place, `orient .` centrality on this harness
no longer ranks SEO skill scripts first. Scoped PATH or an already-applied
`--ignore` often leaves `suggested_ignore: null`.
`edit-plan` JSON uses `primary_target` / `candidate_edit_targets` (not `targets`).
`source --json` returns `definitions` with line ranges (also `sources` on some
builds; not a separate `source_blocks` array). `refs --json` uses `references`
(+ optional `string_refs`), not `refs`. `callers --json` / `blast-radius --json` use
`callers` (list), not `call_sites`. `impact --json` uses `files` / `tests` /
`callers` (not `impacted_files` / `impacted_tests`).
`agent` also exposes `gpu_acceleration` when `--gpu-device-ids` is set (status
`not_requested` / `failed` / `used`; never trust a CPU-fallback as GPU proof —
require `promotion_claim` / `gpu_proof` evidence).

### AST / structural
```bash
tg scan --config sgconfig.yml      # bounded AST scan
tg test                            # structural rule tests
tg run PATTERN [PATH]              # AST slice + guarded rewrite (tg run --help)
                                   # PowerShell: single-quote patterns with $ captures
tg new                             # create bounded AST workflow project/rule/test
tg ast-info                        # supported AST language identifiers
```

### Safety, audit, checkpoints
```bash
tg checkpoint create|list|undo     # edit checkpoints
tg audit                           # parent: audit-verify | audit-history | audit-diff | review-bundle
tg audit-verify MANIFEST           # verify rewrite audit manifest digest/chain
tg audit-history                   # list audit manifests (newest first)
tg audit-diff                      # semantic diff between two manifests
tg review-bundle                   # create/verify enterprise review bundles
tg dogfood --root PATH --output report.json   # agent-readiness gate (no bare PATH arg)
                                     # --progress auto|always|never, --timeout-s N
tg rulesets                        # built-in security/compliance rule packs
tg classify                        # log classification (local default; CyBERT opt-in)
```

### Ops / infra
```bash
tg doctor [--with-lsp] [PATH]      # system, GPU, cache, daemon, launcher diagnostics
                                     # --with-lsp is DEFAULT; inspect health_status
tg session open PATH               # cached edit-loop session
tg session daemon start PATH       # warm daemon for repeated queries
tg repair-launcher                 # fix Windows launcher shadowing native tg.exe
tg lsp / tg lsp-setup              # structural search LSP + provider install
tg mcp                             # MCP server for AI assistants
tg devices / tg calibrate          # GPU inventory / CPU-vs-GPU crossover
tg upgrade | tg update             # upgrade in place
```

## Workflows (what to run when)

| Goal | Command |
|------|---------|
| "What calls this?" | `tg callers PATH SYMBOL --json` |
| "What breaks if I change this?" | `tg blast-radius PATH SYMBOL --json` |
| Quick impact (files + tests only) | `tg impact PATH SYMBOL --json` — read `preferred_command` |
| "Where is this defined?" | `tg defs PATH SYMBOL --json` |
| "Show me the source" | `tg source PATH SYMBOL --json` |
| "Find all references" | `tg refs PATH SYMBOL --json` |
| "What does this file import?" | `tg imports FILE --json` (single-file, no repo scan) |
| "Who imports this file?" | `tg importers FILE [ROOT] --json` — FILE vs cwd, ROOT = scan bound only |
| Unfamiliar repo, need bearings | `tg orient PATH --json` or `tg map PATH` (scope PATH) |
| Persisted browsable code map | `tg codemap PATH --out DIR --json` then `--check`; harness: `--ignore 'core/skills/**'` |
| Harness repo: exclude skill trees | `tg orient . --ignore 'core/skills/**'` or scope PATH |
| Doc drift (files vs CLAUDE.md) | `tg docs-coverage PATH` |
| Doc drift CI gate | `tg docs-coverage PATH --check` (exit 1 if uncovered) |
| Doc drift fix table | `tg docs-coverage PATH --fix` (paste-ready Markdown) |
| Exclude stub trees from coverage | `tg docs-coverage PATH --ignore 'vendor/**'` (repeatable) |
| Stale doc references | `tg docs-coverage PATH --stale` |
| Before editing, get a capsule | `tg agent PATH "task" --json` — read `validation_plan`, `ask_user_before_editing` |
| Plan an edit with validation | `tg edit-plan PATH "change" --json` — read `validation_plan`, `confidence`, `ask_user_before_editing` (1.74.0+) |
| Text search (prefer over grep) | `tg search PATTERN PATH` (always scope PATH) |
| Session health | `tg doctor` |
| Release / agent-readiness check | `tg dogfood --root PATH --output report.json --json` |
| After risky rewrite | `tg checkpoint create` then `tg audit-verify` |

## P1: CLI contract regression trap

Run `tg <subcmd> --help` per-subcommand on EVERY version change. `rc=0` is insufficient.
Keep a contract test that asserts positional shapes and that live output is trusted.
If `--help` shows `DEPRECATED`, migrate immediately.

## P2: Trust fields — `result_incomplete` and low confidence are hard stops

On any symbol command with `--json`, inspect before proceeding:
- `result_incomplete: true` → truncated; widen `--max-repo-files` and re-run.
- **stderr** may also print `INCOMPLETE RESULT` with the repo-file cap — treat as hard stop
  even if you skipped `--json`.
- `not_found: true` on symbol commands or `importers` → didn't resolve; don't assume
  zero callers/importers. `importers` may exit 0 or non-zero with valid JSON when
  `not_found` — always parse stdout. **1.63+:** `tg importers FILE ROOT` resolves
  `FILE` against cwd (never joins onto `ROOT`); `ROOT` is the scan boundary only.
- `graph_trust_summary.confidence` (blast-radius, 1.45+) — values include `strong`,
  `moderate`, etc. Read the full summary: `evidence_counts.parser_backed`,
  `evidence_counts.heuristic`, `evidence_counts.by_ref_kind`, `provenance`,
  `resolution_gaps_present`, `edge_kind`. `moderate` + `resolution_gaps_present: true`
  warrants caution even on low caller counts.
  `moderate` with `parser_backed > 0` and low caller count may still be actionable;
  `resolution_gaps_present: true` warrants caution.
- `graph_completeness`, `provider_status`, `provider_agreement`, `ranking_quality`.
- `scan_limit.possibly_truncated` / `truncation_cause` — explicit cap metadata (1.28+).
- `partial: true` / `deadline_limit.deadline_exceeded` (1.39+ `--deadline` where
  supported — see command map; min 0.1s) — bounded partial result; command may exit
  non-zero even when JSON is present.
- `confidence.overall` + `downgrade_reasons` on `agent` (1.40+) — require
  `overall >= 0.75` OR a non-empty `validation_plan` with `ask_user_before_editing.required:
  false` before trusting `primary_target`; 1.54.6+ may ship validation at 0.75 with
  `validation-corroborated resolution` in downgrade_reasons; **1.61+** scoped agent
  can reach `0.9` with empty downgrades when validation corroborates.
- `ask_user_before_editing.required: true` on `agent` (1.40.4+) — hard stop; read `reasons`.
  Often `false` when `validation_plan` is populated (1.54.6+).
- `agent.scan_limit.possibly_truncated` (1.47+) — hard stop; read `scan_remediation`.
- `ambiguity.requires_confirmation` or unresolved tie on `agent` (1.40.4+) — confirm
  `primary_target` against `tied_alternative_targets` before editing.

`callers: []` without truncation is still NOT "dead code" (see P7).

## P3: Blast-radius pre-change gate

`tg blast-radius PATH SYMBOL --json` BEFORE editing a shared symbol. Use `--json` for
the machine caller graph — `blast-radius-render` is prose-only, not the graph payload.
Use:
- `blast_radius_score` — headline impact metric
- `callers`, `caller_tree`, `affected_files`, `tests`, `test_matches`
- `graph_trust_summary` — `confidence`, `evidence_counts`, `provenance`,
  `resolution_gaps_present` (1.45+)
- `--mermaid` for a doc-friendly caller graph. **1.74.4+:** `--json --mermaid` keeps
  the machine graph and adds a top-level `mermaid` string (`graph TD …`). `--mermaid`
  alone still prints Mermaid text on stdout (no JSON).
- `blast-radius-plan` when you want the planning shape without source snippets

`tg impact` returns `preferred_command: "blast-radius"` and `trust_level: "planning-signal"`
when caller attribution is needed — follow that guidance.

Thresholds (direct callers / affected files):
- <5 → proceed
- 5–20 → document scope
- >20 or low `graph_trust_summary.confidence` / `confidence.overall` → council / operator sign-off

## P4: Positional order — PATH then SYMBOL (PATH defaults to `.`)

Symbol commands: `tg <cmd> [PATH] [SYMBOL]`. Query commands: `tg <cmd> [PATH] "query"`.

**1.28+:** `tg callers SYMBOL` is valid shorthand (searches from `.`). For large repos,
always prefer **`tg callers PATH SYMBOL`** to avoid repo-file cap truncation.

**Never** rely on deprecated `--symbol`.

## P5: Always scope searches

Broad generated-root / workspace-root scans are **refused or bounded** by default. Always pass
a PATH. Opt-in only with `--allow-broad-generated-scan` when you truly need it.
Start narrow (`tg search PATTERN api/app/`), widen one level on empty results.

## P6: `tg doctor` at session start

Run `tg doctor` after worktree switches. `--with-lsp` is default; provider
availability ≠ navigation proof — read `health_status` / `health_check`.
**GPU note (1.27+ / 1.76.6+):** `search_ready=False` is **expected** while GPU search
is experimental/opt-in — text and AST search are unaffected. Read `tier:`
(`installed` / `usable` / `promotion_proof`) and, on probe failure,
`search_runtime_probe.status` (e.g. `failed_probe_path`) plus
`native_error_kind` (`path_not_found` on WSL tempfile probes). `tg calibrate`
requires a CUDA-enabled front door and now prints how to request
`TENSOR_GREP_NATIVE_FRONTDOOR_FLAVOR=nvidia` + `tg upgrade` (falls back to CPU if
no nvidia asset is published for that release).
**AST cache (1.28+):** cold cache adds ~20–30s first-query latency — run `tg map PATH`
once; doctor shows `ast_cache.exists` and remediation hint.
Warm repeated work: `tg session daemon start PATH` (or just run a symbol query —
autostart will spawn).
**1.58+ / 1.68+ / 1.76.6+:** `TG_SESSION_DAEMON_AUTOSTART` is **default-ON** for
`defs`/`impact`/`refs`/`callers`/`blast-radius` (auto-spawns non-blocking on miss;
first call per root pays cold-start). After warm traffic, `tg doctor` should show
`session_daemon: running` and symbol JSON may include `session_id`,
`daemon_response_cache` (`hit`/`miss`), and `serve_cache`. Cold `doctor` can still
report `running: false` / `stopped` before the first autostart. Set `0`/`false`/`off`
to opt out; forced off under `CI`/`GITHUB_ACTIONS`. Idle shutdown via
`TG_SESSION_DAEMON_IDLE_SECONDS` (default 900). `tg session importers FILE` is the
cached-session zero-reparse reverse-import path.
Index state: `.tensor-grep/` and `_tg_refs/` at workspace root.
**Code map (1.68+):** `tg codemap PATH --out DIR` writes `index.md` + per-folder pages
+ `_coverage.json`; prefer live `callers`/`defs`/`refs` for authoritative current
data — use the map for orientation. `tg codemap PATH --out DIR --check` exits 1 when
stale. **1.69+:** `--ignore GLOB` (repeatable) excludes vendor/skill trees from the
generated pages; `--deadline` returns a partial map instead of running unbounded.

## P7: Zero callers ≠ dead code

AST graph misses string registrations, decorator handlers, dispatch tables,
and some dynamic import fallbacks. Cross-check with `tg refs`, `tg importers FILE`,
or scoped `tg search` before deleting.
`tg imports` / `tg importers` are cheap file-dependency primitives. **1.71+:**
`sys.path.insert` sibling modules often resolve (`provenance: sys-path-insert`,
`external: false`, per-edge `resolved` path + top-level `resolved_files`) and
`importers` can return the reverse edge. Still verify when `resolved` is null /
`not_found: true` — string-keyed registries and getattr dispatch remain blind spots.

## P8: Assert the REAL JSON payload shape

Dogfood real command output in contract tests. The 1.35+ envelope (`schema_version: 1`)
uses `result_incomplete`, `output_limit`, `scan_limit`, `graph_trust_summary`,
`blast_radius_score` — not legacy field names.

## P9: Windows shell escaping

PowerShell double quotes expand `$NAME` before tg sees the pattern — use single
quotes or escape `$`. In `cmd.exe`, quote or caret-escape `|`, `&`, `<`, `>`, `^`.
Run `tg doctor` for `shell_escaping_guidance` tailored to your shell.

## P10: Doc-heavy repos — scope orient/agent/map

Repos with bundled skill/vendor trees (e.g. harness libraries) may still need
PATH/`--ignore` scoping. **1.71.3+:** `orient` auto-deweights detected
vendor/skill/generated CODE subtrees by default (`auto_deweight: true`,
`deweighted_trees` lists path+reasons). **1.76.6+:** deweight often covers the
whole skills tree (`reasons` include `skill-tree-shape`) and both `orient` and
root `agent` emit `suggested_ignore: ["core/skills/**"]` — apply that (or pass
`--ignore 'core/skills/**'`) and centrality on this harness ranks hooks/scripts
first instead of SEO skill packages. Pass `--no-auto-deweight` only when debugging
ranking.
**Hard exclude:** repeatable `--ignore` on `orient` and `agent` (1.39+):
`tg orient . --ignore 'core/skills/**'`, `tg agent . "task" --ignore 'core/skills/**'`.
Still valid: scope to the code subtree — `tg orient core/hooks`, `tg map providers/agy`.
For doc-drift on harness repos, exclude bundled skill trees:
`tg docs-coverage . --ignore 'core/skills/seo/**' --check`.

## Environment overrides (common)

| Var | Purpose |
|-----|---------|
| `TG_FORCE_CPU` | Force CPU routing for search |
| `TG_RG_PATH` | Path to ripgrep executable |
| `TG_SIDECAR_PYTHON` | Python executable for sidecar-backed commands |
| `TG_SIDECAR_TIMEOUT_MS` | Sidecar command timeout |
| `TG_HELP_PROBE_TIMEOUT_MS` | Native `--help` passthrough probe timeout (default 3000) |
| `TG_LSP_PROVIDER` | Override LSP semantic provider mode |
| `TG_RG_TIMEOUT_SECONDS` / `TG_SUBPROCESS_TIMEOUT_SECONDS` | Search/subprocess timeouts |
| `TG_NATIVE_TG_BINARY` | Native front door for Python-backed commands |
| `TG_SESSION_DAEMON_AUTOSTART` | Default-ON warm-daemon for symbol cmds; set `0` to opt out (forced off in CI) |
| `TG_SESSION_DAEMON_IDLE_SECONDS` | Daemon idle shutdown (default 900) |
| `TENSOR_GREP_NATIVE_FRONTDOOR_FLAVOR` | Set `nvidia` to prefer CUDA native front-door assets on `tg upgrade` (CPU fallback if unpublished) |
| `TENSOR_GREP_DEVICE_IDS` | Comma-separated GPU IDs |
| `TENSOR_GREP_CLASSIFY_PROVIDER` | Set `cybert` for CyBERT/Triton classify |
| `TENSOR_GREP_LSP_OPERATION_BUDGET_SECONDS` | LSP provider time budget |
| `TENSOR_GREP_SESSION_RESPONSE_CACHE_MAX_BYTES` | Bound agent-loop session response cache |
| `TG_MCP_ALLOW_VALIDATION_COMMANDS` | Set `1` to let MCP `tg_rewrite_apply` run lint/test cmds |

Full list: `tg --help` → **Environment overrides** section.