@culvii/cli 0.0.7 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@culvii/cli",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Culvii CLI",
   "private": false,
   "type": "module",
@@ -10,6 +10,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "COMMANDS.md",
     "USAGE.md"
@@ -49,6 +50,7 @@
     "tsup": "8.5.1",
     "typescript": "6.0.3",
     "vitest": "^4.1.5",
+    "@culvii/kit": "0.0.7",
     "surface-contract": "1.0.0"
   },
   "engines": {
@@ -56,12 +58,14 @@
     "pnpm": ">=10.0.0"
   },
   "scripts": {
-    "prebuild": "node scripts/generate-skill-content.js",
+    "skill:generate": "node --import tsx scripts/generate-skill-bundle.ts",
+    "skill:check": "node --import tsx scripts/generate-skill-bundle.ts --check",
+    "prebuild": "pnpm skill:generate",
     "build": "tsup",
-    "predev": "node scripts/generate-skill-content.js",
+    "predev": "pnpm skill:generate",
     "dev": "tsup --watch",
-    "pretest": "node scripts/generate-skill-content.js",
-    "test": "vitest run",
+    "pretest": "pnpm --filter @culvii/kit build && pnpm skill:check && pnpm skill:generate",
+    "test": "vitest run && tsc --noEmit -p tsconfig.skill-examples.json",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage"
   }

package/skills/culvii/.culvii-skill.json

