@elevasis/sdk 0.4.16 → 0.5.0

package/dist/templates.js

@@ -1,4 +1,6 @@
 // package.json
+
+// src/cli/commands/templates/core/workspace.ts
 function gitignoreTemplate(ctx = {}) {
   let content = `node_modules/
 .env
@@ -14,6 +16,8 @@ ui/dist/
   }
   return content;
 }
+
+// src/cli/commands/templates/core/claude.ts
 function claudeSettingsTemplate() {
   return JSON.stringify({ autoCompact: false }, null, 2) + "\n";
 }
@@ -67,7 +71,7 @@ proactivity -- to their assessed levels.
 | Error history | \`.claude/memory/errors/index.md\` | Debugging errors, checking past fixes |
 | Command View model | \`reference/deployment/command-view.mdx\` | Deploying or building resources that invoke other resources |
 | SDK error reference | \`reference/troubleshooting/common-errors.mdx\` | Unknown error not in workspace memory |
-| Project resource map | \`docs/navigation.mdx\` | Understanding what's deployed |
+| Project map | \`docs/project-map.mdx\` | Session start, project orientation |
 | Project priorities | \`docs/priorities.mdx\` | Deciding what to work on next |
 | User profile and skills | \`.claude/memory/profile/skills.md\` | Session start (mandatory) |
 | Cross-session memory | \`.claude/memory/index.md\` | Session start, recalling past context |${ctx.hasUI ? `
@@ -77,23 +81,19 @@ All \`reference/\` paths resolve to \`node_modules/@elevasis/sdk/reference/\`.
 
 ## Rules
 
-- All resource definitions must be in \`src/\` and exported via \`src/index.ts\`
-- Organize resources by business domain (e.g., src/operations/, src/acquisition/)
-- Each domain exports \`workflows\` and \`agents\` arrays via an index.ts barrel
-- src/shared/ is for cross-domain utilities; domain-specific shared code goes in <domain>/shared/
-- The default export must be an \`OrganizationResources\` object
-- Do not import from \`@repo/core\` -- use \`@elevasis/sdk\` types only
-- \`StepType\`, \`ExecutionError\`, \`ToolingError\` are runtime imports from \`'@elevasis/sdk'\`
-- \`platform\`, \`PlatformToolError\` are runtime imports from \`'@elevasis/sdk/worker'\`
-- \`.env\` is for CLI authentication only (\`ELEVASIS_API_KEY\`) -- never deployed, never in workers
-- Integration credentials are managed via the \`creds\` skill (auto-triggers when you mention credentials) or the Command Center UI
+SDK patterns (imports, source structure, platform tools) are auto-loaded from
+\`.claude/rules/sdk-patterns.md\`. Project-specific patterns live in
+\`.claude/rules/workspace-patterns.md\`.
+
 - Documentation goes in \`docs/\` as \`.mdx\` files
-- \`dist/\` is generated by deploy -- never commit it
-- \`resourceId\` must be lowercase with hyphens, unique per organization
-- When an error occurs, check \`.claude/memory/errors/\` first for past fixes.
-  If the error is new, check \`reference/troubleshooting/common-errors.mdx\`.
-  After resolving, record the error in \`memory/errors/\` with context and fix.
-  If an error recurs 3+ times, promote it to a rule in this section.${ctx.hasUI ? `
+
+### Error Handling
+
+When an error occurs:
+1. Check \`.claude/memory/errors/\` first for past fixes
+2. If new, check \`reference/troubleshooting/common-errors.mdx\`
+3. After resolving, record in \`memory/errors/\` with context and fix
+4. If an error recurs 3+ times, add a rule to \`.claude/rules/workspace-patterns.md\`${ctx.hasUI ? `
 
 ### UI App (\`ui/\`)
 
@@ -129,16 +129,10 @@ For detailed per-dimension adaptation rules, read
 
 | Command | Purpose |
 | --- | --- |
-| \`/meta\` | Project lifecycle: init, status, update, fix, deploy, health, develop |
+| \`/meta\` | Project lifecycle: init, status, fix, deploy, health |
 | \`/docs\` | Documentation lifecycle: create, review, verify |
-| \`/work\` | Task tracking: start, save, resume, done, list |
-| \`/database\` | Database operations: init, browse, query, schema, import |
-| \`/resource\` | Scaffold a new workflow or agent |
-| \`/templates\` | Discover and apply workflow templates |
-| \`/agent\` | Agent development (placeholder) |
+| \`/work\` | Task tracking: create, save, resume, complete |
 | \`/tutorial\` | Progressive learning path |
-| \`/help\` | Command tree and navigation map |
-| \`/profile\` | View and update developer profile |
 
 ## Skills
 
@@ -212,63 +206,6 @@ code (resource IDs, schema fields, platform tools used), and report
 discrepancies. Useful before \`/meta deploy\` to ensure docs are accurate.
 `;
 }
