Tools and packages
This is the integrator's reference for the UW Markdown reference stack. If you just want to create and validate a first record, start with the quickstart instead.
The tools overlap on purpose: the format is the contract, and the tools are interchangeable. Pick the one that matches what you're trying to do.
The reference stack includes the standalone standard Verifier and starter products built on the standard (RFC 0078). The standard is the format, the Protocol as verification, receipts and the metric dictionary; a lender can verify a record with none of these tools. Their behavior is described in the starter products guide.
Two file extensions appear below. .uwx.md is the complete structured record. .uw.md is the UW Lite summary. Readers and source-loading APIs accept the representations they advertise; the editor compiles Lite into UWX. See UW Lite and UWX.
What is published
The version matrix is authoritative for versions and publication state. At the time of writing:
| Package or tool | How to get it |
|---|---|
@uwmd/verify (read and verify only: the reference implementation of the standard, not a starter product) | npm install @uwmd/verify; @uwmd/core depends on it and re-exports it |
@uwmd/core (library) | npm install @uwmd/core |
@uwmd/cli (uwmd command) | npx @uwmd/cli <command> or npm install @uwmd/cli |
@uwmd/signing (block and receipt signatures) | npm install @uwmd/signing |
@uwmd/batch (collection index and fact table) | npx @uwmd/batch <dir> --out <dir> |
@uwmd/excel (.xlsx workbooks) | npm install @uwmd/excel |
@uwmd/report (PDF lender package) | npm install @uwmd/report |
@uwmd/lake (PostgreSQL adapter) | npm install @uwmd/lake |
| Official asset classes | All twelve, including hospitality and data center, are builtins; modules are for third parties |
@uwmd/mcp | Private source workspace: read-only validation, verification and code explanations over stdio; not published on npm |
| Web viewer | Hosted at uwmd.org/viewer, or download the single HTML file |
| Web editor | Hosted public preview at uwmd.org/editor |
| VS Code extension | Source only: package with vsce package |
Install matching exact workspace versions from the matrix. Source-checkout features may be newer than the published package generation.
For source-checkout calculation scenarios, see Calculation context files: select period variants and exact overrides in calc, refinement and explicit Excel export.
For the next modeling step, the lease-up cash-flow example verifies an explicitly dated partial stream using existing APIs.
The verify-cash-flows command checks stated cash-flow metrics without a custom script; see the workflow. It checks mathematical consistency, not economic completeness.
Decision tree
| If you want to... | Reach for |
|---|---|
Open a .uw.md Lite summary or .uwx.md structured deal | Web editor |
| Author a deal file by hand | VS Code extension |
| Edit numeric fields and watch DSCR/LTV recompute | Web editor |
| Script validation, scaffolding, or rendering | uwmd CLI |
| Hand the deal to a banker who lives in Excel | Excel converter |
| Index a folder of deals, or feed a data lake | @uwmd/batch |
| Write an agent's output into the deal | uwmd edit or writeAgentBlock from @uwmd/core (your host runs the agent) |
| Prove a deal's metrics follow from its inputs | uwmd receipt or the web editor |
| Check a receipt a counterparty sent you | any of the CLI, web editor, or VS Code extension |
The standard has Reader and Verifier tiers, with optional profiles. See the protocol spec §II or the tier overview in the conformance corpus.
Web viewer
tools/web-viewer/ — single-file HTML, drag-and-drop.
Use the hosted copy at uwmd.org/viewer, or open index.html in any browser. Drop a .uwx.md record on the page; it is read locally and never uploaded. See it rendered. (It does not read .uw.md Lite summaries — use the web editor for those.)
Best for: sharing a deal with someone who doesn't have the toolchain. Reading a deal you didn't write. Demoing the format.
Skip it for: editing (no edit UI), calc evaluation (no calc engine), sections beyond the most-displayed eight (the inlined registry is intentionally minimal).
Nothing to install.
VS Code extension
tools/vscode-uwmd/ — authoring extension.
Syntax highlighting, section folding, document outline, on-save validation diagnostics tied to BUILTIN_REMEDIATIONS, and a Verify Receipt for This Deal command that checks the .receipt.json sidecar beside the open file. It verifies but does not issue — a receipt issued mid-authoring is stale on the next keystroke. See Verification receipts.
It handles both representations: .uw.md Lite summaries and .uwx.md structured records, choosing the parser from the file's content rather than its extension.
Best for: writing deal files by hand. Reviewing a teammate's PR that touches a deal file. Living in the spec while authoring.
Skip it for: numeric editing with live recalculation (the validator flags issues; it doesn't recompute). Use the web editor for that workflow.
Not yet on the marketplace; install via vsce package + code --install-extension.
Web editor
tools/web-editor/ — calc-aware browser editor.
It opens readable .uw.md Lite summaries and complete .uwx.md structured records. Lite imports compile into UWX before editing; exporting back to Lite always shows any omitted advanced fields. See UW Lite and UWX.
Single-page app. Embeds the @uwmd/core parser, validator, edit dispatcher, and calc engine in the browser. Every numeric edit triggers dependent calculations. Validation and explicit verification still report missing inputs or inconsistent stated restatements.
The Receipt tab issues and verifies verification receipts client-side — nothing is uploaded.
Best for: working on a deal where you care about derived values (NOI, DSCR, LTV, IRR, valuation). Demoing the calc engine to someone unfamiliar with the format.
Skip it for: bulk authoring (the VS Code extension is faster for keyboard-heavy work). Server-side workflows (use the CLI).
Static deploy, no backend needed. A public preview is hosted at uwmd.org/editor.
uwmd CLI
packages/uwmd-cli — programmatic entry point.
npx @uwmd/cli init --output my-deal.uwx.md # scaffold a full record
npx @uwmd/cli validate my-deal.uwx.md # check structure, rules, stage readiness
npx @uwmd/cli verify my-deal.uwx.md # validation, integrity and provenance (exit 1 on failure)
npx @uwmd/cli summary my-deal.uwx.md # print quick metrics
npx @uwmd/cli parse my-deal.uwx.md # to JSON
npx @uwmd/cli report my-deal.uwx.md # lender package / credit memo HTML
npx @uwmd/cli convert my-deal.uwx.md --to uw-json # or uw-xml, uw-csv-bundle, lite
npx @uwmd/cli receipt issue my-deal.uwx.md # issue a verification receipt
npx @uwmd/cli receipt verify my-deal.uwx.md my-deal.receipt.jsonRun npx @uwmd/cli with no arguments for the complete command list, including diff, edit, calc, scope, refine, verify-cash-flows, package and portfolio. An unknown command exits 1 before it reads any file. The CLI reference describes the core commands.
receipt verify exits 0 for verified, 1 for failed, and 3 for unverifiable — "cannot decide" is a distinct outcome, not a pass or a rejection. See Verification receipts.
Best for: CI gates. Pre-commit hooks. Batch processing. Anything where you need a script, not a UI.
Skip it for: interactive editing.
Thin wrapper over @uwmd/core. Published on npm as @uwmd/cli, so npx @uwmd/cli <cmd> works with no clone. Once the package is installed locally the shorter npx uwmd <cmd> also works. (A bare npx uwmd with nothing installed does not, because no npm package is named uwmd.) From a clone, npm run cli -- <cmd> runs it from source.
Excel converter
packages/uwmd-excel — .uwx.md → .xlsx.
On npm (npx @uwmd/excel deal.uwx.md -o deal.xlsx). From a clone: npm run build, then node packages/uwmd-excel/bin/uwmd-excel.mjs deal.uwx.md -o deal.xlsx.
Emits a live underwriting workbook. Derived metrics ship as Excel formulas, not pre-computed values, so the workbook stays in sync with the calc engine by construction. The asset class's calc pack drives both paths, and both quantize at the same declared precision. For the metrics the workbook covers, native recalculation tests require the workbook to match the engine's quantized value exactly (protocol §VIII.5).
Best for: handing a deal to someone who lives in Excel. Producing deliverables for credit committee. Bridging legacy review processes.
Skip it for: storing your data in. The .uwx.md record remains the source of truth. Bounded uwmd-excel --import review.xlsx prints editable section payloads for review and application; it does not overwrite the deal.
Supports all twelve builtin asset classes. Mixed-use gets its own workbook shape — one footing operating statement per component plus a consolidation block that sums to the property NOI. A deal that states a capital_stack section gains a Capital Stack sheet: one row per tranche with live debt-service formulas, and a sizing block that recomputes every stated figure beside its stated value at the same quantum the core verifier compares at.
Batch indexer
packages/uwmd-batch — a folder of deals → one index.
npx @uwmd/batch deals --out batch-output # collection index (JSON + CSV)
npx @uwmd/batch deals --out batch-output --facts # plus the corpus fact tableWalks a directory of .uwx.md records, validates each, records its semantic digest, and emits uwmd-collection.json plus a spreadsheet-safe CSV. With --facts it also writes the corpus fact table: one identity-pinned row per deal per metric, ready for DuckDB or any warehouse. Invalid deals stay visible in the index rather than disappearing. See UW Markdown → data lake.
Best for: screening a pipeline of deals. Feeding a data lake without writing a loader. Answering "median exit cap across these fifty deals" with a SQL query instead of a spreadsheet.
Skip it for: editing (it never writes a deal file). Semantic find-similar retrieval (deferred; see RFC 0013).
Read-only by construction. Published on npm as @uwmd/batch.
Agent writers and context
The reference toolkit hosts no agents: it runs no model, ships no provider adapter or tool schema, and the CLI has no uwmd run. UW Markdown needs no agent to create, read, validate, edit, calculate, convert, or exchange a deal file.
A host that runs its own agents (StackUW, or any other producer) uses what @uwmd/core keeps: the context profiles (buildContext) to prepare what an agent reads, and the generic writers (writeAgentBlock, writeErrorEntry) or the edit API (applyEdit, uwmd edit --agent-id/--agent-version) to write the result with its provenance. Agents write extracted data and narrative only; they never supply financial math. The starter agent writers guide describes the context and writer conventions.
Where each tool lives
| Tool | Path | Role (Protocol conformance tier, or starter product) |
|---|---|---|
| Web viewer | tools/web-viewer/ | Reader |
| VS Code extension | tools/vscode-uwmd/ | Reader |
| Web editor | tools/web-editor/ | Starter editor; recomputes with the reference engine |
uwmd CLI | packages/uwmd-cli/ | Verifier plus starter editing; inspect uwmd manifest and each profile's binding scope. Document-fact operations are library-only. |
| Excel converter | packages/uwmd-excel/ | Starter workbook export and bounded input import |
| Batch indexer | packages/uwmd-batch/ | Reader (read-only index) |
| Context profiles and writers | packages/uwmd-core/src/context-profiles.ts, runner.ts | Starter context builder and generic writers (no agent execution) |