skillwiki 0.10.76 → 0.10.78

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.76",
+  "version": "0.10.78",
   "skills": "./",
   "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": {

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.76",
+  "version": "0.10.78",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 21 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",

package/skills/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.76",
+  "version": "0.10.78",
   "description": "Project-aware Karpathy-style knowledge base: 21 prompt-only skills (wiki-*, proj-*, using-skillwiki, skillwiki-mcp) backed by HTTP MCP wiki_capture.",
   "author": {
     "name": "karlorz"

package/skills/agents/proj-init.md

@@ -20,6 +20,8 @@ You are a project workspace bootstrapper specializing in creating the `projects/
 3. Render README.md from template
 4. Update vault index.md and log.md
 
+**Leaf-host rule (HTTP MCP):** If `$VAULT/.WIKI_GIT_FROZEN` exists, do not local-write. Bootstrap via MCP `wiki_workitem_write` (workspace families: `projects/{slug}/README.md`, `architecture/**`, `requirements/**`, `compound/**` — `.md` only; omit `base_sha256` on create). Use at most `wiki_log_append` for the log entry; never edit `index.md` locally on a leaf. If `wiki_workitem_write` is absent or the deployed server predates the workspace-family allowlist (`PATH_DENIED`), STOP — never rclone/wiki-push.
+
 **Execution Process:**
 
 1. **Resolve vault.** Run `skillwiki path`. If NO_VAULT_CONFIGURED, report failure and STOP.

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.10.76",
+  "version": "0.10.78",
   "private": true,
   "files": [
     "wiki-*",

package/skills/proj-init/SKILL.md

@@ -22,8 +22,15 @@ Standard four reads (vault SCHEMA, index, log) — no project context yet.
 4. Update vault `index.md` "Projects" section: add `- [[projects/{slug}]]`.
 5. Append vault `log.md` entry: "Project {slug} initialized."
 
+## Leaf hosts (HTTP MCP)
+On a leaf host (vault has `.WIKI_GIT_FROZEN` or the HTTP MCP server is the writer), bootstrap goes through MCP instead of local file creation:
+- Write `projects/{slug}/README.md` and any initial `requirements/` or `architecture/` markdown via `wiki_workitem_write` (CAS: omit `base_sha256` on create). Directories materialize implicitly with the first file.
+- The `index.md` "Projects" line and the structural log stay projection/snapshotter-owned: use at most `wiki_log_append` for the init entry. Never edit `index.md` locally on a leaf.
+- If `wiki_workitem_write` is absent from the live tool list or the deployed server predates the workspace-family allowlist (`PATH_DENIED`), STOP — do not local-write, rclone, or wiki-push.
+
 ## Stop conditions
 - `projects/{slug}/` already exists.
+- Leaf host without a usable `wiki_workitem_write` (fail closed; capture the intent via `wiki_capture` instead).
 
 ## Forbidden
 - Modifying any other project's files.

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

@@ -22,8 +22,15 @@ Standard four reads (vault SCHEMA, index, log) — no project context yet.
 4. Update vault `index.md` "Projects" section: add `- [[projects/{slug}]]`.
 5. Append vault `log.md` entry: "Project {slug} initialized."
 
+## Leaf hosts (HTTP MCP)
+On a leaf host (vault has `.WIKI_GIT_FROZEN` or the HTTP MCP server is the writer), bootstrap goes through MCP instead of local file creation:
+- Write `projects/{slug}/README.md` and any initial `requirements/` or `architecture/` markdown via `wiki_workitem_write` (CAS: omit `base_sha256` on create). Directories materialize implicitly with the first file.
+- The `index.md` "Projects" line and the structural log stay projection/snapshotter-owned: use at most `wiki_log_append` for the init entry. Never edit `index.md` locally on a leaf.
+- If `wiki_workitem_write` is absent from the live tool list or the deployed server predates the workspace-family allowlist (`PATH_DENIED`), STOP — do not local-write, rclone, or wiki-push.
+
 ## Stop conditions
 - `projects/{slug}/` already exists.
+- Leaf host without a usable `wiki_workitem_write` (fail closed; capture the intent via `wiki_capture` instead).
 
 ## Forbidden
 - Modifying any other project's files.

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

@@ -35,9 +35,10 @@ On leaf hosts, wiki captures go through MCP. Do **not** write `raw/transcripts/`
 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. **Feature-detect work-item and page-publish tools**:
-   - When the server advertises `wiki_workitem_write`: use it to create, mutate, or close work items under `projects/<slug>/work/**` or update `projects/<slug>/knowledge.md`. Pass `path`, `content`, and `base_sha256` of existing bytes (from `wiki_read_page` or local mirror). On `FILE_CHANGED`, re-read and retry once.
+   - When the server advertises `wiki_workitem_write`: use it to create, mutate, or close work items under `projects/<slug>/work/**` or update `projects/<slug>/knowledge.md`, and to save Layer-3 workspace markdown: `projects/<slug>/README.md`, `projects/<slug>/architecture/**/*.md`, `projects/<slug>/requirements/**/*.md`, `projects/<slug>/compound/**/*.md`. Pass `path`, `content`, and `base_sha256` of existing bytes (from `wiki_read_page` or local mirror). On `FILE_CHANGED`, re-read and retry once. Deployed servers that predate the workspace-family allowlist deny those paths — treat that `PATH_DENIED` as "server predates this release"; STOP, do not fall back.
    - When the server advertises `wiki_page_publish`: use it to publish typed Layer-2 pages (`entities/`, `concepts/`, `comparisons/`, `queries/`, `meta/`) using the same CAS protocol.
    - When those tools are **absent** from the live tool list (e.g. server is captures-only): do not call them or claim they exist. If `$VAULT/.WIKI_GIT_FROZEN` exists, fall back to capturing a close note via `wiki_capture` or STOP. Work-item close remains unavailable on the frozen leaf without `wiki_workitem_write`. Do not `git commit` / `wiki-push` against `~/wiki`.
+4. **`PATH_DENIED` means STOP.** Paths outside the allowlist (`projects/<slug>/history/**`, non-`.md` files such as `fleet.yaml` or `.canvas`, `AGENTS.md`/`CLAUDE.md`, raw edits, index/projection rebuilds) have no agent write path over MCP. wiki-push / `rclone copy` is **not** an agent writer: it bypasses the daemon working copy, so `wiki_read_page` cannot see those bytes until the sg01 snapshot. Never report an S3-only copy as "saved to wiki". Capture the blocked intent via `wiki_capture` and report the denial instead.
 
 ## Reads
 

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

@@ -171,6 +171,7 @@ If the vault has `.WIKI_GIT_FROZEN`:
 |---|---|---|
 | Capture note/idea/bug/task | Yes | HTTP MCP `wiki_capture` / `wiki_log_append` |
 | Close or mutate a work item (`projects/*/work/**`, `knowledge.md`) | Conditional | If live MCP tools include `wiki_workitem_write`, mutate/close via MCP CAS; if absent, capture a close note via MCP `wiki_capture` or STOP. Never local-write. |
+| Save project workspace file (`architecture/`, `README.md`, `requirements/`, `compound/` — `.md` only) | Conditional | Via `wiki_workitem_write` CAS. Feature-detect: if the tool is absent or the deployed server predates the workspace-family allowlist (`PATH_DENIED`), STOP. Never rclone/wiki-push as a fallback writer. |
 | Publish typed Layer-2 page (`concepts/`, `queries/`, etc.) | Conditional | If live MCP tools include `wiki_page_publish`, publish via MCP CAS; if absent, STOP. Do not run local `skillwiki page publish`. |
 | `wiki-sync` push/commit | **No** | Git fail-closed. GitHub is sg01 `wiki-snapshot`. |
 | Read local `~/wiki` | Yes | Mirror reads only |

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

@@ -55,12 +55,37 @@ separate concerns.
 
 ## Fail-Closed Boundary
 
-Never write typed pages, `index.md`, or `log.md` directly. On leaf hosts, captures use HTTP MCP (`wiki_capture`), never local `raw/transcripts` or `log.md` writes. Never bare `rm` or `git rm` as a fleet delete (snapshot resurrects from S3). Never auto `npm install -g skillwiki` in headless/goal/satellite sessions. If `skillwiki page publish --help` is unavailable, fail closed.
+Never write typed pages, `index.md`, or `log.md` directly. On leaf hosts, captures use HTTP MCP (`wiki_capture`), never local `raw/transcripts` or `log.md` writes. Project workspace saves (`projects/<slug>/README.md`, `architecture/`, `requirements/`, `compound/` — `.md` only) go through MCP `wiki_workitem_write` CAS; feature-detect and STOP if the tool is absent or the deployed server predates the workspace-family allowlist (`PATH_DENIED`). wiki-push / rclone is never an agent writer — an S3-only copy is invisible to `wiki_read_page` until the sg01 snapshot; never report it as "saved to wiki". Never bare `rm` or `git rm` as a fleet delete (snapshot resurrects from S3). Never auto `npm install -g skillwiki` in headless/goal/satellite sessions. If `skillwiki page publish --help` is unavailable, fail closed.
 
 ## Sensitive Content
 
 Never commit secrets, credentials, API keys, tokens, passwords, or PII to the vault. Redact using `[REDACTED:<kind>]` before filing.
 
+<!-- mcp-instructions:begin -->
+## SkillWiki Remote Access Contract
+
+### Three-Plane Access Architecture
+- **HTTP MCP (Default)**: Primary remote access plane for AI agents. All reads and mutations go through MCP tools; local vault clone is not required.
+- **CLI (Opt-in)**: Local operator and authoring plane for diagnostics, linting, and health checks on provisioned machines.
+- **Git Clone (Opt-in)**: Storage and sync authority on metal authoring hosts; leaf/agent environments do not manage git or push to remotes.
+
+### Fail-Closed Boundary
+HTTP MCP is the sole agent writer. Never attempt direct local file writes to typed pages (concepts, entities, comparisons, queries, meta), index.md, or log.md. Direct filesystem mutations outside MCP fail closed. Always use MCP tools (wiki_capture, wiki_log_append, wiki_workitem_write, wiki_page_publish).
+
+### CAS Protocol (Compare-And-Swap)
+Mutating tools (wiki_workitem_write, wiki_page_publish) enforce CAS concurrency control to prevent clobbering:
+1. Call wiki_read_page to retrieve the document and its canonical sha256.
+2. Submit mutations with base_sha256 set to the read sha256.
+3. If the write returns FILE_CHANGED, re-read via wiki_read_page, rebase edits against currentVersion, and retry.
+
+### Capture Kinds
+Ad-hoc records via wiki_capture require kind in: task | idea | bug | note.
+Captures append remotely to raw/transcripts/ and never overwrite existing files. Use wiki_log_append for append-only log entries.
+
+### Sensitive Content
+Never send credentials, API keys, auth tokens, passwords, or PII. Redact sensitive values using [REDACTED:<kind>] (e.g. [REDACTED:token]) before writing.
+<!-- mcp-instructions:end -->
+
 ## Drift Warning
 
 If `skillwiki doctor` mentions a version newer than this file, re-read the full `/using-skillwiki` skill for updated content.

package/skills/skillwiki-mcp/SKILL.md

@@ -35,9 +35,10 @@ On leaf hosts, wiki captures go through MCP. Do **not** write `raw/transcripts/`
 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. **Feature-detect work-item and page-publish tools**:
-   - When the server advertises `wiki_workitem_write`: use it to create, mutate, or close work items under `projects/<slug>/work/**` or update `projects/<slug>/knowledge.md`. Pass `path`, `content`, and `base_sha256` of existing bytes (from `wiki_read_page` or local mirror). On `FILE_CHANGED`, re-read and retry once.
+   - When the server advertises `wiki_workitem_write`: use it to create, mutate, or close work items under `projects/<slug>/work/**` or update `projects/<slug>/knowledge.md`, and to save Layer-3 workspace markdown: `projects/<slug>/README.md`, `projects/<slug>/architecture/**/*.md`, `projects/<slug>/requirements/**/*.md`, `projects/<slug>/compound/**/*.md`. Pass `path`, `content`, and `base_sha256` of existing bytes (from `wiki_read_page` or local mirror). On `FILE_CHANGED`, re-read and retry once. Deployed servers that predate the workspace-family allowlist deny those paths — treat that `PATH_DENIED` as "server predates this release"; STOP, do not fall back.
    - When the server advertises `wiki_page_publish`: use it to publish typed Layer-2 pages (`entities/`, `concepts/`, `comparisons/`, `queries/`, `meta/`) using the same CAS protocol.
    - When those tools are **absent** from the live tool list (e.g. server is captures-only): do not call them or claim they exist. If `$VAULT/.WIKI_GIT_FROZEN` exists, fall back to capturing a close note via `wiki_capture` or STOP. Work-item close remains unavailable on the frozen leaf without `wiki_workitem_write`. Do not `git commit` / `wiki-push` against `~/wiki`.
+4. **`PATH_DENIED` means STOP.** Paths outside the allowlist (`projects/<slug>/history/**`, non-`.md` files such as `fleet.yaml` or `.canvas`, `AGENTS.md`/`CLAUDE.md`, raw edits, index/projection rebuilds) have no agent write path over MCP. wiki-push / `rclone copy` is **not** an agent writer: it bypasses the daemon working copy, so `wiki_read_page` cannot see those bytes until the sg01 snapshot. Never report an S3-only copy as "saved to wiki". Capture the blocked intent via `wiki_capture` and report the denial instead.
 
 ## Reads
 

package/skills/using-skillwiki/SKILL.md

@@ -171,6 +171,7 @@ If the vault has `.WIKI_GIT_FROZEN`:
 |---|---|---|
 | Capture note/idea/bug/task | Yes | HTTP MCP `wiki_capture` / `wiki_log_append` |
 | Close or mutate a work item (`projects/*/work/**`, `knowledge.md`) | Conditional | If live MCP tools include `wiki_workitem_write`, mutate/close via MCP CAS; if absent, capture a close note via MCP `wiki_capture` or STOP. Never local-write. |
+| Save project workspace file (`architecture/`, `README.md`, `requirements/`, `compound/` — `.md` only) | Conditional | Via `wiki_workitem_write` CAS. Feature-detect: if the tool is absent or the deployed server predates the workspace-family allowlist (`PATH_DENIED`), STOP. Never rclone/wiki-push as a fallback writer. |
 | Publish typed Layer-2 page (`concepts/`, `queries/`, etc.) | Conditional | If live MCP tools include `wiki_page_publish`, publish via MCP CAS; if absent, STOP. Do not run local `skillwiki page publish`. |
 | `wiki-sync` push/commit | **No** | Git fail-closed. GitHub is sg01 `wiki-snapshot`. |
 | Read local `~/wiki` | Yes | Mirror reads only |

package/skills/using-skillwiki/activation.md

@@ -55,12 +55,37 @@ separate concerns.
 
 ## Fail-Closed Boundary
 
-Never write typed pages, `index.md`, or `log.md` directly. On leaf hosts, captures use HTTP MCP (`wiki_capture`), never local `raw/transcripts` or `log.md` writes. Never bare `rm` or `git rm` as a fleet delete (snapshot resurrects from S3). Never auto `npm install -g skillwiki` in headless/goal/satellite sessions. If `skillwiki page publish --help` is unavailable, fail closed.
+Never write typed pages, `index.md`, or `log.md` directly. On leaf hosts, captures use HTTP MCP (`wiki_capture`), never local `raw/transcripts` or `log.md` writes. Project workspace saves (`projects/<slug>/README.md`, `architecture/`, `requirements/`, `compound/` — `.md` only) go through MCP `wiki_workitem_write` CAS; feature-detect and STOP if the tool is absent or the deployed server predates the workspace-family allowlist (`PATH_DENIED`). wiki-push / rclone is never an agent writer — an S3-only copy is invisible to `wiki_read_page` until the sg01 snapshot; never report it as "saved to wiki". Never bare `rm` or `git rm` as a fleet delete (snapshot resurrects from S3). Never auto `npm install -g skillwiki` in headless/goal/satellite sessions. If `skillwiki page publish --help` is unavailable, fail closed.
 
 ## Sensitive Content
 
 Never commit secrets, credentials, API keys, tokens, passwords, or PII to the vault. Redact using `[REDACTED:<kind>]` before filing.
 
+<!-- mcp-instructions:begin -->
+## SkillWiki Remote Access Contract
+
+### Three-Plane Access Architecture
+- **HTTP MCP (Default)**: Primary remote access plane for AI agents. All reads and mutations go through MCP tools; local vault clone is not required.
+- **CLI (Opt-in)**: Local operator and authoring plane for diagnostics, linting, and health checks on provisioned machines.
+- **Git Clone (Opt-in)**: Storage and sync authority on metal authoring hosts; leaf/agent environments do not manage git or push to remotes.
+
+### Fail-Closed Boundary
+HTTP MCP is the sole agent writer. Never attempt direct local file writes to typed pages (concepts, entities, comparisons, queries, meta), index.md, or log.md. Direct filesystem mutations outside MCP fail closed. Always use MCP tools (wiki_capture, wiki_log_append, wiki_workitem_write, wiki_page_publish).
+
+### CAS Protocol (Compare-And-Swap)
+Mutating tools (wiki_workitem_write, wiki_page_publish) enforce CAS concurrency control to prevent clobbering:
+1. Call wiki_read_page to retrieve the document and its canonical sha256.
+2. Submit mutations with base_sha256 set to the read sha256.
+3. If the write returns FILE_CHANGED, re-read via wiki_read_page, rebase edits against currentVersion, and retry.
+
+### Capture Kinds
+Ad-hoc records via wiki_capture require kind in: task | idea | bug | note.
+Captures append remotely to raw/transcripts/ and never overwrite existing files. Use wiki_log_append for append-only log entries.
+
+### Sensitive Content
+Never send credentials, API keys, auth tokens, passwords, or PII. Redact sensitive values using [REDACTED:<kind>] (e.g. [REDACTED:token]) before writing.
+<!-- mcp-instructions:end -->
+
 ## Drift Warning
 
 If `skillwiki doctor` mentions a version newer than this file, re-read the full `/using-skillwiki` skill for updated content.