-function claudeResourceCommandTemplate() {
-  return `# /resource command
-
-You are a resource scaffolding assistant for this Elevasis workspace.
-
-## Context
-
-Read CLAUDE.md for navigation to SDK patterns (reference/resources/patterns.mdx).
-Read src/index.ts for the registry and domain directories for existing resources.
-
-Before suggesting tools, read \`.claude/memory/profile/identity.md\` if it exists
-to check the user's known integrations and suggest relevant platform tools.
-
-## Guided Mode
-
-Before any operation, check \`.claude/memory/profile/skills.md\`. If the user's
-programming level is \`none\` or \`minimal\`, or automation level is \`none\`,
-activate Guided Mode:
-
-1. Ask: "What does this workflow need to do?" -- let user describe in plain English
-2. Based on description, suggest a resourceId, input schema fields, output schema
-   fields, and whether platform tools are needed
-3. Show suggestions and ask for confirmation before generating code
-4. Generate the complete resource using the confirmed structure
-
-This wraps existing operations with conversational discovery for users who
-cannot specify schemas directly.
-
-## Operations
-
-**\`workflow <name>\`:** Create a new workflow in the appropriate domain directory (e.g., \`src/<domain>/<name>.ts\`) with:
-- Zod input/output schemas with \`z.infer\` type aliases
-- Config object (resourceId, name, type, description, version, status)
-- Contract with schemas
-- Step definition with handler
-- Add the import to \`src/index.ts\` registry
-
-**\`multi-step <name>\`:** Create a multi-step workflow with:
-- Multiple steps connected via StepType.LINEAR or StepType.CONDITIONAL
-- Import \`{ StepType }\` from '@elevasis/sdk' (runtime value, not type)
-- Each step has its own inputSchema/outputSchema
-- Linear: \`next: { type: StepType.LINEAR, target: 'step-two' }\`
-- Conditional: \`next: { type: StepType.CONDITIONAL, routes: [...], default: 'fallback' }\`
-- Last step: \`next: null\`
-- Add to \`src/index.ts\` registry
-
-**\`tool-step <name>\`:** Create a step that calls a platform tool:
-- Prefer typed adapters: \`import { createAttioAdapter, scheduler, llm } from '@elevasis/sdk/worker'\`
-- Integration tools: \`const attio = createAttioAdapter('cred'); await attio.listRecords({...})\`
-- Platform singletons: \`await scheduler.createSchedule({...})\`, \`await llm.generate({...})\`
-- Fallback for tools without adapters: \`await platform.call({ tool, method, params, credential })\`
-- Import \`{ PlatformToolError }\` from '@elevasis/sdk/worker' for error handling
-- Wrap in try/catch for PlatformToolError
-- Note: 60s timeout per call, credential required for integration tools
-- See reference/platform-tools/adapters.mdx for the full adapter API
-`;
-}
 function claudeTutorialCommandTemplate() {
   return `# /tutorial command
 
@@ -359,215 +296,6 @@ Store in \`.claude/memory/tutorial-progress.md\`:
 - Assessment Notes (bullet points)
 `;
 }
