@basementuniverse/kanbn 2.1.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

@@ -68,6 +68,38 @@ boards:
       - 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}
@@ -79,3 +80,9 @@ Examples:
     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

@@ -15,3 +15,9 @@ Options:
   {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

@@ -18,3 +18,7 @@ Options:
   {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/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.
 

package/docs/commands/comment.txt

@@ -10,7 +10,8 @@ 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}
@@ -20,3 +21,9 @@ Options:
   {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.
@@ -83,3 +84,14 @@ Options:
   {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.

package/docs/commands/find.txt

@@ -78,7 +78,7 @@ Options:
     The date can be in (almost) any format.
 
   {b}kanbn find --assigned "name"{b}
-    Find tasks assigned to a specific user. Use "^$" to find unassigned tasks.
+    Find tasks assigned to a specific user. Use "^$" to find unassigned tasks, and {b}@me{b} for tasks assigned to you.
 
   {b}kanbn find --workload N{b}
     Find tasks with a specific calculated workload.
@@ -88,6 +88,28 @@ Options:
     Find tasks with a specific progress value (between 0 and 1).
     If multiple values are specified, find tasks with progress between the lowest and highest inputs.
 
+  {b}kanbn find --overdue{b}
+  {b}kanbn find --no-overdue{b}
+    Find tasks that are (or are not) overdue. A task is overdue if it has a due date in the past and
+    hasn't been completed. A task with no due date is never overdue.
+
+  {b}kanbn find --is-started{b}
+  {b}kanbn find --no-is-started{b}
+    Find tasks that do (or don't) have a started date in their metadata.
+
+  {b}kanbn find --is-completed{b}
+  {b}kanbn find --no-is-completed{b}
+    Find tasks that do (or don't) have a completed date in their metadata.
+
+  {b}kanbn find --in-started-column{b}
+  {b}kanbn find --no-in-started-column{b}
+    Find tasks that are (or aren't) in one of the board's startedColumns. If the board declares no
+    startedColumns, no task is in a started column.
+
+  {b}kanbn find --in-completed-column{b}
+  {b}kanbn find --no-in-completed-column{b}
+    Find tasks that are (or aren't) in one of the board's completedColumns.
+
   {b}kanbn find --sub-task "search term"{b}
   {b}kanbn find -s "search term"{b}
     Find tasks that have sub-tasks matching the search term.
@@ -138,6 +160,9 @@ Examples:
   {b}kanbn find --count-sub-tasks 1 --count-sub-tasks 99 --progress 0 -q{b}
     List the ids of tasks that have sub-tasks but no progress yet.
 
+  {b}kanbn find --overdue --no-in-started-column -q{b}
+    List the ids of overdue tasks that nobody has picked up yet.
+
   {b}kanbn find --board "board-slug"{b}
   {b}kanbn find -b "board-slug"{b}
     Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
@@ -146,5 +171,7 @@ Examples:
   {b}kanbn find --all-boards{b}
     Search every board in the workspace. A task on several boards appears once, annotated with the
     board and column it occupies on each. Without this, the search is scoped to the target board.
+    Computed values are evaluated per board, so a task matches {b}--in-started-column{b} if it is in
+    a started column on any of them.
     This can't be combined with {b}--sprint{b}: sprint numbers and names are relative to one board's
     list, so there is no sensible answer across several.

package/docs/commands/gantt.txt

@@ -14,6 +14,7 @@ Options:
     Output raw data instead of rendering a chart. The data will be returned in JSON format.
 
   {b}kanbn gantt --assigned "user"{b}
+  {b}kanbn gantt --assigned @me{b}
   {b}kanbn gantt -a "user"{b}
     Filter for tasks that are assigned to a particular user.
 

package/docs/commands/help.txt

@@ -26,6 +26,7 @@ Where {b}<command>{b} is one of:
   {b}restore{b} {d}.......{d} Restore a task from the archive
   {b}remove-all{b} {d}....{d} Remove the kanbn board and all tasks
   {b}history{b} {d}.......{d} Show task history
+  {b}contributors{b} {d}..{d} List the workspace's contributors
 
 For more help with commands, try:
 

package/docs/commands/history.txt

@@ -20,6 +20,7 @@ Options:
     If two or more dates are provided, show history from the earliest to latest date.
 
   {b}kanbn history --assigned "user"{b}
+  {b}kanbn history --assigned @me{b}
   {b}kanbn history -a "user"{b}
     Filter for tasks assigned to a specific user.
 

package/docs/commands/move.txt

@@ -30,3 +30,20 @@ Options:
   {b}kanbn move "task-id" -b "board-slug" --no-add{b}
     Refuse to move a task that isn't on the target board, instead of adding it.
     The main board never adds implicitly: moving an untracked task there is an error either way.
+
+
+Simple tasks - lines in a column that aren't task links - can be moved too, by title:
+
+  {b}kanbn move "Buy milk" -c "Done"{b}
+    Move a simple task to another column. The title matches exactly, ignoring case, or slugified.
+    A real task with the same id always wins. Leave off {b}-c{b} to reposition it in its own column.
+
+  {b}kanbn move "Buy milk" -b "board-slug" -c "column"{b}
+    Move a simple task onto another board. A simple task is content in one board file rather than a
+    shared task file, so this moves the line: it leaves this board and joins the other one.
+
+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 move --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/remove.txt

@@ -21,3 +21,13 @@ Options:
   {b}kanbn remove "task-id" --all-boards{b}
     Task files are shared between boards, so deleting one while another board still references it is
     refused. This removes the task from every board that references it, then deletes the file.
+
+  {b}kanbn remove "Buy milk"{b}
+    Remove a simple task - a line in a column that isn't a task link - by title. There is no file to
+    delete and nothing to archive, so {b}--index{b} and {b}--all-boards{b} don't apply.
+
+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 remove --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/restore.txt

@@ -16,3 +16,9 @@ Options:
     Restore the task to that board only. Without this, the task goes back to every board it was on
     when it was archived, in the column it occupied on each. A board that has since been deleted is
     reported and skipped rather than failing the restore.
+
+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 restore --no-actions{b}
+    Run without firing any action rules. {b}KANBN_NO_ACTIONS=1{b} does the same for a whole shell.