npm - skillwiki - Versions diffs - 0.10.104 → 0.10.105 - Mend

skillwiki 0.10.104 → 0.10.105

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/dist/vault-sync/scripts/wiki-snapshot.sh +82 -2
package/package.json +1 -1
package/skills/.claude-plugin/plugin.json +1 -1
package/skills/.codex-plugin/plugin.json +1 -1
package/skills/.cursor-plugin/plugin.json +1 -1
package/skills/package.json +1 -1
package/skills/skills/skillwiki-mcp/SKILL.md +4 -2
package/skills/skills/using-skillwiki/activation.md +61 -69
package/skills/skillwiki-mcp/SKILL.md +4 -2
package/skills/using-skillwiki/activation.md +61 -69

package/dist/vault-sync/scripts/wiki-snapshot.sh CHANGED Viewed

@@ -1042,6 +1042,84 @@ if [ ! -f "$SNAPSHOT_WORKTREE/index.md" ]; then
     exit 1
 fi
+# --- Post-sync direct-S3 log append race ---
+# An MCP log.md append that lands after the pre-sync parity wait (or after the
+# post-repair sync) leaves S3 log.md strictly longer than the worktree copy.
+# The post-sync gate has already refreshed expectations from direct S3. Compare
+# those bytes with the worktree before running the terminal parity gate. Only a
+# strict append of log.md with an unchanged index.md permits one more sync.
+snapshot_post_sync_log_append_race_detected() {
+    [ -n "$PROJECTION_STATE_DIR" ] || return 1
+    [ -f "$SNAPSHOT_WORKTREE/index.md" ] || return 1
+    [ -f "$SNAPSHOT_WORKTREE/log.md" ] || return 1
+    if ! cmp -s "$SNAPSHOT_WORKTREE/index.md" "$PROJECTION_STATE_DIR/expected-index.md"; then
+        log "post-sync log-append race: current store index.md differs from worktree index.md; no additional sync"
+        return 1
+    fi
+    if ! snapshot_projection_log_is_store_ahead "$SNAPSHOT_WORKTREE/log.md" "$PROJECTION_STATE_DIR/expected-log.md"; then
+        log "post-sync log-append race: current store log.md is not a strict prefix extension of worktree log.md; no additional sync"
+        return 1
+    fi
+    return 0
+}
+# Run one additional full rclone sync with the existing RCLONE_OPTS, then repeat
+# delete-intent reconciliation, re-read the current store, and re-run the
+# existing exact worktree parity and semantic preview gates. Returns 0 only when
+# the recovery converged; the caller refuses (without a second retry) otherwise.
+snapshot_retry_sync_after_log_append_race() {
+    local context="${1:-post-sync}"
+    if ! rclone sync "$CLOUD_REMOTE" "$SNAPSHOT_WORKTREE" "${RCLONE_OPTS[@]}" --stats 10s 2>&1 | tee "$RCLONE_LOG"; then
+        log "ERROR: $context log-append race retry rclone sync failed"
+        tail -50 "$RCLONE_LOG" >> "$LOG_FILE" 2>/dev/null || true
+        rm -f "$RCLONE_LOG"
+        return 1
+    fi
+    rm -f "$RCLONE_LOG"
+    log "post-sync log-append race detected; performed one additional rclone sync context=$context"
+    if ! snapshot_reconcile_delete_intents; then
+        log "ERROR: $context log-append race retry delete-intent reconciliation failed"
+        return 1
+    fi
+    snapshot_gate_projection_candidate \
+        "FAIL $context log-append race retry projection expectation refresh; snapshot promotion refused" \
+        "FAIL $context log-append race retry projection candidate verification; snapshot promotion refused"
+}
+# Post-sync projection gate with at most one log-append-race recovery.
+# A first failure that is not the recoverable log-append shape (or that does not
+# converge after the single retry) is logged as the terminal refusal.
+snapshot_gate_projection_candidate_with_race_retry() {
+    local context="${1:-post-sync}"
+    local refresh_fail="$2"
+    local verify_fail="$3"
+    if ! snapshot_refresh_projection_expectations_from_store; then
+        log "$refresh_fail"
+        return 1
+    fi
+    # Exact byte parity is the ordinary path. Its semantic preview is terminal:
+    # a later append must not turn a preview failure into a retry.
+    if [ -z "$PROJECTION_STATE_DIR" ] \
+        || { cmp -s "$PROJECTION_STATE_DIR/expected-index.md" "$SNAPSHOT_WORKTREE/index.md" \
+            && cmp -s "$PROJECTION_STATE_DIR/expected-log.md" "$SNAPSHOT_WORKTREE/log.md"; }; then
+        if snapshot_verify_projection_candidate; then
+            return 0
+        fi
+        log "$verify_fail"
+        return 1
+    fi
+    if ! snapshot_post_sync_log_append_race_detected; then
+        snapshot_verify_worktree_projection_parity || true
+        log "$verify_fail"
+        return 1
+    fi
+    if snapshot_retry_sync_after_log_append_race "$context"; then
+        return 0
+    fi
+    log "$verify_fail"
+    return 1
+}
 # --- Delete-intent no-resurrect ---
 # Git is SSOT for intentional absences. After S3→worktree sync, strip any path
 # that has an active tombstone on origin/main and optionally prune S3.
