lllin000_PaperForge/docs/MIGRATION-v1.2.md

Migration Guide: v1.1 to v1.2

This guide covers all breaking changes when upgrading PaperForge from v1.1 to v1.2.

Who should read this: Anyone upgrading from v1.1 — whether you installed via pip install paperforge-lite, cloned the repo, or use custom scripts referencing the old package or command names.

Estimated time: 5-10 minutes to follow the steps, plus time to update any custom scripts or templates.

---

What's New in v1.2

v1.2 is a systematization release. The core functionality is unchanged — Zotero sync, OCR, deep reading, and note generation all work the same way — but the command interface has been unified to reduce confusion and simplify the mental model.

Key improvements:

• Unified CLI commands: paperforge sync replaces selection-sync and index-refresh; paperforge ocr replaces ocr run and ocr doctor. Fewer commands to remember.
• Unified Agent namespace: All Agent commands now use /pf-* (/pf-deep, /pf-paper, /pf-ocr, etc.), replacing the fragmented /LD-* and /lp-* prefixes from v1.1.
• Package rename: The Python package is now paperforge (not paperforge_lite), matching the CLI command name.
• Shared command modules: CLI and Agent commands now share the same implementation in paperforge/commands/, reducing code duplication and making the system easier to extend (see ARCHITECTURE.md for details).

Backward compatibility note: v1.2 still accepts the old CLI command names (selection-sync, index-refresh, ocr run) as aliases, so existing scripts will not break immediately. However, these aliases are deprecated and may be removed in v1.3. Agent commands (/LD-*, /lp-*) are not backward compatible — your Agent platform must use the new /pf-* namespace.

---

Breaking Changes Summary

Change	Old (v1.1)	New (v1.2)	Impact
Package name	paperforge_lite	paperforge	pip uninstall + reinstall required
CLI sync (full)	paperforge selection-sync then paperforge index-refresh	paperforge sync	Single command; old names still work as aliases
CLI sync (selection only)	paperforge selection-sync	paperforge sync --selection	Old name still works as alias
CLI sync (index only)	paperforge index-refresh	paperforge sync --index	Old name still works as alias
CLI OCR (run)	paperforge ocr run	paperforge ocr	Old name still works as alias
CLI OCR (diagnose)	paperforge ocr doctor	paperforge ocr --diagnose	Old name still works as alias
Agent deep reading	/LD-deep <key>	/pf-deep <key>	Not backward compatible
Agent paper summary	/LD-paper <key>	/pf-paper <key>	Not backward compatible
Agent OCR	/lp-ocr	/pf-ocr	Not backward compatible
Agent sync	/lp-selection-sync, /lp-index-refresh	/pf-sync	Not backward compatible
Agent status	/lp-status	/pf-status	Not backward compatible
Python import	from paperforge_lite.cli import main	from paperforge.cli import main	Update all custom scripts
Module import	from paperforge_lite.config import load_config	from paperforge.config import load_config	Update all custom scripts

---

Detailed Breaking Changes

1. Package Rename: paperforge_lite -> paperforge

The Python package installed by pip has been renamed to match the CLI command name.

What you need to do:

• Uninstall the old package: pip uninstall paperforge-lite
• Install the new package: pip install -e . (from the repo root) or pip install paperforge

Why this changed: Having paperforge_lite as the Python package but paperforge as the CLI command was confusing. Now they match.

2. CLI Commands Unified

In v1.1, syncing required two separate commands:

paperforge selection-sync   # Create library-records
paperforge index-refresh    # Generate formal notes

In v1.2, these are unified under paperforge sync:

paperforge sync             # Runs both selection and index
paperforge sync --selection # Only selection-sync
paperforge sync --index     # Only index-refresh

Similarly, OCR commands were unified:

# v1.1
paperforge ocr run
paperforge ocr doctor

# v1.2
paperforge ocr
paperforge ocr --diagnose

Backward compatibility: The old command names (selection-sync, index-refresh, ocr run, ocr doctor) still work in v1.2 as internal aliases, but they are deprecated. Update your scripts and muscle memory to the new names.

3. Agent Commands Unified to /pf-*

All Agent commands now use the /pf-* (PaperForge) namespace:

Old Command	New Command	Purpose
/LD-deep <key>	/pf-deep <key>	Deep reading (Keshav three-pass)
/LD-paper <key>	/pf-paper <key>	Quick paper summary
/lp-ocr	/pf-ocr	Run OCR on marked papers
/lp-selection-sync	/pf-sync	Sync Zotero to library-records
/lp-index-refresh	(part of /pf-sync)	Generate formal notes
/lp-status	/pf-status	Show system status

No backward compatibility: Your Agent platform (OpenCode, Codex, Claude Code, etc.) must be configured to use the new command names. The old /LD-* and /lp-* prefixes will not be recognized.

---

Migration Steps

Follow these steps in order. Each step is copy-pasteable.

Step 1: Backup Your Vault

Warning

Always back up your data before upgrading. While v1.2 does not modify your notes or library-records automatically, it's good practice.

# Option A: Copy the entire vault
cp -r "你的Vault路径" "你的Vault路径-backup-$(date +%Y%m%d)"

# Option B: If using git, commit current state
cd "你的Vault路径"
git add -A
git commit -m "backup before v1.2 upgrade"

At minimum, back up these directories:

• <resources_dir>/ — your literature notes and library-records
• <system_dir>/PaperForge/ocr/ — OCR results (can be regenerated, but takes time)
• .env — your API keys

Step 2: Uninstall the Old Package

pip uninstall paperforge-lite

If you see WARNING: Skipping paperforge-lite as it is not installed, that's fine — you may have installed it in a different environment.

Step 3: Install the New Package

If installing from the repo (recommended for development/customization):

cd "你的Vault路径"
pip install -e .

If installing from PyPI (when available):

pip install paperforge

Step 4: Verify Installation

# Should show the new unified help output
python -m paperforge --help

# Verify the package name changed
python -c "from paperforge.cli import main; print('OK: import works')"

Expected output for --help:

usage: paperforge [-h] [--version] {sync,ocr,deep-reading,repair,status,doctor} ...

PaperForge Lite v1.2 — Literature workflow for Zotero + Obsidian

positional arguments:
  {sync,ocr,deep-reading,repair,status,doctor}
    sync                Sync Zotero library and generate notes
    ocr                 Run OCR on marked PDFs
    ...

Step 5: Update Scripts and Aliases

Search your system for references to old commands and update them:

# Find old command references in your shell history, aliases, scripts
grep -r "paperforge selection-sync" ~/scripts/ ~/.bashrc ~/.zshrc 2>/dev/null || true
grep -r "paperforge index-refresh" ~/scripts/ ~/.bashrc ~/.zshrc 2>/dev/null || true
grep -r "paperforge ocr run" ~/scripts/ ~/.bashrc ~/.zshrc 2>/dev/null || true

# Find old Python imports
grep -r "from paperforge_lite" ~/scripts/ 2>/dev/null || true

Update checklist:

• Shell aliases in .bashrc, .zshrc, or .bash_profile
• Custom scripts in ~/scripts/ or your vault
• Makefile targets
• CI/CD pipeline scripts
• Obsidian Templater or Dataview scripts that invoke CLI commands

Example updates:

# Old alias
alias pfs='paperforge selection-sync && paperforge index-refresh'

# New alias
alias pfs='paperforge sync'

# Old script line
python -m paperforge_lite.cli selection-sync

# New script line
python -m paperforge sync

Step 6: Update Obsidian Notes and Templates

If any of your Obsidian notes, templates, or Dataview queries reference old command names, update them:

Common places to check:

• Templater templates that insert command examples
• DataviewJS scripts that call dv.view() with CLI commands
• Documentation notes in your vault
• Checklists or SOP notes for literature workflow

Old references to search for:

/LD-deep
/LD-paper
/lp-ocr
/lp-selection-sync
/lp-index-refresh
/lp-status
paperforge selection-sync
paperforge index-refresh
paperforge ocr run
paperforge ocr doctor
paperforge_lite

