Merge coti-sdk-pod docs and upgrade to latest updates

README.md

@@ -12,4 +12,4 @@ Our developer documentation serves as a comprehensive guide to understanding and
 
 * [**Technology Overview**](how-coti-works/): Dive into the technical foundations of the COTI network, including the cryptographic principles and innovative solutions behind its operation.
 * [**Quickstart Guide**](build-on-coti/quickstart.md): Get up and running with the COTI network quickly, using step-by-step instructions and practical examples.
-* [**Developer Tools**](build-on-coti/tools/): Check out the innovative tools and resources to empower developers and organizations.
+* [Privacy on Demand](privacy-on-demand/README.md) — Private computation on COTI with EVM orchestration (PoD)

SUMMARY.md

@@ -116,8 +116,14 @@
   * [Async private operations](privacy-on-demand/async-private-operations.md)
   * [How do PoA fees work?](privacy-on-demand/how-poa-fees-work.md)
   * [For developers: mapping concepts to the SDK](privacy-on-demand/for-developers-mapping-to-the-sdk.md)
+  * [Account onboarding (AES key)](privacy-on-demand/account-onboarding-aes-key.md)
+  * [COTI TypeScript SDK for PoD](privacy-on-demand/coti-typescript-sdk-for-pod.md)
+  * [TypeScript PoD SDK](privacy-on-demand/typescript-pod-sdk.md)
+  * [Reference: data types (it/ct/gt)](privacy-on-demand/reference-data-types.md)
+  * [Reference: PodLib primitives](privacy-on-demand/reference-podlib-and-primitives.md)
+  * [Contract patterns checklist](privacy-on-demand/contract-patterns-checklist.md)
+  * [Reference: examples and contracts](privacy-on-demand/reference-examples-and-contracts.md)
   * [Tutorials: building PoD dApps](privacy-on-demand/tutorials-privacy-on-demand.md)
