@launchchair/agent 0.4.3 → 0.4.6

package/AGENTS.md

@@ -111,8 +111,8 @@ The build folder can be an empty scratch folder until Stack Setup creates or rec
 
 ```toml
 [mcp_servers.launchchair]
-command = "launchchair"
-args = ["mcp-server"]
+command = "/absolute/path/to/node"
+args = ["/absolute/path/to/launchchair-cli.mjs", "mcp-server"]
 required = false
 startup_timeout_sec = 20
 tool_timeout_sec = 3600
@@ -129,7 +129,7 @@ LC_AGENT_CODEX_CWD = "/absolute/path/to/the-folder-codex-should-build-into"
 # LAUNCHCHAIR_AGENT_TOKEN = "<full lc_at token from Settings API Access>"
 ```
 
-If the desktop app cannot find `launchchair`, run `which launchchair` in Terminal and use that absolute path as the MCP command.
+Prefer `launchchair setup codex --cwd /absolute/path/to/build-folder --write-config` or `launchchair mcp-config codex --ui-fields` so the CLI prints exact local command and argument paths for this machine.
 
 ## What To Do First In A Fresh Chat
 
@@ -140,6 +140,7 @@ If the desktop app cannot find `launchchair`, run `which launchchair` in Termina
 5. If the user clicked Run with agent in LaunchChair, call `launchchair_run_once`.
 6. If the user asks to advance the product workflow, call `launchchair_continue_project`.
 7. If LaunchChair asks for a user-choice bucket such as wedge, pricing, or feature direction, call `launchchair_select_choice`. Do not use generic SPEC_UPDATE apply for user-choice buckets.
+8. When the user asks for validation scores or wants to compare ideas, call `launchchair_get_scorecards`. Report validation scorecards separately from generated direction-option scores.
 
 ## Consent Behavior
 
@@ -152,6 +153,8 @@ Safe LaunchChair MCP/API actions that should not need another user confirmation:
 - continuing a project loop with `launchchair_continue_project`
 - selecting a generated wedge, pricing, or feature direction with `launchchair_select_choice`
 - running/rerunning Product Ideation, Market Validation, Positioning, Pricing, and MVP Blueprint buckets
+- running/rerunning Feature Definition and User & Feature Validation for score-based feature comparison
+- reading Product or Feature validation scorecards with `launchchair_get_scorecards`
 - returning phase synthesis links and selected choices
 
 Stop and ask only when:
@@ -178,9 +181,12 @@ Do not start with `ls`, `rg`, dependency inspection, or nearby repo searches whe
 - LaunchChair project creation
 - LaunchChair phase loops
 - score-based reruns such as ICP Pain Score, Market Saturation Score, or Wedge Opportunity Score
+- Feature score-based validation using Feature Pain Score, Pattern Saturation Score, and Feature Opportunity Score
 
 Those are LaunchChair project-state tasks, not local repo tasks.
 
+For Feature projects, the three Feature validation scorecards evaluate the idea. The two generated wedge-direction scores rank the narrow opportunities inside that idea; they are not the Feature validation scores. User & Feature Validation selects the wedge first, then Feature Blueprint generates and selects exactly two concrete feature directions. Every wedge and Feature direction must be grounded in four evidence pillars: ICP complaint themes, delight themes, substitute behaviors, and competitor gaps. Never collapse those decisions or answer a request for Feature validation scores with direction-option scores alone. When comparing multiple Feature ideas, run each through User & Feature Validation, call `launchchair_get_scorecards` for each project, maximize Feature Pain and Feature Opportunity, minimize Pattern Saturation, and prefer ideas that pass every returned recommended threshold.
+
 ## When Repo Inspection Is Correct
 
 Inspect the repo when the current LaunchChair work is:

package/README.md

@@ -94,6 +94,8 @@ launchchair setup claude --cwd /absolute/path/to/repo-or-empty-folder --write-co
 launchchair setup terminal --cwd /absolute/path/to/repo-or-empty-folder
 launchchair projects
 launchchair projects --query LeafLore
+launchchair scorecards --project-id <project-id>
+launchchair scorecards --project-name LeafLore
 launchchair create --name "SignalLift" --one-liner "Distribution workspace for technical founders" --project-type b2b --save-project
 launchchair continue --stop-phase-key market_validation
 launchchair continue --completion-target "rerun Product Ideation until ICP Pain Score is above 85"
