diff --git a/.github/workflows/brand-check.yml b/.github/workflows/brand-check.yml
new file mode 100644
index 0000000..34132b3
--- /dev/null
+++ b/.github/workflows/brand-check.yml
@@ -0,0 +1,17 @@
+name: Brand presentation
+on:
+ pull_request:
+ paths:
+ - 'README*'
+ - 'docs/**'
+ - 'assets/brand/**'
+ - 'project-brand.json'
+ - '.github/workflows/brand-check.yml'
+ workflow_dispatch:
+permissions:
+ contents: read
+jobs:
+ brand:
+ uses: JackMeds/github-brand/.github/workflows/check.yml@078435fe0dc47d75d46e3faf96bd1d366c10d056
+ with:
+ toolkit-ref: 078435fe0dc47d75d46e3faf96bd1d366c10d056
diff --git a/README.md b/README.md
index 6f2b545..9380f92 100644
--- a/README.md
+++ b/README.md
@@ -1,172 +1,87 @@
-# 哔哩摘要笔记
+
+
+
+ 
+
+
-面向个人 Agent 工作流的 B站收藏与稍后再看摘要工具。
+# BiliDigest / 哔哩摘要笔记
-[English README](README_en.md)
+把“稍后再看”里的视频，整理成能检索、能回看来源的笔记。
-许可证：GPL-3.0-or-later。
+面向个人 Agent 工作流的 B站字幕与摘要导出工具。读取本人已登录账号的稍后再看与收藏夹，优先使用现成字幕和 B站 AI 小助手总结，输出 Markdown、SRT 与 JSON。
-**BiliDigest / 哔哩摘要笔记** 用于读取本人已登录 B站账号可访问的视频，把“稍后再看”和“收藏夹”中的内容整理成 Markdown/SRT/JSON，方便 Hermes Agent、Codex 或其他 Agent 做总结、笔记和知识整理。它优先使用 B站现成字幕和 B站 AI 小助手总结，也保留 ASR/大模型转写作为显式 fallback。
+[快速开始](#快速开始) · [批量处理与登录迁移](docs/usage.md) · [Agent Skill](skills/bili-digest/SKILL.md) · [English](README_en.md)
-## 功能
+## 从视频到笔记
-- 使用统一的用户数据目录 session，并兼容迁移旧版 `.user_session.json`。
-- 列出稍后再看、收藏夹目录、收藏夹内容。
-- 稍后再看列表会缓存到本地，避免 Agent 重启后反复拉取 500+ 条列表。
-- 列表命令会返回远端 `total`，即使用 `--limit 1` 也能快速知道稍后再看/收藏夹总数。
-- 批量任务带持久状态文件，支持断点续跑、跳过已完成和失败项。
-- 优先使用 B站已有字幕，不默认跑 ASR。
-- 可导出 B站 AI 小助手总结。
-- 输出到 `output/bilidigest/<日期>/`。
-- Whisper/Qwen/OpenAI/Gemini 保留为显式 fallback，不再作为主流程。
+
-本项目不是 B站 API 文档库，也不是第三方客户端。定位是本地优先的个人 Agent 辅助工具。
+字幕 Markdown 保留视频来源和时间戳链接，可以从一条笔记回到视频中的对应位置。输出目录为 `output/bilidigest/<日期>/`；字幕导出会同时保存 `.md`、`.srt` 与 `.subtitle.json`。
-## 安装
+## 核心能力
-```bash
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-```
-
-## 登录
-
-```bash
-python -m tools.bilidigest auth status
-python -m tools.bilidigest auth import-browser edge
-python -m tools.bilidigest auth login
-```
-
-默认登录态统一保存到 macOS 用户数据目录：
-
-```text
-~/Library/Application Support/BiliDigest/session.json
-```
+- **先取现成内容。** 优先导出 B站字幕和可用的 AI 小助手总结，不默认启动 ASR。
+- **整理自己的收藏。** 列出稍后再看、收藏夹目录与内容，结果包含远端总数。
+- **保存批量进度。** 本地缓存、快照与状态文件支持续跑，默认跳过已完成及已失败项目。
+- **接入 Agent。** CLI 提供 JSON 输出和非阻塞扫码登录流程，仓库附带 `bili-digest` Skill。
-`auth import-browser edge` 会通过 `yt-dlp` 导入 Microsoft Edge 里的 B站 Cookie，并保存到这份共享 session。扫码登录仍然保留：它会同时输出紧凑终端二维码、可复制登录 URL，并保存图片到 `output/login_qr.png`。旧版 BiliSubNotes session 和项目根目录 `.user_session.json` 只作为兼容 fallback；如果存在且有效，会尽量迁移到共享 session。
+## 快速开始
-如果调用方是 Hermes Agent、Telegram bot 或 TUI，使用非阻塞 JSON 登录流程：
+需要 Python 3.10+。在终端中安装项目依赖：
```bash
-python -m tools.bilidigest auth login --json --no-wait
-python -m tools.bilidigest auth poll --json
-python -m tools.bilidigest auth status --json
+git clone https://github.com/JackMeds/BiliDigest.git
+cd BiliDigest
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
```
-第一条命令会返回 `login_url`、`qr_image`、`qrcode_key` 和 `poll_command`。聊天 Agent 把 URL 或二维码图片发给用户，再轮询直到状态变成 `logged_in`、`expired`、`scanned` 或 `pending`。
-
-查看当前共享 session 位置：
-
-```bash
-python -m tools.bilidigest auth session-path --json
-```
+Windows PowerShell 的虚拟环境激活命令为 `.\.venv\Scripts\Activate.ps1`。依赖中仍包含可选转写工具使用的模型库，安装体积可能较大；基本字幕导出流程不需要另配大模型 API Key。
-## 使用
+### 导出第一条字幕
```bash
-# 稍后再看
-python -m tools.bilidigest list watch-later --limit 15
-python -m tools.bilidigest list watch-later --limit 600 --no-items
-
-# 本人收藏夹目录
-python -m tools.bilidigest list favorites --mid me
+# 用 Bilibili App 扫描终端中的二维码
+python -m tools.bilidigest auth login
-# 指定收藏夹内容
-python -m tools.bilidigest list favorite --media-id 123456 --limit 15
+# 先查看一条稍后再看，取得其中的真实 BV 号
+python -m tools.bilidigest list watch-later --limit 1
-# 导出字幕
+# 将下面的占位 BV 号替换为上一步返回的 bvid
python -m tools.bilidigest transcript BVxxxxxxxxxx --format md
-python -m tools.bilidigest transcript "https://www.bilibili.com/video/BVxxxxxxxxxx" --format srt
-
-# 导出 B站 AI 小助手总结
-python -m tools.bilidigest summary BVxxxxxxxxxx
-
-# 批量处理稍后再看
-python -m tools.bilidigest batch watch-later --limit 15 --with-summary
-python -m tools.bilidigest batch watch-later --limit 600 --fallback-summary --with-summary
```
-旧命令仍保留兼容：`python -m tools.auth --status`、`python -m tools.list --watch-later`、`python -m tools.batch_run`。
+终端会返回生成文件的路径。没有字幕时，可对该视频尝试 `python -m tools.bilidigest summary BVxxxxxxxxxx`，但 AI 小助手总结也不保证可用。
-### 批量处理和续跑
-
-`batch watch-later` 默认使用本地缓存和状态文件：
-
-```text
-output/bilidigest/cache/watch-later.jsonl
-output/bilidigest/cache/watch-later.meta.json
-output/bilidigest/snapshots/watch-later.json
-output/bilidigest/state/watch-later.json
-```
-
-默认列表缓存有效期是 24 小时。每次刷新列表时会更新快照并记录 `added`、`removed`、`changed`，方便日更自动化判断新增和移除。日常自动化或 Hermes Agent 重启后，直接重复运行同一条 `batch` 命令即可续跑；已完成视频会跳过，之前失败的视频也会跳过，避免反复请求同一个视频。
-
-常用参数：
+首次单条导出成功后，再处理最多 15 条：
```bash
-# 强制刷新稍后再看列表
-python -m tools.bilidigest batch watch-later --limit 600 --refresh-list
-
-# 每天自动化：刷新列表，但只处理本次快照新增的视频
-python -m tools.bilidigest batch watch-later --limit 600 --refresh-list --only-new --fallback-summary
-
-# 忽略旧状态，从当前列表重新处理
-python -m tools.bilidigest batch watch-later --limit 600 --no-resume
+python -m tools.bilidigest batch watch-later --limit 15 --fallback-summary
```
-`--retry-failed` 只适合人工排查某个短时间故障后手动使用，不要放进日常自动化或大批量后台任务。无字幕、无 AI 总结的视频失败一次就应保留失败状态。
-
-如果视频没有 B站现成字幕，`--fallback-summary` 会尝试导出 B站 AI 小助手总结，并把该条记录为 `summary_only`。遇到登录失效、HTTP `412`、B站 `-352` 等风控信号时，批处理会保存状态并停止。
+重复同一条批量命令即可续跑。收藏夹命令、浏览器登录态导入、缓存刷新、仅处理新增和失败状态说明见[完整使用参考](docs/usage.md)。
-## Agent Skill
+## 隐私与限制
-Skill 位于：
+- 只处理本人账号原本可访问的内容。现有字幕或 AI 总结不可用时，保留失败状态；Whisper、Qwen、OpenAI、Gemini 转写是需要显式选择的其他路径。
+- Cookie 与登录 Session 保存在本机。缓存、字幕和摘要同样是本地文件；Git 忽略规则不等同于加密，分享输出前请自行检查内容。
+- 请求默认限速，批量默认 15 条。遇到登录失效、HTTP `412` 或 B站 `-352` 等风控响应会保存状态并停止；不要并发启动多个批处理或在日常任务中循环重试失败项。
+- 当前统一 `transcript` 入口处理视频的第一个分 P；字幕选择与结果取决于 B站接口和账号权限。
-```text
-skills/bili-digest/
-```
+## Agent 与开发文档
-仓库采用 Agent Skills 标准目录：每个 Skill 是一个目录，目录内必须有 `SKILL.md`。因此标准安装器可以直接发现它：
-
-```bash
-npx skills add . --list
-npx skills add . --skill bili-digest -g -a codex -y
-```
-
-如果从公开 GitHub 仓库安装，HTTPS 可以直接使用：
+安装 Skill 前先保留本仓库与 Python 环境，并将 `BILIDIGEST_HOME` 设置为 clone 的绝对路径。Skill 安装器只安装指令，不安装 Python 项目本体：
```bash
npx skills add https://github.com/JackMeds/BiliDigest --skill bili-digest -g -a codex -y
```
-SSH 形式也可以，但前提是 `ssh -T git@github.com` 能通过。本机当前 GitHub SSH 未打通，所以更建议用 HTTPS 或本地路径。
-
-`npx skills` 安装的是 Skill 指令，不会自动安装 Python 项目本体。仍然需要保留本仓库 clone 和 `.venv` 依赖。Skill 内置了 `skills/bili-digest/scripts/bilidigest` 启动器，会通过 `BILIDIGEST_HOME` 或默认本机路径找到真正的 CLI。
-
-本机开发时也可以继续用软链接安装，优点是改 Skill 文档后立即生效：
-
-```bash
-python install.py --target ~/.agents/skills
-```
-
-日常更新可以这样做：
-
-```bash
-git pull
-npx skills add . --skill bili-digest -g -a codex -y
-```
-
-## 安全默认值
+[中文使用参考](docs/usage.md) · [English reference](docs/usage.en.md) · [CLI 入口](tools/bilisub.py) · [现有测试](tests/)
-- 批量命令默认最多处理 `15` 条。
-- 请求默认故意很慢：每次 API 调用大约等待 `8-12` 秒。可以用 `BILIDIGEST_DELAY_SECONDS` 和 `BILIDIGEST_DELAY_JITTER_SECONDS` 调整。
-- 大批量处理建议使用默认慢速或稍微调到 `BILIDIGEST_DELAY_SECONDS=6 BILIDIGEST_DELAY_JITTER_SECONDS=2`，不要并发启动多个批处理。
-- 旧的视频/音频下载入口也会使用单 fragment 和慢速 `yt-dlp` sleep 参数。可以用 `BILIDIGEST_YTDLP_SLEEP_SECONDS` 和 `BILIDIGEST_YTDLP_MAX_SLEEP_SECONDS` 调整。
-- 遇到 HTTP `412` 或 B站 `-352` 等风控信号会停止批处理。
-- Cookie、Session、`.env` 和输出目录均被 Git 忽略。
-- 只处理本人账号本来就能访问的内容。
+贡献时可提交脱敏的错误信息、最小复现与预期输出。请不要附带 Cookie、Session、私人收藏列表或完整导出包。
-## 鸣谢
+## 许可与鸣谢
-BiliDigest 的功能边界和安全策略参考了开源 B站工具的实践，特别是采用 GPL-3.0-or-later 协议的 [BiliTools](https://github.com/btjawa/BiliTools)。本项目不迁入 BiliTools 的 Tauri UI，只保留轻量 Python CLI，供本地 Agent 使用。归属和参考说明见 [NOTICE](NOTICE)。
+本项目采用 [GPL-3.0-or-later](LICENSE)。功能边界与安全策略参考了 [BiliTools](https://github.com/btjawa/BiliTools) 的开源实践，未迁入其 Tauri UI。归属与参考说明见 [NOTICE](NOTICE)。
diff --git a/README_en.md b/README_en.md
index 5f9b6e7..d10110d 100644
--- a/README_en.md
+++ b/README_en.md
@@ -1,172 +1,87 @@
+
+
+
+
+
+
+
# BiliDigest
-Bilibili digest notes for agents.
+Turn Watch Later videos into searchable notes with a path back to the source.
+
+BiliDigest exports subtitles and summaries from your own logged-in Bilibili account. It reads Watch Later and Favorites, prefers existing subtitles and Bilibili AI Assistant summaries, and writes Markdown, SRT and JSON for personal agent workflows.
+
+[Quick start](#quick-start) · [Batch and login reference](docs/usage.en.md) · [Agent Skill](skills/bili-digest/SKILL.md) · [中文](README.md)
-[中文说明](README.md)
+## From video to notes
-License: GPL-3.0-or-later.
+
-**BiliDigest** helps agents summarize and organize videos from your own logged-in Bilibili Watch Later and Favorites lists. It prefers existing Bilibili subtitles and AI summaries when available, and keeps ASR/model-based transcription as an explicit fallback path.
+Markdown subtitles retain the source video and timestamp links. Exports live under `output/bilidigest//`; a subtitle export writes `.md`, `.srt` and `.subtitle.json` files together.
-## What It Does
+## What it does
-- Reads your Bilibili login session from a shared user data file, with legacy `.user_session.json` migration.
-- Lists Watch Later and Favorite folders/items.
-- Caches large Watch Later lists locally so agents do not refetch hundreds of items on every restart.
-- List commands return the remote `total`, so `--limit 1` can quickly report the Watch Later or Favorite size.
-- Writes a persistent batch state file for resume and skip-completed/failed workflows.
-- Exports existing Bilibili subtitles first, without running ASR by default.
-- Exports Bilibili AI Assistant summaries when available.
-- Writes Markdown, SRT, and JSON under `output/bilidigest//`.
-- Keeps Whisper/Qwen/OpenAI/Gemini transcription tools as explicit fallbacks.
+- **Use existing content first.** Export available Bilibili subtitles and AI summaries without starting ASR by default.
+- **Organize your own lists.** List Watch Later, Favorite folders and their contents, including remote totals.
+- **Resume batches.** Local caches, snapshots and state files retain progress; completed and failed items are skipped by default.
+- **Work with agents.** JSON output, non-blocking QR login and the included `bili-digest` Skill support personal workflows.
-This is not a public API documentation project and not a third-party Bilibili client. It is a local-first tool for personal notes and agent workflows.
+## Quick start
-## Install
+Use Python 3.10+:
```bash
+git clone https://github.com/JackMeds/BiliDigest.git
+cd BiliDigest
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
-## Login
-
-```bash
-python -m tools.bilidigest auth status
-python -m tools.bilidigest auth import-browser edge
-python -m tools.bilidigest auth login
-```
-
-The preferred login cache is the macOS user data file:
-
-```text
-~/Library/Application Support/BiliDigest/session.json
-```
-
-`auth import-browser edge` imports your existing Microsoft Edge Bilibili cookies through `yt-dlp` and stores them in that shared session file. The QR login command remains available; it prints a compact terminal QR, a copyable login URL, and writes `output/login_qr.png`. Old BiliSubNotes and project-local `.user_session.json` files are only used as legacy fallbacks and are migrated into the shared session file when possible.
-
-For chat agents such as Hermes Agent, Telegram bots, or a TUI, use the non-blocking JSON login flow:
-
-```bash
-python -m tools.bilidigest auth login --json --no-wait
-python -m tools.bilidigest auth poll --json
-python -m tools.bilidigest auth status --json
-```
-
-The first command returns `login_url`, `qr_image`, `qrcode_key`, and `poll_command`. Send the URL or QR image to the user, then poll until the response status becomes `logged_in`, `expired`, `scanned`, or `pending`.
-
-To see the shared session location:
-
-```bash
-python -m tools.bilidigest auth session-path --json
-```
+On Windows PowerShell, activate with `.\.venv\Scripts\Activate.ps1`. Dependencies still include model libraries used by optional transcription tools, so installation can be large. The basic subtitle workflow does not need an LLM API key.
-## Usage
+### Export your first subtitle
```bash
-# Watch Later
-python -m tools.bilidigest list watch-later --limit 15
-python -m tools.bilidigest list watch-later --limit 600 --no-items
-
-# Favorite folders for your own account
-python -m tools.bilidigest list favorites --mid me
+# Scan the terminal QR code with the Bilibili app
+python -m tools.bilidigest auth login
-# Items in a favorite folder
-python -m tools.bilidigest list favorite --media-id 123456 --limit 15
+# Get one Watch Later item and its real BV identifier
+python -m tools.bilidigest list watch-later --limit 1
-# Export subtitles
+# Replace this placeholder with the returned bvid
python -m tools.bilidigest transcript BVxxxxxxxxxx --format md
-python -m tools.bilidigest transcript "https://www.bilibili.com/video/BVxxxxxxxxxx" --format srt
-
-# Export Bilibili AI Assistant summary
-python -m tools.bilidigest summary BVxxxxxxxxxx
-
-# Batch Watch Later
-python -m tools.bilidigest batch watch-later --limit 15 --with-summary
-python -m tools.bilidigest batch watch-later --limit 600 --fallback-summary --with-summary
```
-Legacy commands such as `python -m tools.auth --status`, `python -m tools.list --watch-later`, and `python -m tools.batch_run` still work as compatibility wrappers.
+The command returns file paths. If subtitles are unavailable, try `python -m tools.bilidigest summary BVxxxxxxxxxx` for that video; AI summaries are not guaranteed to exist either.
-### Batch Resume
-
-`batch watch-later` uses local cache and state files by default:
-
-```text
-output/bilidigest/cache/watch-later.jsonl
-output/bilidigest/cache/watch-later.meta.json
-output/bilidigest/snapshots/watch-later.json
-output/bilidigest/state/watch-later.json
-```
-
-The default list cache TTL is 24 hours. Each refreshed list updates a snapshot and records `added`, `removed`, and `changed`, which lets daily automation detect new and removed items. For daily automation or after an agent restart, rerun the same `batch` command to resume. Completed videos and previously failed videos are skipped.
-
-Common options:
+After one successful export, try a small batch:
```bash
-# Force-refresh the Watch Later list
-python -m tools.bilidigest batch watch-later --limit 600 --refresh-list
-
-# Daily automation: refresh the list but process only items newly added in this snapshot
-python -m tools.bilidigest batch watch-later --limit 600 --refresh-list --only-new --fallback-summary
-
-# Ignore the old state and process the current list again
-python -m tools.bilidigest batch watch-later --limit 600 --no-resume
+python -m tools.bilidigest batch watch-later --limit 15 --fallback-summary
```
-`--retry-failed` is only for manual investigation after a short-lived outage. Do not put it in daily automation or large background batches. Videos without subtitles or AI summaries should remain failed after one attempt.
-
-If a video has no existing Bilibili subtitle, `--fallback-summary` attempts to export the Bilibili AI Assistant summary and records the item as `summary_only`. Login-expired and risk-control responses such as HTTP `412` or Bilibili `-352` save state and stop the batch.
+Rerun the same batch command to resume. See the [full reference](docs/usage.en.md) for Favorites, browser-cookie import, cache refresh, new-items-only runs and failed-item handling.
-## Agent Skill
+## Privacy and limitations
-The skill lives at:
+- Only process content your account can already access. Missing subtitles or summaries remain failed; Whisper, Qwen, OpenAI and Gemini transcription are separate, explicitly selected paths.
+- Cookies, sessions, caches and exports are local files. Git ignore rules are not encryption; review exports before sharing them.
+- Requests are throttled and batches default to 15 items. Login expiration, HTTP `412` and Bilibili `-352` save progress and stop the batch. Avoid concurrent batches and automatic retry loops for failed videos.
+- The unified `transcript` command currently handles the first part of a multipart video. Subtitle availability depends on Bilibili and your account permissions.
-```text
-skills/bili-digest/
-```
+## Agents and development
-The repository follows the Agent Skills layout: each skill is a directory with a required `SKILL.md` file. This means standard installers can discover it:
-
-```bash
-npx skills add . --list
-npx skills add . --skill bili-digest -g -a codex -y
-```
-
-For the public GitHub repository, HTTPS works directly:
+Keep the repository and Python environment installed, and set `BILIDIGEST_HOME` to your clone's absolute path. The skill installer installs instructions, not the Python application:
```bash
npx skills add https://github.com/JackMeds/BiliDigest --skill bili-digest -g -a codex -y
```
-SSH install also works after `ssh -T git@github.com` succeeds. On this machine SSH auth is not currently configured for GitHub, so prefer HTTPS or the local path.
-
-`npx skills` installs the skill instructions, not the Python project itself. Keep this repository cloned and dependencies installed. The skill includes `skills/bili-digest/scripts/bilidigest`, a small launcher that finds the clone via `BILIDIGEST_HOME` or the default local path.
-
-For live development on this machine, a symlink install is still useful because edits reflect immediately:
-
-```bash
-python install.py --target ~/.agents/skills
-```
-
-For routine updates after a pull:
-
-```bash
-git pull
-npx skills add . --skill bili-digest -g -a codex -y
-```
-
-## Safety Defaults
+[Usage reference](docs/usage.en.md) · [中文参考](docs/usage.md) · [CLI entry point](tools/bilisub.py) · [Existing tests](tests/)
-- Batch commands default to `15` items.
-- Requests are deliberately slow by default: each API call waits about `8-12` seconds. You can tune this with `BILIDIGEST_DELAY_SECONDS` and `BILIDIGEST_DELAY_JITTER_SECONDS`.
-- For large batches, keep the default slow mode or use a modest setting such as `BILIDIGEST_DELAY_SECONDS=6 BILIDIGEST_DELAY_JITTER_SECONDS=2`; do not run multiple batch jobs concurrently.
-- The legacy video/audio downloader also uses one fragment at a time and passes slow `yt-dlp` sleep settings. Tune it with `BILIDIGEST_YTDLP_SLEEP_SECONDS` and `BILIDIGEST_YTDLP_MAX_SLEEP_SECONDS`.
-- Risk-control responses such as HTTP `412` or Bilibili `-352` stop batch processing.
-- Cookies, sessions, `.env`, and output files are ignored by Git.
-- The tool only processes content your logged-in account can already access.
+For contributions, include sanitized errors, a minimal reproduction and expected output. Do not attach cookies, sessions, private lists or full personal exports.
-## Acknowledgements
+## License and acknowledgements
-BiliDigest was shaped by practical behavior observed in open-source Bilibili tooling, especially [BiliTools](https://github.com/btjawa/BiliTools), which is licensed under GPL-3.0-or-later. This repository does not import the BiliTools Tauri UI; it keeps a small Python CLI surface for local agent use. See [NOTICE](NOTICE) for attribution notes.
+Licensed under [GPL-3.0-or-later](LICENSE). The feature boundaries and safety defaults draw on open-source practices from [BiliTools](https://github.com/btjawa/BiliTools); its Tauri UI is not imported. See [NOTICE](NOTICE) for attribution.
diff --git a/README_zh-CN.md b/README_zh-CN.md
index 6e3f7f2..95dc325 100644
--- a/README_zh-CN.md
+++ b/README_zh-CN.md
@@ -1,170 +1,5 @@
-# 哔哩摘要笔记
+# BiliDigest / 哔哩摘要笔记
-面向个人 Agent 工作流的 B站收藏与稍后再看摘要工具。
+中文主文已统一到 [README.md](README.md)，这个文件保留为旧链接入口。
-许可证：GPL-3.0-or-later。
-
-**BiliDigest / 哔哩摘要笔记** 用于读取本人已登录 B站账号可访问的视频，把“稍后再看”和“收藏夹”中的内容整理成 Markdown/SRT/JSON，方便 Hermes Agent、Codex 或其他 Agent 做总结、笔记和知识整理。它优先使用 B站现成字幕和 B站 AI 小助手总结，也保留 ASR/大模型转写作为显式 fallback。
-
-## 功能
-
-- 使用统一的用户数据目录 session，并兼容迁移旧版 `.user_session.json`。
-- 列出稍后再看、收藏夹目录、收藏夹内容。
-- 稍后再看列表会缓存到本地，避免 Agent 重启后反复拉取 500+ 条列表。
-- 列表命令会返回远端 `total`，即使用 `--limit 1` 也能快速知道稍后再看/收藏夹总数。
-- 批量任务带持久状态文件，支持断点续跑、跳过已完成和失败项。
-- 优先使用 B站已有字幕，不默认跑 ASR。
-- 可导出 B站 AI 小助手总结。
-- 输出到 `output/bilidigest/<日期>/`。
-- Whisper/Qwen/OpenAI/Gemini 保留为显式 fallback，不再作为主流程。
-
-本项目不是 B站 API 文档库，也不是第三方客户端。定位是本地优先的个人 Agent 辅助工具。
-
-## 安装
-
-```bash
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-```
-
-## 登录
-
-```bash
-python -m tools.bilidigest auth status
-python -m tools.bilidigest auth import-browser edge
-python -m tools.bilidigest auth login
-```
-
-默认登录态统一保存到 macOS 用户数据目录：
-
-```text
-~/Library/Application Support/BiliDigest/session.json
-```
-
-`auth import-browser edge` 会通过 `yt-dlp` 导入 Microsoft Edge 里的 B站 Cookie，并保存到这份共享 session。扫码登录仍然保留：它会同时输出紧凑终端二维码、可复制登录 URL，并保存图片到 `output/login_qr.png`。旧版 BiliSubNotes session 和项目根目录 `.user_session.json` 只作为兼容 fallback；如果存在且有效，会尽量迁移到共享 session。
-
-如果调用方是 Hermes Agent、Telegram bot 或 TUI，使用非阻塞 JSON 登录流程：
-
-```bash
-python -m tools.bilidigest auth login --json --no-wait
-python -m tools.bilidigest auth poll --json
-python -m tools.bilidigest auth status --json
-```
-
-第一条命令会返回 `login_url`、`qr_image`、`qrcode_key` 和 `poll_command`。聊天 Agent 把 URL 或二维码图片发给用户，再轮询直到状态变成 `logged_in`、`expired`、`scanned` 或 `pending`。
-
-查看当前共享 session 位置：
-
-```bash
-python -m tools.bilidigest auth session-path --json
-```
-
-## 使用
-
-```bash
-# 稍后再看
-python -m tools.bilidigest list watch-later --limit 15
-python -m tools.bilidigest list watch-later --limit 600 --no-items
-
-# 本人收藏夹目录
-python -m tools.bilidigest list favorites --mid me
-
-# 指定收藏夹内容
-python -m tools.bilidigest list favorite --media-id 123456 --limit 15
-
-# 导出字幕
-python -m tools.bilidigest transcript BVxxxxxxxxxx --format md
-python -m tools.bilidigest transcript "https://www.bilibili.com/video/BVxxxxxxxxxx" --format srt
-
-# 导出 B站 AI 小助手总结
-python -m tools.bilidigest summary BVxxxxxxxxxx
-
-# 批量处理稍后再看
-python -m tools.bilidigest batch watch-later --limit 15 --with-summary
-python -m tools.bilidigest batch watch-later --limit 600 --fallback-summary --with-summary
-```
-
-旧命令仍保留兼容：`python -m tools.auth --status`、`python -m tools.list --watch-later`、`python -m tools.batch_run`。
-
-### 批量处理和续跑
-
-`batch watch-later` 默认使用本地缓存和状态文件：
-
-```text
-output/bilidigest/cache/watch-later.jsonl
-output/bilidigest/cache/watch-later.meta.json
-output/bilidigest/snapshots/watch-later.json
-output/bilidigest/state/watch-later.json
-```
-
-默认列表缓存有效期是 24 小时。每次刷新列表时会更新快照并记录 `added`、`removed`、`changed`，方便日更自动化判断新增和移除。日常自动化或 Hermes Agent 重启后，直接重复运行同一条 `batch` 命令即可续跑；已完成视频会跳过，之前失败的视频也会跳过，避免反复请求同一个视频。
-
-常用参数：
-
-```bash
-# 强制刷新稍后再看列表
-python -m tools.bilidigest batch watch-later --limit 600 --refresh-list
-
-# 每天自动化：刷新列表，但只处理本次快照新增的视频
-python -m tools.bilidigest batch watch-later --limit 600 --refresh-list --only-new --fallback-summary
-
-# 忽略旧状态，从当前列表重新处理
-python -m tools.bilidigest batch watch-later --limit 600 --no-resume
-```
-
-`--retry-failed` 只适合人工排查某个短时间故障后手动使用，不要放进日常自动化或大批量后台任务。无字幕、无 AI 总结的视频失败一次就应保留失败状态。
-
-如果视频没有 B站现成字幕，`--fallback-summary` 会尝试导出 B站 AI 小助手总结，并把该条记录为 `summary_only`。遇到登录失效、HTTP `412`、B站 `-352` 等风控信号时，批处理会保存状态并停止。
-
-## Agent Skill
-
-Skill 位于：
-
-```text
-skills/bili-digest/
-```
-
-仓库采用 Agent Skills 标准目录：每个 Skill 是一个目录，目录内必须有 `SKILL.md`。因此标准安装器可以直接发现它：
-
-```bash
-npx skills add . --list
-npx skills add . --skill bili-digest -g -a codex -y
-```
-
-如果从公开 GitHub 仓库安装，HTTPS 可以直接使用：
-
-```bash
-npx skills add https://github.com/JackMeds/BiliDigest --skill bili-digest -g -a codex -y
-```
-
-SSH 形式也可以，但前提是 `ssh -T git@github.com` 能通过。本机当前 GitHub SSH 未打通，所以更建议用 HTTPS 或本地路径。
-
-`npx skills` 安装的是 Skill 指令，不会自动安装 Python 项目本体。仍然需要保留本仓库 clone 和 `.venv` 依赖。Skill 内置了 `skills/bili-digest/scripts/bilidigest` 启动器，会通过 `BILIDIGEST_HOME` 或默认本机路径找到真正的 CLI。
-
-本机开发时也可以继续用软链接安装，优点是改 Skill 文档后立即生效：
-
-```bash
-python install.py --target ~/.agents/skills
-```
-
-日常更新可以这样做：
-
-```bash
-git pull
-npx skills add . --skill bili-digest -g -a codex -y
-```
-
-## 安全默认值
-
-- 批量命令默认最多处理 `15` 条。
-- 请求默认故意很慢：每次 API 调用大约等待 `8-12` 秒。可以用 `BILIDIGEST_DELAY_SECONDS` 和 `BILIDIGEST_DELAY_JITTER_SECONDS` 调整。
-- 大批量处理建议使用默认慢速或稍微调到 `BILIDIGEST_DELAY_SECONDS=6 BILIDIGEST_DELAY_JITTER_SECONDS=2`，不要并发启动多个批处理。
-- 旧的视频/音频下载入口也会使用单 fragment 和慢速 `yt-dlp` sleep 参数。可以用 `BILIDIGEST_YTDLP_SLEEP_SECONDS` 和 `BILIDIGEST_YTDLP_MAX_SLEEP_SECONDS` 调整。
-- 遇到 HTTP `412` 或 B站 `-352` 等风控信号会停止批处理。
-- Cookie、Session、`.env` 和输出目录均被 Git 忽略。
-- 只处理本人账号本来就能访问的内容。
-
-## 鸣谢
-
-BiliDigest 的功能边界和安全策略参考了开源 B站工具的实践，特别是采用 GPL-3.0-or-later 协议的 [BiliTools](https://github.com/btjawa/BiliTools)。本项目不迁入 BiliTools 的 Tauri UI，只保留轻量 Python CLI，供本地 Agent 使用。归属和参考说明见 [NOTICE](NOTICE)。
+[快速开始](README.md#快速开始) · [完整使用与迁移参考](docs/usage.md) · [English](README_en.md)
diff --git a/assets/brand/FONT-LICENSES.txt b/assets/brand/FONT-LICENSES.txt
new file mode 100644
index 0000000..1f5a592
--- /dev/null
+++ b/assets/brand/FONT-LICENSES.txt
@@ -0,0 +1,294 @@
+Brand lettering is outlined from the following fonts. Their licenses are preserved here.
+
+InstrumentSans-OFL.txt
+
+Copyright 2022 The Instrument Sans Project Authors (https://github.com/Instrument/instrument-sans)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+
+IBMPlexMono-OFL.txt
+
+Copyright © 2017 IBM Corp. with Reserved Font Name "Plex"
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+
+SourceHanSans-LICENSE.txt
+
+Copyright 2014-2025 Adobe (http://www.adobe.com/), with Reserved Font
+Name 'Source'. Source is a trademark of Adobe in the United States
+and/or other countries.
+
+This Font Software is licensed under the SIL Open Font License,
+Version 1.1.
+
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font
+creation efforts of academic and linguistic communities, and to
+provide a free and open framework in which fonts may be shared and
+improved in partnership with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply to
+any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software
+components as distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to,
+deleting, or substituting -- in part or in whole -- any of the
+components of the Original Version, by changing formats or by porting
+the Font Software to a new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed,
+modify, redistribute, and sell modified and unmodified copies of the
+Font Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components, in
+Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the
+corresponding Copyright Holder. This restriction only applies to the
+primary font name as presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created using
+the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/assets/brand/build.json b/assets/brand/build.json
new file mode 100644
index 0000000..7d50c5f
--- /dev/null
+++ b/assets/brand/build.json
@@ -0,0 +1,10 @@
+{
+ "toolkit": "JackMeds/github-brand",
+ "version": "1.0.0",
+ "manifestSha256": "fd6c7aeac816eca8317ccd821b00f761570f4d076eaa0c46a24c596242ed2eb6",
+ "fonts": {
+ "InstrumentSans.ttf": "b24f1812584816958afcf22e22d08e44318c5e51651e25d2438efdde389b33b1",
+ "IBMPlexMono-Regular.ttf": "6a3412f058c7d8dfd9170c41e85ade48e5156ecb89356110ca57a0a27734af46",
+ "SourceHanSansSC-Regular.otf": "f1d8611151880c6c336aabeac4640ef434fa13cbfbf1ffe82d0a71b2a5637256"
+ }
+}
diff --git a/assets/brand/hero-dark.svg b/assets/brand/hero-dark.svg
new file mode 100644
index 0000000..ff66a5e
--- /dev/null
+++ b/assets/brand/hero-dark.svg
@@ -0,0 +1 @@
+
diff --git a/assets/brand/hero-light.svg b/assets/brand/hero-light.svg
new file mode 100644
index 0000000..85e02bf
--- /dev/null
+++ b/assets/brand/hero-light.svg
@@ -0,0 +1 @@
+
diff --git a/assets/brand/product-proof.png b/assets/brand/product-proof.png
new file mode 100644
index 0000000..31a47c1
Binary files /dev/null and b/assets/brand/product-proof.png differ
diff --git a/assets/brand/social-preview.png b/assets/brand/social-preview.png
new file mode 100644
index 0000000..7be1567
Binary files /dev/null and b/assets/brand/social-preview.png differ
diff --git a/assets/brand/social-preview.svg b/assets/brand/social-preview.svg
new file mode 100644
index 0000000..87eaf5d
--- /dev/null
+++ b/assets/brand/social-preview.svg
@@ -0,0 +1 @@
+
diff --git a/docs/brand-proof.md b/docs/brand-proof.md
new file mode 100644
index 0000000..6102643
--- /dev/null
+++ b/docs/brand-proof.md
@@ -0,0 +1,86 @@
+# BiliDigest 离线证据图
+
+[返回 README](../README.md) · [查看原图](../assets/brand/product-proof.png)
+
+这张图是实际命令输出的排版截图，不是 BiliDigest 应用界面，也不是已登录账号的字幕导出结果。输入为三条明确标记的虚构字幕；右侧是仓库中 `body_to_markdown()` 的原始返回文本。
+
+## 来源与运行记录
+
+- 源码提交：`3bfa0a9d16182cc32fb919d18f69d2bec1f36f5e`。
+- 采集时间：2026-09-05 07:38（Asia/Shanghai）。
+- Python：`3.14.6`；复用本机已有 BiliDigest 虚拟环境，仅作解释器与依赖来源。
+- 工作目录与导入源码：本次品牌工作区中的全新 BiliDigest 检出副本；已检查 `tools.bili_subtitle.__file__` 指向该副本。
+- `python -m tools.bilidigest --help` 和 `body_to_markdown()` 转换均退出为 `0`，没有标准错误输出。
+- 捕获尺寸：`1600 × 1120`，使用独立的 Playwright `bilidigest-proof` 会话，从本机回环地址页面截图；截图后进行了图片目视检查。
+
+本次没有实例化 `BiliClient`、读取账号 Session、登录、请求 B站 API、下载字幕或调用模型。占位 ID `EXAMPLE_OFFLINE` 是故意无效的示例值；生成的链接没有打开。图中关于 CLI 功能的文字来自帮助输出，不代表相关网络功能已在此次采集中测试。
+
+## 实际帮助命令
+
+```bash
+python -m tools.bilidigest --help
+```
+
+```text
+usage: bilidigest [-h] {auth,list,transcript,summary,batch} ...
+
+BiliDigest 哔哩摘要笔记 CLI
+
+positional arguments:
+ {auth,list,transcript,summary,batch}
+ auth B站登录状态和扫码登录
+ list 列出稍后再看或收藏夹
+ transcript 导出 B站现成字幕
+ summary 导出 B站 AI 小助手总结
+ batch 批量处理稍后再看
+
+options:
+ -h, --help show this help message and exit
+```
+
+## 示例字幕与真实转换
+
+下面的函数调用由采集脚本通过 `python -c` 实际执行。`print(..., end="")` 保留函数返回内容，不额外增加换行。
+
+```python
+from tools.bili_subtitle import body_to_markdown
+
+video = {"title": "示例字幕：把想法写成笔记", "bvid": "EXAMPLE_OFFLINE"}
+subtitle = {"lan": "zh-CN", "lan_doc": "中文（示例字幕）"}
+body = [
+ {"from": 0, "to": 6, "content": "先记录一个值得保留的想法。"},
+ {"from": 12, "to": 18, "content": "为它补上来源，方便回到原处。"},
+ {"from": 28, "to": 35, "content": "用时间戳，把回看变成下一步。"},
+]
+print(body_to_markdown(video, subtitle, body), end="")
+```
+
+实际输出：
+
+```markdown
+# 示例字幕：把想法写成笔记
+
+- BV: EXAMPLE_OFFLINE
+- URL: https://www.bilibili.com/video/EXAMPLE_OFFLINE
+- Subtitle: 中文（示例字幕）
+
+## 字幕
+
+- [00:00](https://www.bilibili.com/video/EXAMPLE_OFFLINE?t=0) 先记录一个值得保留的想法。
+- [00:12](https://www.bilibili.com/video/EXAMPLE_OFFLINE?t=12) 为它补上来源，方便回到原处。
+- [00:28](https://www.bilibili.com/video/EXAMPLE_OFFLINE?t=28) 用时间戳，把回看变成下一步。
+```
+
+## 复现素材
+
+品牌工作区的 `github-brand/scripts/proof-bilidigest.mjs` 负责运行命令、核对源码导入路径，并将原始 stdout 直接转义到 HTML 中。它不改变 BiliDigest 运行时代码或依赖。
+
+从同时包含品牌仓库与项目检出副本的工作区运行，将最后一个参数换成已有 Python 环境的真实路径：
+
+```bash
+node github-brand/scripts/proof-bilidigest.mjs \
+ github-brand-workspace/BiliDigest \
+ /path/to/venv/bin/python
+```
+
+记录保存在工作区 `output/playwright/bilidigest-proof/`：`capture.json` 包含命令、解释器、源码路径与退出码；`cli-help.txt`、`fixture.json` 和 `example.md` 保存原始数据；`index.html` 仅承担展示排版。页面不加载外部资源。用本地静态服务器打开该目录，再以相同尺寸截图，即可重新生成证据图。
diff --git a/docs/usage.en.md b/docs/usage.en.md
new file mode 100644
index 0000000..dd2692b
--- /dev/null
+++ b/docs/usage.en.md
@@ -0,0 +1,174 @@
+# BiliDigest usage and migration reference
+
+Bilibili digest notes for agents.
+
+[Back to the project](../README_en.md) · [中文参考](usage.md)
+
+This reference retains detailed authentication, migration, batch and agent workflows. Run commands from the repository root.
+
+License: GPL-3.0-or-later.
+
+**BiliDigest** helps agents summarize and organize videos from your own logged-in Bilibili Watch Later and Favorites lists. It prefers existing Bilibili subtitles and AI summaries when available, and keeps ASR/model-based transcription as an explicit fallback path.
+
+## What It Does
+
+- Reads your Bilibili login session from a shared user data file, with legacy `.user_session.json` migration.
+- Lists Watch Later and Favorite folders/items.
+- Caches large Watch Later lists locally so agents do not refetch hundreds of items on every restart.
+- List commands return the remote `total`, so `--limit 1` can quickly report the Watch Later or Favorite size.
+- Writes a persistent batch state file for resume and skip-completed/failed workflows.
+- Exports existing Bilibili subtitles first, without running ASR by default.
+- Exports Bilibili AI Assistant summaries when available.
+- Writes Markdown, SRT, and JSON under `output/bilidigest//`.
+- Keeps Whisper/Qwen/OpenAI/Gemini transcription tools as explicit fallbacks.
+
+This is not a public API documentation project and not a third-party Bilibili client. It is a local-first tool for personal notes and agent workflows.
+
+## Install
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Login
+
+```bash
+python -m tools.bilidigest auth status
+python -m tools.bilidigest auth import-browser edge
+python -m tools.bilidigest auth login
+```
+
+The preferred login cache is the macOS user data file:
+
+```text
+~/Library/Application Support/BiliDigest/session.json
+```
+
+`auth import-browser edge` imports your existing Microsoft Edge Bilibili cookies through `yt-dlp` and stores them in that shared session file. The QR login command remains available; it prints a compact terminal QR, a copyable login URL, and writes `output/login_qr.png`. Old BiliSubNotes and project-local `.user_session.json` files are only used as legacy fallbacks and are migrated into the shared session file when possible.
+
+For chat agents such as Hermes Agent, Telegram bots, or a TUI, use the non-blocking JSON login flow:
+
+```bash
+python -m tools.bilidigest auth login --json --no-wait
+python -m tools.bilidigest auth poll --json
+python -m tools.bilidigest auth status --json
+```
+
+The first command returns `login_url`, `qr_image`, `qrcode_key`, and `poll_command`. Send the URL or QR image to the user, then poll until the response status becomes `logged_in`, `expired`, `scanned`, or `pending`.
+
+To see the shared session location:
+
+```bash
+python -m tools.bilidigest auth session-path --json
+```
+
+## Usage
+
+```bash
+# Watch Later
+python -m tools.bilidigest list watch-later --limit 15
+python -m tools.bilidigest list watch-later --limit 600 --no-items
+
+# Favorite folders for your own account
+python -m tools.bilidigest list favorites --mid me
+
+# Items in a favorite folder
+python -m tools.bilidigest list favorite --media-id 123456 --limit 15
+
+# Export subtitles
+python -m tools.bilidigest transcript BVxxxxxxxxxx --format md
+python -m tools.bilidigest transcript "https://www.bilibili.com/video/BVxxxxxxxxxx" --format srt
+
+# Export Bilibili AI Assistant summary
+python -m tools.bilidigest summary BVxxxxxxxxxx
+
+# Batch Watch Later
+python -m tools.bilidigest batch watch-later --limit 15 --with-summary
+python -m tools.bilidigest batch watch-later --limit 600 --fallback-summary --with-summary
+```
+
+Legacy commands such as `python -m tools.auth --status`, `python -m tools.list --watch-later`, and `python -m tools.batch_run` still work as compatibility wrappers.
+
+### Batch Resume
+
+`batch watch-later` uses local cache and state files by default:
+
+```text
+output/bilidigest/cache/watch-later.jsonl
+output/bilidigest/cache/watch-later.meta.json
+output/bilidigest/snapshots/watch-later.json
+output/bilidigest/state/watch-later.json
+```
+
+The default list cache TTL is 24 hours. Each refreshed list updates a snapshot and records `added`, `removed`, and `changed`, which lets daily automation detect new and removed items. For daily automation or after an agent restart, rerun the same `batch` command to resume. Completed videos and previously failed videos are skipped.
+
+Common options:
+
+```bash
+# Force-refresh the Watch Later list
+python -m tools.bilidigest batch watch-later --limit 600 --refresh-list
+
+# Daily automation: refresh the list but process only items newly added in this snapshot
+python -m tools.bilidigest batch watch-later --limit 600 --refresh-list --only-new --fallback-summary
+
+# Ignore the old state and process the current list again
+python -m tools.bilidigest batch watch-later --limit 600 --no-resume
+```
+
+`--retry-failed` is only for manual investigation after a short-lived outage. Do not put it in daily automation or large background batches. Videos without subtitles or AI summaries should remain failed after one attempt.
+
+If a video has no existing Bilibili subtitle, `--fallback-summary` attempts to export the Bilibili AI Assistant summary and records the item as `summary_only`. Login-expired and risk-control responses such as HTTP `412` or Bilibili `-352` save state and stop the batch.
+
+## Agent Skill
+
+The skill lives at:
+
+```text
+skills/bili-digest/
+```
+
+The repository follows the Agent Skills layout: each skill is a directory with a required `SKILL.md` file. This means standard installers can discover it:
+
+```bash
+npx skills add . --list
+npx skills add . --skill bili-digest -g -a codex -y
+```
+
+For the public GitHub repository, HTTPS works directly:
+
+```bash
+npx skills add https://github.com/JackMeds/BiliDigest --skill bili-digest -g -a codex -y
+```
+
+SSH install also works after `ssh -T git@github.com` succeeds. Use HTTPS or the local path if SSH authentication is not configured.
+
+`npx skills` installs the skill instructions, not the Python project itself. Keep this repository cloned and dependencies installed. The skill includes `skills/bili-digest/scripts/bilidigest`, a small launcher that finds the clone via `BILIDIGEST_HOME` or the default local path. Set `BILIDIGEST_HOME` to the absolute path of your clone so the launcher works on your machine.
+
+For local development, a symlink install is still useful because edits reflect immediately:
+
+```bash
+python install.py --target ~/.agents/skills
+```
+
+For routine updates after a pull:
+
+```bash
+git pull
+npx skills add . --skill bili-digest -g -a codex -y
+```
+
+## Safety Defaults
+
+- Batch commands default to `15` items.
+- Requests are deliberately slow by default: each API call waits about `8-12` seconds. You can tune this with `BILIDIGEST_DELAY_SECONDS` and `BILIDIGEST_DELAY_JITTER_SECONDS`.
+- For large batches, keep the default slow mode or use a modest setting such as `BILIDIGEST_DELAY_SECONDS=6 BILIDIGEST_DELAY_JITTER_SECONDS=2`; do not run multiple batch jobs concurrently.
+- The legacy video/audio downloader also uses one fragment at a time and passes slow `yt-dlp` sleep settings. Tune it with `BILIDIGEST_YTDLP_SLEEP_SECONDS` and `BILIDIGEST_YTDLP_MAX_SLEEP_SECONDS`.
+- Risk-control responses such as HTTP `412` or Bilibili `-352` stop batch processing.
+- Cookies, sessions, `.env`, and output files are ignored by Git.
+- The tool only processes content your logged-in account can already access.
+
+## Acknowledgements
+
+BiliDigest was shaped by practical behavior observed in open-source Bilibili tooling, especially [BiliTools](https://github.com/btjawa/BiliTools), which is licensed under GPL-3.0-or-later. This repository does not import the BiliTools Tauri UI; it keeps a small Python CLI surface for local agent use. See [NOTICE](../NOTICE) for attribution notes.
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 0000000..39f8d50
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,174 @@
+# BiliDigest 使用与迁移参考
+
+面向个人 Agent 工作流的 B站收藏与稍后再看摘要工具。
+
+[返回项目首页](../README.md) · [English reference](usage.en.md)
+
+本页保留登录迁移、批量续跑和 Agent 接入的完整说明。下面的命令均从仓库根目录执行。
+
+许可证：GPL-3.0-or-later。
+
+**BiliDigest / 哔哩摘要笔记** 用于读取本人已登录 B站账号可访问的视频，把“稍后再看”和“收藏夹”中的内容整理成 Markdown/SRT/JSON，方便 Hermes Agent、Codex 或其他 Agent 做总结、笔记和知识整理。它优先使用 B站现成字幕和 B站 AI 小助手总结，也保留 ASR/大模型转写作为显式 fallback。
+
+## 功能
+
+- 使用统一的用户数据目录 session，并兼容迁移旧版 `.user_session.json`。
+- 列出稍后再看、收藏夹目录、收藏夹内容。
+- 稍后再看列表会缓存到本地，避免 Agent 重启后反复拉取 500+ 条列表。
+- 列表命令会返回远端 `total`，即使用 `--limit 1` 也能快速知道稍后再看/收藏夹总数。
+- 批量任务带持久状态文件，支持断点续跑、跳过已完成和失败项。
+- 优先使用 B站已有字幕，不默认跑 ASR。
+- 可导出 B站 AI 小助手总结。
+- 输出到 `output/bilidigest/<日期>/`。
+- Whisper/Qwen/OpenAI/Gemini 保留为显式 fallback，不再作为主流程。
+
+本项目不是 B站 API 文档库，也不是第三方客户端。定位是本地优先的个人 Agent 辅助工具。
+
+## 安装
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## 登录
+
+```bash
+python -m tools.bilidigest auth status
+python -m tools.bilidigest auth import-browser edge
+python -m tools.bilidigest auth login
+```
+
+默认登录态统一保存到 macOS 用户数据目录：
+
+```text
+~/Library/Application Support/BiliDigest/session.json
+```
+
+`auth import-browser edge` 会通过 `yt-dlp` 导入 Microsoft Edge 里的 B站 Cookie，并保存到这份共享 session。扫码登录仍然保留：它会同时输出紧凑终端二维码、可复制登录 URL，并保存图片到 `output/login_qr.png`。旧版 BiliSubNotes session 和项目根目录 `.user_session.json` 只作为兼容 fallback；如果存在且有效，会尽量迁移到共享 session。
+
+如果调用方是 Hermes Agent、Telegram bot 或 TUI，使用非阻塞 JSON 登录流程：
+
+```bash
+python -m tools.bilidigest auth login --json --no-wait
+python -m tools.bilidigest auth poll --json
+python -m tools.bilidigest auth status --json
+```
+
+第一条命令会返回 `login_url`、`qr_image`、`qrcode_key` 和 `poll_command`。聊天 Agent 把 URL 或二维码图片发给用户，再轮询直到状态变成 `logged_in`、`expired`、`scanned` 或 `pending`。
+
+查看当前共享 session 位置：
+
+```bash
+python -m tools.bilidigest auth session-path --json
+```
+
+## 使用
+
+```bash
+# 稍后再看
+python -m tools.bilidigest list watch-later --limit 15
+python -m tools.bilidigest list watch-later --limit 600 --no-items
+
+# 本人收藏夹目录
+python -m tools.bilidigest list favorites --mid me
+
+# 指定收藏夹内容
+python -m tools.bilidigest list favorite --media-id 123456 --limit 15
+
+# 导出字幕
+python -m tools.bilidigest transcript BVxxxxxxxxxx --format md
+python -m tools.bilidigest transcript "https://www.bilibili.com/video/BVxxxxxxxxxx" --format srt
+
+# 导出 B站 AI 小助手总结
+python -m tools.bilidigest summary BVxxxxxxxxxx
+
+# 批量处理稍后再看
+python -m tools.bilidigest batch watch-later --limit 15 --with-summary
+python -m tools.bilidigest batch watch-later --limit 600 --fallback-summary --with-summary
+```
+
+旧命令仍保留兼容：`python -m tools.auth --status`、`python -m tools.list --watch-later`、`python -m tools.batch_run`。
+
+### 批量处理和续跑
+
+`batch watch-later` 默认使用本地缓存和状态文件：
+
+```text
+output/bilidigest/cache/watch-later.jsonl
+output/bilidigest/cache/watch-later.meta.json
+output/bilidigest/snapshots/watch-later.json
+output/bilidigest/state/watch-later.json
+```
+
+默认列表缓存有效期是 24 小时。每次刷新列表时会更新快照并记录 `added`、`removed`、`changed`，方便日更自动化判断新增和移除。日常自动化或 Hermes Agent 重启后，直接重复运行同一条 `batch` 命令即可续跑；已完成视频会跳过，之前失败的视频也会跳过，避免反复请求同一个视频。
+
+常用参数：
+
+```bash
+# 强制刷新稍后再看列表
+python -m tools.bilidigest batch watch-later --limit 600 --refresh-list
+
+# 每天自动化：刷新列表，但只处理本次快照新增的视频
+python -m tools.bilidigest batch watch-later --limit 600 --refresh-list --only-new --fallback-summary
+
+# 忽略旧状态，从当前列表重新处理
+python -m tools.bilidigest batch watch-later --limit 600 --no-resume
+```
+
+`--retry-failed` 只适合人工排查某个短时间故障后手动使用，不要放进日常自动化或大批量后台任务。无字幕、无 AI 总结的视频失败一次就应保留失败状态。
+
+如果视频没有 B站现成字幕，`--fallback-summary` 会尝试导出 B站 AI 小助手总结，并把该条记录为 `summary_only`。遇到登录失效、HTTP `412`、B站 `-352` 等风控信号时，批处理会保存状态并停止。
+
+## Agent Skill
+
+Skill 位于：
+
+```text
+skills/bili-digest/
+```
+
+仓库采用 Agent Skills 标准目录：每个 Skill 是一个目录，目录内必须有 `SKILL.md`。因此标准安装器可以直接发现它：
+
+```bash
+npx skills add . --list
+npx skills add . --skill bili-digest -g -a codex -y
+```
+
+如果从公开 GitHub 仓库安装，HTTPS 可以直接使用：
+
+```bash
+npx skills add https://github.com/JackMeds/BiliDigest --skill bili-digest -g -a codex -y
+```
+
+SSH 形式也可以，但前提是 `ssh -T git@github.com` 能通过；未配置 SSH 的环境可使用 HTTPS 或本地路径。
+
+`npx skills` 安装的是 Skill 指令，不会自动安装 Python 项目本体。仍然需要保留本仓库 clone 和 `.venv` 依赖。Skill 内置了 `skills/bili-digest/scripts/bilidigest` 启动器，会通过 `BILIDIGEST_HOME` 或默认本机路径找到真正的 CLI。为适配你的机器，请将 `BILIDIGEST_HOME` 设置为本仓库 clone 的绝对路径。
+
+本地开发时也可以用软链接安装，优点是改 Skill 文档后立即生效：
+
+```bash
+python install.py --target ~/.agents/skills
+```
+
+日常更新可以这样做：
+
+```bash
+git pull
+npx skills add . --skill bili-digest -g -a codex -y
+```
+
+## 安全默认值
+
+- 批量命令默认最多处理 `15` 条。
+- 请求默认故意很慢：每次 API 调用大约等待 `8-12` 秒。可以用 `BILIDIGEST_DELAY_SECONDS` 和 `BILIDIGEST_DELAY_JITTER_SECONDS` 调整。
+- 大批量处理建议使用默认慢速或稍微调到 `BILIDIGEST_DELAY_SECONDS=6 BILIDIGEST_DELAY_JITTER_SECONDS=2`，不要并发启动多个批处理。
+- 旧的视频/音频下载入口也会使用单 fragment 和慢速 `yt-dlp` sleep 参数。可以用 `BILIDIGEST_YTDLP_SLEEP_SECONDS` 和 `BILIDIGEST_YTDLP_MAX_SLEEP_SECONDS` 调整。
+- 遇到 HTTP `412` 或 B站 `-352` 等风控信号会停止批处理。
+- Cookie、Session、`.env` 和输出目录均被 Git 忽略。
+- 只处理本人账号本来就能访问的内容。
+
+## 鸣谢
+
+BiliDigest 的功能边界和安全策略参考了开源 B站工具的实践，特别是采用 GPL-3.0-or-later 协议的 [BiliTools](https://github.com/btjawa/BiliTools)。本项目不迁入 BiliTools 的 Tauri UI，只保留轻量 Python CLI，供本地 Agent 使用。归属和参考说明见 [NOTICE](../NOTICE)。
diff --git a/project-brand.json b/project-brand.json
new file mode 100644
index 0000000..93553a6
--- /dev/null
+++ b/project-brand.json
@@ -0,0 +1,29 @@
+{
+ "schemaVersion": 1,
+ "repo": "JackMeds/BiliDigest",
+ "wordmark": "BiliDigest",
+ "displayName": "BiliDigest / 哔哩摘要笔记",
+ "localName": "哔哩摘要笔记 / 从视频队列到个人知识",
+ "kind": "pipeline",
+ "category": "personal knowledge",
+ "accent": "#B83B69",
+ "accentDark": "#F199B6",
+ "tagline": {
+ "en": "A video queue, ready for your next idea.",
+ "zh": "将字幕与摘要整理成 Agent 可读的笔记。"
+ },
+ "tags": [
+ "subtitles",
+ "markdown",
+ "agent workflows"
+ ],
+ "readmes": [
+ "README.md",
+ "README_en.md"
+ ],
+ "links": {
+ "source": "https://github.com/JackMeds/BiliDigest"
+ },
+ "pilot": true,
+ "proof": "assets/brand/product-proof.png"
+}
+