# Install

## Recommended Customer Flow

1. Extract this package to a stable local directory.
2. Copy the full `RK1...` License from the email.
3. Open this existing empty file and paste the License into it:

```text
licenses\repokey-license.txt
```

4. Double-click:

```text
RepoKey-Setup.cmd
```

5. When asked, enter your Vivado path. Both forms are acceptable:

```text
D:\Xilinx\vivado2020.2\Vivado\2020.2\bin
D:\Xilinx\vivado2020.2\Vivado\2020.2\bin\vivado.bat
```

Do not use `bin\unwrapped\win64.o\vivado.exe`. That internal executable
requires the environment initialized by `vivado.bat` and may exit with Windows
code `0xC0000135`.

The setup wizard checks the License, writes `config\repokey.local.json`, sets the user environment variable `REPOKEY_HOME`, generates `AI_AGENT_START_HERE.local.md`, runs the basic environment check, and automatically attempts idempotent RepoKey MCP registration for every detected supported client, including Codex and Claude Code.

The wizard does not stop the base installation if an AI client is not recognized. In that case it writes `repokey-mcp-config.json`; an MCP-compatible AI client can use that manifest. `RepoKey-MCP-Setup.cmd` is retained as a safe repair/recheck entry point.

Windows normally includes PowerShell. If double-clicking `RepoKey-Setup.cmd` says PowerShell cannot be found, the system is likely a very trimmed Windows environment. Contact WeChat support: `repokey-service`.

## If Setup Fails

- If it says License is missing or invalid, copy the complete `RK1...` text from the License email into `licenses\repokey-license.txt`.
- If it says Vivado path does not exist, copy the correct Vivado `bin` directory or `vivado.bat` path and run `RepoKey-Setup.cmd` again.
- If the issue remains, contact WeChat support: `repokey-service`.

## AI Agent Usage

After `RepoKey-Setup.cmd` passes, verify the package:

```text
RepoKey-Self-Test.cmd
```

Then create the project-local AI entry file:

```text
RepoKey-Init-Project.cmd D:\Customer\YourVivadoProject
```

Give the generated project-root `AI_AGENT_START_HERE.local.md` to your AI Agent first. Do not rely on a developer machine global MCP config.

Important: after the first MCP registration, fully close and restart the AI
client once, for example VS Code/Codex, Claude Code, Claude Desktop, Cursor,
Windsurf, or Cline. The currently open AI window usually cannot see newly
registered MCP tools until the application reloads its MCP configuration.

The setup wizard also writes the user environment variable:

```text
REPOKEY_HOME
```

New terminals and AI sessions can use it to find RepoKey. If a terminal was already open before setup, close and reopen it.

If needed, ask the AI Agent to read:

```text
README.md
AGENTS.md
INSTALL.md
LICENSE_USAGE.md
install\self_test.ps1
```

Then let the AI Agent continue with your Vivado project path and actual task.

## Manual Commands

These commands are optional and mainly for AI Agent or advanced users:

```powershell
powershell -ExecutionPolicy Bypass -File install\self_test.ps1
powershell -ExecutionPolicy Bypass -File install\check_env.ps1
repokey-client.cmd license-status
repokey-client.cmd check-env
repokey-client.cmd build-info
  repokey-client.cmd vivado --help
RepoKey-Init-Project.cmd D:\Customer\YourVivadoProject
RepoKey-MCP-Setup.cmd
```

Large third-party toolchains are not auto-downloaded by default.

## Required MCP Connection

For Free/Core Vivado access, the AI client must register this command as an MCP
stdio server:

```text
<RepoKey extracted path>\repokey-client.cmd vivado serve
```

The neutral configuration can be printed with:

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

The setup wizard attempts this registration automatically. If no supported AI
client is detected, use the generated `repokey-mcp-config.json` with the
client's native MCP settings. After registration, fully close and restart the
AI client, then verify that the RepoKey Vivado tools are visible. Opening a new
chat tab inside the same running client may not reload MCP configuration. The
AI must stop if the MCP server cannot be connected.

On later uses, the setup wizard or `RepoKey-MCP-Setup.cmd` first inspects the
existing MCP configuration. If the RepoKey server with the same command and
arguments is already registered, it skips registration and does not add
duplicate entries. A backup is created before changing an existing file.

Do not replace this with another Vivado MCP service, direct Vivado batch
commands, `launch_runs`, or generated run scripts. `vivado install` is optional
and is not required for temporary MCP sessions.
If RepoKey and another Vivado control path are both visible, choose RepoKey for
this package unless the user explicitly asks to debug outside RepoKey.



