macroctx: pass ctx JSON (caps) to user macros; add demo macro; docs: MacroCtx section and sandbox Box API; golden for for/foreach normalized AST

docs/DEV_QUICKSTART.md

@@ -33,3 +33,11 @@ See also
 ## Testing
 - Rust unit tests: `cargo test`
 - Targeted: e.g., tokenizer/sugar config `cargo test --lib sugar_basic_test -- --nocapture`
+
+## Acceptance Checklist (Phase Freeze)
+- cargo check (workspace) passes
+- Representative smokes are green:
+  - PyVM smokes: `tools/pyvm_stage2_smoke.sh`
+  - LLVM harness smokes: `tools/llvm_smoke.sh release`
+  - Macro goldens: `tools/ci_check_golden.sh`
+- No spec changes (compat maintained); changes are minimal and local

docs/guides/macro-system.md

@@ -92,6 +92,23 @@ Notes:
   - Splice `$...name` into call/array argument lists.
   - Array/Map nodes participate in pattern/unquote (map keys must match literally; values can bind via `$name`).
 
+## MacroCtx (PoC)
+
+User macros executed via the PyVM sandbox receive a second argument `ctx` in `expand(json, ctx)`:
+
+- Shape (string): `{ "caps": { "io": bool, "net": bool, "env": bool } }`
+- Policy: all caps default to false. The sandbox disables plugins and exposes a minimal Box API.
+- Do not print to stdout from macros: the child process stdout is reserved for the expanded JSON.
+  - For diagnostics use stderr in the future; for now prefer silent operation or trace via the parent process.
+
+Example (identity):
+```
+static box MacroBoxSpec {
+  name() { return "MacroCtxDemo" }
+  expand(json, ctx) { return json }
+}
+```
+
 ### JSON test args (advanced)
 
 For `--run-tests`, you can supply per-test arguments and instance construction details via `NYASH_TEST_ARGS_JSON`.