Skip to content

Rewrite README for a newcomer, leading with the compliance engine #281

Description

@eaitbrahim

README.md is 261 lines organised as an operator runbook — how to deploy, how to upgrade, paper vs live. That is the right document for the author's future self and the wrong one for a stranger deciding whether to spend an afternoon here.

What it must do in the first screen

  1. What keel is, led by the compliance engine, not the trading agent. The differentiated asset is 19 deterministic rails, attested screening that fails closed, and §65.4 qabd encoded as an executable check. Almost nobody else has that; plenty of people have a trading bot.
  2. The honest result, stated by us first. 0 of 20 rules are net-positive at the taker rate actually paid; cost is the binding constraint. This is in docs/experiments/ already. A visitor who finds it themselves feels misled; a visitor who is told upfront reads it as rigour.
  3. "keel is not a fatwa engine" — see the positioning issue in Phase 6.
  4. Running it in five minutes, paper mode, no keys, no funds.

Acceptance

  • Newcomer-first structure; the operator runbook content moves to docs/operator-runbook.md (which already exists) rather than being deleted
  • Honest-result section above the fold, linking the experiment record
  • A five-minute paper-mode quickstart that someone can actually follow on a clean machine
  • Architecture sketch: where the rails live, where the rules live, where a broker adapter plugs in
  • Ends with where to ask a question and how to contribute

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationopen-sourceWork toward making keel genuinely open source

Type

No type

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions