@rely-ai/caliber 1.39.0 → 1.40.1

package/README.md

@@ -51,7 +51,7 @@ Requires **Node.js >= 20**.
 npx @rely-ai/caliber bootstrap
 ```
 
-Then, in your next Claude Code or Cursor chat session, type:
+Then, in your terminal (not the IDE chat), start a Claude Code or Cursor CLI session and type:
 
 > **/setup-caliber**
 
@@ -61,6 +61,18 @@ Your agent detects your stack, generates tailored configs for every platform you
 
 > **Your code stays on your machine.** Bootstrap is 100% local — no LLM calls, no code sent anywhere. Generation uses your own AI subscription or API key. Caliber never sees your code.
 
+<details>
+<summary><strong>Windows Users</strong></summary>
+
+Caliber works on Windows with a few notes:
+
+- **Run from your terminal** (PowerShell, CMD, or Git Bash) — not from inside an IDE chat window. Open a terminal, `cd` into your project folder, then run `npx @rely-ai/caliber bootstrap`.
+- **Git Bash is recommended.** Caliber's pre-commit hooks and auto-sync scripts use shell syntax. Git for Windows includes Git Bash, which handles this automatically. If you only use PowerShell, hooks may be skipped silently.
+- **Cursor Agent CLI:** If prompted to install it, download from [cursor.com/downloads](https://www.cursor.com/downloads) instead of the `curl | bash` command shown on macOS/Linux. Then run `agent login` in your terminal to authenticate.
+- **One terminal at a time.** Avoid running Caliber from multiple terminals simultaneously — this can cause conflicting state and unexpected provider detection.
+
+</details>
+
 ## Audits first, writes second
 
 Caliber never overwrites your existing configs without asking. The workflow mirrors code review:

package/dist/bin.js

@@ -858,7 +858,7 @@ function openDiffsInEditor(editor, files) {
   for (const file of files) {
     try {
       const leftPath = file.originalPath ?? getEmptyFilePath(file.proposedPath);
-      if (IS_WINDOWS3) {
+      if (IS_WINDOWS4) {
         const quote = (s) => `"${s}"`;
         spawn3([cmd, "--diff", quote(leftPath), quote(file.proposedPath)].join(" "), { shell: true, stdio: "ignore", detached: true }).unref();
       } else {
@@ -869,11 +869,11 @@ function openDiffsInEditor(editor, files) {
     }
   }
 }
-var IS_WINDOWS3, DIFF_TEMP_DIR;
+var IS_WINDOWS4, DIFF_TEMP_DIR;
 var init_editor = __esm({
   "src/utils/editor.ts"() {
     "use strict";
-    IS_WINDOWS3 = process.platform === "win32";
+    IS_WINDOWS4 = process.platform === "win32";
     DIFF_TEMP_DIR = path25.join(os6.tmpdir(), "caliber-diff");
   }
 });
@@ -3078,6 +3078,10 @@ async function llmCall(options) {
         await new Promise((r) => setTimeout(r, 1e3 * Math.pow(2, attempt - 1)));
         continue;
       }
+      if (isRateLimitError(error.message) && attempt < MAX_RETRIES) {
+        await new Promise((r) => setTimeout(r, 2e3 * Math.pow(2, attempt - 1)));
+        continue;
+      }
       if (isTransientError(error) && attempt < MAX_RETRIES) {
         await new Promise((r) => setTimeout(r, 1e3 * Math.pow(2, attempt - 1)));
         continue;
@@ -6274,6 +6278,7 @@ init_config();
 import chalk3 from "chalk";
 import select2 from "@inquirer/select";
 import confirm from "@inquirer/confirm";
+var IS_WINDOWS3 = process.platform === "win32";
 var PROVIDER_CHOICES = [
   { name: "Claude Code \u2014 use your existing subscription (no API key)", value: "claude-cli" },
   { name: "Cursor \u2014 use your existing subscription (no API key)", value: "cursor" },
@@ -6305,8 +6310,13 @@ async function runInteractiveProviderSetup(options) {
     case "cursor": {
       if (!isCursorAgentAvailable()) {
         console.log(chalk3.yellow("\n  Cursor Agent CLI not found."));
-        console.log(chalk3.dim("  Install it: ") + chalk3.hex("#83D1EB")("curl https://cursor.com/install -fsS | bash"));
-        console.log(chalk3.dim("  Then run ") + chalk3.hex("#83D1EB")("agent login") + chalk3.dim(" to authenticate.\n"));
+        if (IS_WINDOWS3) {
+          console.log(chalk3.dim("  Install it from: ") + chalk3.hex("#83D1EB")("https://www.cursor.com/downloads"));
+          console.log(chalk3.dim("  Then run ") + chalk3.hex("#83D1EB")("agent login") + chalk3.dim(" in PowerShell to authenticate.\n"));
+        } else {
+          console.log(chalk3.dim("  Install it: ") + chalk3.hex("#83D1EB")("curl https://cursor.com/install -fsS | bash"));
+          console.log(chalk3.dim("  Then run ") + chalk3.hex("#83D1EB")("agent login") + chalk3.dim(" to authenticate.\n"));
+        }
         const proceed = await confirm({ message: "Continue anyway?" });
         if (!proceed) throw new Error("__exit__");
       } else if (!isCursorLoggedIn()) {
@@ -6611,7 +6621,7 @@ function checkExistence(dir) {
     earnedPoints: Math.min(skillPoints, maxSkillPoints),
     passed: skillCount >= 1,
     detail: skillCount === 0 ? "No skills found" : `${skillCount} skill${skillCount === 1 ? "" : "s"} found`,
-    suggestion: skillCount === 0 ? "Add .claude/skills/ with project-specific workflows" : skillCount < 3 ? "Optimal is 2-3 focused skills" : void 0,
+    suggestion: skillCount === 0 ? "Skills are reusable agent workflows (e.g., deploy, test, review). Add 2-3 for your most common tasks" : skillCount < 3 ? "Optimal is 2-3 focused skills" : void 0,
     fix: skillCount === 0 ? {
       action: "create_skills",
       data: { currentCount: 0 },
@@ -6628,7 +6638,7 @@ function checkExistence(dir) {
     earnedPoints: mdcCount >= 1 ? POINTS_CURSOR_MDC_RULES : 0,
     passed: mdcCount >= 1,
     detail: mdcCount === 0 ? "No .mdc rule files" : `${mdcCount} .mdc rule${mdcCount === 1 ? "" : "s"} found`,
-    suggestion: mdcCount === 0 ? "Add .cursor/rules/*.mdc with frontmatter for Cursor" : void 0,
+    suggestion: mdcCount === 0 ? "Cursor .mdc rules use frontmatter to scope rules to specific files/paths. Add them for more targeted Cursor behavior" : void 0,
     fix: mdcCount === 0 ? {
       action: "create_mdc_rules",
       data: {},
@@ -6644,7 +6654,7 @@ function checkExistence(dir) {
     earnedPoints: mcp.count >= 1 ? POINTS_MCP_SERVERS : 0,
     passed: mcp.count >= 1,
     detail: mcp.count > 0 ? `${mcp.count} server${mcp.count === 1 ? "" : "s"} in ${mcp.sources.join(", ")}` : "No MCP servers configured",
-    suggestion: mcp.count === 0 ? "Configure MCP servers in .mcp.json for external service access" : void 0,
+    suggestion: mcp.count === 0 ? "MCP servers connect your agent to external tools (databases, Slack, Linear, etc). Add if your team uses external services" : void 0,
     fix: mcp.count === 0 ? {
       action: "configure_mcp",
       data: {},
@@ -6713,7 +6723,7 @@ function checkQuality(dir) {
     earnedPoints: tokenPoints,
     passed: tokenPoints >= 4,
     detail: totalContent.length === 0 ? "No config files to measure" : `~${totalTokens} tokens total across all config files`,
-    suggestion: tokenPoints < 4 && totalContent.length > 0 ? `Total config is ~${totalTokens} tokens \u2014 reduce to under 5000 for better agent performance` : void 0,
+    suggestion: tokenPoints < 4 && totalContent.length > 0 ? `Config is ~${totalTokens} tokens. Agents work best under ~5000 tokens (~4 pages of text) \u2014 trim verbose sections` : void 0,
     fix: tokenPoints < 4 && totalContent.length > 0 ? {
       action: "reduce_size",
       data: { currentTokens: totalTokens, targetTokens: 5e3 },
@@ -7157,7 +7167,7 @@ function checkFreshness(dir) {
     earnedPoints: hasPermissions ? POINTS_PERMISSIONS : 0,
     passed: hasPermissions,
     detail: permissionDetail,
-    suggestion: hasPermissions ? void 0 : "Add permissions.allow to .claude/settings.json for safer agent execution",
+    suggestion: hasPermissions ? void 0 : "Permissions control which shell commands the agent can run without asking. Adds a safety layer for your team",
     fix: hasPermissions ? void 0 : {
       action: "add_permissions",
       data: {},
@@ -7222,7 +7232,7 @@ function checkBonus(dir) {
     earnedPoints: hasHooks ? POINTS_HOOKS : 0,
     passed: hasHooks,
     detail: hasHooks ? hookSources.join(", ") : "No hooks configured",
-    suggestion: hasHooks ? void 0 : `Run \`${resolveCaliber()} init\` to add pre-commit instructions`,
+    suggestion: hasHooks ? void 0 : `Hooks auto-sync your agent config on every commit so it stays fresh. Run \`${resolveCaliber()} init\` to set up`,
     fix: hasHooks ? void 0 : {
       action: "install_hooks",
       data: {},
@@ -7238,7 +7248,7 @@ function checkBonus(dir) {
     earnedPoints: agentsMdExists ? POINTS_AGENTS_MD : 0,
     passed: agentsMdExists,
     detail: agentsMdExists ? "Found at project root" : "Not found",
-    suggestion: agentsMdExists ? void 0 : "Add AGENTS.md \u2014 the emerging cross-agent standard",
+    suggestion: agentsMdExists ? void 0 : "AGENTS.md provides project context to Codex, Copilot, and other agents. Works alongside CLAUDE.md",
     fix: agentsMdExists ? void 0 : {
       action: "create_file",
       data: { file: "AGENTS.md" },
@@ -7274,7 +7284,7 @@ function checkBonus(dir) {
     earnedPoints: allOpenSkills ? POINTS_OPEN_SKILLS_FORMAT : 0,
     passed: allOpenSkills || totalSkillFiles === 0,
     detail: totalSkillFiles === 0 ? "No skills to check" : allOpenSkills ? `All ${totalSkillFiles} skill${totalSkillFiles === 1 ? "" : "s"} use SKILL.md with frontmatter` : `${openSkillsCount}/${totalSkillFiles} use OpenSkills format`,
-    suggestion: totalSkillFiles > 0 && !allOpenSkills ? "Migrate skills to .claude/skills/{name}/SKILL.md with YAML frontmatter" : void 0,
+    suggestion: totalSkillFiles > 0 && !allOpenSkills ? "OpenSkills format (SKILL.md with YAML header) makes skills portable across agents. Migrate for cross-tool compatibility" : void 0,
     fix: totalSkillFiles > 0 && !allOpenSkills ? {
       action: "migrate_skills",
       data: { openSkills: openSkillsCount, total: totalSkillFiles },
@@ -7291,7 +7301,7 @@ function checkBonus(dir) {
     earnedPoints: hasLearned ? POINTS_LEARNED_CONTENT : 0,
     passed: hasLearned,
     detail: hasLearned ? "Session learnings found in CALIBER_LEARNINGS.md" : "No learned content",
-    suggestion: hasLearned ? void 0 : `Install learning hooks: \`${resolveCaliber()} learn install\``
+    suggestion: hasLearned ? void 0 : `Session learnings capture patterns from your coding sessions so the agent improves over time. Run \`${resolveCaliber()} learn install\``
   });
   return checks;
 }
@@ -7532,7 +7542,7 @@ function displayScore(result) {
   formatTopImprovements(result.checks);
 }
 function formatTopImprovements(checks) {
-  const improvable = checks.filter((c) => c.earnedPoints < c.maxPoints).map((c) => ({ name: c.name, potential: c.maxPoints - c.earnedPoints })).sort((a, b) => b.potential - a.potential).slice(0, 5);
+  const improvable = checks.filter((c) => c.earnedPoints < c.maxPoints).map((c) => ({ name: c.name, potential: c.maxPoints - c.earnedPoints, suggestion: c.suggestion })).sort((a, b) => b.potential - a.potential).slice(0, 5);
   if (improvable.length === 0) return;
   console.log(chalk4.gray("  \u2500 TOP IMPROVEMENTS \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
   console.log("");
@@ -7542,6 +7552,9 @@ function formatTopImprovements(checks) {
     const label = chalk4.white(item.name.padEnd(42));
     const pts = chalk4.yellow(`+${item.potential} pts`);
     console.log(`  ${num} ${label}${pts}`);
+    if (item.suggestion) {
+      console.log(chalk4.gray(`     ${item.suggestion}`));
+    }
   }
   console.log("");
 }
@@ -10097,6 +10110,7 @@ function getScoreTrend(entries) {
 }
 
 // src/commands/init.ts
+var IS_WINDOWS5 = process.platform === "win32";
 function log(verbose, ...args) {
   if (verbose) console.log(chalk14.dim(`  [verbose] ${args.map(String).join(" ")}`));
 }
@@ -10232,6 +10246,10 @@ async function initCommand(options) {
   console.log(`  ${chalk14.green("\u2713")} Onboarding hook \u2014 nudges new team members to set up`);
   installSessionStartHook();
   console.log(`  ${chalk14.green("\u2713")} Freshness hook \u2014 warns when configs are stale`);
+  if (IS_WINDOWS5) {
+    console.log(chalk14.yellow("\n  Note: hooks use shell syntax and require Git Bash (included with Git for Windows)."));
+    console.log(chalk14.dim("  If hooks don't run, ensure Git for Windows is installed and git is using its bundled sh."));
+  }
   const { ensureBuiltinSkills: ensureBuiltinSkills2 } = await Promise.resolve().then(() => (init_builtin_skills(), builtin_skills_exports));
   for (const agent of targetAgent) {
     if (agent === "claude" && !fs34.existsSync(".claude"))
@@ -11209,12 +11227,12 @@ async function scoreCommand(options) {
       chalk18.gray("  Biggest gain: ") + chalk18.yellow(`+${pts} pts`) + chalk18.gray(` from "${topFix.name}"`) + (topFix.suggestion ? chalk18.gray(` \u2014 ${topFix.suggestion}`) : "")
     );
     console.log(
-      chalk18.gray("  Run ") + chalk18.hex("#83D1EB")(`${bin} init`) + chalk18.gray(" to auto-fix these.")
+      chalk18.gray("  Run ") + chalk18.hex("#83D1EB")(`${bin} init`) + chalk18.gray(" to generate or update your agent config files.")
     );
   } else if (failing.length > 0) {
     console.log(
       chalk18.green("  Looking good!") + chalk18.gray(
-        ` ${failing.length} check${failing.length === 1 ? "" : "s"} can still be improved.`
+        ` ${failing.length} optional improvement${failing.length === 1 ? "" : "s"} available.`
       )
     );
     console.log(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rely-ai/caliber",
-  "version": "1.39.0",
+  "version": "1.40.1",
   "description": "AI context infrastructure for coding agents — keeps CLAUDE.md, Cursor rules, and skills in sync as your codebase evolves",
   "type": "module",
   "bin": {