DotBots · geonnave · Sep 29, 2026 · Sep 29, 2026 · Sep 29, 2026 · Sep 29, 2026
diff --git a/README.md b/README.md
@@ -47,10 +47,22 @@ Every command and flag is documented in the [CLI reference][cli-doc].
 
 See the whole thing run with nothing but Python!
 
-The command below will run a simulated swarm, which you can observe in the web console at http://localhost:8000/console/ :
+First, in an empty folder, write a config:
 
 ```bash
-dotbot run simulator
+dotbot config init
+```
+
+This writes `./dotbot.toml` with a site named `default`: a 2 x 2 m **field**,
+where experiments happen, and a **staging** strip below it, where robots park.
+`--field 1.5m` or `--field 2x3m` sizes the field, and the rest follows from it.
+Commands run from this folder read the file, and it is yours to edit once you
+measure a real room.
+
+Then run a simulated swarm, which you can observe in the web console at http://localhost:8000/console/ :
+
+```bash
+dotbot run simulator --robots 20
 ```
 
 The console opens automatically; pass `--headless` to suppress it (it's still
@@ -153,32 +165,31 @@ is in the [`swarm` reference][swarm-doc].
 ### Calibrate positions (optional)
 
 Give the DotBots real-world `(x, y)` with Lighthouse 2. It's a two-step flow:
-**collect** a calibration from one DotBot over the air, then **push** it to the
-whole fleet - a single DotBot's capture calibrates the shared arena. This needs
-the `[calibrate]` extra (opencv, for the homography solve):
+**collect** a calibration by placing one DotBot on the four corners of your
+site's field, then **push** it to the whole fleet - one capture calibrates the
+whole site. This needs the `[calibrate]` extra (opencv, for the homography
+solve):
 
 ```bash
 pip install 'pydotbot[calibrate]'
 ```
 
-First, collect from one DotBot. Get its address from `dotbot swarm status` (the
-**Device Addr** column):
+First, flash the `calibrate` app and collect. Each corner is captured when you
+press the DotBot's button:
 
 ```bash
-dotbot swarm status                                           # pick one Device Addr, e.g., BDF2B04BC00D2725
-dotbot swarm stop                                             # DotBots must be idle to capture
-dotbot swarm calibrate-lh2 collect --device <addr> -d 500     # capture + solve + save
+dotbot swarm flash calibrate -ys          # the app that captures on a button press
+dotbot swarm calibrate-lh2 collect        # the field's four corners -> solve -> save
 ```
 
-`-d` is your reference square's side, in mm. This saves a
-`~/.dotbot/calibrations/calibration-<UTC>.toml`. Then push that file to the
-whole fleet:
+This saves the calibration under `~/.dotbot/calibrations/<site>/` and prints
+its id. Then push it to the whole fleet:
 
 ```bash
-dotbot swarm calibrate-lh2 push ~/.dotbot/calibrations/calibration-<UTC>.toml
+dotbot swarm calibrate-lh2 push <id>
 ```
 
-Full walkthrough - arena sizing and the cabled alternative - is in the
+Full walkthrough - choosing the points and the cabled alternative - is in the
 [LH2 calibration guide][lh2-doc].
 
 ## Going further

diff --git a/config_sample.toml b/config_sample.toml
diff --git a/doc/api/dotbot.rst b/doc/api/dotbot.rst
@@ -33,6 +33,7 @@ Submodules
    dotbot.server
    dotbot.sim
    dotbot.site
+   dotbot.site_packs
    dotbot.stream
    dotbot.trail
    dotbot.twin

diff --git a/doc/api/dotbot.site_packs.rst b/doc/api/dotbot.site_packs.rst
@@ -0,0 +1,7 @@
+dotbot.site_packs module
+========================
+
+.. automodule:: dotbot.site_packs
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/cli/config.md b/doc/cli/config.md
@@ -1,7 +1,7 @@
 # `dotbot config` - inspect and scaffold the config
 
 `dotbot` reads a `dotbot.toml` so commands don't repeat shared settings - your
-gateway connection, swarm id, firmware paths. `config` scaffolds that file and
+gateway connection, swarm id, firmware paths, the site you work on. `config` scaffolds that file and
 shows you what the CLI actually resolved. For the full file format - every key,
 deployments, the precedence rules - see the
 [configuration reference](../reference/configuration.md).
@@ -16,23 +16,54 @@ deployments, the precedence rules - see the
 
 ## `init`
 
-Writes a minimal `./dotbot.toml` - a one-line pointer to the docs, plus any keys
-you pre-fill. `--global` writes your per-machine `~/.dotbot/config.toml` instead;
-`-f/--force` overwrites an existing file.
+Writes a starter `./dotbot.toml` holding a site, so the simulator, calibration
+and the examples have a floor to work on from the first run:
+
+```toml
+site = "default"
+
+# Zero is the top-left corner of the extent, x right, y down, millimetres.
+[sites.default]
+anchor = "top-left corner of a 5 x 5 m floor; the field starts 1.5 m in from each wall"
+extent_mm = [5000, 5000]
+
+[sites.default.areas]
+field   = { x = 1500, y = 1500, w = 2000, h = 2000 }
+staging = { x = 1500, y = 3500, w = 2000, h = 600 }
+```
+
+The **field** is where experiments happen and what a calibration covers; the
+**staging** strip along its bottom edge is where robots park. Once you have
+measured a real room, edit the file: the site is plain TOML, and the
+[configuration reference](../reference/configuration.md#sites) has every key.
 
 ```bash
-dotbot config init                                             # commented starter in ./dotbot.toml
+dotbot config init                                             # ./dotbot.toml with a 2 x 2 m field
+dotbot config init --field 1.5m --site lab                     # a 1.5 x 1.5 m field in a site named lab
 dotbot config init --conn mqtts://broker:8883 --swarm-id 1234  # pre-fill the two common keys
 dotbot config init --global                                    # ~/.dotbot/config.toml
 ```
 
+| Flag | Meaning |
+|---|---|
+| `--field` | The field's size (default `2m`): one value for a square, `WxH` for a rectangle. A bare number is mm, and `1500mm`, `1.5m` and `2x3m` also work; decimals only with `m`. From 100 mm to 100 m. The extent and the staging strip follow from it. Above 5 m on a side it warns that one LH2 station rarely covers that well. |
+| `--site` | The site's name (default `default`); its calibrations are kept under `~/.dotbot/calibrations/<site>/`. |
+| `--conn` / `--swarm-id` | Pre-fill the shared connection and swarm id. |
+| `--global` | Write the per-machine `~/.dotbot/config.toml` instead of `./dotbot.toml`. |
+| `-f`, `--force` | Overwrite an existing file, whole. |
+
+`dotbot.example.toml` in the repository is exactly what `dotbot config init`
+writes with no flags.
+
 > MQTT credentials are never file keys - set `DOTBOT_MQTT_USER` /
 > `DOTBOT_MQTT_PASS` in the environment.
 
 ## `show` / `path`
 
-`show` prints the source file, the selected deployment, and the resolved config
-as TOML - only the keys actually set, not the full schema. `path` prints just
+`show` prints the source file, the selected deployment, the active site, every
+site with its areas' roles and where it was read from (inline, or a site pack's
+folder), and the resolved config as TOML - only the keys actually set, not the
+full schema. `path` prints just
 the file path (or notes that built-in defaults are in use). Both are read-only;
 there is no per-key `set` - edit the file, it's yours.
 
@@ -51,4 +82,5 @@ is in the [configuration reference](../reference/configuration.md#precedence).
 ## See also
 
 - [Configuration reference](../reference/configuration.md) - the file format, every key, deployments, precedence.
+- [`dotbot site`](site.md) - install a site pack, or export a site to share.
 - [`dotbot fw`](fw.md) - reads its `[fw]` keys (`segger_dir`, `firmware_repo`) from this same config.
diff --git a/doc/cli/index.md b/doc/cli/index.md
@@ -7,6 +7,7 @@ device
 swarm
 run
 config
+site
 ```
 
 One CLI for the whole DotBot workflow: build firmware, flash one board, control a
@@ -29,7 +30,9 @@ dotbot --help
 | [`run`](run.md) | Start host processes on your computer - controller, gateway bridge, simulator, demos, teleop. | You need the web UI, a gateway bridge, the simulator, or a demo. |
 
 Beyond the four namespaces, [`config`](config.md) scaffolds and inspects the
-shared `dotbot.toml` the other commands read their defaults from.
+shared `dotbot.toml` the other commands read their defaults from, and
+[`site`](site.md) installs and exports site packs: the floors you work on,
+as folders you can share.
 
 ## Which one do I want?
 
@@ -65,6 +68,7 @@ A few signposts so the namespaces don't blur together:
 - [`swarm`](swarm.md) - run experiments across the fleet.
 - [`run`](run.md) - launch the controller, gateway bridge, simulator, and demos.
 - [`config`](config.md) - scaffold and inspect the shared `dotbot.toml`.
+- [`site`](site.md) - add a site pack to this machine, or export one to share.
 
 Two end-to-end walkthroughs put these together: [build and flash one
 board](device.md), and [operate a swarm over the air](swarm.md).
diff --git a/doc/cli/run.md b/doc/cli/run.md
@@ -41,7 +41,8 @@ dotbot run controller --conn /dev/ttyACM0
 | `--controller-http-host` | interface the API binds to (default `127.0.0.1`, loopback). Pass `0.0.0.0` to reach it from another machine - the API is unauthenticated and `/swarmit/*` reaches the swarmit server through it, so only on a network you trust. |
 | `--headless` | don't open the console in a browser (it's still served) |
 | `--csv-data-output` | record DotBot data to a CSV file. A registered camera also writes `<name>-camera.csv` beside it, with a `<name>-camera.toml` sidecar saying what the columns mean. |
-| `--lh2-calibration` | lighthouse calibration the controller runs on: a file path or an id prefix. Also `[run.controller] lh2_calibration`. |
+| `--site` | the site the session works in: its frame, its areas and where its calibrations are looked up. Also `site` in dotbot.toml, or `DOTBOT_SITE`. |
+| `--lh2-calibration` | lighthouse calibration the controller runs on: a file path, a `--tag` or an id prefix. Refused when it was made in another site. Also `[run.controller] lh2_calibration`; `[run.controller] lh2_calibration_max_age_days` (default 30) warns when it is older. |
 | `--camera-calibration` | overhead camera to draw on the map: a file path, or an id prefix of one under `~/.dotbot/calibrations/<site>/`. Register one with `run calibrate-camera collect`. Also `[run.controller] camera_calibration` in dotbot.toml. |
 | `--camera-detect` / `--no-camera-detect` | run the robot detector on that camera's frames (default on). Off serves the layer as a picture only: nothing detected, drawn, pushed or logged. Also `[run.controller] camera_detect` in dotbot.toml. |
 | `--swarmit-url` | swarmit server behind the console's orchestration panel (default `http://localhost:8001`, matching `swarmit serve`). Also `[run.controller] swarmit_url` in dotbot.toml, or `DOTBOT_SWARMIT_URL`. |
@@ -72,15 +73,21 @@ so it shares the controller's flags and serves the same console.
 ```bash
 dotbot run simulator
 dotbot run simulator --robots 500                  # a generated fleet
+dotbot run simulator --robots 150 --area field+staging
 dotbot run simulator --robots 500 --write-init-state fleet.toml
 dotbot run simulator --simulator-init-state fleet.toml
 ```
 
-`--robots N` places N robots 200 mm apart in a near-square grid centred in the
-site's `field` area (else its first area, else its extent, else a 2 x 2 m
-square), the top half of the rows facing up and the rest down, and refuses a
-count that does not fit. `--write-init-state` saves that fleet as a file to
-edit and reuse with `--simulator-init-state`.
+`--robots N` places N robots 200 mm apart, all facing up, in a grid shaped
+like and centred in `--area`, and refuses a count that does not fit: an area
+holds one robot per 200 mm square. `--area` takes a name from the site's
+areas, `x,y,w,h` in mm or a `+`-joined composite, and defaults to the site's
+[field](../reference/configuration.md#area-roles) (a 2 x 2 m square when the
+site declares nothing); it also places the robots a `--simulator-init-state`
+file gives no position.
+`[run.controller] simulator_area` sets it from the config.
+`--write-init-state` saves that fleet as a file to edit and reuse with
+`--simulator-init-state`.
 
 ## `calibrate-lh2` - capture & apply (cabled, deprecated)
 

diff --git a/doc/cli/site.md b/doc/cli/site.md
@@ -0,0 +1,68 @@
+# `dotbot site` - add and export site packs
+
+A **site pack** is a site in its own folder, so it can be committed, zipped or
+handed to someone: `<name>/site.toml` holds the keys of a `[sites.<name>]`
+table, and an optional `<name>/calibrations/` holds the site's LH2 and camera
+calibration files. `site add` installs one on this machine and `site export`
+writes one. How packs are found, and how they relate to inline `[sites.*]`
+tables, is in the [configuration reference](../reference/configuration.md#site-packs).
+
+## Which command do I want?
+
+| Goal | Command |
+|---|---|
+| Use a site someone shared with you | `dotbot site add <folder, zip, git URL or ->` |
+| Share a site, or move an inline table into a pack | `dotbot site export <name>` |
+| See every site and where it was read from | `dotbot config show` |
+
+## `add`
+
+Copies a pack into `~/.dotbot/sites/<name>/`, one of the default `site_dirs`,
+so any config on this machine can then name the site. The source can be:
+
+- a pack folder, whose name is the site's name;
+- a zip of one, as `site export` writes it, whose top folder is the site's name;
+- `-`, to read such a zip from stdin;
+- a git URL whose repository is a pack, named after the site.
+
+```bash
+dotbot site add ./lab                                     # a folder
+dotbot site add lab.zip                                   # a zip from `site export`
+curl -L https://example.org/lab.zip | dotbot site add -   # a zip on stdin
+dotbot site add https://github.com/<org>/lab.git          # a git repository
+```
+
+A zip is not downloaded from a bare `https://...zip` argument: pipe it in with
+`-` as above. `add` refuses to replace a pack of the same name unless you pass
+`-f/--force`; a replacement that fails part-way leaves the old pack as it was.
+It also refuses a site name that is not letters, digits, `-` and `_`, and a
+pack holding links.
+
+Then select the site with `site = "lab"` in your config, `--site lab` or
+`DOTBOT_SITE=lab`.
+
+## `export`
+
+Writes the site `<name>` as a pack zip, `<name>.zip` in the current directory
+by default. The site can be an inline `[sites.<name>]` table, which is written
+out as the pack's `site.toml`, or a pack already.
+
+```bash
+dotbot site export lab                                    # lab.zip
+dotbot site export lab --out ~/share/lab.zip --with-calibrations
+```
+
+| Flag | Meaning |
+|---|---|
+| `--out FILE` | The zip to write (default `<name>.zip`). |
+| `--with-calibrations` | Include the site's calibration files, from its pack's `calibrations/` and from `~/.dotbot/calibrations/<name>/`. |
+| `-f`, `--force` | Overwrite an existing zip. |
+
+A pack is plain files, so `unzip`, `git clone` or `cp` into a `site_dirs`
+folder work just as well as `site add`.
+
+## See also
+
+- [Configuration reference: sites](../reference/configuration.md#sites) - the site table, area roles, `site_dirs`.
+- [`dotbot config`](config.md) - `config show` lists every site and its source.
+- [LH2 calibration](../guides/lh2-calibration.md) - calibrating a site.
diff --git a/doc/cli/swarm.md b/doc/cli/swarm.md
@@ -123,22 +123,23 @@ For another board or an app outside this list, pass the full `.bin` path.
 
 ## 6. LH2 calibration over the air
 
-Capture and push a Lighthouse-2 calibration for one DotBot without a cable,
-driving it over the swarm. The arena geometry and `-d` sizing live in the
-[LH2 calibration guide](../guides/lh2-calibration.md).
+Capture a Lighthouse-2 calibration from one DotBot without a cable, then push
+it to the fleet. Choosing the points, the span overlay and troubleshooting live
+in the [LH2 calibration guide](../guides/lh2-calibration.md).
 
 ```bash
-dotbot swarm stop                                              # capture only runs in READY
-dotbot swarm calibrate-lh2 collect --device BC3D... -d 500     # capture from one DotBot -> solve -> save
-dotbot swarm calibrate-lh2 push ~/.dotbot/calibrations/calibration-<UTC>.toml   # apply to every ready DotBot
+dotbot swarm flash calibrate -ys          # the app that captures on a button press
+dotbot swarm calibrate-lh2 collect        # the field's four corners -> solve -> save
+dotbot swarm calibrate-lh2 push <id>      # send it to every robot
 ```
 
-`collect` walks one DotBot through the four arena corners over the air, solves the
-homography, and saves it under `~/.dotbot/calibrations/`. `push` (no `--device`) then sends
-that calibration to **every ready DotBot** - the arena shares one transform.
-(`collect --push` is a single-DotBot shortcut: it sends only to the captured DotBot.)
-`push` takes a `calibration-*.toml` or the legacy raw payload - the format is
-picked by file extension. Get the `--device` address from `dotbot swarm status`.
+`collect` asks for the four corners of the site's field in turn, and captures
+each when you press the DotBot's button; `--over <area>`, `--square <mm>` and
+`--points` choose other points. It solves every station and saves the result
+under `~/.dotbot/calibrations/<site>/`. `push` then sends it to every robot -
+the whole site shares one calibration. It takes a file path, a `--tag` or an
+id prefix, and refuses robots that report another site. (`collect --push` sends
+only to the robots whose captures built it.)
 
 ## Two web servers - don't mix them up
 

diff --git a/doc/conf.py b/doc/conf.py
@@ -67,6 +67,8 @@
     ("py:class", r"MaxLen"),
     ("py:class", r"NoneType"),
     ("py:class", r"dotbot\.models\._positions_as_waypoints"),
+    # dotbot.config has no API page; its schema is the configuration reference
+    ("py:class", r"dotbot\.config\..*"),
 ]
 
 # -- Options for HTML output -------------------------------------------------

diff --git a/doc/guides/lh2-calibration-cabled.md b/doc/guides/lh2-calibration-cabled.md
@@ -9,16 +9,15 @@ swap.
 > **Deprecated.** The cabled path is kept for bench work before a swarm
 > exists. The supported path is [over the air](lh2-calibration.md).
 
-What LH2 calibration is, and the arena geometry (the `-d` square sizing), are
-covered in the [main guide](lh2-calibration.md); this page is just the cabled
-capture path.
+The [main guide](lh2-calibration.md) explains what LH2 calibration is; this
+page is just the cabled capture path.
 
 ## Prerequisites
 
 - A DotBot v3 you can cable to your machine over USB-C (no external probe - the
   v3 flashes over its on-board programmer).
-- Two LH2 base stations facing the arena, and a square marked on the floor (see
-  [Sizing `-d`](lh2-calibration.md) in the main guide).
+- Two LH2 base stations facing the floor, and a square of known side marked on
+  it.
 - The `[calibrate]` extra:
 
 ```bash