# The GEML Manifesto: Doc-as-a-Base

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

*English | [中文](https://github.com/geml-spec/geml/blob/main/docs/MANIFESTO_CN.md)*

---

## 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](https://github.com/geml-spec/geml/blob/main/docs/comparisons/COMPARISON.md).)

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.*