docs: prefer Nyash runner route (self-hosting); switch to NYASH_MACRO_PATHS; deprecations noted; update smokes to new envs

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.
 

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）の整理