---
phase: 04-onboarding-validation
plan: '04'
type: execute
wave: 1
depends_on: []
files_modified:
  - docs/README.md
autonomous: true
requirements:
  - ONBD-01
  - ZOT-03

must_haves:
  truths:
    - User can read docs/README.md to understand Better BibTeX configuration steps
    - BBT export path, JSON format, and "Keep Updated" setting are all explained
    - User knows how to verify their BBT export is working correctly
  artifacts:
    - path: "docs/README.md"
      provides: "Better BibTeX configuration guide for users"
      contains: "Better BibTeX"
  key_links:
    - from: "docs/README.md"
      to: "paperforge/cli.py"
      via: "paperforge doctor validates BBT export"
      pattern: "paperforge doctor"
---

<objective>
Create docs/README.md with Better BibTeX configuration instructions for users. This is the user-facing BBT setup guide separate from AGENTS.md (which is for agents).
</objective>

<execution_context>
@C:/Users/Lin/.opencode/get-shit-done/workflows/execute-plan.md
@C:/Users/Lin/.opencode/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/phases/04-onboarding-validation/04-CONTEXT.md (Area 2 for BBT validation requirements)
@.planning/STATE.md
@docs/INSTALLATION.md (for format reference)
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create docs/README.md with BBT configuration guide</name>
  <files>docs/README.md</files>
  <read_first>
    - docs/INSTALLATION.md (for format/style reference)
    - .planning/phases/04-onboarding-validation/04-CONTEXT.md (Area 2 for BBT check requirements)
  </read_first>
  <action>
    Create docs/README.md with the following sections:

    ## Better BibTeX 配置指南

    ### 什么是 Better BibTeX

    Better BibTeX (BBT) 是一个 Zotero 插件,用于生成和管理 citation key,并支持自动导出 JSON 格式的文献库。

    ### 为什么需要 BBT

    PaperForge 通过 BBT 的 JSON 导出功能获取文献信息:
    - citation key (zotero_key)
    - 标题、作者、年份
    - DOI、期刊、摘要
    - PDF 附件路径

    ### 配置步骤

    1. **安装 Better BibTeX 插件**
       - 在 Zotero 中: Edit -> Preferences -> Plugins
       - 搜索 "Better BibTeX", 安装并重启 Zotero

    2. **配置自动导出**
       - Zotero -> Edit -> Preferences -> Better BibTeX
       - 勾选 "Keep updated" (保持更新)
       - 选择导出格式: Better BibLaTeX 或 Better BibTeX (二者皆可)
       - 导出路径设置为:
         ```
         {你的Vault路径}/{system_dir}/PaperForge/exports/library.json
         ```
         注意: {system_dir} 默认是 "99_System",可以通过 paperforge.json 自定义

    3. **验证配置**
       - 在 Zotero 中手动触发一次导出 (右击收藏夹 -> Export ...)
       - 确认 JSON 文件已生成且包含文献数据

    4. **使用 paperforge doctor 验证**
       ```bash
       paperforge doctor
       ```
       检查输出中的 "BBT 导出" 部分,确认:
       - [PASS] 导出路径存在
       - [PASS] JSON 格式正确
       - [PASS] 包含有效的 citation key

    ### 常见问题

    **Q: 导出路径填什么?**
    A: 完整路径示例:
    ```
    D:\MyVault\99_System\PaperForge\exports\library.json
    ```
    {Vault根目录} + {system_dir} + PaperForge/exports/library.json

    **Q: "Keep updated" 是什么?**
    A: 勾选后,每次添加/修改文献时 Zotero 会自动更新 JSON 文件,无需手动导出。

    **Q: JSON 文件是空的怎么办?**
    A:
    1. 确认 Zotero 中有文献
    2. 确认导出了 PDF 附件的文献(没有 PDF 的文献可能不会被导出)
    3. 检查 Zotero -> Better BibTeX preferences 中的导出格式设置

    **Q: citation key 是什么?**
    A: citation key 是文献的唯一标识符,例如 "Smith2024AI"。BBT 根据作者、年份、标题自动生成。

    ### 验证 BBT 导出

    使用 paperforge doctor:
    ```bash
    paperforge doctor
    ```

    输出示例(正常情况):
    ```
    [PASS] BBT 导出 — library.json 正常 (25 条)
    ```

    输出示例(有问题):
    ```
    [FAIL] BBT 导出 — library.json 不存在
    [FIX]  请在 Zotero Better BibTeX 设置中配置导出路径为:
           {vault}/{system_dir}/PaperForge/exports/library.json
    ```
  </action>
  <verify>
    <automated>test -f docs/README.md && grep -c "Better BibTeX" docs/README.md</automated>
  </verify>
  <done>docs/README.md created with BBT configuration guide</done>
</task>

</tasks>

<verification>
- docs/README.md exists and contains Better BibTeX configuration steps
- docs/README.md mentions paperforge doctor for verification
- docs/README.md is written in Chinese for user-facing documentation
</verification>

<success_criteria>
docs/README.md provides clear BBT configuration instructions for users in Chinese
</success_criteria>

<output>
After completion, create `.planning/phases/04-onboarding-validation/04-04-SUMMARY.md`
</output>
