@aexol/spectral 0.7.8 → 0.8.0

package/dist/agent/agents.js

@@ -12,12 +12,12 @@
  *   System prompt for the agent goes here.
  *
  * Locations:
- *   ~/.pi/agent/agents/*.md     — User-level (always loaded)
- *   .pi/agents/*.md             — Project-level (opt-in via agentScope)
+ *   ~/.spectral/agent/agents/*.md     — User-level (always loaded)
+ *   .spectral/agents/*.md             — Project-level (opt-in via agentScope)
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { getAgentDir, parseFrontmatter } from "../pi/coding-agent/index.js";
+import { getAgentDir, parseFrontmatter } from "../sdk/coding-agent/index.js";
 function loadAgentsFromDir(dir, source) {
     const agents = [];
     if (!fs.existsSync(dir)) {
@@ -74,7 +74,7 @@ function isDirectory(p) {
 function findNearestProjectAgentsDir(cwd) {
     let currentDir = cwd;
     while (true) {
-        const candidate = path.join(currentDir, ".pi", "agents");
+        const candidate = path.join(currentDir, ".spectral", "agents");
         if (isDirectory(candidate))
             return candidate;
         const parentDir = path.dirname(currentDir);

package/dist/agent/index.js

@@ -13,8 +13,8 @@
  *   - Chain:    { chain: [{ agent, task: "... {previous} ..." }, ...] }
  *
  * Agent definitions live as markdown files with YAML frontmatter:
- *   - ~/.pi/agent/agents/*.md    (user-level, always loaded)
- *   - .pi/agents/*.md            (project-level, opt-in via agentScope)
+ *   - ~/.spectral/agent/agents/*.md    (user-level, always loaded)
+ *   - .spectral/agents/*.md            (project-level, opt-in via agentScope)
  *
  * Subagents use an in-process `agentLoop()` for:
  *   - Clean context isolation (fresh messages array)
@@ -24,15 +24,15 @@
  *   - Signal propagation (abort passthrough)
  *   - Access to observational memory via the recall tool
  */
-import { agentLoop } from "../pi/agent-core/index.js";
-import { StringEnum } from "../pi/ai/index.js";
+import { agentLoop } from "../sdk/agent-core/index.js";
+import { StringEnum } from "../sdk/ai/index.js";
 import { Type } from "typebox";
 import { discoverAgents } from "./agents.js";
 // ---------------------------------------------------------------------------
 // Built-in tool resolution (no spawn needed — tools are registered in-process)
 // ---------------------------------------------------------------------------
-import { createTool, allToolNames } from "../pi/coding-agent/core/tools/index.js";
-import { wrapToolDefinition } from "../pi/coding-agent/core/tools/tool-definition-wrapper.js";
+import { createTool, allToolNames } from "../sdk/coding-agent/core/tools/index.js";
+import { wrapToolDefinition } from "../sdk/coding-agent/core/tools/tool-definition-wrapper.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -386,8 +386,8 @@ export default function subagentExtension(pi) {
         description: [
             "Delegate tasks to specialized subagents with isolated context.",
             "Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder).",
-            'Default agent scope is "user" (from ~/.pi/agent/agents).',
-            'To enable project-local agents in .pi/agents, set agentScope: "both" (or "project").',
+            'Default agent scope is "user" (from ~/.spectral/agent/agents).',
+            'To enable project-local agents in .spectral/agents, set agentScope: "both" (or "project").',
         ].join(" "),
         promptSnippet: "Run a subagent to investigate, plan, review, or implement code changes",
         promptGuidelines: [

package/dist/cli.js

@@ -46,7 +46,7 @@ function printHeader() {
     ].join("\n"));
 }
 // ---- Disable interactive git editors ----------------------------------------
-// Set at process level for serve mode (PiBridge in-process → getShellEnv()
+// Set at process level for serve mode (AgentBridge in-process → getShellEnv()
 // returns process.env). Without this, `git rebase --continue`, `git commit`
 // (without -m), `git merge`, etc. open an editor that hangs forever — the
 // agent's bash tool runs with `stdio: ["ignore", ...]`, so there is no TTY

package/dist/commands/serve.js

