AI expanded what one person can produce. It did not expand what one person can hold in their head. This is the production-comprehension gap: the widening distance between what AI enables a person to generate and what a person can actually reason about, connect, and act on coherently. As AI capabilities grow, this gap continues to widen.

The gap is less about AI capability than about how product knowledge is stored. A founder working alone can speed-draft dozens of product artifacts in an afternoon: research notes, user flows, architecture sketches, feature specifications, pricing models. They may use different terms for each. Within a week, they have fifty of them. Soon after, they cannot remember which artifact connects to which pain point, which hypothesis was validated and which was abandoned, or whether the pricing model drafted earlier aligns with the positioning refined later. The artifacts exist. The agent reading them rarely knows the connections between them, and the founder rarely does either.

Documents, whether in Notion, Confluence, Google Docs, or markdown files, are containers for prose. They are not containers for relationships. Modern AI systems soften this limit: vector search, retrieval-augmented generation, and LLM-indexed wikis can surface the persona document when a question is asked about the feature. But similarity is not the same as structure. The connection between persona and feature still lives, implicitly, in the author's head. It is not declared anywhere a tool can reliably traverse, and that memory fades between sessions and does not transfer to the next person or agent on the project.

What is needed is structure for product work that persists across environments, and a framework-agnostic data model that retains what is true about the product as vocabularies and tools change around it.

Product knowledge today lives across tools that each own a fragment of the picture. A typical team uses:

• Notion or Confluence for strategy documents and research notes
• Linear, Jira, or Asana for delivery tracking
• Figma or FigJam for design artifacts and whiteboarding
• Miro or Whimsical for journey maps and canvases
• Productboard or Vistaly for discovery and opportunity trees
• Sheets or Airtable for prioritisation and roadmapping

Each tool captures its own domain well, but no single tool captures the cross-domain relationships that hold product thinking together. Moving between them always requires translation, and that translation has traditionally lived in people: the feature in Linear, the persona in Notion that motivated it, the hypothesis in Miro that validated it, and the pricing tier in Sheets that packages it were juggled by the practitioners who wrote them.

That arrangement held while humans were the only ones producing product work. When AI agents generate artifacts at machine speed, the human-translation layer cannot keep up: connections accumulate faster than any person can catalogue them. The structure has to live somewhere other than a practitioner's head.

Tool-direct retrieval helps but does not close the gap. An AI agent that can pull documents from Notion, issues from Linear, and frames from Figma still receives them in parallel: every tool has its own schema, its own vocabulary, its own notion of what a "feature" or a "user" even is. Without a shared schema across tools, the information arrives in the agent's context window as parallel streams, not as a connected graph.

An agent given access to this corpus can do more than retrieve individual documents. It can even infer connections between them by re-reading prose at query time: an emergent graph assembled on demand from similarity and summarisation. But an emergent graph is not a curated one. The relationships it surfaces are plausible, not declared, and they must be re-discovered on every run. The structure that matters for product work is not declared anywhere it can be reliably traversed, versioned, or trusted.

Closing the production-comprehension gap calls for a structural layer of its own: a shared foundation humans and AI agents can both use to capture the things a product is made of, the relationships between them, and the reasoning that ties them together. Tools are transient; the knowledge they capture should not be. That foundation is an ontology for product knowledge.

An ontology provides three things that neither documents nor individual tools can:

1. Typed entities. A type is a named category of things that share the same shape: the same information, the same lifecycle, and the same place in the graph. A persona is a different type from a feature, and a feature is a different type from an architectural decision. The ontology defines each type UPG covers: what information it carries, what states it moves through as work progresses, and where it sits in relation to the others. Once something is recognised as a persona, every tool or AI agent that speaks the ontology knows how to handle it without relearning what a persona is.

2. Directed relationships. A relationship between two entities has a name that tells you what the connection means and a direction that tells you which side is the subject. A hyperlink tells you that two documents are related; it cannot tell you how. An ontology names the relationship and gives it direction: a persona pursues a job, an opportunity addresses a need, a hypothesis requires an experiment. Each relationship reads coherently in both directions, so a person or an AI agent can ask "what does this hypothesis require?" or "which hypotheses require this experiment?" and get a real answer.

3. Portability. Knowledge that lives in a plain, open file any compatible tool can read and write, not inside a vendor's database. The knowledge lives in a plain .upg file. The file travels with the product, not with the vendor that happens to be hosting it this year. You can save it to git, see what changed between two versions, hand it to a teammate, and feed it to any AI agent as structured context. Product knowledge stops being trapped inside a tool you may not want to use next year.

This paper describes one such ontology and the open specification built around it: the Unified Product Graph (UPG). UPG is MIT-licensed, implemented as a set of TypeScript packages, and designed to work inside any AI development environment that speaks the Model Context Protocol, with reference implementations in Claude Code, Cursor, and VS Code.

At the root of the production-comprehension gap is a memory problem. Human working memory is limited to approximately 7 ± 2 chunks (Miller, 1956). Large language model context windows, while much larger, reset between sessions and degrade with the position of information within the window (Liu et al., 2024). Neither provides the persistent, structured, queryable memory that long-running product work requires.

A growing landscape of tools addresses this at the seat level. Karpathy's LLM Wiki proposes an incrementally updated markdown collection that the model curates rather than retrieves over, where synthesis is stored once and re-used instead of re-derived on every query (Karpathy, 2026). Graphify turns a repository of code, docs, and diagrams into a queryable knowledge graph for AI coding assistants, built explicitly in the LLM Wiki lineage (Shamsi, 2026). Claude-mem captures session observations in a local SQLite and vector store, re-injecting relevant context into future Claude Code sessions (thedotmack, 2026). These are valuable where they sit, but each is scoped to one operator, one codebase, or one agent. Product work needs something different: a memory shared across people, agents, stakeholders, and time, independent of any single tool or installation. Structure that lives on one developer's machine is not structure the next collaborator, or the next agent, inherits.

Documents solve memory poorly. A document is a linear container for prose, which means it must be re-read to be used. The next AI session that needs information from a 1,500-word persona document must re-read the entire document, because the relationships inside it are not indexed as typed data. Retrieval-augmented generation and semantic search can surface the right document, but retrieval is not the same as structure: a retrieved document still has to be re-parsed, and the connections between artifacts remain implicit in prose rather than declared as traversable edges. The result is a fuzzy graph at best, re-assembled on demand, different every time.

A typed graph solves memory differently. Every entity becomes a stable, referenceable record. A persona captured in week one has a stable identity, a defined shape, and declared relationships to the jobs, needs, and outcomes it connects to. In week ten, an AI agent retrieving that persona performs a single structured query rather than a document re-read. More importantly, every entity written during the intervening nine weeks is already connected to it. Output from yesterday's session becomes context for today's without re-contextualising, and without depending on any individual operator's local setup.

Compounding. A property of structured memory in which each new entity added to the graph does not merely sit alongside existing ones but actively connects to and extends them, so the queryable value of the graph grows faster than its storage cost.

Concretely: a persona captured in week one is referenced by three hypotheses written in week three, which are refuted by a research insight captured in week five, which motivates a feature shipped in week eight. In week ten, asking "what evidence supports this feature?" traverses four typed edges and returns the answer. No re-reading, no re-assembly, no drift. The graph gets denser with every session, and every new entity increases the number of questions the graph can answer. This is the opposite of document accumulation, where each new file is another thing to read from the top. Compounding is what makes a structure count as memory rather than storage, and it is the property that qualifies structured memory as the category of solution the production-comprehension gap requires.

To see compounding concretely, contrast two versions of the same ten-week founder workflow:

Each session starts from zero. Every session starts from where the last one left off.

The argument is not that UPG saves time on any one session. The argument is that UPG makes every session cheaper than the last.

Compounding is not autonomous. The founder still runs the guided playbooks and approaches that produce each entity, the AI still emits mapping_confidence annotations that a human reviews, and entities still get merged, deleted, and corrected as the model of the product evolves. The graph is a shared memory, curated jointly by the practitioner and the AI agents they work with. The marginal cost of writing an entity is roughly the marginal cost of writing a document; the marginal value is different, because one disappears into a folder and the other accrues into a queryable structure.

This paper makes four contributions, corresponding to the argument structure of the section just closed.

1. A framing of structured memory as the category of solution. The production-comprehension gap (§1.1) is, at root, a memory problem (§1.4), and the property that qualifies a structure as memory rather than storage is compounding: each new entity connects to and extends the existing graph rather than sitting beside it. This paper names that property, defines it precisely, and argues that it is what product work requires.

2. An ontology for product knowledge. UPG defines a stable vocabulary of entity types covering the full arc of product creation, from the research insights and personas that shape a product, to the features, architectural decisions, and growth experiments that ship it, to the organisational structures that surround it. Every type carries a defined shape: the information it holds, the lifecycle it moves through, and the place it occupies in a domain hierarchy organised as concentric rings outward from the product nucleus. Relationships between types are typed and directed, with human-readable verb pairs that carry meaning in both directions. The same ontology extends from a single product to a portfolio of them: cross-product edge types and a portfolio-level registry of canonical shared entities (§3.10) let a company's products share personas, metrics, and foundational specifications rather than duplicate them. The full catalogue of types and edges is given in the Technical Appendix.

3. A layered architecture for the specification itself. The ontology is organised into conceptual layers with a strict dependency flow: catalog (what the types are), grammar (how they combine), properties (what information they carry), and output (how they are serialised and consumed). Layers are self-contained and can be adopted incrementally, so an implementer can read the catalog without the output layer, or build tooling against the grammar without committing to every property. The architecture is what makes the specification evolvable: each layer can grow without breaking the ones above or below it.

4. A tooling ecosystem that makes the specification usable in practice. Local and cloud MCP servers that let any AI agent read and write against a .upg file or a remote graph. Agent-native import: a recipe catalog, exposed through a single MCP tool (get_import_recipe), that hands any agent the canonical mapping from thirty-plus external sources — Notion, Linear, Jira, GitHub, Dovetail, and more — into typed entities; the agent executes the import, the recipe carries the mapping, so import fidelity comes from data, not from per-source code. Guided playbooks and approaches that run inside any AI agent speaking the Model Context Protocol. A parser for UPG Markdown, the human-readable serialisation of the format. And a visual graph application — Entopo — built on the specification as its reference product surface, for the moments where a canvas is the right interface.

Taken together, these contributions close a single loop. Section 1 has argued that product knowledge needs a foundation that lives beneath any single tool, that this foundation must solve a memory problem, and that compounding is the property that makes structured memory work. The ontology, the architecture, and the tooling are the three layers of that foundation. The rest of the paper describes each in detail and examines the design choices that hold them together.

Section 1 argued for a foundation that lives beneath any single tool. To locate where such a foundation sits, it helps to start with the tools themselves. Product work today is spread across a landscape of categories that coexist and overlap, each with its own purpose and its own gap.

Work trackers. Jira (2002), Linear (2019), Asana (2008), and GitHub Projects model product work as tasks with status, assignment, and hierarchy. Their ontology is minimal and delivery-oriented: issues, epics, sprints, releases. They answer what are we building? Not why are we building it?

Discovery platforms. Productboard (2014), Vistaly (2020), and ProductPlan introduce structured discovery artifacts: opportunity solution trees, evidence boards, persona canvases. They capture the why, typically as a system disconnected from delivery. The discovery graph and the delivery graph do not share a schema. A validated opportunity in Productboard has no typed connection to a shipped feature in Jira. They answer why are we building it? Not is it actually being built?

Collaboration surfaces. Notion, Confluence, Google Docs, and Coda on the document side; Miro, Lucidchart, Whimsical, and FigJam on the whiteboarding side. These tools were designed for an era when context was held in people: teams shared a room, a Slack channel, or a whiteboard, and meaning travelled with the humans who wrote and drew. They are deliberately schema-free, and their strength is that flexibility. Their limit is that everything they hold is prose or pixels, not typed data. Each is now adding AI features of its own: Notion AI, Miro AI, FigJam AI. But those features are trapped inside the tool they live in. Without a shared schema across tools, an AI inside Notion cannot reason about a flow in Miro or a design in Figma. They answer what has the team been thinking? Not what has the team decided, and how does it connect to everything else?

