@zosmaai/pi-llm-wiki 0.11.0 → 0.11.2

package/docs/superpowers/plans/2026-08-07-synthesis-language.md

@@ -0,0 +1,98 @@
+# Configurable Synthesis Language Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Allow vault owners to configure the narrative language used by background ingest synthesis via `.pi/settings.json`.
+
+**Architecture:** Add `synthesisLanguage` field to `TaskConfig`, parse it in `readNamespacedConfig`, pass it through `wiki_ingest` → `runIngestSynthesis`, and conditionally append a language instruction to the ingest worker's system prompt.
+
+**Tech Stack:** TypeScript (ES2022, ESM), Vitest, Biome
+
+**Roadmap:** None
+
+**Phase:** Single-plan implementation
+
+---
+
+### Task 1: Add `synthesisLanguage` to TaskConfig
+
+**Files:**
+- Modify: `extensions/llm-wiki/lib/task-config.ts`
+
+- [ ] Add `synthesisLanguage?: string` field to `TaskConfig` interface (after `trajectories`)
+- [ ] In `readNamespacedConfig`, parse `section.synthesisLanguage` as a non-empty trimmed string:
+  ```ts
+  const lang = section.synthesisLanguage;
+  if (typeof lang === "string" && lang.trim()) out.synthesisLanguage = lang.trim();
+  ```
+- [ ] Run `pnpm typecheck` — confirm no errors
+- [ ] Commit: `feat: add synthesisLanguage config field`
+
+### Task 2: Wire `synthesisLanguage` into ingest worker
+
+**Files:**
+- Modify: `extensions/llm-wiki/lib/ingest-worker.ts`
+
+- [ ] Add `synthesisLanguage?: string` to `RunIngestSynthesisArgs` interface
+- [ ] In `runIngestSynthesis`, after destructuring args, build the system prompt:
+  ```ts
+  const languageInstruction = synthesisLanguage
+    ? `\n\nWrite all generated narrative content in ${synthesisLanguage}. Preserve product names, repository names, APIs, paths, commands, code, field names, and technical identifiers in their original form.`
+    : "";
+  const systemPrompt = INGEST_SYSTEM + languageInstruction;
+  ```
+- [ ] Pass `systemPrompt` (instead of `INGEST_SYSTEM`) to `runSubAgent`
+- [ ] Run `pnpm typecheck` — confirm no errors
+- [ ] Commit: `feat: inject synthesisLanguage into ingest system prompt`
+
+### Task 3: Pass `synthesisLanguage` from wiki_ingest tool
+
+**Files:**
+- Modify: `extensions/llm-wiki/lib/tools.ts`
+
+- [ ] In the `wiki_ingest` tool's background synthesis block (around line 409), pass `synthesisLanguage` to `runIngestSynthesis`:
+  ```ts
+  const committed = await runIngestSynthesis({
+    model: resolved.model as Parameters<typeof runIngestSynthesis>[0]["model"],
+    apiKey: resolved.apiKey,
+    headers: resolved.headers,
+    paths,
+    sourceId: s.id,
+    manifest: s.manifest,
+    extracted: s.extracted,
+    synthesisLanguage: runtime.config.synthesisLanguage,
+  });
+  ```
+- [ ] Run `pnpm typecheck` — confirm no errors
+- [ ] Run `pnpm test` — confirm existing tests pass
+- [ ] Commit: `feat: wire synthesisLanguage through wiki_ingest tool`
+
+### Task 4: Add unit test for synthesis language injection
+
+**Files:**
+- Create: `extensions/llm-wiki/test/ingest-worker-synthesis-language.test.ts`
+
+- [ ] Write a focused test: verify that when `synthesisLanguage` is set, the language instruction is appended to the system prompt
+  - Mock `runSubAgent` or inspect the constructed prompt
+  - Assert the instruction contains the configured language tag and the preservation clause
+- [ ] Run `pnpm test` — confirm test passes
+- [ ] Commit: `test: verify synthesisLanguage injection`
+
+### Task 5: Update documentation
+
+**Files:**
+- Modify: `docs/configuration.md`
+
+- [ ] Add a section for `synthesisLanguage` under the `llm-wiki` config docs:
+  - Description: language for background ingest synthesis narrative content
+  - Type: BCP 47 language tag (string)
+  - Default: undefined (English synthesis)
+  - Example JSON snippet
+- [ ] Commit: `docs: document synthesisLanguage config`
+
+### Task 6: Final verification
+
+- [ ] Run `pnpm lint` — confirm no Biome issues
+- [ ] Run `pnpm test` — confirm all tests pass
+- [ ] Run `pnpm typecheck` — confirm no TypeScript errors
+- [ ] Commit: `ci: verify synthesisLanguage implementation`

