Restructure draft handling documentation with lifecycle focus

[oblomov-dev]

Summary

Completely restructured the draft handling documentation to prioritize conceptual understanding and practical examples over raw EML primitives. The new structure introduces drafts through an everyday analogy, presents a visual lifecycle diagram, and provides a minimal working example before diving into the full production app.

Key Changes

• Added conceptual introduction — New "What Is a Draft?" section with an everyday analogy (published document vs. unsaved changes) and mental model table to help readers understand the purpose of drafts
• Introduced visual lifecycle diagram — ASCII diagram showing the four states (ACTIVE → EDIT → DRAFT → ACTIVATE/DISCARD) to make the flow immediately clear
• Reorganized EML primitives — Renamed from "The EML Primitives" to "The Four Building Blocks" and reordered to match the actual workflow (Edit → Read → Activate → Discard) rather than Create-first
• Added minimal working example — New "Your First Draft App (Minimal)" section with a complete, runnable 3-step app before the full production version, making the concepts concrete
• Expanded production app context — Clarified why the full app is needed (read-only start, two modes, existing draft handling, confirmation dialogs)
• Added Common Pitfalls table — New section with a quick reference table of the most frequent beginner mistakes (forgetting UPDATE FIELDS, missing COMMIT, wrong %is_draft flag, etc.)
• Improved inline explanations — Added clarifying comments in code examples and callout boxes (::: tip and ::: warning) to highlight critical details like the two-step save process
• Refined terminology — Consistently use "RAP framework" instead of "BO framework" and clarified that SAP provides both the BO and draft table

Notable Implementation Details

• The minimal app demonstrates the three-step lifecycle (open → edit → activate) in under 80 lines, making it immediately clear what a draft app does
• The pitfalls table directly addresses the most common errors with root causes and fixes, reducing support burden
• The lifecycle diagram is the single source of truth for understanding the flow — all subsequent code examples map back to it
• Callout boxes highlight the two-step save process (UPDATE FIELDS then Activate) as the #1 beginner mistake

https://claude.ai/code/session_019A4HnWAzLN5zzN15hLVRdv