@playcraft/cli 0.0.44 → 0.0.46

package/project-template/.claude/skills/playcraft-text-rendering/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playcraft-text-rendering
-description: PlayCraft 可玩广告文字渲染完整指南。涵盖全烤图策略（零字体文件）、静态文字图片规格、动态数字 Digit Sprite Strip 规格与运行时帧切割渲染模板、layout-spec textAssets 字段说明、三角色（Designer/TA/Developer）各自职责。任何涉及游戏内文字、字体、数字显示、分数、计时器的场景前必读。
+description: PlayCraft 可玩广告文字渲染完整指南。涵盖全烤图策略（零字体文件）、静态文字图片规格、动态数字 Digit Sprite Strip 规格与运行时帧切割渲染模板、layout-spec textAssets 字段说明、三角色（Artist/TA/Developer）各自职责。任何涉及游戏内文字、字体、数字显示、分数、计时器的场景前必读。
 triggers: 文字,字体,font,text,数字,digit,分数,score,计时器,timer,倒计时,countdown,sprite strip,digit strip,CTA文字,游戏标题,label,艺术字,显示字体,烤图,text rendering
 ---
 
@@ -17,11 +17,11 @@ triggers: 文字,字体,font,text,数字,digit,分数,score,计时器,timer,倒
 ```
 文字类型决策树：
 ├── 内容固定不变？
-│   ├── 是 → 静态文字图片（Designer 烤入 Master Composite → TA 提取）
+│   ├── 是 → 静态文字图片（Artist 烤入 Master Composite → TA 提取）
 │   └── 否 → 动态文字
 │       ├── 仅数字/符号？
-│       │   ├── 是 → Digit Sprite Strip（Designer 生成 → Developer 帧切割）
-│       │   └── 否 → 扩展 Sprite Strip 字符集（PM 在 layout-spec 指定）
+│       │   ├── 是 → Digit Sprite Strip（Artist 生成 → Developer 帧切割）
+│       │   └── 否 → 扩展 Sprite Strip 字符集（Game Designer 在 layout-spec 指定）
 ```
 
 ---
@@ -42,13 +42,13 @@ triggers: 文字,字体,font,text,数字,digit,分数,score,计时器,timer,倒
 
 ### 生产流程
 
-1. **PM**：在 `layout-spec.md` `## Text Assets > Static Text` 表中列出所有静态文字，指定资产路径
-2. **Designer**：在 Master Composite 的 concept panel 中，将所有静态文字以**艺术风格**渲染（不是随便加文字——文字本身就是美术的一部分）
+1. **Game Designer**：在 `layout-spec.md` `## Text Assets > Static Text` 表中列出所有静态文字，指定资产路径
+2. **Artist**：在 Master Composite 的 concept panel 中，将所有静态文字以**艺术风格**渲染（不是随便加文字——文字本身就是美术的一部分）
 3. **TA**：从 MC concept panel **逐条**提取（`crop` 优先；`segment --text` 最后手段）→ layout-spec 路径
-4. **提取失败** → ICP → **Designer** 交付该 id 的**单张**孤立 PNG（`designer-deliverable-spec.md`）
+4. **提取失败** → ICP → **Artist** 交付该 id 的**单张**孤立 PNG（`artist-deliverable-spec.md`）
 5. **Developer**：`loadImage(path)` per Asset Contract
 
-> Rows must appear in `designer-log` **ASR Coverage Matrix** (`Type: text`).
+> Rows must appear in `artist-log` **ASR Coverage Matrix** (`Type: text`).
 
 ### layout-spec 格式
 
@@ -80,11 +80,11 @@ triggers: 文字,字体,font,text,数字,digit,分数,score,计时器,timer,倒
 
 ### 生产流程
 
