@elevasis/sdk 1.31.0 → 1.33.0

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

@@ -1,235 +1,244 @@
----
-name: elevasis
-description: Elevasis platform operations -- check, deploy, execute, inspect, and debug SDK resources
----
-
-# Elevasis Platform Operations
-
-Manage SDK resources in the `operations/` workspace via the `elevasis-sdk` CLI.
-
-**Usage:**
-
-- `/elevasis` -- Show available operations
-- `/elevasis check` -- Validate resource definitions
-- `/elevasis deploy [--prod]` -- Deploy resources
-- `/elevasis exec <resourceId> [--input '...']` -- Execute a resource
-- `/elevasis describe <resourceId>` -- Show resource schema
-- `/elevasis logs <resourceId>` -- View recent executions
-- `/elevasis creds` -- Manage credentials
-
-## Critical Rules
-
-- **Always describe before exec** -- run `describe` first to see the exact input schema
-- **Use `-f` for complex inputs** -- write JSON to a temp file to avoid shell escaping issues
-- **Always `check` before `deploy`** -- catches schema and config errors early
-
-## Environment
-
-The CLI authenticates via `ELEVASIS_PLATFORM_KEY` in the root `.env` file. The CLI walks up directories to find `.env`, so it works from both the project root and `operations/`.
-
-For dev vs prod targeting:
-
-- Default: production (`https://api.elevasis.io`)
-- `--prod` flag: explicitly targets production (overrides `NODE_ENV=development`)
-- `ELEVASIS_API_URL` env var: override to any custom URL
-
-## Operations
-
-### Check
-
-Validate all resource definitions (schemas, contracts, config):
-
-```bash
-pnpm elevasis-sdk check
-```
-
-Reports: resource count, validation errors, schema serialization warnings. Exit code 0 = pass.
-
-### Deploy
-
-Bundle and deploy resources to the Elevasis platform.
-
-```bash
-pnpm elevasis-sdk deploy [--prod]
-```
-
-Replace `[--prod]` with `--prod` when targeting production.
-
-**Version bumping flags** (written back to `src/index.ts`):
-
-- `--major` -- bump major (1.0.0 to 2.0.0) for breaking contract changes
-- `--minor` -- bump minor (1.0.0 to 1.1.0) for new features
-- `--patch` -- bump patch (1.0.0 to 1.0.1) for fixes
-
-Deploy replaces the previous active deployment. Resources become executable immediately.
-
-### Describe
-
-**Always run before executing.** Shows resource metadata, input/output schemas, and step chain:
-
-```bash
-pnpm elevasis-sdk describe <resourceId>
-
-# JSON output for programmatic use
-pnpm elevasis-sdk describe <resourceId> --json
-```
-
-Output includes: type, name, version, status, domains, input schema (required/optional fields with types), output schema, step definitions with entry point and routing.
-
-### Execute
-
-Run a deployed resource. **Always `describe` first to see the input schema.**
-
-```bash
-# Simple input (inline JSON)
-pnpm elevasis-sdk exec <resourceId> -i '{"key": "value"}'
-
-# Complex input (temp file -- PREFERRED for non-trivial payloads)
-# Write input to a temp file first, then reference it with -f
-pnpm elevasis-sdk exec <resourceId> -f .tmp-input.json
-
-# Async execution (for long-running workflows -- polls until complete)
-pnpm elevasis-sdk exec <resourceId> -f .tmp-input.json --async
-```
-
-**When to use `-f` (file input):**
-
-- Input contains nested objects, arrays, or special characters
-- Input has quotes that conflict with shell escaping
-- Input is reused across multiple executions
-- Any time inline `-i` causes parsing errors
-
-**Temp file pattern:**
-
-1. Write the JSON to a temp file inside the project (e.g., `operations/.tmp-input.json`)
-2. Execute with `-f .tmp-input.json`
-3. Delete the temp file after
-
-**Sync vs async:**
-
-- Sync (default): blocks until execution completes, shows result inline
-- Async (`--async`): returns execution ID immediately, polls every 3s with elapsed timer
-- Use `--async` for workflows that may exceed 30 seconds
-
-**Connection failure recovery:** If the connection drops during sync execution, the CLI automatically searches recent executions for a running one and resumes polling.
-
-### List Resources
-
-View all deployed resources:
-
-```bash
-pnpm elevasis-sdk resources
-
-# JSON output
-pnpm elevasis-sdk resources --json
-```
-
-Shows: resource ID, type (workflow/agent), name, description, status.
-
-### Execution History
-
-View past executions for a resource:
-
-```bash
-# List recent executions (default: last 50)
-pnpm elevasis-sdk executions <resourceId>
-
-# Filter by status
-pnpm elevasis-sdk executions <resourceId> --status failed --limit 10
-
-# View specific execution (full detail with logs)
-pnpm elevasis-sdk execution <resourceId> <executionId>
-
-# Logs only (skip metadata)
-pnpm elevasis-sdk execution <resourceId> <executionId> --logs-only
-
-# Include input and result data
-pnpm elevasis-sdk execution <resourceId> <executionId> --input --result
-```
-
-**`executions` flags:** `--limit <n>` (default 50), `--status running|completed|failed`, `--json`
-
-**`execution` flags:** `--logs-only`, `--input`, `--result`, `--json`
-
-Execution detail shows: status, start/end times, duration, input, result, error (if failed), and timestamped logs with level (ERROR/WARN/INFO/DEBUG).
-
-### Deployments
-
-View deployment history:
-
-```bash
-pnpm elevasis-sdk deployments
-```
-
-Shows: deployment ID, SDK version, status (active/deploying/failed/stopped), created timestamp.
-
-### Credentials
-
-Manage integration credentials (API keys, webhook secrets):
-
-```bash
-# List credentials (metadata only, secrets not exposed)
-pnpm elevasis-sdk creds list
-
-# Create a credential
-pnpm elevasis-sdk creds create --name my-api-key --type api-key --value '{"apiKey":"sk-..."}'
-
-# Update a credential value
-pnpm elevasis-sdk creds update my-api-key --value '{"apiKey":"new-key"}'
-
-# Rename a credential
-pnpm elevasis-sdk creds rename old-name --to new-name
-
-# Delete a credential
-pnpm elevasis-sdk creds delete my-api-key --force
-```
-
-Credential names: lowercase, digits, hyphens only (`^[a-z0-9]+(-[a-z0-9]+)*$`). Types: `api-key`, `webhook-secret`.
-
-### Rename Resource
-
-Rename a resource ID across all platform tables:
-
-```bash
-# Dry run (preview only)
-pnpm elevasis-sdk rename old-id --to new-id
-
-# Apply rename
-pnpm elevasis-sdk rename old-id --to new-id --execute
-```
-
-Always dry-run first to see affected tables and row counts.
-
-### Error Resolution
-
-Mark execution errors as resolved:
-
-```bash
-# Resolve a specific error
-pnpm elevasis-sdk error resolve <errorId>
-
-# Resolve all errors for an execution
-pnpm elevasis-sdk error resolve-execution <executionId>
-```
-
-## Standard Workflow
-
-```
-1. Write/modify resources     operations/src/
-2. Type-check                 pnpm -C operations run check-types
-3. Validate                   /elevasis check
-4. Deploy                     /elevasis deploy --prod
-5. Describe                   /elevasis describe <id>
-6. Execute                    /elevasis exec <id> -f input.json
-7. Inspect logs               /elevasis logs <id>
-```
-
-## Debugging Checklist
-
-When an execution fails:
-
-1. **Get the execution ID** from the exec output or `executions <resourceId> --status failed`
-2. **Read the logs**: `execution <resourceId> <executionId> --logs-only`
-3. **Check the input**: `execution <resourceId> <executionId> --input`
-4. **Check the error**: `execution <resourceId> <executionId> --result`
-5. **Fix the handler**, redeploy, re-execute
+---
+name: elevasis
+description: Elevasis platform operations -- check, deploy, execute, inspect, and debug SDK resources
+---
+
+# Elevasis Platform Operations
+
+Manage SDK resources in the `operations/` workspace via the `elevasis-sdk` CLI.
+
+**Usage:**
+
+- `/elevasis` -- Show available operations
+- `/elevasis check` -- Validate resource definitions
+- `/elevasis deploy [--prod]` -- Deploy resources
+- `/elevasis exec <resourceId> [--input '...']` -- Execute a resource
+- `/elevasis describe <resourceId>` -- Show resource schema
+- `/elevasis logs <resourceId>` -- View recent executions
+- `/elevasis creds` -- Manage credentials
+
+## Critical Rules
+
+- **Always describe before exec** -- run `describe` first to see the exact input schema
+- **Use `-f` for complex inputs** -- write JSON to a temp file to avoid shell escaping issues
+- **Always `check` before `deploy`** -- catches schema and config errors early
+
+## Environment
+
+The CLI authenticates via `ELEVASIS_PLATFORM_KEY` in the root `.env` file. The CLI walks up directories to find `.env`, so it works from both the project root and `operations/`.
+
+For dev vs prod targeting:
+
+- Default: production (`https://api.elevasis.io`)
+- `--prod` flag: explicitly targets production (overrides `NODE_ENV=development`)
+- `ELEVASIS_API_URL` env var: override to any custom URL
+
+## Operations
+
+### Check
+
+Validate all resource definitions (schemas, contracts, config):
+
+```bash
+pnpm elevasis-sdk check
+```
+
+Reports: resource count, validation errors, schema serialization warnings. Exit code 0 = pass.
+
+### Deploy
+
+Bundle and deploy resources to the Elevasis platform.
+
+```bash
+pnpm elevasis-sdk deploy [--prod]
+```
+
+Replace `[--prod]` with `--prod` when targeting production.
+
+**Version bumping flags** (written back to `src/index.ts`):
+
+- `--major` -- bump major (1.0.0 to 2.0.0) for breaking contract changes
+- `--minor` -- bump minor (1.0.0 to 1.1.0) for new features
+- `--patch` -- bump patch (1.0.0 to 1.0.1) for fixes
+
+Deploy replaces the previous active deployment. Resources become executable immediately.
+
+### Describe
+
+**Always run before executing.** Shows resource metadata, input/output schemas, and step chain:
+
+```bash
+pnpm elevasis-sdk describe <resourceId>
+
+# JSON output for programmatic use
+pnpm elevasis-sdk describe <resourceId> --json
+```
+
+Output includes: type, name, version, status, domains, input schema (required/optional fields with types), output schema, step definitions with entry point and routing.
+
+### Execute
+
+Run a deployed resource. **Always `describe` first to see the input schema.**
+
+```bash
+# Simple input (inline JSON)
+pnpm elevasis-sdk exec <resourceId> -i '{"key": "value"}'
+
+# Complex input (temp file -- PREFERRED for non-trivial payloads)
+# Write input to a temp file first, then reference it with -f
+pnpm elevasis-sdk exec <resourceId> -f .tmp-input.json
+
+# Async execution (for long-running workflows -- polls until complete)
+pnpm elevasis-sdk exec <resourceId> -f .tmp-input.json --async
+```
+
+**When to use `-f` (file input):**
+
+- Input contains nested objects, arrays, or special characters
+- Input has quotes that conflict with shell escaping
+- Input is reused across multiple executions
+- Any time inline `-i` causes parsing errors
+
+**Temp file pattern:**
+
+1. Write the JSON to a temp file inside the project (e.g., `operations/.tmp-input.json`)
+2. Execute with `-f .tmp-input.json`
+3. Delete the temp file after
+
+**Sync vs async:**
+
+- Sync (default): blocks until execution completes, shows result inline
+- Async (`--async`): returns execution ID immediately, polls every 3s with elapsed timer
+- Use `--async` for workflows that may exceed 30 seconds
+
+**Connection failure recovery:** If the connection drops during sync execution, the CLI automatically searches recent executions for a running one and resumes polling.
+
+### List Resources
+
+View all deployed resources:
+
+```bash
+pnpm elevasis-sdk resources
+
+# JSON output
+pnpm elevasis-sdk resources --json
+```
+
+Shows: resource ID, type (workflow/agent), name, description, status.
+
+### Execution History
+
+View past executions for a resource:
+
+```bash
+# List recent executions (default: last 50)
+pnpm elevasis-sdk executions <resourceId>
+
+# Filter by status
+pnpm elevasis-sdk executions <resourceId> --status failed --limit 10
+
+# View specific execution (full detail with logs)
+pnpm elevasis-sdk execution <resourceId> <executionId>
+
+# Logs only (skip metadata)
+pnpm elevasis-sdk execution <resourceId> <executionId> --logs-only
+
+# Include input and result data
+pnpm elevasis-sdk execution <resourceId> <executionId> --input --result
+```
+
+**`executions` flags:** `--limit <n>` (default 50), `--status running|completed|failed`, `--json`
+
+**`execution` flags:** `--logs-only`, `--input`, `--result`, `--json`
+
+Execution detail shows: status, start/end times, duration, input, result, error (if failed), and timestamped logs with level (ERROR/WARN/INFO/DEBUG).
+
+### Deployments
+
+View deployment history:
+
+```bash
+pnpm elevasis-sdk deployments
+```
+
+Shows: deployment ID, SDK version, status (active/deploying/failed/stopped), created timestamp.
+
+### Credentials
+
+Manage integration credentials (API keys, webhook secrets):
+
+```bash
+# List credentials (metadata only, secrets not exposed)
+pnpm elevasis-sdk creds list
+
+# Create a credential
+pnpm elevasis-sdk creds create --name my-api-key --type api-key --value '{"apiKey":"sk-..."}'
+
+# Update a credential value
+pnpm elevasis-sdk creds update my-api-key --value '{"apiKey":"new-key"}'
+
+# Rename a credential
+pnpm elevasis-sdk creds rename old-name --to new-name
+
+# Delete a credential
+pnpm elevasis-sdk creds delete my-api-key --force
+```
+
+Credential names: lowercase, digits, hyphens only (`^[a-z0-9]+(-[a-z0-9]+)*$`). Types: `api-key`, `webhook-secret`.
+
+### Rename Resource
+
+Rename a resource ID across all platform tables:
+
+```bash
+# Dry run (preview only)
+pnpm elevasis-sdk rename old-id --to new-id
+
+# Apply rename
+pnpm elevasis-sdk rename old-id --to new-id --execute
+```
+
+Always dry-run first to see affected tables and row counts.
+
+### Error Resolution
+
+Mark execution errors as resolved:
+
+```bash
+# Resolve a specific error
+pnpm elevasis-sdk error resolve <errorId>
+
+# Resolve all errors for an execution
+pnpm elevasis-sdk error resolve-execution <executionId>
+```
+
+## Standard Workflow
+
+```
+1. Write/modify resources     operations/src/
+2. Type-check                 pnpm -C operations run check-types
+3. Validate                   /elevasis check
+4. Deploy                     /elevasis deploy --prod
+5. Describe                   /elevasis describe <id>
+6. Execute                    /elevasis exec <id> -f input.json
+7. Inspect logs               /elevasis logs <id>
+```
+
+## Debugging Checklist
+
+When an execution fails:
+
+1. **Get the execution ID** from the exec output or `executions <resourceId> --status failed`
+2. **Read the logs**: `execution <resourceId> <executionId> --logs-only`
+3. **Check the input**: `execution <resourceId> <executionId> --input`
+4. **Check the error**: `execution <resourceId> <executionId> --result`
+5. **Fix the handler**, redeploy, re-execute
+
+---
+
+## Capability Surface
+
+When a user asks what skills or commands are available, do NOT answer from recollection.
+
+- **Skill inventory:** Read `.claude/Overview.md` — it is the authoritative list of skills available in this project.
+- **Live CLI capability:** Run `pnpm elevasis-sdk cli` — it outputs every command and domain currently registered in the SDK, grouped by domain.

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

