@elevasis/sdk 1.21.0 → 1.22.0

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

@@ -1,235 +1,235 @@
----
-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

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

@@ -17,9 +17,9 @@ Before orienting, scan the user's query for Organization OS terminology. If any
 
 **OS vocabulary triggers:**
 
-- System layer: `system`, `systems`, `SystemModule`, `system key`, `system gate`, `system access`, `gate`, `gating`, `access`, `enable`, `disable`
+- System layer: `system`, `systems`, `SystemModule`, `system key`, `system gate`, `system access`, `gate`, `gating`, `access`, `enable`, `disable`
 - Shell / nav: `manifest`, `shell`, `sub-shell`, `sidebar`, `nav`, `navigation`, `route`
-- Auth / guards: `guard`, `SystemGuard`, `AdminGuard`, `ProtectedRoute`, `admin`
+- Auth / guards: `guard`, `SystemGuard`, `AdminGuard`, `ProtectedRoute`, `admin`
 - Org model: `organization`, `org model`, `organization model`, `domain`, `surface`
 - Foundations: `foundation`, `foundations`, `@core/`, `adapter`
 - Platform ops: `workflow`, `agent`, `deployment`, `resource`
@@ -29,7 +29,7 @@ Before orienting, scan the user's query for Organization OS terminology. If any
 1. Read `.claude/rules/active-change-index.md` immediately. If the target area is flagged as under active refactor, surface the watch-area warning to the user before proceeding — include the "Load:" doc paths listed in that entry so investigation does not rely on stale scaffold prose.
 2. Build the OS context bundle to pass into Step 3:
    - Always: `node_modules/@elevasis/sdk/reference/scaffold/reference/glossary.md`, `.claude/rules/active-change-index.md`, `.claude/rules/agent-start-here.md`
-   - Systems / Shell / Gating queries: add `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` + `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+   - Systems / Shell / Gating queries: add `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` + `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
    - Workflow / Operations queries: add `.claude/rules/operations.md` + glob `operations/src/**`
    - Organization-model queries: add `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` + `core/config/README.md`
 
@@ -37,9 +37,9 @@ Before orienting, scan the user's query for Organization OS terminology. If any
 
 | Query intent                             | Primary OS layers                | Key reference                                                                            |
 | ---------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------- |
-| "Why doesn't my system show up?"         | Systems + UI Shell Runtime       | `glossary.md` (SystemModule, SystemGuard), `feature-flags-and-gating.md`                 |
-| "How do I add a nav item?"               | Systems + Toolkit                | `feature-flags-and-gating.md`, `contracts.md`                                            |
-| "How does admin gating work?"            | Systems + UI Shell Runtime       | `glossary.md` (AdminGuard, requiresAdmin, ProtectedRoute), `feature-flags-and-gating.md` |
+| "Why doesn't my system show up?"         | Systems + UI Shell Runtime       | `glossary.md` (SystemModule, SystemGuard), `feature-flags-and-gating.md`                 |
+| "How do I add a nav item?"               | Systems + Toolkit                | `feature-flags-and-gating.md`, `contracts.md`                                            |
+| "How does admin gating work?"            | Systems + UI Shell Runtime       | `glossary.md` (AdminGuard, requiresAdmin, ProtectedRoute), `feature-flags-and-gating.md` |
 | "What runs when this workflow triggers?" | Platform Public API + Operations | `.claude/rules/operations.md`, `resources.md`                                            |
 | "Why does the foundations adapter fail?" | Foundations                      | `glossary.md` (domain vs surface, settings asymmetry), `core/config/README.md`    |