# AI Agent Start Here

This file is the project-local entry point for AI agents working with RepoKey.
Read it before scanning the project or running tools.

Charter: `REPOKEY_OPERATING_CHARTER.md` in the RepoKey docs tree. Customer
copies of this file keep the same First Rule / routing / red lines.

## Project Variables

Replace these values after copying this file into a project:

```text
PROJECT_ROOT={{PROJECT_ROOT}}
PS_PROJECT_ROOT={{PS_PROJECT_ROOT}}
REPOKEY_ROOT={{REPOKEY_ROOT}}
AI_STACK_ROOT={{AI_STACK_ROOT}}
VIVADO_PATH={{VIVADO_PATH}}
VITIS_PATH={{VITIS_PATH}}
VIVADO_CONTEXT_SRC={{VIVADO_CONTEXT_SRC}}
VITIS_MCP_CONFIG={{VITIS_MCP_CONFIG}}
PL_QOR_MCP_CONFIG={{PL_QOR_MCP_CONFIG}}
AMD_DOC_MCP_ENDPOINT={{AMD_DOC_MCP_ENDPOINT}}
```

`PS_PROJECT_ROOT` is optional. Skip it for PL-only projects. When PS and
Vivado roots differ, use it for `debug ps-run` / `ps-status`.

## First Rule

Tools provide evidence. AI makes engineering decisions within evidence and
safety boundaries. Humans authorize design-intent changes.

Tools = evidence / feedback / guardrails. AI = engineering decisions from
evidence. Humans = authorize design-intent changes.

## Shortest Path, Do Not Complete The Set

Take the shortest available evidence path. Do not treat the sections below
as a checklist that must all run. Missing optional tools or project-local
helpers are a minimum-optional-set recommendation, not a prerequisite.

## Tool Routing

Use the tool that owns the fact:

- RepoKey Vivado MCP: Vivado project, BD/IP/OOC, ILA/VIO, bitstream/LTX,
  Hardware Manager, PL evidence.
- Vivado Debug MCP / `repokey-client.cmd debug`: on-board program, PS run,
  live ILA capture, structured debug sessions. This is the RepoKey-owned
  debug path.
- PL-PS Handoff: PS-facing PL control delivery artifacts.
- PL QoR MCP: timing, fanout, utilization, QoR baseline, decision records, QoR
  comparison, reviewed experiment Tcl generation.
- Vitis MCP: generic Vitis build/run and XSCT when registered. Not a
  required wrapper over project-local helpers.
- AMD Doc MCP: official Vivado/Vitis/XDC/HLS/IP semantics.
- Vivado Context MCP (optional): low-token project context under
  `.vivado_ai_mcp/context`.

## Vivado Build Flow

For a fresh rebuild from synthesis through bitstream, use the packaged RepoKey
flow command first:

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd flow --project-root {{PROJECT_ROOT}} --synth-run synth_1 --impl-run impl_1 --reset
```

This resets the configured synthesis and implementation runs, launches the
RepoKey-managed flow, polls progress, writes bitstream/LTX, and records
evidence. Do not create temporary Vivado batch Tcl for this task.

Use individual RepoKey Vivado MCP tools only when the user asks for
step-by-step control, live session inspection, or recovery of a specific run
stage.

## PL-PS Handoff

Use this when the task is to explain PL controls to PS, generate a handoff table,
compare an old Excel register map, or prepare PS delivery.

Generate the default handoff:

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

Expected outputs:

```text
pl_ps_handoff/
  control_handoff.xlsx
  control_handoff.json
  control_handoff.md
  ps_delivery.xlsx
  evidence.md
  ai_reading_guide.md
```

Use `control_handoff.xlsx` as the PL engineer review workbook. Use
`ps_delivery.xlsx` as the PS-facing delivery workbook.

Compare legacy Excel:

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd handoff compare-legacy {{PROJECT_ROOT}}\pl_ps_handoff\control_handoff.json <legacy.xlsx> --output {{PROJECT_ROOT}}\pl_ps_handoff\legacy_compare.json
{{REPOKEY_ROOT}}\repokey-client.cmd handoff merge-template {{PROJECT_ROOT}}\pl_ps_handoff\legacy_compare.json --output {{PROJECT_ROOT}}\pl_ps_handoff\merge_decision.json
```

