skillwiki 0.8.1-beta.9 → 0.8.2

package/dist/cli.js

@@ -2843,12 +2843,13 @@ async function runRawBodyDedup(vault) {
 // src/commands/path-too-long.ts
 import { existsSync as existsSync4 } from "fs";
 import { mkdir as mkdir8, readFile as readFile16, rename as rename6, unlink as unlink3 } from "fs/promises";
-import { dirname as dirname8, join as join21, posix } from "path";
+import { dirname as dirname8, join as join21, posix, resolve as resolve4 } from "path";
 var MAX_PATH_LENGTH = 240;
+var WINDOWS_ABSOLUTE_PATH_LIMIT = 259;
 async function runPathTooLong(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
-  const violations = findPathTooLongViolations(scan.data.allMarkdown);
+  const violations = findPathTooLongViolations(scan.data.allMarkdown, MAX_PATH_LENGTH);
   if (violations.length > 0) {
     return {
       exitCode: ExitCode.LINT_HAS_ERRORS,
@@ -2863,12 +2864,13 @@ async function runPathTooLong(input) {
 async function fixPathTooLong(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
-  const violations = findPathTooLongViolations(scan.data.allMarkdown);
+  const maxFixLength = maxFixPathLength(input.vault);
+  const violations = findPathTooLongViolations(scan.data.allMarkdown, maxFixLength);
   const fixed = [];
   const unresolved = [];
   for (const violation of violations) {
-    const target = await resolveFixTarget(input.vault, violation.relPath, violation.suggestedRelPath);
-    if (!target || target.relPath === violation.relPath || target.relPath.length > MAX_PATH_LENGTH) {
+    const target = await resolveFixTarget(input.vault, violation.relPath, violation.suggestedRelPath, maxFixLength);
+    if (!target || target.relPath === violation.relPath || target.relPath.length > maxFixLength) {
       unresolved.push(violation.relPath);
       continue;
     }
@@ -2919,13 +2921,20 @@ async function fixPathTooLong(input) {
     result: ok({ fixed, unresolved, rewired, humanHint: hintLines.join("\n") })
   };
 }
-function findPathTooLongViolations(pages) {
-  return pages.filter((page) => page.relPath.length > MAX_PATH_LENGTH).map((page) => ({
+function findPathTooLongViolations(pages, maxLength) {
+  return pages.filter((page) => page.relPath.length > maxLength).map((page) => ({
     relPath: page.relPath,
     length: page.relPath.length,
-    suggestedRelPath: truncateFilename(page.relPath)
+    suggestedRelPath: truncateFilename(page.relPath, maxLength)
   }));
 }
+function maxFixPathLength(vault) {
+  if (process.platform !== "win32") return MAX_PATH_LENGTH;
+  const root = resolve4(vault);
+  const separatorBudget = root.endsWith("\\") || root.endsWith("/") ? 0 : 1;
+  const absoluteSafeRelLength = WINDOWS_ABSOLUTE_PATH_LIMIT - root.length - separatorBudget;
+  return Math.max(1, Math.min(MAX_PATH_LENGTH, absoluteSafeRelLength));
+}
 function truncateFilename(relPath, maxLength = MAX_PATH_LENGTH) {
   if (relPath.length <= maxLength) return relPath;
   const lastSlash = relPath.lastIndexOf("/");
@@ -2944,9 +2953,9 @@ function truncateFilename(relPath, maxLength = MAX_PATH_LENGTH) {
   const prefix = base.slice(0, maxPrefixLen).replace(/[-_\s]+$/, "");
   return dirPrefix + prefix + suffix;
 }
-async function resolveFixTarget(vault, original, preferred) {
-  for (const candidate of candidateRelPaths(preferred)) {
-    if (candidate === original || candidate.length > MAX_PATH_LENGTH) continue;
+async function resolveFixTarget(vault, original, preferred, maxLength) {
+  for (const candidate of candidateRelPaths(preferred, maxLength)) {
+    if (candidate === original || candidate.length > maxLength) continue;
     const candidatePath = join21(vault, candidate);
     if (!existsSync4(candidatePath)) return { relPath: candidate, mode: "rename" };
     if (await hasSameContent(join21(vault, original), candidatePath)) {
@@ -2955,9 +2964,9 @@ async function resolveFixTarget(vault, original, preferred) {
   }
   return null;
 }
-function candidateRelPaths(preferred) {
+function candidateRelPaths(preferred, maxLength) {
   const candidates = [preferred];
-  if (preferred.length > MAX_PATH_LENGTH) return candidates;
+  if (preferred.length > maxLength) return candidates;
   const dir = posix.dirname(preferred) === "." ? "" : posix.dirname(preferred);
   const filename = posix.basename(preferred);
   const ext = filename.endsWith(".md") ? ".md" : "";
@@ -2965,7 +2974,7 @@ function candidateRelPaths(preferred) {
   const dirPrefix = dir ? `${dir}/` : "";
   for (let i = 2; i < 100; i++) {
     const suffix = `-${i}${ext}`;
-    const prefixBudget = MAX_PATH_LENGTH - dirPrefix.length - suffix.length;
+    const prefixBudget = maxLength - dirPrefix.length - suffix.length;
     if (prefixBudget <= 0) break;
     candidates.push(`${dirPrefix}${base.slice(0, prefixBudget).replace(/[-_\s]+$/, "")}${suffix}`);
   }
@@ -3912,7 +3921,7 @@ async function runConfigPath(input) {
 
 // src/commands/doctor.ts
 import { existsSync as existsSync9, lstatSync, readlinkSync, readdirSync, statSync as statSync3, readFileSync as readFileSync7 } from "fs";
-import { join as join27, resolve as resolve4 } from "path";
+import { join as join27, resolve as resolve5 } from "path";
 import { execSync as execSync2 } from "child_process";
 import { platform as platform2 } from "os";
 
@@ -4245,14 +4254,14 @@ function checkNodeVersion() {
 function detectCliChannels(argv, home) {
   const channels = [];
   if (argv.length >= 2 && argv[1].endsWith("cli.js")) {
-    const devPath = resolve4(argv[1]);
+    const devPath = resolve5(argv[1]);
     channels.push({ name: "dev", path: devPath, isDevLink: true });
   }
   try {
     const whichOut = execSync2("which skillwiki 2>/dev/null", { encoding: "utf8" }).trim();
     if (whichOut) {
       const isDev = isDevSymlink(whichOut);
-      if (!channels.some((c) => c.path === resolve4(whichOut))) {
+      if (!channels.some((c) => c.path === resolve5(whichOut))) {
         channels.push({ name: "npm", path: whichOut, isDevLink: isDev });
       }
     }
@@ -4275,7 +4284,7 @@ function isDevSymlink(binPath) {
   try {
     const st = lstatSync(binPath);
     if (st.isSymbolicLink()) {
-      const target = resolve4(binPath, "..", readlinkSync(binPath));
+      const target = resolve5(binPath, "..", readlinkSync(binPath));
       return target.includes("packages/cli") || target.includes("packages\\cli");
     }
   } catch {
@@ -7118,6 +7127,7 @@ function runSyncStatus(input) {
       })
     };
   }
+  enableGitLongPathsOnWindows(vault);
   const porcelain = git(vault, ["status", "--porcelain"]);
   const dirty = porcelain ? porcelain.split("\n").filter((l) => l.trim().length > 0).length : 0;
   const revOutput = git(vault, ["rev-list", "--left-right", "--count", "origin/HEAD...HEAD"]);
@@ -7187,6 +7197,7 @@ async function runSyncPush(input) {
       result: err("NOT_A_GIT_REPO", { path: vault })
     };
   }
+  enableGitLongPathsOnWindows(vault);
   let pathFixes = 0;
   const pathFix = await fixPathTooLong({ vault });
   if (pathFix.result.ok && pathFix.result.data.fixed.length > 0) {
@@ -7297,6 +7308,10 @@ function enumerateStashes(vault) {
   }
   return stashes;
 }
+function enableGitLongPathsOnWindows(vault) {
+  if (process.platform !== "win32") return;
+  git(vault, ["config", "core.longpaths", "true"]);
+}
 async function runSyncPull(input) {
   const vault = input.vault;
   if (!existsSync14(join37(vault, ".git"))) {
@@ -7305,6 +7320,7 @@ async function runSyncPull(input) {
       result: err("NOT_A_GIT_REPO", { path: vault })
     };
   }
+  enableGitLongPathsOnWindows(vault);
   let fetched = false;
   try {
     gitStrict(vault, ["fetch", "origin"]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.1-beta.9",
+  "version": "0.8.2",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.1-beta.9",
+  "version": "0.8.2",
   "skills": "./",
   "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": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.1-beta.9",
+  "version": "0.8.2",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 18 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",
@@ -18,6 +18,7 @@
     "karpathy"
   ],
   "skills": "./skills/",
+  "hooks": "./hooks/hooks-codex.json",
   "interface": {
     "displayName": "SkillWiki",
     "shortDescription": "Project-aware wiki skills for Codex agents",

package/skills/README.md

@@ -10,3 +10,13 @@ Prompt-only Markdown skills for Claude Code. Installed via `skillwiki install`.
 Each top-level skill subdirectory holds one canonical `SKILL.md`. The nested
 `skills/<skill>/SKILL.md` tree mirrors those files for Codex plugin discovery;
 keep it byte-for-byte in sync with the canonical top-level files.
+
+Codex installs through `packages/codex-skills`, a materialized plugin root that
+copies this package's `.codex-plugin/` manifest, `skills/` mirror, and
+Codex-specific hook files. That root exposes `hooks/hooks-codex.json` and
+`hooks/session-start-codex` without exposing the Claude default
+`hooks/hooks.json`.
+
+Run `npm run materialize:plugins` from the repository root after changing
+canonical skill, agent, or hook assets. Run
+`npm run materialize:plugins:check` for read-only drift detection.

package/skills/hooks/hooks-codex.json

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

package/skills/hooks/session-context

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# Shared SessionStart context helpers for skillwiki hook entrypoints.
+
+read_config_value() {
+    local file="$1"
+    local key="$2"
+    local line
+
+    line=$(grep -E "^[[:space:]]*${key}:" "$file" 2>/dev/null | head -n 1 || true)
+    [[ -n "$line" ]] || return 0
+
+    printf '%s' "$line" \
+        | sed -E "s/^[[:space:]]*${key}:[[:space:]]*//; s/[[:space:]]+#.*$//; s/[[:space:]]+$//; s/^['\"]//; s/['\"]$//"
+}
+
+find_dev_loop_config() {
+    local dir="${PWD}"
+
+    while [[ -n "$dir" && "$dir" != "/" ]]; do
+        if [[ -f "${dir}/.claude/dev-loop.config.md" ]]; then
+            printf '%s' "${dir}/.claude/dev-loop.config.md"
+            return 0
+        fi
+        dir=$(dirname "$dir")
+    done
+
+    return 0
+}
+
+build_project_prd_context() {
+    local config_path
+    config_path=$(find_dev_loop_config)
+    [[ -n "$config_path" ]] || return 0
+
+    local prd_layer
+    local prd_pipeline
+    prd_layer=$(read_config_value "$config_path" "prd_layer")
+    prd_pipeline=$(read_config_value "$config_path" "prd_pipeline")
+
+    [[ -n "$prd_layer" || -n "$prd_pipeline" ]] || return 0
+
+    prd_layer="${prd_layer:-unspecified}"
+    prd_pipeline="${prd_pipeline:-unspecified}"
+
+    cat <<EOF
+## Project PRD Mode
+
+Detected \`.claude/dev-loop.config.md\` for this workspace:
+- \`prd_layer\`: \`${prd_layer}\`
+- \`prd_pipeline\`: \`${prd_pipeline}\`
+
+Use this detected PRD mode as the source of truth. Route generated spec/plan artifacts through \`proj-work\`, and do not write them under \`docs/superpowers/\`. If \`prd_layer\` is \`superpowers\` or \`tdd\`, ensure \`EnterPlanMode\` is gated with \`wiki-gate-plan-mode\`. Do not assume \`superpowers/full\` unless the config says so.
+EOF
+}
+
+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"
+}
+
+read_skill_content() {
+    local skill_path="$1"
+    cat "$skill_path" 2>/dev/null || echo "Error reading using-skillwiki skill"
+}
+
+resolve_skill_path() {
+    local plugin_root="$1"
+    local skill_name="$2"
+    local candidate
+
+    for candidate in \
+        "${plugin_root}/${skill_name}/SKILL.md" \
+        "${plugin_root}/skills/${skill_name}/SKILL.md"; do
+        if [[ -f "$candidate" ]]; then
+            printf '%s' "$candidate"
+            return 0
+        fi
+    done
+
+    printf '%s' "${plugin_root}/${skill_name}/SKILL.md"
+}
+
+build_skillwiki_session_context() {
+    local skill_content="$1"
+    local project_prd_context
+    local session_context
+
+    project_prd_context=$(build_project_prd_context)
+
+    session_context=$'### Skillwiki Activation\n\nSkillwiki is active for this workspace. Below are the capability guidelines for local reference:'
+    if [[ -n "$project_prd_context" ]]; then
+        session_context+=$'\n\n'
+        session_context+="$project_prd_context"
+    fi
+    session_context+=$'\n\n'
+    session_context+="$skill_content"
+
+    printf '%s' "$session_context"
+}
+
+print_session_start_json() {
+    local session_context
+    session_context=$(escape_for_json "$1")
+
+    # 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"
+}

package/skills/hooks/session-start

@@ -1,29 +1,15 @@
 #!/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)}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "${SCRIPT_DIR}/.." && pwd)}"
 
-skill_content=$(cat "${PLUGIN_ROOT}/using-skillwiki/SKILL.md" 2>/dev/null || echo "Error reading using-skillwiki skill")
+source "${SCRIPT_DIR}/session-context"
 
-# 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="### Skillwiki Activation\n\nSkillwiki is active for this workspace. Below are the capability guidelines for local reference:\n\n${skill_escaped}"
-
-# 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"
+skill_content=$(read_skill_content "$(resolve_skill_path "$PLUGIN_ROOT" "using-skillwiki")")
+session_context=$(build_skillwiki_session_context "$skill_content")
+print_session_start_json "$session_context"
 
 exit 0

package/skills/hooks/session-start-codex

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Codex SessionStart hook for skillwiki plugin.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="${PLUGIN_ROOT:-$(cd "${SCRIPT_DIR}/.." && pwd)}"
+
+source "${SCRIPT_DIR}/session-context"
+
+skill_content=$(read_skill_content "$(resolve_skill_path "$PLUGIN_ROOT" "using-skillwiki")")
+session_context=$(build_skillwiki_session_context "$skill_content")
+print_session_start_json "$session_context"
+
+exit 0

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.8.1-beta.9",
+  "version": "0.8.2",
   "private": true,
   "files": [
     "wiki-*",

package/skills/proj-decide/SKILL.md

@@ -1,5 +1,4 @@
 ---
-version: 0.2.1
 name: proj-decide
 description: Write an Architectural Decision Record (ADR). If the decision generalizes, also create a concepts/ page.
 ---

package/skills/proj-distill/SKILL.md

@@ -1,5 +1,4 @@
 ---
-version: 0.2.1
 name: proj-distill
 description: 2-step distillation (E4) — analyze project compound entry, then generate a vault concept page with provenance.
 ---

package/skills/proj-init/SKILL.md

@@ -1,5 +1,4 @@
 ---
-version: 0.2.1
 name: proj-init
 description: Bootstrap a project workspace at projects/{slug}/ with README, requirements/, architecture/, work/, compound/.
 ---

package/skills/proj-work/SKILL.md

@@ -1,5 +1,4 @@
 ---
-version: 0.2.2
 name: proj-work
 description: Open or run a work item under projects/{slug}/work/YYYY-MM-DD-{slug}/. Redirects brainstorming/writing-plans output paths.
 ---

package/skills/skills/proj-decide/SKILL.md

@@ -1,5 +1,4 @@
 ---
-version: 0.2.1
 name: proj-decide
 description: Write an Architectural Decision Record (ADR). If the decision generalizes, also create a concepts/ page.
 ---

package/skills/skills/proj-distill/SKILL.md

@@ -1,5 +1,4 @@
 ---
-version: 0.2.1
 name: proj-distill
 description: 2-step distillation (E4) — analyze project compound entry, then generate a vault concept page with provenance.
 ---

package/skills/skills/proj-init/SKILL.md

@@ -1,5 +1,4 @@
 ---
-version: 0.2.1
 name: proj-init
 description: Bootstrap a project workspace at projects/{slug}/ with README, requirements/, architecture/, work/, compound/.
 ---

package/skills/skills/proj-work/SKILL.md

@@ -1,5 +1,4 @@
 ---
-version: 0.2.2
 name: proj-work
 description: Open or run a work item under projects/{slug}/work/YYYY-MM-DD-{slug}/. Redirects brainstorming/writing-plans output paths.
 ---

package/skills/skills/using-skillwiki/SKILL.md

@@ -1,5 +1,4 @@
 ---
-version: 0.2.2
 name: using-skillwiki
 description: Invoke at session start or when knowledge-base tasks arise — maps skillwiki skills, dev-loop alignment, and PRD/TDD routing with plan-mode gate checks
 ---
@@ -122,16 +121,17 @@ For longer-running project work, use `proj-init` → `proj-work` → `proj-disti
 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:
+skillwiki has multiple 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.
+| Codex plugin | `~/.codex/plugins/cache/llm-wiki/` | `codex plugin marketplace upgrade llm-wiki`, then reinstall or restart Codex as needed |
+| Local git dev | source repo checkout | `npm link ./packages/cli` (from repo root) |
+**Check versions:** `skillwiki doctor` reports Plugin/CLI version mismatch warnings when installed channels disagree.
+**Authoring rule:** `SKILL.md` frontmatter follows the Agent Skills schema: top-level `name` and `description` plus optional schema fields such as `metadata`. Do not put release version fields at the top level of `SKILL.md`; plugin and package release versions live in `plugin.json` and `package.json`.
+**Fix:** If developing locally, use the repo source plus `npm link`. If using released versions, update the relevant plugin or npm channel; do not infer release freshness from `SKILL.md` frontmatter.
 
 ## 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.

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

@@ -1,5 +1,4 @@
 ---
-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/skills/wiki-add-task/SKILL.md

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

package/skills/skills/wiki-archive/SKILL.md

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

package/skills/skills/wiki-audit/SKILL.md

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

package/skills/skills/wiki-canvas/SKILL.md

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

package/skills/skills/wiki-crystallize/SKILL.md

@@ -1,5 +1,4 @@
 ---
-version: 0.2.1
 name: wiki-crystallize
 description: Distill the current working session into a typed-knowledge page with provenance.
 ---

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

@@ -1,5 +1,4 @@
 ---
-version: 0.2.1
 name: wiki-gate-plan-mode
 description: Toggle EnterPlanMode gating — force superpowers planning skills instead of built-in plan mode
 ---

package/skills/skills/wiki-ingest/SKILL.md

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

package/skills/skills/wiki-init/SKILL.md

@@ -1,5 +1,4 @@
 ---
-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/skills/wiki-lint/SKILL.md

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

package/skills/skills/wiki-query/SKILL.md

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

package/skills/skills/wiki-reingest/SKILL.md

@@ -1,5 +1,4 @@
 ---
-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/skills/wiki-sync/SKILL.md

@@ -1,5 +1,4 @@
 ---
-version: 0.6.1
 name: wiki-sync
 description: Safely sync the vault git repository — multi-session safe via advisory lockfile. Handles rebase conflict storms from archive-commit × snapshot-stream patterns. Runs skillwiki sync status, then guides push or pull with lint guards and conflict resolution.
 ---

package/skills/using-skillwiki/SKILL.md

@@ -1,5 +1,4 @@
 ---
-version: 0.2.2
 name: using-skillwiki
 description: Invoke at session start or when knowledge-base tasks arise — maps skillwiki skills, dev-loop alignment, and PRD/TDD routing with plan-mode gate checks
 ---
@@ -122,16 +121,17 @@ For longer-running project work, use `proj-init` → `proj-work` → `proj-disti
 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:
+skillwiki has multiple 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.
+| Codex plugin | `~/.codex/plugins/cache/llm-wiki/` | `codex plugin marketplace upgrade llm-wiki`, then reinstall or restart Codex as needed |
+| Local git dev | source repo checkout | `npm link ./packages/cli` (from repo root) |
+**Check versions:** `skillwiki doctor` reports Plugin/CLI version mismatch warnings when installed channels disagree.
+**Authoring rule:** `SKILL.md` frontmatter follows the Agent Skills schema: top-level `name` and `description` plus optional schema fields such as `metadata`. Do not put release version fields at the top level of `SKILL.md`; plugin and package release versions live in `plugin.json` and `package.json`.
+**Fix:** If developing locally, use the repo source plus `npm link`. If using released versions, update the relevant plugin or npm channel; do not infer release freshness from `SKILL.md` frontmatter.
 
 ## 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.

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

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

package/skills/wiki-archive/SKILL.md

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

package/skills/wiki-audit/SKILL.md

@@ -1,5 +1,4 @@
 ---
-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

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

package/skills/wiki-crystallize/SKILL.md

@@ -1,5 +1,4 @@
 ---
-version: 0.2.1
 name: wiki-crystallize
 description: Distill the current working session into a typed-knowledge page with provenance.
 ---

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

@@ -1,5 +1,4 @@
 ---
-version: 0.2.1
 name: wiki-gate-plan-mode
 description: Toggle EnterPlanMode gating — force superpowers planning skills instead of built-in plan mode
 ---

package/skills/wiki-ingest/SKILL.md

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

package/skills/wiki-init/SKILL.md

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

package/skills/wiki-query/SKILL.md

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

package/skills/wiki-reingest/SKILL.md

@@ -1,5 +1,4 @@
 ---
-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

@@ -1,5 +1,4 @@
 ---
-version: 0.6.1
 name: wiki-sync
 description: Safely sync the vault git repository — multi-session safe via advisory lockfile. Handles rebase conflict storms from archive-commit × snapshot-stream patterns. Runs skillwiki sync status, then guides push or pull with lint guards and conflict resolution.
 ---