@jcode.labs/ragmir 2.1.0 → 2.2.0

package/dist/defaults.d.ts

@@ -7,7 +7,6 @@ export declare const CONFIG_PATH = ".ragmir/config.json";
 export declare const LEGACY_CONFIG_PATH = ".kb/config.json";
 export declare const DEFAULT_SKILL_TARGET_DIR = ".ragmir/skills";
 export declare const RAGMIR_PROJECT_ROOT_ENV = "RAGMIR_PROJECT_ROOT";
-export declare const SOURCES_FILE_HEADER: string[];
 export declare const RAGMIR_GITIGNORE_ENTRY = ".ragmir/";
 export declare const LEGACY_KB_GITIGNORE_ENTRY = ".kb/";
 export declare const LEGACY_PRIVATE_GITIGNORE_ENTRY = "private/";

package/dist/defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC,eAAO,MAAM,UAAU,YAAY,CAAA;AACnC,eAAO,MAAM,aAAa,QAAQ,CAAA;AAClC,eAAO,MAAM,kBAAkB,YAAY,CAAA;AAC3C,eAAO,MAAM,cAAc,gBAAsB,CAAA;AACjD,eAAO,MAAM,WAAW,wBAA8B,CAAA;AACtD,eAAO,MAAM,kBAAkB,oBAAiC,CAAA;AAChE,eAAO,MAAM,wBAAwB,mBAAyB,CAAA;AAE9D,eAAO,MAAM,uBAAuB,wBAAwB,CAAA;AAE5D,eAAO,MAAM,mBAAmB,UAM/B,CAAA;AAED,eAAO,MAAM,sBAAsB,aAAmB,CAAA;AACtD,eAAO,MAAM,yBAAyB,SAAsB,CAAA;AAC5D,eAAO,MAAM,8BAA8B,aAA2B,CAAA;AACtE,eAAO,MAAM,uCAAuC,eAA6B,CAAA;AAEjF,eAAO,MAAM,cAAc,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CA+BtD,CAAA;AAED,eAAO,MAAM,qBAAqB,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CAM7D,CAAA"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC,eAAO,MAAM,UAAU,YAAY,CAAA;AACnC,eAAO,MAAM,aAAa,QAAQ,CAAA;AAClC,eAAO,MAAM,kBAAkB,YAAY,CAAA;AAC3C,eAAO,MAAM,cAAc,gBAAsB,CAAA;AACjD,eAAO,MAAM,WAAW,wBAA8B,CAAA;AACtD,eAAO,MAAM,kBAAkB,oBAAiC,CAAA;AAChE,eAAO,MAAM,wBAAwB,mBAAyB,CAAA;AAE9D,eAAO,MAAM,uBAAuB,wBAAwB,CAAA;AAE5D,eAAO,MAAM,sBAAsB,aAAmB,CAAA;AACtD,eAAO,MAAM,yBAAyB,SAAsB,CAAA;AAC5D,eAAO,MAAM,8BAA8B,aAA2B,CAAA;AACtE,eAAO,MAAM,uCAAuC,eAA6B,CAAA;AAEjF,eAAO,MAAM,cAAc,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CA+BtD,CAAA;AAED,eAAO,MAAM,qBAAqB,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CAM7D,CAAA"}

package/dist/defaults.js

@@ -6,13 +6,6 @@ export const CONFIG_PATH = `${RAGMIR_DIR}/config.json`;
 export const LEGACY_CONFIG_PATH = `${LEGACY_KB_DIR}/config.json`;
 export const DEFAULT_SKILL_TARGET_DIR = `${RAGMIR_DIR}/skills`;
 export const RAGMIR_PROJECT_ROOT_ENV = "RAGMIR_PROJECT_ROOT";
