@sdsrs/llm-wiki 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.6.3 (2026-07-11)
+
+Two cosmetic fixes from an independent review of 0.6.0–0.6.2; no behavior
+change beyond the scan warning's rounding.
+
+- fix(scan): the tag-dispersion warning now flags on the same rounded top-tag
+  share it displays, so it can no longer print "top tag covers 30%" while
+  firing a "below 30%" rule. Effective threshold is 29.5% (was a raw 30% with
+  an inconsistent display); negligible for an advisory heuristic. Suite 178 →
+  179.
+- docs: note that the JSON Canvas map's `file` cards are vault-relative from the
+  KB root, so a canvas written outside the KB via `--out` won't resolve them in
+  Obsidian — open the canvas with the KB as its own vault.
+
+## 0.6.2 (2026-07-11)
+
+No breaking changes, no KB migration, no default-behavior change — one additive
+export format.
+
+- feat(export): `--format canvas` writes a JSON Canvas 1.0 file
+  (`<kb>/graph.canvas`) — a domain map of `file` cards laid out in columns by
+  page type (source / entity / concept / comparison / raw), ordered by link
+  degree, colored by type, with invalidated pages flagged red. The cards open
+  as live, clickable notes in Obsidian Canvas when the KB is opened as its own
+  vault. Zero-LLM, alongside the existing graphml / cypher / html / markdown
+  exports. Suite 174 → 178.
+
 ## 0.6.1 (2026-07-11)
 
 No breaking changes, no KB migration, no default-behavior change: the only

package/README.md

@@ -90,7 +90,7 @@ npx @sdsrs/llm-wiki@0 ask "what did we decide about X?"
 | `status` | incremental state: uncompiled raw files, source-dir diff, affected wiki pages |
 | `graph` | query `graph.json` with `path` / `neighbors` / `hubs` (zero-LLM traversal) |
 | `embed` | compute/update page embeddings (`wiki/.vectors.json`) for optional vector location |
-| `export` | export the graph as GraphML, Cypher, or an interactive HTML viewer; or the wiki as standard-markdown copies |
+| `export` | export the graph as GraphML, Cypher, JSON Canvas, or an interactive HTML viewer; or the wiki as standard-markdown copies |
 | `mcp` | run a read-only MCP server (stdio) over the KB |
 
 All commands take `--kb <dir>` (default `.`). `ask` supports `-k <n>` (pages to
@@ -145,6 +145,12 @@ relations:
 `lint` validates each relation target and type; `ambiguous` marks edges for a
 human to resolve.
 
+`export --format canvas` writes a JSON Canvas (`graph.canvas`) domain map —
+`file` cards laid out by page type that open as live notes in Obsidian Canvas.
+The card paths are vault-relative from the KB root, so open the canvas with the
+KB as its own vault; a canvas written outside the KB via `--out` won't resolve
+its cards.
+
 ### Skills (Claude Code / Codex)
 
 The bundled skills (`wiki-build`, `wiki-ingest`, `wiki-query`, `wiki-lint`,

package/bin/llm-wiki.mjs

@@ -128,9 +128,9 @@ program.command('install-skills')
   })
 
 program.command('export')
-  .description('export wiki/graph.json (graphml | cypher | html) or a markdown-links copy of the wiki (markdown)')
+  .description('export wiki/graph.json (graphml | cypher | html | canvas) or a markdown-links copy of the wiki (markdown)')
   .option('--kb <dir>', 'knowledge base root', '.')
