This directory holds repository-specific guidance for contributors and coding agents. AGENTS.md is the session entry point; use this index to find relevant details without scanning the repository.

• Optimize for retrieval. Put one coherent topic in each file, use descriptive filenames and scannable headings, and place the task-specific guidance before background context.
• Be concise and actionable. Record verified behavior, constraints, decision points, failure modes, and required implementation/test touchpoints. Prefer a precise bullet, short procedure, or small lookup table over narrative.
• Link to evidence. Include exact repository paths and relevant identifiers so an agent can jump to implementation, tests, or user-facing configuration. Do not copy large code excerpts or repeat information already maintained elsewhere.
• Maintain the source of truth. In each session, capture verified, durable repo-specific insights found during implementation, debugging, or investigation. Create and index a focused page when a useful topic is missing; update or remove guidance when code changes make it inaccurate.
• Keep pages lean. Exclude transient notes, unverified hypotheses (see below), generic programming advice, and details an agent can safely derive from a nearby definition. Consolidate overlap and link to the canonical page.
• Keep navigation complete. Add every page to this index with a short description; use links between related pages instead of duplicating their content.
• Respect the size guideline. Split a page when it exceeds about 8 KB or covers two distinct tasks; Build\scripts\Test-Docs.ps1 warns above 8 KB.
• Park unverified findings. Record tentative observations in open-questions.md with how to verify them, not in topic pages. Promote or delete them once checked.
• Validate after editing docs. Run pwsh Build\scripts\Test-Docs.ps1 (index completeness, relative links, anchors, page size).
• Keep AGENTS.md concise and limited to startup guidance and navigation.