@elevasis/sdk 1.5.3 → 1.5.5

package/dist/index.d.ts

@@ -2275,113 +2275,6 @@ type Database = {
                     }
                 ];
             };
-            calibration_projects: {
-                Row: {
-                    created_at: string | null;
-                    description: string | null;
-                    id: string;
-                    name: string;
-                    organization_id: string;
-                    resource_id: string;
-                    resource_type: string;
-                    updated_at: string | null;
-                };
-                Insert: {
-                    created_at?: string | null;
-                    description?: string | null;
-                    id?: string;
-                    name: string;
-                    organization_id: string;
-                    resource_id: string;
-                    resource_type: string;
-                    updated_at?: string | null;
-                };
-                Update: {
-                    created_at?: string | null;
-                    description?: string | null;
-                    id?: string;
-                    name?: string;
-                    organization_id?: string;
-                    resource_id?: string;
-                    resource_type?: string;
-                    updated_at?: string | null;
-                };
-                Relationships: [
-                    {
-                        foreignKeyName: "calibration_projects_organization_id_fkey";
-                        columns: ["organization_id"];
-                        isOneToOne: false;
-                        referencedRelation: "organizations";
-                        referencedColumns: ["id"];
-                    }
-                ];
-            };
-            calibration_runs: {
-                Row: {
-                    completed_at: string | null;
-                    config_variants: Json;
-                    created_at: string | null;
-                    description: string | null;
-                    execution_mode: string;
-                    grader_model: string | null;
-                    grading_rubric: Json | null;
-                    id: string;
-                    name: string;
-                    organization_id: string;
-                    project_id: string;
-                    results: Json;
-                    status: string;
-                    test_inputs: Json;
-                };
-                Insert: {
-                    completed_at?: string | null;
-                    config_variants: Json;
-                    created_at?: string | null;
-                    description?: string | null;
-                    execution_mode?: string;
-                    grader_model?: string | null;
-                    grading_rubric?: Json | null;
-                    id?: string;
-                    name: string;
-                    organization_id: string;
-                    project_id: string;
-                    results?: Json;
-                    status?: string;
-                    test_inputs: Json;
-                };
-                Update: {
-                    completed_at?: string | null;
-                    config_variants?: Json;
-                    created_at?: string | null;
-                    description?: string | null;
-                    execution_mode?: string;
-                    grader_model?: string | null;
-                    grading_rubric?: Json | null;
-                    id?: string;
-                    name?: string;
-                    organization_id?: string;
-                    project_id?: string;
-                    results?: Json;
-                    status?: string;
-                    test_inputs?: Json;
-                };
-                Relationships: [
-                    {
-                        foreignKeyName: "calibration_runs_organization_id_fkey";
-                        columns: ["organization_id"];
-                        isOneToOne: false;
-                        referencedRelation: "organizations";
-                        referencedColumns: ["id"];
-                    },
-                    {
-                        foreignKeyName: "calibration_runs_project_id_fkey";
-                        columns: ["project_id"];
-                        isOneToOne: false;
-                        referencedRelation: "calibration_projects";
-                        referencedColumns: ["id"];
-                    }
-                ];
-            };
             command_queue: {
                 Row: {
                     action_payload: Json | null;
@@ -3339,6 +3232,91 @@ type Database = {
                     }
                 ];
             };
