api-designlisted

# API design Treat every public function, command flag, file format, and exported type as a contract. ## Surface Expose the smallest surface that solves the current need. Keep helpers private until a real caller appears. Avoid making implementation details part of the contract. ## Behavior Make inputs, outputs, ordering, defaults, and failure modes predictable. If behavior is conditional, name the condition directly instead of hiding it behind a vague option. ## Compatibility When changing an existing contract, look for callers, tests, generated artifacts, and docs. Decide whether compatibility matters for the version you are working on, then migrate the whole surface consistently. ## Errors Errors are part of the API. Give expected failures stable types or codes, clear messages, and enough context for the caller to recover.