@elevasis/sdk 1.44.2 → 1.45.0

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

@@ -1,475 +0,0 @@
----
-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,
-    core/config/organization-model/**, 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/organization-model/**"
-    - "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
-      - apiInterface
-      - interface readiness
-      - by-ontology
-      - list my roles
-      - what is our
-      - show me all reference docs
-      - where does
-      - apply
-      - build a system
-      - design a system
-      - create a system that
-      - system architecture
-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/organization-model/**`, `core/config/extensions/**`, or
-  `core/config/knowledge/**`
-
-Auto-invocation is driven by frontmatter `description`, `metadata.pathPatterns`, and
-`metadata.promptSignals` -- no explicit prefix is required.
-
----
-
-## Operations
-
-| Operation | Description                                                                                                              | Execute                                 |
-| --------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
-| `build`   | Codify-ceremony runbook for building a System end to end (shell → ontology → resources → topology → knowledge → verify). | `.claude/skills/om/operations/build.md` |
-
----
-
-## 5-Bucket Decision Tree
-
-If the user expresses intent to **build, design, or architect a system** -- phrased as "build a
-system", "design a system", "create a system that does X", "I want a system for Y", "system
-architecture for Z", or any free-text describing a system they want to construct rather than
-query -- route to `/om build` **before** the buckets below. Read
-`.claude/skills/om/operations/build.md` and follow its ordered phases. This is the primary
-entry; the user does not need to type `/om build` explicitly.
-
-Once invoked for read/write intents (not build), 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/`, `:interface/`, `:link/`, `:endpoint/` | `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 elevasis-sdk <cmd>` from the tenant project root (uses the root script
-alias). Alternatively, use `pnpm -C operations exec elevasis-sdk <cmd>` from the monorepo root.
-Do NOT use `pnpm exec elevasis-sdk <cmd>` at the project root -- `@elevasis/sdk` is a dependency of
-`operations/` only; the binary is not found from the project root without the alias.
-
-| 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; also resolves `item:<domain>:<id>` and bare `<prefix>:<uuid>` domain-item forms                                                                     |
-| `om:cat <id>`      | `knowledge:cat`      | Raw MDX body of a knowledge node                                                                                                                                                                                    |
-| `om:ls <path>`     | `knowledge:ls`       | List by mount path. Enumeration: `/all-systems`, `/all-resources`, `/all-roles`. Scoped: `/by-system/`, `/by-kind/`, `/by-ontology/`, `/by-owner/`, `/by-domain/`, `/by-item/`, `/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 elevasis-sdk om:search "lead gen"
-pnpm elevasis-sdk om:search outreach --kinds knowledge --limit 5
-pnpm elevasis-sdk om:search apollo --ids-only
-```
-
-### Neighborhood view for any OM node
-
-```bash
-pnpm elevasis-sdk om:describe sales.crm
-pnpm elevasis-sdk om:describe knowledge.outreach-playbook
-pnpm elevasis-sdk om:describe sales.crm:object/deal
-```
-
-### Domain-item profile (clients, roles, policies, customers, offerings, goals)
-
-Use `om:describe item:<domain>:<id>` to read a rich domain-item profile -- identity, branding,
-location, and governing knowledge. The bare `<prefix>:<uuid>` form (e.g. `client:<uuid>`) is
-accepted as a back-compat alias and resolves identically.
-
-```bash
-pnpm elevasis-sdk om:describe item:clients:<uuid>     # full ClientProfile + location + governing knowledge
-pnpm elevasis-sdk om:describe item:roles:<id>
-pnpm elevasis-sdk om:describe item:policies:<id>
-pnpm elevasis-sdk om:describe item:customers:<id>
-pnpm elevasis-sdk om:describe item:offerings:<id>
-pnpm elevasis-sdk om:describe item:goals:<id>
-```
-
-Do not confuse this with `client:get <uuid>` (the portfolio/DB surface for status, lineage, and
-deals). `om:describe item:clients:<uuid>` returns the org-model `ClientProfile`; `client:get`
-returns a sparse DB record. They share the same `id` and can be cross-linked by it.
-
-### Read a single knowledge node body
-
-```bash
-pnpm elevasis-sdk om:cat knowledge.outreach-playbook
-```
-
-### Top-level enumeration (drill-down entry point)
-
-Start here when an agent needs to discover what this tenant's custom OM contains before
-building on it -- list everything in a domain, then narrow with `om:describe` / `om:cat`:
-
-```bash
-pnpm elevasis-sdk om:ls /all-systems              # every System (path + label)
-pnpm elevasis-sdk om:ls /all-resources            # every resource (id, kind, title)
-pnpm elevasis-sdk om:ls /all-roles                # every role (id, title)
-pnpm elevasis-sdk om:ls /all-systems --ids-only   # pipe paths into om:describe
-```
-
-These resolve against this tenant's resolved model -- they enumerate the project's own custom
-OM, not the platform's. Use `--json` for the wrapped envelope or `--ids-only` for piping.
-
-### Scoped mount-path listings
-
-```bash
-pnpm elevasis-sdk om:ls /by-system/sales.crm
-pnpm elevasis-sdk om:ls /by-kind/playbook --ids-only
-pnpm elevasis-sdk om:ls /by-ontology/sales.crm:object/deal --ids-only
-pnpm elevasis-sdk om:ls /by-owner/role.ops-lead --ids-only
-pnpm elevasis-sdk om:ls /by-domain/clients                    # enumerate all client domain items
-pnpm elevasis-sdk om:ls /by-item/clients/<uuid>               # single item record (same as om:describe item:clients:<uuid>)
-pnpm 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, kind group, or domain-item node
-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 the table below:
-
-| Copy form                            | Resolution                                                                                                                 |
-| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
-| `/om read-folder system:<id>`        | `pnpm elevasis-sdk om:ls /by-system/<id> --ids-only`, then `om:cat` each                                                   |
-| `/om read-folder kind:<kind>`        | `pnpm elevasis-sdk om:ls /by-kind/<kind> --ids-only`, then `om:cat` each                                                   |
-| `/om read-folder owner:<id>`         | `pnpm elevasis-sdk om:ls /by-owner/<id> --ids-only`, then `om:cat` each                                                    |
-| `/om read-folder ontology:<id>`      | `pnpm elevasis-sdk om:ls /by-ontology/<id> --ids-only`, then `om:cat` each                                                 |
-| `/om read-folder item:<domain>:<id>` | `pnpm elevasis-sdk om:describe item:<domain>:<id>` -- returns profile + location + governing knowledge                     |
-| `/om read-folder graph:<id>`         | inspect `/graph/<id>/governs` and `/graph/<id>/governed-by`; read returned knowledge ids                                   |
-| `/om read-folder group:<id>`         | browser overview reference only; resolve by visible children -- `pnpm elevasis-sdk om:ls /by-system/<id> --ids-only`       |
-| `/om read-folder domain:<domain>`    | browser overview reference only; resolve by enumerating domain -- `pnpm elevasis-sdk om:ls /by-domain/<domain> --ids-only` |
-| `/om read-folder folder:<id>`        | browser overview reference only; treat as `domain:<id>` and enumerate with `/by-domain/<id>`                               |
-
-**Legacy bridge -- `graph:client:<uuid>` and other `graph:<prefix>:<uuid>` domain-item forms:**
-Older Knowledge Browser builds emitted `graph:client:<uuid>` for client items. This is a
-graph-neighborhood shorthand, not a profile read. When you receive such a reference:
-
-1. Resolve the graph neighborhood: `pnpm elevasis-sdk om:graph client:<uuid>` (may return empty or only `contains` edges -- that is expected; no `ClientProfile` is accessible this way).
-2. For the rich profile, pivot to: `pnpm elevasis-sdk om:describe item:clients:<uuid>`.
-
-In short: `graph:client:<uuid>` points to the graph node; `item:clients:<uuid>` resolves the
-full org-model profile. Always use `item:` for profile reads going forward.
-
-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 /all-systems`                                                                                                                         | System IDs, parentage, lifecycle, UI metadata, and content                                                                           |
-| What resources exist?              | `om:ls /all-resources`                                                                                                                       | resource ids, kinds, owning System refs                                                                                              |
-| What roles exist?                  | `om:ls /all-roles`                                                                                                                           | role ids, titles, responsibilities                                                                                                   |
-| 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                                                           |
-| Is a platform API interface ready? | the System's `apiInterface` marker and `operations/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`                                                                                      |
-
-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.
-
----
-
-## System Taxonomy and Resource Placement
-
-Use Systems for durable organizational capability boundaries, not implementation categories.
-
-A System is appropriate only when it owns at least one of:
-
-- Business or platform capability semantics
-- System-local ontology/config
-- Accountable roles or governance
-- Resources that operate that capability
-- Knowledge or policies that govern that capability
-
-Do not create Systems for:
-
-- Resource kinds such as `workflows`, `agents`, `scripts`, or `triggers`
-- Shell or navigation groups such as `operations`, `monitoring`, `settings`, or `knowledge`
-- Catch-all buckets such as `automation`, `misc`, `runtime`, or `tools`
-- Individual UI pages or logs such as `command queue`, `task scheduler`, or `execution logs`
-- One-off implementations that should be Resources
-
-Resources still require `systemPath`. Choose the System by the capability the Resource supports,
-not by its implementation type.
-
-Placement examples:
-
-- Scaffold/runtime smoke test `echo` -> `platform.diagnostics`
-- Shared notification workflow -> `platform.notifications`
-- Lead-gen workflow -> `sales.lead-gen`
-- CRM or deal workflow -> `sales.crm`
-- Project status workflow -> `projects`
-- External integration credential/sync resource -> the business or platform System it serves, not
-  `integrations` unless an actual integration-platform subsystem exists
-
-Before adding a System:
-
-1. Run `pnpm elevasis-sdk om:ls /all-systems`.
-2. Run `pnpm elevasis-sdk om:describe <candidate-parent-or-owner>`.
-3. If the proposed System name is a resource kind, shell group, or catch-all, do not create it;
-   attach or create a Resource under the real owning System.
-4. Create a new System only when no existing System owns the capability and the new System has
-   durable ontology/config/governance meaning.
-
-Current template placement convention:
-
-- Platform cross-cutting subsystems live under `platform.*`.
-- `platform.diagnostics` owns scaffold diagnostic resources.
-- `platform.notifications` owns notification delivery.
-- Tenant business workflows belong to the business System they operate, such as `sales.lead-gen`
-  or `projects`.
-
----
-
-## 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 `operations/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
-prospecting, CRM, outreach, or another pipeline-like domain -- read the scaffold-shipped primer:
-
-```bash
-operations/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 workflow resources, templates, 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",
-"workflow resources", 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
-
-Determine the target file for the domain being edited (see the domain reference file for
-"Where it lives" guidance). Read that file into memory before any edit. This is the rollback
-target. For unsplit projects the target is `core/config/organization-model.ts`; for split projects
-use the appropriate sub-file (`profile.ts`, `systems.ts`, or `navigation.ts` under
-`core/config/organization-model/`).
-
-### 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 a single config file under
-  `core/config/` (the entry `organization-model.ts` for unsplit projects, or the appropriate
-  sub-file for split projects — see the domain reference for the correct target).
-  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).
-- `operations/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-06-06