Public Flows Reference

Load this reference before creating, editing, testing, releasing, promoting, or
describing public/end-user Breyta flows.

Public-Ready By Default

Assume every new or edited flow may become public unless the user explicitly
says it is internal-only. This changes how the flow is built, not whether it is
published.

Public-ready defaults:

use :requires, setup inputs, run inputs, connection slots, templates, and resources for values that vary by installer, workspace, user, region, model, file, or environment
avoid hardcoded workspace ids, user ids, emails, test resource ids, private URLs, secrets, personal accounts, and one-off local assumptions
keep outputs and timelines understandable without source code
make names, tags, descriptions, and install copy useful to the target end user

Hardcoding is acceptable only for stable public facts or documented API
constants. When a value belongs to the author, installer, or run, model it as
configuration.

Public Surfaces Are Separate

Private workspace flow: visible inside a workspace.
breyta flows search: actual workspace flow metadata.
breyta flows grep: actual workspace flow source/config search.
breyta flows templates search/grep: approved reusable template definitions to inspect and copy from.
breyta flows discover list/search: public installable catalog.
Discover visibility: stored metadata or :discover {:public true}.
Marketplace visibility: stored metadata or :marketplace {:visible true}.
Paid app catalog: stored metadata or source-authored
:marketplace {:app {... :monetization {:plans [...]}}}. Legacy
:marketplace {:monetization ...} is compatibility for existing listings,
not the preferred shape for new paid apps.
Installation: a per-user instance of an end-user flow with user-scoped prod bindings and inputs.
Activation/setup URL: the author or workspace setup surface for bindings and
saved setup inputs. It is not the public install dialog.
Discover install dialog: the public/end-user install surface. This is the
surface that proves an installable flow can be installed by an end user.

Do not use flows templates search as proof that a flow is publicly
installable. Do not use flows discover as proof that a private workspace flow
exists.

Public Flow As Reusable Tool

When another Breyta flow, hosted agent, coding agent, or external client should
reuse a public flow, prefer the installed HTTP or MCP interface over author
draft/live endpoints.

Default reuse loop:

Find the flow in Discover with breyta flows discover search.
Create, configure, and enable an installation in the caller workspace.
Inspect callable surfaces with
breyta flows installations interfaces <installation-id>.
Smoke-test through the installation:
breyta flows interfaces call <flow-slug> <interface-id> --installation-id <installation-id> --input '{"key":"value"}' --wait.
Use the installation-scoped HTTP or MCP endpoint from the wrapper flow or
external client:
/api/flows/{flow-slug}/installations/{installation-id}/interfaces/{interface-id}.

Use installation-scoped endpoints for consumers so installer setup, auth,
billing entitlement, and ownership are applied correctly. Do not hand off author
draft/live interface URLs as the normal consumer integration path.

For MCP clients, connect to the installed Streamable HTTP endpoint with bearer
auth, call initialize, then tools/list, then tools/call with the published
tool name. Treat paid-flow errors such as billing_trial_ended as billing or
trial state, not as proof that the interface contract is broken.

Install And Public App Links

Do not guess install links from the current authoring page context. In
particular, do not treat an activation/setup URL such as /activate as the
public install page unless the docs or CLI output identify it as the requested
install surface.

Distinguish these surfaces when handing off public or installable work:

Authoring flow page: where the creator edits, releases, configures, and runs the flow inside the source workspace.
Activation/setup page: where a workspace configures an existing flow target or installation. This is setup, not proof of public installability.
Internal app/install surface: where a workspace user can install, configure, or run an installed app inside Breyta, commonly under the workspace Apps area.
Discover/install surface: where public installable flows are found and installed after Discover visibility is enabled.
Public marketing app page: for public flows, also provide https://breyta.ai/apps/<flow-slug> so the creator can view, share, and market the app.

When the user asks to make a flow installable:

first confirm the requested distribution: internal installable, public Discover installable, monetized, or marketplace-visible
do not treat "make this a public app" as permission to expose it to all Breyta users; ask directly before turning on Discover or marketplace visibility
load this reference before changing release, install, Discover, marketplace, or public copy behavior
release/promote only after explicit approval when required by the approval gate
enable Discover/public visibility only after the user has approved that distribution
verify the install surface through CLI/docs/UI evidence rather than inferring from the page the user happened to be viewing
when CLI/API support the approved public, pricing, listing, Discover, or marketplace change, do it directly instead of sending the user to the publish page
for new paid apps, keep plan ids stable, use at most one default/recommended
plan, and do not model seat pricing unless explicit seat entitlements exist
report every relevant URL returned by Breyta: authoring flow, setup/activation, install surface, Discover/public listing, public marketing app page, run, and run output

