codeforerunner 0.4.3__tar.gz → 0.4.5__tar.gz

{codeforerunner-0.4.3/src/codeforerunner.egg-info → codeforerunner-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeforerunner
-Version: 0.4.3
+Version: 0.4.5
 Summary: Model-agnostic repository documentation tooling (prompt-first; thin CLI).
 Author: Derek Palmer
 License-Expression: LicenseRef-Codeforerunner-SAL-0.1
@@ -29,11 +29,11 @@ Dynamic: license-file
 
 # 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.
+[![Socket Badge](https://badge.socket.dev/npm/package/codeforerunner/0.4.5)](https://socket.dev/npm/package/codeforerunner)
 
-## Two modes
+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.
 
-### Mode A — Agent skill (recommended, no API key required)
+## Install
 
 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.
 
@@ -44,10 +44,15 @@ Install forerunner's prompt pack as skills into your agent CLI. Each documentati
 # One-liner (auto-detects Claude Code, Codex, Gemini CLI)
 curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
 
+# npm
+npx -y codeforerunner
+npm install -g codeforerunner
+
 # Windows
 irm https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.ps1 | iex
 
-# Via forerunner CLI (after pip install)
+# Via Python CLI
+pip install codeforerunner
 forerunner install --all claude
 forerunner install --all codex
 ```
@@ -58,26 +63,9 @@ Then in your agent:
 /forerunner-scan        ← scan the repo first
 /forerunner-readme      ← generate README
 /forerunner-check       ← detect doc drift
+/forerunner-refresh     ← scan + update all stale docs
 ```
 
-### 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 |
@@ -87,6 +75,7 @@ If no API key and no `--provider` flag, forerunner auto-detects Ollama at `local
 | `/forerunner-api-docs` | `api-docs` | Generate API reference docs |
 | `/forerunner-diagrams` | `diagrams` | Generate Mermaid architecture diagrams |
 | `/forerunner-flows` | `flows` | Document system flows |
+| `/forerunner-arch-review` | `arch-review` | Rank architecture improvement candidates, inspired by Matt Pocock's [`/improve-codebase-architecture`](https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture) |
 | `/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 |
@@ -94,14 +83,17 @@ If no API key and no `--provider` flag, forerunner auto-detects Ollama at `local
 | `/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 |
+| `/forerunner-refresh` | `refresh` | Scan + check + update all stale docs in one pass |
 
-Slash command availability depends on the agent CLI. Claude Code, Codex, and Gemini CLI support all 12 commands after install.
+Slash command availability depends on the agent CLI. Claude Code, Codex, and Gemini CLI support all commands after install.
 
 ## Skill install options
 
 | Flag | Effect |
 |------|--------|
-| `./install.sh` | Auto-detect all agents, install all skills |
+| `./install.sh` | Auto-detect all agents, prompt global vs local, install all skills |
+| `./install.sh --global` | Skip prompt, install to global agent dirs (all projects) |
+| `./install.sh --local` | Skip prompt, install to `.claude/skills/` and `.agents/skills/` in cwd |
 | `./install.sh --only claude` | Claude Code only |
 | `./install.sh --only codex` | Codex only |
 | `./install.sh --only gemini` | Gemini CLI only |
@@ -120,65 +112,57 @@ pip install codeforerunner
 | `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 refresh` | Output scan + check + all doc-task bundles in sequence for a full doc refresh. |
 | `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 doctor` | Health report: skill parity, config. 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)
+## Quick start
 
 ```bash
 # Install skills into Claude Code
 curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
 
+# Or via npm
+# npx -y codeforerunner
+
 # In Claude Code:
-# /forerunner-scan    → scans your repo
-# /forerunner-readme  → generates README.md
-# /forerunner-check   → checks for doc drift
+# /forerunner-scan     → scans your repo
+# /forerunner-readme   → generates README.md
+# /forerunner-refresh  → updates all stale docs
+# /forerunner-check    → checks for doc drift
 ```
 
-## Quick start (direct API mode)
-
-```bash
-# 1. Install and configure
-pip install codeforerunner
-export ANTHROPIC_API_KEY=sk-...
+## GitHub Action
 
-# 2. Run a task
-forerunner generate readme --stream
+Add doc-drift detection to any repo's CI — fails the PR if docs contradict repo state.
 
-# 3. Enable drift detection
-forerunner doctor --fix        # writes forerunner.config.yaml
-forerunner check               # run any time or as pre-commit hook
+```yaml
+# .github/workflows/doc-check.yml
+name: Doc Check
+on: [push, pull_request]
+
+jobs:
+  doc-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+      - uses: derek-palmer/codeforerunner@v0.4.5
+        with:
+          fail-on-drift: "true"   # set "false" to warn-only
 ```
 
-## GitHub Action
+No-op when `forerunner.config.yaml` is absent — safe to add before configuring rules.
 
-```yaml
-- uses: derek-palmer/codeforerunner@v0.4.2
-```
+**Inputs**
 
-No-op when `forerunner.config.yaml` is absent.
+| Input | Default | Description |
+|-------|---------|-------------|
+| `version` | `latest` | `codeforerunner` version to install |
+| `python-version` | `3.11` | Python version |
+| `repo` | workspace root | Path to check |
+| `fail-on-drift` | `true` | Exit non-zero on drift |
 
 ## Configuration
 
@@ -191,10 +175,7 @@ forerunner doctor --fix
 ### Config fields
 
 ```yaml
-provider: anthropic          # anthropic | openai | google | ollama
-model: claude-opus-4-7
-api_key_env:
-  anthropic: ANTHROPIC_API_KEY
+approaching_eol_threshold_months: 6
 
 tasks:
   check:
@@ -237,20 +218,28 @@ tasks:
 
 See `examples/mcp/` for Claude Desktop and mcp-cli wiring examples.
 
-## Providers
+## Prompt pack
 
-`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.
+Prompts are bundled inside the package at `src/codeforerunner/prompts/`.
 
-| 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` |
+```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  arch-review.md
+    ├── refresh.md
+    └── init-agent-onboarding.md
+```
 
-## Docs and spec
+## Docs
 
-- `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

{codeforerunner-0.4.3 → codeforerunner-0.4.5}/README.md

@@ -2,11 +2,11 @@
 
 # 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.
+[![Socket Badge](https://badge.socket.dev/npm/package/codeforerunner/0.4.5)](https://socket.dev/npm/package/codeforerunner)
 
-## Two modes
+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.
 
-### Mode A — Agent skill (recommended, no API key required)
+## Install
 
 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.
 
@@ -17,10 +17,15 @@ Install forerunner's prompt pack as skills into your agent CLI. Each documentati
 # One-liner (auto-detects Claude Code, Codex, Gemini CLI)
 curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
 
+# npm
+npx -y codeforerunner
+npm install -g codeforerunner
+
 # Windows
 irm https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.ps1 | iex
 
-# Via forerunner CLI (after pip install)
+# Via Python CLI
+pip install codeforerunner
 forerunner install --all claude
 forerunner install --all codex
 ```
@@ -31,26 +36,9 @@ Then in your agent:
 /forerunner-scan        ← scan the repo first
 /forerunner-readme      ← generate README
 /forerunner-check       ← detect doc drift
+/forerunner-refresh     ← scan + update all stale docs
 ```
 
-### 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 |
@@ -60,6 +48,7 @@ If no API key and no `--provider` flag, forerunner auto-detects Ollama at `local
 | `/forerunner-api-docs` | `api-docs` | Generate API reference docs |
 | `/forerunner-diagrams` | `diagrams` | Generate Mermaid architecture diagrams |
 | `/forerunner-flows` | `flows` | Document system flows |
+| `/forerunner-arch-review` | `arch-review` | Rank architecture improvement candidates, inspired by Matt Pocock's [`/improve-codebase-architecture`](https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture) |
 | `/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 |
@@ -67,14 +56,17 @@ If no API key and no `--provider` flag, forerunner auto-detects Ollama at `local
 | `/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 |
+| `/forerunner-refresh` | `refresh` | Scan + check + update all stale docs in one pass |
 
-Slash command availability depends on the agent CLI. Claude Code, Codex, and Gemini CLI support all 12 commands after install.
+Slash command availability depends on the agent CLI. Claude Code, Codex, and Gemini CLI support all commands after install.
 
 ## Skill install options
 
 | Flag | Effect |
 |------|--------|
-| `./install.sh` | Auto-detect all agents, install all skills |
+| `./install.sh` | Auto-detect all agents, prompt global vs local, install all skills |
+| `./install.sh --global` | Skip prompt, install to global agent dirs (all projects) |
+| `./install.sh --local` | Skip prompt, install to `.claude/skills/` and `.agents/skills/` in cwd |
 | `./install.sh --only claude` | Claude Code only |
 | `./install.sh --only codex` | Codex only |
 | `./install.sh --only gemini` | Gemini CLI only |
@@ -93,65 +85,57 @@ pip install codeforerunner
 | `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 refresh` | Output scan + check + all doc-task bundles in sequence for a full doc refresh. |
 | `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 doctor` | Health report: skill parity, config. 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)
+## Quick start
 
 ```bash
 # Install skills into Claude Code
 curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
 
+# Or via npm
+# npx -y codeforerunner
+
 # In Claude Code:
-# /forerunner-scan    → scans your repo
-# /forerunner-readme  → generates README.md
-# /forerunner-check   → checks for doc drift
+# /forerunner-scan     → scans your repo
+# /forerunner-readme   → generates README.md
+# /forerunner-refresh  → updates all stale docs
+# /forerunner-check    → checks for doc drift
 ```
 
-## Quick start (direct API mode)
-
-```bash
-# 1. Install and configure
-pip install codeforerunner
-export ANTHROPIC_API_KEY=sk-...
+## GitHub Action
 
-# 2. Run a task
-forerunner generate readme --stream
+Add doc-drift detection to any repo's CI — fails the PR if docs contradict repo state.
 
-# 3. Enable drift detection
-forerunner doctor --fix        # writes forerunner.config.yaml
-forerunner check               # run any time or as pre-commit hook
+```yaml
+# .github/workflows/doc-check.yml
+name: Doc Check
+on: [push, pull_request]
+
+jobs:
+  doc-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+      - uses: derek-palmer/codeforerunner@v0.4.5
+        with:
+          fail-on-drift: "true"   # set "false" to warn-only
 ```
 
-## GitHub Action
+No-op when `forerunner.config.yaml` is absent — safe to add before configuring rules.
 
-```yaml
-- uses: derek-palmer/codeforerunner@v0.4.2
-```
+**Inputs**
 
-No-op when `forerunner.config.yaml` is absent.
+| Input | Default | Description |
+|-------|---------|-------------|
+| `version` | `latest` | `codeforerunner` version to install |
+| `python-version` | `3.11` | Python version |
+| `repo` | workspace root | Path to check |
+| `fail-on-drift` | `true` | Exit non-zero on drift |
 
 ## Configuration
 
@@ -164,10 +148,7 @@ forerunner doctor --fix
 ### Config fields
 
 ```yaml
-provider: anthropic          # anthropic | openai | google | ollama
-model: claude-opus-4-7
-api_key_env:
-  anthropic: ANTHROPIC_API_KEY
+approaching_eol_threshold_months: 6
 
 tasks:
   check:
@@ -210,20 +191,28 @@ tasks:
 
 See `examples/mcp/` for Claude Desktop and mcp-cli wiring examples.
 
-## Providers
+## Prompt pack
 
-`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.
+Prompts are bundled inside the package at `src/codeforerunner/prompts/`.
 
-| 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` |
+```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  arch-review.md
+    ├── refresh.md
+    └── init-agent-onboarding.md
+```
 
-## Docs and spec
+## Docs
 
-- `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

{codeforerunner-0.4.3 → codeforerunner-0.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codeforerunner"
-version = "0.4.3"
+version = "0.4.5"
 description = "Model-agnostic repository documentation tooling (prompt-first; thin CLI)."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -50,7 +50,7 @@ forerunner = "codeforerunner.cli:main"
 where = ["src"]
 
 [tool.setuptools.package-data]
-codeforerunner = ["py.typed", "prompts/**/*.md"]
+codeforerunner = ["py.typed", "prompts/**/*.md", "tasks.json"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{codeforerunner-0.4.3 → codeforerunner-0.4.5}/src/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-0.4.3 → codeforerunner-0.4.5}/src/codeforerunner/check.py

@@ -21,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, ...]
@@ -124,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
@@ -137,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():
@@ -148,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:
@@ -158,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
@@ -175,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)