Skip to content

docs: rewrite the README from the user's point of view for v3.0.0 - #97

Merged
917Dhj merged 1 commit into
developfrom
docs/readme-refresh
Nov 8, 2026
Merged

917Dhj merged 1 commit into
developfrom
docs/readme-refresh

Conversation

@917Dhj

@917Dhj 917Dhj commented Nov 8, 2026

Copy link
Copy Markdown
Owner

Summary

Both READMEs are rewritten for users ahead of v3.0.0. They stay section-for-section parallel (221 lines each).

  Title, tagline, hero
- 7 badges
+ 5 badges (drop static `status: stable` and `changelog`)
- 4 paragraphs + 4 questions + Zotero tip
+ 1 pain paragraph, 1 positioning paragraph, 5 selling points
+   one sentence per note · reads by paper type · accurate and complete
+   · figures/tables/formulas in the text · a vault that grows with you
  News
-   v2.3.0, two July 2026 items
+   v3.0.0 (type-specific reading), v3.0.0 (vault + new skills), v2.3.1 (Connector)
  Quick Start
+   Codex named explicitly · /deeppapernote · first-run questions · 4. Update
- Collect Papers from Your Browser          → moved into Optional Enhancements
- Why DeepPaperNote? (AI-generated example image + pain table)
+ What a Note Looks Like: opening / type-specific body / closing table,
+   collapsible vault layout and Bases properties, GIF placeholder comment
- Skills table
+ From Paper to Wiki: each skill by what it offers, with how to call it
- Quality Promise ("should…", frozen plan, draft bytes, run_state.py)
+ Notes You Can Trust: six user-facing guarantees + 34-paper corpus,
+   73.6 → 84.2 blind evaluation
- First-Run Preferences                     → folded into Quick Start step 3
  Optional Enhancements: one table, each row says how to turn it on
+ Troubleshooting: what to ask the agent (environment check, run status)
  Inspirations: + HKUSTDial/Supervisor-Skills
  Contributing: + test/lint commands, canonical-workflow line

Facts were checked against the repo: middle section names from type_profiles.py, layout and properties from obsidian-format.md, 34 corpus papers from evals/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 from claude 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

  • Before: News ended at v2.3.0; the usage example image showed garbled text ("Research furtherzedical papers::-no-preveralized…") under section names the product does not write.
    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 in test_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 update was not run locally.

🤖 Generated with Claude Code

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>
@917Dhj
917Dhj merged commit eafae2d into develop Nov 8, 2026
3 checks passed
@917Dhj
917Dhj deleted the docs/readme-refresh branch November 9, 2026 07:58
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