@elevasis/sdk 1.22.0 → 1.23.0

package/reference/claude-config/sync-notes/2026-05-14-organization-model-ontology-refactor.md

@@ -2,7 +2,7 @@
 
 ## Why this note exists
 
-The template now demonstrates the Organization Model ontology bridge. New semantic contracts should be authored in `System.ontology`, while legacy `entities`, `actions`, and `System.content` remain compatibility mirrors for current consumers.
+The template now demonstrates the Organization Model ontology and topology bridge. New semantic contracts should be authored in `System.ontology`; executable Resources bind through `resource.ontology.actions` and optional `resource.ontology.primaryAction`; durable operational wiring belongs in `organizationModel.topology.relationships`. Legacy `entities`, `actions`, and `System.content` remain compatibility mirrors for current consumers.
 
 ## Applies to
 
@@ -14,13 +14,15 @@ The template now demonstrates the Organization Model ontology bridge. New semant
 - `operations/src/resource-registry.test.ts`
 - `operations/src/README.md`
 - `.claude/rules/organization-model.md`
+- `.claude/rules/operations.md`
 
 ## Required actions
 
 1. Preserve system-colocated ontology scopes when syncing template organization-model changes.
-2. Preserve Resource descriptor `ontologyBinding`, `actionKey`, and `codeRefs` together.
-3. Keep `entities`, `actions`, and `System.content` aligned as compatibility mirrors until downstream consumers move fully to compiled ontology indexes.
-4. Do not overwrite project-owned `core/config/extensions/**` files.
+2. Migrate Resource descriptors from `ontology.implements` / `actionKey` to `ontology.actions` / `ontology.primaryAction`; keep `codeRefs` with the Resource descriptor.
+3. Preserve `organizationModel.topology.relationships` when syncing template organization-model changes; keep secrets, credential values, provider webhook mechanics, and per-run state outside the OM.
+4. Keep `entities`, `actions`, and `System.content` aligned as compatibility mirrors until downstream consumers move fully to compiled ontology indexes.
+5. Do not overwrite project-owned `core/config/extensions/**` files.
 
 ## Verification
 
@@ -38,5 +40,6 @@ pnpm sync:verify --pre
 ## Not handled by /git-sync
 
 - Choosing project-specific ontology IDs for tenant-owned systems.
+- Choosing project-specific topology relationships for tenant-owned workflows, checkpoints, integrations, or schedules.
 - Migrating project-owned extension files under `core/config/extensions/**`.
 - Retiring compatibility mirrors before the full internal, SDK, scaffold, and external template-family green cycle.

package/reference/claude-config/sync-notes/2026-05-15-om-skill-rename-and-write-family.md

