docs: publish the OpenAPI document

[tuliomir]

Stacked PR. This sits on top of #25 and targets its branch, so review only this PR's own commit — GitHub re-targets it to main when #25 merges. (GitHub's Stacked Pull Requests are in public preview.)

The README advertised a canonical OpenAPI document that did not exist. Adds docs/openapi.yaml describing all seven operations, the shared error schema with every code mapped to its status and retryable value, the X-Test-Name and x-request-id headers, the /status diagnostic body, and the readiness reasons.

It is based on #25 rather than main because the contract it documents is the one that ships with that fix: the spec carries the funding_initializing reason and states that /fund refuses exactly the phases /ready refuses. Documenting the pre-fix behaviour would have made this stale on the day it merged.

How it works

• docs/openapi.yaml (new) — derived from the handlers, not the README. OpenAPI 3.1, validated against the official meta-schema.
• .github/workflows/ci.yml — a validation job, SHA-pinned like the existing one.
• package.json — the validator is a devDependency resolved from the lockfile rather than fetched at run time, so a registry blip cannot fail an unrelated PR and Dependabot can watch it.
• .github/dependabot.yml — npm joins the covered ecosystems, with the same weekly cadence, 7-day cooldown and patch filtering as the actions block.
• __tests__/src/openapi-version.test.ts (new) — pins info.version to package.json. Client generators stamp that value into generated metadata, so a stale one misleads, and the schema validator would accept any semver string.
• CONTRIBUTING.md — referenced docs/OPENAPI.yaml in the wrong case and docs/AGENT-CONTRACT.md, which has never existed in this repository. The first now resolves; the second is dropped, its retry/error/readiness role folded into the document this PR adds.

Behavioral change

None at runtime. One documentation correction: the README's readiness table listed wallet_unfunded before funds_query_error under "evaluated in this order". The funds query runs inside currentReadiness before computeReadiness is reached, so a failed query never reaches the funded/unfunded decision — funds_query_error comes first. The table is corrected to match the code.

Known limitation

Schema validation proves the document is well-formed, not that it describes this service. Nothing yet detects the spec disagreeing with the handlers — tracked in #33, which also names the concrete case already queued (#31 changes the /multisigWallet response).

Acceptance criteria

• bun run validate:openapi passes locally and in CI, and fails on a malformed document or a dangling $ref.
• All seven endpoints, every error code with its status and retryable value, and the /status body are described.
• The README links to the document instead of promising it.
• info.version matching package.json is enforced by a test.

Closes #29

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 244c8906-053d-4778-bae1-f72d673bfb96

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}