Document Inbox system errors and Privacy Portal recovery flows.

SUMMARY.md

@@ -26,6 +26,7 @@
     * [COTI vs others](how-coti-works/advanced-topics/coti-vs-others.md)
 * [Build on COTI](build-on-coti/README.md)
   * [Core Concepts](build-on-coti/core-concepts/README.md)
+    * [What Is Onboarding?](build-on-coti/core-concepts/what-is-onboarding.md)
     * [Account Onboarding Procedure](build-on-coti/core-concepts/onboard-user.md)
     * [Private Data Types](build-on-coti/core-concepts/secure-data-types.md)
     * [Supported Operations on Private Data Types](build-on-coti/core-concepts/secure-operations-and-gas.md)
@@ -62,6 +63,13 @@
     * [Remix Plugin](build-on-coti/tools/remix-plugin.md)
     * [COTI MetaMask Snap](build-on-coti/tools/coti-metamask-snap/README.md)
       * [Snap Integration](build-on-coti/tools/coti-metamask-snap/snap-integration.md)
+    * [COTI Wallet Plugin](build-on-coti/tools/coti-wallet-plugin/README.md)
+      * [Integration Guide](build-on-coti/tools/coti-wallet-plugin/integration-guide.md)
+      * [Configuration](build-on-coti/tools/coti-wallet-plugin/configuration.md)
+      * [API Reference](build-on-coti/tools/coti-wallet-plugin/api-reference.md)
+      * [AES Key Onboarding](build-on-coti/tools/coti-wallet-plugin/aes-key-onboarding.md)
+      * [Onboard Modal Theming](build-on-coti/tools/coti-wallet-plugin/onboard-modal-theme.md)
+      * [Example App](build-on-coti/tools/coti-wallet-plugin/example-app.md)
     * [Developer Sandbox](build-on-coti/tools/developer-sandbox.md)
 * [Private Messaging](private-messaging/README.md)
   * [Quickstart](private-messaging/quickstart.md)
@@ -112,6 +120,9 @@
   * [Privacy on Demand (PoD) for Dummies](privacy-on-demand/pod-for-dummies.md)
   * [How a private request travels end to end](privacy-on-demand/how-a-private-request-travels-end-to-end.md)
   * [Architecture and main components](privacy-on-demand/architecture-and-components.md)
+  * [Networks](privacy-on-demand/networks/README.md)
+    * [COTI Testnet](privacy-on-demand/networks/coti-testnet.md)
+    * [Avalanche Fuji](privacy-on-demand/networks/fuji.md)
   * [Glossary](privacy-on-demand/glossary.md)
   * [Async private operations](privacy-on-demand/async-private-operations.md)
   * [How do PoA fees work?](privacy-on-demand/how-poa-fees-work.md)
@@ -121,6 +132,24 @@
   * [Cookbook: private investor allocations with PoD](privacy-on-demand/cookbook-private-investor-allocations.md)
   * [Tutorial: private Adder on Sepolia](privacy-on-demand/tutorial-private-adder-sepolia.md)
   * [Tutorial: custom privacy logic with PoD](privacy-on-demand/tutorial-custom-logic.md)
