Skip to main content

​
Preview and validate

Install the pinned Bun/Node toolchain and clone the repository. Docker, Rust, and TanStack Start are paused and are not prerequisites for writing docs.
The local wrapper runs the version pinned in apps/docs/mintlify-version.json through npx from apps/docs. Preview at http://localhost:3000 (or the selected port), and stop with Ctrl+C. It does not start containers or other apps. Run finite source checks from the repository root:
The inventory covers maintained app routes, packages, toolchains, and declared and locked dependencies. Do not hand-edit generated reference pages. It excludes paused Rust/TanStack source and dependency refreshes. Version references describe checked-in versions, not the newest upstream release or a deployment claim. Generated pages under reference/repository/ carry noindex: true in their frontmatter. They remain public and visible in navigation, but stay out of site search, search-engine indexing, AI assistant context, llms.txt, and llms-full.txt. The inventory generator owns this flag. Keep seo.indexing unset (or at its default) in docs.json; "all" can override the exclusions. See Mintlify’s indexing rules and LLM files. Authored package guides, including SDK and masonry, stay indexed. The pinned 4.2.1184 static exporter excludes these pages from its search index and emits their HTML with noindex, but still lists them in its llms.txt. It emits no llms-full.txt. Use hosted checks below to verify the documented LLM exclusions; a successful static export does not establish them. After an authorized deployment, fetch llms-full.txt and confirm that no Source: https://docs.tuturuuu.com/reference/repository/ sections remain; ordinary links to those pages may remain. Check llms.txt for excluded entries, following any split indexes it links. Fetch every generated page anonymously: it must return HTTP 200 with its body and a robots noindex directive. Confirm that the Reference navigation still lists those pages. Search for exact generated page titles and distinctive body text in the site’s search: those pages must be absent, while an authored guide still returns results. Record full-file byte size after the deployment and search-index refresh. Source checks alone do not prove hosted LLM output or search behavior. docs-seo-check.yaml runs inventory, navigation/link, SEO-policy tests, and strict Mintlify validation in CI. Strict validation compiles docs; do not run it or app builds on this machine. Require relevant lint, type-check, unit-test, and real Next build workflows for the exact commit when implementation changes.

​
Sitemap ownership and Search Console

packages/utils/src/seo-policy.json is the canonical app-domain and public-page allowlist. Generate satellite assets with node scripts/generate-app-seo.js and verify them with --check. The generator removes obsolete static sitemaps for private apps and the platform; it leaves unrelated public files untouched. Authenticated workspace pages, login flows, private share links, and checkout pages are not sitemap candidates. A private app needs no sitemap until it has explicitly indexable public content; do not copy the platform sitemap into it. The platform owns src/app/sitemap.ts and src/app/robots.ts; static files with those names conflict with its publication-aware metadata routes. Satellite sitemaps advertise their own canonical origin, including Nova (nova.tuturuuu.com) and Rewise (rewise.tuturuuu.com) production domains. The retired rewise.me and rewise.school hosts and the noncanonical nova.ai.vn host must not appear in generated discovery links. Do not invent lastmod values from build time or add language URLs that redirect to the same canonical page. Dynamic publication paths need an anonymous, publication-aware reader before being enumerated; public route patterns alone do not expose a content catalog. After deployment, verify each advertised sitemap returns XML with successful HTTP status and canonical URLs before submitting it under its matching Search Console property. Repository checks do not prove deployment or crawlability. The invite-only Colab SPA also declares noindex; its authenticated workshop URLs are not a public sitemap catalog. Docs hosting generates its own https://docs.tuturuuu.com/sitemap.xml.

​
Writing Documentation

​
File Structure

Each documentation file should follow this structure:

​
Content Guidelines

  1. Use clear headings to structure your content
  2. Include code examples with proper syntax highlighting
  3. Add cross-references to related documentation
  4. Keep content up-to-date by updating the updatedAt field
  5. Use consistent formatting throughout

​
Product Decisions and Regression Evidence

Record intentional customer behavior in the owning feature page alongside the change: scope, defaults, affected web/mobile surfaces, persistence and permission rules, and intentional exceptions. Distinguish implemented behavior from pending stages and installed or deployed behavior. Link the owning regression tests and exact validation evidence; do not convert a user preference into a repo-wide rule. Exercise the real boundary that previously failed. Examples include server-to-client date serialization, cache provenance before membership-based cancellation, and route-to-provider payload propagation. A helper-only mock can pass while those contracts remain broken. Use synthetic fixtures; keep private calendars, mail, credentials and live notifications out of shared test evidence.

