Make beta release documentation reproducible

.github/ISSUE_TEMPLATE/release-checklist.md

@@ -9,7 +9,7 @@ assignees: []
 ## Release Goal
 
 - Version:
-- Type: `rc` / `stable` / `patch`
+- Type: `beta` / `rc` / `stable` / `patch`
 - Announcement target:
 
 ## Preflight
@@ -41,10 +41,13 @@ assignees: []
 
 ## Fresh Install Verification
 
-- [ ] `brew tap amberframework/amber_cli`
-- [ ] `brew install amber_cli`
+- [ ] `brew install amberframework/amber_cli/amber_cli`
 - [ ] `brew test amber_cli`
-- [ ] `amber new smoke_app -y --no-deps`
+- [ ] macOS binaries do not link to `openssl@1.1`
+- [ ] `amber new smoke_app --type web -y --no-deps`
+- [ ] Generated app pins the reviewed Amber version and ECR template
+- [ ] `shards install`, app specs, and app build pass
+- [ ] Built app starts and serves `/` plus `/css/app.css`
 
 ## Post Release
 

RELEASE_SETUP.md

@@ -10,11 +10,20 @@ A successful release means all of the following happen without manual file editi
 2. The workflow uploads release archives and checksum files to that release.
 3. The workflow dispatches `amberframework/homebrew-amber_cli`.
 4. The tap rewrites `Formula/amber_cli.rb` with the new version and checksums.
-5. The tap's smoke test proves a clean machine can:
-   - `brew tap amberframework/amber_cli`
-   - `brew install amber_cli`
+5. The tap explicitly dispatches its install validation after the bot pushes the
+   formula. This is required because pushes made by `GITHUB_TOKEN` do not start
+   push-triggered workflows.
+6. On Apple Silicon macOS and x86_64 Linux, that validation proves a clean
+   machine can:
+   - `brew install amberframework/amber_cli/amber_cli`
    - `brew test amber_cli`
-   - `amber new smoke_app -y --no-deps`
+   - create the ECR web template with `amber new smoke_app --type web`
+   - install shards, run specs, and build the generated app
+   - launch the built app and request `/` plus `/css/app.css`
+
+The fully qualified Homebrew command trusts only the `amber_cli` formula under
+Homebrew's third-party tap trust model. Do not replace it with a separate
+`brew tap` step in public installation instructions.
 
 If any one of those steps is red, the release is not ready to announce.
 
@@ -59,7 +68,7 @@ Update `shard.yml` to the release version you want to publish.
 From the CLI repo:
 
 ```bash
-./scripts/build_release.sh 2.0.1
+./scripts/build_release.sh X.Y.Z
 ```
 
 That should produce:
@@ -85,9 +94,9 @@ This exercises the same build matrix as the release workflow without uploading a
 After the dry-run is green:
 
 ```bash
-git tag v2.0.1
-git push origin v2.0.1
-gh release create v2.0.1 --repo amberframework/amber_cli --generate-notes
+git tag vX.Y.Z
+git push origin vX.Y.Z
+gh release create vX.Y.Z --repo amberframework/amber_cli --generate-notes
 ```
 
 Publishing the release triggers the automated flow:
@@ -124,13 +133,17 @@ In `amberframework/homebrew-amber_cli`, the install smoke workflow must be green
 That workflow explicitly runs:
 
 ```bash
-brew tap amberframework/amber_cli
-brew install amber_cli
+brew install amberframework/amber_cli/amber_cli
 brew test amber_cli
-amber new smoke_app -y --no-deps
+amber new smoke_app --type web -y --no-deps
+cd smoke_app
+shards install
+crystal spec
+crystal build src/smoke_app.cr -o bin/smoke_app
 ```
 
-and then verifies the scaffolded app can resolve shards and compile.
+It then starts the built application and probes the homepage and generated CSS.
+The macOS job also rejects binaries linked to `openssl@1.1`.
 
 ## Manual Recovery
 
@@ -139,7 +152,8 @@ If the tap update fails after a release:
 1. Download the release assets and checksum files from GitHub.
 2. Update `Formula/amber_cli.rb` in `amberframework/homebrew-amber_cli`.
 3. Commit and push to `main`.
-4. Re-run `.github/workflows/validate-install.yml`.
+4. Explicitly dispatch `.github/workflows/validate-install.yml`; a bot-token
+   push alone will not trigger it.
 
 If the release build fails before the tap update:
 
@@ -149,6 +163,9 @@ If the release build fails before the tap update:
 
 ## Current Packaging Direction
 
-The Homebrew tap is our supported install path today.
+The Homebrew tap and matching release archives are the supported install paths
+for Apple Silicon macOS and x86_64 Linux today. Other operating systems and
+architectures remain preview or contributor build-from-source targets until
+they have published artifacts and the same end-to-end release gates.
 
 For eventual `homebrew/core` inclusion, we should plan for a source-building formula and a clean `brew audit --new --formula amber_cli` story. The current tap keeps release onboarding fast, while the source-build path is the more likely route for upstream Homebrew acceptance.

docs/RELEASE_CHECKLIST.md

@@ -32,8 +32,9 @@ Homebrew formula pins CLI archives and checksums.
 
 1. Publish framework, CLI, and website guides with the same command names,
    versions, platform matrix, and preview labels.