@@ -55,7 +55,6 @@ metadata:
       - show me all reference docs
       - where does
       - apply
-context: fork
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 ---
 
@@ -227,6 +226,58 @@ follow the relationship that matches the work. Prefer structured helpers from
 
 ---
 
+## 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 exec elevasis-sdk om:ls /all-systems`.
+2. Run `pnpm exec 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.
@@ -256,14 +307,14 @@ Use it to emit a short domain layering preview before the normal read, describe,
    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.
+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",
-"automations", and "dashboard or reports". For technical sessions, it is acceptable to name the
-catalog, state map, producer, and consumer surfaces directly.
+"workflow resources", and "dashboard or reports". For technical sessions, it is acceptable to name
+the catalog, state map, producer, and consumer surfaces directly.
 
 ---
 

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

@@ -1,10 +1,12 @@
 # Features Compatibility Notes
 
 `features` is legacy organization-model wording. Current Organization OS vocabulary is
-System/Action oriented:
+System/Resource/Action oriented:
 
-- **Systems** describe availability, routing, ownership, navigation grouping, and knowledge
-  mounts.
+- **Systems** describe durable capability ownership, ontology/config, accountability, governance,
+  and knowledge mounts. They are not sidebar groups.
+- **Resources** describe executable artifacts such as workflows, agents, scripts, and triggers;
+  each Resource attaches to a real System through `systemPath`.
 - **Actions** describe invokable operations such as workflows, agents, commands, and UI-triggered
   tasks.
 
@@ -12,13 +14,17 @@ Use this file only when older prompts, browser copy text, SDK references, or sca
 say "feature". For current tenant organization-model work, route the user to Systems and Actions
 wording and use `/by-system/<id>` knowledge paths.
 
+Do not translate "feature" into a catch-all System. Route to Systems only when the user means a
+durable capability boundary; route workflow, agent, script, trigger, or implementation asks to
+Resources under the System that owns the actual business or platform capability.
+
 ## Compatibility Mapping
 
 | Legacy wording                                                                        | Current wording                                 |
 | ------------------------------------------------------------------------------------- | ----------------------------------------------- |
 | Feature toggle                                                                        | System availability or routing toggle           |
 | Feature ID                                                                            | System ID when discussing Organization OS       |
-| Add a custom feature                                                                  | Add or extend a System, then define any Actions |
+| Add a custom feature                                                                  | Add or extend a capability System, then define Resources and Actions it owns |
 | Feature governs X                                                                     | System governs X                                |
 | `/om read-folder feature:x` (legacy `/knowledge read-folder feature:x` also accepted) | `/om read-folder system:x`                      |
 | `/by-feature/x`                                                                       | `/by-system/x`                                  |
@@ -50,7 +56,8 @@ means adding a project-owned extension under `core/config/extensions/` and wirin
 organization model.
 
 Older references may call this "adding a custom feature"; translate it to "add or extend a
-System and define any Actions it owns" before invoking `operations/codify-level-b.md`.
+capability System and define the Resources and Actions it owns" before invoking
+`operations/codify-level-b.md`.
 
 ## UI Package Exception
 

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

@@ -61,6 +61,16 @@ Before scaffolding, run a single `om:describe` against the parent System (for Re
 pnpm exec elevasis-sdk om:describe sales.crm
 ```
 
