fix: sync docs with Dashboard and OpenAPI changes

apps/content/scripts/generate-openapi-docs.mjs

@@ -83,6 +83,59 @@ function pageSlug(entry) {
   return slug;
 }
 
+function plainText(value) {
+  return value
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function completeSentence(value) {
+  return /[.!?]$/.test(value) ? value : `${value}.`;
+}
+
+function normalizeFrontmatter(file, document) {
+  const slug = file.path.replace(/\.mdx$/, '');
+  const page = Object.entries(PAGES).find(([, output]) => output === slug);
+  if (!page) {
+    throw new Error(`No operation mapped for generated page "${file.path}".`);
+  }
+
+  const [operationKey] = page;
+  const separator = operationKey.indexOf(' ');
+  const method = operationKey.slice(0, separator);
+  const route = operationKey.slice(separator + 1);
+  const operation = document.paths?.[route]?.[method];
+  if (!operation || typeof operation.summary !== 'string') {
+    throw new Error(`No OpenAPI operation found for "${operationKey}".`);
+  }
+
+  const frontmatterEnd = file.content.indexOf('\n---', 4);
+  const body = file.content.slice(frontmatterEnd + 4);
+  const generatedFrontmatter = file.content.slice(4, frontmatterEnd);
+  const openapiStart = generatedFrontmatter.indexOf('_openapi:');
+  if (frontmatterEnd === -1 || openapiStart === -1) {
+    throw new Error(`Could not parse generated frontmatter in "${file.path}".`);
+  }
+
+  const summary = plainText(operation.summary);
+  const overview = completeSentence(
+    plainText(operation.description ?? operation.summary)
+  );
+  const description = `${overview} API reference for ${summary}.`;
+  const openapiMetadata = generatedFrontmatter.slice(openapiStart).trimEnd();
+
+  file.content = `---
+
+title: ${JSON.stringify(summary)}
+description: ${JSON.stringify(description)}
+method: ${method.toUpperCase()}
+full: true
+${openapiMetadata}
+---${body}`;
+}
+
 // Marker Fumadocs writes into every generated MDX page.
 const GENERATED_MARKER = 'This file was generated by Fumadocs';
 
@@ -114,6 +167,13 @@ async function main() {
     per: 'operation',
     groupBy: (entry) => path.dirname(pageSlug(entry)),
     name: (entry) => path.basename(pageSlug(entry)),
+    beforeWrite(files) {
+      const document = this.documents['gt-api']?.dereferenced;
+      if (!document) {
+        throw new Error('Could not load the gt-api OpenAPI document.');
+      }
+      for (const file of files) normalizeFrontmatter(file, document);
+    },
   });
 
   console.log(`\nGenerated operation pages into ${OUTPUT_DIR}`);

docs/en-US/platform/dashboard/get-started.mdx

@@ -26,12 +26,12 @@ The Dashboard is the web app for reviewing translations, guiding the AI with con
 
 ## Configuration [#configuration]
 
-- **Create API keys:** use Project keys for a single Project and Organization keys for broader automation. See [API keys](/docs/platform/dashboard/reference/api-keys).
-- **Manage team access:** invite members and manage Organization settings from the Organization scope. See [Organization settings](/docs/platform/dashboard/reference/organization-settings) and [Roles and permissions](/docs/platform/dashboard/reference/roles-and-permissions).
+- **Create API keys:** use **Project > API Keys** for a single Project and **Organization > Developer > API Keys** for broader automation. See [API keys](/docs/platform/dashboard/reference/api-keys).
+- **Manage team access:** invite members from **Organization > Settings > Members**. See [Organization settings](/docs/platform/dashboard/reference/organization-settings) and [Roles and permissions](/docs/platform/dashboard/reference/roles-and-permissions).
 - **Connect external services:** manage Organization-level authorizations under **Organization > Connections**. Connect providers or link resources under **Project > Integrations**. See [Organization settings](/docs/platform/dashboard/reference/organization-settings).
 - **Configure projects:** update Project name, source locale, CDN delivery, AI Context, and Project ID from Project settings. See [Project settings](/docs/platform/dashboard/reference/project-settings).
 - **Send events to your backend:** use webhooks to receive signed translation events. See [Webhooks](/docs/platform/dashboard/reference/webhooks).
-- **Manage billing:** understand plans, usage-based pricing, buy prepaid credits, and set up auto-reload. See [Managing billing](/docs/platform/dashboard/guides/managing-billing).
+- **Manage billing:** use **Organization > Settings > Billing** to review plans, buy prepaid credits, and set up auto-reload. See [Managing billing](/docs/platform/dashboard/guides/managing-billing).
 
 
 
