skillwiki 0.4.2 → 0.4.3

package/skills/using-skillwiki/SKILL.md

@@ -3,17 +3,12 @@ version: 0.2.1
 name: using-skillwiki
 description: Invoke at session start or when knowledge-base tasks arise — maps all skillwiki 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
@@ -29,13 +24,9 @@ Invoke a skillwiki skill when the user:
 - Wants to sync vault changes to/from a git remote
 - Wants to visualize the vault graph as an Obsidian Canvas
 - Wants to run a research scan of repo and vault health
-
 ## Vault Structure
-
 A skillwiki vault has three layers. The canonical architecture lives in `SCHEMA.md` at the vault root — read it before creating any new directories.
-
 **Layer 1 — Raw (`raw/`):** Immutable source material. Never modify after ingest. `raw/transcripts/` doubles as the ad-hoc capture point for meeting notes and unprocessed ideas.
-
 ```
 raw/
 ├── articles/    # Web articles, clippings
@@ -43,7 +34,6 @@ raw/
 ├── transcripts/ # Meeting notes, interviews, ad-hoc captures
 └── assets/      # Images, diagrams referenced by sources
 ```
-
 Raw frontmatter:
 ```yaml
 ---
@@ -52,23 +42,16 @@ ingested: YYYY-MM-DD
 sha256:          # computed by skillwiki hash over body bytes after closing ---
 ---
 ```
-
 **Layer 2 — Typed Knowledge:** `entities/`, `concepts/`, `comparisons/`, `queries/`, `meta/`. Agent-owned pages with `^[raw/...]` citation markers at paragraph-end. Global scope — project association via `provenance_projects:` frontmatter, not directory nesting.
-
 **Layer 3 — Project Workspaces (`projects/{slug}/`):** Per-project lifecycle directories with `work/` (spec + plan + retro), `compound/` (distilled lessons/patterns), `architecture/` (ADRs), and `history/` (archived specs/plans).
-
 **No `inbox/` directory.** Ad-hoc captures go to `raw/transcripts/` or directly into a project work item via `proj-work`. Do not invent new top-level directories — extend Layer 2 via SCHEMA.md tag taxonomy if needed.
-
 ### Ad-hoc capture: three entry points
-
 | Entry | When | What happens |
 |-------|------|-------------|
 | `/wiki-add-task <text>` | You're in a Claude session | Creates `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md` with ad-hoc capture frontmatter |
 | Filesystem drop | You're NOT in a Claude session (Obsidian, editor, sync) | Create/edit any `.md` file in `raw/transcripts/` — dev-loop discovers it on next cycle |
 | Dev-loop discovery | Automatic, next cycle | Scans `raw/transcripts/` for new files since last cycle, surfaces as claimable work |
-
 ## Skill Map
-
 | Skill | When to Invoke |
 |-------|----------------|
 | `wiki-init` | Bootstrap a new vault — SCHEMA.md, index.md, log.md, ~/.skillwiki/.env |
@@ -89,56 +72,48 @@ sha256:          # computed by skillwiki hash over body bytes after closing ---
 | `proj-decide` | Write an Architectural Decision Record (ADR) |
 | `wiki-gate-plan-mode` | Toggle EnterPlanMode gating — force superpowers planning instead of built-in plan mode |
 | `dev-loop-research` | Standalone research agent — scans repo + vault health, outputs prioritized work-item recommendations |
-
 ## 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`, `compound`, `tag-sync`, `sync status`, `seed`, `stale`, `observe`, `canvas generate`.
-
 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.
