IronAdamant · Nov 5, 2026 · Nov 5, 2026 · Nov 5, 2026 · Nov 5, 2026 · Nov 5, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -2,3 +2,4 @@
 *.sh text eol=lf
 *.bat text eol=crlf
 *.ps1 text eol=crlf
+*.jsonl text eol=lf
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,6 +1,6 @@
 # AGENTS.md
 
-Entry point for any coding agent working in this repository, or using Wikifier on another tree. The day-to-day contract is `skills/run.md` (Agent Protocol v0.7, package 5.1.0). Read that file before substantive work. This file says what is live, what is history, and which rules are easy to miss.
+Entry point for any coding agent working in this repository, or using Wikifier on another tree. The day-to-day contract is `skills/run.md` (Agent Protocol v0.7, package 5.2.0). Read that file before substantive work. This file says what is live, what is history, and which rules are easy to miss.
 
 ## What this program is
 
@@ -26,6 +26,33 @@ Many files: `wikifier record-changes -r "path/or/glob=why" --only <your files> -
 
 Prefer the CLI when the connected MCP server is still `python3 -m wikifier.mcp.server` or `wikifier-mcp`. Those entry points belong to the archived package and the handshake fails. Pass `project_root=` on every MCP call for a tree that is not the server's cwd.
 
+## Choosing groups
+
+You, the agent, choose which Wikifier tool groups a project needs. Add one line for `wikifier` to the `agent-tools` block of the project's AGENTS.md: a fenced code block whose info string is `agent-tools`, in the project root the server uses (`WIKIFIER_PROJECT_ROOT`, else its working directory). The server re-reads the file when it changes and tells the client the tool list changed, so no restart is needed. `WIKIFIER_TOOLS` / `WIKIFIER_DISABLE` in the server's environment override the line, key by key. A mistake in the line is reported as a warning in the `initialize` instructions and the line is ignored.
+
+| Group | What it is for | Turn it off when |
+|---|---|---|
+| `core` | bootstrap, lookups, dependencies, file wikis, `update_maps` | never: always on |
+| `notes` | `record_change` and the journal: why each file changed, handoff reasons | another tool keeps the change notes (for example Trammel notes) and you do not maintain wikis |
+| `health` | `check_changes`, `mark_green`, wiki verification | you only look things up and do not maintain wikis |
+| `map` | import-resolution and barrel diagnostics | you are not debugging the import map (most sessions) |
+| `cycles` | the import-cycle report | you are not untangling dependencies |
+| `status` | repeats of bootstrap: project status, issues, the tool catalogue | almost always |
+
+This repository has no `agent-tools` block, so it keeps every tool for dogfooding. The lines below go inside a block fenced with ```` ```agent-tools ```` in the target project.
+
+One agent maintaining wikis (the usual case):
+
+```text
+wikifier: disable map, cycles, status
+```
+
+Lookups only:
+
+```text
+wikifier: tools core
+```
+
 ## Hard rules
 
 - `Cargo.toml` keeps an empty `[dependencies]` list. Do not add a crates.io crate, a Python package, or a Node module.

diff --git a/AGENTS.md.wiki.md b/AGENTS.md.wiki.md
@@ -2,4 +2,4 @@
 
 **Role:** Entry point for any coding agent in this repository.
 
