skillwiki 0.10.104 → 0.10.106

package/dist/{chunk-XYXTV2YD.js → chunk-DTTKCCQ4.js}

@@ -3,11 +3,11 @@ import {
   ROOT_INDEX_SECTION_ORDER,
   atomicWriteText,
   buildRootIndexUniverse
-} from "./chunk-KDH352MC.js";
+} from "./chunk-HMHMCPCE.js";
 import {
   err,
   ok
-} from "./chunk-QM64LUEY.js";
+} from "./chunk-GJC2CI3W.js";
 
 // src/utils/index-projection.ts
 import { readFile } from "fs/promises";

package/dist/{chunk-QM64LUEY.js → chunk-GJC2CI3W.js}

@@ -161,6 +161,7 @@ var TypedKnowledgeSchema = z.object({
   }
 });
 var sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
+var identityToken = z.string().min(1).max(128).regex(/^[a-zA-Z0-9_.-]+$/, "must be bounded alphanumeric token with _.-");
 var RawSourceSchema = z.object({
   title: z.string().min(1).optional(),
   source_url: z.string().nullable(),
@@ -170,7 +171,10 @@ var RawSourceSchema = z.object({
   sha256: sha256Hex.optional(),
   project: wikilink.optional(),
   work_item: wikilink.optional(),
-  kind: z.enum(["postmortem", "session-log", "meeting-notes", "other", "idea", "bug", "task", "note"]).optional()
+  kind: z.enum(["postmortem", "session-log", "meeting-notes", "other", "idea", "bug", "task", "note"]).optional(),
+  host: identityToken.optional(),
+  agent_role: identityToken.optional(),
+  agent_id: identityToken.optional()
 }).superRefine((v, ctx) => {
   if (v.work_item !== void 0 && (v.project === void 0 || v.kind === void 0)) {
     ctx.addIssue({ code: z.ZodIssueCode.custom, message: "project and kind are required when work_item is set" });
@@ -201,6 +205,9 @@ var WorkItemSchema = z.object({
   parent: wikilink.optional(),
   related: z.array(wikilink).optional(),
   sources: z.array(z.string()).optional(),
+  host: identityToken.optional(),
+  agent_role: identityToken.optional(),
+  agent_id: identityToken.optional(),
   post_release_verification: PostReleaseVerificationSchema.optional()
 }).superRefine((v, ctx) => {
   if (v.status === "completed" && !v.completed) {

package/dist/{chunk-KDH352MC.js → chunk-HMHMCPCE.js}

@@ -8,7 +8,7 @@ import {
   ok,
   scanSensitiveContent,
   scanVault
-} from "./chunk-QM64LUEY.js";
+} from "./chunk-GJC2CI3W.js";
 
 // src/utils/atomic-write.ts
 import { randomBytes } from "crypto";

package/dist/{chunk-F5GFUYPF.js → chunk-JCDAEZVD.js}

@@ -6,7 +6,7 @@ import {
   readPage,
   scanSensitiveContent,
   splitFrontmatter
-} from "./chunk-QM64LUEY.js";
+} from "./chunk-GJC2CI3W.js";
 
 // src/utils/vault-path-safety.ts
 import { lstatSync, realpathSync } from "fs";

package/dist/{chunk-PVIOU7BN.js → chunk-PGD3J2GE.js}

@@ -2,7 +2,7 @@
 import {
   atomicWriteText,
   buildRootIndexUniverse
-} from "./chunk-KDH352MC.js";
+} from "./chunk-HMHMCPCE.js";
 import {
   authorizeRawOperation,
   buildSourceReferenceIndex,
@@ -22,7 +22,7 @@ import {
   resolveExistingRegularFileInsideVault,
   stripFencedBlocks,
   writeLogEvent
-} from "./chunk-F5GFUYPF.js";
+} from "./chunk-JCDAEZVD.js";
 import {
   ExitCode,
   FleetManifestSchema,
@@ -41,7 +41,7 @@ import {
   scanVault,
   splitFrontmatter,
   vaultIoConcurrency
-} from "./chunk-QM64LUEY.js";
+} from "./chunk-GJC2CI3W.js";
 
 // src/utils/managed-write-preflight.ts
 import { existsSync as existsSync11 } from "fs";

package/dist/{chunk-H42EY6E7.js → chunk-QU2IXZRN.js}

@@ -8,7 +8,7 @@ import {
   readLogEvents,
   resolveExistingRegularFileInsideVault,
   writeLogEvent
-} from "./chunk-F5GFUYPF.js";
+} from "./chunk-JCDAEZVD.js";
 import {
   ExitCode,
   RawSourceSchema,
@@ -19,7 +19,7 @@ import {
   scanSensitiveContent,
   scanVault,
   splitFrontmatter
-} from "./chunk-QM64LUEY.js";
+} from "./chunk-GJC2CI3W.js";
 
 // src/commands/sources.ts
 import { readFile as readFile4 } from "fs/promises";

package/dist/{chunk-2BPOEEMW.js → chunk-Z4NCF6K6.js}

@@ -6,7 +6,7 @@ import {
 import {
   renderRootIndex,
   writeRootIndexProjection
-} from "./chunk-XYXTV2YD.js";
+} from "./chunk-DTTKCCQ4.js";
 import {
   CONFIG_KEYS,
   VAULT_HYGIENE_GENERATED_COMMIT_PATHS,
@@ -40,11 +40,11 @@ import {
   snapshotterAliasForLocalHost,
   toUndirectedWeighted,
   writeDotenv
-} from "./chunk-PVIOU7BN.js";
+} from "./chunk-PGD3J2GE.js";
 import {
   atomicWriteText,
   prepareTypedPage
-} from "./chunk-KDH352MC.js";
+} from "./chunk-HMHMCPCE.js";
 import {
   applySourceCompileClaim,
   applySourceCompilePublished,
@@ -57,11 +57,11 @@ import {
   planSourceCompileRelease,
   planSourceReview,
   runSourcesPending
-} from "./chunk-H42EY6E7.js";
+} from "./chunk-QU2IXZRN.js";
 import {
   eventPathFor,
   writeLogEvent
-} from "./chunk-F5GFUYPF.js";
+} from "./chunk-JCDAEZVD.js";
 import {
   CompoundSchema,
   ExitCode,
@@ -82,7 +82,7 @@ import {
   scanVault,
   splitFrontmatter,
   systemdPropertyFor
-} from "./chunk-QM64LUEY.js";
+} from "./chunk-GJC2CI3W.js";
 
 // src/commands/log-append.ts
 import { readFile, stat } from "fs/promises";
@@ -6606,7 +6606,7 @@ async function runQuery(input) {
   }
   let pendingSources;
   if (input.includePending) {
-    const { runSourcesPending: runSourcesPending2 } = await import("./sources-OSGKH6KN.js");
+    const { runSourcesPending: runSourcesPending2 } = await import("./sources-QTQSZMST.js");
     const pending = await runSourcesPending2({
       vault: input.vault,
       match: input.text,

package/dist/cli.js

@@ -63,7 +63,7 @@ import {
   snapshotterHealthChecks,
   upsertIndexEntry,
   vectorIndexStatus
-} from "./chunk-2BPOEEMW.js";
+} from "./chunk-Z4NCF6K6.js";
 import {
   normalizeDistTag,
   readCache,
@@ -76,7 +76,7 @@ import {
   UNMANAGED_START,
   renderRootIndex,
   writeRootIndexProjection
-} from "./chunk-XYXTV2YD.js";
+} from "./chunk-DTTKCCQ4.js";
 import {
   FLEET_REL_PATH,
   REDACTED_MALFORMED_REFERENCE,
@@ -168,12 +168,12 @@ import {
   supersedeStaleReviewRequiredJournals,
   taxonomyCommentForPage,
   writeDotenv
-} from "./chunk-PVIOU7BN.js";
+} from "./chunk-PGD3J2GE.js";
 import {
   assertTargetInsideVault,
   atomicWriteText,
   prepareTypedPage
-} from "./chunk-KDH352MC.js";
+} from "./chunk-HMHMCPCE.js";
 import {
   applySourceDisposition,
   decodeSourceActionApproval,
@@ -181,7 +181,7 @@ import {
   inventorySources,
   planSourceDisposition,
   runSourcesPending
-} from "./chunk-H42EY6E7.js";
+} from "./chunk-QU2IXZRN.js";
 import {
   authorizeRawOperation,
   buildSourceReferenceIndex,
@@ -198,7 +198,7 @@ import {
   resolveExistingRegularFileInsideVault,
   validateLogEvent,
   writeLogEvent
-} from "./chunk-F5GFUYPF.js";
+} from "./chunk-JCDAEZVD.js";
 import {
   ExitCode,
   MetaSchema,
@@ -219,7 +219,7 @@ import {
   scanVault,
   splitFrontmatter,
   vaultIoConcurrency
-} from "./chunk-QM64LUEY.js";
+} from "./chunk-GJC2CI3W.js";
 
 // src/cli.ts
 import { join as join45 } from "path";
@@ -4117,7 +4117,7 @@ ${fmRewritten}
   }
   let indexUpdated = false;
   if (!isRaw) {
-    const { renderRootIndex: renderRootIndex2, writeRootIndexProjection: writeRootIndexProjection2 } = await import("./index-projection-6OHDINHT.js");
+    const { renderRootIndex: renderRootIndex2, writeRootIndexProjection: writeRootIndexProjection2 } = await import("./index-projection-ESBJOBS7.js");
     const before = await readFile8(join20(input.vault, "index.md"), "utf8").catch(() => "");
     const fullTarget = relPath.replace(/\.md$/, "");
     const bare = fullTarget.split("/").pop() ?? fullTarget;
@@ -4240,7 +4240,7 @@ async function runRemove(input) {
   if (relPath.endsWith(".md") && !relPath.startsWith("raw/")) {
     const { readFile: readFile24 } = await import("fs/promises");
     const { join: pathJoin } = await import("path");
-    const { renderRootIndex: renderRootIndex2, writeRootIndexProjection: writeRootIndexProjection2 } = await import("./index-projection-6OHDINHT.js");
+    const { renderRootIndex: renderRootIndex2, writeRootIndexProjection: writeRootIndexProjection2 } = await import("./index-projection-ESBJOBS7.js");
     const before = await readFile24(pathJoin(input.vault, "index.md"), "utf8").catch(() => "");
     const fullTarget = relPath.replace(/\.md$/, "");
     const bare = fullTarget.split("/").pop() ?? fullTarget;
@@ -11207,7 +11207,7 @@ async function emitManagedVaultWrite(vault, command, mutate, opts) {
   if (dirty) {
     return emit(dirty, void 0, { postCommit: false });
   }
-  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-ATDFVLJV.js");
+  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-AYD3CJYD.js");
   const run = await runManagedWriteTransaction2({
     vault,
     command,

package/dist/{index-projection-6OHDINHT.js → index-projection-ESBJOBS7.js}

@@ -4,9 +4,9 @@ import {
   UNMANAGED_START,
   renderRootIndex,
   writeRootIndexProjection
-} from "./chunk-XYXTV2YD.js";
-import "./chunk-KDH352MC.js";
-import "./chunk-QM64LUEY.js";
+} from "./chunk-DTTKCCQ4.js";
+import "./chunk-HMHMCPCE.js";
+import "./chunk-GJC2CI3W.js";
 export {
   UNMANAGED_END,
   UNMANAGED_START,

package/dist/{managed-write-preflight-ATDFVLJV.js → managed-write-preflight-AYD3CJYD.js}

@@ -6,10 +6,10 @@ import {
   runManagedWritePeerGate,
   runManagedWritePreflight,
   runManagedWriteTransaction
-} from "./chunk-PVIOU7BN.js";
-import "./chunk-KDH352MC.js";
-import "./chunk-F5GFUYPF.js";
-import "./chunk-QM64LUEY.js";
+} from "./chunk-PGD3J2GE.js";
+import "./chunk-HMHMCPCE.js";
+import "./chunk-JCDAEZVD.js";
+import "./chunk-GJC2CI3W.js";
 export {
   DEFAULT_MANAGED_WRITE_WAIT_MS,
   MANAGED_WRITE_POLL_INTERVAL_MS,

package/dist/skillwiki-mcp.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-2BPOEEMW.js";
+} from "./chunk-Z4NCF6K6.js";
 import "./chunk-7I2TPIV5.js";
-import "./chunk-XYXTV2YD.js";
-import "./chunk-PVIOU7BN.js";
-import "./chunk-KDH352MC.js";
-import "./chunk-H42EY6E7.js";
-import "./chunk-F5GFUYPF.js";
-import "./chunk-QM64LUEY.js";
+import "./chunk-DTTKCCQ4.js";
+import "./chunk-PGD3J2GE.js";
+import "./chunk-HMHMCPCE.js";
+import "./chunk-QU2IXZRN.js";
+import "./chunk-JCDAEZVD.js";
+import "./chunk-GJC2CI3W.js";
 
 // src/mcp-entry.ts
 runSkillwikiMcpStdio().catch((error) => {

package/dist/sources-QTQSZMST.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import {
+  runSourcesPending
+} from "./chunk-QU2IXZRN.js";
+import "./chunk-JCDAEZVD.js";
+import "./chunk-GJC2CI3W.js";
+export {
+  runSourcesPending
+};

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

@@ -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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.104",
+  "version": "0.10.106",
   "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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.104",
+  "version": "0.10.106",
   "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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.104",
+  "version": "0.10.106",
   "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

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

package/skills/scripts/check_readiness.py

@@ -16,12 +16,24 @@ from typing import Mapping
 PRODUCTION_MCP_URL = "https://wiki.karldigi.dev/mcp"
 TOKEN_ENV = "SKILLWIKI_MCP_TOKEN"
 URL_ENV = "SKILLWIKI_MCP_URL"
+HEADLESS_OAUTH_LOOPBACK_WARNING = (
+    "headless_oauth_loopback: SSH is a hint that the operator browser may not "
+    "be this host. MCP OAuth loopback (localhost callback) binds on this host, "
+    "so an operator browser on another machine cannot finish it. Set "
+    f"{TOKEN_ENV} via process env, host Configure, or skillwiki connect "
+    "--from-file. Do not click the SkillWiki OAuth login on another machine."
+)
 
 
 def _strip(value: str | None) -> str:
     return (value or "").strip()
 
 
+def _ssh_remote_session(source: Mapping[str, str]) -> bool:
+    """SSH is a hint that the operator browser may not be this host (callback would bind here)."""
+    return bool(_strip(source.get("SSH_CONNECTION")) or _strip(source.get("SSH_TTY")))
+
+
 def probe(environ: Mapping[str, str] | None = None) -> dict:
     source = os.environ if environ is None else environ
     token = _strip(source.get(TOKEN_ENV))
@@ -30,6 +42,8 @@ def probe(environ: Mapping[str, str] | None = None) -> dict:
     reasons: list[str] = []
 
     if not token:
+        if _ssh_remote_session(source):
+            warnings.append(HEADLESS_OAUTH_LOOPBACK_WARNING)
         return {
             "status": "missing_prereq",
             "reasons": [f"{TOKEN_ENV} unset"],

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

@@ -21,6 +21,7 @@ Unknown-agent HTTP MCP setup. Use when the client has no SkillWiki plugin and no
 - Do **not** use 云盘 / Drive / CloudStorage as the secret path. Only a chat-attached file reaches the VM.
 - Missing `WIKI_PATH` is expected on an MCP-only leaf. Handshake pass is done.
 - Do **not** instruct the operator to paste the bearer into the chat transcript.
+- Do **not** tell the operator to complete SkillWiki OAuth login in a laptop browser for an SSH/remote host. Loopback `http://localhost:<port>/callback` binds on the remote client; headed vs headless is not the discriminator, and SSH is a hint that the operator browser may not be this host. Use `skillwiki connect --from-file`.
 
 ## Paste-once prompt
 

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

@@ -14,8 +14,9 @@ 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.
+- **Operator browser not on this host (SSH):** installed `.mcp.json` already sends `Authorization: Bearer ${SKILLWIKI_MCP_TOKEN}`. If the token is missing, a 401 may start MCP OAuth with `http://localhost:<port>/callback` on this host. MCP OAuth loopback binds on this host; headed vs headless is not the discriminator (DISPLAY, VNC, or local Chrome cannot complete loopback when the operator browser is on another machine), and SSH is a hint that the operator browser may not be this host. If `check_readiness.py` `warnings` contain `headless_oauth_loopback`, or the host shows an OAuth login URL over SSH: stop. Ask the operator to set `SKILLWIKI_MCP_TOKEN` (process env, Configure, or `skillwiki connect --from-file`). Do not tell the operator to click the login link on another machine. If SkillWiki tools are already connected, continue.
 - 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).
 - `in_sync` means the probe has a usable URL/token decision.
@@ -30,12 +31,14 @@ Remotes still on a pre-HTTP-MCP plugin or CLI must upgrade the plugin channel (a
 
 ## Writes
 
-On leaf hosts, wiki captures go through MCP. Do **not** write `raw/transcripts/` or `log.md` as local files.
+Local Mac coding agents with a valid bearer are managed read-write peers through advertised MCP tools. Remote and other agents are read-mostly; they write only when explicitly authorized and the advertised tool permits the target. 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.
+   - 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. For work-item `spec.md` or goal-plan `plan.md`, pass optional `agent_role` / `agent_id`; the server stamps authenticated `host` and supplied agent identity into frontmatter. Supported workspace paths are: `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.
@@ -44,8 +47,8 @@ On leaf hosts, wiki captures go through MCP. Do **not** write `raw/transcripts/`
 
 Local `~/wiki` (or `skillwiki path`) is fine for reads. MCP read tools are optional. Prefer ordinary file reads of the local mirror. Frozen-leaf agents should use HTTP `wiki_sources_pending`, `wiki_lint_summary`, `wiki_stale`, `wiki_compile_status`, and `wiki_reviews` instead of local CLI commands when those tools are advertised.
 
-`wiki_query` is typed knowledge only unless `scope` is `work` or `all`. For queued work, doctor, plugin-drift, or MCP diagnose questions, call `wiki_context` first (active_work) or pass `scope: "work"` / `"all"`. Do not treat a top typed packet hit as the live work queue.
+`wiki_query` is typed knowledge only unless `scope` is `work` or `all`. For recent progress, key projects, or to-dos, feature-detect and call `wiki_progress`; apply `project`, `host`, or `agent_role` filters when requested, and present `recent_progress`, `key_projects`, and `todos` as complete bullet lists. For queued work, doctor, plugin-drift, or MCP diagnose questions, call `wiki_context` first (active_work) or pass `scope: "work"` / `"all"`. Do not treat a top typed packet hit as the live work queue.
 
 ## Errors
 
-Report handshake, capture, and append failures literally. If tools are missing after a 401 or `missing_prereq`, stop and tell the operator to set `SKILLWIKI_MCP_TOKEN` via process env, host Configure, or `skillwiki connect --from-file` (unknown agents; never paste-into-chat), run `grok plugin update skillwiki`, and start a new session. Do not fall back to local `raw/transcripts/` writes.
+Report handshake, capture, and append failures literally. If tools are missing after a 401 or `missing_prereq`, stop and tell the operator to set `SKILLWIKI_MCP_TOKEN` via process env, host Configure, or `skillwiki connect --from-file` (unknown agents; never paste-into-chat), run `grok plugin update skillwiki`, and start a new session. Over SSH, treat an OAuth login URL the same way: report `headless_oauth_loopback` and stop. Do not fall back to local `raw/transcripts/` writes.

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

@@ -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, append, or progress query: `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. Local Mac coding agents with a valid bearer are managed read-write peers through advertised MCP tools. Remote and other agents are read-mostly; they write only when explicitly authorized and the advertised MCP tool permits the target. 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.
+
+### Progress Queries
+Use `wiki_progress` for recent progress, key projects, or to-dos. Apply requested project, host, or agent-role filters and answer with complete bullet lists.
 
 ### 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/skills/wiki-query/SKILL.md

@@ -14,6 +14,7 @@ Standard four reads (SCHEMA, index, log, project context if applicable).
 0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
 1. **Determine scope.** Ask the user once if ambiguous: vault | current project | project+concepts.
    - Ordinary questions are typed-knowledge-first. Run `skillwiki query "<text>" [vault]` without widening into raw captures. Default ranking is 4-signal only. Optional `skillwiki query "<text>" --hybrid` RRF-fuses that ranking with a rebuildable TF-IDF cache (`skillwiki vectors rebuild`); if the cache is missing, stop and rebuild instead of silently falling back.
+   - Recent progress, key-project, or to-do questions use the MCP `wiki_progress` tool when advertised. Apply requested `project`, `host`, or `agent_role` filters and render all three result sections as complete bullet lists.
    - Setup, MCP, doctor, plugin-drift, or "open work" questions are not typed-knowledge searches. Call `wiki_context` (active_work) or `skillwiki query "<text>" --scope work` / `--scope all`. Default typed query never ranks `projects/*/work`.
    - Explicit freshness language — `new`, `recent`, `fresh`, `clipped`, `raw`, `pending`, `undigested`, `unprocessed`, `not yet ingested`, or `not yet integrated` — requests the pending evidence channel. Run `skillwiki sources pending [vault]` for inventory and `skillwiki query "<text>" [vault] --include-pending` for synthesis support.
 2. **Refresh graph.** If `.skillwiki/graph.json` is missing or older than 24h: `skillwiki graph build <vault>`.

package/skills/skillwiki-connect/SKILL.md

@@ -21,6 +21,7 @@ Unknown-agent HTTP MCP setup. Use when the client has no SkillWiki plugin and no
 - Do **not** use 云盘 / Drive / CloudStorage as the secret path. Only a chat-attached file reaches the VM.
 - Missing `WIKI_PATH` is expected on an MCP-only leaf. Handshake pass is done.
 - Do **not** instruct the operator to paste the bearer into the chat transcript.
+- Do **not** tell the operator to complete SkillWiki OAuth login in a laptop browser for an SSH/remote host. Loopback `http://localhost:<port>/callback` binds on the remote client; headed vs headless is not the discriminator, and SSH is a hint that the operator browser may not be this host. Use `skillwiki connect --from-file`.
 
 ## Paste-once prompt
 

package/skills/skillwiki-mcp/SKILL.md

@@ -14,8 +14,9 @@ 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.
+- **Operator browser not on this host (SSH):** installed `.mcp.json` already sends `Authorization: Bearer ${SKILLWIKI_MCP_TOKEN}`. If the token is missing, a 401 may start MCP OAuth with `http://localhost:<port>/callback` on this host. MCP OAuth loopback binds on this host; headed vs headless is not the discriminator (DISPLAY, VNC, or local Chrome cannot complete loopback when the operator browser is on another machine), and SSH is a hint that the operator browser may not be this host. If `check_readiness.py` `warnings` contain `headless_oauth_loopback`, or the host shows an OAuth login URL over SSH: stop. Ask the operator to set `SKILLWIKI_MCP_TOKEN` (process env, Configure, or `skillwiki connect --from-file`). Do not tell the operator to click the login link on another machine. If SkillWiki tools are already connected, continue.
 - 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).
 - `in_sync` means the probe has a usable URL/token decision.
@@ -30,12 +31,14 @@ Remotes still on a pre-HTTP-MCP plugin or CLI must upgrade the plugin channel (a
 
 ## Writes
 
-On leaf hosts, wiki captures go through MCP. Do **not** write `raw/transcripts/` or `log.md` as local files.
+Local Mac coding agents with a valid bearer are managed read-write peers through advertised MCP tools. Remote and other agents are read-mostly; they write only when explicitly authorized and the advertised tool permits the target. 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.
+   - 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. For work-item `spec.md` or goal-plan `plan.md`, pass optional `agent_role` / `agent_id`; the server stamps authenticated `host` and supplied agent identity into frontmatter. Supported workspace paths are: `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.
@@ -44,8 +47,8 @@ On leaf hosts, wiki captures go through MCP. Do **not** write `raw/transcripts/`
 
 Local `~/wiki` (or `skillwiki path`) is fine for reads. MCP read tools are optional. Prefer ordinary file reads of the local mirror. Frozen-leaf agents should use HTTP `wiki_sources_pending`, `wiki_lint_summary`, `wiki_stale`, `wiki_compile_status`, and `wiki_reviews` instead of local CLI commands when those tools are advertised.
 
-`wiki_query` is typed knowledge only unless `scope` is `work` or `all`. For queued work, doctor, plugin-drift, or MCP diagnose questions, call `wiki_context` first (active_work) or pass `scope: "work"` / `"all"`. Do not treat a top typed packet hit as the live work queue.
+`wiki_query` is typed knowledge only unless `scope` is `work` or `all`. For recent progress, key projects, or to-dos, feature-detect and call `wiki_progress`; apply `project`, `host`, or `agent_role` filters when requested, and present `recent_progress`, `key_projects`, and `todos` as complete bullet lists. For queued work, doctor, plugin-drift, or MCP diagnose questions, call `wiki_context` first (active_work) or pass `scope: "work"` / `"all"`. Do not treat a top typed packet hit as the live work queue.
 
 ## Errors
 
-Report handshake, capture, and append failures literally. If tools are missing after a 401 or `missing_prereq`, stop and tell the operator to set `SKILLWIKI_MCP_TOKEN` via process env, host Configure, or `skillwiki connect --from-file` (unknown agents; never paste-into-chat), run `grok plugin update skillwiki`, and start a new session. Do not fall back to local `raw/transcripts/` writes.
+Report handshake, capture, and append failures literally. If tools are missing after a 401 or `missing_prereq`, stop and tell the operator to set `SKILLWIKI_MCP_TOKEN` via process env, host Configure, or `skillwiki connect --from-file` (unknown agents; never paste-into-chat), run `grok plugin update skillwiki`, and start a new session. Over SSH, treat an OAuth login URL the same way: report `headless_oauth_loopback` and stop. Do not fall back to local `raw/transcripts/` writes.

package/skills/using-skillwiki/activation.md

@@ -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, append, or progress query: `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. Local Mac coding agents with a valid bearer are managed read-write peers through advertised MCP tools. Remote and other agents are read-mostly; they write only when explicitly authorized and the advertised MCP tool permits the target. 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.
+
+### Progress Queries
+Use `wiki_progress` for recent progress, key projects, or to-dos. Apply requested project, host, or agent-role filters and answer with complete bullet lists.
 
 ### 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/wiki-query/SKILL.md

@@ -14,6 +14,7 @@ Standard four reads (SCHEMA, index, log, project context if applicable).
 0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
 1. **Determine scope.** Ask the user once if ambiguous: vault | current project | project+concepts.
    - Ordinary questions are typed-knowledge-first. Run `skillwiki query "<text>" [vault]` without widening into raw captures. Default ranking is 4-signal only. Optional `skillwiki query "<text>" --hybrid` RRF-fuses that ranking with a rebuildable TF-IDF cache (`skillwiki vectors rebuild`); if the cache is missing, stop and rebuild instead of silently falling back.
+   - Recent progress, key-project, or to-do questions use the MCP `wiki_progress` tool when advertised. Apply requested `project`, `host`, or `agent_role` filters and render all three result sections as complete bullet lists.
    - Setup, MCP, doctor, plugin-drift, or "open work" questions are not typed-knowledge searches. Call `wiki_context` (active_work) or `skillwiki query "<text>" --scope work` / `--scope all`. Default typed query never ranks `projects/*/work`.
    - Explicit freshness language — `new`, `recent`, `fresh`, `clipped`, `raw`, `pending`, `undigested`, `unprocessed`, `not yet ingested`, or `not yet integrated` — requests the pending evidence channel. Run `skillwiki sources pending [vault]` for inventory and `skillwiki query "<text>" [vault] --include-pending` for synthesis support.
 2. **Refresh graph.** If `.skillwiki/graph.json` is missing or older than 24h: `skillwiki graph build <vault>`.

package/templates/SCHEMA.md

@@ -92,6 +92,9 @@ created: YYYY-MM-DD     # when capture was written
 ingested:          # filled by ingest pipeline (empty at creation)
 kind:             # idea | bug | task | note | other
 project:          # optional: "[[slug]]" for cross-reference
+host:             # optional: host identity token (stamped by MCP writer)
+agent_role:       # optional: agent role identity token
+agent_id:         # optional: agent identity token
 ---
 ```
 
@@ -101,6 +104,9 @@ project:          # optional: "[[slug]]" for cross-reference
 - `ingested`: Date processed into typed knowledge. **Empty at creation.** Filled by `wiki-ingest`, `wiki-crystallize`.
 - `kind`: Capture type. Affects dev-loop routing (`bug`/`task` → work items; `idea` → knowledge development).
 - `project`: Optional project cross-reference. Enables `provenance_projects:` auto-linking.
+- `host`: Optional host identity token (e.g. `macos-dev`, `sg01`). Stamped by MCP writer from authenticated identity.
+- `agent_role`: Optional agent role identity token (e.g. `researcher`, `worker`, `reviewer`).
+- `agent_id`: Optional specific agent instance identifier.
 
 ### vs Ingested Sources
 

package/dist/sources-OSGKH6KN.js

@@ -1,9 +0,0 @@
-#!/usr/bin/env node
-import {
-  runSourcesPending
-} from "./chunk-H42EY6E7.js";
-import "./chunk-F5GFUYPF.js";
-import "./chunk-QM64LUEY.js";
-export {
-  runSourcesPending
-};