skillwiki 0.2.1-beta.9 → 0.2.2

package/dist/git-M4WGJ5G3.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import {
+  git,
+  gitStrict
+} from "./chunk-TPS5XD2J.js";
+export {
+  git,
+  gitStrict
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.1-beta.9",
+  "version": "0.2.2",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"
@@ -19,6 +19,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1045.0",
+    "@aws-sdk/credential-provider-env": "^3.972.34",
     "commander": "^12.1.0",
     "js-yaml": "^4.1.0",
     "zod": "^3.23.0"

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

@@ -1,8 +1,8 @@
 {
   "name": "skillwiki",
-  "version": "0.2.1-beta.9",
+  "version": "0.2.2",
   "skills": "./",
-  "description": "Project-aware Karpathy-style knowledge base for Claude Code: 15 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
+  "description": "Project-aware Karpathy-style knowledge base for Claude Code: 18 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {
     "name": "karlorz",
     "url": "https://github.com/karlorz"

package/skills/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.2.1-beta.9",
+  "version": "0.2.2",
   "private": true,
   "files": [
     "wiki-*",
     "proj-*",
+    "dev-loop-research",
     "using-skillwiki",
     ".claude-plugin",
     "hooks",

package/skills/proj-decide/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: proj-decide
 description: Write an Architectural Decision Record (ADR). If the decision generalizes, also create a concepts/ page.
 ---
@@ -12,7 +13,7 @@ description: Write an Architectural Decision Record (ADR). If the decision gener
 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.
+1. Compose the ADR in `projects/{slug}/architecture/YYYY-MM-DD-{adr-slug}.md`. Frontmatter: kind=decision, status=in-progress or completed, project link. If no project context exists, default to `playground`.
 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

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: proj-distill
 description: 2-step distillation (E4) — analyze project compound entry, then generate a vault concept page with provenance.
 ---
@@ -15,7 +16,7 @@ Standard four + project context.
 
 ### Source selection
 
-Check `projects/{slug}/compound/` first. If empty, fall back to retro
+Check `projects/{slug}/compound/` first. If no project context exists, default to `playground`. If empty, fall back to retro
 entries in vault `log.md` (lines matching `## [YYYY-MM-DD] retro`).
 
 When reading retros as source material:
@@ -32,6 +33,12 @@ When reading retros as source material:
    `provenance: project` and
    `provenance_projects: ["[[slug]]"]`. Validate with
    `skillwiki validate`.
+   - **Tag hygiene:** `tags:` must only contain entries from
+     `{vault}/SCHEMA.md` taxonomy. Never derive tags from prose text
+     (lesson/evidence sections) — use only established taxonomy tags
+     (e.g., `dev-loop`, `lint`, `vault`). If no relevant taxonomy tag
+     exists, use `[dev-loop]` as the safe default rather than inventing
+     new tags. New tags must be added to SCHEMA.md first.
 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

package/skills/proj-init/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: proj-init
 description: Bootstrap a project workspace at projects/{slug}/ with README, requirements/, architecture/, work/, compound/.
 ---
@@ -18,7 +19,7 @@ Standard four reads (vault SCHEMA, index, log) — no project context yet.
 ## 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}}`.
+3. Render `projects/{slug}/README.md` from `project-README.md` template, filling `{{slug}}` and `{{date}}`. The template includes a `## Knowledge Pages` section with a placeholder; agents populate it on first ingest via `skillwiki project-index`.
 4. Update vault `index.md` "Projects" section: add `- [[projects/{slug}]]`.
 5. Append vault `log.md` entry: "Project {slug} initialized."
 

package/skills/proj-work/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: proj-work
 description: Open or run a work item under projects/{slug}/work/YYYY-MM-DD-{slug}/. Redirects brainstorming/writing-plans output paths.
 ---
@@ -8,6 +9,7 @@ description: Open or run a work item under projects/{slug}/work/YYYY-MM-DD-{slug
 ## 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.
+- If no project context can be determined, default to the `playground` slug so redirect paths always emit and the PRD bridge chain works.
 
 ## Pre-orientation reads
 Standard four + project context (project README, last ~5 work logs).

package/skills/using-skillwiki/SKILL.md

@@ -1,6 +1,7 @@
 ---
+version: 0.2.1
 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
+description: Invoke at session start or when knowledge-base tasks arise — maps all skillwiki skills and teaches the skillwiki CLI workflow
 ---
 
 <SUBAGENT-STOP>
@@ -25,6 +26,9 @@ Invoke a skillwiki skill when the user:
 - 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
+- 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
 
@@ -59,7 +63,7 @@ sha256:          # computed by skillwiki hash over body bytes after closing ---
 
 | Entry | When | What happens |
 |-------|------|-------------|
-| `/wiki-add-task <text>` | You're in a Claude session | Appends entry to `raw/transcripts/YYYY-MM-DD-ad-hoc-captures.md` |
+| `/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 |
 
@@ -80,13 +84,17 @@ sha256:          # computed by skillwiki hash over body bytes after closing ---
 | `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 |
+| `wiki-sync` | Safely sync vault git repository — push/pull with lint guards and conflict resolution |
+| `wiki-canvas` | Generate Obsidian Canvas visualization from vault graph data |
 | `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`.
+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.
 
@@ -131,6 +139,6 @@ When skillwiki is installed, **all spec and plan documents must land in the vaul
 
 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`.
+**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-adapter-prd/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: wiki-adapter-prd
 description: Map foreign PRD formats (CodeStable, RFCs, structured markdown) into skillwiki raw + typed-knowledge pages.
 ---

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

@@ -1,6 +1,7 @@
 ---
+version: 0.2.1
 name: wiki-add-task
-description: Capture ad-hoc ideas, bugs, tasks, or notes into the vault via /wiki-add-task or filesystem drop.
+description: Capture ad-hoc ideas, bugs, tasks, or notes into the vault with ad-hoc capture frontmatter and descriptive filenames.
 ---
 
 # wiki-add-task
@@ -9,8 +10,8 @@ Capture ad-hoc ideas, bugs, tasks, and notes into the vault. Three entry points
 
 | Entry | When | What happens |
 |-------|------|-------------|
-| `/wiki-add-task <text>` | You're in a Claude session | Appends entry to `raw/transcripts/YYYY-MM-DD-ad-hoc-captures.md` |
-| Filesystem drop | You're NOT in a Claude session (Obsidian, editor, sync) | Create/edit any file in `raw/transcripts/` — dev-loop discovers it on next cycle |
+| `/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 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 |
 
 ## When This Skill Activates
@@ -30,52 +31,73 @@ Run `skillwiki lang` at the start. Entry prose and `--human` summaries use the r
    - `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. **Determine target file.** The capture file is `raw/transcripts/YYYY-MM-DD-ad-hoc-captures.md` where YYYY-MM-DD is today's date. If the file exists, append; otherwise create it with standard raw frontmatter.
-3. **Write the entry.** Append to the capture file:
+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:
+   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
-   ### HH:MM — [type]
-
-   [text]
+   # {type}: {text}
 
-   <!---meta: {"captured_at": "YYYY-MM-DDTHH:MM:SS", "type": "[type]"}--->
+   {text}
    ```
-   - Use 24-hour time for HH:MM.
-   - Do not overwrite or modify existing entries.
-4. **Cross-reference (optional).** If a `project` slug was provided:
+   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 work log or compound notes:
-     `- [YYYY-MM-DD] capture: [text] → raw/transcripts/YYYY-MM-DD-ad-hoc-captures.md`
+   - 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).
-5. **Update log.md.** Append: `## [YYYY-MM-DD] capture | [type]: [text (first 60 chars)]`
-6. **Confirm to user.** Report what was captured and where. Suggest next steps:
+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."
 
-## Ad-hoc captures file format
+## Capture file format
 
-The file `raw/transcripts/YYYY-MM-DD-ad-hoc-captures.md` is a standard raw source with frontmatter:
+Each capture is a standalone file with ad-hoc capture frontmatter:
 
 ```yaml
 ---
 source_url:
-ingested: YYYY-MM-DD
-sha256:
+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 `sha256` is computed over the body after the closing `---`. On each append, recompute and update `sha256`. This keeps source-drift detection functional even though the file grows throughout the day.
+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` 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/`.
-- Modifying existing entries in the captures file — only append.
+- 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).
 
@@ -83,15 +105,8 @@ The `sha256` is computed over the body after the closing `---`. On each append,
 
 When you're not in a Claude session, drop files directly into `raw/transcripts/`:
 
-1. Create any `.md` file in `raw/transcripts/` — name it descriptively (e.g., `2026-05-07-idea-xyz.md`)
-2. Add raw frontmatter at the top:
-   ```yaml
-   ---
-   source_url:
-   ingested: YYYY-MM-DD
-   sha256:
-   ---
-   ```
+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 optionally `project:`
 3. Write your idea/bug/task/note below the frontmatter
 
 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.

package/skills/wiki-archive/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: wiki-archive
 description: Archive a superseded typed-knowledge page. Moves page to _archive/, removes from index.md, logs the action.
 ---
@@ -25,7 +26,8 @@ Standard four reads (SCHEMA, index, log, project context if applicable).
 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}/`.
+5. **Raw file archiving (N9 Reingest Protocol only):** When archiving a `raw/` file due to content drift, update ALL `^[raw/...]` citation markers and `sources:` frontmatter entries that reference the old path. Change `raw/articles/foo.md` to `_archive/raw/articles/foo.md` in every referencing page. Verify with `skillwiki audit` that no broken markers remain.
+6. Append a `log.md` entry: `## [{date}] archive | {relPath} → _archive/{subdir}/`.
 
 ## Reversibility
 
@@ -38,6 +40,7 @@ Archiving is reversible: move the file back from `_archive/` to its original dir
 
 ## Forbidden
 
-- Archiving `raw/` files (N9 — raw is immutable).
+- Archiving `raw/` files outside the N9 Reingest Protocol (raw is immutable except during content-drift reingestion).
+- Archiving raw files without updating all `^[raw/...]` citation markers that reference them.
 - Archiving without user confirmation.
 - Deleting files (archive moves, never deletes).

package/skills/wiki-audit/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: wiki-audit
 description: Verify per-page that every ^[raw/...] resolves and sources frontmatter matches the body.
 ---

package/skills/wiki-canvas/SKILL.md

@@ -0,0 +1,57 @@
+---
+version: 0.2.1
+name: wiki-canvas
+description: Generate an Obsidian Canvas visualization of the vault graph. Runs skillwiki graph build then skillwiki canvas generate.
+---
+
+# wiki-canvas
+
+## When This Skill Activates
+
+- User wants a visual map of their vault structure.
+- User asks to see how pages are connected.
+- After significant ingestion or restructuring, user wants an updated overview.
+- User mentions Obsidian Canvas or visual vault exploration.
+
+## Pre-orientation reads
+
+Standard four reads (SCHEMA, index, log, project context if applicable).
+
+## Steps
+
+0. Resolve vault: `skillwiki path`.
+1. Run `skillwiki graph build <vault>` to produce the adjacency graph at `<vault>/.skillwiki/graph.json`. If graph.json already exists and the vault has not changed, this step can be skipped — but regenerate after any ingestion, reingest, archive, or restructuring to keep the canvas current.
+2. Run `skillwiki canvas generate <vault>`. This reads graph.json and writes `<vault>/vault-graph.canvas`.
+3. Present the result to the user: node count, edge count, and the output path.
+4. Advise the user on opening the canvas:
+   - In Obsidian, open the vault folder and click `vault-graph.canvas` in the file explorer, or use the Quick Switcher (`Cmd/Ctrl+O`) and search for "vault-graph".
+   - Nodes are arranged in columns by type: **entities** (red), **concepts** (green), **comparisons** (orange), **queries** (cyan), **meta** (purple). Unclassified pages appear in yellow in the comparisons column.
+   - Edges represent wikilink connections. Click any node to jump to the source page; drag to rearrange.
+   - Zoom and pan with mouse/trackpad to explore large vaults.
+5. Append one `log.md` entry noting the canvas generation (node/edge counts).
+
+## When to regenerate
+
+Regenerate the canvas after any of these events:
+- One or more `wiki-ingest` runs that added new pages.
+- `wiki-reingest` or `wiki-archive` that changed or removed pages.
+- Manual restructuring of the vault directories.
+- After running `wiki-lint` and fixing structural issues.
+
+Stale canvases are not harmful, but they will not reflect new or removed pages until regenerated.
+
+## Future: Bases view
+
+Obsidian Bases (`.base` files) offer tabular data views of vault content. A Bases generation capability may be added in a future version to complement the graph canvas with filterable, sortable table layouts. For now, the canvas is the primary visualization.
+
+## Stop conditions
+
+- `skillwiki graph build` returns a non-zero exit code — investigate before continuing.
+- `graph.json` is missing or invalid — the canvas command will surface the error; direct the user to run `skillwiki graph build` first.
+- User cancels before generation.
+
+## Forbidden
+
+- Modifying `vault-graph.canvas` by hand after generation — regenerate it instead.
+- Regenating the canvas without first regenerating graph.json when the vault has changed.
+- Deleting the previous canvas without generating a replacement.

package/skills/wiki-crystallize/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: wiki-crystallize
 description: Distill the current working session into a typed-knowledge page with provenance.
 ---
@@ -32,3 +33,4 @@ Standard four reads. If cwd is inside `projects/{slug}/`, also read project READ
 ## Forbidden
 - Filing without explicit `provenance:`.
 - Updating `index.md` before `validate` passes.
+- 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.

package/skills/wiki-gate-plan-mode/SKILL.md

@@ -0,0 +1,80 @@
+---
+version: 0.2.1
+name: wiki-gate-plan-mode
+description: Toggle EnterPlanMode gating — force superpowers planning skills instead of built-in plan mode
+---
+
+# wiki-gate-plan-mode
+
+Gate the agent away from Claude Code's built-in `EnterPlanMode` tool, forcing
+all planning through `superpowers:brainstorming` → `superpowers:writing-plans`
+(or a configurable pipeline). Uses `permissions.deny` for two-layer enforcement:
+the tool is removed from the model's context before it ever sees it.
+
+## When This Skill Activates
+
+- User says "gate plan mode", "disable EnterPlanMode", "force superpowers planning"
+- User asks to toggle, check, or configure plan-mode gating
+- User wants to enforce structured planning workflows in a project
+
+## Pre-orientation reads
+
+None for the first run.
+
+## Steps
+
+0. **Parse arguments.** Accept one of:
+   - `on` — enable gating (add EnterPlanMode to deny)
+   - `off` — disable gating (remove EnterPlanMode from deny)
+   - `status` (default if no argument) — report current state
+
+1. **Locate settings file.** Check in this order:
+   - `~/.claude/settings.json` (user-level, global — primary target for plan-mode gating)
+   - `.claude/settings.json` (project-level, checked into repo — use if user specifies project scope)
+   If the target file does not exist, create it with `{ "permissions": { "deny": [] } }`.
+
+2. **Read current state.** Parse the settings JSON. Check whether `"EnterPlanMode"` is present in `permissions.deny[]`.
+
+3. **Apply the requested action:**
+
+   **`on`:**
+   - If `"EnterPlanMode"` is already in `permissions.deny`, report "already gated" and stop.
+   - Otherwise, add `"EnterPlanMode"` to `permissions.deny[]`. Create the array if absent.
+   - Write the updated JSON back, preserving formatting.
+   - Report: "EnterPlanMode gated — agent will use superpowers planning skills."
+
+   **`off`:**
+   - If `"EnterPlanMode"` is not in `permissions.deny`, report "already ungated" and stop.
+   - Otherwise, remove `"EnterPlanMode"` from `permissions.deny[]`. If the array is now empty, remove the `deny` key.
+   - Write the updated JSON back.
+   - Report: "EnterPlanMode ungated — built-in plan mode is available."
+
+   **`status`:**
+   - Check both `~/.claude/settings.json` and `.claude/settings.json`.
+   - Report whether EnterPlanMode is currently gated or ungated.
+   - If gated, list which settings file contains the deny entry.
+
+4. **Suggest CLAUDE.md directive (on action only).** After enabling gating, check whether the project's `CLAUDE.md` contains a planning directive (search for "EnterPlanMode" or "superpowers:brainstorming"). If not found, suggest adding:
+
+   ```
+   ## Planning
+
+   Use superpowers:brainstorming → superpowers:writing-plans for all planning. EnterPlanMode is disabled.
+   ```
+
+   Do NOT edit CLAUDE.md automatically — only suggest.
+
+## Schema Warning
+
+The JSON Schema Store's `claude-code-settings.json` schema has a closed regex for `permissions.deny` that includes `ExitPlanMode` but **omits `EnterPlanMode`**. IDEs (VS Code, JetBrains) will show a validation warning. This is a schema staleness issue, not a runtime issue — Claude Code's runtime accepts `EnterPlanMode` in `permissions.deny` and enforces it correctly. See `[[queries/claude-code-plan-mode-schema-validation]]` for full analysis.
+
+## Stop conditions
+
+- No project directory found (not inside a git repo or project).
+- Settings file exists but is not valid JSON and cannot be parsed.
+
+## Forbidden
+
+- Do not add any tool other than `EnterPlanMode` to the deny list.
+- Do not modify CLAUDE.md automatically — only suggest changes.
+- Do not remove other entries from `permissions.deny` when toggling off — only remove `EnterPlanMode`.

package/skills/wiki-ingest/SKILL.md

@@ -1,4 +1,5 @@
 ---
+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.
 ---
@@ -45,6 +46,7 @@ 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/`.
+- 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
 

package/skills/wiki-init/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 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.
 ---

package/skills/wiki-lint/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: wiki-lint
 description: Vault health check via the umbrella `skillwiki lint` subcommand. Read-only by default; rotation requires explicit user consent.
 ---

package/skills/wiki-query/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: wiki-query
 description: Search the vault and synthesize an answer with E2 4-signal ranking. Optional file to queries/ or comparisons/.
 ---

package/skills/wiki-reingest/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: wiki-reingest
 description: Detect and act on source drift. Runs skillwiki drift, reviews changes, archives old raw + ingests new content.
 ---

package/skills/wiki-sync/SKILL.md

@@ -0,0 +1,91 @@
+---
+version: 0.2.1
+name: wiki-sync
+description: Safely sync the vault git repository. Runs skillwiki sync status, then guides push or pull with lint guards and conflict resolution.
+---
+
+# wiki-sync
+
+## When This Skill Activates
+
+- User wants to push local vault changes to the remote.
+- User wants to pull remote changes into their local vault.
+- User asks about vault sync status, git state, or multi-device coordination.
+- Periodic maintenance before or after editing sessions.
+
+## Pre-orientation reads
+
+Standard four reads.
+
+## Steps
+
+0. Resolve vault: `skillwiki path` (record source for context).
+1. Run `skillwiki sync status <vault>`. Read the JSON output.
+   - Exit code 0: vault is clean (nothing to sync).
+   - Exit code 22: warnings — dirty/ahead/behind (needs action).
+2. Present the current state: `status`, `dirty`, `ahead`, `behind`, `last_commit`.
+3. Ask the user which operation they want: **push**, **pull**, or **both** (pull then push).
+
+### Push workflow
+
+4. If vault is dirty, ask the user to review uncommitted changes before proceeding.
+5. Run `skillwiki lint <vault>`. If errors exist, stop and report — do not push lint errors to remote.
+6. If lint passes (errors = 0), stage and commit:
+   - `git -C <vault> add -A`
+   - `git -C <vault> commit -m "sync: vault update $(date -u +%Y-%m-%dT%H:%MZ)"`
+7. Run `git -C <vault> push origin HEAD`. Report result.
+8. Append one `log.md` entry summarizing: files pushed, lint result, commit hash.
+
+### Pull workflow
+
+9. If vault is dirty, stash first: `git -C <vault> stash push -m "auto-stash before pull $(date -u +%Y-%m-%dT%H:%MZ)"`.
+10. Run `git -C <vault> pull --rebase origin HEAD`. Report result.
+11. If a stash was created, pop it: `git -C <vault> stash pop`.
+12. If conflicts occur during stash pop, identify them and present to the user for resolution (see Conflict Resolution below).
+13. Run `skillwiki lint <vault>` after pull to verify vault integrity.
+14. Append one `log.md` entry summarizing: commits pulled, lint result, any conflicts.
+
+### Pull-then-push workflow
+
+15. Execute the pull workflow (steps 9-13) first.
+16. Then execute the push workflow (steps 4-8).
+
+## Conflict Resolution
+
+When merge conflicts are detected:
+
+- **Frontmatter conflicts:**
+  - For `updated:` fields: always take the newer timestamp (compare both sides, keep the later one).
+  - For all other frontmatter fields: present both versions to the user and ask which to keep.
+- **Body conflicts:**
+  - Do not auto-resolve body conflicts.
+  - Mark unresolved regions with `???` on a line by itself between the conflicting versions, so the user can see both sides and decide.
+  - Example:
+    ```
+    Content from local version
+    ???
+    Content from remote version
+    ```
+- After resolving conflicts, run `skillwiki lint <vault>` to verify before committing.
+
+## Multi-device coordination
+
+When the user mentions editing from Obsidian desktop and Claude Code on a server (or any two-device setup):
+
+- Recommend pulling before every editing session on each device.
+- Recommend pushing after every editing session on each device.
+- If both devices edit the same page between syncs, conflicts are inevitable — the Conflict Resolution section handles this.
+- Suggest enabling auto-commit in Obsidian (Community Plugins: `obsidian-git`) to reduce dirty-state drift.
+
+## Stop conditions
+
+- `skillwiki sync status` reports `not_a_repo` — the vault is not a git repository. Advise the user to initialize one.
+- Lint errors are found before a push — do not push until resolved.
+- `git push` or `git pull` fails with a network error — report and stop.
+
+## Forbidden
+
+- Pushing when lint errors exist.
+- Auto-resolving body conflicts without user review.
+- Force-pushing (`git push --force`).
+- Modifying files in `raw/` to resolve conflicts (N9 — archive and re-ingest instead).