## 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