sdtk-wiki-kit 0.1.0

package/README.md

@@ -0,0 +1,262 @@
+# SDTK-WIKI Kit
+
+`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.
+
+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
+workflows and keep using `.sdtk/atlas`.
+
+## Install
+
+```powershell
+npm install -g sdtk-wiki-kit
+sdtk-wiki --help
+```
+
+For local validation from this repository:
+
+```powershell
+node products/sdtk-wiki/distribution/sdtk-wiki-kit/bin/sdtk-wiki.js --help
+```
+
+## Current Runtime Surface
+
+Implemented in the Foundation/Beta package:
+
+| Capability | Command |
+|---|---|
+| Initialize SDTK-WIKI workspace | `sdtk-wiki init` |
+| 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` |
+| Show workspace/build status | `sdtk-wiki atlas status` |
+| Register one local source in raw/provenance registry | `sdtk-wiki wiki ingest` |
+| 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 compile dry-run preview from a local plan | `sdtk-wiki wiki compile --dry-run` |
+| Ask grounded questions over built graph | `sdtk-wiki ask` |
+| Save one redacted query record after successful Ask | `sdtk-wiki ask --save-query` |
+
+Not implemented in the Foundation/Beta runtime:
+
+- `sdtk-wiki wiki compile --apply`
+- automatic web discovery or web fetch
+- automatic source ingest from the web
+- destructive prune/delete/archive
+- query history list/show/delete commands
+- full prompt/full answer query persistence by default
+- automatic migration or deletion of `.sdtk/atlas`
+
+## Workspace Contract
+
+| Path | Meaning |
+|---|---|
+| `.sdtk/wiki` | 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/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,
+auto-migrate, or rewrite `.sdtk/atlas`.
+
+Existing `sdtk-spec atlas init|build|open|watch|status` commands remain the R1
+compatibility path and keep compatibility output under `.sdtk/atlas`.
+The old `sdtk-spec atlas ask` path is not supported; native Ask uses
+capability `wiki.ask`.
+
+## First Run
+
+Run from the project root you want to index:
+
+```powershell
+sdtk-wiki init --project-path . --no-open
+sdtk-wiki atlas status --project-path .
+sdtk-wiki atlas build --project-path .
+sdtk-wiki lint --project-path .
+```
+
+Open the viewer:
+
+```powershell
+sdtk-wiki atlas open --project-path .
+```
+
+## Command Reference
+
+### Init
+
+```powershell
+sdtk-wiki init [--project-path <path>] [--output-dir <path>] [--scan-root <path>] [--force] [--no-build] [--no-open] [--host <host>] [--port <port>] [--verbose]
+```
+
+Initializes `.sdtk/wiki`, writes package config, optionally builds the graph,
+and optionally opens the viewer.
+
+### Build, Open, Watch, Status
+
+```powershell
+sdtk-wiki atlas build [--project-path <path>] [--output-dir <path>] [--scan-root <path>] [--verbose]
+sdtk-wiki atlas open [--project-path <path>] [--host <host>] [--port <port>] [--no-open]
+sdtk-wiki atlas watch [--project-path <path>] [--scan-root <path>] [--port <port>] [--no-open]
+sdtk-wiki atlas status [--project-path <path>]
+```
+
+The `atlas` namespace is retained for R1 command continuity while generated
+workspace output is SDTK-WIKI-owned under `.sdtk/wiki`.
+
+### Ingest Local Source Metadata
+
+```powershell
+sdtk-wiki wiki ingest --project-path <path> --source <path>
+```
+
+Registers one local project source in `.sdtk/wiki/raw` and writes ingest
+provenance under `.sdtk/wiki/provenance`.
+
+Safety:
+
+- local project files only
+- metadata-only registry
+- no source payload copy
+- no generated page updates
+- no graph/viewer rebuild side effects
+
+### Lint
+
+```powershell
+sdtk-wiki lint [--project-path <path>]
+```
+
+Runs report-first checks over canonical `.sdtk/wiki` artifacts and writes a
+dated markdown report under `.sdtk/wiki/reports`. Lint does not auto-fix,
+delete, archive, compile, or persist query history.
+
+### Prune Dry-Run
+
+```powershell
+sdtk-wiki wiki prune --dry-run --project-path <path>
+```
+
+Writes a stale managed-page review report under `.sdtk/wiki/reports`.
+This command is dry-run only. It does not delete, archive, apply, or mutate
+`.sdtk/atlas`.
+
+### Discover Plan
+
+```powershell
+sdtk-wiki wiki discover --plan --project-path <path>
+```
+
+Writes a local-only discovery plan from existing lint/raw/provenance/stale
+evidence under `.sdtk/wiki/reports`.
+
+Safety:
+
+- no web fetch
+- no source ingest
+- no compile/apply
+- no prune/delete/archive
+
+### Compile Dry-Run Preview
+
+```powershell
+sdtk-wiki wiki compile --plan <path> --project-path <path> --dry-run
+```
+
+Reads a local markdown or JSON compile plan and writes a preview report under
+`.sdtk/wiki/reports`.
+
+Supported operation types:
+
+- `append_section`
+- `create_page`
+- `add_relation`
+- `add_source_ref`
+
+Unknown operation types are reported as `unsupported_operation`. The current
+runtime has no `--apply` behavior and does not modify wiki pages, raw sources,
+provenance, or `.sdtk/atlas`.
+
+### Ask
+
+```powershell
+sdtk-wiki ask --question "<text>" [--project-path <path>] [--json] [--source <id-or-path>] [--max-sources <n>] [--save-query]
+```
+
+Native `sdtk-wiki ask` is the canonical Q&A command for capability `wiki.ask`.
+
+Preconditions:
+
+- `.sdtk/wiki/graph` must exist
+- local `wiki.ask` entitlement must be valid
+- local premium/runtime Ask pack must be available
+
+Query history is off by default. `--save-query` writes one redacted JSON record
+under `.sdtk/wiki/queries` only after a successful answer.
+
+Saved query records store `question_redacted`, `answer_summary`, source refs,
+runtime metadata, and retention policy. They do not store full question or full
+answer by default.
+
+## Practical Flows
+
+Build and view a project knowledge graph:
+
+```powershell
+sdtk-wiki init --project-path . --no-open
+sdtk-wiki atlas build --project-path .
+sdtk-wiki atlas open --project-path .
+```
+
+Add local source metadata and refresh graph outputs:
+
+```powershell
+sdtk-wiki wiki ingest --project-path . --source docs/product/PRD_ORDER_MGMT.md
+sdtk-wiki atlas build --project-path .
+sdtk-wiki lint --project-path .
+```
+
+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 .
+```
+
+Preview a compile plan without applying it:
+
+```powershell
+sdtk-wiki wiki compile --plan <local-plan.md-or-json> --project-path . --dry-run
+```
+
+Ask and save an opt-in redacted query record:
+
+```powershell
+sdtk-wiki atlas build --project-path .
+sdtk-wiki ask --project-path . --question "Which docs describe the deployment path?" --save-query
+```
+
+## 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.
+
+Do not claim the Foundation/Beta runtime includes:
+
+- web fetch/discover
+- compile `--apply`
+- destructive prune/delete/archive
+- query list/show/delete
+- default full prompt/full answer query persistence
+- `.sdtk/atlas` as canonical storage
+
+See `products/sdtk-wiki/governance/SDTK_WIKI_USAGE_GUIDE.md` for the fuller
+current usage guide.