@elevasis/sdk 1.22.0 → 1.23.0

package/dist/worker/index.js

@@ -4611,6 +4611,7 @@ var ORGANIZATION_MODEL_ICON_TOKENS = [
   "crm",
   "lead-gen",
   "projects",
+  "clients",
   "operations",
   "monitoring",
   "knowledge",
@@ -6167,7 +6168,6 @@ function addLegacyEntityProjections(index, diagnostics, sourcesById, entities) {
           table: entity.table
         }
       } : {},
-      legacyEntityId: entity.id,
       ...entity.rowSchema !== void 0 ? { rowSchema: entity.rowSchema } : {},
       ...entity.stateCatalogId !== void 0 ? { stateCatalogId: entity.stateCatalogId } : {}
     };
@@ -6192,8 +6192,7 @@ function addLegacyEntityProjections(index, diagnostics, sourcesById, entities) {
         from: legacyObjectId(entity),
         to: legacyObjectId(targetEntity),
         cardinality: link.kind,
-        ...link.via !== void 0 ? { via: link.via } : {},
-        legacyEntityId: entity.id
+        ...link.via !== void 0 ? { via: link.via } : {}
       };
       addRecord(index, diagnostics, sourcesById, "linkTypes", linkType, {
         source: "legacy.entities.links",
@@ -6251,8 +6250,7 @@ function addSystemContentProjections(index, diagnostics, sourcesById, systemPath
       kind: node.type,
       ...typeof node.data?.["entityId"] === "string" ? { appliesTo: formatOntologyId({ scope: systemPath, kind: "object", localId: node.data["entityId"] }) } : {},
       ...Object.keys(entries).length > 0 ? { entries } : {},
-      ...node.data !== void 0 ? { data: node.data } : {},
-      legacyContentId: `${systemPath}:${localId}`
+      ...node.data !== void 0 ? { data: node.data } : {}
     };
     addRecord(index, diagnostics, sourcesById, "catalogTypes", catalogType, {
       source: "legacy.system.content",
@@ -6430,11 +6428,20 @@ EventEmissionDescriptorSchema.extend({
   ownerKind: z.enum(["resource", "entity"]).meta({ label: "Owner kind" })
 });
 var ResourceOntologyBindingSchema = z.object({
-  implements: z.array(OntologyIdSchema).optional(),
+  actions: z.array(OntologyIdSchema).optional(),
+  primaryAction: OntologyIdSchema.optional(),
   reads: z.array(OntologyIdSchema).optional(),
   writes: z.array(OntologyIdSchema).optional(),
   usesCatalogs: z.array(OntologyIdSchema).optional(),
   emits: z.array(OntologyIdSchema).optional()
+}).superRefine((binding, ctx) => {
+  if (binding.primaryAction === void 0) return;
+  if (binding.actions?.includes(binding.primaryAction)) return;
+  ctx.addIssue({
+    code: z.ZodIssueCode.custom,
+    path: ["primaryAction"],
+    message: "Resource ontology primaryAction must be included in actions"
+  });
 });
 var CodeReferenceSchema = z.object({
   path: z.string().trim().min(1).max(500).regex(/^[A-Za-z0-9_./$@()[\] -]+$/, "Code reference paths must be repo-relative paths"),
@@ -6449,6 +6456,10 @@ var ResourceEntryBaseSchema = z.object({
   order: z.number().default(0),
   /** Required single System membership — value is a dot-separated system path (e.g. "sales.lead-gen"). */
   systemPath: SystemPathSchema.meta({ ref: "system" }),
+  /** Executable display title owned by the OM Resource descriptor. */
+  title: LabelSchema.optional(),
+  /** Executable display description owned by the OM Resource descriptor. */
+  description: DescriptionSchema.optional(),
   /** Optional role responsible for maintaining this resource. */
   ownerRoleId: ModelIdSchema.meta({ ref: "role" }).optional(),
   status: ResourceGovernanceStatusSchema,
@@ -6463,8 +6474,6 @@ var ResourceEntryBaseSchema = z.object({
 });
 var WorkflowResourceEntrySchema = ResourceEntryBaseSchema.extend({
   kind: z.literal("workflow"),
-  /** Mirrors WorkflowConfig.actionKey when the runtime workflow has one. */
-  actionKey: z.string().trim().min(1).max(255).optional(),
   emits: z.array(EventEmissionDescriptorSchema).optional()
 });
 var AgentResourceEntrySchema = ResourceEntryBaseSchema.extend({
@@ -6606,6 +6615,73 @@ var GoalsDomainSchema = z.record(z.string(), ObjectiveSchema).refine((record) =>
   message: "Each objective entry id must match its map key"
 }).default({});
 var DEFAULT_ORGANIZATION_MODEL_GOALS = {};
+var SecretLikeMetadataKeySchema = /(?:secret|password|passwd|token|api[-_]?key|credential|private[-_]?key)/i;
+var SecretLikeMetadataValueSchema = /(?:sk-[A-Za-z0-9_-]{12,}|pk_live_[A-Za-z0-9_-]{12,}|eyJ[A-Za-z0-9_-]{20,}|-----BEGIN (?:RSA |OPENSSH |EC )?PRIVATE KEY-----)/;
+z.enum([
+  "system",
+  "resource",
+  "ontology",
+  "policy",
+  "role",
+  "trigger",
+  "humanCheckpoint",
+  "externalResource"
+]);
+var OmTopologyRelationshipKindSchema = z.enum(["triggers", "uses", "approval"]);
+var OmTopologyNodeRefSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("system"), id: ModelIdSchema }),
+  z.object({ kind: z.literal("resource"), id: ResourceIdSchema }),
+  z.object({ kind: z.literal("ontology"), id: OntologyIdSchema }),
+  z.object({ kind: z.literal("policy"), id: ModelIdSchema }),
+  z.object({ kind: z.literal("role"), id: ModelIdSchema }),
+  z.object({ kind: z.literal("trigger"), id: ResourceIdSchema }),
+  z.object({ kind: z.literal("humanCheckpoint"), id: ResourceIdSchema }),
+  z.object({ kind: z.literal("externalResource"), id: ResourceIdSchema })
+]);
+var OmTopologyMetadataSchema = z.record(z.string().trim().min(1).max(120), JsonValueSchema).superRefine((metadata, ctx) => {
+  function visit(value, path) {
+    if (typeof value === "string" && SecretLikeMetadataValueSchema.test(value)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path,
+        message: "Topology metadata must not contain secret-like values"
+      });
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((entry, index) => visit(entry, [...path, index]));
+      return;
+    }
+    if (typeof value !== "object" || value === null) return;
+    Object.entries(value).forEach(([key, entry]) => {
+      if (SecretLikeMetadataKeySchema.test(key)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [...path, key],
+          message: `Topology metadata key "${key}" looks secret-like`
+        });
+      }
+      visit(entry, [...path, key]);
+    });
+  }
+  visit(metadata, []);
+});
+var OmTopologyRelationshipSchema = z.object({
+  from: OmTopologyNodeRefSchema,
+  kind: OmTopologyRelationshipKindSchema,
+  to: OmTopologyNodeRefSchema,
+  systemPath: SystemPathSchema.optional(),
+  required: z.boolean().optional(),
+  metadata: OmTopologyMetadataSchema.optional()
+});
+var OmTopologyDomainSchema = z.object({
+  version: z.literal(1).default(1),
+  relationships: z.record(z.string().trim().min(1).max(255), OmTopologyRelationshipSchema).default({})
+}).default({ version: 1, relationships: {} });
+var DEFAULT_ORGANIZATION_MODEL_TOPOLOGY = {
+  version: 1,
+  relationships: {}
+};
 var PolicyIdSchema = ModelIdSchema;
 var PolicyApplicabilitySchema = z.object({
   systemIds: z.array(ModelIdSchema.meta({ ref: "system" })).default([]),
@@ -6978,6 +7054,7 @@ z.enum([
   "systems",
   "ontology",
   "resources",
+  "topology",
   "actions",
   "entities",
   "policies",
@@ -6997,6 +7074,7 @@ var DEFAULT_ORGANIZATION_MODEL_DOMAIN_METADATA = {
   systems: { version: 1, lastModified: "2026-05-10" },
   ontology: { version: 1, lastModified: "2026-05-14" },
   resources: { version: 1, lastModified: "2026-05-10" },
+  topology: { version: 1, lastModified: "2026-05-14" },
   actions: { version: 1, lastModified: "2026-05-10" },
   entities: { version: 1, lastModified: "2026-05-10" },
   policies: { version: 1, lastModified: "2026-05-10" },
@@ -7012,6 +7090,7 @@ var OrganizationModelDomainMetadataByDomainSchema = z.object({
   systems: OrganizationModelDomainMetadataSchema,
   ontology: OrganizationModelDomainMetadataSchema,
   resources: OrganizationModelDomainMetadataSchema,
+  topology: OrganizationModelDomainMetadataSchema,
   actions: OrganizationModelDomainMetadataSchema,
   entities: OrganizationModelDomainMetadataSchema,
   policies: OrganizationModelDomainMetadataSchema,
@@ -7030,6 +7109,7 @@ var OrganizationModelSchemaBase = z.object({
   systems: SystemsDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_SYSTEMS),
   ontology: OntologyScopeSchema.default(DEFAULT_ONTOLOGY_SCOPE),
   resources: ResourcesDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_RESOURCES),
+  topology: OmTopologyDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_TOPOLOGY),
   actions: ActionsDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_ACTIONS),
   entities: EntitiesDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_ENTITIES),
   policies: PoliciesDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_POLICIES),
@@ -7372,6 +7452,25 @@ OrganizationModelSchemaBase.superRefine((model, ctx) => {
     surface: ontologyCompilation.ontology.surfaces
   };
   const ontologyIds = new Set(Object.values(ontologyIndexByKind).flatMap((index) => Object.keys(index)));
+  function topologyTargetExists(ref) {
+    if (ref.kind === "system") return systemsById.has(ref.id);
+    if (ref.kind === "resource") return resourcesById.has(ref.id);
+    if (ref.kind === "ontology") return ontologyIds.has(ref.id);
+    if (ref.kind === "policy") return policiesById.has(ref.id);
+    if (ref.kind === "role") return rolesById.has(ref.id);
+    return true;
+  }
+  Object.entries(model.topology.relationships).forEach(([relationshipId, relationship]) => {
+    ["from", "to"].forEach((side) => {
+      const ref = relationship[side];
+      if (topologyTargetExists(ref)) return;
+      addIssue(
+        ctx,
+        ["topology", "relationships", relationshipId, side],
+        `Topology relationship "${relationshipId}" ${side} references unknown ${ref.kind} "${ref.id}"`
+      );
+    });
+  });
   const ontologyReferenceKeyKinds = {
     valueType: "value-type",
     catalogType: "catalog",
@@ -7510,11 +7609,18 @@ OrganizationModelSchemaBase.superRefine((model, ctx) => {
     }
   });
   function validateResourceOntologyBinding(resourceId, bindingKey, expectedKind, ids) {
-    ids?.forEach((ontologyId, ontologyIndex) => {
+    const ontologyIds2 = ids === void 0 ? [] : Array.isArray(ids) ? ids : [ids];
+    ontologyIds2.forEach((ontologyId, ontologyIndex) => {
       if (ontologyIndexByKind[expectedKind][ontologyId] === void 0) {
         addIssue(
           ctx,
-          ["resources", resourceId, "ontology", bindingKey, ontologyIndex],
+          [
+            "resources",
+            resourceId,
+            "ontology",
+            bindingKey,
+            ...Array.isArray(ids) ? [ontologyIndex] : []
+          ],
           `Resource "${resourceId}" ontology binding "${bindingKey}" references unknown ${expectedKind} ontology ID "${ontologyId}"`
         );
       }
@@ -7523,7 +7629,8 @@ OrganizationModelSchemaBase.superRefine((model, ctx) => {
   Object.values(model.resources).forEach((resource) => {
     const binding = resource.ontology;
     if (binding === void 0) return;
-    validateResourceOntologyBinding(resource.id, "implements", "action", binding.implements);
+    validateResourceOntologyBinding(resource.id, "actions", "action", binding.actions);
+    validateResourceOntologyBinding(resource.id, "primaryAction", "action", binding.primaryAction);
     validateResourceOntologyBinding(resource.id, "reads", "object", binding.reads);
     validateResourceOntologyBinding(resource.id, "writes", "object", binding.writes);
     validateResourceOntologyBinding(resource.id, "usesCatalogs", "catalog", binding.usesCatalogs);
@@ -7657,7 +7764,7 @@ var DEFAULT_ORGANIZATION_MODEL_NAVIGATION = {
       business: {
         type: "group",
         label: "Business",
-        icon: "business",
+        icon: "briefcase",
         order: 20,
         children: {
           sales: {
@@ -7674,7 +7781,7 @@ var DEFAULT_ORGANIZATION_MODEL_NAVIGATION = {
             label: "Clients",
             path: "/clients",
             surfaceType: "list",
-            icon: "projects",
+            icon: "clients",
             order: 20,
             targets: { systems: ["clients"] }
           },
@@ -8048,7 +8155,7 @@ var DEFAULT_ORGANIZATION_MODEL = {
       enabled: true,
       lifecycle: "active",
       color: "orange",
-      icon: "projects",
+      icon: "clients",
       path: "/clients"
     },
     operations: {
@@ -8352,6 +8459,7 @@ var DEFAULT_ORGANIZATION_MODEL = {
   },
   ontology: DEFAULT_ONTOLOGY_SCOPE,
   resources: DEFAULT_ORGANIZATION_MODEL_RESOURCES,
+  topology: DEFAULT_ORGANIZATION_MODEL_TOPOLOGY,
   actions: DEFAULT_ORGANIZATION_MODEL_ACTIONS,
   entities: DEFAULT_ORGANIZATION_MODEL_ENTITIES2,
   policies: DEFAULT_ORGANIZATION_MODEL_POLICIES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -57,9 +57,9 @@
     "tsup": "^8.0.0",
     "typescript": "5.9.2",
     "zod": "^4.1.0",
-    "@repo/eslint-config": "0.0.0",
+    "@repo/core": "0.25.0",
     "@repo/typescript-config": "0.0.0",
-    "@repo/core": "0.24.0"
+    "@repo/eslint-config": "0.0.0"
   },
   "scripts": {
     "lint": "eslint src --max-warnings 0",

package/reference/claude-config/rules/operations.md

@@ -32,11 +32,11 @@ The workflow is registered in `operations/src/index.ts` as part of the `example`
 
 1. **Define the descriptor in `core/config/organization-model.ts`** -- Add the OM Resource descriptor under the id-keyed `resources` map so identity, System membership, owner role, and governance status are authored once.
 
-2. **Model the semantic surface** -- Add durable business nouns, verbs, catalogs, links, events, and surfaces to the owning System's `ontology`; add system-local defaults/settings to `System.config`; add explanatory or governing material to `knowledge`; and keep transient DTOs and handler internals out of the OM. Top-level `entities`, top-level `actions`, and `System.content` are compatibility mirrors only when current published consumers still need them.
+2. **Model the semantic surface** -- Add durable business nouns, verbs, catalogs, links, events, and surfaces to the owning System's `ontology`; bind executable Resources through `resource.ontology.actions` and optional `resource.ontology.primaryAction`; add system-local defaults/settings to `System.config`; add explanatory or governing material to `knowledge`; and keep transient DTOs and handler internals out of the OM. Top-level `entities`, top-level `actions`, and `System.content` are compatibility mirrors only when current published consumers still need them.
 
 3. **Define the contract in `core/types/`** -- Add Zod schemas and inferred types to `core/types/index.ts` (or a new file under `core/types/`). Use `core/types/entities.ts` when workflows operate on project-specific entity contracts.
 
-4. **Implement the workflow in `operations/src/`** -- Create a new directory under `operations/src/` for the feature. Import the descriptor, derive runtime `resourceId` / `type` from it, export the workflow from its `index.ts`, and register it in `operations/src/index.ts`.
+4. **Implement the workflow in `operations/src/`** -- Create a new directory under `operations/src/` for the feature. Import the descriptor, derive runtime `resourceId`, `type`, `name`, and `description` from it, export the workflow from its `index.ts`, and register it in `operations/src/index.ts`.
 
 5. **Add the UI in `ui/src/routes/`** -- Create a new route file. Use TanStack Query to call the workflow execution endpoint. Import schemas from `@core/types` for validation and type inference. Read OM resources, ontology, knowledge, and graph data where possible instead of creating page-local semantic registries.
 
@@ -51,7 +51,7 @@ pnpm -C operations deploy       # deploy to dev
 
 ## Resource Registry
 
-`operations/src/index.ts` default-exports a `DeploymentSpec` with `version`, `organizationModel`, `workflows`, `agents`, and optional topology-oriented metadata such as `triggers`, `integrations`, `relationships`, `humanCheckpoints`, and `externalResources`. Each feature group exports `workflows` and `agents` arrays from its own `index.ts`, spread into the top-level spec. `DeploymentSpec` assembles deployable behavior; it should not be treated as a second resource identity catalog.
+`operations/src/index.ts` default-exports a `DeploymentSpec` with `version`, `organizationModel`, `workflows`, `agents`, and optional deployment mechanics such as `triggers`, `integrations`, `relationships`, `humanCheckpoints`, and `externalResources`. Durable operational wiring belongs in `organizationModel.topology.relationships`; deployment mechanics, credentials, provider webhook details, and per-run state stay outside the OM. Each feature group exports `workflows` and `agents` arrays from its own `index.ts`, spread into the top-level spec. `DeploymentSpec` assembles deployable behavior; it should not be treated as a second resource identity catalog.
 
 When you need breadth first, read:
 

package/reference/claude-config/rules/organization-model.md

@@ -1,32 +1,32 @@
----
-description: Edits to the canonical organization model go through /knowledge
-paths:
-  - core/config/organization-model.ts
-  - core/config/extensions/**/*.ts
----
-
-# Organization Model Edit Guide
-
-`core/config/organization-model.ts` is the single source of truth for this
-project's organizational identity -- it encodes customers, offerings, roles, goals,
+---
+description: Edits to the canonical organization model go through /om
+paths:
+  - core/config/organization-model.ts
+  - core/config/extensions/**/*.ts
+---
+
+# Organization Model Edit Guide
+
+`core/config/organization-model.ts` is the single source of truth for this
+project's organizational identity -- it encodes customers, offerings, roles, goals,
 Systems, ontology, Policies, Knowledge, config, and Resources
 descriptors that agents, workflows, and the UI shell all consume at runtime.
 New semantic authoring should start in system-colocated `ontology` scopes. Top-level
 `entities`, top-level `actions`, and `System.content` remain compatibility mirrors while
 published consumers finish moving to compiled ontology indexes.
-
-## Preferred Entry Point: `/knowledge`
-
-Direct edits to `organization-model.ts` are discouraged. Instead, use `/knowledge` (or
-`/knowledge <domain>`) to run the read → propose → confirm → write → validate ceremony:
-
-1. The skill reads the current model so proposals start from ground truth.
-2. It drafts only the specific block being changed, leaving everything else intact.
-3. The user confirms before any file is written.
-4. After writing, `pnpm -C operations check-types` runs and `OrganizationModelSchema.parse()`
-   is verified. On failure the file is rolled back automatically.
-
-Use `/knowledge <domain>` for targeted edits: `identity`, `customers`, `offerings`,
+
+## Preferred Entry Point: `/om`
+
+Direct edits to `organization-model.ts` are discouraged. Instead, use `/om` (or
+`/om <domain>`) to run the read → propose → confirm → write → validate ceremony:
+
+1. The skill reads the current model so proposals start from ground truth.
+2. It drafts only the specific block being changed, leaving everything else intact.
+3. The user confirms before any file is written.
+4. After writing, `pnpm -C operations check-types` runs and `OrganizationModelSchema.parse()`
+   is verified. On failure the file is rolled back automatically.
+
+Use `/om <domain>` for targeted edits: `identity`, `customers`, `offerings`,
 `roles`, `goals`, `techStack`, `systems`, `actions`, or `labels`. Resource identity and
 governance metadata belong in the id-keyed `resources` map; operations code derives runtime
 `resourceId` / `type` from those descriptors.
@@ -36,78 +36,81 @@ Author system-local semantics by boundary:
 - `System.ontology` owns durable object types, action types, catalog types, link types, event types, and surfaces.
 - `System.config` owns system-local JSON settings and defaults.
 - `resources` own executable workflow/agent descriptors, `systemPath`, owners, governance status, code references, and runtime implementation links.
-- `resource.ontology` describes implemented actions, reads, writes, catalog use, and emitted events.
+- `resource.ontology.actions` describes the ontology actions a Resource performs; `resource.ontology.primaryAction` names the default/selectable action when a Resource has one.
+- `resource.ontology` also describes reads, writes, catalog use, and emitted events.
+- `topology.relationships` owns durable operational wiring between Systems, Resources, ontology nodes, policies, roles, triggers, checkpoints, and external resources.
 - `knowledge` owns long-form playbooks, strategies, references, and governance context.
 - `System.content`, top-level `entities`, and top-level `actions` are compatibility mirrors only. Keep them aligned when current published consumers still need them, but do not treat them as the primary authoring surface.
 
-Keep `actionKey` as the current runtime compatibility bridge to workflow metadata.
-
-## Runtime Validation
-
-The model is validated at startup via `resolveOrganizationModel()` followed by
-`OrganizationModelSchema.parse()`. Cross-reference checks (segment ID refs in offerings,
-role reporting lines, period ordering in goals) are runtime-only and not caught by tsc
-alone -- always let the ceremony run both checks before treating a change as complete.
-
-## Extension Files
-
-New Zod extension files under `core/config/extensions/` are Level B codify
-operations. Route these through `/knowledge <domain>` as well -- the skill gates Level B
-to explicit user confirmation before scaffolding a new `.ts` file.
-
-This is a soft guide, not a hard block. The ceremony exists to prevent silent schema
-drift and to keep the model's editorial history visible.
-
-## Resource System Attachment
-
-Every resource in the id-keyed `organizationModel.resources` map declares which System it belongs to
-via `systemPath` -- a dot-separated path that resolves against the OM system tree
-(e.g. `"sys.operations"`, `"sales.crm"`):
-
-```ts
-{
-  id: 'apify-website-crawl',
-  systemPath: 'sys.operations',   // canonical system attachment
-  kind: 'workflow',
-  ...
-}
-```
-
-`systemPath` is validated at parse time by `SystemPathSchema` and cross-checked by
-`OrganizationModelSchema.superRefine` -- an unresolvable path causes a Zod error at
-schema validation. Use `getResourcesForSystem(model, path)` (from `@elevasis/core`) to
-query resources for a system at runtime. Pass `{ includeDescendants: true }` to include
-all descendant systems (segment-aware -- `'sales'` does NOT match `'salesforce.foo'`).
-
-Some external templates may carry a `systemId` compatibility mirror while published
-`@elevasis/core` releases catch up to the current source contract. Treat that field as
-legacy adapter data only; author new resource relationships against `systemPath`.
-
-Do not fetch resources for every system-oriented read by default. For agent workflows, start
-with the user's requested OM/knowledge context and query resources only when the task involves
-runtime ownership, executable implementation, observability, deployment, or resource governance.
-Use the descendant rollup only when parent-system scope is intended.
-
-`resource.category` and `resource.links[].nodeId` are **runtime filter overlays** -- they
-drive UI faceted filtering in the Command Center but do NOT define system membership.
-System membership is `systemPath` only.
-
-```ts
-// category and links power UI filter chips; systemPath is the
-// canonical OM attachment used for graph edges and getResourcesForSystem queries.
-```
-
+Do not author Resource `actionKey` in the target contract. Runtime/UI routing that needs a single selectable action should read `resource.ontology.primaryAction`.
+
+## Runtime Validation
+
+The model is validated at startup via `resolveOrganizationModel()` followed by
+`OrganizationModelSchema.parse()`. Cross-reference checks (segment ID refs in offerings,
+role reporting lines, period ordering in goals) are runtime-only and not caught by tsc
+alone -- always let the ceremony run both checks before treating a change as complete.
+
+## Extension Files
+
+New Zod extension files under `core/config/extensions/` are Level B codify
+operations. Route these through `/om <domain>` as well -- the skill gates Level B
+to explicit user confirmation before scaffolding a new `.ts` file.
+
+This is a soft guide, not a hard block. The ceremony exists to prevent silent schema
+drift and to keep the model's editorial history visible.
+
+## Resource System Attachment
+
+Every resource in the id-keyed `organizationModel.resources` map declares which System it belongs to
+via `systemPath` -- a dot-separated path that resolves against the OM system tree
+(e.g. `"sys.operations"`, `"sales.crm"`):
+
+```ts
+{
+  id: 'apify-website-crawl',
+  systemPath: 'sys.operations',   // canonical system attachment
+  kind: 'workflow',
+  ...
+}
+```
+
+`systemPath` is validated at parse time by `SystemPathSchema` and cross-checked by
+`OrganizationModelSchema.superRefine` -- an unresolvable path causes a Zod error at
+schema validation. Use `getResourcesForSystem(model, path)` (from `@elevasis/core`) to
+query resources for a system at runtime. Pass `{ includeDescendants: true }` to include
+all descendant systems (segment-aware -- `'sales'` does NOT match `'salesforce.foo'`).
+
+Some external templates may carry a `systemId` compatibility mirror while published
+`@elevasis/core` releases catch up to the current source contract. Treat that field as
+legacy adapter data only; author new resource relationships against `systemPath`.
+
+Do not fetch resources for every system-oriented read by default. For agent workflows, start
+with the user's requested OM/om context and query resources only when the task involves
+runtime ownership, executable implementation, observability, deployment, or resource governance.
+Use the descendant rollup only when parent-system scope is intended.
+
+`resource.category` and `resource.links[].nodeId` are **runtime filter overlays** -- they
+drive UI faceted filtering in the Command Center but do NOT define system membership.
+System membership is `systemPath` only.
+
+```ts
+// category and links power UI filter chips; systemPath is the
+// canonical OM attachment used for graph edges and getResourcesForSystem queries.
+```
+
 `resource.codeRefs[]` are repo-relative implementation breadcrumbs for agents and
 operators. Use them to point from a governed OM Resource descriptor to the operations
 entrypoint, handler, schema, test, docs, or config files that implement it. They do
 not define resource identity, System membership, runtime execution topology, or graph
 relationships.
 
+`topology.relationships` defines durable operational wiring in the OM. Keep credential
+values, provider webhook mechanics, deployment environment settings, execution logs,
+and per-run scheduler state outside the OM.
+
 `System.ontology` owns durable semantic contracts: object types, action types, catalog
 types, link types, event types, and surfaces. `System.config` owns local settings and
 defaults. If current UI or runtime code still needs legacy mirrors, keep `entities`,
 `actions`, or `System.content` aligned with the ontology/config record instead of
 inventing a separate source of truth.
-
-See `.claude/rules/system-shaping.md` (in the monorepo) for the substrate-shaping
-propagation checklist that governs renames of this shape.