@culvii/cli 0.0.7 → 0.0.9

package/skills/culvii/examples/human-in-the-loop-workflow.culvii.ts

@@ -0,0 +1,125 @@
+import {
+  MultiAgentEngine,
+  Step,
+  Workflow,
+  createAgentModelConfigFromRef,
+  defineWorkflowTool,
+} from '@culvii/kit';
+
+const MODEL = createAgentModelConfigFromRef('openai/gpt-4.1', 'credential-id');
+
+function createApprovalToolWorkflow() {
+  const trigger = new Step({ id: 'trigger', name: 'Manual Trigger', type: 'manualTrigger' });
+  const approval = new Step({
+    id: 'approval',
+    name: 'Approval',
+    type: 'core.set',
+    params: {
+      values: { stage: 'awaiting-review', amount: 1500 },
+      // A resume request continues from this node.
+      pauseAfterExecution: true,
+    },
+  });
+  trigger.connectTo(approval);
+  return new Workflow({
+    id: 'discount-approval-workflow',
+    name: 'Discount Approval Workflow',
+    steps: [trigger, approval],
+  });
+}
+
+function createAccountLookupWorkflow() {
+  const trigger = new Step({ id: 'trigger', name: 'Manual Trigger', type: 'manualTrigger' });
+  const account = new Step({
+    id: 'account',
+    name: 'Account',
+    type: 'core.set',
+    params: { values: { plan: 'Enterprise', seats: 250 } },
+  });
+  trigger.connectTo(account);
+  return new Workflow({
+    id: 'account-lookup-workflow',
+    name: 'Account Lookup Workflow',
+    steps: [trigger, account],
+  });
+}
+
+function createConciergeAgent() {
+  return new MultiAgentEngine({
+    id: 'discount-concierge',
+    name: 'Discount Concierge',
+    role: 'primary',
+    description: 'Looks up an account and requests approval before offering a discount.',
+    systemPrompt:
+      'Call lookup_account first. If a discount is requested, call request_approval and wait for its human decision before answering.',
+    model: MODEL,
+    metadata: {
+      runtimeDetails: {
+        sandboxProfile: 'default',
+      },
+    },
+    permissions: { default: { '*': 'ask', read_file: 'approve', delete_file: 'deny' } },
+    tools: {
+      lookup_account: defineWorkflowTool({
+        name: 'lookup_account',
+        description: 'Looks up account context.',
+        workflowId: 'account-lookup-workflow',
+        inputSchema: { type: 'object', properties: { account: { type: 'string' } } },
+      }),
+      request_approval: defineWorkflowTool({
+        name: 'request_approval',
+        description: 'Pauses for a human approval decision.',
+        workflowId: 'discount-approval-workflow',
+        inputSchema: { type: 'object', properties: { request: { type: 'string' } } },
+      }),
+    },
+    secondaryAgents: [],
+  });
+}
+
+function createWorkflow() {
+  const trigger = new Step({ id: 'trigger', name: 'Manual Trigger', type: 'manualTrigger' });
+  const request = new Step({
+    id: 'request',
+    name: 'Request',
+    type: 'core.set',
+    params: { values: { customer: 'Acme Corp', request: 'Approve a renewal discount.' } },
+  });
+  const concierge = new Step({
+    id: 'concierge',
+    name: 'Concierge Agent',
+    type: 'core.agent',
+    params: {
+      agentReferenceKey: 'discount-concierge',
+      prompt: "Handle the request for {{ $('Request').json.customer }}.",
+      autoCloseSession: true,
+    },
+  });
+  const managerReview = new Step({
+    id: 'manager-review',
+    name: 'Manager Review',
+    type: 'core.set',
+    params: { values: { status: 'pending' }, pauseAfterExecution: true },
+  });
+  const persist = new Step({
+    id: 'persist',
+    name: 'Persist Decision',
+    type: 'core.set',
+    params: { values: { response: "={{ $('Concierge Agent').json.response }}" } },
+  });
+
+  trigger.connectTo(request);
+  request.connectTo(concierge);
+  concierge.connectTo(managerReview);
+  managerReview.connectTo(persist);
+  return new Workflow({
+    id: 'discount-request-workflow',
+    name: 'Discount Request Workflow',
+    steps: [trigger, request, concierge, managerReview, persist],
+  });
+}
+
+createApprovalToolWorkflow();
+createAccountLookupWorkflow();
+createConciergeAgent();
+createWorkflow();

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

