@elevasis/sdk 1.44.3 → 1.46.0

package/reference/scaffold/recipes/customize-knowledge-browser.md

@@ -14,6 +14,8 @@ The Knowledge Browser is a built-in feature surface that renders MDX documents c
 
 In template-derived projects, `ui/vite.config.ts` imports `elevasisVite` from `@elevasis/ui/vite` and spreads it into the plugins array:
 
+<!-- doc-snippet:skip: illustrative excerpt from the ui/ project's own vite.config.ts -- `defineConfig` and `react` are shown unimported, and this doc-snippet check project (external/_template/operations) does not depend on the ui/ project's vite plugins or @elevasis/ui -->
+
 ```ts
 // ui/vite.config.ts
 import { tanstackRouter } from '@tanstack/router-plugin/vite'
@@ -105,7 +107,7 @@ The template's `ui/src/routes/__root.tsx` registers `knowledgeManifest` from `@e
 ```tsx
 // ui/src/routes/__root.tsx
 import { knowledgeManifest } from '@elevasis/ui/features/knowledge'
-import { ElevasisSystemsProvider } from '@elevasis/ui'
+import { ElevasisSystemsProvider } from '@elevasis/ui/provider'
 
 <ElevasisSystemsProvider
   organizationModel={canonicalOrganizationModel}
@@ -117,34 +119,21 @@ import { ElevasisSystemsProvider } from '@elevasis/ui'
 
 A "Knowledge" sidebar entry appears, routes resolve under `/knowledge`, and the Browser renders with the default tree and node viewer. No additional code required.
 
-### Extend (Custom Nav Items, Default Chrome)
+### Extend (Custom Sidebar, Default Routes)
+
+Spread the manifest and override `sidebar` with a project-owned component. `SystemModule.sidebar` is the supported extension point; everything else in `knowledgeManifest` — routes, the node viewer, the main pane — keeps working unchanged.
 
-Spread the manifest and override `sidebar` to a custom component. The custom component composes `KnowledgeSidebarMiddle` with a modified items array. This is the shortest path to adding project-specific nav entries while keeping the platform chrome.
+The platform's own sidebar internals are **not** part of the published surface. `@elevasis/ui/features/knowledge` exports `knowledgeManifest` and nothing else, so a custom sidebar is project-owned markup. Build it from the knowledge primitives that _are_ published on `@elevasis/ui/knowledge` — `KnowledgeTree`, `KnowledgeNodeList`, `KnowledgeSearchBar`, `KnowledgeBrowser`, and `getSharedOrganizationGraph` — rather than from the default sidebar's parts.
 
 ```tsx
 // ui/src/features/knowledge/sidebar.tsx
