skillwiki 0.2.0-beta.1 → 0.2.0-beta.10

package/package.json

@@ -1,27 +1,40 @@
 {
   "name": "skillwiki",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.10",
   "type": "module",
-  "bin": { "skillwiki": "dist/cli.js" },
-  "files": ["dist", "templates", "README.md"],
+  "bin": {
+    "skillwiki": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "skills",
+    "README.md"
+  ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && rm -rf ./skills && cp -r ../skills ./skills",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@skillwiki/shared": "*",
     "commander": "^12.1.0",
     "js-yaml": "^4.1.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "@skillwiki/shared": "*",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.12.0",
     "tsup": "^8.3.0",
     "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

@@ -0,0 +1,24 @@
+{
+  "name": "skillwiki",
+  "version": "0.2.0-beta.10",
+  "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"
+  },
+  "homepage": "https://github.com/karlorz/llm-wiki",
+  "repository": "https://github.com/karlorz/llm-wiki",
+  "license": "MIT",
+  "keywords": [
+    "knowledge-base",
+    "wiki",
+    "obsidian",
+    "claude-code",
+    "skills",
+    "karpathy",
+    "markdown",
+    "research",
+    "rag-alternative"
+  ]
+}

package/skills/README.md

@@ -0,0 +1,10 @@
+# @skillwiki/skills
+
+Prompt-only Markdown skills for Claude Code. Installed via `skillwiki install`.
+
+| Namespace | Skills |
+|---|---|
+| `wiki-*` | `wiki-init`, `wiki-ingest`, `wiki-query`, `wiki-lint`, `wiki-crystallize`, `wiki-audit` |
+| `proj-*` | `proj-init`, `proj-work`, `proj-distill`, `proj-decide` |
+
+Each subdirectory holds one `SKILL.md`. No build step.

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

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

package/skills/proj-decide/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: proj-decide
+description: Write an Architectural Decision Record (ADR). If the decision generalizes, also create a concepts/ page.
+---
+
+# proj-decide
+
+## When to invoke
+- User commits to an architectural decision worth recording for future reference.
+
+## Pre-orientation reads
+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.
+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`.
+
+## Stop conditions
+- `validate` non-zero on either page.
+
+## Forbidden
+- Filing the concept page without explicit `provenance:`.

package/skills/proj-distill/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: proj-distill
+description: 2-step distillation (E4) — analyze project compound entry, then generate a vault concept page with provenance.
+---
+
+# proj-distill
+
+## When to invoke
+- A project compound entry captures a pattern that generalizes beyond the project.
+
+## Pre-orientation reads
+Standard four + project context.
+
+## Steps (E4 — 2-step pattern)
+
+### 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
+   `npx 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.
+- `validate` non-zero on either page.
+
+## Forbidden
+- Skipping Step 1 (no direct generation).
+- Updating index/logs before `validate` passes.

package/skills/proj-init/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: proj-init
+description: Bootstrap a project workspace at projects/{slug}/ with README, requirements/, architecture/, work/, compound/.
+---
+
+# proj-init
+
+## When to invoke
+- User starts a new project that should live inside the vault.
+
+## Pre-orientation reads
+Standard four reads (vault SCHEMA, index, log) — no project context yet.
+
+## Inputs
+- Slug (lowercase, hyphenated).
+- One-line intent.
+
+## Steps
+1. Verify `projects/{slug}/` does not exist.
+2. Create folders: `projects/{slug}/{requirements,architecture,work,compound}/`.
+3. Render `projects/{slug}/README.md` from `project-README.md` template, filling `{{slug}}` and `{{date}}`.
+4. Update vault `index.md` "Projects" section: add `- [[projects/{slug}]]`.
+5. Append vault `log.md` entry: "Project {slug} initialized."
+
+## Stop conditions
+- `projects/{slug}/` already exists.
+
+## Forbidden
+- Modifying any other project's files.

package/skills/proj-work/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: proj-work
+description: Open or run a work item under projects/{slug}/work/YYYY-MM-DD-{slug}/. Redirects brainstorming/writing-plans output paths.
+---
+
+# proj-work
+
+## When to invoke
+- User starts a feature, issue, refactor, or decision inside an existing project.
+- Brainstorming or writing-plans skills would otherwise default-write outside the project tree.
+
+## Pre-orientation reads
+Standard four + project context (project README, last ~5 work logs).
+
+## Steps
+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.
+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.
+
+## Forbidden
+- Writing spec/plan files outside the work folder.
+- Marking `status: completed` without a `completed:` date.

package/skills/using-skillwiki/SKILL.md

@@ -0,0 +1,65 @@
+---
+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
+
+## 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.

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,42 @@
+---
+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. 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

@@ -0,0 +1,33 @@
+---
+name: wiki-audit
+description: Verify per-page that every ^[raw/...] resolves and sources frontmatter matches the body.
+---
+
+# wiki-audit
+
+## When This Skill Activates
+
+- User asks for a per-page audit or invokes a pre-merge gate.
+- A vault is resolvable (see step 0).
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate audit narrative and `--human` summaries in the resolved language. Frontmatter keys, file names, schema headers, index/log structural lines, citation markers, and wikilink slugs MUST stay English.
+
+## Pre-orientation reads
+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.
+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:`.
+   - For each `missing_from_sources` entry: suggest adding to `sources:`.
+3. Append one `log.md` entry summarizing the audit and any suggested follow-ups.
+
+## Stop conditions
+None — audit always completes.
+
+## Forbidden
+- Auto-applying suggested fixes (audit is observation-only).

package/skills/wiki-crystallize/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: wiki-crystallize
+description: Distill the current working session into a typed-knowledge page with provenance.
+---
+
+# wiki-crystallize
+
+## When This Skill Activates
+
+- User asks to crystallize, consolidate, or promote draft material into typed-knowledge pages.
+- A vault is resolvable (see step 0).
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate consolidated page prose and `--human` summaries in the resolved language. Frontmatter keys, file names, schema headers, index/log structural lines, citation markers, and wikilink slugs MUST stay English.
+
+## Pre-orientation reads
+Standard four reads. If cwd is inside `projects/{slug}/`, also read project README and recent work logs.
+
+## Steps
+0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
+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.
+5. Apply writes: page → `index.md` → `log.md`.
+
+## Stop conditions
+- `validate` non-zero.
+- Missing `provenance:` for project-context runs.
+
+## Forbidden
+- Filing without explicit `provenance:`.
+- Updating `index.md` before `validate` passes.

package/skills/wiki-ingest/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: wiki-ingest
+description: Convert URLs, files, or pasted text into typed-knowledge pages with raw provenance. Supports single and batch mode.
+---
+
+# wiki-ingest
+
+## When This Skill Activates
+
+- User shares a URL, paste, or local file to capture in the vault.
+- The output target is `entities/`, `concepts/`, `comparisons/`, or `queries/`.
+- A vault is resolvable (see step 0).
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate page-body prose, narrative sections, and `--human` summaries in the resolved language. Frontmatter keys, file names, schema headers, index/log structural lines, citation markers, and wikilink slugs MUST stay English.
+
+## Pre-orientation reads (mandatory before any write)
+1. `SCHEMA.md`
+2. `index.md`
+3. Last 20–30 entries of `log.md`
+4. (Project context only) `projects/{slug}/README.md` and last ~5 work-item logs.
+
+## 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.
+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:`.
+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.
+6. **Apply writes in order.** raw → page(s) → `index.md` → `log.md`.
+7. **Confidence flag.** If only one source is cited, set `confidence: low`.
+
+## Provenance defaults
+- Default `provenance: research`.
+- If cwd is inside `projects/{slug}/`, set `provenance: project` and add `provenance_projects: ["[[slug]]"]`.
+
+## Stop conditions
+- `fetch-guard` non-zero.
+- Fetch timeout / size limit exceeded.
+- `validate` non-zero on any page.
+- sha256 already exists in vault for the same source.
+
+## Forbidden
+- 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").