diff --git a/crates/wavekat-flow/README.md b/crates/wavekat-flow/README.md
index ce5c50d..a4549b2 100644
--- a/crates/wavekat-flow/README.md
+++ b/crates/wavekat-flow/README.md
@@ -67,6 +67,23 @@ if let Err(errors) = validate::validate(&flow) {
 }
 ```
 
+## Upgrading when the booking grid moves
+
+`BOOK_GRANULARITY_MINS` decides which times a `book` node can ever say, so
+changing it changes what `vocabulary_refs` — and therefore
+`required_assets` — returns for a node nobody edited.
+
+This crate is where a device answers that question, from the constant
+compiled into it rather than from anything the flow document carries, and a
+device refuses to arm a flow whose required assets aren't all on disk. So a
+device left on an older grid, handed a version published by an authoring
+side that already narrowed, asks for a clip that was never rendered and
+stops running the whole flow — not just its booking step.
+
+Take this crate's upgrade **before** the authoring side takes the matching
+`@wavekat/flow-schema`. Narrowing leaves the published set a superset in the
+meantime, which is the safe direction.
+
 ## One format, two languages
 
 This crate is the Rust half of the format. Authoring, comment-preserving
diff --git a/packages/flow-schema/README.md b/packages/flow-schema/README.md
index 9d82464..0c8b8ba 100644
--- a/packages/flow-schema/README.md
+++ b/packages/flow-schema/README.md
@@ -68,6 +68,23 @@ keys, implicit typing) and reports node-level source ranges for editor
 diagnostics. Validation covers what a schema can't: reachability, caller
 traps, exit-set exactness, hours math, DTMF and prompt rules.
 
+## Upgrading when the booking grid moves
+
+`BOOK_GRANULARITY_MINS` decides which times a `book` node can ever say, so
+changing it changes what `bookVocabularyRefs` — and therefore
+`requiredAssets` — returns for a node nobody edited.
+
+A device computes that set from the version of the Rust crate **compiled
+into it**, not from anything the flow document carries, and refuses to arm a
+flow whose required assets aren't all on disk. So an authoring side that
+adopts a narrower grid first publishes versions that older devices consider
+incomplete, and they stop running the whole flow — not just its booking
+step.
+
+Adopt in this order: release, then every device in the field, then the
+authoring side. Narrowing leaves the published set a superset in the
+meantime, which is the safe direction.
+
 ## One format, two languages
 
 This package is the TypeScript (authoring) half of the format. Parsing,