-function claudeHelpCommandTemplate() {
-  return `# /help command
-
-You are a navigation assistant for this Elevasis workspace.
-
-## Operations
-
-**\`/help\` (no args):** Display the full command tree:
-
-\`\`\`
-Available Commands:
-
-/meta            Project lifecycle
-  /meta init       First-run setup and onboarding
-  /meta status     Project health and template version
-  /meta update     SDK upgrade and template merge
-  /meta fix        Drift repair
-  /meta deploy     Full deploy pipeline (validate, git, deploy, verify)
-  /meta health     Execution debugging and resource status
-  /meta develop    Development navigation hub (resources, tools, examples)
-
-/docs            Documentation lifecycle
-  /docs            Show documentation status
-  /docs create     Create new documentation page
-  /docs review     Review docs for accuracy
-  /docs verify     Cross-reference docs with codebase for accuracy
-
-/work            Task tracking
-  /work            Show current tasks
-  /work start      Create new task
-  /work save       Save progress for session resume
-  /work resume     Resume in-progress work
-  /work done       Complete and move task
-  /work list       List all tasks with status
-
-/database        Database operations
-  /database init     Connect Supabase project
-  /database browse   Query and display table contents
-  /database query    Run filtered queries
-  /database schema   View/compare schema documentation
-  /database import   Import CSV/JSON data
-
-/resource        Scaffold a new workflow or agent
-/templates       Discover and apply workflow templates
-/agent           Agent development (placeholder)
-/tutorial        Progressive learning path
-/profile         View and update developer profile
-/help            This help menu
-
-Navigation:
-- docs/navigation.mdx     Resource and documentation map
-- docs/priorities.mdx      Current goals and priorities
-- memory/index.md          Cross-session knowledge
-\`\`\`
-
-**\`/help <command>\`:** Show detailed help for a specific command with its
-subcommands and usage examples. Read the corresponding command file at
-\`.claude/commands/<command>.md\` and present a summary.
-`;
-}
-function claudeTemplatesCommandTemplate() {
-  return `# /templates command
-
-You are a workflow template assistant for this Elevasis workspace.
-
-## Context
-
-Read \`reference/templates/\` in node_modules/@elevasis/sdk/reference/templates/
-for available template definitions. Read src/index.ts for the current registry.
-Read \`.claude/memory/profile/skills.md\` to adapt generated code to skill level.
-
-## Operations
-
-**\`/templates\` (no args):** Show available template categories:
-- Data Collection (web scraper, RSS feed reader, form handler)
-- Data Processing (CSV import, data enrichment, deduplication)
-- Communication (email sender, notification dispatcher)
-- CRM (contact sync, lead scoring, pipeline update)
-- Documents (PDF generator, report builder, invoice creator)
-- AI (text classifier, data extractor, summarizer)
-- Scheduling (recurring job, delayed task, batch processor)
-
-**\`/templates <category>\`:** Show templates in the category with descriptions.
-
-**\`/templates apply <name>\`:** Generate a workflow from the template:
-1. Read the template definition from reference/templates/<name>.mdx
-2. Generate a workflow file in the appropriate domain directory
-3. Add the import to src/index.ts registry
-4. If the template uses platform tools, prompt for credential setup
-5. If the template uses the database, check that /database init has been run
-6. Run \`elevasis check\` to validate
-
-Templates are documentation-based. The agent reads the template definition
-and generates context-aware code adapted to the user's existing schemas,
-credentials, skill level, and naming conventions.
-`;
-}
-function claudeDatabaseCommandTemplate() {
-  return `# /database command
-
-You are a database assistant for this Elevasis workspace.
-
-## Context
-
-Read \`data/schema.ts\` if it exists for the current schema documentation.
-Read \`.claude/memory/deployment-state.md\` for database connection status.
-Read \`.claude/memory/profile/skills.md\` to adapt explanations.
-
-## Operations
-
-**\`/database init\`:** Guide user through Supabase project setup:
-1. Explain Supabase (free, great dashboard, integrates with workflows)
-2. Walk through: create project at supabase.com/dashboard
-3. Collect Project URL and service_role key
-4. Store as platform credential named 'my-database' via command center
-5. Test connection
-6. Create data/schema.ts with initial table documentation
-7. Record database connection in memory/deployment-state.md
-
-**\`/database\` (no args):** Show database connection status, tables, row counts.
-
-**\`/database add <table>\`:** Create a migration script:
-1. Generate scripts/migrations/NNN-create-<table>.ts
-2. Show the script and explain each statement
-3. Confirm before execution
-4. Update data/schema.ts and docs/database.mdx
-
-**\`/database browse <table>\`:** Query and display table contents via CLI.
-
-**\`/database schema\`:** Show data/schema.ts contents, compare against live DB.
-
-**\`/database import <table> --file <path>\`:** Import CSV/JSON into a table.
-
-## Database Safety
-
-ALWAYS confirm with the user before:
-- DROP TABLE or DROP COLUMN operations
-- DELETE without a WHERE clause (bulk delete)
-- TRUNCATE operations
-- ALTER TABLE that removes columns
-- Any operation that cannot be undone
-
-For read operations and targeted writes (INSERT, UPDATE with WHERE),
-proceed normally.
-
-## Supabase Platform Tool
-
-Workflows access the database via platform.call({ tool: 'supabase', ... }).
-Methods: insert, select, update, delete, upsert, rpc, count.
-Filter syntax uses PostgREST format (eq, neq, gt, gte, lt, lte, like, ilike, in, is).
-`;
-}
-function claudeAgentCommandTemplate() {
-  return `# /agent command
-
-You are an agent development assistant for this Elevasis workspace.
-
-## Current State
-
-Agent definitions are accepted by the SDK and appear in the registry.
-Autonomous agent execution (multi-turn tool use loops) is deferred.
-LLM calls are available via the \`llm\` typed adapter: \`import { llm } from '@elevasis/sdk/worker'\`, then \`await llm.generate({ messages: [...] })\`.
-
-## Operations
-
-**\`/agent\` (no args):** Explain the current state:
-- Agent definitions are accepted by the SDK and appear in the registry
-- Autonomous agent execution (multi-turn tool use loops) is deferred
-- LLM calls are available via the \`llm\` typed adapter (\`import { llm } from '@elevasis/sdk/worker'\`)
-- Show the AgentDefinition pattern for future use
-
-**\`/agent scaffold <name>\`:** Create an agent definition with:
-- Config (resourceId, name, type, description, version, status)
-- System prompt
-- Available tools list
-- Note that execution will fail until agent runtime is implemented
-- Add to src/index.ts registry
-`;
-}
-function claudeProfileCommandTemplate() {
-  return `# /profile command
-
-You are a profile management assistant for this Elevasis workspace.
-
-## Context
-
-Read \`.claude/memory/profile/index.md\` to discover profile sub-files.
-Read the sub-files (identity.md, skills.md, preferences.md) to load the current profile.
-
-If \`.claude/memory/profile/\` does not exist, suggest running \`/meta init\` to create it.
-
-## Operations
-
-**No arguments (default):** Display the current profile in a readable format.
-Show organization, industry, experience level, goals, known integrations, and preferences.
-Ask if anything needs updating.
-
-**\`update\`:** Walk through each profile section, showing current values and
-asking if they should change. Only update fields the user wants to change.
-Write changes to the appropriate memory/profile/ file.
-
-**\`level\`:** Assess the user's current skill level based on their project
-history (resources created, successful deploys, error handling patterns).
-Suggest updating memory/profile/skills.md if the assessment differs from the stored level.
-
-**\`assess\`:** Re-run the competency assessment questions from /meta init.
-Update all skill dimensions in memory/profile/skills.md.
-`;
-}
 function claudeMetaCommandTemplate() {
   return `# /meta command
 
@@ -655,32 +383,35 @@ Display a project health summary:
 2. SDK package version from package.json
 3. Profile summary (from memory/profile/skills.md)
 4. Quick drift check: count of missing managed files, missing gitignore entries
+5. Last deployment status (from memory/deployment-state.md if it exists)
 
-### \`/meta update\` -- Full Upgrade
-
-Upgrade the SDK and merge template changes:
-
-1. Run \`pnpm update @elevasis/sdk\` to pull the latest SDK
-2. Run \`elevasis update\` to add missing files and flag conflicts
-3. For each flagged file in the output:
-   - Read the current project file
-   - Read the new template from \`@elevasis/sdk/templates\`
-   - Compare and merge intelligently:
-     - Add new sections that don't exist
-     - Preserve user customizations
-     - If a section differs, show both versions and let user choose
-4. Return a report of changes
-
-### \`/meta fix\` -- Fix Drift
+### \`/meta fix\` -- Maintenance and Upgrade
 
-Detect and repair drift without a version upgrade:
+Detect and repair all drift. Optionally upgrades the SDK first.
 
+0. **SDK version check** -- Compare installed \`@elevasis/sdk\` against the latest
+   available. If behind, offer to run \`pnpm update @elevasis/sdk\` before
+   continuing. If the user accepts, run it, then run \`elevasis update\` to add
+   any new managed files and flag conflicts. For each flagged file:
+   - Read the current project file and the new template from \`@elevasis/sdk/templates\`
+   - Add new sections that don't exist; preserve user customizations
+   - If a section differs, show both versions and let the user choose
 1. **Missing managed files:** Regenerate from templates
 2. **Gitignore drift:** Append missing entries
 3. **CLAUDE.md sections:** Add missing sections in correct position
 4. **Memory structure:** Verify index consistency
 5. **Doc cross-references:** Scan for broken links
 6. **Settings consistency:** Verify expected fields
+7. **Rules health:** Scan \`memory/errors/\` -- flag any entry that has recurred
+   3+ times and is not yet in \`.claude/rules/workspace-patterns.md\`.
+   If \`workspace-patterns.md\` has no rules yet and 5+ resources exist in \`src/\`,
+   suggest adding patterns. Surface suggestions only -- do not auto-generate.
+8. **Project map freshness:** Check whether \`docs/project-map.mdx\` reflects the
+   current project state (resources, commands, rules, skills, memory files).
+   Compare filesystem state against the map. If stale, run \`elevasis deploy\`
+   to regenerate, or patch inline for minor drift.
+
+Each step reports its result. Steps 1-8 run even if step 0 is skipped.
 
 ### \`/meta deploy\` -- Full Deploy Pipeline
 
@@ -692,7 +423,7 @@ Detect and repair drift without a version upgrade:
 3. Verify docs reflect current resources
 4. If git configured: stage changes, commit with deploy message
 5. Run \`elevasis deploy\`
-6. Bump deployment version in \`docs/navigation.mdx\` metadata
+6. \`docs/project-map.mdx\` is auto-regenerated by deploy (no manual bump needed)
 7. Verify deployment via platform
 8. Update \`memory/deployment-state.md\` with count, timestamp, inventory
 9. If git configured and remote exists: optionally push
@@ -703,29 +434,12 @@ for the enforcement model and common fixes.
 
 ### \`/meta health\` -- Execution Debugging
 
-Renamed from /inspect. Checks:
+Diagnose runtime failures and environment issues:
 - Show recent executions with status (completed/failed)
 - For failed executions: analyze logs, cross-reference with memory/errors/
 - Check resource deployment status (deployed, outdated, never deployed)
 - Verify environment: API key valid, credentials accessible, DB connected
 
-### \`/meta develop\` -- Development Navigation Hub
-
-Primary development entry point. Loads a navigation map and offers actions.
-
-1. **Project Resource Map** -- from docs/navigation.mdx. Shows deployed
-   resources: resourceId, name, status, tools used, last deployment.
-2. **Development Actions** -- contextual based on resource map:
-   - Edit/extend a workflow
-   - Test a workflow
-   - Debug a failed execution
-   - Browse platform tools (read reference/platform-tools/index.mdx)
-   - Set up credentials
-   - View examples (read reference/resources/patterns.mdx)
-3. **SDK Reference Navigation** -- pointers to reference files
-4. **Upkeep Detection** -- check navigation freshness, in-progress items,
-   pending priorities. Suggest /docs cleanup or /docs resume if needed.
-
 ## Merge Strategy
 
 - **CLAUDE.md:** Add new sections in correct position. Preserve customizations.
@@ -738,6 +452,8 @@ The agent reads current templates from the installed SDK:
 \`@elevasis/sdk/templates\` subpath exports all template functions.
 `;
 }