package/docs/superpowers/specs/2026-08-02-okf-foundation-design.md

@@ -43,7 +43,7 @@ Those requirements belong to later child specs.
 2. **Mode controls bundle behavior, not readability.** Every mode reads both legacy and OKF-shaped pages. Mode controls reserved files and generated projections.
 3. **Missing metadata does not become invented metadata.** Foundation never fabricates authorship, verification, provenance, or timestamps it cannot know.
 4. **Unknown data survives rewrites.** Unknown ordinary YAML fields remain semantically equivalent after parse and serialize.
-5. **Generated files are projections.** Registry, backlinks, indexes, and logs derive from authoritative pages and events.
+5. **Generated files are projections; authoritative extension state is not.** Registry, backlinks, indexes, and logs derive from authoritative pages and events. `meta/events.jsonl` is extension-written state, but it is not generated metadata because no rebuild can reconstruct it.
 6. **Invalid explicit configuration fails closed.** Unknown mode and OKF version values never silently downgrade to legacy behavior.
 
 ## Vault Mode
@@ -350,6 +350,12 @@ An index is a projection. Users and importers cannot use it to hide a concept fr
 
 `meta/events.jsonl` remains the authoritative append-only event source in both modes. `wiki/log.md` is a generated OKF projection only in `okf-0.2` mode. Foundation generates no per-directory logs.
 
+`meta/events.jsonl` is durable extension-owned vault state. Users who need activity continuity must preserve it when backing up or synchronizing a complete pi-llm-wiki vault. It is not derivable from canonical pages, raw source packets, `meta/log.md`, or `wiki/log.md`.
+
+Foundation does not make the JSONL event source part of the distributable OKF bundle. `wiki/log.md` is a portable snapshot of recorded activity at projection time, not a recovery format and not a promise that an imported bundle can continue the originating vault's event stream. Import, export, and imported-history composition belong to the later Interchange child specification.
+
+The event stream records selected extension operations. It is not a complete revision history: manual file edits do not fabricate events, while extension-owned operational actions may emit events. Documentation and UI text must call it an activity history rather than a complete content audit trail.
+
 ### Authoritative event shape
 
 Each valid JSONL line must contain:
@@ -363,6 +369,8 @@ Each valid JSONL line must contain:
 
 Additional JSON-compatible fields are allowed. Event production is mode-independent: the same successful capture, creation, update, retro, observation, ingestion, and other tool-owned mutations append the same event in legacy and OKF modes. Event writers append only after the associated authoritative wiki mutation succeeds. A projection rebuild itself does not append an event. Manual file edits do not fabricate events because the extension cannot infer actor or intent safely.
 
+Fields projected into `wiki/log.md` must be safe for a distributable bundle. A local file capture event records its stable `source_id` and format but not the caller-supplied `file_path`; the exact path remains in the extension-owned raw source manifest. Manual event details are user-controlled and documentation must warn callers not to include secrets or machine-local paths intended to remain private.
+
 ### Log template
 
 ```markdown
@@ -398,7 +406,14 @@ If any concept has malformed frontmatter, normalized identity collision, or unsu
 - preserve the previous registry, backlinks, indexes, and logs
 - do not publish a partial metadata generation
 
-Unresolved links and malformed event lines are non-blocking projection diagnostics: valid concepts may still be indexed, and the previous semantics for reporting gaps remain available. The rebuild result reports every diagnostic.
+Unresolved links and malformed event lines are non-blocking projection diagnostics: valid concepts may still be indexed, and valid event lines may still be projected. A missing or unreadable `meta/events.jsonl` is different from a present empty stream. Rebuild reports `event_source_missing` or `event_source_unreadable`, continues publishing registry, backlink, and index projections, and leaves existing `meta/log.md` and `wiki/log.md` byte-identical. A present zero-byte event file is an explicitly empty authoritative stream and generates the normal empty log projections.
+
+Non-blocking diagnostics include:
+
+- `link_unresolved`
+- `event_invalid_json`
+- `event_source_missing`
+- `event_source_unreadable`
 
 On successful rebuild:
 

package/docs/superpowers/specs/2026-08-02-okf-v0.2-interoperability-design.md

@@ -106,12 +106,14 @@ The competitive advantage for pi-llm-wiki is combining OKF interoperability with
 ├── imports/                    # extension-owned import staging and audit records
 │   ├── pending/<import-id>/
 │   └── applied/<import-id>/manifest.json
-├── meta/                       # generated registry, backlinks, embeddings
+├── meta/                       # durable local events + generated internal projections
 └── outputs/                    # reports and explicit exports
 ```
 
 `.llm-wiki/wiki/` is the distributable OKF bundle. Product-specific raw packets, staging state, and generated search metadata remain outside it.
 
