> ## Documentation Index > Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # AGENTS # 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. ## Link and Navigation Hygiene * 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: ```bash theme={null} npx -y -p node@20 -p mint@latest mint validate rg -n $'\\u2014|\\u2013' --glob '!mcp-tools/**' . ``` 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//.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: */} ... {/* mcp-sync:end: */}` 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.