[antoinetoussaint-byte]

Closes #13.

Summary

• An agent starting in this repo had no statement of what it owns, how to build or test it, or how to behave when something does not work. AGENTS.md (127 lines) now carries that: the ownership boundary (the protos belong to module-saas-starter, the transport to the solution runtime, the signer to sdk-go, and _gen/ is never hand-edited), the commands transcribed from .github/workflows/ci.yml, the two version floors that only move together, and the behavioural rules from obin-ai/handbook#68 — anchored to things in this repo rather than stated in the abstract.
• The parity invariant is stated where an agent will hit it: two fixtures are byte-identical to saas-sdk-go, so editing one to go green locally removes the only signal that the two implementations disagree. That is the kind of change the standard means by hack, and the file says so.
• Procedural knowledge went to .claude/skills/ rather than into the root file — regenerate-bindings (the option-stripping step exists so this SDK never registers shared descriptors into the global pool) and wire-format-parity (the payload is closed by _reject_unknown, so a field added on the Go side and not here is a hard verification failure, not an ignored key). Both are read only when the task needs them.
• CLAUDE.md is the one-line @AGENTS.md pointer, so there is one canonical source. The issue framed this as "if a CLAUDE.md is added later"; adding it now is what makes that true rather than aspirational.

Classification: fix. No behaviour of the SDK changes; this adds the repo's missing agent context plus a test that keeps it honest.

Beyond the literal ask

tests/test_agent_context.py (5 tests) is not in the issue text. It enforces the standard's own conditions — root file ≤200 lines, CLAUDE.md exactly @AGENTS.md, and per skill a valid name matching its directory, a non-empty description ≤1024 chars, a body ≤500 lines — and asserts the skill list in AGENTS.md is exactly the set of skill directories, so a renamed or deleted skill cannot leave a pointer aimed at nothing. handbook#68 asks that these files be treated as code; python -m pytest -q already runs in CI, so this needs no workflow change. Two sibling adoptions (codefly-dev/core#536, obin-ai/module-record-store#41) added an equivalent guard. Say so if you would rather not carry it.

Test plan

• pip install -e ".[test,revision-connect,revision-grpc]" then python -m pytest -q — 143 passed (138 pre-existing + 5 new), run on both matrix interpreters: Python 3.10.21 and 3.12.14. Also passes on 3.14.7.
• The commands in AGENTS.md were run, not remembered — handbook#68 names unverified commands as an anti-pattern.
• The gate bites rather than passing vacuously: renaming a skill directory, making CLAUDE.md something other than the pointer, and padding AGENTS.md past 200 lines each fail the specific test, and the tree was restored after each.
• Claims in the prose were checked against the code, and one was wrong and rewritten: a draft bullet said a verification failure can report a structural denial when the cause is a stale key generation. It cannot — an unknown key_id raises unknown key id ... by name. The bullet now says the verifiable thing instead.

Not verified: the regenerate-bindings walk was not executed — it needs buf and a module-saas-starter checkout, and running it would rewrite _gen/, which does not belong in this pull request. It is transcribed from scripts/generate.sh, buf.gen.yaml and SOURCE.txt as they stand. Likewise, no cross-repo change to saas-sdk-go was made or needed here.

🤖 Generated with Claude Code