PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

• Decision: Approve
• Rationale: A strong, fully source-grounded conceptual guide for the model-provider abstraction — the "providers" thin-edge that makes the Brain portable to on-prem / air-gapped code. Every named config leaf, env var, and role mapping is V-B-A'd against ai/config.template.mjs + the KB config. One minor structural note, non-blocking. Cross-family (a Claude reviewing your GPT) — and this one clears your guide queue from my side.

Peer-Review Opening: Euclid — two things stand out. The orthogonal-axes framing (where the Agent OS runs ⟂ where the models run) is exactly the mental model that prevents the "local vs cloud?" confusion, and it matches the one-organism-two-topologies line we want the cloud guides to hold. And "llama.cpp is a profile, not a provider key" is the honest-limits discipline at its best — you explicitly refuse to document a manual host-switching workaround and say "either add the provider-role host implementation or choose a topology Neo can express." That's the right call; documenting around a gap is how docs rot.

🧭 Patch-Blind Premise Snapshot

• Inputs Read Before Patch: #14323, ai/config.template.mjs (the provider leaves + localModels role block), ai/mcp/server/knowledge-base/config.template.mjs (askSynthesis), ai/services.mjs (TextEmbeddingService), ADR-0019 (AiConfig reactive provider SSOT) grounding.
• Expected Solution Shape: A conceptual guide on local-vs-remote models: the cost/residency/ownership trade, the deployment-mode ⟂ model-mode orthogonality, the per-role provider selection (chat/embedding/graph/ask), the configure-the-protocol-not-the-brand rule, honest about what Neo config can't yet express. Render-verified diagrams, conceptual-not-reference.
• Patch Verdict: Matches, and the technical content is grounded, not paraphrased (V-B-A below).
• Premise Coherence: Coheres with ADR-0019 ("aiConfig provider leaves" / inherit-through-the-tree) and the local-model autonomy thesis (night shift without exporting the work).

🕸️ Context & Graph Linking

• Target Epic / Issue ID: Resolves #14323
• Related Graph Nodes: #14310 (epic); AiConfigModel / DeploymentCookbook / cloud-deployment Configuration + LlamaCppProfile cluster

🔬 Depth Floor

Documented V-B-A — every named config claim traced to source:

• 4 provider leaves in ai/config.template.mjs: chatProvider + modelProvider = leaf('openAiCompatible', 'NEO_MODEL_PROVIDER') ✓; graphProvider = leaf('openAiCompatible', 'NEO_GRAPH_PROVIDER'), JSDoc confirms openAiCompatible/ollama (local) — supports the guide's "graph is local-only today" ✓; embeddingProvider = leaf('openAiCompatible', 'NEO_EMBEDDING_PROVIDER') ✓.
• localModels role block: the template's own JSDoc maps "Chat-path consumers (graph extraction, session summary) → localModels.chat.*" and "Embedding-path consumers (Memory Core, KB ingestion) → localModels.embedding.*" — verbatim to the guide's "localModels.chat protects chat, summaries, and graph generation; localModels.embedding protects vector input." ✓
• askSynthesis: real block in ai/mcp/server/knowledge-base/config.template.mjs (+ askSynthesisGuard.mjs, SearchService.mjs) ✓.
• TextEmbeddingService: exists (ai/services.mjs) ✓.

Minor structural note (non-blocking): the §"four provider axes" diagram renders askSynthesis as a sibling aiConfig leaf alongside chatProvider/embeddingProvider/graphProvider — but those three are root-aiConfig leaves while askSynthesis lives in the KB server config, not the root template. The conceptual point (four separately-configurable provider roles) is correct; only the implied co-location is slightly loose. A half-sentence ("the KB ask path configures its own askSynthesis block") would make the structural seam exact. Pure polish.

Rhetorical-Drift Audit: Pass — "configure the contract, not the brand" matches the mechanical reality (openAiCompatible is a protocol selector, llamaCpp is a runtime behind it), and the local-context-residency failure mode is described at the right altitude.

🧠 Graph Ingestion Notes

• [RETROSPECTIVE]: The role-residency framing ("a local chat model can be excellent and still fail the Agent OS if it evicts the embedding model before the next vector call") is the kind of operational truth that separates a real deployment guide from a feature list. Captured precisely and tied to the localModels readiness helpers.

N/A Audits — 📑 📡 🔗 🛂

N/A: docs-only conceptual guide — no Contract Ledger surface, no OpenAPI tool-def, no new skill substrate, no new architectural abstraction (it documents the shipped provider config).

🎯 Close-Target Audit

• Resolves #14323. Leaf docs sub of #14310, not epic-labeled. Pass.

🪜 Evidence Audit

• PR declares render verification; CI 7/7 green (incl. guide dead-link lint, which validates the new AiConfigModel.md / LlamaCppProfile.md links). The verifiable config surface I independently confirmed above. Pass.

📋 Required Actions

No required actions — eligible for human merge.

📊 Evaluation Metrics

• [ARCH_ALIGNMENT]: 95 — correct placement + render-verified diagrams + accurate cross-refs; the orthogonal-axes mental model is exactly right. -5: the askSynthesis co-location nuance.
• [CONTENT_COMPLETENESS]: 95 — local-vs-remote trade, the two axes, four provider roles, configure-the-protocol rule, llama.cpp-profile distinction, honest limits, dual-audience.
• [EXECUTION_QUALITY]: 97 — every named config claim V-B-A'd against source; render-verified diagrams; exemplary honest-limits.
• [PRODUCTIVITY]: 95 — the #14323 goal achieved.
• [IMPACT]: 72 — documents the provider abstraction that makes the Brain portable to private/air-gapped code; adoption-critical for the on-prem story.
• [COMPLEXITY]: 42 — 200-line guide, two TD diagrams, the four-axis provider model, the contract-not-brand + llama.cpp-profile distinctions.
• [EFFORT_PROFILE]: Heavy Lift.

Cross-family approve (a Claude reviewing your GPT). A provider guide whose every config claim matches the config — and honest about the topology it can't yet express. That clears your guide queue from my side again. 🖖