-import {
-  KnowledgeSidebarMiddle,
-  KNOWLEDGE_ITEMS,
-} from '@elevasis/ui/knowledge'
-import { knowledgeManifest, KnowledgeSidebar } from '@elevasis/ui/features/knowledge'
-import { IconBook } from '@tabler/icons-react'
-
-const customItems = [
-  ...KNOWLEDGE_ITEMS,
-  {
-    label: 'Internal Runbooks',
-    to: '/knowledge/by-owner/internal',
-    icon: IconBook,
-    exact: false,
-  },
-]
-
-const CustomKnowledgeSidebar = () => (
-  <KnowledgeSidebar>
-    <KnowledgeSidebarMiddle items={customItems} />
-  </KnowledgeSidebar>
-)
+import { knowledgeManifest } from '@elevasis/ui/features/knowledge'
+import { useElevasisSystems } from '@elevasis/ui/provider'
+
+const CustomKnowledgeSidebar = () => {
+  const { organizationModel } = useElevasisSystems()
+  return <MyProjectSidebar organizationModel={organizationModel} />
+}
 
 export const customKnowledgeManifest = {
   ...knowledgeManifest,
@@ -165,7 +154,7 @@ import { customKnowledgeManifest } from '../features/knowledge/sidebar'
 </ElevasisSystemsProvider>
 ```
 
-`KNOWLEDGE_ITEMS` is the exported default items array (matches the `CRM_ITEMS` shape from `@elevasis/ui/features/crm`). Spread it and append project-specific entries.
+`KNOWLEDGE_ITEMS` is still exported from `@elevasis/ui/knowledge` as a starting nav-item array, but it is deprecated — it exists for the legacy nav-items sidebar variant. Prefer deriving your nav entries from the organization model.
 
 ### Replace (Project-Owned UI)
 
@@ -174,10 +163,14 @@ Skip `knowledgeManifest` entirely and build a project-owned route that calls `@e
 ```tsx
 // ui/src/routes/knowledge/index.tsx
 import { bySystem } from '@elevasis/core/knowledge'
-import { useElevasisSystems } from '@elevasis/ui'
+import { getSharedOrganizationGraph } from '@elevasis/ui/knowledge'
+import { useElevasisSystems } from '@elevasis/ui/provider'
 
 function MyCustomKnowledgeView() {
-  const { graph } = useElevasisSystems()
+  const { organizationModel } = useElevasisSystems()
+  if (!organizationModel) return null
+
+  const graph = getSharedOrganizationGraph(organizationModel)
   const nodes = bySystem(graph, 'sales.crm')
   return <MyOwnLayout nodes={nodes} />
 }
@@ -189,20 +182,19 @@ The `knowledgePlugin()` Vite plugin is still needed in this path because it gene
 
 ## Exports Reference
 
-| Export                                                   | Package                              | Purpose                                                   |
-| -------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------- |
-| `elevasisVite`                                           | `@elevasis/ui/vite`                  | Umbrella plugin factory; includes `knowledgePlugin`       |
-| `knowledgeManifest`                                      | `@elevasis/ui/features/knowledge`    | Default `SystemModule` manifest; spread or pass directly  |
-| `KnowledgeSidebar`                                       | `@elevasis/ui/features/knowledge`    | Default sidebar wrapper                                   |
-| `KnowledgeSidebarMiddle`                                 | `@elevasis/ui/features/knowledge`    | Sidebar middle section; accepts `items?: NavItem[]`       |
-| `KNOWLEDGE_ITEMS`                                        | `@elevasis/ui/knowledge`             | Default sidebar nav items array                           |
-| `KnowledgeBrowser`                                       | `@elevasis/ui/knowledge`             | Composed browser: search bar + detail view                |
-| `KnowledgeTree`                                          | `@elevasis/ui/knowledge`             | Tree for one mount axis                                   |
-| `KnowledgeNodeList`                                      | `@elevasis/ui/knowledge`             | Flat list of node cards                                   |
-| `KnowledgeNodeView`                                      | `@elevasis/ui/knowledge`             | Single node: title, kind badge, body, edge sidecar        |
-| `KnowledgeSearchBar`                                     | `@elevasis/ui/knowledge`             | FlexSearch over title, summary, and body                  |
-| `KnowledgeMDXProvider`                                   | `@elevasis/ui/knowledge`             | React context supplying the component allowlist           |
-| `knowledgePlugin`                                        | `@elevasis/ui/vite-plugin-knowledge` | Vite plugin for build-time MDX codegen + HMR (direct use) |
+| Export                                                                 | Package                              | Purpose                                                   |
+| ---------------------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------- |
+| `elevasisVite`                                                         | `@elevasis/ui/vite`                  | Umbrella plugin factory; includes `knowledgePlugin`       |
+| `knowledgeManifest`                                                    | `@elevasis/ui/features/knowledge`    | Default `SystemModule` manifest; spread or pass directly  |
+| `getSharedOrganizationGraph`                                           | `@elevasis/ui/knowledge`             | Memoized graph for the current organization model         |
+| `KNOWLEDGE_ITEMS`                                                      | `@elevasis/ui/knowledge`             | Deprecated legacy nav-items array                         |
+| `KnowledgeBrowser`                                                     | `@elevasis/ui/knowledge`             | Composed browser: search bar + detail view                |
+| `KnowledgeTree`                                                        | `@elevasis/ui/knowledge`             | Tree for one mount axis                                   |
+| `KnowledgeNodeList`                                                    | `@elevasis/ui/knowledge`             | Flat list of node cards                                   |
+| `KnowledgeNodeView`                                                    | `@elevasis/ui/knowledge`             | Single node: title, kind badge, body, edge sidecar        |
+| `KnowledgeSearchBar`                                                   | `@elevasis/ui/knowledge`             | FlexSearch over title, summary, and body                  |
+| `KnowledgeMDXProvider`                                                 | `@elevasis/ui/knowledge`             | React context supplying the component allowlist           |
+| `knowledgePlugin`                                                      | `@elevasis/ui/vite-plugin-knowledge` | Vite plugin for build-time MDX codegen + HMR (direct use) |
 | `bySystem`, `byOntology`, `byKind`, `byOwner`, `governs`, `governedBy` | `@elevasis/core/knowledge`           | Pure query functions for project-owned custom UI          |
 
 For template-derived projects, import `elevasisVite` from `@elevasis/ui/vite` rather than `knowledgePlugin` directly. The direct `knowledgePlugin` import from `@elevasis/ui/vite-plugin-knowledge` remains available for advanced or non-template wiring.
@@ -210,77 +202,16 @@ For template-derived projects, import `elevasisVite` from `@elevasis/ui/vite` ra
 ## Decision Tree
 
 - **Just want knowledge nodes to show up?** Author `.mdx` files under `core/config/knowledge/nodes/`. That is it.
-- **Need extra sidebar nav entries or a different items order?** Spread the manifest, override `sidebar` with a composed `KnowledgeSidebarMiddle` using custom `items`.
+- **Need different sidebar navigation?** Spread the manifest and override `sidebar` with a project-owned component. The default sidebar's own parts are not published.
 - **Need a completely different layout, data sources, or knowledge UX?** Skip the manifest, own the route, call `@elevasis/core/knowledge` directly.
 - **Need to extend the MDX component allowlist for custom body components?** Pass `extraComponents` to `KnowledgeMDXProvider` in your custom renderer.
-- **Need to add a 6th segment to the sidebar strip?** See the SegmentedControl extension section below.
 - **Need a custom main-pane dispatcher?** See the DescribeNodeView section below.
 
 ## Phase 1.5 Extensions
 
-Phase 1.5 adds two extension surfaces on top of the customization tiers above: a mount-axis `SegmentedControl` strip in the sidebar and a `DescribeNodeView` dispatcher in the main pane. Both are composable -- you can extend the defaults or replace them entirely.
-
-### Extending the SegmentedControl (add a 6th segment)
-
-Phase 1.5 ships `KnowledgeSidebarMiddle` with a five-segment strip above the search bar:
-
-```
-[ By System ] [ By Kind ] [ By Owner ] [ Governs ] [ Governed By ]
-```
-
-Each segment maps to a mount axis exposed by `@elevasis/core/knowledge`. The strip is a `SegmentedControl` from `@mantine/core`; selected axis is local sidebar state and does NOT affect the URL.
+Phase 1.5 adds a `DescribeNodeView` dispatcher in the main pane. It is composable -- you can extend the default or replace it entirely.
 
-To add a 6th segment, supply a `segments` prop to `KnowledgeSidebarMiddle`:
-
-```tsx
-import {
-  KnowledgeSidebar,
-  KnowledgeSidebarMiddle,
-  KNOWLEDGE_SEGMENTS,
-} from '@elevasis/ui/knowledge'
-import { knowledgeManifest } from '@elevasis/ui/features/knowledge'
-import { byOwner } from '@elevasis/core/knowledge'
-
-// KNOWLEDGE_SEGMENTS is the default five-item array; spread and append.
-const customSegments = [
-  ...KNOWLEDGE_SEGMENTS,
-  {
-    value: 'by-team',
-    label: 'By Team',
-    // renderBody receives (graph, knowledgeNodes, selectedNodeId, onSelectNode).
-    // Return any ReactNode -- the strip swaps the tree area for your component.
-    renderBody: ({ graph, knowledgeNodes, onSelectNode, selectedNodeId }) => {
-      const teamNodes = byOwner(graph, 'team:product', knowledgeNodes)
-      return (
-        <MyTeamList
-          nodes={teamNodes}
-          onSelect={onSelectNode}
-          activeId={selectedNodeId}
-        />
-      )
-    },
-  },
-]
-
-const CustomKnowledgeSidebar = () => (
-  <KnowledgeSidebar>
-    <KnowledgeSidebarMiddle segments={customSegments} />
-  </KnowledgeSidebar>
-)
-
-export const customKnowledgeManifest = {
-  ...knowledgeManifest,
-  sidebar: CustomKnowledgeSidebar,
-}
-```
-
-Rules and constraints:
-
-- `value` must be unique across all segments in the array.
-- `label` is the display string inside the `SegmentedControl`; keep it short (under 10 characters) to fit the 320 px sidebar width.
-- `renderBody` receives the same props as the built-in axis renderers. The tree area is replaced by whatever the function returns while that segment is active.
-- The first segment in the array is the default selection on mount.
-- Segment selection is reset to the first item whenever the user navigates to `/knowledge/command-view*` (the command-view sub-route bypasses the strip entirely and renders `CommandViewSidebarContent` instead).
+The default sidebar renders a mount-axis strip above the search bar, but that strip is internal: it is not configurable through a prop and its parts are not published. Projects that need different sidebar axes own the sidebar, per the Extend tier above.
 
 ### Replacing `DescribeNodeView` Entirely
 
@@ -303,11 +234,15 @@ function DescribeNodeView({ node, graph, onNavigateToNode }) {
 ```tsx
 // ui/src/routes/knowledge/$nodeId.tsx
 import { useParams } from '@tanstack/react-router'
-import { useElevasisSystems } from '@elevasis/ui'
+import { getSharedOrganizationGraph } from '@elevasis/ui/knowledge'
+import { useElevasisSystems } from '@elevasis/ui/provider'
 
 export default function KnowledgeNodeRoute() {
   const { nodeId } = useParams({ from: '/knowledge/$nodeId' })
-  const { graph } = useElevasisSystems()
+  const { organizationModel } = useElevasisSystems()
+  if (!organizationModel) return null
+
+  const graph = getSharedOrganizationGraph(organizationModel)
   const node = graph.nodes.find((n) => n.id === nodeId)
 
   if (!node) return <MyNotFoundView />
@@ -363,16 +298,16 @@ function MyDescribeNodeView(props: DescribeNodeViewProps) {
 
 The following exports are added in Phase 1.5 on top of the exports table above:
 
-| Export                         | Package                  | Purpose                                                                      |
-| ------------------------------ | ------------------------ | ---------------------------------------------------------------------------- |
-| `DescribeNodeView`             | `@elevasis/ui/knowledge` | Default graph-node dispatcher; routes by `node.kind`                         |
-| `SystemDescribeView`           | `@elevasis/ui/knowledge` | Minimal System node view: path, icon, lifecycle, hierarchy, edges            |
-| `ResourceDescribeView`         | `@elevasis/ui/knowledge` | Minimal resource node view: resourceType, description, edges                 |
-| `OrganizationDescribeView`     | `@elevasis/ui/knowledge` | Minimal organization node view: label, edges                                 |
-| `GenericDescribeView`          | `@elevasis/ui/knowledge` | Key/value fallback for unknown kinds                                         |
-| `KNOWLEDGE_SEGMENTS`           | `@elevasis/ui/knowledge` | Default five-segment array for `KnowledgeSidebarMiddle`                      |
+| Export                     | Package                  | Purpose                                                           |
+| -------------------------- | ------------------------ | ----------------------------------------------------------------- |
+| `DescribeNodeView`         | `@elevasis/ui/knowledge` | Default graph-node dispatcher; routes by `node.kind`              |
+| `SystemDescribeView`       | `@elevasis/ui/knowledge` | Minimal System node view: path, icon, lifecycle, hierarchy, edges |
+| `ResourceDescribeView`     | `@elevasis/ui/knowledge` | Minimal resource node view: resourceType, description, edges      |
+| `OrganizationDescribeView` | `@elevasis/ui/knowledge` | Minimal organization node view: label, edges                      |
+| `GenericDescribeView`      | `@elevasis/ui/knowledge` | Key/value fallback for unknown kinds                              |
+| `DomainPanelDispatcher`    | `@elevasis/ui/knowledge` | Per-domain panel dispatcher used inside the describe views        |
 
-`KnowledgeSidebarMiddle` gains an optional `segments?: KnowledgeSegment[]` prop (defaults to `KNOWLEDGE_SEGMENTS`). The `KnowledgeSegment` type is exported from `@elevasis/ui/knowledge`.
+Each view also exports its props type (`DescribeNodeViewProps`, `SystemDescribeViewProps`, and so on) from the same subpath.
 
 ## See Also
 

package/reference/scaffold/recipes/customize-organization-model.md

@@ -1,102 +1,104 @@
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
----
-title: Customize organization-model.ts
-description: Annotated walkthrough for customizing the System-backed Organization Model in template-derived projects.
----
-
-# Customize organization-model.ts
-
-`core/config/organization-model.ts` is the semantic contract between the UI shell and platform operations. The shell reads the id-keyed `systems` map for semantic ownership and access, reads `navigation.sidebar` for shell navigation, and binds resources through the id-keyed `resources` map.
-
-## Imports
-
-```ts
-import {
-  createFoundationOrganizationModel,
-  defineOrganizationModel,
-  type OrganizationModel
-} from '@elevasis/core/organization-model'
-```
-
-- `defineOrganizationModel` gives a typed override shape.
-- `createFoundationOrganizationModel` resolves defaults and returns the canonical model plus UI-facing helpers.
-- `OrganizationModel` is the fully resolved model type.
-
-## Systems
-
-The `systems` map is the source of truth for semantic hierarchy, lifecycle, admin visibility, and governed ownership.
-
-```ts
-const override = defineOrganizationModel({
-  systems: {
-    dashboard: {
-      id: 'dashboard',
-      order: 10,
-      label: 'Dashboard',
-      lifecycle: 'active',
-      description: 'Command Center home'
-    },
-    sales: {
-      id: 'sales',
-      order: 20,
-      label: 'Sales',
-      lifecycle: 'active'
-    },
-    'sales.crm': {
-      id: 'sales.crm',
-      order: 30,
-      label: 'CRM',
-      parentSystemId: 'sales',
-      lifecycle: 'active',
-      description: 'CRM pipeline and deal operations'
-    }
-  },
-  navigation: {
-    sidebar: {
-      primary: {
-        dashboard: {
-          type: 'surface',
-          order: 10,
-          label: 'Dashboard',
-          path: '/',
-          surfaceType: 'dashboard',
-          icon: 'feature.dashboard',
-          targets: { systems: ['dashboard'] }
-        },
-        business: {
-          type: 'group',
-          order: 20,
-          label: 'Business',
-          children: {
-            crm: {
-              type: 'surface',
-              order: 10,
-              label: 'CRM',
-              path: '/crm',
-              surfaceType: 'page',
-              targets: { systems: ['sales.crm'] }
-            }
-          }
-        }
-      },
-      bottom: {}
-    }
-  }
-})
-```
-
-System field reference:
-
-- `id` -- lowercase dotted path. Parent Systems are inferred from prefix segments or declared through `parentSystemId`.
-- `order` -- deterministic map iteration order. Use multiples of 10 for easy insertion.
-- `label` -- sidebar and breadcrumb label.
-- `description` -- optional settings/help text.
-- `kind` -- product, operational, platform, or diagnostic.
-- `parentSystemId` -- explicit parent System link.
-- `lifecycle` -- draft, beta, active, deprecated, or archived.
-- `ui` -- optional route metadata used by shell matching during migration.
+---
+title: Customize organization-model.ts
+description: Annotated walkthrough for customizing the System-backed Organization Model in template-derived projects.
+---
+
+# Customize organization-model.ts
+
+`core/config/organization-model.ts` is the semantic contract between the UI shell and platform operations. The shell reads the id-keyed `systems` map for semantic ownership and access, reads `navigation.sidebar` for shell navigation, and binds resources through the id-keyed `resources` map.
+
+## Imports
+
+```ts
+import {
+  createFoundationOrganizationModel,
+  defineOrganizationModel,
+  type OrganizationModel
+} from '@elevasis/core/organization-model'
+```
+
+- `defineOrganizationModel` gives a typed override shape.
+- `createFoundationOrganizationModel` resolves defaults and returns the canonical model plus UI-facing helpers.
+- `OrganizationModel` is the fully resolved model type.
+
+## Systems
+
+The `systems` map is the source of truth for semantic hierarchy, lifecycle, admin visibility, and governed ownership.
+
+<!-- doc-snippet:skip: continues from the Imports section above -- `defineOrganizationModel` is shown unimported here -->
+
+```ts
+const override = defineOrganizationModel({
+  systems: {
+    dashboard: {
+      id: 'dashboard',
+      order: 10,
+      label: 'Dashboard',
+      lifecycle: 'active',
+      description: 'Command Center home'
+    },
+    sales: {
+      id: 'sales',
+      order: 20,
+      label: 'Sales',
+      lifecycle: 'active'
+    },
+    'sales.crm': {
+      id: 'sales.crm',
+      order: 30,
+      label: 'CRM',
+      parentSystemId: 'sales',
+      lifecycle: 'active',
+      description: 'CRM pipeline and deal operations'
+    }
+  },
+  navigation: {
+    sidebar: {
+      primary: {
+        dashboard: {
+          type: 'surface',
+          order: 10,
+          label: 'Dashboard',
+          path: '/',
+          surfaceType: 'dashboard',
+          icon: 'feature.dashboard',
+          targets: { systems: ['dashboard'] }
+        },
+        business: {
+          type: 'group',
+          order: 20,
+          label: 'Business',
+          children: {
+            crm: {
+              type: 'surface',
+              order: 10,
+              label: 'CRM',
+              path: '/crm',
+              surfaceType: 'page',
+              targets: { systems: ['sales.crm'] }
+            }
+          }
+        }
+      },
+      bottom: {}
+    }
+  }
+})
+```
+
+System field reference:
+
+- `id` -- lowercase dotted path. Parent Systems are inferred from prefix segments or declared through `parentSystemId`.
+- `order` -- deterministic map iteration order. Use multiples of 10 for easy insertion.
+- `label` -- sidebar and breadcrumb label.
+- `description` -- optional settings/help text.
+- `kind` -- product, operational, platform, or diagnostic.
+- `parentSystemId` -- explicit parent System link.
+- `lifecycle` -- draft, beta, active, deprecated, or archived.
+- `ui` -- optional route metadata used by shell matching during migration.
 - `requiresAdmin` -- hides the node for non-admin members; descendants inherit it.
 - `actions` / `policies` -- references to cross-cutting domains.
 - `ontology` -- System-owned object, link, action, catalog, event, surface, interface, value-type, property, or group records.
@@ -107,6 +109,8 @@ System field reference:
 
 Use top-level `ontology` for global/shared primitives and `System.ontology` for owned contracts. The resolved ontology index is compiled from root and System scopes and validated for ID shape, kind mismatch, and duplicate IDs.
 
+<!-- doc-snippet:skip: continues from the Imports section above -- `defineOrganizationModel` is shown unimported here -->
+
 ```ts
 const override = defineOrganizationModel({
   ontology: {
@@ -154,12 +158,14 @@ const override = defineOrganizationModel({
 })
 ```
 
-Top-level `entities`, top-level `actions`, and `System.content kind: "schema"` remain accepted for existing consumers and are projected into compiled ontology indexes. Prefer `System.ontology` for new object/action/catalog contracts.
+Top-level `entities` and top-level `actions` remain accepted for existing consumers and are projected into compiled ontology indexes. `System.content` is **not** — it is retired, and the strict System schema rejects it. Author object, action, and catalog contracts in `System.ontology`.
 
 ## System Config
 
 Use `systems[*].config` for local settings and defaults that are not semantic contracts:
 
+<!-- doc-snippet:skip: continues from the Imports section above -- `defineOrganizationModel` is shown unimported here -->
+
 ```ts
 const override = defineOrganizationModel({
   systems: {
@@ -190,19 +196,21 @@ const override = defineOrganizationModel({
 ```
 
 Keep semantic nouns, verbs, relationships, events, catalogs, interfaces, and value types in ontology. Keep secrets, credentials, per-run execution state, logs, and external service state outside the Organization Model.
-
-## Sidebar Navigation
-
-Author shell navigation under `navigation.sidebar`. Groups can contain nested nodes; routeable surface leaves provide `path`, `surfaceType`, and `targets`. Dashboard should appear before Business, Business is a navigation group only, and `/clients` is the canonical clients route.
-
-## Resource Binding
-
-Resource identity and governance metadata live in `OrganizationModel` under `resources`. Workflows, agents, integrations, and scripts import those descriptors and derive runtime `resourceId` / `type` from them. The graph derives System membership from `ResourceEntry.systemPath`.
-
-```ts
-// core/config/organization-model.ts
-import { defineResources } from '@elevasis/core/organization-model'
-
+
+## Sidebar Navigation
+
+Author shell navigation under `navigation.sidebar`. Groups can contain nested nodes; routeable surface leaves provide `path`, `surfaceType`, and `targets`. Dashboard should appear before Business, Business is a navigation group only, and `/clients` is the canonical clients route.
+
+## Resource Binding
+
+Resource identity and governance metadata live in `OrganizationModel` under `resources`. Workflows, agents, integrations, and scripts import those descriptors and derive runtime `resourceId` / `type` from them. The graph derives System membership from `ResourceEntry.systemPath`.
+
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
+```ts
+// core/config/organization-model.ts
+import { defineResources } from '@elevasis/core/organization-model'
+
 export const resourceDescriptors = defineResources({
   leadImport: {
     id: 'lead-import',
@@ -223,26 +231,26 @@ export const resourceDescriptors = defineResources({
     }
   }
 })
-
-// operations/src/lead-import/index.ts
-config: {
-  resource: resourceDescriptors.leadImport,
-  resourceId: resourceDescriptors.leadImport.id,
-  name: 'Lead Import',
-  type: resourceDescriptors.leadImport.kind,
-  version: '1.0.0',
-  status: 'prod',
-  category: 'production'
-}
-```
-
-Use kind-prefixed graph IDs for cross-collection links:
-
-- `system:sales.crm`
-- `integration:instantly`
-- `resource:lead-import`
-- `action:operations.queue.review`
-
+
+// operations/src/lead-import/index.ts
+config: {
+  resource: resourceDescriptors.leadImport,
+  resourceId: resourceDescriptors.leadImport.id,
+  name: 'Lead Import',
+  type: resourceDescriptors.leadImport.kind,
+  version: '1.0.0',
+  status: 'prod',
+  category: 'production'
+}
+```
+
+Use kind-prefixed graph IDs for cross-collection links:
+
+- `system:sales.crm`
+- `integration:instantly`
+- `resource:lead-import`
+- `action:operations.queue.review`
+
 `category` is one of `production`, `diagnostic`, `internal`, or `testing`.
 
 Descriptor `title` and `description` own executable display metadata. Use nested `resource.ontology` bindings to declare which ontology actions, objects, catalogs, and events the resource performs, reads, writes, uses, or emits. `resource.ontology.primaryAction` names the default/selectable action and must be included in `resource.ontology.actions`. Resource event emissions can still be declared through top-level `emits` for older descriptors, but new descriptors should use `resource.ontology.emits`.
@@ -255,7 +263,9 @@ The old `sales`, `prospecting`, and `projects` top-level keys are not part of th
 - stable verbs -> `System.ontology.actionTypes`
 - pipelines, stages, templates, and status vocabularies -> `System.ontology.catalogTypes`
 - local settings and defaults -> `System.config`
-- existing `System.content kind: "schema"` nodes -> compatibility catalog projections
+- legacy `content-node:*` graph IDs from pre-migration projects -> compatibility catalog projections (authoring new `System.content` is rejected)
+
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
 
 ```ts
 systems: {
@@ -290,27 +300,29 @@ systems: {
   }
 }
 ```
-
+
 Keep `semanticClass` values stable; platform analytics and triggers depend on them.
 
 Policy and role integration remains outside ontology in this pass. Use `roles`, `policies`, `responsibleRoleId`, and `ownerRoleId` for accountability and access semantics until a dedicated policy/role ontology design is published.
-
-## Export Pattern
-
-```ts
-const foundation = createFoundationOrganizationModel(override)
-
-export const canonicalOrganizationModel: OrganizationModel = foundation.canonical
-export const organizationModel = foundation.model
-export const { getOrganizationSurface } = foundation
-```
-
-Pass `canonicalOrganizationModel` to `ElevasisSystemsProvider` in `ui/src/routes/__root.tsx`.
-
-## Resolve Behavior
-
-`createFoundationOrganizationModel(override)` resolves defaults, validates System hierarchy, and exposes helper functions used by the shell. Id-keyed domain maps merge additively by key, so tenant overrides can add one System or resource without re-authoring every default entry.
-
+
+## Export Pattern
+
+<!-- doc-snippet:skip: continues from the Imports section above -- `createFoundationOrganizationModel`, `override`, and `OrganizationModel` are shown unimported here -->
+
+```ts
+const foundation = createFoundationOrganizationModel(override)
+
+export const canonicalOrganizationModel: OrganizationModel = foundation.canonical
+export const organizationModel = foundation.model
+export const { getOrganizationSurface } = foundation
+```
+
+Pass `canonicalOrganizationModel` to `ElevasisSystemsProvider` in `ui/src/routes/__root.tsx`.
+
+## Resolve Behavior
+
+`createFoundationOrganizationModel(override)` resolves defaults, validates System hierarchy, and exposes helper functions used by the shell. Id-keyed domain maps merge additively by key, so tenant overrides can add one System or resource without re-authoring every default entry.
+
 Validation catches duplicate System IDs, missing parent Systems, invalid graph IDs, invalid UI paths, invalid ontology IDs, ontology kind mismatches, and duplicate ontology IDs.
 
 ## Refresh Generated Scaffold Copies