UW Markdown cookbook

These short recipes use the reference implementation from a source checkout. They follow current main. For published package versions, consult the version matrix and that package's command help.

Start a structured underwriting record

Create a scaffold, then validate it before adding source facts. The generator creates a UWX working record; .uw.md is reserved for readable Lite summaries.

npm run cli -- init --name "Canyon Apartments" --asset-class multifamily --output canyon.uwx.md
npm run cli -- validate canyon.uwx.md

The initial validation may contain expected incompleteness warnings. Fill fields from source documents, preserve each block's _meta provenance, and use an editor or the CLI edit command rather than rebuilding the file as text.

Inspect an existing deal

npm run cli -- summary examples/Parkview-Apts-Glendale-AZ.uwx.md
npm run cli -- validate examples/Parkview-Apts-Glendale-AZ.uwx.md --json
npm run cli -- render examples/Parkview-Apts-Glendale-AZ.uwx.md --format summary

summary is a quick screen. validate reports the structured rule codes and canonical remediation text. render produces a reviewable read-only view without changing the source file.

Evaluate a formula without giving an agent control of the math

The calc engine owns financial math. Rates are fractions: 0.0551 means 5.51%.

npm run cli -- calc examples/Parkview-Apts-Glendale-AZ.uwx.md "pmt(0.0551 / 12, 360, 1000000)"

Builtin metric definitions live in the normative dictionary. A new or changed builtin requires an accepted RFC and synchronized dictionary, pack and controls. The pack drives both the deterministic calc engine and Excel formula emission; see Calc conventions.

Export a workbook for review

npm --prefix packages/uwmd-excel run build
node packages/uwmd-excel/bin/uwmd-excel.mjs examples/Parkview-Apts-Glendale-AZ.uwx.md -o parkview.xlsx

The workbook is a live projection: input cells and operating-statement line items are carried out, while derived metrics are Excel formulas generated from the same pack. Keep the UWX/Markdown source as the canonical record.

Issue and verify a receipt

npm run cli -- receipt issue examples/Parkview-Apts-Glendale-AZ.uwx.md --issued-at 2026-08-12T00:00:00Z --output parkview.receipt.json
npm run cli -- receipt verify examples/Parkview-Apts-Glendale-AZ.uwx.md parkview.receipt.json

A verified receipt proves that the unchanged record produces the stated pack outputs. It does not prove the input facts are complete, correct, audited, or approved. See Verification receipts.

Convert Lite and UWX

npm run cli -- convert conformance/lite/fixtures/01-minimal.uw.md --to uwx --output deal.uwx.md
npm run cli -- convert conformance/receipts/issue/01-uwx-multifamily/deal.uwx.md --to lite --output deal.uw.md --projection-report lite-losses.json

The Lite-to-UWX direction compiles the supported deal summary into a complete working record. The second command projects a complete structured record into Lite. UWX-to-Lite can omit advanced paths; always review the emitted projection report before treating the Lite output as a complete representation.

Add a metric to a pack

1. For a builtin, obtain RFC acceptance and define the metric in spec/metrics/; keep its core pack declaration synchronized. Third-party module metrics follow the module contract instead.
2. Ensure every field path has a workbook named range in that class's Excel layout, or Excel export will reject it with EXCEL-EMIT-PATH.
3. Use only Excel-mappable builtins in pack formulas; coalesce and null-aware avg intentionally reject with EXCEL-EMIT-FN.
4. Add a pack test and confirm exact Excel-to-engine parity at the declaration's effective round_to (protocol §VIII.5); a native recalculation test is the evidence.

Official asset classes are full builtins. Their dictionary, pack, defaults, example and workbook layout ship together under RFC discipline.