Add agent context docs (CLAUDE.md, AGENT-USAGE.md) and context-generation guide

[kpgalligan]

What this adds

Documentation aimed at AI coding agents (Claude Code and similar) working in or with this repo — and a guide for the team on producing the same docs in other repos. No source or build changes; 12 new markdown files.

Root CLAUDE.md

Orientation for an agent landing in the repo: what Kermit is, a table of all 9 gradle modules with the dependency chain, build/test commands and their gotchas (ktlint gate, binary-compat apiDump requirement, publish-to-mavenLocal before building samples), and our KMP code guidance:

• prefer interfaces over expect/actual classes wherever possible
• use expect/actual factory functions for defaults, structured so explicit configuration always remains possible

Per-module CLAUDE.md (9 files)

Detailed editing context for each module: key files with real API signatures, source-set / expect-actual structure, and the non-obvious constraints an agent (or new team member) would otherwise trip over — e.g. kermit-io's IO-error recovery behavior that must be preserved, the os_log.def cinterop constraints in kermit-core, kermit-simple's manual nonKotlinMain wiring, crashlytics/bugsnag being mirror modules that should be edited in pairs, and kermit-koin's deliberately excluded targets.

Note: repo-wide policy lives only in the root file — agents read every CLAUDE.md on the path down, so module files carry module-specific facts, not repeated rules.

AGENT-USAGE.md

Consumer-facing guide for an agent adding Kermit to another project: which artifact to depend on for which need, core concepts, working code examples, per-module usage notes including platform restrictions, and the supported path for building a custom logging API on kermit-core (https://touchlab.co/kermit-custom-logger).

CONTEXT-GENERATION-TIPS.md

For the team: the original prompt used to generate these docs, the refinements made during review, and practical guidance (explore before writing, verify every cited signature against source, what belongs at which level) so the process is repeatable in other repos.

.github/workflows/claude_md_check.yml + README/CLAUDE.md follow-ups (added after initial draft)

• README now points AI agents at AGENT-USAGE.md; root CLAUDE.md instructs Claude to update doc context on meaningful changes (not bug fixes / minor internals).
• New GitHub Action runs a Claude-based doc-impact check on each PR and comments if the CLAUDE.md context looks stale. PRs from non-Touchlab authors are gated behind the claude-external-pr environment (required reviewers) so an org member approves the run before any API spend. Setup needed after merge: add the ANTHROPIC_API_KEY secret and create the claude-external-pr environment with required reviewers (details in the workflow header comment).

Review notes

• Please sanity-check the module docs you know best — the API details were spot-checked against source, but domain eyes are the real test.
• TEMP_OVERVIEW.md is now superseded by these docs and contains at least one outdated API example; proposing we delete it in a follow-up.

🤖 Generated with Claude Code