@@ -0,0 +1,59 @@
+{
+  "schemaVersion": 1,
+  "name": "culvii",
+  "bundleHash": "687dba881f07be592c3ce200cefbccacd5e7aac67d122256075255f690563d10",
+  "generatorVersion": 1,
+  "sources": {
+    "@culvii/kit": "0.0.7",
+    "nodes": "1.0.0",
+    "surface-contract": "1.0.0",
+    "@culvii/cli": "0.0.8"
+  },
+  "files": {
+    "agents/openai.yaml": "80196c1dbde488639e31d4bbc0addcd253ba626ea0b3cb524d06ee1eabe3263b",
+    "examples/agent-workflow.culvii.ts": "934fcd2368ed8d8a02b7557dd2003b462def5f668021173a88cf7ab2393d9c5a",
+    "examples/complete-workflow.culvii.ts": "6b939592800bb5b94358fd7e8352a20499a16a31b2d310fcf2cd9609d9e12b66",
+    "examples/output-surface.culvii.ts": "1959d8bc5c987c32d6c21fa6f36a1eb70bea5a18742885dff85f353170645702",
+    "examples/wait-surface.culvii.ts": "ae533ae4cf2ed533bc333528bd971d65b4140be033e65025663f78bc99d77cf2",
+    "references/agents.md": "20cbcc3c184d91794f986217f293043c526d157c261a696e46ebf8e7744947c4",
+    "references/authoring-files.md": "ea93dafc36e6643a1040e430aec0fd41f1a5f93c5d24794ae3db0624b26dff53",
+    "references/cli-guide.md": "e7f6d69ec3cbc94fc584a64684883732e4e5ba6933fe1526dfe4b33e0eb19753",
+    "references/cli-reference.md": "e976edf090b5a8c1b8c4f9edc8df434a3c3c69348123ab0c4290547a971612f2",
+    "references/feedback-cycle.md": "0e5cf8142769d2ae6d8331cd0a04a6c1d54b8e9afb24b51eed8dfed4115d2c36",
+    "references/integrations.md": "9fa3db838b4e48d3aae2949012bbbfa7ce84b32779048d17c21ac4548482ee68",
+    "references/kit-api.md": "27ad6b8578dd2cf8606636f580a024551057171a74a4c8b5a3a12764f57cf263",
+    "references/node-core-agent.md": "09b0b3a5607dbdd06f3f463d140f9633a27b580e59b22f135f1bb349b7fcc0bf",
+    "references/node-core-browser-automation.md": "797f7dbd3374c2ea38de830ab2e9b08a2762e45a3cf56dad1ff274cf8109e7e7",
+    "references/node-core-code.md": "2768aa7a0fec5f12d716ece9727b038ee2a205647e7c41bd85f0139165bbbd51",
+    "references/node-core-http.md": "4799365201368c31d270644161a6e415d5ecfa25d9c75cf5e550330aff7679b4",
+    "references/node-core-if.md": "3298f6dbe803eae9e3a69eb7084b08f43a6c76e139e56051539c7603a705b7e1",
+    "references/node-core-jwt.md": "8828d11751ee88474f962a296cf29b279fa055ea2b95d9ee0362d211596bdedb",
+    "references/node-core-set.md": "511944327b31f9af70fbdcc5769c512a78129f901f98bb03ae3e464205b76468",
+    "references/node-cron-trigger.md": "ab958969a2a30b6643ad1d31a3241fed427d3db2e3871ea7ab68c0af4d4cc82b",
+    "references/node-elasticsearch.md": "b79e86b337e3391296036ac65a267b619ecdde5c34f7765c15abb8b5a292c5e5",
+    "references/node-gmail-trigger.md": "f359ea35b30edbc1d723aa3f9f013fa4aaec6082d114211c2dfc369b765e6e87",
+    "references/node-gmail.md": "ce3dc186d6483d12680ccd66b208fd32319aa8fc610ef8d11936f323c4526918",
+    "references/node-google-calendar.md": "5258b43f2434446723ccabfc1f7e023d251661a5d451ba5c639f96452737ebab",
+    "references/node-google-docs.md": "9c98ddd0f287fbc0322128c2c29707bf66b964557c796074dbfa7ace7e613ee1",
+    "references/node-manual-trigger.md": "4bebd22e2a76d6e90acb08ece0d88a6c7040f1a0ac11da298f712251194b7086",
+    "references/node-microsoft-outlook-trigger.md": "e74d4984e85e87f7a8be1f762e72fd77b2ddce984034126612484966e9429ab0",
+    "references/node-microsoft-outlook.md": "4767160228debe361881e6e5fc9cfda55add3b026728221e4a5bd2eb4be9fc87",
+    "references/node-microsoft-sharepoint.md": "7b89f9073da94a39f477ca8aeb2964dee0bb7dee99784841a403884a75c5a822",
+    "references/node-s3.md": "e25649b8103460ebf7c35c96626aa3c9e181dcb1ca2d8af3203afb801a6062ea",
+    "references/node-slack-trigger.md": "a0bdeb27a0d035fb85d25bcd59d54ba2da622be143333431c35a53b5728b7b65",
+    "references/node-slack.md": "e02d5c72948f311fb2847ce59ee11c9ba2a0fd02c59ba661236aa9540091aa3d",
+    "references/node-twilio.md": "337e1163ae54ebad046d7ba9030a8c54503ef39007396a0b5ee10598ed34ff6e",
+    "references/node-wait-timer.md": "72749e63f27b512aa6c51190fbc7a79195cdc37acd6c0f2305285012ce5fd06d",
+    "references/node-webhook-trigger.md": "b98b9cfc92b2e6eb5b1d75e651abccd022b7914d609052d7f7de4e588af45b5a",
+    "references/nodes-index.md": "de160eca230166f6b795f515a9e5884d3ba814b6600a5d412cc0c54a77d68cbb",
+    "references/runtime-values.md": "93dbe09b2f150ffec02a1d1e2bebdce3eda6e885f1daaae05354ecaceb41f038",
+    "references/surface-authoring.md": "b8b666d57f3101461604d94f2910e6c1fc9948411cc773b3b3916f5d89c8b32d",
+    "references/surface-display.md": "0afaf3c04fb2a7718e3bf2db0d55e968f7acab80c20f1d3a9a96282e6688a709",
+    "references/surface-feedback.md": "45009b5b4d050f0af2a186d478ae9a9964990d2e37f7e4e655d6a2e03ea6cb49",
+    "references/surface-input-actions.md": "54cd475120fcb650e4c876b9787905d47b87638483d73fc7dc7fb3a06305a8da",
+    "references/surface-layout.md": "3381fea6ed2ed16f4d1e9a9186aa853ecf834fb8f31a1bd09408e9c218e6b559",
+    "references/validation.md": "224ab2041ab6d823b8468b381e16a9823eb2a97b2ea33a812e89b2592ac72f68",
+    "references/workflows.md": "5988f86d8053c44c12decf4d43e98c13d2b3e22f124060198ede182b1e0fc648",
+    "SKILL.md": "8fc95b5ac2a0347d77d8155d67622033960392e85fb519dacdc67e864874c388"
+  }
+}

