# `docs/tools/` — Tool Inventory & Cross-Cut Reports

This directory contains per-tool documentation generated from the live source tree, plus cross-cutting reports that span the full tool surface.

## Files

| File | Purpose | Regeneration |
|---|---|---|
| [INDEX.md](INDEX.md) | Master index of all 107 tools. SHA1-pinned. | `python bin/gen_tool_inventory.py` |
| [CALL_GRAPH.md](CALL_GRAPH.md) | Cross-tool call/import graph. | `python scripts/inventory_graph.py` |
| `<tool_name>.md` | Per-tool documentation, one file per `bin/*.py` or `bin/*.sh`. | Auto-generated by `gen_tool_inventory.py` |
| [ENV_VAR_RECONCILE_REPORT.md](ENV_VAR_RECONCILE_REPORT.md) | **Full inventory of every env var consumed by m3-memory**, reconciled against the tool inventory. Recommends namespacing strategy for the Rust binding crate. | Manual — re-run via subagent against the patterns documented inside. See `~/m3_oxidation_plan.md` §9.6. |

## Cross-cutting reports

### `ENV_VAR_RECONCILE_REPORT.md` (2026-05-14)

Inventories the m3-memory environment-variable surface. After the 2026-05-14 regeneration:
- **77** `M3_*`-prefixed vars in active use (72 original + 5 added; the original report's "73" headline was an off-by-one on a 72-row table, corrected in the regeneration)
- **32** non-prefixed vars (recommended for `M3_*` namespacing under deprecation alias) — not re-swept in the regeneration
- **3** auth/credential vars (intentionally unprefixed; touch FIPS path)

The Rust binding crate (`m3-core-py`) must surface the original `M3_*` vars unchanged for backward compatibility, with typed configs derived from them.

Cross-checked against [INDEX.md](INDEX.md) — **one known gap**: `bin/_task_runtime.py` (reader of `M3_TASK_LOG_FILE`) is not indexed because `gen_tool_inventory.py` skips leading-underscore modules. Every other env-var reader is indexed.

> **Update — Oxidation wiring (regenerated 2026-05-14):** the Rust core is now wired into `bin/memory_core.py`, `bin/chatlog_redaction.py`, and `bin/auto_route.py`. The regeneration added **5 new live `M3_*` vars**: `M3_CORE_RS_DISABLE`, `M3_ROUTE_SHADOW_MODE`, `M3_EMBED_GGUF`, `M3_EMBED_GGUF_MODEL_TAG` (oxidation), plus `M3_TASK_LOG_FILE` (unrelated). The test-only `M3_TEST_GGUF` is excluded (read only by the Rust crate's test). All five are in [ENV_VAR_RECONCILE_REPORT.md](ENV_VAR_RECONCILE_REPORT.md#oxidation-additions-5--added-since-the-original-sweep) and the oxidation vars also in [`docs/ENVIRONMENT_VARIABLES.md`](../ENVIRONMENT_VARIABLES.md). Still owed: a full re-sweep of the non-prefixed + auth groups.

## Regenerating the per-tool docs

The auto-generated `<tool_name>.md` files and `INDEX.md` are produced by:

```
python bin/gen_tool_inventory.py
```

Run this after changing any tool. Entries in `INDEX.md` whose `sha1` no longer matches the live file need re-validation.

## Regenerating the env-var reconcile report

The env-var report is not auto-regenerated (the search patterns are heuristic and need a human-in-the-loop review for new patterns). To refresh it:

1. Re-run the search-pattern sweep documented in the report's "Methodology" section.
2. Cross-check every reader file path against the current [INDEX.md](INDEX.md).
3. Update the conflicts/gotchas section if any new collisions surface.

Trigger conditions for regeneration:
- New env vars added to any tool
- [INDEX.md](INDEX.md) regenerated and adds/removes tools
- A new oxidation-plan phase introduces additional `M3_*` vars
ves tools
- A new oxidation-plan phase introduces additional `M3_*` vars
