# First-Run Package Bootstrap

Use this prompt when the zip is handed to a new AI agent session, including Codex, Claude Code, Cursor, GitHub Copilot, Gemini, or Cline, and you want the agent to absorb the package once, then answer later questions from the local kit without re-reading the whole package every time.

## What This Mode Guarantees

- The agent performs a one-time package orientation for the current agent session.
- The agent verifies the kit structure and search index.
- The agent generates and reads `.ai/context/session-bootstrap.md`, a compact session map of the package.
- Later questions in the same agent session should use `scripts/search_knowledge.py`, `sources/source-manifest.yaml`, and the session map instead of scanning the whole package again.

## What This Mode Cannot Guarantee

- A different agent session will not remember this session's loaded context.
- Binary assets are not read as text. PDFs, images, videos, and sheets are represented through extracted text, notes, metadata, and `sources/source-manifest.yaml`.
- If files change after bootstrap, the agent must rerun validation, indexing, and bootstrap.
- Scripts require Python 3.10+ or uv. First detect Python: use `python3 --version` on macOS/Linux, and `py -3 --version` or `python --version` on Windows. If Python 3.10+ is not available, ask the user before using uv bootstrap, even for Q&A, so local search can run normally. Direct reading of `AGENTS.md`, `kit.yaml`, `search/chunks.jsonl`, `sources/source-manifest.yaml`, and cited files is only the emergency Q&A fallback when the user declines installation or uv/Python setup is blocked.
- Optional stable environment bootstrap: Windows can run `powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1`; macOS/Linux can run `sh bootstrap.sh`. These scripts use local Python when available; otherwise they ask for permission before installing uv and then run scripts through `uv run --python 3.12 python ...`.

## First Message To Send To The Agent

```text
请以 Onboarding Agent Kit 首次包接手模式启动。

执行顺序：
1. 读取 AGENTS.md。
2. 读取 HANDOFF.md。
3. 读取 MAINTAINERS.md。
4. 读取 BOOTSTRAP.md。
5. 读取 .ai/context/README.md、03-workspace-map.md、04-state-ledger.md。
6. 读取 kit.yaml 和 skills/onboarding-buddy/SKILL.md。
7. 先探测 Python：macOS/Linux 执行 python3 --version；Windows 执行 py -3 --version 或 python --version。
8. 如果 Python >= 3.10，运行 python3 scripts/validate_kit.py、python3 scripts/index_knowledge.py、python3 scripts/bootstrap_session.py。
9. 如果没有 Python 3.10+，即使只是问问题，也先询问我是否允许用 bootstrap.ps1/bootstrap.sh 安装 uv 并由 uv 下载托管 Python；只有我拒绝或安装受阻时，才直接读取 search/chunks.jsonl、sources/source-manifest.yaml 和命中文件来应急降级回答。
10. 读取 .ai/context/session-bootstrap.md。
11. 运行 python3 scripts/search_knowledge.py "入职当天要做什么" --top-k 3。

完成后只回复：
- kit 是否可用
- 当前模块/source/index 概况
- 后续同一线程回答问题时将如何检索
- 是否发现 blocker

后续我问问题时，不要重新全量读取整个包；先用 search_knowledge.py 检索，再只打开命中文件。
```

## Subsequent Question Protocol

After bootstrap has completed in the same agent session:

1. Run `python3 scripts/search_knowledge.py "<question>" --top-k 3`.
2. Open only the cited files needed to answer.
3. Check `sources/source-manifest.yaml` before citing source corpus files.
4. If the cited evidence is insufficient, say unresolved and route to the relevant owner.
5. Rerun bootstrap only if the user asks to reset the session or package files have changed.

If Python is unavailable, first ask the user whether to run the uv bootstrap, including before Q&A. Use `search/chunks.jsonl` as the prebuilt local search corpus only when the user declines installation or setup is blocked. Do not perform maintenance, ingestion, index rebuilds, validation, or packaging without Python 3.10+ or user-approved uv bootstrap.
