bpstr · bpstr · Sep 15, 2026 · Sep 15, 2026
diff --git a/.gitignore b/.gitignore
@@ -8,4 +8,3 @@ dist/
 .pytest_cache/
 .DS_Store
 .codebase-memory/
-graphify-out/
diff --git a/AGENTS.md b/AGENTS.md
@@ -2,7 +2,7 @@
 
 Read [architecture](docs/ARCHITECTURE.md) and [testing policy](docs/TESTING.md) before changing the engine.
 
-Prefer codebase-memory MCP graph tools for code discovery; index the repository if needed. Use scoped text/file searches when graph tools are unavailable or insufficient, or for config/literal searches.
+For code discovery, use any installed code-intelligence, symbol, semantic-search or code-graph tool explicitly described by applicable repository/ancestor agent instructions. Prefer the smallest useful structural query; use scoped text/file searches when no such tool is configured, unavailable, or insufficient, and for config/literal searches. Understand Code must not hard-code or require a specific code-intelligence product.
 
 Canonical code is in `src/`; input contracts are in `schemas/`. After editing either or the role registry, run `python3 scripts/build_bundle.py`. Do not independently edit generated skill engine copies or specialist cards.
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,10 +1,16 @@
 # Changelog
 
+## Unreleased
+
+- Remove vendor-specific code-intelligence coupling from the engine and CLI.
+- Let applicable repository/host agent instructions select any installed code-intelligence retrieval tool.
+- Keep external retrieval results explicitly unverified until checked against current source evidence.
+
 ## 1.0.0 — 2026-09-06
 
 - Add deterministic codebase inventory, native specialist task planning and evidence-bound findings ingestion.
 - Add semantic entities, directed relationships, confidence states, source-reviewed claims and contradiction gaps.
 - Add Markdown Codebase Specs, protected human notes, transactional writes and integrity/freshness verification.
-- Add incremental Git impact, scoped focus, read-only instruction audits and Graphify import/export handoffs.
+- Add incremental Git impact, scoped focus and read-only instruction audits.
 - Ship Claude Code/Codex plugins, self-contained Open Agent Skill, Python CLI, offline regression tests and install/update guides.
 - Keep provider execution, paid testing and runtime trace execution outside the engine.
diff --git a/INSTALL.md b/INSTALL.md
@@ -2,7 +2,9 @@
 
 ## Requirements
 
-Python 3.10 or newer; Git for tracked inventories, history, diffs and worktree isolation. No Python runtime dependencies, API keys, service signup or background process are needed. Claude/Codex installation and authentication are managed by those hosts. Graphify or codebase-memory MCP is a companion for structural retrieval; the CLI can consume a preexisting graph export.
+Python 3.10 or newer and Git. No Python runtime dependencies, API keys, service signup or background process are required. Claude/Codex installation and authentication are managed by those hosts.
+
+Code-intelligence retrieval is host-managed: the native session follows applicable `AGENTS.md`, `CLAUDE.md` and equivalent repository/ancestor instructions and may use any installed structural, symbol, semantic-search or code-graph tool described there. No specific code-intelligence product is required by the CLI.
 
 ## Codex
 
@@ -11,94 +13,35 @@ codex plugin marketplace add bpstr/understand-code
 codex plugin add understand-code@understand-code
 ```
 
-Alternatively select Understand Code in the Plugins Directory after adding the marketplace. Open a new task to load the installed skill, then use `$understand-code`. The self-contained runner and contracts live inside the skill cache; no global CLI installation is necessary.
-
-Update the marketplace and reinstall its current snapshot:
-
-```bash
-codex plugin marketplace upgrade understand-code
-codex plugin add understand-code@understand-code
-```
-
-Open a new task after updates. If the host reports the plugin is already installed without refreshing it, remove and add that exact plugin:
-
-```bash
-codex plugin remove understand-code@understand-code
-codex plugin add understand-code@understand-code
-```
-
-CLI verbs are documented from `codex plugin --help`; older host builds may expose installation through their UI. The repository uses the root plugin path, as in the reference repository's marketplace.
-
 ## Claude Code
 
 ```bash
 claude plugin marketplace add bpstr/understand-code
 claude plugin install understand-code@understand-code
 ```
 
-Restart the session. Use `/understand-code:understand-code` with a reconstruction, focus or update request. The plugin also includes 18 read-only specialist agent definitions. Tool access and native delegation remain controlled by the host/user.
-
-Update:
-
-```bash
-claude plugin marketplace update understand-code
-claude plugin update understand-code@understand-code
-```
-
-Restart after updating. For a local checkout, `claude --plugin-dir /absolute/path/to/understand-code` loads the plugin for development; do not run an inference/eval command as an installation test.
-
 ## Open Agent Skills
 
 ```bash
 npx skills add bpstr/understand-code --skill understand-code
 ```
 
-Choose the target host in the installer. The entire engine, schemas, specialist cards and references are bundled under `skills/understand-code`; copying only SKILL.md is insufficient. For updates, rerun the same installer and select the same skill/hosts, reviewing its replacement behavior.
-
 ## Standalone CLI
 
-Pinned release:
-
 ```bash
 uv tool install 'git+https://github.com/bpstr/understand-code.git@v1.0.0'
 understand-code --version
 ```
 
-Without uv:
-
-```bash
-python3 -m venv ~/.venvs/understand-code
-~/.venvs/understand-code/bin/python -m pip install 'git+https://github.com/bpstr/understand-code.git@v1.0.0'
-~/.venvs/understand-code/bin/understand-code --help
-```
-
-Update to a reviewed release by replacing the version tag:
-
-```bash
-uv tool install --force 'git+https://github.com/bpstr/understand-code.git@v1.0.0'
-```
-
-Or follow main explicitly with `uv tool install --force 'git+https://github.com/bpstr/understand-code.git@main'`. Pinning a tag is preferable for repeatable deployments. The same pinned install command supports rollback to an earlier release. No PyPI publication is required or implied.
-
 ## First reconstruction
 
 ```bash
 understand-code bootstrap /path/to/repo --provider codex
 ```
 
-This requires a clean committed checkout and creates a sibling worktree on a `codex/understand-code-*` branch. Use the repository path printed in its JSON result for subsequent commands. If repository/user policy requires the current branch, or you need to include uncommitted code:
-
-```bash
-understand-code bootstrap /path/to/repo --write-mode local --provider claude
-```
+The default creates an isolated worktree from a clean committed checkout. Use `--write-mode local` when repository policy requires the current branch or uncommitted source must be included. No source files are modified.
 
-No source files are modified in either mode. Existing output must be an owned Codebase Spec; choose `--output docs/reconstructed` for a separate destination. Use that output on every subsequent command. Add `.understand-codeignore` for additional glob exclusions (one glob per line, `#` comments). Git-ignored files are excluded in Git repositories, and known secret/dependency/build paths are excluded everywhere. The scanner does not execute source or inspect `.secrets`.
-
-Modes: quick = up to 6 tasks × 24 paths; standard = 18 × 40; deep = 36 × 60. Scan limits default to 2,000 files and 5 MB of UTF-8 text. `--max-files` and `--max-bytes` adjust them. Skipped/deferred coverage is explicit. Deep mode adds bounded history analysis, not runtime execution.
-
-## Graphify and source updates
-
-Provide an existing `graphify-out/graph.json` or `--graph <repository-relative-export>`. Use native graph tools to investigate and refresh source plus spec Markdown after accepted findings. See [Graphify contract](skills/understand-code/references/graphify.md); this CLI never invokes a paid extraction pipeline.
+Modes: quick = up to 6 tasks × 24 paths; standard = 18 × 40; deep = 36 × 60. Scan limits default to 2,000 files and 5 MB of UTF-8 text. `--max-files` and `--max-bytes` adjust them. Skipped/deferred coverage is explicit.
 
 After source changes:
 
@@ -107,8 +50,6 @@ understand-code update --repo /path/to/spec-worktree --base origin/main
 understand-code status --repo /path/to/spec-worktree
 ```
 
-The update creates scoped tasks and marks affected prior claims UNKNOWN. Investigate and apply refreshed findings before calling the spec current. See [workflow](docs/WORKFLOW.md) and [maintenance/recovery](skills/understand-code/references/maintenance.md).
-
 ## Local development
 
 ```bash
@@ -117,7 +58,8 @@ cd understand-code
 python3 -m venv .venv
 .venv/bin/python -m pip install -e .
 python3 scripts/build_bundle.py
+PYTHONPATH=src python3 -m unittest discover -s tests -v
 python3 scripts/check_distribution.py
 ```
 
-Edit canonical code under `src/`, contracts under `schemas/`, and role objectives in `src/understand_code/spec/planner.py`. Regenerate the bundle after edits; CI rejects stale copies. Run `sh scripts/understand-code.sh --help` to inspect the bundled runner without any provider call.
+Edit canonical code under `src/`, contracts under `schemas/`, and role objectives in `src/understand_code/spec/planner.py`. Regenerate the bundle after edits; CI rejects stale copies.
diff --git a/README.md b/README.md
@@ -6,97 +6,78 @@ Understand Code is a Python CLI and self-contained Claude Code / Codex skill. It
 
 It combines deterministic inventory and validation with bounded investigations in your existing Claude or Codex session. It never starts provider subprocesses, executes the target application, or silently spends API credits.
 
-## Install
+## Code intelligence
+
+Understand Code is deliberately tool-agnostic. The native session follows applicable repository/ancestor instructions such as `AGENTS.md` or `CLAUDE.md` and may use any installed code-intelligence, symbol, semantic-search or code-graph tool described there. If none is configured or useful, it falls back to bounded source/file search. External retrieval output is never evidence by itself; persisted claims require exact current-source evidence.
 
-**Codex plugin**
+## Install
 
 ```bash
 codex plugin marketplace add bpstr/understand-code
 codex plugin add understand-code@understand-code
 ```
 
-Start a new task and invoke `$understand-code reconstruct this repository`.
-
-**Claude Code plugin**
+or:
 
 ```bash
 claude plugin marketplace add bpstr/understand-code
 claude plugin install understand-code@understand-code
 ```
 
-Restart Claude Code and invoke `/understand-code:understand-code reconstruct this repository`.
-
-**Standalone CLI** — Python 3.10+, Git, no runtime Python dependencies:
+Standalone CLI, Python 3.10+ and Git:
 
 ```bash
 uv tool install 'git+https://github.com/bpstr/understand-code.git@v1.0.0'
 understand-code bootstrap /path/to/repository
 ```
 
-The plugin already includes the runner; installing the CLI is optional. See [complete setup and updates](INSTALL.md), including Open Agent Skills and local development.
-
 ## Workflow
 
 ```text
-Source + optional Graphify graph
+Source + repository-configured retrieval tools
           ↓ deterministic inventory
 Bounded native specialist investigations
           ↓ cited findings + source review
-Codebase Spec + semantic graph sidecar
+Codebase Spec
           ↓ source verification
 Task planning / implementation / deep-code-review
           ↓ Git diff + semantic impact
-Updated Codebase Spec → external graph refresh
+Updated Codebase Spec
 ```
 
 ```bash
-understand-code bootstrap .                       # dedicated worktree by default
-understand-code bootstrap . --write-mode local    # docs on the current branch
+understand-code bootstrap .
+understand-code bootstrap . --write-mode local
 understand-code focus "checkout" --repo /path/to/worktree
 understand-code update --repo /path/to/worktree --base origin/main
 understand-code verify --repo /path/to/worktree
 understand-code agent-audit --repo /path/to/worktree
 understand-code status --repo /path/to/worktree
 ```
 
-Bootstrap inventories the repository and writes an investigation plan. It **does not invent product features** from filenames or claim a semantic reconstruction is finished. The skill performs the planned investigations, captures exact source evidence, and applies reviewed findings through the same deterministic engine. [Native workflow and contracts](docs/WORKFLOW.md).
+Bootstrap inventories the repository and writes an investigation plan. It does not invent product features from filenames or claim a semantic reconstruction is finished. Native investigations capture exact source evidence and apply reviewed findings through the deterministic engine.
 
 ## What ships
 
-| Capability | Behavior |
-| --- | --- |
-| Structural discovery | Git-aware file inventory, language/manifests, Python symbols, route/settings/UI/data/event/test candidates, explicit scan limits |
-| Native agents | 18 specialist roles; adaptive quick/standard/deep budgets; Claude/Codex task formats; sequential or authorized native delegation |
-| Semantic model | 18 entity kinds and 22 directed relation types; stable IDs, aliases, feature/flow pages and source-linked change maps |
-| Evidence | Exact ranges, file and excerpt hashes, source snapshots, explicit confidence and recorded semantic review |
-| Incremental updates | Git base + working-tree hashes; renames/deletions; transitive semantic impact; stale claims demoted to UNKNOWN |
-| Human knowledge | Maintainer notes preserved; generated edits block replacement; conflicts retain alternatives |
-| Agent readiness | Instruction scopes, size, duplicate content, missing link observations and bounded recommendations |
-| Graphify | Existing node-link import, scoped graph context, Markdown links, typed semantic sidecar and explicit external refresh handoff |
-| Distribution | Codex/Claude manifests and marketplaces, standalone skill runner, installable Python package, offline CI and release archives |
+- Git-aware structural discovery, manifests, language inventory and bounded candidates.
+- 18 native specialist roles with quick/standard/deep budgets.
+- Typed semantic entities and directed relationships with stable IDs and aliases.
+- Exact source ranges, file/excerpt hashes, confidence and review provenance.
+- Incremental Git updates, stale-claim quarantine and explicit gaps.
+- Maintainer-note preservation and generated-region protection.
+- Tool-agnostic retrieval governed by repository/host instructions.
+- Codex/Claude manifests, standalone CLI and offline deterministic CI.
 
-The default output includes overview, concept pages, evidence, instruction/readiness reports, operational pointers, glossary and gaps. Relevant feature/flow/settings/UI/data pages appear when findings support them. Empty architecture claims are not filled with plausible prose.
-
-## Truth and limitations
-
-`EXTRACTED` means reviewed, direct evidence; `CORROBORATED` requires independent evidence; `INFERRED` is incomplete interpretation; `UNKNOWN` is an unresolved question. Mechanical checks can establish that a citation exists and is current. **They cannot prove a natural-language claim is true.** Reviewer provenance, gaps and coverage remain visible.
-
-Graph imports are retrieval hints. Regex matches are candidates. Test source establishes assertions, not a passing test run. Static links do not establish runtime reachability. Architectural intent needs explicit evidence. There is no live-provider quality claim: the shipped regression suite uses prepared fixtures only.
-
-This release does not execute runtime traces, refresh Graphify through an undocumented command, or run autonomous paid headless agents. Native sessions provide reasoning; an installed Graphify integration performs its own refresh. These boundaries and the [v1 acceptance map](docs/ACCEPTANCE.md) distinguish implemented capabilities from future extensions.
+`EXTRACTED` means reviewed direct evidence; `CORROBORATED` requires independent evidence; `INFERRED` is incomplete interpretation; `UNKNOWN` is unresolved. Mechanical checks prove citation identity and freshness, not natural-language truth. Retrieval tools provide hints only. Tests establish assertions, not passing runtime behavior.
 
 ## Develop
 
 ```bash
 python3 -m venv .venv
 .venv/bin/python -m pip install -e .
 PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -v
-python3 scripts/build_bundle.py
+python3 scripts/build_bundle.py --check
 python3 scripts/check_distribution.py
 ```
 
-All automated tests are offline and deterministic. Never load `.secrets`, record fixtures from providers, or add a paid test opt-in. See [testing policy](docs/TESTING.md) and [contributing](CONTRIBUTING.md).
-
-Inspired by the bounded specialist pattern in [deep-code-review](https://github.com/bpstr/deep-code-review). The implementation is original. Plugin setup follows the host's [Codex plugin interface](https://learn.chatgpt.com/docs/plugins) and [Claude plugin reference](https://code.claude.com/docs/en/plugins-reference).
-
-MIT licensed. [Changelog](CHANGELOG.md) · [Architecture](docs/ARCHITECTURE.md) · [Security](SECURITY.md)
+All automated tests are offline and deterministic. MIT licensed.