@elevasis/sdk 1.22.1 → 1.23.0

package/reference/claude-config/skills/{knowledge → om}/operations/labels.md

@@ -1,94 +1,94 @@
-# Labels domain
-
-`label` is an inline display field carried by status entries, stage entries, System entries,
-knowledge nodes, registry entries, and sidebar surfaces in the OrganizationModel. Labels control what users see in the UI and what
-agents say when narrating state. Editing a label does not change the entry's `id` or
-`semanticClass` -- only the human-readable display string. This is Level A only (config-only
-edits to `core/config/organization-model.ts`).
-
-## What carries labels
-
-The following model elements have editable inline `label` fields:
-
-**Status / stage entries.** Each domain that carries an enum-like array exposes per-entry labels:
-
-- `sales.statuses` -- deal pipeline stages.
-- `prospecting.statuses` -- lead lifecycle stages.
-- `projects.statuses` -- project and task stages.
-
-Source of platform defaults: `packages/core/src/organization-model/domains/{sales,prospecting,projects}.ts`.
-
-Each status entry shape:
-
-```typescript
-{ id: 'new', label: 'New Lead', semanticClass: 'active', color: 'blue' }
-```
-
-**Systems.** The `label` field on a System entry. Editing it changes agent narration and any
-System-derived shell text, but it does not change the System `id`, route path, or graph node id.
-
-**Sidebar surfaces.** Routeable leaves under `navigation.sidebar.primary` and
-`navigation.sidebar.bottom` carry labels. Editing changes nav item and breadcrumb display without
-changing the route path or target System refs.
-
-**Knowledge/domain entries.** Knowledge nodes, customers, offerings, goals, roles, resources,
-actions, entities, and policies may carry labels or titles depending on the domain. Edit only the
-display field that already exists on the entry.
-
-## What is NOT in scope
-
-`id` and `semanticClass` of any entry must never change in a label edit -- they are structural
-anchors used by code, hooks, and workflow adapters. Only `label` (and optionally `color` or
-`icon`) are in scope. To rename an `id`, escalate to a separate Level B refactor with explicit
-confirmation, because every consumer that references the old `id` must be updated in the same
-change.
-
-## Validation rules
-
-- `label` is non-empty, max 120 characters.
-- `id` and `semanticClass` are unchanged from the previous state.
-- Entries not being edited remain byte-identical in the output -- partial array rewrites are
-  preferred over wholesale array replacement to minimize diff surface.
-
-## Realistic examples
-
-Rename two sales statuses:
-
-```
-Domain: sales (deal pipeline)
-  new:           "New Lead"        -> "Inbound Lead"
-  proposal:      "Proposal Sent"   -> "Proposal Out"
-  negotiation:   (unchanged)
-```
-
-Rename a System label without changing its ID:
-
-```
-systems:
-  sales.crm:     label "CRM"            -> "Sales Pipeline"
-  (id stays 'sales.crm'; graph node remains 'system:sales.crm')
-```
-
-Rename a sidebar surface:
-
-```
-navigation.sidebar.primary:
-  sales.crm:     label "Pipeline"       -> "Deal Pipeline"
-```
-
-## Validation gate
-
-Every label change must pass before codify completes:
-
-1. `pnpm -C operations check-types`.
-2. `resolveOrganizationModel()` and `OrganizationModelSchema.parse()` succeed on the merged result.
-
-On failure, the codify ceremony rolls back. See `operations/codify-level-a.md` for the rollback
-procedure.
-
----
-
-> **Read via `/knowledge`** -- natural-language queries like "what's the label for the proposal
-> stage?" or "what do we call the SEO System?" route to this domain via the skill's intent
-> classifier. To rename one or more labels, the `/knowledge` skill triggers the codify ceremony
-> when intent classifies as Codify.
+# Labels domain
+
+`label` is an inline display field carried by status entries, stage entries, System entries,
+knowledge nodes, registry entries, and sidebar surfaces in the OrganizationModel. Labels control what users see in the UI and what
+agents say when narrating state. Editing a label does not change the entry's `id` or
+`semanticClass` -- only the human-readable display string. This is Level A only (config-only
+edits to `core/config/organization-model.ts`).
+
+## What carries labels
+
+The following model elements have editable inline `label` fields:
+
+**Status / stage entries.** Each domain that carries an enum-like array exposes per-entry labels:
+
+- `sales.statuses` -- deal pipeline stages.
+- `prospecting.statuses` -- lead lifecycle stages.
+- `projects.statuses` -- project and task stages.
+
+Source of platform defaults: `packages/core/src/organization-model/domains/{sales,prospecting,projects}.ts`.
+
+Each status entry shape:
+
+```typescript
+{ id: 'new', label: 'New Lead', semanticClass: 'active', color: 'blue' }
+```
+
+**Systems.** The `label` field on a System entry. Editing it changes agent narration and any
+System-derived shell text, but it does not change the System `id`, route path, or graph node id.
+
+**Sidebar surfaces.** Routeable leaves under `navigation.sidebar.primary` and
+`navigation.sidebar.bottom` carry labels. Editing changes nav item and breadcrumb display without
+changing the route path or target System refs.
+
+**Knowledge/domain entries.** Knowledge nodes, customers, offerings, goals, roles, resources,
+actions, entities, and policies may carry labels or titles depending on the domain. Edit only the
+display field that already exists on the entry.
+
+## What is NOT in scope
+
+`id` and `semanticClass` of any entry must never change in a label edit -- they are structural
+anchors used by code, hooks, and workflow adapters. Only `label` (and optionally `color` or
+`icon`) are in scope. To rename an `id`, escalate to a separate Level B refactor with explicit
+confirmation, because every consumer that references the old `id` must be updated in the same
+change.
+
+## Validation rules
+
+- `label` is non-empty, max 120 characters.
+- `id` and `semanticClass` are unchanged from the previous state.
+- Entries not being edited remain byte-identical in the output -- partial array rewrites are
+  preferred over wholesale array replacement to minimize diff surface.
+
+## Realistic examples
+
+Rename two sales statuses:
+
+```
+Domain: sales (deal pipeline)
+  new:           "New Lead"        -> "Inbound Lead"
+  proposal:      "Proposal Sent"   -> "Proposal Out"
+  negotiation:   (unchanged)
+```
+
+Rename a System label without changing its ID:
+
+```
+systems:
+  sales.crm:     label "CRM"            -> "Sales Pipeline"
+  (id stays 'sales.crm'; graph node remains 'system:sales.crm')
+```
+
+Rename a sidebar surface:
+
+```
+navigation.sidebar.primary:
+  sales.crm:     label "Pipeline"       -> "Deal Pipeline"
+```
+
+## Validation gate
+
+Every label change must pass before codify completes:
+
+1. `pnpm -C operations check-types`.
+2. `resolveOrganizationModel()` and `OrganizationModelSchema.parse()` succeed on the merged result.
+
+On failure, the codify ceremony rolls back. See `operations/codify-level-a.md` for the rollback
+procedure.
+
+---
+
+> **Read via `/om`** (legacy `/knowledge` alias also accepted) -- natural-language queries like
+> "what's the label for the proposal stage?" or "what do we call the SEO System?" route to this
+> domain via the skill's intent classifier. To rename one or more labels, the `/om` skill triggers
+> the codify ceremony when intent classifies as Codify.

