codeforerunner 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

codeforerunner/check.py

@@ -1,9 +1,9 @@
-"""Drift detection for docs that claim files don't exist when they do."""
+"""Drift detection for docs vs repo state."""
 from __future__ import annotations
 
 import fnmatch
 import re
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 
 from codeforerunner.config import CheckConfig
@@ -17,8 +17,18 @@ class Violation:
     message: str
 
 
-_RULES = [
-    (
+@dataclass(frozen=True)
+class _Rule:
+    id: str
+    pattern: re.Pattern
+    triggers: tuple[str, ...]
+    message: str
+    invert: bool = False  # True = fire when triggers ABSENT (doc claims feature exists but file gone)
+
+
+_RULES: list[_Rule] = [
+    # Normal rules: fire when trigger EXISTS and phrase matches (doc denies a thing that's present)
+    _Rule(
         "R1-no-cli",
         re.compile(
             r"(?i)no\s+CLI\s+exists"
@@ -29,56 +39,87 @@ _RULES = [
         ("src/codeforerunner/cli.py",),
         "doc claims no CLI exists, but src/codeforerunner/cli.py is present",
     ),
-    (
+    _Rule(
         "R2-no-pre-commit",
         re.compile(r"(?i)no\s+pre[- ]commit(\s+hook)?"),
         (".pre-commit-hooks.yaml",),
         "doc claims no pre-commit hook, but .pre-commit-hooks.yaml is present",
     ),
-    (
+    _Rule(
         "R3-no-ci",
         re.compile(r"(?i)no\s+CI(\s+workflow)?"),
         (".github/workflows/*.yml",),
         "doc claims no CI workflow, but .github/workflows/*.yml is present",
     ),
-    (
+    _Rule(
         "R4-no-installer",
         re.compile(r"(?i)no\s+installer"),
         ("src/codeforerunner/installer.py",),
         "doc claims no installer, but src/codeforerunner/installer.py is present",
     ),
-    (
+    _Rule(
         "R5-no-python-package",
         re.compile(r"(?i)no\s+Python\s+package"),
         ("pyproject.toml",),
         "doc claims no Python package, but pyproject.toml is present",
     ),
-    (
+    _Rule(
         "R6-no-docker",
         re.compile(r"(?i)no\s+Docker(\s+image)?|no\s+Dockerfile"),
         ("Dockerfile", "compose.yml", "docker-compose.yml"),
         "doc claims no Docker, but Dockerfile/compose file is present",
     ),
-    (
+    _Rule(
         "R6b-no-makefile",
         re.compile(r"(?i)no\s+Makefile"),
         ("Makefile",),
         "doc claims no Makefile, but Makefile is present",
     ),
-    (
+    _Rule(
         "R7-no-mcp",
         re.compile(r"(?i)no\s+MCP(\s+server)?"),
         ("src/codeforerunner/mcp_server.py",),
         "doc claims no MCP server, but src/codeforerunner/mcp_server.py is present",
     ),
-    (
+    _Rule(
         "R8-no-marketplace",
         re.compile(r"(?i)no\s+marketplace(\s+manifest)?"),
         ("plugins/codex/marketplace.json",),
         "doc claims no marketplace, but plugins/codex/marketplace.json is present",
     ),
+    # Inverse rules: fire when trigger ABSENT and phrase matches (doc claims thing exists but file gone)
+    _Rule(
+        "RI1-missing-cli",
+        re.compile(
+            r"(?i)\bforerunner\s+(?:init|scan|doc|check|generate|doctor)\b"
+        ),
+        ("src/codeforerunner/cli.py",),
+        "doc references forerunner CLI commands, but src/codeforerunner/cli.py is absent",
+        invert=True,
+    ),
+    _Rule(
+        "RI5-missing-python-package",
+        re.compile(r"(?i)\bpipx?\s+install\s+codeforerunner\b"),
+        ("pyproject.toml",),
+        "doc claims package is installable via pip/pipx, but pyproject.toml is absent",
+        invert=True,
+    ),
+    _Rule(
+        "RI7-missing-mcp",
+        re.compile(r"(?i)\bforerunner\s+mcp-server\b"),
+        ("src/codeforerunner/mcp_server.py",),
+        "doc references forerunner mcp-server, but src/codeforerunner/mcp_server.py is absent",
+        invert=True,
+    ),
 ]
 
+_VERSION_PIN_RE = re.compile(
+    r"(?:codeforerunner==|codeforerunner@v)"
+    r"(\d+\.\d+\.\d+)"
+)
+_PYPROJECT_VERSION_RE = re.compile(r'^version\s*=\s*"(\d+\.\d+\.\d+)"', re.MULTILINE)
+_CHANGELOG_FILENAME = "CHANGELOG.md"
+
 
 def _trigger_exists(repo: Path, patterns: tuple[str, ...]) -> bool:
     for pat in patterns:
@@ -114,6 +155,54 @@ def _path_ignored(repo: Path, doc: Path, ignore_patterns: tuple[str, ...]) -> bo
     return any(fnmatch.fnmatch(rel, pat) for pat in ignore_patterns)
 
 
+def _current_version(repo: Path) -> str | None:
+    pyproject = repo / "pyproject.toml"
+    if not pyproject.is_file():
+        return None
+    try:
+        text = pyproject.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    m = _PYPROJECT_VERSION_RE.search(text)
+    return m.group(1) if m else None
+
+
+def _check_version_drift(
+    repo: Path,
+    docs: list[Path],
+    ignore_patterns: tuple[str, ...],
+    enabled: set[str] | None,
+) -> list[Violation]:
+    if enabled is not None and "RV1-version-drift" not in enabled:
+        return []
+    current = _current_version(repo)
+    if current is None:
+        return []
+    violations: list[Violation] = []
+    for doc in docs:
+        if doc.name == _CHANGELOG_FILENAME:
+            continue
+        if _path_ignored(repo, doc, ignore_patterns):
+            continue
+        try:
+            text = doc.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            for m in _VERSION_PIN_RE.finditer(line):
+                pinned = m.group(1)
+                if pinned != current:
+                    violations.append(
+                        Violation(
+                            path=doc,
+                            line=lineno,
+                            rule_id="RV1-version-drift",
+                            message=f"version pin {pinned!r} does not match current {current!r}",
+                        )
+                    )
+    return violations
+
+
 def run(repo: Path, config: CheckConfig | None = None) -> list[Violation]:
     """Scan repo docs for drift; return list of violations.
 
@@ -124,16 +213,18 @@ def run(repo: Path, config: CheckConfig | None = None) -> list[Violation]:
     enabled = set(config.enabled_rules) if (config and config.enabled_rules is not None) else None
     ignore_patterns = config.ignore_paths if config else ()
 
-    active_rules = [
-        (rid, rx, msg)
-        for rid, rx, triggers, msg in _RULES
-        if _trigger_exists(repo, triggers) and (enabled is None or rid in enabled)
-    ]
-    if not active_rules:
-        return []
+    docs = _scanned_docs(repo)
+
+    active_rules: list[_Rule] = []
+    for rule in _RULES:
+        if enabled is not None and rule.id not in enabled:
+            continue
+        trigger_found = _trigger_exists(repo, rule.triggers)
+        if (not rule.invert and trigger_found) or (rule.invert and not trigger_found):
+            active_rules.append(rule)
 
     violations: list[Violation] = []
-    for doc in _scanned_docs(repo):
+    for doc in docs:
         if _path_ignored(repo, doc, ignore_patterns):
             continue
         try:
@@ -141,11 +232,13 @@ def run(repo: Path, config: CheckConfig | None = None) -> list[Violation]:
         except (OSError, UnicodeDecodeError):
             continue
         for lineno, line in enumerate(text.splitlines(), start=1):
-            for rid, rx, msg in active_rules:
-                if rx.search(line):
+            for rule in active_rules:
+                if rule.pattern.search(line):
                     violations.append(
-                        Violation(path=doc, line=lineno, rule_id=rid, message=msg)
+                        Violation(path=doc, line=lineno, rule_id=rule.id, message=rule.message)
                     )
+
+    violations.extend(_check_version_drift(repo, docs, ignore_patterns, enabled))
     return violations
 
 

codeforerunner/cli.py

@@ -111,7 +111,8 @@ def cmd_generate(args: argparse.Namespace) -> int:
     repo_root = Path(args.repo).resolve() if args.repo else Path.cwd()
     cfg = load_from_repo(repo_root)
 
-    provider_name = args.provider or (cfg.provider if cfg else "anthropic")
+    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()
@@ -132,8 +133,30 @@ def cmd_generate(args: argparse.Namespace) -> int:
     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":
-        print(f"error: missing API key; set ${env_var}", file=sys.stderr)
-        return 3
+        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)
+        else:
+            msg = f"error: missing API key; set ${env_var}"
+            if explicit_provider is None:
+                msg += "\nhint: start Ollama for keyless local generation (https://ollama.com)"
+            print(msg, file=sys.stderr)
+            return 3
+
+    if getattr(args, "stream", False):
+        try:
+            for chunk in provider.stream(prompt=buf.getvalue(), 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=buf.getvalue(), model=model, api_key=api_key)
@@ -151,7 +174,15 @@ def cmd_generate(args: argparse.Namespace) -> int:
 
 def cmd_doctor(args: argparse.Namespace) -> int:
     from codeforerunner import doctor
+    from codeforerunner.config import CONFIG_FILENAME
     root = Path(args.repo).resolve() if args.repo else Path.cwd()
+    if getattr(args, "fix", False):
+        cfg_path = root / CONFIG_FILENAME
+        if not cfg_path.is_file():
+            cfg_path.write_text(doctor.starter_config(), encoding="utf-8")
+            print(f"wrote {cfg_path}", file=sys.stderr)
+        else:
+            print(f"{cfg_path} already exists; skipping --fix", file=sys.stderr)
     findings = doctor.run(root)
     sys.stdout.write(doctor.format_report(findings) + "\n")
     return 1 if any(f.severity == "error" for f in findings) else 0
@@ -200,12 +231,18 @@ def build_parser() -> argparse.ArgumentParser:
     s_mcp.set_defaults(func=cmd_mcp_server)
 
     s_doctor = sub.add_parser("doctor", help="health report: skill parity + marketplace + installed dests")
+    s_doctor.add_argument(
+        "--fix",
+        action="store_true",
+        help="write a starter forerunner.config.yaml if absent",
+    )
     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.set_defaults(func=cmd_generate)
 
     from codeforerunner import installer

codeforerunner/doctor.py

@@ -225,13 +225,23 @@ def _check_config_loadable(repo: Path) -> list[Finding]:
 
 
 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",
+                )
+            ]
         return [
             Finding(
                 "ok",
                 "provider-api-key",
-                f"no {CONFIG_FILENAME}; provider key not checked",
+                f"no {CONFIG_FILENAME}; set an API key in config or start Ollama for keyless local generation",
             )
         ]
     try:
@@ -259,7 +269,7 @@ def _check_provider_api_key(repo: Path) -> list[Finding]:
             Finding(
                 "ok",
                 "provider-api-key",
-                "ollama needs no API key (OLLAMA_HOST optional)",
+                "running in local mode (Ollama; no API key needed)",
             )
         ]
     env_var = cfg.api_key_env.get(provider) or _DEFAULT_PROVIDER_ENV.get(provider, "")
@@ -274,6 +284,26 @@ def _check_provider_api_key(repo: Path) -> list[Finding]:
     ]
 
 
+_STARTER_CONFIG = """\
+# forerunner.config.yaml — generated by `forerunner doctor --fix`
+# See https://github.com/derek-palmer/codeforerunner for docs.
+
+enabled_rules:
+  - R1-no-cli
+  - R2-no-pre-commit
+  - R3-no-ci
+  - R4-no-installer
+  - R5-no-python-package
+  - R7-no-mcp
+  - R8-no-marketplace
+ignore_paths: []
+"""
+
+
+def starter_config() -> str:
+    return _STARTER_CONFIG
+
+
 def run(repo: Path) -> list[Finding]:
     repo = repo.resolve()
     findings: list[Finding] = []

codeforerunner/installer.py

@@ -21,6 +21,23 @@ EXIT_USAGE = 2
 EXIT_BODY_MISMATCH = 3
 EXIT_UNMANAGED_DEST = 4
 
+# Per-task skill slugs (source: skills/<slug>/SKILL.md → plugins/codeforerunner/skills/<slug>/SKILL.md)
+TASK_SKILL_SLUGS: tuple[str, ...] = (
+    "codeforerunner",
+    "forerunner-scan",
+    "forerunner-readme",
+    "forerunner-api-docs",
+    "forerunner-audit",
+    "forerunner-changelog",
+    "forerunner-check",
+    "forerunner-diagrams",
+    "forerunner-flows",
+    "forerunner-init",
+    "forerunner-review",
+    "forerunner-stack-docs",
+    "forerunner-version-audit",
+)
+
 
 @dataclass(frozen=True)
 class Target:
@@ -44,9 +61,65 @@ def resolve_target(agent: str, override: Path | None) -> Target:
         return Target(agent, home / ".codex/skills/codeforerunner/SKILL.md")
     if agent == "claude":
         return Target(agent, home / ".claude/plugins/codeforerunner/skills/codeforerunner/SKILL.md")
+    if agent == "gemini":
+        raise ValueError(
+            "gemini install is handled via `gemini extensions install`; "
+            "run `./install.sh --only gemini` instead"
+        )
     raise ValueError(f"unknown agent '{agent}' (expected: codex, claude, generic)")
 
 
+def resolve_skill_target(agent: str, slug: str) -> Target:
+    """Return install target for a per-task skill slug."""
+    home = _home()
+    if agent == "codex":
+        return Target(agent, home / f".codex/skills/{slug}/SKILL.md")
+    if agent == "claude":
+        return Target(agent, home / f".claude/plugins/codeforerunner/skills/{slug}/SKILL.md")
+    raise ValueError(f"install_all not supported for agent '{agent}' (expected: codex, claude)")
+
+
+def install_all_skills(
+    *,
+    agent: str,
+    repo_root: Path,
+    check_only: bool,
+    out=None,
+    err=None,
+) -> int:
+    """Install all per-task skills for the given agent. Returns 0 on full success."""
+    out = out or sys.stdout
+    err = err or sys.stderr
+    any_error = False
+    for slug in TASK_SKILL_SLUGS:
+        src_path = repo_root / "plugins" / "codeforerunner" / "skills" / slug / "SKILL.md"
+        if not src_path.is_file():
+            print(f"warning: skill source not found: {src_path}", file=err)
+            continue
+        try:
+            target = resolve_skill_target(agent, slug)
+        except ValueError as e:
+            print(f"error: {e}", file=err)
+            return EXIT_USAGE
+        # For per-task skills use simple copy (no body-parity check against canonical)
+        dest = target.path
+        prefix = "would " if check_only else ""
+        if dest.exists():
+            src_trimmed = src_path.read_bytes().rstrip()
+            dest_trimmed = dest.read_bytes().rstrip()
+            if src_trimmed == dest_trimmed:
+                print(f"skip: {dest} (up-to-date)", file=out)
+                continue
+            action = "update"
+        else:
+            action = "create"
+        print(f"{prefix}{action}: {dest}", file=out)
+        if not check_only:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_bytes(src_path.read_bytes())
+    return EXIT_OK if not any_error else EXIT_BODY_MISMATCH
+
+
 def resolve_marketplace_target(agent: str, override: Path | None) -> Target:
     if agent == "generic":
         if override is None:
@@ -277,8 +350,11 @@ def install(
 
 
 def add_subparser(sub: argparse._SubParsersAction) -> None:
-    p = sub.add_parser("install", help="install skill into agent-specific directory (D.installer)")
-    p.add_argument("agent", choices=["codex", "claude", "generic"])
+    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)")
+    p.add_argument("--all", action="store_true",
+                   help="install all per-task skills for the specified agent")
     p.add_argument("--check", action="store_true", help="dry-run: print plan, write nothing")
     p.add_argument("--path", type=Path, help="dest path override (required for generic)")
     p.add_argument("--source", type=Path, help="source skill file (default: agent/codeforerunner.skill.md)")
@@ -292,6 +368,19 @@ def add_subparser(sub: argparse._SubParsersAction) -> None:
 
 def _cli_entry(args: argparse.Namespace) -> int:
     root = Path(args.repo).resolve() if args.repo else Path.cwd()
+
+    if getattr(args, "all", False):
+        agent = args.agent or "claude"
+        return install_all_skills(
+            agent=agent,
+            repo_root=root,
+            check_only=args.check,
+        )
+
+    if not args.agent:
+        print("error: specify an agent or use --all", file=sys.stderr)
+        return EXIT_USAGE
+
     return install(
         agent=args.agent,
         repo_root=root,

codeforerunner/providers/__init__.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from codeforerunner.providers.anthropic import AnthropicProvider
 from codeforerunner.providers.base import CompletionResult, Provider, ProviderError
 from codeforerunner.providers.google import GoogleProvider
-from codeforerunner.providers.ollama import OllamaProvider
+from codeforerunner.providers.ollama import OllamaProvider, is_available as ollama_available
 from codeforerunner.providers.openai import OpenAIProvider
 
 __all__ = [
@@ -18,6 +18,7 @@ __all__ = [
     "ProviderError",
     "REGISTRY",
     "get",
+    "ollama_available",
 ]
 
 REGISTRY: dict[str, type] = {

codeforerunner/providers/anthropic.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import urllib.error
 import urllib.request
+from typing import Iterator
 
 from codeforerunner.providers.base import CompletionResult, ProviderError
 
@@ -12,7 +13,7 @@ from codeforerunner.providers.base import CompletionResult, ProviderError
 class AnthropicProvider:
     name = "anthropic"
     default_env_var = "ANTHROPIC_API_KEY"
-    default_model = "claude-opus-4-5"
+    default_model = "claude-opus-4-7"
 
     endpoint = "https://api.anthropic.com/v1/messages"
 
@@ -59,3 +60,59 @@ class AnthropicProvider:
         return CompletionResult(
             text=text, model=data.get("model", model), usage=data.get("usage")
         )
+
+    def stream(
+        self,
+        *,
+        prompt: str,
+        model: str | None = None,
+        api_key: str | None = None,
+    ) -> Iterator[str]:
+        if not api_key:
+            raise ProviderError(f"missing API key (set ${self.default_env_var})")
+        model = model or self.default_model
+        body = json.dumps(
+            {
+                "model": model,
+                "max_tokens": 4096,
+                "stream": True,
+                "messages": [{"role": "user", "content": prompt}],
+            }
+        ).encode("utf-8")
+        req = urllib.request.Request(
+            self.endpoint,
+            data=body,
+            method="POST",
+            headers={
+                "x-api-key": api_key,
+                "anthropic-version": "2023-06-01",
+                "content-type": "application/json",
+            },
+        )
+        try:
+            resp = urllib.request.urlopen(req)
+        except urllib.error.HTTPError as e:
+            snippet = (e.read() or b"")[:500].decode("utf-8", errors="replace")
+            raise ProviderError(f"HTTP {e.code}: {snippet}") from e
+        except urllib.error.URLError as e:
+            raise ProviderError(f"network error: {e.reason}") from e
+        try:
+            for raw_line in resp:
+                line = raw_line.decode("utf-8").rstrip("\n")
+                if not line.startswith("data: "):
+                    continue
+                payload = line[6:]
+                if payload.strip() == "[DONE]":
+                    break
+                try:
+                    event = json.loads(payload)
+                except json.JSONDecodeError:
+                    continue
+                if event.get("type") == "content_block_delta":
+                    delta = event.get("delta", {})
+                    if delta.get("type") == "text_delta":
+                        text = delta.get("text", "")
+                        if text:
+                            yield text
+        finally:
+            resp.close()

codeforerunner/providers/base.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Protocol
+from typing import Iterator, Protocol
 
 
 @dataclass(frozen=True)
@@ -26,6 +26,14 @@ class Provider(Protocol):
         api_key: str | None = None,
     ) -> CompletionResult: ...
 
+    def stream(
+        self,
+        *,
+        prompt: str,
+        model: str | None = None,
+        api_key: str | None = None,
+    ) -> Iterator[str]: ...
+
 
 class ProviderError(Exception):
     """Raised on provider HTTP failures, missing keys, or malformed responses."""

codeforerunner/providers/google.py

@@ -6,6 +6,7 @@ import json
 import urllib.error
 import urllib.parse
 import urllib.request
+from typing import Iterator
 
 from codeforerunner.providers.base import CompletionResult, ProviderError
 
@@ -18,6 +19,10 @@ class GoogleProvider:
     endpoint_template = (
         "https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={key}"
     )
+    stream_endpoint_template = (
+        "https://generativelanguage.googleapis.com/v1beta/models/{model}:streamGenerateContent"
+        "?key={key}&alt=sse"
+    )
 
     def complete(
         self,
@@ -60,3 +65,48 @@ class GoogleProvider:
             model=data.get("modelVersion", model),
             usage=data.get("usageMetadata"),
         )
+
+    def stream(
+        self,
+        *,
+        prompt: str,
+        model: str | None = None,
+        api_key: str | None = None,
+    ) -> Iterator[str]:
+        if not api_key:
+            raise ProviderError(f"missing API key (set ${self.default_env_var})")
+        model = model or self.default_model
+        url = self.stream_endpoint_template.format(
+            model=urllib.parse.quote(model, safe=""),
+            key=urllib.parse.quote(api_key, safe=""),
+        )
+        body = json.dumps(
+            {"contents": [{"parts": [{"text": prompt}]}]}
+        ).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=body,
+            method="POST",
+            headers={"content-type": "application/json"},
+        )
+        try:
+            resp = urllib.request.urlopen(req)
+        except urllib.error.HTTPError as e:
+            snippet = (e.read() or b"")[:500].decode("utf-8", errors="replace")
+            raise ProviderError(f"HTTP {e.code}: {snippet}") from e
+        except urllib.error.URLError as e:
+            raise ProviderError(f"network error: {e.reason}") from e
+        try:
+            for raw_line in resp:
+                line = raw_line.decode("utf-8").rstrip("\n")
+                if not line.startswith("data: "):
+                    continue
+                try:
+                    event = json.loads(line[6:])
+                    text = event["candidates"][0]["content"]["parts"][0]["text"]
+                    if text:
+                        yield text
+                except (json.JSONDecodeError, KeyError, IndexError, TypeError):
+                    continue
+        finally:
+            resp.close()

codeforerunner/providers/ollama.py

@@ -6,12 +6,23 @@ import json
 import os
 import urllib.error
 import urllib.request
+from typing import Iterator
 
 from codeforerunner.providers.base import CompletionResult, ProviderError
 
 DEFAULT_HOST = "http://localhost:11434"
 
 
+def is_available(host: str | None = None) -> bool:
+    """Return True if an Ollama instance is reachable at the configured host."""
+    base = (host or os.environ.get("OLLAMA_HOST") or DEFAULT_HOST).rstrip("/")
+    try:
+        urllib.request.urlopen(f"{base}/api/tags", timeout=2)
+        return True
+    except Exception:
+        return False
+
+
 class OllamaProvider:
     name = "ollama"
     default_env_var = "OLLAMA_HOST"
@@ -54,3 +65,47 @@ class OllamaProvider:
         usage_keys = ("prompt_eval_count", "eval_count", "total_duration")
         usage = {k: data[k] for k in usage_keys if k in data} or None
         return CompletionResult(text=text, model=data.get("model", model), usage=usage)
+
+    def stream(
+        self,
+        *,
+        prompt: str,
+        model: str | None = None,
+        api_key: str | None = None,
+    ) -> Iterator[str]:
+        base = api_key or os.environ.get(self.default_env_var) or DEFAULT_HOST
+        base = base.rstrip("/")
+        model = model or self.default_model
+        url = f"{base}/api/generate"
+        body = json.dumps(
+            {"model": model, "prompt": prompt, "stream": True}
+        ).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=body,
+            method="POST",
+            headers={"content-type": "application/json"},
+        )
+        try:
+            resp = urllib.request.urlopen(req)
+        except urllib.error.HTTPError as e:
+            snippet = (e.read() or b"")[:500].decode("utf-8", errors="replace")
+            raise ProviderError(f"HTTP {e.code}: {snippet}") from e
+        except urllib.error.URLError as e:
+            raise ProviderError(f"network error: {e.reason}") from e
+        try:
+            for raw_line in resp:
+                line = raw_line.decode("utf-8").strip()
+                if not line:
+                    continue
+                try:
+                    event = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                text = event.get("response", "")
+                if text:
+                    yield text
+                if event.get("done", False):
+                    break
+        finally:
+            resp.close()

codeforerunner/providers/openai.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import urllib.error
 import urllib.request
+from typing import Iterator
 
 from codeforerunner.providers.base import CompletionResult, ProviderError
 
@@ -57,3 +58,56 @@ class OpenAIProvider:
         return CompletionResult(
             text=text, model=data.get("model", model), usage=data.get("usage")
         )
+
+    def stream(
+        self,
+        *,
+        prompt: str,
+        model: str | None = None,
+        api_key: str | None = None,
+    ) -> Iterator[str]:
+        if not api_key:
+            raise ProviderError(f"missing API key (set ${self.default_env_var})")
+        model = model or self.default_model
+        body = json.dumps(
+            {
+                "model": model,
+                "stream": True,
+                "messages": [{"role": "user", "content": prompt}],
+            }
+        ).encode("utf-8")
+        req = urllib.request.Request(
+            self.endpoint,
+            data=body,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "content-type": "application/json",
+            },
+        )
+        try:
+            resp = urllib.request.urlopen(req)
+        except urllib.error.HTTPError as e:
+            snippet = (e.read() or b"")[:500].decode("utf-8", errors="replace")
+            raise ProviderError(f"HTTP {e.code}: {snippet}") from e
+        except urllib.error.URLError as e:
+            raise ProviderError(f"network error: {e.reason}") from e
+        try:
+            for raw_line in resp:
+                line = raw_line.decode("utf-8").rstrip("\n")
+                if not line.startswith("data: "):
+                    continue
+                payload = line[6:]
+                if payload.strip() == "[DONE]":
+                    break
+                try:
+                    event = json.loads(payload)
+                except json.JSONDecodeError:
+                    continue
+                choices = event.get("choices", [])
+                if choices:
+                    text = choices[0].get("delta", {}).get("content")
+                    if text:
+                        yield text
+        finally:
+            resp.close()

codeforerunner-0.4.0.dist-info/METADATA

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: codeforerunner
+Version: 0.4.0
+Summary: Model-agnostic repository documentation tooling (prompt-first; thin CLI).
+Author: Derek Palmer
+License-Expression: LicenseRef-Codeforerunner-SAL-0.1
+Project-URL: Repository, https://github.com/derek-palmer/codeforerunner
+Project-URL: Issues, https://github.com/derek-palmer/codeforerunner/issues
+Keywords: repository-documentation,developer-tools,agent-tooling,code-generation,prompt-engineering,mcp,llm,documentation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+![codeForerunner — your codebase gets a Forerunner; your docs finally see the light](images/readme_banner.png)
+
+# codeForerunner
+
+Model-agnostic repository documentation tooling. Ships a prompt pack for codebase analysis and doc generation, a thin Python CLI, an MCP server, drift-detection rules that keep docs honest — and native slash-command skills for Claude Code, Codex, Gemini CLI, and other agent CLIs.
+
+## Two modes
+
+### Mode A — Agent skill (recommended, no API key required)
+
+Install forerunner's prompt pack as skills into your agent CLI. Each documentation task becomes a slash command (`/forerunner-readme`, `/forerunner-check`, etc.) available inside Claude Code, Codex, Gemini CLI, and other agents. Authentication is handled by your existing agent subscription — no separate API key needed.
+
+```bash
+# From a cloned repo
+./install.sh
+
+# One-liner (auto-detects Claude Code, Codex, Gemini CLI)
+curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
+
+# Windows
+irm https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.ps1 | iex
+
+# Via forerunner CLI (after pip install)
+forerunner install --all claude
+forerunner install --all codex
+```
+
+Then in your agent:
+
+```
+/forerunner-scan        ← scan the repo first
+/forerunner-readme      ← generate README
+/forerunner-check       ← detect doc drift
+```
+
+### Mode B — Direct API (needs API key or Ollama)
+
+Install the Python CLI and call your provider directly. Works without any agent CLI installed.
+
+```bash
+pipx install codeforerunner   # recommended
+pip install codeforerunner    # alternative
+```
+
+Configure a provider (or start Ollama for keyless local generation):
+
+```bash
+export ANTHROPIC_API_KEY=sk-...
+forerunner generate readme --stream
+```
+
+If no API key and no `--provider` flag, forerunner auto-detects Ollama at `localhost:11434` and falls back to local mode.
+
+## Slash commands
+
+| Command | Task | Purpose |
+|---------|------|---------|
+| `/forerunner-scan` | `scan` | Collect repo evidence (run first) |
+| `/forerunner-readme` | `readme` | Generate or refresh README.md |
+| `/forerunner-api-docs` | `api-docs` | Generate API reference docs |
+| `/forerunner-diagrams` | `diagrams` | Generate Mermaid architecture diagrams |
+| `/forerunner-flows` | `flows` | Document system flows |
+| `/forerunner-stack-docs` | `stack-docs` | Stack-specific developer docs |
+| `/forerunner-version-audit` | `version-audit` | Audit pinned versions vs EOL |
+| `/forerunner-check` | `check` | Check docs for staleness |
+| `/forerunner-review` | `review` | Doc-impact summary for PR review |
+| `/forerunner-audit` | `audit` | Security and dependency audit |
+| `/forerunner-changelog` | `changelog` | Generate changelog from git log |
+| `/forerunner-init` | `init-agent-onboarding` | Bootstrap or refresh AGENTS.md |
+
+Slash command availability depends on the agent CLI. Claude Code, Codex, and Gemini CLI support all 12 commands after install.
+
+## Skill install options
+
+| Flag | Effect |
+|------|--------|
+| `./install.sh` | Auto-detect all agents, install all skills |
+| `./install.sh --only claude` | Claude Code only |
+| `./install.sh --only codex` | Codex only |
+| `./install.sh --only gemini` | Gemini CLI only |
+| `./install.sh --dry-run` | Preview, write nothing |
+| `./install.sh --list` | Show detected agents + skill list |
+| `./install.sh --uninstall` | Remove all installed skills |
+
+## CLI
+
+```bash
+pip install codeforerunner
+```
+
+| Command | Purpose |
+|---------|---------|
+| `forerunner init` | Resolve agent-onboarding bundle to stdout. |
+| `forerunner scan` | Resolve scan bundle to stdout. |
+| `forerunner doc <task>` | Resolve `base + partials + task` bundle to stdout. |
+| `forerunner check` | Run drift-detection rules; no-op without `forerunner.config.yaml`. |
+| `forerunner generate <task>` | Call configured provider directly. Add `--stream` for token-by-token output. Falls back to Ollama automatically when no API key is configured. |
+| `forerunner doctor` | Health report: skill parity, config, provider key, local-mode status. Add `--fix` to write a starter config. |
+| `forerunner mcp-server` | Serve prompt bundles as MCP tools over stdio (JSON-RPC 2.0). |
+| `forerunner install <agent>` | Install canonical skill into agent-specific directory. Add `--all` for all per-task skills. |
+
+## Prompt pack
+
+Prompts are bundled inside the package at `src/codeforerunner/prompts/`.
+
+```text
+prompts/
+├── system/base.md
+├── partials/
+│   ├── context-format.md
+│   ├── output-rules.md
+│   └── stack-hints.md
+└── tasks/
+    ├── scan.md          api-docs.md    audit.md
+    ├── readme.md        diagrams.md    changelog.md
+    ├── check.md         flows.md       version-audit.md
+    ├── review.md        stack-docs.md
+    └── init-agent-onboarding.md
+```
+
+## Quick start (agent skill mode)
+
+```bash
+# Install skills into Claude Code
+curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
+
+# In Claude Code:
+# /forerunner-scan    → scans your repo
+# /forerunner-readme  → generates README.md
+# /forerunner-check   → checks for doc drift
+```
+
+## Quick start (direct API mode)
+
+```bash
+# 1. Install and configure
+pip install codeforerunner
+export ANTHROPIC_API_KEY=sk-...
+
+# 2. Run a task
+forerunner generate readme --stream
+
+# 3. Enable drift detection
+forerunner doctor --fix        # writes forerunner.config.yaml
+forerunner check               # run any time or as pre-commit hook
+```
+
+## GitHub Action
+
+```yaml
+- uses: derek-palmer/codeforerunner@v0.3.2
+```
+
+No-op when `forerunner.config.yaml` is absent.
+
+## Configuration
+
+Copy `forerunner.config.yaml.example` to `forerunner.config.yaml` to opt in to drift rules. Generate a starter config with:
+
+```bash
+forerunner doctor --fix
+```
+
+### Config fields
+
+```yaml
+provider: anthropic          # anthropic | openai | google | ollama
+model: claude-opus-4-7
+api_key_env:
+  anthropic: ANTHROPIC_API_KEY
+
+tasks:
+  check:
+    enabled_rules:
+      - R1-no-cli
+      - R2-no-pre-commit
+      - R3-no-ci
+      - R4-no-installer
+      - R5-no-python-package
+      - R7-no-mcp
+      - R8-no-marketplace
+      - RI1-missing-cli
+      - RI5-missing-python-package
+      - RI7-missing-mcp
+      - RV1-version-drift
+    ignore_paths:
+      - docs/legacy/**/*.md
+```
+
+### Drift rules
+
+| Rule | Fires when |
+|------|-----------|
+| `R1-no-cli` | Doc denies having a CLI, but `cli.py` is present |
+| `R2-no-pre-commit` | Doc denies having pre-commit hooks, but `.pre-commit-hooks.yaml` present |
+| `R3-no-ci` | Doc denies having CI, but `.github/workflows/*.yml` present |
+| `R4-no-installer` | Doc denies having an installer, but `installer.py` present |
+| `R5-no-python-package` | Doc denies having a Python package, but `pyproject.toml` present |
+| `R6-no-docker` | Doc denies having Docker, but `Dockerfile`/`compose.yml` present |
+| `R7-no-mcp` | Doc denies having an MCP server, but `mcp_server.py` present |
+| `R8-no-marketplace` | Doc denies having a marketplace, but `marketplace.json` present |
+| `RI1-missing-cli` | Doc references `forerunner` subcommands but `cli.py` absent |
+| `RI5-missing-python-package` | Doc shows `pip install codeforerunner` but `pyproject.toml` absent |
+| `RI7-missing-mcp` | Doc references `forerunner mcp-server` but `mcp_server.py` absent |
+| `RV1-version-drift` | Doc pins `codeforerunner==X.Y.Z` differing from current version |
+
+## MCP Server
+
+`forerunner mcp-server` speaks JSON-RPC 2.0 over stdio and exposes one tool per `prompts/tasks/*.md`. A scan-first gate enforces SPEC V2: any tool except `scan` or `init-agent-onboarding` returns an error until `scan` has been called in the same session.
+
+See `examples/mcp/` for Claude Desktop and mcp-cli wiring examples.
+
+## Providers
+
+`forerunner generate` supports four providers. When no provider is explicitly configured and no API key is found, forerunner probes `localhost:11434` and falls back to Ollama automatically.
+
+| Provider | Env var | Default model |
+|----------|---------|---------------|
+| `anthropic` | `ANTHROPIC_API_KEY` | `claude-opus-4-7` |
+| `openai` | `OPENAI_API_KEY` | `gpt-4o` |
+| `google` | `GOOGLE_API_KEY` | `gemini-2.5-pro` |
+| `ollama` | `OLLAMA_HOST` (optional) | `llama3` |
+
+## Docs and spec
+
+- `SPEC.md` — canonical phase/task tracker
+- `docs/getting-started.md` — manual prompt use
+- `docs/prompt-guide.md` — how system, partial, and task prompts compose
+- `docs/editor-agent-setup.md` — adapting prompts to local agents
+- `docs/roadmap.md` — human-readable roadmap
+- `docs/agent-distribution-design.md` — packaging and installer design

{codeforerunner-0.3.1.dist-info → codeforerunner-0.4.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
 codeforerunner/__init__.py,sha256=4ItVS_FzLddTK77jExpkV3QJ1nHl2Bh-QIujM7Hg_5w,205
 codeforerunner/bundle.py,sha256=wWlhNaja8HPLzN-9pxiSrFD8X0mGi-c1HM9HRyVhmzk,2020
-codeforerunner/check.py,sha256=kSrVoTVb9ALEBHvUerR2nZfroXco_yz6gMgXzdz45Ac,4905
-codeforerunner/cli.py,sha256=3eJtUhfOj_ZMPAYPHvlQ7P-eBs2NRIpzewipqvOpy9w,7981
+codeforerunner/check.py,sha256=5sJVwMMSvVCrRmwBIunYbn2pINroUjONrVJAs5ov3O4,8188
+codeforerunner/cli.py,sha256=fBojCOPEEzQdXxYB0Intjhax90l7Rz7sfsgeFpozP58,9633
 codeforerunner/config.py,sha256=REs4FgmSSn7R2tLIwLJPL8VmSCGkTvw8J2SqBOggzho,6206
-codeforerunner/doctor.py,sha256=AFHY8YbqTp726JcxLAYvrdeOLwr6WLPiNUUF2QYOwL8,10076
-codeforerunner/installer.py,sha256=9Ze_hyjvow-if-NMovk9CzVDYVZSR3vyLO6s2vhOs6g,10227
+codeforerunner/doctor.py,sha256=4VE7nCGdJKpzWtqK3ut-SbrOENdfLNLuvA_wxn-5fcM,10859
+codeforerunner/installer.py,sha256=60CMYbV8di-0iLE8jbsLGScdgU5VSJTOO_PhoBtqYYY,13395
 codeforerunner/mcp_server.py,sha256=oIfuAR7e_rH--B1aLOATVflyWAyGpkyeeXI4SAI4eTg,4657
 codeforerunner/prompts/partials/context-format.md,sha256=WNfkr4kf2Awj0R8wLOrFotEiYCe6hfKTq5eA3Rt5_Xw,817
 codeforerunner/prompts/partials/output-rules.md,sha256=vfIAX-ImxCa-MVAeNH896uSIO7-cKbJd0KohkgHIiD8,1731
@@ -22,15 +22,15 @@ codeforerunner/prompts/tasks/review.md,sha256=IRdIXAKvv0JMOE5WtrnlO1Cd4LHXtcJqb1
 codeforerunner/prompts/tasks/scan.md,sha256=hYXf-IL1kgpBPHJapRrwTu88cLZ7y3bCmAq9HY0yG3U,2300
 codeforerunner/prompts/tasks/stack-docs.md,sha256=Dy-JSXpSmHSyhR5shQBXKa_F0PqnjPcmtljthYZpaiM,1923
 codeforerunner/prompts/tasks/version-audit.md,sha256=oK-pcoxt_VcvDOlj1Sz9OlEhXlcViLPn54r-qP5WfiA,5833
-codeforerunner/providers/__init__.py,sha256=ttMAbHWJIO8s-8H6Kb_EWf3LN5oMzlmX1D12RyGSmIg,962
-codeforerunner/providers/anthropic.py,sha256=zaJDyzH1vPr7nSqUOv6avlTk3covpkWXLHae2-bS9io,2021
-codeforerunner/providers/base.py,sha256=Jk9vBeRNxH9naUC6stN5jY1KHmhrqg2k2kMGOhbQTYk,752
-codeforerunner/providers/google.py,sha256=wBpbte8hdX_Jnr_JBHvQarogT6T1hWR4aGF5O2exBCU,2109
-codeforerunner/providers/ollama.py,sha256=bKhigdjHs3aw73iB5uQka9_n-XCjv1sh_zZfe1TrWTQ,1975
-codeforerunner/providers/openai.py,sha256=OHWeZ11OuHPgQBMwqJnJWxNHyGIP5KL7B06w2ttgxlY,1952
-codeforerunner-0.3.1.dist-info/licenses/LICENSE.md,sha256=iIhmJHib6GbdjcwiDMM-npiNRf3XgASom1WsOJivEdc,2915
-codeforerunner-0.3.1.dist-info/METADATA,sha256=koodiwqaG0vZYUyvQgkhSy7ggb0s6ldTEJazVtCyrec,7737
-codeforerunner-0.3.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-codeforerunner-0.3.1.dist-info/entry_points.txt,sha256=3p8BbPlq-wfcXk42tsweKePRaGlZ1WXho1gOkuZGyIQ,55
-codeforerunner-0.3.1.dist-info/top_level.txt,sha256=pV1rt0-NIpNEotKXpL_sF2060DHr-_0F86LWhUlvXis,15
-codeforerunner-0.3.1.dist-info/RECORD,,
+codeforerunner/providers/__init__.py,sha256=hoLODdqQ-beA7-MVFR6aoE29ZUSzxGVPLhwNXNN1xw4,1020
+codeforerunner/providers/anthropic.py,sha256=kECeFMCeSJHcsUPvF93ECv52wXmLR6H21rFNwPzRhaM,4049
+codeforerunner/providers/base.py,sha256=MMrOUVOXHWP1td-TndxhLhDyDPJZGExZCeFopZUSRCo,923
+codeforerunner/providers/google.py,sha256=OWEE0FNupFWmZCeilIrgYUYDHH1iWvIwHEEsHYQoFFY,3979
+codeforerunner/providers/ollama.py,sha256=Q8ACojaeiBgPQgDFxP7KKM5r4Ccu6dDspNFza1vbOzw,3871
+codeforerunner/providers/openai.py,sha256=999ZzIVh0cqW4xDnzK_NACqfJxNziHwpVjwmw9_jjRw,3825
+codeforerunner-0.4.0.dist-info/licenses/LICENSE.md,sha256=iIhmJHib6GbdjcwiDMM-npiNRf3XgASom1WsOJivEdc,2915
+codeforerunner-0.4.0.dist-info/METADATA,sha256=hCzFSOjHkJ6iNZLYkgvHDpgjlM5P_D0OWP9zTW66pLc,9873
+codeforerunner-0.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+codeforerunner-0.4.0.dist-info/entry_points.txt,sha256=3p8BbPlq-wfcXk42tsweKePRaGlZ1WXho1gOkuZGyIQ,55
+codeforerunner-0.4.0.dist-info/top_level.txt,sha256=pV1rt0-NIpNEotKXpL_sF2060DHr-_0F86LWhUlvXis,15
+codeforerunner-0.4.0.dist-info/RECORD,,

codeforerunner-0.3.1.dist-info/METADATA

@@ -1,133 +0,0 @@
-Metadata-Version: 2.4
-Name: codeforerunner
-Version: 0.3.1
-Summary: Model-agnostic repository documentation tooling (prompt-first; thin CLI).
-Author: Derek Palmer
-License-Expression: LicenseRef-Codeforerunner-SAL-0.1
-Project-URL: Repository, https://github.com/derek-palmer/codeforerunner
-Project-URL: Issues, https://github.com/derek-palmer/codeforerunner/issues
-Keywords: repository-documentation,developer-tools,agent-tooling,code-generation,prompt-engineering,mcp,llm,documentation
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Documentation
-Classifier: Topic :: Software Development :: Documentation
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: Utilities
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE.md
-Requires-Dist: PyYAML>=6.0
-Dynamic: license-file
-
-![codeForerunner — your codebase gets a Forerunner; your docs finally see the light](images/readme_banner.png)
-
-# codeForerunner
-
-CodeForerunner is a model-agnostic documentation agent that acts as overwatch for your repository, automatically analyzing code and maintaining docs, diagrams, and architecture knowledge as your codebase evolves over time.
-
-The current repo is the prompt-first foundation for that agent: it ships prompt assets for understanding a codebase and generating developer docs. A thin Python CLI (including `forerunner mcp-server` and a scoped `forerunner init --full / --agents-only`), an idempotent skill installer, pre-commit + CI hooks, and a PyPI publish workflow now wrap those prompts; the first published PyPI release remains pending.
-
-## Current State
-
-- Core product: Markdown prompts in `prompts/`.
-- Agent package artifacts: Codex plugin files under `plugins/codeforerunner/` and Claude Code plugin files under `.claude-plugin/` plus `skills/codeforerunner/`.
-- Python package: `pyproject.toml` + `src/codeforerunner/` expose a `forerunner` console script. `forerunner doc <task>` resolves the prompt bundle (base + partials + task) to stdout; `forerunner install <agent>` idempotently writes the canonical skill into agent-specific directories; `forerunner init` resolves the agent-onboarding bundle (with `--full` to prepend a scan or `--agents-only` for the default scope); `forerunner scan` resolves the scan bundle; `forerunner mcp-server` serves prompt bundles as MCP tools over stdio.
-- Hooks: `.pre-commit-hooks.yaml` exposes a `forerunner-check` hook; `.github/workflows/forerunner-check.yml` mirrors it in CI. Both no-op when `forerunner.config.yaml` is absent.
-- Current config: `forerunner.config.yaml.example` documents the schema now parsed by `src/codeforerunner/config.py`; see "Configuration" below.
-- Not currently present: Docker image, Makefile, published PyPI release.
-
-## Install
-
-After the first PyPI release:
-
-```bash
-pipx install codeforerunner   # recommended; isolated environment
-pip install codeforerunner    # alternative
-```
-
-From source:
-
-```bash
-git clone https://github.com/derek-palmer/codeForerunner
-cd codeForerunner
-python -m pip install -e .
-```
-
-Then `forerunner --help` should print the subcommand list.
-
-## Prompt Layout
-
-```text
-prompts/
-├── system/
-│   └── base.md
-├── partials/
-│   ├── context-format.md
-│   ├── output-rules.md
-│   └── stack-hints.md
-└── tasks/
-    ├── scan.md
-    ├── init-agent-onboarding.md
-    ├── readme.md
-    ├── api-docs.md
-    ├── stack-docs.md
-    ├── diagrams.md
-    ├── flows.md
-    ├── version-audit.md
-    ├── check.md
-    └── review.md
-```
-
-## Quick Start
-
-1. Open `prompts/system/base.md` and use it as the agent system or project instruction.
-2. Assemble repo context using the shape in `prompts/partials/context-format.md`.
-3. For documentation generation, run `prompts/tasks/scan.md` first.
-4. For agent onboarding only, run `prompts/tasks/init-agent-onboarding.md` directly.
-5. Pass the scan result into one downstream documentation prompt, such as `prompts/tasks/readme.md` or `prompts/tasks/stack-docs.md`.
-6. Apply generated docs only after checking that every claim is grounded in provided files.
-
-## What The Prompts Do
-
-| Prompt | Purpose |
-| --- | --- |
-| `prompts/system/base.md` | Defines the codeforerunner role, quality bar, Markdown rules, and accuracy constraints. |
-| `prompts/tasks/scan.md` | Produces the first structured repo scan used by downstream tasks. |
-| `prompts/tasks/init-agent-onboarding.md` | Generates or updates `AGENTS.md` from repo evidence plus files such as `CLAUDE.md`, `.cursor/rules/*`, `.cursorrules`, `.github/copilot-instructions.md`, and `opencode.json`. |
-| `prompts/tasks/readme.md` | Generates or rewrites a top-level README from scan output and selected files. |
-| `prompts/tasks/api-docs.md` | Documents public APIs when endpoints/interfaces are evident. |
-| `prompts/tasks/stack-docs.md` | Documents stack-specific areas of a repo. |
-| `prompts/tasks/diagrams.md` | Generates Mermaid architecture or flow diagrams. |
-| `prompts/tasks/flows.md` | Documents user, request, job, or data flows. |
-| `prompts/tasks/version-audit.md` | Audits pinned versions from manifests, lockfiles, Dockerfiles, workflows, or IaC. |
-| `prompts/tasks/check.md` | Checks existing docs for staleness against a fresh scan. |
-| `prompts/tasks/review.md` | Summarizes documentation impact for review. |
-
-## Docs And Spec
-
-- `SPEC.md` tracks phases, invariants, and tasks so future PRs can make small status updates instead of broad rewrites.
-- `docs/getting-started.md` explains manual prompt use.
-- `docs/prompt-guide.md` explains how system, partial, and task prompts compose.
-- `docs/editor-agent-setup.md` explains how to adapt prompts to local agents.
-- `docs/roadmap.md` mirrors the `SPEC.md` phase status in human-readable form.
-- `docs/agent-distribution-design.md` records the design that backs the Codex/Claude packages and `forerunner install`.
-
-## Configuration
-
-`forerunner.config.yaml.example` documents the loaded schema. Copy it to `forerunner.config.yaml` to opt in; without that file, `forerunner check` is a silent no-op. The schema has top-level provider/model fields (`provider`, `model`, `api_key_env`, `output_dir`, `context_max_files`, `context_max_lines_per_file`, `approaching_eol_threshold_months`), `ignore_patterns`, `tasks.version_audit`, and `tasks.check`. `forerunner check` honors `tasks.check.enabled_rules` (allowlist of rule IDs, default all) and `tasks.check.ignore_paths` (fnmatch globs applied to scanned docs). Invalid YAML, unknown providers, unknown `api_key_env` providers, or unknown severities surface as a `ConfigError` and exit non-zero.
-
-### MCP Server
-
-`forerunner mcp-server` speaks JSON-RPC 2.0 over stdio and exposes one tool per `prompts/tasks/*.md` (tool name = filename stem). Each `tools/call` returns the resolved `base + partials + task` bundle as text. A scan-first gate enforces SPEC V2: any tool other than `scan` or `init-agent-onboarding` returns an error until `scan` has been called in the same session. Point any MCP-compatible client at `forerunner mcp-server` as a stdio server (running from the target repo so `prompts/tasks/` resolves).
-
-See `examples/mcp/` for Claude Desktop and mcp-cli wiring examples.
-
-## Roadmap
-
-See `SPEC.md` for the canonical phase/task tracker and `docs/roadmap.md` for the human-readable roadmap.