@elevasis/sdk 1.21.0 → 1.22.1

package/reference/scaffold/recipes/add-a-resource.md

@@ -1,124 +1,158 @@
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
----
-title: Add a Resource
-description: Add an OM-owned workflow or agent descriptor, bind executable behavior in operations, and verify descriptor-backed deployment.
----
-
-# Add a Resource
-
-Resources are governed descriptors in the Organization Model. The OM owns resource identity, System membership, owner role, and lifecycle status. Operations code imports those descriptors, attaches executable workflow or agent behavior, and exports a `DeploymentSpec` for deployment.
-
-Do not keep a second identity catalog in operations. `DeploymentSpec` is the runtime/deploy assembly artifact; it should not be the place where a workflow ID is invented.
-
-## 1. Author the OM descriptor
-
-Add the descriptor in `core/config/organization-model.ts`:
-
-```ts
-import { defineResources } from '@elevasis/core/organization-model'
-
-export const resourceDescriptors = defineResources({
+---
+title: Add a Resource
+description: Add an OM-owned workflow or agent descriptor, bind executable behavior in operations, and verify descriptor-backed deployment.
+---
+
+# Add a Resource
+
+Resources are governed descriptors in the Organization Model. The OM owns resource identity, System membership, owner role, and lifecycle status. Operations code imports those descriptors, attaches executable workflow or agent behavior, and exports a `DeploymentSpec` for deployment.
+
+Do not keep a second identity catalog in operations. `DeploymentSpec` is the runtime/deploy assembly artifact; it should not be the place where a workflow ID is invented.
+
+## 1. Author the OM descriptor
+
+Add the descriptor in `core/config/organization-model.ts`:
+
+```ts
+import { defineResources } from '@elevasis/core/organization-model'
+
+export const resourceDescriptors = defineResources({
   myWorkflow: {
     id: 'my-workflow',
+    title: 'My Workflow',
+    description: 'Runs the governed work item workflow.',
     order: 10,
     kind: 'workflow',
-    systemPath: 'sys.operations',
+    systemPath: 'operations',
     ownerRoleId: 'role-ops-lead',
     status: 'active',
-    actionKey: 'operations.my-workflow'
-  }
-})
-```
-
-Then expose the descriptor catalog through the Organization Model:
-
-```ts
-export const resourceGovernanceModel = {
-  systems,
-  resources: resourceDescriptors
-} as const
-```
-
+    ontology: {
+      actions: ['operations:action/my-workflow.run'],
+      primaryAction: 'operations:action/my-workflow.run',
+      reads: ['operations:object/work-item'],
+      writes: ['operations:object/work-item'],
+      usesCatalogs: ['operations:catalog/workflow-status'],
+      emits: ['operations:event/my-workflow.completed']
+    },
+    codeRefs: [
+      {
+        path: 'operations/src/my-workflow/index.ts',
+        role: 'entrypoint',
+        symbol: 'myWorkflow'
+      },
+      {
+        path: 'operations/src/my-workflow/my-workflow.test.ts',
+        role: 'test'
+      }
+    ]
+  }
+})
+```
+
+Then expose the descriptor catalog through the Organization Model:
+
+```ts
+export const resourceGovernanceModel = {
+  systems,
+  resources: resourceDescriptors
+} as const
+```
+
 Use `organizationModel.resources` as the Resources descriptor catalog. Graph references still use kind-prefixed IDs, such as `system:sales.crm`, `resource:lead-import`, or `action:operations.queue.review`, when runtime behavior needs semantic graph binding.
 
-## 2. Author executable behavior
-
-Operations code owns schemas, steps, handlers, triggers, and UI execution metadata. Import the descriptor and derive runtime identity from it at the binding boundary:
+Use `codeRefs` as repo-relative implementation breadcrumbs for agents and operators. They do not define resource identity, System membership, runtime topology, or graph links; they point from the governed Resource descriptor to the files that implement, validate, or document it.
+
+Use descriptor `title` and `description` for 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` is the default/selectable ontology action and must be included in `resource.ontology.actions`. Optional top-level resource `emits` remains readable for bridge-era event descriptors, but new descriptors should keep event bindings in `resource.ontology.emits`.
+
+## 2. Author executable behavior
+
+Operations code owns schemas, steps, handlers, triggers, and UI execution metadata. Import the descriptor and derive runtime identity from it at the binding boundary:
+
+```ts
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { resourceDescriptors } from '@core/config/organization-model'
+
+export const myWorkflow: WorkflowDefinition = {
+  config: {
+    resource: resourceDescriptors.myWorkflow,
+    resourceId: resourceDescriptors.myWorkflow.id,
+    name: 'My Workflow',
+    type: resourceDescriptors.myWorkflow.kind,
+    version: '1.0.0',
+    status: 'dev',
+    category: 'production'
+  },
+  contract: {
+    inputSchema,
+    outputSchema
+  },
+  steps: {
+    run: {
+      id: 'run',
+      name: 'Run',
+      handler: async (_input, context) => {
+        context.logger.info('[my-workflow] starting')
+        return { ok: true }
+      },
+      inputSchema,
+      outputSchema,
+      next: null
+    }
+  },
+  entryPoint: 'run'
+}
+```
+
+`category` is one of `production`, `diagnostic`, `internal`, or `testing`.
+
+## 3. Register in the deployment spec
+
+```ts
+import { resourceGovernanceModel } from '@core/config/organization-model'
+import { myWorkflow } from './my-workflow/index.js'
+
+export const org = {
+  version: '0.1.0',
+  organizationModel: resourceGovernanceModel,
+  workflows: [myWorkflow],
+  agents: []
+}
+```
+
+Use `.js` extensions in TypeScript source imports for ESM compatibility.
+
+## 4. Declare runtime relationships
+
+Use `organizationModel.topology.relationships` for durable execution topology:
 
 ```ts
