| name | docs-contracts |
| description | Keep beater.js documentation, public contracts, final.md evidence, OpenAPI/action metadata, and ecosystem-facing scope honest. Use when changing routes, status codes, schemas, MCP/tool/action surfaces, build/deploy behavior, docs, milestones, or completion claims. |
beater.js docs and contracts
Use this skill whenever a code or behavior change affects what app developers, agents, operators, SDKs, or ecosystem projects can rely on. The job is not to write more docs; it is to keep public promises synchronized with the runtime.
Contract inventory
Before editing docs, identify which contract changed:
README.md: current user-facing status, quickstart, limits, and milestone claims.ARCHITECTURE.md: durable thesis, tier boundaries, runtime model, and deferred work.final.md: evidence-backed completion ledger; update only when the proof exists.docs/security.md: trust boundaries, auth, secrets, network exposure, and local/remote operator model.docs/runtime-limits.md: concurrency, queues, isolate/worker behavior, cancellation, and scaling limits.docs/tools.md: tool schema, idempotency, side effects, and model-facing tool contract.docs/integrations.md: first-party tools, remote MCP, browser providers, SaaS/API integrations, retries, sessions, and egress policy.- Generated/client-facing surfaces: OpenAPI, action metadata, MCP catalog schemas, llms.txt, sitemap, robots, and well-known manifests.
Required workflow
- State the changed behavior in one sentence using precise nouns: route, status code, field, schema, gate, auth rule, build artifact, or runtime limit.
- Find every public surface that mentions that behavior. Do not update only the nearest README sentence.
- Keep status claims evidence-based. Use present tense only after a test, script, transcript, CI check, or merged PR proves the claim.
- If a runtime-visible contract changes, update generated-client-facing docs or tests in the same slice.
- If a model-facing tool/action schema changes, keep one canonical shape. Do not publish unresolved
$ref, opaque object placeholders, or aliases for the same argument.
- If a completion checkbox changes in
final.md, include the command, transcript, PR, or CI evidence that proves it. If the evidence is pending, say pending.
- Keep docs short and operational. Prefer one exact invariant over broad marketing language.
Honesty checks
- Does a clean user know what to run, what credentials are required, and what will fail without them?
- Does an agent know the exact tool schema, side effect, idempotency, and auth model?
- Does an operator know what is exposed on the network and what protects it?
- Does an SDK/client generator see the same fields and statuses the runtime actually emits?
- Does the docs change survive a reverted-code thought experiment, or is it only aspirational?
Ecosystem communication
When the change affects beater.js as part of the broader ecosystem, document both sides:
- Standalone behavior: what beater.js can do without sibling projects.
- Integration lane: how it communicates with Beater, beater-memory, beatbox, tempo, beaterOS, remote MCP providers, or browser providers.
- Trust boundary: which credentials, origins, hosts, sessions, and idempotency keys cross that lane.
- Evidence: the test, script, trace, or gate proving the lane works.
Output standard
End with:
Docs updated: exact files and contracts covered.Evidence: command/CI/PR/transcript, or pending with the missing proof named.Remaining public promises: anything still aspirational or intentionally deferred.
