The GEML Manifesto: Doc-as-a-Base

August 17, 2026 · View on GitHub

Doc-as-a-Base A design manifesto for the document protocol of the human–AI co-writing era.

English | 中文

I. Origin

When Roy Fielding proposed REST, he invented no new network hardware. He gave the web's scattered resources uniform names (URIs) and one standard set of verbs (GET / POST / PUT / DELETE) — and laid the foundation of collaboration on the modern web.

Today, where people and AI agents work together, a document is scattered the same way: countless paragraphs, rules, parameters, and conclusions. With no uniform names and no standard operations, people and agents are left with two blunt moves — rewriting the whole text, and copy-paste.

Doc-as-a-Base extends REST's idea into the document: a document no longer needs just a format — it needs a set of verbs. Give every logical block a unique name (#id), and a standard set of verbs (get / set / add / delete).

II. Definition

In the traditional view, a document is static typeset text for people to read, or an offline artifact a system prints after the fact.

Now that AI agents take a deep hand in building systems and in knowledge work, GEML proposes: the document should be the source of truth that systems run on and collaborate through (Doc-as-a-Base).

  • The document is the object of operation: not an undifferentiated stream for whole-page printing, but readable-writable structured text made of discrete, strongly typed, addressable blocks.
  • The document is stateful: it is itself a context carrier with strict data structure — history, session information, and state should not depend on fragile external scratch storage and scattered prompts to be remembered.
  • The document is the final consensus: human or agent, every read takes the document as the single baseline, and every output lands back in the document as an atomic patch.

Doc-as-a-Base does not wrap the document into a sprawling system. It settles the document's place in human–machine collaboration: the Single Source of Truth.

Base, as in base of truth:

Doc-as-a-Base: a document that is still plain text, but comes with verbs — every block has a name and can be fetched alone; references are checked at build time, and a bad write is stopped before it lands; an embed is a projection, not a copy; a rollback reverts one block, not the whole page. It is the base of every deliverable: the intermediate you operate on precisely, the source that snapshots project from, and the bridge to the final artifact.

III. Rationale: Why Doc-as-a-Base?

1. Ending the fragmentation and drift of context

  • Today: in agent systems, context is torn across vector databases, runtime memory, chat history, and stray Markdown fragments. After a few rounds, state falls out of sync, copies fly everywhere, and hallucination and distortion follow.
  • Why: when the document is the single baseline of truth, every agent operation aligns to a document node. Only a single source can eliminate copy redundancy and version drift at the level of mechanism.

2. Ending the token bloat and parsing distortion of whole-text rewriting

  • Today: unstructured documents have no precise boundaries, so an agent changing one parameter must read in and regenerate the entire text — the system suffers under token bloat.
  • Why: a document that serves as the Base must offer block-level determinism. An agent queries the target block by id and submits a local patch, completing a precise update at very low token cost and freeing the precious context window.

3. Homomorphic interaction between human and machine minds

  • Today: formats like JSON suit machines but block natural human reading and editing; Markdown types nicely but has no rigorous boundaries for machine operation.
  • Why: Doc-as-a-Base unifies the semantic layer of both. People see clear, plain text; agents read and write strongly typed, verifiable block nodes. The two collaborate losslessly on the same Base.

IV. Trade-offs & Laws

One premise first, and it does not count among the four: a format people cannot read has no place in any of this — plain-text readability is the ground everything else is built on.

In the new paradigm, we hold:

  • Precise local edits over whole-document reads and writes
  • Explicit declaration and validation over implicit guessing
  • One dynamically referenced source over copy and paste
  • Minimal syntax rules over an elaborate type system

All four or none: without addressing there are no safe writes; without projection there is only copying; without validation nothing stops a bad write; without rollback there is no recovery.

The old paradigm's tools are not without value — some of them we still use every day — but to co-write with the machine reader, we value the left side more.

These four preferences are not a scorecard for existing formats. Each format was born for one concrete problem, and most solve theirs well. They were simply never asked to solve this one: machines rewriting documents, block by block, again and again. In 2004, the year Markdown was born, nobody yet needed a document a program could rewrite atomically.