+
+// src/cli/commands/templates/core/resources.ts
 function starterWorkflowTemplate() {
   return `import type { WorkflowDefinition } from '@elevasis/sdk'
 import { z } from 'zod'
@@ -884,4 +600,4 @@ export const agents = []
 `;
 }
 
-export { claudeAgentCommandTemplate, claudeDatabaseCommandTemplate, claudeDocsCommandTemplate, claudeHelpCommandTemplate, claudeMdTemplate, claudeMetaCommandTemplate, claudeProfileCommandTemplate, claudeResourceCommandTemplate, claudeSettingsTemplate, claudeTemplatesCommandTemplate, claudeTutorialCommandTemplate, exampleBarrelTemplate, gitignoreTemplate, operationsBarrelTemplate, platformStatusTemplate, starterWorkflowTemplate };
+export { claudeDocsCommandTemplate, claudeMdTemplate, claudeMetaCommandTemplate, claudeSettingsTemplate, claudeTutorialCommandTemplate, exampleBarrelTemplate, gitignoreTemplate, operationsBarrelTemplate, platformStatusTemplate, starterWorkflowTemplate };

package/dist/types/templates.d.ts

@@ -1 +1 @@
-export { claudeMdTemplate, claudeMetaCommandTemplate, claudeProfileCommandTemplate, claudeDocsCommandTemplate, claudeResourceCommandTemplate, claudeTutorialCommandTemplate, claudeHelpCommandTemplate, claudeTemplatesCommandTemplate, claudeDatabaseCommandTemplate, claudeAgentCommandTemplate, gitignoreTemplate, claudeSettingsTemplate, starterWorkflowTemplate, platformStatusTemplate, operationsBarrelTemplate, exampleBarrelTemplate, } from './cli/commands/init.js';
+export { claudeMdTemplate, claudeMetaCommandTemplate, claudeDocsCommandTemplate, claudeTutorialCommandTemplate, gitignoreTemplate, claudeSettingsTemplate, starterWorkflowTemplate, platformStatusTemplate, operationsBarrelTemplate, exampleBarrelTemplate, } from './cli/commands/init.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "0.4.16",
+  "version": "0.5.0",
   "description": "SDK for building Elevasis organization resources",
   "comment:bin": "IMPORTANT: This package shares the 'elevasis' binary name with @repo/cli. They never conflict because @elevasis/sdk must NEVER be added as a dependency of any workspace package (apps/*, packages/*, organizations/*). Workspace projects use @repo/cli for the 'elevasis' binary. External developers (outside the workspace) get this SDK's binary via npm install.",
   "type": "module",
