ContractSpec docs

OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

NavGraphSpec

Detail view for a single contract reference.

field.key.label
NavGraphSpec
field.version.label
field.type.label
field.title.label
NavGraphSpec
field.description.label
field.tags.label
field.owners.label
field.stability.label
public

Relationship graph over registered navigation surface items with hand-curated product knowledge edges.

Overview

`NavGraphSpec` models the navigation surface as a directed graph where:

•

**Nodes** are `NavSurfaceItemSpec` entries (typically auto-derived from `NavRegistry.list()`)

•

**Edges** are hand-maintained product relationships describing how surfaces relate

•

**Optional Layout** hints how to render the graph in the Nav Map viewer

Edge Semantics

Edges use semantic kinds to express relationship intent:

| Kind | Meaning | Example | |------|---------|---------| | `related` | Surfaces are related but not ordered | inbox ↔ threads | | `leads-to` | Natural workflow progression | workflow → evidence | | `escalates-to` | Escalation path | support → escalation-queue | | `parent-of` | Hierarchical containment | analytics → analytics/usage |

Each edge carries an optional `weight` (0..∞) indicating usage frequency or affinity.

Validation

`validateNavGraph` ensures:

•

No self-loops

•

Both endpoints resolve to node routes

•

No duplicate (from, to, kind) triples

Integration with Design-System Graph Templates

`NavGraphSpec` integrates with existing DS graph renderers:

•

`ConversationGraphView` — render conversation/discussion threads

•

`WorkflowDagView` — render workflow DAG

•

`AgentTreeView` — render agent hierarchy

•

`EngineeringLoopView` — render loop/feedback structures

The Nav Map view at `/companyos/nav-map` renders the full `NavGraphSpec` to show power users the complete navigation topology.

Example

const navGraph = defineNavGraph({
  meta: {
    key: 'companyos-nav',
    version: '1.0.0',
    description: 'CompanyOS navigation graph',
    goal: 'Enable power-user nav-map view and routing suggestions',
    context: 'Global navigation topology for all personas',
    owners: ['team-platform'],
    tags: ['core', 'navigation'],
  },
  nodes: navRegistry.list(),
  edges: [
    defineNavEdge({
      from: { web: '/companyos/workflow' },
      to: { web: '/companyos/evidence' },
      kind: 'leads-to',
      weight: 2.5,
    }),
    defineNavEdge({
      from: { web: '/companyos/inbox' },
      to: { web: '/companyos/threads' },
      kind: 'related',
    }),
  ],
  layout: { type: 'force-directed', spacing: 200 },
});