package/reference/claude-config/skills/{knowledge → om}/operations/offerings.md

@@ -1,109 +1,110 @@
-# Offerings domain
-
-The `offerings` domain describes what the organization sells or delivers — a catalog of products
-and services modeled after the Business Model Canvas "Value Propositions". Agents use offerings
-for quoting, proposal generation, and scope-of-work reasoning.
-
-## Schema
-
-Source: `packages/core/src/organization-model/domains/offerings.ts`
-
-```typescript
-OfferingsDomainSchema = z.object({
-  products: z.array(ProductSchema).default([])
-})
-
-ProductSchema = z.object({
-  id:                z.string().trim().min(1).max(100),       // stable ID, e.g. "product-starter-plan"
-  name:              z.string().trim().max(200).default(''),  // display name
-  description:       z.string().trim().max(2000).default(''), // what it delivers
-  pricingModel:      PricingModelSchema.default('custom'),    // 'one-time' | 'subscription' | 'usage-based' | 'custom'
-  price:             z.number().min(0).default(0),            // base price amount (>= 0)
-  currency:          z.string().trim().max(10).default('USD'),// ISO 4217, e.g. "USD", "EUR"
-  targetSegmentIds:  z.array(z.string()).default([]),         // must ref customers.segments[].id
-  deliverySystemId: z.string().optional()                     // optional ref to systems[].id
-})
-```
-
-`pricingModel` values:
-
-- `one-time` -- single purchase (setup fee, project fee)
-- `subscription` -- recurring (monthly/annual SaaS, retainer)
-- `usage-based` -- metered by consumption (API calls, seats)
-- `custom` -- negotiated or bespoke pricing
-
-## Field reference
-
-| Field               | Type     | Max  | Notes                                                    |
-| ------------------- | -------- | ---- | -------------------------------------------------------- |
-| `id`                | string   | 100  | Stable key, min 1 char; e.g. `"product-starter-plan"`    |
-| `name`              | string   | 200  | Display name                                             |
-| `description`       | string   | 2000 | What this product or service delivers                    |
-| `pricingModel`      | enum     | --   | `one-time`, `subscription`, `usage-based`, or `custom`   |
-| `price`             | number   | --   | Base price amount, min 0; use 0 for fully custom pricing |
-| `currency`          | string   | 10   | ISO 4217 code; defaults to `"USD"`                       |
-| `targetSegmentIds`  | string[] | --   | Each entry must reference a `customers.segments[].id`    |
-| `deliverySystemId`  | string   | --   | Optional reference to a `systems[].id`                   |
-
-## Validation rules
-
-- `id` is the stable key; changing it after creation is a breaking change for any downstream
-  references
-- `targetSegmentIds` entries must exist in `customers.segments[].id`; the schema enforces this
-  at parse time — missing references cause `resolveOrganizationModel()` to fail
-- `deliverySystemId` (when present) must exist in `systems[].id`; same parse-time enforcement
-- `price` must be >= 0; use 0 when pricing is fully custom or not yet set
-- `currency` must be a valid ISO 4217 code by convention (the schema only validates length)
-- Cross-reference: if a product is removed, surface any `targetSegmentIds` in other products
-  that reference the removed ID
-
-## Examples
-
-```typescript
-offerings: {
-  products: [
-    {
-      id:               "product-full-service-retainer",
-      name:             "Full-Service Retainer",
-      description:      "End-to-end campaign delivery, reporting, and optimization for SMB clients.",
-      pricingModel:     "subscription",
-      price:            2500,
-      currency:         "USD",
-      targetSegmentIds: ["segment-smb-agencies"],
-      deliverySystemId: undefined
-    },
-    {
-      id:               "product-one-time-audit",
-      name:             "One-Time Operations Audit",
-      description:      "Single-engagement review of current workflows with a remediation roadmap.",
-      pricingModel:     "one-time",
-      price:            1500,
-      currency:         "USD",
-      targetSegmentIds: ["segment-smb-agencies"],
-      deliverySystemId: undefined
-    }
-  ]
-}
-```
-
-## Where it lives in the adapter
-
-`core/config/organization-model.ts` under the `offerings` key of
-`defineOrganizationModel({...})`.
-
-To read current products: open the adapter file and inspect the `offerings.products` array, or
-use `pnpm exec elevasis-sdk knowledge:cat offerings` (external project).
-
-## Write path
-
-To add, edit, or remove a product, the `/knowledge` skill runs the codify ceremony
-(`operations/codify-level-a.md`): snapshot → propose → confirm → write → typecheck → Zod parse →
-rollback on failure. Only the `products` array is written; no other keys in the adapter are
-touched. Before writing, the skill verifies all `targetSegmentIds` and `deliverySystemId`
-references resolve. When adding, append to the array. When editing, replace by `id`. When
-removing, filter out — and surface any dangling references first.
-
----
-
-**Read via `/knowledge`** — natural-language queries like "what do we sell?" or "what's the
-pricing on the retainer?" route to this domain via the skill's intent classifier.
+# Offerings domain
+
+The `offerings` domain describes what the organization sells or delivers — a catalog of products
+and services modeled after the Business Model Canvas "Value Propositions". Agents use offerings
+for quoting, proposal generation, and scope-of-work reasoning.
+
+## Schema
+
+Source: `packages/core/src/organization-model/domains/offerings.ts`
+
+```typescript
+OfferingsDomainSchema = z.object({
+  products: z.array(ProductSchema).default([])
+})
+
+ProductSchema = z.object({
+  id:                z.string().trim().min(1).max(100),       // stable ID, e.g. "product-starter-plan"
+  name:              z.string().trim().max(200).default(''),  // display name
+  description:       z.string().trim().max(2000).default(''), // what it delivers
+  pricingModel:      PricingModelSchema.default('custom'),    // 'one-time' | 'subscription' | 'usage-based' | 'custom'
+  price:             z.number().min(0).default(0),            // base price amount (>= 0)
+  currency:          z.string().trim().max(10).default('USD'),// ISO 4217, e.g. "USD", "EUR"
+  targetSegmentIds:  z.array(z.string()).default([]),         // must ref customers.segments[].id
+  deliverySystemId: z.string().optional()                     // optional ref to systems[].id
+})
+```
+
+`pricingModel` values:
+
+- `one-time` -- single purchase (setup fee, project fee)
+- `subscription` -- recurring (monthly/annual SaaS, retainer)
+- `usage-based` -- metered by consumption (API calls, seats)
+- `custom` -- negotiated or bespoke pricing
+
+## Field reference
+
+| Field              | Type     | Max  | Notes                                                    |
+| ------------------ | -------- | ---- | -------------------------------------------------------- |
+| `id`               | string   | 100  | Stable key, min 1 char; e.g. `"product-starter-plan"`    |
+| `name`             | string   | 200  | Display name                                             |
+| `description`      | string   | 2000 | What this product or service delivers                    |
+| `pricingModel`     | enum     | --   | `one-time`, `subscription`, `usage-based`, or `custom`   |
+| `price`            | number   | --   | Base price amount, min 0; use 0 for fully custom pricing |
+| `currency`         | string   | 10   | ISO 4217 code; defaults to `"USD"`                       |
+| `targetSegmentIds` | string[] | --   | Each entry must reference a `customers.segments[].id`    |
+| `deliverySystemId` | string   | --   | Optional reference to a `systems[].id`                   |
+
+## Validation rules
+
+- `id` is the stable key; changing it after creation is a breaking change for any downstream
+  references
+- `targetSegmentIds` entries must exist in `customers.segments[].id`; the schema enforces this
+  at parse time — missing references cause `resolveOrganizationModel()` to fail
+- `deliverySystemId` (when present) must exist in `systems[].id`; same parse-time enforcement
+- `price` must be >= 0; use 0 when pricing is fully custom or not yet set
+- `currency` must be a valid ISO 4217 code by convention (the schema only validates length)
+- Cross-reference: if a product is removed, surface any `targetSegmentIds` in other products
+  that reference the removed ID
+
+## Examples
+
+```typescript
+offerings: {
+  products: [
+    {
+      id:               "product-full-service-retainer",
+      name:             "Full-Service Retainer",
+      description:      "End-to-end campaign delivery, reporting, and optimization for SMB clients.",
+      pricingModel:     "subscription",
+      price:            2500,
+      currency:         "USD",
+      targetSegmentIds: ["segment-smb-agencies"],
+      deliverySystemId: undefined
+    },
+    {
+      id:               "product-one-time-audit",
+      name:             "One-Time Operations Audit",
+      description:      "Single-engagement review of current workflows with a remediation roadmap.",
+      pricingModel:     "one-time",
+      price:            1500,
+      currency:         "USD",
+      targetSegmentIds: ["segment-smb-agencies"],
+      deliverySystemId: undefined
+    }
+  ]
+}
+```
+
+## Where it lives in the adapter
+
+`core/config/organization-model.ts` under the `offerings` key of
+`defineOrganizationModel({...})`.
+
+To read current products: open the adapter file and inspect the `offerings.products` array, or
+use `pnpm exec elevasis-sdk om:cat offerings` (external project).
+
+## Write path
+
+To add, edit, or remove a product, the `/om` skill runs the codify ceremony
+(`operations/codify-level-a.md`): snapshot → propose → confirm → write → typecheck → Zod parse →
+rollback on failure. Only the `products` array is written; no other keys in the adapter are
+touched. Before writing, the skill verifies all `targetSegmentIds` and `deliverySystemId`
+references resolve. When adding, append to the array. When editing, replace by `id`. When
+removing, filter out — and surface any dangling references first.
+
+---
+
+**Read via `/om`** (legacy `/knowledge` alias also accepted) — natural-language queries like
+"what do we sell?" or "what's the pricing on the retainer?" route to this domain via the skill's
+intent classifier.

