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

package/skills/upg-schema-consolidate/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: upg-schema-consolidate
-description: "Evaluate whether entity types should merge — shared properties, structural analysis, migration path"
+description: "Evaluate whether entity types should merge: shared properties, structural analysis, migration path"
 user-invocable: false
 audience: advanced
 argument-hint: "[type_a] [type_b] or [domain]"
 category: schema
 ---
 
-> ⚠️ **Advanced skill** — intended for UPG contributors and power users who understand the spec internals. Not for general use. Running mutation skills (schema-update, schema-consolidate, schema-evolve) without understanding the cascade can corrupt your graph.
+> ⚠️ **Advanced skill**: intended for UPG contributors and power users who understand the spec internals. Not for general use. Running mutation skills (schema-update, schema-consolidate, schema-evolve) without understanding the cascade can corrupt your graph.
 
-# /upg-schema-consolidate — Entity Type Consolidation
+# /upg-schema-consolidate: Entity Type Consolidation
 
-You are a schema analyst. Your job is to evaluate whether two or more entity types should be consolidated into a single type with a discriminator property, or kept separate. You do this through structured analysis — not gut feeling.
+You are a schema analyst. Your job is to evaluate whether two or more entity types should be consolidated into a single type with a discriminator property, or kept separate. You do this through structured analysis, not gut feeling.
 
 **This is an internal development skill for schema governance.**
 
@@ -60,7 +60,7 @@ Overlap: X/Y properties shared (Z%)
 
 This is the critical test. Check 4 structural dimensions:
 
-**2a. Parent types** — Do they have the same canonical parent?
+**2a. Parent types**: Do they have the same canonical parent?
 ```
 Read UPG_VALID_CHILDREN in grammar/hierarchy.ts
 - type_a parent: bounded_context
@@ -68,7 +68,7 @@ Read UPG_VALID_CHILDREN in grammar/hierarchy.ts
 → DIFFERENT parents = structural divergence
 ```
 
-**2b. Child types** — Do they have the same children?
+**2b. Child types**: Do they have the same children?
 ```
 Search UPG_VALID_CHILDREN for entries where value = type_a or type_b
 - type_a children: technical_debt_item
@@ -76,7 +76,7 @@ Search UPG_VALID_CHILDREN for entries where value = type_a or type_b
 → DIFFERENT children = structural divergence
 ```
 
-**2c. Edge types** — Do they participate in the same relationships?
+**2c. Edge types**: Do they participate in the same relationships?
 ```
 Search UPG_EDGE_CATALOG in catalog/edge-catalog.ts for both types
 - type_a edges: context_has_decision, decision_has_technical_debt_item
@@ -84,7 +84,7 @@ Search UPG_EDGE_CATALOG in catalog/edge-catalog.ts for both types
 → DIFFERENT edges = semantic divergence
 ```
 
-**2d. Domain membership** — Are they in the same domain?
+**2d. Domain membership**: Are they in the same domain?
 ```
 Check registry/domains.ts
 - type_a: engineering
@@ -102,15 +102,15 @@ Check registry/domains.ts
 
 Check how each type is used in practice:
 
-**3a. Skill references** — Which skills create/reference each type?
+**3a. Skill references**: Which skills create/reference each type?
 ```
 grep -r "type_a\|type_b" packages/upg-mcp-server/skills/
 ```
 
-**3b. Lens relevance** — Do they appear in different lenses?
+**3b. Lens relevance**: Do they appear in different lenses?
 If type_a is surfaced in the engineering lens and type_b in the design lens, consolidation would muddy lens clarity.
 
-**3c. Real-world mental models** — Would users think of these as "the same thing with a label" or "fundamentally different activities"?
+**3c. Real-world mental models**: Would users think of these as "the same thing with a label" or "fundamentally different activities"?
 
 This is where you engage the human. Ask:
 
@@ -134,7 +134,7 @@ Usage context: [SAME/DIFFERENT]
 Recommendation: [explanation]
 ```
 
-### Step 5: If Consolidating — Migration Design
+### Step 5: If Consolidating: Migration Design
 
 If the decision is to consolidate:
 
@@ -170,7 +170,7 @@ Parent migration:
 
 **5d. Cascade the change** using `/upg-schema-update`
 
