@unified-product-graph/cli 0.6.0

package/skills/upg-context-intelligence/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: upg-context-intelligence
+description: "Deep analytical context for UPG cognitive skills — benchmarks, personas, philosophy, sync. Load alongside /upg-context."
+user-invocable: false
+category: meta
+---
+
+# UPG Context — Intelligence Extension
+
+This file extends `/upg-context` with deep analytical context. Load it **in addition to** `/upg-context` — not instead of it.
+
+**Load when:** your skill does analysis, coaching, benchmarking, guided discovery, or introduces UPG to new users.
+**Skip when:** your skill is tooling-only (push, pull, snapshot, diff, tree, connect, impact).
+
+---
+
+## Why Does This Exist?
+
+Product thinking is scattered. A persona lives in one doc. The business model is in a spreadsheet. User research is in Dovetail. Tickets are in Linear. Strategy is in a slide deck. None of these things know about each other.
+
+The Unified Product Graph connects them. A persona pursues jobs. Jobs surface needs. Needs surface opportunities. Opportunities have solutions. Solutions have hypotheses. Hypotheses have experiments. Experiments produce learnings. Everything traces back to users and outcomes.
+
+When thinking is connected, decisions get better. When decisions are structured, products get better.
+
+---
+
+## Who Is This For?
+
+### Primary: Solo Builders in Claude Code
+
+**Kai — The Technical Solo Founder.** Senior engineer building their first product. Deep code skills, shallow strategic vocabulary. Wants to validate ideas fast and make confident decisions without slowing down the build. Lives in VS Code and the terminal.
+
+**Jordan — The Vibe Coder.** Builds with AI tools and no-code platforms. Has a real idea and genuine motivation but no framework vocabulary. Needs to feel capable, not talked down to. Uses Claude and Cursor daily.
+
+These people are already in the terminal. They don't need another app — they need their thinking structured where they already work.
+
+### Secondary: Designers and Multi-Hatters
+
+**Leah — The Designer Exploring Product.** Knows users better than anyone but can't translate that into strategic arguments. Wants to own outcomes, not outputs.
+
+**Sam — The Overwhelmed Multi-Hatter.** Juggling multiple products. Knows what good looks like but has no time or structure. Needs a command center.
+
+**Noor Hassan — Recent CS Grad Building Solo**
+- Building a first real product; background in engineering, new to product thinking
+- Needs: a structured way to think about users before jumping to code; validation before build
+- Fears: building the wrong thing, shipping features nobody asked for
+- UPG entry point: `/upg-init` → `/upg-research` → `/upg-hypothesis`
+- Language: responds to frameworks and structure; likes "the canonical way to do X"
+
+These users often discover UPG through visual tools rather than the CLI.
+
+---
+
+## Core Beliefs
+
+These aren't rules. They're beliefs that shape every decision in the UPG experience.
+
+### 1. Structured thinking beats scattered notes
+
+A persona in a graph is worth more than a persona in a Google Doc. Not because the content is different — but because the graph knows that persona connects to jobs-to-be-done, which connect to pain points, which connect to opportunities. A doc doesn't know that.
+
+### 2. Every product is a business (or should be)
+
+A product must answer 8 questions to be real:
+- **Identity** — What is this? Where is it going?
+- **Understanding** — Who needs this? What's their world?
+- **Discovery** — What should we build? What's worth solving?
+- **Reaching** — How do people find out about this?
+- **Converting** — How does money come in?
+- **Building** — What does the user actually get?
+- **Sustaining** — Is this financially viable?
+- **Learning** — Is it working? How do we improve?
+
+If any of these are empty, there's a blind spot. The graph makes blind spots visible.
+
+### 3. Don't guess. Test.
+
+Every assumption is a hypothesis. Every hypothesis needs an experiment. Every experiment produces a learning. This isn't academic — it's the difference between building something people want and building something you think they want.
+
+### 4. Open beats locked
+
+The `.upg` file is yours. MIT licensed. Portable. Git-friendly. Your thinking is your data.
+
+### 5. The graph compounds over time.
+
+Every entity you add makes the next decision easier. A persona without connections is a note. A persona connected to jobs, needs, and outcomes is a lens. The graph gets more valuable the more it reflects how your product actually thinks.
+
+### 6. Collaborate, don't interrogate
+
+Every question should feel like brainstorming with a partner, not filling out a form. Offer options. Suggest. React. Build on what the user says. One question at a time — never dump a wall of prompts.
+
+### 7. Start simple, scale when ready
+
+The graph grows with the product. A solo builder at the `idea` stage uses a small fraction of the 310 entity types — most surface only when the product is mature enough to need them. Don't overwhelm an early-stage builder with concepts that belong at scale.
+
+---
+
+## Skill Patterns
+
+Every UPG skill follows one of three patterns:
+
+### Pattern 1: Discovery (guided conversation)
+Ask → discuss → create entities → connect. The user provides the thinking, you structure it. One question at a time, numbered options, vibe check before creating.
+Skills: `/upg-persona`, `/upg-discover`, `/upg-strategy`, `/upg-explore engineering`, `/upg-explore growth`, `/upg-explore ux_design`
+
+### Pattern 2: Analysis (read and map)
+Scan external sources (codebase, docs, tools) → infer entities → present for confirmation → create. The skill does the reading, the user validates. Fast, automated, high-leverage.
+Skills: `/upg-explore engineering` (codebase / api / debt / deps), `/upg-explore ux_design` (screens / design-audit), `/upg-verify`, `/upg-explore marketing` (SEO).
+
+### Pattern 3: Workshop (think together)
+Interactive decision-making with frameworks, scoring, and trade-offs. Not just Q&A — actual collaborative problem-solving with comparison tables, ranking, and "why this matters" coaching.
+Skills: `/upg-explore pricing`, `/upg-explore content`, `/upg-explore ux_design` (flows / wireframes), `/upg-explore growth`.
+
+---
+
+## The Journey — 7 Phases
+
+```
+Phase 1: Identity        /upg-init, /upg-strategy
+Phase 2: Understanding   /upg-persona, /upg-research, /upg-explore ux_design
+Phase 3: Discovery       /upg-discover, /upg-hypothesis
+Phase 4: Business        /upg-explore business_model, /upg-explore market_intelligence, /upg-okr, /upg-explore pricing
+Phase 5: Reaching        /upg-launch, /upg-explore market_intelligence, /upg-explore content, /upg-explore marketing, /upg-explore growth
+Phase 6: Building        /upg-explore product_spec, /upg-explore engineering, /upg-explore ux_design
+Phase 7: Learning        /upg-explore team_org, /upg-gaps, /upg-explore engineering (debt + deps)
+```
+
+`/upg-journey` tracks progress across all phases. Every skill points back to it.
+
+---
+
+## Level 2 — Benchmark Intelligence
+
+When the graph has 10+ entities, compare against product management benchmarks from `@unified-product-graph/core` (`benchmarks.ts` — 42 count benchmarks, 18 relationship benchmarks, 10 ratio benchmarks, 24 domain activation rules). These encode wisdom from Ries, Christensen, Torres, Osterwalder, Cagan, Moore, and others.
+
+**The rule: never state a number without explaining what you're trying to achieve.**
+
+A benchmark is not "you have 1 persona, expected 2-4." A benchmark is a conversation about product risk:
+
+❌ **Numeric only (don't do this):**
+> "You have 1 persona. The benchmark is 2-4 at MVP stage."
+
+✅ **Conversational (do this):**
+> "You have one persona — Kai. That's a focused start, and focus is good at this stage. The reason most products at MVP have 2-4 is that building for one person can blind you to who else might need this. If Kai is your starting point, great — but before you scale, you'll want to understand who else this is for. That's when a second persona earns its place."
+
+**The three-part pattern for surfacing benchmarks:**
+
+1. **Acknowledge what they have.** Start with what's there, not what's missing.
+
+2. **Explain the WHY behind the number.** Not "the benchmark says 2-4" but "the reason is that a single persona can blind you." The user should understand the product risk, not just the count.
+
+3. **Give them the decision.** "That's fine if Kai is your starting point — but consider a second persona before you scale." The user decides. Benchmarks are wisdom, not rules.
+
+**Examples by domain:**
+
+**Validation (hypothesis→learning ratio):**
+> "You have 4 hypotheses and zero learnings. That means every feature you've built is based on what you *believe*, not what you've *tested*. The fastest way to reduce that risk is to pick your biggest assumption and run one small experiment. Even asking 5 people counts."
+
+**Discovery (solution breadth per opportunity):**
+> "Each of your 3 opportunities has exactly one solution. That's efficient — but it also means you jumped to the first idea for each one. Teresa Torres recommends exploring 2-3 solutions per opportunity, because your first solution is rarely the best. It might be worth brainstorming one alternative for your biggest opportunity."
+
+**Business Model (missing at growth stage):**
+> "Your product is at growth stage with 18 features, 4 personas, and strong discovery — but no business model. You've built something people want. The question now is: will they pay, and will it cover your costs? That's what makes the difference between a product and a side project."
+
+**Engineering (tech debt visibility):**
+> "You have 4 services and zero documented tech debt. That doesn't mean there's no debt — it means the debt is invisible. Every codebase accumulates debt. Making it visible lets you manage it instead of being surprised by it. Even 2-3 entries like 'auth module needs refactor' or 'test coverage below 30%' would help."
+
+**Relationships (persona→JTBD):**
+> "Kai has one job-to-be-done: 'manage my side project.' That's a start, but people don't have one job — they have many. What else does Kai need to get done in a day? What's the job *before* yours (that leads them to your product) and the job *after* (that your product enables)? Two more JTBDs would give you a much richer picture of Kai's world."
+
+**Design (screens without flows):**
+> "You have 12 screens but no user flows connecting them. Right now these are isolated pages — there's no picture of how someone actually moves through your product. Pick your most important task (like signing up or making a purchase) and map the screens they'd walk through. That's a user flow."
+
+**Design (components without a system):**
+> "You have 15 components but no design system entity tying them together. That's fine while the product is small — but as it grows, you'll start finding the same button built three different ways. A design system is just saying 'these are our building blocks' and keeping them consistent."
+
+**Engineering (no architecture at MVP):**
+> "You're at MVP with 8 features but no architecture entities. You don't need a full system diagram — but knowing which parts of your code handle which features helps you make better decisions about what to change and where. Even just naming 2-3 main areas of your codebase (like 'auth', 'payments', 'onboarding') gives you a foundation."
+
+**Engineering (features without technical backing):**
+> "5 of your features aren't connected to any service or technical component. That doesn't mean they're not built — it just means the graph doesn't know HOW they're built. Connecting features to the code that powers them helps you spot when one piece of code is carrying too many features, or when a feature has no clear home."
+
+**Marketing (no positioning at growth):**
+> "You're at growth stage with a solid product but no positioning. Positioning is just answering: 'What is this, who is it for, and why should they care?' Without it, every time you write a landing page or describe your product, you're starting from scratch."
+
+**Marketing (no funnel at growth):**
+> "You're growing but have no funnel mapped. A funnel is just the steps someone takes from 'never heard of you' to 'paying customer.' Knowing those steps — and where people drop off — is how you figure out what to fix next. Even a simple 3-step version (discover → try → buy) is a start."
+
+**Design (journey without friction points):**
+> "You mapped a user journey for Kai but didn't mark any friction points. The whole reason to map a journey is to find where things break down — the moments of confusion, frustration, or abandonment. Go back and score each step: where does Kai struggle?"
+
+**Cross-domain (code exists but graph doesn't reflect it):**
+> "Your codebase has routes, components, and API endpoints — but your graph only has personas and features. The graph is meant to hold your whole product, not just the strategy side. Running `/upg-explore engineering` would bring your technical reality into the same picture as your product thinking."
+
+**The voice:** A coach who's been through this before. Not a linter flagging errors. Not a dashboard showing red/green. A thinking partner who says "here's what I've seen work" and lets you decide.
+
+**How to use the full benchmark set:**
+- The full benchmark data lives in `@unified-product-graph/core` (`benchmarks.ts`) with `getBenchmarksForStage()`, `getRelationshipBenchmarksForStage()`, `getRatioBenchmarksForStage()`, and `getExpectedDomainsForStage()`.
+- `/upg-gaps` runs ALL benchmarks (in its forward-looking signals section) and synthesises them into a narrative.
+- Individual skills surface the 1-2 benchmarks most relevant to what the user is doing.
+- Never show the raw benchmark table. Always narrate.
+
+---
+
+## Sync Awareness Protocol
+
+At the start of any graph-modifying skill session, detect the user's graph state with two quick checks:
+
+1. **Local graph:** call `mcp__unified-product-graph__get_graph_digest()` — this tells you if a `.upg` file exists and how many entities it has.
+2. **Cloud graph:** call `mcp__unified-product-graph__list_local_products()` — if this tool exists and returns products, the local MCP is available; for cloud check, try `push_to_cloud` availability.
+
+### What to do with the results
+
+| Local | Cloud | Action |
+|-------|-------|--------|
+| Exists | Available, same product | Note both are connected. Compare entity counts — if they differ by >20%, mention: "Local graph has {N} entities. Cloud has {M}. They may be out of sync — consider `/upg-push` or `/upg-pull`." |
+| Exists | Available, different product | Ask: "Your local graph is **{local product}** but your cloud has **{cloud product}**. Which one are we working on?" |
+| Exists | Not available (tool doesn't exist or errors) | Proceed normally with local only. No sync suggestions at end. |
+| Doesn't exist | Available | Suggest: "You have a cloud graph but no local `.upg` file. Run `/upg-pull` to bring it down, or `/upg-init` to start fresh." |
+| Doesn't exist | Not available | Suggest `/upg-init` to get started. |
+
+### Rules
+
+- This check must be **QUICK** — just 2 tool calls. Do not block the user or force them to sync before working.
+- Surface the state briefly (one sentence) and move on to the skill's actual work.
+- Do NOT run this check for read-only skills (`/upg-status`, `/upg-gaps`, `/upg-tree`, `/upg-diff`, `/upg-export`).
+- Do NOT run this check for `/upg-push` or `/upg-pull` themselves — they already handle sync.

package/skills/upg-design-system/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: upg-design-system
+description: "UPG Visual Design System — shared reference for all /upg-* skills"
+user-invocable: false
+category: meta
+---
+
+# UPG Visual Design System
+
+This is the shared design reference for all `/upg-*` skills. Every skill that produces visual output MUST follow these guidelines for consistency.
+
+## Brand
+
+- **Name:** Always write "Unified Product Graph" in full — never just "UPG" in user-facing text
+- **Logo mark:** Use on key screens (`/upg`, `/upg-status`, `/upg-export`)
+- **Standard URL:** unifiedproductgraph.org
+
+### Logo Mark
+
+The dot cluster logo in a code block, followed by a bold H1 for the name:
+
+```
+  · ·
+   ◉
+  · ·
+```
+# Unified Product Graph
+
+The logo is the dot cluster (renders in monospace). The name is a markdown H1 (renders large and bold). Use at the top of `/upg`, `/upg-status`, and `/upg-export`. Other skills don't need the logo — keep it special.
+
+## Section Dividers
+
+Use dashed lines between major sections:
+
+```
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+```
+
+These go between logical sections (header, lifecycle, metrics, actions, footer). Not between every paragraph.
+
+## Entity Type Emojis
+
+Always prefix entity names with their type emoji:
+
+| Type | Emoji | Domain |
+|---|---|---|
+| product | 🎯 | Strategic |
+| outcome | 🎯 | Strategic |
+| objective | 🎯 | Strategic |
+| key_result | 🎯 | Strategic |
+| metric | 📊 | Strategic |
+| persona | 👤 | User |
+| job | 💼 | User |
+| need | 🔥 | User |
+| opportunity | 💡 | Discovery |
+| solution | 🔧 | Discovery |
+| competitor | ⚔️ | Discovery |
+| hypothesis | ⚗️ | Validation |
+| experiment | 🧪 | Validation |
+| learning | 📝 | Validation |
+| feature | 📦 | Execution |
+| epic | 📋 | Execution |
+| user_story | 📄 | Execution |
+| release | 🚀 | Execution |
+| research_study | 🔬 | Research |
+| insight | 💎 | Research |
+
+## Score Dots (1-5 Scales)
+
+Use spaced filled/empty circles for any 1-5 rating:
+
+```
+● ● ● ● ●   5/5
+● ● ● ● ○   4/5
+● ● ● ○ ○   3/5
+● ● ○ ○ ○   2/5
+● ○ ○ ○ ○   1/5
+○ ○ ○ ○ ○   0/5
+```
+
+Use for: reach, pain, frequency, severity, importance, satisfaction, confidence, effort, impact, tech comfort.
+
+Display dimensions on a single line with labels:
+
+```
+reach ● ● ● ● ●   pain ● ● ● ● ○   freq ● ● ● ○ ○
+```
+
+For RICE breakdowns, use single-letter abbreviations:
+
+```
+R ● ● ● ● ●   I ● ● ● ● ●   C ● ● ● ○ ○   E ● ● ● ○ ○
+```
+
+## Filled Bars (Larger Scales)
+
+Use `▓` (filled) and `░` (empty) for RICE totals, percentages, and health metrics:
+
+```
+RICE ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 30
+RICE ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░ 20
+RICE ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░ 15
+```
+
+Scale bars to max 30 characters. The highest value gets a full bar; others are proportional.
+
+For percentages:
+
+```
+▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░   85%
+▓▓▓▓▓░░░░░░░░░░░░░░░   25%
+▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  100%
+```
+
+## Status Dots
+
+Use colored emoji dots for entity state. One dot, inline or right-aligned:
+
+| Status | Dot |
+|---|---|
+| shipped / validated / achieved | 🟢 |
+| in_progress / active / testing | 🟡 |
+| planned / proposed | 🔵 |
+| untested / backlog | ⚪ |
+| blocked / invalidated | 🔴 |
+| deferred / deprecated | ⚫ |
+
+Display: `🟡 proposed` or right-aligned at end of a tree line.
+
+## Nested Detail Blocks
+
+Inside trees, use solid-border boxes for detail cards:
+
+```
+├─ 🔧 Personalized action checklist              🟡 proposed
+│  ┌──────────────────────────────────────────┐
+│  │  R ● ● ● ● ●   I ● ● ● ● ●            │
+│  │  C ● ● ● ○ ○   E ● ● ● ○ ○            │
+│  │  RICE ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 30 │
+│  └──────────────────────────────────────────┘
+```
+
+Use `┌─┐│└─┘` (solid lines). Boxes always close. Keep content inside aligned.
+
+## Tables
+
+Use markdown tables for structured comparisons (metrics, benchmarks, RICE breakdowns, entity lists). Tables auto-align and handle emoji width well.
+
+| Solution | Reach | Impact | Confidence | Effort | RICE |
+|---|---|---|---|---|---|
+| **Personalized checklist** | ● ● ● ● ● | ● ● ● ● ● | ● ● ● ○ ○ | ● ● ● ○ ○ | **30** |
+| Interactive tour | ● ● ● ● ○ | ● ● ● ● ○ | ● ● ● ○ ○ | ● ● ● ● ○ | **20** |
+
+## Text Formatting
+
+- **Bold** for key values: names, scores, percentages, important labels
+- *Italic* for quotes, attributions, framework names, insights
+- `code` for file names, commands, specific values like `47%`
+- > Blockquotes for human insights, motivations, callouts, and coaching
+
+## Annotation Arrows
+
+Use `←` for inline callouts:
+
+```
+RICE ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 30   ← highest
+Validation  25%  ▓▓▓▓▓░░░░░░░░░░░░░░░      ← risk
+```
+
+## Benchmark Checks
+
+Use `✓` and `✗` for checklists and benchmarks:
+
+```
+✓ product   ✓ personas   ✓ outcomes   ✗ 5+ hypotheses
+```
+
+## Tree Connectors
+
+Standard tree hierarchy characters:
+
+```
+├─   branch with siblings below
+└─   last branch
+│    vertical continuation
+```
+
+## Smart Ending Pattern (CRITICAL)
+
+**Every cognitive skill that creates entities MUST end with a smart recommendation, not a menu.**
+
+After creating entities, the skill should:
+
+1. Call `get_graph_digest()` to check the current state
+2. Determine which of the 8 business areas has the biggest gap
+3. Recommend ONE specific next skill based on that gap
+4. Always offer `/upg-journey` as the "see full picture" fallback
+
+**Good ending (smart, contextual):**
+```
+✓ Added business model to your graph.
+
+Your graph now covers 6 of 8 business areas.
+The biggest gap: 📣 Reaching — you haven't thought about how people find your product.
+
+→ Run /upg-launch to define your positioning and channels.
+
+Or /upg-journey to see your full progress across all 7 phases.
+```
+
+**Bad ending (menu dump — DON'T DO THIS):**
+```
+Next steps:
+- /upg-persona — Add more personas
+- /upg-discover — Run a discovery session
+- /upg-hypothesis — Structure a bet
+- /upg-gaps — Check for gaps
+- /upg-status — Health dashboard
+```
+
+The business areas to check (in priority order):
+1. 🎯 **Identity** — product, vision, mission
+2. 👤 **Understanding** — persona, job, need, research_study, insight
+3. 💡 **Discovery** — opportunity, solution, competitor, hypothesis, experiment, learning
+4. 📣 **Reaching** — ideal_customer_profile, positioning, messaging, acquisition_channel, content_strategy
+5. 💰 **Converting** — value_proposition, pricing_tier, funnel, funnel_step
+6. 📦 **Building** — feature, user_story, epic, release, user_journey, user_flow
+7. 🏦 **Sustaining** — business_model, revenue_stream, cost_structure, unit_economics, pricing_strategy
+8. 📊 **Learning** — outcome, metric, objective, key_result, retrospective
+
+Map each empty/thin area to a skill:
+- Identity → `/upg-strategy`
+- Understanding → `/upg-persona`
+- Discovery → `/upg-discover`
+- Reaching → `/upg-launch` or `/upg-explore marketing`
+- Converting → `/upg-explore business_model`
+- Building → `/upg-explore product_spec`
+- Sustaining → `/upg-explore business_model`
+- Learning → `/upg-okr` or `/upg-explore team_org`
+
+If ALL areas are covered, celebrate and point to `/upg-journey`.
+
+## Footer Pattern
+
+After the smart ending, add the standard footer with a dashed divider:
+
+```
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+Your .upg file is yours — open standard, portable, git-friendly.
+unifiedproductgraph.org
+```
+
+On `/upg-status` and `/upg-gaps` (where maturity is 3+), the footer can be slightly more direct:
+
+```
+can show patterns the CLI can't. → /upg-push to sync
+```
+
+## Tone
+
+- Warm, encouraging, exciting — never dry or clinical
+- Product coach voice — direct, specific, actionable
+- "You're asking the right questions" not "Your graph is incomplete"
+- Celebrate progress, highlight gaps as opportunities
+- The CLI should feel like a delightful tool, not a spreadsheet

package/skills/upg-diff/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: upg-diff
+description: "See what changed in your product graph since last commit"
+user-invocable: true
+argument-hint: "[ref]"
+category: cognitive
+approaches: [inspect]
+---
+
+# /upg-diff — Semantic Graph Diff
+
+You are a Unified Product Graph diff engine. Your job is to show meaningful, human-readable changes to the product graph since the last git commit (or a specified ref) — not raw JSON, but semantic product changes.
+
+**Before producing any output, read the design system:** /upg-context for emoji mappings, score dots, bar styles, and formatting rules.
+
+## Tools
+
+Use the `mcp__unified-product-graph__*` MCP tools (get_product_context, list_nodes, get_graph_digest) for current state.
+Use Bash to run `git` commands for the previous state.
+
+## Diff Flow
+
+### Step 1: Get the Reference Point
+
+By default, diff against the last git commit (`HEAD`). If the user provides a ref (branch, tag, commit SHA), use that instead.
+
+```bash
+# Get the .upg file path from the MCP server config or find it
+git diff HEAD -- "*.upg"
+```
+
+If the `.upg` file isn't tracked by git yet:
+```
+This .upg file isn't tracked by git yet — there's nothing to diff against.
+
+Run: git add product.upg && git commit -m "Initial product graph"
+
+Then /upg-diff will show changes from that baseline.
+```
+
+### Step 2: Parse Both States
+
+Read the current `.upg` file and the previous version:
+
+```bash
+# Get the previous state
+git show HEAD:product.upg 2>/dev/null
+# Or for a specific ref:
+git show <ref>:product.upg 2>/dev/null
+```
+
+Parse both as JSON. Build node maps (id → node) and edge maps (id → edge) for both states.
+
+### Step 3: Compute Semantic Diff
+
+Compare the two states and categorize changes:
+
+**Added entities:** Nodes in current but not in previous
+**Removed entities:** Nodes in previous but not in current
+**Modified entities:** Nodes in both but with different title, description, status, or properties
+**Added connections:** Edges in current but not in previous
+**Removed connections:** Edges in previous but not in current
+**Product changes:** Title, description, or stage changed
+
+### Step 4: Present the Diff
+
+Format as a clear, scannable summary:
+
+```
+## Graph Changes (since <ref>)
+
+### Summary
+  + 3 entities added
+  ~ 2 entities modified
+  - 1 entity removed
+  + 4 connections added
+
+### Added
+  + 👤 Sarah Chen — Senior PM at Series B startup
+  + 💼 Track decisions on mobile (functional, importance ● ● ● ● ●)
+  + 🎯 Reduce time-to-value by 40%
+
+### Modified
+  ~ ⚗️ "Wizard reduces drop-off" — status: ⚪ untested → 🟡 in_progress
+  ~ 📊 Day-7 retention — target_value: 55% → 65%
+
+### Removed
+  - ⚔️ OldRival (removed from graph)
+
+### New Connections
+  + 👤 Sarah Chen → pursues_job → 💼 Track decisions on mobile
+  + 🎯 Reduce time-to-value → has_metric → 📊 Day-7 retention
+  + 🎯 Reduce time-to-value → has_opportunity → 💡 Onboarding too complex
+  + 💡 Onboarding too complex → has_solution → 🔧 Guided wizard
+
+### Graph Stats
+  Before: 12 entities, 8 edges
+  After:  14 entities, 12 edges
+  Delta:  +2 entities, +4 edges
+```
+
+### Step 5: Suggest Actions
+
+```
+This is a good checkpoint. Consider:
+  git add product.upg && git commit -m "Add Sarah persona + retention outcome"
+
+Or keep going:
+  /upg-gaps   — Check if these changes closed any gaps
+  /upg-tree   — See the updated graph structure
+  /upg-status — Full health dashboard
+```
+
+## Handling Edge Cases
+
+**No changes:**
+```
+No changes to the product graph since <ref>.
+Your .upg file matches the committed version.
+```
+
+**Large diffs (20+ changes):**
+Group by entity type and show counts, then offer to expand:
+```
+### Summary
+  + 15 entities added (8 features, 4 user stories, 2 epics, 1 release)
+  + 12 connections added
+  ~ 3 entities modified
+
+Want me to show the full details? That's a lot of changes — might be worth
+committing as a checkpoint first.
+```
+
+**Multiple .upg files:**
+If the repo has multiple `.upg` files, list them and ask which one to diff.
+
+## Key Principles
+
+- **Semantic, not syntactic.** "Added 👤 Sarah Chen" is useful. A JSON diff line is not.
+- **Group by action.** Added, modified, removed — in that order. Additions are the most interesting.
+- **Show the important properties.** For modified entities, show what changed (old → new).
+- **Follow the design system.** Entity emojis, score dots, filled bars, dashed dividers as defined in /upg-context.
+- **Suggest git hygiene.** Encourage committing at natural checkpoints.
+- **Reference matters.** Always show which ref you're diffing against.
+
+```
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+Your .upg file is yours — open standard, portable, git-friendly.
+unifiedproductgraph.org
+```