generate-readme

README Generator

Generate polished, reader-centric README documentation from actual repository contents.

README Quality Rubric

Before generating, internalize these six criteria. A successful README must satisfy ALL of them. After writing, verify each one (see Verification Pass).

1. Reader-first journey — The README answers questions a new reader asks, in order: "What is this?" → "Should I use it?" → "How do I start?" → "Where do I go next?" The reader is someone who found this repo and wants to know what it does and how to use it in under 5 minutes.

2. Evidence-backed — Every feature, command, endpoint, version number, and architectural claim is traceable to a file in the repository. If the evidence is ambiguous, omit the claim.

3. Actionable — Every command shown is exact and verifiable from build files or scripts. Every configuration key documents its purpose. The reader can copy-paste and run.

4. Scannable — Skimming headers alone tells the story. Code blocks are minimal (≤10 lines). Technical details have a home (API table, config reference) — they are not scattered through narrative paragraphs.

5. WHAT not HOW — The README describes what the project does and how to use it. Internal implementation details (class hierarchy, algorithm choices, code structure walkthrough) belong in developer docs or CONTRIBUTING.md — not in the README.

6. Maintainer voice — Reads as if the project maintainer wrote it for a new team member. No AI self-reference ("I scanned", "the model found"), no generic advice ("it is recommended that"), no filler.

Step 1: Understand The Project First

Before scanning files, establish what this project IS and who it's FOR. Read in priority order:

1. Any existing README (README.md, README.*.md, docs/)
2. Project description field in manifests (package.json description, pyproject.toml description, pom.xml description, Cargo.toml description, mix.exs description, *.gemspec summary)
3. Top-level directory layout
4. Entry-point files (CLI main, server startup, app bootstrap)

From these, answer: what problem does this project solve, and for whom? This answer shapes every section that follows. Do not proceed to scanning until you can state it in one sentence.

Step 2: Choose The Right Structure

Pick the structure that serves THIS project's readers. The sections below are patterns, not mandates — adapt to what the project actually needs.

Pattern A: Library / SDK

For packages consumed by other code.

# Name
One-line: what it does, what problem it solves.

## Installation
## Quick Start (minimal working example: install → import → use)
## Usage (organized by task, not by class/method)
## API Reference (link or compact table)
## Configuration (if any)
## License

Pattern B: Application / Service

For deployable services and applications.

# Name
One-line: what the service does, its role.

## Architecture Overview (if multi-component — keep to 5-9 nodes)
## Prerequisites
## Setup & Installation
## Configuration Reference
## Running
## API (if applicable — compact table: Method | Path | Purpose | Source)
## Operations / Deployment
## License

Pattern C: CLI Tool

For command-line utilities.

# Name
One-line: what the tool does.

## Installation
## Quick Examples (3-5 most common invocations with their output intent)
## Command Reference
## Configuration
## Development
## License

Pattern D: Full-Stack / Monorepo

For projects with both frontend and backend.

# Name
One-line: what the project does.

## Architecture Overview
## Backend
   ### Prerequisites, Setup, Configuration, Running
## Frontend
   ### Prerequisites, Setup, Configuration, Running
## Shared / Development Workflow
## Deployment
## License

Structure Principles

• Start with what the reader needs to know FIRST. What is it → how to get it running. Everything else supports these two.
• A section exists because it answers a real question, not because a template has it. Omit empty sections without comment.
• Complex commercial projects need more detail — that's expected. The README should be as long as the project requires and no longer. Do not pad; do not truncate to hit an arbitrary line count.
• If the project already has a README with a well-organized structure and visual identity (badges, centered headers, Mermaid diagrams), preserve and update it in place. Do not flatten existing polish into a generic template.

Step 3: Safe Project Scan

Excluded Paths

Never read, grep, or display content from:

• VCS: .git/, .svn/, .hg/
• Dependencies: node_modules/, vendor/, .venv/, venv/, env/, __pycache__/
• Build output: dist/, build/, .next/, .nuxt/, out/, .svelte-kit/, coverage/, target/, bin/, obj/, .gradle/, classes/
• Cache: .npm/, .pnpm-store/, .yarn/
• Logs & dumps: *.log, logs/, dump/, *.dump, *.sql, *.sqlite, *.db
• Private config: .env, .env.*, *.env, application-local.*, application-prod.*, bootstrap-prod.*, settings.local.*, local_settings.*
• Credentials: *.pem, *.key, *.p12, *.pfx, id_rsa*, id_ed25519*, credentials.*, secrets.*, secret.*, service-account*.json, kubeconfig