-export const SOURCES_FILE_HEADER = [
-    "# Optional extra source paths or glob patterns, one per line.",
-    "# Relative paths resolve from the project root. Prefix glob exclusions with !.",
-    "# Example: ../apps/*/docs/**/*.md",
-    "# Example: !../apps/**/node_modules/**",
-    "",
-];
 export const RAGMIR_GITIGNORE_ENTRY = `${RAGMIR_DIR}/`;
 export const LEGACY_KB_GITIGNORE_ENTRY = `${LEGACY_KB_DIR}/`;
 export const LEGACY_PRIVATE_GITIGNORE_ENTRY = `${LEGACY_PRIVATE_DIR}/`;

package/dist/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAA;AACnC,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,CAAA;AAClC,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAS,CAAA;AAC3C,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,UAAU,MAAM,CAAA;AACjD,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,UAAU,cAAc,CAAA;AACtD,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,aAAa,cAAc,CAAA;AAChE,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,UAAU,SAAS,CAAA;AAE9D,MAAM,CAAC,MAAM,uBAAuB,GAAG,qBAAqB,CAAA;AAE5D,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,+DAA+D;IAC/D,gFAAgF;IAChF,mCAAmC;IACnC,wCAAwC;IACxC,EAAE;CACH,CAAA;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,UAAU,GAAG,CAAA;AACtD,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,aAAa,GAAG,CAAA;AAC5D,MAAM,CAAC,MAAM,8BAA8B,GAAG,GAAG,kBAAkB,GAAG,CAAA;AACtE,MAAM,CAAC,MAAM,uCAAuC,GAAG,GAAG,kBAAkB,KAAK,CAAA;AAEjF,MAAM,CAAC,MAAM,cAAc,GAAgC;IACzD,MAAM,EAAE,cAAc;IACtB,UAAU,EAAE,GAAG,UAAU,UAAU;IACnC,WAAW,EAAE,GAAG,UAAU,cAAc;IACxC,OAAO,EAAE,EAAE;IACX,aAAa,EAAE,GAAG,UAAU,aAAa;IACzC,kBAAkB,EAAE,GAAG,UAAU,SAAS;IAC1C,SAAS,EAAE,QAAQ;IACnB,iBAAiB,EAAE,YAAY;IAC/B,cAAc,EAAE,qCAAqC;IACrD,6BAA6B,EAAE,KAAK;IACpC,SAAS,EAAE;QACT,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,EAAE;KACb;IACD,SAAS,EAAE,IAAI;IACf,UAAU,EAAE,EAAE;IACd,IAAI,EAAE,CAAC;IACP,SAAS,EAAE,IAAI;IACf,YAAY,EAAE,GAAG;IACjB,YAAY,EAAE,UAAU;IACxB,iBAAiB,EAAE,CAAC;IACpB,kBAAkB,EAAE,EAAE;IACtB,iBAAiB,EAAE,EAAE;IACrB,aAAa,EAAE,EAAE;IACjB,eAAe,EAAE,OAAO;IACxB,eAAe,EAAE,EAAE;IACnB,iBAAiB,EAAE,OAAO;IAC1B,iBAAiB,EAAE,EAAE;IACrB,mBAAmB,EAAE,OAAO;CAC7B,CAAA;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAgC;IAChE,GAAG,cAAc;IACjB,MAAM,EAAE,kBAAkB;IAC1B,UAAU,EAAE,GAAG,aAAa,UAAU;IACtC,WAAW,EAAE,GAAG,aAAa,cAAc;IAC3C,aAAa,EAAE,GAAG,aAAa,aAAa;CAC7C,CAAA"}
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAA;AACnC,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,CAAA;AAClC,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAS,CAAA;AAC3C,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,UAAU,MAAM,CAAA;AACjD,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,UAAU,cAAc,CAAA;AACtD,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,aAAa,cAAc,CAAA;AAChE,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,UAAU,SAAS,CAAA;AAE9D,MAAM,CAAC,MAAM,uBAAuB,GAAG,qBAAqB,CAAA;AAE5D,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,UAAU,GAAG,CAAA;AACtD,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,aAAa,GAAG,CAAA;AAC5D,MAAM,CAAC,MAAM,8BAA8B,GAAG,GAAG,kBAAkB,GAAG,CAAA;AACtE,MAAM,CAAC,MAAM,uCAAuC,GAAG,GAAG,kBAAkB,KAAK,CAAA;AAEjF,MAAM,CAAC,MAAM,cAAc,GAAgC;IACzD,MAAM,EAAE,cAAc;IACtB,UAAU,EAAE,GAAG,UAAU,UAAU;IACnC,WAAW,EAAE,GAAG,UAAU,cAAc;IACxC,OAAO,EAAE,EAAE;IACX,aAAa,EAAE,GAAG,UAAU,aAAa;IACzC,kBAAkB,EAAE,GAAG,UAAU,SAAS;IAC1C,SAAS,EAAE,QAAQ;IACnB,iBAAiB,EAAE,YAAY;IAC/B,cAAc,EAAE,qCAAqC;IACrD,6BAA6B,EAAE,KAAK;IACpC,SAAS,EAAE;QACT,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,EAAE;KACb;IACD,SAAS,EAAE,IAAI;IACf,UAAU,EAAE,EAAE;IACd,IAAI,EAAE,CAAC;IACP,SAAS,EAAE,IAAI;IACf,YAAY,EAAE,GAAG;IACjB,YAAY,EAAE,UAAU;IACxB,iBAAiB,EAAE,CAAC;IACpB,kBAAkB,EAAE,EAAE;IACtB,iBAAiB,EAAE,EAAE;IACrB,aAAa,EAAE,EAAE;IACjB,eAAe,EAAE,OAAO;IACxB,eAAe,EAAE,EAAE;IACnB,iBAAiB,EAAE,OAAO;IAC1B,iBAAiB,EAAE,EAAE;IACrB,mBAAmB,EAAE,OAAO;CAC7B,CAAA;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAgC;IAChE,GAAG,cAAc;IACjB,MAAM,EAAE,kBAAkB;IAC1B,UAAU,EAAE,GAAG,aAAa,UAAU;IACtC,WAAW,EAAE,GAAG,aAAa,cAAc;IAC3C,aAAa,EAAE,GAAG,aAAa,aAAa;CAC7C,CAAA"}