@@ -0,0 +1,52 @@
+# OM Skill Rename + Write Family Release Train
+
+## Why this note exists
+
+This release train renames the tenant `/knowledge` skill to `/om` and broadens it, ports `om:search` / `om:describe` to the `elevasis-sdk` CLI, and bumps the `@elevasis/core` and `@elevasis/sdk` dependency baselines. The template `.claude` skill surface changed shape (a directory was renamed and slash-command references were rewritten across CLAUDE.md, rules, and adjacent skills), and `@elevasis/core` / `@elevasis/sdk` published new exports and CLI commands. Ordinary git merge does not reconcile a managed `.claude` skill rename or pull republished package baselines, so template-derived projects need an operative note.
+
+This note covers the `om-skill` workstream (the `/knowledge` -> `/om` rename + SDK CLI port) and the package-baseline cascades from the same train (`@elevasis/core` minor from `om-skill` + `om-create-skill`; `@elevasis/sdk` minor from `om-skill`). It does NOT cover the unrelated Shared-UI-Migration changes under `external/_template/ui/**`, which are a separate workstream and not part of this train.
+
+## Applies to
+
+- `external/_template/.claude/skills/om/SKILL.md` (renamed from `external/_template/.claude/skills/knowledge/SKILL.md`; canonical 5-bucket decision tree with the tenant Codify/Toggle ceremony preserved)
+- `external/_template/.claude/skills/om/operations/*.md` (10 files moved from `knowledge/operations/`; `elevasis-sdk knowledge:*` references rewritten to `elevasis-sdk om:*`, `/knowledge` footers rewritten to `/om`)
+- `external/_template/.claude/skills/knowledge/` (DELETED — directory removed; tombstone, do not re-create on sync)
+- `external/_template/CLAUDE.md` (Slash Commands table — `/knowledge` -> `/om`)
+- `external/_template/.claude/rules/{organization-model,organization-os,vibe}.md` (slash-command references)
+- `external/_template/.claude/skills/{setup,project,tutorial}/*.md` (slash-command references)
+- `external/_template/core/package.json` (`@elevasis/core` baseline -> 0.25.0)
+- `external/_template/operations/package.json` (`@elevasis/core` -> 0.25.0 and `@elevasis/sdk` -> 1.23.0 baselines)
+
+Package baselines become concrete only after the `core` and `sdk` publish stages of `/sdk ship` complete; the `.claude` skill rename is template-authored and already present in `external/_template`.
+
+## Required actions
+
+1. Apply the managed `.claude` skill rename atomically: create `.claude/skills/om/` (SKILL.md + `operations/`) and delete `.claude/skills/knowledge/` in the same sync. Never leave both directories present — two skills advertising the same scope is the exact confusion the rename removes.
+2. Preserve any tenant-owned Codify/Toggle ceremony content in the project's `om/SKILL.md` Write-Power section; do not overwrite project-authored knowledge node content under `core/config/knowledge/**` (the content directory is separate from the slash-command name).
+3. Rewrite `/knowledge` -> `/om` and `elevasis-sdk knowledge:*` -> `elevasis-sdk om:*` references in managed surfaces only; `knowledge:*` CLI aliases remain valid, so do not hard-fail on legacy invocations in project-owned files.
+4. After the `/sdk ship` publish stages land, bump the `@elevasis/core` (0.25.0) and `@elevasis/sdk` (1.23.0) baselines in `core/package.json` and `operations/package.json`, then reinstall.
+5. The `/om` write sub-skill family (`verify` / `create` / `rename` / `deprecate`) is intentionally NOT ported to the tenant template in this train (deferred to a dedicated task). Do not scaffold those tenant operations from this sync.
+
+## Verification
+
+Run the template verification lane after applying this sync:
+
+```bash
+pnpm sync:verify --pre
+pnpm external:verify
+pnpm -C external/_template/operations check-types
+pnpm -C external/_template/operations test
+```
+
+Then confirm in each downstream project:
+
+- `.claude/skills/om/` exists with `SKILL.md` + `operations/`; `.claude/skills/knowledge/` is gone.
+- `elevasis-sdk om:search "<query>"` and `elevasis-sdk om:describe <id>` resolve against the tenant's organization model; legacy `elevasis-sdk knowledge:*` still aliases.
+- `@elevasis/core` resolves to >= 0.25.0 and `@elevasis/sdk` to >= 1.23.0.
+
+## Not handled by /git-sync
+
+- Publishing `@elevasis/core` (0.25.0) or `@elevasis/sdk` (1.23.0) — owned by `/sdk ship` publish stages.
+- Redeploying the SDK resources bundle (`elevasis-operations`) after the `@elevasis/sdk` publish.
+- Tenant-specific conflict resolution in dirty external project worktrees, including reconciling any project-authored edits to the former `knowledge/SKILL.md`.
+- The unrelated Shared-UI-Migration changes under `external/_template/ui/**` (separate workstream; not in this train's scope).

package/reference/examples/organization-model.ts

@@ -217,13 +217,15 @@ export const customersAndOfferingsExample = defineOrganizationModel({
 export const workflowResourceDescriptorsExample = defineResources({
   leadEnrichment: {
     id: 'lead-enrichment-workflow',
+    title: 'Lead Enrichment',
+    description: 'Enriches lead records and writes qualified opportunities into CRM.',
     kind: 'workflow',
     systemPath: 'sales.lead-gen',
     ownerRoleId: 'role-ops-lead',
-    actionKey: 'prospecting.lead-enrichment',
     status: 'active' as const,
     ontology: {
-      implements: ['sales.lead-gen:action/lead.enrich'],
+      actions: ['sales.lead-gen:action/lead.enrich'],
+      primaryAction: 'sales.lead-gen:action/lead.enrich',
       reads: ['sales.lead-gen:object/lead'],
       writes: ['sales.crm:object/deal'],
       usesCatalogs: ['sales.crm:catalog/pipeline'],
@@ -256,6 +258,28 @@ export const compatibilityGraphLinksExample = {
   ]
 }
 
+export const topologyRelationshipsExample = defineOrganizationModel({
+  topology: {
+    relationships: [
+      {
+        source: { kind: 'trigger', id: 'daily-lead-enrichment' },
+        target: { kind: 'resource', id: workflowResourceDescriptorsExample.leadEnrichment.id },
+        kind: 'triggers'
+      },
+      {
+        source: { kind: 'resource', id: workflowResourceDescriptorsExample.leadEnrichment.id },
+        target: { kind: 'externalResource', id: 'apollo' },
+        kind: 'uses'
+      },
+      {
+        source: { kind: 'resource', id: workflowResourceDescriptorsExample.leadEnrichment.id },
+        target: { kind: 'role', id: 'role-ops-lead' },
+        kind: 'approval'
+      }
+    ]
+  }
+})
+
 // ---------------------------------------------------------------------------
 // Roles and goals
 // ---------------------------------------------------------------------------

package/reference/scaffold/core/organization-model.mdx

@@ -138,17 +138,22 @@ Resource identity is authored in the OM Resources domain. Operations imports des
 ```ts
 import { defineResources } from '@elevasis/core/organization-model'
 
-export const resourceDescriptors = defineResources({
-  leadImport: {
-    id: 'lgn-01c-apollo-import-workflow',
-    kind: 'workflow',
-    systemPath: 'sales.lead-gen',
-    ownerRoleId: 'role-ops-lead',
-    status: 'active',
-    actionKey: 'lead-gen.company.apollo-import',
-    codeRefs: [
-      {
-        path: 'packages/elevasis-operations/src/sales/prospecting/scrape/apollo-import.ts',
+export const resourceDescriptors = defineResources({
+  leadImport: {
+    id: 'lgn-01c-apollo-import-workflow',
+    title: 'Apollo Import',
+    description: 'Imports Apollo company records into the lead generation pipeline.',
+    kind: 'workflow',
+    systemPath: 'sales.lead-gen',
+    ownerRoleId: 'role-ops-lead',
+    status: 'active',
+    ontology: {
+      actions: ['sales.lead-gen:action/company.apollo-import'],
+      primaryAction: 'sales.lead-gen:action/company.apollo-import'
+    },
+    codeRefs: [
+      {
+        path: 'packages/elevasis-operations/src/sales/prospecting/scrape/apollo-import.ts',
         role: 'entrypoint',
         symbol: 'lgnApolloImportWorkflow'
       }

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

@@ -176,15 +176,16 @@ Resources are governed descriptors for executable workflows, agents, integration
 import { defineResources } from '@elevasis/core/organization-model'
 
 export const resourceDescriptors = defineResources({
-  approveReviewItem: {
-    id: 'approve-review-item-workflow',
-    order: 10,
-    kind: 'workflow',
-    systemPath: 'operations.review',
-    ownerRoleId: 'role-ops-lead',
-    status: 'active',
-    actionKey: 'operations.review.approve',
-    codeRefs: [
+  approveReviewItem: {
+    id: 'approve-review-item-workflow',
+    title: 'Approve review item',
+    description: 'Routes a review item through the operations approval workflow.',
+    order: 10,
+    kind: 'workflow',
+    systemPath: 'operations.review',
+    ownerRoleId: 'role-ops-lead',
+    status: 'active',
+    codeRefs: [
       {
         path: 'operations/src/review/approve-review-item/index.ts',
         role: 'entrypoint',
@@ -194,9 +195,10 @@ export const resourceDescriptors = defineResources({
         path: 'operations/src/review/approve-review-item/approve-review-item.test.ts',
         role: 'test'
       }
-    ],
+    ],
     ontology: {
-      implements: ['operations.review:action/review-item.approve'],
+      actions: ['operations.review:action/review-item.approve'],
+      primaryAction: 'operations.review:action/review-item.approve',
       reads: ['operations.review:object/review-item'],
       writes: ['operations.review:object/review-item'],
       emits: ['operations.review:event/review-item.approved']
@@ -205,15 +207,15 @@ export const resourceDescriptors = defineResources({
 })
 ```
 
-Use `actionKey` only when a Resource implements a stable action contract. Keep it URL-safe because some runtimes expose action keys in route params. Resource-only workflows, diagnostics, and helper scripts can stay unbound.
+Use descriptor `title` and `description` for executable display metadata.
 
-Use nested `resource.ontology` bindings for the semantic actions, objects, catalogs, and events a Resource implements, reads, writes, uses, or emits. Top-level resource `emits` remains readable for bridge-era descriptors, but new descriptors should keep event bindings in `resource.ontology.emits`.
+Use nested `resource.ontology` bindings for the semantic actions, objects, catalogs, and events a Resource performs, reads, writes, uses, or emits. `resource.ontology.primaryAction` is the default/selectable ontology action and must be included in `resource.ontology.actions`. Top-level resource `emits` remains readable for bridge-era descriptors, but new descriptors should keep event bindings in `resource.ontology.emits`.
 
 Use `codeRefs` as repo-relative breadcrumbs for agents and operators. They point from the governed Resource descriptor to implementation files; they do not define resource identity, System membership, runtime topology, or graph links.
 
 ## 6. Bind Runtime to the Descriptor
 
-Workflow and agent code owns schemas, handlers, steps, and runtime behavior. It should import the descriptor and derive `resourceId`, `type`, and `actionKey`.
+Workflow and agent code owns schemas, handlers, steps, and runtime behavior. It should import the descriptor and derive `resourceId`, `type`, and display metadata from it.
 
 ```ts
 import type { WorkflowDefinition } from '@elevasis/sdk'
@@ -221,15 +223,15 @@ import { resourceDescriptors } from '@core/config/organization-model'
 
 export const approveReviewItemWorkflow: WorkflowDefinition = {
   config: {
-    resource: resourceDescriptors.approveReviewItem,
-    resourceId: resourceDescriptors.approveReviewItem.id,
-    name: 'Approve review item',
-    type: resourceDescriptors.approveReviewItem.kind,
-    version: '1.0.0',
-    status: 'dev',
-    category: 'production',
-    actionKey: resourceDescriptors.approveReviewItem.actionKey
-  },
+    resource: resourceDescriptors.approveReviewItem,
+    resourceId: resourceDescriptors.approveReviewItem.id,
+    name: resourceDescriptors.approveReviewItem.title,
+    description: resourceDescriptors.approveReviewItem.description,
+    type: resourceDescriptors.approveReviewItem.kind,
+    version: '1.0.0',
+    status: 'dev',
+    category: 'production'
+  },
   contract: {
     inputSchema,
     outputSchema
@@ -255,7 +257,7 @@ export const org = {
 }
 ```
 
-Use `relationships` for execution topology. Use `systemPath`, `resource.ontology`, and `actionKey` for semantic topology. Existing compatibility graph links can stay readable while old consumers migrate.
+Use `organizationModel.topology.relationships` for durable execution topology. The initial topology relationship kinds are `triggers`, `uses`, and `approval`; use `systemPath` and `resource.ontology` for semantic binding. Existing compatibility graph links can stay readable while old consumers migrate.
 
 ## 7. Add UI Wiring
 
@@ -304,7 +306,7 @@ function ReviewLayout() {
 Add tests for the boundaries you changed:
 
 - OM config tests for systems, ontology object/action/catalog records, resources, and any compatibility `System.content`.
-- Runtime registry tests that deployed workflows import descriptors and keep `resourceId`, `type`, and `actionKey` aligned.
+- Runtime registry tests that deployed workflows import descriptors and keep `resourceId`, `type`, title, description, and `resource.ontology.primaryAction` aligned.
 - UI tests or type checks for route, manifest, and guard wiring.
 - Graph or knowledge tests when new ontology records, resources, compatibility content nodes, or emitted events should appear in Command View.
 - Scaffold sync when new docs or generated scaffold references are affected.
@@ -327,7 +329,7 @@ pnpm verify:scaffold-reference
 - Ontology catalog types contain local vocabularies such as pipelines, stages, templates, and status flows.
 - Compatibility `System.content` is used only for existing bridge-era local catalogs or schemas.
 - Each executable workflow or agent has an OM Resource descriptor with `systemPath`.
-- `actionKey` is present only when the Resource implements a stable action contract.
+- Executable Resources use descriptor `title` / `description`, `resource.ontology.actions`, and `resource.ontology.primaryAction`.
 - `codeRefs` point to useful entrypoints, handlers, schemas, tests, docs, or config.
 - Runtime assembly imports descriptors and derives identity from them.
 - UI routes, manifests, and guards use the same System ID.

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

@@ -20,16 +20,18 @@ Add the descriptor in `core/config/organization-model.ts`:
 import { defineResources } from '@elevasis/core/organization-model'
 
 export const resourceDescriptors = defineResources({
-  myWorkflow: {
+  myWorkflow: {
     id: 'my-workflow',
+    title: 'My Workflow',
+    description: 'Runs the governed work item workflow.',
     order: 10,
     kind: 'workflow',
     systemPath: 'operations',
     ownerRoleId: 'role-ops-lead',
     status: 'active',
-    actionKey: 'operations.my-workflow',
     ontology: {
-      implements: ['operations:action/my-workflow.run'],
+      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'],
@@ -63,7 +65,7 @@ Use `organizationModel.resources` as the Resources descriptor catalog. Graph ref
 
 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 `actionKey` only when the resource implements a stable runtime action key. Use nested `resource.ontology` bindings to declare which ontology actions, objects, catalogs, and events the resource implements, reads, writes, uses, or emits. Optional top-level resource `emits` remains readable for bridge-era event descriptors, but new descriptors should keep event bindings in `resource.ontology.emits`.
+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
 
@@ -124,18 +126,26 @@ 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 `relationships` for runtime execution relationships. 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.
+Use `organizationModel.topology.relationships` for durable execution topology:
+
+```ts
+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'
+    }
+  ]
+}
+```
+
+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
 

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

@@ -206,14 +206,16 @@ import { defineResources } from '@elevasis/core/organization-model'
 export const resourceDescriptors = defineResources({
   leadImport: {
     id: 'lead-import',
+    title: 'Lead Import',
+    description: 'Updates CRM deal stage data from imported lead records.',
     order: 10,
     kind: 'workflow',
     systemPath: 'sales.crm',
     ownerRoleId: 'role-ops-lead',
     status: 'active',
-    actionKey: 'sales.crm.deal.update-stage',
     ontology: {
-      implements: ['sales.crm:action/deal.update-stage'],
+      actions: ['sales.crm:action/deal.update-stage'],
+      primaryAction: 'sales.crm:action/deal.update-stage',
       reads: ['sales.crm:object/deal'],
       writes: ['sales.crm:object/deal'],
       usesCatalogs: ['sales.crm:catalog/pipeline'],
@@ -243,7 +245,7 @@ Use kind-prefixed graph IDs for cross-collection links:
 
 `category` is one of `production`, `diagnostic`, `internal`, or `testing`.
 
-`actionKey` mirrors a stable runtime action key when the resource has one. Use nested `resource.ontology` bindings to declare which ontology actions, objects, catalogs, and events the resource implements, reads, writes, uses, or emits. Resource event emissions can still be declared through top-level `emits` for older descriptors, but new descriptors should use `resource.ontology.emits`.
+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`.
 
 ## Compatibility Domain Mirrors
 

package/reference/scaffold/recipes/extend-lead-gen.md

@@ -210,15 +210,15 @@ const companyCleanupLayout: StepConfigLayout<CompanyCleanupInput> = {
 }
 
 const listActions: ListBuilderRegistry = [
-  {
-    resourceId: companyCleanupResource.id,
-    workflowId: companyCleanupResource.id,
-    actionKey: 'lead-gen.company.cleanup',
-    label: 'Company Cleanup',
-    description: 'Normalize and clean company records for the list.',
-    category: 'utility',
-    stagesAffected: ['populated'],
-    schema: companyCleanupInputSchema,
+  {
+    resourceId: companyCleanupResource.id,
+    workflowId: companyCleanupResource.id,
+    actionKey: companyCleanupResource.ontology.primaryAction ?? companyCleanupResource.ontology.actions[0],
+    label: companyCleanupResource.title,
+    description: companyCleanupResource.description,
+    category: 'utility',
+    stagesAffected: ['populated'],
+    schema: companyCleanupInputSchema,
     layout: companyCleanupLayout,
     defaultInput: (list) => ({
       listId: list.id,

package/reference/scaffold/recipes/index.md

@@ -17,7 +17,7 @@ Before starting, read [glossary.md](../reference/glossary.md) to disambiguate ov
 ## Recipes
 
 **[Add an OM-Backed System](add-a-feature.md)**
-You want a new system with cohesive Organization Model semantics, executable resources, and optional UI. Covers Systems, System-owned ontology and config, Resource descriptors with `resource.ontology`, `actionKey`, `codeRefs`, runtime assembly, manifests, routes, guards, tests, and compatibility notes for old `System.content` consumers.
+You want a new system with cohesive Organization Model semantics, executable resources, and optional UI. Covers Systems, System-owned ontology and config, Resource descriptors with `title`, `description`, `resource.ontology.actions`, `primaryAction`, `codeRefs`, OM topology, runtime assembly, manifests, routes, guards, tests, and compatibility notes for old `System.content` consumers.
 
 **[Add a Resource](add-a-resource.md)**
 You want a new workflow or agent deployed to the platform. Covers OM Resource descriptor authoring, descriptor-backed `WorkflowDefinition` binding, `DeploymentSpec` assembly, relationship declarations, and CLI verification.