Noma - Source-controlled artifacts for agents

Why Noma

The problem is not prose. It is the edit loop around artifacts.

LaTeX, Markdown, and HTML each win in a narrow lane. Noma keeps the readable-source advantage, adds semantic structure, and gives agents a proofed patch loop in the browser and CLI.

When users hit this	Common frustration	Noma answer	Where to try it
LaTeX papers and reports	Small syntax mistakes can produce opaque compile failures; collaboration and tables become tool-specific.	Keep math and PDF output, but make the source block-addressable, diagnostics-first, and previewable without a compile-debug cycle.	Live preview
Markdown docs	Tables, rich layouts, data, and agent updates become ad hoc conventions across dialects.	Use Markdown-like prose for simple text, then switch to typed blocks, datasets, validation, and visual table/data editing when structure matters.	Research memo
HTML artifacts	The output is rich, but raw HTML is verbose to review, expensive to feed back to agents, and weak as canonical source.	Render HTML as the artifact while `.noma` remains the source of truth for diffs, LLM context, proofs, and source-preserving patches.	Generated artifacts
Team knowledge bases	Wiki pages are easy to publish but hard to audit in Git, export cleanly, and update safely with agents.	Publish a static Noma Space with search, backlinks, page metadata, and agent-readable indexes while source files stay reviewable.	Noma Space
Agent-maintained documents	Agents often rewrite too much, lose structure, or leave stale claims behind.	Stable IDs, scoped LLM context, diagnostics, proof links, and patch ops make the smallest safe edit the default path.	Agent guide

Agent-safe loop

One source file moves through the whole workflow.

Noma is useful when the document will be read by humans and edited by agents later. The first job is not maximal expressiveness; it is making the next edit targetable, provable, reviewable, and validated.

Step	Command or surface	What it proves	Where to start
Write named blocks	Use Markdown-style prose plus `::claim`, `::evidence`, `::decision`, `::table`, and `::agent_task`.	Humans can review the source in Git. Agents get stable semantic handles instead of guessing from paragraphs.	Start
Render the artifact	`noma render file.noma --to html --strict --out artifact.html`	The reader gets polished output while the source remains plain text and source-controlled.	Examples
Publish a space	`noma render book.noma.yml --to site --out dist/space`	Docs, books, and papers get static navigation, search, backlinks, metadata, and an agent-readable search index.	Open space
Give agents clean context	`noma render file.noma --to llm --select claim,evidence,risk --budget 12000`	Agents receive deterministic context without HTML noise or unsafe escape-hatch bodies.	Agent guide
Prove then patch by ID	`noma ids file.noma`, `noma prove file.noma --ops ops.json --out proof.html`, then `noma patch file.noma --ops ops.json --inplace`	The proof shows diagnostics, hashes, source preservation, diff, LLM context, and preview before the document changes.	Patch flow
Validate before shipping	`noma check file.noma` in the CLI or GitHub Action.	Broken references, duplicate IDs, missing evidence, stale citations, unsafe hatches, and data/plot mismatches fail fast.	Contract
Integrate the loop	Use the CLI, GitHub Action, MCP server, Agent SDK, or VS Code extension.	Human authors and agent hosts share the same source contract instead of custom rewrite scripts.	Docs map

Start

Run the source, artifact, agent loop in 10 minutes.

The first useful test is not learning every directive. It is rendering one document, listing its IDs, exporting agent context, proving a tiny patch, applying it, and validating the result.

No install path

Open the web workbench to edit .noma, preview safe HTML, inspect diagnostics, edit table/data blocks, prove agent patch ops, share proof summaries, view the AST, and copy LLM context.

Open workbench

CLI smoke test

npm install -g @ferax564/noma-cli@latest
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 prove my-spec/demo.noma --op '{"op":"replace_body","id":"first-risk","content":"Tracked by proof before patch."}' --out my-spec/proof.html
noma patch my-spec/demo.noma --op '{"op":"replace_body","id":"first-risk","content":"Tracked by proof before patch."}' --inplace
noma check my-spec/demo.noma

