@elevasis/sdk 1.28.1 → 1.30.0

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.28.1",
+  "version": "1.30.0",
   "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.35.1",
-    "@repo/typescript-config": "0.0.0",
-    "@repo/eslint-config": "0.0.0"
+    "@repo/core": "0.38.0",
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
   },
   "scripts": {
     "lint": "eslint src --max-warnings 0",

package/reference/_navigation.md

@@ -46,25 +46,25 @@ Package entries indexed: 60.
 
 | Resource | Location | Description | When to Load |
 | --- | --- | --- | --- |
-| SDK | `index.mdx` | Root SDK types, config, runtime errors, and registry surface. | (not specified) |
+| SDK | `sdk/index.mdx` | Root SDK types, config, runtime errors, and registry surface. | (not specified) |
 
 ## @elevasis/sdk / Runtime
 
 | Resource | Location | Description | When to Load |
 | --- | --- | --- | --- |
-| Worker Runtime | `runtime.mdx` | Worker runtime entrypoint, adapters, and platform execution surface. | (not specified) |
+| Worker Runtime | `sdk/runtime.mdx` | Worker runtime entrypoint, adapters, and platform execution surface. | (not specified) |
 
 ## @elevasis/sdk / Testing
 
 | Resource | Location | Description | When to Load |
 | --- | --- | --- | --- |
-| Test Utils | `runtime.mdx` | Workflow runner, registry assertion, and typed adapter mocks for SDK consumers. | (not specified) |
+| Test Utils | `sdk/runtime.mdx` | Workflow runner, registry assertion, and typed adapter mocks for SDK consumers. | (not specified) |
 
 ## @elevasis/sdk / Tooling
 
 | Resource | Location | Description | When to Load |
 | --- | --- | --- | --- |
-| Node Build Tooling | `cli.mdx` | Node-only build helpers: knowledge codegen and other fs/path/process utilities. Not browser-safe. | (not specified) |
+| Node Build Tooling | `sdk/cli.mdx` | Node-only build helpers: knowledge codegen and other fs/path/process utilities. Not browser-safe. | (not specified) |
 
 ## @elevasis/ui / Build
 

package/reference/_reference-manifest.json

@@ -95,8 +95,8 @@
       "group": "Getting Started",
       "order": 1,
       "sourcePath": "packages/sdk/src/index.ts",
-      "docPath": "apps/docs/content/docs/sdk/index.mdx",
-      "referencePath": "index.mdx",
+      "docPath": "apps/docs/content/docs/sdk/sdk/index.mdx",
+      "referencePath": "sdk/index.mdx",
       "publishedExportPath": "./dist/index.js"
     },
     {
@@ -109,8 +109,8 @@
       "group": "Runtime",
       "order": 1,
       "sourcePath": "packages/sdk/src/worker/index.ts",
-      "docPath": "apps/docs/content/docs/sdk/runtime.mdx",
-      "referencePath": "runtime.mdx",
+      "docPath": "apps/docs/content/docs/sdk/sdk/runtime.mdx",
+      "referencePath": "sdk/runtime.mdx",
       "publishedExportPath": "./dist/worker/index.js"
     },
     {
@@ -123,8 +123,8 @@
       "group": "Testing",
       "order": 1,
       "sourcePath": "packages/sdk/src/test-utils/index.ts",
-      "docPath": "apps/docs/content/docs/sdk/runtime.mdx",
-      "referencePath": "runtime.mdx",
+      "docPath": "apps/docs/content/docs/sdk/sdk/runtime.mdx",
+      "referencePath": "sdk/runtime.mdx",
       "publishedExportPath": "./dist/test-utils/index.js"
     },
     {
@@ -137,8 +137,8 @@
       "group": "Tooling",
       "order": 1,
       "sourcePath": "packages/sdk/src/node/index.ts",
-      "docPath": "apps/docs/content/docs/sdk/cli.mdx",
-      "referencePath": "cli.mdx",
+      "docPath": "apps/docs/content/docs/sdk/sdk/cli.mdx",
+      "referencePath": "sdk/cli.mdx",
       "publishedExportPath": "./dist/node/index.js"
     },
     {

package/reference/claude-config/hooks/scaffold-registry-reminder.mjs

@@ -16,7 +16,7 @@ const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
 const LOG_DIR = join(ROOT, '.claude', 'logs')
 const LOG_FILE = join(LOG_DIR, 'scaffold-registry-reminder.log')
 const STATE_FILE = join(LOG_DIR, 'scaffold-registry-reminder.state.json')
-const REGISTRY_FILE = join(ROOT, '.claude', 'scaffold-registry.compiled.json')
+const REGISTRY_FILE = join(ROOT, '.claude', 'registries', 'scaffold-registry.compiled.json')
 
 const DEFAULT_COOLDOWN_MS = 300_000 // 5 minutes
 
@@ -89,7 +89,7 @@ function emitReminder(entry, relFilePath) {
     lines.push(formatDependentLine(dep))
   }
   lines.push(
-    `  If this is a scaffold-sensitive pattern not in the registry, also add an entry to .claude/scaffold-registry.yml.`
+    `  If this is a scaffold-sensitive pattern not in the registry, also add an entry to .claude/registries/scaffold-registry.yml.`
   )
   return lines.join('\n')
 }
