---
phase: 06-setup-cli-diagnostics-consistency
plan: '01'
type: execute
wave: 1
depends_on: []
files_modified:
  - command/ld-deep.md
  - AGENTS.md
  - docs/INSTALLATION.md
  - paperforge/ocr_diagnostics.py
autonomous: true
requirements:
  - SETUP-03
  - SETUP-05
  - DIAG-04

must_haves:
  truths:
    - User sees fallback command `python -m paperforge` in AGENTS.md, INSTALLATION.md, and command docs
    - User sees correct field name `ld_deep_script` in command/ld-deep.md (not `literature_script`)
    - User sees actionable HTTP 405 error message distinguishing method mismatch from bad URL
  artifacts:
    - path: command/ld-deep.md
      provides: Agent command docs using correct `ld_deep_script` field name
      contains: ld_deep_script
    - path: AGENTS.md
      provides: User-facing command reference with fallback
      contains: python -m paperforge
    - path: docs/INSTALLATION.md
      provides: Installation docs with fallback
      contains: python -m paperforge
    - path: paperforge/ocr_diagnostics.py
      provides: HTTP 405 detection with actionable message
      contains: 405 Method Not Allowed
  key_links:
    - from: command/ld-deep.md
      to: paperforge/config.py
      via: ld_deep_script field consumed from paths JSON
      pattern: ld_deep_script
    - from: ocr_diagnostics.py L2 check
      to: PaddleOCR API
      via: HTTP POST request
      pattern: POST.*405
---

<objective>
Fix documentation inconsistencies and HTTP 405 error handling. These are independent doc fixes and a targeted diagnostic enhancement that don't block other work.
</objective>

<context>
@.planning/phases/06-setup-cli-diagnostics-consistency/06-CONTEXT.md
@.planning/ROADMAP.md
@.planning/REQUIREMENTS.md
@.planning/STATE.md

From 06-CONTEXT.md (key locked decisions):
- D-02: `command/ld-deep.md` lines 170, 194 must use `ld_deep_script` instead of `literature_script`
- D-16: `python -m paperforge` is the documented fallback when `paperforge` not registered
- D-17: AGENTS.md, INSTALLATION.md, and command docs must mention this fallback explicitly
- D-10-D-12: Doctor L2 must distinguish HTTP 405 "Method Not Allowed" from other errors
</context>

<tasks>

<task type="auto">
  <name>Task 1: Fix ld-deep.md field name (SETUP-05)</name>
  <files>command/ld-deep.md</files>
  <read_first>
    - command/ld-deep.md
    - paperforge/config.py (lines 276-293 for output_keys)
  </read_first>
  <action>
    In `command/ld-deep.md`, find ALL occurrences of `literature_script` and replace with `ld_deep_script`.

    Specifically check and fix:
    - Line ~170: `literature_script` -> `ld_deep_script`
    - Line ~194: `literature_script` -> `ld_deep_script`

    Do NOT change `worker_script` - that field name is correct per D-03.
  </action>
  <verify>
    <automated>grep -n "literature_script" command/ld-deep.md && echo "FAIL: still has literature_script" || echo "PASS: ld_deep_script only"</automated>
  </verify>
  <done>
    command/ld-deep.md uses `ld_deep_script` field name consistently (matching paperforge paths --json output)
  </done>
  <acceptance_criteria>
    - grep "literature_script" command/ld-deep.md returns no results
    - grep "ld_deep_script" command/ld-deep.md returns >= 2 results (lines 170, 194)
    - Context: D-02, D-03 from CONTEXT.md
  </acceptance_criteria>
</task>

<task type="auto">
  <name>Task 2: Add fallback command to AGENTS.md and INSTALLATION.md (SETUP-03)</name>
  <files>
    - AGENTS.md
    - docs/INSTALLATION.md
  </files>
  <read_first>
    - AGENTS.md
    - docs/INSTALLATION.md
  </read_first>
  <action>
    In both AGENTS.md and docs/INSTALLATION.md, add explicit mention of the fallback command `python -m paperforge`.

    For AGENTS.md:
    - Find the section with "常用命令速查" or command reference
    - Add note: "如果 paperforge 命令未注册，可使用: python -m paperforge"

    For docs/INSTALLATION.md:
    - Find the section about running paperforge after installation
    - Add note about the fallback command

    Use the exact string: "python -m paperforge" (with backticks for code formatting).
  </action>
  <verify>
    <automated>grep -c "python -m paperforge" AGENTS.md docs/INSTALLATION.md | head -2</automated>
  </verify>
  <done>
    Both AGENTS.md and INSTALLATION.md mention `python -m paperforge` as fallback
  </done>
  <acceptance_criteria>
    - grep finds "python -m paperforge" in AGENTS.md (at least 1 occurrence)
    - grep finds "python -m paperforge" in docs/INSTALLATION.md (at least 1 occurrence)
    - Context: D-16, D-17 from CONTEXT.md
  </acceptance_criteria>
</task>

<task type="auto">
  <name>Task 3: Add HTTP 405 detection in ocr_diagnostics.py L2 (DIAG-04)</name>
  <files>paperforge/ocr_diagnostics.py</files>
  <read_first>
    - paperforge/ocr_diagnostics.py (lines 44-77 for L2 check, lines 64-69 for current error handling)
  </read_first>
  <action>
    In `paperforge/ocr_diagnostics.py`, modify the L2 URL check to detect HTTP 405 "Method Not Allowed" and provide an actionable message.

    Current code (approx lines 64-69) catches HTTPError but doesn't distinguish 405:
    ```python
    except requests.HTTPError as e:
        issues.append(f"HTTP error: {e}")
    ```

    Replace with 405-specific handling:
    ```python
    except requests.HTTPError as e:
        if e.response.status_code == 405:
            issues.append(
                "URL returned 405 Method Not Allowed — "
                "PaddleOCR endpoint may require GET for probing but POST for OCR jobs. "
                "Check if your API endpoint supports both methods."
            )
        else:
            issues.append(f"HTTP error: {e}")
    ```

    Also update the docstring for the L2 check function to mention 405 handling.
  </action>
  <verify>
    <automated>grep -n "405 Method Not Allowed" paperforge/ocr_diagnostics.py && echo "PASS: 405 handling found"</automated>
  </verify>
  <done>
    OCR diagnostics L2 check distinguishes HTTP 405 from other HTTP errors with actionable fix suggestion
  </done>
  <acceptance_criteria>
    - grep finds "405 Method Not Allowed" in ocr_diagnostics.py
    - grep finds "POST for OCR jobs" or similar actionable message in ocr_diagnostics.py
    - Context: D-10, D-11, D-12 from CONTEXT.md
  </acceptance_criteria>
</task>

</tasks>

<verification>
- command/ld-deep.md uses `ld_deep_script` (not `literature_script`)
- AGENTS.md and docs/INSTALLATION.md mention fallback command
- ocr_diagnostics.py has HTTP 405 specific handling
</verification>

<success_criteria>
- SETUP-03: Fallback command documented in AGENTS.md and INSTALLATION.md
- SETUP-05: ld-deep.md uses correct field name `ld_deep_script`
- DIAG-04: Doctor distinguishes HTTP 405 with actionable message
</success_criteria>

<output>
After completion, create `.planning/phases/06-setup-cli-diagnostics-consistency/06-01-SUMMARY.md`
</output>