​
Long-session learning maintenance

Finish sustained agent work by updating reusable guidance, not by copying the conversation into documentation. Use the existing feature page for customer behavior, the operational runbook for debugging/delivery, and the source skill reference for a fragile agent procedure. Keep AGENTS.md for rules that apply across tasks; managed plugin caches are not editable source. Record the observed cause, the evidence that distinguishes it from alternatives, the safe repair procedure, relevant regression tests and outstanding runtime proof. Separate source implementation, focused local validation, exact-commit CI, deployment markers, production migrations and authenticated runtime behavior. A merge alone proves none of the later stages. Avoid promoting an unverified inference or a one-off workaround into a permanent rule. Use the autonomy contract for useful child work during PR/CI waits and occasional evidence-led workflow audits. Propagate accepted guidance through the maintained plugin and next substantive child/owner briefs. Do not add recurring timers or wake retired controllers as a maintenance side effect. For parallel work, assign one owner per overlapping path and Git publication lane. A child agent being listed is not proof that it is active: check its current state and request a concrete path/check/commit handoff. If a PR branch has another agent’s dirty packet, integrate main in a fresh isolated worktree rather than staging or overwriting that packet. After the parent merges, transplant the owned follow-up patch onto current main; do not replay the whole old branch. Keep temporary receipts, exact SHAs, pending gates and scheduler IDs in an unstaged coordination note. Register every worked-on PR with T3 Code, including follow-ups. Use native PR watches for PR news; use an explicitly authorized scheduled task for broader delivery follow-through. Record its cadence and next run, and disable it when delivery is complete. Recheck live refs after each wake. The latest explicit user instruction determines merge/review timing; a speed exception for merging does not silently authorize production promotion or expand the release range.

​
Code Examples

When including code examples:
  • Use proper syntax highlighting
  • Include TypeScript types
  • Show both server and client examples
  • Include error handling
  • Test examples before committing

​
Images and Assets

  • Store images in the images/ directory
  • Use descriptive filenames
  • Optimize images for web
  • Include alt text for accessibility

​
Contributing

​
Before You Start

  1. Check if documentation already exists
  2. Look for similar patterns in existing docs
  3. Follow the established structure
  4. Read the Organization Guide for structure

​
Making Changes

  1. Create a branch for your documentation changes
  2. Write clear, concise content that’s easy to understand
  3. Include practical examples that developers can use
  4. Update related documentation if needed
  5. Test your changes locally with bun dev:docs

​
Review Process

  1. Self-review your changes for clarity and accuracy
  2. Check links to ensure they work correctly
  3. Verify code examples are correct and complete
  4. Update the table of contents if adding new sections
  5. Submit a pull request with a clear description

​
Best Practices

​
Writing Style

  • Be concise but comprehensive
  • Use active voice when possible
  • Write for your audience (developers)
  • Include context for complex topics
  • Use consistent terminology throughout

​
Organization

  • Group related content together
  • Use clear section headings
  • Include a table of contents for long pages
  • Cross-reference related documentation
  • Keep examples practical and realistic

​
Maintenance

  • Update documentation when APIs change
  • Remove outdated information promptly
  • Keep examples current with latest versions
  • Review documentation regularly for accuracy
  • Ask for feedback from other developers

​
Mintlify runtime compatibility

The docs wrapper pins Node 24.19.0 alongside Mintlify in apps/docs/mintlify-version.json, independent of the repository .node-version pin (see Node.js runtime pin). Other host versions use an isolated npx Node executable; the host installation is unchanged. Got 12.6.1, used by the pinned CLI’s connectivity probe, can schedule a retry after rejection on Node 24.20+ and crash before validation reports an MDX result. The compatibility pin preserves validation and failure exits; it does not retry or ignore errors. The initial tool download needs network access. Reassess the pin when the CLI’s Got dependency contains the upstream connection-error fix. The wrapper gives npm an empty temporary --prefix while Mintlify still runs from apps/docs. This prevents npm from traversing Bun’s installed workspace graph: published packages can contain development-only catalog: ranges that npm cannot parse when applying the repository’s security overrides. Keep those overrides and installed manifests intact. The prefix is removed after success or failure; scripts/paused-runtimes.test.js covers working directory, prefix isolation, cleanup and exit propagation. Strict validation remains CI-only.