ck: Instructions file for Claude Code

Claude Development Guide

This file contains project-specific instructions for Claude and other AI agents working on the ck codebase. Whenever you actually use ck and it does something unexpected, jot it down in a file could UNEXPECTED.md - supply what you ran, what you expected to happen, what happened instead.

Release Process

Version Tagging Convention

IMPORTANT: Tags follow the format X.Y.Z (NO v prefix) to match current standard:

# Correct format (current standard since 0.3.8+)
git tag 0.4.1
git tag 0.3.9

# Old format (deprecated, do not use)
git tag v0.3.4

Always check existing tags first: git tag --sort=-version:refname

Pre-Commit Quality Checks

ALWAYS run these commands in order before any commit:

1. Linting: cargo clippy - Fix all warnings
2. Formatting: cargo fmt - Format all code
3. Testing: cargo test - Ensure all tests pass

Version Bump Process

All eight crates ship in lockstep. To bump from OLD to NEW:

1. Workspace Cargo.toml — update two places:
   • [workspace.package] version = "NEW"
   • The seven ck-* = { path = "...", version = "NEW", ... } lines under [workspace.dependencies]
2. Update CHANGELOG.md with release notes (format below)
3. Tag as X.Y.Z (no v prefix) — release.yml does the rest

That's it. Individual crate Cargo.toml files inherit the workspace version via version.workspace = true and depend on siblings via { workspace = true }.

You do NOT need to bump package.json. The publish-npm job in release.yml reads Cargo.toml's [workspace.package] version at publish time and stamps package.json to match before npm publish. The committed package.json version is informational — only the tag + Cargo.toml are the gate.

What release.yml does on tag push

When tag X.Y.Z is pushed:

1. Create GitHub release (draft) and verify tag matches Cargo.toml
2. Build binaries for 5 targets (linux x86_64, macos x86_64+arm64, windows x86_64+arm64), upload as .tar.gz/.zip assets
3. Publish 8 crates to crates.io in dep order, with retry-on-"already-published" and verify-via-API (User-Agent required)
4. Publish to npm as @beaconbay/ck-search — uses npm Trusted Publishing (OIDC); GitHub mints a short-lived id-token, npm validates it against the trusted-publisher config on the package, no long-lived secret. Tarball is published with SLSA provenance attestation (cryptographically tied to this workflow run + commit). The package's postinstall script downloads the platform binary from the GitHub release at user install time.
5. Finalize GitHub release (out of draft)