package/skills/culvii/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: culvii
+description: Use this skill when writing and validating Culvii agents, workflows, nodes, or dynamic UI surfaces with @culvii/kit and culvii dev, including recursive runtime expressions, surface bindings, and cross-resource references.
+---
+
+# Culvii authoring
+
+Build Culvii resources in TypeScript using public @culvii/kit APIs. This file routes you to the minimum detailed references needed for the task.
+
+## Start here
+
+1. Inspect the project's package.json, culvii.yaml, and existing *.culvii.ts files before generating code.
+2. Read [authoring files](references/authoring-files.md), then read only the task-specific references below.
+3. Never invent node types, component types, props, flags, or APIs. Open the generated reference first.
+4. Never write raw credentials. Resolve Culvii credential IDs through [integration selection](references/integrations.md); never ask the user to copy or paste an ID.
+5. Author the requested resources as drafts, then follow the authenticated validation loop in [the CLI development guide](references/cli-guide.md). Never guess the tenant, never run culvii deploy, and never leave culvii dev running.
+
+For every newly authored workflow, offer runtime widget configuration before starting `culvii dev`. If the user opts in, follow [surface configuration and visual approval](references/surface-feedback.md): choose custom, existing, or default per node, and attach every custom candidate before the first validation. Do not finish while a custom surface is unvalidated or awaiting visual approval.
+
+## Missing required inputs
+
+- Gather every known blocking input before authoring placeholders. Ask them together in one interactive prompt, or the fewest batches allowed by the agent.
+- Use the agent's native in-run question tool, such as Codex request_user_input or Claude AskUserQuestion, so the task pauses and resumes in the same run. Never return a final answer merely to request missing values.
+- Use selectable options only when every option is a complete usable value or a decision that needs no dependent value. Options must come from the user's request, existing project files, or real command output; never invent IDs.
+- An answer such as "DM by user ID" is incomplete when the actual user ID is still missing. If a semantic decision and an ID are both required, collect both in the same in-run prompt or immediately ask for the ID before continuing.
+- For credentials, follow [integration selection](references/integrations.md). For an unknown channel, user, tenant, or resource ID, use a free-text input when the agent supports one. If the question UI only offers radio options plus custom/Other, explicitly ask the user to select custom/Other and paste the literal ID; do not offer a semantic radio answer that can be mistaken for the ID.
+- After the user responds, verify that every required opaque value contains the literal usable ID. Continue authoring and validation automatically only when all required values are present. If no interactive question tool exists, leave the task explicitly waiting for input rather than marking it complete.
+
+## Task routing
+
+- Agents, models, secondary agents, permissions, and tools: [agents](references/agents.md) and [Kit API](references/kit-api.md).
+- Workflows, steps, branching, errors, and references: [workflows](references/workflows.md), [runtime values](references/runtime-values.md), and [validation](references/validation.md).
+- Surfaces: [surface configuration and visual approval](references/surface-feedback.md), [surface authoring](references/surface-authoring.md), then [layout](references/surface-layout.md), [display](references/surface-display.md), or [input/actions](references/surface-input-actions.md).
+- CLI use: [development lifecycle](references/cli-guide.md), [workflow feedback cycle](references/feedback-cycle.md), and [exact CLI reference](references/cli-reference.md).
+- Credentials and provider integrations: [integration selection](references/integrations.md).
+- Node selection: [node index](references/nodes-index.md), then the exact page linked below.
+
+## Node references
+
+- [`core.agent`](references/node-core-agent.md)
+- [`core.browserAutomation`](references/node-core-browser-automation.md)
+- [`core.code`](references/node-core-code.md)
+- [`core.http`](references/node-core-http.md)
+- [`core.if`](references/node-core-if.md)
+- [`core.jwt`](references/node-core-jwt.md)
+- [`core.set`](references/node-core-set.md)
+- [`cronTrigger`](references/node-cron-trigger.md)
+- [`elasticsearch`](references/node-elasticsearch.md)
+- [`gmail`](references/node-gmail.md)
+- [`gmailTrigger`](references/node-gmail-trigger.md)
+- [`googleCalendar`](references/node-google-calendar.md)
+- [`googleDocs`](references/node-google-docs.md)
+- [`manualTrigger`](references/node-manual-trigger.md)
+- [`microsoftOutlook`](references/node-microsoft-outlook.md)
+- [`microsoftOutlookTrigger`](references/node-microsoft-outlook-trigger.md)
+- [`microsoftSharepoint`](references/node-microsoft-sharepoint.md)
+- [`s3`](references/node-s3.md)
+- [`slack`](references/node-slack.md)
+- [`slackTrigger`](references/node-slack-trigger.md)
+- [`twilio`](references/node-twilio.md)
+- [`waitTimer`](references/node-wait-timer.md)
+- [`webhookTrigger`](references/node-webhook-trigger.md)
+
+## Examples
+
+- [Agent and workflow](examples/agent-workflow.culvii.ts)
+- [Output surface](examples/output-surface.culvii.ts)
+- [Wait surface](examples/wait-surface.culvii.ts)
+- [Complete workflow](examples/complete-workflow.culvii.ts)
+
+## Safety
+
+Do not bypass platform validation, add unsupported surface markup/CSS/JavaScript, or expose raw binary data. Never run culvii deploy. Test workflows through the feedback cycle; do not execute standalone agents. Always close the exact culvii dev process you started and wait for it to exit before finishing. Workflow expressions use {{ ... }} selectors; surface bindings use JSON Pointer objects. Keep them separate.

