# KORA v0.2.1-alpha Polish Onboarding Audit

Date: 2026-05-07

## Current Public Head

| Item | Value |
|---|---|
| Public truth | `origin/main` |
| Public HEAD audited | `a3348864fbfbe559a2479826025c53dba42f6e98` |
| Audit branch | `task131_v021_polish_onboarding_audit` |
| Audit worktree | Fresh local worktree under the workspace `worktrees/` directory |

## Release Baseline

| Item | Value |
|---|---|
| Published release | `v0.2.0-alpha` |
| Release URL | `https://github.com/Krako-Labs/KORA/releases/tag/v0.2.0-alpha` |
| Local tag check | `v0.2.0-alpha` exists |
| GitHub release check | `gh release view v0.2.0-alpha` passed |
| Release status | Published GitHub prerelease |

## Audit Scope

This audit reviewed the public onboarding surface after `v0.2.0-alpha`:

- `README.md`
- `CHANGELOG.md`
- `CONTRIBUTING.md`
- `SECURITY.md`
- `GOVERNANCE.md`
- `docs/`
- `docs/reports/`
- docs index and navigation docs
- `examples/`
- `experiments/`
- `scripts/`
- CLI examples:
  - `python3 -m kora --help`
  - `python3 -m kora examples list`

The audit was performed from the perspective of a first-time external developer trying to understand KORA, run a first example, find benchmark evidence, regenerate the deterministic-heavy benchmark, understand claim boundaries, and find contribution/security/governance guidance.

## Summary Assessment

A first-time external developer can understand the core KORA idea in under two minutes from the README and can run the first CLI examples quickly after local editable install. The docs index is useful and the v0.2.0-alpha claim boundary is documented in the claim registry, benchmark artifact policy, release notes, and GitHub Release.

The main gap is not missing evidence. The gap is navigation freshness: several prominent public docs still describe the project as v0.1-era or pre-release even though `v0.2.0-alpha` is published. Benchmark evidence exists but is split across README, changelog, `docs/benchmark.md`, `docs/technical_preview_results.md`, `docs/benchmarks/`, `docs/reports/`, `experiments/README.md`, and the GitHub Release.

## Findings By Severity

### Blocker

No blocker was found that prevents a local first-time developer from cloning the repository, installing locally, listing examples, or running the offline demo path.

### High

1. `CHANGELOG.md` says `v0.2.0-alpha` is "not yet released" even though the tag and GitHub Release are published.
   - Impact: the public release baseline appears inconsistent.
   - Recommended fix: update the changelog status to published and link the release URL.

2. `README.md` still frames the public surface as `v0.1` and does not surface `v0.2.0-alpha` benchmark evidence near the quickstart.
   - Impact: new readers may miss the current alpha release and bounded benchmark evidence.
   - Recommended fix: add a compact current-release block with the `v0.2.0-alpha` release URL, docs index, exact approved benchmark claim, and non-claims link.

3. Benchmark evidence is discoverable but fragmented across multiple docs with mixed freshness.
   - Impact: readers can find the benchmark path, but they must reconcile several files manually.
   - Recommended fix: create or polish a canonical benchmark evidence entrypoint that links `docs/reports/benchmark_artifact_policy.md`, `docs/benchmarks/kora_benchmark_result_v1_100.md`, `docs/claims/kora-claim-registry.md`, release notes, and regeneration commands.

4. `docs/technical_preview_results.md` still lists `v0.1.1-alpha` as the current released tag and an older public HEAD.
   - Impact: this can undermine trust in the current public evidence story.
   - Recommended fix: update it for the published `v0.2.0-alpha` baseline or mark the current file as historical and link to the newer release evidence.

### Medium

1. `experiments/README.md` still describes the benchmark surface as a skeleton and includes old `deterministic_heavy_v0` examples before the current `v1_100` path.
   - Impact: developers trying to regenerate the current deterministic-heavy benchmark may start from old commands.
   - Recommended fix: lead with the `v1_100` workload, `/tmp` raw artifact policy, summary generation, and exact claim boundary.

