skillwiki 0.10.113 → 0.10.115

package/docs/clip-outbox.md

@@ -1,5 +1,9 @@
 # Clip-outbox worker and attended migration
 
+Agents asked to save a generated image or attachment should follow
+`packages/skills/using-skillwiki/references/save-attachments.md`. This file is
+the operator enablement runbook; it is not an unattended enablement checklist.
+
 The channel remains disabled by default. Installing or updating npm ships the
 worker and launchd template; it does not change `clip_outbox.enabled`, load a
 job, import browser settings, or enable wiki-push. `skillwiki doctor` reports

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.113",
+  "version": "0.10.115",
   "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.113",
+  "version": "0.10.115",
   "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.113",
+  "version": "0.10.115",
   "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/agents/wiki-add-task.md

@@ -13,6 +13,7 @@ You are a quick-capture agent specializing in recording ad-hoc captures destined
 - **Idea capture.** Dev-loop spawns you to log an idea surfaced during maintenance.
 - **Bug logging.** A lint/audit cycle found something worth tracking as a bug.
 - **Task note.** Quick note that should persist as a raw transcript for future processing.
+- **Not for generated images or binary attachments.** Follow `using-skillwiki/references/save-attachments.md`.
 
 **Your Core Responsibilities:**
 1. Parse text, type, and optional project from the task prompt
@@ -77,3 +78,4 @@ Return:
 - Creating a full work item (that's proj-work's job)
 - Writing to Layer 2 or Layer 3 locations (captures are Layer 1)
 - Writing live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets to the vault
+- Saving image bytes except via `using-skillwiki/references/save-attachments.md`

package/skills/agents/wiki-ingest.md

