@ictechgy/context-guard 0.4.1 → 0.4.3

package/context-guard-kit/context_pack.py

@@ -10,16 +10,19 @@ retrieval when the path is safe to display.
 from __future__ import annotations
 
 import argparse
+import ast
 import copy
 import hashlib
 import importlib.machinery
 import importlib.util
 import json
 import os
+import posixpath
 from pathlib import Path
 import re
 import shlex
 import stat
+import subprocess
 import sys
 import time
 from dataclasses import dataclass
@@ -35,22 +38,79 @@ MAX_MANIFEST_BYTES = 1_000_000
 MAX_LABEL_CHARS = 160
 MAX_REASON_CHARS = 120
 TOKEN_PROXY_CHARS_PER_TOKEN = 4
+SUGGEST_SCHEMA_VERSION = "contextguard.pack-suggest.v1"
+AUTO_SCHEMA_VERSION = "contextguard.pack-auto.v1"
+AUTO_EXPLAIN_SCHEMA_VERSION = "contextguard.pack-auto-explain.v1"
+REPO_MAP_SCHEMA_VERSION = "contextguard.pack-repo-map.v1"
+DEFAULT_SUGGEST_TOP = 8
+MAX_SUGGEST_TOP = 50
+DEFAULT_SUGGEST_CONTEXT_LINES = 20
+MAX_SUGGEST_CONTEXT_LINES = 120
+SUGGEST_WHOLE_FILE_MAX_LINES = 120
+MAX_SUGGEST_INPUT_BYTES = 256_000
+MAX_QUERY_SCAN_FILES = 2_000
+MAX_QUERY_SCAN_BYTES_PER_FILE = 200_000
+MAX_REPO_MAP_FILES = 1_000
+MAX_REPO_MAP_BYTES_PER_FILE = 120_000
+MAX_REPO_MAP_TREE_ENTRIES = 30
+MAX_REPO_MAP_SIGNATURE_ENTRIES = 40
+MAX_REPO_MAP_GRAPH_RANK_ENTRIES = 30
+MAX_REPO_MAP_RETRIEVAL_HINTS = 30
+MAX_REPO_MAP_SECRET_RISK_FILES = 20
 PACK_DIR = ".context-guard/packs"
 REDACTED_PATH_COMPONENT = "[REDACTED-PATH-COMPONENT]"
+CONTROL_CHAR_RE = re.compile(r"[\x00-\x1f\x7f-\x9f]")
 SECRET_CONTENT_RE = re.compile(
     r"(?is)("
     r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----|"
     r"AKIA[0-9A-Z]{16}|"
+    r"ASIA[0-9A-Z]{16}|"
     r"gh[pousr]_[A-Za-z0-9_]{20,}|"
     r"github_pat_[A-Za-z0-9_]{20,}|"
+    r"glpat-[A-Za-z0-9_-]{12,}|"
     r"xox[abprs]-[A-Za-z0-9-]{10,}|"
     r"sk-(?:ant|proj)-[A-Za-z0-9_-]{12,}|"
     r"sk-[A-Za-z0-9][A-Za-z0-9_-]{20,}|"
+    r"(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{16,}|"
+    r"npm_[A-Za-z0-9]{20,}|"
     r"AIza[0-9A-Za-z_\-]{20,}|"
     r"(?i:Authorization)\s*:\s*(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+|"
     r"(?<![A-Za-z0-9])(?:api[_-]?key|token|secret|password|client[_-]?secret)\s*[:=]\s*[^\s]+"
     r")"
 )
+SECRET_PATH_COMPONENT_RE = re.compile(
+    r"(?i)("
+    r"SG\.[A-Za-z0-9_-]{16,256}\.[A-Za-z0-9_-]{16,512}|"
+    r"eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}|"
+    r"\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{12,}|"
+    r"[a-z][a-z0-9+.-]{0,31}:/+(?:[^/\s:@]{0,256}:[^/\s@]{0,2048}|[^/\s@]{1,2048})@"
+    r")"
+)
+SECRET_RISK_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("private_key_block", re.compile(r"(?is)-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----")),
+    ("github_token", re.compile(r"gh[pousr]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{12,}")),
+    ("provider_api_key", re.compile(r"sk-(?:ant|proj)-[A-Za-z0-9_-]{12,}|sk-[A-Za-z0-9][A-Za-z0-9_-]{20,}|AIza[0-9A-Za-z_\-]{20,}")),
+    ("authorization_header", re.compile(r"(?i)Authorization\s*:\s*(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+")),
+    ("generic_secret_assignment", re.compile(r"(?i)(?:api[_-]?key|token|secret|password|client[_-]?secret)\s*[:=]\s*[^\s]+")),
+)
+REPO_MAP_TEXT_EXTENSIONS = {
+    ".py", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs",
+    ".go", ".rs", ".java", ".kt", ".kts", ".swift", ".c", ".cc", ".cpp", ".h", ".hpp",
+    ".md", ".mdx", ".txt", ".json", ".yaml", ".yml", ".toml", ".sh", ".css", ".html",
+}
+SYMBOL_HINT_EXTENSIONS = {".py", ".js", ".jsx", ".ts", ".tsx", ".go", ".rs"}
+SIGNATURE_LINE_RE = re.compile(
+    r"^\s*(?:export\s+)?(?:(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(|class\s+([A-Za-z_$][\w$]*)|"
+    r"(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>|"
+    r"func\s+(?:\([^)]*\)\s*)?([A-Za-z_]\w*)\s*\(|(?:pub\s+)?(?:async\s+)?fn\s+([A-Za-z_]\w*)\s*\()"
+)
+IMPORT_PATH_RE = re.compile(
+    r"(?:from\s+['\"](?P<jsfrom>[^'\"]+)['\"]|"
+    r"import(?:\s+[^;\n'\"]+?\s+from)?\s+['\"](?P<jsimport>[^'\"]+)['\"]|"
+    r"from\s+(?P<pyfrom>\.*[A-Za-z_][\w.]*|\.+)\s+import|"
+    r"import\s+(?P<pyimport>[A-Za-z_][\w.]*))"
+)
+PY_FROM_IMPORT_LINE_RE = re.compile(r"^\s*from\s+(?P<module>\.*[A-Za-z_][\w.]*|\.+)\s+import\s+(?P<names>[^\n#;]+)")
 
 
 @dataclass(frozen=True)
@@ -87,6 +147,16 @@ class ResolvedSource:
     redacted_lines: int
 
 
+@dataclass
+class SuggestCandidate:
+    path: str
+    score: int
+    reason: str
+    lines: LineRange | None = None
+    label: str | None = None
+    input_index: int = 0
+
+
 class PackError(ValueError):
     pass
 
@@ -176,9 +246,10 @@ def display_root(root: Path) -> str:
 
 
 def display_rel_path(rel: str) -> tuple[str, bool]:
+    normalized = rel.replace("\\", "/")
     parts: list[str] = []
     redacted = False
-    for part in rel.replace("\\", "/").split("/"):
+    for part in normalized.split("/"):
         if not part:
             continue
         safe, did = sanitize_path_component(part)
@@ -187,6 +258,24 @@ def display_rel_path(rel: str) -> tuple[str, bool]:
     return "/".join(parts), redacted
 
 
+def repo_map_path_has_sensitive_evidence(value: str) -> bool:
+    return bool(CONTROL_CHAR_RE.search(value) or SECRET_PATH_COMPONENT_RE.search(value))
+
+
+def repo_map_display_rel_path(rel: str) -> tuple[str, bool]:
+    normalized = rel.replace("\\", "/")
+    if repo_map_path_has_sensitive_evidence(normalized):
+        return f"redacted-path#path:{sha256_text(normalized)[:12]}", True
+    return display_rel_path(normalized)
+
+
+def repo_map_safe_raw_path_label(raw: str) -> str:
+    normalized = raw.replace("\\", "/")
+    if repo_map_path_has_sensitive_evidence(normalized):
+        return f"redacted-path#path:{sha256_text(normalized)[:12]}"
+    return safe_raw_path_label(normalized)
+
+
 def parse_line_range(value: object) -> LineRange | None:
     if value is None or value == "":
         return None
@@ -484,7 +573,7 @@ def retrieval_cli(root_arg: str, display_path: str, lines: LineRange) -> str:
 
 def safe_root_arg_for_retrieval(root_arg: str) -> str | None:
     text = str(root_arg)
-    if SECRET_CONTENT_RE.search(text):
+    if CONTROL_CHAR_RE.search(text) or SECRET_CONTENT_RE.search(text) or SECRET_PATH_COMPONENT_RE.search(text):
         return None
     for part in text.replace("\\", "/").split("/"):
         if not part:
@@ -495,6 +584,13 @@ def safe_root_arg_for_retrieval(root_arg: str) -> str | None:
     return text
 
 
+def safe_repo_map_root_arg_for_retrieval(root_arg: str) -> str | None:
+    text = str(root_arg)
+    if repo_map_path_has_sensitive_evidence(text):
+        return None
+    return safe_root_arg_for_retrieval(text)
+
+
 def retrieval_for(root_arg: str, display_path: str, lines: LineRange, *, redacted_path: bool) -> tuple[str | None, str | None]:
     if redacted_path:
         return None, "redacted_path"
