docs(api): clarify Thread file upload and attach flow

[Yevanchen]

Summary

The Public Thread file API docs list seven file-related operations. The operations are not duplicate endpoints, but the current API reference labels make the flow look confusing because upload, complete, download, and attach all use the same "Thread file" noun without separating the file data plane from the Thread attachment control plane.

Current operation map

• POST /threads/{threadId}/files/uploads opens a Thread-scoped upload session and returns a fileId.
• PUT /files/{fileId}/content uploads the raw file bytes for that pending upload.
• POST /files/{fileId}/complete finalizes the pending upload into a ready file.
• GET /threads/{threadId}/files lists the files currently visible on the Thread.
• GET /files/{fileId}/content downloads a ready file.
• POST /threads/{threadId}/files attaches/claims an existing ready draft file handle to the Thread.
• DELETE /threads/{threadId}/files/{fileId} removes the file from the Thread file set.

Problems

1. Add a Thread file is ambiguous. It sounds like a new upload endpoint, but the implementation is attach/claim: createPublicThreadFile calls fileStore.claimToSession.
2. Create a Thread file upload, Upload Thread file content, and Complete Thread file upload should be explained as one upload data-plane flow, not as peer alternatives to Add a Thread file.
3. The docs need to make the recommended flow explicit: create upload -> PUT bytes -> complete -> list/download/use on next user turn.
4. The relationship between Thread-scoped uploads and POST /threads/{threadId}/files needs clarification. If POST /threads/{threadId}/files/uploads already creates a session-scoped attachment and complete makes it ready on the Thread, say that. If a separate attach step is still required for some draft source, explain when.
5. Compared with Anthropic Managed Agents docs, Mosoo lacks a task-oriented guide that separates file upload/storage from session or thread attachment. Anthropic first explains the session/file model, then shows task flows for upload, attach/mount, list, download, and runtime session resource management. Mosoo currently exposes the generated API reference flatly, so users cannot see which endpoints are sequential steps and which are optional management operations.

Suggested changes

• Rename the API summary Add a Thread file to something like Attach an existing file to a Thread.
• Rename Create a Thread file upload to Create a Thread file upload session.
• Group file docs into two conceptual sections:
  • File data plane: create upload, PUT content, complete, download.
  • Thread file control plane: list, attach existing file, remove.
• Add a short guide page: "Upload and use files in a Thread" with the canonical curl sequence and a note that the Agent sees ready Thread files on the next user turn.
• Add a note for the existing-file attach path explaining what kind of fileId is accepted and when callers need it.

Evidence from current code/docs

• Routes are distinct in apps/api/src/adapters/http/routes/public-api-route.ts.
• OpenAPI summaries live in apps/api/src/adapters/http/routes/public-api-openapi.ts.
• createPublicThreadFileUpload calls fileStore.createSessionResourceUpload.
• createPublicThreadFile calls fileStore.claimToSession.
• docs/prd/public-thread-api-surface.md already describes the two-stage concept, but the generated website API reference does not make this clear enough in navigation and endpoint naming.