OWX チュートリアル：ドキュメントから公開まで

基本の流れ

1. Agent が 1 つの .owx ソースパッケージを書きます。
2. ow a2ui check が閉じた作成契約に対してソースを検証します。
3. ow a2ui compile が型付き Render Document JSON を生成します。
4. ow publish が検証済みの成果物を OWL Compose Hosted に送ります。

OWX が唯一の作成元です。コンパイル済み JSON は出力であり、別の作成言語ではありません。未対応の XML、任意の HTML、JavaScript、素の Markdown、手編集したコンパイル済みファイルは契約の範囲外です。

1. ドキュメントの外枠から始める

すべての作品には 1 つの ow-document ルートがあります。正確なプロトコルバージョンとメタデータを宣言し、読者向けの内容を section と型付きノードに入れます。

<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>

ルートの title はメタデータです。表示する見出しは明示的な ow-text 子ノードにし、同じタイトルを自由文で重ねないでください。

2. データ、クエリ、ファクトを加える

根拠を型付きで再現可能に保ちます。データセットを読み込み、クエリで変換し、表示ノードが使う正確な値を 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>

Query は変換を記述し、Fact は表示ノードが消費する値に名前を付けます。コンパイル済み JSON を手で編集して数値を変えないでください。

3. 対応コンポーネントを配置する

型付きのレイアウトと表示ノードで読者ビューを組み立てます。メトリック、チャート、テーブルは検証済みのクエリまたはファクトに結び、本文で同じ主張を繰り返しません。

<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>

読者の問いに合わせてコンポーネントを選びます。チャート、テーブル、地図、関係図は、データバインディングと視覚的な役割が明示されている場合にだけ有効です。

4. 検証、コンパイル、公開

作成元はソースパッケージです。チェックを順番に実行し、コンパイル結果を確認してから、検証済みの Render Document JSON だけを公開します。

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` は構文、型、バインディング、catalog の所属、リソース境界を検査します。`compile` は成果物を作り、`digest` は固有性を記録し、`publish` は Hosted に送ります。

よく使うノード早見表

Agent が最もよく使うノードです。署名には通常ノードを特定する属性を示しています。すべての任意フィールドや子関係が必要な場合は、生成された catalog を確認してください。

安全な結果を保つルール

• 作成 catalog は閉じた集合です。未登録の ow-* タグや属性を代替コンポーネントとして使えません。
• .owx を 1 つの作成元として保ちます。コンパイル済み JSON は生成物であり、第二の作成言語ではありません。
• 外部の事実は型付きデータ、クエリ、ファクトで結び、空白を埋めるための値を作らないでください。
• パッケージ内メディアと対応クラスだけを使います。任意の HTML、JavaScript、リモート資産、パス越境は拒否されます。

人に見せるもの

作者向けの流れでは、目的、素材、ソースの境界、検証結果、実際のプレビュー、承認待ちの操作を示します。生の OWX は監査面であり、通常の読者体験ではありません。出所の確認やデバッグが必要なときだけ、所有者がソースパッケージと正確な digest を確認します。