docs: expand coverage and add optional GH_TOKEN fallback

- Document optional GH_TOKEN secret for auto-release chain (PAT fallback)
- Add JSR_TOKEN setup and first-publish sections to README
- Add npm-publish comparison section
- Add PR process to CONTRIBUTING
- Add issue and PR templates
- Refresh llms.txt/llms-full.txt and package.json keywords

Author: TheCryptoDonkey

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,31 @@
+---
+name: Feature request
+about: Suggest a new gate, input, or capability
+labels: enhancement
+---
+
+**What problem does this solve?**
+
+Describe the scenario where anvil falls short today. Keep it concrete --
+"a library author who X ends up with Y" beats an abstract wish list.
+
+**Proposed shape**
+
+What input, gate, or workflow change would address it? If it's a new
+gate, what does it check and what does it fail on?
+
+**Threat-model fit**
+
+Does this fit within the boundaries in [THREAT-MODEL.md](../../THREAT-MODEL.md)?
+If it expands the trust surface, call that out -- threat-model-expanding
+changes need explicit justification.
+
+**Audit budget impact**
+
+Rough line-count estimate for the addition. The total bash surface area
+is a hard ~1600-line budget (thirty-minute audit target).
+
+**Alternatives considered**
+
+Other tools, workflow patterns, or existing gates that partially cover
+the problem today.

.github/pull_request_template.md

@@ -0,0 +1,24 @@
+<!--
+Thanks for contributing. Keep the description short; link to relevant
+THREAT-MODEL entries if this changes a gate.
+-->
+
+## What
+
+<!-- One or two sentences on what this PR does. -->
+
+## Why
+
+<!-- The motivation. Link to an issue if one exists. -->
+
+## Notes
+
+<!-- Anything a reviewer should know. Delete the checklist lines that
+     don't apply. -->
+
+- [ ] Tests added / updated (`test/*.bats`)
+- [ ] `bats test/*.bats` passes locally
+- [ ] `shellcheck -x steps/*.sh` clean
+- [ ] No new runtime dependencies outside the GitHub Actions runner image
+- [ ] Audit-budget impact acceptable (line-count delta noted if > ~50 lines)
+- [ ] THREAT-MODEL.md updated if this changes a gate boundary

.github/workflows/auto-release.yml

@@ -45,6 +45,15 @@ on:
         description: Determine version and changelog but do not commit, tag, or create a release
         type: string
         default: 'false'
+    secrets:
+      GH_TOKEN:
+        description: |
+          Optional GitHub App token or PAT with contents: write scope.
+          If provided, the push and GitHub Release creation will use this
+          token instead of the default GITHUB_TOKEN. Required if you want
+          the created Release to trigger release.yml automatically --
+          the default GITHUB_TOKEN cannot trigger further workflow runs.
+        required: false
 
 jobs:
   determine:
@@ -106,9 +115,9 @@ jobs:
           fetch-depth: 0
           # Default GITHUB_TOKEN can push but cannot trigger further
           # workflow runs. If the consumer wants the push to trigger
-          # release.yml, they must pass a PAT or GitHub App token via
-          # secrets. See README "Auto mode" section.
-          token: ${{ secrets.GITHUB_TOKEN }}
+          # release.yml, they pass a PAT or GitHub App token via the
+          # GH_TOKEN secret. See README "Auto" version strategy section.
+          token: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
 
       - name: Configure git
         run: |
@@ -202,7 +211,7 @@ jobs:
         env:
           NEXT_VERSION: ${{ needs.determine.outputs.next_version }}
           CHANGELOG: ${{ needs.determine.outputs.changelog }}
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
         run: |
           gh release create "v${NEXT_VERSION}" \
             --title "v${NEXT_VERSION}" \

CONTRIBUTING.md

@@ -11,24 +11,48 @@ holds after the addition.
 Prerequisites: `bash`, `jq`, `npm`, `gh`, `shellcheck`, `bats`.
 
 ```sh
-# Run the full test suite (71 tests)
+# Run the full test suite
 bats test/*.bats
 
 # Lint all step scripts
 shellcheck -x steps/*.sh
 ```
 
