@elevasis/sdk 1.21.0 → 1.22.1

package/reference/spine/spine-primer.md

@@ -1,99 +1,99 @@
----
-title: Spine Primer
-description: Tenant-facing primer for using an Organization Model catalog as the shared coordination spine between workflow producers, runtime state, API filters, and UI projections.
----
+---
+title: Spine Primer
+description: Tenant-facing primer for using an Organization Model catalog as the shared coordination spine between workflow producers, runtime state, API filters, and UI projections.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-# Spine Primer
-
-Use this primer when a tenant domain has a closed set of stages, statuses, or catalog keys that multiple surfaces must share. A spine is the tenant Organization Model vocabulary that coordinates workflows, runtime state, API reads, and UI rendering without forcing those surfaces to import from each other.
-
-The lead-generation pattern is the reference shape: `organizationModel.prospecting.stages` defines the stage vocabulary, workflow templates reference those stages, workflow factories validate stage keys before running, entity state stores sparse per-stage progress, and UI views render progress from the same vocabulary.
-
-## What The Spine Owns
-
-A spine owns the shared vocabulary for one domain. The vocabulary is not just a list of strings. Each key should carry enough metadata for consumers to derive behavior consistently:
-
-- `key` identifies the stage or catalog member.
-- `label` gives a human-readable name.
-- `description` explains the business meaning.
-- `order` gives stable display and workflow ordering.
-- `entity` identifies which tenant entity the stage updates.
-
-The same keys then appear in four places:
-
-| Role | Tenant-facing shape |
-| --- | --- |
-| Vocabulary | `organizationModel.prospecting.stages` |
-| Process | workflow templates and build steps that reference stage keys |
-| Runtime state | entity state maps such as `{ [stageKey]: { status, updatedAt, data } }` |
-| Consumer projection | API filters, progress summaries, and UI step rendering |
-
-## Layering
-
-```text
-tenant Organization Model
-- prospecting stages
-- workflow templates
-- capability bindings
-        |
-        +--> workflow factory
-        |    - validates stage keys
-        |    - runs producers
-        |    - dispatches entity-tagged results
-        |
-        +--> API and query helpers
-        |    - filter pending entities by stage key
-        |    - aggregate progress from state maps
-        |
-        +--> UI projections
-             - render labels and order from the catalog
-             - distinguish known and unknown state keys
-
-entity runtime state
-{ [stageKey]: { status, updatedAt, data } }
-```
-
-The important boundary is that producers and consumers coordinate through the Organization Model vocabulary plus runtime state. They do not coordinate through direct imports, duplicated string constants, or workflow-specific side channels.
-
-## Invariants
-
-1. **The vocabulary is closed and validated.** Workflow factories should reject stage keys that are not present in the tenant Organization Model.
-
-2. **The vocabulary carries metadata.** Labels, descriptions, ordering, and entity ownership should come from the catalog rather than being copied into each consumer.
-
-3. **Runtime state is sparse and additive.** New stages appear in entity state when reached. Adding a catalog member should not require backfilling every entity.
-
-4. **Producers return entity-tagged results.** Workflow steps should return which entity changed, its identifier, status, and optional data. The factory owns writing those results to the correct state map.
-
-5. **Capability binding is separate from stage naming.** Workflow templates should point at capability keys, and the tenant environment can bind those capabilities to concrete workflow resources.
-
-## Applying The Pattern
-
-Use this checklist when adding or changing a tenant domain spine:
-
-1. Define the domain catalog in the tenant Organization Model.
-2. Include labels, descriptions, ordering, and entity ownership in each catalog entry.
-3. Make workflow templates reference catalog keys instead of free-form strings.
-4. Validate template stage keys when constructing workflow factories.
-5. Store progress in sparse entity state maps keyed by catalog member.
-6. Return entity-tagged workflow results and let the factory dispatch state updates.
-7. Read progress through query helpers that use the same catalog keys.
-8. Render UI labels, order, and status from the catalog plus state map.
-
-Promote a vocabulary to a spine when the same catalog coordinates all three surfaces: at least one process definition, at least one workflow producer, and at least one independent consumer such as an API query or UI view.
-
-## Counter-Patterns
-
-Avoid these patterns in spine-governed domains:
-
-- Free-form stage strings in workflow inputs.
-- Duplicated UI-only labels or ordering.
-- Per-workflow skip logic that bypasses the shared pending and progress contract.
-- State writes from individual steps instead of the workflow factory.
-- Hidden side channels for progress, such as ad hoc context keys.
-- Direct coupling between producer code and consumer UI code.
-
-When in doubt, update the Organization Model vocabulary first, then let workflow templates, factories, queries, and views project from it.
+
+# Spine Primer
+
+Use this primer when a tenant domain has a closed set of stages, statuses, or catalog keys that multiple surfaces must share. A spine is the tenant Organization Model vocabulary that coordinates workflows, runtime state, API reads, and UI rendering without forcing those surfaces to import from each other.
+
+The lead-generation pattern is the reference shape: `organizationModel.prospecting.stages` defines the stage vocabulary, workflow templates reference those stages, workflow factories validate stage keys before running, entity state stores sparse per-stage progress, and UI views render progress from the same vocabulary.
+
+## What The Spine Owns
+
+A spine owns the shared vocabulary for one domain. The vocabulary is not just a list of strings. Each key should carry enough metadata for consumers to derive behavior consistently:
+
+- `key` identifies the stage or catalog member.
+- `label` gives a human-readable name.
+- `description` explains the business meaning.
+- `order` gives stable display and workflow ordering.
+- `entity` identifies which tenant entity the stage updates.
+
+The same keys then appear in four places:
+
+| Role | Tenant-facing shape |
+| --- | --- |
+| Vocabulary | `organizationModel.prospecting.stages` |
+| Process | workflow templates and build steps that reference stage keys |
+| Runtime state | entity state maps such as `{ [stageKey]: { status, updatedAt, data } }` |
+| Consumer projection | API filters, progress summaries, and UI step rendering |
+
+## Layering
+
+```text
+tenant Organization Model
+- prospecting stages
+- workflow templates
+- capability bindings
+        |
+        +--> workflow factory
+        |    - validates stage keys
+        |    - runs producers
+        |    - dispatches entity-tagged results
+        |
+        +--> API and query helpers
+        |    - filter pending entities by stage key
+        |    - aggregate progress from state maps
+        |
+        +--> UI projections
+             - render labels and order from the catalog
+             - distinguish known and unknown state keys
+
+entity runtime state
+{ [stageKey]: { status, updatedAt, data } }
+```
+
+The important boundary is that producers and consumers coordinate through the Organization Model vocabulary plus runtime state. They do not coordinate through direct imports, duplicated string constants, or workflow-specific side channels.
+
+## Invariants
+
+1. **The vocabulary is closed and validated.** Workflow factories should reject stage keys that are not present in the tenant Organization Model.
+
+2. **The vocabulary carries metadata.** Labels, descriptions, ordering, and entity ownership should come from the catalog rather than being copied into each consumer.
+
+3. **Runtime state is sparse and additive.** New stages appear in entity state when reached. Adding a catalog member should not require backfilling every entity.
+
+4. **Producers return entity-tagged results.** Workflow steps should return which entity changed, its identifier, status, and optional data. The factory owns writing those results to the correct state map.
+
+5. **Capability binding is separate from stage naming.** Workflow templates should point at capability keys, and the tenant environment can bind those capabilities to concrete workflow resources.
+
+## Applying The Pattern
+
+Use this checklist when adding or changing a tenant domain spine:
+
+1. Define the domain catalog in the tenant Organization Model.
+2. Include labels, descriptions, ordering, and entity ownership in each catalog entry.
+3. Make workflow templates reference catalog keys instead of free-form strings.
+4. Validate template stage keys when constructing workflow factories.
+5. Store progress in sparse entity state maps keyed by catalog member.
+6. Return entity-tagged workflow results and let the factory dispatch state updates.
+7. Read progress through query helpers that use the same catalog keys.
+8. Render UI labels, order, and status from the catalog plus state map.
+
+Promote a vocabulary to a spine when the same catalog coordinates all three surfaces: at least one process definition, at least one workflow producer, and at least one independent consumer such as an API query or UI view.
+
+## Counter-Patterns
+
+Avoid these patterns in spine-governed domains:
+
+- Free-form stage strings in workflow inputs.
+- Duplicated UI-only labels or ordering.
+- Per-workflow skip logic that bypasses the shared pending and progress contract.
+- State writes from individual steps instead of the workflow factory.
+- Hidden side channels for progress, such as ad hoc context keys.
+- Direct coupling between producer code and consumer UI code.
+
+When in doubt, update the Organization Model vocabulary first, then let workflow templates, factories, queries, and views project from it.

