@culvii/cli 0.0.7 → 0.0.9

package/skills/culvii/references/node-slack-events-trigger.md

@@ -0,0 +1,37 @@
+# slackEventsTrigger
+
+- Type ID: `slackEventsTrigger`
+- Kind: `trigger`
+- Credentials: required as `credentials: { name, id }`; `name` must be one of: `slack_events`
+- Feedback mock: required
+
+Resolve the credential through [integration selection](integrations.md); never ask the user to copy a credential ID.
+
+## Props
+
+- `method`: string; required
+- `event`: options; optional
+  - Values: `message`, `app_mention`, `reaction_added`, `all`
+- `filters`: object; optional
+  - `channelId`: string; optional
+  - `userId`: string; optional
+  - `textContains`: string; optional
+  - `excludeBots`: boolean; optional
+  - `threads`: options; optional
+    - Values: `all`, `topLevel`, `replies`
+  - `includeMessageChanges`: boolean; optional
+- `pauseAfterExecution`: boolean; optional
+
+## Example
+
+```ts
+new Step({
+  id: 'slack-events-trigger',
+  name: 'slackEventsTrigger',
+  type: 'slackEventsTrigger',
+  credentials: { name: 'slack_events', id: 'credential-id' },
+  params: { /* use the required props and conditional values above */ },
+});
+```
+
+Further reading: [Culvii slackEventsTrigger node](https://culvii.com/docs/nodes/triggers/slack-events-trigger/).

package/skills/culvii/references/node-slack-interactions-trigger.md

@@ -0,0 +1,28 @@
+# slackInteractionsTrigger
+
+- Type ID: `slackInteractionsTrigger`
+- Kind: `trigger`
+- Credentials: required as `credentials: { name, id }`; `name` must be one of: `slack_events`
+- Feedback mock: required
+
+Resolve the credential through [integration selection](integrations.md); never ask the user to copy a credential ID.
+
+## Props
+
+- `method`: string; required
+- `actionId`: string; optional
+- `pauseAfterExecution`: boolean; optional
+
+## Example
+
+```ts
+new Step({
+  id: 'slack-interactions-trigger',
+  name: 'slackInteractionsTrigger',
+  type: 'slackInteractionsTrigger',
+  credentials: { name: 'slack_events', id: 'credential-id' },
+  params: { /* use the required props and conditional values above */ },
+});
+```
+
+Further reading: [Culvii slackInteractionsTrigger node](https://culvii.com/docs/nodes/triggers/slack-interactions-trigger/).

package/skills/culvii/references/node-slack-trigger.md

@@ -0,0 +1,40 @@
+# slackTrigger
+
+- Type ID: `slackTrigger`
+- Kind: `trigger`
+- Credentials: required as `credentials: { name, id }`; `name` must be one of: `slack_bot`, `slack_user`
+- Feedback mock: required
+
+Resolve the credential through [integration selection](integrations.md); never ask the user to copy a credential ID.
+
+## Props
+
+- `pollIntervalMs`: number; required
+- `event`: options; required
+  - Values: `messagePosted`
+- `channelId`: string; required
+- `output`: options; optional
+  - Values: `simple`, `raw`
+- `filters`: object; optional
+  - `userId`: string; optional
+  - `textContains`: string; optional
+  - `excludeBots`: boolean; optional
+  - `subtype`: string; optional
+- `options`: object; optional
+  - `maxMessages`: number; optional
+  - `includeThreadReplies`: boolean; optional
+- `pauseAfterExecution`: boolean; optional
+
+## Example
+
+```ts
+new Step({
+  id: 'slack-trigger',
+  name: 'slackTrigger',
+  type: 'slackTrigger',
+  credentials: { name: 'slack_bot', id: 'credential-id' },
+  params: { /* use the required props and conditional values above */ },
+});
+```
+
+Further reading: [Culvii slackTrigger node](https://culvii.com/docs/nodes/triggers/slack-trigger/).

package/skills/culvii/references/node-slack.md

@@ -0,0 +1,162 @@
+# slack
+
+- Type ID: `slack`
+- Kind: `action`
+- Credentials: required as `credentials: { name, id }`; `name` must be one of: `slack_bot`, `slack_user`
+- Feedback mock: required
+
+Resolve the credential through [integration selection](integrations.md); never ask the user to copy a credential ID.
+
+## Props
+
+- `resource`: options; required
+  - Values: `message`, `reaction`, `user`, `channel`, `file`, `search`, `interaction`
+- `operation`: options; required; when resource=message
+  - Values: `send`, `sendByEmail`, `update`, `delete`, `getReplies`, `getPermalink`, `schedule`, `listScheduled`, `cancelScheduled`, `sendEphemeral`
+- `channel`: string; required; when resource=message, operation=send
+- `text`: string; required; when resource=message, operation=send
+- `additionalFields`: object; optional; when resource=message, operation=send
+  - `thread_ts`: string; optional
+  - `reply_broadcast`: boolean; optional
+  - `blocks`: json; optional
+  - `mrkdwn`: boolean; optional
+  - `link_names`: boolean; optional
+  - `unfurl_links`: boolean; optional
+  - `unfurl_media`: boolean; optional
+- `email`: string; required; when resource=message, operation=sendByEmail
+- `text`: string; required; when resource=message, operation=sendByEmail
+- `messageOptions`: object; optional; when resource=message, operation=sendByEmail
+  - `blocks`: json; optional
+  - `mrkdwn`: boolean; optional
+  - `link_names`: boolean; optional
+  - `unfurl_links`: boolean; optional
+  - `unfurl_media`: boolean; optional
+- `channel`: string; required; when resource=message, operation=sendEphemeral
+- `userId`: string; required; when resource=message, operation=sendEphemeral
+- `text`: string; required; when resource=message, operation=sendEphemeral
+- `ephemeralOptions`: object; optional; when resource=message, operation=sendEphemeral
+  - `thread_ts`: string; optional
+  - `blocks`: json; optional
+  - `link_names`: boolean; optional
+- `channel`: string; required; when resource=message, operation=schedule
+- `text`: string; required; when resource=message, operation=schedule
+- `postAt`: dateTime; required; when resource=message, operation=schedule
+- `scheduleOptions`: object; optional; when resource=message, operation=schedule
+  - `thread_ts`: string; optional
+  - `reply_broadcast`: boolean; optional
+  - `blocks`: json; optional
+  - `link_names`: boolean; optional
+  - `unfurl_links`: boolean; optional
+  - `unfurl_media`: boolean; optional
+- `channelId`: string; optional; when resource=message, operation=listScheduled
+- `oldest`: dateTime; optional; when resource=message, operation=listScheduled
+- `latest`: dateTime; optional; when resource=message, operation=listScheduled
+- `limit`: number; optional; when resource=message, operation=listScheduled
+- `cursor`: string; optional; when resource=message, operation=listScheduled
+- `channelId`: string; required; when resource=message, operation=cancelScheduled
+- `scheduledMessageId`: string; required; when resource=message, operation=cancelScheduled
+- `channelId`: string; required; when resource=message, operation=update
+- `messageTs`: string; required; when resource=message, operation=update
+- `text`: string; required; when resource=message, operation=update
+- `blocks`: json; optional; when resource=message, operation=update
+- `channelId`: string; required; when resource=message, operation=delete
+- `messageTs`: string; required; when resource=message, operation=delete
+- `channelId`: string; required; when resource=message, operation=getReplies
+- `threadTs`: string; required; when resource=message, operation=getReplies
+- `limit`: number; optional; when resource=message, operation=getReplies
+- `output`: options; optional; when resource=message, operation=getReplies
+  - Values: `simple`, `raw`
+- `cursor`: string; optional; when resource=message, operation=getReplies
+- `channelId`: string; required; when resource=message, operation=getPermalink
+- `messageTs`: string; required; when resource=message, operation=getPermalink
+- `operation`: options; required; when resource=reaction
+  - Values: `add`, `remove`
+- `channelId`: string; required; when resource=reaction, operation=add
+- `messageTs`: string; required; when resource=reaction, operation=add
+- `emoji`: string; required; when resource=reaction, operation=add
+- `channelId`: string; required; when resource=reaction, operation=remove
+- `messageTs`: string; required; when resource=reaction, operation=remove
+- `emoji`: string; required; when resource=reaction, operation=remove
+- `operation`: options; required; when resource=user
+  - Values: `getByEmail`, `getMany`, `getProfile`, `updateProfile`
+- `email`: string; required; when resource=user, operation=getByEmail
+- `output`: options; optional; when resource=user, operation=getByEmail
+  - Values: `simple`, `raw`
+- `limit`: number; optional; when resource=user, operation=getMany
+- `output`: options; optional; when resource=user, operation=getMany
+  - Values: `simple`, `raw`
+- `cursor`: string; optional; when resource=user, operation=getMany
+- `user`: string; optional; when resource=user, operation=getProfile
+- `user`: string; optional; when resource=user, operation=updateProfile
+- `clearStatus`: boolean; optional; when resource=user, operation=updateProfile
+- `status_text`: string; optional; when resource=user, operation=updateProfile
+- `status_emoji`: string; optional; when resource=user, operation=updateProfile
+- `status_expiration`: string; optional; when resource=user, operation=updateProfile
+- `first_name`: string; optional; when resource=user, operation=updateProfile
+- `last_name`: string; optional; when resource=user, operation=updateProfile
+- `email`: string; optional; when resource=user, operation=updateProfile
+- `operation`: options; required; when resource=channel
+  - Values: `getMany`, `create`, `archive`, `setTopic`, `invite`, `remove`
+- `channelTypes`: options; optional; when resource=channel, operation=getMany
+  - Values: `public`, `private`, `publicAndPrivate`, `directMessages`, `groupDirectMessages`, `all`
+- `excludeArchived`: boolean; optional; when resource=channel, operation=getMany
+- `limit`: number; optional; when resource=channel, operation=getMany
+- `output`: options; optional; when resource=channel, operation=getMany
+  - Values: `simple`, `raw`
+- `cursor`: string; optional; when resource=channel, operation=getMany
+- `channelName`: string; required; when resource=channel, operation=create
+- `isPrivate`: boolean; optional; when resource=channel, operation=create
+- `channelId`: string; required; when resource=channel, operation=archive
+- `channelId`: string; required; when resource=channel, operation=setTopic
+- `topic`: string; required; when resource=channel, operation=setTopic
+- `channelId`: string; required; when resource=channel, operation=invite
+- `userIds`: string; required; when resource=channel, operation=invite
+- `channelId`: string; required; when resource=channel, operation=remove
+- `userId`: string; required; when resource=channel, operation=remove
+- `operation`: options; required; when resource=file
+  - Values: `upload`, `getInfo`, `download`
+- `binaryPropertyName`: string; required; when resource=file, operation=upload
+- `channelId`: string; optional; when resource=file, operation=upload
+- `uploadOptions`: object; optional; when resource=file, operation=upload
+  - `filename`: string; optional
+  - `title`: string; optional
+  - `initial_comment`: string; optional
+  - `thread_ts`: string; optional
+  - `alt_txt`: string; optional
+- `fileId`: string; required; when resource=file, operation=getInfo
+- `output`: options; optional; when resource=file, operation=getInfo
+  - Values: `simple`, `raw`
+- `fileId`: string; required; when resource=file, operation=download
+- `binaryPropertyName`: string; required; when resource=file, operation=download
+- `operation`: options; required; when resource=search
+  - Values: `messages`, `files`
+- `query`: string; required; when resource=search
+- `count`: number; optional; when resource=search
+- `page`: number; optional; when resource=search
+- `sort`: options; optional; when resource=search
+  - Values: `score`, `timestamp`
+- `sort_dir`: options; optional; when resource=search
+  - Values: `asc`, `desc`
+- `operation`: options; required; when resource=interaction
+  - Values: `respond`
+- `responseUrl`: string; required; when resource=interaction, operation=respond
+- `text`: string; optional; when resource=interaction, operation=respond
+- `blocks`: json; optional; when resource=interaction, operation=respond
+- `replaceOriginal`: boolean; optional; when resource=interaction, operation=respond
+- `responseType`: options; optional; when resource=interaction, operation=respond
+  - Values: `in_channel`, `ephemeral`
+- `pauseAfterExecution`: boolean; optional
+
+## Example
+
+```ts
+new Step({
+  id: 'slack',
+  name: 'slack',
+  type: 'slack',
+  credentials: { name: 'slack_bot', id: 'credential-id' },
+  params: { /* use the required props and conditional values above */ },
+});
+```
+
+Further reading: [Culvii slack node](https://culvii.com/docs/nodes/slack/).

package/skills/culvii/references/node-supabase.md

@@ -0,0 +1,61 @@
+# supabase
+
+- Type ID: `supabase`
+- Kind: `action`
+- Credentials: required as `credentials: { name, id }`; `name` must be one of: `supabase`
+- Feedback mock: required
+
+Resolve the credential through [integration selection](integrations.md); never ask the user to copy a credential ID.
+
+## Props
+
+- `resource`: options; required
+  - Values: `database`, `storage`
+- `operation`: options; required; when resource=database
+  - Values: `getRows`, `insertRow`, `updateRows`, `upsertRow`, `deleteRows`, `callFunction`
+- `operation`: options; required; when resource=storage
+  - Values: `uploadFile`, `downloadFile`, `listFiles`, `deleteFile`
+- `table`: string; required; when resource=database, operation=getRows
+- `columns`: string; optional; when resource=database, operation=getRows
+- `filters`: json; optional; when resource=database, operation=getRows
+- `order`: string; optional; when resource=database, operation=getRows
+- `limit`: number; optional; when resource=database, operation=getRows
+- `table`: string; required; when resource=database, operation=insertRow
+- `rowData`: json; required; when resource=database, operation=insertRow
+- `table`: string; required; when resource=database, operation=updateRows
+- `filters`: json; required; when resource=database, operation=updateRows
+- `rowData`: json; required; when resource=database, operation=updateRows
+- `table`: string; required; when resource=database, operation=upsertRow
+- `rowData`: json; required; when resource=database, operation=upsertRow
+- `onConflict`: string; optional; when resource=database, operation=upsertRow
+- `table`: string; required; when resource=database, operation=deleteRows
+- `filters`: json; required; when resource=database, operation=deleteRows
+- `functionName`: string; required; when resource=database, operation=callFunction
+- `args`: json; optional; when resource=database, operation=callFunction
+- `bucket`: string; required; when resource=storage, operation=uploadFile
+- `filePath`: string; required; when resource=storage, operation=uploadFile
+- `binaryPropertyName`: string; required; when resource=storage, operation=uploadFile
+- `upsert`: boolean; optional; when resource=storage, operation=uploadFile
+- `bucket`: string; required; when resource=storage, operation=downloadFile
+- `filePath`: string; required; when resource=storage, operation=downloadFile
+- `binaryPropertyName`: string; required; when resource=storage, operation=downloadFile
+- `bucket`: string; required; when resource=storage, operation=listFiles
+- `folderPath`: string; optional; when resource=storage, operation=listFiles
+- `limit`: number; optional; when resource=storage, operation=listFiles
+- `bucket`: string; required; when resource=storage, operation=deleteFile
+- `filePath`: string; required; when resource=storage, operation=deleteFile
+- `pauseAfterExecution`: boolean; optional
+
+## Example
+
+```ts
+new Step({
+  id: 'supabase',
+  name: 'supabase',
+  type: 'supabase',
+  credentials: { name: 'supabase', id: 'credential-id' },
+  params: { /* use the required props and conditional values above */ },
+});
+```
+
+Further reading: [Culvii supabase node](https://culvii.com/docs/nodes/supabase/).

package/skills/culvii/references/node-twilio.md

@@ -0,0 +1,39 @@
+# twilio
+
+- Type ID: `twilio`
+- Kind: `action`
+- Credentials: required as `credentials: { name, id }`; `name` must be one of: `twilio`
+- Feedback mock: required
+
+Resolve the credential through [integration selection](integrations.md); never ask the user to copy a credential ID.
+
+## Props
+
+- `resource`: options; optional
+  - Values: `call`
+- `operation`: options; optional; when resource=call
+  - Values: `makeCall`
+- `fromNumber`: string; required; when resource=call, operation=makeCall
+- `toNumber`: string; required; when resource=call, operation=makeCall
+- `sayList`: array; required; when resource=call, operation=makeCall
+- `noResponseSayList`: array; optional; when resource=call, operation=makeCall
+- `positiveResponseSayList`: array; optional; when resource=call, operation=makeCall
+- `negativeResponseSayList`: array; optional; when resource=call, operation=makeCall
+- `positiveResponse`: number; required; when resource=call, operation=makeCall
+- `speechRate`: string; optional; when resource=call, operation=makeCall
+- `record`: boolean; optional; when resource=call, operation=makeCall
+- `pauseAfterExecution`: boolean; optional
+
+## Example
+
+```ts
+new Step({
+  id: 'twilio',
+  name: 'twilio',
+  type: 'twilio',
+  credentials: { name: 'twilio', id: 'credential-id' },
+  params: { /* use the required props and conditional values above */ },
+});
+```
+
+Further reading: [Culvii twilio node](https://culvii.com/docs/nodes/twilio/).

package/skills/culvii/references/node-wait-timer.md

@@ -0,0 +1,24 @@
+# waitTimer
+
+- Type ID: `waitTimer`
+- Kind: `action`
+- Credentials: not required
+- Feedback mock: not required
+
+## Props
+
+- `resumeIn`: number; required
+- `pauseAfterExecution`: boolean; optional
+
+## Example
+
+```ts
+new Step({
+  id: 'wait-timer',
+  name: 'waitTimer',
+  type: 'waitTimer',
+  params: { /* use the required props and conditional values above */ },
+});
+```
+
+Further reading: [Culvii waitTimer node](https://culvii.com/docs/nodes/wait-timer/).

package/skills/culvii/references/node-webhook-trigger.md

@@ -0,0 +1,24 @@
+# webhookTrigger
+
+- Type ID: `webhookTrigger`
+- Kind: `trigger`
+- Credentials: not required
+- Feedback mock: not required
+
+## Props
+
+- `method`: string; required
+- `pauseAfterExecution`: boolean; optional
+
+## Example
+
+```ts
+new Step({
+  id: 'webhook-trigger',
+  name: 'webhookTrigger',
+  type: 'webhookTrigger',
+  params: { /* use the required props and conditional values above */ },
+});
+```
+
+Further reading: [Culvii webhookTrigger node](https://culvii.com/docs/nodes/triggers/webhook-trigger/).

package/skills/culvii/references/nodes-index.md

@@ -0,0 +1,51 @@
+# Node index
+
+Generated from `GENERATED_NODE_DEFINITIONS`. Open the exact node page before authoring its params.
+
+- [`argocd`](node-argocd.md) — action; credentials required; feedback mock required
+- [`clickupDoc`](node-clickup-doc.md) — action; credentials required; feedback mock required
+- [`clickupTicket`](node-clickup-ticket.md) — action; credentials required; feedback mock required
+- [`core.agent`](node-core-agent.md) — action
+- [`core.browserAutomation`](node-core-browser-automation.md) — action; feedback mock required
+- [`core.code`](node-core-code.md) — action
+- [`core.http`](node-core-http.md) — action; feedback mock required
+- [`core.if`](node-core-if.md) — action
+- [`core.jwt`](node-core-jwt.md) — action
+- [`core.loop`](node-core-loop.md) — action
+- [`core.loopBreak`](node-core-loop-break.md) — action
+- [`core.loopContinue`](node-core-loop-continue.md) — action
+- [`core.loopOutput`](node-core-loop-output.md) — action
+- [`core.merge`](node-core-merge.md) — action
+- [`core.set`](node-core-set.md) — action
+- [`core.switch`](node-core-switch.md) — action
+- [`costExplorer`](node-cost-explorer.md) — action; credentials required; feedback mock required
+- [`cronTrigger`](node-cron-trigger.md) — trigger
+- [`elasticsearch`](node-elasticsearch.md) — action; credentials required; feedback mock required
+- [`github`](node-github.md) — action; credentials required; feedback mock required
+- [`githubPollTrigger`](node-github-poll-trigger.md) — trigger; credentials required; feedback mock required
+- [`githubWebhookTrigger`](node-github-webhook-trigger.md) — trigger; credentials required; feedback mock required
+- [`gmail`](node-gmail.md) — action; credentials required; feedback mock required
+- [`gmailTrigger`](node-gmail-trigger.md) — trigger; credentials required; feedback mock required
+- [`googleCalendar`](node-google-calendar.md) — action; credentials required; feedback mock required
+- [`googleDocs`](node-google-docs.md) — action; credentials required; feedback mock required
+- [`grafanaDashboard`](node-grafana-dashboard.md) — action; credentials required; feedback mock required
+- [`grafanaDataSource`](node-grafana-data-source.md) — action; credentials required; feedback mock required
+- [`grafanaQuery`](node-grafana-query.md) — action; credentials required; feedback mock required
+- [`hibp.listDomains`](node-hibp-list-domains.md) — action; credentials required; feedback mock required
+- [`hibp.stealerLogs`](node-hibp-stealer-logs.md) — action; credentials required; feedback mock required
+- [`kubernetes`](node-kubernetes.md) — action; credentials required; feedback mock required
+- [`manualTrigger`](node-manual-trigger.md) — trigger
+- [`microsoftOutlook`](node-microsoft-outlook.md) — action; credentials required; feedback mock required
+- [`microsoftOutlookTrigger`](node-microsoft-outlook-trigger.md) — trigger; credentials required; feedback mock required
+- [`microsoftSharepoint`](node-microsoft-sharepoint.md) — action; credentials required; feedback mock required
+- [`onionsearch`](node-onionsearch.md) — action; credentials required; feedback mock required
+- [`prometheus`](node-prometheus.md) — action; credentials required; feedback mock required
+- [`s3`](node-s3.md) — action; credentials required; feedback mock required
+- [`slack`](node-slack.md) — action; credentials required; feedback mock required
+- [`slackEventsTrigger`](node-slack-events-trigger.md) — trigger; credentials required; feedback mock required
+- [`slackInteractionsTrigger`](node-slack-interactions-trigger.md) — trigger; credentials required; feedback mock required
+- [`slackTrigger`](node-slack-trigger.md) — trigger; credentials required; feedback mock required
+- [`supabase`](node-supabase.md) — action; credentials required; feedback mock required
+- [`twilio`](node-twilio.md) — action; credentials required; feedback mock required
+- [`waitTimer`](node-wait-timer.md) — action
+- [`webhookTrigger`](node-webhook-trigger.md) — trigger

package/skills/culvii/references/runtime-values.md

@@ -0,0 +1,36 @@
+# Runtime values
+
+Workflow expressions and surface bindings are different languages. Do not mix them.
+
+## Workflow expressions
+
+Step params are resolved recursively through nested objects and arrays. A value consisting entirely of an expression preserves its runtime type; interpolation inside other text always returns a string.
+
+```ts
+params: { values: {
+  object: "={{ $('Prepare').json.payload }}",
+  nested: { ids: ["={{ $('Prepare').json.id }}", '={{ $system.execId }}'] },
+  message: "Account {{ $('Prepare').json.account }} is ready",
+} }
+```
+
+Selectors:
+
+- `$json.field` or `json.field`: current input.
+- `$('Step Name').json.field`: named step, default port and item index.
+- `$('Step Name:port')[2].json.field`: named port and index.
+- `$system.execId`, `$system.workflowId`, `$system.node.id`: execution metadata.
+
+The `.json` segment after a named step is optional. Use step names, not IDs. Expressions are selectors, not JavaScript.
+
+## Surface bindings
+
+A binding is an object such as `{ path: '/$output/Prepare/main/0/0/account', default: 'Unknown', format: 'text' }`. Its `path` is a JSON Pointer rooted at:
+
+- `$output`: current surfaced step output.
+- `$input`: ancestor step output.
+- `$exec`: execution metadata.
+- `$binary`: safe binary descriptors, not raw bytes.
+- `$form`: wait-surface form state only.
+
+Output/input/binary paths use `/<root>/<step name>/<port>/<output index>/<item index>/...`. Escape `~` as `~0` and `/` as `~1` in every JSON Pointer segment. A real `null` is not replaced by `default`.

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

@@ -0,0 +1,38 @@
+# Surface authoring
+
+Choose components from the use case and expected node data, then verify every prop in the generated catalog pages.
+
+For workflow-attached surfaces, make selection, validation, preview, and approval decisions through [surface configuration and visual approval](surface-feedback.md).
+
+- Objects: `KeyValue`; wrap important groups in `Card` or `Section`.
+- Arrays: `Table` for comparable records, or repeated domain cards composed with layout components.
+- Metrics: `Stat`, `Money`, `Duration`, or `Timestamp`.
+- Files: `FileChip` bound through `$binary`. Binding `file` alone renders a read-only file
+  summary — it is NOT clickable until you also declare `actions.default` as a `navigate` action
+  whose `href` points at the same descriptor's `downloadUrl`:
+  ```ts
+  {
+    id: 'file', type: 'FileChip',
+    props: { file: { path: '/$binary/Render Report/main/0/0/report' } },
+    actions: {
+      default: { type: 'navigate', href: { path: '/$binary/Render Report/main/0/0/report/downloadUrl' } },
+    },
+  }
+  ```
+- Human decisions: a wait `Form` with input components and `Button`, or `ApproveRejectBar`.
+- Raw/debug values: `JsonInspector` or `Code`.
+
+A definition uses `schema: 'kit.ui/v1'`, a root component ID, a flat component document list, and an optional wait form. `root` and `children` contain IDs. Never embed a component object directly inside `children`.
+
+```ts
+definition: {
+  schema: 'kit.ui/v1', root: 'outer', components: [
+    { id: 'outer', type: 'Stack', children: ['card'] },
+    { id: 'card', type: 'Card', props: { title: 'Result' }, children: ['inner'] },
+    { id: 'inner', type: 'Stack', children: ['status'] },
+    { id: 'status', type: 'StatusPill', props: { status: { path: '/$output/Run/main/0/0/status' } } },
+  ],
+}
+```
+
+Recursive Stack/Card/Section graphs are valid up to platform depth 12. Recursive prop schemas are also supported. Component IDs must be unique, reachable from the root, and referenced once according to each component's child mode. The complete catalog is split into [layout](surface-layout.md), [display](surface-display.md), and [input/actions](surface-input-actions.md).