[INSTALL-04] [P2] Put install commands and a usable quickstart at the top of every release #554

Goal

A visitor landing directly on a GitHub release, or opening an extracted archive, should immediately know which download to use and how to run it.

Priority: P2 · Classification: Verified release discoverability gap

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 observed v0.8.0 release body was 94,610 characters. scripts/release-notes.py emits a beta sentence followed by the changelog and a closing archive note; it has no leading installation section or OS download table.

The archive copies the repository README verbatim, but packages neither docs/ nor handbook/. Its relative links and checkout-oriented commands are unsuitable when read inside an extracted binary distribution.

GitHub exposes verification files, binary archives and automatic source-code downloads together. New users currently have to infer which file is executable software.

• Current release-note size handling
• Current release-body rendering
• Archive includes the repository README but no documentation tree
• Windows archive layout
• Archive admission currently pins source README bytes
• v0.8.0 release page

Implementation scope

1. Render a compact Install section before Changes: release version, supported host/CPU choices, direct exact-tag binary links and a link to the canonical install guide. Add bootstrap links when their artifacts are present; derive all links from the release inventory rather than guessing filenames.
2. Keep changelog detail available through a collapsed details section or a clearly linked exact-version changelog. Preserve the existing changelog digest, release-body limit and factual release content.
3. Explain in one line which assets are runnable distributions and which are source snapshots or verification metadata. Keep cryptographic verification instructions reachable, without forcing users to read the entire release-engineering history to find a download.
4. Generate an archive-specific README.md from a small maintained release template. Include package contents, minimum runtime requirements when established, local invocation/PATH guidance, new/check/test/run instructions and working absolute links pinned to the release's documentation.
5. Replace the archive README content in both packagers while retaining one README member; update the owning exact-content admission tests intentionally. Avoid copying the whole repository or introducing a documentation dependency into the executable package.
6. Make shell examples platform-appropriate: Windows gets PowerShell commands and Unix gets POSIX commands. The default first project must use only the installed tools, not examples/ from a missing checkout.
7. Coordinate with the canonical guide in INSTALL-01; this issue owns generated release/archive surfaces, not another independent installation guide.

Acceptance criteria

• The first visible release section contains a complete platform download choice and the next command to run.
• Every generated link names an actual asset in that release and exact-version documentation; unavailable installers/channels are omitted.
• The extracted README contains no broken relative links into missing docs, handbook, examples or scripts directories.
• Following the archive README outside a checkout creates/checks/tests/runs the starter project and prints 42.
• Windows and Unix archive README variants describe their correct executable names and shell behavior.
• Release notes remain within the existing byte limit, with the complete changelog accessible and existing artifact verification intact.

Verification

• Generate release notes for a fixture with and without installer assets and assert that every download link matches the inventory.
• Extract both archive layouts and run a small link/layout check against the bundled README.
• Reuse the distribution journey's literal quickstart sequence; do not create a second end-to-end language test framework.

Existing issues and boundaries

• #167 already manages release publication and manifest reconciliation; preserve those semantics.
• #289 is not reopened. Clear access to existing verification material is a presentation improvement.
• INSTALL-01 is the related canonical-guide change; neither issue has to wait for the new installers to make current downloads easier.

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.