docs: publish beta status and beginner-first README

[askclaw-vesper]

Summary

• transition the release checklist and readiness contract from the private/pre-flip phase to the verified public-beta source state;
• replace the 656-line technical landing page with a 260-line beginner-first README;
• preserve and embed the supplied Session paused screenshot unchanged, with its visible wording repeated as indexable text;
• add an end-to-end beginner Quickstart, a complete technical Reference, and a privacy-safe Validation record;
• answer Why try it?, Why trust it?, intended audience, non-audience, and current limitations with verified evidence rather than marketing;
• teach exactly one watch --follow followed by one audit;
• leave the v0.3.0-beta.1 tag as the sole remaining release action after merge and protected-main CI.

Safety and scope

• no runtime Python, CLI, manifest schema, workflow, package version, or release-tag gate changes;
• no safeguard bypass, automatic retry, model switching, or pause-continuation claims;
• the original pre-export history warning remains permanent;
• the screenshot bytes are unchanged: SHA-256 7df5717543f0b5b6853b0e302708d2f68c1b251a7f72719e4e2a927b2e86a54f;
• the Validation record contains no hostnames, usernames, absolute paths, session IDs, credentials, full prompts, or transcript text.

Verification

• python3.12 -m compileall -q src tests
• python3.12 -m unittest discover -s tests — 548 passed
• tracked-tree public-readiness scan — passed
• full-history scan — passed: 8 commits, 92 unique blobs
• offline wheel install and installed-CLI dry-run — passed
• empty-tree whitespace gate — passed
• image hash — passed
• exact final commit tested on the native Python 3.12 host
• working tree clean

Release state

The source repository is public, private vulnerability reporting is enabled, and protected main requires the test CI check and pull requests. This PR does not create or claim a prerelease. After merge and protected-main CI pass, the only remaining action is the v0.3.0-beta.1 tag workflow.

[adaptcom]

Confidence Score: 5/5

Summary

Docs-and-tests-only PR that flips the release checklist from pre-flip BLOCKED to the verified public-beta state and replaces the 656-line README with a 260-line beginner-first landing page plus docs/QUICKSTART.md, docs/REFERENCE.md, and docs/VALIDATION.md. Every claim checked out against live state: the repo is actually public, private vulnerability reporting is enabled, main is protected with the required test check (enforced for everyone), no v0.3.0-beta.1 tag or release exists yet, and the CI test check is green on the PR head. Locally on the head commit: all 548 unit tests pass (5 initial errors were only missing PyYAML in my sandbox; CI pins PyYAML==6.0.2), the tracked-tree readiness scan, full-history scan (exactly 8 commits, 92 unique blobs as claimed), compileall, and the empty-tree whitespace gate all pass. The screenshot bytes match the claimed SHA-256, the README transcription matches the image word for word, and the image contains no hostnames, usernames, paths, or prompt text. No src/, workflow, or pyproject changes. Only minor, non-blocking nits below.

Important Files Changed

File	Overview
PUBLIC_RELEASE_CHECKLIST.md	Status flipped from BLOCKED to 'the source is PUBLIC'; visibility, vulnerability-reporting, and branch-protection gates recorded as resolved (all three independently verified true via the GitHub API); the permanent old-history warning is preserved; exactly one unchecked item remains, the v0.3.0-beta.1 tag. No concerns.
README.md	Full rewrite into a 260-line beginner-first landing page: plain-words explanation, the Session paused screenshot with a verbatim indexable transcription (verified against the image), evidence-backed why-try/why-trust/audience/limits sections, pre-PyPI install warning with tag-pinned commands only, and links into docs/. Claims (548 tests as '500+', protected-main CI, public repo, reporting enabled, no prerelease yet) all verified truthful.
docs/QUICKSTART.md	New end-to-end beginner walkthrough: checkout install, registry, profile, task file, dry run, explicit launch, exactly one watch --follow, one audit. Uses safe placeholders, no credentials, no bypass flags, no budget key; the --version output claim matches pyproject's 0.3.0b1.
docs/REFERENCE.md	New 575-line operator reference carrying the deep material moved out of the README: payload privacy contract, budget pass-through, audit verdicts, watch events, migration table, development, release notes. Content matches the prior README's technical contracts; tests enforce that the key contracts (switchModelsOnFlag, payload_files_created, verdicts, event vocabulary) are preserved here.
docs/VALIDATION.md	New privacy-safe evidence record for the one real smoke (Linux, Claude Code 2.1.208, exact marker, exact cost, budget flag disclosed as a fixture) plus deterministic gates and an explicit limitations section. Contains no hostnames, usernames, absolute paths, session ids, or transcript text, as claimed.
docs/assets/fable-5-session-paused.jpg	New 26,049-byte JPEG. SHA-256 matches the PR's claimed 7df57175...2e86a54f exactly, and a test pins the hash so the bytes cannot silently change. Image content matches the README transcription word for word and contains no private information.
tests/public_readiness_check.py	Gate updated from pre-flip to post-flip truth: now fails on stale private/BLOCKED wording, requires the public status and resolved gates in the checklist with exactly one unchecked item, and adds beginner-README, evidence-README, one-follow-lifecycle, and validation-record contract checks. Passes on this tree; the inverted assertions are consistent with the verified live repo state.
tests/test_mit_release.py	Mirror of the readiness-gate flip in unittest form: checklist status is public, private-claim needles banned, prerelease-existence claims banned until the tag workflow runs, reporting recorded as enabled-after-flip. All pass.
tests/test_public_readiness.py	Adds ~340 lines of new doc-contract tests: screenshot hash pin and tracking, README landing-page band (100-300 lines), transcription and no-bypass wording, evidence sections, one --follow lifecycle, Quickstart order and safety, relative-link resolution, and Reference contract preservation. All 548 tests pass. One tiny robustness nit noted inline.

Findings

• The exact smoke cost string $0.15400099999999997 is now pinned verbatim in five places (README.md:106, docs/VALIDATION.md:52, tests/test_public_readiness.py:466, tests/public_readiness_check.py:547 and :613). This is clearly deliberate truth-pinning, but any future rewording or rounding of the evidence will fail two CI gates at once; consider centralizing the smoke constants (marker, cost, budget flag) in one shared module the checker and tests both import. Non-blocking.

View in Adapt