skillwiki 0.10.68 → 0.10.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.68",
+  "version": "0.10.69",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js",

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

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

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

@@ -1,7 +1,7 @@
 {
   "name": "skillwiki",
-  "version": "0.10.68",
-  "description": "Project-aware Karpathy-style knowledge base for Codex with 20 prompt-only skills backed by the deterministic skillwiki CLI.",
+  "version": "0.10.69",
+  "description": "Project-aware Karpathy-style knowledge base for Codex with 21 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",
     "url": "https://github.com/karlorz"
@@ -22,7 +22,7 @@
   "interface": {
     "displayName": "SkillWiki",
     "shortDescription": "Project-aware wiki skills for Codex agents",
-    "longDescription": "20 prompt-only skills (wiki-*, proj-*, using-skillwiki) for deterministic, project-aware knowledge workflows.",
+    "longDescription": "21 prompt-only skills (wiki-*, proj-*, using-skillwiki, skillwiki-mcp) for deterministic, project-aware knowledge workflows.",
     "developerName": "karlorz",
     "category": "Productivity",
     "capabilities": [

package/skills/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "skillwiki": {
+      "type": "http",
+      "url": "${SKILLWIKI_MCP_URL:-https://wiki.karldigi.dev/mcp}",
+      "headers": {
+        "Authorization": "Bearer ${SKILLWIKI_MCP_TOKEN}"
+      }
+    }
+  }
+}

package/skills/README.md

@@ -3,7 +3,7 @@
 Prompt-only Markdown skills for Claude Code. Installed via `skillwiki install`
 or the Claude/Codex/Antigravity plugin packaging paths.
 
-Current package inventory: **20 skills**.
+Current package inventory: **21 skills**.
 
 Publication policy: new or updated typed-knowledge and meta pages must use
 `skillwiki page publish` from a temporary draft, inspect its dry-run, and add
@@ -26,6 +26,7 @@ fixed papers/transcripts taxonomy.
 | `wiki-*` | `wiki-init`, `wiki-ingest`, `wiki-query`, `wiki-lint`, `wiki-crystallize`, `wiki-audit`, `wiki-archive`, `wiki-reingest`, `wiki-adapter-prd`, `wiki-add-task`, `wiki-sync`, `wiki-canvas`, `wiki-gate-plan-mode` |
 | `proj-*` | `proj-init`, `proj-work`, `proj-distill`, `proj-decide` |
 | onboarding | `using-skillwiki` |
+| mcp | `skillwiki-mcp` |
 
 Verify the live inventory from source:
 

package/skills/cursor-cli-mcp.example.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "skillwiki": {
+      "type": "http",
+      "url": "https://wiki.karldigi.dev/mcp",
+      "headers": {
+        "Authorization": "Bearer ${env:SKILLWIKI_MCP_TOKEN}"
+      }
+    }
+  }
+}

package/skills/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "skillwiki": {
+      "type": "http",
+      "url": "${SKILLWIKI_MCP_URL:-https://wiki.karldigi.dev/mcp}",
+      "headers": {
+        "Authorization": "Bearer ${SKILLWIKI_MCP_TOKEN}"
+      }
+    }
+  }
+}

