@klhapp/skillmux 1.10.0 → 1.11.1

package/CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.11.1](https://github.com/klhq/skillmux/compare/v1.11.0...v1.11.1) (2026-09-03)
+
+
+### Added
+
+* **cli:** install asks before writing to the vault ([#185](https://github.com/klhq/skillmux/issues/185)) ([7f12d02](https://github.com/klhq/skillmux/commit/7f12d02def0f306d963d37920f2407c8cffe1c04))
+
+
+### Fixed
+
+* **cli:** reject full-vault agents on project attach, clarify agent vs target ([#184](https://github.com/klhq/skillmux/issues/184)) ([118aff5](https://github.com/klhq/skillmux/commit/118aff5f46fb9e83c8c0e068890b96fe0a02311d))
+* **security:** gate install/update on scan findings, plus CLI help cleanup ([#182](https://github.com/klhq/skillmux/issues/182)) ([daffd8a](https://github.com/klhq/skillmux/commit/daffd8af89ebee1fbd4c05870c328baf747bbea3))
+
+## [1.11.0](https://github.com/klhq/skillmux/compare/v1.10.0...v1.11.0) (2026-09-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* **cli:** agent-based native setup — remove --target/--client vagueness, clearer rejections ([#172](https://github.com/klhq/skillmux/issues/172))
+
+### Added
+
+* **cli:** add --register-mcp to auto-register skillmux ([#173](https://github.com/klhq/skillmux/issues/173)) ([55e6e33](https://github.com/klhq/skillmux/commit/55e6e33a71abdfb2b340cdf2634f47db6a0fcff6))
+* **cli:** agent-based native setup — remove --target/--client vagueness, clearer rejections ([#172](https://github.com/klhq/skillmux/issues/172)) ([cf5a346](https://github.com/klhq/skillmux/commit/cf5a346a3374ea217f7ffd17aba9495439b37f87))
+* **cli:** project init --register-mcp for project-scoped MCP + instructions ([#176](https://github.com/klhq/skillmux/issues/176)) ([a1e5e3b](https://github.com/klhq/skillmux/commit/a1e5e3b43cd65b64741528e9cbaed0770d1637b7))
+
+
+### Fixed
+
+* **cli:** four consistency bugs found in a CLI audit ([#177](https://github.com/klhq/skillmux/issues/177)) ([a3aa008](https://github.com/klhq/skillmux/commit/a3aa0082b8d5dd6f36a0bf527bfaddb43075bb7d))
+* **cli:** guided init prompts for vault path instead of guessing ([#175](https://github.com/klhq/skillmux/issues/175)) ([2fa224c](https://github.com/klhq/skillmux/commit/2fa224ce7887a19bc4bbb59b626926c13f3d7284))
+* **cli:** reject config init cleanly for remote targets, add classification registry ([#170](https://github.com/klhq/skillmux/issues/170)) ([9e6da95](https://github.com/klhq/skillmux/commit/9e6da95a386230e03dc94e0c8cbaa6d622a4d3f5))
+
+
+### Changed
+
+* **cli:** consolidate per-agent data into one registry ([#179](https://github.com/klhq/skillmux/issues/179)) ([9af61da](https://github.com/klhq/skillmux/commit/9af61da4e181fc8c1ae5259cf7179d60050bf5b9))
+* **cli:** one meaning per word — finish the target/context split ([#180](https://github.com/klhq/skillmux/issues/180)) ([1714daa](https://github.com/klhq/skillmux/commit/1714daa63a3429ffe6db090fc25a3e018026d85e))
+
+
+### Chores
+
+* pin next release to 1.11.0 ([#178](https://github.com/klhq/skillmux/issues/178)) ([0193952](https://github.com/klhq/skillmux/commit/01939522b550b40ee9bfa6981ea359d17bd55897))
+
 ## [1.10.0](https://github.com/klhq/skillmux/compare/v1.9.3...v1.10.0) (2026-09-01)
 
 

package/README.md

@@ -12,9 +12,9 @@
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
 </p>
 
-<p align="center"><strong>One skill vault. Every AI coding client. Nothing lost in translation.</strong></p>
+<p align="center"><strong>One skill vault. Every AI coding agent. Nothing lost in translation.</strong></p>
 
-Every AI coding client wants its own skill folder and its own format. Skillmux
+Every AI coding agent wants its own skill folder and its own format. Skillmux
 manages [`SKILL.md`](https://agentskills.io) collections across all of them
 from one place. Keep one **vault source of truth** (the logical skill
 collection), pin a small set into native skill directories, and retrieve the
@@ -22,7 +22,7 @@ rest through MCP. A **vault checkout** is a physical copy of that collection.
 On one machine, `~/skills` can be both the source of truth and its checkout.
 
 For a shared topology, the Git-backed vault source of truth has a checkout on
-each client machine, where the Skillmux CLI creates native pins, and a checkout
+each agent machine, where the Skillmux CLI creates native pins, and a checkout
 on the server, where Skillmux server exposes HTTP MCP. Skillmux does not pull,
 push, replicate, or determine freshness between checkouts; Git and the
 deployment process own replication and freshness. See
@@ -40,7 +40,7 @@ See [Configuration](docs/configuration.md#machine-config-bootstrap) and
 
 Choose a setup by the job:
 
-1. Need native skills or local MCP for one client? Install the **Skillmux CLI**.
+1. Need native skills or local MCP for one agent? Install the **Skillmux CLI**.
 2. On Linux when Bun is undesirable? Use the **standalone Linux executable**;
    it is the same Skillmux CLI.
 3. Need one shared HTTP MCP service? Deploy the **full image**, the
@@ -49,7 +49,7 @@ Choose a setup by the job:
    retrieval? Use the **slim image**; see [Deployment](docs/deployment.md).
 
 For native pins and shared retrieval, run the Skillmux CLI on the machines that own
-   client directories and one shared server for routed retrieval. MCP-only
+   agent directories and one shared server for routed retrieval. MCP-only
 clients connect over HTTP and do not need the Skillmux CLI.
 
 Manage the server's vault checkout outside the container. Use the CLI for
@@ -126,19 +126,19 @@ skillmux sync
 skillmux doctor
 ```
 
-The planner detects clients, asks which skills belong in the core tier, and
+The planner detects agents, asks which skills belong in the core tier, and
 shows every write before confirmation. Use explicit flags for automation:
 
 ```sh
 skillmux init \
-  --client claude-code \
-  --client codex \
+  --agent claude-code \
+  --agent codex \
   --core csv-formatter \
   --dry-run
 
 skillmux init \
-  --client claude-code \
-  --client codex \
+  --agent claude-code \
+  --agent codex \
   --core csv-formatter \
   --yes
 ```
@@ -195,7 +195,7 @@ MCP clients authenticate only to `/mcp` with the MCP bearer token. Operators
 use a separate administrative bearer token for `/admin/v1/*`; neither token
 authorizes the other surface. Named CLI contexts administer the deployed server
 only. They never install, pin, synchronize, or otherwise manage skill
-directories on remote client machines. See [Deployment](docs/deployment.md#http-surfaces)
+directories on remote agent machines. See [Deployment](docs/deployment.md#http-surfaces)
 for configuration and examples.
 
 ## Add and inspect skills
@@ -207,7 +207,14 @@ skillmux install owner/repo
 skillmux install owner/repo/path/to/skill
 ```
 
-Skillmux validates `SKILL.md` and scans candidate content before copying it into the vault. Use `--fail-on low|medium|high` to turn selected findings into an install gate.
+Skillmux validates `SKILL.md` and scans candidate content before copying it
+into the vault, then asks before writing. Pass `--yes` to approve up front;
+a non-interactive run needs it, because `install` refuses to write unattended.
+
+A high-severity finding aborts the install by default. `--fail-on
+low|medium|high|none` moves that threshold, and it names the lowest severity
+that still aborts, so a lower value is stricter: `low` aborts on low, medium
+and high, while `none` installs despite any finding.
 
 Useful management commands:
 
@@ -254,16 +261,16 @@ Skillmux returns a ranked shortlist and lets the calling model choose. Endpoint
 
 Read [MCP routing](docs/mcp-routing.md) for transports, client instructions, retrieval modes, and the wire contract.
 
-## Supported clients
+## Supported agents
 
-| Client | Native skill delivery | MCP setup |
+| Agent | Native skill delivery | MCP setup |
 | --- | --- | --- |
-| Claude Code | `~/.claude/skills` | Configure in the client |
-| Codex | `$CODEX_HOME/skills` or `~/.codex/skills` | Configure in the client |
-| Gemini CLI, OpenCode, GitHub Copilot, Windsurf | `~/.agents/skills` | Configure in the client |
-| Antigravity | `~/.gemini/config/skills` | Configure in the client |
+| Claude Code | `~/.claude/skills` | Configure in the agent |
+| Codex | `$CODEX_HOME/skills` or `~/.codex/skills` | Configure in the agent |
+| OpenCode, GitHub Copilot, Windsurf | Shared `~/.agents/skills` | Configure in the agent |
+| Antigravity | `~/.gemini/config/skills` | Configure in the agent |
 | Goose, Hermes | Manual full-vault setup | Manual registration |
-| Custom clients | Any directory through a custom target | Stdio or Streamable HTTP |
+| Custom agents | Any directory through a custom target | Stdio or Streamable HTTP |
 
 Skillmux preserves existing instruction files and unmanaged target content. Run `skillmux init --dry-run` to inspect every planned filesystem change.
 

package/docs/README.md

@@ -1,7 +1,7 @@
 # Skillmux documentation
 
 Skillmux manages one `SKILL.md` vault source of truth: the logical skill
-collection. A vault checkout is a physical copy used by a client machine or
+collection. A vault checkout is a physical copy used by an agent machine or
 server. On one machine, `~/skills` can be both. Choose a workflow based on
 where skills need to appear and where Skillmux should run.
 
@@ -19,7 +19,7 @@ where skills need to appear and where Skillmux should run.
 
 You can combine native management and local MCP retrieval on one machine. For
 native pins plus shared retrieval, run Skillmux CLI on each machine that owns
-client directories and deploy Skillmux server for HTTP MCP. The Bun package is
+agent directories and deploy Skillmux server for HTTP MCP. The Bun package is
 the cross-platform CLI installation method; the standalone Linux executable is
 its Linux alternative. Git and the deployment process, not Skillmux, replicate
 vault checkouts and determine their freshness; see
@@ -38,7 +38,7 @@ to customize behavior; see [Configuration](configuration.md#machine-config-boots
 
 The MCP and administrative surfaces use separate bearer tokens; possession of
 one does not grant access to the other. A named CLI context administers the
-deployed server only, never remote client skill directories. See
+deployed server only, never remote agent skill directories. See
 [Deployment](deployment.md#http-surfaces) for authentication and examples.
 
 ## Learn the model

package/docs/assets/architecture-dark.svg

@@ -4,10 +4,10 @@
 
   <defs>
     <filter id="shadow" x="-15%" y="-15%" width="130%" height="140%">
-      <feDropShadow dx="0" dy="5" stdDeviation="8" flood-color="#000000" flood-opacity="0.35"/>
+      <feDropShadow dx="0" dy="4" stdDeviation="10" flood-color="#000000" flood-opacity="0.40"/>
     </filter>
     <marker id="arrow-teal" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto">
-      <path d="M0 0L10 5L0 10Z" fill="#2dd4bf"/>
+      <path d="M0 0L10 5L0 10Z" fill="#34d399"/>
     </marker>
     <marker id="arrow-blue" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto">
       <path d="M0 0L10 5L0 10Z" fill="#60a5fa"/>
@@ -22,7 +22,7 @@
       .title {
         font-size: 27px;
         font-weight: 750;
-        fill: #e2e8f0;
+        fill: #f1f5f9;
       }
       .subtitle {
         font-size: 16px;
@@ -51,7 +51,7 @@
         fill: #cbd5e1;
       }
       .mono-light {
-        fill: #ffffff;
+        fill: #e2e8f0;
       }
       .chip {
         font-size: 12px;
@@ -61,100 +61,107 @@
     </style>
   </defs>
 
+  <!-- Canvas -->
   <rect width="1200" height="720" rx="24" fill="#0d1117"/>
-  <rect x="1" y="1" width="1198" height="718" rx="23" fill="none" stroke="#30363d" stroke-width="2"/>
+  <rect x="1" y="1" width="1198" height="718" rx="23" fill="none" stroke="#21262d" stroke-width="2"/>
 
+  <!-- Header -->
   <text x="48" y="50" class="title">One vault source of truth, three ways to use Skillmux</text>
   <text x="48" y="78" class="subtitle">Git and deployment replicate checkouts; Skillmux uses each checkout where it runs.</text>
 
+  <!-- Vault card -->
   <g filter="url(#shadow)">
     <rect x="280" y="106" width="640" height="118" rx="18" fill="#161b22" stroke="#30363d" stroke-width="2"/>
-    <circle cx="324" cy="147" r="18" fill="#334155"/>
-    <path d="M314 141H327L333 147L327 153H314M320 135V159" fill="none" stroke="#ffffff" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
+    <circle cx="324" cy="147" r="18" fill="#30363d"/>
+    <path d="M314 141H327L333 147L327 153H314M320 135V159" fill="none" stroke="#e2e8f0" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
     <text x="358" y="144" class="card-title">Git-backed vault source of truth</text>
     <text x="358" y="172" class="mono">SKILL.md per child directory</text>
     <text x="358" y="200" class="body">A checkout is a physical copy of it on one machine.</text>
-    <rect x="751" y="155" width="137" height="34" rx="9" fill="#1e293b" stroke="#475569"/>
+    <rect x="751" y="155" width="137" height="34" rx="9" fill="#21262d" stroke="#30363d"/>
     <text x="819.5" y="177" text-anchor="middle" class="mono">skillmux.toml</text>
   </g>
 
-  <path d="M520 224V252H410V277" fill="none" stroke="#2dd4bf" stroke-width="3" marker-end="url(#arrow-teal)"/>
+  <!-- Connector lines -->
+  <path d="M520 224V252H410V277" fill="none" stroke="#34d399" stroke-width="3" marker-end="url(#arrow-teal)"/>
   <path d="M720 224V252H980V277" fill="none" stroke="#a78bfa" stroke-width="3" marker-end="url(#arrow-violet)"/>
   <text x="394" y="270" text-anchor="end" class="body">client checkout</text>
   <text x="996" y="270" text-anchor="start" class="body">server checkout</text>
 
+  <!-- CLI card (emerald) -->
   <g filter="url(#shadow)">
-    <rect x="40" y="284" width="740" height="302" rx="18" fill="#161b22" stroke="#0f766e" stroke-width="2"/>
-    <rect x="62" y="306" width="124" height="26" rx="13" fill="#134e4a"/>
-    <text x="124" y="324" text-anchor="middle" class="chip" fill="#5eead4">SKILLMUX CLI</text>
+    <rect x="40" y="284" width="740" height="302" rx="18" fill="#161b22" stroke="#059669" stroke-width="2"/>
+    <rect x="62" y="306" width="124" height="26" rx="13" fill="#064e3b"/>
+    <text x="124" y="324" text-anchor="middle" class="chip" fill="#34d399">SKILLMUX CLI</text>
     <text x="62" y="365" class="card-title">On one client machine</text>
     <text x="62" y="390" class="body">Manage native skills, add local MCP retrieval, or do both.</text>
 
-    <rect x="62" y="414" width="276" height="48" rx="10" fill="#0f2e2b" stroke="#0f766e"/>
-    <circle cx="85" cy="438" r="11" fill="#2dd4bf"/>
+    <rect x="62" y="414" width="276" height="48" rx="10" fill="#052e16" stroke="#059669"/>
+    <circle cx="85" cy="438" r="11" fill="#34d399"/>
     <text x="85" y="442.5" text-anchor="middle" style="font-size: 13px; font-weight: 750" fill="#0d1117">1</text>
     <text x="200" y="433" text-anchor="middle" class="label" style="font-size: 17px">Manage native skills</text>
     <text x="200" y="453" text-anchor="middle" class="mono">skillmux init · sync</text>
-    <path d="M200 462V487" fill="none" stroke="#2dd4bf" stroke-width="2.5" marker-end="url(#arrow-teal)"/>
-    <rect x="62" y="493" width="276" height="49" rx="10" fill="#1e293b" stroke="#475569"/>
+    <path d="M200 462V487" fill="none" stroke="#34d399" stroke-width="2.5" marker-end="url(#arrow-teal)"/>
+    <rect x="62" y="493" width="276" height="49" rx="10" fill="#21262d" stroke="#30363d"/>
     <text x="200" y="514" text-anchor="middle" class="label">Native skill directories</text>
     <text x="200" y="533" text-anchor="middle" class="body">managed core and project links</text>
 
     <text x="62" y="570" class="body">Install Skillmux CLI with</text>
-    <rect x="270" y="550" width="85" height="27" rx="8" fill="#0f172a" stroke="#334155"/>
-    <text x="312.5" y="568" text-anchor="middle" class="chip" style="font-size: 10px" fill="#ffffff">BUN PACKAGE</text>
-    <rect x="361" y="550" width="87" height="27" rx="8" fill="#1e293b" stroke="#475569"/>
-    <text x="404.5" y="561" text-anchor="middle" class="chip" style="font-size: 10px" fill="#cbd5e1"><tspan x="404.5">LINUX</tspan><tspan x="404.5" dy="11">EXECUTABLE</tspan></text>
+    <rect x="270" y="550" width="85" height="27" rx="8" fill="#30363d" stroke="#444c56"/>
+    <text x="312.5" y="568" text-anchor="middle" class="chip" style="font-size: 10px" fill="#e2e8f0">BUN PACKAGE</text>
+    <rect x="361" y="550" width="87" height="27" rx="8" fill="#21262d" stroke="#30363d"/>
+    <text x="404.5" y="561" text-anchor="middle" class="chip" style="font-size: 10px" fill="#94a3b8"><tspan x="404.5">LINUX</tspan><tspan x="404.5" dy="11">EXECUTABLE</tspan></text>
   </g>
 
+  <!-- MCP retrieval sub-card (blue) -->
   <g filter="url(#shadow)">
-    <rect x="420" y="414" width="338" height="128" rx="10" fill="#172554" stroke="#3b82f6"/>
+    <rect x="420" y="414" width="338" height="128" rx="10" fill="#0c1929" stroke="#2563eb"/>
     <circle cx="453" cy="435" r="11" fill="#60a5fa"/>
     <text x="453" y="439.5" text-anchor="middle" style="font-size: 13px; font-weight: 750" fill="#0d1117">2</text>
     <text x="476" y="441" class="label" style="font-size: 17px">Add local MCP retrieval</text>
     <text x="442" y="463" class="body">Reaches the whole indexed vault on demand.</text>
 
-    <rect x="442" y="475" width="92" height="48" rx="10" fill="#1e293b" stroke="#475569"/>
+    <rect x="442" y="475" width="92" height="48" rx="10" fill="#21262d" stroke="#30363d"/>
     <text x="488" y="505" text-anchor="middle" class="label">AI client</text>
     <path d="M534 499H578" fill="none" stroke="#60a5fa" stroke-width="2.5" marker-end="url(#arrow-blue)"/>
     <text x="559" y="489" text-anchor="middle" class="body">stdio</text>
-    <rect x="584" y="470" width="152" height="62" rx="10" fill="#161b22" stroke="#3b82f6"/>
+    <rect x="584" y="470" width="152" height="62" rx="10" fill="#161b22" stroke="#2563eb"/>
     <text x="660" y="492" text-anchor="middle" class="mono">skillmux serve</text>
     <text x="660" y="511" text-anchor="middle" class="body">default: FTS5 +</text>
     <text x="660" y="527" text-anchor="middle" class="body">local GTE-small</text>
-
   </g>
 
+  <!-- Server card (violet) -->
   <g filter="url(#shadow)">
     <rect x="800" y="284" width="360" height="302" rx="18" fill="#161b22" stroke="#7c3aed" stroke-width="2"/>
-    <rect x="822" y="306" width="136" height="26" rx="13" fill="#312e81"/>
-    <text x="890" y="324" text-anchor="middle" class="chip" fill="#c4b5fd">SKILLMUX SERVER</text>
+    <rect x="822" y="306" width="136" height="26" rx="13" fill="#2e1065"/>
+    <text x="890" y="324" text-anchor="middle" class="chip" fill="#a78bfa">SKILLMUX SERVER</text>
     <circle cx="833" cy="358" r="11" fill="#a78bfa"/>
     <text x="833" y="362.5" text-anchor="middle" style="font-size: 13px; font-weight: 750" fill="#0d1117">3</text>
     <text x="856" y="365" class="card-title">Run a shared MCP service</text>
     <text x="822" y="390" class="body">Read a server checkout to serve several clients.</text>
 
-    <rect x="822" y="414" width="92" height="48" rx="10" fill="#1e293b" stroke="#475569"/>
+    <rect x="822" y="414" width="92" height="48" rx="10" fill="#21262d" stroke="#30363d"/>
     <text x="868" y="435" text-anchor="middle" class="label">AI clients</text>
     <text x="868" y="453" text-anchor="middle" class="body">one or more</text>
     <path d="M914 438H963" fill="none" stroke="#a78bfa" stroke-width="2.5" marker-end="url(#arrow-violet)"/>
     <text x="939" y="428" text-anchor="middle" class="body">HTTP</text>
-    <rect x="969" y="414" width="169" height="48" rx="10" fill="#2e1065" stroke="#7c3aed"/>
+    <rect x="969" y="414" width="169" height="48" rx="10" fill="#1e0a3c" stroke="#7c3aed"/>
     <text x="1053.5" y="435" text-anchor="middle" class="label">Skillmux server</text>
     <text x="1053.5" y="453" text-anchor="middle" class="body" style="font-size: 13px">Streamable HTTP /mcp</text>
 
-    <rect x="822" y="484" width="148" height="58" rx="10" fill="#2e1065" stroke="#7c3aed"/>
+    <rect x="822" y="484" width="148" height="58" rx="10" fill="#1e0a3c" stroke="#7c3aed"/>
     <text x="896" y="507" text-anchor="middle" class="label">Full image</text>
     <text x="896" y="530" text-anchor="middle" class="body">GTE-small included</text>
-    <rect x="982" y="484" width="156" height="58" rx="10" fill="#1e293b" stroke="#475569"/>
+    <rect x="982" y="484" width="156" height="58" rx="10" fill="#21262d" stroke="#30363d"/>
     <text x="1060" y="507" text-anchor="middle" class="label">Slim image</text>
     <text x="1060" y="530" text-anchor="middle" class="body">remote or lexical</text>
 
     <text x="822" y="570" class="body">Full image is the default deployment.</text>
   </g>
 
-  <rect x="420" y="608" width="740" height="82" rx="14" fill="#1e293b"/>
-  <text x="444" y="633" class="chip" fill="#cbd5e1">MCP TOOL CONTRACT · STDIO + HTTP</text>
+  <!-- Footer / MCP contract bar -->
+  <rect x="420" y="608" width="740" height="82" rx="14" fill="#161b22" stroke="#21262d" stroke-width="1.5"/>
+  <text x="444" y="633" class="chip" fill="#64748b">MCP TOOL CONTRACT · STDIO + HTTP</text>
   <text x="444" y="655" class="mono mono-light" style="font-size: 12px">resolve_skill → lexical + vector → RRF → optional rerank → top_k → ranked candidates</text>
   <text x="444" y="677" class="mono mono-light" style="font-size: 12px">fetch_skill → current SKILL.md bytes + SHA-256</text>
 </svg>

package/docs/assets/architecture-light.svg

@@ -4,10 +4,10 @@
 
   <defs>
     <filter id="shadow" x="-15%" y="-15%" width="130%" height="140%">
-      <feDropShadow dx="0" dy="5" stdDeviation="8" flood-color="#0f172a" flood-opacity="0.10"/>
+      <feDropShadow dx="0" dy="4" stdDeviation="8" flood-color="#94a3b8" flood-opacity="0.18"/>
     </filter>
     <marker id="arrow-teal" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto">
-      <path d="M0 0L10 5L0 10Z" fill="#0f766e"/>
+      <path d="M0 0L10 5L0 10Z" fill="#059669"/>
     </marker>
     <marker id="arrow-blue" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto">
       <path d="M0 0L10 5L0 10Z" fill="#2563eb"/>
@@ -27,7 +27,7 @@
       .subtitle {
         font-size: 16px;
         font-weight: 400;
-        fill: #475569;
+        fill: #64748b;
       }
       .card-title {
         font-size: 21px;
@@ -42,7 +42,7 @@
       .body {
         font-size: 14px;
         font-weight: 400;
-        fill: #475569;
+        fill: #64748b;
       }
       .mono {
         font-family: "DejaVu Sans Mono", Consolas, monospace;
@@ -51,7 +51,7 @@
         fill: #1e293b;
       }
       .mono-light {
-        fill: #ffffff;
+        fill: #e2e8f0;
       }
       .chip {
         font-size: 12px;
@@ -61,14 +61,17 @@
     </style>
   </defs>
 
+  <!-- Canvas -->
   <rect width="1200" height="720" rx="24" fill="#f8fafc"/>
   <rect x="1" y="1" width="1198" height="718" rx="23" fill="none" stroke="#e2e8f0" stroke-width="2"/>
 
+  <!-- Header -->
   <text x="48" y="50" class="title">One vault source of truth, three ways to use Skillmux</text>
   <text x="48" y="78" class="subtitle">Git and deployment replicate checkouts; Skillmux uses each checkout where it runs.</text>
 
+  <!-- Vault card -->
   <g filter="url(#shadow)">
-    <rect x="280" y="106" width="640" height="118" rx="18" fill="#ffffff" stroke="#cbd5e1" stroke-width="2"/>
+    <rect x="280" y="106" width="640" height="118" rx="18" fill="#ffffff" stroke="#e2e8f0" stroke-width="2"/>
     <circle cx="324" cy="147" r="18" fill="#0f172a"/>
     <path d="M314 141H327L333 147L327 153H314M320 135V159" fill="none" stroke="#ffffff" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
     <text x="358" y="144" class="card-title">Git-backed vault source of truth</text>
@@ -78,35 +81,38 @@
     <text x="819.5" y="177" text-anchor="middle" class="mono">skillmux.toml</text>
   </g>
 
-  <path d="M520 224V252H410V277" fill="none" stroke="#0f766e" stroke-width="3" marker-end="url(#arrow-teal)"/>
+  <!-- Connector lines -->
+  <path d="M520 224V252H410V277" fill="none" stroke="#059669" stroke-width="3" marker-end="url(#arrow-teal)"/>
   <path d="M720 224V252H980V277" fill="none" stroke="#7c3aed" stroke-width="3" marker-end="url(#arrow-violet)"/>
   <text x="394" y="270" text-anchor="end" class="body">client checkout</text>
   <text x="996" y="270" text-anchor="start" class="body">server checkout</text>
 
+  <!-- CLI card (emerald) -->
   <g filter="url(#shadow)">
-    <rect x="40" y="284" width="740" height="302" rx="18" fill="#ffffff" stroke="#99d5cc" stroke-width="2"/>
-    <rect x="62" y="306" width="124" height="26" rx="13" fill="#ccfbf1"/>
-    <text x="124" y="324" text-anchor="middle" class="chip" fill="#115e59">SKILLMUX CLI</text>
+    <rect x="40" y="284" width="740" height="302" rx="18" fill="#ffffff" stroke="#6ee7b7" stroke-width="2"/>
+    <rect x="62" y="306" width="124" height="26" rx="13" fill="#d1fae5"/>
+    <text x="124" y="324" text-anchor="middle" class="chip" fill="#065f46">SKILLMUX CLI</text>
     <text x="62" y="365" class="card-title">On one client machine</text>
     <text x="62" y="390" class="body">Manage native skills, add local MCP retrieval, or do both.</text>
 
-    <rect x="62" y="414" width="276" height="48" rx="10" fill="#f0fdfa" stroke="#99d5cc"/>
-    <circle cx="85" cy="438" r="11" fill="#0f766e"/>
+    <rect x="62" y="414" width="276" height="48" rx="10" fill="#ecfdf5" stroke="#6ee7b7"/>
+    <circle cx="85" cy="438" r="11" fill="#059669"/>
     <text x="85" y="442.5" text-anchor="middle" style="font-size: 13px; font-weight: 750" fill="#ffffff">1</text>
     <text x="200" y="433" text-anchor="middle" class="label" style="font-size: 17px">Manage native skills</text>
     <text x="200" y="453" text-anchor="middle" class="mono">skillmux init · sync</text>
-    <path d="M200 462V487" fill="none" stroke="#0f766e" stroke-width="2.5" marker-end="url(#arrow-teal)"/>
+    <path d="M200 462V487" fill="none" stroke="#059669" stroke-width="2.5" marker-end="url(#arrow-teal)"/>
     <rect x="62" y="493" width="276" height="49" rx="10" fill="#f8fafc" stroke="#cbd5e1"/>
     <text x="200" y="514" text-anchor="middle" class="label">Native skill directories</text>
     <text x="200" y="533" text-anchor="middle" class="body">managed core and project links</text>
 
     <text x="62" y="570" class="body">Install Skillmux CLI with</text>
     <rect x="270" y="550" width="85" height="27" rx="8" fill="#0f172a"/>
-    <text x="312.5" y="568" text-anchor="middle" class="chip" style="font-size: 10px" fill="#ffffff">BUN PACKAGE</text>
+    <text x="312.5" y="568" text-anchor="middle" class="chip" style="font-size: 10px" fill="#f1f5f9">BUN PACKAGE</text>
     <rect x="361" y="550" width="87" height="27" rx="8" fill="#f1f5f9" stroke="#cbd5e1"/>
     <text x="404.5" y="561" text-anchor="middle" class="chip" style="font-size: 10px" fill="#334155"><tspan x="404.5">LINUX</tspan><tspan x="404.5" dy="11">EXECUTABLE</tspan></text>
   </g>
 
+  <!-- MCP retrieval sub-card (blue) -->
   <g filter="url(#shadow)">
     <rect x="420" y="414" width="338" height="128" rx="10" fill="#eff6ff" stroke="#93c5fd"/>
     <circle cx="453" cy="435" r="11" fill="#2563eb"/>
@@ -122,13 +128,13 @@
     <text x="660" y="492" text-anchor="middle" class="mono">skillmux serve</text>
     <text x="660" y="511" text-anchor="middle" class="body">default: FTS5 +</text>
     <text x="660" y="527" text-anchor="middle" class="body">local GTE-small</text>
-
   </g>
 
+  <!-- Server card (violet) -->
   <g filter="url(#shadow)">
     <rect x="800" y="284" width="360" height="302" rx="18" fill="#ffffff" stroke="#c4b5fd" stroke-width="2"/>
     <rect x="822" y="306" width="136" height="26" rx="13" fill="#ede9fe"/>
-    <text x="890" y="324" text-anchor="middle" class="chip" fill="#6d28d9">SKILLMUX SERVER</text>
+    <text x="890" y="324" text-anchor="middle" class="chip" fill="#5b21b6">SKILLMUX SERVER</text>
     <circle cx="833" cy="358" r="11" fill="#7c3aed"/>
     <text x="833" y="362.5" text-anchor="middle" style="font-size: 13px; font-weight: 750" fill="#ffffff">3</text>
     <text x="856" y="365" class="card-title">Run a shared MCP service</text>
@@ -153,8 +159,9 @@
     <text x="822" y="570" class="body">Full image is the default deployment.</text>
   </g>
 
-  <rect x="420" y="608" width="740" height="82" rx="14" fill="#0f172a"/>
-  <text x="444" y="633" class="chip" fill="#cbd5e1">MCP TOOL CONTRACT · STDIO + HTTP</text>
+  <!-- Footer / MCP contract bar -->
+  <rect x="420" y="608" width="740" height="82" rx="14" fill="#1e293b"/>
+  <text x="444" y="633" class="chip" fill="#94a3b8">MCP TOOL CONTRACT · STDIO + HTTP</text>
   <text x="444" y="655" class="mono mono-light" style="font-size: 12px">resolve_skill → lexical + vector → RRF → optional rerank → top_k → ranked candidates</text>
   <text x="444" y="677" class="mono mono-light" style="font-size: 12px">fetch_skill → current SKILL.md bytes + SHA-256</text>
 </svg>