sdtk-wiki-kit 0.1.3 → 0.1.4

package/README.md

@@ -2,7 +2,7 @@
 
 `sdtk-wiki-kit` is the standalone SDTK-WIKI Foundation/Beta toolkit package for
 project-local wiki, document graph, provenance, lint/gap analysis, local source
-intake, grounded Ask, and report-first second-brain maintenance workflows.
+intake, grounded Ask, and report-first local wiki maintenance workflows.
 
 SDTK-WIKI is the canonical home for new SDTK wiki work. The older
 `sdtk-spec atlas` commands remain a compatibility path for free graph/viewer
@@ -28,7 +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 a local wiki 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` |
@@ -42,8 +42,8 @@ Implemented in the Foundation/Beta package:
 | 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` |
+| Search generated local wiki pages locally | `sdtk-wiki search` |
+| Query generated local wiki 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 |
 
@@ -60,17 +60,20 @@ Not implemented in the Foundation/Beta runtime:
 
 | Path | Meaning |
 |---|---|
-| `.sdtk/wiki` | SDTK-WIKI workspace root |
+| `wiki` | canonical human-facing local wiki output |
+| `.sdtk/wiki` | internal SDTK-WIKI workspace root |
 | `.sdtk/wiki/graph` | graph/viewer output |
 | `.sdtk/wiki/pages` | generated managed wiki pages |
 | `.sdtk/wiki/raw` | metadata-only raw/source registry |
 | `.sdtk/wiki/provenance` | source/build/ingest provenance |
 | `.sdtk/wiki/reports` | lint, prune, discover, and compile preview reports |
-| `.sdtk/wiki/personal-brain` | generated semantic personal-brain pages from explicit apply |
+| `.sdtk/wiki/personal-brain` | legacy generated semantic pages, readable as fallback only |
 | `.sdtk/wiki/queries` | opt-in redacted Ask query records |
 | `.sdtk/atlas` | legacy Atlas compatibility output, readable only |
 
-SDTK-WIKI writes only under project-local `.sdtk/wiki`. It must not auto-delete,
+SDTK-WIKI writes human-facing generated wiki pages under project-local `wiki/`.
+Internal state, reports, provenance, raw registry, graph, logs, and legacy
+fallback pages stay under project-local `.sdtk/wiki`. It must not auto-delete,
 auto-migrate, or rewrite `.sdtk/atlas`.
 
 Existing `sdtk-spec atlas init|build|open|watch|status` commands remain the R1
@@ -95,9 +98,9 @@ Open the viewer:
 sdtk-wiki atlas open --project-path .
 ```
 
-## Simple Personal-Brain Flow
+## Simple Local Wiki Flow
 
-Use this when you want the shortest local second-brain path and do not need to
+Use this when you want the shortest local wiki path and do not need to
 inspect timestamped JSON files:
 
 ```powershell
@@ -115,7 +118,8 @@ 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
+- `query` is deterministic local search over `wiki/`, with legacy
+  `.sdtk/wiki/personal-brain` fallback; 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`.
@@ -182,7 +186,7 @@ source records 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,
+It does not mutate source files, local wiki pages, raw/provenance state,
 graph outputs, web sources, Ask state, or `.sdtk/atlas`.
 
 Supported JSON repository records may be an array or an object containing a
@@ -312,7 +316,8 @@ are rejected for apply.
 Apply behavior:
 
 - requires `--apply --yes`
-- writes only under `.sdtk/wiki/personal-brain`
+- writes only under `wiki/` for new canonical output
+- legacy `.sdtk/wiki/personal-brain` sidecars remain readable for compatibility
 - create-only or same-content no-op
 - no overwrite with different content
 - no delete, archive, rewrite, or reorder
@@ -325,8 +330,8 @@ Apply behavior:
 sdtk-wiki search --project-path <path> "<query>"
 ```
 
-Searches generated personal-brain Markdown pages under
-`.sdtk/wiki/personal-brain/**/*.md`.
+Searches generated local wiki Markdown pages under `wiki/**/*.md`, falling
+back to `.sdtk/wiki/personal-brain/**/*.md` for legacy workspaces.
 
 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
@@ -396,7 +401,7 @@ Preview a compile plan without applying it:
 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:
+Build a local wiki from local Markdown sources and search it:
 
 ```powershell
 sdtk-wiki ingest docs
@@ -421,13 +426,13 @@ sdtk-wiki ask --project-path . --question "Which docs describe the deployment pa
 ```
 
 This flow requires valid `wiki.ask` entitlement/runtime preconditions. Use
-`sdtk-wiki search` for non-premium local validation of generated
-personal-brain pages.
+`sdtk-wiki search` for non-premium local validation of generated local wiki
+pages.
 
 ## Foundation/Beta Boundaries
 
 This release is local-first and report-first. It is a foundation for a
