# Customer Install Flow

Goal: make RepoKey usable by AI in a customer project without relying on a
developer's global MCP configuration.

## Install

Run the customer setup scripts from the RepoKey package:

```powershell
RepoKey-Setup.cmd
RepoKey-MCP-Setup.cmd
```

The setup flow should install or prepare:

- RepoKey Vivado tools.
- PL-PS Handoff CLI.
- Vitis MCP package when PS/Vitis workflows are enabled.
- PL QoR MCP package.
- Optional Vivado Debug MCP (`tools\ai_vitis_vivado_stack\vivado_debug_mcp`).
- Optional Vivado Context MCP (`tools\ai_vitis_vivado_stack\vivado_context_mcp`).
- MCP registration templates.
- Project-local AI entry templates.

## Project Entry

Copy the local AI entry template into the target project:

```powershell
copy <repokey_package>\templates\AI_AGENT_START_HERE.local.md <project_root>\AI_AGENT_START_HERE.local.md
```

Edit placeholders documented in `TEMPLATE_VARIABLES.md`.

The AI should start from:

```text
<project_root>/AI_AGENT_START_HERE.local.md
```

## Optional MCP Registration

Customers may register MCP servers using:

```text
MCP_REGISTRATION_TEMPLATE.json
```

Do not force global MCP registration during setup. Some customers will prefer
manual registration or project-local invocation.

The optional hardware debug server (`vivado-debug`) is installed and registered
only when the customer explicitly chooses it:

```powershell
install\register_debug_mcp.ps1
```

`vivado-debug` 已内置到 repokey.exe，无需 Python 或网络安装；注册脚本只写
AI 客户端的 MCP 配置。

## Smoke Test

Run:

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

Expected:

- Vitis MCP import OK.
- PL QoR MCP import OK.
- Vivado Debug MCP import OK when installed.
- Vitis debug status OK when the project contains compatible Vitis helpers.
- PL QoR probe OK when Vivado path is available.

## Recommended Customer Workflow

1. AI reads `AI_AGENT_START_HERE.local.md`.
2. AI uses RepoKey Vivado MCP to gather local Vivado/PL evidence.
3. AI uses PL-PS Handoff to generate or update `control_handoff.*` and
   `ps_delivery.xlsx`.
4. AI uses PL QoR MCP to capture timing/fanout/QoR baselines.
5. AI uses Vitis MCP only for PS/Vitis/runtime verification.
6. AI uses AMD Doc MCP only for official tool semantics.
7. Human authorizes all design-intent changes.

## Packaging Note

Do not edit `RepoKey-Setup.cmd` until the final customer package layout is
selected. First ship the templates and docs, then wire setup scripts to copy
them.