-  * [TypeScript PoD SDK (CotiPodCrypto, PodContract)](privacy-on-demand/typescript-pod-sdk.md)
   * [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-demand/README.md

@@ -16,50 +16,63 @@ Privacy on Demand lets applications use **strong privacy for data and computatio
 
 <h2 style="font-size: 2.35rem; font-weight: 600; margin-top: 1.75rem; margin-bottom: 1rem; line-height: 1.2;">Further resources</h2>
 
-- **[Examples](https://github.com/cotitech-io/coti-pod-sdk/tree/main/contracts/examples)** — Contract examples in the PoD SDK repo.
-- **[PoD SDK documentation](https://github.com/cotitech-io/coti-pod-sdk/tree/main/docs)** — Full SDK docs on GitHub.
-
-The same **Quick Access** and **Further resources** blocks appear on the [docs homepage](../README.md).
+- **[Examples](reference-examples-and-contracts.md)** — Contract examples in `@coti-io/coti-contracts`.
+- **[TypeScript PoD SDK](typescript-pod-sdk.md)** — Full `@coti/pod-sdk` reference.
+- **[coti-sdk-pod on GitHub](https://github.com/coti-io/coti-sdk-pod)** — TypeScript SDK source.
+- **[coti-contracts on GitHub](https://github.com/coti-io/coti-contracts/tree/main/contracts/pod)** — Solidity libraries and examples.
+- **[coti-pod-inbox-contracts on GitHub](https://github.com/coti-io/coti-pod-inbox-contracts)** — Inbox implementation and fee contracts.
 
 </div>
 
 ---
 
-This section explains **what PoD is**, **how it feels to users and operators**, and **how the main pieces fit together**. For step-by-step integration with the **COTI PoD SDK**, use the [npm package](https://www.npmjs.com/package/@coti/pod-sdk), the [documentation on GitHub](https://github.com/cotitech-io/coti-pod-sdk/tree/main/docs), and the links below.
+This section is the **canonical user-facing documentation** for PoD. See [Architecture and main components](architecture-and-components.md) for the three-package stack (`@coti/pod-sdk`, `@coti-io/coti-contracts`, `@coti-io/coti-pod-inbox-contracts`).
 
 ## Who this documentation is for
 
 | Audience | What you will get here |
 | --- | --- |
 | **Product, compliance, and business readers** | Plain-language model of privacy, where data lives, and what “async” private operations mean in practice. |
 | **Architects and technical leads** | End-to-end diagrams, component roles, and boundaries between chains and domains. |
-| **Developers** | A clear map from concepts to Solidity/TypeScript work, plus pointers to the authoritative SDK docs. |
+| **Developers** | Tutorials, API reference, checklists, and links to authoritative contract source. |
 
 ## Table of contents
 
 ### Understand first (readable without writing code)
 
-1. [What is Privacy on Demand?](what-is-privacy-on-demand.md) — Problem, promise, and constraints in everyday language.
-2. [How a private request travels end to end](how-a-private-request-travels-end-to-end.md) — Timeline from user action to decrypted result.
-3. [Architecture and main components](architecture-and-components.md) — Where **Inbox**, **MPC executor**, **PodUser**, and **PodLib** sit, with diagrams.
-4. [Glossary](glossary.md) — Short definitions of terms you will see in PoD and SDK docs.
+1. [What is Privacy on Demand?](what-is-privacy-on-demand.md)
+2. [Privacy on Demand (PoD) for Dummies](pod-for-dummies.md) — non-technical overview
+3. [How a private request travels end to end](how-a-private-request-travels-end-to-end.md)
+4. [Architecture and main components](architecture-and-components.md)
+5. [Glossary](glossary.md)
 
 ### Deeper context
 
-5. [Async private operations (why it is not instant)](async-private-operations.md) — What “pending” means and why UX must reflect it.
-6. [How do PoA fees work?](how-poa-fees-work.md) — Two-way Inbox budgets, oracle conversion, and step-by-step gas-unit consumption (worked example).
-7. [For developers: mapping concepts to the SDK](for-developers-mapping-to-the-sdk.md) — Checklists and links to the [PoD SDK documentation on GitHub](https://github.com/cotitech-io/coti-pod-sdk/tree/main/docs).
+6. [Async private operations (why it is not instant)](async-private-operations.md)
+7. [How do PoA fees work?](how-poa-fees-work.md)
+8. [For developers: mapping concepts to the SDK](for-developers-mapping-to-the-sdk.md)
+
+### Integration reference
+
+9. [Account onboarding (AES key)](account-onboarding-aes-key.md)
+10. [COTI TypeScript SDK for PoD](coti-typescript-sdk-for-pod.md)
+11. [TypeScript PoD SDK](typescript-pod-sdk.md) — full `@coti/pod-sdk` reference
+12. [Reference: data types (`it*`, `ct*`, `gt*`)](reference-data-types.md)
+13. [Reference: PodLib primitives](reference-podlib-and-primitives.md)
+14. [Contract patterns checklist](contract-patterns-checklist.md)
+15. [Reference: examples and contracts](reference-examples-and-contracts.md)
 
 ### Tutorials (hands-on)
 
-8. [Tutorials: building PoD dApps](tutorials-privacy-on-demand.md) — When to use **MpcLib / PodLib** primitives vs **custom COTI + host** contracts, with links to focused walkthroughs.
-9. [TypeScript PoD SDK (`CotiPodCrypto`, `PodContract`)](typescript-pod-sdk.md) — Encryption/decryption, fee estimation, method calls, and request ID extraction.
-10. [Cookbook: private investor allocations with PoD](cookbook-private-investor-allocations.md) — Start from a familiar public Sepolia allocation dApp, then make allocation reads and withdrawals private with PoD.
-11. [Tutorial: private Adder on Sepolia](tutorial-private-adder-sepolia.md) — Minimal primitive-only adder: `PodUserSepolia`, fees, TypeScript crypto.
-12. [Tutorial: custom privacy logic with PoD](tutorial-custom-logic.md) — Encrypted messaging shape: `DirectMessageCotiSide` + Sepolia orchestrator.
+16. [Tutorials: building PoD dApps](tutorials-privacy-on-demand.md)
+17. [Cookbook: private investor allocations with PoD](cookbook-private-investor-allocations.md)
+18. [Tutorial: private Adder on Sepolia](tutorial-private-adder-sepolia.md)
+19. [Tutorial: custom privacy logic with PoD](tutorial-custom-logic.md)
 
-## Official technical reference
+## Official code repositories
 
-The machine-readable contracts, types, and APIs live in the open-source SDK. Treat this book chapter as the **human-oriented companion**; treat the repository as the **source of truth** for signatures, fees, and network constants:
+Machine-readable **signatures and constants** live in the repos above. This book is the **documentation source of truth** for integration guidance:
 
-- [COTI PoD SDK — documentation index](https://github.com/cotitech-io/coti-pod-sdk/tree/main/docs)
+- [COTI contracts — PoD contracts](https://github.com/coti-io/coti-contracts/tree/main/contracts/pod)
+- [COTI PoD SDK — TypeScript source](https://github.com/coti-io/coti-sdk-pod)
+- [COTI PoD inbox contracts](https://github.com/coti-io/coti-pod-inbox-contracts)

privacy-on-demand/account-onboarding-aes-key.md

@@ -0,0 +1,66 @@
+# Account onboarding (AES key)
+
+Every PoD user needs an **account AES key** to decrypt `ct*` values returned from private operations. The key is a 16-byte AES secret represented as **32 hexadecimal characters without a `0x` prefix**.
+
+This page describes a practical onboarding flow. Low-level crypto helpers live in [`@coti-io/coti-sdk-typescript`](coti-typescript-sdk-for-pod.md); decryption in app code typically goes through [`CotiPodCrypto`](typescript-pod-sdk.md).
+
+## Trust model
+
+- AES key recovery happens on a **trusted client** (browser, mobile app, or user-controlled wallet extension).
+- A backend may broker encrypted key shares but must **never** see the plaintext AES key.
+- Do not pass the recovered key in URLs, query parameters, or server logs.
+
+## Typical flow
+
+1. Client generates an RSA key pair.
+2. Client sends the RSA **public** key to your onboarding service.
+3. Service returns two encrypted key shares.
+4. Client decrypts and combines shares into the account AES key.
+5. Client stores the key in secure local storage.
+
+## Example implementation
+
+```typescript
+import { generateRSAKeyPair, recoverUserKey } from "@coti-io/coti-sdk-typescript";
+
+type KeySharesResponse = {
+  encryptedKeyShare0: string;
+  encryptedKeyShare1: string;
+};
+
+async function onboardAccount(
+  requestShares: (publicKey: Uint8Array) => Promise<KeySharesResponse>
+): Promise<string> {
+  const { publicKey, privateKey } = generateRSAKeyPair();
+  const { encryptedKeyShare0, encryptedKeyShare1 } = await requestShares(publicKey);
+
+  const accountAesKey = recoverUserKey(privateKey, encryptedKeyShare0, encryptedKeyShare1);
+
+  if (!/^[0-9a-fA-F]{32}$/.test(accountAesKey)) {
+    throw new Error("invalid AES key format");
+  }
+
+  return accountAesKey;
+}
+```
+
+## Storage recommendations
+
+| Environment | Recommendation |
+| --- | --- |
+| Web dApp | Encrypted-at-rest in browser storage with strict origin and session controls |
+| Mobile | OS keychain or secure enclave |
+| Server-rendered apps | Avoid persisting the AES key on the server |
+
+## Operational guardrails
+
+- Never log key shares or the recovered key.
+- Enforce TLS and authenticated onboarding endpoints.
+- Define account recovery and key-rotation policy before production launch.
+- Pair onboarding with [async UX guidance](async-private-operations.md): users cannot decrypt results until onboarding completes.
+
+## See also
+
+- [COTI TypeScript SDK for PoD](coti-typescript-sdk-for-pod.md) — `generateRSAKeyPair`, `recoverUserKey`, decrypt helpers
+- [TypeScript PoD SDK](typescript-pod-sdk.md) — `CotiPodCrypto.decrypt`
+- [Tutorial: private Adder on Sepolia](tutorial-private-adder-sepolia.md) — end-to-end walkthrough that assumes a key is available