package/skills/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.10.68",
+  "version": "0.10.69",
   "private": true,
   "files": [
     "wiki-*",
     "proj-*",
     "using-skillwiki",
+    "skillwiki-mcp",
     "skills",
     "agents",
+    "scripts",
+    "mcp.json",
+    ".mcp.json",
+    "cursor-cli-mcp.example.json",
     ".claude-plugin",
     ".codex-plugin",
     "hooks",

package/skills/scripts/check_readiness.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""SkillWiki HTTP MCP plugin readiness probe.
+
+Interface: probe(environ) -> {status, reasons, url, migrated, warnings}.
+Does not write ~/.cursor/mcp.json, config.toml, or mcp.env.
+Never prints SKILLWIKI_MCP_TOKEN.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Mapping
+
+PRODUCTION_MCP_URL = "https://wiki.karldigi.dev/mcp"
+TOKEN_ENV = "SKILLWIKI_MCP_TOKEN"
+URL_ENV = "SKILLWIKI_MCP_URL"
+
+
+def _strip(value: str | None) -> str:
+    return (value or "").strip()
+
+
+def probe(environ: Mapping[str, str] | None = None) -> dict:
+    source = os.environ if environ is None else environ
+    token = _strip(source.get(TOKEN_ENV))
+    url = _strip(source.get(URL_ENV))
+    warnings: list[str] = []
+    reasons: list[str] = []
+
+    if not token:
+        return {
+            "status": "missing_prereq",
+            "reasons": [f"{TOKEN_ENV} unset"],
+            "url": url or None,
+            "migrated": False,
+            "warnings": warnings,
+        }
+
+    migrated = False
+    if not url:
+        url = PRODUCTION_MCP_URL
+        migrated = True
+        reasons.append(f"{URL_ENV} empty; using {PRODUCTION_MCP_URL}")
+
+    return {
+        "status": "in_sync",
+        "reasons": reasons,
+        "url": url,
+        "migrated": migrated,
+        "warnings": warnings,
+    }
+
+
+def apply(environ: dict[str, str] | None = None) -> dict:
+    """Apply the URL default to this process and Claude's env handoff only."""
+    target = os.environ if environ is None else environ
+    result = probe(target)
+    if result["status"] != "in_sync" or not result.get("migrated"):
+        return result
+    url = result["url"]
+    target[URL_ENV] = url
+    env_file = _strip(target.get("CLAUDE_ENV_FILE"))
+    if env_file:
+        with open(env_file, "a", encoding="utf-8") as handle:
+            handle.write(f"export {URL_ENV}={url}\n")
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="skillwiki HTTP MCP readiness probe")
+    parser.add_argument("--json", action="store_true", help="print JSON verdict")
+    parser.add_argument(
+        "--apply",
+        action="store_true",
+        help="set SKILLWIKI_MCP_URL in this child process and Claude's CLAUDE_ENV_FILE when TOKEN is set",
+    )
+    args = parser.parse_args(argv)
+    result = apply() if args.apply else probe()
+    print(json.dumps(result, separators=(",", ":")))
+    return 0 if result["status"] == "in_sync" else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,36 @@
+---
+name: skillwiki-mcp
+description: Use when capturing a note, idea, or bug into the wiki, appending log.md, or using wiki MCP tools. Writes via wiki_capture / wiki_log_append; never local raw/transcripts.
+---
+
+# SkillWiki HTTP MCP
+
+Use this skill to capture a note, idea, bug, or task into the wiki, append `log.md`, or call SkillWiki HTTP MCP tools.
+
+SkillWiki captures are HTTP MCP only (`type: http`). Claude/Grok use `SKILLWIKI_MCP_URL` as an optional override and otherwise default to `https://wiki.karldigi.dev/mcp`. Every host requires an operator-provided bearer as `SKILLWIKI_MCP_TOKEN` before MCP load. Do not start a local stdio `skillwiki mcp` / `skillwiki-mcp` server for captures.
+
+## First-run readiness
+
+- Resolve the installed plugin root from `GROK_PLUGIN_ROOT`, falling back to `CLAUDE_PLUGIN_ROOT`, and run `python3 "$PLUGIN_ROOT/scripts/check_readiness.py" --apply --json` before the first SkillWiki MCP call.
+- `missing_prereq` means `SKILLWIKI_MCP_TOKEN` is absent from process environment; stop and ask for a bearer. Do not invent a stdio MCP.
+- `in_sync` means the probe has a usable URL/token decision.
+- A 401 is an MCP handshake failure, not a readiness-probe status. Report that the token is missing or rejected and stop.
+- Grok SessionStart cannot inject the parent MCP environment. A restart cannot supply a missing token.
+- Never auto-source `mcp.env` or auto-write `~/.cursor/mcp.json`, Grok `config.toml`, or `mcp.env`.
+- Never print the bearer token.
+
+## Writes (captures-only)
+
+On leaf hosts, wiki captures go through MCP. Do **not** write `raw/transcripts/` or `log.md` as local files.
+
+1. Call MCP `wiki_capture` with `kind` (`task` | `idea` | `bug` | `note`), `project`, `title`, and `content`. Optional `agent_note`.
+2. Call MCP `wiki_log_append` when a structural `log.md` line is needed. Pass append-only `content`. Do not rewrite log history.
+3. Write surface is captures-only. Do not call unpublished Tier 2 tools. Do not `git commit` / `wiki-push` against `~/wiki` for these captures.
+
+## Reads
+
+Local `~/wiki` (or `skillwiki path`) is fine for reads. MCP read tools are optional. Prefer ordinary file reads of the local mirror.
+
+## Errors
+
+Report handshake, capture, and append failures literally. If tools are missing after a 401 or `missing_prereq`, stop and tell the operator to export `SKILLWIKI_MCP_TOKEN`, run `grok plugin update skillwiki`, and start a new session. Do not fall back to local `raw/transcripts/` writes.

