Docs

Match the writing style to the audience.

• Public docs should be human-friendly and explain the implementation clearly.
• architecture.md pages in docs/core-concepts/ should explain how the feature works in detail.
• Agent docs in docs/agent-docs/ should be instruction-first and execution-oriented.
• Agent docs should avoid explanatory filler and focus on the exact steps an agent should follow to complete the work.

Prevent documentation drift on every implementation change.

• Before changing implementation, check the current user-facing docs for that feature.
• After changing implementation, update the relevant Markdown docs and the relevant OpenAPI YAML files in the same pass.
• Do not treat OpenAPI and Markdown as separate optional follow-ups when the feature contract or behavior changed.
• If a change affects agent workflows, update the corresponding file in docs/agent-docs/.
• If a change affects public product understanding, update the corresponding file in docs/core-concepts/, including architecture.md when implementation details changed.
• If a change affects SDK integration guidance, update the corresponding framework guide in docs/sdks/.