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 both versions — Cargo.toml version and the root Omarchy manifest.json version must match the release tag.
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 test now also enforces this without git: a guard test fails if any changelog entry appears under two versions, or if one section repeats a category heading. The manual comparison above stays because it is stronger for the newest section — the guard cannot tell a reworded entry from a new one — but the automated check is what catches a conflict resolution that quietly copies an entry into a published section, which is how it happened the third time.

     The cause is the same every time: a branch that predates the last tag carries its entries under [Unreleased], and git merges them cleanly into whatever now sits at that position — which is the section you just published. It happened to v1.6.0 (#127), to v1.8.0 (#129), and to v1.11.0 when a maintainer resolved #152's conflict with a script. A clean merge is not evidence here; the comparison is, and now the guard is too.

3. Bump packaging/aur/PKGBUILD — pkgver=X.Y.Z, pkgrel=1, reset sha256sums to 'SKIP'.
4. Bump packaging/aur/PKGBUILD-bin — same pkgver, pkgrel=1, reset both sha256sums_x86_64 and sha256sums_aarch64 to 'SKIP'.
5. Regenerate both .SRCINFOs NOW, before tagging — the release workflow's verify-version job rejects the tag if packaging/aur/.SRCINFO or .SRCINFO-bin still carry the old pkgver (learned at v0.17.0, which never shipped for exactly this reason):

   cd packaging/aur && makepkg --printsrcinfo > .SRCINFO
   # PKGBUILD-bin must be named PKGBUILD for makepkg — use a scratch dir:
   t=$(mktemp -d) && cp PKGBUILD-bin "$t/PKGBUILD" &&
     (cd "$t" && makepkg --printsrcinfo > .SRCINFO-bin) &&
     cp "$t/.SRCINFO-bin" .SRCINFO-bin && rm -rf "$t"
   

   The committed files keep sha256sums = SKIP; CI pins the real hashes later.
6. Run gate before tagging:

   make test                                   # cargo test + the desktop JS gate
   cargo clippy --all-targets -- -D warnings   # clean
   cargo machete                               # no unused deps
   omarchy plugin validate .                   # plugin manifest + entry points
   

   make test rather than cargo test: it also runs the GNOME, KDE, and Omarchy frontend contract suites. If kde-plasmoid/ changed, also bump KPlugin.Version in kde-plasmoid/package/metadata.json; it is versioned independently of Cargo.toml, like the GNOME metadata.json.
7. Commit, tag, push:

   git commit -m "vX.Y.Z — …"
   git tag -a vX.Y.Z -m "vX.Y.Z — …"
   git push origin main && git push origin vX.Y.Z
   

8. Wait for CI (3–5 min): the tag push auto-triggers .github/workflows/release.yml which builds both x86_64 and aarch64 tarballs and publishes a GitHub Release.
9. AUR push is automated via CI when AUR_SSH_KEY is set (since v0.4.4). The publish-aur job in .github/workflows/release.yml runs after build + release succeed, pins the real sha256s into both PKGBUILDs (steps 3-4's 'SKIP's), regenerates the .SRCINFOs, and pushes via KSXGitHub/github-actions-deploy-aur. The manual fallback below is for when the secret isn't configured or CI is unavailable.