AGENTS.md

Agent Guidance

This file is a repository-owned contract for agents that create or maintain documentation. It is not a contributor guide and does not define a human contribution workflow.

Documentation Boundaries

Give each documentation surface one reader and one job:

• README.md is the front door for prospective and new users. Keep installation, a correct first success path, the current feature summary, and links to deeper material there; do not turn it into a comprehensive manual.
• docs/usage-guide.md serves users choosing how to operate yin. Put workflow judgment, tradeoffs, catch-up patterns, and guidance about when to use snapshots, deltas, or projections there.
• docs/json-formats.md serves implementers who persist or exchange encoded artifacts. Put exact JSON artifact contracts, field meanings, examples, validation behavior, and compatibility boundaries there.
• docs/releasing.md serves maintainers publishing tagged versions. Put release preparation, version tagging, workflow verification, and failure recovery there.
• DECISIONS.md serves maintainers and future agents looking for the rationale behind settled design choices. Record why a direction was chosen rather than repeating user instructions or current format definitions.
• BACKLOG.md serves maintainers and agents coordinating active planning. Keep prospective work, priorities, and unresolved follow-ups there; it is not documentation of shipped behavior.
• Go comments serve API consumers reading package documentation and maintainers reading the implementation. Document exported API semantics, invariants, and non-obvious implementation constraints close to the code.

Link to the canonical surface instead of copying detailed facts between files. A short summary needed for navigation is acceptable, but field tables, workflow explanations, rationale, and planning state each belong only in their assigned location. When behavior changes outside documentation-only work, update the owning surface and any links to it.

Repository Constraints

• yin is experimental and pre-1.0. Describe current behavior without promising format or API stability.
• The Go module is stdlib-only. Do not add third-party dependencies for documentation, examples, or validation.
• Documentation work must not change public APIs, runtime behavior, persistence behavior, or encoded JSON formats.
• Preserve the distinction between user-visible JSON projections, durable snapshots, and deltas. Do not imply that one artifact can substitute for another unless the API contract says so.
• Avoid duplicated canonical details. Verify claims against the implementation and place corrections in the documentation surface that owns them.

Validation

Choose checks proportional to the changed surface and run them from the repository root:

• Run go test ./... for executable examples and module-wide checks.
• Run go vet ./... for changes to Go source, including Go comments and examples.
• For docs-only edits, use focused deterministic checks such as test -f, grep, and checks that relative links resolve. Avoid network-dependent or nondeterministic validation.

All required checks must pass before documentation work is considered complete. Documentation examples that are executable should be covered by go test ./...; do not rely only on visual inspection.