AIROOT INSTALL RETRO PROMPT

# AIRoot Install Retro Prompt

Date: `2026-06-18`
Status: `active public prompt`

## Purpose

Use this prompt after installing or onboarding `AIRoot` into a new client repo
when setup failed, felt confusing, required manual workaround, or succeeded only
after undocumented help.

The goal is to collect a structured install retro report that can improve:
- `AI_EASY_SETUP.md`
- `AI_ASSISTED_SETUP_PROMPT.md`
- `AIROOT_SETUP_PROTOCOL.md`
- setup scripts under `AIRoot/scripts/`
- generated routers, setup checks, and recovery diagnostics

This prompt is intentionally about AIRoot setup itself. It is not a normal
project work prompt and it is not the XUUnity Light Unity MCP install retro.

## Use When

- the easy setup path did not get the client to a working repo
- the AI-assisted setup prompt produced unclear or wrong actions
- the client tried to set up AIRoot manually and got stuck
- `.sh`, `.cmd`, `.bat`, `.ps1`, Git Bash, PowerShell, `cmd.exe`, WSL, or an AI
  client terminal behaved differently than expected
- a script failed because of CRLF/LF line endings, executable bits, shell
  selection, path quoting, or missing Bash
- clone, auth, local folder selection, or "open the repo root" was confusing
- the agent started from the wrong directory or tried to mutate the `AIRoot`
  repo itself instead of a host repo containing `AIRoot/`
- topology classification was ambiguous: single-project versus monorepo
- `--dry-run`, apply, `--check`, or `--fix` failed
- `Agents.md`, `AIOutput/Registry/setup_status.yaml`,
  `AIOutput/Registry/host_topology.yaml`, project routers, or
  `Assets/AIOutput/ProjectMemory/` did not appear as expected
- setup succeeded but the next user-facing step was unclear

## Do Not Use When

- normal project work is already running through `xuunity`
- the problem is specifically XUUnity Light Unity MCP package installation or
  MCP client wiring; use the MCP install retro prompt for that surface
- the report would require exposing private source, secrets, tokens, passwords,
  private repo URLs, customer names, or unrelated logs

## Redaction Rule

Before sharing the report, replace private values with stable placeholders:

- `<client-repo>`
- `<host-root>`
- `<unity-project>`
- `<user-home>`
- `<private-remote>`
- `<ai-client>`

Do not include API keys, auth tokens, passwords, private SSH keys, private repo
URLs with credentials, machine usernames, or full unrelated logs.

Keep useful public-safe evidence:
- OS and shell names
- AIRoot commit, tag, or branch
- command names
- sanitized paths
- exact error codes and short error excerpts
- Git line-ending metadata
- setup script output
- generated file presence or absence

## Inputs To Gather First

At minimum, collect:

1. OS and version.
2. Shell or terminal used for each command: PowerShell, `cmd.exe`, Git Bash,
   WSL, macOS Terminal, VS Code terminal, AI client terminal, or other.
3. AI client used: VS Code, ChatGPT desktop, Codex CLI, Claude Desktop, Claude
   Code, Cursor, Rider, or other.
4. Whether the AI client had local folder access and terminal execution.
5. Repo clone URL source, redacted as `<private-remote>` if needed.
6. Local folder chosen, redacted as `<host-root>`.
7. Whether the opened folder was the host repo root or `AIRoot/` itself.
8. AIRoot version evidence: commit, branch, tag, or archive date.
9. Which setup doc was followed first.
10. Exact commands attempted, in order, with current directory for each.
11. First visible error, before any retry changed state.
12. Any manual workaround applied.
13. Whether files were modified by setup before the failure.
14. Which generated files exist now and which are missing.
15. If Windows or mixed shell behavior was involved, the launcher flavor for
    each command: `.sh`, `.cmd`, `.bat`, `.ps1`, direct `bash`, direct `python`,
    Git Bash, PowerShell, `cmd.exe`, WSL, or AI client stdio.

If a command cannot run, record the command, current directory, and exact error
instead of guessing.

## Preferred Command Evidence

Run only the commands that match the actual setup route. Prefer `--dry-run`
before mutating setup.

### Cross-platform repo facts