diff --git a/docs/development/roadmap/phases/phase-15/README.md b/docs/development/roadmap/phases/phase-15/README.md
index f6e36c26..5f262e20 100644
--- a/docs/development/roadmap/phases/phase-15/README.md
+++ b/docs/development/roadmap/phases/phase-15/README.md
@@ -148,7 +148,7 @@ Imports/Namespace plan（15.3‑late）
 
 ### 直近タスクリスト（Phase‑15用）
 1. Macro 前段の正式導入（完了／PoC→実運用）
-   - `NYASH_MACRO_BOX_NY=1` → PyVMランナー経由（既定推奨）
+   - `NYASH_MACRO_PATHS=...` でユーザーマクロ登録（ランナールート既定）
    - strict=1/timeout=2000ms（既定）
    - `--dump-expanded-ast-json` を golden として活用
 2. Self‑host フロントの簡素化
diff --git a/docs/development/roadmap/phases/phase-15/planning/macro_driven_replan.md b/docs/development/roadmap/phases/phase-15/planning/macro_driven_replan.md
index 2609cbd5..44d9b54b 100644
--- a/docs/development/roadmap/phases/phase-15/planning/macro_driven_replan.md
+++ b/docs/development/roadmap/phases/phase-15/planning/macro_driven_replan.md
@@ -20,7 +20,7 @@ Status: Adopted (2025‑09). This plan reframes Phase‑15 self‑hosting to lev
 
 ## Work Items
 1) Enable PyVM runner route for macros (done)
-   - `NYASH_MACRO_BOX_CHILD_RUNNER=1` → runner includes macro + calls `MacroBoxSpec.expand(json)`
+   - ランナールートが既定。内部子ルートは非推奨（`NYASH_MACRO_BOX_CHILD_RUNNER=0` でのみ強制）
 2) Identity + upper_string templates (done)
    - Examples under `apps/macros/examples/`
 3) Golden tests
@@ -36,4 +36,3 @@ Status: Adopted (2025‑09). This plan reframes Phase‑15 self‑hosting to lev
 - Expanded AST JSON matches goldens for sample programs
 - Macro runner path green under strict=1, timeout=2000ms
 - MIR/LLVM/VM paths stable with expanded inputs
-
diff --git a/docs/guides/macro-box-nyash.md b/docs/guides/macro-box-nyash.md
index 7d54f025..ed6586ec 100644
--- a/docs/guides/macro-box-nyash.md
+++ b/docs/guides/macro-box-nyash.md
@@ -10,8 +10,8 @@ Philosophy
 API (Nyash)
 ```nyash
 box MacroBoxSpec {
-  // Required entry. Receives entire AST and returns a transformed AST.
-  static function expand(ast) { /* pure transform */ }
+  // Required entry. Receives AST JSON and returns transformed AST JSON.
+  static function expand(json, ctx) { /* pure transform over JSON string */ }
 
   // Optional metadata.
   static function name() { return "MyMacro" }
@@ -27,7 +27,8 @@ paths = [
   "apps/macros/json_lints.nyash"
 ]
 ```
-- Loading policy (dev-only gate): `NYASH_MACRO_BOX_NY=1` enables loading Nyash MacroBoxes from configured paths.
+- Loading policy: register via `NYASH_MACRO_PATHS=path1,path2`（推奨）。
+- Runner route is default（self‑hosting優先）。内部子ルートは非推奨（`NYASH_MACRO_BOX_CHILD_RUNNER=0` 強制時のみ）。
 - Isolation: loaded in a dedicated interpreter with IO disabled; only AST utilities and safe helpers exposed.
  - Interim mapping (prototype): `name()` may map to built-in MacroBoxes for effects (e.g., `"UppercasePrintMacro"`). Otherwise, identity transform.
 
diff --git a/docs/guides/macro-box.md b/docs/guides/macro-box.md
index c42059e3..08f35d39 100644
--- a/docs/guides/macro-box.md
+++ b/docs/guides/macro-box.md
@@ -1,29 +1,32 @@
-# MacroBox — User Extensible Macro Units (Experimental)
+# MacroBox — User Extensible Macro Units
 
