@elevasis/sdk 1.44.2 → 1.45.0

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

@@ -1,237 +0,0 @@
----
-name: build
-description: Guided Codify-ceremony runbook for building a new Organization Model System end to end in a tenant project — shell, ontology, resources, topology, knowledge node, and verify.
-allowed-tools: Read, Glob, Grep, Bash
----
-
-# /om build (Tenant)
-
-Intent-driven runbook for authoring a complete Organization Model System in this tenant project.
-The **primary entry is intent**: `/om` routes free-text build intent here via `promptSignals` and
-the 5-bucket classifier whenever you describe a system you want to build. Manual `/om build` is a
-supported secondary entry.
-
-Every write runs through the Codify ceremony (snapshot → propose → confirm → write → validate →
-rollback). See the "Write Power" section in `SKILL.md` for the ceremony steps.
-
-**Tenant authoring files** (split layout):
-
-- `core/config/organization-model/systems.ts` — System entries and system-owned resources
-- `core/config/organization-model/navigation.ts` — sidebar wiring
-- `core/config/knowledge/nodes/` — knowledge node MDX files
-
----
-
-## Phase 0 — Capture Intent
-
-Before writing anything, extract:
-
-1. **System name and dotted path** (`parent.child` format, e.g. `sales.crm`).
-2. **Kind**: `product`, `operational`, `platform`, or `diagnostic`.
-3. **What it does** — one sentence. This becomes the `description`.
-4. **What it owns** — objects, actions, catalogs, events (these become `system.ontology` entries).
-5. **What it calls or reacts to** — other systems, triggers, human checkpoints.
-6. **Whether it needs a UI route** — yes/no determines whether `system.ui` is authored.
-7. **Whether it adopts a platform API interface** — yes/no determines whether `system.apiInterface`
-   is authored (see "API Interface Readiness" in `SKILL.md`).
-
-Run a pre-flight read to ground id choices in current model state:
-
-```bash
-pnpm elevasis-sdk om:ls /all-systems
-```
-
----
-
-## Phase 1 — System Shell (Codify Level-A)
-
-Use `om:scaffold:system` (dry-run first) or the Codify Level-A ceremony to add the `SystemEntry`
-to `core/config/organization-model/systems.ts`.
-
-**Dry-run:**
-
-```bash
-pnpm elevasis-sdk om:scaffold:system --dry-run
-```
-
-Minimum fields: `id`, `order`, `label`. Optional at this stage: `description`, `kind`,
-`lifecycle`, `responsibleRoleId`.
-
-**Validate after write:**
-
-```bash
-pnpm -C operations check-types
-pnpm -C operations check
-```
-
----
-
-## Phase 2 — Ontology (`system.ontology`)
-
-Add owned ontology kinds inside the `ontology` field of the `SystemEntry` in `systems.ts`.
-
-Valid scope keys: `objectTypes`, `linkTypes`, `actionTypes`, `catalogTypes`, `eventTypes`,
-`interfaceTypes`, `valueTypes`, `sharedProperties`, `groups`, `endpoints`.
-
-All ids use the canonical format: `system.path:kind/local-id`
-(e.g. `sales.crm:object/deal`, `sales.crm:action/qualify-lead`).
-
-Apply via the Codify Level-A ceremony — read, propose diff, confirm, write, validate.
-
-**Validate after write:**
-
-```bash
-pnpm -C operations check-types
-pnpm -C operations check
-```
-
----
-
-## Phase 3 — Resources (Codify Level-A + scaffold)
-
-Add resource entries to `systems.ts` (or the split `resources` section if your project uses one).
-Each resource carries `systemPath` (canonical system attachment) and `ontology` bindings.
-
-Use `om:scaffold:resource` for guided creation, or Codify Level-A for manual addition.
-
-**Dry-run:**
-
-```bash
-pnpm elevasis-sdk om:scaffold:resource --dry-run --system-path <your.system>
-```
-
-Key invariants:
-
-- `resource.systemPath` is the canonical attachment for `getResourcesForSystem()`.
-- Choose `systemPath` based on the business capability the resource operates, not its kind.
-- `primaryAction` must be a member of `resource.ontology.actions`.
-
-**Validate after write:**
-
-```bash
-pnpm -C operations check-types
-pnpm -C operations check
-```
-
----
-
-## Phase 4 — Topology (optional)
-
-If the system reacts to events, calls other systems, or requires human checkpoints, author
-topology relationships. In a tenant project, topology lives alongside the System entries in
-`systems.ts` (or a dedicated `topology` field if your project uses the split layout with a
-separate topology section).
-
-Canonical relationship kinds:
-
-- `triggers` — event, webhook, or schedule fires a resource handler
-- `uses` — this system calls another system or integration
-- `approval` — a step requires human checkpoint before continuing
-
-Cross-system API handoff requires a `uses` edge with `systemInterfaceGrant` metadata — see the
-"API Interface Readiness" section in `SKILL.md`.
-
-Apply via Codify Level-A ceremony. Validate after each topology write.
-
----
-
-## Phase 5 — Knowledge Node (optional)
-
-Author a governing knowledge node to make the system searchable via `/om` and surfaced in the
-knowledge browser.
-
-Use `om:scaffold:knowledge` for guided creation:
-
-```bash
-pnpm elevasis-sdk om:scaffold:knowledge --dry-run --system-path <your.system> --kind playbook
-```
-
-MDX frontmatter shape:
-
-```mdx
----
-id: knowledge.my-system-playbook
-kind: playbook
-label: My System Playbook
-description: Rules and patterns for operating My System.
-governs:
-  - my.system
----
-```
-
-After authoring, regenerate the knowledge index:
-
-```bash
-pnpm elevasis-sdk om:generate
-```
-
----
-
-## Phase 6 — UI and Navigation (optional)
-
-If the system needs a sidebar entry, author `system.ui` and add a navigation surface entry.
-
-`system.ui` fields: `path`, `surfaces[]`, `icon`, `order`. Apply via Codify Level-A.
-
-Navigation wiring lives in `core/config/organization-model/navigation.ts`. Add the system's
-path to the relevant sidebar section. Validate after the navigation write.
-
----
-
-## Phase 7 — apiInterface (API-backed systems only)
-
-`system.apiInterface` is adopt-only in tenant projects. Only add it when the system adopts a
-platform-provided API capability from the installed `@elevasis/core` / `@elevasis/sdk` version.
-Use only readiness profiles listed in
-`operations/node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md`.
-
-The profile also fixes the required System path — do not invent a profile or repoint a cataloged
-profile to a custom path.
-
-Apply via Codify Level-A after confirming the readiness profile with the user:
-
-```bash
-pnpm -C operations check-types
-pnpm -C operations check   # conformance gate fires here if the marker is incomplete
-```
-
----
-
-## Phase 8 — Full Verify
-
-Run both validation gates once all phases are done:
-
-```bash
-pnpm -C operations check-types
-pnpm -C operations check
-```
-
-If the conformance gate reports a gaps file, apply it:
-
-```bash
-pnpm elevasis-sdk om:scaffold:fill --gaps .elevasis/conformance-gaps.json --dry-run
-```
-
----
-
-## Quick Reference
-
-| Phase | OM Slot                           | Authoring File                    | Ceremony                |
-| ----- | --------------------------------- | --------------------------------- | ----------------------- |
-| 1     | `systems` map                     | `systems.ts`                      | Scaffold or Level-A     |
-| 2     | `system.ontology.<scope>`         | `systems.ts`                      | Level-A                 |
-| 3     | resources + `resource.systemPath` | `systems.ts`                      | Scaffold or Level-A     |
-| 4     | topology relationships            | `systems.ts` / topology section   | Level-A                 |
-| 5     | `system.governedByKnowledge[]`    | `knowledge/nodes/<path>/<id>.mdx` | Scaffold or Level-A     |
-| 6     | `system.ui` + navigation surfaces | `systems.ts` + `navigation.ts`    | Level-A                 |
-| 7     | `system.apiInterface`             | `systems.ts`                      | Level-A (adopt-only)    |
-| 8     | —                                 | —                                 | `check` + `check-types` |
-
----
-
-## Cross-Links
-
-- Codify Level-A ceremony: `.claude/skills/om/operations/codify-level-a.md`
-- Scaffold (guided new entries): `.claude/skills/om/operations/scaffold.md`
-- API interface readiness: "API Interface Readiness" section in `.claude/skills/om/SKILL.md`
-- Platform narrative guide + worked examples: `operations/node_modules/@elevasis/sdk/reference/guides/building-systems.md` (if present)

