docs: split playbookitem explanation and add pseudocode

Author: visionik

README.md

@@ -430,7 +430,30 @@ Playbook {
 
 **Purpose**: A single append-only event that creates, refines, or deprecates a logical playbook entry.
 
-PlaybookItems are modeled as an append-only event log so tools can evolve guidance without rewriting history: changes become auditable, mergeable, and safe under concurrent edits. Each PlaybookItem is an immutable event in the log (once written, it is never edited or deleted; changes are represented by appending a new event). Events with the same `targetId` form a single logical “thread” (one playbook entry evolving over time), where each event captures a state change or refinement. When a tool updates or deprecates an entry, it appends a new event (with a new `eventId`) that references the same thread via `targetId`, and points to the most recent prior event in that thread via `prevEventId`—creating a verifiable chain and enabling conflict detection if two updates fork from the same predecessor. Consumers can reconstruct the “latest state” per `targetId` by following the thread. `eventId` uniquely identifies the event itself; `targetId` identifies the evolving entry.
+PlaybookItems are modeled as an append-only event log so tools can evolve guidance without rewriting history: changes become auditable, mergeable, and safe under concurrent edits. Each PlaybookItem is an immutable event in the log (once written, it is never edited or deleted; changes are represented by appending a new event).
+
+Events with the same `targetId` form a single logical “thread” (one playbook entry evolving over time). Each update appends a new event (with a new `eventId`) that references the thread via `targetId`, and points to the most recent prior event in that thread via `prevEventId`—creating a verifiable chain and enabling conflict detection if two updates fork from the same predecessor. Consumers can reconstruct the “latest state” per `targetId` by following the thread.
+
+```javascript
+// Pseudocode: append a new event to an existing thread
+function appendPlaybookEvent(playbook, targetId, patch) {
+  const prev = findLatestEventForTarget(playbook.items, targetId);
+
+  const evt = {
+    eventId: newEventId(),
+    targetId: targetId,
+    operation: "update",
+    prevEventId: prev.eventId,
+    createdAt: nowRFC3339(),
+    ...patch
+  };
+
+  playbook.items.push(evt);
+  playbook.updated = evt.createdAt;
+}
+```
+
+`eventId` uniquely identifies the event itself; `targetId` identifies the evolving entry.
 
 **Required fields (by operation)**: