diff --git a/README.md b/README.md
index 734a39d..74877c6 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,86 @@
 # sporel-tool-mapper
 
-Standalone CLI for v2 Sporel map files.
+Standalone CLI for v2 Sporel map files: encode/decode packed-u32 GIDs, build maps from a text DSL, and inspect stats.
 
-## Status
+## Install
 
-`v0.1.0` — initial scaffold. See `docs/superpowers/specs/2026-05-23-sporel-tool-mapper-design.md` in `sporel-meta` for the full spec.
+This is part of the Sporel monorepo workspace. No npm publish — clone the repo and run via `node bin/mapper.js` or symlink the bin entry into `$PATH`.
+
+```bash
+node bin/mapper.js <subcommand> [args...]
+```
+
+Requires Node ≥18. Zero runtime dependencies.
 
 ## Subcommands
 
-- `encode <atlas_idx> <tile_id> [rotation]`
-- `decode <gid>`
-- `build <spec.txt> <out.json> [--atlas-dir <path> ...]`
-- `inspect <map.json> [--atlas-dir <path> ...]`
+### `encode <atlas_idx> <tile_id> [rotation]`
 
-(Detailed usage and examples are added in Task 12.)
+Print the packed-u32 GID for the given components.
+
+```bash
+$ node bin/mapper.js encode 0 12 1
+196
+```
+
+### `decode <gid>`
+
+Print the components of a GID. Accepts decimal or `0x...` hex. `gid=0` prints `empty`.
+
+```bash
+$ node bin/mapper.js decode 196
+atlas=0 tile=12 rotation=1
+
+$ node bin/mapper.js decode 0
+empty
+```
+
+### `build <spec.txt> <out.json> [--atlas-dir <path> ...]`
+
+Compile a text-DSL map spec into a v2 map JSON file. See `docs/dsl.md` for full syntax (in `sporel-meta`, design spec §4). Minimal example:
+
+```
+id border_demo
+size 8 8
+atlas fa_terrain_v1
+layer surface
+  fill 0 0 7 7 fa_terrain_v1:grass_field
+  set 3 3 fa_terrain_v1:stone_wall_brick rot 1
+```
+
+```bash
+$ node bin/mapper.js build map.txt out.json --atlas-dir ../sporel-libs/lib-asset/prototype-fa-starter/assets/atlases
+```
+
+If the DSL has no `id` directive the output filename basename is used.
+
+### `inspect <map.json> [--atlas-dir <path> ...]`
+
+Read-only stats report. Without `--atlas-dir`, atlas references show as indices only; with it, atlas-id and tile names are resolved.
+
+```bash
+$ node bin/mapper.js inspect demo.map.json --atlas-dir ../sporel-libs/lib-asset/prototype-fa-starter/assets/atlases
+```
+
+## Encoding
+
+GIDs use the same packed-u32 layout as `lib-core.maps` (see `sporel-libs/lib-core/maps/init.lua`):
+
+```
+bit  31 ...... 24 | 23 ............ 4 | 3 .. 2 | 1 .. 0
+     [ atlas:8  ] [   tile_id:20    ] [ rot:2 ] [res:2]
+```
+
+`gid=0` is the canonical empty cell.
+
+## Tests
+
+```bash
+npm test
+```
+
+Uses Node's built-in `node --test` runner. No mocking framework.
+
+## Spec
+
+`docs/superpowers/specs/2026-05-23-sporel-tool-mapper-design.md` in the `sporel-meta` repo.