package/skills/skillwiki-mcp/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: skillwiki-mcp
+description: Use when capturing a note, idea, or bug into the wiki, appending log.md, or using wiki MCP tools. Writes via wiki_capture / wiki_log_append; never local raw/transcripts.
+---
+
+# SkillWiki HTTP MCP
+
+Use this skill to capture a note, idea, bug, or task into the wiki, append `log.md`, or call SkillWiki HTTP MCP tools.
+
+SkillWiki captures are HTTP MCP only (`type: http`). Claude/Grok use `SKILLWIKI_MCP_URL` as an optional override and otherwise default to `https://wiki.karldigi.dev/mcp`. Every host requires an operator-provided bearer as `SKILLWIKI_MCP_TOKEN` before MCP load. Do not start a local stdio `skillwiki mcp` / `skillwiki-mcp` server for captures.
+
+## First-run readiness
+
+- Resolve the installed plugin root from `GROK_PLUGIN_ROOT`, falling back to `CLAUDE_PLUGIN_ROOT`, and run `python3 "$PLUGIN_ROOT/scripts/check_readiness.py" --apply --json` before the first SkillWiki MCP call.
+- `missing_prereq` means `SKILLWIKI_MCP_TOKEN` is absent from process environment; stop and ask for a bearer. Do not invent a stdio MCP.
+- `in_sync` means the probe has a usable URL/token decision.
+- A 401 is an MCP handshake failure, not a readiness-probe status. Report that the token is missing or rejected and stop.
+- Grok SessionStart cannot inject the parent MCP environment. A restart cannot supply a missing token.
+- Never auto-source `mcp.env` or auto-write `~/.cursor/mcp.json`, Grok `config.toml`, or `mcp.env`.
+- Never print the bearer token.
+
+## Writes (captures-only)
+
+On leaf hosts, wiki captures go through MCP. Do **not** write `raw/transcripts/` or `log.md` as local files.
+
+1. Call MCP `wiki_capture` with `kind` (`task` | `idea` | `bug` | `note`), `project`, `title`, and `content`. Optional `agent_note`.
+2. Call MCP `wiki_log_append` when a structural `log.md` line is needed. Pass append-only `content`. Do not rewrite log history.
+3. Write surface is captures-only. Do not call unpublished Tier 2 tools. Do not `git commit` / `wiki-push` against `~/wiki` for these captures.
+
+## Reads
+
+Local `~/wiki` (or `skillwiki path`) is fine for reads. MCP read tools are optional. Prefer ordinary file reads of the local mirror.
+
+## Errors
+
+Report handshake, capture, and append failures literally. If tools are missing after a 401 or `missing_prereq`, stop and tell the operator to export `SKILLWIKI_MCP_TOKEN`, run `grok plugin update skillwiki`, and start a new session. Do not fall back to local `raw/transcripts/` writes.