@@ -0,0 +1,101 @@
+import { MultiAgentEngine, Step, Workflow, createAgentModelConfigFromRef } from '@culvii/kit';
+
+// Resolve both credentials through the integration picker before running dev.
+const MODEL = createAgentModelConfigFromRef(
+  'google-vertex/gemini-3.1-pro-preview',
+  'credential-id'
+);
+const GMAIL = { name: 'gmail', id: 'credential-id' };
+
+const CUTOFF_CODE = `
+export default async function main() {
+  return { cutoff: new Date(Date.now() - 5 * 60 * 1000).toISOString() };
+}
+`;
+
+function createResearchAgent() {
+  return new MultiAgentEngine({
+    id: 'email-researcher',
+    name: 'Email Researcher',
+    role: 'primary',
+    description: 'Researches a recent email and prepares a reply.',
+    systemPrompt:
+      'Read the supplied email subject and content, research its question with your approved web tools, and return only a concise reply body.',
+    model: MODEL,
+    metadata: {
+      runtimeDetails: {
+        sandboxProfile: 'default',
+      },
+    },
+    permissions: { default: { '*': 'deny', web_fetch: 'approve' } },
+    secondaryAgents: [],
+  });
+}
+
+function createWorkflow() {
+  const trigger = new Step({ id: 'trigger', name: 'Manual Trigger', type: 'manualTrigger' });
+  const cutoff = new Step({
+    id: 'cutoff',
+    name: 'Compute Cutoff',
+    type: 'core.code',
+    params: { code: CUTOFF_CODE, codeType: 'js' },
+  });
+  const readEmail = new Step({
+    id: 'read-email',
+    name: 'Read Recent Email',
+    type: 'gmail',
+    credentials: GMAIL,
+    params: {
+      resource: 'message',
+      operation: 'readAll',
+      output: 'simple',
+      limit: 10,
+      userFilters: {
+        filterBy: 'filters',
+        filters: {
+          readStatus: 'both',
+          sender: 'sender@example.com',
+          receivedAfter: "={{ $('Compute Cutoff').json.cutoff }}",
+        },
+      },
+    },
+  });
+  const research = new Step({
+    id: 'research',
+    name: 'Research Email',
+    type: 'core.agent',
+    params: {
+      agentReferenceKey: 'email-researcher',
+      prompt:
+        "Subject: {{ $('Read Recent Email').json.subject }}\nContent: {{ $('Read Recent Email').json.snippet }}\nPrepare the reply.",
+      autoCloseSession: true,
+    },
+  });
+  const sendReply = new Step({
+    id: 'send-reply',
+    name: 'Send Reply',
+    type: 'gmail',
+    credentials: GMAIL,
+    params: {
+      resource: 'message',
+      operation: 'send',
+      toRecipients: 'sender@example.com',
+      subject: "Re: {{ $('Read Recent Email').json.subject }}",
+      bodyContent: "={{ $('Research Email').json.response }}",
+      additionalFields: { bodyContentType: 'text' },
+    },
+  });
+
+  trigger.connectTo(cutoff);
+  cutoff.connectTo(readEmail);
+  readEmail.connectTo(research);
+  research.connectTo(sendReply);
+  return new Workflow({
+    id: 'integration-agent-workflow',
+    name: 'Integration Agent Workflow',
+    steps: [trigger, cutoff, readEmail, research, sendReply],
+  });
+}
+
+createResearchAgent();
+createWorkflow();

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

