demolab-cli 1.0.0__tar.gz

demolab_cli-1.0.0/.github/workflows/landing-preview.yml

@@ -0,0 +1,62 @@
+name: PR preview (demo site)
+
+# Builds the shipped demo for every pull request and publishes it under pr-preview/pr-<N>/ on the
+# gh-pages branch, posts a sticky comment on the PR with the URL, and tears the preview down when
+# the PR closes or merges. This is what makes a PR's rendered doc set readable in place instead of
+# a raw diff. Pairs with landing.yml (the same gh-pages branch); needs the Pages source set to
+# "Deploy from a branch → gh-pages / (root)".
+#
+# Fork PRs get a read-only token and cannot write gh-pages, so previews are skipped for external
+# contributors. Do NOT switch this to pull_request_target to "fix" that — it runs untrusted PR
+# code with a write token (privilege-escalation footgun).
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+# One in-flight run per PR: rapid pushes supersede rather than race commits to gh-pages.
+concurrency:
+  group: preview-pr-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+env:
+  TYPST_VERSION: "0.15.0"
+
+jobs:
+  preview:
+    # Upstream only, same as the production deploy — a fork must not publish into demolab's Pages.
+    if: github.repository == 'eoinmurray/demolab'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # On 'closed' we only tear the preview down (no build needed), so guard the build steps.
+      - name: Install Typst ${{ env.TYPST_VERSION }}
+        if: github.event.action != 'closed'
+        run: |
+          url="https://github.com/typst/typst/releases/download/v${TYPST_VERSION}/typst-x86_64-unknown-linux-musl.tar.xz"
+          curl -fsSL "$url" | tar -xJ
+          echo "$PWD/typst-x86_64-unknown-linux-musl" >> "$GITHUB_PATH"
+
+      - uses: astral-sh/setup-uv@v5
+        if: github.event.action != 'closed'
+
+      - name: Build the demo with the core engine
+        if: github.event.action != 'closed'
+        run: |
+          rsync -a --exclude 'site/' demolab_cli/scaffold/skeleton/ ./
+          rsync -a --exclude 'site/' demolab_cli/scaffold/demo/ ./
+          # Same landing-only homepage as production (landing.yml), so the preview matches.
+          cp demolab_cli/scaffold/demo/site/landing.typ ./landing.typ
+          uv run --no-dev demolab build
+
+      # Deploy artifacts/site (the raw built demo — no CNAME/installers; those only belong at the
+      # production root) to pr-preview/pr-<N>/, maintain the sticky comment, and remove the subdir
+      # on 'closed'. The action auto-detects deploy vs remove from the event type.
+      - name: Deploy / update / tear down the preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: artifacts/site

demolab_cli-1.0.0/.github/workflows/landing.yml

