noma

Noma

Proof-before-apply docs for AI agents.

Noma is a plain-text document format for AI-maintained docs in Git. It lets teams keep reviewable .noma source, give agents scoped context and stable block IDs, generate a proof before applying patches, and render the same source as polished artifacts or searchable documentation spaces. It is:

• readable like Markdown
• structured like data
• renderable like HTML
• printable like PDF
• editable by AI agents at the block level — not via full-file rewrites

.noma source -> scoped context -> proof -> patch -> validated artifact

Live site: https://ferax564.github.io/noma/ — landing page, demo gallery, rendered HTML/PDF/LLM/JSON for every example, full docs.

Why

Markdown is excellent for prose. LaTeX is excellent for publication-grade math and typesetting. HTML is excellent as the browser artifact. The painful gap is the work agents now produce and maintain: research memos, PR reviews, decision records, technical specs, stale-source refreshes, and Word review handoffs that need tables, citations, validation, render targets, and safe follow-up edits.

Noma is that middle layer. Keep the source small and reviewable like Markdown; render the artifact as HTML/PDF/DOCX/LLM/JSON; give agents typed blocks and stable IDs so they can patch the exact claim, table, risk, task, or citation that changed.

See docs/direction.noma for the full positioning and PLAN.md §23 for the three-layer model and the central design test every feature must pass.

The wedge

Use Noma when an agent is about to update a source-controlled document and a reviewer needs proof before the source changes:

Surface	What Noma keeps stable	Why Markdown or raw HTML alone gets awkward
Source	readable .noma text with directive blocks	Markdown gets flat; HTML gets noisy to co-author and diff
Agent	IDs, validation, scoped LLM export, patch ops, proof summaries	Agents need structure instead of whole-file rewrites
Artifact	standalone HTML, PDF, DOCX, docs space, JSON	Markdown needs extra tooling for polished rich output

The first sharp use cases are agent-refreshable research, PR/architecture review artifacts, decision records, table-heavy technical specs, Word review loops, and agent memory files.

The loop

The default workflow is deliberately small:

noma check memo.noma
noma render memo.noma --to html --strict --out memo.html
noma render memo.noma --to llm --select claim,evidence,risk --budget 12000
noma ids memo.noma
noma proof memo.noma --ops ops.json --out proof.html
noma patch memo.noma --ops ops.json --inplace
noma check memo.noma

That is the product contract: humans review source and artifacts; agents inspect IDs, prove the patch, update the smallest stable surface, and validation catches broken structure before the artifact ships.

Hello, Noma

---
title: ASML Investment Thesis
---

# ASML Investment Thesis

::claim{id="asml-euv-moat" confidence=0.82}
ASML has a durable moat because it is the only supplier of EUV lithography systems at scale.
::

::evidence{for="asml-euv-moat" source="annual-report-2025"}
ASML continues to report strong demand for EUV systems from leading-edge customers.
::

::grid{columns=2}
:::card{title="Bull Case"}
EUV demand stays structurally high.
:::

:::card{title="Bear Case"}
Export restrictions and cyclicality.
:::
::

That's the whole language — directive blocks (::name{attrs} ... ::), Markdown-ish inline text, YAML frontmatter, and stable block IDs.

Quick start

Install the public CLI:

npm install -g @ferax564/noma-cli@latest
noma --version
noma init my-spec
noma check my-spec/demo.noma
noma render my-spec/demo.noma --to html --out my-spec/demo.html
noma render my-spec/demo.noma --to llm --budget 12000
noma ids my-spec/demo.noma
noma proof my-spec/demo.noma --op '{"op":"replace_body","id":"first-risk","content":"The first risk is now tracked without rewriting surrounding source."}' --out my-spec/proof.html
noma patch my-spec/demo.noma --op '{"op":"replace_body","id":"first-risk","content":"The first risk is now tracked without rewriting surrounding source."}' --inplace
noma check my-spec/demo.noma

# bring existing Markdown into the agent-safe loop incrementally
noma ingest docs/README.md --out docs/README.noma
noma check docs/README.noma --profile technical-docs

Install editor support:

ext install ferax564.noma-language

Install the agent integration packages when you want MCP or a TypeScript workflow wrapper:

npm install @ferax564/noma-mcp-server@latest
npm install @ferax564/noma-agent-sdk@latest

From a checkout:

git clone https://github.com/ferax564/noma.git
cd noma
npm install