# Clavue v8.9.2 — Website / Marketing Update Pack

**Audience**：clavue.com 的内容维护者 / marketing。
**目标**：把 8.9.2 的 user-visible 变化更新到首页、changelog、docs 三个地方。
**约束**：本仓库不含网站源码（见 `docs/website-content-recommendations.md`）。这份文档把所有"可粘"内容打包好。

---

## 1. 首页改动建议

### 1.1 顶部 banner / hero 副标题

替换或新增一行（紧跟在主标题下方）：

> **v8.9.2** — 终结 `/resume` 数据丢失，rewind 现在持久化，新增 `/branches` 查看回滚分支。

CTA 链接到 changelog 锚点。

### 1.2 "新功能" 卡片（如有 features 区）

新增 3 张卡：

**卡 1: 永不丢失的 /resume**
- 标题：Conversation continuity that actually continues
- 副标题：Persistent HEAD pointer in JSONL — `/resume` 现在确定性地回到你上次离开的那个分支，不再靠 timestamp 抽奖。
- 数据点：在用户真实数据上，恢复率从 16.5% → 100%（新会话）。
- 链接：`/docs/resume-and-branches`

**卡 2: 显式分支**
- 标题：Branches for your conversations
- 副标题：每次 rewind/Esc-Esc 自动建命名分支，`/branches list` 看全部，`/branches switch <id>` 切回去。Git for chats.
- 链接：`/docs/branches`

**卡 3: BashTool 真的是 bash**
- 标题：BashTool now uses /bin/bash
- 副标题：macOS 用户写 `status=$(...)` 不再爆 `read-only variable`。zsh 特殊参数冲突彻底告别。
- 链接：`/docs/changelog#8-9-2`

---

## 2. Changelog 页（/changelog 或 /releases）

把以下 markdown 块直接 append 到 changelog 页顶部：

```markdown
## v8.9.2 — 2026-05-08

### Fixed
- **/resume 不再丢失消息**：transcript on disk 是 DAG，过去当链表读，单 leaf 还按 max(timestamp) 抽奖选。新增持久 HEAD pointer entry，`/resume` 现在确定性回到上次离开的分支。老 jsonl 完全兼容（fallback 到旧逻辑）。
- **rewind 现在持久化**：之前 rewind 只改内存，下次 resume 可能拉回 rewind 前的旧分支。现在 rewind 写 branch + head 并 flush 到磁盘后才改内存，决定性保留。
- **macOS BashTool `status=$(...)` 报错**：`(eval):N: read-only variable: status`。BashTool 之前跟随 `$SHELL`，macOS 默认是 zsh，而 zsh `$status` 是只读特殊参数。现在 BashTool 默认用 `/bin/bash`，仅当用户显式 `CLAUDE_CODE_SHELL=/bin/zsh` 时才用 zsh。
- **claude-opus-4-7 模型 1M context 启用**：之前未注册导致 1M context 静默关闭，现已注册到模型表。

### Added
- **`/branches` 命令**：`list / switch <id|name> / rename <id> <new-name>`。每次 rewind 自动建分支，命名取自回滚目标的 user prompt 首 60 字。
- **未注册模型警告**：logo 上对不在内置模型表中的 model 显示 `(unknown — passthrough)`，提醒用户手动模型字符串在 cache/1M context 等特性上会走默认路径。
- **Audit 工具**：`scripts/audit-transcripts.mjs` 和 `scripts/audit-transcripts-v2.mjs`，只读扫 `~/.claude/projects/`，输出 per-session 损失率，作为修复前后对比基线。

### Changed
- `walkChainBeforeParse`（>5MB transcript 的预剪枝）默认翻为 opt-in。设 `CLAUDE_CODE_ENABLE_PRECOMPACT_SKIP=1` 可恢复旧默认。代价：>5MB 会话峰值 RSS 多约 30MB，换"绝不静默丢分支"。
- `loadTranscriptFile` / `loadFullLog` 不再静默 catch；解析错误会被 `logError` + 遥测事件 (`tengu_transcript_load_partial`、`tengu_resume_full_log_failed`) 记录，partial recovery 替代全丢失。
- `/resume` 后会注入一条系统消息显示恢复统计：`Resume loaded N of M messages. K branches available — /branches to inspect.`

### Telemetry
- 新事件：`tengu_resume_leaf_picked` (source: `head` | `fallback`)
- 新事件：`tengu_transcript_load_partial`、`tengu_resume_full_log_failed`
- 已有事件 `tengu_resume_consistency_delta` 现在在 UI 上对用户可见

### Tests
- 新增 11 个测试 (resume-loss-fix + bash-tool-shell-selection + known-model-detection)
- 全套 `npm run check` 816/819 pass，3 skipped，0 fail

升级：

\`\`\`bash
npm install -g clavue@8.9.2
\`\`\`

完整发布说明：[docs/clavue-v8.9.2-release-notes.md](https://github.com/mycode699/clavue/blob/v8.9.2/docs/clavue-v8.9.2-release-notes.md)
```

---

## 3. Docs 页改动建议

### 3.1 新增 `/docs/resume-and-branches` 页

参考骨架（站维护者填充）：

```markdown
# Resume and Branches

Clavue stores every conversation as an append-only JSONL transcript at
\`~/.claude/projects/<project>/<sessionId>.jsonl\`. Each entry chains via
\`parentUuid\` to form a DAG.

## How /resume picks the right place to resume from

Since v8.9.2, Clavue writes a persistent HEAD pointer to the transcript
after every commit:

\`\`\`jsonl
{"type":"head","sessionId":"...","leafUuid":"...","branchId":"main","reason":"append","timestamp":"..."}
\`\`\`

\`/resume\` reads the most recent HEAD entry and walks back from its
\`leafUuid\`. For older transcripts (no HEAD entries) it falls back to the
classic max-timestamp leaf heuristic.

This makes \`/resume\` deterministic in two cases that used to be flaky:

- **After a rewind**: rewind now writes a HEAD with reason='rewind'
  before mutating in-memory state. Next \`/resume\` lands on the survivor
  side, never the abandoned side.
- **After concurrent edits**: when two sessions touch the same project,
  the most recent HEAD wins, instead of "whichever leaf had the larger
  timestamp".

## /branches

\`\`\`
/branches                          # list named branches in this session
/branches switch <id|name>         # write a HEAD entry to that branch
/branches rename <id|name> <new>   # rename a branch (last-wins)
\`\`\`

Branches are created automatically on rewind. Their names are taken from
the first 60 characters of the user prompt at the rewind target.

## When you'll see a system message

If the on-disk DAG round-trip dropped or duplicated messages versus
the in-session checkpoint, \`/resume\` injects a system message:

\`\`\`
Resume loaded 1024 of 1056 messages (-32). 4 branches available — /branches to inspect.
\`\`\`

The hint surfaces previously silent loss; it's not an error.

## Older sessions

Transcripts created before v8.9.2 have no HEAD entries. \`/resume\` falls
back to the previous heuristic for these. The first \`/resume\` after upgrade
writes a HEAD entry, putting the session on the determinic path going forward.
```

### 3.2 BashTool 文档补丁

如果你的 docs 有 BashTool 章节，加一句 macOS-specific note：

```markdown
> **macOS / zsh users**: BashTool defaults to `/bin/bash`, not your shell of
> choice. Bash idioms like `status=$(...)`, `LINENO=`, `SECONDS=` work as
> expected. To force zsh anyway, set `CLAUDE_CODE_SHELL=/bin/zsh`.
```

### 3.3 模型矩阵更新

如果 docs 有 model 表，加一行 `Opus 4.7`：

| Model | Display Name | 1M Context | Notes |
|-------|--------------|-----------|-------|
| `claude-opus-4-7` | Opus 4.7 | ✅ | New in v8.9.2 |
| `claude-opus-4-6` | Opus 4.6 | ✅ | |
| `claude-sonnet-4-6` | Sonnet 4.6 | ✅ | |

---

## 4. SEO / social cards

OG title / description 建议：

- `og:title`：Clavue v8.9.2 — /resume that doesn't forget
- `og:description`：Persistent HEAD pointer for conversation transcripts. Transactional rewind. New /branches command. zsh status= bug fixed. opus-4-7 with 1M context.

Social blurb (tweet-length)：

> Clavue v8.9.2 is out.
>
> /resume now uses a persistent HEAD pointer — never silently drops messages again.
> Rewind is transactional.
> /branches lists every fork.
> macOS BashTool no longer chokes on `status=`.
> Opus 4.7 with 1M context.
>
> npm i -g clavue@8.9.2

---

## 5. 邮件 / Slack 公告（如有 newsletter）

```
Subject: Clavue v8.9.2 — your /resume just got dramatically more reliable

Hi,

We just shipped Clavue v8.9.2 with three things you'll feel immediately:

1. /resume no longer silently drops conversation history. We added a
   persistent HEAD pointer to the transcript so we always pick the right
   place to resume from. On real user data, /resume went from showing
   ~16% of messages to 100% (on new sessions; older sessions remain
   compatible).

2. New /branches command. Every rewind now creates a named branch
   automatically. Run /branches to list, /branches switch <id> to jump.
   Think git, but for conversations.

3. macOS BashTool stopped breaking on `status=$(...)`. We now default
   to /bin/bash for tool commands instead of following $SHELL.

Plus opus-4-7 model registration with 1M-context, and a "(unknown —
passthrough)" warning when you point Clavue at a model id it doesn't
recognize.

Upgrade: npm install -g clavue@8.9.2

Full notes: https://github.com/mycode699/clavue/blob/v8.9.2/docs/clavue-v8.9.2-release-notes.md
```

---

## 6. Checklist for the website maintainer

- [ ] Update homepage banner / hero subtitle to mention v8.9.2 highlight
- [ ] Add 3 feature cards (or update existing ones) for resume/branches/bash
- [ ] Append v8.9.2 block to /changelog page (markdown above is paste-ready)
- [ ] Create new `/docs/resume-and-branches` page (skeleton above)
- [ ] Add macOS-zsh note in BashTool docs
- [ ] Update model matrix to include Opus 4.7
- [ ] Refresh OG card / social preview
- [ ] Send newsletter / post to community channels (template above)
- [ ] Update GitHub release page description (likely auto-synced from tag)

文件改动追踪在仓库 `docs/clavue-v8.9.2-release-notes.md`。