@@ -0,0 +1,76 @@
+name: Deploy the site (demo at root)
+
+# Publishes to GitHub Pages at demolab.eoinmurray.info via the BRANCH-based flow:
+#   build the shipped demo → assemble _site (demo at /, CNAME) → commit to the
+#   `gh-pages` branch. Branch-based (not the GitHub-Actions Pages flow) so per-PR previews
+#   (landing-preview.yml) can live in the same branch under pr-preview/. Requires the Pages source
+#   set to "Deploy from a branch → gh-pages / (root)". A user's own lab deploy is separate and
+#   opt-in (demolab_cli/deploy/deploy.yml, added by `demolab deploy-setup`).
+on:
+  push:
+    branches: [main]
+    paths:
+      - "demolab_cli/**"
+      - "pyproject.toml"
+      - ".github/workflows/landing.yml"
+  workflow_dispatch:
+
+# The deploy commits the assembled site to the gh-pages branch, so the token needs write.
+permissions:
+  contents: write
+
+# Serialise production deploys against each other and against preview teardowns so two writers
+# never race a commit to gh-pages. Previews use their own per-PR group.
+concurrency:
+  group: pages-deploy
+  cancel-in-progress: false
+
+env:
+  TYPST_VERSION: "0.15.0"  # match the engine's local toolchain
+
+jobs:
+  deploy:
+    # Upstream only. Forks/templates inherit this file, but must never publish demolab's site to
+    # their own Pages — so the job is skipped everywhere but the source repo.
+    if: github.repository == 'eoinmurray/demolab'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Typst ${{ env.TYPST_VERSION }}
+        run: |
+          # Download the pinned release directly (deterministic, no third-party action to track).
+          url="https://github.com/typst/typst/releases/download/v${TYPST_VERSION}/typst-x86_64-unknown-linux-musl.tar.xz"
+          curl -fsSL "$url" | tar -xJ
+          echo "$PWD/typst-x86_64-unknown-linux-musl" >> "$GITHUB_PATH"
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build the demo with the core engine
+        run: |
+          # Materialise the shipped demo at the repo root (skeleton + demo overlay), exactly as
+          # `demolab add-demo-content` does, then compile it with the engine. The engine has zero
+          # runtime deps and the demo ships its rendered figures/videos, so --no-dev skips the
+          # heavy science deps (they're only for *running* experiments and the test suite).
+          rsync -a --exclude 'site/' demolab_cli/scaffold/skeleton/ ./
+          rsync -a --exclude 'site/' demolab_cli/scaffold/demo/ ./
+          # The landing-only homepage (the marketing hero, a custom landing.typ) — kept under
+          # site/ so the add-demo-content overlay never puts it in a user's lab.
+          cp demolab_cli/scaffold/demo/site/landing.typ ./landing.typ
+          uv run --no-dev demolab build
+
+      - name: Assemble the Pages tree (demo at /, CNAME at root)
+        run: |
+          rm -rf _site && cp -R artifacts/site/. _site/
+          cp demolab_cli/scaffold/demo/site/CNAME _site/
+
+      # Publish _site to the root of gh-pages. clean-exclude preserves the live PR previews
+      # (pr-preview/, owned by landing-preview.yml) — CNAME is re-emitted from _site every run.
+      - name: Deploy to gh-pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: _site
+          branch: gh-pages
+          clean: true
+          clean-exclude: pr-preview/
+          single-commit: true

demolab_cli-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish demolab-cli to PyPI
+
+# Tag-triggered release: `git tag v<VERSION> && git push --tags` builds the wheel from a
+# clean checkout and publishes it via PyPI Trusted Publishing (OIDC — no API token stored).
+# One-time setup on pypi.org: Account → Publishing → add a pending publisher for project
+# `demolab-cli`, owner `eoinmurray`, repo `demolab`, workflow `publish.yml`, environment
+# `pypi` — and create the matching `pypi` environment in this repo's GitHub settings.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    # Upstream only — a fork's tags must never try to publish the package.
+    if: github.repository == 'eoinmurray/demolab'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC for Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Tag must match the engine VERSION
+        run: test "v$(cat demolab_cli/VERSION)" = "$GITHUB_REF_NAME"
+
+      - uses: astral-sh/setup-uv@v5
+
+      - run: uv build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

demolab_cli-1.0.0/.github/workflows/tests.yml

@@ -0,0 +1,69 @@
+name: Tests
+
+# Runs the Python test suite on Linux AND Windows. The Windows leg guards the portability
+# fixes a real Windows user's field report drove: the dev server's dual-stack bind (Windows
+# resolves `localhost` to ::1, so an IPv4-only bind makes the printed URL dead there), the
+# overlay.py copy behind demolab scaffold / add-demo-content (rsync doesn't exist on
+# Windows), and slides.py's deck detection (grep/basename didn't either). macOS/Linux pass
+# these trivially — only a real Windows runner is an honest check.
+#
+# Installing typst on the Linux leg unskips the engine build smoke test there; Windows
+# stays typst-less and fast. The packaging job builds the wheel from this clean checkout
+# and inits a lab from it — the same path `uvx demolab-cli init` takes in the wild.
+on:
+  push:
+    branches: [main]
+    paths:
+      - "demolab_cli/**"
+      - "pyproject.toml"
+      - ".github/workflows/tests.yml"
+  pull_request:
+    paths:
+      - "demolab_cli/**"
+      - "pyproject.toml"
+      - ".github/workflows/tests.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install typst (Linux — unskips the engine build tests)
+        if: runner.os == 'Linux'
+        env:
+          TYPST_VERSION: "0.15.0"  # match the engine's toolchain (see landing.yml)
+        run: |
+          curl -sL "https://github.com/typst/typst/releases/download/v${TYPST_VERSION}/typst-x86_64-unknown-linux-musl.tar.xz" \
+            | tar -xJf - -C /usr/local/bin --strip-components=1 "typst-x86_64-unknown-linux-musl/typst"
+
+      - name: Run the test suite
+        run: uv run pytest
+
+  packaging:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build the wheel and init a lab from it
+        run: |
+          uv build
+          # Noise that must never ship (untracked locally, but belt-and-braces).
+          if unzip -l dist/demolab_cli-*.whl | grep -E 'demo/temp/|demo/artifacts/site/|__pycache__|\.demolab/'; then
+            echo "wheel carries build noise" && exit 1
+          fi
+          mkdir /tmp/lab && cd /tmp/lab
+          uvx --from "$(ls "$GITHUB_WORKSPACE"/dist/demolab_cli-*.whl)" demolab-cli init
+          test -f demolab.yaml && test -f .demolab/lib.typ && test -f AGENTS.md