+## Pull requests
+
+1. Branch from `main`. Name the branch `type/short-description`
+   (e.g. `fix/verify-exports-windows`, `feat/gate-for-banned-licences`).
+2. Write a bats test first when adding or changing gate behaviour.
+   Every step script has a matching `test/<name>.bats` fixture.
+3. Commit style: `type: description` (lowercase, imperative). No
+   `Co-Authored-By`. Examples: `fix: handle empty exports map`,
+   `docs: clarify JSR_TOKEN scope`.
+4. Run `bats test/*.bats` and `shellcheck -x steps/*.sh` locally
+   before pushing. CI runs the same checks.
+5. Open the PR against `main`. Keep the description short -- link to
+   the relevant THREAT-MODEL entry if the change affects a gate, and
+   mention the line-count delta if the change is non-trivial (the
+   thirty-minute audit budget is a hard constraint).
+6. A solo maintainer reviews and merges. Expect feedback within a day
+   or two; longer for design-impacting changes.
+
+## Proposing larger changes
+
+For anything that adds a new gate, changes a trust boundary, or grows
+the line count by more than ~50 lines, open an issue first with the
+proposed design. The audit budget means every addition has to earn
+its place; discussing the shape before writing the code saves everyone
+time.
+
 ## Non-goals
 
 - Automated commit analysis or semver determination from commit messages
+  as a release-blocking step (the `auto-release.yml` companion workflow
+  handles this outside the gate pipeline)
 - Changelog generation as a release-blocking step
 - Node-based tooling inside the action itself
 - Dependencies that are not already on the default GitHub Actions runner image
 
-## Commit style
-
-`type: description` (lowercase, imperative). No `Co-Authored-By`.
-
 ## Reporting vulnerabilities
 
 Security issues should be reported via GitHub Security Advisories at

README.md

@@ -167,8 +167,20 @@ when warranted. Zero dependencies, zero config files.
 
 **Note:** The default `GITHUB_TOKEN` can create releases but cannot
 trigger further workflow runs. If you need the auto-created release to
-trigger `release.yml` automatically, use a GitHub App token or PAT
-with `contents: write` scope.
+trigger `release.yml` automatically, pass a GitHub App token or PAT
+with `contents: write` scope via the `GH_TOKEN` secret:
+
+```yaml
+jobs:
+  auto-release:
+    uses: forgesworn/anvil/.github/workflows/auto-release.yml@v0
+    secrets:
+      GH_TOKEN: ${{ secrets.RELEASE_PAT }}
+```
+
+Store the PAT as a repo secret (e.g. `RELEASE_PAT`). Without this,
+the created Release still appears in GitHub but won't trigger
+`release.yml`.
 
 ## What the action does
 
@@ -268,7 +280,7 @@ no reproducibility check). Use the reusable workflow as the default.
 | `audit-level` | `low` | `npm audit` severity floor |
 | `version-strategy` | `manual` | One of `manual`, `verify`. `manual` is the default: you bump, you tag, the action publishes. `verify` parses conventional commits and fails if your bump is smaller than what the commits imply. For fully automatic versioning, use the companion `auto-release.yml` workflow instead. |
 | `strict-action-pins` | `true` | If `true` (the default), **verify-action-pins** fails the release on any unpinned `uses:` reference in `.github/workflows`. Set to `false` for warn-only mode. `forgesworn/anvil` is exempt by name. |
-| `reproducibility-mode` | `strict` | One of `strict`, `warn`, `off`. `strict` blocks the release if the two parallel builds produce different sha256s. `warn` logs the mismatch but publishes. `off` skips the second build entirely (v0.3 single-runner behaviour). |
+| `reproducibility-mode` | `strict` | Reusable workflow only. One of `strict`, `warn`, `off`. `strict` blocks the release if the two parallel builds produce different sha256s. `warn` logs the mismatch but publishes. `off` skips the second build entirely (v0.3 single-runner behaviour). The composite action silently ignores this input (it cannot run the two-build DAG; see "Advanced: composite action directly"). |
 | `dry-run` | `false` | Skip real publish (for smoke-testing) |
 | `debug` | `false` | If `true`, run a diagnostic step before publish that dumps npm version, redacted `.npmrc`, OIDC env vars, and `npm config list`. Flip this on when debugging trusted-publisher errors -- see "Trusted publisher caveat". Does not print token values. |
 
@@ -277,6 +289,33 @@ no reproducibility check). Use the reusable workflow as the default.
 | Secret | When needed |
 |---|---|
 | `JSR_TOKEN` | Only if `jsr.json` exists. JSR does not yet support OIDC. |
