@gcunharodrigues/wrxn 0.2.1 → 0.3.0

package/bin/wrxn.cjs

@@ -12,6 +12,8 @@ const executor = require('../lib/executor.cjs');
 const onboard = require('../lib/onboard.cjs');
 const connect = require('../lib/connect.cjs');
 const statusline = require('../lib/statusline.cjs');
+const { convert } = require('../lib/convert.cjs');
+const { ingest } = require('../lib/ingest.cjs');
 
 const PKG_ROOT = path.join(__dirname, '..');
 
@@ -54,6 +56,8 @@ function parseArgs(argv) {
       args.flags.owner = argv[++i];
     } else if (a === '--probe') {
       args.flags.probe = argv[++i];
+    } else if (a === '--distillation') {
+      args.flags.distillation = argv[++i];
     } else if (a === '--check-report') {
       args.flags['check-report'] = true;
     } else if (a.startsWith('--')) {
@@ -112,6 +116,20 @@ Usage:
                                  resolved (or --path) statusline script, idempotently (append-only,
                                  never overwrites). init NEVER touches your statusline.
 
+  wrxn convert <file> [--cpu]    convert a source file to Markdown and print it. Per-format routing:
+                                 markitdown (html/docx/txt/pptx/xlsx) · docling (pdf, with automatic
+                                 CPU fallback on a GPU arch-crash) · pure-JS floor when Python is
+                                 absent. --cpu forces docling onto CPU from the first attempt.
+
+  wrxn ingest <file> [--distillation <result.json>] [--root <dir>]
+                                 distill a source into the memory wiki: convert (slice 05) → an LLM
+                                 (the ingest skill) produces a summary + N note pages → write them
+                                 to .wrxn/wiki/, each stamped derived_from the raw source, which is
+                                 kept under .wrxn/raw/. ADDITIVE-ONLY: an existing page is never
+                                 overwritten (re-runs are safe). --distillation feeds the skill's
+                                 result JSON (summary,notes); without it, the harness points you at
+                                 the ingest skill.
+
   wrxn onboard [--root <dir>]    scaffold the Day-1 operator file set under context/ from a filled
                                  aios-intake.md (the deterministic half of the onboard skill;
                                  workspace installs only). Idempotent.
@@ -120,7 +138,7 @@ Profiles: --project (default, the dev pipeline + intelligence + enforcement) |
           --workspace (adds the operator layer: onboard/audit/level-up + intake + decisions log +
           connections registry).`;
 
-function main(argv) {
+async function main(argv) {
   const args = parseArgs(argv);
 
   if (args.flags.version) {
@@ -294,6 +312,43 @@ function main(argv) {
     return 0;
   }
 
+  if (cmd === 'convert') {
+    const file = args._[1];
+    if (!file) { process.stderr.write('wrxn: convert requires <file>\n'); return 2; }
+    try {
+      const md = await convert(path.resolve(file), { gpu: args.flags.cpu ? false : undefined });
+      process.stdout.write(md.endsWith('\n') ? md : md + '\n');
+      return 0;
+    } catch (err) {
+      process.stderr.write(`wrxn: ${err.message}\n`);
+      return 2;
+    }
+  }
+
+  if (cmd === 'ingest') {
+    const file = args._[1];
+    if (!file) { process.stderr.write('wrxn: ingest requires <file>\n'); return 2; }
+    const root = path.resolve(args.flags.root || process.cwd());
+    // The distillation is the LLM step (the `ingest` skill). The CLI feeds its structured result via
+    // --distillation <result.json>; without one, the harness's defaultDistill points back to the skill.
+    let distill;
+    if (args.flags.distillation) {
+      const dpath = path.resolve(args.flags.distillation);
+      distill = () => JSON.parse(fs.readFileSync(dpath, 'utf8'));
+    }
+    try {
+      const report = await ingest(path.resolve(file), { root, ...(distill ? { distill } : {}) });
+      process.stdout.write(`wrxn ingest ${report.source} → raw ${report.raw}\n`);
+      for (const p of report.written) process.stdout.write(`  wrote   ${p}\n`);
+      for (const p of report.skipped) process.stdout.write(`  skipped ${p} (exists — additive-only, never clobbered)\n`);
+      process.stdout.write(`${report.written.length} written, ${report.skipped.length} skipped.\n`);
+      return 0;
+    } catch (err) {
+      process.stderr.write(`wrxn: ${err.message}\n`);
+      return 2;
+    }
+  }
+
   if (cmd === 'onboard') {
     const root = path.resolve(args.flags.root || process.cwd());
     let report;
@@ -397,4 +452,7 @@ function main(argv) {
   return 2;
 }
 
-process.exit(main(process.argv.slice(2)));
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => { process.stderr.write(`wrxn: ${err && err.message ? err.message : err}\n`); process.exit(1); }
+);

package/lib/convert.cjs

@@ -0,0 +1,215 @@
+'use strict';
+
+// Converter primitive (multiformat-distill-05) — convert(srcPath) → Markdown, per-format routing.
+//
+// Decision (ADR 0001 / PRD §5, empirically baked off): markitdown is the primary subprocess for the
+// office/web matrix (html/docx/pptx/xlsx); txt is a zero-dep pass-through; PDF escalates to docling
+// (SOTA tables + OCR), which auto-grabs the GPU and CRASHES on arch-incompat (the GTX-1070/Pascal
+// sm_61 trap — torch cu13x ships no sm_61 kernel) → we force CPU on that crash. When Python /
+// markitdown is absent (ENOENT) we degrade to the pure-JS floor (turndown / mammoth / unpdf / SheetJS).
+//
+// The spawn boundary is INJECTED, mirroring lib/connect.cjs's injectable `invoke`: convert(src,{run})
+// takes a converter runner so routing, ENOENT-degrade, and the CPU fallback are unit-testable WITHOUT
+// any real binary. defaultRun does the real spawnSync — that is what makes the integration check
+// "validated by invocation". convert is async only so the pure-JS floor (mammoth/unpdf are async)
+// can be wired in completely; the primary subprocess path is plain blocking spawnSync.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// Extension → logical format. (.htm folds into html.)
+const FORMATS = {
+  '.html': 'html',
+  '.htm': 'html',
+  '.docx': 'docx',
+  '.txt': 'txt',
+  '.pptx': 'pptx',
+  '.xlsx': 'xlsx',
+  '.pdf': 'pdf',
+};
+
+// CUDA / arch-incompat crash signatures — the Pascal sm_61 trap and friends. docling auto-grabs the
+// GPU; a torch build with no matching SM kernel dies with "no kernel image is available...".
+const ARCH_CRASH_RE = /no kernel image|kernel image is available|sm_\d+|CUDA error|CUDA_ERROR|device-side assert|out of memory/i;
+
+const SPAWN_OPTS = { encoding: 'utf8', timeout: 600000, maxBuffer: 256 * 1024 * 1024 };
+
+// ── the injected boundary's real implementation ────────────────────────────────
+
+/**
+ * Run a converter subprocess and normalize its result to { ok, markdown } | { ok:false, error }.
+ * error.code is 'ENOENT' (not installed → degrade), 'CRASH' (arch-incompat → CPU retry), or 'EXIT'.
+ */
+function defaultRun(tool, srcPath, { device } = {}) {
+  if (tool === 'markitdown') {
+    const r = spawnSync('markitdown', [srcPath], SPAWN_OPTS);
+    return normalize(r);
+  }
+  if (tool === 'docling') {
+    // docling writes <basename>.md into an --output dir (no markdown on stdout); read it back.
+    const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'wrxn-docling-'));
+    try {
+      const args = [srcPath, '--to', 'md', '--output', outDir];
+      const opts = { ...SPAWN_OPTS };
+      if (device === 'cpu') {
+        args.push('--device', 'cpu');
+        opts.env = { ...process.env, CUDA_VISIBLE_DEVICES: '' };
+      }
+      const r = spawnSync('docling', args, opts);
+      if (r.error) return { ok: false, error: classifyError(r.error) };
+      if (r.status !== 0 || r.signal) {
+        const stderr = r.stderr || '';
+        const code = ARCH_CRASH_RE.test(stderr) || r.signal ? 'CRASH' : 'EXIT';
+        return { ok: false, error: { code, status: r.status, signal: r.signal, message: stderr.trim() } };
+      }
+      return { ok: true, markdown: readDoclingOutput(outDir, srcPath) };
+    } finally {
+      fs.rmSync(outDir, { recursive: true, force: true });
+    }
+  }
+  throw new Error(`unknown converter tool: ${tool}`);
+}
+
+function normalize(r) {
+  if (r.error) return { ok: false, error: classifyError(r.error) };
+  if (r.status !== 0 || r.signal) {
+    return { ok: false, error: { code: 'EXIT', status: r.status, signal: r.signal, message: (r.stderr || '').trim() } };
+  }
+  return { ok: true, markdown: r.stdout };
+}
+
+function classifyError(err) {
+  return { code: err.code || 'ERR', message: err.message || String(err) };
+}
+
+function readDoclingOutput(outDir, srcPath) {
+  const base = path.basename(srcPath, path.extname(srcPath));
+  const preferred = path.join(outDir, `${base}.md`);
+  if (fs.existsSync(preferred)) return fs.readFileSync(preferred, 'utf8');
+  // Fall back to the first .md docling produced (naming can vary by version).
+  const md = fs.readdirSync(outDir).find((f) => f.toLowerCase().endsWith('.md'));
+  if (!md) throw new Error(`docling produced no markdown in ${outDir}`);
+  return fs.readFileSync(path.join(outDir, md), 'utf8');
+}
+
+// ── the pure-JS floor (no-Python degrade) ───────────────────────────────────────
+
+function lazy(mod) {
+  try {
+    return require(mod);
+  } catch {
+    throw new Error(
+      `pure-JS floor needs "${mod}" but it is not installed, and the primary converter is absent. ` +
+      `Install the primary path (pip install 'markitdown[all]' / docling) or the floor (npm i ${mod}).`
+    );
+  }
+}
+
+/** The no-Python in-process floor (research §2: turndown / mammoth / unpdf / SheetJS). Async. */
+async function defaultFloor(fmt, srcPath) {
+  if (fmt === 'txt') return fs.readFileSync(srcPath, 'utf8');
+  if (fmt === 'html') {
+    const Turndown = lazy('turndown');
+    const td = new Turndown();
+    try {
+      const { gfm } = require('turndown-plugin-gfm');
+      td.use(gfm);
+    } catch { /* gfm tables are a nice-to-have, not required */ }
+    return td.turndown(fs.readFileSync(srcPath, 'utf8'));
+  }
+  if (fmt === 'docx') {
+    const mammoth = lazy('mammoth');
+    const Turndown = lazy('turndown');
+    const { value: html } = await mammoth.convertToHtml({ path: srcPath });
+    return new Turndown().turndown(html);
+  }
+  if (fmt === 'pdf') {
+    const { extractText, getDocumentProxy } = lazy('unpdf');
+    const buf = new Uint8Array(fs.readFileSync(srcPath));
+    const pdf = await getDocumentProxy(buf);
+    const { text } = await extractText(pdf, { mergePages: true });
+    return text;
+  }
+  if (fmt === 'xlsx') {
+    const XLSX = lazy('xlsx');
+    const wb = XLSX.readFile(srcPath);
+    return wb.SheetNames.map((n) => `## ${n}\n\n${XLSX.utils.sheet_to_csv(wb.Sheets[n])}`).join('\n\n');
+  }
+  if (fmt === 'pptx') {
+    const officeParser = lazy('officeparser');
+    return await officeParser.parseOfficeAsync(srcPath);
+  }
+  throw new Error(`no pure-JS floor for format "${fmt}"`);
+}
+
+// ── the primitive ───────────────────────────────────────────────────────────────
+
+/**
+ * Convert a source file to Markdown via per-format routing.
+ * @param {string} srcPath
+ * @param {{ run?: Function, floor?: Function, gpu?: boolean }} [opts]
+ *   run   — injectable converter boundary (default: defaultRun, the real spawnSync).
+ *   floor — injectable pure-JS floor (default: defaultFloor).
+ *   gpu   — false forces docling onto CPU from the first attempt (skips the GPU probe/crash).
+ * @returns {Promise<string>} the markdown.
+ */
+async function convert(srcPath, { run = defaultRun, floor = defaultFloor, gpu } = {}) {
+  // Resolve to an absolute path up front so a leading-dash filename can never be read as a CLI flag
+  // by the converter subprocess — the dash-neutralization must not depend on the caller (slice-06
+  // ingest calls convert() directly, not via the CLI).
+  srcPath = path.resolve(srcPath);
+  // Pre-check existence up front (mirrors lib/ingest.cjs's source-not-found guard) so a missing file
+  // is rejected with a clean message and NEVER reaches the converter subprocess — whose Python
+  // traceback (markitdown/docling) would otherwise leak to the user verbatim (multiformat-distill-08).
+  if (!fs.existsSync(srcPath)) throw new Error(`wrxn convert: source not found: ${srcPath}`);
+  const ext = path.extname(srcPath).toLowerCase();
+  const fmt = FORMATS[ext];
+  if (!fmt) {
+    throw new Error(`wrxn convert: unsupported format "${ext || '(none)'}" — supported: ${Object.keys(FORMATS).join(', ')}`);
+  }
+
+  // txt is already plain text — pass it through (zero-dep, always works).
+  if (fmt === 'txt') {
+    return fs.readFileSync(srcPath, 'utf8');
+  }
+
+  if (fmt === 'pdf') {
+    return convertPdf(srcPath, { run, floor, gpu });
+  }
+
+  // markitdown-primary formats (html/docx/pptx/xlsx).
+  const r = run('markitdown', srcPath);
+  if (r.ok) return r.markdown;
+  if (r.error && r.error.code === 'ENOENT') {
+    return floor(fmt, srcPath); // markitdown absent → degrade to the pure-JS floor
+  }
+  throw new Error(`wrxn convert: markitdown failed on ${path.basename(srcPath)} — ${r.error.message || r.error.code}`);
+}
+
+/** PDF tier: docling (GPU/auto) → CPU on an arch-crash → pure-JS floor if docling is absent. */
+async function convertPdf(srcPath, { run, floor, gpu }) {
+  const firstDevice = gpu === false ? 'cpu' : undefined; // undefined = let docling pick (GPU/auto)
+  const r = run('docling', srcPath, { device: firstDevice });
+  if (r.ok) return r.markdown;
+  if (r.error && r.error.code === 'ENOENT') {
+    return floor('pdf', srcPath); // no docling → unpdf floor
+  }
+  if (r.error && r.error.code === 'CRASH' && firstDevice !== 'cpu') {
+    // arch-incompat / GPU crash → force CPU (CUDA_VISIBLE_DEVICES='' + --device cpu).
+    const cpu = run('docling', srcPath, { device: 'cpu' });
+    if (cpu.ok) return cpu.markdown;
+    if (cpu.error && cpu.error.code === 'ENOENT') return floor('pdf', srcPath);
+    throw new Error(`wrxn convert: docling failed on the CPU fallback for ${path.basename(srcPath)} — ${cpu.error.message || cpu.error.code}`);
+  }
+  throw new Error(`wrxn convert: docling failed on ${path.basename(srcPath)} — ${r.error.message || r.error.code}`);
+}
+
+module.exports = {
+  convert,
+  defaultRun,
+  defaultFloor,
+  FORMATS,
+  ARCH_CRASH_RE,
+};