Design tools. Figma, Sketch, and Adobe XD hold the visual artifacts of product work: wireframes, components, flows, prototypes. Their internal ontology (frames, components, variants) is rich for visual composition but blind to the product-level concepts those artifacts represent. A Figma frame named "Checkout: empty cart" does not know it depicts a user-journey step that addresses a pain point backed by a research insight. They answer what will it look like? Not what does it address, and why does it matter?

AI copilots. The most recent layer, which runs across every category above rather than forming its own: Notion AI, Linear AI, Figma AI, Cursor, and Claude Code. Each copilot is a generator, and each generates inside the ontology of the tool it lives in. More generation, same fragmentation: the AI that drafts a Linear ticket has no structural handle on the persona described in Notion or the component sketched in Figma. They answer what can we generate next? Not how does it fit what already exists?

Each of these categories solves its problem well within its own scope. What is missing, across the whole landscape, is a shared substrate that describes what a product is. The Unified Product Graph (UPG) is designed to sit beneath the landscape rather than within it: a cross-domain ontology spanning strategy, users, discovery, validation, design, engineering, growth, business model, marketing, operations, and organisational structure, so that a work tracker, a discovery platform, a document, a whiteboard, a Figma file, and an AI copilot can all reference the same typed entities rather than each maintain their own.

flowchart TD
  subgraph airow["AI Copilots"]
    ai["Notion AI · Linear AI · Figma AI · Cursor · Claude Code"]
  end
  subgraph tools["Tool Silos: each with its own schema"]
    direction LR
    tracker["Work Trackers\nLinear · Jira"]
    discovery["Discovery\nProductboard · Vistaly"]
    collab["Collaboration\nNotion · Miro"]
    design["Design\nFigma · Sketch"]
  end
  subgraph substrate["UPG: Shared Substrate (beneath every tool)"]
    upg["Unified Product Graph\nTyped entities · Directed edges · Portable .upg file\nCommon ontology readable by any MCP-capable agent"]
  end
  airow --> tools
  tracker & discovery & collab & design -->|"read / write\nshared typed entities"| upg

A fair question at this point: if the Unified Product Graph (UPG) is a typed graph with stable identifiers and directed relationships, why does it not use one of the existing standards for knowledge representation? The World Wide Web Consortium has produced a family of such standards over two decades, each with real adoption. It is worth explaining what each is, what UPG implemented in them would look like, and why UPG did not take that path.

RDF: the Resource Description Framework. A W3C standard (2004) for expressing knowledge as triples of the form subject-predicate-object, where each term is typically a URI. RDF is the foundation of the Semantic Web vision. In RDF, the statement "Felix pursues the job of deciding which feature to ship before the holiday window" would be expressed as three URIs bound together, one for Felix, one for the pursues relationship, and one for the job. A graph in RDF is a collection of such triples. RDF Schema (RDFS) adds a light type system on top, letting you declare that Persona is a class and pursues is a property.

OWL: the Web Ontology Language. A W3C standard (2004, updated 2012) that extends RDF with richer constructs for formal reasoning. Where RDF tells you what is, OWL lets you describe what must follow. It supports class hierarchies, property restrictions, cardinality constraints, and logical inference. An OWL reasoner can deduce that if Felix is-a Persona and every Persona pursues at least one Job, then Felix pursues at least one job. OWL comes in three profiles (Lite, DL, Full) that trade expressive power against computational decidability. Biomedical ontologies like SNOMED CT and the Gene Ontology are built on OWL.

schema.org. A consumer-oriented vocabulary founded in 2011 by Google, Bing, Yahoo, and Yandex, used to annotate structured data on web pages. schema.org is the most widely deployed structured-data standard in the world. It defines types like Person, Organization, Event, Product, Recipe, Review, with properties for each, and it is typically serialised as JSON-LD embedded in HTML. When a search engine shows a rich result with ratings, dates, or prices extracted from a page, it is reading schema.org annotations. Its scope is deliberately broad and shallow: shared labels any web publisher can use, not formal reasoning.

Honestly sketched, a UPG-in-RDF version of a single persona and a connected feature would translate roughly like this in Turtle syntax:

@prefix upg: <https://upg.dev/ontology/> .
@prefix : <https://example.com/products/threadline/> .

:persona-felix
    a upg:Persona ;
    upg:name "Felix, solo builder" ;
    upg:pursues :job-decide-next-feature .

:feature-cross-meeting-search
    a upg:Feature ;
    upg:informed-by :learning-volume-vs-value ;
    upg:in-feature-area :feature-area-search-recall .

Layering OWL on top would add class definitions and formal constraints. A minimal OWL treatment of the same types, in OWL's Turtle form, would look like this:

@prefix owl:  <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
@prefix upg:  <https://upg.dev/ontology/> .

upg:Persona a owl:Class .
upg:Feature a owl:Class .
upg:Opportunity a owl:Class .

upg:pursues a owl:ObjectProperty ;
    rdfs:domain upg:Persona ;
    rdfs:range upg:Job .

upg:implements a owl:ObjectProperty ;
    rdfs:domain upg:Feature ;
    rdfs:range upg:Opportunity .

upg:Feature rdfs:subClassOf
    [ a owl:Restriction ;
      owl:onProperty upg:implements ;
      owl:minCardinality 1 ] .

OWL's contribution is the cardinality restriction at the bottom: every Feature must implement at least one Opportunity. An OWL reasoner can then catch a graph where a Feature exists without a connected Opportunity, or infer the missing connection if other constraints imply it. This is the inference machinery UPG does not currently need, since product-work validation is closer to "does each shipped feature have a research-backed opportunity?" than to automated theorem proving.

The schema.org treatment of the same information compresses dramatically, because the vocabulary was not designed for product work:

{
  "@context": "https://schema.org/",
  "@type": "Person",
  "name": "Felix",
  "description": "Persona pursuing the job of deciding which feature to ship before the holiday window"
}

Persona maps awkwardly to Person, which on schema.org is a real human (typically authors, employees, or search-result subjects) rather than a research abstraction. There is no schema.org equivalent for Feature, Opportunity, Pain Point, or Hypothesis in the sense a product team uses those words. Capturing the full UPG graph under schema.org would mean either flattening every UPG type into a generic parent like Thing or CreativeWork, which strips the product-specific semantics, or defining an extension vocabulary at upg.dev and using schema.org only for the small overlap (such as Organization for the team). In the latter case the extension does almost all the work, which is the scope-mismatch argument in its concrete form.

All three would work. So why not use them? The decision came down to four factors:

What UPG inherits from this tradition is the core idea: typed entities, typed directed relationships, stable identifiers, and an open serialisable format. What UPG departs from is the implementation substrate, TypeScript rather than RDF/OWL; the lifecycle treatment, baked in rather than patched on; the edge vocabulary, human-readable verb pairs on every relationship; and the scope, a vocabulary shaped by product work rather than by the open web.

Section 1.4 introduced a family of tools that extract structure from prose on demand: Karpathy's LLM Wiki, Graphify, and claude-mem, each operating at the seat level. The same pattern scales up. Microsoft's GraphRAG (Edge et al., 2024) applies LLM-driven extraction across enterprise document corpora, building community summaries and cross-document graphs that outperform flat retrieval on comprehensiveness. A broader class of LLM-assisted knowledge-graph extraction tools turns any input (code, documents, papers, screenshots) into a clustered graph in minutes.

These systems share a philosophy with UPG: the AI should maintain the structure, not the human. They also produce measurable gains over unstructured retrieval. GraphRAG reports 72–83% comprehensiveness wins over baseline RAG; graph-augmented benchmarks triple LLM accuracy on schema-intensive questions (data.world, 2024). The case for structure is settled. The case for which structure is not.

The distinction is between emergent graphs and curated graphs.

Emergent graphs describe what a corpus contains. They read documents and surface the concepts mentioned, the entities named, and the soft associations between them. They are excellent for personal knowledge synthesis, exploratory reading, and retrieval over unstructured material. They reflect what you have written.

Curated graphs describe what a practitioner has decided. Entities are created deliberately, with known types, stable identifiers, typed edges, and lifecycle status. Edges carry verbs with direction. The graph does not reflect what you have written. It reflects what you have resolved, connected, and committed to building.

For product creation, five differences matter:

Emergent and curated graphs are not mutually exclusive. A product team may well want both: emergent retrieval over the raw document corpus (meeting notes, Slack threads, user interview transcripts) and a curated graph of the decisions, hypotheses, and shipped work those documents produced. UPG takes the curated approach because product creation is a domain with lifecycles, evidence chains, and resolutions, not a corpus of interchangeable text.

The wiki and the graph. The wiki holds what you know. The graph holds what you have decided, validated, connected, and committed to building.

Both can coexist. A team that writes extensively in Notion or Confluence can extract an emergent graph from its pages and still maintain a curated UPG of its product. The two structures answer different questions. Ask the wiki "what have we been thinking about?" and it returns pages and paragraphs that mention the topic. Ask the graph "what have we decided to build, and what is its evidence?" and it returns typed entities connected by typed edges, traceable end to end. UPG is the second structure, because product work is the second question.

A curated graph is only useful if AI agents can read from it and write into it without custom integration work per tool. The Model Context Protocol (MCP), introduced by Anthropic in 2024, is the emerging standard that makes this possible.

MCP. An open protocol that defines a uniform client-server interface for AI assistants to discover and invoke external tools and data sources. Before MCP, integrating an AI assistant with an external system meant writing bespoke glue for that pair. An assistant that could read Jira could not, without more work, read Linear; an assistant that could search Notion could not, without more work, query a vector store. Each integration was a custom contract between one client and one backend. MCP abstracts that contract into a protocol: servers expose tools, resources, and prompts through a standard schema, and any MCP-capable client can discover and call them the same way. The cost of adding a new data source drops from "a few weeks of integration work per client" to "run an MCP server once, any client can use it."

The protocol grew quickly because the problem it solves is load-bearing for every AI assistant. Claude Code, Cursor, VS Code, Zed, Continue, and a growing list of editors and chat interfaces ship with MCP support. Servers now exist for databases, filesystems, Git hosts, design tools, and most of the category-leading SaaS products. The interoperability dividend is that a single MCP-native tool becomes addressable from every MCP-aware client, without the vendor having to build a separate integration for each.

The Unified Product Graph (UPG) is MCP-native. The specification's primary read/write interface is the UPG MCP server (@unified-product-graph/mcp-server), which exposes CRUD operations on nodes and edges, graph traversal queries, batch mutations, schema introspection, and validation against the ontology. A companion cloud server (@unified-product-graph/cloud-server) does the same over a remote graph backed by a Postgres store, for teams that want a shared graph rather than a local file. Any MCP-capable client (Claude Code, Cursor, Zed, Continue, or a custom in-house agent) reads, writes, and reasons about product graphs without bespoke integration. The agent's side of the contract is the MCP tool list; UPG's side is the graph operations those tools map to.

Two design choices follow from the MCP-native posture. First, UPG does not invent a new wire protocol. The specification focuses on the ontology itself, what the types are, how they connect, what their lifecycles look like, without also specifying how agents call into it. Second, the surface UPG presents to AI agents is uniform with the surfaces presented by every other MCP server the agent already knows how to use. From the agent's point of view, UPG is one more tool it can call, distinguishable by what it operates on rather than by how it is invoked.

The trade is acceptance. By building on MCP rather than a proprietary API, UPG inherits the protocol's reach and its constraints. If MCP changes, UPG follows. If an agent cannot speak MCP, it cannot speak UPG without an adapter. For the current AI-agent landscape, that trade is clearly the right direction: MCP is becoming the default way agents reach out into the world, and UPG is designed to be reachable.

