@basementuniverse/kanbn 1.1.1 → 2.1.0

package/docs/index-structure.md

@@ -67,23 +67,23 @@ taskTemplate: ""
 dateFormat: ""
 views:
   - name: My view 1
+    filters:
+      tag: Bug
     columns:
-      "Column 1":
-        - hidden: false
-          filters:
-            name: /test/
-            workload:
-              - 1
-              - 5
-          sorters:
-            - field: name
-              filter: ""
-              order: ascending
-    lanes:
-      - name: "Lane 1"
-        filter:
+      - name: Column 1
+        filters:
+          name: test
+          workload:
+            - 1
+            - 5
+        sorters:
           - field: name
             filter: ""
+            order: ascending
+    lanes:
+      - name: Lane 1
+        filters:
+          assigned: username
 customFields:
   - name: 'myCustomField'
     type: 'date'
@@ -95,18 +95,71 @@ customFields:
 
 A list of column names. These columns will be hidden from the kanbn board.
 
+This only affects the default board layout. Tasks in hidden columns are still tracked, still show up in `kanbn find` and `kanbn status`, and are still shown by any [view](views.md) that defines its own `columns`.
+
 ### `startedColumns`
 
 A list of column names. When a task is created in or dragged into one of these columns, the task's `started` date will be set to the current time, unless the task already has a 'started' date.
 
 ### `completedColumns`
 
