Merge branch 'main' into db-key-loss-ios

Author: jhaaaa

docs/pages/*.mdx

@@ -0,0 +1,9 @@
+# Page not found
+
+This page may have been moved, renamed, or removed. Our docs are actively maintained, so URLs occasionally change.
+
+Please use the search field or links in the header to find what you need.
+
+To request help or report a bug, please [open an issue](https://github.com/xmtp/docs-xmtp-org/issues).
+
+We know how important it is to have reliable documentation and we appreciate your patience.

docs/pages/agents/build-agents/create-a-client.mdx

@@ -15,7 +15,7 @@ const signer = createSigner(user);
 
 const agent = await Agent.create(signer, {
   env: 'dev', // or 'production'
-  dbEncryptionKey: getRandomValues(new Uint8Array(32)), // save it for later
+  dbEncryptionKey: `0x${getRandomValues(new Uint8Array(32))}`, // save it for later
 });
 ```
 
@@ -25,11 +25,11 @@ The XMTP Agent SDK allows you to use environment variables (`process.env`) for e
 
 **Available variables:**
 
-| Variable                 | Purpose                                                        | Example                                 |
-| ------------------------ | -------------------------------------------------------------- | --------------------------------------- |
-| `XMTP_WALLET_KEY`        | Private key for wallet                                         | `XMTP_WALLET_KEY=0x1234...abcd`         |
-| `XMTP_ENV`               | XMTP network environment (`local`, `dev`, or `production`)     | `XMTP_ENV=dev` or `XMTP_ENV=production` |
-| `XMTP_DB_ENCRYPTION_KEY` | Database encryption key for the local database (32 bytes, hex) | `XMTP_DB_ENCRYPTION_KEY=0xabcd...1234`  |
+| Variable                 | Purpose                                                                              | Example                                 |
+| ------------------------ | ------------------------------------------------------------------------------------ | --------------------------------------- |
+| `XMTP_WALLET_KEY`        | Private key for wallet                                                               | `XMTP_WALLET_KEY=0x1234...abcd`         |
+| `XMTP_ENV`               | XMTP network environment (`local`, `dev`, or `production`)                           | `XMTP_ENV=dev` or `XMTP_ENV=production` |
+| `XMTP_DB_ENCRYPTION_KEY` | Database encryption key for the local database (32 bytes, hex string with 0x prefix) | `XMTP_DB_ENCRYPTION_KEY=0xabcd...1234`  |
 
 Using the environment variables, you can setup your agent in just a few lines of code:
 
@@ -40,7 +40,7 @@ import { generatePrivateKey } from 'viem';
 import { getRandomValues } from 'node:crypto';
 
 const walletKey = generatePrivateKey();
-const encryptionKeyHex = getRandomValues(new Uint8Array(32));
+const encryptionKeyHex = `0x${getRandomValues(new Uint8Array(32))}`;
 
 console.log(`Wallet key: ${walletKey}`);
 console.log(`Encryption key: ${encryptionKeyHex}`);
@@ -121,9 +121,13 @@ apiUrl?: string;
  */
 dbPath?: string | null | ((inboxId: string) => string);
 /**
- * Encryption key for the local DB
+ * Encryption key for the local DB (32 bytes)
+ *
+ * Accepts either:
+ * - Uint8Array (32 bytes)
+ * - Hex string with 0x prefix (64 hex characters representing 32 bytes)
  */
-dbEncryptionKey?: Uint8Array;
+dbEncryptionKey?: Uint8Array | `0x${string}`;
 /**
  * Allow configuring codecs for additional content types
  */

docs/pages/agents/build-agents/group-permissions.mdx

@@ -1,13 +1,14 @@
-# Understand the group permissions system
+# Understand group permissions
+
+The group permissions system controls what actions different members can take in a group chat. This guide explains how the system works conceptually. For practical code examples of managing roles and permissions, see [Manage group chats](/agents/build-agents/groups).
 
 ## Member statuses
 
-Member statuses are the roles that can be assigned to each participant (inbox ID) in a group chat. These are the available member statuses:
+Member statuses are the roles that can be assigned to each participant (inbox ID) in a group chat:
 