+### Resource placement decision
+
+For `om:scaffold:resource`, never choose `systemPath` because the new Resource is a workflow,
+agent, script, or trigger. Those are Resource kinds, not Systems. Pick the existing System that
+owns the business or platform capability the Resource operates.
+
+If no existing System owns that capability, first propose a real capability System. Do not create
+`automation`, `workflows`, `operations`, `monitoring`, `settings`, or similarly broad bucket
+Systems to make the Resource fit.
+
 ### Step 2: Dry-run
 
 Always preview first. Each command prints the exact TypeScript / MDX block it would write.

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

@@ -273,3 +273,12 @@ Running `/setup` more than once is safe:
 5. Hands off to `/om` for full org-model configuration
 
 `/om` owns all other structural org-model editing (identity fields beyond clientBrief, customers, offerings, roles, goals, techStack, systems, actions, labels, and legacy feature compatibility). It is idempotent, confirm-before-overwrite, and includes a runtime validation gate. Re-run `/om` any time organizational reality changes — no need to re-run `/setup`.
+
+---
+
+## Capability Surface
+
+When a user asks what skills or commands are available, do NOT answer from recollection.
+
+- **Skill inventory:** Read `.claude/Overview.md` — it is the authoritative list of skills available in this project.
+- **Live CLI capability:** Run `pnpm elevasis-sdk cli` — it outputs every command and domain currently registered in the SDK, grouped by domain.