Authored by Claude Opus 4.7 (Claude Code). Operator-flagged regression after #11967 / #11966 / #11962 merged to dev.

FAIR-band: in-band [16/30] — corrective lane, no new feature scope. Live verifier (per @neo-gpt cycle-1 anchor): GPT 14 / Claude 16 over last 30 merged PRs (pre-this-PR baseline).

Evidence: L1 (76/76 PASS across config-template, MC/KB config-template, TextEmbeddingService, SessionService.buildChatModel, full graph/ directory, and TenantRepoSyncService specs; grep verification of zero config.template.mjs runtime imports).

Resolves #11968

Summary

Two operator-flagged substrate-quality bugs landed via the three Sub-1/Sub-2/AC1 merges:

1. config.template.mjs import anti-pattern in 7 runtime spots. Importing directly from the template bypasses the operator-overlay ai/config.mjs (gitignored, per learn/agentos/DeploymentCookbook.md §7), so operator customizations at the top-level Tier-1 config never reach runtime code. #11967 added 2 of the 7 (MC/KB config templates); the other 5 are pre-existing legacy. This PR re-points all 7 to ai/config.mjs.

2. JSDoc ticket-archaeology violation of feedback_jsdoc_archaeology_self_audit. #11966 cycle-3 added decay-prone ticket/Epic/Discussion/OQ anchors in production-code JSDoc despite my own memory warning. INTENT framing is what these files need; ticket anchors belong in PR body / commit message which decay-survive.

Changes

Stage 1: initServerConfigs.mjs auto-creates ai/config.mjs

Extended the bootstrap script with initTier1Config() that mirrors the per-server pattern:

• First-time clone of ai/config.template.mjs → ai/config.mjs
• Drift detection on subsequent runs (same shape-projection regex used for MC/KB)
• npm run prepare -- --migrate-config overwrites the local file to match the template

Runs at npm prepare, before initConfigs() (per-server pass) so the top-level overlay is in place when downstream config files resolve.

Stage 2: Re-point 7 AiConfig imports

ai/config.template.mjs is the source-of-truth for template shape; ai/config.mjs is the operator overlay. Runtime code must import from the overlay, never the template:

The MC/KB config templates' import changes propagate to the auto-generated local ai/mcp/server/*/config.mjs files on the next npm run prepare -- --migrate-config invocation.

Stage 3: Idempotent Neo.setupClass(Config) in config.template.mjs

Test workers can now load both config.template.mjs (via the config.template.spec.mjs direct import) AND config.mjs (via runtime code that imports from the overlay) in the same process. Both files register Neo.ai.Config and collide under unitTestMode.

Fixed by const instance = Neo.ns('Neo.ai.Config') ?? Neo.setupClass(Config); — if the class already exists in the namespace, reuse it; otherwise register. Production behavior unchanged because only one of the two files is loaded outside tests.

Stage 4: Strip JSDoc ticket-archaeology

Targets (this-session-only — pre-existing archaeology is out of scope):

• ai/services/graph/providerDispatch.mjs: @summary rewritten with INTENT framing; "Closes #11965 AC5", "OQ2 disposition during Discussion #11961", "operator client-need signal" all removed
• ai/services/memory-core/TextEmbeddingService.mjs: stripped "#11965 Sub-2" + "#11965 Sub-2 cycle-2" markers from ollamaProvider_ JSDoc and 4 inline comments
• ai/services/memory-core/SessionService.mjs: stripped "#11965 Sub-2 cycle-2" markers from the 3 cycle-2 additions (pre-existing anchors at lines 539-540 / 584 / 676 / 831 / 854-856 are out of scope)
• test/playwright/unit/ai/services/graph/providerDispatch.spec.mjs: removed multi-line JSDoc preamble (kept test.describe label with ticket anchor — the documented test-traceability exception)
• test/playwright/unit/ai/services/memory-core/SessionService.buildChatModel.spec.mjs: same treatment

Stage 5: Cookbook §7 documents auto-create behavior

learn/agentos/DeploymentCookbook.md §7 now explains that ai/config.mjs is auto-created on first install via npm prepare, plus the --migrate-config refresh flag.

Slot Rationale

