Outputs And Tables Reference

Load this reference before creating or editing final outputs, public artifacts,
persisted resources, table viewers, or run evidence.

Output Defaults

• Public/end-user flow outputs should default to one readable Markdown artifact, or a deliberate table/media viewer when that is better for the user.
• The default rich output pattern is a Markdown report. Use fenced breyta-resource blocks when that report needs real Breyta tables, charts, downloads, images, video, nested Markdown, text, or JSON resources.
• Keep raw debug maps, internal ids, res:// refs, and implementation-only fields out of final public output unless the user explicitly asked for them.
• Include enough summary context that a user can understand the result without reading step internals.
• Include exact failure or skip reasons when that is the user-facing outcome.
• Do not paste EDN/JSON maps into Markdown prose. Return them as :raw viewer values, embed persisted JSON with :view :json, or put supporting values in fenced code blocks.

Artifact Audience Review

After a run returns output or artifacts, inspect the actual user-facing result
before calling the workflow done. Review it from the perspective of the flow's
intended user and the audience of the artifact, not from the perspective of the
flow author.

Use the right inspection path:

• Markdown/report: open or read the rendered output and check whether the first screen explains the result, the content answers the user's request, links/resources resolve, and there are no raw debug maps or placeholders.
• Table: read the table resource, verify it has rows and useful columns, and judge whether the table is scannable for the intended user.
• Image: open the image artifact/resource and use vision analysis to check whether the visual content is legible, correctly framed, complete, and aligned with the requested audience/use.
• Video: if browser tooling is available, capture screenshots from several moments and review them. Otherwise use the best available frame extraction path and report the limitation.
• Download/blob: inspect metadata and, when safe and useful, read or preview the file enough to confirm it is the expected artifact.

Audience review should catch empty outputs, cut-off text, broken embeds,
illegible images, video frames that never show the intended content, excessive
debug detail, wrong tone, missing context, and outputs that satisfy the data
contract but fail the end-user experience.

Output Shape Decision Table

Markdown resource embeds are authoring syntax. The end-user output should render
as one continuous document; users should not see the raw fenced blocks or
technical res:// URIs.

The floating Copy Markdown action exports resolved embeds, not Breyta-only
fences, whenever possible. Tables become Markdown tables, JSON/raw resources
become readable fenced Clojure blocks, download/video/audio resources become
links to the Breyta resource viewer, and image embeds keep an image preview
wrapped in a Breyta resource-viewer link.

For field-by-field syntax, use the product docs:
breyta docs find "output artifact reference breyta-resource table aggregate".

Full Breyta URLs

Report full Breyta URLs whenever the CLI returns them:

• flow URL
• run URL
• run output URL
• activation/setup URL
• resource URL
• public template URL
• Discover/install URL

Prefer CLI-returned URLs:

• data.flow.webUrl
• data.run.webUrl
• run.webUrl
• outputWebUrl
• data.webUrl
• meta.webUrl
• error.actions[].url

Hand-build URLs only when the CLI does not return one and all required ids are
known.

Markdown Table Or Breyta Table Resource

When the user asks for "table output", decide first which output type they
mean.

Use a markdown table when:

• the table is short
• the table is explanatory
• the table belongs inside a readable report
• copy/export/filter behavior is not important

Use a Breyta table resource when:

• there are many rows
• the user needs scan/copy/export behavior
• the result should be durable structured data
• another step or human should consume the table as a resource

When the table belongs in a larger written report, embed the persisted table in
Markdown with a breyta-resource fence instead of returning a separate table
viewer as the whole output. Use a separate :view :download fence when the user
should get a CSV/source download.

Breyta Table Resource Verification

For a Breyta table resource, verify all of these before calling the workflow
done:

• final output has :breyta.viewer/kind :table
• viewer value has :type :resource-ref
• resource content type is application/vnd.breyta.table+json
• preview.rows-written > 0
• breyta resources read <table-uri> returns rows

Do not consider breyta resources workflow list alone sufficient verification.
It proves a resource exists, not that the user-facing table resource is readable
and populated.

Table Write And Read Shapes