open my-spec/proof.html
open my-spec/demo.html

Then wire agents in

MCP: npx -y @ferax564/noma-mcp-server
SDK: npm install @ferax564/noma-agent-sdk
CI: uses: ferax564/noma@v0.13.0
Editor: ext install ferax564.noma-language

Agent contract

The safe edit is small, named, and validated.

Noma gives agents a boring contract: read scoped context, list stable targets, choose the smallest operation, prove the patch, patch by ID, and re-check. The source file remains the audit log.

Patch transaction

{
  "prevalidate": true,
  "postvalidate": true,
  "ops": [
    {
      "op": "update_attribute",
      "id": "launch-wedge",
      "key": "confidence",
      "value": 0.86
    },
    {
      "op": "replace_body",
      "id": "edit-risk",
      "content": "Agents must patch stable block IDs, not rewrite the file."
    }
  ]
}

Non-negotiable loop

Read clean context with noma render --to llm; do not scrape rendered HTML.
Discover canonical IDs and aliases with noma ids before editing.
Prefer replace_body, table cell ops, or update_attribute over whole-block replacement.
Run noma prove --ops --out proof.html before applying user-visible edits.
Run noma check after the patch and render strict HTML for review.
Use MCP or the SDK when an agent host needs the same loop 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, clean LLM context, and patch proof.	HTML Proof 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
Interactive projection	Controls update computed metrics, computed plots, computed tables, and shareable scenario state.	How live artifacts stay deterministic in static and LLM render targets.	HTML LLM JSON Source
Word review loop	Word controls, comments, change requests, computed tables, and extractable review data.	How a source-controlled artifact can round-trip through DOCX review.	HTML DOCX LLM JSON Source
Noma Space book	Book manifest, scoped chapter IDs, aliases, search, page metadata, backlinks, single-page render, site render, and LLM export.	How documentation, books, and papers can grow past one file without losing source control or agent-safe references.	Space Single page 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 the workflow first, the reference second.

The docs are organized around the agent-safe lifecycle: create a document, render it, expose context, prove a patch, apply it, validate it, and only then reach for the full format reference.

Task	Document	Use it for	Link
Run the first loop	Getting Started	Install, render, export LLM context, list IDs, prove a patch, patch, validate, and wire CI.	Open
Publish a docs space	Spec + example	Render a book manifest to a static space with search, backlinks, metadata, and an agent-readable index.	Spec Example
Give rules to an agent	Agent Editing Guide	The safe proof/patch loop, smallest-operation choices, transaction shape, MCP setup, and SDK workflow.	Open
Choose the right use case	Case Studies	Research refreshes, decision artifacts, technical docs, Word review, and agent memory workflows.	Open
Author in the browser	Workbench Guide	Live source/artifact editing, proof-before-apply, diagnostics, table/data editing, AST/LLM tabs, and export flows.	Open
Look up syntax	Spec	Block syntax, AST variants, render targets, validation rules, profiles, books, math, memory.	Open
Decide if Noma fits	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
Study the wedge	Research Memo	External Markdown/HTML pain research from X, Reddit, HN, specs, GitHub, and Stack Overflow.	Open

Compare

Noma is for durable source, not throwaway output.

The practical split is source vs artifact. Markdown is still the right call for short prose. Raw HTML is still the right call for bespoke pages. Noma is for durable artifacts that will be rendered, checked, and patched safely by agents later.

vs. Markdown

Need	Markdown	Noma
Readable plain text	Strong	Strong
Rich blocks	Ad hoc	Native
Complex tables	Fragile	Structured
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
Durable co-authoring	Weak	Strong
Agent edits	Fragile	Block ops
LLM export	Noisy	Clean

Agent-editable docs, from one readable source.

Rendered artifact