@unified-product-graph/mcp-server 0.7.0 → 0.7.3

package/dist/preflight.js

@@ -18,7 +18,7 @@ for (const [label, specifier] of REQUIRED_DEPS) {
 if (missing.length > 0) {
   process.stderr.write(
     `
-\u256D\u2500 UPG MCP Server \u2014 missing dependencies \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E
+\u256D\u2500 UPG MCP Server: missing dependencies \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E
 \u2502                                                          \u2502
 ` + missing.map(
       (d) => `\u2502  \u2717 ${d}${" ".repeat(Math.max(0, 52 - d.length))}\u2502

package/dist/preflight.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/preflight.ts"],"sourcesContent":["/**\n * Preflight dependency check for the UPG MCP Server.\n *\n * ES module imports are hoisted, so if a dependency is missing the process\n * crashes before any error-handling code runs, producing silent failure\n * in Claude Code. This script checks critical deps first, prints a\n * human-readable message on failure, then dynamically imports the real\n * entry point.\n */\n\nconst REQUIRED_DEPS: Array<[label: string, specifier: string]> = [\n  ['@modelcontextprotocol/sdk', '@modelcontextprotocol/sdk/server'],\n  ['@unified-product-graph/core', '@unified-product-graph/core'],\n  ['chokidar', 'chokidar'],\n  ['nanoid', 'nanoid'],\n]\n\nconst missing: string[] = []\n\nfor (const [label, specifier] of REQUIRED_DEPS) {\n  try {\n    await import(specifier)\n  } catch {\n    missing.push(label)\n  }\n}\n\nif (missing.length > 0) {\n  process.stderr.write(\n    `\\n╭─ UPG MCP Server — missing dependencies ─────────────────╮\\n` +\n    `│                                                          │\\n` +\n    missing.map((d) =>\n      `│  ✗ ${d}${' '.repeat(Math.max(0, 52 - d.length))}│\\n`\n    ).join('') +\n    `│                                                          │\\n` +\n    `│  Run \\`npm install\\` in the project root to fix this.      │\\n` +\n    `╰──────────────────────────────────────────────────────────╯\\n\\n`,\n  )\n  process.exit(1)\n}\n\n// All deps present — boot the real server\nawait import('./index.js')\n\nexport {}\n"],"mappings":";;;AAUA,IAAM,gBAA2D;AAAA,EAC/D,CAAC,6BAA6B,kCAAkC;AAAA,EAChE,CAAC,+BAA+B,6BAA6B;AAAA,EAC7D,CAAC,YAAY,UAAU;AAAA,EACvB,CAAC,UAAU,QAAQ;AACrB;AAEA,IAAM,UAAoB,CAAC;AAE3B,WAAW,CAAC,OAAO,SAAS,KAAK,eAAe;AAC9C,MAAI;AACF,UAAM,OAAO;AAAA,EACf,QAAQ;AACN,YAAQ,KAAK,KAAK;AAAA,EACpB;AACF;AAEA,IAAI,QAAQ,SAAS,GAAG;AACtB,UAAQ,OAAO;AAAA,IACb;AAAA;AAAA;AAAA,IAEA,QAAQ;AAAA,MAAI,CAAC,MACX,kBAAQ,CAAC,GAAG,IAAI,OAAO,KAAK,IAAI,GAAG,KAAK,EAAE,MAAM,CAAC,CAAC;AAAA;AAAA,IACpD,EAAE,KAAK,EAAE,IACT;AAAA;AAAA;AAAA;AAAA;AAAA,EAGF;AACA,UAAQ,KAAK,CAAC;AAChB;AAGA,MAAM,OAAO,YAAY;","names":[]}
+{"version":3,"sources":["../src/preflight.ts"],"sourcesContent":["/**\n * Preflight dependency check for the UPG MCP Server.\n *\n * ES module imports are hoisted, so if a dependency is missing the process\n * crashes before any error-handling code runs, producing silent failure\n * in Claude Code. This script checks critical deps first, prints a\n * human-readable message on failure, then dynamically imports the real\n * entry point.\n */\n\nconst REQUIRED_DEPS: Array<[label: string, specifier: string]> = [\n  ['@modelcontextprotocol/sdk', '@modelcontextprotocol/sdk/server'],\n  ['@unified-product-graph/core', '@unified-product-graph/core'],\n  ['chokidar', 'chokidar'],\n  ['nanoid', 'nanoid'],\n]\n\nconst missing: string[] = []\n\nfor (const [label, specifier] of REQUIRED_DEPS) {\n  try {\n    await import(specifier)\n  } catch {\n    missing.push(label)\n  }\n}\n\nif (missing.length > 0) {\n  process.stderr.write(\n    `\\n╭─ UPG MCP Server: missing dependencies ─────────────────╮\\n` +\n    `│                                                          │\\n` +\n    missing.map((d) =>\n      `│  ✗ ${d}${' '.repeat(Math.max(0, 52 - d.length))}│\\n`\n    ).join('') +\n    `│                                                          │\\n` +\n    `│  Run \\`npm install\\` in the project root to fix this.      │\\n` +\n    `╰──────────────────────────────────────────────────────────╯\\n\\n`,\n  )\n  process.exit(1)\n}\n\n// All deps present; boot the real server\nawait import('./index.js')\n\nexport {}\n"],"mappings":";;;AAUA,IAAM,gBAA2D;AAAA,EAC/D,CAAC,6BAA6B,kCAAkC;AAAA,EAChE,CAAC,+BAA+B,6BAA6B;AAAA,EAC7D,CAAC,YAAY,UAAU;AAAA,EACvB,CAAC,UAAU,QAAQ;AACrB;AAEA,IAAM,UAAoB,CAAC;AAE3B,WAAW,CAAC,OAAO,SAAS,KAAK,eAAe;AAC9C,MAAI;AACF,UAAM,OAAO;AAAA,EACf,QAAQ;AACN,YAAQ,KAAK,KAAK;AAAA,EACpB;AACF;AAEA,IAAI,QAAQ,SAAS,GAAG;AACtB,UAAQ,OAAO;AAAA,IACb;AAAA;AAAA;AAAA,IAEA,QAAQ;AAAA,MAAI,CAAC,MACX,kBAAQ,CAAC,GAAG,IAAI,OAAO,KAAK,IAAI,GAAG,KAAK,EAAE,MAAM,CAAC,CAAC;AAAA;AAAA,IACpD,EAAE,KAAK,EAAE,IACT;AAAA;AAAA;AAAA;AAAA;AAAA,EAGF;AACA,UAAQ,KAAK,CAAC;AAChB;AAGA,MAAM,OAAO,YAAY;","names":[]}

package/dist/tools-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "2",
   "package": "@unified-product-graph/mcp-server",
-  "package_version": "0.7.0",
+  "package_version": "0.7.3",
   "tool_count": 93,
   "domains": [
     "context",
@@ -84,7 +84,7 @@
     },
     {
       "name": "get_session_context",
-      "description": "Read session context: which skills ran, what was recommended, current focus area. Returns `recommendations_to_avoid` — the deduped list of recommendations already given this session. Pick your next recommendation NOT in that array (data-layer dedup, not prose).",
+      "description": "Read session context: which skills ran, what was recommended, current focus area. Returns `recommendations_to_avoid`; the deduped list of recommendations already given this session. Pick your next recommendation NOT in that array (data-layer dedup, not prose).",
       "domain": "context",
       "inputSchema": {
         "type": "object",
@@ -104,7 +104,7 @@
       ],
       "source": "src/tools/context.ts:295",
       "symbol": "getSessionContext",
-      "returns": "JSON: `{ lens, skills_invoked, recommendations_given,\nrecommendations_to_avoid, focus_area, custom, skills_count, last_skill,\nlast_recommendation }`. `recommendations_to_avoid` is the deduped list of\nevery recommendation given this session — runners should filter their\nnext recommendation against this array rather than re-deriving the\ndedup rule from prose.",
+      "returns": "JSON: `{ lens, skills_invoked, recommendations_given,\nrecommendations_to_avoid, focus_area, custom, skills_count, last_skill,\nlast_recommendation }`. `recommendations_to_avoid` is the deduped list of\nevery recommendation given this session; runners should filter their\nnext recommendation against this array rather than re-deriving the\ndedup rule from prose.",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1387,7 +1387,7 @@
       "source": "src/tools/areas.ts:261",
       "symbol": "createArea",
       "returns": "JSON: `{ node, portfolio_file, written_to }`. `node` is the typed\n`UPGProductArea` record persisted to `portfolio_areas[]`.",
-      "atomicity": "atomic per write — the portfolio file is read, mutated, and\nflushed in one pass."
+      "atomicity": "atomic per write; the portfolio file is read, mutated, and\nflushed in one pass."
     },
     {
       "name": "get_area_context",
@@ -2483,7 +2483,7 @@
     },
     {
       "name": "inspect",
-      "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing inspection, invoke the /upg-inspect skill instead of calling this tool directly. — Inspect approach: path of arrival to \"what's broken?\". Returns the Inspect record + invocation params in the family-resemblance envelope. The LLM consumes `signature_hint` and emits `{ violations: [{ severity, kind, entity_id, description, fix_hint }] }` against `UPG_ANTI_PATTERNS` + the live graph. Optional `region` or `entities[]` scope the audit.",
+      "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing inspection, invoke the /upg-inspect skill instead of calling this tool directly. Inspect approach: path of arrival to \"what's broken?\". Returns the Inspect record + invocation params in the family-resemblance envelope. The LLM consumes `signature_hint` and emits `{ violations: [{ severity, kind, entity_id, description, fix_hint }] }` against `UPG_ANTI_PATTERNS` + the live graph. Optional `region` or `entities[]` scope the audit.",
       "domain": "spec",
       "inputSchema": {
         "type": "object",
@@ -2951,7 +2951,7 @@
     },
     {
       "name": "list_frameworks",
-      "description": "List the canonical `UPGFramework` definitions — the 34 curated, famous product frameworks that anchor the public catalog (spanning strategy, discovery, prioritisation, design, growth, engineering, and reflection classics). Paginated (default 50, max 200). Cursor is opaque: pass `next_cursor` from a previous response. Optional `category` is exact-match against `UPGFramework.category` and applies before pagination.",
+      "description": "List the canonical `UPGFramework` definitions; the 34 curated, famous product frameworks that anchor the public catalog (spanning strategy, discovery, prioritisation, design, growth, engineering, and reflection classics). Paginated (default 50, max 200). Cursor is opaque: pass `next_cursor` from a previous response. Optional `category` is exact-match against `UPGFramework.category` and applies before pagination.",
       "domain": "spec",
       "inputSchema": {
         "type": "object",
@@ -3313,7 +3313,7 @@
     },
     {
       "name": "prioritise",
-      "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing prioritisation, invoke the /upg-prioritise skill instead of calling this tool directly. — Prioritise approach: path of arrival to \"what's most important?\". Returns the Prioritise record + invocation params + framework metadata in the family-resemblance envelope. Both `candidates` and `framework_id` are required. The LLM looks up the framework via `get_framework`, reads its scoring spec, and emits `{ ranked: [{ entity_id, score, rationale }], framework_used }`.",
+      "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing prioritisation, invoke the /upg-prioritise skill instead of calling this tool directly. Prioritise approach: path of arrival to \"what's most important?\". Returns the Prioritise record + invocation params + framework metadata in the family-resemblance envelope. Both `candidates` and `framework_id` are required. The LLM looks up the framework via `get_framework`, reads its scoring spec, and emits `{ ranked: [{ entity_id, score, rationale }], framework_used }`.",
       "domain": "spec",
       "inputSchema": {
         "type": "object",
@@ -3354,7 +3354,7 @@
     },
     {
       "name": "reflect",
-      "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing reflection, invoke the /upg-reflect skill instead of calling this tool directly. — Reflect approach: path of arrival to \"what should I be questioning?\". Returns the Reflect record + invocation params in the family-resemblance envelope. The LLM consumes `mode` + `scope` + `signature_hint` and emits `{ prompts: [{ kind, question, target_entities? }] }`. `mode` is one of: `assumptions`, `alternatives`, `blind-spots`, `load-bearing`; omit for open reflection. `scope` accepts a region id, entity id, or `null` for whole-graph.",
+      "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing reflection, invoke the /upg-reflect skill instead of calling this tool directly. Reflect approach: path of arrival to \"what should I be questioning?\". Returns the Reflect record + invocation params in the family-resemblance envelope. The LLM consumes `mode` + `scope` + `signature_hint` and emits `{ prompts: [{ kind, question, target_entities? }] }`. `mode` is one of: `assumptions`, `alternatives`, `blind-spots`, `load-bearing`; omit for open reflection. `scope` accepts a region id, entity id, or `null` for whole-graph.",
       "domain": "spec",
       "inputSchema": {
         "type": "object",
@@ -3447,7 +3447,7 @@
     },
     {
       "name": "trace",
-      "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing tracing, invoke the /upg-trace skill instead of calling this tool directly. — Trace approach: path of arrival to \"walk a meaningful path through existing graph\". Returns the Trace record + invocation params in the family-resemblance envelope. The LLM uses `anchor` + `path` to compose `query()` calls and emits `{ trail: [{ depth, entity_id, edge_type_in }], reached: entity_id[] }`. `path` is type-shorthand: `[\"persona\",\"job\",\"feature\"]` walks persona→job→feature using the canonical edge per pair (via `resolve_edge_for_pair`). Optional `edges_override` selects non-canonical edges per hop; `null` per element means \"use canonical\".",
+      "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing tracing, invoke the /upg-trace skill instead of calling this tool directly. Trace approach: path of arrival to \"walk a meaningful path through existing graph\". Returns the Trace record + invocation params in the family-resemblance envelope. The LLM uses `anchor` + `path` to compose `query()` calls and emits `{ trail: [{ depth, entity_id, edge_type_in }], reached: entity_id[] }`. `path` is type-shorthand: `[\"persona\",\"job\",\"feature\"]` walks persona→job→feature using the canonical edge per pair (via `resolve_edge_for_pair`). Optional `edges_override` selects non-canonical edges per hop; `null` per element means \"use canonical\".",
       "domain": "spec",
       "inputSchema": {
         "type": "object",
@@ -3736,7 +3736,7 @@
           },
           "include_polymorphic_upgrades": {
             "type": "boolean",
-            "description": "When true, include a `polymorphic_with_typed_alternative` array listing polymorphic edges (e.g. node_owned_by_person, node_constrains_node) that have a more-specific typed alternative for their actual source/target pair. Opt-in only — omitted by default to avoid cluttering routine validation output. Does not affect `valid`; these are advisory suggestions."
+            "description": "When true, include a `polymorphic_with_typed_alternative` array listing polymorphic edges (e.g. node_owned_by_person, node_constrains_node) that have a more-specific typed alternative for their actual source/target pair. Opt-in only; omitted by default to avoid cluttering routine validation output. Does not affect `valid`; these are advisory suggestions."
           }
         }
       },
@@ -3804,7 +3804,7 @@
         }
       ],
       "warnings": [
-        "Default is `dry_run: true`. Pass `dry_run: false` to commit.\nIdempotent on retry — re-running after a successful commit reports\nzero changes (canonical statuses pass the validity check)."
+        "Default is `dry_run: true`. Pass `dry_run: false` to commit.\nIdempotent on retry; re-running after a successful commit reports\nzero changes (canonical statuses pass the validity check)."
       ],
       "see": [
         "migrate_type",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unified-product-graph/mcp-server",
-  "version": "0.7.0",
+  "version": "0.7.3",
   "description": "Local MCP server for .upg files. Read and write product knowledge graphs offline.",
   "license": "MIT",
   "author": "The Product Creator <hello@theproductcreator.com>",

package/skills/upg/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: upg
-description: "Unified Product Graph — your product graph, right here in the terminal"
+description: "Unified Product Graph: your product graph, right here in the terminal"
 user-invocable: true
 argument-hint: "[command or natural-language question]"
 category: aggregator
 ---
 
-# /upg — Unified Product Graph
+# /upg: Unified Product Graph
 
-You are the front door to the Unified Product Graph experience inside Claude Code. Your job is **not** to list every skill — it is to orient the user around the **5 approaches** (Plan, Inspect, Prioritise, Trace, Reflect), surface the state of their graph, and route them to **one** concrete next move.
+You are the front door to the Unified Product Graph experience inside Claude Code. Your job is **not** to list every skill; it is to orient the user around the **5 approaches** (Plan, Inspect, Prioritise, Trace, Reflect), surface the state of their graph, and route them to **one** concrete next move.
 
 If they want a phonebook, they can ask for it. The default is conversation.
 
@@ -23,7 +23,7 @@ Use the `mcp__unified-product-graph__*` MCP tools:
 
 ## The Cartographic Frame
 
-UPG is a chart of your product knowledge. The chart is organised into **10 regions** (Strategy, Users & Needs, Discovery, Market, Experience, Delivery, Engineering, Business GTM, Analytics, Operations). The chart is read through one of **5 approaches** — five paths of arrival to five different questions:
+UPG is a chart of your product knowledge. The chart is organised into **10 regions** (Strategy, Users & Needs, Discovery, Market, Experience, Delivery, Engineering, Business GTM, Analytics, Operations). The chart is read through one of **5 approaches**: five paths of arrival to five different questions:
 
 | Approach | Question | Cartographic sense |
 |---|---|---|
@@ -33,11 +33,11 @@ UPG is a chart of your product knowledge. The chart is organised into **10 regio
 | 🧵 **Trace** | *"Walk a meaningful path through what exists"* | Trace a route across charted terrain |
 | 🪞 **Reflect** | *"What should I be questioning?"* | Mark the parts of the chart that may be conjecture |
 
-Skills (`/upg-*`) are the user-invocable surfaces. Each cognitive skill inhabits one or more approaches — you can see this in its frontmatter (`approaches: [plan]`, `approaches: [inspect, prioritise]`, etc.).
+Skills (`/upg-*`) are the user-invocable surfaces. Each cognitive skill inhabits one or more approaches; you can see this in its frontmatter (`approaches: [plan]`, `approaches: [inspect, prioritise]`, etc.).
 
 ## Behavior
 
-### Step 1 — Read state
+### Step 1: Read state
 
 Always start by checking:
 
@@ -50,7 +50,7 @@ Branch based on whether a graph exists.
 
 ---
 
-### Branch A — Graph exists
+### Branch A: Graph exists
 
 Render the orientation card (real markdown, NOT inside a code block):
 
@@ -68,7 +68,7 @@ Render the orientation card (real markdown, NOT inside a code block):
 
 Maturity ● ● ● ○ ○ **3/5** *<stage label>*
 
-> **Lens:** `<active>` — <render the lens description from this table: product → "personas, outcomes, features" · engineering → "services, APIs, data flows" · design → "screens, flows, components" · growth → "funnels, channels, campaigns">. Say "switch to [product|engineering|design|growth]" to change.
+> **Lens:** `<active>`; <render the lens description from this table: product → "personas, outcomes, features" · engineering → "services, APIs, data flows" · design → "screens, flows, components" · growth → "funnels, channels, campaigns">. Say "switch to [product|engineering|design|growth]" to change.
 
 ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
 
@@ -88,15 +88,15 @@ Maturity ● ● ● ○ ○ **3/5** *<stage label>*
 
 ### Routing Hints
 
-When the user selects an approach (or you infer one from their description), pre-call the listed tool before routing — it gives the downstream skill the data it needs without a cold start.
+When the user selects an approach (or you infer one from their description), pre-call the listed tool before routing; it gives the downstream skill the data it needs without a cold start.
 
 | Approach | Pre-call | Entry skill |
 |---|---|---|
-| 🧠 Plan | `mcp__unified-product-graph__list_playbooks()` — see region options | `/upg-explore <region>` |
-| 🔍 Inspect | `mcp__unified-product-graph__get_graph_digest()` — health metrics | `/upg-status` |
-| 📊 Prioritise | `mcp__unified-product-graph__get_graph_digest()` — gap + coverage data | `/upg-gaps` |
-| 🧵 Trace | `mcp__unified-product-graph__get_product_context()` — find anchor entities | `/upg-impact <entity>` |
-| 🪞 Reflect | `mcp__unified-product-graph__get_session_context()` — recent decisions | `/upg-reflect` |
+| 🧠 Plan | `mcp__unified-product-graph__list_playbooks()`; see region options | `/upg-explore <region>` |
+| 🔍 Inspect | `mcp__unified-product-graph__get_graph_digest()`; health metrics | `/upg-status` |
+| 📊 Prioritise | `mcp__unified-product-graph__get_graph_digest()`; gap + coverage data | `/upg-gaps` |
+| 🧵 Trace | `mcp__unified-product-graph__get_product_context()`; find anchor entities | `/upg-impact <entity>` |
+| 🪞 Reflect | `mcp__unified-product-graph__get_session_context()`; recent decisions | `/upg-reflect` |
 
 ---
 
@@ -113,7 +113,7 @@ Surface that one suggestion as: *"Looking at your graph, the highest-value next
 
 ---
 
-### Branch B — No graph yet
+### Branch B: No graph yet
 
 Render (real markdown, NOT a code block):
 
@@ -127,13 +127,13 @@ Render (real markdown, NOT a code block):
 # Unified Product Graph
 ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
 
-**Structure your product thinking as a connected graph — right here in the terminal.**
+**Structure your product thinking as a connected graph, right here in the terminal.**
 
-Your graph lives in a `.upg` file — a portable JSON format you own and track with git. No cloud required, no lock-in.
+Your graph lives in a `.upg` file; a portable JSON format you own and track with git. No cloud required, no lock-in.
 
-UPG is a chart of your product knowledge across **10 regions** — Strategy, Users & Needs, Discovery, Market, Experience, Delivery, Engineering, Business GTM, Analytics, Operations.
+UPG is a chart of your product knowledge across **10 regions**: Strategy, Users & Needs, Discovery, Market, Experience, Delivery, Engineering, Business GTM, Analytics, Operations.
 
-You read the chart through **5 approaches** — Plan, Inspect, Prioritise, Trace, Reflect.
+You read the chart through **5 approaches**: Plan, Inspect, Prioritise, Trace, Reflect.
 
 ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
 
@@ -148,7 +148,7 @@ You read the chart through **5 approaches** — Plan, Inspect, Prioritise, Trace
 
 ---
 
-### Step 2 — If the user passes an argument
+### Step 2: If the user passes an argument
 
 If `/upg <something>` is given:
 
@@ -161,7 +161,7 @@ If unmatched, show the orientation card and ask: *"Did you mean one of these? Or
 
 ---
 
-### Step 3 — When the user asks "show me everything"
+### Step 3: When the user asks "show me everything"
 
 Only then, surface the complete catalogue. Default behaviour stays focused.
 
@@ -212,18 +212,18 @@ When asked, show this expanded view:
 |---|---|
 | `/upg-reflect [scope]` | Five Whys / Pre-mortem / Red Team / Devil's Advocate / Second-order |
 
-**Tooling** (graph state operations — `/upg-init`, `/upg-capture`, `/upg-push`, `/upg-pull`, `/upg-snapshot`, `/upg-rollback`, `/upg-migrate`, `/upg-import`, `/upg-export`, `/upg-feedback`, `/upg-template`, `/upg-workspace`)
+**Tooling** (graph state operations; `/upg-init`, `/upg-capture`, `/upg-push`, `/upg-pull`, `/upg-snapshot`, `/upg-rollback`, `/upg-migrate`, `/upg-import`, `/upg-export`, `/upg-feedback`, `/upg-template`, `/upg-workspace`)
 
-**Schema** (spec evolution — `/upg-schema-update`, `/upg-schema-consolidate`, `/upg-schema-evolve`, `/upg-schema-health`, `/upg-schema-changelog`, `/upg-schema-edges`)
+**Schema** (spec evolution; `/upg-schema-update`, `/upg-schema-consolidate`, `/upg-schema-evolve`, `/upg-schema-health`, `/upg-schema-changelog`, `/upg-schema-edges`)
 
-**Meta** (system reference — `/upg-context`, `/upg-design-system`)
+**Meta** (system reference; `/upg-context`, `/upg-design-system`)
 
 ---
 
 ## Key Principles
 
-- **Orient, don't overwhelm.** Default view shows 5 approaches and ONE next move — never a wall of 40 skills.
-- **Approaches are the spine.** Plan, Inspect, Prioritise, Trace, Reflect — these are the conversational entry points. Skills implement them.
+- **Orient, don't overwhelm.** Default view shows 5 approaches and ONE next move; never a wall of 40 skills.
+- **Approaches are the spine.** Plan, Inspect, Prioritise, Trace, Reflect; these are the conversational entry points. Skills implement them.
 - **Tooling is plumbing.** `/upg-init`, `/upg-push`, `/upg-snapshot` etc. are real and important, but they don't belong in the main view. They surface when the user needs them, or when they ask "show me everything."
 - **State-aware.** If a graph exists, show its state and one concrete suggestion. If not, show the get-started path.
 - **Listen before you list.** When the user describes a problem in their own words, route by approach, not by guessing skill names.
@@ -238,8 +238,8 @@ After routing the user to the next skill, call:
 
 If a returning user asks "what's new?":
 
-- **5 approaches** (Plan / Inspect / Prioritise / Trace / Reflect) replace the old "14 canonical workflows" framing — cognitive operations, not menus.
+- **5 approaches** (Plan / Inspect / Prioritise / Trace / Reflect) replace the old "14 canonical workflows" framing; cognitive operations, not menus.
 - **23 region-anchored playbooks** organised under 10 canonical regions.
-- **89 MCP tools** (was 40) across 6 buckets — primitives, approaches, catalog readers, spec metadata, mutations, workspace ops.
-- **Reflect** is now first-class — `/upg-reflect` walks Five Whys, Pre-mortem, Red Team, Devil's Advocate, or Second-order Thinking against any entity, region, or the whole graph.
-- **Skill frontmatter** declares `category` (cognitive / tooling / schema / meta) and `approaches` — agents and the aggregator can route by these instead of grepping descriptions.
+- **89 MCP tools** (was 40) across 6 buckets; primitives, approaches, catalog readers, spec metadata, mutations, workspace ops.
+- **Reflect** is now first-class; `/upg-reflect` walks Five Whys, Pre-mortem, Red Team, Devil's Advocate, or Second-order Thinking against any entity, region, or the whole graph.
+- **Skill frontmatter** declares `category` (cognitive / tooling / schema / meta) and `approaches`; agents and the aggregator can route by these instead of grepping descriptions.

package/skills/upg-analytics/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: upg-analytics
-description: "Product thinking metrics — hypothesis velocity, coverage ratio, evidence density"
+description: "Product thinking metrics: hypothesis velocity, coverage ratio, evidence density"
 user-invocable: true
 argument-hint: ""
 category: cognitive
 approaches: [inspect]
 ---
 
-# /upg-analytics — Product Thinking Metrics
+# /upg-analytics: Product Thinking Metrics
 
 You are a fast analytics dashboard. Your job: fetch metrics, render a dashboard, suggest ONE action. No questions. No interaction. Just the numbers and what they mean.
 
@@ -41,17 +41,17 @@ The digest pre-computes all metrics in one call (~500 tokens):
 - **coverage_ratio:** Use `chains.persona_with_job` / `chains.persona_total` + deeper chain stats
 - **evidence_density:** Use `counts.by_type` to compute (learning + insight) / hypothesis
 - **orphan_rate:** Use `health.orphan_rate` directly
-- **stale_entity_rate:** Not available locally — skip or note "cloud only"
+- **stale_entity_rate:** Not available locally; skip or note "cloud only"
 
 **1 tool call. This must be fast.**
 
 ## Output Format
 
-Render as real markdown — NOT inside a code block. Use this structure:
+Render as real markdown, NOT inside a code block. Use this structure:
 
 ---
 
-## 📐 Graph Analytics — [Product Name]
+## 📐 Graph Analytics: [Product Name]
 
 ### Hypothesis Velocity
 
@@ -62,7 +62,7 @@ Show each status with its status dot and count, then a filled bar for % resolved
   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░ 58% resolved
 ```
 
-If zero hypotheses exist, show: "No hypotheses yet — run `/upg-hypothesis` to start testing your riskiest assumptions."
+If zero hypotheses exist, show: "No hypotheses yet; run `/upg-hypothesis` to start testing your riskiest assumptions."
 
 ### Coverage Ratio
 
@@ -73,7 +73,7 @@ Show persona count with complete chains out of total, plus a filled bar:
   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░ 75%
 ```
 
-If zero personas, show: "No personas yet — run `/upg-persona` to define who you're building for."
+If zero personas, show: "No personas yet; run `/upg-persona` to define who you're building for."
 
 ### Evidence Density
 
@@ -86,7 +86,7 @@ Show evidence counts and ratio:
 
 Interpret the ratio:
 - 0.0 = "no evidence yet"
-- < 0.5 = "thin — most hypotheses lack evidence"
+- < 0.5 = "thin; most hypotheses lack evidence"
 - 0.5–1.0 = "growing"
 - 1.0+ = "healthy"
 - 2.0+ = "evidence-rich"
@@ -115,20 +115,20 @@ Show orphan rate as a filled bar:
 One short paragraph: what stands out, and what's the single fastest win? End with a specific command suggestion.
 
 Example:
-> Your hypothesis pipeline is moving — 58% resolved. But 4 are still untested. The fastest win is picking one and designing an experiment.
+> Your hypothesis pipeline is moving: 58% resolved. But 4 are still untested. The fastest win is picking one and designing an experiment.
 > → `/upg-hypothesis` to test your riskiest assumption
 
 ## Key Principles
 
 - **FAST.** 2-3 tool calls. No interaction. No questions. Just the dashboard.
-- **Filled bars** for all percentages — max 22 characters (▓ for filled, ░ for empty).
+- **Filled bars** for all percentages; max 22 characters (▓ for filled, ░ for empty).
 - **Interpret, don't just report.** "1.08 evidence per hypothesis <- healthy" beats "ratio: 1.08".
 - **ONE recommendation.** Pick the metric that needs the most attention and suggest the matching skill.
 - **This is NOT `/upg-status --quick`** (5 quick signals) or **/upg-gaps** (deep maturity scoring + action plan). This is the quantitative dashboard.
 - **Follow the design system.** Entity emojis, status dots, dashed dividers, consistent formatting from `/upg-context`.
 
 ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your .upg file is yours — open standard, portable, git-friendly.
+Your .upg file is yours: open standard, portable, git-friendly.
 unifiedproductgraph.org
 
 After rendering your recommendation, call:

package/skills/upg-capture/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: upg-capture
-description: "Capture session work into the graph — review what happened and propose entities"
+description: "Capture session work into the graph: review what happened and propose entities"
 user-invocable: true
 argument-hint: "[--quick] [description]"
 category: tooling
 ---
 
-# /upg-capture — Capture Session Work into the Graph
+# /upg-capture: Capture Session Work into the Graph
 
-You are a Unified Product Graph session analyst. Your job is to review what happened in the current session — conversations, decisions, code changes, designs — and propose entities to add to the graph. You're the bridge between "work that happened" and "knowledge that persists."
+You are a Unified Product Graph session analyst. Your job is to review what happened in the current session (conversations, decisions, code changes, designs) and propose entities to add to the graph. You're the bridge between "work that happened" and "knowledge that persists."
 
 **Before producing any output, load the design system:** `/upg-context` (interaction principles, design system, lens rules) and `/upg-context-intelligence` (benchmarks, user personas, product philosophy).
 
@@ -70,7 +70,7 @@ Before scanning, call `get_changes()`. If there are recent changes from a previo
 
 ### Step 1: Gather Session Context
 
-Open with: "Let's capture what happened — this takes about **~3 minutes**."
+Open with: "Let's capture what happened; this takes about **~3 minutes**."
 
 Silently review the session by checking:
 
@@ -97,10 +97,10 @@ Present a summary of what you found:
 
 I found <N> things worth capturing from this session:
 
-1. 📦 **<Feature name>** — <brief description>
-2. ⚗️ **<Hypothesis>** — <brief description>
-3. 📝 **<Learning>** — <brief description>
-4. 🎯 **<Decision>** — <brief description>
+1. 📦 **<Feature name>**: <brief description>
+2. ⚗️ **<Hypothesis>**: <brief description>
+3. 📝 **<Learning>**: <brief description>
+4. 🎯 **<Decision>**: <brief description>
 
 Shall I walk through each one? You can approve, edit, or skip each.
 ```
@@ -121,16 +121,16 @@ Capture 1 of <N>
 
 Type: feature
 Description: Adapts the user's daily plan based on their morning
-energy check-in — high energy gets productive tasks, low energy
+energy check-in; high energy gets productive tasks, low energy
 gets a gentle rest plan.
 
 Connected to: 🎯 One Day at a Time
 Related to: ⚗️ Ultra-low-friction morning check-in
 
 1. ✅ Add to graph as-is
-2. ✏️ Edit before adding — tell me what to change
+2. ✏️ Edit before adding; tell me what to change
 3. ⏭️ Skip this one
-4. Not sure yet — we can skip this or come back to it
+4. Not sure yet; we can skip this or come back to it
 ```
 
 STOP. Wait for the user's response before proceeding to the next.
@@ -139,11 +139,11 @@ If they choose edit, ask what to change, apply it, then confirm.
 
 #### Quick mode (`--quick`)
 
-Present ALL proposed entities as numbered cards in a single output — no pausing between them:
+Present ALL proposed entities as numbered cards in a single output; no pausing between them:
 
 ```
 ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-📸 SESSION CAPTURE — QUICK MODE
+📸 SESSION CAPTURE; QUICK MODE
 ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
 
 1 · 📦 **Mood-aligned daily planner**
@@ -188,13 +188,13 @@ If a proposed entity conflicts with existing graph data, present the conflict:
 ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
 
 This session discussed pivoting to **enterprise users**, but your
-graph has 👤 Maya — Content Creator as the primary persona (consumer/creator).
+graph has 👤 Maya: Content Creator as the primary persona (consumer/creator).
 
 1. 🔄 Update Maya's context to include enterprise angle
 2. ➕ Add a new persona for enterprise users alongside Maya
 3. 🗄️ Archive Maya and create the enterprise persona
-4. ⏭️ Skip — I'll figure this out later
-5. Not sure yet — we can skip this or come back to it
+4. ⏭️ Skip; I'll figure this out later
+5. Not sure yet; we can skip this or come back to it
 ```
 
 ### Step 5: Capture Summary
@@ -218,7 +218,7 @@ Your graph: <N> entities · <N> edges · <N> domains
 
 ## Close with Smart Ending
 
-Check the graph for the biggest gap across the 8 business areas. Recommend ONE next skill. **Vary the recommendation** — don't always suggest the same global gap. Prioritize:
+Check the graph for the biggest gap across the 8 business areas. Recommend ONE next skill. **Vary the recommendation**: don't always suggest the same global gap. Prioritize:
 
 1. **What's most relevant to what was just captured** (e.g. if we captured a new persona, suggest `/upg-research` to deepen it)
 2. **The biggest gap** only if nothing was captured that suggests a more specific next step
@@ -249,7 +249,7 @@ After rendering your recommendation, call:
 - New components → `design_component` entities
 - Test files → may indicate `experiment` entities
 
-### Type Guidance — Feature vs Task vs Bug
+### Type Guidance: Feature vs Task vs Bug
 **`feature`** = a user-facing capability ("Users can launch clips from the library")
 **`task`** = a shipped work item that isn't user-facing ("Migrated WebSocket to binary protocol")
 **`bug`** = a fix for broken behavior ("Right-click context menu now works")
@@ -270,5 +270,5 @@ Don't overload `feature` with infrastructure, polish, or fixes. Ask yourself: "W
 - **Follow the design system.** Entity emojis, score dots, filled bars, dashed dividers as defined in /upg-context.
 
 ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your `.upg` file is yours — open standard, portable, git-friendly.
+Your `.upg` file is yours: open standard, portable, git-friendly.
 unifiedproductgraph.org

package/skills/upg-connect/SKILL.md

@@ -7,11 +7,11 @@ category: cognitive
 approaches: [plan]
 ---
 
-# /upg-connect — Connect UPG Entities
+# /upg-connect: Connect UPG Entities
 
 > **Tip:** `/upg-connect` is most useful when your graph already has disconnected entities. Run `/upg-tree` first to see your current graph structure and spot the gaps.
 
-You are a Unified Product Graph relationship expert. Your job is to create meaningful, spec-valid connections between entities in the product graph. You understand the 20 core edge types and know when each applies — and when a direct connection is wrong.
+You are a Unified Product Graph relationship expert. Your job is to create meaningful, spec-valid connections between entities in the product graph. You understand the 20 core edge types and know when each applies, and when a direct connection is wrong.
 
 **Before producing any output, read the design system:** /upg-context for emoji mappings, score dots, bar styles, and formatting rules.
 
@@ -91,7 +91,7 @@ Check whether a valid edge type exists between these two entity types. The edge
 - solution -> hypothesis (via `solution_has_hypothesis`)
 - etc.
 
-**Invalid paths (no direct edge — suggest intermediate entities):**
+**Invalid paths (no direct edge; suggest intermediate entities):**
 
 | User wants to connect | Why it's wrong | Correct path |
 |---|---|---|
@@ -150,18 +150,18 @@ After creating an edge, look at the target node and suggest what should come nex
 ## Key Principles
 
 - **Never connect blindly.** Always check that the edge type is valid for the source and target types.
-- **Explain the relationship.** Don't just say "connected" — describe what the edge means semantically.
+- **Explain the relationship.** Don't just say "connected"; describe what the edge means semantically.
 - **Bridge gaps.** When a direct connection isn't valid, offer to build the intermediate path.
 - **Show the chain.** After connecting, show the full path from product root to the new leaf.
 - **Follow the design system.** Entity emojis, score dots, filled bars, dashed dividers as defined in /upg-context.
 - **Direction matters.** Edges are directional. `persona_pursues_job` goes FROM persona TO job, not the reverse.
-- **Reference the standard.** These edge types are defined by the Unified Product Graph standard — they're not arbitrary. Each one has semantic meaning. Mention unifiedproductgraph.org when explaining why a connection is or isn't valid.
+- **Reference the standard.** These edge types are defined by the Unified Product Graph standard; they're not arbitrary. Each one has semantic meaning. Mention unifiedproductgraph.org when explaining why a connection is or isn't valid.
 
 After creating connections and rendering your recommendation, call:
 `update_session_context({ skill_invoked: "upg-connect", recommendation: "<the next skill you recommended>" })`
 
 ```
 ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your .upg file is yours — open standard, portable, git-friendly.
+Your .upg file is yours: open standard, portable, git-friendly.
 unifiedproductgraph.org
 ```