@elevasis/sdk 1.37.0 → 1.38.0

package/reference/claude-config/rules/ui.md

@@ -6,6 +6,17 @@ description: Compatibility pointer for the canonical Ui rule bundled with @eleva
 
 Canonical rule source:
 
-`node_modules/@elevasis/sdk/reference/rules/ui.md`
+`operations/node_modules/@elevasis/sdk/reference/rules/ui.md`
 
-Read that bundled rule before applying this rule. This local file is intentionally kept as a thin compatibility pointer for existing local rule references in skills, sync notes, and older prompts.
+When working in the monorepo template snapshot before dependencies are installed,
+use the repo-local generated fallback:
+
+`packages/sdk/reference/rules/ui.md`
+
+If the generated fallback is stale or missing, use the source:
+
+`packages/sdk/docs/agent-rules/ui.md`
+
+Read the bundled rule first when available. This local file is intentionally kept
+as a thin compatibility pointer for existing local rule references in skills,
+sync notes, and older prompts.

package/reference/claude-config/rules/vibe.md

@@ -6,6 +6,17 @@ description: Compatibility pointer for the canonical Vibe rule bundled with @ele
 
 Canonical rule source:
 
-`node_modules/@elevasis/sdk/reference/rules/vibe.md`
+`operations/node_modules/@elevasis/sdk/reference/rules/vibe.md`
 
-Read that bundled rule before applying this rule. This local file is intentionally kept as a thin compatibility pointer for existing local rule references in skills, sync notes, and older prompts.
+When working in the monorepo template snapshot before dependencies are installed,
+use the repo-local generated fallback:
+
+`packages/sdk/reference/rules/vibe.md`
+
+If the generated fallback is stale or missing, use the source:
+
+`packages/sdk/docs/agent-rules/vibe.md`
+
+Read the bundled rule first when available. This local file is intentionally kept
+as a thin compatibility pointer for existing local rule references in skills,
+sync notes, and older prompts.

package/reference/claude-config/settings.json