@@ -1195,7 +1273,8 @@ snapshot_reconcile_delete_intents() {
 if ! snapshot_reconcile_delete_intents; then
     exit 1
 fi
-if ! snapshot_gate_projection_candidate \
+if ! snapshot_gate_projection_candidate_with_race_retry \
+    "post-sync" \
     "FAIL projection expectation refresh after sync; snapshot promotion refused" \
     "FAIL projection candidate verification; snapshot promotion refused"; then
     exit 1
@@ -1270,7 +1349,8 @@ if [ "$needs_repair" = true ]; then
     if ! snapshot_reconcile_delete_intents; then
         exit 1
     fi
-    if ! snapshot_gate_projection_candidate \
+    if ! snapshot_gate_projection_candidate_with_race_retry \
+        "post-repair" \
         "FAIL post-repair projection expectation refresh after sync; snapshot promotion refused" \
         "FAIL post-repair projection candidate verification; snapshot promotion refused"; then
         exit 1

package/package.json CHANGED Viewed

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.104",
+  "version": "0.10.105",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 22 prompt-only skills (wiki-*, proj-*, using-skillwiki, skillwiki-mcp, skillwiki-connect) backed by the deterministic `skillwiki` CLI.",
   "author": {

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

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

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

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

package/skills/package.json CHANGED Viewed

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

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

@@ -14,7 +14,7 @@ SkillWiki captures are HTTP MCP only (`type: http`). Claude/Grok use `SKILLWIKI_
 ## 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.
-- **Cursor / Grok Bot:** the Cursor-native plugin requires `SKILLWIKI_MCP_TOKEN` under **Plugins → Configure**. Optional non-secret `SKILLWIKI_EXTRA_VAULTS` (comma-separated vault ids such as `wiki-fin`) opts the client into extra vaults on the **same** connector URL. It is not a second connector, not a secret, and not written to `~/.cursor/mcp.json` or Grok `config.toml`. Server `allowed_vaults` remains the security boundary; an extra listed here but missing from the bearer still fails closed. Omit `vault=` on tools to use the handshake `default_vault` (central). Grok Bot does not inherit Mac process env or `~/.cursor/mcp.json`. `failed_to_load` with no token box means this package is missing; after this package is installed, Configure is the token field (same pattern as grok-search).
+- **Cursor / Grok Bot:** the Cursor-native plugin requires `SKILLWIKI_MCP_TOKEN` under **Plugins → Configure**. Optional non-secret `SKILLWIKI_EXTRA_VAULTS` (comma-separated vault ids such as `wiki-fin`) opts the client into extra vaults on the **same** connector URL. It is not a second connector, not a secret, and not written to `~/.cursor/mcp.json` or Grok `config.toml`. Server `allowed_vaults` remains the security boundary; an extra listed here but missing from the bearer still fails closed. Omit `vault=` on tools to use the live handshake `default_vault`; specify an extra vault only when requested. Grok Bot does not inherit Mac process env or `~/.cursor/mcp.json`. `failed_to_load` with no token box means this package is missing; after this package is installed, Configure is the token field (same pattern as grok-search).
 - `missing_prereq` means `SKILLWIKI_MCP_TOKEN` is absent from process environment; stop and ask for a bearer. Do not invent a stdio MCP.
 - A new host (a machine that should write the wiki for the first time) needs an issued host-id bearer before handshake can pass. The operator runs `skillwiki mcp-auth issue-host --host-id <id> --write` on metal (TTY required). Connector hosts put the printed value into process env or host Configure. Unknown agents (no plugin / no usable connector) ingest a chat-attached env file with `skillwiki connect --from-file` (or `--from-stdin`); do not instruct paste-into-chat. Do not auto-write `mcp.env`, `mcp.json`, or Grok `config.toml`. Do not invent a second admin skill. A local vault/FUSE mirror is optional.
 - First-run order: install plugin/CLI → operator issues on metal → connector Configure **or** unknown-agent `skillwiki connect --from-file <attachment>` → **new session** → `skillwiki doctor --check-mcp` → one write (`wiki_capture`, work-item write, or page publish).
@@ -32,7 +32,9 @@ Remotes still on a pre-HTTP-MCP plugin or CLI must upgrade the plugin channel (a
 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`.
+Check the successful write receipt's `vault_id` against the intended vault before reporting any write as saved.
+1. Call MCP `wiki_capture` with `kind` (`task` | `idea` | `bug` | `note`), `project`, `title`, and `content`. Optional `agent_note`. Verify its returned `path` with `wiki_read_page` in that vault.
 2. Call MCP `wiki_log_append` when a structural `log.md` line is needed. Pass append-only `content` (optional `operation_id` is 64 hex). Success returns a receipt (`operation_id`, `event_path`, hashes, `s3_verified`). Verify the exact block via `wiki_read_page(event_path)`. Do not require reading `log.md`. If `log.md` is over 256 KiB, full `wiki_read_page("log.md")` returns `PAGE_TOO_LARGE`; use `tail_bytes` only to browse the newest end.
 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`, 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.

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

@@ -1,98 +1,90 @@
 # SkillWiki Activation
-You have SkillWiki - a project-aware knowledge-base CLI + skill suite for agent harnesses.
-This file is loaded at session start. For full operational detail, invoke `/using-skillwiki`.
+SkillWiki is the project-aware knowledge base and skill suite. This file is
+session-start routing context; invoke `using-skillwiki` for full instructions.
-## CLI Probe
+## Route
-If `skillwiki --help` fails, the CLI is unavailable. Degrade to manual file ops (grep/find) for read-only queries. Fail closed for managed mutations - never write typed pages, index, or log directly.
+Use SkillWiki for vault or wiki work: setup, capture, ingestion, search, health,
+provenance, lifecycle, project workspaces, decisions, sync, or graphing.
+Choose the matching installed skill:
-## When to Route
+- Setup and input: `wiki-init`, `wiki-ingest`, `wiki-add-task`,
+  `wiki-adapter-prd`, `skillwiki-connect`.
+- Read and maintain: `wiki-query`, `wiki-lint`, `wiki-audit`,
+  `wiki-crystallize`, `wiki-reingest`, `wiki-archive`, `wiki-remove`.
+- Projects and planning: `proj-init`, `proj-work`, `proj-distill`,
+  `proj-decide`, `wiki-gate-plan-mode`, `dev-loop:research`.
+- Fleet and visualization: `wiki-sync`, `wiki-canvas`.
+- HTTP MCP capture or append: `skillwiki-mcp`.
-Invoke a SkillWiki skill when the user: wants vault/wiki/knowledge-base operations, ingests sources or URLs, searches/queries vault content, runs health checks or lint, crystallizes a session, works with project workspaces/ADRs, captures ideas/bugs/tasks, archives pages, removes paths, detects source drift, ingests foreign PRD formats, syncs vault git, or visualizes the vault graph.
+If routing is unclear, invoke `using-skillwiki` rather than guessing.
-## Skill Map
+## CLI and Planning
-| Skill | When to Invoke |
-|-------|----------------|
-| `wiki-init` | Bootstrap a vault |
-| `wiki-ingest` | Convert URLs/files/text into typed-knowledge pages |
-| `wiki-query` | Search typed knowledge |
-| `wiki-lint` | Vault health and lint checks |
-| `wiki-crystallize` | Distill current session into a typed page |
-| `wiki-audit` | Verify raw provenance and source integrity |
-| `wiki-archive` | Archive typed pages or preserve-move raw sources |
-| `wiki-remove` | Hard-delete vault paths without snapshot resurrection |
-| `wiki-reingest` | Detect source drift and re-ingest updated content |
-| `wiki-add-task` | Quick-capture ideas, bugs, tasks, notes (HTTP MCP on leaf hosts; local files on authoring hosts) |
-| `skillwiki-mcp` | HTTP MCP captures (`wiki_capture`, `wiki_log_append`); never local writes on leaf hosts |
-| `skillwiki-connect` | Unknown-agent HTTP MCP connect: `skillwiki connect --from-file` (never paste-into-chat) |
-| `wiki-adapter-prd` | Map foreign PRD formats (CodeStable, RFC, AIDE, Hermes) |
-| `wiki-sync` | Safely sync vault git repository |
-| `wiki-canvas` | Generate Obsidian Canvas visualization |
-| `wiki-gate-plan-mode` | Toggle EnterPlanMode gating for brainstorming then proj-work |
-| `proj-init` | Bootstrap a project workspace |
-| `proj-work` | Open or run a work item |
-| `proj-distill` | Distill project compound entries into concept pages |
-| `proj-decide` | Write an Architectural Decision Record (ADR) |
-| `dev-loop:research` | Research scan of repo + vault health |
+If `skillwiki --help` fails, use local tools only for read-only inspection and
+fail closed for managed mutations.
-## PRD Bridge
+After architectural design approval, invoke `proj-work` and put `spec.md` in
+that work item. Do not invoke `writing-plans`. Do not git commit from
+brainstorming. Use standalone `test-driven-development` for bounded TDD. For UI
+work, offer `visual-companion.md` once. Never create `docs/superpowers/`.
-After architectural design approval, invoke `proj-work` then write `spec.md` in that work folder. Do not invoke `writing-plans`. Do not git commit from brainstorming. Bounded TDD uses standalone `test-driven-development` when installed. For UI work, offer brainstorming `visual-companion.md` once (optional). Never create `docs/superpowers/` in any repo.
+Workflow profiles are `native`, `guided`, and explicit-only `full`; selection
+is `adaptive` or `fixed`. Installation or cache discovery proves availability,
+not activation. Native and guided do not force Superpowers or plan-mode gating.
+Only a full profile may use its configured provider flow. Invalid fixed policy
+fails closed; noninteractive sessions do not prompt. Keep workflow profile,
+PRD provider and stage, SkillWiki provenance, and simplify review independent.
-## Workflow Profiles
+## Managed-Write Safety
-Resolve workflow policy before loading provider skills. Profiles are `native`,
-`guided`, and explicit-only `full`; selection is `adaptive` or `fixed`.
-Adaptive chooses only native or guided. Installation and cache discovery prove
-availability, never activation. Native and guided do not force Superpowers or
-plan-mode gating. Explicit full may use the complete configured provider flow;
-gate plan mode only when that flow actually uses Superpowers/TDD planning.
-Invalid fixed policy is unresolved and fail-closed. Noninteractive sessions do
-not prompt. Keep workflow profile, `prd_layer` provider, `prd_pipeline` stage
-template, SkillWiki provenance, and the independent simplify review gate as
-separate concerns.
+The HTTP MCP contract below controls remote reads and mutations. On leaf hosts,
+captures use MCP, never local `raw/transcripts` or `log.md` writes. Project
+workspace writes use `wiki_workitem_write` with compare-and-swap; stop if the
+tool or path family is unavailable. A wiki push or rclone copy is not a managed
+write and is not visible until the authoritative snapshot. Never use bare `rm`
+or `git rm` for fleet deletion. Never auto-install SkillWiki in unattended
+sessions. If required publish support is unavailable, fail closed.
-## 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. 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.
+Never send secrets, credentials, tokens, passwords, or personal information.
+Redact with `[REDACTED:<kind>]`.
 <!-- 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.
+HTTP MCP is the default agent plane. CLI is an opt-in operator plane; Git clone
+is storage authority on authoring hosts. Leaf agents do not manage vault git.
 ### 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).
+HTTP MCP is the sole managed writer. Use `wiki_capture`, `wiki_log_append`,
+`wiki_workitem_write`, or `wiki_page_publish`; never write typed pages,
+`index.md`, or `log.md` directly.
+### Vault Selection
+For the usual vault, omit `vault` and use the live handshake's `default_vault`.
+Set `vault` only when an extra vault was explicitly requested. Before reporting
+a write as saved, check its successful receipt's `vault_id` against the intended
+vault.
 ### 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.
+For `wiki_workitem_write` or `wiki_page_publish`, read first, send the returned
+sha256 as `base_sha256`, and on `FILE_CHANGED` re-read, rebase, 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. Success returns a receipt; verify via wiki_read_page(event_path). Do not require reading log.md. wiki_read_page accepts optional tail_bytes for browsing oversized pages.
+`wiki_capture` kind is `task | idea | bug | note`. Captures append to
+`raw/transcripts/`. Verify its returned `path` with `wiki_read_page`.
+`wiki_log_append` is append-only; verify its `event_path` with `wiki_read_page`.
+Use `tail_bytes` for large pages.
 ### Sensitive Content
-Never send credentials, API keys, auth tokens, passwords, or PII. Redact sensitive values using [REDACTED:<kind>] (e.g. [REDACTED:token]) before writing.
+Never send secrets or personal information. Use `[REDACTED:<kind>]`.
 <!-- 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.
-## Canonical Paths
+## Drift and Canonical Paths
-- Full skill (logical): invoke `/using-skillwiki` or read the installed plugin skill at `<plugin-root>/using-skillwiki/SKILL.md` (repository source: `packages/skills/using-skillwiki/SKILL.md`)
-- Vault schema: `SCHEMA.md` at the vault root (run `skillwiki path` to resolve)
-- Frontier agents (`proj-work`, `proj-decide`): plugin-root `agents/<name>.md` with `model: inherit` — refresh with the active plugin channel (`grok plugin update skillwiki` on Grok)
+If `skillwiki doctor` reports a newer version, invoke `using-skillwiki` again.
+The full source skill is `packages/skills/using-skillwiki/SKILL.md`; resolve the
+vault with `skillwiki path`. Frontier project agents are installed under the
+plugin root with `model: inherit`.

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

@@ -14,7 +14,7 @@ SkillWiki captures are HTTP MCP only (`type: http`). Claude/Grok use `SKILLWIKI_
 ## 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.
-- **Cursor / Grok Bot:** the Cursor-native plugin requires `SKILLWIKI_MCP_TOKEN` under **Plugins → Configure**. Optional non-secret `SKILLWIKI_EXTRA_VAULTS` (comma-separated vault ids such as `wiki-fin`) opts the client into extra vaults on the **same** connector URL. It is not a second connector, not a secret, and not written to `~/.cursor/mcp.json` or Grok `config.toml`. Server `allowed_vaults` remains the security boundary; an extra listed here but missing from the bearer still fails closed. Omit `vault=` on tools to use the handshake `default_vault` (central). Grok Bot does not inherit Mac process env or `~/.cursor/mcp.json`. `failed_to_load` with no token box means this package is missing; after this package is installed, Configure is the token field (same pattern as grok-search).
+- **Cursor / Grok Bot:** the Cursor-native plugin requires `SKILLWIKI_MCP_TOKEN` under **Plugins → Configure**. Optional non-secret `SKILLWIKI_EXTRA_VAULTS` (comma-separated vault ids such as `wiki-fin`) opts the client into extra vaults on the **same** connector URL. It is not a second connector, not a secret, and not written to `~/.cursor/mcp.json` or Grok `config.toml`. Server `allowed_vaults` remains the security boundary; an extra listed here but missing from the bearer still fails closed. Omit `vault=` on tools to use the live handshake `default_vault`; specify an extra vault only when requested. Grok Bot does not inherit Mac process env or `~/.cursor/mcp.json`. `failed_to_load` with no token box means this package is missing; after this package is installed, Configure is the token field (same pattern as grok-search).
 - `missing_prereq` means `SKILLWIKI_MCP_TOKEN` is absent from process environment; stop and ask for a bearer. Do not invent a stdio MCP.
 - A new host (a machine that should write the wiki for the first time) needs an issued host-id bearer before handshake can pass. The operator runs `skillwiki mcp-auth issue-host --host-id <id> --write` on metal (TTY required). Connector hosts put the printed value into process env or host Configure. Unknown agents (no plugin / no usable connector) ingest a chat-attached env file with `skillwiki connect --from-file` (or `--from-stdin`); do not instruct paste-into-chat. Do not auto-write `mcp.env`, `mcp.json`, or Grok `config.toml`. Do not invent a second admin skill. A local vault/FUSE mirror is optional.
 - First-run order: install plugin/CLI → operator issues on metal → connector Configure **or** unknown-agent `skillwiki connect --from-file <attachment>` → **new session** → `skillwiki doctor --check-mcp` → one write (`wiki_capture`, work-item write, or page publish).
@@ -32,7 +32,9 @@ Remotes still on a pre-HTTP-MCP plugin or CLI must upgrade the plugin channel (a
 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`.
+Check the successful write receipt's `vault_id` against the intended vault before reporting any write as saved.
+1. Call MCP `wiki_capture` with `kind` (`task` | `idea` | `bug` | `note`), `project`, `title`, and `content`. Optional `agent_note`. Verify its returned `path` with `wiki_read_page` in that vault.
 2. Call MCP `wiki_log_append` when a structural `log.md` line is needed. Pass append-only `content` (optional `operation_id` is 64 hex). Success returns a receipt (`operation_id`, `event_path`, hashes, `s3_verified`). Verify the exact block via `wiki_read_page(event_path)`. Do not require reading `log.md`. If `log.md` is over 256 KiB, full `wiki_read_page("log.md")` returns `PAGE_TOO_LARGE`; use `tail_bytes` only to browse the newest end.
 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`, 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.

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

@@ -1,98 +1,90 @@
 # SkillWiki Activation
-You have SkillWiki - a project-aware knowledge-base CLI + skill suite for agent harnesses.
-This file is loaded at session start. For full operational detail, invoke `/using-skillwiki`.
+SkillWiki is the project-aware knowledge base and skill suite. This file is
+session-start routing context; invoke `using-skillwiki` for full instructions.
-## CLI Probe
+## Route
-If `skillwiki --help` fails, the CLI is unavailable. Degrade to manual file ops (grep/find) for read-only queries. Fail closed for managed mutations - never write typed pages, index, or log directly.
+Use SkillWiki for vault or wiki work: setup, capture, ingestion, search, health,
+provenance, lifecycle, project workspaces, decisions, sync, or graphing.
+Choose the matching installed skill:
-## When to Route
+- Setup and input: `wiki-init`, `wiki-ingest`, `wiki-add-task`,
+  `wiki-adapter-prd`, `skillwiki-connect`.
+- Read and maintain: `wiki-query`, `wiki-lint`, `wiki-audit`,
+  `wiki-crystallize`, `wiki-reingest`, `wiki-archive`, `wiki-remove`.
+- Projects and planning: `proj-init`, `proj-work`, `proj-distill`,
+  `proj-decide`, `wiki-gate-plan-mode`, `dev-loop:research`.
+- Fleet and visualization: `wiki-sync`, `wiki-canvas`.
+- HTTP MCP capture or append: `skillwiki-mcp`.
-Invoke a SkillWiki skill when the user: wants vault/wiki/knowledge-base operations, ingests sources or URLs, searches/queries vault content, runs health checks or lint, crystallizes a session, works with project workspaces/ADRs, captures ideas/bugs/tasks, archives pages, removes paths, detects source drift, ingests foreign PRD formats, syncs vault git, or visualizes the vault graph.
+If routing is unclear, invoke `using-skillwiki` rather than guessing.
-## Skill Map
+## CLI and Planning
-| Skill | When to Invoke |
-|-------|----------------|
-| `wiki-init` | Bootstrap a vault |
-| `wiki-ingest` | Convert URLs/files/text into typed-knowledge pages |
-| `wiki-query` | Search typed knowledge |
-| `wiki-lint` | Vault health and lint checks |
-| `wiki-crystallize` | Distill current session into a typed page |
-| `wiki-audit` | Verify raw provenance and source integrity |
-| `wiki-archive` | Archive typed pages or preserve-move raw sources |
-| `wiki-remove` | Hard-delete vault paths without snapshot resurrection |
-| `wiki-reingest` | Detect source drift and re-ingest updated content |
-| `wiki-add-task` | Quick-capture ideas, bugs, tasks, notes (HTTP MCP on leaf hosts; local files on authoring hosts) |
-| `skillwiki-mcp` | HTTP MCP captures (`wiki_capture`, `wiki_log_append`); never local writes on leaf hosts |
-| `skillwiki-connect` | Unknown-agent HTTP MCP connect: `skillwiki connect --from-file` (never paste-into-chat) |
-| `wiki-adapter-prd` | Map foreign PRD formats (CodeStable, RFC, AIDE, Hermes) |
-| `wiki-sync` | Safely sync vault git repository |
-| `wiki-canvas` | Generate Obsidian Canvas visualization |
-| `wiki-gate-plan-mode` | Toggle EnterPlanMode gating for brainstorming then proj-work |
-| `proj-init` | Bootstrap a project workspace |
-| `proj-work` | Open or run a work item |
-| `proj-distill` | Distill project compound entries into concept pages |
-| `proj-decide` | Write an Architectural Decision Record (ADR) |
-| `dev-loop:research` | Research scan of repo + vault health |
+If `skillwiki --help` fails, use local tools only for read-only inspection and
+fail closed for managed mutations.
-## PRD Bridge
+After architectural design approval, invoke `proj-work` and put `spec.md` in
+that work item. Do not invoke `writing-plans`. Do not git commit from
+brainstorming. Use standalone `test-driven-development` for bounded TDD. For UI
+work, offer `visual-companion.md` once. Never create `docs/superpowers/`.
-After architectural design approval, invoke `proj-work` then write `spec.md` in that work folder. Do not invoke `writing-plans`. Do not git commit from brainstorming. Bounded TDD uses standalone `test-driven-development` when installed. For UI work, offer brainstorming `visual-companion.md` once (optional). Never create `docs/superpowers/` in any repo.
+Workflow profiles are `native`, `guided`, and explicit-only `full`; selection
+is `adaptive` or `fixed`. Installation or cache discovery proves availability,
+not activation. Native and guided do not force Superpowers or plan-mode gating.
+Only a full profile may use its configured provider flow. Invalid fixed policy
+fails closed; noninteractive sessions do not prompt. Keep workflow profile,
+PRD provider and stage, SkillWiki provenance, and simplify review independent.
-## Workflow Profiles
+## Managed-Write Safety
-Resolve workflow policy before loading provider skills. Profiles are `native`,
-`guided`, and explicit-only `full`; selection is `adaptive` or `fixed`.
-Adaptive chooses only native or guided. Installation and cache discovery prove
-availability, never activation. Native and guided do not force Superpowers or
-plan-mode gating. Explicit full may use the complete configured provider flow;
-gate plan mode only when that flow actually uses Superpowers/TDD planning.
-Invalid fixed policy is unresolved and fail-closed. Noninteractive sessions do
-not prompt. Keep workflow profile, `prd_layer` provider, `prd_pipeline` stage
-template, SkillWiki provenance, and the independent simplify review gate as
-separate concerns.
+The HTTP MCP contract below controls remote reads and mutations. On leaf hosts,
+captures use MCP, never local `raw/transcripts` or `log.md` writes. Project
+workspace writes use `wiki_workitem_write` with compare-and-swap; stop if the
+tool or path family is unavailable. A wiki push or rclone copy is not a managed
+write and is not visible until the authoritative snapshot. Never use bare `rm`
+or `git rm` for fleet deletion. Never auto-install SkillWiki in unattended
+sessions. If required publish support is unavailable, fail closed.
-## 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. 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.
+Never send secrets, credentials, tokens, passwords, or personal information.
+Redact with `[REDACTED:<kind>]`.
 <!-- 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.
+HTTP MCP is the default agent plane. CLI is an opt-in operator plane; Git clone
+is storage authority on authoring hosts. Leaf agents do not manage vault git.
 ### 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).
+HTTP MCP is the sole managed writer. Use `wiki_capture`, `wiki_log_append`,
+`wiki_workitem_write`, or `wiki_page_publish`; never write typed pages,
+`index.md`, or `log.md` directly.
+### Vault Selection
+For the usual vault, omit `vault` and use the live handshake's `default_vault`.
+Set `vault` only when an extra vault was explicitly requested. Before reporting
+a write as saved, check its successful receipt's `vault_id` against the intended
+vault.
 ### 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.
+For `wiki_workitem_write` or `wiki_page_publish`, read first, send the returned
+sha256 as `base_sha256`, and on `FILE_CHANGED` re-read, rebase, 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. Success returns a receipt; verify via wiki_read_page(event_path). Do not require reading log.md. wiki_read_page accepts optional tail_bytes for browsing oversized pages.
+`wiki_capture` kind is `task | idea | bug | note`. Captures append to
+`raw/transcripts/`. Verify its returned `path` with `wiki_read_page`.
+`wiki_log_append` is append-only; verify its `event_path` with `wiki_read_page`.
+Use `tail_bytes` for large pages.
 ### Sensitive Content
-Never send credentials, API keys, auth tokens, passwords, or PII. Redact sensitive values using [REDACTED:<kind>] (e.g. [REDACTED:token]) before writing.
+Never send secrets or personal information. Use `[REDACTED:<kind>]`.
 <!-- 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.
-## Canonical Paths
+## Drift and Canonical Paths
-- Full skill (logical): invoke `/using-skillwiki` or read the installed plugin skill at `<plugin-root>/using-skillwiki/SKILL.md` (repository source: `packages/skills/using-skillwiki/SKILL.md`)
-- Vault schema: `SCHEMA.md` at the vault root (run `skillwiki path` to resolve)
-- Frontier agents (`proj-work`, `proj-decide`): plugin-root `agents/<name>.md` with `model: inherit` — refresh with the active plugin channel (`grok plugin update skillwiki` on Grok)
+If `skillwiki doctor` reports a newer version, invoke `using-skillwiki` again.
+The full source skill is `packages/skills/using-skillwiki/SKILL.md`; resolve the
+vault with `skillwiki path`. Frontier project agents are installed under the
+plugin root with `model: inherit`.