Germey · Oct 4, 2026 · Oct 4, 2026 · Oct 4, 2026 · Oct 4, 2026 · Oct 4, 2026
diff --git a/.github/workflows/sync.yml b/.github/workflows/sync.yml
@@ -1,11 +1,20 @@
 name: Sync Docs from PlatformBackend
 
 on:
+  push:
+    branches: [main]
+    paths:
+      - 'scripts/**'
+      - '.github/workflows/sync.yml'
   repository_dispatch:
-    types: [sync-docs, platform-contracts-updated]
+    types: [platform-contracts-updated]
   workflow_dispatch:
   schedule:
-    - cron: "0 6 * * *"
+    - cron: "37 * * * *"
+
+concurrency:
+  group: docs-publication-main
+  cancel-in-progress: false
 
 permissions:
   contents: write
@@ -26,62 +35,91 @@ jobs:
         uses: actions/checkout@v4
         with:
           path: Docs
+          ref: main
+          token: ${{ secrets.BOT_GITHUB_TOKEN }}
+
+      - name: Checkout current PlatformBackend source
+        uses: actions/checkout@v4
+        with:
+          repository: AceDataCloud/PlatformBackend
+          ref: main
+          fetch-depth: 0
+          path: PlatformBackend
           token: ${{ secrets.BOT_GITHUB_TOKEN }}
 
-      - name: Resolve PlatformBackend ref
+      - name: Verify source event and current contract
         id: backend
         env:
           EVENT_NAME: ${{ github.event_name }}
-          EVENT_TYPE: ${{ github.event.action }}
           SOURCE_SHA: ${{ github.event.client_payload.source_sha }}
         run: |
-          if [ "$EVENT_NAME" = "repository_dispatch" ] && [ "$EVENT_TYPE" = "platform-contracts-updated" ]; then
+          actual=$(git -C PlatformBackend rev-parse HEAD)
+          if [ "$EVENT_NAME" = "repository_dispatch" ]; then
             if ! printf '%s' "$SOURCE_SHA" | grep -Eq '^[0-9a-f]{40}$'; then
-              echo "::error::Direct contract events require a full PlatformBackend source_sha."
+              echo "::error::Contract events require a full source_sha."
               exit 1
             fi
-            echo "ref=$SOURCE_SHA" >> "$GITHUB_OUTPUT"
-            echo "direct=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "ref=main" >> "$GITHUB_OUTPUT"
-            echo "direct=false" >> "$GITHUB_OUTPUT"
+            # An old queued event is a reconciliation signal, never permission
+            # to replay an older snapshot over newer published content.
+            git -C PlatformBackend merge-base --is-ancestor "$SOURCE_SHA" "$actual"
           fi
-
-      - name: Checkout PlatformBackend
-        uses: actions/checkout@v4
-        with:
-          repository: AceDataCloud/PlatformBackend
-          ref: ${{ steps.backend.outputs.ref }}
-          path: PlatformBackend
-          token: ${{ secrets.BOT_GITHUB_TOKEN }}
-
-      - name: Verify PlatformBackend source
-        if: steps.backend.outputs.direct == 'true'
-        run: |
-          actual=$(git -C PlatformBackend rev-parse HEAD)
-          test "$actual" = "${{ steps.backend.outputs.ref }}"
+          echo "sha=$actual" >> "$GITHUB_OUTPUT"
           bundle=$(mktemp -d)
           python PlatformBackend/scripts/ecosystem_contracts.py \
-            --backend-dir PlatformBackend compile \
-            --output-dir "$bundle" \
-            --source-sha "$actual"
+            --backend-dir PlatformBackend compile --output-dir "$bundle" --source-sha "$actual"
           python PlatformBackend/scripts/ecosystem_contracts.py verify \
-            --bundle-dir "$bundle" \
-            --source-sha "$actual"
+            --bundle-dir "$bundle" --source-sha "$actual"
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: "3.12"
 