-1. **PM**：在 `layout-spec.md` `## Text Assets > Digit Sprite Strip` 中定义：
+1. **Game Designer**：在 `layout-spec.md` `## Text Assets > Digit Sprite Strip` 中定义：
    - `characters`：字符集字符串（如 `"0123456789:,."`）
    - `cell size`：单个字符的宽高（如 `64x80`）
    - `asset path`：如 `assets/images/ui/digits.png`
-2. **Designer**：Phase 2 生成整条 strip 图片（见下方生成命令），确保：
+2. **Artist**：Phase 2 生成整条 strip 图片（见下方生成命令），确保：
    - 字符按 `characters` 字符串顺序从左到右排列
    - 每个字符等宽（= cellWidth），高度 = cellHeight
    - 艺术风格与 confirmed Master Composite 一致（使用 composite 作 `--reference-image`）
@@ -93,7 +93,7 @@ triggers: 文字,字体,font,text,数字,digit,分数,score,计时器,timer,倒
 3. **TA**：验证 strip 尺寸（见下方验证命令），不合规则 resize 修正
 4. **Developer**：运行时帧切割渲染（见下方代码模板）
 
-### Designer 生成命令
+### Artist 生成命令
 
 ```bash
 # 计算总尺寸
@@ -144,7 +144,7 @@ playcraft image resize \
 | 分数 + 倍率   | `0123456789x+,.`     | 14 字符 |
 | 完整          | `0123456789:,.x+-/%` | 18 字符 |
 
-> PM 根据项目实际需求在 layout-spec 中指定，不使用固定字符集。
+> Game Designer 根据项目实际需求在 layout-spec 中指定，不使用固定字符集。
 
 ---
 
@@ -153,10 +153,10 @@ playcraft image resize \
 ### Canvas 2D 帧切割
 
 ```javascript
-const DIGIT_CHARS = "0123456789:,."; // ← from layout-spec
+const DIGIT_CHARS = '0123456789:,.'; // ← from layout-spec
 const CELL_W = 64; // ← from layout-spec
 const CELL_H = 80; // ← from layout-spec
