sdtk-brain-kit 0.1.0 → 0.1.1

package/README.md

@@ -6,7 +6,7 @@ layer (`wiki/`) that you — and your AI agent — can search, lint, and browse
 a graph. The agent reading the vault (per its `CLAUDE.md` contract) is the
 knowledge engine; this CLI provides the deterministic rails only.
 
-Package version in this source snapshot: `0.1.0`
+Package version in this source snapshot: `0.1.1`
 CLI command: `sdtk-brain`
 
 Standalone by design: not part of the `sdtk-kit` umbrella, installs no agent
@@ -29,7 +29,7 @@ cp ~/some-article.md raw/inbox/
 sdtk-brain ingest raw/inbox
 sdtk-brain compile --mode safe --apply
 sdtk-brain search "topic"
-sdtk-brain open                      # docs view + graph view (self-contained HTML)
+sdtk-brain open                      # docs view + graph view (local viewer, no server)
 ```
 
 ## Commands

package/assets/atlas/doc_atlas_viewer_template.html

@@ -1011,10 +1011,8 @@ body.panel-resizing [data-resizable]{transition:none!important;}
 </nav>
 
 <script src="./mermaid.min.js"></script>
+<script src="./viewer-data.js"></script>
 <script>
-const INDEX = __ATLAS_INDEX_JSON__;
-const GRAPH = __ATLAS_GRAPH_JSON__;
-const FAMILY_COLORS = __ATLAS_FAMILY_COLORS_JSON__;
 const FAMILY_GLYPHS = {
   'governance': 'G', 'product': 'P', 'spec': 'S', 'architecture': 'A', 'database': 'D',
   'api': 'I', 'qa': 'Q', 'design': 'L', 'dev': 'V', 'skill': 'K', 'template': 'T',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdtk-brain-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Standalone local-first second-brain vault CLI: immutable raw/ sources compiled into a markdown wiki/ knowledge layer, maintained by rails (ingest, compile, lint, search, graph viewer) while your agent is the knowledge engine.",
   "type": "commonjs",
   "bin": {

package/src/commands/enrich.js

@@ -24,6 +24,12 @@ Scope:
   Enriches EXTERNAL tool/repo candidates surfaced by the ingest/compile pipeline.
   Not related to your own project docs — those are indexed by "sdtk-brain atlas build".
 
+Options:
+  --source <source>       Required. Only "github" is supported in R1.
+  --mode <mode>           Required. Only "review" is supported in R1.
+  --project-path <path>   Project root. Defaults to the current directory.
+  -h, --help              Show this help.
+
 Safety:
   Review mode only in R1.
   No network fetch, page rewrite, source mutation, apply, entitlement change, or .brain-legacy-unused mutation.

package/src/commands/init.js

@@ -38,6 +38,10 @@ Scaffolds a second-brain vault:
   CLAUDE.md   the agent operating contract (how the vault is maintained)
   README.md   human orientation
 
+Options:
+  --vault <path>          Vault directory (defaults to the current directory).
+  -h, --help              Show this help.
+
 Safety:
   Defaults to the current directory as the vault. Refuses a target that is
   not empty unless it already looks like a vault (re-runs are idempotent and

package/src/commands/open.js

@@ -1,8 +1,10 @@
 "use strict";
 
 // `sdtk-brain open` — build the vault knowledge graph (shared atlas builder,
-// L-5) and open the self-contained viewer. The viewer is a single HTML file
-// with the graph JSON inlined, so file:// works without any server.
+// L-5) and open the viewer. The graph directory is self-contained
+// (viewer.html + viewer-data.js + mermaid.min.js, loaded by relative src),
+// so file:// works without any server (BK-321: data is a sibling script,
+// no longer inlined into a 28MB single file).
 
 const path = require("path");
 const { parseFlags } = require("../lib/args");
@@ -23,10 +25,16 @@ Usage:
   sdtk-brain open [--vault <path>] [--no-open]
 
 Builds the vault knowledge graph over wiki/ and raw/ (shared SDTK atlas
-builder) into .brain/graph and opens the self-contained viewer.html
-(docs view + graph view). --no-open builds without launching a browser.
+builder) into .brain/graph and opens the viewer (docs view + graph view).
+The output directory is self-contained: viewer.html loads its data from
+the sibling viewer-data.js. --no-open builds without launching a browser.
 
-Local-only: no server is required — the viewer inlines its data.`);
+Options:
+  --vault <path>          Vault directory (defaults to the current directory).
+  --no-open               Build without launching a browser.
+  -h, --help              Show this help.
+
+Local-only: no server is required — the viewer directory carries its data.`);
   return 0;
 }
 
@@ -46,7 +54,15 @@ async function cmdOpen(args) {
     return 1;
   }
 
-  const result = await buildAtlas({ projectRoot: vault, outputDir, scanRoots, excludes });
+  // BK-326: point the builder's pages/provenance workspace at .brain so no
+  // stray .sdtk tree ever lands in the vault root.
+  const result = await buildAtlas({
+    projectRoot: vault,
+    outputDir,
+    scanRoots,
+    excludes,
+    workspaceRoot: path.join(vault, ".brain"),
+  });
   const viewer = path.join(outputDir, "viewer.html");
   console.log(`[brain] Graph: ${result.node_count} nodes, ${result.edge_count} edges`);
   console.log(`[brain] Viewer: ${viewer}`);

package/src/commands/operations.js

@@ -110,7 +110,9 @@ Safety:
   No source mutation, local wiki page writes, graph rebuild, web fetch, Ask, raw/provenance mutation, or .brain-legacy-unused mutation.
 
 Next:
-  sdtk-brain compile --mode safe`);
+  sdtk-brain compile --mode safe
+
+Pass -h / --help on any verb to show its help.`);
   return 0;
 }
 

package/src/commands/search.js

@@ -30,6 +30,12 @@ Inputs:
   Duplicate coverage of the same source is de-duplicated; the atlas version wins.
   Each match reports its store (atlas | wiki).
 
+Options:
+  --project-path <path>   Vault directory (--vault works as an alias).
+  --json                  Emit the full result object as JSON.
+  --limit <n>             Maximum matches to display (default 10, max 50).
+  -h, --help              Show this help.
+
 Behavior:
   Read-only and non-premium.
   No wiki.ask entitlement is required.

package/src/commands/status.js

@@ -35,7 +35,7 @@ function countFiles(root, ext) {
 function cmdStatus(args) {
   const { flags } = parseFlags(args || [], STATUS_FLAG_DEFS);
   if (flags.help) {
-    console.log("Usage: sdtk-brain status [--vault <path>] — read-only vault status.");
+    console.log("Usage: sdtk-brain status [--vault <path>] [-h|--help] — read-only vault status.");
     return 0;
   }
   const vault = resolveProjectPath(flags.vault || process.cwd());

package/src/lib/wiki-build.js

@@ -7,7 +7,7 @@ const crypto = require("crypto");
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-const ATLAS_STATE_VERSION = 6;
+const ATLAS_STATE_VERSION = 7;
 const WIKI_PAGE_SCHEMA_VERSION = 1;
 const WIKI_PROVENANCE_SCHEMA_VERSION = 1;
 
@@ -514,13 +514,38 @@ function load_atlas_state(atlas_dir) {
   }
 }
 
+// BK-324: the cache exists to skip re-PARSING (reference extraction etc.),
+// not to duplicate content — doc bodies are dropped at save time and
+// rehydrated from the source file on reuse (safe: mtime/hash verified the
+// file is unchanged). Cut the state file ~80% on real corpora.
+function _slim_state_for_save(state) {
+  const documents = {};
+  for (const [rel, record] of Object.entries(state.documents || {})) {
+    if (record && typeof record === "object" && record.doc && typeof record.doc === "object") {
+      const doc = { ...record.doc };
+      delete doc.body_markdown;
+      documents[rel] = { ...record, doc };
+    } else {
+      documents[rel] = record;
+    }
+  }
+  return { ...state, documents };
+}
+
 function save_atlas_state(state, atlas_dir) {
   fs.mkdirSync(atlas_dir, { recursive: true });
   const state_path = _atlas_state_path(atlas_dir);
-  _write_text_lf(state_path, _escapeNonAscii(JSON.stringify(state, null, 2)));
+  _write_text_lf(state_path, _escapeNonAscii(JSON.stringify(_slim_state_for_save(state), null, 2)));
   return state_path;
 }
 
+function _rehydrate_doc_body(doc, md_file) {
+  if (doc.body_markdown != null) return doc;
+  const text = fs.readFileSync(md_file, { encoding: "utf8" });
+  doc.body_markdown = _parse_frontmatter(text)[1];
+  return doc;
+}
+
 function build_docs_incremental(root, atlas_dir, generated, scan_roots, exclude_frags) {
   const prior_state = load_atlas_state(atlas_dir);
   const prior_documents = prior_state.documents || {};
@@ -545,6 +570,7 @@ function build_docs_incremental(root, atlas_dir, generated, scan_roots, exclude_
 
     if (prior_record && typeof prior_record === "object" && prior_doc &&
         prior_record.mtime === current_mtime) {
+      _rehydrate_doc_body(prior_doc, md_file);
       next_documents[rel] = prior_record;
       reused_count++;
       continue;
@@ -553,6 +579,7 @@ function build_docs_incremental(root, atlas_dir, generated, scan_roots, exclude_
     const current_hash = _compute_file_hash(md_file);
     if (prior_record && typeof prior_record === "object" && prior_doc &&
         prior_record.hash === current_hash) {
+      _rehydrate_doc_body(prior_doc, md_file);
       next_documents[rel] = {
         mtime: current_mtime,
         hash: current_hash,
@@ -753,24 +780,37 @@ function build_summary(docs, graph, generated, stats, root, scan_roots, exclude_
 // ---------------------------------------------------------------------------
 // Viewer builder
 // ---------------------------------------------------------------------------
-function build_viewer(index, graph, generated) {
-  if (!fs.existsSync(_VIEWER_TEMPLATE_PATH)) {
-    throw new Error(`Viewer template not found: ${_VIEWER_TEMPLATE_PATH}`);
-  }
+// BK-321: the doc index/graph are written to a sibling viewer-data.js instead
+// of being inlined into viewer.html (which grew to ~28MB on real corpora).
+// The viewer already loads ./mermaid.min.js by relative src, so a sibling
+// data script works identically under file:// and the atlas server. Top-level
+// const bindings in a classic script are visible to later classic scripts,
+// so the template's main script keeps using INDEX/GRAPH/FAMILY_COLORS as-is.
+function build_viewer_data(index, graph) {
+  // String concatenation, not String.replace: replace's string form treats
+  // "$&", "$`", "$'", "$$", "$<n>" in doc content as special patterns and
+  // spliced garbage into the script (BK-317). Concatenation has no such
+  // semantics, so "$"-bearing content is inherently safe here.
   const index_json = _json_for_inline_script(index);
   const graph_json = _json_for_inline_script(graph);
   const family_colors_json = _json_for_inline_script(_FAMILY_COLORS);
