@voltro/cli 0.2.2 → 0.4.0

package/templates/agent-docs/reference.md

@@ -21,10 +21,15 @@ The web side of a Voltro app talks to API apps through React hooks. Data hooks a
 | [`useMutation`](/docs/reference/hooks-data) | Run an atomic write (`*.mutation.ts`). |
 | [`useAction`](/docs/reference/hooks-data) | Run a unary non-transactional action (`*.action.ts`). |
 | [`useWorkflow`](/docs/reference/hooks-data) | Start, cancel, resume, or signal a durable workflow (`*.workflow.tsx`). |
+| [`useWorkflowSignal`](/docs/reference/hooks-data) | Focused signal sender, for approval buttons that don't also start workflows. |
+| [`useWorkflowUpdate`](/docs/reference/hooks-data) | Focused tracked update — waits for the workflow handler's result. |
 | [`useWorkflowRun`](/docs/reference/hooks-data) | Subscribe to one workflow run's reactive status row. |
 | [`useWorkflowRuns`](/docs/reference/hooks-data) | Subscribe to a bounded/filterable workflow run list. |
 | [`useWorkflowRunSteps`](/docs/reference/hooks-data) | Subscribe to one run's checkpointed step timeline. |
 | [`useWorkflowRunEvents`](/docs/reference/hooks-data) | Subscribe to one run's lifecycle/timer/signal event timeline. |
+| [`useWorkflowDomainEvents`](/docs/reference/hooks-data) | Subscribe to the domain events a workflow emitted (the business-event timeline). |
+| [`useWorkflowEventDeliveries`](/docs/reference/hooks-data) | Subscribe to delivery attempts/outcomes for those emitted events. |
+| [`useWorkflowRunState`](/docs/ui/reactive-components) | Aggregates run + steps + events into one `{ status, currentStep, waitingFor, … }` plus cancel/resume/signal/update. |
 | [`useAgentStream`](/docs/reference/hooks-data) | Consume a one-shot element stream (`*.stream.ts`). |
 | [`useAgent`](/docs/reference/hooks-data) | Convenience wrapper for transient AI streams. |
 
@@ -44,6 +49,51 @@ The web side of a Voltro app talks to API apps through React hooks. Data hooks a
 |---|---|
 | [`useServerRequest`](/docs/reference/hooks-server) | Request snapshot during SSR and hydration-sensitive client code. |
 
