docs: contributor and agent guidance, and a precommit alias

[jhgaylor]

This library graduated out of the Fountain umbrella with the template's CI, release gate and publish workflow — and none of the guidance that surrounded it there. Somebody arriving at this repository, a contributor or a coding agent, got the README's contract and nothing about how to work in the tree: which checks gate a PR, what the test helper sets up and why, how a release happens, and which traps this library in particular has.

What this adds

File	What it carries
CLAUDE.md	Read by Claude Code and other agents when a session starts here. The gate; the coverage threshold and why it is that number; this library's test patterns, including what test/test_helper.exs sets up and why; the release flow; and the things not to do, with the traps specific to this library.
AGENTS.md	A pointer to CLAUDE.md, for agents that look for that filename instead.
CONTRIBUTING.md	Apache-2.0 inbound and outbound, the DCO sign-off, what to run before pushing, and when a change needs a version bump.
mix.exs	A precommit alias.

CLAUDE.md defers to README.md rather than restating it: the README stays the normative description of what the library does, and CLAUDE.md covers working in the repository.

mix precommit

Runs what .github/workflows/ci.yml runs, in the same order: the unused-dependency check, format --check-formatted, compile --warnings-as-errors, credo --strict, dialyzer, test --cover, hex.build. Until now the only way to run the gate locally was to reproduce seven steps out of the workflow by hand, including two environment overrides that are easy to miss.

Four details worth a reviewer's eye:

• def cli sets preferred_envs: [precommit: :test], matching CI's job-level MIX_ENV: test.
• dialyzer and hex.build shell out with MIX_ENV=dev — the same two overrides CI makes, for the same reason: dialyzer analyses the shipped code, and the test env would pull test-only deps into the analysis and into the cached PLT.
• The unused-dependency step compares mix.lock before and after rather than trusting the task's exit code. mix deps.unlock --unused rewrites the lockfile and exits 0, so the naive version passes while CI fails the same commit on its git diff --exit-code mix.lock.
• hex.build writes its tarball to a temp directory. It is a check, not an artifact, and nothing should have to gitignore it.

Verified end to end on managoat_sandbox: 236 tests, 0 failures, coverage gate met, package built, exit 0.

Why the no-release label

Nothing here changes what the package ships. scripts/release.exs compares mix.exs textually — consumer_facing/1 strips comments and only: :dev/:test dependency lines, but not an aliases block — so a build-tooling alias reads to the gate as a consumer-facing change. This is the documented exception the label exists for.

Notes

One of a set of PRs across all nine managoat_* libraries. The structure is shared; the per-library content in CLAUDE.md (coverage rationale, test patterns, traps) is written per repository.

templates/managoat-library in Fountain is deliberately not updated in this pass, so a future graduation will not inherit this yet — worth a follow-up.

Separately: the no-release label did not exist in any of the nine repositories, although scripts/graduate-library.sh step 5 creates it as part of graduation. It has been created here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Yas72zcnw8CTpxSadda9a9