2. `docs/benchmark.md` contains older direct-vs-KORA language with token and model references that are not clearly tied to the current v0.2.0-alpha simulated deterministic-heavy evidence path.
   - Impact: readers may confuse the older small demo benchmark with the current release evidence.
   - Recommended fix: mark it as an early benchmark note or redirect readers to the current benchmark evidence entrypoint.

3. Contribution/security/governance docs exist, but first-time navigation is uneven.
   - Impact: README links to `CONTRIBUTING.md`, but `SECURITY.md`, `GOVERNANCE.md`, `CODE_OF_CONDUCT.md`, and community docs are not presented together in the first-run path.
   - Recommended fix: add a compact "Contributing and project rules" block in README and docs index.

4. Some scripts include old machine-local absolute paths.
   - Impact: these are not on the primary README path, but they are public repo surface and can confuse contributors or expose maintainer-local assumptions.
   - Recommended fix: scan scripts for local path defaults and replace with repository-relative or environment-driven paths in a dedicated cleanup task.

5. Internal continuity docs are linked from the public docs index.
   - Impact: this may be intentional, but external readers may not know which docs are public guidance versus maintainer handoff context.
   - Recommended fix: add status labels such as "public", "maintainer-facing", or "historical" before broad cleanup.

### Low

1. The README quickstart is runnable but dense.
   - Impact: first-run users may not know which command is the one recommended smoke demo.
   - Recommended fix: present one minimal path first, then the expanded example path.

2. `python3 -m kora --help` is functional but terse.
   - Impact: acceptable for alpha, but it does not point users toward `examples list` as the next command.
   - Recommended fix: later polish CLI help wording without expanding the public command surface.

3. `python3 -m kora examples list` is useful and clear, but README can better mirror that output.
   - Impact: low; the CLI itself is understandable.
   - Recommended fix: keep README example names aligned with the CLI output.

4. There are duplicated governance files at `GOVERNANCE.md` and `docs/GOVERNANCE.md`.
   - Impact: duplication is currently harmless if identical, but it creates drift risk.
   - Recommended fix: decide whether root file is canonical and docs file links back, or keep both with an explicit sync note.

## First-Time Developer Questions

| Question | Assessment |
|---|---|
| Can they understand what KORA is in under 2 minutes? | Yes. README and docs index explain execution control, task graphs, deterministic-first execution, validation, and model escalation. |
| Can they run the first example quickly? | Yes after local editable install. README gives `python3 -m kora examples list` and offline `direct_vs_kora` commands. |
| Can they find benchmark evidence and claim boundaries? | Partially. Evidence exists, but the path is split across several docs and some files are stale. |
| Can they regenerate the deterministic-heavy benchmark? | Yes if they find `docs/reports/benchmark_artifact_policy.md`; less clear if they start from `experiments/README.md`. |
| Can they distinguish public evidence from non-claims? | Yes in claim registry, artifact policy, release notes, and GitHub Release. Some older docs need clearer status labels. |
| Can they find contribution/security/governance docs? | Yes by root files and docs index, but README should make this more direct. |
| Are there confusing stale docs, duplicated docs, or outdated paths? | Yes: changelog release status, README v0.1 framing, technical preview release context, experiments README, older benchmark doc, duplicated governance, local path references in scripts/context docs. |
| Are there references to old local paths that should not be public? | Yes, especially script defaults and maintainer context docs referencing machine-local absolute paths. |
| Are there missing links between README, docs index, benchmark policy, release notes, and examples? | Yes. The pieces exist but should be cross-linked from a small number of canonical entrypoints. |

## Recommended v0.2.1-alpha Task Sequence

1. Task 132: README quickstart and current-release polish.
   - Add a current `v0.2.0-alpha` release block.
   - Keep the first-run command path short.
   - Link docs index, release URL, benchmark evidence, claim registry, contributing, security, governance, and code of conduct.

2. Task 133: docs index/navigation polish.
   - Add clear public, maintainer-facing, historical, and evidence labels.
   - Add direct links to the canonical benchmark evidence path.
   - Keep historical reports preserved.

