diff --git a/docs/reference/environment-variables.md b/docs/reference/environment-variables.md
index 4053b244..79d768b6 100644
--- a/docs/reference/environment-variables.md
+++ b/docs/reference/environment-variables.md
@@ -93,6 +93,8 @@ NYASH_USE_STAGE1_CLI=1 STAGE1_EMIT_MIR_JSON=1 \
 | `NYASH_ENABLE_USING=1` | ON | Any | using 文を有効化 |
 | `HAKO_ENABLE_USING=1` | ON | Any | using 文 alias (.hako) |
 | `NYASH_RESOLVE_TRACE=1` | OFF | Any | using/prelude 解決のトレース |
+| `NYASH_RESOLVE_SEAM_DEBUG=1` | OFF | Any | using/prelude の結合境界マーカーを挿入（診断用） |
+| `NYASH_RESOLVE_DUMP_MERGED=/path/to/out.hako` | unset | Any | using/prelude の text-merge 後ソースを指定パスにダンプ（診断用） |
 | `NYASH_VM_DUMP_MERGED_HAKO=1` | OFF | Rust AST | using/prelude マージ後の Hako ソースをダンプ |
 
 ---
@@ -101,6 +103,7 @@ NYASH_USE_STAGE1_CLI=1 STAGE1_EMIT_MIR_JSON=1 \
 
 | 変数 | デフォルト | 適用経路 | 説明 |
 | --- | --- | --- | --- |
+| `NYASH_ROOT=/path/to/repo` | unset | Any | リポジトリルートのヒント（パス解決・ツール用途）。未指定なら自動推定 |
 | `NYASH_VM_USE_PY=1` | OFF | Any | PyVM を優先実行 |
 | `NYASH_PIPE_USE_PYVM=1` | OFF | JSON v0/Stage-1 | pipe 実行を PyVM に直送 |
 | `NYASH_VM_PLUGIN_STRICT=1` | OFF | Any | 必須プラグイン欠如で fail-fast |
diff --git a/src/config/env/catalog.rs b/src/config/env/catalog.rs
index 1578d340..16805146 100644
--- a/src/config/env/catalog.rs
+++ b/src/config/env/catalog.rs
@@ -263,6 +263,30 @@ pub fn env_vars() -> Vec<EnvVarMeta> {
             applies_to: AppliesTo::CLI,
             default: None,
         },
+        EnvVarMeta {
+            name: "NYASH_ROOT",
+            description: "Repo root hint for tools/path resolution (optional)",
+            applies_to: AppliesTo::CLI,
+            default: None,
+        },
+        EnvVarMeta {
+            name: "NYASH_RESOLVE_TRACE",
+            description: "Trace using/prelude resolution (1=true)",
+            applies_to: AppliesTo::Compiler,
+            default: None,
+        },
+        EnvVarMeta {
+            name: "NYASH_RESOLVE_SEAM_DEBUG",
+            description: "Insert using boundary markers for diagnostics (1=true)",
+            applies_to: AppliesTo::Compiler,
+            default: None,
+        },
+        EnvVarMeta {
+            name: "NYASH_RESOLVE_DUMP_MERGED",
+            description: "Dump merged prelude+main source to the given path",
+            applies_to: AppliesTo::Compiler,
+            default: None,
+        },
         // Macro capabilities (Phase 286A)
         EnvVarMeta {
             name: "NYASH_MACRO_CAP_IO",