package/reference/claude-config/skills/om/operations/codify-level-a.md

@@ -1,109 +0,0 @@
-# Codify Pipeline: Level A (Config-Only Edits)
-
-Level A is the codify pipeline for changes that land in a single config file inside
-`core/config/`. No new TypeScript files are created. The entire ceremony is: snapshot the target
-file, propose the edit, write the edit, validate, and roll back on failure.
-
-This pipeline is called by domain operations (identity, customers, offerings, roles, goals,
-techStack, systems, actions, labels, and legacy feature compatibility) after the user has confirmed the proposed change. The caller provides
-the specific field/block being changed, the proposed new value, and the target file.
-
----
-
-## Pipeline
-
-### Step 1: Snapshot
-
-Before any write, read `TARGET_FILE` and keep the full file content in memory as the rollback
-snapshot. Do not write any file during this step.
-
-```
-Read(TARGET_FILE)
--- store as ROLLBACK_SNAPSHOT
-```
-
-`TARGET_FILE` is the value the caller provides in the Caller Contract (see below). When the
-project has not been split yet, callers pass the default
-`core/config/organization-model.ts`.
-
-### Step 2: Apply the edit
-
-Use the Edit tool to apply the caller's proposed change to `TARGET_FILE`.
-
-Rules for the edit:
-
-- Edit only the specific field or block the caller specified. Do not reformat or restructure
-  unrelated sections.
-- For edits targeting `profile.ts`: preserve all other keys in `defineOrganizationModel({...})`
-  exactly as they are.
-- Maintain the existing code style (trailing commas, quote style, indentation) of the file.
-- If the target field does not yet exist in the file, add it as a new property in the appropriate
-  position (following the declared domain order in the schema).
-
-### Step 3: TypeScript type-check
-
-Run the type-check for the operations package:
-
-```bash
-pnpm -C operations check-types
-```
-
-Capture stdout and stderr. If the command exits non-zero, proceed to Step 5 (rollback).
-
-### Step 4: Runtime schema validation
-
-Confirm that the adapter's output passes `OrganizationModelSchema.parse()`. The adapter calls
-`resolveOrganizationModel()` internally, which merges defaults with overrides and then parses the
-result. A successful `check-types` pass is strong evidence that the schema is valid, but
-cross-reference checks (segment ID refs in offerings, role reporting refs, period ordering in
-goals) are runtime-only.
-
-If the project exposes a validation script (e.g. `pnpm -C operations check`), run that too:
-
-```bash
-pnpm -C operations check
-```
-
-If either validation step fails, proceed to Step 5 (rollback).
-
-### Step 5: Rollback (on failure only)
-
-If Step 3 or Step 4 failed:
-
-1. Write the ROLLBACK_SNAPSHOT content back to `TARGET_FILE` verbatim (use the Write tool with
-   the exact snapshot content).
-2. Confirm the file has been restored by checking that the content matches the snapshot.
-3. Return the error message to the caller.
-
-The caller is responsible for reporting the rollback to the user.
-
-### Step 6: Success signal
-
-If Steps 3 and 4 both passed, return a success signal to the caller with:
-
-- The file edited (`TARGET_FILE`)
-- The fields changed
-- `Type-check: PASS`
-- `Schema validation: PASS`
-
-The caller formats and presents the final report.
-
----
-
-## Caller Contract
-
-Callers must provide before invoking this pipeline:
-
-- **Target file:** the sub-file path to snapshot and edit. Default (unsplit projects):
-  `core/config/organization-model.ts`. Split-project routing:
-  - `core/config/organization-model/profile.ts` for identity, customers, offerings, roles, goals
-    (and techStack/labels when those keys exist in `profile.ts`)
-  - `core/config/organization-model/systems.ts` for systems, actions, resources
-  - Callers use the default entry path when the domain does not yet have a dedicated sub-file
-- **Target block:** the specific domain key or sub-key being changed (e.g. `identity`,
-  `customers.segments`, `roles.roles`, `resources.hubspot`)
-- **Proposed value:** the new TypeScript literal to write for that block
-- **Confirmed:** the user has already said yes to the proposed change
-
-This pipeline does not ask the user any questions. All confirmation happens in the domain
-operation before this pipeline is invoked.

package/reference/claude-config/skills/om/operations/codify-level-b.md

@@ -1,159 +0,0 @@
-# Codify Pipeline: Level B (New Extension TypeScript Files)
-
-Level B is the codify pipeline for changes that require creating a new TypeScript file under
-`core/config/extensions/`. This pipeline is used when the user wants to add or extend a System,
-add an Action, add a custom entity type, or make any structural addition that cannot be expressed as a simple
-field override in `core/config/organization-model.ts`.
-
-Level B is **only offered when the user explicitly asks** for something that requires a new file.
-Never silently escalate from Level A to Level B. If Level A is sufficient, use it.
-
----
-
-## When Level B applies
-
-- Adding or extending a System that does not exist in the platform defaults, including routing,
-  manifest wiring, and route references
-- Adding an Action that is invokable by a workflow, agent, command, or UI trigger
-- Adding a custom entity extension (new Zod schema extending a base entity type)
-- Any structural addition the caller's domain operation has determined cannot be expressed as a
-  field value in the existing adapter
-
-The calling operation (or the legacy compatibility notes in `features.md`) is responsible for deciding when Level B is needed
-and for confirming the intent with the user before invoking this pipeline.
-
----
-
-## Pipeline
-
-### Step 1: Snapshot all files that will be touched
-
-Before any write, read and snapshot:
-
-1. `core/config/organization-model.ts` (always touched for wiring)
-2. The target extension file path (if it already exists -- confirm overwrite with user)
-
-```
-Read("core/config/organization-model.ts")   -- store as ROLLBACK_ADAPTER
-Read("core/config/extensions/{target}.ts")  -- store as ROLLBACK_EXTENSION (if exists)
-```
-
-The target extension file path follows the naming convention:
-`core/config/extensions/{kebab-case-system-or-action-id}.ts`
-
-### Step 2: Scaffold the extension file
-
-Create `core/config/extensions/{id}.ts` using the Write tool.
-
-The file shape depends on the extension type:
-
-**Custom system/action extension (common Level B case):**
-
-```typescript
-/**
- * {System or action label} extension.
- * Registered in core/config/organization-model.ts.
- */
-import type { OrganizationModelSystem } from '@elevasis/core/organization-model'
-
-export const {SYSTEM_CONST}: OrganizationModelSystem = {
-  id: '{system-or-action-id}',
-  label: '{System or Action Label}',
-  description: '{optional description}',
-  enabled: true,
-  entityIds: [],
-  surfaceIds: [],
-  resourceIds: [],
-  actionIds: [],
-}
-```
-
-Replace `{SYSTEM_CONST}` with the SCREAMING_SNAKE_CASE version of the system or action ID
-(e.g. `CLIENT_PORTAL_SYSTEM`).
-
-The caller provides the exact field values based on what the user confirmed.
-
-### Step 3: Wire the extension into the adapter
-
-Edit `core/config/organization-model.ts` to:
-
-1. Import the new constant from the extension file.
-2. Add it to the appropriate `systems` or `actions` collection in the `defineOrganizationModel({...})` call.
-
-Example import addition:
-
-```typescript
-import { CLIENT_PORTAL_SYSTEM } from './extensions/client-portal'
-```
-
-Example system collection addition:
-
-```typescript
-systems: [
-  ...existingSystems,
-  CLIENT_PORTAL_SYSTEM,
-],
-```
-
-### Step 4: TypeScript type-check
-
-```bash
-pnpm -C operations check-types
-```
-
-Capture stdout and stderr. If the command exits non-zero, proceed to Step 6 (rollback).
-
-### Step 5: Runtime schema validation
-
-```bash
-pnpm -C operations check
-```
-
-If either check fails, proceed to Step 6 (rollback).
-
-### Step 6: Rollback (on failure only)
-
-If Step 4 or Step 5 failed:
-
-1. Restore `core/config/organization-model.ts` from ROLLBACK_ADAPTER.
-2. If the extension file did not previously exist, delete it. If it previously existed, restore
-   from ROLLBACK_EXTENSION.
-3. Re-run `pnpm -C operations check-types` to confirm the restore is clean. If the restore
-   itself fails type-check, report both the original error and the restore state to the user --
-   do not silently leave the project in a broken state.
-4. Return the error message to the caller.
-
-### Step 7: Success signal
-
-If Steps 4 and 5 both passed, return a success signal to the caller with:
-
-- Extension file path created
-- Adapter wiring changes (import + systems/actions collection entry)
-- `Type-check: PASS`
-- `Schema validation: PASS`
-
-The caller formats and presents the final report to the user.
-
----
-
-## Caller Contract
-
-Callers must provide before invoking this pipeline:
-
-- **Extension file path:** `core/config/extensions/{id}.ts`
-- **Extension file content:** the full TypeScript content for the new file
-- **Adapter changes:** the exact import line and systems/actions collection addition to write into the adapter
-- **Confirmed:** the user has already said yes to the proposed change and explicitly requested
-  a new extension file
-
-This pipeline does not ask the user any questions. All confirmation and escalation decisions
-happen in the domain operation before this pipeline is invoked.
-
----
-
-## Constraint: Extension files are Tier 3 (never synced)
-
-Files under `core/config/extensions/` are Tier 3 -- project-specific, never overwritten
-by `/external sync`. This means custom systems, actions, and entity extensions survive template upgrades
-automatically. Do not put platform-default overrides in extension files; those belong directly in
-`core/config/organization-model.ts` (Tier 2, merge-aware).

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