package/skills/culvii/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Culvii"
+  short_description: "Build Culvii agents, workflows, and surfaces"
+  default_prompt: "Use $culvii to build and validate a Culvii agent or workflow."

package/skills/culvii/examples/agent-workflow.culvii.ts

@@ -0,0 +1,24 @@
+import { MultiAgentEngine, Step, Workflow, createAgentModelConfigFromRef } from '@culvii/kit';
+
+const MODEL = createAgentModelConfigFromRef('openai/gpt-4.1', 'credential-id');
+
+function createAgent() {
+  return new MultiAgentEngine({
+    id: 'review-agent', name: 'Review Agent', role: 'primary',
+    description: 'Reviews a request.', systemPrompt: 'Return a concise review.',
+    model: MODEL, secondaryAgents: [],
+  });
+}
+
+function createWorkflow() {
+  const trigger = new Step({ id: 'trigger', name: 'Manual Trigger', type: 'manualTrigger' });
+  const run = new Step({
+    id: 'run-review', name: 'Run Review', type: 'core.agent',
+    params: { agentReferenceKey: 'review-agent', prompt: 'Review the request.', autoCloseSession: true },
+  });
+  trigger.connectTo(run);
+  return new Workflow({ id: 'review-workflow', name: 'Review Workflow', steps: [trigger, run] });
+}
+
+createAgent();
+createWorkflow();

package/skills/culvii/examples/complete-workflow.culvii.ts

@@ -0,0 +1,37 @@
+import { MultiAgentEngine, Step, Workflow, createAgentModelConfigFromRef, defineWorkflowTool } from '@culvii/kit';
+
+const MODEL = createAgentModelConfigFromRef('anthropic/claude-sonnet-4-5', 'credential-id');
+
+function createLookupWorkflow() {
+  const trigger = new Step({ id: 'lookup-trigger', name: 'Lookup Trigger', type: 'manualTrigger' });
+  const lookup = new Step({ id: 'lookup', name: 'Lookup', type: 'core.set', params: { values: { plan: 'Enterprise' } } });
+  trigger.connectTo(lookup);
+  return new Workflow({ id: 'lookup-workflow', name: 'Lookup Workflow', steps: [trigger, lookup] });
+}
+
+function createAgent() {
+  return new MultiAgentEngine({
+    id: 'concierge-agent', name: 'Concierge Agent', role: 'primary',
+    description: 'Looks up and reviews account context.', systemPrompt: 'Use lookup_account before answering.', model: MODEL,
+    tools: { lookup_account: defineWorkflowTool({ name: 'lookup_account', description: 'Looks up account data.', workflowId: 'lookup-workflow' }) },
+    secondaryAgents: [],
+  });
+}
+
+function createParentWorkflow() {
+  const trigger = new Step({ id: 'trigger', name: 'Manual Trigger', type: 'manualTrigger' });
+  const prepare = new Step({
+    id: 'prepare', name: 'Prepare', type: 'core.set',
+    params: { values: { account: 'Acme', nested: { ids: ['={{ $system.execId }}', '={{ $json.account }}'] } } },
+  });
+  const agent = new Step({
+    id: 'agent', name: 'Concierge', type: 'core.agent',
+    params: { agentReferenceKey: 'concierge-agent', prompt: "Review {{ $('Prepare').json.account }}", autoCloseSession: true },
+  });
+  trigger.connectTo(prepare); prepare.connectTo(agent);
+  return new Workflow({ id: 'parent-workflow', name: 'Parent Workflow', steps: [trigger, prepare, agent] });
+}
+
+createLookupWorkflow();
+createAgent();
+createParentWorkflow();

package/skills/culvii/examples/output-surface.culvii.ts

@@ -0,0 +1,45 @@
+import { Step, Surface, Workflow } from '@culvii/kit';
+
+function createOutputSurface() {
+  return new Surface({
+    id: 'result-surface',
+    name: 'Result Surface',
+    slot: 'output',
+    definition: {
+      schema: 'kit.ui/v1',
+      root: 'outer',
+      components: [
+        { id: 'outer', type: 'Stack', children: ['card'] },
+        { id: 'card', type: 'Card', props: { title: 'Execution result' }, children: ['inner'] },
+        { id: 'inner', type: 'Stack', children: ['status', 'execution'] },
+        {
+          id: 'status',
+          type: 'StatusPill',
+          props: { status: { path: '/$output/Prepare/main/0/0/status' } },
+        },
+        {
+          id: 'execution',
+          type: 'Text',
+          props: { text: { path: '/$exec/id', default: 'pending' } },
+        },
+      ],
+    },
+  });
+}
+
+function createWorkflow() {
+  const prepare = new Step({
+    id: 'prepare',
+    name: 'Prepare',
+    type: 'core.set',
+    params: { values: { status: 'ready' } },
+    ui: { output: createOutputSurface() },
+  });
+  return new Workflow({
+    id: 'output-surface-workflow',
+    name: 'Output Surface Workflow',
+    steps: [prepare],
+  });
+}
+
+createWorkflow();