-
+## Troubleshooting Version Drift
+skillwiki has three distribution channels that can drift:
+| Channel | Location | Update Command |
+|---------|----------|----------------|
+| npm CLI | `/usr/local/bin/skillwiki` | `npm install -g skillwiki@latest` |
+| npm skills | `/usr/local/lib/node_modules/skillwiki/skills/` | `skillwiki install` (copies to `~/.claude/skills/`) |
+| Claude plugin | `~/.claude/plugins/cache/llm-wiki/` | `claude plugin update skillwiki@llm-wiki` |
+| Local git dev | `~/.hermes/skills/llm-wiki/` | `npm link ./packages/cli` (from repo root) |
+**Check versions:** `skillwiki doctor` reports "Plugin/CLI version" mismatch warnings.
+**Common issue:** npm package ships SKILL.md files with older `version:` frontmatter than CLI code. This creates false-positive "version warnings" in `skillwiki doctor` — the CLI is newer but skills report older version.
+**Fix:** If developing locally, use `npm link` from the git repo. If using released versions, wait for maintainer to bump SKILL.md versions in source and republish.
 ## 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), default to the `playground` project slug. Invoke `proj-work` with `playground` as the slug so redirect paths are emitted normally and the PRD bridge chain works. The `playground` project is a pre-initialized catch-all workspace at `projects/playground/` for exploratory work, experiments, and unclassified features. Work items that mature can be moved to a real project later.
-
 **Never create `docs/superpowers/` in any repo.**

package/skills/wiki-add-task/SKILL.md

@@ -1,132 +1,102 @@
 ---
-version: 0.2.1
+version: 0.2.2
 name: wiki-add-task
 description: Capture ad-hoc ideas, bugs, tasks, or notes into the vault with ad-hoc capture frontmatter and descriptive filenames.
 ---
-
 # wiki-add-task
-
 Capture ad-hoc ideas, bugs, tasks, and notes into the vault. Three entry points depending on where you are:
-
 | Entry | When | What happens |
 |-------|------|-------------|
-| `/wiki-add-task <text>` | You're in a Claude session | Creates `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md` with ad-hoc capture frontmatter |
+| `/wiki-add-task <text>` | You're in a Claude Code session (NOT Hermes compact) | Creates `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md` with ad-hoc capture frontmatter |
+| `skillwiki add-task <text>` | Hermes Agent compact mode | Same as above — compact-compatible CLI trigger |
 | Filesystem drop | You're NOT in a Claude session (Obsidian, editor, sync) | Create any `.md` file in `raw/transcripts/` using the vault template — dev-loop discovers it on next cycle |
 | Dev-loop discovery | Automatic, next cycle | Scans `raw/transcripts/` for new files since last cycle, surfaces as claimable work |
-
+**Path Rule:** Captures ALWAYS go to `$(skillwiki path)/raw/transcripts/` (Layer 1). Never under `projects/{slug}/raw/` — that violates SCHEMA.md Layer 1 immutability.
+### Exception: Explicit project task requests
+When the user explicitly says "raise task to project X", "add a task for X", "create a feature request for X", or uses a directive structure like "raise task to {project} {description}", the intent is a **work item**, not a capture:
+| User wording | Action | Target |
+|---|---|---|
+| "capture this", "note this", "remember this" | Use wiki-add-task (this skill) | `raw/transcripts/` |
+| "raise task to project X", "add task to X project" | Escalate to `proj-work` | `projects/{slug}/work/YYYY-MM-DD-{slug}/task.md` |
+| "save to wiki" + content | Use `wiki-ingest` | `concepts/`, `entities/`, etc. |
+This is NOT a violation of the "ALWAYS" rule below — explicit project task requests are a distinct user intent that bypasses raw capture and goes directly to a Layer 3 work item.
 ## When This Skill Activates
-
 - User invokes `/wiki-add-task` with a description.
 - User says "add task", "capture this", "note this", "remember this", "log this idea", or similar.
 - User provides a short text description and optionally a type tag.
-
+- **Do NOT activate** when the user says "raise task to project X" or "add work item to project X" — escalate to `proj-work` instead.
 ## Output language
-
 Run `skillwiki lang` at the start. Entry prose and `--human` summaries use the resolved language. Frontmatter keys, file names, and structural markers stay English.
-
 ## Steps
-
 0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
 1. **Parse arguments.** Extract from the user's message:
