v0.11.1 public release · MIT

Noma is a document format for agent-safe edits.

Write plain-text .noma files. Noma parses them into a typed document tree, validates the structure, renders useful outputs, and lets agents patch named blocks without rewriting the whole file.

Plain English version

Noma is Markdown-like source with explicit blocks: claims, evidence, risks, decisions, datasets, plots, cards, sections, and agent tasks. Every important block can have a stable ID, so tools and agents can refer to it exactly.

Install and render a file Open examples Read getting started

One source file .noma

# Roadmap Decision

::claim{id="wedge" confidence=0.74}
Research workflows are the best first wedge.
::

::evidence{for="wedge" source="interviews"}
Nine analyst teams asked for stale-source checks.
::

::risk{id="edit-risk" owner="andrea"}
Agents may rewrite too much unless edits target IDs.
::

::grid{columns=2}
:::card{title="Human artifact"}
Render to HTML, PDF, or a docs site.
:::
:::card{title="Agent surface"}
List IDs, validate, and patch blocks.
:::
::

Rendered document

The same source becomes a readable artifact and a structured editing surface.

claim · confidence 0.74 Research workflows are the best first wedge.

evidence · interviews Nine analyst teams asked for stale-source checks.

Human artifactHTML, PDF, or docs site.

Agent surfaceIDs, validation, and patches.

01Parse

.noma source becomes a typed AST.

02Validate

IDs, refs, stale citations, plots, profiles.

03Render

HTML, site, PDF, JSON, LLM context.

04Patch

Replace a block, body, heading, or attr.

05Integrate

CLI, GitHub Action, MCP server, SDK, VS Code.

What Noma does

A small format with a full document toolchain.

The goal is not to replace every editor. It is to make source documents structured enough for validation and agent edits while staying readable in Git, terminal output, pull requests, and plain text.

Capability	What it means	Why it matters	Where to start
Readable source	Markdown-style text plus explicit blocks such as `::claim`, `::evidence`, `::plot`, and `::agent_task`.	People can review the source directly. Agents get semantic handles instead of guessing from prose.	Spec
Validation	`noma check` catches broken references, duplicate IDs, missing evidence, stale citations, unsafe escape hatches, and plot/data mismatch.	Documents can fail CI before a bad artifact or stale memo ships.	Validate
Rendering	One source renders to standalone HTML, multi-page sites, PDF demos, JSON AST, LLM context, and roundtrip-safe `.noma`.	The same document can serve readers, automation, and agents without duplicating content.	Examples
Block patches	`noma patch` applies operations like `replace_body`, `update_heading`, `update_attribute`, and `rename_id`.	Agents can make surgical edits while unrelated bytes stay unchanged.	Agent guide
Agent integrations	The MCP server exposes read, ID listing, validation, and patching. The TypeScript SDK wraps that with safe patch workflows.	Agent tools can share one stable editing protocol instead of writing custom file rewrites.	MCP / SDK

Try it

Install the CLI and render a document.

This path is the simplest proof: install the public npm package, create a starter file, check it, render it, and open the generated HTML.

Fresh project smoke test

npm install -g @ferax564/noma-cli
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

open my-spec/demo.html

Optional tools

VS Code: ext install ferax564.noma-language
GitHub Action: uses: ferax564/noma@v0.11.1
MCP server: npx -y @ferax564/noma-mcp-server
Agent SDK: npm install @ferax564/noma-agent-sdk

Agent editing

Agents patch IDs, not line numbers.

The protocol is deliberately boring: discover block IDs, choose the smallest patch operation, check a SHA if needed, apply the patch, then validate the result. That is the whole safety model.

Patch operation example

{
  "ops": [
    {
      "op": "update_attribute",
      "id": "wedge",
      "key": "confidence",
      "value": 0.82
    },
    {
      "op": "replace_body",
      "id": "edit-risk",
      "content": "Limit agent edits to ID-targeted patches."
    }
  ],
  "prevalidate": true,
  "postvalidate": true
}

Safe loop

Read clean context with noma render file.noma --to llm.
Discover canonical IDs and aliases with noma ids file.noma.
Patch the smallest block surface with noma patch --ops.
Run noma check and render strict HTML for review.
Use MCP or the SDK when an agent host needs the same workflow over stdio.

Examples

Open the output, then inspect the source.

These are not screenshots. They are generated artifacts built from checked-in .noma sources during the site build.

Example	What it demonstrates	What to inspect	Links
Agent planning artifact	Decision matrix, claims, evidence, risks, timeline, agent tasks, and copy-as-prompt controls.	How a planning memo becomes a structured artifact and clean LLM context.	HTML PDF LLM JSON Source
Technical documentation	CLI reference, architecture diagram, warnings, code examples, tabs, and cross-links.	How docs stay plain text while rendering as a polished reference page.	HTML PDF LLM JSON Source
Investment thesis	Claims, evidence, counterevidence, risks, datasets, plots, and review tasks.	How research documents can be validated, rendered, and refreshed over time.	HTML Dark PDF LLM Source
Multi-file book	Book manifest, scoped chapter IDs, aliases, single-page render, site render, and LLM export.	How a project can grow past one file without losing references.	Single page Site LLM
Stale memo trace	An agent refreshes citations, updates confidence, adds evidence, and preserves unrelated bytes.	The before/after source and byte-preservation stats in the trace.	Trace Source
Agent memory trace	A memory-profile file validates durable facts and renders stale-filtered LLM recall.	How Noma can store structured agent memory without dumping stale context forever.	Trace Full recall Recent recall

Documentation

Read by task, not by file name.

Start with the workflow docs. Use the spec only when you need exact block syntax, validation rules, or compatibility boundaries.

Task	Document	Use it for	Link
Start using Noma	Getting Started	Install, render, validate, patch, GitHub Actions, VS Code, MCP, and SDK setup.	Open
Understand the format	Spec	Block syntax, AST variants, render targets, validation rules, profiles, books, math, memory.	Open
Edit with agents	Agent Editing Guide	ID discovery, smallest patch operations, transactions, MCP host setup, and SDK workflow.	Open
Pick a use case	Case Studies	Research refreshes, decision artifacts, technical docs, and agent memory workflows.	Open
Compare alternatives	Comparison Guide	When to use Noma instead of Markdown, MDX, raw HTML, or collaborative docs.	Open
Copy a starting point	Starter Templates	Research memo, decision record, technical spec, and agent refresh pack templates.	Open

Compare

Noma sits between Markdown and HTML.

Markdown is easy to write but structurally weak. HTML renders well but is noisy source. Noma keeps the source readable and moves rendering, validation, and agent edits into tools.

vs. Markdown

Need	Markdown	Noma
Readable plain text	Strong	Strong
Rich blocks	Ad hoc	Native
Validation	Weak	Built in
Agent edits	Fragile	ID-based
LLM context	Basic	Structured

vs. raw HTML

Need	HTML	Noma
Browser output	Strong	Strong
Readable source	Weak	Strong
Clean diffs	Weak	Strong
Agent edits	Fragile	Block ops
LLM export	Noisy	Clean

Design test

The project stays constrained.

Every feature has to justify itself against the source, artifact, and agent surfaces.

Can a human understand this in raw text?
Can an agent edit this safely without destroying the document?
Can it render into an artifact people actually want to read?