#readme generator

Production README, API Docs & Code Comment Pass

Generate a complete README, public API docs, and high-signal comments from a repo or file. Written for the next engineer, not for a README badge contest.

Act as a staff engineer writing docs for the person who gets paged in six months. Document only what the Inputs support. Prefer commands, tables, and failure modes over adjectives. Inputs: - What I'm documenting: [Repo, service, library, or file] - Repo / file dump: [Paste tree, README scraps, key files, or "thin"] - Stack: [Languages, frameworks, runtime] - Audience: [New hire / external contributor / API consumer] - Public surface: [HTTP API / CLI / library exports / internal only] - Known sharp edges: [Gotchas] - Do not invent: [Commands, files, or infra that do not exist] Generate: 1. Confidence and gaps: List what you can document from Inputs vs. what is Unknown. Repeat the Do-not-invent list so you do not violate it. 2. README (complete, paste-ready markdown): - Name and one-paragraph what/why. - Quick start: numbered local run. Only commands that appear in Inputs or are universal (git clone, cd). If a command is not in Inputs, write `<!-- UNKNOWN: how do we start this? -->` instead of guessing. - Requirements: runtime versions if known. - Environment variables: markdown table (name | required | example shape | purpose). Mark unknown purposes as unknown. - Architecture: mermaid diagram (flowchart or sequence) of the pieces named in Inputs. Do not add extra boxes for services that were not mentioned. - Project layout: short tree of the files you were given. - Tests / lint: only if scripts exist in Inputs. - Troubleshooting (5 failures): each with symptom, likely cause, what to check. Include at least one env miss, one dependency/runtime miss, and one "it runs but does the wrong thing." - How to contribute / code of conduct: omit unless Inputs mention them. 3. Public API docs: For each endpoint, export, or CLI command you can see: method/name, purpose, auth, request, response, error codes, example. If the dump is thin, document the surface you can see and add a missing-docs list rather than fabricating payloads. 4. Comment pass: Propose comments (and a few names) only where the code is non-obvious: invariants, why not why-obvious, workarounds, concurrency, units. Show as file + line-ish location + comment text. Ban narrating `i++`. If no code was pasted, give comment rules the author should apply, plus 5 examples in the style of the stack. 5. Missing-docs checklist: Boxes the author still needs to fill (deploy, rollback, data model, SLOs, runbooks, license). Constraints: - No invented commands, scripts, ports, env vars, or badges. - No "built with love," star-history, or screenshot theater. - Mermaid must compile: quoted labels if they contain special characters, no em dashes inside node text. - Comments explain why, tradeoffs, and danger. Delete any comment you wrote that only restates the code. - If Inputs are thin, a shorter honest README beats a fictional enterprise doc.