Agent orientation

# Agent orientation

Canonical: https://docs.flowrelay.app/agent-access/agent-orientation/
Markdown: https://docs.flowrelay.app/agent-access/agent-orientation.md

Agents learn FlowRelay from public docs first, then use authenticated API, CLI, or MCP surfaces only within the merchant-authorized grant.

## Agent workflow
Agents should orient through docs before using authenticated tools.
1. Fetch /llms.txt to discover canonical pages and Markdown equivalents.
2. Read the Markdown page for the task, such as setup, receipts, replay, diagnostics, or grants.
3. Read /agent/v1/manifest to confirm platform identity, capability metadata, docs URLs, safety boundaries, and route names.
4. Use OpenAPI for exact request and response contracts before calling authenticated routes.
5. Use CLI or MCP only as wrappers over the same scoped Agent Operations contract.
6. Escalate to a human when the docs, grant, manifest, or refusal reason says the action is outside authority.

## Orientation order
Start with /llms.txt for the index, read the relevant Markdown page, check /agent/v1/manifest for edition and capability context, then use OpenAPI for exact request and response shapes.


## Which surface to use
The API is canonical. The CLI and MCP surfaces behave as wrappers over the same Agent Operations contract and point agents back to these docs when they need product context.


## Skills timing
FlowRelay docs, OpenAPI, CLI, and MCP references are the canonical agent surfaces. Installable skills are optional; when FlowRelay offers them, they point back to these docs for product meaning and safety boundaries.


## Escalation
Escalate when the grant, manifest, docs, API refusal, CLI response, or MCP tool result says the action is outside authority or requires human judgment.


## Related
- [API Reference](https://docs.flowrelay.app/reference/api.md)
- [OpenAPI](https://docs.flowrelay.app/reference/openapi.md)
- [CLI Reference](https://docs.flowrelay.app/reference/cli.md)
- [MCP Reference](https://docs.flowrelay.app/reference/mcp.md)

## Safety Boundary
Do not include raw payloads, endpoint secrets, auth headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.