DX

Infer direction and surface from the request — never ask which mode:

• Existing surface → audit friction, debug a confusing failure, or run a pre-ship edge-case pass. Open with the first-impressions pass below, then load the matching sections of references/surfaces.md.
• New surface → shape the contract before it ships. Load references/designing.md plus the matching sections of surfaces.md.

Core principle: make the paved path obvious and failure states actionable. If a competent developer must guess, hunt through source, copy a stale example, or debug avoidable setup, that is a finding. The cheapest fix is before the contract ships — every observable behavior of a shipped interface gets depended on.

Invariants

• Errors are UI. Every error names the cause, the fix, and enough context to reproduce it; a bare "Invalid request" or "Unauthorized" is a finding wherever it appears. Redact secrets from every error, log, and verbose-output level.
• First-impressions bar. Open every audit or edge-pass with the 30-second first-impressions pass below. Time-to-first-success gates everything.
• Concrete over abstract. Every finding or design names the target developer (evaluator, first-time user, integrator, contributor, maintainer, operator, migration user), the named heuristic, and the concrete fix or paste-ready shape. Designs end with acceptance criteria checkable by reading the artifact or running a command.

First-impressions pass

A 30-second binary pass — the call an evaluator makes before deciding whether to adopt at all. Run it before any deep-surface work, so the basics are never hidden behind a good deep score. Every item is yes / no / n/a, observable in under 30 seconds from the repo, registry page, or first-run output: