# Configure

Selection files, switching plugin members on and off, local policies, and where to customise.

This page covers what you can change after an install, and the files that hold it.

> Ask the user before running any command on this page: each one changes how their agent or repository behaves.

## The selection file

A selection is a small JSON or YAML file naming the agent, the pinned catalog commit and the policies you picked. The builder writes one for you. The install command reads the same file. These are the fields it checks:

| Field | Meaning |
| --- | --- |
| `schema` | 2, the selection format version. |
| `client` | The agent the plugin is built for: claude-code, cursor, codex, copilot, devin, grok, goose, antigravity, openhands, kimi-code, factory-droid. The --client option on the command line overrides it. |
| `bundle.version` | The plugin's version, 1.0.0 from this site. |
| `catalog.source` | The chock-catalog repository. |
| `catalog.ref` | The pinned catalog commit. The plugin builds only from it. |
| `catalog.release` | Optional. A named catalog release over the commit. |
| `preset` | Optional. The preset the picks started from. |
| `policies` | One entry per picked policy: from (catalog), id, version and sha256. |

## Switch members on and off

These commands come from the engine. Their help appears here as the engine prints it.

### `chock bundle`

Switch a member of an installed plugin bundle on or off (bundle on|off <id>, bundle status)

Ask the user before running the commands below:

```text
usage: chock bundle [-h] {on,off,status} ...
```

The full options are on this page's HTML version, as the engine prints them.

### `chock enable`

Enable a policy by id

Ask the user before running the commands below:

```text
usage: chock enable [-h] [--repo REPO] policy_id
```

The full options are on this page's HTML version, as the engine prints them.

### `chock disable`

Disable a policy by id

Ask the user before running the commands below:

```text
usage: chock disable [-h] [--repo REPO] policy_id
```

The full options are on this page's HTML version, as the engine prints them.

From the engine docs: [docs/custom-policies.md](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/docs/custom-policies.md)

## 2. Add it to a selection

A schema-2 selection names it with `from: local` and a path relative to the selection file's own folder:

Ask the user before running the commands below:

```yaml
schema: 2
client: claude-code
bundle: {name: chock-guardrails, version: 1.0.0}
catalog: {source: https://github.com/open-coder-ai/chock-catalog, ref: <40-hex commit>}
policies:
  - {from: catalog, id: block-destructive-commands, version: <version>, sha256: <64-hex>}
  - {from: local, id: my-tf-destroy, path: .agents/policies/my-tf-destroy}
```

`sha256` is optional on a local entry; when present, the folder must hash to it. A selection with only local
entries needs no `catalog`. A link or a `#s=` code never carries a local policy: install refuses one, because only a
file has a folder beside it.

From the engine docs: [docs/baseline-policies.md](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/docs/baseline-policies.md)

## Customising a policy

Because an installed policy is yours, the first option is simply **edit it**. Change the regex, add
your own token formats, drop rules you disagree with. Re-copying from the catalog is an explicit act;
nothing does it behind your back.

Config overlays remain useful for things you want to change without touching the manifest:

Ask the user before running the commands below:

```yaml
policies:
  disabled: [block-no-verify]        # fully disable a policy
  overrides:
    scan-secrets:
      enforcement: advise            # downgrade to ambient rule only
    protect-main-branch:
      surfaces: [ambient-rule]       # or scope by explicit surfaces
```

- `disabled` removes the policy's compiled artifacts and git-hook wiring.
- `overrides.<id>.surfaces` becomes the `targets` passed to `compile_policy`.
- `overrides.<id>.enforcement: advise` is shorthand for `surfaces: [ambient-rule]`.
- A policy marked `mandatory: true` cannot be disabled; the CLI and `chock check` both
  refuse.

Some values are reachable from config without editing the manifest — `protect-main-branch` reads
`chock.defaults.protected_branches` via its `config_key`. Recompile after changing config, and
the compiled gate, the block message and the advisory text all follow.

Use `chock disable <id>` and `chock enable <id>` for ergonomic toggles, or
`chock status` to see the current state and coverage.

See [Authoring Policies](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/docs/authoring-policies.md) to write your own and
[Enforcement Surfaces](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/docs/enforcement-surfaces.md) for where each guard actually holds.

From the engine docs: [docs/adopting.md](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/docs/adopting.md)

## Golden rule: customize in these places only

| Want to change | Do this | Never edit |
| :--- | :--- | :--- |
| Protected branch names | `.chock/config.yaml` → `defaults.protected_branches` | the installed policy manifest |
| Disable a policy | `.chock/config.yaml` → `policies.disabled` | deleting the policy folder |
| Add a team policy | `chock new policy <id>` | editing an unrelated policy |
| Add a skill or adapter | `chock new` or `install-skills` | generated adapter files |

Customizing only in your own policies and config means `git merge upstream/main` stays clean.


---

Built from engine [5a4b6287a46e](https://github.com/open-coder-ai/chock/commit/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021) and catalog [1e60d211c1bb](https://github.com/open-coder-ai/chock-catalog/commit/1e60d211c1bb767152c6ab0167932da06ab3a10f).