Agent Editing Guide

Agent contract

If you are an agent, treat the .noma source as the artifact's audit log. Your job is to preserve surrounding bytes, keep block IDs stable, and make the next human review smaller.

The safe editing loop

Use noma prove file.noma --ops ops.json --inplace --out proof.html when the proof artifact and source update should be one guarded operation. The command writes the source only if the simulated post-patch document has no validation errors.

Browser proof surface

The web workbench exposes the same product contract for no-install review:

1. paste one patch op or an ops array into Agent Proof
2. click Review -> Prove
3. inspect hashes, diagnostics, source preservation, ops, and post-preview in

the Proof output tab

1. click Apply only when the proof is writable
2. copy Share Proof when a reviewer needs proof metadata without the source

Workbench table and dataset edits also travel through this path. The visual grid generates granular patch ops, runs a proof, and only writes the browser draft when post-validation has no errors.

Space maintenance

For multi-page documentation, books, papers, or agent memory packs, treat the book manifest as the project boundary:

noma ids docs/book.noma.yml
noma check docs/book.noma.yml
noma render docs/book.noma.yml --to site --out dist/docs

The generated Noma Space is reader-facing, but it also gives agents useful orientation: _assets/search-index.json lists page titles, paths, tags, status, owners, updated dates, summaries, and plain text; page sidebars expose related pages and backlinks; cross-chapter [[id]] links use the same scoped ID/alias map as validation. Edits still go through source patches against .noma files, not HTML rewrites.

Choose the smallest operation

Transaction shape

Patch files should use the transaction wrapper when an edit has more than one operation or when validation should guard the write.

{
  "prevalidate": true,
  "postvalidate": true,
  "ops": [
    {
      "op": "update_attribute",
      "id": "launch-decision",
      "key": "status",
      "value": "accepted"
    }
  ]
}

Guardrails for agents

• Do not scrape rendered HTML when --to llm can provide scoped context.
• Prefer noma prove before noma patch when the edit is user-visible,

multi-operation, or needs an audit artifact.

• Prefer replace_body over replace_block when attributes and children should survive.
• Prefer update_heading over text replacement for section titles.
• Use rename_id only when the user accepts a breaking ID change.
• Preserve aliases unless the user asks to remove them.
• Validate fragments before insertion.
• Use --strict for published/team artifacts.
• Keep raw ::html, ::svg, and ::script out of agent-generated content unless explicitly requested.

Minimal agent prompt

You are editing a Noma document. First discover IDs with `noma ids`. Choose the smallest patch operation. Prove the edit with `noma prove --ops --out proof.html`. Apply edits with `noma patch --ops` only after the proof passes. Run `noma check` after the patch. Do not rewrite the whole file unless explicitly requested.

When to ask a human

Ask before editing when:

• The requested target has no stable ID.
• Multiple aliases could refer to different sections.
• A patch would delete evidence, citations, or accepted decisions.
• The edit requires raw HTML/script escape hatches.
• Validation fails after a patch and the fix is not mechanical.

MCP and SDK status

The MCP server exposes read_doc, list_ids, validate_doc, and patch_block over stdio. The Agent SDK wraps that server and remains experimental until the protocol annexes graduate. Treat the CLI and schemas as the stable contract; treat SDK ergonomics as subject to change during v0.x.

MCP host setup

Use the published stdio server from any MCP host that accepts command-based server definitions:

{
  "mcpServers": {
    "noma": {
      "command": "npx",
      "args": ["-y", "@ferax564/noma-mcp-server"]
    }
  }
}

The server should be pointed at absolute file paths by the caller. It does not invent edits: agents still need to discover IDs, choose a small patch operation, and validate after the patch.

SDK workflow

Use the SDK when an agent integration needs a typed client and retry-aware source patches:

import { NomaTools, NomaWorkflow } from "@ferax564/noma-agent-sdk";

const tools = await NomaTools.spawn();
try {
  const ids = await tools.listIds("/repo/memo.noma");
  console.log(ids.ids);

  const workflow = new NomaWorkflow(tools);
  const result = await workflow.safePatch("/repo/memo.noma", {
    op: "replace_body",
    id: "summary",
    content: "Updated summary text.",
  });

  if (!result.ok) {
    throw new Error(`${result.code}: ${result.error}`);
  }
} finally {
  await tools.close();
}

safePatch reads the current SHA before patching and retries only on sha_mismatch. Same-file patches inside one workflow are serialized so two local agent tasks do not race each other.