feat(bindings): generate Gateway bindings outside the source tree

README.md

@@ -46,6 +46,7 @@ repeat. Commands run against the selected Core checkout.
 ```text
 lyracore help [--all]
 lyracore doctor
+lyracore bindings [--check]
 lyracore preflight
 lyracore publish [DATABASE ...] [--skip-preflight]
 lyracore dev up [--single] [--lan <IP>]
@@ -250,6 +251,25 @@ processes the CLI started, `logs/` holds their output, and `config.json` holds t
 When the CLI mints a local coordinator identity, `coordinator-token` stores its credential with
 mode `0600`.
 
+## `bindings`
+
+Run `./lyracore bindings` before a Gateway Cargo build or editor check on a fresh Core checkout.
+It generates private Rust bindings from the local Module with `debug_reducers`, using the pinned
+Rust and SpacetimeDB tools. Schema generation and CLI publishing take Rust flags from the
+checkout's Cargo configuration and ignore ambient Rust-flag overrides. It does not contact a Realm. `dev up` prepares them before its Gateway
+build, and the publish upgrade check reads the prepared schema.
+
+Files live under `.lyracore/generated/gateway/`, outside the source tree. Repeated preparation
+reuses output while source and generated-file hashes match. Module and workspace sources, installed
+Package sources, the Runtime Script event catalogue, Cargo configuration and lockfile, and tool
+pins determine freshness. A failed generation leaves the previous complete output in place.
+
+`./lyracore bindings --check` checks existing output without running Cargo or SpacetimeDB and
+prints JSON with `directory` and `watches`. Core's Gateway build script uses that contract through
+the installed pinned CLI. Missing or stale bindings stop the build with preparation instructions.
+Deleting `.lyracore/generated/gateway/` clears the generated cache, including old directories kept
+for compilers that were already running.
+
 ## `preflight` — the offline deploy gate
 
 ```bash
@@ -313,8 +333,8 @@ Explicit database **NAMES** are published exactly as given:
 * `-c` / `--delete-data` — the destructive wipe — is **refused**, as is any other flag-shaped
   argument, with exit 2 and before a single `spacetime` process starts. Nothing is forwarded.
 
-`--skip-preflight` is the only recognised flag, and it says on stdout that nothing validated the
-schema. Publishing several databases in one command is what makes "every shard" checkable instead of
+`--skip-preflight` skips the preflight checks. Binding preparation and Loot Roll upgrade checks
+still run. Publishing several databases in one command is what makes "every shard" checkable instead of
 remembered: a schema change needs all of them, and the gateway reports a shard left behind only as
 "realm-core unreachable — LOGONS WILL BE REFUSED".
 

docs/commands.md

@@ -47,6 +47,7 @@ was private, which meant a fresh clone's very first command failed for anyone bu
 
 ```text
 lyracore doctor
+lyracore bindings [--check]
 lyracore preflight
 lyracore publish [DATABASE ...] [--skip-preflight]
 lyracore dev up [--lan <IP>]
@@ -850,6 +851,25 @@ directory. Neither repo carries a zip library, so a machine without the binary g
 the reason, and keeps the directory that was already built. A `<DIR>.zip` this command did not
 write is refused rather than overwritten.
 
+## `bindings`
+
+Run `./lyracore bindings` before a Gateway Cargo build or editor check on a fresh Core checkout.
+It generates private Rust bindings from the local Module with `debug_reducers`, using the pinned
+Rust and SpacetimeDB tools. Schema generation and CLI publishing take Rust flags from the
+checkout's Cargo configuration and ignore ambient Rust-flag overrides. It does not contact a Realm. `dev up` prepares them before its Gateway
+build, and the publish upgrade check reads the prepared schema.
+
+Files live under `.lyracore/generated/gateway/`, outside the source tree. Repeated preparation
+reuses output while source and generated-file hashes match. Module and workspace sources, installed
+Package sources, the Runtime Script event catalogue, Cargo configuration and lockfile, and tool
+pins determine freshness. A failed generation leaves the previous complete output in place.
+
+`./lyracore bindings --check` checks existing output without running Cargo or SpacetimeDB and
+prints JSON with `directory` and `watches`. Core's Gateway build script uses that contract through
+the installed pinned CLI. Missing or stale bindings stop the build with preparation instructions.
+Deleting `.lyracore/generated/gateway/` clears the generated cache, including old directories kept
+for compilers that were already running.
+
 ## `preflight` — the offline deploy gate
 
 ```bash
@@ -895,7 +915,7 @@ Its arguments are database **NAMES**. **Every flag-shaped argument is refused**
 any process starts — `-c`, `--delete-data`, `--clear-database` and `--clear` with a message naming
 it as the destructive wipe, anything else with the general refusal. Nothing is forwarded to
 `spacetime publish` that this CLI did not put there itself. The only recognised option is
-`--skip-preflight`, which announces on stdout that nothing validated the schema.
+`--skip-preflight`. Binding preparation and Loot Roll upgrade checks still run.
 
 This is the same contract the maintainers' internal deploy script carries — each of those cases is a
 unit test in the CLI too. [`docs/danger-zones.md`](https://github.com/LyraCoreProject/LyraCore/blob/main/docs/danger-zones.md) §1 remains authoritative.

src/bin/main.rs

@@ -49,6 +49,21 @@ fn run(args: &[String]) -> Result<i32> {
             let blocking = cmd::doctor::report(&checks);
             Ok(if blocking { EXIT_FAILURE } else { EXIT_OK })
         }
+        Command::Bindings { check } => {
+            let project = ProjectLayout::discover()?;
+            if check {
+                let prepared = cmd::bindings::check(&project)?;
+                println!(
+                    "{}",
+                    serde_json::to_string(&prepared)
+                        .map_err(|e| lyracore_cli::Error::Process(e.to_string()))?
+                );
+            } else {
+                cmd::bindings::ensure(&project, &runner)?;
+                println!("Gateway bindings are ready.");
+            }
+            Ok(EXIT_OK)
+        }
         Command::Preflight => {
             cmd::preflight::run(&ProjectLayout::discover()?, &runner).map(|_| EXIT_OK)
         }