@@ -143,9 +145,9 @@ Print a Claude Desktop MCP config example:
 launchchair mcp-config claude
 ```
 
-The recommended config launches `launchchair mcp-server`. That process reads the token saved by `launchchair login`, so Codex and Claude users do not need to paste tokens into MCP config after browser login.
+The recommended config launches the MCP server through the exact Node executable and CLI file path generated by `launchchair setup` or `launchchair mcp-config`. That process reads the token saved by `launchchair login`, so Codex and Claude users do not need to paste tokens into MCP config after browser login.
 
-Use `LAUNCHCHAIR_AGENT_TOKEN` only as a manual fallback when you skip `launchchair login`, need a per-client token override, or your desktop app cannot read the saved CLI config. If a desktop app cannot find `launchchair`, run `which launchchair` and use that absolute path as the MCP command.
+Use `LAUNCHCHAIR_AGENT_TOKEN` only as a manual fallback when you skip `launchchair login`, need a per-client token override, or your desktop app cannot read the saved CLI config. If you use a desktop custom MCP form, run `launchchair mcp-config codex --ui-fields` or `launchchair mcp-config claude --ui-fields` and paste the printed command, each argument, env vars, and working directory exactly as shown.
 
 ## Local Bridge
 

package/launchchair-cli.mjs

@@ -15,7 +15,7 @@ import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 
-const VERSION = "0.4.3";
+const VERSION = "0.4.6";
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_BASE_URL = "https://www.launchchair.io";
 const CONFIG_DIR = process.env.LAUNCHCHAIR_CONFIG_DIR?.trim()
@@ -159,6 +159,8 @@ Commands:
   logout                          Remove the saved local token
   whoami                          Show the current API identity and token source
   projects [--query name]         List projects visible to the token
+  scorecards [--project-id ID|--project-name NAME]
+                                  Read Product or Feature validation scorecards
   create --name NAME [options]    Create a LaunchChair project
   continue [--project-id ID]       Ask LaunchChair to continue the project loop once
   run-once                        Claim and run one queued LaunchChair job through the local bridge
@@ -493,6 +495,86 @@ async function listProjects(args) {
   });
 }
 
+function normalizeProjectName(value) {
+  return String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, " ");
+}
+
+async function resolveProjectIdForCommand(args, commandName) {
+  const configuredProjectId = args["project-id"] || defaultProjectId();
+  if (configuredProjectId) return configuredProjectId;
+
+  const projectName = String(args["project-name"] ?? args.query ?? "").trim();
+  if (!projectName) {
+    throw new Error(
+      `${commandName} requires --project-id, --project-name, LAUNCHCHAIR_PROJECT_ID, or config set project-id.`,
+    );
+  }
+
+  const params = new URLSearchParams();
+  params.set("query", projectName);
+  params.set("limit", "10");
+  const body = await api(`/api/agent/v1/projects?${params.toString()}`);
+  const projects = Array.isArray(body?.projects) ? body.projects : [];
+  const normalizedName = normalizeProjectName(projectName);
+  const exactMatches = projects.filter((project) => normalizeProjectName(project?.name) === normalizedName);
+  const candidates = exactMatches.length > 0 ? exactMatches : projects;
+
+  if (candidates.length === 1 && candidates[0]?.id) {
+    return candidates[0].id;
+  }
+
+  if (candidates.length > 1) {
+    const labels = candidates
+      .map((project) => `${project?.name ?? "Untitled project"} (${project?.id ?? "no id"})`)
+      .join(", ");
+    throw new Error(`Could not resolve a unique project for "${projectName}". Matching projects: ${labels}.`);
+  }
+
+  throw new Error(`Could not find a project named "${projectName}" for this token.`);
+}
+
+async function showScorecards(args) {
+  const projectId = await resolveProjectIdForCommand(args, "scorecards");
+  const body = await api(`/api/agent/v1/projects/${encodeURIComponent(projectId)}/scorecards`);
+  title(`${body?.projectName ?? "Project"} validation scorecards`);
+  const scorecards = Array.isArray(body?.scorecards) ? body.scorecards : [];
+  if (!scorecards.length) {
+    warn("No validation scorecards returned.");
+  }
+  scorecards.forEach((scorecard) => {
+    const score = typeof scorecard?.score === "number" ? `${scorecard.score}/100` : "needs data";
+    const threshold = `${scorecard?.optimization === "minimize" ? "≤" : "≥"}${scorecard?.recommendedThreshold ?? "—"}`;
+    const tone = scorecard?.passesRecommendedThreshold === true ? "green" : scorecard?.score === null ? "yellow" : "red";
+    row(scorecard?.title ?? scorecard?.id ?? "Score", `${score} · target ${threshold}`, tone);
+    if (scorecard?.signalLabel) row("Signal", scorecard.signalLabel, "dim");
+    if (scorecard?.explanation) row("Why", scorecard.explanation, "dim");
+    if (scorecard?.score === null && scorecard?.insufficientDataMessage) {
+      row("Need", scorecard.insufficientDataMessage, "yellow");
+    }
+    if (scorecard?.score === null && Array.isArray(scorecard?.requiredPhases) && scorecard.requiredPhases.length > 0) {
+      row("Required phases", scorecard.requiredPhases.join(", "), "dim");
+    }
+  });
+  const thresholdMessage = body?.allScoresAvailable === false
+    ? "missing required phase data"
+    : body?.passesRecommendedThresholds
+      ? "all passed"
+      : "needs another validation pass";
+  row("Thresholds", thresholdMessage, body?.passesRecommendedThresholds ? "green" : "yellow");
+  if (body?.guidance?.distinction) row("Important", body.guidance.distinction, "dim");
+  const directions = Array.isArray(body?.directionOptions) ? body.directionOptions : [];
+  if (directions.length > 0) {
+    print("");
+    print(paint("Direction options (not validation scorecards)", "bold"));
+    directions.forEach((direction) => {
+      row(direction?.selected ? "Selected" : "Option", `${direction?.title ?? direction?.id}: ${direction?.score ?? 0}/100`, direction?.selected ? "cyan" : "dim");
+    });
+  }
+}
+
 async function createProject(args) {
   const name = typeof args.name === "string" ? args.name : "";
   if (!name) {
@@ -776,9 +858,10 @@ function mcpEnvForTarget(target, options = {}) {
 }
 
 function mcpServerConfig(target, options = {}) {
+  const cliPath = path.join(SCRIPT_DIR, "launchchair-cli.mjs");
   return {
-    command: "launchchair",
-    args: ["mcp-server"],
+    command: process.execPath,
+    args: [cliPath, "mcp-server"],
     env: mcpEnvForTarget(target, options),
   };
 }
@@ -800,9 +883,10 @@ function renderMcpConfig(target, options = {}) {
   const envLines = Object.entries(server.env)
     .map(([key, value]) => `${key} = ${tomlString(value)}`)
     .join("\n");
+  const argsLine = server.args.map(tomlString).join(", ");
   return `[mcp_servers.launchchair]