+| `GH_TOKEN` | Only for `auto-release.yml` when you want the auto-created Release to trigger `release.yml`. See "Version strategy -> Auto". |
+
+### JSR_TOKEN setup
+
+If your package publishes to JSR alongside npm, add a `jsr.json` in the
+repo root and provide a `JSR_TOKEN` secret.
+
+1. Generate the token at [jsr.io/account/tokens](https://jsr.io/account/tokens).
+   Choose **Personal access token** with the `publish` scope for the
+   specific package (or `publish` on the whole org). Short-lived tokens
+   are preferred -- rotate whenever convenient.
+2. Add the token as a repo secret named `JSR_TOKEN` under
+   Settings -> Secrets and variables -> Actions.
+3. Pass it through from your caller workflow:
+
+```yaml
+jobs:
+  release:
+    uses: forgesworn/anvil/.github/workflows/release.yml@v0
+    secrets:
+      JSR_TOKEN: ${{ secrets.JSR_TOKEN }}
+```
+
+JSR does not yet support OIDC trusted publishing; the token is the
+only authentication path today. The action skips JSR publish entirely
+when `jsr.json` is absent, so existing npm-only consumers are
+unaffected.
 
 ## CHANGELOG format
 
@@ -420,6 +459,23 @@ Configure on npmjs.com → your package → Settings → Trusted Publisher:
 | Workflow filename | **your caller workflow file** (e.g. `release.yml`) |
 | Environment | (leave empty) |
 
+### First publish of a new package
+
+npm's trusted publisher flow requires the package to already exist on
+the registry. For a brand-new package that has never been published,
+do a one-time manual publish first:
+
+```sh
+# From your workstation, with a granular access token scoped to publish
+npm publish --access public
+```
+
+Then configure trusted publishing on npmjs.com for all subsequent
+releases. The manual token can be revoked after the first publish --
+from that point on, OIDC handles everything.
+
+### Why the caller-workflow trust model
+
 The reusable workflow still gets you centralised gate logic -- one place
 to update tag-match, secret scan, exports sanity, frozen-vector check,
 runtime audit, etc., across every consumer. That's the real benefit.

docs/comparison.md

@@ -206,6 +206,67 @@ If you prefer the interactive local workflow, np is the right tool.
 
 ---
 
+### vs JS-DevTools/npm-publish (666 stars, GitHub Action)
+
+JS-DevTools/npm-publish is the dominant "just publish" action. It
+detects version bumps in package.json, runs npm publish, and exits.
+v4 supports OIDC trusted publishing. No gates beyond tag/version
+detection. Node-based.
+
+**What JS-DevTools/npm-publish does better:**
+- Battle-tested (666 stars, widely used)
+- Simpler mental model when all you want is publish
+- Handles the version-detection heuristic well
+
+**What anvil does better:**
+- Pre-publish gates: secret scan, exports check, frozen vectors,
+  runtime audit, action-pin audit (JS-DevTools offers none of these)
+- Reproducible-build attestation (two-runner)
+- SLSA provenance required by default, not opt-in
+- Pure bash vs Node runtime (smaller attack surface)
+- Tarball integrity stamped into Release body + uploaded as asset
+
+**The philosophy gap:**
+JS-DevTools/npm-publish publishes. anvil publishes safely.
+If the only bar is "get bytes onto the registry with OIDC",
+JS-DevTools/npm-publish is fine. If the bar includes "no accidental
+secret leak, no broken exports, no silent non-determinism,
+no compromised third-party action in your pipeline", anvil is
+the deliberate upgrade.
+
+**Who should switch:**
+Authors who adopted JS-DevTools/npm-publish for its simplicity but
+now want supply-chain guarantees on top of OIDC.
+
+**Migration effort:** Minimal. Swap the caller workflow;
+OIDC trusted publisher config carries over unchanged.
+
+---
+
+### vs pascalgn/npm-publish-action (227 stars, GitHub Action)
+
+pascalgn/npm-publish-action is a simpler "auto-detect version,
+publish" action. No OIDC support last time checked; relies on
+long-lived NPM_TOKEN. No gates.
+
+**What pascalgn does better:**
+- Nothing relevant to the anvil user profile.
+
+**What anvil does better:**
+- OIDC vs stored NPM_TOKEN (the attack vector this tool predates)
+- All pre-publish gates
+- Reproducible builds, provenance, integrity stamping
+
+**Who should switch:**
+Anyone using pascalgn/npm-publish-action who hasn't yet migrated
+off long-lived NPM_TOKEN. The security gap vs modern tooling is
+significant.
+
+**Migration effort:** Minimal on the action side; revoke NPM_TOKEN
+and configure trusted publishing on npmjs.com.
+
+---
+
 ## Feature matrix: supply-chain hardening
 
 This is where anvil's differentiation is clearest.