@@ -98,7 +98,7 @@ function emitMissingEntryHint(relFilePath) {
   return [
     `\uD83D\uDD14 Scaffold reminder -- unregistered generated path (${relFilePath})`,
     `  This path looks scaffold-generated but has no registry entry.`,
-    `  If it is scaffold-sensitive, add a new entry to .claude/scaffold-registry.yml`,
+    `  If it is scaffold-sensitive, add a new entry to .claude/registries/scaffold-registry.yml`,
     `  so the reminder hook and /work handoff can track it.`
   ].join('\n')
 }

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/tutorial/technical.md

@@ -494,7 +494,7 @@ how data flows between steps.
 **Estimated time:** 25 min
 
 **Files referenced:** `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`,
-`apps/docs/content/docs/sdk/concepts.mdx` (design decisions section)
+`apps/docs/content/docs/sdk/sdk/concepts.mdx` (design decisions section)
 
 **Flow:**
 
@@ -1044,7 +1044,7 @@ result) and understands when to use an agent definition vs a workflow definition
 **Estimated time:** 25 min
 
 **Files referenced:** `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`,
-`apps/docs/content/docs/sdk/concepts.mdx` (workflow vs agent section)
+`apps/docs/content/docs/sdk/sdk/concepts.mdx` (workflow vs agent section)
 
 **Flow:**
 
@@ -1076,7 +1076,7 @@ The SDK converts the Zod schema to JSON Schema internally. The LLM is instructed
 matching that shape. The result is validated and returned as the inferred TypeScript type.
 
 **Agent definition vs workflow definition.** Read the glossary entries from
-`apps/docs/content/docs/sdk/concepts.mdx`:
+`apps/docs/content/docs/sdk/sdk/concepts.mdx`:
 
 - **Workflow** -- deterministic, step-by-step, 300s timeout. Use when inputs and outputs are
   known and the process is predefined.
@@ -1171,7 +1171,7 @@ understands the scaffold registry's purpose.
 **Estimated time:** 20 min
 
 **Files referenced:** `.claude/rules/` (all files), `.claude/memory/` (layout),
-`.claude/scaffold-registry.yml` (reference, monorepo-side concept)
+`.claude/registries/scaffold-registry.yml` (reference, monorepo-side concept)
 
 **Flow:**
 
@@ -1205,7 +1205,7 @@ glob of files it applies to. The rules system discovers it automatically -- no r
 Memory files are readable by the agent at session start. The `profile.md` file is particularly
 important: it sets the project-wide tone for all sessions after the tutorial track is selected.
 
-**Scaffold registry (monorepo-side concept).** `.claude/scaffold-registry.yml` is the
+**Scaffold registry (monorepo-side concept).** `.claude/registries/scaffold-registry.yml` is the
 monorepo's source-of-truth for scaffold dependencies -- it maps source paths to generated or
 manual scaffolds that depend on them. It drives the PostToolUse reminder hook and `/work handoff`
 preflight in the monorepo. In an external project you are a consumer, not a contributor, of that