Your docs

Configuration

Every setting, where it lives, and how changes apply.

The config file

Settings live in ~/.config/planner/config.json (or $XDG_CONFIG_HOME/planner/config.json). The settings page, planner config and you can all edit it.

Only the keys you change are needed. Everything else is the default.
Changes apply by themselves. A running Planner notices the file changed and rescans; never restart it.
Errors never wipe your setup. A file with an error is not applied: Planner keeps the last good settings, shows a warning in the sidebar, and planner config check says what is wrong.
It has a schema. The file names its JSON schema in $schema, so editors and agents can check it as they write. planner config schema prints it.
--root and --port on the command line apply to one run only and are never saved.

A typical file:

{
  "$schema": "https://raw.githubusercontent.com/limyuquan/planner/main/schema/config.schema.json",
  "folders": [
    { "name": "work", "path": "~/code/work/.agents/docs", "icon": "🏢" },
    { "name": "side", "path": "~/code/side-project/plans", "statusFolders": null, "plansFolder": "" }
  ],
  "collections": [{ "label": "Weekly", "path": "weekly/*/*.html" }],
  "hotkeys": { "closeTab": ["Alt+Q"] },
  "taskIcons": { "work:search-rewrite": "🔎" }
}

Reference

Key	Default	Meaning
`folders`	`[]`	Docs folders to read; see below
`statusFolders`	`{"active":"active","done":"done"}`	Folders holding active and finished tasks; `null` if tasks sit directly in the docs folder
`plansFolder`	`"plans"`	Folder inside each task holding its plans; `""` for the task folder itself
`phasePattern`	`^phase-(?<num>\d+[a-z]*)-(?<slug>.+)$`	Phase folder names; `(?<num>…)` is the phase number, `(?<slug>…)` its name
`fileTypes`	`["html","md"]`	Extensions to show, without the dot
`groups`	Research → `research/`, HTML only	Extra folders in each task with their own section; see below
`collections`	`[]`	Docs outside any task, by path pattern; see below
`docTypes`	plan, eli5, recap, md, …	Badges by file name; see below
`hotkeys`	see Keyboard shortcuts	Shortcuts by action; `[]` turns one off
`taskIcons`	`{}`	Icons for tasks, by `"<folder>:<task>"`
`port`	`4173`	Port to listen on

Each folder is { "name", "path" }, with an optional icon and any layout key to override the shared one for that folder only (statusFolders, plansFolder, phasePattern, fileTypes, groups, collections).

name: lowercase letters, digits and dashes, unique. It shows in the sidebar and in links to the folder's docs.
path: absolute, or starting with ~ for your home folder. It must exist.

groups

Each group is { "label", "folder" }, with an optional fileTypes list (default: fileTypes).

{ "groups": [{ "label": "Research", "folder": "research", "fileTypes": ["html"] }] }

collections

Each collection is { "label", "path" }, where path is a pattern inside the docs folder (* matches one name). Also newestFirst (default true; otherwise sorted by path) and notify (default false: no notification for new ones).

{ "collections": [{ "label": "Weekly", "path": "weekly/*/*.html", "notify": false }] }

doc types

Each type is { "id", "label", "match", "color" }, with an optional icon. match is a file name pattern; color is one of grey, violet, blue, teal, green, amber, orange, pink, red. The first match wins, and the order is the reading order.

{
  "docTypes": [
    { "id": "plan", "label": "plan", "match": "plan.html", "color": "violet", "icon": "📐" },
    { "id": "md", "label": "md", "match": "*.md", "color": "grey" }
  ]
}

Giving docTypes replaces the whole default list, so include every type you want.

Icons

An icon is an emoji or a short symbol. Set them on doc types (shown in badges), on folders (shown in their sidebar section), and on tasks with taskIcons or the ☺ on a task row.

Older config files

Config files from before Planner read several folders have a single "root"; it is read as one folder named after the last part of its path, and links stay the same. Files in ~/.config/plan-dashboard/ are still used while there is no ~/.config/planner/config.json.