# FPGA AI Tool Suite Matrix

This document explains how the local FPGA AI tool suite is divided across five
related projects:

- `vivado_mcp`
- `vivado_mcp_pro`
- `vivado_context_mcp`
- `simulation_acceleration`
- `vivado_debug_mcp`

The goal is not to make the tools overlap. The goal is to let them cooperate with
clear boundaries.

## Short Version

- `vivado_context_mcp` gives the agent a low-token project map.
- `simulation_acceleration` gives the agent a fast pre-Vivado verification loop.
- `vivado_mcp` gives the agent direct Vivado access and common project operations.
- `vivado_mcp_pro` gives the agent authoritative, evidence-oriented Vivado workflows and artifact memory.
- `vivado_debug_mcp` gives the agent low-token hardware debug evidence from ILA/VIO sessions.
- `.vivado_ai_mcp/` is the shared project-local evidence store.

## Role Of Each Tool

### `vivado_context_mcp`

Primary role:

- static project understanding before heavy file reads or heavy Vivado actions

Best at:

- finding the active Vivado project
- identifying design top and simulation top
- classifying RTL, XDC, IP, BD, simulation, and Tcl files
- extracting module structure, clock/reset hints, BD summaries, and relevant files
- generating compact context reports for agents

Should not be positioned as:

- a replacement for Vivado
- an HDL compiler
- the final authority for synthesis, implementation, timing, utilization, or hardware state

### `simulation_acceleration`

Primary role:

- fast feedback for simulation and verification before invoking slow Vivado flows

Best at:

- quick RTL smoke tests
- cocotb-based validation loops
- Icarus/Verilator-centered fast simulation workflows
- catching obvious RTL and testbench problems before opening Vivado

Should not be positioned as:

- a replacement for Vivado/xsim for Xilinx-IP-heavy integration
- the final authority for full-project integrated simulation when vendor IP or BD behavior matters

### `vivado_mcp`

Primary role:

- core Vivado control and direct MCP access to Vivado project operations

Best at:

- opening projects
- querying project state
- reading timing and utilization information
- interacting with IP and BD through Vivado
- running common Vivado tasks and batch flows

Should not be positioned as:

- the low-token project understanding layer
- the historical artifact memory layer

### `vivado_mcp_pro`

Primary role:

- authoritative Vivado workflow execution plus evidence/artifact packaging for AI agents

Best at:

- cold-start automated Vivado runs
- synthesis / implementation / bitstream workflows
- storing large Vivado reports and logs locally
- returning compact evidence packets instead of full raw output
- searching, comparing, and reusing historical timing/utilization/run artifacts

Should not be positioned as:

- the first tool an agent uses to discover what a project is
- the fastest day-to-day RTL simulation loop

### `vivado_debug_mcp`

Primary role:

- low-token board-level debug evidence for AI agents working with Vivado Hardware Manager

Best at:

- enumerating hardware targets, devices, ILA cores, VIO cores, and probes
- exposing compact debug inventories instead of raw Hardware Manager logs
- applying structured trigger plans generated by an agent
- running headless ILA captures when the hardware debug path is available
- summarizing captured waveform data into compact signal events
- comparing multiple captures and preserving debug session history

Should not be positioned as:

- an autonomous FPGA debugger
- a replacement for an engineer at the debug bench
- a replacement for project understanding, simulation, synthesis, implementation, or timing tools
- a tool that can observe signals that were not inserted into ILA/VIO or otherwise made visible

## Shared Evidence Store

The suite should use a project-local evidence store:

```text
.vivado_ai_mcp/
  context/
  simulation/
  implementation/
  debug/
  evidence/
```

See [Evidence Store](evidence_store.md) for the formal layout. See
[Vivado Debug MCP MVP](vivado_debug_mcp_mvp.md) for the proposed debug-layer
scope.

The intent is to let tools share compact, reusable evidence without forcing the
agent to repeatedly scan source trees, reread large reports, or ingest raw
waveform data.

Namespace ownership:

- `vivado_context_mcp` writes `context/`
- `simulation_acceleration` writes `simulation/`
- `vivado_mcp_pro` writes `implementation/`
- `vivado_debug_mcp` writes `debug/`
- all tools may update `evidence/index.json` and `evidence/latest.json`

## Recommended Operating Order

For most real workflows, the recommended order is:

1. `vivado_context_mcp`
2. `simulation_acceleration`
3. `vivado_mcp`
4. `vivado_mcp_pro`
5. `vivado_debug_mcp`

In plain language:

1. Use `vivado_context_mcp` first to understand the project.
2. Use `simulation_acceleration` next when the task is mainly RTL/testbench validation.
3. Use `vivado_mcp` when the agent needs direct Vivado project access or interactive Vivado queries.
4. Use `vivado_mcp_pro` when the task needs authoritative execution, evidence capture, or report memory.
5. Use `vivado_debug_mcp` after the design reaches board-level debug and ILA/VIO evidence is needed.

## Recommended Workflow By Question Type

### "What is this project?"

Start with:

- `vivado_context_mcp`

Because the first need is project structure, not Vivado execution.

### "Which files should the agent read first?"

Start with:

- `vivado_context_mcp`

Because relevant-file selection and entry-point discovery are its job.

### "My RTL changed. I want the fastest possible functional feedback."

Start with:

- `simulation_acceleration`

Escalate to:

- `vivado_mcp` or `vivado_mcp_pro` only if Vivado/xsim or Xilinx IP behavior becomes necessary

### "Run synthesis, implementation, or bitstream."

Start with:

- `vivado_mcp_pro`

Because this is an authoritative Vivado workflow, not just project understanding.

### "Read timing and utilization from a real run."

Use:

- `vivado_mcp` for direct access
- `vivado_mcp_pro` when artifact retention, evidence packets, or historical comparison matter

### "The board is running, but I need AI help with ILA/VIO debug."

Use:

- `vivado_debug_mcp`

Because the need is hardware debug inventory, trigger execution, capture
summary, waveform evidence compression, and multi-capture comparison.

### "The project uses Xilinx IP or BD simulation behavior that open-source simulators cannot cover."

Use:

- `vivado_mcp` or `vivado_mcp_pro`

Do not force the workflow through `simulation_acceleration` in this case.

## Practical Positioning

The clean product story is:

- `vivado_context_mcp` is the project-understanding layer.
- `simulation_acceleration` is the fast-verification layer.
- `vivado_mcp` is the core Vivado access layer.
- `vivado_mcp_pro` is the authoritative execution and evidence layer.
- `vivado_debug_mcp` is the headless hardware-debug evidence layer.

That means the suite covers several different bottlenecks:

- too much project context
- too-slow simulation feedback
- too-little Vivado control
- too-much raw Vivado output for AI agents
- too-much raw waveform and debug session data for AI agents

## What The Suite Looks Like To A Customer

An external customer does not need to think in repo boundaries first. The cleaner
message is:

1. The agent first gets a compact project map.
2. The agent then gets a fast simulation path for everyday RTL iteration.
3. The agent can still call real Vivado when the task requires authority.
4. Large Vivado outputs can be stored locally and summarized instead of repeatedly re-read.
5. Board-level ILA/VIO debug captures can be summarized, compared, and reused as compact evidence.

## Boundary Rules

- Do not market `vivado_context_mcp` as a Vivado replacement.
- Do not market `simulation_acceleration` as a replacement for all Xilinx-integrated simulation.
- Do not force `vivado_mcp_pro` to also become the project-map layer.
- Do not blur `vivado_mcp` and `vivado_mcp_pro` into the same customer promise.
- Do not market `vivado_debug_mcp` as an autonomous bug-finding agent.
- Do not use raw debug captures as the default AI input when compact summaries are available.

## One-Sentence Mapping

- `vivado_context_mcp`: understand the project
- `simulation_acceleration`: validate fast
- `vivado_mcp`: access Vivado
- `vivado_mcp_pro`: run Vivado with evidence
- `vivado_debug_mcp`: debug hardware with compact ILA/VIO evidence
