@jgiox/goodvibes 1.2.0 → 1.6.1

package/dist/index.js

@@ -1,17 +1,19 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { createRequire as createRequire2 } from "module";
 import { Command } from "commander";
 
 // src/commands/init.ts
-import { intro, outro, note, tasks } from "@clack/prompts";
+import { readdirSync } from "fs";
+import { intro, outro, note, tasks, cancel } from "@clack/prompts";
 
 // src/steps/copy-templates.ts
 import { copy } from "fs-extra";
 import { readFile as readFile2, rename } from "fs/promises";
 import { readdir } from "fs/promises";
 import { existsSync } from "fs";
-import { join, relative } from "path";
+import { join, relative, sep } from "path";
 import { fileURLToPath } from "url";
 
 // src/utils/sentinel-merge.ts
@@ -104,26 +106,51 @@ async function copyTemplates(templateDir, destDir, dryRun, minimal, projectType
   const selectedVariant = `ci-${projectType}.yml`;
   if (dryRun) {
     const all = await listTemplateFiles(templateDir);
-    return all.filter((p) => !ciVariants.some((v) => p.endsWith(v) && v !== selectedVariant));
+    return { written: all.filter((p) => !ciVariants.some((v) => p.endsWith(v) && v !== selectedVariant)), skipped: [] };
   }
-  await copy(templateDir, destDir, {
-    overwrite: false,
-    errorOnExist: false,
-    filter: (src) => {
-      if (src.endsWith("CLAUDE.md")) return false;
-      if (minimal && src.includes(".github/workflows")) return false;
-      if (relative(templateDir, src).includes("..")) return false;
-      for (const variant of ciVariants) {
-        if (src.endsWith(variant) && variant !== selectedVariant) return false;
+  const existingBefore = /* @__PURE__ */ new Set();
+  if (existsSync(destDir)) {
+    const beforeFiles = await walkDir(destDir, destDir).catch(() => []);
+    for (const f of beforeFiles) existingBefore.add(f);
+  }
+  const skippedFiles = [];
+  const destCiYml = join(destDir, ".github", "workflows", "ci.yml");
+  const workflowPrefix = join(".github", "workflows") + sep;
+  const destHasWorkflows = [...existingBefore].some(
+    (f) => f.startsWith(workflowPrefix) && f.endsWith(".yml")
+  );
+  try {
+    await copy(templateDir, destDir, {
+      overwrite: false,
+      errorOnExist: false,
+      filter: (src) => {
+        if (src.endsWith("CLAUDE.md")) return false;
+        const rel = relative(templateDir, src);
+        if (minimal && (rel.startsWith(".github") || rel.startsWith("docs"))) return false;
+        if (rel.includes("..")) return false;
+        if (src.endsWith(selectedVariant) && existsSync(destCiYml)) return false;
+        for (const variant of ciVariants) {
+          if (src.endsWith(variant) && variant !== selectedVariant) return false;
+        }
+        if (destHasWorkflows && rel.startsWith(workflowPrefix) && src.endsWith(".yml")) return false;
+        return true;
       }
-      return true;
-    }
-  });
+    });
+  } catch (e) {
+    const err = e;
+    const hint = err.code === "EACCES" || err.code === "EPERM" ? "Check directory permissions." : "Check available disk space.";
+    err.message = `Cannot copy template files: ${err.message}. ${hint}`;
+    throw err;
+  }
   if (!minimal) {
     const variantPath = join(destDir, ".github", "workflows", selectedVariant);
     const ciPath = join(destDir, ".github", "workflows", "ci.yml");
     if (existsSync(variantPath)) {
-      await rename(variantPath, ciPath);
+      if (existsSync(ciPath)) {
+        skippedFiles.push(".github/workflows/ci.yml");
+      } else {
+        await rename(variantPath, ciPath);
+      }
     }
   }
   const claudeSrc = join(templateDir, "CLAUDE.md");
@@ -131,7 +158,11 @@ async function copyTemplates(templateDir, destDir, dryRun, minimal, projectType
   const templateContent = await readFile2(claudeSrc, "utf-8");
   await mergeClaude(claudeDest, templateContent);
   const destFiles = await walkDir(destDir, destDir);
-  return destFiles.sort();
+  const allDestFiles = destFiles.sort();
+  const written = allDestFiles.filter((f) => !existingBefore.has(f));
+  const writtenWithClaude = written.includes("CLAUDE.md") ? written : ["CLAUDE.md", ...written];
+  const skipped = [...allDestFiles.filter((f) => existingBefore.has(f) && f !== "CLAUDE.md"), ...skippedFiles];
+  return { written: writtenWithClaude.sort(), skipped: skipped.sort() };
 }
 
 // src/steps/install-headroom.ts
@@ -173,6 +204,16 @@ async function installHeadroom(log) {
     log("Python 3.10+ not found \u2014 skipping headroom install. Install Python 3.10+ and run `goodvibes init` again.");
     return;
   }
+  log("headroom compresses AI context to save tokens \u2014 this keeps your costs down and sessions faster.");
+  try {
+    await execa2("headroom", ["--version"]);
+    log("headroom already installed \u2014 skipping");
+    return;
+  } catch (e) {
+    if (e.code !== "ENOENT") {
+      log(`headroom probe failed: ${e.message?.split("\n")[0] ?? "unknown"}`);
+    }
+  }
   log("Note: headroom will download its compression model on first use \u2014 this may take 1\u20133 minutes on a slow connection.");
   const installers = [
     { cmd: "uv", args: ["tool", "install", "headroom-ai[all]"] },
@@ -262,15 +303,24 @@ function registerInitCommand(program2) {
     const cwd = process.cwd();
     const projectType = detectProjectType(cwd);
     const templateDir = resolveTemplatesDir();
+    const ciVariants = ["ci-node.yml", "ci-python.yml", "ci-both.yml"];
+    const selectedVariant = `ci-${projectType}.yml`;
     intro("goodvibes init");
+    const existingEntries = readdirSync(cwd).filter((e) => e !== ".git" && e !== ".DS_Store");
+    if (existingEntries.length > 0) {
+      note("Existing files will not be overwritten.", "Non-empty project detected");
+    }
     if (dryRun) {
-      const files = await listTemplateFiles(templateDir);
+      const allFiles = await listTemplateFiles(templateDir);
+      const files = minimal ? allFiles.filter((f) => !f.startsWith(".github") && !f.startsWith("docs")) : allFiles.filter((f) => !ciVariants.some((v) => f.endsWith(v) && v !== selectedVariant));
       note(files.map((f) => `  Would write: ${f}`).join("\n"), "Dry run \u2014 no files written");
       note(
         [
-          "1. Open this project in Claude Code",
-          "2. In Claude Code CLI: /plugin marketplace add DietrichGebert/ponytail",
-          "3. Start coding \u2014 CLAUDE.md rules are already active"
+          "1. Open this project in your AI coding tool",
+          "2. Claude Code users: /plugin marketplace add DietrichGebert/ponytail",
+          "   Other IDEs (Cursor, Windsurf, Kiro, Antigravity, etc.): rules already active",
+          "3. Start coding \u2014 CLAUDE.md rules are already active",
+          ...minimal ? ["4. Run without --minimal to also add CI workflows and docs."] : []
         ].join("\n"),
         "Next steps"
       );
@@ -278,13 +328,15 @@ function registerInitCommand(program2) {
       return;
     }
     const createdFiles = [];
+    const skippedFiles = [];
     const taskList = [
       {
         title: "Copying template files",
         task: async (message) => {
-          const files = await copyTemplates(templateDir, cwd, false, minimal, projectType);
-          createdFiles.push(...files);
-          return `Copied ${files.length} files`;
+          const { written, skipped } = await copyTemplates(templateDir, cwd, false, minimal, projectType);
+          createdFiles.push(...written);
+          skippedFiles.push(...skipped);
+          return `Copied ${written.length} files`;
         }
       }
     ];
@@ -306,14 +358,34 @@ function registerInitCommand(program2) {
         }
       );
     }
-    await tasks(taskList);
-    note(createdFiles.join("\n"), "Files created");
+    try {
+      await tasks(taskList);
+    } catch (e) {
+      const err = e;
+      const msg = err.code === "EACCES" || err.code === "EPERM" ? `Cannot write files to ${cwd}.
+Why: You do not have write permission here.
+Fix: Make sure you are inside your project directory before running this command.
+      If permissions are the issue: chmod u+w ${cwd}  (macOS/Linux) or check folder properties (Windows)` : `Setup failed: ${err.message ?? String(e)}`;
+      cancel(msg);
+      process.exit(1);
+    }
+    note(createdFiles.join("\n") || "(none)", `Files written (${createdFiles.length})`);
+    if (skippedFiles.length > 0) {
+      note(skippedFiles.join("\n"), `Files skipped (${skippedFiles.length})`);
+    }
     const nextSteps = [
-      "1. Open this project in Claude Code",
-      "2. In Claude Code CLI: /plugin marketplace add DietrichGebert/ponytail",
+      "1. Open this project in your AI coding tool",
+      "2. Claude Code users: /plugin marketplace add DietrichGebert/ponytail",
+      "   Other IDEs (Cursor, Windsurf, Kiro, Antigravity, etc.): rules already active",
       "3. Start coding \u2014 CLAUDE.md rules are already active"
     ].join("\n");
     note(nextSteps, "Next steps");
+    if (minimal) {
+      note(
+        "CI workflows and docs were skipped.\nRun goodvibes init without --minimal to add them.",
+        "Skipped layers"
+      );
+    }
     outro("You're all set!");
   });
 }
