README Scope

The README is the front door of ORCA.

Its job is to:

• explain what ORCA is
• explain who it is for
• explain what problems it helps solve
• give a clear setup interview, install path, and first-workflow path
• make onboarding and setup feel easier than reading the whole docs tree
• summarize the main capability areas only after the setup path is clear
• route readers to the right deeper docs
• reflect the strongest recurring work shown by the live operating evidence

What The README Should Not Try To Do

It should not become:

• a dump of every feature
• a changelog
• a deep technical spec
• a wiki replacement
• a marketing manifesto
• a page dominated by whichever subsystem was added most recently
• a founder biography
• a generic AI-framework page that could describe almost anything

Good README Behavior

• useful to a new visitor in under a minute
• readable by non-experts
• concise without being vague
• balanced across the project’s real center of gravity
• linked to deeper docs instead of duplicating them
• specific enough to feel evidence-backed without becoming too personal