# 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
Action previews make side effects deliberate and auditable.

- Stage: Preview; What happens: FlowRelay explains the target, current configuration, possible side effects, required authority, and idempotency key.
- 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 delete, and sender test operations when those operations are exposed through API, CLI, or MCP Agent Operations access. The API stores these records under the formal actionIntents contract.

## Idempotency
Preserve the idempotency key from preview through execute. If the target, payload, endpoint, event, or actor changes, create a fresh preview.

## 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 include raw event bodies, endpoint secrets, authentication headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.