Sim owns the content catalog, page rendering, navigation, search, and machine interfaces. Next.js prerenders public pages from that catalog. MDX, Shiki, Radix primitives, and the official MCP SDK provide focused parsing, highlighting, accessibility, and protocol implementations. No Fumadocs runtime or build dependency remains.

app/ follows the App Router's file conventions. The root layout owns the persistent shell: navbar, sidebar, footer, search, and mobile navigation. Client navigation reads the current pathname without remounting the sidebar's scroll container. Only navigation metadata is shared with the client; document bodies and the complete catalog stay on the server. The single catch-all route loads that page's server-compiled MDX or specification reference into the shared article and page frame, which owns its responsive outline. Ordinary content does not create a React route or duplicate a layout. Promised route parameters and the Metadata API follow the installed Next.js 16 documentation.

1. Read EDITORIAL_GUIDE.md and the complete existing page before editing.
2. Add content/docs/<section>/<page>.mdx with a nonempty title and a useful description. Folder index.mdx files fold to the folder URL. Keep existing paths and explicit [#anchor] aliases stable.
3. Place the page in the appropriate meta.json order. Its optional labels map overrides a navigation entry's label without changing the article title. The catalog derives navigation, section-local previous/next links, discovery, and the sitemap. Do not add another page list in a consumer.
4. Use ordinary Markdown and shared components. MDX imports must be named imports registered in lib/content/compile.ts. Unknown modules, components, metadata, duplicate routes/anchors, broken internal links, or missing local media fail compilation with source context.
5. Run bun run --cwd apps/docs content:generate, inspect the affected page and Markdown, and run the applicable repository gates.

The compiler records source hashes, heading IDs, code-fence hashes and media references. Run content:verify-compatibility to enforce preservation against scripts/fixtures/content-baseline.json and write test-results/compatibility.json (or DOCS_COMPATIBILITY_REPORT_PATH). The frozen fixture retains its original source provenance and must not be regenerated from the implementation under test to silence a failure. Review intentional public-contract changes explicitly. Ordinary builds validate current content without loading this inventory or writing a compatibility report. The compiler serializes every tab and disclosure into meaningful Markdown, including workflow configuration and outputs. The introductory paragraph is hidden in HTML only when it exactly repeats the page description; machine-readable prose remains intact.

Shared dimensions, tokens, component ownership, and intentional differences from platform components are documented in DESIGN_SYSTEM.md.

Keep reusable chrome in components/docs/ and reusable reading components in components/ui/. Export Markdown element mappings from getMDXComponents() rather than styling each page. A new MDX component also needs an explicit compiler allowlist entry and a meaningful serializer in lib/content/markdown.ts. Add its states to /design-system and inspect its keyboard, touch, light and dark behavior.

Use canonical @sim/emcn/icons glyphs. Docs tokens are scoped under .docs-root/.docs-portal; platform and landing styles are unchanged. The docs cn wrapper extends class merging for the named docs text-size tokens, so a color utility cannot erase a typography utility. Shared controls own hover, focus, pressed, disabled, loading, success, and error states.

Default components to server rendering. Client islands are reserved for navigation, search, tabs, disclosure reveal, clipboard, media viewing, theme choice, and interactive workflow examples. Pass rendered server content into those islands. Never import the catalog, compiler, specifications, embedding credentials, or syntax highlighter into a client component.

Keep platform screenshots and original integration logos in public/static/ with meaningful alternative text. Use the shared Image component for sizing, captions and expansion. Preserve workflow fixtures as data; the shared preview renders the actual graph, inspector, and outputs.

The compiler converts local screenshot sources into Next.js static image imports after extracting their original Markdown URLs. Static imports give changed assets new content-addressed URLs. The shared image component supplies responsive sizes for each frame variant; Next serves a small set of WebP widths at quality 90 for interface text and 75 for scenery. The original loads when the media viewer opens. Backgrounds use the same hashed assets in both views. Legacy public asset URLs remain available; mutable filenames do not receive immutable caching.

Product contracts remain authoritative for OpenAPI. Run bun run generate:openapi after changing their owners; the docs compiler projects operations from all registered specifications. CLI, MCP operations, integration content, and marked Agent streaming regions retain their existing generators listed in EDITORIAL_GUIDE.md. Do not hand-edit generated regions. Request examples are inert and never execute an API call or accept credentials. Specifications own authentication alternatives, media types, named examples, response headers, callbacks, defaults, and deprecation. Schema-derived samples are labeled as examples. Multipart examples must let the client set the boundary.

Keep existing API heading aliases (authorization, parameters-path, parameters-query, parameters-header, parameters-cookie, request-body, response-body, and callbacks) when changing the reference layout. Local JSON pointers preserve sibling properties, and recursive references remain explicit in both HTML and Markdown.

The agent docs manifest continues to publish existing .mdx paths and its deliberate corpus exclusions. Run bun run check:docs-manifest, bun run check:agent-stream-docs, bun run check:cli-docs, bun run check:openapi, and bun run check:docs after relevant changes.

One catalog owns HTML, canonical metadata, heading citations, per-page Markdown, JSON, MCP, and sitemap identity. The aggregate llms-full.txt deliberately excludes generated operation bodies; individual operation Markdown is complete. See MACHINE_ACCESS.md for public contracts, search freshness and real-client verification.

Reading routes use generateStaticParams and reject unknown slugs. Compilation and highlighting happen before or during the production build, not in the browser. The compiler caches unchanged MDX and emits separate modules per page; it bounds aggregate catalog size. The shell receives only navigation and headings, while article content remains server rendered. Fonts are local Geist/Geist Mono assets; only the reading font is preloaded. Code and tables scroll within their own surfaces. Reduced-motion preferences suppress decorative transitions.

Markdown GET handlers explicitly use dynamic = 'force-static' because their complete responses depend only on the build-time catalog. generateStaticParams and dynamicParams = false restrict HTML and Markdown to known routes; unknown slugs return 404. Search and MCP remain request-time handlers. This follows the installed Next.js caching model; Cache Components is not enabled, and adopting it would require migrating these route settings together.

Metadata uses canonical URLs, descriptive titles, Open Graph/Twitter images, real Git modification dates when available, TechArticle/BreadcrumbList structured data, and a generated sitemap. JSON-LD is safely serialized. Robots permit public docs and machine-readable discovery. There is no special AI-ranking markup or indexing guarantee: clear HTML, preserved citations, useful text, crawlable links, and consistent public representations are the supported foundations.

The implementation was checked against the installed Next.js 16.4.1 docs and current official project structure, server/client boundaries, MDX, and metadata guidance. The monorepo's patched Next version is retained. Google's AI search guidance remains the basis for crawlability; no separate AI-specific schema is required.

Review the compatibility report, library gallery, representative pages, and HTTP/browser reports. Run a production build without embedding credentials to verify the local fallback. Production search index publication remains a separate deployment step and must pass its freshness check.

Search publication changes docs_embeddings separately: before publishing, back up that table and record its paired docs deployment and source revision. Rollback must hold queued publishers, restore the paired deployment and index, and check freshness and citations from the restored source. The workflow does not create this backup automatically and checks out current main; ordinary dispatch cannot select an older publisher.

The requested move to https://sim.ai/docs requires a coordinated path-aware build and infrastructure cutover. See the domain migration plan; the current build remains on docs.sim.ai until that work is verified.