Write extensions/vision/README.md (the 10-section plan outline) #262

New issue

Closed

opened 2026-09-17 03:34:58 +00:00 by david · 1 comment

david commented

2026-09-17 03:34:58 +00:00

Owner

Summary

Write extensions/vision/README.md following the plan's §13 outline (10 sections), describing the shipped behaviour: what the tool does, how to configure it, its limits, thinking mode, failure behaviour, and cost.

Background

Depends on: #254, #255, #256, #257, #258, #260, #261

Every other extension in this repo ships a README next to its index.ts (extensions/mongodb/README.md, extensions/victorialogs/README.md, extensions/penpot/README.md). This is the user-facing contract for the vision extension and is referenced from the repo root README (next step).

Write it against the implemented behaviour, not the plan's intentions. If the implementation diverged from the plan anywhere (e.g. the detail values accepted, whether thinking: {"type":"disabled"} is accepted for vision, an error message's exact wording), the README must describe what the code actually does — that is the point of this step landing after the code.

Follow the section order in the plan's §13 outline exactly, so a reader can check the README against the plan.

Documentation Required

A separate process downloads these into the listed folders before this issue is implemented. Check the folder for the actual reference material before starting.

docs/reference/deepseek-api/

https://api-docs.deepseek.com/guides/vision/ — what the model accepts, the three input methods (this extension uses inline base64 only), the detail values, and the Limits table, all of which the README restates in user terms.
https://api-docs.deepseek.com/guides/thinking_mode/ — thinking is on by default, and the {"thinking":{"type":"enabled|disabled"}} toggle.
https://api-docs.deepseek.com/quick_start/pricing/ — the deepseek-flash peak/off-peak rate table and peak hours, for the cost section (with the best-effort caveat).
https://api-docs.deepseek.com/quick_start/error_codes/ — the status codes whose hints the client surfaces.
https://api-docs.deepseek.com/api/create-chat-completion/ — the usage fields, for the token/cost section.

docs/reference/image-size/

https://www.npmjs.com/package/image-size — the formats image-size detects and the type values, relevant to the "which formats are accepted" wording.

Implementation Details

Create extensions/vision/README.md with these sections, in this order (from plan §13):

What it does and when the agent should use it — one short paragraph plus a sentence on when the current model cannot read an image.
Requirements — DEEPSEEK_API_KEY; state plainly that the tool is absent (not erroring) without it.
Environment variables — a table with Variable / Required / Default / Meaning for DEEPSEEK_API_KEY, VISION_MODEL, VISION_BASE_URL, VISION_MAX_TOKENS, VISION_TIMEOUT, VISION_THINKING, matching src/config.ts.
Usage example — a realistic agent call (prompt, images, optional detail/thinking) and what comes back (text + details + usage).
Limits and validation — the DeepSeek numbers that src/images.ts enforces (formats, 32 MiB per image, 48 MiB body, 600 images, 8192 px / 4096 px at ≥ 15 images) and the fact that failures name the offending file/limit.
Thinking mode — off by default; retry with thinking: true; raise VISION_MAX_TOKENS when enabling it because reasoning tokens count toward the cap.
Failure behaviour — failures throw a ToolError with an actionable message; never a stack trace.
Cost — the peak/off-peak rate table for deepseek-flash with a clearly-labelled best-effort note against DeepSeek's published prices.
Non-goals — image generation/editing, http(s) URLs, the Files API, caching, multi-turn state, streaming, per-call model override.
Development — npm test (note that tests never hit the network) and the manual live-verification command for a real key.

Style: match the sibling extension READMEs (heading levels, table formatting, code fences with bash/json language tags). Use the em-dash style already used across the repo's docs. Do not invent flags or env vars that src/config.ts does not read.

Acceptance Criteria

extensions/vision/README.md exists with all 10 sections, in the order listed above.
The environment-variable table matches src/config.ts exactly (names, defaults, required/optional).
The limits section states DeepSeek's actual numbers and matches what src/images.ts enforces.
The cost section carries the peak/off-peak table and an explicit best-effort caveat linking the pricing page.
The non-goals section lists the plan's confirmed out-of-scope items.
The development section gives npm test and notes tests never hit the network, plus the manual live command.
No env var or parameter is documented that the implementation does not support.

Test Plan

Documentation review — no code to run. Verify the README against the code:

cd /Users/david/Projects/pi-extensions-and-skills
# every env var the README documents is read by config.ts
grep -o "VISION_[A-Z_]*\|DEEPSEEK_API_KEY" extensions/vision/README.md | sort -u
grep -o "VISION_[A-Z_]*\|DEEPSEEK_API_KEY" extensions/vision/src/config.ts | sort -u

Expected: the two sets match exactly.

npm test

Expected: unaffected by this change and still green.

Manual read-through: confirm each of the 10 numbered sections is present and its claims can be traced to the listed source files.

