codeforerunner 0.4.2__py3-none-any.whl → 0.4.4__py3-none-any.whl

codeforerunner/__init__.py

@@ -1,6 +1,8 @@
+"""codeforerunner — prompt-first repo documentation tooling."""
+
 from importlib.metadata import PackageNotFoundError, version
 
 try:
     __version__ = version("codeforerunner")
-except PackageNotFoundError:
+except PackageNotFoundError:  # pragma: no cover
     __version__ = "0.0.0"  # running from source without install

codeforerunner/bundle.py

@@ -5,6 +5,7 @@ from pathlib import Path
 
 
 def _package_prompts() -> Path:
+    """Return the path to the bundled prompts directory inside the package."""
     return Path(__file__).parent / "prompts"
 
 

codeforerunner/check.py

@@ -11,6 +11,8 @@ from codeforerunner.config import CheckConfig
 
 @dataclass(frozen=True)
 class Violation:
+    """Single rule match: which doc, which line, which rule, and what it means."""
+
     path: Path
     line: int
     rule_id: str
@@ -19,6 +21,8 @@ class Violation:
 
 @dataclass(frozen=True)
 class _Rule:
+    """Drift detection rule: pattern to match, trigger files, and violation message."""
+
     id: str
     pattern: re.Pattern
     triggers: tuple[str, ...]
@@ -122,6 +126,7 @@ _CHANGELOG_FILENAME = "CHANGELOG.md"
 
 
 def _trigger_exists(repo: Path, patterns: tuple[str, ...]) -> bool:
+    """Return True if any pattern matches an existing file in repo."""
     for pat in patterns:
         if "*" in pat:
             parent = repo / Path(pat).parent
@@ -135,6 +140,7 @@ def _trigger_exists(repo: Path, patterns: tuple[str, ...]) -> bool:
 
 
 def _scanned_docs(repo: Path) -> list[Path]:
+    """Collect README.md and all *.md files under docs/ from repo."""
     docs: list[Path] = []
     readme = repo / "README.md"
     if readme.is_file():
@@ -146,6 +152,7 @@ def _scanned_docs(repo: Path) -> list[Path]:
 
 
 def _path_ignored(repo: Path, doc: Path, ignore_patterns: tuple[str, ...]) -> bool:
+    """Return True if doc's repo-relative path matches any ignore pattern."""
     if not ignore_patterns:
         return False
     try:
@@ -156,6 +163,7 @@ def _path_ignored(repo: Path, doc: Path, ignore_patterns: tuple[str, ...]) -> bo
 
 
 def _current_version(repo: Path) -> str | None:
+    """Extract the package version from pyproject.toml, or None if absent/unparseable."""
     pyproject = repo / "pyproject.toml"
     if not pyproject.is_file():
         return None
@@ -173,6 +181,7 @@ def _check_version_drift(
     ignore_patterns: tuple[str, ...],
     enabled: set[str] | None,
 ) -> list[Violation]:
+    """Scan docs for pinned version strings that don't match pyproject.toml."""
     if enabled is not None and "RV1-version-drift" not in enabled:
         return []
     current = _current_version(repo)

codeforerunner/cli.py

@@ -56,12 +56,13 @@ def cmd_doc(args: argparse.Namespace) -> int:
 
 
 def _doc_for(args: argparse.Namespace, task: str) -> int:
+    """Emit bundle for *task* by delegating to cmd_doc with a synthetic Namespace."""
     ns = argparse.Namespace(repo=getattr(args, "repo", None), task=task)
     return cmd_doc(ns)
 
 
 def cmd_init(args: argparse.Namespace) -> int:
-    """Default + --agents-only = onboarding bundle only. --full prepends scan."""
+    """Emit onboarding bundle; prepend scan bundle when --full is given."""
     if getattr(args, "full", False):
         sys.stdout.write("<!-- forerunner init --full: section 1/2 (scan) -->\n")
         rc = _doc_for(args, "scan")