-command = "launchchair"
-args = ["mcp-server"]
+command = ${tomlString(server.command)}
+args = [${argsLine}]
 required = false
 startup_timeout_sec = 20
 tool_timeout_sec = 3600
@@ -831,7 +915,7 @@ Command to launch
   ${server.command}
 
 Arguments
-  ${server.args.join(" ")}
+${server.args.map((arg) => `  ${arg}`).join("\n")}
 
 Environment variables
 ${envLines}
@@ -1002,6 +1086,8 @@ function installLaunchChairSkill(args) {
             "For a feature in an existing product, use launchchair_create_feature_project. Never substitute a Product project if that tool is unavailable; report the setup or beta-access issue instead.",
             "Use planToBuildBoard=true for planning through the Feature build board.",
             "Use fullLoop=true only when the user asks to implement/build the feature; continue agent-run QA and stop for production SQL or a genuine external authorization boundary.",
+            "After Feature validation, call launchchair_get_scorecards. Feature Pain, Pattern Saturation, and Feature Opportunity are the validation scorecards; generated direction scores only rank directions inside the idea.",
+            "When comparing multiple Feature ideas, require evidence across ICP complaint themes, delight themes, substitute behaviors, and competitor gaps; then evaluate each with the scorecards, maximize Feature Pain and Feature Opportunity, minimize Pattern Saturation, and prefer ideas that pass every returned recommended threshold.",
           ]
         : []),
       "Do not ask for extra confirmation for ordinary LaunchChair MCP calls when the user already requested the workflow and the token permits it.",
@@ -1135,7 +1221,7 @@ async function setup(args) {
       print(`1. Paste the MCP config above into ${details.label}.`);
       print(`2. Restart or reload ${details.label} so the MCP server is exposed to fresh chats.`);
     }
-    print("3. If the desktop app cannot find launchchair, run `which launchchair` and use that absolute path as the command.");
+    print("3. Use the generated command and argument fields exactly as printed; setup resolves the local Node and CLI paths for this machine.");
     print("4. Keep this bridge running when you want LaunchChair's Run with agent button to work:");
     print(`   ${paint("launchchair bridge", "cyan")}`);
     print("5. Start a fresh agent chat. The agent should discover the LaunchChair skill and MCP server instructions automatically.");
