@unified-product-graph/core 0.7.1 → 0.7.4

package/dist/index.d.ts

@@ -13,20 +13,20 @@
 type UPGEntityType = 'product' | 'outcome' | 'objective' | 'key_result' | 'metric' | 'metric_quality_assessment' | 'vision' | 'mission' | 'strategic_theme' | 'initiative' | 'capability' | 'value_stream' | 'strategic_pillar' | 'assumption' | 'decision' | 'constraint' | 'persona' | 'job' | 'need' | 'desired_outcome' | 'job_step' | 'switching_cost' | 'opportunity' | 'solution' | 'feasibility_study' | 'design_sprint' | 'hypothesis' | 'hypothesis_evidence' | 'experiment' | 'experiment_plan' | 'experiment_run' | 'learning' | 'test_plan' | 'evidence' | 'research_plan' | 'competitor' | 'competitor_feature' | 'market_trend' | 'market_segment' | 'competitive_analysis' | 'classification_axis' | 'classification_value' | 'research_study' | 'insight' | 'participant' | 'observation' | 'quote' | 'affinity_cluster' | 'research_question' | 'interview_guide' | 'survey_response' | 'user_journey' | 'journey_step' | 'journey_phase' | 'journey_action' | 'design_question' | 'design_concept' | 'prototype' | 'wireframe' | 'user_flow' | 'screen' | 'screen_state' | 'annotation' | 'interaction_spec' | 'design_component' | 'design_token' | 'design_system' | 'design_pattern' | 'design_guideline' | 'brand_identity' | 'brand_colour' | 'brand_typography' | 'brand_voice' | 'brand_logo' | 'brand_imagery' | 'feature_area' | 'feature' | 'epic' | 'user_story' | 'story_statement' | 'story_task' | 'acceptance_criterion' | 'release' | 'task' | 'bug' | 'roadmap' | 'roadmap_item' | 'theme' | 'changelog' | 'bounded_context' | 'service' | 'domain_event' | 'api_contract' | 'technical_debt_item' | 'feature_flag' | 'deployment' | 'aggregate' | 'domain_entity' | 'value_object' | 'command' | 'read_model' | 'api_endpoint' | 'database_schema' | 'queue_topic' | 'build_artifact' | 'code_repository' | 'library_dependency' | 'integration_pattern' | 'external_api' | 'data_flow' | 'investigation' | 'root_cause' | 'symptom' | 'fix' | 'funnel' | 'funnel_step' | 'acquisition_channel' | 'growth_campaign' | 'cohort' | 'behavioral_segment' | 'growth_loop' | 'variant' | 'attribution_model' | 'business_model' | 'value_proposition' | 'revenue_stream' | 'pricing_tier' | 'cost_structure' | 'unit_economics' | 'partnership' | 'key_resource' | 'key_activity' | 'customer_relationship' | 'distribution_channel' | 'gtm_strategy' | 'ideal_customer_profile' | 'positioning' | 'messaging' | 'launch' | 'content_strategy' | 'sales_motion' | 'competitive_battle_card' | 'demand_gen_program' | 'territory' | 'objection' | 'rebuttal' | 'proof_point' | 'team' | 'role' | 'stakeholder' | 'person' | 'team_okr' | 'retrospective' | 'dependency' | 'department' | 'skill' | 'ceremony' | 'capacity_plan' | 'data_source' | 'event_schema' | 'dashboard' | 'data_model' | 'data_quality_rule' | 'data_product' | 'data_pipeline' | 'data_lineage' | 'glossary_term' | 'data_domain' | 'report' | 'content_piece' | 'knowledge_base_article' | 'brand_asset' | 'prompt_template' | 'content_calendar' | 'content_theme' | 'documentation_template' | 'document' | 'legal_entity' | 'ip_asset' | 'contract' | 'contract_clause' | 'privacy_policy' | 'compliance_requirement' | 'risk' | 'data_contract' | 'audit_log_policy' | 'compliance_framework' | 'security_audit' | 'service_level_indicator' | 'service_level_objective' | 'error_budget' | 'incident' | 'postmortem' | 'runbook' | 'monitor' | 'alert_rule' | 'ci_pipeline' | 'release_strategy' | 'on_call_rotation' | 'infrastructure_component' | 'threat_model' | 'threat' | 'vulnerability' | 'security_control' | 'security_policy' | 'penetration_test' | 'security_review' | 'data_classification' | 'access_policy' | 'a11y_standard' | 'a11y_guideline' | 'a11y_audit' | 'a11y_issue' | 'a11y_annotation' | 'test_suite' | 'test_case' | 'qa_session' | 'regression_test' | 'test_coverage_report' | 'test_environment' | 'test_result' | 'feedback_program' | 'feature_request' | 'feedback_vote' | 'nps_campaign' | 'user_advisory_board' | 'beta_program' | 'feedback_theme' | 'pricing_strategy' | 'discount_strategy' | 'trial_config' | 'paywall' | 'ai_model' | 'prompt_version' | 'eval_benchmark' | 'eval_run' | 'ai_cost_tracker' | 'hallucination_report' | 'ai_guardrail' | 'model_comparison' | 'ai_experiment' | 'ai_dataset' | 'ai_trace' | 'workflow_template' | 'workflow_run' | 'agent_definition' | 'agent_session' | 'review_gate' | 'approval_record' | 'agent_skill' | 'agent_hook' | 'workflow_artifact' | 'agent_task' | 'organization' | 'portfolio' | 'product_area' | 'workspace' | 'account' | 'contact' | 'lead' | 'deal' | 'pipeline_sales' | 'pipeline_stage' | 'quote_document' | 'subscription' | 'invoice' | 'forecast' | 'program' | 'project' | 'milestone' | 'risk_register' | 'change_request' | 'deliverable' | 'resource_allocation' | 'status_report' | 'marketing_strategy' | 'marketing_channel' | 'marketing_campaign_plan' | 'email_sequence' | 'social_post' | 'seo_keyword' | 'ad_creative' | 'press_release' | 'event' | 'community_initiative' | 'support_ticket' | 'customer_feedback' | 'churn_reason' | 'customer_health_score' | 'playbook' | 'service_level_agreement' | 'customer_journey_stage' | 'touchpoint' | 'success_milestone' | 'service_blueprint' | 'locale' | 'translation_key' | 'translation_bundle' | 'locale_config' | 'cultural_adaptation' | 'regional_pricing' | 'education_program' | 'tutorial' | 'walkthrough' | 'webinar' | 'certification' | 'help_video' | 'learning_path' | 'partner_program' | 'partner_tier' | 'api_ecosystem' | 'marketplace_listing' | 'developer_portal' | 'integration_partner' | 'partner_revenue_share';
 /**
  * No entity types are currently deprecated; this union is `never`. The
- * deprecated-name bridge — which previously widened this union to early
- * aliases (`jtbd`, `pain_point`, `kpi`, …) — is closed, so runtime callers no
+ * deprecated-name bridge, which previously widened this union to early
+ * aliases (`jtbd`, `pain_point`, `kpi`, …), is closed, so runtime callers no
  * longer need an alias-aware type.
  *
  * Narrowed to `never` so any code that still references this union for
  * widening cascades a type error and gets cleaned up. Migration runtime
  * (`migrateNode`, `UPG_MIGRATIONS`, `getReplacementType`) keeps its own
- * internal list of historical names — it does NOT depend on this union.
+ * internal list of historical names; it does NOT depend on this union.
  *
- * @see ../grammar/migrations.ts — runtime migration helpers
- * @see scripts/check-no-deprecated-symbols.ts — string-literal guard
+ * @see ../grammar/migrations.ts for runtime migration helpers
+ * @see scripts/check-no-deprecated-symbols.ts for the string-literal guard
  */
 type DeprecatedUPGEntityType = never;
-/** All entity types — `DeprecatedUPGEntityType` is `never`, so this equals `UPGEntityType`. */
+/** All entity types. `DeprecatedUPGEntityType` is `never`, so this equals `UPGEntityType`. */
 type AnyUPGEntityType = UPGEntityType | DeprecatedUPGEntityType;
 
 /**
@@ -50,7 +50,7 @@ type UPGMappingConfidence = 'high' | 'medium' | 'low' | 'manual';
  * Everything else is optional to keep the format lightweight.
  *
  * @example
- * // A minimal persona node — only required fields populated.
+ * // A minimal persona node, only required fields populated.
  * const persona: UPGBaseNode = {
  *   id: 'n_persona_1',
  *   type: 'persona',
@@ -79,7 +79,7 @@ type UPGMappingConfidence = 'high' | 'medium' | 'low' | 'manual';
 interface UPGBaseNode {
     /** Unique identifier within the graph */
     id: string;
-    /** The UPG entity type — must be a value from UPGEntityType */
+    /** The UPG entity type (must be a value from UPGEntityType) */
     type: UPGEntityType;
     /** Human-readable title */
     title: string;
@@ -102,7 +102,7 @@ interface UPGBaseNode {
     description?: string;
     /** Freeform tags for filtering and grouping */
     tags?: string[];
-    /** Current lifecycle phase — must be a phase ID from getLifecycleForType().
+    /** Current lifecycle phase (must be a phase ID from getLifecycleForType()).
      *  E.g., for hypothesis: 'untested' | 'testing' | 'resolved'.
      *  Entity types without a lifecycle definition should omit this field.
      *  Validated at runtime against UPG_ALL_PHASES_SET. */
@@ -115,7 +115,7 @@ interface UPGBaseNode {
     mapping_confidence?: UPGMappingConfidence;
     /** External tool that holds the canonical artifact (e.g. "figma", "linear", "notion") */
     external_tool?: string;
-    /** URI to the canonical artifact — https:// for cloud tools, file:// or relative path for local files */
+    /** URI to the canonical artifact: https:// for cloud tools, file:// or relative path for local files */
     external_ref?: string;
     /** Identifier in the external tool's system (for sync / round-trip) */
     external_id?: string;
@@ -565,6 +565,13 @@ declare const UPG_EDGE_CATALOG: {
         source_type: string;
         target_type: string;
     };
+    competitor_competes_in_territory: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "cross-domain";
+        source_type: string;
+        target_type: string;
+    };
     competitor_yields_learning: {
         forward_verb: string;
         reverse_verb: string;
@@ -1776,6 +1783,13 @@ declare const UPG_EDGE_CATALOG: {
         source_type: string;
         target_type: string;
     };
+    deployment_triggers_incident: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "causal";
+        source_type: string;
+        target_type: string;
+    };
     service_serves_api_endpoint: {
         forward_verb: string;
         reverse_verb: string;
@@ -2238,6 +2252,13 @@ declare const UPG_EDGE_CATALOG: {
         source_type: string;
         target_type: string;
     };
+    monitor_measures_service_level_indicator: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "semantic";
+        source_type: string;
+        target_type: string;
+    };
     ci_pipeline_deploys_service: {
         forward_verb: string;
         reverse_verb: string;
@@ -2931,6 +2952,13 @@ declare const UPG_EDGE_CATALOG: {
         source_type: string;
         target_type: string;
     };
+    attribution_model_credits_acquisition_channel: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "semantic";
+        source_type: string;
+        target_type: string;
+    };
     product_guided_by_metric: {
         forward_verb: string;
         reverse_verb: string;
@@ -3050,6 +3078,13 @@ declare const UPG_EDGE_CATALOG: {
         source_type: string;
         target_type: string;
     };
+    growth_loop_fuels_acquisition_channel: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "semantic";
+        source_type: string;
+        target_type: string;
+    };
     variant_tests_hypothesis: {
         forward_verb: string;
         reverse_verb: string;
@@ -3855,6 +3890,13 @@ declare const UPG_EDGE_CATALOG: {
         source_type: string;
         target_type: string;
     };
+    forecast_projects_metric: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "cross-domain";
+        source_type: string;
+        target_type: string;
+    };
     product_markets_through_marketing_strategy: {
         forward_verb: string;
         reverse_verb: string;
@@ -4380,6 +4422,13 @@ declare const UPG_EDGE_CATALOG: {
         source_type: string;
         target_type: string;
     };
+    content_theme_organizes_content_piece: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "semantic";
+        source_type: string;
+        target_type: string;
+    };
     document_describes_feature: {
         forward_verb: string;
         reverse_verb: string;
@@ -6156,6 +6205,13 @@ declare const UPG_EDGE_CATALOG: {
         source_type: string;
         target_type: string;
     };
+    participant_represents_persona: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "cross-domain";
+        source_type: string;
+        target_type: string;
+    };
     research_question_addressed_by_insight: {
         forward_verb: string;
         reverse_verb: string;
@@ -6740,23 +6796,23 @@ type _UPGEdgeTypeLocal = keyof typeof UPG_EDGE_CATALOG;
  *
  * Three semantic families are sanctioned:
  *
- * 1. **Universal semantic verbs** — any node can inform / constrain / inspire
+ * 1. **Universal semantic verbs**: any node can inform / constrain / inspire
  *    any other node. The meaning is deliberately abstract; consumers render
  *    them as plain relational signals.
- * 2. **Decision-to-anything** — a decision can influence, be constrained by,
+ * 2. **Decision-to-anything**: a decision can influence, be constrained by,
  *    or produce any kind of node. Decisions cut across domains; binding the
  *    target would force a combinatorial explosion.
- * 3. **Universal ownership** — any node can be owned by a team, role,
+ * 3. **Universal ownership**: any node can be owned by a team, role,
  *    stakeholder, department, or person. Ownership is not per-entity-type.
  *
  * Adding a new polymorphic edge requires extending this array AND the
- * spec-integrity regression test — that forces a conscious decision and
+ * spec-integrity regression test, which forces a conscious decision and
  * keeps consumers (MCP, Entopo, audit tools) able to enumerate the full set.
  */
 declare const UPG_POLYMORPHIC_EDGE_KEYS: readonly _UPGEdgeTypeLocal[];
 /**
  * True if the edge uses the `'node'` wildcard at either endpoint. Derived
- * dynamically from `source_type`/`target_type` — not from the allow-list —
+ * dynamically from `source_type`/`target_type`, not from the allow-list,
  * so an accidentally-added polymorphic edge still returns true and surfaces
  * via the invariant test rather than silently passing.
  *
@@ -6829,7 +6885,7 @@ interface UPGSource {
  * const product: UPGProduct = {
  *   id: 'entopo',
  *   title: 'Entopo',
- *   description: 'The product creation tool — canvas + AI + graph, built on UPG.',
+ *   description: 'The product creation tool: canvas + AI + graph, built on UPG.',
  *   stage: 'beta',
  * }
  */
@@ -7054,7 +7110,7 @@ interface UPGPortfolioDocument {
 }
 
 /**
- * Legacy product-stage aliases — UPG-509 Part 2.
+ * Legacy product-stage aliases (UPG-509 Part 2).
  *
  * Existing graphs (`entopo.upg`, `sanity.upg`, `maximum-minimum.upg`,
  * `notion-saturated.upg`, etc.) carry `product.stage` values that pre-date
@@ -7071,7 +7127,7 @@ interface UPGPortfolioDocument {
  * already canonical and not a known legacy alias).
  *
  * Mapping rationale:
- * - `idea → concept` — pre-canonical alias from early v0.1 product nodes;
+ * - `idea → concept`: pre-canonical alias from early v0.1 product nodes;
  *   matches the v0.2.13 `properties.stage` migration `value_map` and the
  *   `UPG_PRODUCT_STAGE_COERCION_MAP` documented mapping.
  *
@@ -7096,7 +7152,7 @@ declare const LEGACY_PRODUCT_STAGES: Readonly<Record<string, UPGProductStage>>;
  *
  * - Returns the canonical stage when `stage` is a known legacy alias.
  * - Returns `stage` verbatim when it is not a known legacy alias (the input
- *   may itself already be canonical, or genuinely unknown — the strict
+ *   may itself already be canonical, or genuinely unknown. The strict
  *   write path is responsible for rejecting genuinely-unknown values).
  * - Returns `undefined` for `undefined` / `null` inputs.
  *
@@ -7107,7 +7163,7 @@ declare const LEGACY_PRODUCT_STAGES: Readonly<Record<string, UPGProductStage>>;
  * migrateProductStage('IDEA')      // → 'concept'
  * migrateProductStage('concept')   // → 'concept'  (already canonical, passthrough)
  * migrateProductStage('launch')    // → 'launch'   (already canonical, passthrough)
- * migrateProductStage('xyz')       // → 'xyz'      (unknown, passthrough — callers decide)
+ * migrateProductStage('xyz')       // → 'xyz'      (unknown, passthrough; callers decide)
  * migrateProductStage(undefined)   // → undefined
  */
 declare function migrateProductStage<T extends string | undefined | null>(stage: T): T extends string ? UPGProductStage | string : undefined;
@@ -7158,7 +7214,7 @@ type UPGEntityTypeMaturity = 'draft' | 'proposed' | 'stable' | 'deprecated' | 'r
  * }
  *
  * @example
- * // Deprecated type — readable in .upg files, migrates on write.
+ * // Deprecated type: readable in .upg files, migrates on write.
  * const painPointMeta: EntityTypeMeta = {
  *   name: 'pain_point',
  *   type_id: 'ent_018',
@@ -7226,7 +7282,7 @@ declare function getTypeId(name: string): string | undefined;
  *
  * @example
  * getTypeName('ent_016')   // → 'persona'
- * getTypeName('ent_018')   // → 'pain_point' (deprecated — see `getReplacementType`)
+ * getTypeName('ent_018')   // → 'pain_point' (deprecated; see `getReplacementType`)
  * getTypeName('ent_9999')  // → undefined
  */
 declare function getTypeName(typeId: string): string | undefined;
@@ -7237,7 +7293,7 @@ declare function getTypeName(typeId: string): string | undefined;
  */
 
 /**
- * A semantic domain — a flat grouping of related entity types.
+ * A semantic domain: a flat grouping of related entity types.
  *
  * @example
  * const userDomain: UPGDomain = {
@@ -7375,7 +7431,7 @@ declare const UPG_DOMAINS: readonly [{
 }, {
     readonly id: "pricing";
     readonly label: "Pricing & Packaging";
-    readonly description: "How you package and price your product. Pricing strategies set the overall approach. Pricing tiers define what customers buy — bundling features, trials, gates, and discounts. Discount strategies manage promotions. Trial configs define free-to-paid conversion mechanics. Paywalls gate premium features. Connects Business Model (revenue streams) to Growth (conversion optimization) and Sales (deal structure).";
+    readonly description: "How you package and price your product. Pricing strategies set the overall approach. Pricing tiers define what customers buy, bundling features, trials, gates, and discounts. Discount strategies manage promotions. Trial configs define free-to-paid conversion mechanics. Paywalls gate premium features. Connects Business Model (revenue streams) to Growth (conversion optimization) and Sales (deal structure).";
     readonly types: readonly ["pricing_strategy", "pricing_tier", "discount_strategy", "trial_config", "paywall"];
 }, {
     readonly id: "ai";
@@ -7441,13 +7497,13 @@ declare const UPG_DOMAINS: readonly [{
 /**
  * Union of every canonical domain identifier, derived from UPG_DOMAINS.
  *
- * Adding, removing, or renaming a domain updates this type automatically —
- * do NOT maintain a separate list here.
+ * Adding, removing, or renaming a domain updates this type automatically.
+ * Do NOT maintain a separate list here.
  */
 type UPGDomainId = typeof UPG_DOMAINS[number]['id'];
 /**
  * Canonical entity-type → domain-id lookup. O(1) access, derived from
- * `UPG_DOMAINS` at module init — never maintained by hand.
+ * `UPG_DOMAINS` at module init. Never maintained by hand.
  *
  * Prefer this over walking `UPG_DOMAINS` in downstream packages: the repeated
  * `UPG_DOMAINS.find(d => d.types.includes(t))?.id` pattern is a drift risk
@@ -7480,7 +7536,7 @@ declare function getDomainForType(entityType: string): UPGDomain | undefined;
  * Look up the canonical domain id for a typed entity type. O(1).
  *
  * Returns `undefined` only for the degenerate case where an entity type is
- * absent from every domain — which spec-integrity tests guarantee never
+ * absent from every domain, which spec-integrity tests guarantee never
  * happens for active types. Callers with a `UPGEntityType` can treat the
  * result as non-null, but the return type keeps the escape hatch for
  * defensive string-typed call sites.
@@ -7563,7 +7619,7 @@ declare function getValidChildren(entityType: string): readonly string[];
  */
 declare function canBeChildOf(childType: string, parentType: string): boolean;
 /**
- * Containment-free entity types — types that exist in the graph but are
+ * Containment-free entity types: types that exist in the graph but are
  * *referenced* by other nodes (via edges) rather than *contained* by
  * structural parents. They appear in no `UPG_VALID_CHILDREN` list and
  * have no hierarchy edges into them.
@@ -7571,12 +7627,12 @@ declare function canBeChildOf(childType: string, parentType: string): boolean;
  * This is parallel to `UPG_LIFECYCLE_FREE_TYPES` in `grammar/lifecycles.ts`:
  * both describe what a type *does not have*. Lifecycle-free types lack a
  * status progression; containment-free types lack a structural parent.
- * A type may be one, both, or neither — `person` is both; `theme` is
+ * A type may be one, both, or neither: `person` is both; `theme` is
  * lifecycle-free but structurally contained; `feature` is neither.
  *
  * The G2b hierarchy audit treats absence from `UPG_VALID_CHILDREN` as a
  * defect *unless* the type is in this set. Use this category for types
- * that are orthogonal to product structure — identities, references,
+ * that are orthogonal to product structure: identities, references,
  * cross-cutting concerns that any node might point at.
  *
  * `person` is the first explicit member of the set. Additional candidates
@@ -7591,7 +7647,7 @@ declare function canBeChildOf(childType: string, parentType: string): boolean;
  */
 declare const UPG_CONTAINMENT_FREE_TYPES: ReadonlySet<string>;
 /**
- * Returns `true` if `entityType` is containment-free — i.e. it deliberately
+ * Returns `true` if `entityType` is containment-free, i.e. it deliberately
  * has no structural parent in `UPG_VALID_CHILDREN`. See
  * `UPG_CONTAINMENT_FREE_TYPES` for the rationale and roster.
  */
@@ -7617,12 +7673,12 @@ interface UPGLifecycle {
      * group, label, and link templates without re-detecting them structurally.
      */
     template_id?: string;
-    /** The universal phases — fixed by the spec, understood by all tools. */
+    /** The universal phases, fixed by the spec and understood by all tools. */
     phases: LifecyclePhase[];
     /** Which phase a new entity of this type starts in. */
     initial_phase: string;
     /**
-     * Phases representing completion — the end points of normal forward progression.
+     * Phases representing completion: the end points of normal forward progression.
      *
      * A terminal phase MAY still declare `transitions_to` entries, which represent
      * late-state transitions (e.g., `archived → draft` for republishing, `approved
@@ -7641,17 +7697,17 @@ interface UPGLifecycle {
 }
 /** A phase is one broad stage in the entity's lifecycle. */
 interface LifecyclePhase {
-    /** Machine-readable phase ID — the universal vocabulary.
+    /** Machine-readable phase ID: the universal vocabulary.
      * @example "in_progress" */
     id: string;
     /** Human-readable label.
      * @example "In Progress" */
     label: string;
-    /** What this phase means — guidance for agents and documentation.
+    /** What this phase means: guidance for agents and documentation.
      * @example "The solution is actively being built or tested." */
     description: string;
     /**
-     * Which phases can follow this one — valid transitions at the phase level.
+     * Which phases can follow this one: valid transitions at the phase level.
      *
      * On non-terminal phases: forward progression targets.
      * On terminal phases: late-state / reopen / revive paths (optional; often empty).
@@ -7659,7 +7715,7 @@ interface LifecyclePhase {
      * @example ["shipped", "deferred"]
      */
     transitions_to: string[];
-    /** Core states defined by the spec — always available in this phase.
+    /** Core states defined by the spec, always available in this phase.
      * If omitted, the phase itself is the only state. No nesting needed. */
     core_states?: LifecycleState[];
 }
@@ -7697,26 +7753,26 @@ declare function getLifecycleForType(entityType: string): UPGLifecycle | undefin
  * Entity types that are deliberately lifecycle-free.
  *
  * Every active UPGEntityType must be either in UPG_LIFECYCLES or in this
- * set — the `10-lifecycle-coverage` audit enforces it. The coverage check
+ * set; the `10-lifecycle-coverage` audit enforces it. The coverage check
  * is the successor to the earlier ad-hoc "barren entity" info log.
  *
  * Categories represented here:
  *
- *  • **Reference / catalog data** — vocabulary definitions that don't
+ *  • **Reference / catalog data**: vocabulary definitions that don't
  *    transition (persona, skill, competitor, glossary_term).
- *  • **Structural primitives** — atoms of a larger composite (journey_step,
+ *  • **Structural primitives**: atoms of a larger composite (journey_step,
  *    funnel_step, aggregate, domain_entity, contract_clause).
- *  • **Data points / snapshots** — immutable observations (quote,
+ *  • **Data points / snapshots**: immutable observations (quote,
  *    observation, evidence, survey_response, test_result).
- *  • **Configuration** — static settings (paywall, trial_config,
+ *  • **Configuration**: static settings (paywall, trial_config,
  *    attribution_model, design_token).
- *  • **Historical records** — append-only ledger entries (changelog,
+ *  • **Historical records**: append-only ledger entries (changelog,
  *    approval_record, workflow_artifact, ai_trace, ai_cost_tracker).
- *  • **Profile / directory entries** — people and orgs (contact,
+ *  • **Profile / directory entries**: people and orgs (contact,
  *    stakeholder, organization).
- *  • **Computed / derived values** — not workflow-bearing (cohort,
+ *  • **Computed / derived values**: not workflow-bearing (cohort,
  *    customer_health_score, forecast, error_budget).
- *  • **DDD modelling primitives** — aggregates / value objects / commands —
+ *  • **DDD modelling primitives**: aggregates / value objects / commands;
  *    they describe the domain model, not processes within it.
  *
  * Some of these will gain lifecycles in v0.3 if Entopo usage surfaces real
@@ -7732,27 +7788,27 @@ declare const UPG_LIFECYCLE_FREE_TYPES: ReadonlySet<string>;
  * {@link UPG_LIFECYCLE_FREE_TYPES} for the full list and rationale).
  *
  * @example
- * isLifecycleFreeType('tag')        // true  — tags are reference data, not stateful artefacts
- * isLifecycleFreeType('feature')    // false — features carry a development lifecycle
+ * isLifecycleFreeType('tag')        // true  (tags are reference data, not stateful artefacts)
+ * isLifecycleFreeType('feature')    // false (features carry a development lifecycle)
  */
 declare function isLifecycleFreeType(entityType: string): boolean;
 /**
- * Entity types that are **triaged but not yet implemented** — each has a
+ * Entity types that are **triaged but not yet implemented**; each has a
  * lifecycle planned for a later phase of. This set exists so that
  * the coverage audit (`10-lifecycle-coverage`) distinguishes
- * "actively deferred" from "untriaged" — moving a type here is a commitment
+ * "actively deferred" from "untriaged"; moving a type here is a commitment
  * to enrich it, not a punt.
  *
  * Phase breakdown (committed 2026-04-17):
  *
- *  • **Phase B** — high-value hand-authored lifecycles (NL) + two new
+ *  • **Phase B**: high-value hand-authored lifecycles (NL) + two new
  *    templates (SALES_DEAL, RISK_ITEM). ~30 types: outcome, feature, epic,
  *    user_story, bug, deal, threat, risk, compliance_requirement, insight,
  *    hypothesis-adjacent artefacts, workflow artefacts, etc.
- *  • **Phase C** — expand existing-template coverage to the PUBLISHING /
+ *  • **Phase C**: expand existing-template coverage to the PUBLISHING /
  *    OPERATIONAL / APPROVAL / MATURITY / WORK_ITEM buckets via
  *    `fromTemplate()`. ~60 types.
- *  • **Phase D** — residual new lifecycles for types that don't fit a
+ *  • **Phase D**: residual new lifecycles for types that don't fit a
  *    template cleanly but didn't make Phase B's cut. ~10 types.
  *
  * As phases land, types migrate out of this set into UPG_LIFECYCLES.
@@ -7765,13 +7821,13 @@ declare const UPG_LIFECYCLE_PLANNED_TYPES: ReadonlySet<string>;
  * (see {@link UPG_LIFECYCLE_PLANNED_TYPES}).
  *
  * @example
- * isLifecyclePlannedType('outcome')   // true  — planned for a later phase
- * isLifecyclePlannedType('feature')   // false — feature lifecycle is already implemented
+ * isLifecyclePlannedType('outcome')   // true  (planned for a later phase)
+ * isLifecyclePlannedType('feature')   // false (feature lifecycle is already implemented)
  */
 declare function isLifecyclePlannedType(entityType: string): boolean;
 /** A render-ready lifecycle state (one phase of the underlying lifecycle). */
 interface LifecycleRenderState {
-    /** Phase id — e.g. `'draft'`, `'in_progress'`, `'archived'`. */
+    /** Phase id (e.g. `'draft'`, `'in_progress'`, `'archived'`). */
     id: string;
     /** Human-readable label. */
     label: string;
@@ -7790,10 +7846,10 @@ interface LifecycleRenderTransition {
      * Classification derived from the lifecycle's terminal set and authoring
      * order:
      *
-     * - `'reopen'`   — source is terminal, target is not (e.g. `archived → draft`).
-     * - `'terminal'` — target is terminal, source is not (forward to completion).
-     * - `'backward'` — target appears before source in `phases[]` and is not a reopen.
-     * - `'forward'`  — everything else.
+     * - `'reopen'`: source is terminal, target is not (e.g. `archived → draft`).
+     * - `'terminal'`: target is terminal, source is not (forward to completion).
+     * - `'backward'`: target appears before source in `phases[]` and is not a reopen.
+     * - `'forward'`: everything else.
      *
      * The classification is a render hint, not a validation rule: any transition
      * declared in the source lifecycle is valid by definition.
@@ -7814,7 +7870,7 @@ interface LifecycleRenderShape {
     states: LifecycleRenderState[];
     /** Render transitions, classified by `kind`. */
     transitions: LifecycleRenderTransition[];
-    /** Initial state id — equals the source `initial_phase`. */
+    /** Initial state id; equals the source `initial_phase`. */
     initial_state: string;
 }
 /**
@@ -7822,7 +7878,7 @@ interface LifecycleRenderShape {
  * lifecycle, or `null` if the type is intentionally lifecycle-free
  * (see {@link UPG_LIFECYCLE_FREE_TYPES}).
  *
- * The shape is flattened to one level — each phase becomes one render state.
+ * The shape is flattened to one level; each phase becomes one render state.
  * Optional finer-grained `core_states` are not surfaced here; consumers that
  * need them should read the source lifecycle directly via
  * {@link getLifecycleForType}.
@@ -7906,7 +7962,7 @@ declare const UPG_SCALES: Record<string, UPGScaleDefinition>;
 /**
  * Look up a scale definition by its ID.
  *
- * Returns undefined for unknown IDs — callers should handle this case
+ * Returns undefined for unknown IDs; callers should handle this case
  * gracefully (e.g. fall back to displaying raw value).
  *
  * @example
@@ -7921,8 +7977,8 @@ declare function getScale(scaleId: string): UPGScaleDefinition | undefined;
  * 1. Check `PROPERTY_SCALE_MAP` for a property-level override.
  * 2. Fall back to `'scale_5'` (generic 1–5 ordinal) for all other properties.
  *
- * The `entityType` parameter is accepted for API stability — future versions
- * may add per-entity overrides — but the initial implementation ignores it.
+ * The `entityType` parameter is accepted for API stability; future versions
+ * may add per-entity overrides, but the initial implementation ignores it.
  *
  * @param entityType  - The UPG entity type string (e.g. `'problem_statement'`).
  *                      Currently unused; reserved for future per-entity overrides.
@@ -7958,7 +8014,7 @@ interface UPGEnumScaleValue {
  *
  * `values` is ordered semantically (e.g. low → high for ordinal scales;
  * strict → permissive for rule strength). Array index is the canonical
- * position — no separate `position` field.
+ * position (no separate `position` field).
  */
 interface UPGEnumScaleDefinition {
     /** Matches the TypeScript type name (e.g. `'HealthStatus'`) */
@@ -7970,12 +8026,12 @@ interface UPGEnumScaleDefinition {
     /** Per-value metadata in semantic order */
     values: UPGEnumScaleValue[];
     /**
-     * Optional rendering hint — which end of the scale is desirable.
+     * Optional rendering hint: which end of the scale is desirable.
      * Parallel to `SCALE_TONE_DIRECTION` for numeric scales.
      *
-     * `'high-is-good'`  — first value is best (e.g. on_track, high confidence)
-     * `'low-is-good'`   — last value in natural order is worst (e.g. critical urgency is bad)
-     * `'neutral'`       — no inherent good/bad direction (e.g. Cadence, Priority)
+     * `'high-is-good'`: first value is best (e.g. on_track, high confidence)
+     * `'low-is-good'`: last value in natural order is worst (e.g. critical urgency is bad)
+     * `'neutral'`: no inherent good/bad direction (e.g. Cadence, Priority)
      */
     tone_direction?: 'high-is-good' | 'low-is-good' | 'neutral';
 }
@@ -8010,7 +8066,7 @@ declare const UPG_MIGRATIONS: Record<string, UPGTypeMigration[]>;
  *
  * Returns a negative number if `a < b`, zero if `a === b`, positive if `a > b`.
  * Components are compared numerically (e.g. `0.2.11` is greater than `0.2.8`,
- * not less — naive string comparison gets this backwards because `'11' < '8'`
+ * not less; naive string comparison gets this backwards because `'11' < '8'`
  * lexicographically).
  *
  * Used by every range-filtered migration helper below
@@ -8031,7 +8087,7 @@ declare function compareVersions(a: string, b: string): number;
  * Used by TYPE_ALIASES and .upg file readers.
  *
  * @example
- * // Upgrading from v0 (pre-UPG) to v0.2.0 — collect every type rename.
+ * // Upgrading from v0 (pre-UPG) to v0.2.0: collect every type rename.
  * const map = getMigrationMap('0.0.0', '0.2.0')
  * // map.pain_point === 'need'
  * // map.jtbd       === 'job'
@@ -8042,7 +8098,7 @@ declare function getMigrationMap(fromVersion: string, toVersion: string): Record
  * Apply migrations to a single node, converting its type and
  * merging default properties.
  *
- * `T` is the caller's node shape — typically `UPGBaseNode` or a narrower
+ * `T` is the caller's node shape, typically `UPGBaseNode` or a narrower
  * app-specific node type. The constraint (`{ type: string; properties?: ... }`)
  * keeps the function node-library-agnostic so adapters, CLI tools, and test
  * fixtures can all reuse it without coupling to `UPGBaseNode` directly.
@@ -8056,7 +8112,7 @@ declare function getMigrationMap(fromVersion: string, toVersion: string): Record
  * // migrated.properties.description === 'Onboarding is slow'  // original preserved
  *
  * @example
- * // Non-deprecated type passes through — return shape preserves T.
+ * // Non-deprecated type passes through; return shape preserves T.
  * const healthy = { id: 'n2', type: 'persona', properties: { is_primary: true } }
  * const same = migrateNode(healthy, '0.0.0', '0.1.0')
  * // same === healthy  (referentially unchanged)
@@ -8081,9 +8137,9 @@ declare function getDeprecatedTypes(): Set<string>;
  *
  * Discriminated by `kind`:
  *
- * - `'drop_props'` — remove keys from `node.properties`. The original
+ * - `'drop_props'`: remove keys from `node.properties`. The original
  *   shape; the existing v0.2.2 + v0.2.8 entries use this.
- * - `'rename_top_level'` — rename a top-level `UPGBaseNode` field to a
+ * - `'rename_top_level'`: rename a top-level `UPGBaseNode` field to a
  *   different top-level field, optionally remapping its value. Used when a
  *   pre-canonical custom field (e.g. `lifecycle_status`) shifts to its
  *   canonical slot (`status`).
@@ -8091,7 +8147,7 @@ declare function getDeprecatedTypes(): Set<string>;
  *   top-level field, optionally remapping. Used when a slot that was
  *   pragmatically stuffed in `properties` graduates to a top-level
  *   `UPGBaseNode` slot (e.g. `properties.stage` → top-level `status`).
- * - `'drop_when_self_referential'` — drop top-level fields whose value
+ * - `'drop_when_self_referential'`: drop top-level fields whose value
  *   equals the node's own `id` or `type` (or another configured
  *   self-reference). Used to clean up redundant round-trip metadata that's
  *   only meaningful when pointing OUT of the node, not at itself.
@@ -8217,7 +8273,7 @@ declare function migrateNodeProperties<T extends {
     changes: UPGPropertyMigrationChange[];
 };
 /**
- * Returns every property migration entry between two versions — useful for
+ * Returns every property migration entry between two versions; useful for
  * load-time warning generation and audit reports.
  */
 declare function getPropertyMigrations(fromVersion: string, toVersion: string): UPGPropertyMigration[];
@@ -8232,7 +8288,7 @@ interface UPGSplitTarget {
     /** Defaults merged after keep_props (route-specific defaults win). */
     defaults?: Record<string, unknown>;
 }
-/** Per-target route plan — what to spawn and what overrides apply. */
+/** Per-target route plan: what to spawn and what overrides apply. */
 interface UPGSplitRouteTarget {
     /** Route-specific defaults merged on top of UPGSplitTarget.defaults. */
     defaults?: Record<string, unknown>;
@@ -8258,9 +8314,9 @@ interface UPGSplitEdge {
     /**
      * When to emit the edge.
      *
-     * - `'both_spawned'` — only emit if both source_ref and target_ref were
+     * - `'both_spawned'`: only emit if both source_ref and target_ref were
      *   spawned by the routing rule.
-     * - `'always'` — emit unconditionally (rare; only valid if both refs
+     * - `'always'`: emit unconditionally (rare; only valid if both refs
      *   appear in every routing entry's `spawn`).
      */
     when: 'both_spawned' | 'always';
@@ -8275,7 +8331,7 @@ interface UPGSplitMigration {
     status_property: string;
     /** The N canonical types this rule produces. */
     produces: readonly UPGSplitTarget[];
-    /** Per-status routing — keys are values of source[status_property]. */
+    /** Per-status routing: keys are values of source[status_property]. */
     routing: Record<string, UPGSplitRoute>;
     /** Edges to emit between spawned targets. */
     edges: readonly UPGSplitEdge[];
@@ -8303,7 +8359,7 @@ declare function getSplitMigrations(fromVersion: string, toVersion: string): UPG
  * `flip` is true) and may gate on endpoint identity via
  * `requires_source_type` / `requires_target_type`.
  *
- * `drop` removes the edge entirely (no replacement key) — used when a
+ * `drop` removes the edge entirely (no replacement key); used when a
  * legacy edge has been superseded by a structurally different canonical
  * edge whose endpoints don't match the legacy rule's `from`.
  */
@@ -8337,13 +8393,13 @@ declare const UPG_EDGE_MIGRATIONS: Record<string, UPGEdgeMigration[]>;
  * Get all edge migration rules between two versions, in version order.
  *
  * @example
- * // v0.2.0 backfill — six jtbd→job edge renames.
+ * // v0.2.0 backfill: six jtbd→job edge renames.
  * const rules = getUPGEdgeMigrations('0.0.0', '0.2.0')
  * rules.length // → 6
  * rules.every(r => r.kind === 'rename') // → true
  *
  * @example
- * // Full v0.2.x range — every rule from v0.2.0 + v0.2.7 + v0.2.8.
+ * // Full v0.2.x range: every rule from v0.2.0 + v0.2.7 + v0.2.8.
  * getUPGEdgeMigrations('0.0.0', '0.2.8').filter(r => r.kind === 'drop').length // → 4
  */
 declare function getUPGEdgeMigrations(fromVersion: string, toVersion: string): UPGEdgeMigration[];
@@ -8353,7 +8409,7 @@ declare function getUPGEdgeMigrations(fromVersion: string, toVersion: string): U
  * Both `sourceType` and `targetType` should be the *post-migration* node
  * types (i.e. after `migrateNode` / `applySplit` has run on the endpoints).
  * When omitted, rules with `requires_source_type` / `requires_target_type`
- * guards are skipped (safer default — a guard that cannot be evaluated
+ * guards are skipped (safer default; a guard that cannot be evaluated
  * does not fire).
  */
 interface UPGEdgeMigrationEndpoints {
@@ -8368,7 +8424,7 @@ interface UPGEdgeMigrationEndpoints {
  * dead-ends.
  *
  * **Why this exists.** `UPG_EDGE_MIGRATIONS` accumulates rules across the
- * spec's history. A single edge can be renamed multiple times — and the
+ * spec's history. A single edge can be renamed multiple times, and the
  * direction can reverse (e.g. v0.2.8 renamed `solution_proposes_hypothesis`
  * → `solution_proposes_hypothesis_claim`, then v0.4.0 renamed the latter
  * back to the former). Naively picking "the first rule whose `from` matches"
@@ -8384,19 +8440,19 @@ interface UPGEdgeMigrationEndpoints {
  * outcome rather than loop forever.
  *
  * **Return values.**
- *  - `{ kind: 'canonical', to }` — the walk landed on a key present in
+ *  - `{ kind: 'canonical', to }`: the walk landed on a key present in
  *    `UPG_EDGE_CATALOG`. Callers should suggest `to` as the migration target.
- *  - `{ kind: 'drop' }` — the walk encountered a `drop` rule. The edge has
+ *  - `{ kind: 'drop' }`: the walk encountered a `drop` rule. The edge has
  *    no canonical replacement.
- *  - `{ kind: 'dead_end', last }` — no rule matched and `last` is not in
+ *  - `{ kind: 'dead_end', last }`: no rule matched and `last` is not in
  *    `UPG_EDGE_CATALOG`. The edge is non-canonical with no known migration
  *    target.
- *  - `{ kind: 'cycle', visited }` — a cycle was detected. Returned so
+ *  - `{ kind: 'cycle', visited }`: a cycle was detected. Returned so
  *    callers can degrade gracefully. Should not happen in practice given
  *    the version-ordered structure of `UPG_EDGE_MIGRATIONS`.
  *
  * **Caller note.** Callers that already know `edge_type` is canonical
- * (i.e. `edge_type in UPG_EDGE_CATALOG`) should NOT call this helper —
+ * (i.e. `edge_type in UPG_EDGE_CATALOG`) should NOT call this helper;
  * there's nothing to suggest. The helper is for the case where the edge
  * type is deprecated and the caller needs to find its canonical successor.
  *
@@ -8411,7 +8467,7 @@ interface UPGEdgeMigrationEndpoints {
  * // → { kind: 'drop' }
  *
  * @example
- * // Already-canonical edge type — returns dead_end because the helper is
+ * // Already-canonical edge type: returns dead_end because the helper is
  * // intended for non-canonical callers. The 'canonical' branch fires only
  * // when the chain ENDS on a catalog entry, not when it STARTS on one.
  * // (In practice the validator skips this case before calling.)
@@ -8436,20 +8492,20 @@ declare function walkMigrationChainToCanonical(edge_type: string, catalog: Reado
  *   - the original edge (un-shaped, referentially equal) if no rule matched;
  *   - a new edge with retyped `type` (and possibly swapped `source`/`target`
  *     when the rule sets `flip: true`) if a `rename` rule matched;
- *   - `null` if a `drop` rule matched — caller should remove the edge.
+ *   - `null` if a `drop` rule matched; caller should remove the edge.
  *
  * Endpoint guards (`requires_source_type` / `requires_target_type`) check
  * the *post-migration* endpoint types provided via `endpoints`. When
- * `endpoints` is omitted, guarded rules are skipped — callers running edge
+ * `endpoints` is omitted, guarded rules are skipped; callers running edge
  * migration in isolation (without endpoint type context) get only the
  * un-guarded rules.
  *
- * `T` is the caller's edge shape — only `type` is required; `source` and
+ * `T` is the caller's edge shape; only `type` is required. `source` and
  * `target` are touched only when `flip: true` and are otherwise preserved
  * verbatim.
  *
  * @example
- * // No rule matches — edge passes through unchanged.
+ * // No rule matches; edge passes through unchanged.
  * const edge = { id: 'e1', type: 'persona_pursues_job' }
  * migrateEdge(edge, '0.2.0', '0.2.8') === edge // → true
  *
@@ -8460,7 +8516,7 @@ declare function walkMigrationChainToCanonical(edge_type: string, catalog: Reado
  * migrated?.type // → 'persona_pursues_job'
  *
  * @example
- * // Drop rule matches — null signals "remove this edge".
+ * // Drop rule matches; null signals "remove this edge".
  * const dropped = { id: 'e3', type: 'experiment_tests_hypothesis' }
  * migrateEdge(dropped, '0.0.0', '0.2.7') // → null
  */
@@ -8497,7 +8553,7 @@ declare function migrateEdge<T extends {
  * Each top-level key is an entity type; each inner key is a legacy status
  * value observed in real graphs; the value is the canonical phase id from
  * that type's lifecycle. Entity types absent from this map have no
- * registered status migration — `migrateStatusValue` returns `null` for
+ * registered status migration; `migrateStatusValue` returns `null` for
  * them, signalling "no automated fix; surface to operator".
  *
  * **Population strategy.** Only mappings that are unambiguous from observed
@@ -8505,7 +8561,7 @@ declare function migrateEdge<T extends {
  * different canonical phases, the type is left empty rather than guessing.
  *
  * **Why this is a map of maps rather than a list of rules.** Status values
- * are entity-type-scoped — `"active"` means different things on `service`,
+ * are entity-type-scoped: `"active"` means different things on `service`,
  * `feature`, and `hypothesis`. A flat `[{ from, to, type }]` list would
  * force every lookup to filter; a map of maps gives O(1) `[type][value]`
  * lookup and makes the per-type registry obvious to readers.
@@ -8518,7 +8574,7 @@ declare const UPG_STATUS_MIGRATIONS: Partial<Record<UPGEntityType, Record<string
  * Caller contract: only invoke when the current status is known-invalid
  * for the entity's lifecycle. `null` signals "no automated fix is on
  * file; surface to the operator". The presence of a mapping does NOT
- * imply the current status is invalid — checking validity is the caller's
+ * imply the current status is invalid; checking validity is the caller's
  * job (typically via `getLifecycleForType(entityType).phases`).
  *
  * @example
@@ -8648,9 +8704,9 @@ interface UPGValidationError {
 interface UPGValidationResult {
     /** Whether the document passed all mandatory spec checks */
     valid: boolean;
-    /** Spec violations — any entry here means `valid` is false */
+    /** Spec violations: any entry here means `valid` is false */
     errors: UPGValidationError[];
-    /** Best-practice notices — present even when `valid` is true */
+    /** Best-practice notices: present even when `valid` is true */
     warnings: UPGValidationWarning[];
 }
 interface UPGValidationWarning {
@@ -8681,7 +8737,7 @@ interface UPGValidationWarning {
  */
 declare function validateUPGDocument(doc: unknown): UPGValidationResult;
 /**
- * Type guard — returns true if the document is a valid UPGDocument.
+ * Type guard: returns true if the document is a valid UPGDocument.
  * Use `validateUPGDocument` for detailed error reporting.
  *
  * @example
@@ -8709,10 +8765,10 @@ type ISODateTime = string;
  *
  * Format: `PnYnMnDTnHnMnS` (year/month/day prefix P, time prefix T).
  * Common examples:
- *   `P14D`     — 14 days
- *   `P3M`      — 3 months
- *   `PT2H30M`  — 2 hours 30 minutes
- *   `P1Y6M`    — 1 year 6 months
+ *   `P14D`     : 14 days
+ *   `P3M`      : 3 months
+ *   `PT2H30M`  : 2 hours 30 minutes
+ *   `P1Y6M`    : 1 year 6 months
  *
  * Used for retention periods, notice periods, agreement terms, lead times,
  * lookback windows, sprint durations, and any other measured time span.
@@ -8725,9 +8781,9 @@ type Duration = string;
  * Extended 6-field form: `second minute hour day-of-month month day-of-week`
  *
  * Examples:
- *   `'0 9 * * 1'`       — every Monday at 09:00
- *   `'0 0 1 * *'`       — first day of every month at midnight
- *   `'*\/15 * * * *'`   — every 15 minutes
+ *   `'0 9 * * 1'`       : every Monday at 09:00
+ *   `'0 0 1 * *'`       : first day of every month at midnight
+ *   `'*\/15 * * * *'`   : every 15 minutes
  *
  * Used for scheduled data pipelines, recurring jobs, and automation triggers.
  */
@@ -8735,12 +8791,12 @@ type Cron = string;
 /**
  * Flexible, human-readable timeframe label.
  *
- * Accepted forms (not exhaustive — this is an open-shape string):
- *   `'Q1 2026'`          — calendar quarter
- *   `'2026-H1'`          — calendar half-year
- *   `'FY2027 Q2'`        — fiscal quarter
- *   `'12-18 months'`     — relative range
- *   `'now'` / `'ongoing'` — open-ended
+ * Accepted forms (not exhaustive; this is an open-shape string):
+ *   `'Q1 2026'`          : calendar quarter
+ *   `'2026-H1'`          : calendar half-year
+ *   `'FY2027 Q2'`        : fiscal quarter
+ *   `'12-18 months'`     : relative range
+ *   `'now'` / `'ongoing'` : open-ended
  *
  * Used to unify `timeline`, `time_horizon`, `timeframe`, `period`, and
  * `report_period` properties that share the same human-calendar semantics
@@ -8753,7 +8809,7 @@ type Timeframe = string;
  * Examples: `'USD'`, `'EUR'`, `'GBP'`, `'JPY'`.
  * All characters must be ASCII uppercase letters (A–Z).
  *
- * Used wherever a property JSDoc says "ISO 4217" — pricing tiers, contracts,
+ * Used wherever a property JSDoc says "ISO 4217": pricing tiers, contracts,
  * sales quotes, growth campaigns, and localisation settings.
  */
 type ISO4217 = string;
@@ -8823,18 +8879,18 @@ type SignalSentiment = 'positive' | 'neutral' | 'negative' | 'mixed';
  * provides the canonical closed set for migration.
  *
  * Members:
- *   `'analytics_event'` — first-party product analytics event (PostHog, Amplitude, etc.)
- *   `'community'`       — forum, Discord, Slack community, etc.
- *   `'email'`           — direct email or newsletter reply
- *   `'in_app'`          — in-product feedback widget, NPS prompt, or beta-feedback panel
- *   `'interview'`       — user or sales interview
- *   `'other'`           — catch-all for unlisted channels
- *   `'review'`          — app store or G2/Capterra review
- *   `'sales_call'`      — sales demo or discovery call
- *   `'social'`          — social media mention or DM
- *   `'support_ticket'`  — helpdesk or in-app support ticket
- *   `'survey'`          — NPS, CSAT, or custom survey
- *   `'usage_session'`   — observed product session (telemetry-derived friction signal)
+ *   `'analytics_event'` : first-party product analytics event (PostHog, Amplitude, etc.)
+ *   `'community'`       : forum, Discord, Slack community, etc.
+ *   `'email'`           : direct email or newsletter reply
+ *   `'in_app'`          : in-product feedback widget, NPS prompt, or beta-feedback panel
+ *   `'interview'`       : user or sales interview
+ *   `'other'`           : catch-all for unlisted channels
+ *   `'review'`          : app store or G2/Capterra review
+ *   `'sales_call'`      : sales demo or discovery call
+ *   `'social'`          : social media mention or DM
+ *   `'support_ticket'`  : helpdesk or in-app support ticket
+ *   `'survey'`          : NPS, CSAT, or custom survey
+ *   `'usage_session'`   : observed product session (telemetry-derived friction signal)
  */
 type SignalChannel = 'analytics_event' | 'community' | 'email' | 'in_app' | 'interview' | 'other' | 'review' | 'sales_call' | 'social' | 'support_ticket' | 'survey' | 'usage_session';
 /**
@@ -8847,15 +8903,15 @@ type SignalChannel = 'analytics_event' | 'community' | 'email' | 'in_app' | 'int
  * rather than a labelled tier.
  *
  * Members (coarse → fine):
- *   `'continuous'` — always running / no discrete recurrence
- *   `'hourly'`     — recurs every hour
- *   `'daily'`      — recurs every day
- *   `'weekly'`     — recurs every week
- *   `'monthly'`    — recurs every month
- *   `'quarterly'`  — recurs every calendar quarter
- *   `'yearly'`     — recurs every year
- *   `'on_demand'`  — triggered by event, not schedule
- *   `'other'`      — recurs on a cadence not captured by the above tiers
+ *   `'continuous'` : always running, no discrete recurrence
+ *   `'hourly'`     : recurs every hour
+ *   `'daily'`      : recurs every day
+ *   `'weekly'`     : recurs every week
+ *   `'monthly'`    : recurs every month
+ *   `'quarterly'`  : recurs every calendar quarter
+ *   `'yearly'`     : recurs every year
+ *   `'on_demand'`  : triggered by event, not schedule
+ *   `'other'`      : recurs on a cadence not captured by the above tiers
  *
  * Introduced in v0.4.0 as the canonical replacement for ad-hoc
  * `frequency?: string` and `*cadence?: string` properties (Concern 2 axis
@@ -8875,17 +8931,17 @@ type Cadence = 'continuous' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'quart
  * will normalise casing in a follow-up pass.
  *
  * Members (alphabetical):
- *   `'asyncapi'`  — AsyncAPI / event-driven API spec
- *   `'event'`     — generic event/message bus
- *   `'file'`      — file-based transfer (SFTP, S3, etc.)
- *   `'graphql'`   — GraphQL over HTTP
- *   `'grpc'`      — gRPC / Protocol Buffers
- *   `'mqtt'`      — MQTT (IoT / lightweight pub-sub)
- *   `'other'`     — unlisted protocol
- *   `'rest'`      — REST over HTTP
- *   `'soap'`      — SOAP / XML web services
- *   `'webhook'`   — HTTP webhook (push callback)
- *   `'websocket'` — WebSocket bidirectional stream
+ *   `'asyncapi'`  : AsyncAPI / event-driven API spec
+ *   `'event'`     : generic event/message bus
+ *   `'file'`      : file-based transfer (SFTP, S3, etc.)
+ *   `'graphql'`   : GraphQL over HTTP
+ *   `'grpc'`      : gRPC / Protocol Buffers
+ *   `'mqtt'`      : MQTT (IoT / lightweight pub-sub)
+ *   `'other'`     : unlisted protocol
+ *   `'rest'`      : REST over HTTP
+ *   `'soap'`      : SOAP / XML web services
+ *   `'webhook'`   : HTTP webhook (push callback)
+ *   `'websocket'` : WebSocket bidirectional stream
  */
 type Protocol = 'asyncapi' | 'event' | 'file' | 'graphql' | 'grpc' | 'mqtt' | 'other' | 'rest' | 'soap' | 'webhook' | 'websocket';
 /**
@@ -8898,18 +8954,18 @@ type Protocol = 'asyncapi' | 'event' | 'file' | 'graphql' | 'grpc' | 'mqtt' | 'o
  * This primitive is the alphabetical superset of both.
  *
  * Members:
- *   `'discord'`   — Discord community / server
- *   `'email'`     — newsletter / email marketing platform
- *   `'google'`    — Google Ads / Search / Display
- *   `'instagram'` — Instagram organic or paid
- *   `'linkedin'`  — LinkedIn organic or paid
- *   `'meta'`      — Meta Ads (Facebook/Instagram ad platform)
- *   `'other'`     — unlisted platform
- *   `'podcast'`   — podcast advertising or distribution
- *   `'reddit'`    — Reddit organic or paid
- *   `'tiktok'`    — TikTok organic or paid
- *   `'twitter'`   — Twitter / X organic or paid
- *   `'youtube'`   — YouTube organic or paid
+ *   `'discord'`   : Discord community / server
+ *   `'email'`     : newsletter / email marketing platform
+ *   `'google'`    : Google Ads / Search / Display
+ *   `'instagram'` : Instagram organic or paid
+ *   `'linkedin'`  : LinkedIn organic or paid
+ *   `'meta'`      : Meta Ads (Facebook/Instagram ad platform)
+ *   `'other'`     : unlisted platform
+ *   `'podcast'`   : podcast advertising or distribution
+ *   `'reddit'`    : Reddit organic or paid
+ *   `'tiktok'`    : TikTok organic or paid
+ *   `'twitter'`   : Twitter / X organic or paid
+ *   `'youtube'`   : YouTube organic or paid
  */
 type MarketingPlatform = 'discord' | 'email' | 'google' | 'instagram' | 'linkedin' | 'meta' | 'other' | 'podcast' | 'reddit' | 'tiktok' | 'twitter' | 'youtube';
 
@@ -9035,7 +9091,7 @@ interface VisionProperties {
  * @example
  * const properties: MissionProperties = {
  *   target_audience: 'Product managers and founders at 10–200-person B2B SaaS companies.',
- *   core_value: 'Clarity beats velocity — decisions you can justify compound faster than code.',
+ *   core_value: 'Clarity beats velocity: decisions you can justify compound faster than code.',
  *   differentiation: 'Open interchange format + works where you already think.',
  * }
  */
@@ -9414,7 +9470,7 @@ interface JobStepProperties {
  * const properties: SwitchingCostProperties = {
  *   cost_type: 'financial',
  *   magnitude: 'high',
- *   barrier_description: 'Extensive Notion workspace with years of history — migration feels daunting.',
+ *   barrier_description: 'Extensive Notion workspace with years of history; migration feels daunting.',
  * }
  */
 interface SwitchingCostProperties {
@@ -10471,7 +10527,7 @@ interface JourneyStepProperties {
  *   opportunity_score: 5,
  *   evidence: 'Pasted transcript appears as a single text node',
  *   system: 'canvas-paste-handler',
- *   notes: 'Most users hesitate before pasting — too much trust required.',
+ *   notes: 'Most users hesitate before pasting; too much trust required.',
  * }
  */
 interface JourneyActionProperties {
@@ -10545,7 +10601,7 @@ interface DesignQuestionProperties {
  * @example
  * const properties: DesignConceptProperties = {
  *   sketch_url: 'https://figma.com/file/abc/sketch',
- *   rationale: 'Reduces support burden and lifts activation — both priorities this quarter.',
+ *   rationale: 'Reduces support burden and lifts activation, both priorities this quarter.',
  *   concept_status: 'exploring',
  * }
  */
@@ -10797,7 +10853,7 @@ interface DesignPatternProperties {
  * const properties: DesignGuidelineProperties = {
  *   guideline_category: 'spacing',
  *   applies_to: 'All customer-facing surfaces',
- *   rationale: 'Reduces support burden and lifts activation — both priorities this quarter.',
+ *   rationale: 'Reduces support burden and lifts activation, both priorities this quarter.',
  * }
  */
 interface DesignGuidelineProperties {
@@ -11249,7 +11305,7 @@ interface EpicProperties {
  * persona will be able to do. Lifecycle-free: a statement either still
  * describes a real promise, or is superseded by a new one when the promise changes.
  *
- * Pairs with `task` (UCS pattern P4 — story_task collapsed into task) via `task_implements_user_story`.
+ * Pairs with `task` (UCS pattern P4, story_task collapsed into task) via `task_implements_user_story`.
  * One statement can have many tasks (re-implementation, per-platform variants);
  * each task carries its own lifecycle.
  *
@@ -13305,7 +13361,7 @@ interface A11yAuditProperties {
  * @example
  * const properties: A11yIssueProperties = {
  *   severity: 'minor',
- *   wcag_criterion: '1.4.3 — Contrast (Minimum)',
+ *   wcag_criterion: '1.4.3: Contrast (Minimum)',
  *   rule_id: 'dqr_nodes_no_null_title',
  * }
  */
@@ -13782,7 +13838,7 @@ interface KnowledgeBaseArticleProperties {
  * const properties: BrandAssetProperties = {
  *   asset_type: 'logo',
  *   url: 'https://example.com/doc',
- *   usage_rights: 'Internal use only — do not redistribute without written approval.',
+ *   usage_rights: 'Internal use only. Do not redistribute without written approval.',
  * }
  */
 interface BrandAssetProperties {
@@ -14221,7 +14277,7 @@ interface RoleProperties {
  *
  * Properties are minimal: identity, addressability, coordination. HR-shaped
  * fields (`seniority`, `employment_type`, `start_date`) are intentionally
- * out of scope — they encode org-design opinions that vary wildly across
+ * out of scope; they encode org-design opinions that vary wildly across
  * companies and have no bearing on product-graph reasoning. UPG is not
  * an HRIS.
  *
@@ -14475,7 +14531,7 @@ interface RiskRegisterProperties {
  * const properties: ChangeRequestProperties = {
  *   change_type: 'scope',
  *   priority: 'high',
- *   impact_assessment: 'Medium — affects onboarding success metric.',
+ *   impact_assessment: 'Medium: affects onboarding success metric.',
  * }
  */
 interface ChangeRequestProperties {
@@ -14877,6 +14933,8 @@ interface WorkflowTemplateProperties {
     checkpoint_enabled?: boolean;
     /** Whether a human approval step is required */
     human_in_loop?: boolean;
+    /** Version label for this workflow template (e.g. "2.1") */
+    version?: string;
 }
 /** Workflow run.
  *
@@ -14940,6 +14998,8 @@ interface AgentDefinitionProperties {
     multimodal?: boolean;
     /** Operational status of this agent definition */
     agent_status?: 'active' | 'disabled' | 'testing';
+    /** Version label for this agent definition (e.g. "1.4.2") */
+    version?: string;
 }
 /** Agent session.
  *
@@ -15251,6 +15311,8 @@ interface PartnershipProperties {
     risk_level?: UPGAssessment;
     /** Internal owner */
     owner?: string;
+    /** Date the partnership became effective (ISO 8601) */
+    start_date?: ISODate;
 }
 /** KeyResource.
  *
@@ -15558,7 +15620,7 @@ interface GrowthLoopProperties {
  *
  * @example
  * const properties: VariantProperties = {
- *   variant_name: 'B — simplified onboarding',
+ *   variant_name: 'B: simplified onboarding',
  *   traffic_percentage: 42,
  *   variant_status: 'active',
  * }
@@ -16641,7 +16703,7 @@ interface LocaleConfigProperties {
  * @example
  * const properties: CulturalAdaptationProperties = {
  *   adaptation_type: 'content',
- *   rationale: 'Reduces support burden and lifts activation — both priorities this quarter.',
+ *   rationale: 'Reduces support burden and lifts activation, both priorities this quarter.',
  * }
  */
 interface CulturalAdaptationProperties {
@@ -16992,7 +17054,7 @@ interface WorkspaceProperties {
 /** Type-safe lookup from entity type string to its property interface.
  *  Every active entity type has an entry. */
 interface UPGPropertyMap {
-    /** The product being built — root node of every product graph */
+    /** The product being built: root node of every product graph */
     product: ProductProperties;
     /** A measurable outcome the product is working toward */
     outcome: OutcomeProperties;
@@ -17000,13 +17062,13 @@ interface UPGPropertyMap {
     objective: ObjectiveProperties;
     /** A quantifiable key result used to measure an objective */
     key_result: KeyResultProperties;
-    /** A tracked metric — present when a quantitative measure is defined */
+    /** A tracked metric, present when a quantitative measure is defined */
     metric: MetricProperties;
     /** A point-in-time review of a metric's quality and fitness for purpose. */
     metric_quality_assessment: MetricQualityAssessmentProperties;
     /** The long-horizon vision statement for the product */
     vision: VisionProperties;
-    /** The mission statement — who is served and what core value is delivered */
+    /** The mission statement: who is served and what core value is delivered */
     mission: MissionProperties;
     /** A strategic theme grouping related initiatives under a common direction */
     strategic_theme: StrategicThemeProperties;
@@ -17018,20 +17080,20 @@ interface UPGPropertyMap {
     value_stream: ValueStreamProperties;
     /** A durable strategic pillar spanning multi-year horizons */
     strategic_pillar: StrategicPillarProperties;
-    /** An assumption that underpins strategy or design — present when validation is being tracked */
+    /** An assumption that underpins strategy or design, present when validation is being tracked */
     assumption: AssumptionProperties;
-    /** A decision record — strategic, product, engineering, or design */
+    /** A decision record (strategic, product, engineering, or design) */
     decision: DecisionProperties;
-    /** A named limitation or boundary — resource, technical, regulatory,
-     *  temporal, or compliance — that bounds product creation. Edge-defined. */
+    /** A named limitation or boundary (resource, technical, regulatory,
+     *  temporal, or compliance) that bounds product creation. Edge-defined. */
     constraint: ConstraintProperties;
     /** A user persona representing a segment of people the product serves */
     persona: PersonaProperties;
-    /** A job-to-be-done — the progress a user is trying to make */
+    /** A job-to-be-done: the progress a user is trying to make */
     job: JobProperties;
     /** A user need derived from research or synthesis */
     need: NeedProperties;
-    /** A desired outcome — the specific result a user wants from a job step */
+    /** A desired outcome: the specific result a user wants from a job step */
     desired_outcome: DesiredOutcomeProperties;
     /** A discrete step within a job-to-be-done */
     job_step: JobStepProperties;
@@ -17039,21 +17101,21 @@ interface UPGPropertyMap {
     switching_cost: SwitchingCostProperties;
     /** A product opportunity identified from user needs or market gaps */
     opportunity: OpportunityProperties;
-    /** A proposed solution to an opportunity — present before commitment */
+    /** A proposed solution to an opportunity, present before commitment */
     solution: SolutionProperties;
     /** A feasibility study assessing viability of a solution */
     feasibility_study: FeasibilityStudyProperties;
     /** A design sprint run to explore and test a solution space */
     design_sprint: DesignSprintProperties;
-    /** A testable belief — the canonical validation design artefact. */
+    /** A testable belief: the canonical validation design artefact. */
     hypothesis: HypothesisProperties;
-    /** @deprecated since v0.4.0 — use `evidence` + `hypothesis_has_evidence` edge instead. */
+    /** @deprecated since v0.4.0. Use `evidence` + `hypothesis_has_evidence` edge instead. */
     hypothesis_evidence: HypothesisEvidenceProperties;
     /** A general-purpose experiment entity (canonical-stable). Use `experiment_plan` + `experiment_run` for fine-grained plan/run separation. */
     experiment: ExperimentProperties;
-    /** Planning intent for a structured test of a hypothesis (UCS pattern P4 — work-unit). Pairs with `experiment_run`. */
+    /** Planning intent for a structured test of a hypothesis (UCS pattern P4, work-unit). Pairs with `experiment_run`. */
     experiment_plan: ExperimentPlanProperties;
-    /** Execution evidence for a structured test of a hypothesis (UCS pattern P6 — event-occurrence). Pairs with `experiment_plan`. */
+    /** Execution evidence for a structured test of a hypothesis (UCS pattern P6, event-occurrence). Pairs with `experiment_plan`. */
     experiment_run: ExperimentRunProperties;
     /** A learning captured from an experiment or research activity */
     learning: LearningProperties;
@@ -17063,7 +17125,7 @@ interface UPGPropertyMap {
     evidence: EvidenceProperties;
     /** A research plan outlining goals, methods, and participant criteria */
     research_plan: ResearchPlanProperties;
-    /** A competitor in the market — present when competitive tracking is active */
+    /** A competitor in the market, present when competitive tracking is active */
     competitor: CompetitorProperties;
     /** A specific feature offered by a competitor */
     competitor_feature: CompetitorFeatureProperties;
@@ -17075,13 +17137,13 @@ interface UPGPropertyMap {
     competitive_analysis: CompetitiveAnalysisProperties;
     /** A dimension along which subjects are classified */
     classification_axis: ClassificationAxisProperties;
-    /** A value on a classification axis — one position in a taxonomy */
+    /** A value on a classification axis: one position in a taxonomy */
     classification_value: ClassificationValueProperties;
-    /** A formal user research study — interview series, survey, usability test */
+    /** A formal user research study (interview series, survey, usability test) */
     research_study: ResearchStudyProperties;
-    /** An insight synthesised from research — a meaningful pattern or finding */
+    /** An insight synthesised from research: a meaningful pattern or finding */
     insight: InsightProperties;
-    /** A research participant — present when participant tracking is needed */
+    /** A research participant, present when participant tracking is needed */
     participant: ParticipantProperties;
     /** A raw observation recorded during research */
     observation: ObservationProperties;
@@ -17113,7 +17175,7 @@ interface UPGPropertyMap {
     wireframe: WireframeProperties;
     /** A user flow showing task-level paths through the product */
     user_flow: UserFlowProperties;
-    /** A screen in the product UI — present when screen mapping is tracked */
+    /** A screen in the product UI, present when screen mapping is tracked */
     screen: ScreenProperties;
     /** A specific UI state of a screen (empty, loading, error, etc.) */
     screen_state: ScreenStateProperties;
@@ -17123,33 +17185,33 @@ interface UPGPropertyMap {
     interaction_spec: InteractionSpecProperties;
     /** A reusable UI component in the design system */
     design_component: DesignComponentProperties;
-    /** A design token — a named value for colour, spacing, typography, etc. */
+    /** A design token: a named value for colour, spacing, typography, etc. */
     design_token: DesignTokenProperties;
-    /** The design system itself — governance, tooling, and coverage metadata */
+    /** The design system itself, covering governance, tooling, and coverage metadata */
     design_system: DesignSystemProperties;
     /** A recurring interaction or layout pattern documented in the design system */
     design_pattern: DesignPatternProperties;
     /** A design guideline stating how and when to apply a pattern or token */
     design_guideline: DesignGuidelineProperties;
-    /** The brand identity — values, personality, and positioning */
+    /** The brand identity, covering values, personality, and positioning */
     brand_identity: BrandIdentityProperties;
     /** A specific brand colour with usage guidance */
     brand_colour: BrandColourProperties;
-    /** A brand typography pairing — typeface, scale, and usage rules */
+    /** A brand typography pairing (typeface, scale, and usage rules) */
     brand_typography: BrandTypographyProperties;
-    /** The brand voice — tone, register, and writing principles */
+    /** The brand voice: tone, register, and writing principles */
     brand_voice: BrandVoiceProperties;
-    /** A brand logo variant — full, icon, wordmark, etc. */
+    /** A brand logo variant (full, icon, wordmark, etc.) */
     brand_logo: BrandLogoProperties;
-    /** Brand imagery guidelines — photography and illustration style */
+    /** Brand imagery guidelines covering photography and illustration style */
     brand_imagery: BrandImageryProperties;
     /** A feature area grouping related features under a product section */
     feature_area: FeatureAreaProperties;
-    /** A product feature — a discrete unit of user-facing functionality */
+    /** A product feature: a discrete unit of user-facing functionality */
     feature: FeatureProperties;
     /** An epic grouping related user stories under a deliverable theme */
     epic: EpicProperties;
-    /** The "As X, I want Y so Z" templated promise — a user story (UCS pattern P5 — templated-statement). Implemented by `task` via `task_implements_user_story`. */
+    /** The "As X, I want Y so Z" templated promise: a user story (UCS pattern P5, templated-statement). Implemented by `task` via `task_implements_user_story`. */
     user_story: UserStoryProperties;
     /**
      * @deprecated since v0.4.0. story_task collapsed into task.
@@ -17158,15 +17220,15 @@ interface UPGPropertyMap {
     story_task: StoryTaskProperties;
     /** An acceptance criterion defining when a story or feature is complete */
     acceptance_criterion: AcceptanceCriterionProperties;
-    /** A product release — present when versioned delivery is tracked */
+    /** A product release, present when versioned delivery is tracked */
     release: ReleaseProperties;
     /** A discrete task assigned to a person or team */
     task: TaskProperties;
-    /** A bug report — present when a defect is being tracked */
+    /** A bug report, present when a defect is being tracked */
     bug: BugProperties;
     /** A product roadmap grouping features and themes over a planning horizon */
     roadmap: RoadmapProperties;
-    /** A single item on a roadmap — a feature, epic, or theme with timing */
+    /** A single item on a roadmap: a feature, epic, or theme with timing */
     roadmap_item: RoadmapItemProperties;
     /** A thematic grouping used to cluster work on the roadmap */
     theme: ThemeProperties;
@@ -17180,31 +17242,31 @@ interface UPGPropertyMap {
     domain_event: DomainEventProperties;
     /** An API contract specifying the interface between services or clients */
     api_contract: ApiContractProperties;
-    /** A technical debt item — present when debt is being tracked for remediation */
+    /** A technical debt item, present when debt is being tracked for remediation */
     technical_debt_item: TechnicalDebtItemProperties;
     /** A feature flag controlling runtime behaviour without deployment */
     feature_flag: FeatureFlagProperties;
-    /** A deployment record — present when a specific release was deployed */
+    /** A deployment record, present when a specific release was deployed */
     deployment: DeploymentProperties;
-    /** A DDD aggregate — a cluster of domain objects with a consistency boundary */
+    /** A DDD aggregate: a cluster of domain objects with a consistency boundary */
     aggregate: AggregateProperties;
-    /** A domain entity — an object with identity that changes over time */
+    /** A domain entity: an object with identity that changes over time */
     domain_entity: DomainEntityProperties;
-    /** A value object — an immutable domain concept identified by its attributes */
+    /** A value object: an immutable domain concept identified by its attributes */
     value_object: ValueObjectProperties;
     /** A command representing an intent to change system state */
     command: CommandProperties;
-    /** A read model — a query-optimised projection of domain state */
+    /** A read model: a query-optimised projection of domain state */
     read_model: ReadModelProperties;
-    /** A specific API endpoint — present when endpoint-level tracking is needed */
+    /** A specific API endpoint, present when endpoint-level tracking is needed */
     api_endpoint: ApiEndpointProperties;
-    /** A database schema — table structure, constraints, and migration status */
+    /** A database schema (table structure, constraints, and migration status) */
     database_schema: DatabaseSchemaProperties;
     /** A message queue topic or channel */
     queue_topic: QueueTopicProperties;
     /** A build artifact produced by the CI pipeline */
     build_artifact: BuildArtifactProperties;
-    /** A code repository — present when repo-level tracking is needed */
+    /** A code repository, present when repo-level tracking is needed */
     code_repository: CodeRepositoryProperties;
     /** A library dependency tracked for version and licence compliance */
     library_dependency: LibraryDependencyProperties;
@@ -17218,7 +17280,7 @@ interface UPGPropertyMap {
     investigation: InvestigationProperties;
     /** The root cause identified during an incident investigation */
     root_cause: RootCauseProperties;
-    /** A symptom observed during an incident — present before root cause is known */
+    /** A symptom observed during an incident, present before root cause is known */
     symptom: SymptomProperties;
     /** A fix applied to resolve a bug or incident */
     fix: FixProperties;
@@ -17234,47 +17296,47 @@ interface UPGPropertyMap {
     cohort: CohortProperties;
     /** A behavioural segment defined by in-product actions */
     behavioral_segment: BehavioralSegmentProperties;
-    /** A growth loop — a self-reinforcing cycle that compounds user or revenue growth */
+    /** A growth loop: a self-reinforcing cycle that compounds user or revenue growth */
     growth_loop: GrowthLoopProperties;
     /** A variant in an A/B or multivariate experiment */
     variant: VariantProperties;
     /** An attribution model defining how credit is assigned to acquisition channels */
     attribution_model: AttributionModelProperties;
-    /** The overall business model — present when BMC-level structure is tracked */
+    /** The overall business model, present when BMC-level structure is tracked */
     business_model: BusinessModelProperties;
-    /** A value proposition — the core promise made to a customer segment */
+    /** A value proposition: the core promise made to a customer segment */
     value_proposition: ValuePropositionProperties;
-    /** A revenue stream — a mechanism through which the product earns money */
+    /** A revenue stream: a mechanism through which the product earns money */
     revenue_stream: RevenueStreamProperties;
     /** A pricing tier defining what a customer gets at a given price point */
     pricing_tier: PricingTierProperties;
-    /** The cost structure — fixed and variable costs underpinning the business model */
+    /** The cost structure (fixed and variable costs underpinning the business model) */
     cost_structure: CostStructureProperties;
-    /** Unit economics — per-unit revenue, cost, and margin metrics */
+    /** Unit economics: per-unit revenue, cost, and margin metrics */
     unit_economics: UnitEconomicsProperties;
-    /** A partnership — a strategic relationship with an external organisation */
+    /** A partnership: a strategic relationship with an external organisation */
     partnership: PartnershipProperties;
     /** A key resource required to deliver value (people, IP, infrastructure) */
     key_resource: KeyResourceProperties;
     /** A key activity the business must perform to deliver its value proposition */
     key_activity: KeyActivityProperties;
-    /** A customer relationship type — how the business interacts with a segment */
+    /** A customer relationship type: how the business interacts with a segment */
     customer_relationship: CustomerRelationshipProperties;
     /** A distribution channel through which value reaches the customer */
     distribution_channel: DistributionChannelProperties;
-    /** The GTM strategy — present when go-to-market planning is formalised */
+    /** The GTM strategy, present when go-to-market planning is formalised */
     gtm_strategy: GtmStrategyProperties;
     /** An ideal customer profile defining the best-fit buyer */
     ideal_customer_profile: IdealCustomerProfileProperties;
     /** A positioning statement defining where the product sits in the market */
     positioning: PositioningProperties;
-    /** A messaging framework — headlines, value pillars, and proof points */
+    /** A messaging framework (headlines, value pillars, and proof points) */
     messaging: MessagingProperties;
-    /** A product launch — present when a coordinated launch is being planned */
+    /** A product launch, present when a coordinated launch is being planned */
     launch: LaunchProperties;
     /** A content strategy defining themes, formats, and channels */
     content_strategy: ContentStrategyProperties;
-    /** A sales motion — the repeatable process used to close deals */
+    /** A sales motion: the repeatable process used to close deals */
     sales_motion: SalesMotionProperties;
     /** A competitive battle card for use by the sales team */
     competitive_battle_card: CompetitiveBattleCardProperties;
@@ -17288,17 +17350,17 @@ interface UPGPropertyMap {
     rebuttal: RebuttalProperties;
     /** A proof point substantiating a claim in messaging or sales */
     proof_point: ProofPointProperties;
-    /** A team — a group of people working on a shared scope */
+    /** A team: a group of people working on a shared scope */
     team: TeamProperties;
-    /** A role — a function or responsibility within the team or organisation */
+    /** A role: a function or responsibility within the team or organisation */
     role: RoleProperties;
     /** A stakeholder with interest in or influence over the product */
     stakeholder: StakeholderProperties;
-    /** A named, accountable individual — distinct from `stakeholder` (interested party) and `role` (responsibility slot) */
+    /** A named, accountable individual, distinct from `stakeholder` (interested party) and `role` (responsibility slot) */
     person: PersonProperties;
     /** An OKR set at the team level */
     team_okr: TeamOkrProperties;
-    /** A retrospective — present when team reflections are being tracked */
+    /** A retrospective, present when team reflections are being tracked */
     retrospective: RetrospectiveProperties;
     /** A cross-team dependency that may block delivery */
     dependency: DependencyProperties;
@@ -17314,13 +17376,13 @@ interface UPGPropertyMap {
     data_source: DataSourceProperties;
     /** An event schema defining the structure of a tracked event */
     event_schema: EventSchemaProperties;
-    /** A dashboard — present when a reporting surface is being tracked */
+    /** A dashboard, present when a reporting surface is being tracked */
     dashboard: DashboardProperties;
-    /** A data model — entity relationships and schema structure */
+    /** A data model covering entity relationships and schema structure */
     data_model: DataModelProperties;
     /** A data quality rule defining expectations on a dataset or field */
     data_quality_rule: DataQualityRuleProperties;
-    /** A data product — a curated, discoverable dataset made available to consumers */
+    /** A data product: a curated, discoverable dataset made available to consumers */
     data_product: DataProductProperties;
     /** A data pipeline moving or transforming data between systems */
     data_pipeline: DataPipelineProperties;
@@ -17330,13 +17392,13 @@ interface UPGPropertyMap {
     glossary_term: GlossaryTermProperties;
     /** A data domain grouping related data assets under a common owner */
     data_domain: DataDomainProperties;
-    /** A report — a scheduled or on-demand analytical output */
+    /** A report: a scheduled or on-demand analytical output */
     report: ReportProperties;
-    /** A content piece — blog post, video, podcast, whitepaper, or case study */
+    /** A content piece (blog post, video, podcast, whitepaper, or case study) */
     content_piece: ContentPieceProperties;
     /** A knowledge base article for customers, developers, or internal teams */
     knowledge_base_article: KnowledgeBaseArticleProperties;
-    /** A brand asset — logo, illustration, photo, or video */
+    /** A brand asset (logo, illustration, photo, or video) */
     brand_asset: BrandAssetProperties;
     /** A prompt template used for AI-assisted workflows */
     prompt_template: PromptTemplateProperties;
@@ -17346,21 +17408,21 @@ interface UPGPropertyMap {
     content_theme: ContentThemeProperties;
     /** A documentation template defining structure for a class of documents */
     documentation_template: DocumentationTemplateProperties;
-    /** A document entity — provenance container linking to a source file */
+    /** A document entity: provenance container linking to a source file */
     document: DocumentProperties;
-    /** A legal entity — company, subsidiary, or contracting party */
+    /** A legal entity (company, subsidiary, or contracting party) */
     legal_entity: LegalEntityProperties;
-    /** An intellectual property asset — patent, trademark, copyright, or trade secret */
+    /** An intellectual property asset (patent, trademark, copyright, or trade secret) */
     ip_asset: IpAssetProperties;
     /** A contract between the company and an external party */
     contract: ContractProperties;
-    /** A specific clause within a contract — present when clause-level tracking is needed */
+    /** A specific clause within a contract, present when clause-level tracking is needed */
     contract_clause: ContractClauseProperties;
-    /** A privacy policy document — present when policy tracking is active */
+    /** A privacy policy document, present when policy tracking is active */
     privacy_policy: PrivacyPolicyProperties;
     /** A compliance requirement from a regulation, standard, or customer contract */
     compliance_requirement: ComplianceRequirementProperties;
-    /** A risk — a potential event with negative impact on the product or business */
+    /** A risk: a potential event with negative impact on the product or business */
     risk: RiskProperties;
     /** A data contract defining agreed schema and SLAs between producer and consumer */
     data_contract: DataContractProperties;
@@ -17368,15 +17430,15 @@ interface UPGPropertyMap {
     audit_log_policy: AuditLogPolicyProperties;
     /** A compliance framework being adhered to (SOC 2, ISO 27001, GDPR, etc.) */
     compliance_framework: ComplianceFrameworkProperties;
-    /** A security audit — present when a formal review has been conducted */
+    /** A security audit, present when a formal review has been conducted */
     security_audit: SecurityAuditProperties;
-    /** A service level indicator — a specific measurement of service behaviour */
+    /** A service level indicator: a specific measurement of service behaviour */
     service_level_indicator: ServiceLevelIndicatorProperties;
-    /** A service level objective — a target range for an SLI */
+    /** A service level objective: a target range for an SLI */
     service_level_objective: ServiceLevelObjectiveProperties;
-    /** An error budget derived from an SLO — present when reliability is tracked */
+    /** An error budget derived from an SLO, present when reliability is tracked */
     error_budget: ErrorBudgetProperties;
-    /** An incident — a production event requiring response */
+    /** An incident: a production event requiring response */
     incident: IncidentProperties;
     /** A postmortem written after an incident is resolved */
     postmortem: PostmortemProperties;
@@ -17386,25 +17448,25 @@ interface UPGPropertyMap {
     monitor: MonitorProperties;
     /** An alert rule defining when a monitor fires a notification */
     alert_rule: AlertRuleProperties;
-    /** A CI pipeline configuration — build, test, and deploy stages */
+    /** A CI pipeline configuration (build, test, and deploy stages) */
     ci_pipeline: CiPipelineProperties;
     /** A release strategy defining how changes are deployed (blue-green, canary, etc.) */
     release_strategy: ReleaseStrategyProperties;
     /** An on-call rotation assigning responders to incidents by schedule */
     on_call_rotation: OnCallRotationProperties;
-    /** An infrastructure component — server, container, network resource, etc. */
+    /** An infrastructure component (server, container, network resource, etc.) */
     infrastructure_component: InfrastructureComponentProperties;
     /** A threat model documenting attack surfaces and adversary assumptions */
     threat_model: ThreatModelProperties;
     /** A specific threat identified within a threat model */
     threat: ThreatProperties;
-    /** A vulnerability — a known weakness that could be exploited */
+    /** A vulnerability: a known weakness that could be exploited */
     vulnerability: VulnerabilityProperties;
     /** A security control mitigating one or more threats */
     security_control: SecurityControlProperties;
     /** A security policy governing how the system or team handles a security domain */
     security_policy: SecurityPolicyProperties;
-    /** A penetration test — present when external security testing is tracked */
+    /** A penetration test, present when external security testing is tracked */
     penetration_test: PenetrationTestProperties;
     /** A security review of a feature, service, or architecture change */
     security_review: SecurityReviewProperties;
@@ -17416,7 +17478,7 @@ interface UPGPropertyMap {
     a11y_standard: A11yStandardProperties;
     /** A specific accessibility guideline derived from a standard */
     a11y_guideline: A11yGuidelineProperties;
-    /** An accessibility audit — present when a formal review has been run */
+    /** An accessibility audit, present when a formal review has been run */
     a11y_audit: A11yAuditProperties;
     /** An accessibility issue found during audit or user research */
     a11y_issue: A11yIssueProperties;
@@ -17424,9 +17486,9 @@ interface UPGPropertyMap {
     a11y_annotation: A11yAnnotationProperties;
     /** A test suite grouping related test cases */
     test_suite: TestSuiteProperties;
-    /** A test case — a single scenario with expected inputs and outputs */
+    /** A test case: a single scenario with expected inputs and outputs */
     test_case: TestCaseProperties;
-    /** A QA session — present when exploratory testing is being tracked */
+    /** A QA session, present when exploratory testing is being tracked */
     qa_session: QaSessionProperties;
     /** A regression test ensuring previously fixed behaviour does not break */
     regression_test: RegressionTestProperties;
@@ -17434,33 +17496,33 @@ interface UPGPropertyMap {
     test_coverage_report: TestCoverageReportProperties;
     /** A test environment configuration used to run a test suite */
     test_environment: TestEnvironmentProperties;
-    /** The result of a test run — pass, fail, or flaky */
+    /** The result of a test run (pass, fail, or flaky) */
     test_result: TestResultProperties;
-    /** A feedback programme — present when structured customer feedback is collected */
+    /** A feedback programme, present when structured customer feedback is collected */
     feedback_program: FeedbackProgramProperties;
     /** A feature request submitted by a customer or prospect */
     feature_request: FeatureRequestProperties;
-    /** A vote on a feature request — present when voting is tracked */
+    /** A vote on a feature request, present when voting is tracked */
     feedback_vote: FeedbackVoteProperties;
-    /** An NPS campaign — present when Net Promoter Score is being measured */
+    /** An NPS campaign, present when Net Promoter Score is being measured */
     nps_campaign: NpsCampaignProperties;
-    /** A user advisory board — a formal group of customers shaping product direction */
+    /** A user advisory board: a formal group of customers shaping product direction */
     user_advisory_board: UserAdvisoryBoardProperties;
-    /** A beta programme — present when pre-release access is being managed */
+    /** A beta programme, present when pre-release access is being managed */
     beta_program: BetaProgramProperties;
     /** A feedback theme clustering related requests or complaints */
     feedback_theme: FeedbackThemeProperties;
-    /** The pricing strategy — present when pricing approach is formalised */
+    /** The pricing strategy, present when pricing approach is formalised */
     pricing_strategy: PricingStrategyProperties;
     /** A discount strategy defining when and how discounts are applied */
     discount_strategy: DiscountStrategyProperties;
-    /** A trial configuration — present when a free trial or pilot is offered */
+    /** A trial configuration, present when a free trial or pilot is offered */
     trial_config: TrialConfigProperties;
-    /** A paywall — the gate between free and paid access */
+    /** A paywall: the gate between free and paid access */
     paywall: PaywallProperties;
     /** An AI model used by or integrated into the product */
     ai_model: AiModelProperties;
-    /** A versioned prompt — present when prompt engineering is tracked */
+    /** A versioned prompt, present when prompt engineering is tracked */
     prompt_version: PromptVersionProperties;
     /** An evaluation benchmark defining pass/fail criteria for a model */
     eval_benchmark: EvalBenchmarkProperties;
@@ -17468,9 +17530,9 @@ interface UPGPropertyMap {
     eval_run: EvalRunProperties;
     /** An AI cost tracker monitoring token usage and spend */
     ai_cost_tracker: AiCostTrackerProperties;
-    /** A hallucination report — present when model output accuracy is audited */
+    /** A hallucination report, present when model output accuracy is audited */
     hallucination_report: HallucinationReportProperties;
-    /** An AI guardrail — a safety or quality constraint applied to model output */
+    /** An AI guardrail: a safety or quality constraint applied to model output */
     ai_guardrail: AiGuardrailProperties;
     /** A model comparison evaluating two or more models on the same benchmark */
     model_comparison: ModelComparisonProperties;
@@ -17482,17 +17544,17 @@ interface UPGPropertyMap {
     ai_trace: AiTraceProperties;
     /** A workflow template defining a reusable multi-step process */
     workflow_template: WorkflowTemplateProperties;
-    /** A workflow run — a live execution of a workflow template */
+    /** A workflow run: a live execution of a workflow template */
     workflow_run: WorkflowRunProperties;
-    /** An agent definition — the configuration and capabilities of an AI agent */
+    /** An agent definition: the configuration and capabilities of an AI agent */
     agent_definition: AgentDefinitionProperties;
-    /** An agent session — a single interaction run by an agent */
+    /** An agent session: a single interaction run by an agent */
     agent_session: AgentSessionProperties;
     /** A review gate requiring human approval before a workflow continues */
     review_gate: ReviewGateProperties;
-    /** An approval record — the decision made at a review gate */
+    /** An approval record: the decision made at a review gate */
     approval_record: ApprovalRecordProperties;
-    /** A skill available to an agent — a named, callable capability */
+    /** A skill available to an agent: a named, callable capability */
     agent_skill: AgentSkillProperties;
     /** A hook executed before or after a workflow step */
     agent_hook: AgentHookProperties;
@@ -17500,67 +17562,67 @@ interface UPGPropertyMap {
     workflow_artifact: WorkflowArtifactProperties;
     /** A task assigned to an agent within a workflow run */
     agent_task: AgentTaskProperties;
-    /** An organisation — the company or entity that owns a portfolio of products */
+    /** An organisation: the company or entity that owns a portfolio of products */
     organization: OrganizationProperties;
     /** A portfolio grouping multiple products under a common strategy */
     portfolio: PortfolioProperties;
-    /** A product area — a named section of the product with its own ownership */
+    /** A product area: a named section of the product with its own ownership */
     product_area: ProductAreaProperties;
-    /** A workspace — the collaboration boundary for a team or organisation */
+    /** A workspace: the collaboration boundary for a team or organisation */
     workspace: WorkspaceProperties;
-    /** An account — a company or organisation in the CRM */
+    /** An account: a company or organisation in the CRM */
     account: AccountProperties;
-    /** A contact — an individual person at an account */
+    /** A contact: an individual person at an account */
     contact: ContactProperties;
-    /** A lead — an unqualified prospect entering the sales funnel */
+    /** A lead: an unqualified prospect entering the sales funnel */
     lead: LeadProperties;
-    /** A deal — a qualified sales opportunity being pursued */
+    /** A deal: a qualified sales opportunity being pursued */
     deal: DealProperties;
-    /** The sales pipeline — present when pipeline-level metadata is tracked */
+    /** The sales pipeline, present when pipeline-level metadata is tracked */
     pipeline_sales: PipelineSalesProperties;
     /** A stage within the sales pipeline */
     pipeline_stage: PipelineStageProperties;
     /** A quote document sent to a prospect */
     quote_document: QuoteDocumentProperties;
-    /** A subscription — a recurring revenue relationship with a customer */
+    /** A subscription: a recurring revenue relationship with a customer */
     subscription: SubscriptionProperties;
     /** An invoice issued to a customer */
     invoice: InvoiceProperties;
-    /** A sales forecast — present when revenue prediction is tracked */
+    /** A sales forecast, present when revenue prediction is tracked */
     forecast: ForecastProperties;
     /** A programme grouping related projects under a strategic objective */
     program: ProgramProperties;
-    /** A project — a time-boxed initiative with a defined scope */
+    /** A project: a time-boxed initiative with a defined scope */
     project: ProjectProperties;
     /** A milestone marking a significant point in a project or release */
     milestone: MilestoneProperties;
     /** A risk register capturing identified risks and mitigations */
     risk_register: RiskRegisterProperties;
-    /** A change request — present when a formal change process is followed */
+    /** A change request, present when a formal change process is followed */
     change_request: ChangeRequestProperties;
-    /** A deliverable — a tangible output committed to a stakeholder */
+    /** A deliverable: a tangible output committed to a stakeholder */
     deliverable: DeliverableProperties;
     /** A resource allocation mapping team capacity to projects */
     resource_allocation: ResourceAllocationProperties;
     /** A status report summarising progress against plan */
     status_report: StatusReportProperties;
-    /** The marketing strategy — present when marketing is formalised at the programme level */
+    /** The marketing strategy, present when marketing is formalised at the programme level */
     marketing_strategy: MarketingStrategyProperties;
-    /** A marketing channel — a medium used to reach the target audience */
+    /** A marketing channel: a medium used to reach the target audience */
     marketing_channel: MarketingChannelProperties;
-    /** A marketing campaign plan — present when a campaign is being planned */
+    /** A marketing campaign plan, present when a campaign is being planned */
     marketing_campaign_plan: MarketingCampaignPlanProperties;
-    /** An email sequence — a series of automated emails sent to a segment */
+    /** An email sequence: a series of automated emails sent to a segment */
     email_sequence: EmailSequenceProperties;
-    /** A social post — present when social content is being planned or tracked */
+    /** A social post, present when social content is being planned or tracked */
     social_post: SocialPostProperties;
     /** An SEO keyword being targeted in content or paid search */
     seo_keyword: SeoKeywordProperties;
-    /** An ad creative — copy and visual used in a paid media placement */
+    /** An ad creative: copy and visual used in a paid media placement */
     ad_creative: AdCreativeProperties;
-    /** A press release — present when media outreach is being tracked */
+    /** A press release, present when media outreach is being tracked */
     press_release: PressReleaseProperties;
-    /** An event — physical or virtual — being planned or tracked */
+    /** An event (physical or virtual) being planned or tracked */
     event: EventProperties;
     /** A community initiative building engagement with users or prospects */
     community_initiative: CommunityInitiativeProperties;
@@ -17570,9 +17632,9 @@ interface UPGPropertyMap {
     customer_feedback: CustomerFeedbackProperties;
     /** A churn reason explaining why a customer cancelled */
     churn_reason: ChurnReasonProperties;
-    /** A customer health score — present when account health is tracked */
+    /** A customer health score, present when account health is tracked */
     customer_health_score: CustomerHealthScoreProperties;
-    /** A playbook — a documented response to a customer scenario */
+    /** A playbook: a documented response to a customer scenario */
     playbook: PlaybookProperties;
     /** A service level agreement defining commitments to a customer */
     service_level_agreement: ServiceLevelAgreementProperties;
@@ -17584,39 +17646,39 @@ interface UPGPropertyMap {
     success_milestone: SuccessMilestoneProperties;
     /** A service blueprint mapping frontstage and backstage activities */
     service_blueprint: ServiceBlueprintProperties;
-    /** A locale — a language and region combination supported by the product */
+    /** A locale: a language and region combination supported by the product */
     locale: LocaleProperties;
     /** A translation key mapping a string identifier to localised text */
     translation_key: TranslationKeyProperties;
-    /** A translation bundle — a collection of keys for a single locale */
+    /** A translation bundle: a collection of keys for a single locale */
     translation_bundle: TranslationBundleProperties;
     /** A locale configuration defining date, number, and currency formatting */
     locale_config: LocaleConfigProperties;
-    /** A cultural adaptation — a locale-specific change beyond string translation */
+    /** A cultural adaptation: a locale-specific change beyond string translation */
     cultural_adaptation: CulturalAdaptationProperties;
     /** A regional pricing configuration adjusting price for a locale */
     regional_pricing: RegionalPricingProperties;
-    /** An education programme — a structured curriculum for customer learning */
+    /** An education programme: a structured curriculum for customer learning */
     education_program: EducationProgramProperties;
     /** A tutorial walking a user through a feature or workflow */
     tutorial: TutorialProperties;
-    /** A walkthrough — an in-product guided tour */
+    /** A walkthrough: an in-product guided tour */
     walkthrough: WalkthroughProperties;
-    /** A webinar — a live or recorded educational session */
+    /** A webinar: a live or recorded educational session */
     webinar: WebinarProperties;
     /** A certification awarded upon completing a learning path */
     certification: CertificationProperties;
-    /** A help video — a short screencast explaining a feature */
+    /** A help video: a short screencast explaining a feature */
     help_video: HelpVideoProperties;
-    /** A learning path — a sequenced collection of tutorials, videos, and assessments */
+    /** A learning path: a sequenced collection of tutorials, videos, and assessments */
     learning_path: LearningPathProperties;
     /** A partner programme defining tiers, benefits, and requirements */
     partner_program: PartnerProgramProperties;
-    /** A partner tier within a programme — Bronze, Silver, Gold, etc. */
+    /** A partner tier within a programme (Bronze, Silver, Gold, etc.) */
     partner_tier: PartnerTierProperties;
-    /** The API ecosystem — developer community and integration surface */
+    /** The API ecosystem: developer community and integration surface */
     api_ecosystem: ApiEcosystemProperties;
-    /** A marketplace listing — present when the product is listed on a platform */
+    /** A marketplace listing, present when the product is listed on a platform */
     marketplace_listing: MarketplaceListingProperties;
     /** A developer portal providing documentation and sandbox access */
     developer_portal: DeveloperPortalProperties;
@@ -17625,16 +17687,16 @@ interface UPGPropertyMap {
     /** A partner revenue share arrangement defining commercial terms */
     partner_revenue_share: PartnerRevenueShareProperties;
 }
-/** A fully typed UPG node — `UPGBaseNode` narrowed to a specific entity type.
+/** A fully typed UPG node. `UPGBaseNode` narrowed to a specific entity type.
  *
  * `T` is an entity-type literal from `UPGPropertyMap`. When supplied, it
  * constrains `type` to that literal and narrows `properties` to the matching
- * `*Properties` interface. When omitted, `T` defaults to the full union — the
+ * `*Properties` interface. When omitted, `T` defaults to the full union: the
  * node accepts any entity type and `properties` widens to the union of all
  * domain property shapes.
  *
  * @example
- * // Narrowed by T — `type` is locked to 'feature' and `properties` to
+ * // Narrowed by T: `type` is locked to 'feature' and `properties` to
  * // FeatureProperties.
  * const featureNode: UPGNode<'feature'> = {
  *   id: 'feat-1',
@@ -17644,7 +17706,7 @@ interface UPGPropertyMap {
  * }
  *
  * @example
- * // A different instantiation of T — the generic lets a single helper
+ * // A different instantiation of T: the generic lets a single helper
  * // signature return the correctly typed node for any entity type.
  * const personaNode: UPGNode<'persona'> = {
  *   id: 'p-1',
@@ -17659,7 +17721,7 @@ type UPGNode<T extends keyof UPGPropertyMap = keyof UPGPropertyMap> = UPGBaseNod
 };
 
 /**
- * UPG Property Registry — Runtime schema for entity types
+ * UPG Property Registry: Runtime schema for entity types
  *
  * AUTO-GENERATED by scripts/generate-property-registry.ts
  * Do not edit manually. Run: npx tsx scripts/generate-property-registry.ts
@@ -17671,9 +17733,9 @@ interface PropertyDefinition {
     type: 'string' | 'number' | 'boolean' | 'string[]' | 'object';
     description?: string;
     enum?: string[];
-    /** For object-typed fields — nested property shapes. */
+    /** For object-typed fields: nested property shapes. */
     properties?: Record<string, PropertyDefinition>;
-    /** For object-typed fields — required keys within `properties`. */
+    /** For object-typed fields: required keys within `properties`. */
     required?: string[];
 }
 type PropertySchema = Record<string, PropertyDefinition>;
@@ -17689,7 +17751,7 @@ declare const UPG_PROPERTY_SCHEMA: Record<string, PropertySchema>;
 declare function getPropertySchema(entityType: string): PropertySchema | undefined;
 
 /**
- * UPG Labels — framework-vocabulary Rosetta Stone. Each entity type maps to a
+ * UPG Labels: framework-vocabulary Rosetta Stone. Each entity type maps to a
  * canonical label, alt labels, and framework-specific labels. Answers "what
  * does framework X call this concept?"
  *
@@ -17708,7 +17770,7 @@ interface UPGTypeLabel {
     designations?: Record<string, string>;
 }
 /**
- * The complete Rosetta Stone — one UPGTypeLabel for every active type.
+ * The complete Rosetta Stone: one UPGTypeLabel for every active type.
  *
  * Assembly logic:
  * 1. If a type has a PRIORITY_LABELS entry → use it (richest framework_labels)
@@ -17751,11 +17813,11 @@ declare function resolveLabel(entityType: string, frameworkId?: string, designat
  * aliases['problem']           // → 'need'       (Lean Canvas label → canonical)
  */
 declare function buildTypeAliases(): Record<string, string>;
-/** Pre-built alias map — import this instead of calling buildTypeAliases() repeatedly */
+/** Pre-built alias map. Import this instead of calling buildTypeAliases() repeatedly. */
 declare const UPG_TYPE_ALIASES: Record<string, string>;
 
 /**
- * UPG Intelligence Conditions — structured, machine-evaluable graph predicates.
+ * UPG Intelligence Conditions: structured, machine-evaluable graph predicates.
  *
  * Three check types: `EntityCheck` (count by criteria), `RelationshipCheck`
  * (edge existence/count), `BenchmarkCheck` (compare against stage benchmark).
@@ -17902,7 +17964,7 @@ interface StepBase {
     phase: string;
     /** Human-readable label for this step */
     name?: string;
-    /** Optional prompt shown to the user at this step. Structure only — no UI hints. */
+    /** Optional prompt shown to the user at this step. Structure only, no UI hints. */
     prompt_hint?: string;
     /** Machine-evaluable condition that must hold before advancing to the next step */
     transition_condition?: IntelligenceCondition;
@@ -17918,7 +17980,7 @@ interface DomainGuideStep extends StepBase {
 /** Step that applies a named framework. */
 interface FrameworkInvocationStep extends StepBase {
     kind: 'framework';
-    /** ID of the framework to apply — matches an entry in UPG_FRAMEWORKS */
+    /** ID of the framework to apply (matches an entry in UPG_FRAMEWORKS) */
     framework_id: string;
 }
 /** Step that creates entities of an explicit, fixed list of types. */
@@ -17930,7 +17992,7 @@ interface EntitySequenceStep extends StepBase {
 /** Step that chains into a nested playbook or technique. */
 interface SubSequenceStep extends StepBase {
     kind: 'sub_sequence';
-    /** ID of the nested sequence — `playbook:*` or `technique:*` */
+    /** ID of the nested sequence: `playbook:*` or `technique:*` */
     sub_sequence_id: string;
 }
 /**
@@ -18016,7 +18078,7 @@ type UPGRegionShape =
 /**
  * The graph role an entity plays *within* its super-domain.
  *
- * Purely structural — independent of any rendering concept.
+ * Purely structural, independent of any rendering concept.
  */
 type UPGRegionEntityRole = 'anchor' | 'root' | 'hub' | 'container' | 'leaf';
 /** A single entity's membership in a super-domain. */
@@ -18052,20 +18114,20 @@ interface UPGAnchorEntity {
     inbound_cross_edge_count: number;
 }
 /**
- * A super-domain region — a coherent rollup of 1–N atomic domains.
+ * A super-domain region: a coherent rollup of 1-N atomic domains.
  *
  * Topology only: regions describe what is connected to what, not how it
  * renders. Rendering concerns live in Entopo (`apps/entopo/src/regions/`).
  *
- * @see {@link UPG_REGIONS} — the canonical catalog
- * @see MENTAL-MODEL.md — regions as the static "place" primitive
+ * @see {@link UPG_REGIONS} for the canonical catalog
+ * @see MENTAL-MODEL.md for regions as the static "place" primitive
  */
 interface UPGRegion {
     /** Machine-readable region id (snake_case) */
     id: string;
     /** Human-readable name */
     label: string;
-    /** Numeric order — matches prose file prefix (01–10) */
+    /** Numeric order, matches prose file prefix (01-10) */
     order: number;
     /** Shape archetype */
     shape: UPGRegionShape;
@@ -18108,7 +18170,7 @@ interface UPGPlaybook {
     version: string;
     /** One-sentence description */
     description: string;
-    /** REQUIRED — the region this playbook anchors */
+    /** REQUIRED: the region this playbook anchors */
     region: UPGRegionId;
     /**
      * Marks the canonical playbook for this region. Exactly one canonical per
@@ -18116,7 +18178,7 @@ interface UPGPlaybook {
      */
     is_canonical?: boolean;
     /**
-     * Optional — the framework this playbook is anchored on. References
+     * Optional: the framework this playbook is anchored on. References
      * `UPGFramework.id`. Specialised playbooks are typically framework-anchored;
      * the canonical playbook usually is not.
      */
@@ -18127,7 +18189,7 @@ interface UPGPlaybook {
      */
     target_anchor_entity?: string;
     /**
-     * Ordered creation sequence — typically one `DomainGuideStep` per atomic
+     * Ordered creation sequence, typically one `DomainGuideStep` per atomic
      * domain composed by the region, OR a framework-driven sequence when
      * `framework_id` is set.
      */
@@ -18142,15 +18204,15 @@ interface PlaybookBinding {
     surface: SurfaceId;
     /** Identifier the runtime maps to a component or handler */
     renderer: string;
-    /** Per-step renderer overrides — keyed by `Step.order` */
+    /** Per-step renderer overrides, keyed by `Step.order` */
     step_renderers?: Record<number, string>;
     /** Surface-specific step kinds the runtime handles beyond the canonical ones */
     custom_step_kinds?: readonly string[];
-    /** Lifecycle hook id — runtime-resolved, fires when a run starts */
+    /** Lifecycle hook id: runtime-resolved, fires when a run starts */
     on_start?: string;
-    /** Lifecycle hook id — runtime-resolved, fires after each step */
+    /** Lifecycle hook id: runtime-resolved, fires after each step */
     on_step_complete?: string;
-    /** Lifecycle hook id — runtime-resolved, fires when a run completes */
+    /** Lifecycle hook id: runtime-resolved, fires when a run completes */
     on_run_complete?: string;
 }
 /**
@@ -18205,7 +18267,7 @@ interface PlaybookRuntime {
 }
 
 /**
- * UPG Lenses — role-specific projections combining vocabulary, visibility,
+ * UPG Lenses: role-specific projections combining vocabulary, visibility,
  * workflow, and intelligence. Applied on read.
  * https://unifiedproductgraph.org/spec | MIT
  */
@@ -18215,24 +18277,24 @@ interface PlaybookRuntime {
  * layer. Surfaces a message when a trigger condition evaluates to `true`
  * over the current product graph.
  *
- * Runtimes evaluate `structured_condition` — the machine-readable form.
+ * Runtimes evaluate `structured_condition`, the machine-readable form.
  * `condition` is a human-readable shadow kept for documentation, prompt
  * engineering, debug output, and grep-ability. The two should describe
  * the same intent; when they diverge (rare), `structured_condition` is
  * the source of truth.
  *
  * @example
- * // A simple "missing thing" nudge — fires when the product has no outcomes.
+ * // A simple "missing thing" nudge that fires when the product has no outcomes.
  * const noOutcomes: UPGLensIntelligencePrompt = {
  *   condition: 'outcomes.length === 0',
  *   structured_condition: {
  *     check: { type: 'entity_count', entity_type: 'outcome', comparison: 'zero' },
  *   },
- *   message: 'No outcomes defined yet. Start with what success looks like — what measurable result should this product drive?',
+ *   message: 'No outcomes defined yet. Start with what success looks like: what measurable result should this product drive?',
  * }
  *
  * @example
- * // A compound nudge — features exist but no hypotheses validate them.
+ * // A compound nudge: features exist but no hypotheses validate them.
  * const featuresWithoutHypotheses: UPGLensIntelligencePrompt = {
  *   condition: 'features.length > 0 && hypotheses.length === 0',
  *   structured_condition: {
@@ -18247,12 +18309,12 @@ interface PlaybookRuntime {
  */
 interface UPGLensIntelligencePrompt {
     /**
-     * Human-readable shadow of `structured_condition`. Kept as documentary —
+     * Human-readable shadow of `structured_condition`. Kept as documentary reference,
      * useful for prompt engineering, debug output, and search. Not evaluated
      * at runtime; if the two ever diverge, `structured_condition` wins.
      */
     condition: string;
-    /** Machine-evaluable condition — when to surface this prompt. */
+    /** Machine-evaluable condition: when to surface this prompt. */
     structured_condition: IntelligenceCondition;
     /** The message to show, in the lens's voice */
     message: string;
@@ -18264,7 +18326,7 @@ interface UPGLensIntelligencePrompt {
  * A lens combines four orthogonal layers: vocabulary (which labels to
  * use), visibility (which domains to show), workflow (which guided
  * sequence to follow), and intelligence (which nudges to surface). The
- * `.upg` file format is lens-unaware — lenses apply on read only.
+ * `.upg` file format is lens-unaware; lenses apply on read only.
  *
  * @example
  * const productLens: UPGLens = {
@@ -18313,7 +18375,7 @@ interface UPGLens {
      * mental model. Structure lives in the playbook registry; the lens owns
      * only presentation (labels, visibility, intelligence).
      *
-     * Lenses without a 1:1 region playbook (e.g. `product`, `full` — both
+     * Lenses without a 1:1 region playbook (e.g. `product`, `full`, both
      * cross-region) leave this field unset. Resolved via `getLensPlaybook`.
      *
      * Renamed from `workflow_id` (workflows → playbooks + techniques).
@@ -18392,13 +18454,13 @@ declare function getLensIds(): string[];
  * @example
  * const lens = getLens('design')!
  * const playbook = getLensPlaybook(lens)
- * // playbook?.id matches lens.playbook_id — the bootstrap path for the
+ * // playbook?.id matches lens.playbook_id, the bootstrap path for the
  * // experience_design_brand region.
  */
 declare function getLensPlaybook(lens: UPGLens): UPGPlaybook | undefined;
 
 /**
- * UPG Domain Rings — 7 concentric groupings of the 36 UPG domains.
+ * UPG Domain Rings: 7 concentric groupings of the 36 UPG domains.
  *
  * Defines the ring assignment for every domain and the canonical ring metadata.
  *
@@ -18442,7 +18504,7 @@ declare function getRingForDomain(domainId: string): UPGDomainRing | undefined;
 declare function getDomainsInRing(ringId: string): string[];
 
 /**
- * UPG Domain Usage Guides — operational knowledge for MCP agents.
+ * UPG Domain Usage Guides: operational knowledge for MCP agents.
  *
  * Each guide gives a domain's anchor entity, creation sequence, named
  * patterns (entity + edge chains), required cross-domain bridges, and
@@ -18450,7 +18512,7 @@ declare function getDomainsInRing(ringId: string): string[];
  */
 
 interface UPGDomainPattern {
-    /** Human-readable pattern name — no jargon, spell out acronyms */
+    /** Human-readable pattern name (no jargon, spell out acronyms) */
     name: string;
     /** What this pattern accomplishes */
     description: string;
@@ -18469,16 +18531,16 @@ interface UPGDomainBridge {
 }
 /**
  * A common mistake agents make in a domain. Structured so MCP
- * consumers can proactively surface violations — "you created a feature
- * without a persona, that's an anti-pattern" — instead of only rendering
+ * consumers can proactively surface violations (e.g. "you created a feature
+ * without a persona, that's an anti-pattern") instead of only rendering
  * prose. Migrated from `anti_patterns: string[]`; existing copy lives in
  * `description`, and `name` / `affected_entity` / `remediation` are
  * optional for backward migration but preferred for new entries.
  */
 interface UPGAntiPattern {
-    /** Short title — enables compact display and cross-guide search. */
+    /** Short title. Enables compact display and cross-guide search. */
     name?: string;
-    /** The anti-pattern itself — prose explanation of the mistake. */
+    /** The anti-pattern itself: prose explanation of the mistake. */
     description: string;
     /** Which entity type is typically involved in this anti-pattern. */
     affected_entity?: UPGEntityType;
@@ -18488,7 +18550,7 @@ interface UPGAntiPattern {
 interface UPGDomainUsageGuide {
     /** Domain ID this guide covers */
     domain_id: UPGDomainId;
-    /** The entity you create first — everything else hangs from it */
+    /** The entity you create first. Everything else hangs from it. */
     anchor_entity: UPGEntityType;
     /** Recommended creation sequence */
     creation_sequence: UPGEntityType[];
@@ -18513,7 +18575,7 @@ declare const UPG_DOMAIN_GUIDES: readonly UPGDomainUsageGuide[];
  */
 declare function getGuideForDomain(domainId: UPGDomainId | string): UPGDomainUsageGuide | undefined;
 /**
- * Get the anchor entity for a domain — the entity you create first.
+ * Get the anchor entity for a domain (the entity you create first).
  *
  * @example
  * getAnchorEntity('user')                 // → 'persona'
@@ -18528,7 +18590,7 @@ declare function getAnchorEntity(domainId: UPGDomainId | string): UPGEntityType
  * const all = getAntiPatterns()
  * // all[0].domain                   === 'user'
  * // all[0].anti_pattern.name        === 'persona_without_jobs' (example)
- * // all.length                      — one entry per anti-pattern across all guides
+ * // all.length                      // one entry per anti-pattern across all guides
  */
 declare function getAntiPatterns(): Array<{
     domain: UPGDomainId;
@@ -18547,8 +18609,8 @@ declare function getAntiPatterns(): Array<{
  * against free-form strings. Each variant carries enough metadata to render
  * the citation inline without further lookup.
  *
- * @example { kind: 'book', citation: 'The Lean Startup — Eric Ries (2011), ch. 7' }
- * @example { kind: 'practitioner', attribution: 'Teresa Torres — Continuous Discovery Habits' }
+ * @example { kind: 'book', citation: 'The Lean Startup, Eric Ries (2011), ch. 7' }
+ * @example { kind: 'practitioner', attribution: 'Teresa Torres, Continuous Discovery Habits' }
  * @example { kind: 'industry_practice', category: 'devops' }
  * @example { kind: 'fundamental' }
  */
@@ -18572,7 +18634,7 @@ type UPGBenchmarkSource =
     kind: 'industry_practice';
     category: string;
 }
-/** Definitional — true by the spec's own construction, not externally sourced. */
+/** Definitional: true by the spec's own construction, not externally sourced. */
  | {
     kind: 'fundamental';
 };
@@ -18632,7 +18694,7 @@ interface RatioBenchmark {
     numerator_type: UPGEntityType | UPGEntityType[];
     /** Entity type(s) forming the denominator of the ratio */
     denominator_type: UPGEntityType | UPGEntityType[];
-    /** Minimum acceptable ratio value — below this signals an imbalance */
+    /** Minimum acceptable ratio value. Below this signals an imbalance. */
     expected_min: number;
     /** Stages where this ratio is meaningful and should be evaluated */
     stages: UPGProductStage[];
@@ -18669,8 +18731,8 @@ interface DomainActivation {
  *
  * Benchmark shape: see `CountBenchmark` in `./types.ts`.
  *
- * @see ./types.ts — `CountBenchmark`, `StageRange`, `UPG_PRODUCT_STAGES`
- * @see ../intelligence.ts — health scoring consumer
+ * @see ./types.ts `CountBenchmark`, `StageRange`, `UPG_PRODUCT_STAGES`
+ * @see ../intelligence.ts health scoring consumer
  * https://unifiedproductgraph.org/spec | MIT
  */
 
@@ -18682,7 +18744,7 @@ declare const UPG_COUNT_BENCHMARKS: CountBenchmark[];
  *
  * Encodes wisdom like "each persona should have at least 2 jobs" (JTBD) or
  * "each hypothesis should produce at least one learning" (Lean Startup).
- * Relationship benchmarks are stage-scoped — a persona doesn't need 2 jobs
+ * Relationship benchmarks are stage-scoped: a persona doesn't need 2 jobs
  * at `concept`, but does by `build`.
  *
  * Consumers:
@@ -18691,8 +18753,8 @@ declare const UPG_COUNT_BENCHMARKS: CountBenchmark[];
  *
  * Benchmark shape: see `RelationshipBenchmark` in `./types.ts`.
  *
- * @see ./types.ts — `RelationshipBenchmark`
- * @see ../intelligence.ts — audit consumer
+ * @see ./types.ts `RelationshipBenchmark`
+ * @see ../intelligence.ts audit consumer
  * https://unifiedproductgraph.org/spec | MIT
  */
 
@@ -18716,8 +18778,8 @@ declare const UPG_RELATIONSHIP_BENCHMARKS: RelationshipBenchmark[];
  *
  * Benchmark shape: see `RatioBenchmark` in `./types.ts`.
  *
- * @see ./types.ts — `RatioBenchmark`
- * @see ../intelligence.ts — ratio audit consumer
+ * @see ./types.ts `RatioBenchmark`
+ * @see ../intelligence.ts ratio audit consumer
  * https://unifiedproductgraph.org/spec | MIT
  */
 
@@ -18737,16 +18799,16 @@ declare const UPG_RATIO_BENCHMARKS: RatioBenchmark[];
  *
  * Benchmark shape: see `DomainActivation` in `./types.ts`.
  *
- * @see ./types.ts — `DomainActivation`
- * @see ../../registry/domains.ts — canonical domain registry
- * @see ../intelligence.ts — domain-activation audit consumer
+ * @see ./types.ts `DomainActivation`
+ * @see ../../registry/domains.ts canonical domain registry
+ * @see ../intelligence.ts domain-activation audit consumer
  * https://unifiedproductgraph.org/spec | MIT
  */
 
 declare const UPG_DOMAIN_ACTIVATION: DomainActivation[];
 
 /**
- * benchmarks/ — Product management wisdom as structured data.
+ * benchmarks/ Product management wisdom as structured data.
  *
  * Encodes expected entity counts, relationships, ratios, and domain activation
  * thresholds per product stage. All 9 stages populated.
@@ -18775,15 +18837,15 @@ declare function getBenchmark(entityType: UPGEntityType | string, stage: UPGProd
 declare function getBenchmarksByDomain(domain: UPGDomainId | string): CountBenchmark[];
 
 /**
- * UPG Curated Anti-Patterns — cross-domain reference set.
+ * UPG Curated Anti-Patterns: cross-domain reference set.
  *
  * Each entry pairs a memorable name with a machine-evaluable
  * `IntelligenceCondition`, the stages it fires in, a "why it matters" line,
  * and a remediation hint.
  *
  * Distinct from `UPGAntiPattern` in `domain-guides.ts`:
- * - `UPGAntiPattern` (per-domain) — guidance for MCP agents working *inside* a domain.
- * - `UPGCuratedAntiPattern` (this file) — cross-cutting patterns evaluated against the *whole* graph.
+ * - `UPGAntiPattern` (per-domain): guidance for MCP agents working *inside* a domain.
+ * - `UPGCuratedAntiPattern` (this file): cross-cutting patterns evaluated against the *whole* graph.
  *
  * Adding one: append to `UPG_ANTI_PATTERNS`. Integrity tests validate id
  * uniqueness, condition well-formedness, and stage/severity vocab. Cite
@@ -18809,7 +18871,7 @@ type UPGAntiPatternSeverity = 'high' | 'medium' | 'low';
  * {
  *   id: 'features-without-hypotheses',
  *   name: 'Features without hypotheses',
- *   description: 'The graph has features but no hypotheses — work is being scoped without a stated belief about why it should work.',
+ *   description: 'The graph has features but no hypotheses. Work is being scoped without a stated belief about why it should work.',
  *   structured_condition: { operator: 'and', checks: [
  *     { check: { type: 'entity_count', entity_type: 'feature', comparison: 'nonzero' } },
  *     { check: { type: 'entity_count', entity_type: 'hypothesis', comparison: 'zero' } },
@@ -18822,7 +18884,7 @@ type UPGAntiPatternSeverity = 'high' | 'medium' | 'low';
  */
 interface UPGCuratedAntiPattern {
     /**
-     * Stable slug — kebab-case, unique within `UPG_ANTI_PATTERNS`.
+     * Stable slug: kebab-case, unique within `UPG_ANTI_PATTERNS`.
      * Surfaced as URL fragment on the `/intelligence` site page; never rename
      * once published (rename = breaking link surface).
      */
@@ -18853,7 +18915,7 @@ interface UPGCuratedAntiPattern {
      * "competitors-missing" warnings during `concept`).
      */
     stages: readonly UPGProductStage[];
-    /** Severity tier — see `UPGAntiPatternSeverity`. */
+    /** Severity tier. See `UPGAntiPatternSeverity`. */
     severity: UPGAntiPatternSeverity;
     /**
      * Optional citation for the pattern's origin (a book, practitioner,
@@ -18940,9 +19002,9 @@ interface AntiPatternInputs {
     /** Nodes with zero in-edges AND zero out-edges. */
     orphanCount: number;
     /**
-     * Active product stage — used to filter `UPG_ANTI_PATTERNS[i].stages[]`.
+     * Active product stage. Used to filter `UPG_ANTI_PATTERNS[i].stages[]`.
      * If undefined, the evaluator runs all patterns regardless of stage gating
-     * (safer default — surface everything when stage is unknown).
+     * (safer default: surface everything when stage is unknown).
      */
     productStage?: UPGProductStage;
 }
@@ -18957,7 +19019,7 @@ interface AntiPatternViolation {
     anti_pattern_id: string;
     name: string;
     severity: UPGAntiPatternSeverity;
-    /** Entity-type strings the catalog references. Phase 1 — types, not ids. */
+    /** Entity-type strings the catalog references. Phase 1: types, not ids. */
     target_entities: string[];
     description: string;
     why_it_matters: string;
@@ -18974,7 +19036,7 @@ interface EvaluateAntiPatternsOptions {
  * Evaluate the curated anti-pattern catalog against a graph's pre-computed
  * stats. Returns the violations, sorted high → medium → low, then by id asc.
  *
- * @param inputs The pre-computed graph stats — see `AntiPatternInputs`.
+ * @param inputs The pre-computed graph stats (see `AntiPatternInputs`).
  * @param options Optional filters: `severity`, `anti_pattern_ids` subset.
  *
  * @example
@@ -19027,15 +19089,15 @@ declare function isCanonicalProductStage(value: unknown): value is UPGProductSta
 /**
  * Result of a soft-coercion attempt on a product `stage` value.
  *
- * - `canonical` — the canonical UPGProductStage to use, or `undefined` when
+ * - `canonical`: the canonical UPGProductStage to use, or `undefined` when
  *   the input was unrecognised (no entry in the coercion map AND not already
  *   canonical). Callers can choose to fall back to a default (typically
  *   `'concept'`) or surface the unknown value.
- * - `originalValue` — the raw input, for warning messages and audit trails.
- * - `wasCoerced` — `true` if the input was a known legacy value that was
+ * - `originalValue`: the raw input, for warning messages and audit trails.
+ * - `wasCoerced`: `true` if the input was a known legacy value that was
  *   mapped to a canonical equivalent. `false` if the input was already
  *   canonical or unrecognised.
- * - `wasUnknown` — `true` if the input was non-canonical AND not in the
+ * - `wasUnknown`: `true` if the input was non-canonical AND not in the
  *   coercion map. Callers should fall back to a default and log loudly.
  */
 interface ProductStageCoercion {
@@ -19089,13 +19151,13 @@ declare function validateProductStageStrict(value: unknown): string | null;
  *   discovery-validation-hypothesis-cycle → build-measure-learn
  *
  * Every existing v0.2.x workflow maps here; cross-region lens workflows
- * (`product-journey`, `full-product-journey`) were dropped — their content
+ * (`product-journey`, `full-product-journey`) were dropped; their content
  * is already covered by the 10 canonical region playbooks.
  */
 
 declare const STRATEGY_OUTCOMES_PLAYBOOK: UPGPlaybook;
 /**
- * Canonical users_needs playbook — net-new authored content per Q.C of the
+ * Canonical users_needs playbook: net-new authored content per Q.C of the
  * decision doc. Persona has 25 inbound cross-edges; the spec's gravitational
  * centre. Skeleton-only is not acceptable here.
  */
@@ -19133,7 +19195,7 @@ declare const OPERATIONS_TEAM_RITUALS_PLAYBOOK: UPGPlaybook;
 declare const UPG_PLAYBOOKS: readonly UPGPlaybook[];
 
 /**
- * playbooks/ — UPG Playbook public API.
+ * playbooks/: UPG Playbook public API.
  *
  * Exports: `UPGPlaybook`, `PlaybookRuntime`, `PlaybookFilter`, `PlaybookRun`,
  * `PlaybookBinding`, `UPG_PLAYBOOKS`, and the lookup helpers
@@ -19148,12 +19210,12 @@ declare function getPlaybookById(id: string): UPGPlaybook | undefined;
 /**
  * Return the single canonical playbook for a region (the "start here" path).
  * Returns `null` when the region has no canonical playbook (W1 invariant
- * violation — caught by `audit-playbook-coverage.ts`).
+ * violation, caught by `audit-playbook-coverage.ts`).
  */
 declare function getCanonicalPlaybookForRegion(region: UPGRegionId): UPGPlaybook | null;
 /**
  * Return every playbook (canonical + specialised) anchored at a region.
- * Order is the canonical `UPG_PLAYBOOKS` order — canonical entry first by
+ * Order is the canonical `UPG_PLAYBOOKS` order, canonical entry first by
  * convention (catalog authoring discipline).
  */
 declare function getPlaybooksForRegion(region: UPGRegionId): readonly UPGPlaybook[];
@@ -19191,13 +19253,13 @@ interface FrameworkSlot {
     /** Explanation of what this slot represents in the framework */
     description?: string;
 }
-/** Where the framework came from — attribution and licensing */
+/** Where the framework came from: attribution and licensing */
 interface FrameworkOrigin {
     /** Whether the framework is from academia, a practitioner, the community, or original to UPG */
     type: 'academic' | 'practitioner' | 'community' | 'custom';
     /** Human-readable attribution (e.g. "Sean Ellis", "Marty Cagan", "Teresa Torres") */
     attribution?: string;
-    /** Provenance narrative — how the framework came about (e.g. "Published in Business Model Generation") */
+    /** Provenance narrative: how the framework came about (e.g. "Published in Business Model Generation") */
     description?: string;
     /** URL to the original source or publication */
     url?: string;
@@ -19259,12 +19321,12 @@ interface FrameworkConstant {
     properties: Record<string, unknown>;
 }
 /**
- * Everything the framework needs from the graph's data layer — which entity
+ * Everything the framework needs from the graph's data layer: which entity
  * types play which roles, which properties each type must carry under the
  * lens, and any computed or scaffolded constants.
  *
  * @example
- * // RICE — scores a feature on reach, impact, confidence, effort.
+ * // RICE: scores a feature on reach, impact, confidence, effort.
  * const riceData: FrameworkDataSpec = {
  *   entity_types: [
  *     { type: 'feature', role: 'item', min_count: 1 },
@@ -19300,12 +19362,12 @@ interface FrameworkDataSpec {
      * domain-specific fields on top of canonical entities (RICE adds
      * `reach`/`impact`/`confidence`/`effort` to a feature; Kano adds
      * `functional_response`/`dysfunctional_response`). These fields are NOT
-     * universal to the entity — they live inside the framework context.
+     * universal to the entity; they live inside the framework context.
      *
      * Consumers must read framework-introduced properties from this spec, not
      * from `UPG_PROPERTY_SCHEMA`. Renderers merge both when displaying an
-     * entity under a framework. See `src/ARCHITECTURE.md` —
-     * "Framework Properties — Lens-Scoped Fields".
+     * entity under a framework. See `src/ARCHITECTURE.md`,
+     * "Framework Properties: Lens-Scoped Fields".
      */
     required_properties: Record<string, FrameworkPropertyRequirement[]>;
     /** Properties that are derived from other properties via expressions */
@@ -19374,15 +19436,15 @@ interface NamedGroup {
 interface FrameworkStructureSpec {
     /** The visual / topological pattern (tree, table, matrix, etc.) */
     pattern: StructurePattern;
-    /** Tree levels — only used when pattern is 'tree' */
+    /** Tree levels (only used when pattern is 'tree') */
     levels?: FrameworkLevel[];
     /** Edge types used to connect entities in this framework */
     edge_types?: string[];
-    /** Matrix slots — only used when pattern is 'matrix' */
+    /** Matrix slots (only used when pattern is 'matrix') */
     slots?: MatrixSlot[];
-    /** Funnel stages — only used when pattern is 'funnel' */
+    /** Funnel stages (only used when pattern is 'funnel') */
     stages?: FunnelStage[];
-    /** Named groups — only used when pattern is 'collection' */
+    /** Named groups (only used when pattern is 'collection') */
     groups?: NamedGroup[];
 }
 /** A column definition for table-layout frameworks */
@@ -19457,7 +19519,7 @@ interface FrameworkPresentationSpec {
     card_fields?: string[];
     /** Whether tree branches can be collapsed */
     collapsible?: boolean;
-    /** Custom colour map — keys are values of the colour_by dimension, values are CSS colours */
+    /** Custom colour map: keys are values of the colour_by dimension, values are CSS colours */
     colour_map?: Record<string, string>;
 }
 /** One step in a guided walkthrough of how to use a framework */
@@ -19490,11 +19552,11 @@ interface FrameworkEducation {
  * A UPG Framework is a declarative, config-driven lens that structures
  * UPG graph data into a well-known product management pattern.
  *
- * Frameworks are pure data — no code. The rendering engine reads the
+ * Frameworks are pure data; no code. The rendering engine reads the
  * framework definition and produces the appropriate UI.
  *
  * @example
- * // Abbreviated RICE definition — shows the layer split (data / structure
+ * // Abbreviated RICE definition, showing the layer split (data / structure
  * // / presentation / education). Real definitions live in
  * // `src/frameworks/definitions/`.
  * const riceFramework: UPGFramework = {
@@ -19570,19 +19632,19 @@ interface UPGFramework {
     /** ID of a parent framework this one extends */
     extends?: string;
     /**
-     * The approaches this framework serves — many-to-many. Each value is a
+     * The approaches this framework serves (many-to-many). Each value is a
      * `UPGApproachId` (`'plan' | 'inspect' | 'prioritise' | 'trace' | 'reflect'`).
-     * Optional — partial coverage is by design; adding tags later is additive.
+     * Optional: partial coverage is by design; adding tags later is additive.
      *
      * Type-erased to `string[]` to avoid a circular import with
      * `approaches/types.ts`. Conceptually `readonly UPGApproachId[]`.
      *
-     * @see MENTAL-MODEL.md — approach × framework relationship
+     * @see MENTAL-MODEL.md, approach × framework relationship
      */
     approach_ids?: readonly string[];
 }
 /**
- * Lightweight framework metadata — the identity + origin subset of UPGFramework.
+ * Lightweight framework metadata: the identity + origin subset of UPGFramework.
  *
  * Use this type for catalogue listings, site data, and anywhere that needs
  * framework identity without the full data/structure/presentation/education layers.
@@ -19610,7 +19672,7 @@ interface UPGFrameworkMeta {
 }
 
 /**
- * UPG Approach primitive — the cognitive *path of arrival* to a region.
+ * UPG Approach primitive: the cognitive *path of arrival* to a region.
  *
  * Five canonical approaches: Plan, Inspect, Prioritise, Trace, Reflect.
  * The catalog is closed. New techniques land as frameworks under existing
@@ -19621,7 +19683,7 @@ interface UPGFrameworkMeta {
  */
 
 /**
- * The five canonical approach ids. Closed catalog — adding a sixth is a
+ * The five canonical approach ids. Closed catalog: adding a sixth is a
  * coordinated breaking-shape change.
  *
  * Source of truth for `UPGFramework.approach_ids` and the MCP tool dispatch
@@ -19632,17 +19694,17 @@ type UPGApproachId = 'plan' | 'inspect' | 'prioritise' | 'trace' | 'reflect';
  * A definition record describing a cognitive engagement category exposed as
  * a verb-led MCP tool (`plan` / `inspect` / `prioritise` / `trace` / `reflect`).
  *
- * Today these ship as definition lookups — the MCP handler returns the
+ * Today these ship as definition lookups: the MCP handler returns the
  * approach record + invocation parameters; the LLM is the executor.
  * Structured execution is forward-declared (see `ApproachRuntime`) and is
  * a forthcoming follow-up.
  *
  * @example
- * // The Prioritise approach — "what's most important?"
+ * // The Prioritise approach: "what's most important?"
  * const prioritise: UPGApproach = {
  *   id: 'prioritise',
  *   label: 'Prioritise',
- *   description: 'Rank a candidate set by an explicit framework — RICE, ICE, Kano, Cost of Delay.',
+ *   description: 'Rank a candidate set by an explicit framework: RICE, ICE, Kano, Cost of Delay.',
  *   question_answered: "what's most important?",
  *   signature_hint: '({ candidates: entity_ids[], framework_id }) → { ranked, framework_used }',
  *   framework_id_examples: ['rice-scoring', 'ice-scoring', 'kano-model', 'cost-of-delay'],
@@ -19650,11 +19712,11 @@ type UPGApproachId = 'plan' | 'inspect' | 'prioritise' | 'trace' | 'reflect';
  */
 interface UPGApproach {
     /**
-     * Unique identifier — bare verb, matches the MCP tool name. One of
+     * Unique identifier: bare verb, matches the MCP tool name. One of
      * `'plan' | 'inspect' | 'prioritise' | 'trace' | 'reflect'`.
      */
     id: UPGApproachId;
-    /** Human-readable label (Title Case) — `'Plan'`, `'Inspect'`, etc. */
+    /** Human-readable label (Title Case): `'Plan'`, `'Inspect'`, etc. */
     label: string;
     /** One-paragraph description of the cognitive engagement category. */
     description: string;
@@ -19664,44 +19726,44 @@ interface UPGApproach {
      */
     question_answered: string;
     /**
-     * Compact signature reminder — `(args) → return-shape`. Documents the
+     * Compact signature reminder: `(args) → return-shape`. Documents the
      * structured-execution shape; today the MCP handler returns the approach
      * record + invocation parameters (definition lookup).
      */
     signature_hint: string;
     /**
-     * 3-5 canonical framework ids inside this approach (`UPGFramework.id`) —
+     * 3-5 canonical framework ids inside this approach (`UPGFramework.id`),
      * a discoverability surface, not exhaustive coverage. Full reverse-lookup
      * is via `UPGFramework.approach_ids`.
      */
     framework_id_examples?: readonly string[];
 }
 /**
- * Canonical reflect modes — the 4 nouns the `reflect` approach accepts as an
+ * Canonical reflect modes: the 4 nouns the `reflect` approach accepts as an
  * optional `mode` parameter. Absence of `mode` is open reflection.
  *
  * Locked vocabulary; agent-facing. Users speak natural language; the LLM
  * translates `"what assumptions are we making?"` → `mode: 'assumptions'`.
  */
 type ReflectMode = 'assumptions' | 'alternatives' | 'blind-spots' | 'load-bearing';
-/** Closed list — useful for tool input-schema enums. */
+/** Closed list, useful for tool input-schema enums. */
 declare const REFLECT_MODES: readonly ReflectMode[];
 /**
  * Shared envelope every approach handler returns. The handler-specific
- * payload spreads into `...payload` — see each approach's `signature_hint`
+ * payload spreads into `...payload`; see each approach's `signature_hint`
  * for the per-id shape.
  */
 interface UPGApproachEnvelope {
     /** The approach id this envelope is wrapping. */
     approach_id: UPGApproachId;
     /**
-     * Approach-specific scope — a region id (Plan, Inspect, Reflect), an
+     * Approach-specific scope: a region id (Plan, Inspect, Reflect), an
      * anchor entity id (Trace), an entity id array (Prioritise candidates),
      * or `null` (open invocation). Typed `unknown` because the shape varies
      * by approach.
      */
     scope: unknown;
-    /** ISO-8601 datetime — when the handler produced the envelope. */
+    /** ISO-8601 datetime when the handler produced the envelope. */
     generated_at: string;
 }
 /** Per-surface experience binding for a `UPGApproach`. Forward-declared. */
@@ -19712,28 +19774,28 @@ interface ApproachBinding {
     surface: SurfaceId;
     /** Identifier the runtime maps to a component or handler */
     renderer: string;
-    /** Per-step renderer overrides — keyed by `Step.order` */
+    /** Per-step renderer overrides, keyed by `Step.order` */
     step_renderers?: Record<number, string>;
     /** Surface-specific step kinds the runtime handles */
     custom_step_kinds?: readonly string[];
-    /** Lifecycle hook id — runtime-resolved, fires when an invocation starts */
+    /** Lifecycle hook id: runtime-resolved, fires when an invocation starts */
     on_start?: string;
-    /** Lifecycle hook id — runtime-resolved, fires after each step */
+    /** Lifecycle hook id: runtime-resolved, fires after each step */
     on_step_complete?: string;
-    /** Lifecycle hook id — runtime-resolved, fires when an invocation completes */
+    /** Lifecycle hook id: runtime-resolved, fires when an invocation completes */
     on_run_complete?: string;
 }
 /** Narrowing filter for `listApproaches`. All fields AND together. */
 interface ApproachFilter {
     /** Filter to approaches whose framework_id_examples include this id */
     framework_id?: string;
-    /** Filter to approaches relevant to a specific region (forward-compat — all five are cross-region today) */
+    /** Filter to approaches relevant to a specific region (forward-compat; all five are cross-region today) */
     region?: UPGRegionId;
     /** Filter to approaches reachable via a specific entry mode (forward-compat) */
     entry_mode?: EntryMode;
 }
 /**
- * A concrete invocation of a `UPGApproach`. Forward-declared — the MCP
+ * A concrete invocation of a `UPGApproach`. Forward-declared: the MCP
  * handlers are stateless definition lookups today; structured execution
  * with run tracking is a forthcoming follow-up.
  */
@@ -19753,7 +19815,7 @@ interface ApproachRun {
 }
 /**
  * Forward-declared interface for a future structured-execution runtime. No
- * current surface implements it — the MCP tools ship as definition lookups.
+ * current surface implements it; the MCP tools ship as definition lookups.
  */
 interface ApproachRuntime {
     /** Return all approaches matching an optional filter */
@@ -19767,15 +19829,15 @@ interface ApproachRuntime {
 }
 
 /**
- * approaches/definitions/ — the five canonical UPGApproach records.
+ * approaches/definitions/: the five canonical UPGApproach records.
  *
- * Each record is a definition lookup — id, label, description (cartographic
+ * Each record is a definition lookup: id, label, description (cartographic
  * framing), question_answered, signature_hint, framework_id_examples.
  * Structured execution semantics are a forthcoming follow-up; the LLM is the
  * executor today.
  *
  * Order is stable: Plan / Inspect / Prioritise / Trace / Reflect. Matches the
- * cognitive flow — decide what to build, check what's broken, rank what's
+ * cognitive flow: decide what to build, check what's broken, rank what's
  * most important, walk a path through what exists, question what you're
  * assuming.
  *
@@ -19806,7 +19868,7 @@ declare function getRegionForEntityType(entityType: string): UPGRegion | undefin
 declare const UPG_REGION_COUNT: number;
 
 /**
- * Framework validation — validates UPGFramework objects against the spec.
+ * Framework validation: validates UPGFramework objects against the spec.
  */
 /** Result of validating a UPGFramework object */
 interface FrameworkValidationResult {
@@ -19852,7 +19914,7 @@ interface FrameworkValidationResult {
 declare function validateUPGFramework(framework: unknown): FrameworkValidationResult;
 
 /**
- * Canonical Framework Library — v1 public surface.
+ * Canonical Framework Library: v1 public surface.
  *
  * The 34 famous, battle-tested product frameworks that anchor the public
  * Unified Product Graph framework catalog. Curated for editorial confidence
@@ -19864,7 +19926,7 @@ declare function validateUPGFramework(framework: unknown): FrameworkValidationRe
  * promoted into this canonical set incrementally as each framework is
  * reviewed and validated.
  *
- * THIS FILE IS GENERATED — see scripts/regen-canonical-frameworks.mjs.
+ * THIS FILE IS GENERATED. See scripts/regen-canonical-frameworks.mjs.
  */
 
 declare const UPG_FRAMEWORKS: UPGFramework[];
@@ -19883,7 +19945,7 @@ declare const UPG_FRAMEWORKS_BY_CATEGORY: Record<string, UPGFramework[]>;
  */
 
 /** The current spec version implemented by this package */
-declare const UPG_VERSION: "0.7.0";
+declare const UPG_VERSION: "0.7.3";
 /**
  * The `.upg` JSON document format version. Written to the `upg_version` field.
  * Evolves independently from `UPG_VERSION` (the catalogue version).
@@ -19906,7 +19968,7 @@ declare const UPG_EDGE_TYPES: readonly UPGEdgeType[];
  * Lookup map: `"source_type:target_type"` → ordered list of canonical edge keys.
  *
  * Computed from the edge catalog. Multiple edges may share a `(source, target)`
- * pair — e.g. `learning_updates_hypothesis` (causal) and `learning_refines_hypothesis`
+ * pair, e.g. `learning_updates_hypothesis` (causal) and `learning_refines_hypothesis`
  * (cross-domain) both connect `learning → hypothesis`. Prior to v0.4.1 this map
  * was a `Record<string, UPGEdgeType>` populated by `Object.fromEntries`, which
  * silently dropped every collision but the last (35 pairs).
@@ -19939,14 +20001,14 @@ declare function resolveAllEdges(sourceType: string, targetType: string): UPGEdg
  * **Policy:**
  * 1. If `hint` is provided and an edge with that `classification` exists for
  *    the pair, return it (first declared wins for sub-collisions inside a
- *    single classification — declaration order is the canonical tiebreaker).
+ *    single classification, declaration order is the canonical tiebreaker).
  * 2. Otherwise, return the highest-ranked classification edge available,
  *    using `CLASSIFICATION_RANK` (hierarchy ≻ causal ≻ semantic ≻ cross-domain).
  * 3. If the pair has no catalogued edges, return `null`.
  *
  * **Determinism:** for any `(source, target)` the picked edge is stable across
- * runs and never changes unless the catalog is edited. This is the v0.4.1 fix
- * — pair collisions are no longer last-wins.
+ * runs and never changes unless the catalog is edited. This is the v0.4.1 fix:
+ * pair collisions are no longer last-wins.
  *
  * @example
  * pickCanonicalEdge('product', 'decision', 'hierarchy')
@@ -19960,8 +20022,8 @@ declare function pickCanonicalEdge(sourceType: string, targetType: string, hint?
  * Resolve the canonical `UPGEdgeType` for a containment relationship.
  *
  * Import adapters need to emit edges like "epic contains user_story" but
- * cannot safely construct raw `${parent}_contains_${child}` template strings —
- * that union is closed and most pairs are not registered. This function looks
+ * cannot safely construct raw `${parent}_contains_${child}` template strings,
+ * because that union is closed and most pairs are not registered. This function looks
  * up the canonical edge for the given parent→child pair using
  * `pickCanonicalEdge` with the `'hierarchy'` hint, falling back through the
  * standard precedence when no hierarchy-class edge exists for the pair.
@@ -19975,7 +20037,7 @@ declare function pickCanonicalEdge(sourceType: string, targetType: string, hint?
  *   caller can fall back to `node_informs_node` or skip the edge entirely.
  *
  * **Design note:** the `hint` argument is omitted from this function for
- * back-compat — all in-tree callers (Markdown, Notion, Linear, GitHub
+ * back-compat. All in-tree callers (Markdown, Notion, Linear, GitHub
  * adapters) are containment-only. Callers that need a different classification
  * should call `pickCanonicalEdge(source, target, hint)` directly.
  *