skillwiki 0.2.0-beta.1 → 0.2.0-beta.3

package/dist/cli.js

@@ -1238,7 +1238,7 @@ async function runLint(input) {
 
 // src/cli.ts
 var program = new Command();
-program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version("0.1.0");
+program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version("0.2.0-beta.3");
 program.option("--human", "render terminal-readable output instead of JSON");
 function emit(r) {
   if (program.opts().human) printHuman(r.result);
@@ -1257,7 +1257,7 @@ program.command("orphans [vault]").action(async (vault) => emit(await runOrphans
 })));
 program.command("audit <file>").action(async (file) => emit(await runAudit({ file })));
 program.command("install").option("--target <dir>", "target install directory", `${process.env.HOME ?? ""}/.claude/skills/`).option("--dry-run", "preview only", false).option("--skills-root <dir>", "source skills directory (defaults to packaged)").action(async (opts) => {
-  const skillsRoot = opts.skillsRoot ?? new URL("../../skills/", import.meta.url).pathname;
+  const skillsRoot = opts.skillsRoot ?? new URL("../skills/", import.meta.url).pathname;
   emit(await runInstall({ skillsRoot, target: opts.target, dryRun: !!opts.dryRun }));
 });
 program.command("path").option("--vault <dir>", "explicit vault override (runtime)").option("--target <dir>", "explicit target override (init-time)").option("--init-time", "use init-time chain instead of runtime", false).option("--explain", "include resolution chain in output", false).action(async (opts) => {

package/package.json

@@ -1,22 +1,22 @@
 {
   "name": "skillwiki",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.3",
   "type": "module",
   "bin": { "skillwiki": "dist/cli.js" },
-  "files": ["dist", "templates", "README.md"],
+  "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",

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

@@ -0,0 +1,23 @@
+{
+  "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).",
+  "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/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@skillwiki/skills",
+  "version": "0.1.0",
+  "private": true,
+  "files": ["wiki-*", "proj-*", ".claude-plugin", "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,26 @@
+---
+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)
+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`.
+
+## 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,29 @@
+---
+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.
+
+## 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/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,47 @@
+---
+name: wiki-ingest
+description: Convert URLs, files, or pasted text into typed-knowledge pages with raw provenance. Single-pass v1.
+---
+
+# 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/`.

package/skills/wiki-init/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: wiki-init
+description: Bootstrap a CodeWiki vault — domain-aware SCHEMA.md, index.md, log.md, and ~/.skillwiki/.env binding. Use when starting a fresh vault.
+---
+
+# wiki-init
+
+## When This Skill Activates
+
+- User asks to create, build, or start a vault, wiki, or knowledge base.
+- The resolved vault path (see step 0) does not yet contain SCHEMA.md.
+
+## Pre-orientation reads
+
+None for the first run.
+
+## Steps
+
+0. **Resolve target.** Run `skillwiki path --init-time` to see what target the CLI will pick. Confirm with the user, or override with `--target <dir>`.
+1. Verify target is empty or has no SCHEMA.md.
+2. Ask the domain question: "What knowledge domain will this vault cover? Be specific."
+3. Propose a 10–15 tag taxonomy tailored to the domain. Confirm or accept the user's revision.
+4. Ask the language question: "What language should generated page prose use? Default is `en`. Aliases like `chinese-traditional` or `zh-Hant` are accepted."
+5. Run `skillwiki init --target <dir> --domain "<answer>" --taxonomy "<comma list>" --lang "<lang>"`.
+6. **Suggest first sources.** Propose 3–5 initial sources (URLs, papers, articles) appropriate to the domain. Prompt the user to provide the first one to ingest, then hand off to wiki-ingest.
+
+## Stop conditions
+
+- Target non-empty and `--force` not consented.
+- `~/.skillwiki/.env` already binds a different vault or language and `--force` not consented.
+
+## Forbidden
+
+- Modifying anything outside the target directory or `~/.skillwiki/.env`.
+- Writing to `~/.hermes/.env` (read-only fallback).
+- Running any LLM-driven content generation in this skill.

package/skills/wiki-lint/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: wiki-lint
+description: Vault health check via the umbrella `skillwiki lint` subcommand. Read-only by default; rotation requires explicit user consent.
+---
+
+# wiki-lint
+
+## When This Skill Activates
+
+- User asks for a vault health report, lint, or audit.
+- Periodic maintenance.
+
+## Pre-orientation reads
+
+Standard four reads.
+
+## Steps
+
+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.
+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).
+
+## Stop conditions
+
+None — lint reports all findings even on per-page errors.
+
+## Forbidden
+
+- Auto-rotating logs.
+- Auto-updating sha256 fields.
+- Modifying any page beyond the lint summary entry in `log.md`.

package/skills/wiki-query/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: wiki-query
+description: Search the vault and synthesize an answer with E2 4-signal ranking. Optional file to queries/ or comparisons/.
+---
+
+# wiki-query
+
+## When This Skill Activates
+
+- User asks a question that should be answered from vault contents.
+- A vault is resolvable (see step 0).
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate query-result 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 (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>`.
+4. **Score candidates** in prompt using the 4 signals:
+   - Direct wikilink: 3.0×
+   - Source overlap: 4.0× (read from overlap output)
+   - Adamic-Adar: 1.5× (read from graph output)
+   - Type affinity: 1.0×
+5. **Read top candidates** in full (frontmatter + body).
+6. **Synthesize answer** with explicit citations to the candidate pages.
+7. **Optional file.** If user accepts: write to `queries/<slug>.md` or `comparisons/<slug>.md` with full frontmatter, validate, then update `index.md` then `log.md`.
+
+## Stop conditions
+- Zero matching pages.
+- User declines to file.
+
+## Forbidden
+- Filing without `validate` passing.
+- Skipping the orientation reads even for "quick" queries.