Documentation Health

This page tracks documentation quality for agent legibility. It is not a backlog for every missing note; it records gaps that affect future agent or teammate effectiveness.

Last reviewed: 2026-06-04.

Module Documentation Gaps

Domain modules that exist in code but lack a docs/modules/<name>.md:

Already documented: ConnectApi (docs/modules/connect-api.md).

Architecture Gaps

• ARCHITECTURE.md codemap does not mention routes/connect-api.php or the Connect API network boundary (JWT-authenticated external API surface).
• The Boundaries and Interfaces section should list the Connect API alongside the existing public API and hub API boundaries.

Process Gaps

• Link casing should be normalized (all lowercase filenames are now the convention).
• README should stay as an entrypoint, not a long tool manual.
• Agent entrypoint length should stay short enough to preserve task context.
• Repeated PR feedback should be promoted into docs, skills, tests, or lint checks.

Desired Checks

Add these when the repository is ready for mechanical doc enforcement:

• markdown link checker with case-sensitive path validation;
• max-line or max-byte check for .ai/guidelines/project.md;
• docs index coverage check for top-level durable docs;
• stale-doc review cadence for architecture and module docs;
• formatter/lint check for Markdown headings and code fences.

Maintenance Rules

• Update docs/index.md when adding a durable doc.
• Update ARCHITECTURE.md when boundaries, runtime modes, or invariants change.
• Update a focused workflow doc when the canonical implementation path changes.
• Prefer deleting or merging stale docs over preserving duplicates.
• Keep Laravel framework details in Laravel Boost or version-aware references.