-### Step 5 (Alternative): If Keeping Separate — Document Why
+### Step 5 (Alternative): If Keeping Separate: Document Why
 
 If the decision is to keep separate, create a brief decision record:
 
@@ -222,14 +222,14 @@ These consolidations have already happened in UPG and can be referenced as patte
 | `risk_item` | `risk` | `risk_domain: 'program'` | 0.1.0 |
 | `architecture_decision`, `design_decision`, `product_decision` | `decision` | `layer: 'engineering' \| 'design' \| 'product'` | 0.2.0 |
 | `jtbd` | `job` | (renamed, no discriminator) | 0.2.0 |
-| `how_might_we` | `design_question` | (renamed — framework-neutral) | 0.2.0 |
+| `how_might_we` | `design_question` | (renamed; framework-neutral) | 0.2.0 |
 | `sli`, `slo`, `sla` | `service_level_indicator`, `service_level_objective`, `service_level_agreement` | (acronyms expanded) | 0.2.0 |
-| `customer_segment_bm`, `target_customer_segment` | `market_segment` | — | 0.2.0 |
-| `channel_bm` | `distribution_channel` | — | 0.2.0 |
+| `customer_segment_bm`, `target_customer_segment` | `market_segment` | | 0.2.0 |
+| `channel_bm` | `distribution_channel` | | 0.2.0 |
 | `campaign` | `growth_campaign` | (disambiguated from marketing_campaign_plan) | 0.2.0 |
 | `segment` | `behavioral_segment` | (disambiguated from market_segment) | 0.2.0 |
-| `package` | `pricing_tier` | — | 0.2.0 |
-| `internal_doc` | `document` | `document_type` — audience=internal | 0.2.0 |
+| `package` | `pricing_tier` | | 0.2.0 |
+| `internal_doc` | `document` | `document_type`; audience=internal | 0.2.0 |
 
 ## Key Principles
 

package/skills/upg-schema-edges/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: upg-schema-edges
-description: "Edge design advisor — when to add an edge, naming, direction, edge vs hierarchy vs entity"
+description: "Edge design advisor: when to add an edge, naming, direction, edge vs hierarchy vs entity"
 user-invocable: false
 audience: advanced
 argument-hint: "[source_type] [target_type] or [relationship description]"
 category: schema
 ---
 
-> ⚠️ **Advanced skill** — intended for UPG contributors and power users who understand the spec internals. Not for general use. Running mutation skills (schema-update, schema-consolidate, schema-evolve) without understanding the cascade can corrupt your graph.
+> ⚠️ **Advanced skill**: intended for UPG contributors and power users who understand the spec internals. Not for general use. Running mutation skills (schema-update, schema-consolidate, schema-evolve) without understanding the cascade can corrupt your graph.
 
-# /upg-schema-edges — Edge Design Advisor
+# /upg-schema-edges: Edge Design Advisor
 
-You are an edge design advisor. Your job is to help decide whether a relationship between entities should be an edge, a parent-child hierarchy link, or a relationship entity — and if it's an edge, how to name and direct it.
+You are an edge design advisor. Your job is to help decide whether a relationship between entities should be an edge, a parent-child hierarchy link, or a relationship entity, and if it's an edge, how to name and direct it.
 
 **This is an internal development skill for schema governance.**
 
@@ -34,7 +34,7 @@ Every relationship between entities in UPG can be expressed as one of three thin
 **When to use:**
 - The child is a **component** of the parent (journey_step inside user_journey)
 - The child is a **decomposition** of the parent (epic inside feature)
-- The child's **lifecycle** is bound to the parent — delete the parent, delete the children
+- The child's **lifecycle** is bound to the parent; delete the parent, delete the children
 - There's a clear **containment** relationship (acceptance_criterion inside user_story)
 
 **Test:** "Would you delete all [children] if you deleted the [parent]?"
@@ -53,10 +53,10 @@ Every relationship between entities in UPG can be expressed as one of three thin
 **What it is:** A semantic relationship between two independent entities. Defined in `UPG_EDGE_CATALOG` (in `catalog/edge-catalog.ts`). Both entities can exist without the other.
 
 **When to use:**
-- The entities are **independent** — either can exist alone
+- The entities are **independent**: either can exist alone
 - The relationship is **cross-domain** (design → engineering)
 - There are **multiple valid** relationships between the same pair (a service can both `powers` and `has_technical_debt`)