Approval Gate

Never set Discover or marketplace visibility without explicit flow-author
approval. The approval must say that the flow may be made accessible to all
Breyta users now. A vague request to "make it public" or "make this a public
app" is not enough.

Do not do any of the following without approval:

set :discover {:public true}
set :marketplace {:visible true}
run equivalent CLI update flags for public visibility
release or promote a public/end-user flow
publish a new public description, media, or install-facing copy that materially changes user claims

When approval is needed, show the exact metadata and release/promotion command
you plan to run. Ask: "Do you want me to make this flow accessible to all Breyta
users now?" Only proceed after the author confirms and the flow is
installable-ready.

Installable Flow Checklist

Use this checklist whenever the user asks for an installable, public, Discover,
or marketplace flow. Do not stop at activation.

Confirm explicit flow-author approval for public visibility,
release/promote, install-facing copy, media, and marketplace visibility.
Configure Discover visibility with :discover {:public true} and
breyta flows push --file ..., or
breyta flows discover update <slug> --public=true.
Push, diff, release, and promote the live version after approval.
Prove owner setup separately with activation/configure/check when required.
Prove end-user installability through the Discover install dialog or an
installation create/configure/enable path.
Bind installer-owned connections and setup inputs on the installation.
Run the installed target with
breyta flows run <slug> --installation-id <installation-id> --wait.
Inspect the installed run output from the intended end-user perspective.

Report URLs for the flow, live version, activation/setup surface, Discover or
install surface, installation, installed run, run output, and any resources the
user needs to inspect. If browser access is unavailable, write
web UI not verified and include the CLI installation proof that was run.

Public Preflight Checklist

Use public-ready architecture for every new or edited flow unless the user says
it is internal-only. Run this full checklist only when the task changes public
copy, install behavior, publish/release behavior, Discover, marketplace, or
public output.

Before turning a flow public or changing public behavior, confirm these
essentials:

public-ready architecture: no hardcoded private workspace/user/test values, secrets, private URLs, or author-only assumptions
setup contract: installer-owned connections use the right :requires shape, including :provided-by :installer and :oauth where OAuth connect-first setup is needed
cost contract: external API, LLM, search, and other paid provider steps have step-level metering or cost estimates where supported; if unsupported, record that in the risk ledger
public name and slug: clear, human-readable, and aligned with the primary user query
short :description: one or two sentences covering audience, entrypoint/interface, integrations, and outcome
meta description copy: 140-160 character search snippet for review; set it only if current docs/schema expose a supported field
markdown publish description: SEO/AEO-friendly end-user landing-page copy that explains why to install, setup requirements, what happens after install, outputs, limits, and failure/permission expectations
tags: outcome, audience/use case, integration/tool, and modality tags, not only draft or internal labels
media: useful image or video when it helps users understand the actual result; flow-resource media must be a reviewed same-workspace res://... resource intended for public cards
outputs: a readable public result, usually markdown, table/media viewer, or markdown with embedded Breyta resources
verification: draft run, public/install setup path, installation-targeted run when relevant, web UI check when available, output/resource readback, and full Breyta URLs
approval: explicit flow-author approval for visibility, release/promote, marketplace, media, and install-facing claims

Setup And Run Field Planning

Treat setup and run forms as product UI for a non-technical end user. Before
creating or editing public flow fields, classify every user-supplied value:

setup-once: company profile, audience, voice, examples, default region, default folder, or other durable context reused across runs
run-each-time: prompt, file, CSV, resource picker selection, recipient, date range, row limit, or other values that naturally change per run
connection: OAuth/API/database/blob-storage accounts that should be bound through :requires
hidden/internal: implementation ids, debug toggles, author workspace state, or values the end user should not decide

Third-party accounts are setup work, not prompt text: declare connection
requirements, hand off setup/edit URLs when needed, and never ask end users to
paste secrets in chat.

For setup-once context that needs LLM processing, use setup inputs to create a
durable artifact such as a company profile, voice profile, influencer bible, or
other reusable context, then persist and reuse that context on later runs.

Keep the setup page and run form small:

use plain labels and helper text
set defaults where safe
avoid advanced/internal fields unless they are real user decisions
use :label and :title on run-collected forms so recent runs are readable
prefer :resource fields for selecting existing artifacts, and keep manual upload available when useful

