@culvii/cli 0.0.7 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@culvii/cli",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "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.8",
     "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,90 @@
+{
+  "schemaVersion": 1,
+  "name": "culvii",
+  "bundleHash": "bb8ee103e0534e36fbf3df701f1c1539e2061f4f50e1a6affc1a0b173b29b672",
+  "generatorVersion": 1,
+  "sources": {
+    "@culvii/kit": "0.0.8",
+    "nodes": "1.0.0",
+    "surface-contract": "1.0.0",
+    "@culvii/cli": "0.0.9"
+  },
+  "files": {
+    "agents/openai.yaml": "80196c1dbde488639e31d4bbc0addcd253ba626ea0b3cb524d06ee1eabe3263b",
+    "examples/agent-workflow.culvii.ts": "c82471aa06e2fb2f939f50b70ae797b6fed22f2d51277975a93c16d0b94ecd76",
+    "examples/binary-document-workflow.culvii.ts": "3bc13dd2cf04b426449d5509749343a9c040b5e51bcb7e5982339b1173a459c6",
+    "examples/complete-workflow.culvii.ts": "2c59f6b9d525092e75b980aa174ccd8b0187621c8c196270453e03591000a08d",
+    "examples/custom-output-surface.culvii.ts": "8ccfb826d8b140dae94f8e57458eba7d98bf1cdf3dda372c23b757f9f47cb72b",
+    "examples/custom-wait-surface.culvii.ts": "4efef08381de6b51c4530fa312450682a09c3008c77f74c4b55c44b685bf4348",
+    "examples/human-in-the-loop-workflow.culvii.ts": "9daee28598cdae498786aea1b55640c1065097825d19262eb072c1b584328cfc",
+    "examples/integration-agent-workflow.culvii.ts": "3c9b3a3c174ebdfc4f128b2076d44685355d4ce952e54a5a4ec7061e1f231daf",
+    "examples/multi-agent-workflow-tools.culvii.ts": "ac96689205433dc647078acb323e970ac1c2ef06be118f087d428200b852a560",
+    "examples/nested-agent-workflow.culvii.ts": "e1255b0e22e83c26ea09876c9e90496c4c5ab4c24a52cf30d2cc2a7e9b1212a7",
+    "examples/output-surface.culvii.ts": "1959d8bc5c987c32d6c21fa6f36a1eb70bea5a18742885dff85f353170645702",
+    "examples/wait-surface.culvii.ts": "ae533ae4cf2ed533bc333528bd971d65b4140be033e65025663f78bc99d77cf2",
+    "references/agents.md": "bdd14922138c42c9b2ac6466d0eca5960365750451079e8ab28b65f2e0602ae5",
+    "references/authoring-files.md": "ea93dafc36e6643a1040e430aec0fd41f1a5f93c5d24794ae3db0624b26dff53",
+    "references/cli-guide.md": "f127193a2e669861ec9884fdf1f3618af6baf37324029943a05cc13a49d696bc",
+    "references/cli-reference.md": "1c97ed69b833a62b8e9000f20684c99315ff1eabaca265ba9fe54817c3b67020",
+    "references/feedback-cycle.md": "54ad5b36049e377344220e10a7ddaea1e010f532d9fe7ab39b6abd3d435a6a2a",
+    "references/integrations.md": "9fa3db838b4e48d3aae2949012bbbfa7ce84b32779048d17c21ac4548482ee68",
+    "references/kit-api.md": "c082d1b63bec52fdd7124e711f4e86bfae015f1cd7045b25e4910349c4fca1fd",
+    "references/node-argocd.md": "5abd8bfc02ced232d85d366108f2395bfe8d82e0dd0414527ccf932d85da6191",
+    "references/node-clickup-doc.md": "bf62328992963604fe0e015063b9af34d67ca49181c744b77b591a635c1b8c35",
+    "references/node-clickup-ticket.md": "b616e8c02a771eb5283fe33972e100aa6be410f88dd01adfbbfc58fe794b6d23",
+    "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-loop-break.md": "d383011f16ae620860e2535be49cafc862a57c7ecae7d7fbd57ac767a5afbd3c",
+    "references/node-core-loop-continue.md": "308af6ffa74572a211f784ffc77b565702105cc73718ae5e8874f1f13254a0ff",
+    "references/node-core-loop-output.md": "dd70d65ad423387cf1190f9e103d4ba734763e32b82674299b733cdb299dbac6",
+    "references/node-core-loop.md": "35d9e5f15ef49d9e5eb1ed824f438a1c61382ca00ff2a838e371fd60919f3b26",
+    "references/node-core-merge.md": "f1c2753761791f872a3e786552ba776742c81b5b56985c23660d90bed6c9422a",
+    "references/node-core-set.md": "511944327b31f9af70fbdcc5769c512a78129f901f98bb03ae3e464205b76468",
+    "references/node-core-switch.md": "512edc581e410f44f7f15ac31ed27fbd1698c0c4cfb9a7fd93feb42bbb29d1ae",
+    "references/node-cost-explorer.md": "65bafd0f0e3c9910f3af2f210d492fc0d1648b570c61ff258642c4b441e688f2",
+    "references/node-cron-trigger.md": "ab958969a2a30b6643ad1d31a3241fed427d3db2e3871ea7ab68c0af4d4cc82b",
+    "references/node-elasticsearch.md": "276ca5fa4368a0c7a12a4383dd01404bdc3c345f6c837ec5fc1c9d609b3138b2",
+    "references/node-github-poll-trigger.md": "132d7a0d7b56cfa29be552418725eeddefb0a11716b7b7192f53de6d57667ee8",
+    "references/node-github-webhook-trigger.md": "09de1c2b493476d908611f71a88850fc76786d6aed48b74e573c6b647110c6a3",
+    "references/node-github.md": "b7ed8f59ecdbcf3ea0166268a27905f1ada3c3fcc5e3e121dc32dea5427a3d06",
+    "references/node-gmail-trigger.md": "59ca6745079299e3bdf77f87fa328bd7900227bbe131ed7a977f781d2ee606e1",
+    "references/node-gmail.md": "f9d8f18d005acc6423c49e8741d909fe8541c4d849ae8ae590c04b561576bd82",
+    "references/node-google-calendar.md": "3bf8ed7c280036fd0009c299fcacbf920bb3b18429f2734ac603e18e16796f73",
+    "references/node-google-docs.md": "b8d6d68914b4228f11adf575753bcaa86cbf71fd3c7dfa36fb07d84627250ad1",
+    "references/node-grafana-dashboard.md": "9bdfafcdfd461a0082b0645a4089826204021fb273589732071ee56ff97ab83e",
+    "references/node-grafana-data-source.md": "050f9dda595a35346b5396563de0e8c18acb05a9139655c61d2a706cc39b5544",
+    "references/node-grafana-query.md": "35c95c6528c01766cfe0c88a9f1adcf786a95061ce81e963025ec131da1d1873",
+    "references/node-hibp-list-domains.md": "b977ed4babb1c419bfe13d76166528fffeddbaeb81147ece07b3c19d34d0f797",
+    "references/node-hibp-stealer-logs.md": "13758678d5eebd520823bc0e56d12cbef8b72835b54b0fc00e9402b744d44550",
+    "references/node-kubernetes.md": "293fd70959588d4f10fd8869388cf37809f477e2f987752da5ab0cdfb2c7cdc2",
+    "references/node-manual-trigger.md": "4bebd22e2a76d6e90acb08ece0d88a6c7040f1a0ac11da298f712251194b7086",
+    "references/node-microsoft-outlook-trigger.md": "aa4385d1734de97e79ce59d2c6ca802683e6c07f625b521d606f8bf5f8540ac5",
+    "references/node-microsoft-outlook.md": "51d55b369461dc0b88dd9b1fcf905f6f9b37fd9270053fc9e2022c2d3c33bed2",
+    "references/node-microsoft-sharepoint.md": "10f27d6507989598ead041a5e1965dd3014dd610848d2b12e4ee81864e4373ed",
+    "references/node-onionsearch.md": "3711791d3c5516ae6ee88bf29b1d18a79da3446cb310446d1e4fb77e22934fe6",
+    "references/node-prometheus.md": "337c4583bbe7f18b54bd7bcf452b8b7f0eb8dbab5d4c65945e6bdec2bbddc35b",
+    "references/node-s3.md": "8ecc9a791cda334707431dfcfed34abe9eedbedbb9c06f1ad03907f8af59b2a8",
+    "references/node-slack-events-trigger.md": "9884a5f369f654b5bf78cd352aaee9df27ec6e5fa548edde8485ea7f47d31eb2",
+    "references/node-slack-interactions-trigger.md": "b8fe95a36582dc8bc0d96b842a621e50fbacf6141914d00c13abfc9912748916",
+    "references/node-slack-trigger.md": "43e6caa5ee349e1ba3c256da3d3279b7385e182829b78e134f2123a650c3d052",
+    "references/node-slack.md": "2d24da368e43494487fa740b111f33d7ab9b763ec88ab45be852a8a8b64c3ff7",
+    "references/node-supabase.md": "c67e87065053adbb5c44425ad62d1e531c0fd9d98de0a7dc91b45e582a24c270",
+    "references/node-twilio.md": "a191b4c071a738c1283d545512e6b73f52aabb1c7fae4d9acb08c5346f5a6ad3",
+    "references/node-wait-timer.md": "72749e63f27b512aa6c51190fbc7a79195cdc37acd6c0f2305285012ce5fd06d",
+    "references/node-webhook-trigger.md": "b98b9cfc92b2e6eb5b1d75e651abccd022b7914d609052d7f7de4e588af45b5a",
+    "references/nodes-index.md": "e8feb33feff53ddf84628f6db9a45db26f9dd5cd6c14082912606af4f1c299eb",
+    "references/runtime-values.md": "93dbe09b2f150ffec02a1d1e2bebdce3eda6e885f1daaae05354ecaceb41f038",
+    "references/surface-authoring.md": "21ae1e1b64e15c8d89ff1d95efec84829ffa2f2aa2f0d5ba400c78742463586d",
+    "references/surface-display.md": "9a24b5fc81f48ad517d36f202c99291258866b7e607f8481763a985bd26d1a26",
+    "references/surface-feedback.md": "425f70b7bbda1923624bd9639fb0d7f071828ad7b59feb54867ef6fe5b5054cb",
+    "references/surface-input-actions.md": "54cd475120fcb650e4c876b9787905d47b87638483d73fc7dc7fb3a06305a8da",
+    "references/surface-layout.md": "3381fea6ed2ed16f4d1e9a9186aa853ecf834fb8f31a1bd09408e9c218e6b559",
+    "references/validation.md": "224ab2041ab6d823b8468b381e16a9823eb2a97b2ea33a812e89b2592ac72f68",
+    "references/workflows.md": "5988f86d8053c44c12decf4d43e98c13d2b3e22f124060198ede182b1e0fc648",
+    "SKILL.md": "d885d3601c21bd69156cdce3116268464edbbf88bc7cec0b6e98989d3a33e41b"
+  }
+}