-2. Check that no onboarding page uses `amber-cli`, `brew install amber-cli`, a
-   personal fork, a moving `v2-dev` dependency, or Slang for a new V2 app.
+2. Check that no onboarding page uses a hyphenated tap or formula name, a
+   separate tap step, a personal fork, a moving `v2-dev` dependency, or Slang
+   for a new V2 app.
 3. Verify all release/download links and commands from a clean shell.
 
 Do not mark the beta complete if either supported platform cannot install the

scripts/check_beta_contract.sh

@@ -11,7 +11,15 @@ grep -F 'version: 2.0.0-beta.2' src/amber_cli/commands/new.cr
 grep -F 'template: ecr' src/amber_cli/commands/new.cr
 grep -F 'brew install amberframework/amber_cli/amber_cli' README.md
 
-if grep -Ein 'brew tap amberframework/amber_cli|brew install amber_cli' README.md RELEASE_NOTES_V2.0.2.md docs/*.md; then
+files=(
+  README.md
+  RELEASE_NOTES_V2.0.2.md
+  RELEASE_SETUP.md
+  .github/ISSUE_TEMPLATE/release-checklist.md
+  docs/*.md
+)
+
+if grep -Ein 'amberframework/amber-cli|brew tap amberframework/amber_cli|brew install amber-cli|brew install amber_cli|docs\.amberframework\.org' "${files[@]}" src/amber_cli/*.cr src/amber_cli/commands/*.cr; then
   echo "Amber CLI docs contain an untrusted or incomplete Homebrew install path" >&2
   exit 1
 fi

src/amber_cli/commands/generate.cr

@@ -291,7 +291,7 @@ RETRIES
 #   #{class_name}.new.enqueue(delay: 5.minutes)
 #   #{class_name}.new.enqueue(queue: "critical")
 #
-# See: https://docs.amberframework.org/amber/guides/jobs
+# See: https://github.com/amberframework/amber/blob/v2.0.0-beta.2/docs/guides/background-jobs.md
 class #{class_name} < Amber::Jobs::Job
   include JSON::Serializable
 
@@ -389,7 +389,7 @@ METHOD
 #     .subject("Welcome!")
 #     .deliver
 #
-# See: https://docs.amberframework.org/amber/guides/mailers
+# See: https://github.com/amberframework/amber/blob/v2.0.0-beta.2/docs/guides/mailer.md
 class #{class_name}Mailer < Amber::Mailer::Base
   def initialize(@user_name : String, @user_email : String)
   end
@@ -493,7 +493,7 @@ SPEC
 #     # Handle errors: result.errors
 #   end
 #
-# See: https://docs.amberframework.org/amber/guides/schemas
+# See: https://github.com/amberframework/amber/blob/v2.0.0-beta.2/docs/guides/schema-api.md
 class #{class_name}Schema < Amber::Schema::Definition
 #{field_definitions}
 end
@@ -598,7 +598,7 @@ SPEC
 # Clients subscribe to this channel through a ClientSocket.
 # Messages sent to this channel are handled by `handle_message`.
 #
-# See: https://docs.amberframework.org/amber/guides/websockets
+# See: https://github.com/amberframework/amber/blob/v2.0.0-beta.2/docs/guides/websockets.md
 class #{class_name}Channel < Amber::WebSockets::Channel
   # Called when a client subscribes to this channel.
   # Use this for authorization or sending initial state.
@@ -629,7 +629,7 @@ CHANNEL
 # Configure in config/routes.cr:
 #   websocket "/#{file_name}", #{class_name}Socket
 #
-# See: https://docs.amberframework.org/amber/guides/websockets
+# See: https://github.com/amberframework/amber/blob/v2.0.0-beta.2/docs/guides/websockets.md
 struct #{class_name}Socket < Amber::WebSockets::ClientSocket
   channel "#{file_name}:*", #{class_name}Channel
 
@@ -854,7 +854,7 @@ SPEC
 #
 # Used by #{controller_name} for request validation.
 #
-# See: https://docs.amberframework.org/amber/guides/schemas
+# See: https://github.com/amberframework/amber/blob/v2.0.0-beta.2/docs/guides/schema-api.md
 class #{class_name}Schema < Amber::Schema::Definition
 #{field_definitions}
 end

src/amber_cli/commands/setup_lsp.cr

@@ -215,7 +215,7 @@ module AmberCLI::Commands
 
       content = <<-YAML
       # Amber LSP Configuration
-      # See: https://docs.amberframework.org/amber/guides/lsp
+      # See: https://github.com/amberframework/amber/blob/v2.0.0-beta.2/docs/guides/lsp-setup.md
 
       # Override built-in rule settings
       # rules:

src/amber_cli/documentation.cr

@@ -451,7 +451,7 @@ module AmberCLI::Documentation
   #
   # ### Getting More Help
   #
-  # - Check the [Amber Framework documentation](https://docs.amberframework.org)
+  # - Check the [Amber V2 beta documentation](https://amberframework.org/docs/v2)
   # - Join the [Crystal community](https://crystal-lang.org/community/)
   # - Report issues on [GitHub](https://github.com/amberframework/amber_cli/issues)
   class Troubleshooting