docs(openapi): cover the full HTTP API surface

[aaron-tsar]

Summary

The committed internal/http/openapi_spec.json documented 60 of ~258 actual HTTP routes (incl. the Vault chunk added in this PR's first commit). This PR brings that to 210 paths — full coverage of the public + admin surface — and adds 31 component schemas so generated clients have real types instead of object blobs.

Two commits:

1. docs(openapi): add vault endpoints + schemas — 19 Vault routes, 9 schemas, 2 tags (Vault, Vault Graph). Diff for this commit is +1961, 0 deletions.
2. docs(openapi): cover the remaining HTTP endpoints — 151 more paths, 19 schemas, 8 tags spanning KG, Memory, OAuth, Storage, Agents sub-resources, Skills, MCP, Providers, Tenants, CLI Credentials, System / Backup, Packages, Built-in Tools, TTS / Voices, Teams, Channels / Contacts, Evolution, Episodic Memory, Edition, openapi.json itself, API Keys revoke, Traces export, Usage breakdown.

Total this PR: +10620 lines, no existing operation/schema/tag modified.

Source of truth

Every entry is grounded in code from internal/http/*.go:

Area	Source files used
Vault	vault_handlers.go, vault_handler_documents.go, vault_handler_links.go, vault_handler_tree.go, vault_handler_upload.go, vault_graph_handler.go
Knowledge Graph	knowledge_graph.go, knowledge_graph_handlers.go, internal/store/knowledge_graph_store.go
Memory	memory.go, memory_handlers.go
OAuth	oauth.go (chatgpt+openai share the same handler set)
Storage / Files	storage.go, files.go, workspace_upload.go
Agents sub-resources	agents.go and helpers (agents_export*.go, agents_import*.go, agents_instances.go, agents_sharing.go, agents_prompt_preview.go, agents_workspace.go)
Skills	skills.go
MCP	mcp.go, mcp_user_credentials.go
Providers	providers.go
Tenants / users	tenants.go, channel_instances.go (users/search)
CLI Credentials	secure_cli.go, secure_cli_user_credentials.go, secure_cli_agent_grants.go
System / Backup	system_configs.go, backup_handler.go, backup_s3_handler.go, tenant_backup_handler.go, restore_handler.go, edition.go, openapi.go
Packages	packages.go
Built-in Tools	builtin_tools.go
TTS / Voices	tts.go, voices.go, tts_capabilities.go
Teams / Channels / Contacts	agents.go (team export/import), channel_instances.go, team_events.go, team_attachments.go
Evolution / Episodic	evolution_handlers.go, episodic_handlers.go
Traces / Usage / API keys	traces.go, usage.go
Orchestration / v3 flags	orchestration_handlers.go, v3_flags_handlers.go

For each handler I read: route registration line (method + path), var body struct { ... } if any (to derive request body fields), and the writeJSON(...) call shape (to derive responses). Where the body is generic / free-form (map[string]any / additionalProperties: true), the spec documents that honestly rather than fabricating a rigid schema.

Diff cleanliness

Default git diff uses the Myers algorithm, which for this kind of big-block JSON insertion produces some cosmetic deletion lines (about 270) even though no semantic content was removed. Verified two ways:

• git diff --histogram and git diff --patience both report 0 deletions for the second commit (the first commit was already 0 deletions under Myers).
• Programmatic check: load HEAD's spec + the new spec with json.load and compare every operation / schema entry. All originals are bit-identical; nothing was changed in place.

$ git diff --diff-algorithm=histogram --stat internal/http/openapi_spec.json
 internal/http/openapi_spec.json | 10620 +++++++++++++++++++++++++...
 1 file changed, 10620 insertions(+)

What's intentionally not covered

• WebSocket-only methods (sessions, cron, chat history, pairing, ...). The OpenAPI spec is HTTP only.
• A few admin / internal endpoints whose handlers accept fully free-form payloads (e.g. agents_import_handlers.go) are documented with additionalProperties: true rather than a fabricated rigid body. If the maintainers want strict shapes for those, happy to follow up after this lands.
• Workstations + Webhooks weren't in the route gap on dev at this commit.

Test plan

• JSON parses (python3 -c "import json; json.load(open(...))").
• go build ./internal/http/ — //go:embed compiles with the new bytes.
• go vet ./internal/http/ — clean.
• Semantic preservation check: every original paths[*][method] entry and every original components.schemas[*] entry is bit-identical between HEAD and the new file.
• No existing tag renamed or removed.
• Run goclaw locally and curl /v1/openapi.json → Swagger UI at /docs should now list every visible HTTP handler.

Why one PR instead of three

I started with a Vault-only PR for review-size reasons and the maintainers' time. The user driving this asked to ship it all together since the work is mechanical and verifiable — the diff is large but flat, and the semantic preservation is automatable.

Happy to split back into three commits (Vault / KG-Memory / rest) if that's easier to review — they're already separable in the current commit history.