@elevasis/sdk 1.23.0 → 1.25.0

package/reference/rules/active-change-index.md

@@ -0,0 +1,83 @@
+---
+description: Bridge between stable scaffold docs and higher-volatility in-progress architecture work that may override assumptions for agents working in the template
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Active Change Index
+
+Use this rule to decide whether stable scaffold docs are enough, or whether you also need to load in-progress platform architecture docs from the monorepo.
+
+> **Note:** Paths prefixed with `apps/` or `packages/` are monorepo-internal and unavailable in standalone projects. For those areas, use the stable scaffold docs under `node_modules/@elevasis/sdk/reference/scaffold/` as the primary reference. The monorepo paths are retained for contributors working within the monorepo.
+
+## Current Watch Areas
+
+### Organization OS
+
+Use when the task touches:
+
+- organization model semantics
+- feature/provider runtime
+- feature manifests or shell composition
+- graph or command-view concepts
+- downstream propagation of scaffold contract changes
+
+Load:
+
+- `apps/docs/content/docs/technical/architecture/core/organization-model/index.mdx`
+- `apps/docs/content/docs/technical/architecture/core/organization-model/graph.mdx`
+- `apps/docs/content/docs/technical/architecture/ui/feature-shell.mdx`
+- `apps/docs/content/docs/technical/architecture/ui/composition-extensibility.mdx`
+
+Stable scaffold docs affected:
+
+- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+- `.claude/rules/ui.md`
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md`
+
+### Package Surface / Reference System
+
+Use when the task touches:
+
+- published `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk` surfaces
+- generated package maps
+- contract drift between source and scaffold docs
+
+Load:
+
+- `packages/core/src/organization-model/README.md`
+- `packages/ui/src/provider/README.md`
+- `packages/ui/src/features/README.md`
+- `packages/sdk/reference/_navigation.md`
+
+Stable scaffold docs affected:
+
+- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+
+### Resource / Topology Mapping
+
+Use when the task touches:
+
+- resource registration
+- triggers, integrations, relationships, human checkpoints
+- topology-aware navigation or impact analysis
+
+Load:
+
+- `operations/src/README.md`
+- `operations/src/index.ts`
+
+Stable scaffold docs affected:
+
+- `.claude/rules/operations.md`
+
+## Working Rule
+
+When a task touches one of the watch areas above:
+
+1. Read the stable scaffold doc.
+2. Read the listed in-progress or package-local source-of-truth docs.
+3. Prefer source and in-progress architecture docs if they disagree with scaffold prose.
+4. Flag drift instead of silently trusting the scaffold doc.

package/reference/rules/agent-start-here.md

@@ -0,0 +1,280 @@
+---
+description: Canonical first-read for agents entering the template scaffold -- project continuity, task-class routing, and boundary resolution
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Agent Start Here
+
+Read this file first when entering a freshly scaffolded project.
+
+## Project Profile
+
+Before doing anything else, check for `.claude/memory/profile.md`. It is created by `/tutorial` on first invocation and persists across sessions.
+
+If present, read it. The file declares which onboarding **track** is active -- `vibe-coder` (non-technical user, agent does the work) or `technical` (developer, code-first) -- and ships a tone block describing how to communicate.
+
+Apply the tone block to ALL agent output for the rest of the session, not just inside `/tutorial`:
+
+- **vibe-coder track:** never use technical vocabulary in user-facing dialogue (workflow -> automation, deploy -> make it live, schema -> "the information your automation needs"). Tool calls are made silently -- do not narrate slash commands, file paths, or build steps. The full swap table lives in `profile.md`.
+- **technical track:** code-first, current command surface, real file paths. The user reads diffs and stacktraces; do not over-explain.
+
+If the file does not exist, the user has not run `/tutorial` yet. Proceed normally and note that running `/tutorial` would establish a project tone for future sessions.
+
+## First Action: Check Active Projects
+
+Before loading any docs for a new session, check whether the user's ask resumes or relates to an in-flight client project. Project context (milestones, tasks, resume notes) is DB-canonical -- agents and CLI read/write it through the `elevasis-sdk project:*` surface.
+
+1. **Portfolio snapshot.** Run this first to see what is active or blocked:
+
+   ```bash
+   pnpm elevasis-sdk project:list --status active --pretty
+   pnpm elevasis-sdk project:list --status blocked --pretty
+   ```
+
+2. **Resume-style asks.** If the user says "continue", "pick up", references a client name, or names a task/milestone, resolve it via:
+
+   ```bash
+   pnpm elevasis-sdk project:work <query>
+   ```
+
+   `project:work` fuzzy-matches a project or task by name/ID and returns the current resume context -- the canonical continuity payload (current state, next steps, files modified, key docs).
+
+3. **Fresh non-project asks.** Only if the portfolio snapshot and the request show no overlap with active projects, fall back to the docs-index flow below. Even then, if the work will take more than a single file edit, offer to create a project first (`/project create` or `project:create`) so continuity is captured from the start.
+
+### Resume Context Source of Truth
+
+`resume_context` lives in the `prj_tasks` table in the database, not in task-doc frontmatter. There is one source of truth:
+
+- **Humans write** via the inline resume-context editor on the Project Detail page in Command Center.
+- **Agents and the CLI write** via `pnpm elevasis-sdk project:task:save <task-id> --current-state ... --next-steps ... --files-modified ...`.
+- **Readers** consume it via `project:work <query>` or `project:task:resume <id>`.
+
+Do not write resume state into markdown frontmatter. Task-doc frontmatter is limited to `title`, `description`, and `status`.
+
+### Session-Start Dashboard
+
+The session-start dashboard directive lives in `CLAUDE.md`. If you see it there, follow it on the first response of a session. This file (`agent-start-here` rule) is the drill-down reference layer; `CLAUDE.md` owns session bootstrap.
+
+## Template Surfaces
+
+Once project continuity is resolved (or confirmed irrelevant), the template is not just an app starter. It is an agent operating environment with several distinct surfaces:
+
+- `ui/` -- React frontend app and shell composition
+- `operations/` -- Elevasis SDK resources deployed to the platform
+- `core/` -- runtime-agnostic shared contracts and organization model adaptation
+- `.claude/` -- local agent rules, skills, and hooks
+- `client-workspace/` -- optional separate knowledge workspace for richer team knowledge management
+- `node_modules/@elevasis/sdk/reference/scaffold/` -- SDK reference scaffold: canonical recipes, UI patterns, gating model, contracts, and glossary. Entry point: `index.mdx`.
+
+## Discovery Order
+
+Use this order unless a more specific doc tells you otherwise:
+
+1. Complete the "First Action: Check Active Projects" flow above.
+2. Read `CLAUDE.md` for project rules, command surface, and navigation pointers.
+3. Read this rule and classify the task using the Task Classes below.
+4. Read `identity.clientBrief` from the OrganizationModel (`core/config/organization-model.ts`) for organization context and naming.
+5. Read the relevant structural map:
+   - Glob `node_modules/@elevasis/sdk/reference/` for published package surfaces
+   - Read `operations/src/index.ts` for deployment assembly, `core/config/organization-model.ts` for resource descriptors, or run `pnpm elevasis-sdk project:list --pretty` for live DB state
+6. For feature integration, resource authoring, or UI customization tasks, read `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` to find the canonical recipe or reference doc.
+7. Drill into the co-located local explainer for the abstraction boundary you are changing.
+8. Check the `.claude/rules/active-change-index.md` rule before trusting stable assumptions in areas that are under active architecture work.
+
+## SDK Reference Scaffold
+
+Universal scaffold documentation (recipes, patterns, architecture, reference) has been centralized in the SDK reference. After `pnpm install`, the entry point is:
+
+`node_modules/@elevasis/sdk/reference/scaffold/index.mdx`
+
+This index links to all scaffold docs including pathway recipes, UI patterns, core architecture, and auto-generated contracts/feature registry.
+
+For task classes that involve feature integration, resource authoring, or UI customization, start with the scaffold index rather than local docs.
+
+## Task Classes
+
+Classify the request, then follow the load/inspect/verify sequence for that class.
+
+### 1. UI / Shell Work
+
+Examples: add a page, change sidebar behavior, adjust feature visibility, update dashboard labels.
+
+Load first:
+
+- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- UI recipes, feature flags, customization)
+- `.claude/rules/ui.md`
+- `ui/src/routes/README.md`
+- `core/config/README.md`
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- specifically recipe 6 when building a "run this resource" surface
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md` -- when building or extending CRM pages, sidebars, hooks, workflows, or deal data surfaces
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- when building or extending lead-gen pages, sidebars, hooks, workflows, list/member state, or artifacts
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` -- when changing CRM deal action buttons or adding a workflow-backed deal action
+
+Then inspect:
+
+- `ui/src/routes/__root.tsx`
+- `ui/src/config/*`
+- relevant `ui/src/routes/*`
+- relevant `ui/src/features/*`
+- `core/config/organization-model.ts`
+
+Verify with:
+
+- route and manifest source
+- any relevant package README from `packages/ui`
+
+### 2. Workflow / Agent / Operations Work
+
+Examples: add a workflow, update an agent, change resource registration, understand deployable resources.
+
+Load first:
+
+- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- workflow recipes, resource authoring)
+- `.claude/rules/operations.md`
+- `operations/src/README.md`
+
+Then inspect:
+
+- `operations/src/index.ts`
+- relevant `operations/src/<feature>/*`
+- `core/types/index.ts` -- workflow input/output Zod schemas
+- `core/types/entities.ts` -- typed entity contracts (Project, Deal, etc.) extending `@elevasis/core/entities` base types. Read this when authoring a workflow that takes or returns these entities so the input/output schemas reference the canonical entity shapes rather than redeclaring them.
+- `operations/elevasis.config.ts`
+
+Verify with:
+
+- Read `operations/src/index.ts` for deployment assembly, `core/config/organization-model.ts` for resource descriptors, or run `pnpm elevasis-sdk project:list --pretty` for live DB state
+- local SDK guidance in `.claude/skills/elevasis/SKILL.md`
+
+### 3. Organization Model / Feature Access Work
+
+Examples: rename a feature area, change quick access surfaces, map new business terms into the shell, adjust feature gating.
+
+Load first:
+
+- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- contracts, gating patterns, glossary)
+- `core/config/README.md`
+- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+- typed feature/surface constants from `@elevasis/core/organization-model` -- `CRM_FEATURE_ID`, `LEAD_GEN_FEATURE_ID`, `PROJECTS_FEATURE_ID`, `OPERATIONS_FEATURE_ID`, `MONITORING_FEATURE_ID`, `SETTINGS_FEATURE_ID`, `SEO_FEATURE_ID`, `CRM_PIPELINE_SURFACE_ID`, `LEAD_GEN_LISTS_SURFACE_ID`, `PROJECTS_INDEX_SURFACE_ID`, `OPERATIONS_ORGANIZATION_GRAPH_SURFACE_ID`. Use these typed constants instead of magic strings when overriding feature/surface IDs.
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md` -- CRM is an Organization OS + UI + hooks + workflow-adapter surface; read this before extending CRM structure.
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- lead gen is an Organization OS + UI + hooks + workflow-adapter surface; read this before extending lead-gen lists, members, artifacts, or state transitions.
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` -- CRM action buttons are not `sales.actions` org-model config in v1; use the recipe's provider/custom-button path.
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md`
+
+Then inspect:
+
+- `core/config/organization-model.ts`
+- `core/config/organization-model.ts` -- Organization Model overrides plus Systems and Resources descriptors. Start here for feature labels, surface mapping, and resource identity/governance changes.
+- `ui/src/routes/__root.tsx`
+- `ui/src/lib/hooks/useFeatureAccess.ts`
+- relevant nav config files
+
+Verify with:
+
+- published package docs for `@elevasis/core/organization-model`
+- current scaffold routes and manifests
+
+### 4. Debugging / Impact Analysis
+
+Examples: why is this automation disconnected, what does this workflow affect, what should I inspect before changing this resource.
+
+Load first:
+
+- `operations/src/README.md`
+- `.claude/rules/active-change-index.md`
+- Read `operations/src/index.ts` for deployment assembly, `core/config/organization-model.ts` for resource descriptors, or run `pnpm elevasis-sdk project:list --pretty` for live DB state
+- For "why didn't this run?", "why is this still pending?", "what needs approval?", or schedule/queue debugging, inspect live operations state with `pnpm elevasis-sdk schedule:list --pretty`, `pnpm elevasis-sdk queue:list --status pending --pretty`, and `pnpm elevasis-sdk queue:status --pretty`.
+
+Then inspect:
+
+- `operations/src/index.ts`
+- resource definitions
+- related UI route and feature files
+- related core contracts
+- pending HITL items via `elevasis-sdk queue:get <id>` before selecting or expiring an action
+- recurring automation via `elevasis-sdk schedule:get <id>` before pausing, resuming, or cancelling it
+
+Verify with:
+
+- resource registration and relationship declarations
+- generated maps
+- package and source ownership boundaries
+- `queue:*` or `schedule:*` CLI output when runtime state is part of the question
+
+### 5. Platform Extension / Package Contract Work
+
+Examples: extend a published package contract, understand how a scaffold surface maps to `@elevasis/ui`, update a package-facing reference doc.
+
+Load first:
+
+- `.claude/rules/active-change-index.md`
+- Glob `node_modules/@elevasis/sdk/reference/` for the current SDK package surface
+- package README found via that glob
+
+Then inspect:
+
+- package source entrypoints
+- package reference manifests
+- scaffold files that consume that contract
+
+Verify with:
+
+- published package docs
+- source exports
+- scaffold consumption points
+
+## Boundary Resolution
+
+Once the request is classified, determine which boundary owns the change:
+
+- **Core boundary** -- semantics, aliases, labels, shared schemas
+- **UI shell boundary** -- provider composition, manifests, navigation, route ownership
+- **Operations boundary** -- deployable resource registration, workflow/agent contracts, topology
+- **Package boundary** -- public exports, shared platform behavior, reusable contracts
+
+If a task spans boundaries, start at the semantic boundary, then move to runtime composition, then to registration/deployment.
+
+## Main Boundaries
+
+### `core/config/organization-model.ts`
+
+The semantic adaptation point between platform contracts and scaffold-local terminology. Start here for feature labels, legacy aliases, quick-access surfaces, and shell-facing organization semantics.
+
+### `ui/src/routes/__root.tsx`
+
+The shell composition point. Start here for manifest mounting, provider wiring, app-local nav, and how the scaffold combines published feature surfaces with project-owned shell concerns.
+
+### `operations/src/index.ts`
+
+The deployment aggregation point. Start here for what resources are registered and deployed as part of the scaffold.
+
+## Source of Truth
+
+Trust these in order:
+
+1. Source code and published package docs
+2. Co-located boundary docs
+3. Generated structural maps
+4. Hand-authored template guidance
+5. In-progress architecture docs when `.claude/rules/active-change-index.md` says the area is actively evolving
+
+If a hand-authored doc conflicts with source or published package docs, trust source and flag the doc drift.
+
+## Common Traps
+
+- Do not assume feature directories are exhaustive without also checking `operations/src/index.ts` and `core/config/organization-model.ts` directly.
+- Do not assume placeholder knowledge is sufficient for real client context. Read `identity.clientBrief` from the OrganizationModel (`core/config/organization-model.ts`).
+- Do not trust stable docs blindly when `.claude/rules/active-change-index.md` flags related in-progress architecture work.
+- Do not write `resume_context` into task-doc frontmatter. DB is canonical; write via `project:task:save` or the inline editor in Command Center.
+
+## Operations-Only Projects
+
+Some projects derived from this template are operations-only. They have `operations/` (or a top-level `src/`) but NO `ui/`, NO `core/config/organization-model.ts`, and NO frontend. Finding none of these is not missing scaffolding -- it is by design.
+
+**What applies:** Only Task Classes 2 (Workflow / Agent / Operations Work) and 4 (Debugging / Impact Analysis) apply to operations-only projects. Task Classes 1 (UI / Shell Work), 3 (Organization Model / Feature Access Work), and 5 (Platform Extension / Package Contract Work) do not apply and can be skipped.
+
+**Primary entrypoint:** For operations-only projects, the project's own `CLAUDE.md` and its Navigation table are the canonical first-read. This rule provides task-routing context but its full surface map is irrelevant for that project type.
+
+**Signal:** The `CLAUDE.md` of an operations-only project includes `Project type: operations-only` in its `## Project` section. When you see this signal, skip all template surfaces that don't exist and go directly to the operations task class.

package/reference/rules/deployment.md

@@ -0,0 +1,60 @@
+---
+description: Deployment workflow -- check-first, dev vs prod, version bumping, common errors
+paths:
+  - operations/**
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Deployment
+
+## Always Check Before Deploy
+
+```bash
+pnpm -C operations run check        # Validate resource definitions
+pnpm -C operations run check-types  # TypeScript type-check
+pnpm -C operations run deploy       # Deploy to dev (only after both pass)
+```
+
+`check` catches duplicate resource IDs, OM descriptor/code mismatches, invalid step chains, broken relationships, and schema serialization issues. Same validation runs during deploy -- if `check` passes, deploy validation will pass.
+
+## Dev vs Prod
+
+| Command                              | Target            | When                    |
+| ------------------------------------ | ----------------- | ----------------------- |
+| `pnpm -C operations run deploy`      | Local dev API     | Development and testing |
+| `pnpm -C operations run deploy:prod` | `api.elevasis.io` | Production release      |
+
+Always test in dev first, verify with `elevasis-sdk exec`, then deploy to prod.
+
+## Version Bumping
+
+Deploy accepts `--major`, `--minor`, `--patch` flags to bump the deployment version. The bumped version is written back to `src/index.ts`. Bump on contract changes (input/output schema modifications).
+
+## What Gets Deployed
+
+1. **Bundle:** esbuild compiles `src/index.ts` + all dependencies into a single self-contained CJS file. No `node_modules` needed at runtime.
+2. **Metadata:** Resource definitions, OM Resources descriptor bindings, Zod schemas (converted to JSON Schema), relationships, triggers.
+
+## Environment
+
+- `ELEVASIS_PLATFORM_KEY` in `.env` is required for CLI auth
+- `.env` is never included in the bundle -- it stays local
+- Integration credentials live in Command Center, not `.env`
+
+## Common Errors
+
+| Error                                    | Fix                                                                                                 |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `401: Invalid API key`                   | Check `ELEVASIS_PLATFORM_KEY` in `.env`                                                             |
+| `Duplicate resource ID`                  | Fix the duplicated OM Resource descriptor ID, then derive runtime `resourceId` from that descriptor |
+| `Missing OM Resource descriptor`         | Add the descriptor to `core/config/organization-model.ts` under the id-keyed `resources` map        |
+| `Step references non-existent next step` | Fix the `next:` field in the step chain                                                             |
+| `Schema serialization failed`            | Simplify the Zod schema (warning, still deploys)                                                    |
+| `No default export found`                | `src/index.ts` must `export default` a `DeploymentSpec`                                             |
+| `Documentation file exceeds 100KB`       | Split the `.md` file                                                                                |
+
+## Deployment Replaces Previous
+
+Only one deployment can be `active` at a time. Deploying again automatically marks the previous deployment as `stopped`. Resources become executable immediately after deploy succeeds.

package/reference/rules/error-handling.md

@@ -0,0 +1,59 @@
+---
+description: Error handling -- ExecutionError vs PlatformToolError, retry logic, no auto-retry
+paths:
+  - operations/**
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Error Handling
+
+## Error Types
+
+Two error classes from `@elevasis/sdk`:
+
+**`ExecutionError`** -- base class for workflow/step failures.
+
+```typescript
+import { ExecutionError } from '@elevasis/sdk'
+
+throw new ExecutionError('Payment processing failed', {
+  context: { invoiceId: '123', amount: 500 }
+})
+```
+
+**`PlatformToolError`** -- thrown by `platform.call()` and typed adapters.
+
+```typescript
+import { PlatformToolError } from '@elevasis/sdk'
+
+try {
+  await attio.createRecord({ ... })
+} catch (err) {
+  if (err instanceof PlatformToolError && err.retryable) {
+    // Transient error (rate limit, timeout, network) -- safe to retry
+  } else {
+    // Permanent error (invalid credentials, bad input) -- don't retry
+  }
+}
+```
+
+## No Auto-Retry
+
+The platform does NOT automatically retry failed steps. Your handler is responsible for retry logic. Check `PlatformToolError.retryable` to decide whether retrying is safe.
+
+## Error Visibility
+
+- Unhandled exceptions in handlers surface directly to CLI output and AI Studio.
+- Use `context.logger.error()` to log errors -- `console.error()` is NOT captured by the platform.
+- Write clear, descriptive error messages -- they're the primary debugging signal for end users.
+
+## Common PlatformToolError Codes
+
+| Code                  | Retryable | Cause                             |
+| --------------------- | --------- | --------------------------------- |
+| `rate_limit_exceeded` | Yes       | Integration API rate limit hit    |
+| `timeout_error`       | Yes       | Integration call timed out        |
+| `credentials_invalid` | No        | Credential not found or expired   |
+| `validation_error`    | No        | Invalid parameters passed to tool |

package/reference/rules/execution.md

@@ -0,0 +1,43 @@
+---
+description: Execution model -- timeouts, memory, concurrency, org isolation, runtime constraints
+paths:
+  - operations/**
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Execution Model
+
+## Runtime Environment
+
+Each execution runs in an isolated Node.js worker thread spawned from the deployed bundle. Workers are ephemeral -- created on execution start, terminated on completion. No state persists between executions.
+
+## Constraints
+
+| Constraint | Workflows                       | Agents                                                |
+| ---------- | ------------------------------- | ----------------------------------------------------- |
+| Timeout    | 300s (5 min)                    | 600s (10 min, configurable via `constraints.timeout`) |
+| Memory     | 256MB hard limit                | 256MB hard limit                                      |
+| Disk       | None (no persistent filesystem) | None                                                  |
+
+- Platform enforces timeouts -- no handler code needed, worker terminates automatically.
+- Memory overflow crashes the worker. Other tenants are unaffected.
+- For long-running tasks, break work into multiple steps or use agents with extended timeout.
+
+## Concurrency
+
+Concurrent executions for the same organization run in completely separate workers with zero shared state. No locking, no race conditions between executions.
+
+## Organization Isolation
+
+- `organizationId` is injected server-side from the JWT context -- workers never see it.
+- Storage paths are automatically org-prefixed.
+- Resource IDs are scoped per organization (not global).
+- External developers cannot access other organizations' data by construction.
+
+No developer action needed for multi-tenancy -- the platform handles it.
+
+## Cancellation
+
+The platform can cancel in-flight executions. The worker terminates immediately with no cleanup handler.

package/reference/rules/frontend.md

@@ -0,0 +1,46 @@
+---
+description: Frontend conventions -- React, routing, state, styling, testing, pages
+paths:
+  - ui/src/**
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Frontend
+
+## Safety Invariants
+
+- `ElevasisUIProvider` in `ui/src/main.tsx` auto-composes shared UI, auth, and API surface -- route files do not wire providers manually
+- `useApiClient()` from `@/lib/hooks/useApiClient` for authenticated API calls -- never raw `fetch` with auth headers
+- `routeTree.gen.ts` is auto-generated on `pnpm dev` -- never edit manually
+- Auth protection: wrap page content with `ProtectedRoute` from `@elevasis/ui/auth`. Admin pages nest `AdminGuard` inside `ProtectedRoute`
+- Never fork `@elevasis/ui` components -- if a published component needs a tweak, that missing capability is a bug in `@elevasis/ui`
+
+## Silent-Break Gotchas
+
+- Route files vs layout files: `operations.tsx` is a layout (renders `<Outlet />`), `operations/my-page.index.tsx` is a page. Confusing the two breaks routing silently
+- `core/` cannot import React or `@elevasis/sdk/worker` -- it is runtime-agnostic shared types and organization configuration only
+- `@/*` resolves to `ui/src/*`, `@core/*` resolves to `core/*` -- never import from `operations/` (separate runtime)
+
+## Stack Constraints
+
+- Mantine 8.2.7 for all UI components -- no Radix UI, no Tailwind CSS, no shadcn
+- `@tabler/icons-react` for icons -- never Lucide
+- Server state: TanStack Query. Client state: Zustand + Immer. Never mix the two
+- Glass background is the primary surface treatment: `var(--glass-background)` with `backdrop-filter: var(--glass-blur)`
+- Import shared components from `@elevasis/ui/components`, `@elevasis/ui/layout`, `@elevasis/ui/charts`
+- Import charts from `@elevasis/ui/charts`, not directly from `@mantine/charts`
+
+## Integration UI Surfaces
+
+When building pages that display external data, use published `@elevasis/ui` components before building custom UI. Use Mantine components and CSS variables exclusively -- no inline hex colors, no custom design tokens. Match existing page density and spacing.
+
+## Detailed Reference
+
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- add a page, add a nav item, theme tokens, feature-scoped components, route patterns (static, nested, dynamic)
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- `systemKey` / `SystemGuard` / `AdminGuard` model
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` -- sidebar composition via manifest overrides
+- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- TypeScript shapes (`SystemModule`, `NavItem`, `OrganizationModel`)
+- `ui/src/config/theme.ts` -- theme configuration and CSS variable definitions
+- `ui/src/config/nav-items.ts` -- sidebar navigation entries

package/reference/rules/observability.md

@@ -0,0 +1,34 @@
+---
+description: Observability -- context.logger API, execution inspection, step-level context
+paths:
+  - operations/**
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Observability
+
+## Safety Invariants
+
+- Use `context.logger` for all logging in step handlers -- `console.*` is NOT captured by the platform
+- Log levels: `debug` (verbose), `info` (normal progress), `warn` (non-fatal, processing continues), `error` (fatal, processing stops)
+- Step lifecycle events (started, completed, failed, route taken) are auto-logged by the SDK worker -- no handler code needed
+
+## Key Rules
+
+- Every handler should log at: entry (step name + key params), decisions (skips, branches), progress (per-item in loops), summary (counts at end)
+- Error messages in handlers surface as the execution's error message -- write for humans, not machines
+- String values truncated at 200 characters in logs
+- 30-day log retention (includes logs from deleted resources)
+
+## Inspecting Executions
+
+```bash
+pnpm elevasis-sdk execution <resourceId> <executionId>
+pnpm elevasis-sdk executions <resourceId>
+```
+
+## Detailed Reference
+
+- `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- full logging patterns and handler examples