docs: truth pass — README/nav-map/checklist match the v0.8 surface + release policy

[LukasWodka]

What

WS-F.1/F.2 of the customer-surface truth pass (epic tracebloc/backend#1106): make README, the navigation map, and the release checklist tell the truth about the v0.8-era surface, and write down a release policy so develop stops drifting 46 commits past the last tag.

Stacked on #300 (WS-F.5 Homebrew drop) — both edit README.md + RELEASE_CHECKLIST.md. Merge #300 first; this diff is chore/299-drop-homebrew-tap..docs/296-readme-truth-pass.

Changes

README.md — every claim verified against the actual command tree (go run ./cmd/tracebloc --help + every subcommand, on develop @ 5af9a80):

• "v0.3.0 is released" → v0.8.0 (latest GitHub release, 2026-07-10) + a lifecycle table documenting the real surface: login/logout/auth status, client/client status, resources/resources set, data ingest/list/delete/validate, cluster info, doctor, delete (offboard), version/completion/home screen. Honest note on what landed after the v0.8.0 cut (resources, status-aware home screen, top-level doctor, semseg).
• "15 of 16 task categories" → all 16 — verified per feat(data ingest): wire semantic_segmentation (RFC-0002 phase 4, #182) #247 and against internal/push/category.go (16× CLISupported: true, zero false).
• Roadmap tail: "9 of 10 modalities" + v0.2/v0.3-era story → the v0.2–v0.8 arc; semantic_segmentation removed from Next (it shipped); cloud-source ingestion kept (still backed by RFC-0002 + the in-help 1 GiB-cap copy).
• Links docs/cli-navigation.md. The existing --intent train install example was checked and is still valid (the flag survives on develop) — left alone.

docs/cli-navigation.md:

• Stale-basis disclaimer (develop @ 27c5392) removed.
• resources set (feat(resources): tracebloc resources set — guided compute budget (P2, wizard + GPU) (#143) #241) and the status-aware home screen (feat(cli): status-aware tracebloc home screen #244) un-dashed — both merged; the now-unused proposed classDef dropped.
• Both references to the nonexistent home-screen-spec.md removed (they point at shipped feat(cli): status-aware tracebloc home screen #244 now).
• doctor node updated: top-level doctor shipped, cluster doctor is the hidden alias (pinned by TestClusterCmd_DoctorIsHiddenAlias).
• Known-gaps pruned to what is still true — re-verified in delete.go that a degraded offboard still returns exit 0 (gap kept).

scripts/RELEASE_CHECKLIST.md:

• New Release policy section (WS-F.2, per report §5): trigger = customer-visible feature merge or weekly, whichever first; owner = DevEx squad (role, not a person — proposal, flag if you'd rather assign differently).
• EKS smoke tracebloc dataset push → tracebloc data ingest; the v0.1-ticket pre-flight item genericized.

.github/workflows/release.yml — header comment claimed release notes are "generated from CHANGELOG.md"; no CHANGELOG.md exists, the workflow uses generate_release_notes: true. Comment now says so.

Verification

• Ran locally: root --help + auth, client, data (+ ingest/list/delete/validate), cluster info, doctor, resources (+ set), delete, login, logout, version, and the alias probes (data push/rm, dataset, cluster doctor, hidden client create/list) — the docs now match that output.
• go build ./... green; release.yml still parses (comment-only change there).
• Docs-only diff otherwise — no behavior change.

Fixes#296

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation and workflow comments only; no runtime, auth, or release pipeline behavior changes.

Overview
Docs-only truth pass so customer-facing material matches develop and current releases (README now cites v0.9.1 and the full lifecycle command table, not v0.3.0-era copy).

README broadens the product blurb, replaces stale status/roadmap with the v0.2–v0.9 arc, links docs/cli-navigation.md, and states data ingest supports all 16 task categories (including semantic_segmentation via #247). Release/install wording is generalized beyond a single pinned version.

docs/cli-navigation.md drops the old “basis @ commit” and proposed/not-shipped styling: resources set, the status-aware home screen, and top-level doctor are drawn as shipped; known-gaps list is trimmed to what’s still open.

scripts/RELEASE_CHECKLIST.md adds a release policy (when to cut, DevEx owner) and updates pre-flight smoke to tracebloc data ingest.

.github/workflows/release.yml header comment only: release notes come from generate_release_notes: true, not CHANGELOG.md.

^{Reviewed by Cursor Bugbot for commit 49c6f40. Bugbot is set up for automated code reviews on this repo. Configure here.}

[LukasWodka]

👋 Heads-up — Code review queue is at 44 / 30

Above the WIP limit. The team convention is to review existing PRs before opening new work.

Open PRs currently in Code review (oldest first):

• averaging-service#181 — feat(weights): normalize-on-read — mixed cycles average instead of rejecting (SEC-03 §8 step 2) · author: @shujaatTracebloc · no reviewer assigned
• averaging-service#182 — feat(weights): averaging writes SafeTensors (TF + PyTorch) — SEC-03 §8 step 4 · author: @shujaatTracebloc · no reviewer assigned
• backend#1079 — feat(global_meta): edge dataset_meta exposure + attributes contract at ingest (#924 G4a) · author: @divyasinghds · no reviewer assigned
• backend#1086 — docs(rfc): SafeTensors weight-format migration — SEC-03 Phase 1 (RFC 0004) · author: @shujaatTracebloc · no reviewer assigned
• backend#1093 — chore(deps): bump django from 5.2.14 to 5.2.15 · author: @dependabot · no reviewer assigned
• backend#1095 — feat(experiment): configurable preprocessing knobs incl. tabular scaler — RFC 0003 L1 + L1b (#1094) · author: @LukasWodka · no reviewer assigned
• backend#1100 — fix(boot): pin SDK install to tracebloc==0.11.2, drop 404 dev line (#1098) · author: @LukasWodka · reviewer: @saqlainsyed007
• backend#1105 — perf(api): query micro-fixes — notifications N+1, cached data_scientist, composite index, sampling (#975) · author: @aptracebloc · no reviewer assigned
• cli#266 — main - > enhance CLI features and tests · author: @saadqbal · no reviewer assigned
• cli#278 — fix(deps): toolchain go1.26.5 + x/net v0.57.0 — clear 6 reachable vulns; govulncheck CI gate · author: @LukasWodka · reviewer: @saadqbal

Pull from review before opening new work. (This is a nudge from the kanban WIP check, not a block.)

[LukasWodka]

@BugBot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 40f6347. Configure here.}

[saadqbal]

One staleness to catch before merge (ironic for a truth pass 🙂): this predates the v0.9.0 + v0.9.1 cuts, so a few version claims are now behind —

• README "v0.8.0 is the latest release" → now v0.9.1.
• The "Landed on develop after the v0.8.0 cut (ships with the next release): resources / home screen / top-level doctor / semantic_segmentation" framing — those all shipped in v0.9.0 now, so they're no longer "next release".

Everything else matches the develop surface. Worth a quick version-reference refresh (here or a fast follow-up).

[saadqbal]

Approving — the command surface, 16-category list, doctor-promotion and resources/home-screen notes are all accurate, and the release.yml change is comment-only. Just refresh the v0.8.0 'latest release' references to v0.9.1 (see my comment) since we cut v0.9.0/v0.9.1 after this was authored. 👍

The base branch was changed.

[saadqbal]

Status: I reopened + retargeted this to develop. Heads-up — it got auto-closed when I squash-merged its base #300 with branch deletion (GitHub closes a PR when its base branch is gone); sorry for the noise. Now conflicts (docs only), so a quick rebase onto develop + re-review and it's good.

[LukasWodka]

@saadqbal thanks — rebased onto develop and refreshed the version references you flagged.

• Rebase: base is develop; since chore(release): drop the Homebrew tap job + install.tracebloc.io promise #300 (drop-homebrew-tap) squash-merged into develop, I dropped the now-redundant homebrew-drop commit from this branch and replayed only the truth-pass commit on top. Develop's README/checklist/release.yml were already byte-identical to the pre-truth-pass base, so it re-applied clean. No Homebrew tap or install.tracebloc.io promise reintroduced — the only remaining "Homebrew" strings are the deliberate "tap dropped (WS-F.5: drop Homebrew job/template + install.tracebloc.io promise (APPROVED) #299)" roadmap note and the brew install cosign dependency hint (both kept on purpose per chore(release): drop the Homebrew tap job + install.tracebloc.io promise #300).
• v0.8.0 → v0.9.1: Status blurb now reads "v0.9.1 is the latest release".
• "next release" framing fixed: the post-v0.8.0 list (resources / status-aware home screen / top-level doctor / semantic_segmentation) now reads "Shipped in v0.9.0" instead of "ships with the next release", and the roadmap tail gained a "v0.9 added …; v0.9.1 is the current latest" entry. Remaining v0.8.0 mentions are intentional historical contrasts (the v0.8.0 cut; v0.8.0 had doctor only as cluster doctor).

go build ./... + go vet ./... green (docs-only change). Ready for a re-review when you have a moment.

[saadqbal]

Re-approving — you addressed the version staleness (now 'v0.9.1 is the latest release' + the v0.9 roadmap row). Docs match the develop surface. 👍