Docs: Add checkpoint-filter.ts explanation to README

Author: FL4TLiN3

examples/github-issue-bot/README.md

@@ -50,6 +50,82 @@ Add `ANTHROPIC_API_KEY` with your Anthropic API key.
 
 ---
 
+## How checkpoint-filter.ts Works
+
+`checkpoint-filter.ts` is a working example of processing Perstack's event stream.
+
+### Event Stream
+
+When you run `perstack run --stream-events`, it outputs JSON events to stdout:
+
+```json
+{"type":"callTool","toolCall":{"toolName":"think","args":{"thought":"..."}}}
+{"type":"callTool","toolCall":{"toolName":"readTextFile","args":{"path":"..."}}}
+{"type":"completeRun","text":"Final answer here"}
+```
+
+### Processing Events
+
+The filter reads stdin line by line, parses JSON, and formats human-readable output:
+
+```typescript
+function formatEvent(event: Record<string, unknown>): string | null {
+  const type = event.type as string
+  switch (type) {
+    case "callTool": {
+      const toolCall = event.toolCall as Record<string, unknown>
+      const toolName = toolCall?.toolName as string
+      const args = toolCall?.args as Record<string, unknown>
+      if (toolName === "think") {
+        return `💭 ${args?.thought}`
+      }
+      if (toolName === "readTextFile") {
+        return `📖 Reading: ${args?.path}`
+      }
+      // ... more tool handlers
+    }
+    case "completeRun": {
+      finalAnswer = event.text as string
+      return "✅ Done"
+    }
+  }
+}
+```
+
+### Real-time Updates
+
+The filter updates a GitHub comment in real-time using the GitHub API:
+
+```typescript
+const res = await fetch(
+  `https://api.github.com/repos/${GITHUB_REPO}/issues/comments/${COMMENT_ID}`,
+  {
+    method: "PATCH",
+    headers: { Authorization: `Bearer ${GH_TOKEN}` },
+    body: JSON.stringify({ body: formattedLog }),
+  }
+)
+```
+
+### Event Types
+
+| Event Type    | Description                    | Example Output          |
+| ------------- | ------------------------------ | ----------------------- |
+| `callTool`    | Tool invocation                | `📖 Reading: src/app.ts` |
+| `completeRun` | Run completed with final text  | `✅ Done`                |
+
+### Tool-specific Formatting
+
+| Tool Name           | Icon | Output                          |
+| ------------------- | ---- | ------------------------------- |
+| `think`             | 💭   | Thought content (truncated)     |
+| `readTextFile`      | 📖   | File path                       |
+| `listDirectory`     | 📁   | Directory path                  |
+| `exec`              | ⚡   | Command + args                  |
+| `attemptCompletion` | ✨   | "Generating answer..."          |
+
+---
+
 ## Trigger Conditions
 
 | Event             | Trigger                            |
@@ -73,8 +149,8 @@ For OpenAI, add `OPENAI_API_KEY` secret instead.
 
 ## Files
 
-| File                   | Purpose                 |
-| ---------------------- | ----------------------- |
-| `issue-bot.yml`        | GitHub Actions workflow |
-| `checkpoint-filter.ts` | Real-time log formatter |
-| `perstack.toml`        | Expert definition       |
+| File                   | Purpose                                  |
+| ---------------------- | ---------------------------------------- |
+| `issue-bot.yml`        | GitHub Actions workflow                  |
+| `checkpoint-filter.ts` | Event stream processor (working example) |
+| `perstack.toml`        | Expert definition                        |