Playbook: Public And Marketplace

Load when changing Discover visibility, marketplace visibility, public copy,
pricing, install behavior, or public/end-user output.

Approval Boundary

Public visibility, marketplace visibility, paid-flow settings, release, and
promotion require explicit author approval. Keep authoring, live version,
activation/setup, Discover install, marketplace, public app page, installed run,
and output page as separate proof surfaces.

The public marketing app page is always derived from the flow slug:
https://breyta.ai/apps/<flow-slug>. Include that URL in public handoff proof
alongside the workspace install and Discover surfaces.

Do not treat "make this a public app" as approval to expose the flow to all
Breyta users. Do not set :discover {:public true}, :marketplace {:visible true}, or equivalent CLI flags until the author explicitly approves and the
flow has installable-ready proof.

Default Loop

1. Confirm the requested public surface:
   • Discover listing
   • marketplace visibility
   • paid/pricing
   • public app page copy
   • install/setup/run behavior
   • for paid source-authored apps, whether the catalog belongs under
     :marketplace {:app {... :monetization {:plans [...]}}} or an existing
     legacy :marketplace {:monetization ...} listing must be preserved
2. Inspect current state:
   • breyta flows show <slug>
   • breyta discover search "<query>" --include-own --limit 5 when debugging own public indexing
   • breyta flows discover show <workspace-id>/<flow-slug> to inspect any
     public app's full listing (publish copy, pricing, connections, versions),
     including apps owned by other workspaces. breyta flows show only works
     inside workspaces you are a member of.
3. Keep installable values out of source:
   • use :requires, setup inputs, run inputs, connection slots, templates, and resources
   • avoid hardcoded workspace ids, user ids, emails, private URLs, and secrets
4. Verify release/install shape, not draft alone:
   • breyta flows show <slug> --target live
   • breyta flows run <slug> --target live --interface-id <id> --wait
   • installation commands or UI proof when install behavior changed
   • complete the install test matrix in playbooks/release-and-install.md
     once the app is installable (right after release/publish, before
     announcing it): minimal config, plus per declared surface: optional
     integrations absent and broken, explicit-false toggles, malformed
     constrained text
   • for HTTP/MCP public flows, inspect installed interfaces with
     breyta flows installations interfaces <installation-id> and run one
     installation-scoped interface smoke test
5. Use supported CLI/API operations directly once approved; ask only for true
   author decisions such as visibility, exact price, currency, paywall timing,
   free runs, and public claims.
   • Use breyta flows public publish <slug> or
     breyta flows public delist <slug> when moving a flow onto or off all
     public surfaces together.
   • Use breyta flows marketplace update or breyta flows discover update
     only when intentionally changing one lower-level flag.
6. Inspect public output from the intended audience perspective. Markdown,
   tables, media, and resource viewers should be readable without raw debug
   payloads.
7. For paid pricing work, load references/public-app-pricing.md. Prefer
   prepaid usage packs and subscriptions; avoid tiny payments and per-run
   microtransactions. Consider step-level metering or cost estimates for paid
   external API, LLM, search, and other provider calls. State when cost
   metadata is unavailable.
8. Report all relevant URLs: source flow, live version, activation/setup,
   Discover/public listing, https://breyta.ai/apps/<flow-slug>,
   marketplace/app page, run, output, and resources.

Common Pitfalls

• /activate is setup proof, not Discover install proof.
• Template search is not public catalog proof.
• Draft CLI proof is not public-ready proof.
• The marketplace publish description is stored flow metadata: author it in
  source as :publish-description and persist it with breyta flows push,
  or set it directly with breyta flows update <slug> --publish-description-file ... for metadata-only edits. Update and
  release both republish changed metadata for already-public flows; reserve
  breyta flows public publish <slug> for visibility changes or an explicit
  retry after a failed publish. Prove propagation by fetching
  https://breyta.ai/apps/<flow-slug> with a bot user agent and checking
  the updated copy appears; the CMS publisher run has no author-facing
  status surface.
• Optional-integration failures that kill installed runs, silent-zero report
  lines, and or-coalesced booleans that swallow explicit false are the
  most common post-launch defects; design against the degradation contract in
  references/public-flows.md before publish.
• Installed-app manual-run QA can be invalidated by flow concurrency. If you
  expect multiple in-flight runs from the installed app page, do not leave the
  flow on :concurrency {:type :singleton :on-new-version :supersede}. That
  policy intentionally replaces the earlier run, which looks like "only the
  last run exists". Prefer :on-new-version :coexist unless replacement is the
  product behavior you actually want to ship.
• The workspace install URL is not the marketing app URL. Use
  https://breyta.ai/apps/<flow-slug> for public app-page proof.
• Public copy should explain audience, setup requirements, run input,
  integrations, outputs, limits, and failure expectations.
• New paid apps should use app-owned plan catalogs. Keep plan ids stable, use
  at most one default/recommended plan, and do not describe seat pricing unless
  explicit seat entitlements exist.
• Paid app pricing should usually use subscriptions, subscription usage, or
  prepaid run packs. Use free or trial runs for sampling instead of tiny paid
  checkout.

References

• Paid Public Flows
• Marketplace App Pricing
• Installations
• Flow Metadata
• Output Artifacts