@@ -72,6 +73,7 @@ def cmd_init(args: argparse.Namespace) -> int:
 
 
 def cmd_scan(args: argparse.Namespace) -> int:
+    """Emit the scan prompt bundle and hint about FORERUNNER_SCAN_DONE."""
     rc = _doc_for(args, "scan")
     if rc == 0:
         print(
@@ -102,6 +104,7 @@ def cmd_check(args: argparse.Namespace) -> int:
 
 
 def cmd_mcp_server(args: argparse.Namespace) -> int:
+    """Start the stdio MCP server exposing prompt bundles as tools."""
     from codeforerunner import mcp_server
     try:
         prompts_root = find_prompts_root(args.repo)
@@ -111,88 +114,22 @@ def cmd_mcp_server(args: argparse.Namespace) -> int:
     return mcp_server.serve(prompts_root)
 
 
-def cmd_generate(args: argparse.Namespace) -> int:
-    """Resolve the bundle for <task> and send it to the configured provider.
-
-    With --prompt-only (or when no provider/key/Ollama is reachable), outputs
-    the assembled prompt bundle to stdout for the calling agent to process.
-    """
-    from codeforerunner import providers as _providers
-    from codeforerunner.config import load_from_repo
-
-    repo_root = Path(args.repo).resolve() if args.repo else Path.cwd()
-    cfg = load_from_repo(repo_root)
-
-    ns = argparse.Namespace(repo=getattr(args, "repo", None), task=args.task)
-
-    # --prompt-only: output the bundle and stop; the calling agent is the model.
-    if getattr(args, "prompt_only", False):
-        return cmd_doc(ns)
-
-    bundle, rc = _get_bundle(ns)
-    if rc != 0:
-        return rc
-
-    explicit_provider = args.provider or (cfg.provider if cfg else None)
-    provider_name = explicit_provider or "anthropic"
-    model = args.model or (cfg.model if cfg else None)
-    provider_cls = _providers.get(provider_name)
-    provider = provider_cls()
-    model = model or provider.default_model
-
-    env_var = (cfg.api_key_env.get(provider_name) if cfg else None) or provider.default_env_var
-    api_key = os.environ.get(env_var)
-    if api_key is None and provider_name != "ollama":
-        if explicit_provider is None and _providers.ollama_available():
-            provider_name = "ollama"
-            provider_cls = _providers.get("ollama")
-            provider = provider_cls()
-            if not args.model:
-                model = provider.default_model
-            print("info: no API key; falling back to Ollama (local mode)", file=sys.stderr)
-        elif explicit_provider is None:
-            # Skill-mode auto-detect: no provider configured, no Ollama — output
-            # the prompt bundle for the calling agent to process directly.
-            sys.stdout.write(bundle)
-            if sys.stdout.isatty():
-                print(
-                    "\ninfo: no provider configured and Ollama not running.\n"
-                    "      Prompt bundle written above — paste into your agent,\n"
-                    "      or run: forerunner generate --prompt-only "
-                    f"{args.task}",
-                    file=sys.stderr,
-                )
-            return 0
-        else:
-            print(f"error: missing API key; set ${env_var}", file=sys.stderr)
-            return 3
-
-    if getattr(args, "stream", False):
-        try:
-            for chunk in provider.stream(prompt=bundle, model=model, api_key=api_key):
-                sys.stdout.write(chunk)
-                sys.stdout.flush()
-        except _providers.ProviderError as e:
-            print(f"error: {provider_name} provider failed: {e}", file=sys.stderr)
-            return 4
-        sys.stdout.write("\n")
-        return 0
-
-    try:
-        result = provider.complete(prompt=bundle, model=model, api_key=api_key)
-    except _providers.ProviderError as e:
-        print(f"error: {provider_name} provider failed: {e}", file=sys.stderr)
-        return 4
-
-    sys.stdout.write(result.text.rstrip() + "\n")
-    print(
-        f"# {provider_name} {result.model} {result.usage or ''}".rstrip(),
-        file=sys.stderr,
-    )
+def cmd_refresh(args: argparse.Namespace) -> int:
+    """Emit scan + check + all doc-task bundles to stdout for a full doc refresh."""
+    tasks = ["scan", "check", "readme", "api-docs", "stack-docs",
+             "diagrams", "flows", "version-audit", "audit"]
+    for i, task in enumerate(tasks):
+        ns = argparse.Namespace(repo=getattr(args, "repo", None), task=task)
+        rc = cmd_doc(ns)
+        if rc != 0:
+            return rc
+        if i < len(tasks) - 1:
+            sys.stdout.write("\n---\n\n")
     return 0
 
 
 def cmd_doctor(args: argparse.Namespace) -> int:
+    """Run health checks and print a single-screen report; exit 1 on errors."""
     from codeforerunner import doctor
     from codeforerunner.config import CONFIG_FILENAME
     root = Path(args.repo).resolve() if args.repo else Path.cwd()
@@ -209,6 +146,7 @@ def cmd_doctor(args: argparse.Namespace) -> int:
 
 
 def build_parser() -> argparse.ArgumentParser:
+    """Build and return the top-level argument parser with all subcommands registered."""
     p = argparse.ArgumentParser(
         prog="forerunner",
         description="Prompt-first repo documentation tooling. Thin CLI; product logic in prompts/.",
@@ -265,18 +203,8 @@ def build_parser() -> argparse.ArgumentParser:
     )
     s_doctor.set_defaults(func=cmd_doctor)
 
-    s_gen = sub.add_parser("generate", help="resolve bundle for <task> and call the configured provider")
-    s_gen.add_argument("task", help="task basename under prompts/tasks/")
-    s_gen.add_argument("--provider", help="override config provider")
-    s_gen.add_argument("--model", help="override config model")
-    s_gen.add_argument("--stream", action="store_true", help="stream output token-by-token")
-    s_gen.add_argument(
-        "--prompt-only",
-        dest="prompt_only",
-        action="store_true",
-        help="output the assembled prompt bundle to stdout; do not call a model (skill mode)",
-    )
-    s_gen.set_defaults(func=cmd_generate)
+    s_refresh = sub.add_parser("refresh", help="output all doc-refresh bundles in sequence (scan + check + all tasks)")
+    s_refresh.set_defaults(func=cmd_refresh)
 
     from codeforerunner import installer
     installer.add_subparser(sub)
@@ -285,6 +213,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def main(argv: Sequence[str] | None = None) -> int:
+    """Parse argv and dispatch to the appropriate subcommand handler."""
     parser = build_parser()
     args = parser.parse_args(argv)
     if not hasattr(args, "repo"):

codeforerunner/config.py

@@ -3,13 +3,13 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from pathlib import Path
 from typing import Any
 
 import yaml
 
 CONFIG_FILENAME = "forerunner.config.yaml"
 
-_KNOWN_PROVIDERS = {"anthropic", "openai", "google", "ollama"}
 _KNOWN_SEVERITIES = {"HIGH", "MEDIUM", "LOW"}
 
 
@@ -19,6 +19,8 @@ class ConfigError(Exception):
 
 @dataclass(frozen=True)
 class CheckConfig:
+    """Drift-check task configuration: severity gates and path filters."""
+
     block_on: tuple[str, ...] = ("HIGH", "MEDIUM")
     warn_on: tuple[str, ...] = ("LOW",)
     enabled_rules: tuple[str, ...] | None = None  # None = all rules enabled
@@ -27,6 +29,8 @@ class CheckConfig:
 
 @dataclass(frozen=True)
 class VersionAuditConfig:
+    """Version-audit task configuration: staleness window and live EOL data toggle."""
+
     enabled: bool = True
     stale_after_days: int = 30
     fetch_live_eol_data: bool = False
@@ -34,16 +38,16 @@ class VersionAuditConfig:
 
 @dataclass(frozen=True)
 class ForerunnerConfig:
-    provider: str = "anthropic"
-    model: str = "claude-opus-4-7"
+    """Top-level forerunner.config.yaml configuration."""
+
     approaching_eol_threshold_months: int = 6
     ignore_patterns: tuple[str, ...] = ()
-    api_key_env: dict[str, str] = field(default_factory=dict)
     check: CheckConfig = field(default_factory=CheckConfig)
     version_audit: VersionAuditConfig = field(default_factory=VersionAuditConfig)
 
 
 def _require_type(value: Any, expected: type, field_name: str) -> Any:
+    """Raise ConfigError if value is not an instance of expected."""
     if not isinstance(value, expected):
         raise ConfigError(
             f"{field_name}: expected {expected.__name__}, got {type(value).__name__}"
@@ -52,6 +56,7 @@ def _require_type(value: Any, expected: type, field_name: str) -> Any:
 
 
 def _coerce_str_tuple(value: Any, field_name: str) -> tuple[str, ...]:
+    """Coerce a list of strings to a tuple, raising ConfigError on bad input."""
     if value is None:
         return ()
     if not isinstance(value, list):
@@ -64,30 +69,8 @@ def _coerce_str_tuple(value: Any, field_name: str) -> tuple[str, ...]:
     return tuple(out)
 
 
-def _parse_api_key_env(raw: Any) -> dict[str, str]:
-    if raw is None:
-        return {}
-    if not isinstance(raw, dict):
-        raise ConfigError(f"api_key_env: expected dict, got {type(raw).__name__}")
-    out: dict[str, str] = {}
-    for k, v in raw.items():
-        if not isinstance(k, str):
-            raise ConfigError(
-                f"api_key_env: keys must be strings, got {type(k).__name__}"
-            )
-        if k not in _KNOWN_PROVIDERS:
-            raise ConfigError(
-                f"api_key_env: unknown provider '{k}' (expected one of {sorted(_KNOWN_PROVIDERS)})"
-            )
-        if not isinstance(v, str) or not v:
-            raise ConfigError(
-                f"api_key_env[{k}]: expected non-empty string, got {type(v).__name__}"
-            )
-        out[k] = v
-    return out
-
-
 def _parse_check(raw: Any) -> CheckConfig:
+    """Parse the tasks.check mapping into a CheckConfig."""
     if raw is None:
         return CheckConfig()
     _require_type(raw, dict, "tasks.check")
@@ -114,6 +97,7 @@ def _parse_check(raw: Any) -> CheckConfig:
 
 
 def _to_int(value: Any, field_name: str) -> int:
+    """Convert value to int, raising ConfigError on failure."""
     try:
         return int(value)
     except (TypeError, ValueError) as e:
@@ -121,6 +105,7 @@ def _to_int(value: Any, field_name: str) -> int:
 
 
 def _parse_version_audit(raw: Any) -> VersionAuditConfig:
+    """Parse the tasks.version_audit mapping into a VersionAuditConfig."""
     if raw is None:
         return VersionAuditConfig()
     _require_type(raw, dict, "tasks.version_audit")
@@ -137,24 +122,21 @@ def parse(raw: dict[str, Any] | None) -> ForerunnerConfig:
         return ForerunnerConfig()
     _require_type(raw, dict, "<root>")
 
-    provider = raw.get("provider", "anthropic")
-    _require_type(provider, str, "provider")
-    if provider not in _KNOWN_PROVIDERS:
+    tasks_raw = raw.get("tasks")
+    tasks = tasks_raw if tasks_raw is not None else {}
+    _require_type(tasks, dict, "tasks")
+
+    eol_months = _to_int(
+        raw.get("approaching_eol_threshold_months", 6), "approaching_eol_threshold_months"
+    )
+    if eol_months <= 0:
         raise ConfigError(
-            f"provider: unknown '{provider}' (expected one of {sorted(_KNOWN_PROVIDERS)})"
+            f"approaching_eol_threshold_months: must be a positive integer, got {eol_months}"
         )
 
-    tasks = raw.get("tasks") or {}
-    _require_type(tasks, dict, "tasks")
-
     return ForerunnerConfig(
-        provider=provider,
-        model=_require_type(raw.get("model", "claude-opus-4-7"), str, "model"),
-        approaching_eol_threshold_months=_to_int(
-            raw.get("approaching_eol_threshold_months", 6), "approaching_eol_threshold_months"
-        ),
+        approaching_eol_threshold_months=eol_months,
         ignore_patterns=_coerce_str_tuple(raw.get("ignore_patterns", []), "ignore_patterns"),
-        api_key_env=_parse_api_key_env(raw.get("api_key_env")),
         check=_parse_check(tasks.get("check")),
         version_audit=_parse_version_audit(tasks.get("version_audit")),
     )

codeforerunner/doctor.py

@@ -23,22 +23,18 @@ MARKETPLACE_REL = Path("plugins/codex/marketplace.json")
 MARKER_BEGIN = "<!-- forerunner:begin managed=codeforerunner.skill -->"
 MARKER_END = "<!-- forerunner:end -->"
 
-_DEFAULT_PROVIDER_ENV = {
-    "anthropic": "ANTHROPIC_API_KEY",
-    "openai": "OPENAI_API_KEY",
-    "google": "GOOGLE_API_KEY",
-    "ollama": "OLLAMA_HOST",
-}
-
 
 @dataclass(frozen=True)
 class Finding:
+    """Single health-check result with severity, check name, and human message."""
+
     severity: str  # "ok" | "warn" | "error"
     check: str
     message: str
 
 
 def _installed_skill_destinations() -> list[Path]:
+    """Return default install paths for the codeforerunner skill across supported agents."""
     home = Path(os.path.expanduser("~"))
     return [
         home / ".codex/skills/codeforerunner/SKILL.md",
@@ -47,10 +43,12 @@ def _installed_skill_destinations() -> list[Path]:
 
 
 def _installed_marketplace_destination() -> Path:
+    """Return default install path for the Codex marketplace manifest."""
     return Path(os.path.expanduser("~")) / ".codex/marketplaces/codeforerunner.json"
 
 
 def _load_script_module(repo: Path, relpath: str, module_name: str):
+    """Load a Python script from the repo as a module with a unique name to avoid cache collisions."""
     # L3: unique name prevents stale cached module on repeated calls
     unique_name = f"{module_name}_{uuid.uuid4().hex}"
     script_path = repo / relpath
@@ -64,6 +62,7 @@ def _load_script_module(repo: Path, relpath: str, module_name: str):
 
 
 def _check_skill_body_parity(repo: Path, run_scripts: bool = False) -> list[Finding]:
+    """Verify that all distributed skill copies match the canonical body."""
     if not run_scripts:
         return [
             Finding(
@@ -116,6 +115,7 @@ def _check_skill_body_parity(repo: Path, run_scripts: bool = False) -> list[Find
 
 
 def _check_codex_marketplace(repo: Path, run_scripts: bool = False) -> list[Finding]:
+    """Validate the Codex marketplace manifest using the repo validation script."""
     if not run_scripts:
         return [
             Finding(
@@ -143,6 +143,7 @@ def _check_codex_marketplace(repo: Path, run_scripts: bool = False) -> list[Find
 
 
 def _check_installed_destinations(repo: Path) -> list[Finding]:
+    """Check whether installed skill and marketplace files are present and managed."""
     findings: list[Finding] = []
 
     for dest in _installed_skill_destinations():
@@ -227,6 +228,7 @@ def _check_installed_destinations(repo: Path) -> list[Finding]:
 
 
 def _check_config_loadable(repo: Path) -> list[Finding]:
+    """Try parsing forerunner.config.yaml; report error finding on ConfigError."""
     cfg_path = repo / CONFIG_FILENAME
     if not cfg_path.is_file():
         return [
@@ -243,92 +245,6 @@ def _check_config_loadable(repo: Path) -> list[Finding]:
     return [Finding("ok", "config-loadable", f"{CONFIG_FILENAME} parses cleanly")]
 
 
-def _skill_mode_active() -> bool:
-    """True if any installed skill destination has managed markers — agent IS the model."""
-    for dest in _installed_skill_destinations():
-        if dest.exists():
-            try:
-                text = dest.read_text(encoding="utf-8")
-                if MARKER_BEGIN in text and MARKER_END in text:
-                    return True
-            except OSError:
-                pass
-    return False
-
-
-def _check_provider_api_key(repo: Path) -> list[Finding]:
-    from codeforerunner.providers.ollama import is_available as _ollama_available
-
-    cfg_path = repo / CONFIG_FILENAME
-    if not cfg_path.is_file():
-        if _ollama_available():
-            return [
-                Finding(
-                    "ok",
-                    "provider-api-key",
-                    "no config; Ollama running — generate will use local mode automatically",
-                )
-            ]
-        if _skill_mode_active():
-            return [
-                Finding(
-                    "ok",
-                    "provider-api-key",
-                    "no config; skill mode active — the installed agent is the model, no API key needed",
-                )
-            ]
-        return [
-            Finding(
-                "ok",
-                "provider-api-key",
-                f"no {CONFIG_FILENAME}; set an API key in config, start Ollama, or use skill mode (`forerunner generate --prompt-only`)",
-            )
-        ]
-    try:
-        cfg = load_from_repo(repo)
-    except ConfigError:
-        # config-loadable check will surface this; skip here
-        return [
-            Finding(
-                "ok",
-                "provider-api-key",
-                "config unparseable; skipped (see config-loadable)",
-            )
-        ]
-    if cfg is None:  # pragma: no cover - defensive
-        return [
-            Finding(
-                "ok",
-                "provider-api-key",
-                f"no {CONFIG_FILENAME}; provider key not checked",
-            )
-        ]
-    provider = cfg.provider
-    if provider == "ollama":
-        return [
-            Finding(
-                "ok",
-                "provider-api-key",
-                "running in local mode (Ollama; no API key needed)",
-            )
-        ]
-    env_var = cfg.api_key_env.get(provider) or _DEFAULT_PROVIDER_ENV.get(provider, "")
-    if os.environ.get(env_var):
-        return [Finding("ok", "provider-api-key", f"{provider}: {env_var} is set")]
-    return [
-        Finding(
-            "warn",
-            "provider-api-key",
-            f"{provider}: ${env_var} is not set; `forerunner generate` will refuse to run"
-            + (
-                " (use `--prompt-only` for key-free bundle output)"
-                if _skill_mode_active()
-                else ""
-            ),
-        )
-    ]
-
-
 _STARTER_CONFIG = """\
 # forerunner.config.yaml — generated by `forerunner doctor --fix`
 # See https://github.com/derek-palmer/codeforerunner for docs.
@@ -348,31 +264,34 @@ tasks:
 
 
 def starter_config() -> str:
+    """Return the default forerunner.config.yaml content written by --fix."""
     return _STARTER_CONFIG
 
 
 def run(repo: Path, run_scripts: bool = False) -> list[Finding]:
+    """Run all health checks against *repo* and return findings."""
     repo = repo.resolve()
     findings: list[Finding] = []
     findings.extend(_check_skill_body_parity(repo, run_scripts=run_scripts))
     findings.extend(_check_codex_marketplace(repo, run_scripts=run_scripts))
     findings.extend(_check_installed_destinations(repo))
     findings.extend(_check_config_loadable(repo))
-    findings.extend(_check_provider_api_key(repo))
     return findings
 
 
 def format_report(findings: list[Finding]) -> str:
+    """Format findings as a human-readable report string with a summary line."""
     lines = [f"[{f.severity}] {f.check}: {f.message}" for f in findings]
     counts: dict[str, int] = {"ok": 0, "warn": 0, "error": 0}
     for f in findings:
-        counts[f.severity] = counts.get(f.severity, 0) + 1
+        counts[f.severity] += 1
     summary = f"summary: {counts['ok']} ok, {counts['warn']} warn, {counts['error']} error"
     lines.append(summary)
     return "\n".join(lines)
 
 
 def main(argv: list[str] | None = None) -> int:
+    """Entry point for `forerunner doctor`; returns 1 when any finding is an error."""
     parser = argparse.ArgumentParser(
         prog="forerunner doctor",
         description="Single-screen health report for codeforerunner repo.",

codeforerunner/installer.py

@@ -41,15 +41,19 @@ TASK_SKILL_SLUGS: tuple[str, ...] = (
 
 @dataclass(frozen=True)
 class Target:
+    """Resolved install destination: agent name + absolute path."""
+
     name: str
     path: Path
 
 
 def _home() -> Path:
+    """Return the current user's home directory as a Path."""
     return Path(os.path.expanduser("~"))
 
 
 def resolve_target(agent: str, override: Path | None) -> Target:
+    """Return the default install Target for the given agent, or use override path."""
     if agent == "generic":
         if override is None:
             raise ValueError("generic target requires --path PATH")
@@ -126,6 +130,7 @@ def install_all_skills(
 
 
 def resolve_marketplace_target(agent: str, override: Path | None) -> Target:
+    """Return the marketplace install Target for the given agent, or use override path."""
     if agent == "generic":
         if override is None:
             raise ValueError("generic marketplace target requires --path PATH")
@@ -160,10 +165,12 @@ def extract_frontmatter(text: str) -> str:
 
 
 def _hash(s: str) -> str:
+    """Return SHA-256 hex digest of a UTF-8 encoded string."""
     return hashlib.sha256(s.encode("utf-8")).hexdigest()
 
 
 def _hash_bytes(b: bytes) -> str:
+    """Return SHA-256 hex digest of raw bytes."""
     return hashlib.sha256(b).hexdigest()
 
 
@@ -181,6 +188,7 @@ def render(source_text: str, dest_existing: str | None, agent: str) -> str:
 
 
 def find_markers(text: str) -> tuple[int, int] | None:
+    """Return (start, end) byte offsets of the managed region, or None if absent."""
     a = text.find(MARKER_BEGIN)
     if a < 0:
         return None
@@ -202,12 +210,15 @@ def overlay(dest_text: str, source_body: str) -> str:
 
 @dataclass
 class Plan:
+    """Pending install action computed by plan_install or plan_marketplace."""
+
     action: str  # "create" | "update" | "skip" | "abort"
     reason: str
     target: Target
     new_content: str | None = None
 
     def write(self) -> None:
+        """Execute the plan: create or update the destination file."""
         if self.action in ("skip", "abort"):
             return
         assert self.new_content is not None
@@ -306,6 +317,7 @@ def install(
     out=None,
     err=None,
 ) -> int:
+    """Run one install operation (skill or marketplace). Returns an EXIT_* code."""
     out = out or sys.stdout
     err = err or sys.stderr
 
@@ -356,6 +368,7 @@ def install(
 
 
 def add_subparser(sub: argparse._SubParsersAction) -> None:
+    """Register the `forerunner install` subcommand onto *sub*."""
     p = sub.add_parser("install", help="install skill(s) into agent-specific directories (D.installer)")
     p.add_argument("agent", choices=["codex", "claude", "generic"], nargs="?",
                    help="target agent (omit with --all to install to all detected agents)")
@@ -373,6 +386,7 @@ def add_subparser(sub: argparse._SubParsersAction) -> None:
 
 
 def _cli_entry(args: argparse.Namespace) -> int:
+    """Dispatch `forerunner install` subcommand from parsed CLI args."""
     root = Path(args.repo).resolve() if args.repo else Path.cwd()
 
     if getattr(args, "all", False):