---
phase: 18-documentation-ux-polish
plan: 02
type: execute
wave: 1
depends_on: []
files_modified:
  - docs/MIGRATION-v1.4.md
  - docs/ARCHITECTURE.md
  - AGENTS.md
  - README.md
  - chart-reading/INDEX.md
  - .planning/ROADMAP.md
autonomous: true
requirements:
  - DOCS-01
  - DOCS-02
  - DOCS-03
  - DOCS-04
  - UX-02
  - UX-03
  - UX-04

must_haves:
  truths:
    - "docs/MIGRATION-v1.4.md documents all behavioral changes between v1.3 and v1.4"
    - "docs/ARCHITECTURE.md includes ADR-012 (Shared Utilities) and ADR-013 (Dual-Output Logging) after ADR-011"
    - "AGENTS.md Section 1 includes a 'What to type where' table mapping /pf-* commands to paperforge CLI commands"
    - "AGENTS.md references --verbose, auto_analyze_after_ocr, and chart-reading INDEX.md"
    - "README.md no longer has orphaned legacy code lines at lines 102-104"
    - "chart-reading/INDEX.md lists all 19 guides ordered by biomedical commonness"
    - ".planning/ROADMAP.md shows Phase 18 with 2 plans"
  artifacts:
    - path: "docs/MIGRATION-v1.4.md"
      provides: "Migration documentation from v1.3 to v1.4"
      min_lines: 100
    - path: "docs/ARCHITECTURE.md"
      provides: "ADR-012 and ADR-013"
      contains: "ADR-012"
    - path: "AGENTS.md"
      provides: "Command mapping table in Section 1 + v1.4 feature references"
      contains: "auto_analyze_after_ocr"
    - path: "README.md"
      provides: "Fixed rendering — orphaned legacy lines removed"
      min_lines: 105
    - path: "chart-reading/INDEX.md"
      provides: "Cross-reference index of all 19 chart-reading guides"
      min_lines: 25
  key_links:
    - from: "chart-reading/INDEX.md"
      to: "prompt_deep_subagent.md"
      via: "chart-type-map.json recommend guides from INDEX"
      pattern: "chart-reading"
    - from: "AGENTS.md"
      to: "docs/MIGRATION-v1.4.md"
      via: "Migration link in Section 11"
      pattern: "MIGRATION-v1.4\\.md"
---

<objective>
Create MIGRATION-v1.4.md, add ADR-012/013 to ARCHITECTURE.md, update AGENTS.md with command mapping table and v1.4 features, fix README.md orphaned lines, create chart-reading INDEX.md, and update ROADMAP.md.

Purpose: Complete all user-facing and maintainer-facing documentation for v1.4 — migration path, architecture decisions, command naming audit, and cross-references.
Output: 6 files created or modified.
</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/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md

