docs: LLM-first quickstart + GET /v1/models and chat-completions reference (#3)

[longnhp12]

Context

Workstream 3/4 (Docs) of the Deva LLM API v1 epic (Bitplanet-L1/cross-eco-internal-docs#248). Per #3: docs led with agent identity/registration and had no LLM on-ramp; the API reference listed POST /v1/chat/completions only as a table row and didn't document GET /v1/models at all.

Part of #3 — covers the three active checkboxes (LLM-first quickstart, canonical path + /v1/models reference, SDK separation). The deferred deva.me/docs hosting checkbox stays open, so this PR intentionally does not close the issue.

What

• docs/quickstart.md — restructured to lead with "Call the Deva LLM API" (OpenRouter-style 3 steps): get a key via POST /agents/register, make a chat completion (cURL + official OpenAI Python/JS SDKs with base_url = https://api.deva.me/v1), and read costs (usage.cost, usage.deva.karma_cost/karma_balance, X-Deva-Karma-* headers, streaming final-chunk usage). The agent-platform quickstart is preserved below under its own heading.
• docs/api-reference.md — new full GET /v1/models subsection (query params, list envelope, all model fields incl. description, input/output_modalities, USD-per-token + karma pricing strings, capabilities, cache headers, detail route) and an expanded POST /v1/chat/completions subsection (canonical path per D1, request shape, streaming usage chunk, karma billing surfaces, 402 insufficient_quota). AI-resources table updated.
• SDK separation (README + quickstart): @deva-me/agent-sdk (Deva-me-AI/deva-agent-sdk, the native LLM/agent-resources SDK — now published to npm) vs @bitplanet/deva-sdk ("Login with Deva" auth SDK). The quickstart leads with cURL + the official OpenAI SDKs and the SDKs section adds real npm install @deva-me/agent-sdk instructions with a native DevaAgent.chat.create example (second commit, added after the package published).
• README.md — "Call any LLM" added as quickstart step 2 + SDKs section; docs/pricing.md points at GET /v1/models / deva.me/models as the live per-model pricing source.

Verification

• GET /v1/models example JSON copied from the live production endpoint (34 models, post-Bitplanet-L1/content-server#1959 contract with descriptions/modalities/real capabilities).
• Chat-completion usage/402 shapes validated against content-server source (app/schemas/ai_completions.py, app/apis/ai_completions.py).
• All intra-repo anchors resolve; no stale /v1/ai/chat/completions or @deva-ai/sdk references; the native-SDK example matches the published @deva-me/agent-sdk@0.2.0 README/source.

🤖 Generated with Claude Code

[claude]

Claude finished @longnhp12's task —— View job

---

PR #5 Review — LLM-first docs

Overall this is a strong, well-structured docs PR. The LLM-first restructuring reads cleanly (OpenRouter-style 3 steps), the GET /v1/models and POST /v1/chat/completions sections are thorough, and the SDK separation is clearly explained. Anchors resolve and I found no stale /v1/ai/chat/completions or @deva-ai/sdk references. Below are a few accuracy/consistency notes — nothing blocking.

Findings

1. Karma↔USD rate stated two ways (potentially confusing) — docs/quickstart.md:5

usage is charged in karma (1 ₭ = $0.001)

Every other doc states the rate as 1,000 ₭ = 1 USDC (pricing.md:7, x402-payments.md:20, architecture.md:57). 1 ₭ = $0.001 is arithmetically identical, but mixing per-unit vs per-1000 framing invites doubt. Suggest aligning on the canonical 1,000 ₭ = $1 form (or showing both explicitly, e.g. 1,000 ₭ = $1; 1 ₭ = $0.001).

2. Cost-vs-karma example math doesn't quite add up — quickstart.md:96-103, api-reference.md:227-228
The example pairs "cost": 0.000345 with "karma_cost": 1. With "karma charged in whole ₭, rounded up," a $0.000345 call → karma = 0.000345 × 1000 = 0.345 → rounds up to 1 ₭. That checks out and the inline note (quickstart.md:103) explains it well. ✅ Worth keeping that explanatory sentence in the api-reference copy too — api-reference.md:234 omits the rounding note that quickstart has, so a reader landing on the reference alone sees cost 0.000345 → karma_cost 1 with no explanation.

3. max_completion_tokens: 400 looks suspiciously low for gpt-4o — api-reference.md:167
The sample model object shows "context_length": 120000 but "max_completion_tokens": 400. If this was copied verbatim from the live endpoint it may be accurate, but 400 output tokens is unusual enough that a reader may assume a typo (e.g. truncated from 4000/16384). Worth double-checking the source value, or it'll generate support questions.

4. Truncated description in JSON sample — api-reference.md:168
The description ends mid-sentence with ... inside a JSON string literal. It's clearly illustrative, but since the block is valid-looking JSON a copy-paste user might be momentarily confused. Minor — a trailing …" reads as intentional truncation, which it already does. No change required.

5. Doc cross-links — pricing "2x OpenRouter" vs usage.cost — pricing.md:75, pricing.md:113 / README.md:113
Pricing still says LLM completion is 2x OpenRouter, while the new copy emphasizes usage.cost "mirrors OpenRouter's usage.cost" (api-reference.md:233). If usage.cost is the Deva (already-marked-up) cost, then it is not the raw OpenRouter cost — the "mirrors OpenRouter's usage.cost" phrasing could mislead a reader into thinking it's the un-marked-up upstream figure. Consider clarifying whether usage.cost is pre- or post-markup.

Minor / nits

• quickstart.md:35 etc. use model id anthropic/claude-opus-4-7, while the live workflow/model elsewhere is claude-opus-4-8. Fine as an illustrative id, just confirm it exists in the catalog so copy-paste works.
• GET /v1/models is listed as "Free (no auth)" in the AI-resources table (api-reference.md:114) and the section reiterates no-auth — consistent. 👍
• Streaming behavior (final-chunk usage, headers-before-cost) is explained consistently in both quickstart and reference. 👍

Security / performance

No concerns — documentation-only change. Example secrets are placeholders (deva_your_api_key), no real keys exposed. Caching guidance (ETag + max-age=300) on /v1/models is a nice touch.

Verdict: Approve-worthy after a quick look at items 1–3 (rate framing, reference-side rounding note, and the max_completion_tokens: 400 value). The rest are nits.
· docs/3-llm-first