diff --git a/src/scheduler/CLAUDE.md b/src/scheduler/CLAUDE.md
index af678135..fd2a26e1 100644
--- a/src/scheduler/CLAUDE.md
+++ b/src/scheduler/CLAUDE.md
@@ -1,28 +1,31 @@
 # XCE Scheduler
 
 ## Overview
-C-based job scheduling engine with a plugin architecture. Determines job-to-node assignments based on resource requirements and scheduling policies.
+C-based job scheduling engine with a plugin architecture. Determines job-to-node assignments based on resource requirements and scheduling policies. Since `scheduler-core` (2026-08), the engine is split into a mode-agnostic **core** state machine driven by two interchangeable **drivers** — a controller-connected normal-mode driver and a standalone `.replay`-file simulation driver — so scheduling decisions can be recorded live and deterministically replayed offline for debugging/tuning.
 
 ## Build
 ```bash
-# From workspace root
-nix develop
-meson build && ninja -C build
+/xce-build scheduler    # debug + ASAN + tests; add `all` instead of `scheduler` when a downstream
+                         # task also needs xceadmin/controller binaries coexisting in the same build dir
 ```
 
 ## Architecture
-- Plugin-based: scheduling policies live under `src/plugins/`
-- Each plugin implements a standard scheduling interface
-- Core engine selects the active plugin at runtime
+- **Core** (`core.c`/`core_events.c`/`core_session.c`/`core_clock.c`) — passive, event-driven `xce_sched_core_t` state machine. Zero controller I/O (no `netio`/`xceapi`/`client`/`delay`/`idgen` — enforced by `test_core_isolation.c`); `core_clock.c` is the one sanctioned exception (`clock_gettime`, virtualized two-base+speed clock formula, `xce_core_now()`). Picker→allocator handoff is a strict `jbuf` cbuf capacity-1 rendezvous — this is the project's determinism invariant, not a tuning knob; never raise it without re-deriving Req 5 AC 7 in `.kiro/specs/scheduler-core/requirements.md`.
+- **Picker plugin interface** (`plugin.h`'s `xce_job_picker_iface_t`, `plugins/builtin_fcfs.c`) — job-selection strategies are pluggable; `scheduler.c`'s `sched_job_picker()` branches on whether a plugin still uses the legacy `job_elect_fn`-only shape (`plugins/fcfs.c`, kept as-is for a compat-wrapper exercise, not the live default) vs the native hook interface (`builtin_fcfs`, the registered default). New scheduling policies → add as a picker plugin under `src/plugins/`, do not modify the core loop.
+- **Drivers** — `driver.c` (normal mode: capnp↔core event translation, decision publishing, deferred admin-request handling) and `sim.c`/`sim_loop.c`/`sim_record.c`/`sim_verify.c` (simulation mode: `.replay` file loading, discrete virtual clock, `--sim-verify`/`--sim-alt-events`/`--sim-output`). Both drive the identical core session/decision-callback protocol — one core, two consumers.
+- **Replay/recording** — `recording.c`/`recording_events.c`/`recording_session.c` (live capture) and `snapshot.c`/`snapshot_wire.c`/`snapshot_load.c` (state save/restore) read/write the `.replay` capnp binary stream (`src/schema/controller.capnp`); controlled via `OPCode_schedAdmin` (`src/controller/cluster.c`) and `xceadmin scheduler record start|stop|status` / `scheduler dump <FILE>`.
+- **Interactive REPL** (`repl.c`/`repl_break.c`/`repl_info.c`/`repl_params.c`, `--interactive`) — single-step/breakpoint/state-inspection/snapshot-capture control over the simulation driver; drives the exact same `sched_sim_driver_run()` as batch `--sim`, gated only by `sim->interactive`, so REPL and batch runs are decision-equivalent by construction (`test_repl_equivalence.c`).
 
-Links against `libxce` from `src/lib/`.
+Links against `libxce` from `src/lib/`. Full design/requirements: `.kiro/specs/scheduler-core/`.
 
 ## Conventions
 - C standard: gnu17
 - Format with `clang-format`
 - New scheduling policies → add as a plugin under `src/plugins/`, do not modify the core engine
 - Shared types defined in `src/include/xce/` (libxce)
+- Files stay under the repo's 800-line cap — several core/sim/repl/snapshot/recording modules are deliberately split across multiple `*_events.c`/`*_session.c`/`*_wire.c`-style files for this reason; keep new logic in the file matching its concern rather than growing one file past the cap.
 
 ## See Also
 - Shared library: `src/lib/CLAUDE.md`
 - Root guidelines: `CLAUDE.md` (repo root)
+- Architecture/requirements: `.kiro/specs/scheduler-core/design.md`, `.kiro/specs/scheduler-core/requirements.md`