# TP-052 — Migrate end-user documentation into the Hugo site

## Mission

Populate the Hextra-based icuvisor.app site (scaffolded in TP-050) with the **end-user-facing** documentation currently scattered across `README.md` and `docs/`. After this task lands, the website is the single home for everything an athlete or coach needs to install, configure, connect, troubleshoot, and understand icuvisor. The project source tree keeps only developer/contributor docs.

Project context: icuvisor is private and pre-launch; no external links to preserve; no migration notices needed. Move files freely.

The migration is organized along Diataxis lines:

- **Install** (how-to) — platform installers and verification.
- **Connect** (how-to) — configure each MCP client.
- **Tutorials** (study + action) — handled by TP-053 (ChatGPT first-steps tutorial), not this task.
- **Guides** (how-to) — task-focused step-by-step.
- **Reference** (work + cognition) — CLI flags, env vars, config file, MCP resources & prompts, safety modes; tool catalog is generated by TP-051.
- **Explain** (study + cognition) — conceptual background.

PRD anchors: §6 KR1 (install success — clear install/connect path), KR5 (token efficiency — long-form content off the binary), §7.4 product principles.

ROADMAP positioning: docs polish for v0.5 internal beta and v1.0 public launch.

Complexity: Blast radius 2 (docs only; no Go code), Pattern novelty 2 (first significant Hextra content authoring), Security 1, Reversibility 1 = 6 → Review Level 1–2. Size: L (high page count, low risk per page).

## Dependencies

- **TP-050** — Hugo + Hextra scaffold with empty section indexes. Required (blocking).
- **TP-055** — Reconcile three doc conflicts. Required (blocking). The migration must consume corrected PRD/ROADMAP/README truth; do not start this task until TP-055 has landed.
- **TP-051** — Tool catalog generator. Recommended to land first so this task does **not** hand-author the tool list. If TP-051 has not landed, leave `reference/tools.md` as a stub frontmatter file with a `TODO: generator lands in TP-051` note in `STATUS.md`.

## Context to Read First

- `CLAUDE.md`
- `README.md` (the whole thing — this task replaces large chunks of it on the website side; the README rewrite itself is TP-054)
- `docs/install/macos.md`
- `docs/clients/claude-desktop.md`
- `docs/clients/claude-code.md`
- `docs/clients/codex-local.md` (read to confirm it is **developer** content and stays in `docs/`)
- `docs/coach-mode.md`
- `docs/post-update.md`
- `docs/prd/PRD-icuvisor.md` §7.2.A (config), §7.2.D (transport), §7.2.E (delete/write safety), §7.2.F (toolset tiers), §7.2.G (resources & prompts) — these are the upstream truth for the reference pages.
- `internal/config/`, `internal/safety/`, `internal/toolset/`, `internal/prompts/` — verify env-var names and behaviour against code, not just prose.

## File Scope

### Migrate from `docs/` (move + adapt to end-user voice)

| Source | Destination | Notes |
|---|---|---|
| `docs/install/macos.md` | `web/content/install/macos.md` | Strip maintainer release-signing checklist (developer-only); keep Gatekeeper verification + uninstall. |
| `docs/clients/claude-desktop.md` | `web/content/connect/claude-desktop.md` | End-user voice; keep smoke checklist as collapsible section. |
| `docs/clients/claude-code.md` | `web/content/connect/claude-code.md` | Same. |
| `docs/coach-mode.md` | Split: user slice → `web/content/guides/coach-mode.md` and `web/content/explain/coach-mode.md` | Step-by-step setup is a how-to; conceptual model + ACL philosophy is an explanation. |
| `docs/post-update.md` | `web/content/guides/after-upgrade.md` | End-user voice. |

**Stays in `docs/` (developer / heavy-user; not migrated):**

- `docs/clients/codex-local.md`
- `docs/prd/`, `docs/dogfood/`, `docs/internal-beta/`, `docs/safety/`, `docs/threat-models/`, `docs/upstream-gaps/`, `docs/kr5-benchmark.md`

Deletion of the migrated source files is handled in TP-054 (so README link updates and source deletions land together).

### Extract from `README.md` into the website

The following README sections become website pages; this task creates the website pages. The README slim-down itself is TP-054.

