diff --git a/docs/systems/api.md b/docs/systems/api.md
index b6eeb73f..514dca0f 100644
--- a/docs/systems/api.md
+++ b/docs/systems/api.md
@@ -184,9 +184,21 @@ PATCH  /spaces/:id/join-requests/:rid    { action }          → { request }  [M
 GET    /users/@me/join-requests          ?status=            → { requests[] }
 ```
 
-## Uploads (`routes/uploads.ts`)
+## Uploads (`routes/files.ts`, `routes/uploads.ts`)
+
+### Tus Upload Endpoints
+
+| Method | Path | Auth | Purpose |
+|--------|------|------|---------|
+| POST | `/api/files/` | JWT | Create resumable upload. Returns `Location` (upload URL) and `Upload-Expires`. |
+| HEAD | `/api/files/:uploadId` | JWT (ownership) | Probe `Upload-Offset` for resume. |
+| PATCH | `/api/files/:uploadId` | JWT (ownership) | Append bytes at offset. |
+| DELETE | `/api/files/:uploadId` | JWT (ownership) | Abort. |
+
+The final PATCH that completes an upload returns the `Attachment` JSON in its response body. See `docs/systems/uploads.md` for the full pipeline (PRE_CREATE / PRE_PATCH / POST_FINISH hooks, storage layout, janitor).
+
+### File Serving
 ```
-POST /uploads     (auth, multipart, rate-limited) → { attachment }
 GET  /uploads/:filename  (public, supports Range) → file stream
 ```
 
diff --git a/docs/systems/federation.md b/docs/systems/federation.md
index c6577cb8..7ca6fc27 100644
--- a/docs/systems/federation.md
+++ b/docs/systems/federation.md
@@ -898,6 +898,10 @@ When the origin instance receives a `file_rejected` event:
 
 Uses the same backoff schedule as outbox delivery. Max attempts: 10 (`MAX_FILE_ATTEMPTS`). After exceeding max attempts: `status = 'failed'`, `rejectionReason = 'max_attempts_exceeded'`.
 
+### Boundary vs. tus Upload Migration (2026-04)
+
+The `federation_file_queue` worker downloads files from peer instances via plain `fetch` + `Readable.fromWeb` to disk, post-completion. It consumes finished files at `${uploadDir}/${filename}`. Whether a file got there via the legacy multipart endpoint, the current tus endpoint at `/api/files/*`, or any future protocol is invisible to this worker -- its contract is purely with the on-disk filename. No changes were required when the upload protocol changed.
+
 ---
 
 ## 8. Read State Relay