Mintlify User Manual Architecture & One-Way Sync Guide

┌─────────────────────────────────────────────────────────────┐
│ Application / Core Repo (Source of Truth)                   │
│ docs/ (User, Admin, Dev guides) + .agents/skills/           │
└───────────────────────────┬─────────────────────────────────┘
                            │ (python tools/build_mintlify_mdx.py)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Compiled Intermediate Tree: docs-source/ + docs.json        │
└───────────────────────────┬─────────────────────────────────┘
                            │ (python scripts/sync_docs.py)
                            ▼ (5 Strict Safety Guards A-E)
┌─────────────────────────────────────────────────────────────┐
│ Downstream Deployment: <OWNER>/<DOCS_REPO>                  │
│ Pure User Manual, Admin Manual, Developer Manual            │
└───────────────────────────┬─────────────────────────────────┘
                            │ (Mintlify Rebuild)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Public Portal: https://<SUBDOMAIN>.mintlify.site            │
└─────────────────────────────────────────────────────────────┘

## Prompt (copy from here)

You are working inside the GitHub repository <OWNER>/<APP_REPO> (the "app repo"). Your job is to:

1. Compile plain Markdown in docs/ (and optionally skills/) into a polished user-manual Mintlify site under docs-source/.
2. Set up a one-way, guarded sync pipeline that pushes docs-source/ into the downstream Mintlify repo <OWNER>/<DOCS_REPO> (the "docs repo"), deployed at https://<SUBDOMAIN>.mintlify.app.

The docs repo is never edited by humans, agents, or the Mintlify web editor. Sync is strictly one-way. Never force-push.

### Fixed values (fill in before running)

- App repo (source of truth, edit here): <OWNER>/<APP_REPO>
- Docs repo (Mintlify-connected, downstream, DO NOT EDIT DIRECTLY): <OWNER>/<DOCS_REPO>
- Mintlify subdomain: <SUBDOMAIN>.mintlify.app
- Branch on both repos: main
- Native Markdown source in app repo: docs/ (and optionally skills/)
- Compiled Mintlify MDX in app repo: docs-source/
- Target in docs repo: repo root
- Sync bot identity: name Docs Sync Bot, email bot@<SUBDOMAIN>.mintlify.app (or a project-owned mailbox)
- Product / project display name: <PRODUCT_NAME>
- One-line product value prop: <PRODUCT_VALUE_PROP>
- Primary audience: end users and integrators of <PRODUCT_NAME> (NOT internal maintainers)

### Content mandate: this site is a USER MANUAL

Everything the compiler emits and every hand-authored .mdx MUST read as an end-user manual for <PRODUCT_NAME>. Non-negotiable.

What this means in practice:
- Write for the person USING <PRODUCT_NAME>, not the person building or deploying it.
- Every page answers one of: "What is this?", "How do I do X?", "What does this setting/field mean?", "What went wrong and how do I fix it?".
- Lead with the reader's goal, then the steps, then the reference detail.
- Second person ("you"), active voice, imperative mood for instructions.
- Show working, copy-pasteable examples with expected output where useful.
- No em dashes or en dashes as punctuation. Use commas, colons, parentheses, or split the sentence.
- Never invent product facts. If a fact is not in docs/, skills/, or explicit source material, leave a TODO: marker in the body (never in frontmatter) and continue.

INCLUDE (user-manual scope):
- Getting started: signup, install, first successful action, first working example.
- Core concepts: product terminology, mental model, key workflows.
- How-to guides: step-by-step walkthroughs of real user tasks.
- Tutorials: end-to-end scenarios a new user can follow.
- Public API / SDK / CLI reference with request/response or command examples.
- Configuration users actually control through the product UI or public config files.
- Integrations, webhooks, extension points users set up themselves.
- Troubleshooting and FAQ written from a user perspective.
- Governance and legal pages users need (security policy, legal notice, license summary) when applicable.

EXCLUDE (do not document, even if present in the source repo):
- Internal microservice architecture, service boundaries, internal RPC.
- Database schemas, migrations, ORM internals.
- CI/CD pipelines, deployment scripts, infra-as-code, Kubernetes manifests (unless the product IS the infra).
- Internal admin tools, back-office dashboards.
- Business-logic implementation details, refactors, ADRs.
- Auth SYSTEM internals (OAuth provider wiring, session management, token storage). Document ONLY how the user obtains credentials.
- Server/runtime configuration users never touch.
- Dependency management, lockfiles, linter/build config.
- Contribution guides, code review process, internal onboarding.

### User manual site style

Frontmatter on every .mdx (required):
---
title: "<50-60 char SEO title, unique across the site>"
sidebarTitle: "<1-3 word Title Case label>"
description: "<130-155 chars, unique, adds info beyond the title>"
---

Rules:
- sidebarTitle is mandatory and short (1-3 words). Never put the full SEO title in the sidebar. Never repeat <PRODUCT_NAME> in the sidebar.
- First paragraph of the body MUST be plain prose naming the feature and stating what the page covers.
- Titles use Title Case. Sidebar labels use Title Case. Group and tab names use Title Case.

Information architecture (docs-source/docs.json):
- navigation MUST be an object with tabs (≤ 2-3 tabs) or groups. NEVER an array.
- Hard limits: at most 4-5 groups per tab, never a group with fewer than 2 pages. Merge thin groups.
- Group and tab names: Title Case, 1-3 words ("Get Started", "Guides", "Reference", "Troubleshooting").
- Page paths in navigation: extensionless, no leading slash (e.g. guides/first-integration).
- index is the landing page; quickstart is a working first-run page.

### Deliverables to generate

0. tools/build_mintlify_mdx.py:
   Translates docs/ and skills/ into docs-source/ (.mdx) and builds docs-source/docs.json.

1. Seed docs-source/:
   Run python tools/build_mintlify_mdx.py once to populate initial pages and docs.json.

2. scripts/sync_docs.py:
   Python 3.11 script with 5 strict safety guards (Guards A-E):
   - Guard A: Source directory and docs.json exist and parse as valid JSON.
   - Guard B: Minimum .mdx file floor (MIN_MDX_FILES, default 5).
   - Guard C: Navigation integrity matching all docs.json paths against .mdx files on disk.
   - Guard D: Diff preview with MAX_DELETIONS cap (default 10).
   - Guard E: Dry-run support via --dry-run or DRY_RUN=true.

3. .github/workflows/sync-docs.yml:
   Automated push trigger and workflow_dispatch with dry-run support.

4. docs-source/.mintignore:
   Ignore internal files: AGENTS.md, AGENTS-PROMPT.md, drafts/, *.draft.mdx.

5. Automated Tests:
   - tests/test_mintlify_mdx_builder.py: Frontmatter parsing, sidebarTitle synthesis, MDX transforms, docs.json assembly.
   - tests/test_sync_docs.py: Guards A through E.

## End of prompt