Diagnose the main legibility failures with references/legibility-rubric.md. Look for missing maps, hidden conventions, stale docs, weak boundaries, and validation gaps.
Make AGENTS.md a map, not an encyclopedia. Keep it short, stable, and action-oriented. Point to deeper sources of truth instead of duplicating them.
Move important knowledge into the repo:

Treat docs/ or another obvious repo-local knowledge area as the system of record for non-trivial repositories. Add indexes and cross-links so the agent can progressively discover depth instead of receiving one giant instruction blob.
Encode constraints mechanically wherever possible:

Write remediation messages for lint and structural-test failures so another agent run can recover without human translation.
Increase runtime legibility when the task depends on behavior rather than static code. Make the relevant system locally runnable or inspectable, expose reproducible scripts, and give agents access to logs, metrics, traces, test harnesses, CLIs, UIs, or other feedback loops as appropriate.
Capture human taste once, then promote it into reusable artifacts. Convert repeated review comments and tribal knowledge into docs, helpers, lints, tests, or templates.
Plan for entropy. Add recurring doc-gardening, quality scoring, or targeted cleanup work so bad patterns are corrected continuously instead of in occasional cleanup sprints.
Report outcomes in terms of leverage:

Default Deliverables

A concise AGENTS.md that routes the agent to deeper sources.
A repo-local knowledge structure with clear indexes.
Architecture, operational, and planning artifacts for areas that are currently implicit.
Mechanical checks for the highest-value invariants.
A prioritized legibility audit with concrete next steps.

Decision Rules

Optimize for what a future agent run can discover and trust quickly.
Prefer progressive disclosure over giant instruction files.
Prefer boring, inspectable abstractions over opaque dependencies at critical boundaries.
Enforce invariants centrally and allow flexibility inside those boundaries.
Version plans, decisions, and standards near the code they govern.
Treat stale documentation as a correctness problem, not a cosmetic one.

legibility-rubric.md: audit dimensions, failure modes, and prioritization checklist.
artifact-patterns.md: recommended document set, layout patterns, and enforcement ideas.