@@ -360,13 +432,6 @@ async function detectInstalledVersion(cwd) {
   const content = await readFile3(claudePath, "utf-8");
   return extractVersion(content);
 }
-async function detectBundledVersion(templateDir) {
-  if (!templateDir) return null;
-  const claudeSrc = join3(templateDir, "CLAUDE.md");
-  if (!await pathExists2(claudeSrc)) return null;
-  const content = await readFile3(claudeSrc, "utf-8");
-  return extractVersion(content);
-}
 async function computeChanges(templateDir, destDir, projectType) {
   const allFiles = await listTemplateFiles(templateDir) ?? [];
   const managedFiles = allFiles.filter(
@@ -423,7 +488,7 @@ async function upgradeTemplates(templateDir, destDir, projectType) {
   return allDest.filter((f) => f.startsWith(".claude/skills/") || f.startsWith(".github/workflows/") || f === "CLAUDE.md").sort();
 }
 function registerUpgradeCommand(program2) {
-  program2.command("upgrade").description("Update goodvibes-managed files to the latest version").option("--dry-run", "Preview what would change without writing").action(async (options) => {
+  program2.command("upgrade").alias("update").description("Update goodvibes-managed files to the latest version").option("--dry-run", "Preview what would change without writing").action(async (options) => {
     const dryRun = options.dryRun ?? false;
     const cwd = process.cwd();
     intro2("goodvibes upgrade");
@@ -446,7 +511,7 @@ function registerUpgradeCommand(program2) {
     const templateDir = resolveTemplatesDir();
     const projectType = detectProjectType(cwd);
     const installedVersion = await detectInstalledVersion(cwd);
-    const bundledVersion = await detectBundledVersion(templateDir);
+    const bundledVersion = getInstalledVersion();
     if (installedVersion && bundledVersion && versionGte(installedVersion, bundledVersion)) {
       outro2(`Already up to date (v${installedVersion})`);
       return;
@@ -473,6 +538,90 @@ function registerUpgradeCommand(program2) {
   });
 }
 
+// src/commands/doctor.ts
+import { note as note3, outro as outro3 } from "@clack/prompts";
+import { existsSync as existsSync4, readFileSync } from "fs";
+import { join as join4 } from "path";
+import { execa as execa5 } from "execa";
+var SENTINEL_START2 = "<!-- goodvibes:start -->";
+var SENTINEL_END2 = "<!-- goodvibes:end -->";
+async function checkHeadroom() {
+  try {
+    await execa5("headroom", ["--version"]);
+    return { label: "headroom on PATH", pass: true };
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      return {
+        label: "headroom on PATH",
+        pass: false,
+        remedy: 'Run: uv tool install "headroom-ai[all]"  (or re-run goodvibes init)'
+      };
+    }
+    throw e;
+  }
+}
+async function checkGit() {
+  const keys = ["user.name", "user.email"];
+  const results = [];
+  for (const key of keys) {
+    try {
+      const { stdout } = await execa5("git", ["config", key]);
+      results.push({
+        label: `git ${key}`,
+        pass: stdout.trim().length > 0,
+        remedy: stdout.trim().length > 0 ? void 0 : `Run: git config --global ${key} "Your Value"`
+      });
+    } catch {
+      results.push({
+        label: `git ${key}`,
+        pass: false,
+        remedy: `Run: git config --global ${key} "Your Value"`
+      });
+    }
+  }
+  return results;
+}
+function checkClaudeMd(cwd) {
+  const present = existsSync4(join4(cwd, "CLAUDE.md"));
+  return {
+    label: "CLAUDE.md present",
+    pass: present,
+    remedy: present ? void 0 : "Run: goodvibes init"
+  };
+}
+function checkSentinel(cwd) {
+  const path = join4(cwd, "CLAUDE.md");
+  if (!existsSync4(path)) {
+    return { label: "goodvibes sentinel block", pass: false, remedy: "Run: goodvibes init" };
+  }
+  const content = readFileSync(path, "utf-8");
+  const ok = content.includes(SENTINEL_START2) && content.includes(SENTINEL_END2);
+  return {
+    label: "goodvibes sentinel block",
+    pass: ok,
+    remedy: ok ? void 0 : "Run: goodvibes init (will merge sentinel block)"
+  };
+}
+function registerDoctorCommand(program2) {
+  program2.command("doctor").description("Check goodvibes setup is complete").action(async () => {
+    const cwd = process.cwd();
+    const headroomResult = await checkHeadroom();
+    const gitResults = await checkGit();
+    const claudeMdResult = checkClaudeMd(cwd);
+    const sentinelResult = checkSentinel(cwd);
+    const all = [headroomResult, ...gitResults, claudeMdResult, sentinelResult];
+    const lines = all.map((r) => `${r.pass ? "\u2713" : "\u2717"} ${r.label}`);
+    note3(lines.join("\n"), "goodvibes doctor");
+    const failures = all.filter((r) => !r.pass);
+    if (failures.length > 0) {
+      const remediation = failures.filter((r) => r.remedy).map((r) => r.remedy).join("\n");
+      note3(remediation, "How to fix");
+      process.exit(1);
+    }
+    outro3("All checks passed.");
+  });
+}
+
 // src/index.ts
 var [major] = process.version.replace("v", "").split(".").map(Number);
 if (major < 20) {
@@ -484,8 +633,11 @@ Install the latest LTS from https://nodejs.org
   );
   process.exit(1);
 }
+var _require2 = createRequire2(import.meta.url);
+var _pkg = _require2("../package.json");
 var program = new Command();
-program.name("goodvibes").version("1.0.0").description("One-command bootstrap for vibe coding projects");
+program.name("goodvibes").version(_pkg.version).description("One-command bootstrap for vibe coding projects");
 registerInitCommand(program);
 registerUpgradeCommand(program);
+registerDoctorCommand(program);
 await program.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgiox/goodvibes",
-  "version": "1.2.0",
+  "version": "1.6.1",
   "description": "One-command bootstrap for vibe coding projects",
   "type": "module",
   "bin": {
@@ -24,7 +24,10 @@
     "claude",
     "llm",
     "starter-kit",
-    "cli"
+    "cli",
+    "ai-coding",
+    "claude-code",
+    "copilot"
   ],
   "publishConfig": {
     "access": "public"
@@ -37,7 +40,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "commander": "^13",
+    "commander": "^15",
     "@clack/prompts": "^1",
     "fs-extra": "^11",
     "execa": "^9"

package/templates/.amazonq/rules/goodvibes.md

@@ -0,0 +1,28 @@
+## Engineering Rules — goodvibes
+
+### Think before coding
+State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+### Simplicity first
+Stop at the first rung that holds:
+
+1. Does this need to exist at all? Speculative need → skip it. (YAGNI)
+2. Already in this codebase? Reuse it.
+3. Stdlib does it? Use it.
+4. Native platform feature covers it? Use it.
+5. Already-installed dependency solves it? Use it.
+6. Can it be one line? One line.
+7. Only then: the minimum code that works.
+
+No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+### Surgical changes
+Keep diffs narrow. No opportunistic reformats. No renames unless the task requires it. Only remove what your change made unused.
+
+### Fail loud
+No empty `catch` blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable.
+
+### Security
+Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege.
+
+Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.

package/templates/.bolt/prompt

@@ -0,0 +1,11 @@
+Engineering Rules for this project (goodvibes).
+
+Think before coding. State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+Simplicity first. Stop at the first option that works: Does this need to exist at all? Already in the codebase? Use it. Stdlib covers it? Use it. Can it be one line? One line. Only then write new code. No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+Surgical changes. Keep diffs narrow. No opportunistic reformats. No renames unless the task requires it. Only remove what your change made unused.
+
+Fail loud. No empty catch blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable and specific.
+
+Security. Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege. Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.

package/templates/.claude/skills/goodvibes-hygiene/SKILL.md

@@ -17,7 +17,14 @@ explicit on-demand audits.
 
 ## Setup
 
-Ponytail commands require the ponytail plugin. Install it in Claude Code:
+> **Using Cursor, Windsurf, Kiro, Copilot, Antigravity, Amazon Q, Cline, Continue.dev, Devin Desktop, or another IDE?**
+> The minimalism rules are already embedded in your project's IDE rule file
+> (`.cursor/rules/goodvibes.mdc`, `GEMINI.md`, `.windsurfrules`, `.kiro/steering/goodvibes.md`, `AGENTS.md`, `.clinerules/goodvibes.md`, `.amazonq/rules/goodvibes.md`, `.continue/rules/goodvibes.md`, `.devin/rules/goodvibes.md`)
+> and activate automatically — no plugin setup needed. The `/ponytail-review` and
+> `/ponytail-audit` commands below are **Claude Code CLI terminal only** and are not
+> available in other IDEs.
+
+Ponytail commands require the ponytail plugin. Install it in **Claude Code CLI terminal**:
 
 ```
 /plugin marketplace add DietrichGebert/ponytail

package/templates/.clinerules/goodvibes.md

@@ -0,0 +1,28 @@
+## Engineering Rules — goodvibes
+
+### Think before coding
+State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+### Simplicity first
+Stop at the first rung that holds:
+
+1. Does this need to exist at all? Speculative need → skip it. (YAGNI)
+2. Already in this codebase? Reuse it.
+3. Stdlib does it? Use it.
+4. Native platform feature covers it? Use it.
+5. Already-installed dependency solves it? Use it.
+6. Can it be one line? One line.
+7. Only then: the minimum code that works.
+
+No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+### Surgical changes
+Keep diffs narrow. No opportunistic reformats. No renames unless the task requires it. Only remove what your change made unused.
+
+### Fail loud
+No empty `catch` blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable.
+
+### Security
+Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege.
+
+Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.

package/templates/.continue/rules/goodvibes.md

@@ -0,0 +1,28 @@
+## Engineering Rules — goodvibes
+
+### Think before coding
+State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+### Simplicity first
+Stop at the first rung that holds:
+
+1. Does this need to exist at all? Speculative need → skip it. (YAGNI)
+2. Already in this codebase? Reuse it.
+3. Stdlib does it? Use it.
+4. Native platform feature covers it? Use it.
+5. Already-installed dependency solves it? Use it.
+6. Can it be one line? One line.
+7. Only then: the minimum code that works.
+
+No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+### Surgical changes
+Keep diffs narrow. No opportunistic reformats. No renames unless the task requires it. Only remove what your change made unused.
+
+### Fail loud
+No empty `catch` blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable.
+
+### Security
+Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege.
+
+Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.

package/templates/.cursor/rules/goodvibes.mdc

@@ -0,0 +1,28 @@
+---
+alwaysApply: true
+---
+
+## Engineering Rules — goodvibes
+
+### Think before coding
+State assumptions explicitly before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+### Simplicity first
+Stop at the first rung that holds:
+
+1. Does this need to exist at all? Speculative need → skip it. (YAGNI)
+2. Already in this codebase? Reuse it.
+3. Stdlib does it? Use it.
+4. Native platform feature covers it? Use it.
+5. Already-installed dependency solves it? Use it.
+6. Can it be one line? One line.
+7. Only then: the minimum code that works.
+
+### Surgical changes
+Keep diffs narrow. No opportunistic reformats. No renames unless required. Only remove what your change made unused.
+
+### Fail loud
+No empty `catch` blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable.
+
+### Security
+Validate input at the boundary. Keep secrets out of code and logs. Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.

package/templates/.devin/rules/goodvibes.md

@@ -0,0 +1,28 @@
+## Engineering Rules — goodvibes
+
+### Think before coding
+State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+### Simplicity first
+Stop at the first rung that holds:
+
+1. Does this need to exist at all? Speculative need → skip it. (YAGNI)
+2. Already in this codebase? Reuse it.
+3. Stdlib does it? Use it.
+4. Native platform feature covers it? Use it.
+5. Already-installed dependency solves it? Use it.
+6. Can it be one line? One line.
+7. Only then: the minimum code that works.
+
+No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+### Surgical changes
+Keep diffs narrow. No opportunistic reformats. No renames unless the task requires it. Only remove what your change made unused.
+
+### Fail loud
+No empty `catch` blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable.
+
+### Security
+Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege.
+
+Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.

package/templates/.github/copilot-instructions.md

@@ -0,0 +1,28 @@
+## Engineering Rules — goodvibes
+
+### Think before coding
+State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+### Simplicity first
+Stop at the first rung that holds:
+
+1. Does this need to exist at all? Speculative need → skip it. (YAGNI)
+2. Already in this codebase? Reuse it.
+3. Stdlib does it? Use it.
+4. Native platform feature covers it? Use it.
+5. Already-installed dependency solves it? Use it.
+6. Can it be one line? One line.
+7. Only then: the minimum code that works.
+
+No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+### Surgical changes
+Keep diffs narrow. No opportunistic reformats. No renames unless the task requires it. Only remove imports, variables, or functions that your change made unused.
+
+### Fail loud
+No empty `catch` blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable and specific enough to debug.
+
+### Security
+Validate input at the boundary. Keep secrets out of code, commits, and logs. Apply least privilege for tokens and permissions.
+
+Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets, unsafe dependency additions.

package/templates/.kiro/steering/goodvibes.md

@@ -0,0 +1,28 @@
+---
+inclusion: always
+---
+
+## Engineering Rules — goodvibes
+
+### Think before coding
+State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+### Simplicity first
+Stop at the first rung that holds:
+
+1. Does this need to exist at all? Speculative need → skip it. (YAGNI)
+2. Already in this codebase? Reuse it.
+3. Stdlib does it? Use it.
+4. Native platform feature covers it? Use it.
+5. Already-installed dependency solves it? Use it.
+6. Can it be one line? One line.
+7. Only then: the minimum code that works.
+
+### Surgical changes
+Keep diffs narrow. No opportunistic reformats. No renames unless required. Only remove what your change made unused.
+
+### Fail loud
+No empty `catch` blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable.
+
+### Security
+Validate input at the boundary. Keep secrets out of code and logs. Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.

package/templates/.windsurfrules

@@ -0,0 +1,28 @@
+## Engineering Rules — goodvibes
+
+### Think before coding
+State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+### Simplicity first
+Stop at the first rung that holds:
+
+1. Does this need to exist at all? Speculative need → skip it. (YAGNI)
+2. Already in this codebase? Reuse it.
+3. Stdlib does it? Use it.
+4. Native platform feature covers it? Use it.
+5. Already-installed dependency solves it? Use it.
+6. Can it be one line? One line.
+7. Only then: the minimum code that works.
+
+No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+### Surgical changes
+Keep diffs narrow. No opportunistic reformats. No renames unless the task requires it. Only remove what your change made unused.
+
+### Fail loud
+No empty `catch` blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable.
+
+### Security
+Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege.
+
+Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.

package/templates/AGENTS.md

@@ -0,0 +1,28 @@
+## Engineering Rules — goodvibes
+
+### Think before coding
+State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+### Simplicity first
+Stop at the first rung that holds:
+
+1. Does this need to exist at all? Speculative need → skip it. (YAGNI)
+2. Already in this codebase? Reuse it.
+3. Stdlib does it? Use it.
+4. Native platform feature covers it? Use it.
+5. Already-installed dependency solves it? Use it.
+6. Can it be one line? One line.
+7. Only then: the minimum code that works.
+
+No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+### Surgical changes
+Keep diffs narrow. No opportunistic reformats. No renames unless the task requires it. Only remove what your change made unused.
+
+### Fail loud
+No empty `catch` blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable.
+
+### Security
+Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege.
+
+Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.

package/templates/CLAUDE.md

@@ -1,7 +1,7 @@
 # CLAUDE.md
 
 <!-- goodvibes:start -->
-# goodvibes: v1.2.0
+# goodvibes: v1.6.1
 
 ## Engineering Rules
 
@@ -53,6 +53,13 @@ Rules: do not rewrite history. Additive entries only. Keep it short, factual, an
 **Push to GitHub after every completed task or end of session.**
 A commit that only exists locally is one machine failure away from being lost. Run `git push origin <branch>` after each commit, or at minimum before stopping for the day. Never leave completed work unpushed for more than one session.
 
+### Tools and environment
+**IDE plugin commands are surface-specific.**
+A slash command or plugin install that works in Claude Code terminal will not work in the
+VS Code extension, Cursor, Windsurf, Kiro, or any other IDE. Before referencing a tool
+command in shared docs, prompts, or instructions, confirm which surface it runs on. If it
+only works in one place, say so explicitly — do not leave users to discover it silently fails.
+
 ## Ponytail — Minimalism Ruleset
 
 You are a lazy senior developer. Lazy means efficient, not careless. You have

package/templates/GEMINI.md

@@ -0,0 +1,28 @@
+## Engineering Rules — goodvibes
+
+### Think before coding
+State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+### Simplicity first
+Stop at the first rung that holds:
+
+1. Does this need to exist at all? Speculative need → skip it. (YAGNI)
+2. Already in this codebase? Reuse it.
+3. Stdlib does it? Use it.
+4. Native platform feature covers it? Use it.
+5. Already-installed dependency solves it? Use it.
+6. Can it be one line? One line.
+7. Only then: the minimum code that works.
+
+No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+### Surgical changes
+Keep diffs narrow. No opportunistic reformats. No renames unless the task requires it. Only remove what your change made unused.
+
+### Fail loud
+No empty `catch` blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable.
+
+### Security
+Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege.
+
+Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.

package/templates/docs/getting-started.md

@@ -0,0 +1,31 @@
+# Getting started with goodvibes
+
+You ran `goodvibes init`. Here is what happens next.
+
+## What was set up
+
+goodvibes wrote several files into your project: `CLAUDE.md` with engineering rules and the ponytail minimalism ruleset, AI rule files for your coding tool (Cursor, Windsurf, Kiro, GitHub Copilot, and others), CI workflows for automated quality checks, and docs templates including this one. Everything runs automatically — no configuration needed.
+
+## Your first change
+
+1. **Open your project in your AI coding tool.** Cursor, Windsurf, Kiro, and GitHub Copilot all pick up the goodvibes rules automatically. The AI will follow minimal-code and fail-loud principles from the first message.
+2. **Tell the AI what you want to build.** Describe the feature in plain language — the rules guide the AI to keep code simple and surgical.
+3. **Review the diff before you commit.** Check that the AI only changed what you asked. The rules encourage narrow diffs — if the change looks too large, ask the AI to trim it.
+4. **Run `git add . && git commit -m "feat: your change here"`.** This saves a checkpoint in your project history so you can always go back.
+5. **Run `git push`.** This sends your work to GitHub, where it is safe even if your machine breaks.
+
+## Check your setup
+
+Run `goodvibes doctor` to verify everything is working. It checks that headroom is installed, your git identity is configured, and the goodvibes rules are in place.
+
+## Useful commands
+
+| Command | What it does |
+|---------|--------------|
+| `goodvibes update` | Re-sync goodvibes files to the latest version |
+| `goodvibes doctor` | Check that headroom, git, and rules are all working |
+| `goodvibes upgrade --dry-run` | Preview what `goodvibes update` would change |
+
+## What is headroom?
+
+headroom compresses the AI's memory of your project so you spend fewer tokens per session. It runs automatically in the background when Claude Code is active — you do not need to invoke it manually.

package/templates/docs/onboarding.md

@@ -93,3 +93,21 @@ A maintainer will look at your PR and either approve it, request changes, or ask
 ---
 
 That is the full loop: clone → branch → commit → push → pull request. Every contribution, large or small, follows this same pattern.
+
+---
+
+## Troubleshooting IDE rules
+
+**Cursor — rules appear inactive in agent mode**
+
+Cursor 3.0.x has a known bug where `alwaysApply: true` rules are silently downgraded in agent mode. If your goodvibes rules seem to have no effect in Cursor:
+
+1. Open Settings (Cmd/Ctrl + ,) and search for "Rules".
+2. Verify that `goodvibes` is listed under "Always Active" rules.
+3. If it appears as "Requestable" instead, toggle it to "Always Active" manually.
+
+This is an upstream Cursor issue — the `goodvibes.mdc` file format is correct.
+
+**Using multiple AI coding tools?**
+
+`goodvibes init` writes an `AGENTS.md` file at your project root. This is a cross-tool standard natively read by Zed, Aider, JetBrains Junie (IntelliJ, PyCharm, WebStorm), Jules, Amp, Codex CLI, and many others — without any extra setup. If you switch to a new AI coding tool, check whether it reads `AGENTS.md` before creating a separate rules file.

package/templates/docs/platform-setup/base44.md

@@ -0,0 +1,40 @@
+# Base44 — goodvibes setup
+
+Base44 does not read files from your project. Instead, you paste your rules into the AI controls panel, and Base44 applies them to every AI interaction in that project.
+
+## Steps
+
+1. Go to [base44.com](https://base44.com) and sign in.
+2. Open your project.
+3. Find the **AI controls** panel — it is usually in the top-right corner or under project Settings.
+4. Click **Custom Instructions**.
+5. Paste the text below into the box.
+6. Click **Save**.
+
+That is it. From now on, every AI action in this project follows the goodvibes engineering rules.
+
+> If the steps above do not match what you see, look for **Custom Instructions** or **AI controls** in the project settings. The UI may change — the paste text stays the same.
+
+> **Base44 Skills** is a separate feature for saving reusable instruction sets. goodvibes does not require it — pasting into Custom Instructions is enough.
+
+---
+
+## Paste this text
+
+```
+Engineering Rules — goodvibes
+
+Think before coding. State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+Simplicity first. Stop at the first option that works: Does this need to exist at all? Already in the codebase? Use it. Stdlib covers it? Use it. Can it be one line? One line. Only then write new code. No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+Surgical changes. Keep diffs narrow. No opportunistic reformats. No renames unless the task requires it. Only remove what your change made unused.
+
+Fail loud. No empty catch blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable and specific.
+
+Security. Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege. Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.
+```
+
+---
+
+## Last verified: 2026-07-01

package/templates/docs/platform-setup/bolt.md

@@ -0,0 +1,22 @@
+# Bolt.new — goodvibes setup
+
+Bolt.new does not read project files for AI rules. You activate ponytail discipline by pasting the rules into the chat as a one-time instruction.
+
+## One-time setup
+
+1. Open your Bolt.new project.
+2. In the chat, paste: "Please follow these engineering rules for all code you write:" then copy the text from `CLAUDE.md` between `<!-- goodvibes:start -->` and `<!-- goodvibes:end -->`.
+3. Bolt.new will acknowledge and apply the rules for the rest of the session.
+4. Repeat this at the start of each new session, or save it as a pinned message if Bolt.new supports it.
+
+## Ponytail on Bolt.new
+
+Once the rules are in the chat context, Bolt.new follows the ponytail minimalism rules: minimal code, surgical changes, fail loud. The AI will tell you when it is skipping something that is not needed yet.
+
+## Headroom
+
+Headroom is not applicable inside Bolt.new — context is managed by the Bolt.new platform itself.
+
+---
+
+## Last verified: 2026-07-01

package/templates/docs/platform-setup/chatgpt.md

@@ -0,0 +1,38 @@
+# ChatGPT Projects — goodvibes setup
+
+ChatGPT does not read files from your project. Instead, you paste your rules directly into the project's custom instructions, and ChatGPT applies them to every conversation in that project.
+
+## Steps
+
+1. Go to [chatgpt.com](https://chatgpt.com) and sign in.
+2. Click **Projects** in the left sidebar. Create a new project or open an existing one.
+3. Click the project name at the top of the page. A panel opens on the right.
+4. Click **Project Instructions**.
+5. Paste the text below into the box.
+6. Click **Save**.
+
+That is it. From now on, every conversation in this project follows the goodvibes engineering rules.
+
+> If the steps above do not match what you see, look for **Project Instructions** or **Custom Instructions** in the project settings panel. The UI may change — the paste text stays the same.
+
+---
+
+## Paste this text
+
+```
+Engineering Rules — goodvibes
+
+Think before coding. State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+Simplicity first. Stop at the first option that works: Does this need to exist at all? Already in the codebase? Use it. Stdlib covers it? Use it. Can it be one line? One line. Only then write new code. No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+Surgical changes. Keep diffs narrow. No opportunistic reformats. No renames unless the task requires it. Only remove what your change made unused.
+
+Fail loud. No empty catch blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable and specific.
+
+Security. Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege. Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.
+```
+
+---
+
+## Last verified: 2026-07-01

package/templates/docs/platform-setup/cursor.md

@@ -0,0 +1,23 @@
+# Cursor — goodvibes setup
+
+goodvibes init wrote `.cursor/rules/goodvibes.mdc` into your project. This file activates the ponytail minimalism rules automatically when you open the project in Cursor.
+
+## Ponytail is already active
+
+The rules enforce simplicity-first coding, fail-loud error handling, and surgical changes — no file you did not touch, no code you did not need. You do not need to paste anything. The rules are in `.cursor/rules/goodvibes.mdc` and Cursor loads them for every AI chat in this project.
+
+## Verify activation
+
+Open Cursor. In the AI chat, ask: "What are your active rules?" You should see a reference to goodvibes or ponytail in the response.
+
+## If you use .cursorrules (legacy)
+
+If your project has a `.cursorrules` file from before goodvibes, the `.cursor/rules/goodvibes.mdc` file is independent. Both will apply. You may want to merge them to avoid duplication.
+
+## Headroom (context compression)
+
+Cursor does not use Claude Code's MCP protocol. If you want context compression, install headroom separately and use it via its CLI. See [headroom docs](https://headroom-docs.vercel.app/).
+
+---
+
+## Last verified: 2026-07-01

package/templates/docs/platform-setup/kiro.md

@@ -0,0 +1,19 @@
+# Kiro — goodvibes setup
+
+goodvibes init wrote `.kiro/steering/goodvibes.md` into your project. Kiro applies steering files automatically to all AI interactions in the project.
+
+## Ponytail is already active
+
+The ponytail rules in `.kiro/steering/goodvibes.md` enforce simplicity-first coding, fail-loud error handling, and surgical changes. You do not need to paste anything or configure anything — the steering file is active as soon as you open the project in Kiro.
+
+## Verify activation
+
+Open Kiro and check the steering files panel in your project settings. You should see `goodvibes.md` listed as an always-on steering file.
+
+## Headroom (context compression)
+
+Kiro does not use Claude Code's MCP protocol. If you want context compression, install headroom separately and use it via its CLI. See [headroom docs](https://headroom-docs.vercel.app/).
+
+---
+
+## Last verified: 2026-07-01

package/templates/docs/platform-setup/replit.md

@@ -0,0 +1,26 @@
+# Replit Agent — goodvibes setup
+
+Replit Agent does not read files from your project automatically. Instead, you provide the rules as a system prompt for the Agent.
+
+## One-time setup
+
+1. Open your Repl.
+2. Find **System prompt** or **AI instructions** in the Agent settings panel.
+3. Copy the text from `CLAUDE.md` — specifically the section between `<!-- goodvibes:start -->` and `<!-- goodvibes:end -->`.
+4. Paste into the system prompt field and click **Save**.
+
+That is it. Replit Agent will follow the goodvibes rules for every task in this project.
+
+> If you do not see a system prompt field, look for **Agent instructions** or **Custom rules** in the project settings.
+
+## Ponytail on Replit
+
+Once the system prompt is set, Replit Agent follows the ponytail rules for every task: minimal code, no over-engineering, and explicit error handling. The AI will tell you if it is skipping something because it is not needed yet.
+
+## Headroom
+
+Replit manages its own context. Headroom is not applicable inside Replit — skip the headroom install step if you are Replit-only.
+
+---
+
+## Last verified: 2026-07-01

package/templates/docs/platform-setup/windsurf.md

@@ -0,0 +1,19 @@
+# Windsurf — goodvibes setup
+
+goodvibes init wrote `.windsurfrules` into your project. Windsurf reads this file automatically and applies the goodvibes engineering rules to every AI interaction.
+
+## Ponytail is already active
+
+The rules in `.windsurfrules` enforce simplicity-first coding, fail-loud error handling, and surgical changes. You do not need to paste anything — Windsurf picks up the file on its own.
+
+## Verify activation
+
+Open Windsurf. In the Cascade AI panel, ask: "What are your active rules?" You should see a reference to goodvibes or ponytail in the response.
+
+## Headroom (context compression)
+
+Windsurf does not use Claude Code's MCP protocol. If you want context compression, install headroom separately and use it via its CLI. See [headroom docs](https://headroom-docs.vercel.app/).
+
+---
+
+## Last verified: 2026-07-01

package/templates/replit.md

@@ -0,0 +1,32 @@
+# Engineering Rules — goodvibes
+<!-- Replit Agent may regenerate this file. Commit it to git to preserve your edits. -->
+
+## Project Overview
+This project uses goodvibes engineering rules. Apply them to every task.
+
+## Coding Style
+State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+## Simplicity First
+Stop at the first rung that holds:
+
+1. Does this need to exist at all? Speculative need → skip it. (YAGNI)
+2. Already in this codebase? Reuse it.
+3. Stdlib does it? Use it.
+4. Native platform feature covers it? Use it.
+5. Already-installed dependency solves it? Use it.
+6. Can it be one line? One line.
+7. Only then: the minimum code that works.
+
+No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+## Surgical Changes
+Keep diffs narrow. No opportunistic reformats. Only remove what your change made unused.
+
+## Fail Loud
+No empty catch blocks. No silent retries. No fake success on real failure. Error messages must be actionable.
+
+## Security
+Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege.
+
+Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.