docs: README rewrite, protocol doc, open-questions

[mirkokiefer]

Summary

Rewrites the README around builder pain first, vocabulary second, then ships the philosophical thesis as a separate PROTOCOL.md plus an open-questions.md collaboration invite.

The current README leads with framework abstractions (scenes, gradients, tiers) before earning the right to use those words. A landing builder bounces. This rewrite reverses the order: the bug-caught moment comes first, the 2-line drop-in is the immediate payoff, and only then does the doc teach the vocabulary — anchored in concrete pictures, not definitions.

What ships

README.md rewrite

• New tagline: "Trace your agent's world, not just its tool calls." — pain-shaped, builder-language, contrasts directly with Phoenix/Langfuse.
• New hero: 60-second drift-caught story (welcome-email-not-sent example) + the 2-line drop-in code, before any framework vocabulary appears.
• New section: "Five words you'll meet, all you need." Teaches scene, diff, goal, gradient, predictor by example, not by definition. Each anchored in a concrete picture or sentence the reader can re-derive without the README.
• Reframed five-tier ladder: each row leads with the dev pain it solves, not the framework feature it adds. Tier 4 in particular framed as "My agent's about to call an irreversible API. I want it to think first."
• "Why this isn't another agent framework" trimmed from 4 to 3 rows.
• "What scenegrad does NOT do" section cut (was 6 negation bullets).
• "Thinking framework" philosophical prose relocated to PROTOCOL.md.
• "Scenes are the unit of agent work" thesis section, three sentences, links to deeper docs for readers who want to go further.
• Stack section promoted from "Related." scenecast listed first as the foundational vocabulary the rest of the stack uses.
• Long GIF caption removed; the GIF still anchors the hero but the description is leaner.

PROTOCOL.md (new)

The protocol scenegrad runs on, as a doc separate from the implementation:

• Five primitives (Scene, Assertion, Goal, Patch, ToolCall, Predictor) with TypeScript signatures and one-paragraph contracts.
• Two derivations (distance, gradient) explained as functions of the primitives.
• The trajectory wire format + WorldModelMetrics scoring surface.
• Pointer to open-questions.md for the unsolved frontier.

The doc is meant to be the canonical reference future implementations target — other languages, other runtimes, learned components — not just one implementation's internals.

docs/open-questions.md (new)

Seven open frontiers, framed as collaboration invitations:

1. What's a good distance function over a typed scene?
2. How do you compute semantic diffs?
3. What's the right scoring rubric for a Predictor?
4. How do gradients compose across multi-actor scenes?
5. Scene design as a teachable craft.
6. The cold-start moat.
7. Adversarial scenes.

Each section ends with explicit unsolved questions. Closes with "Want to push back?" — pointer to the issues tab.

Why this shape

The previous README treated readers as if they'd already absorbed Daslab's worldview. They hadn't. The new README earns the worldview by leading with a recognizable bug, paying off with a 2-line fix, and only then introducing the five words that name what the reader is already looking at.

The thesis — scenes are the unit of agent work — is preserved in full, but lives in PROTOCOL.md where readers who want depth can find it without forcing it on first-time visitors.

Dependency

References tier 4 (Predictor, DreamerSolver, evalWorldModel, examples/dreamer-inbox.ts) which lands in #1. Either:

• Merge feat: tier 4 — Predictor + DreamerSolver + worldmodel eval (v0) #1 first, then this. Cleanest.
• Or merge this first; the tier-4 references in the README will be live once feat: tier 4 — Predictor + DreamerSolver + worldmodel eval (v0) #1 ships in v0.0.2 (already noted in the Status section).

Either order works; flagging in case there's a preferred merge sequence.

Test plan

• Markdown renders correctly on GitHub (long lines wrapped, code blocks tagged, links resolve).
• Internal links (./PROTOCOL.md, ./docs/open-questions.md) point at files that exist on this branch.
• Eyeball pass — does a hands-on builder reach the 5-tier ladder before bouncing?
• Drift-caught hero screenshot — flagged as a follow-up. The current GIF is the bulk-trajectory view, which still works for the hero but isn't the one image that closes the sale. A purpose-shot screenshot of the assertion-fired-red moment would be the strongest single upgrade.