+* [Privacy on Avalanche](privacy-on-avalanche/README.md)
+  * [Getting started on Avalanche Fuji (Day 0)](privacy-on-avalanche/getting-started-fuji.md)
+  * [What is Privacy on Avalanche?](privacy-on-avalanche/what-is-privacy-on-avalanche.md)
+  * [Privacy on Avalanche (PoD) for Dummies](privacy-on-avalanche/pod-for-dummies.md)
+  * [How a private request travels end to end](privacy-on-avalanche/how-a-private-request-travels-end-to-end.md)
+  * [Architecture and main components](privacy-on-avalanche/architecture-and-components.md)
+  * [Networks](privacy-on-avalanche/networks/README.md)
+    * [Avalanche Fuji](privacy-on-avalanche/networks/fuji.md)
+    * [COTI Testnet](privacy-on-avalanche/networks/coti-testnet.md)
+  * [Glossary](privacy-on-avalanche/glossary.md)
+  * [Async private operations](privacy-on-avalanche/async-private-operations.md)
+  * [How do PoA fees work?](privacy-on-avalanche/how-poa-fees-work.md)
+  * [For developers: mapping concepts to the SDK](privacy-on-avalanche/for-developers-mapping-to-the-sdk.md)
+  * [Tutorials: building PoD dApps on Avalanche](privacy-on-avalanche/tutorials-privacy-on-avalanche.md)
+  * [TypeScript PoD SDK (CotiPodCrypto, PodContract)](privacy-on-avalanche/typescript-pod-sdk.md)
+  * [Cookbook: private investor allocations with PoD](privacy-on-avalanche/cookbook-private-investor-allocations.md)
+  * [Tutorial: private Adder on Avalanche Fuji](privacy-on-avalanche/tutorial-private-adder-fuji.md)
+  * [Tutorial: custom privacy logic with PoD](privacy-on-avalanche/tutorial-custom-logic.md)
 
 ## Security
 

build-on-coti/core-concepts/onboard-user.md

@@ -4,6 +4,8 @@ Account Onboarding is a procedure that is needed to acquire the EOA unique AES k
 
 Once the EOA is created and funded with native coin, it needs to be onboarded to the system to obtain an AES key. 
 
+For a plain-language explanation for end users, see [What Is Onboarding?](what-is-onboarding.md).
+
 See the [guide for onboarding an account](../guides/account-onboard.md).
 
 After completing the Account Onboard step the wallet has a functional account with the necessary credentials (having own AES key) allowing it to start interacting with the gcEVM operations, including running smart contracts or performing other actions as needed.

build-on-coti/core-concepts/what-is-onboarding.md

