@jcode.labs/ragmir 2.0.0 → 2.2.0

package/dist/sources.js

@@ -1,27 +1,48 @@
 import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { loadConfig } from "./config.js";
-import { SOURCES_FILE_HEADER } from "./defaults.js";
+import { findProjectConfig, loadConfig } from "./config.js";
+/**
+ * List the configured source entries. Sources live in the `sources` array of
+ * `.ragmir/config.json` (the primary mechanism). A legacy `.ragmir/sources.txt`
+ * is still read and merged when present so existing projects keep working, but
+ * it is never created or written by these functions anymore.
+ */
 export async function listSourceEntries(cwd = process.cwd()) {
     const config = await loadConfig(cwd);
-    const content = await readSourcesFile(config.sourcesFile);
-    return {
-        sourcesFile: config.sourcesFile,
-        entries: content ? parseSourceEntries(content) : [],
-    };
+    const projectConfig = findProjectConfig(cwd);
+    const configEntries = await readConfigSources(projectConfig);
+    const legacyEntries = await readLegacySourcesTxt(config.sourcesFile);
+    const seen = new Set();
+    const entries = [];
+    for (const entry of [...configEntries, ...legacyEntries]) {
+        if (!seen.has(entry)) {
+            seen.add(entry);
+            entries.push(entry);
+        }
+    }
+    return { sourcesFile: projectConfig.configPath, entries };
 }