For :persist {:type :table ...} writes, use the table-name form in the
:table field. Table queries and reads can use table resource refs, but a
result table URI in a persist write can pass draft validation and still fail at
live runtime parameter validation.

After writing rows, read the table back with breyta resources read <table-uri>
or the table step/query path that downstream consumers will use. Confirm the
returned URI/ref is non-empty and that rows are present before storing or
reporting the table as ready.

If a flow stores a table URI/ref in KV or a registry, never overwrite a known
good value with nil or an empty value from a later upsert/write result. Keep
the previous ref or fail loudly so downstream reads do not inherit a corrupted
registry entry.

Large Artifact Hygiene

Agents should inspect large artifacts through refs and bounded previews, not by
pasting full tables or reports into chat. Use breyta resources read <uri> for
the default compact blob preview or default bounded table preview and add
--full only when the full payload is required for the current decision.
Treat --pretty as formatting only; it must not imply full payload access.

When a flow produces a long Markdown report, transcript, JSON body, or research
artifact, persist the body as a blob/resource and pass the resource ref, signed
URL, and a short summary through run results or table rows. Keep durable tables
scan-friendly: store status, counts, source refs, output refs, and short previews
instead of giant cells like report_markdown that contain the whole artifact.

For blob resources, choose the tier up front: retained/default for durable or
user-visible artifacts; :tier :ephemeral for temporary streamed HTTP blobs,
downloads, exports, generated media, and intermediate API responses. Function,
table, and KV persists use the retained/default path today.

Persist And Resource-Ref Handoff

Default to :persist when payload size is unknown or unbounded: provider
exports, paged API responses, generated media, long Markdown reports,
transcripts, JSON snapshots, files, and tables.

Persisting changes the shape passed to later steps:

• persisted blobs carry resource refs in :uri / :resource-uri
• persisted blobs also carry storage loader details under :blob-ref
• persisted tables should be treated as canonical {:type :resource-ref :uri ...} maps
• UI/API/report handoff should use the resource URI or canonical resource-ref
• downstream blob hydration should pass the whole persisted step result and use
  :load on the function step

Use this handoff shape:

(let [resp (flow/step :http :fetch-export
             {:connection :api
              :path "/export"
              :accept :json
              :persist {:type :blob
                        :tier :ephemeral
                        :content-type "application/json"}})
      rows (flow/step :function :extract-rows
             {:input {:resp resp}
              :load [:resp]
              :code '(fn [{:keys [resp]}]
                       (get-in resp [:body :items]))})
      table (flow/step :function :persist-rows
              {:input {:rows rows}
               :code '(fn [{:keys [rows]}] {:rows rows})
               :persist {:type :table
                         :table "export-rows"
                         :rows-path [:rows]
                         :write-mode :upsert
                         :key-fields [:id]}})]
  {:breyta.viewer/kind :table
   :breyta.viewer/value table})

Use (:resource-uri result) or (:uri result) when a command, table row, or
Markdown breyta-resource fence needs a URI string. Keep the full persisted
result when a downstream step can load it. Do not use [:blob-ref :path] as a
public/user-facing ref; it is a storage pointer for loaders and storage-backed
steps.

Persisted Resources

Use breyta resources ... to inspect persisted result refs like res://....

• breyta resources list lists refs by filters.
• breyta resources workflow list <workflow-id> lists refs for a run.
• breyta resources get <uri> fetches metadata.
• breyta resources read <uri> reads persisted results.
• breyta resources url <uri> gives a shareable URL.

For large outputs, pass refs through the flow rather than large bodies. Keep
inline final output small and user-facing.

Runtime Proof

Runtime proof should include:

• exact command run
• workflow/run id
• terminal status
• user-facing output summary
• artifact audience review notes
• required side-effect evidence
• full Breyta URLs
• unresolved risk or blocked verification

Do not report success based only on flows push or resources workflow list.
Behavior is proven by a representative run, by reading the outputs/resources
that matter, and by reviewing the actual artifact as the intended user would.

For notification flows, include the rendered or submitted payload in the proof:
recipient, sender, subject, relevant body copy, and any required absence checks
such as "no PR link" or "no debug map".