Document buildings and levels where the old single-map model was still taught

The 0.11.0 release changed what a map position means and six documents still
described the model it replaced. Each of these could have caused a real mistake
rather than being merely out of date:

- IMPORT-API mapped legacy mapleft/maptop to mapx/mapy with no mention of the
  level, so a scripted import - including the classic-ASP one still to run
  against production - would have produced markers the map shows as "level
  unknown". It now maps levelid too and says how to resolve the default level.
- API-REFERENCE enumerates the unauthenticated surface in full, because that is
  what a deploy reviewer reads, and the three public /api/maplevels reads were
  missing from it. Also records why the write split is asymmetric: repositioning
  needs assets.edit, creating a level needs admin, since a level's dimensions are
  the coordinate space every marker on it is expressed in.
- CONFIG still presented the four map_* settings as live, telling the reader to
  re-upload a blueprint in a settings page that no longer drives the map. They
  are marked superseded and kept for downgrade.
- UPGRADE gained a 0.11.0 section: nothing moves on screen, and replacing a
  blueprint with one of different dimensions moves every marker on that level, so
  recalibrate from landmarks rather than editing width and height.
- PLUGIN-HOOKS now states that a map overlay keys on assetid and must not return
  coordinates or a level - a second copy of a position is one that can disagree.

Adds FLOOR-MAP.md, the operator's page: loading a plan, placing markers, and
what to do when the plan changes, with the reasoning left in ADR-017. START-HERE
routes to it from the new-site path, and specifically as the page to read BEFORE
a floor plan changes.

docs/UPGRADE.md

@@ -89,6 +89,36 @@ Confirm the app is healthy (login page renders, `/api/auth/login` returns a
 
 ## Version-specific notes
 
+### Upgrading to v0.11.0: the floor map became buildings and levels
+
+Nothing to do, and nothing moves on screen. Run both migration steps as always:
+
+```bash
+flask db upgrade
+flask plugin upgrade-all
+```
+
+`7d33_buildings_and_levels` creates one building ("Main") and one default level
+("Ground floor") carrying the blueprint paths and dimensions from your `map_*`
+settings, then assigns every already-placed asset and location to that level.
+Unplaced things stay unplaced. The old settings rows are deliberately left in
+place, so a downgrade still finds the blueprint.
+
+Two things to know afterwards:
+
+- **A second floor or building is a Settings task**, not a migration: add it under
+  Settings > Buildings and levels, upload its blueprint, then move the markers
+  that belong on it. `POST /api/mappositions/transform` moves a whole level's
+  markers onto a redrawn plan from landmark pairs, dry run by default.
+- **Replacing a blueprint with one of DIFFERENT dimensions moves every marker on
+  that level**, because the coordinates are pixels of the old size. Upload it, then
+  recalibrate with landmarks rather than editing the level's width and height by
+  hand. The API refuses to adopt a new size on a level that already has markers,
+  for this reason.
+
+If you wrote a plugin that stores map positions, see CONTRACT-STABILITY.md: the
+contract is 0.20.0 and a position must now carry its `levelid`.
+
 ### Upgrading to v0.5.0 or later: bundled the reference site floor plan removed
 
 Versions before 0.5 shipped the the reference site facility floor-plan PNGs as the