@culvii/cli 0.0.7 → 0.0.9

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. Binding `file` alone does not make the chip clickable — declare `actions.default` as a `navigate` action with `href` bound to the same descriptor's `downloadUrl` path (e.g. `{ path: "/$binary/<step>/main/0/0/<key>/downloadUrl" }`), or the chip renders as a read-only file summary with no download button.
+
+- 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,38 @@
+# Surface configuration and visual approval
+
+Use this flow for every newly authored workflow. The agent authors surfaces; the user reviews the exact Culvii renderer before accepting them.
+
+## 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 runtime widgets or platform 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, attach a real existing surface, or use the default. Combine independent choices into the fewest prompts the agent supports.
+3. Read [surface authoring](surface-authoring.md) and only the component catalog pages needed for custom choices. Use expected output shape and workflow purpose; do not ask the user to write component documents.
+4. Create every custom candidate as a real Culvii `Surface` and attach it to its workflow step before the first `culvii dev`. Attach selected existing surfaces now and leave default choices unchanged.
+
+Do not add a wait surface or pause merely to display output. A wait surface is valid only when the workflow already needs human input.
+
+## Validate, execute, and review
+
+1. Start one tracked `culvii dev` process after the workflow and all candidate surfaces exist. Fix every validation and sync error before previewing.
+2. Run the [workflow feedback cycle](feedback-cycle.md). Its successful execution supplies the preview data. For a cron, webhook, or polling trigger, use its temporary manual-trigger conversion and representative payload; never invoke or mock the runtime trigger implementation.
+3. For every custom surface in that execution, create a review manifest. It includes only the configured nodes, never the full run:
+
+```json
+{
+  "items": [
+    { "executionId": "exc_…", "nodeId": "research-agent" },
+    { "executionId": "exc_…", "nodeId": "report-output" }
+  ]
+}
+```
+
+4. Run `culvii surface review create --file <manifest.json> --json`. It returns a Console URL. Ask permission before running `culvii surface review open <review-id>`; otherwise show the URL to the user and keep the same chat run open.
+5. The review page uses the production `SurfaceView` renderer, groups items by workflow, and labels each preview as **Mocked output**, **Simulated trigger**, or **Executed output**. It shows only the configured custom surfaces.
+6. Wait for the user to choose **Keep this surface**, **Request changes**, or **Use default** for every item and submit the review. Read `culvii surface review get <review-id> --json` to obtain the decisions; do not ask the user to paste them into chat.
+7. For changes, edit the real surface and let the active `culvii dev` watcher validate/sync it. Create a new review after the next successful feedback execution. For default, remove the custom attachment/resource as appropriate and let `culvii dev` validate it.
+
+The review is an ephemeral, user-scoped record. It resolves the current draft surface and current execution data on each page load, so it never claims that an old preview matches a revised surface. It expires after two hours; recreate it if needed.
+
+## Finish
+
+Every configured node must end as accepted custom, selected existing, platform default, or explicitly skipped. Restore any temporary trigger conversion, wait for `culvii dev` to sync it, then stop only the exact `culvii dev` process started for this task. 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/).