Merge pull request #81 from BlockScience/dev

docs + fix: improve llms.txt and fix canonical formula

Author: rororowyourboat

CLAUDE.md

@@ -16,6 +16,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 | gds-stockflow | `stockflow` | `packages/gds-stockflow/` |
 | gds-control | `gds_control` | `packages/gds-control/` |
 | gds-software | `gds_software` | `packages/gds-software/` |
+| gds-sim | `gds_sim` | `packages/gds-sim/` |
 | gds-examples | — | `packages/gds-examples/` |
 
 ## Commands
@@ -32,12 +33,13 @@ uv run --package gds-stockflow pytest packages/gds-stockflow/tests -v
 uv run --package gds-control pytest packages/gds-control/tests -v
 uv run --package gds-software pytest packages/gds-software/tests -v
 uv run --package gds-examples pytest packages/gds-examples -v
+uv run --package gds-sim pytest packages/gds-sim/tests -v
 
 # Run a single test
 uv run --package gds-framework pytest packages/gds-framework/tests/test_blocks.py::TestStackComposition::test_rshift_operator -v
 
 # Run all tests across all packages
-uv run --package gds-framework pytest packages/gds-framework/tests packages/gds-viz/tests packages/gds-games/tests packages/gds-stockflow/tests packages/gds-control/tests packages/gds-software/tests packages/gds-examples -v
+uv run --package gds-framework pytest packages/gds-framework/tests packages/gds-viz/tests packages/gds-games/tests packages/gds-stockflow/tests packages/gds-control/tests packages/gds-software/tests packages/gds-examples packages/gds-sim/tests -v
 
 # Lint & format
 uv run ruff check packages/
@@ -68,6 +70,8 @@ gds-control    ←  control systems DSL (depends on gds-framework)
 gds-software   ←  software architecture DSL (depends on gds-framework)
     ↑
 gds-examples   ←  tutorials (depends on gds-framework + gds-viz)
+
+gds-sim        ←  simulation engine (standalone — no gds-framework dep, only pydantic)
 ```
 
 ### gds-framework: Two-Layer Design

docs/guides/getting-started.md

@@ -422,9 +422,15 @@ You have built a complete GDS specification for a thermostat system, progressing
 
 From here, explore the [example models](../examples/index.md) or the [Rosetta Stone](rosetta-stone.md) guide to see the same system through different DSL lenses.
 
-## Running Interactively
+## Interactive Notebook
 
-The guide includes a [marimo notebook](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/guides/getting_started/notebook.py) for interactive exploration:
+/// marimo-embed-file
+    filepath: packages/gds-examples/guides/getting_started/notebook.py
+    height: 800px
+    mode: read
+///
+
+To run the notebook locally:
 
 ```bash
 uv run marimo run packages/gds-examples/guides/getting_started/notebook.py

docs/guides/interoperability.md

@@ -232,31 +232,47 @@ This validates GDS as an **interoperability substrate**, not just a modeling fra
 
 ## Running the Examples
 
-### Nash equilibrium analysis
+### Nash Equilibrium Analysis
+
+/// marimo-embed-file
+    filepath: packages/gds-examples/guides/nash_equilibrium/notebook.py
+    height: 800px
+    mode: read
+///
+
+To run locally:
 
 ```bash
-# Install dependencies
 uv sync --all-packages --extra nash
+cd packages/gds-examples && \
+    uv run marimo run guides/nash_equilibrium/notebook.py
+```
 
+```bash
 # Run tests (22 tests)
 uv run --package gds-examples pytest \
     packages/gds-examples/games/prisoners_dilemma_nash/ -v
+```
+
+### Evolution of Trust Simulation
+
+/// marimo-embed-file
+    filepath: packages/gds-examples/guides/evolution_of_trust/notebook.py
+    height: 800px
+    mode: read
+///
 
-# Interactive notebook
+To run locally:
+
+```bash
 cd packages/gds-examples && \
-    uv run marimo run guides/nash_equilibrium/notebook.py
+    uv run marimo run guides/evolution_of_trust/notebook.py
 ```
 
-### Evolution of Trust simulation
-
 ```bash
 # Run tests (71 tests)
 uv run --package gds-examples pytest \
     packages/gds-examples/games/evolution_of_trust/ -v
-
-# Interactive notebook (with plotly charts)
-cd packages/gds-examples && \
-    uv run marimo run guides/evolution_of_trust/notebook.py
 ```
 
 ### Source files

docs/guides/rosetta-stone.md

@@ -313,9 +313,15 @@ from guides.rosetta.comparison import canonical_spectrum_table
 print(canonical_spectrum_table())
 ```
 
-## Running Interactively
+## Interactive Notebook
 
-The guide includes a [marimo notebook](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/guides/rosetta/notebook.py) for interactive exploration with live Mermaid rendering and dropdown selectors:
+/// marimo-embed-file
+    filepath: packages/gds-examples/guides/rosetta/notebook.py
+    height: 800px
+    mode: read
+///
+
+To run the notebook locally:
 
 ```bash
 uv run marimo run packages/gds-examples/guides/rosetta/notebook.py

docs/guides/verification.md

@@ -372,9 +372,15 @@ for finding in report.findings:
     print(f"{finding.check_id}: {finding.message}")
 ```
 
-## Running Interactively
+## Interactive Notebook
 
-The guide includes a [marimo notebook](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/guides/verification/notebook.py) with interactive dropdowns for selecting broken models and watching checks in real time:
+/// marimo-embed-file
+    filepath: packages/gds-examples/guides/verification/notebook.py
+    height: 800px
+    mode: read
+///
+
+To run the notebook locally:
 
 ```bash
 uv run marimo run packages/gds-examples/guides/verification/notebook.py

