feat: P.0.lib.maps single-tile-grid implementation (replaces trivial-stub)

README.md

@@ -1,6 +1,20 @@
 # lib-core.maps
 
-P.0.module.skeleton trivial-stub. Will be properly implemented in P.0.lib.maps slice.
+P.0 single-tile-grid-map implementation. Loads JSON map + tilemap files,
+provides tile-fetch + walkability queries.
 
 - Lib-ID: `lib-core.maps`
 - Version: `0.1.0`
+- Spec: `meta/docs/superpowers/specs/2026-05-09-p0-lib-maps-design.md`
+
+Forward-compat stubs (DEPRECATED-MVP) for multi-map graph, lifecycle states,
+walls, sprite-fields, generators, save-integration. See
+`meta/docs/architecture/map-topology.md` for the full target spec.
+
+## API
+- `maps.load(path)` — load + register a map from JSON
+- `maps.create(table)` — programmatic creation (tests, procedural)
+- `maps.tile_at(map_id, tx, ty)` / `maps.tile_at(tx, ty)` — current-map sugar
+- `maps.is_walkable(...)`, `maps.size(...)`, `maps.tile_size(...)`
+- `maps.current()`, `maps.set_current(id)`, `maps.list()`
+- Stubs (deferred): `maps.state()`, `maps.pin()`