@@ -1165,6 +1251,7 @@ async function main() {
   if (command === "logout") return logout();
   if (command === "whoami") return whoami();
   if (command === "projects") return listProjects(args);
+  if (command === "scorecards") return showScorecards(args);
   if (command === "create") return createProject(args);
   if (command === "continue") return continueProject(args);
   if (command === "run-once") return spawnBridge(["--once", "--verbose"]);

package/local-bridge.mjs

@@ -17,7 +17,7 @@ import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { buildRunnerCommand, parseRunnerCommand } from "./runner-command.mjs";
 
-const VERSION = "0.4.3";
+const VERSION = "0.4.6";
 const CLIENT_TYPES = ["codex", "chatgpt", "claude", "claude_code", "other"];
 const AGENT_SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const CONFIG_DIR = process.env.LAUNCHCHAIR_CONFIG_DIR?.trim()

package/mcp-bridge-server.mjs

@@ -19,7 +19,7 @@ import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { buildRunnerCommand, parseRunnerCommand } from "./runner-command.mjs";
 
-const VERSION = "0.4.3";
+const VERSION = "0.4.6";
 const SERVER_NAME = "launchchair-agent-mcp";
 const AGENT_SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const CONFIG_DIR = process.env.LAUNCHCHAIR_CONFIG_DIR?.trim()
@@ -27,7 +27,7 @@ const CONFIG_DIR = process.env.LAUNCHCHAIR_CONFIG_DIR?.trim()
   : path.join(os.homedir() || process.cwd(), ".launchchair");
 const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 const BASE_SERVER_INSTRUCTIONS =
-  "Use LaunchChair MCP tools—not web browsing—for LaunchChair project discovery, creation, planning, and loops. Call the most specific available tool. If a requested workflow is unavailable, explain the access or setup issue instead of silently substituting another project type or workflow.";
+  "Use LaunchChair MCP tools—not web browsing—for LaunchChair project discovery, creation, planning, validation scoring, and loops. Call the most specific available tool. When asked for validation scores, call launchchair_get_scorecards and report those scorecards; do not substitute generated direction-option scores. If a requested workflow is unavailable, explain the access or setup issue instead of silently substituting another project type or workflow.";
 
 function nodeScriptCommand(scriptName) {
   return `${JSON.stringify(process.execPath)} ${JSON.stringify(path.join(AGENT_SCRIPT_DIR, scriptName))}`;
@@ -413,6 +413,14 @@ async function listProjects(args = {}) {
   return api(`/api/agent/v1/projects${suffix ? `?${suffix}` : ""}`);
 }
 
+async function getScorecards(args = {}) {
+  const projectId = await resolveProjectId(args);
+  if (!projectId) {
+    throw new Error("projectId is required. Pass projectId, set LAUNCHCHAIR_PROJECT_ID, or pass projectName.");
+  }
+  return api(`/api/agent/v1/projects/${encodeURIComponent(projectId)}/scorecards`);
+}
+
 function normalizeProjectName(value) {
   return String(value ?? "")
     .trim()
@@ -749,6 +757,22 @@ const MCP_TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "launchchair_get_scorecards",
+    description:
+      "Read the Product or Feature validation scorecards for a project, including recommended thresholds and direction-option scores kept separate. Use this whenever the user asks about validation scores or wants to compare/rerun ideas until the scorecards are strong.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: { type: "string" },
+        projectName: {
+          type: "string",
+          description: "Optional project name to resolve through launchchair_list_projects when projectId is omitted.",
+        },
+      },
+      additionalProperties: false,
+    },
+  },
   {
     name: "launchchair_heartbeat",
     description: "Send heartbeat and update connected agent metadata.",
@@ -918,7 +942,7 @@ const MCP_TOOLS = [
   },
 ];
 
-const READ_ONLY_TOOLS = new Set(["launchchair_status", "launchchair_list_projects"]);
+const READ_ONLY_TOOLS = new Set(["launchchair_status", "launchchair_list_projects", "launchchair_get_scorecards"]);
 
 function annotateTool(tool) {
   return {
@@ -1037,6 +1061,11 @@ async function handleRpc(request) {
         writeResult(id, textResult(payload));
         return;
       }
+      if (toolName === "launchchair_get_scorecards") {
+        const payload = await getScorecards(args);
+        writeResult(id, textResult(payload));
+        return;
+      }
       if (toolName === "launchchair_heartbeat") {
         const payload = await heartbeat(args);
         writeResult(id, textResult(payload));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@launchchair/agent",
-  "version": "0.4.3",
+  "version": "0.4.6",
   "description": "LaunchChair Agent CLI, MCP bridge, local bridge, and runners for Codex, Claude Code, ChatGPT, Claude, and Hermes workflows.",
   "type": "module",
   "bin": {