Metadata-Version: 2.5
Name: repoforge-ai
Version: 0.7.0
Summary: Generate technical docs and AI agent skills (SKILL.md, AGENT.md) from any codebase — model-agnostic, monorepo-aware
Project-URL: Homepage, https://github.com/JNZader/repoforge
Project-URL: Repository, https://github.com/JNZader/repoforge
Project-URL: Issues, https://github.com/JNZader/repoforge/issues
Project-URL: Changelog, https://github.com/JNZader/repoforge/releases
License: MIT
License-File: LICENSE
Keywords: agents,ai-agents,claude,claude-code,code-analysis,developer-tools,docsify,documentation,github-copilot,gpt,llm,monorepo,ollama,opencode,skills
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: litellm!=1.82.8,>=1.82.6
Requires-Dist: mcp>=1.26.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: faiss-cpu>=1.7.0; extra == 'all'
Requires-Dist: mypy>=1.0; extra == 'all'
Requires-Dist: pdfplumber>=0.10.0; extra == 'all'
Requires-Dist: pytest-cov; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: ruff==0.15.6; extra == 'all'
Requires-Dist: tree-sitter-language-pack>=1.3.3; extra == 'all'
Requires-Dist: tree-sitter>=0.23; extra == 'all'
Requires-Dist: youtube-transcript-api>=1.0.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff==0.15.6; extra == 'dev'
Provides-Extra: intelligence
Requires-Dist: tree-sitter-language-pack>=1.3.3; extra == 'intelligence'
Requires-Dist: tree-sitter>=0.23; extra == 'intelligence'
Provides-Extra: pdf
Requires-Dist: pdfplumber>=0.10.0; extra == 'pdf'
Provides-Extra: search
Requires-Dist: faiss-cpu>=1.7.0; extra == 'search'
Provides-Extra: youtube
Requires-Dist: youtube-transcript-api>=1.0.0; extra == 'youtube'
Description-Content-Type: text/markdown

# RepoForge

Read this in: [English](README.md) · [Español](README.es.md)

AI-powered code analysis for generating technical docs, agent skills, security scans, code graphs, architecture diagrams, and LLM-ready repo exports.

[![PyPI version](https://img.shields.io/pypi/v/repoforge-ai?label=PyPI&color=blue)](https://pypi.org/project/repoforge-ai/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

[Live Demo](https://repoforge.javierzader.com) · [PyPI](https://pypi.org/project/repoforge-ai/) · [GitHub](https://github.com/JNZader/repoforge) · [Issues](https://github.com/JNZader/repoforge/issues)

## What It Is

RepoForge scans a repository once and produces several outputs from the same analysis: a Docsify-ready documentation site, multi-tool agent skills, Mermaid/SVG diagrams, code graphs, security scans, and single-file LLM context exports.

The core idea: mix **deterministic analysis** (stack detection, graphing, scoring, scanning, coverage parsing, diagram generation) with **optional LLM text generation**, instead of pretending the model understands the repo by magic. The LLM writes prose; everything structural is computed.

Use it when you need to:

- onboard engineers into an unfamiliar codebase fast
- generate internal docs without hand-writing every chapter
- create agent instructions for Claude Code, OpenCode, Cursor, Codex, Gemini, and Copilot from one source
- flatten a repository into a single LLM-friendly context file
- audit generated markdown for secrets, prompt injection, or unsafe commands
- understand architectural blast radius before refactoring
- publish a docs site to GitHub Pages without building a custom docs pipeline

## Quick Start

```bash
pip install repoforge-ai

# Generate Docsify-ready docs (needs an LLM API key)
repoforge docs -w /path/to/repo --lang English

# Generate multi-tool skills (needs an LLM API key)
repoforge skills -w /path/to/repo --targets all

# Export repo context for an LLM (no API key)
repoforge export -w /path/to/repo -o context.md

# Deterministic security scan (no API key)
repoforge scan -w /path/to/repo
```

Notes:

- CLI command: `repoforge`
- PyPI package name: `repoforge-ai` (`repoforge` was already taken)
- Recommended for speed: install `ripgrep`

## Table of Contents

- [Installation](#installation)
- [Command Overview](#command-overview)
- [Model Setup](#model-setup)
- [Technical Quick Start](#technical-quick-start)
- [`docs` Command](#docs-command)
- [`skills` Command](#skills-command)
- [`export` Command](#export-command)
- [`score` Command](#score-command)
- [`scan` Command](#scan-command)
- [`compress` Command](#compress-command)
- [`graph` Command](#graph-command)
- [`diagram` Command](#diagram-command)
- [Code Analysis Commands](#code-analysis-commands)
- [MCP Server](#mcp-server)
- [GitHub Pages Deployment](#github-pages-deployment)
- [Monorepo Support](#monorepo-support)
- [`repoforge.yaml` - Per-Repo Config](#repoforgeyaml--per-repo-config)
- [Python API](#python-api)
- [How It Works](#how-it-works)
- [Cost](#cost)
- [Supported Stacks](#supported-stacks)
- [License](#license)
- [Inspirations](#inspirations)

## Installation

```bash
pip install repoforge-ai
```

### Optional extras

Some commands need extra dependencies. Install only what you use:

```bash
pip install "repoforge-ai[intelligence]"  # tree-sitter signatures in the docs API surface; not used by `analyze` or `slice`
pip install "repoforge-ai[search]"        # semantic search index (faiss) for `index`/`query`
pip install "repoforge-ai[pdf]"           # PDF ingestion for `skills-from-docs`
pip install "repoforge-ai[youtube]"       # YouTube transcript ingestion for `skills-from-docs`
pip install "repoforge-ai[all]"           # everything above
```

`ripgrep` is strongly recommended for faster scanning:

```bash
brew install ripgrep
sudo apt install ripgrep
scoop install ripgrep
```

## Command Overview

### Generation commands (need an LLM API key)

| Command | What it does |
|---|---|
| `repoforge docs` | Generate Docsify-ready technical documentation |
| `repoforge skills` | Generate skills and agents for coding tools |
| `repoforge index` | Build a semantic search index from codebase entities (calls an embedding API) |

### Deterministic commands (no API key)

| Command | What it does |
|---|---|
| `repoforge export` | Flatten a repo into one LLM-optimized file |
| `repoforge score` | Score generated `SKILL.md` files across 7 dimensions |
| `repoforge scan` | Security-scan generated markdown |
| `repoforge compress` | Token-optimize generated markdown |
| `repoforge graph` | Build dependency/call graphs and blast-radius views |
| `repoforge diagram` / `diagrams` | Generate Mermaid, SVG, ERD, K8s, and OpenAPI diagrams |
| `repoforge check` | Validate code references in generated docs |
| `repoforge diff` | Entity-level semantic diff between two git refs |
| `repoforge audit` | Run all analysis checks in one shot |
| `repoforge skills-from-docs` | Fill a `SKILL.md` template from external docs (URL, GitHub repo, local dir, PDF, YouTube, notebook). No LLM call |
| `repoforge analyze` | Regex layers: symbols, calls, CFG, DFG, PDG. Does not need `[intelligence]` |
| `repoforge search` | Semantic code search by behavior |
| `repoforge query` | Search a previously built index |
| `repoforge blast-radius` | Transitive blast radius of a change |
| `repoforge change-impact` | Identify which tests to run for a change |
| `repoforge co-change` | Detect files that always change together |
| `repoforge ownership` | Compute file/module ownership and bus factor |
| `repoforge dead-code` | Detect potentially dead code via graph analysis |
| `repoforge slice` | Program slice for a specific line, from the same regex analysis. Does not need `[intelligence]` |
| `repoforge decisions` | Decision registry from git history and inline markers |
| `repoforge context-prune` | Graph-aware context pruning for LLM review |
| `repoforge prompts` | Generate reusable analysis prompts from a scan |
| `repoforge import-docs` | Import external dependency docs to enrich context |
| `repoforge validate-skills` | Validate `SKILL.md` files against the standard format |
| `repoforge registry` | Cross-repo code graph registry (`add`/`remove`/`list`/`build`/`search`) |

Run `repoforge <command> --help` for the full option list of any command.

### Common flags

- `-w`, `--working-dir` / `--workspace`: repo path
- `-o`, `--output` / `--output-dir`: output file or directory
- `--model`: LLM model
- `--dry-run`: plan only, no LLM calls
- `-q`, `--quiet`: quieter output

## Model Setup

RepoForge auto-detects providers from environment variables, but explicit setup matters because provider behavior is NOT the same.

### GitHub Models

Best low-friction option if you already use GitHub tooling.

```bash
export GITHUB_TOKEN=$(gh auth token)
repoforge docs -w . --model github/gpt-4o-mini
```

For GitHub Actions, the built-in `GITHUB_TOKEN` is not enough for GitHub Models. You need a PAT with `models:read` scope, usually stored as `GH_MODELS_TOKEN`.

### Groq

```bash
export GROQ_API_KEY=gsk_...
repoforge docs -w . --model groq/llama-3.3-70b-versatile
```

### Ollama

```bash
ollama pull qwen2.5-coder:14b
repoforge docs -w . --model ollama/qwen2.5-coder:14b
```

### Claude Haiku

```bash
export ANTHROPIC_API_KEY=sk-ant-...
repoforge docs -w . --model claude-haiku-3-5
```

### OpenAI

```bash
export OPENAI_API_KEY=sk-...
repoforge docs -w . --model gpt-4o-mini
```

### Practical model notes

- `github/gpt-4o-mini`: easiest default for docs and skills if you already use GitHub
- `claude-haiku-3-5`: cheap and usually good enough for generation
- `ollama/...`: local and free, but quality depends heavily on the model you pull
- `groq/...`: fast and free-tier friendly, but rate limits matter
- `gpt-4o-mini`: solid baseline if you already have OpenAI wired in

## Technical Quick Start

```bash
# Docs
repoforge docs -w /path/to/repo --lang English -o docs

# Serve docs locally
repoforge docs -w . --serve

# Generate skills for Claude + OpenCode + Cursor + Codex
repoforge skills -w /path/to/repo --targets claude,opencode,cursor,codex

# Generate skills and immediately score, scan, and compress them
repoforge skills -w /path/to/repo --score --scan --compress

# Export repo context
repoforge export -w /path/to/repo -o context.md

# Build dependency graph
repoforge graph -w /path/to/repo --format mermaid

# Generate dependency diagram
repoforge diagram -w /path/to/repo --type dependency

# Incremental docs
repoforge docs -w /path/to/repo --incremental

# Plan only
repoforge docs -w /path/to/repo --dry-run
repoforge skills -w /path/to/repo --dry-run
```

## `docs` Command

Generates a Docsify-ready technical documentation site adapted to project type.

| Project type | Typical chapters |
|---|---|
| Web service | Data Models, API Reference |
| Frontend SPA | Components, State Management |
| CLI tool | Commands, Configuration |
| Data science | Data Pipeline, Models and Training, Experiments |
| Library or SDK | Public API, Integration Guide |
| Mobile app | Screens and Navigation, Native Integrations |
| Infra or DevOps | Resources, Variables, Deployment Guide |
| Monorepo | Global chapters plus per-layer subdocs |

```text
repoforge docs [OPTIONS]

  -w, --working-dir DIR     Repo to analyze  [default: .]
  -o, --output-dir DIR      Output directory  [default: docs]
  --model TEXT              LLM model
  --lang LANGUAGE           Documentation language  [default: English]
  --name TEXT               Project name override
  --complexity LEVEL        auto|small|medium|large
  --theme THEME             vue|dark|buble|pure
  --serve                   Generate and open local docs
  --serve-only              Skip generation, serve existing docs
  --port INT                Local server port  [default: 8000]
  --chunked                 Use chunked generation mode
  --verify / --no-verify    Enable or disable Stage C verification
  --verify-model TEXT       Verification model override
  --no-verify-docs          Disable verification and deterministic corrections
  --facts-only              Emit factual extraction without prose
  --incremental             Regenerate only stale chapters
  --semantic-dedup          Skip semantically unchanged chapters in incremental mode
  --semantic-threshold FLOAT
  --watch                   Regenerate docs when files change
  --watch-interval FLOAT
  --link-style STYLE        backtick|wiki
  --diagrams                Embed Mermaid diagrams in architecture docs
  --max-workers INT         Parallel chapter workers
  --model-heavy TEXT        Heavy-tier model when --model auto
  --model-standard TEXT     Standard-tier model when --model auto
  --model-light TEXT        Light-tier model when --model auto
  --dry-run
  -q, --quiet
```

Supported languages: English, Spanish, French, German, Portuguese, Chinese, Japanese, Korean, Russian, Italian, Dutch.

### Output

Up to 8 chapters plus Docsify scaffolding:

- `index.md`
- `01-overview.md`
- `02-quickstart.md`
- `03-architecture.md`
- `04-core-mechanisms.md`
- `05-data-models.md` when relevant
- `06-api-reference.md` when relevant
- `07-dev-guide.md`
- `index.html`, `_sidebar.md`, and `.nojekyll` for Docsify and GitHub Pages

### Incremental mode

With `--incremental`, RepoForge tracks chapter dependencies in a manifest and uses `git diff` to decide which chapters are stale. That matters on large repos because regenerating everything is just burning tokens for no reason.

`--semantic-dedup` goes one step further by using embedding similarity to skip chapters whose meaning did not materially change, even if files changed.

### Complexity levels

| Level | Behavior |
|---|---|
| `auto` | Detect from file count and layer count |
| `small` | Fewer files, denser per-file coverage |
| `medium` | Balanced depth |
| `large` | More architectural summarization, less file-by-file noise |

### Local preview

```bash
repoforge docs -w . --serve
```

Or serve the generated folder yourself:

```bash
python3 -m http.server 8000 --directory docs
```

## `skills` Command

Generates `SKILL.md` and `AGENT.md` artifacts for six coding-agent targets from a single scan.

```text
repoforge skills [OPTIONS]

  -w, --working-dir DIR     Repo to analyze  [default: .]
  -o, --output-dir DIR      Output directory  [default: .claude]
  --model TEXT              LLM model
  --complexity LEVEL        auto|small|medium|large
  --targets TARGETS         claude|opencode|cursor|codex|gemini|copilot|all
  --disclosure MODE         tiered|full
  --with-hooks              Generate HOOKS.md
  --plugin                  Generate plugin.json + commands/
  --score                   Score skills after generation
  --compress                Compress skills after generation
  --aggressive              Stronger compression mode
  --scan                    Run security scan after generation
  --no-opencode             Skip mirror to .opencode/
  --serve                   Open skills browser
  --serve-only              Open existing skills browser
  --port INT                Browser port  [default: 8765]
  --dry-run
  -q, --quiet
```

### Output targets

| Target | Output | Format |
|---|---|---|
| `claude` | `.claude/skills/`, `.claude/agents/` | `SKILL.md` and `AGENT.md` |
| `opencode` | `.opencode/` | Mirror of Claude output |
| `cursor` | `.cursor/rules/*.mdc` | Cursor rules |
| `codex` | `AGENTS.md` | Consolidated instructions |
| `gemini` | `GEMINI.md` | Gemini CLI instructions |
| `copilot` | `.github/copilot-instructions.md` | Copilot instructions |

The agent-teams-lite registry output (`.atl/skill-registry.md`) is also produced.

### Example layout

```text
.claude/
├── skills/
│   ├── backend/SKILL.md
│   ├── backend/auth/SKILL.md
│   └── frontend/SKILL.md
├── agents/
│   ├── orchestrator/AGENT.md
│   ├── backend-agent/AGENT.md
│   └── frontend-agent/AGENT.md
├── commands/
├── plugin.json
├── HOOKS.md
├── DISCOVERY_INDEX.md
└── SKILLS_INDEX.md
```

### Things worth knowing

- `--targets all` is the fastest way to produce a full multi-agent output set.
- `--disclosure tiered` adds progressive disclosure markers and index files.
- `--score --scan --compress` lets you treat skill generation like a pipeline instead of a one-shot dump.

## `export` Command

Flatten a repo into one LLM-friendly file. No API key required.

```text
repoforge export [OPTIONS]

  -w, --working-dir DIR     Repo to analyze  [default: .]
  -o, --output FILE         Output file, or stdout if omitted
  --max-tokens INT          Token budget cap
  --no-contents             Tree plus definitions only
  --format FORMAT           markdown|xml
  --compress                API-surface-focused export
  -q, --quiet
```

```bash
repoforge export -w .
repoforge export -w . -o context.md
repoforge export -w . --max-tokens 100000
repoforge export -w . --no-contents
repoforge export -w . --format xml
repoforge export -w . --compress
```

## `score` Command

Scores generated skills across 7 dimensions: completeness, clarity, specificity, examples, format, safety, and agent readiness. No API key required.

```text
repoforge score [OPTIONS]

  -w, --working-dir DIR     Repo root  [default: .]
  -d, --skills-dir DIR      Skills directory override
  --format FORMAT           table|json|markdown
  --min-score FLOAT         Exit 1 if a skill falls below threshold
  -q, --quiet
```

```bash
repoforge score -w .
repoforge score -w . --format json
repoforge score -w . --min-score 0.7
repoforge score -d /path/to/skills
```

## `scan` Command

Security scanner for generated markdown. No API key required. It ships 37 rules across 5 categories:

- prompt injection
- hardcoded secrets
- PII exposure
- destructive commands
- unsafe code patterns

It is context-aware: anti-pattern examples are downgraded instead of treated the same as production secrets.

```text
repoforge scan [OPTIONS]

  -w, --workspace DIR       Repo root  [default: .]
  --target-dir DIR          Specific directory override
  --format FORMAT           table|json|markdown
  --allowlist IDS           Comma-separated rule IDs
  --fail-on SEVERITY        critical|high|medium|low
  -q, --quiet
```

```bash
repoforge scan -w .
repoforge scan -w . --format json
repoforge scan -w . --fail-on critical
repoforge scan -w . --allowlist SEC-020,SEC-022
repoforge scan --target-dir ./my-skills
```

## `compress` Command

Deterministic markdown compression for lower token cost. No API key required.

Compression passes include whitespace normalization, filler removal, table compaction, code-block cleanup, bullet consolidation, and optional aggressive abbreviation.

```text
repoforge compress [OPTIONS]

  -w, --workspace DIR       Repo root  [default: .]
  --target-dir DIR          Directory override
  --aggressive              Stronger abbreviation mode
  --dry-run                 Show compression stats only
  -q, --quiet
```

```bash
repoforge compress -w .
repoforge compress -w . --aggressive
repoforge compress -w . --dry-run
repoforge compress --target-dir ./my-skills
```

## `graph` Command

Builds a code knowledge graph from repository structure. No API key required.

It supports file-level dependency graphs, symbol-level call graphs, structured graph queries, community detection, and blast radius analysis.

```text
repoforge graph [OPTIONS]

  -w, --workspace DIR       Repo root  [default: .]
  -o, --output FILE         Output file or stdout
  --format FORMAT           mermaid|json|dot|summary
  --type TYPE               deps|calls
  --blast-radius MODULE     Show impact of a module change
  --v2                      Use extractor-based graph builder
  --depth INT               BFS depth for v2 blast radius
  --max-files INT           Max files in blast-radius result
  --include-tests / --no-include-tests
  --query MODE              callers|callees|imports
  --symbol TEXT             Symbol for callers or callees query
  --file PATH               File path for imports query
  --communities             Detect related module clusters
  --incremental             Use file-hash graph caching
  -q, --quiet
```

```bash
repoforge graph -w .
repoforge graph -w . --format mermaid
repoforge graph -w . --format json -o graph.json
repoforge graph -w . --format dot -o graph.dot
repoforge graph -w . --blast-radius repoforge/cli.py
repoforge graph -w . --type calls
repoforge graph --query callers --symbol build_graph
repoforge graph --query imports --file repoforge/cli.py
repoforge graph -w . --communities --format summary
```

## `diagram` Command

Generates architecture diagrams from code or external specs. No API key required.

```text
repoforge diagram [OPTIONS]

  -w, --workspace DIR       Repo root  [default: .]
  -o, --output FILE         Output file or stdout
  --type TYPE               dependency|directory|callflow|erd|k8s|openapi|svg|all
  --max-nodes INT           Dependency diagram node cap
  --max-depth INT           Directory or call-flow depth
  --entry FILE              Entry point for call-flow diagrams
  --input FILE              Required for erd, k8s, and openapi
  -q, --quiet
```

```bash
repoforge diagram -w .
repoforge diagram -w . --type dependency
repoforge diagram -w . --type callflow --entry src/main.py
repoforge diagram -w . --type erd --input schema.sql
repoforge diagram -w . --type k8s --input k8s/deployment.yaml
repoforge diagram -w . --type openapi --input openapi.json
repoforge diagram -w . --type svg -o architecture.svg
repoforge diagram -w . -o diagrams.md
```

There is also a `repoforge diagrams` command that writes a combined markdown file with multiple Mermaid blocks.

## Code Analysis Commands

Beyond docs and skills, RepoForge exposes a set of deterministic code-analysis commands (no API key required unless noted). These power refactor planning, review scoping, and codebase archaeology.

```bash
# Regex layers: symbols, calls, CFG, DFG, PDG. No [intelligence] extra.
repoforge analyze -w .

# Transitive blast radius of a change
repoforge blast-radius -w . --files repoforge/cli.py

# Which tests to run for a change
repoforge change-impact -w .

# Files that always change together
repoforge co-change -w .

# Ownership and bus factor
repoforge ownership -w .

# Potentially dead code via graph analysis
repoforge dead-code -w .

# Program slice for a specific line
repoforge slice -w . --file repoforge/cli.py --line 100

# Decision registry from git history and inline markers
repoforge decisions -w .

# Graph-aware context pruning for LLM review
repoforge context-prune -w . --files repoforge/cli.py

# Semantic code search by behavior
repoforge search -w . "where do we validate the API key"

# Run every analysis check in one shot
repoforge audit -w .
```

For cross-repo work, `repoforge registry` maintains a registry of repositories and lets you `add`, `remove`, `list`, `build`, and `search` graphs across all of them.

## MCP Server

RepoForge ships an MCP (Model Context Protocol) server that exposes its deterministic analysis to MCP-capable agents. `list_tools` registers these tools:

- `repoforge_score`
- `repoforge_graph`
- `repoforge_changelog`
- `repoforge_drift`
- `repoforge_analyze`
- `repoforge_context`

Add it to your MCP client config (for example `~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "repoforge": {
      "command": "uv",
      "args": ["--directory", "/path/to/repoforge", "run", "python", "-m", "repoforge.mcp_server"]
    }
  }
}
```

## GitHub Pages Deployment

RepoForge ships a docs workflow with safe deploy modes. The default is generate-only. That is the correct default because clobbering an existing Pages site would be amateur-hour behavior.

### Deploy modes

| Mode | Behavior |
|---|---|
| `none` | Generate docs only, do not publish |
| `auto` | If no live site exists, deploy to Pages root; otherwise deploy to a subpath |
| `main` | Force deploy to Pages root |
| `subpath` | Publish under `/<prefix>/` on `gh-pages` while preserving existing files |

### Step-by-step: safe GitHub Pages setup

1. Copy or reuse `.github/workflows/docs.yml` in your repository.
2. Create a GitHub PAT with `models:read` scope.
3. Save that PAT as the repository secret `GH_MODELS_TOKEN`.
4. Decide whether you want generate-only, root deploy, or subpath deploy.
5. If you want publishing, set repository variables:
   - `REPOFORGE_DOCS_DEPLOY_MODE=auto` or `main` or `subpath`
   - `REPOFORGE_DOCS_CONFIRM_DEPLOY=true`
   - optional `REPOFORGE_DOCS_SUBPATH_PREFIX=docs`
6. Check GitHub Pages settings:
   - for `main`: Pages should use GitHub Actions
   - for `subpath`: Pages should deploy from `gh-pages` branch at `/ (root)`
7. Push to `main`, or trigger `workflow_dispatch` with `deploy_mode`, `confirm_deploy`, and `subpath_prefix`.
8. Open the published URL reported by the workflow summary.

### Required Pages settings by mode

| `deploy_mode` | Deployment mechanism | Required Pages setting |
|---|---|---|
| `none` | Generate only | Any |
| `main` | `actions/deploy-pages@v4` | GitHub Actions |
| `subpath` | `peaceiris/actions-gh-pages@v4` with `keep_files` | Deploy from branch `gh-pages` |
| `auto` | Chooses `main` or `subpath` | Must match actual target |

### Example: add docs without breaking an existing Pages site

```bash
gh variable set REPOFORGE_DOCS_DEPLOY_MODE --body "auto" --repo youruser/yourrepo
gh variable set REPOFORGE_DOCS_CONFIRM_DEPLOY --body "true" --repo youruser/yourrepo
gh variable set REPOFORGE_DOCS_SUBPATH_PREFIX --body "docs" --repo youruser/yourrepo
gh secret set GH_MODELS_TOKEN --repo youruser/yourrepo
```

If your repo already serves `https://youruser.github.io/yourrepo/`, auto mode will prefer a preserved subpath deploy when it detects an existing live site.

### Using the reusable GitHub Action

RepoForge also ships a composite action (`action.yml`). When you reference it from another workflow, pin a released tag instead of `@main` so downstream workflows stay reproducible:

```yaml
uses: JNZader/repoforge@v0.6.0  # pin a released tag — see the Releases page
```

### Manual Pages flow

Still supported if you do not want the workflow:

```bash
repoforge docs -w . -o docs --lang English
git add docs
git commit -m "docs: generate documentation"
git push
```

Then configure GitHub Pages to serve `/docs` from `main` if that is your chosen model.

## Monorepo Support

RepoForge auto-detects layers and generates hierarchical docs.

```text
docs/
├── index.md
├── 01-overview.md
├── 03-architecture.md
├── 06b-service-map.md
├── frontend/
│   ├── index.md
│   ├── 05-components.md
│   └── 06-state.md
└── backend/
    ├── index.md
    ├── 05-data-models.md
    └── 06-api-reference.md
```

That means you get a global architecture view plus layer-specific chapters instead of one useless, flattened wall of prose.

## `repoforge.yaml` - Per-Repo Config

Create `repoforge.yaml` in the repo root to override defaults.

```yaml
# Core identity
project_name: "My App"
project_type: web_service
language: English

# Model selection
model: github/gpt-4o-mini

# If you want per-tier routing, set model: auto and configure tiers
models:
  heavy: claude-haiku-3-5
  standard: github/gpt-4o-mini
  light: github/gpt-4o-mini

# Generation depth
complexity: auto
disclosure: tiered

# Multi-tool output
targets: [claude, opencode, cursor, codex]
generate_hooks: true
generate_plugin: true

# Monorepo layer overrides
layers:
  frontend: apps/web
  backend: apps/api
  shared: packages/shared

# Docs generation defaults
parallel:
  max_workers: 4

# Optional chapter-level customization
pages:
  - file: "03-architecture.md"
    sections:
      - type: intro
        order: 1
        content: "This project follows a layered architecture."
      - type: diagram
        enabled: true
        order: 2
      - type: custom
        title: "Deployment Notes"
        order: 3
        content: "Production deploys through GitHub Actions."

# Optional project-type template overrides
templates:
  - name: "custom-web-service"
    project_type: web_service
    chapters:
      - file: "08-ops.md"
        title: "Operations"
        description: "Runbooks, observability, and deployment notes"
        prompt_key: dev_guide
        order: 80
```

### Config behavior notes

- CLI flags beat config values.
- If `model` is not `auto`, the same model is used for heavy, standard, and light tiers.
- If `model: auto`, RepoForge reads `models.heavy`, `models.standard`, and `models.light`.
- `targets` can be a YAML list and maps directly to multi-tool output.
- `pages` customizes sections within generated chapters.
- `templates` lets you override or extend chapter templates for project types.

## Python API

RepoForge is not just a CLI wrapper. You can call the underlying library directly.

```python
from repoforge import (
    generate_artifacts,
    generate_docs,
    export_llm_view,
    SkillScorer,
    SkillCompressor,
    SecurityScanner,
    scan_generated_output,
    build_graph,
    build_graph_from_workspace,
    build_graph_v2,
    get_blast_radius_v2,
    generate_dependency_diagram,
    generate_directory_diagram,
    generate_call_flow_diagram,
    generate_all_diagrams,
    Manifest,
    ChapterEntry,
    load_manifest,
    save_manifest,
    get_changed_files,
    build_chapter_deps,
    get_stale_chapters,
    DependencyHealthReport,
    analyze_dependency_health,
    CoverageReport,
    auto_detect_and_parse,
    render_coverage_markdown,
    adapt_for_cursor,
    adapt_for_codex,
    adapt_for_gemini,
    adapt_for_copilot,
    resolve_targets,
    ALL_TARGETS,
)

# Generate skills and agents
generate_artifacts(
    working_dir="/path/to/repo",
    output_dir=".claude",
    model="github/gpt-4o-mini",
    targets="claude,cursor,codex",
    complexity="auto",
    with_hooks=True,
    with_plugin=True,
    disclosure="tiered",
    compress=True,
)

# Generate documentation
generate_docs(
    working_dir="/path/to/repo",
    output_dir="docs",
    model="claude-haiku-3-5",
    language="English",
    complexity="auto",
    incremental=True,
    embed_diagrams=True,
)

# Export repo context
context = export_llm_view(
    workspace="/path/to/repo",
    output_path="context.md",
    max_tokens=100000,
    fmt="markdown",
)

# Score skills
scorer = SkillScorer()
scores = scorer.score_directory(".claude/skills")
print(scorer.report(scores, fmt="table"))

# Scan generated output
scan_result = scan_generated_output("/path/to/repo")
scanner = SecurityScanner()
print(scanner.report(scan_result, fmt="table"))

# Graph and blast radius
graph = build_graph_from_workspace("/path/to/repo")
print(graph.to_mermaid())
graph_v2 = build_graph_v2("/path/to/repo")
blast = get_blast_radius_v2(graph_v2, "repoforge/cli.py")

# Diagrams
print(generate_dependency_diagram(graph_v2, max_nodes=40))

# Incremental docs helpers
manifest = load_manifest("docs")
changed = get_changed_files("/path/to/repo")

# Dependency health and coverage
health = analyze_dependency_health("/path/to/repo")
reports = auto_detect_and_parse("/path/to/repo")
markdown = render_coverage_markdown(reports)
```

### API areas worth knowing

- docs generation: `generate_docs`
- skills generation: `generate_artifacts`
- repo export: `export_llm_view`
- scanning and scoring: `SecurityScanner`, `SkillScorer`
- graph analysis: `build_graph_from_workspace`, `build_graph_v2`, `get_blast_radius_v2`
- diagrams: `generate_dependency_diagram`, `generate_all_diagrams`
- incremental docs: manifest and stale-chapter helpers
- adapters: `adapt_for_cursor`, `adapt_for_codex`, `adapt_for_gemini`, `adapt_for_copilot`

## How It Works

```text
1. SCAN     (deterministic)  Detect stack, layers, files, symbols, and structure
2. PLAN     (deterministic)  Choose chapters, rank modules, route by complexity
3. GENERATE (LLM)            Produce prose for docs or skills
4. ADAPT    (deterministic)  Convert output to Cursor, Codex, Gemini, Copilot, OpenCode formats
5. ENRICH   (deterministic)  Add scans, compression, plugin manifests, diagrams, dependency health, coverage
6. WRITE                     Emit Docsify docs, skills, agents, exports, and reports
```

Important distinction: the LLM generates text, but the structural analysis, graphing, scoring, scanning, coverage parsing, and diagram generation are deterministic.

## Cost

The only paid step is LLM text generation (`docs`, `skills`, `index`). `skills-from-docs` fills a template and does not call a model. Every other command is free to run.

| Model | Cost |
|---|---|
| GitHub Models | Free with the right token setup |
| Groq | Free tier, rate-limited |
| Ollama | Free local runtime |
| Claude Haiku 3.5 / GPT-4o-mini | Low per-run cost |
| Claude Sonnet / larger models | Higher per-run cost |

Actual cost depends on repo size, chapter count, and model pricing. Use `--dry-run` to see the generation plan before spending tokens.

## Supported Stacks

Scanning is language-agnostic. `analyze` and `slice` are regex over Python, TypeScript, JavaScript, Go, Java, and Rust. They do not use tree-sitter. The `[intelligence]` extra supplies tree-sitter signatures for the docs API surface.

The graph extractors (`graph --v2`, blast radius) cover a core subset — Python, TypeScript, JavaScript, Go, Java, and Rust — plus mixed monorepos.

## License

MIT

## Inspirations

- [CodeViewX](https://github.com/dean2021/codeviewx)
- [Gentleman-Skills](https://github.com/Gentleman-Programming/Gentleman-Skills)
- [agent-teams-lite](https://github.com/Gentleman-Programming/agent-teams-lite)
- [repomix](https://github.com/yamadashy/repomix)
- [rendergit](https://github.com/nicobytes/rendergit)
- [aider](https://github.com/Aider-AI/aider)
- [semgrep](https://github.com/semgrep/semgrep)
