@culvii/cli 0.0.7 → 0.0.8

package/skills/culvii/references/surface-display.md

@@ -0,0 +1,390 @@
+# Surface display components
+
+## Avatar
+
+Initials derived from a name or email.
+
+- Children: `none`
+
+Props:
+
+- `email` (string; bindable) — Fallback source for initials.
+
+- `label` (string; bindable) — Text beside the avatar.
+
+- `name` (string; bindable) — Name used for initials.
+
+- `size` (string; literal; values: "sm" | "md" | "lg") — Avatar size.
+
+## Badge
+
+Small label with an explicit tone.
+
+- Children: `none`
+
+Props:
+
+- `format` (string; literal; values: "text" | "number" | "compact" | "percent" | "currency" | "bytes" | "duration" | "date" | "datetime" | "time" | "list" | "json" | "boolean") — Display format.
+
+- `maxChars` (number; literal; integer; min 1) — Maximum displayed characters.
+
+- `text` (any; bindable) — Badge label.
+
+- `tone` (string; literal; values: "neutral" | "info" | "success" | "warning" | "error") — Badge tone.
+
+- `transform` (string; literal; values: "capitalize" | "title" | "upper" | "lower" | "humanize") — Text transform.
+
+## Code
+
+Monospace text block.
+
+- Children: `none`
+- Limits: `{"characters":20000}`
+
+Props:
+
+- `label` (string; bindable) — Block label.
+
+- `text` (any; bindable) — Code or payload.
+
+- `wrap` (boolean; literal) — Wrap long lines.
+
+## DiffView
+
+Structural JSON or line-by-line text comparison.
+
+- Children: `none`
+- Limits: `{"depth":6,"children":100,"lines":2000,"characters":200000}`
+
+Props:
+
+- `after` (any; bindable) — Proposed value.
+
+- `before` (any; bindable) — Prior value.
+
+- `mode` (string; literal; values: "json" | "text") — Comparison mode.
+
+## Duration
+
+A duration in milliseconds or between two instants.
+
+- Children: `none`
+
+Props:
+
+- `end` (union; bindable) — End instant.
+  - Variant 1: string; literal
+  - Variant 2: number; literal
+
+- `size` (string; literal; values: "xs" | "sm" | "md" | "lg") — Displayed value size.
+
+- `start` (union; bindable) — Start instant.
+  - Variant 1: string; literal
+  - Variant 2: number; literal
+
+- `tone` (string; literal; values: "default" | "muted" | "success" | "warning" | "error" | "info") — Displayed value tone.
+
+- `unit` (string; literal; values: "seconds" | "ms") — Numeric instant unit.
+
+- `value` (number; bindable; min 0) — Duration in milliseconds.
+
+## EmailMessageCard
+
+Inbox list or opened email message.
+
+- Children: `none`
+- Limits: `{"renderedMessages":50}`
+
+Props:
+
+- `body` (string; bindable) — Message body.
+
+- `cc` (string; bindable) — Carbon-copy recipients.
+
+- `date` (union; bindable) — Sent or received instant.
+  - Variant 1: string; literal
+  - Variant 2: number; literal
+
+- `emptyText` (string; bindable) — Empty-state text.
+
+- `fields` (object; literal) — Field-name mapping.
+
+- `from` (string; bindable) — Sender.
+
+- `labels` (array; bindable) — Message labels.
+  - Items: string; literal
+
+- `message` (object; bindable) — Single message.
+
+- `messages` (array; bindable) — Message list.
+  - Items: object; literal
+
+- `snippet` (string; bindable) — Preview text.
+
+- `subject` (string; bindable) — Subject.
+
+- `to` (string; bindable) — Recipients.
+
+- `unread` (boolean; bindable) — Unread state.
+
+## FileChip
+
+Metadata and download affordance for a produced file.
+
+- Children: `none`
+- Interaction: `single-action`
+
+Props:
+
+- `file` (object; bindable) — Binary descriptor.
+  - `downloadUrl` (string; literal) — Protected download URL.
+  - `fileName` (string; literal) — Original file name.
+  - `key` (string; literal; required) — Binary property key.
+  - `mimeType` (string; literal) — MIME type.
+  - `size` (number; literal; min 0) — File size in bytes.
+
+- `label` (string; bindable) — Displayed file name.
+
+## Heading
+
+A section title.
+
+- Children: `none`
+
+Props:
+
+- `level` (number; literal; values: 1 | 2 | 3; integer) — Heading level.
+
+- `maxChars` (number; literal; integer; min 1) — Maximum displayed characters.
+
+- `text` (any; bindable) — Heading text.
+
+- `transform` (string; literal; values: "capitalize" | "title" | "upper" | "lower" | "humanize") — Text transform.
+
+## HtmlRenderer
+
+Sandboxed HTML fragment renderer.
+
+- Children: `none`
+- Limits: `{"characters":20000}`
+
+Props:
+
+- `allowRemoteImages` (boolean; literal) — Allow remote HTTPS images.
+
+- `emptyText` (string; bindable) — Empty-state text.
+
+- `height` (number; literal; min 80; max 1200) — Frame height in pixels.
+
+- `html` (string; bindable) — HTML markup.
+
+- `label` (string; bindable) — Frame label.
+
+## JsonInspector
+
+Collapsible JSON tree and default fallback renderer.
+
+- Children: `none`
+
+Props:
+
+- `collapsed` (boolean; literal) — Start collapsed.
+
+- `value` (any; bindable) — Any JSON value.
+
+## KeyValue
+
+Declared label/value entries or a bound object.
+
+- Children: `none`
+
+Props:
+
+- `columns` (number; literal; values: 1 | 2; integer) — Pairs per row.
+
+- `dense` (boolean; literal) — Use tighter row spacing.
+
+- `emptyText` (string; bindable) — Empty-state text.
+
+- `entries` (array; bindable) — Declared label/value entries.
+  - Items: object; literal
+    - `currency` (string; literal) — ISO 4217 currency code.
+    - `decimals` (number; literal; integer; min 0; max 20) — Fixed decimal places.
+    - `format` (string; literal; values: "text" | "number" | "compact" | "percent" | "currency" | "bytes" | "duration" | "date" | "datetime" | "time" | "list" | "json" | "boolean") — Display format.
+    - `label` (string; bindable) — Row label.
+    - `map` (object; literal) — Map known displayed values to labels.
+    - `maxChars` (number; literal; integer; min 1) — Maximum displayed characters.
+    - `mono` (boolean; literal) — Render the value in monospace.
+    - `tone` (string; literal; values: "default" | "muted" | "success" | "warning" | "error" | "info") — Displayed value tone.
+    - `transform` (string; literal; values: "capitalize" | "title" | "upper" | "lower" | "humanize") — Text transform.
+    - `type` (string; literal; values: "status") — Set to status to render a status pill.
+    - `unit` (string; literal; values: "seconds" | "ms") — Numeric timestamp unit.
+    - `value` (any; bindable) — Row value.
+
+- `hideEmpty` (boolean; literal) — Hide missing values.
+
+- `humanizeKeys` (boolean; literal) — Humanize object keys.
+
+- `mono` (boolean; literal) — Render shorthand values in monospace.
+
+- `value` (object; bindable) — Object whose keys become labels.
+
+## Money
+
+A formatted currency amount.
+
+- Children: `none`
+
+Props:
+
+- `currency` (string; bindable) — ISO 4217 currency code.
+
+- `decimals` (number; literal; integer; min 0; max 20) — Fixed decimal places.
+
+- `signed` (boolean; literal) — Colour positive and negative values.
+
+- `size` (string; literal; values: "xs" | "sm" | "md" | "lg") — Displayed value size.
+
+- `tone` (string; literal; values: "default" | "muted" | "success" | "warning" | "error" | "info") — Displayed value tone.
+
+- `value` (number; bindable) — Currency amount.
+
+## Stat
+
+One prominent value with a label and caption.
+
+- Children: `none`
+
+Props:
+
+- `caption` (any; bindable) — Caption below the value.
+
+- `captionTransform` (string; literal; values: "capitalize" | "title" | "upper" | "lower" | "humanize") — Caption transform.
+
+- `currency` (string; literal) — ISO 4217 currency code.
+
+- `decimals` (number; literal; integer; min 0; max 20) — Fixed decimal places.
+
+- `format` (string; literal; values: "text" | "number" | "compact" | "percent" | "currency" | "bytes" | "duration" | "date" | "datetime" | "time" | "list" | "json" | "boolean") — Display format.
+
+- `label` (string; bindable) — Label above the value.
+
+- `maxChars` (number; literal; integer; min 1) — Maximum displayed characters.
+
+- `mono` (boolean; literal) — Render the value in monospace.
+
+- `tone` (string; literal; values: "default" | "muted" | "success" | "warning" | "error" | "info") — Displayed value tone.
+
+- `transform` (string; literal; values: "capitalize" | "title" | "upper" | "lower" | "humanize") — Text transform.
+
+- `unit` (string; literal; values: "seconds" | "ms") — Numeric timestamp unit.
+
+- `value` (any; bindable) — Displayed value.
+
+## StatusPill
+
+Semantic status pill for statuses, booleans, and HTTP codes.
+
+- Children: `none`
+
+Props:
+
+- `format` (string; literal; values: "text" | "number" | "compact" | "percent" | "currency" | "bytes" | "duration" | "date" | "datetime" | "time" | "list" | "json" | "boolean") — Display format.
+
+- `label` (any; bindable) — Displayed label.
+
+- `maxChars` (number; literal; integer; min 1) — Maximum displayed characters.
+
+- `status` (any; bindable) — Status value.
+
+- `tone` (string; literal; values: "neutral" | "info" | "success" | "warning" | "error") — Forced tone.
+
+- `transform` (string; literal; values: "capitalize" | "title" | "upper" | "lower" | "humanize") — Text transform.
+
+## Table
+
+Tabular view of an array.
+
+- Children: `none`
+- Limits: `{"renderedRows":100}`
+
+Props:
+
+- `columns` (array; literal) — Literal field names or column definitions.
+  - Items: union; literal
+    - Variant 1: string; literal
+    - Variant 2: object; literal
+      - `align` (string; literal; values: "left" | "center" | "right") — Cell alignment.
+      - `currency` (string; literal) — ISO 4217 currency code.
+      - `decimals` (number; literal; integer; min 0; max 20) — Fixed decimal places.
+      - `format` (string; literal; values: "text" | "number" | "compact" | "percent" | "currency" | "bytes" | "duration" | "date" | "datetime" | "time" | "list" | "json" | "boolean") — Display format.
+      - `header` (string; literal) — Column heading.
+      - `key` (string; literal; required) — Field name inside each row.
+      - `map` (object; literal) — Map known displayed values to labels.
+      - `maxChars` (number; literal; integer; min 1) — Maximum displayed characters.
+      - `mono` (boolean; literal) — Render cells in monospace.
+      - `tone` (string; literal; values: "default" | "muted" | "success" | "warning" | "error" | "info") — Displayed value tone.
+      - `transform` (string; literal; values: "capitalize" | "title" | "upper" | "lower" | "humanize") — Text transform.
+      - `type` (string; literal; values: "status") — Set to status to render status pills.
+      - `unit` (string; literal; values: "seconds" | "ms") — Numeric timestamp unit.
+
+- `dense` (boolean; literal) — Use tighter rows.
+
+- `emptyText` (string; bindable) — Empty-state text.
+
+- `items` (array; bindable) — Rows to render.
+  - Items: any; literal
+
+## Text
+
+Body text with shared formatting.
+
+- Children: `none`
+
+Props:
+
+- `currency` (string; literal) — ISO 4217 currency code.
+
+- `decimals` (number; literal; integer; min 0; max 20) — Fixed decimal places.
+
+- `format` (string; literal; values: "text" | "number" | "compact" | "percent" | "currency" | "bytes" | "duration" | "date" | "datetime" | "time" | "list" | "json" | "boolean") — Display format.
+
+- `maxChars` (number; literal; integer; min 1) — Maximum displayed characters.
+
+- `mono` (boolean; literal) — Render in monospace.
+
+- `muted` (boolean; literal) — Shorthand for the muted tone.
+
+- `size` (string; literal; values: "xs" | "sm" | "md" | "lg") — Displayed value size.
+
+- `text` (any; bindable) — Value to display.
+
+- `tone` (string; literal; values: "default" | "muted" | "success" | "warning" | "error" | "info") — Displayed value tone.
+
+- `transform` (string; literal; values: "capitalize" | "title" | "upper" | "lower" | "humanize") — Text transform.
+
+- `unit` (string; literal; values: "seconds" | "ms") — Numeric timestamp unit.
+
+- `weight` (string; literal; values: "normal" | "medium" | "semibold") — Font weight.
+
+## Timestamp
+
+ISO or epoch timestamp.
+
+- Children: `none`
+
+Props:
+
+- `format` (string; literal; values: "datetime" | "date" | "time" | "smart") — Timestamp format.
+
+- `relative` (boolean; literal) — Display relative time.
+
+- `size` (string; literal; values: "xs" | "sm" | "md" | "lg") — Displayed value size.
+
+- `tone` (string; literal; values: "default" | "muted" | "success" | "warning" | "error" | "info") — Displayed value tone.
+
+- `unit` (string; literal; values: "seconds" | "ms") — Numeric timestamp unit.
+
+- `value` (union; bindable) — ISO string or epoch number.
+  - Variant 1: string; literal
+  - Variant 2: number; literal

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

