[INSTALL-01] [P1] Make prebuilt installation the default README and handbook path #551

Goal

A developer should reach a working published binary and run the starter project without first cloning Semaprax or compiling it.

Priority: P1 · Classification: Verified documentation defects and onboarding improvement

Reviewed baseline: main 56ad6438653f, 6 October 2026. Published distribution inspected: v0.8.0 (CLI build commit 615e501). Recheck these installation surfaces against the current branch before implementing.

Current behavior and evidence

The README's first route requires Git and Rust/Cargo 1.88+ and runs Cargo from a checkout. Its install link leads to a handbook page that also starts with source compilation. The technical install reference is the only substantial manual-archive guide.

The handbook says v0.8.0 archives have not been published and the technical reference calls v0.7.0 the latest archive. The live GitHub API reported v0.8.0 published on 2026-10-06 at 07:37:34 UTC, immediately before the reviewed main commit. This is a release-discovery defect, not a request to infer release status from Cargo.toml.

The manual checksum example checks every entry in SHA256SUMS. With only the Linux archive downloaded, the selected archive verified successfully but shasum exited 1 because the macOS and Windows files were absent.

The release's CLI successfully created, checked, tested and ran a project outside the repository during this review. The result was 42. A checkout-free first lesson is already supported.

• README source-first onboarding
• Handbook source route
• Handbook release claim
• Stale release reference, whole-inventory checksum command and checkout-only confirmation
• Current README claim parser recognizes a narrowly fixed phrase
• Published v0.8.0 and live release metadata

Implementation scope

1. Make handbook/getting-started/install.md the primary new-user entry point. Put a prominent Install link in the README navigation and lead Get started with the supported prebuilt route, with complete Unix and PowerShell instructions. Keep the existing technical guide as the detailed reference and source compilation as the explicit latest-main/contributor option.
2. Show a host/CPU table, the current published release link, exact binary asset names, extraction, selected-asset verification and persistent/current-terminal PATH steps. Explain that GitHub's automatically generated Source code downloads are repository snapshots. For the archive route, do not require unrelated platforms' archives or silently ignore checksum failures.
3. Immediately show: semaprax --version; semaprax new first-semaprax; semaprax check first-semaprax/semaprax.toml; semaprax test first-semaprax/semaprax.toml; semaprax run first-semaprax/semaprax.toml. These commands must work from an arbitrary fresh user directory. Keep the existing generator.
4. Attach Rust/Git requirements to source installation, Clang to native compilation, and Node to the relevant web tooling. The interpreter-first path must not imply any of these or an API key is mandatory.
5. Replace stale availability claims with links to actual release state. Label historical candidate notes as dated history; preserve their evidence instead of presenting them as the current installation status. Keep exact-tag documentation for release users and clearly label main-only capabilities.
6. Correct the source/archive naming distinction: the archive packages the full build under semaprax and includes semapraxd; a source install of only --bin semaprax is a different build. State exactly which binaries each source command installs.
7. Advertise the bootstrap and package-manager commands when those channels are actually published and usable. This ticket can land first using today's manual archives. Extend existing documentation/reconciliation checks so changes to the human wording cannot silently bypass checks of current install claims.

Acceptance criteria

• README → Install reaches one maintained beginner guide; the primary flow uses a published binary on each supported host.
• All documented URLs are real; release-bound links use the selected tag and floating discovery links resolve only once before exact-version instructions are used.
• The literal beginner command sequence runs outside a checkout and produces 42 with the selected published artifact.
• Unix and Windows instructions cover extraction, both executable names, verification and PATH; checking one downloaded archive succeeds without downloading other hosts.
• Source installation remains complete, and optional native/web prerequisites are explained at their point of use.
• No installer, package-manager listing or Marketplace listing is advertised merely because its source files or metadata exist.

Verification

• Replay the manual checksum example in a directory containing only one host archive and SHA256SUMS, then run the literal new/check/test/run sequence.
• Run existing documentation checks and add focused fixtures for stale published-version claims, absent installer assets, exact-tag links and the selected-checksum example.
• At release time validate link/asset data against the release inventory; ordinary compiler builds must remain independent of network availability.

Existing issues and boundaries

• #167 already owns release reconciliation; extend its coverage instead of replacing its state machine.
• #144 supplies the installed journey and #444 supplies harness setup. Neither implements this primary installation entry point.
• #253 remains the held Marketplace-publication issue. Linking a future listing does not authorize duplicating or completing it.

Delivery notes

Implement in the existing owning modules and test harnesses. Follow AGENTS.md and the relevant release/editor contracts. Keep fixes focused, preserve unrelated behavior, and attach the actual verification results. Do not replace existing signing, publication, project generation or harness setup with a second system.