package/skills/culvii/examples/wait-surface.culvii.ts

@@ -0,0 +1,24 @@
+import { Step, Surface, Workflow } from '@culvii/kit';
+
+function createWaitSurface() {
+  return new Surface({
+    id: 'approval-surface', name: 'Approval Surface', slot: 'wait',
+    definition: { schema: 'kit.ui/v1', root: 'form', components: [
+      { id: 'form', type: 'Form', props: { title: 'Review result' }, children: ['comment', 'approve'] },
+      { id: 'comment', type: 'TextArea', props: { label: 'Comment', bind: '/$form/comment' } },
+      { id: 'approve', type: 'Button', props: { label: 'Continue', variant: 'primary' }, actions: {
+        click: { type: 'node.resume', payload: { comment: { path: '/$form/comment', default: '' } } },
+      } },
+    ], form: { fields: [{ name: 'comment', label: 'Comment', type: 'textarea' }] } },
+  });
+}
+
+function createWorkflow() {
+  const review = new Step({
+    id: 'review', name: 'Review', type: 'core.set', params: { values: { status: 'pending' } },
+    ui: { wait: createWaitSurface() },
+  });
+  return new Workflow({ id: 'approval-workflow', name: 'Approval Workflow', steps: [review] });
+}
+
+createWorkflow();

package/skills/culvii/references/agents.md

