docs(ocr): bundled setup guide for the local vision endpoint (Ollama/LM Studio) #6
No reviewers
Labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
daniel/obsidian-remarkable-round-trip!6
Loading…
Reference in a new issue
No description provided.
Delete branch "agent/ocr-endpoint-setup-docs"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Part of #3 (Part of #2). Docs-only, zero code risk — safe to land first.
What to do
Add a bundled setup guide that removes the first-read friction for the vision-model endpoint path, and link it from the two places a user looks.
1. New file
docs/ocr-endpoint-setup.mdSibling to the existing
docs/ocr-corrections.md(match its tone — calm, second-person, concrete commands). Cover, in this order:ollama pull qwen2.5vl:7b(the plugin's default model).Originis Obsidian'sapp://obsidian.mdunless you allow it. SetOLLAMA_ORIGINS=app://obsidian.md(orOLLAMA_ORIGINS=*for any origin) in Ollama's environment, then restart Ollama. Show how to set it per-OS: macOSlaunchctl setenv OLLAMA_ORIGINS "app://obsidian.md"(then restart the app); Linux systemdsystemctl edit ollama.service→Environment="OLLAMA_ORIGINS=app://obsidian.md"; Windows via Edit the system environment variables. MentionOLLAMA_HOSTonly if the server must listen on a non-default address (e.g. a server on the LAN); for localhost the default127.0.0.1:11434is fine.http://localhost:11434/v1, Modelqwen2.5vl:7b, API key empty.agent/ocr-endpoint-test-connection) — or, as a fallback that works today,curl http://localhost:11434/v1/modelsto confirm the server answers and the model is listed.http://localhost:1234/v1), enable the OpenAI-compatible server, use that endpoint + the model id LM Studio shows. Note LM Studio does not need an origin allowlist the way Ollama does.OLLAMA_ORIGINS), 404 on /v1/chat/completions (endpoint missing the/v1suffix, or not an OpenAI-compatible route), model not found (not pulled →ollama pull …, or wrong tag).2. Link it from the README
In
README.md, in the OCR section at the Vision model endpoint bullet (~L171), add a sentence/link: "First time? See the endpoint setup guide."3. Link it from the settings note
In
src/settingschema.ts, the "Reading handwriting (OCR)" sectionnote(L397–405) ends describing the vision endpoint. Append one short sentence pointing to the guide, e.g. "First-time endpoint setup (Ollama/LM Studio): see docs/ocr-endpoint-setup.md." Keep it a plain-text mention (the note renders as text, so a bare relative path is fine — do not invent a markdown link control).Why
Issue #2 reports the endpoint path is "untested because of setup difficulties." The dominant blocker is the Ollama origin/CORS allowlist, which is invisible until a request silently fails. A bundled guide is the lowest-risk half of #3 and gives users a path to a first successful read.
Scope boundary (do NOT do here)
transcribe()error-mapping, and the newocr.tshelpers are the sibling MR onagent/ocr-endpoint-test-connection— do not implement them here.Validation contract
nix develop -c npx vitest run src/__tests__→ PASS. The settings-note change is a plain string edit;settingschema.test.tsasserts schema keys/visibility, not note text, so it stays green. Confirm no snapshot test pins the note string (grep the tests for a fragment of the note before/after).docs/ocr-endpoint-setup.md.✅ Agent run completed
2m54s · 21 turns · $1.25 · pushed
agent/ocr-endpoint-setup-docs· session saved — new comments resume this runclaude referenced this pull request2026-10-20 15:18:28 +02:00
What changed
docs/ocr-endpoint-setup.md— first-time setup guide for the vision-model endpoint: local-first note, Ollama step-by-step (pullqwen2.5vl:7b, the per-OSOLLAMA_ORIGINSorigin/CORS gotcha, plugin settings, verify), LM Studio equivalent, and a symptom→fix troubleshooting table.README.md(Vision model endpoint bullet) and the "Reading handwriting (OCR)" settingsnoteinsrc/settingschema.tseach gained one line pointing to the guide. No behaviour change — the note edit is a plain-string append (renders as text, bare relative path as instructed).Verify
npx vitest run src/__tests__→ 653 pass / 0 fail;tsc -noEmit -skipLibCheck→ clean. Confirmed no snapshot test pins the note string (greppedsrc/__tests__for note fragments — no match). No pipeline has run for the head SHA yet; the only recent CI run is a pre-existingfailureonmain, unrelated to this diff.Follow-ups
transcribe()error-mapping, andocr.tshelpers are intentionally out of scope here — they land in the sibling MR onagent/ocr-endpoint-test-connection. The guide references Test connection as the primary verify step with acurl .../v1/modelsfallback that works today.claude referenced this pull request2026-10-20 15:21:52 +02:00
claude referenced this pull request2026-10-20 16:34:09 +02:00
claude referenced this pull request2026-10-20 16:34:09 +02:00
claude referenced this pull request2026-10-20 18:57:21 +02:00
claude referenced this pull request2026-10-20 18:57:24 +02:00
claude referenced this pull request2026-10-20 19:02:05 +02:00
claude referenced this pull request2026-10-20 19:02:19 +02:00
claude referenced this pull request2026-10-20 19:02:19 +02:00