@controllerai/cli 0.2.0

package/skills/controllerai-workflows/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: controllerai-workflows
+description: Build, inspect, edit, test, recover, and publish Controller AI workflows through the cai CLI. Use when a user asks to create or change an automation, workflow, flow, or workflow release, or when another Controller AI skill needs the shared lifecycle and safety rules.
+---
+
+# Controller AI workflows
+
+Use `cai` as the control surface. Do not call Controller AI REST or MCP routes directly unless the CLI reports that a required capability is absent.
+
+## Establish context
+
+```bash
+cai auth status --json
+cai workflow list --json
+cai use <workflowId>
+cai workflow status --json
+```
+
+If no workflow exists, create and pin one:
+
+```bash
+cai workflow create --name "<clear outcome-oriented name>" --json
+```
+
+Use IDs returned by the CLI. Never invent workflow, flow, node, prop, event, field, route, or connection identifiers.
+
+## Build protocol
+
+1. Translate the request into inputs, steps, outputs, trigger, integrations, failure behavior, and publish intent.
+2. Inspect the current workflow before editing: `cai workflow get`, `cai flow list`, then `cai flow get <flowId>`.
+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.
+
+For multi-domain work, read [references/command-map.md](references/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`.
+- Prefer `--json` for decisions and IDs; human tables are for presentation.
+- 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.
+- 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.
+- **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 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
+
+Before claiming success, verify all of the following:
+
+```bash
+cai workflow status --json
+cai flow get <flowId> --json
+cai run flow <flowId> --inputs <values.json> --json
+```
+
+Then confirm:
+
+- 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.
+
+State what was built, what was tested, whether it was published, and any user-owned connection or product choice still pending.

package/skills/controllerai-workflows/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Controller AI Workflows"
+  short_description: "Build and edit Controller AI workflows safely"
+  default_prompt: "Use Controller AI to build or edit this workflow, verify it, and keep live unchanged until I ask to publish."

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

@@ -0,0 +1,64 @@
+# Workflow command map
+
+Read only the sections relevant to the requested work. Use `cai <domain> --help` as the authoritative flag reference.
+
+## Setup and workflow lifecycle
+
+```text
+cai connect
+cai doctor
+cai auth status
+cai workflow list|create|get|rename|describe|duplicate|delete
+cai workflow state|status|versions|releases|history|save|restore|publish
+cai use <workflowId>
+```
+
+`workflow save` creates a named development checkpoint. `workflow publish` promotes development to live. Version history may be plan-gated. `workflow delete --yes` undeploys triggers and soft-deletes the workflow row; it is not a permanent history purge, and deleted rows currently have no CLI restore command.
+
+## Canvas and graph
+
+```text
+cai flow list|get|create|rename|duplicate|delete|reorder
+cai flow input add|update|delete
+cai flow output add|update|delete
+cai node find|search|components|component
+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.
+
+## Conditions and composition
+
+```text
+cai node only-when
+cai branch list|add|update|delete|connect|reorder
+cai flow for-each
+cai node set-flow
+```
+
+Use branch-specific connection commands for Router and If/Else outputs. Generic `node connect` supports only `main` and `error` outputs.
+
+## Verification
+
+```text
+cai run inputs|node|flow|discover
+cai exec list|get|flow|node|ports|tree
+```
+
+`run discover` executes the real integration action in a scratch flow and can incur third-party effects or usage. Do not use it casually for mutating actions.
+
+## Product surfaces
+
+```text
+cai connection list|connect
+cai trigger list|get|search|props|options|create|events|event|select-event|replay|toggle|rename|delete
+cai schema list|get|resolve|create|update|delete
+cai data collections|fields|query|get|create|update|delete|delete-many|import|copy-to-live
+cai agent list|get|create|update|add-workflow|remove-tool|add-file|tools|publish-preflight|publish|versions|visibility
+cai agent conversation list|create|status|history|send|approve|deny
+```
+
+Connections are authorized in a browser. The CLI returns and opens the Controller AI connection URL.
+Agent visibility supports only `private` and `organization`; organization is an explicit live access change after agent publish.

package/skills/manifest.json

@@ -0,0 +1,248 @@
+{
+  "schemaVersion": 1,
+  "skillSetVersion": "2026.08.09.13",
+  "minCliVersion": "0.2.0",
+  "skills": [
+    {
+      "name": "controllerai-start",
+      "files": [
+        {
+          "path": "controllerai-start/SKILL.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-start/SKILL.md",
+          "sha256": "e84ff628653b9dddec3237c838f41b8f41f62bb8f0611741fa02ebbd81bcc60b",
+          "size": 3157
+        },
+        {
+          "path": "controllerai-start/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-start/agents/openai.yaml",
+          "sha256": "3240c24df8ba5ebfb67bc3e9dbce97f4a78384c352123210197a2dbf27c51150",
+          "size": 226
+        }
+      ]
+    },
+    {
+      "name": "controllerai-workflows",
+      "files": [
+        {
+          "path": "controllerai-workflows/SKILL.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-workflows/SKILL.md",
+          "sha256": "cd63ceabd6f6ecf51b40131cfe3c837efb55f038fe2ccf6474579bf32fcba18f",
+          "size": 6842
+        },
+        {
+          "path": "controllerai-workflows/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-workflows/agents/openai.yaml",
+          "sha256": "6fb00a93a5f83fc2664679eb633ab07b477105472f8790fcf6dbcca913921a84",
+          "size": 251
+        },
+        {
+          "path": "controllerai-workflows/references/command-map.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-workflows/references/command-map.md",
+          "sha256": "d46f772188150f9058c62d84178bf454a4fceff62a03cb05e683bef6c3720587",
+          "size": 2530
+        }
+      ]
+    },
+    {
+      "name": "controllerai-node-config",
+      "files": [
+        {
+          "path": "controllerai-node-config/SKILL.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-node-config/SKILL.md",
+          "sha256": "3f8d59b12090ed4ad2211c71f482c145ef2afe2bc0331cb06200fdd40f74ca4c",
+          "size": 5494
+        },
+        {
+          "path": "controllerai-node-config/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-node-config/agents/openai.yaml",
+          "sha256": "7fbd6f0c1f9ea40c41051d532736a4718895cfa397608a2c716300bcf4256df1",
+          "size": 242
+        },
+        {
+          "path": "controllerai-node-config/references/prop-and-readiness.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-node-config/references/prop-and-readiness.md",
+          "sha256": "76094190732f07a2f636a8dce77f2209928496852f99e242df4dcce8b1ed4630",
+          "size": 4287
+        }
+      ]
+    },
+    {
+      "name": "controllerai-expressions",
+      "files": [
+        {
+          "path": "controllerai-expressions/SKILL.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-expressions/SKILL.md",
+          "sha256": "aee4184b982dd8aea3f2234133671f7791d1c0873e2de13a587bb7e3412bcdab",
+          "size": 6300
+        },
+        {
+          "path": "controllerai-expressions/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-expressions/agents/openai.yaml",
+          "sha256": "280d1f4d0a44cb5cfd3e5649e0a123b91b57b1484dcbc3a02ace988233234bc3",
+          "size": 249
+        },
+        {
+          "path": "controllerai-expressions/references/dsl-and-recipes.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-expressions/references/dsl-and-recipes.md",
+          "sha256": "2bfb219a5e3e0f2bc6d4407ff509d4df5a4b3ba1e6f90c02fa4398142f815757",
+          "size": 3677
+        }
+      ]
+    },
+    {
+      "name": "controllerai-flow-control",
+      "files": [
+        {
+          "path": "controllerai-flow-control/SKILL.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-flow-control/SKILL.md",
+          "sha256": "5e92e266a28a906e280d3c54783eefcf16cf56f525b15f956b477a0b0b1bf135",
+          "size": 7619
+        },
+        {
+          "path": "controllerai-flow-control/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-flow-control/agents/openai.yaml",
+          "sha256": "164adf3b887bf9f67bba9cd210b5b49935c29ea0f52f76325fe5df517d279592",
+          "size": 229
+        },
+        {
+          "path": "controllerai-flow-control/references/patterns.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-flow-control/references/patterns.md",
+          "sha256": "a3bb4c02fd431c29393a8172713eb9bce0b4042df11725489c923fd97ef9296b",
+          "size": 2877
+        }
+      ]
+    },
+    {
+      "name": "controllerai-runs",
+      "files": [
+        {
+          "path": "controllerai-runs/SKILL.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-runs/SKILL.md",
+          "sha256": "14b9844d3ee6b383beafcd0ad3883fcec980d85acab5bfbad2760f7f8879394d",
+          "size": 6174
+        },
+        {
+          "path": "controllerai-runs/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-runs/agents/openai.yaml",
+          "sha256": "63180f12974e19ce7b714695944608760e4132bfb88947543e52616098a88f5c",
+          "size": 234
+        },
+        {
+          "path": "controllerai-runs/references/debugging.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-runs/references/debugging.md",
+          "sha256": "080a178c8c653342c193fa262945296579d5a805f342968d09b37e3bb6d0fe5d",
+          "size": 2058
+        }
+      ]
+    },
+    {
+      "name": "controllerai-triggers",
+      "files": [
+        {
+          "path": "controllerai-triggers/SKILL.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-triggers/SKILL.md",
+          "sha256": "33ed7bcb2613b3902394f32d35b7ebf22101fa428c43abf1023e36c8c966efc0",
+          "size": 7326
+        },
+        {
+          "path": "controllerai-triggers/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-triggers/agents/openai.yaml",
+          "sha256": "56aa1bd33e54045d88002ade0c420be7bca37ac39433e6eedccef2e22bbd9515",
+          "size": 239
+        },
+        {
+          "path": "controllerai-triggers/references/lifecycle.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-triggers/references/lifecycle.md",
+          "sha256": "06e0edcd5c36d7f4f005831f08b2c9f44898f075a911a2bbd471b6c9c00986e8",
+          "size": 1890
+        }
+      ]
+    },
+    {
+      "name": "controllerai-data",
+      "files": [
+        {
+          "path": "controllerai-data/SKILL.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-data/SKILL.md",
+          "sha256": "97d9a12897b7cfeb49988ff00b71780c3d0d8448fe35e272a5f891dbf5d1d887",
+          "size": 7020
+        },
+        {
+          "path": "controllerai-data/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-data/agents/openai.yaml",
+          "sha256": "5c54b0a714086088213c679fb904a69a599374847f9aa1d6c0756172c2a2f227",
+          "size": 219
+        },
+        {
+          "path": "controllerai-data/references/data-rails.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-data/references/data-rails.md",
+          "sha256": "61cd1207eb65a9b7c8b908fb294718b67dd951070eb9ec0537028b928ee7ec70",
+          "size": 1597
+        }
+      ]
+    },
+    {
+      "name": "controllerai-ai-nodes",
+      "files": [
+        {
+          "path": "controllerai-ai-nodes/SKILL.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-ai-nodes/SKILL.md",
+          "sha256": "fcb2406e8b55a3ba657d8952daa28bb86a106e6bb2acea5837670d16eed971d2",
+          "size": 3961
+        },
+        {
+          "path": "controllerai-ai-nodes/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-ai-nodes/agents/openai.yaml",
+          "sha256": "3ba8b8bb6f0cd4b0d5675ebda0af10bb79dc7a42e394eb98479343c83da92599",
+          "size": 256
+        },
+        {
+          "path": "controllerai-ai-nodes/references/selection-and-testing.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-ai-nodes/references/selection-and-testing.md",
+          "sha256": "12fb32c422f9cec34c5830ce7dc2cf4f482b9d8b200bb11c45581a108ee81abe",
+          "size": 1639
+        }
+      ]
+    },
+    {
+      "name": "controllerai-integration-actions",
+      "files": [
+        {
+          "path": "controllerai-integration-actions/SKILL.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-integration-actions/SKILL.md",
+          "sha256": "a6a5ec228ddfd5c7b734c0b3959a5f8d817c872213d36c1745f74adb373a4bf4",
+          "size": 4955
+        },
+        {
+          "path": "controllerai-integration-actions/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-integration-actions/agents/openai.yaml",
+          "sha256": "82ee62aa48a644e658c9bb6a78c417dc15eb4f3ec9f4abc9081b6d24d16fe92d",
+          "size": 262
+        }
+      ]
+    },
+    {
+      "name": "controllerai-agents",
+      "files": [
+        {
+          "path": "controllerai-agents/SKILL.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-agents/SKILL.md",
+          "sha256": "dfdc083d0eb1b37d6e88ec7dc44bc24668f8e26261f70eebdc5f778c03a35d54",
+          "size": 11209
+        },
+        {
+          "path": "controllerai-agents/agents/openai.yaml",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-agents/agents/openai.yaml",
+          "sha256": "f4684ec904f3ebb051bb48460375756899c3316fbb16304aad5fff3d89692b09",
+          "size": 293
+        },
+        {
+          "path": "controllerai-agents/references/instructions-and-versioning.md",
+          "url": "https://getcontroller.ai/skills/2026.08.09.13/controllerai-agents/references/instructions-and-versioning.md",
+          "sha256": "b8bc2c02806d75ee48b1fd6618d6fd8532605240442840efb0199e15dd0fcad6",
+          "size": 4939
+        }
+      ]
+    }
+  ]
+}