release: prepare v1.0.2

docs: document preflight token checks
chore(ci): add preflight token and API checks
2026-03-21 13:35:24 +00:00 · 2026-03-21 13:17:39 +00:00 · 2026-03-21 13:06:15 +00:00 · 2026-03-21 12:57:40 +00:00 · 2026-03-21 12:51:50 +00:00 · 2026-03-21 12:51:28 +00:00
17 changed files with 1288 additions and 136 deletions
--- a/.gitea/workflows/do-release.yml
+++ b/.gitea/workflows/do-release.yml
@@ -28,7 +28,7 @@ jobs:
      run:
        shell: bash
    env:
-      RELEASE_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      RELEASE_TOKEN: ${{ secrets.GITHUB_TOKEN || secrets.GITEA_TOKEN }}
      SUMMARY_FILE: ${{ runner.temp }}/do-release-summary.md
    steps:
      - name: Checkout tagged revision
@@ -52,11 +52,45 @@ jobs:
          cache: true
          cache-dependency-path: go.sum

+      - name: Preflight release API access
+        env:
+          REQUESTED_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+
+          if [[ -z "${RELEASE_TOKEN:-}" ]]; then
+            echo "No release token available. Set GITEA_TOKEN (or GITHUB_TOKEN on GitHub)." >&2
+            exit 1
+          fi
+
+          api_base="${GITHUB_API_URL:-${GITHUB_SERVER_URL%/}/api/v1}"
+          repo_api="${api_base}/repos/${GITHUB_REPOSITORY}"
+
+          curl --fail-with-body -sS \
+            -H "Authorization: token ${RELEASE_TOKEN}" \
+            -H "Content-Type: application/json" \
+            "${repo_api}" >/dev/null
+
+          curl --fail-with-body -sS \
+            -H "Authorization: token ${RELEASE_TOKEN}" \
+            -H "Content-Type: application/json" \
+            "${repo_api}/releases?limit=1" >/dev/null
+
+          requested_tag="$(printf '%s' "${REQUESTED_TAG:-}" | sed 's/^[[:space:]]\+//; s/[[:space:]]\+$//')"
+          if [[ -n "$requested_tag" ]]; then
+            normalized_tag="${requested_tag#v}"
+            tag_ref="refs/tags/v${normalized_tag}"
+            if ! git rev-parse --verify --quiet "$tag_ref" >/dev/null; then
+              echo "Requested tag ${tag_ref#refs/tags/} was not found in the checked out repository." >&2
+              exit 1
+            fi
+          fi
+
      - name: Create or update release
        id: publish
        uses: ./publish
        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ secrets.GITHUB_TOKEN || secrets.GITEA_TOKEN }}
          version: ${{ inputs.tag }}

      - name: Build release binaries
@@ -177,7 +211,7 @@ jobs:

      - name: Download released binary
        env:
-          TOKEN: ${{ github.token }}
+          TOKEN: ${{ secrets.GITHUB_TOKEN || secrets.GITEA_TOKEN }}
          TAG_NAME: ${{ needs.release.outputs.tag }}
          RELEASE_VERSION: ${{ needs.release.outputs.version }}
          ASSET_ARCH: ${{ matrix.asset_arch }}
--- a/.gitea/workflows/prepare-release.yml
+++ b/.gitea/workflows/prepare-release.yml
@@ -46,13 +46,39 @@ jobs:
        id: cache-token
        run: echo "value=${GITHUB_SHA}" >> "$GITHUB_OUTPUT"

+      - name: Resolve release tag
+        id: resolve-version
+        run: |
+          set -euo pipefail
+
+          provided_version="$(printf '%s' "${{ inputs.version }}" | sed 's/^[[:space:]]\+//; s/[[:space:]]\+$//')"
+          if [[ -z "$provided_version" ]]; then
+            release_tag="$(go run ./cmd/vociferate --recommend --root .)"
+          elif [[ "$provided_version" == v* ]]; then
+            release_tag="$provided_version"
+          else
+            release_tag="v${provided_version}"
+          fi
+
+          echo "tag=${release_tag}" >> "$GITHUB_OUTPUT"
+
+      - name: Update agent docs action tags
+        run: |
+          set -euo pipefail
+
+          release_tag="${{ steps.resolve-version.outputs.tag }}"
+          for file in README.md AGENTS.md; do
+            sed -E -i "s/@v[0-9]+\.[0-9]+\.[0-9]+/@${release_tag}/g" "$file"
+          done
+
      - name: Prepare and tag release
        id: prepare
        uses: ./prepare
        env:
          VOCIFERATE_CACHE_TOKEN: ${{ steps.cache-token.outputs.value }}
        with:
-          version: ${{ inputs.version }}
+          version: ${{ steps.resolve-version.outputs.tag }}
+          git-add-files: CHANGELOG.md release-version README.md AGENTS.md

      - name: Summarize prepared release
        run: |
--- a/.gitea/workflows/push-validation.yml
+++ b/.gitea/workflows/push-validation.yml
@@ -8,7 +8,7 @@ on:
      - "*"

 jobs:
-  validate:
+  coverage-badge:
    runs-on: ubuntu-latest
    container: docker.io/catthehacker/ubuntu:act-latest
    defaults:
@@ -35,96 +35,57 @@ jobs:
          cache: true
          cache-dependency-path: go.sum

-      - name: Install AWS CLI v2
-        uses: ankurk91/install-aws-cli-action@v1
-
-      - name: Verify AWS CLI
-        run: aws --version
-
      - name: Run full unit test suite with coverage
-        id: coverage
        run: |
          set -euo pipefail

          go test -covermode=atomic -coverprofile=coverage.out ./...
-          go tool cover -html=coverage.out -o coverage.html

-          total="$(go tool cover -func=coverage.out | awk '/^total:/ {sub(/%/, "", $3); print $3}')"
-          printf '{\n  "total": "%s"\n}\n' "$total" > coverage-summary.json
-          printf 'total=%s\n' "$total" >> "$GITHUB_OUTPUT"
+      - name: Publish coverage badge artefacts
+        id: coverage
+        uses: ./coverage-badge
+        with:
+          artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }}
+          artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
+          summary-file: ${{ env.SUMMARY_FILE }}

-      - name: Generate coverage badge
-        env:
-          COVERAGE_TOTAL: ${{ steps.coverage.outputs.total }}
+      - name: Summary
+        if: ${{ always() }}
        run: |
          set -euo pipefail

-          color="$(awk -v total="$COVERAGE_TOTAL" 'BEGIN {
-            if (total >= 80) print "brightgreen";
-            else if (total >= 70) print "green";
-            else if (total >= 60) print "yellowgreen";
-            else if (total >= 50) print "yellow";
-            else print "red";
-          }')"
-
-          cat > coverage-badge.svg <<EOF
-          <svg xmlns="http://www.w3.org/2000/svg" width="126" height="20" role="img" aria-label="coverage: ${COVERAGE_TOTAL}%">
-            <linearGradient id="smooth" x2="0" y2="100%">
-              <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
-              <stop offset="1" stop-opacity=".1"/>
-            </linearGradient>
-            <clipPath id="round">
-              <rect width="126" height="20" rx="3" fill="#fff"/>
-            </clipPath>
-            <g clip-path="url(#round)">
-              <rect width="63" height="20" fill="#555"/>
-              <rect x="63" width="63" height="20" fill="${color}"/>
-              <rect width="126" height="20" fill="url(#smooth)"/>
-            </g>
-            <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
-              <text x="32.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
-              <text x="32.5" y="14">coverage</text>
-              <text x="93.5" y="15" fill="#010101" fill-opacity=".3">${COVERAGE_TOTAL}%</text>
-              <text x="93.5" y="14">${COVERAGE_TOTAL}%</text>
-            </g>
-          </svg>
-          EOF
-
-      - name: Upload branch coverage artefacts
-        id: upload
-        run: |
-          set -euo pipefail
-
-          aws configure set default.s3.addressing_style path
-
-          repo_name="${GITHUB_REPOSITORY##*/}"
-          prefix="${repo_name}/branch/${GITHUB_REF_NAME}"
-          display_endpoint="${ARTEFACT_BUCKET_ENDPONT#https://}"
-          display_endpoint="${display_endpoint#http://}"
-          report_url="//${display_endpoint%/}/${ARTEFACT_BUCKET_NAME}/${prefix}/coverage.html"
-          badge_url="//${display_endpoint%/}/${ARTEFACT_BUCKET_NAME}/${prefix}/coverage-badge.svg"
-
-          aws --endpoint-url "${ARTEFACT_BUCKET_ENDPONT}" s3 cp coverage.html "s3://${ARTEFACT_BUCKET_NAME}/${prefix}/coverage.html" --content-type text/html
-          aws --endpoint-url "${ARTEFACT_BUCKET_ENDPONT}" s3 cp coverage-badge.svg "s3://${ARTEFACT_BUCKET_NAME}/${prefix}/coverage-badge.svg" --content-type image/svg+xml
-          aws --endpoint-url "${ARTEFACT_BUCKET_ENDPONT}" s3 cp coverage-summary.json "s3://${ARTEFACT_BUCKET_NAME}/${prefix}/coverage-summary.json" --content-type application/json
-
-          printf 'report_url=%s\n' "$report_url" >> "$GITHUB_OUTPUT"
-          printf 'badge_url=%s\n' "$badge_url" >> "$GITHUB_OUTPUT"
-
-      - name: Add coverage summary
-        run: |
-          set -euo pipefail
-
-          {
-            echo '## Coverage'
+          echo 'Summary'
          echo
-            echo '- Total: `${{ steps.coverage.outputs.total }}%`'
-            echo '- Report: ${{ steps.upload.outputs.report_url }}'
-            echo '- Badge: ${{ steps.upload.outputs.badge_url }}'
-          } >> "$SUMMARY_FILE"
+
+          if [[ -s "$SUMMARY_FILE" ]]; then
+            cat "$SUMMARY_FILE"
+          else
+            echo 'No summary generated.'
+          fi
+
+  recommend-release:
+    runs-on: ubuntu-latest
+    container: docker.io/catthehacker/ubuntu:act-latest
+    needs: coverage-badge
+    if: ${{ github.ref == 'refs/heads/main' }}
+    defaults:
+      run:
+        shell: bash
+    env:
+      SUMMARY_FILE: ${{ runner.temp }}/push-validation-recommend-summary.md
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.26.1'
+          check-latest: true
+          cache: true
+          cache-dependency-path: go.sum

      - name: Recommend next release tag on main pushes