@@ -0,0 +1,157 @@
+import {
+  MultiAgentEngine,
+  Step,
+  Workflow,
+  createAgentModelConfigFromRef,
+  defineWorkflowTool,
+} from '@culvii/kit';
+
+const MODEL = createAgentModelConfigFromRef('openai/gpt-4.1', 'credential-id');
+
+// Workflow tools target workflows, not agents. Keep these leaf workflows free
+// of core.agent steps so the resource graph stays within the depth limit.
+function createLeafWorkflow(id: string, name: string, values: Record<string, unknown>) {
+  const trigger = new Step({ id: 'trigger', name: 'Manual Trigger', type: 'manualTrigger' });
+  const result = new Step({
+    id: 'result',
+    name,
+    type: 'core.set',
+    params: { values },
+  });
+  trigger.connectTo(result);
+  return new Workflow({ id, name, steps: [trigger, result] });
+}
+
+const inventoryTool = defineWorkflowTool({
+  name: 'check_inventory',
+  description: 'Checks stock for a SKU.',
+  workflowId: 'inventory-workflow',
+  inputSchema: {
+    type: 'object',
+    properties: { sku: { type: 'string' } },
+    additionalProperties: false,
+  },
+});
+
+const shippingTool = defineWorkflowTool({
+  name: 'quote_shipping',
+  description: 'Returns shipping options for a destination.',
+  workflowId: 'shipping-workflow',
+  inputSchema: {
+    type: 'object',
+    properties: { destination: { type: 'string' } },
+    additionalProperties: false,
+  },
+});
+
+const complianceTool = defineWorkflowTool({
+  name: 'screen_compliance',
+  description: 'Screens an order destination for export restrictions.',
+  workflowId: 'compliance-workflow',
+  inputSchema: {
+    type: 'object',
+    properties: { destination: { type: 'string' } },
+    additionalProperties: false,
+  },
+});
+
+function createCoordinatorAgent() {
+  return new MultiAgentEngine({
+    id: 'fulfillment-coordinator',
+    name: 'Fulfillment Coordinator',
+    role: 'primary',
+    description: 'Coordinates inventory, shipping, compliance, and specialist review.',
+    systemPrompt:
+      'For every line item, check inventory and quote shipping. Delegate compliance to the finance specialist and combine all returned facts into the final fulfillment plan.',
+    model: MODEL,
+    metadata: {
+      runtimeDetails: {
+        sandboxProfile: 'default',
+      },
+    },
+    permissions: {
+      default: {
+        '*': 'ask',
+        git: 'ask',
+        delete_file: 'deny',
+      },
+    },
+    tools: {
+      check_inventory: inventoryTool,
+      quote_shipping: shippingTool,
+      screen_compliance: complianceTool,
+    },
+    secondaryAgents: [
+      {
+        id: 'finance-specialist',
+        name: 'Finance Specialist',
+        role: 'secondary',
+        description: 'Screens the order and reports financial or regulatory risks.',
+        systemPrompt:
+          'Review the supplied compliance result, then return its financial or regulatory risks.',
+        model: MODEL,
+      },
+    ],
+  });
+}
+
+function createWorkflow() {
+  const trigger = new Step({ id: 'trigger', name: 'Manual Trigger', type: 'manualTrigger' });
+  const order = new Step({
+    id: 'order',
+    name: 'Order',
+    type: 'core.set',
+    params: {
+      values: {
+        customer: 'Acme Corp',
+        destination: 'DE',
+        lineItems: [
+          { sku: 'WIDGET-001', quantity: 12 },
+          { sku: 'GADGET-114', quantity: 4 },
+        ],
+      },
+    },
+  });
+  const coordinator = new Step({
+    id: 'coordinator',
+    name: 'Coordinator Agent',
+    type: 'core.agent',
+    params: {
+      agentReferenceKey: 'fulfillment-coordinator',
+      prompt:
+        "Fulfill the order for {{ $('Order').json.customer }} shipping to {{ $('Order').json.destination }}. Process every line item and use your tools and finance specialist.",
+      autoCloseSession: true,
+    },
+  });
+  const persist = new Step({
+    id: 'persist',
+    name: 'Persist Plan',
+    type: 'core.set',
+    params: { values: { plan: "={{ $('Coordinator Agent').json.response }}" } },
+  });
+
+  trigger.connectTo(order);
+  order.connectTo(coordinator);
+  coordinator.connectTo(persist);
+  return new Workflow({
+    id: 'fulfillment-workflow',
+    name: 'Fulfillment Workflow',
+    steps: [trigger, order, coordinator, persist],
+  });
+}
+
+createLeafWorkflow('inventory-workflow', 'Inventory Result', {
+  available: 420,
+  warehouse: 'us-east-1',
+});
+createLeafWorkflow('shipping-workflow', 'Shipping Quote', {
+  carrier: 'GlobalEx',
+  service: 'ground',
+  etaDays: 4,
+});
+createLeafWorkflow('compliance-workflow', 'Compliance Result', {
+  restricted: false,
+  licenseRequired: false,
+});
+createCoordinatorAgent();
+createWorkflow();

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

