docs: fix staleness in README and GitHub Pages site#111
Merged
Conversation
Audit of README.md and the docs/ site against the real CLI surface (cmd/things/main.go) surfaced drift accumulated through v0.5.0: - README: document the today-view --include-completed flag and the --on/--from/--to date filters (all undocumented); correct the "combine freely with any view" heading, which is false for the date and completed filters. - commands tab: fix the add --project/--list example (--list overrides --project), correct the project-edit flag-set claim (partial overlap, no checklist/heading flags, adds --area), fix the open example (bare titles never resolve areas), add Shell completions and Version sections. - Scope the "every command speaks JSON" claim to read commands on the homepage, commands tab, and _config.yml (write commands ignore -j). - install: document RELEASE_BASE_URL (third env var) and replace the stale v0.1.0 version pin with a vX.Y.Z placeholder (also in install.sh).
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.
Audited
README.mdand the GitHub Pages site (docs/, → things.rlew.io) against the real CLI surface incmd/things/main.go. The CLI now has 17 commands; the docs had drifted, mostly around the v0.5.0 additions. 12 verified findings, all fixed.README
--include-completed(today-view UI-parity flag, added v0.5.0) — was undocumented.--on/--from/--todate filters — were entirely undocumented.today/upcoming/anytime/someday/deadlines/project) and--include-completedis today-only.Commands tab (
docs/_tabs/commands.md)add --project X --list Yexample —--listsilently overrides--project.project editmirrors the same flag set" — it's a partial overlap (no checklist/heading flags; adds--area/--area-id).open "Side projects"comment — a bare positional never resolves an area; areas need-a/--area.things completions bash|zsh|fish) and Version sections.Homepage / config
docs/index.md(×2),docs/_tabs/commands.md, anddocs/_config.yml.-jis a global flag but inert on write commands.Install
docs/_tabs/install.md: script reads three env vars, not two — documentedRELEASE_BASE_URL.VERSION=v0.1.0pin with avX.Y.Zplaceholder (in install.md and theinstall.shheader comment).Method
Generated via a multi-agent staleness audit: built an authoritative inventory from the kong wiring, audited each doc surface against it, and adversarially verified every finding against the source. The
abouttab and GitHub repo metadata (description/topics/homepage) were clean. Out of scope but noted:internal/skill/SKILL.mdmay carry parallel drift.