# Useful Helpers Suite — Agent Control Plane

A suite of local developer tools and small apps, made **agent-accessible** and
**human-accessible** through one shared tool registry and two entrances:

- **Agent entrance** — an MCP server (`python -m src.app mcp`) exposing every tool via
  `tools/list` / `tools/call`.
- **Human entrance** — a registry-driven desktop GUI (`python -m src.app ui`).

Both read the same registry and dispatch through one `invoke()` seam to each tool's headless
CLI. Add a tool once → it appears in both entrances.

## Layout
- `src/` — the control plane (`core/` registry + invoke seam · `interfaces/` mcp + cli ·
  `ui/` human entrance · `lib/` shared).
- `tools/` — small re-homed CLI tools · `apps/` — larger re-homed apps.
- `config/` — the generated registry. `_docs/` — architecture, plans, provenance, journal.
- `.parts-bin/` — read-only donor reservoir (Mindshard + the legacy helper suite). Not a
  runtime dependency; everything shipped is re-homed out of it.
- `_BCC/` — the Builder Constraint Contract governing this project.

## Status
Control-plane spine is live with **44 registered capabilities + playbooks**. The latest parked
tranche is **T-bd-graph**: a deterministic split -> emit -> SQLite -> query/project graph
pipeline re-homed from the BD donor suite. See
`_docs/IMPLEMENTATION_ROADMAP.md`, `_docs/TOOL_DERIVATION_PLAN.md`, and
`_docs/DONOR_DEPLETION_AUDIT.md`.

## Quick start (once the spine lands at T3)
```bat
setup_env.bat            :: create the shared root .venv
run.bat cli tool-list    :: list registered tools
run.bat mcp              :: start the MCP server (agent entrance)
run.bat ui               :: launch the desktop GUI (human entrance)
python smoke_test.py     :: run the spine smoke suite (repeatable dogfood check)
```