| README section | Destination | Type |
|---|---|---|
| §Quickstart + §"Getting an API key" + keychain manual storage | `web/content/install/_index.md` (overview) and `web/content/guides/api-key.md` (how-to) | how-to |
| §"MCP transport" | `web/content/guides/http-transport.md` (how-to: enable + LAN warning) and `web/content/reference/cli.md` (flags) | how-to + reference |
| §"Delete/write safety mode" | `web/content/reference/safety-modes.md` (table) + `web/content/explain/safety-modes.md` (why) | reference + explanation |
| §"Toolset tiers" | Merged into the same two pages above (reference + explanation). One page per concept, not one per env var. | reference + explanation |
| §"MCP resources" | `web/content/reference/resources-prompts.md` | reference |
| §"MCP prompts" | Same page as above. | reference |
| §Features (planned for v1.0) | Move only the marketing-tone bullets to landing if not already there; remove from website otherwise. The landing already covers this. | n/a |

### New pages (no existing source — write from scratch using code as truth)

- `web/content/reference/cli.md` — CLI flags, env vars, exit codes. **Authoritative source: `./bin/icuvisor --help` output** (TP-035 made `--help` the SoT for the CLI surface). Render the help fixture verbatim under a "Full `--help` output" section and add inline explanatory prose around it. Re-render whenever `--help` golden test changes.
- `web/content/reference/config-file.md` — JSON config field reference (`athlete_id`, `timezone`, `api_base_url`, `http_timeout`, `transport`, `http_bind`). Cross-reference: `internal/config/`.
- `web/content/explain/what-is-mcp.md` — One-paragraph intro to MCP for non-technical users; link to <https://modelcontextprotocol.io>.
- `web/content/explain/local-first.md` — Why the API key lives in the OS keychain; what "local-first" means; how data never leaves the user's machine.
- `web/content/explain/terse-by-default.md` — Why responses are terse; what `include_full` does conceptually; link to the explanation of toolset tiers.
- `web/content/guides/troubleshooting.md` — Symptom-to-fix table covering: Gatekeeper rejection, missing API key, stale schema after upgrade (links to `after-upgrade.md`), transport refused on LAN, key-not-found on Linux without libsecret.

### Cross-references and links

