feat(kb,okf): add kb init skill and okf graph-viewer renderer

.claude-plugin/marketplace.json

@@ -107,12 +107,12 @@
     {
       "name": "kb",
       "source": "./kb",
-      "description": "Knowledge base maintenance skills. Consolidate, dedupe, prune, refresh, and forget notes in a markdown KB."
+      "description": "Knowledge base maintenance skills. Initialize a shared-brain kb, then consolidate, dedupe, prune, refresh, and forget notes in a markdown KB."
     },
     {
       "name": "okf",
       "source": "./okf",
-      "description": "Open Knowledge Format (OKF) tooling. Author, initialize, validate, and refactor knowledge into vendor-neutral OKF v0.1 bundles: markdown files with YAML frontmatter."
+      "description": "Open Knowledge Format (OKF) tooling. Author, initialize, validate, render, and refactor knowledge into vendor-neutral OKF v0.1 bundles: markdown files with YAML frontmatter."
     },
     {
       "name": "unsloth-training",

kb/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kb",
-  "version": "1.0.1",
-  "description": "Knowledge base maintenance skills. Consolidate, dedupe, prune, refresh, and forget notes in a markdown KB.",
+  "version": "1.1.0",
+  "description": "Knowledge base maintenance skills. Initialize a shared-brain kb, then consolidate, dedupe, prune, refresh, and forget notes in a markdown KB.",
   "author": {
     "name": "duyet",
     "url": "https://github.com/duyet"

kb/.codex-plugin/plugin.json

@@ -1,15 +1,15 @@
 {
   "name": "kb",
-  "version": "1.0.1",
-  "description": "Knowledge base maintenance skills. Consolidate, dedupe, prune, refresh, and forget notes in a markdown KB.",
+  "version": "1.1.0",
+  "description": "Knowledge base maintenance skills. Initialize a shared-brain kb, then consolidate, dedupe, prune, refresh, and forget notes in a markdown KB.",
   "author": {
     "name": "duyet"
   },
   "skills": "./skills/",
   "commands": "./commands/",
   "interface": {
     "displayName": "Knowledge Base",
-    "shortDescription": "Maintain a markdown knowledge base: consolidate, dedupe, prune, and forget notes.",
+    "shortDescription": "Initialize and maintain a markdown knowledge base: consolidate, dedupe, prune, and forget notes.",
     "developerName": "duyet",
     "category": "productivity",
     "capabilities": ["Skill", "Command"],

kb/README.md

@@ -5,6 +5,12 @@ markdown knowledge base via a path argument or the `$KB_DIR` environment variabl
 
 ## Skills
 
+- **init** — scaffold a brand-new shared-brain kb folder (default `~/kb`): the
+  memory protocol (`AGENTS.md`/`CLAUDE.md`/`DREAM.md`/`MEMORY.md`), an OKF v0.1
+  `memory/` bundle, a capture inbox, and a self-contained CLI (`bin/kb`,
+  `scripts/render_okf_viewer.py` for the graph viewer, `lint.sh`, `sync.sh`,
+  `wire.sh`). Idempotent; never overwrites existing files; never edits anything
+  outside the target folder without asking first.
 - **dream** — the consolidation pass. Merges near-duplicate notes, flags contradictions,
   prunes stale/low-value notes, ingests inbox captures, refreshes notes from their
   source URLs, splits multi-fact notes, relinks/retags, and rebuilds the index. Shows a
@@ -20,11 +26,17 @@ markdown knowledge base via a path argument or the `$KB_DIR` environment variabl
 ## Usage
 
 ```bash
-dream ./docs/kb           # consolidate a KB (interactive, diff-for-approval)
-dream $KB_DIR --auto      # non-interactive; merges/prunes, skips contradictions
-dream forget "old server" # propose deleting notes matching a query
+init                       # scaffold a new shared-brain kb at ~/kb (or $KB_DIR)
+init ~/kb                  # scaffold at an explicit path
+
+dream ./docs/kb            # consolidate a KB (interactive, diff-for-approval)
+dream $KB_DIR --auto       # non-interactive; merges/prunes, skips contradictions
+dream forget "old server"  # propose deleting notes matching a query
 ```
 
 The KB is any directory of `*.md` notes with YAML frontmatter (`name`, `type`, `tags`,
 `created`, `updated`, optional `pinned`/`confidence`/`sources`), optionally with a
-`MEMORY.md` index, a `raw/inbox/` of captures, and `raw/` source docs.
+`MEMORY.md` index, a `raw/inbox/` of captures, and `raw/` source docs — exactly what
+`init` scaffolds. It is also a conformant [OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+bundle; see the companion **okf** plugin for deeper bundle authoring, validation, and
+graph-viewer rendering.

kb/commands/init.md

@@ -0,0 +1,34 @@
+---
+description: Scaffold a new shared-brain knowledge base folder (default ~/kb) — OKF v0.1-conformant, with a graph viewer and its own CLI, vendored and self-contained.
+---
+
+# /init
+
+Scaffold a new shared-brain kb folder: memory protocol (`AGENTS.md`/`CLAUDE.md`/
+`DREAM.md`/`MEMORY.md`), an OKF v0.1 `memory/` bundle, a capture inbox
+(`raw/inbox/`), and a self-contained CLI (`bin/kb`, `scripts/`). Delegate to the
+`init` skill for the full scaffold. Idempotent — never overwrites existing files.
+
+## Arguments
+
+- `path`: target directory (optional; defaults to `$KB_DIR` or `~/kb`)
+
+Pass the rest of the line as `$ARGUMENTS`. Examples: `/init`, `/init ~/kb`,
+`/init ./team-kb`.
+
+## Workflow
+
+1. Resolve the target path from `$ARGUMENTS`, `$KB_DIR`, or the default `~/kb`;
+   confirm with the user if ambiguous.
+2. Invoke the `init` skill and follow its steps exactly.
+3. Report files created vs. skipped (pre-existing).
+4. Offer PATH export, `git init`, and `scripts/wire.sh on` as separate,
+   confirm-first follow-ups — never run them without asking, since wiring
+   edits global agent config outside the scaffolded folder.
+
+## Guardrails
+
+- Never overwrite a file that already exists in the target.
+- Never touch anything outside the target folder without explicit confirmation.
+- Never invent personal facts to seed `memory/` with — leave it for the user.
+- Keep this command thin — all scaffolding logic lives in the `init` skill.

kb/skills/init/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: init
+description: Scaffold a new shared-brain knowledge base folder (default ~/kb) — a plain-markdown, OKF v0.1-conformant memory store that any coding agent can read/write across sessions. Use when the user asks to set up, init, or bootstrap a kb / shared brain / persistent agent memory folder, or wants an OKF bundle with a graph viewer ready out of the box.
+---
+
+# init — scaffold a shared-brain kb folder
+
+## What this creates
+
+A self-contained directory — plain markdown, no database, no server — that is:
+
+- **A memory protocol.** `AGENTS.md` (the full read/write/dream rules), `CLAUDE.md`
+  (thin pointer for Claude Code), `DREAM.md` (the consolidation pass), `MEMORY.md`
+  (the index every agent reads first).
+- **An OKF v0.1 bundle.** `memory/` is the bundle root; every note is one `.md`
+  file with a `type` in frontmatter. Conforms to
+  [OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+  — see the companion **okf** skill/plugin for deeper bundle authoring and
+  validation.
+- **A capture inbox.** `raw/inbox/` for low-ceremony daily notes; `raw/` for
+  immutable source docs.
+- **Its own CLI and tooling**, vendored into `scripts/`/`bin/` so the folder
+  keeps working even if this Claude plugin is later removed: `bin/kb`
+  (capture/lint/sync/gen/viz/wire), `scripts/render_okf_viewer.py` (regenerates
+  `memory/**/index.md` + a self-contained `viz.html` graph viewer), `scripts/
+lint.sh`, `scripts/sync.sh`, `scripts/wire.sh`.
+
+This is the generic, brand-neutral form of a personal "shared brain" pattern —
+it ships with no memory content, no assumed git remote, and no personal
+branding. Everything it writes is a template for the user to fill in.
+
+## When to use
+
+- "set up a kb / shared brain / persistent memory folder for me"
+- "init ~/kb" or "bootstrap my knowledge base"
+- The user wants cross-session, cross-agent memory but has none yet.
+
+If a kb already exists at the target (has `AGENTS.md` or `memory/`), this skill
+is still safe to run — see Idempotency below — but check first whether the user
+actually wants `dream` (consolidate existing notes) instead of `init`.
+
+## Steps
+
+1. **Resolve the target path.** Default `$HOME/kb`. Use `$KB_DIR` if set, or a
+   path the user gave explicitly. Confirm the path with the user if ambiguous.
+2. **Scaffold.** Run the bundled script with an absolute path (it does not
+   expand `~`):
+
+   ```bash
+   bash "${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/scaffold.sh" "$HOME/kb"
+   ```
+
+   It is idempotent — creates missing files, chmods scripts executable, seeds
+   starter `memory/{user,feedback,reference,projects,topics}/` groups, and
+   **never overwrites a file that already exists** in the target. It ends by
+   running `render_okf_viewer.py` once so `memory/index.md` and `viz.html`
+   exist immediately.
+
+3. **Report what happened**: how many files were created vs. skipped
+   (pre-existing), and the target path.
+4. **Offer, but do not run automatically, three follow-ups** — each changes
+   something outside the new folder or is otherwise consequential, so ask
+   first:
+   - **PATH.** Suggest adding `export PATH="<target>/bin:$PATH"` to the user's
+     shell rc. Don't edit their `.zshrc`/`.bashrc` yourself unless they ask.
+   - **Version control.** Offer `git init` (and `git remote add origin <url>`
+     if they have one). Skip silently if they don't want git.
+   - **Wiring.** `<target>/scripts/wire.sh on` adds a small marked block to
+     `~/.claude/CLAUDE.md` (and `~/.codex/AGENTS.md` / `~/.config/opencode/
+AGENTS.md` if those tools are present) so every future session
+     auto-reads the kb. This edits files **outside** the scaffolded folder and
+     affects every future session — explain what it does and get explicit
+     confirmation before running it. `wire.sh off` cleanly reverses it.
+5. **If the user wants example notes**, don't invent personal facts — either
+   leave `memory/` empty for them to fill in via `kb capture`, or ask what to
+   record.
+
+## After scaffolding
+
+- Point to `memory/_TEMPLATE.md` for the note format and `AGENTS.md` for the
+  full protocol — both are self-documenting inside the new folder.
+- For ongoing maintenance (merge duplicates, prune stale notes, rebuild the
+  index), use this plugin's **dream** skill against the new kb.
+- For richer OKF authoring/validation beyond what `bin/kb gen` covers (custom
+  concept types, `validate_okf.py` conformance checks), use the **okf** plugin.
+- `kb viz` (or `bin/kb viz` before `PATH` is set) opens the graph viewer any
+  time after notes are added.
+
+## Idempotency & safety
+
+- `scaffold.sh` only ever creates files that don't already exist — re-running
+  it against a partially-set-up or already-populated kb is safe and adds
+  nothing to files it finds present.
+- It never touches anything outside `<target>` — no global config, no shell
+  rc, no git remote. Those are the explicit, confirm-first follow-ups above.
+- It writes no personal data — the scaffolded files are generic templates.
+
+## Checklist
+
+- [ ] Resolved target path (arg, `$KB_DIR`, or confirmed default `~/kb`).
+- [ ] Ran `scaffold.sh` with an absolute path; reported created vs. skipped files.
+- [ ] `memory/index.md` and `viz.html` exist (scaffold.sh generates them).
+- [ ] Offered PATH / git init / wire as separate, confirm-first steps — did not
+      edit anything outside the target folder without asking.
+- [ ] Did not invent personal facts to seed `memory/` with.

kb/skills/init/scripts/scaffold.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Scaffold a new shared-brain kb folder at <target> (default: ~/kb).
+# Idempotent: never overwrites a file that already exists in <target>, so it's
+# safe to re-run against a kb that's already partially set up. Does NOT run
+# git init, does NOT touch any file outside <target> (wiring is a separate,
+# explicit step — see scripts/wire.sh in the scaffolded folder).
+set -euo pipefail
+
+TEMPLATES="$(cd -P "$(dirname "${BASH_SOURCE[0]}")/../templates" && pwd)"
+TARGET="${1:-$HOME/kb}" # pass an absolute path; this script does not expand ~
+
+created=() skipped=()
+
+put() { # put <src-relative-to-templates> <dest-relative-to-target>
+	local src="$TEMPLATES/$1" dest="$TARGET/$2"
+	mkdir -p "$(dirname "$dest")"
+	if [[ -e "$dest" ]]; then
+		skipped+=("$2")
+		return
+	fi
+	cp "$src" "$dest"
+	created+=("$2")
+}
+
+mkdir -p "$TARGET"
+
+put "AGENTS.md" "AGENTS.md"
+put "CLAUDE.md" "CLAUDE.md"
+put "DREAM.md" "DREAM.md"
+put "README.md" "README.md"
+put "gitignore" ".gitignore"
+put "memory/_TEMPLATE.md" "memory/_TEMPLATE.md"
+put "raw/README.md" "raw/README.md"
+put "scripts/lint.sh" "scripts/lint.sh"
+put "scripts/sync.sh" "scripts/sync.sh"
+put "scripts/wire.sh" "scripts/wire.sh"
+put "scripts/render_okf_viewer.py" "scripts/render_okf_viewer.py"
+put "bin/kb" "bin/kb"
+chmod +x "$TARGET"/scripts/*.sh "$TARGET/bin/kb" 2>/dev/null || true
+
+# Starter memory groups + inbox — empty dirs need a placeholder to survive git.
+for d in memory/user memory/feedback memory/reference memory/projects memory/topics raw/inbox; do
+	mkdir -p "$TARGET/$d"
+	[[ -e "$TARGET/$d/.gitkeep" ]] || {
+		: >"$TARGET/$d/.gitkeep"
+		created+=("$d/.gitkeep")
+	}
+done
+
+if [[ ! -e "$TARGET/.agent/state.json" ]]; then
+	mkdir -p "$TARGET/.agent"
+	printf '{}\n' >"$TARGET/.agent/state.json"
+	created+=(".agent/state.json")
+fi
+
+if [[ ! -e "$TARGET/MEMORY.md" ]]; then
+	cat >"$TARGET/MEMORY.md" <<'EOF'
+# Memory Index
+
+Master table of contents. One line per note — read this first, then open only
+the notes relevant to your task. See `AGENTS.md` for the protocol.
+
+(No notes yet — this index is rebuilt by hand or by a `DREAM.md` pass as notes
+are added under `memory/`.)
+EOF
+	created+=("MEMORY.md")
+fi
+
+# Initial OKF index.md + viz.html so the bundle is immediately browsable.
+python3 "$TARGET/scripts/render_okf_viewer.py" "$TARGET/memory" \
+	--title "$(basename "$TARGET")" --out "$TARGET/viz.html" >/dev/null
+
+echo "kb scaffolded at $TARGET"
+echo "  created: ${#created[@]} file(s)"
+[[ ${#skipped[@]} -gt 0 ]] && echo "  skipped (already existed): ${skipped[*]}"
+echo
+echo "next steps:"
+echo "  export PATH=\"$TARGET/bin:\$PATH\"   # add to your shell rc"
+echo "  cd $TARGET && git init                # optional: version control"
+echo "  $TARGET/scripts/wire.sh on             # optional: wire the reflex into agents' global config (ask the user first — it edits files outside this folder)"