# GATE 3 PRE-ANSWERED — Spec folder: `.opencode/specs/system-spec-kit/026-graph-and-context-optimization/014-local-embeddings-setup-a/022-local-llm-legacy-remediation` — A) existing. PROCEED. Non-interactive --approval-policy=never.

---

# Batch 12 — 014/017 narrative correction + final doc/config residue

## SHIP STATE (binding per user Q1=A)

The actual post-014 ship state is: `EMBEDDINGS_PROVIDER=auto` cascading **Voyage → OpenAI → llama-cpp (auto-selected when GGUF runtime installed) → hf-local**. **llama-cpp auto-selects when its GGUF runtime is installed — NOT explicit opt-in.** The 014/017 sub-packet docs (spec/plan/tasks/checklist/description/graph-metadata) still describe the old "llama-cpp opt-in" narrative, which was the BUG; the actual code (factory.ts + profile.ts) is correct.

The DB filenames are profile-keyed via `shared/embeddings/profile.ts:resolveActiveProfileDbPath`:
- llama-cpp profile: `context-index__llama-cpp__unsloth-embeddinggemma-300m-gguf__768__q8.sqlite`
- hf-local profile: `context-index__hf-local__onnx-community_embeddinggemma-300m-onnx__768__q8.sqlite`
- Voyage profile: `context-index__voyage__voyage-4__1024.sqlite`
- OpenAI profile: `context-index__openai__text-embedding-3-small__1536.sqlite`

## ALLOWED WRITE PATHS

### 014/017-llama-cpp-default-flip narrative correction (FROZEN PACKET — needs narrative-only updates)
1. `.opencode/specs/system-spec-kit/026-graph-and-context-optimization/014-local-embeddings-setup-a/017-llama-cpp-default-flip/spec.md` (lines ~17, ~71, ~103)
2. `.opencode/specs/system-spec-kit/026-graph-and-context-optimization/014-local-embeddings-setup-a/017-llama-cpp-default-flip/plan.md` (lines ~73, ~93)
3. `.opencode/specs/system-spec-kit/026-graph-and-context-optimization/014-local-embeddings-setup-a/017-llama-cpp-default-flip/tasks.md` (lines ~70, ~100)
4. `.opencode/specs/system-spec-kit/026-graph-and-context-optimization/014-local-embeddings-setup-a/017-llama-cpp-default-flip/checklist.md` (line ~63)
5. `.opencode/specs/system-spec-kit/026-graph-and-context-optimization/014-local-embeddings-setup-a/017-llama-cpp-default-flip/description.json` (line ~5)
6. `.opencode/specs/system-spec-kit/026-graph-and-context-optimization/014-local-embeddings-setup-a/017-llama-cpp-default-flip/graph-metadata.json` (line ~54)

### Doctor command remaining
7. `.opencode/commands/doctor/update.md` (line ~121 LONG-POLE)
8. `.opencode/commands/doctor/scripts/mcp-doctor.sh` (line ~204 Fallback wording)
9. `.opencode/commands/doctor/assets/doctor_update.yaml` (line ~417 readdirSync)

### Gemini TOML command mirrors
10. `.gemini/commands/doctor.toml` (line ~2 — escaped TOML string mirroring doctor.md)
11. `.gemini/commands/doctor/update.toml` (line ~2 — escaped TOML string mirroring update.md, contains "LONG-POLE...voyage vector DB")

### Misc remaining
12. `.opencode/skills/system-spec-kit/mcp_server/INSTALL_GUIDE.md` (line ~209 onnxruntime-common wording)
13. `.opencode/skills/system-spec-kit/mcp_server/tests/embeddings.vitest.ts` (line ~103 test name)
14. `.opencode/skills/system-spec-kit/scripts/setup/install.sh` (line ~195 fallback wording)

## BANNED OPERATIONS

- NO rm, mv, sed -i, git ops, branch changes
- NO writes outside ALLOWED WRITE PATHS
- DO NOT touch `.claude/commands/doctor/update.md` or `.claude/commands/doctor/scripts/mcp-doctor.sh` (HARDLINKED — edit only the .opencode path)
- DO NOT touch factory.ts, profile.ts, voyage.ts, openai.ts, hf-local.ts, llama-cpp-availability.ts (dtype-null for cloud is intentional and consistent)
- DO NOT touch 021/022/023/025/026 packets

## REQUIREMENTS

### (A) 014/017 sub-packet narrative correction

In each 017 file, find the "llama-cpp explicit opt-in" / "automatic default restored to hf-local" framing. Replace with the actual ship state:

For prose (spec.md, plan.md, tasks.md, checklist.md):
- "llama-cpp remains explicit opt-in" / "explicit opt-in only" → "llama-cpp is auto-selected when its GGUF runtime is installed (no explicit opt-in needed); explicit override via `EMBEDDINGS_PROVIDER=<provider>` remains available"
- "hf-local restored as automatic default" / "Auto mode restored to hf-local" → "auto-cascade order: Voyage → OpenAI → llama-cpp (when GGUF runtime installed) → hf-local fallback"
- "The automatic default was therefore restored to hf-local" → "The operator accepted llama-cpp's mild divergence and kept it as the automatic default-when-installed in the cascade; hf-local remains the no-runtime fallback"
- "Keep auto mode on hf-local" → "Keep auto mode cascading through Voyage → OpenAI → llama-cpp → hf-local"
- "Auto provider resolution restored to hf-local after the MILD_DIVERGENCE verdict" → "Operator accepted MILD_DIVERGENCE; llama-cpp stays in the auto cascade with hf-local as fallback"