package/reference/templates/index.mdx

@@ -1,47 +1,47 @@
----
-title: Templates
-description: Ready-to-use workflow templates for common automation patterns -- web scraping, data enrichment, email sending, lead scoring, PDF generation, text classification, and recurring jobs
----
-
-Templates are pre-built workflow definitions covering the most common SDK automation patterns. Each template includes a complete `WorkflowDefinition` with Zod schemas, step handlers, and real platform tool usage. Scaffold any template through Claude Code (`/work` then describe the template) or adapt the code manually.
-
-Templates follow the same `WorkflowDefinition` structure as any custom resource -- they are reference implementations, not a special feature. The patterns demonstrated (multi-step chains, LLM structured output, Supabase CRUD, scheduler setup) apply directly to custom workflows you build.
-
-All templates are available for any organization. Credentials specific to each template (Supabase, Resend, Apify, etc.) must be created in the command center before running the workflow.
-
-## Documentation
-
-### Data Collection & Processing
-
-- [Web Scraper](web-scraper.mdx) - Apify actor runs web scrape, stores structured results in Supabase table
-- [Data Enrichment](data-enrichment.mdx) - Reads Supabase records, enriches each with LLM, writes results back; supports batching
-
-### Communication & CRM
-
-- [Email Sender](email-sender.mdx) - Transactional email via Resend with plain text and HTML support, single or multiple recipients
-- [Lead Scorer](lead-scorer.mdx) - Multi-criteria LLM lead scoring with configurable rubric and Supabase result storage
-
-### Documents & AI
-
-- [PDF Generator](pdf-generator.mdx) - Renders structured data to PDF, uploads to platform storage, returns signed download URL
-- [Text Classifier](text-classifier.mdx) - Multi-label text classification via LLM structured output, configurable categories and confidence scoring
-
-### Scheduling
-
-- [Recurring Job](recurring-job.mdx) - Two-workflow setup pattern: a setup workflow creates the schedule, the job workflow runs on each trigger; uses idempotency keys for safe re-registration
-
-## Platform Tools Used
-
-| Template        | Platform Tools      | Credentials Needed              |
-| --------------- | ------------------- | ------------------------------- |
-| Web Scraper     | `apify`, `supabase` | `apify`, `my-database`          |
-| Data Enrichment | `llm`, `supabase`   | `my-database` (LLM server-side) |
-| Email Sender    | `resend`            | `my-resend`                     |
-| Lead Scorer     | `llm`, `supabase`   | `my-database` (LLM server-side) |
-| PDF Generator   | `pdf`, `storage`    | None (platform services)        |
-| Text Classifier | `llm`               | None (LLM server-side)          |
-| Recurring Job   | `scheduler`         | None (platform service)         |
-
----
-
-**Last Updated:** 2026-03-19
+---
+title: Templates
+description: Ready-to-use workflow templates for common automation patterns -- web scraping, data enrichment, email sending, lead scoring, PDF generation, text classification, and recurring jobs
+---
+
+Templates are pre-built workflow definitions covering the most common SDK automation patterns. Each template includes a complete `WorkflowDefinition` with Zod schemas, step handlers, and real platform tool usage. Scaffold any template through Claude Code (`/work` then describe the template) or adapt the code manually.
+
+Templates follow the same `WorkflowDefinition` structure as any custom resource -- they are reference implementations, not a special feature. The patterns demonstrated (multi-step chains, LLM structured output, Supabase CRUD, scheduler setup) apply directly to custom workflows you build.
+
+All templates are available for any organization. Credentials specific to each template (Supabase, Resend, Apify, etc.) must be created in the command center before running the workflow.
+
+## Documentation
+
+### Data Collection & Processing
+
+- [Web Scraper](web-scraper.mdx) - Apify actor runs web scrape, stores structured results in Supabase table
+- [Data Enrichment](data-enrichment.mdx) - Reads Supabase records, enriches each with LLM, writes results back; supports batching
+
+### Communication & CRM
+
+- [Email Sender](email-sender.mdx) - Transactional email via Resend with plain text and HTML support, single or multiple recipients
+- [Lead Scorer](lead-scorer.mdx) - Multi-criteria LLM lead scoring with configurable rubric and Supabase result storage
+
+### Documents & AI
+
+- [PDF Generator](pdf-generator.mdx) - Renders structured data to PDF, uploads to platform storage, returns signed download URL
+- [Text Classifier](text-classifier.mdx) - Multi-label text classification via LLM structured output, configurable categories and confidence scoring
+
+### Scheduling
+
+- [Recurring Job](recurring-job.mdx) - Two-workflow setup pattern: a setup workflow creates the schedule, the job workflow runs on each trigger; uses idempotency keys for safe re-registration
+
+## Platform Tools Used
+
+| Template        | Platform Tools      | Credentials Needed              |
+| --------------- | ------------------- | ------------------------------- |
+| Web Scraper     | `apify`, `supabase` | `apify`, `my-database`          |
+| Data Enrichment | `llm`, `supabase`   | `my-database` (LLM server-side) |
+| Email Sender    | `resend`            | `my-resend`                     |
+| Lead Scorer     | `llm`, `supabase`   | `my-database` (LLM server-side) |
+| PDF Generator   | `pdf`, `storage`    | None (platform services)        |
+| Text Classifier | `llm`               | None (LLM server-side)          |
+| Recurring Job   | `scheduler`         | None (platform service)         |
+
+---
+
+**Last Updated:** 2026-03-19