@@ -1,34 +1,30 @@
-{
-  "statusLine": {
-    "type": "command",
-    "command": "node .claude/scripts/statusline-command.js"
-  },
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Write|Edit|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node .claude/hooks/post-edit-validate.mjs"
-          },
-          {
-            "type": "command",
-            "command": "node .claude/hooks/scaffold-registry-reminder.mjs"
-          }
-        ]
-      }
-    ],
-    "PostToolUseFailure": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node .claude/hooks/tool-failure-recovery.mjs"
-          }
-        ]
-      }
-    ]
-  }
-}
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node .claude/scripts/statusline-command.js"
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/post-edit-validate.mjs"
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/tool-failure-recovery.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -1,156 +1,159 @@
----
-name: deploy
-description: Test, build, fix issues, then commit and push
----
-
-# Deploy
-
-Test, build, fix issues, then commit and push.
-
-**Usage:** `/deploy [--skip] [--minor | --major] [commit message]`
-
-## Flags
-
-- `--skip` -- Skip tests, type checking, and build (Steps 2-4). Go straight from pre-flight to commit and push.
-- `--minor` -- Bump the minor version instead of patch (e.g. 1.0.0 -> 1.1.0).
-- `--major` -- Bump the major version instead of patch (e.g. 1.0.0 -> 2.0.0).
-
-## Process
-
-### Step 1: Pre-flight Check
-
-Run in parallel:
-
-```bash
-git status
-git diff --stat
-```
-
-If there are no changes, report "Nothing to deploy" and stop.
-
-### Step 1b: Version Bump
-
-Read the current version from `package.json`, then bump it:
-
-- Default: bump **patch** (e.g. 1.0.0 -> 1.0.1)
-- `--minor`: bump **minor** (e.g. 1.0.0 -> 1.1.0)
-- `--major`: bump **major** (e.g. 1.0.0 -> 2.0.0)
-
-Use the Edit tool to update the `"version"` field in `package.json` directly. Do not use `npm version` or any CLI command.
-
-### Step 2: Run Tests
-
-```bash
-pnpm test
-```
-
-If tests fail:
-
-1. Read the failing test output
-2. Attempt to fix the issue
-3. Re-run tests
-4. If still failing after 2 attempts, stop and report the failures
-
-### Step 3: Type Check
-
-```bash
-pnpm lint
-```
-
-If type errors exist:
-
-1. Read the errors
-2. Attempt to fix
-3. Re-run
-4. If still failing after 2 attempts, stop and report
-
-### Step 4: Build
-
-```bash
-pnpm build
-```
-
-If build fails:
-
-1. Read the error output
-2. Attempt to fix
-3. Re-run
-4. If still failing after 2 attempts, stop and report
-
-### Step 5: Commit
-
-1. Stage all changed files: `git add -A`
-2. Create commit with the provided message (or auto-generate from changes)
-3. Format: conventional commits (feat:, fix:, chore:, docs:, etc.)
-
-```bash
-git add -A
-git commit -m "<message>"
-```
-
-### Step 6: Push
-
-```bash
-git push
-```
-
-If push fails (e.g., remote has new commits):
-
-1. `git pull --rebase`
-2. Re-run tests to verify no conflicts broke anything
-3. `git push`
-
-### Step 7: Report
-
-```
-Deploy Complete
-===============
-Version: <old> -> <new>
-Tests:   passed
-Types:   clean
-Build:   success
-Commit:  <hash> - <message>
-Push:    pushed to <branch>
-```
-
-### Step 8: Project Task Status Transition
-
-After a successful push, mark any linked project task as `submitted`. This is a best-effort fanout -- it must never fail the deploy.
-
-1. **Resolve the task ID.** Look for a `prj_tasks` UUID tied to the current work, in this order:
-   - A task UUID explicitly captured in the current conversation (e.g. from a previous `/save`, `/project work`, or `project:task:*` invocation).
-   - The most recent in-progress task on the most-recently-touched project, via:
-
-     ```bash
-     pnpm elevasis-sdk project:list --status active --pretty
-     pnpm elevasis-sdk project:list --status blocked --pretty
-     pnpm elevasis-sdk project:task:list --project <project-id> --status in_progress --pretty
-     ```
-
-   - If the session produced an ambiguous or empty result, PROMPT the user once: "Mark a project task as submitted? (task UUID, or 'skip')". Default is skip.
-
-2. **Fire the transition** (only when a single confident task ID is resolved):
-
-   ```bash
-   pnpm elevasis-sdk project:task:update <task-id> --status submitted
-   ```
-
-3. **Failure handling.** If the CLI call errors, no task ID can be resolved, or the user declines, emit a single warning line and continue:
-
-   ```
-   Warning: skipped project:task status transition (<reason>). Deploy itself succeeded.
-   ```
-
-   Never retry, never block the deploy report, never exit non-zero on this step.
-
-## Error Recovery
-
-If any step fails and cannot be auto-fixed:
-
-```
-Deploy Failed at Step N: [step name]
-=====================================
-Error: [description]
-Attempted fixes: [what was tried]
-Manual action needed: [what the user should do]
-```
+---
+name: deploy
+description: Test, build, fix issues, then commit and push
+---
+
+# Deploy
+
+Test, build, fix issues, then commit and push.
+
+**Usage:** `/deploy [--skip] [--minor | --major] [commit message]`
+
+## Flags
+
+- `--skip` -- Skip tests, type checking, and build (Steps 2-4). Go straight from pre-flight to commit and push.
+- `--minor` -- Bump the minor version instead of patch (e.g. 1.0.0 -> 1.1.0).
+- `--major` -- Bump the major version instead of patch (e.g. 1.0.0 -> 2.0.0).
+
+## Process
+
+### Step 1: Pre-flight Check
+
+Run in parallel:
+
+```bash
+git status
+git diff --stat
+```
+
+If there are no changes, report "Nothing to deploy" and stop.
+
+### Step 1b: Version Bump
+
+Read the current version from `package.json`, then bump it:
+
+- Default: bump **patch** (e.g. 1.0.0 -> 1.0.1)
+- `--minor`: bump **minor** (e.g. 1.0.0 -> 1.1.0)
+- `--major`: bump **major** (e.g. 1.0.0 -> 2.0.0)
+
+Use the Edit tool to update the `"version"` field in `package.json` directly. Do not use `npm version` or any CLI command.
+
+### Step 2: Run Tests
+
+```bash
+pnpm test
+```
+
+If tests fail:
+
+1. Read the failing test output
+2. Attempt to fix the issue
+3. Re-run tests
+4. If still failing after 2 attempts, stop and report the failures
+
+### Step 3: Type Check
+
+Root has no `lint` script -- `lint` only exists in `ui/package.json` (`tsc --noEmit`). `operations/package.json` has an equivalent `check-types` script; `core/package.json` has neither `lint` nor `check-types` (only `test`). Run:
+
+```bash
+pnpm -C ui lint
+pnpm -C operations check-types
+```
+
+If type errors exist:
+
+1. Read the errors
+2. Attempt to fix
+3. Re-run
+4. If still failing after 2 attempts, stop and report
+
+### Step 4: Build
+
+```bash
+pnpm build
+```
+
+If build fails:
+
+1. Read the error output
+2. Attempt to fix
+3. Re-run
+4. If still failing after 2 attempts, stop and report
+
+### Step 5: Commit
+
+1. Stage all changed files: `git add -A`
+2. Create commit with the provided message (or auto-generate from changes)
+3. Format: conventional commits (feat:, fix:, chore:, docs:, etc.)
+
+```bash
+git add -A
+git commit -m "<message>"
+```
+
+### Step 6: Push
+
+```bash
+git push
+```
+
+If push fails (e.g., remote has new commits):
+
+1. `git pull --rebase`
+2. Re-run tests to verify no conflicts broke anything
+3. `git push`
+
+### Step 7: Report
+
+```
+Deploy Complete
+===============
+Version: <old> -> <new>
+Tests:   passed
+Types:   clean
+Build:   success
+Commit:  <hash> - <message>
+Push:    pushed to <branch>
+```
+
+### Step 8: Project Task Status Transition
+
+After a successful push, mark any linked project task as `submitted`. This is a best-effort fanout -- it must never fail the deploy.
+
+1. **Resolve the task ID.** Look for a `prj_tasks` UUID tied to the current work, in this order:
+   - A task UUID explicitly captured in the current conversation (e.g. from a previous `/save`, `/project work`, or `project:task:*` invocation).
+   - The most recent in-progress task on the most-recently-touched project, via:
+
+     ```bash
+     pnpm elevasis-sdk project:list --status active --pretty
+     pnpm elevasis-sdk project:list --status blocked --pretty
+     pnpm elevasis-sdk project:task:list --project <project-id> --status in_progress --pretty
+     ```
+
+   - If the session produced an ambiguous or empty result, PROMPT the user once: "Mark a project task as submitted? (task UUID, or 'skip')". Default is skip.
+
+2. **Fire the transition** (only when a single confident task ID is resolved):
+
+   ```bash
+   pnpm elevasis-sdk project:task:update <task-id> --status submitted
+   ```
+
+3. **Failure handling.** If the CLI call errors, no task ID can be resolved, or the user declines, emit a single warning line and continue:
+
+   ```
+   Warning: skipped project:task status transition (<reason>). Deploy itself succeeded.
+   ```
+
+   Never retry, never block the deploy report, never exit non-zero on this step.
+
+## Error Recovery
+
+If any step fails and cannot be auto-fixed:
+
+```
+Deploy Failed at Step N: [step name]
+=====================================
+Error: [description]
+Attempted fixes: [what was tried]
+Manual action needed: [what the user should do]
+```

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

