@bastani/atomic 0.8.1-1 → 0.8.2-0

package/dist/builtin/subagents/src/runs/shared/subagent-prompt-runtime.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { APP_NAME } from "@bastani/atomic";
+import { APP_NAME, getEnvValue } from "@bastani/atomic";
 
 const ENV_PREFIX = APP_NAME.toUpperCase();
 const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = `${ENV_PREFIX}_SUBAGENT_INHERIT_PROJECT_CONTEXT`;
@@ -28,7 +28,7 @@ const SKILLS_HEADER = "\n\nThe following skills provide specialized instructions
 const DATE_HEADER = "\nCurrent date:";
 
 function readBooleanEnv(name: string): boolean | undefined {
-	const value = process.env[name];
+	const value = getEnvValue(name);
 	if (value === undefined) return undefined;
 	return value !== "0";
 }
@@ -134,7 +134,7 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 	});
 
 	pi.on("before_agent_start", async (event) => {
-		const intercomSessionName = process.env[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
+		const intercomSessionName = getEnvValue(SUBAGENT_INTERCOM_SESSION_NAME_ENV)?.trim();
 		if (intercomSessionName && typeof pi.setSessionName === "function") {
 			pi.setSessionName(intercomSessionName);
 		}

package/dist/builtin/subagents/src/shared/artifacts.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { CONFIG_DIR_NAME } from "@bastani/atomic";
+import { getAgentConfigPaths } from "@bastani/atomic";
 import { TEMP_ARTIFACTS_DIR, type ArtifactPaths } from "./types.ts";
 const CLEANUP_MARKER_FILE = ".last-cleanup";
 
@@ -75,25 +75,26 @@ export function cleanupOldArtifacts(dir: string, maxAgeDays: number): void {
 export function cleanupAllArtifactDirs(maxAgeDays: number): void {
 	cleanupOldArtifacts(TEMP_ARTIFACTS_DIR, maxAgeDays);
 
-	const sessionsBase = path.join(os.homedir(), CONFIG_DIR_NAME, "agent", "sessions");
-	if (!fs.existsSync(sessionsBase)) return;
+	for (const sessionsBase of getAgentConfigPaths("sessions")) {
+		if (!fs.existsSync(sessionsBase)) continue;
 
-	let dirs: string[];
-	try {
-		dirs = fs.readdirSync(sessionsBase);
-	} catch {
-		// Session artifact cleanup is best-effort. If the sessions root cannot be read,
-		// skip cleanup instead of failing extension startup.
-		return;
-	}
-
-	for (const dir of dirs) {
-		const artifactsDir = path.join(sessionsBase, dir, "subagent-artifacts");
+		let dirs: string[];
 		try {
-			cleanupOldArtifacts(artifactsDir, maxAgeDays);
+			dirs = fs.readdirSync(sessionsBase);
 		} catch {
-			// Session cleanup is best-effort. Keep going so one unreadable session dir
-			// does not block cleanup for the rest.
+			// Session artifact cleanup is best-effort. If the sessions root cannot be read,
+			// skip cleanup instead of failing extension startup.
+			continue;
+		}
+
+		for (const dir of dirs) {
+			const artifactsDir = path.join(sessionsBase, dir, "subagent-artifacts");
+			try {
+				cleanupOldArtifacts(artifactsDir, maxAgeDays);
+			} catch {
+				// Session cleanup is best-effort. Keep going so one unreadable session dir
+				// does not block cleanup for the rest.
+			}
 		}
 	}
 }

package/dist/builtin/subagents/src/shared/types.ts

@@ -7,7 +7,7 @@ import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
 import type { FSWatcher } from "node:fs";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { APP_NAME } from "@bastani/atomic";
+import { APP_NAME, getEnvValue } from "@bastani/atomic";
 
 const ENV_PREFIX = APP_NAME.toUpperCase();
 const SUBAGENT_MAX_DEPTH_ENV = `${ENV_PREFIX}_SUBAGENT_MAX_DEPTH`;
@@ -650,7 +650,7 @@ export function normalizeMaxSubagentDepth(value: unknown): number | undefined {
 }
 
 export function resolveCurrentMaxSubagentDepth(configMaxDepth?: number): number {
-	return normalizeMaxSubagentDepth(process.env[SUBAGENT_MAX_DEPTH_ENV])
+	return normalizeMaxSubagentDepth(getEnvValue(SUBAGENT_MAX_DEPTH_ENV))
 		?? normalizeMaxSubagentDepth(configMaxDepth)
 		?? DEFAULT_SUBAGENT_MAX_DEPTH;
 }
@@ -662,14 +662,14 @@ export function resolveChildMaxSubagentDepth(parentMaxDepth: number, agentMaxDep
 }
 
 export function checkSubagentDepth(configMaxDepth?: number): { blocked: boolean; depth: number; maxDepth: number } {
-	const depth = Number(process.env[SUBAGENT_DEPTH_ENV] ?? "0");
+	const depth = Number(getEnvValue(SUBAGENT_DEPTH_ENV) ?? "0");
 	const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth);
 	const blocked = Number.isFinite(depth) && depth >= maxDepth;
 	return { blocked, depth, maxDepth };
 }
 
 export function getSubagentDepthEnv(maxDepth?: number): Record<string, string> {
-	const parentDepth = Number(process.env[SUBAGENT_DEPTH_ENV] ?? "0");
+	const parentDepth = Number(getEnvValue(SUBAGENT_DEPTH_ENV) ?? "0");
 	const nextDepth = Number.isFinite(parentDepth) ? parentDepth + 1 : 1;
 	return {
 		[SUBAGENT_DEPTH_ENV]: String(nextDepth),

package/dist/builtin/web-access/config-paths.ts

@@ -0,0 +1,11 @@
+import { existsSync } from "node:fs";
+import { getUserConfigPaths } from "@bastani/atomic";
+
+export const WEB_SEARCH_CONFIG_PATHS = getUserConfigPaths("web-search.json");
+export const WEB_SEARCH_CONFIG_PATH = WEB_SEARCH_CONFIG_PATHS[0] ?? "~/.atomic/web-search.json";
+export const EXA_USAGE_PATHS = getUserConfigPaths("exa-usage.json");
+export const EXA_USAGE_PATH = EXA_USAGE_PATHS[0] ?? "~/.atomic/exa-usage.json";
+
+export function findReadableConfigPath(paths = WEB_SEARCH_CONFIG_PATHS): string {
+	return paths.find((path) => existsSync(path)) ?? paths[0] ?? WEB_SEARCH_CONFIG_PATH;
+}

package/dist/builtin/web-access/exa.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { CONFIG_DIR_NAME } from "@bastani/atomic";
+import { EXA_USAGE_PATH, findReadableConfigPath } from "./config-paths.ts";
 import { activityMonitor } from "./activity.js";
 import type { ExtractedContent } from "./extract.js";
 import type { SearchOptions, SearchResponse } from "./perplexity.js";
@@ -9,8 +10,8 @@ import type { SearchOptions, SearchResponse } from "./perplexity.js";
 const EXA_ANSWER_URL = "https://api.exa.ai/answer";
 const EXA_SEARCH_URL = "https://api.exa.ai/search";
 const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
-const CONFIG_PATH = join(homedir(), CONFIG_DIR_NAME, "web-search.json");
-const USAGE_PATH = join(homedir(), CONFIG_DIR_NAME, "exa-usage.json");
+const CONFIG_PATH = findReadableConfigPath();
+const USAGE_PATH = EXA_USAGE_PATH;
 
 const MONTHLY_LIMIT = 1000;
 const WARNING_THRESHOLD = 800;

package/dist/builtin/web-access/gemini-api.ts

@@ -2,9 +2,10 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { CONFIG_DIR_NAME } from "@bastani/atomic";
+import { findReadableConfigPath } from "./config-paths.ts";
 
 export const API_BASE = "https://generativelanguage.googleapis.com/v1beta";
-const CONFIG_PATH = join(homedir(), CONFIG_DIR_NAME, "web-search.json");
+const CONFIG_PATH = findReadableConfigPath();
 export const DEFAULT_MODEL = "gemini-3-flash-preview";
 
 interface GeminiApiConfig {

package/dist/builtin/web-access/gemini-search.ts

@@ -7,6 +7,7 @@ import { getApiKey, API_BASE, DEFAULT_MODEL } from "./gemini-api.js";
 import { isGeminiWebAvailable, queryWithCookies } from "./gemini-web.js";
 import { isPerplexityAvailable, searchWithPerplexity, type SearchResult, type SearchResponse, type SearchOptions } from "./perplexity.js";
 import { hasExaApiKey, isExaAvailable, searchWithExa } from "./exa.js";
+import { findReadableConfigPath } from "./config-paths.ts";
 
 export type SearchProvider = "auto" | "perplexity" | "gemini" | "exa";
 export type ResolvedSearchProvider = Exclude<SearchProvider, "auto">;
@@ -15,7 +16,7 @@ export interface AttributedSearchResponse extends SearchResponse {
 	provider: ResolvedSearchProvider;
 }
 
-const CONFIG_PATH = join(homedir(), CONFIG_DIR_NAME, "web-search.json");
+const CONFIG_PATH = findReadableConfigPath();
 
 let cachedSearchConfig: { searchProvider: SearchProvider; searchModel?: string } | null = null;
 

package/dist/builtin/web-access/gemini-web-config.ts

@@ -2,8 +2,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { APP_NAME, CONFIG_DIR_NAME } from "@bastani/atomic";
+import { findReadableConfigPath } from "./config-paths.ts";
 
-const CONFIG_PATH = join(homedir(), CONFIG_DIR_NAME, "web-search.json");
+const CONFIG_PATH = findReadableConfigPath();
 const ALLOW_BROWSER_COOKIES_ENV = `${APP_NAME.toUpperCase()}_ALLOW_BROWSER_COOKIES`;
 
 interface GeminiWebConfig {

package/dist/builtin/web-access/github-extract.ts

@@ -6,8 +6,9 @@ import { CONFIG_DIR_NAME } from "@bastani/atomic";
 import { activityMonitor } from "./activity.js";
 import type { ExtractedContent } from "./extract.js";
 import { checkGhAvailable, checkRepoSize, fetchViaApi, showGhHint } from "./github-api.js";
+import { findReadableConfigPath } from "./config-paths.ts";
 
-const CONFIG_PATH = join(homedir(), CONFIG_DIR_NAME, "web-search.json");
+const CONFIG_PATH = findReadableConfigPath();
 
 const BINARY_EXTENSIONS = new Set([
 	".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".webp", ".svg", ".tiff", ".tif",

package/dist/builtin/web-access/index.ts

@@ -33,14 +33,16 @@ import { createRequire } from "node:module";
 import { platform, homedir } from "node:os";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
-import { CONFIG_DIR_NAME } from "@bastani/atomic";
+import { CONFIG_DIR_NAME, getUserConfigPaths } from "@bastani/atomic";
+import { findReadableConfigPath } from "./config-paths.ts";
 import { isPerplexityAvailable } from "./perplexity.js";
 import { isExaAvailable } from "./exa.js";
 import { isGeminiApiAvailable } from "./gemini-api.js";
 import { getActiveGoogleEmail, isGeminiWebAvailable } from "./gemini-web.js";
 import { isBrowserCookieAccessAllowed } from "./gemini-web-config.ts";
 
-const WEB_SEARCH_CONFIG_PATH = join(homedir(), CONFIG_DIR_NAME, "web-search.json");
+const WEB_SEARCH_CONFIG_PATH = getUserConfigPaths("web-search.json")[0] ?? join(homedir(), CONFIG_DIR_NAME, "web-search.json");
+const WEB_SEARCH_CONFIG_READ_PATH = findReadableConfigPath();
 
 interface WebSearchConfig {
 	provider?: string;
@@ -69,25 +71,26 @@ interface CuratorBootstrap {
 }
 
 function loadConfig(): WebSearchConfig {
-	if (!existsSync(WEB_SEARCH_CONFIG_PATH)) return {};
-	const raw = readFileSync(WEB_SEARCH_CONFIG_PATH, "utf-8");
+	if (!existsSync(WEB_SEARCH_CONFIG_READ_PATH)) return {};
+	const raw = readFileSync(WEB_SEARCH_CONFIG_READ_PATH, "utf-8");
 	try {
 		return JSON.parse(raw) as WebSearchConfig;
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
-		throw new Error(`Failed to parse ${WEB_SEARCH_CONFIG_PATH}: ${message}`);
+		throw new Error(`Failed to parse ${WEB_SEARCH_CONFIG_READ_PATH}: ${message}`);
 	}
 }
 
 function saveConfig(updates: Partial<WebSearchConfig>): void {
 	let config: Record<string, unknown> = {};
-	if (existsSync(WEB_SEARCH_CONFIG_PATH)) {
-		const raw = readFileSync(WEB_SEARCH_CONFIG_PATH, "utf-8");
+	const existingConfigPath = findReadableConfigPath();
+	if (existsSync(existingConfigPath)) {
+		const raw = readFileSync(existingConfigPath, "utf-8");
 		try {
 			config = JSON.parse(raw) as Record<string, unknown>;
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
-			throw new Error(`Failed to parse ${WEB_SEARCH_CONFIG_PATH}: ${message}`);
+			throw new Error(`Failed to parse ${existingConfigPath}: ${message}`);
 		}
 	}
 

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.8.1-1",
+  "version": "0.8.2-0",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction.",
   "contributors": [

package/dist/builtin/web-access/perplexity.ts

@@ -4,9 +4,10 @@ import { join } from "node:path";
 import { CONFIG_DIR_NAME } from "@bastani/atomic";
 import { activityMonitor } from "./activity.js";
 import type { ExtractedContent } from "./extract.js";
+import { findReadableConfigPath } from "./config-paths.ts";
 
 const PERPLEXITY_API_URL = "https://api.perplexity.ai/chat/completions";
-const CONFIG_PATH = join(homedir(), CONFIG_DIR_NAME, "web-search.json");
+const CONFIG_PATH = findReadableConfigPath();
 
 const RATE_LIMIT = {
 	maxRequests: 10,

package/dist/builtin/web-access/video-extract.ts

@@ -9,8 +9,9 @@ import { isGeminiWebAvailable, queryWithCookies } from "./gemini-web.js";
 import { queryGeminiApiWithVideo, getApiKey, API_BASE } from "./gemini-api.js";
 import { extractHeadingTitle, type ExtractedContent, type ExtractOptions, type FrameResult } from "./extract.js";
 import { readExecError, trimErrorText, mapFfmpegError } from "./utils.js";
+import { findReadableConfigPath } from "./config-paths.ts";
 
-const CONFIG_PATH = join(homedir(), CONFIG_DIR_NAME, "web-search.json");
+const CONFIG_PATH = findReadableConfigPath();
 const UPLOAD_BASE = "https://generativelanguage.googleapis.com/upload/v1beta";
 
 const DEFAULT_VIDEO_PROMPT = `Extract the complete content of this video. Include:

package/dist/builtin/web-access/youtube-extract.ts

@@ -9,8 +9,9 @@ import { isGeminiApiAvailable, queryGeminiApiWithVideo } from "./gemini-api.js";
 import { searchWithPerplexity } from "./perplexity.js";
 import { extractHeadingTitle, type ExtractedContent, type FrameResult, type VideoFrame } from "./extract.js";
 import { formatSeconds, readExecError, isTimeoutError, trimErrorText, mapFfmpegError } from "./utils.js";
+import { findReadableConfigPath } from "./config-paths.ts";
 
-const CONFIG_PATH = join(homedir(), CONFIG_DIR_NAME, "web-search.json");
+const CONFIG_PATH = findReadableConfigPath();
 
 const YOUTUBE_PROMPT = `Extract the complete content of this YouTube video. Include:
 1. Video title, channel name, and duration

package/dist/builtin/workflows/builtin/deep-research-codebase.ts

@@ -185,6 +185,8 @@ export default defineWorkflow("deep-research-codebase")
       codebaseLines,
     );
 
+    let noAskQuestionToolSet = ["read, bash, edit, write, todo"];
+
     let plannerModelConfig = {
       model: "openai/gpt-5.5",
       fallbackModels: [
@@ -193,6 +195,7 @@ export default defineWorkflow("deep-research-codebase")
         "github-copilot/claude-opus-4.7",
       ],
       thinkingLevel: "high" as const,
+      tools: noAskQuestionToolSet,
     };
 
     let explorerModelConfig = {
@@ -203,6 +206,7 @@ export default defineWorkflow("deep-research-codebase")
         "github-copilot/claude-haiku-4.5",
       ],
       thinkingLevel: "low" as const,
+      tools: noAskQuestionToolSet,
     };
 
     const initialDiscovery = await ctx.parallel(

package/dist/builtin/workflows/builtin/open-claude-design.ts

@@ -122,8 +122,8 @@ function prepareArtifactDir(): {
 } {
   const runId = `${new Date().toISOString().replace(/[:.]/g, "-")}-${Math.random().toString(36).slice(2, 8)}`;
   const candidates = [
-    join(process.cwd(), ".atomic", "workflows", "open-claude-design", runId),
-    join(tmpdir(), "pi-open-claude-design", runId),
+    join(process.cwd(), "specs", "design", runId),
+    join(tmpdir(), "open-claude-design", runId),
   ];
   for (const candidate of candidates) {
     try {
@@ -164,6 +164,13 @@ const ANTI_SLOP_RULES = [
   "Commit to a specific aesthetic direction; do not hedge with generic SaaS defaults.",
 ].join("\n");
 
+const PLAYWRIGHT_BROWSER_BOOTSTRAP_RULES = [
+  "Probe for playwright-cli availability with `playwright-cli --version` (or `npx --no-install playwright-cli --version` when relying on a project-local install). Do not install playwright-cli itself.",
+  "If playwright-cli is available but opening a page fails because Chrome, Chrome for Testing, Chromium, or another browser executable is not installed, run `playwright-cli install-browser chrome-for-testing` (or the equivalent `npx --no-install playwright-cli install-browser chrome-for-testing`) and retry the browser action once.",
+  "Only install the missing browser runtime; do not install npm packages, change project dependencies, or repeatedly retry failed installs.",
+  "If playwright-cli is unavailable or browser installation still fails, degrade gracefully and surface the manual file path / URL.",
+].join("\n");
+
 export default defineWorkflow("open-claude-design")
   .description(
     "AI-powered design workflow: design-system onboarding → reference import → HTML generation → impeccable-driven refinement → quality gate → rich HTML handoff. Each stage delegates to a specific impeccable sub-skill; the user can iteratively review and annotate the generated HTML through playwright-cli.",
@@ -447,13 +454,15 @@ export default defineWorkflow("open-claude-design")
             "impeccable_skill",
             "extract — separate one-off styling from repeated, intentional patterns. Only carry forward what is used 3+ times or what is structurally load-bearing.",
           ],
+          ["playwright_browser_bootstrap", PLAYWRIGHT_BROWSER_BOOTSTRAP_RULES],
           [
             "instructions",
             [
               "1. Use browser/screenshot tooling (e.g. playwright-cli) if available; cite observable evidence rather than guessing.",
-              "2. Analyze: layout, visual hierarchy, navigation, color, typography, spacing, states, interactions, responsive behavior.",
-              "3. Separate reference-specific styling from requirements that should transfer to this project's design system.",
-              "4. If the URL is inaccessible, state that and provide a best-effort fallback based only on available information — never fabricate observations.",
+              "2. If playwright-cli is available but opening the reference URL reports a missing browser executable, install Chrome for Testing with the bootstrap command and retry once.",
+              "3. Analyze: layout, visual hierarchy, navigation, color, typography, spacing, states, interactions, responsive behavior.",
+              "4. Separate reference-specific styling from requirements that should transfer to this project's design system.",
+              "5. If the URL is inaccessible or browser bootstrap fails, state that and provide a best-effort fallback based only on available information — never fabricate observations.",
             ].join("\n"),
           ],
           [
@@ -573,14 +582,16 @@ export default defineWorkflow("open-claude-design")
           ],
           ["preview_path", previewPath],
           ["preview_file_url", previewFileUrl],
+          ["playwright_browser_bootstrap", PLAYWRIGHT_BROWSER_BOOTSTRAP_RULES],
           [
             "instructions",
             [
-              "1. Probe for playwright-cli availability by running `playwright-cli --version` (or `npx --no-install playwright-cli --version`). Do not install anything.",
-              `2. If available, run: \`playwright-cli open ${previewFileUrl}\` then \`playwright-cli show --annotate\` so the user can draw boxes and leave notes directly on the live page.`,
-              "3. Once the user finishes annotating, capture the returned annotated snapshot path / notes and surface them in your output.",
-              `4. If playwright-cli is NOT available, do not attempt installation. Instead, print a clear instruction block telling the user to open the file manually at: ${previewPath} (or via the URL ${previewFileUrl}).`,
-              "5. Never block the workflow on unavailable tooling; always exit with a non-empty status string.",
+              "1. Probe for playwright-cli availability using the bootstrap rules above.",
+              `2. If available, run: \`playwright-cli open ${previewFileUrl}\`. If that reports a missing browser executable, install Chrome for Testing with the bootstrap command and retry once.`,
+              "3. Then run `playwright-cli show --annotate` so the user can draw boxes and leave notes directly on the live page.",
+              "4. Once the user finishes annotating, capture the returned annotated snapshot path / notes and surface them in your output.",
+              `5. If playwright-cli is NOT available or browser bootstrap fails, print a clear instruction block telling the user to open the file manually at: ${previewPath} (or via the URL ${previewFileUrl}).`,
+              "6. Never block the workflow on unavailable tooling; always exit with a non-empty status string.",
             ].join("\n"),
           ],
           [
@@ -699,13 +710,15 @@ export default defineWorkflow("open-claude-design")
               ["preview_path", previewPath],
               ["preview_file_url", previewFileUrl],
               ["current_design_and_feedback", "{previous}"],
+              ["playwright_browser_bootstrap", PLAYWRIGHT_BROWSER_BOOTSTRAP_RULES],
               [
                 "instructions",
                 [
-                  `1. Attempt rendering verification via playwright-cli: \`playwright-cli open ${previewFileUrl}\`, then \`playwright-cli resize 360 800\`, \`playwright-cli screenshot --filename=${join(artifactDir, `mobile-${iteration}.png`)}\`, \`playwright-cli resize 1440 900\`, \`playwright-cli screenshot --filename=${join(artifactDir, `desktop-${iteration}.png`)}\`.`,
-                  "2. Check: contrast (WCAG AA), overflow, spacing rhythm, alignment, breakpoint behavior, empty/loading/error states, keyboard/pointer affordances, focus rings, prefers-reduced-motion.",
-                  "3. If playwright-cli is unavailable, perform a static design review of the HTML source and mark every finding as `needs-rendering-verification`.",
-                  "4. Distinguish confirmed visual issues from risks that need rendering verification. Never fabricate rendered evidence.",
+                  `1. Attempt rendering verification via playwright-cli: \`playwright-cli open ${previewFileUrl}\`. If that reports a missing browser executable, install Chrome for Testing with the bootstrap command and retry once.`,
+                  `2. Then run \`playwright-cli resize 360 800\`, \`playwright-cli screenshot --filename=${join(artifactDir, `mobile-${iteration}.png`)}\`, \`playwright-cli resize 1440 900\`, \`playwright-cli screenshot --filename=${join(artifactDir, `desktop-${iteration}.png`)}\`.`,
+                  "3. Check: contrast (WCAG AA), overflow, spacing rhythm, alignment, breakpoint behavior, empty/loading/error states, keyboard/pointer affordances, focus rings, prefers-reduced-motion.",
+                  "4. If playwright-cli is unavailable or browser bootstrap fails, perform a static design review of the HTML source and mark every finding as `needs-rendering-verification`.",
+                  "5. Distinguish confirmed visual issues from risks that need rendering verification. Never fabricate rendered evidence.",
                 ].join("\n"),
               ],
               [
@@ -785,13 +798,15 @@ export default defineWorkflow("open-claude-design")
             ],
             ["preview_path", previewPath],
             ["preview_file_url", previewFileUrl],
+            ["playwright_browser_bootstrap", PLAYWRIGHT_BROWSER_BOOTSTRAP_RULES],
             [
               "instructions",
               [
-                `1. If playwright-cli is available, run \`playwright-cli goto ${previewFileUrl}\` (or open if no session is active), then \`playwright-cli show --annotate\` to invite annotated feedback.`,
-                `2. If playwright-cli is unavailable, surface the path clearly: ${previewPath} (URL: ${previewFileUrl}).`,
-                "3. Return any captured annotations as structured notes the next user-feedback step can read.",
-                "4. Do not block on unavailable tooling.",
+                `1. If playwright-cli is available, run \`playwright-cli goto ${previewFileUrl}\` (or \`playwright-cli open ${previewFileUrl}\` if no session is active). If that reports a missing browser executable, install Chrome for Testing with the bootstrap command and retry once.`,
+                "2. Then run `playwright-cli show --annotate` to invite annotated feedback.",
+                `3. If playwright-cli is unavailable or browser bootstrap fails, surface the path clearly: ${previewPath} (URL: ${previewFileUrl}).`,
+                "4. Return any captured annotations as structured notes the next user-feedback step can read.",
+                "5. Do not block on unavailable tooling.",
               ].join("\n"),
             ],
             [
@@ -948,13 +963,15 @@ export default defineWorkflow("open-claude-design")
           ["spec_file_url", specFileUrl],
           ["preview_path", previewPath],
           ["preview_file_url", previewFileUrl],
+          ["playwright_browser_bootstrap", PLAYWRIGHT_BROWSER_BOOTSTRAP_RULES],
           [
             "instructions",
             [
-              "1. Probe for playwright-cli (`playwright-cli --version` or `npx --no-install playwright-cli --version`). Never attempt installation.",
-              `2. If available, run \`playwright-cli open ${specFileUrl}\` then \`playwright-cli show --annotate\` so the user can capture any final notes.`,
-              `3. Always print, prominently, the absolute paths so the user can open them manually:\n   - Final spec: ${specPath}\n   - Approved preview: ${previewPath}`,
-              "4. Do not block the workflow; return a structured summary even if no tooling worked.",
+              "1. Probe for playwright-cli availability using the bootstrap rules above.",
+              `2. If available, run \`playwright-cli open ${specFileUrl}\`. If that reports a missing browser executable, install Chrome for Testing with the bootstrap command and retry once.`,
+              "3. Then run `playwright-cli show --annotate` so the user can capture any final notes.",
+              `4. Always print, prominently, the absolute paths so the user can open them manually:\n   - Final spec: ${specPath}\n   - Approved preview: ${previewPath}`,
+              "5. Do not block the workflow; return a structured summary even if no tooling worked.",
             ].join("\n"),
           ],
           [

package/dist/builtin/workflows/builtin/ralph.ts

@@ -152,6 +152,8 @@ export default defineWorkflow("ralph")
     let approved = false;
     let iterationsCompleted = 0;
 
+    let noAskQuestionToolSet = ["read, bash, edit, write, todo"];
+
     let plannerModelConfig = {
       model: "openai/gpt-5.5",
       fallbackModels: [
@@ -160,6 +162,7 @@ export default defineWorkflow("ralph")
         "github-copilot/claude-opus-4.7",
       ],
       thinkingLevel: "high" as const,
+      tools: noAskQuestionToolSet,
     };
 
     let orchestratorModelConfig = {
@@ -170,6 +173,7 @@ export default defineWorkflow("ralph")
         "github-copilot/claude-sonnet-4.6",
       ],
       thinkingLevel: "medium" as const,
+      tools: noAskQuestionToolSet,
     };
 
     let simplifierModelConfig = {
@@ -180,6 +184,7 @@ export default defineWorkflow("ralph")
         "github-copilot/claude-sonnet-4.6",
       ],
       thinkingLevel: "medium" as const,
+      tools: noAskQuestionToolSet,
     };
 
     let reviewerModelConfig = {
@@ -190,6 +195,7 @@ export default defineWorkflow("ralph")
         "github-copilot/claude-opus-4.7",
       ],
       thinkingLevel: "high" as const,
+      tools: noAskQuestionToolSet,
     };
 
     let explorerModelConfig = {
@@ -200,6 +206,7 @@ export default defineWorkflow("ralph")
         "github-copilot/claude-haiku-4.5",
       ],
       thinkingLevel: "low" as const,
+      tools: noAskQuestionToolSet,
     };
 
     for (let iteration = 1; iteration <= maxLoops; iteration += 1) {

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.8.1-1",
+  "version": "0.8.2-0",
   "private": true,
   "description": "pi extension for multi-stage workflow authoring and execution.",
   "contributors": [