@controllerai/cli 0.2.8 → 0.2.10

package/skills/controllerai-agents/SKILL.md

@@ -45,6 +45,7 @@ cai run flow <flowId> --inputs values.json --json
 ```
 
 Capture the successful workflow execution ID. Workflow inputs become tool parameters and outputs become its result.
+Before attaching a workflow tool, require a nonempty output contract and verify that the completed run returns it; otherwise the agent receives an empty result.
 
 ## 3. Create and assemble the draft
 
@@ -68,11 +69,16 @@ cai agent add-workflow <agentId> \
   --description "Use when ...; accepts ...; returns ..." \
   --json
 
-cai agent add-file <agentId> --file <path> --json
+cai agent add-file <agentId> --file <path> --space knowledge --json
+cai agent add-file <agentId> --file <path> --space shared --json
+cai agent files <agentId> --space knowledge --json
+cai agent files <agentId> --space shared --live --json
 cai agent tools <agentId> --json
 cai agent get <agentId> --json
 ```
 
+Use `cai agent files <agentId> [--space <knowledge|shared>] [--live]` to read file inventories. Adding with `--space shared` updates the live runtime file space immediately without publishing; an active agent sees it on the next turn, while a disabled agent sees it after enablement.
+
 Permission is part of agent design, not an afterthought. For every tool, settle the approval level WITH the user before attaching: present the tool list and ask which steps they want a human in the loop for ("should sending the email require your approval each time, or run automatically?"). The default is no approval. Add `--require-confirmation` for consequential writes, deletion, external communications, permission changes, purchases/spend, or an ambiguous destination; `cai agent update-tool` changes it later. Omitting the flag must be the user's informed autonomy decision, not an unnoticed default.
 
 Keep the two modes straight:
