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

# Override syntax

## File types

| Extension        | Behavior                                                         |
| ---------------- | ---------------------------------------------------------------- |
| `.yaml` / `.yml` | Parsed as a patch and merged into the current profile.           |
| `.js`            | Runs `main(profile)`; its return value becomes the next profile. |

Empty files are skipped with a warning. An unsupported extension fails configuration compilation.

## YAML modifiers

| Form               | Behavior                                                                |
| ------------------ | ----------------------------------------------------------------------- |
| `key: value`       | Replaces scalars, merges objects recursively, and replaces plain lists. |
| `key-start: [...]` | Inserts items at the beginning of an existing list.                     |
| `key-end: [...]`   | Appends items to an existing list.                                      |
| `key-merge: {...}` | Recursively merges a map without removing existing keys.                |
| `key-force: value` | Replaces the whole field without merging.                               |
| `<key-end>: value` | Treats a modifier-shaped field name literally.                          |

Known lists such as `rules`, `proxies`, and `proxy-groups` support `-start` and `-end`. When named proxies or groups collide, the last definition wins.

```yaml theme={null}
rules-start:
  - DOMAIN-SUFFIX,lan,DIRECT

rules-end:
  - DOMAIN-SUFFIX,example.com,PROXY

hosts-merge:
  router.local: 192.168.1.1

dns-force:
  enable: true
  nameserver:
    - https://dns.alidns.com/dns-query
```

## JavaScript

`main(profile)` may mutate and return `profile`, or return a new object. Returning `undefined`, an array, or a scalar makes that script fail; the previous profile is retained.

```js theme={null}
async function main(profile) {
  const response = await fetch("http://127.0.0.1:8080/rules.yaml");
  if (!response.ok) return profile;

  return deepMerge(profile, await response.yaml(), true);
}
```

### `deepMerge`

| JS form          | Behavior                                               |
| ---------------- | ------------------------------------------------------ |
| `key: value`     | Replaces a scalar or list; merges objects recursively. |
| `"+key": [...]`  | Inserts items at the beginning of a list.              |
| `"key+": [...]`  | Appends items to a list.                               |
| `"key!": {...}`  | Replaces the target field with an object.              |
| `"<key>": value` | Uses a literal field name.                             |

### Available APIs

| API                                          | Purpose                                |
| -------------------------------------------- | -------------------------------------- |
| `yaml.parse(text)` / `yaml.stringify(value)` | Convert YAML and objects.              |
| `deepMerge(target, patch, true)`             | Merge objects with override semantics. |
| `fetch(url, init?)`                          | Make an HTTP request.                  |
| `response.text()` / `json()` / `yaml()`      | Read a response body.                  |
| `console.log/info/warn/error/debug`          | Write to the adjacent `.log` file.     |
| `Buffer.from()`、`b64e()`、`b64d()`            | Convert UTF-8 and Base64 values.       |

<Warning>The embedded `fetch` supports `http://` only, not HTTPS. Importing an override file from a URL supports both HTTP and HTTPS.</Warning>

## Failures

| Situation                                     | Result                                                                             |
| --------------------------------------------- | ---------------------------------------------------------------------------------- |
| YAML parsing fails                            | The profile compilation fails.                                                     |
| JavaScript throws or returns an invalid value | That script is skipped, the previous profile is retained, and a warning is logged. |
| An age-encrypted profile                      | Override warnings and JS logs redact profile content.                              |

YumeBox then applies runtime constraints such as private provider paths, DNS defaults, and mode-specific patches. Enabling **Disable all overrides** in Root modes bypasses these runtime patches too.