@@ -0,0 +1,108 @@
+import {
+  MultiAgentEngine,
+  Step,
+  Workflow,
+  createAgentModelConfigFromRef,
+  defineWorkflowTool,
+} from '@culvii/kit';
+
+const MODEL = createAgentModelConfigFromRef('anthropic/claude-sonnet-4-5', 'credential-id');
+
+// This is the agent -> workflow -> agent shape. The leaf agent has no workflow
+// tools, which keeps the reference graph at the supported maximum depth.
+function createLeafAgent() {
+  return new MultiAgentEngine({
+    id: 'evidence-reviewer',
+    name: 'Evidence Reviewer',
+    role: 'primary',
+    description: 'Reviews a brief and asks a second agent to check for gaps.',
+    systemPrompt: 'Review the brief, delegate a gap check, and return a recommendation.',
+    model: MODEL,
+    metadata: {
+      runtimeDetails: { sandboxProfile: 'default' },
+    },
+    permissions: { default: { '*': 'deny' } },
+    secondaryAgents: [
+      {
+        id: 'gap-checker',
+        name: 'Gap Checker',
+        role: 'secondary',
+        description: 'Checks a recommendation for missing evidence.',
+        systemPrompt: 'Check the recommendation for gaps and report them directly.',
+        model: MODEL,
+      },
+    ],
+  });
+}
+
+function createResearchWorkflow() {
+  const trigger = new Step({ id: 'trigger', name: 'Manual Trigger', type: 'manualTrigger' });
+  const brief = new Step({
+    id: 'brief',
+    name: 'Research Brief',
+    type: 'core.set',
+    params: { values: { topic: 'Expansion readiness', audience: 'Leadership' } },
+  });
+  const reviewer = new Step({
+    id: 'reviewer',
+    name: 'Evidence Reviewer',
+    type: 'core.agent',
+    params: {
+      agentReferenceKey: 'evidence-reviewer',
+      prompt:
+        "Review {{ $('Research Brief').json.topic }} for {{ $('Research Brief').json.audience }}.",
+      autoCloseSession: true,
+    },
+  });
+  trigger.connectTo(brief);
+  brief.connectTo(reviewer);
+  return new Workflow({
+    id: 'research-workflow',
+    name: 'Research Workflow',
+    steps: [trigger, brief, reviewer],
+  });
+}
+
+function createRootAgent() {
+  return new MultiAgentEngine({
+    id: 'strategy-agent',
+    name: 'Strategy Agent',
+    role: 'primary',
+    description: 'Delegates research to a workflow and a second opinion to a specialist.',
+    systemPrompt:
+      'Call research_readiness first, ask the strategist for a second opinion, then combine both results.',
+    model: MODEL,
+    metadata: {
+      runtimeDetails: {
+        sandboxProfile: 'default',
+      },
+    },
+    permissions: { default: { '*': 'ask', read_file: 'approve', delete_file: 'deny' } },
+    tools: {
+      research_readiness: defineWorkflowTool({
+        name: 'research_readiness',
+        description: 'Runs the research workflow.',
+        workflowId: 'research-workflow',
+        inputSchema: {
+          type: 'object',
+          properties: { topic: { type: 'string' } },
+          additionalProperties: false,
+        },
+      }),
+    },
+    secondaryAgents: [
+      {
+        id: 'strategist',
+        name: 'Strategist',
+        role: 'secondary',
+        description: 'Provides a second opinion on the root agent’s research result.',
+        systemPrompt: 'Review the supplied research result and return a concise second opinion.',
+        model: MODEL,
+      },
+    ],
+  });
+}
+
+createLeafAgent();
+createResearchWorkflow();
+createRootAgent();

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,77 @@
+# 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,
+    },
+  ],
+});
+```
+
+Context-window capacity is platform controlled, not agent authored. It defaults
+to `512_000`; an operator may override an exact provider/model through
+`AGENT_MODEL_CONTEXT_WINDOWS`. The platform includes the current user prompt
+when deciding whether older session turns must be compacted.
+
+Workflow-context helpers and delegation tools are available by default. Sandbox
+tools, including `web_fetch` and `git`, follow top-level `permissions.default`.
+Only tools with an explicit rule or `'*'` rule are available. Root `tools`
+contains only configured workflow tools.
+
+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.
+
+Choose the sandbox image when authoring the agent with
+`metadata.runtimeDetails.sandboxProfile`. This is a platform-configured profile
+name such as `node`, `go`, or `java`, not a Docker image reference. The platform
+resolves it to an immutable digest and snapshots that choice when the session is
+created:
+
+```ts
+metadata: { runtimeDetails: { sandboxProfile: 'go' } },
+```
+
+Ask the platform operator to publish and configure the profile before using it.
+Agents without this setting use the `default` profile.
+
+Sandbox tools use top-level platform-enforced permissions. Missing entries are
+unavailable; exact names override `'*'`:
+
+```ts
+metadata: { runtimeDetails: { sandboxProfile: 'go' } },
+permissions: {
+  default: {
+      '*': 'ask',
+      read_file: 'approve',
+      delete_file: 'deny',
+  },
+},
+```
+
+`approve` runs automatically, `deny` removes the tool, and `ask` suspends the
+agent until the user decides in the console. Governed sandbox and workflow tools
+belong to the root agent so durable continuation has one exact model transcript;
+secondary agents return analysis to that root. Workflow tools need no permission;
+each invocation suspends durably until its child workflow finishes, including
+any HITL wait. Workflow-context helpers remain always available.
+
+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 the Console [surface review](surface-feedback.md), 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/).