| name | readme |
| description | When the user wants to create or update a README.md file for a project. Also use when the user says "write readme," "create readme," "document this project," "project documentation," or asks for help with README.md. Produces thorough, verified documentation covering local setup, architecture, and distribution. |
README Generator
You are an expert technical writer. Write (or update) a README.md that lets a developer on a fresh machine get the app running, understand how it works, and ship it.
The Three Purposes of a README
- Local Development - Help any developer get the app running locally in minutes
- Understanding the System - Explain how the app is put together and why
- Distribution - Cover how the project is built, released, and deployed
Before Writing
If a README.md already exists (it does in this repo), default to updating it in place: preserve its tone, structure, and any hand-written sections. Only restructure wholesale if the user asks for a rewrite.
Step 1: Explore the codebase — never document from memory
Every claim in the README must be verifiable in the repo. Check:
- Manifest and scripts:
package.json (name, scripts, engines, packageManager), lockfile, .nvmrc
- Entry points and build:
index.html, vite.config.js, src/ layout, tsconfig.json
- Platform targets:
capacitor.config.ts + android/ (mobile), electron/ + forge.config.js (desktop), vercel.json (web hosting), fastlane/ (store releases)
- CI/CD:
.github/workflows/
- Repo docs that already answer questions:
AGENTS.md, CHANGELOG.md, docs/
- Helper scripts:
scripts/ — document the ones a contributor actually needs
For this repo specifically: it is a Yarn 4 (Corepack) + Vite + React 19 SPA that also ships as an Android app (Capacitor) and desktop app (Electron Forge). Package-manager commands in the README must use yarn, never npm.
Step 2: Ask only if critical
If something can be discovered from the repo, discover it. Ask the user only about things that cannot be inferred: production URLs, secrets policy, badge preferences, target audience.
README Structure
Include the sections that apply; skip ones that don't. Suggested order:
- Title + one-paragraph overview — what it is, who it's for, links to the live app/stores
- Key features — short bullet list, user-facing
- Tech stack — table of major dependencies with one-line roles
- Prerequisites — runtime versions (from
engines/.nvmrc), corepack enable, platform SDKs only for the platform sections that need them
- Getting started — clone,
corepack yarn install, yarn start, expected dev URL; every command copy-pasteable and tested
- Architecture overview — directory map with one-line descriptions, data flow, where state lives, how the P2P/backendless parts work (if applicable)
- Configuration — env vars/flags as a table (name, required?, default, purpose)
- Available scripts — table of the
package.json scripts a contributor will actually use
- Testing — how to run unit/e2e tests, what CI runs
- Building and releasing — per-platform build commands (web, Android, Electron), release process pointers
- Troubleshooting — only real, observed failure modes with fixes; don't invent generic ones
- Contributing / License — link
AGENTS.md/docs rather than duplicating policy
Writing Principles
- Verify every command — run it or confirm it exists in
package.json before documenting it
- Copy-pasteable code blocks with language hints; show expected output where it helps
- Explain the why, not just the what
- Assume a fresh machine for setup sections
- Tables for reference material — env vars, scripts, options
- Match the project's package manager —
yarn here; never write npm install for a Yarn repo
- Table of contents for READMEs over ~200 lines
- Don't duplicate other repo docs — link to
AGENTS.md, playbooks instead of restating them; duplicated policy drifts
Output
Write directly to README.md in the project root. After public-facing English content changes in this repo, run yarn llms:generate and commit any resulting public/llms*.txt changes (see AGENTS.md Task Router).
