docs: document passkey advanced configuration options

docs/kratos/passwordless/05_passkeys.mdx

@@ -111,6 +111,91 @@ Alternatively, use the Ory CLI to enable the passkey strategy:
 </Tabs>
 ```
 
+### Advanced configuration
+
+The passkey strategy exposes additional options that control the WebAuthn ceremony. All options are optional and existing passkey
+credentials keep working. One default changed — see the note on authenticator attachment below.
+
+| Option                                      | Type     | Default         | What it controls                                                                                                                                                                                                   |
+| ------------------------------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `authenticator_selection.attachment`        | string   | _unset_         | Restricts eligible authenticators by attachment modality: `"platform"` (Touch ID, Windows Hello) or `"cross-platform"` (HID tokens, YubiKeys). Omit this field to accept either type.                              |
+| `authenticator_selection.resident_key`      | string   | `"required"`    | Whether the authenticator must create a client-side discoverable credential: `"required"`, `"preferred"`, or `"discouraged"`.                                                                                      |
+| `authenticator_selection.user_verification` | string   | `"preferred"`   | Whether biometrics or a PIN are required: `"required"`, `"preferred"`, or `"discouraged"`.                                                                                                                         |
+| `attestation.preference`                    | string   | `"none"`        | Attestation conveyance preference Kratos _requests_ from the authenticator: `"none"`, `"indirect"`, `"direct"`, or `"enterprise"`. See the note below — this is a request hint only, not an enforcement control.   |
+| `timeouts.registration`                     | duration | library default | Timeout for the registration ceremony. Use Go duration format, for example `"60s"` or `"5m"`. When unset, the library default applies: 5 minutes, or 2 minutes when `user_verification` is set to `"discouraged"`. |
+| `timeouts.login`                            | duration | library default | Timeout for the login ceremony. Use Go duration format. When unset, the same default behavior as `timeouts.registration` applies.                                                                                  |
+
+:::note
+
+**Default behavior change:** Earlier versions of the passkey strategy hardcoded `attachment: platform`, so only built-in
+authenticators (Touch ID, Windows Hello) could be registered. The strategy now defaults to **no attachment preference**, which
+means users can register either platform or cross-platform (roaming) authenticators. To restore the previous behavior, set
+`authenticator_selection.attachment` to `"platform"`.
+
+:::
+
+:::note
+
+**Timeouts are enforced by the browser:** `timeouts.registration` and `timeouts.login` are communicated to the browser, which
+enforces them during the WebAuthn ceremony. Kratos does not reject late responses server-side based on these values — the login
+and registration flow lifespans (`selfservice.flows.*.lifespan`) govern how long a flow remains valid.
+
+:::
+
+:::note
+
+**`attestation.preference` is request-only:** This option controls only what Kratos requests from the authenticator. Kratos does
+not verify or enforce the returned attestation statement, so this option cannot be used to restrict registration to specific
+authenticator types or models. Most consumer passkeys (iOS, Android) support only `"none"`; requesting `"direct"` or
+`"enterprise"` may not be honored.
+
+:::
+
+The following example configures cross-platform authenticators (such as a HID token or YubiKey) with required user verification:
+
+```mdx-code-block
+<Tabs>
+  <TabItem value="cli" label="Ory CLI">
+    <CodeBlock language="shell">{`ory patch identity-config <your-project-id> \\
+  --add '/selfservice/methods/passkey/config/authenticator_selection/attachment="cross-platform"' \\
+  --add '/selfservice/methods/passkey/config/authenticator_selection/user_verification="required"'
+`}
+    </CodeBlock>
+  </TabItem>
+  <TabItem value="network" label="Ory Network" default>
+    <CodeBlock language="yaml" title="config.yml">{`selfservice:
+  methods:
+    passkey:
+      enabled: true
+      config:
+        authenticator_selection:
+          attachment: cross-platform
+          user_verification: required`}</CodeBlock>
+  </TabItem>
+  <TabItem value="self-hosted" label="Self-hosted Ory Kratos">
+    <CodeBlock language="yaml" title="config.yml">{`selfservice:
+  methods:
+    passkey:
+      enabled: true
+      config:
+        rp:
+          display_name: Your Application name
+          id: localhost
+          origins:
+            - http://localhost:4455
+        authenticator_selection:
+          attachment: cross-platform
+          resident_key: required
+          user_verification: required
+        attestation:
+          preference: none
+        timeouts:
+          registration: 5m
+          login: 5m`}</CodeBlock>
+  </TabItem>
+</Tabs>
+```
+
 ### Identity schema
 
 If you want to use a custom identity schema, you must define which field of the identity schema is the display name for the