@@ -866,6 +962,1559 @@ def slice_source(root: Path, *, raw_path: str, lines: LineRange) -> tuple[dict[s
     return payload, 0
 
 
+def suggest_tokens(text: str) -> set[str]:
+    sanitized = SECRET_CONTENT_RE.sub(" ", text.lower())
+    return {part for part in re.findall(r"[a-z0-9_][a-z0-9_.-]{1,}", sanitized) if len(part) >= 2}
+
+
+def suggest_score_path(path: str, query_terms: set[str]) -> int:
+    lowered = path.lower()
+    score = 0
+    for term in query_terms:
+        if term in lowered:
+            score += 120
+    return score
+
+
+def suggest_reason(*parts: str) -> str:
+    return cap_label("; ".join(part for part in parts if part), default="local heuristic", limit=MAX_REASON_CHARS) or "local heuristic"
+
+
+def split_suggest_files(values: list[str] | None) -> list[str]:
+    out: list[str] = []
+    for value in values or []:
+        for part in str(value).split(","):
+            text = part.strip()
+            if text:
+                out.append(text)
+    return out
+
+
+def line_window(line_number: int, total_lines: int | None, context_lines: int) -> LineRange:
+    start = max(1, line_number - context_lines)
+    if total_lines is None:
+        end = max(start, line_number + context_lines)
+    else:
+        end = min(max(start, line_number + context_lines), max(1, total_lines))
+    return LineRange(start, end)
+
+
+def merge_line_window(existing: LineRange | None, line_number: int, context_lines: int) -> LineRange:
+    window = line_window(line_number, None, context_lines)
+    if existing is None:
+        return window
+    return LineRange(min(existing.start, window.start), max(existing.end, window.end))
+
+
+def add_suggest_candidate(
+    candidates: list[SuggestCandidate],
+    *,
+    path: str,
+    score: int,
+    reason: str,
+    lines: LineRange | None = None,
+    label: str | None = None,
+) -> None:
+    candidates.append(
+        SuggestCandidate(
+            path=path,
+            score=score,
+            reason=suggest_reason(reason),
+            lines=lines,
+            label=cap_label(label),
+            input_index=len(candidates),
+        )
+    )
+
+
+def run_git_diff(root: Path, diff_ref: str) -> str:
+    ref = diff_ref.strip()
+    if not ref:
+        raise PackError("empty --diff")
+    command = ["git", "-C", str(root), "diff", "--no-ext-diff", "--no-textconv", "--unified=3"]
+    if ref in {"staged", "--staged", "cached", "--cached"}:
+        command.extend(["--cached"])
+    elif ref in {"worktree", "unstaged", "working-tree"}:
+        pass
+    elif ref.startswith("-"):
+        raise PackError("invalid --diff: revision must not start with '-'")
+    else:
+        command.append(ref)
+    try:
+        proc = subprocess.run(command, text=True, errors="replace", capture_output=True, timeout=10, check=False)
+    except (OSError, UnicodeError, subprocess.TimeoutExpired) as exc:
+        raise PackError(f"could not read diff: {exc.__class__.__name__}") from exc
+    if proc.returncode != 0:
+        detail = sanitize_text(proc.stderr or proc.stdout or "git diff failed")[0].strip().splitlines()
+        message = detail[0] if detail else "git diff failed"
+        raise PackError(f"could not read diff: {cap_label(message, default='git diff failed', limit=160)}")
+    return sanitize_text(proc.stdout[:MAX_SUGGEST_INPUT_BYTES])[0]
+
+
+def collect_diff_candidates(root: Path, diff_ref: str, query_terms: set[str], context_lines: int) -> list[SuggestCandidate]:
+    diff_text = run_git_diff(root, diff_ref)
+    candidates: list[SuggestCandidate] = []
+    current_path: str | None = None
+    hunk_re = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@")
+    for line in diff_text.splitlines():
+        if line.startswith("diff --git "):
+            match = re.match(r"^diff --git a/(.+?) b/(.+)$", line)
+            current_path = None
+            if match:
+                left, right = match.groups()
+                current_path = right if right != "/dev/null" else left
+            continue
+        if current_path is None:
+            continue
+        hunk = hunk_re.match(line)
+        if hunk:
+            start = int(hunk.group(1))
+            count = int(hunk.group(2) or "1")
+            end_line = max(start, start + max(1, count) - 1)
+            start_line = max(1, start - context_lines)
+            window = LineRange(start_line, max(start_line, end_line + context_lines))
+            score = 7_000 + suggest_score_path(current_path, query_terms)
+            add_suggest_candidate(
+                candidates,
+                path=current_path,
+                score=score,
+                reason="changed diff hunk",
+                lines=window,
+                label=f"diff:{safe_raw_path_label(current_path)}",
+            )
+    return candidates
+
+
+OUTPUT_PATH_RE = re.compile(
+    r"(?<![A-Za-z0-9_./-])"
+    r"(?P<path>(?:\.\/)?(?:[A-Za-z0-9_.-]+/)*[A-Za-z0-9_.-]+\."
+    r"(?:py|js|jsx|ts|tsx|mjs|cjs|md|json|yml|yaml|toml|sh|css|html|txt|rb|go|rs|java|kt|swift|c|cc|cpp|h|hpp))"
+    r"(?::(?P<line>\d+))?"
+)
+
+
+def read_text_input_under_root(root: Path, raw_path: str) -> tuple[str | None, dict[str, Any] | None]:
+    rel, reason = lexical_rel(raw_path)
+    display = safe_raw_path_label(raw_path)
+    if rel is None:
+        return None, {"path": display, "status": "omitted", "reason": reason}
+    display, redacted = display_rel_path(rel.as_posix())
+    if redacted:
+        return None, {"path": display, "status": "omitted", "reason": "redacted_path", "retrieval_omitted_reason": "redacted_path"}
+    handle, reason = open_regular_under_root(root, rel)
+    if handle is None:
+        return None, {"path": display, "status": "omitted", "reason": reason}
+    try:
+        with handle:
+            text = handle.read(MAX_SUGGEST_INPUT_BYTES + 1)
+    except (OSError, UnicodeError):
+        return None, {"path": display, "status": "omitted", "reason": "unsafe_path"}
+    if len(text.encode("utf-8", errors="replace")) > MAX_SUGGEST_INPUT_BYTES:
+        text = text[:MAX_SUGGEST_INPUT_BYTES]
+    sanitized, _redacted = sanitize_text(text)
+    return sanitized, None
+
+
+def collect_output_candidates(
+    root: Path,
+    raw_paths: list[str] | None,
+    query_terms: set[str],
+    context_lines: int,
+    *,
+    origin: str,
+) -> tuple[list[SuggestCandidate], list[dict[str, Any]]]:
+    candidates: list[SuggestCandidate] = []
+    omitted: list[dict[str, Any]] = []
+    for raw in raw_paths or []:
+        text, omission_item = read_text_input_under_root(root, raw)
+        if omission_item is not None:
+            omission_item["origin"] = origin
+            omitted.append(omission_item)
+            continue
+        assert text is not None
+        by_path: dict[str, LineRange | None] = {}
+        for match in OUTPUT_PATH_RE.finditer(text):
+            path = match.group("path")
+            if path.startswith("./"):
+                path = path[2:]
+            line_text = match.group("line")
+            if line_text:
+                try:
+                    line_number = int(line_text)
+                except ValueError:
+                    line_number = 1
+                by_path[path] = merge_line_window(by_path.get(path), line_number, context_lines)
+            else:
+                by_path.setdefault(path, None)
+        for path, lines in sorted(by_path.items()):
+            score = 5_000 + suggest_score_path(path, query_terms)
+            add_suggest_candidate(
+                candidates,
+                path=path,
+                score=score,
+                reason=f"{origin} referenced path",
+                lines=lines,
+                label=f"{origin}:{safe_raw_path_label(path)}",
+            )
+    return candidates, omitted
+
+
+def git_ls_files(root: Path) -> list[str]:
+    try:
+        proc = subprocess.run(
+            ["git", "-C", str(root), "ls-files", "-z"],
+            text=False,
+            capture_output=True,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        proc = None
+    if proc is not None and proc.returncode == 0:
+        raw = proc.stdout[: MAX_QUERY_SCAN_FILES * 512]
+        return [part.decode("utf-8", "replace") for part in raw.split(b"\0") if part][:MAX_QUERY_SCAN_FILES]
+    out: list[str] = []
+    skip_dirs = {".git", ".omx", ".context-guard", "node_modules", "dist", "build", "__pycache__"}
+    for current, dirs, files in os.walk(root):
+        dirs[:] = [name for name in dirs if name not in skip_dirs and not name.startswith(".pytest")]
+        current_path = Path(current)
+        for name in files:
+            rel = (current_path / name).relative_to(root).as_posix()
+            out.append(rel)
+            if len(out) >= MAX_QUERY_SCAN_FILES:
+                return out
+    return out
+
+
+def collect_query_candidates(root: Path, query_terms: set[str], context_lines: int) -> list[SuggestCandidate]:
+    if not query_terms:
+        return []
+    candidates: list[SuggestCandidate] = []
+    for rel_path in git_ls_files(root):
+        rel, reason = lexical_rel(rel_path)
+        if rel is None or reason:
+            continue
+        display, redacted = display_rel_path(rel.as_posix())
+        if redacted:
+            continue
+        path_score = suggest_score_path(display, query_terms)
+        handle, open_reason = open_regular_under_root(root, rel)
+        if handle is None:
+            continue
+        first_match_line: int | None = None
+        content_score = 0
+        try:
+            with handle:
+                scanned_bytes = 0
+                for index, raw_line in enumerate(handle, start=1):
+                    scanned_bytes += byte_len(raw_line)
+                    if scanned_bytes > MAX_QUERY_SCAN_BYTES_PER_FILE:
+                        break
+                    if index > SUGGEST_WHOLE_FILE_MAX_LINES and content_score == 0 and path_score == 0:
+                        break
+                    lowered = raw_line.lower()
+                    hits = sum(1 for term in query_terms if term in lowered)
+                    if hits:
+                        content_score += 250 * hits
+                        if first_match_line is None:
+                            first_match_line = index
+        except (OSError, UnicodeError):
+            _ = open_reason
+            continue
+        if path_score == 0 and content_score == 0:
+            continue
+        if first_match_line is not None:
+            lines = line_window(first_match_line, None, context_lines)
+            reason = "query matched file content"
+        else:
+            lines = None
+            reason = "query matched file path"
+        add_suggest_candidate(
+            candidates,
+            path=display,
+            score=3_000 + path_score + content_score,
+            reason=reason,
+            lines=lines,
+            label=f"query:{display}",
+        )
+    return candidates
+
+
+def source_selected_range(source: ResolvedSource) -> LineRange:
+    start = source.requested_lines.start if source.requested_lines else 1
+    return LineRange(start, start + max(len(source.selected_lines), 1) - 1)
+
+
+def resolved_block_bytes(source: ResolvedSource, *, root_arg: str) -> int:
+    included = source_selected_range(source)
+    return byte_len(render_block(source, source.selected_lines, root_arg=root_arg, status="included", included=included))
+
+
+def manifest_source_for_candidate(source: ResolvedSource, *, priority: int, label: str | None) -> dict[str, Any]:
+    item: dict[str, Any] = {"path": source.display_path, "priority": priority}
+    if label:
+        item["label"] = label
+    if source.requested_lines is not None:
+        item["lines"] = source_selected_range(source).as_dict()
+    return item
+
+
+def suggested_source_payload(source: ResolvedSource, candidate: SuggestCandidate, *, root_arg: str) -> dict[str, Any]:
+    included = source_selected_range(source)
+    payload: dict[str, Any] = {
+        "path": source.display_path,
+        "priority": candidate.score,
+        "score": candidate.score,
+        "reason": candidate.reason,
+        "lines": included.as_dict(),
+        "bytes": byte_len("".join(source.selected_lines)),
+    }
+    if candidate.label:
+        payload["label"] = candidate.label
+    retrieval, retrieval_omitted_reason = retrieval_for(root_arg, source.display_path, included, redacted_path=source.redacted_path)
+    if retrieval:
+        payload["retrieval_cli"] = retrieval
+    elif retrieval_omitted_reason:
+        payload["retrieval_omitted_reason"] = retrieval_omitted_reason
+    return payload
+
+
+def normalize_suggest_source(root: Path, candidate: SuggestCandidate) -> tuple[ResolvedSource | None, dict[str, Any] | None]:
+    spec = SourceSpec(
+        path=candidate.path,
+        priority=candidate.score,
+        lines=candidate.lines,
+        label=candidate.label,
+        input_index=candidate.input_index,
+        origin="suggest",
+    )
+    source, omitted_item = resolve_source(root, spec)
+    if omitted_item is not None:
+        omitted_item["reason"] = omitted_item.get("reason") or candidate.reason
+        omitted_item["suggest_reason"] = candidate.reason
+        return None, omitted_item
+    assert source is not None
+    if source.redacted_path:
+        return None, omission(spec, "redacted_path", path=source.display_path, redacted_path=True)
+    if spec.lines is None and source.total_lines > SUGGEST_WHOLE_FILE_MAX_LINES:
+        capped = SourceSpec(
+            path=candidate.path,
+            priority=candidate.score,
+            lines=LineRange(1, min(SUGGEST_WHOLE_FILE_MAX_LINES, source.total_lines)),
+            label=candidate.label,
+            input_index=candidate.input_index,
+            origin="suggest",
+        )
+        source, omitted_item = resolve_source(root, capped)
+        if omitted_item is not None:
+            omitted_item["suggest_reason"] = candidate.reason
+            return None, omitted_item
+        assert source is not None
+    return source, None
+
+
+def write_manifest_under_root(root: Path, raw_path: str, manifest: dict[str, Any]) -> str:
+    content = json.dumps(manifest, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+    return write_text_under_root(root, raw_path, content, "--manifest-out")
+
+
+def validate_output_path_under_root(root: Path, raw_path: str, option_name: str) -> str:
+    rel, reason = lexical_rel(raw_path)
+    if rel is None:
+        raise PackError(f"invalid {option_name}: {reason}")
+    display, redacted = display_rel_path(rel.as_posix())
+    if redacted:
+        raise PackError(f"invalid {option_name}: redacted_path")
+    parent_parts = rel.parts[:-1]
+    filename = rel.parts[-1]
+    current_fd: int | None = None
+    file_fd = -1
+    try:
+        current_fd = open_dir_no_follow(root)
+        for part in parent_parts:
+            next_fd = open_dir_no_follow(part, dir_fd=current_fd)
+            os.close(current_fd)
+            current_fd = next_fd
+        flags = os.O_WRONLY
+        if hasattr(os, "O_NOFOLLOW"):
+            flags |= os.O_NOFOLLOW
+        if hasattr(os, "O_CLOEXEC"):
+            flags |= os.O_CLOEXEC
+        if hasattr(os, "O_NONBLOCK"):
+            flags |= os.O_NONBLOCK
+        try:
+            file_fd = os.open(filename, flags, dir_fd=current_fd)
+            st = os.fstat(file_fd)
+            if not stat.S_ISREG(st.st_mode):
+                raise PackError(f"invalid {option_name}: unsafe_path")
+        except FileNotFoundError:
+            temp_fd = -1
+            temp_name = f".context-guard-pack-preflight-{os.getpid()}-{hashlib.sha256(raw_path.encode('utf-8', 'replace')).hexdigest()[:10]}"
+            try:
+                create_flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+                if hasattr(os, "O_NOFOLLOW"):
+                    create_flags |= os.O_NOFOLLOW
+                if hasattr(os, "O_CLOEXEC"):
+                    create_flags |= os.O_CLOEXEC
+                if hasattr(os, "O_NONBLOCK"):
+                    create_flags |= os.O_NONBLOCK
+                temp_fd = os.open(temp_name, create_flags, 0o600, dir_fd=current_fd)
+            except OSError as exc:
+                raise PackError(f"invalid {option_name}: {exc.strerror or exc.__class__.__name__}") from exc
+            finally:
+                if temp_fd >= 0:
+                    try:
+                        os.close(temp_fd)
+                    except OSError:
+                        pass
+                    try:
+                        os.unlink(temp_name, dir_fd=current_fd)
+                    except OSError:
+                        pass
+        except IsADirectoryError as exc:
+            raise PackError(f"invalid {option_name}: unsafe_path") from exc
+        except OSError as exc:
+            raise PackError(f"invalid {option_name}: {exc.strerror or exc.__class__.__name__}") from exc
+    except PackError:
+        raise
+    except FileNotFoundError as exc:
+        raise PackError(f"invalid {option_name}: missing") from exc
+    except OSError as exc:
+        raise PackError(f"invalid {option_name}: {exc.strerror or exc.__class__.__name__}") from exc
+    finally:
+        if file_fd >= 0:
+            try:
+                os.close(file_fd)
+            except OSError:
+                pass
+        if current_fd is not None:
+            try:
+                os.close(current_fd)
+            except OSError:
+                pass
+    return display
+
+
+def output_rel_for_collision_check(raw_path: str, option_name: str) -> Path:
+    rel, reason = lexical_rel(raw_path)
+    if rel is None:
+        raise PackError(f"invalid {option_name}: {reason}")
+    _display, redacted = display_rel_path(rel.as_posix())
+    if redacted:
+        raise PackError(f"invalid {option_name}: redacted_path")
+    return rel
+
+
+def existing_output_identity_under_root(root: Path, rel: Path) -> tuple[int, int] | None:
+    current_fd: int | None = None
+    try:
+        current_fd = open_dir_no_follow(root)
+        for part in rel.parts[:-1]:
+            next_fd = open_dir_no_follow(part, dir_fd=current_fd)
+            os.close(current_fd)
+            current_fd = next_fd
+        st = os.stat(rel.parts[-1], dir_fd=current_fd, follow_symlinks=False)
+        if not stat.S_ISREG(st.st_mode):
+            return None
+        return int(st.st_dev), int(st.st_ino)
+    except (FileNotFoundError, OSError, NotImplementedError):
+        return None
+    finally:
+        if current_fd is not None:
+            try:
+                os.close(current_fd)
+            except OSError:
+                pass
+
+
+def reject_matching_output_targets(
+    root: Path,
+    *,
+    first_rel: Path,
+    second_rel: Path,
+    second_option: str,
+    reason: str,
+) -> None:
+    first_identity = existing_output_identity_under_root(root, first_rel)
+    second_identity = existing_output_identity_under_root(root, second_rel)
+    same_existing_target = first_identity is not None and first_identity == second_identity
+    same_lexical_target = first_rel == second_rel or first_rel.as_posix().casefold() == second_rel.as_posix().casefold()
+    if same_lexical_target or same_existing_target:
+        raise PackError(f"invalid {second_option}: {reason}")
+
+
+def write_text_under_root(root: Path, raw_path: str, content: str, option_name: str) -> str:
+    rel, reason = lexical_rel(raw_path)
+    if rel is None:
+        raise PackError(f"invalid {option_name}: {reason}")
+    display, redacted = display_rel_path(rel.as_posix())
+    if redacted:
+        raise PackError(f"invalid {option_name}: redacted_path")
+    parent_parts = rel.parts[:-1]
+    filename = rel.parts[-1]
+    current_fd: int | None = None
+    file_fd = -1
+    try:
+        current_fd = open_dir_no_follow(root)
+        for part in parent_parts:
+            next_fd = open_dir_no_follow(part, dir_fd=current_fd)
+            os.close(current_fd)
+            current_fd = next_fd
+        flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+        if hasattr(os, "O_NOFOLLOW"):
+            flags |= os.O_NOFOLLOW
+        if hasattr(os, "O_CLOEXEC"):
+            flags |= os.O_CLOEXEC
+        if hasattr(os, "O_NONBLOCK"):
+            flags |= os.O_NONBLOCK
+        file_fd = os.open(filename, flags, 0o600, dir_fd=current_fd)
+        st = os.fstat(file_fd)
+        if not stat.S_ISREG(st.st_mode):
+            raise PackError(f"invalid {option_name}: unsafe_path")
+        with os.fdopen(file_fd, "w", encoding="utf-8") as handle:
+            file_fd = -1
+            handle.write(content)
+    except PackError:
+        raise
+    except FileNotFoundError as exc:
+        raise PackError(f"invalid {option_name}: missing") from exc
+    except OSError as exc:
+        raise PackError(f"invalid {option_name}: {exc.strerror or exc.__class__.__name__}") from exc
+    finally:
+        if file_fd >= 0:
+            try:
+                os.close(file_fd)
+            except OSError:
+                pass
+        if current_fd is not None:
+            try:
+                os.close(current_fd)
+            except OSError:
+                pass
+    return display
+
+
+def manifest_to_source_specs(manifest: dict[str, Any]) -> list[SourceSpec]:
+    version = manifest.get("version", VERSION)
+    if version != VERSION:
+        raise PackError(f"unsupported manifest version: {version}")
+    sources = manifest.get("sources")
+    if not isinstance(sources, list):
+        raise PackError("manifest sources must be a list")
+    specs: list[SourceSpec] = []
+    for index, item in enumerate(sources):
+        if not isinstance(item, dict):
+            raise PackError("manifest sources must be objects")
+        if "path" not in item:
+            raise PackError("manifest source missing path")
+        try:
+            lines = parse_line_range(item.get("lines"))
+        except PackError:
+            lines = LineRange(-1, -1)
+        specs.append(SourceSpec(
+            path=str(item.get("path", "")),
+            priority=bounded_int(item.get("priority"), 0, -1_000_000, 1_000_000),
+            lines=lines,
+            label=cap_label(item.get("label")),
+            input_index=index,
+            origin="auto",
+        ))
+    return specs
+
+
+def build_suggest_manifest(sources: list[dict[str, Any]]) -> dict[str, Any]:
+    manifest_sources: list[dict[str, Any]] = []
+    for item in sources:
+        source: dict[str, Any] = {"path": item["path"], "priority": item["priority"]}
+        if "label" in item:
+            source["label"] = item["label"]
+        if "lines" in item:
+            source["lines"] = item["lines"]
+        manifest_sources.append(source)
+    return {"version": VERSION, "sources": manifest_sources}
+
+
+def suggest_build_hint(root_arg: str, manifest_path: str | None, budget: int) -> tuple[str | None, str | None]:
+    safe_root = safe_root_arg_for_retrieval(root_arg)
+    if safe_root is None:
+        return None, "unsafe_root_path"
+    manifest_arg = manifest_path or "<manifest.json>"
+    command_parts = ["context-guard-pack", "build", "--root", ".", "--manifest", manifest_arg, "--budget-bytes", str(budget), "--json"]
+    command = " ".join(shlex.quote(part) for part in command_parts)
+    if safe_root in {".", ""}:
+        return command, None
+    return f"cd {shlex.quote(safe_root)} && {command}", None
+
+
+def suggest_pack(root: Path, args: argparse.Namespace, *, root_arg: str) -> tuple[dict[str, Any], int]:
+    query_text, _query_redactions = sanitize_text(args.query or "")
+    query = " ".join(query_text.split())
+    query_terms = suggest_tokens(query)
+    context_lines = bounded_int(args.context_lines, DEFAULT_SUGGEST_CONTEXT_LINES, 0, MAX_SUGGEST_CONTEXT_LINES)
+    top = bounded_int(args.top, DEFAULT_SUGGEST_TOP, 1, MAX_SUGGEST_TOP)
+    budget = bounded_int(args.budget_bytes, DEFAULT_BUDGET_BYTES, MIN_BUDGET_BYTES, MAX_BUDGET_BYTES)
+    candidates: list[SuggestCandidate] = []
+    omitted: list[dict[str, Any]] = []
+    file_inputs = split_suggest_files(args.files)
+    has_signal = bool(query or file_inputs or args.diff or args.output or args.test_output)
+    if not has_signal:
+        raise PackError("provide --query, --files, --diff, --output, or --test-output")
+
+    for raw_path in file_inputs:
+        add_suggest_candidate(
+            candidates,
+            path=raw_path,
+            score=9_000 + suggest_score_path(raw_path, query_terms),
+            reason="explicit file request",
+            label=f"file:{safe_raw_path_label(raw_path)}",
+        )
+    if args.diff:
+        candidates.extend(collect_diff_candidates(root, args.diff, query_terms, context_lines))
+    output_candidates, output_omitted = collect_output_candidates(root, args.output, query_terms, context_lines, origin="output")
+    test_candidates, test_omitted = collect_output_candidates(root, args.test_output, query_terms, context_lines, origin="test-output")
+    candidates.extend(output_candidates)
+    candidates.extend(test_candidates)
+    omitted.extend(output_omitted)
+    omitted.extend(test_omitted)
+    candidates.extend(collect_query_candidates(root, query_terms, context_lines))
+
+    candidates.sort(key=lambda item: (-item.score, item.input_index, item.path, item.lines.identity() if item.lines else "0:0"))
+    seen: set[tuple[str, str]] = set()
+    final_seen: set[tuple[str, str]] = set()
+    selected: list[dict[str, Any]] = []
+    manifest_seed: list[dict[str, Any]] = []
+    current_bytes = byte_len("# Context Pack\n\nGenerated by context-guard-pack. Token counts are estimated proxies; byte counts are observed.\n\n")
+    for candidate in candidates:
+        rel, reason = lexical_rel(candidate.path)
+        identity_path = rel.as_posix() if rel is not None else safe_raw_path_label(candidate.path)
+        identity_lines = candidate.lines.identity() if candidate.lines else "all"
+        identity = (identity_path, identity_lines)
+        if rel is not None and identity in seen:
+            display, redacted = display_rel_path(rel.as_posix())
+            duplicate_item = {
+                "path": display,
+                "status": "omitted",
+                "reason": "duplicate_source",
+                "suggest_reason": candidate.reason,
+                "priority": candidate.score,
+                "retrieval_omitted_reason": "redacted_path" if redacted else None,
+            }
+            omitted.append({key: value for key, value in duplicate_item.items() if value is not None})
+            continue
+        if rel is not None:
+            seen.add(identity)
+        source, omitted_item = normalize_suggest_source(root, candidate)
+        if omitted_item is not None:
+            omitted_item["priority"] = candidate.score
+            omitted_item["suggest_reason"] = candidate.reason
+            omitted.append({key: value for key, value in omitted_item.items() if value is not None})
+            continue
+        assert source is not None
+        final_identity = (source.display_path, source_selected_range(source).identity() if source.requested_lines is not None else "all")
+        if final_identity in final_seen:
+            omitted.append({
+                "path": source.display_path,
+                "status": "omitted",
+                "reason": "duplicate_source",
+                "suggest_reason": candidate.reason,
+                "priority": candidate.score,
+            })
+            continue
+        final_seen.add(final_identity)
+        source_bytes = resolved_block_bytes(source, root_arg=root_arg)
+        remaining = budget - current_bytes
+        if source_bytes > remaining:
+            if not selected and remaining > 0:
+                partial_lines, _partial_block, partial_range = fit_partial_lines(source, remaining, root_arg=root_arg)
+                if partial_range is not None and partial_lines:
+                    partial_spec = SourceSpec(
+                        path=candidate.path,
+                        priority=candidate.score,
+                        lines=partial_range,
+                        label=candidate.label,
+                        input_index=candidate.input_index,
+                        origin="suggest",
+                    )
+                    source, omitted_item = resolve_source(root, partial_spec)
+                    if omitted_item is not None:
+                        omitted_item["priority"] = candidate.score
+                        omitted_item["suggest_reason"] = candidate.reason
+                        omitted.append(omitted_item)
+                        continue
+                    assert source is not None
+                    source_bytes = resolved_block_bytes(source, root_arg=root_arg)
+                else:
+                    omitted.append({"path": source.display_path, "status": "omitted", "reason": "budget_exhausted", "priority": candidate.score})
+                    continue
+            else:
+                omitted.append({"path": source.display_path, "status": "omitted", "reason": "budget_exhausted", "priority": candidate.score})
+                continue
+        payload = suggested_source_payload(source, candidate, root_arg=root_arg)
+        selected.append(payload)
+        manifest_seed.append(manifest_source_for_candidate(source, priority=candidate.score, label=candidate.label))
+        current_bytes += source_bytes
+        if len(selected) >= top:
+            break
+
+    manifest = build_suggest_manifest(manifest_seed)
+    estimated_pack_bytes = current_bytes if selected else 0
+    manifest_path: str | None = None
+    if args.manifest_out:
+        manifest_path = write_manifest_under_root(root, args.manifest_out, manifest)
+    build_hint, build_hint_omitted_reason = suggest_build_hint(root_arg, manifest_path, budget)
+    payload: dict[str, Any] = {
+        "tool": TOOL_NAME,
+        "schema_version": SUGGEST_SCHEMA_VERSION,
+        "version": VERSION,
+        "mode": "suggest",
+        "root": display_root(root),
+        "query": query,
+        "budget_bytes": budget,
+        "estimated_pack_bytes": estimated_pack_bytes,
+        "token_proxy": {
+            "measurement": "estimated",
+            "method": f"chars_div_{TOKEN_PROXY_CHARS_PER_TOKEN}",
+            "estimated_pack": estimated_pack_bytes // TOKEN_PROXY_CHARS_PER_TOKEN,
+        },
+        "sources": selected,
+        "omitted_sources": sorted(omitted, key=lambda item: (str(item.get("path", "")), str(item.get("reason", "")), int(item.get("priority", 0) or 0))),
+        "manifest": manifest,
+        "manifest_path": manifest_path,
+        "build_hint": build_hint,
+        "caveats": [
+            "Deterministic local heuristics only; no model, network, embedding, or provider-cost estimate is used.",
+            "Byte and token values are pack-size proxies, not billing claims.",
+        ],
+    }
+    if build_hint_omitted_reason:
+        payload["build_hint_omitted_reason"] = build_hint_omitted_reason
+    return payload, 0
+
+
+def line_range_identity(value: object) -> str:
+    if isinstance(value, dict):
+        return f"{value.get('start')}:{value.get('end')}"
+    if value is None:
+        return "all"
+    return str(value)
+
+
+def copy_explain_fields(item: dict[str, Any], fields: tuple[str, ...]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for field in fields:
+        if field in item and item[field] is not None:
+            out[field] = copy.deepcopy(item[field])
+    return out
+
+
+def build_source_matches_exact(suggest_item: dict[str, Any], build_item: dict[str, Any]) -> bool:
+    if build_item.get("path") != suggest_item.get("path"):
+        return False
+    if build_item.get("priority") != suggest_item.get("priority"):
+        return False
+    lines = line_range_identity(suggest_item.get("lines"))
+    requested = line_range_identity(build_item.get("requested_lines"))
+    included = line_range_identity(build_item.get("included_lines"))
+    return lines in {requested, included, "all"}
+
+
+def find_exact_build_source_for_explain(
+    suggest_item: dict[str, Any],
+    build_sources: list[dict[str, Any]],
+    used_indexes: set[int],
+) -> dict[str, Any] | None:
+    for index, item in enumerate(build_sources):
+        if index in used_indexes:
+            continue
+        if build_source_matches_exact(suggest_item, item):
+            used_indexes.add(index)
+            return item
+    return None
+
+
+def find_fallback_build_source_for_explain(
+    suggest_item: dict[str, Any],
+    build_sources: list[dict[str, Any]],
+    used_indexes: set[int],
+) -> dict[str, Any] | None:
+    path = suggest_item.get("path")
+    for index, item in enumerate(build_sources):
+        if index in used_indexes or item.get("path") != path:
+            continue
+        used_indexes.add(index)
+        return item
+    return None
+
+
+def explain_omission_key(item: dict[str, Any]) -> tuple[str, str, str, str, str]:
+    return (
+        str(item.get("phase", "")),
+        str(item.get("path", "")),
+        str(item.get("reason", "")),
+        str(item.get("suggest_reason", "")),
+        json.dumps(item.get("requested_lines", item.get("lines", "")), ensure_ascii=False, sort_keys=True),
+    )
+
+
+def sanitize_explain_text(value: str, *, limit: int = MAX_LABEL_CHARS) -> str:
+    sanitized, _redacted = sanitize_text(str(value))
+    return cap_label(sanitized, default="", limit=limit) or ""
+
+
+def is_repo_map_text_path(path: str) -> bool:
+    name = Path(path).name.lower()
+    if name in {"readme", "license", "dockerfile", "makefile"}:
+        return True
+    return Path(path).suffix.lower() in REPO_MAP_TEXT_EXTENSIONS
+
+
+def read_repo_map_text(root: Path, rel_path: str) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+    rel, reason = lexical_rel(rel_path)
+    if rel is None:
+        return None, {"path": repo_map_safe_raw_path_label(rel_path), "reason": reason}
+    display, redacted_path = repo_map_display_rel_path(rel.as_posix())
+    if not is_repo_map_text_path(display):
+        return None, {"path": display, "reason": "unsupported_file_type"}
+    handle, open_reason = open_regular_under_root(root, rel)
+    if handle is None:
+        return None, {"path": display, "reason": open_reason, "retrieval_omitted_reason": "redacted_path" if redacted_path else None}
+    try:
+        with handle:
+            text = handle.read(MAX_REPO_MAP_BYTES_PER_FILE + 1)
+    except (OSError, UnicodeError):
+        return None, {"path": display, "reason": "unsafe_path", "retrieval_omitted_reason": "redacted_path" if redacted_path else None}
+    capped = byte_len(text) > MAX_REPO_MAP_BYTES_PER_FILE
+    if capped:
+        text = text.encode("utf-8", errors="replace")[:MAX_REPO_MAP_BYTES_PER_FILE].decode("utf-8", errors="ignore")
+    risk_counts = secret_risk_counts(text)
+    sanitized_text, redacted_lines = sanitize_text(text)
+    return {
+        "path": display,
+        "raw_path": rel.as_posix(),
+        "redacted_path": redacted_path,
+        "text": sanitized_text,
+        "bytes": byte_len(sanitized_text),
+        "bytes_capped": capped,
+        "line_count": len(sanitized_text.splitlines()) or (1 if sanitized_text else 0),
+        "redacted_lines": redacted_lines,
+        "secret_risk_counts": risk_counts,
+    }, None
+
+
+def repo_map_records(root: Path) -> tuple[list[dict[str, Any]], list[dict[str, Any]], dict[str, Any]]:
+    paths = git_ls_files(root)
+    path_cap_reached = len(paths) > MAX_REPO_MAP_FILES
+    records: list[dict[str, Any]] = []
+    omitted: list[dict[str, Any]] = []
+    for rel_path in paths[:MAX_REPO_MAP_FILES]:
+        record, omission_item = read_repo_map_text(root, rel_path)
+        if record is not None:
+            records.append(record)
+        elif omission_item is not None and omission_item.get("reason") != "unsupported_file_type":
+            omitted.append({key: value for key, value in omission_item.items() if value is not None})
+    caps = {
+        "max_files": MAX_REPO_MAP_FILES,
+        "files_capped": path_cap_reached,
+        "max_bytes_per_file": MAX_REPO_MAP_BYTES_PER_FILE,
+        "bytes_per_file_capped_count": sum(1 for item in records if item.get("bytes_capped")),
+        "max_tree_entries": MAX_REPO_MAP_TREE_ENTRIES,
+        "max_signature_entries": MAX_REPO_MAP_SIGNATURE_ENTRIES,
+        "max_graph_rank_entries": MAX_REPO_MAP_GRAPH_RANK_ENTRIES,
+        "max_retrieval_hints": MAX_REPO_MAP_RETRIEVAL_HINTS,
+        "max_secret_risk_files": MAX_REPO_MAP_SECRET_RISK_FILES,
+    }
+    return records, omitted, caps
+
+
+def secret_risk_counts(text: str) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for name, pattern in SECRET_RISK_PATTERNS:
+        found = len(pattern.findall(text))
+        if found:
+            counts[name] = found
+    return counts
+
+
+def build_secret_scan(records: list[dict[str, Any]]) -> dict[str, Any]:
+    risk_counts: dict[str, int] = {}
+    files: list[dict[str, Any]] = []
+    for record in records:
+        counts = dict(record.get("secret_risk_counts", {}) if isinstance(record.get("secret_risk_counts"), dict) else {})
+        if not counts:
+            continue
+        for name, count in counts.items():
+            risk_counts[name] = risk_counts.get(name, 0) + count
+        files.append({
+            "path": record["path"],
+            "counts": counts,
+            "redacted_path": bool(record.get("redacted_path")),
+        })
+    files.sort(key=lambda item: (-sum(item["counts"].values()), item["path"]))
+    return {
+        "risk_counts": dict(sorted(risk_counts.items())),
+        "files_with_risks": files[:MAX_REPO_MAP_SECRET_RISK_FILES],
+        "files_omitted_by_cap": max(0, len(files) - MAX_REPO_MAP_SECRET_RISK_FILES),
+        "caveat": "Counts are local best-effort secret-pattern risk signals; raw matched values are never emitted.",
+    }
+
+
+def build_token_tree(records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    directory_totals: dict[str, dict[str, int]] = {}
+    file_entries: list[dict[str, Any]] = []
+    for record in records:
+        path = str(record["path"])
+        bytes_count = int(record.get("bytes", 0) or 0)
+        file_entries.append({
+            "kind": "file",
+            "path": path,
+            "bytes": bytes_count,
+            "token_proxy": token_proxy(str(record.get("text", ""))),
+            "line_count": int(record.get("line_count", 0) or 0),
+            "bytes_capped": bool(record.get("bytes_capped")),
+        })
+        parts = path.split("/")
+        if len(parts) > 1:
+            prefix = ""
+            for part in parts[:-1]:
+                prefix = part if not prefix else f"{prefix}/{part}"
+                bucket = directory_totals.setdefault(prefix, {"bytes": 0, "file_count": 0})
+                bucket["bytes"] += bytes_count
+                bucket["file_count"] += 1
+    directory_entries = [
+        {
+            "kind": "directory",
+            "path": path,
+            "bytes": data["bytes"],
+            "token_proxy": max(0, round(data["bytes"] / TOKEN_PROXY_CHARS_PER_TOKEN)),
+            "file_count": data["file_count"],
+        }
+        for path, data in directory_totals.items()
+    ]
+    entries = directory_entries + file_entries
+    entries.sort(key=lambda item: (-int(item.get("bytes", 0) or 0), str(item.get("path", ""))))
+    return entries[:MAX_REPO_MAP_TREE_ENTRIES]
+
+
+def signature_range(line_number: int, total_lines: int) -> LineRange:
+    return LineRange(max(1, line_number), min(max(1, total_lines), max(1, line_number) + 24))
+
+
+def signature_entry(record: dict[str, Any], *, kind: str, name: str, raw_signature: str, line_number: int) -> dict[str, Any]:
+    total_lines = int(record.get("line_count", 0) or 1)
+    line_range = signature_range(line_number, total_lines)
+    return {
+        "path": record["path"],
+        "kind": kind,
+        "name": sanitize_explain_text(name, limit=80),
+        "signature": sanitize_explain_text(raw_signature, limit=180),
+        "line": line_number,
+        "lines": line_range.as_dict(),
+    }
+
+
+def python_signatures(record: dict[str, Any], text: str) -> list[dict[str, Any]]:
+    try:
+        module = ast.parse(text)
+    except (SyntaxError, ValueError, RecursionError):
+        return []
+    lines = text.splitlines()
+    out: list[dict[str, Any]] = []
+    for node in module.body:
+        if isinstance(node, ast.ClassDef):
+            raw = lines[node.lineno - 1].strip() if 0 < node.lineno <= len(lines) else f"class {node.name}"
+            out.append(signature_entry(record, kind="class", name=node.name, raw_signature=raw, line_number=node.lineno))
+            for child in node.body:
+                if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    raw_child = lines[child.lineno - 1].strip() if 0 < child.lineno <= len(lines) else f"def {child.name}"
+                    out.append(signature_entry(record, kind="method", name=child.name, raw_signature=raw_child, line_number=child.lineno))
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            raw = lines[node.lineno - 1].strip() if 0 < node.lineno <= len(lines) else f"def {node.name}"
+            out.append(signature_entry(record, kind="function", name=node.name, raw_signature=raw, line_number=node.lineno))
+    return out
+
+
+def regex_signatures(record: dict[str, Any], text: str) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    suffix = Path(str(record.get("path", ""))).suffix.lower()
+    for index, raw in enumerate(text.splitlines(), start=1):
+        stripped = raw.strip()
+        if suffix in {".md", ".mdx"}:
+            heading = re.match(r"^(#{1,6})\s+(.+)$", stripped)
+            if heading:
+                out.append(signature_entry(record, kind="heading", name=heading.group(2), raw_signature=stripped, line_number=index))
+            continue
+        match = SIGNATURE_LINE_RE.match(raw)
+        if not match:
+            continue
+        name = next((group for group in match.groups() if group), "signature")
+        kind = "class" if re.search(r"\bclass\s+" + re.escape(name), raw) else "function"
+        out.append(signature_entry(record, kind=kind, name=name, raw_signature=stripped, line_number=index))
+    return out
+
+
+def extract_signatures(records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    signatures: list[dict[str, Any]] = []
+    for record in records:
+        text = str(record.get("text", ""))
+        suffix = Path(str(record.get("path", ""))).suffix.lower()
+        if suffix == ".py":
+            parsed = python_signatures(record, text)
+            if parsed:
+                signatures.extend(parsed)
+                continue
+        signatures.extend(regex_signatures(record, text))
+    signatures.sort(key=lambda item: (str(item.get("path", "")), int(item.get("line", 0) or 0), str(item.get("name", ""))))
+    return signatures[:MAX_REPO_MAP_SIGNATURE_ENTRIES]
+
+
+def normalize_repo_map_candidate(path: str) -> str:
+    normalized = posixpath.normpath(path.replace("\\", "/"))
+    if normalized == ".":
+        return ""
+    return normalized.lstrip("/")
+
+
+def resolve_import_target(raw_target: str, source_path: str, known_paths: set[str]) -> str | None:
+    target = raw_target.strip()
+    if not target:
+        return None
+    candidates: list[str] = []
+    source_dir = Path(source_path).parent.as_posix()
+    if target.startswith("."):
+        if target.startswith("./") or target.startswith("../"):
+            base = normalize_repo_map_candidate(posixpath.join(source_dir, target))
+        else:
+            leading = len(target) - len(target.lstrip("."))
+            remainder = target[leading:].replace(".", "/")
+            base_dir = source_dir
+            for _ in range(max(0, leading - 1)):
+                base_dir = posixpath.dirname(base_dir)
+            base = normalize_repo_map_candidate(posixpath.join(base_dir, remainder)) if remainder else normalize_repo_map_candidate(base_dir)
+        candidates.extend([base, f"{base}.py", f"{base}.ts", f"{base}.tsx", f"{base}.js", f"{base}.jsx", f"{base}/index.ts", f"{base}/index.js"])
+    else:
+        module_path = target.replace(".", "/")
+        candidates.extend([f"{module_path}.py", f"{module_path}.ts", f"{module_path}.tsx", f"{module_path}.js", f"{module_path}.jsx", f"{module_path}/index.ts", f"{module_path}/index.js"])
+    for candidate in candidates:
+        normalized = normalize_repo_map_candidate(candidate)
+        if normalized in known_paths:
+            return normalized
+    return None
+
+
+def python_from_import_targets(module_name: str, imported_names: str) -> list[str]:
+    targets = [module_name]
+    if module_name.strip("."):
+        return targets
+    for raw_name in imported_names.replace("(", " ").replace(")", " ").split(","):
+        name = raw_name.strip().split(" as ", 1)[0].strip()
+        if not re.fullmatch(r"[A-Za-z_]\w*", name):
+            continue
+        targets.append(f"{module_name}{name}")
+    return targets
+
+
+def collect_import_edges(records: list[dict[str, Any]]) -> list[dict[str, str]]:
+    known = {str(record.get("path", "")) for record in records}
+    edges: list[dict[str, str]] = []
+    seen: set[tuple[str, str]] = set()
+    for record in records:
+        source = str(record.get("path", ""))
+        for line in str(record.get("text", "")).splitlines():
+            py_from_match = PY_FROM_IMPORT_LINE_RE.match(line)
+            if py_from_match:
+                raw_targets = python_from_import_targets(py_from_match.group("module"), py_from_match.group("names"))
+            else:
+                raw_targets = [next((value for value in match.groupdict().values() if value), "") for match in IMPORT_PATH_RE.finditer(line)]
+            for raw_target in raw_targets:
+                target = resolve_import_target(raw_target, source, known)
+                if target is None or target == source:
+                    continue
+                edge = (source, target)
+                if edge in seen:
+                    continue
+                seen.add(edge)
+                edges.append({"from": source, "to": target})
+                if len(edges) >= MAX_REPO_MAP_FILES:
+                    return edges
+    return edges
+
+
+def repo_map_seed_paths(args: argparse.Namespace, suggest_payload: dict[str, Any], build_payload: dict[str, Any]) -> set[str]:
+    seeds: set[str] = set()
+    for raw in split_suggest_files(getattr(args, "files", None)):
+        rel, _reason = lexical_rel(raw)
+        if rel is not None:
+            display, redacted = repo_map_display_rel_path(rel.as_posix())
+            if not redacted:
+                seeds.add(display)
+    for source in suggest_payload.get("sources", []):
+        if isinstance(source, dict) and isinstance(source.get("path"), str):
+            seeds.add(source["path"])
+    for source in build_payload.get("included_sources", []):
+        if isinstance(source, dict) and isinstance(source.get("path"), str):
+            seeds.add(source["path"])
+    return seeds
+
+
+def build_graph_rank(
+    records: list[dict[str, Any]],
+    signatures: list[dict[str, Any]],
+    edges: list[dict[str, str]],
+    *,
+    query_terms: set[str],
+    seed_paths: set[str],
+    secret_scan: dict[str, Any],
+) -> list[dict[str, Any]]:
+    signature_paths = {str(item.get("path", "")) for item in signatures}
+    secret_paths = {str(item.get("path", "")) for item in secret_scan.get("files_with_risks", []) if isinstance(item, dict)}
+    degree: dict[str, int] = {}
+    for edge in edges:
+        degree[edge["from"]] = degree.get(edge["from"], 0) + 1
+        degree[edge["to"]] = degree.get(edge["to"], 0) + 1
+    ranked: list[dict[str, Any]] = []
+    for record in records:
+        path = str(record.get("path", ""))
+        text = str(record.get("text", "")).lower()
+        components = {
+            "seed": 1000 if path in seed_paths else 0,
+            "query_path": suggest_score_path(path, query_terms),
+            "query_content": min(500, 25 * sum(text.count(term) for term in query_terms)),
+            "signature": 80 if path in signature_paths else 0,
+            "graph_degree": 25 * degree.get(path, 0),
+            "secret_risk_penalty": -25 if path in secret_paths else 0,
+        }
+        score = sum(components.values())
+        if score <= 0:
+            continue
+        ranked.append({
+            "path": path,
+            "score": score,
+            "components": components,
+            "explain_only": True,
+            "line_count": int(record.get("line_count", 0) or 0),
+        })
+    ranked.sort(key=lambda item: (-int(item["score"]), str(item["path"])))
+    return ranked[:MAX_REPO_MAP_GRAPH_RANK_ENTRIES]
+
+
+def repo_map_retrieval_for(root_arg: str, display_path: str, lines: LineRange, *, redacted_path: bool) -> tuple[str | None, str | None]:
+    if redacted_path:
+        return None, "redacted_path"
+    safe_root = safe_repo_map_root_arg_for_retrieval(root_arg)
+    if safe_root is None:
+        return None, "unsafe_root_path"
+    return retrieval_cli(safe_root, display_path, lines), None
+
+
+def repo_map_retrieval(
+    record_by_path: dict[str, dict[str, Any]],
+    signatures: list[dict[str, Any]],
+    graph_rank: list[dict[str, Any]],
+    *,
+    root_arg: str,
+) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    seen: set[tuple[str, str, str]] = set()
+
+    def add(path: str, line_range: LineRange, source: str, name: str | None = None) -> None:
+        record = record_by_path.get(path)
+        if record is None:
+            return
+        retrieval, reason = repo_map_retrieval_for(root_arg, path, line_range, redacted_path=bool(record.get("redacted_path")))
+        key = (path, line_range.identity(), source)
+        if key in seen:
+            return
+        seen.add(key)
+        item: dict[str, Any] = {"path": path, "source": source, "lines": line_range.as_dict()}
+        if retrieval:
+            item["slice_cli"] = retrieval
+        elif reason:
+            item["retrieval_omitted_reason"] = reason
+        if name and retrieval and Path(path).suffix.lower() in SYMBOL_HINT_EXTENSIONS:
+            item["symbol_cli"] = " ".join(shlex.quote(part) for part in ["context-guard-read-symbol", "--json", path, name])
+        out.append(item)
+
+    for signature in signatures:
+        lines = signature.get("lines")
+        if isinstance(lines, dict):
+            try:
+                line_range = LineRange(int(lines.get("start")), int(lines.get("end")))
+            except (TypeError, ValueError):
+                continue
+            add(str(signature.get("path", "")), line_range, "signature", str(signature.get("name", "")) or None)
+        if len(out) >= MAX_REPO_MAP_RETRIEVAL_HINTS:
+            return out[:MAX_REPO_MAP_RETRIEVAL_HINTS]
+    for item in graph_rank:
+        path = str(item.get("path", ""))
+        record = record_by_path.get(path)
+        if record is None:
+            continue
+        total = int(record.get("line_count", 0) or 1)
+        add(path, LineRange(1, min(total, 80)), "graph_rank")
+        if len(out) >= MAX_REPO_MAP_RETRIEVAL_HINTS:
+            break
+    return out[:MAX_REPO_MAP_RETRIEVAL_HINTS]
+
+
+def build_repo_map_payload(
+    root: Path,
+    args: argparse.Namespace,
+    suggest_payload: dict[str, Any],
+    build_payload: dict[str, Any],
+    *,
+    root_arg: str,
+) -> dict[str, Any]:
+    records, omitted, caps = repo_map_records(root)
+    record_by_path = {str(record["path"]): record for record in records}
+    signatures = extract_signatures(records)
+    secret_scan = build_secret_scan(records)
+    edges = collect_import_edges(records)
+    query_terms = suggest_tokens(str(suggest_payload.get("query", "")))
+    graph_rank = build_graph_rank(
+        records,
+        signatures,
+        edges,
+        query_terms=query_terms,
+        seed_paths=repo_map_seed_paths(args, suggest_payload, build_payload),
+        secret_scan=secret_scan,
+    )
+    retrieval = repo_map_retrieval(record_by_path, signatures, graph_rank, root_arg=root_arg)
+    tree = build_token_tree(records)
+    total_bytes = sum(int(record.get("bytes", 0) or 0) for record in records)
+    return {
+        "schema_version": REPO_MAP_SCHEMA_VERSION,
+        "summary": {
+            "files_scanned": len(records),
+            "files_capped": bool(caps["files_capped"]),
+            "bytes_per_file_capped_count": int(caps["bytes_per_file_capped_count"]),
+            "tree_bytes": total_bytes,
+            "tree_token_proxy": sum(int(item.get("token_proxy", 0) or 0) for item in tree),
+            "signature_files": len({str(item.get("path", "")) for item in signatures}),
+            "signature_count": len(signatures),
+            "secret_risk_files": len(secret_scan.get("files_with_risks", [])),
+            "graph_edges": len(edges),
+        },
+        "caps": caps,
+        "token_tree": tree,
+        "secret_scan": secret_scan,
+        "signature_index": signatures,
+        "graph": {
+            "edges": edges[:MAX_REPO_MAP_GRAPH_RANK_ENTRIES],
+            "edges_omitted_by_cap": max(0, len(edges) - MAX_REPO_MAP_GRAPH_RANK_ENTRIES),
+        },
+        "graph_rank": graph_rank,
+        "retrieval": retrieval,
+        "omitted_files": omitted[:MAX_REPO_MAP_TREE_ENTRIES],
+        "safety": {
+            "deterministic_local_only": True,
+            "no_network": True,
+            "no_model_or_embedding": True,
+            "explain_only": True,
+            "redacted_before_output": True,
+            "tree_sitter": {"status": "unavailable_without_optional_dependency", "fallback": "python_ast_and_regex_signatures"},
+            "caveats": [
+                "Repo-map bytes are local sampled UTF-8 bytes and estimated chars_div_4 token proxies, not provider-token or savings claims.",
+                "Graph ranking is deterministic explain metadata only; it does not change pack selection in this stage.",
+            ],
+        },
+    }
+
+
+def build_auto_explain_payload(
+    args: argparse.Namespace,
+    suggest_payload: dict[str, Any],
+    build_payload: dict[str, Any],
+    payload: dict[str, Any],
+    *,
+    root: Path | None = None,
+    root_arg: str = ".",
+) -> dict[str, Any]:
+    build_sources = [
+        item
+        for item in build_payload.get("included_sources", [])
+        if isinstance(item, dict)
+    ]
+    used_build_indexes: set[int] = set()
+    suggest_sources = [
+        item
+        for item in suggest_payload.get("sources", [])
+        if isinstance(item, dict)
+    ]
+    exact_matches: dict[int, dict[str, Any]] = {}
+    for index, item in enumerate(suggest_sources):
+        build_item = find_exact_build_source_for_explain(item, build_sources, used_build_indexes)
+        if build_item is not None:
+            exact_matches[index] = build_item
+
+    selection: list[dict[str, Any]] = []
+    for index, item in enumerate(suggest_sources):
+        entry = copy_explain_fields(
+            item,
+            ("path", "score", "priority", "reason", "label", "lines", "bytes", "retrieval_cli", "retrieval_omitted_reason"),
+        )
+        build_item = exact_matches.get(index)
+        if build_item is None:
+            build_item = find_fallback_build_source_for_explain(item, build_sources, used_build_indexes)
+        if build_item is not None:
+            entry["build_status"] = build_item.get("status", "included")
+            for key in ("requested_lines", "included_lines"):
+                if key in build_item:
+                    entry[key] = copy.deepcopy(build_item[key])
+            if "bytes" in build_item:
+                entry["build_bytes"] = build_item["bytes"]
+        else:
+            entry["build_status"] = "not_built"
+        selection.append(entry)
+
+    omissions: list[dict[str, Any]] = []
+    seen_omissions: set[tuple[str, str, str, str, str]] = set()
+    omission_fields = (
+        "path",
+        "status",
+        "reason",
+        "suggest_reason",
+        "priority",
+        "label",
+        "requested_lines",
+        "included_lines",
+        "lines",
+        "total_lines",
+        "retrieval_cli",
+        "retrieval_omitted_reason",
+        "input_index",
+    )
+    for phase, source in (("suggest", suggest_payload), ("build", build_payload)):
+        for item in source.get("omitted_sources", []):
+            if not isinstance(item, dict):
+                continue
+            entry = copy_explain_fields(item, omission_fields)
+            entry["phase"] = phase
+            key = explain_omission_key(entry)
+            if key in seen_omissions:
+                continue
+            seen_omissions.add(key)
+            omissions.append(entry)
+    omissions.sort(key=explain_omission_key)
+
+    build_source_counts = build_payload.get("sources", {}) if isinstance(build_payload.get("sources"), dict) else {}
+    auto_source_counts = payload.get("sources", {}) if isinstance(payload.get("sources"), dict) else {}
+    artifact = build_payload.get("artifact", {}) if isinstance(build_payload.get("artifact"), dict) else {}
+    pack_bytes = int(payload.get("pack_bytes", build_payload.get("pack_bytes", 0)) or 0)
+    budget_bytes = int(payload.get("budget_bytes", build_payload.get("budget_bytes", 0)) or 0)
+    budget_omitted_count = sum(1 for item in omissions if item.get("reason") == "budget_exhausted")
+    explicit_files = split_suggest_files(args.files)
+    query = str(suggest_payload.get("query", ""))
+    diff_label = cap_label(args.diff) if getattr(args, "diff", None) else None
+    explain = {
+        "schema_version": AUTO_EXPLAIN_SCHEMA_VERSION,
+        "summary": {
+            "suggested": int(auto_source_counts.get("suggested", len(selection)) or 0),
+            "included": int(auto_source_counts.get("included", build_source_counts.get("included", 0)) or 0),
+            "partial": int(auto_source_counts.get("partial", build_source_counts.get("partial", 0)) or 0),
+            "omitted": int(auto_source_counts.get("omitted", build_source_counts.get("omitted", 0)) or 0),
+            "suggest_omitted": len([item for item in suggest_payload.get("omitted_sources", []) if isinstance(item, dict)]),
+            "explain_omissions": len(omissions),
+            "pack_bytes": pack_bytes,
+            "budget_bytes": budget_bytes,
+            "manifest_written": bool(payload.get("manifest_path")),
+            "pack_written": bool(payload.get("pack_path")),
+            "artifact_stored": bool(artifact.get("stored")),
+            "artifact_capped": bool(artifact.get("capped")),
+        },
+        "inputs": {
+            "query": query,
+            "query_present": bool(query),
+            "diff": diff_label,
+            "diff_present": bool(diff_label),
+            "explicit_file_count": len(explicit_files),
+            "output_count": len(args.output or []),
+            "test_output_count": len(args.test_output or []),
+            "top": bounded_int(args.top, DEFAULT_SUGGEST_TOP, 1, MAX_SUGGEST_TOP),
+            "context_lines": bounded_int(args.context_lines, DEFAULT_SUGGEST_CONTEXT_LINES, 0, MAX_SUGGEST_CONTEXT_LINES),
+            "no_artifact": bool(args.no_artifact),
+            "manifest_path": payload.get("manifest_path"),
+            "pack_path": payload.get("pack_path"),
+        },
+        "selection": selection,
+        "omissions": omissions,
+        "budget": {
+            "pack_bytes": pack_bytes,
+            "budget_bytes": budget_bytes,
+            "remaining_bytes": budget_bytes - pack_bytes,
+            "partial_count": int(build_source_counts.get("partial", 0) or 0),
+            "budget_omitted_count": budget_omitted_count,
+            "token_proxy": copy.deepcopy(payload.get("token_proxy", {})),
+            "measurement": "observed_bytes_estimated_tokens",
+            "caveat": "Byte counts are observed pack bytes; token counts are estimated chars_div_4 proxies, not provider-token savings.",
+        },
+        "safety": {
+            "redaction": copy.deepcopy(build_payload.get("redaction", {})),
+            "caveats": copy.deepcopy(payload.get("caveats", [])),
+            "deterministic_local_only": True,
+            "raw_output_embedded": False,
+            "raw_test_output_embedded": False,
+        },
+    }
+    if root is not None:
+        explain["repo_map"] = build_repo_map_payload(root, args, suggest_payload, build_payload, root_arg=root_arg)
+    return explain
+
+
+def auto_pack(root: Path, args: argparse.Namespace, *, root_arg: str) -> tuple[dict[str, Any], int]:
+    manifest_rel = output_rel_for_collision_check(args.manifest_out, "--manifest-out") if args.manifest_out else None
+    pack_rel = output_rel_for_collision_check(args.pack_out, "--pack-out") if args.pack_out else None
+    if manifest_rel is not None and pack_rel is not None:
+        reject_matching_output_targets(
+            root,
+            first_rel=manifest_rel,
+            second_rel=pack_rel,
+            second_option="--pack-out",
+            reason="same_as_manifest_out",
+        )
+    if args.manifest_out:
+        validate_output_path_under_root(root, args.manifest_out, "--manifest-out")
+    if args.pack_out:
+        validate_output_path_under_root(root, args.pack_out, "--pack-out")
+    suggest_args = copy.copy(args)
+    suggest_args.manifest_out = None
+    suggest_payload, rc = suggest_pack(root, suggest_args, root_arg=root_arg)
+    manifest = suggest_payload["manifest"]
+    specs = manifest_to_source_specs(manifest)
+    budget = bounded_int(args.budget_bytes, DEFAULT_BUDGET_BYTES, MIN_BUDGET_BYTES, MAX_BUDGET_BYTES)
+    build_payload = build_pack(root, specs, budget_bytes=budget, root_arg=root_arg, store_artifact=False)
+    if not args.no_artifact:
+        receipt_rel = Path(PACK_DIR) / f"{build_payload['pack_id']}.json"
+        if manifest_rel is not None:
+            reject_matching_output_targets(
+                root,
+                first_rel=receipt_rel,
+                second_rel=manifest_rel,
+                second_option="--manifest-out",
+                reason="same_as_artifact_receipt",
+            )
+        if pack_rel is not None:
+            reject_matching_output_targets(
+                root,
+                first_rel=receipt_rel,
+                second_rel=pack_rel,
+                second_option="--pack-out",
+                reason="same_as_artifact_receipt",
+            )
+    manifest_path: str | None = None
+    pack_path: str | None = None
+    if args.pack_out:
+        pack_path = write_text_under_root(root, args.pack_out, str(build_payload["pack"]), "--pack-out")
+    if args.manifest_out:
+        manifest_path = write_manifest_under_root(root, args.manifest_out, manifest)
+    if not args.no_artifact:
+        build_payload["artifact"] = store_receipt(root, build_payload)
+    build_hint, build_hint_omitted_reason = suggest_build_hint(root_arg, manifest_path, budget)
+    suggest_payload["manifest_path"] = manifest_path
+    suggest_payload["build_hint"] = build_hint
+    suggest_payload.pop("build_hint_omitted_reason", None)
+    if build_hint_omitted_reason:
+        suggest_payload["build_hint_omitted_reason"] = build_hint_omitted_reason
+    payload: dict[str, Any] = {
+        "tool": TOOL_NAME,
+        "schema_version": AUTO_SCHEMA_VERSION,
+        "version": VERSION,
+        "mode": "auto",
+        "root": display_root(root),
+        "query": suggest_payload.get("query", ""),
+        "budget_bytes": budget,
+        "manifest": manifest,
+        "manifest_path": manifest_path,
+        "pack_path": pack_path,
+        "suggest": suggest_payload,
+        "build": build_payload,
+        "sources": {
+            "suggested": len(suggest_payload.get("sources", [])),
+            "included": build_payload.get("sources", {}).get("included", 0),
+            "partial": build_payload.get("sources", {}).get("partial", 0),
+            "omitted": build_payload.get("sources", {}).get("omitted", 0),
+        },
+        "pack_bytes": build_payload.get("pack_bytes", 0),
+        "token_proxy": build_payload.get("token_proxy", {}),
+        "caveats": [
+            "Deterministic local heuristics only; no model, network, embedding, or provider-cost estimate is used.",
+            "Byte and token values are pack-size proxies, not billing claims.",
+        ],
+    }
+    if build_hint_omitted_reason:
+        payload["build_hint_omitted_reason"] = build_hint_omitted_reason
+    if args.explain:
+        payload["explain"] = build_auto_explain_payload(args, suggest_payload, build_payload, payload, root=root, root_arg=root_arg)
+    return payload, rc
+
+
+def print_suggest_text(payload: dict[str, Any]) -> None:
+    print(
+        f"context-guard-pack suggest: {len(payload['sources'])} source(s), "
+        f"estimated {payload['estimated_pack_bytes']}/{payload['budget_bytes']} bytes"
+    )
+    for item in payload["sources"]:
+        lines = item.get("lines")
+        line_text = f":{lines['start']}:{lines['end']}" if isinstance(lines, dict) else ""
+        print(f"- {item['path']}{line_text} priority={item['priority']} reason={item['reason']}")
+    if payload.get("manifest_path"):
+        print(f"manifest: {payload['manifest_path']}")
+    if payload.get("build_hint"):
+        print(f"build: {payload['build_hint']}")
+    elif payload.get("build_hint_omitted_reason"):
+        print(f"build hint omitted: {payload['build_hint_omitted_reason']}")
+
+
+def print_auto_text(payload: dict[str, Any]) -> None:
+    print(
+        f"context-guard-pack auto: {payload['sources']['suggested']} suggested source(s), "
+        f"pack {payload['pack_bytes']}/{payload['budget_bytes']} bytes"
+    )
+    explain = payload.get("explain")
+    if isinstance(explain, dict):
+        summary = explain.get("summary", {}) if isinstance(explain.get("summary"), dict) else {}
+        budget = explain.get("budget", {}) if isinstance(explain.get("budget"), dict) else {}
+        print(
+            "explain: "
+            f"selected={summary.get('suggested', 0)} "
+            f"included={summary.get('included', 0)} "
+            f"partial={summary.get('partial', 0)} "
+            f"omitted={summary.get('omitted', 0)} "
+            f"budget={budget.get('pack_bytes', payload.get('pack_bytes', 0))}/{budget.get('budget_bytes', payload.get('budget_bytes', 0))} "
+            "heuristic=local"
+        )
+        for item in (explain.get("selection", []) if isinstance(explain.get("selection"), list) else [])[:5]:
+            if not isinstance(item, dict):
+                continue
+            lines = item.get("included_lines") or item.get("lines")
+            if isinstance(lines, dict):
+                line_text = f":{lines.get('start')}:{lines.get('end')}"
+            else:
+                line_text = ""
+            print(
+                f"- {item.get('path')}{line_text} "
+                f"status={item.get('build_status', 'unknown')} "
+                f"score={item.get('score', item.get('priority', 0))} "
+                f"reason={item.get('reason', 'local heuristic')}"
+            )
+        omissions = explain.get("omissions", []) if isinstance(explain.get("omissions"), list) else []
+        if omissions:
+            reason_counts: dict[str, int] = {}
+            for item in omissions:
+                if not isinstance(item, dict):
+                    continue
+                reason = str(item.get("reason", "unknown"))
+                reason_counts[reason] = reason_counts.get(reason, 0) + 1
+            reason_text = ", ".join(f"{reason}={count}" for reason, count in sorted(reason_counts.items()))
+            print(f"omitted reasons: {reason_text}")
+    if payload.get("manifest_path"):
+        print(f"manifest: {payload['manifest_path']}")
+    if payload.get("pack_path"):
+        print(f"pack: {payload['pack_path']}")
+    else:
+        print()
+        sys.stdout.write(str(payload["build"]["pack"]))
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Build budgeted local context packs with exact retrieval hints.")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -881,6 +2530,33 @@ def build_parser() -> argparse.ArgumentParser:
     slice_cmd.add_argument("--path", required=True, help="relative file path under root")
     slice_cmd.add_argument("--lines", required=True, help="inclusive 1-indexed START:END")
     slice_cmd.add_argument("--json", action="store_true", help="emit JSON payload")
+    suggest = sub.add_parser("suggest", help="suggest a build-compatible context pack manifest from local signals")
+    suggest.add_argument("--root", default=".", help="project root; must not be a symlink")
+    suggest.add_argument("--query", default="", help="task or question to match against local files")
+    suggest.add_argument("--diff", help="git diff range, or staged/worktree, to seed changed-file ranges")
+    suggest.add_argument("--files", "--file", dest="files", action="append", help="explicit relative file path(s), comma-separated or repeated")
+    suggest.add_argument("--output", action="append", help="relative path to sanitized command output text under root")
+    suggest.add_argument("--test-output", action="append", help="relative path to sanitized test output text under root")
+    suggest.add_argument("--budget-bytes", type=int, default=DEFAULT_BUDGET_BYTES)
+    suggest.add_argument("--top", type=int, default=DEFAULT_SUGGEST_TOP, help="maximum suggested sources")
+    suggest.add_argument("--context-lines", type=int, default=DEFAULT_SUGGEST_CONTEXT_LINES, help="line context around diff/output hits")
+    suggest.add_argument("--manifest-out", help="write the suggested build manifest to this relative path under root")
+    suggest.add_argument("--json", action="store_true", help="emit JSON payload")
+    auto = sub.add_parser("auto", help="suggest a context pack manifest and build the budgeted pack in one local step")
+    auto.add_argument("--root", default=".", help="project root; must not be a symlink")
+    auto.add_argument("--query", default="", help="task or question to match against local files")
+    auto.add_argument("--diff", help="git diff range, or staged/worktree, to seed changed-file ranges")
+    auto.add_argument("--files", "--file", dest="files", action="append", help="explicit relative file path(s), comma-separated or repeated")
+    auto.add_argument("--output", action="append", help="relative path to sanitized command output text under root")
+    auto.add_argument("--test-output", action="append", help="relative path to sanitized test output text under root")
+    auto.add_argument("--budget-bytes", type=int, default=DEFAULT_BUDGET_BYTES)
+    auto.add_argument("--top", type=int, default=DEFAULT_SUGGEST_TOP, help="maximum suggested sources")
+    auto.add_argument("--context-lines", type=int, default=DEFAULT_SUGGEST_CONTEXT_LINES, help="line context around diff/output hits")
+    auto.add_argument("--manifest-out", help="write the suggested build manifest to this relative path under root")
+    auto.add_argument("--pack-out", help="write the built Markdown pack to this relative path under root")
+    auto.add_argument("--json", action="store_true", help="emit JSON payload")
+    auto.add_argument("--no-artifact", action="store_true", help="do not write .context-guard/packs receipt")
+    auto.add_argument("--explain", action="store_true", help="include deterministic local selection/build explanation metadata")
     return parser
 
 
@@ -919,6 +2595,22 @@ def main(argv: list[str] | None = None) -> int:
             else:
                 print(f"context-guard-pack: {payload.get('reason')}", file=sys.stderr)
             return rc
+        if args.command == "suggest":
+            payload, rc = suggest_pack(root, args, root_arg=str(args.root))
+            if args.json:
+                json.dump(payload, sys.stdout, ensure_ascii=False, indent=2, sort_keys=True)
+                sys.stdout.write("\n")
+            else:
+                print_suggest_text(payload)
+            return rc
+        if args.command == "auto":
+            payload, rc = auto_pack(root, args, root_arg=str(args.root))
+            if args.json:
+                json.dump(payload, sys.stdout, ensure_ascii=False, indent=2, sort_keys=True)
+                sys.stdout.write("\n")
+            else:
+                print_auto_text(payload)
+            return rc
         raise PackError("unknown command")
     except PackError as exc:
         print(f"context-guard-pack: {exc}", file=sys.stderr)