@elevasis/sdk 0.4.8 → 0.4.10

package/reference/deployment/command-view.mdx

@@ -0,0 +1,154 @@
+---
+title: Command View
+description: How the Command View graph works -- node types, relationships, what is enforced vs decorative, and what the platform needs to render your resource graph
+loadWhen: "Deploying resources or building resources that invoke other resources"
+---
+
+The Command View is a visual graph in the Elevasis command center that shows how your organization's resources connect. Nodes are resources (workflows, agents, integrations). Edges are relationships you declare between them. The graph helps operators understand how automation flows through the system at a glance.
+
+---
+
+## Node Types
+
+Every resource you deploy becomes a node in the Command View. Some nodes are executable (the platform runs them); others are visual-only (they exist for the graph but have no runtime behavior).
+
+### Executable Nodes
+
+| Type | What It Does | Deployed By |
+| ---- | ------------ | ----------- |
+| Workflow | Runs step handlers in sequence or branching paths | `elevasis deploy` |
+| Agent | Autonomous LLM-powered resource with tools | `elevasis deploy` |
+
+### Visual-Only Nodes
+
+These exist solely for the Command View graph. They have no runtime behavior -- the platform does not execute them.
+
+| Type | What It Represents | Why It Exists |
+| ---- | ------------------ | ------------- |
+| Trigger | A webhook or schedule that starts a workflow | Shows how executions begin |
+| Integration | A credential reference (provider + credential name) | Shows which external services a resource uses |
+| External Resource | A third-party automation (n8n, Make, Zapier) | Documents automations outside the platform |
+| Human Checkpoint | A point where a human makes a decision | Shows where HITL approval gates exist |
+
+Visual-only nodes are declarations. A `TriggerDefinition` does not set up actual trigger routing -- the webhook gateway routes independently. An `IntegrationDefinition` does not configure or connect to anything -- it is a visual node referencing a credential.
+
+---
+
+## Relationships
+
+Relationships are edges in the Command View graph. You declare them in `OrganizationResources` to tell the platform how resources connect.
+
+### Declaring Relationships
+
+```typescript
+const org: OrganizationResources = {
+  workflows: {
+    'score-lead': scoreLeadWorkflow,
+    'send-proposal': sendProposalWorkflow,
+  },
+  agents: {
+    'research-agent': researchAgent,
+  },
+  relationships: {
+    'score-lead': {
+      triggers: {
+        workflows: ['send-proposal'],  // score-lead triggers send-proposal
+        agents: ['research-agent'],     // score-lead triggers research-agent
+      },
+      uses: {
+        integrations: ['attio-integration'],  // score-lead uses Attio
+      },
+    },
+  },
+};
+```
+
+### Relationship Fields
+
+| Field | Type | Meaning |
+| ----- | ---- | ------- |
+| `triggers.workflows` | `string[]` | Workflows this resource starts |
+| `triggers.agents` | `string[]` | Agents this resource starts |
+| `uses.integrations` | `string[]` | Integrations this resource depends on |
+
+All referenced IDs must exist in the same organization. Missing targets cause a validation error at deploy time.
+
+### Relationships Are Declarations, Not Routing
+
+Relationships tell the Command View what edges to draw. They do **not** create execution paths. If you declare that workflow A triggers workflow B, the platform does not automatically route A's output to B. Your handler code must explicitly invoke B using the `execution` adapter or `platform.call()`.
+
+This means the graph can drift from reality:
+
+- If your code invokes resource B but you forgot to declare the relationship, the edge is **missing** from the graph
+- If you declared a relationship to resource B but your code never invokes it, the edge is **stale** in the graph
+
+---
+
+## What Is Enforced vs Decorative
+
+| Category | Validated at Deploy | Matches Runtime | Status |
+| -------- | ------------------- | --------------- | ------ |
+| Resource IDs unique | Yes | Yes | **Enforced** |
+| Input schema matches execution interface | Yes | Yes | **Enforced** |
+| Relationship targets exist | Yes | No -- invocations are hardcoded strings in handlers | **Decorative** |
+| Trigger routing | No | No -- webhook handlers route independently | **Decorative** |
+| Tool availability per agent | No | No -- tools built dynamically at runtime | **Decorative** |
+| Model config | Yes (provider + model valid) | No -- runtime uses environment config | **Decorative** |
+| Integration usage | Partial (IDs checked) | No -- credentials resolved at runtime | **Decorative** |
+
+**Enforced** means the platform rejects invalid state. **Decorative** means the platform trusts your declaration but does not verify it matches what the code actually does.
+
+### What This Means for You
+
+- Keep relationships in sync with your handler code. When you add an `execution.trigger('other-resource')` call, add the corresponding relationship declaration.
+- When you remove an invocation, remove the relationship.
+- The Command View is only as accurate as your declarations.
+
+---
+
+## Deploy-Time Validation
+
+When you run `elevasis deploy` or `elevasis check`, the SDK validates your resource definitions locally using the same `ResourceRegistry` the platform uses.
+
+### What Gets Checked
+
+- **Duplicate resource IDs** -- two resources with the same key in `workflows` or `agents`
+- **Relationship targets exist** -- every ID in `triggers` and `uses` must match a resource or integration in the same `OrganizationResources`
+- **Model configuration** -- agent model params (provider, model name, temperature bounds) are valid
+- **Step chains** -- `next.target` values in multi-step workflows point to existing step names
+
+### What Does Not Get Checked
+
+- Whether your handler code actually invokes the resources you declared in relationships
+- Whether your handler code invokes resources you did **not** declare in relationships
+- Whether triggers route to the workflows you declared
+- Whether agents use the tools you expect
+
+These are the decorative gaps listed above. The graph is a best-effort representation that depends on you keeping declarations in sync with code.
+
+### Validation Error Examples
+
+```
+ERROR  Relationship target 'send-proposal' not found in organization resources
+  Resource: score-lead
+  Field: relationships.triggers.workflows
+
+ERROR  Duplicate resource ID 'score-lead' in organization
+```
+
+Fix relationship errors by checking that the target resource ID is spelled correctly and exists in your `OrganizationResources` export. If the resource was renamed or removed, update the relationship to match.
+
+---
+
+## Graph Serialization
+
+The platform converts your resource definitions and relationships into a visual graph using two data structures:
+
+- **`CommandViewNode`** -- one per resource (workflow, agent, trigger, integration, etc.). Contains the resource ID, type, name, status, and metadata.
+- **`CommandViewEdge`** -- one per relationship. Contains source node, target node, and edge type (triggers, uses).
+
+The `buildEdges()` function in the platform registry reads your `relationships` declarations and produces `CommandViewEdge[]`. This is a pure transformation -- it does not add or remove edges based on runtime behavior.
+
+---
+
+**Last Updated:** 2026-03-02