-  .requiredOption('--format <format>', 'graphml | cypher | html | markdown')
+  .requiredOption('--format <format>', 'graphml | cypher | html | canvas | markdown')
   .option('--out <file>', 'output path (default: <kb>/graph.<ext>, or <kb>/wiki-md/ for markdown)')
   .action((opts) => {
     if (opts.format === 'markdown') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/llm-wiki",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Compile messy document directories into Karpathy-style llm_wiki knowledge bases — standalone Q&A CLI + Claude Code/Codex skills",
   "directories": {
     "test": "test"

package/src/export.mjs

@@ -236,13 +236,71 @@ step()
 `
 }
 
-const RENDERERS = { graphml: toGraphML, cypher: toCypher, html: toHtml }
+// JSON Canvas 1.0 (jsoncanvas.org) — an open node/edge format Obsidian Canvas and
+// other tools read. Nodes are `file` cards pointing at the real KB pages
+// (vault-relative from the KB root, where the .canvas is written), so opening the
+// map in Obsidian gives live, clickable notes. Layout is deterministic — one
+// column per node type, ordered by degree — so exports are stable and diffable.
+const CANVAS_COLORS = { source: '5', entity: '4', concept: '6', comparison: '2' } // JSON Canvas preset ids; raw/unknown → default gray
+const CANVAS_TYPE_ORDER = ['source', 'entity', 'concept', 'comparison', 'raw']
+const CANVAS_NODE_W = 260
+const CANVAS_NODE_H = 60
+const CANVAS_COL_GAP = 340
+const CANVAS_ROW_GAP = 90
+
+export function toCanvas(graph) {
+  const degree = new Map()
+  for (const e of graph.edges) for (const end of [e.source, e.target]) degree.set(end, (degree.get(end) ?? 0) + 1)
+
+  const cols = new Map()
+  for (const n of graph.nodes) {
+    const key = CANVAS_TYPE_ORDER.includes(n.type) ? n.type : 'raw'
+    if (!cols.has(key)) cols.set(key, [])
+    cols.get(key).push(n)
+  }
+  const rank = (t) => { const i = CANVAS_TYPE_ORDER.indexOf(t); return i === -1 ? CANVAS_TYPE_ORDER.length : i }
+  const colKeys = [...cols.keys()].sort((a, b) => rank(a) - rank(b))
+
+  const nodes = []
+  colKeys.forEach((key, ci) => {
+    const column = cols.get(key).sort((a, b) =>
+      (degree.get(b.id) ?? 0) - (degree.get(a.id) ?? 0) || a.id.localeCompare(b.id))
+    column.forEach((n, ri) => {
+      const node = {
+        id: n.id,
+        type: 'file',
+        file: n.id.startsWith('raw/') ? n.id : `wiki/${n.id}.md`,
+        x: ci * CANVAS_COL_GAP,
+        y: ri * CANVAS_ROW_GAP,
+        width: CANVAS_NODE_W,
+        height: CANVAS_NODE_H,
+      }
+      const color = n.status === 'invalidated' ? '1' : CANVAS_COLORS[n.type]
+      if (color) node.color = color
+      nodes.push(node)
+    })
+  })
+
+  const present = new Set(nodes.map(n => n.id))
+  const edges = graph.edges
+    .filter(e => present.has(e.source) && present.has(e.target))
+    .map((e, i) => {
+      const edge = { id: `e${i}`, fromNode: e.source, toNode: e.target }
+      if (e.type) edge.label = e.type
+      return edge
+    })
+
+  return JSON.stringify({ nodes, edges }, null, 2) + '\n'
+}
+
+const RENDERERS = { graphml: toGraphML, cypher: toCypher, html: toHtml, canvas: toCanvas }
+const EXT = { graphml: 'graphml', cypher: 'cypher', html: 'html', canvas: 'canvas' }
 
 export function exportGraph(kbRoot, { format, out } = {}) {
   const render = RENDERERS[format]
   if (!render) throw new Error(`unknown format: ${format} (expected ${Object.keys(RENDERERS).join(' | ')} | markdown)`)
   const graph = loadGraph(kbRoot)
-  const outPath = out ?? path.join(kbRoot, `graph.${format === 'graphml' ? 'graphml' : format === 'cypher' ? 'cypher' : 'html'}`)
+  const outPath = out ?? path.join(kbRoot, `graph.${EXT[format]}`)
   fs.writeFileSync(outPath, render(graph))
   return { out: outPath, nodeCount: graph.nodes.length, edgeCount: graph.edges.length }
 }

package/src/scanner.mjs

@@ -33,8 +33,12 @@ function detectDomainMixture(files, kbRoot) {
   if (pages.length >= TAG_MIN_PAGES) {
     const counts = new Map()
     for (const p of pages) for (const t of new Set(p.data.tags)) counts.set(t, (counts.get(t) ?? 0) + 1)
-    const topShare = Math.max(...counts.values()) / pages.length
-    tags = { pages: pages.length, distinct: counts.size, topShare: Number(topShare.toFixed(2)), flagged: topShare < TAG_TOP_SHARE_MIN }
+    // Round once and flag on the rounded value so the stored/displayed share
+    // (CLI prints Math.round(topShare*100)) never reads "30%" while the strict
+    // `< TAG_TOP_SHARE_MIN` rule fired on a raw 0.29x. Effective threshold is
+    // 29.5%; negligible for an advisory heuristic, and flag/display now agree.
+    const topShare = Number((Math.max(...counts.values()) / pages.length).toFixed(2))
+    tags = { pages: pages.length, distinct: counts.size, topShare, flagged: topShare < TAG_TOP_SHARE_MIN }
   }
   return { language, tags, flagged: language.flagged || (tags?.flagged ?? false) }
 }