docs: fix stale command references, polish README to agent/10k-star-repo standard - #236
Merged
Merged
Conversation
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
…o standard README.md, SKILL.md, and SKILL-QUICK.md still documented the pre-#195 architecture — Quick Start and most workflow examples used commands that were dropped or absorbed into umbrellas over a year ago: `init`, `query`, `list`, `detect`, `serve`, `guard`, and bare `trace`/`impact`/`circular`/`dead-code`/`secrets` as standalone commands. Every one of these now either doesn't exist (verified: `codelens init .` -> "invalid choice: 'init'") or requires an umbrella prefix (`context --check trace`, `audit --check dead-code`, etc). An agent or new contributor following the README's own Quick Start would hit an argparse error on the very first command. Also fixed: MCP tool count claimed "55 tools" in one section and "12 Tools" in another (real count, verified: 12 = 6 static + 6 dynamic). `codelens` is an installed PyPI console script (editable install, confirmed pointing at this checkout) but every example used the legacy `python3 scripts/codelens.py` invocation instead. Every single command example in all three files was re-verified directly against the current CLI before being written down — none of this is copy-pasted from the old docs with names swapped. README.md additionally restructured for readability: badges, table of contents, a "replace grep with this" comparison up front, a "why CodeLens" table answering questions grep can't, and a single "gotcha" callout for the search pattern/workspace argument-order trap (the same one fixed in scripts/commands/search.py in the prior PR) instead of burying it in a giant command reference table. scripts/codelens.py: also fixed the --help description's hardcoded `python3 scripts/codelens.py --command-count` self-reference to say `codelens --command-count`, matching the same legacy-vs-installed inconsistency found in the docs.
|
This was referenced Jul 14, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #234 (the agent-tooling audit). While closing that out I noticed the primary documentation surface — README.md, SKILL.md, SKILL-QUICK.md — was still describing the pre-#195 command architecture. This directly undermines "CodeLens as an agent's tool": an agent or new contributor following the README's own Quick Start hits an argparse error on the very first command.
Verified broken examples (before this PR):
codelens init .→invalid choice: 'init'codelens detect .→invalid choice: 'detect'codelens trace foo .→invalid choice: 'trace'codelens serve/codelens guard→ don't exist (confirmed dropped, not just hidden)sync_command_count.py): 12 (6 static + 6 dynamic)python3 scripts/codelens.py— the installedcodelensPyPI console script (confirmed editable-install pointing at this exact checkout) was never mentioned as the primary UXChanges
searchpattern/workspace argument-order gotcha (instead of burying it), all examples re-verified against the live CLI.--helpdescription's self-reference (python3 scripts/codelens.py --command-count) fixed tocodelens --command-count.Every single command example across all three files was independently re-run against the current CLI before being written down — none of it is copy-pasted from the old docs with names find-and-replaced.
Test plan
sync_command_count.py --apply— still reports "in sync" after the rewrite (verified the exact regex patterns it checks still match the new wording where practical)pytest tests/test_command_count.py tests/test_version_consistency.py— 7/7 passpytest tests/test_cli.py -k "not FormatConflictRegression"— 36/36 pass (excluded 2 pre-existing subprocess-timeout tests, unrelated, tracked in fix(ci): CodeLens CI/Quality Gate broken on main since #195 consolidation #235)--format graphml,--mode graphCypher query)