- Every page that mentions a tool name links to the tool's anchor on `/reference/tools/` (which TP-051 generates).
- Every page that mentions an env var links to `/reference/cli/` (or `/reference/safety-modes/` for `ICUVISOR_DELETE_MODE` / `ICUVISOR_TOOLSET`).
- Internal links use Hugo relative-ref syntax (`[text]({{< relref "..." >}})`) so Hugo can validate them at build time.
- No bare `project docs links` links from website pages — every link is either a relref to another website page or to a top-level GitHub artifact (`README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `ROADMAP.md`, the PRD).

## Steps

### Step 1: Inventory + audit

- [ ] Read every source file listed above. Note any factual claim that differs from `internal/` code (env var names, defaults, exit codes). If a discrepancy exists, code wins; flag in `STATUS.md`.
- [ ] Confirm TP-055 has landed. Verify the three known doc conflicts (analyzer family / `get_planning_parameters` / `update_wellness` error contract) are resolved in PRD / ROADMAP / README before authoring any migrated page. If TP-055 has **not** landed, **stop** and surface the blocker — do not migrate content against inconsistent upstream docs.

### Step 2: Reference section first

Why first: the rest of the site links into reference pages.

- [ ] `reference/cli.md` — render from `internal/app/testdata/help_golden.txt` (created by TP-035) or by running the binary. Add prose framing.
- [ ] `reference/safety-modes.md` — table of `ICUVISOR_DELETE_MODE` and `ICUVISOR_TOOLSET` values, what's registered at each, the `_meta.delete_mode` and `_meta.toolset` echo behaviour.
- [ ] `reference/config-file.md` — JSON schema-style field reference.
- [ ] `reference/resources-prompts.md` — four resources (`icuvisor://workout-syntax`, `…/event-categories`, `…/custom-item-schemas`, `…/athlete-profile`) and five prompts (`training_analysis`, `recovery_check`, `weekly_planning`, `race_week_taper`, `coach_roster_triage`). Pull descriptions from `internal/prompts/` registry, not from the README — code is truth.
- [ ] `reference/tools.md` — frontmatter stub if TP-051 has not landed yet; otherwise the page authored by TP-051.

### Step 3: Install section

- [ ] `install/_index.md` — overview chooser (macOS / Windows / Linux / build from source). Build-from-source links to GitHub, not to a website page (it is developer content).
- [ ] `install/macos.md` — adapted from `docs/install/macos.md`. Drop maintainer release-signing checklist. Keep Gatekeeper verification, DMG drag-to-Applications, MCP executable path.
- [ ] `install/windows.md` — placeholder "Coming with v1.0. Build from source: [link]" until installers exist.
- [ ] `install/linux.md` — same placeholder.

### Step 4: Connect section

- [ ] `connect/_index.md` — chooser: Claude Desktop, Claude Code, ChatGPT, Cursor, Continue, Zed, "other MCP clients".
- [ ] `connect/claude-desktop.md` — from `docs/clients/claude-desktop.md`; end-user voice; smoke checklist as a collapsible details block.
- [ ] `connect/claude-code.md` — from `docs/clients/claude-code.md`.
- [ ] `connect/chatgpt.md` — new; minimal "point ChatGPT's MCP plugin at the binary, paste the JSON below" snippet. Tutorial detail lives in `tutorials/getting-started-chatgpt.md` (TP-053); this page is a focused how-to.
- [ ] `connect/other-clients.md` — pointers for Cursor / Continue / Zed / Pi using the same JSON shape as Claude Desktop.

### Step 5: Guides section

- [ ] `guides/api-key.md` — how to get an intervals.icu API key + store it via `icuvisor setup` (the recommended path) + manual keychain commands per OS (extracted from current README §"Getting an API key"). End-user voice.
- [ ] `guides/http-transport.md` — how to enable Streamable HTTP; loopback default; explicit LAN warning per CLAUDE.md hard rule #7.
- [ ] `guides/coach-mode.md` — user-facing setup steps from `docs/coach-mode.md`.
- [ ] `guides/after-upgrade.md` — from `docs/post-update.md`; what `_meta.schema_changed` means in plain English; the "open a new AI-client conversation" advice.
- [ ] `guides/troubleshooting.md` — new symptom→fix table.

### Step 6: Explanation section

- [ ] `explain/what-is-mcp.md`
- [ ] `explain/local-first.md`
- [ ] `explain/terse-by-default.md`
- [ ] `explain/safety-modes.md` — the **why** of safe/full/none; pair with `reference/safety-modes.md` for the table.
- [ ] `explain/coach-mode.md` — conceptual model: server-held key, `athlete_id` as selector not credential, per-athlete ACLs.

### Step 7: Reconcile content with code (drift sweep)

- [ ] Grep website pages for every env-var, flag, and tool name. Cross-check against `internal/`.
- [ ] Grep website pages for every JSON shape. Confirm against `internal/` types.
- [ ] If a discrepancy appears, **code wins** — update the website prose. Do not change Go code in this task.

### Step 8: Build + link check

- [ ] `cd web && hugo --minify --gc`. Zero broken relrefs.
- [ ] Pagefind index includes all new pages (verify by running a search for a tool name and an env var).
- [ ] Manually click through every nav entry; every link lands somewhere valid.

## Acceptance Criteria

- Every end-user-facing file in `docs/` has a corresponding page on the Hugo site, adapted to end-user voice.
- Every end-user-facing README section has a Hugo page (reference, how-to, or explanation as appropriate).
- The site builds cleanly with no broken internal links.
- Tool names, env-var names, and config fields on every page match the values in `internal/` source.
- Pagefind search finds env vars, tool names, and config fields.
- Developer-only content (`docs/prd/`, `docs/dogfood/`, `docs/internal-beta/`, `docs/safety/`, `docs/threat-models/`, `docs/upstream-gaps/`, `docs/kr5-benchmark.md`, `docs/clients/codex-local.md`) is untouched and stays in `docs/`.
- Source files in `docs/` are **not deleted** in this task (TP-054 owns deletion + README link updates).
- `STATUS.md` records any code-vs-prose discrepancies discovered and notes whether TP-055 has landed.

## Do NOT

- Do not delete source files in `docs/` — TP-054 handles that.
- Do not edit `README.md` in this task — TP-054 handles that.
- Do not hand-author the tool catalog list — TP-051 generates it.
- Do not move developer content (`codex-local.md`, PRD, dogfood, internal-beta, threat-models, kr5-benchmark, upstream-gaps) onto the website.
- Do not paste maintainer release-signing instructions onto the website — those stay in `docs/`.
- Do not add emojis (per CLAUDE.md).
- Do not introduce a JavaScript build step.
- Do not invent env-var names, default values, or exit codes — read them from `internal/`.

## Documentation

Must update:

- `STATUS.md` — code-vs-prose discrepancies; whether TP-055 dependencies were met.
- `CHANGELOG.md` `[Unreleased]` under "Changed": "User-facing docs migrated to icuvisor.app".

## Git Commit Convention

Commit at step boundaries with messages prefixed by `TP-052`, e.g., `TP-052 author reference section`.

---

## Amendments

_Add amendments below this line only._
