@recapt/mcp 0.0.12-beta → 0.0.14-beta

package/dist/cli/commands/setup-self-healing-gh.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Setup Self-Healing GitHub Command
+ *
+ * Interactive wizard to set up the self-healing agentic workflow for GitHub.
+ */
+import { Command } from "commander";
+export declare const setupSelfHealingGhCommand: Command;

package/dist/cli/commands/setup-self-healing-gh.js

@@ -0,0 +1,310 @@
+/**
+ * Setup Self-Healing GitHub Command
+ *
+ * Interactive wizard to set up the self-healing agentic workflow for GitHub.
+ */
+import { Command } from "commander";
+import { exec, execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { installSkill } from "./skill.js";
+import { confirm, select, multiSelect, input, header, print, success, error, info, warn, newline, } from "../utils/prompts.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const TEMPLATES_DIR = path.resolve(__dirname, "../../../templates");
+const WORKFLOW_TEMPLATE = "self-healing.md";
+const WORKFLOW_DEST = ".github/workflows/self-healing.md";
+const ENGINES = [
+    { id: "claude", name: "Claude (Anthropic)", secretName: "ANTHROPIC_API_KEY" },
+    { id: "copilot", name: "GitHub Copilot", secretName: "COPILOT_GITHUB_TOKEN" },
+    { id: "codex", name: "Codex (OpenAI)", secretName: "OPENAI_API_KEY" },
+];
+const API_URL = process.env.RECAPT_API_URL ||
+    process.env.EXTERNAL_API_URL ||
+    "https://api.recapt.app";
+async function fetchDomains(secretKey) {
+    try {
+        const res = await fetch(`${API_URL}/v1beta/query/domains`, {
+            headers: {
+                "x-private-key": secretKey,
+                "Content-Type": "application/json",
+            },
+        });
+        if (!res.ok) {
+            return null;
+        }
+        const data = (await res.json());
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+function commandExists(cmd) {
+    try {
+        execSync(`which ${cmd}`, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function ghExtensionInstalled(extension) {
+    try {
+        const output = execSync("gh extension list", { encoding: "utf-8" });
+        return output.includes(extension);
+    }
+    catch {
+        return false;
+    }
+}
+function isGitRepo() {
+    try {
+        execSync("git rev-parse --is-inside-work-tree", { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getRepoUrl() {
+    try {
+        const url = execSync("gh repo view --json url -q .url", {
+            encoding: "utf-8",
+        }).trim();
+        return url || null;
+    }
+    catch {
+        return null;
+    }
+}
+function openBrowser(url) {
+    const platform = process.platform;
+    let command;
+    switch (platform) {
+        case "darwin":
+            command = `open "${url}"`;
+            break;
+        case "win32":
+            command = `start "" "${url}"`;
+            break;
+        default:
+            command = `xdg-open "${url}"`;
+    }
+    exec(command, (err) => {
+        if (err) {
+            info(`Could not open browser automatically. Please visit: ${url}`);
+        }
+    });
+}
+async function runSetupSelfHealingGh() {
+    header("Recapt Self-Healing GitHub Setup");
+    const cwd = process.cwd();
+    print("Checking prerequisites...");
+    newline();
+    const hasGh = commandExists("gh");
+    print(`  ${hasGh ? "[x]" : "[ ]"} gh CLI installed`);
+    if (!hasGh) {
+        newline();
+        error("GitHub CLI (gh) is required but not installed.");
+        info("Install it from: https://cli.github.com/");
+        process.exit(1);
+    }
+    const hasGhAw = ghExtensionInstalled("github/gh-aw");
+    print(`  ${hasGhAw ? "[x]" : "[ ]"} gh-aw extension installed`);
+    if (!hasGhAw) {
+        newline();
+        const shouldInstall = await confirm("gh-aw extension is required. Install it now?", true);
+        if (shouldInstall) {
+            print("Installing gh-aw extension...");
+            try {
+                execSync("gh extension install github/gh-aw", { stdio: "inherit" });
+                success("gh-aw extension installed");
+            }
+            catch {
+                error("Failed to install gh-aw extension");
+                info("Try manually: gh extension install github/gh-aw");
+                process.exit(1);
+            }
+        }
+        else {
+            error("gh-aw extension is required to continue.");
+            process.exit(1);
+        }
+    }
+    const inGitRepo = isGitRepo();
+    print(`  ${inGitRepo ? "[x]" : "[ ]"} Git repository detected`);
+    if (!inGitRepo) {
+        newline();
+        error("This command must be run from within a git repository.");
+        process.exit(1);
+    }
+    newline();
+    const engineOptions = ENGINES.map((engine) => ({
+        label: `${engine.name} (requires ${engine.secretName} secret)`,
+        value: engine,
+    }));
+    const selectedEngine = await select("Which AI engine do you want to use?", engineOptions);
+    if (!selectedEngine) {
+        error("No engine selected.");
+        process.exit(1);
+    }
+    newline();
+    // Domain selection
+    print("Configuring domain filter...");
+    info("You can optionally limit the workflow to specific domains.");
+    newline();
+    let selectedDomains = [];
+    const recaptKey = await input("Enter your RECAPT_SECRET_KEY to fetch domains (or press Enter to skip)");
+    if (recaptKey) {
+        const domains = await fetchDomains(recaptKey);
+        if (domains && domains.length > 0) {
+            const domainOptions = [
+                { label: "All domains", value: "__all__", selected: true },
+                ...domains.map((d) => ({
+                    label: d.domainName,
+                    value: d.domainName,
+                    selected: false,
+                })),
+            ];
+            const selected = await multiSelect("Which domains should this workflow analyze?", domainOptions);
+            if (!selected.includes("__all__") && selected.length > 0) {
+                selectedDomains = selected;
+                success(`Selected domains: ${selectedDomains.join(", ")}`);
+            }
+            else {
+                info("Will analyze all domains");
+            }
+        }
+        else {
+            warn("Could not fetch domains. Will analyze all domains.");
+        }
+    }
+    else {
+        const manualDomain = await input("Enter a specific domain to filter (or press Enter for all domains)");
+        if (manualDomain) {
+            selectedDomains = [manualDomain];
+            success(`Selected domain: ${manualDomain}`);
+        }
+        else {
+            info("Will analyze all domains");
+        }
+    }
+    newline();
+    print("Installing self-healing skill...");
+    const skillInstalled = installSkill(cwd, "self-healing");
+    if (!skillInstalled) {
+        error("Failed to install self-healing skill");
+        process.exit(1);
+    }
+    newline();
+    print("Creating workflow...");
+    const templatePath = path.join(TEMPLATES_DIR, WORKFLOW_TEMPLATE);
+    const destPath = path.join(cwd, WORKFLOW_DEST);
+    const destDir = path.dirname(destPath);
+    if (!fs.existsSync(templatePath)) {
+        error(`Workflow template not found: ${templatePath}`);
+        process.exit(1);
+    }
+    if (!fs.existsSync(destDir)) {
+        fs.mkdirSync(destDir, { recursive: true });
+    }
+    const templateContent = fs.readFileSync(templatePath, "utf-8");
+    // Build domain config section
+    let domainConfig = "";
+    if (selectedDomains.length > 0) {
+        const domainList = selectedDomains.join(", ");
+        domainConfig = `### Domain Restriction
+
+**Target domains:** ${domainList}
+
+Before doing any work:
+1. Call \`get_domains\` to verify the target domain(s) exist
+2. If any target domain is NOT in the list, stop immediately and report: "Domain not found: [domain]. Available domains: [list]"
+3. If domains are valid, pass the \`domain\` parameter to all tools that support filtering (e.g., \`run_full_diagnostic\`, \`get_page_metrics\`, etc.)
+
+Do NOT analyze or fix issues for domains not in the target list.
+
+`;
+    }
+    else {
+        domainConfig = `### Domain Scope
+
+**Target:** All domains
+
+Analyze and fix issues across all domains configured in recapt. Call \`get_domains\` first to see available domains.
+
+`;
+    }
+    // Replace placeholders (support both {{VAR}} and { { VAR } } formats)
+    const workflowContent = templateContent
+        .replace(/\{\s*\{\s*ENGINE\s*\}\s*\}/g, selectedEngine.id)
+        .replace(/\{\s*\{\s*DOMAIN_CONFIG\s*\}\s*\}/g, domainConfig);
+    if (fs.existsSync(destPath)) {
+        const overwrite = await confirm("Workflow file already exists. Overwrite?", false);
+        if (!overwrite) {
+            info("Skipping workflow creation");
+        }
+        else {
+            fs.writeFileSync(destPath, workflowContent);
+            success(`Created: ${WORKFLOW_DEST}`);
+        }
+    }
+    else {
+        fs.writeFileSync(destPath, workflowContent);
+        success(`Created: ${WORKFLOW_DEST}`);
+    }
+    newline();
+    print("Compiling workflow...");
+    try {
+        execSync("gh aw compile", { cwd, stdio: "inherit" });
+        success("Created: .github/workflows/self-healing.lock.yml");
+    }
+    catch {
+        warn("Failed to compile workflow. You can run 'gh aw compile' manually.");
+    }
+    newline();
+    print("GitHub Secrets Required:");
+    info(`1. ${selectedEngine.secretName} - For ${selectedEngine.name} to run the agent`);
+    info("2. RECAPT_SECRET_KEY - For recapt behavioral intelligence");
+    newline();
+    const repoUrl = getRepoUrl();
+    if (repoUrl) {
+        const secretsUrl = `${repoUrl}/settings/secrets/actions`;
+        const openSecrets = await confirm("Open GitHub secrets page?", true);
+        if (openSecrets) {
+            openBrowser(secretsUrl);
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+        }
+    }
+    else {
+        info("Go to your repository Settings → Secrets and variables → Actions");
+        info(`Add ${selectedEngine.secretName} and RECAPT_SECRET_KEY as secrets.`);
+    }
+    newline();
+    success("Setup complete!");
+    newline();
+    print("Next steps:");
+    print('  1. git add . && git commit -m "Add recapt self-healing workflow"');
+    print("  2. git push");
+    print("  3. Run manually: gh aw run self-healing");
+    newline();
+    warn("Important: Enable PR creation permissions");
+    info("The workflow needs permission to create pull requests.");
+    info("Go to Settings → Actions → General → Workflow permissions");
+    info('Enable "Allow GitHub Actions to create and approve pull requests"');
+    info("(This may need to be set at the organization level)");
+    newline();
+}
+export const setupSelfHealingGhCommand = new Command("setup-self-healing-gh")
+    .description("Set up automated self-healing workflow for GitHub Actions")
+    .action(async () => {
+    try {
+        await runSetupSelfHealingGh();
+    }
+    catch (err) {
+        error(`Setup failed: ${err}`);
+        process.exit(1);
+    }
+});

package/dist/cli/commands/skill.d.ts

@@ -12,6 +12,7 @@ interface SkillInfo {
 }
 export type { SkillInfo };
 export declare function getAvailableSkills(): SkillInfo[];
+export declare function installSkill(cwd: string, skillName: string): boolean;
 export interface InstallResult {
     success: boolean;
     installed: string[];

package/dist/cli/commands/skill.js

@@ -115,7 +115,7 @@ ${MARKER_END}`;
     }
     writeAgentsMd(cwd, content + "\n");
 }
-function installSkill(cwd, skillName) {
+export function installSkill(cwd, skillName) {
     let skills;
     try {
         skills = getAvailableSkills();

package/dist/cli/index.d.ts

@@ -5,7 +5,8 @@
  * Unified command-line interface for recapt MCP server management.
  *
  * Commands:
- *   setup     - Configure recapt MCP server for your AI IDE(s)
- *   skill     - Manage recapt workflow skills
+ *   setup                  - Configure recapt MCP server for your AI IDE(s)
+ *   setup-self-healing-gh  - Set up automated self-healing workflow for GitHub
+ *   skill                  - Manage recapt workflow skills
  */
 export {};

package/dist/cli/index.js

@@ -5,13 +5,15 @@
  * Unified command-line interface for recapt MCP server management.
  *
  * Commands:
- *   setup     - Configure recapt MCP server for your AI IDE(s)
- *   skill     - Manage recapt workflow skills
+ *   setup                  - Configure recapt MCP server for your AI IDE(s)
+ *   setup-self-healing-gh  - Set up automated self-healing workflow for GitHub
+ *   skill                  - Manage recapt workflow skills
  */
 import { Command } from "commander";
 import { createRequire } from "module";
 import { skillCommand } from "./commands/skill.js";
 import { setupCommand } from "./commands/setup.js";
+import { setupSelfHealingGhCommand } from "./commands/setup-self-healing-gh.js";
 const require = createRequire(import.meta.url);
 const pkg = require("../../package.json");
 const program = new Command();
@@ -20,5 +22,6 @@ program
     .description("Recapt MCP CLI - Configure and manage recapt for AI IDEs")
     .version(pkg.version);
 program.addCommand(setupCommand);
+program.addCommand(setupSelfHealingGhCommand);
 program.addCommand(skillCommand);
 program.parse();

package/dist/cli/utils/prompts.d.ts

@@ -1,7 +1,7 @@
 /**
  * Interactive Prompts
  *
- * Readline-based prompts for CLI interactions.
+ * Arrow-key navigable prompts for CLI interactions using @inquirer/prompts.
  */
 export declare function confirm(message: string, defaultYes?: boolean): Promise<boolean>;
 export declare function input(message: string, defaultValue?: string): Promise<string>;

package/dist/cli/utils/prompts.js

@@ -1,110 +1,47 @@
 /**
  * Interactive Prompts
  *
- * Readline-based prompts for CLI interactions.
+ * Arrow-key navigable prompts for CLI interactions using @inquirer/prompts.
  */
-import readline from "readline";
-function createInterface() {
-    return readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
-}
+import { confirm as inquirerConfirm, input as inquirerInput, password as inquirerPassword, select as inquirerSelect, checkbox as inquirerCheckbox, } from "@inquirer/prompts";
 export async function confirm(message, defaultYes = true) {
-    const hint = defaultYes ? "(Y/n)" : "(y/N)";
-    const askOnce = () => {
-        const rl = createInterface();
-        return new Promise((resolve) => {
-            rl.question(`${message} ${hint} `, (answer) => {
-                rl.close();
-                const normalized = answer.trim().toLowerCase();
-                if (normalized === "") {
-                    resolve(defaultYes);
-                }
-                else if (normalized === "y" || normalized === "yes") {
-                    resolve(true);
-                }
-                else if (normalized === "n" || normalized === "no") {
-                    resolve(false);
-                }
-                else {
-                    resolve(null);
-                }
-            });
-        });
-    };
-    let result = await askOnce();
-    while (result === null) {
-        console.log('Please enter "y" or "n"');
-        result = await askOnce();
-    }
-    return result;
+    return inquirerConfirm({
+        message,
+        default: defaultYes,
+    });
 }
 export async function input(message, defaultValue) {
-    const rl = createInterface();
-    const hint = defaultValue ? ` (${defaultValue})` : "";
-    return new Promise((resolve) => {
-        rl.question(`${message}${hint}: `, (answer) => {
-            rl.close();
-            const value = answer.trim();
-            resolve(value || defaultValue || "");
-        });
+    return inquirerInput({
+        message,
+        default: defaultValue,
     });
 }
 export async function secret(message) {
-    const rl = createInterface();
-    return new Promise((resolve) => {
-        rl.question(`${message}: `, (answer) => {
-            rl.close();
-            resolve(answer.trim());
-        });
+    return inquirerPassword({
+        message,
+        mask: "*",
     });
 }
 export async function multiSelect(message, options) {
-    const rl = createInterface();
-    console.log(`\n${message}`);
-    console.log("(Enter comma-separated numbers, or 'all' for all options)\n");
-    options.forEach((opt, i) => {
-        const marker = opt.selected ? "[x]" : "[ ]";
-        console.log(`  ${i + 1}. ${marker} ${opt.label}`);
-    });
-    return new Promise((resolve) => {
-        rl.question("\nYour selection: ", (answer) => {
-            rl.close();
-            const normalized = answer.trim().toLowerCase();
-            if (normalized === "all" || normalized === "a") {
-                resolve(options.map((o) => o.value));
-                return;
-            }
-            if (normalized === "" || normalized === "none" || normalized === "n") {
-                resolve(options.filter((o) => o.selected).map((o) => o.value));
-                return;
-            }
-            const indices = normalized
-                .split(/[,\s]+/)
-                .map((s) => parseInt(s, 10) - 1)
-                .filter((i) => i >= 0 && i < options.length);
-            resolve(indices.map((i) => options[i].value));
-        });
+    return inquirerCheckbox({
+        message,
+        choices: options.map((opt) => ({
+            name: opt.label,
+            value: opt.value,
+            checked: opt.selected ?? false,
+        })),
     });
 }
 export async function select(message, options) {
-    const rl = createInterface();
-    console.log(`\n${message}\n`);
-    options.forEach((opt, i) => {
-        console.log(`  ${i + 1}. ${opt.label}`);
-    });
-    return new Promise((resolve) => {
-        rl.question("\nYour selection: ", (answer) => {
-            rl.close();
-            const index = parseInt(answer.trim(), 10) - 1;
-            if (index >= 0 && index < options.length) {
-                resolve(options[index].value);
-            }
-            else {
-                resolve(null);
-            }
-        });
+    if (options.length === 0) {
+        return null;
+    }
+    return inquirerSelect({
+        message,
+        choices: options.map((opt) => ({
+            name: opt.label,
+            value: opt.value,
+        })),
     });
 }
 export function print(message) {

package/dist/index.js

@@ -96,6 +96,46 @@ function registerHiddenTools() {
     // Session Analysis
     registerToolHandler("search_sessions", createApiHandler("POST", "/sessions/search"));
     registerToolHandler("list_sessions", createApiHandler("GET", "/sessions"));
+    registerToolHandler("get_session_pages", async (args) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { session_id, session_ids } = args;
+        if (!session_id && (!session_ids || session_ids.length === 0)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Either session_id or session_ids must be provided",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const isSingleSession = session_id && !session_ids;
+        const { data, error } = isSingleSession
+            ? await apiGet(`/sessions/${session_id}/pages`)
+            : await apiPost("/sessions/pages", {
+                session_ids: session_ids ?? [session_id],
+            });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
     registerToolHandler("get_session_details", async (args) => {
         if (!isApiConfigured()) {
             return {

package/dist/tools/catalog/toolCatalog.json

@@ -14629,7 +14629,7 @@
       "category": {
         "type": "string",
         "required": false,
-        "description": "Filter by knowledge category"
+        "description": "Filter by category: false_positive, intended_behavior, fix_pattern, or context"
       },
       "page_path": {
         "type": "string",
@@ -14639,7 +14639,7 @@
       "issue_category": {
         "type": "string",
         "required": false,
-        "description": "Filter by issue category"
+        "description": "Filter by issue category: code_error, dead_click, rage_click, ux_friction, performance, form_issue, behavioral_anomaly, or structural_issue"
       },
       "limit": {
         "type": "number",
@@ -15042,7 +15042,7 @@
       "category": {
         "type": "string",
         "required": true,
-        "description": "Category of knowledge"
+        "description": "Category: false_positive, intended_behavior, fix_pattern, or context"
       },
       "subject": {
         "type": "string",
@@ -15067,7 +15067,7 @@
       "issue_category": {
         "type": "string",
         "required": false,
-        "description": "Associated issue category"
+        "description": "Issue category: code_error, dead_click, rage_click, ux_friction, performance, form_issue, behavioral_anomaly, or structural_issue"
       }
     },
     "embedding": [

package/dist/tools/getSessionPages.d.ts

@@ -0,0 +1,7 @@
+/**
+ * get_session_pages tool
+ *
+ * Returns the pages visited within one or more sessions.
+ * Thin proxy to external-api /sessions/:id/pages and /sessions/pages endpoints.
+ */
+export declare function registerGetSessionPages(server: any): void;

package/dist/tools/getSessionPages.js

@@ -0,0 +1,74 @@
+/**
+ * get_session_pages tool
+ *
+ * Returns the pages visited within one or more sessions.
+ * Thin proxy to external-api /sessions/:id/pages and /sessions/pages endpoints.
+ */
+import { z } from "zod";
+import { apiGet, apiPost, isApiConfigured } from "../api/client.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerGetSessionPages(server) {
+    server.registerTool("get_session_pages", {
+        description: "Get the pages visited within one or more sessions. Returns navigation history " +
+            "with timestamps, source pages, and dwell times. Use this to understand the " +
+            "user's journey through the site during a session. Accepts a single session_id " +
+            "or an array of session_ids (max 20).",
+        inputSchema: z.object({
+            session_id: z
+                .string()
+                .optional()
+                .describe("Single session ID to get pages for"),
+            session_ids: z
+                .array(z.string())
+                .max(20)
+                .optional()
+                .describe("Array of session IDs to get pages for (max 20)"),
+        }),
+    }, async ({ session_id, session_ids, }) => {
+        if (!isApiConfigured()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "API not configured" }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        if (!session_id && (!session_ids || session_ids.length === 0)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Either session_id or session_ids must be provided",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        if (session_id && !session_ids) {
+            const { data, error } = await apiGet(`/sessions/${session_id}/pages`);
+            if (error) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error }) }],
+                    isError: true,
+                };
+            }
+            return { content: [{ type: "text", text: JSON.stringify(data) }] };
+        }
+        const ids = session_ids ?? [session_id];
+        const { data, error } = await apiPost("/sessions/pages", {
+            session_ids: ids,
+        });
+        if (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error }) }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recapt/mcp",
-  "version": "0.0.12-beta",
+  "version": "0.0.14-beta",
   "description": "MCP exposing recapt behavioral intelligence to AI coding agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,11 +21,13 @@
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "templates"
   ],
   "author": "Recapt",
   "license": "ISC",
   "dependencies": {
+    "@inquirer/prompts": "^8.3.2",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "commander": "^14.0.3",
     "zod": "^3.24.0"

package/skills/self-healing.md

@@ -1,13 +1,21 @@
 # Recapt Self-Healing Workflow
 
-Use this workflow when asked to "fix issues", "heal the site", or improve UX based on behavioral data from recapt.
+Use this workflow when asked to "heal the site" or improve UX based on behavioral data from recapt.
 
 ## When to Use
 
-- User asks to fix UX issues or friction points
-- User wants to improve conversion or reduce drop-offs
-- User asks to "heal" or "diagnose" their site
-- After identifying issues with `run_full_diagnostic`
+This is a **comprehensive site improvement workflow**. Only use it when the user explicitly requests a full-site analysis:
+
+- "Heal my site"
+- "Run the self-healing workflow"
+- "Analyze my whole site and improve it"
+- "Do a full UX audit"
+- "Make general improvements across the site"
+  **Do NOT use this workflow for:**
+- Specific page fixes ("fix the checkout button")
+- Single flow optimization ("improve the signup funnel")
+- Investigating a specific issue ("why are users rage clicking here?")
+  For specific requests, use the appropriate tools directly — let the conversation guide which tools to call.
 
 ## Workflow
 
@@ -35,40 +43,119 @@ If fixes have sufficient data:
 
 Start with `run_full_diagnostic` (always available) to get a prioritized list of issues across the site.
 
-### 2. Investigate
+### 2. Analyze Flows
+
+After diagnosing issues, proactively look for flow optimization opportunities — even when nothing is "broken."
+
+#### 2a. Discover Journey Patterns
+
+- Search: "journey patterns" → `get_journey_patterns`
+- Look for:
+  - **Backtrack hotspots** — pages users return to repeatedly (signals confusion or missing information)
+  - **Dropoff pages** — where sessions end unexpectedly (potential conversion leaks)
+  - **Unexpected paths** — users taking roundabout routes to reach goals
+
+#### 2b. Analyze Key Funnels
+
+- Search: "analyze funnel" → `analyze_funnel`
+- Analyze critical conversion paths:
+  - Landing → Signup/Trial
+  - Pricing → Checkout → Success
+  - Onboarding flows
+- For each funnel step, note:
+  - Dropoff rate (>30% is a red flag)
+  - Frustration/confusion scores
+  - Dwell time anomalies
+
+#### 2c. Analyze Specific Flows
+
+- Search: "analyze flow" → `analyze_flow`, `get_flow_friction`
+- For pages with high dropoff or backtracking, analyze the flow in detail:
+  - What's the success rate for users entering this flow?
+  - Where are the bottlenecks?
+  - What's the friction score at each step?
+
+#### 2d. Understand User Segments
+
+- Search: "personas" → `discover_personas`
+- Identify behavioral personas:
+  - Which personas struggle most?
+  - What are their risk factors?
+  - What interventions are recommended?
 
-For each high-priority issue, search for investigation tools:
+#### 2e. Compare Success vs Failure
+
+- Search: "compare cohorts" → `compare_cohorts`
+- For flows with low conversion, compare:
+  - Users who completed vs dropped off
+  - Users on mobile vs desktop
+  - New vs returning users
+- Look for patterns: What do successful users do differently?
+
+#### Presenting Flow Opportunities
+
+Present opportunities alongside issues, clearly labeled:
+
+> **Issues Found:**
+>
+> 1. [CRITICAL] Rage clicks on checkout button — JS error
+> 2. [HIGH] Dead clicks on pricing toggle
+>
+> **Flow Optimization Opportunities:**
+>
+> 1. [OPPORTUNITY] 40% backtrack from /pricing to /features — consider adding feature comparison on pricing page
+> 2. [OPPORTUNITY] 65% dropoff at step 2 of onboarding — simplify or add progress indicator
+> 3. [OPPORTUNITY] Mobile users 3x more likely to abandon checkout — review mobile UX
+
+### 3. Investigate
+
+For each high-priority issue or opportunity, search for investigation tools:
 
 - Search: "investigate issue" → `investigate_issue`, `validate_issue`
 - This provides detailed context: affected sessions, element interactions, timing patterns
 
-### 3. Triage
+For flow opportunities, also consider:
+
+- Watching session replays of users who dropped off vs completed
+- Checking element friction on high-dropoff pages
+
+### 4. Triage
 
 Present findings to the user. Not all detected issues need fixing:
 
 - Search: "dismiss issue" → `dismiss_issue`, `mark_intended_behavior`
 - Some behaviors are intentional (e.g., rage clicks on a "copy" button)
-- Ask the user which issues to address before proceeding
+- Some flow patterns may be acceptable (e.g., users comparing options before deciding)
+- Ask the user which issues and opportunities to address before proceeding
 
-### 4. Fix
+### 5. Fix
 
-Implement code changes to address the issues. After making changes:
+Implement code changes to address issues and opportunities. After making changes:
 
 - Search: "propose fix" → `propose_fix`, `get_similar_fixes`, `get_fix_history`
 - Log the remediation so recapt can track its effectiveness
 
-### 5. Track
+For flow optimizations, common fixes include:
+
+- Adding missing information to reduce backtracking
+- Simplifying forms to reduce abandonment
+- Adding progress indicators to multi-step flows
+- Improving CTAs and visual hierarchy
+- Adding social proof or trust signals at decision points
+
+### 6. Track
 
 Mark fixes as deployed so recapt can measure impact:
 
 - Search: "deployment" → `confirm_deployment`, `evaluate_fix`, `list_pending_fixes`
 
-### 6. Learn
+### 7. Learn
 
 Build site knowledge for future reference:
 
 - Search: "site knowledge" → `get_site_knowledge`, `add_site_knowledge`
 - Document patterns, intended behaviors, and architectural decisions
+- Record successful flow optimizations for future reference
 
 ## Post-Fix Behavior
 
@@ -88,6 +175,11 @@ If the user agrees:
 | ------------- | ------------------- | ---------------------------------------------------------- |
 | Check Pending | "pending fixes"     | `list_pending_fixes`, `evaluate_fix`                       |
 | Diagnose      | (always available)  | `run_full_diagnostic`                                      |
+| Journey       | "journey patterns"  | `get_journey_patterns`                                     |
+| Funnels       | "analyze funnel"    | `analyze_funnel`                                           |
+| Flows         | "analyze flow"      | `analyze_flow`, `get_flow_friction`                        |
+| Personas      | "personas"          | `discover_personas`                                        |
+| Compare       | "compare cohorts"   | `compare_cohorts`                                          |
 | Investigate   | "investigate issue" | `investigate_issue`, `validate_issue`                      |
 | Triage        | "dismiss issue"     | `dismiss_issue`, `mark_intended_behavior`                  |
 | Fix           | "propose fix"       | `propose_fix`, `get_similar_fixes`, `get_fix_history`      |

package/templates/self-healing.md

@@ -0,0 +1,76 @@
+---
+on:
+  schedule: daily
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: "Branch to analyze"
+        default: "main"
+
+engine: { { ENGINE } }
+
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+
+mcp-servers:
+  recapt:
+    command: npx
+    args: ["@recapt/mcp@latest"]
+    env:
+      RECAPT_SECRET_KEY: "${{ secrets.RECAPT_SECRET_KEY }}"
+    allowed: ["*"]
+
+safe-outputs:
+  create-pull-request:
+    title-prefix: "[self-healing] "
+    labels: [automated, ux-fix]
+    base-branch: main
+    draft: true
+---
+
+## Self-Healing UX Fixes
+
+You are a UX engineer using recapt behavioral intelligence to automatically detect and fix user friction points.
+
+### Important: Autonomous Mode
+
+You are running in a GitHub Actions sandbox with NO human interaction possible. You must:
+
+- **Never wait for user input** - Make all decisions autonomously
+- **Never ask questions** - Proceed with reasonable defaults
+- **Complete all work in one run** - There is no "check back later"
+- **Always track fixes** - Call `confirm_deployment` for every fix without asking
+- **Triage autonomously** - Fix high-confidence issues, skip ambiguous ones (document skipped issues in the PR)
+- **If data is insufficient** - Note it in the PR and proceed with available information
+
+{{DOMAIN_CONFIG}}
+
+### Context
+
+Get recent changes to understand what might have introduced issues:
+
+```bash
+git log --since="24 hours ago" --oneline
+```
+
+### Workflow
+
+Follow the self-healing workflow defined in `.agents/recapt/self-healing.md`. The recapt MCP server is connected and provides all necessary tools.
+
+The workflow covers:
+
+1. Checking and evaluating any pending fixes from previous runs
+2. Running diagnostics to find current UX issues
+3. Investigating and triaging high-priority issues
+4. Implementing code fixes for actionable issues
+5. Tracking fixes for future evaluation
+
+### Output
+
+Create a pull request containing:
+
+- Evaluation results for any previously deployed fixes (improved/regressed/no change)
+- New issues discovered and fixes implemented
+- Clear commit messages explaining each change