@elevasis/sdk 1.22.0 → 1.23.0

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

@@ -0,0 +1,324 @@
+---
+name: om
+description: |
+  TRIGGER this skill when any of the following apply:
+  - The user references organization-model entities by name or concept: identity, customers,
+    offerings, roles, goals, techStack, systems, actions, labels, knowledge nodes, governance edges,
+    mounts, playbook, outreach cadence, or any domain in the org model.
+  - The user asks to read, list, find, show, query, navigate, describe, codify, add, edit,
+    update, toggle, enable, or disable any organization-model domain or knowledge node.
+  - The user asks "what governs X?", "what does X control?", "system governs", "what is our
+    identity set to?", "what's our timezone?", "show me all reference docs", "list my roles",
+    "where does outreach-cadence apply?", or similar.
+  - An agent is editing files matching: core/config/organization-model.ts or
+    core/config/knowledge/**.
+  SKIP this skill when the task is purely UI layout, workflow authoring, or infrastructure
+  work with no reference to org-model or knowledge-graph entities.
+
+  /knowledge is preserved as a permanent alias for muscle memory; both names route here.
+metadata:
+  pathPatterns:
+    - "core/config/organization-model.ts"
+    - "core/config/knowledge/**"
+    - "core/config/extensions/**"
+  promptSignals:
+    phrases:
+      - playbook
+      - knowledge node
+      - system governs
+      - outreach cadence
+      - identity
+      - customer segment
+      - codify
+      - enable system
+      - toggle system
+      - what governs
+      - org model
+      - organization model
+      - offerings
+      - techStack
+      - roles
+      - goals
+      - labels
+      - knowledge map
+      - governance edge
+      - knowledge mount
+      - knowledge graph
+      - knowledge browser
+      - ontology
+      - by-ontology
+      - list my roles
+      - what is our
+      - show me all reference docs
+      - where does
+      - apply
+context: fork
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# OM (Organization Model)
+
+Unified intent-inferring skill for all organization-model interaction in this tenant project.
+Reads OM state through the `elevasis-sdk om:*` CLI surface (or the legacy `knowledge:*` aliases
+that still work); writes run through the Codify/Toggle ceremony. No verb namespace is required --
+the skill classifies intent from conversation context and routes internally.
+
+The slash command was renamed from `/knowledge` to `/om`; `/knowledge` is preserved as a permanent
+alias. Both invocations land here.
+
+---
+
+## When to Invoke
+
+This skill auto-invokes whenever:
+
+- Conversation references org-model entities (identity, customers, offerings, roles, goals,
+  techStack, systems, actions, labels, knowledge nodes, governance edges, mounts)
+- The user asks to read, list, find, show, query, navigate, describe, codify, add, edit,
+  update, toggle, enable, or disable any of those
+- An agent is editing files matching `core/config/organization-model.ts`,
+  `core/config/extensions/**`, or `core/config/knowledge/**`
+
+Auto-invocation is driven by frontmatter `description`, `metadata.pathPatterns`, and
+`metadata.promptSignals` -- no explicit prefix is required.
+
+---
+
+## 5-Bucket Decision Tree
+
+Once invoked, classify the user's input into ONE of these buckets and dispatch the matching
+primitive. When two buckets fit, prefer the higher one (more specific → more general).
+
+| #   | Bucket                         | Trigger                                                                           | Dispatch                                                                        |
+| --- | ------------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| 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) |
+| 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`                |
+
+On ambiguous input, default to **bucket 5 (search)** and surface the top hits. Codify and Toggle
+intents are write paths -- see "Write Power" below.
+
+---
+
+## CLI Surface
+
+All commands run with `pnpm exec elevasis-sdk <cmd>` (or the `om:` alias of the legacy `knowledge:` name).
+
+| Command            | Alias                | Purpose                                                                                                                   |
+| ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `om:search <q>`    | `knowledge:search`   | Universal keyword search across all 6 OM surfaces                                                                         |
+| `om:describe <id>` | `knowledge:describe` | Structured neighborhood view; kind auto-detected from id shape                                                            |
+| `om:cat <id>`      | `knowledge:cat`      | Raw MDX body of a knowledge node                                                                                          |
+| `om:ls <path>`     | `knowledge:ls`       | List nodes by mount path (`/by-system/`, `/by-kind/`, `/by-ontology/`, `/by-owner/`, `/graph/<id>/{governs,governed-by}`) |
+| `om:graph <id>`    | `knowledge:graph`    | Show outgoing + incoming graph edges                                                                                      |
+| `om:skills <id>`   | `knowledge:skills`   | Show callable invocations on graph neighbors                                                                              |
+| `om:generate`      | `knowledge:generate` | Regenerate `_generated/nodes.ts` from MDX sources                                                                         |
+
+Common flags: `--json`, `--ids-only`, `--limit <n>`, `--kinds <list>`.
+
+---
+
+## Read Patterns (Tenant Project)
+
+### Free-text discovery (default for natural-language queries)
+
+```bash
+pnpm exec elevasis-sdk om:search "lead gen"
+pnpm exec elevasis-sdk om:search outreach --kinds knowledge --limit 5
+pnpm exec elevasis-sdk om:search apollo --ids-only
+```
+
+### Neighborhood view for any OM node
+
+```bash
+pnpm exec elevasis-sdk om:describe sales.crm
+pnpm exec elevasis-sdk om:describe knowledge.outreach-playbook
+pnpm exec elevasis-sdk om:describe sales.crm:object/deal
+```
+
+### Read a single knowledge node body
+
+```bash
+pnpm exec elevasis-sdk om:cat knowledge.outreach-playbook
+```
+
+### Mount-path listings
+
+```bash
+pnpm exec elevasis-sdk om:ls /by-system/sales.crm
+pnpm exec elevasis-sdk om:ls /by-kind/playbook --ids-only
+pnpm exec elevasis-sdk om:ls /by-ontology/sales.crm:object/deal --ids-only
+pnpm exec elevasis-sdk om:ls /by-owner/role.ops-lead --ids-only
+pnpm exec elevasis-sdk om:graph knowledge.outreach-playbook
+```
+
+When a query clearly names an ontology id such as `sales.crm:object/deal`, route through
+`/by-ontology/<id>` automatically. When the query names a graph node id such as
+`ontology:sales.crm:object/deal`, strip the `ontology:` graph prefix for the
+`/by-ontology/<id>` path.
+
+### `/om read-folder` (chat shorthand from the Knowledge Browser)
+
+The Knowledge Browser's copy button on a top-level system or kind group emits a single
+`/om read-folder <axis>:<id>` line (or the legacy `/knowledge read-folder ...` form) instead of
+N per-node `read` lines. Resolve it by listing the folder via `om:ls` and reading each child:
+
+| Copy form                       | Resolution                                                                               |
+| ------------------------------- | ---------------------------------------------------------------------------------------- |
+| `/om read-folder system:<id>`   | `pnpm exec elevasis-sdk om:ls /by-system/<id> --ids-only`, then `om:cat` each            |
+| `/om read-folder kind:<kind>`   | `pnpm exec elevasis-sdk om:ls /by-kind/<kind> --ids-only`, then `om:cat` each            |
+| `/om read-folder owner:<id>`    | `pnpm exec elevasis-sdk om:ls /by-owner/<id> --ids-only`, then `om:cat` each             |
+| `/om read-folder ontology:<id>` | `pnpm exec elevasis-sdk om:ls /by-ontology/<id> --ids-only`, then `om:cat` each          |
+| `/om read-folder graph:<id>`    | inspect `/graph/<id>/governs` and `/graph/<id>/governed-by`; read returned knowledge ids |
+
+Dotted system ids may use either dots or slashes (`sales.crm` and `sales/crm` both work).
+Legacy `feature:<id>` copy lines from older browser builds are compatibility aliases for
+`system:<id>`; resolve through `/by-system/`. Per-node leaves still copy as
+`/om read <node-id>` (or `/knowledge read <node-id>`).
+
+`read-folder system:<id>` is the baseline knowledge read, not a mandatory full-system snapshot.
+Start by loading governing knowledge nodes; broaden into adjacent OM context only when the
+current task makes it relevant.
+
+---
+
+## Organization Model Navigation Guide
+
+Use this map whenever the task asks what something is, where it lives, what governs it, or
+what adjacent context may matter:
+
+| Question                           | Start here                                                                                    | Then inspect                                                               |
+| ---------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| What Systems exist?                | `om:ls /by-kind/system` or `core/config/organization-model.ts`                                | System IDs, parentage, lifecycle, UI metadata, and content                 |
+| What governs a System?             | `om:describe <system-id>` or `om:ls /by-system/<id>`                                          | system entry, governed knowledge, roles, policies, graph `governs` edges   |
+| 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 |
+| 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`                            |
+
+Do not treat any one read as a complete system snapshot. The OM is a set of related domain maps;
+follow the relationship that matches the work. Prefer structured helpers from
+`@elevasis/core/organization-model` over ad hoc string scanning when code access is available.
+
+---
+
+## Shared Layering Preview
+
+When opening a domain that uses a closed stage, status, or catalog vocabulary -- especially
+prospecting, CRM, outreach, or another pipeline-like domain -- read the scaffold-shipped primer:
+
+```bash
+node_modules/@elevasis/sdk/reference/spine/spine-primer.md
+```
+
+Use it to emit a short domain layering preview before the normal read, describe, or codify flow:
+
+1. **Catalog:** which `organizationModel.<domain>` catalog owns the keys, labels, descriptions,
+   ordering, and entity ownership.
+2. **Runtime state:** where record progress is stored as sparse state keyed by those catalog
+   members.
+3. **Producers:** which templates, automations, or factories write entity-tagged results for those
+   keys.
+4. **Consumers:** which dashboards, queues, reports, filters, or API reads render or aggregate the
+   same keys.
+
+For vibe-coder sessions, translate this into plain language: "business profile", "saved progress",
+"automations", and "dashboard or reports". For technical sessions, it is acceptable to name the
+catalog, state map, producer, and consumer surfaces directly.
+
+---
+
+## Write Power (Codify + Toggle Ceremony)
+
+This tenant skill owns the full Codify and Toggle write surface. Every write runs the six-step
+safety ceremony preserved verbatim from the legacy `/configure` flow.
+
+### Step 1: Snapshot
+
+Read `core/config/organization-model.ts` into memory before any edit. This is the rollback target.
+
+### Step 2: Propose
+
+Show the diff in chat. Identify which domain and field changes. Present the proposed new value
+in context alongside the current value.
+
+For stage, status, or catalog vocabulary edits, include the shared-layer impact preview before
+asking for confirmation. Name the affected catalog key, whether existing sparse runtime state may
+contain the old key, which producers/templates reference it, and which consumers render or filter
+by it.
+
+### Step 3: Confirm
+
+Pause for explicit user confirmation. Do not proceed without a clear yes. Permission prompts also
+gate writes.
+
+### Step 4: Write
+
+Apply the edit using the Edit or Write tool.
+
+### Step 5: Validate
+
+Run both checks:
+
+```bash
+pnpm -C operations check-types   # TypeScript type-check
+pnpm -C operations check         # Runtime schema validation (Zod parse)
+```
+
+### Step 6: Rollback
+
+If any validation step fails, restore the file from the Step 1 snapshot and report the error.
+The rollback is mandatory -- never leave the project in a broken state.
+
+**Two-level ceremony:**
+
+- **Level A** -- config-only edits to existing schema fields in `core/config/organization-model.ts`.
+  Execute: `.claude/skills/om/operations/codify-level-a.md`
+- **Level B** -- new Zod extension files in `core/config/extensions/`. Gated to explicit user
+  ask. On casual second mentions of a new type, suggest Level B and wait for confirmation rather
+  than scaffolding automatically.
+  Execute: `.claude/skills/om/operations/codify-level-b.md`
+
+---
+
+## Domain References
+
+The following domain reference files document each org-model domain: schema fields, validation
+rules, examples, and how to read or edit them. Load the relevant file when the user's intent
+classification names a specific domain.
+
+- `.claude/skills/om/operations/identity.md` -- identity domain
+- `.claude/skills/om/operations/customers.md` -- customer segments
+- `.claude/skills/om/operations/offerings.md` -- products and services
+- `.claude/skills/om/operations/roles.md` -- role chart
+- `.claude/skills/om/operations/goals.md` -- organizational goals
+- `.claude/skills/om/operations/techStack.md` -- external integration registry
+- `.claude/skills/om/operations/features.md` -- legacy compatibility notes for feature wording
+- `.claude/skills/om/operations/labels.md` -- inline display labels on enum entries
+
+---
+
+## When NOT to Use This Skill
+
+- Pure UI layout (no OM, no org-model entities, no knowledge graph)
+- Workflow authoring or infrastructure work that doesn't reference org-model entities
+- Status checks / ops questions about deployed resources -- those route through `/elevasis`
+- Project/task management -- those route through `/project`
+
+---
+
+## Cross-Links
+
+- `/configure` -- legacy org-model editor (pre-absorption). Absorbed into this skill; all Codify
+  and Toggle intents now route here. `/configure` vocabulary still works as a domain hint
+  (e.g. "configure identity" is parsed as domain=identity, intent=Describe-or-Codify).
+- `node_modules/@elevasis/sdk/reference/spine/spine-primer.md` -- scaffold-shipped layering primer
+  for stage/status/catalog vocabularies that coordinate business-profile entries, runtime progress,
+  producers, and consumers in tenant projects.
+
+---
+
+**Last Updated:** 2026-05-14

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

@@ -1,109 +1,110 @@
-# 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
-
-`core/config/organization-model.ts` under the `customers` key of
-`defineOrganizationModel({...})`.
-
-To read current segments: open the adapter file and inspect the `customers.segments` array, or
-use `pnpm exec elevasis-sdk knowledge:cat customers` (external project).
-
-## Write path
-
-To add, edit, or remove a segment, the `/knowledge` skill runs the codify ceremony
-(`operations/codify-level-a.md`): snapshot → propose → confirm → write → typecheck → Zod parse →
-rollback on failure. Only the `segments` array is written; no other keys in the adapter 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 `/knowledge`** — 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.
+# 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
+
+`core/config/organization-model.ts` under the `customers` key of
+`defineOrganizationModel({...})`.
+
+To read current segments: open the adapter 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. Only the `segments` array is written; no other keys in the adapter 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.