package/lib/ingest.cjs

@@ -0,0 +1,174 @@
+'use strict';
+
+// Distillation ingest harness (multiformat-distill-06) — the deterministic half of `wrxn ingest`.
+//
+// PRD decisions D/E (grill 2026-06-16) + [[karpathy-llm-wiki-pattern]] (raw → distill → wiki, Adler):
+// a dropped source becomes a SUMMARY page + N NOTE pages in the memory wiki, each carrying a
+// `derived_from:` link back to the raw source. Additive-only: ingest CREATES new pages and refuses
+// to overwrite an existing one — editing existing knowledge + cross-source synthesis is the `dream`
+// loop (out of scope here).
+//
+// TWO boundaries are INJECTED, mirroring lib/convert.cjs's injectable spawn, so the harness is
+// deterministically testable WITHOUT a real binary OR a live LLM:
+//   - convert(src) → markdown          slice-05 converter primitive (default: the real convert).
+//   - distill(markdown, ctx) → pages   the LLM step. The `ingest` SKILL is the prompt that produces
+//                                       this; the harness only consumes its structured output, so the
+//                                       distillation QUALITY is validated by the feature QA-walk, not
+//                                       here. defaultDistill refuses to fabricate — it points the
+//                                       caller at the skill (or the CLI's --distillation feed).
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { convert: defaultConvert } = require('./convert.cjs');
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+const TIERS = ['concepts', 'decisions', 'gotchas', 'sessions'];
+const DEFAULT_TIER = 'concepts'; // distilled source knowledge lands in the concepts tier by default.
+const MAX_NOTES = 100;           // cap so a garbage distillation can't flood the wiki.
+// eslint-disable-next-line no-control-regex
+const CTRL_RE = /[\x00-\x1f]/;   // control chars (NL/CR/NUL/...) — illegal in a source filename.
+
+// Collapse a value to a single safe frontmatter scalar: strip control chars, fold whitespace.
+function safeScalar(v) {
+  // eslint-disable-next-line no-control-regex
+  return String(v || '').replace(/[\x00-\x1f]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+// The no-op default for the distill boundary: there is no deterministic LLM, so refuse rather than
+// fabricate. The real distillation is the `ingest` skill; the CLI feeds its result via --distillation.
+function defaultDistill() {
+  throw new Error(
+    'no distillation provided. The distillation step is the `ingest` skill (an LLM reads the ' +
+    'converted markdown and produces a summary + notes). Run via the ingest skill, feed a result ' +
+    'with --distillation <result.json>, or inject a distill boundary. See .claude/skills/ingest/SKILL.md.'
+  );
+}
+
+/** Flatten the distillation result into an ordered page list, validating the contract. */
+function normalizePages(result) {
+  if (!result || typeof result !== 'object') throw new Error('wrxn ingest: distillation returned no result object');
+  const summary = result.summary;
+  if (!summary || !summary.slug || !summary.body) {
+    throw new Error('wrxn ingest: distillation must include a summary page with { slug, body }');
+  }
+  const notes = Array.isArray(result.notes) ? result.notes : [];
+  if (notes.length > MAX_NOTES) {
+    throw new Error(`wrxn ingest: distillation produced ${notes.length} notes — cap is ${MAX_NOTES}. Refusing to flood the wiki.`);
+  }
+  const pages = [{ ...summary, role: 'summary' }, ...notes.map((n) => ({ ...n, role: 'note' }))];
+  for (const pg of pages) {
+    if (!pg.slug || !SLUG_RE.test(pg.slug)) {
+      throw new Error(`wrxn ingest: page slug must be kebab-case ([a-z0-9-]): "${pg.slug}"`);
+    }
+    pg.tier = pg.tier || DEFAULT_TIER;
+    if (!TIERS.includes(pg.tier)) {
+      throw new Error(`wrxn ingest: unknown tier "${pg.tier}" — one of ${TIERS.join(', ')}`);
+    }
+  }
+  // Intra-run dup: the DISTILLATION itself yielded two pages targeting one path. Distinct from the
+  // legit pre-existing-page skip (handled at write time via the wx/O_EXCL EEXIST path).
+  const seen = new Set();
+  for (const pg of pages) {
+    const key = `${pg.tier}/${pg.slug}`;
+    if (seen.has(key)) throw new Error(`wrxn ingest: duplicate slug in distillation: "${pg.slug}" (tier ${pg.tier})`);
+    seen.add(key);
+  }
+  return pages;
+}
+
+/** Render one wiki page: frontmatter (with the sanitized derived_from provenance stamp) + body. */
+function renderPage(pg, derivedFrom) {
+  return [
+    '---',
+    `name: ${pg.slug}`,
+    `description: ${safeScalar(pg.description)}`,
+    `tier: ${pg.tier}`,
+    `derived_from: ${safeScalar(derivedFrom)}`,
+    `role: ${pg.role}`,
+    'source: wrxn-ingest',
+    '---',
+    '',
+    `# ${pg.title || pg.slug}`,
+    '',
+    (pg.body || '').trim(),
+    '',
+  ].join('\n');
+}
+
+/**
+ * Ingest a source file into the memory wiki as a summary + N note pages.
+ * @param {string} srcPath
+ * @param {{ root?: string, convert?: Function, distill?: Function }} [opts]
+ *   root    — install root the wiki + raw zone live under (default: cwd).
+ *   convert — injectable converter boundary (default: slice-05 convert, the real spawnSync path).
+ *   distill — injectable distillation boundary (default: defaultDistill, which refuses to fabricate).
+ * @returns {Promise<{source:string, raw:string, written:string[], skipped:string[]}>}
+ */
+async function ingest(srcPath, { root, convert = defaultConvert, distill = defaultDistill } = {}) {
+  srcPath = path.resolve(srcPath);
+  if (!fs.existsSync(srcPath)) throw new Error(`wrxn ingest: source not found: ${srcPath}`);
+  root = path.resolve(root || process.cwd());
+
+  // ── fail-fast guards: everything cheap that can reject runs BEFORE convert + raw copy, so a pure
+  //    error path leaves NO stray work (no spawned converter, no dropped raw file). ──
+  const base = path.basename(srcPath);
+  if (CTRL_RE.test(base)) {
+    // a newline/control char in the filename would break out of the YAML frontmatter block.
+    throw new Error(`wrxn ingest: source filename contains control characters (invalid): ${JSON.stringify(base)}`);
+  }
+  // refuse a symlinked source: copyFileSync would follow it and copy an arbitrary readable file.
+  if (fs.lstatSync(srcPath).isSymbolicLink()) {
+    throw new Error(`wrxn ingest: source is a symlink (refused): ${srcPath}`);
+  }
+  // validate the distill boundary up front — `wrxn ingest <file>` with no distillation must NOT
+  // convert + drop a raw file before defaultDistill throws.
+  if (distill === defaultDistill) defaultDistill();
+
+  // 1. convert source → markdown (slice 05).
+  const markdown = await convert(srcPath);
+
+  // 2. place/keep the raw source under .wrxn/raw/. The filename is content-hash-namespaced so two
+  //    DIFFERENT sources sharing a basename never collide (provenance stays correct), while the SAME
+  //    bytes always map to the SAME name → idempotent re-run skips the copy.
+  const rawDir = path.join(root, '.wrxn', 'raw');
+  fs.mkdirSync(rawDir, { recursive: true });
+  const bytes = fs.readFileSync(srcPath);
+  const hash = crypto.createHash('sha256').update(bytes).digest('hex').slice(0, 8);
+  const ext = path.extname(base);
+  const stem = base.slice(0, base.length - ext.length);
+  const rawName = `${stem}.${hash}${ext}`;
+  const rawDest = path.join(rawDir, rawName);
+  if (!fs.existsSync(rawDest)) fs.writeFileSync(rawDest, bytes);
+  const derivedFrom = path.relative(root, rawDest).split(path.sep).join('/');
+
+  // 3. distill the markdown → { summary, notes } (validated: contract, note cap, intra-run dup slug).
+  const pages = normalizePages(await distill(markdown, { srcPath, derivedFrom }));
+
+  // 4. write pages ADDITIVELY. The wx flag (O_EXCL) makes the check-and-create atomic AND refuses to
+  //    follow a (dangling) symlink at the destination — EEXIST is the legit pre-existing-page skip.
+  const written = [];
+  const skipped = [];
+  for (const pg of pages) {
+    const dir = path.join(root, '.wrxn', 'wiki', pg.tier);
+    fs.mkdirSync(dir, { recursive: true });
+    const dest = path.join(dir, `${pg.slug}.md`);
+    const rel = path.relative(root, dest).split(path.sep).join('/');
+    try {
+      fs.writeFileSync(dest, renderPage(pg, derivedFrom), { flag: 'wx' });
+      written.push(rel);
+    } catch (err) {
+      if (err.code === 'EEXIST') { skipped.push(rel); continue; }
+      throw err;
+    }
+  }
+
+  return {
+    source: path.relative(root, srcPath).split(path.sep).join('/'),
+    raw: derivedFrom,
+    written,
+    skipped,
+  };
+}
+
+module.exports = { ingest, defaultDistill, normalizePages, DEFAULT_TIER, TIERS, MAX_NOTES };

package/manifest.json

@@ -148,6 +148,11 @@
       "class": "managed",
       "profile": "project"
     },
+    {
+      "path": ".claude/skills/ingest/SKILL.md",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".claude/skills/memory/SKILL.md",
       "class": "managed",
@@ -398,6 +403,11 @@
       "class": "state",
       "profile": "project"
     },
+    {
+      "path": ".wrxn/raw/.gitkeep",
+      "class": "state",
+      "profile": "project"
+    },
     {
       "path": ".wrxn/wiki.cjs",
       "class": "managed",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcunharodrigues/wrxn",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "WRXN Kernel — installable AI operating system. Two profiles (project | workspace), pull-based updates, managed/seeded/state file classes.",
   "bin": {
     "wrxn": "bin/wrxn.cjs"
@@ -16,7 +16,7 @@
     "test": "node --test"
   },
   "dependencies": {
-    "recon-wrxn": "6.0.0-wrxn.1"
+    "recon-wrxn": "6.0.0-wrxn.2"
   },
   "engines": {
     "node": ">=20"

package/payload/.claude/skills/ingest/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: ingest
+description: Distill a dropped source file (PDF/DOCX/HTML/PPTX/XLSX/TXT) into curated memory-wiki pages — a summary page + N note pages, each linked back to the raw source. Use when an operator drops a file in .wrxn/raw/ (or names one) and says "ingest this", "distill this document", or "turn this source into wiki notes".
+user-invocable: true
+---
+
+# ingest — read → distill → split into notes
+
+The distillation half of `wrxn ingest <file>`. Turns a raw source into compounding wiki knowledge,
+following the Karpathy LLM-wiki pattern (Adler's *How to Read a Book*: read → distill → split into
+notes). This is built as the first concrete slice of the Phase-3 `dream` ingest.
+
+The work is **split** (the kernel executor pattern):
+
+- **The harness is deterministic** (`lib/ingest.cjs` → `wrxn ingest`): convert the source to markdown,
+  place/keep the raw under `.wrxn/raw/`, write the pages you produce with a `derived_from:` provenance
+  stamp, and enforce the **additive-only** guard. You do NOT re-implement any of that.
+- **You are the distillation step.** You read the converted markdown and produce the *content* — a
+  summary page + N note pages. Your job is the curation quality.
+
+## Scope (PRD decision E)
+
+- **Inspectional + analytical depth**: 1 source → **1 summary page + N note pages**. Divide the source
+  into its natural documents (sections / themes), one note page each.
+- **Additive-only.** You CREATE new pages. You never edit an existing wiki page and never synthesise
+  across sources — that is the `dream` loop, out of scope. The harness refuses to overwrite, so a slug
+  that collides with an existing page is silently skipped: choose fresh, source-specific slugs.
+
+## Loop
+
+1. **Convert.** Read the converted markdown — either run `wrxn convert <file>` and read its output, or
+   read what the harness converted. Do not parse the binary yourself.
+2. **Read for the gist.** One pass for the whole; identify the source's structure and its key claims.
+3. **Summary page.** One page capturing what the source IS and its main points — the inspectional read.
+4. **Note pages.** One page per distinct theme/section — the analytical read. Each note is
+   self-contained and titled by its idea, not "Section 3".
+5. **Emit the result** as the structured object below and hand it to the harness.
+
+## Result contract
+
+The harness consumes this exact shape (the CLI accepts it via `--distillation <result.json>`):
+
+```json
+{
+  "summary": { "slug": "paper-summary", "title": "...", "description": "one line", "body": "markdown" },
+  "notes": [
+    { "slug": "paper-method",  "title": "...", "description": "one line", "body": "markdown" },
+    { "slug": "paper-results", "title": "...", "description": "one line", "body": "markdown" }
+  ]
+}
+```
+
+- `slug` — kebab-case (`[a-z0-9-]`), unique, source-specific (prefix with the source name to avoid
+  collisions). The harness rejects a non-kebab slug.
+- `summary` is required (`{slug, body}` minimum); `notes` is an array (≥1 in practice).
+- `tier` is optional per page (default `concepts`; may be `concepts|decisions|gotchas|sessions`).
+- The harness adds the `derived_from: .wrxn/raw/<file>` stamp, `role`, and `source: wrxn-ingest`
+  frontmatter — you do not write frontmatter into `body`.
+
+## Run
+
+```bash
+# the harness does convert → raw placement → provenance stamp → additive write:
+wrxn ingest .wrxn/raw/paper.pdf --distillation result.json
+```
+
+Re-running on the same source is safe — existing pages are skipped, never clobbered.
+
+## Source
+
+WRXN Kernel issue multiformat-distill-06 (PRD decisions D + E). Harness: `lib/ingest.cjs`.
+Converter: `lib/convert.cjs` (slice 05). Wiki: `.wrxn/wiki/` (see the `memory` skill).

package/payload/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "recon-wrxn": {
       "command": "npx",
-      "args": ["-y", "recon-wrxn@6.0.0-wrxn.1", "serve"]
+      "args": ["-y", "recon-wrxn@6.0.0-wrxn.2", "serve"]
     }
   }
 }