+`meta/events.jsonl` is durable local pi-llm-wiki state but is not part of the base OKF bundle. A full-vault backup preserves it; an OKF-only export does not. The exported `wiki/log.md` is therefore a readable history snapshot, not a lossless or resumable event source.
+
 Source pages inside the bundle provide stable provenance targets for canonical pages. Raw packet paths may remain pi-llm-wiki extension metadata on source pages, but portable provenance references should resolve to source pages or external resources rather than escaping the bundle.
 
 `imports/**` is extension-owned and protected by the same tool-call guardrail model as `raw/**` and `meta/**`. Pending imports never participate in recall or metadata indexing.
@@ -253,7 +255,7 @@ The metadata rebuild writes:
 
 Each directory index lists only direct concepts and immediate child directories. This preserves progressive disclosure and avoids loading a recursive catalog into context.
 
-Reserved `index.md` and `log.md` files are not concept documents and are excluded from ordinary concept recall. Imported reserved files are validated and recorded in the import manifest, but the live bundle regenerates its own indexes and log. Foreign concept paths and document-level metadata are preserved; arbitrary foreign index prose is not merged into the live generated index.
+Reserved `index.md` and `log.md` files are not concept documents and are excluded from ordinary concept recall. Imported reserved files are validated and recorded in the import manifest, but the live bundle regenerates its own indexes and log. Foreign concept paths and document-level metadata are preserved; arbitrary foreign index prose is not merged into the live generated index. Before Interchange implementation, its normative child spec must define whether an imported `log.md` is archived, retained as a separate historical baseline, or replaced when a new local event stream begins. It must not imply that Markdown prose can reconstruct the originating JSONL stream.
 
 ## Import Design
 
@@ -334,6 +336,8 @@ live legacy + OKF pages
 
 Export never mutates the live vault. It preserves safe concept paths, bodies, unknown document fields, standard metadata, and pi-llm-wiki extension fields. Legacy pages are converted in memory. Generated `meta/**`, pending imports, source packet internals, and embeddings are not exported.
 
+Because `meta/events.jsonl` is excluded, exported `log.md` is a deterministic snapshot rather than a resumable event ledger. Export must use only bundle-safe projected fields. Portable event continuity or a machine-readable event sidecar requires a separately reviewed Interchange decision and is not implied by Foundation.
+
 Raw evidence remains represented through portable source concept pages and their provenance links. A later option may package selected original artifacts under an OKF `references/` convention.
 
 ## Migration Design

package/docs/superpowers/specs/2026-08-07-synthesis-language-design.md

