pi-soly 1.11.2 → 1.12.0

package/skills/soly-framework/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: soly-framework
+description: Use when the user invokes soly workflow commands (`/plan`, `/execute`, `/discuss`, `/inspect`, `/pause`, `/resume`, `/quick`, `/soly-init`, `/soly-migrate`, `/soly-status`, `/soly-log`) or asks how to use soly in pi-coding-agent — phases, plans, tasks, intent docs, ROADMAP/STATE state machine, rules, close-out order, and the available soly_* tools. Loaded as the complete reference for managing a soly project end-to-end (init → plan → execute → summary → state update).
+priority: high
+---
+
 # soly framework
 
 The **soly** extension adds project-management workflow to [pi-coding-agent](https://github.com/nicobailon/pi-coding-agent): intent docs, ROADMAP/STATE/PHASE state machine, and LLM-driven plan execution. This skill is your complete reference for using it.
@@ -10,40 +16,49 @@ The **soly** extension adds project-management workflow to [pi-coding-agent](htt
 2. **Project state** (`.soly/STATE.md`, `ROADMAP.md`) — where we are, current phase, recent decisions.
 3. **Project rules** (`.soly/rules/`, `~/.soly/rules/`) — how to behave in this project.
 
-**Workflow model — phases and plans:**
-
-- A **phase** is a milestone (e.g. "01-foundation"). Has one or more `PLAN.md` files.
-- A **plan** is one ordered execution unit. Has `<task>` blocks.
-- A **task** is the smallest unit. Has type, description, verify, accept.
-- **Close-out**: production code commits → `SUMMARY.md` → `STATE.md` updated → ROADMAP check.
+**Workflow model — phases and tasks (unified):**
 
-## Quick reference — slash commands
+- A **phase** is a milestone (e.g. "01-foundation"). It groups **tasks** under `phases/<NN>-<slug>/tasks/`.
+- A **task** is the unit of execution: its own dir with `PLAN.md` (frontmatter: `id`, `kind`, `status`, `depends-on`, optional `feature`) and, when done, `SUMMARY.md`. Tasks run in dependency order.
+- `soly plan <N>` writes a phase's tasks · `soly execute <N>` runs its ready tasks (deps met) in order · `soly verify` reviews.
+- **Close-out** (per task): production commits → task `SUMMARY.md` → flip `status: done` → `STATE.md` / ROADMAP check.
+- Legacy projects (standalone `NN-MM-PLAN.md` files, or a `features/` dir) still load and run; `soly migrate` converts them to this layout.
 
-| Command | What it does |
-|---|---|
-| `/plan [N]` | Generate or update `PLAN.md` for phase N (or current phase) |
-| `/execute [N[.MM]]` | Execute plan(s) in phase N. `N` = all plans. `N.MM` = specific plan. The LLM (you) executes directly. |
-| `/discuss N` | Discussion-driven scoping for phase N — capture decisions before planning |
-| `/inspect` | One-screen summary: position, phases, recent decisions |
-| `/pause` | Save handoff (`HANDOFF.json` + `.continue-here.md`) for later resume |
-| `/resume` | Restore from a paused handoff |
-| `/quick <task>` | One-shot task that doesn't need a full plan — direct dispatch |
-| `/soly` | Project state inspection (alias for `/inspect`) |
-| `/why` | Show what context the LLM's last turn was based on |
-| `/soly-init` | Scaffold a new soly project (interactive template picker) |
-| `/soly-migrate` | Move legacy `.soly/` to `.agents/` (atomic) |
-| `/soly-status` | Comprehensive one-screen report |
-| `/soly-log [N]` | Show last N notifications from the log |
+## Commands
 
-`/soly <verb>` plain-text aliases also work for some verbs (legacy compat).
+Workflow verbs are **plain text** — type `soly <verb>` (NOT a slash command):
 
-## No rotors (removed in 1.4.0)
-
-As of 1.4.0, soly no longer ships rotors. No `/rotor` command, no `Ctrl+Tab` cycle, no footer pill. The LLM picks the right subagent based on the task brief — use `subagent(...)` with `agent: "worker"` for implementation, `"oracle"` for decisions, `"scout"` for recon, `"reviewer"` for adversarial review.
+| Verb | What it does |
+|---|---|
+| `soly discuss <N>` | Discussion-driven scoping for phase N — interactive, uses the `ask_pro` picker |
+| `soly plan <N>` | Generate `PLAN.md` for phase N (also `<task-id>`, `--new-task`, `--feature`) |
+| `soly execute <N[.MM]>` | Execute a phase / one plan / a task / `--all` / `--feature` |
+| `soly verify [N] [fresh]` | Self-review loop until "No issues found." (max N; `verify stop` to exit; `fresh` = fresh-context) |
+| `soly pause` · `soly compact` | Save a handoff (compact also compresses the session) |
+| `soly resume [N]` | Restore from a handoff |
+| `soly status` · `log` · `diff` · `doctor` · `iterations` · `todos` | Quick read-outs (no LLM round-trip) |
 
-**Why drop them?** Rotors were a UX shortcut (Ctrl+Tab) that pi itself doesn't support well. pi has its own subagent system (`worker`, `oracle`, `scout`, `reviewer`); wrapping it in a "cycle" was over-engineering. The LLM in the main session is the executor; pi's subagents are helpers, not cycle modes.
+**Slash commands** (pi's command surface):
 
-**For soly work**, the LLM does the work itself — it reads PLAN.md, runs commands, commits, writes SUMMARY.md. It does NOT spawn a soly subagent. Use `subagent(...)` only for read-only research (e.g. `agent: "scout"` for "find all files using X").
+| Command | What it does |
+|---|---|
+| `/rules` · `/docs` | Open the rules / intent-docs **modal** (fuzzy list + preview; `e/d/r` enable·disable·reload on rules). A subcommand (`/rules stats`, `/docs stats`, …) prints to chat instead of opening the modal. |
+| `/soly [<sub>]` | Project-state inspection (position, state, plan, roadmap, phases, tasks, …); bare `/soly` opens the picker |
+| `/soly-init` · `/soly-migrate` | Scaffold a project · migrate `.soly/` → `.agents/` |
+| `/why` | What rules + state grounded the last turn |
+| `/rulewizard` | Rule vs .editorconfig vs linter guide |
+
+## Delegation
+
+`soly plan` and `soly execute` delegate the heavy work to a `worker` subagent
+(via the `subagent(...)` tool from pi-subagents); the parent session keeps the
+close-out (production commits → `SUMMARY.md` → `STATE.md` → then `soly verify`).
+If the `subagent` tool is NOT installed they run **inline** in the main session
+instead — `soly doctor` reports which mode is active. First-party delegation is
+on the roadmap. Other agents are read-only helpers: `oracle` (second opinion),
+`scout` (recon), `reviewer` (adversarial review). `soly discuss` is always
+interactive in the main session (not delegated). Rotors / `Ctrl+Tab` cycling
+were removed in 1.4.0.
 
 ## File structure
 
@@ -64,10 +79,12 @@ As of 1.4.0, soly no longer ships rotors. No `/rotor` command, no `Ctrl+Tab` cyc
 │   │   ├── 01-foundation/
 │   │   │   ├── 01-CONTEXT.md     # domain + decisions for phase 1
 │   │   │   ├── 01-RESEARCH.md    # what we looked up
-│   │   │   ├── 01-PLAN-01.md     # plan 1
-│   │   │   ├── 01-PLAN-01-SUMMARY.md
-│   │   │   ├── 01-PLAN-02.md
-│   │   │   └── 01-PLAN-02-SUMMARY.md
+│   │   │   └── tasks/            # unified model: one dir per task
+│   │   │       ├── auth-login-a3f9/
+│   │   │       │   ├── PLAN.md   # frontmatter: id, kind, status, depends-on
+│   │   │       │   └── SUMMARY.md
+│   │   │       └── auth-token-b1c2/
+│   │   │           └── PLAN.md
 │   │   └── 02-feature-x/
 │   │       └── ...
 │   ├── iterations/                # per-execution context bundles (auto)
@@ -211,10 +228,22 @@ Once production commits exist, returning without a committed `SUMMARY.md` is an
 | `soly_env()` | Detect runtime (package manager, runtimes, services, scripts) |
 | `soly_snippet(path, offset, limit)` | Read bounded line range with line numbers |
 | `soly_doc_search(query, limit)` | Search .md/.html under cwd (prioritizes intent docs) |
-| `soly_intent()` | List 0-point intent docs from `.soly/docs/` |
 | `soly_scratchpad(limit)` | Recent conversation recap (one line per turn) |
-| `ask_pro(questions)` | Multi-question picker (tabbed, single/multi-select, ⭐, Other…) |
-| `todo_update(todos)` | Update task list rendered in footer |
+| `ask_pro(questions)` | Multi-question picker (tabbed, single/multi-select, ⭐, `preview` w/ code highlight, `allowOther`, `freeText`, `minSelect`/`maxSelect`, `s` to skip, notes) — preferred for structured input |
+| `decision_deck(options)` | Full-screen TUI deck — one card per option with a highlighted code snippet + pros/cons. For design/architecture forks where the choice hinges on the concrete code shape |
+| `html_artifact(title, html, id?, assets?)` | Render HTML (full doc or body fragment) and serve it from a per-session browser gallery SPA (sidebar + iframe + filter + live updates, one stable URL) — soly's "artifacts". `id` updates in place; `assets` writes sibling files. For visual output: example galleries, comparisons, diagrams |
+| `soly_save_discuss_checkpoint(...)` · `soly_finish_discuss(...)` | Save / finalize a `soly discuss` session (writes CONTEXT.md) |
+| `soly_ask_user(...)` | Single-question picker — **deprecated**, prefer `ask_pro` |
+
+### Visual & interaction tools — when to reach for each
+
+The main system prompt only points at these; the detail is here.
+
+**`ask_pro`** — multi-question picker. Use for 1–6 related questions where the user picks concrete answers to move forward (e.g. `soly discuss` scoping). NOT for simple yes/no, a single open-ended prompt, questions already answered, or trivial clarifications — use plain text. Per option, `preview` shows a side panel while focused (put a code/API/config snippet there; fenced ```code is highlighted). `freeText` = optional typed answer; `allowOther` = escape hatch; `minSelect`/`maxSelect` bound multi-select. The user can skip (`s`, returned `(skipped)`) or note (`n`, returned `// note:` — treat as a hard constraint).
+
+**`decision_deck`** — full-screen cards (one per option) with a highlighted code snippet + pros/cons. Reach for it when the choice hinges on the concrete code/structure of each option, not a label, and there are 2–6 alternatives worth comparing side-by-side. Prefer `ask_pro` for short-label choices; don't use it for trivial/yes-no.
+
+**`html_artifact`** — render HTML served from a per-session browser gallery SPA (sidebar + iframe + filter + live SSE updates, one stable localhost URL). Use when a visual rendered result beats terminal text: example galleries, before/after or side-by-side comparisons, tables, diagrams, a small HTML/CSS/SVG demo. Pass `title` + `html` (a body fragment is fine — it's wrapped in a themed skeleton; put code in `<pre><code>`). Pass `id` to re-render/update an artifact in place (instead of piling up copies); pass `assets: [{path, content, encoding?}]` to write sibling files the HTML references by relative path (e.g. an image or `data.json`). The theme is overridable per project via `.soly/artifact-theme.css`. Keep it self-contained unless you use `assets` — no external/CDN requests. Don't use it for a single snippet (markdown code block) or prose. Mention the returned URL to the user.
 
 ## Common workflows
 
@@ -247,8 +276,6 @@ You are a data scientist. ...
 3. `~/.agents/` — user vendor-neutral (preferred)
 4. `~/.pi/agent/agents/` — user pi native (legacy)
 
-`Ctrl+Tab` to see them in the cycle. (Removed in 1.4.0 — use `subagent(...)` directly.)
-
 ### Add a feature to an existing phase
 
 1. `/plan 1.05` (next plan number)

package/tool-hints.ts

@@ -0,0 +1,62 @@
+// =============================================================================
+// tool-hints.ts — per-turn affordance hints for soly's interactive tools
+// =============================================================================
+//
+// Scans the user's prompt for trigger words (bilingual RU/EN) and, when matched,
+// returns a small system-prompt section nudging the LLM to consider the right
+// interactive tool: html_artifact (examples / visual output), decision_deck
+// (comparing options), or ask_pro (clarifying questions).
+//
+// Soft + dynamic: the hint is only injected on turns that actually mention these
+// things (zero token cost otherwise) and explicitly says "only if it helps", so
+// it steers without forcing. Pure: prompt string in, hint string out.
+// =============================================================================
+
+export type ToolHint = { artifact: boolean; deck: boolean; ask: boolean };
+
+// Trigger words. Stems chosen to catch RU inflections (вариант/варианты/…) and
+// common EN forms. Kept narrow enough to avoid firing on every prompt.
+const TRIGGERS = {
+	artifact: [
+		/пример/i, /образец/i, /галере/i, /шпаргалк/i, /таблиц/i, /диаграмм/i,
+		/визуализ/i, /макет/i, /дашборд/i,
+		/\bexamples?\b/i, /\bsamples?\b/i, /\bdemo\b/i, /\bgallery\b/i,
+		/cheat\s*sheet/i, /\btables?\b/i, /\bdiagram/i, /\bvisuali[sz]/i,
+		/\bmock\s?up/i, /\bdashboard\b/i,
+	],
+	deck: [
+		/вариант/i, /сравн/i, /альтернатив/i, /\bлибо\b/i, /какой подход/i,
+		/что лучше/i, /выбрать (?:между|из)/i,
+		/\boptions?\b/i, /\bcompare\b/i, /\bcomparison\b/i, /\bvs\.?\b/i,
+		/\btrade-?offs?\b/i, /which approach/i, /\bpros and cons\b/i,
+	],
+	ask: [
+		/уточн/i, /несколько вопрос/i, /опросник/i,
+		/\bclarif/i, /\ba few questions\b/i,
+	],
+};
+
+/** Which interactive tools the prompt's wording hints at. */
+export function detectToolHints(prompt: string): ToolHint {
+	const has = (res: RegExp[]): boolean => res.some((r) => r.test(prompt));
+	return {
+		artifact: has(TRIGGERS.artifact),
+		deck: has(TRIGGERS.deck),
+		ask: has(TRIGGERS.ask),
+	};
+}
+
+/** Build the affordance section, or null when nothing matched. */
+export function buildToolHintSection(h: ToolHint): string | null {
+	const bits: string[] = [];
+	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.");
+	if (h.ask)
+		bits.push("- Several things to clarify → use `ask_pro` (one batched picker).");
+	if (bits.length === 0) return null;
+	return `\n## soly — interactive output for this turn\n\n${bits.join(
+		"\n",
+	)}\nAsk once and briefly (a one-line question is fine). If the content is tiny or the format is obvious, just answer in text.`;
+}

package/tools.ts

@@ -22,7 +22,6 @@ import { detectEnv, type EnvSummary } from "./env.ts";
 import type { SolyConfig } from "./config.ts";
 import { buildDocIndex, searchDocs, readSnippet, stripHtml } from "./docs.ts";
 import { buildScratchpad, SCRATCHPAD_LIMITS } from "./scratchpad.ts";
-import { loadIntentDocs, buildIntentSection, type IntentDoc } from "./intent.ts";
 
 const execFileAsync = promisify(execFile);
 
@@ -67,7 +66,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_read",
 		label: "soly read",
 		description:
-			"read a .soly/ artifact. Use when you need to inspect what the project knows — current state, the active plan, phase context/research, the roadmap, requirements, project overview, or milestone. Pass `phase` (number) to target a specific phase's plan/context/research; defaults to the current phase. Returns the file content as text.",
+			"Read a .soly/ artifact (state, plan, context, research, roadmap, requirements, project, milestone, task). `phase` targets a specific phase (default: current); `taskId` for the task artifact. Returns the file text.",
 		parameters: Type.Object({
 			artifact: StringEnum([
 				"state",
@@ -190,7 +189,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_log_decision",
 		label: "soly log decision",
 		description:
-			"append a row to the Decisions table in .soly/STATE.md (creates the table if missing). Use this for meaningful choices the future-you should know about — scope cuts, library picks, trade-off resolutions. Pass `phase` (number) to attach to a specific phase; defaults to the current phase. Decision and rationale should each be one line.",
+			"Append a one-line decision + rationale to the Decisions table in .soly/STATE.md (creates it if missing). For meaningful choices: scope cuts, library picks, trade-offs. `phase` defaults to current.",
 		parameters: Type.Object({
 			decision: Type.String({ description: "The decision made (one line)." }),
 			rationale: Type.String({ description: "Why this decision was made (one line)." }),
@@ -275,7 +274,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_list_tasks",
 		label: "soly list tasks",
 		description:
-			"list all tasks across all features with kind, status, priority, and dependencies. Use when you need an overview of available tasks — e.g. before `soly execute <task-id>` or `soly execute --all`.",
+			"List all tasks across features (kind, status, priority, deps). Use before `soly execute <task-id>` / `--all`.",
 		parameters: Type.Object({}),
 		async execute(_id, _params, _signal, _onUpdate, _ctx) {
 			const state = getState();
@@ -301,7 +300,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_list_phases",
 		label: "soly list phases",
 		description:
-			"list all phases in .soly/phases/ with plan count, CONTEXT/RESEARCH presence markers (C/R), and the current position marker (→). Use when you need an overview of which phases exist, which have plans, and which have research/context notes — e.g. before suggesting `soly plan <N>` or `soly execute <N>`.",
+			"List phases with plan count, C/R (context/research) markers, and current-position marker (→). Use before `soly plan <N>` / `execute <N>`.",
 		parameters: Type.Object({}),
 		async execute(_id, _params, _signal, _onUpdate, _ctx) {
 			const state = getState();
@@ -330,7 +329,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_todos",
 		label: "soly todos",
 		description:
-			"scan the working tree for TODO / FIXME / HACK / XXX / NOTE comments, grouped by file. Use for a quick audit of outstanding cleanup work. Scans .ts/.tsx/.js/.jsx/.py/.go/.rs only, excluding node_modules, .git, dist, build, .soly, coverage. Requires `rg` (ripgrep) on PATH — silently returns empty if missing. Pass `paths` to override the scan root, `limit` to cap (default 200).",
+			"Scan the tree for TODO/FIXME/HACK/XXX/NOTE comments, grouped by file (common source extensions; excludes node_modules/.git/dist/build/.soly). Needs ripgrep on PATH. `paths` overrides root, `limit` caps (default 200).",
 		parameters: Type.Object({
 			paths: Type.Optional(
 				Type.Array(Type.String(), {
@@ -462,7 +461,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_env",
 		label: "soly env",
 		description:
-			"detect the project's runtime environment and return it as a one-screen summary. Use to answer 'what test runner?', 'is docker used here?', 'what's the package manager?' etc. Detects: package manager, runtimes (node/bun), key dependencies, available scripts (dev/build/test/lint/...), services (postgres/redis/etc from compose), tooling flags (ts/tests/docker/ci).",
+			"Detect the project's environment as a one-screen summary: package manager, runtimes, key deps, scripts, services (from compose), and tooling flags (ts/tests/docker/ci). Answers 'what test runner / package manager / is docker used'.",
 		parameters: Type.Object({}),
 		async execute(_id, _params, _signal, _onUpdate, ctx) {
 			const env = detectEnv(ctx.cwd);
@@ -500,19 +499,14 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_snippet",
 		label: "soly snippet",
 		description:
-			"read a bounded range of lines from a file with line numbers (lazy context). Use when you need a specific function/class/section without loading the whole file. Path is relative to cwd unless absolute. `offset` is 0-indexed start, `limit` defaults to 100 (cap 500). For .html files, pass `format=\"stripped\"` to strip HTML tags (text-only output, useful for intent docs).",
+			"Read a bounded line range from a file with line numbers — a specific function/section without the whole file. `offset` 0-indexed, `limit` default 100 (cap 500). For .html, `format=\"stripped\"` removes tags.",
 		parameters: Type.Object({
 			path: Type.String({ description: "File path (relative to cwd or absolute)." }),
-			offset: Type.Optional(
-				Type.Number({ description: "0-indexed start line. Default 0." }),
-			),
-			limit: Type.Optional(
-				Type.Number({ description: "Max lines to return. Default 100, cap 500." }),
-			),
+			offset: Type.Optional(Type.Number({ description: "0-indexed start line. Default 0." })),
+			limit: Type.Optional(Type.Number({ description: "Max lines. Default 100, cap 500." })),
 			format: Type.Optional(
 				StringEnum(["raw", "stripped"] as const, {
-					description:
-						"Output format. \"raw\" returns content as-is. \"stripped\" removes HTML tags (for .html files). Default \"raw\".",
+					description: '"raw" (default) or "stripped" (remove HTML tags).',
 				}),
 			),
 		}),
@@ -575,7 +569,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_doc_search",
 		label: "soly doc search",
 		description:
-			"search .md and .html files under cwd (excluding node_modules, dist, etc.) for a query. Use to discover relevant docs before loading a specific file with soly_snippet. Intent docs (from `.soly/docs/` and `.soly/phases/<N>/docs/`) are prioritized via a source-priority bonus — hits are tagged `[intent]`, `[phase-intent]`, or `[project]` so you can tell at a glance. `limit` defaults to 10 (cap 50).",
+			"Search .md/.html under cwd for a query (intent docs prioritized, hits tagged [intent]/[phase-intent]/[project]). Use to find docs before loading one with soly_snippet. `limit` default 10 (cap 50).",
 		parameters: Type.Object({
 			query: Type.String({ description: "Search query (substring, case-insensitive)." }),
 			limit: Type.Optional(
@@ -633,7 +627,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_scratchpad",
 		label: "soly scratchpad",
 		description:
-			"return a compact summary of the recent conversation (one line per turn: user prompt + first line of assistant response). Use to recover shared context after a long break, or to brief a sibling subagent without sharing the full session history. `limit` defaults to 20 user-turns (cap 50).",
+			"Compact recap of the recent conversation (one line per turn). Use to recover context after a break or brief a sibling subagent. `limit` default 20 user-turns (cap 50).",
 		parameters: Type.Object({
 			limit: Type.Optional(
 				Type.Number({
@@ -682,51 +676,6 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		},
 	});
 
-	// ============================================================================
-	// soly_intent — refresh / list the project's 0-point intent docs
-	// ============================================================================
-
-	pi.registerTool({
-		name: "soly_intent",
-		label: "soly intent",
-		description:
-			"list the project's 0-point intent docs from `.soly/docs/` — the business/domain/tech-intent documents the user wrote BEFORE any soly plans. Use before planning, discussing, or executing a phase to ensure alignment with the user's vision. Supports `.md` and `.html` (parsed for `<title>`/`<h1>`/`<meta description>`). Phase-specific docs under `.soly/phases/<N>/docs/` are also included if present. Pass no arguments — this tool always returns the full list.",
-		parameters: Type.Object({}),
-		async execute(_id, _params, _signal, _onUpdate, ctx) {
-			const docs = loadIntentDocs(ctx.cwd);
-			const { section } = buildIntentSection(docs);
-
-			if (docs.length === 0) {
-				return {
-					content: [
-						{
-							type: "text",
-							text:
-								`soly_intent: no docs found in ${path.join(ctx.cwd, ".soly", "docs")}.\n\n` +
-								`Project intent is the user's vision written BEFORE soly plans. If empty, ask the user to drop their intent docs (business glossary, design vision, domain concepts) into .soly/docs/ as .md or .html files, then run soly_intent again.`,
-						},
-					],
-					details: { count: 0 },
-				};
-			}
-
-			// Render the same section that goes into the system prompt, so the
-			// model sees a consistent view whether it asks or not.
-			const out: string[] = [];
-			out.push(`soly_intent: ${docs.length} document(s) in .soly/docs/:`);
-			out.push("");
-			out.push(section);
-			out.push("");
-			out.push(
-				"To read a specific doc, use soly_snippet(path=\".soly/docs/<name>\", offset=N, limit=M). For HTML files, pass format=\"stripped\" to get plain text.",
-			);
-			return {
-				content: [{ type: "text", text: out.join("\n") }],
-				details: { count: docs.length, paths: docs.map((d) => d.relPath) },
-			};
-		},
-	});
-
 	// ============================================================================
 	// soly_ask_user — multiple-choice picker (for `soly discuss` interactive flow)
 	// ============================================================================
@@ -735,29 +684,18 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_ask_user",
 		label: "soly ask user",
 		description:
-			"Ask the user a multiple-choice question via pi's UI picker. Use this for progressive Q&A flows (e.g. `soly discuss <N>`). The first option is treated as the recommended answer — mark it with a ⭐ prefix in its label and add a 1-sentence rationale in the `rationale` parameter. Returns the chosen option text (or the custom string if `allowOther: true` and the user picked 'Other…'). The picker has ↑/↓/j/k navigation, Enter to confirm, Esc to cancel (cancelled → returns 'cancelled' in details).",
+			"DEPRECATED — prefer `ask_pro` (multi-question picker). Fallback only. Asks one multiple-choice question via pi's picker; option #1 is the recommended answer (⭐ prefix + a `rationale`). `allowOther` adds a custom-text 'Other…'. Returns the chosen text (or custom string); Esc → cancelled.",
 		parameters: Type.Object({
-			title: Type.String({
-				description: "Short title shown above the picker (e.g. 'Q1: Session handling').",
-			}),
-			question: Type.String({
-				description: "The question to ask the user (one short sentence).",
-			}),
+			title: Type.String({ description: "Title above the picker." }),
+			question: Type.String({ description: "The question (one sentence)." }),
 			options: Type.Array(Type.String(), {
-				description:
-					"2-4 concrete options. Option #1 is the recommended answer (mark with ⭐ prefix in the label).",
+				description: "2-4 options; #1 is recommended (⭐ prefix).",
 			}),
 			rationale: Type.Optional(
-				Type.String({
-					description:
-						"1-2 sentence note explaining why option #1 is recommended. Shown above the picker.",
-				}),
+				Type.String({ description: "Why #1 is recommended (shown above the picker)." }),
 			),
 			allowOther: Type.Optional(
-				Type.Boolean({
-					description:
-						"If true, appends an 'Other…' option that opens a text-input dialog for a custom answer. The custom string is returned in place of the option index.",
-				}),
+				Type.Boolean({ description: "Add a custom-text 'Other…' choice." }),
 			),
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
@@ -880,45 +818,35 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_finish_discuss",
 		label: "soly finish discuss",
 		description:
-			"Finalize a `soly discuss <N>` session: write the canonical `<phase>-CONTEXT.md` with all captured decisions, and delete the checkpoint file (if any). Call this AFTER asking all gray-area questions and recording the user's answers via `soly_ask_user`. Do NOT call this for partial progress — use the checkpoint file (auto-saved by soly_finish_discuss_checkpoint) for resume.",
+			"Finalize a `soly discuss <N>` session: write `<phase>-CONTEXT.md` with all decisions and delete the checkpoint. Call AFTER all gray-area questions are answered — not for partial progress (use soly_save_discuss_checkpoint for that).",
 		parameters: Type.Object({
-			phase_number: Type.Number({
-				description: "Phase number being discussed (e.g. 5).",
-			}),
+			phase_number: Type.Number({ description: "Phase number being discussed." }),
 			domain: Type.String({
 				description:
-					"1-2 paragraphs: what this phase delivers, grounded in ROADMAP + intent. No implementation details.",
+					"1-2 paragraphs: what this phase delivers (grounded in ROADMAP + intent, no implementation details).",
 			}),
 			decisions: Type.Array(
 				Type.Object({
-					category: Type.String({
-						description:
-							"Category of the decision (e.g. 'Session handling', 'Error responses', 'Token storage').",
-					}),
+					category: Type.String({ description: "Decision category (e.g. 'Session handling')." }),
 					choice: Type.String({ description: "What was chosen." }),
 					rationale: Type.Optional(
-						Type.String({
-							description: "Why this choice — default 'user discretion' if not specified.",
-						}),
+						Type.String({ description: "Why (default 'user discretion')." }),
 					),
 				}),
-				{ description: "All decisions captured during this discussion round." },
+				{ description: "All decisions captured this round." },
 			),
 			canonical_refs: Type.Optional(
 				Type.Array(Type.String(), {
 					description:
-						"MANDATORY. List of files the planner will need (intent docs, REQUIREMENTS, contracts, prior CONTEXT.md). Full relative paths starting with `.soly/`.",
+						"MANDATORY. Files the planner needs (intent docs, REQUIREMENTS, contracts), full paths from `.soly/`.",
 				}),
 			),
 			deferred_ideas: Type.Optional(
-				Type.Array(Type.String(), {
-					description: "Scope-creep items for future phases (or empty array).",
-				}),
+				Type.Array(Type.String(), { description: "Scope-creep items for future phases." }),
 			),
 			codebase_context: Type.Optional(
 				Type.Array(Type.String(), {
-					description:
-						"Reusable assets/patterns the planner should know (e.g. 'src/components/Card.tsx — already has rounded/shadow variants, reuse for consistency').",
+					description: "Reusable assets/patterns the planner should know (path — what to reuse).",
 				}),
 			),
 		}),
@@ -1074,7 +1002,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_save_discuss_checkpoint",
 		label: "soly save discuss checkpoint",
 		description:
-			"Save a partial-progress checkpoint for `soly discuss <N>`. Call after each captured decision (so a session quit doesn't lose progress). The next `soly discuss <N>` invocation will pick up from the checkpoint. After all decisions captured, call `soly_finish_discuss` (which deletes the checkpoint and writes CONTEXT.md).",
+			"Save a partial-progress checkpoint for `soly discuss <N>` (call after each decision so a quit doesn't lose progress; the next `soly discuss <N>` resumes from it). When done, call `soly_finish_discuss`.",
 		parameters: Type.Object({
 			phase_number: Type.Number({ description: "Phase number being discussed." }),
 			decisions: Type.Array(