@@ -167,7 +167,7 @@ _ = login
 
 ### 2FA with TOTP
 
-For sites with authenticator app 2FA, include `totp_secret` so Kernel can generate a fresh code during automatic login and reauthentication:
+For sites with authenticator app 2FA, include `totp_secret` so KERNEL can generate a fresh code during automatic login and reauthentication. Supply a base32 secret of 16–128 characters or an `otpauth://totp/` provisioning URI. The default is SHA1, 6 digits, and a 30-second period. If the authenticator uses different settings, provide `totp_algorithm` (`SHA1`, `SHA256`, or `SHA512`), `totp_digits` (6–9), and `totp_period` (15–300 seconds):
 
 <CodeGroup>
 ```typescript TypeScript
@@ -178,7 +178,10 @@ const credential = await kernel.credentials.create({
     username: 'my-username',
     password: 'my-password',
   },
-  totp_secret: 'JBSWY3DPEHPK3PXP',  // From authenticator app setup
+  totp_secret: 'JBSWY3DPEHPK3PXP',
+  totp_algorithm: 'SHA512',
+  totp_digits: 8,
+  totp_period: 60,
 });
 ```
 
@@ -190,7 +193,10 @@ credential = await kernel.credentials.create(
         "username": "my-username",
         "password": "my-password",
     },
-    totp_secret="JBSWY3DPEHPK3PXP",  # From authenticator app setup
+    totp_secret="JBSWY3DPEHPK3PXP",
+    totp_algorithm="SHA512",
+    totp_digits=8,
+    totp_period=60,
 )
 ```
 
@@ -203,7 +209,10 @@ credential, err := client.Credentials.New(ctx, kernel.CredentialNewParams{
 			"username": "my-username",
 			"password": "my-password",
 		},
-		TotpSecret: kernel.String("JBSWY3DPEHPK3PXP"), // From authenticator app setup
+		TotpSecret: kernel.String("JBSWY3DPEHPK3PXP"),
+		TotpAlgorithm: kernel.CreateCredentialRequestTotpAlgorithmSha512,
+		TotpDigits: kernel.Int(8),
+		TotpPeriod: kernel.Int(60),
 	},
 })
 if err != nil {
@@ -213,6 +222,13 @@ _ = credential
 ```
 </CodeGroup>
 
+The examples use typed fields available in TypeScript, Python, and Go SDK v0.116.0 or later. You can also pass an `otpauth://totp/` provisioning URI as `totp_secret`.
+
+- URI parameters override explicit settings. If a parameter is missing, the API uses its explicit field, then the default.
+- Replacing a URI resets omitted settings to defaults. Rotating a raw secret preserves stored settings unless you send new values.
+- The API stores only the normalized seed, never the URI label or issuer.
+- A code's length follows `totp_digits`; don't assume six digits when reading `totp_code` or calling `totpCode()`.
+
 ### SSO / OAuth
 
 For sites with "Sign in with Google/GitHub/Microsoft", set `sso_provider` so Kernel can select the matching SSO route. Automatic completion depends on the provider's login requirements.
 
@@ -142,7 +142,7 @@ If multiple items match a domain, the first match is used. Organize your vaults
 
 ## TOTP Support
 
-If your 1Password item has a one-time password (TOTP) field configured, Kernel can generate fresh codes for automatic login and reauthentication. No additional setup is needed.
+If your 1Password item has a one-time password (TOTP) field configured, KERNEL uses its `otpauth://` secret, algorithm (SHA1, SHA256, or SHA512), digit count (6–9), and period (15–300 seconds) to generate fresh codes for automatic login and reauthentication. Missing settings default to SHA1, 6 digits, and 30 seconds. An unsupported setting makes the field unavailable instead of generating an incorrect fallback code.
 
 ## Supported Login Types
 
 
@@ -142,7 +142,10 @@ Create a new credential.
 | `--name <name>` | Unique name for the credential (required). |
 | `--domain <domain>` | Target domain this credential is for (required). |
 | `--value <name=value>` | Field name/value pair (repeatable, e.g. `--value username=myuser --value password=mypass`). |
-| `--totp-secret <secret>` | Base32-encoded TOTP secret for 2FA. |
+| `--totp-secret <secret>` | Base32 TOTP secret (16–128 characters) or `otpauth://` provisioning URI. |
+| `--totp-algorithm <name>` | `SHA1` (default), `SHA256`, or `SHA512`. URI parameters override explicit settings. |
+| `--totp-digits <n>` | Code length, 6–9 digits (default 6). |
+| `--totp-period <seconds>` | Rotation period, 15–300 seconds (default 30). |
 | `--sso-provider <provider>` | SSO provider (e.g. `google`, `github`, `microsoft`). |
 | `--output json`, `-o json` | Output raw JSON object. |
 
@@ -170,7 +173,10 @@ Update a credential.
 |------|-------------|
 | `--name <name>` | New name for the credential. |
 | `--value <name=value>` | Field name/value pair to update (repeatable). |
-| `--totp-secret <secret>` | Base32-encoded TOTP secret (set to an empty string to remove). |
+| `--totp-secret <secret>` | Replacement base32 secret (16–128 characters) or `otpauth://` URI. Raw secret rotation retains stored settings when flags are omitted; a URI uses its own settings or defaults. |
+| `--totp-algorithm <name>` | `SHA1`, `SHA256`, or `SHA512`; requires `--totp-secret`. |
+| `--totp-digits <n>` | Code length, 6–9 digits; requires `--totp-secret`. |
+| `--totp-period <seconds>` | Rotation period, 15–300 seconds; requires `--totp-secret`. |
 | `--sso-provider <provider>` | SSO provider (set to an empty string to remove). |
 | `--output json`, `-o json` | Output raw JSON object. |
 
 
@@ -103,6 +103,8 @@ set `provider: "kernel"` so KERNEL stores the values and hosts collection. the a
 
 password and totp fields must be sensitive. usernames and email addresses can also remain sensitive; `fill` works either way. fields marked `sensitive: false` return their stored values in item responses.
 
+Vault `totp` fields currently generate SHA1, six-digit codes every 30 seconds. Configurable TOTP settings on stored managed-auth credentials do **not** apply to vault items. For a non-default algorithm, digit count, or period, don't use a vault `totp` field for fill until that API supports those settings.
+
 `fields` is an ordered array. define fields in the same top-to-bottom order as the website; collection forms preserve it exactly. `name` remains authoritative for `state.fields`, updates, and `fill`. `label` only changes display text and is returned as non-secret metadata. labels must be nonempty, trimmed, single-line display text of at most 128 utf-8 bytes.
 
 an item accepts 1–32 named fields. field names must start with an ascii letter, contain only ascii letters, numbers, and underscores, and be at most 64 characters. `email` values must be bare valid addresses such as `user@example.com`; use `text` for usernames that aren't valid email addresses. initial values must be nonempty strings and fit within 16 kib of utf-8 data each; `null` and empty strings aren't accepted on creation.