diff --git a/content/docs/(reference)/swift-sdk.mdx b/content/docs/(reference)/swift-sdk.mdx
index afd43cba..79bae6db 100644
--- a/content/docs/(reference)/swift-sdk.mdx
+++ b/content/docs/(reference)/swift-sdk.mdx
@@ -233,7 +233,13 @@ try await copy.declareTypes([
 ])
 ```
 
-`declareTypes(_:)` replaces the app's whole set, so pass every type on each call. **Until the copy first hydrates, a queued create is checked against these declarations** and the types Marfa ships, so the app works offline from its first launch. On hydration, the copy registers each declared type the instance lacks, if the credential may register types, and the `HydrateReport` lists them in `registeredTypes` and `unregisteredTypes`. [Define a type](/guides/define-a-type) explains what a definition holds.
+`declareTypes(_:)` replaces the app's whole set, so pass every type on each call. **Until the copy first hydrates, a queued create is checked against these declarations** and the types Marfa ships, so the app works offline from its first launch. On hydration, the copy brings the instance's types up to date:
+
+- **It registers each declared type the instance lacks**, if the credential may register types. The `HydrateReport` lists them in `registeredTypes` and the ones the instance refused in `unregisteredTypes`.
+- **It replaces each declared `app.*` type the instance holds in another definition**, if the credential may change it. The server judges whether a definition differs, after normalizing both, so key order and defaults written out or left out never cause a write. The `HydrateReport` doesn't list them yet.
+- **It leaves a type the instance refuses to replace as the instance holds it.** A refusal doesn't stop the hydration, and the `HydrateReport` doesn't list it yet. A key without `schema.write` can add optional fields and change a label, but the server refuses a change that makes a field required or removes one.
+
+A type outside `app.*`, such as one under `user.*`, is registered when missing and never replaced. [Define a type](/guides/define-a-type) explains what a definition holds.
 
 ## Call the server directly