Generate comprehensive README documentation for codebases

Generates an "absurdly thorough" README.md by first exploring the codebase - project structure, framework detection via lockfiles like Gemfile/package.json/go.mod/requirements.txt, config files, database schema and migrations, dependency manifests, and existing bin/ scripts - then detecting the deployment target from marker files (Dockerfile/docker-compose.yml, vercel.json, netlify.toml, fly.toml, railway.json, render.yaml, app.yaml, Procfile, .ebextensions, serverless.yml, terraform, k8s manifests) so the deployment section matches the actual platform rather than giving generic advice, defaulting to Docker guidance when no deployment config exists. It only asks the user clarifying questions when something can't be determined from the code itself - what the project does, specific credentials or URLs, or business context - otherwise it proceeds straight to writing.

The generated README follows a fixed section order: title and overview with key features, tech stack, prerequisites, a complete "fresh machine" Getting Started walkthrough (clone, install dependencies, environment setup with a variable table, database setup, start dev server), an Architecture section going deep into directory structure, request lifecycle, data flow, key components, and database schema, a full Environment Variables reference split into required/optional/credentials/per-environment tables, an Available Scripts table, a Testing section covering how to run tests, test-directory structure, and worked examples, a Deployment section tailored to the detected platform with worked examples for Kamal, Docker, Heroku, Fly.io, Render, and manual VPS deployment, a Troubleshooting section pairing specific error messages with their fix, and optional Contributing/License sections.

kamal setup
kamal deploy
kamal rollback

Use it when creating a new README.md or substantially updating an existing one for a project that needs onboarding, architecture, and deployment documentation. Eight writing principles govern the output: be absurdly thorough (when in doubt, include it), make every command copy-pasteable in a fenced code block with a language hint, show example output where it helps, explain why a command matters rather than just naming it, write as if the reader has never seen the codebase before, use tables for environment variables/scripts/options, match the package manager actually used by the project (pnpm versus npm), and add a linked table of contents once the document passes roughly 200 lines. The output is written directly to README.md in the project root.

Input is the existing codebase - its structure, config files, database schema, dependency manifests, and deployment configuration. Output is a single complete README.md with proper Markdown formatting, language-hinted code fences, tables, a clear section hierarchy, and, for long documents, a linked table of contents.

Adapts its Getting Started, scripts, and deployment sections to whatever stack it detects rather than assuming one - it recognizes Ruby (Gemfile), Node (package.json), Go (go.mod), and Python (requirements.txt) projects, and writes platform-specific deployment instructions for Docker, Vercel, Netlify, Fly.io, Railway, Render, Google App Engine, Heroku, AWS Elastic Beanstalk, Serverless Framework, Terraform, and Kubernetes based on which marker file is present.

Developers who need comprehensive onboarding, architecture, and deployment documentation generated directly from their codebase rather than written by hand or left thin, especially for a project a new contributor needs to run locally within minutes.