-second-brain workflow, not a fully autonomous second brain.
+local wiki workflow, not a fully autonomous second brain.
 
 Do not claim the Foundation/Beta runtime includes:
 

package/package.json

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

package/src/commands/enrich.js

@@ -0,0 +1,51 @@
+"use strict";
+
+const { parseFlags } = require("../lib/args");
+const { ValidationError } = require("../lib/errors");
+const { runWikiGithubEnrichmentReview } = require("../lib/wiki-enrich");
+
+const ENRICH_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  "project-path": { type: "string" },
+  source: { type: "string" },
+  mode: { type: "string" },
+};
+
+function cmdEnrichHelp() {
+  console.log(`SDTK-WIKI Enrich
+
+Usage:
+  sdtk-wiki enrich --source github --mode review [--project-path <path>]
+
+Purpose:
+  Write an explicit opt-in GitHub enrichment review report from local wiki evidence.
+
+Safety:
+  Review mode only in R1.
+  No network fetch, page rewrite, source mutation, apply, entitlement change, or .sdtk/atlas mutation.
+  Network-backed metadata verification requires a later controller-approved slice.`);
+  return 0;
+}
+
+function cmdEnrich(args) {
+  const { flags } = parseFlags(args || [], ENRICH_FLAG_DEFS);
+  if (flags.help) return cmdEnrichHelp();
+  if (flags.source !== "github") {
+    throw new ValidationError("sdtk-wiki enrich requires --source github in R1. No project files were changed.");
+  }
+  const mode = flags.mode || "review";
+  if (mode !== "review") {
+    throw new ValidationError("sdtk-wiki enrich supports only --mode review in R1. No project files were changed.");
+  }
+  const result = runWikiGithubEnrichmentReview({ projectPath: flags["project-path"] });
+  console.log(`[wiki] GitHub enrichment review: ${result.markdownPath}`);
+  console.log(`[wiki] JSON report: ${result.jsonPath}`);
+  console.log(`[wiki] Candidates: ${result.records.length}`);
+  console.log("[wiki] Review-only local metadata. No network fetch, page rewrite, source mutation, or .sdtk/atlas mutation was performed.");
+  return 0;
+}
+
+module.exports = {
+  cmdEnrich,
+  cmdEnrichHelp,
+};

package/src/commands/help.js

@@ -12,6 +12,7 @@ Usage:
   sdtk-wiki query --help
   sdtk-wiki discover --help
   sdtk-wiki maintain --help
+  sdtk-wiki enrich --help
   sdtk-wiki atlas build --help
   sdtk-wiki atlas open --help
   sdtk-wiki atlas watch --help
@@ -24,7 +25,7 @@ Usage:
   sdtk-wiki search --help
   sdtk-wiki lint --help
 
-Simple personal-brain workflow:
+Simple local wiki workflow:
   sdtk-wiki init --no-open
   sdtk-wiki ingest <source-root>
   sdtk-wiki compile --mode safe [--apply]
@@ -36,10 +37,11 @@ Simple personal-brain workflow:
 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.
+  compile              Run safe local wiki compile preview, optionally apply to wiki/.
+  query                Search generated local wiki pages without premium Ask.
   discover             Write a local-only discovery plan from WIKI gap evidence.
   maintain             Run safe lint, discover, and compile-preview maintenance reports.
+  enrich               Write explicit opt-in GitHub enrichment review 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.
@@ -47,9 +49,9 @@ R1 command model:
   wiki ingest          Register one local source in metadata-only raw/provenance state.
   wiki prune           Write a report-only dry-run stale managed-page review.
   wiki discover        Write a local-only discovery plan from WIKI gap evidence.
-  wiki compile         Preview or explicitly apply local personal-brain compile plans.
+  wiki compile         Preview or explicitly apply local wiki compile plans.
   ask                  Ask grounded questions over the built SDTK-WIKI graph.
-  search               Search generated personal-brain pages locally without premium Ask.
+  search               Search generated local wiki pages without premium Ask.
   lint                 Write a report-first, non-destructive wiki lint report.
 
 Advanced/audit workflow:
@@ -57,15 +59,17 @@ Advanced/audit workflow:
   sdtk-wiki wiki compile --plan <extract-json> --dry-run
   sdtk-wiki wiki compile --plan <apply-json> --apply --yes
   sdtk-wiki search "<query>"
+  sdtk-wiki enrich --source github --mode review
 
 Workspace paths:
-  .sdtk/wiki           New SDTK-WIKI workspace target.
+  wiki/                Canonical human-facing local wiki output target.
+  .sdtk/wiki           Internal SDTK-WIKI state target.
   .sdtk/wiki/graph     New SDTK-WIKI graph output target.
