Rewrite the README in plain English

[pedro-pscunha]

What changed

README.md is rewritten in simple-english pragmatic mode, with the heading order and glossary
shared by the three guideme SDKs (guideme-goals/2026-09-22-readme-skeleton.md).

Headings: Install, Quick start, Questions, When the model is not sure, Examples and
counterexamples, Several questions in one request, The receipt, Errors, Retries and timeouts,
Testing your code, Observability, Configuration, Lower layers, Other SDKs, Development, License.

• The first screen says what the library does, in three sentences.
• One word, one meaning: "question", "answer", "option", "level", "rubric", "unsure",
  "policy", "fallback", "unsure ladder", "setting", "state", "transport", "error kind".
  "judgment" appears once, in the intro.
• The Errors table gains an "Error kind" column (Error::kind(), the error.type on a span).
• Facts added from the code: Error is #[non_exhaustive]; .detail() drops an earlier
  .or(..); Levels has no fallback (use .or(level)); a line break in an example is refused;
  timeout(..) beside http(..) is Error::Config; from_env does not combine with
  client(..); guide.models().
• One correction: the guideme.retry warning fires before every retry wait, including after a
  failure to connect, not only on a throttle (api/client.rs, warn_retry).
• "Other SDKs" lists three SDKs. The TypeScript row links the repository only and says
  "@guideme/sdk (not yet on npm)".
• Every Rust block is plain rust or no_run and self-contained. The two blocks that used
  # hidden lines (batch, receipt) are rewritten so nothing renders literally on GitHub or
  crates.io. The subscriber block that Cargo.toml cites and the guideme::api::reqwest path
  that guideme/tests/batch.rs cites both stay.
• CHANGELOG.md: an Unreleased → Documentation note. No version bump.

What moved where

Nothing needed a new home. Every fact that left the README was already recorded in the repo:

• The 0.75 / 0.25 measurement for noul examples: docs/design.md (Decisions, "All three kinds
  take examples").
• Why a timeout is not retried: docs/contract.md §4 (retry policy), linked from Retries and
  timeouts. No prose was added to docs/contract.md.
• Span and event field lists, OTLP log records, exporter environment variables:
  docs/observability.md.
• Tooling, commands, lint set, test policy, live tests, hooks: AGENTS.md and
  CONTRIBUTING.md, both linked from Development.

Dropped, with reasons (from the claim ledger):

• The Cargo.toml alternative to cargo add: the same two dependencies.
• The paragraph describing Python's API (enum.Enum bases, .otherwise, AsyncGuide): the
  Python README owns it.

Line counts

Before: 483 lines. After: 467 lines, code included. The shared target is "at most about 320".
The review accepted the length: 10 compiled Rust blocks, self-contained because hidden lines are
not allowed, are most of it, and the guide stays one file.

Review fixes (second commit)

Five Majors: the Quick start builds the guide once in #[tokio::main] and passes &Guide; its
fallback now fires under .min_confidence(0.6); batch ids follow BTreeMap key order
(ask.rs); p, confidence and threshold are defined before "unsure"; the policy example
patches yes_above(0.9), which a yes/no question uses. Plus 38 Minors (definitions at first
use, required derives, attribute keys, option and level counts in the Config row, a narrower
cross-SDK claim, a merged Configuration table).

Out of scope

The docs.rs front page (guideme/src/lib.rs //!) is unchanged. The crates.io page keeps the
0.2.0 README until the next release.

Verification

• cargo test --doc -p guideme: 14 passed, 10 of them the README blocks.
• cargo package -p guideme --list still lists README.md at the package root. The
  guideme/README.md symlink is unchanged.
• The pre-push gate (mise run check: fmt, clippy, nextest 35/35, doctests, rustdoc,
  cargo-deny) passed.
• rg -n -i readme over the repo: AGENTS.md:188-194 (symlink rule, unchanged and still
  true), guideme/src/lib.rs:64-69 (the doctest item; the blocks still compile),
  guideme/tests/batch.rs:12 (the README still names guideme::api::reqwest),
  Cargo.toml:29 (the subscriber doctest still exists), guideme/Cargo.toml:11 (readme
  key), CHANGELOG.md:51 (a 0.1.x history entry; the "Testing your code" heading still
  exists). No change needed.
• Self-check: no sentence over 20 words in procedural text or 25 in descriptive text. No
  semicolons outside code and the rubric block. No should/may/might/could/would,
  simply/just/easily, contractions or Latin abbreviations. Every if/when starts its sentence.