docs: add conventional commit guidelines after learning the hard way

Documented commit type reference and common mistakes to prevent
future accidental releases from misusing fix: instead of test:/chore:.

Author: 27Bslash6

CLAUDE.md

@@ -0,0 +1,59 @@
+# cachekit-core
+
+Standalone Rust crate for compression, checksums, and encryption.
+
+**Status**: Published to crates.io (v0.1.0)
+
+## Conventional Commits (IMPORTANT - READ THIS)
+
+**THIS PROJECT USES RELEASE-PLEASE** - Commit types matter. Get them wrong, and you'll trigger accidental releases or hide important changes.
+
+### Commit Type Reference
+
+| Type | Triggers Release? | Use When | Examples |
+|------|------------------|----------|----------|
+| `feat:` | ✅ YES | New user-facing functionality | New API method, new feature flag |
+| `fix:` | ✅ YES | User-facing bug fixes | Crash fix, incorrect behavior fix |
+| `perf:` | ✅ YES | Performance improvements | Algorithm optimization, reduced allocations |
+| `security:` | ✅ YES | Security fixes | CVE patch, timing attack mitigation |
+| `revert:` | ✅ YES | Reverting previous changes | Revert previous commit |
+| `docs:` | ❌ NO | Documentation only | README updates, doc comments |
+| `test:` | ❌ NO | Test-only changes | New tests, test fixes, test refactoring |
+| `chore:` | ❌ NO | Build/CI/tooling changes | Workflow updates, dependency bumps |
+| `refactor:` | ❌ NO | Code refactoring (no behavior change) | Internal restructuring |
+| `ci:` | ❌ NO | CI/CD changes | GitHub Actions, workflow config |
+| `build:` | ❌ NO | Build system changes | Cargo.toml metadata, build scripts |
+
+### Common Mistakes (LEARNED THE HARD WAY - 2025-12-09)
+
+❌ **WRONG**: `fix: use CodeQL autobuild to capture Rust-generated C FFI`
+- This is a CI workflow change, not a user-facing bug fix
+- Would trigger patch release for no reason
+
+✅ **CORRECT**: `chore: use CodeQL autobuild to capture Rust-generated C FFI`
+
+❌ **WRONG**: `fix: improve timing test robustness for CI environments`
+- Test-only change, no user impact
+- Would show up in release notes as a "bug fix"
+
+✅ **CORRECT**: `test: improve timing test robustness for CI environments`
+
+### Decision Framework
+
+Ask yourself:
+1. **Does this change user-facing behavior?** → `feat:` or `fix:`
+2. **Is this a security issue?** → `security:`
+3. **Does this only affect tests?** → `test:`
+4. **Does this only affect CI/build/tooling?** → `chore:` or `ci:`
+5. **Is this internal refactoring?** → `refactor:`
+
+**When in doubt**: Use a non-releasing type (`chore:`, `test:`, `ci:`). You can always re-release later if needed.
+
+## Release Process
+
+- Release-please runs on every push to `main`
+- Analyzes conventional commits since last release
+- Creates/updates release PR with auto-generated CHANGELOG
+- On PR merge, publishes to crates.io automatically
+
+**Manifest sync**: `.release-please-manifest.json` is auto-updated by release-please. If it gets out of sync (manual publish), update it manually to match Cargo.toml version.