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).