Safe example files MAY be read: .env.example, .env.sample, config.example.*, application-example.*

When private files exist, do not call out their exact paths in the README. Use a general note or omit entirely.

Scan Order

1. Existing docs — README.md, README.*.md, docs/, CHANGELOG.md, CONTRIBUTING.md, LICENSE
2. Manifests — detect language, framework, dependencies, versions
3. Entry points — main source, server startup, CLI entry, route definitions
4. Configuration — example config, env templates, config structs/models
5. Project tree — source layout, test layout, deployment configs

Project Type Detection

Use the following signals to identify the implementation language(s). When multiple languages coexist, identify each one's role (e.g., "Python backend + TypeScript frontend") — do not force a single label.

Ecosystem	Key Signals
Node.js / TypeScript	package.json, tsconfig.json, vite.config.*, next.config.*, nuxt.config.*
Python	pyproject.toml, requirements*.txt, setup.py, setup.cfg, Pipfile, uv.lock, poetry.lock
Java / Kotlin	pom.xml, build.gradle, build.gradle.kts, settings.gradle
Go	go.mod, cmd/, main.go, internal/
Rust	Cargo.toml, src/main.rs, src/lib.rs
C# / .NET	*.csproj, *.sln, *.fsproj, Program.cs
Ruby	Gemfile, *.gemspec, Rakefile
PHP	composer.json, index.php, artisan
Elixir	mix.exs, lib/, config/
C / C++	CMakeLists.txt, Makefile, configure.ac, meson.build
Swift	Package.swift, *.xcodeproj, *.xcworkspace
Dart / Flutter	pubspec.yaml, lib/main.dart
Zig	build.zig, src/main.zig
Shell	*.sh with project-scale structure, Makefile-only projects

README handling rules by ecosystem:

• Node.js/TS: Detect package manager from lockfile (pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm, bun.lockb → bun). Extract real scripts from package.json. Separate frontend/backend when both exist.
• Python: Detect tooling (uv.lock → uv, poetry.lock → Poetry, Pipfile → Pipenv, requirements*.txt → pip). For web frameworks, document the actual run command found in code or scripts.
• Java/Kotlin: Detect Maven vs Gradle. Identify framework from dependencies (Spring Boot, Quarkus, Micronaut). Do not read private Spring profile files.
• Go: Use module path from go.mod. For CLI tools, include command examples from flag definitions. For services, document routes from explicit router registrations.
• Rust: Detect binary vs library from Cargo.toml. Use cargo commands. For CLI, extract help text or arg definitions.
• C#/.NET: Use dotnet commands. Identify project type (web, console, library) from .csproj.
• Ruby: Detect gem vs Rails app. Use bundle/gem commands accordingly.
• PHP: Detect Composer packages vs Laravel/Symfony apps. Use appropriate artisan/console commands.
• Elixir: Detect Mix project type. Use mix commands. Identify Phoenix if present.
• Dart/Flutter: Detect pure Dart vs Flutter. Use dart/flutter commands accordingly.

Step 4: Content Generation Rules

Overview

2-4 sentences answering: What does this project do? Who is it for? What problem does it solve? Ground in the project description from manifests, existing docs, or entry-point comments.

Do NOT describe the tech stack here, do NOT list features, do NOT say "built with X and Y."

Features

• List user-visible capabilities only. Not implementation details.
• Each feature: one line describing what it does, not how.
• BAD: "Uses Redis for caching" — GOOD: "Fast responses with automatic caching"
• BAD: "Implemented with Spring Security" — GOOD: "Role-based access control for admin and user accounts"
• Group related features. List only what the project actually has — do not pad.

Tech Stack

A categorized reference table, not narrative prose. Include only categories with evidence:

Category	Technology	Version	Purpose
Runtime	Node.js	22	Server runtime

Keep to one row per distinct technology. Group related items under category headers.

Project Structure

Compact directory tree:

• Max depth 3 (deeper only if showing a critical subdirectory)
• Max 40 lines
• Show: source, config, tests, docs, deployment files
• Omit: build output, dependencies, generated code, private config

Getting Started

Every command shown must be verifiable from the project's build files, scripts, or Makefile.

• Prerequisites: runtime versions, required external services

---

Content truncated.