-It points at `skills/run.md` (protocol v0.7, package 5.1.0) and names the live Rust binary, the daily loop, and the Python-era records kept under `Findings/archive/`. `pip install wikifier` is the archived Python 4.7 package. Map roots stay `src/` and `tests/`. The import scan stays comment-masked regex plus named re-exports. Rust also resolves `crate::`, `self::`, `super::`, root crate names, and `[workspace] members`, so `src/main.rs` and `tests/*.rs` are dependents of the library modules they import. `mark-green` checks Rust `pub` names, impl methods, and trait-impl items.
+It points at `skills/run.md` (protocol v0.7, package 5.2.0) and names the live Rust binary, the daily loop, and the Python-era records kept under `Findings/archive/`. `pip install wikifier` is the archived Python 4.7 package. Map roots stay `src/` and `tests/`. The import scan stays comment-masked regex plus named re-exports. Rust also resolves `crate::`, `self::`, `super::`, root crate names, and `[workspace] members`, so `src/main.rs` and `tests/*.rs` are dependents of the library modules they import. `mark-green` checks Rust `pub` names, impl methods, and trait-impl items. A "Choosing groups" section tells an agent what each MCP tool group is for, when to turn it off, and the `wikifier:` line for the `agent-tools` block; this file itself has no such block, so dogfooding keeps every tool.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.2.0] - 2026-11-05
+
+### Added
+- MCP tool groups, following the suite-wide convention. Every tool is in one of six groups: `core` (always on), `notes`, `health`, `map`, `cycles`, `status`. `WIKIFIER_TOOLS` (allowlist) and `WIKIFIER_DISABLE` (applied after it) take group or tool names, ignore case and spaces, and `WIKIFIER_TOOLS` accepts `all`. Switched-off tools are absent from `tools/list`; calling one returns `isError` with `tool "<name>" is disabled (group "<group>") by <VAR>; …`. An unknown name, or `core` or one of its tools in `WIKIFIER_DISABLE`, prints one line to stderr and exits 2. An empty or whitespace-only value counts as unset. When either variable is set, `initialize` carries an `instructions` line naming the active groups and `list_core_tools` adds a `groups` line and lists only the exposed tools. With neither set, `tools/list` and every other reply are byte-identical to 5.1.0, except that `initialize` now always advertises `capabilities.tools.listChanged: true`. The CLI ignores both variables.
+- Agents choose the groups per project: the first fenced `agent-tools` block in AGENTS.md at the server's project root (`WIKIFIER_PROJECT_ROOT`, else the working directory) may hold `wikifier: tools <list>` and `wikifier: disable <list>` lines (commas or spaces, `#` comments, other tools' lines ignored). `WIKIFIER_TOOLS` overrides the `tools` line and `WIKIFIER_DISABLE` the `disable` line. A mistake in the block (unknown name, `core` in `disable`, unknown key) never stops the server: that line is ignored and a warning line goes into the `initialize` instructions and `list_core_tools`. The server stats AGENTS.md (mtime and size) before every request; when the exposed tool list changes it sends `notifications/tools/list_changed` before the response. `initialize` always advertises `tools.listChanged`, so a block added mid-session takes effect without a restart. With a block or a switch present, its instructions end with the groups line. An `agent-tools` block inside another fenced block (a docs example) is text, not config.
+- "Choosing groups" sections in AGENTS.md, README, and `skills/run.md`: what each group is for, when to turn it off, and the line to add. This repository's own AGENTS.md has no block, so dogfooding keeps every tool.
+- `tools/list` sizes: 22.7 KB (31 tools) with every group on; 18.2 KB without `notes`, 17.0 KB without `health`, 20.8 KB without `map`, 21.9 KB without `cycles`, 19.4 KB without `status`; 16.8 KB (22 tools) with the recommended `WIKIFIER_DISABLE=map,cycles,status`; 6.6 KB (8 tools) with `WIKIFIER_TOOLS=core`.
+
 ## [5.1.0] - 2026-11-05
 
 Agent-facing fixes found by driving the MCP server like an agent on real repositories, Windows fixes, and a speed pass. Protocol stays v0.7.

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Wikifier is a **zero-dependency, agent-to-agent codebase wiki**: it gives AI agents a token-efficient, queryable map of a codebase (health matrix, dependency graph, per-file wiki summaries) so they can look things up instead of re-reading full sources. The human layer (`index.html` dashboard) is strictly secondary — a read-only viewer of the same artifacts. It is deliberately NOT a general human documentation tool.
 
-**This repo dogfoods itself.** Wikifier runs on its own source, and you are expected to follow its agent protocol when working here (see below). `AGENTS.md` is the entry point for any coding agent. The authoritative contract is `skills/run.md` (Agent Protocol v0.7, package 5.1.0). Read it before substantive work.
+**This repo dogfoods itself.** Wikifier runs on its own source, and you are expected to follow its agent protocol when working here (see below). `AGENTS.md` is the entry point for any coding agent. The authoritative contract is `skills/run.md` (Agent Protocol v0.7, package 5.2.0). Read it before substantive work.
 
 **USE WIKIFIER FIRST (non-negotiable in this repo, preferred on any managed target):** At session start call `session_bootstrap` (MCP or `wikifier session-bootstrap`). Prefer Core daily tools (`list_core_tools`): bootstrap, `check_changes`, `prepare_edit`, `suggest_next_actions` (json `actions[]`), `record_change`, `mark_green`. Look up via map/wiki/deps before re-reading full sources. Selective work only (🔴 / actionable 🟡). Never skip `record_change` after edits.
 
@@ -56,7 +56,7 @@ wikifier mcp                           # MCP server on stdio
 
 ## Architecture
 
