json(vm): fix birth dispatch; unify constructor naming (Box.birth/N); JsonNode factories return JsonNodeInstance; quick: enable heavy JSON with probe; builder: NYASH_BUILDER_DEBUG_LIMIT guard; json_query_min(core) harness; docs/tasks updated

docs/guides/dev-mode.md

@@ -0,0 +1,54 @@
+Dev Mode and Defaults (Plan)
+
+Overview
+- Goal: make Nyash simple to run like other languages. Defaults should be obvious; experiments should be opt‑in.
+- Two modes:
+  - Production (default): quiet, stable; only stable features on.
+  - Development (`--dev`): safe dev defaults on; experiments enabled in observe mode; helpful diagnostics.
+
+Current
+- Use `--dev` to enable development defaults:
+  - `nyash --dev script.nyash`
+  - Enables AST using + Operator Boxes (observe) by default. Output remains stable.
+- Dev shortcuts remain available:
+  - `./tools/opbox-json.sh` – JSON Roundtrip/Nested with Operator Boxes
+  - `./tools/opbox-quick.sh` – Quick suite with Operator Boxes
+- Using guard:
+  - Duplicate `using` (same file imported twice or alias rebound) is a hard error with file:line hints.
+  - Fix by removing/consolidating duplicates.
+
+Defaults mapping
+- Production (default)
+  - using: ON (SSOT). AST merge only when nyash.toml defines the module (no implicit).
+  - Operator Boxes: OFF (no behavior change from legacy).
+  - Traces: OFF.
+- Development (`--dev`)
+  - using: AST merge ON (SSOT + AST prelude enabled by default).
+  - Operator Boxes: observe ON (stringify/compare/add calls visible; results not adopted → output is stable).
+  - Traces: OFF by default; can enable selectively via `NYASH_TRACE` (to be introduced) or legacy flags.
+  - Duplicate `using`: error (with line numbers).
+
+Flag consolidation (mid‑term)
+- `NYASH_OPERATOR_BOXES=all|none|comma-list` → expands to legacy flags.
+- `NYASH_TRACE=all|vm,box,print,if,loop` → expands to legacy trace flags.
+- Old flags remain; new keys take precedence; final resolved state is logged when `NYASH_CLI_VERBOSE=1`.
+
+nyash.toml profiles (long‑term)
+- Example:
+  [profiles.json-dev]
+  operator_boxes = ["stringify", "compare", "add"]
+  using_ast = true
+  trace = []
+
+  [profiles.debug]
+  operator_boxes = "all"
+  trace = ["vm", "box", "if", "loop"]
+  verbose = true
+
+Priority
+- CLI `--profile` > explicit env > nyash.toml defaults > built‑in defaults.
+
+Acceptance
+- `nyash script.nyash` runs with stable defaults.
+- `nyash --dev script.nyash` enables AST using + Operator Boxes (observe) and passes JSON Roundtrip/Nested.
+- Smokes use `--dev` path when appropriate; profiles remain as a convenience.

docs/guides/operator-boxes.md

@@ -0,0 +1,56 @@
+Operator Boxes (MVP) — Stringify
+
+Overview
+- Goal: Extend “Everything is Box” to implicit operations by modeling them as explicit, observable Boxes.
+- Scope (MVP): Stringify operation used by print paths.
+- Status: Dev‑only; opt‑in via env flag; backward compatible.
+
+Quick Run
+- JSON only (Roundtrip + Nested): `./tools/opbox-json.sh`
+- Quick suite (dev, light preflight): `./tools/opbox-quick.sh`
+
+Flags
+- NYASH_OPERATOR_BOX_STRINGIFY=1  Enable StringifyOperator on print paths
+- NYASH_OPERATOR_BOX_COMPARE=1    Enable CompareOperator (observer) on compare ops
+- NYASH_OPERATOR_BOX_ADD=1        Enable AddOperator (observer) on Add binop
+- NYASH_OPERATOR_BOX_ALL=1        Enable auto-prelude injection for all operator modules (runtime convenience)
+- NYASH_USING_AST=1               Required to AST‑merge the operator modules automatically
+  
+Parser tokens
+- Tokenizer accepts `~`, `<<`, `>>` in non‑strict mode (default). In strict_12_7, shift tokens are gated.
+- Unary `~x` parses to `UnaryOp(BitNot, x)`; binary `<< >> & | ^` parse via existing bit/shift rules.
+
+Behavior
+- Stringify: When the flag is ON, VM attempts to call `StringifyOperator.apply/1` before falling back to the legacy `to_string()`.
+- Compare (observer): When the flag is ON, VM calls `CompareOperator.apply/3` with `(op, a, b)` for observability, then performs normal compare semantics (operator result is ignored for now).
+- Add (observer): When the flag is ON, VM calls `AddOperator.apply/2` with `(a, b)` for observability, then performs normal add semantics (operator result is ignored for now).
+- The operators live under `apps/lib/std/operators/` and are auto‑injected into the AST prelude (dev only) so functions are materialized without changing user sources.
+
+Operator definitions (MVP)
+- Stringify — `apps/lib/std/operators/stringify.nyash`
+  - If `value` has `stringify()`, call it; else return `"" + value`.
+- Compare — `apps/lib/std/operators/compare.nyash`
+  - `apply(op, a, b)`; observer‑only for now, returns `true` and the VM performs the real compare.
+- Add — `apps/lib/std/operators/add.nyash`
+  - `apply(a, b)`; observer‑only for now, VM performs the real addition.
+- Sub/Mul/Div/Mod — `apps/lib/std/operators/{sub,mul,div,mod}.nyash`
+  - `apply(a, b)`; direct evaluation.
+- Bitwise/Shifts — `apps/lib/std/operators/{bitand,bitor,bitxor,shl,shr}.nyash`
+  - `apply(a, b)`; direct evaluation on integers.
+- Unary — `apps/lib/std/operators/{neg,not,bitnot}.nyash`
+  - `apply(a)`; negate / logical-not / bitwise-not.
+
+Design Notes
+- Backward compatible: existing programs run unchanged with the flag OFF (default).
+- Observability: with `NYASH_BOX_TRACE=1`, calls to the operator are visible as JSON lines (stderr), aiding diagnostics.
+- Rollback is trivial: remove the resolver injection and the two VM hooks; delete the operator file.
+
+Future Work (Optional / Later)
+- Elevate Compare/Add from observer to authoritative semantics behind stricter flags, once parity is verified.
+- Unify lowering (sugar → operator boxes) after VM and Builder parity are green.
+- Add per-operator adopt flags if needed for runtime switching; current builder call lowering already routes via operator boxes.
+
+Builder lowering (centralized)
+- Master flag: `NYASH_BUILDER_OPERATOR_BOX_ALL_CALL=1` lowers all arithmetic/compare/unary ops to `*Operator.apply` calls in one place (src/mir/builder/ops.rs).
+- Reentrancy guard: when building inside `*Operator.apply`, lowering is skipped to avoid recursion; falls back to direct MIR op.
+- Metadata: builder annotates result types (Integer/String/Bool) to preserve `value_types` so downstream analysis remains stable.