@launchchair/agent 0.4.2 → 0.4.5

package/AGENTS.md

@@ -87,6 +87,7 @@ LAUNCHCHAIR_PROJECT_ID="optional project UUID; omit or leave blank if creating o
 ```
 
 `launchchair login` is the recommended token path. It saves the token to `~/.launchchair/config.json`, and `launchchair mcp-server` reads that saved token. Use `LAUNCHCHAIR_AGENT_TOKEN` only as a manual fallback when browser login is skipped or a per-client token override is needed.
+The packaged MCP and local bridges also read the same saved CLI config as a fallback, so a desktop MCP launch should not require pasting a token into Codex or Claude config after browser login.
 
 For Codex Desktop local runs:
 
@@ -112,7 +113,7 @@ The build folder can be an empty scratch folder until Stack Setup creates or rec
 [mcp_servers.launchchair]
 command = "launchchair"
 args = ["mcp-server"]
-required = true
+required = false
 startup_timeout_sec = 20
 tool_timeout_sec = 3600
 default_tools_approval_mode = "approve"
@@ -139,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
 
@@ -151,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:
@@ -177,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"

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.2";
+const VERSION = "0.4.4";
 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) {
@@ -1002,6 +1084,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.",
@@ -1165,6 +1249,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

@@ -10,14 +10,20 @@
  */
 
 import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { buildRunnerCommand, parseRunnerCommand } from "./runner-command.mjs";
 
-const VERSION = "0.4.0";
+const VERSION = "0.4.4";
 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()
+  ? path.resolve(process.env.LAUNCHCHAIR_CONFIG_DIR.trim())
+  : path.join(os.homedir() || process.cwd(), ".launchchair");
+const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 
 function nodeScriptCommand(scriptName) {
   return `${JSON.stringify(process.execPath)} ${JSON.stringify(path.join(AGENT_SCRIPT_DIR, scriptName))}`;
@@ -33,6 +39,23 @@ function env(name, fallback = "") {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
 }
 
+function loadSavedConfig() {
+  try {
+    if (!existsSync(CONFIG_PATH)) return {};
+    const parsed = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+const savedConfig = loadSavedConfig();
+
+function savedConfigValue(key, fallback = "") {
+  const value = savedConfig[key];
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
+
 function hasArg(name) {
   return process.argv.includes(name);
 }
@@ -92,8 +115,9 @@ function printHelp() {
   console.log(`
 LaunchChair local bridge v${VERSION}
 
-Required env:
-  LAUNCHCHAIR_AGENT_TOKEN
+Token:
+  Recommended: run launchchair login once to save ~/.launchchair/config.json
+  Optional env fallback: LAUNCHCHAIR_AGENT_TOKEN or LAUNCHCHAIR_API_KEY
 
 Optional env:
   LAUNCHCHAIR_BASE_URL           Default: http://localhost:3000
