sdtk-wiki-kit 0.1.1 → 0.1.2

package/README.md

@@ -28,6 +28,7 @@ Implemented in the Foundation/Beta package:
 | Capability | Command |
 |---|---|
 | Initialize SDTK-WIKI workspace | `sdtk-wiki init` |
+| Build a personal-brain without timestamp variables | `sdtk-wiki ingest`, `sdtk-wiki compile --mode safe --apply`, `sdtk-wiki query` |
 | Build graph, viewer, generated pages, and provenance | `sdtk-wiki atlas build` |
 | Open local viewer | `sdtk-wiki atlas open` |
 | Watch markdown sources and rebuild | `sdtk-wiki atlas watch` |
@@ -36,10 +37,13 @@ Implemented in the Foundation/Beta package:
 | Run non-destructive wiki lint | `sdtk-wiki lint` |
 | Run stale-page prune dry-run report | `sdtk-wiki wiki prune --dry-run` |
 | Generate local discovery plan from gap evidence | `sdtk-wiki wiki discover --plan` |
+| Generate local discovery plan with beginner facade | `sdtk-wiki discover --plan` |
+| Run report-first maintenance cycle | `sdtk-wiki maintain --mode safe` |
 | Generate semantic extraction dry-run report | `sdtk-wiki wiki extract --dry-run` |
 | Generate compile dry-run preview and JSON sidecar | `sdtk-wiki wiki compile --dry-run` |
 | Apply an approved compile JSON sidecar | `sdtk-wiki wiki compile --apply --yes` |
 | Search generated personal-brain pages locally | `sdtk-wiki search` |
+| Query generated personal-brain pages locally | `sdtk-wiki query` |
 | Ask grounded questions over built graph | `sdtk-wiki ask` with `wiki.ask` entitlement/runtime preconditions |
 | Save one redacted query record after successful Ask | `sdtk-wiki ask --save-query` with `wiki.ask` entitlement/runtime preconditions |
 
@@ -91,6 +95,41 @@ Open the viewer:
 sdtk-wiki atlas open --project-path .
 ```
 
+## Simple Personal-Brain Flow
+
+Use this when you want the shortest local second-brain path and do not need to
+inspect timestamped JSON files:
+
+```powershell
+sdtk-wiki init --no-open
+sdtk-wiki ingest .\source-md
+sdtk-wiki compile --mode safe --apply
+sdtk-wiki query "multi-agent"
+sdtk-wiki lint
+sdtk-wiki discover --plan
+sdtk-wiki maintain --mode safe
+```
+
+Behavior:
+
+- `ingest` runs local semantic extraction and writes a report.
+- `compile --mode safe --apply` creates or refreshes the compile preview/JSON
+  sidecar internally, then applies the sidecar contract.
+- `query` is deterministic local search over `.sdtk/wiki/personal-brain`; it
+  does not use premium Ask, LLM/RAG, web fetch, or query history.
+- `discover` and `maintain` are report-first and do not apply, delete, archive,
+  fetch web sources, or mutate `.sdtk/atlas`.
+
+Interactive viewer flow:
+
+```powershell
+sdtk-wiki init
+```
+
+Bare `sdtk-wiki init` may open/start the viewer and keep the terminal session
+active. Use `sdtk-wiki init --no-open` for automation, CI, and local
+non-interactive validation.
+
 ## Command Reference
 
 ### Init
@@ -131,6 +170,20 @@ Safety:
 - no generated page updates
 - no graph/viewer rebuild side effects
 
+### Beginner Ingest Operation
+
+```powershell
+sdtk-wiki ingest <source-root> [--project-path <path>]
+sdtk-wiki ingest --source-root <source-root> [--project-path <path>]
+```
+
+Runs semantic extraction over a local Markdown source root and writes the latest
+`semantic-extraction-dry-run-*.json` report under `.sdtk/wiki/reports`.
+
+This is the beginner-friendly facade for `sdtk-wiki wiki extract --dry-run`.
+It does not mutate source files, personal-brain pages, raw/provenance state,
+graph outputs, web sources, Ask state, or `.sdtk/atlas`.
+
 ### Lint
 
 ```powershell
@@ -167,6 +220,15 @@ Safety:
 - no compile/apply
 - no prune/delete/archive
 
