---
phase: 01-config-and-command-foundation
plan: 04
type: execute
wave: 4
depends_on:
  - 02
  - 03
files_modified:
  - command/lp-status.md
  - command/lp-selection-sync.md
  - command/lp-index-refresh.md
  - command/lp-ocr.md
  - command/ld-deep.md
  - command/ld-paper.md
  - README.md
  - docs/INSTALLATION.md
  - docs/setup-guide.md
  - setup_wizard.py
  - tests/test_command_docs.py
autonomous: true
requirements:
  - CONF-03
  - CMD-01
  - CMD-02
  - CMD-03
must_haves:
  truths:
    - "User-facing command docs show stable `paperforge ...` commands instead of requiring `<system_dir>` substitution."
    - "Legacy direct worker invocation remains documented as a fallback, not as the primary path."
    - "Setup-generated command guidance points users to `paperforge paths`, `paperforge status`, `paperforge ocr run`, and `paperforge deep-reading`."
  artifacts:
    - path: "command/lp-status.md"
      provides: "Stable status command doc"
    - path: "command/lp-selection-sync.md"
      provides: "Stable selection sync command doc"
    - path: "command/lp-index-refresh.md"
      provides: "Stable index refresh command doc"
    - path: "command/lp-ocr.md"
      provides: "Stable OCR run command doc"
    - path: "command/ld-deep.md"
      provides: "Agent deep-reading command doc with resolved-path guidance"
    - path: "tests/test_command_docs.py"
      provides: "Placeholder-free command documentation checks"
  key_links:
    - from: "command/*.md"
      to: "paperforge.cli"
      via: "documented stable commands"
      pattern: "paperforge status|paperforge ocr run|paperforge deep-reading"
    - from: "setup_wizard.py"
      to: "paperforge command docs"
      via: "generated next commands"
      pattern: "paperforge paths"
---

<objective>
Update command and setup-facing documentation to use the new stable command surface.

Purpose: Phase 1 is not complete if users still see unresolved worker path tokens as the main way to run PaperForge.
Output: Updated command docs, setup/readme command examples, and tests that prevent unresolved-token regressions in user-run commands.
</objective>

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

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/REQUIREMENTS.md
@.planning/phases/01-config-and-command-foundation/01-CONTEXT.md
@.planning/phases/01-config-and-command-foundation/01-RESEARCH.md
@paperforge/cli.py
@command/lp-status.md
@command/lp-selection-sync.md
@command/lp-index-refresh.md
@command/lp-ocr.md
@command/ld-deep.md
@command/ld-paper.md
@README.md
@docs/INSTALLATION.md
@docs/setup-guide.md
@setup_wizard.py
</context>

<tasks>

<task type="auto" tdd="true">
  <name>Task 1: Add docs regression tests for stable commands</name>
  <files>tests/test_command_docs.py</files>
  <read_first>
    - `command/lp-status.md`
    - `command/lp-selection-sync.md`
    - `command/lp-index-refresh.md`
    - `command/lp-ocr.md`
    - `command/ld-deep.md`
    - `command/ld-paper.md`
    - `README.md`
    - `docs/INSTALLATION.md`
    - `docs/setup-guide.md`
    - `setup_wizard.py`
  </read_first>
  <behavior>
    - Command docs for `/lp-status`, `/lp-selection-sync`, `/lp-index-refresh`, and `/lp-ocr` contain `paperforge status`, `paperforge selection-sync`, `paperforge index-refresh`, and `paperforge ocr run`.
    - Those four command docs do not contain `python <system_dir>/PaperForge/worker/scripts/literature_pipeline.py`.
    - `README.md`, `docs/INSTALLATION.md`, and `docs/setup-guide.md` contain at least one stable `paperforge paths` or `paperforge status` example.
    - `command/ld-deep.md` points queue preflight to `paperforge deep-reading` and script path discovery to `paperforge paths --json`.
  </behavior>
  <action>Create `tests/test_command_docs.py` with pytest tests that read the listed markdown and Python files as UTF-8. Assert the exact stable commands above are present. Limit unresolved-token rejection to user-run command examples; do not fail on explanatory tokens inside architecture diagrams or frontmatter field examples in `AGENTS.md`, because this phase must not rewrite the user-facing guide wholesale.</action>
  <verify>
    <automated>python -m pytest tests/test_command_docs.py -q</automated>
  </verify>
  <acceptance_criteria>
    - `rg -n "paperforge status|paperforge ocr run|paperforge paths --json|python <system_dir>" tests/test_command_docs.py` shows stable command assertions and scoped unresolved-token checks.
    - `python -m pytest tests/test_command_docs.py -q` passes after Task 2.
  </acceptance_criteria>
  <done>Docs tests encode CMD-03 without forcing full onboarding rewrite deferred to Phase 4.</done>
