chore: import upstream snapshot with attribution

docs/articles/optimization.md

@@ -0,0 +1,77 @@
+## Make Retention Visible
+
+Zerolang optimization docs should answer a concrete question: why did this graph
+input retain these bytes, helpers, allocations, or runtime shims?
+
+```json-render
+{
+  "messages": [
+    {
+      "role": "user",
+      "text": "why is this binary bigger now?"
+    },
+    {
+      "role": "assistant",
+      "text": "I’ll inspect the size report and trace what is being retained."
+    },
+    {
+      "role": "tools",
+      "calls": [
+        {
+          "command": "zero size --json",
+          "output": "{\"sizeBreakdown\":{},\"retentionReasons\":[\"std.http.fetch retained by handle\"]}"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## What This Means
+
+Use graph inputs or graph-first packages:
+
+```sh
+zero size --json examples/fixed-vec.graph
+zero mem --json examples/allocator-collections.graph
+zero build --json --profile tiny --target linux-musl-x64 examples/hello.graph --out .zero/out/hello
+```
+
+## Profiles
+
+| Profile | Use when | Contract |
+| --- | --- | --- |
+| `debug` | You need diagnostics and local symbols. | Keeps diagnostic/debug metadata. |
+| `fast` | Throughput matters more than minimum size. | Optimizes for speed within current direct codegen limits. |
+| `small` | You want the normal release shape. | Pay-as-used helpers and deterministic artifacts. |
+| `tiny` | Artifact size is the main constraint. | Minimum runtime metadata and strict helper budget. |
+
+Build JSON includes `profileSemantics`, `profileCatalog`, `profileBudget`, and
+`safetyFacts`.
+
+## Size Reports
+
+`zero size --json` adds:
+
+- `sizeBreakdown`
+- `retentionReasons`
+- `optimizationHints`
+- retained function and helper facts
+- literal and section cost
+- target and profile facts
+
+Use `retentionReasons` when an agent needs to explain why a helper, literal, or
+debug metadata block stayed in the artifact.
+
+## Memory Reports
+
+`zero mem --json` includes:
+
+- `memoryBudgets`
+- `allocatorFacts`
+- `allocationInstrumentation`
+- `collectionFacts`
+- `safetyFacts`
+
+These fields are the public way to check whether an example remains
+fixed-capacity, caller-buffered, or heap-free.