dimensionalOS · swstica · May 6, 2026 · May 6, 2026 · May 6, 2026 · May 6, 2026
diff --git a/docs/agents/docs/codeblocks.md → docs/agents/docs/codeblocks.mdx b/docs/agents/docs/codeblocks.md → docs/agents/docs/codeblocks.mdx
@@ -1,5 +1,3 @@
-# Executable Code Blocks
-
 We use [md-babel-py](https://github.com/leshy/md-babel-py/) to execute code blocks in markdown and insert results.
 
 ## Golden Rule
@@ -38,7 +36,7 @@ Use `skip` when a block would pull in **CUDA / GPU-only** stacks (for example pe
 
 Execute code blocks in markdown files and insert the results.
 
-![Demo](assets/screencast.gif)
+<img alt="Demo" src="assets/screencast.gif" />
 
 **Use cases:**
 - Keep documentation examples up-to-date automatically
@@ -54,7 +52,7 @@ Execute code blocks in markdown files and insert the results.
 echo "cwd: $(pwd)"
 ```
 
-<!--Result:-->
+{/* Result: */}
 ```
 cwd: /work
 ```
@@ -66,7 +64,7 @@ a = "hello world"
 print(a)
 ```
 
-<!--Result:-->
+{/* Result: */}
 ```
 hello world
 ```
@@ -77,7 +75,7 @@ Sessions preserve state between code blocks:
 print(a, "again")
 ```
 
-<!--Result:-->
+{/* Result: */}
 ```
 hello world again
 ```
@@ -89,7 +87,7 @@ console.log("Hello from Node.js");
 console.log(`Node version: ${process.version}`);
 ```
 
-<!--Result:-->
+{/* Result: */}
 ```
 Hello from Node.js
 Node version: v22.21.1
@@ -112,8 +110,8 @@ plt.grid(alpha=0.3)
 plt.savefig('{output}', transparent=True)
 ```
 
-<!--Result:-->
-![output](assets/matplotlib-demo.svg)
+{/* Result: */}
+<img alt="output" src="assets/matplotlib-demo.svg" />
 
 ### Pikchr
 
@@ -155,8 +153,8 @@ arrow from X to Out.w
 
 </details>
 
-<!--Result:-->
-![output](assets/pikchr-demo.svg)
+{/* Result: */}
+<img alt="output" src="assets/pikchr-demo.svg" />
 
 ### Asymptote
 
@@ -183,8 +181,8 @@ xaxis("$x$",BottomTop,LeftTicks,p=white);
 yaxis("$dP/dx$",LeftRight,RightTicks(trailingzero),p=white);
 ```
 
-<!--Result:-->
-![output](assets/histogram.svg)
+{/* Result: */}
+<img alt="output" src="assets/histogram.svg" />
 
 ### Graphviz
 
@@ -193,8 +191,8 @@ A -> B -> C
 A -> C
 ```
 
-<!--Result:-->
-![output](assets/graph.svg)
+{/* Result: */}
+<img alt="output" src="assets/graph.svg" />
 
 ### OpenSCAD
 
@@ -203,8 +201,8 @@ cube([10, 10, 10]);
 sphere(r=7);
 ```
 
-<!--Result:-->
-![output](assets/cube-sphere.png)
+{/* Result: */}
+<img alt="output" src="assets/cube-sphere.png" />
 
 ### Diagon
 
@@ -214,7 +212,7 @@ ASCII art diagrams:
 1 + 1/2 + sum(i,0,10)
 ```
 
-<!--Result:-->
+{/* Result: */}
 ```
         10
         ___
@@ -229,7 +227,7 @@ A -> B -> C
 A -> C
 ```
 
-<!--Result:-->
+{/* Result: */}
 ```
 ┌───┐
 │A  │

diff --git a/docs/agents/docs/doclinks.md → docs/agents/docs/doclinks.mdx b/docs/agents/docs/doclinks.md → docs/agents/docs/doclinks.mdx
@@ -4,13 +4,13 @@ Full documentation if needed: [`utils/docs/doclinks.md`](/dimos/utils/docs/docli
 
 ## Syntax
 
-<!-- doclinks-ignore-start -->
+{/*  doclinks-ignore-start  */}
 | Pattern     | Example                                             |
 |-------------|-----------------------------------------------------|
 | Code file   | `[`service/spec.py`]()` → resolves path             |
 | With symbol | `Configurable` in `[`spec.py`]()` → adds `#L<line>` |
 | Doc link    | `[Configuration](.md)` → resolves to doc            |
-<!-- doclinks-ignore-end -->
+{/*  doclinks-ignore-end  */}
 
 ## Usage
 

diff --git a/docs/agents/docs/index.md → docs/agents/docs/overview.mdx b/docs/agents/docs/index.md → docs/agents/docs/overview.mdx
@@ -1,6 +1,3 @@
-
-# Code Blocks
-
 **All code blocks must be executable.**
 Never write illustrative/pseudo code blocks.
 If you're showing an API usage pattern, create a minimal working example that actually runs. This ensures documentation stays correct as the codebase evolves.
@@ -75,8 +72,8 @@ C: box "Step 3" rad 5px fit wid 170% ht 170%
 
 </details>
 
-<!--Result:-->
-![output](assets/pikchr_basic.svg)
+{/* Result: */}
+<img alt="output" src="assets/pikchr_basic.svg" />
 
 ## Box sizing
 
@@ -99,8 +96,8 @@ C: box "two lines" "of text" rad 5px fit wid 170% ht 170%
 
 </details>
 
-<!--Result:-->
-![output](assets/pikchr_sizing.svg)
+{/* Result: */}
+<img alt="output" src="assets/pikchr_sizing.svg" />
 
 The pattern `fit wid 170% ht 170%` means: auto-size to text, then scale width by 170% and height by 170%.
 
@@ -120,8 +117,8 @@ B: box "Step 2" rad 5px fit wid 170% ht 170%
 
 </details>
 
-<!--Result:-->
-![output](assets/pikchr_explicit.svg)
+{/* Result: */}
+<img alt="output" src="assets/pikchr_explicit.svg" />
 
 ## Common settings
 
@@ -156,8 +153,8 @@ D: box "Path B" rad 5px fit wid 170% ht 170%
 
 </details>
 
-<!--Result:-->
-![output](assets/pikchr_branch.svg)
+{/* Result: */}
+<img alt="output" src="assets/pikchr_branch.svg" />
 
 **Tip:** For tree/hierarchy diagrams, prefer left-to-right layout (root on left, children branching right). This reads more naturally and avoids awkward vertical stacking.
 
@@ -176,8 +173,8 @@ text "label below" at (A.x, A.y - 0.4in)
 
 </details>
 
-<!--Result:-->
-![output](assets/pikchr_labels.svg)
+{/* Result: */}
+<img alt="output" src="assets/pikchr_labels.svg" />
 
 ## Reference
 

diff --git a/docs/agents/index.md → docs/agents/overview.mdx b/docs/agents/index.md → docs/agents/overview.mdx
@@ -1,5 +1,3 @@
-# For Agents
-
 ├── testing.md (docs about writing tests)
 ├── docs (these are docs about writing docs)
 │   ├── codeblocks.md

diff --git a/docs/agents/style.md → docs/agents/style.mdx b/docs/agents/style.md → docs/agents/style.mdx
@@ -1,5 +1,3 @@
-# Code Style Guidelines
-
 Rules for writing code in dimos. These address recurring issues found in code review.
 
 ## No comment banners

diff --git a/docs/agents/testing.md → docs/agents/testing.mdx b/docs/agents/testing.md → docs/agents/testing.mdx
@@ -1,5 +1,3 @@
-# Testing Guidelines
-
 Rules for writing tests in dimos. These address recurring issues found in code review.
 
 For grid testing (spec/impl tests across multiple backends), see [Grid Testing Strategy](/docs/development/grid_testing.md).

diff --git a/docs/capabilities/agents/readme.md → docs/capabilities/agents.mdx b/docs/capabilities/agents/readme.md → docs/capabilities/agents.mdx
@@ -1,5 +1,3 @@
-# Agents
-
 LLM agents run as native DimOS modules. They subscribe to camera, LiDAR, odometry, and spatial memory streams and they control the robot through skills.
 
 ## Architecture

diff --git a/...ities/manipulation/adding_a_custom_arm.md → ...ties/manipulation/adding_a_custom_arm.mdx b/...ities/manipulation/adding_a_custom_arm.md → ...ties/manipulation/adding_a_custom_arm.mdx
@@ -1,5 +1,3 @@
-# How to Integrate a New Manipulator Arm
-
 This guide walks through integrating a new robot arm with DimOS, from writing the hardware adapter to creating blueprints for planning and control.
 
 ## Architecture Overview

diff --git a/...ities/manipulation/openarm_integration.md → ...ties/manipulation/openarm_integration.mdx b/...ities/manipulation/openarm_integration.md → ...ties/manipulation/openarm_integration.mdx
@@ -1,5 +1,3 @@
-# OpenArm Integration
-
 Guide for running the **OpenArm** — an open-source bimanual 7-DOF research arm built from Damiao DM-J quasi-direct-drive motors — under the dimos manipulation + control stack.
 
 **If you're standing in front of the hardware and just want to run it, skip to [Quick start](#quick-start).**

diff --git a/docs/capabilities/manipulation/readme.md → docs/capabilities/manipulation/overview.mdx b/docs/capabilities/manipulation/readme.md → docs/capabilities/manipulation/overview.mdx
@@ -1,5 +1,3 @@
-# Manipulation
-
 Motion planning and teleoperation for robotic manipulators. Uses Drake for physics simulation and Meshcat for 3D visualization.
 
 ## Quick Start

diff --git a/docs/capabilities/memory/algo_comparison.md → docs/capabilities/memory/algo_comparison.mdx b/docs/capabilities/memory/algo_comparison.md → docs/capabilities/memory/algo_comparison.mdx
@@ -84,9 +84,9 @@ delta_plot.to_svg("assets/plot_brightness_algo_delta.svg")
 
 ```
 
-![output](assets/plot_brightness_algo.svg)
+<img alt="output" src="assets/plot_brightness_algo.svg" />
 
-![output](assets/plot_brightness_algo_delta.svg)
+<img alt="output" src="assets/plot_brightness_algo_delta.svg" />
 
 We see that new algo is strictly better.
 

diff --git a/docs/capabilities/memory/index.md → docs/capabilities/memory/overview.mdx b/docs/capabilities/memory/index.md → docs/capabilities/memory/overview.mdx
@@ -1,4 +1,5 @@
-<details><summary>Python</summary>
+<details>
+<summary>Python</summary>
 
 ```python fold session=mem output=none
 import pickle
@@ -12,6 +13,7 @@ from dimos.utils.data import get_data
 from dimos.memory2.vis.space.elements import Point
 ```
 
+
 </details>
 
 we init our recording, investigate available streams
@@ -23,7 +25,7 @@ for name, stream in store.streams.items():
    print(stream.summary())
 ```
 
-<!--Result:-->
+{/* Result: */}
 ```
 Stream("color_image"): 4164 items, 2025-12-26 11:09:08 — 2025-12-26 11:14:00 (292.5s)
 Stream("color_image_embedded"): 267 items, 2025-12-26 11:09:12 — 2025-12-26 11:14:00 (288.4s)
@@ -48,7 +50,7 @@ drawing.to_svg("assets/color_image.svg")
 
 our drawing system applies turbo color scheme to timestamps by default
 
-![output](assets/color_image.svg)
+<img alt="output" src="assets/color_image.svg" />
 
 we can create new streams by querying existing streams, and we can save, further transform or draw those
 
@@ -67,7 +69,7 @@ drawing.add(
 drawing.to_svg("assets/speed.svg")
 ```
 
-![output](assets/speed.svg)
+<img alt="output" src="assets/speed.svg" />
 
 we can do all kinds of things with this, for example map out room lighting
 
@@ -87,7 +89,7 @@ drawing.add(
 drawing.to_svg("assets/brightness.svg")
 ```
 
-![output](assets/brightness.svg)
+<img alt="output" src="assets/brightness.svg" />
 
 So knowing above, we can create embeddings for the full stream,
 
@@ -134,7 +136,7 @@ drawing.add(store.streams.color_image_embedded.search(search_vector))
 drawing.to_svg("assets/embedding.svg")
 ```
 
-![output](assets/embedding.svg)
+<img alt="output" src="assets/embedding.svg" />
 
 We don't really have to deal with the whole global map actually, let's get top 10 embeddings, and render only lidar around those.
 
@@ -160,15 +162,16 @@ drawing.add(matches)
 drawing.to_svg("assets/embedding_focused.svg")
 ```
 
-<!--Result:-->
+{/* Result: */}
 ```
 Stream("color_image_embedded") | vector_search(k=30)
 08:19:54.129 [inf][dimos/mapping/voxels.py       ] VoxelGrid using device: CUDA:0
 ```
 
-![output](assets/embedding_focused.svg)
+<img alt="output" src="assets/embedding_focused.svg" />
 
-<details><summary>Python</summary>
+<details>
+<summary>Python</summary>
 
 ```python fold session=mem
 import matplotlib
@@ -199,6 +202,7 @@ def plot_mosaic(frames, path, cols=5):
 
 ```
 
+
 </details>
 
 let's view those images
@@ -207,4 +211,4 @@ let's view those images
 plot_mosaic(matches.map(lambda obs: obs.data).to_list(), "assets/grid.png")
 ```
 
-![output](assets/grid.png)
+<img alt="output" src="assets/grid.png" />