-Pipeline: **scan → parse → resolve → cache → health → artifacts**, implemented in Rust under `src/` (version in `Cargo.toml`, currently **5.1.0**). The Python package is no longer in this repository. `pip install wikifier` still installs Python 4.7. CLI (`src/main.rs`) and MCP (`src/mcp.rs`) both call `src/api.rs`. Every function returns a JSON object with `success`. Operational failures return `{"success": false, "error", "error_type"}`.
+Pipeline: **scan → parse → resolve → cache → health → artifacts**, implemented in Rust under `src/` (version in `Cargo.toml`, currently **5.2.0**). The Python package is no longer in this repository. `pip install wikifier` still installs Python 4.7. CLI (`src/main.rs`) and MCP (`src/mcp.rs`) both call `src/api.rs`. Every function returns a JSON object with `success`. Operational failures return `{"success": false, "error", "error_type"}`.
 
 - `src/api.rs` — the library surface: `session_bootstrap`, `check_changes`, `prepare_edit`, `suggest_next_actions`, `record_change`, `record_changes`, `record_deletion`, `mark_green`, `verify_wikis`, `update_maps` / `update_maps_run`, `dependency_report`, `load_dependents`, `cycles`, `init_project`, `serve_loop`, `monitor_loop`, `daemon_ctl`. `check_changes` watches mapped files, Green files, and `monitored_paths.txt`. `record_changes` reads `git status` (git is optional).
 - `src/scope.rs` — project root, `map_paths.txt`, `monitored_paths.txt`, excludes, and the file walk. A missing configured map directory is a scope error. Three or more child projects make the root a container and the walk stops.
@@ -65,7 +65,7 @@ Pipeline: **scan → parse → resolve → cache → health → artifacts**, imp
 - `src/artifacts.rs` — `file_health.json` (schema version 2) plus the `file_health.md` view, pending lines, and the journal. Identical journal retries within 120 seconds are skipped. `mark_green` stores `public_symbols`, `wiki_hash`, and `source_mtime_ns`, and refuses a Python or JS/TS wiki that misses the current public names, still mentions a removed name in backticks, or is unchanged after the public surface changed.
 - `src/maps_out.rs` — `library.md` (a file tree, a Mermaid block capped at 80 edges, and the dependency table) and sharded folder cards at `.wikifier_staging/maps/_root.json` and `maps/{prefix}/_index.json`.
 - `src/project_lock.rs` — advisory lock `.wikifier_staging/.lock`, taken before the cache lock, re-entrant per thread, 30 second wait, stolen when the recorded pid is dead.
-- `src/mcp.rs` — stdio JSON-RPC. `isError` follows `success: false`. `resources/read` and `prompts/get` are implemented. Deadline `WIKIFIER_MCP_DEADLINE_S` (default 60).
+- `src/mcp.rs` — stdio JSON-RPC. `isError` follows `success: false`. `src/mcp_groups.rs` holds the tool groups, the AGENTS.md `agent-tools` block parser, and the `WIKIFIER_TOOLS` / `WIKIFIER_DISABLE` switches (MCP only; an env mistake exits 2, a block mistake is a warning). This repo's AGENTS.md has no `agent-tools` block on purpose: dogfooding keeps every tool. `resources/read` and `prompts/get` are implemented. Deadline `WIKIFIER_MCP_DEADLINE_S` (default 60).
 
 Generated artifacts (in the target project root): `file_health.md/.json`, `library.md`, `pending_updates.md`, `journal/YYYY/MM/DD.md`, per-file `*.wiki.md`, `.wikifier_staging/` (`wk_cache`, folder maps, `incremental_status.json`, locks, daemon state). Scoping: `monitored_paths.txt` (extra watch list), `map_paths.txt` (import-map roots), `exclude_patterns.txt`. This repo's map roots are `src/` and `tests/`.
 

diff --git a/CLAUDE.md.wiki.md b/CLAUDE.md.wiki.md
@@ -2,4 +2,4 @@
 
 **Role:** Repo guidance for an agent working in this tree.
 
-Hard constraints: empty Cargo dependencies, no hand-edits of `library.md` or the health and pending files, and the human dashboard stays secondary. The Python-era plan logs live under `Findings/archive/`. It points agents at `AGENTS.md` and `skills/run.md` (protocol v0.7, package 5.1.0). The architecture section names the Rust modules under `src/`, the library file tree, and this repo's map roots `src/` and `tests/`. The parse note includes Rust `crate::`, `self::`, `super::`, Cargo.toml crate names, `[workspace] members`, and `rust_public_symbols` for wiki checks. JSON failures use `success: false`.
+Hard constraints: empty Cargo dependencies, no hand-edits of `library.md` or the health and pending files, and the human dashboard stays secondary. The Python-era plan logs live under `Findings/archive/`. It points agents at `AGENTS.md` and `skills/run.md` (protocol v0.7, package 5.2.0). The architecture section names the Rust modules under `src/`, the library file tree, and this repo's map roots `src/` and `tests/`. The parse note includes Rust `crate::`, `self::`, `super::`, Cargo.toml crate names, `[workspace] members`, and `rust_public_symbols` for wiki checks. JSON failures use `success: false`.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "wikifier"
-version = "5.1.0"
+version = "5.2.0"
 edition = "2021"
 description = "Wikifier — zero-dependency agent-to-agent codebase wiki."
 license = "MIT"

