@basementuniverse/kanbn 2.0.0 → 2.5.0

package/docs/index-structure.md

@@ -29,7 +29,57 @@ The project description should appear below the title. The description can be of
 
 Below the description there should be one or more level-2 headings. The 'Options' name is reserved for project options.
 
-All level-2 headings (except for 'Options') will be treated as columns. Columns should only contain a list of links to task markdown files.
+All level-2 headings (except for 'Options') will be treated as columns.
+
+## Column contents
+
+A column tracks a task when it contains a **markdown link** to that task's file:
+
+```markdown
+## Todo
+
+- [my-task](tasks/my-task.md)
+```
+
+That link is the only thing kanbn reads as a task. Any other line in a column - a bare title, a checkbox item, a note, a paragraph - is left exactly as you wrote it and ignored by every command:
+
+```markdown
+## Todo
+
+- [my-task](tasks/my-task.md)
+- remember to check the staging deploy
+- [ ] buy milk
+```
+
+These lines are **simple tasks**. They have no id, no metadata and no dates, they can't collide with a task of the same name, and they count towards nothing: not `kanbn status`, not workload, burndown, gantt or sprints. They are preserved when kanbn saves the board file, and stay in the column they were written in - though a line isn't anchored to the task above it, so sorting a column can move tasks around it.
+
+They are shown on the board in the default layout, dimmed, at the end of their column. Views leave them out: a view filters and sorts tasks, and a simple task has no fields to filter or sort on. They are left out of `kanbn board --json` for the same reason.
+
+### Working with simple tasks
+
+Four commands accept a simple task, addressed by its title - exactly, ignoring case, or slugified, so `"Buy milk"` and `buy-milk` both work. **A real task always wins**: kanbn only looks for a simple task when no task has that id, so a line whose title matches an existing task can only be edited by hand.
+
+| Command | Effect |
+| --- | --- |
+| `kanbn move "Buy milk" -c Done` | Moves the line to another column. `-b` moves it to another board |
+| `kanbn edit "Buy milk" ...` | **Promotes** it to a real task file, then edits it as normal |
+| `kanbn remove "Buy milk"` | Deletes the line. There is no file to delete and nothing to archive |
+| `kanbn task "Buy milk"` | Says which column it's in, and how to promote it |
+
+Promotion is one-way. The new task gets a file, an id, a `created` date as of the promotion and a `created` history event naming the column the line was in. There is no way back: a task carries metadata, comments and history that a line can't hold.
+
+Two lines with the same title on one board are two different lines, so a command naming one of them reports the ambiguity rather than guessing. Two lines with the same title on *different* boards are unrelated - a simple task belongs to the board file it's written in, and nothing else.
+
+Anything that isn't a single line of a list - a paragraph, a quote, a code block - is preserved just the same, but isn't a simple task: it isn't shown on the board, and no command will move, promote or remove it.
+
+`kanbn validate` lists them, so they can't hide. It reports two cases more loudly, because both mean a task silently isn't being tracked:
+
+- a line that looks like a task link with a typo in it, e.g. a missing closing bracket;
+- a line naming a task file that exists but isn't written as a link, e.g. `- my-task`.
+
+_Note: before version 2.2.0 a bare task id in a column (`- my-task`) was treated as a task reference. It no longer is - only links are. Run `kanbn validate` to find any, and write them as links._
+
+If a column references a task file that doesn't exist, kanbn skips that task and carries on rather than failing - this happens routinely when a board file and a task file arrive in different commits. `kanbn board` says how many tasks were skipped, and `kanbn validate` names them.
 
 ## Project options
 
@@ -37,7 +87,7 @@ The 'Options' heading should be followed by a code block containing YAML. The 'y
 
 Project options will be merged with YAML front-matter if any is present.
 