@@ -89,9 +95,19 @@ Publishing the agent snapshots its display name, instructions, tool identities,
 
 Publishing is a hard cutover: live conversations that are mid-turn are interrupted immediately (the person's in-flight answer never arrives), their unexecuted approval requests expire, and each conversation reopens on its own next message running the new version. Time publishes with that in mind and tell the user what a publish does to active conversations.
 
+Runtime lifecycle changes do not require publishing:
+
+```bash
+cai agent update <agentId> --disabled --json
+cai agent update <agentId> --enabled --json
+cai agent delete <agentId> --confirm --json
+```
+
+Disable pauses runtime immediately; enable resumes it immediately. Delete is soft: it revokes live access, requests best-effort termination of active sessions and pending approvals, retains conversation history but makes it inaccessible, has no CLI restore, and does not guard dependent workflows, which can fail later.
+
 ## Runtime usage boundary
 
-The user's local Codex, Claude, or other coding-agent subscription can cover builder reasoning. Hosted agent tests and conversations consume Controller AI runtime usage from the organization's shared pool. Connected providers may add charges or side effects. State this before starting a hosted test or describing this route as free.
+The user's coding-agent subscription covers builder reasoning, but hosted agent tests and conversations consume Controller AI runtime usage from the organization's pool, and connected providers may add charges or side effects. Say so before starting a hosted test or calling this route free.
 
 ## 4. Verify the draft as an agent
 
@@ -104,7 +120,7 @@ cai agent conversation history <conversationId> --json
 
 Test requests that should and should not select each tool. Verify exact arguments, truthful use of results, errors, and knowledge behavior.
 
-The user can also test the draft themselves in the product — offer them the agent's page in the app so they can try it hands-on before publishing (`cai agent create`/`publish`/`test` outputs include `appUrl` links to the agent and conversation pages when the app origin is known). Their impression of the conversation matters more than your transcript reading.
+Also offer the user the agent's app page to try the draft hands-on before publishing (`create`/`publish`/`test` outputs include `appUrl` links when the app origin is known). Their impression outweighs your transcript reading.
 
 - For a workflow tool, correlate a side-effectful call with its terminal workflow execution ID.
 - For a direct integration action, inspect persisted conversation action events/run result and the intended external effect. Direct actions do not create workflow execution IDs.
@@ -112,11 +128,13 @@ The user can also test the draft themselves in the product — offer them the ag
 For pending approval, inspect the exact request before choosing:
 
 ```bash
-cai agent conversation approve <conversationId> --request <requestId> --tool <toolName> --json
-cai agent conversation deny <conversationId> --request <requestId> --tool <toolName> --message "<reason>" --json
+cai agent conversation approve <conversationId> --request <requestId> --json
+cai agent conversation deny <conversationId> --request <requestId> --message "<reason>" --json
 ```
 
-Do not approve merely to make a test continue.
+The server resolves the tool from the permission request; do not pass a human-readable tool name. Do not approve merely to make a test continue.
+
+After `cai agent remove-tool`, test both a request that must no longer use the removed capability and a representative retained capability.
 
 ## 5. Publish in dependency order
 
@@ -153,16 +171,16 @@ Draft evidence does not prove the live agent. Test is owner-only. Shared users a
 
 ## 6. Offer Slack and organization sharing
 
-After a successful publish, offer the next steps rather than waiting to be asked:
+After a successful publish, offer the next steps unprompted:
 
-- **Slack**: if the user wants to talk to the agent in Slack, that requires the Slack ↔ Controller AI connection plus per-agent Slack configuration (agent slug, channel) — both set up in the product, not the CLI. Point the user to the relevant product page and offer to walk them through it.
+- **Slack**: talking to the agent in Slack needs the Slack ↔ Controller AI connection plus per-agent Slack configuration (slug, channel), both set up in the product, not the CLI — point the user there and offer to walk them through it.
 - **Sharing**: agents remain private unless the user explicitly asks for organization access:
 
 ```bash
 cai agent visibility <agentId> --value organization --json
 ```
 
-Organization members use the published version. Direct actions run through the agent owner's connected external account, while Controller AI usage comes from the organization's shared pool. Rebinding, revoking, or detaching that live grant can immediately affect published agents. Return to private visibility to revoke organization access.
+Organization members use the published version. Direct actions run through the owner's connected external account; usage comes from the organization's pool. Rebinding or revoking that live grant immediately affects published agents. Return to private visibility to revoke access.
 
 ## Final report
 

package/skills/controllerai-agents/references/instructions-and-versioning.md

@@ -66,7 +66,7 @@ Do not republish the agent merely to make a followed workflow's new live release
 
 | Layer | Evidence |
 | --- | --- |
-| Workflow tool | Completed development `cai run flow` execution |
+| Workflow tool | Completed development `cai run flow` execution; an intentional `cai run flow <flowId> --target live --confirm-live` execution is stronger evidence of published behavior than a draft-agent proxy |
 | Direct action | Persisted conversation action/run events, returned result, and intended external effect |
 | Draft routing | Draft conversation chooses the correct tool and arguments |
 | Published workflow | `workflow status` reports the intended live release and active state |

package/skills/controllerai-data/SKILL.md

@@ -79,6 +79,8 @@ cai data fields --type custom.customer --json
 
 Never feed a queried record directly into a write. Build a new fields object keyed by the `writeKey` mapping and omit reserved `id`, `createdAt`, and `updatedAt`.
 
+Fields may be typed `date`. Their values are strict ISO-8601 strings (`"2026-06-05"` or `"2026-06-05T12:30:00Z"`) on both write and read; anything else is rejected. Reserved `createdAt`/`updatedAt` are currently `text` — use `.toDate()` before date operations on them.
+
 ## Work on the correct rail
 
 Development is the default:
@@ -93,6 +95,23 @@ Use `--env live` only when the user intends to inspect or mutate production stat
 
 `data query --query` is plain-text search over serialized records and metadata, not a field predicate. Perform exact field filtering inside workflow expressions or inspect results explicitly.
 
+## Delete records explicitly
+
+Record deletion is CLI/REST-only; no workflow data node exposes it. Delete one known record or an explicit set of IDs:
+
+```bash
+cai data delete <recordId> --type custom.customer --env dev --json
+cai data delete-many --type custom.customer --records <id1,id2> --env dev --json
+```
+
+Delete every record in a collection only with explicit user intent; `--all` also requires `--yes`:
+
+```bash
+cai data delete-many --type custom.customer --all --yes --env dev --json
+```
+
+The default rail is development. Use `--env live` only for an intentional production deletion, then query that same rail to verify the result.
+
 ## Import and promote
 
 Validate CSV before writing:

package/skills/controllerai-data/references/data-rails.md

@@ -25,7 +25,7 @@ Field IDs are contracts. Prefer keeping an ID stable and changing only its displ
 ## Destructive operations
 
 - `data delete` soft-deletes one record.
-- `data delete-many --all` is broad and development-only through its REST route.
+- `data delete-many --all --yes` is broad, REST-backed, and DEVELOPMENT-ONLY — `--env live` is refused (`DEV_ONLY_ROUTE`). The only live write paths are single-record `data create/update/delete --env live` and `copy-to-live`.
 - `schema delete` removes access to the whole collection and breaks its type references.
 - CSV `--mode commit` appends rows.
 - `copy-to-live` changes production data.

package/skills/controllerai-expressions/SKILL.md

@@ -46,6 +46,8 @@ Copy binding and field names exactly. Important sources include:
 
 Do not derive a binding from a display label. Context flags duplicate display names and supplies the de-duplicated JS name, input ID, and source node.
 
+When compilation reports an unknown field, copy a typeable display-derived accessor it advertises; field IDs appear second for disambiguation.
+
 ### 3. Use only advertised syntax
 
 Get the current operation catalog when needed:
@@ -56,9 +58,11 @@ cai expr ops --type <text|number|date|list|boolean|file|custom> --json
 
 Keep the program to optional `const` declarations followed by one final expression. Do not use loops, assignments, `new`, regular expressions, optional chaining, arbitrary library methods, or object construction unless the current compiler catalog explicitly supports them.
 
+Date values are ISO-8601 strings on the wire (`"2026-06-05"` or `"2026-06-05T12:30:00Z"`). A `date`-typed flow input or field is used directly with date operations; only `text` values need `.toDate()` first. For epoch text, pass the unit literal explicitly: `flow.timestamp.toDate("epoch_seconds")` or `flow.timestamp.toDate("epoch_millis")`. The ops table renders that argument generically; never guess the unit from digit count.
+
 Read [references/dsl-and-recipes.md](references/dsl-and-recipes.md) for canonical patterns.
 
-### 4. Compile, write, and read back atomically
+### 4. Compile, write, and read back
 
 For a node prop, prefer:
 
@@ -72,7 +76,9 @@ For multiline expressions or shell-sensitive templates, put the exact source in
 cai expr set <nodeId> --prop <propName> --js-file expression.js --json
 ```
 
-This fetches target metadata, compiles without writing on failure, chooses `valueJs` versus `expressionValueJs`, persists, and verifies read-back.
+This fetches target metadata, auto-enables a catalog-only optional target when needed, compiles before writing the value, persists to the correct channel, and verifies read-back. If validation or the value write then fails, the prop stays enabled; repair with `cai node disable-prop <nodeId> --prop <propName>`.
+
+Array channels are not interchangeable. On a value-channel `SHORT_TEXT_ARRAY`, a scalar expression replaces the whole array with one dynamic element; it does not append. List-typed expressions on value-channel array props are rejected. Use `cai node set <nodeId> --prop <propName> --value '["a","b"]'` for a static list, or use a list-typed expression only where prop metadata exposes whole-array expression mode.
 
 For a side-effect-free check:
 

package/skills/controllerai-flow-control/SKILL.md

@@ -103,6 +103,8 @@ Inside loop mappings, `item` exists only where context exposes it. Inside the bo
 
 Loops run sequentially. `--continue-on-error` applies to a failed child iteration; a list expression or mapping/config expression that fails before the child starts still aborts the loop. Test empty, one-item, several-item, over-limit, and intended iteration-error behavior.
 
+Never enable continue-on-error on a money path; charges, purchases, transfers, refunds, and other spend must fail fast.
+
 ## Subflows and convergence
 
 Define the called flow's inputs and outputs first. Then initialize a Run flow component and bind it:

package/skills/controllerai-node-config/SKILL.md

@@ -63,6 +63,8 @@ cai node status <nodeId> --json
 cai node props <nodeId> --json
 ```
 
+For option-backed props, `node props` and write readback may report `optionsAvailability`: `available`, `blocked_upstream` with `blockedBy`, or `dynamic_upstream`. It is positional: earlier single `DROPDOWN` selectors gate later options. Older backends, and responses without a dependency catalog, may omit it; treat absence as unknown, not available.
+
 Work through blockers in this order:
 
 1. Missing connection
@@ -73,7 +75,9 @@ Work through blockers in this order:
 6. Expressions
 7. Unresolved output type
 
-Re-run `node props` after every reload selector or connection change. Dynamic props can appear, disappear, or reset.
+Follow `next`. When a disabled required prop has an activating selector, its blocker names that selector; when it is the next blocker, `next` gives the exact `cai node set` command. `dynamicSelectorNotes` is non-blocking: a node may read ready while its dynamic selector's dependents still reflect the last concrete resolution.
+
+After every concrete reload-selector or connection change, re-run `node props`; dynamic props can appear, disappear, or reset. Use `cai node reload <nodeId> --json` to re-resolve without re-setting a selector. If an explicit reload finds an unset materialized reload selector, it returns `reconcileSkipped: "unset_selector"` plus a note and preserves materialized dependent props instead of reconciling them.
 
 ### 5. Set props safely
 
@@ -87,10 +91,12 @@ Optional prop:
 
 ```bash
 cai node optional-props <nodeId> --json
-cai node enable-prop <nodeId> --prop <exactName> --json
-cai node props <nodeId> --json
+cai node set <nodeId> --prop <exactName> --value '<literal-or-json>' --json
+# or: cai expr set <nodeId> --prop <exactName> --js '<expression>' --json
 ```
 
+`node set` and `expr set` auto-enable a catalog-only optional prop, refresh its metadata, then write. Do not run a separate enable step first. If validation or the later write fails, the prop stays enabled; repair with `cai node disable-prop <nodeId> --prop <exactName>` and re-read props. This is also the repair for the Update-data wipe footgun: that action writes every enabled field, so disable any accidentally enabled field before running it.
+
 Remote or dynamic option:
 
 ```bash
@@ -102,7 +108,20 @@ cai node set <nodeId> \
   --json
 ```
 
-For a remote option, preserve both fields from the same returned option. The label is not cosmetic: the CLI uses it to search providers that do not index opaque IDs, then verifies that the returned value still matches before writing. For a multi-select, pass a JSON array of returned values and one `--label` argument per value, in the same order. The CLI supplies the persisted label shape, chooses the correct expression storage channel, and verifies read-back. If metadata or options cannot be fetched, it fails closed; do not bypass that with a raw API call.
+`node options` also supports `--prev-context '<context JSON>'` from the preceding page and repeatable `--for '<earlierProp>=<value>'` overrides for read-only hypothetical resolution; JSON literals are accepted and bare text stays a string. If options are `blocked_upstream`, both `node options` and `node set` name the blocking prop and print the exact `cai node set` command to run first.
+
+For an ordinary remote option, preserve both fields from the same returned option. The label is not cosmetic: the CLI uses it to search providers that do not index opaque IDs, then verifies that the returned value still matches before writing. For a multi-select, pass a JSON array of returned values and one `--label` argument per value, in the same order. The CLI supplies the persisted label shape, chooses the correct expression storage channel, and verifies read-back.
+
+When an earlier selector makes the prop `dynamic_upstream`, no option list exists. Use a known exact ID or an expression:
+
+```bash
+cai node set <nodeId> --prop <exactName> --value '<exact-id>' --label '<display label>' --json
+cai node set <nodeId> --prop <exactName> --js '<expression>' --json
+```
+
+`--value` stores the literal without provider-option validation and prints a note; on a label-bearing selector, `--label` controls its display label. This is the sole raw `--value` exception when the CLI has an advertised option set: outside `dynamic_upstream`, a missing prop row, a failed or empty advertised remote-options lookup, or a value absent from advertised options fails closed. The exception still requires prop metadata and verified read-back. Do not bypass failures with a raw API call.
+
+For components whose dependent props exist only after a concrete selector value, use a template first: set one concrete value, re-read `node props`, configure or record the revealed dependents, then switch the selector to `--js`. Those materialized props persist as the last concrete schema. Starting dynamic leaves them absent; neither that write nor `node reload` materializes them until one concrete selection is made.
 
 For dynamic values, load `controllerai-expressions` and prefer `cai expr set`.
 
@@ -125,14 +144,22 @@ cai run node <nodeId> --inputs <values.json> --json
 
 If the node has a wired input or consumes `inputs.<name>`, the node test is only an isolated configuration check. Run `cai run flow <flowId> --inputs <values.json> --json` before declaring its upstream expressions verified.
 
+If a dynamic provider action cannot be run but its response is documented, declare an unverified output contract:
+
+```bash
+cai node declare-output <nodeId> --sample-file provider-response.json --json
+```
+
+The sample must be a JSON object or a non-empty JSON array of provider items. Re-read status and expression context afterward; the first real completed run verifies the declaration.
+
 Read [references/prop-and-readiness.md](references/prop-and-readiness.md) when a prop is dynamic, option-backed, expression-capable, or unexpectedly absent.
 
 ## Hard rules
 
 - Configure props in returned order; later props may depend on earlier values.
 - Never write a prop absent from `node props`.
-- Enable catalog-only optional props before writing them.
+- Let `node set` or `expr set` auto-enable catalog-only optional props; disable the prop explicitly after a failed write.
 - Wire before authoring an expression that consumes upstream data.
 - Changing a connection invalidates connection-scoped options; re-read props and options.
 - A successful write is not completion. Require read-back plus `node status`.
-- If output type remains unresolved, perform a realistic development test and inspect the resulting execution. Never fabricate an output schema.
+- If output type remains unresolved, perform a realistic development test and inspect the resulting execution. Declare only a documented provider sample; never fabricate an output schema.

package/skills/controllerai-node-config/references/prop-and-readiness.md

@@ -6,7 +6,9 @@ The JSON response reports:
 
 - `missingConnection`: an authenticated component has no account bound.
 - `missingRequiredProps`: materialized required props without a value.
+- `disabledRequiredProps`: required props currently disabled by an activating selector. When that selector can be resolved, its blocker names the selector; when it is next, `next` gives the exact `cai node set` command.
 - `pendingReloadProps`: selectors that must be set before dependent props are trustworthy.
+- `dynamicSelectorNotes`: reload selectors holding dynamic values whose dependents were not re-resolved. These notes do not block readiness, so inspect them even when the node reads ready.
 - `outputTypeStatus`: `concrete`, `unresolved`, or `none`. Connection-port wrappers never count as a concrete process output.
 - `readyForExpressions`: connection and required/reload props are complete. The source still must be wired before its binding appears in expression context.
 - `readyForRun`: connection and required/reload props are complete; running may be the step that discovers a concrete output type.
@@ -40,6 +42,14 @@ Do not force a channel with internal fields. `cai node set` and `cai expr set` c
 
 Static options are declared in component/prop metadata. Remote options require current connection and earlier prop values.
 
+When dependency metadata is available, each option-bearing prop reports:
+
+- `available`: no earlier selector blocks option resolution; connection or provider failures can still stop the lookup.
+- `blocked_upstream` with `blockedBy`: an earlier single `DROPDOWN` selector is unset.
+- `dynamic_upstream`: an earlier single `DROPDOWN` selector is dynamic, so no concrete option list exists.
+
+The backend computes this in prop order. Older backends, and current responses without a dependency catalog, omit these fields; do not interpret absence as `available`.
+
 ```bash
 cai node options <nodeId> --prop <name> --query "<specific search>" --json
 cai node set <nodeId> --prop <name> --value '<option.value>' --label '<option.label>' --json
@@ -47,6 +57,20 @@ cai node set <nodeId> --prop <name> --value '<option.value>' --label '<option.la
 
 Pass the value and label from the same live option. Remote providers often search labels rather than opaque values, so omitting `--label` can make a valid copied ID impossible to re-verify. For multi-select, pass a JSON array of returned values plus one `--label` argument per value in matching order. The CLI constructs the required array of `{value,label}` records for read-back/UI compatibility.
 
+Continue a provider page with the opaque context printed by the previous call:
+
+```bash
+cai node options <nodeId> --prop <name> --prev-context '<context JSON>' --json
+```
+
+Preview options under uncommitted earlier values with repeatable overrides; valid JSON becomes a typed literal and bare text remains a string:
+
+```bash
+cai node options <nodeId> --prop <name> --for '<selector>=<value>' --for '<other>=true' --json
+```
+
+For `blocked_upstream`, follow the error's exact command for `blockedBy`. For `dynamic_upstream`, `node options` returns no list; `node set --value '<exact-id>'` deliberately stores a known literal without provider membership validation and prints a note. Add `--label '<display label>'` when the prop is label-bearing, or use `node set --js '<expression>'`. For an advertised option set outside that state, a missing prop row, a failed or empty advertised remote-options lookup, or a value absent from advertised options fails closed.
+
 ## Reload selectors
 
 A prop with `reloadProps:true` changes the downstream prop schema. Set it statically, wait for the mutation, and immediately re-read:
@@ -57,8 +81,18 @@ cai node props <nodeId> --json
 cai node status <nodeId> --json
 ```
 
+Use `cai node reload <nodeId> --json` to re-resolve current values explicitly instead of re-setting a selector. If any materialized reload selector is unset, the command returns `reconcileSkipped: "unset_selector"` and a note; that skipped path updates metadata without reconciling or deleting materialized dependent props.
+
 Do not batch dependent values into stale metadata. A provider, model family, spreadsheet, database, or action selector commonly triggers this behavior.
 
+For a component whose dependent schema exists only after a concrete upstream selection, materialize a template before going dynamic:
+
+1. Set the selector to one concrete value.
+2. Re-read props and configure or record the revealed dependents.
+3. Switch the selector to a dynamic value with `--js`.
+
+The dependent props persist from the last concrete selection. Starting with a dynamic selector leaves them absent, and neither the dynamic write nor an explicit reload can materialize them until the selector has held a concrete value once.
+
 ## Output type
 
 An unresolved output blocks trustworthy downstream field expressions. Resolve it by one of:

package/skills/controllerai-runs/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: controllerai-runs
-description: Run and debug Controller AI nodes and flows on the development version — execution history, ports, outputs, skip reasons, and resolved configs. Use when verifying or testing a build, investigating a failed or green-but-wrong run, resolving an unknown output type, checking expression values, or proving what data and configuration reached each node.
+description: Run and debug Controller AI nodes on development and flows on development or the published live version — execution history, ports, outputs, skip reasons, and resolved configs. Use when verifying or testing a build, investigating a failed or green-but-wrong run, resolving an unknown output type, checking expression values, or proving what data and configuration reached each node.
 ---
 
 # Controller AI runs
 
-Think "dev run", not "test". The development version is a real environment with its own data store — like an app's dev environment — and there is NO simulation mode: a dev run executes real integration actions (messages send, records change, provider usage is spent). Dev isolation covers the data store only. Running is a required part of building — one successful run is how a dynamic node's output type gets resolved for the next step — so the job is never "avoid running"; it is to mitigate risk before running.
+Think "real run", not "simulation". `run node` always uses development; `run flow` defaults to development and can target the published live version. Both rails execute real integration actions (messages send, records change, provider usage is spent); development isolation covers the data store only. Running is a required part of building — one successful run is how a dynamic node's output type gets resolved for the next step — so mitigate risk before running.
 
 ## Consequential actions: mitigate with the user, don't refuse
 
-Before dev-running an action with external consequences (send, reject, delete, charge), tell the user plainly what will really happen and ask for a safe target:
+Before running an action with external consequences (send, reject, delete, charge), tell the user plainly what will really happen and ask for a safe target:
 
 - Email/message sends → "What address/channel can I send the dev run to?" (often the user's own).
 - Record deletes/updates → "Is there a record I can safely use, or shall I create one first and delete that?"
@@ -25,7 +25,13 @@ cai node declare-output <nodeId> --sample-file shape.json
 
 ## First live run is part of development
 
-Publishing and running live is a legitimate, supervised development step — not a process failure. For risky sends, build the safe-audience harness: branch on the `isLiveVersion` data source with If/Else — the false branch targets the developer (own email/channel), the true branch targets the real audience. The first live run under supervision is how remaining problems surface.
+After publishing, run the published version directly under supervision:
+
+```bash
+cai run flow <flowId> --inputs values.json --target live --confirm-live --json
+```
+
+This command fires external actions and spends usage. For risky sends, build the safe-audience harness: branch on the `isLiveVersion` data source with If/Else — the false branch targets the developer (own email/channel), the true branch targets the real audience. Use this direct live run for explicit verification; do not wait for a real trigger event.
 
 ## Prepare exact run inputs
 
@@ -44,6 +50,10 @@ Use returned opaque input IDs. A compact input file can be a flat map:
 
 Do not key test values by a guessed display name.
 
+Before an isolated node run, `cai run inputs <nodeId> --json` calls `get_node_test_inputs`; supply every referenced `flowInputs[].id` explicitly. Missing one fails before execution with `ISOLATED_FLOW_CONTEXT_REQUIRED`. Explicit `null`, `""`, `false`, and `0` are valid supplied values.
+
+Date-typed inputs take plain ISO-8601 strings, e.g. `"2026-06-05"` or `"2026-06-05T12:30:00Z"` (no double-encoding, no epoch strings).
+
 ## Run the smallest useful scope
 
 Start with a changed node, then run its containing flow:
@@ -63,6 +73,7 @@ For every node test, inspect:
 - `skipReason`
 - `runScope`, especially `upstreamNodesExecuted` and `endToEndValidationRequired`
 - `resolvedConfigs`
+- `resolvedConfigs[].resolutionWarnings`: trust every structured entry; `[]` is authoritatively clean. Runs also surface entries on stderr, so read stderr even when the execution completed.
 - `outputTypeAdoption`: the server verifies the exact completed `nodeExecutionId`, derives its persisted output shape, and updates only that non-static node. `adopted` or `already_typed` lets the next `node status` converge; `no_observed_output` means the representative run returned no reusable shape. `adoptedNodeIds` must be empty or contain only the tested node; stop if it names a sibling.
 - output shape and values
 
@@ -99,6 +110,7 @@ After successful output discovery, re-read `cai node status` and downstream `cai
 
 ## Completion gate
 
+- Gate scripts on `cai workflow validate`; it exits 1 when the response has `valid: false`.
 - The test exercised the changed path with credible values.
 - The first unexpected node, if any, was identified rather than inferred from the final error.
 - All dynamic configs resolved to intended values.

package/skills/controllerai-runs/references/debugging.md

@@ -9,7 +9,7 @@ cai workflow status --json
 cai flow get <flowId> --json
 ```
 
-Manual node/flow tests use development. Trigger replay defaults to the development rail, but both development and live replay can call real providers and create external effects. Live replay additionally requires `--target live --confirm-live`.
+Node runs use development. Flow runs default to development; `cai run flow <flowId> --target live --confirm-live` runs the published version. Trigger replay also defaults to development and uses the same flags for live. Every rail can call real providers and create external effects.
 
 ## 2. Find the first divergence
 

package/skills/controllerai-start/SKILL.md

@@ -44,5 +44,6 @@ The platform reference lives at https://docs.getcontroller.ai. Fetch https://doc
 - Local coding-agent subscriptions cover builder reasoning, not Controller AI hosted-agent runtime usage.
 - Provider actions can send messages, mutate or delete records, and incur provider charges. Decide the per-action confirmation policy before attaching one.
 - Never publish, share with the organization, replay a live trigger, or perform a consequential external test without clear user intent.
+- When a platform limitation blocks the outcome, STOP and report the partial result with the blocking error; never keep probing until the clock expires.
 
 At completion, report what was created, what is still draft or live, the evidence actually observed, and any connection or user decision still required.

package/skills/controllerai-workflows/SKILL.md

@@ -16,12 +16,16 @@ cai use <workflowId>
 cai workflow status --json
 ```
 
-If no workflow exists, create and pin one:
+If no workflow exists, create it with its final name:
 
 ```bash
 cai workflow create --name "<clear outcome-oriented name>" --json
 ```
 
+Read `selected`, `effectiveWorkflowId`, and `pinSource` from the result; creation does not guarantee that the new workflow won the effective pin. If `selected` is false, rerun without `--workflow` when `pinSource` is `flag`; otherwise run `cai use <id>` for a stored pin or clear an inherited `CAI_WORKFLOW` pin in the parent environment, then re-check context. Use `cai config reset` to clear stale stored pins; it cannot clear an environment pin. `cai doctor` verifies that the effective workflow pin and its development head are readable. Do not create and then rename: `workflow create --name` submits the name directly.
+
+A new workflow already ships with one empty flow. Rename that flow and build in it — do not add a second flow for the first piece of work; only add flows for genuinely separate canvases. A stray empty "Flow 1" left behind is clutter the user has to clean up.
+
 Use IDs returned by the CLI. Never invent workflow, flow, node, prop, event, field, route, or connection identifiers.
 
 To orient inside a workflow, prefer one call over many:
@@ -38,8 +42,9 @@ It returns the whole map compactly — every flow with typed inputs/outputs, its
 2. Inspect the current workflow before editing: `cai workflow outline`, then `cai flow get <flowId>` for the flows you will touch.
 3. Create or select a flow. Define flow inputs and outputs before nodes that derive props from them.
 4. Build in execution order. After each material change, read it back with the corresponding `get`, `props`, `status`, or `list` command.
-5. Test on the development rail. Debug every failed or suspicious node; a green top-level status alone is insufficient.
-6. Re-read `cai workflow status`. Publish only when the user asked for a live change or clearly authorized deployment.
+5. After a headless build, run `cai flow layout <flowId>` once per changed flow at the end; an open builder auto-tidies itself.
+6. Test on the development rail. Debug every failed or suspicious node; a green top-level status alone is insufficient.
+7. Re-read `cai workflow status`. Publish only when the user asked for a live change or clearly authorized deployment.
 
 For multi-domain work, read [references/command-map.md](references/command-map.md) before editing.
 
@@ -59,18 +64,18 @@ Load the narrow skill when the task reaches that surface:
 ## Lifecycle rules
 
 - All graph edits target development. Live remains unchanged until `cai workflow publish`.
-- Prefer `--json` for decisions and IDs; human tables are for presentation.
+- Prefer `--json` for decisions and IDs; human tables are for presentation. If human output looks odd, re-run the same read with `--json` before acting.
 - A workflow contains flows; a flow is one canvas. Do not confuse their IDs.
-- For flow inputs, pass a human `--display` label and capture the returned `jsBinding`. The server derives, deduplicates, and then freezes that binding; `--name` is only a legacy display alias and renaming the label does not rename expressions.
+- For flow inputs, pass a human `--display` label and use the compiler-current binding from the latest `cai flow get` (`jsBinding`) or `cai workflow outline` (`binding`). An input rename can change it: re-read bindings after every rename and never cache their spellings across renames. `legacyBinding` is diagnostic-only; never use it in expressions.
 - Name nodes after the data they produce. Downstream input bindings are seeded from that name when wired.
-- Use `cai workflow save --name "<checkpoint>"` before a risky rewrite when version history is available.
-- **Edit the graph with git-like freedom.** Every save is a version state — `cai workflow history` lists them, `cai workflow restore <stateId>` is the undo. Duplicate, delete, and refactor boldly; nothing inside the graph is unrecoverable. Restore rolls back the DEFINITION (graph and schemas) only — record data is unversioned and stays as it is. External side effects (sent messages, provider calls) are equally outside the undo.
+- Use `cai workflow save --name "<checkpoint>"` before a risky rewrite. Named saves and state renames work on every plan.
+- **Edit the graph with a plan-aware safety net.** Each save is a version state. `cai workflow history` has no age cutoff on Free, Max, or custom plans and a 90-day window on Pro/Starter; expand a group with `cai workflow history --group <groupId>` to get its state IDs. Restore with `cai workflow restore --state <stateId>` within 7 days on Free, 90 days on Pro/Starter, or without an age limit on Max/custom. Duplicate, delete, and refactor with that window in mind. Restore rolls back the DEFINITION (graph and schemas) only — record data is unversioned and stays as it is. External side effects (sent messages, provider calls) are equally outside the undo.
 - **Validate after structural edits, don't ask permission before them.** After deleting a flow, deleting a type, or a large refactor — and before publish — run `cai workflow validate` and fix what it lists: unlinked subflow callers, dangling type references, branch problems, trigger issues. Deleting a flow deletes its nodes, edges, inputs/outputs, and attached triggers, and breaks callers in other flows — exactly like deleting a function breaks its call sites; validate shows every break.
 - On a conflict, re-read current state and reapply intent. Do not replay stale IDs or whole documents.
 - Never delete a workflow without the user's explicit intent; the CLI requires `--yes` but that is not a substitute for authorization. `cai workflow delete` tears down deployed triggers and soft-deletes the workflow row. Historical workflow/version data remains stored, but there is currently no CLI restore command for the deleted row.
 - **Know the dependency graph before deleting or refactoring shared resources.** `cai deps` shows which agents attach this workflow as a tool (LIVE or draft), which workflows call it, and which connections it uses; `cai deps --account` maps the whole account. Deleting a workflow that agents depend on is refused with the dependents named — bring that list to the user, then `--force` only on their informed choice (a LIVE agent changes behavior immediately).
 - **Check the account feed when recent activity matters.** `cai events` lists what happened in the account, newest first: connections created, workflow edits/publishes/runs, agents created/published, members added. Filter with `--type` (comma-separated), `--since 30m|2h|7d|<ISO>`, `--for-workflow <id>`; page with `--cursor`. Typical uses: `cai events --type connection.created --since 10m` to see whether the user finished connecting, `cai events --since 24h` to catch up at session start, `cai events --for-workflow <id> --type workflow.run` for recent run activity. The feed cannot show connection deletions, settings changes, or member removals — absence there proves nothing.
-- **Share the platform, not just text.** At the right moments, hand the user the real product page — command outputs include `appUrl` when the app origin is known: after `workflow publish` (the live builder view), after `run flow`/`run node` (the run page, to follow along), after `agent publish`/`test` (agent and conversation pages), and `connection connect` prints the connect link (use `--wait` to continue automatically once they connect). When the user asks for a link at any other time, don't guess URLs: `cai workflow get`, `cai workflow status`, and `cai agent get` include `appUrl`. When you cannot perform something (settings, product-only surfaces), give the link instead of apologizing.
+- **Share the platform, not just text.** At the right moments, hand the user the real product page — command outputs include `appUrl` when the app origin is known: after `workflow publish` (the live builder view), after development `run flow`/`run node` (the run page; live flow runs omit it), after `agent publish`/`test` (agent and conversation pages), and `connection connect` prints the connect link (use `--wait` to continue automatically once they connect). When the user asks for a link at any other time, don't guess URLs: `cai workflow get`, `cai workflow status`, and `cai agent get` include `appUrl`. When you cannot perform something (settings, product-only surfaces), give the link instead of apologizing.
 - Never silently weaken the request to make a test pass. Report an unsupported capability or ask about a real product decision.
 
 ## Completion gate

package/skills/controllerai-workflows/references/command-map.md

@@ -7,6 +7,7 @@ Read only the sections relevant to the requested work. Use `cai <domain> --help`
 ```text
 cai connect
 cai doctor
+cai config reset [--local|--global]
 cai auth status
 cai workflow list|create|get|rename|describe|duplicate|delete
 cai workflow state|status|versions|releases|history|save|restore|publish
@@ -18,7 +19,7 @@ cai use <workflowId>
 ## Canvas and graph
 
 ```text
-cai flow list|get|create|rename|duplicate|delete|reorder
+cai flow list|get|create|rename|duplicate|delete|reorder|layout
 cai flow input add|update|delete
 cai flow output add|update|delete
 cai node find|search|components|component
@@ -27,7 +28,7 @@ cai node init|status|get|props|set|connect|disconnect|delete
 
 Declare flow outputs before adding a Return response node. Its props are derived from those outputs.
 
-`cai flow input add <flowId> --display "<human label>" --type <type>` returns the exact frozen `jsBinding`. Copy it or re-read expression context; never infer it from the label after deduplication.
+`cai flow input add <flowId> --display "<human label>" --type <type>` returns the compiler-current `jsBinding`. Use the latest value from `flow get` (`jsBinding`) or `workflow outline` (`binding`), re-read it after every input rename, and never cache its spelling across renames. `legacyBinding` is diagnostic-only.
 
 ## Conditions and composition