3. Task 134: benchmark regeneration guide cleanup.
   - Make `experiments/README.md` lead with `deterministic_heavy_v1_100`.
   - Link to `docs/reports/benchmark_artifact_policy.md`.
   - Keep raw JSON outputs under `/tmp` unless explicitly selected as frozen evidence.

4. Task 135: release evidence cross-linking.
   - Link the GitHub Release, changelog, release report, benchmark policy, benchmark summary, claim registry, and technical preview results.
   - Update stale `v0.2.0-alpha` "not yet released" wording.

5. Task 136: first-time contributor path review.
   - Align `CONTRIBUTING.md`, good first issues, community docs, security, governance, and code of conduct.
   - Keep contribution expectations conservative and alpha-appropriate.

6. Task 137: stale branch/local path reference scan.
   - Replace public script defaults that point to machine-local absolute paths.
   - Add status notes to internal context docs where the old local path is historical or maintainer-only.

## Quick Wins

- Update `CHANGELOG.md` status for `v0.2.0-alpha` from "not yet released" to published prerelease.
- Add the GitHub Release URL to the README current-release section.
- Add one canonical "Benchmark evidence" link block in README.
- Add a "Regenerate benchmark" link from README to `docs/reports/benchmark_artifact_policy.md`.
- Add README links to `SECURITY.md`, `GOVERNANCE.md`, and `CODE_OF_CONDUCT.md`.
- Add an explicit stale/historical note to `docs/benchmark.md` or route readers to current evidence.
- Make `experiments/README.md` use `/tmp` output paths for routine benchmark artifacts.

## Do-Not-Touch Items

- Do not delete historical reports, EOD docs, readiness docs, benchmark summaries, release notes, or migration docs during v0.2.1-alpha polish.
- Do not move or rename docs before adding links and status labels.
- Do not freeze or commit raw benchmark JSON artifacts unless a later release process explicitly selects them.
- Do not change package version as part of onboarding polish.
- Do not create Git tags or GitHub Releases for this audit.
- Do not expand the public CLI surface during README/docs cleanup unless separately approved.
- Do not remove claim-boundary language while shortening docs.

## Claim Hygiene Notes

Keep current public wording bounded to the approved evidence path:

> In a reproducible 100-task deterministic-heavy benchmark workload, KORA-controlled execution avoided 80 of 100 simulated model invocations versus a naive direct baseline.

Every benchmark or release-evidence page should continue to state that the current evidence does not prove:

- production cost reduction
- real API-cost reduction
- production benchmark proof
- full runtime-integrated benchmark evidence
- broad workload superiority
- energy reduction evidence

Avoid turning the simulated invocation evidence into production, billing, latency, energy, adoption, partner, or paper-grade claims.

## Proposed Next Task 132

Task 132 should be a small README-only or README-plus-links polish task:

- work from a fresh branch off `origin/main`
- update the README to reflect `v0.2.0-alpha` as the current published prerelease
- keep the first-run path concise:
  - `python3 -m kora examples list`
  - `python3 -m kora run hello_kora`
  - `python3 -m kora run direct_vs_kora -- --offline`
- add a benchmark evidence block linking:
  - GitHub Release `v0.2.0-alpha`
  - `docs/README.md`
  - `docs/reports/benchmark_artifact_policy.md`
  - `docs/benchmarks/kora_benchmark_result_v1_100.md`
  - `docs/claims/kora-claim-registry.md`
- add direct contributor/project-rule links:
  - `CONTRIBUTING.md`
  - `SECURITY.md`
  - `GOVERNANCE.md`
  - `CODE_OF_CONDUCT.md`
- run:
  - `python3 -m pytest`
  - `python3 -m kora --help`
  - `python3 -m kora examples list`
  - `python3 -m kora run direct_vs_kora -- --offline`

## Validation Commands For This Audit

The audit branch should be validated with:

```bash
python3 -m pytest
python3 -m kora --help
python3 -m kora examples list
python3 -m kora run direct_vs_kora -- --offline
```