-      - name: Run sync script
+      - name: Reconcile public documents
+        id: publication
         working-directory: Docs
         env:
           PUBLIC_EXAMPLE_DENYLIST: ${{ secrets.PUBLIC_EXAMPLE_DENYLIST }}
         run: |
+          set +e
           python -u scripts/sync_from_platformbackend.py \
             --backend-dir ../PlatformBackend \
-            --output-dir .
+            --output-dir . \
+            --report "$RUNNER_TEMP/docs-sync-report.json"
+          result=$?
+          set -e
+          if [ "$result" -ne 0 ] && [ "$result" -ne 2 ]; then
+            exit "$result"
+          fi
+          echo "incomplete=$([ "$result" -eq 2 ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
+          python - "$RUNNER_TEMP/docs-sync-report.json" >> "$GITHUB_STEP_SUMMARY" <<'PY'
+          import json, sys
+          report = json.load(open(sys.argv[1]))
+          print(f"Current document versions: {report['ready']}/{report['total']}")
+          for item in report['pending'][:100]:
+              print(f"- {item['language']}/{item['source_key']}: {item['status']}")
+          PY
+
+      - name: Preserve publication completeness report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-sync-report
+          path: ${{ runner.temp }}/docs-sync-report.json
+          if-no-files-found: warn
+          retention-days: 14
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: Docs/package-lock.json
+
+      - name: Validate MDX and local links before pushing
+        working-directory: Docs
+        run: |
+          npm ci --ignore-scripts
+          node scripts/validate_mdx.mjs .
 
       - name: Check for changes
         id: changes
@@ -95,9 +133,8 @@ jobs:
           fi
 
           echo "changed=true" >> "$GITHUB_OUTPUT"