@@ -40,7 +40,7 @@ The Dashboard is the web app for reviewing translations, guiding the AI with con
 The Dashboard is organized into nested scopes: **Enterprise**, **Organization**, and **Project**. Most teams use Organizations and Projects. Enterprise is a layer for larger teams managing multiple Organizations.
 
 - **Enterprise** contains Organizations, members, billing, and security settings across multiple Organizations.
-- **Organization** contains Projects, team members, shared context, API keys, webhooks, usage, Connections for authorized external services, and **Locadex > Automations** and **Locadex > Integrations**.
+- **Organization** contains Projects, shared context, usage, Connections for authorized external services, and **Locadex > Automations** and **Locadex > Integrations**. **Developer** contains API keys and webhooks. **Settings** contains members, billing, plans, and Organization settings.
 - **Project** contains translations, Project context, API keys, settings, **Automations**, and **Integrations > Connected** and **Integrations > Catalog**.
 
 Use the switcher in the header to move between scopes. The sidebar changes based on the selected scope.
@@ -53,7 +53,7 @@ If you do not see a page, check that you are in the right Organization or Projec
 
 **What is General Translation?** General Translation (GT) is the full-stack localization platform to translate your app, docs, and content into any language. GT combines open-source i18n libraries, an AI-native translation platform, and the purpose-built localization agent Locadex. We build a complete understanding of your codebase and product context by connecting your code, content, and translations. So you can bring the best translations of your product to the whole world.
 
-**How do I get an API key?** Create a Project, then open **API Keys** at the Project or Organization level. Project keys are used for one Project. Organization keys support custom permissions for broader automation. See [API keys](/docs/platform/dashboard/reference/api-keys).
+**How do I get an API key?** Create a Project, then open **Project > API Keys** or **Organization > Developer > API Keys**. Project keys are used for one Project. Organization keys support custom permissions for broader automation. See [API keys](/docs/platform/dashboard/reference/api-keys).
 
 **Can I edit translations after they are generated?** Yes. Use the **Translations** page to review and edit generated translations. You can also use annotations to label entries, add notes, and discuss translations with your team. See [Reviewing and editing translations](/docs/platform/dashboard/guides/reviewing-translations).
 

docs/en-US/platform/dashboard/guides/managing-billing.mdx

@@ -11,7 +11,7 @@ related:
 
 ---
 
-Usage records and spend estimates live on **Usage**. Plans, credit balances, reload settings, and invoices live on **Billing** for your Organization.
+Usage records and spend estimates live on **Organization > Usage**. Plans, credit balances, reload settings, and invoices live on **Organization > Settings > Billing**.
 
 ## Plans [#plans]
 
