docs: add guide for using Headroom with OpenCode + DeepSeek

[suvenkatesh97]

Documents how to configure Headroom proxy with DeepSeek for OpenCode users.

• No headroom wrap needed -- manual config avoids Claude/GPT model overwrites
• Covers proxy setup, OpenCode provider config, output shaping, model comparison, and troubleshooting
• Includes current DeepSeek V4 Pro and V4 Flash models, with deprecated alias guidance for deepseek-chat / deepseek-reasoner
• Adds the guide to the published docs tree and navigation
• All API keys use placeholders

Description

Adds documentation (docs/content/docs/opencode-deepseek.mdx) showing OpenCode users how to route through Headroom proxy with DeepSeek. Addresses the gap described in #78 (OpenCode integration docs) and provides the manual config workaround documented in #1679 (wrap broken with Go CLI).

Type of Change

• Documentation update

Changes Made

• New docs page: docs/content/docs/opencode-deepseek.mdx -- step-by-step setup guide covering proxy launch, OpenCode provider config, output shaping, model comparison, thinking-mode notes, and troubleshooting
• Updated docs/content/docs/meta.json so the guide appears under Integrations

Testing

• Guide verified against a working setup: headroom proxy on port 8787, DeepSeek V4 Pro and V4 Flash models, OpenCode with @ai-sdk/openai-compatible provider, output shaping level 2
• All API keys use placeholders -- no real credentials in the doc
• git diff --check
• npm ci in docs/
• npm run types:check in docs/ -- currently fails in existing generated docs plumbing: lib/source.ts(2,22): error TS2306: File '.../docs/.source/server.ts' is not a module.

Real Behavior Proof

• Environment: Ubuntu, Python 3.13, headroom-ai 0.32.1, OpenCode (Go CLI)
• Setup: headroom proxy --port 8787 --openai-api-url https://api.deepseek.com/v1, OpenCode config using @ai-sdk/openai-compatible pointing at http://127.0.0.1:8787/v1
• Observed: proxy routes chat completions to DeepSeek, input compression active (SmartCrusher), output shaping (level 2) reduces response tokens by ~11%
• Dashboard: http://127.0.0.1:8787/stats shows compressed requests and token savings

Review Readiness

• I have performed a self-review
• This PR is ready for human review

[github-actions]

PR governance

This PR does not yet satisfy the required template fields:

• Paste real command output or artifact links in Testing → Test Output.
• Fill in Real Behavior Proof → Exact command / steps.
• Fill in Real Behavior Proof → Observed result.
• Fill in Real Behavior Proof → Not tested.

Please update the PR body, or move the PR back to draft while it is still in progress.

[JerrettDavis]

Thanks for putting this together. I think the guide needs one correctness pass before it is ready.

The new R1 section and the model table still describe deepseek-reasoner as a selectable R1/128K model, and the section says users can switch to it with /model deepseek-reasoner even though the preceding text says only proxy-exposed models should be placed in the OpenCode picker. DeepSeek's current API docs list deepseek-v4-flash and deepseek-v4-pro as the active model names, and explicitly say deepseek-chat / deepseek-reasoner are compatibility aliases that will be deprecated on 2026-07-24 15:59 UTC, with deepseek-reasoner corresponding to thinking mode on deepseek-v4-flash: https://api-docs.deepseek.com/

Please update the guide to use the current V4 model names consistently, and document thinking mode via the current DeepSeek request parameters instead of presenting deepseek-reasoner as a separate R1 model. That should also remove the contradiction between "only include model IDs from /v1/models" and the later instruction to switch to a model that the guide says is not in that list.

[suvenkatesh97]

Thanks for the review. Updated:

• Removed the "Using DeepSeek R1 (reasoner)" section and all references to deepseek-reasoner/deepseek-chat
• Replaced with a "Thinking mode (reasoning)" section that documents the thinking: {"type": "enabled"} and reasoning_effort parameters on deepseek-v4-pro/deepseek-v4-flash
• Config only includes deepseek-v4-pro and deepseek-v4-flash — consistent with what the proxy exposes via /v1/models
• Removed the contradictory /model deepseek-reasoner instruction from troubleshooting
• Added deprecation note in "What's NOT in this guide"

[JerrettDavis]

Thanks for the quick follow-up. The deprecated-alias issue is much better now, but the guide still has a few product-truth problems that need to be fixed before this is ready:

• The OpenCode model config and comparison table still list both V4 models as 200000 / 200K context with 16384 output. Headroom's registry and pricing data model these as 1,000,000 context and 384,000 max output (headroom/models/registry.py, headroom/pricing/deepseek_prices.py), and DeepSeek's current pricing docs say context length is 1M and max output is 384K: https://api-docs.deepseek.com/quick_start/pricing/
• deepseek-v4-flash is still labeled "Free" / "free-tier reasoning". The current pricing data has Flash at $0.14 input / $0.28 output per 1M tokens, with cache-hit input at $0.0028. If DeepSeek offers promotional free credits elsewhere, this setup guide should not present the model itself as free.
• The PR body is now stale: the intro/testing bullets still say the guide includes R1/reasoner models. Please update the description to match the current guide and include the actual test-output/template fields so governance stays accurate.

Once those are corrected, the original blocker about selecting deepseek-reasoner from OpenCode should be resolved.

[suvenkatesh97]

Thanks — all three issues fixed:

• Context/output limits corrected to 1M / 384K per DeepSeek's pricing page
• Flash is no longer labeled "Free" — pricing updated to $0.14/$0.28 per 1M tokens
• Thinking mode section simplified to a one-liner (works out of the box, no extra config)
• PR body updated — removed R1 references from intro and testing sections

[JerrettDavis]

Re-reviewed the latest branch after the DeepSeek corrections and docs integration update. The guide now uses the current V4 Pro/Flash model names, 1M context / 384K max-output limits, and current per-1M pricing, and it no longer presents Flash as free or R1/reasoner as a selectable OpenCode model. I also moved the page into the published docs tree (docs/content/docs/opencode-deepseek.mdx), added it to meta.json, and updated the PR body so the path/testing notes match the source.\n\nValidation: git diff --check passed;
pm ci in docs/ passed.
pm run types:check still fails in existing generated docs plumbing with lib/source.ts(2,22): error TS2306: File '.../docs/.source/server.ts' is not a module., so I do not think that failure is introduced by this guide.\n\nThis is ready for final human review from my side.