Every discipline that contributes to product creation has its own frameworks, and every framework has its own vocabulary. Product management uses Opportunity Solution Trees, Jobs-to-be-Done, Lean Canvas, and the Business Model Canvas. Design uses empathy maps, user journey maps, and design-thinking stages. Engineering uses domain-driven design, the C4 model, and architecture decision records. Growth uses funnels, loops, and aha-moment frameworks. Each framework is a trusted method for thinking about part of the product, and each brings real clarity within its own domain.

Frameworks collide when they describe the same thing. A Pain Point in Lean Canvas is a Need in Jobs-to-be-Done is a Frustration in an empathy map is an Unmet Need in a user research report. A Feature in Jira is a Solution in an Opportunity Solution Tree is a Capability in a capability map is a Service in a domain-driven design diagram. The concepts are shared across disciplines. The labels are not.

A cross-discipline map makes the collisions visible. The following table shows a handful of recurring concepts, the names they travel under across product management, design, engineering, and growth, and the canonical UPG type each one maps to:

One response to these collisions is to give each framework its own schema and translate between them as needed. That is essentially the practice today, and it is why moving between tools costs so much human-mediated translation: a designer describing a Frustration and a product manager describing a Pain Point are often looking at the same thing without realising it.

UPG's approach is to treat frameworks as view definitions over a canonical graph. The underlying data is framework-agnostic: whatever the practitioner's framework calls it, the entity lands in the graph as a need with a declared valence (pain, gap, or constraint), or as a feature regardless of whether a Lean Canvas view calls it a Solution. The presentation is framework-fluent: the same need with valence: pain renders as Pain Point in a Lean Canvas view, as Frustration in an empathy-map view, and as Friction in a funnel view. A designer and a product manager applying different frameworks see vocabulary that fits their training, and the graph stays coherent underneath.

This is the move that lets a single UPG describe a product across all the disciplines that touch it. The graph is what a product is. The frameworks are how different people choose to read it. The two are not in tension; they are layered.

A concrete example makes the mechanism explicit. The Business Model Canvas (Osterwalder, 2010) defines nine building blocks including Customer Segments, Value Propositions, Channels, and Revenue Streams. In a traditional tool the canvas is an artefact, and the items on it exist inside the artefact. In UPG there is no BMC artefact. The entity types already exist in the graph (value_proposition, revenue_stream, cost_structure, partnership, market_segment). The BMC is a declarative definition, a JSON object whose slots select a subset of those types and arrange them in nine zones. The Lean Canvas is a different definition selecting a partially overlapping subset (including need displayed as Problem). The Opportunity Solution Tree is yet another, arranging outcome, opportunity, solution, experiment, and assumption as a tree rather than a grid. The same value_proposition node appears in every framework view that selects it; editing it in one view edits the underlying entity everywhere. Framework choice becomes a presentation-layer question rather than a data-modelling one, and a team that adopts Lean Canvas for two years and wants to move to Jobs-to-be-Done only needs to change their framework view; the data is untouched.

The mechanism is shown below. Three frameworks (BMC, Lean Canvas, and Opportunity Solution Tree) each select a different subset of UPG entity types and render them under framework-specific labels. The underlying entities are shared; only the view definition changes.

flowchart TD
  vp["<b>value_proposition</b>\n(in the graph)"]
  need["<b>need</b>\n(in the graph)"]
  opportunity["<b>opportunity</b>\n(in the graph)"]

  subgraph bmc["Business Model Canvas"]
    bmc_vp["Value Proposition"] 
  end
  subgraph lc["Lean Canvas"]
    lc_vp["Unique Value\nProposition"]
    lc_need["Problem"]
  end
  subgraph ost["Opportunity Solution Tree"]
    ost_opp["Opportunity"]
    ost_need["Opportunity (need)"]
  end

  vp --> bmc_vp
  vp --> lc_vp
  need --> lc_need
  need --> ost_need
  opportunity --> ost_opp

The same value_proposition node appears in the BMC view as Value Proposition and in the Lean Canvas as Unique Value Proposition. The same need node appears as Problem in Lean Canvas and Opportunity (need) in OST. Editing the entity in any view edits the single underlying record. Framework choice becomes a presentation-layer question rather than a data-modelling one.

Running a framework: the exercise model. A view definition says how to read the graph; many frameworks also evaluate it, and a RICE pass or a MoSCoW sort produces a result that has to live somewhere. UPG puts it on a relationship, not on the entity. Running a framework over a set of entities creates a framework_exercise node, one named pass (a Q3 prioritisation, a canvas for one segment), with a framework_exercise_includes_node edge to each entity it covers. The per-entity result rides that edge: a MoSCoW bucket, a RICE score, a Kano class, and the slot role the entity plays in the run. Because the value sits on the relationship, the entity stays what it is. A feature carries no scoring fields of its own, the same feature can be a must in one exercise and a could in another without collision, any entity type can be scored rather than only feature, and a re-run never overwrites the last one. Scoring is thus the inverse of presentation: a view reads many frameworks off one entity, while an exercise records one framework's reading of many entities, each on its own edge. The score is computed by the framework's scoring_method (Appendix H), evaluated at read time and never persisted to the node.

The full UPGFramework type schema, the scoring_method and exercise model, and the complete Business Model Canvas definition as worked example live in Appendix H.

UPG was designed against six goals. The first four describe what the graph should be; the last two describe how it survives time and how it meets the world.

1. Legible to humans and AI agents. The same choices (self-explanatory names, verb-paired edges, inline property schemas) serve both audiences without translation. A practitioner encountering job for the first time needs no glossary; an agent producing a hypothesis from conversation knows the expected fields and follow-on relationships without being told.

2. Framework-neutral and process-neutral. No single framework is privileged in the data layer. Jobs-to-be-Done, Opportunity Solution Trees, Lean Canvas, and the Business Model Canvas are views over the same typed entities, never competing schemas (§2.5). The same neutrality applies to process: the graph does not require Dual-Track Agile, Lean Startup, or any specific methodology. The layered architecture (§3.2) keeps declarative structure in Layers 1–4 and procedural guidance in Layer 5, so teams can adopt the data model without committing to a playbook, or run playbooks without giving up portability.

3. Portable (§1.3). The .upg file is the unit of portability; it is JSON, git-friendly, and readable by any compatible tool.

4. Incrementally adoptable. A useful graph can begin with three entities. Only id, type, and title are required on any node; the full property schema is available but never demanded. Coverage grows as the team's thinking grows, not the other way around.

5. Structurally durable across schema evolution. Entity types carry immutable identifiers (type_id) that survive renames, merges, and deprecations. When pain_point was merged into need with a valence: pain property, the old type_id was preserved so existing .upg files auto-migrate on load without data loss. Names belong to humans; type_id values belong to the wire format. Lifecycle transitions, deprecations, and framework additions do not invalidate the graphs already in circulation.

6. Enactable through playbooks and approaches, not prescribed by them. The declarative layers say what a graph is; Layer 5 (§3.7) says what an agent or practitioner can do with it. Playbooks provide region-anchored creation sequences: ordered guides for building out a domain of the graph. Approaches provide cross-cutting orientations: cognitive engagement modes that frame how to work with whatever already exists. A team using UPG without any playbooks or approaches still has a valid, compounding graph. Playbooks and approaches are procedural scaffolding that reads and writes the same underlying structure; they do not alter it.

Every design decision later in this section can be traced back to one of these six. Where a decision serves more than one goal, the priority order above decides which wins on trade-off.

The six goals from §3.1 become concrete first in how the specification is organised. UPG is split into five layers. Layers 1 through 4 are declarative: they describe what a graph is. Layer 5 is procedural: it describes what to do with one. Every layer depends only on the layers below it, never sideways and never upward. The result is a substrate whose foundation cannot be destabilised by changes at the surface.

flowchart BT
  subgraph L1["Layer 1: Foundation"]
    catalog["catalog\nWhat entities and edges exist"]
    shapes["shapes\nStructural primitives: node, edge, document"]
    registry["registry\nStable identifiers, maturity, domain"]
    catalog --> shapes --> registry
  end
  subgraph L2["Layer 2: Grammar"]
    grammar["grammar\nHierarchy rules · Lifecycle phases · Migrations · Validation"]
  end
  subgraph L3["Layer 3: Properties"]
    properties["properties\nTyped field schemas per entity type\n(324 types across 37 domains)"]
  end
  subgraph L4["Layer 4: Output  ·  read-time only, never persisted"]
    presentation["presentation\nLabels · Role-based lenses · Domain rings"]
    intelligence["intelligence\nBenchmarks · Anti-patterns · Domain guides"]
    frameworks["frameworks\n53 canonical framework definitions"]
    regions["regions\n11 super-domain rollups"]
  end
  subgraph L5["Layer 5: Procedural  ·  read-time only, never persisted"]
    playbooks["playbooks\n13 region-anchored creation sequences"]
    approaches["approaches\n5 cross-cutting orientations\nplan · inspect · prioritise · trace · reflect"]
  end
  L1 --> L2 --> L3 --> L4 --> L5

Layer 1 (Foundation) names what exists and what shape it takes: the catalog of entity and edge types, the shape interfaces every node and edge implement, and the registry that assigns each type a stable identifier, a maturity, and a domain. Layer 2 (Grammar) encodes what is allowed: hierarchy rules, lifecycle phases, migrations, and the validation routines tools import to check structural legality. Layer 3 (Properties) attaches typed field interfaces to each type (what a persona carries, what a hypothesis carries) and stays narrow on purpose so that framework-specific fields stay in Layer 4. Layer 4 (Output) holds the four read-time modules: presentation (labels, lenses, rings), intelligence (benchmarks, anti-patterns, domain guides), frameworks (RICE, Kano, BMC, OST as canvas view definitions over canonical types), and regions (the eleven super-domain rollups, §3.3). Layer 5 (Playbooks and Approaches) is the procedural layer: UPGPlaybook records carry region-anchored creation sequences, UPGApproach records carry cross-cutting cognitive orientations (Plan, Inspect, Prioritise, Trace, Reflect). §3.7 develops Layer 5 in detail; Appendix A walks every module.

The critical design decision. The .upg file contains Layers 1 through 3 only. Labels, lenses, benchmarks, frameworks, regions, playbooks, and approaches are never persisted to the file; they are applied at read time, recomputed at will, and replaceable without migration. The same graph data can be rendered through the Product lens or the Engineering lens, scored under RICE or Kano, grouped by ring or by region, and guided by a users-and-needs playbook or a discovery-validation playbook, all without touching what is stored. Storage stays narrow so the graph survives the evolution of everything above it.

Per-module detail, import graph, and representative benchmark, region, playbook, and approach records: Appendix A.

The atomic domains named in the registry are the graph's subject headings: user, strategy, discovery, engineering, growth, and so on. UPG carries two groupings over that set, both at Layer 4. The ring model arranges the domains as concentric rings radiating outward from the product nucleus, with maturity over time as its axis. The region model rolls the domains up into eleven super-domains, with coherence across space as its axis. When to reach for which: rings answer which stage is this product at? (used by intelligence-module benchmarks that vary by lifecycle stage); regions answer which area of work is this? (used by playbooks, the plan and inspect approaches, and starter templates). Neither is persisted; both are computed at read time from the same atomic-domain assignments. A competitor, for instance, projects into Ring 1 (Understand) and Region 4 (Market & Competitive) from a single market_intelligence assignment, without either grouping being stored.

The ring model

Seven rings radiate outward from the product nucleus, each holding the domains that answer one question.

Most products activate rings inside-out as they mature. A concept-stage product holds entities in Rings 0 through 2; a growth-stage product activates Rings 3 through 5; a mature organisation reaches into all seven. The intelligence module uses this progression to set healthy entity-count ranges per type per lifecycle stage and surfaces structural observations when the graph diverges from them.

The region model

Eleven regions group the atomic domains into super-domains, each a coherent area of product work.