@@ -46,15 +46,15 @@ See the [usage rates](https://generaltranslation.com/pricing/usage) page for cur
 
 ## Invoice history [#invoices]
 
-When invoices are available, the **Billing** page shows each invoice's date, description, status, and amount. Choose **Breakdown** to review line items and quantities, or **View** to open the hosted invoice when one is available.
+When invoices are available, **Organization > Settings > Billing** shows each invoice's date, description, status, and amount. Choose **Breakdown** to review line items and quantities, or **View** to open the hosted invoice when one is available.
 
 <Callout type="info">
   **Enterprise-managed Organizations:** Cost and invoice data are managed at Enterprise scope. Open **Enterprise > Billing** to review them.
 </Callout>
 
 ## How the credit balance works [#credits]
 
-Your **credit balance** is a prepaid wallet for platform usage, shown on the **Billing** page and denominated in dollars ($1 = 1M credits). The balance is split into buckets:
+Your **credit balance** is a prepaid wallet for platform usage, shown on **Organization > Settings > Billing** and denominated in dollars ($1 = 1M credits). The balance is split into buckets:
 
 - **Purchased** — credits you purchased.
 - **Granted** — any one-time signup credit.
@@ -64,11 +64,11 @@ Every billable workflow, including translations and Ask AI responses, deducts it
 
 ### Buying credits [#buying-credits]
 
-Choose **Buy Credits** on the Billing page and enter an **Amount** to charge to your default payment method. The dialog shows the allowed range for your plan (the Starter minimum is $10).
+Choose **Buy Credits** on **Organization > Settings > Billing** and enter an **Amount** to charge to your default payment method. The dialog shows the allowed range for your plan (the Starter minimum is $10).
 
 ### Auto-reload [#auto-reload]
 
-Auto-reload keeps your balance topped up automatically when your balance falls below a certain threshold. It is off by default. To turn on, choose **Auto Reload** on the Billing page, turn on **Enable Auto Reload**, and set:
+Auto-reload keeps your balance topped up automatically when your balance falls below a certain threshold. It is off by default. To turn on, choose **Auto Reload** on **Organization > Settings > Billing**, turn on **Enable Auto Reload**, and set:
 
 - **Minimum Balance** — when your balance goes below this, a reload is triggered.
 - **Reload to** — the target balance to bring your credits back up to.
@@ -96,7 +96,7 @@ What happens at $0 depends on auto-reload:
 
 ### Upgrade to Starter [#to-starter]
 
-Because Starter has no monthly fee, upgrading is simply adding a payment method. On the **Billing** page, choose **Manage Billing** and add a card and billing address.
+Because Starter has no monthly fee, upgrading is simply adding a payment method. On **Organization > Settings > Billing**, choose **Manage Billing** and add a card and billing address.
 
 Upgrading removes your rate limit and also unlocks features including: Locadex, team invites, auto-reload, the Translation Editor, version branching, and unlimited Projects.
 

docs/en-US/platform/dashboard/reference/api-keys.mdx

@@ -18,7 +18,7 @@ Organization keys and Project keys have different creation flows. Project keys a
 
 ## Create Organization keys [#create-organization-keys]
 
-Create Organization keys from **Organization > API Keys**. Organization keys use the `gtx-org-` prefix and can be configured with a custom permission set.
+Create Organization keys from **Organization > Developer > API Keys**. Organization keys use the `gtx-org-` prefix and can be configured with a custom permission set.
 
 Permissions are configured per resource. `Write` includes `Read`.
 

docs/en-US/platform/dashboard/reference/organization-settings.mdx

@@ -12,15 +12,15 @@ For larger teams, **Enterprises** provide an optional layer above Organizations.
 
 ## Inviting new members [#inviting-new-members]
 
-Organization admins can invite new members by email.
+Organization admins can invite new members by email from **Organization > Settings > Members**.
 
 Invitees receive a link to join the Organization. The link expires after 7 days.
 
 For Enterprise accounts, members added at the Enterprise level can access all managed Organizations.
 
 ## Member roles [#member-roles]
 
-The Members page shows everyone with access to your Organization. Roles control what members can see and do.
+The **Organization > Settings > Members** page shows everyone with access to your Organization. Roles control what members can see and do.
 
 - **Admin** has full access to all Organization settings, Projects, members, billing, and translations. Admins can delete the Organization.
 - **Developer** has technical access to Projects, including API keys, GitHub integration, Locadex, and usage data.
@@ -39,7 +39,7 @@ Open **Organization > Usage** to switch between **Tokens** and **Agent**. If you
 
 The page also lists recent translation records with input and output token counts and recent Agent workflow records with trace IDs. When the Organization has multiple Projects, the Project selector filters token metrics and translation records; Agent and Cost totals remain Organization-wide.
 
-Manage an Organization-owned plan, credit balance, and invoices from **Organization > Billing**. Choose **Breakdown** on an invoice to review its line items and quantities. Enterprise-managed Organizations use **Enterprise > Billing** instead. [Contact us](https://generaltranslation.com/en-US/enterprise/contact) if you're interested in Enterprise plans for larger teams with complex localization needs.
+Manage an Organization-owned plan, credit balance, and invoices from **Organization > Settings > Billing**. Choose **Breakdown** on an invoice to review its line items and quantities. Enterprise-managed Organizations use **Enterprise > Billing** instead. [Contact us](https://generaltranslation.com/en-US/enterprise/contact) if you're interested in Enterprise plans for larger teams with complex localization needs.
 
 ## Connections [#connections]
 

docs/en-US/platform/dashboard/reference/webhooks.mdx

@@ -9,7 +9,7 @@ Webhooks send translation events to your backend as signed HTTP POST requests. U
 
 ## Create a webhook [#create-webhook]
 
-1. Go to **Organization > Webhooks > Endpoints**.
+1. Go to **Organization > Developer > Webhooks**.
 2. Click **Add endpoint**.
 3. Enter the endpoint URL where you want to receive events. The URL must use HTTPS.
 4. Select the event types you want to subscribe to.
@@ -115,7 +115,7 @@ Webhooks use **at-least-once delivery**.
 
 If your endpoint does not return a `2xx` response within 10 seconds, the delivery is retried with exponential backoff for up to **10 attempts**.
 
-You can manually retry a failed delivery from **Organization > Webhooks > Events** in the Dashboard.
+You can manually retry a failed delivery from **Organization > Developer > Webhook Events** in the Dashboard.
 
 Expand a failed attempt to inspect its **Error** field. For a non-`2xx` response, the error includes the HTTP status and may include a sanitized excerpt of the endpoint's response body. General Translation reads up to 4,096 bytes from the response and stores at most 500 characters for diagnostics.
 
@@ -139,14 +139,14 @@ app.post("/webhooks/gt", (req, res) => {
 
 ## Manage endpoints [#manage-endpoints]
 
-From **Organization > Webhooks > Endpoints**, you can:
+From **Organization > Developer > Webhooks**, you can:
 
 - Enable or disable an endpoint without deleting it
 - Update the subscribed event types
 - Reveal the signing secret
 - Delete the endpoint
 
-From **Organization > Webhooks > Events**, you can view delivery history, inspect individual attempts, and retry failed deliveries.
+From **Organization > Developer > Webhook Events**, you can view delivery history, inspect individual attempts, and retry failed deliveries.
 
 ## Best practices [#best-practices]
 

docs/en-US/platform/openapi/openapi.yaml

@@ -233,6 +233,10 @@ paths:
     get:
       tags: [Context]
       summary: Check if context generation is needed
+      description: >
+        Check whether the Project needs translation context generated. This
+        deprecated endpoint is retained for backward compatibility and is no
+        longer called by current clients.
       deprecated: true
       operationId: shouldGenerateContext
       parameters:
@@ -304,6 +308,10 @@ paths:
     get:
       tags: [Context]
       summary: Get context generation job status
+      description: >
+        Track a context generation job. This deprecated endpoint is retained
+        for backward compatibility; new integrations should use
+        `POST /v2/project/jobs/info`.
       deprecated: true
       operationId: getContextStatus
       parameters:
@@ -567,6 +575,8 @@ paths:
     post:
       tags: [Branches]
       summary: Get branch information
+      description: >
+        Return the Project's default branch and any branches requested by name.
       operationId: getBranchInfo
       parameters:
         - $ref: '#/components/parameters/GtApiVersion'
@@ -910,6 +920,9 @@ paths:
     get:
       tags: [Project]
       summary: Get project information
+      description: >
+        Read the authenticated Project's name, Organization ID, locale settings,
+        and auto-approval setting.
       operationId: getProjectInfo
       parameters:
         - $ref: '#/components/parameters/GtApiVersion'
@@ -980,6 +993,9 @@ paths:
     post:
       tags: [Jobs]
       summary: Get translation job status
+      description: >
+        Return normalized status information for one or more queued translation
+        or context generation jobs.
       operationId: getJobsInfo
       parameters:
         - $ref: '#/components/parameters/GtApiVersion'
@@ -1115,6 +1131,9 @@ paths:
     get:
       tags: [Files]
       summary: Get translation status for a file
+      description: >
+        Return translation progress and availability by locale for one source
+        file, along with its source metadata.
       operationId: getTranslationStatus
       parameters:
         - $ref: '#/components/parameters/GtApiVersion'
@@ -1428,7 +1447,7 @@ components:
         fileName: { type: string }
         fileFormat:
           type: string
-          description: File format, e.g. json, yaml, xml.
+          description: File format identifier, for example JSON, MDX, or LOTTIE.
         dataFormat:
           type: string
           description: Data format, e.g. STRING, JSX, ICU.

docs/en-US/platform/openapi/reference/context/check-freshness.mdx

@@ -1,13 +1,20 @@
 ---
-title: Check if context generation is needed
+
+title: "Check if context generation is needed"
+description: "Check whether the Project needs translation context generated. This deprecated endpoint is retained for backward compatibility and is no longer called by current clients. API reference for Check if context generation is needed."
+method: GET
 full: true
 _openapi:
   method: GET
   route: /v2/project/setup/should-generate
   toc: []
   structuredData:
     headings: []
-    contents: []
+    contents:
+      - content: >
+          Check whether the Project needs translation context generated. This
+          deprecated endpoint is retained for backward compatibility and is no
+          longer called by current clients.
 ---
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

docs/en-US/platform/openapi/reference/context/context-status.mdx

@@ -1,13 +1,20 @@
 ---
-title: Get context generation job status
+
+title: "Get context generation job status"
+description: "Track a context generation job. This deprecated endpoint is retained for backward compatibility; new integrations should use POST /v2/project/jobs/info. API reference for Get context generation job status."
+method: GET
 full: true
 _openapi:
   method: GET
   route: /v2/project/setup/status/{jobId}
   toc: []
   structuredData:
     headings: []
-    contents: []
+    contents:
+      - content: >
+          Track a context generation job. This deprecated endpoint is retained
+          for backward compatibility; new integrations should use `POST
+          /v2/project/jobs/info`.
 ---
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

docs/en-US/platform/openapi/reference/context/generate-context.mdx

@@ -1,6 +1,8 @@
 ---
-title: Generate translation context
-description: Generate glossaries and translation instructions for the project.
+
+title: "Generate translation context"
+description: "Generate glossaries and translation instructions for the project. API reference for Generate translation context."
+method: POST
 full: true
 _openapi:
   method: POST