diff --git a/README.md b/README.md
@@ -21,11 +21,11 @@ Download a binary from the [GitHub releases](https://github.com/IronAdamant/wiki
 Check `SHA256SUMS`, unpack, and put `wikifier` (`wikifier.exe` on Windows) on your `PATH`:
 
 ```bash
-# Linux x86_64, 5.1.0
-curl -fsSL -O https://github.com/IronAdamant/wikifier/releases/download/v5.1.0/SHA256SUMS
-curl -fsSL -O https://github.com/IronAdamant/wikifier/releases/download/v5.1.0/wikifier-5.1.0-x86_64-unknown-linux-gnu.tar.gz
+# Linux x86_64, 5.2.0
+curl -fsSL -O https://github.com/IronAdamant/wikifier/releases/download/v5.2.0/SHA256SUMS
+curl -fsSL -O https://github.com/IronAdamant/wikifier/releases/download/v5.2.0/wikifier-5.2.0-x86_64-unknown-linux-gnu.tar.gz
 sha256sum --check --ignore-missing SHA256SUMS
-tar -xzf wikifier-5.1.0-x86_64-unknown-linux-gnu.tar.gz
+tar -xzf wikifier-5.2.0-x86_64-unknown-linux-gnu.tar.gz
 ./wikifier --version
 ```
 
@@ -60,6 +60,52 @@ Or add it to a project's `.mcp.json`:
 
 Every tool takes `project_root` (an absolute path). Without it the server uses `WIKIFIER_PROJECT_ROOT`, then its working directory. A call with a missing argument or an unknown file fails with a message that names the fix, and a failed call sets `isError`. To keep replies small, MCP `session_bootstrap` lists at most 100 files unless you pass `limit` (`files_total` gives the full count, `limit: 0` lists every file), and `update_maps` leaves out the edge list unless you pass `edges: true`. Then give the agent the short prompt in [`skills/run.md`](skills/run.md#paste-into-new-sessions). Any agent that can run shell commands can use the CLI instead: the daily tools have twins such as `wikifier session-bootstrap`, `prepare-edit`, and `record-change` that print the same JSON (the mapping is in `skills/run.md`).
 
+### Tool groups
+
+The 31 MCP tools are in six groups. The agent picks the groups a project needs with one line in the project's AGENTS.md (see Choosing groups below); an operator can override that in the MCP client's `env` block. The CLI is not affected. `WIKIFIER_TOOLS` is an allowlist and `WIKIFIER_DISABLE` hides groups or single tools after it; both take comma-separated group or tool names, ignore case and spaces, and `WIKIFIER_TOOLS` also accepts `all`. With neither set, the listing is exactly what it was; `initialize` always advertises `tools.listChanged`, so an edit to the AGENTS.md block takes effect without a restart. A block inside another fenced block (a docs example) is ignored. An unknown name, or `core` or one of its tools in `WIKIFIER_DISABLE`, stops the server with exit code 2 and a one-line message, so a mistake shows up as a failed server. An empty value counts as unset. A switched-off tool, if called, returns `isError` naming the switch to change.
+
+| Group | Tools | Overlaps with |
+|---|---|---|
+| `core` (always on) | `session_bootstrap`, `prepare_edit`, `get_dependencies`, `get_dependents`, `get_file_wiki`, `list_paths`, `suggest_next_actions`, `update_maps` | — |
+| `notes` | `record_change`, `record_changes`, `record_deletion`, `search_journal`, `why_file`, `journal` | Trammel notes (`add_note`) |
+| `health` | `check_changes`, `mark_green`, `verify_wikis`, `health`, `validate`, `list_healable_stubs`, `heal_stubs`, `seed_source_content_hashes` | — |
+| `map` | `get_resolution_diagnostics`, `get_barrel_reports`, `get_incremental_status` | — |
+| `cycles` | `get_cycles` | — |
+| `status` | `list_core_tools`, `get_project_status`, `get_current_project_root`, `issues`, `get_files_needing_attention` | — |
+
+`tools/list` is 22.7 KB with every group on. The recommended lean setting keeps the whole daily loop and drops the diagnostics and the tools that repeat bootstrap: 22 tools, 16.8 KB.
+
+```json
+"env": {"WIKIFIER_DISABLE": "map,cycles,status"}
+```
+
+`WIKIFIER_TOOLS=core` alone is 8 tools and 6.6 KB, for an agent that only looks things up. Turning `notes` off also turns off `record_change`, which marks a file for its wiki refresh, so keep `notes` on unless another tool records the changes.
+
+### Choosing groups
+
+You, the agent, choose which Wikifier tool groups a project needs. Add one line for `wikifier` to the `agent-tools` block of the project's AGENTS.md: a fenced code block whose info string is `agent-tools`, in the project root the server uses (`WIKIFIER_PROJECT_ROOT`, else its working directory). The server re-reads the file when it changes and tells the client the tool list changed, so no restart is needed. `WIKIFIER_TOOLS` / `WIKIFIER_DISABLE` in the server's environment override the line, key by key. A mistake in the line is reported as a warning in the `initialize` instructions and the line is ignored.
+
+| Group | What it is for | Turn it off when |
+|---|---|---|
+| `core` | bootstrap, lookups, dependencies, file wikis, `update_maps` | never: always on |
+| `notes` | `record_change` and the journal: why each file changed, handoff reasons | another tool keeps the change notes (for example Trammel notes) and you do not maintain wikis |
+| `health` | `check_changes`, `mark_green`, wiki verification | you only look things up and do not maintain wikis |
+| `map` | import-resolution and barrel diagnostics | you are not debugging the import map (most sessions) |
+| `cycles` | the import-cycle report | you are not untangling dependencies |
+| `status` | repeats of bootstrap: project status, issues, the tool catalogue | almost always |
+
+One agent maintaining wikis (the usual case):
+
+```agent-tools
+wikifier: disable map, cycles, status
+```
+
+Lookups only:
+
+```agent-tools
+wikifier: tools core
+```
+
 ## Quick start
 
 ```bash
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,4 +2,4 @@

		Role: Entry point for any coding agent in this repository.

		It points at `skills/run.md` (protocol v0.7, package 5.1.0) and names the live Rust binary, the daily loop, and the Python-era records kept under `Findings/archive/`. `pip install wikifier` is the archived Python 4.7 package. Map roots stay `src/` and `tests/`. The import scan stays comment-masked regex plus named re-exports. Rust also resolves `crate::`, `self::`, `super::`, root crate names, and `[workspace] members`, so `src/main.rs` and `tests/*.rs` are dependents of the library modules they import. `mark-green` checks Rust `pub` names, impl methods, and trait-impl items.
		It points at `skills/run.md` (protocol v0.7, package 5.2.0) and names the live Rust binary, the daily loop, and the Python-era records kept under `Findings/archive/`. `pip install wikifier` is the archived Python 4.7 package. Map roots stay `src/` and `tests/`. The import scan stays comment-masked regex plus named re-exports. Rust also resolves `crate::`, `self::`, `super::`, root crate names, and `[workspace] members`, so `src/main.rs` and `tests/*.rs` are dependents of the library modules they import. `mark-green` checks Rust `pub` names, impl methods, and trait-impl items. A "Choosing groups" section tells an agent what each MCP tool group is for, when to turn it off, and the `wikifier:` line for the `agent-tools` block; this file itself has no such block, so dogfooding keeps every tool.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,4 +2,4 @@

		Role: Repo guidance for an agent working in this tree.

		Hard constraints: empty Cargo dependencies, no hand-edits of `library.md` or the health and pending files, and the human dashboard stays secondary. The Python-era plan logs live under `Findings/archive/`. It points agents at `AGENTS.md` and `skills/run.md` (protocol v0.7, package 5.1.0). The architecture section names the Rust modules under `src/`, the library file tree, and this repo's map roots `src/` and `tests/`. The parse note includes Rust `crate::`, `self::`, `super::`, Cargo.toml crate names, `[workspace] members`, and `rust_public_symbols` for wiki checks. JSON failures use `success: false`.
		Hard constraints: empty Cargo dependencies, no hand-edits of `library.md` or the health and pending files, and the human dashboard stays secondary. The Python-era plan logs live under `Findings/archive/`. It points agents at `AGENTS.md` and `skills/run.md` (protocol v0.7, package 5.2.0). The architecture section names the Rust modules under `src/`, the library file tree, and this repo's map roots `src/` and `tests/`. The parse note includes Rust `crate::`, `self::`, `super::`, Cargo.toml crate names, `[workspace] members`, and `rust_public_symbols` for wiki checks. JSON failures use `success: false`.