# TOOLS_ARCHIVE.md — Detailed Reference Material

## DocIngest — Knowledge Base (Detailed)

### What runs where

| Step | Who does it | Model/Service |
|------|-------------|---------------|
| Text extraction (PDF text layer) | FastAPI backend | PyMuPDF — direct Unicode extraction |
| Text extraction (scanned pages) | FastAPI backend | Tesseract OCR, `lang=eng+lat+ell` |
| Chunking | FastAPI backend | 400 words/chunk, 50-word overlap |
| Embedding (ingest) | FastAPI → Ollama | `nomic-embed-text` (local, 768-dim vectors) |
| Vector storage | FastAPI → PostgreSQL | `pgvector`, table `conductor.document_chunks` |
| Embedding (query) | FastAPI → Ollama | Same `nomic-embed-text` model |
| Similarity search | PostgreSQL | Cosine distance (`<=>` operator), threshold ≥ 0.4 |
| Synthesizing an answer | Conductor | **Sonnet API** — not the local model |

**The local Ollama model only handles embedding.** All reasoning, synthesis, and the decision to search in the first place is Sonnet.

**Query:** Conductor calls `POST /api/docingest/search` → FastAPI embeds via Ollama → pgvector cosine search → Sonnet synthesizes answer with chunks as context.

**Ingest:** Drop file on Dashboard → PyMuPDF extract (Tesseract OCR fallback) → 400-word chunks → Ollama embed → pgvector. Status: queued → processing → done/error.

### Notes

- **Cost:** zero for ingest/search (local Ollama). Only Conductor's synthesis uses Sonnet API.
- **OCR:** `eng+lat+ell`. Polytonic Greek supported.
- **Chunk size:** 400 words; `nomic-embed-text` 2048-token limit.
- **Delete** removes doc + all chunks. **Duplicate** (same SHA-256) returns existing doc.
- **When to search:** before *any* factual, language, grammar, historical, or reference question. See AGENTS.md.

## OpenClaw Gateway Config (Detailed)

**Real config location:** `/var/lib/docker/volumes/openclaw_config/_data/openclaw.json`
**Dashboard:** `https://openclaw.nerdbox.com`
**Gateway container:** `openclaw-openclaw-gateway-1` (port 18789)

### Changing a channel's model
ALWAYS `docker stop` gateway before editing `sessions.json` — it holds the file in memory.

### Local model (llama3.2:3b-lowctx) — context limit warning

**Hard limit: 16,384 tokens.** If a session's context exceeds this when switching to the local model, Ollama will fail silently ("fetch failed") and leave a stale lock file.

- **Safe threshold:** ~12k tokens. Above that, warn before switching.
- **Recovery:** stale locks are auto-cleared every 5 min by `scripts/clear_stale_locks.sh` (crontab).
- **Before switching to local in a long session:** run `/reset` in the channel first, then `/model ollama/llama3.2:3b-lowctx`.
- **Clearing a stuck override manually:** `docker stop gateway` → edit `sessions.json`, remove `providerOverride`/`modelOverride` fields → `docker start gateway`.

### Browser / Playwright
- Chromium at `/home/node/.cache/ms-playwright` (`PLAYWRIGHT_BROWSERS_PATH` set in openclaw.json)
- Always use `profile="openclaw"` — never `profile="chrome"` (requires physical tab)
- Always `navigate` before `screenshot` — `screenshot` does NOT navigate by URL