The README nobody has to ask you about

Most READMEs describe what a project is. A good one answers the questions a stranger actually has, in the order they have them.

The order is the design

1. What is this, in one sentence — including who it is for. Your audience sentence from the previous lesson.
2. A picture. One screenshot of the running thing. It answers more questions than three paragraphs and costs a minute.
3. Run it in five commands. Clone, install, configure, start, open. Numbered, copyable, no prose between them.
4. What you need first — a free API key, and where to get one. Say it is free, because a person who assumes it costs money stops here.
5. What it does — the features, briefly.
6. What it does not do. The section almost nobody writes, and the one that makes the rest believable.
7. How it works — the shape: proxy holds the key, panels do not fetch, layouts are documents.
8. Licence, for the code and separately for the data.

A stranger who bounces does so in the first thirty seconds, and everything above item 5 is what they read.

Write the limitations, specifically

Not "this is a work in progress". The real ones, from your own measurements:

• Rules are checked while the page is open. There is no background alerting.
• Quotes are as fresh as your plan allows; the cockpit shows the age of every panel.
• The screener runs on one exchange. It cannot see instruments outside it.
• Backtests use today's constituent list, so results are biased by survivorship.

Every one of those came from a wall you measured. Writing them down converts four limitations into four demonstrations that you understand your own tool, which is exactly what a reader is trying to establish.

Test the quick start on a machine that is not yours

The instructions are wrong. They are always wrong, because you have things installed that you have forgotten about.

The cheap version of this test: a fresh clone into a new directory, with your .env.local moved aside. Follow your own instructions literally, typing nothing you did not write down. Every place you have to improvise is a bug in the README.

Let your assistant be the stranger

Give it the README and nothing else, and ask: "what would stop you running this, and what is ambiguous?"

This is the one review task where an assistant's lack of context is the point. It genuinely does not know what you meant, which is exactly the reader you are writing for.

Try it now

Do the fresh-clone test and time it. If it takes more than five minutes or requires one improvisation, fix the README before doing anything else in this course — everything downstream assumes a person can get the thing running.