Metadata Is A Landing Page

For public/end-user flows, treat metadata and install surfaces as an end-user
landing page, not internal implementation notes.

:description is the short card/catalog summary. It should say who the flow is for, what starts it, what systems it uses, and what outcome it produces.
Tags should support discovery and clustering by outcome, audience/use case, integration/tool, and modality.
publishDescription or --publish-description-file is richer markdown for install/discover dialogs. It should explain why to install, what the user must connect or enter, what happens after install, and what output they get.
Curated Discover card media should help the user understand the actual flow or result, not decorate the listing.
Do not invent new metadata fields such as metaDescription unless product docs or schema support them.

Write the markdown publish description like a small landing page for the
intended end user:

lead with the outcome and audience
name the entrypoint/interface and connected systems in plain language
explain required setup, permissions, and inputs before the user installs
describe the output they will receive and where they will see it
include practical limits, privacy/permission expectations, and common failure cases
use headings and short sections so search engines, AI answer engines, and humans can extract the value quickly

Good public copy answers:

Who is this for?
What entrypoint or interface starts it?
What accounts, files, or inputs must the user connect?
What does it do after install?
What output does the user get?
What failure or permission cases should the user expect?

Testing Public Behavior

When public behavior matters, test through public surfaces:

use breyta flows discover list/search for catalog visibility
use breyta flows discover search "<query>" --include-own when debugging whether a flow owned by the current workspace is indexed, because normal Discover search may exclude own flows
verify the Discover install dialog; /activate alone is only owner setup proof
install or inspect installation surfaces rather than only running the private draft flow
verify activation/bindings in the user-scoped prod profile
run an installation-targeted execution when required:
- breyta flows run <slug> --installation-id <installation-id> --wait
after release/promote approval, smoke the installed target:
- breyta flows run <slug> --target live --wait
when browser/UI access is available, test the actual setup page, run form fields, upload CSV or file path, resource picker, and run output page
report full Breyta URLs for the public flow, install surface, activation, run, and run output when available

Private draft runs are useful for build iteration, but they are not sufficient
proof that public install behavior works.

End-user verification ladder:

Draft run for fast iteration.
breyta flows diff <slug> before release.
Release/promote only after explicit flow-author approval.
breyta flows show <slug> --target live.
breyta flows run <slug> --target live --wait.
Discover install dialog or installation create/configure/enable proof.
breyta flows run <slug> --installation-id <installation-id> --wait.
Web UI setup/run test when tooling and access are available.
Resource picker/upload test for resource fields, including upload CSV workflows.
Output artifact audience review.

If a browser or UI path is unavailable, do the installation-targeted CLI proof
and write web UI not verified in the risk ledger. If CLI works but UI fails,
or draft works but the setup page, run form fields, installed flow, resource
picker, or old live version fails, submit breyta feedback send with full
Breyta URLs before closing the task.

For final handoff, do not write Done for public, installable, marketplace, or
paid-flow work until the touched user-visible surfaces have been verified or
named as unverified. The minimum surface matrix is source flow, live version,
Discover listing/install surface, marketplace visibility when touched,
activation/setup when relevant, installed run when install behavior matters,
public app page, and run output.

Human Timeline Quality

Public users and operators read run timelines without source code. Keep labels
plain and outcome-based.

Add :title values for non-trivial or user-visible steps.
Use step titles that describe a human action or outcome.
Use clear manual interface labels and branch labels.
Avoid vague visible labels such as "normalize", "hydrate", "finalize", "process", or "prepare payload" unless that is truly what the user understands.

Prefer titles such as:

"Search Gmail for support emails"
"Create draft reply"
"Check whether invoice is already approved"
"Summarize run result"

Discover Card Media

For public Discover/install cards, use creator-curated media when it helps the
user understand the actual result.

Set media with breyta flows update <slug> --publish-media-type image --publish-media-source-kind https-url --publish-media-source https://....
Video media can include a poster with --publish-media-poster-kind https-url --publish-media-poster https://....
Clear media intentionally with breyta flows update <slug> --clear-publish-media.
If keeping the flow in source control, author the same value in the flow file as :publish-media.
Use alt text that explains the visible result, not implementation detail.
For --publish-media-source-kind flow-resource, use a res://... URI from
the same workspace. Treat it as public card media: use only reviewed resources
that are meant to appear on Discover/install surfaces.