Docs: group-site restyle, PyPI install guide, ti-runtime and workbench pages

README.md

@@ -11,6 +11,7 @@
 > models from LaTeX; don't hand-code what the compiler should generate.**
 
 📖 **New here? Start with the [documentation](docs/index.md)** —
+[Installation](docs/installation.md) ·
 [Getting started](docs/mechdsl-core/getting-started.md) ·
 [Core concepts](docs/mechdsl-core/concepts.md) ·
 [LaTeX directive reference](docs/mechdsl-core/latex-directives.md) ·
@@ -38,9 +39,17 @@ viscoplasticity, and Lemaitre continuum damage. Backends: Taichi (MVP-stable), M
 
 [`mechdsl-workbench`](https://github.com/CEmM2/mechdsl-workbench) is a companion
 browser workbench: LaTeX on the left, the compiled mechanics or transpiled
-algorithm on the right. It installs this repository's packages at a pinned
-release and is the fastest way to try the language before committing to the
-pipeline documentation.
+algorithm on the right. It is the fastest way to try the language before
+committing to the pipeline documentation.
+
+```bash
+pip install "mechdsl-workbench[mechdsl]"   # workbench + the MechDSL engine
+mechdsl-workbench                          # then open http://127.0.0.1:8000
+```
+
+The `[mechdsl]` extra pulls `mechdsl-core[verify]` and `algo2code` from PyPI. The
+workbench pins Python 3.12 (`>=3.12,<3.13`), narrower than this repository's
+`>=3.11,<3.14`. See [the workbench docs page](docs/workbench.md).
 
 ## Installation
 
@@ -265,11 +274,14 @@ User-facing documentation lives in [`docs/`](docs/) and is built as a
 | Page | What it covers |
 |------|----------------|
 | [Home](docs/index.md) | What MechDSL is and why to use it |
-| [Getting started](docs/mechdsl-core/getting-started.md) | Install with `uv`, first solver, `.tex` and energy-derived inputs |
+| [Installation](docs/installation.md) | Every package and extra on PyPI, plus the from-source `uv` workflow |
+| [Getting started](docs/mechdsl-core/getting-started.md) | `pip install`, first solver, `.tex` and energy-derived inputs |
 | [Core concepts](docs/mechdsl-core/concepts.md) | LaTeX-first idea, six-layer pipeline, hyperelastic vs. dissipative, support tiers |
 | [LaTeX directive reference](docs/mechdsl-core/latex-directives.md) | Every `% mechanics` directive with examples |
 | [Constitutive models](docs/mechdsl-core/constitutive-models.md) | Model catalog with runnable snippets |
 | [Algorithm transpiler (algo2code)](docs/algo2code/index.md) | How return-maps/PCG are transpiled from `algpseudocode` |
+| [ti-runtime](docs/ti-runtime/index.md) | The neutral Taichi runtime: seams, primitives, and the operator contract |
+| [Browser workbench](docs/workbench.md) | Installing and running the companion browser app |
 | [Examples gallery](docs/mechdsl-core/examples.md) | Cantilever, Cook's membrane, necking bar, patch test, cyclic plasticity |
 | [How it works](docs/reference/architecture.md) | Layers, IR discipline, determinism, verification |
 | [FAQ & troubleshooting](docs/reference/faq.md) | Common questions and fixes |

docs/algo2code/getting-started.md

@@ -1,27 +1,43 @@
 # Getting started
 
-This page takes you from a fresh clone to a transpiled algorithm.
+This page takes you from an empty environment to a transpiled algorithm.
 
-## Prerequisites
+## Install
 
-`algo2code` is part of the MechDSL [uv](https://docs.astral.sh/uv/) workspace, so the
-simplest way to get it is the workspace install:
+`algo2code` is on PyPI and installs on its own — you do not need `mechdsl-core`, and
+you do not need the monorepo:
 
 ```bash
-git clone https://github.com/CEmM2/MechDSL.git
-cd MechDSL
-uv sync --all-packages --all-groups --all-extras
+pip install algo2code
 ```
 
+It requires Python 3.11, 3.12, or 3.13 (`requires-python = ">=3.11,<3.14"`) and
+nothing else.
+
 !!! tip "Zero runtime dependencies"
-    `algo2code` is **standard-library only** — it imports nothing at runtime beyond the
-    Python stdlib, and it never imports `mechdsl`. That means the package directory
+    `algo2code` is **standard-library only** — its `dependencies` list is literally
+    empty, it imports nothing at runtime beyond the Python stdlib, and it never imports
+    `mechdsl`. That also means the package directory
     (`packages/algo2code/src/algo2code/`) is self-contained and can be vendored into
     another project by copying it, with no dependency footprint.
 
-!!! warning "Always go through `uv run`"
-    Never call `python` or `pytest` directly inside the workspace — prefix every command
-    with `uv run` so it uses the project's locked environment.
+`algo2code` also arrives automatically with `pip install "mechdsl-core[verify]"`, since
+the full engine uses it to generate the matrix-free PCG solver.
+
+??? note "Installing from source instead"
+    `algo2code` is one of the three packages in the MechDSL
+    [uv](https://docs.astral.sh/uv/) workspace. For the test suite or to contribute:
+
+    ```bash
+    git clone https://github.com/CEmM2/MechDSL.git
+    cd MechDSL
+    uv sync --all-packages --all-groups --all-extras
+    ```
+
+    Inside a source checkout, never call `python` or `pytest` directly — prefix every
+    command with `uv run` so it uses the project's locked environment.
+
+See [Installation](../installation.md) for the full matrix across all packages.
 
 ## Your first transpile
 
@@ -38,7 +54,7 @@ print(code)        # Taichi-compatible Python source, as text
 Run it:
 
 ```bash
-uv run python first_algo.py
+python first_algo.py
 ```
 
 ### What just happened
@@ -77,3 +93,5 @@ radial_return_j2 = ns["radial_return_j2"]   # now a real callable
   how the transpiled code is wired into the mechdsl-core solver.
 - [Examples](examples.md) — runnable snippets for the J2 return-map family and the PCG
   solver.
+- [Browser workbench](../workbench.md) — paste an `algorithmic` block into a pane and
+  read the generated Taichi next to it.

docs/algo2code/index.md

@@ -9,6 +9,12 @@ It is deliberately tiny: **zero runtime dependencies** (stdlib only), and it nev
 `mechdsl`. The relationship is strict producer/consumer — mechdsl-core consumes
 `algo2code`-generated artifacts, not the other way around.
 
+It is on PyPI under the MIT license and installs standalone — no `mechdsl-core` needed:
+
+```bash
+pip install algo2code
+```
+
 ---
 
 ## Why a separate package
@@ -47,7 +53,8 @@ The authoritative reference is `dev/design_docs/11-ALGO2CODE.md`.
 
 <div class="grid cards" markdown>
 
-- :material-rocket-launch: **[Getting started](getting-started.md)** — install and transpile your first algorithm.
+- :material-download: **[Installation](../installation.md)** — every package, extra, and the from-source workflow.
+- :material-rocket-launch: **[Getting started](getting-started.md)** — `pip install`, then transpile your first algorithm.
 - :material-code-tags: **[Usage](usage.md)** — the `transpile` API, the algorithm library, and the solver seam.
 - :material-cards: **[Examples](examples.md)** — runnable transpile snippets for the J2 family and PCG.
 

docs/index.md

@@ -1,11 +1,13 @@
 # MechDSL
 
-**Write your mechanics in LaTeX. Get tested code back.**
+![LaTeX goes in, GPU kernels come out.](assets/mechdsl-banner.webp){ .hero-banner }
 
-MechDSL is a monorepo of two cooperating LaTeX-to-code compilers for computational solid
-mechanics. You describe the math — a boundary-value problem, a strain-energy function, a
-return-mapping algorithm — in an ordinary LaTeX document, and the toolchain emits
-deterministic, tested [Taichi](https://www.taichi-lang.org/) solver code.
+**Write your mechanics in LaTeX. Get a tested finite-element solver back.**
+
+MechDSL is a monorepo of LaTeX-to-code compilers for computational solid mechanics. You
+describe the math — a boundary-value problem, a strain-energy function, a return-mapping
+algorithm — in an ordinary LaTeX document, and the toolchain emits deterministic, tested
+[Taichi](https://www.taichi-lang.org/) solver code.
 
 The same `.tex` file renders normally through `pdflatex` **and** is executable input to
 the compiler. Your paper's source can be your simulation's source. The guiding principle:
@@ -14,7 +16,28 @@ the compiler. Your paper's source can be your simulation's source. The guiding p
 
 ---
 
-## The two packages
+## Install it
+
+Everything is on PyPI under the MIT license:
+
+```bash
+pip install mechdsl-core              # the compiler: LaTeX -> emitted solver source (Taichi-free)
+pip install "mechdsl-core[verify]"    # the full engine: run and verify solves
+```
+
+Or skip the scripting entirely and drive it from a browser:
+
+```bash
+pip install "mechdsl-workbench[mechdsl]"
+mechdsl-workbench                     # then open http://127.0.0.1:8000
+```
+
+See [Installation](installation.md) for every package, extra, and the from-source
+workflow.
+
+---
+
+## The packages
 
 <div class="grid cards" markdown>
 
@@ -26,6 +49,8 @@ the compiler. Your paper's source can be your simulation's source. The guiding p
     element kernels, deriving stress **S = ∂Ψ/∂E** and tangent **C = ∂²Ψ/∂E²**
     symbolically. Six-layer pipeline, Total Lagrangian, Hex8, Taichi backend.
 
+    `pip install mechdsl-core`
+
     [:octicons-arrow-right-24: Introduction](mechdsl-core/index.md) ·
     [Getting started](mechdsl-core/getting-started.md)
 
@@ -37,15 +62,43 @@ the compiler. Your paper's source can be your simulation's source. The guiding p
     the PCG solver — into executable code. Zero runtime dependencies. Consumed by
     mechdsl-core for everything that *isn't* a closed-form expression.
 
+    `pip install algo2code`
+
     [:octicons-arrow-right-24: Introduction](algo2code/index.md) ·
     [Getting started](algo2code/getting-started.md)
 
+- :material-chip: **[ti-runtime](ti-runtime/index.md)**
+
+    ---
+
+    The neutral Taichi runtime. Vector primitives, Tier-1 `@ti.func` tensor helpers, and
+    the injection seams that generated bodies plug into. Generated code depends on this,
+    never on the compiler that produced it.
+
+    `pip install ti-runtime`
+
+    [:octicons-arrow-right-24: Introduction](ti-runtime/index.md)
+
+- :material-application-brackets: **[mechdsl-workbench](workbench.md)**
+
+    ---
+
+    The companion browser app: LaTeX on the left, compiled mechanics or transpiled
+    algorithm on the right. Lives in its own repository; the fastest way to try the
+    language before committing to the pipeline.
+
+    `pip install "mechdsl-workbench[mechdsl]"`
+
+    [:octicons-arrow-right-24: Browser workbench](workbench.md)
+
 </div>
 
-The relationship is strict producer/consumer: **mechdsl-core consumes algo2code-generated
-artifacts**; algo2code is runtime-free and never imports `mechdsl`. Together they cover
-both halves of a constitutive model — the closed-form energy (differentiated by
-mechdsl-core) and the iterative algorithm (transpiled by algo2code).
+The three monorepo packages have strict, one-way relationships. **mechdsl-core consumes
+algo2code-generated artifacts**; algo2code is runtime-free and never imports `mechdsl`;
+`ti-runtime` is what generated code lands on and never imports `mechdsl` either. Together
+they cover both halves of a constitutive model — the closed-form energy (differentiated
+by mechdsl-core) and the iterative algorithm (transpiled by algo2code) — plus the runtime
+floor they both emit against.
 
 ---
 
@@ -69,15 +122,20 @@ print(bundle.content_hash())       # deterministic — same input, same hash, ev
 ```
 
 That call runs the full pipeline: parse the directives → build the Mechanics IR →
-localise to an Element IR → plan the tensor contractions → emit Taichi.
+localise to an Element IR → plan the tensor contractions → emit Taichi. It needs only the
+base `pip install mechdsl-core` — no Taichi required to emit.
 
 ---
 
 ## Where to go next
 
+- Just want it installed? **[Installation](installation.md)** covers PyPI, the extras,
+  and the `uv` source workflow.
 - New here? Start with the **[mechdsl-core introduction](mechdsl-core/index.md)** — it's
   the main package.
 - Want to run something? **[Getting started](mechdsl-core/getting-started.md)** takes you
-  from a fresh clone to a compiled solver bundle.
+  from a fresh install to a compiled solver bundle.
+- Prefer clicking to typing? The **[browser workbench](workbench.md)** runs the same
+  compiler behind a UI.
 - Curious about the design? **[How it works](reference/architecture.md)** is a guided tour
   of the six layers, and the **[FAQ](reference/faq.md)** answers the common questions.

docs/installation.md

@@ -0,0 +1,127 @@
+# Installation
+
+Every MechDSL package is published on PyPI under the MIT license, so the fastest way
+in is `pip install`. Installing from source with [uv](https://docs.astral.sh/uv/) is
+the path for contributors and for anyone who wants the runnable `examples/` tree.
+
+!!! tip "In a hurry?"
+    `pip install "mechdsl-workbench[mechdsl]"` then `mechdsl-workbench` gives you the
+    whole toolchain behind a browser UI — LaTeX in the left pane, generated Taichi in
+    the right. See [the workbench page](workbench.md).
+
+## What's on PyPI
+
+| Install | What it gives you |
+|---|---|
+| `pip install mechdsl-core` | The FEM compiler: LaTeX → emitted Taichi solver source. **Taichi-free.** ([PyPI](https://pypi.org/project/mechdsl-core/)) |
+| `pip install "mechdsl-core[verify]"` | The full engine — adds `taichi`, `ti-runtime`, and `algo2code` so you can *run* and *verify* solves |
+| `pip install algo2code` | The algorithm transpiler on its own. **Zero runtime dependencies**, stdlib only. ([PyPI](https://pypi.org/project/algo2code/)) |
+| `pip install ti-runtime` | The neutral Taichi runtime: vector primitives, Tier-1 `@ti.func` helpers, injection seams. ([PyPI](https://pypi.org/project/ti-runtime/)) |
+| `pip install "mechdsl-workbench[mechdsl]"` | The browser workbench plus the engine, in one command. ([PyPI](https://pypi.org/project/mechdsl-workbench/)) |
+
+All five are released together and currently sit at **0.2.1**.
+
+## Requirements
+
+- **Python 3.11–3.13** for `mechdsl-core`, `algo2code`, and `ti-runtime`
+  (`requires-python = ">=3.11,<3.14"`).
+- **Python 3.12** for `mechdsl-workbench`, which pins `>=3.12,<3.13`.
+- No compiler toolchain, no system FEM library. Taichi ships prebuilt wheels and
+  JIT-compiles to CPU or GPU at run time.
+
+## Install from PyPI
+
+### Just the compiler (lean, Taichi-free)
+
+```bash
+pip install mechdsl-core
+```
+
+This is everything you need to **emit** code: parse `% mechanics` directives, derive
+stress and tangent symbolically, plan contractions, and print Taichi source. It pulls
+only `sympy`, `numpy`, `scipy`, `opt-einsum`, `pyyaml`, and `nrpylatex` — no Taichi, so
+the install stays small and imports cleanly in Taichi-free environments.
+
+```python
+from mechdsl import compile_latex
+
+bundle = compile_latex("% mechanics dim 3\n% mechanics cell hex8\n"
+                       "% mechanics formulation total_lagrangian\n"
+                       "% mechanics material svk --E 200e3 --nu 0.3\n")
+print(bundle.content_hash())
+```
+
+### The full engine (run and verify solves)
+
+```bash
+pip install "mechdsl-core[verify]"
+```
+
+The `verify` extra adds `taichi`, `ti-runtime`, and `algo2code` — the complete
+installation. Expect a noticeably larger download; Taichi alone is around 170 MB.
+Take this one if you want to execute generated kernels, run the verification
+harness, or use the generated matrix-free PCG solver.
+
+!!! info "Why the split?"
+    Only `mechdsl.integration.verify()` ever touches Taichi, and it imports it lazily
+    at call time. The emit, transpile, `capabilities()`, and `model_catalog()`
+    surfaces are proven Taichi-free by the test suite, so downstream consumers can
+    depend on `mechdsl-core` for code generation without pulling Taichi into their
+    dependency closure.
+
+### The satellite packages alone
+
+```bash
+pip install algo2code     # LaTeX algpseudocode -> executable code; stdlib-only
+pip install ti-runtime    # Taichi primitives + injection seams for generated code
+```
+
+`algo2code` never imports `mechdsl`, and `ti-runtime` never imports `mechdsl` either —
+generated artifacts depend on `ti_runtime`, not on the compiler that produced them. Both
+are usable standalone.
+
+## Install from source
+
+Use this if you want the `examples/` scripts, the test suite, or you intend to
+contribute. The repository is a [uv](https://docs.astral.sh/uv/) workspace holding all
+three monorepo packages.
+
+```bash
+git clone https://github.com/CEmM2/MechDSL.git
+cd MechDSL
+uv sync --all-packages --all-groups --all-extras
+```
+
+Verify the install with the fast test tier:
+
+```bash
+uv run pytest -m "not slow and not gpu" -q
+```
+
+!!! warning "Inside the workspace, always go through `uv run`"
+    Never call `python`, `pytest`, `ruff`, or `mypy` directly in a source checkout —
+    they may not be on your PATH or may pick up the wrong environment. Prefix every
+    project command with `uv run`. (This applies to the source workflow only; a
+    `pip install`ed MechDSL is an ordinary package in whatever environment you put it.)
+
+## Command-line entry points
+
+`mechdsl-core` installs one console script:
+
+```bash
+mechdsl-lawgen --help              # emit constitutive-law carriers for the ticonstit target
+mechdsl-lawgen compile law.yaml    # ...with --dry-run to print the plan and write nothing
+```
+
+`mechdsl-workbench` installs its own launcher — see [the workbench page](workbench.md).
+
+## Where to next
+
+<div class="grid cards" markdown>
+
+- :material-rocket-launch: **[mechdsl-core getting started](mechdsl-core/getting-started.md)** — compile your first solver bundle.
+- :material-cog-transfer: **[algo2code getting started](algo2code/getting-started.md)** — transpile your first algorithm.
+- :material-application-brackets: **[Browser workbench](workbench.md)** — try the language without writing a script.
+- :material-help-circle: **[FAQ & troubleshooting](reference/faq.md)** — when something doesn't install or run.
+
+</div>