docs(api): document v1 conventions and add contract drift tests (#829)

[Zach Dunn (zachdunn)]

Problem

Issue #829's §1 checklist had two items left unfinished after PR #830: the
OpenAPI document didn't cover several registered canonical file routes, and
nothing caught drift between the three descriptions of the public API
(registered routes, openapi.json, docs/api.md). §6 asked to freeze the
v1 collection-envelope and error conventions in prose.

Changes

§1 residue

• apps/web/public/.well-known/openapi.json: added the three canonical file
  routes that were registered but undocumented — GET .../files/by-path, GET .../files/file-url, and PATCH .../files/visibility.
• apps/api/src/openapi-contract.test.ts: a new static test that loads the
  Hono app's app.routes, openapi.json, and docs/api.md, and asserts
  they agree on the files/usage/galleries verticals (plus /public/galleries/:id).
  It flags a route missing from either doc and a documented path that no
  longer exists on the app. I verified it actually catches drift by
  temporarily renaming a path in openapi.json and watching it fail.

§6 — freeze v1 conventions

• docs/api.md "Pagination" section: added a "Collection envelope shapes"
  table listing the exact field set for every list endpoint
  ({ files, prefixes, cursor }, { items, truncated, cursor }, etc.),
  extending the existing section from PR feat(api): cursor-paginate file search (#829) #838 rather than duplicating it.
• docs/api.md "Errors" section: clarified that type is the broad
  category and code is the stable branch key, and documented that an
  AppError can override its default HTTP status but that override never
  travels on the wire (verified against packages/errors/src/base.ts and
  types.ts — no route uses the override today).

Scope note

The contract test covers the files/usage/galleries verticals — the ones
issue #829 named and the ones docs/api.md's "Canonical routes" table
documents. The canonical github/members/storage/billing verticals
(issue #613 phases 2–3) are session-only account management with their own
docs; folding them into this guard is a separate, larger piece of work and
is called out as out of scope in the test's docblock rather than silently
expanded.

Nothing renamed or removed — additive only. Legacy /v1/:workspace/...
stays documented as a compatibility family, not path by path.

Testing

• pnpm test (root): 5140 tests pass.
• pnpm --filter @uploads/api typecheck: clean.
• Manually broke a path in openapi.json to confirm the new test fails as
  expected, then restored it.

Refs #829 §1, §6.

[changeset-bot]

⚠️ No Changeset found

Latest commit: d79f62c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (2)

• coderabbit:review
• review

🚫 Excluded labels (none allowed) (1)

• wip

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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 22ca7a6c-63b5-4cb8-ae64-f6453a236e88

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.}