Make the docs and the demo data reachable from a pip install

[AlexisJanin]

The tutorial and the example are easy to find with a source checkout (the repo is on disk) and with the standalone application (assemble_bundle.py copies both in next to the executable). A pip install is the third channel, and it has neither: the wheel packages src/ and nothing else. This branch closes that gap.

What a pip user had before this

• The PyPI project page is their only entry point, and its description is the README — whose six links were all repo-relative. PyPI resolves those against pypi.org, so every one of them 404'd and the demo GIF did not render.
• The app itself offered no link to the tutorial.
• Quickstart step 3 told them to point at demo_database/demo_patient/, a folder they do not have, with no alternative named.

Four commits

1. Make the documentation reachable — [project.urls] gains Documentation, Changelog and Issues (Warehouse renders these as the project page's sidebar); every README link is absolute; a grey 📖 Docs pill joins the version badge and settings gear in the top-right stack. A test fails on any relative link reintroduced into the README.

2. Publish the example dataset as a release asset — an example job in build.yml zips example/ into clinical-scope-example.zip and attaches it to the same draft release as the executables. The tree is staged through a filtered copy first, so the per-run parquet cache and macOS metadata stay out: 2.2 MB rather than the 10 MB an unfiltered archive would carry. example/ itself does not move — the bundle keeps its own copy and the test fixtures keep their paths.

3. clinical-scope --demo — downloads that asset into ~/.clinical_scope/example/ and prints the data-folder and config paths the app asks for. clinical-scope -h now describes it, and --version prints the installed version.

4. Document it — a Trying the demo section in the README and Trying the Demo Dataset in the user guide, covering both the bundled copy and the download. The guide is where the new Docs link lands, so that is where a pip user discovers the demo is a download away.

Two design notes

The parser lives in a new cli.py, not in core_api.main. core_api.py stays the PyInstaller entry point and must keep ignoring sys.argv — macOS hands a Finder-launched bundle a -psn_… argument that argparse would reject. Keeping it separate also means --help and --demo never build the Dash layout, which happens at import time.

Fetch rather than ship in the wheel. Bundling the demo as package data would force example/ under src/clinical_scope/, breaking assemble_bundle.py and the test fixtures, and would add ~6 MB to every install for the majority of users who bring their own ICU data. The download is bounded in size, staged in a sibling folder so an interrupted run cannot leave a half-filled demo behind, and refuses any archive member that would write outside its destination.

Testing

• tests/unit/test_demo_data.py — 16 tests covering the happy path, idempotency, --force, zip-slip, oversize, bad zip, and offline. No network: urlopen is replaced by a fake serving bytes built in the test.
• tests/unit/test_readme_links.py — guards the README against relative links.
• Verified by hand: the CI archive step builds a 2.23 MB zip with no cache or macOS leakage, and that real archive round-trips through the extractor to all nine datasource folders plus the config.

Known limitation

--demo cannot work until a release ships with the asset — releases/latest/download/clinical-scope-example.zip 404s today. Until then the command reports a readable message and exits 1 rather than raising. docs/RELEASING.md step 3 now includes checking that the asset is attached, and warns that renaming it breaks the command for every version already installed.

The in-app Docs link points at the online tutorial, so it is dead for a standalone-bundle user with no network, even though the PDF sits next to their executable. Left alone for now; say the word if that case is worth handling.

🤖 Generated with Claude Code

[AlexisJanin]

1 additional comment: i suggest to take this PR opportunity to also clarify the term tutorial vs user-guide. Most obvious conflict is the tutorial.md being transformed to user_guide.pdf

[AlexisJanin]

Review addressed

All fifteen threads answered inline. Two commits, split the way you asked.

tutorial vs user-guide — taken up, own commit

You were right that this PR was the moment. The document already disagreed with itself in three places: its own frontmatter title is "Clinical Scope -- User Guide", it builds to ClinicalScope_UserGuide.pdf, and README linked it as "the user guide" — while the file was tutorial.md and CLAUDE.md, CONTRIBUTING and the three skills all called it the tutorial. The filename was the odd one out, not the prose.

docs/user_guide/tutorial.md → docs/user_guide/user_guide.md, and every reference settled on "user guide": links, prose, build_pdf.sh, three skills, ADR-0008, and the test that reads the file by path. The rename commit is 30 lines changed and a content-identical move, so it reviews in one pass.

CHANGELOG.md deliberately still says "tutorial" — entries 56 and 57 describe what shipped in past releases, which is a historical record rather than an inconsistency. Shout if you'd rather they match.

One pushback worth your eyes

The cli.py naming thread — I kept cli.py over api.py and explained why, along with an honest answer to your "is it a workaround?" question. Short version: the macOS -psn_ constraint is real and load-bearing, but you correctly sensed something else, which is that core_api builds its layout at import time. The docstring now says the true reason instead of the flattering one.

Known limitations — one is new

The description's Known limitation section needs a second entry: the in-app Docs link now resolves to releases/latest/download/ClinicalScope_UserGuide.pdf, so like --demo, it 404s until a release ships carrying that asset. build.yml attaches it from now on, and RELEASING step 3 lists it among what to check on the draft.

The offline-bundle-user case I raised originally is unchanged: they have the PDF next to their executable but the link goes online regardless.

🤖 Generated with Claude Code