chore: import upstream snapshot with attribution

docs/articles/concepts/compile-path.md

@@ -0,0 +1,117 @@
+## From Graph To Code
+
+Zerolang is easiest to understand against parse-first compilers. Most languages
+have a parse-first compile path: the normal compiler input is text, so every
+compile starts by parsing text into compiler data structures. Zerolang's
+package path is graph-first. It is the same kind of pipeline with fewer stages,
+and the input is the graph store instead of text:
+
+```json-render
+{
+  "type": "flow",
+  "title": "Parse-first compile path vs Zero graph-first path",
+  "nodes": [
+    { "id": "p1", "label": "source files", "x": 0, "y": 0, "tone": "text" },
+    { "id": "p2", "label": "lexer / parser", "x": 0, "y": 96, "tone": "text" },
+    { "id": "p3", "label": "AST", "x": 0, "y": 192, "tone": "text" },
+    { "id": "p4", "label": "name resolution", "x": 0, "y": 288, "tone": "text" },
+    { "id": "p5", "label": "type checking", "x": 0, "y": 384, "tone": "text" },
+    { "id": "p6", "label": "IR lowering", "x": 0, "y": 480, "tone": "text" },
+    { "id": "p7", "label": "optimization", "x": 0, "y": 576, "tone": "text" },
+    { "id": "p8", "label": "codegen", "x": 0, "y": 672, "tone": "text" },
+    { "id": "p9", "label": "artifact", "x": 0, "y": 768, "tone": "text" },
+
+    { "id": "g1", "label": "zero.graph", "x": 380, "y": 0, "tone": "graph" },
+    { "id": "g2", "label": "repository graph tables", "x": 380, "y": 96, "tone": "graph" },
+    { "id": "g3", "label": "semantic validation", "x": 380, "y": 192, "tone": "compiler" },
+    { "id": "g4", "label": "type checking", "x": 380, "y": 288, "tone": "compiler" },
+    { "id": "g5", "label": "MIR and backend facts", "x": 380, "y": 384, "tone": "graph" },
+    { "id": "g6", "label": "direct codegen", "x": 380, "y": 480, "tone": "compiler" },
+    { "id": "g7", "label": "artifact", "x": 380, "y": 576, "tone": "graph" }
+  ],
+  "edges": [
+    { "source": "p1", "target": "p2" },
+    { "source": "p2", "target": "p3" },
+    { "source": "p3", "target": "p4" },
+    { "source": "p4", "target": "p5" },
+    { "source": "p5", "target": "p6" },
+    { "source": "p6", "target": "p7" },
+    { "source": "p7", "target": "p8" },
+    { "source": "p8", "target": "p9" },
+    { "source": "g1", "target": "g2" },
+    { "source": "g2", "target": "g3" },
+    { "source": "g3", "target": "g4" },
+    { "source": "g4", "target": "g5" },
+    { "source": "g5", "target": "g6" },
+    { "source": "g6", "target": "g7" }
+  ]
+}
+```
+
+Rust, Go, Zig, C, and many other languages differ in details, but the normal
+compiler input is text. The `.0` projection can be exported and imported, but it
+is not the normal package compile input. The compiler loads the graph store
+directly.
+
+```json-render
+{
+  "messages": [
+    {
+      "role": "user",
+      "text": "why is this less work for the agent?"
+    },
+    {
+      "role": "assistant",
+      "text": "The agent can ask the compiler for graph facts, submit one checked semantic patch, and avoid a separate write-format-parse cycle. The compiler still checks and builds, but the edit itself is closer to the final compiler model."
+    },
+    {
+      "role": "tools",
+      "calls": [
+        {
+          "command": "zero query --calls write",
+          "output": "call write\n  receiver: world.out\n  arg0: #expr_653eeb6e String"
+        },
+        {
+          "command": "zero patch --op 'set node=\"#expr_653eeb6e\" field=\"value\" expect=\"old\\n\" value=\"new\\n\"'",
+          "output": "program graph patch ok"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Why The Path Matters
+
+For agents, the compile path is also the authoring path. If text is primary,
+the agent writes text and waits for the compiler to tell it whether the text
+meant what it intended.
+
+If the graph is primary, the agent can ask the compiler for node handles,
+symbol facts, calls, references, diagnostics, and patch operations before it
+edits. The edit is already expressed in compiler terms.
+
+That is why Zero keeps investing in binary graph storage and direct graph
+loading. The long-term goal is to memory-map final compiler IR and codegen from
+semantic data with as little redundant parsing and reconstruction as possible.
+
+## Performance And Size Angle
+
+The graph model is not only about agent ergonomics. It also supports Zero's
+systems goals:
+
+- fewer reparsed text inputs on normal package commands
+- deterministic graph identity and stable diff/review output
+- pay-as-used standard library helpers
+- explicit capability and allocation facts
+- small direct artifacts when the selected profile and target support them
+
+Use `zero size --json`, `zero mem --json`, and the benchmark docs to inspect
+those facts for a graph input instead of treating performance claims as prose.
+
+## Current Boundary
+
+Zero is still experimental. Some commands and targets expose readiness facts or
+structured diagnostics when a backend cannot build a graph shape yet. That is
+intentional: the docs should show what works today and what the compiler can
+explain, not imply production completeness.

docs/articles/concepts/graph-architecture.md

@@ -0,0 +1,123 @@
+## The Program Database
+
+Zerolang exists because humans increasingly ask agents to write programs.
+
+Most programming languages still make text the primary program database. That
+works for humans, but it is a poor interface for agents. An agent has to infer
+semantic structure from text, make a text edit, run tools to learn whether the
+edit was valid, format the result, and then inspect failures after the fact.
+
+In Zero, the graph is the program database. The graph stores declarations,
+types, calls, blocks, imports, capabilities, and source-map facts directly.
+Agents edit those facts with checked graph patches. Humans read `.0`
+projections when they want a source-like review view.
+
+## The Editing Loop
+
+A traditional agent loop writes text, then runs check, format, and build to find
+out what the text meant. Zero's loop queries the graph, submits one checked
+patch, and only runs the validation a task actually needs:
+
+```json-render
+{
+  "type": "flow",
+  "title": "Traditional source loop vs Zero graph loop",
+  "height": 520,
+  "nodes": [
+    { "id": "t1", "label": "agent writes text", "x": 0, "y": 0, "tone": "text" },
+    { "id": "t2", "label": "check", "x": 0, "y": 90, "tone": "compiler" },
+    { "id": "t3", "label": "format", "x": 0, "y": 180, "tone": "text" },
+    { "id": "t4", "label": "build", "x": 0, "y": 270, "tone": "compiler" },
+    { "id": "t5", "label": "inspect failures", "x": 0, "y": 360, "tone": "human" },
+    { "id": "z1", "label": "agent queries graph", "x": 360, "y": 0, "tone": "graph" },
+    { "id": "z2", "label": "agent submits checked patch", "x": 360, "y": 105, "tone": "graph" },
+    { "id": "z3", "label": "compiler rejects invalid graph edits immediately", "x": 360, "y": 210, "tone": "compiler" },
+    { "id": "z4", "label": "agent runs only task validation", "x": 360, "y": 315, "tone": "graph" },
+    { "id": "z5", "label": "human reviews projection when useful", "x": 360, "y": 420, "tone": "human" }
+  ],
+  "edges": [
+    { "source": "t1", "target": "t2" },
+    { "source": "t2", "target": "t3" },
+    { "source": "t3", "target": "t4" },
+    { "source": "t4", "target": "t5" },
+    { "source": "t5", "target": "t1", "label": "repeat" },
+    { "source": "z1", "target": "z2" },
+    { "source": "z2", "target": "z3" },
+    { "source": "z3", "target": "z4" },
+    { "source": "z4", "target": "z5" }
+  ]
+}
+```
+
+The difference is not just syntax. A graph patch can target “the literal
+argument to this write call” or “the body of this block” instead of asking an
+agent to locate and rewrite a span of text.
+
+```json-render
+{
+  "messages": [
+    {
+      "role": "user",
+      "text": "change the greeting to hello graph"
+    },
+    {
+      "role": "assistant",
+      "text": "I’ll patch the greeting and run the program so you can see the output."
+    },
+    {
+      "role": "tools",
+      "calls": [
+        {
+          "command": "zero query --fn main",
+          "output": "main\n  check world.out.write \"hello from zero\\n\"\n  graphHash graph:a7f7e6899a73f3b4"
+        },
+        {
+          "command": "zero patch --expect-graph-hash graph:a7f7e6899a73f3b4 --op 'set node=\"#expr_653eeb6e\" field=\"value\" expect=\"hello from zero\\n\" value=\"hello graph\\n\"'",
+          "output": "program graph patch ok"
+        },
+        {
+          "command": "zero run",
+          "output": "hello graph"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Invalid Edits Fail Earlier
+
+The graph store has shape rules. Required edges, ordered child groups, node
+kinds, type facts, and repository metadata are validated when patches are
+applied. If an edit would leave a sparse argument list, a missing expression, a
+stale graph hash, or an invalid repository store, the patch fails before the
+package becomes the new compiler input.
+
+That is the agent-facing contract: write checked semantic edits, not hopeful
+text diffs.
+
+## Human Review Stays Textual
+
+Humans should not have to inspect graph dumps to trust a change. `.0`
+projections exist so people can read, review, and occasionally manually edit a
+program.
+
+The important distinction is ownership:
+
+- agents normally author through `zero query` and `zero patch`
+- humans review through projections
+- humans may edit projections as an escape hatch
+- `zero import` reconstructs the graph from reviewed projection text
+- `zero verify-projection` catches drift instead of hiding it
+
+Zero is a graph-native language with human-editable text projections.
+
+## The Payoff
+
+The graph-first model is meant to reduce guessing and reduce tool calls. A
+checked patch combines edit intent, stale-state protection, shape validation,
+and formatting-normalized projection output into one compiler-mediated step.
+
+That gives agents a smaller, more precise work surface. It gives humans a
+reviewable source-like view. It gives the compiler a direct path to semantic
+program facts without reparsing text on the normal package compile path.

docs/articles/concepts/projections.md

@@ -0,0 +1,100 @@
+## Human Review Surface
+
+In Zerolang, `.0` files are human-readable projections of the graph.
+
+They exist for trust. A human can read the program, review a change, and make a
+manual edit when needed. They are also useful for diagnostics because source
+maps can point to familiar line and column spans.
+
+They are not the normal agent write surface.
+
+## Explicit Sync Model
+
+Zero uses explicit commands so graph and projection state cannot silently drift:
+
+```sh
+zero export
+zero import
+zero verify-projection
+zero status
+```
+
+Use `zero export` when a human needs the latest `.0` review text. Use
+`zero import` after a human intentionally edits projection text and wants to
+reconstruct the graph. Use `zero verify-projection` in review or CI when you
+want a no-write drift check.
+
+```json-render
+{
+  "messages": [
+    {
+      "role": "user",
+      "text": "show me the projection so i can review it"
+    },
+    {
+      "role": "assistant",
+      "text": "I’ll export the current projection and verify it is in sync."
+    },
+    {
+      "role": "tools",
+      "calls": [
+        {
+          "command": "zero export",
+          "output": "repository graph export ok\nwrote: ./src/main.0"
+        },
+        {
+          "command": "zero verify-projection",
+          "output": "repository graph verify-projection ok"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## No Silent Divergence
+
+`zero status` reports whether the projection is clean, missing, stale, conflicting, or unavailable.
+When the checked-in `.0` sources were edited after `zero.graph` was written, commands that consume the store, including `zero check`, `zero build`, `zero run`, `zero test`, `zero query`, `zero view`, and `zero diff`, refresh the store from the edited source first and report the refresh on stderr.
+When the graph is the newer side, for example right after `zero patch`, those commands keep using `zero.graph` until `zero export` syncs the projection, and they say so on stderr.
+When both sides were edited independently, they fail with an `RGP006` diagnostic that offers `zero import` and `zero export` as repairs instead of picking a side.
+Which side moved is decided by content: every store write records a hash of the source projection inside `zero.graph`, so a freshly staged, cloned, or extracted workspace classifies the same way everywhere regardless of file timestamps.
+Set `ZERO_STALE=fail` to fail with an `RGP008` diagnostic instead of refreshing automatically.
+
+That rule prevents the worst ambiguity: an agent editing text, seeing `zero check` pass, and then running a binary built from different code.
+
+## Human Escape Hatch
+
+The escape hatch is deliberate. A project should remain reconstructable from
+text projections. A human can edit `src/main.0`, reconcile it back into the
+graph, and confirm the projection still matches:
+
+```json-render
+{
+  "type": "flow",
+  "title": "Human escape hatch: edit text, reconcile to the graph",
+  "nodes": [
+    { "id": "n1", "label": "human reviews src/main.0", "x": 0, "y": 0, "tone": "human" },
+    { "id": "n2", "label": "human edits src/main.0", "x": 0, "y": 96, "tone": "human" },
+    { "id": "n3", "label": "zero import", "x": 0, "y": 192, "tone": "compiler" },
+    { "id": "n4", "label": "zero check", "x": 0, "y": 288, "tone": "compiler" },
+    { "id": "n5", "label": "zero export", "x": 0, "y": 384, "tone": "graph" },
+    { "id": "n6", "label": "zero verify-projection", "x": 0, "y": 480, "tone": "compiler" }
+  ],
+  "edges": [
+    { "source": "n1", "target": "n2" },
+    { "source": "n2", "target": "n3" },
+    { "source": "n3", "target": "n4" },
+    { "source": "n4", "target": "n5" },
+    { "source": "n5", "target": "n6" }
+  ]
+}
+```
+
+This keeps the system auditable. The graph is first-class, but humans are not
+locked out of a readable format.
+
+## Review Rule
+
+Use graph commands for authoring. Use projections for review. Import
+projections only when a human intentionally edits them.

docs/articles/concepts/semantic-vs-text.md

@@ -0,0 +1,94 @@
+## Semantic Edits
+
+In Zerolang, text is an excellent human review format. It is not an ideal agent edit format.
+
+When an agent edits text, it must keep many details in its context at once:
+syntax, indentation, imports, symbol names, surrounding control flow, stale
+file contents, and the compiler's current capabilities. A small mistake can
+produce invalid code that is only discovered after another tool call.
+
+Graph edits carry more intent:
+
+```text
+replaceFunctionBody main
+  check world.out.write "hello\n"
+end
+```
+
+That patch says which function body changes and what rows should become the new
+body. The compiler parses those rows, builds graph nodes, checks graph shape,
+updates repository metadata, and can export a stable projection for humans.
+
+```json-render
+{
+  "messages": [
+    {
+      "role": "user",
+      "text": "add a help command and then show me the source"
+    },
+    {
+      "role": "assistant",
+      "text": "I’ll add the help branch, run it, and then show the projection."
+    },
+    {
+      "role": "tools",
+      "calls": [
+        {
+          "command": "zero patch --check-only /tmp/help.patch",
+          "output": "program graph patch ok (check-only)"
+        },
+        {
+          "command": "zero patch /tmp/help.patch",
+          "output": "program graph patch ok"
+        },
+        {
+          "command": "zero run -- help",
+          "output": "usage: zero run -- <command>"
+        },
+        {
+          "command": "zero export",
+          "output": "repository graph export ok\nwrote: ./src/main.0"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Text Edit Failure Modes
+
+Common text-edit problems for agents:
+
+- editing the wrong overload or similarly named function
+- losing an import or closing brace
+- creating syntax that looks plausible but is not accepted by this compiler
+- formatting code that later changes the span the agent intended to patch
+- using stale file contents after another edit
+- changing source while the graph store remains the actual compiler input
+
+Zero does not remove all errors. It moves the primary edit operation closer to
+the compiler's semantic model so more errors are caught at patch time.
+
+## Graph Patch Guardrails
+
+Graph patches can include:
+
+- graph hash expectations
+- node hash expectations
+- field expectations
+- typed operation names
+- function body or block body replacement
+- dry-run and check-only modes
+
+Those guardrails make stale edits explicit. They also make the failure useful:
+the agent can query the graph again and patch the current node rather than
+guessing from text.
+
+## Where Projections Fit
+
+Projection text is still part of the system. It gives humans a compact review
+format and a manual edit escape hatch. It also gives diagnostics stable spans
+and makes examples readable.
+
+The rule is simple: agents write the graph by default; humans review
+projections by choice.