+Beginner facade:
+
+```powershell
+sdtk-wiki discover --plan [--project-path <path>]
+```
+
+This uses the same local-only discovery plan behavior and report-first safety
+boundary.
+
 ### Semantic Extraction Dry-Run
 
 ```powershell
@@ -212,6 +274,24 @@ Supported operation types:
 Unknown operation types are reported as `unsupported_operation`. Dry-run does
 not modify wiki pages, raw sources, provenance, or `.sdtk/atlas`.
 
+### Beginner Compile Operation
+
+```powershell
+sdtk-wiki compile --mode safe [--project-path <path>]
+sdtk-wiki compile --mode safe --apply [--project-path <path>]
+```
+
+The beginner facade hides timestamped JSON paths:
+
+- without `--apply`, it finds the latest semantic extraction report and writes
+  the compile preview plus JSON sidecar
+- with `--apply`, it finds the latest sidecar or creates one from the latest
+  extraction report, then applies through the same sidecar-only contract
+
+`safe` is the only R1 mode. Auto mode, destructive cleanup, web fetch, Ask, raw
+mutation, provenance mutation, source mutation, and `.sdtk/atlas` mutation are
+not performed.
+
 ### Compile Apply
 
 ```powershell
@@ -245,6 +325,15 @@ Search is deterministic, read-only, and non-premium. It does not require
 `wiki.ask` entitlement, does not call an LLM/RAG runtime, does not write query
 history, and does not mutate project files.
 
+Beginner query facade:
+
+```powershell
+sdtk-wiki query --project-path <path> "<query>"
+```
+
+`query` is the simple local search command. It is not premium Ask and does not
+require `wiki.ask`.
+
 ### Ask
 
 ```powershell
@@ -290,8 +379,8 @@ Run report-first maintenance checks:
 
 ```powershell
 sdtk-wiki lint --project-path .
