> ## Documentation Index
> Fetch the complete documentation index at: https://flows.breyta.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Start Here

Breyta quickstart for the default flow lifecycle: draft working copy -> configure -> run.

## Quick Answer

Use this sequence:

```bash
# Optional for agent sessions; also follow any CLI missing/stale skill warning:
breyta skills status --provider all
breyta docs find "flows" --limit 5 --format json
breyta flows search "<workspace pattern or integration>" --limit 5
breyta flows templates search "<problem keyword>" --limit 5
breyta resources search "<existing report, upload, or run output>" --limit 5
# Reuse/create/test connections up front (recommended when flow uses external systems):
# breyta connections list
# breyta connections create ...
# breyta connections test <connection-id>   # health/config check only; still do a real flow run
breyta flows pull <slug> --out ./tmp/flows/<slug>.clj
breyta flows lint --file ./tmp/flows/<slug>.clj
breyta flows push --file ./tmp/flows/<slug>.clj
# Configure/check before first run when the flow has :requires slots.
# Example:
# breyta flows configure <slug> --set api.conn=conn-...
breyta flows configure check <slug>
# Optional read-only verification (useful for CI/troubleshooting):
breyta flows validate <slug>
breyta flows run <slug> --input '{"name":"Ada"}' --wait
# Open the run Output page returned by the CLI and confirm the final artifact is readable.
```

If you need the full command catalog or a broader docs map instead of the default lifecycle, jump to [CLI Commands](/docs/reference-cli-commands) or [Reference Index](/docs/reference-index).
For task-oriented agent work, start with [Author Flows](/docs/playbook-author-flows), then open only the exact reference needed.

## Use Breyta Docs With AI Coding Agents

Use the agent-readable docs index when working in Cursor, Claude Code, Codex,
or another coding agent:

- Breyta Flows docs index: https://flows.breyta.ai/llms.txt
- Complete Breyta Flows docs: https://flows.breyta.ai/llms-full.txt
- Markdown page form: append `.md` to any docs URL, for example https://flows.breyta.ai/docs/start-here.md
- Context7 claim file: https://flows.breyta.ai/docs/context7.json
- Context7 source: submit https://flows.breyta.ai/llms.txt or crawl https://flows.breyta.ai/docs

Recommended agent rule: when creating or editing Breyta flows, read the Breyta
Flows docs first and prefer the referenced playbooks and step references over
stale examples.

## Flow Definition Mental Model

A Breyta flow file is a DSL with Clojure/EDN syntax, not a normal Clojure
program. Think of it as an orchestration definition: declare setup contracts,
run inputs, interfaces, reusable templates/functions/steps/agents, then compose
bounded `flow/step` calls in `:flow`. Put side effects and large data at step
boundaries, keep orchestration deterministic, persist large results as resource
refs, and use small map-oriented functions for transforms.

## Draft Vs Live

`draft` is the staging/current workspace authoring state. Use it for edits,
configure checks, and safe smoke tests. `live` is the released/runtime state. A
flow is unreleased until a version is released or activated and the live path is
verified. Say `draft verified` when only draft was exercised; reserve
`released`, `end-user ready`, and `public ready` for live/install-shaped proof.

## Configure Before First Run (When Required)

`breyta flows search "<query>" --limit 5` searches actual workspace flow
metadata. Use `breyta flows grep "<literal>" --limit 5` for workspace
source/config search, such as tool names or upload fields. Approved reusable
templates live under
`breyta flows templates search "<problem keyword>" --limit 5` and
`breyta flows templates grep "<literal>"`. Add `--surface definition` or
`--surface tools` when a literal appears in too many places.

Treat search like `rg`: read the compact hit ref, matched surface/field,
snippet or preview, and `nextCommand`; open only the one focused docs page,
flow, template, or resource that the hit points to.

If the new flow should build on existing reports, uploads, table resources, or
prior run output, search resources before creating a new ingestion path:

- `breyta resources search "<query>" --limit 5`
- `breyta resources read <resource-uri> --limit 5`

If your flow declares `:requires` slots or setup form fields, configure those
values before the first run. Values that should be entered on each run belong in
`:invocations` and are supplied with `breyta flows run --input ...`.

New flows should expose manual runs through `:interfaces :manual` over an
`:invocations` contract. `breyta flows run <slug> --input ... --wait` can use
the enabled manual interface automatically. Declare at most one manual
interface; when authors need multiple entry modes, model that choice as an
invocation input such as `mode` or use another interface family. Use
`--interface-id <id>` only when you need to select the declared manual interface
explicitly. New flow source also needs an explicit `:concurrency` policy.

Use [Flow Configuration](/docs/guide-flow-configuration) for the exact configuration workflow.

## How Requires, Configure, And Connections Fit Together

| Stage | What it controls | Canonical command |
|---|---|---|
| Declare setup contract | `:requires` in the flow file defines required slots/setup inputs. | `breyta flows pull/push ...` |
| Declare run contract | `:invocations` in the flow file defines per-run inputs. | `breyta flows pull/push ...` |
| Bind values | Target bindings map each required slot to a real connection/secret/input value for a target. | `breyta flows configure <slug> --set <slot>.conn=<connection-id>` |
| Verify readiness | Checks missing/invalid bindings and required inputs before runtime. For live, prefer version-pinned checks. | `breyta flows configure check <slug>` or `breyta flows configure check <slug> --target live --version latest` |
| Run | Runtime resolves the selected target bindings and executes. | `breyta flows run <slug> ...` |
| Maintain wiring | Usage reports show where bindings reference a connection/secret. | `breyta connections usages ...` / `breyta secrets usages ...` |