Each region carries four defining pieces: a set of composed atomic domains, an anchor entity (the type that carries the region's design problem most sharply), a shape archetype (cascade, convergent, tributary, dag, multi-hub, event-driven, among others), and boundary edges fixing how the region connects to its neighbours.

The region is the primary unit of product work in UPG. When a product team asks "what should we think about next?", the answer is almost always a region ("we need to think more about the business model" or "our discovery region is thin.") Regions are what playbooks (§3.7) bootstrap, what the plan and inspect approaches (§3.7) operate over, and what the intelligence module uses to scope its coverage analysis. The region is also the unit teams tend to specialise around: a designer primarily works in Region 5, an engineer in Region 7, a growth marketer in Region 8. Role-based lenses (defined in §3.9) filter which regions dominate a given view, but the regions themselves are always present in the graph.

The anchor entity is not just a label. Each anchor is the entity type where its region's central question concentrates. objective anchors Strategy & Outcomes because the accountability question of strategy (is this objective being met?) resolves through an objective node. persona anchors Users & Needs because every cross-domain edge that describes a user (from competitive intelligence, from research, from feedback) eventually traces back to a persona. feature anchors Product & Delivery because the shipped unit of product value is a feature regardless of whether it came from a research-backed opportunity or a customer request.

Shape archetypes describe a region's topology. The shape describes the dominant topology of the region's internal edges, how entities within the region connect to each other. The shape tells an agent (or a practitioner) how to navigate the region: whether to start at the root and flow down, start at the hub and traverse outward, or start anywhere and follow the loop. Ten archetypes appear across the eleven regions: cascade (Strategy & Outcomes), convergent (Users & Needs), directed-cyclic (Discovery), tributary (Market & Competitive), multi-hierarchy (Experience, Design & Brand), work-breakdown (Product & Delivery), dag (Engineering & Platform), multi-hub (Business, GTM & Growth), event-driven (Operations & Quality), and polymorphic-target (Analytics & Data, Foundations). Full per-region patterns with mermaid diagrams: Appendix J.

Boundary edges are the graph's joints. Every boundary edge is a registered cross-domain edge type in the catalog. The seam between Region 3 (Discovery) and Region 6 (Product & Delivery) is crossed by learning_informs_feature (with feature_request_creates_opportunity running the other way). The seam between Region 6 and Region 1 (Strategy) is crossed by feature_drives_key_result. The seam between Region 2 (Users) and Region 3 (Discovery) is crossed by persona_experiences_need and job_surfaces_need. Without these boundary edges, regions would be isolated silos. With them, the full product graph is one connected structure traversable from any starting point.

Full region records with entity rosters, shape archetypes, boundary-edge sets, and per-region profile notes: Appendix J.

Every entity in a UPG graph, whatever its type and whichever grouping it belongs to, carries the same structural base. Before the full schema, a concrete three-node example shows the essential idea: two entities connected by a typed, directed edge.

flowchart LR
  persona["<b>persona</b>\nFelix, solo builder"]
  job["<b>job</b>\nDecide which feature\nto ship before the holiday window"]
  need["<b>need</b>\nStop letting feedback volume\ndecide the roadmap"]
  persona -->|"<span class='mverb'>pursues</span>"| job
  job -->|"<span class='mverb'>surfaces</span>"| need

Each box is an entity: a typed, titled, structured record. Each arrow is an edge: a named, directed relationship. The two together form a traversable, queryable fragment of a product graph. The full schema that underpins this is:

Shape.

// UPG v0.2: packages/upg-spec/src/shapes/base-node.ts
interface UPGBaseNode {
  id: string                                // Unique identifier within the graph
  type: UPGEntityType                       // Canonical UPG entity type
  title: string                             // Human-readable title
  slug?: string                             // Stable handle for inline [[type:slug]] chips; unique within (product_id, type)
  aliases?: string[]                        // Past slug values, retained so renamed-slug chips still resolve
  description?: string                      // Optional narrative description
  tags?: string[]                           // Freeform tags for filtering and grouping
  status?: string                           // Current lifecycle phase
  source_id?: string                        // Original ID in the source tool
  source_type?: string                      // Original type name in the source tool
  mapping_confidence?: UPGMappingConfidence // 'high' | 'medium' | 'low' | 'manual'
  external_tool?: string                    // External tool holding the canonical artifact
  external_ref?: string                     // URI to the canonical artifact
  external_id?: string                      // Identifier in the external tool's system
  properties?: Record<string, unknown>      // Type-specific properties
}

Design decisions. Four choices are visible in this shape.

Source traceability. Every entity carries its origin: which tool it came from, what it was called there, where it lives externally, and how confident the type mapping is. An import — the agent applying the Linear recipe — records the Linear ID, the Linear type string, and a URL back to the issue, so round-trip export is lossless and the imported entity stays linked to its canonical artefact.

Mapping confidence is explicit, never silent. When a Notion page maps to UPG persona, the confidence level is recorded. high means unambiguous. medium means probable. low means speculative; human review is recommended. manual means a person made the call. Uncertainty is a first-class property of any imported entity.

Progressive structure. Only id, type, and title are required. A valid entity can be three fields. The full property schema for that type is available for deep modelling but never demanded. This supports a pattern observed in user sessions: people mention an entity in passing before they are ready to define it fully, and the format lets that first mention be captured immediately.

Wire-format stability. Every entity type carries an immutable identifier (e.g. type_id: "ent_016" for persona) that survives renames, merges, and deprecations. When pain_point was merged into need with a valence: 'pain' property, the type_id was preserved so existing .upg files auto-migrate on load without data loss. Names belong to humans; type_id values belong to the wire format. Full EntityTypeMeta interface with maturity lifecycle and worked rename example: Appendix B.

Implications. Taken together, these commitments let the specification evolve without breaking graphs in circulation. Imported entities stay linked to their origins, new fields attach through properties without touching the base, and any tool that can render one UPG entity can render any of them.

Entities alone describe a set. The graph emerges from the edges that connect them. Edges in UPG are typed, directed, and carry human-readable verbs in both directions; the edge instance is minimal, and the semantics live in a canonical catalog.

Shape.

// UPG v0.2: packages/upg-spec/src/shapes/edges.ts
interface UPGEdge {
  id: string                                // Unique identifier within the graph
  source: string                            // Source node ID
  target: string                            // Target node ID
  type: UPGEdgeType                         // Key into UPG_EDGE_CATALOG, e.g. 'persona_pursues_job'
  mapping_confidence?: UPGMappingConfidence // If this edge type was inferred during import
  properties?: Record<string, unknown>     // Edge-scoped payload, only on opt-in edge types
}

// UPG v0.2: packages/upg-spec/src/catalog/edge-catalog.ts
interface UPGEdgeDefinition {
  forward_verb: string                      // "source [forward_verb] target"
  reverse_verb: string                      // "target [reverse_verb] source"
  classification: 'hierarchy' | 'causal' | 'semantic' | 'cross-domain'
  source_type: string                       // Entity type permitted at the source
  target_type: string                       // Entity type permitted at the target
  carries_properties?: boolean              // Opt-in: may this edge carry a properties payload?
}

Every canonical edge type is registered once in UPG_EDGE_CATALOG. Three representative entries:

persona_pursues_job: {
  forward_verb: 'pursues',       reverse_verb: 'pursued_by',
  classification: 'semantic',
  source_type: 'persona',        target_type: 'job',
}

experiment_produces_learning: {
  forward_verb: 'produces',      reverse_verb: 'produced_by',
  classification: 'causal',
  source_type: 'experiment',     target_type: 'learning',
}

opportunity_addresses_need: {
  forward_verb: 'addresses',     reverse_verb: 'addressed_by',
  classification: 'cross-domain',
  source_type: 'opportunity',    target_type: 'need',
}

Design decisions. Four choices are visible in this shape.

Minimal instances, catalog-carried semantics. A plain edge instance on the wire is four fields plus an optional mapping confidence. Verb pair, classification, and endpoint types live in the catalog entry, not on the edge. This keeps graph files small and means a verb rename in the catalog does not require rewriting every edge that uses it. A deliberately small set of edge types opts into carrying a properties payload (the catalog entry sets carries_properties: true); the canonical case is framework_exercise_includes_node, which stores a framework's per-entity result on the relationship rather than on either endpoint, so the entities stay framework-agnostic (Appendix C, §2.5). The competitive feature_rivals_competitor_feature and the classification edges (competitor_classified_as_classification_value and its polymorphic sibling) likewise carry their assessment on the relationship; the classification edges additionally declare a typed property_schema (confidence on the confidence_5 scale, plus provenance) that validators range-check. Validators reject properties on any edge type that has not opted in.

Every edge reads in both directions. "Persona pursues job" reads naturally forward; "Job pursued by persona" reads naturally backward. The graph can be traversed and rendered from any entity as origin without the query engine having to invert a verb. This matters when an AI agent is asked "what is this job connected to?" and needs to describe incoming as well as outgoing edges in natural language.

Every edge has a classification. Four classifications cover the catalog:

Classification drives traversal strategy. A traceability query ("trace this feature back to user evidence") follows causal and cross-domain edges backward, never hierarchy edges. A scope query ("what does this feature area contain?") follows hierarchy edges downward only. Without classification, every query degenerates into a full-graph walk.

Every edge pins its endpoints. source_type and target_type fix which entity types may appear at each end. An invalid endpoint pairing is a structural error at validation time, not a mystery at read time. Full catalog excerpt across all four classifications: Appendix C.

Implications. A small, declarative edge catalog lets queries know which edges to follow for which question, lets tools describe any edge in natural language without per-edge code, and lets the catalog evolve (verb renames, new edge types, deprecations) without rewriting graphs in circulation.

Classification (§3.5) is what makes the graph traversable. A spine is a path along typed edges that answers one question: where does a feature come from, what is a metric actually measuring, which user problem is a design decision meant to solve. UPG carries many such spines, and each uses whichever classifications its question needs.

A small selection of spines visible in the v0.2 catalog:

• competitor → competitor_feature → feature traces competitive differentiation into shipped work.
• metric → key_result → objective → strategic_theme traces measurement back into strategy.
• design_token → design_component → screen → user_journey traces design primitives into user-visible flows.
• persona → job → need → opportunity → solution → hypothesis → experiment → learning → feature traces user needs into shipped features. This is the spine most often requested in user sessions, and the one walked through below.

What varies across spines is which edges each one follows and what question each one answers.

One spine, walked through. The discovery-to-delivery spine runs from persona to feature through discovery and experimentation. Every arrow is a typed edge in the catalog, with a classification (§3.5) and a verb pair:

flowchart TD
  persona[persona] -->|<span class="mverb">pursues</span><span class="mtype">semantic</span>| job[job]
  job -->|<span class="mverb">surfaces</span><span class="mtype">causal</span>| need[need]
  need -->|<span class="mverb">addressed by</span><span class="mtype">cross-domain</span>| opp[opportunity]
  opp -->|<span class="mverb">drives</span><span class="mtype">causal</span>| sol[solution]

flowchart TD
  hyp[hypothesis] -->|<span class="mverb">requires</span><span class="mtype">causal</span>| exp[experiment]
  exp -->|<span class="mverb">produces</span><span class="mtype">causal</span>| learn[learning]
  learn -->|<span class="mverb">informs</span><span class="mtype">cross-domain</span>| feat[feature]

The bridge is solution → proposes → hypothesis (left column ends, right column begins).

Read end to end:

Persona pursues job. Job surfaces need. Need addressed by opportunity. Opportunity drives solution. Solution proposes hypothesis. Hypothesis requires experiment. Experiment produces learning. Learning informs feature.

This spine walks causal and cross-domain edges only; hierarchy edges sit outside the traversal. The classification is what makes that distinction possible: the paths that carry why a feature exists look different in the catalog from the paths that carry where it lives.

A team can capture the chain in whatever order they happen to think about it. Start from a feature idea, from a user interview, or from a market opportunity; the spine is reconstructed from whichever connections are present.

Worked example. Felix runs Threadline, a meeting-notes tool that auto-extracts action items and tags each one to the attendees on the calendar invite. Four months post-launch on Product Hunt; around 200 weekly actives, 30 paying at $9/mo (around $270 MRR); week-4 retention sits at 18%. Three feature requests have stacked up: Slack integration (25 votes, the loudest), Calendar back-fill (12 votes, medium), Cross-meeting search (8 votes, the quietest). Felix has bandwidth for one before the holiday window. The decision the graph has to support is not which is most-requested, it is which one moves week-4 retention.

The discovery chain Felix captures runs from the persona that owns the decision through the learning that resolves it:

flowchart TD
  felix["<b>Felix, solo builder</b><span class='ntype'>persona</span>"]
  jobF["<b>Decide which feature to ship before the holiday window</b><span class='ntype'>job</span>"]
  needF["<b>Stop letting feedback volume decide the roadmap when volume and value are uncorrelated</b><span class='ntype'>need</span>"]
  oppF["<b>Cluster feedback by persona × retention bucket to surface the request that retained users actually pull</b><span class='ntype'>opportunity</span>"]
  solF["<b>Cluster the last six weeks of feedback by persona × job × retention bucket</b><span class='ntype'>solution</span>"]

  felix -->|<span class="mverb">pursues</span><span class="mtype">semantic</span>| jobF
  jobF -->|<span class="mverb">surfaces</span><span class="mtype">causal</span>| needF
  needF -->|<span class="mverb">addressed by</span><span class="mtype">cross-domain</span>| oppF
  oppF -->|<span class="mverb">drives</span><span class="mtype">causal</span>| solF

flowchart TD
  hypF["<b>One of the three requests is asked by retained week-8+ users at ≥3× the rate of churned users</b><span class='ntype'>hypothesis</span>"]
  expF["<b>Tag 60 feedback items in Linear by persona, job-pursued, and retention bucket; recompute volume table</b><span class='ntype'>experiment</span>"]
  learnF["<b>The loudest request is a churn-cohort projection; the quietest request is a retained-cohort pull</b><span class='ntype'>learning</span>"]
  featF["<b>Cross-meeting search</b><span class='ntype'>feature</span>"]

  hypF -->|<span class="mverb">requires</span><span class="mtype">causal</span>| expF
  expF -->|<span class="mverb">produces</span><span class="mtype">causal</span>| learnF
  learnF -->|<span class="mverb">informs</span><span class="mtype">cross-domain</span>| featF

The left column captures what Felix observed and proposed; the right column captures what the experiment showed and what shipped. The bridge between them is the edge solution → proposes → hypothesis.

Every link in this chain is a graph edge. The shipped feature (Cross-meeting search) has a typed provenance reachable with a single query, rather than one scattered across Slack threads, support tickets, and a Linear backlog. Run the same query on a graph without this chain and it returns nothing: the feature exists, but the reason for it has to be reconstructed from prose.

A second spine, in the same graph. The discovery spine alone does not show why the loudest request was not the right one. That answer lives in a parallel chain in the Customer Feedback domain, which the same graph also carries:

flowchart TD
  fbSlack["<b>Slack request verbatim: Team Lead, churned</b><span class='ntype'>customer_feedback</span>"]
  fbSearch["<b>Cross-meeting search request verbatim: IC Researcher, week-12 retained</b><span class='ntype'>customer_feedback</span>"]
  frSlack["<b>Slack integration: push action items to a #meetings channel</b><span class='ntype'>feature_request</span>"]
  frSearch["<b>Cross-meeting search: find decisions across past meetings</b><span class='ntype'>feature_request</span>"]
  segChurn["<b>Churned within 30 days</b><span class='ntype'>behavioral_segment</span>"]
  segActive["<b>Active week-8+</b><span class='ntype'>behavioral_segment</span>"]
  perTL["<b>Team Lead</b><span class='ntype'>persona</span>"]
  perIC["<b>IC Researcher</b><span class='ntype'>persona</span>"]
  churn["<b>Couldn't get team to adopt Threadline</b><span class='ntype'>churn_reason</span>"]

  fbSlack -->|<span class="mverb">becomes</span><span class="mtype">cross-domain</span>| frSlack
  fbSearch -->|<span class="mverb">becomes</span><span class="mtype">cross-domain</span>| frSearch
  frSlack -->|<span class="mverb">from</span><span class="mtype">cross-domain</span>| segChurn
  frSearch -->|<span class="mverb">from</span><span class="mtype">cross-domain</span>| segActive
  segChurn -->|<span class="mverb">maps to</span><span class="mtype">cross-domain</span>| perTL
  segActive -->|<span class="mverb">maps to</span><span class="mtype">cross-domain</span>| perIC
  fbSlack -->|<span class="mverb">reveals</span><span class="mtype">cross-domain</span>| churn

This is the traversal Felix's experiment ran: feature_request → from → behavioral_segment → maps_to → persona. The Slack request resolves to the Churned within 30 days segment, which maps to the Team Lead persona; the same edge type takes the Cross-meeting search request to the Active week-8+ segment and the IC Researcher persona. A parallel customer_feedback → reveals → churn_reason edge surfaces why the Slack signal is loud despite being a poor retention bet: it is a churn-cohort projection of the missing piece, not a retained-cohort pull. The graph compounds knowledge across two domains (Discovery and Customer Feedback), and the feature decision is the join.

Read end to end, the two spines answer two questions a flat ticket queue cannot answer in one query: what is the typed provenance of this shipped feature?, and what is the persona-and-retention shape of the cohort each request came from? Volume alone says ship Slack. The graph says ship Cross-meeting search.

Many spines, one mechanism. The discovery-to-delivery spine is one walk through the catalog. The metric-to-strategy, competitor-to-feature, and design-token-to-journey spines work the same way: typed edges, classification-driven traversal, verbalisable at read time. When entities expected along a spine are missing or disconnected, the intelligence module (§3.8) reports it.

Traceability (§3.6) describes how the graph is read. Layer 5 describes how it is produced and worked with, through two distinct primitives. A playbook runs in creation mode: it builds out a region of the graph. An approach runs in engagement mode: it frames how to work with what already exists. Playbooks compose ordered Step records; approaches are definition lookups that orient the LLM's engagement. The same graph is the subject of both; the modes are not interchangeable.

Playbooks

A playbook answers "I'm populating this region of the graph: what should I create, and in what order?" One canonical playbook exists per region; a region may also carry specialised playbooks for alternative entry paths. The catalog holds 13 playbooks across 11 regions (11 canonical, 2 specialised).

// UPG v0.3: packages/upg-spec/src/playbooks/types.ts
interface UPGPlaybook {
  id: string             // namespace-prefixed: 'playbook:<region>[-variant]'
  name: string           // Human-readable name
  version: string        // Semver
  description: string    // One-sentence description
  region: UPGRegionId    // REQUIRED: the region this playbook anchors
  is_canonical?: boolean // True for the one canonical playbook per region
  framework_id?: string  // Set on framework-anchored specialised playbooks
  target_anchor_entity?: string  // The entity this playbook produces
  creation_sequence: readonly Step[]  // Ordered creation steps
}

Design decisions.

Region-scoped, not domain-scoped. Playbooks anchor to a region (one of the eleven super-domains: Users & Needs, Discovery, Business & GTM, etc.) rather than an atomic domain. A region composes several atomic domains; the playbook's creation sequence spans them in the order that makes sense for the region's anchor entity. The Users & Needs playbook, for instance, walks personas, then jobs, then needs, then opportunities: four domains in one coherent sequence.

One canonical per region, W1 invariant. Every region has exactly one canonical playbook. This is an audited constraint, not a type-system guarantee: a CI script enforces it. Specialised playbooks (framework-anchored variants) exist alongside the canonical one; they do not replace it.

Steps are discriminated. Four step kinds compose the creation sequence: domain_guide defers to the Intelligence module's usage guide for a named domain; framework applies a named framework from the Frameworks module (Layer 4); entity_sequence fixes an ordered list of entity types to capture; sub_sequence nests another playbook, so longer journeys can reuse shorter ones without duplicating steps.

Structure shared, experience per surface. One playbook definition is authored once in @unified-product-graph/core; each surface (a terminal client, an IDE extension, a browser canvas) registers its own PlaybookBinding. The binding decides how steps render: it cannot change the sequence, the step kinds, or the prompts. The same playbook runs in a terminal and in a visual canvas without re-authoring.

Approaches

An approach is a cross-cutting cognitive orientation: the path of arrival to a region. Like an aircraft's final approach to a runway, it describes the heading and angle of engagement with the terrain, determining which aspects of the graph come into focus and how to move through them.

Five canonical approaches cover the full space of how a practitioner or AI agent can engage with a product graph. The catalog is closed at v0.8.0; adding a sixth would be a coordinated breaking change.

// UPG v0.3, packages/upg-spec/src/approaches/types.ts
type UPGApproachId = 'plan' | 'inspect' | 'prioritise' | 'trace' | 'reflect'

interface UPGApproach {
  id: UPGApproachId          // bare verb, matches the MCP tool name
  label: string              // 'Plan', 'Inspect', etc.
  description: string        // Cartographic framing of the engagement
  question_answered: string  // The user intent in plain language
  signature_hint: string     // '(args) → return-shape' (v0.3.x execution contract)
  framework_id_examples: string[]  // Named techniques that live inside this approach
}

Design decisions.

Each approach carries named techniques. The framework_id_examples field lists the frameworks that live inside that approach. The five approaches are the engagement categories; the frameworks are the named techniques within each category. Five Whys, Pre-mortem, Red Team, Devil's Advocate, and Second-order Thinking are techniques inside reflect. RICE, ICE, Kano, and Cost of Delay are techniques inside prioritise. The approach names the path; the framework names the instrument.

Five approaches, five bare-verb MCP tools. Each approach is directly invocable via its id as an MCP tool: plan, inspect, prioritise, trace, reflect. Each tool executes a structured pass over the live graph and returns computed results — plan returns the region's missing entities and a coverage score; inspect returns typed violations with fix hints — and the AI agent interprets and acts on what comes back. The approach definitions, with full signatures, are in Appendix K. (Earlier releases shipped these as definition lookups; execution landed as the runtime matured.)

Traceability (§3.6) shows what chains exist; playbooks (§3.7) guide building them. The intelligence module (Layer 4) reports whether what has been built is structurally healthy, and where it is not.

The intelligence module has three components.

Domain usage guides. One guide per atomic domain. Each guide is a declarative record specifying the canonical creation sequence for that domain: the entity types to create, the order to create them in, the properties most important to fill, and the conditions under which creation of one type should trigger creation of another. Domain usage guides are what playbooks defer to when a step has kind: 'domain_guide': the guide is the intelligence behind the playbook step. An agent calling get_catalog_entry({ kind: 'domain_guide', id: 'discovery' }) gets a structured record it can use to drive a creation session without relying on in-context instructions.

Benchmarks. The intelligence module carries three kinds of declarative benchmark, each evaluated at the relevant product lifecycle stage:

Benchmarks are what get_graph_digest uses to populate benchmark_hits: the digest is the spec's self-measurement at read time, grounded in the ontology's own expectations rather than in an external heuristic.

Anti-patterns. The intelligence module carries a catalog of named anti-patterns, each with a machine-checkable structured_condition (detection is data, not code), a severity (high, medium, or low), the lifecycle stages it applies to, a why_it_matters rationale, a remediation hint, and a source attribution. They detect broken or missing narrative chains, the failure mode the spec exists to prevent. Anti-patterns are what the inspect approach surfaces when it audits a graph. Four representative entries:

validate_graph runs all anti-pattern checks across the whole graph and returns a structured violation list.

Absence as a detectable signal. Most detectors ask whether a relationship exists: a persona with no job, a hypothesis with no experiment. The fourth entry above asks a different question, and it is worth stating why the question is different in kind. A surface is a place inside the interface (a pane, a slot, a gutter, an action bar) that features compete to occupy; feature_occupies_surface is its guest list, and arbitration_rule records who wins when the guest list exceeds what the place can hold. An unfilled arbitration_rule on a contested place does not mean the contest never happened. It means the settlement was reached in conversation and never written down, so it will be re-argued at the next feature — a cost paid in repeated decisions rather than in a visible defect.

Expressing that detector required extending the condition language rather than composing existing checks. The entity filter is value-keyed, and a value index can only enumerate values that exist; a condition keyed on an unfilled field could never fire. EntityCheck therefore gained a presence predicate that counts entities of a type by whether a named property is set at all. The generalisation is the point: where a property carries a decision rather than a description, its absence is itself the finding, and an ontology that can only detect missing edges will never see it.

Absence is not always an omission. Deploying that detector against a real thirty-surface product exposed the limit of the idea. Some places hold many occupants and no arbitration rule by design: where each occupant wraps the next by invoking a render-default callback it was handed, nothing is suppressed and nothing needs to win. Fourteen of the thirty surfaces had that shape, and the detector could not be quieted by modelling them correctly, because absence alone cannot distinguish a decision nobody made from a decision the composition already answers. A check that correct modelling cannot silence stops being read.

The repair generalises past this one case. A presence predicate may now name a declared exemption: count the entities missing this property except those declaring that one. The exemption is earned rather than assumed, so a surface that says nothing keeps firing and silence has to be claimed deliberately, which preserves the default suspicion the detector depends on. A second property records the state of the arbitration answer, separating a rule enforced in code but never transcribed (minutes of work) from one nobody ever decided (a design meeting) from a place that is safe only because its occupants happen not to collide, which reads as settled from outside and fails the first time an occupant is added. That third state is the one prose can hide, so it fires on its own even where a rule is written. Declaring the healthy state does not by itself silence anything, which keeps the vocabulary from degrading into the placeholder text the property it describes was written to forbid.

The intelligence module is the difference between a graph that is a passive record and one that surfaces where it is incomplete. A practitioner can ask "what should I do next?" and receive a structured answer grounded in the ontology's canonical expectations: not a recommendation from a language model, but a comparison of what exists in the graph against what the spec says should exist.

Full benchmark definitions and anti-pattern catalog: Appendix E (the list_catalog facet over benchmarks and anti_patterns, plus validate_graph tool descriptions).

The same graph can be read from multiple perspectives without changing what is stored. A lens is a named projection over the entity catalog: it selects a subset of domains, relabels entity types with role-appropriate vocabulary, and orders the regions that matter most to that role.

The four above are illustrative; the canonical set runs to nine: product, design, engineering, growth, business, research, marketing, competitive, and full. The competitive lens is the narrowest of all: it foregrounds the single market_intelligence domain, so a product marketer sees only rivals, their offerings, the dated moves they make (§3.11), and where the product leads or trails.

Lenses are what get_product_context uses to scope its digest and what update_session_context stores as the active lens for an ongoing session. The other presentation-layer outputs, framework labels (§2.5, Appendix M) and the domain ring visualisation (§3.3), sit alongside lenses at the same Layer 4 surface.

A single .upg file holds one product, and §3.1 through §3.9 described how knowledge compounds inside it. But few products exist alone. A company runs several at once; a platform hosts the products built on top of it; a company-level north-star metric is fed by the KPIs of every product beneath it; the same persona buys one product and uses another. The knowledge that compounds within a product should also compound across a portfolio of them. UPG extends the same layered model to that case rather than inventing a second one.

Three tiers, one ontology. A portfolio is organised into three conceptual tiers, and only the middle tier introduces new vocabulary.

1. Product graphs are the instances. Each is an ordinary single-product graph, exactly as described above, stored in its own file and valid on its own. Nothing about a product graph changes when it joins a portfolio.
2. The portfolio tier is the organisational structure that holds them. An organization invests via one or more portfolio nodes, which contain product nodes, optionally grouped into nestable product_area nodes. These Nucleus-ring types and their hierarchy edges (organization_invests_via_portfolio, portfolio_contains_product, product_area_contains_product, and the nesting variants) are the only structure the tier adds. It answers what exists, and how is it grouped?
3. The registry is the shared-vocabulary tier: a portfolio-level home for the entities many products refer to. A canonical persona, a company metric, a shared competitor, a foundational specification: defined once, and pointed at from every product that instantiates it. It answers what do these products have in common?

flowchart TD
  org["organization"] --> port["portfolio"]
  port --> areaA["product_area"]
  areaA --> prodA["product A"]
  areaA --> prodB["product B"]
  port --> prodC["product C"]
  subgraph registry [registry: shared vocabulary]
    canon["canonical persona ★"]
    spec["specification"]
  end
  prodA -.->|"instance_of"| canon
  prodB -.->|"instance_of"| canon
  prodA -.->|"implements"| spec
  prodC -.->|"implements"| spec

Cross-product edges are the seams. Within a product, typed edges connect typed nodes. Across products, a separate closed union of sixty-nine cross-product edge types connects nodes that live in different files. Each references its endpoints by qualified id ({product_id}/{node_id}, or registry/{node_id} for a registry target), reusing the cross-file reference mechanism the file format already carries. They cluster into a few families, each answering a question a single product graph cannot:

The registry turns convention into structure. Without a registry, a shared persona is copied into every product graph, and keeping the copies aligned is a convention enforced by discipline rather than by the spec. The registry makes it an architecture. The canonical persona is a normal persona node that happens to live in the registry tier, and each product's local persona links to it with an instance_of edge. Canonical-ness is conferred by where the node lives, not by a new type or a flag, so the same mechanism serves personas, metrics, competitors, and market segments without per-type machinery. The payoff is rollup (every instance of the Developer persona, and the per-product jobs each one pursues), diff, and drift detection: a portfolio_validate pass flags an instance whose title or shape has strayed from its canonical, while distinguishing genuine drift from a sanctioned product-local alias carried on the edge itself. instance_of and the symmetric shares_* edges coexist; they answer different questions (canonical-to-instance versus peer-to-peer), and neither deprecates the other.

Foundations: the deepest shared layer. The most invisible cross-product structure is the foundational technology many products are built on: a query language, a content format, a wire protocol. UPG models these as two Foundations-region entity types. A specification is the governed rulebook a product implements, exposes, or conforms to; a primitive is a compositional unit a specification defines. Registered once and referenced by every product that uses them, they make the deepest layer of a portfolio's moat visible as first-class objects instead of a string repeated across a dozen graphs. Foundations is the eleventh canonical region (§3.3, Appendix J), anchored on specification, with a polymorphic-target shape: many products point inward at the same small set of shared specifications.

Portfolio-scoped reads. The single-product read primitives have multi-product counterparts that fan out across every product in scope and roll the results up in one call: portfolio_query (the multi-product query), portfolio_digest (the multi-product get_graph_digest), and portfolio_validate (the multi-product validate_graph, and the home of registry drift detection). A portfolio can therefore answer questions no single product graph holds: which company objective has no product driving it? which products share a persona about to be repositioned? which products implement a specification about to be versioned? Each is a typed traversal of one connected structure rather than a manual reconciliation across files.

A single graph makes a product's knowledge compound across sessions. The portfolio tier makes it compound across products: a persona learned once is available everywhere, a metric defined once rolls up automatically, and a foundational primitive named once is visible to every product built on it. The mechanics of the portfolio document that serialises all of this are in §4.7; its full shape and a worked example are in Appendix O.

The portfolio tier so far has modelled what an organisation owns. A product creator also has to watch what it does not own. UPG extends the portfolio tier to the competitive landscape.

A watched member kind marks a graph the company monitors rather than ships, so a rival can sit in the same portfolio as the products it competes with without dragging their health scores. A competitor_signal records a dated competitor move, mapping it onto an owned feature or a surfaced opportunity. A parity edge (feature_rivals_competitor_feature) records where a product trails, and a classify edge positions a rival on canonical registry axes such as AI maturity and go-to-market. Both edge families carry validated, typed properties under the same property_schema mechanism that governs node properties (P17, one of the twenty invariants defined in §5), so where does a product trail? and what kind of competitor is this? become typed traversals over the competitive lens (§3.9), comparable across the organisation rather than re-invented per analyst.

The cross-graph edges connect a watched graph and the registry back to an owned product:

flowchart LR
  subgraph watched [watched graph]
    comp["competitor"]
    sig["competitor_signal"]
    cfeat["competitor feature"]
    comp -->|"emits"| sig
  end
  subgraph owned [owned product]
    feat["feature"]
    opp["opportunity"]
  end
  subgraph registry [registry]
    axis["classification_axis"]
    val["classification_value"]
    axis --> val
  end
  sig -.->|"maps_to_feature"| feat
  sig -.->|"surfaces_opportunity"| opp
  feat -.->|"rivals"| cfeat
  comp -.->|"classified_as"| val

The member kinds, the signal, parity, classification, and edge-property mechanics, and the portfolio read surface are detailed in Appendix P.

The portfolio tier moves graphs between products and into a shared registry (§3.10), and §3.11 added watched graphs from outside the company. Everything those mechanisms carry travels through the same export, snapshot, push, and cross-product sync, which raises a question the single-file case could defer: what belongs in a graph that travels, and what does not. A product's modelling knowledge, its personas, decisions, features, and the typed relationships between them, is what should travel. A person's email address, a company's tax id, an app-session id, a live vendor invoice figure, or an environment-specific storage URI is not. Each belongs to the application and tenancy layer that hosts a graph, not to the format that carries it. Put those in the body and the specification exports private and soon-stale data to everyone the graph is shared with.

The principle. The portable graph holds modelling knowledge, not PII, account credentials, registry filings, app-session ids, or environment-specific infrastructure pointers. Five classes sit outside the boundary, each with a place it belongs instead:

The boundary is not a blanket ban on URLs or identifiers. Where the value is the entity's own content or a stable public reference, it stays: a design_token's value, a brand_colour's hex, a specification's canonical spec_url, a vulnerability's CVE id, a screen's route. The test is what the value points at. A stable standard reference or the entity's own content stays; a per-tenant secret, a contact detail, or an environment-specific pointer goes.

A property-modifier family makes the line enforceable. Three values on a property's modifier field (@derived, @snapshot, @volatile in shorthand) mark a property whose value is not authored and stable, so tooling, exports, and validators treat it correctly rather than trusting a naming convention:

• @derived: computed from edges or children at read time, never hand-authored. A stored value that disagrees with the graph is stale by definition and recomputed. The count caches (feature_count, a workflow's step_count) are @derived, kept as a cache and recomputed on read rather than removed.
• @snapshot: a stale-stamped cache of a live reading, paired with a *_as_of timestamp. A definition entity may hold live state only as a snapshot; the live series itself lives on a metric node.
• @volatile: an environment-specific pointer (URL, path, id) that may rot or be stripped on export. It keeps a pointer usable while marking it non-portable, so relocating an out-of-bounds field does not force a choice between losing the link and leaking it.

The same family encodes the governance line the boundary rests on: definition entities describe what is designed or configured; live readings, rolling metrics, and execution outcomes live on metric nodes by edge, or on dedicated record entities such as an eval_run, a test_result, or a workflow_run. A definition entity carrying a raw rate or a current value is what @snapshot flags.

The guardrail suite holds the boundary over time. Each gain is frozen as a baseline a later change cannot grow past: no property re-encodes its entity's own lifecycle phases as a *_status enum (the phase lives on the base node's status); no numeric aggregate is stored where it should be @derived; no live reading sits un-snapshotted on a definition entity; and a property marked removed in a past version is gone, not left as a deprecated ghost. Every subsequent version inherits these baselines, so the boundary holds as the specification grows.

§3 described the five layers of the Unified Product Graph (UPG) specification. §4 describes what each of those layers looks like on disk and in flight: the file format that serialises Layers 1 through 3, the MCP server that reads and writes it, the import-recipe catalog that brings existing corpora in, the playbook and approach runtime that implements Layer 5, and the hybrid markdown surface that lets prose and graph coexist in one file.

The file format has to be readable by hand, diffable in version control, and producible by a language model without a framework to consult. A single JSON document satisfies all three.

A .upg file is a JSON document (MIME type application/vnd.upg+json). A minimal but complete example, a one-product graph with a persona, a job, a need, and two typed edges connecting them, drawn from the Threadline reference graph:

{
  "$upg": {
    "format_version": "1.0.0",
    "spec_version": "0.35.0",
    "product": {
      "id": "n_5KO9z8qsX-pYKVIb",
      "title": "Threadline",
      "stage": "growth"
    },
    "counts": {
      "nodes": 3,
      "edges": 2
    },
    "provenance": {
      "tool": "upg-mcp-server",
      "tool_version": "0.35.0",
      "exported_at": "2026-06-18T12:00:00Z"
    },
    "integrity": {
      "algorithm": "sha256-128",
      "body": "098dbda4962d49fa9ba4d1206f3f69ac"
    }
  },
  "product": {
    "id": "n_5KO9z8qsX-pYKVIb",
    "title": "Threadline",
    "stage": "growth"
  },
  "nodes": [
    {
      "id": "n_XqLDdZOoqrmufgjd",
      "type": "job",
      "title": "Decide which feature to ship before the holiday window",
      "properties": {
        "importance": { "label": "Critical", "value": 5 },
        "job_type": "functional",
        "statement": "Felix has bandwidth for one feature before the December slowdown. Three requests are stacked. The job is to pick the one that most moves the metric that matters: week-4 retention, not the loudest one."
      }
    },
    {
      "id": "n_8B1SNCNbDSs4O8Qr",
      "type": "need",
      "title": "Stop letting feedback volume decide the roadmap when volume and value are uncorrelated",
      "status": "raw",
      "properties": {
        "severity": { "label": "Severe", "value": 4 },
        "valence": "pain"
      }
    },
    {
      "id": "n_SuIk0TASeSWJRFaf",
      "type": "persona",
      "title": "Felix, solo builder",
      "description": "Builds Threadline evenings on top of a day job. Ships every two weeks. Four months post-launch. Faces a recurring 'which request next?' decision and has shipped two of the last four features chasing loudest-voice asks, both shipped to crickets.",
      "properties": {
        "experience_level": "intermediate",
        "is_primary": true
      }
    }
  ],
  "edges": [
    {
      "id": "edg_1",
      "source": "n_SuIk0TASeSWJRFaf",
      "target": "n_XqLDdZOoqrmufgjd",
      "type": "persona_pursues_job",
      "mapping_confidence": "high"
    },
    {
      "id": "edg_2",
      "source": "n_XqLDdZOoqrmufgjd",
      "target": "n_8B1SNCNbDSs4O8Qr",
      "type": "job_surfaces_need",
      "mapping_confidence": "high"
    }
  ]
}

A single leading $upg header carries everything a reader needs before it walks the graph: the serialisation format_version, the spec_version the data conforms to, a one-line product summary, entity and edge counts, write provenance, and an integrity checksum over the body. Below it, product, nodes, and edges hold the graph itself. Three nodes, two edges, enough structure to answer "which needs does this persona's job surface?" with a typed query. Every property carries its schema: valence is an enum, severity is an assessment with a qualitative label and a numeric value (P17). Every edge carries a typed relationship with a forward and reverse verb inherited from the catalog. The persona's is_primary: true flag establishes which persona is canonical for the product without requiring a prose convention. Node IDs are server-issued opaque identifiers that survive across sessions and tools (P3, P14). The nodes appear ordered by type then title, and object keys are sorted, because the file is written in canonical form (below): the same graph always serialises to the same bytes.

Five format decisions follow from the file needing to survive version control, tool changes, and schema evolution.

1. Git-friendly JSON. JSON, not a custom format or a binary encoding, so the file opens in any editor, reads into any language, and diffs in git. A product decision three months ago is a git blame away.
2. Canonical form. The same logical graph always serialises to byte-identical output, regardless of which tool wrote it. Object keys follow a fixed order, the node and edge collections are sorted by stable keys, encoding is pinned (UTF-8, two-space indent, LF), and volatile fields are kept out of the hashed body. The rules adapt RFC 8785 (the JSON Canonicalization Scheme) with two deliberate departures for human review: the output is pretty-printed rather than minified, and the set-like collections are sorted rather than left in write order. The payoff is that adding one edge produces a one-line diff instead of a reshuffled file, and a no-op re-save produces no diff at all. A reference formatter, upg fmt, rewrites any file to canonical form and upg fmt --check gates it in CI, exactly as gofmt or Prettier do for code. Appendix N gives the full specification.
3. A reserved $upg header and an explicit format_version. Metadata that used to sit as loose siblings of the data (version, provenance, integrity) is consolidated into one leading $upg object, so a reviewer reads what product, what version, how big, who last wrote it, and a content checksum before scrolling a single node. The on-disk format_version is distinct from spec_version: the serialisation can evolve independently of the ontology. Portfolio files use the same header with kind: "portfolio".
4. Integrity and migration on load. $upg.integrity.body is a SHA-256 checksum of the canonical body, truncated to 128 bits (labelled sha256-128), so it is stable across no-op re-exports and changes only when the graph changes. On load, tools verify it and, in the same step, auto-migrate deprecated types to their canonical replacements (for example, pain_point → need, Appendix G) and repair legacy serialisation drift such as double-encoded property values. Downstream tools only ever see current, well-formed types; corruption and structural drift are caught at the file boundary rather than deep in a traversal. A published JSON Schema (Draft 2020-12) lets any editor or CI step validate the structure independently.
5. Unknown-type preservation, and reads accept both envelopes. If a writer produces a node with a type not in the reader's spec version, the reader preserves the node unchanged rather than dropping it; a newer writer cannot break an older reader. In the same spirit, readers accept both the $upg envelope and the older flat layout, so adoption need not be instantaneous across a fleet of tools.

One product per file. The default unit is one product, keeping files scoped and shareable without leaking unrelated work. A portfolio document extends the same $upg-headed shape to multiple products with cross-product edges.

Serialisation scope. .upg carries Layers 1 through 3 (catalog, shapes, registry, grammar, properties). Layers 4 and 5 (presentation, intelligence, frameworks, regions, playbooks, approaches) are read-time concerns and are never written to the file. The same graph data can be rendered through any output module or guided by any playbook without round-tripping through the file format.

The file is the state. Every client (human editor, AI agent, or in-house tool) reaches into it through the same entry point: the UPG MCP server (@unified-product-graph/mcp-server). §2.4 introduced the Model Context Protocol; the reference server is its concrete implementation for UPG.

Architecture. The local MCP server runs as a subprocess of the AI client. All transport is stdio; the server never opens a network port.

flowchart TD
  client["<b>AI client</b><span class='nsub'>Claude Code · Cursor · VS Code</span><span class='nsub'>any MCP-capable client</span>"]
  server["<b>@unified-product-graph/mcp-server</b><span class='nsub'>Node.js subprocess</span><span class='nsub'>tool handlers · schema introspection</span><span class='nsub'>batch executor · integrity validation</span><span class='nsub'>auto-migration on load</span>"]
  upgfile["<b>.upg file (JSON)</b><span class='nsub'>single file, versionable in git</span>"]

  client -->|<span class="mverb">stdio</span><span class="mtype">JSON-RPC</span>| server
  server -->|<span class="mverb">read / write</span><span class="mtype">integrity check</span>| upgfile

The .upg file is the only persistent state the local server needs. No database, network connection, or separate cache is required, though any of those can be layered on top for teams that want them. Anyone who can run a Node.js subprocess and read a JSON file can run the UPG MCP server. A graph reachable only through one vendor's cloud service is bound to that vendor; the local server ensures the ontology can be adopted, forked, and audited without that binding.

Why MCP as the protocol. §2.4 made the load-bearing argument; the implementation choice follows directly. The major AI coding clients already speak MCP at connection time, so building on MCP is building on the layer the agents are already speaking.

Why not GraphQL. The comparison is natural: GraphQL and UPG MCP both carry a type system with relationships, both expose schema introspection, and both structure client-server interaction around a graph. The MCP design makes three moves GraphQL does not: agents reach for named tools rather than compose queries (no intermediate query language to write); introspection is a call-time safety rail (get_entity_schema answers "what would be valid here, right now?" before a write) rather than a build-time codegen input; and primitives like triage reads (get_graph_digest), typed session context, and diff-based collaboration have no GraphQL-native expression. GraphQL is a query language for data retrieval; UPG MCP is an invitation-driven protocol for agent-graph interaction, and the inversion matters for the agent-facing case.

Four moves beyond CRUD. The MCP server's AI-first shape reduces to four design moves, each of which Appendix E expands with tool-by-tool detail.

1. Introspection-first. get_entity_schema makes the ontology queryable at write time, so the same agent-side code works against any spec version without retraining. A call to get_entity_schema({ type: 'hypothesis' }) returns the valid parents, the typed property interface (we_believe, will_result_in, we_know_when, risk_if_wrong), the permitted outgoing edges (including hypothesis_tested_by_experiment), and the lifecycle phase model (untested → testing → resolved). The agent writes a create_node that conforms on the first attempt because the shape was queried rather than guessed.
2. Triage as a first-class read primitive. get_graph_digest answers where to focus rather than what data to fetch, distinct from the record-access reads (get_node, list_nodes, search_nodes) that serve retrieval.
3. Session context as a typed artefact. get_session_context and update_session_context carry working memory across conversations as structured data, not conversation history. This is the compounding property of §1.4 realised at the tool layer: a new conversation opens with get_product_context and inherits the active playbook step, the recent-change cursor, the active lens, and the open hypotheses.
4. Change-based collaboration. get_changes returns a diff since a sync point, and get_sync_state compares local and cloud heads. Two agents reconcile by diffing cursors rather than by acquiring locks, which makes long-running AI sessions compatible with concurrent edits.

Cloud variant. @unified-product-graph/cloud-server backs the same tool surface with PostgreSQL for teams that need multi-user collaboration, incremental sync, and optimistic locking per node. Tool signatures are identical; a client switches by changing the server address, and graphs round-trip between local and cloud.

Client compatibility. Any MCP-capable client works with UPG. At the time of writing, that includes the major AI coding editors.

Full MCP tool inventory, response shapes for introspection, batching, session and product context, graph digest, area-scoped traversal, change-based collaboration, and dual-transport details: Appendix E.

The MCP server is how new work enters the graph. Existing work — tickets in Linear, pages in Notion, specs in Markdown — needs an entry point too. That entry point is agent-native import: the agent that already speaks MCP is also the importer. A single tool, get_import_recipe, returns the canonical mapping recipe for a named source: which source objects become which entity types, which fields map to which properties, which relations become which edges, and the pre-import analysis worth running (title clustering, semantic similarity, entity extraction over prose) before committing.

The recipe catalog covers thirty-plus sources. Its lineage matters: the first generation of UPG import was adapter code per source; the mapping tables inside those adapters proved to be the durable asset, and the code around them proved to be a re-implementation of what the agent already does better — reading a corpus, exercising judgment on ambiguous items, asking a human when unsure. So the tables were promoted to first-class recipe data and the executor was replaced by the agent. Import fidelity now improves by editing a recipe, not by shipping code.

Four representative recipes:

Recipe mapping in practice. A Linear issue labelled persona, titled "Felix, solo builder", with body prose describing the archetype, becomes a persona node: title from the issue title, description from the body, source_id set to the Linear issue ID, and mapping_confidence: 'high' because the label matched a canonical type. The same issue without a UPG-aligned label is imported as a generic document with mapping_confidence: 'low' and surfaced for human type selection. Source-traceability and mapping-confidence semantics (§3.4) apply to every imported node; the draft is always reviewed before commit.

Post-import checks are source-independent. After any import, the same structural checks apply regardless of where the corpus came from: missing edges, orphan nodes, domains the source implies should exist. These run as ordinary graph validation, not per-importer logic.

The honest gap has moved. Structured sources (Linear, Notion databases, GitHub) import with high fidelity because their recipes are precise. Loosely structured corpora — long documents, meeting transcripts, threaded discussions — now import through the same agent, but the recipes constrain them less, so structure quality depends more on the agent's judgment and the human review pass. Sharpening recipe guidance for prose-scale corpora is the active edge of this work (§6.2).

The recipe catalog and its mapping tables: packages/upg-adapters/ in the specification repository, exposed at runtime via get_import_recipe.

Adapters bring existing work in. Playbooks and approaches are the other side: structured modes for producing new work and engaging with what exists. §3.7 introduced playbooks and approaches as Layer 5 of the specification; this subsection describes how the reference implementation runs today.

The current reference implementation. Slash-command skills inside Claude Code (/upg-new-persona, /upg-new-hypothesis, /upg-check-gaps and others) are the per-surface bindings of canonical UPGPlaybook and UPGApproach definitions. Playbook structure lives in @unified-product-graph/core; the experience lives in a PlaybookBinding for the target surface. The same playbook definition binds to a Cursor command, a VS Code extension, or a browser canvas without change: the structure-shared, experience-per-surface split described in §3.7.

Three modes cover the current set.

The conversation is the data entry. A skill does not ask the user to draft a persona document and then extract entities later. Every question resolves to a create_node or update_node call at the moment the user answers; prose never becomes an intermediate artefact. The graph is updated live, one utterance at a time. This is the discipline that keeps capture and structure as the same step: in the document paradigm writing and structuring are two different steps, and the second one is usually skipped.

Playbook and approach schemas: Appendix A. Full MCP tool inventory including the list_catalog facet (playbooks, approaches) and the five approach skills (plan / inspect / prioritise / reflect / trace): Appendix E.

Guided playbooks capture entities through conversation; UPG Markdown captures them through prose. A .upg file is the canonical JSON serialisation of a product graph; a .upg.md file is an alternate surface over the same graph: standard markdown with typed entity references embedded inline. Neither format is derived from the other; both serialise the same underlying structure, and a UPG-aware tool can round-trip between them. A reference takes one of three forms: [[type:id]] for a bare mention, [[type:id|property:value]] for a mention that asserts property values at that point of reference, and [[+type:id]] for a creation reference. A paragraph reads as natural prose to a human and parses as structured references to a machine:

Felix, a felix-solo-builder, repeatedly hits volume-vs-value every time three feature requests stack up and the loudest one is not obviously the right one.

A memo written in .upg.md is simultaneously a document, read linearly and committed to git, and a graph composition whose references resolve to live records. The memo is a curated view over the graph rather than a parallel copy that drifts from it.

Full grammar, resolver behaviour, the longer worked memo, staleness detection, and the rendering implementation: Appendix F.

UPG is used to model the product that defines it. The reference .upg file maintained by the authors was built incrementally across dozens of AI-assisted sessions, grew without schema migration as new domains became relevant (engineering entities appeared when architecture work began; growth entities appeared when business-model work started), and is the operational memory for ongoing development of Entopo, the visual graph application introduced in §1.5. Typed features trace back through the discovery-to-delivery spine (feature ← hypothesis ← solution ← opportunity ← need ← job ← persona), and the gaps where chains break are visible in the graph rather than hidden in prose.

This is existence-proof of feasibility, not evidence of generalisation. The specification was designed to model a specific kind of product, and the self-hosted graph demonstrates that the specification is internally coherent enough to support sustained use by the team that wrote it. Controlled user studies across independent product teams, reference graphs built by external collaborators, and cross-domain corpus analysis are open work.

§4.1 noted that the default unit is one product per file. The portfolio document (§3.10) is the multi-product case, and it reuses the same machinery: the same $upg header, the same canonical form, the same cross-file reference syntax. It is distinguished by $upg.kind: "portfolio" (the in-memory discriminator is type: "portfolio"), and in place of a single product's product / nodes / edges it carries a small set of top-level sections:

• organization: the single organisation that owns the portfolio, the same identity summary the header surfaces.
• portfolios and product_areas are the hierarchy nodes: nestable portfolios (the strategic axis, where the company invests) and product areas (the organisational axis, who owns what).
• products: each member product with its own nodes and edges embedded inline, so a portfolio document is one self-contained, portable snapshot. Each embedded product retains the exact shape it has as a standalone .upg file.
• cross_edges: the cross-product edges (§3.10), each referencing its endpoints by qualified id.
• registry is optional and additive: the shared-vocabulary tier, a { nodes, edges? } object of canonical entities. A portfolio without a registry omits the section entirely and stays byte-identical; an empty registry is never serialised.

Two properties follow from this design, both deliberate. First, the format is additive. A single-product UPGDocument remains valid unchanged; a portfolio is a strict superset that wraps products which still open, validate, and version as ordinary graphs. A team can adopt the portfolio tier over an existing fleet of single-product graphs without rewriting any of them, and a local workspace typically maintains the members as separate files and assembles them into one portfolio document only on export. Second, the registry is reached by a reserved address. Canonical entities are addressed as registry/{node_id}, where registry is a reserved pseudo product-id no real product may claim; the targets of instance_of, the area-to-audience edges, and the foundations edges all resolve through it. The registry is therefore a third tier without being a third file format: a namespaced section inside the portfolio document, separating the company's structure (portfolios and areas) from its shared vocabulary (the registry) without adding a loader, a schema, or a tier for every adopter to learn.

The full UPGPortfolioDocument interface, the registry shape, and a worked portfolio.upg example are in Appendix O.

The implementations described in Section 4 (file format, MCP server, adapters, guided skills, markdown surface) are surfaces over a single ontology. They cohere only because the ontology itself is constrained. A persona written by a skill has to match a persona parsed from a memo has to match a persona imported from Notion. The Unified Product Graph (UPG) specification governs this convergence through twenty invariants, refined across three review cycles and grouped into five clusters.

Each principle earns its place by being an invariant: a property of the ontology that, if violated, admits a class of failure that has cost projects time, interoperability, or trust. Some are enforced by automated tests against @unified-product-graph/core; others by manual review against the governance document. One principle runs through the other nineteen. P16 states it directly: UPG is machine-written, human-readable. No human writes a .upg file by hand. The format is produced by agents, adapters, and tools; consumed by AI inference, renderers, and other agents. Every entity type name, property key, and edge verb is parseable from natural language. The clusters that follow all serve that commitment.

Vocabulary determines whether a practitioner describing a job in prose and an agent writing a job node converge without translation. The penalty for getting this wrong is small per session and compounds badly over time: every jargon translation is a place where agent output diverges from the canonical type. P1 keeps type names readable without a glossary; P2 keeps the data layer framework-neutral so framework vocabularies remain display labels; P7 collapses overlapping types into one canonical type with a discriminator property; P9 anchors naming inside each domain to that domain's universal practitioner vocabulary.

P7 in practice. Early versions of the specification carried framework-specific types for the same underlying concepts. The discriminator property that replaced each consolidation set carries the information the framework-specific types were carrying implicitly: pain_point, user_need, and desired_outcome became need with valence: pain | gap | constraint; kpi, north_star_metric, and input_metric became metric with designation; design_decision, product_decision, and architecture_decision became decision with layer. Made explicit, one canonical type suffices and every framework view still renders its preferred label. P7 does not forbid distinctions between concepts: it forbids creating a type when a property would do.

Grammar is what keeps the graph structurally meaningful. P4 makes hierarchy a first-class spec concept, so an agent cannot place a database_schema under a persona: the validator catches it against the spec alone. P5 and P18 give every edge a semantic verb and a reverse form, so the relationship reads naturally from either endpoint. P6 keeps domains as coherent semantic groupings rather than buckets of convenience.

This cluster is where UPG diverges most sharply from ad-hoc modelling. It asks, for any concept, whether it is an entity, an edge, or a property. P14 keeps the same relationship from being stored in two places (edge and foreign key) that can disagree. P19 upgrades repeatedly-referenced values (statuses, categories, metric names) from strings to first-class nodes. P20 gives the ontology an operational test for whether a candidate type deserves to exist at all.

P20 operates on a different axis from P7. Where P7 asks whether two candidate types should collapse into one, P20 asks whether a single candidate type earns the right to exist at all. The operational test is mechanical: remove the entity and rewire its edges directly between its neighbours. If the graph loses no information, the entity was a pass-through. If it loses a hub role, a container role, or narrative meaning that did not belong on any single edge, the entity earns its place.

P20 in practice. The surface type is a worked instance of the test. Three types already answered adjacent questions about a piece of interface: feature_area answers who owns this?, bounded_context answers what architecture does this belong to?, and screen answers which route is this?. None answers what else occupies this same place, and who wins when two things want it? Run the removal test: delete the surface and rewire its edges so features attach directly to the screen that renders them. The graph retains "this feature appears on this screen" and loses three things it cannot recover. It loses the container role, because a screen is route-level and the places features actually contest nest several levels below it (a shell holds a pane, a pane holds a region, a region holds a slot). It loses the hub role, because the same place is simultaneously governed by a design guideline, drawn with design components, judged by a metric, and visited by a journey step, and those four facts have no shared endpoint once the place itself is gone. And it loses the narrative: arbitration_rule states who wins when the place is oversubscribed, a sentence that belongs to the place and to no edge leaving it.

The general lesson is that P20 rewards resolution, not novelty. surface introduces no concept a design team did not already hold; it makes a distinction the team was already drawing in prose addressable, at a grain one level finer than the type that existed. A candidate type may pass P20 by being a strictly finer reading of an accepted type, provided the finer reading anchors relationships the coarser one cannot.

Properties are where judgment becomes data. P3 forbids escape hatches so the schema cannot degrade into a catalog of titles. P13 prevents two entity types from inventing divergent enum values for the same conceptual axis. P17 keeps qualitative meaning separate from computational convenience: a slider reading 3/5 is not the same as "Severe pain," and the ontology refuses to let that distinction collapse. P15 makes status portable across tools; the universal phases hold everywhere, and granular states extend without breaking interop.

A standard fractures the moment two implementations quietly disagree. The governance principles are what let the ontology grow over years without splintering. P8 prevents forking of the canonical vocabulary into app-specific dialects. P10 prevents the specification from becoming an opinion paper. P11 keeps the extension path from becoming an escape hatch that breaks interoperability. P12 keeps documentation and types in the same place, so the spec cannot drift from its docs.

A note on numbering. Principle identifiers reflect the order in which each invariant was recognised and added to the specification; the clusters above are a later semantic grouping applied once the full set was stable. A cluster-ordered reference index is provided at the end of Appendix D.

Appendix D expands each of the twenty principles with the specific failure mode it prevents and the mix of automated tests and manual review that enforces it.

The specification today covers the software-product-creation graph. The sections below collect the open work: four domains staged as the next ontology expansions, and several areas where the specification will grow through contributions from outside the authors.

Four domains sit outside UPG's current coverage. Each needs native entity types, edge semantics, and lifecycle models rather than workarounds through the types that exist today.

Each is a multi-month ontology effort. The path forward uses the UPGEntityTypeMaturity lifecycle (draft → proposed → stable → deprecated → removed) so community proposals can ship in .upg files and accumulate usage data before entering the stable specification. The project invites collaborators in each sector to co-propose the entity catalog, lifecycle model, and edge semantics for their domain.

Four areas where the specification benefits from work outside the authors:

Governance for all of this runs through a public RFC process in the specification repository. The specification grows when other people's work lands in it.

AI expanded what one person can produce. It did not expand what one person can hold in their head. The gap widens with every model release, and the tools piling more output into folders, chat histories, and scattered documents widen it further rather than closing it.

The Unified Product Graph gives product knowledge a shape: typed entities, directed relationships with forward and reverse verbs, lifecycle phases and states, a portable JSON file format, and a migration system that lets the ontology evolve without breaking files already in circulation. The .upg file is agnostic about which tool writes it and which tool reads it, so long as product knowledge carries structure, relationships stay explicit, and no context is lost when data moves between systems or between AI sessions.

The specification is early. The ontology will grow, shift, and occasionally shrink as use cases clarify what was wrong. The evidence is preliminary, the community is small, and the hard questions of governance, independent implementation, and formal evaluation are ahead rather than behind.

The thesis is what the paper has argued and what the authors have run in production long enough to trust: structured memory, curated jointly by practitioners and the AI agents they work with, compounds across sessions, roles, and tools where unstructured output dissolves. A product's memory is built once and written into by every session thereafter. That is what makes the next session cheaper than the last.

UPG is open source, MIT-licensed, and available at unifiedproductgraph.org.