Restructure docs

.gitignore

@@ -7,4 +7,5 @@ build
 .vscode
 
 # windsurf rules
-.windsurfrules
+.windsurfrules
+CLAUDE.md

README.md

@@ -40,34 +40,7 @@ Changes to the documentation are automatically deployed when merged to the main
 
 You can access the Mintlify dashboard for this project at:
 [dashboard.mintlify.com](https://dashboard.mintlify.com/turnkey-0e7c1f5b/turnkey-0e7c1f5b)
-
-## The dashboard provides analytics, deployment status, and other management features for our documentation.
-
-## Legacy Documentation
-
-The following information pertains to the previous Docusaurus-based documentation setup.
-
-### Algolia
-
-We use the Algolia plugin for Docusaurus to manage search on our docs page. The primary dashboard can be accessed via https://dashboard.algolia.com/apps/89KSB43UFT/dashboard. Reach out to Jack, Arnaud, or Andrew for access.
-
-#### Crawling
-
-Our crawler settings can be found at https://crawler.algolia.com/admin/crawlers/15584ae7-61de-4f26-af35-4bc55d0de0b5/overview. Algolia crawls our docs site once a week on Monday at 12:31 (UTC). This is simply the default behavior. There are cases where we may want to forcefully trigger Algolia to crawl/index our site, i.e. when we do a big refactor or otherwise reorganize the structure of our docs significantly.
-
-In order to manually trigger a new crawl, use the `Restart crawling` button:
-
-<img src="./static/algolia-crawler.png" />
-
-Our docs site is small, so each crawl is quick (~30-60s).
-
-### Vercel
-
-Each push to Github will trigger a Vercel build:
-
-<img src="./static/vercel.png" />
-
-This is a convenient way to view changes, add feedback, and collaborate overall. Any build can also be promoted to production, if need be.
+The dashboard provides analytics, deployment status, and other management features for our documentation.
 
 ## Build & Code Generation
 
@@ -79,3 +52,20 @@ We provide the following Make targets to generate API reference content:
 - `make tags`: Generate the endpoint-tags MDX snippet at `snippets/data/endpoint-tags.mdx`.
 
 These commands require Node.js and `ts-node`.
+
+---
+
+**Shared Snippets Usage Guidelines**
+
+The docs in this repository utilize shared MDX snippets to ensure consistency and adherence to DRY principles across duplicate pages. When identical content is required in multiple locations, each duplicate page imports a shared snippet from the `/snippets/shared/` folder. This method minimizes maintenance overhead by centralizing content updates.
+
+**Important:** Always update the shared MDX file rather than modifying individual duplicate pages. This guarantees that any change propagates throughout all references.
+
+| Duplicate Page Path                                          | Shared MDX File                        |
+| ------------------------------------------------------------ | -------------------------------------- |
+| `concepts/policies/overview.mdx`                             | `/snippets/shared/policy-engine.mdx`   |
+| `products/embedded-wallets/features/policy-engine.mdx`         | `/snippets/shared/policy-engine.mdx`   |
+| `products/transaction-automation/features/export-wallets.mdx`  | `/snippets/shared/export-wallets.mdx`  |
+| `products/transaction-automation/features/import-wallets.mdx`  | `/snippets/shared/import-wallets.mdx`  |
+
+*Note: Duplicate pages must reside in separate file paths as required by `docs.json`. Mintlify restricts pages with identical content from sharing the same path to ensure correct sidebar behavior.*

authentication/email.mdx

@@ -1,7 +1,6 @@
 ---
-title: "Overview"
+title: "Email Auth & Recovery"
 description: "Email Authentication enables users to authenticate and recover their Turnkey accounts using email-based verification. There are two methods of email authentication:"
-sidebarTitle: "Email"
 ---
 
 **One-Time Password**
@@ -26,7 +25,10 @@ Email Authentication is built with expiring API keys as the foundation. The two
 The authentication process happens in two steps:
 
 <Steps>
-  <Step>A 6-9 digit or alphanumeric OTP code is sent to the user's verified email address</Step>
+  <Step>
+    A 6-9 digit or alphanumeric OTP code is sent to the user's verified email
+    address
+  </Step>
   <Step>
     Upon verification of the correct code, an API key credential is generated
     and encrypted for the client
@@ -39,6 +41,18 @@ The API key credential is encrypted and delivered directly through email to the
 
 In both cases, once the credential is live on the client side (within the context of an iframe), it is readily available to stamp (authenticate) requests. See the [enclave to end-user secure channel](/security/enclave-secure-channels) for more info on how we achieve secure delivery.
 
+## Prerequisites
+
+Make sure you have set up your primary Turnkey organization with at least one API user that can programmatically initiate email auth on behalf of suborgs. Check out our [Quickstart guide](/getting-started/quickstart) if you need help getting started. To allow an API user to initiate email auth, you'll need the following policy in your main organization:
+
+```json
+{
+  "effect": "EFFECT_ALLOW",
+  "consensus": "approvers.any(user, user.id == '<YOUR_API_USER_ID>')",
+  "condition": "activity.resource == 'AUTH' && activity.action == 'CREATE'"
+}
+```
+
 ## User Experience
 
 ### OTP-based Authentication Flow
@@ -109,6 +123,58 @@ The recovery process consists of two phases:
   <img src="/images/authentication/img/auth_email.png" alt="auth email" />
 </Frame>
 
+## Email Customization
+
+We offer customization for the following:
+
+- `appName`: the name of the application. This will be used in the email's subject, e.g. `Sign in to ${appName}`
+- `logoUrl`: a link to a PNG with a max width of 340px and max height of 124px
+- `magicLinkTemplate`: a template for the URL to be used in the magic link button, e.g. `https://dapp.xyz/%s`. The auth bundle will be interpolated into the `%s`
+
+```js
+// Sign and submits the EMAIL_AUTH activity
+const response = await client.emailAuth({
+  type: "ACTIVITY_TYPE_EMAIL_AUTH",
+  timestampMs: String(Date.now()),
+  organizationId: <sub-organization-id>,
+  parameters: {
+    email: <user-email>,
+    targetPublicKey: <iframe-public-key>,
+    apiKeyName: <optional-api-key-name>,
+    expirationSeconds: <optional-api-key-expiration-in-seconds>,
+    emailCustomization: {
+      appName: <optional-your-app-name>,
+      logoUrl: <optional-your-logo-png>,
+      magicLinkTemplate: <optional-magic-link>
+    }
+  },
+});
+```
+
+### Email Templates
+
+We also support custom HTML email templates for [Enterprise](https://www.turnkey.com/pricing) clients on the **Scale** tier. This allows you to inject arbitrary data from a JSON string containing key-value pairs. In this case, the `emailCustomization` variable may look like:
+
+```js
+...
+emailCustomization: {
+  templateId: <HTML-template-stored-in-turnkey>,
+  templateVariables: "{\"username\": \"alice and bob\"}"
+}
+...
+```
+
+In this specific example, the value `alice and bob` can be interpolated into the email template using the key `username`. The use of such template variables is purely optional.
+
+Here's an example of a custom HTML email containing an email auth bundle:
+
+<Frame>
+  ![dynamic email auth
+  example](/images/embedded-wallets/img/email-auth-example-dynamic.png)
+</Frame>
+
+If you are interested in implementing bespoke, fully-customized email templates, please reach out to [[email protected]](mailto:[email protected]).
+
 ## Authorization
 
 Authorization is managed through our [policy engine](/concepts/policies/overview):

authentication/overview.mdx

@@ -3,8 +3,6 @@ title: Overview
 description: Learn about supported authentication methods for Turnkey, how to add them, and usage details.
 ---
 
-# Overview
-
 Turnkey's wallet system supports granular controls on who can access wallets and what actions different users can perform.
 
 To enforce these controls, Turnkey's API must verify the identity of the party requesting a wallet action, ensuring that only authorized actions are executed by the system. This process is known as **authentication**.
@@ -68,11 +66,4 @@ For information about managing authenticated sessions, see our [Sessions](/authe
   <Card title="Sessions" icon="clock" href="/authentication/sessions">
     Manage authenticated user sessions and access tokens in your application.
   </Card>
-  <Card
-    title="API Stamps"
-    icon="stamp"
-    href="/developer-reference/api-overview/stamps"
-  >
-    Authenticate and sign requests to the Turnkey API with cryptographic stamps.
-  </Card>
 </CardGroup>

concepts/overview.mdx

@@ -3,16 +3,34 @@ title: "Overview"
 description: "Turnkey is flexible, scalable, and secure wallet infrastructure that can be used for transaction automation (e.g., payments flows, smart contract management), or non-custodial embedded wallets. Turnkey offers low-level primitives that can be combined to accomplish a variety of goals."
 ---
 
-When you sign up to Turnkey, you create an **[organization](/concepts/organizations)**, which is a segregated collection of users (including root users), wallets, and policies that are controlled by your business. This top level organization that is initially created, often referred to as your parent organization, is generally meant to represent an entire Turnkey-powered application. **[Users](/concepts/users/introduction)** can access Turnkey via their **[credentials](/concepts/users/credentials)** (e.g., API key, passkey). There are two primary ways for users to interact with Turnkey -- via the [Turnkey Dashboard](https://app.turnkey.com/dashboard), and by submitting activity requests via our public API. The Turnkey Dashboard, which is where you'll first create your Turnkey parent organization, is where root users of your parent organization will typically manage administrative activities. It supports passkey authentication only. On the other hand, interactions with Turnkey at scale (primarily, interactions initiated by end users) can be done via programmatically calling the Turnkey public API and submitting activity requests, with a variety of authentication methods supported. Users can submit **[activities](/developer-reference/api-overview/submissions)** (e.g. sign transaction, create user) based on the permissions granted by **[policies](/concepts/policies/overview)**. Root users are a special type of user that can bypass our policy engine and take any action if the threshold of **[root quorum](/concepts/users/root-quorum)** is met. Finally, **[wallets](/concepts/wallets)** are HD seed phrases that can derive many wallet accounts (i.e., individual addresses) which are used for signing operations.
+Turnkey’s security and flexibility enables you to build cutting-edge user experiences, whether you’re using our bare-bones API or pre-built UI components. To make the most out of your implementation, we recommend reading through the following Concepts page for a better understanding of how our products work, and how to best utilize all of Turnkey’s features.
 
-Parent organizations can create **[sub-organizations](/concepts/sub-organizations)**, a segregated set of users, policies, and wallets to which the parent has read access, but not write access. These sub-organizations typically map to an end user in an embedded wallet setup, but can be used wherever you may need full segregation of Turnkey resources.
+### How Turnkey works
+
+At the core of Turnkey is an important concept: instead of directly managing private keys, wallets are accessed through authenticators like passkeys, social logins, or API keys:
 
 <Frame>
   <img src="/images/concepts/all_concepts.png" alt="all concepts screenshot" />
 </Frame>
 
+- **Organizations (parent orgs)** in Turnkey are top-level entities that contain users, wallets, and policies for a business, with the initial “parent organization” typically representing an entire Turnkey-powered application.
+- Parent organizations can create **sub-organizations (sub-orgs)**, which are fully segregated organizations nested under the parent organization. Parent orgs cannot modify the contents of a sub-org, and sub-orgs and typically represent an end user.
+- Both parent organizations and sub-organizations contain a set of **resources and authenticators** that you can configure, including their own users, wallets, API keys, private keys, and policies.
+- **Activities** (like signing transactions or creating users) are governed by **policies** created via Turnkey’s policy engine, though root users can bypass the policy engine when meeting root quorum requirements.
+- **Wallets** in Turnkey are HD seed phrases that can generate multiple wallet accounts (addresses) for signing operations.
+
+### Managing Turnkey interactions and organizations
+
+There are two primary ways for users to interact with Turnkey — via the Turnkey Dashboard, and by submitting activity requests via our public API.
+
+The Turnkey Dashboard, which is where you’ll first create your Turnkey parent organization, is where root users of your parent organization will typically manage administrative activities. It supports passkey authentication only.
+
+On the other hand, interactions with Turnkey at scale (primarily, interactions initiated by end users) can be done via programmatically calling the Turnkey public API and submitting activity requests, with a variety of authentication methods supported.
+
 ## Concepts dictionary
 
+For more details on individual concepts, feel free to explore our concept-specific documentation (also accessible through the left navbar).
+
 ### Organizations
 
 An organization is a logical grouping of resources like users, policies, and wallets. There are two types of organizations:
@@ -70,52 +88,13 @@ Resources used to generate crypto addresses and sign transactions or messages. W
 
 Learn more about leveraging Wallets across different crypto ecosystems on our [Ecosystem Support](/networks/framework) page.
 
-## Typical implementations
-
-### Transaction Automation
-
-Transaction automation entails a business signing transactions on its own behalf. For example, automating payments flows, managing smart contract deployment or programmatically trading in DeFi.
-
-<Frame>
-  <img
-    src="/images/concepts/transaction_automation_example.png"
-    alt="transaction automation screenshot"
-  />
-</Frame>
-
-In this setup, the business is in full control of its wallets at all times. This use case typically does not require the use of sub-organizations and everything can be managed from the parent organization. We suggest the following setup:
-
-- **Root Users:** After initial setup of your parent organization, set a reasonable root quorum (e.g., 2 of 3), attach backup credentials to each user for safekeeping, and only use the root users in a “break glass” scenario.
-- **Service Users:** Create different users for separate services and/or approval workflows. For example, you might have user A that can automatically sign any transaction with Wallet X, but require both user A and user B to approve transactions with Wallet B.
-- **Service Policies:** Set appropriately restrictive policies based on your security needs.
-- **Wallets:** Create separate wallets where differentiated policies are needed, otherwise just leverage multiple wallet accounts within a single wallet.
-
-### Embedded Wallets
-
-Embedded wallets entail a business creating non-custodial wallets controlled by its end users. For example, allowing an end user to create and use a wallet via Web2 authentication methods like email or OAuth.
-
-<Frame>
-  <img
-    src="/images/concepts/embedded_wallets_example.png"
-    alt="embedded wallets screenshot"
-  />
-</Frame>
-
-This is a non-custodial setup where the end user is in control of its wallet at all times. This use case requires the use of sub-organizations which map to an individual end user, and does not require any wallets in the parent organization. The parent organization will be used by your backend service for onboarding new users and initiating certain authentication methods (e.g., email, SMS), while the sub-organizations will be used by the end users for day-to-day signing. We suggest the following setup:
-
-- **Root Users:** After initial setup of your parent organization, set a reasonable root quorum (e.g., 2 of 3), attach backup credentials to each user for safekeeping, and only use the root users in a “break glass” scenario.
-- **Normal Users:** Create a single service user used for user onboarding and authentication.
-- **Policies:** Set a policy granting the user permission to `CREATE_SUB_ORGANIZATION`, `EMAIL_AUTH`, `OAUTH`, `OTP_AUTH`. For examples of how to create such policies [look here](/concepts/policies/examples).
-- **Sub-organizations:** Create individual sub-organizations for each user that contain a single root user with any relevant credentials, and a single wallet with any relevant wallet accounts.
-
-For more details on each individual concepts, refer to the pages below:
-
 <CardGroup>
   <Card title="Overview" href="/concepts/overview" icon="file-lines" iconType="solid" horizontal>
     Understand Turnkey's core features and fundamentals.
   </Card>
 
 {" "}
+
 <Card
   title="Organizations"
   href="/concepts/organizations"
@@ -136,6 +115,7 @@ For more details on each individual concepts, refer to the pages below:
 </Card>
 
 {" "}
+
 <Card
   title="Users"
   href="/concepts/users/introduction"
@@ -147,6 +127,7 @@ For more details on each individual concepts, refer to the pages below:
 </Card>
 
 {" "}
+
 <Card
   title="Wallets"
   href="/concepts/wallets"
@@ -158,6 +139,7 @@ For more details on each individual concepts, refer to the pages below:
 </Card>
 
 {" "}
+
 <Card
   title="Resource Limits"
   href="/concepts/resource-limits"