Local embeddings: on-device model as the default — complete epic (all platforms, field-tested)

[NestorCanales]

What this is

The complete local-embeddings epic, consolidated into one branch per your review-workflow preference: the app now works fully offline with no API key — a bundled on-device model (multilingual-e5-small, int8 ONNX) is the default embedding provider on every shipping platform. OpenAI remains an explicit opt-in.

Everything is in this one branch: Phases 0–6 plus all fixes discovered during verification (previously drafts #3, #4, #5, #6, #7, #8, #9, #10 — all closed pointing here).

Guided tour (suggested reading order)

1. Documentation/Epics/local-embeddings.md — the whole story: research, phase-by-phase execution notes, platform matrix, field-test findings, measured numbers, and two parked product questions (Phase 6 notes).
2. Documentation/Bugs/local-embed-token-budget-overflow.md — the critical find: every multi-chunk file (>~1.7 KB) silently failed to embed on all platforms; caught by a real-vault field test, fixed with a permanent regression test.
3. Documentation/Bugs/fswatcher-create-event-swallowed-linux.md + Documentation/windows-build.md — the other bug report and the Windows build/artifact provenance.

What's included

• Interface + pipeline: EmbedDocuments/EmbedQuery split, chunker tokenizer seam, local ONNX embedder package (internal/embeddings/local, CGo behind the localembed tag — plain go test ./... stays native-lib-free)
• Provider system: local is default, OpenAI opt-in, provider switching with re-index, fingerprint safety, provider-aware thresholds; keyless onboarding UI
• All five targets: macOS arm64 + x86_64, Linux arm64 + x64, Windows x64 — per-platform go:embed of the ONNX runtime, make assets manifest (SHA-256-pinned), two self-hosted native artifacts in this repo's releases (mac-Intel ORT source build; Windows tokenizer lib source build — recipes in release notes)
• Fixes found during verification: token-budget overflow (critical, cross-platform); watcher create-events swallowed (verified on 3 OSes); index failures invisible in the Log page; Windows close-window zombie instances; arch-namespaced asset extraction; darwin-guarded tray; per-OS Claude Desktop config path

Verification

• Automated suites green on all platforms (untagged suite stays native-lib-free; tagged integration includes a large-document regression)
• Field tests on real hardware: Windows — real 109-file vault indexed (105 files / 932 chunks / 0 errors after the fix), real semantic searches through Claude Desktop; Linux x64 (Pop!_OS 24.04) — GUI onboarding, indexing, search verified on-device
• Offline proof: --network none container runs index+search correctly; cross-platform vector compatibility confirmed (mac-indexed DB searched on Linux/Windows)
• Consolidated branch: full suite + vet + tagged integration + make build re-run green after the merges

🤖 Generated with Claude Code

[theBoEffect]

Regarding this question: "One thing I'd love your input on: for existing OpenAI users upgrading, I chose to keep them on OpenAI (preserving their index) rather than switch them to local and prompt a re-index. I took the safer route, but I may have read the fingerprint section differently than you intended — very happy to change it if you'd prefer."

I would say, this isn't a widely used product and its not a SaaS solution, its a local desktop app. So we don't need to think about migration. I don't know what preserving the index from OpenAI and then adding the new one does. If it works fine, great! But if not, we may just want to reindex and thats ok. The main goal is to get away form OpenAI as the default though.

[theBoEffect]

The isolation to /local makes sense and organizes things nicely.
Would you like me to start running this locally and do an architectural pass or wait till you finish the epic and test it all together? It may be easier to review once the interfaces are in place.

[NestorCanales]

Thanks Bo! Two quick things.

On the migration question: got it, I'll keep it simple. Local stays the default, and if an index ever mismatches we'll just re-index. No heavy migration logic.

On timing: since your comment I finished Phase 4 (keyless onboarding, a Local/OpenAI toggle in Settings, and updated docs), so this PR is now the full macOS version, Phases 0 through 4. It's working and tested end to end through Claude Desktop, so the interfaces and UI are all in place. Probably a good point for your architectural pass whenever you get a chance. I'll do the cross-platform work (Phase 5) as a separate PR.

Also bumped the PR title to reflect 0 through 4.

[theBoEffect]

Excellent work on this epic — the review found the architecture discipline, build-tag isolation, asset pipeline, and inference math all solid, and everything verified locally on this end: full untagged suite green, tagged integration suite (real model, incl. the large-document regression) green, go vet clean, make build clean, GUI launches with the keyless local default, and a real offline semantic search through stdio MCP works end-to-end. The field-testing rigor shows.

The inline comments below are what I'd like addressed before merge. The first (shutdown during scan) is the one true blocker; the rest are small. One additional nit that has no diff line to anchor to: an empty search result set serializes as null — [] would be kinder to strict JSON clients.

---

One more thing — a new epic to define (not build) in this PR

The close=quit fix you made for Windows/Linux is the right triage for the zombie-instance bug, but it leaves those platforms with a real product gap: the app only watches and indexes while the window is open. On macOS the tray keeps us resident in the background; on Windows/Linux, closing the window now stops watching entirely (stdio search keeps working, but the index goes stale until the next launch). Windows has a first-class notification-area/tray pattern for exactly this — the limitation is only that our tray.go is darwin-only Objective-C.

I'd like you to add an epic definition to this PR — just the document, not the implementation — and take it on as your next piece of work after this merges. Suggested name: background-presence (Documentation/Epics/background-presence.md). Rough scope to capture in it:

• Cross-platform tray/notification-area icon (likely fyne-io/systray; evaluate its message-loop integration with Wails v2) with Show/Quit, restoring hide-on-close on platforms that have it
• Start-on-login option (per-OS: Login Items / registry Run key / XDG autostart)
• Linux reality check: tray support varies by desktop environment (appindicator vs legacy); document what we target and what degrades to close=quit
• Single-instance guard so the zombie-stacking class of bug is structurally impossible regardless of tray state
• Keep the current close=quit as the documented fallback wherever a tray isn't available

Follow the same epic conventions as local-embeddings (Execution Notes, phase gates, record deviations in the doc).

🤖 Review drafted with Claude Code

[theBoEffect]

Blocking: shutdown during the initial scan can silently orphan files.

This change is correct (hide-with-no-tray left unreachable zombie instances — good catch in the field test), but it makes "app quits while initialScan is running" a routine event on Windows/Linux, and the shutdown path isn't safe against it:

1. app.shutdown calls engine.Close() but never engine.Stop(), so stopCh is never closed and the scan goroutine keeps indexing while the store shuts down under it.
2. IndexFile steps 9–11 (remove old chunks → upsert file row with the new hash → insert chunks) are three separate implicit transactions. If the process dies between steps 10 and 11, the DB permanently records the file as indexed at the current hash with zero chunks.
3. The hash short-circuit (engine.go:227) then skips that file on every future scan — silently unsearchable forever, no error, no log row. For a re-indexed file it's worse: step 9 already deleted the old chunks, so previously-searchable content vanishes.

Two-part fix, please: call engine.Stop() before engine.Close() in app.shutdown (orderly cancel at a file boundary), and wrap steps 9–11 in a single transaction so even a mid-file process death leaves the file either fully indexed or untouched-and-retryable. The transaction is the part that actually guarantees correctness (this race pre-dates your PR via macOS tray-Quit; your change just promotes it from rare to routine, so now's the time).

[theBoEffect]

Surfacing index failures in the activity log is a real improvement — but as written the log grows without bound and this line self-amplifies.

A failed file never persists a hash (that only happens on success at step 10), so every launch re-runs the pipeline and appends the identical error row again — your own field test's 79 failing files would mean ~79 new rows per launch, forever. Nothing prunes activity_log except Reset(), and the Log page polls ListLogEntries every 3s, which opens with SELECT COUNT(*) over the whole table on the MaxOpenConns=1 connection — so the growing table is paid for continuously, in contention with indexing writes.

Requested: (a) retention on the table — a TTL prune and/or row cap, applied at startup or on write; (b) dedupe the self-feeding source — log a failure only on first occurrence or state change per path (or update a last-seen timestamp instead of appending).

[theBoEffect]

Extract failures double-log, and this logging is copy-pasted at four call sites.

IndexFile already logs extraction failures internally (engine.go:234) and then returns the error — so this line (and its three siblings at 626, 731, 748) logs the same failure a second time: two Log rows per corrupt PDF/docx, the most common real-world failure class, while every other failure class gets one. And because the logging lives in the callers, any future IndexFile caller silently regresses to stderr-only.

Suggest logging the error exactly once inside IndexFile (or an indexAndLog wrapper), deleting the four caller-side copies and the line-234 special case.

[theBoEffect]

This regression test never exercises initialScan — the exact path of the motivating incident.

The Windows field-test failure this fixes ("79 of 105 files dropped with zero signal") happened during the startup scan, but the test only covers other callers — deleting the logActivity line from initialScan leaves the suite green. Coverage is cheap from here: stub ListDirectoriesFn to return a temp dir (as done elsewhere in this file) and call eng.initialScan() directly — it's synchronous when called directly.

[theBoEffect]

The merge fix is correct and well-reasoned — but its test coverage is platform-dependent.

TestOnCreate catches a regression only on OSes that emit the CREATE-then-WRITE double event; on macOS it passes with or without this fix, so the primary dev environment can't detect a regression. Please add a small deterministic test that drives debounce directly with a Create followed by a Write for the same path and asserts OnCreate (not OnModify) fires — that pins the behavior on every platform. Worth covering the delete-wins precedence the same way.

[theBoEffect]

Unrecorded deviation from the epic: dimension-only guard instead of the specified fingerprint.

The epic (Phase 3c table) specifies an embedding_fingerprint (provider:model:dimensions) written per index run and checked at GUI startup; what shipped is embedding_dimension, checked only here in the read-only path. The simplification is defensible today — the two providers happen to differ in dimension, and provider switches always go through Reset() — but dimension can't detect a same-width model swap, and our own named upgrade candidate (Granite 97m) is also 384-dim. The day the default local model changes, this guard is blind and mixed vectors return silently garbage-ranked results — exactly what the fingerprint was designed to catch.

Requested (cheap): store the full fingerprint string in this same config slot — identical plumbing, strictly more information — and record the decision in the epic doc either way, per its own "update the tables, don't silently diverge" rule (Phases 2 and 5 both did this well).

[theBoEffect]

Polish (non-blocking): main.go's HideWindowOnClose: runtime.GOOS == "darwin" re-derives the "has tray" fact that the build tags on tray.go/tray_stub.go already own — two places that must agree with nothing enforcing it. A const hasTray = true/false declared in each tagged file and used as HideWindowOnClose: hasTray makes drift impossible (and drops main.go's only use of the runtime import). This also sets up the background-presence epic cleanly — the tray implementation becomes the single owner of that fact per platform.

[theBoEffect]

Btw, try the /code-review skill next time. Thats what I used :)

