Skip to content

docs(readme): rewrite for the newcomer, led by the compliance engine - #300

Merged
eaitbrahim merged 1 commit into
mainfrom
docs/readme-newcomer
Aug 16, 2026
Merged

docs(readme): rewrite for the newcomer, led by the compliance engine#300
eaitbrahim merged 1 commit into
mainfrom
docs/readme-newcomer

Conversation

@eaitbrahim

Copy link
Copy Markdown
Contributor

Closes #281

The README was a 261-line operator runbook — right for the author's future self, wrong for a
stranger deciding whether to spend an afternoon here.

The new first screen

  1. What keel is, led by the compliance engine — 19 deterministic rails, attested screening
    that fails closed, §65.4 qabd as an executable check; the trading agent is the reference
    implementation on top, not the headline.
  2. The honest result, stated by us first — no shipped rule family net-positive at the
    taker fee actually paid; viable intersection empty under production-faithful execution,
    linking docs/experiments/2026-08-13-restated-under-a-production-faithful-engine.md.
  3. The not-a-fatwa-engine boundary (from Phase 6, kept verbatim).
  4. Try it in five minutes — see below.

Quickstart, verified end-to-end on a clean clone (that's why it says keel rules seed,
not keel init: a clone has the tracked config.yaml and init refuses to overwrite it):

git clone … && cd keel
uv sync --all-extras --dev
cp .env.example .env          # free read-only CDP key
uv run keel rules seed
uv run keel fetch
uv run keel simulate --years 1 --skip-within-cap

Two honest caveats are in the text because they were measured: keel fetch without a CDP
key dies in AuthenticationError (tested), and keel simulate on default rules reports
TRAIN MORE with the failing gates named — presented as the engine working, because it is.

Rest of the structure: condensed How-it-works (rules, rails, screening, confirm/autonomy,
ships-inert, the tighter-stop→larger-position mechanic), an architecture sketch naming the
three load-bearing places (keel/execution/guards.py, keel/agent.py,
packages/keel-broker-* port + entry point), a documentation map, and an ending that routes
questions to Discussions (now enabled) and contributions to CONTRIBUTING.md.

Moved, not deleted: deploying/upgrading releases, the paper-vs-live table and its
interactions, and "how much money moves" now live in docs/operator-runbook.md (Part 2,
verbatim in substance).

Tests (tests/test_readme.py, red first): honest result above the fold + cited record
exists; quickstart commands verbatim incl. the CDP caveat and paper path; the three
architecture locations named; README ends with Discussions/CONTRIBUTING routing; operator
content present in the runbook and absent from the README (the anti-runnable-regression
guard).

Gates: pytest 2794 passed / 1 skipped, ruff check clean, mypy clean.

The README was an operator runbook; a stranger deciding whether to spend
an afternoon here needs what is differentiated (19 rails, fails-closed
attested screening, qabd as an executable check), the honest measured
result stated by us first, the not-a-fatwa boundary, and a five-minute
path that actually runs (#281). The operator content moved to
docs/operator-runbook.md unchanged. Quickstart steps verified on a clean
clone, including the AuthenticationError keel fetch raises without a CDP
key -- stated rather than discovered at step four. tests/test_readme.py
pins the structure so the README cannot quietly grow back into a runbook.
@eaitbrahim
eaitbrahim merged commit db7a4d6 into main Aug 16, 2026
1 check passed
@eaitbrahim
eaitbrahim deleted the docs/readme-newcomer branch August 16, 2026 23:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Rewrite README for a newcomer, leading with the compliance engine

1 participant