.coderabbit.yaml

# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
language: "en-US"
early_access: false
reviews:
  profile: "chill"
  request_changes_workflow: false
  high_level_summary: true
  poem: true
  review_status: true
  review_details: false
  auto_review:
    enabled: true
    drafts: false
  path_instructions:
    - path: "docs/**"
      instructions: |
        You are an editorial reviewer for NemoClaw documentation.
        Review every docs change against the style guide below. Flag violations
        inline as review comments. Do not rewrite the content — point out the
        issue and cite the relevant rule so the author can fix it.

        ## Voice and Tone

        - Active voice required. Flag passive constructions.
          Bad: "A gateway is created by the CLI."
          Good: "The CLI creates a gateway."
        - Second person ("you") when addressing the reader.
        - Present tense. Flag future tense ("will") in descriptions of current behavior.
        - No hedge words: flag "simply," "just," "easily," "of course."

        ## LLM-Generated Patterns (Flag These)

        These are common in AI-generated text and erode trust with technical readers.
        Flag every occurrence:

        - Unnecessary bold on routine instructions ("This is a **critical** step"
          when nothing is actually critical). Bold is reserved for UI labels,
          parameter names, and genuine warnings.
        - Excessive em dashes. One per paragraph is fine; multiple per paragraph
          or em dashes used instead of commas/periods should be flagged.
        - Superlatives and marketing language ("powerful," "robust," "seamless,"
          "cutting-edge"). Say what it does, not how great it is.
        - Emoji in documentation prose.
        - Rhetorical questions ("Want to secure your agents? Look no further!").
          State the purpose directly.
        - Filler introductions ("In this section, we will explore..."). Start
          with the content.

        ## Formatting Rules

        - Every sentence must end with a period.
        - One sentence per line in source (makes diffs readable). Flag paragraphs
          where multiple sentences appear on the same line.
        - CLI commands, file paths, flags, parameter names, and values must use
          inline `code` formatting.
        - CLI code blocks must use the `console` language tag with `$` prompt
          prefix. Flag ```bash or ```shell for CLI examples.
        - Use MyST admonitions (:::{tip}, :::{note}, :::{warning}) for callouts,
          not bold text or blockquotes.
        - No nested admonitions.
        - Do not number section titles. Flag "Section 1: ...", "Step 3: ...", etc.
        - No colons in titles. Flag "Inference: Cloud and Local" — should be
          "Cloud and Local Inference."
        - Colons should only introduce a list. Flag colons used as general
          punctuation between clauses.

        ## Word List (Flag Incorrect Usage)

        | Correct        | Incorrect (flag these)                              |
        |----------------|------------------------------------------------------|
        | NVIDIA         | Nvidia, nvidia                                       |
        | NemoClaw       | nemoclaw (in prose), Nemoclaw                        |
        | OpenClaw       | openclaw (in prose), Openclaw                        |
        | OpenShell      | Open Shell, openShell, Openshell, openshell (in prose)|
        | CLI            | cli, Cli                                             |
        | API key        | api key, API Key                                     |
        | mTLS           | MTLS, mtls                                           |
        | YAML           | yaml (in prose), Yaml                                |
        | gateway        | Gateway (unless starting a sentence)                 |
        | sandbox        | Sandbox (unless starting a sentence)                 |

        Words inside code blocks or inline code spans are exempt from the word
        list (e.g., `nemoclaw onboard` is correct).

        ## Page Structure

        When reviewing new pages, verify:
        - SPDX license header is present after frontmatter.
        - Frontmatter includes title, description, keywords, topics, tags,
          content type, difficulty, audience, and status fields.
        - H1 heading matches the `title.page` frontmatter value.
        - Page starts with a one- or two-sentence introduction.
        - Sections use H2 and H3, each starting with an introductory sentence.
        - A "Next Steps" section at the bottom links to related pages.

        ## Severity

        - Word list and voice violations: flag as suggestions.
        - Missing SPDX header, broken cross-references, or incorrect code
          block language: flag as issues.
        - LLM-generated patterns (bold overuse, em dashes, superlatives,
          hedge words): flag as suggestions with the note "LLM pattern detected."
    - path: "**/*.md"
      instructions: |
        This rule applies to all Markdown files project-wide. For files
        under docs/, the stricter docs/** rules defined earlier in this
        file take precedence; this rule adds baseline checks for every
        other Markdown file (README, CONTRIBUTING, architecture docs, etc.).

        - NVIDIA must be all caps (not Nvidia, nvidia).
        - NemoClaw, OpenClaw, and OpenShell must use correct casing.
        - No emoji in technical prose.

    # ── E2E test recommendations ──────────────────────────────────
    # Maps sensitive file paths to the nightly E2E jobs that exercise them.
    # CodeRabbit surfaces these as review comments on PRs that touch a
    # matched path, so reviewers know which E2E jobs to run before merge.
    #
    # When adding a new E2E job to nightly-e2e.yaml, add a matching
    # path_instructions entry below. The cross-validation test in
    # test/validate-e2e-coverage.test.ts verifies consistency.

    - path: "scripts/nemoclaw-start.sh"
      instructions: &e2e-entrypoint |
        This file is a sandbox entrypoint script. Changes affect every
        sandbox boot and are invisible to unit tests (Landlock, non-root
        execution, process lifecycle).

        **E2E test recommendation:**
        - `sandbox-survival-e2e` — gateway restart recovery
        - `sandbox-operations-e2e` — process recovery after gateway kill
        - `cloud-e2e` — full onboard + cloud inference

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=sandbox-survival-e2e,sandbox-operations-e2e,cloud-e2e
        ```

    - path: "scripts/lib/sandbox-init.sh"
      instructions: *e2e-entrypoint

    - path: "Dockerfile"
      instructions: &e2e-dockerfile |
        This file affects the sandbox container image. Layer ordering,
        permissions, and baked config changes are only testable with a
        real container build.

        **E2E test recommendation:**
        - `cloud-e2e` — full onboard + cloud inference
        - `sandbox-survival-e2e` — gateway restart recovery
        - `hermes-e2e` — Hermes agent onboard + inference
        - `rebuild-openclaw-e2e` — workspace state survives rebuild

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=cloud-e2e,sandbox-survival-e2e,hermes-e2e,rebuild-openclaw-e2e
        ```

    - path: "Dockerfile.base"
      instructions: *e2e-dockerfile

    - path: "nemoclaw-blueprint/scripts/http-proxy-fix.js"
      instructions: |
        This file is the L7 proxy rewrite script. Changes affect all
        inference routing through the proxy. FORWARD-mode path needs
        manual validation until a dedicated forward-proxy-e2e exists.

        **E2E test recommendation:**
        - `cloud-e2e` — full inference through the proxy chain
        - `inference-routing-e2e` — credential isolation + error classification

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=cloud-e2e,inference-routing-e2e
        ```

    - path: "src/lib/onboard.ts"
      instructions: |
        This file contains core onboarding logic. Changes here affect
        the full sandbox creation and configuration flow.

        **E2E test recommendation:**
        - `cloud-e2e` — full onboard + cloud inference
        - `sandbox-operations-e2e` — multi-sandbox lifecycle
        - `rebuild-openclaw-e2e` — workspace state survives rebuild
        - `messaging-compatible-endpoint-e2e` — Telegram + compatible endpoint
          inference.local regression

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=cloud-e2e,sandbox-operations-e2e,rebuild-openclaw-e2e,messaging-compatible-endpoint-e2e
        ```

    - path: "src/nemoclaw.ts"
      instructions: |
        This file contains CLI dispatch, status, recovery, and connect
        functions. Changes affect sandbox lifecycle commands.

        **E2E test recommendation:**
        - `sandbox-survival-e2e` — gateway restart recovery
        - `sandbox-operations-e2e` — process recovery after gateway kill

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=sandbox-survival-e2e,sandbox-operations-e2e
        ```

    - path: "src/lib/cluster-image-patch.ts"
      instructions: &e2e-overlayfs |
        This file handles Docker 26+ overlayfs compatibility. Changes
        are only testable under real Docker + K3s execution.

        **E2E test recommendation:**
        - `overlayfs-autofix-e2e` — Docker 26+ nested-mount auto-fix

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=overlayfs-autofix-e2e
        ```

    - path: "src/lib/preflight.ts"
      instructions: *e2e-overlayfs

    - path: "src/lib/deploy.ts"
      instructions: |
        This file contains deployment lifecycle logic (start/stop,
        cloudflared tunnel, uninstall).

        **E2E test recommendation:**
        - `deployment-services-e2e` — backup/restore, start/stop, uninstall

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=deployment-services-e2e
        ```

    - path: "src/lib/sandbox-state.ts"
      instructions: |
        This file manages sandbox state (backup, restore, rebuild,
        snapshot). Changes affect data persistence across sandbox
        lifecycle operations.

        **E2E test recommendation:**
        - `snapshot-commands-e2e` — snapshot create/list/restore lifecycle
        - `rebuild-openclaw-e2e` — workspace state survives rebuild

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=snapshot-commands-e2e,rebuild-openclaw-e2e
        ```

    - path: "src/lib/shields*.ts"
      instructions: |
        These files control shields down/up, config mutability, audit
        trail, and auto-restore timer.

        **E2E test recommendation:**
        - `shields-config-e2e` — shields lifecycle + config get/set/rotate

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=shields-config-e2e
        ```

    - path: "agents/hermes/**"
      instructions: |
        This directory contains the Hermes agent. Changes affect
        multi-agent onboarding, health probes, and inference routing.

        **E2E test recommendation:**
        - `hermes-e2e` — Hermes onboard + health probe + live inference
        - `rebuild-hermes-e2e` — Hermes upgrade path

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=hermes-e2e,rebuild-hermes-e2e
        ```

    - path: "nemoclaw-blueprint/policies/**"
      instructions: |
        This directory contains network policy definitions and presets.
        Changes affect sandbox egress rules and SSRF filtering.

        **E2E test recommendation:**
        - `network-policy-e2e` — deny-by-default, whitelist, hot-reload, SSRF

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=network-policy-e2e
        ```

    - path: "test/e2e/test-issue-2478-crash-loop-recovery.sh"
      instructions: |
        STAYS_IN_PR_UNTIL_SHIP — long-running soak test for the gateway
        recovery preload chain hardening (issue #2478). Removed in the
        same commit that drops the test file before merge.

        **E2E test recommendation:**
        - `issue-2478-crash-loop-recovery-e2e` — gateway recovery preload
          chain hardening soak

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=issue-2478-crash-loop-recovery-e2e
        ```

    # ── Split cloud-experimental tests (#2644) ──────────────────
    - path: "test/e2e/test-cloud-onboard-e2e.sh"
      instructions: &e2e-cloud-onboard |
        This script tests the public installer flow, Landlock read-only
        enforcement, API key leak detection, and inference.local HTTPS.

        **E2E test recommendation:**
        - `cloud-onboard-e2e` — public installer + sandbox health + security

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=cloud-onboard-e2e
        ```

    - path: "test/e2e/e2e-cloud-experimental/checks/**"
      instructions: *e2e-cloud-onboard

    - path: "test/e2e/test-cloud-inference-e2e.sh"
      instructions: &e2e-cloud-inference |
        This script tests live chat via inference.local and validates
        the skill filesystem layout inside the sandbox.

        **E2E test recommendation:**
        - `cloud-inference-e2e` — live cloud inference + skill filesystem

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=cloud-inference-e2e
        ```

    - path: "test/e2e/test-skill-agent-e2e.sh"
      instructions: &e2e-skill-agent |
        This script tests skill injection into the sandbox and verifies
        the agent reads the skill and returns a verification token.

        **E2E test recommendation:**
        - `skill-agent-e2e` — skill injection + agent verification

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=skill-agent-e2e
        ```

    - path: "test/e2e/e2e-cloud-experimental/features/**"
      instructions: *e2e-skill-agent

    - path: "test/e2e/test-docs-validation.sh"
      instructions: &e2e-docs-validation |
        This script validates CLI/docs parity (nemoclaw --help vs
        commands.md) and markdown link resolution.

        **E2E test recommendation:**
        - `docs-validation-e2e` — CLI/docs parity + link validation

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=docs-validation-e2e
        ```

    - path: "test/e2e/e2e-cloud-experimental/check-docs.sh"
      instructions: *e2e-docs-validation

    - path: "docs/reference/commands.md"
      instructions: *e2e-docs-validation

    - path: "test/e2e/test-messaging-compatible-endpoint.sh"
      instructions: |
        This script validates the Telegram + OpenAI-compatible endpoint
        regression path with a local mock endpoint. Changes here affect
        the hermetic coverage for managed inference.local routing from
        messaging-triggered agent turns.

        **E2E test recommendation:**
        - `messaging-compatible-endpoint-e2e` — Telegram + compatible
          endpoint inference.local routing

        To run selectively:
        ```
        gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=messaging-compatible-endpoint-e2e
        ```

    - path: ".github/workflows/nightly-e2e.yaml"
      instructions: |
        This is the nightly E2E workflow definition. Changes here affect
        which tests run and how they are triggered.

        If a new E2E job is added, verify a corresponding
        `path_instructions` entry exists in `.coderabbit.yaml` for the
        source files it covers. The cross-validation test in
        `test/validate-e2e-coverage.test.ts` checks this automatically.

        If a job is renamed or removed, update the corresponding
        `.coderabbit.yaml` path_instructions entries and the
        `notify-on-failure` needs list.
chat:
  auto_reply: true