Repository navigation
docs: rewrite the README from the user's point of view for v3.0.0 - #97
Merged
Merged
Conversation
The README still described v2.3: its pitch covered gathering material and placing figures, while reading by paper type, Takeaways, Connections, and the vault-level skills went unmentioned. The usage example was an AI-generated image with garbled text and a note structure the product does not produce. Both READMEs now open with five selling points (one sentence per note, reading by paper type, accuracy, figures in the text, a vault that grows with you), then News for v3.0.0, a Quick Start with slash commands and update steps, what a note looks like, the four skills by what they offer, Notes You Can Trust with the regression and blind-evaluation numbers, optional enhancements with how to turn each one on, and troubleshooting phrased as what to ask the agent. Maintainer details (run_state.py paths, the canonical contract) move to Troubleshooting and Contributing. The animated demo GIF is a placeholder comment for now. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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
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
Both READMEs are rewritten for users ahead of v3.0.0. They stay section-for-section parallel (221 lines each).
Facts were checked against the repo: middle section names from
type_profiles.py, layout and properties fromobsidian-format.md, 34 corpus papers fromevals/expectations/, the evaluation numbers from the phase D acceptance run (6 papers, 12 blind comparisons, rubric out of 100), the Semantic Scholar variable from_metadata_sources.py, the update commands fromclaude plugin --help, and the Zotero setting from the Zotero 7 UI.Not in this PR: the animated demo GIF and removal of the now-unreferenced
assets/usage-example.png(assets PR), and CHANGELOG plus the 3.0.0 version bump (release PR).Evidence
After: no AI-generated example image; every section name, path, and number in the README traces to the repo.
python3 -m pytest -q -n auto: 1739 passed, 1 skipped (includes the README checks intest_contracts_consistency.py).python3 -m ruff check skills tests: clean.Merge Danger
Door: two-way
Docs only; revert restores the old README.
Blast Radius: docs
News links to the v3.0.0 release page, which 404s until the release is published. Users see the README only after develop merges into main at release time, so the timing lines up.
npx skills updatewas not run locally.🤖 Generated with Claude Code