define_canonical_entity
Define a canonical shared entity in the portfolio registry (the shared-vocabulary tier of `.upg/portfolio.upg`). Use when an archetype is shared across products (a Developer persona, a North-Star metric, a competitor) and should have ONE authoritative definition that product instances link to via `register_instance`. A canonical entity is a normal node of any active entity type (persona, metric, competitor, market_segment, and any other active type) that lives in the registry rather than in a product. Creates the portfolio document if absent. Returns the canonical node and its `registry/{id}` qualified id.
Arguments
typestringrequiredAny active UPG entity type, including `proposed`-maturity types. There is no canonical allowlist; persona, metric, competitor, market_segment are common examples, not the allowed set. The only gate is that the type is active (see list_entity_types).
titlestringrequiredCanonical name (e.g. "Developer").
descriptionstringoptionalOptional longer description of the canonical entity.
propertiesobjectoptionalOptional properties (e.g. a persona's audience_role).
tagsarrayoptionalOptional tags.
canonical_idstringoptionalOptional explicit registry id; otherwise derived from type + title (e.g. persona_developer).
Returns
{ canonical, qualified_id, portfolio_file }