-  .sdtk/wiki/pages     Generated local wiki page target.
+  .sdtk/wiki/pages     Internal graph/wiki compatibility page target.
   .sdtk/wiki/raw       Metadata-only local source registry target.
   .sdtk/wiki/provenance Generated source provenance target.
   .sdtk/atlas          Legacy Atlas workspace, readable for compatibility.
-  Write paths must stay under project-local .sdtk/wiki.
+  Human-facing generated wiki paths must stay under project-local wiki/.
 
 Compatibility:
   Existing sdtk-spec atlas commands remain the R1 compatibility path.
@@ -78,13 +82,14 @@ 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.
+  sdtk-wiki query      Beginner-friendly local deterministic search over wiki/, with legacy .sdtk/wiki/personal-brain fallback.
+  sdtk-wiki search     Deterministic, read-only local search over wiki/, with legacy .sdtk/wiki/personal-brain fallback.
                        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 enrich --source github --mode review writes a local-only enrichment review report.
   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(`
@@ -92,7 +97,7 @@ Maintenance:
   It never fetches web sources, ingests sources, compiles pages, applies edits, prunes, or mutates .sdtk/atlas.`);
   console.log(`
   sdtk-wiki wiki compile --dry-run writes a markdown preview plus JSON sidecar under .sdtk/wiki/reports.
-  sdtk-wiki wiki compile --apply --yes consumes only the JSON sidecar and writes create-only personal-brain pages.
+  sdtk-wiki wiki compile --apply --yes consumes only the JSON sidecar and writes create-only local wiki pages under wiki/.
   It never rewrites pages, mutates raw/provenance files, or mutates .sdtk/atlas.`);
   return 0;
 }

package/src/commands/lint.js

@@ -21,7 +21,7 @@ Output:
 Behavior:
   Findings are written to the report and do not auto-modify wiki or source files.
   Source-quality checks report mojibake-like text, missing source URLs, weak titles, duplicate repo/source candidates, low-confidence extraction, and raw/graph/provenance coverage mismatch.
-  Personal-brain quality metrics report frontmatter coverage, required sections, source refs, internal links, stub ratio, giant pages, density, and source evidence coverage.
+  Local wiki quality metrics report frontmatter coverage, required sections, source refs, internal links, stub ratio, giant pages, density, and source evidence coverage.
   Completed lint runs exit 0 even when findings exist.
   Missing workspace or fatal report-write failures exit non-zero.
 

package/src/commands/operations.js

@@ -101,7 +101,7 @@ Purpose:
 
 Safety:
   Local sources only.
-  No source mutation, personal-brain page writes, graph rebuild, web fetch, Ask, raw/provenance mutation, or .sdtk/atlas mutation.
+  No source mutation, local wiki page writes, graph rebuild, web fetch, Ask, raw/provenance mutation, or .sdtk/atlas mutation.
 
 Next:
   sdtk-wiki compile --mode safe`);
@@ -132,7 +132,7 @@ Usage:
   sdtk-wiki query [--project-path <path>] [--json] [--limit <n>] "<query>"
 
 Purpose:
-  Deterministically search generated personal-brain Markdown pages.
+  Deterministically search generated local wiki Markdown pages.
 
 Behavior:
   Local search only.
@@ -195,7 +195,7 @@ function cmdIngest(args) {
   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] No source files, local wiki pages, raw/provenance state, graph outputs, or atlas compatibility files were modified.");
   console.log("[wiki] Next: sdtk-wiki compile --mode safe");
   return 0;
 }
@@ -264,8 +264,9 @@ function cmdCompile(args) {
   }
   console.log(`[wiki] Created files: ${result.created.length}`);
   console.log(`[wiki] Unchanged files: ${result.unchanged.length}`);
+  console.log(`[wiki] Scaffold created/skipped: ${result.scaffoldCreated.length}/${result.scaffoldSkipped.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] Canonical local wiki output is <project>/wiki; .sdtk/wiki remains internal state. No source files, raw sources, provenance descriptors, or atlas compatibility files were modified.");
   console.log("[wiki] Next: sdtk-wiki query \"multi-agent\"");
   return 0;
 }

package/src/commands/search.js

@@ -22,10 +22,10 @@ Usage:
   sdtk-wiki search --project-path <path> --json --limit 10 "Claude Code"
 
 Purpose:
-  Deterministically search generated personal-brain Markdown pages.
+  Deterministically search generated local wiki Markdown pages.
 
 Inputs:
-  .sdtk/wiki/personal-brain/**/*.md
+  wiki/**/*.md, falling back to .sdtk/wiki/personal-brain/**/*.md for legacy workspaces.
 
 Behavior:
   Read-only and non-premium.