-const digitImg = await loadImage("assets/images/ui/digits.png");
+const digitImg = await loadImage('assets/images/ui/digits.png');
 
 function drawText(ctx, text, x, y, scale = 1) {
   const w = CELL_W * scale;
@@ -180,8 +180,8 @@ function drawText(ctx, text, x, y, scale = 1) {
 }
 
 // Usage
-drawText(ctx, "12345", 100, 50); // score
-drawText(ctx, "0:30", 300, 10, 0.75); // timer (scaled down)
+drawText(ctx, '12345', 100, 50); // score
+drawText(ctx, '0:30', 300, 10, 0.75); // timer (scaled down)
 ```
 
 ### 对齐辅助
@@ -204,13 +204,13 @@ function drawTextRight(ctx, text, rightX, y, scale = 1) {
 
 ```javascript
 const atlas = new pc.TextureAtlas();
-atlas.setFrame("0", { rect: new pc.Vec4(0, 0, CELL_W, CELL_H) });
-atlas.setFrame("1", { rect: new pc.Vec4(CELL_W, 0, CELL_W, CELL_H) });
+atlas.setFrame('0', { rect: new pc.Vec4(0, 0, CELL_W, CELL_H) });
+atlas.setFrame('1', { rect: new pc.Vec4(CELL_W, 0, CELL_W, CELL_H) });
 // ... register all chars
 
 const sprite = new pc.Sprite(app.graphicsDevice, {
   atlas: atlas,
-  frameKeys: DIGIT_CHARS.split(""),
+  frameKeys: DIGIT_CHARS.split(''),
 });
 ```
 
@@ -218,19 +218,19 @@ const sprite = new pc.Sprite(app.graphicsDevice, {
 
 ## 4. 角色职责速查
 
-| 角色          | 文字相关职责                                                                                       |
-| ------------- | -------------------------------------------------------------------------------------------------- |
-| **PM**        | 在 layout-spec `textAssets` 中定义：静态文字列表 + digit strip 字符集/尺寸/路径                    |
-| **Designer**  | ① Master Composite concept panel 中渲染所有静态文字（艺术风格）；② Phase 2 生成 digit sprite strip |
-| **TA**        | ① 从 composite 提取静态文字图片（segment → resize）；② 验证 digit strip 尺寸合规                   |
-| **Developer** | ① 静态文字按 Asset Contract 路径加载图片；② digit strip 帧切割渲染（上方代码模板）                 |
+| 角色              | 文字相关职责                                                                                       |
+| ----------------- | -------------------------------------------------------------------------------------------------- |
+| **Game Designer** | 在 layout-spec `textAssets` 中定义：静态文字列表 + digit strip 字符集/尺寸/路径                    |
+| **Artist**        | ① Master Composite concept panel 中渲染所有静态文字（艺术风格）；② Phase 2 生成 digit sprite strip |
+| **TA**            | ① 从 composite 提取静态文字图片（segment → resize）；② 验证 digit strip 尺寸合规                   |
+| **Developer**     | ① 静态文字按 Asset Contract 路径加载图片；② digit strip 帧切割渲染（上方代码模板）                 |
 
 ---
 
 ## 5. 注意事项
 
-1. **文字是美术的一部分**——Designer 不是"随便加文字"，而是将文字作为视觉设计元素融入 concept
+1. **文字是美术的一部分**——Artist 不是"随便加文字"，而是将文字作为视觉设计元素融入 concept
 2. **digit strip 字符顺序必须与 layout-spec 一致**——Developer 按索引切割，顺序错了显示就错
 3. **不要用 CSS text-shadow / -webkit-text-stroke 模拟艺术字**——这不是 web 页面，是游戏
 4. **CTA 按钮文字也是图片**——按钮背景 + 文字都从 composite 提取，Developer 只管点击事件
-5. **多语言场景**：如需多语言，PM 在 layout-spec 中为每种语言指定独立的文字资产路径，Designer 为每种语言生成对应文字
+5. **多语言场景**：如需多语言，Game Designer 在 layout-spec 中为每种语言指定独立的文字资产路径，Artist 为每种语言生成对应文字

package/project-template/.claude/skills/session-analyzer/SKILL.md

@@ -0,0 +1,386 @@
+---
+name: session-analyzer
+description: >
+  Navigate and analyze AI coding session logs (Claude Code / Claude Internal / CodeBuddy).
+  Use when asked to find specific tool calls, understand what happened in a turn,
+  trace subagent work, or answer "what did the agent do here?" questions.
+triggers: session, turn, subagent, agent做了什么, 为什么这么多步骤, 查会话, 分析session, 读日志
+---
+
+# Session Analyzer
+
+Analyze AI coding assistant session logs stored as JSONL files in the session tracker project
+(`D:\project\cli-tool-tracker`).
+
+## Quick Reference: Directory Layout
+
+```
+~/.claude/projects/                      ← Claude Code sessions
+  {project-slug}/
+    {session-uuid}.jsonl                 ← main session file
+    {session-uuid}/subagents/            ← subagent files
+      agent-{hex}.jsonl
+      agent-{hex}.meta.json
+
+~/.claude-internal/projects/             ← Claude Internal sessions
+  {project-slug}/
+    {session-uuid}.jsonl                 ← main session file
+    {session-uuid}/subagents/
+      agent-{hex}.jsonl
+      agent-{hex}.meta.json
+
+~/.codebuddy/projects/                   ← CodeBuddy sessions
+  {project-slug}/
+    {session-uuid}.jsonl
+    {session-uuid}/subagents/
+      agent-{hex}.jsonl
+```
+
+## How to Find a Specific Session
+
+### Method 1: Use the Session Tracker UI
+
+1. Start the tracker: `cd D:\project\cli-tool-tracker && pnpm run dev`
+2. Select the source tab (CodeBuddy / Claude / Claude Internal)
+3. Find the project in the Projects list → click to list sessions
+4. Click a session to see its turns
+5. Click a turn to see events (tool calls, messages, reasoning)
+6. Click any event to see full context (input/output/raw JSON)
+
+### Method 2: Command-line Search
+
+```powershell
+# Find project directories
+ls ~\.claude-internal\projects\ | Where Name -like "*keyword*"
+
+# List sessions in a project
+ls ~\.claude-internal\projects\D--project-{name}\ | Where Name -like "*.jsonl"
+
+# Find a specific session by date/size
+ls ~\.claude-internal\projects\D--project-{name}\*.jsonl | Sort Length -Desc | Select -First 10 Name,Length
+
+# Search JSONL for specific tool calls
+Select-String -Path "path\to\session.jsonl" -Pattern '"name":"Agent"' | Select -First 10 LineNumber,Line
+
+# Search for specific content in a session
+Select-String -Path "path\to\session.jsonl" -Pattern "keyword" | Select LineNumber,@{n='Preview';e={$_.Line.Substring(0,200)}}
+```
+
+## JSONL Line Types (Claude / Claude-Internal Format)
+
+Each line is a JSON object with a `type` field:
+
+| Line Type                      | Description                 | Key Fields                                                                  |
+| ------------------------------ | --------------------------- | --------------------------------------------------------------------------- |
+| `"user"`                       | User message or tool result | `message.content` (text or tool_result blocks)                              |
+| `"assistant"`                  | AI response                 | `message.content` (thinking/text/tool_use blocks), `message.usage` (tokens) |
+| `"system"`                     | System event                | `subtype`, `content`                                                        |
+| `"attachment"`                 | Skill listing, permissions  | `attachment.type`, `attachment.content`                                     |
+| `"file-history-snapshot"`      | File tracking               | `snapshot.trackedFileBackups`                                               |
+| `"ai-title"`                   | Auto-generated title        | `aiTitle`                                                                   |
+| `"mode"` / `"permission-mode"` | Session config              | `mode`, `permissionMode`                                                    |
+
+### Assistant Message Content Blocks
+
+Within an `"assistant"` line, `message.content[]` contains:
+
+| Block Type   | Description                | Data Location                                             |
+| ------------ | -------------------------- | --------------------------------------------------------- |
+| `"thinking"` | Model's reasoning/thinking | `block.thinking` (text), `block.signature`                |
+| `"text"`     | Display text reply         | `block.text`                                              |
+| `"tool_use"` | Tool call                  | `block.name`, `block.id` (callId), `block.input` (params) |
+
+### Tool Result Content Blocks
+
+Within a `"user"` line, `message.content[]` contains:
+
+| Block Type      | Description           | Data Location                                                                    |
+| --------------- | --------------------- | -------------------------------------------------------------------------------- |
+| `"tool_result"` | Tool execution result | `block.tool_use_id` (matches callId), `block.content` (output), `block.is_error` |
+
+## Subagent Relationship
+
+### How Subagents are Spawned
+
+1. Main agent calls `Agent` tool → `function_call` event with `toolName: "Agent"`
+2. Runtime spawns a subagent process → writes to `subagents/agent-{hex}.jsonl`
+3. When subagent finishes → `function_call_result` with `toolUseResult.agentId: "{hex}"`
+4. The `agentId` links the main session's Agent call to the subagent file
+
+**Critical**: In Claude Internal format, `agentId` is at `toolUseResult.agentId` in the JSONL
+(outer structure of the result line), NOT in the text content.
+
+### Subagent File Format
+
+Same as main JSONL but with:
+
+- `"agentId": "a2834ad1c500a2f8c"` on user/assistant lines
+- `"isSidechain": true` on all lines
+- `"attributionAgent": "Explore"` on assistant lines (agent type)
+- Each subagent file = one agent invocation (may have multiple turns internally)
+
+### How to Trace Subagent Work
+
+1. In the main session JSONL, find the Agent `tool_use` line → note `block.id` (callId)
+2. Find the corresponding `tool_result` line (same `tool_use_id`)
+3. Extract `agentId` from `toolUseResult.agentId`
+4. The subagent file is `subagents/agent-{agentId}.jsonl`
+5. Read that file to see what the subagent did
+
+## Turn Structure
+
+A **turn** starts when the user sends a message and ends when the AI finishes responding
+(including all tool calls and their results). The turn splitter detects turns by:
+
+- A `user` message (not a tool_result) → starts a new turn
+- If `parentUuid` points to an assistant message → new turn
+- If `parentUuid` points to another user message → continuation of current turn
+
+Turns contain: user message → assistant thinking → assistant text → tool calls → results → more assistant responses → ...
+
+## How to Analyze a Turn
+
+### Step 1: Identify the Turn Boundaries
+
+```powershell
+# In the tracker UI: expand a turn to see its events
+# OR manually in JSONL:
+Select-String -Path "session.jsonl" -Pattern '"type":"user".*"role":"user"' | Select LineNumber
+```
+
+### Step 2: List All Tool Calls in a Turn
+
+```powershell
+Select-String -Path "session.jsonl" -Pattern '"type":"tool_use"' | Select LineNumber,@{n='Tool';e={if($_.Line -match '"name":"([^"]+)"'){$matches[1]}}}
+```
+
+### Step 3: Find Agent (Subagent) Calls
+
+```powershell
+Select-String -Path "session.jsonl" -Pattern '"name":"Agent"' -Context 0,5 | Select LineNumber
+```
+
+### Step 4: Check Subagent Results
+
+```powershell
+# Find results of a specific tool_use_id
+Select-String -Path "session.jsonl" -Pattern "TOOL_USE_ID_HERE" | Select LineNumber
+```
+
+### Step 5: Read Subagent Files
+
+```powershell
+ls "session-dir\subagents\agent-*.jsonl" | ForEach { Write-Host "--- $($_.Name) ---"; Get-Content $_.FullName -Head 3 }
+```
+
+## Reusable Analysis Scripts
+
+All scripts are in the `scripts/` directory relative to this skill. Run with Node.js (ESM).
+
+### Quick Reference
+
+| Script                       | Purpose                                    | Usage                                                           |
+| ---------------------------- | ------------------------------------------ | --------------------------------------------------------------- |
+| `resolve-session.mjs`        | Find session file path by project keyword  | `node scripts/resolve-session.mjs <keyword> [uuid]`             |
+| `find-turns.mjs`             | List all user-initiated turns in a session | `node scripts/find-turns.mjs <session.jsonl>`                   |
+| `turn-timeline.mjs`          | Show event timeline for a line range       | `node scripts/turn-timeline.mjs <session.jsonl> <start> [end]`  |
+| `subagent-stats.mjs`         | Extract stats for all Agent calls          | `node scripts/subagent-stats.mjs <session.jsonl> [start] [end]` |
+| `subagent-tool-timeline.mjs` | Show tool call sequence in a subagent      | `node scripts/subagent-tool-timeline.mjs <subagent.jsonl>`      |
+| `time-gaps.mjs`              | Find performance bottleneck (time gaps)    | `node scripts/time-gaps.mjs <file.jsonl> [--threshold 5]`       |
+| `heavy-output.mjs`           | Find heaviest output turns                 | `node scripts/heavy-output.mjs <file.jsonl> [--min-kb 3]`       |
+| `execution-breakdown.mjs`    | Auto-detect phases & time allocation       | `node scripts/execution-breakdown.mjs <subagent.jsonl>`         |
+
+### Typical Analysis Workflow
+
+```bash
+# 1. Resolve session path
+node scripts/resolve-session.mjs tencent-test10 55f43f72-...
+
+# 2. Find turns
+node scripts/find-turns.mjs /path/to/session.jsonl
+
+# 3. Look at specific turn (e.g. turn starting at line 205, ending at 337)
+node scripts/turn-timeline.mjs /path/to/session.jsonl 205 337
+
+# 4. Get subagent stats (which agents ran, how long, how many tokens)
+node scripts/subagent-stats.mjs /path/to/session.jsonl 205 337
+
+# 5. Deep-dive into a slow subagent
+node scripts/subagent-tool-timeline.mjs /path/to/subagents/agent-abc123.jsonl --compact
+node scripts/time-gaps.mjs /path/to/subagents/agent-abc123.jsonl --threshold 5
+node scripts/execution-breakdown.mjs /path/to/subagents/agent-abc123.jsonl
+node scripts/heavy-output.mjs /path/to/subagents/agent-abc123.jsonl --min-kb 3
+```
+
+### Script Details
+
+#### resolve-session.mjs
+
+Searches all three session stores (Claude Code / Claude Internal / CodeBuddy) by keyword.
+
+- With just a keyword: lists all sessions in matching projects (sorted by size)
+- With keyword + UUID: resolves to exact file path + lists subagent files
+
+#### find-turns.mjs
+
+Identifies turn boundaries by finding user messages with `promptSource` (typed/system).
+
+- `--verbose`: show previews for all turns (not just typed)
+- Distinguishes user-typed vs system-triggered turns
+
+#### turn-timeline.mjs
+
+Shows chronological events within a line range. Tags each event:
+
+- `THINK [size]`: thinking blocks with size indicator
+- `TOOL: <name>`: tool calls with input preview
+- `RESULT(OK/ERR)`: tool results
+- `NOTIFY`: system notifications
+
+#### subagent-stats.mjs
+
+For each Agent tool call in the range, extracts from `toolUseResult`:
+
+- `agentId`, `agentType`, `status`
+- `totalDurationMs`, `totalTokens`, `totalToolUseCount`
+- `toolStats` breakdown (read/search/bash/edit counts, lines added/removed)
+- Summary comparison table when multiple agents found
+
+#### subagent-tool-timeline.mjs
+
+Parses a subagent's JSONL to show every tool call in sequence.
+
+- `--compact`: one line per call (good for overview)
+- Shows file names for Read/Write/Edit, commands for Bash
+- Includes tool count summary at the end
+
+#### time-gaps.mjs
+
+Finds the largest time gaps between events to identify bottlenecks.
+
+- `--threshold <seconds>`: minimum gap to report (default: 10s)
+- `--top <N>`: how many gaps to show (default: 10)
+- Classifies each gap: LLM thinking, tool execution, bash command
+- Shows gap category summary with percentages
+
+#### heavy-output.mjs
+
+Finds turns that generated the most content (thinking + text + file writes).
+
+- `--min-kb <N>`: minimum output size to report (default: 5KB)
+- `--top <N>`: how many to show (default: 15)
+- Breaks down: thinking KB, text KB, write KB
+- Shows output category breakdown (thinking vs text vs file writes)
+
+#### execution-breakdown.mjs
+
+Auto-detects "phases" in a subagent's execution and calculates time allocation.
+
+- Groups by: thinking, reading files, writing files, bash commands, etc.
+- Classifies bash commands: npm install, dev server, process debugging, etc.
+- Shows time allocation with ASCII bar chart
+- Useful for answering "where did the time go?"
+
+## Legacy PowerShell Scripts (kept for reference)
+
+### Helper Script: Find Subagent Files for a Session
+
+```powershell
+# Save as: find-subagents.ps1
+param($SessionPath)
+
+$dir = Split-Path $SessionPath -Parent
+$sid = Split-Path $SessionPath -Leaf
+$sid = $sid -replace '\.jsonl$',''
+$subDir = Join-Path $dir $sid 'subagents'
+if (Test-Path $subDir) {
+    Get-ChildItem $subDir -Filter "agent-*.jsonl" | ForEach-Object {
+        $first = Get-Content $_.FullName -Head 1 | ConvertFrom-Json
+        $agentType = $first.attributionAgent ?? $first.message?.role ?? "?"
+        $lines = (Get-Content $_.FullName | Measure-Object).Count
+        Write-Host "$($_.Name) | type: $agentType | lines: $lines"
+    }
+} else {
+    Write-Host "No subagents directory at $subDir"
+}
+```
+
+### Helper Script: Summarize a Turn
+
+```powershell
+# Save as: summarize-turn.ps1
+# Usage: .\summarize-turn.ps1 -SessionPath "session.jsonl" -TurnStartLine 100
+param($SessionPath, $TurnStartLine = 1, $MaxLines = 500)
+
+$lines = Get-Content $SessionPath
+$end = [Math]::Min($TurnStartLine + $MaxLines, $lines.Count)
+
+for ($i = $TurnStartLine - 1; $i -lt $end; $i++) {
+    $line = $lines[$i]
+    try { $obj = $line | ConvertFrom-Json } catch { continue }
+
+    $ln = $i + 1
+    $ts = if ($obj.timestamp) { [DateTime]::Parse($obj.timestamp).ToString("HH:mm:ss") } else { "" }
+
+    if ($obj.type -eq 'user') {
+        $content = $obj.message.content
+        if ($content -is [string]) { Write-Host "[$ln] $ts USER: $content" }
+        elseif ($content[0].type -eq 'tool_result') {
+            $tid = $content[0].tool_use_id.Substring(0,20)
+            Write-Host "[$ln] $ts RESULT: $tid"
+        }
+    }
+    elseif ($obj.type -eq 'assistant') {
+        foreach ($b in $obj.message.content) {
+            if ($b.type -eq 'text') { Write-Host "[$ln] $ts TEXT: $($b.text.Substring(0,[Math]::Min(80,$b.text.Length)))" }
+            elseif ($b.type -eq 'thinking') { Write-Host "[$ln] $ts THINK: $($b.thinking.Substring(0,[Math]::Min(80,$b.thinking.Length)))" }
+            elseif ($b.type -eq 'tool_use') { Write-Host "[$ln] $ts TOOL: $($b.name) | $($b.id.Substring(0,20))" }
+        }
+    }
+    elseif ($obj.type -eq 'ai-title') { Write-Host "[$ln] $ts TITLE: $($obj.aiTitle)" }
+}
+```
+
+## Understanding a Turn: Step-by-Step Analysis
+
+When asked "what happened in this turn?" or "why did it do this?", follow this process:
+
+1. **Read the turn title** (`ai-title` lines) for high-level summary
+2. **Read the user message** — what was the request?
+3. **Read the assistant thinking** — what was the model planning?
+4. **List all tool calls** in order — what actions were taken?
+5. **For each Agent call**: check the subagent file to see what it explored/did
+6. **Read the tool results** — what came back?
+7. **Read the assistant text replies** — what was communicated?
+
+## Token Usage
+
+Each assistant message has `message.usage`:
+
+```json
+"usage": {
+  "input_tokens": 25441,
+  "output_tokens": 186,
+  "cache_read_input_tokens": 10624,
+  "cache_creation_input_tokens": 0
+}
+```
+
+- `input_tokens` + `output_tokens` = total tokens for this API call
+- `cache_read_input_tokens` > 0 means cache was hit (saved cost)
+- `cache_creation_input_tokens` > 0 means new cache entries were created
+- Usage appears on ALL lines sharing the same `message.id`; the LAST line has the most complete data
+
+## Quick Search Script
+
+```powershell
+# Save as: search-session.ps1
+# Usage: .\search-session.ps1 -Path "session.jsonl" -Query "Agent"
+param($Path, $Query)
+
+Select-String -LiteralPath $Path -Pattern $Query | ForEach-Object {
+    $preview = $_.Line.Substring(0, [Math]::Min(300, $_.Line.Length))
+    Write-Host "[$($_.LineNumber)] $preview"
+    Write-Host "---"
+}
+```