dmno-dev · theoephraim · Apr 21, 2026 · Apr 21, 2026 · Apr 21, 2026 · Apr 21, 2026
diff --git a/.bumpy/README.md b/.bumpy/README.md
@@ -0,0 +1,63 @@
+# 🐸 Bumpy
+
+This directory is used by [bumpy](https://bumpy.varlock.dev) to manage versioning and changelogs.
+
+Bumpy is a modern versioning tool for JavaScript/TypeScript projects (monorepos and single packages). It uses **bump files** — small markdown files in this directory — to declare pending version changes. These files are consumed during the release process to compute version bumps, update changelogs, and publish packages.
+
+## How it works
+
+1. When you make a change that should trigger a release, create a bump file (typically one per PR)
+2. Bump files accumulate on your main branch until you're ready to release
+3. At release time, bumpy merges all pending bumps into a release plan, updates versions and changelogs, and publishes packages
+
+## Creating bump files
+
+### Interactive
+
+```bash
+bunx bumpy add
+```
+
+### Non-interactive (useful for AI-assisted development)
+
+```bash
+bunx bumpy add --packages "package-name:minor,other-package:patch" --message "Description of changes" --name "my-change"
+```
+
+### By hand
+
+Create a `.md` file in this directory with YAML frontmatter mapping package names to bump levels (`major`, `minor`, or `patch`), and a markdown body for the changelog entry:
+
+```markdown
+---
+'package-name': minor
+---
+
+Added a new feature.
+```
+
+### From conventional commits
+
+```bash
+bunx bumpy generate
+```
+
+### Empty bump files
+
+For PRs that intentionally don't need a release (docs, CI, etc.):
+
+```bash
+bunx bumpy add --empty --name "docs-update"
+```
+
+## Keeping bump files up to date
+
+As a PR evolves, make sure its bump file stays in sync. If the scope of changes grows (e.g., a patch becomes a new feature), update the bump level and description to match. Reviewers and AI assistants should treat the bump file as part of the PR — just like tests and docs.
+
+## Files in this directory
+
+- `_config.json` — bumpy configuration
+- `README.md` — this file
+- `*.md` (other than README.md) — pending bump files
+
+📖 Full documentation: https://bumpy.varlock.dev
diff --git a/.bumpy/init-readme.md b/.bumpy/init-readme.md
@@ -0,0 +1,5 @@
+---
+'@varlock/bumpy': patch
+---
+
+Generate comprehensive README.md in .bumpy/ during init with auto-detected package manager commands
diff --git a/.env.schema b/.env.schema
@@ -6,4 +6,4 @@
 
 # Public URL for the bumpy website/docs
 # @type=url
-BUMPY_WEBSITE_URL=https://github.com/dmno-dev/bumpy
+BUMPY_WEBSITE_URL=https://bumpy.varlock.dev
diff --git a/packages/bumpy/bunfig.toml b/packages/bumpy/bunfig.toml
@@ -3,4 +3,3 @@
 
 [define]
 "__BUMPY_VERSION__" = "'dev'"
-"__BUMPY_WEBSITE_URL__" = "'https://github.com/dmno-dev/bumpy'"
diff --git a/packages/bumpy/src/cli.ts b/packages/bumpy/src/cli.ts
@@ -234,7 +234,7 @@ function printHelp() {
   AI setup options:
     --target <tool>         Target AI tool: opencode, cursor, codex
 
-  ${colorize(__BUMPY_WEBSITE_URL__, 'dim')}
+  ${colorize('https://bumpy.varlock.dev', 'dim')}
 `);
 }
 

diff --git a/packages/bumpy/src/commands/ci.ts b/packages/bumpy/src/commands/ci.ts
@@ -435,7 +435,7 @@ function formatReleasePlanComment(
   const lines: string[] = [];
 
   const preamble = [
-    `<a href="${__BUMPY_WEBSITE_URL__}"><img src="${FROG_IMG_BASE}/frog-talking.png" alt="bumpy-frog" width="60" align="left" style="image-rendering: pixelated;" title="Hi! I'm bumpy!" /></a>`,
+    `<a href="https://bumpy.varlock.dev"><img src="${FROG_IMG_BASE}/frog-talking.png" alt="bumpy-frog" width="60" align="left" style="image-rendering: pixelated;" title="Hi! I'm bumpy!" /></a>`,
     '',
     '**The changes in this PR will be included in the next version bump.**',
     '<br clear="left" />',
@@ -495,14 +495,14 @@ function formatReleasePlanComment(
   }
 
   lines.push('---');
-  lines.push(`_This comment is maintained by [bumpy](${__BUMPY_WEBSITE_URL__})._`);
+  lines.push(`_This comment is maintained by [bumpy](https://bumpy.varlock.dev)._`);
   return lines.join('\n');
 }
 
 function formatNoBumpFilesComment(prBranch: string | null, pm: PackageManager): string {
   const runCmd = pmRunCommand(pm);
   const lines = [
-    `<a href="${__BUMPY_WEBSITE_URL__}"><img src="${FROG_IMG_BASE}/frog-neutral.png" alt="bumpy-frog" width="60" align="left" style="image-rendering: pixelated;" title="Hi! I'm bumpy!" /></a>`,
+    `<a href="https://bumpy.varlock.dev"><img src="${FROG_IMG_BASE}/frog-neutral.png" alt="bumpy-frog" width="60" align="left" style="image-rendering: pixelated;" title="Hi! I'm bumpy!" /></a>`,
     '',
     "Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. **If these changes should result in a version bump, you need to add a bump file.**",
     '<br clear="left" />\n',
@@ -519,7 +519,7 @@ function formatNoBumpFilesComment(prBranch: string | null, pm: PackageManager):
   }
 
   lines.push('\n---');
-  lines.push(`_This comment is maintained by [bumpy](${__BUMPY_WEBSITE_URL__})._`);
+  lines.push(`_This comment is maintained by [bumpy](https://bumpy.varlock.dev)._`);
   return lines.join('\n');
 }
 

diff --git a/packages/bumpy/src/commands/init.ts b/packages/bumpy/src/commands/init.ts
@@ -1,7 +1,16 @@
 import { resolve } from 'node:path';
 import { ensureDir, writeJson, writeText, exists } from '../utils/fs.ts';
 import { log } from '../utils/logger.ts';
+import { detectPackageManager } from '../utils/package-manager.ts';
 import type { BumpyConfig } from '../types.ts';
+import readmeTemplate from '../../../../.bumpy/README.md';
+
+const PM_RUNNER: Record<string, string> = {
+  bun: 'bunx bumpy',
+  pnpm: 'pnpm bumpy',
+  yarn: 'yarn bumpy',
+  npm: 'npx bumpy',
+};
 
 export async function initCommand(rootDir: string): Promise<void> {
   const bumpyDir = resolve(rootDir, '.bumpy');
@@ -20,11 +29,10 @@ export async function initCommand(rootDir: string): Promise<void> {
   };
   await writeJson(resolve(bumpyDir, '_config.json'), config);
 
-  // Write a README explaining the directory
-  await writeText(
-    resolve(bumpyDir, 'README.md'),
-    `# 🐸 Bumpy\n\nThis directory is used by [bumpy](${__BUMPY_WEBSITE_URL__}) to manage versioning.\n\nBump files (\`.md\`) in this directory describe pending version bumps.\nRun \`bumpy add\` to create one interactively, or \`bumpy generate\` to auto-create from branch commits.\n`,
-  );
+  // Write a README with commands tailored to the detected package manager
+  const pm = await detectPackageManager(rootDir);
+  const readmeContent = readmeTemplate.replaceAll('bunx bumpy', PM_RUNNER[pm] || 'npx bumpy');
+  await writeText(resolve(bumpyDir, 'README.md'), readmeContent);
 
   log.success('Initialized .bumpy/ directory');
   log.dim('  Created .bumpy/_config.json');

diff --git a/packages/bumpy/src/globals.d.ts b/packages/bumpy/src/globals.d.ts
@@ -7,9 +7,8 @@
  * Injected at build time by tsdown, or via bunfig.toml when running from source
  * */
 declare const __BUMPY_VERSION__: string;
-/**
- * docs website url
- *
- * Injected at build time by tsdown, or via bunfig.toml when running from source
- * */
-declare const __BUMPY_WEBSITE_URL__: string;
+
+declare module '*.md' {
+  const content: string;
+  export default content;
+}
diff --git a/packages/bumpy/src/types.ts b/packages/bumpy/src/types.ts
@@ -144,9 +144,9 @@ export const DEFAULT_CONFIG: BumpyConfig = {
     title: '🐸 Versioned release',
     branch: 'bumpy/version-packages',
     preamble: [
-      `<a href="${__BUMPY_WEBSITE_URL__}"><img src="https://raw.githubusercontent.com/dmno-dev/bumpy/main/images/frog-talking.png" alt="bumpy-frog" width="60" align="left" style="image-rendering: pixelated;" title="Hi! I'm bumpy!" /></a>`,
+      `<a href="https://bumpy.varlock.dev"><img src="https://raw.githubusercontent.com/dmno-dev/bumpy/main/images/frog-talking.png" alt="bumpy-frog" width="60" align="left" style="image-rendering: pixelated;" title="Hi! I'm bumpy!" /></a>`,
       '',
-      `This PR was created and will be kept in sync by [bumpy](${__BUMPY_WEBSITE_URL__}) based on your .bumpy bump files. Merge it when you are ready to release the packages listed below:`,
+      `This PR was created and will be kept in sync by [bumpy](https://bumpy.varlock.dev) based on your .bumpy bump files. Merge it when you are ready to release the packages listed below:`,
       '<br clear="left" />',
     ].join('\n'),
   },

diff --git a/packages/bumpy/tsdown.config.ts b/packages/bumpy/tsdown.config.ts
@@ -1,7 +1,6 @@
 import { defineConfig } from 'tsdown';
 import { readFileSync } from 'node:fs';
 import 'varlock/auto-load';
-import { ENV } from 'varlock/env';
 
 const pkg = JSON.parse(readFileSync('./package.json', 'utf-8'));
 
@@ -13,8 +12,10 @@ export default defineConfig({
   format: 'esm',
   dts: true,
   clean: true,
+  loader: {
+    '.md': 'text',
+  },
   define: {
     __BUMPY_VERSION__: JSON.stringify(pkg.version),
-    __BUMPY_WEBSITE_URL__: JSON.stringify(ENV.BUMPY_WEBSITE_URL),
   },
 });
Original file line number	Diff line number	Diff line change
Expand Up		@@ -3,4 +3,3 @@

		[define]
		"__BUMPY_VERSION__" = "'dev'"
		"__BUMPY_WEBSITE_URL__" = "'https://github.com/dmno-dev/bumpy'"