package/reference/framework/index.mdx

@@ -92,4 +92,4 @@ The Growth Log in `memory/profile/skills.md` keeps approximately 20 recent entri
 
 ---
 
-**Last Updated:** 2026-02-25
+**Last Updated:** 2026-02-27

package/reference/framework/project-structure.mdx

@@ -12,23 +12,39 @@ loadWhen: "Understanding scaffolded files or project layout"
 
 ### `src/index.ts`
 
-The registry entry point for your workspace. This file imports and re-exports all resources from `src/workflows/` as an `OrganizationResources` default export. It does not contain workflow logic itself -- its sole job is aggregation:
+The registry entry point for your workspace. This file aggregates resources from domain barrel files and re-exports them as an `OrganizationResources` default export. It does not contain workflow logic itself -- its sole job is aggregation:
 
 ```ts
 import type { OrganizationResources } from '@elevasis/sdk'
-import { echo } from './workflows/echo.js'
+import * as operations from './operations/index.js'
+import * as example from './example/index.js'
 
 const org: OrganizationResources = {
-  workflows: [echo],
+  workflows: [
+    ...operations.workflows,
+    ...example.workflows,
+  ],
+  agents: [
+    ...operations.agents,
+    ...example.agents,
+  ],
 }
 export default org
 ```
 