demolab_cli-1.0.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.uv/
+
+# Tool caches
+.pytest_cache/
+
+# macOS
+.DS_Store
+
+# Agent / editor local tooling (not part of the repo)
+.claude/
+
+# Short-lived run scratch (regenerated by every tool run).
+# Note: artifacts/data/ (figures + numbers.json) and artifacts/pdfs/ (compiled
+# deliverables you host/link) are committed; artifacts/site/ is a regenerable build.
+temp/
+dist/
+artifacts/site/
+demolab_cli/scaffold/demo/temp/
+demolab_cli/scaffold/demo/artifacts/site/
+# Transient preview copy written by `demolab dev --demo --landing` (source of truth is
+# demo/site/landing.typ) — never committed, never part of the user-facing demo overlay.
+demolab_cli/scaffold/demo/landing.typ
+
+# Engine staging dir the demolab CLI materialises at the lab root (lib.typ + web assets
+# + version stamp) — regenerated whenever the installed demolab-cli version changes.
+.demolab/
+
+# Secrets — never commit
+.env
+.env.local

demolab_cli-1.0.0/AGENTS.md

@@ -0,0 +1,59 @@
+# AGENTS.md
+
+Demolab — an agent-operated lab notebook for computational science. This file is the thin
+entry point; the substance (runbooks + guides) ships inside the `demolab-cli` package and
+is reached through the CLI, so it's always in step with the installed engine. **Read the
+rules before working here.**
+
+> **This checkout is also the demolab-cli source repo** — the engine lives in
+> `demolab_cli/` (build code, Typst templates, runbooks, guides, scaffold). Editing the
+> engine itself? Read [DEVELOPING.md](DEVELOPING.md) first. Everything below applies to
+> operating a lab, here or anywhere.
+
+**Finding the docs:** run `demolab docs` for the menu of runbooks (step-by-step procedures)
+and guides (reference). `demolab docs <NAME>` prints the file's absolute path — read that
+file. Start with `demolab docs RULES` — the single conventions doc: toolchain, what you may
+edit, commits, the tool ↔ experiment contract + schemas, and how to add a tool /
+experiment / writing. Unfamiliar with a term? `demolab docs GLOSSARY`. Authoring a writing?
+`demolab docs HOUSESTYLE` (a root `HOUSESTYLE.local.md`, if present, extends or replaces it
+— read it too). A slide deck? `demolab docs SLIDES`. Lost in the layout? `demolab docs
+STRUCTURE`. Need a human? `demolab docs SUPPORT`.
+
+Three rules important enough to state here too:
+
+- **Toolchain:** use `uv` (Python) and `typst` (publishing) via the `demolab` CLI. Never
+  call `pip` / `python` / `python3` directly.
+- **Commits:** author every commit as the human only — never a `Co-Authored-By:` / agent
+  trailer, never an agent in the author/committer fields.
+- **Don't hand-edit machine-managed dirs:** the gitignored `.demolab/` staging dir at a
+  lab root belongs to the CLI. In a user's lab the engine isn't even on disk to edit — it
+  lives in the installed package; updating it is a dependency bump (`demolab docs UPDATE`).
+
+## Commands — type a NAME
+
+demolab is driven by typing a **name in CAPS** (SCREAMING-KEBAB). Three commands:
+
+- **`HELP`** — run `demolab docs` and present its menu, one line each.
+- **`<RUNBOOK>`** — a runbook name (e.g. `GETTING-STARTED`, `LINT`, `DOCTOR`) → run
+  `demolab docs <NAME>`, read the file, 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>`** — a guide name (e.g. `RULES`, `SLIDES`) → read it the same way, then **walk
+  the user through it**: summarise, go section by section, answer questions — don't just
+  paste the file.
+
+**The NAME is the command.** If the user's message is (or starts with) one of these names,
+that *is* the request: act on it, don't ask what they mean. Natural phrasings route too
+("lint the writings" → `LINT`, "set up my lab" → `GETTING-STARTED`) — the `demolab docs`
+menu's one-liners tell you which doc covers what.
+
+**Docs are the source of truth.** When the user is confused, stuck, or asks "how do I…"
+about operating demolab, check the menu *before* improvising an answer. If a runbook or
+guide covers it, ground your answer in it — cite it, or offer to start it — rather than
+explaining from memory.
+
+> **`GETTING-STARTED`** ("set up my lab", "how do I get started") means **following the
+> runbook as a conversation** — orient the user, then ask the gated questions *in order*
+> and wait for answers. **Do not autonomously scaffold, install, build an experiment, and
+> report back** — that races past every choice the user is supposed to make (what to
+> compute, branding, publishing). Read the runbook first; run nothing before its step-0
+> orient + ready-check.

demolab_cli-1.0.0/CLAUDE.md

@@ -0,0 +1,19 @@
+# CLAUDE.md
+
+Read **[AGENTS.md](AGENTS.md)** before working here — it's the entry point. (This checkout
+is also the demolab-cli source repo; engine work goes through [DEVELOPING.md](DEVELOPING.md).)
+
+## Commands — type a NAME
+
+demolab is driven by names in CAPS. **If the user's message is just one of these names,
+that IS the command — do it, don't ask what they mean:**
+
+- **`HELP`** — run `demolab docs` and present the menu of runbooks and guides.
+- **A runbook name** (e.g. `GETTING-STARTED`, `TOUR`, `LINT`, `DOCTOR`, `RED-TEAM`,
+  `STEELMAN`, `NEXT`, `UPDATE`) — run `demolab docs <NAME>`, read the file it points at,
+  then **start that runbook** and drive it step by step.
+- **A guide name** (e.g. `RULES`, `HOUSESTYLE`, `SLIDES`, `STRUCTURE`, `GLOSSARY`,
+  `SUPPORT`) — read it the same way, then **walk the user through it** interactively.
+
+The full, current menu (names + one-liners) comes from `demolab docs` — run it rather than
+relying on a memorised list. Details of the interaction rules are in [AGENTS.md](AGENTS.md).

demolab_cli-1.0.0/DEVELOPING.md

@@ -0,0 +1,76 @@
+# Developing demolab
+
+This repo is the source of the **`demolab-cli`** package — the engine (`demolab_cli/`:
+build code, Typst templates, runbooks, guides, scaffold + demo) plus the packaging to ship
+it to PyPI. `uv sync` installs the package **editable**, so the `demolab` command here runs
+the working tree's code directly, and the engine-data lookup resolves to these very files —
+edit, run, no reinstall.
+
+## Serve the shipped demo — the usual case
+
+```sh
+demolab dev --demo             # materialises the demo into temp/demo-preview and serves it
+demolab dev --demo --landing   # …and previews the marketing landing page (site/landing.typ)
+```
+
+This copies the demo into `temp/demo-preview/` (a disposable lab; rebuilt fresh on every
+invocation) and serves it. **Engine edits hot-reload** — the dev server watches the package's
+`typ/` assets and `.py` files, which here *are* the working tree. **Demo-content edits don't**
+(the served copy is a snapshot): edit under `demolab_cli/scaffold/demo/`, then rerun the
+command — or serve the demo source directly when iterating on demo content itself:
+
+```sh
+DEMOLAB_ROOT=demolab_cli/scaffold/demo uv run python -m demolab_cli.devserver
+```
+
+(That writes build scratch into `scaffold/demo/temp/` + `scaffold/demo/artifacts/site/` —
+both gitignored, both excluded from the wheel.)
+
+## Full sandbox — when you need to *run* the experiments
+
+To **run** the demo's experiments (regenerate figures, tweak a runner), materialise the demo
+at the repo root — this repo's own `demolab.yaml` makes it a valid lab:
+
+```sh
+demolab add-demo-content   # copy the worked demo (skeleton + demo) to the repo root
+demolab dev                # serve whatever content is at the root
+demolab run exp000         # re-run a runner, etc.
+```
+
+This *copies* the demo to the root, so keep it out of git with a **local** exclude — never
+the shipped `.gitignore`. `.git/info/exclude` is per-clone and never committed:
+
+```sh
+cat >> .git/info/exclude <<'EOF'
+# local dev sandbox — never committed
+/writings/
+/experiments/
+/tools/
+/artifacts/
+EOF
+```
+
+Tear it down with `demolab clear-demo-content` (or `rm -rf writings experiments tools artifacts`).
+
+## Packaging & release
+
+- **Build + inspect the wheel:** `uv build`, then `unzip -l dist/demolab_cli-*.whl` — the
+  wheel must carry `typ/`, `runbooks/`, `guides/`, `scaffold/` (demo *without* its
+  `temp/`/`artifacts/site/` noise) and no `demolab_cli/test_*.py`. CI builds from a clean
+  checkout, so local noise can't ship even if the excludes drift.
+- **Version:** `demolab_cli/VERSION` is the single source of truth (hatchling reads it via
+  the regex version source; `demolab version` prints it; lib.typ stamps it into the site's
+  generator meta). SemVer per `demolab_cli/CHANGELOG.md`.
+- **Test from the wheel:** `uvx --from dist/demolab_cli-*.whl demolab-cli init` in an empty
+  dir, then point the fresh lab's `[tool.uv.sources]` at the wheel to `uv sync` against it.
+- **Release:** update `CHANGELOG.md`, bump `VERSION`, commit, then
+  `git tag v<VERSION> && git push --tags` — `.github/workflows/publish.yml` builds and
+  publishes to PyPI via trusted publishing (the tag must match `VERSION`).
+
+## Why the lab needs `.demolab/` staging at all
+
+Writings use root-relative paths (`/.demolab/lib.typ`, `/artifacts/…`) and Typst confines
+every read to `--root` (the lab). The engine lives in site-packages — outside every lab —
+so the CLI materialises the few files Typst must read (`lib.typ` + web assets) into the
+gitignored `.demolab/` and stages `main.typ` into `temp/bundle/` per build. Everything else
+the engine does happens in Python, where site-packages is a perfectly good home.

demolab_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eoin Murray
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

demolab_cli-1.0.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: demolab-cli
+Version: 1.0.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
+License: MIT License
+        
+        Copyright (c) 2026 Eoin Murray
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Demolab
+
+**A lab notebook for computational science — reproducible results, published and citable, run by a coding agent instead of a build system.**
+
+> **Coding agent setting someone up?** Run `uvx demolab-cli docs GETTING-STARTED`, read the file it prints, and follow it strictly, step by step. *(Human, setting up by hand? See [Quickstart](#quickstart).)*
+
+You write a model or experiment once as a small program. Demolab runs it, captures everything it produced, stamps it with the exact code version, and publishes a clean page — figures, numbers, and real typeset maths — to both the web and PDF. The numbers on the page are read from the run, so they can't drift. You drive it all by talking to a coding agent; there's no web development or build config to touch.
+
+## Quickstart
+
+Open your coding agent in an empty folder and paste:
+
+> Run `uvx demolab-cli init` here, then follow its GETTING-STARTED runbook strictly.
+
+It lays your lab down, walks you through the toolchain (`uv`, `typst`) and your first experiment, one step at a time.
+
+<details>
+<summary><b>Set it up by hand instead?</b></summary>
+
+Install [`uv`](https://docs.astral.sh/uv/) and [`typst`](https://typst.app) (`brew install uv typst`), then:
+
+```sh
+mkdir my-lab && cd my-lab
+uvx demolab-cli init   # lab structure + git init — yours from the first commit
+uv sync                # installs the deps and the `demolab` command
+```
+
+Then `demolab add-demo-content && demolab run exp000 && demolab dev` to see the loop. `demolab clear-demo-content` wipes the demo again. The engine lives in the `demolab-cli` package — updating it is `uv lock --upgrade-package demolab-cli && uv sync`.
+
+</details>
+
+## What to ask your agent
+
+Open your lab in your agent and say a runbook's name — it follows that runbook one step at a time. `demolab docs` lists them all (each is a plain file shipped in the package; `demolab docs <NAME>` prints its path). In this repo they live under [`demolab_cli/runbooks/`](demolab_cli/runbooks/).
+
+| Say… | …and it will |
+|------|--------------|
+| **GETTING-STARTED** | set you up end to end: scaffold, your first experiment live on a page, brand, publish |
+| **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
+
+One decoupled loop: **a tool computes → drops data → an experiment writes it up → the site publishes it.** Every run records its exact parameters and the git commit it came from (stamped on the page), and tables read their numbers straight from the run — so prose and results can't disagree. A single Typst pass emits a website, a PDF per entry, and a book, all sharing the same live numbers.
+
+The detail lives in the guides (in a lab: `demolab docs <NAME>`; in this repo, the files under `demolab_cli/guides/`):
+
+- **[RULES.md](demolab_cli/guides/RULES.md)** — the tool ↔ experiment contract, schemas, provenance, and how to add things.
+- **[STRUCTURE.md](demolab_cli/guides/STRUCTURE.md)** — the annotated file tree.
+- **[HOUSESTYLE.md](demolab_cli/guides/HOUSESTYLE.md)** — prose, maths, and figure style.
+- **[AGENTS.md](AGENTS.md)** — the agent entry point.
+
+## Commands
+
+`demolab` shows them all. The everyday ones: `init`, `docs`, `install`, `scaffold` · `add-demo-content` · `clear-demo-content`, `run expNNN`, `dev`, `build`, `test`.
+
+## License
+
+[MIT](LICENSE) — free to use, fork, and adapt for your own lab.

demolab_cli-1.0.0/README.md

@@ -0,0 +1,70 @@
+# Demolab
+
+**A lab notebook for computational science — reproducible results, published and citable, run by a coding agent instead of a build system.**
+
+> **Coding agent setting someone up?** Run `uvx demolab-cli docs GETTING-STARTED`, read the file it prints, and follow it strictly, step by step. *(Human, setting up by hand? See [Quickstart](#quickstart).)*
+
+You write a model or experiment once as a small program. Demolab runs it, captures everything it produced, stamps it with the exact code version, and publishes a clean page — figures, numbers, and real typeset maths — to both the web and PDF. The numbers on the page are read from the run, so they can't drift. You drive it all by talking to a coding agent; there's no web development or build config to touch.
+
+## Quickstart
+
+Open your coding agent in an empty folder and paste:
+
+> Run `uvx demolab-cli init` here, then follow its GETTING-STARTED runbook strictly.
+
+It lays your lab down, walks you through the toolchain (`uv`, `typst`) and your first experiment, one step at a time.
+
+<details>
+<summary><b>Set it up by hand instead?</b></summary>
+
+Install [`uv`](https://docs.astral.sh/uv/) and [`typst`](https://typst.app) (`brew install uv typst`), then:
+
+```sh
+mkdir my-lab && cd my-lab
+uvx demolab-cli init   # lab structure + git init — yours from the first commit
+uv sync                # installs the deps and the `demolab` command
+```
+
+Then `demolab add-demo-content && demolab run exp000 && demolab dev` to see the loop. `demolab clear-demo-content` wipes the demo again. The engine lives in the `demolab-cli` package — updating it is `uv lock --upgrade-package demolab-cli && uv sync`.
+
+</details>
+
+## What to ask your agent
+
+Open your lab in your agent and say a runbook's name — it follows that runbook one step at a time. `demolab docs` lists them all (each is a plain file shipped in the package; `demolab docs <NAME>` prints its path). In this repo they live under [`demolab_cli/runbooks/`](demolab_cli/runbooks/).
+
+| Say… | …and it will |
+|------|--------------|
+| **GETTING-STARTED** | set you up end to end: scaffold, your first experiment live on a page, brand, publish |
+| **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
+
+One decoupled loop: **a tool computes → drops data → an experiment writes it up → the site publishes it.** Every run records its exact parameters and the git commit it came from (stamped on the page), and tables read their numbers straight from the run — so prose and results can't disagree. A single Typst pass emits a website, a PDF per entry, and a book, all sharing the same live numbers.
+
+The detail lives in the guides (in a lab: `demolab docs <NAME>`; in this repo, the files under `demolab_cli/guides/`):
+
+- **[RULES.md](demolab_cli/guides/RULES.md)** — the tool ↔ experiment contract, schemas, provenance, and how to add things.
+- **[STRUCTURE.md](demolab_cli/guides/STRUCTURE.md)** — the annotated file tree.
+- **[HOUSESTYLE.md](demolab_cli/guides/HOUSESTYLE.md)** — prose, maths, and figure style.
+- **[AGENTS.md](AGENTS.md)** — the agent entry point.
+
+## Commands
+
+`demolab` shows them all. The everyday ones: `init`, `docs`, `install`, `scaffold` · `add-demo-content` · `clear-demo-content`, `run expNNN`, `dev`, `build`, `test`.
+
+## License
+
+[MIT](LICENSE) — free to use, fork, and adapt for your own lab.