@@ -1,114 +0,0 @@
-# Customers domain
-
-The `customers` domain describes who the organization serves — distinct buyer archetypes modeled
-after the Value Proposition Canvas (BMC / VPC). Each segment captures jobs-to-be-done, pains,
-gains, firmographics, and a value proposition. Agents use these segments for targeting, outreach
-context, and personalization.
-
-## Schema
-
-Source: `packages/core/src/organization-model/domains/customers.ts`
-
-```typescript
-CustomersDomainSchema = z.object({
-  segments: z.array(CustomerSegmentSchema).default([])
-})
-
-CustomerSegmentSchema = z.object({
-  id:           z.string().trim().min(1).max(100),             // stable ID, e.g. "segment-smb-agencies"
-  name:         z.string().trim().max(200).default(''),        // display name
-  description:  z.string().trim().max(2000).default(''),       // who this segment is
-  jobsToBeDone: z.string().trim().max(2000).default(''),       // the goal they hire you to accomplish
-  pains:        z.array(z.string().trim().max(500)).default([]),
-  gains:        z.array(z.string().trim().max(500)).default([]),
-  firmographics: FirmographicsSchema.default({}),              // industry, companySize, region
-  valueProp:    z.string().trim().max(2000).default('')        // why your offering fits this segment
-})
-
-FirmographicsSchema = z.object({
-  industry:    z.string().trim().max(200).optional(),  // e.g. "Marketing Agency"
-  companySize: z.string().trim().max(100).optional(),  // e.g. "11–50"
-  region:      z.string().trim().max(200).optional()   // e.g. "North America"
-})
-```
-
-## Field reference
-
-| Field           | Type     | Max  | Notes                                                        |
-| --------------- | -------- | ---- | ------------------------------------------------------------ |
-| `id`            | string   | 100  | Stable key, min 1 char; e.g. `"segment-smb-agencies"`        |
-| `name`          | string   | 200  | Display name                                                 |
-| `description`   | string   | 2000 | Who this segment is in one or two sentences                  |
-| `jobsToBeDone`  | string   | 2000 | The goal they hire you to accomplish, in their terms         |
-| `pains`         | string[] | 500  | Each item: a frustration or obstacle                         |
-| `gains`         | string[] | 500  | Each item: an outcome or benefit they hope for               |
-| `firmographics` | object   | --   | Optional industry, companySize, region filters for targeting |
-| `valueProp`     | string   | 2000 | Why your offering uniquely addresses this segment's needs    |
-
-## Validation rules
-
-- `id` is the stable key used by `offerings.products[].targetSegmentIds` references; once set,
-  changing the `id` of a segment breaks any offering that references it
-- `firmographics` is optional; all three sub-fields (`industry`, `companySize`, `region`) are
-  individually optional
-- `pains` and `gains` default to empty arrays; agents should treat an empty array as unconfigured
-- There is no uniqueness constraint enforced by the schema on `id`, but agents must treat it as
-  unique and surface duplicates if found
-- Cross-reference: if a segment is removed, any `offerings.products[].targetSegmentIds` that
-  reference its `id` become dangling references; surface a warning before removing
-
-## Examples
-
-```typescript
-customers: {
-  segments: [
-    {
-      id:           "segment-smb-agencies",
-      name:         "SMB Marketing Agencies",
-      description:  "Owner-operated agencies with 1–15 employees running campaign delivery for SMB clients.",
-      jobsToBeDone: "Deliver consistent client results without adding headcount.",
-      pains: [
-        "Manual campaign QA eats time",
-        "Client reporting takes hours each week",
-        "Hard to scale without hiring"
-      ],
-      gains: [
-        "More client capacity without more staff",
-        "Predictable delivery timelines"
-      ],
-      firmographics: {
-        industry:    "Marketing Agency",
-        companySize: "1–15",
-        region:      "North America"
-      },
-      valueProp: "Automates the repetitive delivery and reporting work so agencies can take on more clients."
-    }
-  ]
-}
-```
-
-## Where it lives in the adapter
-
-**Split projects:** `core/config/organization-model/profile.ts` under the `customers` key of
-`defineOrganizationModel({...})`.
-
-**Unsplit projects:** `core/config/organization-model.ts` under the same key.
-
-To read current segments: open the appropriate file and inspect the `customers.segments` array,
-or use `pnpm exec elevasis-sdk om:cat customers` (external project).
-
-## Write path
-
-To add, edit, or remove a segment, the `/om` skill runs the codify ceremony
-(`operations/codify-level-a.md`): snapshot → propose → confirm → write → typecheck → Zod parse →
-rollback on failure. Pass `targetFile` as `core/config/organization-model/profile.ts` for split
-projects, or `core/config/organization-model.ts` for unsplit projects. Only the `segments` array
-is written; no other keys in the target file are touched. When adding, append to the array. When
-editing, replace the matching entry by `id`. When removing, filter it out — and surface any
-dangling `targetSegmentIds` references first.
-
----
-
-**Read via `/om`** (legacy `/knowledge` alias also accepted) — natural-language queries like
-"who are our customer segments?" or "what pains does the agency segment have?" route to this
-domain via the skill's intent classifier.