package/reference/claude-config/skills/{knowledge → om}/operations/roles.md

@@ -1,99 +1,100 @@
-# Roles domain
-
-The `roles` domain describes who does what inside the organization — a role chart inspired by the
-EOS Accountability Chart but using plain-language field names throughout. Agents use this domain
-for HITL routing, escalation logic, and approval-rights reasoning.
-
-Field names are developer-facing; when narrating to users, say "role", "responsibilities",
-"reports to", and "held by". Do not say "seat", "accountability", or "EOS".
-
-## Schema
-
-Source: `packages/core/src/organization-model/domains/roles.ts`
-
-```typescript
-RolesDomainSchema = z.object({
-  roles: z.array(RoleSchema).default([])
-})
-
-RoleSchema = z.object({
-  id:               z.string().trim().min(1).max(100),              // stable ID, e.g. "role-ceo"
-  title:            z.string().trim().min(1).max(200),              // display title, e.g. "CEO"
-  responsibilities: z.array(z.string().trim().max(500)).default([]),// what this role owns
-  reportsToId:      z.string().trim().min(1).max(100).optional(),   // must ref another roles[].id
-  heldBy:           z.string().trim().max(200).optional()           // name or email, free-form
-})
-```
-
-## Field reference
-
-| Field              | Type     | Max | Notes                                                           |
-| ------------------ | -------- | --- | --------------------------------------------------------------- |
-| `id`               | string   | 100 | Stable key, min 1 char; e.g. `"role-ceo"`                       |
-| `title`            | string   | 200 | Display title; min 1 char required                              |
-| `responsibilities` | string[] | 500 | Each item: one thing this role is accountable for               |
-| `reportsToId`      | string   | 100 | Optional; must reference another `roles[].id` in the collection |
-| `heldBy`           | string   | 200 | Optional; name or email of the person holding this role         |
-
-## Validation rules
-
-- `reportsToId` (when present) must resolve to another `roles[].id` in the same collection;
-  enforced at parse time by `OrganizationModelSchema.superRefine()`
-- Absence of `reportsToId` indicates a top-level role (no reporting line)
-- Cycle detection is not enforced by the schema (known limitation); agents should surface
-  obvious cycles (e.g. role A reports to role B which reports to role A)
-- `heldBy` is free-form; no validation beyond max length
-- An empty roles array means no HITL routing or escalation rules are available
-
-## Examples
-
-```typescript
-roles: {
-  roles: [
-    {
-      id:               "role-ceo",
-      title:            "CEO",
-      responsibilities: [
-        "Set company direction",
-        "Final approval on deals >$10K",
-        "Manage investor relations"
-      ],
-      reportsToId: undefined,
-      heldBy:      "Alice Johnson"
-    },
-    {
-      id:               "role-head-of-client-success",
-      title:            "Head of Client Success",
-      responsibilities: [
-        "Own client health scores",
-        "Lead quarterly business reviews",
-        "Handle escalations"
-      ],
-      reportsToId: "role-ceo",
-      heldBy:      undefined
-    }
-  ]
-}
-```
-
-## Where it lives in the adapter
-
-`core/config/organization-model.ts` under the `roles` key of
-`defineOrganizationModel({...})`.
-
-To read the current role chart: open the adapter file and inspect the `roles.roles` array, or
-use `pnpm exec elevasis-sdk knowledge:cat roles` (external project).
-
-## Write path
-
-To add, edit, or remove a role, the `/knowledge` skill runs the codify ceremony
-(`operations/codify-level-a.md`): snapshot → propose → confirm → write → typecheck → Zod parse →
-rollback on failure. Only the `roles` array is written; no other keys in the adapter are touched.
-Before writing, the skill verifies all `reportsToId` references resolve to IDs that will exist
-after the write. When removing a role, the skill surfaces any other roles that `reportsToId` to it
-and asks whether to clear those reporting lines before proceeding.
-
----
-
-**Read via `/knowledge`** — natural-language queries like "who is responsible for client
-escalations?" or "list my roles" route to this domain via the skill's intent classifier.
+# Roles domain
+
+The `roles` domain describes who does what inside the organization — a role chart inspired by the
+EOS Accountability Chart but using plain-language field names throughout. Agents use this domain
+for HITL routing, escalation logic, and approval-rights reasoning.
+
+Field names are developer-facing; when narrating to users, say "role", "responsibilities",
+"reports to", and "held by". Do not say "seat", "accountability", or "EOS".
+
+## Schema
+
+Source: `packages/core/src/organization-model/domains/roles.ts`
+
+```typescript
+RolesDomainSchema = z.object({
+  roles: z.array(RoleSchema).default([])
+})
+
+RoleSchema = z.object({
+  id:               z.string().trim().min(1).max(100),              // stable ID, e.g. "role-ceo"
+  title:            z.string().trim().min(1).max(200),              // display title, e.g. "CEO"
+  responsibilities: z.array(z.string().trim().max(500)).default([]),// what this role owns
+  reportsToId:      z.string().trim().min(1).max(100).optional(),   // must ref another roles[].id
+  heldBy:           z.string().trim().max(200).optional()           // name or email, free-form
+})
+```
+
+## Field reference
+
+| Field              | Type     | Max | Notes                                                           |
+| ------------------ | -------- | --- | --------------------------------------------------------------- |
+| `id`               | string   | 100 | Stable key, min 1 char; e.g. `"role-ceo"`                       |
+| `title`            | string   | 200 | Display title; min 1 char required                              |
+| `responsibilities` | string[] | 500 | Each item: one thing this role is accountable for               |
+| `reportsToId`      | string   | 100 | Optional; must reference another `roles[].id` in the collection |
+| `heldBy`           | string   | 200 | Optional; name or email of the person holding this role         |
+
+## Validation rules
+
+- `reportsToId` (when present) must resolve to another `roles[].id` in the same collection;
+  enforced at parse time by `OrganizationModelSchema.superRefine()`
+- Absence of `reportsToId` indicates a top-level role (no reporting line)
+- Cycle detection is not enforced by the schema (known limitation); agents should surface
+  obvious cycles (e.g. role A reports to role B which reports to role A)
+- `heldBy` is free-form; no validation beyond max length
+- An empty roles array means no HITL routing or escalation rules are available
+
+## Examples
+
+```typescript
+roles: {
+  roles: [
+    {
+      id:               "role-ceo",
+      title:            "CEO",
+      responsibilities: [
+        "Set company direction",
+        "Final approval on deals >$10K",
+        "Manage investor relations"
+      ],
+      reportsToId: undefined,
+      heldBy:      "Alice Johnson"
+    },
+    {
+      id:               "role-head-of-client-success",
+      title:            "Head of Client Success",
+      responsibilities: [
+        "Own client health scores",
+        "Lead quarterly business reviews",
+        "Handle escalations"
+      ],
+      reportsToId: "role-ceo",
+      heldBy:      undefined
+    }
+  ]
+}
+```
+
+## Where it lives in the adapter
+
+`core/config/organization-model.ts` under the `roles` key of
+`defineOrganizationModel({...})`.
+
+To read the current role chart: open the adapter file and inspect the `roles.roles` array, or
+use `pnpm exec elevasis-sdk om:cat roles` (external project).
+
+## Write path
+
+To add, edit, or remove a role, the `/om` skill runs the codify ceremony
+(`operations/codify-level-a.md`): snapshot → propose → confirm → write → typecheck → Zod parse →
+rollback on failure. Only the `roles` array is written; no other keys in the adapter are touched.
+Before writing, the skill verifies all `reportsToId` references resolve to IDs that will exist
+after the write. When removing a role, the skill surfaces any other roles that `reportsToId` to it
+and asks whether to clear those reporting lines before proceeding.
+
+---
+
+**Read via `/om`** (legacy `/knowledge` alias also accepted) — natural-language queries like
+"who is responsible for client escalations?" or "list my roles" route to this domain via the
+skill's intent classifier.