diff --git a/apps/docs/content/guides/auth/auth-mfa/phone.mdx b/apps/docs/content/guides/auth/auth-mfa/phone.mdx
index c903dd95165..649e87d4b97 100644
--- a/apps/docs/content/guides/auth/auth-mfa/phone.mdx
+++ b/apps/docs/content/guides/auth/auth-mfa/phone.mdx
@@ -12,16 +12,25 @@ The phone messaging configuration for MFA is shared with [phone auth login](/doc
Below is a flow chart illustrating how the Enrollment and Verify APIs work in the context of MFA (Phone).
-
+```mermaid
+flowchart TD
+ InitS((Setup flow)) --> SAAL1[/Session is AAL1/]
+ SAAL1 --> Enroll[Enroll API]
+ Enroll --> ChallengeAPI[Challenge API]
+ ChallengeAPI --> Scan[/Code sent to User/]
+ Scan --> Enter[User: Enter code]
+ Enter --> Verify[Verify API]
+ Verify --> Check{{Is code correct?}}
+ Check -->|Yes| AAL2[/Upgrade to AAL2/]
+ AAL2 --> Done((Done))
+ Check -->|No| Enter
+ InitA((Login flow)) --> SignIn([User: Sign-in])
+ SignIn --> AAL1[/Upgrade to AAL1/]
+ AAL1 --> ListFactors[List Factors API]
+ ListFactors -->|1 or more factors| OpenAuth([User: Select phone factor])
+ OpenAuth --> Enter
+ ListFactors -->|0 factors| Setup[[Setup flow]]
+```
### Add enrollment flow
diff --git a/apps/docs/content/guides/auth/auth-mfa/totp.mdx b/apps/docs/content/guides/auth/auth-mfa/totp.mdx
index c1869fbb097..906c0b81b14 100644
--- a/apps/docs/content/guides/auth/auth-mfa/totp.mdx
+++ b/apps/docs/content/guides/auth/auth-mfa/totp.mdx
@@ -12,16 +12,25 @@ The use of a QR code was [initially introduced by Google Authenticator](https://
Below is a flow chart illustrating how the Enrollment, Challenge, and Verify APIs work in the context of MFA (TOTP).
-
+```mermaid
+flowchart TD
+ InitS((Setup flow)) --> SAAL1[/Session is AAL1/]
+ SAAL1 --> Enroll[Enroll API]
+ Enroll --> ShowQR[Show QR code]
+ ShowQR --> Scan([User: Scan QR code in authenticator])
+ Scan --> Enter([User: Enter code])
+ Enter --> Verify[Challenge + Verify API]
+ Verify --> Check{{Is code correct?}}
+ Check -->|Yes| AAL2[/Upgrade to AAL2/]
+ AAL2 --> Done((Done))
+ Check -->|No| Enter
+ InitA((Login flow)) --> SignIn([User: Sign-in])
+ SignIn --> AAL1[/Upgrade to AAL1/]
+ AAL1 --> ListFactors[List Factors API]
+ ListFactors -->|1 or more factors| OpenAuth([User: Open authenticator])
+ OpenAuth --> Enter
+ ListFactors -->|0 factors| Setup[[Setup flow]]
+```
[TOTP MFA API](/docs/reference/javascript/auth-mfa-api) is free to use and is enabled on all Supabase projects by default.
diff --git a/apps/docs/content/guides/auth/signing-keys.mdx b/apps/docs/content/guides/auth/signing-keys.mdx
index 2fcd8b3ce59..771cc541fcc 100644
--- a/apps/docs/content/guides/auth/signing-keys.mdx
+++ b/apps/docs/content/guides/auth/signing-keys.mdx
@@ -74,31 +74,12 @@ Key rotation and revocation are one of the most important processes for maintain
### Lifetime of a signing key
-
-
-
-
-
-
A newly created key starts off as standby, before being rotated into in use (becoming the current key) while the existing current key becomes previously used.
At any point you can move a key from the previously used or revoked states back to being a standby key, and rotate to it. This gives you the confidence to revert back to an older key if you identify problems with the rotation, such as forgetting to update a component of your application that is relying on a specific key (for example, the legacy JWT secret).
Each action on a key is reversible (except permanent deletion).
-
-
-
-
| Action | Accepted JWT signatures | Description |
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create a new key | Current key only, new key has not created any JWTs yet. | When you initially create a key, after choosing the signing algorithm or importing a private key you already have, it starts out in the standby state. If using an asymmetric key (RSA, Elliptic Curve) its public key will be available in the discovery endpoint. Supabase Auth does not use this key to create new JWTs. |
diff --git a/apps/docs/content/guides/database/connecting-to-postgres.mdx b/apps/docs/content/guides/database/connecting-to-postgres.mdx
index 20e48681bd6..eace71d0811 100644
--- a/apps/docs/content/guides/database/connecting-to-postgres.mdx
+++ b/apps/docs/content/guides/database/connecting-to-postgres.mdx
@@ -315,14 +315,16 @@ Because the dedicated pooler is hosted on the same machine as your database, it
See the [connection method matrix](#how-to-connect-to-your-postgres-databases) at the top of this page for a quick reference, or follow the decision flow in the diagram below to choose the right option for your environment.
-
+```mermaid
+flowchart TD
+ A[Where are you connecting from?] --> B[Persistent Backend]
+ A --> C[Serverless / Edge]
+ B --> D{IPv6 Supported? IPv4 Add-on?}
+ B --> E{IPv4 Needed?}
+ C --> H{IPv6 Supported? IPv4 Add-on?}
+ C --> I{IPv4 Needed?}
+ D --> F[Use Direct Connection]
+ E --> G[Use Supavisor Session Mode]
+ H --> J[Use Dedicated Pooler PgBouncer Pro]
+ I --> K[Use Supavisor Transaction Mode]
+```
diff --git a/apps/docs/content/guides/local-development/seeding-your-database.mdx b/apps/docs/content/guides/local-development/seeding-your-database.mdx
index 4426ea1f7f8..0bce7ba4064 100644
--- a/apps/docs/content/guides/local-development/seeding-your-database.mdx
+++ b/apps/docs/content/guides/local-development/seeding-your-database.mdx
@@ -98,7 +98,29 @@ export default defineConfig({
Suppose you have a database with the following schema:
-
+```mermaid
+erDiagram
+ User ||--o{ Post : createdBy
+ User ||--o{ Comment : userId
+ Post ||--o{ Comment : postId
+ User {
+ bigint id PK
+ text email
+ text name
+ }
+ Post {
+ bigint id PK
+ text title
+ text content
+ bigint createdBy FK
+ }
+ Comment {
+ bigint id PK
+ text text
+ bigint userId FK
+ bigint postId FK
+ }
+```
You can use the seed script example generated by Snaplet `seed.ts` to define the values you want to generate. For example:
@@ -107,8 +129,8 @@ You can use the seed script example generated by Snaplet `seed.ts` to define the
- Three `Post.comments` from three different users.
```ts seed.ts
-import { createSeedClient } from '@snaplet/seed'
import { copycat } from '@snaplet/copycat'
+import { createSeedClient } from '@snaplet/seed'
async function main() {
const seed = await createSeedClient({ dryRun: true })
diff --git a/apps/docs/content/guides/platform/read-replicas.mdx b/apps/docs/content/guides/platform/read-replicas.mdx
index e0a106e0c3d..212ee1bea9a 100644
--- a/apps/docs/content/guides/platform/read-replicas.mdx
+++ b/apps/docs/content/guides/platform/read-replicas.mdx
@@ -45,10 +45,21 @@ You can only read data from a Read Replica. This is in contrast to a Primary dat
When your database starts slowing down, you face a choice: make your existing database bigger (scale vertically), or spread the load across multiple databases (scale horizontally). Both approaches work. Neither is universally correct. The right answer depends on your workload, your budget, and where the bottleneck actually is.
-
+```mermaid
+flowchart TD
+ A[Database slowing down] --> B{CPU above 70% sustained?}
+ B -->|No| C[Monitor, do not scale yet]
+ B -->|Yes| D{Queries optimized? Indexes in place?}
+ D -->|No| E[Run EXPLAIN ANALYZE Add missing indexes Optimize first]
+ E --> D
+ D -->|Yes| F{Workload 80%+ reads?}
+ F -->|No| G[Upgrade compute Replicas will not help writes]
+ F -->|Yes| H{Already at 16XL?}
+ H -->|Yes| I[Read Replicas Only horizontal option left]
+ H -->|No| J{Need workload isolation or geo-distribution?}
+ J -->|Yes| K[Read Replicas]
+ J -->|No| L[Either works Compute is simpler Replicas scale further]
+```
diff --git a/apps/docs/content/guides/storage/schema/design.mdx b/apps/docs/content/guides/storage/schema/design.mdx
index f2d380a8dd4..e0f06401c90 100644
--- a/apps/docs/content/guides/storage/schema/design.mdx
+++ b/apps/docs/content/guides/storage/schema/design.mdx
@@ -18,7 +18,37 @@ This is important because the storage schema only stores the metadata and the ac
Here is the schema that represents the Storage service:
-
+```mermaid
+erDiagram
+ buckets ||--o{ objects : "buckets_id:id"
+ buckets {
+ text id PK
+ text name
+ timestamptz created_at
+ timestamptz updated_at
+ boolean public
+ bigint file_size_limit
+ text[] allowed_mime_types
+ text owner_id
+ }
+ objects {
+ uuid id PK
+ text bucket_id FK
+ text name
+ timestamptz created_at
+ timestamptz updated_at
+ jsonb metadata
+ text[] path_tokens
+ text version
+ text owner_id
+ }
+ migrations {
+ integer id PK
+ varchar(100) name
+ varchar(40) hash
+ timestamp executed_at
+ }
+```
You have the option to query this table directly to retrieve information about your files in Storage without the need to go through our API.
diff --git a/apps/docs/public/img/guides/auth-mfa/auth-mfa-flow.svg b/apps/docs/public/img/guides/auth-mfa/auth-mfa-flow.svg
deleted file mode 100644
index d7dd78a4bf0..00000000000
--- a/apps/docs/public/img/guides/auth-mfa/auth-mfa-flow.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/apps/docs/public/img/guides/auth-mfa/auth-mfa-phone-flow.svg b/apps/docs/public/img/guides/auth-mfa/auth-mfa-phone-flow.svg
deleted file mode 100644
index 976dd3525c4..00000000000
--- a/apps/docs/public/img/guides/auth-mfa/auth-mfa-phone-flow.svg
+++ /dev/null
@@ -1,3 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/apps/docs/public/img/guides/auth-signing-keys/states.svg b/apps/docs/public/img/guides/auth-signing-keys/states.svg
deleted file mode 100644
index fc49db026d7..00000000000
--- a/apps/docs/public/img/guides/auth-signing-keys/states.svg
+++ /dev/null
@@ -1,2 +0,0 @@
-
-
diff --git a/apps/docs/public/img/guides/cli/snaplet-example-schema.png b/apps/docs/public/img/guides/cli/snaplet-example-schema.png
deleted file mode 100644
index dab45e505a4..00000000000
Binary files a/apps/docs/public/img/guides/cli/snaplet-example-schema.png and /dev/null differ
diff --git a/apps/docs/public/img/guides/cli/workflow.png b/apps/docs/public/img/guides/cli/workflow.png
deleted file mode 100644
index f23f1c21905..00000000000
Binary files a/apps/docs/public/img/guides/cli/workflow.png and /dev/null differ
diff --git a/apps/docs/public/img/guides/database/connecting-to-postgres/connection-decision-tree-light.svg b/apps/docs/public/img/guides/database/connecting-to-postgres/connection-decision-tree-light.svg
deleted file mode 100644
index 51bfe3a7a42..00000000000
--- a/apps/docs/public/img/guides/database/connecting-to-postgres/connection-decision-tree-light.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/apps/docs/public/img/guides/database/connecting-to-postgres/connection-decision-tree.svg b/apps/docs/public/img/guides/database/connecting-to-postgres/connection-decision-tree.svg
deleted file mode 100644
index 576e76ea87d..00000000000
--- a/apps/docs/public/img/guides/database/connecting-to-postgres/connection-decision-tree.svg
+++ /dev/null
@@ -1,102 +0,0 @@
-
\ No newline at end of file
diff --git a/apps/docs/public/img/guides/integrations/onesignal/diagram.png b/apps/docs/public/img/guides/integrations/onesignal/diagram.png
deleted file mode 100644
index 77b83ca5315..00000000000
Binary files a/apps/docs/public/img/guides/integrations/onesignal/diagram.png and /dev/null differ
diff --git a/apps/docs/public/img/guides/integrations/zuplo/arch.png b/apps/docs/public/img/guides/integrations/zuplo/arch.png
deleted file mode 100644
index af425e632a2..00000000000
Binary files a/apps/docs/public/img/guides/integrations/zuplo/arch.png and /dev/null differ
diff --git a/apps/docs/public/img/guides/platform/read-replicas/read-replicas-flow.svg b/apps/docs/public/img/guides/platform/read-replicas/read-replicas-flow.svg
deleted file mode 100644
index a49c06eb103..00000000000
--- a/apps/docs/public/img/guides/platform/read-replicas/read-replicas-flow.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/apps/docs/public/img/guides/realtime/realtime-arch.png b/apps/docs/public/img/guides/realtime/realtime-arch.png
deleted file mode 100644
index fca216142b1..00000000000
Binary files a/apps/docs/public/img/guides/realtime/realtime-arch.png and /dev/null differ
diff --git a/apps/docs/public/img/storage/schema-design.png b/apps/docs/public/img/storage/schema-design.png
deleted file mode 100644
index 79401732ce2..00000000000
Binary files a/apps/docs/public/img/storage/schema-design.png and /dev/null differ