pi-soly 1.12.0 → 1.12.1

package/ask/index.ts

@@ -71,7 +71,7 @@ export default function piAskExtension(pi: ExtensionAPI) {
 		name: "ask_pro",
 		label: "soly · ask_pro",
 		description:
-			"Ask the user several questions at once via a tabbed picker; returns all answers in one call. Per question: single-select (default), `multiSelect` (+ `minSelect`/`maxSelect`), `allowOther` (free-text choice), or `freeText` (typed answer, no options). Per option: `recommended` (⭐) and `preview` (side panel, fenced code highlighted). User can skip (`s`) or note (`n`). Prefer over one-by-one questions; good for `soly discuss`.",
+			"Ask the user one or more questions at once via a tabbed picker (≤6 questions); returns all answers in one call. USE WHEN: (a) you have 2+ related questions to gather in one batch, OR (b) you have ONE simple choice among 2-4 options where each option is a short label + 1-2 sentence description (no per-option code, no pros/cons). For ONE architectural/design comparison where each option needs its own code + pros/cons card on a full screen, use `decision_deck` instead. Per question: single-select (default), `multiSelect` (+ `minSelect`/`maxSelect`), `allowOther` (free-text 'Other…'), or `freeText` (typed answer, no options). Per option: `recommended` (⭐) and `preview` (side panel, fenced code highlighted). User can skip (`s`) or note (`n`). Prefer this over one-by-one questions.",
 		parameters: Type.Object({
 			questions: Type.Array(
 				Type.Object({

package/deck/index.ts

@@ -24,7 +24,7 @@ export default function piDeckExtension(pi: ExtensionAPI) {
 		name: "decision_deck",
 		label: "soly · decision_deck",
 		description:
-			"Present ONE design/architecture decision as a full-screen deck of cards (one per option) the user flips through (←/→ or 1-N) and picks with Enter. Use instead of ask_pro when the choice hinges on comparing each option's concrete code shape, not a label. 2-6 options. The user can attach a free-text note (rationale, caveats) via `n`; it's returned in the result. Native TUI. Returns the chosen option.",
+			"Present ONE design/architecture decision as a full-screen deck of cards (one per option) the user flips through (←/→ or 1-N) and picks with Enter. Use when 2-6 options each need their own card with code + pros/cons to be properly compared (e.g. architectural forks, API shapes, data-model choices). STRICTLY ONE question per call — for 2+ related questions in one batch, use `ask_pro` instead. Each option SHOULD carry either a non-trivial code snippet or explicit pros/cons; for plain label-vs-label choices, `ask_pro` is lighter. The user can attach a free-text note (rationale, caveats) via `n`; it's returned in the result. Native TUI. Returns the chosen option.",
 		parameters: Type.Object({
 			title: Type.Optional(Type.String({ description: "Decision title." })),
 			prompt: Type.Optional(Type.String({ description: "Question shown above the cards." })),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "1.12.0",
+  "version": "1.12.1",
   "description": "Project management + workflow framework for pi-coding-agent. Plans, state, MANDATORY rules, self-review, multi-question picker, native footer + welcome chrome — one npm install, zero config. The LLM drives execution and delegates to a worker subagent when available.",
   "type": "module",
   "main": "index.ts",

package/tool-hints.ts

@@ -52,9 +52,9 @@ export function buildToolHintSection(h: ToolHint): string | null {
 	if (h.artifact)
 		bits.push("- Examples / a table / a visual result: **ask the user first** — render it in the browser as an artifact (`html_artifact`), or just as text here? Then proceed accordingly.");
 	if (h.deck)
-		bits.push("- Comparing options/alternatives: **ask the user first** — show them as a full-screen deck (`decision_deck`, code + pros/cons), or inline as text? Then proceed.");
+		bits.push("- Comparing 2-6 options: if it's ONE question and each option needs code + pros/cons on its own card → use `decision_deck`. If it's 2+ related questions in one batch → use `ask_pro`. **Default to `ask_pro` unless you have explicit code or trade-offs per option.** Never use `decision_deck` for 2+ questions.");
 	if (h.ask)
-		bits.push("- Several things to clarify → use `ask_pro` (one batched picker).");
+		bits.push("- Several things to clarify → use `ask_pro` (one batched picker). `decision_deck` does NOT support multi-question — never reach for it here.");
 	if (bits.length === 0) return null;
 	return `\n## soly — interactive output for this turn\n\n${bits.join(
 		"\n",