@rmrdeveloper/sideroom-pi 8.1.1 → 8.3.0

package/README.md

@@ -4,6 +4,15 @@
 [![npm monthly downloads](https://img.shields.io/npm/dm/@rmrdeveloper/sideroom-pi?label=downloads&logo=npm)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 [![npm license](https://img.shields.io/npm/l/@rmrdeveloper/sideroom-pi?label=license)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 
+**Asks before it guesses. Shows the plan. Enforces the style. Refuses to
+call it done in red.**
+
+```bash
+pi install npm:@rmrdeveloper/sideroom-pi
+```
+
+![Sideroom asking a multi-question batch and keeping the live board below it](https://raw.githubusercontent.com/RMRdeveloper/sideroom-pi/main/media/preview.png)
+
 > Coding agents fail in predictable ways: they guess instead of asking, they
 > bury progress in chat scroll, they litter your repo with `TODO.md` files,
 > every session writes code in a slightly different style, and they declare
@@ -54,14 +63,17 @@ wall of tool calls, it:
 
 - **Asks like a senior would.** A clean TUI questionnaire appears — tabs for
   several questions, a simple list for one. Every question carries a
-  recommendation, you can always answer *Out of scope* or write your own,
-  and everything is written in your language. Escape cancels the whole
-  batch. No guessing, no twenty follow-up clarifications in chat.
+  recommendation, and a plural one lets you tick several answers at once. You
+  can always answer *Out of scope* or write your own, and everything is written
+  in your language. Escape cancels the whole batch. No guessing, no twenty
+  follow-up clarifications in chat.
 - **Works in the open.** A compact board sits above the editor:
   `pending → in_progress → completed`. Exactly one step is active at a
   time; the agent completes the current step and starts the next one in the
-  same move, so skipped steps become structurally hard. The board survives
-  reload, tree navigation, and compaction.
+  same move, so skipped steps become structurally hard. The widget shows at
+  most five rows, keeps the active step visible, and `F9` opens the full
+  read-only board. The board survives reload, tree navigation, and
+  compaction.
 - **Shows its traces.** Below the board, the last edited files appear as
   clickable `file://` links. `F8` opens the full session history; `R` clears
   it. Only successful Pi `write`/`edit` calls are tracked — no guesses from
@@ -86,9 +98,11 @@ wall of tool calls, it:
 ### `sideroom_ask` — decisions, not interrogations
 
 One call is one 1–N question batch. Each question needs an `id`, a `prompt`,
-at least two `{ value, label }` options, and a `recommendationIndex` pointing
-at the recommended option. The UI adds the rest: the recommended mark, the
-always-on *Out of scope* row, and a custom answer.
+at least two `{ value, label }` options, and a recommendation:
+`recommendationIndex` for the default single answer, or
+`selectionMode: "multiple"` with `recommendedIndices` when the question accepts
+several. The UI adds the rest: the recommended mark, the always-on *Out of
+scope* row, and a custom answer.
 
 TUI-only by design. In print, JSON, or RPC modes it fails fast with
 `UI not available` instead of hanging.
@@ -102,6 +116,10 @@ chat. It never creates a repository task file or a `/todos` command.
 - `update` patches `{ id, status?, content? }` items and works everywhere,
   including headless modes.
 - Invariant: while anything is pending, exactly one item is `in_progress`.
+- Widget: at most five rows — open items before resolved ones, the
+  `in_progress` row always visible — plus a `…+N more · F9: view all` hint.
+  `F9` opens the full board as a read-only overlay, so the widget stays small
+  without hiding work from you; the agent still gets every item in its prompt.
 
 ### Edited files — proof, not promises
 
@@ -185,9 +203,10 @@ pi update --extension npm:@rmrdeveloper/sideroom-pi
 ### Questionnaire contract
 
 Each batch accepts one to four questions, with two to four caller-provided
-options per question. Tab labels accept at most 16 characters and option
-labels at most 60. Inputs that exceed a limit are rejected rather than
-truncated.
+options per question. A question takes one answer unless it declares
+`selectionMode: "multiple"`, which requires `recommendedIndices` and at least
+one selection. Tab labels accept at most 16 characters and option labels at
+most 60. Inputs that exceed a limit are rejected rather than truncated.
 
 Write prompts, tab labels, and option copy in the language the user is
 speaking; keep ids, option values, and TUI chrome in English. Do not send
@@ -200,6 +219,13 @@ Items have stable string ids, short content, and one of `pending`,
 start the next one in the same `update` call. Snapshots live in the active
 session branch and are rebuilt after navigation and compaction.
 
+- Widget: max five rows. Open items win the cap over resolved ones, the
+  `in_progress` row is always shown, and a `…+N more · F9: view all` line
+  appears when rows are hidden.
+- Extended view: `F9` toggles a read-only overlay. `↑`/`↓` and `PgUp`/`PgDn`
+  scroll; `Esc` or `F9` closes. It never mutates the board.
+- The cap is display-only: every item still reaches the system prompt.
+
 A forked session inherits the board visible at its fork point. Later board
 updates are reconstructed from each session's active branch, so the fork and
 the original session evolve independently.
@@ -250,6 +276,17 @@ Single-session scope only. Files are created lazily: nothing exists until
 the first term or decision crystallises. A session with a sharper glossary
 and zero ADRs is working as designed.
 
+### Coexisting with other grilling skills
+
+Pi routes skills by description, not by name, so several grilling skills can
+be installed at once. `sideroom-grill` claims non-trivial plans before
+implementation and states precedence over other grilling, interview, and spec
+skills. If a third-party skill still wins, remove it from routing by adding
+`disable-model-invocation: true` to its frontmatter, or exclude its path with
+`-path` in `settings.skills`. A literal name collision keeps the first skill
+found: project `.pi/skills`, then project `.agents/skills`, then
+`~/.pi/agent/skills`, then `~/.agents/skills`, then packages.
+
 ## Documentation
 
 Maintainer reference lives in [`docs/`](docs/README.md): the

package/extensions/ask/index.ts

@@ -9,16 +9,18 @@ import {
 } from './model.ts';
 
 export const ASK_DESCRIPTION =
-  'Ask the user one or more questions in the language they are speaking. Use for clarifying requirements, getting preferences, or confirming decisions. Each question must include a recommended option. For a single question, shows a simple option list. For multiple questions, shows a tab-based interface.';
+  'Ask the user one or more questions in the language they are speaking. Use for clarifying requirements, getting preferences, or confirming decisions. Each question must include a recommended option, or several recommended options when it accepts multiple selections. For a single question, shows a simple option list. For multiple questions, shows a tab-based interface.';
 
 export const ASK_PROMPT_SNIPPET =
   'Ask the user one or more questions with a recommended option, in their language.';
 
 export const ASK_PROMPT_GUIDELINES = [
   'Use sideroom_ask to clarify requirements, preferences, or decisions with the user.',
+  'When a non-trivial request is not yet a settled spec, follow the sideroom-grill skill before implementing; it owns the interview and drives sideroom_ask rounds.',
   'Each sideroom_ask question needs an id, a prompt, at least two options, and a recommendationIndex pointing at the recommended option.',
   'Write every sideroom_ask prompt, tab label, and option label or description in the language the user is speaking. Keep ids, option values, and tool code in English.',
-  'sideroom_ask always adds Out of scope and a custom answer; do not include those options yourself.',
+  'sideroom_ask always adds Out of scope and a custom answer; do not include those options yourself, and in a multiple-selection question they replace the selections.',
+  'For a genuinely plural sideroom_ask question, set selectionMode "multiple" with recommendedIndices (at least one) instead of recommendationIndex; never send both fields, and keep the single default otherwise.',
   'One sideroom_ask call is one batch; call it again if another round of questions is needed.',
   'sideroom_ask only works in the interactive TUI; it returns an error in print, JSON, or RPC modes.',
 ];
@@ -73,6 +75,14 @@ export default function registerAsk(pi: ExtensionAPI): void {
         if (answer.wasCustom) {
           return `${mark}${id}: ${theme.fg('muted', '(wrote) ')}${answer.label}`;
         }
+        if (answer.selections !== undefined && answer.selections.length > 0) {
+          const picked = answer.selections
+            .map(
+              (selection) => `${String(selection.index)}. ${selection.label}`,
+            )
+            .join(', ');
+          return `${mark}${id}: ${picked}`;
+        }
         if (answer.index !== undefined) {
           return `${mark}${id}: ${String(answer.index)}. ${answer.label}`;
         }

package/extensions/ask/model.ts

@@ -9,6 +9,13 @@ export const CUSTOM_LABEL = 'Write a custom answer';
 export const UI_UNAVAILABLE =
   'Error: UI not available (running in non-interactive mode)';
 
+export const SINGLE_SELECTION_MODE = 'single';
+export const MULTIPLE_SELECTION_MODE = 'multiple';
+
+export type SelectionMode =
+  | typeof SINGLE_SELECTION_MODE
+  | typeof MULTIPLE_SELECTION_MODE;
+
 const MAX_QUESTIONS = 4;
 const MAX_OPTIONS = 4;
 const MAX_TAB_LABEL_LENGTH = 16;
@@ -39,10 +46,32 @@ const QuestionSchema = Type.Object({
     maxItems: MAX_OPTIONS,
     description: `Two to ${String(MAX_OPTIONS)} mutually exclusive options`,
   }),
-  recommendationIndex: Type.Integer({
-    minimum: 0,
-    description: 'Index into options pointing at the recommended option',
-  }),
+  selectionMode: Type.Optional(
+    Type.Union(
+      [
+        Type.Literal(SINGLE_SELECTION_MODE),
+        Type.Literal(MULTIPLE_SELECTION_MODE),
+      ],
+      {
+        description:
+          "'single' (default) answers with one option; 'multiple' answers with one or more",
+      },
+    ),
+  ),
+  recommendationIndex: Type.Optional(
+    Type.Integer({
+      minimum: 0,
+      description:
+        "Required for a 'single' question: index into options pointing at the recommended option",
+    }),
+  ),
+  recommendedIndices: Type.Optional(
+    Type.Array(Type.Integer({ minimum: 0 }), {
+      minItems: 1,
+      description:
+        "Required for a 'multiple' question: indexes of every recommended option, at least one",
+    }),
+  ),
 });
 
 export const AskParamsSchema = Type.Object({
@@ -61,7 +90,14 @@ export interface AskQuestion {
   readonly label: string;
   readonly prompt: string;
   readonly options: readonly QuestionOption[];
-  readonly recommendationIndex: number;
+  readonly selectionMode: SelectionMode;
+  readonly recommendedIndices: readonly number[];
+}
+
+export interface AskSelection {
+  readonly value: string;
+  readonly label: string;
+  readonly index: number;
 }
 
 export interface AskAnswer {
@@ -71,6 +107,7 @@ export interface AskAnswer {
   readonly wasCustom: boolean;
   readonly outOfScope: boolean;
   readonly index?: number;
+  readonly selections?: readonly AskSelection[];
 }
 
 export interface AskResult {
@@ -208,11 +245,9 @@ export function parseAskParams(value: unknown): ParseAskResult {
       };
     }
     seen.add(question.id);
-    if (question.recommendationIndex >= question.options.length) {
-      return {
-        ok: false,
-        message: `Error: recommendationIndex ${String(question.recommendationIndex)} is out of range for question '${question.id}'`,
-      };
+    const failure = recommendationError(question);
+    if (failure !== undefined) {
+      return { ok: false, message: failure };
     }
   }
 
@@ -224,6 +259,7 @@ export function normalizeQuestions(
 ): AskQuestion[] {
   return questions.map((question, index) => {
     const label = question.label;
+    const selectionMode = selectionModeOf(question);
     return {
       id: question.id,
       label:
@@ -232,15 +268,67 @@ export function normalizeQuestions(
           : `Q${String(index + 1)}`,
       prompt: question.prompt,
       options: question.options,
-      recommendationIndex: question.recommendationIndex,
+      selectionMode,
+      recommendedIndices: recommendedIndicesFor(question, selectionMode),
     };
   });
 }
 
+function selectionModeOf(
+  question: AskParams['questions'][number],
+): SelectionMode {
+  return question.selectionMode === MULTIPLE_SELECTION_MODE
+    ? MULTIPLE_SELECTION_MODE
+    : SINGLE_SELECTION_MODE;
+}
+
+function recommendedIndicesFor(
+  question: AskParams['questions'][number],
+  selectionMode: SelectionMode,
+): readonly number[] {
+  if (selectionMode === MULTIPLE_SELECTION_MODE) {
+    return question.recommendedIndices ?? [];
+  }
+  if (question.recommendationIndex === undefined) {
+    return [];
+  }
+  return [question.recommendationIndex];
+}
+
+function recommendationError(
+  question: AskParams['questions'][number],
+): string | undefined {
+  if (selectionModeOf(question) === SINGLE_SELECTION_MODE) {
+    if (question.recommendationIndex === undefined) {
+      return `Error: Question '${question.id}' requires recommendationIndex`;
+    }
+    if (question.recommendedIndices !== undefined) {
+      return `Error: Question '${question.id}' is a single-selection question; remove recommendedIndices`;
+    }
+    if (question.recommendationIndex >= question.options.length) {
+      return `Error: recommendationIndex ${String(question.recommendationIndex)} is out of range for question '${question.id}'`;
+    }
+    return undefined;
+  }
+  if (question.recommendedIndices === undefined) {
+    return `Error: Question '${question.id}' is a multiple-selection question and requires recommendedIndices`;
+  }
+  if (question.recommendationIndex !== undefined) {
+    return `Error: Question '${question.id}' is a multiple-selection question; remove recommendationIndex`;
+  }
+  const outOfRange = question.recommendedIndices.find(
+    (optionIndex) => optionIndex >= question.options.length,
+  );
+  if (outOfRange !== undefined) {
+    return `Error: recommendedIndices ${String(outOfRange)} is out of range for question '${question.id}'`;
+  }
+  return undefined;
+}
+
 export function renderOptions(question: AskQuestion): RenderOption[] {
   const options: RenderOption[] = question.options.map((option, index) => ({
     ...option,
-    isRecommended: index === question.recommendationIndex,
+    isRecommended: question.recommendedIndices.includes(index),
   }));
   options.push({
     value: OUT_OF_SCOPE_VALUE,
@@ -268,6 +356,13 @@ export function formatAnswerLines(
     if (answer.wasCustom) {
       return `${questionLabel}: user wrote: ${answer.label}`;
     }
+    const selections = answer.selections;
+    if (selections !== undefined && selections.length > 0) {
+      const picked = selections
+        .map((selection) => `${String(selection.index)}. ${selection.label}`)
+        .join(', ');
+      return `${questionLabel}: user selected: ${picked}`;
+    }
     if (answer.index !== undefined) {
       return `${questionLabel}: user selected: ${String(answer.index)}. ${answer.label}`;
     }
@@ -302,6 +397,15 @@ function schemaErrorMessage(value: unknown): string {
     }
   }
 
+  const recommendedMatch = /\/questions\/(\d+)\/recommendedIndices$/.exec(
+    error.instancePath,
+  );
+  if (recommendedMatch !== null && error.keyword === 'minItems') {
+    const questionIndex = Number(recommendedMatch[1]);
+    const id = questionId(questions, questionIndex);
+    return `Error: Question '${id}' must mark at least one recommended option`;
+  }
+
   const tabLabelMatch = /\/questions\/(\d+)\/label$/.exec(error.instancePath);
   if (error.keyword === 'maxLength' && tabLabelMatch !== null) {
     const questionIndex = Number(tabLabelMatch[1]);

package/extensions/ask/selection.ts

@@ -0,0 +1,47 @@
+import type { AskAnswer, AskQuestion, AskSelection } from './model.ts';
+
+/**
+ * Sorted ascending so the answer and its rendering stay stable no matter the
+ * order the user toggled the options in.
+ */
+export function toggleSelection(
+  selected: readonly number[],
+  optionIndex: number,
+): number[] {
+  if (selected.includes(optionIndex)) {
+    return selected.filter((index) => index !== optionIndex);
+  }
+  return [...selected, optionIndex].sort((left, right) => left - right);
+}
+
+export function answerFromSelections(
+  question: AskQuestion,
+  selected: readonly number[],
+): AskAnswer {
+  const selections = selected.map((optionIndex) =>
+    toSelection(question, optionIndex),
+  );
+  const [first] = selections;
+  if (first === undefined) {
+    throw new Error(`Question '${question.id}' needs at least one selection`);
+  }
+  return {
+    id: question.id,
+    value: first.value,
+    label: first.label,
+    index: first.index,
+    wasCustom: false,
+    outOfScope: false,
+    selections,
+  };
+}
+
+function toSelection(question: AskQuestion, optionIndex: number): AskSelection {
+  const option = question.options[optionIndex];
+  if (option === undefined) {
+    throw new Error(
+      `Unknown option index ${String(optionIndex)} for question '${question.id}'`,
+    );
+  }
+  return { value: option.value, label: option.label, index: optionIndex + 1 };
+}

package/extensions/ask/ui.ts

@@ -11,9 +11,11 @@ import {
   type AskAnswer,
   type AskQuestion,
   type AskResult,
+  MULTIPLE_SELECTION_MODE,
   type RenderOption,
   renderOptions,
 } from './model.ts';
+import { answerFromSelections, toggleSelection } from './selection.ts';
 
 export async function runAskUi(
   ui: Pick<ExtensionUIContext, 'custom'>,
@@ -25,8 +27,7 @@ export async function runAskUi(
   return ui.custom<AskResult>((tui, theme, _keybindings, done) => {
     let currentTab = 0;
     const firstQuestion = questions[0];
-    let optionIndex =
-      firstQuestion === undefined ? 0 : firstQuestion.recommendationIndex;
+    let optionIndex = firstQuestion?.recommendedIndices[0] ?? 0;
     let inputMode = false;
     let inputQuestionId: string | null = null;
     let cachedLines: string[] | undefined;
@@ -82,11 +83,10 @@ export async function runAskUi(
         return;
       }
       const saved = answers.get(question.id);
-      if (saved?.index !== undefined) {
-        optionIndex = saved.index - 1;
-      } else {
-        optionIndex = question.recommendationIndex;
-      }
+      optionIndex =
+        saved?.index !== undefined
+          ? saved.index - 1
+          : (question.recommendedIndices[0] ?? 0);
       refresh();
     }
 
@@ -106,6 +106,45 @@ export async function runAskUi(
       answers.set(answer.id, answer);
     }
 
+    function selectedIndices(question: AskQuestion): readonly number[] {
+      const saved = answers.get(question.id);
+      if (saved?.selections === undefined) {
+        return [];
+      }
+      return saved.selections.map((selection) => selection.index - 1);
+    }
+
+    function answerSummary(answer: AskAnswer): string {
+      if (answer.selections === undefined || answer.selections.length === 0) {
+        return answer.label;
+      }
+      return answer.selections.map((selection) => selection.label).join(', ');
+    }
+
+    function isReservedOption(opt: RenderOption): boolean {
+      return opt.isOther === true || opt.isOutOfScope === true;
+    }
+
+    function activateReservedOption(
+      question: AskQuestion,
+      opt: RenderOption,
+      index: number,
+    ): void {
+      if (opt.isOther === true) {
+        openCustomEditor(question);
+        return;
+      }
+      saveAnswer({
+        id: question.id,
+        value: opt.value,
+        label: opt.label,
+        wasCustom: false,
+        outOfScope: true,
+        index: index + 1,
+      });
+      advanceAfterAnswer();
+    }
+
     function openCustomEditor(question: AskQuestion): void {
       inputMode = true;
       inputQuestionId = question.id;
@@ -127,20 +166,8 @@ export async function runAskUi(
       if (opt === undefined) {
         return;
       }
-      if (opt.isOther === true) {
-        openCustomEditor(question);
-        return;
-      }
-      if (opt.isOutOfScope === true) {
-        saveAnswer({
-          id: question.id,
-          value: opt.value,
-          label: opt.label,
-          wasCustom: false,
-          outOfScope: true,
-          index: index + 1,
-        });
-        advanceAfterAnswer();
+      if (isReservedOption(opt)) {
+        activateReservedOption(question, opt, index);
         return;
       }
       const original = question.options[index];
@@ -155,6 +182,49 @@ export async function runAskUi(
       advanceAfterAnswer();
     }
 
+    function toggleMultipleOption(
+      question: AskQuestion,
+      opts: readonly RenderOption[],
+      index: number,
+    ): void {
+      const opt = opts[index];
+      if (opt === undefined) {
+        return;
+      }
+      if (isReservedOption(opt)) {
+        activateReservedOption(question, opt, index);
+        return;
+      }
+      const next = toggleSelection(selectedIndices(question), index);
+      if (next.length === 0) {
+        answers.delete(question.id);
+        refresh();
+        return;
+      }
+      answers.set(question.id, answerFromSelections(question, next));
+      refresh();
+    }
+
+    function confirmMultipleSelection(
+      question: AskQuestion,
+      opts: readonly RenderOption[],
+      index: number,
+    ): void {
+      const opt = opts[index];
+      if (opt === undefined) {
+        return;
+      }
+      if (isReservedOption(opt)) {
+        activateReservedOption(question, opt, index);
+        return;
+      }
+      if (selectedIndices(question).length === 0) {
+        refresh();
+        return;
+      }
+      advanceAfterAnswer();
+    }
+
     editor.onSubmit = (value) => {
       if (inputQuestionId === null) {
         return;
@@ -232,15 +302,31 @@ export async function runAskUi(
         return;
       }
 
+      if (
+        question?.selectionMode === MULTIPLE_SELECTION_MODE &&
+        matchesKey(data, Key.space)
+      ) {
+        toggleMultipleOption(question, opts, optionIndex);
+        return;
+      }
+
       const digit = optionIndexFromDigit(data, opts.length);
       if (digit !== undefined && question !== undefined) {
         optionIndex = digit;
-        confirmOption(question, opts, digit);
+        if (question.selectionMode === MULTIPLE_SELECTION_MODE) {
+          toggleMultipleOption(question, opts, digit);
+        } else {
+          confirmOption(question, opts, digit);
+        }
         return;
       }
 
       if (matchesKey(data, Key.enter) && question !== undefined) {
-        confirmOption(question, opts, optionIndex);
+        if (question.selectionMode === MULTIPLE_SELECTION_MODE) {
+          confirmMultipleSelection(question, opts, optionIndex);
+        } else {
+          confirmOption(question, opts, optionIndex);
+        }
         return;
       }
 
@@ -310,7 +396,10 @@ export async function runAskUi(
         lines.push('');
       }
 
-      function renderOptionList(): void {
+      function renderOptionList(questionForList: AskQuestion): void {
+        const isMultipleAnswer =
+          questionForList.selectionMode === MULTIPLE_SELECTION_MODE;
+        const selected = selectedIndices(questionForList);
         for (let index = 0; index < opts.length; index += 1) {
           const opt = opts[index];
           if (opt === undefined) {
@@ -319,10 +408,16 @@ export async function runAskUi(
           if (opt.isOutOfScope === true) {
             lines.push('');
           }
-          const selected = index === optionIndex;
-          const prefix = selected ? theme.fg('accent', '> ') : '  ';
-          const color = selected ? 'accent' : 'text';
-          let line = theme.fg(color, `${String(index + 1)}. ${opt.label}`);
+          const focused = index === optionIndex;
+          const prefix = focused ? theme.fg('accent', '> ') : '  ';
+          const color = focused ? 'accent' : 'text';
+          let line = '';
+          if (isMultipleAnswer && !isReservedOption(opt)) {
+            line += selected.includes(index)
+              ? theme.fg('success', '[x] ')
+              : theme.fg('dim', '[ ] ');
+          }
+          line += theme.fg(color, `${String(index + 1)}. ${opt.label}`);
           if (opt.isRecommended === true) {
             line = `${line} ${theme.fg('dim', 'recommended')}`;
           }
@@ -367,7 +462,7 @@ export async function runAskUi(
           }
           addWrappedWithPrefix(
             ' ',
-            `${name}${theme.fg('dim', kind)}${theme.fg('text', answer.label)}`,
+            `${name}${theme.fg('dim', kind)}${theme.fg('text', answerSummary(answer))}`,
           );
         }
         lines.push('');
@@ -395,19 +490,31 @@ export async function runAskUi(
         if (saved !== undefined) {
           addWrappedWithPrefix(
             ' ',
-            theme.fg('muted', `Current: ${saved.label}`),
+            theme.fg('muted', `Current: ${answerSummary(saved)}`),
           );
         }
         lines.push('');
-        renderOptionList();
+        renderOptionList(question);
       }
 
       if (!inputMode && currentTab !== questions.length) {
         lines.push('');
+        if (
+          question?.selectionMode === MULTIPLE_SELECTION_MODE &&
+          selectedIndices(question).length === 0
+        ) {
+          addWrappedWithPrefix(
+            ' ',
+            theme.fg('warning', 'Select at least one option'),
+          );
+        }
         const count = String(opts.length);
-        const help = isMulti
-          ? `↑↓ or 1–${count} · Enter · Tab next · Esc cancel`
-          : `↑↓ or 1–${count} · Enter select · Esc cancel`;
+        let help = `↑↓ or 1–${count} · Enter select · Esc cancel`;
+        if (question?.selectionMode === MULTIPLE_SELECTION_MODE) {
+          help = `↑↓ or 1–${count} toggle · Space toggle · Enter confirm · Esc cancel`;
+        } else if (isMulti) {
+          help = `↑↓ or 1–${count} · Enter · Tab next · Esc cancel`;
+        }
         addWrappedWithPrefix(' ', theme.fg('dim', help));
       }
       lines.push(theme.fg('accent', '─'.repeat(renderWidth)));

package/extensions/todo/index.ts

@@ -18,6 +18,7 @@ import {
   TODO_WIDGET_REFRESH_EVENT,
   type TodoStore,
 } from './session.ts';
+import { createTodoBoardOverlayController } from './ui.ts';
 
 export const TODO_DESCRIPTION =
   'Maintain a live, user-visible work board. propose replaces the full board; update patches existing items by id.';
@@ -32,9 +33,12 @@ export const TODO_PROMPT_GUIDELINES = [
   'propose is interactive-TUI-only; update also works in print, JSON, and RPC modes.',
 ];
 
+const BOARD_SHORTCUT = 'f9';
+
 // Pi loads extensions/*/index.ts through export default.
 export default function registerTodo(pi: ExtensionAPI): void {
   const store = createTodoStore();
+  const overlay = createTodoBoardOverlayController(() => store.items);
   const restore: BoardLifecycle = (ctx) => {
     restoreBoard(store, ctx);
   };
@@ -50,6 +54,10 @@ export default function registerTodo(pi: ExtensionAPI): void {
   registerGuardEvents(pi, store, restore);
   registerBoardContext(pi, store, restoreAndRefresh);
   registerTodoTool(pi, store, notifyWidgetRefresh);
+  pi.registerShortcut(BOARD_SHORTCUT, {
+    description: 'Toggle the work board',
+    handler: (ctx) => overlay.toggle(ctx),
+  });
 }
 
 function registerTodoTool(

package/extensions/todo/ui.ts

@@ -1,5 +1,48 @@
-import type { Theme } from '@earendil-works/pi-coding-agent';
-import { formatBoardBlock, TODO_STATUS, type TodoItem } from './model.ts';
+import type { ExtensionContext, Theme } from '@earendil-works/pi-coding-agent';
+import {
+  type Component,
+  Key,
+  matchesKey,
+  type TUI,
+  truncateToWidth,
+} from '@earendil-works/pi-tui';
+import {
+  formatBoardBlock,
+  TODO_STATUS,
+  type TodoItem,
+  type TodoStatus,
+} from './model.ts';
+
+const COMPACT_ROW_LIMIT = 5;
+const EXTENDED_ROW_LIMIT = 12;
+
+const SELECTION_RANK = {
+  inProgress: 0,
+  pending: 1,
+  resolved: 2,
+} as const;
+
+export interface VisibleBoardRows {
+  readonly indexes: readonly number[];
+  readonly hiddenCount: number;
+}
+
+export function selectVisibleBoardRows(
+  items: readonly TodoItem[],
+  limit: number,
+): VisibleBoardRows {
+  if (items.length <= limit) {
+    return { indexes: items.map((_item, index) => index), hiddenCount: 0 };
+  }
+
+  const indexes = items
+    .map((item, index) => ({ index, rank: selectionRank(item) }))
+    .sort((left, right) => left.rank - right.rank || left.index - right.index)
+    .slice(0, limit)
+    .map((row) => row.index)
+    .sort((left, right) => left - right);
+  return { indexes, hiddenCount: items.length - indexes.length };
+}
 
 export function renderTodoWidget(
   items: readonly TodoItem[],
@@ -9,33 +52,199 @@ export function renderTodoWidget(
     return undefined;
   }
 
+  const rows = boardRowLines(items);
+  const visible = selectVisibleBoardRows(items, COMPACT_ROW_LIMIT);
+  const renderedRows = visible.indexes.flatMap((index) => {
+    const item = items[index];
+    const row = rows[index];
+    if (item === undefined || row === undefined) {
+      return [];
+    }
+    return [colorizeBoardRow(row, item.status, theme)];
+  });
+  const lines = [
+    theme.fg('accent', theme.bold(boardHeader(items))),
+    ...renderedRows,
+  ];
+  if (visible.hiddenCount > 0) {
+    lines.push(theme.fg('dim', hiddenRowsHint(visible.hiddenCount)));
+  }
+  return lines;
+}
+
+export interface TodoBoardOverlayController {
+  toggle(ctx: ExtensionContext): void;
+}
+
+export function createTodoBoardOverlayController(
+  items: () => readonly TodoItem[],
+): TodoBoardOverlayController {
+  let close: (() => void) | undefined;
+  let opening = false;
+
+  return {
+    toggle(ctx) {
+      if (close !== undefined) {
+        close();
+        return;
+      }
+      if (opening || ctx.mode !== 'tui') {
+        return;
+      }
+
+      opening = true;
+      void ctx.ui
+        .custom<void>(
+          (tui, theme, _keybindings, done) => {
+            close = done;
+            return new TodoBoardOverlay(tui, items, theme, done);
+          },
+          {
+            overlay: true,
+            overlayOptions: {
+              anchor: 'center',
+              width: '70%',
+              minWidth: 40,
+              maxHeight: '80%',
+              visible: (terminalWidth) => terminalWidth >= 60,
+            },
+          },
+        )
+        .finally(() => {
+          close = undefined;
+          opening = false;
+        });
+    },
+  };
+}
+
+export class TodoBoardOverlay implements Component {
+  private offset = 0;
+  private readonly tui: TUI;
+  private readonly items: () => readonly TodoItem[];
+  private readonly theme: Theme;
+  private readonly close: () => void;
+
+  constructor(
+    tui: TUI,
+    items: () => readonly TodoItem[],
+    theme: Theme,
+    close: () => void,
+  ) {
+    this.tui = tui;
+    this.items = items;
+    this.theme = theme;
+    this.close = close;
+  }
+
+  handleInput(data: string): void {
+    const maxOffset = Math.max(0, this.items().length - EXTENDED_ROW_LIMIT);
+    if (matchesKey(data, Key.escape) || matchesKey(data, Key.f9)) {
+      this.close();
+      return;
+    }
+    if (matchesKey(data, Key.up)) {
+      this.offset = Math.max(0, this.offset - 1);
+      this.tui.requestRender();
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.offset = Math.min(maxOffset, this.offset + 1);
+      this.tui.requestRender();
+      return;
+    }
+    if (matchesKey(data, Key.pageUp)) {
+      this.offset = Math.max(0, this.offset - EXTENDED_ROW_LIMIT);
+      this.tui.requestRender();
+      return;
+    }
+    if (matchesKey(data, Key.pageDown)) {
+      this.offset = Math.min(maxOffset, this.offset + EXTENDED_ROW_LIMIT);
+      this.tui.requestRender();
+    }
+  }
+
+  render(width: number): string[] {
+    const innerWidth = Math.max(1, width - 2);
+    const items = this.items();
+    const rows = boardRowLines(items);
+    const visibleRows = items
+      .map((item, index) => ({ item, row: rows[index] }))
+      .slice(this.offset, this.offset + EXTENDED_ROW_LIMIT);
+    const border = (text: string) => this.theme.fg('border', text);
+    const line = (text: string) => truncateToWidth(text, innerWidth, '…', true);
+    const title = line(` Work board (${String(items.length)}) `);
+    const lines = [
+      border(`╭${'─'.repeat(innerWidth)}╮`),
+      `${border('│')}${line(this.theme.fg('accent', this.theme.bold(title)))}${border('│')}`,
+      `${border('├')}${border('─'.repeat(innerWidth))}${border('┤')}`,
+    ];
+
+    for (const entry of visibleRows) {
+      const row =
+        entry.row === undefined
+          ? ''
+          : colorizeBoardRow(entry.row, entry.item.status, this.theme);
+      lines.push(`${border('│')}${line(row)}${border('│')}`);
+    }
+    if (items.length === 0) {
+      lines.push(
+        `${border('│')}${line(this.theme.fg('muted', ' No items on the board.'))}${border('│')}`,
+      );
+    }
+
+    const scrollHint = items.length > EXTENDED_ROW_LIMIT ? ' ↑↓ scroll ·' : '';
+    lines.push(`${border('├')}${border('─'.repeat(innerWidth))}${border('┤')}`);
+    lines.push(
+      `${border('│')}${line(this.theme.fg('dim', `${scrollHint} F9 or Esc close`))}${border('│')}`,
+    );
+    lines.push(border(`╰${'─'.repeat(innerWidth)}╯`));
+    return lines;
+  }
+
+  invalidate(): void {}
+}
+
+function selectionRank(item: TodoItem): number {
+  if (item.status === TODO_STATUS.inProgress) {
+    return SELECTION_RANK.inProgress;
+  }
+  if (item.status === TODO_STATUS.pending) {
+    return SELECTION_RANK.pending;
+  }
+  return SELECTION_RANK.resolved;
+}
+
+function boardHeader(items: readonly TodoItem[]): string {
   const active = items.filter(
     (item) => item.status === TODO_STATUS.inProgress,
   ).length;
   const queued = items.filter(
     (item) => item.status === TODO_STATUS.pending,
   ).length;
-  const blockLines = formatBoardBlock(items).split('\n');
-  const rows = blockLines.slice(1, 1 + items.length);
-  const header = theme.fg(
-    'accent',
-    theme.bold(
-      `Sideroom board (${String(active)} active, ${String(queued)} queued)`,
-    ),
-  );
-  const renderedRows = rows.map((row, index) => {
-    const item = items[index];
-    if (item === undefined) {
-      return row;
-    }
-    if (item.status === TODO_STATUS.inProgress) {
-      return theme.fg('success', row);
-    }
-    if (item.status === TODO_STATUS.pending) {
-      return theme.fg('text', row);
-    }
-    return theme.fg('muted', row);
-  });
+  return `Sideroom board (${String(active)} active, ${String(queued)} queued)`;
+}
+
+function boardRowLines(items: readonly TodoItem[]): string[] {
+  return formatBoardBlock(items)
+    .split('\n')
+    .slice(1, 1 + items.length);
+}
+
+function colorizeBoardRow(
+  row: string,
+  status: TodoStatus,
+  theme: Theme,
+): string {
+  if (status === TODO_STATUS.inProgress) {
+    return theme.fg('success', row);
+  }
+  if (status === TODO_STATUS.pending) {
+    return theme.fg('text', row);
+  }
+  return theme.fg('muted', row);
+}
 
-  return [header, ...renderedRows];
+function hiddenRowsHint(hiddenCount: number): string {
+  return `…+${String(hiddenCount)} more · F9: view all`;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "8.1.1",
-  "description": "A global Pi package with a questionnaire, work board, edited-file view, coding guidelines, rule enforcement, and a finish gate for parent agents.",
+  "version": "8.3.0",
+  "description": "Pi coding-agent package that asks clarifying questions, shows a live todo board, enforces coding guidelines, and will not call it done while your checks are red.",
   "type": "module",
   "files": [
     "extensions",
@@ -16,11 +16,12 @@
     "version-packages": "changeset version",
     "commitlint": "commitlint",
     "types": "tsc --noEmit",
-    "test": "node --test 'extensions/**/*.test.ts'",
+    "test": "node --test 'extensions/**/*.test.ts' 'scripts/**/*.test.mjs'",
     "lint": "biome lint extensions scripts commitlint.config.mjs",
     "lint:fix": "biome lint --write extensions scripts commitlint.config.mjs",
     "format": "biome format --write extensions scripts package.json biome.json commitlint.config.mjs .changeset/config.json",
     "format:check": "biome format extensions scripts package.json biome.json commitlint.config.mjs .changeset/config.json",
+    "preview": "node scripts/render-preview.mjs",
     "check:if-blocks": "node scripts/check-if-blocks.mjs",
     "check": "npm run types && npm run check:if-blocks && biome check extensions scripts package.json biome.json commitlint.config.mjs .changeset/config.json && npm test"
   },
@@ -31,13 +32,31 @@
     "pi",
     "pi-package",
     "pi-extension",
+    "pi-skill",
+    "coding-agent",
+    "questions",
+    "clarifying-questions",
     "questionnaire",
+    "planning",
+    "spec",
     "todo",
+    "task-board",
+    "progress",
     "edited-files",
-    "sideroom_ask",
-    "sideroom_todo",
     "guidelines",
-    "typescript"
+    "code-style",
+    "code-quality",
+    "guardrails",
+    "rules",
+    "linting",
+    "testing",
+    "done",
+    "skills",
+    "typescript",
+    "tui",
+    "claude",
+    "sideroom_ask",
+    "sideroom_todo"
   ],
   "license": "MIT",
   "repository": {
@@ -53,7 +72,9 @@
     ],
     "skills": [
       "./skills"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/RMRdeveloper/sideroom-pi/main/media/preview.png",
+    "video": "https://raw.githubusercontent.com/RMRdeveloper/sideroom-pi/main/media/preview.mp4"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/skills/sideroom-grill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sideroom-grill
-description: "Interview the user in rounds to resolve a fuzzy plan, design decision, or domain-language conflict before implementation. Use when the user asks to be grilled, wants clarifying questions, or says the plan or terms are not settled. Do not use for a code-first repository scan or a simple glossary lookup."
+description: "Default interview route before implementation: grill the user in sideroom_ask rounds to settle a non-trivial plan, feature, or decision, and resolve domain-language conflicts along the way. Use whenever a change is not trivial and is not yet a settled spec, or when the user asks to be grilled, wants clarifying questions, or says the plan or terms are not settled. Prefer this skill over any other grilling, interview, or spec skill when more than one is available. Do not use when the user already brought a closed spec or tickets, for a code-first repository scan, or for a simple glossary lookup."
 license: MIT
 metadata:
   author: RMRdeveloper
@@ -19,9 +19,10 @@ if the effort is too big to hold in one session, say so and stop.
 
 - Interview in rounds. One `sideroom_ask` call is one round; wait for its
   answers before the next round.
-- Every question carries a recommendation (`recommendationIndex`). Write
-  prompts and option copy in the language the user is speaking; keep ids and
-  option values in English.
+- Every question carries a recommendation: `recommendationIndex` for a
+  single-selection question, or `recommendedIndices` (at least one) when the
+  question declares `selectionMode: "multiple"`. Write prompts and option copy
+  in the language the user is speaking; keep ids and option values in English.
 - Never ask the user what the codebase can answer. Read the code first; ask
   only what the code cannot settle.
 - An *Out of scope* answer closes that thread. Do not re-ask it.