@@ -153,9 +177,9 @@ Runner placeholders:
 }
 
 const config = {
-  baseUrl: env("LAUNCHCHAIR_BASE_URL", "http://localhost:3000").replace(/\/+$/, ""),
-  token: env("LAUNCHCHAIR_AGENT_TOKEN", env("LAUNCHCHAIR_API_KEY")),
-  projectId: env("LAUNCHCHAIR_PROJECT_ID") || null,
+  baseUrl: env("LAUNCHCHAIR_BASE_URL", savedConfigValue("baseUrl", "http://localhost:3000")).replace(/\/+$/, ""),
+  token: env("LAUNCHCHAIR_AGENT_TOKEN", env("LAUNCHCHAIR_API_KEY", savedConfigValue("agentToken"))),
+  projectId: env("LAUNCHCHAIR_PROJECT_ID", savedConfigValue("projectId")) || null,
   clientName: env("LC_AGENT_CLIENT_NAME", "Local Bridge"),
   clientType: env("LC_AGENT_CLIENT_TYPE", "auto"),
   clientVersion: env("LC_AGENT_CLIENT_VERSION", VERSION),
@@ -187,7 +211,9 @@ if (hasArg("--help")) {
 
 if (!config.token) {
   // eslint-disable-next-line no-console
-  console.error("Missing LAUNCHCHAIR_AGENT_TOKEN. LAUNCHCHAIR_API_KEY is also supported as an alias.");
+  console.error(
+    `Missing LaunchChair Agent API token. Run "launchchair login" or set LAUNCHCHAIR_AGENT_TOKEN. Checked ${CONFIG_PATH}.`,
+  );
   printHelp();
   process.exit(1);
 }

package/mcp-bridge-server.mjs

@@ -12,16 +12,22 @@
  */
 
 import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { buildRunnerCommand, parseRunnerCommand } from "./runner-command.mjs";
 
-const VERSION = "0.4.0";
+const VERSION = "0.4.4";
 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()
+  ? path.resolve(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))}`;
@@ -32,6 +38,23 @@ function env(name, fallback = "") {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
 }
 
+function loadSavedConfig() {
+  try {
+    if (!existsSync(CONFIG_PATH)) return {};
+    const parsed = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (_error) {
+    return {};
+  }
+}
+
+const savedConfig = loadSavedConfig();
+
+function savedConfigValue(key, fallback = "") {
+  const value = savedConfig[key];
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
+
 function toInt(value, fallback) {
   const parsed = Number.parseInt(String(value ?? ""), 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
@@ -84,9 +107,9 @@ function builtInRunnerCommand(target) {
 }
 
 const config = {
-  baseUrl: env("LAUNCHCHAIR_BASE_URL", "http://localhost:3000").replace(/\/+$/, ""),
-  token: env("LAUNCHCHAIR_AGENT_TOKEN", env("LAUNCHCHAIR_API_KEY")),
-  projectId: env("LAUNCHCHAIR_PROJECT_ID") || null,
+  baseUrl: env("LAUNCHCHAIR_BASE_URL", savedConfigValue("baseUrl", "http://localhost:3000")).replace(/\/+$/, ""),
+  token: env("LAUNCHCHAIR_AGENT_TOKEN", env("LAUNCHCHAIR_API_KEY", savedConfigValue("agentToken"))),
+  projectId: env("LAUNCHCHAIR_PROJECT_ID", savedConfigValue("projectId")) || null,
   clientName: env("LC_AGENT_CLIENT_NAME", "MCP Bridge"),
   clientType: env("LC_AGENT_CLIENT_TYPE", "other"),
   clientVersion: env("LC_AGENT_CLIENT_VERSION", VERSION),
@@ -106,14 +129,16 @@ const config = {
     claudeCode: env("LC_AGENT_RUNNER_CMD_CLAUDE_CODE", builtInRunnerCommand("claude_code")),
   },
   localRepoPaths: {
-    codex: env("LC_AGENT_CODEX_CWD", process.cwd()),
-    claudeCode: env("LC_AGENT_CLAUDE_CODE_CWD", process.cwd()),
+    codex: env("LC_AGENT_CODEX_CWD", savedConfigValue("codexCwd", process.cwd())),
+    claudeCode: env("LC_AGENT_CLAUDE_CODE_CWD", savedConfigValue("claudeCodeCwd", process.cwd())),
   },
 };
 
 if (!config.token) {
   // eslint-disable-next-line no-console
-  console.error("Missing LAUNCHCHAIR_AGENT_TOKEN for MCP bridge. LAUNCHCHAIR_API_KEY is also supported as an alias.");
+  console.error(
+    `Missing LaunchChair Agent API token. Run "launchchair login" or set LAUNCHCHAIR_AGENT_TOKEN. Checked ${CONFIG_PATH}.`,
+  );
   process.exit(1);
 }
 
@@ -388,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()
@@ -724,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.",
@@ -893,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 {
@@ -1012,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.2",
+  "version": "0.4.5",
   "description": "LaunchChair Agent CLI, MCP bridge, local bridge, and runners for Codex, Claude Code, ChatGPT, Claude, and Hermes workflows.",
   "type": "module",
   "bin": {