docs: improve agent guidance

[opieter-aws]

Description

The AGENTS.md files are supposed to steer coding agents toward house conventions, but an audit of both SDKs against their own guidance turned up three gaps that let agents drift: the highest-traffic patterns weren't documented at all, several rules lived only in side docs an agent reading AGENTS.md never opens, and one cross-SDK rule was actively wrong.

This change makes the guidance match what the code already does and surfaces the un-lintable rules where an agent will actually load them. It is documentation-only — no source or behavior changes.

The most-repeated patterns are now written down. Adding a model provider and the async-generator streaming contract are the two patterns a contributor copies most often, and neither appeared in either AGENTS.md. Both SDKs now have mirrored "Adding a Model Provider" and "Async & Streaming" sections built from the existing skeleton (config-as-TypedDict/interface, validate_config_keys/resolveConfigMetadata, the keyword-only * before tool_choice, vendor-error translation), plus a Python "Data Structures" rule (TypedDict for wire/config shapes, @dataclass for runtime objects, pydantic only for model-read/write schemas) and a TypeScript interface-vs-type rule.

Un-lintable rules are surfaced where they're needed. Several judgment rules lived only in docs/STYLE_GUIDE.md / docs/HOOKS.md and were referenced only as bottom-of-page links. The Python guide now gates those reads at the point of use ("before adding a public interface, read STYLE_GUIDE.md"; "before adding a hook event, read HOOKS.md") and inlines the rules a linter can't catch (Protocol-over-Callable, tool_name over hardcoded strings, X | None over Optional, scoped # type: ignore[code], typed exceptions over bare Exception).

Genuinely shared rules now live in one place. Plugin naming, cross-SDK literal parity, public/internal API marking, the logging format, evergreen comments, and directory-naming parity were documented only on the TypeScript side though they apply to both SDKs — they're now a single "Cross-SDK Conventions" section in the root AGENTS.md that both sub-guides reference, so they can't drift apart.

Two contradictions fixed. The TypeScript guide told agents both "always provide explicit return types" and "leverage type inference where appropriate" with no precedence — now scoped to "explicit on signatures, infer locals." And the "use exactly the same literal as the Python SDK" rule was false for multi-word values (Python tool_use → TS toolUse via an explicit map); the rule now states the real convention (single-word identical, multi-word camelCased in TS, wire names verbatim). strands-ts/docs/TESTING.md also referenced a tests_integ/ directory that doesn't exist — corrected to test/integ/.

New strands-py/docs/TESTING.md. The TypeScript SDK had a 738-line testing guide; Python had ~40 lines in AGENTS.md and no docs/TESTING.md, which hid a real shared-fixtures library agents were reinventing. The new file documents the fixtures quick-reference, the tru_/exp_ assertion-pair naming, whole-object assertions, and the strict-asyncio marker rule.

Related Issues

None — maintenance change from a convention audit of both SDKs.

Documentation PR

Not applicable — these are contributor-facing AGENTS.md/docs/ files, not user-facing docs under site/.

Type of Change

Documentation update

Testing

Documentation-only. Verified that every file and symbol cited in the new guidance exists in the current tree (the provider skeletons, validate_config_keys/resolveConfigMetadata, STOP_REASON_MAP/snakeToCamel, the fixtures and conftest helpers, and the referenced docs/ links all resolve), and that the corrected test/integ/ path matches the real directory.

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!