@@ -38,14 +38,15 @@ function printHumanResult(result) {
   const lines = [
     `Query: ${result.query}`,
     `Search mode: ${result.searchMode}`,
-    `Personal brain: ${result.personalBrainPath}`,
+    `Wiki content: ${result.wikiContentPath}`,
+    `Wiki content mode: ${result.wikiContentMode}`,
     `Scanned files: ${result.scannedFiles}`,
     `Matches: ${result.totalMatches}`,
     "",
   ];
 
   if (result.matches.length === 0) {
-    lines.push("No local personal-brain matches found.");
+    lines.push("No local wiki matches found.");
   } else {
     result.matches.forEach((match, index) => {
       lines.push(`${index + 1}. ${match.path}`);

package/src/commands/wiki.js

@@ -37,7 +37,7 @@ function cmdWikiExtractHelp() {
   sdtk-wiki wiki extract --project-path <path> --source-root <path> --dry-run
 
 Purpose:
-  Write a local semantic extraction dry-run report for SDTK-WIKI personal-brain generation.
+  Write a local semantic extraction dry-run report for SDTK-WIKI local wiki generation.
 
 Writes:
   .sdtk/wiki/reports/semantic-extraction-dry-run-YYYYMMDD-HHMMSSZ.json
@@ -45,7 +45,7 @@ Writes:
 Safety:
   Dry-run report only.
   Local Markdown and supported JSON source roots only; remote URLs are rejected.
-  No personal-brain pages, managed pages, raw sources, provenance state, atlas compatibility files, web fetch, Ask, compile/apply, prune, delete, archive, or source files are modified.`);
+  No local wiki pages, managed pages, raw sources, provenance state, atlas compatibility files, web fetch, Ask, compile/apply, prune, delete, archive, or source files are modified.`);
   return 0;
 }
 
@@ -60,13 +60,13 @@ Purpose:
 Writes:
   .sdtk/wiki/reports/compile-dry-run-preview-YYYY-MM-DD.md
   .sdtk/wiki/reports/compile-apply-plan-YYYY-MM-DD.json
-  .sdtk/wiki/personal-brain/... only when --apply --yes is used with an apply JSON sidecar
+  wiki/... only when --apply --yes is used with an apply JSON sidecar
 
 Safety:
   Dry-run remains preview-only.
   Apply consumes only record_type sdtk_wiki_compile_apply_plan JSON sidecars.
   Markdown plans and semantic extraction JSON are rejected for apply.
-  Apply is create-only or same-content no-op under .sdtk/wiki/personal-brain.
+  Apply is create-only or same-content no-op under project-local wiki/.
   No delete, archive, rewrite, reorder, raw source, provenance, atlas compatibility, discover, prune, query-history, or release mutation.
   Unknown operation types are reported as unsupported_operation and cause a non-zero exit after the report is written.`);
   return 0;
@@ -225,11 +225,12 @@ function cmdWikiCompile(args) {
     console.log(`[wiki] Compile apply plan: ${result.planPath}`);
     console.log(`[wiki] Created files: ${result.created.length}`);
     console.log(`[wiki] Unchanged files: ${result.unchanged.length}`);
+    console.log(`[wiki] Scaffold created/skipped: ${result.scaffoldCreated.length}/${result.scaffoldSkipped.length}`);
     console.log(`[wiki] Source-quality warnings: ${result.sourceQualityWarningCount}`);
     if (result.sourceQualityWarningCount > 0) {
       console.log("[wiki] Source-quality findings were present in the apply plan; pages were still applied because --yes was explicit.");
     }
-    console.log("[wiki] No source files, raw sources, provenance descriptors, or atlas compatibility files were modified.");
+    console.log("[wiki] Canonical local wiki output is <project>/wiki; .sdtk/wiki remains internal state. No source files, raw sources, provenance descriptors, or atlas compatibility files were modified.");
     return 0;
   }
   if (!flags["dry-run"]) {
@@ -274,7 +275,7 @@ function cmdWikiExtract(args) {
   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 personal-brain pages, raw sources, provenance state, or atlas compatibility files were modified.");
+  console.log("[wiki] No local wiki pages, raw sources, provenance state, or atlas compatibility files were modified.");
   return 0;
 }
 

package/src/index.js

@@ -12,6 +12,7 @@ const {
   cmdMaintain,
   cmdQuery,
 } = require("./commands/operations");
+const { cmdEnrich } = require("./commands/enrich");
 const { cmdSearch } = require("./commands/search");
 const { cmdWiki } = require("./commands/wiki");
 const { ValidationError } = require("./lib/errors");
@@ -51,6 +52,7 @@ const COMMANDS = new Set([
   "query",
   "discover",
   "maintain",
+  "enrich",
 ]);
 
 async function run(argv) {
@@ -90,6 +92,8 @@ async function run(argv) {
       return cmdDiscover(args);
     case "maintain":
       return cmdMaintain(args);
+    case "enrich":
+      return cmdEnrich(args);
   }
 }