name: breyta
description: >-
Use Breyta CLI to turn end-user problems into validated flow behavior with the
canonical lifecycle: pull/push/validate -> run, with release/promote/installations as advanced rollout.

Goal

Translate user problems into correct flow changes and verified runtime behavior.

Required Output

1. Problem contract: trigger, inputs, outputs, integrations, failure behavior.
2. Flow delta: what changed (file/slug/steps/bindings/config).
3. Runtime proof: commands run + workflow IDs + observed status/output.
4. Risk ledger: what remains unverified or blocked.

Non-Negotiables

• Never assume command shape. Verify with breyta help ... and breyta docs find ....
• Use docs search as primary docs path: docs find -> docs show.
• Before creating a new flow, inspect workspace flows first: breyta flows list then breyta flows show <slug>.
• Use breyta flows search <query> only for approved template discovery/reuse.
• Treat flow grouping as mutable metadata, not authored source. Verify grouping via breyta flows list --pretty / breyta flows show <slug> --pretty rather than the pulled .clj file.
• Global catalog search still works without a selected workspace; --catalog-scope workspace requires one.
• Reuse existing workspace connections before creating new ones.
• Keep :flow orchestration-focused; use top-level :functions and :templates for shaping/static content.
• Ask for concrete missing config (connections, secrets, installation inputs); do not invent values.
• Prefer exact recovery URLs from failures when available: error.actions[].url first, then meta.webUrl.
• For successful reads/runs, include web links from CLI JSON (meta.webUrl / data.*.webUrl) so users can inspect in Breyta web.
• Only derive canonical recovery URLs when the needed ids are already known: billing, activate, draft-bindings, installation, or connection edit.
• When blocked, include the exact recovery URL in Runtime proof, not just generic "go to billing/setup" text.
• If blocked by missing capability or repeated unclear failures, submit feedback with breyta feedback send before closing the task.

Capability Discovery

Minimum discovery for non-trivial tasks:

• breyta docs
• breyta docs find "flows"
• breyta flows --help
• breyta runs --help
• breyta resources --help

Useful search examples:

• breyta docs find "source:cli flows run" --limit 10 --offset 0
• breyta docs find "\"end-user\" AND source:flows-api" --limit 10
• breyta docs find "install" --with-snippets --explain --format json

Cross-Docs Search (Secondary)

Use only for offline/regex corpus scans:

breyta docs sync --out ./.breyta-docs --clean
rg -n "<query>" ./.breyta-docs/pages

Preflight

1. Confirm auth/API:
   • breyta auth whoami
   • breyta flows list --limit 1
2. Confirm workspace context:
   • Check workspace/token/env before writes.
3. Confirm reusable resources:
   • breyta connections list
   • Existing workspace flow: breyta flows list then breyta flows show <slug>
   • Approved template discovery: breyta flows search <query>
4. Confirm grouping context when related flows should ship together:
   • breyta flows list --pretty
   • breyta flows show <slug> --pretty
   • Look for groupKey, groupName, groupDescription, groupOrder, and groupFlows

Canonical Execution Loop

1. Understand the contract

• Trigger mode, integrations, expected output, failure policy.

1. Bootstrap from existing artifacts

• Prefer existing flow file first:
  • breyta flows pull <slug> --out ./tmp/flows/<slug>.clj

1. Working copy iteration

• breyta flows push --file ./tmp/flows/<slug>.clj
• breyta flows configure <slug> ... (when required)
• breyta flows configure check <slug>
• If the flow belongs to a bundle of dependent flows, set explicit order with breyta flows update <slug> --group-order <n> and re-check grouping after metadata changes with breyta flows show <slug> --pretty
• Live target updates after slot changes: use --target live --version <n|latest> (and --from-draft when promoting draft bindings)
• Optional read-only verification: breyta flows validate <slug>

1. Run and verify

• Canonical run:
  • breyta flows run <slug> --input '<json>' --wait
• Installation-targeted run when required (advanced):
  • breyta flows run <slug> --installation-id <installation-id> --wait
• Inspect run:
  • breyta runs show <workflow-id>
  • Persisted artifacts discovery: breyta resources search "<query>", breyta resources list --query "<query>" --types file,result --accept text/*,application/json --exclude-tier ephemeral, and breyta resources workflow list <workflow-id>

1. Advanced rollout (only when needed)

• breyta flows diff <slug>
• breyta flows release <slug> --release-note-file ./release-note.md
• breyta flows versions update <slug> --version <n> --release-note-file ./release-note.md
• breyta flows promote <slug>
• breyta flows installations configure <installation-id> --input '{...}'

Install Operations

Use these for end-user/runtime setup:

• breyta flows installations list <flow-slug>
• breyta flows installations get <installation-id>
• breyta flows installations triggers <installation-id>
• breyta flows installations upload <installation-id> --file ./a.pdf

Rollback

Capture pre-change state:

• breyta flows show <slug> --pretty
• breyta flows show <slug> --include versions --pretty

Rollback path:

• breyta flows promote <slug> --version <last-known-good>
• Re-run representative verification and record evidence.

Definition Of Done

1. Working copy validates for intended flow changes.
2. At least one representative flows run succeeds for the default target.
3. At least one representative run reaches expected terminal status.
4. Required side effects/output are confirmed (not inferred).
5. Report includes evidence and unresolved risks.

Failure Triage

1. Capability mismatch

• Re-check with breyta docs find + breyta help.

1. Config mismatch

• Re-check auth/workspace/token context.

1. Installation config mismatch

• Inspect and configure installation (install show / install configure).

1. Runtime mismatch

• Narrow to changed step, validate, release, and re-run.

Compatibility Notes

Legacy commands remain executable but are non-canonical for end-user guidance:

• use canonical commands first and treat hidden aliases as compatibility-only paths.