# RepoKey AI Vitis / Vivado Stack

Local tool stack inside the RepoKey Vivado AI customer package. The tools
produce evidence; the AI makes engineering judgments; a human authorizes design
intent changes. `<REPOKEY_HOME>` in paths refers to the installed package root.

## Components

| Component | Responsibility | Entry point (all via `repokey-client.cmd`, no Python) |
|---|---|---|
| `vitis_mcp` | PS/Vitis/XSCT runtime evidence, PS static context, ILA CSV analysis dispatch, persistent ILA capture service | `repokey-client.cmd vitis` |
| `pl_qor_mcp` | PL timing/utilization/QoR evidence collection, decision logging, comparison | `repokey-client.cmd pl-qor` |
| `pl_ps_handoff` | PL-to-PS control delivery (`control_handoff.*` / `ps_delivery.xlsx` / `evidence.md` / `ai_reading_guide.md`) | `repokey-client.cmd handoff pl2ps ...` |
| `pl_optimizer_compat` | QoR version adaptation and baseline collection (built into `repokey.exe`; also ships `scripts\repokey_pl_qor.py` and other helper scripts for the local pl_qor adaptation path) | Built in |
| `vivado_debug_mcp` | Hardware debug evidence layer: ILA/VIO inventory, trigger templates, capture summary/compare, live capture, XSCT register probe | `repokey-client.cmd debug serve` |
| `vivado_context_mcp` | Low-token project context index (xpr/RTL/XDC/BD/IP, relevant files, token estimate, handoff facts) | `repokey-client.cmd context serve` |

## Start Here

- `AI_TOOL_ROUTING.md`: rules for choosing a tool by evidence domain.
- Stack health check: `repokey-client.cmd mcp-selfcheck` (a separate
  `scripts\smoke_test_mcp_stack.py` exists only in the source dev directory; not
  shipped to customers).

## MCP Registration

- `MCP_REGISTRATION_TEMPLATE.json`: optional MCP server registration template
  (vitis / pl-qor / vivado-debug / vivado-context).
- The main RepoKey Vivado MCP is managed by `install\register_mcp.ps1`; optional
  `vivado-debug` registration is in `install\register_debug_mcp.ps1`.
- All stack MCPs are built into `repokey.exe`; the registration scripts need no
  `pip install` or `PYTHONPATH`.

## Evidence Path Convention

Projects use a unified layout:

```text
.vivado_ai_mcp\
  context\     Vivado Context MCP index
  qor\         PL QoR baseline/compare
  ps_context\  Vitis MCP PS static context
  debug\       vivado_debug_mcp sessions and evidence
```

## Boundaries

- Does not auto-run PL optimization experiments, does not auto-edit
  RTL/XDC/BD, does not add timing exceptions.
- AMD Doc MCP only provides official semantics, not local project evidence.