Apply reviewed semantics:

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd handoff apply-feedback {{PROJECT_ROOT}}\pl_ps_handoff\control_handoff.json feedback_patch.json --output {{PROJECT_ROOT}}\pl_ps_handoff_patched --summary-json
{{REPOKEY_ROOT}}\repokey-client.cmd handoff delivery-from-review {{PROJECT_ROOT}}\pl_ps_handoff\control_handoff.json {{PROJECT_ROOT}}\pl_ps_handoff\control_handoff.xlsx --output {{PROJECT_ROOT}}\pl_ps_delivery_reviewed --summary-json
```

Handoff may write delivery artifacts. It must not modify Vivado RTL, XDC, XCI,
BD, or implementation outputs.

## PL QoR

Use PL QoR MCP when it is registered and visible. If the MCP namespace is not
visible, use the CLI adapter as the supported fallback and say that PL QoR MCP
registration is optional for this package.

QoR evidence belongs to the Vivado project, not the RepoKey tool directory.
Write QoR output under:

```text
{{PROJECT_ROOT}}\.vivado_ai_mcp\qor
```

This package ships the pl_optimizer_compat helper scripts under
`tools\ai_vitis_vivado_stack\pl_optimizer_compat\scripts` (used as the local PL
QoR adapter path). Prefer the registered PL QoR MCP tools when available:
`pl_qor_probe`, `pl_qor_collect_baseline`, `pl_qor_decide`, `pl_qor_compare`,
and `pl_qor_make_experiment`.

Do not run optimization experiments automatically. `make-experiment` only
generates reviewed Tcl/manifest files.

## PL Debug Quick Start

When a board is connected and the question is about ILA/VIO or waveform
evidence, use the RepoKey debug path. Do not require project-local helpers.

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd debug preflight --project-root {{PROJECT_ROOT}}
{{REPOKEY_ROOT}}\repokey-client.cmd debug program --bit <PL.runs\impl_1\top.bit> --ltx <PL.runs\impl_1\top.ltx>
{{REPOKEY_ROOT}}\repokey-client.cmd debug ps-run --project-root {{PS_PROJECT_ROOT}} --platform <platform> --skip-fpga --xsct <xsct.bat>
{{REPOKEY_ROOT}}\repokey-client.cmd debug live-capture --ila hw_ila_1 --ltx <top.ltx> --out-csv {{PROJECT_ROOT}}\.vivado_ai_mcp\debug\captures\hw_ila_1.csv
{{REPOKEY_ROOT}}\repokey-client.cmd debug ila-csv-summary --csv <that csv>
{{REPOKEY_ROOT}}\repokey-client.cmd debug write-session --project-root {{PROJECT_ROOT}} --issue-name <short_issue>
```

Keep captures and session evidence under the project:

```text
{{PROJECT_ROOT}}\.vivado_ai_mcp\
  debug\
    sessions\
      <timestamp>_<issue_name>\
    captures\
  evidence\
    index.json
    latest.json
```

Notes:

- After batch `program`, always pass `--ltx` on `live-capture`.
- Identify ILA cores by probe names; `hw_ila_*` index may not match LTX order.
- If a Vivado GUI holds JTAG, release the hw_target before batch program.
- Project-local CSV analyzers or persistent-session helpers are optional
  reference after the generic capture, never a required step.

## Vitis / PS

Use Vitis MCP for generic PS/Vitis evidence only when this project actually
has PS/Vitis collateral and the MCP is registered. For PL-only projects,
skip Vitis checks and say they are not applicable.

For PS-side code understanding, prefer a RepoKey/Vitis `ps_context_summary`
when it exists. It writes:

```text
{{PROJECT_ROOT}}\.vivado_ai_mcp\ps_context\project_summary.json
{{PROJECT_ROOT}}\.vivado_ai_mcp\ps_context\agent_summary.md
```

It does not modify PS code, run XSCT, or parse PL.

### Optional local reference (not required)

If the customer project ships its own helpers, they may be used **after**
the RepoKey path, and only when the user wants project-specific RF/ILA
semantics. If a helper is missing, skip it. A missing project-local tree
is not a failed smoke or a blocked debug path.

Use live PS/JTAG commands only when the board is powered and the user expects
hardware access.

## PS Run / Debug (Zynq)

