diff --git a/crates/didbot-policy-records/src/record.rs b/crates/didbot-policy-records/src/record.rs
index 802aa451..61b6b5c9 100644
--- a/crates/didbot-policy-records/src/record.rs
+++ b/crates/didbot-policy-records/src/record.rs
@@ -1,11 +1,10 @@
 //! The declaration one policy statement becomes between the operator's
 //! record and [`didbot_policy::PolicyDeclaration`].
 //!
-//! `didbot-policy-records`' `set::declarations` reads a `bot.did.policy`
-//! record and produces one [`ParsedPolicy`] per statement per action the
-//! statement can decide. [`crate::compile`] takes it from there, resolving
-//! `language` against the evaluators this build carries and registering the
-//! result on a tree.
+//! [`crate::set::declarations`] reads a `bot.did.policy` record and produces
+//! one [`ParsedPolicy`] per statement per action the statement can decide.
+//! [`crate::compile`] takes it from there, resolving `language` against the
+//! evaluators this build carries and registering the result on a tree.
 //!
 //! # Applicability is declarative data, outside the predicate
 //!
@@ -34,11 +33,12 @@ pub struct ParsedPolicy {
     pub language: String,
     /// The predicate document, typed by `language` and opaque here.
     pub predicate: serde_json::Value,
-    /// Which revision of this declaration this is. A label the caller
-    /// chooses: `didbot-policy-records` numbers every declaration it makes
-    /// [`Revision`]`(0)`, and nothing in the compile step orders by it. It
-    /// reaches an operator through
-    /// [`crate::merge::LastGoodFallback`].
+    /// Which revision of this declaration this is -- a label whoever
+    /// declares it chooses. [`crate::set::declarations`] stamps every
+    /// declaration [`Revision`]`(0)`, so an operator's records all carry the
+    /// same one; nothing here orders by it, and
+    /// [`crate::last_good::LastGoodPolicies`] keys on the declaration's id.
+    /// It reaches an operator through [`crate::merge::LastGoodFallback`].
     /// See [`didbot_policy::Revision`]'s own doc comment for why a revision
     /// carries no timestamp.
     pub revision: Revision,
diff --git a/crates/didbot-schema/src/lib.rs b/crates/didbot-schema/src/lib.rs
index 223c17e9..4a301aad 100644
--- a/crates/didbot-schema/src/lib.rs
+++ b/crates/didbot-schema/src/lib.rs
@@ -8,13 +8,14 @@
 //! record with the same code the store runs; [`validate_with`] is the whole
 //! of what a write's shape must satisfy.
 //!
-//! # What this covers, and what it does not
+//! # What this covers
 //!
-//! The *record* subset of the Lexicon specification: object, array, string,
-//! integer, boolean, bytes, cid-link, blob, unknown, ref, union, and every
-//! constraint those carry. It does not cover queries, procedures,
-//! subscriptions, parameters or permission sets, because nothing in this
-//! server accepts a record shaped by one.
+//! The Lexicon specification's type system: object, array, string, integer,
+//! boolean, bytes, cid-link, blob, unknown, ref, union, and every constraint
+//! those carry. [`Method`] and [`MethodOutput`] carry a query's or
+//! procedure's own parameters, input and output on top of that, so
+//! [`Catalog::validate_input`] and [`Catalog::validate_output`] check an
+//! XRPC body the same way [`validate_with`] checks a record.
 //!
 //! # Unrecognised things are carried, not refused
 //!