-*Note: when the index is saved, all project options will be placed into YAML front-matter. The 'Options' heading is still supported for backwards-compatibility.*
+_Note: when the index is saved, all project options will be placed into YAML front-matter. The 'Options' heading is still supported for backwards-compatibility._
 
 ```yaml
 hiddenColumns:
@@ -89,6 +139,23 @@ customFields:
     type: 'date'
 {customFieldName}Columns:
   - {Column name}
+contributors:
+  - gordon
+  - name: dave
+    displayName: Dave Smith
+    email: dave@example.com
+    aliases:
+      - Dave Smith
+    colour: '#7c5cff'
+actions:
+  - name: start-work
+    on: task.moved
+    when:
+      toColumn: In Progress
+    then:
+      - assign: '@me'
+      - addTag: active
+actionsFile: ""
 ```
 
 ### `hiddenColumns`
@@ -105,7 +172,7 @@ A list of column names. When a task is created in or dragged into one of these c
 
 A list of column names. When a task is created in or dragged into one of these columns, the task's `completed` date will be set to the current time, unless the task already has a `completed` date.
 
-Note that these columns control when the date is *written*. They don't decide whether a task counts as complete - that comes from the date itself. See [Task state](#task-state) below.
+Note that these columns control when the date is _written_. They don't decide whether a task counts as complete - that comes from the date itself. See [Task state](#task-state) below.
 
 ### `startedField`
 
@@ -130,10 +197,36 @@ customFields:
 
 Set to `false` to suppress hints and notices printed alongside normal output, such as the reminder shown when tasks have dates that don't match their column. Defaults to `true`. Hints are never shown when using `--json`.
 
+### `defaultBoard`
+
+The board that commands target when `-b` isn't given and `KANBN_BOARD` isn't set. Workspace-scoped: it belongs in the config file, or in the main board's front matter when there is no config file.
+
+See [multiple boards](multiple-boards.md).
+
+### `boards`
+
+Board discovery settings. `exclude` lists markdown files in the kanbn folder that aren't boards, `order` sets the display order for `kanbn boards`, and any other key is a board slug whose value is that board's options.
+
+```yaml
+boards:
+  exclude:
+    - notes.md
+  order:
+    - index
+    - design
+  design:
+    hiddenColumns:
+      - Ideas
+```
+
+Workspace-scoped. See [multiple boards](multiple-boards.md).
+
 ### `sprints`
 
 A list of sprints. Each sprint will have `start`, `name` and `description` properties.
 
