@unified-product-graph/core 0.7.1 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unified-product-graph/core",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Unified Product Graph — open specification and TypeScript types for product knowledge",
   "type": "module",
   "license": "MIT",

package/spec/UPG-MARKDOWN-v0.1.md

@@ -1,10 +1,10 @@
-# UPG Markdown — Format Specification (v0.1)
+# UPG Markdown: Format Specification (v0.1)
 
 > The literate variant of the `.upg` JSON format.
 > Human-authored Markdown with typed entity references that resolve against a product graph.
 
 **Format version:** 0.1
-**Status:** Pragmatic spec (not formal grammar — written the way good web specs are written).
+**Status:** Pragmatic spec (not formal grammar; written the way good web specs are written).
 **Reference implementation:** `@unified-product-graph/markdown` on npm.
 **Third-party parser conformance:** §3 below is the normative checklist for conformant parsers.
 **License:** MIT.
@@ -16,16 +16,16 @@
 A `.upg.md` file is a single CommonMark Markdown document with two additions:
 
 1. **YAML frontmatter** declaring the document's identity and graph-membership.
-2. **Inline typed references** in the body — `[[type:id]]` chips for entities, `{{type:id → type:id|verb}}` connectors for edges — and an optional fenced JSON escape hatch (` ```upg `) for declarations a renderer needs to resolve up-front.
+2. **Inline typed references** in the body (`[[type:id]]` chips for entities, `{{type:id → type:id|verb}}` connectors for edges) and an optional fenced JSON escape hatch (` ```upg `) for declarations a renderer needs to resolve up-front.
 
 It is **the same product graph as `.upg`**, expressed prose-first. A `.upg.md` document is itself an entity of type `document`; the references it contains are the graph the document narrates.
 
 The format is designed for:
 
-- **Human authoring** — write Markdown the way you already do; entities and edges sit inline.
-- **Round-trip with `.upg` JSON** — a `.upg.md` and an equivalent `.upg` file describe the same graph.
-- **Portability** — any Markdown-aware tool can render the document; UPG-aware tools resolve the chips.
-- **Diffability** — line-oriented source, friendly to git, code review, and pair authoring.
+- **Human authoring**: write Markdown the way you already do; entities and edges sit inline.
+- **Round-trip with `.upg` JSON**: a `.upg.md` and an equivalent `.upg` file describe the same graph.
+- **Portability**: any Markdown-aware tool can render the document; UPG-aware tools resolve the chips.
+- **Diffability**: line-oriented source, friendly to git, code review, and pair authoring.
 
 Non-goals: HTML rendering semantics, live link resolution, embedding/search, MDX-style component syntax, multi-document workspace indexing. All are out of scope here. They MAY ship in tooling layers; they are not part of the format.
 
@@ -35,8 +35,8 @@ Non-goals: HTML rendering semantics, live link resolution, embedding/search, MDX
 
 A `.upg.md` document has exactly two parts in this order:
 
-1. **Frontmatter** — a YAML block delimited by `---` on its own lines (§3).
-2. **Body** — CommonMark Markdown with inline references (§4–§6) and optional fenced `upg` blocks (§7).
+1. **Frontmatter**: a YAML block delimited by `---` on its own lines (§3).
+2. **Body**: CommonMark Markdown with inline references (§4–§6) and optional fenced `upg` blocks (§7).
 
 ```
 ---
@@ -60,7 +60,7 @@ The persona [[persona:alex-senior-pm]] pursues
 
 ## 3. Frontmatter
 
-The frontmatter MUST be the first construct in the file. If the opening `---` is absent, the document is not a `.upg.md` — UPG-aware tools SHOULD treat it as plain Markdown and emit a `MISSING_FRONTMATTER` error if UPG semantics are required.
+The frontmatter MUST be the first construct in the file. If the opening `---` is absent, the document is not a `.upg.md`. UPG-aware tools SHOULD treat it as plain Markdown and emit a `MISSING_FRONTMATTER` error if UPG semantics are required.
 
 ### 3.1 Required fields
 
@@ -72,7 +72,7 @@ The frontmatter MUST be the first construct in the file. If the opening `---` is
 | `entity_type` | string literal `document` | The document is an entity. v0.1 fixes this to `document`. |
 | `entity_id` | string | Stable ID of the document entity itself. MUST match `^[a-z][a-z0-9_-]*$`. |
 
-A document missing any required field is **invalid** — a conforming parser emits `MISSING_REQUIRED_FIELD` and halts structural extraction. Chips and edges MAY still be reported as warnings for diagnostics.
+A document missing any required field is **invalid**: a conforming parser emits `MISSING_REQUIRED_FIELD` and halts structural extraction. Chips and edges MAY still be reported as warnings for diagnostics.
 
 ### 3.2 Optional fields
 
@@ -101,11 +101,11 @@ This is the forward-compatibility commitment: tools that ship today MUST round-t
 
 ## 4. Body conventions
 
-The body is **prose-first**: standard CommonMark plus GitHub-Flavored Markdown (tables, fenced code blocks, strikethrough, task lists). The two Markdown extensions UPG MD adds — typed chips and edge connectors — are **inline syntax inside ordinary prose**, not block-level constructs.
+The body is **prose-first**: standard CommonMark plus GitHub-Flavored Markdown (tables, fenced code blocks, strikethrough, task lists). The two Markdown extensions UPG MD adds (typed chips and edge connectors) are **inline syntax inside ordinary prose**, not block-level constructs.
 
 > **Rationale for prose-first.** See `08-decisions/2026-04-25-upg-md-prose-first.md`. Earlier drafts treated entity declarations as block constructs (Markdown headings + property tables). Authoring practice converged on inline references. The fenced `upg` block (§7) remains the structural escape hatch when prose alone cannot express what's needed.
 
-A document MAY contain zero references. A `.upg.md` with no chips is a valid document — it just narrates without graph-augmentation.
+A document MAY contain zero references. A `.upg.md` with no chips is a valid document, narrating without graph-augmentation.
 
 ### 4.1 What Markdown extensions are in scope
 
@@ -134,11 +134,11 @@ Form: `[[type:id]]`, with optional creation marker, product scope, and pipe-deli
 
 Capture groups:
 
-1. **Creation flag** — `+` if present (§5.3), empty otherwise.
-2. **Type** — `^[a-z][a-z_]*$`. Must match an entry in `UPG_ENTITY_META` to be **resolved**; unknown types remain valid syntax (§8.5).
-3. **ID** — `^[a-z][a-z0-9_-]*$`. May be the entity's canonical UUID, slug, or any value in its `aliases[]` (§5.5).
-4. **Product slug** — optional `@product` suffix (§5.4). Absent means inherit `upg_product` from frontmatter.
-5. **Modifiers** — pipe-delimited segments parsed left-to-right (§5.6).
+1. **Creation flag**: `+` if present (§5.3), empty otherwise.
+2. **Type**: `^[a-z][a-z_]*$`. Must match an entry in `UPG_ENTITY_META` to be **resolved**; unknown types remain valid syntax (§8.5).
+3. **ID**: `^[a-z][a-z0-9_-]*$`. May be the entity's canonical UUID, slug, or any value in its `aliases[]` (§5.5).
+4. **Product slug**: optional `@product` suffix (§5.4). Absent means inherit `upg_product` from frontmatter.
+5. **Modifiers**: pipe-delimited segments parsed left-to-right (§5.6).
 
 ### 5.2 The basic forms
 
@@ -149,7 +149,7 @@ Capture groups:
 | `[[type:id@product]]` | Cross-product reference (§5.4). |
 | `[[type:id\|"label"]]` | Display label override (§5.6.1). |
 | `[[type:id\|key:value]]` | Inline property assignment (§5.6.2). |
-| `[[type:id\|key:value\|"label"]]` | Combined — modifiers and display text in any order. |
+| `[[type:id\|key:value\|"label"]]` | Combined: modifiers and display text in any order. |
 
 ### 5.3 Creation references
 
@@ -190,7 +190,7 @@ Inline properties are **assignments scoped to this reference**. Their interpreta
 - **Loaders** treat the first such assignment for a given `(entity, property)` pair as authoritative; subsequent occurrences are SHOULD-warn (`DUPLICATE_INLINE_PROPERTY`).
 - **Round-trippers** preserve every modifier byte-for-byte.
 
-Conforming parsers MUST surface modifiers as an **ordered list** of `{kind: 'label', value}` or `{kind: 'property', key, value}` entries — order is normative for round-trip (§8).
+Conforming parsers MUST surface modifiers as an **ordered list** of `{kind: 'label', value}` or `{kind: 'property', key, value}` entries; order is normative for round-trip (§8).
 
 ### 5.7 What chips do NOT do
 
@@ -210,7 +210,7 @@ Form: `{{src_type:src_id → tgt_type:tgt_id|verb}}`.
 
 ### 6.2 Endpoints
 
-Both endpoints follow chip rules: type matches `^[a-z][a-z_]*$`, id matches `^[a-z][a-z0-9_-]*$`, optional `@product` suffix per §5.4. Endpoints inside an edge reference are **references**, not declarations — to declare an entity inside an edge, use a creation chip elsewhere in the document.
+Both endpoints follow chip rules: type matches `^[a-z][a-z_]*$`, id matches `^[a-z][a-z0-9_-]*$`, optional `@product` suffix per §5.4. Endpoints inside an edge reference are **references**, not declarations. To declare an entity inside an edge, use a creation chip elsewhere in the document.
 
 ### 6.3 The arrow
 
@@ -218,9 +218,9 @@ The arrow MUST be either `→` (U+2192) or the ASCII fallback `->`. Conforming p
 
 ### 6.4 Verbs
 
-The verb segment matches `[\w_]+` (lowercase identifiers with underscores). To be **resolved**, the verb MUST be a key in `UPG_EDGE_CATALOG`. Unknown verbs are warnings (§8.5), not errors — the format is forward-compatible with edge types added in later spec versions.
+The verb segment matches `[\w_]+` (lowercase identifiers with underscores). To be **resolved**, the verb MUST be a key in `UPG_EDGE_CATALOG`. Unknown verbs are warnings (§8.5), not errors; the format is forward-compatible with edge types added in later spec versions.
 
-A verb is **canonical** when paired with the correct `(src_type, tgt_type)` — the spec catalogue keys edges by full triple. A verb that exists in the catalogue but is paired with the wrong endpoint types is `UNKNOWN_VERB_FOR_PAIR` (warning).
+A verb is **canonical** when paired with the correct `(src_type, tgt_type)`: the spec catalogue keys edges by full triple. A verb that exists in the catalogue but is paired with the wrong endpoint types is `UNKNOWN_VERB_FOR_PAIR` (warning).
 
 ### 6.5 Inline edges and fenced edges are equivalent
 
@@ -230,7 +230,7 @@ An inline `{{a → b|verb}}` and a fenced declaration `{ "src": "a", "tgt": "b",
 
 ## 7. Fenced `upg` blocks (the JSON escape hatch)
 
-Inline chips (§5) and inline edges (§6) are the primary authoring surface. **Fenced `upg` blocks remain part of v0.1 and MUST be supported by every conforming parser** — exporters, structural import, and round-trip with `.upg` JSON depend on them.
+Inline chips (§5) and inline edges (§6) are the primary authoring surface. **Fenced `upg` blocks remain part of v0.1 and MUST be supported by every conforming parser**; exporters, structural import, and round-trip with `.upg` JSON depend on them.
 
 ### 7.1 Block shape
 
@@ -259,14 +259,14 @@ Each entry in `edges[]` is equivalent to an inline `{{src → tgt|verb}}`. Requi
 
 ### 7.4 Malformed JSON
 
-A malformed block is a **warning** (`INVALID_FENCED_JSON`) that affects only that block — the rest of the document MUST still parse. Conforming parsers SHOULD continue to extract inline chips and edges around the malformed block.
+A malformed block is a **warning** (`INVALID_FENCED_JSON`) that affects only that block; the rest of the document MUST still parse. Conforming parsers SHOULD continue to extract inline chips and edges around the malformed block.
 
 ### 7.5 When to use a fenced block
 
 Use the fenced block when:
 
 - A renderer needs property assignments that don't fit cleanly inline (e.g. a 12-field `metric_quality_assessment`).
-- The same set of declarations is reused across multiple sections — declare once, reference inline thereafter.
+- The same set of declarations is reused across multiple sections: declare once, reference inline thereafter.
 - The document is generated by tooling that emits structural data and prose separately.
 
 For most human authoring, inline chips suffice. Fenced blocks are the escape hatch, not the default.
@@ -280,14 +280,14 @@ For most human authoring, inline chips suffice. Fenced blocks are the escape hat
 1. **Parse frontmatter first.** A document with malformed frontmatter is invalid; halt structural extraction (§3).
 2. **Mask code regions.** Chips and edges inside fenced code blocks (` ``` ... ``` ` excluding `upg` blocks) and inline code spans (`` ` ... ` `` and `` `` ... `` ``) MUST NOT be extracted as references.
 3. **Honour escapes.** `\[\[`, `\]\]`, `\{\{`, `\}\}` render literal brackets and MUST NOT be extracted (§8.3).
-4. **Surface byte ranges.** For every chip and edge, expose the source byte range. Byte ranges are normative — they enable round-trip edits (§9).
+4. **Surface byte ranges.** For every chip and edge, expose the source byte range. Byte ranges are normative; they enable round-trip edits (§9).
 5. **Preserve unknown frontmatter keys.** Verbatim, including order (§3.3).
 6. **Preserve modifier order.** Modifier segments inside a chip MUST round-trip in source order (§5.6).
 
 ### 8.2 Recommended behaviour (SHOULD)
 
 1. **Normalise the arrow** to `→` on emit, preserving the source style on round-trip (§6.3).
-2. **Warn, don't drop.** Unknown types, unknown verbs, unknown frontmatter keys, malformed individual chips — warn and continue (§8.5).
+2. **Warn, don't drop.** Unknown types, unknown verbs, unknown frontmatter keys, malformed individual chips: warn and continue (§8.5).
 3. **Layered ID resolution** per §5.5 if the parser also resolves.
 4. **Multiline limit.** A single reference SHOULD NOT span more than 3 lines; longer spans warn (`MULTILINE_EXCEEDS_LIMIT`) and are not extracted.
 
@@ -334,7 +334,7 @@ A conforming parser **never silently drops structural content**.
 
 ### 8.6 Forward compatibility
 
-An older conforming parser reading a newer document MUST round-trip without data loss for any construct it does not understand. This is non-negotiable. A future spec version MAY add new sigils, new modifier kinds, new fenced block types — older parsers preserve them as opaque text and warn.
+An older conforming parser reading a newer document MUST round-trip without data loss for any construct it does not understand. This is non-negotiable. A future spec version MAY add new sigils, new modifier kinds, new fenced block types; older parsers preserve them as opaque text and warn.
 
 ---
 
@@ -345,8 +345,8 @@ An older conforming parser reading a newer document MUST round-trip without data
 ### 9.1 `.upg.md → .upg` (lossy)
 
 Drops:
-- Prose surrounding the chips (the document is preserved as a `document` entity with its body in `properties.body_md`, but Markdown structure — headings, paragraph layout, formatting — is intentionally not modelled in the graph).
-- Modifier display labels (`"Alex (CEO)"`) — these are presentation, not graph data.
+- Prose surrounding the chips (the document is preserved as a `document` entity with its body in `properties.body_md`, but Markdown structure, including headings, paragraph layout, and formatting, is intentionally not modelled in the graph).
+- Modifier display labels (`"Alex (CEO)"`): presentation, not graph data.
 - Comments and incidental whitespace (§8.4).
 
 Preserves:
@@ -360,7 +360,7 @@ Preserves:
 
 Drops:
 - Edge metadata that has no inline syntax (e.g. edge weights, custom edge properties beyond verb).
-- Per-entity properties that aren't surfaceable as inline modifiers (large bodies of structured data — these stay in the graph; the document references them).
+- Per-entity properties that aren't surfaceable as inline modifiers (large bodies of structured data stay in the graph; the document references them).
 
 Preserves:
 - Every entity → creation chip or fenced declaration.
@@ -381,20 +381,20 @@ Each example below is a complete `.upg.md` document. Each is validated by the ro
 
 See `packages/upg-spec/spec/examples/`:
 
-- `enterprise-pilot-results.upg.md` — full experiment-report shape (existing reference document).
-- `persona-minimal.upg.md` — minimal viable doc; frontmatter + a single chip (§10.1).
-- `feature-decision.upg.md` — feature decision doc with chips + edges + a fenced `upg` block (§10.2).
-- `metric-tracking.upg.md` — metric doc using property modifiers and cross-product references (§10.3).
+- `enterprise-pilot-results.upg.md`: full experiment-report shape (existing reference document).
+- `persona-minimal.upg.md`: minimal viable doc; frontmatter + a single chip (§10.1).
+- `feature-decision.upg.md`: feature decision doc with chips + edges + a fenced `upg` block (§10.2).
+- `metric-tracking.upg.md`: metric doc using property modifiers and cross-product references (§10.3).
 
-### 10.1 `persona-minimal.upg.md` — minimum viable document
+### 10.1 `persona-minimal.upg.md`: minimum viable document
 
 The smallest valid `.upg.md`. Demonstrates required frontmatter and a single inline chip.
 
-### 10.2 `feature-decision.upg.md` — chips + edges + fenced block
+### 10.2 `feature-decision.upg.md`: chips + edges + fenced block
 
 Demonstrates the full prose-first authoring shape: typed chips for the persona/feature/decision; an edge expressing the rationale relationship; a fenced `upg` block for the structural decision-record properties (the prose alone wouldn't fit them cleanly).
 
-### 10.3 `metric-tracking.upg.md` — modifiers + cross-product
+### 10.3 `metric-tracking.upg.md`: modifiers + cross-product
 
 Demonstrates inline property modifiers on metrics (`current:22%|target:30%`), the creation-marker form for newly-discovered entities, and a cross-product reference to a sibling product graph.
 
@@ -402,14 +402,14 @@ Demonstrates inline property modifiers on metrics (`current:22%|target:30%`), th
 
 ## 11. Versioning
 
-The format spec is versioned independently from `@unified-product-graph/core`'s spec version (entity catalogue, edge catalogue, lifecycles) — those evolve more frequently and the format remains stable across them.
+The format spec is versioned independently from `@unified-product-graph/core`'s spec version (entity catalogue, edge catalogue, lifecycles), which evolve more frequently while the format remains stable across them.
 
 - **Format version (this document):** `0.1`. Exposed at runtime as `MARKDOWN_FORMAT_VERSION` from `@unified-product-graph/core`.
 - **Spec version (`upg_version` frontmatter):** the entity/edge catalogue version the document targets (e.g. `0.2`). Independent of format version.
 
 A document declaring `upg_version: "0.2"` and consumed by a tool that bundles `@unified-product-graph/core@0.2.x` is in-spec. Forward compatibility (§8.6) handles version drift.
 
-A future format `v0.2` would ship as `UPG-MARKDOWN-v0.2.md` alongside this document. The format is intentionally conservative about breaking changes — most evolution happens in catalogue versions, not format versions.
+A future format `v0.2` would ship as `UPG-MARKDOWN-v0.2.md` alongside this document. The format is intentionally conservative about breaking changes; most evolution happens in catalogue versions, not format versions.
 
 ---
 
@@ -419,10 +419,10 @@ Explicitly **not** part of this spec:
 
 - HTML rendering semantics, hover cards, syntax highlighting (consumer concerns).
 - Live link resolution against a graph store (resolver tooling).
-- Embedding semantics — search, similarity, vector indexing.
+- Embedding semantics (search, similarity, vector indexing).
 - Workspace-level multi-document indexing and cross-document linking semantics.
-- Speculative future syntax — templated chips, computed properties, inline queries, conditional rendering.
-- MDX / JSX components — out of scope per §4.1; prose-first means CommonMark prose.
+- Speculative future syntax (templated chips, computed properties, inline queries, conditional rendering).
+- MDX / JSX components: out of scope per §4.1; prose-first means CommonMark prose.
 - Block-level entity declaration syntax (e.g. heading-keyed entity blocks). The format converged prose-first; block-level structure is the fenced `upg` block (§7).
 
 Each of the above MAY be specified in a later format version or in tooling layers above the format. None affect parser conformance for v0.1.
@@ -431,7 +431,7 @@ Each of the above MAY be specified in a later format version or in tooling layer
 
 ## 13. Cross-references
 
-- **Reference implementation:** `@unified-product-graph/markdown` on npm — `parse()`, `validate()`, `buildIndex()`, `toPlainMarkdown()`, `updateRefs()`, TipTap converters.
+- **Reference implementation:** `@unified-product-graph/markdown` on npm, providing `parse()`, `validate()`, `buildIndex()`, `toPlainMarkdown()`, `updateRefs()`, and TipTap converters.
 - **Prose-first rationale:** UPG MD is authored for humans first; entity references are CommonMark-compatible inline chips so files render cleanly in any Markdown viewer.
 - **`.upg` JSON format:** UPG MD is the literate variant of the `.upg` JSON format. See the UPG core spec for the JSON schema.
 - **Site `/format` page:** [unifiedproductgraph.org/format](https://unifiedproductgraph.org/format) links to this document at a stable URL.

package/spec/examples/cms-field-guide.upg

@@ -8,7 +8,7 @@
   },
   "product": {
     "id": "cms-field-guide",
-    "title": "CMS Editor Paradigms — A Studio PM Field Guide",
+    "title": "CMS Editor Paradigms: A Studio PM Field Guide",
     "description": "Proof-of-spec fixture for the classification model. Models the CMS Field Editor Guide end-to-end using only canonical UPG entities: a single competitive_analysis dimensioned by two classification_axis children, with five classification_value children per axis, two exemplar competitor nodes classified against axis values, three empty_cells covering all rationale_kind values, and a persona with an anti_fit_for edge.",
     "stage": "mvp"
   },
@@ -26,13 +26,13 @@
             "axis_a_value_ref": "val-composable",
             "axis_b_value_ref": "val-wysiwyg",
             "rationale_kind": "structural",
-            "rationale_md": "Composable rejects HTML blobs; WYSIWYG requires them. The two paradigms are structurally incompatible — you can't simultaneously commit to a typed content graph and to a free-form HTML editor."
+            "rationale_md": "Composable rejects HTML blobs; WYSIWYG requires them. The two paradigms are structurally incompatible: you can't simultaneously commit to a typed content graph and to a free-form HTML editor."
           },
           {
             "axis_a_value_ref": "val-git-based",
             "axis_b_value_ref": "val-portable-text",
             "rationale_kind": "opportunity",
-            "rationale_md": "No technical reason — only adoption inertia. Watching brief: anyone shipping a starter that drops .md into Portable Text JSON could change the row."
+            "rationale_md": "No technical reason, only adoption inertia. Watching brief: anyone shipping a starter that drops .md into Portable Text JSON could change the row."
           },
           {
             "axis_a_value_ref": "val-monolithic",
@@ -105,7 +105,7 @@
       "description": "Decouples content storage from presentation; serves content via an API.",
       "parent_id": "axis-architecture",
       "properties": {
-        "rationale": "Headless without the composable extensions — APIs over content but no typed graph guarantee, often without real-time, often with hosted-only editor.",
+        "rationale": "Headless without the composable extensions: APIs over content but no typed graph guarantee, often without real-time, often with hosted-only editor.",
         "exemplars": ["Contentstack", "Storyblok", "Strapi"],
         "commitments": [
           { "name": "API-only delivery", "description": "No coupled rendering layer; consumers pull content via REST/GraphQL." },
@@ -124,7 +124,7 @@
       "description": "API delivery plus optional coupled rendering; vendor-managed personalization layer.",
       "parent_id": "axis-architecture",
       "properties": {
-        "rationale": "Splits the difference between headless and monolithic — typically enterprise DXP vendors layering API delivery on top of their incumbent page-bound stack.",
+        "rationale": "Splits the difference between headless and monolithic, typically enterprise DXP vendors layering API delivery on top of their incumbent page-bound stack.",
         "exemplars": ["Optimizely", "Sitecore XM Cloud"]
       }
     },
@@ -191,7 +191,7 @@
       "description": "Long-form content as a typed array of typed blocks; rich text without HTML.",
       "parent_id": "axis-editing",
       "properties": {
-        "rationale": "Sanity's signature shape — long-form authoring without surrendering type guarantees. Each paragraph/heading/quote is a typed block; embedded references are first-class.",
+        "rationale": "Sanity's signature shape: long-form authoring without surrendering type guarantees. Each paragraph/heading/quote is a typed block; embedded references are first-class.",
         "exemplars": ["Sanity Studio"],
         "commitments": [
           { "name": "Typed blocks", "description": "Every paragraph, heading, list, quote is a typed JSON block with stable schema." },
@@ -227,7 +227,7 @@
         "strengths": [
           "Typed content graph with GROQ query language",
           "Real-time CRDT collaboration out of the box",
-          "Embeddable studio — owned inside the team's repo"
+          "Embeddable studio, owned inside the team's repo"
         ],
         "weaknesses": [
           "Steeper learning curve than form-based headless CMSs",

package/spec/examples/enterprise-pilot-results.upg.md

@@ -1,5 +1,5 @@
 ---
-title: "Enterprise Pilot Results — Q2 2026"
+title: "Enterprise Pilot Results: Q2 2026"
 upg_product: entopo
 upg_version: "0.4.0"
 entity_type: document
@@ -12,7 +12,7 @@ composition_pattern: experiment_report
 graph_source: enterprise-pilot.upg
 ---
 
-# Enterprise Pilot Results — Q2 2026
+# Enterprise Pilot Results: Q2 2026
 
 ## Background
 
@@ -20,12 +20,12 @@ Our primary persona [[persona:alex-senior-pm]] faces a critical need:
 [[need:no-single-source-of-truth|valence:pain|severity:Significant]].
 
 This was identified through research that surfaced a key insight:
-{{insight:tool-fragmentation → opportunity:unified-knowledge|informs}} —
+{{insight:tool-fragmentation → opportunity:unified-knowledge|informs}},
 our strongest evidence chain from user research to strategic opportunity.
 
 [[persona:alex-senior-pm|"Alex"]] leads a 12-person team and
 {{persona:alex-senior-pm -> job:keep-team-aligned|pursues}} alignment as
-a core job — but today that job is underserved.
+a core job, but today that job is underserved.
 
 ## What We Tested
 
@@ -41,7 +41,7 @@ The chain from need to hypothesis:
 - The solution proposes
   [[hypothesis:structured-knowledge-reduces-planning]]
 
-We ran [[experiment:enterprise-pilot-q2]] — a controlled pilot with 5
+We ran [[experiment:enterprise-pilot-q2]], a controlled pilot with 5
 enterprise teams over 8 weeks.
 
 ## Results
@@ -49,8 +49,8 @@ enterprise teams over 8 weeks.
 {{experiment:enterprise-pilot-q2 → learning:planning-time-reduction|produces}}
 
 [[learning:planning-time-reduction|"The key learning"]]: teams reduced
-planning time by 22% — below the 30% target but statistically
-significant. 3 of 5 teams exceeded the 20% threshold.
+planning time by 22% (below the 30% target but statistically
+significant). 3 of 5 teams exceeded the 20% threshold.
 
 [[metric:planning-time|current:22%|target:30%]] is trending positive.
 
@@ -77,14 +77,14 @@ The discovery came from the experiment itself:
    strong and statistically significant.
 
 2. **Adjust the target.** [[metric:planning-time]] target should move
-   from 30% to 25% — more realistic based on pilot data.
+   from 30% to 25%, a more realistic target based on pilot data.
 
 3. **Investigate the new need.**
    [[need:context-loss-between-sprints]] is a potential second
    opportunity worth sizing.
 
 4. **North star remains.**
-   [[objective:reduce-context-switching]] is the right objective —
+   [[objective:reduce-context-switching]] is the right objective;
    the pilot confirms the direction.
 
 ## Full Evidence Chain

package/spec/examples/enterprise-pilot.upg

@@ -9,7 +9,7 @@
   "product": {
     "id": "entopo",
     "title": "Entopo",
-    "description": "The product creation tool. Structure your product knowledge as a typed graph — queryable, traversable, AI-readable.",
+    "description": "The product creation tool. Structure your product knowledge as a typed graph: queryable, traversable, AI-readable.",
     "stage": "mvp"
   },
   "nodes": [
@@ -170,7 +170,7 @@
       "id": "solution_unified-product-graph",
       "type": "solution",
       "title": "Unified Product Graph",
-      "description": "A typed knowledge graph that models all product entities — personas, needs, opportunities, solutions, hypotheses, experiments, features, metrics — as nodes with semantic edges. Queryable, traversable, AI-readable.",
+      "description": "A typed knowledge graph that models all product entities (personas, needs, opportunities, solutions, hypotheses, experiments, features, metrics) as nodes with semantic edges. Queryable, traversable, AI-readable.",
       "status": "active",
       "tags": [
         "primary-solution"
@@ -245,7 +245,7 @@
     {
       "id": "learning_planning-time-reduction",
       "type": "learning",
-      "title": "22% reduction — below target but statistically significant",
+      "title": "22% reduction, below target but statistically significant",
       "description": "Teams reduced planning time by 22% (target was 30%). 3 of 5 teams exceeded the 20% threshold. The result is statistically significant and directionally positive, strengthening confidence in the hypothesis.",
       "status": "active",
       "tags": [
@@ -349,7 +349,7 @@
       "target": "need_context-loss-between-sprints",
       "type": "experiment_surfaces_need",
       "properties": {
-        "note": "Discovered during pilot — not part of original hypothesis"
+        "note": "Discovered during pilot; not part of original hypothesis"
       }
     },
     {
@@ -366,10 +366,10 @@
     }
   ],
   "metadata": {
-    "export_name": "Enterprise Pilot — UPG Markdown Spec Reference Graph",
+    "export_name": "Enterprise Pilot: UPG Markdown Spec Reference Graph",
     "exported_by": "mr-data",
     "node_count": 12,
     "edge_count": 11,
-    "purpose": "Companion graph for UPG-MARKDOWN-v0.1.upg.md — provides resolvable entities for the spec's worked example"
+    "purpose": "Companion graph for UPG-MARKDOWN-v0.1.upg.md. Provides resolvable entities for the spec's worked example."
   }
 }

package/spec/examples/feature-decision.upg.md

@@ -1,5 +1,5 @@
 ---
-title: "Decision — Ship Smart Search before Q3 Planning"
+title: "Decision: Ship Smart Search before Q3 Planning"
 upg_product: entopo
 upg_version: "0.4.0"
 entity_type: document
@@ -24,12 +24,12 @@ We're shipping [[+feature:smart-search|"Smart Search"]] in the v0.2.10 release w
 The rationale chain:
 
 - [[need:no-single-source-of-truth]] surfaces during planning (every quarter).
-- {{feature:smart-search → metric:weekly-actives|drives}} — we expect a 12% lift in weekly actives based on pilot interviews.
-- {{decision:ship-smart-search-q2 → feature:smart-search|approves}} — this decision authorises the work.
+- {{feature:smart-search → metric:weekly-actives|drives}}: we expect a 12% lift in weekly actives based on pilot interviews.
+- {{decision:ship-smart-search-q2 → feature:smart-search|approves}}: this decision authorises the work.
 
 ## Structural properties
 
-The decision record has properties that don't fit cleanly inline — stakeholders, alternatives considered, blast radius. We use a fenced block:
+The decision record has properties that don't fit cleanly inline (stakeholders, alternatives considered, blast radius). We use a fenced block:
 
 ```upg
 {

package/spec/examples/metric-tracking.upg.md

@@ -1,5 +1,5 @@
 ---
-title: "Metric Tracking — Planning Time Reduction (Q2)"
+title: "Metric Tracking: Planning Time Reduction (Q2)"
 upg_product: entopo
 upg_version: "0.4.0"
 entity_type: document
@@ -12,7 +12,7 @@ tags: [metric, q2, validation]
 graph_source: ../enterprise-pilot.upg
 ---
 
-# Planning Time Reduction — Q2 Tracking
+# Planning Time Reduction: Q2 Tracking
 
 ## Headline
 
@@ -24,8 +24,8 @@ We're below target but trending positive. Statistical significance is confirmed
 
 The metric decomposes into two input metrics:
 
-- [[metric:meeting-count-per-sprint|current:4.2|target:3.0|designation:input]] — how many planning meetings each team holds per sprint.
-- [[metric:context-handoff-time|current:18m|target:10m|designation:input]] — time spent re-establishing context at sprint boundaries.
+- [[metric:meeting-count-per-sprint|current:4.2|target:3.0|designation:input]]: how many planning meetings each team holds per sprint.
+- [[metric:context-handoff-time|current:18m|target:10m|designation:input]]: time spent re-establishing context at sprint boundaries.
 
 Both are moving in the right direction. Meeting count is at 4.2 (down from 6.1 baseline); context handoff is at 18 minutes (down from 27 minutes).
 
@@ -39,7 +39,7 @@ During pilot week 6, the team surfaced a previously unknown input we should add
 
 [[+metric:re-planning-incidents|current:1.4|target:0.5|designation:input|"Times per sprint a team has to redo planning because of context loss"]].
 
-This is a creation reference — first occurrence in this document declares the metric. It enters the graph at next sync.
+This is a creation reference. The first occurrence in this document declares the metric; it enters the graph at next sync.
 
 ## Quality assessment
 

package/spec/examples/persona-minimal.upg.md

@@ -1,5 +1,5 @@
 ---
-title: "Alex (Senior PM) — Persona Profile"
+title: "Alex (Senior PM): Persona Profile"
 upg_product: entopo
 upg_version: "0.4.0"
 entity_type: document
@@ -19,4 +19,4 @@ status: published
 
 ## What gets in her way
 
-The biggest blocker is [[need:no-single-source-of-truth|valence:pain|severity:Significant]] — context lives in seven tools and nobody owns reconciling them.
+The biggest blocker is [[need:no-single-source-of-truth|valence:pain|severity:Significant]]: context lives in seven tools and nobody owns reconciling them.