demolab-cli 2.2.0__tar.gz → 2.3.0__tar.gz

{demolab_cli-2.2.0 → demolab_cli-2.3.0}/AGENTS.md

@@ -1,8 +1,7 @@
 > **demolab lab** — before working here, run `uv run demolab docs` and follow what it
-> prints (the agent manual + runbook menu). In an ordinary lab where `demolab` is already
-> active, `demolab docs` is equivalent. Use `uvx demolab-cli docs` only when bootstrapping
-> a new lab with no project environment. A user message that is just a NAME in CAPS
-> (`HELP`, `LINT`, `DOCTOR`, …) is a command — the manual explains.
+> prints (the agent manual + runbook menu). Do not substitute `uvx`: this lab's project
+> environment is the source of truth. A user message that is just a NAME in CAPS (`HELP`,
+> `LINT`, `DOCTOR`, …) is a command — the manual explains.
 
 **This checkout is also the demolab-cli source repo** — the engine lives in `demolab_cli/`
 (build code, Typst templates, runbooks, guides, scaffold, and the manual `demolab docs`

{demolab_cli-2.2.0/demolab_cli/scaffold/root → demolab_cli-2.3.0}/CLAUDE.md

@@ -1,7 +1,7 @@
 Read [AGENTS.md](AGENTS.md) and follow it before doing anything else here.
 
 **Command reflex — applies before any other action.** A user message that is *only* a
-NAME in CAPS (SCREAMING-KEBAB) — `HELP`, `LINT`, `DOCTOR`, `NEXT`, `LITERATURE-SEARCH`, … —
+NAME in CAPS (SCREAMING-KEBAB) — `HELP`, `LINT`, `DOCTOR`, `LITERATURE-SEARCH`, … —
 *is* a command, not a topic to research. Your first move is to run `demolab docs <NAME>`
 (bare `demolab docs` for the menu + manual), read the file it prints, and follow it. Don't
 grep for it, don't guess, don't ask the user what they meant — the runbook says what to do.

{demolab_cli-2.2.0 → demolab_cli-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: demolab-cli
-Version: 2.2.0
+Version: 2.3.0
 Summary: Lab notebook for computational science: Python tools produce per-run artifacts; Typst publishes them as a web bundle, per-entry PDFs, and a book.
 Project-URL: Homepage, https://github.com/eoinmurray/demolab
 Project-URL: Changelog, https://github.com/eoinmurray/demolab/blob/main/demolab_cli/CHANGELOG.md
@@ -70,15 +70,10 @@ Open your lab in your agent and say a runbook's name — it follows that runbook
 | **TOUR** | guided walkthrough of the lab — what's here, what it found, where to start |
 | **MIGRATE-CODE** | bring an existing codebase in, one experiment at a time |
 | **FROM-JUPYTER** | launder a Jupyter notebook into a reproducible, seeded experiment |
-| **FROM-PAPER** | scaffold experiments to reproduce a paper's key result in your stack |
 | **MIGRATE-STACK** | write your tools in MATLAB / Julia / R / Octave instead of Python |
 | **EMBED-DOCS** | drop demolab into another project as a `docs/` site |
-| **NEXT** | read your whole arc and propose the next experiments worth running |
-| **GROUND-CLAIMS** | find the source sentences behind each citation |
 | **LINT** | check your writeups against the house style |
 | **DOCTOR** | audit the repo against the conventions |
-| **RED-TEAM** | adversarially check a result holds up before you publish it |
-| **STEELMAN** | build the strongest honest case for a result, so you don't under-sell it |
 | **UPDATE** | update the engine package, leaving your content untouched |
 
 ## How it works

{demolab_cli-2.2.0 → demolab_cli-2.3.0}/README.md

@@ -39,15 +39,10 @@ Open your lab in your agent and say a runbook's name — it follows that runbook
 | **TOUR** | guided walkthrough of the lab — what's here, what it found, where to start |
 | **MIGRATE-CODE** | bring an existing codebase in, one experiment at a time |
 | **FROM-JUPYTER** | launder a Jupyter notebook into a reproducible, seeded experiment |
-| **FROM-PAPER** | scaffold experiments to reproduce a paper's key result in your stack |
 | **MIGRATE-STACK** | write your tools in MATLAB / Julia / R / Octave instead of Python |
 | **EMBED-DOCS** | drop demolab into another project as a `docs/` site |
-| **NEXT** | read your whole arc and propose the next experiments worth running |
-| **GROUND-CLAIMS** | find the source sentences behind each citation |
 | **LINT** | check your writeups against the house style |
 | **DOCTOR** | audit the repo against the conventions |
-| **RED-TEAM** | adversarially check a result holds up before you publish it |
-| **STEELMAN** | build the strongest honest case for a result, so you don't under-sell it |
 | **UPDATE** | update the engine package, leaving your content untouched |
 
 ## How it works

{demolab_cli-2.2.0 → demolab_cli-2.3.0}/demolab_cli/AGENT.md

@@ -23,7 +23,7 @@ machine-managed staging. Full tree: `demolab docs STRUCTURE`.
 demolab is driven by the user typing a **name in CAPS** (SCREAMING-KEBAB):
 
 - **`HELP`** — present the menu at the bottom of this output, one line each.
-- **`<RUNBOOK>`** (e.g. `LINT`, `DOCTOR`, `NEXT`) — run `demolab docs <NAME>`, read the
+- **`<RUNBOOK>`** (e.g. `LINT`, `DOCTOR`, `TOUR`) — run `demolab docs <NAME>`, read the
   file it prints, then **start it** and drive it step by step: run a step, show the
   result, confirm before the next. Never dump the whole runbook at once.
 - **`<GUIDE>`** (e.g. `RULES`, `SLIDES`) — read it the same way, then **walk the user

{demolab_cli-2.2.0 → demolab_cli-2.3.0}/demolab_cli/CHANGELOG.md

@@ -13,6 +13,27 @@ the runbook shows the entries between your version and the latest.
 
 ## [Unreleased]
 
+## [2.3.0] — 2026-08-07
+
+### Added
+- **Optional collaborative inline annotations with Hypothesis.** Set `annotations: hypothesis`
+  lab-wide in `demolab.yaml` or `annotations: "hypothesis"` on one writing's `meta`; web readers
+  can highlight text and use Hypothesis threads and private groups, while PDFs remain unchanged.
+  The new `ar027` demo article documents the workflow and opts itself in as a live example.
+
+## [2.2.1] — 2026-08-07
+
+### Fixed
+- **Lab agent instructions no longer suggest the bootstrap-only `uvx` fallback.** Every
+  scaffolded lab now directs agents unambiguously to its project environment with
+  `uv run demolab docs`, preventing sessions from falsely claiming that `demolab` is not
+  on `PATH` and running a cached or released package instead.
+
+### Removed
+- **Retired five overlapping runbooks:** `FROM-PAPER`, `NEXT`, `GROUND-CLAIMS`, `RED-TEAM`, and
+  `STEELMAN`. Their command routing, onboarding references, demo documentation, and published demo
+  artifacts have been removed with them.
+
 ## [2.2.0] — 2026-08-07
 
 ### Added
@@ -326,7 +347,7 @@ the runbook shows the entries between your version and the latest.
   last night + queue the next pre-registered experiments), **NIGHT-SHIFT** (work the queue on a
   branch, open a PR whose description is the digest) — plus the **AUTORESEARCH-RULES** guide
   they cite. DOCTOR gains a one-plan-one-log / every-queued-entry-has-a-kill check; LINT exempts
-  the `log` from the prose rules; NEXT reads the `log`'s decision arc. Opt-in and additive:
+  the `log` from the prose rules. Opt-in and additive:
   nothing changes for a lab that doesn't create a `plan` article.
 - **Per-PR site previews (`deploy.yml` rewrite + new `preview.yml`).** `demolab deploy-setup` now
   installs two workflows. Production (`deploy.yml`) switched from the GitHub-Actions Pages flow
@@ -662,8 +683,8 @@ Initial versioned release — the engine after its foundational build-out.
   The demo lives in `demolab-engine/scaffold/` and doubles as the smoke-test fixture.
 - **One-line installers** — `install.sh` (macOS/Linux) and `install.ps1` (Windows), served from the
   project landing page at demolab.eoinmurray.info.
-- **14 agent runbooks** — getting-started, tour, migrate-code, from-jupyter, from-paper,
-  migrate-stack, embed-docs, next, ground-claims, lint, doctor, red-team, steelman, update — plus a
+- **Agent runbooks** — getting-started, tour, migrate-code, from-jupyter,
+  migrate-stack, embed-docs, lint, doctor, and update — plus a
   `HELP` index, each triggerable by bare name.
 - **Citations** — `#cite(...)` inline numbered cites + `#reference-list(...)` with DOI links, and
   Wikipedia-style hover popovers on the web (DOIs open in a new tab).

demolab_cli-2.3.0/demolab_cli/VERSION

@@ -0,0 +1 @@
+2.3.0

{demolab_cli-2.2.0 → demolab_cli-2.3.0}/demolab_cli/guides/AUTORESEARCH-RULES.md

@@ -237,9 +237,9 @@ non-compliant artifact can't ship even if the agent misses the rule.
   can't drift from what ran.
 - Pre-registration = **provenance** (RULES §4.7): the mandate's commit predates the results' commits.
 - Long runs use **staged runners** (RULES §7.5) so a night can re-enter compute without repeating it.
-- **NEXT** reads the night documents' records and digests (not just published results), so it
-  proposes from the decision arc; its suggestions are raw material a human may approve as
-  `queued` entries in **AUTORESEARCH**.
+- **AUTORESEARCH** reads the night documents' records and digests (not just published results),
+  so each review continues from the decision arc and may propose `queued` entries for human
+  approval.
 - **DOCTOR** checks program structure (each night document carries a mandate + record + digest,
   every `queued` entry has a `kill`, no AI-attribution trailer in commits or PR descriptions).
 - **LINT** applies the full prose rules to night documents, including the cold-read dimension.

{demolab_cli-2.2.0 → demolab_cli-2.3.0}/demolab_cli/guides/RULES.md

@@ -31,7 +31,7 @@ The concrete annotated file tree is in [`STRUCTURE.md`](STRUCTURE.md); this sect
 
 **3.2 — Machine-managed staging** (gitignored, owned by the CLI — never hand-edit): `.demolab/` at the lab root holds the few engine files Typst must read from inside the lab tree (`lib.typ`, the web assets, a `VERSION` stamp); every build refreshes it when the installed engine version changes. `temp/bundle/` holds the staged bundle root (`main.typ`) plus build scratch. Local edits to either are overwritten without warning — a customisation that seems to need them is a missing config knob (see 3.3, or propose it upstream).
 
-**3.3 — Your root overrides, optional** (root files the framework reads; never overwritten by updates): `demolab.yaml` (wordmark + PDF titles + collections — also the **lab marker**: the CLI finds the lab root by walking up to it, so don't delete it) and `HOUSESTYLE.local.md` (your house-style overrides, which extend or replace the default `HOUSESTYLE.md`; an agent reads it). Every key defaults ⇒ a minimal file is fine. The root stubs (`AGENTS.md`, `CLAUDE.md`, `README.md`, `pyproject.toml`, `.gitignore`, CI) are laid down once by `demolab init` and are yours from then on.
+**3.3 — Your root overrides, optional** (root files the framework reads; never overwritten by updates): `demolab.yaml` (wordmark + PDF titles + collections + optional web annotations — also the **lab marker**: the CLI finds the lab root by walking up to it, so don't delete it) and `HOUSESTYLE.local.md` (your house-style overrides, which extend or replace the default `HOUSESTYLE.md`; an agent reads it). Every key defaults ⇒ a minimal file is fine. The root stubs (`AGENTS.md`, `CLAUDE.md`, `README.md`, `pyproject.toml`, `.gitignore`, CI) are laid down once by `demolab init` and are yours from then on.
 
 **3.4 — User content** (100% the user's — freely deletable and replaceable): `tools/*`, `experiments/*` (runners, plus `playground.py` — the Streamlit demo, exempt from the contract), `writings/*` (`.typ` writeups), `artifacts/*` (`data/` per-run figures + `numbers.json`, `pdfs/` compiled PDFs; `artifacts/site/` is a gitignored build), `temp/*` (regenerable scratch).
 
@@ -118,6 +118,14 @@ Numbers must come from the run (§5.4) — never hand-type a literal that could
 
 See `ar006` for a worked example — ten references with DOIs, inline cites throughout, and the reference list at the foot of the body.
 
+**6.7 — Collaborative annotations are opt-in and web-only.** Set `annotations: hypothesis`
+in root `demolab.yaml` to embed the hosted Hypothesis client on every article and experiment,
+or put `annotations: "hypothesis"` in one writing's `meta` block to enable only that entry. An
+entry-level `annotations: none` disables a lab-wide setting. The client is never emitted into PDFs.
+Hypothesis owns annotation accounts, storage, private-group membership, anchoring, and threads;
+collaborators must choose their private group before posting if the discussion is not public. See
+demo article `ar027` for the complete setup and a live example.
+
 ## 7. Adding an experiment
 
 **7.1 — Tool subcommand.** Add a subcommand (or reuse one) in the relevant `tools/<tool>/tool.py`. Pass a `manifest` to `write_output` declaring the headline metrics (and a video, for a rendering tool).

{demolab_cli-2.2.0 → demolab_cli-2.3.0}/demolab_cli/runbooks/AUTORESEARCH.md

@@ -92,7 +92,7 @@ Give one explicit verdict:
 - **SUITABLE** — ready to formulate as a program;
 - **NEEDS REFINEMENT** — promising, but an outcome, baseline, contrast, or scope is still vague;
 - **BLOCKED** — required evidence or infrastructure is unavailable;
-- **WRONG WORKFLOW** — this is better handled as a one-off experiment, `FROM-PAPER`,
+- **WRONG WORKFLOW** — this is better handled as a one-off experiment,
   `LITERATURE-SEARCH`, or another named workflow.
 
 Do not force every interesting thought into AUTORESEARCH merely because it owns a capitalized

{demolab_cli-2.2.0 → demolab_cli-2.3.0}/demolab_cli/runbooks/FROM-JUPYTER.md

@@ -68,10 +68,9 @@ working lab, or a bare `demolab scaffold`) and `demolab build` green before you
    and the reproducible version is the correct one. That's a feature, not a regression.
 
 6. **Hand off.** Show the page + its PDF. State plainly **what was dropped** (scratch cells) and
-   **what was fixed** (seeds added, drifting numbers wired to the run, deps pinned). Then offer to
-   run **RED-TEAM** on the fresh experiment — a just-laundered notebook is exactly the thing to
-   adversarially check before anyone trusts it. Note: the original `.ipynb` is yours to keep or
-   delete — it's not part of the demolab record once the experiment reproduces.
+   **what was fixed** (seeds added, drifting numbers wired to the run, deps pinned). Note: the
+   original `.ipynb` is yours to keep or delete — it's not part of the demolab record once the
+   experiment reproduces.
 
 ---
 

{demolab_cli-2.2.0 → demolab_cli-2.3.0}/demolab_cli/runbooks/GETTING-STARTED.md

@@ -133,7 +133,7 @@ freestyling, not following this runbook.
      **scatter** of the sampled points coloured inside/outside with the quarter-circle arc, and a
      **log-x convergence curve** settling toward π. Its `README.md` states the figure contract.
    - **Bringing something in?** Existing codebase → [`MIGRATE-CODE.md`](MIGRATE-CODE.md); a
-     notebook → [`FROM-JUPYTER.md`](FROM-JUPYTER.md); a paper → [`FROM-PAPER.md`](FROM-PAPER.md).
+     notebook → [`FROM-JUPYTER.md`](FROM-JUPYTER.md).
      Land the **first** experiment via that runbook (same live-page payoff as below), and set
      the expectation that the rest migrates incrementally, later.
    - **Stack, in passing:** Python (`uv`) is the default — don't ask, just note it. If their
@@ -208,8 +208,7 @@ freestyling, not following this runbook.
      runbook and then every guide as a **numbered list, one per line with its one-line
      description** (don't hand-summarise from memory or trim to a favourite few — the whole
      point is they see everything demolab can do next). Runbooks
-     first (**NEXT** to pick the next experiment, **TOUR**, **MIGRATE-CODE**, **FROM-JUPYTER**,
-     **FROM-PAPER**, **LINT**, **DOCTOR**, **RED-TEAM**, **UPDATE**, …), then the guides
+     first (**TOUR**, **MIGRATE-CODE**, **FROM-JUPYTER**, **LINT**, **DOCTOR**, **UPDATE**, …), then the guides
      (**RULES**, **HOUSESTYLE**, **STRUCTURE**, **GLOSSARY**, …). Tell them: **HELP** re-shows
      this menu anytime, and typing any name in it starts that job.
    - **Ask me anything about the repo** — how it works, where something lives, why a convention
@@ -244,8 +243,8 @@ data and the landing site's source — read it for file shapes, never overlay it
   - **Missing a prerequisite?** — if `uv` or `typst` doesn't resolve, ask them to install it
     themselves and wait; skip entirely if both already resolve. `[1]`
   - **What should your first experiment be?** — open but shaped: their idea · field → three
-    numbered starters · bring in code/notebook/paper (→ `MIGRATE-CODE` / `FROM-JUPYTER` /
-    `FROM-PAPER`). No idea / no field? Fall back to the **Monte Carlo π** starter so no one
+    numbered starters · bring in code/notebook (→ `MIGRATE-CODE` / `FROM-JUPYTER`).
+    No idea / no field? Fall back to the **Monte Carlo π** starter so no one
     freezes here — this is the one question with a safety net, not a hard no-default. `[2]`
   - **Publish to GitHub Pages?** — free unless the repo is private; default yes, if no skip (it
     works locally). `[5]`

{demolab_cli-2.2.0 → demolab_cli-2.3.0}/demolab_cli/runbooks/LINT.md

@@ -6,9 +6,8 @@
 
 ## When to use
 When you want the prose and plots to read like a person — not an LLM — wrote them, and to
-conform to the house style before publishing. This is the **style** pass — one of three:
-*Doctor* audits the structural RULES, *Lint* (here) audits the prose **and the figures**, and
-*Red-team* audits whether the result is true and defensible. Run all three for a full check.
+conform to the house style before publishing. This is the **style** pass: *Doctor* audits the
+structural RULES, while *Lint* (here) audits the prose **and the figures**.
 `HOUSESTYLE.md` is the source of truth for every rule: this runbook cites it, it does not
 restate it. Scope is `writings/*.typ` (the published prose) **and the rendered figures it
 embeds** (`artifacts/data/<id>/*.svg`, `*.png`) — the plots are half of a writing and are lint

{demolab_cli-2.2.0 → demolab_cli-2.3.0}/demolab_cli/runbooks/TOUR.md

@@ -27,7 +27,7 @@ Adapt the depth to who's asking: a new lab member wants the on-ramp, a reviewer
 
 2. **Orient for their goal.** Ask what they're here to do, and tailor the close:
    - *Contributing?* → GETTING-STARTED's add-an-experiment flow, and RULES.
-   - *Reviewing?* → the results, then RED-TEAM.
+   - *Reviewing?* → the results, their supporting artifacts, and the relevant tests.
    - *Taking it over?* → flag anything undocumented or fragile you noticed while reading.
 
    Keep it warm and readable — this is the door into someone else's (or past-you's) thinking.