gitwise-cli 0.29.0__tar.gz → 0.30.0__tar.gz

{gitwise_cli-0.29.0 → gitwise_cli-0.30.0}/CHANGELOG.md

@@ -3,6 +3,12 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.30.0 (2026-06-19)
+
+### Feat
+
+- **diff**: support refs, path scope, and summary (Sprint 2 PR-A) (#66)
+
 ## v0.29.0 (2026-06-19)
 
 ### Feat

{gitwise_cli-0.29.0 → gitwise_cli-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitwise-cli
-Version: 0.29.0
+Version: 0.30.0
 Summary: Python CLI for optimizing git workflows and Claude Code integration
 Project-URL: Homepage, https://github.com/drzioner/gitwise
 Project-URL: Repository, https://github.com/drzioner/gitwise

{gitwise_cli-0.29.0 → gitwise_cli-0.30.0}/gitwise/__init__.py

@@ -1,7 +1,10 @@
-__version__ = "0.29.0"
+"""gitwise -- CLI for optimizing git workflows and coding-agent integration."""
+
+__version__ = "0.30.0"
 
 
 def get_version() -> str:
+    """Return the installed package version, falling back to the source version."""
     from importlib.metadata import PackageNotFoundError
     from importlib.metadata import version as _version
 

{gitwise_cli-0.29.0 → gitwise_cli-0.30.0}/gitwise/__main__.py

@@ -11,16 +11,19 @@ from .output import print_dim, print_json, set_json_mode, set_json_pretty
 
 
 def _is_log_json_enabled() -> bool:
+    """Return True when GITWISE_LOG_JSON is set to a truthy value."""
     import os
 
     return os.environ.get("GITWISE_LOG_JSON", "").lower() in ("1", "true")
 
 
 def _should_show_rich_traceback() -> bool:
+    """Return True when rich tracebacks should be used (tty and not in JSON log mode)."""
     return (not _is_log_json_enabled()) and sys.stderr.isatty()
 
 
 def _install_rich_traceback() -> None:
+    """Install the rich traceback handler if conditions allow; no-op otherwise."""
     if not _should_show_rich_traceback():
         return
     try:
@@ -56,6 +59,7 @@ def _ensure_utf8_stdio() -> None:
 
 
 def main() -> int:
+    """Parse args, dispatch to the matching subcommand handler, and return an exit code."""
     import os
 
     from ._runtime_config import reset_runtime_config

{gitwise_cli-0.29.0 → gitwise_cli-0.30.0}/gitwise/_cli_completions.py

@@ -7,6 +7,7 @@ from ._cli_parser import build_parser
 
 
 def build_completions_script(*, shell: str, prog: str) -> str:
+    """Return a shell completion script for the given shell and program name."""
     parser = build_parser()
     parser.prog = prog
 
@@ -23,10 +24,12 @@ def build_completions_script(*, shell: str, prog: str) -> str:
 
 
 def _fish_escape(text: str) -> str:
+    """Escape single quotes for use inside a fish completion string literal."""
     return text.replace("'", "\\'")
 
 
 def _build_fish_option_line(*, prog: str, condition: str, flag: str, help_text: str) -> str:
+    """Return a single fish ``complete`` line for an option, or an empty string for unrecognized flags."""
     escaped_help = _fish_escape(help_text)
     escaped_prog = _fish_escape(prog)
     escaped_condition = _fish_escape(condition)
@@ -44,6 +47,7 @@ def _build_fish_option_line(*, prog: str, condition: str, flag: str, help_text:
 
 
 def _build_fish_completions_script(*, parser: argparse.ArgumentParser, prog: str) -> str:
+    """Generate a fish completion script from the full argparse parser tree."""
     escaped_prog = _fish_escape(prog)
     lines: list[str] = [f"# fish completion for {escaped_prog}"]
 

{gitwise_cli-0.29.0 → gitwise_cli-0.30.0}/gitwise/_cli_dispatch.py

@@ -1,6 +1,7 @@
 """Command dispatchers: thin wrappers that delegate to subcommand modules."""
 
 import argparse
+import sys
 from collections.abc import Callable
 
 from . import __version__
@@ -17,18 +18,21 @@ from .utils.json_envelope import error_envelope
 
 
 def _run_update(args: argparse.Namespace) -> int:
+    """Dispatch to ``update`` subcommand."""
     from .update import run_update
 
     return run_update(dry_run=args.dry_run, as_json=args.json)
 
 
 def _run_doctor(args: argparse.Namespace) -> int:
+    """Dispatch to ``doctor`` subcommand."""
     from .doctor import run_doctor
 
     return run_doctor(as_json=args.json)
 
 
 def _run_setup_agents(args: argparse.Namespace) -> int:
+    """Dispatch to ``setup-agents`` subcommand, handling provider listing."""
     if getattr(args, "list_providers", False) or getattr(args, "list_adapters", False):
         from .i18n import t as _t
         from .setup_agents.providers import list_providers
@@ -68,6 +72,7 @@ def _run_setup_agents(args: argparse.Namespace) -> int:
 
 
 def _run_setup(args: argparse.Namespace) -> int:
+    """Dispatch to ``setup`` subcommand."""
     from .setup import run_setup
 
     return run_setup(
@@ -79,24 +84,28 @@ def _run_setup(args: argparse.Namespace) -> int:
 
 
 def _run_audit(args: argparse.Namespace) -> int:
+    """Dispatch to ``audit`` subcommand."""
     from .audit import run_audit
 
     return run_audit(quick=args.quick, as_json=args.json)
 
 
 def _run_summarize(args: argparse.Namespace) -> int:
+    """Dispatch to ``summarize`` subcommand."""
     from .summarize import run_summarize
 
     return run_summarize(as_json=args.json, diff=args.diff, max_commits=args.max_commits)
 
 
 def _run_snapshot(args: argparse.Namespace) -> int:
+    """Dispatch to ``snapshot`` subcommand."""
     from .snapshot import run_snapshot
 
     return run_snapshot(as_json=args.json)
 
 
 def _run_clean(args: argparse.Namespace) -> int:
+    """Dispatch to ``clean`` subcommand."""
     from .clean import run_clean
 
     return run_clean(
@@ -109,12 +118,14 @@ def _run_clean(args: argparse.Namespace) -> int:
 
 
 def _run_optimize(args: argparse.Namespace) -> int:
+    """Dispatch to ``optimize`` subcommand."""
     from .optimize import run_optimize
 
     return run_optimize(dry_run=args.dry_run, yes=args.yes, as_json=args.json)
 
 
 def _run_worktree(args: argparse.Namespace) -> int:
+    """Dispatch to ``worktree`` subcommand."""
     from .worktree import run_worktree
 
     return run_worktree(
@@ -122,19 +133,72 @@ def _run_worktree(args: argparse.Namespace) -> int:
     )
 
 
+def _recover_diff_pathspec_boundary() -> tuple[str | None, list[str] | None]:
+    """Recover the explicit ``--`` pathspec boundary argparse loses.
+
+    With ``refspec nargs="?"`` + ``paths nargs="*"``, a path-only invocation
+    like ``gitwise diff -- src/`` mis-assigns ``src/`` to ``refspec``. git
+    treats ``--`` as a hard pathspec separator, so honor it here: anything
+    positional before ``--`` (excluding flags) feeds ``refspec``; anything
+    after ``--`` is literal paths, even values starting with ``-``.
+
+    Raises ``ValueError`` when more than one positional precedes ``--``, since
+    ``gitwise diff`` accepts a single refspec (two-commit diffs use ``a..b``);
+    failing fast beats silently dropping the extras.
+    """
+    try:
+        sub_idx = sys.argv.index("diff")
+    except ValueError:
+        return None, None
+    cmd_argv = sys.argv[sub_idx + 1 :]
+    if "--" not in cmd_argv:
+        return None, None
+    sep = cmd_argv.index("--")
+    before = [a for a in cmd_argv[:sep] if not a.startswith("-")]
+    after = list(cmd_argv[sep + 1 :])
+    if len(before) > 1:
+        raise ValueError(t("diff_too_many_refs", count=str(len(before))))
+    refspec = before[0] if before else None
+    paths = after if after else None
+    return refspec, paths
+
+
 def _run_diff(args: argparse.Namespace) -> int:
+    """Dispatch to ``diff`` subcommand."""
     from .diff import run_diff
+    from .output import error as error_out
+
+    refspec = args.refspec
+    paths = args.paths
+    # Honor `--` as a pathspec separator (git semantics). argparse's nargs="?"
+    # + nargs="*" otherwise mis-assigns path-only invocations to refspec.
+    if "--" in sys.argv:
+        try:
+            recovered_refspec, recovered_paths = _recover_diff_pathspec_boundary()
+        except ValueError as exc:
+            if args.json:
+                print_json(error_envelope(error=str(exc), code="too_many_refs"))
+            else:
+                error_out(str(exc))
+            return 1
+        if recovered_refspec is not None or recovered_paths is not None:
+            refspec = recovered_refspec
+            paths = recovered_paths
 
     return run_diff(
+        refspec=refspec,
+        paths=paths,
         staged=args.staged,
         stat=args.stat,
         name_only=args.name_only,
         full=args.full,
+        summary=args.summary,
         as_json=args.json,
     )
 
 
 def _run_log(args: argparse.Namespace) -> int:
+    """Dispatch to ``log`` subcommand."""
     from .log import run_log
 
     return run_log(
@@ -151,12 +215,14 @@ def _run_log(args: argparse.Namespace) -> int:
 
 
 def _run_show(args: argparse.Namespace) -> int:
+    """Dispatch to ``show`` subcommand."""
     from .show import run_show
 
     return run_show(ref=args.ref, stat=args.stat, as_json=args.json)
 
 
 def _run_commit(args: argparse.Namespace) -> int:
+    """Dispatch to ``commit`` subcommand."""
     from .commit import run_commit
 
     return run_commit(
@@ -171,12 +237,14 @@ def _run_commit(args: argparse.Namespace) -> int:
 
 
 def _run_branches(args: argparse.Namespace) -> int:
+    """Dispatch to ``branches`` subcommand."""
     from .branches import run_branches
 
     return run_branches(stale=args.stale, remote=args.remote, sort=args.sort, as_json=args.json)
 
 
 def _run_sync(args: argparse.Namespace) -> int:
+    """Dispatch to ``sync`` subcommand."""
     from .sync import run_sync
 
     return run_sync(
@@ -189,12 +257,14 @@ def _run_sync(args: argparse.Namespace) -> int:
 
 
 def _run_pr(args: argparse.Namespace) -> int:
+    """Dispatch to ``pr`` subcommand."""
     from .pr import run_pr
 
     return run_pr(action=args.action, selector=args.selector, as_json=args.json)
 
 
 def _run_undo(args: argparse.Namespace) -> int:
+    """Dispatch to ``undo`` subcommand."""
     from .undo import run_undo
 
     return run_undo(
@@ -208,18 +278,21 @@ def _run_undo(args: argparse.Namespace) -> int:
 
 
 def _run_context(args: argparse.Namespace) -> int:
+    """Dispatch to ``context`` subcommand."""
     from .context import run_context
 
     return run_context(as_json=args.json)
 
 
 def _run_health(args: argparse.Namespace) -> int:
+    """Dispatch to ``health`` subcommand."""
     from .health import run_health
 
     return run_health(as_json=args.json)
 
 
 def _run_stash(args: argparse.Namespace) -> int:
+    """Dispatch to ``stash`` subcommand."""
     from .stash import run_stash
 
     return run_stash(
@@ -233,6 +306,7 @@ def _run_stash(args: argparse.Namespace) -> int:
 
 
 def _run_tag(args: argparse.Namespace) -> int:
+    """Dispatch to ``tag`` subcommand."""
     from .tag import run_tag
 
     return run_tag(
@@ -247,6 +321,7 @@ def _run_tag(args: argparse.Namespace) -> int:
 
 
 def _run_merge(args: argparse.Namespace) -> int:
+    """Dispatch to ``merge`` subcommand."""
     from .merge import run_merge
 
     return run_merge(
@@ -262,18 +337,21 @@ def _run_merge(args: argparse.Namespace) -> int:
 
 
 def _run_conflicts(args: argparse.Namespace) -> int:
+    """Dispatch to ``conflicts`` subcommand."""
     from .conflicts import run_conflicts
 
     return run_conflicts(ours=args.ours, theirs=args.theirs, as_json=args.json)
 
 
 def _run_suggest(args: argparse.Namespace) -> int:
+    """Dispatch to ``suggest`` subcommand."""
     from .suggest import run_suggest
 
     return run_suggest(as_json=args.json)
 
 
 def _run_pick(args: argparse.Namespace) -> int:
+    """Dispatch to ``pick`` / ``cherry-pick`` subcommand."""
     from .pick import run_pick
 
     return run_pick(
@@ -287,12 +365,18 @@ def _run_pick(args: argparse.Namespace) -> int:
 
 
 def _run_status(args: argparse.Namespace) -> int:
+    """Dispatch to ``status`` subcommand."""
     from .status import run_status
 
     return run_status(as_json=args.json)
 
 
 def _run_completions(args: argparse.Namespace) -> int:
+    """Generate and output a shell completions script.
+
+    Returns 1 on missing dependency (shtab), unsupported shell, or
+    runtime error.
+    """
     shell = args.shell
     prog = args.prog
     try:
@@ -346,6 +430,7 @@ def _run_completions(args: argparse.Namespace) -> int:
 
 
 def _run_commands(args: argparse.Namespace) -> int:
+    """List all registered subcommands with aliases."""
     parser = build_parser()
     commands = commands_metadata(parser)
     payload = {
@@ -374,6 +459,10 @@ def _run_commands(args: argparse.Namespace) -> int:
 
 
 def _run_schema(args: argparse.Namespace) -> int:
+    """Print the JSON Schema for a subcommand's CLI input.
+
+    Returns 1 when the command is unknown or its schema file is missing.
+    """
     from .schema import load_command_input_schema
 
     parser = build_parser()

{gitwise_cli-0.29.0 → gitwise_cli-0.30.0}/gitwise/_cli_introspection.py

@@ -7,6 +7,7 @@ from . import __version__
 
 
 def _json_safe(value: object) -> object:
+    """Recursively convert an argparse value to a JSON-serializable form."""
     if value is argparse.SUPPRESS:
         return None
     if value is None or isinstance(value, str | int | float | bool):
@@ -19,6 +20,7 @@ def _json_safe(value: object) -> object:
 
 
 def _subparsers_action(parser: argparse.ArgumentParser) -> argparse._SubParsersAction | None:
+    """Return the first _SubParsersAction from a parser, or None."""
     for action in parser._actions:
         if isinstance(action, argparse._SubParsersAction):
             return action
@@ -26,6 +28,7 @@ def _subparsers_action(parser: argparse.ArgumentParser) -> argparse._SubParsersA
 
 
 def _serialize_actions(parser: argparse.ArgumentParser) -> list[dict[str, object]]:
+    """Serialize a parser's non-help, non-subparser actions into JSON-friendly dicts."""
     items: list[dict[str, object]] = []
     for action in parser._actions:
         if action.dest in {"help"}:
@@ -49,6 +52,7 @@ def _serialize_actions(parser: argparse.ArgumentParser) -> list[dict[str, object
 
 
 def extract_command_token(argv: list[str]) -> str | None:
+    """Extract the subcommand name from a raw argv, skipping global flags and their values."""
     skip_next = False
     for token in argv:
         if skip_next:
@@ -64,6 +68,7 @@ def extract_command_token(argv: list[str]) -> str | None:
 
 
 def help_payload(parser: argparse.ArgumentParser, command: str | None = None) -> dict[str, object]:
+    """Build a structured help payload for the root parser or a specific subcommand."""
     payload: dict[str, object] = {
         "v": 2,
         "ok": True,
@@ -130,6 +135,8 @@ def help_payload(parser: argparse.ArgumentParser, command: str | None = None) ->
 
 
 class CommandMetadata(TypedDict):
+    """Minimal metadata for a single subcommand."""
+
     name: str
     help: str
     aliases: list[str]
@@ -137,6 +144,7 @@ class CommandMetadata(TypedDict):
 
 
 def canonical_command_name(command_parser: argparse.ArgumentParser) -> str:
+    """Return the canonical name (last prog token) of a subcommand parser."""
     prog = command_parser.prog.strip()
     if not prog:
         return ""
@@ -145,6 +153,7 @@ def canonical_command_name(command_parser: argparse.ArgumentParser) -> str:
 
 
 def commands_metadata(parser: argparse.ArgumentParser) -> list[CommandMetadata]:
+    """Return metadata for every unique subcommand, deduplicating by parser identity."""
     sub_action = _subparsers_action(parser)
     if sub_action is None:
         return []
@@ -189,6 +198,7 @@ def commands_metadata(parser: argparse.ArgumentParser) -> list[CommandMetadata]:
 
 
 def _json_type_for_action(action: argparse.Action) -> str:
+    """Map an argparse action to a JSON Schema type string."""
     if isinstance(action, argparse._StoreTrueAction | argparse._StoreFalseAction):
         return "boolean"
 
@@ -201,6 +211,7 @@ def _json_type_for_action(action: argparse.Action) -> str:
 
 
 def _action_property_schema(action: argparse.Action) -> dict[str, object]:
+    """Build a JSON Schema property dict for a single argparse action."""
     value_schema: dict[str, object] = {"type": _json_type_for_action(action)}
 
     if action.choices:
@@ -230,6 +241,7 @@ def _action_property_schema(action: argparse.Action) -> dict[str, object]:
 
 
 def _action_required(action: argparse.Action) -> bool:
+    """Determine whether an argparse action produces a required JSON field."""
     if action.option_strings:
         return bool(getattr(action, "required", False))
 
@@ -242,6 +254,7 @@ def _action_required(action: argparse.Action) -> bool:
 
 
 def command_input_schema(command_parser: argparse.ArgumentParser) -> dict[str, object]:
+    """Generate a JSON Schema (draft 2020-12) describing the CLI input of a subcommand."""
     properties: dict[str, object] = {}
     required: list[str] = []
 
@@ -269,6 +282,7 @@ def command_input_schema(command_parser: argparse.ArgumentParser) -> dict[str, o
 def resolve_command_parser(
     *, parser: argparse.ArgumentParser, name: str
 ) -> argparse.ArgumentParser | None:
+    """Look up the sub-parser registered under *name*, or return None."""
     sub_action = _subparsers_action(parser)
     if sub_action is None:
         return None

{gitwise_cli-0.29.0 → gitwise_cli-0.30.0}/gitwise/_cli_parser.py

@@ -8,10 +8,12 @@ from .i18n import t
 
 
 def _root_help_epilog() -> str:
+    """Return the localized environment-variable epilog for root help."""
     return t("help_root_environment_epilog")
 
 
 def build_parser() -> argparse.ArgumentParser:
+    """Build and return the top-level argparse parser with all subcommands registered."""
     parent = argparse.ArgumentParser(add_help=False)
     parent.add_argument(
         "--lang",
@@ -176,7 +178,24 @@ def build_parser() -> argparse.ArgumentParser:
     diff_group.add_argument(
         "--full", "--patch", action="store_true", help="show full patch with delta integration"
     )
+    diff_group.add_argument(
+        "--summary",
+        action="store_true",
+        help="compact summary: additions/deletions per file, no patch",
+    )
     p.add_argument("--stat", action="store_true", help="show diffstat (default behavior)")
+    p.add_argument(
+        "refspec",
+        nargs="?",
+        default=None,
+        help="commit, branch, or range to diff (e.g. HEAD~3, main..feat, main...feat)",
+    )
+    p.add_argument(
+        "paths",
+        nargs="*",
+        metavar="PATH",
+        help="limit to paths (use -- to separate from refspec)",
+    )
 
     p = sub.add_parser("log", help="pretty git log with filters", parents=[parent])
     p.add_argument("--oneline", action="store_true", help="one line per commit")

{gitwise_cli-0.29.0 → gitwise_cli-0.30.0}/gitwise/_cli_setup_agents.py

@@ -194,6 +194,11 @@ def _run_setup_local(
     providers: list[str] | None = None,
     adapters_legacy_used: bool = False,
 ) -> int:
+    """Install per-repo setup-agents artifacts (CLAUDE.md, settings, skills).
+
+    Returns 0 on success, 1 on plan/execution errors, 2 when ``--strict``
+    mode encounters warnings.
+    """
     cwd = target or Path.cwd()
 
     if not is_repo(cwd):

{gitwise_cli-0.29.0 → gitwise_cli-0.30.0}/gitwise/_i18n_data.json

@@ -447,10 +447,22 @@
     "es": "Diagnóstico{suffix} — {count} observación(es):",
     "en": "Diagnostic{suffix} — {count} finding(s):"
   },
+  "diff_binary_lfs_hint": {
+    "es": "archivo binario {path} ({mib} MiB) -- considera Git LFS",
+    "en": "binary file {path} ({mib} MiB) -- consider Git LFS"
+  },
   "diff_prefix": {
     "es": "diff: {stat}",
     "en": "diff: {stat}"
   },
+  "diff_summary_header": {
+    "es": "Resumen -- {count} archivo(s):",
+    "en": "Summary -- {count} file(s):"
+  },
+  "diff_too_many_refs": {
+    "es": "demasiados argumentos posicionales antes de '--' ({count}); gitwise diff acepta un unico refspec (usa a..b para un rango)",
+    "en": "too many positional arguments before '--' ({count}); gitwise diff accepts a single refspec (use a..b for a range)"
+  },
   "directory_exists": {
     "es": "el directorio ya existe: {path}",
     "en": "directory already exists: {path}"

{gitwise_cli-0.29.0 → gitwise_cli-0.30.0}/gitwise/_runtime_config.py

@@ -16,6 +16,7 @@ _OSC_TIMEOUT = 0.5
 
 
 def _drain_fd(fd: int, timeout: float = 0.1) -> None:
+    """Read and discard pending data from a file descriptor."""
     while True:
         ready, _, _ = select.select([fd], [], [], timeout)
         if not ready:
@@ -27,6 +28,7 @@ def _drain_fd(fd: int, timeout: float = 0.1) -> None:
 
 
 def _query_bg_color() -> str | None:
+    """Query the terminal background color via OSC 11; returns a hex string or None."""
     if os.environ.get("NO_COLOR", "") != "":
         return None
     if os.environ.get("GITWISE_NO_COLOR", "").lower() in ("1", "true"):
@@ -67,6 +69,7 @@ def _query_bg_color() -> str | None:
 
 
 def _read_osc_response(fd: int) -> str | None:
+    """Read an OSC response from a tty fd, with a timeout."""
     buf = bytearray()
     osc_received = False
     while len(buf) < 50:
@@ -92,6 +95,7 @@ def _read_osc_response(fd: int) -> str | None:
 
 
 def _parse_osc_color(resp: str) -> str | None:
+    """Extract a hex color from an OSC 11 response string."""
     idx = resp.find("\x1b]")
     if idx == -1:
         return None
@@ -125,6 +129,7 @@ def _parse_osc_color(resp: str) -> str | None:
 
 
 def _parse_rgb_component(s: str) -> int:
+    """Parse a single hex RGB component, normalizing values wider than 8 bits."""
     val = int(s, 16)
     if len(s) > 2:
         val = val >> (4 * (len(s) - 2))
@@ -132,20 +137,25 @@ def _parse_rgb_component(s: str) -> int:
 
 
 def _relative_luminance(hex_color: str) -> float:
+    """Compute the sRGB relative luminance of a hex color (WCG 2.4)."""
     h = hex_color.lstrip("#")
     r, g, b = int(h[0:2], 16) / 255, int(h[2:4], 16) / 255, int(h[4:6], 16) / 255
 
     def linearize(c: float) -> float:
+        """Apply the sRGB gamma curve."""
         return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
 
     return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b)
 
 
 def _is_dark_background(bg_hex: str) -> bool:
+    """Return True if the background luminance is below the dark threshold."""
     return _relative_luminance(bg_hex) < _BRIGHTNESS_THRESHOLD
 
 
 class RuntimeConfig:
+    """Immutable runtime settings detected from the environment."""
+
     __slots__ = (
         "_theme_tokens",
         "color_depth",
@@ -167,6 +177,7 @@ class RuntimeConfig:
     theme: str
 
     def __init__(self) -> None:
+        """Detect theme, TTY, tools, and color settings from the current environment."""
         self.has_bat = bool(shutil.which("bat"))
         self.has_delta = bool(shutil.which("delta"))
         self.theme = self._detect_theme()
@@ -178,10 +189,12 @@ class RuntimeConfig:
 
     @property
     def theme_tokens(self) -> ThemeTokens:
+        """Return the resolved ThemeTokens for the current theme."""
         return self._theme_tokens
 
     @staticmethod
     def _detect_theme() -> str:
+        """Detect theme preference from env vars, OSC 11 query, or COLORFGBG."""
         explicit = os.environ.get("GITWISE_THEME", "").lower()
         if explicit in ("dark", "light"):
             return explicit
@@ -216,6 +229,7 @@ class RuntimeConfig:
 
     @staticmethod
     def _detect_terminal_width() -> int:
+        """Return terminal width from GITWISE_WIDTH or shutil detection."""
         from .design import MAX_WIDTH, MIN_WIDTH, detect_terminal_width
 
         env_width = os.environ.get("GITWISE_WIDTH", "")
@@ -226,6 +240,7 @@ class RuntimeConfig:
 
     @staticmethod
     def _detect_color_depth() -> ColorDepth:
+        """Delegate color-depth detection to design.detect_color_depth."""
         from .design import detect_color_depth
 
         return detect_color_depth()
@@ -235,6 +250,7 @@ _runtime_config: RuntimeConfig | None = None
 
 
 def get_runtime_config() -> RuntimeConfig:
+    """Return the module-level RuntimeConfig singleton, creating it on first call."""
     global _runtime_config
     if _runtime_config is None:
         _runtime_config = RuntimeConfig()
@@ -242,5 +258,6 @@ def get_runtime_config() -> RuntimeConfig:
 
 
 def reset_runtime_config() -> None:
+    """Clear the cached RuntimeConfig so it is re-detected on next access."""
     global _runtime_config
     _runtime_config = None