Chatto API Design Audit

Ask: Can an independent integration use Chatto's supported features without copying the bundled frontend's assumptions?

Review the public contract first. Inspect implementation only to confirm behavior that the contract does not settle. Report implementation defects separately from design gaps. This skill does not authorize fixes, issues, commits, or PRs; those need a separate user instruction.

Scope and Sources

• Follow root and path-specific AGENTS.md, including the current release policy. Keep Chatto separate from Authling and shared framework modules.
• Apply API rules. Use API compatibility for version and migration effects. Link to those rules instead of copying them.
• Start with public protobufs under proto/chatto/, mounted services, and generated API docs. Use FDRs to identify supported features and interfaces to check exposed surfaces. Use the glossary for terms and relevant ADRs for intentional design choices.
• For a full audit, cover integration, admin, auth, discovery, and realtime contracts. Keep the local Operator API in a separate section if reviewed. For a focused request, limit the audit and state what was not checked.
• Check relevant callers, tests, and docs to confirm findings. The frontend shows one use of the API; it does not define the full requirement.

Audit Method

1. Map services to resources and supported features. Note available reads, commands, collections, related IDs, and live events. Check that declared operations are mounted and usable by their intended callers.
2. Trace a few real workflows for the scope: a bot, an independent chat client, an admin tool, or a JSON-only integration. Start with discovery and access; follow the work through reads, writes, and refresh or reconnect as needed.
3. Apply the checks below. Mark each area as checked, not applicable, or not checked. Follow evidence; do not turn the checklist into a feature wish list.
4. Compare apparent gaps with documented product limits and design decisions. Confirm a concrete client problem before recommending a change.

Design Checks

Evidence and Verification

Use source paths and line references for findings. Distinguish a confirmed problem from an open question. A missing test alone is not a design defect.

Run existing focused checks when they can resolve uncertainty. Schema lint and compatibility checks do not prove usability or behavior. Do not run a full suite or start a server merely to inventory the API. Follow repository browser tooling rules when browser verification is needed. State what was verified.

Do not require CRUD, batch methods, events, or configuration for every resource. Require them only when a supported workflow needs them. Treat documented exceptions as choices to assess, not automatic violations.

Report and Stop

Lead with a short verdict on integration use, completeness, consistency, and future growth. State the scope and verification limits.

For each actionable finding, give:

• Priority and affected service or workflow.
• Source evidence and the concrete problem for an API consumer.
• The smallest useful change and why it improves the contract.
• Compatibility and caller migration effects; note stored-data effects separately.

Separate confirmed defects, design improvements, and open questions. Rank findings by client impact, not naming preference. Group related findings into small, coherent changes and recommend one next step.

Do not reopen explicitly deferred work unless new evidence changes its impact. Do not invent follow-up tasks to keep the audit going. If no meaningful gaps remain, say that the API is good enough for the reviewed scope and stop.