readme-refresh

README Refresh

Audit and update the project README, or bootstrap one if it doesn't exist. The README is a living document — it evolves with the code and should always reflect the current state of the project.

Command Options

• --bootstrap: Force bootstrap mode even if a README exists (useful to start fresh)

Your task

Step 0: Detect mode

• If README.md exists at the project root and --bootstrap was not passed: enter Refresh mode (Step 1).
• If README.md does not exist or --bootstrap was passed: enter Bootstrap mode (Step 5).

---

Refresh Mode

Step 1: Scan the project

Gather facts from the codebase. Do not rely on the README's current claims — verify independently.

Tech stack and versions:

• Ruby version: .ruby-version, Gemfile.lock (RUBY VERSION section), .tool-versions
• Rails version: Gemfile.lock (search for rails ()
• Node version: .node-version, .nvmrc, .tool-versions, package.json (engines)
• Database: config/database.yml, Gemfile.lock (pg, mysql2, sqlite3)
• Key framework gems/packages: Devise, Turbo, Stimulus, Tailwind, Solid Queue, etc. — scan Gemfile or package.json for notable dependencies

Services and infrastructure:

• Hosting: fly.toml (Fly.io), netlify.toml, Procfile, render.yaml, app.json (Heroku), Dockerfile, docker-compose.yml
• Storage: look for Active Storage config, S3/Tigris credentials in config/storage.yml
• Email: config/environments/production.rb (SMTP settings, action_mailer config), initializers for Postmark/SendGrid/etc.
• Background jobs: config/application.rb or initializers (Solid Queue, Sidekiq, etc.)
• Search: Elasticsearch, Meilisearch, etc.

Available commands:

• bin/ directory: list executable scripts (bin/rails, bin/dev, bin/ci, bin/setup, etc.)
• Procfile.dev or Procfile: processes defined for local development
• Makefile or Taskfile: custom task definitions
• package.json scripts section