chore: import upstream snapshot with attribution

docs/articles/learn-zero.md

@@ -0,0 +1,192 @@
+## The Human Model
+
+Zerolang has two views of the same program:
+
+- The graph is the program database. Agents inspect and patch it.
+- The `.0` projection is readable text. Humans use it for review and rare
+  manual edits.
+
+When this page shows Zero syntax, it is showing projection syntax. The graph
+contains the same declarations, types, calls, and edges as structured facts.
+
+## Expected Usage
+
+Ask for the behavior in normal language. The Zero skills tell the agent to use
+the graph:
+
+```json-render
+{
+  "messages": [
+    {
+      "role": "user",
+      "text": "make a cli that adds two numbers"
+    },
+    {
+      "role": "assistant",
+      "text": "I’ll add the function, wire the CLI, and run a sample input."
+    },
+    {
+      "role": "tools",
+      "calls": [
+        {
+          "command": "zero query --fn main",
+          "output": "main\n  check world.out.write \"hello\\n\""
+        },
+        {
+          "command": "zero patch /tmp/add-cli.patch",
+          "output": "program graph patch ok"
+        },
+        {
+          "command": "zero run -- 40 2",
+          "output": "42"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Under the hood, the agent gathers current compiler knowledge with `zero skills`,
+inspects the package with `zero status` or `zero query`, patches the graph, then
+runs `zero check`, `zero test`, or `zero run` only when useful for the task.
+
+## A Minimal Program
+
+```zero
+pub fn main(world: World) -> Void raises {
+    check world.out.write("hello\n")
+}
+```
+
+Pieces visible in both graph and projection:
+
+- `pub fn main` declares the entry point.
+- `world: World` is an explicit capability parameter.
+- `Void` means no useful return value.
+- `raises` marks a fallible function.
+- `check` propagates a fallible operation.
+- `world.out.write(...)` writes through an explicit output capability.
+
+Run the graph input:
+
+```sh
+zero run examples/hello.graph
+```
+
+## Values And Bindings
+
+```zero
+let name: String = "Ada"
+var count: u32 = 0
+count = count + 1
+```
+
+`let` is immutable. `var` is mutable. Public constants and declarations should
+carry explicit types because the graph, diagnostics, and docs all benefit from
+stable type facts.
+
+## Functions
+
+```zero
+fn add(x: i32, y: i32) -> i32 {
+    return x + y
+}
+
+test "add works" {
+    expect (add(40, 2) == 42)
+}
+```
+
+Agents should usually add this through patch operations such as `addFunction`,
+`addParam`, `addReturnBinary`, and `addTest`, or through the row-based body DSL
+when replacing a function or block body.
+
+## Types
+
+```zero
+type Point {
+    x: i32,
+    y: i32,
+}
+
+enum Status {
+    Pending,
+    Ready,
+}
+```
+
+Types are graph declarations. Projection snippets make them readable for
+humans, but tools should inspect declaration nodes and symbol references.
+
+## Control Flow
+
+```zero
+if ready {
+    return 1
+} else {
+    return 0
+}
+
+while index < count {
+    index = index + 1
+}
+```
+
+Conditions must be `Bool`. Branch and loop bodies are blocks in the graph, so
+agents can patch a specific block without replacing the entire function.
+
+## Absence And Errors
+
+```zero
+let value: Maybe<u32> = std.args.parseU32(1)
+if value.has {
+    return value.value
+}
+return 0
+```
+
+`Maybe<T>` represents absence. Fallible functions use `raises`; `check`
+propagates failure through explicit control flow rather than exceptions.
+
+## Memory Views
+
+```zero
+let bytes: Span<u8> = std.mem.span("hello")
+var scratch: [16]u8 = [0_u8; 16]
+let copied: usize = std.mem.copy(scratch, bytes)
+```
+
+`Span<T>` borrows contiguous storage. `[N]T` is fixed storage. Standard library
+helpers prefer caller-owned buffers so the graph can expose allocation and
+ownership facts.
+
+## Packages And Projections
+
+A graph-first package has:
+
+```text
+zero.toml
+zero.graph
+src/main.0
+```
+
+`zero.graph` is the normal compile input. `src/main.0` is the readable
+projection named by the package target for source maps and review.
+
+Use:
+
+```sh
+zero export
+zero import
+zero verify-projection
+```
+
+Only use `export` or `import` when a human review or manual edit calls for it.
+
+## What To Read Next
+
+- Read **CLI Reference** for command groups and graph patch forms.
+- Read **Primitives And Types** for the language pieces behind graph facts.
+- Read **Standard Library** before asking an agent for CLI, HTTP, JSON, or
+  filesystem programs.
+- Read **Diagnostics And Repair** when an agent hits a compiler error.