diff --git a/README.md b/README.md
index 33b6715..526a982 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,15 @@
-# Logos Blockchain Indexer Module
+# Logos Execution Zone Indexer Module
+
+A Logos Core **service module** (`type: core`) that runs the Logos Execution Zone
+(L2) indexer and exposes it to the Logos ecosystem. It is a thin Qt plugin around
+the `indexer_ffi` library from
+[`logos-execution-zone`](https://github.com/logos-blockchain/logos-execution-zone):
+it starts the indexer, which connects to an L1/bedrock node, indexes the zone's
+channel, and serves queries over an RPC (WebSocket) server.
+
+Registered module name: **`lez_indexer_module`**. It pairs with the
+[`lez-explorer-ui`](https://github.com/logos-co/lez-explorer-ui) block explorer,
+which connects to the indexer's RPC endpoint.
 
 ### Setup
 
@@ -11,6 +22,54 @@ This will reduce friction when working on the project.
 #### Nix
 
 * Use `nix flake update` to bring all nix context and packages
-* Use `nix build` to build the package
+* Use `nix build` to build the package (produces `lez_indexer_module.<dylib|so|dll>`)
 * Use `nix run` to launch the module-viewer and check your module loads properly
 * Use `nix develop` to setup your IDE
+
+### Running the indexer
+
+The module does **not** start the indexer on load — something must invoke its
+`start_indexer` method (via the module-viewer's invoke panel, or another module /
+basecamp over the Logos API):
+
+```
+start_indexer(config_path, port)
+```
+
+* `config_path` — **absolute** path to a JSON config (see
+  [`config/indexer_config.json`](config/indexer_config.json)). It must be absolute:
+  the module runs inside the `logos_host` subprocess, whose working directory is not
+  your shell's.
+* `port` — TCP port for the RPC server, e.g. `8779`. Passed as a **string** (see the
+  macOS / Qt notes below).
+
+On success it returns `0` and the RPC server listens on `ws://localhost:<port>`;
+point the explorer (or any client) there. A non-zero return is the FFI
+`OperationStatus` (e.g. `2 = InitializationError`) — note the FFI does not log, so
+the numeric code is all you get.
+
+### Configuration
+
+`config/indexer_config.json` is deserialized into the indexer's `IndexerConfig`.
+Key fields:
+
+| Field | Meaning |
+|---|---|
+| `bedrock_config.addr` | L1/bedrock node URL the indexer reads from (default `http://localhost:8080` — it must be reachable). |
+| `home` | Directory for the indexer's RocksDB state, **relative to the host's working directory** (`"."` by default). Use an absolute path for a predictable location. |
+| `channel_id` | The zone channel the indexer consumes; must match what the sequencer inscribes. |
+
+The config keys must match the `IndexerConfig` schema of the `logos-execution-zone`
+rev pinned in `flake.nix`/`flake.lock`; bumping that rev may require re-syncing this
+file. Unknown keys are ignored.
+
+### macOS / Qt notes
+
+* **Keep the module name short.** `logos_host` derives a Qt Remote Objects `local:`
+  socket from it (`local:logos_<name>_<id>`), and macOS caps Unix socket paths at
+  104 bytes. The build emits the library with no `lib` prefix so its filename equals
+  the registered name (`lez_indexer_module`) — consumers derive the QtRO invoke
+  target from the filename, so the two must stay identical.
+* **`Q_INVOKABLE` parameters are `QString`.** The QtRO `ModuleProxy` invokes via
+  `QMetaObject::invokeMethod` with exact type matching and delivers arguments as
+  `QString`, so `start_indexer` takes the port as a string and parses it internally.