-        if: ${{ github.ref == 'refs/heads/main' }}
        run: |
          set -euo pipefail

--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,366 @@
+# Æther Go Project Workflow Instructions
+
+These instructions apply to all coding work in Æther Go repositories.
+
+This file is self-contained. Do not assume access to this Guides repository or any other Æther repository when following these instructions.
+
+## Engineering Process: Strict TDD
+
+Follow TDD (Red, Green, Refactor) for all feature and bug-fix work:
+
+- **Red**: Write or update a test first. Confirm the test fails for the expected reason.
+- **Green**: Implement the minimum code needed to pass the test.
+- **Refactor**: Improve code only after tests are green.
+
+Do not implement behavior before a failing test exists, unless the user explicitly asks to skip TDD.
+
+## Testing Requirements
+
+- Always create and update tests in `*_test.go` files (Go language standard).
+- Use the repository's established test framework (prefer testify suites for new coverage where appropriate).
+- Run focused tests for touched packages first using `go test -run <TestName> ./path/to/package`.
+- Run broader package or module suites as needed.
+- Run full project validation when requested or when change risk warrants it.
+- Preserve behavior validated by the repository's behavior/integration suites unless a behavioral change is explicitly requested.
+
+## Coverage Standards
+
+Apply coverage gates per package/module, not repository-wide aggregate:
+
+- **Target**: 80%+ coverage per module.
+- **Warning zone**: 65% to 79.99% (below target, improve during normal engineering work).
+- **High risk**: 50% to 64.99% (requires explicit justification and follow-up).
+- **Fail gate**: Below 50% (unacceptable).
+
+Exclude generated code from coverage calculations. Run coverage analysis for changed modules:
+
+```bash
+go test -covermode=atomic -coverprofile=coverage.out ./...
+```
+
+## Commit Checkpoints
+
+Create commits at these checkpoints unless the user explicitly asks not to commit:
+
+- After writing failing tests (red commit).
+- After implementation passes tests (green commit).
+- After refactoring (if substantial refactoring occurred).
+- After changelog updates (separate docs-only commit).
+
+For each functional change block, create at least one code commit before moving to unrelated work. Keep commits small and scoped to one change unit. Use non-interactive git commands.
+
+### Changelog Commits
+
+After completing a change block:
+
+1. Update the changelog (typically `CHANGELOG.md`).
+2. Create a separate docs-only commit for changelog updates.
+3. Keep changelog commits scoped to documentation changes only—do not mix code edits into that commit.
+
+### Commit Message Guidance
+
+Prefer conventional commits with clear scopes and concise summaries.
+
+- Preferred format for Go maintenance and tooling changes: `chore(go): <summary>`
+- Preferred format for documentation updates: `docs: <summary>`
+- Keep summaries lowercase, imperative, and under 72 characters when possible.
+- Use one commit per logical change.
+
+Examples:
+
+- `chore(go): update dependency injection guidance`
+- `docs: clarify security scanning requirements`
+
+## Go Conventions
+
+- **Go version**: Target the repository's standard Go toolchain (typically `1.26.1`) and maintain compatibility with declared repository settings.
+- **Test files**: Keep tests in `*_test.go` files in the same package as the code being tested.
+- **Test suites**: Prefer testify suites for new Go test coverage where appropriate.
+- **Focused testing**: Run package-specific tests first, then broader validation when requested.
+- **Behavior parity**: Use the repository behavior suite for behavior parity validation when relevant.
+
+## Dependency Injection (DI) Pattern
+
+Dependency Injection is a required architectural pattern in Æther Go projects. Use the standards below directly:
+
+- **Interfaces as contracts**: Define interfaces to represent dependencies; place interfaces in the same package as consumers.
+- **Concrete structs**: Implement concrete types as structs that satisfy interfaces.
+- **Constructor functions**: Use `New<TypeName>` constructor functions to wire dependencies and validate inputs.
+- **No globals or singletons**: Accept dependencies as parameters; avoid hidden global state.
+- **Testing with DI**: Create concrete mock implementations of interfaces for testing; avoid reflection-based mocking.
+
+Example pattern:
+
+```go
+// Interface defines a contract.
+type UserRepository interface {
+	GetUser(ctx context.Context, id string) (*User, error)
+}
+
+// Concrete implementation satisfies the interface.
+type PostgresUserRepository struct {
+	db *sql.DB
+}
+
+func (r *PostgresUserRepository) GetUser(ctx context.Context, id string) (*User, error) {
+	// Implementation
+}
+
+// Constructor function injects dependencies.
+func NewPostgresUserRepository(db *sql.DB) (*PostgresUserRepository, error) {
+	if db == nil {
+		return nil, errors.New("database connection cannot be nil")
+	}
+	return &PostgresUserRepository{db: db}, nil
+}
+
+// Consumer type accepts interface dependency.
+type UserService struct {
+	repo UserRepository
+}
+
+func NewUserService(repo UserRepository) (*UserService, error) {
+	if repo == nil {
+		return nil, errors.New("UserRepository cannot be nil")
+	}
+	return &UserService{repo: repo}, nil
+}
+```
+
+Key rules:
+
+- Validate injected dependencies in constructors; return error if validation fails.
+- Keep interfaces minimal and focused on the consumer's contract (Interface Segregation Principle).
+- Organize packages by domain, not by layer (avoid `service`, `handler`, `repository` top-level packages).
+- Break circular dependencies using interfaces; define the interface in the consuming package.
+
+## Additional Go Conventions
+
+Beyond dependency injection, follow these Go-specific conventions:
+
+### Error Handling
+
+- Return errors as the last return value.
+- Use `errors.New()` or `fmt.Errorf()` for simple errors; use custom error types for complex cases.
+- Wrap errors with context using `fmt.Errorf("%w", err)` in Go 1.13+.
+- Do not log and return errors; let the caller decide how to handle.
+
+Example:
+
+```go
+func (s *UserService) GetUser(ctx context.Context, id string) (*User, error) {
+	if id == "" {
+		return nil, fmt.Errorf("GetUser: invalid user id")
+	}
+	user, err := s.repo.GetUser(ctx, id)
+	if err != nil {
+		return nil, fmt.Errorf("GetUser: %w", err)
+	}
+	return user, nil
+}
+```
+
+### Package Organization
+
+- Use domain-driven design principles; packages represent domain entities or use cases.
+- Keep package dependencies acyclic; use interfaces to break circular dependencies.
+- Place interfaces in consumer packages, not separate `interfaces` packages.
+- Consider a `cmd/` directory for application entry points and `internal/` for domain logic.
+
+Example structure:
+
+```
+myapp/
+  cmd/
+    myapp/
+      main.go                 # Dependency wiring
+  internal/
+    user/
+      user.go               # Domain model
+      service.go            # UserService and UserRepository interface
+      repository.go         # PostgresUserRepository
+    auth/
+      auth.go               # Domain model
+      service.go            # AuthService and AuthProvider interface
+```
+
+### Concurrency Patterns
+
+- Use goroutines and channels for concurrent work.
+- Prefer message passing (channels) over shared memory.
+- Use `context.Context` for cancellation and timeouts.
+- Protect shared state with mutexes only when channels are not practical.
+
+Example:
+
+```go
+func (s *UserService) ProcessUsers(ctx context.Context, ids []string) error {
+	workers := 5
+	jobs := make(chan string, len(ids))
+	errors := make(chan error, len(ids))
+
+	for i := 0; i < workers; i++ {
+		go func() {
+			for id := range jobs {
+				if err := s.processUser(ctx, id); err != nil {
+					errors <- err
+				}
+			}
+		}()
+	}
+
+	for _, id := range ids {
+		jobs <- id
+	}
+	close(jobs)
+
+	for i := 0; i < len(ids); i++ {
+		select {
+		case err := <-errors:
+			if err != nil {
+				return err
+			}
+		case <-ctx.Done():
+			return ctx.Err()
+		}
+	}
+	return nil
+}
+```
+
+### Code Organization and Naming
+
+- Use clear, descriptive names for types and functions.
+- Avoid `util`, `helper`, or `common` packages; prefer domain-specific package names.
+- Keep files focused; one struct per file is reasonable if the struct is substantial.
+- Use `context.Context` as the first parameter in functions that can block or make external calls.
+
+## Workflow and Release Standards
+
+When updating CI workflows or release logic:
+
+- Use the repository's standard Go setup (typically `actions/setup-go@v5` with pinned version and go.sum caching).
+- Keep workflow summary output using the summary-file pattern:
+  - Define `SUMMARY_FILE` environment variable per job.
+  - Append markdown output from steps to the summary file.
+  - Print the summary in a final `Summary` step with `if: ${{ always() }}` condition.
+- Badge URLs must use `https://{HOST}/{OWNER}/{REPO}/actions/workflows/{WORKFLOW_FILE}.yml/badge.svg{?CONTEXT_PARAMS}`.
+- Badge-link targets must use `https://{HOST}/{OWNER}/{REPO}/actions/runs/latest?workflow={WORKFLOW_FILE}.yml{&CONTEXT_PARAMS}`.
+- `CONTEXT_PARAMS` is optional; available params are `branch`, `event`, `style` for badge URLs and `branch`, `event` for badge-link targets. Prefer `branch` and `event` when filtering run context; if `style` is used, place it last.
+- Prefer latest-run pages for badge links for fast status triage.
+
+### Composite Actions and Release Orchestration
+
+Use `https://git.hrafn.xyz/aether/vociferate` as the default release-management tool when integrating Æther composite actions:
+
+- Pin all action references to released tags (for example `@v1.0.0`).
+- Keep all vociferate references on the same tag within a workflow.
+- In self-hosted runner environments (git.hrafn.xyz), use explicit `https://` action paths in `uses:` references and avoid shorthand owner/repo coordinates.
+- Use `prepare` action to update changelog/version and create release tags.
+- Use `publish` action to create/update release notes and assets from existing tags.
+- Do not mix alternate release actions unless a repository-local policy explicitly documents an override.
+- Use `coverage-badge` action after tests produce `coverage.out` for coverage artifact uploads.
+- For pre-conditions: checkout with full history (`fetch-depth: 0`), valid credentials, and required bucket variables/secrets.
+
+Minimal standalone release workflow example:
+
+```yaml
+name: release
+
+on:
+	push:
+		branches: [main]
+
+permissions:
+	contents: write
+
+jobs:
+	prepare:
+		runs-on: ubuntu-latest
+		steps:
+			- name: Checkout
+				uses: actions/checkout@v4
+				with:
+					fetch-depth: 0
+
+			- name: Vociferate prepare
+				uses: https://git.hrafn.xyz/aether/vociferate/prepare@v1.0.0
+
+	publish:
+		needs: prepare
+		runs-on: ubuntu-latest
+		steps:
+			- name: Checkout
+				uses: actions/checkout@v4
+				with:
+					fetch-depth: 0
+
+			- name: Vociferate publish
+				uses: https://git.hrafn.xyz/aether/vociferate/publish@v1.0.0
+```
+
+## Project Conventions
+
+- **Automation**: Prefer `justfile` for task automation; mirror core CI operations locally.
+- **Dependency management**: Use `go.mod` and `go.sum` for version tracking.
+- **Structure**: Keep code organized in logical packages; avoid deep nesting.
+
+## Security Standards
+
+Security standards (self-contained):
+
+- **gosec**: Run static security analysis for Go code.
+  - Command: `gosec ./...`
+  - Purpose: Detect common security issues (hard-coded secrets, SQL injection, weak crypto, etc.)
+  - Suppress: Use `#nosec` comments only with documented justification.
+
+- **govulncheck**: Check Go code and dependencies for known vulnerabilities.
+  - Command: `govulncheck ./...`
+  - Purpose: Detect vulnerabilities in direct and transitive dependencies.
+  - Address: Update vulnerable dependencies to patched versions.
+
+- **Dependency hygiene**: Keep `go.mod` and `go.sum` clean; run `go mod tidy` and `go mod verify` regularly.
+
+Integrate both tools into CI workflows; fail builds on high/critical findings.
+
+## Validation Sequence
+
+Execute validation in this order (unless repository policy specifies otherwise):
+
+1. Run focused package tests that directly cover the changed code.
+2. Run broader package or module test suites as needed.
+3. Run `gosec ./...` for security analysis.
+4. Run `govulncheck ./...` for vulnerability scanning.
+5. Run full project or behavior/integration suites when change scope or risk warrants it.
+6. Verify coverage gates per changed module/class (target 80%, low bound 65%, fail below 50%).
+
+## Safety and Scope
+
+- Do not revert unrelated local changes.
+- Avoid broad refactors outside the requested scope.
+- Keep implementation minimal and aimed only at passing the failing test.
+- Do not add code that the test does not exercise.
+
+## Disambiguation and Decision-Making
+
+If blocked by ambiguity:
+
+- Ask one concise clarifying question rather than guessing.
+- Proceed with the most reasonable interpretation based on context.
+- Document any assumption in a commit message or code comment if relevant.
+
+## Checklist: Feature or Bug-Fix Completion
+
+Before considering a task done:
+
+- ✓ A failing test existed before implementation (or skip-TDD was explicitly requested).
+- ✓ Implementation was minimal and aimed at passing the test only.
+- ✓ Refactoring happened only after tests were green.
+- ✓ Focused tests passed for all changed packages.
+- ✓ Broader validation was run when risk or scope justified it.
+- ✓ Coverage gates were evaluated per changed module/class (target 80%, low bound 65%, fail below 50%).
+- ✓ Behavioral parity expectations were preserved unless change was explicitly requested.
+- ✓ Security scanning passed: `gosec ./...` and `govulncheck ./...` without unacknowledged findings.
+- ✓ Dependency injection properly applied: dependencies injected via constructors, not globals; interfaces define contracts; concrete implementations satisfy interfaces.
+- ✓ Commits were created at checkpoints (red test, green implementation, changelog).
+- ✓ Changelog was updated with a separate docs-only commit.
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,245 @@
+# Agent Integration Guide
+
+This guide is for agentic coding partners that need to integrate the composite actions published by this repository.
+
+## Source Of Truth
+
+Pin all action references to a released tag (for example `@v1.0.2`) and keep all vociferate references on the same tag in a workflow.
+
+Published composite actions:
+
+- `git.hrafn.xyz/aether/vociferate@v1.0.2` (root action)
+- `git.hrafn.xyz/aether/vociferate/prepare@v1.0.2`
+- `git.hrafn.xyz/aether/vociferate/publish@v1.0.2`
+- `git.hrafn.xyz/aether/vociferate/coverage-badge@v1.0.2`
+- `git.hrafn.xyz/aether/vociferate/decorate-pr@v1.0.2`
+
+## Action Selection Matrix
+
+Use this when deciding which action to call:
+
+- Choose `prepare` when you need to update changelog/version files, commit, and push a release tag.
+- Choose `publish` when a tag already exists and you need to create or update release notes/assets.
+- Choose `coverage-badge` after tests have produced `coverage.out` and you need coverage artefacts uploaded.
+- Choose `decorate-pr` to annotate pull requests with coverage information and unreleased changelog entries.
+- Choose root `vociferate` for direct recommend/prepare logic without commit/tag/push behavior.
+
+## Preconditions
+
+Apply these checks before invoking actions:
+
+- Checkout repository first.
+- For prepare/publish flows that depend on tags/history, use full history checkout (`fetch-depth: 0`).
+- Use valid credentials for release/comment API calls. On GitHub, `secrets.GITHUB_TOKEN` is used; on self-hosted Gitea, set `secrets.GITEA_TOKEN`.
+- `do-release` and `decorate-pr` now run preflight API checks and fail fast when token credentials are missing or insufficient.
+- Set required vars/secrets for coverage uploads:
+  - `vars.ARTEFACT_BUCKET_NAME`
+  - `vars.ARTEFACT_BUCKET_ENDPONT`
+  - `secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY`
+  - `secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET`
+- For externally visible changelog links, set `vars.VOCIFERATE_REPOSITORY_URL` to the server/base URL only.
+
+## Changelog Format Guidance
+
+Agents should keep `CHANGELOG.md` in a Keep a Changelog compatible structure because vociferate derives versions and release notes from headings.
+
+Required conventions:
+
+- Keep the top-level heading as `# Changelog`.
+- Maintain an `## [Unreleased]` section.
+- Keep the standard subsections under `Unreleased` in this order:
+  - `### Breaking`
+  - `### Added`
+  - `### Changed`
+  - `### Removed`
+  - `### Fixed`
+- Record releases with headings like `## [1.2.3] - YYYY-MM-DD`.
+- Use bullet entries under subsections (for example `- Added new publish output`).
+- Preserve or regenerate bottom reference links (`[Unreleased]: ...`, `[1.2.3]: ...`) instead of mixing inline heading links.
+
+Semver behavior used by recommendation logic:
+
+- `Breaking` or `Removed` entries trigger a major bump.
+- `Added` entries trigger a minor bump.
+- Otherwise recommendation falls back to a patch bump.
+
+Minimal template:
+
+```markdown
+# Changelog
+
+## [Unreleased]
+
+### Breaking
+
+### Added
+
+### Changed
+
+### Removed
+
+### Fixed
+```
+
+## Minimal Integration Patterns
+
+### 1. Prepare Then Publish
+
+```yaml
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - id: prepare
+        uses: git.hrafn.xyz/aether/vociferate/prepare@v1.0.2
+
+  publish:
+    needs: prepare
+    uses: aether/vociferate/.gitea/workflows/do-release.yml@v1.0.2
+    with:
+      tag: ${{ needs.prepare.outputs.version }}
+    secrets: inherit
+```
+
+### 2. Publish Existing Tag
+
+```yaml
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - id: publish
+        uses: git.hrafn.xyz/aether/vociferate/publish@v1.0.2
+        with:
+          version: v1.2.3
+```
+
+### 3. Coverage Badge Publication
+
+```yaml
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    env:
+      AWS_ACCESS_KEY_ID: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET }}
+      AWS_DEFAULT_REGION: ${{ vars.ARTEFACT_BUCKET_REGION }}
+      AWS_EC2_METADATA_DISABLED: true
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run tests with coverage
+        run: go test -covermode=atomic -coverprofile=coverage.out ./...
+      - id: badge
+        uses: git.hrafn.xyz/aether/vociferate/coverage-badge@v1.0.2
+        with:
+          artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }}
+          artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
+```
+
+### 4. Decorate Pull Request With Coverage and Changes
+
+```yaml
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    env:
+      AWS_ACCESS_KEY_ID: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET }}
+      AWS_DEFAULT_REGION: ${{ vars.ARTEFACT_BUCKET_REGION }}
+      AWS_EC2_METADATA_DISABLED: true
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run tests with coverage
+        run: go test -covermode=atomic -coverprofile=coverage.out ./...
+      - id: badge
+        uses: git.hrafn.xyz/aether/vociferate/coverage-badge@v1.0.2
+        with:
+          artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }}
+          artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
+      - name: Decorate PR
+        uses: git.hrafn.xyz/aether/vociferate/decorate-pr@v1.0.2
+        with:
+          coverage-percentage: ${{ steps.badge.outputs.total }}
+          badge-url: ${{ steps.badge.outputs.badge-url }}
+```
+
+## Inputs And Outputs Cheatsheet
+
+### prepare
+
+Common inputs:
+
+- `version` (optional override)
+- `version-file` (optional)
+- `version-pattern` (optional)
+- `changelog` (optional)
+
+Primary output:
+
+- `version` (resolved tag, for example `v1.2.3`)
+
+### publish
+
+Common inputs:
+
+- `token` (optional, defaults to workflow token)
+- `version` (optional if running from tag ref)
+- `changelog` (optional)
+
+Primary outputs:
+
+- `release-id`
+- `tag`
+- `version`
+
+### coverage-badge
+
+Required inputs:
+
+- `artefact-bucket-name`
+- `artefact-bucket-endpoint`
+
+Useful optional inputs:
+
+- `coverage-profile` (default `coverage.out`)
+- `summary-file` (append markdown summary)
+
+Primary outputs:
+
+- `total`
+- `report-url`
+- `badge-url`
+
+### decorate-pr
+
+Required inputs:
+
+- `coverage-percentage` (0-100, typically from coverage-badge action)
+- `badge-url` (SVG badge URL, typically from coverage-badge action)
+
+Useful optional inputs:
+
+- `changelog` (default `CHANGELOG.md`)
+- `comment-title` (default `Vociferate Review`)
+- `token` (defaults to workflow token)
+
+Primary outputs:
+
+- `comment-id`
+- `comment-url`
+
+## Guardrails For Agents
+
+Use these rules to avoid common automation mistakes:
+
+- Do not mix action tags in one workflow update.
+- Do not assume a release workflow will run from a tag push in all environments; reusable workflow call paths are supported.
+- Do not treat `VOCIFERATE_REPOSITORY_URL` as a full repository URL; it must be a base URL.
+- Do not bypass preflight failures with broad retry loops; fix token scope/secret wiring first.
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,8 +2,8 @@

 All notable changes to this project will be documented in this file.