+A board can declare its own `sprints` in its front matter, which **replaces** the workspace list for that board entirely. See [multiple boards](multiple-boards.md#per-board-sprints).
+
 Run `kanbn sprint --help` for more information.
 
 ### `defaultTaskWorkload`
@@ -179,13 +272,13 @@ progress
 {...customFields}
 ```
 
-*Note: referencing a variable that isn't in the list above (or a custom field that isn't declared in `customFields`) will print "Unable to build task template" instead of rendering the board.*
+_Note: referencing a variable that isn't in the list above (or a custom field that isn't declared in `customFields`) will print "Unable to build task template" instead of rendering the board._
 
 The default task template is `^+^_${overdue ? '^R' : ''}${name}^: ${created ? ('\\n^-^/' + created) : ''}`.
 
 This string can contain markup sequences. See [terminal-kit](https://github.com/cronvel/terminal-kit/blob/21607fb51749853dd9193c6aaf205b14c63b2768/doc/markup.md#markup) for markup reference.
 
-*Note: custom fields can also be interpolated into the task template, but only if they are defined in `customFields` (see below).*
+_Note: custom fields can also be interpolated into the task template, but only if they are defined in `customFields` (see below)._
 
 ### `dateFormat`
 
@@ -208,6 +301,7 @@ An array of custom metadata fields, where each field should have `name` and `typ
 Run `kanbn add --help`, `kanbn edit --help`, `kanbn find --help` and `kanbn sort --help` for more information.
 
 Valid types are:
+
 - `boolean`
 - `date`
 - `number`
@@ -227,8 +321,8 @@ If the custom field has `updateDate` set to `always`, the field will be updated
 
 Here's an example of how this could be used:
 
-* Assume we have added a column called `Testing`
-* In `index.md` (or `kanbn.json` / `kanbn.yml` if using a separate configuration file), we have:
+- Assume we have added a column called `Testing`
+- In `index.md` (or `kanbn.json` / `kanbn.yml` if using a separate configuration file), we have:
   ```
   customFields:
     - name: testedAt
@@ -237,16 +331,56 @@ Here's an example of how this could be used:
   testedAtColumns:
     - Testing
   ```
-* When a task is moved into the `Testing` column and the task doesn't already have a `testedAt` value in its metadata, this value will be automatically populated with the current date/time.
+- When a task is moved into the `Testing` column and the task doesn't already have a `testedAt` value in its metadata, this value will be automatically populated with the current date/time.
+
+### `contributors`
+
+An optional list of the people who work on this workspace. Each entry is either a bare name or an object with a required `name` and optional `displayName`, `email`, `aliases` and `colour`.
+
+`contributors` is **workspace-scoped**: like `customFields`, it belongs in `kanbn.json` / `kanbn.yml`, or in the main board's front matter when there is no configuration file, and every board inherits it. A secondary board that declares its own is reported by `kanbn validate` and ignored.
+
+Contributors are **advisory**. `assigned` and comment `author` remain free text and are never validated against the list, never rejected and never rewritten. What the list buys you is a canonical spelling for each person, an autocomplete in the interactive prompts, `@me` in filters, and `kanbn contributors --usage` to find the spellings already in use.
+
+See [Contributors](contributors.md) for the full description, and `kanbn contributors --help`.
+
+### `actions`
+
+A list of rules that fire when a task is created, moved, updated, commented on, archived, restored, deleted, started or completed. Each rule names an event (`on`), an optional condition (`when`), an optional set of related tasks to act on (`for`), and the verbs to apply (`then`).
+
+```yaml
+actions:
+  - name: start-work
+    on: task.moved
+    when:
+      toColumn: In Progress
+    then:
+      - assign: '@me'
+      - addTag: active
+      - removeTag: ready
+```
+
+`actions` is board-scoped: in a configuration file it applies to every board, and in a board's front matter it applies to that board alone. A board that declares its own replaces the inherited list rather than adding to it.
+
+Rules only fire during commands that change something, and nothing a rule writes ever fires another rule. See [Actions](actions.md) for the events, the verbs, the substitutions and the failure semantics.
+
+### `actionsFile`
+
+A path, relative to the `.kanbn` folder, of a file holding the same list of rules that `actions` would have held. For rule sets that have outgrown a board's front matter.
+
+```yaml
+actionsFile: actions/design.yml
+```
+
+Setting both `actions` and `actionsFile` on the same board is an error, and so is naming a file that doesn't exist or doesn't parse.
 
 ## Task state
 
 Whether a task has started or been completed is decided by its metadata dates, and nothing else:
 
-* a task has started if its `started` field is set (or whichever field `startedField` names);
-* a task is complete if its `completed` field is set (or whichever field `completedField` names).
+- a task has started if its `started` field is set (or whichever field `startedField` names);
+- a task is complete if its `completed` field is set (or whichever field `completedField` names).
 
-The column a task sits in doesn't make it started or complete. Columns listed in `startedColumns` and `completedColumns` cause those dates to be *written* when a task is moved through the CLI or the VSCode extension, but the dates are what everything else reads: `kanbn status`, `kanbn find`, progress, burndown charts and gantt charts.
+The column a task sits in doesn't make it started or complete. Columns listed in `startedColumns` and `completedColumns` cause those dates to be _written_ when a task is moved through the CLI or the VSCode extension, but the dates are what everything else reads: `kanbn status`, `kanbn find`, progress, burndown charts and gantt charts.
 
 This matters when a task is moved **outside** of kanbn - by editing the index file by hand, or through a git merge. No date is written in that case, so the task keeps whatever state its metadata already described. `kanbn validate` reports tasks whose dates and columns disagree, and `kanbn validate --fix` fills in the missing dates, taking them from the task's history where possible.
 

package/docs/index.md

@@ -9,6 +9,9 @@ To get started quickly, check out the [Quick Start](quick-start.md) guide.
 - [Quick Start](quick-start.md)
 - [Index Structure](index-structure.md) — the board file and all project options
 - [Task Structure](task-structure.md) — task files, metadata, sub-tasks, relations, comments and history
+- [Multiple Boards](multiple-boards.md) — several boards over one shared pool of tasks
+- [Contributors](contributors.md) — an optional list of who works on a workspace, and who "you" are
+- [Actions](actions.md) — declarative rules that fire when a task is created, moved, updated or finished
 - [Views](views.md) — custom board layouts, columns and lanes
 - [Filtering and Sorting](filtering-and-sorting.md) — the filter and sorter model shared by `find`, `sort` and views
 - [Advanced Configuration](advanced-configuration.md)
@@ -16,13 +19,14 @@ To get started quickly, check out the [Quick Start](quick-start.md) guide.
 
 ## Examples
 
-The [`example`](../example) directory contains ready-to-run boards:
+The [`example`](../example) directory contains ready-to-run workspaces:
 
 | Example | Demonstrates |
 | --- | --- |
 | [`example/basic`](../example/basic) | A typical board: columns, tags, workload, sprints |
 | [`example/views`](../example/views) | Views, lanes, filters and sorters |
-| [`example/advanced`](../example/advanced) | A `kanbn.yml` config file, custom fields, column sorting and a custom task template |
+| [`example/boards`](../example/boards) | Multiple boards over one shared pool of tasks, with per-board state fields |
+| [`example/advanced`](../example/advanced) | A `kanbn.yml` config file, custom fields, contributors, column sorting and a custom task template |
 
 Run any Kanbn command from inside one of those directories to try it out.
 

package/docs/multiple-boards.md

@@ -0,0 +1,259 @@
+# Multiple Boards
+
+A Kanbn workspace can hold more than one board. Every board is a markdown file directly inside the kanbn folder, in exactly the same format as `index.md`, and they all share one `tasks/` folder — so a single task can appear on several boards, in a different column on each.
+
+Multi-board support is opt-in. A workspace that never creates a second board behaves, and produces files, exactly as it always has.
+
+## Views or boards?
+
+> **A view is a lens; a board is a place.** A view re-arranges, filters and groups the tasks that are already on a board — it is read-only, and nothing you do to a view changes where a task lives. A board is somewhere tasks actually live: a task is added to it, moved between its columns, and removed from it. If you want to *look at* the same work differently, use a view. If you want to *track* the same work in a different workflow, use a board.
+
+See [Views](views.md) for the read-only option.
+
+## The main board
+
+`.kanbn/index.md` is the **main board**. Its slug is `index`, and `main` and `default` always resolve to it. If you have customised `indexFile` in your config file, the main board's slug is that filename without its extension, and `main` / `default` still resolve to it.
+
+The main board is the default target of every command, so nothing changes for existing workspaces or scripts.
+
+## Creating a board
+
+```bash
+kanbn init -b design -n "Design Pipeline" -d "Design work across the product" -c Ideas -c Designing -c "Signed Off"
+```
+
+That writes `.kanbn/design.md`:
+
+```markdown
+# Design Pipeline
+
+Design work across the product
+
+## Ideas
+
+## Designing
+
+## Signed Off
+```
+
+Board slugs are generated the same way task ids are, so they must be lowercase and hyphenated. A few slugs are reserved and rejected: `index`, `main`, `default`, and the names of your task and archive folders.
+
+Running `kanbn init -b design` again updates the board's name, description and columns, in the same way `kanbn init` does for the main board.
+
+A new board only picks up the default `startedColumns: [In Progress]` and `completedColumns: [Done]` if it actually has columns by those names — a board with its own workflow does not silently claim that "In Progress" started work and "Done" finished it.
+
+## Listing boards
+
+```bash
+kanbn boards
+```
+
+```
+2 boards:
+
+index (main board)
+  Main Project
+  4 columns, 12 tasks, 25% complete, last modified 2026-08-27T11:49:17.314Z
+
+design
+  Design Pipeline
+  Design work across the product
+  3 columns, 4 tasks, 50% complete, last modified 2026-08-27T11:50:34.602Z
+```
+
+`kanbn boards --tasks` shows the cross-board picture — every task that appears on more than one board, and the column it occupies on each. Add `--all` to include tasks that are only on one board.
+
+`kanbn boards --rename design ux --name "UX Pipeline"` renames a board, and `kanbn boards --delete design` deletes one. Deleting a board never deletes task files, but tasks that no other board references become untracked; if that would happen, they are listed and `-f` is required to go ahead.
+
+Both listings support `--json`.
+
+## Targeting a board
+
+Every board-scoped command takes `-b` / `--board`:
+
+```bash
+kanbn board -b design
+kanbn status -b design
+kanbn task build-tenant-settings-page -b design
+kanbn find -b design --tag Bug
+kanbn validate -b design
+```
+
+The target board is resolved in this order:
+
+1. `--board` / `-b`
+2. the `KANBN_BOARD` environment variable
+3. the `defaultBoard` option in your config file
+4. the main board
+
+There is deliberately no stateful "current board" — everything stays visible in your shell and in git-tracked markdown.
+
+## Tracked, untracked, and tracked elsewhere
+
+"Tracked" is workspace-scoped: a task is tracked if **any** board references it.
+
+```bash
+kanbn status -b design --untracked
+```
+
+reports two separate things:
+
+- `untrackedTasks` — task files that are on no board at all;
+- `tasksOnOtherBoards` — tasks that other boards track but this one doesn't, naming the board and column each one sits in. This is the useful half: it is the "what could I pull onto this board" list.
+
+Once a workspace has more than one board, `kanbn status` also reports a `board` field naming the board it applied to. A single-board workspace produces exactly the output it always has.
+
+`kanbn task <task-id>` lists the boards a task appears on, and the column it occupies on each, whenever there is more than one.
+
+`kanbn find --all-boards` searches every board, annotating each result with the board and column it occupies. Without the flag, `find` is scoped to the target board as it always has been.
+
+## Working with tasks across boards
+
+Every board-scoped command takes `-b`, so a task can be created, moved, commented on and removed on whichever board you mean:
+
+```bash
+kanbn add -n "Task" -b design -c Ideas
+kanbn move build-settings-page -b design -c Designing
+kanbn remove build-settings-page -b design
+kanbn edit build-settings-page -b design --tag Bug
+```
+
+`kanbn add -b` is repeatable, so one task can land on several boards at once. Each `-b` pairs with the `-c` in the same position; boards with no `-c` of their own use the first one given, and a board that hasn't got that column falls back to its first column with a notice:
+
+```bash
+kanbn add -n "Task" -b index -b design -b ops -c Todo -c Designing
+```
+
+With a *single* board an unknown column is still an error — the fallback only applies when several boards are named at once, where a column can legitimately exist on one and not another.
+
+### Adding, moving and removing membership
+
+- `kanbn move <task> -b design -c Designing` moves the task on the design board. If it isn't on that board yet, it is **added**, with a notice. `--no-add` turns that back into an error.
+  The main board never adds implicitly: moving an untracked task there is an error either way.
+- `kanbn remove <task> -b design --index` removes the task from the design board only. Boards own membership, so the task file and every other board are untouched.
+- Without `--index`, `remove` deletes the task file as well, and that is refused while another board still references it. `--all-boards` removes the task from every board and then deletes the file.
+- `kanbn rename <task>` rewrites the id on **every** board that references it, because the id is the file name.
+
+Membership changes are recorded in the task's history as `added` and `removed` events, so a board's history includes the task arriving and leaving. See [Task Structure](task-structure.md#history).
+
+### Archiving and restoring
+
+Archiving removes a task from every board and remembers where it was on each:
+
+```yaml
+column: In Progress          # the main board, as it always has been
+columns:                     # only written when the task was on more than one board
+  design: Designing
+  ops: Backlog
+```
+
+`kanbn restore <task>` puts it back on every board it was on, in the column it occupied on each. A board that has since been deleted, or a column that has since gone, is reported and skipped rather than failing the restore. `kanbn restore <task> -b design` restores to that board only.
+
+## Options and configuration
+
+Options resolve in layers when a board is loaded:
+
+```
+defaults  <  kanbn.yml / kanbn.json  <  boards.<slug> in config  <  board file front matter
+```
+
+Array options — `startedColumns`, `completedColumns`, `hiddenColumns`, `sprints`, `views` — **override** rather than merge. Element-wise merging of an ordered array has no predictable semantics.
+
+Some options describe the workspace rather than a single board:
+
+| Option | Scope |
+| --- | --- |
+| `hiddenColumns`, `startedColumns`, `completedColumns`, `startedField`, `completedField`, `columnSorting`, `views`, `taskTemplate`, `verbose` | Board |
+| `sprints` | Workspace, overridable per board |
+| `customFields` | Workspace — task files are shared, so a field defined on one board must parse on all |
+| `contributors` | Workspace — `assigned: gordon` has to mean the same person on every board that references the task |
+| `defaultTaskWorkload`, `taskWorkloadTags` | Workspace — workload is a property of the task, not the board |
+| `dateFormat` | Workspace only — dates should read identically everywhere |
+| `mainFolder`, `indexFile`, `taskFolder`, `archiveFolder`, `defaultBoard`, `boards` | Workspace only — layout, meaningless in a board file |
+
+A workspace-scoped option in a *secondary* board's front matter is ignored, because one shared task file has to parse identically for every board that references it.
+
+Where options are written:
+
+- **Main board** — unchanged. If a config file exists, options go there; otherwise they go into `index.md`'s front matter.
+- **Secondary boards** — board-scoped options are always written to that board file's front matter. A board-local operation never writes to the workspace config file.
+
+If you have no config file, the workspace options live in the main board's front matter, so loading any secondary board also reads `index.md`. That costs one extra file read per process, not per board.
+
+**Only workspace-scoped options are inherited from `index.md`'s front matter.** With no config file that file is doing double duty — it holds the workspace options *and* the main board's own board-scoped ones — so `startedColumns`, `completedColumns`, `hiddenColumns`, `views`, custom field column linkages and the rest stay with the main board. A secondary board that happens to share a column name with it does not silently pick up its behaviour; if you want those columns to mean the same thing on another board, declare them in that board's front matter.
+
+A `kanbn.yml` / `kanbn.json` config file is different: it is workspace-level by construction, so a board-scoped option declared there is a deliberate statement about every board, and is inherited.
+
+### Per-board state fields
+
+Because `started` and `completed` live on the shared task file, a board that needs its own notion of started or completed can point at different metadata fields:
+
+```markdown
+---
+startedField: designStartedAt
+completedField: designSignedOffAt
+startedColumns:
+  - Designing
+completedColumns:
+  - Signed Off
+---
+
+# Design Pipeline
+```
+
+Declare `designStartedAt` and `designSignedOffAt` once as workspace-scoped `customFields` of type `date`. The design board then stamps and reads its own fields, and the main board's `completed` can never leak into it. See [Index Structure](index-structure.md) for `customFields`.
+
+### Per-board sprints
+
+Sprints are workspace-level by default: a board reads the workspace list unless it declares its own `sprints` in its front matter, in which case that list **replaces** the workspace one entirely.
+
+`kanbn sprint -b design` appends to the workspace list, and says so, unless the design board has its own list — in which case it appends there, auto-named `Design Pipeline Sprint 2`. A board-local list is never created implicitly: forking is permanent and invisible in the CLI, so it stays a deliberate front-matter edit.
+
+The cost of forking is worth stating plainly: a board with its own list can no longer see workspace sprints at all, so `kanbn status -b design -s "Foundation Sprint"` will fail to find it.
+
+`--sprint` can't be combined with `--all-boards`, because sprint numbers and names are relative to one board's list.
+
+`kanbn burndown -b <slug>` on a board that declares no `startedColumns` errors rather than drawing an empty chart — a board with no notion of work in progress has nothing to burn down. Gantt charts don't use sprints at all, so they are unaffected.
+
+Note that a task on two boards contributes its workload to both boards' charts. That is correct for per-board reporting; it is only double counting if you add the charts together.
+
+### History and charts are board-scoped
+
+`kanbn history -b design` shows the events that happened on the design board, plus the ones that aren't board-scoped at all. Burndown datapoints are placed and annotated the same way, so activity on one board never puts markers on another board's chart.
+
+`progress` and `archived` events are never filtered: progress is a property of the task, and archiving removes a task from every board.
+
+### Validation
+
+`kanbn validate` reports multi-board problems as warnings once a workspace has more than one board:
+
+- a workspace-scoped option in a secondary board's front matter, which is ignored;
+- several boards stamping the same shared `completedField`, where whichever board is touched first silently owns that date for every board;
+- sprints out of chronological order, which the "current sprint" logic assumes;
+- a task on no board at all, or referenced by a board with no file behind it;
+- a task in two columns on the same board;
+- history events naming a board that has been deleted;
+- markdown files beside the boards that don't parse as one, and files excluded by `boards.exclude`.
+
+`kanbn validate --all-boards` validates every board and its tasks, rather than just the target board.
+
+### Board discovery
+
+Boards are discovered by globbing `*.md` directly inside the kanbn folder, so `tasks/` and `archive/` are excluded by construction. A file counts as a board if it parses as an index — that is, if it has an H1. Files that don't parse are ignored during ordinary commands and reported by `kanbn validate`.
+
+Where discovery isn't enough, the `boards` config key takes over:
+
+```yaml
+boards:
+  exclude:
+    - notes.md          # not a board, just a scratch file
+  order:                # display order for `kanbn boards`
+    - index
+    - design
+    - ops
+  design:               # options applied to the design board
+    hiddenColumns:
+      - Ideas
+```
+
+`exclude` and `order` are reserved; every other key is a board slug whose value is that board's options.

package/docs/quick-start.md

@@ -89,10 +89,30 @@ kanbn board -v by-assignee
 
 See [views](views.md) for columns, lanes, filters and sorters.
 
+## Multiple boards
+
+A workspace can hold more than one board, all sharing the same pool of tasks:
+
+```
+kanbn init -b design -n "Design Pipeline" -c Ideas -c Designing -c "Signed Off"
+kanbn boards
+```
+
+Every board-scoped command takes `-b`, so a task can sit in `In Progress` on the main board and `Designing` on the design board at the same time:
+
+```
+kanbn move my-new-task -b design -c Designing
+kanbn board -b design
+kanbn boards --tasks
+```
+
+See [multiple boards](multiple-boards.md) for membership, per-board options and per-board sprints.
+
 ## Next steps
 
 - [Index structure](index-structure.md) — project settings, tags and workload calculations
+- [Multiple boards](multiple-boards.md) — several boards over one shared pool of tasks
 - [Task structure](task-structure.md) — task metadata, sub-tasks, relations and comments
 - [Views](views.md) and [filtering and sorting](filtering-and-sorting.md)
 - [Advanced configuration](advanced-configuration.md) — separate config files and custom paths
-- The [`example`](../example) directory contains three ready-to-run boards you can experiment with
+- The [`example`](../example) directory contains four ready-to-run workspaces you can experiment with

package/docs/task-structure.md

@@ -100,13 +100,17 @@ An array of tags to apply to this task.
 
 ### `assigned`
 
-The name of the user this task is assigned to.
+The name of the user this task is assigned to. This is free text: any string is a valid assignee, and Kanbn never rejects or rewrites one.
+
+A workspace can declare a list of [contributors](contributors.md), which gives each person a canonical spelling, autocompletes this field in the interactive prompts and lets `kanbn find --assigned @me` work. Contributors are advisory — `assigned` stays free text either way, and a name that isn't in the list is still perfectly valid.
+
+A task has one assignee. `assigned` is a single string in the schema, the filters, the board template and the reporting commands, and there is no multiple-assignee form.
 
 ### `progress`
 
 The amount of progress for this task. This should be between 0 (not started) and 1 (complete).
 
-Progress is not derived from sub-tasks. If the task has no `progress` value it counts as 0, and a task that is considered complete always counts as 1 regardless of this value. A task is considered complete if it has a `completed` date or is in one of the [`completedColumns`](index-structure.md#completedcolumns).
+Progress is not derived from sub-tasks. If the task has no `progress` value it counts as 0, and a task that is considered complete always counts as 1 regardless of this value. A task is considered complete if its [`completedField`](index-structure.md#completedfield) — `completed` by default — has a date. The column a task sits in doesn't make it complete; see [Index Structure](index-structure.md#completedcolumns).
 
 ### `started`
 
@@ -150,6 +154,8 @@ The `depends-on` relation type is reserved for gantt scheduling. It means the cu
 
 An array of comments, where each comment has an `author` and `date` property, and some text.
 
+`author` is free text, exactly like [`assigned`](#assigned), and it is optional — a comment added on a machine with no resolvable user has an empty author rather than failing to save. When the workspace declares [contributors](contributors.md), the default author is the canonical name for the current user.
+
 ## History
 
 An optional array of structured lifecycle events used for richer timeline reporting (including burndown).
@@ -157,6 +163,8 @@ An optional array of structured lifecycle events used for richer timeline report
 Supported event types:
 
 - `created`: requires `date` and `column`
+- `added`: requires `date` and `column` — the task joined a board
+- `removed`: requires `date` — the task left a board
 - `moved`: requires `date`, `fromColumn`, `toColumn`
 - `progress`: requires `date`, `fromProgress`, `toProgress`
 - `archived`: requires `date`, `fromColumn`
@@ -166,4 +174,24 @@ Notes:
 
 - History entries are stored in the reserved `## History` section as list items.
 - `date` should be an ISO timestamp.
-- Additional fields (for example `author`) are preserved if present.
+- Every event carries an optional `author`, naming the [current user](contributors.md#the-current-user) at the time it happened. The key is omitted entirely when there is no resolvable user, so a machine with no git identity writes exactly the history it always has.
+- Any other additional field is preserved if present.
+- An event type this version of Kanbn doesn't recognise is preserved and skipped rather than rejected, so a task file written by a newer version stays readable.
+
+### Board attribution
+
+In a workspace with [multiple boards](multiple-boards.md), an event carries an optional `board` key naming the board it happened on:
+
+```markdown
+## History
+
+- type: moved
+  date: 2026-07-14T09:12:00.000Z
+  fromColumn: Ideas
+  toColumn: Designing
+  board: design
+```
+
+Events on the **main board carry no `board` key**, so a single-board workspace writes exactly the history it always has, and every existing task file stays valid.
+
+`archived` and `progress` events are never board-scoped: archiving removes a task from every board, and progress is a property of the task rather than of a board.

package/example/README.md

@@ -48,6 +48,29 @@ kanbn board -v everything
 kanbn board -v triage --json
 ```
 
+## [`boards`](boards)
+
+Several boards over one shared pool of tasks. See [Multiple Boards](../docs/multiple-boards.md).
+
+- an engineering board in [`index.md`](boards/.kanbn/index.md) and a design board in
+  [`design.md`](boards/.kanbn/design.md), sharing one `tasks/` folder
+- three tasks that sit in **different columns on each board** - including one that design has started
+  and engineering hasn't
+- `startedField` / `completedField` on the design board, so design progress is tracked in its own
+  metadata fields rather than in the shared `started` / `completed` dates
+- board-scoped options in each board's front matter, and workspace-scoped `customFields` in the main
+  board's - where they are inherited by both
+
+```bash
+kanbn boards
+kanbn boards --tasks
+kanbn board -b design
+kanbn status -b design --untracked
+kanbn task build-tenant-settings-page
+kanbn find --all-boards
+kanbn validate --all-boards
+```
+
 ## [`advanced`](advanced)
 
 Project configuration beyond the defaults. See