@@ -34,11 +34,6 @@
     "dist/types/templates.d.ts",
     "reference/"
   ],
-  "scripts": {
-    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.core-dts.json && tsc -p tsconfig.build.json && tsup && rollup -c rollup.dts.config.mjs && esbuild src/cli/index.ts --bundle --platform=node --outfile=dist/cli.cjs --format=cjs --external:esbuild --external:jiti --banner:js=\"#!/usr/bin/env node\" && node scripts/copy-reference-docs.mjs && node scripts/generate-navigation.mjs",
-    "check-types": "tsc --noEmit",
-    "test:bundle": "pnpm build && vitest run --config vitest.bundle.config.ts"
-  },
   "dependencies": {
     "esbuild": "^0.25.0",
     "jiti": "^2.0.0"
@@ -47,8 +42,6 @@
     "zod": "^4.1.0"
   },
   "devDependencies": {
-    "@repo/core": "workspace:*",
-    "@repo/typescript-config": "workspace:*",
     "@types/node": "^22.0.0",
     "chalk": "^5.3.0",
     "commander": "^11.0.0",
@@ -59,6 +52,13 @@
     "rollup-plugin-dts": "^6.3.0",
     "tsup": "^8.0.0",
     "typescript": "5.9.2",
-    "zod": "^4.1.0"
+    "zod": "^4.1.0",
+    "@repo/core": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.core-dts.json && tsc -p tsconfig.build.json && tsup && rollup -c rollup.dts.config.mjs && esbuild src/cli/index.ts --bundle --platform=node --outfile=dist/cli.cjs --format=cjs --external:esbuild --external:jiti --banner:js=\"#!/usr/bin/env node\" && node scripts/copy-reference-docs.mjs && node scripts/generate-navigation.mjs",
+    "check-types": "tsc --noEmit",
+    "test:bundle": "pnpm build && vitest run --config vitest.bundle.config.ts"
   }
-}
+}

package/reference/concepts/index.mdx

@@ -11,7 +11,7 @@ This page covers core Elevasis concepts in plain English. It is the teaching voc
 | Term | Definition |
 | --- | --- |
 | Workflow | A series of named steps that run one after another. Each step does one job. The workflow receives input data and produces output data. |
-| Agent | An autonomous AI resource with access to platform tools. Agents can make decisions and call tools on their own. (Execution deferred -- see Known Limitations in the SDK overview.) |
+| Agent | An autonomous AI resource with access to platform tools. Agents can make decisions and call tools on their own. Run agents with `--async` to avoid HTTP timeout limits on long-running executions. |
 | Resource | Anything you deploy to the platform -- a workflow or an agent. Each resource has a unique ID. |
 | Step | One job inside a workflow. A step receives data, processes it, and passes data to the next step. |
 | Schema | A description of what your data looks like. Schemas validate that input and output data has the right shape -- the right fields with the right types. |