package/dist/sources.d.ts

@@ -1,4 +1,5 @@
 export interface SourceEntriesResult {
+    /** Where the listed entries come from: always config.json now. */
     sourcesFile: string;
     entries: string[];
 }
@@ -7,10 +8,22 @@ export interface AddSourceEntriesOptions {
     entries: readonly string[];
 }
 export interface AddSourceEntriesResult {
+    /** config.json path the entries were written to. */
     sourcesFile: string;
     added: string[];
     skipped: string[];
 }
+/**
+ * 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 declare function listSourceEntries(cwd?: string): Promise<SourceEntriesResult>;
+/**
+ * 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 declare function addSourceEntries(options: AddSourceEntriesOptions): Promise<AddSourceEntriesResult>;
 //# sourceMappingURL=sources.d.ts.map

package/dist/sources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,wBAAsB,iBAAiB,CAAC,GAAG,SAAgB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAOzF;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CA+BjC"}
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,SAAgB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAczF;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAkCjC"}

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

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "2.1.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.1.0";
+export const VERSION = "2.2.0";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcode.labs/ragmir",
-  "version": "2.1.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.1.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.

package/skills/ragmir-audio-summary/narration-templates.md

@@ -0,0 +1,162 @@
+# Narration Templates
+
+Reference for the drafting step of `ragmir-audio-summary`. These are **thinking skeletons**, not
+output formatting. The final narration is plain flowing prose with no markdown, headings, bullets,
+tables, SSML, or XML tags. The skeletons below only shape how you order and connect ideas before you
+write the spoken text.
+
+Pick the format chosen in the skill, then fill the skeleton with the evidence that serves the user's
+intent. Drop anything that does not serve the intent — that is how you avoid superfluous data.
+
+## Format Selection Recap
+
+| Format | When to use | Word budget |
+| --- | --- | --- |
+| Micro-brief | Little relevant material, or one clear question | 150-220 words |
+| Brief standard | Moderate material, a few angles worth keeping | 450-750 words |
+| Dossier long | Dense, multi-faceted material needing chapters | 1500-3000 words |
+
+Length follows relevant material. Never pad.
+
+---
+
+## Micro-Brief Skeleton
+
+Spoken-prose shape (write it as one flowing passage, not as headings):
+
+1. **Hook + intent** — one sentence naming the subject and why the listener asked.
+2. **Key idea** — the single thing to remember, stated up front (primacy).
+3. **Evidence** — one short, plain-language reason or fact that supports it.
+4. **Uncertainty / caveat** — one sentence if the evidence is partial or stale; omit only if solid.
+5. **Recap + recall** — restate the key idea in other words, then ask one active-recall question,
+   pause with `…`, and give the answer.
+
+Abstract example (do not copy the words, follow the shape):
+
+> "Vous vouliez savoir si la clause de rupture est applicable. Oui, elle l'est, mais seulement après
+> un préavis de trente jours. Le contrat le prévoit explicitement à la section terminaison. En
+> revanche, la date de départ du préavis reste ambiguë, aucun courrier ne la fixe clairement.
+> Retenez donc une chose: rupture possible, préavis de trente jours, point de départ à confirmer.
+> Question: quelle est la durée du préavis prévu? … Trente jours."
+
+---
+
+## Brief Standard Skeleton (Pyramid + SCQA)
+
+The standard brief follows Barbara Minto's pyramid: answer first, then supporting points, then
+recap. Wrap it in a short Situation-Complication-Question-Answer opening.
+
+1. **Situation** — one or two sentences framing the context the listener already shares.
+2. **Complication** — the tension, change, or question that prompted the summary.
+3. **Question** — the explicit question the summary answers.
+4. **Answer (the key message)** — the one-to-three points to retain, stated first (primacy).
+5. **Developed points** — each of the two-to-four points expanded in plain speech, grouped with
+   signposting ("D'abord…, Ensuite…, Enfin…"). Proven facts only; separate from inference.
+6. **Uncertainty, risks, decisions, missing documents** — a short passage on what is not yet
+   settled or needs action.
+7. **Recap** — restate the two-to-four key points in compressed form (recency).
+8. **Active recall** — two or three recall questions, each followed by a `…` pause and the answer.
+
+Abstract example (shape only):
+
+> "Le projet a atteint sa phase de test. Le souci, c'est que deux blocages apparaissent en
+> parallèle. Faut-il continuer ou mettre en pause? La réponse tient en deux points: continuez sur
+> le module A, mais mettez en pause le module B. D'abord, le module A passe ses tests sans
+> régression. Ensuite, le module B dépend d'un composant externe encore instable. Ce qu'on ne sait
+> pas encore, c'est la date de livraison du composant externe. Donc retenez: module A en avant,
+> module B en attente, dépendance externe à confirmer. Première question: quel module peut
+> continuer sans risque? … Le module A. Deuxième question: pourquoi mettre en pause le module B? … À cause d'un
+> composant externe instable."
+
+---
+
+## Dossier Long Skeleton (Chaptered)
+
+Use only when the material genuinely has several distinct facets. Each chapter is a self-contained
+mini-brief with its own mini-recap, so a listener can step away and come back.
+
+1. **Promise** — what the whole audio covers and the three-to-five landmarks to listen for. State
+   the key message of the whole dossier up front.
+2. **Chapter 1** — signpost the chapter ("Premier point: …"). Give its mini pyramid
+   (answer → evidence → caveat), then a one-sentence mini-recap.
+3. **Chapter 2** — same shape, explicit transition ("Deuxième point: …").
+4. **Continue** for each facet. Keep chapters balanced in length; merge thin ones.
+5. **Global recap** — compress the key message of every chapter into one flowing passage (recency).
+6. **Active recall** — three to five recall questions across the chapters, each with a `…` pause
+   and the answer. Spread the questions across chapters, not only the last one.
+
+Transitions between chapters are essential in long audio — see the signposting catalogue below.
+
+Abstract shape:
+
+> "Ce dossier couvre les trois enjeux du contrat: la durée, la rupture, et les pénalités. En une
+> ligne: la durée est ferme, la rupture est conditionnée, les pénalités sont plafonnées. Premier
+> point: la durée. Le contrat court sur trois ans, fermes. … [chapitre] … Donc, durée ferme de
+> trois ans. Deuxième point: la rupture. … [chapitre] … Donc, rupture possible sous préavis.
+> Troisième point: les pénalités. … [chapitre] … Donc, pénalités plafonnées à dix pour cent. Pour
+> récapituler l'ensemble: trois ans fermes, rupture sous préavis, pénalités plafonnées. Première
+> question: quelle est la durée ferme du contrat? … Trois ans. …"
+
+---
+
+## Signposting Catalogue
+
+Signposting is the connective tissue that makes audio followable without visuals. Use these spoken
+transitions instead of lists or headings.
+
+| Move | Spoken cue (FR examples) |
+| --- | --- |
+| Open | "Voici l'essentiel sur…" / "Vous vouliez savoir si… La réponse courte est…" |
+| Enumerate | "D'abord…, Ensuite…, Enfin…" / "Il y a trois points…" (then speak each) |
+| Contrast | "En revanche…" / "Mais attention…" / "À l'inverse…" |
+| Cause / effect | "Parce que…" / "C'est pourquoi…" / "La conséquence est…" |
+| Emphasize | "Retenez ceci…" / "Le point clé, c'est…" |
+| Transition chapter | "Deuxième point…" / "Passons à…" / "Cela nous amène à…" |
+| Mini-recap | "En un mot…" / "Donc, pour ce point…" |
+| Close | "Pour récapituler…" / "En résumé…" |
+| Recall question | "Question: …? … [answer]" |
+
+When enumerating, say the count first ("trois points") then speak each one with "D'abord / Ensuite /
+Enfin" — never read a literal list.
+
+---
+
+## Active-Recall Question Catalogue
+
+Active recall forces the listener to retrieve from memory, which anchors retention far better than
+passive re-exposure. Phrase questions so they require **recall**, not recognition (no multiple
+choice, no "est-ce que c'est X?" with the answer embedded).
+
+### By intent
+
+| Intent | What to drill | Question shape (FR examples) |
+| --- | --- | --- |
+| Decide | The decision and its one main driver | "Quelle option recommande-t-on, et pourquoi?" |
+| Learn | The definitions and the one mechanism to remember | "Comment définit-on X, et qu'est-ce qui le déclenche?" |
+| Monitor | The thresholds and the alert condition | "À partir de quel seuil déclenche-t-on l'alerte?" |
+| Compare | The decisive differentiator | "Quelle est la principale différence entre A et B?" |
+| Plan | The next concrete action and its owner | "Quelle est la première action à mener, et par qui?" |
+
+### Rules
+
+- Two to three questions for a brief, three to five for a dossier. One is enough for a micro-brief.
+- Each question targets a key point from the recap, not a peripheral detail.
+- After the question mark, insert `…` so the TTS pause gives the listener a beat to answer silently,
+  then state the answer in the fewest words possible.
+- Do not reveal the answer inside the question. "Le préavis est-il de trente jours?" leaks the
+  answer — prefer "Quelle est la durée du préavis?".
+
+---
+
+## Evidence Separation In Spoken Form
+
+Spoken audio can still respect the Ragmir separation of evidence and inference. Use language cues,
+not formatting:
+
+- Proven fact: state plainly. "Le contrat fixe le préavis à trente jours."
+- Inference: mark it. "Cela suggère que…" / "On peut en déduire que…"
+- Uncertainty: mark it. "Ce qu'on ne sait pas encore, c'est…" / "Reste à confirmer…"
+- Missing document: name it. "Il manque le courrier de notification, donc…"
+- Decision / action: mark it. "La décision à prendre est…"
+
+This keeps the narration honest without leaning on tables or footnotes that audio cannot carry.