@elevasis/sdk 1.29.0 → 1.30.1

package/dist/test-utils/index.js

@@ -6886,6 +6886,7 @@ var ORGANIZATION_MODEL_ICON_TOKENS = [
   "view",
   "launch",
   "message",
+  "message-plus",
   "escalate",
   "promote",
   "submit",
@@ -6923,7 +6924,7 @@ var LabelSchema = z.string().trim().min(1).max(120);
 var DescriptionSchema = z.string().trim().min(1).max(2e3);
 var ColorTokenSchema = z.string().trim().min(1).max(50);
 var IconNameSchema = OrganizationModelIconTokenSchema;
-z.string().trim().startsWith("/").max(300);
+var PathSchema = z.string().trim().startsWith("/").max(300);
 var ReferenceIdsSchema = z.array(ModelIdSchema).default([]);
 var DisplayMetadataSchema = z.object({
   label: LabelSchema,
@@ -6995,6 +6996,89 @@ function listAllSystems(model) {
   return results;
 }
 
+// ../core/src/organization-model/domains/entities.ts
+var EntityIdSchema = ModelIdSchema;
+var EntityLinkKindSchema = z.enum(["belongs-to", "has-many", "has-one", "many-to-many"]).meta({ label: "Link kind" });
+var EntityLinkSchema = z.object({
+  toEntity: EntityIdSchema.meta({ ref: "entity" }),
+  kind: EntityLinkKindSchema,
+  via: z.string().trim().min(1).max(255).optional(),
+  label: LabelSchema.optional()
+});
+var EntitySchema = z.object({
+  id: EntityIdSchema,
+  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
+  order: z.number(),
+  label: LabelSchema,
+  description: DescriptionSchema.optional(),
+  ownedBySystemId: ModelIdSchema.meta({ ref: "system" }),
+  table: z.string().trim().min(1).max(255).optional(),
+  rowSchema: ModelIdSchema.optional(),
+  stateCatalogId: ModelIdSchema.optional(),
+  links: z.array(EntityLinkSchema).optional()
+});
+z.record(z.string(), EntitySchema).refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
+  message: "Each entity entry id must match its map key"
+}).default({});
+
+// ../core/src/organization-model/domains/actions.ts
+var ActionResourceIdSchema = z.string().trim().min(1).max(255).regex(/^[A-Za-z0-9]+(?:[-._][A-Za-z0-9]+)*$/, "Resource IDs must use letters, numbers, -, _, or . separators");
+z.enum(["slash-command", "mcp-tool", "api-endpoint", "script-execution"]).meta({ label: "Invocation kind" });
+var ActionIdSchema = ModelIdSchema;
+var ActionScopeSchema = z.union([
+  z.literal("global"),
+  z.object({
+    domain: ModelIdSchema
+  })
+]);
+var ActionRefSchema = z.object({
+  actionId: ActionIdSchema.meta({ ref: "action" }),
+  intent: z.enum(["exposes", "consumes"]).meta({ label: "Intent" })
+});
+var SlashCommandInvocationSchema = z.object({
+  kind: z.literal("slash-command"),
+  command: z.string().trim().min(1).max(200).regex(/^\/[^\s].*$/, "Slash commands must start with /"),
+  toolFactory: ModelIdSchema.optional()
+});
+var McpToolInvocationSchema = z.object({
+  kind: z.literal("mcp-tool"),
+  server: ModelIdSchema,
+  name: ModelIdSchema
+});
+var ApiEndpointInvocationSchema = z.object({
+  kind: z.literal("api-endpoint"),
+  method: z.enum(["GET", "POST", "PATCH", "DELETE"]).meta({ label: "HTTP method" }),
+  path: z.string().trim().startsWith("/").max(500),
+  requestSchema: ModelIdSchema.optional(),
+  responseSchema: ModelIdSchema.optional()
+});
+var ScriptExecutionInvocationSchema = z.object({
+  kind: z.literal("script-execution"),
+  resourceId: ActionResourceIdSchema
+});
+var ActionInvocationSchema = z.discriminatedUnion("kind", [
+  SlashCommandInvocationSchema,
+  McpToolInvocationSchema,
+  ApiEndpointInvocationSchema,
+  ScriptExecutionInvocationSchema
+]);
+var ActionSchema = z.object({
+  id: ActionIdSchema,
+  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
+  order: z.number(),
+  label: LabelSchema,
+  description: DescriptionSchema.optional(),
+  scope: ActionScopeSchema.default("global"),
+  resourceId: ActionResourceIdSchema.optional(),
+  affects: z.array(EntityIdSchema.meta({ ref: "entity" })).optional(),
+  invocations: z.array(ActionInvocationSchema).default([]),
+  knowledge: z.array(ModelIdSchema.meta({ ref: "knowledge" })).default([]).optional(),
+  lifecycle: z.enum(["draft", "beta", "active", "deprecated", "archived"]).meta({ label: "Lifecycle", color: "teal" }).default("active")
+});
+z.record(z.string(), ActionSchema).refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
+  message: "Each action entry id must match its map key"
+}).default({});
+
 // ../core/src/organization-model/domains/prospecting.ts
 DisplayMetadataSchema.extend({
   id: ModelIdSchema,
@@ -8316,7 +8400,7 @@ var OntologyGroupSchema = OntologyRecordBaseSchema.extend({
 var OntologySurfaceTypeSchema = OntologyRecordBaseSchema.extend({
   route: z.string().trim().min(1).max(500).optional()
 });
-z.object({
+var OntologyScopeSchema = z.object({
   objectTypes: z.record(OntologyIdSchema, OntologyObjectTypeSchema).default({}).optional(),
   linkTypes: z.record(OntologyIdSchema, OntologyLinkTypeSchema).default({}).optional(),
   actionTypes: z.record(OntologyIdSchema, OntologyActionTypeSchema).default({}).optional(),
@@ -8549,6 +8633,152 @@ function compileOrganizationOntology(model) {
   addLegacyActionProjections(ontology, diagnostics, sourcesById, model.actions ?? {}, model.entities ?? {});
   return { ontology: sortResolvedOntologyIndex(ontology), diagnostics };
 }
+var SystemKindSchema = z.enum(["product", "operational", "platform", "diagnostic"]).meta({ label: "System kind", color: "blue" });
+var SystemLifecycleSchema = z.enum(["draft", "beta", "active", "deprecated", "archived"]).meta({ label: "Lifecycle", color: "teal" });
+var SystemStatusSchema = z.enum(["active", "deprecated", "archived"]).meta({ label: "Status", color: "teal" });
+var SystemIdSchema = ModelIdSchema;
+var SystemPathSchema = z.string().trim().min(1).regex(
+  /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/,
+  'must be a dotted lowercase path (e.g. "sales.lead-gen" or "sales.crm")'
+);
+var UiPositionSchema = z.enum(["sidebar-primary", "sidebar-bottom"]).meta({ label: "UI position" });
+z.string().trim().min(1).max(200).regex(
+  /^[a-z][a-z-]*:([a-z0-9-]+)(\.[a-z0-9-]+)*(:[a-z0-9.-]+)*$/,
+  "Node references must use kind:dotted-path (e.g. system:sales.crm or resource:lead-gen.company.qualify)"
+);
+var SystemUiSchema = z.object({
+  path: PathSchema,
+  surfaces: ReferenceIdsSchema,
+  icon: IconNameSchema.optional(),
+  order: z.number().int().optional()
+});
+var SystemInterfaceKeySchema = ModelIdSchema;
+var SystemInterfaceLifecycleSchema = z.enum(["draft", "active", "disabled", "deprecated", "archived"]).meta({ label: "System interface lifecycle", color: "teal" });
+var SYSTEM_INTERFACE_PROFILES = [
+  {
+    systemPath: "sales.lead-gen",
+    interfaceKey: "api",
+    readinessProfile: "sales.lead-gen.api"
+  },
+  {
+    systemPath: "sales.crm",
+    interfaceKey: "api",
+    readinessProfile: "sales.crm.api"
+  },
+  {
+    systemPath: "sales.lead-gen",
+    interfaceKey: "crm-handoff",
+    readinessProfile: "sales.lead-gen.crm-handoff"
+  }
+];
+var SYSTEM_INTERFACE_READINESS_PROFILES = SYSTEM_INTERFACE_PROFILES.map(
+  (profile) => profile.readinessProfile
+);
+var SystemInterfaceReadinessProfileSchema = z.enum(SYSTEM_INTERFACE_READINESS_PROFILES);
+var SystemInterfaceResourceScopeSchema = z.array(ModelIdSchema).default([]);
+var SystemApiInterfaceSchema = z.object({
+  lifecycle: SystemInterfaceLifecycleSchema.default("active"),
+  readinessProfile: SystemInterfaceReadinessProfileSchema.optional(),
+  /**
+   * Resource ids that participate in this API interface. This scopes readiness
+   * derivation without duplicating authored required/provided contract refs.
+   */
+  resourceIds: SystemInterfaceResourceScopeSchema.optional()
+}).strict();
+z.object({
+  systemPath: SystemPathSchema,
+  interfaceKey: SystemInterfaceKeySchema
+}).strict();
+var JsonValueSchema = z.lazy(
+  () => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(JsonValueSchema),
+    z.record(z.string(), JsonValueSchema)
+  ])
+);
+var SystemConfigSchema = z.record(z.string().trim().min(1).max(200), JsonValueSchema).default({}).optional();
+var SystemEntrySchema = z.object({
+  /** Stable tenant-defined system id (e.g. "sys.lead-gen" or "sales.crm"). */
+  id: SystemIdSchema,
+  /** Human-readable system label shown in UI, governance, and operations surfaces. */
+  label: LabelSchema.optional(),
+  /** @deprecated Use label. Accepted for pre-consolidation System declarations. */
+  title: LabelSchema.optional(),
+  /** One-paragraph purpose statement for the bounded context. */
+  description: DescriptionSchema.optional(),
+  /** Closed system shape enum; catalog values remain tenant-defined. */
+  kind: SystemKindSchema.optional(),
+  /** Optional self-reference for System hierarchy. */
+  parentSystemId: SystemIdSchema.optional(),
+  /** Optional UI presence. Systems without UI omit this. */
+  ui: SystemUiSchema.optional(),
+  /** Canonical lifecycle state. Replaces Feature.enabled/devOnly and System.status. */
+  lifecycle: SystemLifecycleSchema.optional(),
+  /** Optional role responsible for this system. */
+  responsibleRoleId: ModelIdSchema.meta({ ref: "role" }).optional(),
+  /** Optional knowledge nodes that govern this system. */
+  governedByKnowledge: z.array(ModelIdSchema.meta({ ref: "knowledge" })).default([]).optional(),
+  /** Optional actions this system exposes or consumes. */
+  actions: z.array(ActionRefSchema).optional(),
+  /** Optional operational policies that apply to this system. */
+  policies: z.array(ModelIdSchema.meta({ ref: "policy" })).default([]).optional(),
+  /** Optional goals this system contributes to. */
+  drivesGoals: z.array(ModelIdSchema.meta({ ref: "goal" })).default([]).optional(),
+  /** Thin API runtime-boundary marker. Readiness is derived from scoped resources and topology. */
+  apiInterface: SystemApiInterfaceSchema.optional(),
+  /** @deprecated Use lifecycle. Accepted for one publish cycle. */
+  status: SystemStatusSchema.optional(),
+  /** @deprecated Use ui.path. Kept for one-cycle Feature compatibility. */
+  path: PathSchema.optional(),
+  /** @deprecated Use ui.icon. Kept for one-cycle Feature compatibility. */
+  icon: IconNameSchema.optional(),
+  /** @deprecated Feature color token, retained for one-cycle compatibility. */
+  color: ColorTokenSchema.optional(),
+  /** @deprecated UI placement hint, retained for one-cycle compatibility. */
+  uiPosition: UiPositionSchema.optional(),
+  /** @deprecated Use lifecycle. */
+  enabled: z.boolean().optional(),
+  /** @deprecated Use lifecycle: "beta". */
+  devOnly: z.boolean().optional(),
+  requiresAdmin: z.boolean().optional(),
+  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
+  order: z.number(),
+  /**
+   * System-local JSON settings and defaults. Strongly typed OM fields,
+   * secrets, credentials, and runtime state stay outside this bucket.
+   */
+  config: SystemConfigSchema,
+  /**
+   * System-owned ontology declarations. `systems` is now the canonical child
+   * key; this scope holds the object, action, catalog, link, event, and
+   * shared contract records owned by this system.
+   */
+  ontology: OntologyScopeSchema.optional(),
+  /**
+   * Recursive child systems, authored via nesting (per L11).
+   * The key is the local system id; the full path is computed by joining
+   * ancestor keys with `.` (e.g. parent key `'sales'` + child key `'crm'` → `'sales.crm'`).
+   * Per Phase 4: `id` and `parentSystemId` fields will be removed in favour of
+   * position-derived paths. Both still exist on this schema for backward compat.
+   */
+  systems: z.lazy(() => z.record(z.string().trim().min(1).max(100), SystemEntrySchema)).optional(),
+  /** @deprecated Use systems. Accepted as a compatibility alias during the ontology bridge. */
+  subsystems: z.lazy(() => z.record(z.string().trim().min(1).max(100), SystemEntrySchema)).optional()
+}).strict().refine((system) => system.label !== void 0 || system.title !== void 0, {
+  path: ["label"],
+  message: "System must provide label or title"
+}).transform((system) => {
+  const normalizedSystem = system.systems !== void 0 && system.subsystems === void 0 ? { ...system, subsystems: system.systems } : system;
+  if (normalizedSystem.status === void 0) return normalizedSystem;
+  console.warn("[organization-model] System.status is deprecated; use System.lifecycle instead.");
+  return normalizedSystem.lifecycle === void 0 ? { ...normalizedSystem, lifecycle: normalizedSystem.status } : normalizedSystem;
+});
+z.record(z.string(), SystemEntrySchema).refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
+  message: "Each system entry id must match its map key"
+}).default({});
 
 // ../core/src/organization-model/migration-helpers.ts
 function catalogRecords(model) {
@@ -8626,21 +8856,12 @@ z.object({
 });
 
 // ../core/src/business/acquisition/ontology-validation.ts
-var LEAD_GEN_API_INTERFACE = {
-  interfaceKey: "api",
-  readinessProfile: "sales.lead-gen.api"
-};
-var CRM_API_INTERFACE = {
-  systemPath: "sales.crm",
-  interfaceKey: "api",
-  readinessProfile: "sales.crm.api"
-};
-var LEAD_GEN_CRM_HANDOFF_INTERFACE = {
-  systemPath: "sales.lead-gen",
-  interfaceKey: "crm-handoff",
-  readinessProfile: "sales.lead-gen.crm-handoff"
-};
+var LEAD_GEN_API_INTERFACE = SYSTEM_INTERFACE_PROFILES[0];
+var CRM_API_INTERFACE = SYSTEM_INTERFACE_PROFILES[1];
+var LEAD_GEN_CRM_HANDOFF_INTERFACE = SYSTEM_INTERFACE_PROFILES[2];
+LEAD_GEN_API_INTERFACE.readinessProfile;
 CRM_API_INTERFACE.readinessProfile;
+LEAD_GEN_CRM_HANDOFF_INTERFACE.readinessProfile;
 var LEAD_GEN_LIST_OBJECT_ONTOLOGY_ID = formatOntologyId({
   scope: "sales.lead-gen",
   kind: "object",
@@ -8718,6 +8939,9 @@ function profileForInterface(systemPath, interfaceKey, readinessProfile) {
 function readinessMarkerPath(context) {
   return context.interfaceKey === "api" ? `systems.${context.systemPath}.apiInterface` : `systems.${context.systemPath}.derivedCrmHandoffReadiness`;
 }
+function formatSupportedReadinessProfiles() {
+  return SYSTEM_INTERFACE_READINESS_PROFILES.map((profile) => `"${profile}"`).join(", ");
+}
 function getActiveScopedResources(model, resourceIds, issues, context) {
   const resources = [];
   for (const [index2, resourceId] of resourceIds.entries()) {
@@ -8997,18 +9221,13 @@ function computeInterfaceReadiness(model, request) {
       { path: `${readinessMarkerPath(request)}.lifecycle` }
     );
   }
-  const supportedProfiles = [
-    LEAD_GEN_API_INTERFACE.readinessProfile,
-    CRM_API_INTERFACE.readinessProfile,
-    LEAD_GEN_CRM_HANDOFF_INTERFACE.readinessProfile
-  ];
-  const supportedProfile = readinessProfile !== void 0 && supportedProfiles.some((profile) => profile === readinessProfile);
+  const supportedProfile = readinessProfile !== void 0 && SYSTEM_INTERFACE_PROFILES.some((profile) => profile.readinessProfile === readinessProfile);
   if (!supportedProfile) {
     addReadinessIssue(
       issues,
       "SYSTEM_INTERFACE_INVALID",
       "unknown-readiness-profile",
-      `System Interface "${formatInterfaceIdentity(request.systemPath, request.interfaceKey)}" references unknown readiness profile "${readinessProfile}".`,
+      `System Interface "${formatInterfaceIdentity(request.systemPath, request.interfaceKey)}" references unknown readiness profile "${readinessProfile}". Supported profiles: ${formatSupportedReadinessProfiles()}. Custom Systems should not declare apiInterface; route custom behavior through workflows/operations plus ontology, resources, and topology.`,
       { path: `${readinessMarkerPath(request)}.readinessProfile`, ref: readinessProfile }
     );
     return {

package/dist/worker/index.js

@@ -4978,6 +4978,7 @@ var ORGANIZATION_MODEL_ICON_TOKENS = [
   "view",
   "launch",
   "message",
+  "message-plus",
   "escalate",
   "promote",
   "submit",

package/package.json

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

package/reference/claude-config/rules/topbar-actions.md

@@ -0,0 +1,70 @@
+---
+description: OM-declared topbar actions — navigation.topbar field and TOPBAR_ACTION_MANIFESTS registry pattern
+paths:
+  - ui/src/lib/components/AppTopbar*
+  - ui/src/routes/__root*
+  - core/config/organization-model/**
+---
+
+# Topbar Actions (Template Mirror Discipline — Tier 1 Note)
+
+> **Scope:** This note documents substrate that has landed in the monorepo but is not yet published
+> to `@elevasis/sdk/reference/rules/`. It will be superseded by the bundled rule once the
+> `@elevasis/ui` minor that carries the topbar substrate ships. Until then, use this file.
+
+## navigation.topbar OM Field
+
+The Organization Model now has a `navigation.topbar` region for declaring topbar action items.
+Each entry is a distinct node type — OM owns data and visibility; a registry binds behavior.
+
+```ts
+// core/config/organization-model.ts (navigation section)
+navigation: {
+  topbar: {
+    request: {
+      id: 'request',
+      label: 'Request a feature or report an issue',
+      tooltip: 'Request a feature or report an issue',
+      icon: 'message-plus',
+      order: 10,
+      enabled: true
+    }
+  }
+}
+```
+
+Topbar items are toggled via `/org-os manage` exactly like sidebar surfaces. The `surfaceType`
+enum (`page | dashboard | list | detail | graph | settings`) does NOT apply to topbar items —
+they are a separate node type, not surfaces.
+
+## TOPBAR_ACTION_MANIFESTS Registry
+
+Behavior for each `navigation.topbar` key is bound through a manifest registry in
+`@elevasis/ui`. Each manifest maps a key to a render function:
+
+```ts
+// Registered in packages/ui/src/features/registry/manifests.ts
+TOPBAR_ACTION_MANIFESTS = {
+  request: requestTopbarActionManifest
+}
+```
+
+The `requestTopbarActionManifest` renders `<RequestActionIcon />` from
+`@elevasis/ui/features/monitoring/requests`. It owns its own disclosure state and modal —
+no wiring needed at the call site.
+
+## Template Authoring (Tier 2 — Post-Publish)
+
+Declaring `navigation.topbar.request` in the template OM and rendering `<TopbarActions />`
+in `AppTopbar` is **Tier 2 post-publish authoring** — it runs after the `@elevasis/ui` minor
+bump lands in `external/_template`. Do NOT edit `core/config/organization-model/**` for this
+until the publish + baseline bump step completes.
+
+The requests-page `RequestButton` (entry point C) is a CC-level app-local addition in the
+platform `apps/command-center` routes. Template projects add their own equivalent in
+`ui/src/routes/monitoring/requests.index.tsx` after the surface is present in their navigation.
+
+## Related Rules
+
+- `node_modules/@elevasis/sdk/reference/rules/organization-model.md` — OM schema and authoring ceremony
+- `node_modules/@elevasis/sdk/reference/rules/organization-os.md` — `/org-os manage` toggle surface

package/reference/claude-config/skills/om/SKILL.md

@@ -47,6 +47,8 @@ metadata:
       - knowledge graph
       - knowledge browser
       - ontology
+      - apiInterface
+      - interface readiness
       - by-ontology
       - list my roles
       - what is our
@@ -95,7 +97,7 @@ primitive. When two buckets fit, prefer the higher one (more specific → more g
 | --- | ------------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
 | 1   | Named knowledge/role/policy id | User names `knowledge.<id>`, `role.<id>`, `policy.<id>` directly                  | `om:cat <id>` for body, `om:describe <id>` for neighborhood                     |
 | 2   | Named system                   | User names a system path (`sales.crm`, `sales.lead-gen`)                          | `om:describe <id>`                                                              |
-| 3   | Named ontology id              | Id contains `:object/`, `:action/`, `:event/`, `:catalog/`, `:link/`, `:surface/` | `om:describe <id>` (or `om:ls /by-ontology/<id> --ids-only` then `om:cat` each) |
+| 3   | Named ontology id              | Id contains `:object/`, `:action/`, `:event/`, `:catalog/`, `:interface/`, `:link/`, `:surface/` | `om:describe <id>` (or `om:ls /by-ontology/<id> --ids-only` then `om:cat` each) |
 | 4   | Kind keyword                   | "playbooks", "strategies", "all references", "list policies"                      | `om:ls /by-kind/<kind> --ids-only` then `om:cat` each                           |
 | 5   | Free-text discovery            | Anything else ("lead gen", "outreach", "what governs X?")                         | `om:search "<query>"` then drill into top hit with `om:describe`                |
 
@@ -198,6 +200,7 @@ what adjacent context may matter:
 | What resources belong to a System? | the id-keyed `organizationModel.resources` map and `getResourcesForSystem(model, systemPath)` | use `{ includeDescendants: true }` only for parent-scope rollups           |
 | What can a System do?              | system action refs and the actions domain                                                     | `action.resourceId`, invocation metadata, affected entities, policies      |
 | What data does it own?             | entities domain                                                                               | owning System refs, state catalogs, entity links, emitted/projected events |
+| Is a platform API interface ready? | the System's `apiInterface` marker and `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md` | matching convention-locked System path, cataloged `readinessProfile`, derived resource ontology bindings, and scoped topology grants |
 | What UI surface exposes it?        | `navigation.sidebar` plus `SystemModule` manifests                                            | route files, surface targets, route-prefix modules, guards                 |
 | What knowledge applies?            | `om:ls /by-system/<id>` plus graph edges                                                      | `om:cat`, `om:graph`, `/graph/<id>/governed-by`                            |
 
@@ -207,6 +210,20 @@ follow the relationship that matches the work. Prefer structured helpers from
 
 ---
 
+## API Interface Readiness
+
+`system.apiInterface` is adopt-only in tenant projects. It declares intent to adopt a platform-provided API capability from the installed `@elevasis/core` / `@elevasis/sdk` version; it is not a tenant extension point.
+
+Use only readiness profiles listed in `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md`. The profile also fixes the required System path, such as `sales.lead-gen` or `sales.crm`. Do not invent a profile, and do not repoint a cataloged profile to a custom System path.
+
+Readiness is derived, not hand-authored. After the marker is present, the validator checks ontology object/catalog types, scoped resources and their `resource.ontology` bindings, and any required scoped topology `uses` grants. Lead-gen to CRM handoff is represented as a scoped topology relationship under the cross-System boundary invariant, not as an authored bridge object.
+
+Custom Systems should not carry `apiInterface`. Build custom behavior through `System.ontology`, `System.config`, resources, catalogs, topology, navigation, and workflows/operations. Runtime business logic belongs in workflows and agents registered by `operations/src/index.ts`; the tenant project does not add platform API routes.
+
+Do not confuse ontology `interface` records with `system.apiInterface`. Ontology ids such as `<system>:interface/<local-id>` describe semantic model records under `System.ontology`; `system.apiInterface` is a flat System-level marker for closed platform API readiness.
+
+---
+
 ## Shared Layering Preview
 
 When opening a domain that uses a closed stage, status, or catalog vocabulary -- especially

package/reference/claude-config/skills/om/operations/scaffold.md

@@ -0,0 +1,153 @@
+# Scaffold: New OM Entries via `om:scaffold:*` CLI
+
+`om:scaffold:*` is the guided-creation surface for adding new entries to the tenant Organization Model. Each command prompts for missing fields, prints the proposed TypeScript / MDX block under `--dry-run`, and (when run without `--dry-run`) writes into the canonical authoring file under `core/config/organization-model/**` or `core/config/knowledge/nodes/`.
+
+This operation is invoked by `/om` when intent classifies as **Codify-new-entry** (a net-new System, Resource, Role, Knowledge node, or a fill-pass against a conformance-gap JSON) rather than a Level-A field edit. For existing-field edits, dispatch to `codify-level-a.md` instead.
+
+---
+
+## When to Use
+
+| Intent signal                                   | Dispatch                         |
+| ----------------------------------------------- | -------------------------------- |
+| "Add a new system for …", "we have an X system" | `om:scaffold:system`             |
+| "Add a workflow / resource called …"            | `om:scaffold:resource`           |
+| "Add a role …", "we need a … role"              | `om:scaffold:role`               |
+| "Add a knowledge node / playbook / strategy …"  | `om:scaffold:knowledge`          |
+| Conformance gate produced a gap JSON to apply   | `om:scaffold:fill --gaps <path>` |
+
+For existing-field edits (changing a description, toggling a system, renaming a label), use the Codify Level-A ceremony — do not scaffold.
+
+---
+
+## CLI Surface
+
+All commands run from inside `external/<project>/` (or any descendant — `elevasis-sdk` walks up to the `.elevasis` marker). Add `--dry-run` to any command to preview the generated TypeScript / MDX without writing.
+
+| Command                 | Purpose                                                                                              | Writes to                                   |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| `om:scaffold:system`    | Guide creation of a new System entry. Optional `--api-backed` emits an `apiInterface` block.         | `core/config/organization-model/systems.ts` |
+| `om:scaffold:resource`  | Add a new workflow Resource descriptor with `systemPath` attachment and an ontology `primaryAction`. | `core/config/organization-model/systems.ts` |
+| `om:scaffold:role`      | Add a new Role to the profile domain.                                                                | `core/config/organization-model/profile.ts` |
+| `om:scaffold:knowledge` | Create a new MDX knowledge node file under the requested kind / system mount.                        | `core/config/knowledge/nodes/`              |
+| `om:scaffold:fill`      | Non-interactive apply of a conformance-gap JSON produced by the conformance gate (Agent 2a).         | Per-file as recorded in the JSON.           |
+
+---
+
+## Common Options
+
+| Flag                        | Behavior                                                                             |
+| --------------------------- | ------------------------------------------------------------------------------------ | -------- | --------- | -------- |
+| `--dry-run`                 | Print proposed block; write nothing. Always run this first when in doubt.            |
+| `-h`, `--help`              | Print command-specific help.                                                         |
+| `--id <id>`                 | Pre-fill the canonical id (prompted if absent).                                      |
+| `--title <title>`           | Pre-fill display title (prompted if absent — `system`, `resource`, `role`).          |
+| `--system-path <path>`      | Attach Resource or Knowledge to an existing System (prompted if absent).             |
+| `--api-backed`              | (`system` only) Emit an `apiInterface` block; reminds you to populate `resourceIds`. |
+| `--primary-action <action>` | (`resource` only) Pre-fill ontology primary action id.                               |
+| `--kind <kind>`             | (`knowledge` only) `playbook                                                         | strategy | reference | policy`. |
+| `--gaps <path>`             | (`fill` only) Required path to the conformance-gap JSON.                             |
+| `--skipped <path>`          | (`fill` only) Output path for gaps that still need manual input.                     |
+
+---
+
+## Step-by-Step
+
+### Step 1: Pre-flight read
+
+Before scaffolding, run a single `om:describe` against the parent System (for Resource / Knowledge scaffolds) or the profile domain (for Role scaffolds). This grounds the proposed id, system path, and ontology references in current model state. Skipping this step routinely produces ids that collide with existing entries.
+
+```bash
+pnpm exec elevasis-sdk om:describe sales.crm
+```
+
+### Step 2: Dry-run
+
+Always preview first. Each command prints the exact TypeScript / MDX block it would write.
+
+```bash
+pnpm exec elevasis-sdk om:scaffold:system --dry-run
+pnpm exec elevasis-sdk om:scaffold:resource --dry-run
+pnpm exec elevasis-sdk om:scaffold:role --dry-run
+pnpm exec elevasis-sdk om:scaffold:knowledge --dry-run
+```
+
+The dry-run output is the diff you would present to the user during a Codify proposal. Show it verbatim before asking for confirmation.
+
+### Step 3: Confirm
+
+Pause for explicit user confirmation, exactly like Codify Level-A Step 3. Permission prompts also gate the underlying write.
+
+### Step 4: Write
+
+Re-run the command without `--dry-run`. The CLI:
+
+1. Asserts the project is in split layout (`core/config/organization-model/{profile,systems,navigation}.ts`); on monolithic projects it errors with a guidance message rather than guessing where to write.
+2. Inserts the new block alongside existing entries of the same kind.
+3. Reports the touched file path.
+
+### Step 5: Validate
+
+Always run both gates after a scaffold write:
+
+```bash
+pnpm -C operations check-types   # tsc --noEmit
+pnpm -C operations check         # elevasis-sdk resource validator (incl. conformance gate)
+```
+
+The new conformance gate (shipped in `@elevasis/sdk@1.30+`) will catch a System that declares API-backed Resources but no `apiInterface`. If it fires after a `system` scaffold, either:
+
+- Re-run `om:scaffold:system --api-backed` to add the `apiInterface` block, or
+- Run `om:scaffold:fill --gaps <gaps.json>` against the gate's emitted gaps file.
+
+### Step 6: Rollback on failure
+
+If either validation gate fails, restore the touched file from the snapshot captured in Step 1 of the parent `/om` Codify ceremony. The scaffold CLI does not perform its own rollback — the ceremony around it does.
+
+---
+
+## `om:scaffold:fill` — Conformance Gap Pass
+
+`om:scaffold:fill` is the non-interactive counterpart to the four guided scaffolders. It consumes a JSON file shaped like the output of the conformance gate (the new deploy preflight introduced alongside `@elevasis/core@0.38` + `@elevasis/sdk@1.30`) and writes the missing fields it can derive without user input. Gaps that require a choice (e.g. picking a `readinessProfile`) land in the `--skipped` output for manual review.
+
+```bash
+# After the conformance gate prints a gaps file:
+pnpm exec elevasis-sdk om:scaffold:fill --gaps .elevasis/conformance-gaps.json --dry-run
+pnpm exec elevasis-sdk om:scaffold:fill --gaps .elevasis/conformance-gaps.json --skipped .elevasis/conformance-skipped.json
+```
+
+`fill` is idempotent for already-applied gaps; it skips entries that no longer match the live model.
+
+---
+
+## Layout Guard
+
+Every `om:scaffold:*` command requires the split layout under `core/config/organization-model/`:
+
+- `profile.ts` — identity, customers, offerings, roles, goals, techStack, labels
+- `systems.ts` — systems + system-attached resources
+- `navigation.ts` — navigation surfaces and sidebar wiring
+
+On a monolithic `core/config/organization-model.ts`, the command errors with a one-line instruction to split first. The split step is owned by an upstream `/om` workflow — do not hand-split during a scaffold.
+
+---
+
+## Related Operations
+
+- `codify-level-a.md` — existing-field edits (the default Codify pipeline)
+- `codify-level-b.md` — net-new Zod extension files under `core/config/extensions/`
+- `verify.md` — model-coherence checks (the in-memory doctor)
+
+---
+
+## Caller Contract (when dispatched from `/om`)
+
+When `/om` classifies a Codify-new-entry intent, it should:
+
+1. Pick the correct sub-command from the table above.
+2. Pre-fill any options it can confidently extract from the conversation (`--id`, `--title`, `--system-path`, `--api-backed`, etc.) so the CLI does not re-prompt for them.
+3. Always pass `--dry-run` on the first invocation and show the output to the user.
+4. On user confirmation, re-invoke without `--dry-run`.
+5. Run the Step 5 validators and report the result. Roll back if either fails.
+
+Do not skip the dry-run round-trip. The scaffolders write into the authoring source of truth — silent writes erode the trust the `/om` ceremony exists to protect.