Document Shamir mnemonic recovery

content/docs/ai/mcp-toolkit/get-started.mdx

@@ -122,7 +122,7 @@ Then in VS Code:
 2. Open GitHub Copilot Chat and select **Agent mode**
 3. Click **Tools** to verify the MCP tools are available
 
-→ [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
+→ [VS Code MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
 </Tab>
 <Tab value="Cursor">
 **Config path:** `.cursor/mcp.json` (project-level)

content/docs/tools/wdk-utils/api-reference.mdx

@@ -465,14 +465,16 @@ Treat the returned `secretKey` as sensitive and clear it after its final use. Th
 
 ### BIP-39 Mnemonic Sharing Helpers
 
+See [Shamir Secret Sharing](/tools/wdk-utils/guides/shamir-secret-sharing) for the complete split, storage, verification, and recovery journey.
+
 | Function | Description | Returns |
 | --- | --- | --- |
 | `splitMnemonic(mnemonic, options)` | Split valid BIP-39 mnemonic entropy into hex-encoded Shamir shares. | `Promise<string[]>` |
-| `combineMnemonic(shares)` | Reconstruct and validate a BIP-39 mnemonic from a threshold-sized share set. | `Promise<string>` |
+| `combineMnemonic(shares)` | Reconstruct and validate a BIP-39 mnemonic from a threshold-or-larger share set. | `Promise<string>` |
 
 #### `splitMnemonic(mnemonic, options)`
 
-Decode a valid 12-, 15-, 18-, 21-, or 24-word English BIP-39 mnemonic to entropy and split it into Shamir shares.
+Normalize and decode a valid 12-, 15-, 18-, 21-, or 24-word English BIP-39 mnemonic to entropy and split it into Shamir shares. The helper receives only the mnemonic words; it does not include an optional BIP-39 passphrase or wallet-specific recovery metadata.
 
 ```javascript title="Split A Mnemonic"
 import { splitMnemonic } from '@tetherto/wdk-utils'
@@ -486,12 +488,13 @@ const shares = await splitMnemonic(seedPhrase, {
 - `shares` must be an integer from `2` through `255`.
 - `threshold` must be an integer from `2` through `shares`.
 - The returned shares are unencrypted lowercase hex strings.
+- The package-specific share strings are not SLIP-39 mnemonic shares. They do not include the recovery threshold or a format-version marker, so retain that metadata separately.
 - Invalid BIP-39 words, word counts, and checksums are rejected.
-- The runtime must provide secure `crypto.getRandomValues`; React Native apps may need to load `react-native-get-random-values` before importing WDK Utils.
+- Node.js uses the dependency's `node:crypto` implementation. Browser and React Native paths must provide secure `crypto.getRandomValues`; React Native apps may need to load `react-native-get-random-values` before importing WDK Utils. In Bare, import from the package root so the Bare entrypoint provides the Node-compatible crypto path; do not load the React Native polyfill. The dependency versions currently resolved for a fresh beta.11 installation require Bare `1.28.0` or later.
 
 #### `combineMnemonic(shares)`
 
-Reconstruct a mnemonic from enough shares produced by `splitMnemonic()`.
+Reconstruct a mnemonic from enough shares produced by the same `splitMnemonic()` call.
 
 ```javascript title="Reconstruct A Mnemonic"
 import { combineMnemonic } from '@tetherto/wdk-utils'
@@ -503,10 +506,12 @@ const restored = await combineMnemonic([
 ])
 ```
 
-The helper verifies the embedded four-byte integrity checksum and rejects malformed, corrupted, duplicate, mixed-length, or insufficient share sets.
+The helper accepts 2 through 255 case-insensitive hex shares and returns the normalized English BIP-39 mnemonic. Shares must have the same length and unique coordinates. `combineMnemonic()` does not receive or recover the original threshold, so the application must retain and enforce it.
+
+Both helpers return Promises that reject with `Error` objects. For `combineMnemonic()`, non-array input, fewer than two shares, non-string entries, and malformed hex retain specific messages. Duplicate coordinates, mixed lengths, more than 255 shares, reconstruction failures, and checksum failures collapse to `Invalid shares: could not reconstruct a valid mnemonic`.
 
 <Callout type="warn">
-Each share is sensitive recovery material. Store shares in separate trusted locations and never log or transmit them through analytics. The embedded checksum detects accidental corruption; it does not authenticate shares or protect against maliciously crafted input.
+Each share is sensitive recovery material. Store shares in separate trusted locations and never log or transmit them through analytics. The embedded 32-bit checksum normally detects accidental corruption, but it can collide and does not authenticate shares or protect against maliciously crafted input. Authenticate the exact share bytes against a tamper-evident record before combining them, then verify the recovered wallet against an independently protected, collision-resistant public identifier.
 </Callout>
 
 ### BIP-21 Bitcoin Payment URI Helpers

content/docs/tools/wdk-utils/configuration.mdx

@@ -21,6 +21,10 @@ npm install react-native-get-random-values
 
 Load the polyfill before importing WDK Utils in the application entrypoint.
 
+```javascript title="React Native Entrypoint"
+import 'react-native-get-random-values'
+```
+
 ## Import address validation helpers
 
 You can import only the validators your flow needs from the package entrypoint:
@@ -117,14 +121,14 @@ import {
 ## Runtime notes
 
 - `@tetherto/wdk-utils` exports plain functions. There is no client object to initialize.
-- The package publishes a default module entrypoint through `index.js` and a bare runtime entrypoint through `bare.js`.
+- The package publishes a default module entrypoint through `index.js` and a Bare runtime entrypoint through `bare.js`. The dependency versions currently resolved for a fresh beta.11 installation require Bare `1.28.0` or later.
 - `validateAddress()` dispatches the CAIP-2 namespaces `bip122`, `eip155`, `solana`, `spark`, and `tron` to their chain validators. Unsupported namespaces return `UNSUPPORTED_CHAIN`, and malformed chain IDs return `INVALID_CHAIN_ID`.
 - For `bip122` and `spark`, the chain reference selects the expected network. A missing, unknown, or incompatible reference returns `NETWORK_MISMATCH`. Other supported namespaces validate the address format but do not enforce the reference value.
 - Successful Bitcoin and Spark validators return `compatibleNetworks`, because some address formats are valid on more than one network. WDK Utils validates structure and network compatibility, not account existence, ownership, or recipient intent.
 - `validateSolanaAddress()` accepts base58-encoded 32-byte public keys, including off-curve program-derived addresses. Solana has no address checksum, so the helper cannot detect every mistyped address.
 - `splitMnemonic()` accepts valid 12-, 15-, 18-, 21-, or 24-word English BIP-39 phrases. It returns hex-encoded Shamir shares and supports threshold schemes from 2-of-2 through 255-of-255.
-- `combineMnemonic()` verifies an embedded integrity checksum before returning the reconstructed phrase. The checksum detects corruption but does not authenticate shares.
-- `encrypt()` and `splitMnemonic()` require `globalThis.crypto.getRandomValues`. In React Native, load `react-native-get-random-values` before importing `@tetherto/wdk-utils` when the runtime does not provide secure random bytes.
+- `combineMnemonic()` verifies an embedded 32-bit integrity checksum before returning the reconstructed phrase. The checksum normally detects accidental corruption, but it can collide and does not authenticate shares.
+- `encrypt()` requires `globalThis.crypto.getRandomValues`. In Node.js, `splitMnemonic()` uses the dependency's `node:crypto` implementation; browser and React Native paths require `globalThis.crypto.getRandomValues`. In React Native, load `react-native-get-random-values` before importing `@tetherto/wdk-utils` when the runtime does not provide secure random bytes. In Bare, import from the package root so the Bare entrypoint provides the Node-compatible crypto path; do not load the React Native polyfill.
 - `parseBip21Request()` accepts `bitcoin:` URIs with a validated Bitcoin address and optional `amount`, `label`, and `message` parameters.
 - `encodeBip21Request()` validates the Bitcoin address and amount before returning a `bitcoin:` URI.
 - `encrypt()` returns a versioned payload with hex-encoded `salt`, `iv`, `tag`, and `ciphertext` fields plus the scrypt cost parameters used for key derivation.
@@ -210,25 +214,7 @@ const encrypted = encrypt(seedPhrase, passphrase)
 const restoredSeedPhrase = decrypt(encrypted, passphrase)
 ```
 
-You can split a BIP-39 mnemonic into shares that require a threshold to recover:
-
-```javascript title="Split And Recover A Mnemonic"
-import 'react-native-get-random-values' // React Native only; load before WDK Utils
-import { combineMnemonic, splitMnemonic } from '@tetherto/wdk-utils'
-
-const shares = await splitMnemonic(seedPhrase, {
-  shares: 5,
-  threshold: 3
-})
-
-const restored = await combineMnemonic([
-  shares[0],
-  shares[2],
-  shares[4]
-])
-```
-
-Treat every unencrypted share as sensitive recovery material. Store shares separately and do not send them to logs, analytics, or untrusted services.
+For mnemonic sharing, follow [Shamir Secret Sharing](/tools/wdk-utils/guides/shamir-secret-sharing) to choose a threshold, authenticate stored shares, verify the recovery path, and understand compatibility limits. In React Native, load the random-values polyfill in the application entrypoint as shown above rather than importing it in shared Node.js or browser code.
 
 You can derive independent keys for application-specific purposes by using distinct domain labels: