`docs/` 索引

本文件只做索引：根层文档各是什么、谁在引用它，以及 6 个子目录各归什么。 🚫 这里不定义任何规则 —— 规则的稳定归属见根 CLAUDE.md §4「红线归属规则」。索引与被索引者漂移时，以被索引的那份为准，回来改本文件。
体量数字刻意不写（它们必然静默漂移，见 verification/README.md 的同款铁律）。要现数：ls -la docs/*.md。

1. 根层（按用途分四组）

「被引用」= 全仓非归档处引用该文件名的文件数（现数命令见 §4），用来判断改它的爆炸半径。

产品与架构

文档	做什么用	谁在引用
`product.md`	产品概览 —— 双端产品定位与功能清单的唯一真相源（2026-08-29 起 `rvh/docs/product.md` 已收缩成指回它的指针）。不是规划文档	CLAUDE.md · roadmap / launch-todo · rvh 侧指针
`architecture.md`	桌面端当前系统架构（Multi-Webview / DB 双通道 / content-script IPC 的展开面）	`src-tauri/CLAUDE.md` · 多数 plan
`sync-protocol.md`	同步协议全景 —— 增量游标 / 脏判定 / 墓碑 / 冲突裁决 / 快照通道，以及四个静默失效家族与五条契约不变量的关系。只讲解释，条文在 `../CLAUDE.md` §4	architecture.md · cross-end/README · verification/sync-consistency
`recommendation-algorithm.md`	推荐系统算法全景（发现 → 维护 → 个性化）。纯 RB + Supabase，无 RVH	admin · supabase functions · 推荐类 plan
`vocabulary-domain-knowledge.md`	语言学/构词学领域概念词典（词源、消歧、cloze、词形还原的术语边界）	`tools/` pipeline · 词汇类 plan

规范（写代码前对齐）

文档	做什么用	谁在引用
`coding-standards.md`	代码风格 / 组件分层 / Store 分离 / 文件归属 / 提交规范的细节。⚠️ 技术红线的真相源不在这里，在 `CLAUDE.md` §4，本文件 §1 只留指针	CLAUDE.md §12 · `/arch-check` · `/rb-code-review`
`ui-standards.md`	桌面端设计语言：token / 组件变体 / 间距字号 scale / 交互原则。`/arch-check` S10-S12 + `/ui-check` 按它扫描	`src/CLAUDE.md` · `/ui-check` · `/arch-check`
`ui-component-inventory.md`	`src/components/ui/` 每个组件的实际调用点与业务实体映射。与 ui-standards 互补：规范说「应该用什么」，它记「当前用在哪」	ui-standards · `/ui-check`

🔑 两套 UI 规范是刻意的，不是漂移 —— 别去「统一」它们。docs/ui-standards.md（Tailwind / 桌面端 Tauri+React）与 rvh/docs/ui-guidelines/（Material 3 / 移动端 Flutter） 各管一端：前者的 token 是 CSS 变量与 Tailwind @theme，后者的是 Material 3 的 elevation / color role / typography scale。两端的设计系统本身不同源，合并会产出一份两边都不能直接执行的东西。真正需要三端一致的是数据与算法（SM-2 映射表、sync 协议、归一键空间），那些的归属在 CLAUDE.md §4 / §9，不在 UI 规范里。

数据（三份分工明确，别混用）

文档	做什么用	谁在引用
`database-schema.md`	列级字典 + §9 Supabase 映射 + §10 迁移版本史（迁移明细的唯一真相源）	全仓引用最多的一份 · CLAUDE.md §5 · schema 同步协议清单
`database-tables-overview.md`	概念地图：本地表按用途分组 + 数据流 + 关系图 + 同步/soft-delete 一览。管「流向」，schema 管「列」	database-schema · plan
`database-operations.md`	运维手册总纲：日常节律 · 重大变更 · 事故分级与处置 · 演练周期。`/db-incident` 的背景读物	`/db-incident` · backup runbook

Runbook（照着做的操作手册）

文档	做什么用	谁在引用
`supabase-backup-restore-runbook.md`	Supabase 备份/恢复的操作步骤，配套 `scripts/backup-supabase.sh` + `scripts/backup-supabase-storage.mjs`	database-operations · product-launch-todo C4
`smoke-test-runbook.md`	发版前对运行中 dev app 跑的半自动冒烟清单（rb-debug MCP 驱动）。不是 CI 门	`/release` · roadmap 5-5

2. 子目录（各自有 README，去那里找细目）

目录	归什么	索引
`plans/`	活跃实施计划 + `backlog.md`/`backlog-archive.md` + roadmap + launch-todo。完成即移进 `docs/plans/archive/`。⚠️ 移动端另有一套同构的 `rvh/docs/plans/`（含 2026-08-30 新建的 `rvh/docs/plans/archive/`）—— 跨端条目按「谁执行谁持有」分落两侧，规则写在两份 backlog 的头部	有 README
`plans/archive/`	已完成/已作废的 plan。🚫 历史记述，不要改	同上
`cross-end/`	跨端交接（handoff / confirmation / 裁定）+ `sm2-golden-vectors.json`。文件名是 `NN-*` 时序编号，是 `docs/kebab-case.md` 规则的唯一例外	有 README（含重号总表）
`verification/`	专题验证清单，🔒 常驻永不归档。配套 `scripts/*-verify.sh`，对应关系见 `../scripts/README.md`	有 README（含「判据下沉成断言」铁律）
`archive/`	早期编号文档（`00-项目概述.md` … `09-双端整合实施计划.md`）+ `PROGRESS.md` + `mcp-primer.md`（2026-08-30 从根层归档）。🚫 历史记述	有 README
`docs/.vitepress/`	知识库站点配置（VitePress，knowledge-base-plan P3）。`srcDir` 设成仓根 ⇒ 全仓 md 进站、7 份 CLAUDE.md 可读。🔒 两条前提写在 `docs/.vitepress/config.ts` 头注释里：主题层零 Vue + 文档只用标准 markdown（守卫 = `scripts/check-kb.mjs` A7/A8）。本机跑 `pnpm docs:dev`；`pnpm docs:build` 已进 CI	配置文件头注释
（部署 · 迁移中）	🔴 Vercel project `lampio-kb` 的 Standard Protection 挡不住 production 域（Hobby 无可用档位，`All Deployments` 是 Pro/$150 月）⇒ 正迁往 Cloudflare Pages + Access。仓库侧已备：`wrangler.toml`（产物目录）· `.node-version`。剩余步骤与验收命令在 `plans/backlog.md` 顶部 P0。🔒 验收一律是「无 cookie 请求打不开」，不是看设置页 —— 上一次正是靠这条判据发现设置页在说谎	`wrangler.toml` · backlog P0
`docs/brand/`	品牌母图 SVG（`lampio-icon.svg` / `lampio-mark.svg`）+ `README.md`：三条派生链（favicon / Tauri icons / rvh branding）的唯一活跃记载	—

别处的 README（同层级但不在 docs/ 下）：../scripts/README.md · ../tools/README.md · ../supabase/README.md。

📱 移动端自成一棵文档树（合仓后仍独立，本索引不重复收录它的细目）： ../rvh/docs/README.md（导航）· ../rvh/docs/plans/README.md（活跃计划区的约定）· ../rvh/scripts/README.md。 ⚠️ 有五样东西不在那棵树里（产品定位 / cross-end / 双端契约红线 / CI / 桌面端 CHANGELOG），它们的真相源都在仓根 —— 逐条对照表在 rvh/docs/README.md 开头那一节。

3. 写新文档时的约定（速查，规则本体在 CLAUDE.md §12）

文件名英文 kebab-case、禁数字前缀，正文中文。唯一例外 = docs/cross-end/NN-*.md。
一次性方案进 docs/plans/，完成后 git mv 进 docs/plans/archive/；反复重跑的清单进 docs/verification/（放进 plans 等于排进归档队列）。
反引号里写仓根相对路径（给 scripts/check-claude-md-paths.mjs 验）， markdown 链接写相对路径（给人点）。两者不要混。
新增根层文档后回来加一行。本文件是索引，不是自动生成物。
🔒 知识层文档必须是该知识的唯一真相源。 「整理归纳一份挂上去」= 造第二本账，立刻开始漂（architecture.md §8 那份同步流程图停在已废弃协议上三个月，就是现成例证）。正确动作是迁移 + 原处留指针：把解释搬进知识文档，原处（plan / cross-end / 别的 docs）改成一行链接。判据 = 把新文档删掉，原来的规则与流程是否仍然完整。
🔒 不要把「贴到公网上会扩大攻击面」的标识符写进文档 —— 判据不是「它是不是密钥」（那类本仓一个都没有），而是**「公开之后攻击者少走多少步」。已知两类，守卫 = scripts/check-kb.mjs A10：生产库连接串（用户名/主机/端口齐全，缺的只有密码 ⇒ 写成 postgres.<project-ref>@…<region>… 占位符）· 真实测试账号的邮箱与 user_id（登录标识符 ⇒ 写成 <测试账号 A> / <test-user-id-A> 这类稳定**占位符，稳定是为了保住「这两条记录是同一个账号」这层信息）。真值放 Keychain / 1Password，不入仓。 ⚠️ 访问控制解决不了这一类 —— 站关掉它们照样在仓库里，且下次摘一份文档给人看会再带出去一次。
🔒 知识文档必须带 sourceRefs + verifiedAt frontmatter，并登记进 scripts/check-kb.mjs 的注册表，否则守卫红。verifiedAt 的语义是「我把这篇对着这个 commit 核过了」—— 没核过就别填：填一个没核过的 sha 会让新鲜度报告永远说它是新的，那比没有徽章更糟。 pnpm run check:kb 会打印哪几篇的源码已变动、变了几次、是哪些 commit（只报告，不判失败）。
🔒 知识层写「解释」，../CLAUDE.md §4 留「规则」。 知识文档引用红线编号、不复述条文 —— 复述出来的那份是恒加载区那份的副本，漂了没有任何东西会红。（方案见 plans/knowledge-base-plan.md §3.2）

4. 数字现算命令

bash

cd /Users/larry/reading-browser
ls -la docs/*.md                       # 根层份数与体量
for f in docs/*.md; do b=$(basename "$f");
  printf "%-40s %3s\n" "$b" "$(grep -rl -- "$b" --include='*.md' --include='*.ts' \
    --include='*.tsx' --include='*.rs' --include='*.sh' --include='*.mjs' --include='*.yml' . \
    2>/dev/null | grep -v node_modules | grep -v '^./docs/archive' | grep -v "^./$f" | wc -l)"
done                                    # 被引用数（爆炸半径）
node scripts/check-doc-links.mjs        # 活跃文档里的 plans / cross-end 引用是否悬挂
node scripts/check-claude-md-paths.mjs docs/README.md   # 本文件反引号路径是否都存在

docs/ 索引 ​

1. 根层（按用途分四组） ​

产品与架构 ​

规范（写代码前对齐） ​

数据（三份分工明确，别混用） ​

Runbook（照着做的操作手册） ​

2. 子目录（各自有 README，去那里找细目） ​

3. 写新文档时的约定（速查，规则本体在 CLAUDE.md §12） ​

4. 数字现算命令 ​