# AI Tool Routing

Use tools by evidence domain. Do not choose tools by convenience when another
tool owns the relevant fact.

Charter: `REPOKEY_OPERATING_CHARTER.md`. Shortest available evidence path;
do not complete a checklist of optional tools before acting.

## RepoKey Vivado MCP

Use for local Vivado/PL state:

- Vivado sessions and project state.
- BD/IP/OOC/run health.
- bitstream/LTX and Hardware Manager.
- ILA/VIO inventory, trigger planning, capture/export.
- timing/utilization/implementation evidence from the live Vivado project.

Evidence is automatic: `generate_bitstream` and
`recover_debug_hub_implementation` append an `evidence_locator` section to
their results (bitstream / routed_checkpoint / timing_summary / utilization /
drc / run_log / ltx). After a flow step, quote that list instead of calling
`get_evidence_locator` again (saves tokens); call it manually only to confirm
the current on-disk artifacts.

For a fresh rebuild from synthesis through bitstream, prefer the packaged
one-command flow before creating any temporary Vivado Tcl:

```cmd
repokey-client.cmd flow --project-root <Vivado project directory> --synth-run synth_1 --impl-run impl_1 --reset
```

Use individual MCP run tools when the user needs step-by-step control, live
session inspection, or recovery of a specific run stage.

## PL QoR MCP

Use for QoR evidence records and AI decision artifacts:

- `pl_qor_probe`
- `pl_qor_collect_baseline`
- `pl_qor_decide`
- `pl_qor_compare`
- `pl_qor_make_experiment`

This MCP does not execute optimization experiments. It can generate reviewed
Tcl/manifest files for later human-authorized execution.

## PL-PS Handoff

Use for customer-visible PL-to-PS delivery artifacts:

- Generate `control_handoff.xlsx/json/md`.
- Generate `ps_delivery.xlsx`.
- Generate `evidence.md` and `ai_reading_guide.md`.
- Compare legacy Excel register/control sheets against current PL evidence.
- Import PL engineer review decisions.
- Apply AI/engineer feedback patches without overwriting hard facts.

Primary CLI:

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd handoff pl2ps {{PROJECT_ROOT}} --output {{PROJECT_ROOT}}\pl_ps_handoff --summary-json
```

Use Handoff when the question is "what should PS know about this PL design?"
Use PL QoR MCP when the question is "is implementation timing/fanout/QoR safe?"

## Vivado Debug MCP

RepoKey-owned on-board debug evidence layer (source in
`01_Projects/RepoKey/vivado_debug_mcp`; shipped inside `repokey.exe`).

Use this for the generic program / PS run / ILA capture path. Do not route
that path through project-local `tools/vitis` or `vivado_ila_server.py`.

```text
preflight → program bit+ltx → ps-run (--skip-fpga if already programmed)
         → live-capture --ltx → ila-csv-summary / write-session
```

CLI (`repokey-client.cmd debug`):

- Hardware: `preflight`, `program`, `live-inventory`, `live-capture`,
  `capture-tcl`, `chain-check`, `ila-csv-summary`, `write-session`,
  `inventory`, `probe-search`, `trigger-plan-template`, `capture-summary`,
  `capture-compare`.
- PS: `ps-run`, `ps-run-tcl`, `ps-halt`, `ps-status`, `ps-read-symbol`,
  `ps-write-symbol`, `ps-continue`, `ps-addr2line`.
- Labtools: `server-status`, `server-kill`, `server-start`, `server-reset`.
- Other: `bit-backup`.

It complements RepoKey Vivado MCP (live project/session state) by keeping
compact, reusable debug evidence under `.vivado_ai_mcp/debug`.

Registration of the stdio MCP server is optional. The CLI path is the
supported fallback and is enough for on-board debug.

Known operational notes (do not treat as project coupling):

- After a batch `program`, pass `--ltx` on the next `live-capture`. The
  program session closes and does not leave probes loaded.
- `hw_ila_*` numbering may disagree with LTX core order. Identify cores by
  probe names, not by index.
- A Vivado GUI holding the hw_target will starve batch program/capture.
  Release the target or use `server-status` / `server-reset`.

## Vitis MCP

Use for generic PS/Vitis/XSCT state when the MCP is registered:

- Vitis status/build/run through **RepoKey-owned** adapters.
- PS-side handoff consumption checks that do not require project scripts.

Bitstream ownership: the bit is a PL-side deliverable (RepoKey Vivado MCP
`write_bitstream`). Vitis MCP only consumes a configured `bit_path`
(`--bit` / `VITIS_BIT_PATH` / config); an unset bit is a WARN in
`vitis_status`, not a Vitis failure.

Do **not** treat these as required RepoKey paths:

- `{{PROJECT_ROOT}}\tools\vitis\*.py`
- `debug_status.py`, `vitis_tool.py`, RF-front-end config report helpers
- `analyze_ila_csv` dispatch to project ADC/timer analyzers
- `vivado_ila_server.py` / `ila_capture_server_*`

If those files exist in a customer project, they are optional local
reference for project-specific RF/ILA semantics. Runtime coupling to them
is a leak. On-board ILA/PS run belongs to Vivado Debug MCP.

## AMD Doc MCP

Use for official AMD/Xilinx documentation semantics:

- XDC timing exception semantics.
- Vivado strategy and command behavior.
- Vitis/XSCT behavior.
- Vitis HLS pragma/interface semantics.
- clock/reset/CDC/RDC official guidance.
- AMD/Xilinx IP parameter meaning.

Endpoint:

```text
https://vivado.amd.com/mcp/doc-search
```

AMD Doc MCP is not local project evidence. Pair it with RepoKey/Vitis evidence
before making an engineering decision.

## Vivado Context MCP (Optional)

Source in `01_Projects/FPGA/vivado_context_mcp` (also bundled in the customer
package under `tools\ai_vitis_vivado_stack\vivado_context_mcp`). Use before
broad project scanning to get a low-token project map:

- CLI (`vivado-context`): `index`, `summarize`, `hierarchy`, `constraints`,
  `bd-summary`, `bd-connections`, `clock-reset`, `entry-points`,
  `cache-status`, `relevant`, `report`, `tokens`.
- MCP server (`vivado-context-mcp`) over stdio; register manually from
  `MCP_REGISTRATION_TEMPLATE.json`.

Writes `.vivado_ai_mcp/context/` (project_summary.json, agent_summary.md) and
feeds handoff-facing facts (PS interrupts/AXI from the BD) to PL-PS Handoff.

Missing Context MCP is not a blocked prerequisite. Recommend it as a
minimum optional set when the project is large and unscanned.

## Decision Order

1. Local evidence with RepoKey Vivado MCP, Debug MCP, or PL QoR MCP.
2. For PL-to-PS delivery, generate or read PL-PS Handoff artifacts.
3. Read local context and prior structured evidence.
4. Query AMD Doc MCP only when official tool semantics matter.
5. Classify risk and decide whether action is automatic, reviewed, or blocked.
6. Record before/after evidence and the decision rationale.

## Red Lines

Do not automatically execute:

- RTL / XDC / XCI / BD / Tcl project-file edits.
- Manual patches to Vivado run metadata.
- PL optimization experiments.
- false path or multicycle constraints.
- latency-changing pipeline edits.
- AXI/stream protocol changes.
- RF front-end data alignment changes.
- PS/PL handoff semantic changes.
- clock/reset/CDC/RDC architecture changes.