## Summary Write `extensions/vision/README.md` following the plan's §13 outline (10 sections), describing the shipped behaviour: what the tool does, how to configure it, its limits, thinking mode, failure behaviour, and cost. ## Background **Depends on:** #254, #255, #256, #257, #258, #260, #261 Every other extension in this repo ships a README next to its `index.ts` (`extensions/mongodb/README.md`, `extensions/victorialogs/README.md`, `extensions/penpot/README.md`). This is the user-facing contract for the `vision` extension and is referenced from the repo root README (next step). Write it against the *implemented* behaviour, not the plan's intentions. If the implementation diverged from the plan anywhere (e.g. the `detail` values accepted, whether `thinking: {"type":"disabled"}` is accepted for vision, an error message's exact wording), the README must describe what the code actually does — that is the point of this step landing after the code. Follow the section order in the plan's §13 outline exactly, so a reader can check the README against the plan. ## Documentation Required A separate process downloads these into the listed folders before this issue is implemented. Check the folder for the actual reference material before starting. **`docs/reference/deepseek-api/`** - https://api-docs.deepseek.com/guides/vision/ — what the model accepts, the three input methods (this extension uses inline base64 only), the `detail` values, and the Limits table, all of which the README restates in user terms. - https://api-docs.deepseek.com/guides/thinking_mode/ — thinking is on by default, and the `{"thinking":{"type":"enabled|disabled"}}` toggle. - https://api-docs.deepseek.com/quick_start/pricing/ — the `deepseek-flash` peak/off-peak rate table and peak hours, for the cost section (with the best-effort caveat). - https://api-docs.deepseek.com/quick_start/error_codes/ — the status codes whose hints the client surfaces. - https://api-docs.deepseek.com/api/create-chat-completion/ — the `usage` fields, for the token/cost section. **`docs/reference/image-size/`** - https://www.npmjs.com/package/image-size — the formats `image-size` detects and the `type` values, relevant to the "which formats are accepted" wording. ## Implementation Details Create `extensions/vision/README.md` with these sections, in this order (from plan §13): 1. **What it does and when the agent should use it** — one short paragraph plus a sentence on when the current model cannot read an image. 2. **Requirements** — `DEEPSEEK_API_KEY`; state plainly that the tool is absent (not erroring) without it. 3. **Environment variables** — a table with Variable / Required / Default / Meaning for `DEEPSEEK_API_KEY`, `VISION_MODEL`, `VISION_BASE_URL`, `VISION_MAX_TOKENS`, `VISION_TIMEOUT`, `VISION_THINKING`, matching `src/config.ts`. 4. **Usage example** — a realistic agent call (`prompt`, `images`, optional `detail`/`thinking`) and what comes back (text + `details` + `usage`). 5. **Limits and validation** — the DeepSeek numbers that `src/images.ts` enforces (formats, 32 MiB per image, 48 MiB body, 600 images, 8192 px / 4096 px at ≥ 15 images) and the fact that failures name the offending file/limit. 6. **Thinking mode** — off by default; retry with `thinking: true`; raise `VISION_MAX_TOKENS` when enabling it because reasoning tokens count toward the cap. 7. **Failure behaviour** — failures throw a `ToolError` with an actionable message; never a stack trace. 8. **Cost** — the peak/off-peak rate table for `deepseek-flash` with a clearly-labelled best-effort note against DeepSeek's published prices. 9. **Non-goals** — image generation/editing, `http(s)` URLs, the Files API, caching, multi-turn state, streaming, per-call model override. 10. **Development** — `npm test` (note that tests never hit the network) and the manual live-verification command for a real key. Style: match the sibling extension READMEs (heading levels, table formatting, code fences with `bash`/`json` language tags). Use the em-dash style already used across the repo's docs. Do not invent flags or env vars that `src/config.ts` does not read. ## Acceptance Criteria - [ ] `extensions/vision/README.md` exists with all 10 sections, in the order listed above. - [ ] The environment-variable table matches `src/config.ts` exactly (names, defaults, required/optional). - [ ] The limits section states DeepSeek's actual numbers and matches what `src/images.ts` enforces. - [ ] The cost section carries the peak/off-peak table **and** an explicit best-effort caveat linking the pricing page. - [ ] The non-goals section lists the plan's confirmed out-of-scope items. - [ ] The development section gives `npm test` and notes tests never hit the network, plus the manual live command. - [ ] No env var or parameter is documented that the implementation does not support. ## Test Plan Documentation review — no code to run. Verify the README against the code: ```bash cd /Users/david/Projects/pi-extensions-and-skills # every env var the README documents is read by config.ts grep -o "VISION_[A-Z_]*\|DEEPSEEK_API_KEY" extensions/vision/README.md | sort -u grep -o "VISION_[A-Z_]*\|DEEPSEEK_API_KEY" extensions/vision/src/config.ts | sort -u ``` Expected: the two sets match exactly. ```bash npm test ``` Expected: unaffected by this change and still green. Manual read-through: confirm each of the 10 numbered sections is present and its claims can be traced to the listed source files.

david added this to the Vision: M7 - Packaging and documentation milestone

2026-09-17 03:34:58 +00:00

david added the

feature

label

2026-09-17 03:34:58 +00:00

david self-assigned this

2026-09-17 03:34:58 +00:00

david referenced this issue

2026-09-17 03:35:09 +00:00

List the vision extension in the repo root README #263

david referenced this issue from a pull request that will close it,