Buildings and levels for the floor map, and make every identifier searchable

The map was one picture of one floor. A second floor was added, the blueprint
changed size, and machines moved, so a position now records WHICH DRAWING its
coordinates belong to.

Buildings and levels (ADR-017). Each level owns its blueprint per theme and its
own native pixel size; assets.mapx/mapy are pixels of assets.levelid, not of the
site. A position whose level is unknown renders "level unknown" and is never
drawn on the default level, because a marker on the wrong floor plan looks
entirely correct while pointing at the wrong place.

Repositioning in bulk: filter by unplaced, needs-review or level, search, place,
confirm. Landmark recalibration solves the transform PER AXIS from landmark
pairs and never from image dimensions - the canvas grew taller without
rescaling, so a dimension-derived scale would stretch Y by 1.57 and be wrong
everywhere. It defaults to a dry run, reports what would land off the drawing,
snapshots before applying, and clears mapverifiedat because a transform is a
guess awaiting review. Snapshots restore, including the level and the review
state, and a restore snapshots first so an undo is undoable.

Search: gaugelabreference was matched only for measuring tools and
maintenancereference was matched nowhere at all, for any asset type, while
Settings happily offers both identifiers on machines and PCs. A tag an operator
is told to record has to be findable or it is a write-only field. USB devices
and printed items were unreachable from search entirely - neither is an asset,
so the generic asset search could not see them and no searcher existed; they
now match on serial, asset tag, label, bin code and gage-lab tag, honouring
isactive, with Settings toggles and result labels to match.

The retired-application rule was half a rule: GET /api/knowledgebase hid
articles whose topic application is retired while global search still returned
them and printed the retired application as the subject. A filter is only real
if every path that reaches the row applies it.

Contract to 0.20.0 (additive): Asset gained levelid and mapverifiedat, Location
gained levelid, and resolve_asset_position returns the levelid belonging to
whichever source supplied the coordinates. The five plugins that write a map
position are re-pinned. The install-list text format gained levelid as a NINTH
field, appended, because the shipped Pascal installer reads fields 0-7 by index.

That installer still compiles in one drawing's dimensions and bundles one
blueprint, so its map is accurate for the default level only; /api/maplevels is
deliberately unauthenticated so it can read both at runtime once rebuilt.
Recorded in PRINTER-INSTALLER.md section 6 along with the other known gaps.

Migration 7d33 converts an existing single-map site into one building and one
default level carrying the old map_* settings, then assigns every placed asset
and location to it. Nothing moves on screen. Old settings rows are kept so a
rollback still finds them. Verified end to end on MySQL 5.6 from a
production-shaped database.

docs/api-inventory.json

@@ -346,7 +346,7 @@
       {
         "method": "GET",
         "path": "/api/search",
-        "purpose": "Global search across assets, applications, KB, employees, notifications, custom fields, hostnames, IPs/subnets, vendor/model/type; ServiceNOW ticket prefixes and smart redirects; results capped at 50, types filterable via search_<type>_enabled settings",
+        "purpose": "Global search across assets (including the gaugelabreference and maintenancereference identifiers), applications, KB, employees, USB devices, printed items, notifications, custom fields, hostnames, IPs/subnets, vendor/model/type; ServiceNOW ticket prefixes and smart redirects; results capped at 50, types filterable via search_<type>_enabled settings. Retired (isactive=0) rows are excluded everywhere, including KB articles whose topic application is retired",
         "auth": "jwt-optional",
         "params": "q (required, 2-200 chars)",
         "example": "curl 'http://localhost:5001/api/search?q=WKSTN0042'"
@@ -3232,5 +3232,122 @@
         "example": "curl -I http://localhost:5001/api/docs/redoc.standalone.js"
       }
     ]
