# Repository settings

> Page: https://docs.plotwork.dev/repository-settings. Index of every page: https://docs.plotwork.dev/llms.txt

Keep how your team draws in one file, `plotwork.config.json`, at the root of the repository: defaults for the header options a diagram leaves out, style rules that CI enforces, the organisation whose brand hosted calls use, and the diagrams made from files of the repository. The command line, the GitHub Action and the local MCP server read the file; a hosted agent passes it as the `settings` argument.

## TL;DR

| Question | Answer |
|---|---|
| Where does the file go? | `plotwork.config.json` at the repository root, or `.plotwork/config.json`. Plotwork looks in the diagram's folder (or the working folder) and each folder above it, up to the repository root. |
| What can it hold? | `defaults` for header options, `rules` that CI checks, `brand` naming an organisation, and `sources`, the diagrams made from files (see [Diagrams as code](https://docs.plotwork.dev/diagrams-as-code.md)). Every section is optional. |
| Does a diagram's header still win? | Yes. A default fills only an option the header does not write. |
| Can my editor complete it? | Yes. Add `"$schema": "https://docs.plotwork.dev/schemas/plotwork.config.json"`. |
| What fails CI? | A broken rule, unless the rule says `"level": "warning"`. Defaults never fail anything. |
| Which plan? | The file is free on every plan and needs no account. Saving rules in an organisation, and a brand, are part of Pro. |
| Is anything sent? | Not by default. The file is read on the machine that runs Plotwork. Its brand colors are never in it: `brand` is only a name. |

## 1. Write the file

```json
{
  "$schema": "https://docs.plotwork.dev/schemas/plotwork.config.json",
  "defaults": {
    "icons": "auto",
    "direction": "right",
    "legend": "off",
    "theme": "light",
    "embedSource": true,
    "kinds": {
      "mindmap": {
        "layout": "radial"
      },
      "tree": {
        "style": "org"
      }
    }
  },
  "rules": {
    "requireDescription": true,
    "ids": {
      "pattern": "^[a-z][a-z0-9_]*$",
      "hint": "Use snake_case ids."
    },
    "icons": [
      {
        "label": "postgres|mysql",
        "use": [
          "aws:rds",
          "simple:postgresql",
          "simple:mysql"
        ]
      }
    ],
    "tones": [
      {
        "types": [
          "database"
        ],
        "allow": [
          "green",
          "neutral"
        ]
      }
    ]
  },
  "brand": {
    "organization": "acme"
  }
}
```

A file that does not check is reported with its line and column (S100), and nothing is drawn or checked with it.

## 2. Defaults

A default fills a header option the diagram leaves out. The header of a diagram always wins, and a default a kind's header does not take is left out for that kind.

| Field | What it sets | Where it applies |
|---|---|---|
| `icons` | `icons=auto` or `icons=off`: whether an item with no `icon=` gets the icon its label names. | Every kind whose header takes `icons=` |
| `direction` | `direction=` (`auto`, `right`, `down`, `left`, `up`). | Every kind whose header takes the value |
| `legend` | `legend=on` or `legend=off`. | Flow |
| `animate`, `numbered` | `animate=` and `numbered=`, `on` or `off`. | The kinds that take them |
| `kinds` | Header options for one kind, such as `{ "mindmap": { "layout": "radial" } }`. A value the kind refuses is left out with warning S200. | That kind |
| `theme` | The color scheme a single picture is drawn in: `light`, `dark` or `auto`. | The command line's `render` |
| `schemes` | The pictures written beside a diagram: `light-and-dark` (the default) writes a light and a dark SVG; `auto` writes one SVG that follows the reader's light or dark setting, which GitHub shows right in dark mode. A source of `sources` can set its own. | The command line's `sync` and `generate`, the GitHub Action's `sync` and `generate`, and the `sync_markdown` tool |
| `embedSource` | Whether a saved SVG carries its source. | The command line's `render`, the GitHub Action's `render`, and the drawing tools (true turns `embedSource` on). Never publishing: a published picture carries its source only when the call asks. |

The pictures, the source an SVG carries, and a drawing's view link include the defaults, so a picture reads back the same without the file. A change to the defaults makes the pictures under every diagram fence stale, and `sync` redraws them.

## 3. Rules

Rules are checked by `plotwork check`, by the GitHub Action's `check` and `validate`, and by the drawing tools, which return a broken rule as a warning and never stop a drawing.

| Field | What it checks | Finding |
|---|---|---|
| `requireTitle` | Every diagram has a title in its header. | R207 |
| `requireDescription` | Every diagram has `desc=` in its header, the text a screen reader announces. | R200 |
| `maxNodes` | No diagram has more nodes than this. | R201 |
| `forbidKinds` | No diagram is of these kinds. | R202 |
| `ids` | Every node id matches `pattern`. | R203 |
| `labels` | Every node label matches `pattern`. | R204 |
| `icons` | Every node whose label matches `label` (case ignored) draws one of the icons in `use`. `aws:*` accepts any icon of a set. | R205 |
| `tones` | Nodes of `types` (or every node) take only the tones in `allow`, or none of those in `forbid`. | R206 |
| `level` | At the top of `rules`, the level of every rule; on a rule, its own. `error` (the default) or `warning`. | |
| `kinds` | On a naming, icon or tone rule: only diagrams of these kinds. | |
| `hint` | On a naming, icon or tone rule: what to tell the author. | |

A pattern is a JavaScript regular expression without the slashes. One that repeats a group that itself repeats, such as `(a+)+`, or uses a back reference, is refused (R101), because it can take too long to match. An icon must be one Plotwork bundles; find its name with `npx @buun_group/plotwork icons postgres`.

Node rules look at the parts each kind calls a node: the nodes of a flow, the actors of a sequence, the tables of a schema, the elements of a C4 view, the classes of a class diagram (never asked for an icon), the states of a state diagram, the blocks of a layered architecture, the lanes and items of a swimlane, the topics of a mind map, and the entries of a tree. A kind without nodes, such as a chart or a timeline, is held to the rules about the whole diagram only. A mind map topic and a tree entry have no id, so an `ids` rule passes them.

## 4. Brand

`brand.organization` names the organisation (its slug or id) whose saved brand colors hosted calls use. It takes effect when the caller is a member of that organisation and its owner's plan includes brand themes; otherwise the call draws as it would without it. The file never holds colors: a brand is saved in the organisation by its owner or an admin. See [Brand themes](https://docs.plotwork.dev/brand-themes.md).

## 5. Sources

`sources` lists the diagrams made from files of the repository: for each, the files (`from`), their `format`, and where the diagram goes (`out`). `plotwork generate` and the Action's `command: generate` read it; every other command leaves it alone. The fields, the overrides file each diagram may have, and the workflows are in [Diagrams as code](https://docs.plotwork.dev/diagrams-as-code.md).

## 6. Where the file is read

| Host | How it gets the settings |
|---|---|
| Command line | Every command reads the file from the diagram's folder up to the repository root. `--config <file>` or `PLOTWORK_CONFIG` names another. `check` needs a `rules` section. |
| GitHub Action | Reads one settings file per run: the first found from `working-directory` up to the repository root. A settings file in a subfolder is not read; run the Action once per folder, with `working-directory`, if folders need their own. `config` names another file, or `off` reads none. |
| Local MCP server | Reads the file once at start, from the folder it starts in up to the repository root, or the file `PLOTWORK_CONFIG` names, and gives it to every drawing tool whose call passes no `settings`. |
| Hosted MCP server and REST API | Cannot read a repository. An agent reads the file and passes it as `settings` to `draw_diagram`, `validate_diagram`, `render_diagram`, `outline_diagram`, `edit_diagram`, `draw_from_pattern`, `convert_mermaid`, `sync_markdown` and `publish_diagram`, so a published picture follows the defaults too. Settings that do not check are refused with the path of each problem. A call made with an organisation's API key also gets the organisation's saved rules as warnings, unless it brings rules of its own. |

## 7. Check in CI

```bash
npx @buun_group/plotwork check docs README.md
```

`check` reads every Markdown and `.diagram` file the words name, writes the defaults into each header, and checks the rules. It exits with 1 when a rule at level error is broken or a diagram has an error, and with 2 when there are no rules or the settings do not check.

```yaml
- uses: actions/checkout@v7
- uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.14
  with:
    command: check
```

The samples pin the latest release of the Action by its commit. `@v1` becomes available at the first stable release.

The Action finds `plotwork.config.json` by itself. Every finding is an annotation on its line of the pull request: an error for a rule at level error, a warning otherwise.

## 8. Share rules across repositories

On Pro, an owner or admin saves rules in the organisation with [`PUT /orgs/{org}/style-rules`](https://docs.plotwork.dev/api/put-orgs-org-style-rules.md), and CI in every repository applies the same ones with an organisation API key. The saved rules take the fields of the `rules` section, with `"version": 1`.

```yaml
- uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.14
  with:
    command: check
    rules-org: acme
  env:
    PLOTWORK_API_KEY: ${{ secrets.PLOTWORK_API_KEY }}
```

An agent connected to the hosted MCP server gets the same rules back as warnings when it calls with the organisation's key, or as a member whose `settings` name the organisation in `brand.organization`. On your machine, `npx @buun_group/plotwork check docs --org acme` with `PLOTWORK_API_KEY` set does the same. The organisation's rules replace the file's rules; the file's defaults still apply. The key is never printed. If the owner moves to Free, the saved rules are kept but CI is told they no longer apply.

## 9. Privacy

The file stays where it is: Plotwork reads it on the machine that runs the command line, the Action or the local server, and fetches nothing it names. Settings an agent passes to a hosted tool are worked on in memory with the diagram and are not stored. Rules saved in an organisation are stored as the text typed, with who saved them and when. See the [privacy policy](https://docs.plotwork.dev/privacy-policy.md).

## See also

| Doc | Why |
|---|---|
| [Keep diagrams in sync in CI](https://docs.plotwork.dev/diagrams-in-ci.md) | The GitHub Action's other inputs, and checking that pictures are up to date |
| [Diagrams as code](https://docs.plotwork.dev/diagrams-as-code.md) | The `sources` section, overrides, and drift |
| [Brand themes](https://docs.plotwork.dev/brand-themes.md) | What a brand changes, and how an organisation saves one |
| [Organisations](https://docs.plotwork.dev/organisations.md) | Roles, members and organisation API keys |
| [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md) | The header options the defaults fill |
| [Privacy policy](https://docs.plotwork.dev/privacy-policy.md) | What is stored about an organisation and its rules |