@elevasis/sdk 1.20.1 → 1.21.0

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

@@ -0,0 +1,384 @@
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+---
+title: Customize Knowledge Browser
+description: Author knowledge nodes and customize the Knowledge Browser in a template-derived project -- from zero-config authoring through sidebar composition, custom dispatchers, and direct query access.
+---
+
+# Customize Knowledge Browser
+
+The Knowledge Browser is a built-in feature surface that renders MDX documents called knowledge nodes. In template-derived projects it is pre-wired and ready to use without any configuration changes.
+
+## How It Works
+
+In template-derived projects, `ui/vite.config.ts` imports `elevasisVite` from `@elevasis/ui/vite` and spreads it into the plugins array:
+
+```ts
+// ui/vite.config.ts
+import { tanstackRouter } from '@tanstack/router-plugin/vite'
+import { elevasisVite } from '@elevasis/ui/vite'
+
+export default defineConfig({
+  plugins: [tanstackRouter({ autoCodeSplitting: true }), react(), ...elevasisVite()],
+})
+```
+
+`elevasisVite()` includes `knowledgePlugin()` as one of the plugins it returns. The plugin runs MDX codegen at `buildStart` and handles hot-module updates during `vite dev`. You do not need to touch `vite.config.ts` for the Knowledge Browser to work.
+
+Knowledge node icons are authored as semantic data tokens in MDX frontmatter, not as UI library component names. Use `knowledge.playbook`, `knowledge.strategy`, or `knowledge.reference` by node kind, or a project-owned `custom.*` token when the platform catalog does not cover the concept.
+
+## Author a Knowledge Node
+
+Drop an `.mdx` file anywhere under `core/config/knowledge/nodes/`. Subdirectories are fine -- codegen walks the tree recursively.
+
+Required frontmatter fields:
+
+- `id` -- unique string; convention is `knowledge.{slug}`
+- `kind` -- one of `playbook`, `strategy`, or `reference`
+- `title` -- display title shown in the Browser tree
+- `description` -- one-sentence summary shown in search results
+- `updatedAt` -- ISO date string (e.g. `2026-05-04`)
+
+Optional frontmatter fields:
+
+- `icon` -- semantic token such as `knowledge.playbook` (defaults by kind if omitted)
+- `links` -- array of node IDs or System references this node relates to
+- `ownerIds` -- array of role IDs that own or maintain this node
+
+Example:
+
+```mdx
+---
+id: knowledge.internal-runbook
+kind: playbook
+title: Internal Runbook
+description: Operating notes for project-specific support and escalation.
+icon: knowledge.playbook
+ownerIds:
+  - role.operator
+links:
+  - system:operations
+updatedAt: 2026-05-04
+---
+
+## Body content here
+
+Write plain markdown. A small JSX component allowlist is available in the body:
+`Card`, `Cards`, `Step`, `Steps`, `Callout`, `Tab`, `Tabs`.
+```
+
+On the next dev hot-reload or production build the node appears in the Browser. No manual command is required.
+
+The template ships a starter node at `core/config/knowledge/nodes/welcome.mdx` so the first `pnpm -C ui dev` produces a non-empty Browser. Delete or rewrite it once you have authored your own nodes.
+
+## `elevasis-sdk knowledge:generate` -- Manual One-Shot
+
+The CLI command `elevasis-sdk knowledge:generate` refreshes `core/config/knowledge/_generated/nodes.ts` outside a dev or build cycle. It is useful for two situations:
+
+- Force-refreshing generated output without starting `vite dev` or running `vite build`
+- Pre-build pipelines that must compile MDX before TypeScript starts
+
+The template's `pnpm -C ui build` script calls `pnpm -C .. knowledge:generate` explicitly before `tsc` and `vite build`, so production builds regenerate nodes as a first step without requiring a running dev server.
+
+During development the Vite plugin handles codegen automatically on every save. You do not need to run the CLI command manually unless you are operating outside a dev or build cycle.
+
+## CSS
+
+Import the knowledge subpath CSS in your app entry point:
+
+```ts
+// ui/src/main.tsx
+import '@elevasis/ui/knowledge/index.css'
+```
+
+This is required for Mantine-based knowledge components to render correctly. The CSS is not auto-loaded -- per the `@elevasis/ui` publish rules, consumers import CSS subpaths explicitly.
+
+## Customization
+
+The sections below cover optional customization for projects that need to diverge from the platform default. The authoring steps above are sufficient for the common case.
+
+### Default Mount (What the Template Ships)
+
+The template's `ui/src/routes/__root.tsx` registers `knowledgeManifest` from `@elevasis/ui/features/knowledge` in the `ElevasisSystemsProvider` manifest array. That is all that is required for the default Knowledge Browser to appear. The template already does this -- you do not need to add it yourself unless you scaffolded the project manually without using the template.
+
+```tsx
+// ui/src/routes/__root.tsx
+import { knowledgeManifest } from '@elevasis/ui/features/knowledge'
+import { ElevasisSystemsProvider } from '@elevasis/ui'
+
+<ElevasisSystemsProvider
+  organizationModel={canonicalOrganizationModel}
+  systems={[crmManifest, leadGenManifest, knowledgeManifest]}
+>
+  {/* ... */}
+</ElevasisSystemsProvider>
+```
+
+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)
+
+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.
+
+```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>
+)
+
+export const customKnowledgeManifest = {
+  ...knowledgeManifest,
+  sidebar: CustomKnowledgeSidebar,
+}
+```
+
+Register the custom manifest in place of the default:
+
+```tsx
+// ui/src/routes/__root.tsx
+import { customKnowledgeManifest } from '../features/knowledge/sidebar'
+
+<ElevasisSystemsProvider
+  systems={[crmManifest, leadGenManifest, customKnowledgeManifest]}
+>
+  {/* ... */}
+</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.
+
+### Replace (Project-Owned UI)
+
+Skip `knowledgeManifest` entirely and build a project-owned route that calls `@elevasis/core/knowledge` directly. Use this when the project's knowledge UI has a different layout, navigation structure, or data sources than the platform default.
+
+```tsx
+// ui/src/routes/knowledge/index.tsx
+import { bySystem } from '@elevasis/core/knowledge'
+import { useElevasisSystems } from '@elevasis/ui'
+
+function MyCustomKnowledgeView() {
+  const { graph } = useElevasisSystems()
+  const nodes = bySystem(graph, 'sales.crm')
+  return <MyOwnLayout nodes={nodes} />
+}
+```
+
+The project owns the renderer, layout, search, and navigation. The data layer is shared -- the org model remains the source of truth, and query results are consistent with what `elevasis-sdk knowledge:*` returns at the CLI.
+
+The `knowledgePlugin()` Vite plugin is still needed in this path because it generates the `KNOWLEDGE_BODIES` component map that any project-local renderer will need to display MDX bodies. The plugin is included automatically via `elevasisVite()` in the template's `vite.config.ts`.
+
+## 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) |
+| `bySystem`, `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.
+
+## 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 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.
+
+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).
+
+### Replacing `DescribeNodeView` Entirely
+
+Phase 1.5 introduces `DescribeNodeView` as the main-pane dispatcher. It receives any graph node (not just knowledge nodes) and routes to a per-kind view component:
+
+```tsx
+function DescribeNodeView({ node, graph, onNavigateToNode }) {
+  switch (node.kind) {
+    case 'knowledge':     return <KnowledgeNodeView node={node} graph={graph} onNavigateToNode={onNavigateToNode} />
+    case 'system':       return <SystemDescribeView node={node} graph={graph} onNavigateToNode={onNavigateToNode} />
+    case 'resource':      return <ResourceDescribeView node={node} graph={graph} onNavigateToNode={onNavigateToNode} />
+    case 'organization':  return <OrganizationDescribeView node={node} graph={graph} onNavigateToNode={onNavigateToNode} />
+    default:              return <GenericDescribeView node={node} graph={graph} onNavigateToNode={onNavigateToNode} />
+  }
+}
+```
+
+**Keep sidebar chrome, replace main pane:** Override the route component in your project's route tree. The default route for `/knowledge/:nodeId` renders `DescribeNodeView`. Replace it with a project-owned component that receives the same `node` and `graph` props:
+
+```tsx
+// ui/src/routes/knowledge/$nodeId.tsx
+import { useParams } from '@tanstack/react-router'
+import { useElevasisSystems } from '@elevasis/ui'
+
+export default function KnowledgeNodeRoute() {
+  const { nodeId } = useParams({ from: '/knowledge/$nodeId' })
+  const { graph } = useElevasisSystems()
+  const node = graph.nodes.find((n) => n.id === nodeId)
+
+  if (!node) return <MyNotFoundView />
+
+  // Completely custom dispatcher -- no platform chrome in the main pane.
+  return <MyDescribeNodeView node={node} graph={graph} />
+}
+```
+
+The sidebar (managed by the manifest) continues to operate normally. Tree clicks still navigate to `/knowledge/:nodeId`. Only the main pane changes.
+
+**Own everything:** Skip `knowledgeManifest` and build your own route tree as described in the Replace section above. Call `@elevasis/core/knowledge` directly for data and supply your own dispatcher.
+
+### Overriding Per-Kind Views (extend the dispatcher's switch)
+
+If you want the default dispatcher behavior for most kinds but need a custom layout for one kind, extend the exported `DescribeNodeView` rather than replacing it entirely. Phase 1.5 exports `createDescribeNodeDispatcher` for this purpose:
+
+```tsx
+import {
+  createDescribeNodeDispatcher,
+  SystemDescribeView,
+} from '@elevasis/ui/knowledge'
+
+// Supply overrides for specific kinds; all others fall through to platform defaults.
+const MyDescribeNodeView = createDescribeNodeDispatcher({
+  system: ({ node, graph, onNavigateToNode }) => (
+    // Project-specific System view with extra metadata section.
+    <MyFeatureDetailView node={node} graph={graph} onNavigateToNode={onNavigateToNode} />
+  ),
+  // 'knowledge', 'resource', 'organization', and the default fallback
+  // are handled by the platform unless you override them here.
+})
+```
+
+`createDescribeNodeDispatcher` returns a component with the same props interface as `DescribeNodeView` (`node`, `graph`, `onNavigateToNode`). You can drop it anywhere the default dispatcher is used.
+
+Override keys match `OrgGraphNodeKind` values: `'knowledge'`, `'feature'`, `'resource'`, `'organization'`, `'surface'`, `'entity'`, `'action'`. The `default` key overrides the generic fallback for unknown kinds.
+
+Each override function receives `{ node, graph, onNavigateToNode }` and must return a `ReactNode`. The platform kind-specific components (`KnowledgeNodeView`, `SystemDescribeView`, etc.) are all exported from `@elevasis/ui/knowledge` so you can compose them inside your override rather than replacing them from scratch:
+
+```tsx
+const MyDescribeNodeView = createDescribeNodeDispatcher({
+  system: ({ node, graph, onNavigateToNode }) => (
+    <>
+      {/* Platform view for the standard fields */}
+      <SystemDescribeView node={node} graph={graph} onNavigateToNode={onNavigateToNode} />
+      {/* Project-specific extension panel below */}
+      <MySystemAuditPanel systemId={node.id} />
+    </>
+  ),
+})
+```
+
+### Phase 1.5 Exports Reference
+
+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`                         |
+| `createDescribeNodeDispatcher` | `@elevasis/ui/knowledge` | Factory for per-kind overrides; returns a `DescribeNodeView`-shape component |
+| `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`                      |
+
+`KnowledgeSidebarMiddle` gains an optional `segments?: KnowledgeSegment[]` prop (defaults to `KNOWLEDGE_SEGMENTS`). The `KnowledgeSegment` type is exported from `@elevasis/ui/knowledge`.
+
+## See Also
+
+- [Composition and Extensibility](../composition-extensibility.mdx) -- the general sidebar override pattern this recipe follows (CRM + delivery examples)
+- [Query the Knowledge Graph](query-the-knowledge-graph.md) -- CLI walkthrough of the same five mount axes
+- [Contracts Reference](../reference/contracts.md) -- `SystemModule`, `NavItem`, `OrgKnowledgeNode` TypeScript shapes

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

@@ -1,14 +1,14 @@
----
-title: Customize organization-model.ts
-description: Annotated walkthrough for customizing the flat Organization Model in template-derived projects.
----
 <!-- @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 one flat feature list, derives hierarchy from dotted IDs, and binds resources through graph links declared on resource metadata.
+`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
 
