docs: polish README naming section formatting

README.md

@@ -1,6 +1,118 @@
 # vociferate
 
-A reusable release preparation tool for Go repositories.
+`vociferate` is a release orchestration tool written in Go for repositories that
+want changelog-driven versioning, automated release preparation, and repeatable
+tag publication.
+
+It started as release preparation glue, but it now covers the full release path:
+recommend the next semantic version, promote `Unreleased` changelog entries,
+commit and tag a release, and publish release notes/assets from the tagged
+revision.
+
+## Reuse In Other Repositories
+
+Vociferate ships two composite actions that together cover the full release flow.
+Pin both to the same released tag.
+
+### `prepare` — update files, commit, and push tag
+
+```yaml
+name: Prepare Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Optional semantic version override.
+        required: false
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Resolve cache token
+        id: cache-token
+        run: echo "value=${GITHUB_SHA}" >> "$GITHUB_OUTPUT"
+
+      - uses: git.hrafn.xyz/aether/vociferate/prepare@v1.0.0
+        env:
+          VOCIFERATE_CACHE_TOKEN: ${{ steps.cache-token.outputs.value }}
+        with:
+          version: ${{ inputs.version }}
+```
+
+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.
+
+For repositories that embed the version inside source code, pass `version-file`
+and `version-pattern`:
+
+```yaml
+- uses: git.hrafn.xyz/aether/vociferate/prepare@v1.0.0
+  env:
+    VOCIFERATE_CACHE_TOKEN: ${{ github.sha }}
+  with:
+    version-file: internal/myapp/version/version.go
+    version-pattern: 'const Version = "([^"]+)"'
+    git-add-files: changelog.md internal/myapp/version/version.go
+```
+
+`prepare` uses `github.token` internally for authenticated fetch/push operations,
+so no token input is required.
+
+### `publish` — create release with changelog notes
+
+```yaml
+name: Do Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: git.hrafn.xyz/aether/vociferate/publish@v1.0.0
+```
+
+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 `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@v1.0.0
+
+- name: Upload my binary
+  run: |
+    curl --fail-with-body -X POST \
+      -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
+      -H "Content-Type: application/octet-stream" \
+      "${{ github.api_url }}/repos/${{ github.repository }}/releases/${{ steps.publish.outputs.release-id }}/assets?name=myapp" \
+      --data-binary "@dist/myapp"
+```
+
+## Why The Name
+
+> **vociferate** _(verb)_: to cry out loudly or forcefully.
+
+Long story short: vociferating into the Æther is synonymous screaming into the
+void.
+
+If updating changelogs and documenting releases has ever felt like that, this
+tool is for you.
 
 ## Build
 
@@ -78,93 +190,3 @@ The tag-driven `Do Release` workflow publishes prebuilt `vociferate` binaries fo
 
 It also uploads `checksums.txt` for integrity verification.
 If a release already exists for the same tag, the workflow updates its release notes and replaces matching asset filenames so reruns stay in sync.
-
-## Reuse In Other Repositories
-
-Vociferate ships two composite actions that together cover the full release flow.
-Pin both to the same released tag.
-
-### `prepare` — update files, commit, and push tag
-
-```yaml
-name: Prepare Release
-
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: Optional semantic version override.
-        required: false
-
-jobs:
-  prepare:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: git.hrafn.xyz/aether/vociferate/prepare@v1.0.0
-        with:
-          version: ${{ inputs.version }}
-          token: ${{ secrets.GITHUB_TOKEN }}
-```
-
-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.
-
-For repositories that embed the version inside source code, pass `version-file`
-and `version-pattern`:
-
-```yaml
-- uses: git.hrafn.xyz/aether/vociferate/prepare@v1.0.0
-  with:
-    version-file: internal/myapp/version/version.go
-    version-pattern: 'const Version = "([^"]+)"'
-    git-add-files: changelog.md internal/myapp/version/version.go
-    token: ${{ secrets.GITHUB_TOKEN }}
-```
-
-### `publish` — create release with changelog notes
-
-```yaml
-name: Do Release
-
-on:
-  push:
-    tags:
-      - "v*.*.*"
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: git.hrafn.xyz/aether/vociferate/publish@v1.0.0
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-```
-
-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 `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@v1.0.0
-  with:
-    token: ${{ secrets.GITHUB_TOKEN }}
-
-- name: Upload my binary
-  run: |
-    curl --fail-with-body -X POST \
-      -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
-      -H "Content-Type: application/octet-stream" \
-      "${{ github.api_url }}/repos/${{ github.repository }}/releases/${{ steps.publish.outputs.release-id }}/assets?name=myapp" \
-      --data-binary "@dist/myapp"
-```