lua-cli 3.29.1 → 3.31.0

package/docs/API_INDEX.md

@@ -11,6 +11,7 @@ Quick reference for all lua-cli APIs and exports.
 | [LuaTool](./api/LuaTool.md) | Individual tool interface | `import { LuaTool } from 'lua-cli/skill'` |
 | [LuaWebhook](./api/LuaWebhook.md) | HTTP webhook handler | `import { LuaWebhook } from 'lua-cli'` |
 | [LuaJob](./api/LuaJob.md) | Scheduled task | `import { LuaJob } from 'lua-cli'` |
+| [LuaWorkflow](./api/LuaWorkflow.md) | Durable multi-step workflow (`createStep`/`createWorkflow`) | `import { createWorkflow } from 'lua-cli'` |
 | [PreProcessor](./api/PreProcessor.md) | Message preprocessor | `import { PreProcessor } from 'lua-cli'` |
 | [PostProcessor](./api/PostProcessor.md) | Response postprocessor | `import { PostProcessor } from 'lua-cli'` |
 | LuaMCPServer | MCP server integration | `import { LuaMCPServer } from 'lua-cli'` |
@@ -20,6 +21,7 @@ Quick reference for all lua-cli APIs and exports.
 | API | Purpose | Methods |
 |-----|---------|---------|
 | [AI](./api/AI.md) | AI text generation | `generate()` |
+| [Workflows](./api/Workflows.md) | Workflow runs | `start()`, `get()`, `list()`, `cancel()`, `resume()`, `signal()` |
 | [User](./api/User.md) | User data management | `get()`, `getChatHistory()` |
 | [Products](./api/Products.md) | Product catalog | `get()`, `search()`, `getById()`, `create()`, `update()`, `delete()` |
 | [Baskets](./api/Baskets.md) | Shopping carts | `get()`, `create()`, `getById()`, `addItem()`, `clear()`, `placeOrder()` |

package/docs/README.md

@@ -1,10 +1,11 @@
-# lua-cli v3.29.1
+# lua-cli v3.31.0
 
-Welcome to the comprehensive API documentation for lua-cli v3.29.1. This guide covers every API, class, and function exported by the package.
+Welcome to the comprehensive API documentation for lua-cli v3.31.0. This guide covers every API, class, and function exported by the package.
 
 ## 📚 Documentation Index
 
 ### Core Primitives
+
 - [LuaAgent](./api/LuaAgent.md) - Unified agent configuration
 - [LuaSkill](./api/LuaSkill.md) - Tool collections
 - [LuaTool](./api/LuaTool.md) - Individual tools
@@ -16,6 +17,7 @@ Welcome to the comprehensive API documentation for lua-cli v3.29.1. This guide c
 - LuaDevice - Bidirectional device communication (send commands, receive triggers)
 
 ### Runtime APIs
+
 - [User API](./api/User.md) - User data management
 - [Products API](./api/Products.md) - Product catalog (with filter support)
 - [Data API](./api/Data.md) - Custom data storage with vector search
@@ -29,6 +31,7 @@ Welcome to the comprehensive API documentation for lua-cli v3.29.1. This guide c
 - Lua Runtime - Channel detection (`import { Lua } from 'lua-cli'`)
 
 ### Utilities
+
 - `env()` - Environment variable access (`import { env } from 'lua-cli'`)
 - `BasketStatus` - Basket state enum
 - `OrderStatus` - Order state enum
