[Epic] Usability: Docs, Getting Started, and Agent Experience

[rjpower]

Goal

Make Marin approachable for new users (human and agent) by fixing documentation rot, writing an Iris getting started guide, removing stale Ray references from docs, and making Iris docs agent-friendly.

Sub-issues

• Remove old doc rot #4463 Remove old doc rot — audit and fix ~20 stale doc files
• Iris getting started guide #4464 Iris getting started guide — user-facing zero-to-running tutorial
• Remove Ray from Marin docs entirely #4465 Remove Ray from Marin docs entirely — replace all Ray references with Iris equivalents
• Make Iris docs agent-friendly #4466 Make Iris docs agent-friendly — structured CLI/SDK/config reference
• Iris CLI: simplify --cluster default experience #4467 --cluster=marin default experience — simplify the common-case CLI workflow
• Iris controller restart protocol #4530

Related

• Iris docs: replace Ray as blessed path, update for accuracy, make agent-friendly #4443 — Iris docs: replace Ray as blessed path, update for accuracy, make agent-friendly

Definition of done

• A human can go from zero to "job running on Iris" following the docs
• An agent given "submit a TPU training job" can find all needed info without leaving the docs
• No stale Ray-centric tutorials remain in docs/
• Iris CLI, SDK, and config documented in structured, parseable form

[claude]

🤖 Plan:

• Fetch epic + sub-issues
• Scope check: epic, not a single bug fix
• Post analysis comment (no PR)

Research

Epic tracks 5 sub-items, all already filed as separate issues. No implementation belongs on this meta-issue; work should land on the children.

Sub-issue status

• Remove old doc rot #4463 — Remove old doc rot
• Iris getting started guide #4464 — Iris getting started guide
• Remove Ray from Marin docs entirely #4465 — Remove Ray from Marin docs entirely
• Iris docs: replace Ray as blessed path, update for accuracy, make agent-friendly #4443 — Iris docs: replace Ray as blessed path, make agent-friendly
• (no open issue yet) — `--cluster=marin` default experience

Current state (docs/)

• ~20 files reference Ray; worst offenders: `tutorials/tpu-cluster-setup.md`, `tutorials/executor-101.md`, `tutorials/first-experiment.md`, `tutorials/train-an-lm.md`, `dev-guide/rebuilding-cluster.md`.
• No Iris tutorial under `docs/tutorials/`; only `docs/iris-budget-{design,research}.md` exist at top level and aren't in nav.
• `lib/iris/docs/` has 22 design docs but no newcomer entry point; OPS.md is two paragraphs (per Iris docs: replace Ray as blessed path, update for accuracy, make agent-friendly #4443).

Proposed approach (for humans)

Do not open a single mega-PR from this epic. Drive work through the sub-issues in this order so later steps can cite earlier ones:

1. Iris getting started guide #4464 Iris getting started first — produces `docs/tutorials/iris-getting-started.md` (install → auth → `iris submit` → monitor → logs). Becomes the target link for Ray removals.
2. Iris docs: replace Ray as blessed path, update for accuracy, make agent-friendly #4443 Iris docs agent-friendly in parallel — restructure `lib/iris/README.md` + `OPS.md` into CLI reference, SDK reference, config schema, common tasks. Audit against current code. Add Iris section to `mkdocs.yml` nav.
3. Remove Ray from Marin docs entirely #4465 Remove Ray from docs — rewrite the ~20 Ray-referencing tutorials to point at Iris equivalents (or delete if superseded). Depends on (1) existing.
4. Remove old doc rot #4463 Doc rot audit — sweep remaining stale pages; wire orphaned files into `mkdocs.yml` (per Iris docs: replace Ray as blessed path, update for accuracy, make agent-friendly #4443 stretch, 26 files aren't in nav).
5. `--cluster=marin` default — file a dedicated issue; requires CLI change in `lib/iris`, not a docs-only fix.

Each sub-issue is independently PR-sized (~100–400 LOC of docs). This meta-epic should stay open as a tracker and not receive a PR itself.

Scope note: epic, not a bug. No fix-issue PR from this agent run.

[rjpower]

🤖 Closing as duplicate of #4273 (Improve Usability & Observability). Sub-issues #4463–#4467 moved under #4273.