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

# charter.yaml Reference

> Configure Charter's policy, MCP allowlist, and behavior via charter.yaml.

`charter.yaml` is Charter's repo-root configuration file. It is optional — Charter still runs with built-in defaults when the file is absent. In v1 it exposes two configuration surfaces: `policy` for score gating and `mcp.trustedRemotes` for reviewed remote MCP hosts.

**File location:** repo root. Auto-discovered by all Charter commands.

## Full example

```yaml theme={null}
# yaml-language-server: $schema=https://use-charter.dev/schema/charter.schema.json
policy:
  profile: standard    # standard (80), strict (90), or relaxed (60)
  threshold: 85        # optional: overrides the profile's default threshold

mcp:
  trustedRemotes:
    - "api.your-internal-tool.com"
    - "mcp.your-company.com"
```

The first line is optional but recommended: it points editors (via the YAML Language Server used by VS Code, Neovim, and others) at Charter's published schema for inline validation and autocomplete. `charter init` adds it for you.

## Fields

<ResponseField name="policy.profile" type="string">
  Named threshold preset. Accepted values:

  | Value      | Threshold | When to use                            |
  | ---------- | --------- | -------------------------------------- |
  | `relaxed`  | 60        | Repos still ramping up agent-readiness |
  | `standard` | 80        | Default for most repos                 |
  | `strict`   | 90        | Security-sensitive or production repos |

  Default: `standard`
</ResponseField>

<ResponseField name="policy.threshold" type="integer">
  Explicit numeric threshold. Accepted range: `0`–`100`.

  Overrides the default threshold for the selected `policy.profile`. Use this when you want an exact gate that doesn't map cleanly to the named profiles (for example, `85`).
</ResponseField>

<ResponseField name="mcp.trustedRemotes" type="string[]">
  List of remote MCP server hostnames to add to the trusted allowlist for `AE-MCP-002`.

  Entries are hostnames, not full URLs. This repo-level list is combined with Charter's built-in catalog of known vendor-operated hosts. Local origins (`localhost`, `127.0.0.1`) are always exempt and do not need to be listed.
</ResponseField>

## Threshold precedence

<Note>
  When multiple threshold sources are present, Charter applies them in this order:

  ```
  --threshold flag  >  policy.threshold  >  policy.profile default  >  built-in default (80)
  ```

  If you set both `profile` and `threshold`, the `threshold` value wins. The `profile` label becomes documentation only.
</Note>

Example: a CLI invocation always wins over the repo config:

```bash theme={null}
charter doctor --threshold 95
```

This gates at 95 regardless of what `charter.yaml` says, without modifying the file.

## Validation

Charter fails fast on invalid configuration:

* Unknown `policy.profile` values → error at startup
* `policy.threshold` outside `0..100` → error at startup
* Malformed YAML → error at startup

## Schema

<Tip>
  The full JSON Schema is published at **`https://use-charter.dev/schema/charter.schema.json`**. Reference it with the `# yaml-language-server: $schema=…` header shown above for editor validation and autocomplete. Source: `web/public/schema/charter.schema.json`.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Policy Profiles" icon="adjustments-horizontal" href="/docs/config/policy-profiles">
    The named threshold presets and how precedence resolves.
  </Card>

  <Card title="GitHub Action" icon="puzzle" href="/docs/ci/github-action">
    How the action reads `charter.yaml` policy in CI.
  </Card>

  <Card title="Investigate MCP Findings" icon="search" href="/docs/how-to/investigate-mcp-findings">
    Resolve the rules that `mcp.trustedRemotes` governs.
  </Card>

  <Card title="MCP Safety Model" icon="plug" href="/docs/concepts/mcp-safety-model">
    Why the allowlist exists and what it protects against.
  </Card>
</CardGroup>