@controllerai/cli 0.2.20 → 0.2.22

package/skills/controllerai-node-config/references/command-reference.md

@@ -1,186 +0,0 @@
-# Controller AI node configuration
-
-
-A node is ready only after its component, connection, dependency-ordered props, wiring, and output type are valid. Treat configuration as a state machine, not a bag of property writes.
-
-## Deterministic sequence
-
-### 1. Find an exact component
-
-```bash
-cai integration actions "<capability>" --json
-cai integration action --integration <nodeSlug> --key <nodeKey> --json
-```
-
-Use the returned `nodeSlug` and full `key`. Do not infer a component key from its display name. If discovery is broad, narrow it with:
-
-```bash
-cai integration search "<integration>" --actions --json
-cai integration actions "<action>" --integration <nodeSlug> --json
-```
-
-Inspect static prop metadata before creating the node. `required`, `remoteOptions`, and `reloadProps` determine configuration order.
-
-### 2. Resolve the account
-
-If the component requires auth:
-
-```bash
-cai connection list --node <nodeSlug> --json
-```
-
-- One active connection: use its exact `id` as the `connectionId`.
-- Several: use an explicit user preference; otherwise ask which account.
-- None: add the real component without `--connection`; `missingConnection: true` is a valid handoff state. On CLI, get the link with `cai connection connect <nodeSlug> --no-open` and share it right away; do not block on `--wait` before sharing.
-
-  MCP: call `connection_connect_url` with `nodeSlug`, show its `url` as a markdown link, ask the user to finish, then confirm with `connection_list` using its `integration`.
-
-  After they confirm, run `cai connection list --integration <nodeSlug> --json` and bind the new ID with `cai node set-connection <nodeId> --connection <connectionId>`.
-
-Never substitute a connection from a similar slug.
-
-Rename or change the default with `cai connection update <id> [--name "<displayName>"] [--default|--no-default]` (MCP: `connection_update`); delete only intentionally with `cai connection delete <id> --yes` (MCP: `connection_delete`).
-Deleting a connection immediately removes authorization from bound nodes and agent tools.
-
-A missing connection is never a reason to substitute `registry_http-http-request` for a catalog component. A raw endpoint mentioned by the user is background context, not an instruction to hand-roll the call.
-
-### 3. Initialize once
-
-```bash
-cai node init \
-  --flow <flowId> \
-  --node <nodeSlug> \
-  --key <nodeKey> \
-  --name "<data this node produces>" \
-  --connection <connectionId> \
-  --after <upstreamNodeId> \
-  --json
-```
-
-MCP: use `node_add`; `cai node init` is the CLI alias of `cai node add`.
-
-Omit flags that do not apply. `--after` creates the ordinary main/error wire at creation. Use it when later props need upstream data. Initialization also accepts `--props`, but use it only for static, non-option values already present in the inspected component metadata. Never inline a `remoteOptions` value, a reload selector and its dependents, or a prop that has not materialized yet; initialize first and set those sequentially. Use `--enable-prop <name...>` only for optional props confirmed by component metadata.
-
-Capture the returned `nodeId`; do not rediscover it by name. Inspect the complete create result before projecting fields. A missing projection is not proof that creation failed, so read the captured ID or exact flow inventory before any retry.
-
-When repairing an existing node, keep its node ID and configure it in place. Do not delete and recreate it merely to clear bad props, select a component, or refresh generated props; deletion discards wiring, conditions, and identity-based references. Replace it only when the requested component itself must change. Then capture the replacement ID, reconnect every dependent, and revalidate them.
-
-### 4. Follow readiness, not guesses
-
-```bash
-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
-2. Required selector props with `reloadProps`
-3. Newly revealed required props
-4. Static and remote-option props
-5. Wiring required for expressions
-6. Expressions
-7. Unresolved output type
-
-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
-
-Static value:
-
-```bash
-cai node set <nodeId> --prop <exactName> --value '<literal-or-json>' --json
-```
-
-MCP: use `node_prop_set` with `value`; it also handles expression writes through `js`.
-
-Optional prop:
-
-```bash
-cai node optional-props <nodeId> --json
-cai node set <nodeId> --prop <exactName> --value '<literal-or-json>' --json
-# or: cai expr set <nodeId> --prop <exactName> --js '<expression>' --json
-```
-
-MCP: `cai expr set` is the `js` form of `node_prop_set`.
-
-`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.
-
-MCP: use `node_optional_prop_set` with `enabled: false` to disable or `enabled: true` to enable.
-
-Remote or dynamic option:
-
-```bash
-cai node options <nodeId> --prop <exactName> --query "<specific label>" --json
-cai node set <nodeId> \
-  --prop <exactName> \
-  --value '<returned value>' \
-  --label '<returned label>' \
-  --json
-```
-
-`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: it is used to search providers that do not index opaque IDs, then the returned value is verified before writing. For a multi-select, pass a JSON array of returned values and one `--label` argument per value, in the same order. The write 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`.
-
-### 6. Wire and verify
-
-Ordinary outputs:
-
-```bash
-cai node connect --flow <flowId> --from <sourceNodeId> --to <targetNodeId> --output main --json
-```
-
-Use `--output error` only for the automatic error path. Router and If/Else outputs require `cai branch connect` from the flow-control skill.
-
-Finish with:
-
-```bash
-cai node status <nodeId> --json
-cai run node <nodeId> --inputs <values.json> --json
-```
-
-MCP: `run_node` takes the parsed `inputs` object and `waitSeconds` (default 60, max 120).
-
-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.
-
-MCP: `run_flow` takes the parsed `inputs` object and `waitSeconds` (default 60, max 120).
-
-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
-```
-
-MCP: call `node_output_type_declare` with the parsed provider response in `sample`; the server cannot read `provider-response.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 [prop-and-readiness.md](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`.
-- 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. Declare only a documented provider sample; never fabricate an output schema.

package/skills/controllerai-runs/references/command-reference.md

@@ -1,113 +0,0 @@
-# Controller AI runs
-
-
-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
-
-Use the task's existing authorization and a safe test target for actions with external consequences. For authorized CRUD testing, create synthetic records and exercise updates/deletion on those. Ask only when a needed external side effect or target is not covered by the user's request. Test runs execute real actions.
-
-## First live run is part of development
-
-After publishing, run the published version directly under supervision:
-
-```bash
-cai run flow <flowId> --inputs values.json --target live --confirm-live --json
-```
-
-MCP: pass parsed values in `inputs` and set `waitSeconds` on `run_flow`.
-
-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
-
-```bash
-cai run inputs <nodeId> --json
-cai run inputs <flowId> --flow --json
-```
-
-Use returned opaque input IDs. Flow mode lists EVERY declared input with a `used` flag: supply the used ones (an unsupplied used input falls back to its saved test value), while values keyed to unused inputs are accepted and ignored. The input object can be a flat map; the CLI may load it from a file:
-
-```json
-{
-  "<inputId>": "representative value"
-}
-```
-
-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:
-
-```bash
-cai run node <nodeId> --inputs values.json --json
-cai run flow <flowId> --inputs values.json --json
-```
-
-MCP: pass parsed values in `inputs` and set `waitSeconds` on `run_node` or `run_flow`.
-
-`run node` is deliberately isolated: it does not execute wired upstream nodes. Read its `runScope`. If `endToEndValidationRequired` is true, values derived from upstream can be empty even when the selected node is green; do not accept that run as expression proof. `run flow` is the end-to-end check that executes upstream wiring.
-
-The CLI waits for a terminal execution state by default. MCP polling is bounded by `waitSeconds` and may return an unfinished execution ID. Capture `workflowExecutionId` and `nodeExecutionId` from the result.
-
-For every node test, inspect:
-
-- `status` and `errorMessage`
-- `skipReason`
-- `runScope`, especially `upstreamNodesExecuted` and `endToEndValidationRequired`
-- `resolvedConfigs`
-- `resolvedConfigs[].resolutionWarnings`: trust every structured entry; `[]` is authoritatively clean. Also read any transport warnings; CLI runs may mirror them on stderr.
-- `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
-
-A dynamic prop with a null/empty resolved config is a failure even when status is green. `0` and `false` are valid resolved values.
-
-## Debug from the execution tree
-
-```bash
-cai exec tree <workflowExecutionId> --limit 50 --json
-cai exec get <workflowExecutionId> --json
-cai exec flow <flowExecutionId> --json
-cai exec node <nodeExecutionId> --full --json
-```
-
-Page with the returned `nextCursor` via `--cursor`; narrow large runs with repeatable `--status`
-or `--flow <flowId>`. Use the tree to locate the first unexpected status. Use the full node
-execution to inspect its status, resolved configuration, and untruncated output. Read
-[debugging.md](debugging.md) for the fault-isolation order.
-
-## Output discovery
-
-Prefer a configured node test. If a component is not yet in the graph, `run discover` creates a scratch node and deletes it after execution:
-
-```bash
-cai run discover \
-  --node <nodeSlug> \
-  --key <nodeKey> \
-  --connection <connectionId|none> \
-  --props '<json>' \
-  --json
-```
-
-MCP: `run_discover` always removes the scratch graph and exposes neither `keep` nor `waitSeconds`.
-
-This calls the real third-party action and spends usage. For a destructive action, do not probe merely to learn its output — first ask the user for a safe target (see "Consequential actions" above); if they decline, declare the expected shape instead. On CLI, use `--keep` only when the user wants the scratch node retained.
-
-After successful output discovery, re-read `cai node status` and downstream `cai expr context`; verify the adopted output type is concrete.
-
-## Completion gate
-
-- CLI scripts may gate on `cai workflow validate` exiting 1; MCP callers inspect `valid` and `errors`.
-- 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.
-- Output fields and types match downstream expectations.
-- Branch skips are intentional and error paths are accounted for.
-- A full flow test passes after isolated node fixes.
-- `completed` with an empty or null output is treated as a failure until the output values are read and explained — an empty result usually means a mis-mapped input or an expression that null-propagated silently.
-- The final report cites execution IDs and distinguishes development testing from live verification.

package/skills/controllerai-triggers/references/command-reference.md

@@ -1,215 +0,0 @@
-# Controller AI triggers
-
-
-A trigger targets exactly one flow. Its source may capture events before publish, but ordinary event execution uses the live workflow. Creating the source is therefore separate from mapping, development testing, publishing, and live replay.
-
-
-- Preserve trigger ID and source during repair; see Create and map.
-- Delete a retired start; disable a reversible pause. See Remove or disable an automatic start.
-- Lifecycle uses `--enable|--disable`; test events use `--allow|--disallow`. See Remove or disable an automatic start and Finish trigger setup.
-- Disarm capture when setup ends; see Finish trigger setup.
-- Lifecycle edits are development-only; publish only for Live. See Verify development, then publish.
-- Replay with `--target dev`; Live also requires `--confirm-live`. See Verify development, then publish.
-
-## Require a real source decision
-
-Determine how the trigger choice was established:
-
-- `explicit-in-request`: user named it in the request
-- `user-answer`: user chose after clarification
-- `inferred-from-existing-workflow`: preserving an existing source
-
-Do not use `assumption`; the backend rejects it. If the request does not determine when the automation runs, ask one focused question before creating a source.
-
-## Discover the exact event
-
-```bash
-cai trigger search "<event intent>" --json
-cai trigger search --node <nodeSlug> --events-per-node 50 --json
-```
-
-Copy the exact `nodeSlug` and `eventKey`. Never infer an event key from its display name.
-
-If authentication is required:
-
-```bash
-cai connection list --node <nodeSlug> --json
-cai connection connect <nodeSlug>
-```
-
-MCP: call `connection_connect_url`; it returns the URL immediately and has no `open` or `wait` parameter.
-
-## Resolve trigger props
-
-```bash
-cai trigger props \
-  --node <nodeSlug> \
-  --event <eventKey> \
-  --connection <connectionId> \
-  --json
-```
-
-Use the returned shape-correct `propsExample` as a starting point. Hidden props remain unset. `readyForCreate` must be true before using it in `trigger create`; the response intentionally omits unresolved required option props rather than emitting a plausible placeholder.
-
-For each name in `unresolvedOptionProps`, run the complete canonical option command returned by the transport, or equivalently:
-
-```bash
-cai trigger options \
-  --node <nodeSlug> \
-  --event <eventKey> \
-  --prop <propName> \
-  --connection <connectionId> \
-  --configured '<configuredPropsJson>' \
-  --dynamic-props-id <dynamicPropsId> \
-  --query "<human option label>" \
-  --json
-```
-
-Copy the exact returned `value`, not its display `label`, into `--configured`, then rerun `trigger props`. Use `--page` and returned `context` via `--prev-context` only when search is unavailable.
-
-When a selector has `reloadProps`, rerun with its configured values and returned `dynamicPropsId` before creating the trigger.
-
-```bash
-cai trigger props \
-  --node <nodeSlug> \
-  --event <eventKey> \
-  --connection <connectionId> \
-  --configured '<configuredPropsJson>' \
-  --dynamic-props-id <dynamicPropsId> \
-  --json
-```
-
-Keep the same node, event, connection, and configured values on every reload, but always pass the LATEST `dynamicPropsId` the backend returned — a reload can mint a new ID, and reusing a stale one resolves against a stale schema. The response provides the complete canonical command; do not shorten it to only `--configured`.
-
-Timer values are objects:
-
-```json
-{"cron":{"cron":"0 9 * * *","timezone":"America/Chicago"}}
-```
-
-or
-
-```json
-{"cron":{"intervalSeconds":900}}
-```
-
-Do not pass a bare cron string or assume a timezone. Ask when the user says "at 9am" without one.
-
-## Create and map
-
-```bash
-cai trigger create \
-  --flow <targetFlowId> \
-  --node <nodeSlug> \
-  --event <eventKey> \
-  --source-basis <basis> \
-  --connection <connectionId> \
-  --props '<json>' \
-  --dynamic-props-id <id> \
-  --json
-```
-
-Capture all returned IDs. `triggerId` is the canvas ID used for get/rename/set-enabled/delete/test-events. `backendTriggerId` is numeric and used for captured events and replay. They are not interchangeable.
-
-When repairing an existing trigger, preserve its canvas ID and source. Repair its mapping in place; do not delete and recreate it merely to clear readiness. Replacement changes captured IDs and may change a webhook URL. Replace only when the requested source itself must change, then recapture every returned ID.
-
-Read a single trigger back with `cai trigger get <triggerId> --json` — the full record: node, event, connection, props, lifecycle. Read-back is always `get`; the CLI has no `describe` read command anywhere (`cai workflow set-description` is a setter).
-
-Follow returned `nextSteps` in order. Trigger payload does not automatically populate the target flow; define flow inputs, relink the run-subflow node if needed, and configure its mapping props.
-
-## Remove or disable an automatic start
-
-`cai trigger delete <triggerId>` removes the automatic start from the development canvas; use it when the start should no longer exist. Never delete its owning flow merely to remove the trigger. `cai trigger set-enabled <triggerId> --enable|--disable` changes the enabled state reversibly and idempotently; pass exactly one state flag.
-
-MCP: call `trigger_set_enabled` with `enabled: true` or `enabled: false`.
-
-Both are development edits. Publish only for an authorized Live change; otherwise the prior Live trigger remains active.
-
-## Establish a typed sample
-
-After sending a representative event to the source:
-
-```bash
-cai trigger events --trigger <backendTriggerId> --json
-cai trigger event <eventId> --json
-cai trigger select-event --node <triggerNodeId> --event <eventId> --json
-```
-
-Then re-read expression context on downstream nodes. A sample without a platform data type may remain untyped.
-
-## Finish trigger setup: disarm test events
-
-Armed test events let real events reach the DEV version while you set the trigger up. They exist for one purpose: capturing the real data shape so it becomes the trigger node's output type. Arming is the START of trigger setup; **disarming is how trigger setup ENDS.** Once the shape is captured, selected, and typed, turn it off — also when a build fails or is abandoned midway:
-
-```bash
-cai trigger test-events --id <triggerId> --disallow
-```
-
-MCP: call `trigger_test_events_set` with `allowed: false`, or `allowed: true` to arm it.
-
-Do not mix the flag families. `set-enabled` takes `--enable` or `--disable`; `test-events` takes `--allow` or `--disallow`; replay takes `--target dev` or `--target live`, with `--confirm-live` for Live.
-
-The acknowledgements are distinct: `--acknowledge-dual-run` applies only while arming, `--acknowledge-dual-dispatch` only while publishing an armed trigger, and `--confirm-live` only to one Live replay.
-
-Arming is sticky and independent from enablement. Armed plus live dispatch runs each real event twice; a schedule does so every interval. Disabling does not clear the allow flag, so always disallow after capture.
-
-Keeping both rails armed is an uncommon user decision, never a default.
-
-## Verify development, then publish
-
-Use `cai run flow` for direct development verification, then replay one captured event through the development trigger path. MCP `run_flow` calls take `waitSeconds`.
-
-```bash
-cai trigger replay --trigger <backendTriggerId> --event <eventId> --target dev --json
-cai exec tree <workflowExecutionId> --json
-```
-
-A development replay never dispatches live, but nodes still call real providers and can create side effects or spend usage. Publish only after mappings and development behavior pass.
-
-A draft-only request stops after development proof. Do not publish merely because the trigger is ready.
-
-Before publishing, audit EVERY trigger in the workflow — not just the one you worked on. Users forget triggers left enabled or armed in other flows. Read each row's lifecycle fields from `cai trigger list --json` (`devCanvasEnabled`, `deployment.liveCanvasEnabled`, `deployment.inLiveVersion`, `deployment.devDispatchArmed`, `deployment.dualDispatchLive`) and confirm with the user which triggers should be starting this workflow live:
-
-```bash
-cai trigger list --json
-cai workflow publish --name "<release>" --json
-```
-
-If publish fails because a trigger still has test events armed, that error is the designed backstop, not a malfunction: trigger setup was never finished. The normal resolution is to disarm and republish. Publishing WITH an armed trigger requires the user's explicit, informed choice — explain the double-run and double-billing consequence first, then pass the intent flag:
-
-```bash
-cai workflow publish --name "<release>" --acknowledge-dual-dispatch --json
-```
-
-Never pass `--acknowledge-dual-dispatch` on your own initiative.
-
-Live replay is optional and requires an explicit acknowledgement:
-
-```bash
-cai trigger replay \
-  --trigger <backendTriggerId> \
-  --event <eventId> \
-  --target live \
-  --confirm-live \
-  --json
-cai exec tree <workflowExecutionId> --json
-```
-
-It executes the published workflow, calls live third-party actions, and spends usage. Obtain appropriate user intent before replaying a side-effectful event.
-
-Read [lifecycle.md](lifecycle.md) for trigger state and debugging.
-
-## Before you finish
-
-```bash
-cai trigger get <triggerId> --json
-cai trigger list --json
-cai workflow status --json
-# Only after an authorized create or mapping test:
-cai exec tree <workflowExecutionId> --json
-```
-
-- Read-back must retain the intended trigger, source, target flow, connection, props, and mapping.
-- `devCanvasEnabled`, `liveCanvasEnabled`, and `inLiveVersion` must match the requested rail state.
-- `devDispatchArmed` must be false unless the user explicitly chose dual dispatch; report `dualDispatchLive`.
-- For authorized create/mapping work, the development test must produce the expected tree. Never replay for delete/disable-only work. Live replay needs separate authorization.

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

@@ -1,118 +0,0 @@
-# Controller AI workflows
-
-
-
-- Lock the effective workflow ID and exact flow ID; see Establish context.
-- Repair the selected workflow and flow instead of creating replacements; see Build protocol.
-- Keep workflow, flow, node, input, and output IDs distinct; see Lifecycle rules.
-- Preserve contract fields in place and refresh their dependents; see Lifecycle rules.
-- Use save, history, and restore for recovery instead of rebuilding; see Lifecycle rules.
-- Treat validation counts as status; prove the requested rail and stop. See Lifecycle rules and Before you finish.
-
-## Establish context
-
-```bash
-cai auth status --json
-cai workflow list --json
-cai use <workflowId>
-cai workflow status --json
-```
-
-MCP: use `account_status`, then call `workflow_list` and `workflow_status` with explicit `workflowId`; there is no `cai use` or stored pin.
-
-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`; creation may not win the pin. If unselected, remove a command flag, use `cai use <id>` for a stored pin, or clear inherited `CAI_WORKFLOW`, as `pinSource` directs, then re-check. `cai config reset` clears only stored pins. `cai doctor` verifies the effective pin and development head. On MCP, capture and pass the new `workflowId`. Create with the final name.
-
-After `cai workflow create`, check `flowCount` in the output. If it is 0 (or the field is missing, run `cai flow list --json`), create the first flow with `cai flow create --name "<name>" --json`. If one empty flow already exists, rename it and build in it. Never add a second flow for the first piece of work; add flows only for genuinely separate canvases.
-
-Use IDs returned by the selected transport. For account-wide lists, filter by exact ID or name and owning workflow; never choose the first or latest similar result. Read the selected object's ID, name, and owner once, reuse those IDs, and never rediscover the target by name. A missing projected create field is not failure: inspect the complete result and exact inventory before retrying. Never invent identifiers.
-
-To orient inside a workflow, prefer one call over many:
-
-```bash
-cai workflow outline --json
-```
-
-`cai workflow state --json` is bounded; add `--flow <flowId>` for node and edge identities. Use `workflow document` only for complete opaque JSON. `workflow outline` shows flows, contracts, graph `deps`, triggers, and data inventory. Use `flow get` for props and expressions.
-
-## Build protocol
-
-1. Translate the request into inputs, steps, outputs, trigger, integrations, failure behavior, and publish intent. When the request says to store, save, log, or record something and names no external destination, that means a data type plus a create-record node (`controllerai-data`) — a flow output alone does not persist anything. When the user names the destination (a spreadsheet, a CRM, another app, a file), write there with that integration's node instead; add a platform record only when the user also wants a copy kept here.
-2. Inspect the current workflow before editing: `cai workflow outline`, then `cai flow get <flowId>`. Repair those IDs; do not create replacements for a repair.
-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. Run `cai flow layout <flowId>` once per changed flow as the LAST step after a headless build or any batch of structural edits (adds, deletes, rewires) — add-time placement avoids overlap, but only layout produces clean left-to-right columns. An open builder adopts your layout automatically.
-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 [command-map.md](command-map.md) before editing.
-
-## Route specialized work
-
-Load the narrow skill when the task reaches that surface:
-
-- Node discovery, initialization, connections, props, or wiring: `controllerai-node-config`
-- Dynamic values or conditions: `controllerai-expressions`
-- Router, If/Else, loops, joins, or subflows: `controllerai-flow-control`
-- Test execution or debugging: `controllerai-runs`
-- Scheduled, webhook, or integration events: `controllerai-triggers`
-- Schemas or records: `controllerai-data`
-- Ask AI or Agent nodes: `controllerai-ai-nodes`
-- User-facing agents and their workflow tools: `controllerai-agents`
-
-## Lifecycle rules
-
-- All graph edits target development. Live remains unchanged until `cai workflow publish`.
-- Email verification is not a publishing prerequisite. An unclaimed agent-created account may publish; email claiming only raises its monthly usage cap and enables account recovery.
-- On the CLI, prefer `--json` for decisions and IDs; human tables are for presentation. MCP tools return typed JSON. 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 use the current binding from `flow get` (`jsBinding`) or `workflow outline` (`binding`). Rename an existing contract input or output in place; do not delete and recreate it. After any rename or deletion, re-read the flow and repair every expression and subflow mapping before validation or execution. `legacyBinding` is diagnostic-only.
-- 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. Named saves and state renames work on every plan.
-
-```bash
-cai workflow history --json
-cai workflow history --group <groupId> --json
-cai workflow restore --state <stateId> --json
-```
-
-- **Use version history for recovery.** Each save is a state. History retention is unlimited on Free, Max, and custom plans and 90 days on Pro/Starter; restore eligibility is 7 days on Free, 90 on Pro/Starter, and unlimited on Max/custom. Expand groups to capture state IDs. Restore rolls back the definition only; records and external effects remain.
-- **Validate after structural edits and before publish.** Fix every listed prop, wire, expression, type, subflow, branch, and trigger error. Publish refuses errors; use `--acknowledge-validation-errors` only after explicit approval of the listed issues. Flow deletion also removes its contract, graph, and triggers and breaks callers; validation shows each break.
-- Treat validation warning and error counts as status only. Never write them or their messages into unrelated workflow properties.
-- 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. MCP: `workflow_delete` has no `yes` parameter, but still requires the same explicit intent. `cai workflow delete` tears down deployed triggers and soft-deletes the workflow row. Historical workflow/version data remains stored, but there is currently no restore command for the deleted row.
-- **Check dependencies before shared-resource changes.** `cai deps` shows attached agents, workflow callers, and connections; `cai deps --account` maps the account. Deleting a workflow with agent dependents is refused server-side, and `--force` is a deprecated, inert compatibility flag. Detach draft tools with `cai agent remove-tool <agentId> --tool <toolId>`. If still LIVE, use `cai agent publish <agentId>` after explicit approval. A dependent agent publish or delete is its own live/destructive decision. Then retry deletion.
-- **Use the account feed only for recorded history.** Filter `cai events` by type, time, workflow, and cursor. It omits deletions, settings, member removals, and labels. For an unrecorded past change, say it is not recorded and change nothing; names and current state are not proof.
-- **Share real product links.** Relevant publish, development run, agent, connection, workflow get/status, and agent get outputs include `appUrl` when known. Share returned links; never guess one. MCP `connection_connect_url` returns its link immediately.
-- Never silently weaken the request to make a test pass. Report an unsupported capability or ask about a real product decision.
-
-## Before you finish
-
-Before claiming success, verify all of the following:
-
-```bash
-cai workflow outline --json
-cai workflow validate --json
-cai workflow status --json
-cai flow get <flowId> --json
-cai run flow <flowId> --inputs <values.json> --json
-```
-
-MCP: pass the parsed values in `inputs` and set `waitSeconds` on `run_flow`.
-
-Then confirm:
-
-- **`cai workflow validate` reports `errors: 0`.** Every error is fixed, or explicitly reported to the user with what it breaks — never summarized away, never called cosmetic. A red canvas and a "done" claim cannot coexist.
-- Required node connections and props are complete.
-- Expressions compiled and their resolved configs are non-null.
-- Expected branch or error paths were exercised where practical.
-- Flow outputs contain the promised values.
-- The reported live/dev state matches what the user asked for.
-- Final outline inventory matches the request. Remove only scratch schemas, flows, nodes, and triggers created during abandoned attempts.
-
-State what was built, what was tested, whether it was published, and any user-owned connection or product choice still pending.