-- The relationship is **discovery-dependent** — you might not know it exists when entities are first created
+- The relationship is **discovery-dependent**: you might not know it exists when entities are first created
 
 **Test:** "Can [source] and [target] each exist meaningfully on their own?"
 - Yes → edge
@@ -129,7 +129,7 @@ The source entity is the actor, the target is the receiver:
 ```
 ✅ debt_blocks_feature  (debt is blocking the feature)
 ✅ fix_resolved_bug     (fix resolved the bug)
-❌ feature_blocked_by_debt  (inverted — make debt the source)
+❌ feature_blocked_by_debt  (inverted; make debt the source)
 ```
 
 **Rule 3: Specific over generic**
@@ -203,8 +203,8 @@ grep "SOURCE_.*_TARGET" packages/upg-spec/src/catalog/edge-catalog.ts
 
 **If a pair already has an edge**, consider whether you need a second edge or if the existing one covers your semantics. Two edges between the same pair should represent genuinely different relationships:
 ```
-✅ service:feature has both 'service_powers_feature' AND 'service_has_feature' — different semantics
-❌ service:feature having 'service_connects_to_feature' AND 'service_links_to_feature' — same thing
+✅ service:feature has both 'service_powers_feature' AND 'service_has_feature'; different semantics
+❌ service:feature having 'service_connects_to_feature' AND 'service_links_to_feature'; same thing
 ```
 
 ## Edge Map Hygiene Audit
@@ -234,7 +234,7 @@ DUPLICATE SEMANTICS
 ```
 
 ### Check 3: Missing Reverse Lookups
-Important edges that only go one direction but should be queryable both ways. Not proposing reverse edges — just flagging that queries might need to follow edges backwards:
+Important edges that only go one direction but should be queryable both ways. Not proposing reverse edges; just flagging that queries might need to follow edges backwards:
 ```
 ONE-WAY EDGES (consider if reverse queries are needed)
 | Edge | Direction | Reverse query use case |
