Start with the reader and content shape
- Choose report, article, briefing, or dashboard from the reading task.
- Write the conclusion and evidence sequence before styling.
- Select a supported theme and compatible accent.
- Use one approved icon library per document.
Keep data and presentation explicit
Store material values as typed facts or query results, then bind tables, metrics, and charts to those identifiers. Do not encode important numbers only inside decorative text.
Treat media as evidence-bearing assets
- Freeze used media into the package.
- Record source, creator or publisher, license, retrieval date, digest, alt text, caption, and credit.
- Use authored metadata for user- or model-generated images.
- Make the document remain intelligible when an image is unavailable.
Run the deterministic gate
ow a2ui draft check ./artifact
ow a2ui draft build ./artifact
ow a2ui digest ./artifact/document.mdwProduct boundary
Do not unzip and hand-edit the generated package. Change the draft source and rebuild it.
FAQ
Frequently asked questions
Is .mdw just Markdown with a different extension?
No. It is a deterministic typed package containing content, presentation, integrity-linked assets, and protocol metadata.
Can I put arbitrary HTML or JavaScript in an MDW document?
No. Author through supported typed nodes and renderer capabilities; arbitrary HTML and scripts are outside the Hosted contract.
Use the real workflow
Publish what your agent creates.
Give every report, document, or plan its own reader-ready page. Comments, review decisions, and formal revisions can flow back from there.