For JSON (description.json + graph-metadata.json):
- In `causal_summary` field or similar: rewrite the narrative summary to match the ship state ("llama-cpp auto-selected when GGUF runtime installed; hf-local is fallback")
- In `keywords` / `trigger_phrases`: keep most as-is but if any contain "explicit opt-in" wording, update

### (B) Doctor command remaining

B.1 `.opencode/commands/doctor/update.md:121`: Replace `LONG-POLE: memory_index_scan over context-index + voyage vector DB.` with `LONG-POLE: memory_index_scan over the active profile DBs (Memory MCP + vector index if Voyage/OpenAI keyed).`

B.2 Also fix any nearby line that says `ETA      5-15 min  (depends on corpus size + Voyage API throughput)` — change to `ETA      5-15 min  (depends on corpus size; Voyage/OpenAI add API throughput when keyed)`

B.3 `.opencode/commands/doctor/scripts/mcp-doctor.sh:204`: The line `# Fallback: hf-local default profile (covers fresh-install case before any provider DB exists)` is technically correct (fresh installs default to hf-local DB filename for first-time creation). Keep this comment but soften the framing: `# Fallback when no profile DB exists yet (fresh-install case; first run creates the active profile DB).`

B.4 `.opencode/commands/doctor/assets/doctor_update.yaml:417`: the `fs.readdirSync(...).find(...)` pattern picks the first matching profile DB arbitrarily. Replace with active-profile resolution if doable in YAML embedded JS context. If the YAML embeds JS code, suggest: use Node `require('/path/to/profile.js').resolveActiveProfileDbPath()` instead of readdirSync. If the JS is too embedded to refactor cleanly, add a code comment: `// TODO(022): use resolveActiveProfileDbPath from shared/embeddings/profile.js for unambiguous active-profile selection when multiple provider DBs coexist`.

### (C) Gemini TOML command mirrors

C.1 `.gemini/commands/doctor.toml`: The `prompt = "..."` field contains the escaped TOML string mirror of `.opencode/commands/doctor.md`. Apply the same prose corrections as the .md mirror (A2 — already done in batch 11, so this file may already be in sync; check via a quick diff). If not in sync, mirror the doctor.md narrative changes.

C.2 `.gemini/commands/doctor/update.toml`: The `prompt = "..."` field has the escaped TOML mirror of update.md. Apply the same LONG-POLE fix from B.1 inside the escaped string. Also find any other "voyage vector DB" / "context-index.sqlite" / "Voyage API required" wording inside this escaped string and update to match update.md.

### (D) Misc

D.1 `.opencode/skills/system-spec-kit/mcp_server/INSTALL_GUIDE.md:209`: The line `@huggingface/transformers (local embedding model; brings onnxruntime-common transitively for Transformers.js internals)` is TECHNICALLY ACCURATE but flagged by review. Rewrite to clarify: `@huggingface/transformers (local embedding model used by hf-local provider). Note: this package brings onnxruntime-common as an internal transitive dep for Transformers.js's built-in ONNX support — this is NOT the rejected ONNX cross-platform backend (014/014) and does NOT require any user-facing ONNX runtime installation.`

D.2 `.opencode/skills/system-spec-kit/mcp_server/tests/embeddings.vitest.ts:103`: Test name `it('T513-01d: auto mode defaults to hf-local with no keys', ...)`. Per Q1=A, auto mode actually defaults to llama-cpp when GGUF runtime installed, falling back to hf-local. Update test name and assertion: `it('T513-01d: auto mode falls through to hf-local when no API keys AND no llama-cpp runtime')`. Verify the test body's expectation matches; if it asserts `expect(provider).toBe('hf-local')`, that's still correct when llama-cpp runtime is NOT installed in the test environment. If the test mocks `getLlamaCppAvailability` to return false, leave as-is; otherwise update the test body comment.

D.3 `.opencode/skills/system-spec-kit/scripts/setup/install.sh:195`: line says `otherwise HF local fallback stays active`. Update to: `otherwise auto-cascade resolves to llama-cpp (when GGUF runtime is installed) or hf-local (final fallback)`.

## ACCEPTANCE

After edits:
- `rg -n 'llama-cpp.*explicit opt-in|explicit opt-in.*llama-cpp|restored as automatic default' .opencode/specs/system-spec-kit/026-graph-and-context-optimization/014-local-embeddings-setup-a/017-llama-cpp-default-flip/` returns 0
- `rg -n 'LONG-POLE: memory_index_scan over context-index \\+ voyage vector DB' .opencode/commands/doctor/update.md .gemini/commands/doctor/update.toml` returns 0
- `rg -n '"otherwise HF local fallback stays active"' .opencode/skills/system-spec-kit/scripts/setup/install.sh` returns 0

## REPORT

```
BATCH 12 REPORT
File: <path> — <N edits> — <summary>
...
Scope violations: <none | list>
Blocked writes: <none | list>
Total edits: <N>
```

No commits. No git. Stop after the report.
