Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Please document how a local client authenticates against the V2 background service, so third-party integrations can use the HTTP API (including GET /api/event) directly.

The V2 migration guide says integrations that call the server API must migrate to the V2 API, and the troubleshooting page says opencode api "uses the local service discovery and authentication flow". However, that flow itself is not documented anywhere I could find:

• The API reference lists 401 UnauthorizedError on every route, but not which scheme is expected.
• The OpenAPI document served at /openapi.json has an empty security array and no securitySchemes.
• ~/.local/state/opencode/service.json contains url and password, but no page explains how they are meant to be used.

By trial I found that HTTP Basic auth with the username opencode and the password from service.json works. Bearer auth, or Basic auth with an empty username, returns 401. That works today, but it is an undocumented detail I would rather not depend on.

opencode api is not a full substitute for integrations: opencode api get /api/event does not pass the event stream through while it runs, so a client that needs live session events (session.execution.*, permissions, …) has to talk HTTP itself.

What would help

1. Document the discovery file (service.json: which fields, stability guarantees) and the auth scheme (e.g. Basic, username opencode) as a supported contract.
2. Declare the scheme in the served OpenAPI document (components.securitySchemes + security), so generated clients pick it up.
3. Optionally, let opencode api get /api/event stream its output.

Context

I'm building a desktop app that hosts OpenCode agents as terminal tiles on top of the shared service: it creates sessions via POST /api/session (location, model, permissions) and follows /api/event for status. Everything else it needs is documented. Only the authentication step is not.

opencode --version: 2.0.18, macOS.