-          changed_files=$(git diff --cached --name-only | head -300)
-          echo "Files changed:"
-          echo "$changed_files"
+          changed_files=$(git diff --cached --name-only)
+          git diff --cached --stat
 
           changed_services=$(echo "$changed_files" \
             | grep -oP '^(?:openapi/|[^/]+/guides/|[^/]+/mcp/)\K[^/.]+' \
@@ -113,6 +150,18 @@ jobs:
         run: |
           git config user.name "Ace Data Cloud Dev"
           git config user.email "dev@acedata.cloud"
-          git commit -m "docs: sync from PlatformBackend [automated]"
+          latest=$(git -C ../PlatformBackend ls-remote origin refs/heads/main | cut -f1)
+          test "$latest" = "${{ steps.backend.outputs.sha }}" || {
+            echo "::error::PlatformBackend advanced during publication; retry from current main."
+            exit 1
+          }
+          git commit -m "docs: sync from PlatformBackend [automated]" \
+            -m "Source: ${{ steps.backend.outputs.sha }}"
           git push
           echo "commit_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: Require complete publication
+        if: steps.publication.outputs.incomplete == 'true'
+        run: |
+          echo "::error::Publication is incomplete. Current pages were refreshed; retained or missing translations are listed in docs-sync-report."
+          exit 1
diff --git a/.github/workflows/validate-sync.yml b/.github/workflows/validate-sync.yml
@@ -21,3 +21,9 @@ jobs:
         run: |
           python -m compileall -q scripts tests
           python -m unittest
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: npm
+      - run: npm ci --ignore-scripts
+      - run: node --test tests/mdx-validation.test.mjs
diff --git a/README.md b/README.md
@@ -1,64 +1,90 @@
-# Mintlify Starter Kit
+# AceDataCloud Docs
+
+Mintlify documentation for AceDataCloud. Preview with `mint dev`; check public
+links with `mint broken-links`. Navigation and site settings live in `docs.json`.
+
+## Sources and ownership
+
+- PlatformBackend owns Markdown source files and OpenAPI definitions. Edit the
+  source, not generated Docs pages.
+- Reuse the existing `/api/v1/documents/?lang=en` list, including normal
+  pagination. Its additive `content_source` metadata identifies the source file,
+  source SHA-256, exact-language readiness and content hash. Independent Text
+  guides and MCP pages are read directly rather than inferred from API siblings.
+  No new endpoint, response envelope or export mode is required.
+- Every configured locale's `guides/` and `mcp/` directories are generated.
+  Existing Greek, Finnish and Serbian directories are also reconciled because
+  their unlisted URLs remain accessible, without adding them to the language menu.
+  `mcp/overview.mdx` is explicitly hand-authored and preserved. Public source
+  records without an old service route use `guides/platform/<source-key>.mdx`.
+  Existing routes and the exact Coding route map are preserved.
+- Per-locale API reference indexes are generated from the published specs.
+  Source-file links are resolved to the correct locale route; platform-relative
+  document links are made absolute instead of being interpreted as Docs routes.
+- `openapi/` contains specs for APIs with public platform document records;
+  private markers and temporary publication holds are still enforced.
+- Generated navigation is reconciled atomically with pages: Coding translations,
+  additional public guides, MCP pages, and OpenAPI groups become discoverable;
+  retired generated links are removed. Existing editorial groups are preserved.
+- Quickstarts, concepts, pricing, FAQ, and other editorial pages are maintained
+  here. They are not automatically rewritten from API changes.
+
+## Synchronization contract
+
+`Sync Ecosystem Contracts` is the only source-change trigger. The Docs workflow
+serializes all writers, checks out current `main` after acquiring the queue, and
+validates that an event SHA belongs to the current backend history. Old events
+cannot republish old source snapshots. A final source check rejects a backend
+revision that advanced during generation; normal Git push rejects concurrent
+editorial changes without overwriting them.
+
+Hourly reconciliation picks up asynchronous source deployment and translation
+completion even when no new Git event occurs. Before switching this consumer on,
+deploy the additive metadata on the existing document list. Missing metadata or
+malformed/incomplete pages fail instead of being treated as a successful sync.
+
+For every generated page, the database source hash must match the checked-out
+Markdown and the target translation must be current. Catalog identity must also
+remain consistent across locale reads. The normal list keeps its display fallback; the Docs consumer checks metadata
+and never counts that fallback as a current translation.
+When a translation is pending, an existing page is retained for availability but
+is explicitly reported as incomplete; a missing page is not fabricated. Ready
+pages and public withdrawals can still publish. Exit status **2** means partial
+publication and fails the workflow's final completeness gate. Other nonzero
+statuses abort publication; **0** means every expected page is current.
+
+The workflow retains `docs-sync-report` for 14 days and puts pending page keys,
+locales, and reasons in the job summary. Generated output is staged and validated
+before an atomic publish; interruption recovery includes navigation and all MCP
+locales. A separate MDX and local-link gate checks every site page before Git
+push, including editorial entry points. Plain Markdown braces are escaped outside code rather than interpreted as
+JavaScript expressions. Customer example sanitization remains mandatory.
+
+## Verification
 
-Use the starter kit to get your docs deployed and ready to customize.
-
-Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with
-
-- Guide pages
-- Navigation
-- Customizations
-- API reference pages
-- Use of popular components
-
-**[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)**
-
-## AI-assisted writing
-
-Set up your AI coding tool to work with Mintlify:
-
-```bash
-npx skills add https://mintlify.com/docs
-```
-
-This command installs Mintlify's documentation skill for your configured AI tools like Claude Code, Cursor, Windsurf, and others. The skill includes component reference, writing standards, and workflow guidance.
-
-See the [AI tools guides](/ai-tools) for tool-specific setup.
-
-## Development
-
-Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command:
-
-```
-npm i -g mint
-```
-
-Run the following command at the root of your documentation, where your `docs.json` is located:
-
-```
-mint dev
+```sh
+python -m compileall -q scripts tests
+python -m unittest
+npm ci --ignore-scripts
+node --test tests/mdx-validation.test.mjs
+node scripts/validate_mdx.mjs /path/to/generated-preview
+mint broken-links
 ```
 
-View your local preview at `http://localhost:3000`.
-
-## Publishing changes
-
-Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.
-
-## Need help?
-
-### Troubleshooting
-
-- If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI.
-- If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`.
-
-### Resources
-- [Mintlify documentation](https://mintlify.com/docs)
-
-## Automated tests
+For read-only reconciliation, run:
 
 ```sh
-python3 -m unittest
+python scripts/sync_from_platformbackend.py --backend-dir ../PlatformBackend \
+  --output-dir . --dry-run --report /tmp/docs-sync-report.json
 ```
 
-CI discovers tests by filename instead of maintaining a per-file list. Add Python
-tests as `test_*.py` in `tests/`; no workflow change is needed.
+`--preview-dir /tmp/docs-preview` preserves dry-run output in a new directory for
+review and link checking. Set `PUBLIC_EXAMPLE_DENYLIST` and `--require-denylist` to
+include private-value checks in a dry run; without it the report explicitly marks
+that check unverified. Actual publication always requires the configured denylist.
+
+`--catalog-dir /path/to/snapshots` loads files named `zh-cn.json`, `en.json`, etc.
+containing complete responses from the same document list for reproducible,
+offline verification. Reports
+belong outside the generated output tree. No sync command writes the backend DB
+or generates translations.
diff --git a/ar/introduction.mdx b/ar/introduction.mdx
@@ -8,16 +8,16 @@ description: "يوفر Ace Data Cloud منصة API موحدة للذكاء ال
 Ace Data Cloud هو منصة API موحدة للذكاء الاصطناعي، تتيح الوصول إلى خدمات الذكاء الاصطناعي الرائدة عالميًا من خلال مفتاح API واحد وواجهة موحدة.
 
 <CardGroup cols={2}>
-  <Card title="دردشة الذكاء الاصطناعي" icon="comments" href="/guides/claude/claude_chat_completions">
+  <Card title="دردشة الذكاء الاصطناعي" icon="comments" href="/ar/guides/claude/claude_chat_completions">
     الوصول إلى نماذج مثل Claude و GPT و Gemini و DeepSeek و Grok و Kimi وغيرها عبر واجهة متوافقة مع OpenAI.
   </Card>
-  <Card title="صور الذكاء الاصطناعي" icon="image" href="/guides/midjourney/midjourney_imagine">
-    توليد الصور باستخدام Midjourney و Flux و DALL·E و Seedream وغيرها.
+  <Card title="صور الذكاء الاصطناعي" icon="image" href="/ar/guides/flux/flux_images">
+    توليد الصور باستخدام و Flux و DALL·E و Seedream وغيرها.
   </Card>
-  <Card title="فيديوهات الذكاء الاصطناعي" icon="video" href="/guides/sora/sora_videos">
-    توليد الفيديوهات باستخدام Sora و Veo و Luma و Kling و Hailuo و Seedance وغيرها.
+  <Card title="فيديوهات الذكاء الاصطناعي" icon="video" href="/ar/guides/veo/veo_videos">
+    توليد الفيديوهات باستخدام و Veo و Luma و Kling و Hailuo و Seedance وغيرها.
   </Card>
-  <Card title="صوتيات الذكاء الاصطناعي" icon="music" href="/guides/suno/suno_audios">
+  <Card title="صوتيات الذكاء الاصطناعي" icon="music" href="/ar/guides/suno/suno_audios">
     توليد الموسيقى والصوتيات باستخدام Suno و Fish Audio و Producer وغيرها.
   </Card>
 </CardGroup>
@@ -36,10 +36,10 @@ Ace Data Cloud هو منصة API موحدة للذكاء الاصطناعي، ت
   <Card title="الحصول على مفتاح API" icon="key" href="https://platform.acedata.cloud">
     التسجيل والحصول على رمز API
   </Card>
-  <Card title="مرجع API" icon="code" href="/authentication">
+  <Card title="مرجع API" icon="code" href="/ar/authentication">
     وثائق API تفاعلية
   </Card>
-  <Card title="خوادم MCP" icon="plug" href="/mcp/overview">
+  <Card title="خوادم MCP" icon="plug" href="/ar/mcp/overview">
     ربط مساعد الذكاء الاصطناعي بواجهاتنا البرمجية
   </Card>
 </CardGroup>