@unified-product-graph/mcp-server 0.6.0

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@unified-product-graph/mcp-server",
+  "version": "0.6.0",
+  "description": "Local MCP server for .upg files. Read and write product knowledge graphs offline.",
+  "license": "MIT",
+  "author": "The Product Creator <hello@theproductcreator.com>",
+  "homepage": "https://unifiedproductgraph.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unified-product-graph/mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/unified-product-graph/mcp-server/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "bin": {
+    "upg-mcp-server": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "scripts/install-skills.sh",
+    "scripts/claudemd-snippet.md",
+    "TOOLS.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "postbuild": "npm run generate-tools",
+    "dev": "echo '@unified-product-graph/mcp-server: standalone only. Run with: npx upg-mcp-server --file <path.upg>'",
+    "generate-tools": "tsx scripts/generate-tool-reference.ts",
+    "generate-tools:check": "tsx scripts/generate-tool-reference.ts --check",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "@unified-product-graph/core": "*",
+    "@unified-product-graph/sdk": "*",
+    "chokidar": "^4.0.0",
+    "nanoid": "^5.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.0.0",
+    "typescript": "^5.8.0",
+    "@unified-product-graph/frameworks": "*",
+    "@unified-product-graph/mcp-tooling": "*"
+  },
+  "keywords": [
+    "mcp",
+    "upg",
+    "unified-product-graph",
+    "product-management",
+    "model-context-protocol",
+    "knowledge-graph"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/claudemd-snippet.md

@@ -0,0 +1,19 @@
+## Unified Product Graph
+
+This project uses the Unified Product Graph to structure product thinking. A `.upg` file in the repo root contains the product graph.
+
+### Available Commands
+- `/upg` — See your product graph status and all available commands
+- `/upg-journey` — Guided 7-phase product journey with progress tracking
+- `/upg-init` — Bootstrap a new product graph (~5 min guided setup)
+- `/upg-explore` — Create any entity (90+ types across 32 domains)
+- `/upg-status` — Health dashboard with maturity scoring
+- `/upg-gaps` — Gap analysis across 8 business areas
+- `/upg-capture` — Capture session work into the graph
+
+### Graph Awareness
+When a `.upg` file exists, be aware of the product graph context. During conversations about product decisions, features, user research, or business strategy, offer to capture relevant insights into the graph. Don't be pushy — only suggest when the work is clearly graph-worthy (new features, strategic decisions, user insights). Routine code changes are not graph-worthy.
+
+At natural checkpoints (after commits, before session end, after design discussions), suggest running `/upg-capture` to review and save session work.
+
+Learn more: unifiedproductgraph.org

package/scripts/install-skills.sh

@@ -0,0 +1,259 @@
+#!/bin/bash
+# Install UPG skills into AI coding tool skill directories
+# Run from anywhere: bash /path/to/install-skills.sh
+#
+# Flags:
+#   --no-claudemd         Skip CLAUDE.md awareness snippet
+#   --target=claude,cursor  Install for specific IDEs (skip prompt)
+#
+# Supported targets: claude, cursor, codex, gemini, opencode, kiro
+
+set -e
+
+# ── Auto-detect package location ──────────────────────────────────────────────
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PACKAGE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+SKILLS_SOURCE="$PACKAGE_DIR/skills"
+SNIPPET_FILE="$SCRIPT_DIR/claudemd-snippet.md"
+
+# Find project root (git root or current directory)
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+if [ ! -d "$SKILLS_SOURCE" ]; then
+  echo "Error: Skills source not found at $SKILLS_SOURCE"
+  exit 1
+fi
+
+# ── Parse flags ───────────────────────────────────────────────────────────────
+
+NO_CLAUDEMD=false
+TARGET_FLAG=""
+
+for arg in "$@"; do
+  case "$arg" in
+    --no-claudemd)
+      NO_CLAUDEMD=true
+      ;;
+    --target=*)
+      TARGET_FLAG="${arg#--target=}"
+      ;;
+  esac
+done
+
+# ── IDE target definitions ────────────────────────────────────────────────────
+
+# Each target: name, directory, has MCP support
+declare -a ALL_TARGETS=("claude" "cursor" "codex" "gemini" "opencode" "kiro")
+
+target_dir() {
+  case "$1" in
+    claude)   echo ".claude/skills" ;;
+    cursor)   echo ".cursor/skills" ;;
+    codex)    echo ".codex/skills" ;;
+    gemini)   echo ".gemini/skills" ;;
+    opencode) echo ".opencode/skills" ;;
+    kiro)     echo ".kiro/skills" ;;
+  esac
+}
+
+target_label() {
+  case "$1" in
+    claude)   echo "Claude Code" ;;
+    cursor)   echo "Cursor" ;;
+    codex)    echo "Codex CLI" ;;
+    gemini)   echo "Gemini CLI" ;;
+    opencode) echo "OpenCode" ;;
+    kiro)     echo "Kiro" ;;
+  esac
+}
+
+# ── Select targets ────────────────────────────────────────────────────────────
+
+SELECTED_TARGETS=()
+
+if [ -n "$TARGET_FLAG" ]; then
+  # Parse comma-separated targets from flag
+  IFS=',' read -ra SELECTED_TARGETS <<< "$TARGET_FLAG"
+else
+  # Interactive prompt
+  echo ""
+  echo "  · ·"
+  echo "   ◉"
+  echo "  · ·"
+  echo ""
+  echo "UPG Skills Installer"
+  echo "┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄"
+  echo ""
+  echo "Where do you want to install UPG skills?"
+  echo ""
+  echo "  1) Claude Code only (.claude/skills/)"
+  echo "  2) Claude Code + Cursor (.claude/skills/ + .cursor/skills/)"
+  echo "  3) Claude Code + all supported IDEs"
+  echo "  4) Pick specific IDEs"
+  echo ""
+  echo "Supported: Claude Code, Cursor, Codex CLI, Gemini CLI, OpenCode, Kiro"
+  echo ""
+  printf "Choice [1]: "
+  read -r choice
+
+  case "${choice:-1}" in
+    1)
+      SELECTED_TARGETS=("claude")
+      ;;
+    2)
+      SELECTED_TARGETS=("claude" "cursor")
+      ;;
+    3)
+      SELECTED_TARGETS=("${ALL_TARGETS[@]}")
+      ;;
+    4)
+      echo ""
+      echo "Select IDEs (comma-separated, e.g. claude,cursor,gemini):"
+      echo "  Available: ${ALL_TARGETS[*]}"
+      printf "> "
+      read -r picks
+      IFS=',' read -ra SELECTED_TARGETS <<< "$picks"
+      ;;
+    *)
+      SELECTED_TARGETS=("claude")
+      ;;
+  esac
+fi
+
+# Validate targets
+VALID_TARGETS=()
+for t in "${SELECTED_TARGETS[@]}"; do
+  t="$(echo "$t" | tr -d ' ')"  # trim whitespace
+  dir="$(target_dir "$t")"
+  if [ -n "$dir" ]; then
+    VALID_TARGETS+=("$t")
+  else
+    echo "Warning: Unknown target '$t' — skipping"
+  fi
+done
+
+if [ ${#VALID_TARGETS[@]} -eq 0 ]; then
+  echo "Error: No valid targets selected"
+  exit 1
+fi
+
+# ── Count skills ──────────────────────────────────────────────────────────────
+
+SKILL_COUNT=0
+for skill_dir in "$SKILLS_SOURCE"/upg*; do
+  [ -d "$skill_dir" ] && SKILL_COUNT=$((SKILL_COUNT + 1))
+done
+
+# ── Install skills ────────────────────────────────────────────────────────────
+
+echo ""
+echo "Installing UPG skills..."
+echo "  Source: $SKILLS_SOURCE"
+echo ""
+
+HAS_NON_CLAUDE=false
+
+for target in "${VALID_TARGETS[@]}"; do
+  dir="$(target_dir "$target")"
+  label="$(target_label "$target")"
+  full_path="$PROJECT_ROOT/$dir"
+
+  mkdir -p "$full_path"
+
+  echo "  $label → $dir/"
+
+  for skill_dir in "$SKILLS_SOURCE"/upg*; do
+    [ -d "$skill_dir" ] || continue
+    skill_name=$(basename "$skill_dir")
+    target_link="$full_path/$skill_name"
+
+    # Remove existing (symlink or directory)
+    if [ -L "$target_link" ]; then
+      rm "$target_link"
+    elif [ -d "$target_link" ]; then
+      rm -rf "$target_link"
+    fi
+
+    # Create symlink
+    ln -s "$skill_dir" "$target_link"
+  done
+
+  echo "    ✓ $SKILL_COUNT skills symlinked"
+
+  if [ "$target" != "claude" ]; then
+    HAS_NON_CLAUDE=true
+  fi
+done
+
+# ── Note about slash commands vs skills for non-Claude IDEs ───────────────────
+
+if [ "$HAS_NON_CLAUDE" = true ]; then
+  echo ""
+  echo "  Note: /slash-command syntax is Claude Code specific. In other IDEs,"
+  echo "  the skill files work as rules/instructions that guide the AI assistant."
+  echo "  MCP tools work in any IDE that supports the Model Context Protocol."
+fi
+
+# ── CLAUDE.md awareness snippet ───────────────────────────────────────────────
+
+CLAUDEMD_UPDATED=false
+
+if [ "$NO_CLAUDEMD" = false ]; then
+  echo ""
+  CLAUDEMD_PATH="$PROJECT_ROOT/CLAUDE.md"
+
+  # Check if snippet already exists
+  if [ -f "$CLAUDEMD_PATH" ] && grep -q "## Unified Product Graph" "$CLAUDEMD_PATH" 2>/dev/null; then
+    echo "  CLAUDE.md already has UPG awareness — skipping"
+    CLAUDEMD_UPDATED=true
+  else
+    printf "Add UPG awareness to your CLAUDE.md? [Y/n] "
+    read -r answer
+
+    if [ "${answer:-Y}" != "n" ] && [ "${answer:-Y}" != "N" ]; then
+      if [ ! -f "$SNIPPET_FILE" ]; then
+        echo "Warning: Snippet file not found at $SNIPPET_FILE — skipping"
+      else
+        # Create CLAUDE.md if it doesn't exist
+        if [ ! -f "$CLAUDEMD_PATH" ]; then
+          echo "# $(basename "$PROJECT_ROOT")" > "$CLAUDEMD_PATH"
+          echo "" >> "$CLAUDEMD_PATH"
+        fi
+
+        # Append snippet
+        echo "" >> "$CLAUDEMD_PATH"
+        cat "$SNIPPET_FILE" >> "$CLAUDEMD_PATH"
+        CLAUDEMD_UPDATED=true
+      fi
+    fi
+  fi
+fi
+
+# ── Summary ───────────────────────────────────────────────────────────────────
+
+echo ""
+echo "┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄"
+
+TARGETS_LIST=""
+for target in "${VALID_TARGETS[@]}"; do
+  label="$(target_label "$target")"
+  if [ -z "$TARGETS_LIST" ]; then
+    TARGETS_LIST="$label"
+  else
+    TARGETS_LIST="$TARGETS_LIST, $label"
+  fi
+done
+
+echo "✓ $SKILL_COUNT skills installed → $TARGETS_LIST"
+if [ "$CLAUDEMD_UPDATED" = true ]; then
+  echo "✓ CLAUDE.md updated with UPG awareness"
+fi
+echo ""
+echo "Quick start:"
+echo "  /upg          — see your product graph"
+echo "  /upg-init     — bootstrap a new graph (~5 min)"
+echo "  /upg-journey  — guided product journey"
+echo ""
+echo "Skills are symlinked — edits in the source are live immediately."
+echo ""

package/skills/upg/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: upg
+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
+
+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.
+
+**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).
+
+## Tools
+
+Use the `mcp__unified-product-graph__*` MCP tools:
+- **State:** `get_product_context`, `get_graph_digest`, `get_session_context`
+- **Approaches:** `list_approaches`, `get_approach`
+- **Regions / playbooks (when relevant):** `list_regions`, `get_region`, `list_playbooks`, `get_playbook`
+
+## 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:
+
+| Approach | Question | Cartographic sense |
+|---|---|---|
+| 🧠 **Plan** | *"What should I build next?"* | Walk the coastline, mark missing contour |
+| 🔍 **Inspect** | *"What's broken?"* | Survey for hazards before approach |
+| 📊 **Prioritise** | *"What's most important?"* | Compute order of arrival from a chosen vantage |
+| 🧵 **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.).
+
+## Behavior
+
+### Step 1 — Read state
+
+Always start by checking:
+
+```
+get_product_context()      // graph exists? what's in it?
+get_session_context()      // what's the active lens?
+```
+
+Branch based on whether a graph exists.
+
+---
+
+### Branch A — Graph exists
+
+Render the orientation card (real markdown, NOT inside a code block):
+
+---
+
+```
+  · ·
+   ◉
+  · ·
+```
+# Unified Product Graph
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+
+**<Product Name>** · *<stage>* · <N> entities · <N> edges · <N> regions active
+
+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.
+
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+
+**What do you want to do?**
+
+| | Approach | Question | Common entry |
+|---|---|---|---|
+| 🧠 | **Plan** | What should I build next? | `/upg-explore <region>` · `/upg-strategy` · `/upg-journey` |
+| 🔍 | **Inspect** | What's broken? | `/upg-status` · `/upg-tree` · `/upg-inspect <entity>` |
+| 📊 | **Prioritise** | What's most important? | `/upg-prioritise` · `/upg-gaps` · `/upg-impact` |
+| 🧵 | **Trace** | Walk a path through what exists | `/upg-trace <anchor> → <destination>` · `/upg-impact <entity>` · `/upg-connect` |
+| 🪞 | **Reflect** | What should I be questioning? | `/upg-reflect` · *Five Whys · Pre-mortem · Red Team · Devil's Advocate · Second-order* |
+
+**Tell me which approach, or just describe what's on your mind.**
+
+---
+
+### 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.
+
+| 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` |
+
+---
+
+After the card, **make ONE concrete suggestion** based on the graph state. Pick the highest-value next move from this priority order:
+
+1. **No anchor entity for an active region** → suggest `/upg-explore <region>` to fill the missing scaffolding (Plan)
+2. **Anti-pattern violations present** → suggest `/upg-status` then `/upg-gaps` (Inspect)
+3. **A `decision` entity has no rationale or has gone stale** → suggest `/upg-reflect <decision>` (Reflect)
+4. **A `hypothesis` has no `evidence`** → suggest `/upg-hypothesis` to design the experiment (Plan)
+5. **A `feature` is `in_progress` with no linked outcome** → suggest `/upg-impact <feature>` (Trace)
+6. **Otherwise** → suggest `/upg-status` for a 30-second pulse
+
+Surface that one suggestion as: *"Looking at your graph, the highest-value next move is **X**. Want to start there?"*
+
+---
+
+### Branch B — No graph yet
+
+Render (real markdown, NOT a code block):
+
+---
+
+```
+  · ·
+   ◉
+  · ·
+```
+# Unified Product Graph
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+
+**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.
+
+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.
+
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+
+**Get started**
+
+| | Command | What it does |
+|---|---|---|
+| 🌱 | `/upg-init` | Bootstrap your first product graph (guided, ~5 minutes) |
+| 📋 | `/upg-template` | Start from a proven pattern (SaaS, marketplace, mobile, OSS, agency) |
+
+> Learn more: **unifiedproductgraph.org**
+
+---
+
+### Step 2 — If the user passes an argument
+
+If `/upg <something>` is given:
+
+1. **Match a subcommand:** `init`, `status`, `tree`, `gaps`, `inspect`, `reflect`, `explore`, `journey`, etc. → run the corresponding `/upg-<x>` skill.
+2. **Match an approach name:** `plan`, `inspect`, `prioritise`, `trace`, `reflect` → call `get_approach({ approach_id })` and route the user to the most-fitting skill for their graph state.
+3. **Match a region name:** `strategy`, `users_needs`, `experience_design_brand`, etc. → suggest `/upg-explore <region>`.
+4. **Free-text question:** parse intent into one of the 5 approaches, then suggest a skill.
+
+If unmatched, show the orientation card and ask: *"Did you mean one of these? Or tell me in your own words."*
+
+---
+
+### Step 3 — When the user asks "show me everything"
+
+Only then, surface the complete catalogue. Default behaviour stays focused.
+
+When asked, show this expanded view:
+
+**Cognitive skills (organised by approach)**
+
+🧠 **Plan**
+| Skill | What |
+|---|---|
+| `/upg-explore <region>` | Walk a region's canonical playbook |
+| `/upg-run <playbook-id>` | Run any canonical playbook directly |
+| `/upg-journey` | 7-phase product journey |
+| `/upg-strategy` | Vision → mission → themes → outcomes |
+| `/upg-okr` | Objectives & key results |
+| `/upg-launch` | Go-to-market planning |
+| `/upg-research` | User research session |
+| `/upg-discover` | OST-guided discovery |
+| `/upg-hypothesis` | Structured hypothesis creation |
+| `/upg-persona` | Guided persona building |
+
+🔍 **Inspect**
+| Skill | What |
+|---|---|
+| `/upg-status` | Health dashboard |
+| `/upg-tree` | Framework-aware tree view |
+| `/upg-inspect <entity>` | Deep-dive on one entity |
+| `/upg-analytics` | Product thinking metrics |
+| `/upg-verify` | Code-to-graph sync audit |
+| `/upg-diff` | What changed since last commit |
+
+📊 **Prioritise**
+| Skill | What |
+|---|---|
+| `/upg-prioritise` | RICE / WSJF / Eisenhower / ICE scoring across candidate items |
+| `/upg-gaps` | Strategic gap analysis + maturity scoring |
+| `/upg-impact` | Forward blast radius (Trace + Prioritise) |
+
+🧵 **Trace**
+| Skill | What |
+|---|---|
+| `/upg-trace <anchor> → <destination>` | Walk a directed path through the graph (canonical Trace entry) |
+| `/upg-impact <entity>` | Forward / `--upstream` causal chain |
+| `/upg-connect` | Wire relationships between entities |
+
+🪞 **Reflect**
+| Skill | What |
+|---|---|
+| `/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`)
+
+**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`)
+
+---
+
+## 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.
+- **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.
+- **Always write "Unified Product Graph" in full** when introducing it. Never abbreviate to "UPG" in user-facing text.
+- **The `.upg` file is the hero.** Open standard, portable, git-friendly. Reinforce ownership.
+- **Follow the design system.** Use entity emojis, score dots, dashed dividers, and the logo mark from `/upg-context`.
+
+After routing the user to the next skill, call:
+`update_session_context({ skill_invoked: "upg", recommendation: "<the next skill you routed to>" })`
+
+## What Changed in v0.3
+
+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.
+- **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.