Docs + E2E: document OLLAMA_ORIGINS for localhost extension testing (planner-verify, dev harness)

[Ayush7614]

Problem

When running WebBrain as a browser extension against Ollama on localhost, LLM calls fail with 403 unless Ollama is started with extension origins allowed:

OLLAMA_ORIGINS="*" ollama serve
# or tighter:
OLLAMA_ORIGINS="chrome-extension://*,moz-extension://*" ollama serve

This is not a WebBrain planner bug — the browser sends Origin: chrome-extension://<id> (or moz-extension://…), which recent Ollama versions reject by default. Related: #33.

What breaks locally without this

• Manual extension testing with Ollama (Act mode, planner gate, etc.)
• New E2E verifier for planner v1 (test/planner-verify.mjs, npm run test:planner) — planner gate never emits plan_review because the planning LLM call 403s first
• npm run test:anonymous and node scripts/dev.mjs when Ollama is the configured provider

curl / terminal probes to http://localhost:11434 still work — only extension-origin requests are blocked.

Docs gap

1. README only says ollama serve + set base URL — no OLLAMA_ORIGINS mention (README.md ~line 69).
2. Website FAQ says localhost usually doesn't need CORS — true for normal web pages, misleading for extensions (extension origin ≠ http://localhost).
3. test/README.md documents test:anonymous but not test:planner or the Ollama prerequisite for any extension E2E run.
4. Code already surfaces a helpful 403 hint in src/chrome/src/providers/openai.js — but users hit it before reading docs.

Context

Discovered while validating planner v1 for #165 (PR #178). Unit tests pass (npm test — planner parse/format). Full headed E2E blocked until Ollama allows extension origins.

Proposed fixes

• README: add OLLAMA_ORIGINS to the Ollama quick-start block (Chrome + Firefox READMEs too)
• test/README.md: document npm run test:planner, headed Chromium requirement, and OLLAMA_ORIGINS prerequisite
• Website FAQ: clarify that browser extensions need OLLAMA_ORIGINS even when Ollama runs on the same machine as the browser
• Optional: scripts/dev.mjs / test runners print a one-line warning if a probe with Origin: chrome-extension://test gets 403 from configured Ollama URL
• Optional: link Ollama connection problem on firefox #33 ↔ this issue in a short maintainer note (403 detection + model dropdown tracked there)

Workaround (today)

Quit Ollama app if it holds port 11434, then:

OLLAMA_ORIGINS="*" ollama serve
npm run test:planner   # or node scripts/dev.mjs for manual testing

Environment

• macOS, Ollama desktop app default install
• Chrome MV3 extension (unpacked src/chrome/)
• Ollama OpenAI-compatible endpoint http://localhost:11434/v1

[Ayush7614]

cc: @esokullu

[esokullu]

sounds like this one needs another PR :)

[Ayush7614]

Validation update (while testing PR #178 / #165)

Confirmed locally on feat/planner-v1 (includes maintainer review fixes in 7b876d10):

What passes without Ollama E2E

• npm test — 429 passed, 0 failed
• Injection corpus — 60/60, including new check: planner prompt treats page context as untrusted data
• Maintainer review fixes covered by new unit tests:
  • abort during planner LLM call → stops before review card
  • approved plan appends to scratchpad (does not wipe existing pinned facts)

What still blocks full extension E2E

npm run test:planner (headed Chromium + auto-approve) fails with:

ollama error 403: Ollama rejected the extension origin

Probe with Origin: chrome-extension://test → 403 from default Ollama desktop app on localhost:11434. Terminal curl to the same endpoint works — only extension-origin requests are rejected.

Workaround from this issue works once Ollama is restarted with origins allowed:

OLLAMA_ORIGINS="*" ollama serve
npm run test:planner

Related notes

• Extension already surfaces a helpful 403 hint in openai.js — good UX, but users still hit it before reading docs (as noted above).
• Local unstaged fixes for plan_response (decision field) and await loadPlanBeforeAct() help manual “Approve & run” — separate from this docs issue but worth knowing for anyone testing the planner gate manually.

Happy to take the README / test/README.md doc updates from the proposed checklist if maintainers want a small follow-up PR after #178 lands.

cc @esokullu

[esokullu]

added to the website in the faq.

[esokullu]

closing it if you think that's enough, otherwise feel free to let me know or open a PR