orca/.ciagent/PLAN_v0.10.md

# Plan: v0.10 Docs & Install Milestone

## Milestone: v0.10 — Docs & Install Hardening
- **Type**: feature (P1 `fix`, P2-P4 `docs`; at least one non-docs phase)
- **Tags**: `v0.9.0` (P0) → `v0.9.1` (P1) → `v0.9.2` (P2) → `v0.9.3` (P3) → `v0.9.4` (P4) → `v0.9.5` (P5 = milestone release)
- **Branch**: `milestone/v0.10-docs-cli-examples`

## Phase breakdown

### Phase P1 — release.sh + install.sh fix (Wave 1)
**REQs**: REQ-097, REQ-098
**Persona**: backend-engineer
**Territory**: `scripts/release.sh`, `scripts/install.sh`, `scripts/tests/*.bash`
**Vertical slice**: a broken release → a correctly-asseted release that install.sh resolves.

| Task | Description | REQ |
|------|-------------|-----|
| P1-T1 | `scripts/release.sh`: replace host-arch build (lines 84, 89-98) with explicit `GOOS=linux GOARCH=amd64 go build` cross-build; produce `orca-${VERSION}-linux-amd64.tar.gz` regardless of host arch | REQ-097 |
| P1-T2 | `scripts/release.sh`: after `tea releases create` (line 132), add post-create asset verification — query `/api/v1/repos/$OWNER/$REPO/releases/tags/$VERSION`, assert the tarball appears in `attachments`, retry once if missing, fail loudly with clear error if still missing | REQ-097 |
| P1-T3 | `scripts/install.sh`: add asset fallback walk — if the resolved release (latest or `--version`) lacks the matching `orca-<ver>-<os>-<arch>.tar.gz`, query `/releases?limit=20`, walk backward, use the most recent release that carries the asset, print a warning | REQ-098 |
| P1-T4 | `scripts/install.sh`: add `--check` dry-run mode that prints version + asset URL + install path without writing | REQ-098 |
| P1-T5 | `scripts/tests/release.bats` + `scripts/tests/install.bats`: add/extend bats tests for the new behavior (happy path: asset present; fallback: latest release asset-less, older release has asset; --check prints without writing) | REQ-097, REQ-098 |

**Must-haves**: release.sh produces an amd64 tarball on any host arch; install.sh resolves to a release with an asset (walking back if needed); `--check` works; bats tests pass.

### Phase P2 — CLI + jobspec + ingress docs (Wave 2)
**REQs**: REQ-091, REQ-092, REQ-093
**Persona**: docs-engineer (phase-specific), lead-developer
**Territory**: `docs/cli.md`, `docs/jobspec.md`, `docs/ingress.md`
**Vertical slice**: an operator with no orca background → can author a jobspec, run it, and understand the ingress model from docs alone.

| Task | Description | REQ |
|------|-------------|-----|
| P2-T1 | `docs/cli.md`: full CLI reference — global flags, every command/subcommand with synopsis + flag tables + one-line example, output modes (text/json/watch), exit codes, deprecated surface callout boxes (daemon/cert/node-join-mTLS/HCL-jobspec) | REQ-091 |
| P2-T2 | `docs/jobspec.md`: markdown frontmatter schema reference — top-level keys, block reference (runtime/ports/env-secrets/volumes/restart/update/service/health/lifecycle/constraints/affinity/tasks), kinds matrix, CEL subset grammar, body semantics, deprecated HCL callout | REQ-092 |
| P2-T3 | `docs/ingress.md`: Traefik ingress reference — service→Traefik mapping, R-007 socket-vs-TCP-bind, generated YAML shape, atomic reload (C-10), drain, TLS, worked-example pointer to `examples/full-stack/`, v0.10 forward limitations | REQ-093 |

**Must-haves**: every command/flag in `internal/cli/` is documented; every jobspec field in `internal/jobspec/markdown.go` is documented; every factual claim is grounded in the live codebase; cross-links resolve; deprecated surface is clearly marked.

### Phase P3 — full-stack examples (Wave 2, parallel with P2)
**REQs**: REQ-094
**Persona**: docs-engineer (phase-specific), lead-developer
**Territory**: `examples/full-stack/**`
**Vertical slice**: an operator → can deploy a multi-service stack with ingress by copying the examples.