RepoKey can independently program the bitstream, initialize the PS, download
the core ELFs and run the cores over XSCT. No external PS helper scripts
are required. Running the PS is what lets PS-configured PL interfaces start
their clocks, so ILAs clocked by PS-driven logic become visible only after
the PS has run.

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd debug ps-run --project-root {{PS_PROJECT_ROOT}} --platform <platform> --bit <PL.runs\impl_1\top.bit> --xsct <xsct.bat>
{{REPOKEY_ROOT}}\repokey-client.cmd debug ps-halt --project-root {{PS_PROJECT_ROOT}} --platform <platform> --xsct <xsct.bat>
{{REPOKEY_ROOT}}\repokey-client.cmd debug ps-status --project-root {{PS_PROJECT_ROOT}} --platform <platform> --xsct <xsct.bat>
```

`ps-run` performs, in one XSCT session: `fpga -file <bit>` (or `--skip-fpga`
to reuse a programmed bit) -> `source <ps7_init>` + `ps7_init` +
`ps7_post_config` -> `rst -processor` + `dow` of core0 and core1 ELFs ->
`con` on both cores (dual-core AMP). Use `ps-halt` to stop a core and dump
registers/backtrace, and `ps-status` to list targets / read core0 PC.

Defaults (project-relative, override with flags): ps7_init =
`<root>\<platform>\hw\ps7_init.tcl`, core0 ELF =
`<root>\demo_core0\Debug\demo_core0.elf`, core1 ELF =
`<root>\demo_core1\Debug\demo_core1.elf`. `ps-run-tcl` writes the generated
script without running it.

The PS project artifacts (ps7_init, ELFs, XSA) are customer-specific build
outputs; RepoKey provides the run/debug flow and locates them in the project.

Additional general PS debug helpers (all project-agnostic):

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd debug ps-read-symbol --project-root {{PS_PROJECT_ROOT}} --elf0 <core0.elf> <symbol> --xsct <xsct.bat>
{{REPOKEY_ROOT}}\repokey-client.cmd debug ps-write-symbol --project-root {{PS_PROJECT_ROOT}} --elf0 <core0.elf> <symbol> <value> --xsct <xsct.bat>
{{REPOKEY_ROOT}}\repokey-client.cmd debug ps-continue --project-root {{PS_PROJECT_ROOT}} --xsct <xsct.bat>
{{REPOKEY_ROOT}}\repokey-client.cmd debug ps-addr2line --elf <core0.elf> <pc0> <pc1> ...
{{REPOKEY_ROOT}}\repokey-client.cmd debug bit-backup --bit <PL.runs\impl_1\top.bit> --ltx <top.ltx> --label <label>
```

## Labtools Server Reset

When a hardware session stalls because a stale `hw_server` / `cs_server` holds
ports 3121 / 3042, do not keep retrying a failing program/capture. Run a clean
server reset instead:

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd debug server-status
{{REPOKEY_ROOT}}\repokey-client.cmd debug server-kill --dry-run
{{REPOKEY_ROOT}}\repokey-client.cmd debug server-reset --vivado {{VIVADO_PATH}}
```

`server-reset` kills every server process on ports 3121/3042/9999 plus
`hw_server.exe`/`cs_server.exe`, restarts them, waits for the ports, and
reports the fresh state. Add `--kill-vivado` to also close `vivado.exe`
(review first: it can interrupt an open Vivado GUI). Then rerun
`debug preflight` before `program`/`live-capture`.

## AMD Official Docs

Use AMD Doc MCP when official tool semantics matter:

```text
{{AMD_DOC_MCP_ENDPOINT}}
```

Required before recommending or applying:

- false path or multicycle constraints.
- clock/reset/CDC/RDC interpretation.
- Vivado implementation strategy changes.
- Vitis/XSCT behavior whose semantics are uncertain.
- Vitis HLS pragma/interface changes.
- AMD/Xilinx IP parameter interpretation.

AMD Doc MCP is not local project evidence. Pair it with RepoKey/Vitis evidence.

## Red Lines

Do not automatically do these:

- Modify RTL, XDC, XCI, BD, or Tcl project files.
- Manually edit Vivado run metadata such as `.vivado.begin.rst`,
  `.vivado.end.rst`, `.synth_design.begin.rst`, or `.synth_design.end.rst`.
  If run metadata looks stale or inconsistent, use a RepoKey repair tool
  and record evidence; do not patch these files by hand.
- Execute PL optimization experiments.
- Add false path or multicycle path constraints.
- Change latency, AXI/stream protocol, CDC/RDC, clock/reset architecture.
- Change PS/PL handoff register semantics or address maps.
- Change RF front-end data alignment or behavior.

When any red line is involved, stop and ask for explicit human authorization.

## Smoke Tests

After setup, run the stack smoke test only if the script exists. Do not
require project-local helpers for a pass.

```powershell
if (Test-Path "{{AI_STACK_ROOT}}\scripts\smoke_test_mcp_stack.py") { python {{AI_STACK_ROOT}}\scripts\smoke_test_mcp_stack.py } else { Write-Host "RepoKey stack smoke script not packaged; skip optional smoke test." }
```

Expected result (imports only; local helper status is optional):

```text
ok: true
vitis_mcp_import: OK
pl_qor_mcp_import: OK
pl_qor_probe: OK
```