@@ -0,0 +1,94 @@
+# Configurable Language for Background Ingest Synthesis
+
+**Issue:** [#124](https://github.com/zosmaai/pi-llm-wiki/issues/124)
+**Date:** 2026-08-07
+**Status:** Approved
+
+## Problem
+
+Background ingest synthesis (`wiki_ingest(background=true)`) always produces English narrative content, regardless of the vault's authoring language. The background sub-agent does not inherit language instructions from `AGENTS.md`, `APPEND_SYSTEM.md`, `WIKI_SCHEMA.md`, or the main session prompt.
+
+Workarounds are inadequate:
+- `background=false` returns extracted content to the main session, consuming context window.
+- Manual translation after ingest is error-prone and defeats the purpose of background synthesis.
+
+## Goal
+
+Allow vault owners to configure the narrative language used by background ingest synthesis, without copying the main conversation context into the background worker.
+
+## Design
+
+### Configuration
+
+- **Field:** `synthesisLanguage`
+- **Type:** BCP 47 language tag (e.g., `"ru"`, `"fr"`, `"en"`)
+- **Location:** `.pi/settings.json` under the `llm-wiki` namespace
+- **Default:** undefined (no change to current behavior)
+
+Example:
+```json
+{
+  "llm-wiki": {
+    "synthesisLanguage": "ru"
+  }
+}
+```
+
+This matches the existing pattern used by `taskModel`, `trajectories`, `notices`, etc.
+
+### System Prompt Modification
+
+When `synthesisLanguage` is configured, the background ingest worker appends a fixed instruction block to its system prompt (`INGEST_SYSTEM` in `ingest-worker.ts`):
+
+> Write all generated content in {language}, including titles, headings, summaries, descriptions, and concept/entity names. Only preserve code, API names, file paths, commands, exact technical identifiers, and verbatim quotations in their original form.
+
+The BCP 47 tag is validated using `Intl.getCanonicalLocales()` and canonicalized before use. Invalid or suspicious tags (containing newlines, quotes, or instruction-like words) are rejected.
+
+Additionally, the page renderer translates fixed headings (Summary, Key Takeaways, etc.) into the configured language for supported languages (Russian, French, German, Japanese). Unsupported languages fall back to English headings.
+
+### Scope
+
+The language setting applies to LLM-generated narrative fields:
+- Page titles
+- Headings
+- Summaries
+- Descriptions
+- Key takeaways
+- Conclusions
+- Entity and concept descriptions
+- Synthesis and analysis text
+
+It does NOT apply to:
+- Raw captured source content (`extracted.md`)
+- Code blocks
+- Technical identifiers (API names, paths, commands, field names)
+- Source quotations
+
+### Implementation Changes
+
+1. **`lib/task-config.ts`**
+   - Add `synthesisLanguage?: string` to `TaskConfig` interface
+   - Parse in `readNamespacedConfig` as a non-empty trimmed string
+
+2. **`lib/ingest-worker.ts`**
+   - Add `synthesisLanguage?: string` to `RunIngestSynthesisArgs`
+   - In `runIngestSynthesis`, conditionally append the language instruction to `INGEST_SYSTEM` when `synthesisLanguage` is set
+
+3. **`lib/tools.ts`** (wiki_ingest tool)
+   - Pass `runtime.config.synthesisLanguage` into `runIngestSynthesis` args
+
+### Acceptance Criteria
+
+- [ ] Background ingest generates synthesis in the configured language
+- [ ] Configuration works with `wiki_ingest(background=true)`
+- [ ] Main conversation context is NOT copied into the background worker
+- [ ] Existing behavior unchanged when no language is configured
+- [ ] Technical identifiers and source quotations remain in their original language
+- [ ] Generated titles, headings, summaries, and conclusions consistently follow the configured language
+
+## Out of Scope
+
+- Per-source language override
+- Automatic language detection from source content
+- User-editable prompt template (fixed wording for now)
+- Language setting for other background tasks (embeddings, topic inference) — can be added later if needed

package/extensions/llm-wiki/lib/bootstrap.ts

@@ -14,9 +14,12 @@ export const WIKI_SCHEMA = [
   "|------|-------|------|",
   "| raw/** | extension | immutable after capture |",
   "| wiki/** | model + user | editable knowledge pages |",
-  "| meta/* | extension | auto-generated |",
+  "| meta/events.jsonl | extension tools | append-only authoritative state |",
+  "| meta/* except events.jsonl | extension | generated projections |",
   "| . | human + explicit request | operating rules |",
   "",
+  "Back up `meta/events.jsonl` to preserve activity history. Generated logs cannot reconstruct it.",
+  "",
   "## Source Packet Format",
   "",
   "```",

package/extensions/llm-wiki/lib/ingest-worker.ts

@@ -92,13 +92,113 @@ export type CommitSynthesisOutcome =
 
 // ── deterministic persistence (no LLM) ────────────────────
 
-function buildEntityPageBody(title: string, description: string, sourceId: string): string {
+/** Localized headings for generated pages (issue #124). */
+const HEADINGS: Record<string, Record<string, string>> = {
+  ru: {
+    summary: "Резюме",
+    keyTakeaways: "Ключевые выводы",
+    entitiesMentioned: "Упомянутые сущности",
+    conceptsMentioned: "Упомянутые концепции",
+    notableQuotes: "Заметные цитаты",
+    contradictions: "Противоречия",
+    sourcePacket: "Пакет источника",
+    overview: "Обзор",
+    definition: "Определение",
+    noneRecorded: "[Не записано]",
+    none: "[Нет]",
+    id: "ID",
+    extracted: "Извлечено",
+    manifest: "Манифест",
+    contradiction: "⚠️ **Противоречие**",
+  },
+  fr: {
+    summary: "Résumé",
+    keyTakeaways: "Points clés",
+    entitiesMentioned: "Entités mentionnées",
+    conceptsMentioned: "Concepts mentionnés",
+    notableQuotes: "Citations notables",
+    contradictions: "Contradictions",
+    sourcePacket: "Paquet source",
+    overview: "Aperçu",
+    definition: "Définition",
+    noneRecorded: "[Aucun enregistré]",
+    none: "[Aucun]",
+    id: "ID",
+    extracted: "Extrait",
+    manifest: "Manifeste",
+    contradiction: "⚠️ **Contradiction**",
+  },
+  de: {
+    summary: "Zusammenfassung",
+    keyTakeaways: "Wichtige Erkenntnisse",
+    entitiesMentioned: "Erwähnte Entitäten",
+    conceptsMentioned: "Erwähnte Konzepte",
+    notableQuotes: "Bemerkenswerte Zitate",
+    contradictions: "Widersprüche",
+    sourcePacket: "Quellenpaket",
+    overview: "Übersicht",
+    definition: "Definition",
+    noneRecorded: "[Keine aufgezeichnet]",
+    none: "[Keine]",
+    id: "ID",
+    extracted: "Extrahiert",
+    manifest: "Manifest",
+    contradiction: "⚠️ **Widerspruch**",
+  },
+  ja: {
+    summary: "要約",
+    keyTakeaways: "主な要点",
+    entitiesMentioned: "言及されたエンティティ",
+    conceptsMentioned: "言及された概念",
+    notableQuotes: "注目すべき引用",
+    contradictions: "矛盾",
+    sourcePacket: "ソースパケット",
+    overview: "概要",
+    definition: "定義",
+    noneRecorded: "[記録なし]",
+    none: "[なし]",
+    id: "ID",
+    extracted: "抽出済み",
+    manifest: "マニフェスト",
+    contradiction: "⚠️ **矛盾**",
+  },
+};
+
+function getHeadings(lang?: string): Record<string, string> {
+  if (lang && HEADINGS[lang]) return HEADINGS[lang];
+  // English defaults
+  return {
+    summary: "Summary",
+    keyTakeaways: "Key Takeaways",
+    entitiesMentioned: "Entities Mentioned",
+    conceptsMentioned: "Concepts Mentioned",
+    notableQuotes: "Notable Quotes",
+    contradictions: "Contradictions",
+    sourcePacket: "Source Packet",
+    overview: "Overview",
+    definition: "Definition",
+    noneRecorded: "[None recorded]",
+    none: "[None]",
+    id: "ID",
+    extracted: "Extracted",
+    manifest: "Manifest",
+    contradiction: "⚠️ **Contradiction**",
+  };
+}
+
+function buildEntityPageBody(
+  title: string,
+  description: string,
+  sourceId: string,
+  lang?: string,
+): string {
   const desc = description.trim() || "One-line description.";
+  const h = getHeadings(lang);
   return `# ${title}
 
 ${desc}
 
-## Overview
+## ${h.overview}
 
 [Key facts]
 
@@ -107,13 +207,19 @@ ${desc}
 - [${sourceId}](/sources/${sourceId}.md)`;
 }
 
-function buildConceptPageBody(title: string, definition: string, sourceId: string): string {
+function buildConceptPageBody(
+  title: string,
+  definition: string,
+  sourceId: string,
+  lang?: string,
+): string {
   const def = definition.trim() || "One-line definition.";
+  const h = getHeadings(lang);
   return `# ${title}
 
 ${def}
 
-## Definition
+## ${h.definition}
 
 [Clear explanation]
 
@@ -127,60 +233,62 @@ export function buildIngestedSourcePageBody(
   manifest: Record<string, unknown>,
   data: SynthesisData,
   _date: string,
+  lang?: string,
 ): string {
   const id = String(manifest.id);
   const title = String(manifest.title || id);
   const url = manifest.url ? `\n> _Original: [${manifest.url}](${manifest.url})_` : "";
+  const h = getHeadings(lang);
 
   const takeaways =
     data.key_takeaways.length > 0
       ? data.key_takeaways.map((t) => `- ${t.trim()}`).join("\n")
-      : "- [None recorded]";
+      : `- ${h.noneRecorded}`;
   const entities =
     data.entities.length > 0
       ? data.entities.map((e) => `- [${e.title}](/entities/${slugify(e.title)}.md)`).join("\n")
-      : "- [None]";
+      : `- ${h.none}`;
   const concepts =
     data.concepts.length > 0
       ? data.concepts.map((c) => `- [${c.title}](/concepts/${slugify(c.title)}.md)`).join("\n")
-      : "- [None]";
+      : `- ${h.none}`;
   const quotes =
     data.quotes && data.quotes.length > 0
       ? data.quotes
           .map((q) => `> ${q.text.trim()}${q.attribution ? ` — ${q.attribution}` : ""}`)
           .join("\n\n")
-      : "> [None recorded]";
+      : `> ${h.noneRecorded}`;
   const contradictions =
     data.contradictions && data.contradictions.length > 0
-      ? `\n## Contradictions\n\n${data.contradictions.map((c) => `⚠️ **Contradiction**: ${c.trim()}`).join("\n")}\n`
+      ? `\n## ${h.contradictions}\n\n${data.contradictions.map((c) => `${h.contradiction}: ${c.trim()}`).join("\n")}\n`
       : "";
 
   return `# ${title}${url}
 
-## Summary
+## ${h.summary}
 
 ${data.summary.trim()}
 
-## Key Takeaways
+## ${h.keyTakeaways}
 
 ${takeaways}
 
-## Entities Mentioned
+## ${h.entitiesMentioned}
 
 ${entities}
 
-## Concepts Mentioned
+## ${h.conceptsMentioned}
 
 ${concepts}
 
-## Notable Quotes
+## ${h.notableQuotes}
 
 ${quotes}
-${contradictions}## Source Packet
+${contradictions}## ${h.sourcePacket}
 
-- **ID:** \`sources/${id}\`
-- **Extracted:** \`raw/sources/${id}/extracted.md\`
-- **Manifest:** \`raw/sources/${id}/manifest.json\`
+- **${h.id}:** \`sources/${id}\`
+- **${h.extracted}:** \`raw/sources/${id}/extracted.md\`
+- **${h.manifest}:** \`raw/sources/${id}/manifest.json\`
 `;
 }
 
@@ -189,12 +297,13 @@ export function buildIngestedSourcePage(
   manifest: Record<string, unknown>,
   data: SynthesisData,
   date: string,
+  lang?: string,
 ): string {
   const id = String(manifest.id);
   const title = String(manifest.title || id);
   const format = String(manifest.format || "unknown");
   const captured = String(manifest.captured || date);
-  const body = buildIngestedSourcePageBody(manifest, data, date);
+  const body = buildIngestedSourcePageBody(manifest, data, date, lang);
   const doc = createKnowledgeDocument(
     `sources/${id}.md`,
     {
@@ -223,6 +332,7 @@ export function commitSynthesis(
   manifest: Record<string, unknown>,
   data: SynthesisData,
   date: string = fmtDate(),
+  lang?: string,
 ): CommitSynthesisOutcome {
   const result: CommitResult = {
     sourceId,
@@ -250,7 +360,7 @@ export function commitSynthesis(
     if (!parsed.ok) return { ok: false, sourceId, diagnostics: parsed.diagnostics };
     sourceDocument = patchKnowledgeDocument(parsed.document, {
       fields: { status: "ingested", updated: date },
-      body: buildIngestedSourcePageBody(manifest, data, date),
+      body: buildIngestedSourcePageBody(manifest, data, date, lang),
     });
   } else {
     sourceDocument = createKnowledgeDocument(
@@ -265,7 +375,7 @@ export function commitSynthesis(
         status: "ingested",
         updated: date,
       },
-      buildIngestedSourcePageBody(manifest, data, date),
+      buildIngestedSourcePageBody(manifest, data, date, lang),
     );
   }
   mkdirSync(join(paths.wiki, "sources"), { recursive: true });
@@ -289,7 +399,7 @@ export function commitSynthesis(
           created: date,
           updated: date,
         },
-        buildEntityPageBody(e.title, e.description, sourceId),
+        buildEntityPageBody(e.title, e.description, sourceId, lang),
         [{ id: sourceId, resource: `/sources/${sourceId}.md` }],
       );
       writeKnowledgeDocumentFile(pagePath, entityDoc);
@@ -315,7 +425,7 @@ export function commitSynthesis(
           created: date,
           updated: date,
         },
-        buildConceptPageBody(c.title, c.definition, sourceId),
+        buildConceptPageBody(c.title, c.definition, sourceId, lang),
         [{ id: sourceId, resource: `/sources/${sourceId}.md` }],
       );
       writeKnowledgeDocumentFile(pagePath, conceptDoc);
@@ -363,6 +473,8 @@ export interface RunIngestSynthesisArgs {
   /** Cap on extracted chars fed to the model (avoid huge prompts). Default 24k. */
   maxChars?: number;
   signal?: AbortSignal;
+  /** BCP 47 language tag for narrative content (issue #124). */
+  synthesisLanguage?: string;
 }
 
 /**
@@ -373,10 +485,26 @@ export interface RunIngestSynthesisArgs {
 export async function runIngestSynthesis(
   args: RunIngestSynthesisArgs,
 ): Promise<CommitResult | undefined> {
-  const { model, apiKey, headers, paths, sourceId, manifest, extracted, maxChars, signal } = args;
+  const {
+    model,
+    apiKey,
+    headers,
+    paths,
+    sourceId,
+    manifest,
+    extracted,
+    maxChars,
+    signal,
+    synthesisLanguage,
+  } = args;
   const content = extracted.slice(0, maxChars ?? 24_000);
   if (!content.trim()) return undefined;
 
+  const languageInstruction = synthesisLanguage
+    ? `\n\nWrite all generated content in ${synthesisLanguage}, including titles, headings, summaries, descriptions, and concept/entity names. Only preserve code, API names, file paths, commands, exact technical identifiers, and verbatim quotations in their original form.`
+    : "";
+  const systemPrompt = INGEST_SYSTEM + languageInstruction;
+
   let committed: CommitResult | undefined;
 
   const commitTool: AgentTool<typeof CommitSynthesisSchema> = {
@@ -386,7 +514,14 @@ export async function runIngestSynthesis(
       "Persist the structured synthesis of this source into wiki pages. Call exactly once.",
     parameters: CommitSynthesisSchema,
     execute: async (_id, params) => {
-      const outcome = commitSynthesis(paths, sourceId, manifest, params);
+      const outcome = commitSynthesis(
+        paths,
+        sourceId,
+        manifest,
+        params,
+        undefined,
+        synthesisLanguage,
+      );
       if (!outcome.ok) {
         return {
           content: [{ type: "text", text: `Failed: ${outcome.diagnostics[0].message}` }],
@@ -411,7 +546,7 @@ export async function runIngestSynthesis(
     model,
     apiKey,
     headers,
-    systemPrompt: INGEST_SYSTEM,
+    systemPrompt,
     userPrompt,
     tools: [commitTool as AgentTool],
     signal,

package/extensions/llm-wiki/lib/knowledge-document.ts

@@ -21,6 +21,8 @@ export type DiagnosticCode =
   | "okf_version_mismatch"
   | "link_path_escape"
   | "link_unresolved"
+  | "event_source_missing"
+  | "event_source_unreadable"
   | "event_invalid_json"
   | "event_invalid_timestamp"
   | "event_missing_kind";