-Status: Prototype, behind env gates (default OFF).
+Status: Stable for user macros via Nyash runner route（self‑hosting優先）。
 
 Goals
 - Allow users to implement procedural macro-like expansions in pure Nyash (future) and Rust (prototype) with a clean, deterministic interface.
 - Preserve “Box independence” (loose coupling). Operate on public interfaces; avoid relying on private internals.
 
 Enabling
-- Enable MacroBox execution: `NYASH_MACRO_BOX=1`
-- Enable built-in example: `NYASH_MACRO_BOX_EXAMPLE=1`
-- Macro engine is ON by default; disable with `NYASH_MACRO_DISABLE=1`.
+- Macro engine is ON by default. Disable with `NYASH_MACRO_DISABLE=1`.
+- Register user macro files via `NYASH_MACRO_PATHS=path1,path2`.
+- Runner route（Nyashでの実行）が既定。内部子ルートは非推奨（`NYASH_MACRO_BOX_CHILD_RUNNER=0` でのみ強制）。
 
-API (Rust, prototype)
-- Trait: `trait MacroBox { fn name(&self) -> &'static str; fn expand(&self, ast: &ASTNode) -> ASTNode }`
-- Register: `macro::macro_box::register(&MY_BOX)`
-- Execution: Engine applies all registered boxes once per expansion pass (after built-in expansions). Order is registration order.
+API（Nyash, 推奨）
+- Box: `static box MacroBoxSpec { static function expand(json[, ctx]) -> json }`
+- Contract: AST JSON v0（docs/reference/ir/ast-json-v0.md）。ctxはJSON文字列（MVP: {caps:{io,net,env}}）。
+- 実行: エンジンは登録されたファイルをNyashランナールートで呼び出し、展開JSONを受け取る。
+
+API（Rust, 内部/開発者向け）
+- Trait: `MacroBox { name() -> &'static str; expand(&ASTNode) -> ASTNode }`
+- 用途: 最小のビルトイン（例: derive）やプロトタイピング。一般ユーザーはNyash版を使う。
 
 Constraints (philosophy)
-- Deterministic; side-effect free; no IO.
-- Respect Box independence: operate on public interfaces only where applicable.
+- Deterministic; side-effect free by default（io/net/envはcapabilitiesで明示）
+- Respect “Box independence”: 公開インターフェースを基本に、疎結合を維持
 
 Built-in example
-- `UppercasePrintMacro` (guarded by `NYASH_MACRO_BOX_EXAMPLE=1`): transforms `print("UPPER:...")` to uppercase.
+- `UppercasePrintMacro`（開発者向けの内蔵例）。通常はNyashで実装されたユーザーマクロを使用。
 
 Future plan
-- MacroBox in Nyash: `box MacroBox { static function expand(ast) -> ast }` with sandboxing and package registration via `nyash.toml`.
-- Attribute-style macros: `@derive`-like hooks executed as MacroBoxes.
-
+- nyash.toml による登録/パッケージ管理
+- Attribute-style macros（@derive/@lint）の整理
diff --git a/tools/test/smoke/macro/macro_user_invalid_json_nonstrict_identity.sh b/tools/test/smoke/macro/macro_user_invalid_json_nonstrict_identity.sh
index 9e20b7fa..2e4c7b40 100644
--- a/tools/test/smoke/macro/macro_user_invalid_json_nonstrict_identity.sh
+++ b/tools/test/smoke/macro/macro_user_invalid_json_nonstrict_identity.sh
@@ -11,11 +11,9 @@ if [ ! -x "$bin" ]; then
   exit 1
 fi
 
-export NYASH_MACRO_BOX_NY=1
-export NYASH_MACRO_BOX_CHILD_RUNNER=1
-export NYASH_MACRO_BOX_NY_PATHS="apps/macros/examples/invalid_json_macro.nyash"
+export NYASH_MACRO_ENABLE=1
+export NYASH_MACRO_PATHS="apps/macros/examples/invalid_json_macro.nyash"
 export NYASH_MACRO_STRICT=0   # non-strict should fall back to identity