+/**
+ * Add source entries to the `sources` array of `.ragmir/config.json`. Does not
+ * touch the legacy `sources.txt` file anymore; entries already present there
+ * are treated as existing (skipped) to avoid duplicates.
+ */
 export async function addSourceEntries(options) {
-    const entries = normalizeRequestedEntries(options.entries);
-    if (entries.length === 0) {
+    const requested = normalizeRequestedEntries(options.entries);
+    if (requested.length === 0) {
         throw new Error("At least one source path or glob is required.");
     }
     const config = await loadConfig(options.cwd);
-    const content = await readSourcesFile(config.sourcesFile);
-    const existingEntries = new Set(content ? parseSourceEntries(content) : []);
+    const projectConfig = findProjectConfig(options.cwd ?? process.cwd());
+    const configEntries = await readConfigSources(projectConfig);
+    const existingEntries = new Set([
+        ...configEntries,
+        ...(await readLegacySourcesTxt(config.sourcesFile)),
+    ]);
     const added = [];
     const skipped = [];
-    for (const entry of entries) {
+    for (const entry of requested) {
         if (existingEntries.has(entry)) {
             skipped.push(entry);
             continue;
@@ -30,20 +51,49 @@ export async function addSourceEntries(options) {
         added.push(entry);
     }
     if (added.length > 0) {
-        await mkdir(path.dirname(config.sourcesFile), { recursive: true });
-        await writeFile(config.sourcesFile, nextSourcesFileContent(content, added), "utf8");
+        await writeConfigSources(projectConfig, [...configEntries, ...added]);
     }
     return {
-        sourcesFile: config.sourcesFile,
+        sourcesFile: projectConfig.configPath,
         added,
         skipped,
     };
 }
-async function readSourcesFile(sourcesFile) {
+/** Read the raw `sources` array from config.json without resolving paths. */
+async function readConfigSources(projectConfig) {
+    if (!existsSync(projectConfig.configPath)) {
+        return [];
+    }
+    try {
+        const raw = JSON.parse(await readFile(projectConfig.configPath, "utf8"));
+        if (isRecord(raw) && Array.isArray(raw.sources)) {
+            return raw.sources.filter((entry) => typeof entry === "string");
+        }
+    }
+    catch {
+        // Fall back to empty if the config is unreadable; loadConfig surfaces real errors elsewhere.
+    }
+    return [];
+}
+/** Write the `sources` array back into config.json, preserving other fields. */
+async function writeConfigSources(projectConfig, entries) {
+    await mkdir(path.dirname(projectConfig.configPath), { recursive: true });
+    const raw = existsSync(projectConfig.configPath)
+        ? JSON.parse(await readFile(projectConfig.configPath, "utf8"))
+        : {};
+    if (!isRecord(raw)) {
+        throw new Error(`${path.relative(projectConfig.projectRoot, projectConfig.configPath)} must contain a JSON object.`);
+    }
+    raw.sources = [...entries];
+    await writeFile(projectConfig.configPath, `${JSON.stringify(raw, null, 2)}\n`, "utf8");
+}
+/** Read the legacy sources.txt read-only for backward compatibility. */
+async function readLegacySourcesTxt(sourcesFile) {
     if (!existsSync(sourcesFile)) {
-        return null;
+        return [];
     }
-    return readFile(sourcesFile, "utf8");
+    const content = await readFile(sourcesFile, "utf8");
+    return parseSourceEntries(content);
 }
 function parseSourceEntries(content) {
     return content
@@ -64,8 +114,7 @@ function normalizeRequestedEntries(entries) {
     }
     return normalized;
 }
-function nextSourcesFileContent(currentContent, added) {
-    const base = currentContent === null ? SOURCES_FILE_HEADER.join("\n") : currentContent.trimEnd();
-    return `${base ? `${base}\n` : ""}${added.join("\n")}\n`;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //# sourceMappingURL=sources.js.map

package/dist/sources.js.map

@@ -1 +1 @@
-{"version":3,"file":"sources.js","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC7D,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAkBnD,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE;IACzD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,CAAA;IACpC,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;IACzD,OAAO;QACL,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE;KACpD,CAAA;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgC;IAEhC,MAAM,OAAO,GAAG,yBAAyB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IAC1D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAA;IAClE,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC5C,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;IACzD,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IAC3E,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,MAAM,OAAO,GAAa,EAAE,CAAA;IAE5B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACnB,SAAQ;QACV,CAAC;QACD,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAC1B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACnB,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QAClE,MAAM,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,sBAAsB,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,CAAA;IACrF,CAAC;IAED,OAAO;QACL,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,KAAK;QACL,OAAO;KACR,CAAA;AACH,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,WAAmB;IAChD,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,CAAA;AACtC,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAe;IACzC,OAAO,OAAO;SACX,KAAK,CAAC,QAAQ,CAAC;SACf,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;AAC/D,CAAC;AAED,SAAS,yBAAyB,CAAC,OAA0B;IAC3D,MAAM,UAAU,GAAa,EAAE,CAAA;IAC/B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;QAC5B,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAClC,SAAQ;QACV,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QACjB,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAC1B,CAAC;IACD,OAAO,UAAU,CAAA;AACnB,CAAC;AAED,SAAS,sBAAsB,CAAC,cAA6B,EAAE,KAAwB;IACrF,MAAM,IAAI,GAAG,cAAc,KAAK,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,EAAE,CAAA;IAChG,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAA;AAC1D,CAAC"}
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAA;AAE3C,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAInD,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhF;AAED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,mBAAmB,EAAE,EAC9B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAcf;AAED,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAevF;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAOjF;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CASnE;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG/D"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAA;AAE3C,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAiBnD,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBhF;AA6BD,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,mBAAmB,EAAE,EAC9B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAcf;AAED,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAevF;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAOjF;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CASnE;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG/D"}

package/dist/store.js

@@ -3,6 +3,19 @@ import path from "node:path";
 import * as lancedb from "@lancedb/lancedb";
 import { isRecord } from "./guards.js";
 const EMPTY_TEXT_FILES_MANIFEST = "empty-text-files.json";
+/**
+ * LanceDB requires a minimum number of rows to train an IVF_PQ vector index.
+ * Below this threshold, brute-force (flat) scan is used instead, which is
+ * optimal for small corpora and avoids wasted index-training work.
+ */
+const MIN_INDEX_ROWS = 256;
+/**
+ * IVF partition count heuristic: roughly sqrt(row_count), bounded to keep both
+ * small corpora (too many empty partitions) and very large corpora (training
+ * cost) well-behaved. See LanceDB production guidance.
+ */
+const MIN_IVF_PARTITIONS = 8;
+const MAX_IVF_PARTITIONS = 1024;
 export async function writeRows(rows, config) {
     await mkdir(config.storageDir, { recursive: true });
     const db = await lancedb.connect(config.storageDir);
@@ -14,9 +27,41 @@ export async function writeRows(rows, config) {
         return;
     }
     const records = rows.map((row) => ({ ...row }));
-    await db.createTable(config.tableName, records, {
+    const table = await db.createTable(config.tableName, records, {
         mode: "overwrite",
     });
+    // Train an IVF_PQ vector index once the corpus is large enough to benefit
+    // from approximate nearest-neighbour search. Below the threshold, LanceDB
+    // falls back to an exact flat scan, which is faster for small corpora and
+    // avoids wasting work training an index on too few vectors.
+    if (rows.length >= MIN_INDEX_ROWS) {
+        await ensureVectorIndex(table, rows.length);
+    }
+}
+async function ensureVectorIndex(table, rowCount) {
+    const existing = await table.listIndices();
+    const hasVectorIndex = existing.some((index) => index.name === "vector_idx");
+    if (hasVectorIndex) {
+        return;
+    }
+    // numSubVectors must divide the vector dimension evenly. 16 is a safe default
+    // for the 384-dim local-hash and mxbai-xsmall models; LanceDB validates and
+    // will reject a value that does not divide evenly, so larger models still
+    // fall back to flat scan rather than corrupting the index.
+    const numSubVectors = 16;
+    const numPartitions = clampIvfPartitions(Math.round(Math.sqrt(rowCount)));
+    try {
+        await table.createIndex("vector", {
+            config: lancedb.Index.ivfPq({ numPartitions, numSubVectors }),
+        });
+    }
+    catch {
+        // Index training can fail on edge-case dimensionality or tiny effective
+        // corpora; the table remains usable via flat scan. Do not fail the ingest.
+    }
+}
+function clampIvfPartitions(value) {
+    return Math.min(MAX_IVF_PARTITIONS, Math.max(MIN_IVF_PARTITIONS, value));
 }
 export async function writeEmptyTextFiles(records, config) {
     const manifestPath = path.join(config.storageDir, EMPTY_TEXT_FILES_MANIFEST);

package/dist/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -56,6 +56,8 @@ export interface RedactionPattern {
     pattern: string;
     flags?: string | undefined;
     replacement?: string | undefined;
+    /** Optional post-match verification for patterns prone to false positives. */
+    verify?: "luhn" | undefined;
 }
 export interface RedactionCount {
     name: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "2.0.0";
+export declare const VERSION = "2.2.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "2.0.0";
+export const VERSION = "2.2.0";
 //# sourceMappingURL=version.js.map

package/examples/library-api-demo/README.md

@@ -25,7 +25,8 @@ That builds Ragmir Core, then runs the demo. It reuses the committed synthetic c
 `sovereign-rag-demo`, so it needs no private documents and writes only to that example's gitignored
 `.ragmir/storage`.
 
-To run it directly against the already-built `dist/` without rebuilding:
+To run it directly against the already-built `dist/` without rebuilding (run `pnpm build` first;
+`dist/` is gitignored, so a clean clone has none):
 
 ```bash
 node packages/ragmir-core/examples/library-api-demo/run.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcode.labs/ragmir",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Ragmir Core: open-source sovereign local RAG for confidential datasets and AI agents.",
   "type": "module",
   "license": "MIT",
@@ -68,7 +68,7 @@
     "unpdf": "^1.4.0",
     "yaml": "^2.9.0",
     "zod": "^4.1.13",
-    "@jcode.labs/ragmir-tts": "2.0.0"
+    "@jcode.labs/ragmir-tts": "2.2.0"
   },
   "devDependencies": {
     "@types/html-to-text": "^9.0.4",
@@ -79,9 +79,9 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "check": "tsc -p tsconfig.json --noEmit",
+    "check": "pnpm --filter @jcode.labs/ragmir-tts build && tsc -p tsconfig.json --noEmit",
     "mcp:smoke": "pnpm build && node scripts/mcp-smoke.mjs",
     "package:check": "publint",
-    "test": "vitest run"
+    "test": "pnpm --filter @jcode.labs/ragmir-tts build && vitest run"
   }
 }

package/skills/ragmir-audio-summary/SKILL.md

@@ -1,17 +1,35 @@
 ---
 name: ragmir-audio-summary
 description: >-
-  Create an optional spoken audio summary from a Ragmir local knowledge base. Use when the user asks
-  for an audio, TTS, spoken brief, briefing, narration, or listenable summary based on private
-  repository documents indexed by Ragmir. The skill is confidentiality-first: gather facts through
-  Ragmir, write only a temporary narration text file outside the repository, and render the final
-  audio under ignored local Ragmir state unless the user explicitly chooses another output path.
+  Create an intention-driven, memorable spoken audio summary from a Ragmir local knowledge base. Use
+  when the user asks for an audio, TTS, spoken brief, briefing, narration, or listenable summary
+  based on private repository documents indexed by Ragmir. The skill is confidentiality-first: it
+  filters everything against the user's intent, writes only a temporary narration text file outside
+  the repository, and renders the final audio under ignored local Ragmir state unless the user
+  explicitly chooses another output path.
 ---
 
 # Ragmir Audio Summary
 
-Use this skill to turn a confidential local Ragmir knowledge base into an optional audio summary.
-The knowledge base stays local; the final audio is a generated artifact and must not be committed.
+Use this skill to turn a confidential local Ragmir knowledge base into a spoken summary that
+respects the listener: only what serves their intent, structured to be intelligible in one pass, and
+designed to be retained.
+
+The knowledge base stays local. The final audio is a generated artifact and must not be committed.
+
+The goal is not a "basic summary read aloud". It is a deliberate narration built from five
+techniques:
+
+1. **Intent-first filtering** — drop everything that does not serve what the user actually needs.
+2. **Density-driven duration** — short for a small topic, long for a large one. Never pad.
+3. **Pyramid structure** — answer first, then the supporting points, then a recap.
+4. **Writing for the ear** — short sentences, spoken signposting, deliberate TTS punctuation.
+5. **Active recall** — two-to-three self-check questions that force retrieval and anchor memory.
+
+Two reference files sit next to this skill and are read while drafting:
+
+- `listening-style.md` — how to write prose a TTS engine can pronounce and a listener can follow.
+- `narration-templates.md` — skeletons per format, plus signposting and active-recall catalogues.
 
 ## Confidentiality Rules
 
@@ -25,7 +43,22 @@ The knowledge base stays local; the final audio is a generated artifact and must
 - Render audio under `.ragmir/audio/` by default. This directory is ignored by Git when Ragmir is installed.
 - Never stage or commit generated audio, temporary text, WAV, AIFF, or intermediate files.
 
-## 1. Verify The Knowledge Base
+## 1. Capture The Intent Before Searching
+
+Do not run any search yet. First make the intent explicit so every later step filters by it. Confirm
+with the user when it is ambiguous, or infer it from their request and state your assumption.
+
+Capture four things:
+
+- **Purpose** — what the listener will do with this: decide, learn, monitor, compare, or plan.
+- **Subject** — the precise question or topic, narrower than "summarize everything".
+- **Depth** — a quick scan or a deep dossier. Let the user steer, but default from the material.
+- **Language** — the spoken language, passed later to `--lang` (`fr` default, `en`, `es`).
+
+This is the guardrail against superfluous data: anything that does not advance the captured intent
+gets dropped at the drafting step, not added because it was "also in the documents".
+
+## 2. Verify The Knowledge Base
 
 From the repository root, run:
 
@@ -48,9 +81,10 @@ pnpm exec ragmir audit --unsupported
 has no warnings. Do not create an audio summary from stale or incomplete evidence unless the user
 explicitly accepts that limitation.
 
-## 2. Search Deeply Before Writing
+## 3. Search Deeply, Guided By The Intent
 
-Use Ragmir search or MCP tools to gather evidence before drafting the narration.
+Use Ragmir search or MCP tools to gather evidence, and derive the queries from the intent captured
+in step 1 — not from the subject alone.
 
 For a broad summary, run multiple searches:
 
@@ -63,26 +97,72 @@ pnpm exec ragmir ask "<specific synthesis question>" --top-k 8
 When MCP is available, prefer `ragmir_search`, `ragmir_ask`, `ragmir_audit`, and
 `ragmir_security_audit` over shell commands.
 
-Keep citations in your working notes, but do not read long raw passages aloud. The audio should be a
-clear synthesis, not a dump of source text.
+Keep citations in your working notes, but do not read long raw passages aloud. The audio is a clear
+synthesis, not a dump of source text.
+
+While searching, also gauge the **density of relevant material** for step 4:
+
+- How many passages directly serve the intent?
+- Do they overlap, reinforce, or contradict each other?
+- Are there clear facets (chapters) or one tight question?
+
+## 4. Choose The Format From The Density
+
+Pick the format from the relevant material found, not from a fixed default. Length follows material;
+never pad.
+
+| Format | Use when | Word budget | Duration |
+| --- | --- | --- | --- |
+| **Micro-brief** | One clear question or little relevant material | 150-220 words | ~60-90 s |
+| **Brief standard** | Moderate material, a few angles worth keeping | 450-750 words | ~3-5 min |
+| **Dossier long** | Dense, multi-faceted material needing chapters | 1500-3000 words | ~10-20 min |
+
+If two formats plausibly fit, prefer the shorter one unless the user asked for depth. A short,
+dense summary respects the listener more than a padded one.
+
+If the user explicitly asks for a long audio on a thin topic, say so in the final report and keep
+the narration tight rather than inflated.
+
+## 5. Write For Listening
+
+Write one flowing narration in the chosen language. No markdown, headings, bullets, tables, SSML, or
+XML tags in the spoken text. Open `listening-style.md` for the full rules; the cardinal ones:
+
+- **Pyramid first.** State the key message (one-to-four points to retain) up front, then develop it,
+  then recap it. This exploits primacy and recency.
+- **Signpost, do not list.** Use spoken transitions ("D'abord…, Ensuite…, Enfin…") instead of
+  enumerated lists. See `narration-templates.md` for the catalogue.
+- **Short sentences.** One idea per sentence, twenty words or fewer. Split long ones.
+- **Deliberate punctuation.** Periods for full pauses, commas for micro-pauses, `…` for the
+  deliberate beat before an active-recall answer. Avoid semicolons and exclamation marks.
+- **Pronounceable.** Expand acronyms on first use, write numbers and symbols in words, never read
+  URLs, paths, or code aloud.
+
+Read the draft aloud once at a normal pace. If you stumble or run out of breath, the sentence is too
+long or too dense — fix it.
 
-## 3. Write For Listening
+## 6. Anchor Memorability
 
-Write one flowing narration in the user's working language. Do not use markdown, headings, bullets,
-tables, SSML, XML tags, or stage directions in the spoken text.
+Build two devices into every narration, systematically:
 
-Good audio structure:
+1. **Recap the key points twice** — once right after the opening message, once at the very end.
+   Same points, compressed, in different words the second time.
+2. **Active recall** — end with self-check questions that force retrieval, not recognition:
+   - One question for a micro-brief, two-to-three for a standard brief, three-to-five for a dossier.
+   - Each question targets a key point from the recap, not a peripheral detail.
+   - Phrase so the answer is not leaked: "Quelle est la durée du préavis?" beats "Le préavis est-il
+     de trente jours?".
+   - After each question mark, insert `…` so the TTS pause gives the listener a beat to answer
+     silently, then state the answer in the fewest words possible.
 
-1. Start with the purpose of the summary and the two-to-four ideas to retain.
-2. Explain the current evidence in plain language.
-3. Separate proven facts from uncertainty.
-4. Highlight decisions, risks, deadlines, and missing documents.
-5. End with a concise recap and two or three self-check questions.
+For the full skeleton per format and the active-recall catalogue by intent, see
+`narration-templates.md`.
 
-Use short sentences and natural punctuation. Spell acronyms and symbols in a way a TTS engine can
-pronounce.
+Respect the Ragmir evidence separation in spoken form using language cues rather than formatting:
+state proven facts plainly, mark inferences ("Cela suggère que…"), mark uncertainty ("Reste à
+confirmer…"), and name missing documents.
 
-## 4. Render The Audio
+## 7. Render The Audio
 
 Create the output directory and write the narration to a temp file outside the repo:
 
@@ -140,11 +220,13 @@ Helper engine selection:
 
 Voice can be selected with `TTS_VOICE`. Speed for Edge can be selected with `TTS_RATE`.
 
-## 5. Report The Result
+## 8. Report The Result
 
 After rendering, report:
 
 - the audio path;
+- the **format chosen** (micro-brief, brief standard, dossier long) and the **intention served**;
+- the **estimated duration** (`word count / 140`) versus the target budget;
 - which renderer/model was used or requested;
 - whether remote model downloads or online TTS were allowed;
 - any evidence limitation, such as stale index, missing documents, or weak search results.

package/skills/ragmir-audio-summary/listening-style.md

@@ -0,0 +1,91 @@
+# Listening Style Guide
+
+Reference for the narration-writing step of `ragmir-audio-summary`. This file defines how to turn
+retrieved evidence into spoken text that a TTS engine can pronounce and a listener can follow and
+remember in one pass. There is no second chance to re-read audio.
+
+## Pacing And Duration
+
+- Conversational narration lands around **130-150 words per minute**. Plan on **140 words/minute**
+  as the working estimate.
+- Estimated duration = `word count / 140`. Keep a short narration under the target; never pad to
+  reach a target.
+- Per-format word budgets (use them as ceilings, not goals):
+
+| Format | Target duration | Word budget |
+| --- | --- | --- |
+| Micro-brief | ~60-90 s | 150-220 words |
+| Brief standard | ~3-5 min | 450-750 words |
+| Dossier long | ~10-20 min | 1500-3000 words |
+
+If the relevant material does not fill the budget, stop earlier. Padding makes audio undrinkable.
+
+## Sentence Shape
+
+- One idea per sentence. If you need "and" twice, split the sentence.
+- Aim for **20 words or fewer** per sentence. A few longer sentences are fine for rhythm; never chain
+  three long ones in a row.
+- Prefer subject-verb-object order. TTS engines and the human ear both handle it best.
+- Avoid stacked subordinate clauses and parentheticals. They trip the reader and the listener.
+
+  Before: "Le contrat, qui avait été signé, malgré des réserves émises tardivement, par les deux
+  parties, prévoit une rupture."
+
+  After: "Les deux parties ont signé le contrat, avec des réserves de dernière minute. Il prévoit
+  une rupture."
+
+## Punctuation For TTS
+
+Punctuation is the only cue a TTS engine has for pausing. Use it deliberately.
+
+- **Comma** `,` — short micro-pause. Use it to separate clauses and ease breathing points.
+- **Period** `.` — full pause. End sentences here. Favour periods over commas when in doubt.
+- **Ellipsis** `…` — deliberate longer pause. Use it before the answer in an active-recall question,
+  so the listener gets a beat to think (about three seconds).
+- **Colon** `:` — read as a mild pause; acceptable when introducing a short enumeration spoken as
+  prose, but prefer rephrasing into a plain sentence.
+- **Semicolon** `;` — avoid. Engines hesitate inconsistently. Split into two sentences.
+- **Exclamation** `!` — avoid for TTS. It can trigger an unnatural spike in pitch.
+- **Question mark** `?` — use it for the active-recall questions; the engine raises intonation
+  naturally.
+
+## Pronounceability
+
+Anything the engine might misread must be rewritten for the ear.
+
+- **Acronyms**: expand on first use, then use the short form if it is pronounceable. "Le RGPD, le
+  Règlement Général sur la Protection des Données, ..."
+- **Numbers**: write them the way they should be read. "1500" can read as "mille cinq cents" or
+  "quinze cents" — write the intended form. For money, spell the currency: "douze mille euros".
+- **Symbols**: rewrite in words. `&` becomes "et", `%` becomes "pour cent", `->` becomes "mène à".
+- **Dates and times**: write them fully. "Le quinze mars deux mille vingt-cinq", not "2025-03-15".
+- **URLs, paths, code**: never read them aloud. Paraphrase: "le fichier de configuration du
+  projet" instead of `ragmir/config.json`.
+- **Foreign terms**: if the term has no clean translation, introduce it once and keep it.
+
+## Anti-Patterns
+
+Avoid these — they are the main causes of "imbuvable" audio.
+
+- **Jargon without setup.** If a technical term is needed, define it in one short clause first.
+- **Spoken bullet lists.** Enumerations read aloud are exhausting. Convert lists into flowing
+  sentences with signposting ("D'abord…, Ensuite…, Pour finir…"). See `narration-templates.md`.
+- **Meta-commentary.** Drop "Dans ce résumé, nous allons parler de…". Open on the substance.
+- **Padding to reach a duration.** Restating the same idea in more words lowers density and respect
+  for the listener. Shorter is better than watered down.
+- **Reading raw source passages.** The audio is a synthesis, not a quote dump. Reformulate in plain
+  speech and keep the citation in your working notes, not in the narration.
+- **Overload.** More than ~4 new ideas in a brief is too many to retain. Group, merge, or defer.
+
+## Language
+
+- Write the narration in the same language passed to `--lang` (`fr` default, `en`, `es`).
+- Match the working language the user used when asking for the summary when it is one of the three
+  supported languages.
+- Keep numerals, units, and proper nouns pronounceable in the target language.
+
+## Self-Check Before Rendering
+
+Read the draft aloud once at a normal pace. If you stumble or run out of breath on a sentence, it is
+too long or too dense. Fix it, then estimate the duration with `word count / 140` and confirm it
+matches the chosen format's budget.