package/skills/culvii/SKILL.md

@@ -0,0 +1,104 @@
+---
+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
+
+- [`argocd`](references/node-argocd.md)
+- [`clickupDoc`](references/node-clickup-doc.md)
+- [`clickupTicket`](references/node-clickup-ticket.md)
+- [`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.loop`](references/node-core-loop.md)
+- [`core.loopBreak`](references/node-core-loop-break.md)
+- [`core.loopContinue`](references/node-core-loop-continue.md)
+- [`core.loopOutput`](references/node-core-loop-output.md)
+- [`core.merge`](references/node-core-merge.md)
+- [`core.set`](references/node-core-set.md)
+- [`core.switch`](references/node-core-switch.md)
+- [`costExplorer`](references/node-cost-explorer.md)
+- [`cronTrigger`](references/node-cron-trigger.md)
+- [`elasticsearch`](references/node-elasticsearch.md)
+- [`github`](references/node-github.md)
+- [`githubPollTrigger`](references/node-github-poll-trigger.md)
+- [`githubWebhookTrigger`](references/node-github-webhook-trigger.md)
+- [`gmail`](references/node-gmail.md)
+- [`gmailTrigger`](references/node-gmail-trigger.md)
+- [`googleCalendar`](references/node-google-calendar.md)
+- [`googleDocs`](references/node-google-docs.md)
+- [`grafanaDashboard`](references/node-grafana-dashboard.md)
+- [`grafanaDataSource`](references/node-grafana-data-source.md)
+- [`grafanaQuery`](references/node-grafana-query.md)
+- [`hibp.listDomains`](references/node-hibp-list-domains.md)
+- [`hibp.stealerLogs`](references/node-hibp-stealer-logs.md)
+- [`kubernetes`](references/node-kubernetes.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)
+- [`onionsearch`](references/node-onionsearch.md)
+- [`prometheus`](references/node-prometheus.md)
+- [`s3`](references/node-s3.md)
+- [`slack`](references/node-slack.md)
+- [`slackEventsTrigger`](references/node-slack-events-trigger.md)
+- [`slackInteractionsTrigger`](references/node-slack-interactions-trigger.md)
+- [`slackTrigger`](references/node-slack-trigger.md)
+- [`supabase`](references/node-supabase.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)
+- [Binary document workflow](examples/binary-document-workflow.culvii.ts)
+- [Custom output surface](examples/custom-output-surface.culvii.ts)
+- [Custom wait surface](examples/custom-wait-surface.culvii.ts)
+- [Human-in-the-loop workflow](examples/human-in-the-loop-workflow.culvii.ts)
+- [Integration agent workflow](examples/integration-agent-workflow.culvii.ts)
+- [Nested agent workflow](examples/nested-agent-workflow.culvii.ts)
+- [Multi-agent workflow tools](examples/multi-agent-workflow-tools.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,47 @@
+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,
+    metadata: {
+      runtimeDetails: {
+        sandboxProfile: 'default',
+      },
+    },
+    permissions: {
+      default: {
+        '*': 'ask',
+        read_file: 'approve',
+        git: 'ask',
+        delete_file: 'deny',
+      },
+    },
+    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/binary-document-workflow.culvii.ts

@@ -0,0 +1,80 @@
+import { MultiAgentEngine, Step, Workflow, createAgentModelConfigFromRef } from '@culvii/kit';
+
+const MODEL = createAgentModelConfigFromRef(
+  'google-vertex/gemini-3.1-pro-preview',
+  'credential-id'
+);
+
+const CREATE_DOCUMENT_CODE = `
+export default async function main() {
+  const { Buffer } = require('node:buffer');
+  const document = 'Quarterly review\\nRevenue grew 18 percent.\\nNext step: renew the account.';
+  return {
+    json: { generated: true },
+    binary: {
+      sourceFile: {
+        data: Buffer.from(document, 'utf8').toString('base64'),
+        mimeType: 'text/plain',
+        fileName: 'quarterly-review.txt',
+        fileExtension: 'txt',
+      },
+    },
+  };
+}
+`;
+
+function createDocumentAgent() {
+  return new MultiAgentEngine({
+    id: 'document-reviewer',
+    name: 'Document Reviewer',
+    role: 'primary',
+    description: 'Reads workflow files and returns a concise review plus a text artifact.',
+    systemPrompt:
+      'Uploaded workflow files are only available through the binary tools. Always list files first, read the requested file, and never guess its contents.',
+    model: MODEL,
+    metadata: {
+      runtimeDetails: { sandboxProfile: 'default' },
+    },
+    permissions: { default: { '*': 'deny' } },
+    secondaryAgents: [],
+  });
+}
+
+function createWorkflow() {
+  const trigger = new Step({ id: 'trigger', name: 'Manual Trigger', type: 'manualTrigger' });
+  const createDocument = new Step({
+    id: 'create-document',
+    name: 'Create Document',
+    type: 'core.code',
+    params: { code: CREATE_DOCUMENT_CODE, codeType: 'js' },
+  });
+  const review = new Step({
+    id: 'review',
+    name: 'Review Document',
+    type: 'core.agent',
+    params: {
+      agentReferenceKey: 'document-reviewer',
+      prompt:
+        'List the workflow binary files, read the file with key "sourceFile", summarize its exact contents, then create a text/plain binary output named "review.txt" containing your summary. Reply with the source filename and the output filename.',
+      autoCloseSession: true,
+    },
+  });
+  const persist = new Step({
+    id: 'persist',
+    name: 'Persist Review',
+    type: 'core.set',
+    params: { values: { response: "={{ $('Review Document').json.response }}" } },
+  });
+
+  trigger.connectTo(createDocument);
+  createDocument.connectTo(review);
+  review.connectTo(persist);
+  return new Workflow({
+    id: 'binary-document-workflow',
+    name: 'Binary Document Workflow',
+    steps: [trigger, createDocument, review, persist],
+  });
+}
+
+createDocumentAgent();
+createWorkflow();

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

@@ -0,0 +1,81 @@
+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,
+    // This agent uses only its workflow tool, so sandbox tools are unavailable.
+    metadata: {
+      runtimeDetails: { sandboxProfile: 'default' },
+    },
+    permissions: { default: { '*': 'deny' } },
+    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/custom-output-surface.culvii.ts

@@ -0,0 +1,69 @@
+import { Step, Surface, Workflow } from '@culvii/kit';
+
+const responseSurface = new Surface({
+  id: 'http-response-summary',
+  name: 'HTTP Response Summary',
+  description: 'Displays an operation status and response body.',
+  slot: 'output',
+  definition: {
+    schema: 'kit.ui/v1',
+    root: 'card',
+    components: [
+      { id: 'card', type: 'Card', props: { title: 'Operation result' }, children: ['content'] },
+      { id: 'content', type: 'Stack', children: ['status', 'body'] },
+      {
+        id: 'status',
+        type: 'StatusPill',
+        props: {
+          label: { path: '$output/Fetch Resource/0/statusMessage' },
+          status: { path: '$output/Fetch Resource/0/statusCode' },
+        },
+      },
+      {
+        id: 'body',
+        type: 'JsonInspector',
+        props: { value: { path: '$output/Fetch Resource/0/body' } },
+      },
+    ],
+  },
+});
+
+function createWorkflow(id: string, output: 'define' | 'reuse') {
+  const trigger = new Step({ id: 'trigger', name: 'Manual Trigger', type: 'manualTrigger' });
+  const fetch = new Step({
+    id: 'fetch',
+    name: 'Fetch Resource',
+    type: 'core.code',
+    params: {
+      code: `export default async function main() {
+        return { json: { statusCode: 200, statusMessage: 'OK', body: { ready: true } } };
+      }`,
+      codeType: 'js',
+    },
+    // One workflow defines and attaches the custom output UI.
+    ui:
+      output === 'define'
+        ? { output: responseSurface }
+        : {
+            // Another workflow can reuse it by key with a safe fallback.
+            output: {
+              kind: 'custom',
+              surfaceKey: responseSurface.id,
+              fallbackSurfaceId: 'default.json',
+            },
+          },
+  });
+
+  trigger.connectTo(fetch);
+  return new Workflow({
+    id,
+    name:
+      id === 'custom-output-surface-workflow'
+        ? 'Custom Output Surface Workflow'
+        : 'Reused Output Surface Workflow',
+    steps: [trigger, fetch],
+  });
+}
+
+createWorkflow('custom-output-surface-workflow', 'define');
+createWorkflow('reused-output-surface-workflow', 'reuse');

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

@@ -0,0 +1,90 @@
+import { Step, Surface, Workflow } from '@culvii/kit';
+
+const approvalSurface = new Surface({
+  id: 'expense-approval',
+  name: 'Expense Approval',
+  description: 'Shows an amount and lets a reviewer approve or reject it.',
+  slot: 'wait',
+  definition: {
+    schema: 'kit.ui/v1',
+    root: 'form',
+    components: [
+      { id: 'form', type: 'Form', children: ['amount', 'comment', 'decision'] },
+      {
+        id: 'amount',
+        type: 'KeyValue',
+        props: {
+          entries: [
+            { label: 'Requested amount', value: { path: '$input/Collect Request/0/amount' } },
+          ],
+        },
+      },
+      {
+        id: 'comment',
+        type: 'TextArea',
+        props: { label: 'Reviewer comment', bind: '/$form/comment' },
+      },
+      {
+        id: 'decision',
+        type: 'ApproveRejectBar',
+        actions: {
+          approve: {
+            type: 'node.resume',
+            payload: {
+              approved: { path: '$form/approved', default: true },
+              comment: { path: '$form/comment', default: '' },
+            },
+          },
+          reject: {
+            type: 'node.stop',
+            payload: { reason: { path: '$form/comment', default: 'Rejected by reviewer' } },
+          },
+        },
+      },
+    ],
+    form: {
+      fields: [
+        { name: 'comment', label: 'Reviewer comment', type: 'textarea' },
+        { name: 'approved', label: 'Approved', type: 'checkbox' },
+      ],
+    },
+  },
+});
+
+function createApprovalWorkflow(id: string, selection: 'define' | 'reuse', amount: number) {
+  const trigger = new Step({ id: 'trigger', name: 'Manual Trigger', type: 'manualTrigger' });
+  const collect = new Step({
+    id: 'collect',
+    name: 'Collect Request',
+    type: 'core.set',
+    params: { values: { amount, stage: 'awaiting-approval' } },
+  });
+  const approval = new Step({
+    id: 'approval',
+    name: 'Approval',
+    type: 'core.set',
+    params: { values: { reviewer: 'manager' } },
+    ui: {
+      wait:
+        selection === 'define'
+          ? approvalSurface
+          : { kind: 'custom', surfaceKey: approvalSurface.id },
+    },
+  });
+  const result = new Step({
+    id: 'result',
+    name: 'Persist Decision',
+    type: 'core.set',
+    params: { values: { approved: "={{ $('Approval').json.approved }}" } },
+  });
+
+  trigger.connectTo(collect);
+  collect.connectTo(approval);
+  approval.connectTo(result);
+  return new Workflow({ id, name: id, steps: [trigger, collect, approval, result] });
+}
+
+// A wait surface automatically sets pauseAfterExecution: true. It can be
+// reused by key in another workflow, and $form is valid only in the wait slot.
+createApprovalWorkflow('manager-approval-workflow', 'define', 450);
+createApprovalWorkflow('finance-approval-workflow', 'reuse', 12000);