docs/guides/visualization.md

@@ -203,9 +203,15 @@ mermaid_str = system_to_mermaid(system, theme="dark")
 # Paste into GitHub markdown, mermaid.live, or mo.mermaid()
 ```
 
-## Running Interactively
+## Interactive Notebook
 
-The guide includes a [marimo notebook](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/guides/visualization/notebook.py) with interactive dropdowns for selecting views, themes, and models:
+/// marimo-embed-file
+    filepath: packages/gds-examples/guides/visualization/notebook.py
+    height: 800px
+    mode: read
+///
+
+To run the notebook locally:
 
 ```bash
 uv run marimo run packages/gds-examples/guides/visualization/notebook.py

mkdocs.yml

@@ -27,6 +27,7 @@ theme:
 
 plugins:
   - search
+  - marimo
   - mkdocstrings:
       handlers:
         python:
@@ -44,55 +45,69 @@ plugins:
         compile to the same GDS IR, validating it as a universal transition calculus.
       full_output: llms-full.txt
       sections:
-        Framework:
-          - index.md
-          - framework/index.md
-          - framework/quick-reference.md
-          - framework/getting-started/install.md
-          - framework/getting-started/quickstart.md
+        Framework (gds-framework):
+          - {index.md: "Monorepo landing page — package overview, install, architecture"}
+          - {framework/index.md: "Core engine — blocks, composition algebra, compiler, verification"}
+          - {framework/quick-reference.md: "Cheat sheet for types, blocks, composition, and verification"}
+          - {framework/getting-started/install.md: "Installation for users and developers"}
+          - {framework/getting-started/quickstart.md: "Build a thermostat spec in 5 minutes"}
           - framework/guide/*.md
-          - framework/design/*.md
           - framework/api/*.md
-        Visualization:
-          - viz/index.md
-          - viz/getting-started.md
+        Visualization (gds-viz):
+          - {viz/index.md: "Mermaid diagram renderers for GDS specifications"}
+          - {viz/getting-started.md: "First diagram in 3 lines of code"}
           - viz/guide/*.md
           - viz/api/*.md
-        Games:
-          - games/index.md
-          - games/getting-started.md
+        Games (gds-games / ogs):
+          - {games/index.md: "Typed DSL for compositional game theory (Open Games)"}
+          - {games/getting-started.md: "Model a Prisoner's Dilemma game"}
           - games/guide/*.md
           - games/design/*.md
           - games/api/*.md
-        Business:
-          - business/index.md
-          - business/getting-started.md
+        Business (gds-business):
+          - {business/index.md: "Business dynamics DSL — CLD, supply chain, value stream map"}
+          - {business/getting-started.md: "Model a causal loop diagram"}
           - business/guide/*.md
           - business/api/*.md
-        Stock-Flow:
-          - stockflow/index.md
-          - stockflow/getting-started.md
+        Stock-Flow (gds-stockflow):
+          - {stockflow/index.md: "Declarative stock-flow DSL over GDS semantics"}
+          - {stockflow/getting-started.md: "Model an SIR epidemic as stocks and flows"}
           - stockflow/guide/*.md
           - stockflow/api/*.md
-        Control:
-          - control/index.md
-          - control/getting-started.md
+        Control (gds-control):
+          - {control/index.md: "State-space control systems DSL over GDS semantics"}
+          - {control/getting-started.md: "Model a PID thermostat controller"}
           - control/guide/*.md
           - control/api/*.md
-        Software:
-          - software/index.md
-          - software/getting-started.md
+        Software (gds-software):
+          - {software/index.md: "Software architecture DSL — DFD, state machine, C4, ERD, component, dependency"}
+          - {software/getting-started.md: "Model a data flow diagram"}
           - software/guide/*.md
           - software/api/*.md
         Examples:
-          - examples/*.md
+          - {examples/index.md: "Six tutorial models demonstrating every framework feature"}
+          - {examples/learning-path.md: "Recommended order for working through examples"}
+          - examples/building-models.md
+          - examples/feature-matrix.md
           - examples/examples/*.md
         Tutorials:
           - tutorials/*.md
         Guides:
-          - guides/*.md
+          - {guides/getting-started.md: "Build a thermostat model in 5 progressive stages"}
+          - {guides/choosing-a-dsl.md: "Decision guide for picking the right DSL"}
+          - {guides/best-practices.md: "Patterns and anti-patterns for GDS modeling"}
+          - {guides/rosetta-stone.md: "Same problem modeled with stockflow, control, and games"}
+          - {guides/verification.md: "All 3 verification layers with deliberately broken models"}
+          - {guides/visualization.md: "6 view types, 5 themes, cross-DSL rendering"}
+          - guides/real-world-patterns.md
+          - guides/troubleshooting.md
+          - guides/interoperability.md
+          - guides/architecture-milestone-layer0.md
+          - guides/dsl-roadmap.md
+          - guides/research-boundaries.md
+          - guides/view-stratification.md
         Ecosystem:
-          - framework/ecosystem.md
+          - {framework/ecosystem.md: "All packages, their imports, and dependency relationships"}
 
 markdown_extensions:
   - admonition
@@ -131,11 +146,6 @@ nav:
           - Pipeline: framework/guide/pipeline.md
           - Verification: framework/guide/verification.md
           - Glossary: framework/guide/glossary.md
-      - Design:
-          - GDS Deep Dive: framework/design/gds-deepdive.md
-          - v0.2 Design: framework/design/v0.2-design.md
-          - Proposals:
-              - Entity Redesign: framework/design/proposals/entity-redesign.md
       - API Reference:
           - Overview: framework/api/index.md
           - gds: framework/api/init.md