@@ -0,0 +1,17 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "codeforerunner",
+  "description": "Repo documentation tooling for Claude Code. Adds /forerunner-scan, /forerunner-readme, /forerunner-check, and 9 other documentation slash commands.",
+  "owner": {
+    "name": "Derek Palmer",
+    "url": "https://github.com/derek-palmer"
+  },
+  "plugins": [
+    {
+      "name": "codeforerunner",
+      "description": "Model-agnostic repo documentation prompts. Slash commands for scan, readme, api-docs, diagrams, flows, stack-docs, version-audit, check, review, audit, changelog, and agent onboarding.",
+      "source": "./",
+      "category": "productivity"
+    }
+  ]
+}
@@ -0,0 +1,5 @@
+# codeforerunner Codex integration
+# Skills installed here are available as Codex slash commands.
+
+[features]
+skills = true
@@ -0,0 +1,48 @@
+# codeforerunner — Gemini CLI context
+
+Model-agnostic repository documentation tooling. Ships prompt packs for codebase analysis, doc generation, drift detection, and agent onboarding. Python CLI + MCP server + agent skills.
+
+## Available tasks
+
+Run any task via `forerunner doc <task>`, or use the installed Gemini extension skills:
+
+| Slash command | Task | Description |
+|---|---|---|
+| `/forerunner-scan` | `scan` | Scan repo; always run first |
+| `/forerunner-readme` | `readme` | Generate or refresh README.md |
+| `/forerunner-api-docs` | `api-docs` | Generate API reference |
+| `/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 entry from git log |
+| `/forerunner-init` | `init-agent-onboarding` | Bootstrap or refresh AGENTS.md |
+
+## Workflow
+
+1. Start with `/forerunner-scan` to collect repo evidence.
+2. Run the documentation task you need.
+3. Use `/forerunner-check` before commits to detect drift.
+
+## CLI quick reference
+
+```bash
+forerunner doc <task>         # Get composed prompt for a task
+forerunner generate <task>    # Call configured provider directly
+forerunner check              # Run drift-detection rules
+forerunner doctor             # Health report
+forerunner install gemini     # Install skills to Gemini config dir
+```
+
+## Config
+
+Drop a `forerunner.config.yaml` at repo root to enable drift rules. Run `forerunner doctor --fix` to generate a starter config.
+
+## Sources
+
+- Prompts: `src/codeforerunner/prompts/tasks/`
+- Skills: `skills/` (source) → `plugins/codeforerunner/skills/` (distribution)
+- Repo: https://github.com/derek-palmer/codeforerunner
@@ -2,115 +2,160 @@
 
 # codeForerunner
 
-Model-agnostic repository documentation tooling. Ships a prompt pack for codebase analysis and doc generation, a thin Python CLI, an MCP server, a Codex marketplace plugin, and drift-detection rules that keep docs honest.
+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.
 
-## Install
+## 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 — isolated environment
+pipx install codeforerunner   # recommended
 pip install codeforerunner    # alternative
 ```
 
-From source:
+Configure a provider (or start Ollama for keyless local generation):
 
 ```bash
-git clone https://github.com/derek-palmer/codeforerunner
-cd codeforerunner
-python -m pip install -e .
+export ANTHROPIC_API_KEY=sk-...
+forerunner generate readme --stream
 ```
 
-Verify: `forerunner --help`
+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 (`--full` prepends scan; `--agents-only` is the default scope). |
+| `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; silent no-op without `forerunner.config.yaml`. |
-| `forerunner generate <task>` | Resolve bundle for `<task>` and call the configured provider. Add `--stream` to stream output token-by-token. |
-| `forerunner doctor` | Single-screen health report: skill parity, marketplace validation, installed destinations, config, provider key. Add `--fix` to write a starter `forerunner.config.yaml` if absent. |
+| `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>` | Idempotently write the canonical skill into agent-specific directories. |
+| `forerunner install <agent>` | Install canonical skill into agent-specific directory. Add `--all` for all per-task skills. |
 
-## Prompt Pack
+## Prompt pack
 
 Prompts are bundled inside the package at `src/codeforerunner/prompts/`.
 
 ```text
 prompts/
