.coderabbit.yaml

# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
reviews:
  profile: chill
  high_level_summary: true
  auto_review:
    base_branches:
      - "main"
      - "release/.*"
  pre_merge_checks:
    docstrings:
      threshold: 65

  path_instructions:
    # ─────────────────────────────────────────────────────────
    # ROOT-LEVEL CONTRIBUTOR DOCS
    # ─────────────────────────────────────────────────────────

    - path: "CLAUDE.md"
      instructions: >
        Project-wide guidance for Claude Code (this repo's CLAUDE.md is loaded
        into every session). When public APIs change, conventions evolve, or
        new lint/test patterns are introduced, ensure this file is updated so
        the rules stay in sync with the codebase. Conversely, flag any rule
        in CLAUDE.md that contradicts the diff (e.g. an import boundary
        described here that the PR violates) and ask the author to either
        update the rule or revert.

    - path: "AGENTS.md"
      instructions: >
        High-level orientation for AI agents working in this repo. Treat
        edits the same way as CLAUDE.md — keep it accurate as the project
        evolves; don't let drift accumulate.

    - path: "README.md"
      instructions: >
        Top-level project README. Should reflect the latest install / usage
        commands and the canonical package names (@frontmcp/sdk,
        @frontmcp/cli published as `frontmcp`, etc.). If commands or
        package names change in the diff, ensure README is updated to match.

    - path: "ROADMAP.md"
      instructions: >
        Forward-looking roadmap. Don't gate PRs on roadmap edits, but flag
        substantive feature work that lands without a corresponding roadmap
        update.

    - path: "BREAKING_CHANGES.v1.md"
      instructions: >
        Manually curated breaking changes for the v1.x line. Any PR that
        introduces a breaking change MUST update this file (or its JSON
        sibling `breaking-changes.v1.json`); ask for the entry if missing.

    # ─────────────────────────────────────────────────────────
    # MINTLIFY DOCS — FLAT, HUMAN-EDITED
    # ─────────────────────────────────────────────────────────
    # Layout reality (no live/draft split, no v/<minor>/ archives):
    #   docs/
    #   ├── docs.json                Mintlify navigation
    #   ├── assets/                  images / static
    #   └── frontmcp/                section content (mdx)
    #       ├── adapters/
    #       ├── authentication/
    #       ├── deployment/
    #       ├── extensibility/
    #       ├── features/
    #       ├── fundamentals/
    #       ├── getting-started/
    #       ├── guides/
    #       ├── nx-plugin/
    #       ├── plugins/
    #       ├── react/
    #       ├── sdk-reference/
    #       ├── servers/
    #       ├── testing/
    #       └── updates.mdx

    - path: "docs/frontmcp/**"
      instructions: >
        Mintlify documentation (MDX). Authors edit these files directly —
        there is no `draft/` staging area. When reviewing:
        - When public APIs in libs/** or plugins/** change, ensure the matching
          docs page under docs/frontmcp/** is updated in the same PR (sdk-reference,
          adapters, plugins, features, etc.). Flag missing doc updates.
        - Look for stale `import { ... } from '@frontmcp/...'` snippets,
          renamed exports, or removed options that no longer exist.
        - Look for stale URI examples — skills are exposed under the
          singular SEP-2640 `skill://` scheme (e.g. `skill://index.json`,
          `skill://{+skillPath}/SKILL.md`). The legacy plural `skills://`
          scheme has been removed; flag any reintroduced references.
        - Code examples should match the public surface of the corresponding
          library (no internal symbols, no removed APIs).
        - Updates to `docs/frontmcp/updates.mdx` follow the format described
          in `.github/UPDATES_FORMAT.md`.

    - path: "docs/frontmcp/sdk-reference/**"
      instructions: >
        SDK reference pages (organised under `core/`, `decorators/`,
        `registries/`, `contexts/`, `errors/`, `types/`, `utilities/`,
        plus standalone pages like `guard.mdx` and `telemetry.mdx`).
        These should reflect the actual public exports of `@frontmcp/sdk`
        (see `libs/sdk/src/index.ts`). When new symbols are exported from
        the SDK barrel, suggest a matching reference page in the right
        subfolder; when symbols are removed, flag stale entries.

    - path: "docs/docs.json"
      instructions: >
        Mintlify navigation. When new docs pages are added under
        docs/frontmcp/**, the navigation MUST list them or they won't be
        reachable. Conversely, removed pages MUST be removed from navigation
        — orphaned entries cause build failures.

    - path: "docs/assets/**"
      instructions: >
        Static assets used by the docs (images, diagrams). Flag oversized or
        non-optimised images (>500KB) and any binary checked in by mistake.

    - path: "docs/**"
      instructions: >
        Mintlify documentation root. See more specific rules above.
        - There is NO docs/live/** or docs/draft/** split in this repo —
          authors edit `docs/frontmcp/**` and `docs/docs.json` directly.
        - There is NO docs/v/{minor}/** archive — versioning is handled by
          the external docs deployment described in
          `.github/DOCS_VERSION_STRATEGY.md`.
        - The `frontmcp build` and `frontmcp` CLI is published as `frontmcp`
          on npm even though the workspace package is named `@frontmcp/cli`.
          Examples should reflect this (`npx frontmcp ...`, not
          `npx @frontmcp/cli`).

    # ─────────────────────────────────────────────────────────
    # SDK & SUPPORTING LIBRARIES
    # ─────────────────────────────────────────────────────────

    - path: "libs/sdk/**"
      instructions: >
        Core SDK. Strict rules per CLAUDE.md:
        - MUST import all MCP protocol types/schemas/`McpError` from
          `@frontmcp/protocol`, never from `@modelcontextprotocol/sdk`
          directly. Flag any direct upstream import.
        - MUST use `@frontmcp/utils` for filesystem (`readFile`, `stat`,
          `readJSON`, etc.) and crypto (`sha256`, `randomUUID`,
          `generateCodeVerifier`, etc.) — never `node:crypto` or
          `fs/promises` directly.
        - Test files MUST end in `.spec.ts` (NOT `.test.ts`).
        - 95%+ coverage target across statements/branches/functions/lines.
        - Use specific MCP error classes with JSON-RPC codes; avoid
          non-null assertions (`!`).
        - When public exports in `libs/sdk/src/index.ts` change, ensure
          `docs/frontmcp/sdk-reference/**` has matching updates.

    - path: "libs/protocol/**"
      instructions: >
        ONLY library allowed to import from `@modelcontextprotocol/sdk`.
        This is the boundary that lets us swap or upgrade the upstream
        package in one place. If a needed type isn't reachable, re-export
        it here rather than reaching around the boundary in callers.

    - path: "libs/auth/**"
      instructions: >
        Standalone auth library (sessions, credential vault, CIMD, OAuth).
        All authentication-related code belongs here, NOT in libs/sdk/src/auth.
        Flag PRs that introduce auth logic in libs/sdk/**.

    - path: "libs/skills/**"
      instructions: >
        Curated SKILL.md catalog. The catalog manifest
        (`catalog/skills-manifest.json`) is the single source of truth for
        scaffolding/install tooling. New skills should add a directory under
        `catalog/<category>/<name>/`, a SKILL.md, and a manifest entry.

    - path: "libs/cli/**"
      instructions: >
        Command-line interface — published as `frontmcp` on npm even though
        the workspace package is `@frontmcp/cli`. Docs and examples should
        use `frontmcp` / `npx frontmcp`, not `@frontmcp/cli`.

    - path: "libs/adapters/**"
      instructions: >
        Framework adapters (Express, Fastify, Lambda, Vercel, OpenAPI, etc.).
        Module format must remain CommonJS for Lambda/Vercel adapters per
        prior fix (#388) — flag any move back to ESM here.

    - path: "libs/**"
      instructions: >
        Publishable SDK libraries.
        - Review for API correctness, breaking changes, and consistency with
          docs.
        - When public APIs change, ensure there is a matching update under
          `docs/frontmcp/**` (this repo edits docs directly — there is no
          `docs/draft/**`).
        - Internal `@frontmcp/*` dependency versions must stay normalised
          to the exact release line (per #361/#363); flag drift.
        - Resource URI scheme for skills is the singular `skill://`
          (SEP-2640). The legacy `skills://` scheme has been removed and
          MUST NOT be reintroduced.

    # ─────────────────────────────────────────────────────────
    # PLUGINS
    # ─────────────────────────────────────────────────────────

    - path: "plugins/**"
      instructions: >
        Publishable SDK plugins (each its own package).
        - Review for API correctness, breaking changes, and consistency with
          `docs/frontmcp/plugins/**`.
        - Plugins extending `ExecutionContextBase` must follow the
          module-augmentation + prototype-extension pattern (see
          `plugin-remember/src/remember.context-extension.ts`).
        - Use `Plugin({ ... })` decorator metadata, not legacy patterns.

    # ─────────────────────────────────────────────────────────
    # APPS / DEMOS / E2E
    # ─────────────────────────────────────────────────────────

    - path: "apps/demo/**"
      instructions: >
        Demo application — playground for SDK usage examples and the docs
        site source for inline snippets. Keep examples idiomatic; they are
        copied into docs and reviewed by users learning the SDK.

    - path: "apps/e2e/**"
      instructions: >
        End-to-end test suites (one project per feature: skills, agents,
        cache, distributed, channels, etc.). Each E2E project boots a real
        FrontMCP server via `apps/e2e/<name>/src/main.ts` and exercises it
        via the `@frontmcp/testing` MCP client harness.
        - Tests live under `e2e/*.e2e.spec.ts` (NOT `.spec.ts`, NOT `.test.ts`).
        - Don't suggest mocking the MCP transport here — these tests exist
          precisely to catch regressions across the wire.
        - When adding tests, mirror the URI shape used in production code
          (e.g. `skill://{+skillPath}/SKILL.md`, not the removed `skills://`).

    - path: "apps/**"
      instructions: >
        Demo applications and end-to-end test suites. Reference for SDK
        usage; not published. Breaking changes to library APIs MUST be
        reflected here so the demos and E2Es continue to compile.

    # ─────────────────────────────────────────────────────────
    # SCRIPTS / WORKFLOWS / CONFIG
    # ─────────────────────────────────────────────────────────

    - path: "scripts/**"
      instructions: >
        Build / release / coverage scripts. When adding a `.ts`/`.mjs`
        script that imports `@frontmcp/*` workspace packages, the script
        runner needs `TSX_TSCONFIG_PATH=tsconfig.base.json` (see
        `libs/guard/project.json`'s `generate-types` target) — flag scripts
        that import workspace paths without that env var.

    - path: ".github/workflows/**"
      instructions: >
        CI/CD workflows. When adding workflows that run tests, prefer
        `nx run-many -t test --exclude='demo-e2e-*'` for unit tests and
        `nx run-many -t test --projects='demo-e2e-*'` for E2E. Don't skip
        hooks (`--no-verify`) or signing flags unless absolutely necessary.

    - path: ".github/ISSUE_TEMPLATE/**"
      instructions: >
        Issue templates. Keep terse and self-explanatory; avoid duplicate
        templates.

    - path: "**/project.json"
      instructions: >
        Nx project configuration. When adding a new build target, follow
        the existing pattern: `build-cjs` + `build-esm` + `build` (the
        composite target runs `strip-dist-from-pkg.js`). Flag custom
        target structures unless the package genuinely needs them.

    - path: "**/package.json"
      instructions: >
        Workspace package config.
        - Internal `@frontmcp/*` dependencies must be pinned to the exact
          release-line version (per #357/#361/#363). Flag `^` or `~` ranges
          on `@frontmcp/*` deps.
        - `engines.node` should match the root package.json (`>=24.0.0`).

    - path: "**/eslint.config.mjs"
      instructions: >
        Per-project ESLint config. Keep aligned with the root
        `eslint.config.mjs` and `eslint.imports.mjs`. New rules should be
        added at the root, not duplicated per-project, unless a project
        genuinely needs an exception.

    - path: "**/jest.config.ts"
      instructions: >
        Per-project Jest config. Test files MUST match `.spec.ts` (or
        `.spec.tsx` / `.e2e.spec.ts` / `.perf.spec.ts` / `.pw.spec.ts`).
        Flag any `.test.ts` patterns.

  path_filters:
    # Standard build/cache outputs
    - "!**/dist/**"
    - "!**/build/**"
    - "!**/coverage/**"
    - "!**/.next/**"
    - "!**/.nuxt/**"
    - "!**/.svelte-kit/**"
    - "!**/.turbo/**"
    - "!**/.swc/**"
    - "!**/.parcel-cache/**"
    - "!**/.nx/**"
    - "!**/node_modules/**"
    - "!**/.yarn/**"
    - "!**/.pnpm-store/**"
    - "!**/*.min.{js,css}"
    - "!**/*.map"
    - "!**/public/**"
    - "!**/*.svg"
    - "!**/*lock*.{json,yaml,yml}"

    # Generated files committed to git so IDE works without a build.
    # `*.generated.ts` files (e.g. libs/guard/src/schemas/schemas.generated.ts)
    # are produced by `scripts/generate-schema-types.mjs` from Zod schemas;
    # human review of the generated output adds noise without value.
    - "!**/*.generated.ts"

    # Per-project local Nx cache
    - "!**/tsconfig.tsbuildinfo"