Basic workflow

The Agent writes one .owx source package.
ow a2ui check validates the closed-world authoring contract.
ow a2ui compile emits the typed Render Document JSON artifact.
ow publish sends the validated artifact to OWL Compose Hosted.

OWX is the source of truth. The compiled JSON is an output, not a second authoring language. Unsupported XML, arbitrary HTML, JavaScript, raw Markdown, and hand-edited compiled files are outside the contract.

Tutorial

Create an OWX document step by step.

Start with a minimal document, add data, queries, facts, and display components, then run the commands to check, compile, and publish it. Use the node table and machine contract at the end when you need an exact reference.

1. Start with the document shell

Every work has one ow-document root. Give it the exact protocol version and metadata, then put reader-facing content inside sections and typed nodes.

<ow-document owx-version="1" title="Decision brief" canvas="briefing">
  <section id="overview">
    <ow-text id="summary" title="Decision brief" title-level="1" body="A concise conclusion." />
  </section>
</ow-document>

The root title is metadata. A visible masthead is an explicit ow-text child, so do not repeat the same title as loose prose.

2. Add data, queries, and facts

Keep evidence typed and reproducible. Load a dataset, transform it with a query, and expose the exact value a component should display through a fact.

<ow-document owx-version="1" title="Regional revenue">
  <ow-data id="sales" src="./sales.csv" schema="./sales.toml" />
  <ow-query id="sales-by-region" from="dataset:sales">
    <ow-group by="region" />
    <ow-aggregate name="revenue" operation="sum" field="revenue" />
  </ow-query>
  <ow-fact id="total-revenue" query="query:sales-by-region" field="revenue" />
</ow-document>

Queries describe transformations; facts name the values that presentation nodes consume. Do not hand-edit the compiled JSON to change a number.

3. Place supported components

Compose the reader view with typed layout and presentation nodes. Bind metrics, charts, and tables to the same verified query or fact instead of duplicating claims in prose.

<section id="summary">
  <ow-grid id="cards">
    <ow-metric id="revenue" fact="fact:total-revenue" label="Revenue" />
    <ow-chart id="revenue-chart" data="query:sales-by-region" type="bar" title="Revenue by region" summary="Compare revenue by region." />
    <ow-table id="regional-table" data="query:sales-by-region" title="By region" />
  </ow-grid>
</section>

Choose the component for the reader's question. A chart, table, map, or graph is useful only when its data binding and visual role are explicit.

4. Validate, compile, and publish

The source package is the editable source. Run the checks in order, inspect the compiled result, and publish only the validated Render Document JSON artifact.

ow a2ui check ./artifact/document.owx
ow a2ui fmt ./artifact/document.owx
ow a2ui compile ./artifact/document.owx --output ./artifact/document.json
ow a2ui digest ./artifact/document.json
ow publish ./artifact/document.json --no-open

`check` catches syntax, types, bindings, catalog membership, and resource boundaries. `compile` creates the artifact; `digest` records its exact identity; `publish` sends that artifact to Hosted.

Common nodes at a glance

These are the nodes an Agent reaches for most often. Each signature shows the attributes that normally identify the node; use the generated catalog when you need every optional field or child relationship.

Document structure

Start with the root and give each visible region a real parent.

Tag	Signature	Use it for
`ow-document`	`<ow-document owx-version title>`	The single authoring root and protocol boundary.
`section`	`<section id>`	A semantic page region with a stable id.
`ow-text`	`<ow-text id title title-level>`	Visible heading, eyebrow, body, or fact references.
`ow-grid`	`<ow-grid id class>`	A responsive layout container for typed children.

Data and evidence

Make the path from source material to displayed value inspectable.

Tag	Signature	Use it for
`ow-data`	`<ow-data id src schema>`	A typed dataset loaded from a package-local source.
`ow-query`	`<ow-query id from>`	A repeatable filter, derive, group, or aggregate pipeline.
`ow-fact`	`<ow-fact id query field>`	A named value resolved from a query and field.
`ow-sources`	`<ow-sources src>`	The source ledger attached to the work.

Presentation

Use a typed visual when it answers a concrete reader question.

Tag	Signature	Use it for
`ow-metric`	`<ow-metric id fact label>`	A prominent value bound to one fact.
`ow-chart`	`<ow-chart id data type title summary>`	A chart bound to a query with an explicit type.
`ow-table`	`<ow-table id data>`	A tabular view of a verified dataset or query.
`ow-map`	`<ow-map id data place country level join value title summary>`	A geographic view with place and value fields.

Relationships and interaction

Declare topology and bounded state instead of drawing arbitrary HTML.

Tag	Signature	Use it for
`ow-graph`	`<ow-graph id layout direction>`	A topology-aware graph container.
`ow-graph-node`	`<ow-graph-node id label>`	A labeled node inside an ow-graph.
`ow-connector`	`<ow-connector from to>`	A typed relation between known endpoints.
`ow-view-switcher`	`<ow-view-switcher id label>`	A bounded set of named views.

Supporting content

Use package-local media and explicit supporting blocks.

Tag	Signature	Use it for
`ow-media`	`<ow-media id file alt>`	An embedded package-local image with meaningful alt text.
`ow-code`	`<ow-code id language value>`	A code block with an explicit language.
`ow-list`	`<ow-list id>`	An ordered or unordered list of typed items.
`ow-callout`	`<ow-callout id title body>`	A labeled note or decision callout.

Rules that keep the result safe

The author catalog is closed-world: an unregistered ow-* tag or attribute is not a fallback component.
Keep one .owx source of truth. Treat compiled JSON as a generated artifact, never as a second authoring language.
Bind external facts through typed data, queries, and facts; do not invent values to fill visual space.
Use package-local media and supported classes only. Arbitrary HTML, JavaScript, remote assets, and path traversal fail closed.

Supported OWX workflow

Machine contract and audit guide

The tutorial above is the normal entry. The links below point to the supported workflow, the node map on this page, and the maintained CLI and authoring guides when an Agent or reviewer needs to verify a name, attribute, relationship, or version.

Supported OWX workflowThe authoring, validation, compilation, and publish path Node map on this pageCommon nodes, signatures, and purposes CLI command referenceThe commands used to check, compile, and publish OWX authoring guideMaintained guidance for Agent-authored work

What a human should see

The author-facing path should show the goal, materials, source boundaries, validation result, real preview, and the action awaiting approval. Raw OWX is an audit surface, not the default reader experience. The owner can inspect the source bundle and exact digest when provenance or debugging requires it.

New to OWL Compose?

Start with your Agent.

Learn the product workflow first. Return here only when the Agent or an auditor needs the underlying contract.

Understand OWX first