Hosted diagrams and plans

Repository settings

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). 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

1{2  "$schema": "https://docs.plotwork.dev/schemas/plotwork.config.json",3  "defaults": {4    "icons": "auto",5    "direction": "right",6    "legend": "off",7    "theme": "light",8    "embedSource": true,9    "kinds": {10      "mindmap": {11        "layout": "radial"12      },13      "tree": {14        "style": "org"15      }16    }17  },18  "rules": {19    "requireDescription": true,20    "ids": {21      "pattern": "^[a-z][a-z0-9_]*$",22      "hint": "Use snake_case ids."23    },24    "icons": [25      {26        "label": "postgres|mysql",27        "use": [28          "aws:rds",29          "simple:postgresql",30          "simple:mysql"31        ]32      }33    ],34    "tones": [35      {36        "types": [37          "database"38        ],39        "allow": [40          "green",41          "neutral"42        ]43      }44    ]45  },46  "brand": {47    "organization": "acme"48  }49}

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.

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.

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

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.

1- uses: actions/checkout@v72- uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.143  with:4    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.

On Pro, an owner or admin saves rules in the organisation with PUT /orgs/{org}/style-rules, 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.

1- uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.142  with:3    command: check4    rules-org: acme5  env:6    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.

Doc	Why
Keep diagrams in sync in CI	The GitHub Action's other inputs, and checking that pictures are up to date
Diagrams as code	The `sources` section, overrides, and drift
Brand themes	What a brand changes, and how an organisation saves one
Organisations	Roles, members and organisation API keys
Writing diagrams	The header options the defaults fill
Privacy policy	What is stored about an organisation and its rules