[theBoEffect]

Second epic to define (again: definition only, not built in this PR) — metadata filters for MCP search

Alongside background-presence, please add one more epic definition doc to this PR and queue it behind that work. Suggested name: mcp-search-filters (Documentation/Epics/mcp-search-filters.md).

What it does: the MCP search tool (stdio and HTTP) gains optional filter parameters that constrain results by file metadata, so a caller can ask things like "search only my markdown notes," "only files under this directory," or "only files modified in the last month" instead of filtering client-side after the fact.

User-set constraints to record in the epic (settled, don't relitigate):

• Filesystem-tier metadata only: path/glob, file type/extension, watched directory, file modified time, file size, indexed-at time. Document-embedded properties (title/author/created from docx/pdf/etc.) are explicitly out of scope for this epic — worth a parking-lot note, nothing more.
• MCP surface only: both transports' search tool schemas. No GUI search work.
• Definition merged in this PR; implementation comes later, sequenced after background-presence unless Bo reorders.

Current-state notes for your research section (verified against this branch):

• The files table today carries only path, hash, indexed_at, directory_id — no mtime, size, or type column. Filters on modified-time/size need columns captured at index time, which implies a migration and a decision about backfill (existing rows lack the data until re-index — cheap here since os.Stat at next scan can backfill without re-embedding).
• The key design question is how filtering composes with the KNN query in store.Search: sqlite-vec vec0 KNN doesn't trivially JOIN-filter. Research the options — over-fetching then filtering in SQL/Go vs. sqlite-vec's newer metadata-column/partition-key support in vec0 tables — and record the measured trade-off in the epic the way local-embeddings recorded its Phase 0 numbers. Getting limit/offset/threshold semantics right post-filter matters (a filter that eats 90% of neighbors shouldn't return 1 result because the over-fetch was too small).
• Filter params should flow through domain.SearchParams so engine/readonly/store stay interface-clean; tool schemas in internal/mcp/server.go are the only delivery-layer touch.

Follow the same epic conventions (Execution Notes, phase gates with Verify, record deviations in the doc).

🤖 Drafted with Claude Code

[theBoEffect]

Field confirmation of your PDF passthrough bug — please schedule the fix

Bo hit Documentation/Bugs/pdf-extraction-passthrough.md in the wild on his real vault: for every indexed PDF (five checked, spanning PDF versions 1.3–1.6 and multiple producers, including Skia-generated ones), chunk 0's stored content is the raw PDF byte stream — %PDF-1.x, object dictionaries, /Filter /FlateDecode, compressed stream noise — exactly the passthrough your report diagnosed.

Good find in Phase 0 — and now that the local model makes indexing free, every one of these burns CPU to embed noise and pollutes search results. Please pick this up as a proper fix task (separate PR is fine, per your report's own scoping): real PDF text extraction via a pure-Go library, plus a unit test with a small sample PDF.

One trap your report doesn't cover — the fix must force re-extraction. IndexFile skips any file whose content hash is unchanged (engine.go:227), and fixing the extractor doesn't change file hashes — so a naive fix silently never applies to already-indexed PDFs; the garbage chunks stay forever. The fix needs a mechanism to invalidate previously-extracted content when extraction logic changes — e.g., an extractor-version column on files checked alongside the hash, or a one-time purge of .pdf file rows on upgrade. Please include that mechanism (and a regression test for it) in the fix — it's the difference between fixing new indexes and fixing everyone's existing index.

Priority-wise: slot it with Bo, but it's likely ahead of the epic queue — it's small, and it's a correctness hole in the product's headline feature.

🤖 Drafted with Claude Code

[theBoEffect]

Two more field findings from Bo's live usage (via Claude Desktop / stdio MCP)

1. index_status progress reporting is structurally dead over stdio — and the tool schema promises it works.

Observed: while the GUI was actively mid-index (file and chunk totals visibly climbing poll over poll), repeated index_status calls through Claude Desktop returned IsIndexing: false and IndexedFiles/TotalToIndex: 0/0 every single time. So an MCP client cannot distinguish "index is settled" from "index is mid-run," and can't show progress. This had a real cost during debugging: it made "PDFs are broken" indistinguishable from "PDFs just haven't been indexed yet."

Root cause (pre-existing, not introduced by this PR): the progress fields live only in the GUI process's memory — Engine.Stats() overlays eng.indexing / eng.indexedFiles / eng.totalToIndex (engine.go:508–517), and nothing ever persists them. The stdio process's ReadOnlyEngine.Stats() (readonly.go:64) can only read the store, and hard-codes IsIndexing = false (readonly.go:72) — the comment there shows this was a known limitation, but the index_status tool description still advertises a "currently indexing flag," so the contract overpromises what stdio can deliver.

Suggested fix shape (your design call): persist progress the same way watcher_running already is — the engine writes an indexing-state record to the config table (running flag + indexed/total counters + a heartbeat timestamp, updated every N files, cleared on completion), and ReadOnlyEngine.Stats() reads it, treating a stale heartbeat (e.g., > 30s old) as not-indexing so a crashed GUI can't leave the flag stuck on. The per-file config write is noise next to the chunk inserts already happening. Please also make the shutdown path clear the state — which ties into the Stop()-before-Close() fix from the review.

Schedule with Bo alongside the PDF fix — same class: pre-existing, field-found, hurts the MCP consumer experience directly.

2. Upgrading the review-body nit to a requested fix: search returns null for an empty result set.

Bo hit it in practice: a tight threshold legitimately excluded all results (filtering itself was correct), and the tool returned literal null instead of []. A null where clients expect an array throws on .length / for...of — please make empty results serialize as [] in this PR's revision round. Likely one-liner: the nil slice from the store/engine marshals as null; return a non-nil empty slice (or normalize at the MCP dispatch layer for both transports).

🤖 Drafted with Claude Code

[theBoEffect]

Third epic to define (definition only, same drill) — multi-representation indexing (dual-vector chunks)

One more epic definition to add to this PR's docs and queue. Suggested name: multi-representation-indexing (Documentation/Epics/multi-representation-indexing.md).

Problem (verified against this branch): a chunk's one content currently serves two conflicting jobs — the text we embed and the text we return. .html/.htm are in the extractor's textExtensions (raw passthrough), so an HTML chunk's vector substantially describes class names and tags (text-slate-800, border-collapse) rather than what the page says — findable only by markup-shaped queries. Stripping tags before embedding is wrong the other way: for source files the markup is the artifact, and a code-shaped query should match raw and get raw back. Any per-file "document or code?" classification has no right answer.

Proposed shape (design input for you to validate in the epic, not settled): decouple embedded text from stored text — allow up to two vectors per chunk, both pointing at the same stored raw payload:

• vector A = embed(raw chunk) — matches code/markup-shaped queries
• vector B = embed(extracted text of that chunk) — matches prose queries about the rendered content
• Emission is measurable, not taxonomic: at index time compare extracted length to raw length. Ratio near 1 (prose: md/txt/docx) → one vector from raw, exactly today's behavior, no regression. Extracted ≪ raw (html/svg/ipynb) → both vectors. Extraction ≈ nothing (minified bundles, base64) → one raw vector + a file-level summary chunk (path, type, title/headings outline) — the same shape as the ZIP metadata stub the extractor already emits.
• Extraction stays deterministic and free: for HTML, walk text nodes + structural landmarks (<title>, headings, alt, aria-label, link/button labels) via golang.org/x/net/html. No LLM, no per-file cost.

Binding constraints: files on disk are never modified; search returns raw content by default (existing callers unchanged; an optional include_extracted response field is fine); no LLM in the pipeline; the extra embed/vector cost lands on local compute and is accepted (~10–15% vector growth in a mostly-prose corpus).

Things the epic must work out (the real design content):

1. Schema: chunk_embeddings is vec0(chunk_id INTEGER PRIMARY KEY, embedding FLOAT[dim]) — strictly one vector per chunk today. Two vectors per chunk means a synthetic embedding id with a (chunk_id, representation) mapping — via an aux table or sqlite-vec's metadata/auxiliary columns — plus migration/Reset changes.
2. Search semantics: KNN now returns embedding rows, not chunks — results must dedupe to one row per chunk keeping the best score, which forces over-fetch before limit/offset/threshold apply. This is the same post-KNN machinery mcp-search-filters needs — whichever epic lands second inherits the first's design; consider designing store.Search's post-processing once for both.
3. Pairing granularity — the subtlest question: chunk boundaries are computed on raw text, so "the extracted text of chunk 42" means extracting from a raw HTML fragment (x/net/html tolerates fragments, but verify landmark quality mid-document), vs. the alternative of two parallel chunkings of the file with looser file-level pairing. Spike this first; it decides the data model.
4. Threshold interplay: raw-vector and extracted-vector distances for the same chunk will distribute differently; confirm the provider-aware default threshold behaves sensibly when both representations compete.

Sequencing: the PDF extraction fix (previous comment) is a hard prerequisite — same mechanism, and PDFs become "embed extracted, store extracted" with no raw vector (nobody queries for /Filter /FlateDecode). Slot the rest with Bo.

🤖 Drafted with Claude Code

[theBoEffect]

Review wrap-up — one index of everything on this PR

Since the feedback landed across a review and several comments, here's the consolidated list. Details live in the linked items; this is the checklist.

For this PR's revision round

Blocking

1. Shutdown-during-scan data loss — engine.Stop() before Close() + one transaction around IndexFile's remove/upsert/insert (inline comment on main.go:201).

Requested
2. Activity log retention (TTL/cap) + dedupe of repeat failures per path (engine.go:626).
3. Consolidate error logging into IndexFile; kill the double-log at the four call sites (engine.go:480).
4. Cover initialScan in the error-logging regression test (engine_test.go:626).
5. Deterministic cross-platform test for the watcher Create+Write merge (fswatcher.go:135).
6. Full embedding_fingerprint instead of dimension-only guard; record the deviation in the epic (readonly.go:44).
7. search empty results: return [], not null (upgraded from nit — Bo hit it in the field; likely a one-line nil-slice fix at the source or dispatch layer).

Polish (optional)
8. const hasTray in the tray build-tag pair instead of runtime.GOOS == "darwin" in main.go (tray_stub.go:7).

Docs to add to this PR (definition only — no implementation)
9. Documentation/Epics/background-presence.md — Windows/Linux tray + start-on-login + single-instance guard (scope in the review body).
10. Documentation/Epics/mcp-search-filters.md — filesystem-tier metadata filters on the MCP search tool (scope + constraints in comment).
11. Documentation/Epics/multi-representation-indexing.md — dual-vector chunks for markup-heavy formats (scope + design questions in comment).

Scheduled after merge (separate PRs, slot priorities with Bo)

• PDF extraction fix — real text extraction + the re-index invalidation mechanism (extractor-version or purge) + regression test. Likely first: it's small, it's a correctness hole in the headline feature, and it's a hard prerequisite for epic #11.
• Persisted index progress — progress state written to config with a heartbeat so index_status over stdio stops reporting a dead false/0/0; also fixes the tool schema's overpromise.
• Epic queue — suggested order: background-presence → mcp-search-filters → multi-representation-indexing. Note fix(embeddings): token budget overflow — every multi-chunk file failed to embed [stacks on #7] #10 and #11 share the post-KNN over-fetch/dedupe machinery in store.Search; whichever you build first, design that piece for both.

Nothing else outstanding from this review. Once the revision round lands, ping and we'll re-verify the same way (full suites, tagged integration, build, live run). Thanks again — the field-test discipline on this PR set a high bar.

🤖 Drafted with Claude Code

[NestorCanales]

Revision round complete — checklist → commits

Everything from the review is addressed; full suites + tagged integration + make build + -race (engine/watcher) green on the branch.

Review item	Commit
1. Blocker: shutdown-during-scan — Stop() before Close() and the remove/upsert/insert sequence is now ONE transaction (store.UpsertFileWithChunks); Stop() also waits for the in-flight file. Regression tests: mid-transaction failure leaves the previous entry fully searchable; Stop() blocks until the file boundary	df97e90
2. Activity log retention + dedupe — 30-day TTL + 5000-row cap at store open; error rows are per-path upserts	a8b4db9, hardened in 36df4be
3. Error logging consolidated inside IndexFile (4 caller copies + line-234 special case removed)	a8b4db9
4. initialScan covered in the visibility regression test (+ asserts exactly-once)	a8b4db9
5. Deterministic watcher tests driving debounce() directly (create+write merge, write-alone, delete-wins)	5962d9f
6. Full embedding_fingerprint guard; deviation recorded in the epic	05936dc, hardened in 36df4be
7. Empty search results → [] (wire-contract test incl. offset-past-results)	a8b4db9
8. hasTray owned by the tray build-tag pair	388b930
9–11. Epic definitions: background-presence, mcp-search-filters, multi-representation-indexing	3252e03

Took your /code-review advice — it caught real things

Ran the skill over the revision round before pinging you. It found defects in my own new code, all fixed in 36df4be/5b34c15: the read-only fingerprint/threshold used a provider resolution that dropped the key-implies-openai fallback (rule now hoisted to embeddings.ResolveProvider + embeddings.Fingerprint, used by writer and checker); the log upsert didn't collapse pre-existing duplicate rows; the fingerprint wasn't recorded after onboarding's first index; a WaitGroup Add/Wait race in the watcher handlers; and the debounce merge mis-handled vim-style atomic saves (RENAME+CREATE in one window → OnDelete for a file that still exists — dispatch now stats the path first). Plus: N+1 delete inside the new transaction → single IN statement; UpsertFile/InsertChunks (now production-dead) trimmed from the interface.

Honest residuals the review surfaced (pre-existing — flagging, not fixed here)

1. Distance-metric semantics (worth a decision): chunk_embeddings is declared without distance_metric, so sqlite-vec returns L2, not cosine as comments claimed. Unit-norm vectors make ranking identical (L2 = √(2·cos_dist)), but the thresholds are therefore L2-scale: mE5 "related" ≈0.51–0.60, cross-lingual ≈0.58–0.66, unrelated ≈0.76. The local 0.6 cutoff truncates part of the cross-lingual band the epic targets. Options: declare distance_metric=cosine (table rebuild via existing Reset path) and keep 0.6, or retune the L2 value (~0.66–0.70). Comment now documents the real semantics either way.
2. Upgraded-DB startup is unguarded in the GUI/RW path: a 1536-wide table + a DB that resolves to local (no key stored) opens without any width/fingerprint check → every insert fails per-file with no rebuild path. Wants one startup reconciliation (actual vec-table width + fingerprint vs active embedder → existing Reset). Natural companion to the fingerprint work; happy to do as a follow-up PR.
3. Settings provider-switch flow: switching persists the provider before the embedder/chunker build or Reset can fail (a failed build can leave the app unable to start); and selecting OpenAI commits with an empty key (the key field renders after selection) → wipes the local index and re-embeds through 401s; saving the key afterwards doesn't rescan.
4. Smaller: chunk_overlap isn't clamped when the local provider clamps chunk size (a stored overlap ≥ 480 drives the chunker step to 1); Stats() returns empty provider/model for legacy DBs over --mcp; warm starts read all ~150MB embedded assets before the idempotent fast path can short-circuit and the tokenizer.json is parsed/held twice; ortInitErr under sync.Once makes a transient ORT init failure permanent.

Suggested slotting: #2 + #3 alongside the already-queued PDF-extraction and index-progress fixes; #1 is your call on metric vs threshold; #4 as opportunistic cleanups.

🤖 Generated with Claude Code