| Task | Description | REQ |
|------|-------------|-----|
| P3-T1 | `examples/full-stack/web-app.md`: kind Service, process runtime, port http, service block (socket default), health, restart (service), update (rolling), constraints (CEL), task group (app + sidecar) | REQ-094 |
| P3-T2 | `examples/full-stack/api.md`: kind Service, process runtime, port api, service bind 127.0.0.1 (TCP opt-in), health, restart, update (canary) | REQ-094 |
| P3-T3 | `examples/full-stack/worker.md`: kind Job, process runtime, one-shot, timeout, env, lifecycle hooks | REQ-094 |
| P3-T4 | `examples/full-stack/log-shipper.md`: kind DaemonSet, schedule (every-node), restart, constraints | REQ-094 |
| P3-T5 | `examples/full-stack/postgres.md`: kind Service, process runtime, port pg, volumes + replication (syncthing), health, restart, update (blue-green) | REQ-094 |
| P3-T6 | `examples/full-stack/rendered/`: the Traefik dynamic YAML + systemd units orca generates for the stack (traefik-dynamic-web-app.yaml, traefik-dynamic-api.yaml, systemd-web-app.service, systemd-api.service, systemd-log-shipper.service) | REQ-094 |
| P3-T7 | `examples/full-stack/README.md`: walkthrough (init → node join → capacity set → ns create → job run → list --watch → inspect rendered → drain/rollback notes → cross-link to docs/ingress.md) | REQ-094 |

**Must-haves**: all 5 jobspecs parse with the current `internal/jobspec` parser and pass `internal/spec/schema` validators; rendered artifacts match what the emitters would produce; README walkthrough is end-to-end coherent.

### Phase P4 — README + namespace.md refresh (Wave 3, after P2/P3)
**REQs**: REQ-095, REQ-096
**Persona**: lead-developer
**Territory**: `README.md`, `docs/namespace.md`
**Vertical slice**: a new visitor to the repo → sees accurate status, all commands, install instructions that work, and a link to the docs + examples.

| Task | Description | REQ |
|------|-------------|-----|
| P4-T1 | `README.md`: status line (v0.9 complete, v0.10 in progress); install `--version` example updated to current tag; subcommand table expanded to all commands with deprecation markers; update-in-place example updated; development targets complete; new Documentation + Examples sections | REQ-095 |
| P4-T2 | `docs/namespace.md`: replace v0.8 flat path table with v0.9 multi-namespace layout (`cluster/`, `_defaults/`, per-ns `db/jobs/alloc/ns.md`); `ORCA_HOME`/`--system` resolution; `orca ns` subcommand cross-link; v0.8 flat layout flagged deprecated | REQ-096 |

**Must-haves**: README subcommand table matches `internal/cli/` exactly; install example pins a current tag; namespace.md path table matches `internal/paths/paths.go`; both files cross-link to the new docs.

### Phase P5 — final review + ship + audit (Wave 4)
**REQs**: all (REQ-091..REQ-098)
**Persona**: lead-developer
**Vertical slice**: milestone complete → merged to main, tagged, released.

| Task | Description | REQ |
|------|-------------|-----|
| P5-T1 | Code review across all phases (P1-P4); auto-apply P0 fixes, flag P1+ for post-hoc | all |
| P5-T2 | Audit: reconstruction test (git log matches `.ciagent/`), file discipline, branch hygiene, commit discipline | all |
| P5-T3 | Milestone ship: merge phase/05 → milestone → main; tag `v0.9.5` (= v0.10.0 milestone release); create release with full milestone summary + Linux binary asset (verified by the P1 fix); delete all milestone branches | all |
| P5-T4 | Complete milestone: mark REQ-091..098 complete in REQUIREMENTS.md; mark v0.10 docs milestone complete in ROADMAP.md; clear checkpoint | all |

**Must-haves**: milestone merged to main; release carries the Linux binary (the fix from P1 proving itself); all REQs marked complete; checkpoint cleared.

## Wave ordering

- **Wave 1**: P1 (release/install fix) — unblocks the ship of every subsequent phase (each phase ship needs a correctly-asseted release)
- **Wave 2**: P2 (docs) + P3 (examples) — parallel, no dependencies between them
- **Wave 3**: P4 (README + namespace.md) — depends on P2/P3 existing (cross-links)
- **Wave 4**: P5 (final review + ship) — depends on all prior phases

## Risks

- **R1**: The jobspecs in P3 might not parse if a field shape has drifted since the explore report. Mitigation: validate each jobspec against the current parser before committing (write a throwaway test or run `orca job run` with `--dry-run` if available).
- **R2**: `tea releases create` asset verification in P1 might reveal a tea CLI bug that can't be worked around in bash. Mitigation: fall back to a direct `curl` upload to the Gitea attachments API if `tea` is unreliable.
- **R3**: The v0.8.15 release still has no asset after P1 ships (P1 only fixes forward). Mitigation: install.sh's fallback walk (P1-T3) handles the gap; users installing between P1 ship and the first correctly-asseted release (P1's own ship tag v0.9.1) will get a clear warning + fallback.