@@ -0,0 +1,41 @@
+# Surface configuration and visual approval
+
+Use this flow for every newly authored workflow. The agent authors surfaces; the user chooses the experience and approves what they see.
+
+## Choose before validation
+
+1. After planning the workflow graph and expected node data, ask once through the agent's native in-run question tool whether the user wants to configure runtime widgets or keep the defaults. Do not end the chat run to ask.
+2. If the user chooses configuration, ask for each node in each workflow whether to:
+   - create a custom surface now;
+   - attach a compatible existing surface; or
+   - use the platform default.
+3. Present only real existing surfaces found in project files or command output. Never invent a surface reference. Combine independent node choices into the fewest question-tool prompts the agent supports.
+4. Read [surface authoring](surface-authoring.md) and only the component catalog pages needed for custom choices. Use expected output shape and the workflow's purpose to design the surface; do not ask the user to write component documents.
+5. Create every custom candidate as a real Culvii `Surface` and attach it to its workflow step before the first `culvii dev`. "Candidate" describes its approval state, not a separate resource type. Attach selected existing surfaces now and leave default choices unchanged.
+
+Do not introduce a wait surface or pause merely to display output. A wait surface is valid only when the requested workflow already requires human input. Surface documents use only supported Culvii components and bindings; the temporary preview HTML described below is never placed in a `.culvii.ts` file.
+
+## Validate and collect data
+
+Start one tracked `culvii dev` process after the workflow and all candidate surfaces exist. Fix every schema, prop, binding, slot, and cross-resource error reported by the watcher. Never preview an invalid candidate.
+
+Once the draft graph syncs successfully, run the [workflow feedback cycle](feedback-cycle.md). Use its successful node outputs as preview data. For an authored cron, webhook, or polling trigger, create a representative payload matching its real output shape and deliver it through the temporary manual-trigger conversion. This supplies the trigger's surface and downstream nodes without mocking or invoking the runtime trigger implementation. Sanitize private values and replace credentials, tokens, raw binary, and other secrets with harmless representative values.
+
+## Visual approval loop
+
+For each custom candidate:
+
+1. Create a tracked temporary directory outside the project and generate a self-contained HTML file that approximates the validated Culvii surface with its sanitized execution data. Use inline CSS and only minimal local JavaScript needed for visual interaction. Make no network requests. Escape untrusted text, do not embed credentials or raw binary, and label the page **Visual preview — Culvii runtime rendering may differ**.
+2. Ask for permission before launching the local `file://` page in the user's browser. If the environment cannot open it, provide the local file path and keep the same chat run waiting for review; do not treat the surface as approved.
+3. Ask through the native in-run question tool:
+   - **Keep this widget** — accept the attached custom surface;
+   - **Change it** — collect plain-language feedback in the same run; or
+   - **Use the default** — detach/remove the candidate and keep the platform default.
+4. For **Change it**, edit the real surface, wait for the active `culvii dev` watcher to validate and sync it, regenerate the HTML with the same data, and ask again. Never show a revision that failed validation.
+5. For **Use the default**, remove the custom attachment/resource as appropriate and wait for `culvii dev` to validate the updated graph.
+
+The HTML is a review aid, not a second validator and not a claim of pixel parity with the Culvii runtime. Component contracts and bindings remain authoritative through `culvii dev`.
+
+## Finish
+
+Every node must end as accepted custom, selected existing, platform default, or explicitly skipped by the user. After the final workflow execution succeeds, delete only the tracked temporary preview directory and follow the development guide to stop the exact `culvii dev` process. Never report completion while a custom surface is awaiting review.

package/skills/culvii/references/surface-input-actions.md

@@ -0,0 +1,143 @@
+# Surface input and action components
+
+## ApproveRejectBar
+
+Named approve/reject decision actions.
+
+- Children: `none`
+- Interaction: `multi-action`
+- Actions: `{"allowed":["approve","reject"]}`
+
+Props:
+
+- `approveLabel` (string; bindable) — Approve button label.
+
+- `canDecide` (boolean; bindable) — Whether the viewer may decide.
+
+- `comment` (string; bindable) — Current comment value.
+
+- `commentRequired` (boolean; bindable) — Require a comment before rejection.
+
+- `decidedBy` (string; bindable) — Recorded decider.
+
+- `decision` (string; bindable) — Recorded decision.
+
+- `disabledReason` (string; bindable) — Reason actions are disabled.
+
+- `rejectLabel` (string; bindable) — Reject button label.
+
+## Button
+
+Single-action button.
+
+- Children: `none`
+- Interaction: `single-action`
+
+Props:
+
+- `disabled` (boolean; bindable) — Disabled state.
+
+- `label` (string; bindable) — Button label.
+
+- `variant` (string; literal; values: "primary" | "default" | "danger") — Button variant.
+
+## Checkbox
+
+Boolean form input.
+
+- Children: `none`
+- Interaction: `input`
+
+Props:
+
+- `description` (string; bindable) — Helper text.
+
+- `disabled` (boolean; bindable) — Disabled state.
+
+- `label` (string; bindable) — Text beside the checkbox.
+
+## Select
+
+Single-choice form input.
+
+- Children: `none`
+- Interaction: `input`
+
+Props:
+
+- `disabled` (boolean; bindable) — Disabled state.
+
+- `label` (string; bindable) — Field label.
+
+- `options` (array; bindable) — Literal or bound options.
+  - Items: union; literal
+    - Variant 1: string; literal
+    - Variant 2: number; literal
+    - Variant 3: object; literal
+      - `label` (string; literal) — Displayed option label.
+      - `value` (union; literal; required) — Submitted option value.
+        - Variant 1: string; literal
+        - Variant 2: number; literal
+
+- `placeholder` (string; bindable) — Placeholder.
+
+## TextArea
+
+Multi-line form input.
+
+- Children: `none`
+- Interaction: `input`
+
+Props:
+
+- `disabled` (boolean; bindable) — Disabled state.
+
+- `label` (string; bindable) — Field label.
+
+- `placeholder` (string; bindable) — Placeholder.
+
+- `rows` (number; literal; integer; min 1) — Visible rows.
+
+## TextField
+
+Single-line form input.
+
+- Children: `none`
+- Interaction: `input`
+
+Props:
+
+- `disabled` (boolean; bindable) — Disabled state.
+
+- `label` (string; bindable) — Field label.
+
+- `placeholder` (string; bindable) — Placeholder.
+
+- `type` (string; literal; values: "text" | "number" | "email" | "url") — HTML input type.
+
+## Reserved and rejected component types
+
+- `Accordion` — unsupported and rejected by validation.
+- `AgentRunPanel` — unsupported and rejected by validation.
+- `CalendarEventCard` — unsupported and rejected by validation.
+- `DatePicker` — unsupported and rejected by validation.
+- `ErrorPanel` — unsupported and rejected by validation.
+- `Icon` — unsupported and rejected by validation.
+- `Image` — unsupported and rejected by validation.
+- `List` — unsupported and rejected by validation.
+- `Markdown` — unsupported and rejected by validation.
+- `ProgressBar` — unsupported and rejected by validation.
+- `RadioGroup` — unsupported and rejected by validation.
+- `SlackMessageCard` — unsupported and rejected by validation.
+- `SlackThread` — unsupported and rejected by validation.
+- `Spacer` — unsupported and rejected by validation.
+- `Spinner` — unsupported and rejected by validation.
+- `Tabs` — unsupported and rejected by validation.
+- `Timeline` — unsupported and rejected by validation.
+- `ToolCallCard` — unsupported and rejected by validation.
+- `Tree` — unsupported and rejected by validation.
+
+## Slot policies
+
+- Output: actions navigate; forms rejected.
+- Wait: actions navigate, node.resume, node.stop; forms allowed.