@@ -27,11 +27,18 @@ Manage SDK resources in the `operations/` workspace via the `elevasis-sdk` CLI.
 
 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:
+**API URL resolution priority** (highest wins, first match applies):
 
-- 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
+1. `--api-url <url>` CLI flag -- explicit override, always wins
+2. `--prod` flag -- forces `https://api.elevasis.io`
+3. `ELEVASIS_API_URL` env var -- custom URL override
+4. `NODE_ENV` default -- `http://localhost:5170` only when `NODE_ENV=development`; otherwise `https://api.elevasis.io`
+
+**The default target is production.** Unless `NODE_ENV=development` is set in the environment, every command hits `https://api.elevasis.io` even with no flags at all.
+
+**`NODE_ENV=development` is what selects the dev API** (`http://localhost:5170`). Setting `NODE_ENV=development` also switches the credential lookup: `ELEVASIS_PLATFORM_KEY_DEV` is used if set, falling back to `ELEVASIS_PLATFORM_KEY` if not.
+
+**`--prod` forces production, even under `NODE_ENV=development`.** It overrides the dev API URL back to `https://api.elevasis.io` AND forces the credential lookup to use `ELEVASIS_PLATFORM_KEY` (never the `_DEV` variant), regardless of `NODE_ENV`.
 
 ## Operations
 

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

