# Vivado AI MCP Evidence Store

This document defines the shared local evidence store used by the Vivado AI MCP
tool suite.

The goal is to give AI agents compact, reusable FPGA evidence without forcing
them to rescan source trees, reread large reports, or ingest raw waveform data on
every request.

## Directory

Each customer project should store generated AI evidence under the project root:

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

This directory is project-local. It is not a global database, and it should not
modify customer source files.

Recommended `.gitignore` entry:

```text
.vivado_ai_mcp/
```

Teams that want reviewable debug records may selectively keep small summary files
in source control, but raw logs, waveforms, run folders, and captures should stay
local by default.

## Tool Ownership

Each tool owns one namespace:

- `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`

Tools should not write into another tool namespace except through explicit shared
APIs or documented migration code.

## Recommended Layout

```text
.vivado_ai_mcp/
  context/
    project_summary.json
    agent_summary.md
    context_report.md
    hierarchy.json
    relevant_files.json

  simulation/
    runs/
      20260706_153000_xsim_smoke/
        manifest.json
        summary.json
        failures.json
        waveform_summary.json
        raw/

  implementation/
    runs/
      20260706_154500_impl_1/
        manifest.json
        timing_summary.json
        utilization_summary.json
        drc_summary.json
        raw/

  debug/
    sessions/
      20260706_160000_ethernet_tx_issue/
        session.json
        inventory.json
        trigger_plan.json
        capture_001_summary.json
        capture_001_events.json
        capture_002_summary.json
        compare_001_002.json
        notes.md
        raw/

  evidence/
    index.json
    latest.json
```

## Evidence Levels

Every stored result should prefer three evidence levels:

- `summary`: compact data intended for normal agent calls
- `details`: medium-size structured data for follow-up questions
- `raw`: original logs, reports, waveforms, or tool outputs

Agents should read `summary` first and request `details` or `raw` only when the
task requires it.

## Manifest

Each run or session should include a `manifest.json`.

Recommended fields:

```json
{
  "schema_version": 1,
  "tool": "vivado_debug_mcp",
  "tool_version": "0.1.0",
  "project_root": "D:/work/project",
  "xpr_path": "D:/work/project/project.xpr",
  "vivado_version": "2023.2",
  "created_at": "2026-07-06T16:00:00+08:00",
  "purpose": "ethernet_tx_issue",
  "inputs": {
    "source_hashes": {},
    "constraint_hashes": {},
    "bitstream_hash": null,
    "ltx_hash": null
  },
  "outputs": {
    "summary": "capture_001_summary.json",
    "raw_dir": "raw"
  },
  "stale": false,
  "stale_reason": null
}
```

The exact fields may evolve, but every manifest should identify:

- the producing tool
- the project and Vivado version
- the input artifacts used
- the output artifacts produced
- whether the evidence is still valid

## Cache Validity

Cached evidence must not be trusted blindly. A tool should mark evidence stale
when important inputs change.

Typical invalidation inputs:

- `.xpr` file changes
- RTL source changes
- constraint changes
- block design changes
- IP metadata changes
- bitstream or `.ltx` changes for hardware debug
- Vivado version changes when the result depends on Vivado behavior

It is acceptable to use file size and modification time for fast local checks.
For stronger checks, tools may store content hashes.

## Global Index

`evidence/index.json` is the project-local catalog of all evidence records.

Recommended shape:

```json
{
  "schema_version": 1,
  "project_root": "D:/work/project",
  "records": [
    {
      "id": "20260706_160000_ethernet_tx_issue",
      "kind": "debug",
      "tool": "vivado_debug_mcp",
      "created_at": "2026-07-06T16:00:00+08:00",
      "summary_path": ".vivado_ai_mcp/debug/sessions/20260706_160000_ethernet_tx_issue/capture_001_summary.json",
      "manifest_path": ".vivado_ai_mcp/debug/sessions/20260706_160000_ethernet_tx_issue/manifest.json",
      "status": "valid",
      "tags": ["ila", "ethernet", "tx"]
    }
  ]
}
```

`evidence/latest.json` should point to the most recent useful records by kind:

```json
{
  "context": ".vivado_ai_mcp/context/project_summary.json",
  "simulation": ".vivado_ai_mcp/simulation/runs/latest/summary.json",
  "implementation": ".vivado_ai_mcp/implementation/runs/latest/timing_summary.json",
  "debug": ".vivado_ai_mcp/debug/sessions/latest/session.json"
}
```

## Agent Reading Rules

Agents should:

- read `evidence/latest.json` first when resuming a project
- prefer summaries over raw logs
- ask for stale status before relying on old evidence
- use context evidence before reading large source trees
- use simulation evidence before requesting slow Vivado runs when appropriate
- use debug summaries before requesting raw waveform data

Agents should not:

- treat cached evidence as authoritative when marked stale
- read raw waveform data by default
- ingest whole Vivado run directories unless the user asks for deep diagnosis

## Migration From `.vivado_context`

Older `vivado_context_mcp` versions wrote context output under:

```text
.vivado_context/
```

New versions should write to:

```text
.vivado_ai_mcp/context/
```

Tools may keep read-only fallback support for `.vivado_context/` during the
transition, but new product documentation should use `.vivado_ai_mcp/`.

## Product Boundary

The evidence store is not an AI agent and not a code editor. It is local
infrastructure for compact FPGA evidence.

Its job is to make agents faster and more reliable by giving them structured
project, simulation, implementation, and hardware-debug context.
