Nopdocs

NOPDOCS — the heredoc replacement

**NOP = no operation.** A NOPDOC is a document in an envelope that *nothing between the author and the disk is allowed to touch*: an explicit BEGIN line, a few optional headers, a verbatim body, a **mandatory END line**, and a **receipt** on the other side. If the envelope arrives cut, mangled or unterminated, it is **refused and nothing is written**. That is the whole idea, and it is the one property a heredoc cannot have.

-----BEGIN NOPDOC-----
Path: src/config.py
Lines: 3

DEBUG = False
NAME = "it's fine: quotes, $vars, `backticks`, {braces}, \backslashes and 1u << 20 are all inert here"
PATH = "C:\\Users\\me"
-----END NOPDOC-----

$ nop apply changes.nopdoc
{"nop":1,"seq":1,"op":"put","path":"C:/proj/src/config.py","status":"written","bytes":151,"lines":3,"sha256":"3f9a…","eol":"lf","created":false,"check":"none","declared":{"lines":"3"},"before":{"bytes":140,"sha256":"a01c…"},"ms":2.1}
{"nop":1,"summary":true,"frames":1,"applied":1,"refused":0,"status":"ok","exit":0,"journal":"C:/Users/me/.nopdocs/journal.jsonl"}

Built for every LLM, agent and coding harness — now and later — by a machine that lost hundreds of hours to heredocs and then measured exactly why ([WHY.md](WHY.md)). Public, MIT, one Python file, no dependencies.

---

Why this exists, in three measured facts

On Windows with Git for Windows' bash spawned by any native harness process (Claude Code, and anything else built on Node):

1. Every quoted bash -c argument is silently cut at 8,186 characters, whatever its content. When the cut lands inside a heredoc body, bash writes the partial file and exits 0. [measured, tests/probe_transport.py]
2. Every \\ inside a quoted region arrives as \. A Python or JavaScript string literal loses half its backslashes with no error. [measured]
3. The "odd apostrophe" error is the cut wearing a disguise. The harness turns each ' into '"'"'; when the argument is cut, bash blames the