-sdtk-wiki wiki prune --dry-run --project-path .
-sdtk-wiki wiki discover --plan --project-path .
+sdtk-wiki discover --plan --project-path .
+sdtk-wiki maintain --mode safe --project-path .
 ```
 
 Preview a compile plan without applying it:
@@ -302,6 +391,14 @@ sdtk-wiki wiki compile --plan <local-plan.md-or-json> --project-path . --dry-run
 
 Build a personal-brain from local Markdown sources and search it:
 
+```powershell
+sdtk-wiki ingest docs
+sdtk-wiki compile --mode safe --apply
+sdtk-wiki query "multi-agent"
+```
+
+Advanced/audit workflow with explicit report files:
+
 ```powershell
 sdtk-wiki wiki extract --project-path . --source-root docs --dry-run
 sdtk-wiki wiki compile --project-path . --plan .sdtk/wiki/reports/semantic-extraction-dry-run-<stamp>.json --dry-run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdtk-wiki-kit",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Project-local wiki and knowledge graph toolkit for SDTK workspaces.",
   "bin": {
     "sdtk-wiki": "bin/sdtk-wiki.js"

package/src/commands/help.js

@@ -7,6 +7,11 @@ Usage:
   sdtk-wiki --help
   sdtk-wiki --version
   sdtk-wiki init --help
+  sdtk-wiki ingest --help
+  sdtk-wiki compile --help
+  sdtk-wiki query --help
+  sdtk-wiki discover --help
+  sdtk-wiki maintain --help
   sdtk-wiki atlas build --help
   sdtk-wiki atlas open --help
   sdtk-wiki atlas watch --help
@@ -19,8 +24,22 @@ Usage:
   sdtk-wiki search --help
   sdtk-wiki lint --help
 
+Simple personal-brain workflow:
+  sdtk-wiki init --no-open
+  sdtk-wiki ingest <source-root>
+  sdtk-wiki compile --mode safe [--apply]
+  sdtk-wiki query "<query>"
+  sdtk-wiki lint
+  sdtk-wiki discover --plan
+  sdtk-wiki maintain --mode safe
+
 R1 command model:
   init                 Initialize the SDTK-WIKI workspace.
+  ingest               Run local semantic extraction without handling timestamped JSON.
+  compile              Run safe personal-brain compile preview, optionally apply.
+  query                Search generated personal-brain pages locally without premium Ask.
+  discover             Write a local-only discovery plan from WIKI gap evidence.
+  maintain             Run safe lint, discover, and compile-preview maintenance reports.
   atlas build          Build graph/viewer plus local wiki pages/provenance.
   atlas open           Open or serve the local graph viewer.
   atlas watch          Watch markdown sources and rebuild the graph.
@@ -33,6 +52,12 @@ R1 command model:
   search               Search generated personal-brain pages locally without premium Ask.
   lint                 Write a report-first, non-destructive wiki lint report.
 
+Advanced/audit workflow:
+  sdtk-wiki wiki extract --source-root <source-root> --dry-run
+  sdtk-wiki wiki compile --plan <extract-json> --dry-run
+  sdtk-wiki wiki compile --plan <apply-json> --apply --yes
+  sdtk-wiki search "<query>"
+
 Workspace paths:
   .sdtk/wiki           New SDTK-WIKI workspace target.
   .sdtk/wiki/graph     New SDTK-WIKI graph output target.
@@ -53,10 +78,13 @@ Premium Ask:
                        Query history, discover, compile, and cleanup automation are not enabled in R1.
 
 Local Search:
+  sdtk-wiki query      Beginner-friendly local deterministic search over .sdtk/wiki/personal-brain.
   sdtk-wiki search     Deterministic, read-only local search over .sdtk/wiki/personal-brain.
                        Does not require wiki.ask entitlement and does not perform LLM/RAG behavior.
 
 Maintenance:
+  sdtk-wiki discover --plan is a top-level alias for local-only discovery planning.
+  sdtk-wiki maintain --mode safe runs report-first lint/discover/compile-preview checks without apply.
   sdtk-wiki wiki prune --dry-run is report-only and writes under .sdtk/wiki/reports.
   It never deletes, archives, applies, or mutates .sdtk/atlas.`);
   console.log(`

package/src/commands/operations.js

@@ -0,0 +1,345 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { parseFlags } = require("../lib/args");
+const { CliError, ValidationError } = require("../lib/errors");
+const { runWikiCompileApply, runWikiCompileDryRun } = require("../lib/wiki-compile");
+const { runWikiDiscoverPlan } = require("../lib/wiki-discover");
+const { runWikiExtractDryRun } = require("../lib/wiki-extract");
+const { runWikiLint } = require("../lib/wiki-lint");
+const { runWikiSearch } = require("../lib/wiki-search");
+const { getWikiReportsPath, resolveProjectPath } = require("../lib/wiki-paths");
+const { printHumanResult } = require("./search");
+
+const INGEST_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  "project-path": { type: "string" },
+  "source-root": { type: "string" },
+};
+
+const COMPILE_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  "project-path": { type: "string" },
+  mode: { type: "string" },
+  apply: { type: "boolean" },
+};
+
+const QUERY_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  "project-path": { type: "string" },
+  json: { type: "boolean" },
+  limit: { type: "string" },
+};
+
+const DISCOVER_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  "project-path": { type: "string" },
+  plan: { type: "boolean" },
+};
+
+const MAINTAIN_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  "project-path": { type: "string" },
+  mode: { type: "string" },
+};
+
+function ensureProjectPath(projectPath) {
+  const resolved = resolveProjectPath(projectPath || process.cwd());
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+    throw new ValidationError(`--project-path is not a valid directory: ${resolved}`);
+  }
+  return resolved;
+}
+
+function ensureSafeMode(mode, commandName) {
+  const resolvedMode = mode || "safe";
+  if (resolvedMode !== "safe") {
+    throw new ValidationError(
+      `sdtk-wiki ${commandName} supports only --mode safe in R1. Auto mode is deferred. No project files were changed.`
+    );
+  }
+  return resolvedMode;
+}
+
+function findLatestReport(projectPath, pattern) {
+  const reportsPath = getWikiReportsPath(projectPath);
+  if (!fs.existsSync(reportsPath) || !fs.statSync(reportsPath).isDirectory()) {
+    return null;
+  }
+  const matcher = new RegExp(`^${pattern}$`);
+  const files = fs.readdirSync(reportsPath)
+    .filter((name) => matcher.test(name))
+    .map((name) => {
+      const filePath = path.join(reportsPath, name);
+      return { filePath, mtimeMs: fs.statSync(filePath).mtimeMs };
+    })
+    .sort((a, b) => {
+      if (b.mtimeMs !== a.mtimeMs) return b.mtimeMs - a.mtimeMs;
+      return b.filePath.localeCompare(a.filePath);
+    });
+  return files.length > 0 ? files[0] : null;
+}
+
+function latestExtraction(projectPath) {
+  return findLatestReport(projectPath, "semantic-extraction-dry-run-.*\\.json");
+}
+
+function latestApplyPlan(projectPath) {
+  return findLatestReport(projectPath, "compile-apply-plan-.*\\.json");
+}
+
+function cmdIngestHelp() {
+  console.log(`SDTK-WIKI Ingest
+
+Usage:
+  sdtk-wiki ingest <source-root> [--project-path <path>]
+  sdtk-wiki ingest --source-root <path> [--project-path <path>]
+
+Purpose:
+  Run local semantic extraction over a Markdown source root and write a report under .sdtk/wiki/reports.
+
+Safety:
+  Local sources only.
+  No source mutation, personal-brain page writes, graph rebuild, web fetch, Ask, raw/provenance mutation, or .sdtk/atlas mutation.
+
+Next:
+  sdtk-wiki compile --mode safe`);
+  return 0;
+}
+
+function cmdCompileHelp() {
+  console.log(`SDTK-WIKI Compile
+
+Usage:
+  sdtk-wiki compile --mode safe [--project-path <path>]
+  sdtk-wiki compile --mode safe --apply [--project-path <path>]
+
+Purpose:
+  Use the latest semantic extraction report to write a compile preview and JSON sidecar, then optionally apply the sidecar.
+
+Safety:
+  Safe mode is the only R1 mode.
+  --apply still uses the existing JSON sidecar contract.
+  No delete, archive, rewrite, raw/provenance mutation, source mutation, web fetch, Ask, or .sdtk/atlas mutation.`);
+  return 0;
+}
+
+function cmdQueryHelp() {
+  console.log(`SDTK-WIKI Query
+
+Usage:
+  sdtk-wiki query [--project-path <path>] [--json] [--limit <n>] "<query>"
+
+Purpose:
+  Deterministically search generated personal-brain Markdown pages.
+
+Behavior:
+  Local search only.
+  No wiki.ask entitlement, LLM/RAG runtime, query history, or project mutation.
+  Use sdtk-wiki ask for premium grounded Q&A when wiki.ask preconditions are available.`);
+  return 0;
+}
+
+function cmdDiscoverHelp() {
+  console.log(`SDTK-WIKI Discover
+
+Usage:
+  sdtk-wiki discover --plan [--project-path <path>]
+
+Purpose:
+  Write a local-only discovery plan from existing wiki gap evidence.
+
+Safety:
+  Plan-only. No web fetch, source ingest, compile, apply, prune, delete, archive, query history, Ask, or .sdtk/atlas mutation.`);
+  return 0;
+}
+
+function cmdMaintainHelp() {
+  console.log(`SDTK-WIKI Maintain
+
+Usage:
+  sdtk-wiki maintain --mode safe [--project-path <path>]
+
+Purpose:
+  Run a report-first maintenance cycle: lint, discover plan, and compile preview when an extraction report exists.
+
+Safety:
+  Safe mode only.
+  No apply, delete, archive, source mutation, web fetch, Ask, query history, or .sdtk/atlas mutation.`);
+  return 0;
+}
+
+function resolveSourceRoot(flags, positional) {
+  if (flags["source-root"]) return flags["source-root"];
+  if (positional.length === 1) return positional[0];
+  if (positional.length > 1) {
+    throw new ValidationError("sdtk-wiki ingest accepts one source root. Quote paths that contain spaces. No project files were changed.");
+  }
+  throw new ValidationError("sdtk-wiki ingest requires <source-root> or --source-root <path>. No project files were changed.");
+}
+
+function cmdIngest(args) {
+  const { flags, positional } = parseFlags(args || [], INGEST_FLAG_DEFS);
+  if (flags.help) return cmdIngestHelp();
+  const projectPath = ensureProjectPath(flags["project-path"]);
+  const result = runWikiExtractDryRun({
+    projectPath,
+    sourceRootArg: resolveSourceRoot(flags, positional),
+  });
+  const extraction = result.extraction;
+
+  console.log(`[wiki] Semantic extraction report: ${result.reportPath}`);
+  console.log(`[wiki] Sources scanned: ${extraction.source_counts.scanned}`);
+  console.log(`[wiki] Sources indexed: ${extraction.source_counts.indexed}`);
+  console.log(`[wiki] Tool candidates: ${extraction.tool_entities.length}`);
+  console.log(`[wiki] Concept candidates: ${extraction.concepts.length}`);
+  console.log(`[wiki] Quality findings: ${extraction.source_quality_findings.length}`);
+  console.log("[wiki] No source files, personal-brain pages, raw/provenance state, graph outputs, or atlas compatibility files were modified.");
+  console.log("[wiki] Next: sdtk-wiki compile --mode safe");
+  return 0;
+}
+
+function runCompileDryRunFromLatestExtraction(projectPath) {
+  const extraction = latestExtraction(projectPath);
+  if (!extraction) {
+    throw new ValidationError(
+      "No semantic extraction report found. Run \"sdtk-wiki ingest <source-root>\" first. No project files were changed."
+    );
+  }
+  return runWikiCompileDryRun({ projectPath, planArg: extraction.filePath });
+}
+
+function ensureApplySidecar(projectPath) {
+  const extraction = latestExtraction(projectPath);
+  const sidecar = latestApplyPlan(projectPath);
+  if (!sidecar && !extraction) {
+    throw new ValidationError(
+      "No compile apply sidecar or semantic extraction report found. Run \"sdtk-wiki ingest <source-root>\" first. No project files were changed."
+    );
+  }
+  if (!sidecar || (extraction && extraction.mtimeMs > sidecar.mtimeMs)) {
+    const dryRun = runCompileDryRunFromLatestExtraction(projectPath);
+    return {
+      sidecarPath: dryRun.applyPlanPath,
+      dryRun,
+      createdFreshSidecar: true,
+    };
+  }
+  return {
+    sidecarPath: sidecar.filePath,
+    dryRun: null,
+    createdFreshSidecar: false,
+  };
+}
+
+function cmdCompile(args) {
+  const { flags } = parseFlags(args || [], COMPILE_FLAG_DEFS);
+  if (flags.help) return cmdCompileHelp();
+  ensureSafeMode(flags.mode, "compile");
+  const projectPath = ensureProjectPath(flags["project-path"]);
+
+  if (!flags.apply) {
+    const result = runCompileDryRunFromLatestExtraction(projectPath);
+    console.log(`[wiki] Compile dry-run preview: ${result.reportPath}`);
+    console.log(`[wiki] Compile apply JSON sidecar: ${result.applyPlanPath}`);
+    console.log(`[wiki] Operations: ${result.operations.length}`);
+    console.log(`[wiki] Unsupported operations: ${result.unsupportedCount}`);
+    console.log("[wiki] No wiki pages, raw sources, provenance, source files, or atlas compatibility files were modified.");
+    console.log("[wiki] Next: sdtk-wiki compile --mode safe --apply");
+    if (result.unsupportedCount > 0) {
+      throw new CliError(
+        `unsupported_operation: ${result.unsupportedCount} operation(s) are blocked. Review the compile dry-run preview report.`,
+        1
+      );
+    }
+    return 0;
+  }
+
+  const sidecar = ensureApplySidecar(projectPath);
+  const result = runWikiCompileApply({ projectPath, planArg: sidecar.sidecarPath });
+  console.log(`[wiki] Compile apply plan: ${result.planPath}`);
+  if (sidecar.createdFreshSidecar) {
+    console.log(`[wiki] Refreshed compile dry-run preview: ${sidecar.dryRun.reportPath}`);
+  }
+  console.log(`[wiki] Created files: ${result.created.length}`);
+  console.log(`[wiki] Unchanged files: ${result.unchanged.length}`);
+  console.log(`[wiki] Source-quality warnings: ${result.sourceQualityWarningCount}`);
+  console.log("[wiki] No source files, raw sources, provenance descriptors, or atlas compatibility files were modified.");
+  console.log("[wiki] Next: sdtk-wiki query \"multi-agent\"");
+  return 0;
+}
+
+function cmdQuery(args) {
+  const { flags, positional } = parseFlags(args || [], QUERY_FLAG_DEFS);
+  if (flags.help) return cmdQueryHelp();
+  const query = positional.join(" ");
+  const result = runWikiSearch({
+    projectPath: flags["project-path"],
+    query,
+    limit: flags.limit,
+  });
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log("[wiki] Query mode: local deterministic search. Premium Ask is not used.");
+    printHumanResult(result);
+  }
+  return 0;
+}
+
+function cmdDiscover(args) {
+  const { flags } = parseFlags(args || [], DISCOVER_FLAG_DEFS);
+  if (flags.help) return cmdDiscoverHelp();
+  if (!flags.plan) {
+    throw new ValidationError("sdtk-wiki discover requires --plan. No web/fetch/apply/auto behavior is enabled. No project files were changed.");
+  }
+  const projectPath = ensureProjectPath(flags["project-path"]);
+  const result = runWikiDiscoverPlan({ projectPath });
+
+  console.log(`[wiki] Discovery plan report: ${result.reportPath}`);
+  console.log(`[wiki] Pages scanned: ${result.pageCount}`);
+  console.log(`[wiki] Plan items: ${result.items.length}`);
+  console.log("[wiki] No sources were fetched, ingested, compiled, applied, pruned, deleted, archived, or persisted.");
+  return 0;
+}
+
+function cmdMaintain(args) {
+  const { flags } = parseFlags(args || [], MAINTAIN_FLAG_DEFS);
+  if (flags.help) return cmdMaintainHelp();
+  ensureSafeMode(flags.mode, "maintain");
+  const projectPath = ensureProjectPath(flags["project-path"]);
+
+  const lint = runWikiLint({ projectPath });
+  const discover = runWikiDiscoverPlan({ projectPath });
+  const extraction = latestExtraction(projectPath);
+  let compile = null;
+  if (extraction) {
+    compile = runWikiCompileDryRun({ projectPath, planArg: extraction.filePath });
+  }
+
+  console.log(`[wiki] Maintain mode: safe`);
+  console.log(`[wiki] Lint report: ${lint.reportPath}`);
+  console.log(`[wiki] Discovery plan report: ${discover.reportPath}`);
+  if (compile) {
+    console.log(`[wiki] Compile dry-run preview: ${compile.reportPath}`);
+    console.log(`[wiki] Compile apply JSON sidecar: ${compile.applyPlanPath}`);
+  } else {
+    console.log("[wiki] Compile preview skipped: no semantic extraction report found. Run \"sdtk-wiki ingest <source-root>\".");
+  }
+  console.log("[wiki] No apply, source mutation, web fetch, Ask, query history, delete/archive, or atlas compatibility mutation was performed.");
+  return 0;
+}
+
+module.exports = {
+  cmdCompile,
+  cmdCompileHelp,
+  cmdDiscover,
+  cmdDiscoverHelp,
+  cmdIngest,
+  cmdIngestHelp,
+  cmdMaintain,
+  cmdMaintainHelp,
+  cmdQuery,
+  cmdQueryHelp,
+};