+  return [
+    "// Generated by the SDTK atlas builder — regenerable via `atlas build`, do not edit.",
+    "const INDEX = " + index_json + ";",
+    "const GRAPH = " + graph_json + ";",
+    "const FAMILY_COLORS = " + family_colors_json + ";",
+    "",
+  ].join("\n");
+}
+
+function build_viewer(generated) {
+  if (!fs.existsSync(_VIEWER_TEMPLATE_PATH)) {
+    throw new Error(`Viewer template not found: ${_VIEWER_TEMPLATE_PATH}`);
+  }
   const template = fs.readFileSync(_VIEWER_TEMPLATE_PATH, "utf8");
-  // Replacer functions, not plain strings: String.prototype.replace treats a
-  // string replacement's "$&", "$`", "$'", "$$", "$<n>" sequences as special
-  // patterns. Indexed doc content routinely contains "$" (shell docs, prices,
-  // template-literal examples), which previously spliced stray template/JSON
-  // fragments into the inline script and broke it (BK-317).
-  return template
-    .replace(/__ATLAS_GENERATED__/g, () => generated)
-    .replace(/__ATLAS_INDEX_JSON__/g, () => index_json)
-    .replace(/__ATLAS_GRAPH_JSON__/g, () => graph_json)
-    .replace(/__ATLAS_FAMILY_COLORS_JSON__/g, () => family_colors_json);
+  // Replacer function per BK-317 discipline (timestamp is "$"-free today, but
+  // the string form's special-pattern hazard is not worth re-litigating).
+  return template.replace(/__ATLAS_GENERATED__/g, () => generated);
 }
 
 function copy_viewer_assets(atlas_dir) {
@@ -786,9 +826,13 @@ function copy_viewer_assets(atlas_dir) {
 // ---------------------------------------------------------------------------
 // Wiki pages + provenance
 // ---------------------------------------------------------------------------
-function _wiki_workspace_root(root) { return path.join(root, ".sdtk", "wiki"); }
-function _wiki_pages_root(root) { return path.join(_wiki_workspace_root(root), "pages"); }
-function _wiki_provenance_root(root) { return path.join(_wiki_workspace_root(root), "provenance"); }
+// BK-326: the workspace root is overridable so hosts with a different
+// machine-state home (sdtk-brain uses `.brain/`) don't get a stray
+// `.sdtk/wiki` tree leaked into their vault root. sdtk-wiki's default is
+// unchanged.
+function _wiki_workspace_root(root, workspace_root) {
+  return workspace_root ? path.resolve(workspace_root) : path.join(root, ".sdtk", "wiki");
+}
 
 function _stable_page_id(source_path) {
   const norm = source_path.replace(/\\/g, "/");
@@ -803,12 +847,12 @@ function _safe_slug(value) {
   return slug || "page";
 }
 
-function _page_relative_path(doc) {
+function _page_relative_path(doc, pages_prefix) {
   const source_path = String(doc.path).replace(/\\/g, "/");
   const source_digest = crypto.createHash("sha256").update(source_path, "utf8").digest("hex").slice(0, 8);
   const slug = _safe_slug(String(doc.title || path.parse(source_path).name));
   const family = _safe_slug(String(doc.family || "other-markdown"));
-  return `.sdtk/wiki/pages/${family}/${slug}--${source_digest}.md`;
+  return `${pages_prefix || ".sdtk/wiki/pages"}/${family}/${slug}--${source_digest}.md`;
 }
 
 function _yaml_quote(value) {
@@ -871,10 +915,16 @@ function _build_change_set(prior_hashes, current_hashes) {
   return { added, changed, unchanged, removed };
 }
 
-function write_wiki_pages_and_provenance(docs, state, root, generated, scan_roots) {
-  const workspace_root = _wiki_workspace_root(root);
-  const pages_root = _wiki_pages_root(root);
-  const provenance_root = _wiki_provenance_root(root);
+function write_wiki_pages_and_provenance(docs, state, root, generated, scan_roots, workspaceRoot) {
+  const workspace_root = _wiki_workspace_root(root, workspaceRoot);
+  const pages_root = path.join(workspace_root, "pages");
+  const provenance_root = path.join(workspace_root, "provenance");
+  // Page paths are recorded relative to the project root (posix separators)
+  // so provenance and _index.md stay portable.
+  const pages_prefix = path
+    .relative(root, pages_root)
+    .split(path.sep)
+    .join("/");
   const sources_path = path.join(provenance_root, "sources.json");
   const changes_path = path.join(provenance_root, "changes.json");
 
@@ -897,7 +947,7 @@ function write_wiki_pages_and_provenance(docs, state, root, generated, scan_root
       source_hash = crypto.createHash("sha256").update(source_path, "utf8").digest("hex");
     }
     const page_id = _stable_page_id(source_path);
-    const page_rel = _page_relative_path(doc);
+    const page_rel = _page_relative_path(doc, pages_prefix);
     const page_path = path.join(root, page_rel);
 
     _assert_inside(workspace_root, page_path);
@@ -971,7 +1021,7 @@ function write_wiki_pages_and_provenance(docs, state, root, generated, scan_root
 // ---------------------------------------------------------------------------
 // Top-level buildAtlas
 // ---------------------------------------------------------------------------
-async function buildAtlas({ projectRoot, outputDir, scanRoots, excludes, verbose } = {}) {
+async function buildAtlas({ projectRoot, outputDir, scanRoots, excludes, verbose, workspaceRoot } = {}) {
   const generated = _now_utc();
   const root = path.resolve(projectRoot);
   const atlas_dir = path.resolve(outputDir);
@@ -1008,7 +1058,7 @@ async function buildAtlas({ projectRoot, outputDir, scanRoots, excludes, verbose
   process.stdout.write(`[atlas] Graph: ${graph.nodes.length} nodes, ${graph.edges.length} edges.\n`);
 
   process.stdout.write("[atlas] Writing wiki pages and provenance...\n");
-  const wiki_result = write_wiki_pages_and_provenance(docs, state, root, generated, roots);
+  const wiki_result = write_wiki_pages_and_provenance(docs, state, root, generated, roots, workspaceRoot);
   process.stdout.write(`[atlas] Wiki pages: ${wiki_result.page_count}\n`);
 
   const index_data = {
@@ -1036,7 +1086,9 @@ async function buildAtlas({ projectRoot, outputDir, scanRoots, excludes, verbose
   const summary_path = path.join(atlas_dir, "SDTK_DOC_ATLAS_SUMMARY.md");
   _write_text_lf(summary_path, summary_text);
 
-  const viewer_html = build_viewer(index_data, graph_out, generated);
+  const viewer_data_js = build_viewer_data(index_data, graph_out);
+  _write_text_lf(path.join(atlas_dir, "viewer-data.js"), viewer_data_js);
+  const viewer_html = build_viewer(generated);
   const viewer_path = path.join(atlas_dir, "viewer.html");
   _write_text_lf(viewer_path, viewer_html);
 
@@ -1089,6 +1141,7 @@ module.exports = {
   build_graph,
   build_summary,
   build_viewer,
+  build_viewer_data,
   write_wiki_pages_and_provenance,
   load_atlas_state,
   save_atlas_state,