-Every resource you add is wired into this file. The `/resource workflow` command updates it automatically.
+Each domain directory exports `workflows` and `agents` arrays via an `index.ts` barrel. When you add a new domain, import it here and spread its arrays. The `/resource workflow` command updates the appropriate domain barrel automatically.
 
-### `src/workflows/echo.ts`
+### `src/operations/platform-status.ts`
 
-The starter workflow, scaffolded to demonstrate the per-file pattern: one workflow per file with its own Zod input/output schemas, config object, contract, and step handler. When you add new workflows, each one gets its own file in `src/workflows/` and is imported into `src/index.ts`.
+A multi-step workflow demonstrating real platform API usage. Calls `platform.call({ tool: 'status', method: 'overview' })` to gather platform status data, then passes it to `platform.call({ tool: 'llm', method: 'generate' })` for a natural language summary. Shows the pattern for workflows that interact with platform tools and chain steps with `StepType.LINEAR`.
+
+### `src/example/echo.ts`
+
+The starter workflow, scaffolded to demonstrate the per-file pattern: one workflow per file with its own Zod input/output schemas, config object, contract, and step handler. Replace this domain with your own when you're ready.
+
+### `src/shared/`
+
+Cross-domain shared types and utilities. This directory starts empty (`.gitkeep`). Place code here when two or more domains share the same utility -- for example, formatters, shared types, or notification helpers. Domain-specific shared code goes in `<domain>/shared/` instead.
 
 ### `elevasis.config.ts`
 
@@ -38,7 +54,7 @@ Project-level configuration. The scaffolded file includes `templateVersion`, whi
 import type { ElevasConfig } from '@elevasis/sdk'
 
 export default {
-  templateVersion: 4,
+  templateVersion: 5,
   // defaultStatus: 'dev',     // Default status for new resources ('dev' | 'production')
   // dev: { port: 5170 },      // Local API port (internal development only)
 } satisfies ElevasConfig
@@ -92,7 +108,9 @@ Only `src/` and `docs/` are scaffolded by `elevasis init`. The following directo
 
 | Directory | Created by | When |
 |-----------|-----------|------|
-| `src/workflows/` | `elevasis init` (default) | Always -- starter workflow `echo.ts` lives here |
+| `src/operations/` | `elevasis init` (default) | Always -- platform-status workflow lives here |
+| `src/example/` | `elevasis init` (default) | Always -- echo starter workflow lives here (replace with your own) |
+| `src/shared/` | `elevasis init` (default) | Always -- cross-domain shared utilities (starts empty) |
 | `docs/` | `elevasis init` (default) | Always |
 | `docs/in-progress/` | Agent (on first `/docs checkpoint`) | When you save work-in-progress across sessions |
 | `docs/navigation.mdx` | Agent (on first `/meta deploy`) | Auto-generated and updated on each deploy |
@@ -105,7 +123,7 @@ This structure keeps the initial workspace minimal and adds directories only whe
 
 ### `src/lib/`
 
-Shared TypeScript utilities, types, and helpers used by multiple workflows. The agent creates this directory when you have code shared between two or more workflow files -- for example, retry logic, formatters, or shared types. Included in the esbuild bundle alongside workflow code. Not scaffolded by default to avoid premature abstraction.
+Legacy shared code directory. In v5+ projects, use `src/shared/` for cross-domain utilities instead. The agent may still create `src/lib/` in older projects that predate the domain-based organization. Included in the esbuild bundle alongside workflow code.
 
 ### `data/`
 
@@ -250,7 +268,7 @@ Applies pre-built workflow templates to your workspace. Three operations:
 
 - **No arguments** -- List available template categories (Data Collection, Data Processing, Communication, CRM, Documents, AI, Scheduling)
 - **`<category>`** -- Show templates in a category with descriptions
-- **`apply <name>`** -- Generate a workflow from a template: writes to `src/workflows/`, wires into `src/index.ts`, prompts for credential setup if needed, and runs `elevasis check` to validate
+- **`apply <name>`** -- Generate a workflow from a template: writes to the appropriate domain directory, wires into the domain barrel, prompts for credential setup if needed, and runs `elevasis check` to validate
 
 Templates are documentation files bundled with the SDK, not rigid copy-paste code. The agent reads the template and generates a workflow adapted to your existing schemas, credentials, and naming conventions.
 
