Skip to content

AGENTS.md

Latest commit

 

History

History
134 lines (110 loc) · 6.1 KB

AGENTS.md

File metadata and controls

134 lines (110 loc) · 6.1 KB

AGENTS.md

Instructions for AI coding agents working in this repository (Superwall docs site).

For documentation-writing guidelines (tone, content conventions, etc.), see content/README/AGENTS.md.

Project overview

  • Stack: Next.js + Fumadocs (MDX) + TailwindCSS
  • Hosting: Cloudflare (via @opennextjs/cloudflare)
  • Docs: multi-platform SDK docs (iOS, Android, Flutter, Expo, React Native) + dashboard/integration guides
  • Search/AI: built-in search + AI search mode; support center integration
  • Theming: custom themes; dark/light mode is disabled by default

Non-negotiable rules

  • Never deploy without explicit user approval.
  • Content vs. engineering changes:
    • Content changes: update files in content/docs/** (and content/shared/** if used).
    • Engineering changes: you may edit other parts of the repo as needed.
    • Never edit public/** (it is generated and will be overwritten).
  • SDK references first: if a task needs SDK APIs/changelogs, run bun run download:references before writing.
  • SDK reference tables: use the Fumadocs-style TypeTable for parameters/types; do not use <ParamTable>.
  • Test: run bun run build:cf and bun test after making changes to ensure you didn't break anything

Common commands (run from repo root)

# Dev (http://localhost:8293)
bun run dev

# Build (runs all generators, then MDX + Next build)
bun run build

# Clear caches (when build/dev gets weird)
rm -rf .next
bun run clear:cache

# Content generation / assets
bun run generate:llm
bun run generate:md
bun run copy:docs-images
bun run watch:images

# Cloudflare builds / preview
bun run build:cf
bun run preview

# Deploy (DO NOT RUN WITHOUT USER APPROVAL)
bun run deploy:staging
bun run deploy

Content + navigation system

  • Navigation is defined by meta.json files alongside content directories.
    • If a meta.json does not include "...", every page must be explicitly listed.
    • Use relative paths without extensions (e.g. "guides/my-guide", not "guides/my-guide.mdx").
    • You can nest objects to group related pages.
  • Adding a new page:
    • Create the .mdx file under the correct content/docs/** folder.
    • Update the folder’s meta.json to include it in navigation.
    • Run bun run build to verify generation + routing.
  • Images: assets in docs content are copied into public/ during build (use bun run copy:docs-images; in dev use bun run watch:images).

Routing, redirects, and base path

  • The site is served under /docs (basePath + assetPrefix in next.config.ts).
  • /docs/sdk/* is a selector route that redirects to the chosen platform page.
  • Redirects are generated from redirects-map.ts (folderRedirectsMap, fileRedirectsMap, externalRedirectsMap) inside next.config.ts.
    Changes require a rebuild to take effect.

MDX / remark pipeline (order matters)

Custom remark plugins are wired in source.config.ts. The current order is:

  1. remark-image-paths (must run first)
  2. remark-follow-export
  3. Fumadocs “existing” plugins
  4. remark-include
  5. remark-directive
  6. remark-tabs-syntax
  7. remark-code-language
  8. remark-codegroup-to-tabs
  9. remark-sdk-filter (must run last; removes non-matching SDK blocks)

Key files (where to look first)

  • Config: source.config.ts, next.config.ts, open-next.config.ts, tsconfig.json
  • Redirects: redirects-map.ts
  • Layout/routing: src/app/layout.config.tsx, src/app/(docs)/[[...slug]]/page.tsx
  • Source plumbing: src/lib/source.ts, src/mdx-components.tsx
  • Plugins: plugins/*
  • Scripts: scripts/* (title map, generators, image copy/watch, cache clear, etc.)
  • New UI/components: put React components in src/components/ and wire site-level layout/nav in src/app/layout.config.tsx / src/lib/source.ts.

What requires a rebuild (not just hot reload)

  • meta.json navigation edits
  • redirects-map.ts changes
  • remark plugin changes (plugins/* or source.config.ts)
  • new/updated images (make sure copy/watch runs)

Cloudflare / deployment notes

  • Cloudflare builds use bun run build:cf (OpenNext adapter).
  • Cloudflare Workers disallow eval(): next.config.ts aliases the eval-based fumadocs-ui hide-if-empty component to src/components/HideIfEmptyStub.tsx.

Performance notes

  • Builds use Turbo (next dev --turbo) and Cloudflare’s CDN for delivery.

SDK references (required for SDK-accuracy work)

Run:

bun run download:references

This clones/pulls SDK repos into reference/ (gitignored). Use the source to confirm API signatures and behavior before updating docs.

SDK changelogs (strict rules)

  • Docs location: content/docs/<sdk>/changelog.mdx for ios, android, flutter, expo, react-native
  • Source of truth: reference/<sdk>/CHANGELOG.md
  • Process: run bun run download:references, then copy upstream changelog verbatim
  • Allowed edits: keep required frontmatter (title: "Changelog" + short per-SDK description). Optionally add one top-level deprecation callout.
  • Formatting: no MDX components/wrappers in the changelog body; escape angle brackets that would parse as tags (e.g. &lt; 8).
  • Navigation: ensure each SDK meta.json lists changelog right after index.

AI SDK / AI SDK Elements

  • For any AI SDK or AI SDK Elements work, fetch the latest docs via Context7 MCP before making changes.

Environment variables

  • SEARCH_MODE: 'fumadocs' (default) or 'rag' (external AI search)
  • NEXTJS_ENV: development/production
  • Optional integration keys may exist (Slack, Mesh, Unify, RB2B, Pylon). See project environment documentation if present.

TypeScript path aliases

  • @/* → src/*
  • @/.source → .source/index.ts (generated by Fumadocs)

Troubleshooting

  • Build failures: check MDX syntax; validate meta.json; ensure listed pages exist; run bun run build for full errors.
  • Dev server issues: rm -rf .next, bun run clear:cache, verify port 8293 is free, reinstall dependencies if needed.

Skill mirrors

  • Keep .agents/skills/ and .claude/skills/ in sync for shared skills.