ai-usagebar: Instructions file for Claude Code

CLAUDE.md

Notes for Claude Code (and humans) about working in this repo. Keep tight: these are invariants we keep almost-forgetting, not a project tour.

Release checklist — must do all of these

When cutting a new version (patch, minor, or major):

1. Bump all version surfaces — Cargo.toml version, the root Omarchy manifest.json version, and packaging/scoop/ai-usagebar.json version must match the release tag. The Scoop manifest's URL/hash keep the previous release's values in-tree; publish-scoop rewrites them from the published sidecar at release time (verify-version only gates version — v1.20.0 never shipped because the bump missed this file).
2. Update CHANGELOG.md:

   • Add a new ## [X.Y.Z] — YYYY-MM-DD section above the previous one.

   • Categorize entries by Added / Changed / Fixed / Security (Keep-A-Changelog).

   • Update the [Unreleased] compare link and add a new release link at the bottom.

   • Prove no published section moved, before tagging. Compare the newest released section against its own tag, byte for byte:

     prev=$(git describe --tags --abbrev=0)
     diff <(git show "$prev:CHANGELOG.md" | sed -n "/^## \[${prev#v}\]/,/^## \[/p") \
          <(sed -n "/^## \[${prev#v}\]/,/^## \[/p" CHANGELOG.md)
     

     Any output means the released section changed. It must compare, not grep for removals. The first version of this check greped ^- and therefore only caught a rewritten entry; #129 branched before v1.8.0 and its [Unreleased] bullet merged in as a pure insertion, adding a feature to a shipped release with no removed line for the grep to find. It passed clean while the section was wrong.

     make changelog-check now does this comparison for you — it diffs every released section against its own tag and refuses a version file that moved backwards, which is the other half of the same hazard (four branches once came back reading 1.12.0 after v1.13.0 shipped). Run it instead of composing the diff by hand; the manual form below is kept because it documents what the script checks.