sdtk-brain-kit 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# sdtk-brain-kit
+
+`sdtk-brain` is a **standalone, local-first second-brain vault CLI**. One job:
+turn a folder of immutable sources (`raw/`) into a compiled markdown knowledge
+layer (`wiki/`) that you — and your AI agent — can search, lint, and browse as
+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`
+CLI command: `sdtk-brain`
+
+Standalone by design: not part of the `sdtk-kit` umbrella, installs no agent
+skills, makes no network calls, needs no entitlement. It shares its graph
+builder and viewer with SDTK-WIKI at build time (byte-identity is CI-guarded).
+
+## Install
+
+```bash
+npm install -g sdtk-brain-kit
+sdtk-brain --version
+```
+
+## Quick start
+
+```bash
+mkdir my-vault && cd my-vault
+sdtk-brain init                      # raw/ + wiki/ + workspace/ + CLAUDE.md
+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)
+```
+
+## Commands
+
+```text
+sdtk-brain init [--vault <path>]     scaffold a vault (refuses non-empty non-vault targets)
+sdtk-brain ingest <file|dir>         semantic extraction over raw sources (report-first)
+sdtk-brain compile --mode safe [--apply]   compile extraction into wiki/ pages
+sdtk-brain search [--json] "<q>"     deterministic search over the vault wiki
+sdtk-brain lint | maintain           report-first hygiene (orphans, links, stale, contradictions)
+sdtk-brain discover --plan           gap-analysis plan
+sdtk-brain enrich --source github --mode review   review-only external repo metadata
+sdtk-brain open [--no-open]          build + open the graph viewer
+sdtk-brain status                    vault status
+```
+
+There is deliberately **no `ask` command**: open the vault in your agent (or
+Obsidian) and ask there — grounded synthesis is the agent's job.
+
+## Vault layout
+
+```
+raw/        immutable sources (inbox, articles, papers, repos, notes, meetings, archive)
+wiki/       compiled knowledge (sources, concepts, entities, comparisons, syntheses, …)
+workspace/  scratch
+CLAUDE.md   the agent operating contract
+.brain/     machine state (reports, graph, provenance) — never edit by hand
+```
+
+## Boundaries
+
+- 100% local: no LLM, no network, no telemetry, no entitlement
+- never mutates `raw/` content; `.brain/` is CLI-owned machine state
+- a vault is a standalone folder — `init` refuses non-empty non-vault targets