A claim must be checkable, or it is a slogan. The four claims map to four laws, each with a decidable criterion; a format for the second reader must satisfy all four at once:

  1. The Law of Addressing: every structural block has a stable, machine-recognizable key, and can be read or replaced on its own, free of context. A document is made of discrete typed blocks; agents and people alike locate by #id and patch in place, atomically. get(id) returns that block alone; set(id) replaces that block alone — the rest is not merely unchanged, it is never even loaded. What is never loaded cannot be broken: isolation, not discipline.
  2. The Law of Projection: a reference is a dynamic lookup on the view side, never a static copy. Copies drift from the day they are made; projection abolishes the labor of keeping them in sync. An embed evaluates — it does not copy, and it does not merely point (that is what links are for). One definition at the source ends copy fragmentation for good.
  3. The Law of Validation: cross-block references are checked at build time; a bad write is stopped before it lands. The write itself is defended: one more gate on the write path, with no waiting for human review to intervene.
  4. The Law of Rollback: when something goes wrong, it must be possible to revert only the block that went wrong. With the companion .gemlhistory, a bad change is reverted atomically for a single block, touching nothing else. An agent's long-term memory is, by nature, the history of its short-term memory. Git — built on files and commits — is too heavy an operation here and structurally cannot offer block granularity. That is not a flaw in Git; it lives at a different layer.

Addressing, projection, validation, rollback — each is a solved problem somewhere: databases have primary keys, XML has XInclude, schemas validate, Git keeps history. What is uncommon is not any one of them, but holding all four inside one human-readable plain text. (For the format-by-format breakdown, see the capability matrix.)

One more thing follows the four — not a fifth law, but what the four hand you once they hold: context is a scarce resource. Fetching one block instead of the whole document looks like an efficiency detail on paper; inside an agent's multi-turn loop it decides where the model's attention lands and how much budget the round has left. What addressing saves is not bandwidth — it is the room the model has to think.

V. Tenets

To make Doc-as-a-Base infrastructure that actually lands, GEML commits to these engineering tenets:

  1. Typed Block as Primitive A document is built from structured typed blocks; every block carries a globally unique, addressable id, giving agents precise read and write.

  2. In-Place Mutation Rewriting the whole text for a local change is forbidden. Every change to the Base must support in-place patching by block id, with idempotent updates.

  3. Syntax Austerity Not one extra token for typesetting or wrapping; syntax carries structure and nothing else, and the context it saves goes to content.

  4. Validation-First Ingestion To write is to be checked. A structure-breaking write or an illegal reference is stopped before it enters the Base, keeping the source of truth clean.

  5. Block-level History (.gemlhistory) The Base's evolution must be traceable and attributable. With the companion history file, any single block can be rolled back on its own, keeping human–machine collaboration safe.

VI. Boundaries

GEML declares its own boundaries — that is where this specification's credibility lives:

  • It is not a database: queries are O(N) traversals of a character stream, with no index; concurrent writes get at most a whole-file lock; there are no cross-file transactions. GEML borrows the database's operational semantics — addressing, reads and writes, validation, rollback — not its runtime properties.
  • It does not replace vector stores or an agent's runtime memory: semantic similarity search belongs to the vector database, and conversational context to short-term memory. GEML's job is exactly one thing — the persistent, auditable, precisely readable and writable base of documentary truth.
  • It does not promise zero syntax overhead: === type {#id ...} costs tokens by itself. What GEML goes after is the compounding token waste of rewriting whole documents over and over — eliminated by precise local patches, not by an imaginary zero.
  • Validation cannot stop bad writing: it stops structural damage and broken references. If an agent writes something stupid, it will not say a word.

VII. Conclusion

Doc-as-a-Base is not out to build a heavy system. It brings order to chaotic documents with a minimal set of conventions.

Give every passage a name, give every change a boundary — and let the document become the reliable, deterministic source of truth between people and AI agents.

This manifesto has no signature page. Writing a file in GEML is the signature.