tirth8205
diff --git a/‎code_review_graph/cli.py‎
Lines changed: 109 additions & 10 deletions b/‎code_review_graph/cli.py‎
Lines changed: 109 additions & 10 deletions
diff --git a/‎code_review_graph/embeddings.py‎
Lines changed: 34 additions & 0 deletions b/‎code_review_graph/embeddings.py‎
Lines changed: 34 additions & 0 deletions
diff --git a/‎code_review_graph/incremental.py‎
Lines changed: 58 additions & 19 deletions b/‎code_review_graph/incremental.py‎
Lines changed: 58 additions & 19 deletions
diff --git a/‎code_review_graph/main.py‎
Lines changed: 7 additions & 0 deletions b/‎code_review_graph/main.py‎
Lines changed: 7 additions & 0 deletions
@@ -95,6 +95,61 @@ def _print_banner() -> None:
 """)
 
 
+def _instruction_files_to_modify(
+    repo_root: Path, target: str,
+) -> list[str]:
+    """Return the list of instruction files that ``install`` would write
+    or modify, given the current state of the repo and the selected
+    platform target. Used for the dry-run / confirm preview (#173).
+    """
+    from .skills import _CLAUDE_MD_SECTION_MARKER, _PLATFORM_INSTRUCTION_FILES
+
+    targets: list[str] = []
+
+    if target in ("claude", "all"):
+        claude_md = repo_root / "CLAUDE.md"
+        if claude_md.exists():
+            content = claude_md.read_text(encoding="utf-8")
+            if _CLAUDE_MD_SECTION_MARKER not in content:
+                targets.append("CLAUDE.md (append)")
+        else:
+            targets.append("CLAUDE.md (new)")
+
+    for filename, owners in _PLATFORM_INSTRUCTION_FILES.items():
+        if target != "all" and target not in owners:
+            continue
+        path = repo_root / filename
+        if path.exists():
+            content = path.read_text(encoding="utf-8")
+            if _CLAUDE_MD_SECTION_MARKER not in content:
+                targets.append(f"{filename} (append)")
+        else:
+            targets.append(f"{filename} (new)")
+
+    return targets
+
+
+def _confirm_yes_no(prompt: str, default_yes: bool = True) -> bool:
+    """Prompt the user [Y/n] and return True for yes.
+
+    Non-interactive environments (no TTY on stdin, e.g. an MCP wrapper
+    piping the CLI) return ``default_yes`` without blocking — the
+    stdio transport cannot safely read from stdin without corrupting
+    the JSON-RPC stream. See: #173, #174
+    """
+    if not sys.stdin.isatty():
+        return default_yes
+    suffix = "[Y/n]" if default_yes else "[y/N]"
+    try:
+        answer = input(f"{prompt} {suffix} ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return False
+    if not answer:
+        return default_yes
+    return answer in ("y", "yes")
+
+
 def _handle_init(args: argparse.Namespace) -> None:
     """Set up MCP config for detected AI coding platforms."""
     from .incremental import ensure_repo_gitignore_excludes_crg, find_repo_root
@@ -108,6 +163,8 @@ def _handle_init(args: argparse.Namespace) -> None:
     target = getattr(args, "platform", "all") or "all"
     if target == "claude-code":
         target = "claude"
+    auto_yes = getattr(args, "yes", False)
+    skip_instructions = getattr(args, "no_instructions", False)
 
     print("Installing MCP server config...")
     configured = install_platform_configs(repo_root, target=target, dry_run=dry_run)
@@ -117,9 +174,17 @@ def _handle_init(args: argparse.Namespace) -> None:
     else:
         print(f"\nConfigured {len(configured)} platform(s): {', '.join(configured)}")
 
+    # Preview the instruction files that would be touched (#173).
+    instr_targets = _instruction_files_to_modify(repo_root, target)
+    if instr_targets:
+        print()
+        print("Graph instructions will be injected into:")
+        for t in instr_targets:
+            print(f"  {t}")
+
     if dry_run:
-        print("[dry-run] Would ensure .gitignore ignores .code-review-graph/.")
-        print("\n[dry-run] No files were modified.")
+        print("\n[dry-run] Would ensure .gitignore ignores .code-review-graph/.")
+        print("[dry-run] No files were modified.")
         return
 
     gitignore_state = ensure_repo_gitignore_excludes_crg(repo_root)
@@ -131,7 +196,8 @@ def _handle_init(args: argparse.Namespace) -> None:
         print(".gitignore already contains .code-review-graph/.")
 
     # Skills and hooks are installed by default so Claude actually uses the
-    # graph tools proactively.  Use --no-skills / --no-hooks to opt out.
+    # graph tools proactively.  Use --no-skills / --no-hooks / --no-instructions
+    # to opt out.
     skip_skills = getattr(args, "no_skills", False)
     skip_hooks = getattr(args, "no_hooks", False)
     # Legacy: --skills/--hooks/--all still accepted (no-op, everything is default)
@@ -147,11 +213,26 @@ def _handle_init(args: argparse.Namespace) -> None:
     if not skip_skills:
         skills_dir = generate_skills(repo_root)
         print(f"Generated skills in {skills_dir}")
-        if target in ("claude", "all"):
-            inject_claude_md(repo_root)
-        updated = inject_platform_instructions(repo_root, target=target)
-        if updated:
-            print(f"Injected graph instructions into: {', '.join(updated)}")
+
+    # Confirm before writing instruction files (#173). --yes skips the
+    # prompt; --no-instructions skips the whole block.
+    if not skip_instructions and instr_targets:
+        if auto_yes or _confirm_yes_no(
+            "Inject graph instructions into the files above?",
+            default_yes=True,
+        ):
+            if target in ("claude", "all"):
+                inject_claude_md(repo_root)
+            inject_platform_instructions(repo_root, target=target)
+            # Use the precomputed instr_targets list for the confirmation
+            # message; we don't need the fresh return value from
+            # inject_platform_instructions here.
+            names = [t.split(" ")[0] for t in instr_targets]
+            print(f"Injected graph instructions into: {', '.join(names)}")
+        else:
+            print("Skipped instruction injection (user declined).")
+    elif skip_instructions:
+        print("Skipped instruction injection (--no-instructions).")
 
     if not skip_hooks and target in ("claude", "all"):
         install_hooks(repo_root)
@@ -194,6 +275,14 @@ def main() -> None:
         "--no-hooks", action="store_true",
         help="Skip installing Claude Code hooks",
     )
+    install_cmd.add_argument(
+        "--no-instructions", action="store_true",
+        help="Skip injecting graph instructions into CLAUDE.md / AGENTS.md / etc.",
+    )
+    install_cmd.add_argument(
+        "-y", "--yes", action="store_true",
+        help="Auto-confirm instruction injection without an interactive prompt",
+    )
     # Legacy flags (kept for backwards compat, now no-ops since all is default)
     install_cmd.add_argument("--skills", action="store_true", help=argparse.SUPPRESS)
     install_cmd.add_argument("--hooks", action="store_true", help=argparse.SUPPRESS)
@@ -225,6 +314,14 @@ def main() -> None:
         "--no-hooks", action="store_true",
         help="Skip installing Claude Code hooks",
     )
+    init_cmd.add_argument(
+        "--no-instructions", action="store_true",
+        help="Skip injecting graph instructions into CLAUDE.md / AGENTS.md / etc.",
+    )
+    init_cmd.add_argument(
+        "-y", "--yes", action="store_true",
+        help="Auto-confirm instruction injection without an interactive prompt",
+    )
     init_cmd.add_argument("--skills", action="store_true", help=argparse.SUPPRESS)
     init_cmd.add_argument("--hooks", action="store_true", help=argparse.SUPPRESS)
     init_cmd.add_argument("--all", action="store_true", dest="install_all",
@@ -553,8 +650,9 @@ def main() -> None:
             watch(repo_root, store)
 
         elif args.command == "visualize":
+            from .incremental import get_data_dir
             from .visualization import generate_html
-            html_path = repo_root / ".code-review-graph" / "graph.html"
+            html_path = get_data_dir(repo_root) / "graph.html"
             vis_mode = getattr(args, "mode", "auto") or "auto"
             generate_html(store, html_path, mode=vis_mode)
             print(f"Visualization ({vis_mode}): {html_path}")
@@ -579,8 +677,9 @@ def main() -> None:
                 print("Open in browser to explore your codebase graph.")
 
         elif args.command == "wiki":
+            from .incremental import get_data_dir
             from .wiki import generate_wiki
-            wiki_dir = repo_root / ".code-review-graph" / "wiki"
+            wiki_dir = get_data_dir(repo_root) / "wiki"
             result = generate_wiki(store, wiki_dir, force=args.force)
             total = result["pages_generated"] + result["pages_updated"] + result["pages_unchanged"]
             print(
 
@@ -13,6 +13,7 @@
 import os
 import sqlite3
 import struct
+import sys
 import time
 from abc import ABC, abstractmethod
 from pathlib import Path
@@ -246,6 +247,35 @@ def name(self) -> str:
         return f"minimax:{self._MODEL}"
 
 
+CLOUD_PROVIDERS = {"google", "minimax"}
+
+
+def _warn_cloud_egress(provider_name: str) -> None:
+    """Print a stderr warning before a cloud embedding provider is used.
+
+    The warning is suppressed when ``CRG_ACCEPT_CLOUD_EMBEDDINGS=1`` is
+    set in the environment, so scripted / CI workloads can acknowledge
+    once and move on. Use stderr (never stdin/input) to stay compatible
+    with the MCP stdio transport — anything we write to stdout would
+    corrupt the JSON-RPC stream. See: #174
+    """
+    if os.environ.get("CRG_ACCEPT_CLOUD_EMBEDDINGS", "").strip() == "1":
+        return
+    print(
+        f"\n⚠️  code-review-graph: about to embed code via the '{provider_name}' "
+        "cloud provider.\n"
+        "    Your source code (function names, docstrings, file paths) will be "
+        "sent to an external API.\n"
+        "    This is necessary for semantic search with the cloud provider you "
+        "selected.\n"
+        "    To skip this warning in future runs, set "
+        "CRG_ACCEPT_CLOUD_EMBEDDINGS=1 in your environment.\n"
+        "    To stay fully offline, use the default 'local' provider instead "
+        "(no API key needed).\n",
+        file=sys.stderr,
+    )
+
+
 def get_provider(
     provider: str | None = None,
     model: str | None = None,
@@ -256,6 +286,8 @@ def get_provider(
         provider: Provider name. One of "local", "google", "minimax", or None for local.
                   Google requires GOOGLE_API_KEY env var and explicit opt-in.
                   MiniMax requires MINIMAX_API_KEY env var and explicit opt-in.
+                  Cloud providers emit a one-time stderr warning before use
+                  unless ``CRG_ACCEPT_CLOUD_EMBEDDINGS=1`` is set. See: #174
         model: Model name/path to use. For local provider this is any
                sentence-transformers compatible model. Falls back to
                CRG_EMBEDDING_MODEL env var, then to all-MiniLM-L6-v2.
@@ -268,6 +300,7 @@ def get_provider(
                 "MINIMAX_API_KEY environment variable is required for "
                 "the MiniMax embedding provider."
             )
+        _warn_cloud_egress("minimax")
         return MiniMaxEmbeddingProvider(api_key=api_key)
 
     if provider == "google":
@@ -277,6 +310,7 @@ def get_provider(
                 "GOOGLE_API_KEY environment variable is required for "
                 "the Google embedding provider."
             )
+        _warn_cloud_egress("google")
         try:
             return GoogleEmbeddingProvider(
                 api_key=api_key,
 
@@ -84,37 +84,76 @@ def find_repo_root(start: Path | None = None) -> Optional[Path]:
 
 
 def find_project_root(start: Path | None = None) -> Path:
-    """Find the project root: git repo root if available, otherwise cwd."""
+    """Find the project root.
+
+    Resolution order (highest precedence first):
+
+    1. ``CRG_REPO_ROOT`` environment variable — explicit override for
+       anyone scripting the CLI from outside the repo (CI jobs, daemons,
+       multi-repo orchestrators). See: #155
+    2. Git repository root via :func:`find_repo_root` from ``start``.
+    3. ``start`` itself (or cwd if no start given).
+    """
+    env_override = os.environ.get("CRG_REPO_ROOT", "").strip()
+    if env_override:
+        p = Path(env_override).expanduser().resolve()
+        if p.exists():
+            return p
     root = find_repo_root(start)
     if root:
         return root
     return start or Path.cwd()
 
 
-def get_db_path(repo_root: Path) -> Path:
-    """Determine the database path for a repository.
+def get_data_dir(repo_root: Path) -> Path:
+    """Return the directory where this project's graph data lives.
 
-    Creates the ``.code-review-graph/`` directory and an inner ``.gitignore``
-    (with ``*``) so generated files are never committed.  If a legacy
-    ``.code-review-graph.db`` exists at the repo root the database is migrated
-    into the new directory (WAL/SHM side-files are discarded).
+    By default, ``<repo_root>/.code-review-graph``. If the
+    ``CRG_DATA_DIR`` environment variable is set, it is used verbatim
+    instead — letting you keep graphs outside the working tree (useful
+    for ephemeral workspaces, Docker volumes, or shared caches). See: #155
+
+    The directory is created if it does not already exist; an inner
+    ``.gitignore`` (with ``*``) is written so any accidentally-nested
+    files never get committed. Both are idempotent.
     """
-    crg_dir = repo_root / ".code-review-graph"
-    new_db = crg_dir / "graph.db"
+    env_override = os.environ.get("CRG_DATA_DIR", "").strip()
+    if env_override:
+        data_dir = Path(env_override).expanduser().resolve()
+    else:
+        data_dir = repo_root / ".code-review-graph"
 
-    # Ensure directory exists
-    crg_dir.mkdir(exist_ok=True)
+    data_dir.mkdir(parents=True, exist_ok=True)
 
-    # Auto-create .gitignore inside the directory (idempotent)
-    inner_gitignore = crg_dir / ".gitignore"
+    inner_gitignore = data_dir / ".gitignore"
     if not inner_gitignore.exists():
-        inner_gitignore.write_text(
-            "# Auto-generated by code-review-graph — do not commit database files.\n"
-            "# The graph.db contains absolute paths and code structure metadata.\n"
-            "*\n"
-        )
+        try:
+            inner_gitignore.write_text(
+                "# Auto-generated by code-review-graph — do not commit database files.\n"
+                "# The graph.db contains absolute paths and code structure metadata.\n"
+                "*\n"
+            )
+        except OSError:
+            # Data dir might be read-only (rare); that's OK, it's a best-effort guard.
+            pass
+
+    return data_dir
+
+
+def get_db_path(repo_root: Path) -> Path:
+    """Determine the database path for a repository.
+
+    Respects ``CRG_DATA_DIR`` (see :func:`get_data_dir`). Migrates a
+    legacy top-level ``.code-review-graph.db`` file into the new
+    directory when it exists (WAL/SHM side-files are discarded).
+    """
+    crg_dir = get_data_dir(repo_root)
+    new_db = crg_dir / "graph.db"
 
-    # Migrate legacy database if present
+    # Migrate legacy database if present (only meaningful when the
+    # legacy file sits at the repo root — if CRG_DATA_DIR is set we
+    # skip the migration because there's no relationship between the
+    # legacy location and the new one).
     legacy_db = repo_root / ".code-review-graph.db"
     if legacy_db.exists() and not new_db.exists():
         legacy_db.rename(new_db)
 
@@ -571,6 +571,7 @@ def refactor_tool(
 def apply_refactor_tool(
     refactor_id: str,
     repo_root: Optional[str] = None,
+    dry_run: bool = False,
 ) -> dict:
     """Apply a previously previewed refactoring to source files.
 
@@ -584,9 +585,15 @@ def apply_refactor_tool(
     Args:
         refactor_id: The refactor ID from refactor_tool's response.
         repo_root: Repository root path. Auto-detected if omitted.
+        dry_run: If True, return a unified diff of what would change
+            without touching any files. The refactor_id remains valid so
+            the same preview can be applied in a follow-up call without
+            dry_run. Use this for a human-in-the-loop review before
+            committing changes to disk. See: #176
     """
     return apply_refactor_func(
         refactor_id=refactor_id, repo_root=_resolve_repo_root(repo_root),
+        dry_run=dry_run,
     )