fix(docs): inject required frontmatter and fix naming collisions in generated API docs

The generate-docs.ts script was overwriting MDX files without the
url, metaTitle, and metaDescription frontmatter fields required by
source.config.ts. Additionally, the naming function produced identical
filenames for list and get-by-id operations (e.g., both GET /v1/projects
and GET /v1/projects/{id} mapped to get-projects.mdx), causing content
corruption and data loss.

Changes:
- Extend beforeWrite hook to derive and inject url, metaTitle,
  metaDescription from the operation metadata
- Use slice-based content replacement instead of String.replace to
  prevent content corruption
- Fix naming regex (By[A-Z][a-z]* → By[A-Z][a-z]{2,}) so ById is
  preserved as -by-id, preventing list/detail filename collisions
- Add pre-commit frontmatter validation step to the sync workflow
- Add stale file cleanup step before generation
- Update meta.json navigation files for new and renamed pages

Author: kristof-siket

.github/workflows/sync-management-api-docs.yml

@@ -35,10 +35,29 @@ jobs:
         working-directory: apps/docs
         run: pnpm fetch-openapi
 
+      - name: Clean stale endpoint files
+        run: find apps/docs/content/docs/management-api/endpoints -name '*.mdx' -type f -delete
+
       - name: Generate docs
         working-directory: apps/docs
         run: pnpm tsx scripts/generate-docs.ts
 
+      - name: Validate generated frontmatter
+        run: |
+          missing=$(find apps/docs/content/docs/management-api/endpoints -name '*.mdx' -type f -exec sh -c '
+            for field in url metaTitle metaDescription; do
+              if ! grep -q "^${field}:" "$1"; then
+                echo "$1: missing $field"
+              fi
+            done
+          ' _ {} \;)
+          if [ -n "$missing" ]; then
+            echo "::error::Generated MDX files have missing required frontmatter fields:"
+            echo "$missing"
+            exit 1
+          fi
+          echo "All generated MDX files have required frontmatter fields"
+
       - name: Check for changes
         id: changes
         run: |

…oints/connections/delete-connections.mdx …connections/delete-connections-by-id.mdxapps/docs/content/docs/management-api/endpoints/connections/delete-connections.mdx renamed to apps/docs/content/docs/management-api/endpoints/connections/delete-connections-by-id.mdx apps/docs/content/docs/management-api/endpoints/connections/delete-connections.mdx renamed to apps/docs/content/docs/management-api/endpoints/connections/delete-connections-by-id.mdx

@@ -9,6 +9,9 @@ _openapi:
     headings: []
     contents:
       - content: Deletes the connection with the given ID.
+url: /management-api/endpoints/connections/delete-connections-by-id
+metaTitle: 'DELETE /v1/connections/{id} | Delete connection - Prisma Postgres'
+metaDescription: 'Management API: Deletes the connection with the given ID. DELETE /v1/connections/{id}.'
 ---
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

apps/docs/content/docs/management-api/endpoints/connections/get-connections-by-id.mdx

@@ -0,0 +1,21 @@
+---
+title: Get connection
+full: true
+_openapi:
+  path: "/v1/connections/{id}"
+  method: GET
+  toc: []
+  structuredData:
+    headings: []
+    contents:
+      - content: Returns the connection with the given ID.
+url: /management-api/endpoints/connections/get-connections-by-id
+metaTitle: 'GET /v1/connections/{id} | Get connection - Prisma Postgres'
+metaDescription: 'Management API: Returns the connection with the given ID. GET /v1/connections/{id}.'
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+Returns the connection with the given ID.
+
+<APIPage document={"management-api"} operations={[{"path":"/v1/connections/{id}","method":"get"}]} />

apps/docs/content/docs/management-api/endpoints/connections/get-connections.mdx

@@ -1,18 +1,23 @@
 ---
-title: Get connection
+title: List connections
 full: true
 _openapi:
-  path: "/v1/connections/{id}"
+  path: "/v1/connections"
   method: GET
   toc: []
   structuredData:
     headings: []
     contents:
-      - content: Returns the connection with the given ID.
+      - content: >-
+          Returns all connections the actor has access to, with optional
+          database filter.
+url: /management-api/endpoints/connections/get-connections
+metaTitle: 'GET /v1/connections | List connections - Prisma Postgres'
+metaDescription: 'Management API: Returns all connections the actor has access to, with optional database filter. GET /v1/connections.'
 ---
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
 
-Returns the connection with the given ID.
+Returns all connections the actor has access to, with optional database filter.
 
-<APIPage document={"management-api"} operations={[{"path":"/v1/connections/{id}","method":"get"}]} />age document={"management-api"} operations={[{"path":"/v1/connections","method":"get"}]} />
+<APIPage document={"management-api"} operations={[{"path":"/v1/connections","method":"get"}]} />

apps/docs/content/docs/management-api/endpoints/connections/meta.json

@@ -0,0 +1,9 @@
+{
+  "title": "Connections",
+  "pages": [
+    "get-connections",
+    "get-connections-by-id",
+    "post-connections",
+    "delete-connections-by-id"
+  ]
+}

apps/docs/content/docs/management-api/endpoints/connections/post-connections.mdx

@@ -9,6 +9,9 @@ _openapi:
     headings: []
     contents:
       - content: Creates a new connection for the specified database.
+url: /management-api/endpoints/connections/post-connections
+metaTitle: 'POST /v1/connections | Create connection - Prisma Postgres'
+metaDescription: 'Management API: Creates a new connection for the specified database. POST /v1/connections.'
 ---
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

apps/docs/content/docs/management-api/endpoints/database-backups/get-databases-id-backups.mdx

@@ -9,6 +9,9 @@ _openapi:
     headings: []
     contents:
       - content: Returns backups for the specified database.
+url: /management-api/endpoints/database-backups/get-databases-id-backups
+metaTitle: 'GET /v1/databases/{databaseId}/backups | Get list of backups - Prisma Postgres'
+metaDescription: 'Management API: Returns backups for the specified database. GET /v1/databases/{databaseId}/backups.'
 ---
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

apps/docs/content/docs/management-api/endpoints/database-usage/get-databases-id-usage.mdx

@@ -9,6 +9,9 @@ _openapi:
     headings: []
     contents:
       - content: Returns usage metrics for the specified database.
+url: /management-api/endpoints/database-usage/get-databases-id-usage
+metaTitle: 'GET /v1/databases/{databaseId}/usage | Get database usage metrics - Prisma Postgres'
+metaDescription: 'Management API: Returns usage metrics for the specified database. GET /v1/databases/{databaseId}/usage.'
 ---
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

apps/docs/content/docs/management-api/endpoints/databases-connections/delete-connections.mdx

@@ -9,6 +9,9 @@ _openapi:
     headings: []
     contents:
       - content: Returns all connections for the given database.
+url: /management-api/endpoints/databases-connections/get-databases-id-connections
+metaTitle: 'GET /v1/databases/{databaseId}/connections | Get list of database connections - Prisma Postgres'
+metaDescription: 'Management API: Returns all connections for the given database. GET /v1/databases/{databaseId}/connections.'
 ---
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}