Action previews

# Action previews

Canonical: https://docs.flowrelay.app/reference/action-intents/
Markdown: https://docs.flowrelay.app/reference/action-intents.md

Preview, confirmation, idempotency, metering, audit, and refusal behavior for approved actions.

## Intent lifecycle
For preview_or_execute operations, the lifecycle is preview -> confirm -> execute. Execute without the required matching preview and confirmation is refused. This lifecycle does not apply to read_only, handoff_only, or direct create_resource operations.


- Stage: Preview; What happens: A preview explains the target, current configuration, possible side effects, the authority required, and the idempotency key that will carry into execute.
- Stage: Confirm; What happens: A human or authorized agent confirms the exact action inside the grant and product boundary.
- Stage: Execute; What happens: FlowRelay performs the action, records audit context, and returns the result or refusal.

## Actions that need previews
Use action previews for replay, diagnostics sharing, endpoint edits, secret rotation, endpoint deletion, and support request preview/submit. Each records audit context on execute or refusal. Endpoint creation and expansion or feature requests are direct create_resource operations and do not use this lifecycle; endpoint-test intent is handoff_only and returns sender-owned test instructions rather than sending traffic.


## Direct creation and support submission
Endpoint creation executes when the scoped request is accepted and returns its new secret once. Expansion and feature requests record non-binding request resources directly with expansion:request scope. Support request preview and submit use explicit request states, consent, redaction, and idempotency, but the API does not claim that submit is coupled to a persisted matching-preview record.


## Idempotency
Carry the same idempotency key from preview to execute. Generate a fresh preview, and a new key, if the target, payload, endpoint, event, or actor changes. Reusing a key after any of these changes is refused.


## Metering
FlowRelay counts action previews separately from executed actions. Repeated preview loops can hit short-window rate limits or sustained fair-use review even when no action is executed, so check plan usage before broad reads, polling, or repeated previews.


## Audit and refusals
Audit preserves who previewed, who confirmed, what was executed, and which grant allowed it. Refusals explain the missing scope, unsafe state, expired retention, usage limit, or product boundary.


## Example Surface
- `preview -> confirm -> execute`
- `idempotencyKey`
- `refusal.reason`

## Safety Boundary
Do not share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs in public examples.