skillwiki 0.10.67 → 0.10.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.67",
+  "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.67",
+  "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.67",
-  "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.67",
+  "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/skills/using-skillwiki/SKILL.md

@@ -76,7 +76,7 @@ raw/
 ├── archived/{articles,papers,transcripts}/
 └── duplicates/{articles,papers,transcripts}/
 ```
-Use explicit vault-root asset embeds such as `![[raw/assets/example/diagram.png]]`. Agents may choose flat or URL-friendly nested paths. Once an immutable capture references an asset, that path freezes; routine source archive/dedup never moves the asset. Remote images remain external dependencies unless separately captured.
+Use explicit vault-root asset embeds such as `![[raw/assets/example/diagram.png]]`. Agents may choose flat or URL-friendly nested paths. Once an immutable capture references an asset, that path freezes; routine source archive/dedup never moves the asset. Remote images remain external dependencies unless separately captured. When storing binaries under `raw/assets/`, also write a sibling Markdown note (`listings.md`, `note.md`, or a dated `.md`) that embeds each file. Never use `.txt` as the only index; Obsidian opens Markdown notes.
 Raw frontmatter:
 ```yaml
 ---

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

@@ -10,7 +10,7 @@ Capture ad-hoc ideas, bugs, tasks, and notes into the vault. Three entry points
 | Filesystem drop | Hermes Agent compact mode (no slash commands available) | Same as above — create `.md` in `raw/transcripts/`, dev-loop discovers it |
 | Filesystem drop | You're NOT in a Claude session (Obsidian, editor, sync) | Create a new `.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.
+**Path Rule:** Captures ALWAYS go to `$(skillwiki path)/raw/transcripts/` (Layer 1). Never under `projects/{slug}/raw/` — that violates SCHEMA.md Layer 1 immutability. Text captures stay in `raw/transcripts/`. If the capture includes images or other binaries, store those files under `raw/assets/` with a sibling Markdown note that embeds them; never use a .txt sidecar (such as `README.txt`) as the only index; Obsidian opens Markdown notes.
 ### 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 |
@@ -92,6 +92,7 @@ Ad-hoc captures may omit `sha256`; omission does not grant mutation authority. O
 - 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).
 - Writing live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets to the vault.
+- Indexing `raw/assets/` binaries with only a `.txt` sidecar.
 ## 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`)

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

@@ -65,6 +65,7 @@ Raw ephemeral data (market feeds, logs, transient JSON) must be written to the *
 - Writing raw ephemeral data directly to cloud-mounted wiki paths (`~/wiki/`).
 - Writing host-local absolute paths as canonical durable source references (see `using-skillwiki` → Portable Source References).
 - 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.
+- Indexing `raw/assets/` binaries with only a `.txt` sidecar. Write a sibling Markdown note that embeds each file with `![[ ]]`.
 ## 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–8 for each source individually, using one `skillwiki ingest` command per source.

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

@@ -37,7 +37,9 @@ None for the first run.
    images remain external dependencies. An attended local-asset capture may
    choose any URL-friendly path under `raw/assets/`, but it must write the asset,
    emit an explicit vault-qualified `![[raw/assets/...]]` embed, verify
-   resolution/preview, and only then finalize the immutable raw note.
+   resolution/preview, and only then finalize the immutable raw note. Also write
+   a sibling Markdown note (`listings.md`, `note.md`, or a dated `.md`) that
+   embeds each file. Never use `.txt` as the only index.
 8. **Suggest first sources.** Propose 3–5 initial sources (URLs, papers, articles) appropriate to the domain. Prompt the user to provide the first one to ingest, then hand off to wiki-ingest.
 
 ## Stop conditions

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.

package/skills/using-skillwiki/SKILL.md