-import type { WorkflowDefinition } from '@elevasis/sdk'
-import { resourceDescriptors } from '@core/config/organization-model'
-
-export const myWorkflow: WorkflowDefinition = {
-  config: {
-    resource: resourceDescriptors.myWorkflow,
-    resourceId: resourceDescriptors.myWorkflow.id,
-    name: 'My Workflow',
-    type: resourceDescriptors.myWorkflow.kind,
-    version: '1.0.0',
-    status: 'dev',
-    category: 'production'
-  },
-  contract: {
-    inputSchema,
-    outputSchema
-  },
-  steps: {
-    run: {
-      id: 'run',
-      name: 'Run',
-      handler: async (_input, context) => {
-        context.logger.info('[my-workflow] starting')
-        return { ok: true }
-      },
-      inputSchema,
-      outputSchema,
-      next: null
+topology: {
+  relationships: [
+    {
+      source: { kind: 'trigger', id: 'daily-work-item-import' },
+      target: { kind: 'resource', id: 'my-workflow' },
+      kind: 'triggers'
+    },
+    {
+      source: { kind: 'resource', id: 'my-workflow' },
+      target: { kind: 'externalResource', id: 'hubspot' },
+      kind: 'uses'
     }
-  },
-  entryPoint: 'run'
+  ]
 }
 ```
 
-`category` is one of `production`, `diagnostic`, `internal`, or `testing`.
-
-## 3. Register in the deployment spec
-
-```ts
-import { resourceGovernanceModel } from '@core/config/organization-model'
-import { myWorkflow } from './my-workflow/index.js'
-
-export const org = {
-  version: '0.1.0',
-  organizationModel: resourceGovernanceModel,
-  workflows: [myWorkflow],
-  agents: []
-}
-```
-
-Use `.js` extensions in TypeScript source imports for ESM compatibility.
-
-## 4. Declare runtime relationships
-
-Use `DeploymentSpec.relationships` for execution topology:
-
-```ts
-relationships: {
-  'my-workflow': {
-    triggers: { workflows: ['email-notification'] },
-    uses: { integrations: ['hubspot'] }
-  }
-}
-```
-
-Use `config.links` for semantic graph binding and `relationships` for runtime execution relationships.
-
-## 5. Verify
-
-```bash
+Use relationship kinds `triggers`, `uses`, and `approval` for the initial topology vocabulary. For semantic graph binding, prefer OM ontology IDs in `resource.ontology`; keep `config.links` only when maintaining older descriptors that still need the legacy graph bridge.
+
+## 5. Verify
+
+```bash
 pnpm -C operations check
 pnpm -C operations deploy
 pnpm exec elevasis describe Elevasis/my-workflow
+pnpm scaffold:sync
+pnpm scaffold:verify
 ```

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

@@ -26,7 +26,7 @@ export default defineConfig({
 
 `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.
+Knowledge node icons are authored as semantic data tokens in MDX frontmatter, not as UI library component names. Use `playbook`, `strategy`, or `reference` by node kind, or a project-owned `custom.*` token when the platform catalog does not cover the concept.
 
 ## Author a Knowledge Node
 
@@ -42,7 +42,7 @@ Required frontmatter fields:
 
 Optional frontmatter fields:
 
-- `icon` -- semantic token such as `knowledge.playbook` (defaults by kind if omitted)
+- `icon` -- semantic token such as `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
 
@@ -54,7 +54,7 @@ id: knowledge.internal-runbook
 kind: playbook
 title: Internal Runbook
 description: Operating notes for project-specific support and escalation.
-icon: knowledge.playbook
+icon: playbook
 ownerIds:
   - role.operator
 links:
@@ -203,7 +203,7 @@ The `knowledgePlugin()` Vite plugin is still needed in this path because it gene
 | `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          |
+| `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.
 
@@ -380,5 +380,5 @@ The following exports are added in Phase 1.5 on top of the exports table above:
 ## 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
+- [Query the Knowledge Graph](query-the-knowledge-graph.md) -- CLI walkthrough of the same six query axes
 - [Contracts Reference](../reference/contracts.md) -- `SystemModule`, `NavItem`, `OrgKnowledgeNode` TypeScript shapes