# RepoKey Vivado AI

RepoKey is the bridge between an AI agent and local Vivado. It lets the agent
inspect Vivado projects, run synthesis and implementation, generate bitstream
and LTX files, check timing/utilization, and handle debug evidence through
RepoKey-managed commands.

## Setup

1. Install Vivado first. Vivado 2020.2 is the primary validated target; other
   versions may need compatibility checks.
2. Run `RepoKey-Setup.cmd`.
3. Select the Vivado installation and project directory, and let the wizard
   register the MCP servers. Without a License, setup continues in free-tier
   mode; with a Pro License, paste it into `licenses\repokey-license.txt`
   before running setup.
4. Restart the AI client completely.
5. Give the generated `AI_AGENT_START_HERE.local.md` to the AI agent.

## Agent Quick Commands

Fresh rebuild from synthesis through bitstream:

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

Use this command before creating temporary Vivado Tcl scripts. It is the
packaged RepoKey path for "rerun from synthesis and generate a new bit".

Run a setup/self-check:

```cmd
repokey-client.cmd mcp-selfcheck
```

Collect support diagnostics:

```cmd
repokey-client.cmd diagnose
```

The default diagnostic bundle excludes `licenses\repokey-license.txt`, redacts
local machine paths and sensitive fields, and stores flow audit records under
the project-local `.vivado_ai_mcp\audit\flow_calls.jsonl` directory. Review the
bundle before sharing it. Do not send the full License or unredacted logs in a
normal support request.

## Directory Map

| Path | Purpose |
|---|---|
| `RepoKey-Setup.cmd` | Main setup wizard. |
| `repokey-client.cmd` | Command-line client used by agents and support. |
| `AGENTS.md` | Rules that AI agents must read. |
| `docs\` | Detailed installation, acceptance, and routing docs. |
| `config\`, `licenses\`, `bin\`, `tools\` | RepoKey runtime and tool payload. |
| `install\` | Setup, registration, and self-test scripts. |

## Rules

Agents must use RepoKey for Vivado control. Do not bypass RepoKey with direct
`vivado.bat`, generated batch Tcl, `runme.bat`, SynthPilot, or another Vivado
MCP server unless the user explicitly asks to debug outside RepoKey.

Design-intent changes require explicit user approval. This includes RTL, XDC,
IP, BD, timing exceptions, clock/reset/CDC changes, debug-core removal, and
manual Vivado run metadata edits.

## License

See `docs\LICENSE_USAGE.md`.