+## Schema-driven UI Hooks
+
+The headless primitives that derive UI from a descriptor's Schema. **Reach for
+these before hand-rolling a form, a table, or a picker** — full guide in
+[Schema-driven UI](/docs/ui/overview).
+
+| Hook | Purpose |
+|---|---|
+| [`useFormBinding`](/docs/ui/forms-and-tables) | Bind a form to a MUTATION — fields + validation from its input Schema; a server `ValidationError({ field })` routes to that field. |
+| [`useDataTable`](/docs/ui/forms-and-tables) | Bind a table to a QUERY — live rows, columns derived from the output Schema, sort/filter/pagination. |
+| [`useQueryFilters`](/docs/ui/forms-and-tables) | Filter controls derived from a query's INPUT Schema (the read-side mirror of a form). |
+| [`useQueryField`](/docs/ui/forms-and-tables) | Query-bound picker — a debounced search term drives a live subscription. |
+| [`useFormSkeleton`](/docs/ui/client-utilities/use-skeletons) / [`useTableSkeleton`](/docs/ui/client-utilities/use-skeletons) | Placeholders shaped like the REAL data, from the same Schema. |
+| [`useAsyncValidation`](/docs/ui/client-utilities/use-async-validation) | Live server-side validation (uniqueness, cross-row) over a query binding. |
+| [`useDebounced`](/docs/ui/client-utilities/use-debounced) | Debounce a value (search, filter, validation input). |
+| [`useRecord`](/docs/ui/client-utilities/use-record) | One live record from a "get" query, normalized (array → first row). |
+
+## Files, Permissions, and Client Utilities
+
+| Hook | Purpose |
+|---|---|
+| [`useUpload`](/docs/plugins/storage) | File upload with progress + cancel, on every storage provider. Not base64 → action. |
+| [`useCan`](/docs/ui/client-utilities/use-can) | Scope/RBAC UI gate, over `<PermissionProvider>`. Lives in `@voltro/client` — scopes are a framework concept, so gating a button needs no rbac dependency. |
+| [`useCanAny`](/docs/ui/client-utilities/use-permissions) | OR variant of `useCan` — true when the subject holds AT LEAST ONE of the required scopes. |
+| [`usePermissions`](/docs/ui/client-utilities/use-permissions) / `<PermissionProvider>` | The current subject's scope set, fed once from your session query — the source `useCan` reads. Gates UI on the SAME scope strings the server checks. |
+| [`useResourceCan`](/docs/ui/client-utilities/use-permissions) / `useResourceCans` | Per-RESOURCE (ReBAC) gate, reactive — one resource or many in a single subscription. |
+| [`useDerived`](/docs/ui/client-utilities/use-derived) | Dependency-tracked derived value from reactive sources. Replaces hand-maintained `useMemo` dep arrays. |
+| [`useWindowedSubscription`](/docs/ui/client-utilities/use-windowed-subscription) | Subscribe to the VISIBLE window of a huge list, not the whole table. |
+| [`useOutbox`](/docs/ui/client-utilities/use-outbox) | Queue mutations offline, replay in order on reconnect. |
+| [`useUndoLog`](/docs/ui/client-utilities/use-undo) / `useUndo` | Client controller for the server-persisted undo stack. |
+| [`usePreview`](/docs/ui/client-utilities/use-preview) | Mutation dry-run — run the real handler in a rolled-back transaction. |
+| [`useProvenance`](/docs/ui/client-utilities/use-provenance) | "Why is this value here?" — lineage lookup for a field. |
+| [`useOnRpcError`](/docs/ui/client-utilities/use-on-rpc-error) / `reportClientError` | Subscribe to the rpc error bus; report a client error to the server. |
+| [`useTracking`](/docs/ui/client-utilities/use-tracking) | Fire mount/unmount + interaction tracking events. |
+| [`useCapabilityManifest`](/docs/ui/client-utilities/use-capability-manifest) | The api's capability manifest (procedures + tables + schemas), fetched once. |
+| [`useRefreshSubscriptions`](/docs/ui/client-utilities/use-refresh-subscriptions) | Force-refresh live subscriptions (e.g. after an out-of-band change). |
+
+## AI Hooks
+
+| Hook | Purpose |
+|---|---|
+| [`useAgentChat`](/docs/ui/reactive-components) | Full chat surface over an `*.agent.tsx` (messages + send + streaming). |
+| [`useResumableAgentStream`](/docs/ai/streaming) | Agent stream that survives reload/reconnect. |
+| [`useDataCopilot`](/docs/ai/data-copilot) | Bind a data-copilot action by api name + tag. |
+
 ## Where To Read Next
 
 - [Data hooks](/docs/reference/hooks-data)
@@ -255,6 +305,32 @@ Events include lifecycle changes, timers, signals, and updates recorded by the w
 
 `useWorkflowEvents(apiName, runId)` is a shorter alias for the same hook.
 
+## `useWorkflowDomainEvents(apiName, filters?, options?)`
+
+Subscribes to the **domain events** an app emitted through `ctx.events.emit(...)` — the business-event log behind [event triggers](/docs/workflows/event-triggers), not one run's internal timeline.
+
+```tsx
+const { events } = useWorkflowDomainEvents('app', { name: 'order.paid', limit: 50 })
+```
+
+Both filters are optional: `name` narrows to one event name, `limit` defaults to `100` and is clamped to `500` by the server. Rows arrive newest-first (by `occurredAt`), and each carries `id`, `name`, `payload`, `source`, `subject`, `traceId`, and `occurredAt`. The third argument is the standard `SubscriptionOptions` (e.g. `{ skip }`).
+
+Alongside `events`, the hook returns the normal subscription fields (`data`, `error`, `revision`, …).
+
+## `useWorkflowEventDeliveries(apiName, eventId)`
+
+Subscribes to the **fan-out** of one emitted domain event: one row per trigger the event was routed to, so you can see which workflows a single `emit(...)` actually started.
+
+```tsx
+const { deliveries } = useWorkflowEventDeliveries('app', selectedEvent?.id)
+
+deliveries.map((d) => `${d.workflowName}: ${d.status}`)
+```
+
+The subscription is skipped while `eventId` is `undefined`, so it pairs directly with a row selected out of `useWorkflowDomainEvents`. Rows are ordered oldest-first and carry `eventId`, `eventName`, `triggerId`, `workflowName`, `executionId`, `idempotencyKey`, `skipped`, `errorMessage`, `createdAt`, `completedAt`, and a `status` of `'starting'`, `'started'`, `'skipped'`, or `'failed'`.
+
+A `skipped` delivery is the normal outcome when a trigger's `filter` returned false or its `idempotencyKey` had already been seen — it is not a failure. `errorMessage` is set only on `'failed'`.
+
 ## `useAgentStream(apiName, rpcTag)`
 
 Consumes a `defineStream` RPC. Despite the name, this hook is not limited to AI agents; it handles any one-shot element stream.