-export NYASH_MACRO_BOX=1
 
 out=$("$bin" --dump-expanded-ast-json "$src")
 
diff --git a/tools/test/smoke/macro/macro_user_invalid_json_strict_fail.sh b/tools/test/smoke/macro/macro_user_invalid_json_strict_fail.sh
index 3a1b842e..56d05199 100644
--- a/tools/test/smoke/macro/macro_user_invalid_json_strict_fail.sh
+++ b/tools/test/smoke/macro/macro_user_invalid_json_strict_fail.sh
@@ -10,11 +10,9 @@ if [ ! -x "$bin" ]; then
   exit 1
 fi
 
-export NYASH_MACRO_BOX_NY=1
-export NYASH_MACRO_BOX_CHILD_RUNNER=1
-export NYASH_MACRO_BOX_NY_PATHS="apps/macros/examples/invalid_json_macro.nyash"
+export NYASH_MACRO_ENABLE=1
+export NYASH_MACRO_PATHS="apps/macros/examples/invalid_json_macro.nyash"
 export NYASH_MACRO_STRICT=1    # strict should fail process on invalid JSON
-export NYASH_MACRO_BOX=1
 
 set +e
 "$bin" --dump-expanded-ast-json "$src" >/dev/null 2>&1
diff --git a/tools/test/smoke/macro/macro_user_timeout_strict_fail.sh b/tools/test/smoke/macro/macro_user_timeout_strict_fail.sh
index 41b6fe91..cad58dcf 100644
--- a/tools/test/smoke/macro/macro_user_timeout_strict_fail.sh
+++ b/tools/test/smoke/macro/macro_user_timeout_strict_fail.sh
@@ -10,12 +10,10 @@ if [ ! -x "$bin" ]; then
   exit 1
 fi
 
-export NYASH_MACRO_BOX_NY=1
-export NYASH_MACRO_BOX_CHILD_RUNNER=1
-export NYASH_MACRO_BOX_NY_PATHS="apps/macros/examples/hang_macro.nyash"
+export NYASH_MACRO_ENABLE=1
+export NYASH_MACRO_PATHS="apps/macros/examples/hang_macro.nyash"
 export NYASH_NY_COMPILER_TIMEOUT_MS=200  # keep test quick
 export NYASH_MACRO_STRICT=1              # strict should fail process
-export NYASH_MACRO_BOX=1
 
 set +e
 "$bin" --dump-expanded-ast-json "$src" >/dev/null 2>&1
diff --git a/tools/test/smoke/macro/selfhost_preexpand_auto_smoke.sh b/tools/test/smoke/macro/selfhost_preexpand_auto_smoke.sh
index 5c1c4689..be794235 100644
--- a/tools/test/smoke/macro/selfhost_preexpand_auto_smoke.sh
+++ b/tools/test/smoke/macro/selfhost_preexpand_auto_smoke.sh
@@ -12,10 +12,7 @@ fi
 
 # Enable user macro (upper string) and macro engine
 export NYASH_MACRO_ENABLE=1
-export NYASH_MACRO_BOX_NY=1
-export NYASH_MACRO_BOX_NY_PATHS="apps/macros/examples/upper_string_macro.nyash"
-# Prefer internal child mode for speed/stability in CI
-export NYASH_MACRO_BOX_CHILD_RUNNER=0
+export NYASH_MACRO_PATHS="apps/macros/examples/upper_string_macro.nyash"
 
 # Selfhost pre-expand: default auto (no explicit env); requires PyVM
 export NYASH_USE_NY_COMPILER=1
@@ -31,4 +28,3 @@ echo "$out" | rg -q "selfhost macro pre-expand: engaging" && echo "[OK] selfhost
 echo "[WARN] selfhost pre-expand auto did not engage; printing logs:" >&2
 echo "$out" >&2
 exit 2
-