@@ -0,0 +1,35 @@
+# What Is Onboarding?
+
+Onboarding is the one-time setup that gives your wallet its encryption key for private on-chain data. A short COTI Network transaction **retrieves** that key (your AES key) for your wallet address so you can encrypt and decrypt private on-chain values.
+
+Until the key is available in your wallet session, you can still use the network normally (public transfers, gas, non-private contracts). You **cannot** read or write private data — for example private balances, amounts, or other encrypted contract variables.
+
+When a dApp needs access to private data, it will ask you to complete onboarding by approving that transaction in your wallet.
+
+{% hint style="info" %}
+**Developers:** see [Account Onboarding Procedure](onboard-user.md) and [Account Onboard](../guides/account-onboard.md).
+{% endhint %}
+
+## Why do I need it?
+
+Private values on COTI are stored encrypted. Encryption and decryption use a key that belongs only to **your** wallet account ([EOA](../../support-and-community/glossary.md#account)).
+
+Your wallet needs that key to:
+
+* **encrypt** inputs before private transactions
+* **decrypt** outputs when you need to see private values
+
+Without it, private features stay locked. The network already associates a unique AES key with your address; onboarding is how your wallet **receives** that key (first time) or **recovers** it again (new device, cleared storage, reinstall). Recovering always returns the **same** key for that address — it does not issue a new one.
+
+## What is the encryption key?
+
+* One AES key per wallet address — not shared across accounts
+* Used only for **your** private data on COTI
+* Held by your wallet / dApp session (for MetaMask users, often inside the [COTI Snap](../tools/coti-metamask-snap/README.md)); you usually never need to copy it
+* Delivered wrapped so only your wallet can open it — not left as plaintext for others to read on-chain
+
+{% hint style="danger" %}
+Treat your AES key like your wallet private key. Anyone who has it can decrypt your private on-chain data. Never share your AES key, seed phrase, or private key.
+{% endhint %}
+
+Technical detail: [AES Keys](../../how-coti-works/advanced-topics/aes-keys.md).

build-on-coti/tools/README.md

@@ -1,2 +1,22 @@
 # Tools
 
+Developer tools for building on COTI.
+
+## SDKs and libraries
+
+* [TypeScript SDK](typescript-sdk.md)
+* [Ethers.js](ethers.js.md)
+* [Python SDK](python-sdk.md)
+* [Web3.py](web3.py.md)
+* [Contracts Library](contracts-library/README.md)
+
+## IDE and wallet plugins
+
+* [Hardhat](hardhat.md)
+* [Remix Plugin](remix-plugin.md)
+* [COTI MetaMask Snap](coti-metamask-snap/README.md)
+* [COTI Wallet Plugin](coti-wallet-plugin/README.md) — React library for adding private token support to wagmi/RainbowKit dApps
+
+## Other
+
+* [Developer Sandbox](developer-sandbox.md)

build-on-coti/tools/coti-metamask-snap/README.md

@@ -30,6 +30,8 @@ Once the snap is installed, the MetaMask site will offer to continue to COTI's c
 
 #### **2. Onboard Account (Retrieve AES Key)**
 
+For a plain-language overview, see [What Is Onboarding?](../../core-concepts/what-is-onboarding.md).
+
 Once you are in the companion dApp site ([metamask.coti.io](https://metamask.coti.io)):
 
 1. Click on the "**Connect Wallet**" button, follow the prompts on MetaMask.

build-on-coti/tools/coti-metamask-snap/snap-integration.md

@@ -1,5 +1,9 @@
 # Snap Integration
 
+{% hint style="info" %}
+**Building a React/wagmi dApp?** Use the [COTI Wallet Plugin](../../coti-wallet-plugin/README.md) instead. It handles Snap RPC wiring, AES onboarding, and private balance decryption through a provider + hooks model. This guide is for low-level Snap integration without the wallet plugin.
+{% endhint %}
+
 ### Integrating your dApp with the COTI MetaMask Snap
 
 If you are building a dApp on the COTI network and want it to interact with the COTI MetaMask snap, follow these steps:

build-on-coti/tools/coti-wallet-plugin/README.md

@@ -0,0 +1,130 @@
+---
+description: React library for adding COTI private token support to wagmi/RainbowKit dApps.
+---
+
+# COTI Wallet Plugin
+
+The **COTI Wallet Plugin** (`@coti-io/coti-wallet-plugin`) is a React library that lets dApp developers add COTI private token (pToken) support to an existing **wagmi v2 + RainbowKit** stack — without building a custom wallet or hand-rolling AES key management.
+
+{% hint style="info" %}
+**Important:** This library is a **plugin for existing dApps and wallets**, not a standalone wallet application. It is designed to be injected into your existing React/wagmi stack to seamlessly enhance standard wallets with COTI network privacy capabilities.
+{% endhint %}
+
+## When to use it
+
+Use the COTI Wallet Plugin when you are building a **React dApp** that needs:
+
+* Wallet connection via MetaMask, Rabby, WalletConnect, and other EIP-1193 wallets
+* AES key onboarding and unlock for private token balances
+* Public ↔ private token bridging
+* Private encrypt/decrypt/send operations
+
+If you are building without React or wagmi, use the lower-level [TypeScript SDK](../typescript-sdk.md), [Ethers.js](../ethers.js.md), or [COTI MetaMask Snap](../coti-metamask-snap/snap-integration.md) integration guides instead.
+
+## What it does
+
+| Capability | How |
+| --- | --- |
+| Wallet connection | `WagmiRainbowKitProvider` — MetaMask, Rabby, WalletConnect, and more |
+| AES onboarding / unlock | Built-in `OnboardModal` — Snap, contract onboarding, encrypted backup restore |
+| Private balance display | Auto-decrypt on-chain ciphertext balances |
+| Public ↔ private bridging | Native COTI bridge on COTI chains; PoD Privacy Portal on Sepolia / Avalanche Fuji |
+| Private crypto ops | `encryptPrivateValue`, `decryptPrivateValue`, `sendPrivateToken` |
+| Network enforcement | `NetworkGuard` for supported chains |
+
+## Supported chains
+
+| Chain | Chain ID | Portal strategy |
+| --- | --- | --- |
+| COTI Testnet | 7082400 | COTI native bridge |
+| COTI Mainnet | 2632500 | COTI native bridge |
+| Sepolia | 11155111 | PoD Privacy Portal |
+| Avalanche Fuji | 43113 | PoD Privacy Portal |
+
+Unlock is wallet-based (same on every supported chain), in preferred order:
+
+1. MetaMask Snap (when MetaMask + Snap is available)
+2. Encrypted backup restore
+3. Contract onboarding (on COTI)
+4. Manual AES key input (if the host enables it)
+
+See [AES Key Onboarding](aes-key-onboarding.md) for routes and fallbacks.
+
+## Relationship to other COTI tools
+
+| Product | Role |
+| --- | --- |
+| [COTI MetaMask Snap](../coti-metamask-snap/README.md) | Key storage and Snap-backed crypto; the plugin calls it via RPC |
+| [TypeScript SDK](../typescript-sdk.md) | Low-level encrypt/decrypt primitives; wrapped internally by the plugin |
+| [Ethers.js](../ethers.js.md) | Contract onboarding (`generateOrRecoverAes`); used internally |
+| [COTI Privacy Portal](../../../coti-privacy-portal/README.md) | A dApp that may consume the plugin; not required to use the library |
+
+## Installation
+
+```bash
+npm install @coti-io/coti-wallet-plugin
+```
+
+### Peer dependencies
+
+```bash
+npm install react react-dom ethers viem @coti-io/coti-sdk-typescript @metamask/providers @rainbow-me/rainbowkit wagmi @tanstack/react-query
+```
+
+{% hint style="warning" %}
+This release is validated with `@rainbow-me/rainbowkit@2.2.0` and `wagmi@2.14.0`. Keep those two packages on compatible versions in the host app; installing mismatched latest peer versions can break RainbowKit before the plugin loads.
+{% endhint %}
+
+## Quickstart
+
+```tsx
+import {
+  PrivacyBridgeProvider,
+  WagmiRainbowKitProvider,
+  usePrivateUnlock,
+} from '@coti-io/coti-wallet-plugin';
+
+export function Root() {
+  return (
+    <WagmiRainbowKitProvider walletConnectProjectId={process.env.WALLETCONNECT_PROJECT_ID}>
+      <PrivacyBridgeProvider>
+        <App />
+      </PrivacyBridgeProvider>
+    </WagmiRainbowKitProvider>
+  );
+}
+
+export function HeaderUnlockButton() {
+  const privateUnlock = usePrivateUnlock();
+
+  return (
+    <button
+      onClick={() => privateUnlock.toggleLock()}
+      disabled={privateUnlock.isUnlocking}
+    >
+      {privateUnlock.isUnlocked ? 'Lock Private Balances' : 'Unlock Private Balances'}
+    </button>
+  );
+}
+```
+
+See the [Integration Guide](integration-guide.md) for the full provider setup, unlock flow, and private action guards.
+
+## dApp API contract
+
+dApps should **not** handle AES keys in the normal integration path. Use the plugin provider and hook APIs to connect wallets, onboard/unlock private balances, and execute private operations. The plugin owns AES retrieval, backup restore, Snap storage, and Snap-backed decrypt/encrypt calls internally.
+
+For MetaMask Snap wallets, runtime private operations use Snap RPCs without extracting the AES key from Snap. For non-Snap wallets, the plugin keeps any recovered key in plugin session state only as needed.
+
+## Example app
+
+See [Example App](example-app.md) for setup and run instructions. Source code lives in the [coti-wallet-plugin GitHub repository](https://github.com/coti-io/coti-wallet-plugin/tree/main/examples).
+
+## Next steps
+
+* [Integration Guide](integration-guide.md) — provider setup, unlock flow, lock semantics
+* [Configuration](configuration.md) — `configureCotiPlugin()` and onboarding services
+* [API Reference](api-reference.md) — hooks, providers, types, and error codes
+* [AES Key Onboarding](aes-key-onboarding.md) — onboarding routes, contract flow, security
+* [Onboard Modal Theming](onboard-modal-theme.md) — customize the onboarding UI
+* [Example App](example-app.md) — runnable reference dApp