Skip to content

docs: correct CLI quickstarts and warn before overwriting document formats - #15

Open
kiku-jw wants to merge 3 commits into
mainfrom
docs/accurate-cli-safety-2026-09-18
Open

kiku-jw wants to merge 3 commits into
mainfrom
docs/accurate-cli-safety-2026-09-18

Conversation

@kiku-jw

@kiku-jw kiku-jw commented Sep 18, 2026

Copy link
Copy Markdown
Member

Why this takes priority over more promotional copy

Source inspection found three mismatches between documented CLI examples and tool.py:

  1. main() requires Path.exists() before calling process_file(), so normal - stdin invocation is rejected even though process_file() contains a stdin branch.
  2. --stdout prints progress, separators and final statistics to the same stream as cleaned text.
  3. Normal processing writes UTF-8 text back to the original path, including a DOCX/PDF input path. A backup is not format-preserving output and repeated runs can overwrite an earlier backup.

Changes

  • Describe the browser's optional AI mode separately from the rule-based Python CLI and state that DOCX/PDF support is text extraction.
  • Make installation examples start with --dry-run on an existing file.
  • Remove the non-working raw-PDF stdin recipes.
  • Explain stdout contamination and the risk of in-place DOCX/PDF cleaning before showing commands.
  • Align README.md, docs/wiki/Home.md and docs/wiki/Usage.md so source documentation does not repeat contradictory recipes.

Verification

Read the current tool.py PDF/DOCX/text readers and the complete process_file I/O, backup, logging and main-dispatch sections; read the repository's contribution guide and all three changed documentation files. Examples use existing flags and filenames rather than claiming new support. No application code, cleaning policy, dependency or release configuration is changed.

Not a runtime fix. No Python CLI suite, browser suite, actual document conversion or installed Homebrew artifact was executed/verified in this environment. The separate GitHub Wiki repository is not modified by editing its source copies here.

Follow-up functional acceptance

A separate tested CLI change should prove: stdin text reaches processing; PDF bytes are not implicitly treated as text; stdout contains only the intended payload; DOCX/PDF originals cannot be overwritten accidentally; and dry-run/backup/undo behavior remains correct. This documentation PR deliberately does not claim those defects are fixed.

No merge, deployment, wiki publication or auto-merge is requested.

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant