fix(quickstart): make curl-install and af-stack dev work from a fresh clone

[AbirAbbas]

Summary

The README quickstart — curl … install.sh | bash then af-stack dev — was broken on a fresh clone in three independent ways. All three were invisible from a long-lived maintainer checkout, which is why they shipped.

1. install.sh died before downloading anything. It piped the GitHub API response into grep -m1, which exits on its first match; curl then fails its remaining write (curl: (23) Failed writing body) and, under set -o pipefail, the whole $(...) is treated as failed even though the tag parsed. Reproduced 5/5 from a file, from stdin, and via curl | bash. The script now resolves the tag from the github.com/<repo>/releases/latest 302 redirect (which also avoids the 60 req/hour unauthenticated API limit that CI runners hit) and falls back to the API with the body buffered before parsing.

2. Even when the install succeeded, af-stack dev could be "command not found". For any non-root user /usr/local/bin is not writable, so the binary landed in ~/.local/bin, which macOS never puts on PATH and Ubuntu only adds at the next login. The script printed a version banner via the absolute path and exited 0. It now prefers a usable directory that is already on PATH and, when the chosen one is not, prints the exact export PATH=… line plus the rc-file line for the user's shell. It also flags an older copy shadowing the new one.

3. A fresh clone crash-looped the runtime. .env.example set AF_STACK_KMS_KEY=change-me-to-a-real-key. Since the KMS boot gate (#141) a key that is set but cannot be loaded is fatal by design, so af-stack dev, af-stack mode, and cp .env.example .env && docker compose up all seeded that placeholder and the runtime refused to start. The example now ships the runtime's dev sentinel dev-secret-change-me (the same value docker-compose.yml defaults to), so it boots with the deterministic dev key and a warning. The docs-site quickstart also told readers to write AF_STACK_KMS_KEY=$(openssl rand -hex 32) into .env; compose passes that through literally, same crash. Fixed.

Installer hardening (from an adversarial review, each reproduced first)

• Checksum fetch failed open: any transport error on checksums.txt was reported as "not found on the release" and the install continued unverified. It now branches on the HTTP status, refuses to install otherwise with the status and curl's error, and AF_STACK_SKIP_CHECKSUM=1 is the explicit override.
• The post-install probe was silenced and ran after the success banner; it now gates the banner. install -m 0755 replaces mv so a sudo install is root-owned. mkdir gets the same sudo fallback and actionable error as the copy, and directory resolution runs before the download so a bad target fails in under a second.
• AF_STACK_VERSION=0.12.4 (bare, the spelling release.yml and the prod compose use) 404'd and blamed repo visibility; the other prefix is tried once.
• AF_STACK_DOWNLOAD_BASE points both fetches at a mirror, which is also what lets CI drive the real script against a local fake release.

Gates added so this cannot regress silently

• install-script CI job, required by ci-success (path-filtered, so unrelated PRs skip it): bash -n + shellcheck; the installer run against the real latest release piped from stdin and from a file with an exact af-stack <version> assertion (tags resolved via gh, independently of the script's own redirect); the previous release pinned both v-prefixed and bare, so a no-op pin can never pass; and a local http.server serving the real archive as a fake release, against which the script must reject a tampered checksums.txt and install nothing, refuse a missing one with HTTP 404 unless overridden, and install with the correct one.
• secrets.TestEnvExampleBootsKMS: reads the committed .env.example the way compose does, loads the KMS cipher from it, and runs the runtime's boot preflight. It fails against the old placeholder with the exact crash-loop reason and passes with the sentinel. .env.example is added to CI's Go path filter so the test runs when the example changes.

Verification

• All ten steps of the new CI job run green locally. Beyond them: the PATH warning prints the exact export line when the dir is off PATH and nothing when it is on PATH; trailing slashes are trimmed; an uncreatable dir fails before any download; unknown repo, bad pin, and missing release each fail with a specific message.
• Fresh clone of main + released af-stack v0.12.4 + af-stack dev with no manual edits: /ready reports ready, POST /api/v1/agents/supportdesk.echo echoes back, dashboard and customer app serve their sign-in pages, and the runtime logs exactly one dev-key warning with zero restarts.
• Contract test proven red on the old example, green on the new. Full go build, go vet, and go test ./... pass; golangci-lint v2.13.1 in CI's new-issues mode reports 0 new issues. docs-lint, build-docs-site (47 pages), and validate-deploy-targets pass locally.

Not in this PR

• The docs-site references port 38080 in several pages (quickstart, swap-defaults, the Scalar API browser proxy, launch posts) and wrong operator credentials on the quickstart page; that port was never a default. Separate reconciliation sweep with its own CI assertion.
• af-stack dev silently skips port auto-allocation when Node is missing or older than 18; the README now says Node is optional, but porting the preflight into the Go binary would remove the dependency.
• The af-stack dev banner could print the seeded operator login, which the README never gives.
• af-stack dev could generate a unique random KMS key when seeding a new .env instead of the shared dev sentinel.

🤖 Generated with Claude Code