Chore: Refresh and cleanups

.github/dependabot.yml

@@ -0,0 +1,25 @@
+# see: https://docs.github.com/code-security/dependabot/dependabot-version-updates
+version: 2
+
+updates:
+  - package-ecosystem: cargo
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    # workspace crates share dependencies - one PR per batch keeps CI runs and
+    # changelog noise down. commit messages match this repo's convention:
+    # workspace-level changes carry no crate-name prefix
+    groups:
+      cargo-dependencies:
+        patterns:
+          - "*"
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      github-actions:
+        patterns:
+          - "*"

.github/workflows/ci.yaml

@@ -6,10 +6,7 @@ on:
       - '**'
     tags-ignore:
       - '**'
-    paths:
-      - ".github/workflows/**.yml"
-      - "**/Cargo.toml"
-      - "**.rs"
+  pull_request:
   workflow_dispatch:
 
 jobs:
@@ -20,7 +17,7 @@ jobs:
       tags: ${{ steps.info.outputs.tags }}
     steps:
       - name: Checkout Source Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
         with:
           fetch-tags: true
       - name: Set Info

.github/workflows/publish.yaml

@@ -15,11 +15,19 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Source Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
         with:
           fetch-tags: true
       - name: Install Rust Toolchain (stable)
         uses: dtolnay/rust-toolchain@stable
+      # NOTE: publishing needs none of these, but `cargo xtask setup` installs
+      # them and `cargo install` always builds from source. fetching the
+      # prebuilt binaries makes `setup` below a no-op instead - see the same
+      # step in `test.yaml` for details
+      - name: Install Prebuilt Tooling
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-llvm-cov,cargo-deny,cargo-semver-checks,typos
       - name: Setup Project
         run: cargo xtask setup
       - name: Publish to Crates.io

.github/workflows/test.yaml

@@ -11,22 +11,80 @@ jobs:
     strategy:
       # fail-fast: false
       matrix:
-        os:
-          - ubuntu-latest
-          - macos-latest
-          - windows-latest
-        architecture:
-          - x64
+        include:
+          - os: ubuntu-latest
+            architecture: x64
+          - os: macos-latest
+            architecture: arm64
+          - os: windows-latest
+            architecture: x64
     steps:
       - name: Git Symlink Setup for Windows
         if: matrix.os == 'windows-latest'
         run: git config --global core.symlinks true
       - name: Checkout Source Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
       - name: Install Rust Toolchain (stable)
         uses: dtolnay/rust-toolchain@stable
+      # NOTE: `cargo install` always builds from source - crates.io ships no
+      # binaries. these tools publish prebuilt binaries via GitHub Releases,
+      # which this action fetches in seconds rather than minutes. installing
+      # them here makes the `setup` step below a no-op, since it skips any
+      # tool that is already available
+      # NOTE: these are `install-action` tool names, not crate names - they
+      # match one-to-one here except `typos`, whose crate is `typos-cli` (the
+      # name `cargo xtask setup` installs) and whose binary is `typos`
+      # NOTE: `cargo-semver-checks` is listed even though no job here runs it -
+      # `setup` installs it for `crate:release`, and fetching the prebuilt
+      # binary is far cheaper than letting `setup` build it from source
+      - name: Install Prebuilt Tooling
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-llvm-cov,cargo-deny,cargo-semver-checks,typos
       - name: Setup Project
         run: cargo xtask setup
       - name: Run Tests & Coverage
         run: cargo xtask ci
 
+  deny:
+    name: Audit Dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout Source Code
+        uses: actions/checkout@v7
+      - name: Install Rust Toolchain (stable)
+        uses: dtolnay/rust-toolchain@stable
+      - name: Install cargo-deny
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-deny
+      - name: Check Advisories, Licenses & Bans
+        run: cargo deny --all-features check
+
+  msrv:
+    name: Verify Minimum Supported Rust Version
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout Source Code
+        uses: actions/checkout@v7
+      - name: Read MSRV from Cargo.toml
+        id: msrv
+        run: |
+          version="$(grep -m1 '^rust-version' Cargo.toml | sed -E 's/.*"([^"]+)".*/\1/')"
+          echo ":::: MSRV: ${version}"
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+      - name: Install Rust Toolchain (MSRV)
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ steps.msrv.outputs.version }}
+      - name: Check Workspace Builds on MSRV
+        # NOTE: `rust-toolchain.toml` pins `stable`, which takes precedence over
+        # the toolchain installed above - `RUSTUP_TOOLCHAIN` overrides both, so
+        # without it this job would silently verify the wrong toolchain
+        env:
+          RUSTUP_TOOLCHAIN: ${{ steps.msrv.outputs.version }}
+        run: |
+          rustc --version
+          cargo check --workspace --all-features --all-targets

.gitignore

@@ -3,9 +3,9 @@
 debug/
 target/
 
-# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
-# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
-Cargo.lock
+# NOTE: `Cargo.lock` is intentionally committed. current guidance is to commit
+# it for *all* projects - libraries included - so CI builds are reproducible
+# see: https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
 
 # These are backup files generated by rustfmt
 **/*.rs.bk

AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS.md
+
+Instructions for AI coding agents working on this repository. **Read [README.md](README.md) first** — it covers setup, conventions, and the full command list, and takes precedence if this document conflicts with it.
+
+## Hard rules — require explicit approval
+
+- **Never** run `cargo add`. Ask; the user must say yes explicitly. Do not infer approval from a request to implement a feature that needs a dependency.
+- **Never** `git commit`. Make changes locally, then prompt the user to review and commit.
+- **Never** `git push`. Prompt the user, and explain why the push is needed.
+- **Never** publish a crate. See "[How to publish crates](README.md#develop-publish-crate)".
+
+## Commands
+
+All local dev commands are `xtask` scripts — run `cargo xtask help` for the full list.
+
+- `cargo xtask test` — fast inner loop while iterating.
+- `cargo xtask ci` — run before prompting the user to review. Chains `format --check`, `spellcheck`, `lint` (clippy), `doc --check` (doc tests + rustdoc warnings), and `coverage` (which runs the tests). Report results honestly.
+- `cargo xtask audit` — dependency audit (advisories, licenses, sources). Needs network access and runs as its own CI job, so it is **not** part of `cargo xtask ci`.
+- `cargo xtask semver` — checks the public API against the last published version. Versions are bumped at release time, not alongside the code, so breaking changes legitimately sit on `main` un-bumped — this must **not** gate CI. `crate:release` runs it automatically before prompting for the new version.
+
+Task naming follows one rule: `--check` is a non-mutating mode of a task that otherwise writes (`format`, `doc`); `name:sub` is a family of distinct operations on one noun (`crate:add`, `crate:list`, ...); everything else is a bare verb.
+- `cargo xtask crate:add` — the only supported way to add a crate. Never hand-create one under `crates/`.
+
+## Conventions
+
+- **Toolchain is pinned** to Rust 1.86 (`rust-toolchain.toml`, `Cargo.toml`). CI verifies this MSRV — don't use newer language or std features.
+- **Commit messages** are `[<crate name>] <message>` (e.g. `[node-js-release-info] update docs`) and crate changes are staged separately from workspace changes. This drives automated changelogs. Workspace-level changes (including `xtask`) get no prefix.
+- **Don't hand-edit** the crate list in `README.md` — it's generated between the `<!-- crate-list-start -->` / `<!-- crate-list-end -->` markers.
+- **Document public interfaces** with inline rustdoc annotations.
+- **TODO comments** are formatted `// TODO (<name>): <message>`.

CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+The instructions live in [AGENTS.md](AGENTS.md) — shared by every AI coding agent used here — and are imported below so they load automatically.
+
+@AGENTS.md