@@ -1,78 +1,78 @@
----
-name: explore
-description: Codebase exploration anchored to project documentation
----
-
-# Explore
-
-Codebase exploration anchored to project documentation.
-
-**Usage:** `/explore [area or question]`
-
-## Process
-
-### Step 0: OS-Vocab Classification
-
-Before orienting, scan the user's query for Organization OS terminology. If any of the following appear, classify the query as **OS-relevant** and follow the OS context steps below; otherwise skip to Step 1.
-
-**OS vocabulary triggers:**
-
-- 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`
-- Org model: `organization`, `org model`, `organization model`, `domain`, `surface`
-- Foundations: `foundation`, `foundations`, `@core/`, `adapter`
-- Platform ops: `workflow`, `agent`, `deployment`, `resource`
-
-**If OS-relevant:**
-
-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`
-   - 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`
-
-**OS layer → query intent map** (guides which reference docs the investigator loads first):
-
-| 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` |
-| "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`    |
-
-### Step 1: Orient
-
-1. Read `.claude/rules/agent-start-here.md` for project structure, task-class routing, and boundary resolution
-2. Determine which domain the user's question falls into
-
-### Step 2: Load Domain Context
-
-Read the relevant doc(s) and source directories based on the area being explored. Use the Navigation table in `CLAUDE.md` for quick reference.
-
-For OS-relevant queries, also inject the OS context bundle assembled in Step 0 into the investigator's starting context.
-
-### Step 3: Investigate
-
-For targeted questions:
-
-- Use Grep to search for specific patterns, function names, or strings
-- Use Glob to find files by pattern
-- Read specific files for detailed understanding
-
-For broad exploration:
-
-- Dispatch a `general-purpose` subagent with the domain context and exploration question
-- The subagent should read files, trace data flow, and return a structured report
-- For OS-relevant queries, pass the preloaded OS context bundle so the subagent starts with terminology already resolved
-
-### Step 4: Report
-
-Present findings with:
-
-- Direct answers to the question
-- Relevant code locations (file:function format)
-- Connections to other parts of the system
-- Suggestions for related areas to explore (if relevant)
+---
+name: explore
+description: Codebase exploration anchored to project documentation
+---
+
+# Explore
+
+Codebase exploration anchored to project documentation.
+
+**Usage:** `/explore [area or question]`
+
+## Process
+
+### Step 0: OS-Vocab Classification
+
+Before orienting, scan the user's query for Organization OS terminology. If any of the following appear, classify the query as **OS-relevant** and follow the OS context steps below; otherwise skip to Step 1.
+
+**OS vocabulary triggers:**
+
+- 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`
+- Org model: `organization`, `org model`, `organization model`, `domain`, `surface`
+- Foundations: `foundation`, `foundations`, `@core/`, `adapter`
+- Platform ops: `workflow`, `agent`, `deployment`, `resource`
+
+**If OS-relevant:**
+
+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: `operations/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 `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` + `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+   - Workflow / Operations queries: add `.claude/rules/operations.md` + glob `operations/src/**`
+   - Organization-model queries: add `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` + `core/config/README.md`
+
+**OS layer → query intent map** (guides which reference docs the investigator loads first):
+
+| 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` |
+| "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`           |
+
+### Step 1: Orient
+
+1. Read `.claude/rules/agent-start-here.md` for project structure, task-class routing, and boundary resolution
+2. Determine which domain the user's question falls into
+
+### Step 2: Load Domain Context
+
+Read the relevant doc(s) and source directories based on the area being explored. Use the Navigation table in `CLAUDE.md` for quick reference.
+
+For OS-relevant queries, also inject the OS context bundle assembled in Step 0 into the investigator's starting context.
+
+### Step 3: Investigate
+
+For targeted questions:
+
+- Use Grep to search for specific patterns, function names, or strings
+- Use Glob to find files by pattern
+- Read specific files for detailed understanding
+
+For broad exploration:
+
+- Dispatch a `general-purpose` subagent with the domain context and exploration question
+- The subagent should read files, trace data flow, and return a structured report
+- For OS-relevant queries, pass the preloaded OS context bundle so the subagent starts with terminology already resolved
+
+### Step 4: Report
+
+Present findings with:
+
+- Direct answers to the question
+- Relevant code locations (file:function format)
+- Connections to other parts of the system
+- Suggestions for related areas to explore (if relevant)