-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. If the task already has a `completed` date, this date will be updated.
+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.
+
+### `startedField`
+
+The name of the metadata field that holds a task's started date. Defaults to `started`.
+
+### `completedField`
+
+The name of the metadata field that holds a task's completed date. Defaults to `completed`.
+
+Pointing these at custom date fields lets a board track its own started/completed state without touching the shared `started` and `completed` fields:
+
+```yaml
+completedField: designSignedOffAt
+completedColumns:
+  - Signed Off
+customFields:
+  - name: designSignedOffAt
+    type: date
+```
+
+### `verbose`
+
+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`
@@ -123,7 +176,9 @@ An associative array of column names and sorters. Each column can have an array
 
 The `filter` property can be used to transform values before sorting.
 
-Run `kanbn sort --help` for more information.
+Columns listed here are re-sorted every time Kanbn writes the index, so the order survives `kanbn add`, `kanbn move` and `kanbn validate --save`.
+
+See [Filtering and Sorting](filtering-and-sorting.md#sorters), or run `kanbn sort --help`.
 
 ### `taskTemplate`
 
@@ -137,6 +192,7 @@ updated
 started
 completed
 due
+assigned
 tags
 subTasks
 relations
@@ -149,6 +205,8 @@ 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.*
+
 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.
@@ -161,11 +219,13 @@ The date format to use for dates on the kanbn board and burndown chart views. Se
 
 ### `views`
 
-An array of views that can be used to customize how the kanbn board is displayed.
+An array of views that can be used to customize how the kanbn board is displayed. Select a view with `kanbn board --view "name"`.
+
+Each view has a required `name`, an optional root `filters` object, an optional array of `columns` and an optional array of `lanes`. Each column has a required `name` and optional `filters` and `sorters`. Each lane has a required `name` and optional `filters`.
 
-Each view should have a `name` property (run `kanbn board --view "name"` to specify which view to use), a list of columns and a list of lanes.
+If `columns` is omitted, the index columns are used (minus `hiddenColumns`). If `lanes` is omitted, a single lane containing all matching tasks is used.
 
-Each column can be hidden, filtered or sorted. Each lane has a list of filters.
+See [Views](views.md) for a full description and worked examples, and [Filtering and Sorting](filtering-and-sorting.md) for the filter and sorter formats.
 
 ### `customFields`
 
@@ -204,3 +264,18 @@ Here's an example of how this could be used:
     - 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.
+
+## 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).
+
+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.
+
+To clear a date - for example to reopen a task that was completed - use `kanbn edit "task-id" --unset completed`.
+
+_Note: before version 2.0.0, a task sitting in a completed column counted as complete even with no `completed` date. See [Migrating to 2.0.0](migration-2.0.md)._

package/docs/index.md

@@ -7,6 +7,32 @@ To get started quickly, check out the [Quick Start](quick-start.md) guide.
 ## Contents
 
 - [Quick Start](quick-start.md)
-- [Index Structure](index-structure.md)
-- [Task Structure](task-structure.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
+- [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)
+- [Migrating to 2.0.0](migration-2.0.md) — separate config files and custom folder locations
+
+## Examples
+
+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/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, column sorting and a custom task template |
+
+Run any Kanbn command from inside one of those directories to try it out.
+
+## Command help
+
+Every command has built-in help:
+
+```bash
+kanbn help <command>
+kanbn <command> --help
+```

package/docs/migration-2.0.md

@@ -0,0 +1,92 @@
+# Migrating to 2.0.0
+
+Version 2.0.0 changes how kanbn decides whether a task has started or been completed. Everything else about the file format is unchanged: your `index.md` and task files are read and written exactly as before, and no migration step is required to open an existing board.
+
+## What changed
+
+**Before**, a task counted as complete if *either* it had a `completed` date *or* it was sitting in a column listed in `completedColumns`. The same applied to `started` and `startedColumns` when drawing burndown charts.
+
+**Now**, only the dates count. A task has started if its `started` date is set, and it is complete if its `completed` date is set.
+
+Columns still cause those dates to be written. Moving a task into a completed column through `kanbn move`, `kanbn edit -c`, or the VSCode extension sets its `completed` date exactly as it did before. What's changed is that the column no longer *stands in for* the date.
+
+## Why
+
+Inferring state from columns produced results that contradicted themselves and couldn't be corrected:
+
+* `kanbn status --due` could report a task as `completed: true` with `completedDate: null` - complete, but with no record of when.
+* Burndown charts substituted a task's **created** date when it had no started date, inventing timings unrelated to when the work happened.
+* State could only ever move forwards. Once a `completed` date was written, moving the task back out of the column didn't clear it, and there was no command that could.
+* A task could be complete on one board and not another purely because of what its columns were called - which becomes a real problem now that a task can appear on several boards.
+
+## What you might notice
+
+* **Tasks moved by hand.** If you moved a task between columns by editing `index.md` directly, or a git merge moved it, no date was written. Those tasks will now show as not started or not complete.
+* **Burndown charts will look different** for any board where dates and columns disagreed.
+* **Generated boards.** Tasks written by a tool or an AI assistant may sit in `Done` without a `completed` date.
+
+Boards that have only ever been driven through the CLI or the VSCode extension already have the right dates and won't change.
+
+## Fixing up an existing board
+
+```
+kanbn validate
+```
+
+reports every task whose dates and column disagree, in both directions:
+
+```
+2 tasks have dates that don't match their column:
+  bravo: task is in column "In Progress" but has no started date
+  alpha: task is in column "Done" but has no completed date
+```
+
+```
+kanbn validate --fix
+```
+
+fills in the missing dates. Each date is taken from the task's own history, where the move into that column is recorded, so the backfilled dates reflect when the move actually happened:
+
+```
+Filled in 2 missing dates:
+  bravo: started set to 2026-08-14T09:12:04.000Z (from history)
+  alpha: completed set to 2026-08-19T16:40:11.000Z (from history)
+```
+
+If a task has no history recording the move, the date falls back to the task's `updated` date, then its `created` date. The source is always reported so you can see which dates were guessed.
+
+Tasks that have a `completed` date while sitting **outside** a completed column are reported but never changed - the date records something that really happened, and removing it automatically would lose it.
+
+`kanbn board` and `kanbn status` print a one-line reminder when a board has drifted. Set `verbose: false` in your project options to suppress it.
+
+## Clearing a date
+
+There is now a way to remove a date, which is what makes the dates trustworthy as the single source of truth:
+
+```
+kanbn edit "my-task" --unset completed
+```
+
+This reopens a completed task. It works for `started`, `completed`, `due`, `plannedStart`, `plannedFinish`, `assigned`, `progress`, `tags`, and any custom field. If the same command also moves the task into a completed column, the unset is applied last, so it wins.
+
+## Per-board state fields
+
+Two new project options, `startedField` and `completedField`, name the metadata fields a board reads and writes. They default to `started` and `completed`.
+
+Pointing them at custom date fields lets one task carry separate state for separate workflows:
+
+```yaml
+completedField: designSignedOffAt
+completedColumns:
+  - Signed Off
+customFields:
+  - name: designSignedOffAt
+    type: date
+```
+
+A board configured this way writes and reads `designSignedOffAt` and leaves the shared `completed` field alone.
+
+## Other changes in 2.0.0
+
+* **Task ids ending in a single capital letter are now fully lowercased.** `kanbn add -n "Task A"` previously produced the id `task-A`; it now produces `task-a`. Non-ASCII capitals are lowercased too. Existing task files are not renamed.
+* **Unknown history event types and keys are preserved** rather than rejected, so a task file written by a newer version of kanbn stays readable.

package/docs/multiple-boards.md

@@ -0,0 +1,258 @@
+# 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 |
+| `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

@@ -59,4 +59,60 @@ This will add a "Large" tag to the task and modify the task's updated date. If y
 
 Run `kanbn edit --help` for more information on editing tasks.
 
-See [index structure](index-structure.md) for more information on project settings, tags and workload calculations.
+## Find tasks
+
+```
+kanbn find --tag "Large" --column "Todo"
+```
+
+Filters are combined with AND, string filters are case-insensitive regular expressions, and dates and numbers can be given twice to search a range. See [filtering and sorting](filtering-and-sorting.md) for the full model.
+
+## Customise the board
+
+Define a view in your project options to re-arrange, filter or group the board without moving any tasks:
+
+```yaml
+views:
+  - name: 'by-assignee'
+    lanes:
+      - name: 'Me'
+        filters:
+          assigned: '^my-username$'
+      - name: 'Everyone else'
+        filters:
+          assigned: '^(?!my-username$).*'
+```
+
+```
+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 four ready-to-run workspaces you can experiment with