@@ -24,61 +24,89 @@ import {
 - `createFoundationOrganizationModel` resolves defaults and returns the canonical model plus UI-facing helpers.
 - `OrganizationModel` is the fully resolved model type.
 
-## Features
+## Systems
 
-The `features` array is the source of truth for navigation, labels, enabled state, admin visibility, and development-only visibility.
+The `systems` map is the source of truth for semantic hierarchy, lifecycle, admin visibility, and governed ownership.
 
 ```ts
 const override = defineOrganizationModel({
-  features: [
-    {
+  systems: {
+    dashboard: {
       id: 'dashboard',
+      order: 10,
       label: 'Dashboard',
-      enabled: true,
-      path: '/',
-      icon: 'feature.dashboard',
-      uiPosition: 'sidebar-primary'
+      lifecycle: 'active',
+      description: 'Command Center home'
     },
-    {
+    sales: {
       id: 'sales',
+      order: 20,
       label: 'Sales',
-      enabled: true,
-      icon: 'feature.sales',
-      uiPosition: 'sidebar-primary'
+      lifecycle: 'active'
     },
-    {
+    'sales.crm': {
       id: 'sales.crm',
+      order: 30,
       label: 'CRM',
-      enabled: true,
-      path: '/crm'
-    },
-    {
-      id: 'admin',
-      label: 'Admin',
-      enabled: true,
-      path: '/admin',
-      uiPosition: 'sidebar-bottom',
-      requiresAdmin: true
+      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: {}
+    }
+  }
 })
 ```
 
-Feature field reference:
+System field reference:
 
-- `id` -- lowercase dotted path. Parent features are inferred from prefix segments.
+- `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.
-- `enabled` -- organization default.
-- `path` -- route path for leaf nodes. Containers omit it.
-- `icon` and `color` -- optional display metadata. Use semantic icon tokens such as `feature.dashboard`, `feature.sales`, or project-owned `custom.*` tokens; UI icon libraries are implementation details.
-- `uiPosition` -- `sidebar-primary` or `sidebar-bottom`; descendants inherit it.
+- `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.
-- `devOnly` -- hides the node outside development contexts; descendants inherit it.
+- `actions` / `policies` -- references to cross-cutting domains.
+
+## 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.entries`. Workflows, agents, and integrations import those descriptors and derive runtime `resourceId` / `type` from them while still declaring semantic graph links in resource metadata.
+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
@@ -87,8 +115,9 @@ import { defineResources } from '@elevasis/core/organization-model'
 export const resourceDescriptors = defineResources({
   leadImport: {
     id: 'lead-import',
+    order: 10,
     kind: 'workflow',
-    systemId: 'sys.prospecting',
+    systemPath: 'sales.crm',
     ownerRoleId: 'role-ops-lead',
     status: 'active'
   }
@@ -102,17 +131,16 @@ config: {
   type: resourceDescriptors.leadImport.kind,
   version: '1.0.0',
   status: 'prod',
-  links: [{ nodeId: 'feature:sales.lead-gen', kind: 'operates-on' }],
   category: 'production'
 }
 ```
 
 Use kind-prefixed graph IDs for cross-collection links:
 
-- `feature:sales.crm`
+- `system:sales.crm`
 - `integration:instantly`
 - `resource:lead-import`
-- `capability:operations.queue.review`
+- `action:operations.queue.review`
 
 `category` is one of `production`, `diagnostic`, `internal`, or `testing`.
 
@@ -150,10 +178,10 @@ export const organizationModel = foundation.model
 export const { getOrganizationSurface } = foundation
 ```
 
-Pass `canonicalOrganizationModel` to `ElevasisFeaturesProvider` in `ui/src/routes/__root.tsx`.
+Pass `canonicalOrganizationModel` to `ElevasisSystemsProvider` in `ui/src/routes/__root.tsx`.
 
 ## Resolve Behavior
 
-`createFoundationOrganizationModel(override)` resolves defaults, validates feature hierarchy, and exposes helper functions used by the shell. Arrays are replaced wholesale, so if you provide `features`, include every feature the app should expose.
+`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 feature IDs, missing parent containers, invalid graph IDs, and invalid sidebar positions.
+Validation catches duplicate System IDs, missing parent Systems, invalid graph IDs, and invalid UI paths.