@docs/MIGRATION-v1.2.md (template for MIGRATION-v1.4.md)
@docs/ARCHITECTURE.md (ADRs at lines 283-501, ADR-011 ends at line 501)
@AGENTS.md (Section 1 at lines 29-42, Section 8 at lines 393-435)
@README.md (lines 100-104 orphaned legacy code)
@.planning/phases/13-logging-foundation/13-CONTEXT.md (source for ADR-013)
@.planning/phases/14-shared-utilities-extraction/14-CONTEXT.md (source for ADR-012)
@paperforge/skills/literature-qa/chart-reading/ (19 guide files)
@paperforge/skills/literature-qa/prompt_deep_subagent.md (already references chart-reading)
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create MIGRATION-v1.4.md + fix README.md orphaned lines</name>
  <files>docs/MIGRATION-v1.4.md, README.md</files>
  <action>
    Per D-07 (DOCS-01) and D-10 (UX-02):

    ### docs/MIGRATION-v1.4.md

    Follow the exact structure of `docs/MIGRATION-v1.2.md` as a template. Create `docs/MIGRATION-v1.4.md` with:

    - **Header:** `# Migration Guide: v1.3 to v1.4`
    - **What's New in v1.4 section:** Describe the four areas: (1) structured logging with dual output, (2) retry + progress bars, (3) pre-commit hooks + ruff, (4) auto_analyze_after_ocr
    - **Breaking Changes Summary table**: env vars (PAPERFORGE_LOG_LEVEL, PAPERFORGE_RETRY_MAX, PAPERFORGE_BACKOFF), pre-commit hooks (new dev requirement), auto_analyze_after_ocr (opt-in)
    - **Detailed sections**: One per change area:
      1. Dual-Output Logging: `--verbose` flag, PAPERFORGE_LOG_LEVEL env var, logger hierarchy, stdout vs stderr split
      2. Retry Behavior: exponential backoff, PAPERFORGE_RETRY_MAX/PAPERFORGE_RETRY_BACKOFF env vars, zombie job detection
      3. Pre-commit + Ruff: `pre-commit install` requirement, `ruff check --fix`, `ruff format`, E501 suppression
      4. auto_analyze_after_ocr: opt-in, set in paperforge.json, reduces manual frontmatter editing
    - **Migration Steps**: Step-by-step guide (backup → update → install hooks → verify)
    - **Rollback Instructions**: Following v1.2 template pattern
    - **FAQ**: Common questions about the upgrade

    ### README.md fix

    Per UX-02: Remove orphaned legacy code lines 102-104:
    ```
    python <resolved_worker_script> --vault . ocr
    python <resolved_worker_script> --vault . status
    ```
    These lines appear after the `> **双模式说明**` quote block and before `## License`. They are not inside any code fence. Remove lines 102, 103, AND 104 (the lone closing ``` on line 104) so the `> **双模式说明**` quote block flows directly to `## License`.

    After removal, verify no other rendering issues by scanning AGENTS.md, docs/*.md, and command/*.md for code snippets or backtick fences that appear orphaned (check for unclosed code fences, text outside callout blocks that looks like code, etc.). If found, fix them.
  </action>
  <verify>
    <automated>python -c "assert '## What' in open('docs/MIGRATION-v1.4.md').read(); print('MIGRATION-v1.4.md exists and has content')" && python -c "text = open('README.md').read(); assert 'python <resolved_worker_script>' not in text, 'orphaned lines still present'; assert text.strip().endswith('MIT License'), 'README ends correctly'"</automated>
  </verify>
  <done>
    docs/MIGRATION-v1.4.md exists following v1.2 template pattern with all v1.4 changes documented. README.md has orphaned lines 102-104 removed with no other rendering issues found in doc audit.
  </done>
</task>

<task type="auto">
  <name>Task 2: Add ADR-012, ADR-013 to ARCHITECTURE.md + update AGENTS.md</name>
  <files>docs/ARCHITECTURE.md, AGENTS.md</files>
  <action>
    Per D-08 (DOCS-03), D-09 (UX-04), and DOCS-02:

    ### docs/ARCHITECTURE.md — ADR-012 and ADR-013

    Add two new ADR entries after ADR-011 (ends at line 501, before `## Extension Points` at line 503). Follow the exact ADR format used by ADR-001 through ADR-011:

    **ADR-012: Shared Utilities Extraction (`_utils.py`)**
    Extract from Phase 14 CONTEXT.md:
    - **Status:** Accepted
    - **Phase:** 14
    - **Context:** ~1,610 lines of utility code were copy-pasted across 7 worker modules; changes to one copy often missed others; bug fixes had to be applied N times.
    - **Decision:** Create `paperforge/worker/_utils.py` as a pure leaf module organized by category (JSON I/O, YAML helpers, String/Path Utils, Journal Database, Constants). The module must never import from `paperforge.worker.*` or `paperforge.commands.*` — only from stdlib and `paperforge.config`. Functions are imported by workers as `from paperforge.worker._utils import read_json, ...`. Re-exports with `# Re-exported from _utils.py for backward compatibility` comments preserve backward compatibility in original modules.
    - **Consequences:** (+) Single source of truth for utility functions. (+) Easier testing (dedicated test files). (+) No circular imports (leaf module constraint). (-) Re-export comments add minor clutter to original modules. (-) Module must be carefully audited at every change to maintain leaf status.

    **ADR-013: Dual-Output Logging Strategy**
    Extract from Phase 13 CONTEXT.md:
    - **Status:** Accepted
    - **Phase:** 13
    - **Context:** The codebase used ad-hoc `print()` calls for all output — user-facing status, diagnostic traces, and error messages. This made it impossible to filter log levels, broke piped command output when diagnostic text appeared on stdout, and provided no structured error reporting.
    - **Decision:** Implement a dual-output strategy: (1) `print()` preserved for user-facing formatted output on stdout only — existing piped commands and Agent scripts that parse stdout remain unmodified. (2) `logging.getLogger(__name__)` used for all diagnostic/trace/error output to stderr. A `configure_logging(verbose: bool)` function in `paperforge/logging_config.py` configures the root logger. Log level defaults to `INFO` (from `PAPERFORGE_LOG_LEVEL` env var) and switches to `DEBUG` when `--verbose`/`-v` is passed.
    - **Consequences:** (+) Structured log output with levels, module names, and timestamps. (+) Piped stdout remains clean. (+) `--verbose` enables per-module debugging. (-) Two output channels require documentation (users must know stdout vs stderr). (-) Existing `print()` calls for user-facing output remain as-is (no behavioral change guarantee).

    ### AGENTS.md — Command Mapping + v1.4 Updates

    Per D-09 (UX-04) and DOCS-02:

    1. **Add "What to type where" table in Section 1 (核心架构):**
       Insert the following table after the bullet list at line 41 (`- Worker 不会自动触发 Agent，Agent 不会自动触发 Worker`) and before the `---` separator at line 42:

       ```markdown
       **操作速查**：
       | 你要做什么 | 在终端输入 | 在 OpenCode 输入 |
       |-----------|-----------|-----------------|
       | 同步 Zotero 并生成笔记 | `paperforge sync` | `/pf-sync` |
       | 运行 OCR | `paperforge ocr` | `/pf-ocr` |
       | 查看精读队列 | `paperforge deep-reading` | `/pf-deep`（精读具体文献） |
       | 查看系统状态 | `paperforge status` | `/pf-status` |
       | 修复状态分歧 | `paperforge repair` | （终端操作） |
       | 验证安装配置 | `paperforge doctor` | （终端操作） |
       | 查看帮助 | `paperforge --help` | （终端操作） |
       ```

       The `---` separator (line 42) must remain after the table.

    2. **AGENTS.md v1.4 updates (DOCS-02):**
       - In Section 5 (`## 5. Agent 命令`), add `--verbose` flag note after `paperforge deep-reading --verbose` in the CLI examples.
       - In Section 5, add a note about `auto_analyze_after_ocr` workflow option to explain the opt-in automation: "如果开启了paperforge.json中的auto_analyze_after_ocr，OCR完成后analyze会自动设为true，无需手动修改library-record。"
       - In Section 8 (常用命令速查), ensure `--verbose` is shown on sync, ocr, and deep-reading examples.
       - In Section 8, if the chart-reading INDEX.md reference is relevant, add a brief cross-reference.
       - Update Section 11 date/version references if applicable.
  </action>
  <verify>
    <automated>python -c "text = open('docs/ARCHITECTURE.md').read(); assert 'ADR-012' in text; assert 'ADR-013' in text" && python -c "text = open('AGENTS.md').read(); assert '操作速查' in text or '/pf-sync' in text; assert 'auto_analyze_after_ocr' in text"</automated>
  </verify>
  <done>
    ARCHITECTURE.md has ADR-012 and ADR-013 after ADR-011. AGENTS.md Section 1 has "What to type where" table mapping commands. AGENTS.md references --verbose and auto_analyze_after_ocr.
  </done>
</task>

<task type="auto">
  <name>Task 3: Create chart-reading INDEX.md + update ROADMAP.md</name>
  <files>chart-reading/INDEX.md, .planning/ROADMAP.md</files>
  <action>
    Per D-04 (UX-03) and D-11 (DOCS-04):

    ### chart-reading/INDEX.md

    Create `paperforge/skills/literature-qa/chart-reading/INDEX.md` with a table listing all 19 chart-reading guides, ordered by approximate biomedical commonness per D-04:

    Ordering per D-04 (most common first):
    bar/column → forest plot → line → scatter → ROC → survival (Kaplan-Meier) → box plot → heatmap → flow diagram → pie → violin → waterfall → volcano → bubble → correlation matrix → dendrogram → nomogram → calibration → QQ plot

    Map the 19 actual guide files to this ordering. Where a guide covers multiple chart types (e.g., 箱式图与小提琴图 covers both box plot and violin), use the most common type for ordering. Append guides not covered by D-04's list after the ordered list (grouped by similarity).

    Format:
    ```markdown
    # Chart-Reading Guide Index

    > 按生物医学文献中的常见度排序。每个指南包含该图类型的阅读方法、关键审查问题、以及常见陷阱。

    | # | 图表类型 | 处理的主要图表类型 | 指南文件 |
    |---|---------|-------------------|---------|
    | 1 | 条形图与误差棒 | 柱状图、条形图、误差棒 | [条形图与误差棒.md](条形图与误差棒.md) |
    | 2 | 森林图与Meta分析 | 森林图、Meta分析 | [森林图与Meta分析.md](森林图与Meta分析.md) |
    | ... | ... | ... | ... |
    ```

    Suggested order for all 19 files (with D-04 primary rank mapped, and remaining files appended in logical groups):

    1. 条形图与误差棒 (bar)
    2. 森林图与Meta分析 (forest plot)
    3. 折线图与时间序列 (line)
    4. 散点图与气泡图 (scatter, bubble)
    5. ROC与PR曲线 (ROC)
    6. 生存曲线 (survival/Kaplan-Meier)
    7. 箱式图与小提琴图 (box plot, violin)
    8. 热图与聚类图 (heatmap, correlation matrix, dendrogram)
    9. 桑基图与弦图 (flow/Sankey)
    10. 火山图与曼哈顿图 (volcano, Manhattan)
    11. 网络图与通路图 (network/pathway)
    12. GSEA富集图 (enrichment analysis)
    13. 降维图(PCA-tSNE-UMAP) (dimension reduction)
    14. 雷达图与漏斗图 (radar, funnel)
    15. 组织学半定量图 (histology)
    16. 免疫荧光定量图 (immunofluorescence)
    17. 显微照片与SEM图 (micrograph, SEM)
    18. Western Blot条带图 (Western blot)
    19. 蛋白质结构图 (protein structure)

    Use Obsidian wikilinks format `[[filename]]` for the guide links since the INDEX.md lives in the same directory and will be viewed in Obsidian.

    Each row includes a brief description of the chart types covered.

    ### .planning/ROADMAP.md update

    Per D-11 (DOCS-04):

    1. Update Phase 18 entry in the main list (top section): Change `- [ ] **Phase 18: ...**` to `- [ ] **Phase 18: ... — 2 plans` (add plan count)
    2. Update the Phase 18 details section (## Phase Details):
       - Change `**Plans**: TBD` to `**Plans**: 2 plans (1 wave)`
       - Add plan list under the Plans heading:
         ```
         Plans:
         - [ ] 18-01-PLAN.md — Core Config & Foundation Docs (auto_analyze_after_ocr, CHANGELOG, CONTRIBUTING)
         - [ ] 18-02-PLAN.md — Migration, Architecture & Doc Polish (MIGRATION, ADRs, AGENTS, INDEX, README)
         ```
    3. Update the progress table at the bottom: Change Phase 18 plans from `0/0` to `2/0` (2 planned, 0 complete)

    Make no other changes to ROADMAP.md.
  </action>
  <verify>
    <automated>python -c "text = open('paperforge/skills/literature-qa/chart-reading/INDEX.md').read(); assert '|' in text; assert '条形图' in text; assert 'INDEX' in text; assert len([l for l in text.splitlines() if l.startswith('|') and '|' in l[1:]]) >= 20  # header + separator + 19 data rows" && python -c "text = open('.planning/ROADMAP.md').read(); assert '18-01-PLAN' in text; assert '18-02-PLAN' in text"</automated>
  </verify>
  <done>
    chart-reading/INDEX.md created listing all 19 guides in biomedical commonness order. ROADMAP.md updated to show 2 plans for Phase 18 with correct plan names and count.
  </done>
</task>

</tasks>

<verification>
1. `[ -f docs/MIGRATION-v1.4.md ]` — migration doc exists
2. `grep -q "ADR-012" docs/ARCHITECTURE.md && grep -q "ADR-013" docs/ARCHITECTURE.md` — ADRs added
3. `grep -q "操作速查\|/pf-sync\|/pf-ocr" AGENTS.md` — command mapping table in AGENTS.md §1
4. `grep -q "auto_analyze_after_ocr" AGENTS.md` — v1.4 features documented
5. `! grep -q "python <resolved_worker_script>" README.md` — orphaned lines removed
6. `[ -f paperforge/skills/literature-qa/chart-reading/INDEX.md ]` — INDEX exists
7. `grep -q "18-01-PLAN" .planning/ROADMAP.md && grep -q "18-02-PLAN" .planning/ROADMAP.md` — roadmap updated
8. `pytest tests/ -x` — no regressions
</verification>

<success_criteria>
1. docs/MIGRATION-v1.4.md documents all v1.3→v1.4 behavioral changes
2. ARCHITECTURE.md has ADR-012 and ADR-013 with proper format
3. AGENTS.md §1 has command mapping table; AGENTS.md references v1.4 features
4. README.md no longer shows orphaned legacy code lines
5. chart-reading/INDEX.md lists all 19 guides ordered by commonness
6. ROADMAP.md accurately shows 2 Phase 18 plans
</success_criteria>

<output>
After completion, create `.planning/phases/18-documentation-ux-polish/18-02-SUMMARY.md`
</output>
