diff --git a/.changeset/28319-kanban-lanes-tsdoc.md b/.changeset/28319-kanban-lanes-tsdoc.md
new file mode 100644
index 00000000000..c5345d4ad6b
--- /dev/null
+++ b/.changeset/28319-kanban-lanes-tsdoc.md
@@ -0,0 +1,10 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the `kanban.lanes` TSDoc states what the board draws
+
+Clause-②: no
+Metadata-protocol: none
+
+The `KanbanConfigSchema.lanes` TSDoc still said the board drew one lane per option until the Console read the key. The Console reads it now, so the paragraph says what is drawn: the listed lanes and no others, in the order the author wrote them; a record whose value is not listed lands in `Uncategorized`; without the key, one lane per option in the options' own order. The `.describe()` text already said this and is unchanged. No schema or behaviour change.
diff --git a/packages/lint/src/validate-list-view-field-refs.ts b/packages/lint/src/validate-list-view-field-refs.ts
index 34aa7c35d40..f1d597c3ec0 100644
--- a/packages/lint/src/validate-list-view-field-refs.ts
+++ b/packages/lint/src/validate-list-view-field-refs.ts
@@ -1083,6 +1083,11 @@ export function validateListViewFieldRefs(
    * [#28018] `kanban.lanes`, judged once a list view's bound object resolves:
    * every entry must be an inline option of `groupByField`. See the section of
    * that name on this module.
+   *
+   * It reads only the option map above, built from inline `options[].value`.
+   * A future `FieldSchema` key that widens the inline options a `groupByField`
+   * may carry must join that map, or a lane naming a widened option is
+   * reported as unknown.
    */
   const checkKanbanLanes = (listView: AnyRec, object: string, where: string, path: string): void => {
     const kanban = listView.kanban;
diff --git a/packages/spec/src/ui/view.zod.ts b/packages/spec/src/ui/view.zod.ts
index 50b103ffe45..dcdc2b6972d 100644
--- a/packages/spec/src/ui/view.zod.ts
+++ b/packages/spec/src/ui/view.zod.ts
@@ -2094,8 +2094,10 @@ export const KanbanConfigSchema = lazySchema(() => strictObject({
    * ⛔ No spec-side default: absence keeps every board stored before this key
    * exactly as it was, one lane per option.
    *
-   * Lands ahead of its reader: the board draws one lane per option until the
-   * console half reads this key where it builds its lanes.
+   * What the board draws: the listed lanes and no others, in the order the
+   * author wrote them; a record whose value is not listed lands in
+   * `Uncategorized`. Without the key it draws one lane per option, in the
+   * options' own order.
    */
   lanes: z.array(SystemIdentifierSchema)
     .min(1, { message: '`kanban.lanes` lists at least one lane. To draw one lane per option, omit the key.' })