# 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
Lifecycle: preview -> confirm -> execute. Preview is mandatory before any side effect; execute without a matching preview is refused.

- 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 intent replay, diagnostics sharing, endpoint edits, secret rotation, endpoint deletion, and sender test operations where exposed through API, CLI, or MCP Agent Operations access. Each records an audit entry on execute or refusal. The API stores these records under the formal actionIntents contract.

## 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.