BlockScience · rororowyourboat · Mar 4, 2026 · Mar 4, 2026 · Mar 4, 2026 · Mar 4, 2026
diff --git a/docs/examples/examples/evolution-of-trust.md b/docs/examples/examples/evolution-of-trust.md
@@ -22,13 +22,13 @@ system = pipeline.feedback([payoff -> decisions])
 
 ```mermaid
 flowchart TD
-    subgraph Simultaneous Decisions
+    subgraph Decisions[Simultaneous Decisions]
         Alice[Alice Decision]
         Bob[Bob Decision]
     end
-    Simultaneous Decisions --> Payoff[[Payoff Computation]]
-    Payoff -.Alice Payoff.-> Alice
-    Payoff -.Bob Payoff.-> Bob
+    Decisions --> Payoff[[Payoff Computation]]
+    Payoff -. Alice Payoff .-> Alice
+    Payoff -. Bob Payoff .-> Bob
 ```
 
 ## What You'll Learn

diff --git a/docs/guides/dsl-roadmap.md b/docs/guides/dsl-roadmap.md
@@ -27,7 +27,7 @@ All three compile to `GDSSpec` / `SystemIR` and produce clean canonical decompos
 
 ## DSL Contract Checklist
 
-Every new DSL must answer the [Semantic Layer Contract](../framework/guide/architecture.md#4-the-semantic-layer-contract) — eight questions that fully specify how a domain maps onto the composition algebra:
+Every new DSL must answer the **Semantic Layer Contract** — eight questions that fully specify how a domain maps onto the [composition algebra](../framework/guide/architecture.md):
 
 1. **Block semantics** — what does a block represent?
 2. **Sequential (`>>`)** — what operation is induced?
@@ -65,7 +65,7 @@ Before the first external release of a new DSL:
 
 ## Potential Future DSLs
 
-These formalisms are in-scope per the [architecture scope boundary](../framework/guide/architecture.md#5-scope-boundary) and should compile to the existing substrate without architectural changes:
+These formalisms are in-scope per the [architecture](../framework/guide/architecture.md) scope boundary and should compile to the existing substrate without architectural changes:
 
 | Formalism | Expected Mapping | Complexity |
 |---|---|---|

diff --git a/docs/index.md b/docs/index.md
@@ -2,24 +2,59 @@
 
 **Typed compositional specifications for complex systems**, grounded in [Generalized Dynamical Systems](https://doi.org/10.57938/e8d456ea-d975-4111-ac41-052ce73cb0cc) theory (Zargham & Shorish, 2022).
 
-## Installation
+GDS gives you a composition algebra for modeling complex systems — from epidemics and control loops to game theory and software architecture — with built-in verification, visualization, and a shared formal foundation.
 
-Install individual packages from PyPI as needed:
+## Where to Start
 
-```bash
-pip install gds-framework    # Core library
-pip install gds-viz          # Visualization
-pip install gds-stockflow    # Stock-flow DSL
-pip install gds-control      # Control systems DSL
-pip install gds-games        # Game theory DSL
-pip install gds-software     # Software architecture DSL
-pip install gds-business     # Business dynamics DSL
-pip install gds-examples     # Tutorial models
-```
+<div class="grid cards" markdown>
+
+-   :material-rocket-launch:{ .lg .middle } **New to GDS?**
+
+    ---
+
+    Follow the hands-on tutorial to build your first model in minutes.
+
+    [:octicons-arrow-right-24: Start Here](tutorials/getting-started.md)
+
+-   :material-map-marker-path:{ .lg .middle } **Guided Learning Path**
+
+    ---
+
+    Work through seven example models in recommended order, from simple to complex.
+
+    [:octicons-arrow-right-24: Learning Path](examples/learning-path.md)
+
+-   :material-swap-horizontal:{ .lg .middle } **Which DSL Should I Use?**
+
+    ---
+
+    Compare all seven domain DSLs and pick the right one for your problem.
+
+    [:octicons-arrow-right-24: Choosing a DSL](guides/choosing-a-dsl.md)
+
+-   :material-translate:{ .lg .middle } **Rosetta Stone**
+
+    ---
+
+    See the same problem modeled with stockflow, control, and game theory DSLs side by side.
 
-!!! note "PyPI names differ from import names"
-    Each package's PyPI name (what you `pip install`) differs from its Python import name.
-    Use the table below as a reference.
+    [:octicons-arrow-right-24: Rosetta Stone](guides/rosetta-stone.md)
+
+</div>
+
+## Interactive Notebooks
+
+Key guides include embedded [marimo](https://marimo.io) notebooks — run code, tweak parameters, and see results directly in the docs. No local setup required.
+
+| Guide | What You'll Explore |
+|-------|---------------------|
+| **[Getting Started](guides/getting-started.md)** | Build a thermostat model in 5 progressive stages |
+| **[Rosetta Stone](guides/rosetta-stone.md)** | Same problem modeled with three different DSLs |
+| **[Verification](guides/verification.md)** | All 3 verification layers with deliberately broken models |
+| **[Visualization](guides/visualization.md)** | 6 view types, 5 themes, cross-DSL rendering |
+| **[Interoperability](guides/interoperability.md)** | Cross-DSL composition and data exchange |
+
+## Packages
 
 | PyPI Package | Import Name | Description |
 |---|---|---|
@@ -32,50 +67,29 @@ pip install gds-examples     # Tutorial models
 | `gds-business` | `gds_business` | Business dynamics DSL (CLD, supply chain, value stream map) |
 | `gds-examples` | — | Tutorial models demonstrating framework features |
 
-### For developers
+## Installation
 
-To work on the monorepo with all packages linked locally:
+Install individual packages from PyPI as needed:
 
 ```bash
-git clone https://github.com/BlockScience/gds-core.git
-cd gds-core
-uv sync --all-packages
+pip install gds-framework    # Core library
+pip install gds-viz          # Visualization
+pip install gds-stockflow    # Stock-flow DSL
+pip install gds-control      # Control systems DSL
+pip install gds-games        # Game theory DSL
+pip install gds-software     # Software architecture DSL
+pip install gds-business     # Business dynamics DSL
+pip install gds-examples     # Tutorial models
 ```
 
-## Quick Start
+For development (all packages linked locally):
 
-```python
-from gds import (
-    BoundaryAction, Policy, Mechanism,
-    GDSSpec, compile_system, verify,
-    typedef, entity, state_var, space, interface,
-)
+```bash
+git clone https://github.com/BlockScience/gds-core.git
+cd gds-core
+uv sync --all-packages
 ```
 
-## Packages
-
-| Package | Docs |
-|---------|------|
-| **[gds-framework](framework/index.md)** | Core engine — blocks, composition algebra, compiler, verification |
-| **[gds-viz](viz/index.md)** | Mermaid diagram renderers for GDS specifications |
-| **gds-stockflow** | Declarative stock-flow DSL over GDS semantics |
-| **gds-control** | State-space control DSL over GDS semantics |
-| **[gds-games](games/index.md)** | Typed DSL for compositional game theory (Open Games) |
-| **gds-software** | Software architecture DSL — DFD, state machine, component, C4, ERD, dependency |
-| **[gds-business](business/index.md)** | Business dynamics DSL — CLD, supply chain, value stream map |
-| **[gds-examples](examples/index.md)** | Six tutorial models demonstrating every framework feature |
-
-## Guides
-
-Interactive tutorials with code, diagrams, and runnable marimo notebooks:
-
-| Guide | What You'll Learn |
-|-------|-------------------|
-| **[Getting Started](guides/getting-started.md)** | Build a thermostat model in 5 progressive stages — from raw blocks to DSL to verification |
-| **[Rosetta Stone](guides/rosetta-stone.md)** | Same resource-pool problem modeled with stockflow, control, and game theory DSLs |
-| **[Verification](guides/verification.md)** | All 3 verification layers demonstrated with deliberately broken models |
-| **[Visualization](guides/visualization.md)** | 6 view types, 5 themes, and cross-DSL rendering with gds-viz |
-
 ## Architecture
 
 ```