-The format is based on [Keep a Changelog](//keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](//semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

 A `### Breaking` section is used in addition to Keep a Changelog's standard sections to explicitly document changes that are backwards-incompatible but would otherwise appear under `### Changed`. Entries under `### Breaking` trigger a major version bump in automated release recommendation logic.

@@ -19,6 +19,49 @@ A `### Breaking` section is used in addition to Keep a Changelog's standard sect

 ### Fixed

+## [1.0.2] - 2026-03-21
+
+### Breaking
+
+### Added
+
+### Changed
+
+- Documented release/PR-decoration preflight token and API-access checks, including `GITHUB_TOKEN`/`GITEA_TOKEN` behavior for self-hosted Gitea.
+
+### Removed
+
+### Fixed
+
+## [1.0.1] - 2026-03-21
+
+### Breaking
+
+### Added
+
+### Changed
+
+### Removed
+
+### Fixed
+
+- Enforced explicit `https://` changelog reference links in prepare output for browser-safe markdown links.
+
+## [1.0.0] - 2026-03-21
+
+### Breaking
+
+### Added
+
+### Changed
+
+- Canonical changelog filename is now `CHANGELOG.md`, and action/code defaults were updated to match.
+- README now uses `Æther` stylization in prose and corrects released-tag guidance wording.
+
+### Removed
+
+### Fixed
+
 ## [0.2.0] - 2026-03-21

 ### Breaking
@@ -27,14 +70,19 @@ A `### Breaking` section is used in addition to Keep a Changelog's standard sect

 - Added a project LICENSE file.
 - Root and prepare actions now read `${{ vars.VOCIFERATE_REPOSITORY_URL }}` and forward it to `VOCIFERATE_REPOSITORY_URL` for repository URL override.
+- Added a published `coverage-badge` composite action for generating and uploading coverage report/badge artefacts for reuse across repositories.
+- Added `AGENTS.md`, an explicit integration guide for agentic coding partners using vociferate composite actions.

 ### Changed

+- Push validation now handles coverage artefact and badge generation in a dedicated `coverage-badge` job, with release recommendation isolated in a separate dependent job.
+- Push validation now calls the reusable `./coverage-badge` composite action for coverage badge generation and publication.
+
 ### Removed

 ### Fixed

- Browser-facing URLs emitted in generated changelog links, workflow summaries, and markdown now use protocol-relative `//` forms.
+- Browser-facing URLs emitted in generated changelog links, workflow summaries, and markdown now use explicit `https://` forms.
 - Release workflows now collect summary markdown into portable temp files and print it in explicit `Summary` steps instead of relying on unsupported `GITHUB_STEP_SUMMARY` output.
 - Prepare now recreates the standard `Unreleased` section headers after promoting notes into a tagged release entry.
 - First-release recommendation remains `v1.0.0` when no prior releases exist in the changelog.
@@ -76,6 +124,9 @@ A `### Breaking` section is used in addition to Keep a Changelog's standard sect
 - Project/automation rename from `releaseprep` to `vociferate` (entrypoint, package paths, outputs).
 - README guidance focused on primary cross-repository reuse workflows.

-[Unreleased]: //git.hrafn.xyz/aether/vociferate/compare/v0.2.0...main
-[0.2.0]: //git.hrafn.xyz/aether/vociferate/compare/v0.1.0...v0.2.0
-[0.1.0]: //git.hrafn.xyz/aether/vociferate/compare/2060af6...v0.1.0
+[Unreleased]: https://git.hrafn.xyz/aether/vociferate/compare/v1.0.2...main
+[1.0.2]: https://git.hrafn.xyz/aether/vociferate/compare/v1.0.1...v1.0.2
+[1.0.1]: https://git.hrafn.xyz/aether/vociferate/compare/v1.0.0...v1.0.1
+[1.0.0]: https://git.hrafn.xyz/aether/vociferate/compare/v0.2.0...v1.0.0
+[0.2.0]: https://git.hrafn.xyz/aether/vociferate/compare/v0.1.0...v0.2.0
+[0.1.0]: https://git.hrafn.xyz/aether/vociferate/compare/2060af6...v0.1.0
--- a/README.md
+++ b/README.md
@@ -1,11 +1,11 @@
 # vociferate

-[![Main Validation](//git.hrafn.xyz/aether/vociferate/actions/workflows/push-validation.yml/badge.svg?branch=main&event=push)](//git.hrafn.xyz/aether/vociferate/actions/runs/latest?workflow=push-validation.yml&branch=main&event=push)
-[![Prepare Release](//git.hrafn.xyz/aether/vociferate/actions/workflows/prepare-release.yml/badge.svg?event=workflow_dispatch)](//git.hrafn.xyz/aether/vociferate/actions/runs/latest?workflow=prepare-release.yml)
-[![Do Release](//git.hrafn.xyz/aether/vociferate/actions/workflows/do-release.yml/badge.svg?event=push)](//git.hrafn.xyz/aether/vociferate/actions/runs/latest?workflow=do-release.yml)
-[![Coverage](//s3.hrafn.xyz/aether-workflow-report-artefacts/vociferate/branch/main/coverage-badge.svg)](//s3.hrafn.xyz/aether-workflow-report-artefacts/vociferate/branch/main/coverage.html)
+[![Main Validation](https://git.hrafn.xyz/aether/vociferate/actions/workflows/push-validation.yml/badge.svg?branch=main&event=push)](https://git.hrafn.xyz/aether/vociferate/actions/runs/latest?workflow=push-validation.yml&branch=main&event=push)
+[![Prepare Release](https://git.hrafn.xyz/aether/vociferate/actions/workflows/prepare-release.yml/badge.svg?event=workflow_dispatch)](https://git.hrafn.xyz/aether/vociferate/actions/runs/latest?workflow=prepare-release.yml)
+[![Do Release](https://git.hrafn.xyz/aether/vociferate/actions/workflows/do-release.yml/badge.svg?event=push)](https://git.hrafn.xyz/aether/vociferate/actions/runs/latest?workflow=do-release.yml)
+[![Coverage](https://s3.hrafn.xyz/aether-workflow-report-artefacts/vociferate/branch/main/coverage-badge.svg)](https://s3.hrafn.xyz/aether-workflow-report-artefacts/vociferate/branch/main/coverage.html)

-`vociferate` is an `aether` release orchestration tool written in Go for repositories that
+`vociferate` is an `Æther` release orchestration tool written in Go for repositories that
 want changelog-driven versioning, automated release preparation, and repeatable
 tag publication.

@@ -16,8 +16,10 @@ revision.

 ## Use In Other Repositories

-Vociferate ships two composite actions that together cover the full release flow.
-Until release tags are created, reference `@main`. Once tags exist again, pin both actions to the same released tag.
+Vociferate ships composite actions covering release preparation, release publication, coverage badge publishing, and pull request decoration.
+Release tags now exist; pin all action and reusable-workflow references to the same released tag (for example, `@v1.0.2`) instead of `@main`.
+
+For agentic coding partners, see [`AGENTS.md`](AGENTS.md) for a direct integration playbook, selection matrix, and copy-paste workflow patterns.

 ### `prepare` — update files, commit, and push tag

@@ -39,19 +41,19 @@ jobs:
        with:
          fetch-depth: 0

-      - uses: git.hrafn.xyz/aether/vociferate/prepare@main
+      - uses: git.hrafn.xyz/aether/vociferate/prepare@v1.0.2
        with:
          version: ${{ inputs.version }}

  publish:
    needs: prepare
-    uses: aether/vociferate/.gitea/workflows/do-release.yml@main
+    uses: aether/vociferate/.gitea/workflows/do-release.yml@v1.0.2
    with:
      tag: ${{ needs.prepare.outputs.version }}
    secrets: inherit
 ```

-Downloads a prebuilt vociferate binary, runs it to update `changelog.md` and
+Downloads a prebuilt vociferate binary, runs it to update `CHANGELOG.md` and
 `release-version`, then commits those changes to the default branch and pushes
 the release tag. Does not require Go on the runner.

@@ -59,11 +61,11 @@ For repositories that embed the version inside source code, pass `version-file`
 and `version-pattern`:

 ```yaml
- uses: git.hrafn.xyz/aether/vociferate/prepare@main
+- uses: git.hrafn.xyz/aether/vociferate/prepare@v1.0.2
  with:
    version-file: internal/myapp/version/version.go
    version-pattern: 'const Version = "([^"]+)"'
-    git-add-files: changelog.md internal/myapp/version/version.go
+    git-add-files: CHANGELOG.md internal/myapp/version/version.go
 ```

 `prepare` uses `github.token` internally for authenticated fetch/push operations,
@@ -83,22 +85,27 @@ on:

 jobs:
  release:
-    uses: aether/vociferate/.gitea/workflows/do-release.yml@main
+    uses: aether/vociferate/.gitea/workflows/do-release.yml@v1.0.2
    with:
      tag: ${{ inputs.tag }}
    secrets: inherit
 ```

-Reads the matching section from `changelog.md` and creates or updates the
+Reads the matching section from `CHANGELOG.md` and creates or updates the
 Gitea/GitHub release with those notes. The `version` input is optional — when
 omitted it is derived from the current tag ref automatically.

+The reusable `Do Release` workflow now runs preflight checks before publish to
+fail fast when the release token is missing or lacks API access. On
+self-hosted Gitea, set `secrets.GITEA_TOKEN`; on GitHub, `secrets.GITHUB_TOKEN`
+is used automatically.
+
 The `publish` action outputs `release-id` so you can upload additional release
 assets after it runs:

 ```yaml
 - id: publish
-  uses: git.hrafn.xyz/aether/vociferate/publish@main
+  uses: git.hrafn.xyz/aether/vociferate/publish@v1.0.2

 - name: Upload my binary
  run: |
@@ -109,6 +116,53 @@ assets after it runs:
      --data-binary "@dist/myapp"
 ```

+### `coverage-badge` - publish coverage report and badge
+
+Run your coverage tests first, then call the action to generate `coverage.html`, `coverage-badge.svg`, and `coverage-summary.json`, upload them to S3-compatible storage, and emit output URLs.
+
+```yaml
+- name: Run tests with coverage
+  run: go test -covermode=atomic -coverprofile=coverage.out ./...
+
+- id: coverage
+  uses: git.hrafn.xyz/aether/vociferate/coverage-badge@v1.0.2
+  with:
+    artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }}
+    artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
+
+- name: Print coverage links
+  run: |
+    echo "Report: ${{ steps.coverage.outputs.report-url }}"
+    echo "Badge: ${{ steps.coverage.outputs.badge-url }}"
+```
+
+### `decorate-pr` - annotate pull requests with coverage and changes
+
+Decorate pull requests with coverage badges, coverage percentages, and unreleased changelog entries. The action creates a new comment or updates an existing one on each run.
+
+`decorate-pr` also runs a preflight comment API check so workflows fail early
+with a clear message when token permissions are insufficient.
+
+```yaml
+- name: Run tests with coverage
+  run: go test -covermode=atomic -coverprofile=coverage.out ./...
+
+- id: coverage
+  uses: git.hrafn.xyz/aether/vociferate/coverage-badge@v1.0.2
+  with:
+    artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }}
+    artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
+
+- name: Decorate pull request
+  if: github.event_name == 'pull_request'
+  uses: git.hrafn.xyz/aether/vociferate/decorate-pr@v1.0.2
+  with:
+    coverage-percentage: ${{ steps.coverage.outputs.total }}
+    badge-url: ${{ steps.coverage.outputs.badge-url }}
+```
+
+The action automatically finds existing vociferate comments by their marker and updates them instead of creating duplicates. This keeps PR timelines clean while keeping review information current.
+
 ## Why The Name

 > **vociferate** _(verb)_: to cry out loudly or forcefully.
@@ -163,7 +217,7 @@ Defaults:

 - `version-file`: `release-version`
 - `version-pattern`: `^\s*([^\r\n]+)\s*$`
- `changelog`: `changelog.md`
+- `changelog`: `CHANGELOG.md`

 When no `--version-file` flag is provided, `vociferate` derives the current version from the most recent released section heading in the changelog (`## [x.y.z] - ...`). If no prior releases exist, it defaults to `0.0.0` and recommends `v1.0.0` as the first tag.

@@ -183,7 +237,7 @@ just go-test

 Releases use two workflows:

- `Prepare Release` runs on demand, updates `release-version` and `changelog.md`, commits those changes back to `main`, and pushes the release tag.
+- `Prepare Release` runs on demand, updates `release-version` and `CHANGELOG.md`, commits those changes back to `main`, and pushes the release tag.
 - `Prepare Release` then calls `Do Release` directly via reusable `workflow_call` with the resolved tag.
 - `Do Release` reads the matching changelog section from that tagged revision, creates or updates the release, and uploads prebuilt binaries.

--- a/action.yml
+++ b/action.yml
@@ -16,7 +16,7 @@ inputs:
  changelog:
    description: Path to changelog file relative to repository root.
    required: false
-    default: changelog.md
+    default: CHANGELOG.md
  recommend:
    description: If true, print recommended next release tag.
    required: false
--- a/cmd/vociferate/main_test.go
+++ b/cmd/vociferate/main_test.go
@@ -12,7 +12,7 @@ import (
 func TestMainRecommendPrintsTag(t *testing.T) {
 	root := t.TempDir()
 	writeFile(t, filepath.Join(root, "release-version"), "1.1.6\n")
-	writeFile(t, filepath.Join(root, "changelog.md"), "# Changelog\n\n## [Unreleased]\n\n### Added\n\n- Feature.\n\n## [1.1.6] - 2017-12-20\n")
+	writeFile(t, filepath.Join(root, "CHANGELOG.md"), "# Changelog\n\n## [Unreleased]\n\n### Added\n\n- Feature.\n\n## [1.1.6] - 2017-12-20\n")

 	stdout, stderr, code := runMain(t, "--recommend", "--root", root)
 	if code != 0 {
@@ -37,7 +37,7 @@ func TestMainPrepareUpdatesFiles(t *testing.T) {
 	root := t.TempDir()
 	writeFile(t, filepath.Join(root, ".git", "config"), "[remote \"origin\"]\n\turl = git@git.hrafn.xyz:aether/vociferate.git\n")
 	writeFile(t, filepath.Join(root, "release-version"), "1.1.6\n")
-	writeFile(t, filepath.Join(root, "changelog.md"), "# Changelog\n\n## [Unreleased]\n\n### Fixed\n\n- Patch note.\n\n## [1.1.6] - 2017-12-20\n")
+	writeFile(t, filepath.Join(root, "CHANGELOG.md"), "# Changelog\n\n## [Unreleased]\n\n### Fixed\n\n- Patch note.\n\n## [1.1.6] - 2017-12-20\n")

 	_, stderr, code := runMain(t, "--version", "v1.1.7", "--date", "2026-03-20", "--root", root)
 	if code != 0 {
--- a/coverage-badge/action.yml
+++ b/coverage-badge/action.yml
@@ -0,0 +1,168 @@
+name: vociferate/coverage-badge
+description: >
+  Generate coverage report artefacts, publish them to object storage,
+  and expose report URLs for workflow summaries.
+
+inputs:
+  coverage-profile:
+    description: Path to the Go coverage profile file.
+    required: false
+    default: coverage.out
+  coverage-html:
+    description: Output path for the rendered HTML coverage report.
+    required: false
+    default: coverage.html
+  coverage-badge:
+    description: Output path for the generated SVG badge.
+    required: false
+    default: coverage-badge.svg
+  coverage-summary:
+    description: Output path for the generated coverage summary JSON.
+    required: false
+    default: coverage-summary.json
+  artefact-bucket-name:
+    description: S3 bucket name for published coverage artefacts.
+    required: true
+  artefact-bucket-endpoint:
+    description: Endpoint URL used for S3-compatible uploads.
+    required: true
+  branch-name:
+    description: Branch name used in the publication path.
+    required: false
+    default: ''
+  repository-name:
+    description: Repository name used in the publication path.
+    required: false
+    default: ''
+  summary-file:
+    description: Optional file path to append markdown summary output.
+    required: false
+    default: ''
+
+outputs:
+  total:
+    description: Computed coverage percentage.
+    value: ${{ steps.generate.outputs.total }}
+  report-url:
+    description: Browser-facing URL for the published coverage report.
+    value: ${{ steps.upload.outputs.report_url }}
+  badge-url:
+    description: Browser-facing URL for the published coverage badge.
+    value: ${{ steps.upload.outputs.badge_url }}
+
+runs:
+  using: composite
+  steps:
+    - name: Install AWS CLI v2
+      uses: ankurk91/install-aws-cli-action@v1
+
+    - name: Verify AWS CLI
+      shell: bash
+      run: aws --version
+
+    - name: Generate coverage artefacts
+      id: generate
+      shell: bash
+      env:
+        COVERAGE_PROFILE: ${{ inputs.coverage-profile }}
+        COVERAGE_HTML: ${{ inputs.coverage-html }}
+        COVERAGE_BADGE: ${{ inputs.coverage-badge }}
+        COVERAGE_SUMMARY: ${{ inputs.coverage-summary }}
+      run: |
+        set -euo pipefail
+
+        go tool cover -html="$COVERAGE_PROFILE" -o "$COVERAGE_HTML"
+
+        total="$(go tool cover -func="$COVERAGE_PROFILE" | awk '/^total:/ {sub(/%/, "", $3); print $3}')"
+        printf '{\n  "total": "%s"\n}\n' "$total" > "$COVERAGE_SUMMARY"
+        printf 'total=%s\n' "$total" >> "$GITHUB_OUTPUT"
+
+        color="$(awk -v total="$total" 'BEGIN {
+          if (total >= 80) print "brightgreen";
+          else if (total >= 70) print "green";
+          else if (total >= 60) print "yellowgreen";
+          else if (total >= 50) print "yellow";
+          else print "red";
+        }')"
+
+        cat > "$COVERAGE_BADGE" <<EOF
+        <svg xmlns="http://www.w3.org/2000/svg" width="126" height="20" role="img" aria-label="coverage: ${total}%">
+          <linearGradient id="smooth" x2="0" y2="100%">
+            <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+            <stop offset="1" stop-opacity=".1"/>
+          </linearGradient>
+          <clipPath id="round">
+            <rect width="126" height="20" rx="3" fill="#fff"/>
+          </clipPath>
+          <g clip-path="url(#round)">
+            <rect width="63" height="20" fill="#555"/>
+            <rect x="63" width="63" height="20" fill="${color}"/>
+            <rect width="126" height="20" fill="url(#smooth)"/>
+          </g>
+          <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
+            <text x="32.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
+            <text x="32.5" y="14">coverage</text>
+            <text x="93.5" y="15" fill="#010101" fill-opacity=".3">${total}%</text>
+            <text x="93.5" y="14">${total}%</text>
+          </g>
+        </svg>
+        EOF
+
+    - name: Upload coverage artefacts
+      id: upload
+      shell: bash
+      env:
+        ARTEFACT_BUCKET_NAME: ${{ inputs.artefact-bucket-name }}
+        ARTEFACT_BUCKET_ENDPONT: ${{ inputs.artefact-bucket-endpoint }}
+        INPUT_BRANCH_NAME: ${{ inputs.branch-name }}
+        INPUT_REPOSITORY_NAME: ${{ inputs.repository-name }}
+        COVERAGE_HTML: ${{ inputs.coverage-html }}
+        COVERAGE_BADGE: ${{ inputs.coverage-badge }}
+        COVERAGE_SUMMARY: ${{ inputs.coverage-summary }}
+      run: |
+        set -euo pipefail
+
+        aws configure set default.s3.addressing_style path
+
+        branch_name="$(printf '%s' "$INPUT_BRANCH_NAME" | sed 's/^[[:space:]]\+//; s/[[:space:]]\+$//')"
+        if [[ -z "$branch_name" ]]; then
+          branch_name="${GITHUB_REF_NAME}"
+        fi
+
+        repo_name="$(printf '%s' "$INPUT_REPOSITORY_NAME" | sed 's/^[[:space:]]\+//; s/[[:space:]]\+$//')"
+        if [[ -z "$repo_name" ]]; then
+          repo_name="${GITHUB_REPOSITORY##*/}"
+        fi
+
+        prefix="${repo_name}/branch/${branch_name}"
+
+        display_endpoint="${ARTEFACT_BUCKET_ENDPONT#https://}"
+        display_endpoint="${display_endpoint#http://}"
+        report_url="https://${display_endpoint%/}/${ARTEFACT_BUCKET_NAME}/${prefix}/coverage.html"
+        badge_url="https://${display_endpoint%/}/${ARTEFACT_BUCKET_NAME}/${prefix}/coverage-badge.svg"
+
+        aws --endpoint-url "${ARTEFACT_BUCKET_ENDPONT}" s3 cp "$COVERAGE_HTML" "s3://${ARTEFACT_BUCKET_NAME}/${prefix}/coverage.html" --content-type text/html
+        aws --endpoint-url "${ARTEFACT_BUCKET_ENDPONT}" s3 cp "$COVERAGE_BADGE" "s3://${ARTEFACT_BUCKET_NAME}/${prefix}/coverage-badge.svg" --content-type image/svg+xml
+        aws --endpoint-url "${ARTEFACT_BUCKET_ENDPONT}" s3 cp "$COVERAGE_SUMMARY" "s3://${ARTEFACT_BUCKET_NAME}/${prefix}/coverage-summary.json" --content-type application/json
+
+        printf 'report_url=%s\n' "$report_url" >> "$GITHUB_OUTPUT"
+        printf 'badge_url=%s\n' "$badge_url" >> "$GITHUB_OUTPUT"
+
+    - name: Append coverage summary
+      if: ${{ inputs.summary-file != '' }}
+      shell: bash
+      env:
+        SUMMARY_FILE: ${{ inputs.summary-file }}
+        TOTAL: ${{ steps.generate.outputs.total }}
+        REPORT_URL: ${{ steps.upload.outputs.report_url }}
+        BADGE_URL: ${{ steps.upload.outputs.badge_url }}
+      run: |
+        set -euo pipefail
+
+        {
+          echo '## Coverage'
+          echo
+          echo "- Total: \`${TOTAL}%\`"
+          echo "- Report: ${REPORT_URL}"
+          echo "- Badge: ${BADGE_URL}"
+        } >> "$SUMMARY_FILE"
--- a/decorate-pr/action.yml
+++ b/decorate-pr/action.yml
@@ -0,0 +1,234 @@
+name: vociferate/decorate-pr
+description: >
+  Decorate pull requests with coverage badges, unreleased changelog entries,
+  and other useful review information. Updates existing comment or creates a
+  new one if it doesn't exist.
+
+inputs:
+  coverage-percentage:
+    description: >
+      Computed coverage percentage (0-100). Typically from coverage-badge
+      action outputs.
+    required: true
+  badge-url:
+    description: >
+      Browser-facing URL for the coverage badge image (SVG). Typically from
+      coverage-badge action outputs.
+    required: true
+  changelog:
+    description: Path to changelog file relative to repository root.
+    required: false
+    default: CHANGELOG.md
+  comment-title:
+    description: >
+      Title/identifier for the PR comment. Used to locate existing comment
+      for updates. Defaults to 'Vociferate Review'.
+    required: false
+    default: 'Vociferate Review'
+  token:
+    description: >
+      GitHub or Gitea token for posting PR comments. Defaults to the
+      workflow token.
+    required: false
+    default: ''
+
+outputs:
+  comment-id:
+    description: Numeric ID of the posted or updated PR comment.
+    value: ${{ steps.post-comment.outputs.comment_id }}
+  comment-url:
+    description: URL to the posted or updated PR comment.
+    value: ${{ steps.post-comment.outputs.comment_url }}
+
+runs:
+  using: composite
+  steps:
+    - name: Validate PR context
+      id: validate
+      shell: bash
+      env:
+        GITHUB_EVENT_NAME: ${{ github.event_name }}
+        PR_NUMBER: ${{ github.event.pull_request.number }}
+      run: |
+        set -euo pipefail
+
+        if [[ "$GITHUB_EVENT_NAME" != "pull_request" ]]; then
+          echo "This action only works on pull_request events" >&2
+          exit 1
+        fi
+
+        if [[ -z "$PR_NUMBER" ]]; then
+          echo "Could not determine PR number from context" >&2
+          exit 1
+        fi
+
+        printf 'pr_number=%s\n' "$PR_NUMBER" >> "$GITHUB_OUTPUT"
+
+    - name: Preflight comment API access
+      id: preflight
+      shell: bash
+      env:
+        AUTH_TOKEN: ${{ inputs.token != '' && inputs.token || github.token }}
+        PR_NUMBER: ${{ steps.validate.outputs.pr_number }}
+        SERVER_URL: ${{ github.server_url }}
+        REPOSITORY: ${{ github.repository }}
+      run: |
+        set -euo pipefail
+
+        if [[ -z "$AUTH_TOKEN" ]]; then
+          echo "No token available for PR comment API calls. Set input token or provide workflow token." >&2
+          exit 1
+        fi
+
+        api_url="${SERVER_URL}/api/v1"
+        if [[ "$SERVER_URL" == *"github.com"* ]]; then
+          api_url="https://api.github.com"
+        fi
+
+        comments_url="${api_url}/repos/${REPOSITORY}/issues/${PR_NUMBER}/comments"
+
+        curl --fail-with-body -sS \
+          -H "Authorization: Bearer ${AUTH_TOKEN}" \
+          -H "Content-Type: application/json" \
+          "$comments_url" >/dev/null
+
+    - name: Extract changelog unreleased entries
+      id: extract-changelog
+      shell: bash
+      env:
+        CHANGELOG: ${{ inputs.changelog }}
+      run: |
+        set -euo pipefail
+
+        if [[ ! -f "$CHANGELOG" ]]; then
+          printf 'unreleased_entries=%s\n' "" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        # Extract everything between [Unreleased] header and the next [X.Y.Z] header
+        unreleased="$(awk '
+          /^## \[Unreleased\]/ { in_unreleased=1; next }
+          /^## \[[0-9]+\.[0-9]+\.[0-9]+\]/ { if (in_unreleased) exit }
+          in_unreleased && NF { print }
+        ' "$CHANGELOG")"
+
+        # Use a temporary file to handle multiline content
+        tmp_file=$(mktemp)
+        printf '%s' "$unreleased" > "$tmp_file"
+        
+        # Read it back and set as output
+        delimiter="EOF_CHANGELOG"
+        printf '%s<<%s\n' "unreleased_entries<<$delimiter" "$delimiter" >> "$GITHUB_OUTPUT"
+        cat "$tmp_file" >> "$GITHUB_OUTPUT"
+        printf '%s\n' "$delimiter" >> "$GITHUB_OUTPUT"
+        
+        rm -f "$tmp_file"
+
+    - name: Build PR comment markdown
+      id: build-comment
+      shell: bash
+      env:
+        COMMENT_TITLE: ${{ inputs.comment-title }}
+        COVERAGE_PCT: ${{ inputs.coverage-percentage }}
+        BADGE_URL: ${{ inputs.badge-url }}
+        UNRELEASED: ${{ steps.extract-changelog.outputs.unreleased_entries }}
+      run: |
+        set -euo pipefail
+
+        # Start building the comment
+        tmp_file=$(mktemp)
+        
+        # Add title and coverage section
+        cat > "$tmp_file" << 'EOF'
+<!-- vociferate-pr-review -->
+EOF
+        
+        printf '## %s\n\n' "$COMMENT_TITLE" >> "$tmp_file"
+        
+        # Coverage badge section
+        cat >> "$tmp_file" << EOF
+### Coverage
+![Coverage Badge]($BADGE_URL)
+
+**Coverage:** $COVERAGE_PCT%
+
+EOF
+        
+        # Changelog section
+        if [[ -n "$UNRELEASED" ]]; then
+          cat >> "$tmp_file" << 'EOF'
+### Unreleased Changes
+
+EOF
+          printf '%s\n' "$UNRELEASED" >> "$tmp_file"
+          printf '\n' >> "$tmp_file"
+        fi
+        
+        # Add footer
+        cat >> "$tmp_file" << 'EOF'
+---
+*This comment was automatically generated by [vociferate/decorate-pr](https://git.hrafn.xyz/aether/vociferate).*
+EOF
+        
+        # Store as output using delimiter
+        delimiter="EOF_COMMENT"
+        printf '%s<<%s\n' "comment_body<<$delimiter" "$delimiter" >> "$GITHUB_OUTPUT"
+        cat "$tmp_file" >> "$GITHUB_OUTPUT"
+        printf '%s\n' "$delimiter" >> "$GITHUB_OUTPUT"
+        
+        rm -f "$tmp_file"
+
+    - name: Find and update/post PR comment
+      id: post-comment
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ inputs.token != '' && inputs.token || github.token }}
+        PR_NUMBER: ${{ steps.validate.outputs.pr_number }}
+        COMMENT_BODY: ${{ steps.build-comment.outputs.comment_body }}
+        SERVER_URL: ${{ github.server_url }}
+        REPOSITORY: ${{ github.repository }}
+      run: |
+        set -euo pipefail
+
+        API_URL="${SERVER_URL}/api/v1"
+        if [[ "$SERVER_URL" == *"github.com"* ]]; then
+          API_URL="https://api.github.com"
+        fi
+
+        # List existing comments to find vociferate comment
+        comments_url="${API_URL}/repos/${REPOSITORY}/issues/${PR_NUMBER}/comments"
+        
+        response=$(curl -s -H "Authorization: Bearer ${GITHUB_TOKEN}" "$comments_url")
+        
+        # Find existing vociferate comment by checking for the marker
+        existing_comment_id=$(printf '%s' "$response" | \
+          jq -r '.[] | select(.body | contains("vociferate-pr-review")) | .id' 2>/dev/null | \
+          head -1 || echo "")
+
+        if [[ -n "$existing_comment_id" ]]; then
+          # Update existing comment
+          update_url="${API_URL}/repos/${REPOSITORY}/issues/comments/${existing_comment_id}"
+          curl -s -X PATCH \
+            -H "Authorization: Bearer ${GITHUB_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "$(printf '{"body": %s}' "$(printf '%s' "$COMMENT_BODY" | jq -Rs .)")" \
+            "$update_url" > /dev/null
+          
+          printf 'comment_id=%s\n' "$existing_comment_id" >> "$GITHUB_OUTPUT"
+          printf 'comment_url=%s/repos/%s/issues/%s#issuecomment-%s\n' \
+            "$SERVER_URL" "$REPOSITORY" "$PR_NUMBER" "$existing_comment_id" >> "$GITHUB_OUTPUT"
+        else
+          # Create new comment
+          create_url="${API_URL}/repos/${REPOSITORY}/issues/${PR_NUMBER}/comments"
+          response=$(curl -s -X POST \
+            -H "Authorization: Bearer ${GITHUB_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "$(printf '{"body": %s}' "$(printf '%s' "$COMMENT_BODY" | jq -Rs .)")" \
+            "$create_url")
+          
+          comment_id=$(printf '%s' "$response" | jq -r '.id' 2>/dev/null)
+          
+          printf 'comment_id=%s\n' "$comment_id" >> "$GITHUB_OUTPUT"
+          printf 'comment_url=%s/repos/%s/issues/%s#issuecomment-%s\n' \
+            "$SERVER_URL" "$REPOSITORY" "$PR_NUMBER" "$comment_id" >> "$GITHUB_OUTPUT"
+        fi
--- a/internal/vociferate/vociferate.go
+++ b/internal/vociferate/vociferate.go
@@ -19,7 +19,7 @@ import (
 const (
 	defaultVersionFile        = "release-version"
 	defaultVersionExpr        = `^\s*([^\r\n]+)\s*$`
-	defaultChangelog          = "changelog.md"
+	defaultChangelog          = "CHANGELOG.md"
 	defaultUnreleasedTemplate = "### Breaking\n\n### Added\n\n### Changed\n\n### Removed\n\n### Fixed\n"
 )

@@ -38,7 +38,7 @@ type Options struct {
 	// When empty, a line-oriented default matcher is used.
 	VersionPattern string
 	// Changelog is the path to the changelog file, relative to the repository
-	// root. When empty, changelog.md is used.
+	// root. When empty, CHANGELOG.md is used.
 	Changelog string
 }

@@ -541,10 +541,10 @@ func addChangelogLinks(text, repoURL, rootDir string) string {
 func displayURL(url string) string {
 	trimmed := strings.TrimSpace(url)
 	if strings.HasPrefix(trimmed, "https://") {
-		return "//" + strings.TrimPrefix(trimmed, "https://")
+		return trimmed
 	}
 	if strings.HasPrefix(trimmed, "http://") {
-		return "//" + strings.TrimPrefix(trimmed, "http://")
+		return "https://" + strings.TrimPrefix(trimmed, "http://")
 	}
 	return trimmed
 }
--- a/internal/vociferate/vociferate_internal_test.go
+++ b/internal/vociferate/vociferate_internal_test.go
@@ -146,3 +146,16 @@ func TestDeriveRepositoryURL_UsesOverrideAsHighestPriority(t *testing.T) {
 		t.Fatalf("unexpected repository URL: %q", url)
 	}
 }
+
+func TestResolveOptions_UsesUppercaseChangelogDefault(t *testing.T) {
+	t.Parallel()
+
+	resolved, err := resolveOptions(Options{})
+	if err != nil {
+		t.Fatalf("resolveOptions returned unexpected error: %v", err)
+	}
+
+	if resolved.Changelog != "CHANGELOG.md" {
+		t.Fatalf("resolved changelog = %q, want %q", resolved.Changelog, "CHANGELOG.md")
+	}
+}
--- a/internal/vociferate/vociferate_test.go
+++ b/internal/vociferate/vociferate_test.go
@@ -41,7 +41,7 @@ func (s *PrepareSuite) SetupTest() {
 	))

 	require.NoError(s.T(), os.WriteFile(
-		filepath.Join(s.rootDir, "changelog.md"),
+		filepath.Join(s.rootDir, "CHANGELOG.md"),
 		[]byte("# Changelog\n\n## [Unreleased]\n\n### Breaking\n\n### Added\n\n- New thing.\n\n### Fixed\n\n- Old thing.\n\n## [1.1.6] - 2017-12-20\n\n### Fixed\n\n- Historical note.\n"),
 		0o644,
 	))
@@ -72,15 +72,15 @@ func (s *PrepareSuite) TestPrepare_UpdatesVersionAndPromotesUnreleasedNotes() {
 	require.NoError(s.T(), err)
 	require.Equal(s.T(), "1.1.7\n", string(versionBytes))

-	changelogBytes, err := os.ReadFile(filepath.Join(s.rootDir, "changelog.md"))
+	changelogBytes, err := os.ReadFile(filepath.Join(s.rootDir, "CHANGELOG.md"))
 	require.NoError(s.T(), err)
 	firstCommit := firstCommitShortHash(s.T(), s.rootDir)
-	require.Equal(s.T(), "# Changelog\n\n## [Unreleased]\n\n### Breaking\n\n### Added\n\n### Changed\n\n### Removed\n\n### Fixed\n\n## [1.1.7] - 2026-03-20\n\n### Breaking\n\n### Added\n\n- New thing.\n\n### Fixed\n\n- Old thing.\n\n## [1.1.6] - 2017-12-20\n\n### Fixed\n\n- Historical note.\n\n[Unreleased]: //git.hrafn.xyz/aether/vociferate/compare/v1.1.7...main\n[1.1.7]: //git.hrafn.xyz/aether/vociferate/compare/v1.1.6...v1.1.7\n[1.1.6]: //git.hrafn.xyz/aether/vociferate/compare/"+firstCommit+"...v1.1.6\n", string(changelogBytes))
+	require.Equal(s.T(), "# Changelog\n\n## [Unreleased]\n\n### Breaking\n\n### Added\n\n### Changed\n\n### Removed\n\n### Fixed\n\n## [1.1.7] - 2026-03-20\n\n### Breaking\n\n### Added\n\n- New thing.\n\n### Fixed\n\n- Old thing.\n\n## [1.1.6] - 2017-12-20\n\n### Fixed\n\n- Historical note.\n\n[Unreleased]: https://git.hrafn.xyz/aether/vociferate/compare/v1.1.7...main\n[1.1.7]: https://git.hrafn.xyz/aether/vociferate/compare/v1.1.6...v1.1.7\n[1.1.6]: https://git.hrafn.xyz/aether/vociferate/compare/"+firstCommit+"...v1.1.6\n", string(changelogBytes))
 }

 func (s *PrepareSuite) TestPrepare_ReturnsErrorWhenUnreleasedSectionMissing() {
 	require.NoError(s.T(), os.WriteFile(
-		filepath.Join(s.rootDir, "changelog.md"),
+		filepath.Join(s.rootDir, "CHANGELOG.md"),
 		[]byte("# Changelog\n\n## [1.1.6] - 2017-12-20\n"),
 		0o644,
 	))
@@ -92,7 +92,7 @@ func (s *PrepareSuite) TestPrepare_ReturnsErrorWhenUnreleasedSectionMissing() {

 func (s *PrepareSuite) TestPrepare_ReturnsErrorWhenUnreleasedSectionIsEmpty() {
 	require.NoError(s.T(), os.WriteFile(
-		filepath.Join(s.rootDir, "changelog.md"),
+		filepath.Join(s.rootDir, "CHANGELOG.md"),
 		[]byte("# Changelog\n\n## [Unreleased]\n\n## [1.1.6] - 2017-12-20\n"),
 		0o644,
 	))
@@ -111,7 +111,7 @@ func (s *PrepareSuite) TestRecommendedTag_UsesMinorBumpWhenBreakingHeadingIsEmpt

 func (s *PrepareSuite) TestRecommendedTag_ReturnsErrorWhenUnreleasedHasOnlyTemplateHeadings() {
 	require.NoError(s.T(), os.WriteFile(
-		filepath.Join(s.rootDir, "changelog.md"),
+		filepath.Join(s.rootDir, "CHANGELOG.md"),
 		[]byte("# Changelog\n\n## [Unreleased]\n\n### Breaking\n\n### Added\n\n### Changed\n\n### Removed\n\n### Fixed\n\n## [1.1.6] - 2017-12-20\n"),
 		0o644,
 	))
@@ -123,7 +123,7 @@ func (s *PrepareSuite) TestRecommendedTag_ReturnsErrorWhenUnreleasedHasOnlyTempl

 func (s *PrepareSuite) TestRecommendedTag_UsesPatchBumpForFixOnlyChanges() {
 	require.NoError(s.T(), os.WriteFile(
-		filepath.Join(s.rootDir, "changelog.md"),
+		filepath.Join(s.rootDir, "CHANGELOG.md"),
 		[]byte("# Changelog\n\n## [Unreleased]\n\n### Fixed\n\n- Patch note.\n\n## [1.1.6] - 2017-12-20\n"),
 		0o644,
 	))
@@ -136,7 +136,7 @@ func (s *PrepareSuite) TestRecommendedTag_UsesPatchBumpForFixOnlyChanges() {

 func (s *PrepareSuite) TestRecommendedTag_UsesMajorBumpWhenRemovedEntriesExist() {
 	require.NoError(s.T(), os.WriteFile(
-		filepath.Join(s.rootDir, "changelog.md"),
+		filepath.Join(s.rootDir, "CHANGELOG.md"),
 		[]byte("# Changelog\n\n## [Unreleased]\n\n### Removed\n\n- Breaking removal.\n\n## [1.1.6] - 2017-12-20\n"),
 		0o644,
 	))
@@ -149,7 +149,7 @@ func (s *PrepareSuite) TestRecommendedTag_UsesMajorBumpWhenRemovedEntriesExist()

 func (s *PrepareSuite) TestRecommendedTag_UsesMajorBumpWhenBreakingEntriesExist() {
 	require.NoError(s.T(), os.WriteFile(
-		filepath.Join(s.rootDir, "changelog.md"),
+		filepath.Join(s.rootDir, "CHANGELOG.md"),
 		[]byte("# Changelog\n\n## [Unreleased]\n\n### Breaking\n\n- Changed API contract.\n\n### Changed\n\n- Updated defaults.\n\n## [1.1.6] - 2017-12-20\n"),
 		0o644,
 	))
@@ -206,7 +206,7 @@ func (s *PrepareSuite) TestRecommendedTag_UsesChangelogVersionWhenNoVersionFileC
 		0o644,
 	))
 	require.NoError(s.T(), os.WriteFile(
-		filepath.Join(s.rootDir, "changelog.md"),
+		filepath.Join(s.rootDir, "CHANGELOG.md"),
 		[]byte("# Changelog\n\n## [Unreleased]\n\n### Fixed\n\n- A fix.\n\n## [3.0.0] - 2026-01-01\n\n### Fixed\n\n- Historical.\n"),
 		0o644,
 	))
@@ -220,7 +220,7 @@ func (s *PrepareSuite) TestRecommendedTag_UsesChangelogVersionWhenNoVersionFileC
 func (s *PrepareSuite) TestRecommendedTag_DefaultsToV1WhenNoPriorReleasesInChangelog() {
 	require.NoError(s.T(), os.Remove(filepath.Join(s.rootDir, "release-version")))
 	require.NoError(s.T(), os.WriteFile(
-		filepath.Join(s.rootDir, "changelog.md"),
+		filepath.Join(s.rootDir, "CHANGELOG.md"),
 		[]byte("# Changelog\n\n## [Unreleased]\n\n### Breaking\n\n### Added\n\n- First feature.\n"),
 		0o644,
 	))
@@ -252,7 +252,7 @@ func (s *PrepareSuite) TestRecommendedTag_UsesCustomVersionFileAndPattern() {
 		0o644,
 	))
 	require.NoError(s.T(), os.WriteFile(
-		filepath.Join(s.rootDir, "changelog.md"),
+		filepath.Join(s.rootDir, "CHANGELOG.md"),
 		[]byte("# Changelog\n\n## [Unreleased]\n\n### Added\n\n- Feature.\n\n## [2.3.4] - 2026-03-10\n"),
 		0o644,
 	))
@@ -273,7 +273,7 @@ func (s *PrepareSuite) TestPrepare_UsesGitHrafnXYZEnvironmentForChangelogLinks()
 	err := vociferate.Prepare(s.rootDir, "1.1.7", "2026-03-20", vociferate.Options{})
 	require.NoError(s.T(), err)

-	changelogBytes, readErr := os.ReadFile(filepath.Join(s.rootDir, "changelog.md"))
+	changelogBytes, readErr := os.ReadFile(filepath.Join(s.rootDir, "CHANGELOG.md"))
 	require.NoError(s.T(), readErr)
 	changelog := string(changelogBytes)
 	firstCommit := firstCommitShortHash(s.T(), s.rootDir)
@@ -283,9 +283,9 @@ func (s *PrepareSuite) TestPrepare_UsesGitHrafnXYZEnvironmentForChangelogLinks()
 	require.Contains(s.T(), changelog, "### Removed\n")
 	require.Contains(s.T(), changelog, "## [1.1.7] - 2026-03-20")
 	require.Contains(s.T(), changelog, "## [1.1.6] - 2017-12-20")
-	require.Contains(s.T(), changelog, "[Unreleased]: //git.hrafn.xyz/aether/vociferate/compare/v1.1.7...main")
-	require.Contains(s.T(), changelog, "[1.1.7]: //git.hrafn.xyz/aether/vociferate/compare/v1.1.6...v1.1.7")
-	require.Contains(s.T(), changelog, "[1.1.6]: //git.hrafn.xyz/aether/vociferate/compare/"+firstCommit+"...v1.1.6")
+	require.Contains(s.T(), changelog, "[Unreleased]: https://git.hrafn.xyz/aether/vociferate/compare/v1.1.7...main")
+	require.Contains(s.T(), changelog, "[1.1.7]: https://git.hrafn.xyz/aether/vociferate/compare/v1.1.6...v1.1.7")
+	require.Contains(s.T(), changelog, "[1.1.6]: https://git.hrafn.xyz/aether/vociferate/compare/"+firstCommit+"...v1.1.6")
 }

 func (s *PrepareSuite) TestPrepare_UsesGitHubEnvironmentForChangelogLinks() {
@@ -295,7 +295,7 @@ func (s *PrepareSuite) TestPrepare_UsesGitHubEnvironmentForChangelogLinks() {
 	err := vociferate.Prepare(s.rootDir, "1.1.7", "2026-03-20", vociferate.Options{})
 	require.NoError(s.T(), err)

-	changelogBytes, readErr := os.ReadFile(filepath.Join(s.rootDir, "changelog.md"))
+	changelogBytes, readErr := os.ReadFile(filepath.Join(s.rootDir, "CHANGELOG.md"))
 	require.NoError(s.T(), readErr)
 	changelog := string(changelogBytes)
 	firstCommit := firstCommitShortHash(s.T(), s.rootDir)
@@ -305,7 +305,7 @@ func (s *PrepareSuite) TestPrepare_UsesGitHubEnvironmentForChangelogLinks() {
 	require.Contains(s.T(), changelog, "### Removed\n")
 	require.Contains(s.T(), changelog, "## [1.1.7] - 2026-03-20")
 	require.Contains(s.T(), changelog, "## [1.1.6] - 2017-12-20")
-	require.Contains(s.T(), changelog, "[Unreleased]: //github.com/aether/vociferate/compare/v1.1.7...main")
-	require.Contains(s.T(), changelog, "[1.1.7]: //github.com/aether/vociferate/compare/v1.1.6...v1.1.7")
-	require.Contains(s.T(), changelog, "[1.1.6]: //github.com/aether/vociferate/compare/"+firstCommit+"...v1.1.6")
+	require.Contains(s.T(), changelog, "[Unreleased]: https://github.com/aether/vociferate/compare/v1.1.7...main")
+	require.Contains(s.T(), changelog, "[1.1.7]: https://github.com/aether/vociferate/compare/v1.1.6...v1.1.7")
+	require.Contains(s.T(), changelog, "[1.1.6]: https://github.com/aether/vociferate/compare/"+firstCommit+"...v1.1.6")
 }
--- a/prepare/action.yml
+++ b/prepare/action.yml
@@ -26,7 +26,7 @@ inputs:
  changelog:
    description: Path to changelog file relative to repository root.
    required: false
-    default: changelog.md
+    default: CHANGELOG.md
  git-user-name:
    description: Name for the release commit author.
    required: false
@@ -38,10 +38,10 @@ inputs:
  git-add-files:
    description: >
      Space-separated list of file paths to stage for the release commit.
-      Defaults to changelog.md and release-version. Adjust when using a
+      Defaults to CHANGELOG.md and release-version. Adjust when using a
      custom version-file.
    required: false
-    default: 'changelog.md release-version'
+    default: 'CHANGELOG.md release-version'

 outputs:
  version:
--- a/publish/action.yml
+++ b/publish/action.yml
@@ -20,7 +20,7 @@ inputs:
  changelog:
    description: Path to changelog file relative to repository root.
    required: false
-    default: changelog.md
+    default: CHANGELOG.md

 outputs:
  release-id:
@@ -67,7 +67,7 @@ runs:
      id: extract-notes
      shell: bash
      env:
-        CHANGELOG: ${{ inputs.changelog != '' && inputs.changelog || 'changelog.md' }}
+        CHANGELOG: ${{ inputs.changelog != '' && inputs.changelog || 'CHANGELOG.md' }}
        RELEASE_VERSION: ${{ steps.resolve-version.outputs.version }}
        RUNNER_TEMP: ${{ runner.temp }}
      run: |
--- a/2
+++ b/2
@@ -1 +1 @@
-0.2.0
+1.0.2
Author	SHA1	Message	Date
gitea-actions[bot]	b5530d0c48	release: prepare v1.0.2	2026-03-21 13:35:24 +00:00
Micheal Wilkinson	b1aaff9f3b	docs: document preflight token checks All checks were successful Push Validation / coverage-badge (push) Successful in 35s Details Push Validation / recommend-release (push) Successful in 14s Details	2026-03-21 13:17:39 +00:00
Micheal Wilkinson	3e03382781	chore(ci): add preflight token and API checks All checks were successful Push Validation / coverage-badge (push) Successful in 50s Details Push Validation / recommend-release (push) Successful in 17s Details	2026-03-21 13:06:15 +00:00
Micheal Wilkinson	43018ae9ac	chore: support both GITHUB_TOKEN and GITEA_TOKEN in do-release workflow All checks were successful Push Validation / coverage-badge (push) Successful in 56s Details Push Validation / recommend-release (push) Successful in 14s Details	2026-03-21 12:57:40 +00:00
Micheal Wilkinson	3e384dd8a3	chore: update decorate-pr action version to v1.0.1 in examples	2026-03-21 12:51:50 +00:00
Micheal Wilkinson	821802c0c4	feat: add decorate-pr composite action for pull request review decoration	2026-03-21 12:51:28 +00:00
Micheal Wilkinson	2810d93b89	docs: add copilot instructions for Æther Go workflow	2026-03-21 12:50:27 +00:00
gitea-actions[bot]	02db91114d	release: prepare v1.0.1	2026-03-21 11:33:08 +00:00
Micheal Wilkinson	c27b042bb1	fix: restore protocol-relative changelog links All checks were successful Push Validation / coverage-badge (push) Successful in 1m44s Details Push Validation / recommend-release (push) Successful in 38s Details	2026-03-21 11:26:31 +00:00
Micheal Wilkinson	59ce683813	docs: remove non-action guardrails from AGENTS.md Some checks failed Push Validation / coverage-badge (push) Failing after 42s Details Push Validation / recommend-release (push) Has been skipped Details	2026-03-21 10:03:42 +00:00
Micheal Wilkinson	d653f632d1	fix: add unreleased changelog entry for https:// protocol change Some checks failed Push Validation / coverage-badge (push) Failing after 43s Details Push Validation / recommend-release (push) Has been skipped Details	2026-03-21 10:00:44 +00:00
Micheal Wilkinson	8e5d05fce6	fix: replace protocol-relative // URLs with explicit https:// Some checks failed Push Validation / coverage-badge (push) Failing after 1m59s Details Push Validation / recommend-release (push) Has been skipped Details	2026-03-21 09:57:53 +00:00
gitea-actions[bot]	5dad65cc3b	release: prepare v1.0.0	2026-03-21 01:13:41 +00:00
Micheal Wilkinson	e99527f68b	docs: refresh README wording and stylization All checks were successful Push Validation / coverage-badge (push) Successful in 1m43s Details Push Validation / recommend-release (push) Successful in 38s Details	2026-03-21 00:48:46 +00:00
Micheal Wilkinson	f314d7da1b	feat: sync docs action tags during prepare	2026-03-21 00:29:14 +00:00
Micheal Wilkinson	21a68647f3	refactor: normalize changelog filename docs	2026-03-21 00:27:32 +00:00
Micheal Wilkinson	ba715d9965	feat: migrate changelog path to CHANGELOG.md	2026-03-21 00:27:18 +00:00
Micheal Wilkinson	62f637614d	test: require CHANGELOG.md defaults	2026-03-21 00:26:43 +00:00
Micheal Wilkinson	7d6ae6f486	docs: pin README examples to release tags	2026-03-21 00:20:08 +00:00
Micheal Wilkinson	16274ea1e5	feat: add reusable coverage-badge action	2026-03-21 00:18:21 +00:00
@@ -1 +1 @@
 .2.0
 .0.2