​

Agent Guidelines for Suki Developer Documentation

​

Project Type

​

New Doc Writing Rule

​

Instruction scope (do not assume)

• Do only what the user explicitly asked. If they asked to check, verify, or investigate, deliver findings (what the repo says, gaps, contradictions). Do not rewrite multiple pages or assert product behavior unless they asked you to update docs or confirmed facts.
• If something is unclear or needs ground truth not present in the repo (for example, whether a feature exists in a shipped SDK), ask the user for clarity instead of assuming and editing.
• Broad edits (new sections, cross-cutting claims, many files) require an explicit request or a short plan the user approves.

​

Git (commit and push)

• Do not run git commit or git push unless the user explicitly asks to commit and/or push (for example: “commit”, “push”, “commit and push”).
• When work is done without that request, leave the working tree as-is (or only stage if they asked to stage), summarize changes, and let the user commit when they want.

​

Build / Development

• mintlify dev or mint dev — Start local development server
• mintlify install — Reinstall dependencies if dev server fails
• No test commands (documentation site)

​

File Structure

• docs.json — Main Mintlify configuration (navigation, theme, SEO)
• documentation/ — Platform docs, getting started, guides
• api-reference/ — API reference and OpenAPI-backed pages
• web-sdk/ — Web SDK docs
• mobile-sdk/ — Mobile SDK docs
• headless-web-sdk/ — Headless Web SDK docs
• sdk-overview/ — SDK overview
• Glossary/ — Glossary
• updates/ — Release notes and announcements
• Root — Shared assets: logo/, og-image/, new-favicon.ico, scripts/, style.css (see scripts/README.md for PDF export limits and third-party MDX/Mermaid → PDF options)
• scripts/export-pdf.js: PDF control (icon + label) next to the page h1 (browser print or Save as PDF). Edit EXCLUDED_PREFIXES / EXCLUDED_EXACT in that file to hide the control. When the user uses this control (html.suki-printing-pdf), prep injects /logo/dark-light.svg at the top of #content-area and removes it on afterprint. Print/PDF is theme-agnostic: @media print always applies the same light-on-paper typography (prose, code, pre, callouts, links, strong/b) whether the site is in light or dark UI, so you do not maintain parallel html.dark print rules. Layout helpers (flatten grid/flex, sticky/fixed, z-index, overflow-hidden) still apply under #content-area for OpenAPI-style pages; transform: none is not applied inside svg so Mermaid diagrams print correctly. primeMermaidForPrint() (before PDF/print) nudges window.mermaid to render when possible. No PDF button on paths in EXCLUDED_PREFIXES / EXCLUDED_EXACT: OpenAPI endpoint sections only (api-reference/authentication, ambient-sessions, audio-transcription, ambient-content, user-preferences, feedback, asynchronous, info), plus doc home/overview/introduction, SDK overview, updates/release-notes, updates/announcements, updates/release-notes-rss-feed. PDF is enabled on monthly pages updates/mmmYYYY-release-notes. For print/PDF, the script also opens all <details> (Mintlify Accordion) under #content-area, uses matchMedia('print'), double requestAnimationFrame before print(), plus beforeprint/afterprint cleanup. Tab panels are expanded the same way. Print layout rules are in style.css under @media print. release-notes-print.css (imported from style.css) plus scripts/release-notes-print-scope.js add html.suki-print-monthly-release-notes and extra print styling only on those monthly release note URLs. Do not add extra text-decoration: underline on links in print: Mintlify .link already uses a bottom border, which would double with underline in PDF.

​

Content Guidelines

• Use MDX for all documentation files
• Mermaid: Use ```mermaid actions={false} (same line) on new diagrams so Mintlify does not render zoom/pan chrome that breaks browser PDF/print. If you need on-page controls for a specific diagram, set actions={true} and accept print noise, or add a static image for the PDF use case.
• Include frontmatter with title and description
• Images: use light/dark variants with className="block dark:hidden" and className="hidden dark:block" where appropriate
• Follow healthcare/medical terminology standards; keep a professional, clinical tone for healthcare developers
• Writing style: Follow the Writing style guide for voice, punctuation, capitalization, inclusivity, and terminology. Summary: no em dashes (use commas or colons); sentence-style capitalization for headings; Oxford comma; concise, scannable prose

​

Navigation

• Tabs: Home, Docs, SDKs, APIs, Glossary, Release Notes (defined in docs.json under navigation.tabs)
• Docs tab: Getting Started, Onboarding & Authentication, Product Capabilities, Guides, Support/FAQs
• SDKs tab: The SDKs tab uses Mintlify’s built-in menu on the tab (see Mintlify navigation – Menus): SDK overview, Web SDK, Mobile SDK, and Headless Web SDK, each with the same groups / pages tree as before. No custom navbar script or CSS for a chevron or flyout.
• APIs tab: API Overview, API References (Authentication, Ambient Session Management, Dictation, Ambient Content, etc.)
• Update docs.json when adding new pages; use flat paths (e.g. documentation/my-page, web-sdk/guides/ambient)

​

Web SDK

• Use the existing code block structure with js and react tabs and code blocks with appropriate icons
• Ensure code examples are clear and relevant to SDK usage
• Add references and “read more” links to other sections of the documentation where helpful

​

Release Notes

• When adding a new release section in updates/release-notes.mdx, add the LATEST badge to the newest release card only
• Remove the LATEST badge from the previous release card
• Only one release should have the LATEST badge at any time
• Release notes RSS (hub): The hub page uses mode: frame; Mintlify does not emit <Update> items in RSS for frame pages. The combined feed lives on updates/release-notes-rss-feed.mdx (rss: true, hidden: true, no frame). Feed URL: /updates/release-notes-rss-feed/rss.xml. The RSS button on the hub points there. When you add a month to the timeline, add a matching <Update> in release-notes-rss-feed.mdx (newest first). See scripts/release-notes-rss.md.

​

Release Note Page Format

1. Frontmatter: title (e.g. “March 2026”), description, sidebarTitle, rss: true
2. Lead paragraph: One short summary of the release (no heading)
3. Sections: Use ## What's New, ## What's Enhanced, ## What's Changed, ## What's Removed as needed
4. Anchors: Add <span id="kebab-case-anchor" /> before each <Update> so deep links work
5. Update blocks: Wrap each change in <Update label="..." description="..." tags={[...]}></Update>. Use tag="LATEST" only on the single newest update.

• Section heading: ### New Features | ### Enhancements | ### Deprecated | ### Removed (match the section)
• Badge: <Badge size="sm" color="...">Product Version</Badge>
  • API: color="blue" (e.g. API v1.2.1)
  • Web SDK: color="green" (e.g. Web SDK 2.1.2)
  • Headless Web SDK: color="orange"
• Bold title: One line summarizing the change (e.g. Audio streaming and download:)
• Body: Short paragraph(s) describing what changed and how to use it
• Why it matters: One line starting with Why it matters: explaining the benefit
• Link: Learn more in the [Link text](path) documentation. or ... guide. (use relative path from updates/)