package/skills/culvii/references/surface-layout.md

@@ -0,0 +1,97 @@
+# Surface layout components
+
+## Card
+
+Bordered container with an optional header and status.
+
+- Children: `single`
+
+Props:
+
+- `dense` (boolean; literal) — Use tighter body padding.
+
+- `map` (object; literal) — Map known displayed values to labels.
+
+- `status` (any; bindable) — Status value used to derive the header pill.
+
+- `statusLabel` (any; bindable) — Header status label.
+
+- `statusTone` (string; literal; values: "neutral" | "info" | "success" | "warning" | "error") — Forced status tone.
+
+- `subtitle` (string; bindable) — Header subtitle.
+
+- `title` (string; bindable) — Header title.
+
+- `transform` (string; literal; values: "capitalize" | "title" | "upper" | "lower" | "humanize") — Status label transform.
+
+## Divider
+
+Horizontal rule between content blocks.
+
+- Children: `none`
+
+Props:
+
+_No props._
+
+## Form
+
+Groups wait-surface inputs and actions.
+
+- Children: `list`
+
+Props:
+
+- `title` (string; bindable) — Form heading.
+
+## Grid
+
+Responsive equal-width columns.
+
+- Children: `list`
+
+Props:
+
+- `columns` (number; literal; values: 1 | 2 | 3 | 4; integer) — Column count.
+
+- `gap` (string; literal; values: "xs" | "sm" | "md" | "lg") — Spacing between children.
+
+## Row
+
+Wrapping horizontal group.
+
+- Children: `list`
+
+Props:
+
+- `align` (string; literal; values: "start" | "center" | "end" | "baseline") — Cross-axis alignment.
+
+- `gap` (string; literal; values: "xs" | "sm" | "md" | "lg") — Spacing between children.
+
+- `justify` (string; literal; values: "between") — Set to between to push children apart.
+
+## Section
+
+Labelled group with one child.
+
+- Children: `single`
+
+Props:
+
+- `collapsible` (boolean; literal) — Allow the section to be folded.
+
+- `defaultOpen` (boolean; literal) — Initial collapsible state.
+
+- `description` (string; bindable) — Section description.
+
+- `title` (string; bindable) — Section label.
+
+## Stack
+
+Vertical stack and the default surface container.
+
+- Children: `list`
+
+Props:
+
+- `gap` (string; literal; values: "xs" | "sm" | "md" | "lg") — Spacing between children.