+            reported_issues: {
+                Row: {
+                    affected_page: string | null;
+                    category: string;
+                    context: Json | null;
+                    created_at: string;
+                    description: string;
+                    evidence: Json | null;
+                    id: string;
+                    organization_id: string;
+                    project_id: string | null;
+                    reported_at: string;
+                    reporter_id: string | null;
+                    resolved_at: string | null;
+                    severity: string;
+                    source: string;
+                    status: string;
+                    task_id: string | null;
+                    title: string;
+                    updated_at: string;
+                };
+                Insert: {
+                    affected_page?: string | null;
+                    category: string;
+                    context?: Json | null;
+                    created_at?: string;
+                    description: string;
+                    evidence?: Json | null;
+                    id?: string;
+                    organization_id: string;
+                    project_id?: string | null;
+                    reported_at?: string;
+                    reporter_id?: string | null;
+                    resolved_at?: string | null;
+                    severity: string;
+                    source: string;
+                    status?: string;
+                    task_id?: string | null;
+                    title: string;
+                    updated_at?: string;
+                };
+                Update: {
+                    affected_page?: string | null;
+                    category?: string;
+                    context?: Json | null;
+                    created_at?: string;
+                    description?: string;
+                    evidence?: Json | null;
+                    id?: string;
+                    organization_id?: string;
+                    project_id?: string | null;
+                    reported_at?: string;
+                    reporter_id?: string | null;
+                    resolved_at?: string | null;
+                    severity?: string;
+                    source?: string;
+                    status?: string;
+                    task_id?: string | null;
+                    title?: string;
+                    updated_at?: string;
+                };
+                Relationships: [
+                    {
+                        foreignKeyName: "reported_issues_organization_id_fkey";
+                        columns: ["organization_id"];
+                        isOneToOne: false;
+                        referencedRelation: "organizations";
+                        referencedColumns: ["id"];
+                    },
+                    {
+                        foreignKeyName: "reported_issues_project_id_fkey";
+                        columns: ["project_id"];
+                        isOneToOne: false;
+                        referencedRelation: "prj_projects";
+                        referencedColumns: ["id"];
+                    },
+                    {
+                        foreignKeyName: "reported_issues_task_id_fkey";
+                        columns: ["task_id"];
+                        isOneToOne: false;
+                        referencedRelation: "prj_tasks";
+                        referencedColumns: ["id"];
+                    }
+                ];
+            };
             session_messages: {
                 Row: {
                     created_at: string | null;
@@ -6537,6 +6515,7 @@ declare const ProjectSchemas: {
             at_risk: "at_risk";
             blocked: "blocked";
         }>>;
+        search: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     ProjectIdParams: z.ZodObject<{
         id: z.ZodString;
@@ -6568,6 +6547,11 @@ declare const ProjectSchemas: {
         due_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         completed_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         sequence: z.ZodOptional<z.ZodNumber>;
+        checklist: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            completed: z.ZodBoolean;
+        }, z.core.$strip>>>;
         metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     }, z.core.$strict>;
     ProjectIdPathParams: z.ZodObject<{
@@ -6583,9 +6567,9 @@ declare const ProjectSchemas: {
             code: "code";
             other: "other";
             documentation: "documentation";
+            research: "research";
             report: "report";
             design: "design";
-            research: "research";
             refactor: "refactor";
             feature: "feature";
             bug: "bug";
@@ -6619,9 +6603,9 @@ declare const ProjectSchemas: {
             code: "code";
             other: "other";
             documentation: "documentation";
+            research: "research";
             report: "report";
             design: "design";
-            research: "research";
             refactor: "refactor";
             feature: "feature";
             bug: "bug";
@@ -8035,7 +8019,7 @@ interface ResourceList {
     environment?: 'dev' | 'prod';
 }
 /** Webhook provider identifiers */
-type WebhookProviderType = 'cal-com' | 'stripe' | 'signature-api' | 'instantly' | 'apify';
+type WebhookProviderType = 'cal-com' | 'stripe' | 'signature-api' | 'instantly' | 'apify' | 'test';
 /** Webhook trigger configuration */
 interface WebhookTriggerConfig {
     /** Provider identifier */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -44,7 +44,7 @@
     "tsup": "^8.0.0",
     "typescript": "5.9.2",
     "zod": "^4.1.0",
-    "@repo/core": "0.2.1",
+    "@repo/core": "0.5.0",
     "@repo/typescript-config": "0.0.0"
   },
   "scripts": {

package/reference/_navigation.md

@@ -2,7 +2,7 @@
 
 Auto-generated from the package reference manifests.
 
-Package entries indexed: 36.
+Package entries indexed: 41.
 
 ## @elevasis/core / Core
 
@@ -10,6 +10,12 @@ Package entries indexed: 36.
 | --- | --- | --- | --- |
 | Core | `packages/core/src/README.md` | Published core wrapper for the curated contract surface. | (not specified) |
 
+## @elevasis/core / Entities
+
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Entities | `packages/core/src/business/README.md` | Published base entity contracts (Project, Milestone, Task, Deal, Company, Contact) generic over a metadata extension slot. | (not specified) |
+
 ## @elevasis/core / Organization Model
 
 | Resource | Location | Description | When to Load |
@@ -69,12 +75,15 @@ Package entries indexed: 36.
 | Router | `packages/ui/src/router/README.md` | Published router entry for downstream applications. | (not specified) |
 | Router Context | `packages/ui/src/router/README.md` | Published router context entry for downstream applications. | (not specified) |
 | Zustand | `packages/ui/src/zustand/README.md` | Published Zustand slice entry for downstream applications. | (not specified) |
+| App | `packages/ui/src/app/README.md` | Published app factory that composes providers, router, auth, and theme into a mountable React app. | (not specified) |
 
 ## @elevasis/ui / Hooks
 
 | Resource | Location | Description | When to Load |
 | --- | --- | --- | --- |
 | Hooks | `packages/ui/src/hooks/README.md` | Headless hooks surface for executions, sessions, observability, and operations. | (not specified) |
+| Hooks Delivery | `packages/ui/src/hooks/README.md` | Published delivery hooks for projects, milestones, tasks, and notes. | (not specified) |
+| Transform Command View Data | `packages/ui/src/hooks/README.md` | Utility that transforms backend CommandViewData arrays into a unified frontend CommandViewGraph with nodes and edges. | (not specified) |
 
 ## @elevasis/ui / Provider
 
@@ -82,6 +91,7 @@ Package entries indexed: 36.
 | --- | --- | --- | --- |
 | Provider | `packages/ui/src/provider/README.md` | Published provider and feature-shell contract for downstream apps. | (not specified) |
 | Provider UI | `packages/ui/src/provider/README.md` | Published provider UI entry for downstream applications. | (not specified) |
+| Elevasis Service Context | `packages/ui/src/provider/README.md` | Standalone service context and provider that supplies apiRequest, organizationId, and isReady to child components. | (not specified) |
 
 ## @elevasis/ui / Visual
 

package/reference/_reference-manifest.json

@@ -15,6 +15,20 @@
       "referencePath": "packages/core/src/README.md",
       "publishedExportPath": "./dist/index.js"
     },
+    {
+      "packageName": "@elevasis/core",
+      "packageDir": "packages/core",
+      "subpath": "./entities",
+      "kind": "subpath",
+      "title": "Entities",
+      "description": "Published base entity contracts (Project, Milestone, Task, Deal, Company, Contact) generic over a metadata extension slot.",
+      "group": "Entities",
+      "order": 1,
+      "sourcePath": "packages/core/src/business/entities-published.ts",
+      "docPath": "packages/core/src/business/README.md",
+      "referencePath": "packages/core/src/business/README.md",
+      "publishedExportPath": "./dist/business/entities-published.js"
+    },
     {
       "packageName": "@elevasis/core",
       "packageDir": "packages/core",
@@ -435,6 +449,20 @@
       "referencePath": "packages/ui/src/zustand/README.md",
       "publishedExportPath": "./dist/zustand/index.js"
     },
+    {
+      "packageName": "@elevasis/ui",
+      "packageDir": "packages/ui",
+      "subpath": "./app",
+      "kind": "subpath",
+      "title": "App",
+      "description": "Published app factory that composes providers, router, auth, and theme into a mountable React app.",
+      "group": "Foundation",
+      "order": 14,
+      "sourcePath": "packages/ui/src/app/index.ts",
+      "docPath": "packages/ui/src/app/README.md",
+      "referencePath": "packages/ui/src/app/README.md",
+      "publishedExportPath": "./dist/app/index.js"
+    },
     {
       "packageName": "@elevasis/ui",
       "packageDir": "packages/ui",
@@ -449,6 +477,34 @@
       "referencePath": "packages/ui/src/hooks/README.md",
       "publishedExportPath": "./dist/hooks/published.js"
     },
+    {
+      "packageName": "@elevasis/ui",
+      "packageDir": "packages/ui",
+      "subpath": "./hooks/delivery",
+      "kind": "subpath",
+      "title": "Hooks Delivery",
+      "description": "Published delivery hooks for projects, milestones, tasks, and notes.",
+      "group": "Hooks",
+      "order": 2,
+      "sourcePath": "packages/ui/src/hooks/delivery/index.ts",
+      "docPath": "packages/ui/src/hooks/README.md",
+      "referencePath": "packages/ui/src/hooks/README.md",
+      "publishedExportPath": "./dist/hooks/delivery/index.js"
+    },
+    {
+      "packageName": "@elevasis/ui",
+      "packageDir": "packages/ui",
+      "subpath": "./hooks/operations/command-view/utils/transformCommandViewData",
+      "kind": "subpath",
+      "title": "Transform Command View Data",
+      "description": "Utility that transforms backend CommandViewData arrays into a unified frontend CommandViewGraph with nodes and edges.",
+      "group": "Hooks",
+      "order": 3,
+      "sourcePath": "packages/ui/src/hooks/operations/command-view/utils/transformCommandViewData.ts",
+      "docPath": "packages/ui/src/hooks/README.md",
+      "referencePath": "packages/ui/src/hooks/README.md",
+      "publishedExportPath": "./dist/hooks/operations/command-view/utils/transformCommandViewData.js"
+    },
     {
       "packageName": "@elevasis/ui",
       "packageDir": "packages/ui",
@@ -477,6 +533,20 @@
       "referencePath": "packages/ui/src/provider/README.md",
       "publishedExportPath": "./dist/provider/index.js"
     },
+    {
+      "packageName": "@elevasis/ui",
+      "packageDir": "packages/ui",
+      "subpath": "./provider/ElevasisServiceContext",
+      "kind": "subpath",
+      "title": "Elevasis Service Context",
+      "description": "Standalone service context and provider that supplies apiRequest, organizationId, and isReady to child components.",
+      "group": "Provider",
+      "order": 3,
+      "sourcePath": "packages/ui/src/provider/ElevasisServiceContext.tsx",
+      "docPath": "packages/ui/src/provider/README.md",
+      "referencePath": "packages/ui/src/provider/README.md",
+      "publishedExportPath": "./dist/provider/ElevasisServiceContext.js"
+    },
     {
       "packageName": "@elevasis/ui",
       "packageDir": "packages/ui",

package/reference/claude-config/commands/submit-issue.md

@@ -0,0 +1,11 @@
+# Submit Issue
+
+**Usage:** `/submit-issue [optional one-line description]`
+
+**Goal:** File a structured issue report to the Elevasis platform after agent-driven pre-analysis.
+
+**EXECUTE:** `.claude/skills/submit-issue/SKILL.md`
+
+## Env Requirements
+
+- `ELEVASIS_PLATFORM_KEY` (same key used by all `elevasis-sdk` commands — no extra setup if deploy already works)

package/reference/claude-config/hooks/post-edit-validate.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// post-edit-validate.mjs
+// PostToolUse hook — auto-formats with prettier, type-checks .ts/.tsx files.
+// Fires after Edit|Write|MultiEdit succeeds.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve, normalize, extname, join, dirname, relative } from 'node:path'
+import { execSync } from 'node:child_process'
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
+
+// Extensions prettier should format
+const PRETTIER_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json', '.css', '.md'])
+
+// Extensions that trigger type-checking
+const TS_EXTENSIONS = new Set(['.ts', '.tsx'])
+
+function findNearestTsconfig(startDir) {
+  let dir = startDir
+  const root = normalize(ROOT)
+  while (dir.length >= root.length) {
+    const candidate = join(dir, 'tsconfig.json')
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+try {
+  const chunks = []
+  for await (const chunk of process.stdin) chunks.push(chunk)
+  const input = JSON.parse(Buffer.concat(chunks).toString())
+
+  const filePath = input.tool_input?.file_path
+  if (!filePath) process.exit(0)
+
+  const ext = extname(filePath).toLowerCase()
+  const absPath = normalize(resolve(filePath))
+  if (!existsSync(absPath)) process.exit(0)
+
+  const results = []
+
+  // 0. Frontmatter check for docs/*.md (except docs/index.md which is auto-generated)
+  const docsDir = normalize(join(ROOT, 'docs'))
+  const indexPath = normalize(join(docsDir, 'index.md'))
+  if (ext === '.md' && absPath.startsWith(docsDir) && absPath !== indexPath) {
+    const content = readFileSync(absPath, 'utf-8')
+    if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) {
+      const rel = relative(ROOT, absPath).replace(/\\/g, '/')
+      results.push(`Missing frontmatter in ${rel}. All docs require:\n---\ntitle: ...\ndescription: ...\n---`)
+    }
+  }
+
+  // 1. Prettier (skip silently if not installed yet, e.g. before first pnpm install)
+  if (PRETTIER_EXTENSIONS.has(ext)) {
+    try {
+      execSync('pnpm exec prettier --version', { cwd: ROOT, stdio: 'pipe', timeout: 5_000 })
+      try {
+        execSync('pnpm exec prettier --write "' + absPath + '"', {
+          cwd: ROOT,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          timeout: 10_000
+        })
+      } catch (err) {
+        const stderr = err.stderr?.toString().trim() || ''
+        if (stderr && !/ignored/i.test(stderr)) {
+          results.push('Prettier error: ' + stderr.slice(0, 300))
+        }
+      }
+    } catch {
+      // prettier not installed yet -- skip silently
+    }
+  }
+
+  // 2. Type-check for .ts/.tsx
+  if (TS_EXTENSIONS.has(ext)) {
+    const tsconfig = findNearestTsconfig(dirname(absPath))
+    if (tsconfig) {
+      try {
+        execSync('pnpm exec tsc --noEmit -p "' + tsconfig + '"', {
+          cwd: ROOT,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          timeout: 30_000,
+          env: { ...process.env, NODE_OPTIONS: '--max-old-space-size=4096' }
+        })
+      } catch (err) {
+        if (err.killed) process.exit(0) // Don't block on timeout
+        const stdout = err.stdout?.toString() || ''
+        if (stdout.includes('error TS')) {
+          const errorLines = stdout
+            .split('\n')
+            .filter((l) => l.includes('error TS'))
+            .slice(0, 10)
+          results.push('Type errors after editing ' + filePath + ':\n' + errorLines.join('\n'))
+        }
+      }
+    }
+  }
+
+  // Output errors to Claude's context (silence = success)
+  if (results.length > 0) {
+    process.stderr.write(results.join('\n\n'))
+    process.exit(2) // Exit 2 = send stderr as feedback to Claude
+  }
+} catch {}
+
+process.exit(0)

package/reference/claude-config/hooks/tool-failure-recovery.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// tool-failure-recovery.mjs
+// PostToolUseFailure hook — pattern-matches known Bash errors and returns
+// recovery advice via stderr + exit 2 (feedback to Claude).
+
+const RECOVERY_TABLE = [
+  {
+    test: (r) => /JavaScript heap out of memory/i.test(r),
+    advice: 'Out of memory.',
+    fix: 'Run the command with NODE_OPTIONS="--max-old-space-size=4096".',
+    why: 'Large TypeScript projects can exceed Node default heap limit.'
+  },
+  {
+    test: (r) => /ENOENT/.test(r) && /node_modules/.test(r),
+    advice: 'Missing node_modules dependency.',
+    fix: 'Run: pnpm install',
+    why: 'Dependencies are not installed or were cleared.'
+  },
+  {
+    test: (r) => /ERR_MODULE_NOT_FOUND/.test(r),
+    advice: 'Module not found at import path.',
+    fix: 'Check the import path and verify the package is installed (pnpm install).',
+    why: 'The import path does not match any installed package or local file.'
+  },
+  {
+    test: (r) => /TS2307/.test(r) || (/cannot find/i.test(r) && /declaration/i.test(r)),
+    advice: 'TypeScript cannot resolve module or declaration file.',
+    fix: 'Check that the package is installed and tsconfig paths are correct.',
+    why: 'Missing dependency or incorrect TypeScript configuration.'
+  },
+  {
+    test: (r) => /EPERM/.test(r) || /permission denied/i.test(r),
+    advice: 'Permission denied (EPERM).',
+    fix: 'Close the file in any other process (editor, terminal, or dev server) and retry.',
+    why: 'On Windows, files locked by another process cannot be written to.'
+  },
+  {
+    test: (r) => /lockfile/i.test(r) && /conflict|outdated|ERR_PNPM/i.test(r),
+    advice: 'pnpm lockfile conflict or outdated.',
+    fix: 'Run: pnpm install to regenerate the lockfile.',
+    why: 'The lockfile is out of sync with package.json changes.'
+  },
+  {
+    test: (r) => /EADDRINUSE/.test(r),
+    advice: 'Port already in use.',
+    fix: 'Find and kill the process using the port, or use a different port.',
+    why: 'A previous dev server or process is still holding the port.'
+  }
+]
+
+function formatRecovery(entry) {
+  let msg = 'FAILED: ' + entry.advice + '\nFIX: ' + entry.fix
+  if (entry.why) msg += '\nWHY: ' + entry.why
+  if (entry.see) msg += '\nSEE: ' + entry.see
+  return msg
+}
+
+try {
+  const chunks = []
+  for await (const chunk of process.stdin) chunks.push(chunk)
+  const input = JSON.parse(Buffer.concat(chunks).toString())
+
+  const response = input.tool_response ?? ''
+
+  for (const entry of RECOVERY_TABLE) {
+    if (entry.test(response)) {
+      process.stderr.write(formatRecovery(entry))
+      process.exit(2)
+    }
+  }
+} catch {}
+
+process.exit(0)

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

@@ -0,0 +1,57 @@
+---
+description: Deployment workflow -- check-first, dev vs prod, version bumping, common errors
+paths:
+  - operations/**
+---
+
+# 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 resourceIds, 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, Zod schemas (converted to JSON Schema), relationships, triggers.
+3. **Docs:** All `.md` and `.mdx` files in `docs/` (max 100KB per file, 1MB total). The SDK scans the directory configured as `docsDir` in `elevasis.config.ts` (defaults to `docs/`, set to `../docs/` in this template). Two auto-generated files are regenerated by `/deploy` and `/elevasis deploy` before upload: `docs/index.md` (navigation hub) and `docs/resources.md` (platform resource inventory).
+
+## 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`                  | Rename `resourceId` in the conflicting resource         |
+| `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.