-   - `text` — the idea/bug/task/note content (required)
-   - `type` — one of: `idea`, `bug`, `task`, `note` (default: `task`)
-   - `project` — project slug for claim detection (e.g., `llm-wiki`). Required for `task` and `bug` types to appear in `skillwiki stale` unclaimed list.
+- `text` — the idea/bug/task/note content (required)
+- `type` — one of: `idea`, `bug`, `task`, `note` (default: `idea`)
+- `project` — optional project slug to cross-reference (e.g., `llm-wiki`)
 2. **Build filename.** Derive a slug from the first ~6 words of the text (lowercased, hyphens for spaces, non-alphanumeric stripped). The capture file is `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md`. Each capture gets its own file — never append to an existing file.
 3. **Write frontmatter.** Create the file with ad-hoc capture frontmatter:
-   ```yaml
-   ---
-   source_url:
-   created: YYYY-MM-DD
-   ingested:          # filled by ingest pipeline
-   kind: {type}
-   project: "[[{slug}]]"
-   ---
-   ```
-   - Set `kind` to the parsed type (`idea`, `bug`, `task`, `note`).
-   - Set `project: "[[slug]]"` — **required for claim detection**. Without this field, the transcript is invisible to `skillwiki stale`. If no project context exists, ask the user which project this capture belongs to.
-   - `source_url` is null (these are locally originated captures).
-   - `created` — today's date. `ingested` is left empty for the ingest pipeline.
-   - No `sha256` — ad-hoc captures are mutable working notes, not immutable sources.
+```yaml
+---
+source_url:
+ingested: YYYY-MM-DD
+kind: {type}
+project: "[[{slug}]]"
+---
+```
+- Set `kind` to the parsed type (`idea`, `bug`, `task`, `note`).
+- If a `project` slug was provided, set `project: "[[slug]]"`.
+- If no project, omit the `project` field entirely.
+- `source_url` is null (these are locally originated captures).
+- No `sha256` — ad-hoc captures are mutable working notes, not immutable sources.
 4. **Write body.** Below the frontmatter, write:
-   ```markdown
-   # {type}: {text}
-
-   {text}
-   ```
-   Use the resolved output language for any prose. The type label and frontmatter stay English.
+```markdown
+# {type}: {text}
+{text}
+```
+Use the resolved output language for any prose. The type label and frontmatter stay English.
 5. **Cross-reference (optional).** If a `project` slug was provided:
-   - Check that `projects/{slug}/` exists in the vault.
-   - Append a one-line reference to the project's compound notes:
-     `- [YYYY-MM-DD] capture: [text (first 60 chars)] → raw/transcripts/YYYY-MM-DD-{type}-{slug}.md`
-   - Do NOT create a full work item (that's `proj-work`'s job).
+- Check that `projects/{slug}/` exists in the vault.
+- Append a one-line reference to the project's compound notes:
+`- [YYYY-MM-DD] capture: [text (first 60 chars)] → raw/transcripts/YYYY-MM-DD-{type}-{slug}.md`
+- Do NOT create a full work item (that's `proj-work`'s job).
 6. **Update log.md.** Append: `## [YYYY-MM-DD] capture | [type]: [text (first 60 chars)]`
 7. **Confirm to user.** Report what was captured and where. Suggest next steps:
-   - If `type: idea` → "Consider ingesting related sources to develop this idea."
-   - If `type: bug` → "Use proj-work to create a bug-fix work item."
-   - If `type: task` → "Use proj-work to track this task through the dev loop."
-   - If `type: note` → "Will be available for future wiki-query searches."
-
+- If `type: idea` → "Consider ingesting related sources to develop this idea."
+- If `type: bug` → "Use proj-work to create a bug-fix work item."
+- If `type: task` → "Use proj-work to track this task through the dev loop."
+- If `type: note` → "Will be available for future wiki-query searches."
 ## Capture file format
-
 Each capture is a standalone file with ad-hoc capture frontmatter:
-
 ```yaml
 ---
 source_url:
-created: 2026-05-08
-ingested:
+ingested: 2026-05-08
 kind: idea
 project: "[[llm-wiki]]"
 ---
-
 # idea: Fix the template mismatch
-
 Fix the template mismatch between wiki-add-task and the vault template.
 ```
