pi-soly 1.13.5 → 1.14.0

package/README.md

@@ -114,8 +114,7 @@ soly status        # current position + progress (no LLM round-trip)
 ### Setup
 
 ```bash
-/soly-init                # scaffold .soly/ (templates: minimal|web-app|library|cli)
-/soly-migrate             # atomic .soly/ → .agents/ rename (vendor-neutral)
+/soly init                # scaffold .agents/ (templates: minimal|web-app|library|cli)
 /soly-status              # one-screen health report
 /soly-log                 # recent notifications
 ```
@@ -133,7 +132,7 @@ soly status        # current position + progress (no LLM round-trip)
 
 Two system-prompt injections, both **opt-in** and **fully observable**.
 
-### Rules — `.soly/rules/` or `~/.soly/rules/`
+### Rules — `.agents/rules/` or `~/.agents/rules/`
 
 Markdown files with frontmatter. Three modes:
 
@@ -167,7 +166,7 @@ modify. If a rule contradicts your instinct, the rule wins.**
 
 See context breakdown anytime: `/rules stats`.
 
-### Docs — `.soly/docs/` or `~/.soly/docs/`
+### Docs — `.agents/docs/` or `~/.agents/docs/`
 
 Zero-point intent docs (your vision, business context). Loaded as **preview only** (180 chars per doc) — cheap. Add `inline: true` to opt-in to full body injection.
 
@@ -229,7 +228,7 @@ Flip cards with ←/→ (or 1-N), choose with Enter, Esc to cancel. Native TUI
 
 ## 🖼 HTML Artifacts
 
-`html_artifact` tool for the LLM — soly's local "artifacts". Renders HTML (a full document or just body content, themed light/dark) and serves it from a **per-session gallery SPA** — a sidebar of every artifact this session, an iframe viewer, a filter box, a light/dark toggle, and live SSE updates — on one stable localhost URL, opened in your browser. Pass `id` to update an artifact in place; pass `assets` to write sibling files (images/css/json) the HTML references; restyle everything via `.soly/artifact-theme.css`. (Falls back to opening the file directly if the server is disabled.)
+`html_artifact` tool for the LLM — soly's local "artifacts". Renders HTML (a full document or just body content, themed light/dark) and serves it from a **per-session gallery SPA** — a sidebar of every artifact this session, an iframe viewer, a filter box, a light/dark toggle, and live SSE updates — on one stable localhost URL, opened in your browser. Pass `id` to update an artifact in place; pass `assets` to write sibling files (images/css/json) the HTML references; restyle everything via `.agents/artifact-theme.css`. (Falls back to opening the file directly if the server is disabled.)
 
 ```ts
 html_artifact({
@@ -272,7 +271,7 @@ Use it when a visual, rendered result beats terminal text (example galleries, co
                          │
             ┌────────────┼────────────┐
             ▼            ▼            ▼
-       .soly/STATE  phases/<N>/   rules/
+       .agents/STATE  phases/<N>/   rules/
        (current     CONTEXT,      docs/
         position)   PLAN,         (system
                     RESEARCH)     prompt)
@@ -288,10 +287,10 @@ Use it when a visual, rendered result beats terminal text (example galleries, co
                 └──────────────────┘
 ```
 
-State lives in `.soly/` — portable, git-friendly, human-readable. Migrate to vendor-neutral `.agents/` with `/soly-migrate` (both supported, `.soly/` shows deprecation warning).
+State lives in `.agents/` — portable, git-friendly, human-readable. (Projects from before the rename used `.soly/`; soly no longer reads it — run `mv .soly .agents`.)
 
 ```
-.soly/
+.agents/
 ├── ROADMAP.md           # phase table
 ├── STATE.md             # current position + decisions log
 ├── docs/                # 0-point intent docs (preview-loaded)
@@ -306,7 +305,7 @@ State lives in `.soly/` — portable, git-friendly, human-readable. Migrate to v
                 └── SUMMARY.md
 ```
 