-├── system/
-│   └── base.md
+├── 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
-    ├── audit.md
-    └── changelog.md
+    ├── 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
 ```
 
-| Task | Purpose |
-|------|---------|
-| `scan` | Structured repo scan used by downstream tasks. |
-| `init-agent-onboarding` | Generates or updates `AGENTS.md` from repo evidence. |
-| `readme` | Generates or rewrites a top-level README. |
-| `api-docs` | Documents public APIs. |
-| `stack-docs` | Documents stack-specific areas. |
-| `diagrams` | Generates Mermaid architecture or flow diagrams. |
-| `flows` | Documents user, request, job, or data flows. |
-| `version-audit` | Audits pinned versions from manifests, lockfiles, workflows, IaC. |
-| `check` | Checks existing docs for staleness against a fresh scan. |
-| `review` | Summarizes documentation impact for review. |
-| `audit` | Security and dependency audit report. |
-| `changelog` | Generates a Keep-a-Changelog entry from git log. |
-
-## Quick Start
+## Quick start (agent skill mode)
 
 ```bash
-# 1. Point your agent at the scan prompt
-forerunner scan
+# Install skills into Claude Code
+curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
 
-# 2. Generate or update docs for a task
-export FORERUNNER_SCAN_DONE=1
-forerunner doc readme
-
-# 3. Direct model call (needs provider config)
-forerunner generate readme --stream
+# In Claude Code:
+# /forerunner-scan    → scans your repo
+# /forerunner-readme  → generates README.md
+# /forerunner-check   → checks for doc drift
 ```
 
-## GitHub Action
+## Quick start (direct API mode)
 
-Use forerunner check as a reusable action in any workflow:
+```bash
+# 1. Install and configure
+pip install codeforerunner
+export ANTHROPIC_API_KEY=sk-...
 
-```yaml
-- uses: derek-palmer/codeforerunner@v0.3.2
+# 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
 ```
 
-With a pinned version:
+## GitHub Action
 
 ```yaml
 - uses: derek-palmer/codeforerunner@v0.3.2
-  with:
-    version: '0.3.2'
 ```
 
 No-op when `forerunner.config.yaml` is absent.
 
 ## Configuration
 
-Copy `forerunner.config.yaml.example` to `forerunner.config.yaml` to opt in. Without that file, `forerunner check` is a silent no-op. Generate a starter config with:
+Copy `forerunner.config.yaml.example` to `forerunner.config.yaml` to opt in to drift rules. Generate a starter config with:
 
 ```bash
 forerunner doctor --fix
@@ -122,7 +167,7 @@ forerunner doctor --fix
 provider: anthropic          # anthropic | openai | google | ollama
 model: claude-opus-4-7
 api_key_env:
-  anthropic: ANTHROPIC_API_KEY   # override per-provider env var name
+  anthropic: ANTHROPIC_API_KEY
 
 tasks:
   check:
@@ -134,10 +179,10 @@ tasks:
       - R5-no-python-package
       - R7-no-mcp
       - R8-no-marketplace
-      - RI1-missing-cli          # inverse: doc claims CLI but file absent
+      - RI1-missing-cli
       - RI5-missing-python-package
       - RI7-missing-mcp
-      - RV1-version-drift        # pinned version in docs ≠ pyproject.toml
+      - RV1-version-drift
     ignore_paths:
       - docs/legacy/**/*.md
 ```
@@ -159,15 +204,15 @@ tasks:
 | `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
+## 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. Set the appropriate env var before calling:
+`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 |
 |----------|---------|---------------|
@@ -176,20 +221,11 @@ See `examples/mcp/` for Claude Desktop and mcp-cli wiring examples.
 | `google` | `GOOGLE_API_KEY` | `gemini-2.5-pro` |
 | `ollama` | `OLLAMA_HOST` (optional) | `llama3` |
 
-## Codex Plugin
-
-```bash
-forerunner install codex --marketplace
-```
-
-Installs the Codex marketplace entry and skill. Or install manually:
-`forerunner install <agent>` copies the canonical skill into the agent-specific directory.
-
-## Docs and Spec
+## 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` — design backing Codex/Claude packages
+- `docs/agent-distribution-design.md` — packaging and installer design