@basementuniverse/kanbn 2.0.0 → 2.5.0

package/docs/actions.md

@@ -0,0 +1,337 @@
+# Actions
+
+An action is a rule that says "when _this_ happens to a task, do _that_". Kanbn has had a single-purpose version of this since the beginning — [`startedColumns` and `completedColumns`](index-structure.md#startedcolumns) stamp a date when a task enters a column, and [custom date fields](index-structure.md#customfields) let you declare more of the same. Actions are that idea generalised: more triggers, and more than one thing you can do.
+
+```yaml
+actions:
+  - name: start-work
+    on: task.moved
+    when:
+      toColumn: In Progress
+    then:
+      - assign: '@me'
+      - addTag: active
+      - removeTag: ready
+```
+
+Two properties hold everywhere in this document, and most of the rest follows from them:
+
+- **Actions only fire during commands that change something.** `board`, `status`, `find`, `burndown` and `gantt` never fire an action, so a report is always a pure function of the files on disk. There are no time-based triggers, because Kanbn isn't running when time passes.
+- **Actions never fire actions.** Anything a rule writes is written with the rule engine switched off, so a rule can never trigger another rule — or itself. Rules do not chain. If you want two things to happen, write two verbs in one rule.
+
+## Where rules live
+
+`actions` is an ordinary [index option](index-structure.md#project-options), so it layers the way every other option does:
+
+- In `kanbn.yml` / `kanbn.json` / the `kanbn` key in `package.json`, it applies to **every board** in the workspace.
+- In a board's front matter — including the main board's — it applies to **that board only**.
+
+A board that declares its own `actions` **replaces** the inherited list rather than adding to it, which is how every other option layers. A board that wants the workspace rules and one of its own has to restate them; [`actionsFile`](#actionsfile) is what makes that bearable.
+
+An operation is scoped to exactly one board, so only that board's rules fire for it — with one deliberate exception, [`anyBoard`](#listening-from-another-board).
+
+## Events
+
+| Event | Fires when | Also carries |
+| --- | --- | --- |
+| `task.created` | `kanbn add` creates a task | `column` |
+| `task.moved` | a task changes column | `fromColumn`, `toColumn` |
+| `task.updated` | a task is edited | `changedFields`, `unsetFields` |
+| `task.commented` | a comment is added | `comment` |
+| `task.addedToBoard` | a task joins this board | `column`, `board` |
+| `task.archived` | a task is archived | `fromColumn` |
+| `task.restored` | a task is restored from the archive | `toColumn` |
+| `task.deleted` | a task is removed from a board | `fromColumn`, `removeFile`, `allBoards` |
+| `task.started` | a task becomes started | (whatever the operation carried) |
+| `task.completed` | a task becomes completed | (whatever the operation carried) |
+
+Every event also carries `board`, `boardSlug` and `isMainBoard`.
+
+`task.moved` fires only when the column actually changes, matching the rule Kanbn already uses for history events.
+
+### Derived events
+
+`task.started` and `task.completed` aren't operations — they're **transitions**. They fire when the task was not started (or completed) before the operation and is afterwards, whatever caused it: a move into a started column, a `completed` date typed in by hand, a restore into a done column. They read the board's own `startedColumns`, `completedColumns`, `startedField` and `completedField`, so a rule meaning "when this is done" doesn't have to repeat the column list config already holds:
+
+```yaml
+# Correct on a board with one completed column, and still correct after you add a second
+- on: task.completed
+  then:
+    - removeTag: active
+```
+
+One operation can fire two events — `task.moved` and then `task.completed`. Both sets of rules run, the concrete event first. The transition is evaluated against the state Kanbn is about to write, and before any rule runs, so a rule that writes a `completed` date does **not** fire `task.completed`.
+
+### What can't be an event
+
+There is no daemon, so nothing happens in a Kanbn workspace on its own: due dates passing, sprint boundaries, "no activity for three days" and inbound webhooks are all triggers that need something to be running when time passes, and nothing is. Reporting commands never fire actions either, which is what keeps `kanbn burndown` giving the same answer twice for the same files.
+
+## Conditions
+
+`when` filters the event. It uses the ordinary [filter vocabulary](filtering-and-sorting.md#filter-fields) — every field `kanbn find` accepts, including `tag`, `assigned`, `overdue`, `is-completed` and your own custom fields — plus the event's own keys:
+
+```yaml
+- on: task.moved
+  when:
+    toColumn: [In Progress, Reviewing]   # an event key: matched exactly, a list matches any of them
+    tag: epic                            # a task filter: the usual find vocabulary
+    overdue: true
+  then:
+    - addTag: late-start
+```
+
+Event keys are matched **exactly**, so a rule written for `Done` doesn't match a column called `Done Later`. Task filters behave exactly as they do in `kanbn find`. A rule with no `when` matches every occurrence of its event.
+
+The task is filtered as it will be *after* the operation, so `when: { toColumn: Done }` and `when: { 'in-completed-column': true }` agree with each other.
+
+## Verbs
+
+`then` is a list of verbs, applied in order. This list is closed, on purpose.
+
+| Verb | Argument | Notes |
+| --- | --- | --- |
+| `set` | `{ field: value }` | Metadata only. `created` and `updated` are Kanbn's and can't be written |
+| `unset` | a field name, or a list of them | |
+| `assign` | a name | Shorthand for `set: { assigned: … }` |
+| `addTag` / `removeTag` | a tag, or a list of them | `addTag` is idempotent |
+| `setProgress` | a number between 0 and 1 | Records a `progress` history event, as a manual change does |
+| `comment` | some text | Authored by the rule — see [attribution](#attribution) |
+| `move` | a column name, or `{ column, position }` | The only verb that touches the index |
+| `addToBoard` | `{ board, column }` | Adds the task to another board |
+
+```yaml
+- name: close-out
+  on: task.completed
+  then:
+    - removeTag: active
+    - set: { closedBy: '@me', closedIn: '@event.toColumn' }
+    - unset: [blocked-by, escalated]
+    - setProgress: 1
+    - comment: 'Completed by @me'
+```
+
+There are no expressions, no arithmetic and no conditionals. `when` is where conditions go, and a rule that needs two conditions is two rules. If you need something this list can't express, Kanbn is a command-line application: write a script that calls it.
+
+### `move`
+
+`move` doesn't perform a second move — it changes the destination of the write that was already about to happen, so "when it enters Review, move it to QA" leaves the task in QA with QA's dates stamped on it:
+
+```yaml
+- on: task.moved
+  when: { toColumn: Review }
+  then:
+    - move: QA
+```
+
+- A move to the column the task is already in (or already moving to) is a no-op.
+- A move to a column that doesn't exist is a configuration error, reported by `kanbn validate`.
+- `move` is not available on `task.archived` or `task.deleted`, where the task is leaving the board.
+
+## Substitutions
+
+| Token | Value |
+| --- | --- |
+| `@me` | The [current user](contributors.md#the-current-user) |
+| `@now` | The operation's timestamp |
+| `@task.id`, `@task.name` | The task being written |
+| `@event.<key>` | Any key the event carries: `@event.toColumn`, `@event.fromColumn`, `@event.column`, `@event.board`, `@event.comment` |
+| `@board` | The board the operation ran on |
+| `@event.task.id`, `@event.task.name` | The task the event fired for — only different from `@task.*` in a [cross-task rule](#acting-on-related-tasks) |
+
+A value that is nothing but a token keeps that token's type, so `set: { reviewedAt: '@now' }` writes a date rather than a string. A token inside a longer string is interpolated: `comment: 'Moved to @event.toColumn by @me'`.
+
+`@me` can resolve to nothing — a CI container with no `KANBN_USER`, no matching contributor and no git identity has no current user. A verb whose value can't be resolved is **skipped with a warning** rather than writing an empty value, and `kanbn validate` points out rules that use `@me` where no user resolves.
+
+## Acting on related tasks
+
+By default a rule's verbs apply to the task the event fired for. A `for` clause points them at the tasks it is [related](task-structure.md#relations) to instead:
+
+```yaml
+- name: epic-children-follow
+  on: task.moved
+  when: { tag: epic, toColumn: In Progress }
+  for:
+    related: child-of          # the relation type; omit it to match any relation
+    direction: incoming        # incoming: tasks that point at this one. outgoing: tasks it points at
+    where: { is-completed: false }   # optional, narrows the set - the usual filter vocabulary
+  then:
+    - addToBoard: { board: sprint, column: Todo }
+```
+
+The division of labour is worth learning once: **`when` decides whether the rule fires, `for` decides who it fires on, and `where` narrows that set.**
+
+Direction matters because Kanbn doesn't maintain inverse relations, and neither will you:
+
+- **`outgoing`** — the tasks named in this task's own `relations` list. This is the child-to-parent direction, given that a child is the natural place to record `child-of`.
+- **`incoming`** — the tasks whose `relations` name this task. This is the parent-to-children direction, and it is what makes an epic workable: adding a child doesn't mean editing the epic.
+
+Relation types are matched loosely, so `child-of`, `Child Of` and `child of` are the same type.
+
+Three things to know about the cost and the limits:
+
+- An `incoming` selector has to read every task on the board, which is the same work `kanbn find` does. It happens only when such a rule actually matches, and once per operation however many rules need it. `outgoing` reads only the tasks the relations name.
+- A relation pointing at a task that doesn't exist is skipped with a warning, not an error.
+- Targets are selected **one hop** away, and their writes fire nothing. So "when a child is done, close the epic if all its siblings are done" is not expressible: that needs a condition over a whole set of tasks, which actions deliberately don't have.
+
+`task.deleted` rules **must** have a `for` clause. Verbs applied to a task that is about to stop
+existing are writes to a file about to be removed; acting on the tasks that related to it is the
+useful thing to do:
+
+```yaml
+- name: orphan-children
+  on: task.deleted
+  for: { related: child-of, direction: incoming }
+  then:
+    - removeTag: in-epic
+    - comment: 'Epic @event.task.id was removed'
+```
+
+## Listening from another board
+
+Archiving, restoring and deleting affect **every** board a task is on, so the board you happened to run the command from is an arbitrary choice of whose rules should fire. By default the acting board's rules are the ones that run — the same way `kanbn restore` already lets the acting board's options drive the dates while every board gets its membership back.
+
+A rule on another board can opt in to hearing about those three events whoever triggered them:
+
+```yaml
+# in the design board's front matter
+- name: log-archives
+  on: task.archived
+  anyBoard: true
+  then:
+    - comment: 'Archived from @event.board'
+```
+
+- `anyBoard` is only meaningful on `task.archived`, `task.restored` and `task.deleted`. Setting it on any other event is a configuration error.
+- It applies only when the operation really did affect every board. Removing a task from one board (`kanbn remove` without `--all-boards`) is not workspace-wide, so no other board hears about it.
+- Rules run in board order, with the acting board's first.
+- An `anyBoard` rule can't use `move`, because the columns it names belong to a different board.
+- If another board's rules are broken, they're skipped with a warning rather than failing a command that didn't ask for that board. `kanbn validate --all-boards` reports them.
+
+## `actionsFile`
+
+A long rule set makes front matter hard to read, and a board that wants the workspace rules plus one of its own has to restate all of them. `actionsFile` points at a file holding the same list:
+
+```yaml
+actionsFile: actions/design.yml    # relative to the .kanbn folder
+```
+
+```yaml
+# .kanbn/actions/design.yml
+- name: tag-on-review
+  on: task.moved
+  when: { toColumn: Review }
+  then:
+    - addTag: needs-review
+```
+
+- The file contains exactly what the `actions` option would have contained: a list of rules. A file with a top-level `actions:` key is accepted too.
+- `actions` and `actionsFile` on the same board is an error — pick one.
+- A missing or unparseable `actionsFile` is an error rather than "no rules". A rule set that quietly stops existing is worse than one that fails loudly.
+
+## When something goes wrong
+
+Two kinds of problem, treated differently on purpose:
+
+**Configuration errors** are wrong in the file: an unknown event or verb, a `move` to a column that doesn't exist, a `set` on `created`. `kanbn validate` reports them, and any command that would have run the rules **fails before writing anything**. The whole rule set is checked, not just the rules that would have fired, so a typo shows up the first time you run any command rather than the first time that one rule matches.
+
+**Runtime skips** are things that can only be discovered when the rule fires: `@me` resolving to nothing, a relation pointing at a missing task, `addToBoard` naming a column that has since gone. These print a warning to stderr and the rest of the operation completes.
+
+Nothing fails silently. A rule that quietly stopped working would be worse than no rule at all.
+
+```bash
+kanbn validate
+kanbn validate --all-boards
+```
+
+`kanbn validate` also warns about rule sets that work but probably don't do what they look like — two rules writing the same field on the same event, where the last one silently wins.
+
+## Turning actions off
+
+Every command that can fire an action takes `--no-actions`, and `KANBN_NO_ACTIONS=1` does the same thing for a whole shell:
+
+```bash
+kanbn move my-task -c Done --no-actions
+KANBN_NO_ACTIONS=1 kanbn add -n "Imported task" -c Backlog
+```
+
+This is a way around a misbehaving rule, not a safety control — actions are declarative, so there is nothing being executed to be protected from.
+
+## Attribution
+
+Anything a rule writes is attributed to the rule rather than to a person. A comment written by a rule called `close-out` has the author `@kanbn/close-out`, and so do the history events for a move, a progress change or a board membership that a rule caused:
+
+```yaml
+comments:
+  - author: '@kanbn/close-out'
+    date: 2026-08-29T14:22:05.000Z
+    text: Completed by gordon
+```
+
+`@me` inside a rule means the human who ran the command, not the rule — both are available at once, which is what lets a rule-written comment say who did it without pretending to be them. [Contributor warnings](contributors.md) ignore `@kanbn/*` authors: a rule is not a missing contributor.
+
+## Interaction with column-linked dates
+
+[Column-linked date fields](index-structure.md#customfields) still work exactly as they did, and they are **not** implemented in terms of actions. Built-in stamping happens first, then rules, so a rule can observe and override a stamped value:
+
+```yaml
+customFields:
+  - name: testedAt
+    type: date
+testedAtColumns: [Testing]
+
+actions:
+  - on: task.moved
+    when: { toColumn: Testing }
+    then:
+      - assign: '@me'          # runs after testedAt has been stamped
+```
+
+A rule that redirects a move with `move` re-stamps for the column the task actually ends up in.
+
+## Full example
+
+```yaml
+actions:
+  # Tag and assign work as it starts
+  - name: start-work
+    on: task.started
+    then:
+      - assign: '@me'
+      - addTag: active
+      - removeTag: ready
+
+  # Tidy up when it finishes, whatever caused it to finish
+  - name: close-out
+    on: task.completed
+    then:
+      - removeTag: active
+      - setProgress: 1
+      - set: { closedBy: '@me' }
+
+  # Anything entering Review is stamped and flagged
+  - name: review-stamp
+    on: task.moved
+    when: { toColumn: Review }
+    then:
+      - set: { reviewRequestedAt: '@now' }
+      - addTag: needs-review
+
+  # An epic starting pulls its unfinished children onto the sprint board with it
+  - name: epic-children-follow
+    on: task.moved
+    when: { tag: epic, toColumn: In Progress }
+    for:
+      related: child-of
+      direction: incoming
+      where: { is-completed: false }
+    then:
+      - addToBoard: { board: sprint, column: Todo }
+
+  # Removing an epic leaves its children findable
+  - name: orphan-children
+    on: task.deleted
+    for: { related: child-of, direction: incoming }
+    then:
+      - removeTag: in-epic
+      - comment: 'Epic @event.task.id was removed'
+```

package/docs/advanced-configuration.md

@@ -8,6 +8,8 @@ If any project options are added to the index file, then the next time Kanbn wri
 
 _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
@@ -48,3 +50,56 @@ This will rename the folder where tasks are stored. By default this is `tasks`.
 ### `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.

package/docs/commands/add.txt

@@ -35,7 +35,8 @@ Options:
 
   {b}kanbn add --assigned "name"{b}
   {b}kanbn add -a "name"{b}
-    Create a new task and set the assigned user name. If this option is left blank, the current git username will be used.
+    Create a new task and set the assigned user name. If this option is left blank, the task is assigned to the current user.
+    The current user comes from KANBN_USER or your git identity, canonicalised against the {b}contributors{b} list if the workspace has one - see {b}kanbn contributors --help{b}.
 
   {b}kanbn add --sub-task "sub-task"{b}
   {b}kanbn add -s "sub-task"{b}
@@ -70,3 +71,18 @@ Examples:
 
   {b}kanbn a -ui -f "my-task-3" -f "my-task-4" -c "Done"{b}
     Interactively adds untracked tasks "my-task-3.md" and "my-task-4.md" to the "Done" column.
+
+  {b}kanbn add --board "board-slug"{b}
+  {b}kanbn add -b "board-slug"{b}
+    Add the task to a board other than the main one. This option can be repeated to put one task on
+    several boards at once - the task file is created once and every board named references it:
+      {b}kanbn add -n "Task" -b index -b design -c Todo -c Designing{b}
+    Each {b}-b{b} pairs with the {b}-c{b} in the same position; boards with no {b}-c{b} 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. With a single board an unknown column is still an error.
+
+Boards can declare {b}actions{b} - rules that fire when a task changes, e.g. "when this enters In
+Progress, assign it to me and tag it active". See {b}docs/actions.md{b}.
+
+  {b}kanbn add --no-actions{b}
+    Run without firing any action rules. {b}KANBN_NO_ACTIONS=1{b} does the same for a whole shell.

package/docs/commands/archive.txt

@@ -10,3 +10,14 @@ Options:
   {b}kanbn archive --list{b}
   {b}kanbn archive -l{b}
     Show a list of archived task filenames.
+
+  {b}kanbn archive "task-id" --board "board-slug"{b}
+  {b}kanbn archive "task-id" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.
+
+Boards can declare {b}actions{b} - rules that fire when a task changes, e.g. "when this enters In
+Progress, assign it to me and tag it active". See {b}docs/actions.md{b}.
+
+  {b}kanbn archive --no-actions{b}
+    Run without firing any action rules. {b}KANBN_NO_ACTIONS=1{b} does the same for a whole shell.

package/docs/commands/board.txt

@@ -13,3 +13,12 @@ Options:
   {b}kanbn board -j{b}
     Output raw data instead of rendering the board. The data will be returned in JSON format.
     This is the quickest way to check what a view's filters actually match.
+
+  {b}kanbn board --board "board-slug"{b}
+  {b}kanbn board -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.
+
+Simple tasks - lines in a column that aren't task links - are shown dimmed at the end of their
+column. They only appear in the default layout: a view filters and sorts tasks, and a simple task
+has no fields to filter or sort on. They are left out of {b}--json{b} for the same reason.

package/docs/commands/boards.txt

@@ -0,0 +1,34 @@
+{b}kanbn boards{b}
+
+List the boards in this workspace.
+
+A board is a markdown file directly inside the kanbn folder, in the same format as the index. The
+index file is the main board; every other markdown file beside it is a secondary board. All boards
+share one task folder, so a task can appear on several boards, in a different column on each.
+
+Create a board with {b}kanbn init -b "board-slug"{b}, and target one with {b}-b "board-slug"{b} on
+any board-scoped command.
+
+Options:
+  {b}kanbn boards --tasks{b}
+  {b}kanbn boards -t{b}
+    Show every task that appears on more than one board, with the column it occupies on each.
+
+  {b}kanbn boards --tasks --all{b}
+  {b}kanbn boards -t -a{b}
+    Show every tracked task, not only the ones on more than one board.
+
+  {b}kanbn boards --rename "board-slug" --name "Board Name"{b}
+  {b}kanbn boards -r "board-slug" -n "Board Name"{b}
+    Rename a board. The positional argument is the new slug, and {b}--name{b} sets the display name:
+    {b}kanbn boards --rename design ux --name "UX Pipeline"{b}
+    Either the new slug or {b}--name{b} may be omitted, but not both. The main board can't be renamed.
+
+  {b}kanbn boards --delete "board-slug"{b}
+  {b}kanbn boards -d "board-slug"{b}
+    Delete a board file. Task files are never deleted, but tasks referenced only by this board become
+    untracked - if that would happen, the tasks are listed and {b}-f{b} is required to go ahead.
+
+  {b}kanbn boards --json{b}
+  {b}kanbn boards -j{b}
+    Output the board list, or the cross-board task overview, in JSON format.

package/docs/commands/burndown.txt

@@ -30,6 +30,7 @@ Options:
     Filter for tasks in a particular column. This option can be repeated to include multiple columns.
 
   {b}kanbn burndown --assigned "user"{b}
+  {b}kanbn burndown --assigned @me{b}
   {b}kanbn burndown -a "user"{b}
     Filter for tasks that are assigned to a particular user.
 
@@ -37,3 +38,9 @@ Options:
   {b}kanbn burndown --n "days"|"hours"|"minutes"|"seconds"{b}
     Normalise dates. Task event times (history events or legacy created/started/completed dates) will be rounded down to the nearest day, hour, minute or second. This may cause task events to be grouped together.
     If this option is set to a blank or unsupported value, the normalisation mode will be automatically selected based on the date range.
+
+  {b}kanbn burndown --board "board-slug"{b}
+  {b}kanbn burndown -b "board-slug"{b}
+    Chart a board other than the main one. Burndown measures work in flight, so a board that
+    declares no {b}startedColumns{b} has nothing to chart and says so rather than drawing an empty
+    chart.

package/docs/commands/comment.txt

@@ -10,8 +10,20 @@ Options:
 
   {b}kanbn comment "task-id" --author "name"{b}
   {b}kanbn comment "task-id" -a "name"{b}
-    Set the comment author. If this option is left blank or omitted, the current git username will be used.
+    Set the comment author. If this option is left blank or omitted, the current user is used, and the comment has no author at all if there isn't one.
+    The current user comes from KANBN_USER or your git identity, canonicalised against the {b}contributors{b} list if the workspace has one - see {b}kanbn contributors --help{b}.
 
   {b}kanbn comment "task-id" --text "text"{b}
   {b}kanbn comment "task-id" -t "text"{b}
     Set the comment text.
+
+  {b}kanbn comment "task-id" --board "board-slug"{b}
+  {b}kanbn comment "task-id" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.
+
+Boards can declare {b}actions{b} - rules that fire when a task changes, e.g. "when this enters In
+Progress, assign it to me and tag it active". See {b}docs/actions.md{b}.
+
+  {b}kanbn comment --no-actions{b}
+    Run without firing any action rules. {b}KANBN_NO_ACTIONS=1{b} does the same for a whole shell.

package/docs/commands/contributors.txt

@@ -0,0 +1,58 @@
+{b}kanbn contributors{b}
+
+List the people who work on this workspace, and say which of them Kanbn thinks you are.
+
+Contributors are an optional, workspace-scoped list declared in {b}kanbn.yml{b} / {b}kanbn.json{b}, or
+in the main board's front matter:
+
+  contributors:
+    - gordon
+    - dave
+    - name: sam
+      displayName: Sam Vimes
+      email: sam@example.com
+      aliases:
+        - Samuel Vimes
+        - samv
+      colour: '#7c5cff'
+
+A contributor can be a bare name or an object; only {b}name{b} is required, and it is the value
+written into a task's {b}assigned{b} field or a comment's {b}author{b}.
+
+Contributors are {b}advisory{b}. {b}assigned{b} and {b}author{b} stay free text and are never
+validated against the list, never rejected and never rewritten - the list makes the common case one
+keystroke instead of a retyped name, and makes the names a workspace uses discoverable.
+
+{b}The current user{b}
+
+Kanbn resolves "you" in this order, first match wins:
+
+  1. the {b}KANBN_USER{b} environment variable, used exactly as given
+  2. {b}git config user.email{b} matched against a contributor's {b}email{b}
+  3. {b}git config user.name{b} matched against a contributor's {b}name{b}, {b}displayName{b} or
+     {b}aliases{b}, ignoring case
+  4. {b}git config user.name{b} as-is
+  5. nobody
+
+That value is what {b}kanbn add --assigned{b} and {b}kanbn edit --assigned{b} write when given no
+value, what a comment's author defaults to, and what {b}@me{b} expands to in
+{b}kanbn find --assigned{b}, {b}kanbn burndown --assigned{b}, {b}kanbn gantt --assigned{b} and
+{b}kanbn history --assigned{b}.
+
+Steps 2 and 3 are what canonicalise: on a machine whose git username is "Gordon Larrigan", a
+workspace listing {b}gordon{b} with that name as an alias writes {b}gordon{b} into the task file.
+With no contributors declared, this is exactly the git username Kanbn has always used.
+
+Options:
+  {b}kanbn contributors --usage{b}
+  {b}kanbn contributors -u{b}
+    Show how many tasks and comments each contributor appears in, and every name used in a task that
+    isn't a known contributor. This is how you adopt contributors in an existing workspace: it tells
+    you what to put in the list, and which spellings to add as aliases.
+
+    It is read-only. Nothing is rewritten - renaming "Gordon" to "gordon" across every task file is a
+    bulk mutation and isn't done here.
+
+  {b}kanbn contributors --json{b}
+  {b}kanbn contributors -j{b}
+    Output the contributor list, or the usage report, in JSON format.

package/docs/commands/edit.txt

@@ -34,7 +34,8 @@ Options:
     Modify a task's progress. This should be a number between 0 (not started) and 1 (complete).
 
   {b}kanbn edit "task-id" --assigned "name"{b}
-    Modify a task assigned user name. If this option is left blank, the current git username will be used.
+    Modify a task assigned user name. If this option is left blank, the task is assigned to the current user.
+    The current user comes from KANBN_USER or your git identity, canonicalised against the {b}contributors{b} list if the workspace has one - see {b}kanbn contributors --help{b}.
 
   {b}kanbn edit "task-id" --remove-sub-task "sub-task"{b}
     Remove a sub-task.
@@ -78,3 +79,19 @@ Options:
 
   {b}kanbn edit --remove-<custom field name>{b}
     Remove a custom metadata field.
+
+  {b}kanbn edit "task-id" --board "board-slug"{b}
+  {b}kanbn edit "task-id" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.
+
+  {b}kanbn edit "Buy milk"{b}
+    Editing a simple task - a line in a column that isn't a task link - promotes it to a real task
+    file first, and then applies the edit. The new task is created in the column the line was in,
+    with a created date as of the promotion. There is no way back.
+
+Boards can declare {b}actions{b} - rules that fire when a task changes, e.g. "when this enters In
+Progress, assign it to me and tag it active". See {b}docs/actions.md{b}.
+
+  {b}kanbn edit --no-actions{b}
+    Run without firing any action rules. {b}KANBN_NO_ACTIONS=1{b} does the same for a whole shell.