@@ -14,6 +14,7 @@ You are a vault ingestion specialist converting source material (URLs and readab
 - **File ingestion.** Local files need to be captured as raw sources and distilled into concept pages.
 - **Batch ingestion.** Multiple sources to process through deterministic raw capture and shared publication.
 - **Raw promotion.** A raw/transcripts/ capture is ready for promotion to a typed-knowledge page.
+- **Not for generated-image ingress.** Follow `using-skillwiki/references/save-attachments.md`. Do not `skillwiki ingest` the binary.
 
 **Your Core Responsibilities:**
 1. Guard: run `skillwiki fetch-guard <url>` for URL sources
@@ -73,3 +74,4 @@ Return:
 - Writing `[[wikilinks]]` to nonexistent pages — verify first
 - Writing raw ephemeral data to cloud-mounted wiki paths
 - Writing live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets to the vault
+- Ingesting image bytes or treating a host-local image path as a portable attachment

package/skills/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: skillwiki-mcp
-description: Use when capturing a note, idea, or bug, appending log.md, or using wiki MCP tools. Writes via wiki_capture / wiki_log_append; never local raw/transcripts.
+description: "Use when capturing a note, idea, or bug, appending log.md, or using wiki MCP tools. Never local transcripts. Images: clip-outbox."
 ---
 
 # SkillWiki HTTP MCP
@@ -9,6 +9,8 @@ Use this skill to capture a note, idea, bug, or task into the wiki, append `log.
 
 When this MCP namespace is loaded and available, it wins over wiki-add-task local-write steps for capture intents.
 
+HTTP MCP captures Markdown only. There is no binary-upload MCP tool. Generated images and attachments use `using-skillwiki/references/save-attachments.md`.
+
 SkillWiki captures are HTTP MCP only (`type: http`). Claude/Grok use `SKILLWIKI_MCP_URL` as an optional override and otherwise default to `https://wiki.karldigi.dev/mcp`. Every host requires an operator-provided bearer as `SKILLWIKI_MCP_TOKEN` before MCP load. Do not start a local stdio `skillwiki mcp` / `skillwiki-mcp` server for captures.
 
 ## First-run readiness

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

@@ -1,12 +1,15 @@
 ---
 name: using-skillwiki
-description: Invoke for vault, wiki, or SkillWiki setup. Maps skills, workflow profiles, and vault routing.
+description: "Invoke for vault or wiki work: skill map, workflow profiles, routing, generated images, screenshots, design mockups, attachments."
 ---
 *Note: If executing as a background subagent, skip this skill section.*
 
 # using-skillwiki
 You have skillwiki — a project-aware Karpathy-style knowledge base for agent harnesses.
 
+## Images and attachments
+Generated images, screenshots, design mockups, attachments, saving pictures, and Markdown image rendering use `using-skillwiki/references/save-attachments.md`. HTTP MCP has no binary-upload tool; that is not an unsupported-image conclusion.
+
 ## Last Hook Gate (SessionStart)
 
 This skill is activated by the plugin during startup and clear lifecycle
@@ -55,6 +58,7 @@ Invoke a skillwiki skill when the user:
 - Mentions crystallizing a session into a note
 - Talks about project workspaces, ADRs, or distillation
 - Wants to quickly capture an idea, bug, task, or note without interrupting their workflow
+- Wants to save a generated image, screenshot, design mockup, attachment, or make a Markdown image portable in the wiki
 - Needs unknown-agent HTTP MCP connect (CLI + dotenv; no plugin/connector)
 - Wants to archive or clean up old vault pages
 - Wants to hard-delete a vault path without snapshot resurrection (`wiki-remove`)
@@ -174,6 +178,7 @@ If the vault has `.WIKI_GIT_FROZEN`:
 | Close or mutate a work item (`projects/*/work/**`, `knowledge.md`) | Conditional | If live MCP tools include `wiki_workitem_write`, mutate/close via MCP CAS; if absent, capture a close note via MCP `wiki_capture` or STOP. Never local-write. |
 | Save project workspace file (`architecture/`, `README.md`, `requirements/`, `compound/` — `.md` only) | Conditional | Via `wiki_workitem_write` CAS. Feature-detect: if the tool is absent or the deployed server predates the workspace-family allowlist (`PATH_DENIED`), STOP. Never rclone/wiki-push as a fallback writer. |
 | Publish typed Layer-2 page (`concepts/`, `queries/`, etc.) | Conditional | If live MCP tools include `wiki_page_publish`, publish via MCP CAS; if absent, STOP. Do not run local `skillwiki page publish`. |
+| Save generated image, screenshot, design mockup, or attachment | Conditional | Existing enabled clip-outbox only. See `using-skillwiki/references/save-attachments.md`. |
 | `wiki-sync` push/commit | **No** | Git fail-closed. GitHub is sg01 `wiki-snapshot`. |
 | Read local `~/wiki` | Yes | Mirror reads only |
 | `/wiki-add-task <text>` | You're in an interactive session on an authoring host | Creates `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md` with ad-hoc capture frontmatter |
@@ -245,7 +250,7 @@ for code changes.
 
 ## CLI Backbone
 All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, health reporting, and linting. Skills invoke it via Bash for the mechanical parts and use the active agent for the creative parts.
-Key CLI subcommands: `init`, `health`, `lint`, `config`, `doctor`, `connect`, `path`, `lang`, `install`, `fleet context`, `fleet validate`, `graph build`, `query`, `vectors rebuild`, `vectors status`, `sources pending`, `sources compile`, `sources review`, `sources reviews`, `sources disposition`, `sources dispose`, `archive`, `remove`, `drift`, `dedup`, `compound`, `tag-sync`, `tag reconcile`, `page publish`, `sync status`, `seed`, `stale`, `claim`, `claims audit`, `observe`, `canvas generate`, `mcp`, `mcp-auth`.
+Key CLI subcommands: `init`, `health`, `lint`, `config`, `doctor`, `connect`, `path`, `lang`, `install`, `fleet context`, `fleet validate`, `graph build`, `query`, `vectors rebuild`, `vectors status`, `sources pending`, `sources compile`, `sources review`, `sources reviews`, `sources disposition`, `sources dispose`, `archive`, `remove`, `drift`, `dedup`, `compound`, `tag-sync`, `tag reconcile`, `page publish`, `sync status`, `seed`, `stale`, `claim`, `claims audit`, `observe`, `canvas generate`, `mcp`, `mcp-auth`, `clip-outbox`.
 Optional read-only MCP (`skillwiki mcp`) exposes pending/compile/review list tools. Do not use MCP for compile claim, publish, or review writes.
 `skillwiki claim` binds a transcript to a work item only through an exact `raw/transcripts/...` path in `source:` / `sources:` / `closes:`. A `--project` that contradicts the capture's explicit project is rejected. `skillwiki stale --project` uses exact normalized slugs, not substring matching. `skillwiki claims audit` is the read-only integrity report for duplicate, malformed, dangling, cross-project, and unbacked claims; it never rewrites captures or work items.
 

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

@@ -17,6 +17,7 @@ Choose the matching installed skill:
   `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`.
+- Generated images, screenshots, design mockups, attachments, Markdown image saving: `using-skillwiki/references/save-attachments.md`. MCP has no binary-upload tool; that is not an unsupported-image conclusion.
 
 If routing is unclear, invoke `using-skillwiki` rather than guessing.
 

package/skills/skills/using-skillwiki/references/save-attachments.md

@@ -0,0 +1,129 @@
+# Save SkillWiki images and attachments
+
+Use this runbook when the user asks to save a generated image, screenshot,
+design mockup, attachment, picture, or Markdown image into the wiki.
+
+HTTP MCP Markdown capture and binary bundle transport are different supported
+capabilities. The connected MCP advertises no binary-upload tool. That is
+expected. It is not evidence that SkillWiki cannot save images.
+
+Do not invent commands. Confirm the live CLI before acting:
+
+```sh
+skillwiki --version
+skillwiki clip-outbox --help
+skillwiki clip-outbox status
+skillwiki doctor
+```
+
+Historical "planned" or "disabled by default" labels do not override the help
+and status of the installed CLI.
+
+## Live clip-outbox commands
+
+Quote these from current `skillwiki clip-outbox --help` (v0.10.113 source in
+`packages/cli/src/cli.ts`). Re-read help if a newer CLI disagrees.
+
+| Subcommand | Help text | Agent may run? |
+|---|---|---|
+| `status` | show whether the clip-outbox channel is configured | Yes |
+| `watch` | run the enabled dedicated outbox worker using macOS FSEvents | No, unless the user explicitly asks to operate that worker |
+| `mirror-watch` | copy admitted raw/articles and raw/assets from storage into the frozen mirror using MCP SSE | No, unless the user explicitly asks to operate that listener |
+| `install-or-migrate` | refresh the packaged launchd plist without enabling the channel | No, unless the user explicitly asks to operate infrastructure |
+
+Do not run `watch`, `mirror-watch`, or `install-or-migrate` unless the user explicitly asks to operate that infrastructure.
+
+`status` with the channel off prints `clip channel not configured` and
+`enabled: false`. `status` with the channel on prints
+`clip-outbox enabled root=<outbox> mode=event-watch` plus journal rows.
+
+Doctor clip rows on an MCP-only leaf print `MCP-only leaf — check skipped`.
+That host has Markdown MCP only. It is not a binary ingress.
+
+Operator enablement lives in `packages/cli/docs/clip-outbox.md`. Do not follow
+that file as an unattended enablement checklist.
+
+## Routing cases
+
+| Request | Host facts | Report and do |
+|---|---|---|
+| Generated PNG, screenshot, design mockup, or attachment | MCP has no binary-upload tool; `clip-outbox status` is enabled | Discover this route without a user hint. Stage the bundle in the dedicated outbox root from status. Never `~/wiki`. |
+| Same request | MCP-only leaf; doctor clip rows `MCP-only leaf — check skipped`; no supported binary ingress | Report that exact limitation. Do not rclone, copy credentials, write the frozen wiki, or invent an upload service. |
+| Same request | `clip channel not configured`, or doctor `production clip watcher not loaded and enabled` | Stop at that prerequisite. Do not set `clip_outbox.enabled`, load launchd, or run `install-or-migrate` / `watch` as a fallback. |
+| Journal `notify-pending`, or object receipts without `central-visible` | Transfer in flight | Report **transfer pending**, not complete. |
+| Existing central Markdown uses `/Users/...`, `file://`, or another host-local image path | Note is already in the wiki | That reference is not a portable attachment. |
+| Enabled outbox finishes | Journal `central-visible`; MCP `wiki_read_page` has `s3_verified=true`; mirror SHA-256 matches the original bytes | Report those verified stages. Keep image bytes. Expect a sibling `note.md`. |
+| Reader on another device | Visual check not done | Distinguish ordinary Markdown `![](url)` from Obsidian `![[raw/assets/...]]`. Do not claim rendering. |
+
+## Bundle layout
+
+Parse the outbox root from `skillwiki clip-outbox status` (`root=` in
+`humanHint`). The worker admits Markdown under `raw/articles/` and local
+binaries under `raw/assets/` of that dedicated vault. It is not `~/wiki`.
+
+Stage:
+
+```
+<root>/raw/assets/<slug>/<file>.png
+<root>/raw/articles/<slug>.md
+```
+
+The article must reference the image with a vault-relative embed or markdown
+image whose target is `raw/assets/...`. Supported image kinds are png, jpeg,
+gif, and webp. Host-absolute paths (`/Users/...`, `/home/...`, `file://`) are
+not portable and the localizer holds them as unsafe.
+
+Example article body:
+
+```markdown
+---
+source_url:
+ingested: YYYY-MM-DD
+kind: note
+---
+# Title
+
+![[raw/assets/<slug>/<file>.png]]
+```
+
+The worker localizes, seals snapshots outside raw, and preserves existing local
+asset paths. It does not rewrite the input article. Published keys include a
+date plus capture identity. It also uploads sibling
+`raw/assets/<captureId>/note.md` that embeds each asset. Never use a `.txt`
+sidecar as the only index.
+
+After central visibility, a maintained work item may cite the vault-relative
+embed through permitted Markdown MCP (`wiki_workitem_write`). That is still
+not a binary MCP upload.
+
+Leave completed raw captures immutable. Later results become a new capture or a
+permitted maintained work-item update.
+
+## Progress labels
+
+Use these labels. Do not collapse them into "saved".
+
+| Label | Evidence |
+|---|---|
+| local archive saved | Bytes written under the dedicated outbox `raw/articles/` and `raw/assets/` |
+| bundle staged | Journal `sealed` (snapshots under the configured state root) |
+| transfer acknowledged | Journal `assets-verified` / `article-verified` (create-only PUT receipts) |
+| centrally visible | Journal `central-visible` after the ready hint accounts for every path |
+| central note verified | MCP `wiki_read_page` on the article and `raw/assets/<captureId>/note.md` with `s3_verified=true` |
+| mirrored binary hash verified | Frozen-mirror file SHA-256 equals the original image. The worker never infers `mirrored`. |
+| reader rendering verified | A person checked display in a reader. Ordinary Markdown needs a resolvable URL; `![[raw/assets/...]]` needs a compatible resolver. |
+
+`notify-pending` means the ready hint is not yet adopted. A queued HTTP 202 is
+not central visibility.
+
+## Authority boundary
+
+Markdown writes stay on permitted MCP tools (`wiki_capture`,
+`wiki_log_append`, `wiki_workitem_write`, `wiki_page_publish`).
+
+Binary saving uses only an existing enabled clip-outbox ingress. Never write
+binaries into the frozen wiki, never `rclone` / wiki-push as a writer, never
+copy clip credentials, and never stand up another upload service.
+
+If the route is missing, disabled, or unauthorized, report that limitation and
+stop.

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

@@ -1,6 +1,6 @@
 ---
 name: wiki-add-task
-description: Capture ad-hoc ideas, bugs, tasks, or notes into the vault (HTTP MCP wiki_capture on leaf hosts; local raw/transcripts/ on authoring hosts).
+description: "Capture ideas, bugs, tasks, notes (MCP wiki_capture on leaf; authoring-host raw/transcripts). Images: clip-outbox."
 ---
 # wiki-add-task
 Capture ad-hoc ideas, bugs, tasks, and notes into the vault. Destination of captures remains vault `raw/transcripts/`. Entry points depend on host role and environment:
@@ -11,7 +11,7 @@ Capture ad-hoc ideas, bugs, tasks, and notes into the vault. Destination of capt
 | Filesystem drop | Hermes Agent compact mode on an authoring host | Fallback — create `.md` in `raw/transcripts/`, dev-loop discovers it |
 | Filesystem drop | Not in a Claude session (Obsidian, editor, sync) on an authoring host | Fallback — create a new `.md` file in `raw/transcripts/` using vault template; dev-loop discovers it on next cycle |
 | Dev-loop discovery | Automatic, next cycle (authoring-host / leftover-transition only) | Scans `raw/transcripts/` for new files since last cycle, surfaces as claimable work |
-**Path Rule:** Destination of captures is vault `raw/transcripts/` (Layer 1). Frozen-leaf hosts capture via MCP `wiki_capture` (server writes `raw/transcripts/` remotely); local file writes only occur on authoring hosts. Never capture under `projects/{slug}/raw/` — that violates SCHEMA.md Layer 1 immutability. Text captures stay in `raw/transcripts/`. If the capture includes images or other binaries, store those files under `raw/assets/` with a sibling Markdown note that embeds them; never use a .txt sidecar (such as `README.txt`) as the only index; Obsidian opens Markdown notes.
+**Path Rule:** Destination of captures is vault `raw/transcripts/` (Layer 1). Frozen-leaf hosts capture via MCP `wiki_capture` (server writes `raw/transcripts/` remotely); local file writes only occur on authoring hosts. Never capture under `projects/{slug}/raw/` — that violates SCHEMA.md Layer 1 immutability. Text captures stay in `raw/transcripts/`. Generated images and other binaries are not `wiki_capture` content and are not a local write into the frozen wiki. Follow `using-skillwiki/references/save-attachments.md`.
 ### Exception: Explicit project task requests
 When the user explicitly says "raise task to project X", "add a task for X", "create a feature request for X", or uses a directive structure like "raise task to {project} {description}", the intent is a **work item**, not a capture:
 | User wording | Action | Target |
@@ -26,6 +26,7 @@ This is NOT a violation of the rule below — explicit project task requests are
 - User provides a short text description and optionally a type tag.
 - **Precedence:** If SkillWiki MCP tools are available (`wiki_capture`), **skillwiki-mcp / wiki_capture wins**. Do not race to local writes. The local-write path in wiki-add-task is only when MCP is absent AND the host is an authoring host (not a frozen leaf).
 - **Do NOT activate** when the user says "raise task to project X" or "add work item to project X" — escalate to `proj-work` instead.
+- **Do NOT activate as the binary writer** for generated images, screenshots, design mockups, or attachments. Follow `using-skillwiki/references/save-attachments.md`.
 ## Output language
 Run `skillwiki lang` at the start. Entry prose and `--human` summaries use the resolved language. Frontmatter keys, file names, and structural markers stay English.
 ## Steps
@@ -120,6 +121,7 @@ Ad-hoc captures may omit `sha256`; omission does not grant mutation authority. O
 - Writing to any Layer 2 or Layer 3 location. Captures are Layer 1 (raw).
 - Writing live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets to the vault.
 - Indexing `raw/assets/` binaries with only a `.txt` sidecar.
+- Saving image bytes except via `using-skillwiki/references/save-attachments.md`.
 ## Filesystem drop (offline capture — authoring hosts only)
 When you're not in a Claude session on an authoring host, drop files directly into `raw/transcripts/`:
 1. Create a `.md` file in `raw/transcripts/` — name it descriptively (e.g., `2026-05-08-idea-fix-template.md`)

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

@@ -1,12 +1,13 @@
 ---
 name: wiki-ingest
-description: Convert URLs, files, or pasted text into typed-knowledge pages with raw provenance. Supports single and batch mode.
+description: "Convert URLs, files, or pasted text into typed pages with provenance. Images: clip-outbox, not binary ingest."
 ---
 # wiki-ingest
 ## When This Skill Activates
 - User shares a URL, paste, or local file to capture in the vault.
 - The output target is `entities/`, `concepts/`, `comparisons/`, or `queries/`.
 - A vault is resolvable (see step 0).
+- Generated images and attachments use `using-skillwiki/references/save-attachments.md`, not `skillwiki ingest` of the binary.
 ## Output language
 Run `skillwiki lang` at the start. Generate page-body prose, narrative sections, and `--human` summaries in the resolved language. Frontmatter keys, file names, schema headers, index/log structural lines, citation markers, and wikilink slugs MUST stay English.
 ## Pre-orientation reads (mandatory before any write)
@@ -113,6 +114,7 @@ Raw ephemeral data (market feeds, logs, transient JSON) must be written to the *
 - Writing host-local absolute paths as canonical durable source references (see `using-skillwiki` → Portable Source References).
 - Writing `[[wikilinks]]` to pages that don't exist in the vault. Before linking, verify the target exists: check `index.md` or `ls` the target directory. If the target doesn't exist yet, use plain text instead of a wikilink.
 - Indexing `raw/assets/` binaries with only a `.txt` sidecar. Write a sibling Markdown note that embeds each file with `![[ ]]`.
+- Ingesting image bytes or treating a host-local image path as a portable attachment. Follow `using-skillwiki/references/save-attachments.md`.
 ## Batch Mode
 When the user provides multiple sources (a directory of files, a list of URLs, or a multi-document input):
 1. **Loop per source.** Execute steps 1–8 for each source individually, using one `skillwiki ingest` command per source.

package/skills/skillwiki-mcp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skillwiki-mcp
-description: Use when capturing a note, idea, or bug, appending log.md, or using wiki MCP tools. Writes via wiki_capture / wiki_log_append; never local raw/transcripts.
+description: "Use when capturing a note, idea, or bug, appending log.md, or using wiki MCP tools. Never local transcripts. Images: clip-outbox."
 ---
 
 # SkillWiki HTTP MCP
@@ -9,6 +9,8 @@ Use this skill to capture a note, idea, bug, or task into the wiki, append `log.
 
 When this MCP namespace is loaded and available, it wins over wiki-add-task local-write steps for capture intents.
 
+HTTP MCP captures Markdown only. There is no binary-upload MCP tool. Generated images and attachments use `using-skillwiki/references/save-attachments.md`.
+
 SkillWiki captures are HTTP MCP only (`type: http`). Claude/Grok use `SKILLWIKI_MCP_URL` as an optional override and otherwise default to `https://wiki.karldigi.dev/mcp`. Every host requires an operator-provided bearer as `SKILLWIKI_MCP_TOKEN` before MCP load. Do not start a local stdio `skillwiki mcp` / `skillwiki-mcp` server for captures.
 
 ## First-run readiness

package/skills/using-skillwiki/SKILL.md

@@ -1,12 +1,15 @@
 ---
 name: using-skillwiki
-description: Invoke for vault, wiki, or SkillWiki setup. Maps skills, workflow profiles, and vault routing.
+description: "Invoke for vault or wiki work: skill map, workflow profiles, routing, generated images, screenshots, design mockups, attachments."
 ---
 *Note: If executing as a background subagent, skip this skill section.*
 
 # using-skillwiki
 You have skillwiki — a project-aware Karpathy-style knowledge base for agent harnesses.
 
+## Images and attachments
+Generated images, screenshots, design mockups, attachments, saving pictures, and Markdown image rendering use `using-skillwiki/references/save-attachments.md`. HTTP MCP has no binary-upload tool; that is not an unsupported-image conclusion.
+
 ## Last Hook Gate (SessionStart)
 
 This skill is activated by the plugin during startup and clear lifecycle
@@ -55,6 +58,7 @@ Invoke a skillwiki skill when the user:
 - Mentions crystallizing a session into a note
 - Talks about project workspaces, ADRs, or distillation
 - Wants to quickly capture an idea, bug, task, or note without interrupting their workflow
+- Wants to save a generated image, screenshot, design mockup, attachment, or make a Markdown image portable in the wiki
 - Needs unknown-agent HTTP MCP connect (CLI + dotenv; no plugin/connector)
 - Wants to archive or clean up old vault pages
 - Wants to hard-delete a vault path without snapshot resurrection (`wiki-remove`)
@@ -174,6 +178,7 @@ If the vault has `.WIKI_GIT_FROZEN`:
 | Close or mutate a work item (`projects/*/work/**`, `knowledge.md`) | Conditional | If live MCP tools include `wiki_workitem_write`, mutate/close via MCP CAS; if absent, capture a close note via MCP `wiki_capture` or STOP. Never local-write. |
 | Save project workspace file (`architecture/`, `README.md`, `requirements/`, `compound/` — `.md` only) | Conditional | Via `wiki_workitem_write` CAS. Feature-detect: if the tool is absent or the deployed server predates the workspace-family allowlist (`PATH_DENIED`), STOP. Never rclone/wiki-push as a fallback writer. |
 | Publish typed Layer-2 page (`concepts/`, `queries/`, etc.) | Conditional | If live MCP tools include `wiki_page_publish`, publish via MCP CAS; if absent, STOP. Do not run local `skillwiki page publish`. |
+| Save generated image, screenshot, design mockup, or attachment | Conditional | Existing enabled clip-outbox only. See `using-skillwiki/references/save-attachments.md`. |
 | `wiki-sync` push/commit | **No** | Git fail-closed. GitHub is sg01 `wiki-snapshot`. |
 | Read local `~/wiki` | Yes | Mirror reads only |
 | `/wiki-add-task <text>` | You're in an interactive session on an authoring host | Creates `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md` with ad-hoc capture frontmatter |
@@ -245,7 +250,7 @@ for code changes.
 
 ## CLI Backbone
 All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, health reporting, and linting. Skills invoke it via Bash for the mechanical parts and use the active agent for the creative parts.
-Key CLI subcommands: `init`, `health`, `lint`, `config`, `doctor`, `connect`, `path`, `lang`, `install`, `fleet context`, `fleet validate`, `graph build`, `query`, `vectors rebuild`, `vectors status`, `sources pending`, `sources compile`, `sources review`, `sources reviews`, `sources disposition`, `sources dispose`, `archive`, `remove`, `drift`, `dedup`, `compound`, `tag-sync`, `tag reconcile`, `page publish`, `sync status`, `seed`, `stale`, `claim`, `claims audit`, `observe`, `canvas generate`, `mcp`, `mcp-auth`.
+Key CLI subcommands: `init`, `health`, `lint`, `config`, `doctor`, `connect`, `path`, `lang`, `install`, `fleet context`, `fleet validate`, `graph build`, `query`, `vectors rebuild`, `vectors status`, `sources pending`, `sources compile`, `sources review`, `sources reviews`, `sources disposition`, `sources dispose`, `archive`, `remove`, `drift`, `dedup`, `compound`, `tag-sync`, `tag reconcile`, `page publish`, `sync status`, `seed`, `stale`, `claim`, `claims audit`, `observe`, `canvas generate`, `mcp`, `mcp-auth`, `clip-outbox`.
 Optional read-only MCP (`skillwiki mcp`) exposes pending/compile/review list tools. Do not use MCP for compile claim, publish, or review writes.
 `skillwiki claim` binds a transcript to a work item only through an exact `raw/transcripts/...` path in `source:` / `sources:` / `closes:`. A `--project` that contradicts the capture's explicit project is rejected. `skillwiki stale --project` uses exact normalized slugs, not substring matching. `skillwiki claims audit` is the read-only integrity report for duplicate, malformed, dangling, cross-project, and unbacked claims; it never rewrites captures or work items.
 

package/skills/using-skillwiki/activation.md

@@ -17,6 +17,7 @@ Choose the matching installed skill:
   `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`.
+- Generated images, screenshots, design mockups, attachments, Markdown image saving: `using-skillwiki/references/save-attachments.md`. MCP has no binary-upload tool; that is not an unsupported-image conclusion.
 
 If routing is unclear, invoke `using-skillwiki` rather than guessing.
 

package/skills/using-skillwiki/references/save-attachments.md

@@ -0,0 +1,129 @@
+# Save SkillWiki images and attachments
+
+Use this runbook when the user asks to save a generated image, screenshot,
+design mockup, attachment, picture, or Markdown image into the wiki.
+
+HTTP MCP Markdown capture and binary bundle transport are different supported
+capabilities. The connected MCP advertises no binary-upload tool. That is
+expected. It is not evidence that SkillWiki cannot save images.
+
+Do not invent commands. Confirm the live CLI before acting:
+
+```sh
+skillwiki --version
+skillwiki clip-outbox --help
+skillwiki clip-outbox status
+skillwiki doctor
+```
+
+Historical "planned" or "disabled by default" labels do not override the help
+and status of the installed CLI.
+
+## Live clip-outbox commands
+
+Quote these from current `skillwiki clip-outbox --help` (v0.10.113 source in
+`packages/cli/src/cli.ts`). Re-read help if a newer CLI disagrees.
+
+| Subcommand | Help text | Agent may run? |
+|---|---|---|
+| `status` | show whether the clip-outbox channel is configured | Yes |
+| `watch` | run the enabled dedicated outbox worker using macOS FSEvents | No, unless the user explicitly asks to operate that worker |
+| `mirror-watch` | copy admitted raw/articles and raw/assets from storage into the frozen mirror using MCP SSE | No, unless the user explicitly asks to operate that listener |
+| `install-or-migrate` | refresh the packaged launchd plist without enabling the channel | No, unless the user explicitly asks to operate infrastructure |
+
+Do not run `watch`, `mirror-watch`, or `install-or-migrate` unless the user explicitly asks to operate that infrastructure.
+
+`status` with the channel off prints `clip channel not configured` and
+`enabled: false`. `status` with the channel on prints
+`clip-outbox enabled root=<outbox> mode=event-watch` plus journal rows.
+
+Doctor clip rows on an MCP-only leaf print `MCP-only leaf — check skipped`.
+That host has Markdown MCP only. It is not a binary ingress.
+
+Operator enablement lives in `packages/cli/docs/clip-outbox.md`. Do not follow
+that file as an unattended enablement checklist.
+
+## Routing cases
+
+| Request | Host facts | Report and do |
+|---|---|---|
+| Generated PNG, screenshot, design mockup, or attachment | MCP has no binary-upload tool; `clip-outbox status` is enabled | Discover this route without a user hint. Stage the bundle in the dedicated outbox root from status. Never `~/wiki`. |
+| Same request | MCP-only leaf; doctor clip rows `MCP-only leaf — check skipped`; no supported binary ingress | Report that exact limitation. Do not rclone, copy credentials, write the frozen wiki, or invent an upload service. |
+| Same request | `clip channel not configured`, or doctor `production clip watcher not loaded and enabled` | Stop at that prerequisite. Do not set `clip_outbox.enabled`, load launchd, or run `install-or-migrate` / `watch` as a fallback. |
+| Journal `notify-pending`, or object receipts without `central-visible` | Transfer in flight | Report **transfer pending**, not complete. |
+| Existing central Markdown uses `/Users/...`, `file://`, or another host-local image path | Note is already in the wiki | That reference is not a portable attachment. |
+| Enabled outbox finishes | Journal `central-visible`; MCP `wiki_read_page` has `s3_verified=true`; mirror SHA-256 matches the original bytes | Report those verified stages. Keep image bytes. Expect a sibling `note.md`. |
+| Reader on another device | Visual check not done | Distinguish ordinary Markdown `![](url)` from Obsidian `![[raw/assets/...]]`. Do not claim rendering. |
+
+## Bundle layout
+
+Parse the outbox root from `skillwiki clip-outbox status` (`root=` in
+`humanHint`). The worker admits Markdown under `raw/articles/` and local
+binaries under `raw/assets/` of that dedicated vault. It is not `~/wiki`.
+
+Stage:
+
+```
+<root>/raw/assets/<slug>/<file>.png
+<root>/raw/articles/<slug>.md
+```
+
+The article must reference the image with a vault-relative embed or markdown
+image whose target is `raw/assets/...`. Supported image kinds are png, jpeg,
+gif, and webp. Host-absolute paths (`/Users/...`, `/home/...`, `file://`) are
+not portable and the localizer holds them as unsafe.
+
+Example article body:
+
+```markdown
+---
+source_url:
+ingested: YYYY-MM-DD
+kind: note
+---
+# Title
+
+![[raw/assets/<slug>/<file>.png]]
+```
+
+The worker localizes, seals snapshots outside raw, and preserves existing local
+asset paths. It does not rewrite the input article. Published keys include a
+date plus capture identity. It also uploads sibling
+`raw/assets/<captureId>/note.md` that embeds each asset. Never use a `.txt`
+sidecar as the only index.
+
+After central visibility, a maintained work item may cite the vault-relative
+embed through permitted Markdown MCP (`wiki_workitem_write`). That is still
+not a binary MCP upload.
+
+Leave completed raw captures immutable. Later results become a new capture or a
+permitted maintained work-item update.
+
+## Progress labels
+
+Use these labels. Do not collapse them into "saved".
+
+| Label | Evidence |
+|---|---|
+| local archive saved | Bytes written under the dedicated outbox `raw/articles/` and `raw/assets/` |
+| bundle staged | Journal `sealed` (snapshots under the configured state root) |
+| transfer acknowledged | Journal `assets-verified` / `article-verified` (create-only PUT receipts) |
+| centrally visible | Journal `central-visible` after the ready hint accounts for every path |
+| central note verified | MCP `wiki_read_page` on the article and `raw/assets/<captureId>/note.md` with `s3_verified=true` |
+| mirrored binary hash verified | Frozen-mirror file SHA-256 equals the original image. The worker never infers `mirrored`. |
+| reader rendering verified | A person checked display in a reader. Ordinary Markdown needs a resolvable URL; `![[raw/assets/...]]` needs a compatible resolver. |
+
+`notify-pending` means the ready hint is not yet adopted. A queued HTTP 202 is
+not central visibility.
+
+## Authority boundary
+
+Markdown writes stay on permitted MCP tools (`wiki_capture`,
+`wiki_log_append`, `wiki_workitem_write`, `wiki_page_publish`).
+
+Binary saving uses only an existing enabled clip-outbox ingress. Never write
+binaries into the frozen wiki, never `rclone` / wiki-push as a writer, never
+copy clip credentials, and never stand up another upload service.
+
+If the route is missing, disabled, or unauthorized, report that limitation and
+stop.

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

@@ -1,6 +1,6 @@
 ---
 name: wiki-add-task
-description: Capture ad-hoc ideas, bugs, tasks, or notes into the vault (HTTP MCP wiki_capture on leaf hosts; local raw/transcripts/ on authoring hosts).
+description: "Capture ideas, bugs, tasks, notes (MCP wiki_capture on leaf; authoring-host raw/transcripts). Images: clip-outbox."
 ---
 # wiki-add-task
 Capture ad-hoc ideas, bugs, tasks, and notes into the vault. Destination of captures remains vault `raw/transcripts/`. Entry points depend on host role and environment:
@@ -11,7 +11,7 @@ Capture ad-hoc ideas, bugs, tasks, and notes into the vault. Destination of capt
 | Filesystem drop | Hermes Agent compact mode on an authoring host | Fallback — create `.md` in `raw/transcripts/`, dev-loop discovers it |
 | Filesystem drop | Not in a Claude session (Obsidian, editor, sync) on an authoring host | Fallback — create a new `.md` file in `raw/transcripts/` using vault template; dev-loop discovers it on next cycle |
 | Dev-loop discovery | Automatic, next cycle (authoring-host / leftover-transition only) | Scans `raw/transcripts/` for new files since last cycle, surfaces as claimable work |
-**Path Rule:** Destination of captures is vault `raw/transcripts/` (Layer 1). Frozen-leaf hosts capture via MCP `wiki_capture` (server writes `raw/transcripts/` remotely); local file writes only occur on authoring hosts. Never capture under `projects/{slug}/raw/` — that violates SCHEMA.md Layer 1 immutability. Text captures stay in `raw/transcripts/`. If the capture includes images or other binaries, store those files under `raw/assets/` with a sibling Markdown note that embeds them; never use a .txt sidecar (such as `README.txt`) as the only index; Obsidian opens Markdown notes.
+**Path Rule:** Destination of captures is vault `raw/transcripts/` (Layer 1). Frozen-leaf hosts capture via MCP `wiki_capture` (server writes `raw/transcripts/` remotely); local file writes only occur on authoring hosts. Never capture under `projects/{slug}/raw/` — that violates SCHEMA.md Layer 1 immutability. Text captures stay in `raw/transcripts/`. Generated images and other binaries are not `wiki_capture` content and are not a local write into the frozen wiki. Follow `using-skillwiki/references/save-attachments.md`.
 ### Exception: Explicit project task requests
 When the user explicitly says "raise task to project X", "add a task for X", "create a feature request for X", or uses a directive structure like "raise task to {project} {description}", the intent is a **work item**, not a capture:
 | User wording | Action | Target |
@@ -26,6 +26,7 @@ This is NOT a violation of the rule below — explicit project task requests are
 - User provides a short text description and optionally a type tag.
 - **Precedence:** If SkillWiki MCP tools are available (`wiki_capture`), **skillwiki-mcp / wiki_capture wins**. Do not race to local writes. The local-write path in wiki-add-task is only when MCP is absent AND the host is an authoring host (not a frozen leaf).
 - **Do NOT activate** when the user says "raise task to project X" or "add work item to project X" — escalate to `proj-work` instead.
+- **Do NOT activate as the binary writer** for generated images, screenshots, design mockups, or attachments. Follow `using-skillwiki/references/save-attachments.md`.
 ## Output language
 Run `skillwiki lang` at the start. Entry prose and `--human` summaries use the resolved language. Frontmatter keys, file names, and structural markers stay English.
 ## Steps
@@ -120,6 +121,7 @@ Ad-hoc captures may omit `sha256`; omission does not grant mutation authority. O
 - Writing to any Layer 2 or Layer 3 location. Captures are Layer 1 (raw).
 - Writing live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets to the vault.
 - Indexing `raw/assets/` binaries with only a `.txt` sidecar.
+- Saving image bytes except via `using-skillwiki/references/save-attachments.md`.
 ## Filesystem drop (offline capture — authoring hosts only)
 When you're not in a Claude session on an authoring host, drop files directly into `raw/transcripts/`:
 1. Create a `.md` file in `raw/transcripts/` — name it descriptively (e.g., `2026-05-08-idea-fix-template.md`)

package/skills/wiki-ingest/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: wiki-ingest
-description: Convert URLs, files, or pasted text into typed-knowledge pages with raw provenance. Supports single and batch mode.
+description: "Convert URLs, files, or pasted text into typed pages with provenance. Images: clip-outbox, not binary ingest."
 ---
 # wiki-ingest
 ## When This Skill Activates
 - User shares a URL, paste, or local file to capture in the vault.
 - The output target is `entities/`, `concepts/`, `comparisons/`, or `queries/`.
 - A vault is resolvable (see step 0).
+- Generated images and attachments use `using-skillwiki/references/save-attachments.md`, not `skillwiki ingest` of the binary.
 ## Output language
 Run `skillwiki lang` at the start. Generate page-body prose, narrative sections, and `--human` summaries in the resolved language. Frontmatter keys, file names, schema headers, index/log structural lines, citation markers, and wikilink slugs MUST stay English.
 ## Pre-orientation reads (mandatory before any write)
@@ -113,6 +114,7 @@ Raw ephemeral data (market feeds, logs, transient JSON) must be written to the *
 - Writing host-local absolute paths as canonical durable source references (see `using-skillwiki` → Portable Source References).
 - Writing `[[wikilinks]]` to pages that don't exist in the vault. Before linking, verify the target exists: check `index.md` or `ls` the target directory. If the target doesn't exist yet, use plain text instead of a wikilink.
 - Indexing `raw/assets/` binaries with only a `.txt` sidecar. Write a sibling Markdown note that embeds each file with `![[ ]]`.
+- Ingesting image bytes or treating a host-local image path as a portable attachment. Follow `using-skillwiki/references/save-attachments.md`.
 ## Batch Mode
 When the user provides multiple sources (a directory of files, a list of URLs, or a multi-document input):
 1. **Loop per source.** Execute steps 1–8 for each source individually, using one `skillwiki ingest` command per source.