skillwiki 0.2.0-beta.3 → 0.2.0-beta.30

package/package.json

@@ -1,14 +1,22 @@
 {
   "name": "skillwiki",
-  "version": "0.2.0-beta.3",
+  "version": "0.2.0-beta.30",
   "type": "module",
-  "bin": { "skillwiki": "dist/cli.js" },
-  "files": ["dist", "templates", "skills", "README.md"],
+  "bin": {
+    "skillwiki": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "skills",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsup && rm -rf ./skills && cp -r ../skills ./skills",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "commander": "^12.1.0",
@@ -23,5 +31,11 @@
     "typescript": "^5.7.0",
     "vitest": "^2.1.0"
   },
-  "engines": { "node": ">=20" }
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/karlorz/llm-wiki.git"
+  },
+  "engines": {
+    "node": ">=20"
+  }
 }

package/skills/.claude-plugin/plugin.json

@@ -1,7 +1,8 @@
 {
   "name": "skillwiki",
-  "version": "0.1.0",
-  "description": "Project-aware Karpathy-style knowledge base for Claude Code: 10 prompt-only skills (wiki-* + proj-*) backed by the deterministic `skillwiki` CLI (8 subcommands, JSON-by-default).",
+  "version": "0.2.0-beta.30",
+  "skills": "./",
+  "description": "Project-aware Karpathy-style knowledge base for Claude Code: 11 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI (8 subcommands, JSON-by-default).",
   "author": {
     "name": "karlorz",
     "url": "https://github.com/karlorz"

package/skills/bin/skillwiki

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# skillwiki CLI wrapper — delegates to npx so the CLI is available
+# automatically when this plugin is enabled (Claude Code adds bin/ to PATH).
+set -euo pipefail
+exec npx -y skillwiki@beta "$@"

package/skills/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/hooks/run-hook.cmd

@@ -0,0 +1,43 @@
+: << 'CMDBLOCK'
+@echo off
+REM Cross-platform polyglot wrapper for hook scripts.
+REM On Windows: cmd.exe runs the batch portion, which finds and calls bash.
+REM On Unix: the shell interprets this as a script (: is a no-op in bash).
+REM
+REM Hook scripts use extensionless filenames (e.g. "session-start" not
+REM "session-start.sh") so Claude Code's Windows auto-detection -- which
+REM prepends "bash" to any command containing .sh -- doesn't interfere.
+
+if "%~1"=="" (
+    echo run-hook.cmd: missing script name >&2
+    exit /b 1
+)
+
+set "HOOK_DIR=%~dp0"
+
+REM Try Git for Windows bash in standard locations
+if exist "C:\Program Files\Git\bin\bash.exe" (
+    "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+if exist "C:\Program Files (x86)\Git\bin\bash.exe" (
+    "C:\Program Files (x86)\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+REM Try bash on PATH
+where bash >nul 2>nul
+if %ERRORLEVEL% equ 0 (
+    bash "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+REM No bash found - exit silently
+exit /b 0
+CMDBLOCK
+
+# Unix: run the named script directly
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_NAME="$1"
+shift
+exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

package/skills/hooks/session-start

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# SessionStart hook for skillwiki plugin
+# Injects using-skillwiki SKILL.md content into every conversation.
+
+set -euo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+
+skill_content=$(cat "${PLUGIN_ROOT}/using-skillwiki/SKILL.md" 2>/dev/null || echo "Error reading using-skillwiki skill")
+
+# Escape string for JSON embedding using bash parameter substitution.
+# Each ${s//old/new} is a single C-level pass.
+escape_for_json() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\t'/\\t}"
+    printf '%s' "$s"
+}
+
+skill_escaped=$(escape_for_json "$skill_content")
+session_context="<EXTREMELY_IMPORTANT>\nYou have skillwiki.\n\n**Below is the full content of your 'skillwiki:using-skillwiki' skill - your introduction to the skillwiki skills. For all other skills, use the 'Skill' tool:**\n\n${skill_escaped}\n</EXTREMELY_IMPORTANT>"
+
+# Uses printf instead of heredoc to work around bash 5.3+ heredoc hang.
+printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context"
+
+exit 0

package/skills/package.json

@@ -1,6 +1,13 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.1.0",
+  "version": "0.2.0-beta.30",
   "private": true,
-  "files": ["wiki-*", "proj-*", ".claude-plugin", "README.md"]
+  "files": [
+    "wiki-*",
+    "proj-*",
+    "using-skillwiki",
+    ".claude-plugin",
+    "hooks",
+    "README.md"
+  ]
 }

package/skills/proj-decide/SKILL.md

@@ -13,7 +13,7 @@ Standard four + project context.
 
 ## Steps
 1. Compose the ADR in `projects/{slug}/architecture/YYYY-MM-DD-{adr-slug}.md`. Frontmatter: kind=decision, status=in-progress or completed, project link.
-2. `npx skillwiki validate <adr>`. If non-zero, STOP.
+2. `skillwiki validate <adr>`. If non-zero, STOP.
 3. **Generalization check.** If the decision applies beyond this project, create a `concepts/` page with `provenance: project` (or `mixed` if research-informed).
 4. Apply writes: ADR → (optional) concept page → vault `index.md` → vault `log.md` and project `log.md`.
 

package/skills/proj-distill/SKILL.md

@@ -12,10 +12,32 @@ description: 2-step distillation (E4) — analyze project compound entry, then g
 Standard four + project context.
 
 ## Steps (E4 — 2-step pattern)
-1. **Step 1 — Analyze.** Read the source compound entry + linked work items. Output a candidate concept outline. STOP if no clear universal pattern is found — surface the reasoning instead of forcing a page.
-2. **Step 2 — Generate.** Compose the vault concept page with `provenance: project` and `provenance_projects: ["[[slug]]"]`. Validate with `npx skillwiki validate`.
-3. **Backlink.** Set `promoted_to: "[[concept-slug]]"` on the source compound entry.
-4. **Apply writes in order.** Vault concept page → backlink update → project `log.md` → vault `index.md` → vault `log.md`.
+
+### Source selection
+
+Check `projects/{slug}/compound/` first. If empty, fall back to retro
+entries in vault `log.md` (lines matching `## [YYYY-MM-DD] retro`).
+
+When reading retros as source material:
+- Collect all retros for the project, focusing on entries with
+  `Generalize?: yes`.
+- Group by recurring theme (≥2 occurrences across cycles).
+- Each group becomes a candidate concept outline.
+
+1. **Step 1 — Analyze.** Read the source compound entry + linked work
+   items (or retro groups from log.md). Output a candidate concept
+   outline. STOP if no clear universal pattern is found — surface the
+   reasoning instead of forcing a page.
+2. **Step 2 — Generate.** Compose the vault concept page with
+   `provenance: project` and
+   `provenance_projects: ["[[slug]]"]`. Validate with
+   `skillwiki validate`.
+3. **Backlink.** Set `promoted_to: "[[concept-slug]]"` on the source
+   compound entry. For retro-sourced distillation, skip backlink (log.md
+   entries are append-only) and instead add `sources:` citing the vault
+   log with date range.
+4. **Apply writes in order.** Vault concept page → backlink update →
+   project `log.md` → vault `index.md` → vault `log.md`.
 
 ## Stop conditions
 - No clear universal pattern.

package/skills/proj-work/SKILL.md

@@ -16,10 +16,29 @@ Standard four + project context (project README, last ~5 work logs).
 1. Determine `kind:` (feature | issue | refactor | decision) and slug.
 2. Create folder `projects/{slug}/work/YYYY-MM-DD-{work-slug}/`.
 3. Override default output paths for any nested skill: `spec.md`, `plan.md`, and `log.md` are written here, not at vault root.
-4. Validate work-item frontmatter via `npx skillwiki validate <spec.md>`. If non-zero, STOP.
+4. Validate work-item frontmatter via `skillwiki validate <spec.md>`. If non-zero, STOP.
 5. Manage status transitions: `planned` → `in-progress` → `completed` (set `completed:` date) or `abandoned`.
 6. Append vault `log.md` entry on creation and on each status transition.
 
+## Redirect Output
+
+After step 3 (output path override), emit redirect paths for the active PRD skill:
+
+> Work item created: projects/{slug}/work/YYYY-MM-DD-{work-slug}/
+>
+> Redirect paths for PRD skills:
+>   spec → <vault-root>/projects/{slug}/work/YYYY-MM-DD-{work-slug}/spec.md
+>   plan → <vault-root>/projects/{slug}/work/YYYY-MM-DD-{work-slug}/plan.md
+>
+> Pass these paths to your PRD skill (superpowers:brainstorming, superpowers:writing-plans,
+> CodeStable, or any other). Files land in the vault natively — no separate ingest needed.
+
+Rules:
+- Emit redirect paths as the first output after folder creation, before any PRD skill runs.
+- Resolve `<vault-root>` via `skillwiki path` (never hardcode).
+- proj-work does NOT invoke any PRD skill — it provides paths only.
+- If the PRD skill cannot accept custom save paths, fall back to manual `wiki-ingest`.
+
 ## Stop conditions
 - `validate` non-zero.
 - Conflicting work folder name.

package/skills/using-skillwiki/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: using-skillwiki
+description: Invoke at session start or when knowledge-base tasks arise — maps all wiki-*/proj-* skills and teaches the skillwiki CLI workflow
+---
+
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill.
+</SUBAGENT-STOP>
+
+# using-skillwiki
+
+You have skillwiki — a project-aware Karpathy-style knowledge base for Claude Code.
+
+## When to Use These Skills
+
+Invoke a skillwiki skill when the user:
+- Wants to create, build, or start a vault/wiki/knowledge base
+- Mentions ingesting sources, reading URLs into notes, converting content
+- Asks to search, query, or find information in their vault
+- Wants a health check or lint on their vault
+- Mentions crystallizing a session into a note
+- Talks about project workspaces, ADRs, or distillation
+- Wants to archive or clean up old vault pages
+- Needs to detect source drift or re-ingest updated content
+- Has a spec/plan in a non-skillwiki format (CodeStable, RFC, AIDE)
+- Asks about their skillwiki configuration or setup health
+
+## Vault Structure
+
+A skillwiki vault has two layers:
+
+**Layer 1 — Raw (`raw/`):** Immutable source material. Never modify after ingest.
+
+```
+raw/
+├── articles/    # Web articles, clippings
+├── papers/      # PDFs, arxiv papers
+├── transcripts/ # Meeting notes, interviews
+└── assets/      # Images, diagrams referenced by sources
+```
+
+Raw frontmatter:
+```yaml
+---
+source_url: https://…
+ingested: YYYY-MM-DD
+sha256:          # computed by skillwiki hash over body bytes after closing ---
+---
+```
+
+**Layer 2 — Agent-owned pages:** `entities/`, `concepts/`, `comparisons/`, `queries/`, `meta/`, `projects/`. Citations use `^[raw/articles/source-file.md]` markers at paragraph-end.
+
+## Skill Map
+
+| Skill | When to Invoke |
+|-------|----------------|
+| `wiki-init` | Bootstrap a new vault — SCHEMA.md, index.md, log.md, ~/.skillwiki/.env |
+| `wiki-ingest` | Convert URLs, files, or pasted text into typed-knowledge pages |
+| `wiki-query` | Search the vault and synthesize an answer with ranked results |
+| `wiki-lint` | Vault health check (stale pages, oversized pages, log rotation) |
+| `wiki-crystallize` | Distill the current working session into a typed-knowledge page |
+| `wiki-audit` | Verify raw provenance references and source frontmatter integrity |
+| `wiki-archive` | Archive a typed-knowledge page — move to `_archive/`, remove from index |
+| `wiki-reingest` | Detect drift in raw sources (sha256 comparison) and re-ingest updated content |
+| `wiki-adapter-prd` | Map foreign PRD formats (CodeStable, RFC, AIDE, Hermes) into vault pages |
+| `proj-init` | Bootstrap a project workspace (README, requirements, architecture) |
+| `proj-work` | Open or run a work item under a project's work/ directory |
+| `proj-distill` | Distill project compound entries into vault concept pages |
+| `proj-decide` | Write an Architectural Decision Record (ADR) |
+
+## CLI Backbone
+
+All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, and linting. Skills invoke it via Bash for the mechanical parts and use Claude for the creative parts.
+
+Key CLI subcommands: `init`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `graph build`, `archive`, `drift`.
+
+Run `skillwiki doctor` to diagnose setup issues. Run `skillwiki config list` to see current configuration.
+
+## Typical Workflow
+
+1. **Init** (`wiki-init`) — create vault, set domain and taxonomy
+2. **Ingest** (`wiki-ingest`) — add sources, build pages
+3. **Query** (`wiki-query`) — search and synthesize answers
+4. **Lint** (`wiki-lint`) — periodic health checks
+5. **Crystallize** (`wiki-crystallize`) — save session insights as pages
+6. **Audit** (`wiki-audit`) — verify source integrity
+
+For longer-running project work, use `proj-init` → `proj-work` → `proj-distill` / `proj-decide`.
+
+Maintenance: **Archive** (`wiki-archive`) superseded pages, **Drift** (`wiki-reingest`) to detect stale sources, **Adapter** (`wiki-adapter-prd`) for foreign PRD format ingestion.
+
+## Multi-Wiki Profiles
+
+skillwiki supports named wiki profiles for working with multiple vaults. Set `WIKI_DEFAULT` to control which wiki all skills target by default.
+
+**Manage profiles:**
+- `skillwiki config set wiki.<name>.path <dir>` — register a profile
+- `skillwiki config set default <name>` — set active profile
+- `skillwiki config list --profiles` — list all profiles
+- `skillwiki --wiki <name> lint` — override per-command
+
+**Project-local override:** Place a `./skillwiki/.env` in a project root to bind that project to a specific wiki. Skills will use it automatically when running from that directory.
+
+## PRD Bridge — Redirect Spec/Plan Output to Vault
+
+When skillwiki is installed, **all spec and plan documents must land in the vault**, not in repo-local directories like `docs/superpowers/`. This applies to any PRD/design skill (superpowers:brainstorming, superpowers:writing-plans, CodeStable, AIDE, Hermes, etc.).
+
+**Rule:** Before a PRD skill writes a spec or plan file, redirect its save path:
+1. Resolve the vault path: `skillwiki path`
+2. If the cwd is inside a project (check for `projects/{slug}/` via `skillwiki path --init-time` or look for `./skillwiki/.env`), use that project's work directory
+3. Create or locate the work item via `proj-work`, which emits redirect paths for `spec.md` and `plan.md`
+4. Pass those vault paths to the PRD skill as its save location
+
+**Concrete overrides for superpowers:**
+- `superpowers:brainstorming` step 6: override `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` → vault work-item `spec.md` path from `proj-work`
+- `superpowers:writing-plans` header: override `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md` → vault work-item `plan.md` path from `proj-work`
+
+Both skills say "User preferences for spec location override this default" — the vault work-item path IS the override.
+
+**If no project context exists** (standalone vault, not inside a project), save specs/plans directly under the vault root with the PRD skill's default naming, e.g. `<vault>/specs/YYYY-MM-DD-<slug>.md`.
+
+**Never create `docs/superpowers/` in any repo.**

package/skills/wiki-adapter-prd/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: wiki-adapter-prd
+description: Map foreign PRD formats (CodeStable, RFCs, structured markdown) into skillwiki raw + typed-knowledge pages.
+---
+
+# wiki-adapter-prd
+
+## When This Skill Activates
+
+- User provides a document or URL in a non-skillwiki PRD format and wants it captured in the vault.
+- User mentions CodeStable, RFC, AIDE, or another structured design document format.
+- A foreign spec/plan needs to be normalized into the vault's raw + concept structure.
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate page prose in the resolved language. Frontmatter keys, file names, and structural markers stay English.
+
+## Pre-orientation reads
+
+Standard four reads (SCHEMA, index, log, project context if applicable).
+
+## Recognized PRD Formats
+
+| Format | Structural cues |
+|--------|----------------|
+| CodeStable | `REQ-NNN` requirement IDs, `## Requirements` / `## Architecture` headers |
+| RFC | `## Motivation` / `## Proposal` / `## Drawbacks` headers |
+| AIDE directives | Specific YAML frontmatter keys (`aide-*`) |
+| Hermes spec | `N1`–`N18` normative requirement markers |
+| Generic structured | Clear `##` section hierarchy with requirements, decisions, or designs |
+
+If the format is unrecognized, treat as generic structured markdown and map by section hierarchy.
+
+## Mapping Strategy
+
+### Raw capture (verbatim)
+
+- Write the full source document to `raw/articles/<slug>.md` with RawSourceSchema frontmatter (`sha256`, `source_url`, `ingested`, `ingested_by: "wiki-ingest"`).
+- If the source is a URL, run `skillwiki fetch-guard <url>` first.
+- Run `skillwiki hash <raw-file>` to compute sha256.
+
+### Knowledge extraction
+
+Map source sections to typed-knowledge pages:
+
+| Source section | Target type | Notes |
+|----------------|-------------|-------|
+| Requirements list | `concepts/` or `entities/` | Each major requirement becomes its own page or a section in a compound page |
+| Architecture decisions | `concepts/` | Map to concept pages with `tags: [architecture]` |
+| Motivation / context | `entities/` | Capture as entity pages describing the system or component |
+| Trade-offs / comparisons | `comparisons/` | Create comparison pages when the source weighs alternatives |
+| Action items / next steps | Skip | Not knowledge — track in project work items instead |
+
+### Cross-reference handling
+
+- Requirement IDs (`REQ-NNN`, `N1`–`N18`) → preserve as frontmatter tags or inline references.
+- Internal links within the source → convert to `[[wikilinks]]` where corresponding pages exist.
+- External URLs → keep as-is in body text.
+
+## Steps
+
+0. Resolve vault and language: `skillwiki path` and `skillwiki lang`.
+1. Classify the input format using the structural cues above.
+2. If URL source: run `skillwiki fetch-guard <url>`, then fetch.
+3. Write raw capture: frontmatter + full body → `raw/articles/<slug>.md`.
+4. Run `skillwiki hash <raw-file>`, embed sha256.
+5. Generate typed-knowledge pages following the mapping strategy.
+6. For each page: run `skillwiki validate <page>`. If any fails, STOP.
+7. Write pages, then update `index.md` and `log.md`.
+
+## Provenance defaults
+
+- `provenance: research` (external PRD sources).
+- `sources: ["^[raw/articles/<slug>.md]"]` on every generated page.
+
+## Stop conditions
+
+- `fetch-guard` non-zero.
+- `validate` non-zero on any page.
+- sha256 already exists for the same source (skip — already ingested).
+
+## Forbidden
+
+- Skipping `fetch-guard` for URL sources.
+- Writing index/log before all pages validate.
+- Modifying existing raw files (N9).
+- Auto-generating pages for action items, timelines, or process steps — those are project management, not knowledge.

package/skills/wiki-archive/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: wiki-archive
+description: Archive a superseded typed-knowledge page. Moves page to _archive/, removes from index.md, logs the action.
+---
+
+# wiki-archive
+
+## When This Skill Activates
+
+- User wants to retire, supersede, or remove a typed-knowledge page from active use.
+- A page has been replaced by a newer version and should be kept for reference but excluded from lint and queries.
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate log entries in the resolved language.
+
+## Pre-orientation reads
+
+Standard four reads (SCHEMA, index, log, project context if applicable).
+
+## Steps
+
+0. Resolve vault: `skillwiki path` and `skillwiki lang`.
+1. Identify the target page. Confirm with the user which page to archive (show full relPath).
+2. Run `skillwiki archive <page> [vault]`. Read the JSON output.
+3. Verify with `skillwiki index-check [vault]` — confirm no ghost entries remain.
+4. Run `skillwiki lint [vault]` — check for broken wikilinks from other pages that still reference the archived page. If found, update those pages to point to the replacement or remove the stale link.
+5. Append a `log.md` entry: `## [{date}] archive | {relPath} → _archive/{subdir}/`.
+
+## Reversibility
+
+Archiving is reversible: move the file back from `_archive/` to its original directory and re-add the wikilink entry to `index.md`. No data is deleted.
+
+## Stop conditions
+
+- `skillwiki archive` returns non-zero exit code (page not found, already archived, invalid vault).
+- User declines to proceed.
+
+## Forbidden
+
+- Archiving `raw/` files (N9 — raw is immutable).
+- Archiving without user confirmation.
+- Deleting files (archive moves, never deletes).

package/skills/wiki-audit/SKILL.md

@@ -19,7 +19,7 @@ Standard four reads.
 
 ## Steps
 0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
-1. `npx skillwiki audit <page>`. Read the JSON report.
+1. `skillwiki audit <page>`. Read the JSON report.
 2. Reason over the report:
    - For each unresolved marker: suggest ingesting the missing source or correcting the path.
    - For each `unused_sources` entry: suggest adding a body marker or removing from `sources:`.

package/skills/wiki-crystallize/SKILL.md

@@ -22,7 +22,7 @@ Standard four reads. If cwd is inside `projects/{slug}/`, also read project READ
 1. Identify type: entity / concept / comparison / query / summary.
 2. Set `provenance:`. Default `research`. If in project context: `project` with `provenance_projects: ["[[slug]]"]`.
 3. Compose the page with citations pre-attached. Reuse existing `raw/` sources where possible.
-4. `npx skillwiki validate <page>`. If non-zero, STOP.
+4. `skillwiki validate <page>`. If non-zero, STOP.
 5. Apply writes: page → `index.md` → `log.md`.
 
 ## Stop conditions

package/skills/wiki-ingest/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wiki-ingest
-description: Convert URLs, files, or pasted text into typed-knowledge pages with raw provenance. Single-pass v1.
+description: Convert URLs, files, or pasted text into typed-knowledge pages with raw provenance. Supports single and batch mode.
 ---
 
 # wiki-ingest
@@ -23,11 +23,11 @@ Run `skillwiki lang` at the start. Generate page-body prose, narrative sections,
 
 ## Steps (in order — N6, N7, N8)
 0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`. Use the resolved vault path for all writes; use the canonical language for all generated prose.
-1. **Guard.** For each URL: run `npx skillwiki fetch-guard <url>`. If exit ≠ 0, STOP and surface the error. Do not retry.
+1. **Guard.** For each URL: run `skillwiki fetch-guard <url>`. If exit ≠ 0, STOP and surface the error. Do not retry.
 2. **Fetch.** Use `web_fetch` (or read local file) under Layer 2 controls (the CLI Layer 2 fetcher applies in tests; in skill runtime use `web_fetch` directly and treat any error as STOP).
-3. **Hash.** Write the raw file (frontmatter + body). Run `npx skillwiki hash <raw-file>` and embed the result in raw frontmatter `sha256:`.
+3. **Hash.** Write the raw file (frontmatter + body). Run `skillwiki hash <raw-file>` and embed the result in raw frontmatter `sha256:`.
 4. **Generate page(s).** Compose typed-knowledge page(s) with citations pre-attached (`^[raw/...]` markers).
-5. **Validate.** For each generated page: run `npx skillwiki validate <page>`. If exit ≠ 0, STOP — do not write index/log.
+5. **Validate.** For each generated page: run `skillwiki validate <page>`. If exit ≠ 0, STOP — do not write index/log.
 6. **Apply writes in order.** raw → page(s) → `index.md` → `log.md`.
 7. **Confidence flag.** If only one source is cited, set `confidence: low`.
 
@@ -45,3 +45,14 @@ Run `skillwiki lang` at the start. Generate page-body prose, narrative sections,
 - Skipping `fetch-guard`.
 - Updating `index.md` or `log.md` before all pages validate.
 - Modifying any existing file in `raw/`.
+
+## Batch Mode
+
+When the user provides multiple sources (a directory of files, a list of URLs, or a multi-document input):
+
+1. **Loop per source.** Execute steps 1–5 for each source individually (guard → fetch → hash → generate → validate).
+2. **Accumulate, don't write yet.** Collect all raw files and pages in memory. Do not write `index.md` or `log.md` until every source has validated.
+3. **Fail fast.** If any page fails validation, STOP. Report all failures. Do not write index/log for any source.
+4. **Deduplication.** Before writing each raw file, check `sha256` against existing vault raw sources. Skip sources whose content is already present.
+5. **Single index/log update.** After all sources validate, write all raw files and pages, then update `index.md` and `log.md` once.
+6. **Progress.** After each source completes validation, report progress (e.g., "Validated 3/10 sources").

package/skills/wiki-lint/SKILL.md

@@ -18,7 +18,7 @@ Standard four reads.
 
 0. Resolve vault: `skillwiki path` (record source for context).
 1. Run `skillwiki lint <vault>`. Read the JSON.
-2. Reason over findings; present grouped by severity with concrete suggested actions per kind.
+2. Reason over findings; present grouped by severity with concrete suggested actions per kind. If the CLI was recently updated with new lint checks, re-running lint on the full vault may flag pre-existing pages that predate the new rule — treat these as legitimate findings, not false positives.
 3. If `log_rotate_needed` is present and the user consents, run `skillwiki log-rotate <vault> --apply`. Otherwise leave alone.
 4. Append one `log.md` entry summarizing the lint counts (errors/warnings/info).
 

package/skills/wiki-query/SKILL.md

@@ -20,8 +20,8 @@ Standard four reads (SCHEMA, index, log, project context if applicable).
 ## Steps
 0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
 1. **Determine scope.** Ask the user once if ambiguous: vault | current project | project+concepts.
-2. **Refresh graph.** If `.skillwiki/graph.json` is missing or older than 24h: `npx skillwiki graph build <vault>`.
-3. **Compute overlap.** `npx skillwiki overlap <vault>`.
+2. **Refresh graph.** If `.skillwiki/graph.json` is missing or older than 24h: `skillwiki graph build <vault>`.
+3. **Compute overlap.** `skillwiki overlap <vault>`.
 4. **Score candidates** in prompt using the 4 signals:
    - Direct wikilink: 3.0×
    - Source overlap: 4.0× (read from overlap output)

package/skills/wiki-reingest/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: wiki-reingest
+description: Detect and act on source drift. Runs skillwiki drift, reviews changes, archives old raw + ingests new content.
+---
+
+# wiki-reingest
+
+## When This Skill Activates
+
+- User wants to check if any vault sources have changed since ingestion.
+- Periodic drift check during lint or maintenance cycles.
+- User explicitly asks to re-ingest a specific source.
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate log entries in the resolved language.
+
+## Pre-orientation reads
+
+Standard four reads (SCHEMA, index, log, project context if applicable).
+
+## Steps
+
+0. Resolve vault: `skillwiki path` and `skillwiki lang`.
+1. Run `skillwiki drift [vault]`. Read the JSON output.
+2. Present findings grouped by status:
+   - **drifted:** Source content has changed. Show stored vs current sha256.
+   - **fetch_failed:** Could not re-fetch. Show error details.
+   - **unchanged:** No action needed.
+3. For each drifted source, ask the user: archive old + ingest new, or skip?
+4. If the user approves re-ingest for a source:
+   a. Run `skillwiki archive <raw-path>` to archive the old raw file.
+   b. Follow the `wiki-ingest` skill to ingest the updated content as a new raw file.
+   c. Update any concept/entity pages that cite the old source to reference the new one.
+5. Append a `log.md` entry summarizing: scanned, drifted, re-ingested, skipped.
+
+## N9 Compliance
+
+Raw files are immutable (N9). Re-ingest never modifies an existing raw file. Instead:
+- Archive the old raw file (moves to `_archive/raw/`).
+- Create a new raw file with updated content and new sha256.
+- This preserves full provenance history.
+
+## Stop conditions
+
+- `skillwiki drift` returns non-zero exit code other than DRIFT_DETECTED.
+- User declines all re-ingest actions.
+- No raw sources have `source_url` (nothing to check).
+
+## Forbidden
+
+- Modifying files in `raw/` directly (N9).
+- Re-ingesting without user approval for each drifted source.
+- Skipping the drift check and assuming sources have changed.