@@ -49,7 +52,7 @@ import {
   LuaJob,
   PreProcessor,
   PostProcessor,
-  
+
   // Runtime APIs
   User,
   Products,
@@ -58,7 +61,7 @@ import {
   Data,
   Jobs,
   Webhooks,
-  
+
   // Instances
   UserDataInstance,
   ProductInstance,
@@ -66,19 +69,20 @@ import {
   OrderInstance,
   DataEntryInstance,
   JobInstance,
-  
+
   // Enums
   BasketStatus,
   OrderStatus,
-  
+
   // Utilities
-  env
+  env,
 } from 'lua-cli';
 ```
 
 ### Common Patterns
 
 #### Create a Tool
+
 ```typescript
 import { LuaTool } from 'lua-cli/skill';
 import { z } from 'zod';
@@ -87,7 +91,7 @@ export default class MyTool implements LuaTool {
   name = 'my_tool';
   description = 'Tool description';
   inputSchema = z.object({ param: z.string() });
-  
+
   async execute(input: z.infer<typeof this.inputSchema>) {
     return { result: 'success' };
   }
@@ -95,17 +99,19 @@ export default class MyTool implements LuaTool {
 ```
 
 #### Create an Agent
+
 ```typescript
 import { LuaAgent, LuaSkill } from 'lua-cli';
 
 export const agent = new LuaAgent({
   name: 'my-agent',
   persona: 'Agent personality...',
-  skills: [skill1, skill2]
+  skills: [skill1, skill2],
 });
 ```
 
 #### Use Runtime APIs
+
 ```typescript
 import { User, Products, Data } from 'lua-cli';
 
@@ -119,6 +125,7 @@ await Data.create('notes', { text: 'Hello' });
 ## 📖 By Category
 
 ### For Building Agents
+
 - Start with [LuaAgent](./api/LuaAgent.md)
 - Learn about [LuaSkill](./api/LuaSkill.md)
 - Create [LuaTool](./api/LuaTool.md)
@@ -126,25 +133,30 @@ await Data.create('notes', { text: 'Hello' });
 - Schedule [LuaJob](./api/LuaJob.md) tasks
 
 ### For Data Management
+
 - [User API](./api/User.md) - User profiles
 - [Data API](./api/Data.md) - Custom collections
 - [Products API](./api/Products.md) - Product catalog
 
 ### For E-commerce
+
 - [Products API](./api/Products.md) - Product catalog
 - [Baskets API](./api/Baskets.md) - Shopping carts
 - [Orders API](./api/Orders.md) - Order fulfillment
 
 ### For Automation
+
 - [LuaJob](./api/LuaJob.md) - Scheduled tasks (cron, intervals)
 - [Jobs API](./api/Jobs.md) - Dynamic job creation from tools
 - [LuaWebhook](./api/LuaWebhook.md) - HTTP endpoints for external triggers
 
 ### For Message Processing
+
 - [PreProcessor](./api/PreProcessor.md) - Filter/modify incoming messages
 - [PostProcessor](./api/PostProcessor.md) - Format/enhance agent responses
 
 ### For Third-Party Integrations
+
 - `lua integrations` command - Connect accounts (Linear, Discord, Google Calendar, etc.)
 - Auto-creates MCP servers for connected integrations
 
@@ -153,16 +165,19 @@ await Data.create('notes', { text: 'Hello' });
 ## 🎯 Learning Path
 
 ### Beginner
+
 1. Read [LuaAgent](./api/LuaAgent.md) - Understand agent configuration
 2. Read [LuaTool](./api/LuaTool.md) - Learn to create tools
 3. Read [LuaSkill](./api/LuaSkill.md) - Organize tools into skills
 
 ### Intermediate
+
 1. [User API](./api/User.md) - Work with user data
 2. [Products API](./api/Products.md) - Manage products
 3. [Data API](./api/Data.md) - Use custom storage
 
 ### Advanced
+
 1. [LuaJob](./api/LuaJob.md) - Schedule automated tasks
 2. [Jobs API](./api/Jobs.md) - Create jobs dynamically
 3. [LuaWebhook](./api/LuaWebhook.md) - Build integrations
@@ -218,6 +233,7 @@ await Data.create('notes', { text: 'Hello' });
 ## 📝 Documentation Standards
 
 Each API doc includes:
+
 - ✅ Overview and purpose
 - ✅ Type definitions
 - ✅ Complete method reference
@@ -255,6 +271,7 @@ Each API doc includes:
 ## Additional Utilities
 
 ### Lua Runtime
+
 ```typescript
 import { Lua } from 'lua-cli';
 
@@ -264,6 +281,7 @@ if (Lua.request.channel === 'whatsapp') {
 ```
 
 ### env() Utility
+
 ```typescript
 import { env } from 'lua-cli';
 

package/docs/api/Jobs.md

@@ -53,7 +53,7 @@ const job = await Jobs.create({
 console.log('Job created:', job.id);
 ```
 
-### `Jobs.get(jobId)`
+### `Jobs.getJob(jobId)`
 
 Retrieves a job by ID.
 
@@ -64,7 +64,7 @@ Retrieves a job by ID.
 
 **Example:**
 ```typescript
-const job = await Jobs.get('job_123');
+const job = await Jobs.getJob('job_123');
 console.log(job.name);
 console.log(job.schedule);
 ```
@@ -85,7 +85,7 @@ interface JobConfig {
   /** When/how often to run */
   schedule: JobSchedule;
   
-  /** Maximum execution time in ms */
+  /** Maximum execution time in seconds (default 300, supported range: 1-600) */
   timeout?: number;
   
   /** Retry configuration */
@@ -133,7 +133,7 @@ schedule: {
 ```typescript
 schedule: {
   type: 'interval',
-  intervalSeconds: number  // Seconds between executions
+  seconds: number  // Seconds between executions
 }
 ```
 
@@ -142,13 +142,13 @@ schedule: {
 // Run every 5 minutes
 schedule: {
   type: 'interval',
-  intervalSeconds: 300
+  seconds: 300
 }
 
 // Run every hour
 schedule: {
   type: 'interval',
-  intervalSeconds: 3600
+  seconds: 3600
 }
 ```
 
@@ -157,7 +157,7 @@ schedule: {
 ```typescript
 schedule: {
   type: 'cron',
-  pattern: string  // Cron pattern
+  expression: string  // Cron expression
 }
 ```
 
@@ -166,19 +166,19 @@ schedule: {
 // Every day at 9 AM
 schedule: {
   type: 'cron',
-  pattern: '0 9 * * *'
+  expression: '0 9 * * *'
 }
 
 // Every Monday at 8 AM
 schedule: {
   type: 'cron',
-  pattern: '0 8 * * 1'
+  expression: '0 8 * * 1'
 }
 
 // Every 15 minutes
 schedule: {
   type: 'cron',
-  pattern: '*/15 * * * *'
+  expression: '*/15 * * * *'
 }
 ```
 

package/docs/api/LuaWorkflow.md

@@ -0,0 +1,73 @@
+# LuaWorkflow — `createStep` / `createWorkflow`
+
+The workflow primitive: a **durable, multi-step program** you author in TypeScript, compile with `lua compile`, and push with `lua push workflow`. The engine executes the compiled graph server-side — steps survive restarts, waits hold no compute, and approvals/signals park the run until a person or a webhook answers.
+
+> **Execution model — read this first.** *`execute` re-runs from the top after resume; execution is at-least-once — dedupe on `occurrenceId`.* `occurrenceId` is `${lineageId}:${stepId}` — the same key on retry, resume, `retry-step` and a repair run; an effect that must be unique across independent runs needs your own business key (`refund:${ticketId}`). Wrap external effects in `ctx.once(key, fn)`.
+
+## Import
+
+```typescript
+import { createStep, createWorkflow, defineWorkflow, step, stepOf, eq, gt, gte, lit, template, fromInit, fromStep, fromKnowledge, rows, env } from 'lua-cli';
+```
+
+## `createStep(config)`
+
+A typed code step. `inputSchema` / `outputSchema` / `resumeSchema` are zod schemas; the compiler serializes them to JSON Schema.
+
+| Field | Meaning |
+|---|---|
+| `id` | Unique step id (referenced by `then`, containers, `fromStep`) |
+| `inputSchema` / `outputSchema` | zod; outputs are validated after every attempt |
+| `timeoutSeconds` | Per-attempt wall (worker tier ≤ 600; `tier:'job'` up to 86 400) |
+| `retry` | `{ maxAttempts, backoffSeconds?, backoff?: 'fixed'\|'exponential', maxBackoffSeconds? }` — waits `backoffSeconds · 2^(attempt-1)` capped at `maxBackoffSeconds` |
+| `sideEffects` | `'external'` ⇒ never auto-retried on a platform-fault reclaim — the step **parks** instead (see [When a step parks](../workflows/recovery.md)) |
+| `onError` | `'fail'` (default) · `'continue'` · `'park'` |
+| `requiredConnections` | Connection ids that must mount before `execute` runs |
+| `tier` / `workspace` / `jobResources` / `jobTools` | Job-tier fields — see [Workspaces and long steps](../workflows/workspaces-and-long-steps.md) |
+| `execute(ctx)` | `ctx`: `inputData`, `resumeData`, `getInitData()`, `getStepResult(id)`, `state`, `suspend()`, `bail()`, `bailRun()`, `once()`, `log()`, `env`, `artefacts`, `occurrenceId`, `workspace?` |
+
+`ctx.suspend(payload)` parks the step for `Workflows.resume(runId, stepId, resumeData)`; on resume **`execute` re-runs from the top** with `ctx.resumeData` set.
+
+## `createWorkflow(config)…commit()`
+
+`createWorkflow(cfg)` opens a fluent builder; `.commit()` freezes it into the compiled graph. `defineWorkflow(cfg, (wf) => …)` is sugar for the same thing.
+
+Config: `name`, `description?`, `inputSchema`, `outputSchema?`, `budget?` (`maxCredits`, `maxDurationSeconds`, `maxJobSeconds?`), `schedule?` (`{ type:'cron', expression, timezone }`), `scheduleInput?`, `concurrencyPolicy?` (`'allow'|'forbid'`), `workspace?`, `outputVisibility?` (see [Output visibility](../workflows/output-visibility.md)), `env.template()` overlays (see [Env overlays](../workflows/env-overlays.md)).
+
+### Builder verbs and the placement rule
+
+**The call site places.** Every builder call — `then`, `agentStep`, `specialistStep`, `toolStep`, `map`, `approval`, `waitForSignal`, `sleep`, `sleepUntil`, `foreach`, `parallel`, `branch`, `switch`, `dowhile`, `dountil`, `workflow` — appends **exactly one** entry to the chain where it is called. Containers take `StepRef`s: an inline step object, or a **string** naming an `agentStep`/`specialistStep`/`toolStep` declared elsewhere in the same chain — a string ref inside a container means "declare here, inside me" and does not append a second top-level entry. An id declared but never placed is `WORKFLOW_UNPLACED_STEP` (warning locally, error at push); referenced but never declared is `unknown-step-ref` at `.commit()`.
+
+| Verb | Entry |
+|---|---|
+| `.then(step, input?)` | Sequential step |
+| `.agentStep(id, { agentId, prompt, outputSchema?, toolScope?, tier?, … })` | Agent turn (`prompt` is a `template(...)`) |
+| `.specialistStep(id, { role, prompt, … })` | Ephemeral role on the owning agent (D25) |
+| `.toolStep(id, { toolId, input? })` | One tool call |
+| `.map(descriptors, { id })` | Data reshaping — `id` is **required** once the workflow has ≥ 2 maps (`map-id-required`) |
+| `.parallel([...arms], { merge? })` | Concurrent arms; a `[map, step]` pair is a legal arm (lowered to an implicit subrun) |
+| `.switch([[predicate, armRef]...], otherwise?)` / `.branch(...)` | Conditional (exclusive / inclusive) |
+| `.foreach(step, { concurrency?, maxItems?, chunk?, rateLimit? })` / `.foreach({ items })` | Fan-out over an upstream array |
+| `.dowhile(ref, predicate, { maxIterations, intervalSeconds? })` / `.dountil(...)` | Loop |
+| `.sleep(ms)` / `.sleepUntil(template)` | Engine-side waits — `sleepUntil` lowers to an `<id>_at` mapping + `sleepUntil{dateFrom}` (D6-r1) |
+| `.approval(id, { title, approver, timeoutHours, onTimeout, editable?, editablePaths?, itemsPath?, … })` | Human gate — see [Approvals](../workflows/approvals.md) |
+| `.waitForSignal(id, { signal, schema?, timeoutHours, acceptedSources? })` | External event via `Workflows.signal` |
+| `.workflow(id, ref, input?, { workspace? })` | Child run the parent waits for |
+
+### Typed predicates
+
+`step(x).path('confidence')` / `stepOf<typeof schema>('id').path('confidence')` yield a `TypedRef<T>`; `eq`, `gt`, `gte`, `inSet` type-check against `lit(...)` literals — `gt(number, lit('a'))` does not compile.
+
+### Bindings
+
+`fromInit(path)` · `fromStep(id, path?)` · `template('${initData.x} ${stepResults.id.y}')` · `fromKnowledge({ source, query, maxChars })` · `rows(id, path, { offset, limit })` (paged dataset rows) · `env(key)` (run-time secret) vs `env.template(key)` (push-time overlay).
+
+## Testing and pushing
+
+- Offline: `lua test workflow <name>` — the local reference driver ([Testing locally](./Workflows.md#testing-locally), full flags in [Testing offline](../workflows/testing-offline.md)).
+- `lua push workflow` compiles, validates (placement, schema flow, caps preflight) and creates a sandbox version; `lua workflows deploy` / `activate` manage the lifecycle.
+
+## Related
+
+- [Workflows](./Workflows.md) — the runtime API (`Workflows.start/get/list/cancel/resume/signal`)
+- [When a step parks](../workflows/recovery.md) · [Approvals](../workflows/approvals.md) · [Script form](../workflows/script-form.md)

package/docs/api/Workflows.md

@@ -0,0 +1,110 @@
+# Workflows API
+
+The Workflows API lets your tools, jobs, webhooks, triggers and other workflows start, inspect and steer **workflow runs** — durable, multi-step programs you author with `createWorkflow(...)` and push with `lua push workflow`.
+
+## Import
+
+```typescript
+import { Workflows } from 'lua-cli';
+```
+
+Inside a sandbox (tools, jobs, webhooks, workflow code steps) `Workflows` is also available as a global.
+
+## Overview
+
+- `start` **never awaits execution** — it returns `{ runId, status }` immediately. `waitSeconds` (≤ 55) asks the server to hold the response for early terminal state; it changes the response, never the execution model.
+- Runs are idempotent on `idempotencyKey` — re-sending the same key returns the existing run instead of a duplicate.
+- A workflow with `concurrencyPolicy: 'forbid'` refuses a second start while one is in flight with a thrown `WorkflowApiError { code: 'RUNS_IN_FLIGHT', blockingRunId }` — never a 429, never a gate.
+- `status: 'gated'` means the run is parked (quota, billing or consent) and holds no slot. Consent gates are cleared from the desktop or with `lua workflows approve`.
+- `nameOrId` resolves the workflow **name on the calling agent first**, then a workflow id.
+- `get` / `list` honour output visibility: a restricted run comes back with `restricted: true` and no `output` — never an error.
+- From a workflow code step, `Workflows.start` creates a **detached** run (no parent link). Use the `.workflow(...)` builder node when the parent should wait.
+
+## Methods
+
+### `Workflows.start(nameOrId, input?, opts?)`
+
+Starts a run.
+
+**Parameters:**
+
+- `nameOrId` (string) — workflow name (agent-local) or id
+- `input` (unknown) — validated against the workflow's `inputSchema`
+- `opts` (object, optional)
+  - `idempotencyKey` (string) — dedup key (≤ 128 chars)
+  - `budget` (`{ maxCredits?, maxSteps?, maxDurationSeconds? }`)
+  - `waitSeconds` (number ≤ 55) — server long-poll
+  - `initialState` (object ≤ 64 KB) — seeds `ctx.state`
+  - `correlationKey` (string), `tags` (string[] ≤ 10)
+  - `replyTo` (`{ channel, threadId }`) — customer-channel continuation
+  - `workflowVersionId` (string) — pin a version (default: the active one)
+
+**Returns:** `Promise<{ runId, status: 'queued' | 'gated' | 'running' | 'completed' | 'failed', output? }>`
+
+```typescript
+const { runId, status } = await Workflows.start(
+  'outreach',
+  { leads },
+  { idempotencyKey: `outreach:${batchId}`, tags: ['crm'] }
+);
+```
+
+### `Workflows.get(runId)`
+
+Returns the run summary (status, counts, gate, lineage, `output` when readable).
+
+### `Workflows.list(opts?)`
+
+`opts`: `{ limit?, status?, workflow?, correlationKey?, tags?, sort? }` — `tags` are AND-ed; `sort` is one of `-createdAt | createdAt | -durationMs | durationMs`.
+
+### `Workflows.cancel(runId, opts?)`
+
+`opts.mode` is `'request'` (default, two-stage) or `'force'` (after `forceAvailableAt`). Returns `{ status, nextAction: 'cancel_again' | 'force' | 'none', forceAvailableAt? }`. A running code step is killed within seconds; if the runner cannot be reached the step ends at its next boundary (≤ 10 min) — cancellation is never lost either way.
+
+### `Workflows.resume(runId, stepId, resumeData)`
+
+Resumes a step suspended with `ctx.suspend(...)`. The loser of a resume race receives `{ resumed: false, reason: 'already_resumed', recorded }` — never an error. Approvals resolve through `lua workflows approve` (human-only); signals through `Workflows.signal`.
+
+### `Workflows.signal(runId, name, payload?, opts?)`
+
+Delivers a named signal to a run waiting on `waitForSignal(name)`. `opts.dedupeKey` makes a re-send a no-op (`{ accepted: true, duplicate: true }`). Returns `{ accepted, reason?: 'source_not_accepted' | 'duplicate' | 'parked' }`.
+
+### Reserved members
+
+`startBatch`, `signalByKey`, `raiseBudget`, `setGoal` and `goals.{list,get,pause,resume,close}` are part of the API surface (the member list is frozen) and throw `WorkflowApiError { code: 'WORKFLOWS_API_UNAVAILABLE' }` until their server routes ship. For `startBatch`: from an agent turn, prefer the `startWorkflowRunBatch` tool (one consent card for the whole batch, D23-r5).
+
+## Errors
+
+All failures throw `WorkflowApiError` with `code` (the server discriminator — `RUNS_IN_FLIGHT`, `SUSPENDED_CAP`, `WORKFLOW_NOT_FOUND`, `CONTROL_UNAVAILABLE`, …), `statusCode`, and any extra fields the server returned (for example `blockingRunId`).
+
+```typescript
+try {
+  await Workflows.start('nightly-sync', {});
+} catch (e) {
+  if (e.code === 'RUNS_IN_FLIGHT') return `Already running: ${e.blockingRunId}`;
+  throw e;
+}
+```
+
+## Testing locally
+
+`lua test workflow <name>` runs a compiled workflow **offline** through the local reference driver — no engine, no cluster:
+
+```bash
+lua test workflow outreach --input @leads.json \
+  --step-output draftEmail=@fixtures/draft.json \
+  --approve reviewDrafts=@edited.json \
+  --ledger-out out.json
+```
+
+- `--step-output <id>=@file|<json>` completes a step without running it (validated against its `outputSchema`) — this is how a predicate over an agent output gets both truth values under the default `--agents fake`.
+- `--approve <id>[=@payload]` / `--deny <id>[=@reason]` pre-answer approvals; `--signal <name>=<json>` pre-supplies `waitForSignal` payloads in order.
+- `--fixtures <dir>` replays recorded agent/tool outputs (`--record <dir>` writes them); a missing fixture exits **5** — never a silent fake.
+- `--from-run <runId>` seeds every completed step from a real run and restarts at the first non-completed one.
+- `--ledger-out <file>` writes the in-memory ledger; `lua workflows replay <runId> --local` re-evaluates a real run's predicates and mappings against your compiled artifact and reports `LEDGER_DIVERGENCE`.
+- `--park <id>` simulates a platform-fault park of a `sideEffects:'external'` step (retry / skip / complete / fail, same verbs as production); `--fast-retries` collapses retry backoff to 0; `--real-time` actually waits instead of fast-forwarding the virtual clock; `--artefacts-dir <dir>` backs `ctx.artefacts.*` on disk.
+
+## Related
+
+- `lua workflows` — list, start, runs, status, watch, attach, cancel, resume, approve, signal, replay, logs, delete — `attach` re-attaches to a running run's event stream (the same stream your chat card re-attaches to)
+- [LuaWorkflow](./LuaWorkflow.md) — the builder primitive

package/docs/workflows/approvals.md

@@ -0,0 +1,28 @@
+# Approvals
+
+_Source of truth: workflows-spec 06 §6.4. This page is the developer summary; the spec is normative._
+
+`.approval(id, cfg)` parks the run until a person decides. The node completes with `{ approved, payload?, edited?, timedOut?, escalations? }` — branchable data, never an exception.
+
+## Approver specs
+
+`approver:` takes `'creator' | 'org-admins' | { users: [...] } | { role: '<org-role>' } | { group: '<group>' }`. Role/group specs are org data and template-portable; user lists are not. Approvers are re-resolved **at suspend and at decision** — a role change mid-wait applies.
+
+- **Maker-checker**: `excludeInitiator: true` — whoever started the run can never approve it. On a customer-channel run (`principalKind:'customer'`) an approval resolving to `'creator'` fails `approver-is-run-principal`.
+- **Four-eyes**: `fourEyes: { edit: <spec>, approve: <spec> }` — whoever edits the payload cannot be the one who approves it.
+
+## Deadlines and escalation chains
+
+`timeoutHours` runs on **business time** when `businessHours: { tz, calendar }` is set. `onTimeout` is a chain: each `{ escalateTo, timeoutHours }` hop re-prompts the next audience; the terminal `'deny'` (or `'cancel-run'`/`'continue'`) completes the node — e.g. `{approved:false, timedOut:true, escalations:2}`.
+
+## Edited payloads
+
+`editable: true` + `editablePaths: ['amount', 'drafts[*].body']` (the `a.b[0].c` / `[*]` grammar) lets the approver patch the payload. The sequence is **fetch → patch → approve-with-fingerprint**: the approve call echoes the fingerprint of the revision the approver saw, so a concurrent edit forces a re-read. Out-of-grammar paths are refused; `editedPayloadSchema` validates the result.
+
+## Where approvals surface
+
+The desktop inbox and run detail carry the full card (per-item rows, edits, escalation state). **Text channels (WhatsApp/SMS/email) approve or deny the whole batch only** — no per-item decisions, no edits.
+
+Per-item approvals (`itemsPath` / `itemApprover` / `itemTimeout`) fan one node out to one decision per item — see [Per-item approvals](./per-item-approvals.md).
+
+Offline: `--approve <id>[=@payload]` / `--deny <id>[=@reason]` pre-answer the prompt; an edited payload is checked with the same `matchesEditablePath` + `editedPayloadSchema` the server uses.

package/docs/workflows/artefacts-and-datasets.md

@@ -0,0 +1,19 @@
+# Artefacts and datasets
+
+_Source of truth: workflows-spec (P1-8; Cluster K B40). This page is the developer summary; the spec is normative._
+
+`ctx.artefacts.put(name, data, { contentType?, kind?, datasetSchema?, title?, source? })` stores a file on the run (≤ 50 per step) and returns `{ artefactId }`; `get(id)` / `list()` read back. Steps pass **references**, not bytes.
+
+## Datasets — `{__datasetRef}`
+
+An array-typed step output over **8 MB** becomes a `{__datasetRef}` (NDJSON on the CDN) instead of `OUTPUT_TOO_LARGE`. Bind pages with `rows(stepId, path, { offset, limit })` — the bare ref renders as the ref object. `--input` values may carry `{"__artefactRef": "<id>"}` to hand a run an existing artefact.
+
+## Streaming and datasets
+
+`get(id).stream({ range })` reads large artefacts without buffering; `get(id).rows({ offset, limit })` pages NDJSON/parquet datasets (parquet row groups pass through untranscoded). Ceilings: 256 MB inline, 4 GiB streamed.
+
+## Titles and sources
+
+`title` and `source` metadata surface in the desktop artefact pane and in exports; `lua workflows artefact <runId> <artefactId>` fetches one from the CLI (presigned).
+
+Offline: `--artefacts-dir <dir>` backs `ctx.artefacts.*` on disk (`<dir>/<artefactId>` + `<artefactId>.meta.json`, ids `local-<n>`); without it every call fails loudly (`ARTEFACTS_NOT_AVAILABLE_OFFLINE`) — never a silent fake. Dataset-ref paging is engine-side.

package/docs/workflows/coding-harness.md

@@ -0,0 +1,12 @@
+# Coding harness — `claude-code` vs `generic`
+
+_Source of truth: workflows-spec 05 §5.17.6 (D27). This page is the developer summary; the spec is normative._
+
+`harness:'claude-code'` runs Claude Code against Anthropic-class models; `harness:'generic'` runs Lua's own agent loop with the **same nine workspace tools** against any provider your org is allowed — the tool ids, the budget, the secret scan and the turn limit are identical.
+
+- Absent `harness`, the platform derives one from the step's model; the local driver prints the derived value so you see what the server will stamp.
+- `LUA_WF_JOB_PROVIDERS` gates providers per org; an out-of-list model is `job-tier-provider-unsupported`.
+- **Org BYOK keys go through the sidecar proxy — your key never enters the agent container.**
+- Billing rows carry `model` + `harness` (seat multiplier per provider).
+
+Offline: `--agents live` with `harness:'generic'` runs the generic provider in-process against **your own** key from the environment (`OPENAI_API_KEY` / `GOOGLE_API_KEY` / `ANTHROPIC_API_KEY`) — billing and governance are server-side only.

package/docs/workflows/compliance-gates.md

@@ -0,0 +1,16 @@
+# Compliance gates — EXT-* features shipped dark
+
+_Source of truth: workflows-spec §15 gates. This page is the developer summary; the spec is normative._
+
+Several enterprise surfaces are **specified and shipped dark; each flips on its own gate** — the code is in the release, inert until the platform opens the gate for your org:
+
+| Gate | Surface | Dark behaviour |
+|---|---|---|
+| `EXT-REGION` | Region-pinned Job workspaces / data residency | `region-unavailable` at push |
+| `EXT-KMS` | BYOK key-alias on workspaces + artefacts (B38) | alias refused at push |
+| `EXT-AUDIT-API` | SIEM pull / `lua workflows audit-search` (B39, R72) | the verb answers **501** |
+| `EXT-EFS` | `workspace.backend: 'efs' \| 's3'` | `workspace-backend-unavailable` (refused, not downgraded) |
+| `EXT-GOVERNANCE` | Signed external governance review (`routeReview`) | policy verdicts stay platform-internal |
+| `EXT-APPROVALS` / `EXT-SCIM` | External approval systems / SCIM approver sync | approver specs resolve org-locally |
+
+Asking for a gate is an org-admin → platform request; nothing in your workflow file changes when it opens.

package/docs/workflows/connections-in-coding-turns.md

@@ -0,0 +1,9 @@
+# Connections in coding turns
+
+_Source of truth: workflows-spec 05 §5.17.6 / 11 §11.5. This page is the developer summary; the spec is normative._
+
+`toolScope.connectionIds` on a Job-tier agent step mounts MCP connections into the coding turn **through a local proxy**: the model calls `tools/list` / `tools/call`; the proxy holds the token — the model never sees it.
+
+- A tool that needs approval is **refused inside the turn** (`mcp_call_denied`) — hand it to a worker-tier step where the approval card can park the run.
+- Calls are capped per segment; the cap and usage appear in the step detail.
+- Offline: connections are **not mounted** (no proxy, no token mint) — `--mcp <connectionId>=@fixture.json` stubs `tools/list` / `tools/call` from a `{ tools:[…], calls:{ [tool]: result } }` fixture; an unstubbed call returns the production `mcp_call_denied{reason:'not_in_scope'}` shape.

package/docs/workflows/correlation-keys.md

@@ -0,0 +1,11 @@
+# Correlation keys
+
+_Source of truth: workflows-spec (P1-3 / P1-14). This page is the developer summary; the spec is normative._
+
+`correlationKey` stamps a run with YOUR business identity (`ticket-4711`, `order-…`): pass it at `Workflows.start(..., { correlationKey })`, from a trigger's `correlationKeyTemplate`, or `lua workflows start --correlation-key`.
+
+- `Workflows.signalByKey(nameOrId, correlationKey, name, payload?)` delivers a signal **by business key** — no runId bookkeeping in your webhook; `allowMultiple` fans out when several runs share the key.
+- `Workflows.list({ correlationKey })` / `lua workflows runs --correlation-key` find the run(s).
+- `tags` are free-form labels (AND-ed in list filters); `replyTo: { channel, threadId }` routes the terminal reply back to the originating conversation.
+
+Offline: `--correlation-key`, `--tag`, `--reply-to <channel>:<threadId>` and `--on-behalf-of` stamp `ctx.runtime.*`; the would-be reply prints on the terminal instead of sending.

package/docs/workflows/env-overlays.md

@@ -0,0 +1,12 @@
+# Env overlays — `env.template()` vs `env()`
+
+_Source of truth: workflows-spec (Cluster K B33, WF-543). This page is the developer summary; the spec is normative._
+
+**`env.template('KEY')` = a graph literal resolved at push**, visible in `lua workflows env-overlay <name>` (a presence table — values are never printed). **`env('KEY')` = a run-time secret read inside `execute`.** One file, per-env values: staging and prod resolve different overlays over the **same `graphHash`** (the hash covers placeholders only; `envOverlayHash` sits outside the consent fingerprint).
+
+- A missing key at push is ERROR `env-template-missing` (exit 1; the version is never sent).
+- Keys matching `/(SECRET|TOKEN|KEY|PASSWORD)$/` are refused at compile (`env-template-secret-key`) — secrets belong in `env()`.
+- Caps: ≤ 64 keys, values ≤ 4 KB (`invalid-envelope`).
+- Installing a template re-resolves the overlay against the installing org's values.
+
+Offline: `lua test workflow --env KEY=value` (repeatable; then the project's `.env`) — a missing key is exit 2, and values never reach `--ledger-out`.

package/docs/workflows/evidence-bundles.md

@@ -0,0 +1,11 @@
+# Evidence bundles and run exports
+
+_Source of truth: workflows-spec (Cluster E R53–R56 / D24). This page is the developer summary; the spec is normative._
+
+`lua workflows export-run <runId> --out <dir>` writes one run's evidence bundle: the run doc, per-step rows (inputs/outputs/attempts), events, approvals with decision fingerprints, and artefact manifests. `export-runs --full --since … --until …` bulk-exports a window — the DSAR and audit path (`archive-runs` adds zip-per-run + an `archive-index.ndjson`).
+
+- Output visibility applies: restricted payloads export as `restricted: true` unless the caller's roles pass (owner bypass is audited).
+- Very large originals are referenced, not inlined (a 413 `PAYLOAD_PAGE_REQUIRED` answer means: page the artefact endpoint).
+- `--no-inputs` / `--no-artefacts` trim bundles for privacy-sensitive hand-offs.
+
+See also [Exports](./exports.md) for policy-driven terminal exports.

package/docs/workflows/exports.md

@@ -0,0 +1,5 @@
+# Exports on terminal state
+
+_Source of truth: workflows-spec (Cluster K B45). This page is the developer summary; the spec is normative._
+
+`workflowPolicy.export.onTerminal` (org policy) writes an evidence bundle for every terminal run to the configured destination — the always-on sibling of the manual [evidence bundles](./evidence-bundles.md). `lua workflows exports` lists what was written (destination, run, status); failures surface in the org inbox, and the run itself is never blocked by an export failure.

package/docs/workflows/external-content-and-toolscope.md

@@ -0,0 +1,11 @@
+# External content and `toolScope` — the taint rule
+
+_Source of truth: workflows-spec (Cluster E, P1-16). This page is the developer summary; the spec is normative._
+
+A step is **external-content tainted** when anything untrusted can reach its prompt: customer-channel input (`${initData.message}` on a customer-started run), `{knowledge}` bindings, or output flowing from a tool of the external kinds (`web-search`, `web-fetch`, `email-read`, `http`, `scrape`). Taint **propagates along bindings** — a step consuming a tainted step's output is tainted too (`computeExternalContentTaint` walks the plan).
+
+**A tainted `agentStep` must declare `toolScope`** — `{}` means "no tools" (and `defaultToolScopeMode:'deny'` implies it when absent). The point: prompt-injected content must not be able to steer an agent that holds tools.
+
+Walk-through — `support-triage` (§3.2 (g)): `classify` renders the customer message AND a knowledge binding ⇒ tainted ⇒ `toolScope: {}`; the downstream `refundGate` approval routes to `org-admins` (never `'creator'` — on a customer-channel run that is `approver-is-run-principal`).
+
+Push refuses a tainted step without `toolScope` (`external-content-needs-toolscope`); the desktop run detail marks tainted steps with the provenance chain (`via`).

package/docs/workflows/git-credentials.md

@@ -0,0 +1,11 @@
+# Git credentials in workflows
+
+_Source of truth: workflows-spec 11 §11.5.6 / 05 §5.17.3. This page is the developer summary; the spec is normative._
+
+`workspace.credentialsRef` names a **git-host connection** (e.g. your org's GitHub App install). Per Job, the platform mints a **short-lived token held by a sidecar** — git operations in the step go through the credential proxy; the token never enters the agent container and never appears in `env`.
+
+> **Never put a PAT in `env`.** Rotation or revocation of the underlying connection makes the next mint fail: the step fails `credentials_revoked{git_token_mint_failed}` and — with `onError:'park'` — enters the park/`retry-step` loop, so a re-grant resumes the run without losing work.
+
+- `jobTools:['gh']` is what mints `GH_TOKEN` for a code step (`pull_requests:write` + `contents:write` + `issues:read`, repo-scoped). Merge is a contents write — human-only-merge orgs keep `contents:write` off the App.
+- Templates never hardcode a connection id: they use `connections[].key`, resolved at install.
+- Offline, `credentialsRef` is printed and **not** resolved (no token mint) — `--credentials-ref-ok` suppresses the notice; the local driver uses your own git credentials.

package/docs/workflows/knowledge-bindings.md

@@ -0,0 +1,13 @@
+# Knowledge bindings
+
+_Source of truth: workflows-spec (P1-11; Cluster K B41). This page is the developer summary; the spec is normative._
+
+`fromKnowledge({ source, query, maxChars?, topK? })` as a map descriptor retrieves at render time (S2): each chunk arrives under a **provenance header** — `[knowledge source=<source> doc=<doc> chunk=<n> score=<s>]` — so the model can cite and the audit trail can trace. `maxChars` caps the rendered block; a retrieval timeout renders the EMPTY block plus a `knowledge: empty` warning (the run continues).
+
+## Connection sources (B41)
+
+`source:'connection'` with `connectionId` retrieves from Drive / Notion / Confluence through the org's connection. Requirements: the step must carry `toolScope` (connection knowledge is external content — see [External content](./external-content-and-toolscope.md)); the compiler's overlay pass adds the knowledge connection to the step's mounted set.
+
+Any knowledge binding taints the step (P1-16).
+
+Offline: knowledge retrieval is not emulated — a knowledge binding fails closed (`binding_unresolved`) unless you `--step-output` the consuming step. (`--knowledge <key>=@file` substitution is specified in 03 §3.9 step 7 and not yet wired in this build.)