package/skills/culvii/references/validation.md

@@ -0,0 +1,18 @@
+# Validation and common failures
+
+- `agentReferenceKey` must resolve to a collected agent ID; `agentId` is invalid.
+- Workflow-tool `workflowId` values and local custom surface keys must resolve.
+- Workflow-tool targets follow the trigger, agent-node, and reference-depth rules in [workflows.md](workflows.md).
+- Credentialed nodes require `{ name, id }`; model configs require `credentialId`. Never author raw secrets.
+- A surface's slot must match `ui.output` or `ui.wait`.
+- Surface component IDs must be unique, reachable, and connected by ID references. Maximum graph depth is 12 and maximum component count is 300.
+- Use only active catalog types. Reserved types are rejected.
+- Bindings accept `$output`, `$input`, `$exec`, `$binary`, and wait-only `$form`; JSON Pointer syntax and step names must be exact.
+- Output surfaces allow navigation actions. Wait surfaces additionally allow node resume/stop actions and form input.
+- A versioned custom surface reference may point to a published version. An unversioned local custom surface must be present in the same collected graph.
+
+When validation fails, fix the resource definition rather than bypassing validation. Keep running `culvii dev` after each fix until evaluation, validation, and draft sync succeed. Do not present the resources as complete while errors remain.
+
+After validation succeeds, use the [workflow feedback cycle](feedback-cycle.md) for requested workflows. Feedback runtime overrides never replace platform validation.
+
+Further reading: [Testing](https://culvii.com/docs/sdk-reference/guides/testing/).