</task>

<task type="auto">
  <name>Task 2: Replace unresolved path-token command examples with stable launcher commands</name>
  <files>command/lp-status.md, command/lp-selection-sync.md, command/lp-index-refresh.md, command/lp-ocr.md, command/ld-deep.md, command/ld-paper.md, README.md, docs/INSTALLATION.md, docs/setup-guide.md, setup_wizard.py, tests/test_command_docs.py</files>
  <read_first>
    - `tests/test_command_docs.py`
    - `paperforge/cli.py`
    - `command/lp-status.md`
    - `command/lp-selection-sync.md`
    - `command/lp-index-refresh.md`
    - `command/lp-ocr.md`
    - `command/ld-deep.md`
    - `command/ld-paper.md`
    - `README.md`
    - `docs/INSTALLATION.md`
    - `docs/setup-guide.md`
    - `setup_wizard.py`
  </read_first>
  <action>Update `/lp-*` command docs to use exactly these primary commands: `paperforge status`, `paperforge selection-sync`, `paperforge index-refresh`, and `paperforge ocr run`. In `README.md`, replace the primary quick-start worker commands with `paperforge selection-sync`, `paperforge index-refresh`, `paperforge ocr run`, `paperforge deep-reading`, and `paperforge status`; keep one clearly labeled legacy fallback example `python <resolved-worker-script> --vault . status` only if the text tells users to obtain the resolved path from `paperforge paths`. In `docs/INSTALLATION.md` and `docs/setup-guide.md`, add `python -m pip install -e .`, `paperforge paths`, and `paperforge status` as the command verification path. In `command/ld-deep.md` and `command/ld-paper.md`, replace runtime unresolved path-token instructions with `paperforge paths --json` for resolving `ld_deep_script`, `ocr`, and `literature` paths. In `setup_wizard.py`, change generated next-step command text from `python {system_dir}/PaperForge/worker/scripts/literature_pipeline.py --vault .` to stable `paperforge ...` commands, while still mentioning legacy direct invocation is supported.</action>
  <verify>
    <automated>python -m pytest tests/test_command_docs.py -q</automated>
    <automated>python -m paperforge --vault . paths --json</automated>
  </verify>
  <acceptance_criteria>
    - `rg -n "paperforge status|paperforge selection-sync|paperforge index-refresh|paperforge ocr run|paperforge deep-reading|paperforge paths --json" command README.md docs setup_wizard.py` finds stable command examples.
    - `rg -n "python <system_dir>/PaperForge/worker/scripts/literature_pipeline.py" command README.md docs` returns no matches.
    - `python -m pytest tests/test_command_docs.py -q` passes.
  </acceptance_criteria>
  <done>User-run docs now prefer stable launcher commands and avoid unresolved worker path tokens.</done>
</task>

</tasks>

<threat_model>
## Trust Boundaries

| Boundary | Description |
|----------|-------------|
| documentation -> user shell | Users copy commands from markdown into PowerShell or Bash. |
| setup wizard output -> user shell | Generated next steps become executable user commands. |

## STRIDE Threat Register

| Threat ID | Category | Component | Disposition | Mitigation Plan |
|-----------|----------|-----------|-------------|-----------------|
| T-01-07 | Spoofing | command docs | mitigate | Document only local `paperforge`/`python -m paperforge` commands; do not add curl/download execution snippets. |
| T-01-08 | Tampering | setup-generated command text | mitigate | Keep commands static and parameterized by resolver behavior, not string-built absolute shell paths. |
</threat_model>

<verification>
Run `python -m pytest tests/test_command_docs.py -q` and `python -m paperforge --vault . paths --json`.
</verification>

<success_criteria>
Phase 1 command documentation is copy-pasteable with stable launcher commands, while legacy direct worker invocation remains supported and discoverable.
</success_criteria>

<output>
After completion, create `.planning/phases/01-config-and-command-foundation/01-config-and-command-foundation-04-SUMMARY.md`
</output>
