feat: add experimental selected-map event catalog

README.md

@@ -18,9 +18,11 @@ not a current support claim.
 > into bounded, read-only raw snapshots, then project map IDs, names, display
 > order, and parent relationships into a typed catalog. It can also summarize
 > one catalog-selected map's basic metadata and opaque event count, and selected
-> project-level system settings. Its first contextual validator checks only the
-> stored player start. It does not yet provide broader semantic understanding,
-> project validity, or modification. Do not rely on it for valuable workflows.
+> project-level system settings. A further bounded projection lists map-scoped
+> event IDs, names, coordinates, and opaque page counts. Its first contextual
+> validator checks only the stored player start. It does not yet provide broader
+> semantic understanding, project validity, or modification. Do not rely on it
+> for valuable workflows.
 
 ## What Tilewright aims to provide
 
@@ -56,8 +58,8 @@ for the distinction between planned and supported behavior.
 
 | Package | Role | Current state |
 | --- | --- | --- |
-| [`tilewright`](crates/tilewright/README.md) | Format-aware domain library and primary public API | Experimental discovery, inventory, strict lossless JSON syntax, raw snapshot loading, typed map catalog, selected-map and system summaries, and player-start validation |
-| [`tilewright-cli`](crates/tilewright-cli/README.md) | Human- and script-facing adapter; installs the `tilewright` executable | Experimental discovery, inventory, raw snapshot, typed projections, player-start validation, and JSON inspection adapter |
+| [`tilewright`](crates/tilewright/README.md) | Format-aware domain library and primary public API | Experimental discovery, inventory, strict lossless JSON syntax, raw snapshot loading, typed map and event catalogs, selected-map and system summaries, and player-start validation |
+| [`tilewright-cli`](crates/tilewright-cli/README.md) | Human- and script-facing adapter; installs the `tilewright` executable | Experimental discovery, inventory, raw snapshot, typed map/event projections, player-start validation, and JSON inspection adapter |
 | [`tilewright-mcp`](crates/tilewright-mcp/README.md) | Thin MCP adapter over the library | Scaffold |
 
 The dependency direction is inward:
@@ -114,6 +116,7 @@ cargo run -p tilewright-cli -- inventory path/to/project
 cargo run -p tilewright-cli -- snapshot path/to/project
 cargo run -p tilewright-cli -- maps path/to/project
 cargo run -p tilewright-cli -- map path/to/project 1
+cargo run -p tilewright-cli -- events path/to/project 1
 cargo run -p tilewright-cli -- system path/to/project
 cargo run -p tilewright-cli -- validate path/to/project
 cargo run -p tilewright-cli -- inspect-json path/to/file.json
@@ -131,6 +134,7 @@ tilewright inventory path/to/project
 tilewright snapshot path/to/project
 tilewright maps path/to/project
 tilewright map path/to/project 1
+tilewright events path/to/project 1
 tilewright system path/to/project
 tilewright validate path/to/project
 tilewright inspect-json path/to/file.json
@@ -142,12 +146,13 @@ for update and uninstall details.
 
 The CLI currently exposes experimental candidate discovery, project inventory,
 bounded raw snapshot loading, typed map-catalog inspection, selected-map
-summaries, selected system-setting summaries, bounded player-start validation,
-and strict lossless JSON syntax inspection. The validation command covers only
-the stored player start; it does not establish general project validity or
-editor compatibility. No command establishes MZ-version compatibility,
-round-trip behavior, or write support. Contributors should use the full
-verification process described in
+summaries, selected-map event catalogs, selected system-setting summaries,
+bounded player-start validation, and strict lossless JSON syntax inspection.
+The event command leaves page bodies and commands opaque. The validation
+command covers only the stored player start; it does not establish general
+project validity or editor compatibility. No command establishes MZ-version
+compatibility, round-trip behavior, or write support. Contributors should use
+the full verification process described in
 [CONTRIBUTING.md](CONTRIBUTING.md#verification).
 
 ## License

crates/tilewright-cli/README.md

@@ -7,13 +7,14 @@
 ## Status
 
 This crate is experimental. It provides help and version output plus read-only
-`discover`, `inventory`, `snapshot`, `maps`, `map`, `system`, `validate`, and
-`inspect-json`
+`discover`, `inventory`, `snapshot`, `maps`, `map`, `events`, `system`,
+`validate`, and `inspect-json`
 commands over the core library's experimental RPG Maker MZ
 candidate-discovery, capability-relative project inventory, raw snapshot
-loader, typed map catalog, selected-map summary, system summary, player-start
-validation, and strict lossless JSON syntax APIs. It does not provide general
-project understanding, project validity, editor compatibility, or modification.
+loader, typed map catalog, selected-map summary and event catalog, system
+summary, player-start validation, and strict lossless JSON syntax APIs. It does
+not provide general project understanding, project validity, editor
+compatibility, or modification.
 
 ## Install from a checkout
 
@@ -69,6 +70,10 @@ cargo run -p tilewright-cli -- maps path/to/project --format json
 cargo run -p tilewright-cli -- map path/to/project 1
 cargo run -p tilewright-cli -- map path/to/project 1 --format json
 
+# List bounded events on one catalog-selected map.
+cargo run -p tilewright-cli -- events path/to/project 1
+cargo run -p tilewright-cli -- events path/to/project 1 --format json
+
 # Summarize selected project-level system settings.
 cargo run -p tilewright-cli -- system path/to/project
 cargo run -p tilewright-cli -- system path/to/project --format json
@@ -138,6 +143,18 @@ options shown above are available on both `maps` and `map`. Neither command
 validates editor compatibility, provides stable project-wide resource identity,
 or establishes mutation, round-trip, or write support.
 
+The `events` command requires the same coherent map catalog and evidenced map
+document, then reports map-scoped event IDs, decoded names, nonnegative
+coordinates, and opaque page counts in ID order. Coordinates outside the map's
+dimensions are successful contextual findings, not claims that MZ rejects the
+state. Structural event errors exit with code 1.
+
+The command does not emit notes, raw page bodies, commands, or unprojected
+fields. Event IDs are scoped to the selected map, and page counts do not imply
+page or command understanding. The snapshot resource-limit options are
+available on `events`. The command does not establish editor compatibility,
+runtime behavior, mutation, round-trip, or write support.
+
 The `system` command loads the same bounded snapshot and delegates projection
 to the core library. It reports the decoded game title, currency unit, locale,
 stored editor-map scalar, and player-start map/X/Y scalars from exact
@@ -171,9 +188,9 @@ a non-UTF-8 path.
 
 Note: While descendant symlink entries are reported without traversal, the
 initial `open_ambient_dir` acquisition used by `inventory`, `snapshot`, `maps`,
-`map`, `system`, and `validate` may resolve root or ancestor symlinks and does
-not prove root identity. The `inspect-json` command explicitly opens the
-provided path and makes no project-containment claim.
+`map`, `events`, `system`, and `validate` may resolve root or ancestor symlinks
+and does not prove root identity. The `inspect-json` command explicitly opens
+the provided path and makes no project-containment claim.
 
 ## Responsibilities