Tip: Use Obsidian's global search (Ctrl+Shift+F or Cmd+Shift+F) to search for these strings across your vault.

Step 7: Verify Sync Works

Run a dry-run sync to confirm everything is wired correctly:

paperforge sync --dry-run

Expected behavior:

• No files are modified
• You see a preview of what would happen (new items detected, records that would be created)
• No import errors or path resolution errors

If the dry-run succeeds, run the real sync:

paperforge sync

Then verify:

1. New library-records are created in <resources_dir>/<control_dir>/library-records/
2. Formal notes are generated in <resources_dir>/<literature_dir>/
3. Existing notes and records are not corrupted

---

Import Path Changes

If you have custom Python scripts that import from paperforge_lite, update the import paths:

CLI Main Entry Point

# v1.1
from paperforge_lite.cli import main

# v1.2
from paperforge.cli import main

Configuration

# v1.1
from paperforge_lite.config import load_config, load_vault_config, paperforge_paths

# v1.2
from paperforge.config import load_config, load_vault_config, paperforge_paths

Command Modules (Advanced)

# v1.1 — commands were inline in cli.py or literature_pipeline.py
from paperforge_lite.cli import run_selection_sync

# v1.2 — commands are in shared modules
from paperforge.commands.sync import sync
from paperforge.commands.ocr import ocr
from paperforge.commands.deep import deep_reading_queue
from paperforge.commands.status import show_status

Script Invocation

# v1.1
import subprocess
subprocess.run(["python", "-m", "paperforge_lite", "selection-sync"])

# v1.2
import subprocess
subprocess.run(["python", "-m", "paperforge", "sync", "--selection"])

---

Rollback Instructions

If something goes wrong after upgrading to v1.2, you can downgrade to v1.1.

Option A: Rollback via Git (Recommended if you cloned the repo)

cd "你的Vault路径"

# Check out the v1.1 tag or branch
git checkout v1.1
# OR
git checkout <commit-hash-of-v1.1>

# Reinstall the old package
pip uninstall paperforge
pip install -e .

Option B: Rollback via PyPI (If installed from PyPI)

# Uninstall v1.2
pip uninstall paperforge

# Install the last v1.1 release
pip install paperforge-lite==1.1.x

Replace 1.1.x with the specific version you were using.

Option C: Quick Restore from Backup

If you created a backup in Step 1:

# Remove the upgraded vault
rm -rf "你的Vault路径"

# Restore from backup
cp -r "你的Vault路径-backup-YYYYMMDD" "你的Vault路径"

# Reinstall v1.1 package
pip uninstall paperforge
pip install paperforge-lite==1.1.x

What to Watch Out For

State compatibility: v1.2 does not change the format of library-records, formal notes, or OCR output. If you downgrade to v1.1 after running v1.2:

• Your library-records will still work (frontmatter format unchanged)
• Your formal notes will still work
• Your OCR output will still work
• Exception: If you used new v1.2 features (e.g., paperforge repair), the v1.1 scripts may not recognize new fields. These fields are harmless — v1.1 will ignore them.

Agent commands: If you downgraded the package but your Agent platform still has /pf-* commands configured, those commands will fail. Revert your Agent configuration to use /LD-deep, /LD-paper, etc.

---

FAQ

Q: Do I need to reconfigure my vault?

A: No. paperforge.json, .env, directory structure, and all your data remain compatible. The only changes are command names and the Python package name.

Q: Will my existing notes break?

A: No. v1.2 does not modify existing notes or library-records during sync unless you explicitly run paperforge sync and new items are detected. Existing notes keep their frontmatter, content, and ## 精读 sections unchanged.

Q: Can I use both old and new commands at the same time?

A: For CLI commands: yes, temporarily. v1.2 accepts selection-sync, index-refresh, and ocr run as deprecated aliases. However, these aliases may be removed in v1.3, so update your habits and scripts.

For Agent commands: no. /LD-deep, /LD-paper, /lp-* are not recognized in v1.2. You must use /pf-deep, /pf-paper, /pf-*.

Q: What about my custom scripts that import paperforge_lite?

A: You must update the import paths. paperforge_lite no longer exists after you uninstall it. Search your scripts for from paperforge_lite and import paperforge_lite and replace with paperforge.

Q: The sync command seems slower — is this normal?

A: paperforge sync (full) runs both selection-sync and index-refresh sequentially. If you previously ran them separately and only ran one at a time, the full sync will take longer because it does more work. Use paperforge sync --selection or paperforge sync --index if you only need one phase.

If it's significantly slower than running the old commands back-to-back, check:

1. Are there many new items in Zotero? First sync after upgrade may take longer.
2. Is your vault on a slow drive (network drive, spinning disk)?
3. Run with --verbose to see per-step timing: paperforge sync --verbose

Q: How do I update my Obsidian templates?

A: If your templates contain command examples (e.g., in a "Literature Workflow" template), update the command references:

<!-- Old -->
1. Run `paperforge selection-sync`
2. Run `paperforge index-refresh`
3. Run `/LD-deep {{zotero_key}}`

<!-- New -->
1. Run `paperforge sync`
2. Run `/pf-deep {{zotero_key}}`

Use Obsidian's global search (Ctrl+Shift+F) to find old command names in your templates.

Q: I get ModuleNotFoundError: No module named 'paperforge_lite' after upgrading.

A: You have a script, alias, or Obsidian plugin still referencing the old package name. Search for paperforge_lite in:

• Your shell aliases (~/.bashrc, ~/.zshrc)
• Custom Python scripts
• Obsidian Templater or DataviewJS scripts
• Systemd services or cron jobs

Replace all occurrences with paperforge.

Q: Do I need to update my .opencode/skills/ or .opencode/command/ files?

A: Yes, if you manually copied or symlinked the Agent command files. The v1.2 repository includes updated command/pf-*.md files and updated skill scripts. Re-copy or re-symlink them from the v1.2 repo:

# If you previously symlinked:
ln -sf "$(pwd)/command/pf-deep.md" .opencode/command/pf-deep.md
ln -sf "$(pwd)/command/pf-paper.md" .opencode/command/pf-paper.md
# ... etc for all 5 command files

Also update the skill script if you symlinked it:

ln -sf "$(pwd)/.agents/skills/literature-qa/scripts/ld_deep.py" .opencode/skills/literature-qa/scripts/ld_deep.py

Q: Will v1.1 command aliases be removed?

A: They are deprecated in v1.2 and may be removed in v1.3. There is no set timeline, but the recommendation is to migrate your scripts and documentation to the new command names as soon as convenient.

---

Quick Reference Card

Print this and keep it handy:

+------------------+---------------------------+---------------------------+
| Task             | Old (v1.1)                | New (v1.2)                |
+------------------+---------------------------+---------------------------+
| Full sync        | selection-sync +          | paperforge sync           |
|                  | index-refresh             |                           |
| Selection only   | paperforge selection-sync | paperforge sync --selection|
| Index only       | paperforge index-refresh  | paperforge sync --index   |
| Run OCR          | paperforge ocr run        | paperforge ocr            |
| Diagnose OCR     | paperforge ocr doctor     | paperforge ocr --diagnose |
| Deep reading     | /LD-deep <key>            | /pf-deep <key>            |
| Paper summary    | /LD-paper <key>           | /pf-paper <key>           |
| Agent OCR        | /lp-ocr                   | /pf-ocr                   |
| Agent sync       | /lp-selection-sync        | /pf-sync                  |
| Agent status     | /lp-status                | /pf-status                |
| Python package   | paperforge_lite           | paperforge                |
+------------------+---------------------------+---------------------------+

---

Need Help?

• Architecture details: See ARCHITECTURE.md
• Command reference: See COMMANDS.md
• Installation guide: See INSTALLATION.md
• User guide: See AGENTS.md
• Report issues: Open an issue with the tag migration-v1.2

---

PaperForge Lite | Migration Guide | v1.1 -> v1.2