-> Legacy projects (standalone `NN-MM-PLAN.md` / a `features/` dir) still work; run `soly migrate` to convert them to this layout.
+> Legacy projects (standalone `NN-MM-PLAN.md` files / a `features/` dir) still load and run alongside the unified `phases/<N>/tasks/` layout.
 
 ---
 

package/artifact/index.ts

@@ -31,13 +31,13 @@ import {
 type ToolText = { content: { type: "text"; text: string }[]; details: Record<string, unknown> };
 type Asset = { path: string; content: string; encoding?: string };
 
-/** Load the artifact CSS theme: config override → .soly/artifact-theme.css →
+/** Load the artifact CSS theme: config override → .agents/artifact-theme.css →
  *  built-in DEFAULT_CSS. */
 function loadCss(themeCfg: string, cwd: string): string {
 	const candidates: string[] = [];
 	const t = themeCfg.trim();
 	if (t) candidates.push(path.isAbsolute(t) ? t : path.join(cwd, t));
-	candidates.push(path.join(cwd, ".soly", "artifact-theme.css"));
+	candidates.push(path.join(cwd, ".agents", "artifact-theme.css"));
 	for (const c of candidates) {
 		try {
 			return fs.readFileSync(c, "utf-8");
@@ -150,7 +150,7 @@ export default function piArtifactExtension(pi: ExtensionAPI, getConfig: () => S
 		name: "html_artifact",
 		label: "soly · html_artifact",
 		description:
-			"Render HTML to a self-contained file and serve it from a per-project gallery in the browser — soly's artifacts. `html` is a full document or a body fragment (wrapped in a styled light/dark skeleton; theme overridable via .soly/artifact-theme.css). Pass `id` to update an existing artifact in place (re-render). Pass `assets` to write sibling files (images/css/json) the HTML references via relative paths. Use when a visual rendered result beats terminal text. Self-contained otherwise — no external URLs. The gallery is shared across every pi window in this folder and survives restarts. Returns the localhost URL + gallery.",
+			"Render HTML to a self-contained file and serve it from a per-project gallery in the browser — soly's artifacts. `html` is a full document or a body fragment (wrapped in a styled light/dark skeleton; theme overridable via .agents/artifact-theme.css). Pass `id` to update an existing artifact in place (re-render). Pass `assets` to write sibling files (images/css/json) the HTML references via relative paths. Use when a visual rendered result beats terminal text. Self-contained otherwise — no external URLs. The gallery is shared across every pi window in this folder and survives restarts. Returns the localhost URL + gallery.",
 		parameters: Type.Object({
 			title: Type.String({ description: "Title (used for <title>, header, gallery, filename)." }),
 			html: Type.String({

package/artifact/render.ts

@@ -6,7 +6,7 @@
 // session gallery shell — soly's local "artifacts". Pure: every function takes
 // strings and returns strings; the stylesheet is passed in (loaded from a file
 // or the built-in DEFAULT_CSS by the caller) so a project can restyle every
-// artifact by dropping a `.soly/artifact-theme.css`.
+// artifact by dropping a `.agents/artifact-theme.css`.
 //
 // A body *fragment* is wrapped in the skeleton; a *full document* keeps its own
 // markup but gets the theme injected as a base layer (its own styles win).
@@ -155,7 +155,7 @@ export function buildGalleryShell(token: string): string {
 }
 
 // Self-contained artifact stylesheet — no external fonts, scripts, or CDN
-// requests. Overridable per project via .soly/artifact-theme.css.
+// requests. Overridable per project via .agents/artifact-theme.css.
 export const DEFAULT_CSS = `
 :root{color-scheme:light dark}
 *{box-sizing:border-box}

package/ask/README.md

@@ -18,7 +18,9 @@ showing a **tabbed, multi-question picker** in pi's TUI.
   typed-answer question; it's optional (blank is allowed)
 - **Option previews** — per-option `preview` shows a side panel while focused;
   fenced ```code blocks in it are syntax-highlighted
-- **"Other…"** — per-question `allowOther: true` adds a free-text custom choice
+- **"Other…"** — every options question automatically gets a free-text custom
+  choice (the `ask_pro` tool forces `allowOther: true`), so the user can always
+  answer in their own words; `freeText` questions are already free-form
 - **Notes & skip** — `n` attaches a free-text note to any answer; `s` skips a
   question (returned in `skipped`)
 - **Cancelled detection** — `Esc` resolves `{cancelled: true}`

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 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) the choice is local — a sub-question inside an already-decided theme, or a simple label-vs-label «или/или» that doesn't justify a full-screen deck. Each option is a short label + 1-2 sentence description (no per-option code, no pros/cons). For a global architectural fork with real counterweight between options, 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.",
+			"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) the choice is local — a sub-question inside an already-decided theme, or a simple label-vs-label «или/или» that doesn't justify a full-screen deck. Each option is a short label + 1-2 sentence description (no per-option code, no pros/cons). For a global architectural fork with real counterweight between options, use `decision_deck` instead. Per question: single-select (default), `multiSelect` (+ `minSelect`/`maxSelect`), or `freeText` (typed answer, no options). **Every options question automatically includes a free-text 'Other…' choice — the user can always answer in their own words, so never add a manual «other/custom» option yourself.** 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({
@@ -99,7 +99,10 @@ export default function piAskExtension(pi: ExtensionAPI) {
 						Type.Boolean({ description: "Allow multiple picks (default single-select)." }),
 					),
 					allowOther: Type.Optional(
-						Type.Boolean({ description: "Add a free-text 'Other…' choice." }),
+						Type.Boolean({
+							description:
+								"Ignored — a free-text 'Other…' choice is always added to every options question automatically. Kept for backward compatibility.",
+						}),
 					),
 					minSelect: Type.Optional(
 						Type.Number({ description: "Multi-select: min picks (default 1)." }),
@@ -150,6 +153,17 @@ export default function piAskExtension(pi: ExtensionAPI) {
 					details: { error: "too_many_questions", count: params.questions.length },
 				};
 			}
+
+			// Always offer a free-text "Other…" on every options question, so the
+			// user can answer in their own words even when no option fits. This is
+			// enforced here (not left to the model) so the escape hatch is
+			// guaranteed on every question. `freeText` questions are already
+			// free-form, so leave them untouched. Done before validation so the
+			// synthetic "Other…" slot is counted in multi-select bounds.
+			for (const q of params.questions) {
+				if (q && !q.freeText) q.allowOther = true;
+			}
+
 			for (let i = 0; i < params.questions.length; i++) {
 				const q = params.questions[i];
 				if (!q) continue;

package/codemap.ts

@@ -8,7 +8,7 @@
 // live without having to `ls` its way around.
 //
 // Heuristics:
-//   - skip noise: node_modules, .git, dist, build, .soly, .next, out, target,
+//   - skip noise: node_modules, .git, dist, build, .agents, .next, out, target,
 //     coverage, .venv, __pycache__
 //   - depth: walk 2 levels deep by default (cwd → dirs → subdirs)
 //   - key files: package.json, tsconfig.json, README.md, Cargo.toml, go.mod,
@@ -23,7 +23,7 @@ import * as path from "node:path";
 const IGNORE_DIRS = new Set([
 	"node_modules",
 	".git",
-	".soly",
+	".agents",
 	"dist",
 	"build",
 	"out",

package/commands.ts

@@ -43,7 +43,6 @@ import {
 	type IntentInlineDoc,
 } from "./intent.ts";
 import type { SolyConfig } from "./config.ts";
-import { migrateSolyDir } from "./migrate.js";
 import { initSolyProject } from "./init.js";
 import { ListPanel, type ListItem, type ListAction } from "./visual/list-panel.ts";
 import { getArtifactServer, ensureArtifactServer, artifactDir } from "./artifact/session.ts";
@@ -367,7 +366,7 @@ What must the LLM do?
 			return;
 		}
 
-		// /rules add <url> — download a remote rule into .soly/rules/
+		// /rules add <url> — download a remote rule into .agents/rules/
 		if (sub === "add") {
 			const url = (target ?? "").trim();
 			if (!url) {
@@ -461,7 +460,7 @@ What must the LLM do?
 			if (sub === "list") {
 				const docs = getIntentDocs();
 				if (docs.length === 0) {
-					ui.notify("no intent docs found in .soly/docs/ — drop your vision/domain docs there", "info");
+					ui.notify("no intent docs found in .agents/docs/ — drop your vision/domain docs there", "info");
 					return;
 				}
 				if (ctx.mode === "tui") {
@@ -500,56 +499,7 @@ What must the LLM do?
 		},
 	});
 
-	// ============================================================================
-	// /soly migrate — move .soly/ → .agents/ atomically
-	// ============================================================================
-	pi.registerCommand("soly-migrate", {
-		description:
-			"migrate project state from .soly/ to .agents/ (atomic rename, validates result, suggests git commit)",
-		handler: async (args, ctx) => {
-			const ui: CommandUI = {
-				notify: (t, k) => ctx.ui.notify(t, k ?? "info"),
-				select: async (label, options) => {
-					const result = await ctx.ui.select(label, options);
-					return result === undefined ? null : options.indexOf(result);
-				},
-				confirm: (title, message) => ctx.ui.confirm(title, message),
-			};
-			await migrateSolyDir(ctx.cwd, ui, { autoYes: args.includes("--yes") });
-		},
-	});
-
-	// /soly init — scaffold new project
-	// ============================================================================
-	pi.registerCommand("soly-init", {
-		description:
-			"scaffold a new soly project (interactive: pick template — minimal/web-app/library/cli)",
-		handler: async (args, ctx) => {
-			const ui: CommandUI = {
-				notify: (t, k) => ctx.ui.notify(t, k ?? "info"),
-				select: async (label, options) => {
-					const result = await ctx.ui.select(label, options);
-					return result === undefined ? null : options.indexOf(result);
-				},
-				confirm: (title, message) => ctx.ui.confirm(title, message),
-				input: (label, placeholder) => ctx.ui.input(label, placeholder),
-			};
-			// Parse args: --template=X, --yes, --name=X
-			const template = (args.match(/--template[= ](\S+)/)?.[1] as
-				| "minimal" | "web-app" | "library" | "cli" | undefined) ?? undefined;
-			const autoYes = args.includes("--yes");
-			const projectName = args.match(/--name[= ](\S+)/)?.[1];
-			const initUi = {
-				notify: (t: string, k?: "info" | "warning" | "error") => ctx.ui.notify(t, k ?? "info"),
-				select: async (label: string, options: string[]) => ctx.ui.select(label, options),
-				confirm: (title: string, message: string) => ctx.ui.confirm(title, message),
-				input: (label: string, placeholder?: string) => ctx.ui.input(label, placeholder),
-			};
-			await initSolyProject(ctx.cwd, initUi, { template, autoYes, projectName });
-		},
-	});
-
-	// /soly
+	// /soly  (also hosts `/soly init` — see the early dispatch in the handler)
 	// ============================================================================
 
 	pi.registerCommand("soly", {
@@ -564,9 +514,30 @@ What must the LLM do?
 				},
 				confirm: (title, message) => ctx.ui.confirm(title, message),
 			};
+			// `init` is special — it scaffolds a NEW project, so it must run even
+			// when there's no `.agents/` dir yet. Dispatch it before the project
+			// guard below. (Moved here from the old standalone `/soly-init`.)
+			{
+				const firstArg = args.trim().split(/\s+/).filter(Boolean)[0] ?? "";
+				if (firstArg === "init") {
+					const template = (args.match(/--template[= ](\S+)/)?.[1] as
+						| "minimal" | "web-app" | "library" | "cli" | undefined) ?? undefined;
+					const autoYes = args.includes("--yes");
+					const projectName = args.match(/--name[= ](\S+)/)?.[1];
+					const initUi = {
+						notify: (t: string, k?: "info" | "warning" | "error") => ctx.ui.notify(t, k ?? "info"),
+						select: async (label: string, options: string[]) => ctx.ui.select(label, options),
+						confirm: (title: string, message: string) => ctx.ui.confirm(title, message),
+						input: (label: string, placeholder?: string) => ctx.ui.input(label, placeholder),
+					};
+					await initSolyProject(ctx.cwd, initUi, { template, autoYes, projectName });
+					return;
+				}
+			}
+
 			const state = getState();
 			if (!state.exists) {
-				ui.notify("soly: no .soly/ directory in cwd", "error");
+				ui.notify("soly: no .agents/ project here — run `/soly init` to scaffold one", "info");
 				return;
 			}
 
@@ -592,7 +563,7 @@ What must the LLM do?
 				// extension (rotor switcher removed in 1.4.0).
 				// Soly no longer owns a rotor switcher.
 				config: {
-					description: "show merged config (per-project + global + defaults); edit .soly/config.json or ~/.soly/config.json",
+					description: "show merged config (per-project + global + defaults); edit .agents/soly.json or ~/.agents/soly.json",
 					run: () => {
 						const cfg = getConfig();
 						const out: string[] = [];
@@ -603,12 +574,12 @@ What must the LLM do?
 						out.push("```");
 						out.push("");
 						out.push("Sources:");
-						out.push(`  global:  ~/.soly/config.json`);
-						out.push(`  project: <cwd>/.soly/config.json`);
+						out.push(`  global:  ~/.agents/soly.json`);
+						out.push(`  project: <cwd>/.agents/soly.json`);
 						out.push("");
 						out.push("To edit:");
-						out.push(`  - project: edit \`${state.solyDir}/config.json\` directly`);
-						out.push(`  - global:  edit \`~/.soly/config.json\``);
+						out.push(`  - project: edit \`${state.solyDir}/soly.json\` directly`);
+						out.push(`  - global:  edit \`~/.agents/soly.json\``);
 						out.push("After editing, run /soly reload to re-pick up changes.");
 						ui.notify(out.join("\n"), "info");
 					},
@@ -720,7 +691,7 @@ What must the LLM do?
 					run: () => {
 						const s = getState();
 						if (s.tasks.length === 0) {
-							ui.notify("soly: no tasks found in .soly/features/*/tasks/", "info");
+							ui.notify("soly: no tasks found in .agents/features/*/tasks/", "info");
 							return;
 						}
 						const byFeature = new Map<string, typeof s.tasks>();
@@ -779,7 +750,7 @@ What must the LLM do?
 					run: () => {
 						const features = getState().features;
 						if (features.length === 0) {
-							ui.notify("soly: no features found in .soly/features/", "info");
+							ui.notify("soly: no features found in .agents/features/", "info");
 							return;
 						}
 						const lines = features.map((f) => {
@@ -790,7 +761,7 @@ What must the LLM do?
 					},
 				},
 				milestone: {
-					description: "show the active milestone document (.soly/milestones/<v>.md)",
+					description: "show the active milestone document (.agents/milestones/<v>.md)",
 					run: () => {
 						const s = getState();
 						if (!s.milestone || s.milestone === "—") {
@@ -996,7 +967,7 @@ What must the LLM do?
 					"",
 					"tell me what behavior or outcome you want to constrain. I'll help you",
 					"decide whether it should be:",
-					"  • a soly rule (.soly/rules/*.md) — for process, behavior, or project",
+					"  • a soly rule (.agents/rules/*.md) — for process, behavior, or project",
 					"    conventions the LLM must follow",
 					"  • an .editorconfig entry — for formatting (indent, line endings, EOL,",
 					"    charset, trailing whitespace, max line length)",

package/config.ts

@@ -2,8 +2,8 @@
 // config.ts — soly config loader (per-project + global)
 // =============================================================================
 //
-// Per-project: `.soly/config.json` (version-controlled, repo-specific).
-// Global:     `~/.soly/config.json` (per-user, applies to all projects).
+// Per-project: `.agents/soly.json` (version-controlled, repo-specific).
+// Global:     `~/.agents/soly.json` (per-user, applies to all projects).
 //
 // Lookup order: per-project overrides global overrides defaults. Missing
 // files are silently ignored (defaults apply). Malformed JSON returns a
@@ -41,10 +41,14 @@ export interface SolyConfig {
 		/** Inject per-turn affordance hints (examples → html_artifact, options →
 		 *  decision_deck, …) when the prompt mentions those. Default on. */
 		toolHints: boolean;
-		/** For non-trivial tasks, tell the LLM to confirm the approach with the
-		 *  user (ask "ready to implement, or discuss first?") before writing code.
-		 *  Default on. */
-		confirmBeforeCode: boolean;
+		/** Before non-trivial coding, make the LLM ask the user the decisions
+		 *  only they can make, instead of coding on assumptions. Levels:
+		 *    "scope" — batch the substantive questions (placement, pattern,
+		 *              scope, interface) via ask_pro, then wait. (default)
+		 *    "ask"   — lighter: one "ready to implement, or discuss?" question.
+		 *    "off"   — no gate.
+		 *  Booleans accepted for back-compat: true = "scope", false = "off". */
+		confirmBeforeCode: boolean | "off" | "ask" | "scope";
 		/** Inject a compact list of rules applicable to the file being
 		 *  edited/written, appended to the tool's result. Forces the LLM to
 		 *  confirm in the next message which rules were applied — closes the
@@ -111,7 +115,7 @@ export interface SolyConfig {
 		 *  (one stable localhost URL). When false, just open the .html file. */
 		server: boolean;
 		/** Path to a CSS file overriding the artifact theme. Empty → built-in.
-		 *  Resolved like `dir`; also auto-detected at `.soly/artifact-theme.css`. */
+		 *  Resolved like `dir`; also auto-detected at `.agents/artifact-theme.css`. */
 		theme: string;
 		/** Prune session artifact dirs older than N days on session start.
 		 *  0 = keep forever. */
@@ -131,7 +135,7 @@ export const DEFAULT_CONFIG: SolyConfig = {
 		autoCheckpointOnPause: true,
 		nudgeNotify: false,
 		toolHints: true,
-		confirmBeforeCode: true,
+		confirmBeforeCode: "scope",
 		preActionRuleReminder: true,
 	},
 	display: {
@@ -222,7 +226,12 @@ function deepMerge(base: SolyConfig, over: RawConfig): SolyConfig {
 			merged.agent.nudgeNotify = over.agent.nudgeNotify;
 		if (typeof over.agent.toolHints === "boolean")
 			merged.agent.toolHints = over.agent.toolHints;
-		if (typeof over.agent.confirmBeforeCode === "boolean")
+		if (
+			typeof over.agent.confirmBeforeCode === "boolean" ||
+			over.agent.confirmBeforeCode === "off" ||
+			over.agent.confirmBeforeCode === "ask" ||
+			over.agent.confirmBeforeCode === "scope"
+		)
 			merged.agent.confirmBeforeCode = over.agent.confirmBeforeCode;
 		if (typeof over.agent.preActionRuleReminder === "boolean")
 			merged.agent.preActionRuleReminder = over.agent.preActionRuleReminder;
@@ -291,7 +300,7 @@ export function loadConfig(cwd: string, homeDir?: string): LoadConfigResult {
 	const sources = { global: null as string | null, project: null as string | null };
 
 	const home = homeDir ?? os.homedir();
-	const globalPath = path.join(home, ".soly", "config.json");
+	const globalPath = path.join(home, ".agents", "soly.json");
 	const globalRaw = readJsonIfExists(globalPath);
 	if (globalRaw) {
 		sources.global = globalPath;
@@ -301,8 +310,7 @@ export function loadConfig(cwd: string, homeDir?: string): LoadConfigResult {
 			);
 		}
 	}
-	const projectSolyDir = path.join(cwd, ".soly");
-	const projectPath = path.join(projectSolyDir, "config.json");
+	const projectPath = path.join(cwd, ".agents", "soly.json");
 	const projectRaw = readJsonIfExists(projectPath);
 	if (projectRaw) {
 		sources.project = projectPath;

package/core.ts

@@ -3,12 +3,12 @@
 // =============================================================================
 //
 // Owns:
-//   - Rule loading from .soly/rules/ (project + global)
-//   - Soly project state loading from .soly/ (STATE.md, ROADMAP.md, phases/)
+//   - Rule loading from .agents/rules/ (project + global)
+//   - Soly project state loading from .agents/ (STATE.md, ROADMAP.md, phases/)
 //   - Status line construction
 //   - Shared utility functions and constants
 //
-// Path convention: <cwd>/.soly/. Pi itself loads AGENTS.md / CLAUDE.md
+// Path convention: <cwd>/.agents/. Pi itself loads AGENTS.md / CLAUDE.md
 // from ancestor directories through its own resource loader, so soly
 // stays out of that path.
 // =============================================================================
@@ -142,8 +142,8 @@ export interface PhaseInfo {
 
 /**
  * A feature is a logical grouping of tasks (e.g. "auth", "orders").
- * Dual-mode with phases: features live under `.soly/features/`, phases
- * under `.soly/phases/`. soly supports both simultaneously.
+ * Dual-mode with phases: features live under `.agents/features/`, phases
+ * under `.agents/phases/`. soly supports both simultaneously.
  */
 export interface FeatureInfo {
   name: string;
@@ -548,7 +548,7 @@ export function buildRulesSection(
     headerHint = `Phase ${phase} rules are loaded for the currently active phase; all other rules are always-on. Inline @see references are resolved recursively.`;
   } else {
     blocks = applicable.map(render);
-    headerHint = `The following rules are loaded from \`.soly/rules/\` and \`~/.soly/rules/\` and are mandatory. Follow them strictly. Inline @see references are resolved recursively.`;
+    headerHint = `The following rules are loaded from \`.agents/rules/\` and \`~/.agents/rules/\` and are mandatory. Follow them strictly. Inline @see references are resolved recursively.`;
   }
 
   const skippedNote = skipped.length
@@ -981,7 +981,7 @@ export function formatRulesContextStats(stats: RulesContextStats): string {
 // @import resolver (markdown only)
 // ============================================================================
 //
-// Used by intent docs (`.soly/docs/*.md`) to inline other markdown files
+// Used by intent docs (`.agents/docs/*.md`) to inline other markdown files
 // via `@import path/to/file.md` lines. Cycles and > MAX_IMPORT_DEPTH
 // are skipped with a comment.
 //
@@ -1121,7 +1121,7 @@ export function resolveImports(
 }
 
 // ============================================================================
-// Project state (.soly/)
+// Project state (.agents/)
 // ============================================================================
 
 function extractCurrentPosition(body: string): SolyPosition | null {
@@ -1524,20 +1524,18 @@ export function buildStatusLine(
 /** Preferred soly dir name (vendor-neutral). */
 export const SOLY_DIRNAME = ".agents";
 
-/** Legacy soly dir name. Kept for backward compat with existing projects. */
+/** Legacy soly dir name. Detection-only — soly no longer reads or writes it.
+ *  Used to warn users with an old `.soly/` project to rename it to `.agents/`. */
 export const LEGACY_SOLY_DIRNAME = ".soly";
 
-/** Which project subdir name is currently in use. Returns the first
- *  one that exists, preferring `.agents/`. Falls back to `.soly/` if
- *  no `.agents/` exists. If neither exists, returns `.agents/` (so
- *  new writes go to the new location). */
+/** The soly project dir for a given cwd. Always `<cwd>/.agents/` — the legacy
+ *  `.soly/` location is no longer read (rename it; `isLegacySolyDir` warns). */
 export function solyDirFor(cwd: string): string {
-	if (fs.existsSync(path.join(cwd, SOLY_DIRNAME))) return path.join(cwd, SOLY_DIRNAME);
-	if (fs.existsSync(path.join(cwd, LEGACY_SOLY_DIRNAME))) return path.join(cwd, LEGACY_SOLY_DIRNAME);
-	return path.join(cwd, SOLY_DIRNAME); // default to new for new projects
+	return path.join(cwd, SOLY_DIRNAME);
 }
 
-/** True if the legacy `.soly/` dir is in active use (and `.agents/` isn't). */
+/** True if a legacy `.soly/` dir exists but `.agents/` doesn't — i.e. the
+ *  project predates the rename and is now invisible to soly. Warn the user. */
 export function isLegacySolyDir(cwd: string): boolean {
 	const newPath = path.join(cwd, SOLY_DIRNAME);
 	const oldPath = path.join(cwd, LEGACY_SOLY_DIRNAME);
@@ -1553,7 +1551,7 @@ export function isLegacySolyDir(cwd: string): boolean {
 // the next sensible soly action without needing to read STATE.md.
 //
 // Returns null when:
-//   - there is no .soly/ in cwd (nothing to suggest)
+//   - there is no .agents/ in cwd (nothing to suggest)
 //   - every phase is already complete
 //
 // Heuristic priority (first match wins):

package/docs.ts

@@ -10,7 +10,7 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { estimateTokens, findMarkdownFiles, readIfExists } from "./core.ts";
+import { estimateTokens, findMarkdownFiles, readIfExists, solyDirFor } from "./core.ts";
 import { extractTitleAndPreview, stripHtml } from "./html.ts";
 
 // Re-export the stripHtml helper so existing imports of `stripHtml from
@@ -42,7 +42,7 @@ const DOC_GLOBS_IGNORE = [
 	"venv",
 ];
 
-// .soly/ IS indexed, but intent docs in .soly/docs/ and .soly/phases/<N>/docs/
+// .agents/ IS indexed, but intent docs in .agents/docs/ and .agents/phases/<N>/docs/
 // are tagged with higher priority in search results (see buildDocIndex).
 
 const INTENT_DOC_EXTS = [".md", ".html", ".htm"];
@@ -72,7 +72,7 @@ export function buildDocIndex(cwd: string, limit = 5000): DocIndexEntry[] {
 	};
 
 	// 1. Intent docs (priority 0)
-	const docsRoot = path.join(cwd, ".soly", "docs");
+	const docsRoot = path.join(solyDirFor(cwd), "docs");
 	if (fs.existsSync(docsRoot)) {
 		const intentFiles = findIntentFiles(docsRoot);
 		for (const f of intentFiles) {
@@ -83,7 +83,7 @@ export function buildDocIndex(cwd: string, limit = 5000): DocIndexEntry[] {
 	}
 
 	// 2. Phase intent docs (priority 1) — only if phases dir exists
-	const phasesRoot = path.join(cwd, ".soly", "phases");
+	const phasesRoot = path.join(solyDirFor(cwd), "phases");
 	if (out.length < limit && fs.existsSync(phasesRoot)) {
 		try {
 			const phaseEntries = fs.readdirSync(phasesRoot, { withFileTypes: true });