Modified learn/agentos/DeploymentCookbook.md §7 (Local-Only Orchestrator Appendix). Disposition: keep in the operator guide — no turn-loaded substrate expansion. Rating: medium trigger-frequency × medium failure-severity × high enforceability. Rationale: operators who set up a local maintainer machine read §7 to wire devSyncRoots. They need to know ai/config.mjs is auto-created on npm prepare (so they edit it in place rather than create from scratch) and that --migrate-config is the refresh primitive when the template evolves. Without this update, §7's example reads as "create from scratch" while the actual install path auto-creates the file — misleading operators on the canonical bootstrap step.

Test Evidence

Bootstrap precondition: an existing checkout without the gitignored ai/config.mjs must run the setup script before any spec that loads the Tier-1 overlay. CI's npm install triggers prepare, which runs initServerConfigs.mjs automatically — CI is the canonical case. For local reproduction on a clone that pre-dates this PR:

node ai/scripts/setup/initServerConfigs.mjs

<h1 class="neo-h1" data-record-id="11">2) Run the affected specs</h1>

npm run test-unit -- \
  test/playwright/unit/ai/config.template.spec.mjs \
  test/playwright/unit/ai/mcp/server/memory-core/config.template.spec.mjs \
  test/playwright/unit/ai/mcp/server/knowledge-base/config.template.spec.mjs \
  test/playwright/unit/ai/services/memory-core/TextEmbeddingService.spec.mjs \
  test/playwright/unit/ai/services/memory-core/SessionService.buildChatModel.spec.mjs \
  test/playwright/unit/ai/services/graph/ \
  test/playwright/unit/ai/daemons/orchestrator/services/TenantRepoSyncService.spec.mjs

→ 76/76 PASS (4 + 5 + 2 + 9 + 6 + 23 + 27).

Grep verification:

grep -rn "from.*['\"].*config\.template\.mjs['\"]" ai/ --include="*.mjs"

→ 0 matches — no runtime imports of config.template.mjs remain.

Deltas from ticket

None — all 5 listed AC items satisfied; OOS pre-existing JSDoc archaeology left untouched per ticket scope-discipline.

Post-Merge Validation

• Operator confirms fresh npm install on a clean clone auto-creates ai/config.mjs from the template
• Operator confirms npm run prepare -- --migrate-config refreshes ai/config.mjs from the template (overwrites local edits)
• Operator confirms that setting overrides in their local ai/config.mjs (e.g. modelProvider: 'ollama') now propagates to all 7 import sites at runtime
• Operators with existing local ai/mcp/server/*/config.mjs files should run --migrate-config to refresh those too (the templates' import targets changed)

Avoided Traps

• ✓ Did NOT touch pre-existing JSDoc archaeology in files I did not introduce this session (SessionService.mjs:539-540, :584, :676, :831, :854-856 — those are pre-#11966 anchors per feedback_substrate_scope_restraint)
• ✓ Did NOT add ai/config.mjs to git tracking — gitignored per the existing operator-overlay model
• ✓ Did NOT refactor the AiConfig overlay-merge mechanism itself (already env-var-first per cookbook precedence)
• ✓ Did NOT replace ticket anchors with INTENT framing AND keep the ticket reference at the bottom — partial deletion would be incoherent per the self-audit memory

Substrate signal

Per the operator's "team value, no blame" framing — this PR doubles as a substrate signal that:

1. The PR-review workflow's depth-floor didn't catch the config.template.mjs import on #11967. I approved it after the 11 template tests passed (the symptom of the bug: tests pass because templates were the only thing being read). I should have asked: "Does importing AiConfig from the template file rather than the operator-overlay config.mjs bypass local overrides?" — but didn't.
2. The feedback_jsdoc_archaeology_self_audit memory I authored 2026-05-25 failed to fire at authoring time during #11966 cycle-3. Self-audit memories are static rules; without an active recall-at-author-time mechanism, they decay-into-noise. Worth surfacing for the broader MX (Model Experience) substrate evolution thread — possibly as Ideation Sandbox material.

Both signals are mine; the corrective work is this PR.

Authored by [Claude Opus 4.7] (Claude Code).