+  },
+  {
+    "surface": "core-map",
+    "endpoints": [
+      {
+        "method": "GET",
+        "path": "/api/maplevels",
+        "auth": "none",
+        "params": "none",
+        "purpose": "Every building with its levels in display order, each carrying blueprint paths, native pixel size and marker count, plus defaultlevelid. PUBLIC: the printer installer map draws a blueprint before anyone logs in",
+        "example": "curl http://localhost:5001/api/maplevels"
+      },
+      {
+        "method": "GET",
+        "path": "/api/maplevels/<levelid>",
+        "auth": "none",
+        "params": "levelid in path",
+        "purpose": "One level: name, building, blueprints and native size. That size is what mapx/mapy on this level are pixels of (ADR-017)",
+        "example": "curl http://localhost:5001/api/maplevels/2"
+      },
+      {
+        "method": "GET",
+        "path": "/api/maplevels/<levelid>/blueprint/<filename>",
+        "auth": "none",
+        "params": "levelid and filename in path",
+        "purpose": "Serve a level's blueprint image, with sandbox headers so an SVG floor plan cannot execute as script",
+        "example": "curl -I http://localhost:5001/api/maplevels/2/blueprint/level-2-light.png"
+      },
+      {
+        "method": "POST",
+        "path": "/api/maplevels/buildings",
+        "auth": "jwt + role:admin",
+        "params": "body: buildingname (required), sortorder",
+        "purpose": "Create a building. An asset references the level, never the building, so the two cannot disagree",
+        "example": "curl -H \"Authorization: Bearer $TOKEN\" -H 'Content-Type: application/json' -d '{\"buildingname\":\"Annex\"}' -X POST http://localhost:5001/api/maplevels/buildings"
+      },
+      {
+        "method": "PUT|PATCH",
+        "path": "/api/maplevels/buildings/<buildingid>",
+        "auth": "jwt + role:admin",
+        "params": "buildingid in path; body: buildingname, sortorder, isactive",
+        "purpose": "Rename or reorder a building. Levels move with it and nothing repositions",
+        "example": "curl -H \"Authorization: Bearer $TOKEN\" -X PATCH http://localhost:5001/api/maplevels/buildings/1"
+      },
+      {
+        "method": "POST",
+        "path": "/api/maplevels",
+        "auth": "jwt + role:admin",
+        "params": "body: buildingid and levelname (required), sortorder, blueprintlight, blueprintdark, mapwidth, mapheight, isdefault",
+        "purpose": "Create a level. Name and sort order are separate because levels are not reliably numbered (basement, mezzanine, roof), and gaps let one be inserted later without renumbering",
+        "example": "curl -H \"Authorization: Bearer $TOKEN\" -X POST http://localhost:5001/api/maplevels"
+      },
+      {
+        "method": "PUT|PATCH",
+        "path": "/api/maplevels/<levelid>",
+        "auth": "jwt + role:admin",
+        "params": "levelid in path; body: levelname, sortorder, blueprintlight, blueprintdark, mapwidth, mapheight, isdefault, isactive",
+        "purpose": "Update a level. Changing mapwidth/mapheight returns a warning naming what it affects: the dimensions are the coordinate space every marker is expressed in, so a resize moves them all relative to the drawing - use a landmark transform instead",
+        "example": "curl -H \"Authorization: Bearer $TOKEN\" -X PATCH http://localhost:5001/api/maplevels/1"
+      },
+      {
+        "method": "DELETE",
+        "path": "/api/maplevels/<levelid>",
+        "auth": "jwt + role:admin",
+        "params": "levelid in path",
+        "purpose": "Deactivate a level. Refused with 409 while assets are placed on it, and refused for the default level: deleting a drawing out from under a marker leaves a position in a coordinate space that no longer exists",
+        "example": "curl -H \"Authorization: Bearer $TOKEN\" -X DELETE http://localhost:5001/api/maplevels/3"
+      },
+      {
+        "method": "POST",
+        "path": "/api/maplevels/<levelid>/blueprint",
+        "auth": "jwt + role:admin",
+        "params": "levelid in path; multipart/form-data: file=<image>, theme=light|dark",
+        "purpose": "Upload a level's blueprint. Reads the image's real pixel size from its header and adopts it when the level is EMPTY; with markers already placed it reports the mismatch and changes nothing, because adopting a new coordinate space silently moves every marker while looking like a successful upload",
+        "example": "curl -H \"Authorization: Bearer $TOKEN\" -F file=@second-floor.png -F theme=light -X POST http://localhost:5001/api/maplevels/2/blueprint"
+      },
+      {
+        "method": "POST",
+        "path": "/api/mappositions/transform",
+        "auth": "permission:assets.edit",
+        "params": "body: levelid (required), landmarks [{fromx,fromy,tox,toy}] (two or more), tolevelid, assetids, dryrun (defaults TRUE)",
+        "purpose": "Move every placed marker on a level by a transform derived per axis from landmark pairs. NEVER from image dimensions: a level added below another changes canvas height without rescaling anything, and a dimension-derived scale would stretch Y and be wrong everywhere. Dry run returns every old and new position plus which land outside the target. Applying snapshots first and clears mapverifiedat, because a transformed position is a guess awaiting review",
+        "example": "curl -H \"Authorization: Bearer $TOKEN\" -H 'Content-Type: application/json' -d '{\"levelid\":1,\"landmarks\":[{\"fromx\":0,\"fromy\":0,\"tox\":0,\"toy\":1450},{\"fromx\":1000,\"fromy\":1000,\"tox\":1000,\"toy\":2450}]}' -X POST http://localhost:5001/api/mappositions/transform"
+      },
+      {
+        "method": "POST",
+        "path": "/api/mappositions/positions",
+        "auth": "permission:assets.edit",
+        "params": "body: positions [{assetid, mapx, mapy, levelid}] - levelid required per row - and verified",
+        "purpose": "Set many positions at once, snapshotting first. levelid is per position rather than per request because a bulk save can span levels and inferring it is the guess this model exists to remove. Placing by hand counts as review, so mapverifiedat is stamped",
+        "example": "curl -H \"Authorization: Bearer $TOKEN\" -H 'Content-Type: application/json' -d '{\"positions\":[{\"assetid\":42,\"mapx\":1200,\"mapy\":900,\"levelid\":2}]}' -X POST http://localhost:5001/api/mappositions/positions"
+      },
+      {
+        "method": "POST",
+        "path": "/api/mappositions/verify",
+        "auth": "permission:assets.edit",
+        "params": "body: assetids (required), unverify",
+        "purpose": "Mark markers reviewed against the current drawing without moving them - the common case in a review pass. No snapshot, because no position changes",
+        "example": "curl -H \"Authorization: Bearer $TOKEN\" -H 'Content-Type: application/json' -d '{\"assetids\":[42,43]}' -X POST http://localhost:5001/api/mappositions/verify"
+      },
+      {
+        "method": "GET",
+        "path": "/api/mappositions/snapshots",
+        "auth": "permission:assets.view",
+        "params": "none; newest 50",
+        "purpose": "Position snapshots, newest first, with what caused each and whether it has been restored. Metadata only - the positions are large",
+        "example": "curl -H \"Authorization: Bearer $TOKEN\" http://localhost:5001/api/mappositions/snapshots"
+      },
+      {
+        "method": "POST",
+        "path": "/api/mappositions/snapshots/<snapshotid>/restore",
+        "auth": "permission:assets.edit",
+        "params": "snapshotid in path",
+        "purpose": "Put a snapshot back, snapshotting first so an undo is itself undoable. Restores level and review state, not just coordinates, and reports assets that no longer exist rather than failing the whole restore",
+        "example": "curl -H \"Authorization: Bearer $TOKEN\" -X POST http://localhost:5001/api/mappositions/snapshots/7/restore"
+      }
+    ]
   }
 ]