@@ -279,7 +279,7 @@ Value: { source_type: '[source_type]', target_type: '[target_type]', description
 
 - **Hierarchy is structural, edges are semantic.** Parent-child says "X contains Y." Edges say "X relates to Y in this specific way."
 - **When in doubt, prefer an edge.** Hierarchy is harder to change later. Edges can be added and removed without restructuring the graph.
-- **800+ edges is fine if each is distinct.** The problem isn't quantity — it's duplicates, orphans, and vague naming.
+- **800+ edges is fine if each is distinct.** The problem isn't quantity; it's duplicates, orphans, and vague naming.
 - **Direction matters for queries.** Think about how users will traverse: "show me what blocks this feature" requires debt → feature, not feature → debt.
 - **Edges are cheap, relationship entities are expensive.** Only create a relationship entity when the relationship itself has a lifecycle and multiple properties.
 

package/skills/upg-schema-evolve/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: upg-schema-evolve
-description: "Domain deep-dive — audit entity coverage, surface gaps, design new types from real needs"
+description: "Domain deep-dive: audit entity coverage, surface gaps, design new types from real needs"
 user-invocable: false
 audience: advanced
 argument-hint: "[domain] or [feedback/requirement description]"
 category: schema
 ---
 
-> ⚠️ **Advanced skill** — intended for UPG contributors and power users who understand the spec internals. Not for general use. Running mutation skills (schema-update, schema-consolidate, schema-evolve) without understanding the cascade can corrupt your graph.
+> ⚠️ **Advanced skill**: intended for UPG contributors and power users who understand the spec internals. Not for general use. Running mutation skills (schema-update, schema-consolidate, schema-evolve) without understanding the cascade can corrupt your graph.
 
-# /upg-schema-evolve — Schema Evolution Through Domain Analysis
+# /upg-schema-evolve: Schema Evolution Through Domain Analysis
 
-You are a schema evolution advisor. Your job is to help the UPG schema grow thoughtfully — not by adding types speculatively, but by analysing real domains, real user feedback, and real cross-domain requirements to determine what's genuinely missing.
+You are a schema evolution advisor. Your job is to help the UPG schema grow thoughtfully, not by adding types speculatively, but by analysing real domains, real user feedback, and real cross-domain requirements to determine what's genuinely missing.
 
 **This is an internal development skill for schema governance.**
 
@@ -21,7 +21,7 @@ You are a schema evolution advisor. Your job is to help the UPG schema grow thou
 - User feedback reveals a concept that doesn't map to any existing type
 - A new use case surfaces that existing types can't model
 - Cross-domain requirements emerge (e.g., "design handoff to engineering needs a bridge entity")
-- Before a batch of new types — to think first, add second
+- Before a batch of new types; to think first, add second
 
 ## Input Modes
 
@@ -79,8 +79,8 @@ Map the domain against the real-world activities it should support. Use industry
 - Testing (→ qa_testing domain)
 - Security (→ security domain)
 - Observability & monitoring (→ devops domain)
-- Performance (? — gap?)
-- Documentation (? — partial, documentation_template in content domain)
+- Performance (? gap?)
+- Documentation (? partial, documentation_template in content domain)
 
 **Design domain reference activities:**
 - User research (→ ux_research domain)
@@ -93,7 +93,7 @@ Map the domain against the real-world activities it should support. Use industry
 - Interaction design (interaction_spec ✓)
 - Accessibility (→ accessibility domain)
 - Content design (→ content domain)
-- Handoff to engineering (? — gap? screen_implements_feature edge exists but no handoff entity)
+- Handoff to engineering (? gap? screen_implements_feature edge exists but no handoff entity)
 
 Present gaps as opportunities:
 
@@ -125,7 +125,7 @@ Option A: New type `performance_benchmark`
   + Has unique properties (target_metric, current_value, threshold)
   + Would parent to service or api_endpoint
   + Edge: benchmark_measures_endpoint
-  - Only 1-2 instances per service — low cardinality
+  - Only 1-2 instances per service; low cardinality
   - Overlaps with `metric` (which already has value tracking)
 
 Option B: Use `metric` with tag `performance`
@@ -171,7 +171,7 @@ MISSING BRIDGES
 
 ### 2c. Bridging Entity Candidates
 
-Sometimes the gap isn't an edge — it's a missing entity that lives at the boundary:
+Sometimes the gap isn't an edge; it's a missing entity that lives at the boundary:
 
 ```
 BOUNDARY ENTITY CANDIDATES
@@ -228,10 +228,10 @@ Options:
   B) Edge with properties: team_adopts_design_system (with adoption_rate on the edge)
   C) Use metric type with tags: metric { tags: ['adoption'], linked to team + design_system }
 
-→ RECOMMENDATION: Option C — adoption is a measurement, not a thing. Use metric.
+→ RECOMMENDATION: Option C; adoption is a measurement, not a thing. Use metric.
 ```
 
-### 3b. If New Type Needed — Design It
+### 3b. If New Type Needed: Design It
 
 Follow this template:
 
@@ -257,14 +257,14 @@ Lens relevance: Engineering (primary), DevOps (secondary)
 Skill: Would be created by `/upg-explore engineering` (or a new `/upg-explore performance` playbook if the domain emerges as separate).
 
 Similar existing types:
-  - metric — but lacks SLA/threshold semantics
-  - service_level_indicator / service_level_objective — in DevOps domain, more operational than development-focused
+  - metric: but lacks SLA/threshold semantics
+  - service_level_indicator / service_level_objective: in DevOps domain, more operational than development-focused
   
 Decision: [ADD / DEFER / USE EXISTING]
 Reason: [why]
 ```
 
-### 3c. Before Adding — Consolidation Check
+### 3c. Before Adding: Consolidation Check
 
 Before approving any new type, run a quick consolidation check:
 
@@ -294,7 +294,7 @@ EVOLUTION SUMMARY
 ✅ Covered by existing schema: [list]
 🆕 New types recommended: [list with reasons]
 🔗 New edges recommended: [list]
-🔀 Consolidation candidates: [list — run /upg-schema-consolidate]
+🔀 Consolidation candidates: [list; run /upg-schema-consolidate]
 ⏸️ Deferred: [list with revisit conditions]
 
 Next: /upg-schema-update [type] to implement approved additions

package/skills/upg-schema-health/SKILL.md

@@ -1,27 +1,27 @@
 ---
 name: upg-schema-health
-description: "Schema usage audit — dead types, empty properties, orphan patterns, real vs theoretical"
+description: "Schema usage audit: dead types, empty properties, orphan patterns, real vs theoretical"
 user-invocable: false
 audience: advanced
 argument-hint: "[path to .upg file] or [domain]"
 category: schema
 ---
 
-> ⚠️ **Advanced skill** — intended for UPG contributors and power users who understand the spec internals. Not for general use. Running mutation skills (schema-update, schema-consolidate, schema-evolve) without understanding the cascade can corrupt your graph.
+> ⚠️ **Advanced skill**: intended for UPG contributors and power users who understand the spec internals. Not for general use. Running mutation skills (schema-update, schema-consolidate, schema-evolve) without understanding the cascade can corrupt your graph.
 
-# /upg-schema-health — Schema Usage Audit
+# /upg-schema-health: Schema Usage Audit
 
-You are a schema health auditor. Your job is to compare what the UPG schema defines against what real graphs actually contain — surfacing dead types, empty properties, unused edges, and patterns the schema didn't anticipate.
+You are a schema health auditor. Your job is to compare what the UPG schema defines against what real graphs actually contain; surfacing dead types, empty properties, unused edges, and patterns the schema didn't anticipate.
 
 **This is the feedback loop for schema governance.** Without it, we add types speculatively and never learn if they were right.
 
 ## When to Use
 
-- After adding new entity types — are they being used?
-- Before a major schema evolution — what's dead weight?
-- When a user reports confusion — is the schema matching their mental model?
-- Periodically (quarterly) — schema hygiene check
-- When onboarding a new domain (e.g., Felix bringing engineering) — what does their graph actually contain?
+- After adding new entity types; are they being used?
+- Before a major schema evolution; what's dead weight?
+- When a user reports confusion; is the schema matching their mental model?
+- Periodically (quarterly): schema hygiene check
+- When onboarding a new domain (e.g., Felix bringing engineering); what does their graph actually contain?
 
 ## Input Modes
 
@@ -102,10 +102,10 @@ Design (22 of 22 unused):
 ```
 
 **Classify each dead type:**
-- **Too new** — added recently, hasn't had time to be used (check `since` in entity-meta)
-- **Too specialised** — only relevant at scale-up/enterprise tier (check tier classification)
-- **Wrong abstraction** — the concept exists in the user's world but the type doesn't match their mental model
-- **Genuinely unnecessary** — deprecation candidate
+- **Too new**: added recently, hasn't had time to be used (check `since` in entity-meta)
+- **Too specialised**: only relevant at scale-up/enterprise tier (check tier classification)
+- **Wrong abstraction**: the concept exists in the user's world but the type doesn't match their mental model
+- **Genuinely unnecessary**: deprecation candidate
 
 ### 2c. Surprise Types
 
@@ -120,7 +120,7 @@ SURPRISE TYPES (in graph but not in schema)
 | "tech_spike" | 2 | upg-capture | → Candidate for new type? Or map to 'investigation'? |
 ```
 
-These are gold — they tell you what users actually need that the schema doesn't provide.
+These are gold; they tell you what users actually need that the schema doesn't provide.
 
 ## Phase 3: Property Usage Analysis
 
@@ -138,7 +138,7 @@ PROPERTY FILL RATES
 | service | 3 | 2/8 (25%) | tech_stack, repo_url, ci_status, health_check, team_owner, status |
 ```
 
-**Flag types with <30% fill rate** — the properties might be:
+**Flag types with <30% fill rate**: the properties might be:
 - Too granular for the user's stage
 - Named confusingly (user doesn't recognise the field)
 - Better suited as optional future enrichment than required at creation
@@ -157,7 +157,7 @@ UNSCHEMATISED PROPERTIES
 | persona | "company_size" | 3 | "startup", "enterprise" |
 ```
 
-These are candidates for adding to the property interfaces — the user is already using them.
+These are candidates for adding to the property interfaces; the user is already using them.
 
 ## Phase 4: Edge Usage Analysis
 
@@ -208,7 +208,7 @@ ORPHAN ANALYSIS
 |------|-------|----------|-------------|---------|
 | feature | 12 | 2 | 17% | 🟡 2 features with no parent or children |
 | hypothesis | 8 | 5 | 63% | 🔴 Most hypotheses disconnected |
-| task | 6 | 6 | 100% | 🔴 All tasks are orphans — wrong parent? |
+| task | 6 | 6 | 100% | 🔴 All tasks are orphans; wrong parent? |
 ```
 
 **High orphan rates suggest:**
@@ -252,9 +252,9 @@ Graph: [name] · [N] nodes · [M] edges · [T] types used
 - [list things that need fixing]
 
 RECOMMENDATIONS:
-1. [Most impactful action] — /upg-schema-evolve [domain]
-2. [Second action] — /upg-schema-consolidate [types]
-3. [Third action] — consider deprecating [types]
+1. [Most impactful action]; /upg-schema-evolve [domain]
+2. [Second action]; /upg-schema-consolidate [types]
+3. [Third action]; consider deprecating [types]
 
 DEAD TYPE CANDIDATES FOR DEPRECATION:
 - [types with 0 usage across all audited graphs AND >6 months old]
@@ -268,9 +268,9 @@ SURPRISE TYPES TO INVESTIGATE:
 
 ## Key Principles
 
-- **Real data over theory.** A type with 0 instances isn't wrong — it might be too new, too specialised, or genuinely unnecessary. The data tells you which.
+- **Real data over theory.** A type with 0 instances isn't wrong; it might be too new, too specialised, or genuinely unnecessary. The data tells you which.
 - **Surprise types are the most valuable signal.** When users create types the schema doesn't have, that's direct feedback on what's missing.
-- **Property fill rates reveal UX problems.** A 25% fill rate doesn't mean the properties are wrong — it might mean the creation skill doesn't ask for them.
+- **Property fill rates reveal UX problems.** A 25% fill rate doesn't mean the properties are wrong; it might mean the creation skill doesn't ask for them.
 - **Orphan rate reveals hierarchy problems.** 100% orphan rate on a type means the parent-child model is wrong for how users think about that concept.
 - **Run this before and after schema changes.** The "before" establishes a baseline; the "after" tells you if the change helped.
 - **Cross-graph analysis is more valuable than single-graph.** One graph's habits aren't representative. Compare multiple graphs to separate user preference from schema design issues.

package/skills/upg-schema-update/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: upg-schema-update
-description: "Add or update UPG entity types, edge types, or properties — cascades through the full codebase"
+description: "Add or update UPG entity types, edge types, or properties: cascades through the full codebase"
 user-invocable: false
 audience: advanced
 argument-hint: "[entity type name or description of change]"
 category: schema
 ---
 
-> ⚠️ **Advanced skill** — intended for UPG contributors and power users who understand the spec internals. Not for general use. Running mutation skills (schema-update, schema-consolidate, schema-evolve) without understanding the cascade can corrupt your graph.
+> ⚠️ **Advanced skill**: intended for UPG contributors and power users who understand the spec internals. Not for general use. Running mutation skills (schema-update, schema-consolidate, schema-evolve) without understanding the cascade can corrupt your graph.
 
-# /upg-schema-update — UPG Schema Update Cascade
+# /upg-schema-update: UPG Schema Update Cascade
 
-You are a schema update operator. When new entity types, edge types, or properties need to be added to the UPG specification, you cascade the change through every registration point in the codebase — from spec to MCP server to Graph UI to cloud server.
+You are a schema update operator. When new entity types, edge types, or properties need to be added to the UPG specification, you cascade the change through every registration point in the codebase; from spec to MCP server to Graph UI to cloud server.
 
 **This is an internal development skill, not a user-facing UPG skill.**
 
@@ -38,9 +38,9 @@ The source of truth. All changes start here.
 | `registry/domains.ts` | Add to domain's `types` array | Find the domain by `id` in `UPG_DOMAINS`, add to its `types` array |
 | `properties/domains/<domain>.ts` | Add property interface | Create `export interface XxxProperties { ... }` with typed fields. Use existing interfaces as templates. |
 | `catalog/edge-catalog.ts` | Add edge types to `UPG_EDGE_CATALOG` | Format: `edge_name: { source_type, target_type, description, cardinality }`. The `UPG_EDGE_PAIR_MAP` is derived automatically. |
-| `shapes/edges.ts` / `shapes/base-node.ts` | If modifying UPGEdge / UPGBaseNode | Rarely needed — most additions go in catalog and property interfaces |
+| `shapes/edges.ts` / `shapes/base-node.ts` | If modifying UPGEdge / UPGBaseNode | Rarely needed; most additions go in catalog and property interfaces |
 
-**Verify:** `cd packages/upg-spec && npm run build` — must compile clean.
+**Verify:** `cd packages/upg-spec && npm run build`; must compile clean.
 
 ### Layer 2: `upg-mcp-server` (packages/upg-mcp-server/)
 
@@ -48,17 +48,17 @@ The MCP server that reads/writes `.upg` files.
 
 | What to check | When it matters |
 |---------------|----------------|
-| `src/server.ts` — tool handlers | If new types need special handling in `get_product_context`, `get_graph_digest`, or lens-aware sections |
-| `src/lib/tools.ts` — digest computation | If new types should appear in health metrics |
-| `skills/` — skill markdown files | If any skill references entity types that changed |
+| `src/server.ts`; tool handlers | If new types need special handling in `get_product_context`, `get_graph_digest`, or lens-aware sections |
+| `src/lib/tools.ts`; digest computation | If new types should appear in health metrics |
+| `skills/`; skill markdown files | If any skill references entity types that changed |
 | `src/lib/edge-inference.ts` | If new edge types need inference rules |
 | `src/classification.ts` | If tier classification changes |
 
-**Verify:** `cd packages/upg-mcp-server && npm run build` — JS must build (DTS error in preflight.ts is pre-existing, ignore it).
+**Verify:** `cd packages/upg-mcp-server && npm run build`; JS must build (DTS error in preflight.ts is pre-existing, ignore it).
 
 ### Layer 3: `apps/graph` (apps/graph/src/)
 
-The Graph UI. This is the most tedious layer — one monolithic file with ~10 registries that ALL need every type.
+The Graph UI. This is the most tedious layer; one monolithic file with ~10 registries that ALL need every type.
 
 **Main file:** `apps/graph/src/lib/entity-metadata.ts` (~6300 lines)
 
@@ -91,7 +91,7 @@ The Graph UI. This is the most tedious layer — one monolithic file with ~10 re
 2. For each registry, search for that template type and add the new type nearby
 3. Follow alphabetical or domain ordering within each registry
 
-**Verify:** `cd apps/graph && npx tsc --noEmit` — the `Record<NodeType, ...>` pattern will catch any missing entries at compile time.
+**Verify:** `cd apps/graph && npx tsc --noEmit`; the `Record<NodeType, ...>` pattern will catch any missing entries at compile time.
 
 ### Layer 4: `upg-cloud-server` (packages/upg-cloud-server/)
 
@@ -99,11 +99,11 @@ The cloud API server with PostgreSQL storage.
 
 | What to check | When it matters |
 |---------------|----------------|
-| `src/store/pg-store.ts` — `rowToEdge()` | If new fields were added to UPGEdge (e.g., `confidence`, `note`) — need column or JSONB field |
-| `src/store/pg-store.ts` — `rowToNode()` | If new fields were added to UPGBaseNode |
+| `src/store/pg-store.ts`; `rowToEdge()` | If new fields were added to UPGEdge (e.g., `confidence`, `note`); need column or JSONB field |
+| `src/store/pg-store.ts`; `rowToNode()` | If new fields were added to UPGBaseNode |
 | Database migrations | If new columns needed for new edge/node properties |
 
-**Usually no changes needed** for additive entity types — the cloud server stores types as strings and properties as JSONB. But check edge/node serialisation if interface shapes changed.
+**Usually no changes needed** for additive entity types; the cloud server stores types as strings and properties as JSONB. But check edge/node serialisation if interface shapes changed.
 
 ### Layer 5: `apps/upg-site` (apps/upg-site/)
 
@@ -115,19 +115,19 @@ The documentation site.
 | Sanity CMS content | If framework docs reference entity types |
 | Domain/layer overview pages | If domain composition changed |
 
-**Usually deferred** — docs update is a separate task.
+**Usually deferred**: docs update is a separate task.
 
 ## Workflow
 
 ### Step 1: Gather Requirements
 
 Ask for or determine:
-- **Entity type name(s)** — snake_case, singular (e.g., `root_cause`)
-- **Domain** — which domain does it belong to? (e.g., `engineering`)
-- **Properties** — what typed fields does it have?
-- **Parent type** — what's its canonical parent in the hierarchy?
-- **Edge types** — what relationships does it have with other types?
-- **Display metadata** — label, plural, icon, description, layer name
+- **Entity type name(s)**: snake_case, singular (e.g., `root_cause`)
+- **Domain**: which domain does it belong to? (e.g., `engineering`)
+- **Properties**: what typed fields does it have?
+- **Parent type**: what's its canonical parent in the hierarchy?
+- **Edge types**: what relationships does it have with other types?
+- **Display metadata**: label, plural, icon, description, layer name
 
 ### Step 2: Execute the Cascade
 
@@ -154,7 +154,7 @@ cd apps/graph && npx tsc --noEmit
 cd packages/upg-cloud-server && npm run build
 ```
 
-**The `Record<NodeType, ...>` pattern in Layer 3 is your best friend** — TypeScript will error on every registry that's missing the new type. Let the compiler find what you missed.
+**The `Record<NodeType, ...>` pattern in Layer 3 is your best friend**: TypeScript will error on every registry that's missing the new type. Let the compiler find what you missed.
 
 ### Step 4: Commit
 
@@ -176,7 +176,7 @@ Cascade: spec → mcp-server → graph → cloud-server
 
 - Edges live in `UPG_EDGE_CATALOG` in `catalog/edge-catalog.ts`
 - Format: `edge_name: { source_type, target_type, description, cardinality }`
-- `UPG_EDGE_PAIR_MAP` (`source_type:target_type` → edge key) is derived automatically — don't edit it
+- `UPG_EDGE_PAIR_MAP` (`source_type:target_type` → edge key) is derived automatically; don't edit it
 - Check for duplicates before adding: search for the pair in the catalog
 - Edge names should be verb-based: `causes`, `blocks`, `enables`, `implements`, `specifies`
 

package/skills/upg-snapshot/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: upg-snapshot
-description: "Save a named checkpoint of your product graph — version your thinking"
+description: "Save a named checkpoint of your product graph: version your thinking"
 user-invocable: true
 argument-hint: "[message]"
 category: tooling
 ---
 
-# /upg-snapshot — Version Your Thinking
+# /upg-snapshot: Version Your Thinking
 
-You are a Unified Product Graph versioning tool. Your job is to save a named checkpoint of the product graph — a git commit plus version metadata in the .upg file. Fast, no questions beyond the message.
+You are a Unified Product Graph versioning tool. Your job is to save a named checkpoint of the product graph; a git commit plus version metadata in the .upg file. Fast, no questions beyond the message.
 
 **Before producing any output, read the design system:** /upg-context for emoji mappings, formatting rules, and shared interaction patterns.
 
@@ -77,7 +77,7 @@ If git fails (not a repo, nothing to commit), report the error briefly and still
 Show confirmation using this exact format:
 
 ```
-<checkmark> Snapshot saved — version <N>: "<message>"
+<checkmark> Snapshot saved; version <N>: "<message>"
   <node_count> entities · <edge_count> edges
 
 Rollback:     git checkout HEAD~1 -- <filename>.upg
@@ -88,7 +88,7 @@ Use the checkmark symbol, entity/edge counts from Step 1, and the actual .upg fi
 ## Example Output
 
 ```
-✓ Snapshot saved — version 5: "Added pricing strategy"
+✓ Snapshot saved; version 5: "Added pricing strategy"
   47 entities · 38 edges
 
 Rollback:     git checkout HEAD~1 -- product.upg
@@ -98,11 +98,11 @@ Rollback:     git checkout HEAD~1 -- product.upg
 
 - **Fast.** No preamble, no dashboard, no health check. ~10 seconds.
 - **One question max.** Only ask for the message if not provided.
-- **Git-native.** The .upg file is diffable — git is the version history.
+- **Git-native.** The .upg file is diffable; git is the version history.
 - **Silent on success.** Don't explain what versioning is. Just confirm.
 - **Graceful on failure.** If git isn't available, still patch the version and say so.
-- **No graph entity mutations.** This skill versions the file — it does not create or modify graph entities.
+- **No graph entity mutations.** This skill versions the file; it does not create or modify graph entities.
 
 ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your `.upg` file is yours — open standard, portable, git-friendly.
+Your `.upg` file is yours: open standard, portable, git-friendly.
 unifiedproductgraph.org