orca/.ciagent/RESEARCH_v0.10.md

# Research: v0.10 Docs & Install Milestone

## Documentation landscape in the orca tree

### What exists today

The `docs/` directory contains four files:

- `docs/install.md` — install guide (user-level, system-level, version
  pinning, in-place update, troubleshooting). Accurate for v0.5-v0.8
  but does not mention the v0.9 multi-namespace layout, `--config`, or
  `--no-deprecation-warnings`.
- `docs/docker.md` — Docker image guide. Still documents `orca daemon`
  (deprecated in v0.9).
- `docs/namespace.md` — namespace and paths. Documents the **v0.8 flat
  layout** (`~/.orca/orca.db`, `ca.crt`, `ca.key`, `server.crt`,
  `server.key`). Does NOT document the v0.9 multi-namespace layout
  (`cluster/`, `_defaults/`, per-ns `db/jobs/alloc/ns.md`), `orca ns`
  subcommands, or the `_defaults` implicit root (D-159/D-185/D-187).
- `docs/security-scanning.md` — gosec + govulncheck + gitleaks guide.
  Accurate; no v0.9 drift.

### What's missing (the gap this milestone closes)

1. **No CLI reference doc.** The entire CLI command surface (init, job,
   node, ns, cert, daemon, doctor, status, audit, version) is
   undocumented in `docs/`. The README subcommand table is stale (lists
   only version/init/status/node/job with fake "Phase N" statuses,
   missing cert/daemon/doctor/audit/ns/node-capacity/node-key-reset).
2. **No jobspec reference doc.** The markdown frontmatter schema (kinds,
   blocks, CEL subset, validation rules, body semantics) is
   undocumented. Operators must read `internal/jobspec/markdown.go` and
   `internal/spec/schema/schema.go` source.
3. **No ingress/Traefik doc.** The service→Traefik mapping, R-007
   socket-vs-TCP-bind, atomic reload, drain, TLS — all undocumented.
4. **No examples directory.** `testdata/` holds legacy HCL fixtures
   (`hello.hcl`, `fail.hcl`) for Go tests, not operator-facing
   examples. No worked full-stack demo exists.
5. **README is stale.** Status line says "v0.1: Foundation".
   Subcommand table missing 5 commands. Install `--version` example
   pins v0.4.2. Update-in-place example references v0.4.1→v0.4.2.
   Development section omits 4 make targets.

### Prior art for CLI reference docs

- **Nomad**: `nomad job` / `nomad node` / `nomad agent` reference pages,
  one per subcommand, with flag tables and JSON examples. Orca's
  single-file `docs/cli.md` is simpler (one file vs a subdirectory) but
  follows the same flag-table + example convention.
- **kubectl**: `kubectl reference` + per-command pages. Too heavy for
  orca; the single-file model fits the minimalist ethos.
- **Docker CLI**: `docker run` reference with flag tables. Matches the
  shape orca's `docs/cli.md` will take.

### Prior art for example jobspecs

- **Nomad example jobs**: `nomad-job-spec.example` files in the Nomad
  repo showing service + job + sysbatch patterns. Orca's
  `examples/full-stack/` mirrors this with 5 markdown jobspecs covering
  Service/Job/DaemonSet + task groups + volumes + replication.
- **Kubernetes examples**: `examples/` directory with yaml
  deployments/services/ingress. Orca's equivalent is the 5 jobspecs +
  rendered Traefik/systemd artifacts.

## Release/install pipeline research

### Root cause of the v0.4.5 install

Verified via the Gitea API:

```
GET /api/v1/repos/coreci/orca/releases/latest
→ tag_name: "v0.8.15"

GET /api/v1/repos/coreci/orca/releases/tags/v0.8.15
→ attachments: []   (zero binary assets)
```

The v0.8.x releases (v0.8.0 through v0.8.15) all shipped with **zero
binary assets attached**. Only `v0.4.5` carries a tarball
(`orca-v0.4.5-linux-amd64.tar.gz`).

`scripts/install.sh:70-78` resolves "latest" → v0.8.15, then
`install.sh:96-104` looks for `orca-v0.8.15-linux-amd64.tar.gz` in
v0.8.15's assets. Since the asset is missing, install.sh errors out
(`could not find asset ... in release v0.8.15`). The v0.4.5 install
came from an earlier run or a pinned `--version`.

### Why v0.8.x releases have no assets

`scripts/release.sh:132-136` calls `tea releases create "$VERSION" ...
--asset "$TARBALL"`. The script builds the tarball (line 98) and passes
it to `tea`. Two likely failure modes:

1. **Host arch mismatch**: `release.sh:89-95` builds for the host arch
   (`uname -m`). If the CI runner or dev machine is arm64, it produces
   `orca-v0.8.15-linux-arm64.tar.gz`, but `install.sh` looks for
   `linux-amd64`. The `.coreci.yml:121` release step hardcodes
   `--asset orca-${VERSION}-linux-amd64.tar.gz`, so the CI runner must
   be amd64 — but `release.sh` run locally on an arm64 dev machine
   produces the wrong arch.
2. **Silent asset drop**: `tea releases create` has been observed to
   succeed (exit 0) without attaching the asset in some tea versions.
   The script treats `tea`'s exit code as success without verifying the
   asset actually appears in the release.

### Fix approach (REQ-097, REQ-098)

**release.sh**:
- Cross-build `linux-amd64` explicitly via
  `GOOS=linux GOARCH=amd64 go build`, regardless of host arch.
- After `tea releases create`, query
  `/api/v1/repos/$OWNER/$REPO/releases/tags/$VERSION` and assert the
  tarball appears in `attachments`. If not, retry once, then fail
  loudly with a clear error.

**install.sh**:
- Add an asset fallback walk: if the resolved release (latest or
  pinned) lacks the matching tarball, query
  `/releases?limit=20`, walk backward, and use the most recent release
  that carries the `orca-<ver>-<os>-<arch>.tar.gz` asset. Print a
  clear warning.
- Add `--check` dry-run mode (D-194) that prints the version + asset URL
  + install path without writing.

## Persona assessment (PERSONAS.md)

This milestone touches two territories:

1. **`scripts/` (release.sh, install.sh)** — bash scripts, not Go.
   Backend-engineer territory (API-adjacent tooling). The fix is
   cross-build + API verification + fallback walk.
2. **`docs/` + `examples/` + `README.md`** — markdown documentation.
   Lead-developer territory (coordination + cross-cutting docs).

No data-engineer work (no schema/migration changes). No
frontend-engineer work (no UI). The data-engineer persona is
deactivated for this milestone. A docs-engineer custom persona is
created for P2/P3/P4 (markdown authoring with codebase-grounded
factual claims).