@@ -260,12 +278,13 @@ Templates are documentation files bundled with the SDK, not rigid copy-paste cod
 
 Not all scaffolded files participate in template updates. Files fall into two categories:
 
-**SCAFFOLD_FILES total: 23**
+**SCAFFOLD_FILES total: 27**
 
-**INIT_ONLY** (10 files) -- Written once during `elevasis init`, never updated by `elevasis update`:
+**INIT_ONLY** (14 files) -- Written once during `elevasis init`, never updated by `elevasis update`:
 - `package.json`, `pnpm-workspace.yaml`, `tsconfig.json`
 - `.env`, `.env.example`, `.npmrc`
-- `src/index.ts`, `src/workflows/echo.ts`, `docs/index.mdx`, `.claude/settings.json`
+- `src/index.ts`, `src/operations/platform-status.ts`, `src/operations/index.ts`, `src/example/echo.ts`, `src/example/index.ts`, `src/shared/.gitkeep`
+- `docs/index.mdx`, `docs/in-progress/.gitkeep`
 
 **MANAGED** (13 files) -- Written during `elevasis init` and checked/updatable by `elevasis update`:
 - `elevasis.config.ts`, `.gitignore`, `CLAUDE.md`, `docs/navigation.mdx`
@@ -280,7 +299,7 @@ Run `elevasis update` after installing a new SDK version to bring managed files
 | File | When You Edit It |
 |------|-----------------|
 | `src/index.ts` | Adding or removing resources (the `/resource` command does this automatically) |
-| `src/workflows/*.ts` | Writing and modifying workflow logic |
+| `src/<domain>/*.ts` | Writing and modifying workflow logic (organized by business domain) |
 | `docs/index.mdx` | Updating project documentation |
 | `docs/navigation.mdx` | Never -- auto-generated by `/meta deploy` |
 | `docs/priorities.mdx` | When goals or priorities change |
@@ -291,4 +310,4 @@ Run `elevasis update` after installing a new SDK version to bring managed files
 
 ---
 
-**Last Updated:** 2026-02-26
+**Last Updated:** 2026-02-27

package/reference/getting-started/index.mdx

@@ -29,7 +29,7 @@ elevasis init my-project
 cd my-project
 ```
 
-The command scaffolds 23 files covering configuration, source, documentation, and Claude Code integration:
+The command scaffolds 27 files covering configuration, source, documentation, and Claude Code integration:
 
 ```
 my-project/
@@ -47,9 +47,15 @@ my-project/
 │       ├── tutorial.md             # Progressive learning
 │       └── profile.md              # View and update user profile
 ├── src/
-│   ├── index.ts                    # Registry entry point
-│   └── workflows/
-│       └── echo.ts                 # Starter workflow
+│   ├── index.ts                    # Registry entry point (aggregates domain barrels)
+│   ├── operations/
+│   │   ├── index.ts                # Domain barrel (exports workflows + agents)
+│   │   └── platform-status.ts     # Platform status workflow (real API example)
+│   ├── example/
+│   │   ├── index.ts                # Domain barrel (exports workflows + agents)
+│   │   └── echo.ts                 # Starter workflow (replace with your own)
+│   └── shared/
+│       └── .gitkeep                # Cross-domain shared utilities
 ├── docs/
 │   ├── index.mdx                   # Starter documentation page
 │   └── in-progress/
@@ -70,7 +76,7 @@ The scaffolded `elevasis.config.ts` includes a `templateVersion` field that trac
 import type { ElevasConfig } from '@elevasis/sdk'
 
 export default {
-  templateVersion: 4,
+  templateVersion: 5,
 } satisfies ElevasConfig
 ```
 
@@ -145,4 +151,4 @@ When a new SDK version is released, run `elevasis update` to bring your project'
 
 ---
 
-**Last Updated:** 2026-02-25
+**Last Updated:** 2026-02-27