package/src/commands/search.js

@@ -84,5 +84,6 @@ function cmdSearch(args) {
 module.exports = {
   cmdSearch,
   parseSearchFlags,
+  printHumanResult,
   printSearchHelp,
 };

package/src/index.js

@@ -5,6 +5,13 @@ const { cmdAsk } = require("./commands/ask");
 const { cmdHelp } = require("./commands/help");
 const { cmdInit } = require("./commands/init");
 const { cmdLint } = require("./commands/lint");
+const {
+  cmdCompile,
+  cmdDiscover,
+  cmdIngest,
+  cmdMaintain,
+  cmdQuery,
+} = require("./commands/operations");
 const { cmdSearch } = require("./commands/search");
 const { cmdWiki } = require("./commands/wiki");
 const { ValidationError } = require("./lib/errors");
@@ -30,7 +37,21 @@ function parseCommand(argv) {
   return { command: first, args: rest };
 }
 
-const COMMANDS = new Set(["help", "version", "init", "atlas", "wiki", "ask", "lint", "search"]);
+const COMMANDS = new Set([
+  "help",
+  "version",
+  "init",
+  "atlas",
+  "wiki",
+  "ask",
+  "lint",
+  "search",
+  "ingest",
+  "compile",
+  "query",
+  "discover",
+  "maintain",
+]);
 
 async function run(argv) {
   const { command, args } = parseCommand(argv);
@@ -59,6 +80,16 @@ async function run(argv) {
       return cmdLint(args);
     case "search":
       return cmdSearch(args);
+    case "ingest":
+      return cmdIngest(args);
+    case "compile":
+      return cmdCompile(args);
+    case "query":
+      return cmdQuery(args);
+    case "discover":
+      return cmdDiscover(args);
+    case "maintain":
+      return cmdMaintain(args);
   }
 }
 

package/src/lib/wiki-search.js

@@ -126,7 +126,7 @@ function runWikiSearch({ projectPath, query, limit = DEFAULT_LIMIT }) {
   }
   if (!fs.existsSync(personalBrainPath) || !fs.statSync(personalBrainPath).isDirectory()) {
     throw new ValidationError(
-      `No SDTK-WIKI personal brain found at ${personalBrainPath}. Run extract, compile dry-run, and compile --apply --yes from the generated JSON sidecar first.`
+      `No SDTK-WIKI personal brain found at ${personalBrainPath}. Run "sdtk-wiki ingest <source-root>" and "sdtk-wiki compile --mode safe --apply" first. Advanced users can still use wiki extract/compile sidecar commands.`
     );
   }