@@ -0,0 +1,29 @@
+# Agents
+
+Create a root agent with `new MultiAgentEngine(primaryConfig)`. A primary agent requires `id`, `name`, `role: 'primary'`, `systemPrompt`, `model`, and `secondaryAgents`. Include a useful `description`. A secondary agent is defined inline with `role: 'secondary'`; secondary agents cannot contain further secondary agents.
+
+Create models with `createAgentModelConfigFromRef('<provider>/<model>', '<credential-id>', options?)`. Supported built-in providers are `anthropic`, `openai`, `gemini`, `vertexai`, and `google-vertex`. A credential ID is required; never use an API key as the ID.
+
+```ts
+const MODEL = createAgentModelConfigFromRef('anthropic/claude-sonnet-4-5', 'credential-uuid');
+const agent = new MultiAgentEngine({
+  id: 'support-agent',
+  name: 'Support Agent',
+  role: 'primary',
+  description: 'Resolves support requests with a research specialist.',
+  systemPrompt: 'Solve the request and delegate research when useful.',
+  model: MODEL,
+  secondaryAgents: [{
+    id: 'researcher', name: 'Researcher', role: 'secondary',
+    description: 'Finds supporting evidence.', systemPrompt: 'Return concise evidence.', model: MODEL,
+  }],
+});
+```
+
+Built-in permissions live at `metadata.runtimeDetails.permissions`. Only keys in `BUILTIN_AGENT_PERMISSIONS` are valid: `*`, `web:fetch`, `web:crawl`, `workflow:binary:read`, `workflow:binary:write`, `workflow:pdf:read`, `workflow:docx:read`, `workflow:docx:write`, and `workflow:docx:append`. Workflow-prefixed capabilities are available only during a workflow execution.
+
+Workflow tools belong in root `tools` and are created with `defineWorkflowTool({ name, description, workflowId, triggerNodeName?, inputSchema? })`. Omit `tools` when there are no tools. `workflowId` references a local workflow resource ID, not a display name.
+
+Agent references flow in the other direction through a `core.agent` step's `params.agentReferenceKey`, which must exactly equal the `MultiAgentEngine` ID. Never use `agentId`.
+
+Further reading: [Multi-Agent API](https://culvii.com/docs/sdk-reference/api-reference/multi-agent-api/) and [Authentication](https://culvii.com/docs/sdk-reference/guides/authentication/).

package/skills/culvii/references/authoring-files.md

@@ -0,0 +1,21 @@
+# Authoring files
+
+Before writing code, inspect `package.json`, `culvii.yaml`, and every existing `*.culvii.ts` file. Preserve the project's module style and dependency versions.
+
+Each evaluated `*.culvii.ts` file should import public APIs from `@culvii/kit`, construct resources inside named functions, and call those functions at the bottom. Do not export resources as a substitute for construction: dev discovery observes constructors through `DevRegistry`.
+
+```ts
+import { MultiAgentEngine, Step, Surface, Workflow, createAgentModelConfigFromRef } from '@culvii/kit';
+
+const MODEL = createAgentModelConfigFromRef('openai/gpt-4.1', 'CREDENTIAL_ID');
+
+function createAgent() { return new MultiAgentEngine({ /* ... */ }); }
+function createWorkflow() { return new Workflow({ /* ... */ }); }
+function createSurface() { return new Surface({ /* ... */ }); }
+
+createAgent();
+createWorkflow();
+createSurface();
+```
+
+Use stable kebab-case resource IDs and unique step names. Credential IDs are references to credentials stored in Culvii; never place raw secrets in source.

package/skills/culvii/references/cli-guide.md

@@ -0,0 +1,22 @@
+# CLI development guide
+
+Safe lifecycle:
+
+1. Inspect `package.json`, `culvii.yaml`, and existing `*.culvii.ts` files.
+2. Author resources using installed `@culvii/kit` types. For every new workflow, complete the pre-validation choices in [surface configuration and visual approval](surface-feedback.md), including attaching any custom candidate surfaces, before starting `culvii dev`.
+3. Run `culvii whoami --json` to check the stored login and active context.
+4. If the user is not authenticated, run `culvii login` as a tracked process. If command execution or opening the browser requires approval, request that approval and continue as soon as the user allows it. Keep the login process running while its local callback server opens the user's browser and waits for authentication. When login lists multiple tenants, present those exact tenants through the agent's native in-run question tool, then write the selected tenant number followed by Enter to the same login process. Never choose a tenant or end the run while login is awaiting input. The CLI uses its interactive selector in a real terminal and automatically falls back to a plain numbered prompt when raw terminal mode is unavailable. Ask the user to run login manually only after execution is denied or the environment actually fails to launch the browser, callback server, or writable input process. Prefer the same `culvii` executable that will run `culvii dev`; if it is not on PATH, resolve the project-local CLI without hard-coding a machine-specific absolute path.
+5. After a fresh login, keep the tenant selected during login and do not ask again. For an existing authenticated session whose tenant has not been confirmed for the task, run `culvii switch` to list contexts. If more than one is available, show those exact tenants through the native question tool and run `culvii switch <tenant-slug>` with the user's selection. Never choose a tenant for the user.
+6. Run `culvii whoami --json` again and verify that the authenticated identity and active tenant match the user's selection.
+7. Start `culvii dev` as a tracked long-running process and retain its exact process/session handle. If another dev session is already active, do not start or terminate anything; ask the user to close their existing session.
+8. Inspect the initial evaluation and sync output. If it reports evaluation, schema, surface, node, or cross-resource validation errors, fix the authored files and let the running watcher validate them again. Repeat until validation and draft sync succeed.
+9. For a requested workflow, complete the [workflow feedback cycle](feedback-cycle.md), including visual approval of custom surfaces, while this dev session remains active.
+10. In a cleanup step that runs after success, failure, cancellation, or a blocker, send Ctrl-C/SIGINT to the exact `culvii dev` process the agent started and wait for it to exit. Confirm the CLI disconnected and discarded the draft session. If graceful shutdown fails, terminate only that exact process and report that cleanup could not be confirmed. Never use a broad process kill.
+11. Do not present the resources as complete while validation or feedback errors remain or while the dev process is still running.
+12. Never run `culvii deploy`. Deployment is a separate user-operated action outside this skill.
+
+`culvii dev` watches `*.culvii.ts`, evaluates resources, validates their combined reference graph, and syncs drafts. Removed resources become orphans for the session. Ending the session cleans up draft resources. Do not assume a successful TypeScript build proves cross-resource references are valid.
+
+Use [cli-reference.md](cli-reference.md) for exact commands and flags generated from the registered Commander tree.
+
+Further reading: [`culvii dev`](https://culvii.com/docs/cli/dev/) and [`culvii deploy`](https://culvii.com/docs/cli/deploy/).

package/skills/culvii/references/cli-reference.md

@@ -0,0 +1,184 @@
+# CLI reference
+
+Generated from the registered Commander command tree. Disabled and unregistered commands are excluded.
+
+## `culvii`
+
+Culvii CLI
+
+Options:
+
+- `--debug` — Enable debug logging to ~/.culvii/logs/cli.log
+- `-V, --version` — output the version number
+
+## `culvii auth`
+
+Authentication commands
+
+## `culvii auth login`
+
+Login to Culvii
+
+## `culvii auth logout`
+
+Logout of Culvii
+
+## `culvii deploy`
+
+Deploy an agent
+
+Options:
+
+- `--env <env>` (required) — Environment (sandbox or prod)
+- `--workspace-slug <slug>` — Target workspace slug (overrides config)
+
+## `culvii dev`
+
+Start the development server and file watcher
+
+## `culvii env [environment]`
+
+Show or switch the active environment (dev, sandbox, prod)
+
+## `culvii execution`
+
+Inspect workflow executions
+
+Options:
+
+- `--env <env>` — Target environment (dev, sandbox, or prod)
+
+## `culvii execution get <execution-id>`
+
+Get execution details, step outputs, and errors
+
+Options:
+
+- `--json` — Print machine-readable JSON
+
+## `culvii execution list`
+
+List workspace executions
+
+Options:
+
+- `--json` — Print machine-readable JSON
+- `--limit <limit>` — Results per page
+- `--page <page>` — Page number
+- `--status <status>` — Filter by execution status
+- `--trigger <trigger>` — Filter by trigger type
+- `--workflow <workflow>` — Filter by workflow reference key or ID
+
+## `culvii init [project-name]`
+
+Scaffold a new Culvii project with working agent and workflow files
+
+Options:
+
+- `--here` — Scaffold into the current directory instead of a named subdirectory
+- `--provider <provider>` — Model provider: openai | anthropic | gemini | google-vertex
+- `--template <template>` — Template: agent-only | agent-workflow | agent-workflow-tool | multi-agent
+- `-y, --yes` — Accept all defaults non-interactively
+
+## `culvii integration`
+
+List and manage Culvii integrations
+
+Options:
+
+- `--env <env>` — Target environment (dev, sandbox, or prod)
+
+## `culvii integration list`
+
+List available integration credentials and their scopes
+
+Options:
+
+- `--json` — Print machine-readable JSON
+
+## `culvii login`
+
+Login to Culvii
+
+## `culvii logout`
+
+Logout of Culvii
+
+## `culvii rename <old-slug> <new-slug>`
+
+Rename a resource
+
+Options:
+
+- `--env <env>` — Target environment (sandbox or prod)
+- `--resource-type <type>` (required) — Type of resource (agent)
+- `--workspace-slug <slug>` — Target workspace slug (overrides config)
+
+## `culvii skill`
+
+Manage AI agent skills
+
+## `culvii skill install`
+
+Install the Culvii authoring skill bundle for AI agents
+
+Options:
+
+- `--agent <agent>` — Specify agent (claude|cursor|windsurf|github|opencode|gemini|kiro|codex|agents)
+- `--force` — Replace an existing unmanaged Culvii skill directory
+- `--global` — Install globally instead of in the current project
+
+## `culvii switch [tenant-slug]`
+
+Switch the active tenant context
+
+## `culvii whoami`
+
+Show current authenticated user context
+
+Options:
+
+- `--json` — Output as JSON
+
+## `culvii workflow`
+
+Workflow execution commands
+
+Options:
+
+- `--env <env>` — Target environment (dev, sandbox, or prod)
+
+## `culvii workflow run <workflow>`
+
+Start a workflow execution
+
+Options:
+
+- `--json` — Print machine-readable JSON
+- `--mocks-file <path>` — JSON object mapping node IDs to mock outputs
+- `--payload <json>` — Trigger payload as JSON
+- `--payload-file <path>` — Read trigger payload from a JSON file
+- `--trigger <node-name>` (required) — Trigger node name
+
+## `culvii workspace`
+
+Workspace commands
+
+Options:
+
+- `--env <env>` — Target environment (sandbox or prod)
+
+## `culvii workspace create`
+
+Create a new workspace
+
+Options:
+
+- `--name <name>` (required) — Workspace name
+- `--slug <slug>` (required) — Workspace slug
+
+## `culvii workspace list`
+
+List workspaces
+
+Further reading: [`culvii dev`](https://culvii.com/docs/cli/dev/) and [`culvii deploy`](https://culvii.com/docs/cli/deploy/).

package/skills/culvii/references/feedback-cycle.md

@@ -0,0 +1,43 @@
+# Workflow feedback cycle
+
+Use this only after `culvii dev` has validated and synced the requested draft resources.
+
+1. Keep the tracked `culvii dev` process running.
+2. Execute feedback only through a `manualTrigger`. If the selected authored trigger is cron, webhook, or polling, first snapshot its exact type, params, credentials, and other trigger-specific fields. Temporarily change that same step to `manualTrigger` while preserving its `id`, `name`, connections, and attached surfaces; remove incompatible trigger-only fields until restoration. Let the active `culvii dev` watcher validate and sync the temporary graph before continuing.
+3. Create a JSON payload matching the real runtime trigger's expected output shape. This representative payload becomes the mocked manual-trigger output automatically and supplies both downstream workflow data and surface preview data. Never mock or invoke the cron, webhook, or polling implementation itself.
+4. For every node reachable from the manual trigger whose generated node reference says `Feedback mock: required`, create a mock output keyed by the node's authored `id`. Do not include cron, webhook, or polling triggers in the mock file. Do not mock `core.agent`; agents must execute through their workflow node.
+5. Start the draft workflow with `culvii workflow run <workflow-reference-key> --trigger <manual-node-name> --payload-file <path> --mocks-file <path> --json`.
+6. Fetch `culvii execution get <execution-id> --json` until its status is `success` or `failed`. This status polling is not a workflow wait and must not resume paused nodes.
+7. On failure, inspect the execution error and the failing step's input/output ports. Fix the authored resource or mock fixture, allow `culvii dev` to resync, and rerun. Stop after three failed attempts and report the remaining error unless the user asks to continue.
+8. On success, inspect the final and intermediate step outputs for the requested behavior. If the workflow has custom candidate surfaces, use these outputs to complete their [visual approval loop](surface-feedback.md#visual-approval-loop). Return to the development lifecycle only after all surface decisions are resolved; keep `culvii dev` running until then.
+9. In success, failure, cancellation, and blocker cleanup, restore the temporarily converted trigger exactly from the snapshot. Wait for `culvii dev` to validate and sync the restored authored graph before stopping the dev process. Do not modify an originally authored manual trigger.
+
+The platform applies these execution-only overrides; the agent must not write them into the authored files:
+
+- Every node receives `pauseAfterExecution: false`.
+- `core.agent` receives `autoCloseSession: true`.
+- Agents outside the workflow are not executed.
+- Surfaces do not control execution progress. Their visual approval uses sanitized execution output but does not change workflow execution.
+
+## Mock file
+
+The file is a JSON object keyed by workflow node ID. An object produces one output item; an array produces multiple items on the first output. Use `batches` only when a node needs multiple output indexes.
+
+```json
+{
+  "gmail-send": { "id": "mock-message-1", "threadId": "mock-thread-1" },
+  "outlook-read": [
+    { "id": "mail-1", "subject": "Urgent request", "from": "person@example.com" }
+  ],
+  "multi-output-node": {
+    "batches": [
+      [{ "matched": true }],
+      [{ "matched": false }]
+    ]
+  }
+}
+```
+
+In mock mode, the trigger payload becomes the selected manual trigger's output. Feedback execution rejects non-manual triggers. A node marked as requiring a feedback mock fails safely when its mock is missing instead of executing. Nodes not marked this way, including core workflow logic and workflow-contained agents, execute normally.
+
+Use `culvii execution list --workflow <workflow> --page <n> --limit <n> --json` to find earlier runs. Use [cli-reference.md](cli-reference.md) for the current generated flags.

package/skills/culvii/references/integrations.md

@@ -0,0 +1,13 @@
+# Integration selection
+
+Use this flow whenever an agent model or workflow node requires a Culvii credential ID.
+
+1. After authentication and tenant selection, run `culvii integration list --json` in the user's project.
+2. Use only a connected integration whose provider, platform scope, and OAuth scopes cover the requested operation. The command returns each usable `credentialId` and the active tenant/environment's `addUrl`.
+3. If exactly one integration matches, use its `credentialId` directly in the authored resource without asking the user to copy it.
+4. If several match, ask one in-run selectable question. Label each option with its integration name, provider, and scope; retain the option-to-`credentialId` mapping internally.
+5. If none match, show the exact `addUrl` returned by the command on its own line as `🟨 **Integration URL:** \`<addUrl>\`` and ask the user to add or connect the integration. The yellow marker is portable; do not emit raw ANSI color codes because structured question dialogs control their own text colors. Keep the current agent run open. After the user confirms completion, rerun `culvii integration list --json` and continue from its real output.
+
+Never ask the user to find, copy, or paste a credential ID. Never invent one. A tenant-scoped integration applies tenant-wide; an environment-scoped integration applies only to its environment; a workspace-scoped integration applies only to the listed workspace IDs. Treat `connected: false` or insufficient OAuth scopes as unusable and explain what must be connected or authorized at the displayed URL.
+
+Users can run `culvii integration list` themselves for a readable table or add `--json` for machine-readable output. See [the generated CLI reference](cli-reference.md) for current flags.