Connection/secret delete guards are binding-based.
Even if a flow definition changed, delete remains blocked while any `draft`, `live`, or installation target still references that id.

## Draft Vs Live (Target Split)

If CLI works but UI fails, first check whether the CLI tested draft while the
web setup page, run form fields, installed flow, or public/end-user run used an
old live version. `flows push` updates draft only; the UI install path follows
the released live/install target.

| Target | What it means | Commands |
|---|---|---|
| `draft` (default) | Your draft setup/config target (latest `flows push` + `flows configure`). Fast iteration lane for authoring and validation. `flows run` still executes the active version unless `--version` overrides it. | `breyta flows run/show/pull/validate <slug>` |
| `live` | Installed released target for stable/runtime consumption. Changed by `release`/`promote`, not by `push`. | `breyta flows run <slug> --target live` |

## Run Target After Release

`breyta flows release <slug> --release-note-file ./release-note.md` creates a release, attaches a markdown release note, and updates the live installation target for the selected workspace by default.

`breyta flows run <slug>` still uses draft-target bindings/config unless you explicitly target live/install target.

Brand-new flows with no active version are not runnable through `flows run` until you deploy or release a version.

If the new flow has `:requires` slots, prepare the live target before the first release:

- `breyta flows configure <slug> --target live --version latest --set <slot>.conn=<connection-id>`
- `breyta flows configure check <slug> --target live --version latest`

To run the installed live target, use one of:

- `breyta flows run <slug> --target live --wait`
- `breyta flows run <slug> --installation-id <installation-id> --wait`

If you intentionally skipped end-user installation promotion (`--skip-promote-installations`), promote them later with:

- `breyta flows promote <slug>`
- `breyta flows versions update <slug> --version <n> --release-note-file ./release-note.md` if you need to edit the release note later

Before releasing, inspect draft-vs-live changes with:

- `breyta flows diff <slug>`

## What You Get

| Outcome | Why it matters |
|---|---|
| Config target checked | Catches missing bindings/secrets/inputs before first run. |
| Optional explicit validation | Gives a read-only checkpoint for CI/troubleshooting. |
| Required config applied | Prevents first-run failures from missing bindings/secrets/inputs. |
| Runnable immediately after push | Keeps iteration fast in the same workspace. |
| Verified run output | Confirms end-to-end behavior quickly. For human-facing flows, the Output page should be a readable artifact, usually a Markdown report. |

## Shape The Final Output

The value returned by `:flow` is the run output. Treat that final return value
as a product surface, not just an automation payload. For most human-facing
flows, return a Markdown viewer envelope; when the report needs real Breyta
tables, charts, files, images, videos, or JSON resources, embed them with
`breyta-resource` fences.

Use [Output Artifacts](/docs/guide-output-artifacts) before releasing any
flow where a person will inspect the result.

## Next Playbooks And References

| Need | Page |
|---|---|
| Create or edit a flow | [Author Flows](/docs/playbook-author-flows) |
| Debug a failed run or verify output | [Debug And Verify](/docs/playbook-debug-and-verify) |
| Release, promote, or install | [Release And Install](/docs/playbook-release-and-install) |
| Public, Discover, or marketplace work | [Public And Marketplace](/docs/playbook-public-and-marketplace) |
| Fanout, paging, concurrency, large artifacts | [Advanced Reliability](/docs/playbook-advanced-reliability) |
| Full command catalog | [CLI Commands](/docs/reference-cli-commands) |
| Reference map | [Reference Index](/docs/reference-index) |
| Runtime data shapes and resource refs | [Runtime Data Shapes](/docs/reference-runtime-data-shapes) |
| Final output viewers and Markdown resource embeds | [Output Artifacts](/docs/guide-output-artifacts) |
| Setup reusable connections first | [Connections First](/docs/guide-connections-first) |
| Publish a paid public flow | [Paid Public Flows](/docs/guide-paid-public-flows) |
| Installation scopes (advanced) | [Installations](/docs/guide-installations) |
| Requires/bindings/secrets | [Flow Configuration](/docs/guide-flow-configuration) |
| Failures and triage | [Troubleshooting](/docs/guide-troubleshooting) |

## Notes

- Canonical default surface is `flows pull`, `flows push`, `flows configure`, `flows configure check`, and `flows run`.
- `flows diff` shows draft-vs-live or version-vs-version source changes on demand.
- `flows release` (auto live install for selected workspace) and `flows promote` are rollout/governance operations.
- `flows push` updates `draft` only; it does not change `live`.
- `connections test` confirms health/config state, not end-to-end step execution.
- Activation inputs are preserved across `flows release`/`flows promote`; update them explicitly via `flows configure` or `flows installations configure`.

- Legacy command aliases still execute for compatibility but are intentionally hidden from default help.