@@ -146,7 +146,7 @@ export async function runServe(opts = {}) {
     const backendUrl = opts.backendUrlOverride ?? process.env.SPECTRAL_BACKEND_URL ?? DEFAULT_BACKEND_URL;
     const relayUrl = opts.relayUrlOverride ?? process.env.SPECTRAL_RELAY_URL ?? deriveRelayUrl(backendUrl);
     // Register BEFORE constructing the SessionStreamManager. The manager
-    // (and every PiBridge it spawns) needs the machine JWT to authenticate
+    // (and every AgentBridge it spawns) needs the machine JWT to authenticate
     // backend-proxied inference calls, so registration must succeed first.
     // Fail-fast on error — a clear message beats a hang.
     let registration;

package/dist/extensions/spectral-vision-fallback.js

@@ -1,55 +1,87 @@
 /**
  * Spectral Vision Extension
  *
- * Automatically describes images using a vision-capable model and replaces
- * raw image data with text descriptions. This saves context for the main agent
- * and allows non-vision models to "see" images.
+ * Automatically switches to a vision-capable model for image processing
+ * when images are attached. This allows non-vision models to "see" images
+ * and saves main agent context by using a potentially smaller/cheaper
+ * vision model for image understanding.
  *
  * Logic:
  *   - ALWAYS intercepts images (even when main model supports vision),
- *     replacing them with text descriptions to save main agent context.
- *   - Uses the main model for vision descriptions if it supports images.
- *   - Falls back to the admin-configured default vision model (isVisionDefault
- *     flag from backend via SettingsManager).
- *   - If no admin default is configured, falls back to the first available
+ *     replacing them with text descriptions.
+ *   - Prefers the admin-configured default vision model (isVisionDefault
+ *     flag from backend via SettingsManager) for image descriptions.
+ *   - Falls back to the main model for vision if no admin default is
+ *     configured and the main model supports images.
+ *   - If neither is available, falls back to the first available
  *     vision-capable model by provider priority.
  *
  * Hooks into the `context` event to intercept ALL images before they reach
  * the LLM (covers user-attached images and tool-result images alike).
  */
-import { streamSimple } from "../pi/ai/index.js";
+import { streamSimple } from "../sdk/ai/index.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-/** Find the best available vision-capable model from the registry */
-function findVisionModel(ctx) {
+/**
+ * Check if the SettingsManager has an admin-configured default vision model
+ * with working auth. Returns the model if found and auth-ready, or undefined.
+ */
+function getAdminVisionModel(ctx) {
+    const settings = ctx.settingsManager;
+    if (!settings)
+        return undefined;
+    const defaultVisionProvider = settings.getDefaultVisionProvider();
+    const defaultVisionModel = settings.getDefaultVisionModel();
+    if (!defaultVisionProvider || !defaultVisionModel)
+        return undefined;
     const allModels = ctx.modelRegistry.getAll();
-    const availableModels = allModels.filter((m) => ctx.modelRegistry.hasConfiguredAuth(m));
-    // Filter to models that support images
-    const visionModels = availableModels.filter((m) => m.input.includes("image"));
-    if (visionModels.length === 0)
+    const match = allModels.find((m) => m.provider === defaultVisionProvider && m.id === defaultVisionModel);
+    if (!match || !match.input.includes("image"))
         return undefined;
-    // 1. Try admin-configured default vision model from settings
-    const settings = ctx.settingsManager;
-    if (settings) {
-        const defaultVisionProvider = settings.getDefaultVisionProvider();
-        const defaultVisionModel = settings.getDefaultVisionModel();
-        if (defaultVisionProvider && defaultVisionModel) {
-            const match = visionModels.find((m) => m.provider === defaultVisionProvider && m.id === defaultVisionModel);
-            if (match) {
-                process.stderr.write(`[spectral-vision] Using admin-configured default: ${match.provider}/${match.id}\n`);
-                return match;
-            }
-        }
+    if (!ctx.modelRegistry.hasConfiguredAuth(match))
+        return undefined;
+    return match;
+}
+/**
+ * Resolve the best vision model to use for image descriptions.
+ *
+ * Priority:
+ *   1. Admin-configured default vision model (isVisionDefault from backend)
+ *   2. Current main model if it supports images
+ *   3. Best available vision model by provider priority
+ *   4. First available vision model
+ */
+function resolveVisionModel(ctx) {
+    // 1. Admin-configured default vision model (always preferred)
+    const adminModel = getAdminVisionModel(ctx);
+    if (adminModel) {
+        process.stderr.write(`[spectral-vision] Using admin-configured default: ${adminModel.provider}/${adminModel.id}\n`);
+        return adminModel;
     }
-    // 2. Fall back to provider priority
+    // 2. Current main model if it supports images
+    const currentModel = ctx.model;
+    if (currentModel?.input.includes("image") && ctx.modelRegistry.hasConfiguredAuth(currentModel)) {
+        process.stderr.write(`[spectral-vision] Using main model for vision: ${currentModel.provider}/${currentModel.id}\n`);
+        return currentModel;
+    }
+    // 3. Fall back to best available vision model by provider priority
+    const allModels = ctx.modelRegistry.getAll();
+    const visionModels = allModels.filter((m) => m.input.includes("image") && ctx.modelRegistry.hasConfiguredAuth(m));
+    if (visionModels.length === 0)
+        return undefined;
     const providerPriority = ["anthropic", "openai", "google", "openrouter"];
     for (const provider of providerPriority) {
         const match = visionModels.find((m) => m.provider === provider);
-        if (match)
+        if (match) {
+            process.stderr.write(`[spectral-vision] Using fallback vision model: ${match.provider}/${match.id}\n`);
             return match;
+        }
     }
-    return visionModels[0];
+    // 4. First available vision model
+    const fallback = visionModels[0];
+    process.stderr.write(`[spectral-vision] Using first available vision model: ${fallback.provider}/${fallback.id}\n`);
+    return fallback;
 }
 /** Check if any content block in an array is an image */
 function hasImageContent(content) {
@@ -111,6 +143,13 @@ async function describeImages(visionModel, content, contextText, ctx) {
         const textNote = description.trim()
             ? `[Image description from ${visionModel.provider}/${visionModel.id} (${imageCount} image(s)):\n${description}\n]`
             : `[${imageCount} image(s) — vision model returned empty description]`;
+        // Notify the frontend that the vision extension analyzed the image(s)
+        try {
+            ctx.ui.notify(`[spectral-vision] Analyzed ${imageCount} image(s) with ${visionModel.provider}/${visionModel.id}`, "info");
+        }
+        catch {
+            // UI context may not be available in headless modes
+        }
         return [
             ...textPrefixBlocks,
             { type: "text", text: textNote },
@@ -119,6 +158,13 @@ async function describeImages(visionModel, content, contextText, ctx) {
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         process.stderr.write(`[spectral-vision] Vision call failed: ${msg}\n`);
+        // Notify frontend about the failure
+        try {
+            ctx.ui.notify(`[spectral-vision] Failed to analyze ${imageCount} image(s): ${msg}`, "warning");
+        }
+        catch {
+            // UI context may not be available in headless modes
+        }
         return [
             ...textPrefixBlocks,
             {
@@ -134,7 +180,7 @@ async function describeImages(visionModel, content, contextText, ctx) {
 export default function spectralVisionExtension(pi) {
     let visionModel;
     pi.on("session_start", (_event, ctx) => {
-        visionModel = findVisionModel(ctx);
+        visionModel = resolveVisionModel(ctx);
         if (visionModel) {
             process.stderr.write(`[spectral-vision] Ready — using ${visionModel.provider}/${visionModel.id} for image descriptions.\n`);
         }
@@ -151,19 +197,10 @@ export default function spectralVisionExtension(pi) {
         }
         if (totalImages === 0)
             return;
-        // Resolve vision model
-        const currentModel = ctx.model;
-        // If main model supports images, use it for vision (saves auth setup)
-        if (currentModel?.input.includes("image")) {
-            visionModel = currentModel;
-        }
-        else {
-            // Refresh vision model
-            if (!visionModel ||
-                !ctx.modelRegistry.hasConfiguredAuth(visionModel)) {
-                visionModel = findVisionModel(ctx);
-            }
-        }
+        // Re-resolve vision model each time images are encountered.
+        // This ensures automatic switching to the admin-configured default
+        // vision model even when the main model supports vision.
+        visionModel = resolveVisionModel(ctx);
         if (!visionModel) {
             process.stderr.write("[spectral-vision] No vision model available, images will be omitted\n");
             return;

package/dist/mcp/agent-dir.js

@@ -3,7 +3,7 @@ import { join, resolve } from "node:path";
 export function getAgentDir() {
     const configured = process.env.PI_CODING_AGENT_DIR?.trim();
     if (!configured) {
-        return join(homedir(), ".pi", "agent");
+        return join(homedir(), ".spectral", "agent");
     }
     if (configured === "~") {
         return homedir();

package/dist/mcp/config.js

@@ -5,7 +5,7 @@ import { dirname, join, resolve } from "node:path";
 import { getAgentPath } from "./agent-dir.js";
 const GENERIC_GLOBAL_CONFIG_PATH = join(homedir(), ".config", "mcp", "mcp.json");
 const PROJECT_CONFIG_NAME = ".mcp.json";
-const PROJECT_PI_CONFIG_NAME = ".pi/mcp.json";
+const PROJECT_MCP_CONFIG_NAME = ".spectral/mcp.json";
 const REPOPROMPT_BINARY_CANDIDATES = [
     join(homedir(), "RepoPrompt", "repoprompt_cli"),
     "/Applications/Repo Prompt.app/Contents/MacOS/repoprompt-mcp",
@@ -32,7 +32,7 @@ export function getProjectConfigPath(cwd = process.cwd()) {
     return resolve(cwd, PROJECT_CONFIG_NAME);
 }
 export function getProjectPiConfigPath(cwd = process.cwd()) {
-    return resolve(cwd, PROJECT_PI_CONFIG_NAME);
+    return resolve(cwd, PROJECT_MCP_CONFIG_NAME);
 }
 export function getConfigDiscoveryPaths(overridePath) {
     return getConfigSources(overridePath).map((source) => ({
@@ -368,7 +368,7 @@ function findProjectRoot(cwd = process.cwd()) {
         if (existsSync(join(current, ".git"))
             || existsSync(join(current, "package.json"))
             || existsSync(join(current, PROJECT_CONFIG_NAME))
-            || existsSync(join(current, ".pi"))) {
+            || existsSync(join(current, ".spectral"))) {
             return current;
         }
         const parent = dirname(current);

package/dist/mcp/sampling-handler.js

@@ -1,4 +1,4 @@
-import { complete } from "../pi/ai/index.js";
+import { complete } from "../sdk/ai/index.js";
 import { truncateAtWord } from "./utils.js";
 import { CreateMessageRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 export function registerSamplingHandler(client, options) {

package/dist/mcp/server-manager.js

@@ -96,6 +96,8 @@ export class McpServerManager {
             }
             // Check for UnauthorizedError — server requires OAuth.
             // This can fire from createHttpTransport probe or client.connect.
+            // transport may be undefined if createHttpTransport threw during the probe
+            // before returning a transport; close() handles this safely.
             if (error instanceof UnauthorizedError && supportsOAuth(definition)) {
                 return {
                     client,
@@ -239,7 +241,9 @@ export class McpServerManager {
         connection.status = "closed";
         this.connections.delete(name);
         await connection.client.close().catch(() => { });
-        await connection.transport.close().catch(() => { });
+        if (connection.transport) {
+            await connection.transport.close().catch(() => { });
+        }
     }
     async closeAll() {
         const names = [...this.connections.keys()];

package/dist/memory/commands/status.js

@@ -1,4 +1,4 @@
-import { SettingsManager } from "../../pi/coding-agent/index.js";
+import { SettingsManager } from "../../sdk/coding-agent/index.js";
 import { getMemoryState, rawTokensSinceLastBound, rawTokensSinceLastCompaction, } from "../branch.js";
 import { observationPoolTokens as estimateObservationPoolTokens } from "../compaction.js";
 import { countByRelevance, formatRelevanceHistogram } from "../relevance.js";

package/dist/memory/compaction.js

@@ -1,5 +1,5 @@
-import { agentLoop } from "../pi/agent-core/index.js";
-import { Type } from "../pi/ai/index.js";
+import { agentLoop } from "../sdk/agent-core/index.js";
+import { Type } from "../sdk/ai/index.js";
 import { debugLog, isDebugLogEnabled } from "./debug-log.js";
 import { hashId } from "./ids.js";
 import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "./model-budget.js";

package/dist/memory/config.js

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { getAgentDir } from "../pi/coding-agent/index.js";
+import { getAgentDir } from "../sdk/coding-agent/index.js";
 export const DEFAULTS = {
     observationThresholdTokens: 1_000,
     compactionThresholdTokens: 50_000,
-    reflectionThresholdTokens: 30_000,
+    reflectionThresholdTokens: 10_000,
     passive: false,
     debugLog: false,
     observerMaxChunkTokens: 30_000,
@@ -72,7 +72,7 @@ function readNamespacedConfig(path) {
 }
 export function loadConfig(cwd, env = process.env) {
     const globalPath = join(getAgentDir(), "settings.json");
-    const projectPath = join(cwd, ".pi", "settings.json");
+    const projectPath = join(cwd, ".spectral", "settings.json");
     return {
         ...DEFAULTS,
         ...readNamespacedConfig(globalPath),

package/dist/memory/debug-log.js

@@ -1,7 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { existsSync, mkdirSync, renameSync, statSync, unlinkSync, appendFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { getAgentDir } from "../pi/coding-agent/index.js";
+import { getAgentDir } from "../sdk/coding-agent/index.js";
 export const DEBUG_LOG_MAX_BYTES = 10 * 1024 * 1024;
 export const DEBUG_LOG_RELATIVE_PATH = join("observational-memory", "debug.ndjson");
 const storage = new AsyncLocalStorage();

package/dist/memory/observer.js

@@ -1,5 +1,5 @@
-import { agentLoop } from "../pi/agent-core/index.js";
-import { Type } from "../pi/ai/index.js";
+import { agentLoop } from "../sdk/agent-core/index.js";
+import { Type } from "../sdk/ai/index.js";
 import { hashId } from "./ids.js";
 import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "./model-budget.js";
 import { OBSERVER_SYSTEM } from "./prompts.js";

package/dist/memory/tokens.js

@@ -1,4 +1,4 @@
-import { estimateTokens as estimateMessageTokens } from "../pi/coding-agent/index.js";
+import { estimateTokens as estimateMessageTokens } from "../sdk/coding-agent/index.js";
 export function estimateStringTokens(text) {
     return Math.ceil(text.length / 4);
 }

package/dist/memory/tools/read-project-observations.js

@@ -1,5 +1,5 @@
-import { Type } from "../../pi/ai/index.js";
-import { defineTool } from "../../pi/coding-agent/index.js";
+import { Type } from "../../sdk/ai/index.js";
+import { defineTool } from "../../sdk/coding-agent/index.js";
 import { getProjectObsStore } from "../project-observations-store.js";
 export const READ_PROJECT_OBSERVATIONS_TOOL_NAME = "read_project_observations";
 export const readProjectObservationsTool = defineTool({

package/dist/memory/tools/recall-observation.js

@@ -1,5 +1,5 @@
-import { Type } from "../../pi/ai/index.js";
-import { defineTool } from "../../pi/coding-agent/index.js";
+import { Type } from "../../sdk/ai/index.js";
+import { defineTool } from "../../sdk/coding-agent/index.js";
 import { recallMemorySources, } from "../branch.js";
 import { renderRecallSourceEntries, renderRecallSourceEntry } from "../serialize.js";
 import { estimateEntryTokens } from "../tokens.js";

package/dist/relay/auto-research.js

@@ -1,6 +1,6 @@
 /**
  * Auto-research handler — sends an auto-research task through the existing
- * PiBridge (backend proxy) instead of spawning a separate pi process.
+ * AgentBridge (backend proxy) instead of spawning a separate pi process.
  *
  * This ensures auto-research uses the same model and API keys as the active
  * session — no separate subprocess, no missing API key errors.
@@ -47,12 +47,12 @@ function makeRelaySubscriber(sessionId, relay) {
     };
 }
 /**
- * Scan the project's .pi/extensions/auto-research/ directory for generated
+ * Scan the project's .spectral/extensions/auto-research/ directory for generated
  * extension directories. Each subdirectory with .ts files counts as one
  * extension.
  */
 function scanGeneratedExtensions(projectPath) {
-    const arDir = path.join(projectPath, ".pi", "extensions", "auto-research");
+    const arDir = path.join(projectPath, ".spectral", "extensions", "auto-research");
     const extensions = [];
     try {
         if (!fs.existsSync(arDir))
@@ -105,7 +105,7 @@ function scanGeneratedExtensions(projectPath) {
             }
             extensions.push({
                 name: entry.name,
-                path: `.pi/extensions/auto-research/${entry.name}`,
+                path: `.spectral/extensions/auto-research/${entry.name}`,
                 description,
                 usesLLM,
                 fileCount,
@@ -137,7 +137,7 @@ function hasAgentsMdUpdate(projectPath) {
  */
 function readManifest(projectPath) {
     try {
-        const mPath = path.join(projectPath, ".pi", "extensions", "auto-research", "manifest.json");
+        const mPath = path.join(projectPath, ".spectral", "extensions", "auto-research", "manifest.json");
         if (!fs.existsSync(mPath))
             return null;
         const raw = fs.readFileSync(mPath, "utf-8");
@@ -164,7 +164,7 @@ function gatherPreRunContext(projectPath) {
     const isIncremental = manifest !== null;
     const existingExtensions = [];
     try {
-        const arDir = path.join(projectPath, ".pi", "extensions", "auto-research");
+        const arDir = path.join(projectPath, ".spectral", "extensions", "auto-research");
         if (fs.existsSync(arDir)) {
             for (const entry of fs.readdirSync(arDir, { withFileTypes: true })) {
                 if (entry.isDirectory() && entry.name !== "node_modules") {
@@ -209,7 +209,7 @@ function buildIncrementalSection(ctx) {
     if (ctx.existingExtensions.length > 0) {
         lines.push("### Existing extensions to review:");
         for (const name of ctx.existingExtensions) {
-            lines.push(`  - \`.pi/extensions/auto-research/${name}/\``);
+            lines.push(`  - \`.spectral/extensions/auto-research/${name}/\``);
         }
         lines.push("");
     }
@@ -224,7 +224,7 @@ function buildIncrementalSection(ctx) {
     lines.push("   was removed from the project, delete the extension directory entirely.", "");
     lines.push("4. **Update AGENTS.md** — The AUTO-RESEARCH section should reflect the CURRENT");
     lines.push("   set of extensions (remove stale entries, add new ones).", "");
-    lines.push("5. **Save manifest.json** — Write/update .pi/extensions/auto-research/manifest.json");
+    lines.push("5. **Save manifest.json** — Write/update .spectral/extensions/auto-research/manifest.json");
     lines.push(`   with: lastRun (ISO), lastCommit (git HEAD), runCount (${ctx.manifest ? ctx.manifest.runCount + 1 : 1}),`);
     lines.push("   and extensions array with name/path/category for each generated extension.", "");
     return lines.join("\n");
@@ -234,7 +234,7 @@ function buildIncrementalSection(ctx) {
  */
 function writeManifest(projectPath, extensions) {
     try {
-        const arDir = path.join(projectPath, ".pi", "extensions", "auto-research");
+        const arDir = path.join(projectPath, ".spectral", "extensions", "auto-research");
         if (!fs.existsSync(arDir))
             fs.mkdirSync(arDir, { recursive: true });
         let currentCommit = "unknown";
@@ -257,7 +257,7 @@ function writeManifest(projectPath, extensions) {
 }
 /**
  * Build the auto-research task prompt. This is sent as a user message
- * through the existing PiBridge, so the agent uses the session's model
+ * through the existing AgentBridge, so the agent uses the session's model
  * and backend proxy.
  *
  * @param projectPath Absolute path to the project root
@@ -297,8 +297,8 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
         "}",
         "```",
         "",
-        "Extensions live in: `.pi/extensions/` (project-local) or `~/.pi/agent/extensions/` (user-global).",
-        "Auto-research generates extensions into `.pi/extensions/auto-research/<name>/`.",
+        "Extensions live in: `.spectral/extensions/` (project-local) or `~/.spectral/agent/extensions/` (user-global).",
+        "Auto-research generates extensions into `.spectral/extensions/auto-research/<name>/`.",
         "",
         "### Tools (pi.registerTool)",
         "",
@@ -400,10 +400,10 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
         "",
         "### Extension File Structure",
         "",
-        "Each extension is a directory under `.pi/extensions/auto-research/`:",
+        "Each extension is a directory under `.spectral/extensions/auto-research/`:",
         "",
         "```",
-        ".pi/extensions/auto-research/",
+        ".spectral/extensions/auto-research/",
         "  <extension-name>/",
         "    index.ts          # Entry point — default export activate(pi)",
         "    utils.ts          # [optional] Helper functions",
@@ -440,7 +440,7 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
         "",
         "1. **Context Collection** — Explore the project structure:",
         "   - Read package.json, tsconfig.json, deno.json (if present)",
-        "   - Check existing extensions under .pi/extensions/",
+        "   - Check existing extensions under .spectral/extensions/",
         "   - Review key source files to understand architecture",
         "   - Check git log for recent changes and patterns",
         "",
@@ -454,9 +454,9 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
         "   - Use `pi.registerTool()` for simple tools with TypeBox validation",
         "   - Use `pi.registerCommand()` for custom slash commands",
         "   - For LLM-powered extensions, use `ctx.modelRegistry` to call models",
-        "   - Create files under `.pi/extensions/auto-research/<name>/`",
+        "   - Create files under `.spectral/extensions/auto-research/<name>/`",
         "   - Each extension needs an `index.ts` that registers its tools/commands",
-        "   - Read `.pi/agents/auto-research-templates.md` for proven extension templates",
+        "   - Read `.spectral/agents/auto-research-templates.md` for proven extension templates",
         "",
         "4. **Validation** — Verify generated extensions:",
         "   - Ensure all imports resolve to available packages (see reference above)",
@@ -478,7 +478,7 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
         "",
         "### Important Rules",
         "",
-        "- Write each extension as TypeScript files under `.pi/extensions/auto-research/<name>/`",
+        "- Write each extension as TypeScript files under `.spectral/extensions/auto-research/<name>/`",
         "- Every extension directory MUST have an `index.ts` entry point",
         "- Use proper TypeScript with type annotations and error handling",
         "- Extensions must handle errors gracefully (never crash the agent)",
@@ -491,7 +491,7 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
         "agent sessions automatically know about the new capabilities.",
         "",
         "**How AGENTS.md works:**",
-        "- Pi loads AGENTS.md at startup from the project root and parent directories",
+        "- Spectral loads AGENTS.md at startup from the project root and parent directories",
         "- All found AGENTS.md files are concatenated and injected into the system prompt",
         "- This means documented extensions get discovered by the agent automatically",
         "",
@@ -502,7 +502,7 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
         "## Auto-Generated Extensions",
         "",
         "These extensions were generated by auto-research. They are available",
-        "in every session. Pi loads them automatically from `.pi/extensions/`.",
+        "in every session. Spectral loads them automatically from `.spectral/extensions/`.",
         "",
         "### `<extension-name>`",
         "",
@@ -539,7 +539,7 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
 // ---------------------------------------------------------------------------
 const AR_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes — generous for LLM-based analysis
 /**
- * Execute auto-research for a project through the existing PiBridge.
+ * Execute auto-research for a project through the existing AgentBridge.
  *
  * Caller (dispatcher) is fire-and-forget — this function is `void` and
  * all errors are surfaced as `auto_research_error` events on the wire
@@ -547,7 +547,7 @@ const AR_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes — generous for LLM-based a
  *
  * This replaces the old subprocess-spawning approach. Instead of launching
  * a separate pi process (which lacks backend proxy credentials), we send
- * the auto-research task through the session's existing PiBridge. The agent
+ * the auto-research task through the session's existing AgentBridge. The agent
  * uses the session's model, backend proxy, and all available tools.
  */
 export function handleAutoResearch(input, deps) {
@@ -700,7 +700,7 @@ export function handleAutoResearch(input, deps) {
     // then timeout fires and calls finalize() again — but finalize() is
     // gated by watcherFired, so it's a no-op. The only issue is we don't
     // clearTimeout on watcher fire — but that's fine, the timer is harmless.
-    // --- Send the prompt through the existing PiBridge (backend proxy) ---
+    // --- Send the prompt through the existing AgentBridge (backend proxy) ---
     manager.prompt(sessionId, taskContent, storedModelId).catch((err) => {
         if (watcherFired)
             return; // already handled by watcher