not-elm/desktop-homunculus/sync-api-docs

Sync API Documentation

Synchronize API documentation with the actual HTTP server and SDK implementation.

Phase 1: Analysis

Gather information and present findings before making changes.

Steps

1. Read HTTP endpoints: Scan crates/homunculus_http_server/src/** to extract all endpoint definitions (routes, methods, request/response types)

1. Read SDK interfaces: Scan sdk/typescript/src/** to extract client interfaces and type definitions

1. Read current documentation:

• docs/api/open-api.yml for OpenAPI spec
• docs/mod-manual/src/sdk/** for SDK manual

1. Compare and classify: For each endpoint and SDK interface, determine status:

• new — exists in code but not in docs
• changed — exists in both but differs
• unchanged — matches between code and docs
• removed — exists in docs but not in code

1. Present summary table:

| Type     | Name           | Status    | Notes                   |
|----------|----------------|-----------|-------------------------|
| Endpoint | POST /api/xxx  | new       | Not in OpenAPI spec     |
| Endpoint | GET /api/yyy   | changed   | Response schema differs |
| SDK      | SomeClient     | unchanged |                         |

1. Ask for confirmation: "Proceed with documentation updates?"

Do NOT proceed to Phase 2 without explicit user confirmation.

Phase 2: Update

After user confirms, update the documentation.

Steps

1. Update OpenAPI spec: Modify docs/api/open-api.yml to reflect current endpoints

• Add new endpoints with appropriate tags
• Update changed endpoint schemas
• For removed items: confirm with user before deleting

1. Update SDK manual: Modify docs/mod-manual/src/sdk/** to match SDK interfaces

1. Regenerate: Run make build-openapi

1. Report: Summarize what was updated

Constraints

• Documentation must be in English
• Documentation must match the actual implementation (not aspirational)
• Documentation must be clear and concise
• Tag APIs appropriately by category (e.g., vrm, webview, chat, system)
• Never remove documentation for "removed" endpoints without explicit confirmation