# Advanced Configuration

Kanbn will search for a JSON or YAML configuration file in the root of the directory where it is initialised. The configuration file should be called `kanbn.json` or `kanbn.yml`.

If such a file is found, then project options (which are normally saved as YAML front matter in the index file) will instead be saved into this file.

If any project options are added to the index file, then the next time Kanbn writes to the index the options will be moved into the configuration file.

_Note: in future, it might be possible to split project options between the index and configuration files, but for now configuration must be saved inside only one of these files._

This applies to the **main board**. In a workspace with [several boards](multiple-boards.md), a secondary board's own options always live in that board file's front matter, and a board-local operation never writes to the configuration file.

_Note: Kanbn rewrites whichever file holds the project options every time it saves them (`kanbn add`, `kanbn move`, `kanbn sort --save`, `kanbn validate --save`, and so on). The YAML is regenerated, so formatting and comments in that file are not preserved._

## Configuring default locations

By default, Kanbn will store everything inside the `.kanbn` directory inside your workspace. The index file will be called `index.md` and tasks will be stored inside `.kanbn/tasks/`.

However, these paths can be configured by adding the following optional fields to your `kanbn.json` / `kanbn.yml` file:

```json
{
  "mainFolder": "custom-kanbn-folder",
  "indexFile": "custom-index.md",
  "taskFolder": "custom-task-folder",
  "archiveFolder": "custom-archive-folder"
}
```
```yaml
mainFolder: custom-kanbn-folder
indexFile: custom-index.md
taskFolder: custom-task-folder
archiveFolder: custom-archive-folder
```

_Note: these options must go inside the configuration file in the root of your workspace. If they're added to the index file they will have no effect._

### `mainFolder`

This will rename the main folder where everything is stored. By default this is `.kanbn`.

### `indexFile`

This will rename the index file. By default this is `index.md`. It is relative to the main folder.

### `taskFolder`

This will rename the folder where tasks are stored. By default this is `tasks`. It is relative to the main folder.

### `archiveFolder`

This will rename the archive folder where archived tasks are stored. By default this is `archive`. It is relative to the main folder.

## Multiple boards

Two more workspace-scoped options control [multiple boards](multiple-boards.md): `defaultBoard` names the board that commands target when `-b` isn't given, and `boards` controls discovery, display order and per-board options.

```yaml
defaultBoard: design
boards:
  exclude:
    - notes.md
  order:
    - index
    - design
  design:
    hiddenColumns:
      - Ideas
```

## Contributors

`contributors` is workspace-scoped too: an optional list of the people who work on this workspace, used to canonicalise `assigned` and comment `author` values and to answer "who is the current user?".

```yaml
contributors:
  - gordon
  - name: dave
    email: dave@example.com
    aliases:
      - Dave Smith
```

It is advisory — nothing is ever validated against it. See [Contributors](contributors.md).

## Actions

`actions` is a list of rules that fire when a task changes — "when this enters In Progress, assign it to me and tag it active". Unlike `contributors` it is **board-scoped**: declared in a configuration file it applies to every board, and declared in a board's front matter it applies to that board alone.

```yaml
actions:
  - name: start-work
    on: task.moved
    when:
      toColumn: In Progress
    then:
      - assign: '@me'
      - addTag: active
```

Rules are declarative — Kanbn never executes anything a workspace supplies — and nothing a rule writes can fire another rule. `--no-actions` on any mutating command, or `KANBN_NO_ACTIONS=1`, steps around a rule that is misbehaving. `actionsFile` moves a long rule set out of front matter and into a file of its own. See [Actions](actions.md).

Note that `indexFile` also sets the **main board's slug**: with `indexFile: board.md`, the main board's slug is `board`, and `main` / `default` still resolve to it.

Where a configuration file exists, everything in it is inherited by every board — it is workspace-level by construction, so a board-scoped option declared there is a deliberate statement about all boards. Where there is no configuration file, the workspace options live in the main board's front matter, and only the workspace-scoped ones propagate; `startedColumns`, `views` and the rest stay with the main board.