@@ -76,7 +76,7 @@ raw/
 ├── archived/{articles,papers,transcripts}/
 └── duplicates/{articles,papers,transcripts}/
 ```
-Use explicit vault-root asset embeds such as `![[raw/assets/example/diagram.png]]`. Agents may choose flat or URL-friendly nested paths. Once an immutable capture references an asset, that path freezes; routine source archive/dedup never moves the asset. Remote images remain external dependencies unless separately captured.
+Use explicit vault-root asset embeds such as `![[raw/assets/example/diagram.png]]`. Agents may choose flat or URL-friendly nested paths. Once an immutable capture references an asset, that path freezes; routine source archive/dedup never moves the asset. Remote images remain external dependencies unless separately captured. When storing binaries under `raw/assets/`, also write a sibling Markdown note (`listings.md`, `note.md`, or a dated `.md`) that embeds each file. Never use `.txt` as the only index; Obsidian opens Markdown notes.
 Raw frontmatter:
 ```yaml
 ---

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

@@ -10,7 +10,7 @@ Capture ad-hoc ideas, bugs, tasks, and notes into the vault. Three entry points
 | Filesystem drop | Hermes Agent compact mode (no slash commands available) | Same as above — create `.md` in `raw/transcripts/`, dev-loop discovers it |
 | Filesystem drop | You're NOT in a Claude session (Obsidian, editor, sync) | Create a new `.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.
+**Path Rule:** Captures ALWAYS go to `$(skillwiki path)/raw/transcripts/` (Layer 1). Never under `projects/{slug}/raw/` — that violates SCHEMA.md Layer 1 immutability. Text captures stay in `raw/transcripts/`. If the capture includes images or other binaries, store those files under `raw/assets/` with a sibling Markdown note that embeds them; never use a .txt sidecar (such as `README.txt`) as the only index; Obsidian opens Markdown notes.
 ### 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 |
@@ -92,6 +92,7 @@ Ad-hoc captures may omit `sha256`; omission does not grant mutation authority. O
 - 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).
 - Writing live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets to the vault.
+- Indexing `raw/assets/` binaries with only a `.txt` sidecar.
 ## 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`)

package/skills/wiki-ingest/SKILL.md

@@ -65,6 +65,7 @@ Raw ephemeral data (market feeds, logs, transient JSON) must be written to the *
 - Writing raw ephemeral data directly to cloud-mounted wiki paths (`~/wiki/`).
 - Writing host-local absolute paths as canonical durable source references (see `using-skillwiki` → Portable Source References).
 - 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.
+- Indexing `raw/assets/` binaries with only a `.txt` sidecar. Write a sibling Markdown note that embeds each file with `![[ ]]`.
 ## 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–8 for each source individually, using one `skillwiki ingest` command per source.

package/skills/wiki-init/SKILL.md

@@ -37,7 +37,9 @@ None for the first run.
    images remain external dependencies. An attended local-asset capture may
    choose any URL-friendly path under `raw/assets/`, but it must write the asset,
    emit an explicit vault-qualified `![[raw/assets/...]]` embed, verify
-   resolution/preview, and only then finalize the immutable raw note.
+   resolution/preview, and only then finalize the immutable raw note. Also write
+   a sibling Markdown note (`listings.md`, `note.md`, or a dated `.md`) that
+   embeds each file. Never use `.txt` as the only index.
 8. **Suggest first sources.** Propose 3–5 initial sources (URLs, papers, articles) appropriate to the domain. Prompt the user to provide the first one to ingest, then hand off to wiki-ingest.
 
 ## Stop conditions

package/templates/SCHEMA.md

@@ -117,6 +117,7 @@ project:          # optional: "[[slug]]" for cross-reference
 - **Stable asset pool:** binary assets may use any flat or URL-friendly nested path under `raw/assets/`; no fixed internal taxonomy such as papers/transcripts is required.
 - Use explicit vault-root embeds such as `![[raw/assets/example/diagram.png]]` so Obsidian preview and GitHub browsing remain unambiguous.
 - Resolve and preview a new local embed before finalizing its raw capture. Once referenced, the asset path freezes; source archive/dedup does not move it. Remote HTTP(S) images remain external dependencies unless separately captured.
+- **Asset notes:** When storing binaries under `raw/assets/`, also write a sibling Markdown note (`listings.md`, `note.md`, or a dated `.md`) that embeds each file with `![[filename.png]]` or vault-root `![[raw/assets/<dir>/<file>]]`. A `.txt` sidecar is never the only index; Obsidian opens Markdown notes, not `.txt`.
 - **Dataview queries** (read-only; do not replace index.md):
 
 ```dataview