-- Member
-  - Everyone in a group chat is a member. A member can be granted admin or super admin status. If a member's admin or super admin status is removed, they are still a member of the group.
-- Admin
-- Super admin
+- **Member** - Everyone in a group chat is a member. A member can be granted admin or super admin status. If a member's admin or super admin status is removed, they are still a member of the group.
+- **Admin** - Members with elevated permissions
+- **Super admin** - Highest permission level with full control over the group
 
 ## Options
 
@@ -79,3 +80,10 @@ If you aren't opinionated and don't set any permissions and options, groups will
 - Update group metadata - All members
 
 To learn more about the `All_Members` and `Admin_Only` policy sets, see [group_permissions.rs](https://github.com/xmtp/libxmtp/blob/85dd6d36f46db1ed74fe98273eea6871fea2e078/xmtp_mls/src/groups/group_permissions.rs#L1192-L1226) in the LibXMTP repo.
+
+## Next steps
+
+Now that you understand how the permission system works, see [Manage group chats](/agents/build-agents/groups) for practical code examples of:
+- Adding and removing members
+- Assigning roles
+- Managing group metadata

docs/pages/agents/build-agents/groups.mdx

@@ -6,13 +6,15 @@ Group chats can have metadata like names, descriptions, and images to help users
 To learn more, see the [Gated group example](https://github.com/ephemeraHQ/xmtp-agent-examples/tree/main/examples/xmtp-gated-group) in the xmtp-agents-examples repo.
 :::
 
-## Available metadata fields
+## Group metadata
+
+### Available metadata fields
 
 - `group_name`: The name of the group chat
 - `description`: A description of the group chat
 - `image_url`: A URL pointing to an image for the group chat
 
-## Get and update metadata
+### Get and update metadata
 
 ```js [Node]
 // Get metadata
@@ -26,56 +28,46 @@ await group.updateDescription('New Group Description');
 await group.updateImageUrl('newurl.com');
 ```
 
-## Manage group chat membership
-
-:::tip[Quickstart]
-To learn more, see the [Gated group example](https://github.com/ephemeraHQ/xmtp-agent-examples/tree/main/examples/xmtp-gated-group) in the xmtp-agents-examples repo.
-:::
+## Group membership
 
 The maximum group chat size is 250 members.
 
+### Add members
+
+Add members directly by their Ethereum addresses or by their inbox IDs:
+
 ```js [Node]
-// Get inbox IDs for identities
-const inboxId = await client.getInboxIdByIdentities([
-  bo.identity,
-  caro.identity,
-]);
+// Add members by Ethereum address
+await ctx.addMembersWithAddresses(group, [ address1, address2 ]);
 
-// Add/remove members
+// Add members using inbox IDs
 await group.addMembers([inboxId]);
-await group.removeMembers([inboxId]);
+```
 
-// Get member information
-await group.sync();
-const members = group.members;
-const addedByInboxId = group.addedByInboxId;
+### Remove members
+
+Remove members from the group by their Ethereum addresses or by their inbox IDs:
+
+```js [Node]
+// Remove members by address
+await ctx.removeMembersWithAddresses(group, [ address1, address2 ]);
 
-// Map inbox ID to account identity
-const inboxIdIdentityMap = new Map(
-  members.map((member) => [member.inboxId, member.accountIdentity])
-);
+// Remove members by inbox ID
+await group.removeMembers([inboxId]);
 ```
 
-## Manage group chat admins
+### Get member information
 
-```js [Node]
-// Check admin status
-const isAdmin = group.isAdmin(inboxId);
-const isSuperAdmin = group.isSuperAdmin(inboxId);
+Retrieve and work with member data:
 
-// List admins
-const admins = group.admins;
-const superAdmins = group.superAdmins;
+```js [Node]
+// Sync group data to get latest member information
+await group.sync();
 
-// Add/remove admin status
-await group.addAdmin(inboxId);
-await group.addSuperAdmin(inboxId);
-await group.removeAdmin(inboxId);
-await group.removeSuperAdmin(inboxId);
+// Get all members
+const members = await group.members();
 ```
 
-## Member information
-
 Get detailed information about group members:
 
 ```typescript
@@ -98,3 +90,33 @@ agent.on('text', async (ctx) => {
   }
 });
 ```
+
+## Group roles
+
+Members can be assigned different roles with varying permission levels. To learn more about how the permission system works, see [Understand group permissions](/agents/build-agents/group-permissions).
+
+### Available roles
+
+- **Member** - Default role for all group participants
+- **Admin** - Members with elevated permissions  
+- **Super admin** - Highest permission level (creator starts as super admin)
+
+### Manage roles
+
+Check and assign roles to group members:
+
+```js [Node]
+// Check admin status
+const isAdmin = group.isAdmin(inboxId);
+const isSuperAdmin = group.isSuperAdmin(inboxId);
+
+// List admins
+const admins = group.admins;
+const superAdmins = group.superAdmins;
+
+// Add/remove admin status
+await group.addAdmin(inboxId);
+await group.addSuperAdmin(inboxId);
+await group.removeAdmin(inboxId);
+await group.removeSuperAdmin(inboxId);
+```

docs/pages/agents/build-agents/local-database.mdx

@@ -2,6 +2,12 @@
 
 Each XMTP agent installation maintains its own local database containing message history, conversation state, and cryptographic material. When you delete this database (or use an in-memory database), you create a new installation that counts toward your [installation limits](/chat-apps/core-messaging/manage-inboxes#inbox-update-and-installation-limits).
 
+:::danger[CRITICAL FOR PRODUCTION]
+
+Each time you run your agent, XMTP creates local database files that must be **kept between restarts and between deployments**. Without persistent volumes, each restart creates a new installation and you're **limited to 10 installations per inbox**.
+
+:::
+
 ## Installation limits and revocation rules
 
 Understanding XMTP's installation and inbox limits is critical for production deployments:
@@ -12,6 +18,7 @@ Understanding XMTP's installation and inbox limits is critical for production de
 
 These limits protect inbox integrity and prevent unbounded key state growth across devices. For production environments, always use persistent volumes to back up and preserve your database across agent restarts.
 
+
 ## Understand local database files
 
 The Agent SDK creates database files in the `dbPath` directory (default is `'/'`). These files store your agent's identity and message history.
@@ -30,22 +37,6 @@ xmtp-production-62ff7c82fa2e8c9a0a0c9e58e7247704d102c41e5ceb4dc3573792d7d7a1c688
 - `62ff7c82fa2e8c9a0a0c9e58e7247704d102c41e5ceb4dc3573792d7d7a1c688`: Inbox ID (Your xmtp identity)
 - `.db3`: SQLite database file extension
 
-**Keep these files between deployments:**
-
-- Deleting them creates a new installation each time
-- Reusing them maintains the same installation
-- Each inbox can have up to 10 installations
-
-**For production deployments:**
-
-- Use persistent volumes (Railway volumes, Render disks, etc.)
-- The database needs to persist across restarts
-
-:::warning[Note]
-
-If you hit the 10 installation limit, use [this script](https://github.com/ephemeraHQ/xmtp-agent-examples?tab=readme-ov-file#revoke-installations) to revoke installations.
-
-:::
 
 ## Understand installations
 
@@ -89,45 +80,18 @@ If you deploy your agent to this same network environment, you have 1 inbox with
   />
 </div>
 
-Here are some best practices for agent installation management:
-
-- Configure your deployments to preserve the agent's database
-- Consider how many platforms you'll need before hitting the 10 installation limit
-- Keep track of which installation corresponds to which platform
-- Regularly [check how many installations your agent has](/agents/deploy/debug-agents)
-- [Revoke installations](#revoke-agent-installations) from platforms you no longer use
-
-## Common agent installation scenarios
-
-### Deploy to a new platform
-
-When you deploy your agent to a new platform (e.g., from Railway to Fly.io):
-
-- Your agent creates a new installation for the new platform
-- If you already have 10 installations, you'll need to [revoke one first](#revoke-agent-installations)
-- The new installation will start fresh without conversation history
-
-### Update an existing deployment
-
-When you redeploy your agent to the same platform:
-
-- If the platform preserves the database, the same installation continues working
-- If the platform doesn't preserve the database, a new installation is created
-
 ## Revoke agent installations
 
-:::warning[Important]
+When you revoke an agent installation, it can no longer send or receive messages. However, you can still access the local database. Your agent can still run from any active installations on other deployment platforms.
 
+:::danger[Important]
 Revoking an installation is permanent. You cannot recover access to a revoked installation.
-
 :::
 
-When you revoke an agent installation, it can no longer send or receive messages. However, you can still access the local database.
+1. Web tool: [xmtp.chat/inbox-tools](https://xmtp.chat/inbox-tools)
+2. CLI script: [revokeInstallations.ts](https://github.com/ephemeraHQ/xmtp-agent-examples/blob/eb1dc17e99570b77de906ba0d58094586a4af844/scripts/revokeInstallations.ts) in the xmtp-agent-examples repo
 
-Your agent can still run from any active installations on other deployment platforms.
+  ```bash
+  yarn revoke <inbox-id> <installations-to-exclude>
+  ```
 
-To revoke an agent installation, use [revokeInstallations.ts](https://github.com/ephemeraHQ/xmtp-agent-examples/blob/eb1dc17e99570b77de906ba0d58094586a4af844/scripts/revokeInstallations.ts) in the xmtp-agent-examples repo. For example:
-
-```bash
-yarn revoke <inbox-id> <installations-to-exclude>
-```

docs/pages/agents/concepts/context.mdx

@@ -73,6 +73,15 @@ agent.on('text', async (ctx) => {
 });
 ```
 
+### Get inbox ID by identifier
+
+```typescript
+const inboxId = await ctx.client.getInboxIdByIdentifier({
+  identifier: targetAddress,
+  identifierKind: IdentifierKind.Ethereum,
+});
+```
+
 ### getSenderAddress()
 
 Get the Ethereum address of the message sender:

docs/pages/agents/concepts/identity.mdx

@@ -36,7 +36,7 @@ When you call `Agent.create()`, the following steps happen under the hood:
 
 The `dbEncryptionKey` client option is used by the Node, React Native, Android, and Swift SDKs only.
 
-The encryption key is critical to the stability and continuity of an XMTP client. It encrypts the local SQLite database created when you call `Client.create()`, and must be provided every time you create or build a client.
+The encryption key is used together with an auto-generated salt to encrypt the local database using [SQLCipher](https://www.zetetic.net/sqlcipher/). It encrypts the database created when you call `Agent.create()`.
 
 This encryption key is not stored or persisted by the XMTP SDK, so it's your responsibility as the app developer to store it securely and consistently.
 

docs/pages/agents/content-types/markdown.mdx

@@ -75,6 +75,9 @@ The markdown content type supports the following formatting patterns:
 - `*italic text*` or `_italic text_`
 - `~~strikethrough text~~`
 - \`inline code\`
+- \`\`\`code block\`\`\`
+- > block quote
+- [link](https://www.example.com)
 
 ### Lists
 
@@ -87,18 +90,6 @@ The markdown content type supports the following formatting patterns:
 - Standard markdown table syntax with `|` separators
 - Header rows with `---` separators
 
-### Code blocks
-
-- Fenced code blocks with triple backticks
-- Language-specific syntax highlighting
-- Inline code with single backticks
-
-### Other elements
-
-- Blockquotes with `>`
-- Horizontal rules with `---`
-- Links with `[text](url)`
-- Images with `![alt](url)`
 
 ### Example usage
 

docs/pages/agents/get-started/build-an-agent.mdx

@@ -60,9 +60,11 @@ await agent.start();
 
 Each time you run your agent, XMTP creates local database files that must be **kept between restarts and between deployments**. Without persistent volumes, each restart creates a new installation and you're **limited to 10 installations per inbox**.
 
+To learn more, see [Manage agent local database files and installations](/agents/build-agents/local-database).
+
 :::
 
-XMTP creates local database files in the `dbPath` (default is `'/'`) directory. These files store your device identity and message history. To learn more, see [Manage agent local database files and installations](/agents/build-agents/local-database).
+XMTP creates local database files in the `dbPath` (default is `'/'`) directory. These files store your device identity and message history. 
 
 ### Set environment variables