-
 The `kind` field uses the capture type and must be one of: `idea`, `bug`, `task`, `note` (plus the existing `postmortem`, `session-log`, `meeting-notes`, `other` for non-capture raw sources).
-
-The `project` field is **required for claim detection**. Without it, `skillwiki stale` cannot surface the transcript as unclaimed work. The `kind` and `project` fields can be set independently — they do not require `work_item`. The `work_item` field is only used when the raw source is directly tied to a project work item (set by `proj-work`).
-
+The `project` and `kind` fields can be set independently — they do not require `work_item`. The `work_item` field is only used when the raw source is directly tied to a project work item (set by `proj-work`).
 Ad-hoc captures omit `sha256` — they are mutable working notes, not immutable sources. The `sha256` field is reserved for ingested raw sources that require integrity verification.
-
 ## Stop conditions
-
 - `skillwiki path` returns NO_VAULT_CONFIGURED.
 - No `text` provided (prompt user once, then stop).
 - Target file already exists (use a different slug or add a suffix).
-
 ## Forbidden
-
 - Creating an `inbox/` directory. All captures go to `raw/transcripts/`.
 - Appending to existing capture files — each capture gets its own file.
 - Creating a work item — this is capture-only. Use `proj-work` for full work items.
 - Writing to any Layer 2 or Layer 3 location. Captures are Layer 1 (raw).
-
 ## Filesystem drop (offline capture)
-
 When you're not in a Claude session, drop files directly into `raw/transcripts/`:
-
 1. Create a `.md` file in `raw/transcripts/` — name it descriptively (e.g., `2026-05-08-idea-fix-template.md`)
-2. Use ad-hoc capture frontmatter: `source_url:`, `ingested:`, `kind:`, and `project:` (required for `task`/`bug`)
+2. Use ad-hoc capture frontmatter: `source_url:`, `ingested:`, `kind:`, and optionally `project:`
 3. Write your idea/bug/task/note below the frontmatter
-
-**For claim detection**, `kind` must be `task` or `bug` AND `project: "[[slug]]"` must be set. Without both fields, the transcript won't appear in `skillwiki stale` unclaimed list.
-
-No special format required — `skillwiki stale --days 0` will detect unclaimed task/bug transcripts on the next run. Mark the type with a heading like `## idea`, `## bug`, `## task`, or just write freeform.
-
+No special format required — the dev-loop QUERY step will discover new files on the next cycle and surface them as claimable work. Mark the type with a heading like `## idea`, `## bug`, `## task`, or just write freeform.
 ## Dev-loop discovery
-
-`skillwiki stale` detects unclaimed transcripts automatically. A transcript is **unclaimed** when:
-- `kind` is `task` or `bug`
-- `project` field is set (e.g., `project: "[[llm-wiki]]"`)
-- No work item matches it (via date-prefix or `source:` frontmatter reference in spec.md)
-
-Run `skillwiki stale --days 0 --human` to see all unclaimed transcripts. The output includes an `unclaimed_transcripts` section listing each capture that needs a work item.
-
-The agent then decides whether to:
-- Create a work item via `proj-work` (for tasks and bugs) — set `source:` in spec.md to the transcript path for cross-date linking
+When the dev-loop QUERY step runs, it should scan `raw/transcripts/` for files with `ingested:` date newer than the last cycle. New files are surfaced as claimable work items. The agent then decides whether to:
+- Create a work item via `proj-work` (for tasks and bugs)
 - Ingest as a knowledge page via `wiki-ingest` (for ideas with sources)
 - Leave in place (for notes that don't need action yet)
-
-Transcripts without `kind` or `project` fields (e.g., `loop-cycle-*` session logs) are excluded from claim detection.

package/skills/wiki-crystallize/SKILL.md

@@ -3,35 +3,26 @@ version: 0.2.1
 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. Every page MUST include:
-   - `## TL;DR` as the first section after frontmatter — a 1–3 bullet summary of the page's key takeaway.
-   - For pages tagged `architecture` or explaining workflows/systems: include a Mermaid diagram (`graph TB` or `sequenceDiagram`) in the body. Follow Obsidian-compatible Mermaid rules (see SCHEMA.md `## Mermaid Diagrams`).
+- `## TL;DR` as the first section after frontmatter — a 1–3 bullet summary of the page's key takeaway.
+- For pages tagged `architecture` or explaining workflows/systems: include a Mermaid diagram (`graph TB` or `sequenceDiagram`) in the body. Follow Obsidian-compatible Mermaid rules (see SCHEMA.md `## Mermaid Diagrams`).
 4. `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

@@ -3,57 +3,50 @@ version: 0.2.1
 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 `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 `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). Every page MUST include:
-   - `## TL;DR` as the first section after frontmatter — a 1–3 bullet summary of the page's key takeaway.
-   - For pages tagged `architecture` or explaining workflows/systems: include a Mermaid diagram (`graph TB` or `sequenceDiagram`) in the body. Follow Obsidian-compatible Mermaid rules (see SCHEMA.md `## Mermaid Diagrams`).
+- `## TL;DR` as the first section after frontmatter — a 1–3 bullet summary of the page's key takeaway.
+- For pages tagged `architecture` or explaining workflows/systems: include a Mermaid diagram (`graph TB` or `sequenceDiagram`) in the body. Follow Obsidian-compatible Mermaid rules (see SCHEMA.md `## Mermaid Diagrams`).
 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`.
-
 ## Provenance defaults
 - Default `provenance: research`.
 - If cwd is inside `projects/{slug}/`, set `provenance: project` and add `provenance_projects: ["[[slug]]"]`.
-
+## Raw Data Locality
+Raw ephemeral data (market feeds, logs, transient JSON) must be written to the **project local** `raw/` directory, NOT the cloud-mounted wiki path. See `references/raw-data-locality.md` for the full pattern.
+**Quick rule:**
+- Transient data → `~/projects/{slug}/raw/` (local, git-tracked)
+- Compound pages → `~/wiki/projects/{slug}/compound/` (cloud, durable)
 ## 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/`.
+- Writing raw ephemeral data directly to cloud-mounted wiki paths (`~/wiki/`).
 - Writing `[[wikilinks]]` to pages that don't exist in the vault. Before linking, verify the target exists: check `index.md` or `ls` the target directory. If the target doesn't exist yet, use plain text instead of a wikilink.
-
 ## 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.

package/skills/wiki-lint/SKILL.md

@@ -1,34 +1,25 @@
 ---
-version: 0.2.1
+version: 0.2.2
 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).
+- **CRITICAL**: Verify the correct vault when the user has multiple wiki instances (e.g., ~/wiki vs ~/wiki-fin). User may explicitly specify which vault to target — confirm before destructive operations.
 1. Run `skillwiki lint <vault>`. Read the JSON.
 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).
-
+4. **Post-migration verification**: If the user recently migrated content (e.g., moved entity/concept pages to another vault), re-run lint and verify that broken_wikilinks count decreased. Remaining broken links for migrated content indicate pages still referencing the moved files — these should be cleaned up (remove citations or migrate the referencing pages too).
+5. 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

@@ -1,41 +1,36 @@
 ---
-version: 0.2.1
+version: 0.2.2
 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: `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)
-   - Adamic-Adar: 1.5× (read from graph output)
-   - Type affinity: 1.0×
+- 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.
-
+## Pitfalls
+### Claimed-status vs actual-state gap
+When a wiki page (especially a work item `tasks.md`) claims that fixes were applied, features were completed, or files were removed — **verify on disk before accepting the claim**. In one incident, a `tasks.md` marked 6 items DONE but 5 were not actually applied: a script claimed "removed" was still 2020 bytes on disk, a crontab claimed "updated to 30min" was still `*/10`, and a build target claimed "verified has consumers" had no web server serving it. 
+**Rule**: After reading a work item that declares completion, run at least one verification command per critical claim (check file existence, grep a config, inspect a crontab). Documents can drift from reality — the filesystem is the source of truth.
 ## Forbidden
 - Filing without `validate` passing.
 - Skipping the orientation reads even for "quick" queries.