Skip to main content

​
AGENTS.md

This file defines mandatory authoring rules for AI agents (Codex, Claude, and similar assistants) that contribute to this repository.

​
Scope

These instructions apply to the full repository unless a deeper AGENTS.md overrides specific rules.

​
Primary Goal

Write documentation that helps real end users complete tasks confidently. Every page should feel like it was written by a strong technical writer, not generated text.

​
Non-Negotiable Writing Rules

  1. Write from the end-user point of view.
    • Explain what users need to do, why it matters, and what result they should expect.
    • Prefer practical guidance over internal implementation details.
  2. Be clear, thorough, and explicit.
    • Use short paragraphs, clear headings, and step-by-step instructions.
    • Define terms before using them in advanced explanations.
    • Include prerequisites, expected inputs, outputs, and common mistakes.
  3. Make writing human and natural.
    • Do not use em dash or en dash punctuation in prose.
    • Avoid common LLM filler terms such as delve, leverage, seamless, robust, unlock, journey, and in today’s landscape.
    • Vary sentence structure and use precise wording.
  4. Keep tone consistent.
    • Professional, helpful, and direct.
    • Confident but not marketing-heavy.
    • Use active voice where possible.

​
SEO + GEO Requirements (Required for Every Page)

Every new or updated documentation page must be optimized for both classic search engines (SEO) and generative engines or AI answer systems (GEO).

​
SEO baseline

  • Include a specific, intent-focused title.
  • Write a concise, descriptive page description.
  • Place the primary key phrase in:
    • title
    • description
    • first 120 words
    • at least one H2 heading
  • Use descriptive headings that match likely search intent.
  • Add internal links to relevant docs.
  • Add external links only when they improve trust or clarity.
  • Use meaningful alt text for images.
  • Keep slugs, filenames, and headings readable and specific.

​
GEO baseline

  • Start with a direct answer or definition in the opening section.
  • Include a “Who is this for” or “When to use this” section when relevant.
  • Use structured lists, comparison tables, and concise summaries that are easy to quote.
  • State assumptions, limits, and prerequisites clearly.
  • Include a brief recap section for long pages.
  • Ensure factual statements are precise and consistent with product behavior.

​
Structure Requirements for Task-Oriented Docs

For endpoint pages, follow API_ENDPOINT_TEMPLATE.md. Every state-changing operation must identify its side effects, retry safety, prerequisites, verification step, operation-specific errors, and related lifecycle operations. When writing setup, configuration, or workflow pages, prefer this order:
  1. What this page helps you do
  2. Before you begin
  3. Step-by-step instructions
  4. Verify the result
  5. Troubleshooting
  6. Related pages

​
Visual and Theme Consistency

  • Follow the existing Mintlify and DialNexa design language defined in docs.json.
  • Do not introduce ad hoc color values that conflict with the current theme.
  • Reuse existing components and formatting patterns used in nearby docs.
  • Keep navigation entries in docs.json aligned with added or moved pages.
  • Use extensionless paths in docs.json.
  • Validate that internal links resolve correctly.
  • Changelog entries must link to the exact section that documents the change, using heading anchors instead of broad page links when a section exists.

​
Integration Catalog Limits

  • Keep exactly 50 individual provider guide pages, defined by INDIA_GUIDE_SLUGS in scripts/generate_integrations.py.
  • Keep the complete supported-provider list in integrations/directory, but link only providers that have one of the 50 retained guides.
  • Do not regenerate individual MDX pages or logo files for providers outside the retained set.
  • Redirect directory-only provider URLs to the matching alphabetical directory page.
  • When replacing a retained provider, update the generator list, navigation, directory output, redirects, inbound links, and validation coverage in the same change.

​
Source Snapshot Workflow

  • Before updating docs from dashboard or speech code, read DOCS_SOURCE_SNAPSHOT.md.
  • Pull latest master in dashboard-be, dashboard-fe, and speech-ai.
  • Diff each source repository from the commit recorded in DOCS_SOURCE_SNAPSHOT.md.
  • Read the changed files first, plus directly referenced helpers only when needed.
  • Treat source diffs as bidirectional. Add docs for new behavior, and remove or revise docs for deleted, renamed, hidden, deprecated, or unsupported behavior.
  • Stale docs are bugs. Delete or update obsolete MDX prose, OpenAPI operations, docs.json navigation entries, screenshots, image references, examples, and changelog links when the current codebase no longer supports them.
  • For API work, compare added and removed routes, DTOs, controller methods, guards, and routes.config entries against api-reference/openapi.json, API MDX pages, navigation, and prose references.
  • Update DOCS_SOURCE_SNAPSHOT.md with new commit IDs after the docs are validated.

​
Quality Gate Before Submitting

Run these checks when possible:
If a command cannot run in the local environment, explain why in the PR notes.

​
MCP Tools Pages Are a Special Case

Individual mcp-tools/<group>/<tool>.mdx pages and resource-group overviews are generated by scripts/build-mcp-tools-from-export.py from the real tool descriptions registered in dashboard-be/src/modules/mcp/tools/*.tools.ts. The hand-authored pages are mcp-tools/overview.mdx, mcp-tools/quickstart.mdx, and mcp-tools/errors.mdx. Content inside {/* mcp-sync:start:<tool> */} ... {/* mcp-sync:end:<tool> */} blocks must never be hand-edited: it is copied verbatim (including punctuation, such as em dashes) from the source so the docs always say exactly what the MCP server sends to a connected agent. To change a tool’s documented behavior, change its description in the source tools.ts file, re-run npm run mcp:export in dashboard-be, copy the result to mcp-tools/_generated/mcp-tools.raw.json, and re-run the build script here. The builder creates one page per tool, assigns the safety label, creates group overviews, updates the MCP navigation in docs.json, writes mcp-tools/_generated/mcp-tools.manifest.json, and adds compatibility redirects for superseded collection pages. Do not hand-edit files containing {/* mcp-sync:managed-file */}. Review MCP_TOOL_TEMPLATE.md before changing the generator. Prose outside generated blocks still follows every rule above, including the no-em-dash rule. The build script backslash-escapes literal {, }, and < characters in generated text (see mdx_escape()). Several tool descriptions include inline JSON-shaped examples (e.g. config = { output: node_id }) written as plain prose, not inside a fenced code block. MDX parses a bare {...} outside a code fence as a JSX expression, and fails to compile the page if the contents aren’t valid JavaScript. Escaping is the only transformation applied: it changes how the punctuation is encoded (\{ instead of {) so it renders as the same literal character, never the wording. If you see \{/\} in a generated file’s source, that is expected and correct; do not remove the backslashes. Run python3 scripts/validate_mcp_tool_docs.py after every MCP reference build. It checks tool coverage, source-block markers, safety labels, request examples, navigation, redirects, and authored dash punctuation.

​
Editing Discipline

  • Keep changes scoped to the user request.
  • Do not rewrite unrelated sections.
  • Preserve accurate product terminology.
  • Prefer incremental edits over broad, unnecessary rewrites.