> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diffraction.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Repository configuration

> Define review behavior in a versioned diffraction.yml file.

Place `diffraction.yml` at the root of the repository being reviewed. Commands,
routes, viewports, budgets, and review rules belong in this file. Credentials
belong in secret stores; the file may contain secret reference names only.

## Starting configuration

This example assumes a pnpm web application with `build` and `start` scripts.
Adapt its commands, route, and checkpoint to your application before running it.
The score scale and budget below are example choices for the repository owner.

```yaml diffraction.yml theme={"theme":"css-variables"}
version: 1
app:
  install: pnpm install --frozen-lockfile
  build: pnpm build
  start: pnpm start --port 3000
  port: 3000
  readyUrl: http://127.0.0.1:3000
  workingDirectory: .
review:
  mode: standard
  scoreScale: 5
  importantRoutes: [/]
  flows:
    - name: Open the homepage
      route: /
      objective: Verify the main entry point remains usable.
      checkpoints:
        - The primary navigation is visible and usable.
  browsers: [chromium, firefox]
  viewports:
    - name: desktop
      width: 1440
      height: 900
    - name: mobile
      width: 390
      height: 844
  budgets:
    maxDurationMs: 600000
    maxSteps: 20
    maxAiTokens: 30000
    maxCostUsd: 0.9
    maxRetries: 1
    maxMediaDurationMs: 180000
```

## Review controls

| Field               | Purpose                                                                         |
| ------------------- | ------------------------------------------------------------------------------- |
| `review.mode`       | `budget`, `standard`, or `deep` review mode.                                    |
| `review.scoreScale` | Owner-selected scale of `3` or `5`.                                             |
| `review.flows`      | Named objectives and checkpoints; an optional `persona` adds context.           |
| `review.browsers`   | A nonempty selection of `chromium`, `firefox`, and `webkit`.                    |
| `review.viewports`  | Named dimensions; every selected browser/viewport pair needs its own recording. |
| `review.e2eCommand` | Optional command for existing end-to-end tests.                                 |
| `review.triggers`   | `alwaysRun` and `ignore` patterns used by UI-impact detection.                  |
| `review.brand`      | `rules`, `rulePaths`, and `referenceImages` supplied by the repository.         |

The current schema requires a positive `maxCostUsd` strictly below `1`.
Higher budgets are not supported by this schema. Runtime limits and available
provider configuration can constrain a run further.

## Network and secrets

`app.network` optionally requests `installationAllowedHosts`,
`runtimeAllowedHosts`, and `browserAllowedHosts`. Entries are public DNS hostnames,
with optional leading wildcards; URLs and IP addresses are rejected. Production
egress authorization uses the immutable base revision, so a pull request cannot
grant itself new network access through its own configuration.

`secrets.references` accepts uppercase secret names. Declaring a reference does
not provision a credential or authorize exposing production secrets to PR code.

The [configuration parser](https://github.com/jstEagle/Diffraction/blob/main/packages/config/src/index.ts)
is the authoritative field contract and rejects unknown properties.