fix(version-check): use createRequire instead of require.resolve for ESM compat

docs: add versioning guidelines to AGENTS.md, CONTRIBUTING.md, and scaffold README

- Fix require.resolve in readAdapterVersion — not available in ESM context
- Add Versioning section to AGENTS.md: patch/minor/major rules for core + adapters
- Add versioning + changeset workflow section to CONTRIBUTING.md
- Update create-adapter scaffold: README now includes versioning section,
  correct package name (@browserkit-dev/adapter-*), and dynamic core version

Made-with: Cursor

Author: jonzarecki

AGENTS.md

@@ -80,3 +80,45 @@ Durable facts and correction patterns for this workspace. Updated by continual-l
 - El Al scraper returns `ERR_ABORTED` when called concurrently with Israir — run the two scrapers sequentially to avoid
 - **Israir booking URL** format: `https://www.israir.co.il/he-IL/reservation/deal/searchFlight/abroadFlight?destCode=TLV&departDate=...&fNumbers=...&sessionId=...` — the `sessionId` is live-session-scoped and expires; cannot be reused outside the active browser session
 - **Verification preference**: use the adapter's own headless Patchright browser (not the cursor-ide-browser MCP) for rescue-flights verification — user stated strong preference ("I prefer it immensely")
+
+## Versioning
+
+### @browserkit-dev/core
+
+Follows semver. During 0.x, treat minor bumps as potentially breaking for consumers.
+
+- **patch** (`0.1.x`): bug fixes, log/doc changes, internal refactors with no public API change.
+  - Examples: fix a crash in `waitUntil`, fix a typo in an error message, optimize `scrollContainer`.
+  - Rule: **no adapter needs to change any code** after updating core.
+
+- **minor** (`0.x.0`): new features, new optional fields on `SiteAdapter`, new exported utilities, new CLI commands.
+  - Examples: add `withLoginFlow`, add `minCoreVersion?` to `SiteAdapter`, add `browserkit doctor`.
+  - Rule: **existing adapters compile and run without changes** (purely additive).
+
+- **major** (`x.0.0`): breaking changes — removed exports, renamed functions, required new fields on `SiteAdapter`, changed tool-call contracts.
+  - Examples: rename `detectRateLimit` → `detectChallenge`, make `minCoreVersion` required, remove `scrollContainer`.
+  - Rule: **at least one published adapter must change source code** to compile against the new version.
+
+**Decision shortcut**: run `test-adapters.yml` after your change (or locally build each adapter against the new core). If all 5 pass without code changes → patch or minor. If any fails → major (or the failing adapter's peer dep range was already wrong).
+
+### Adapter packages (`@browserkit-dev/adapter-*`)
+
+Same semver rules, but "breaking" means "an MCP tool's public interface changed":
+
+- **patch**: bug fix, selector update, scraping logic change — no tool name/input/output signature change.
+- **minor**: new tool added, new optional input field on an existing tool, new optional output field.
+- **major**: tool removed or renamed, required input field added, output field removed or type-changed.
+
+### Changeset workflow (required for every PR that changes behavior)
+
+```bash
+# In the monorepo (core changes)
+pnpm changeset
+
+# In an adapter repo
+npx changeset
+```
+
+When prompted: choose `patch` / `minor` / `major` per the rules above, then write a one-sentence user-facing summary (what changed for users, not how it was implemented). Commit the generated `.changeset/*.md` file in the same PR.
+
+The Release GitHub Action handles version bumping and `npm publish` automatically when the changeset PR is merged to `main`.

CONTRIBUTING.md

@@ -91,3 +91,27 @@ Scaffold a new adapter with:
 ```bash
 npx @browserkit-dev/core create-adapter my-site
 ```
+
+---
+
+## Versioning and releases
+
+Versioning rules are documented in full in [AGENTS.md — Versioning](https://github.com/browserkit-dev/browserkit/blob/main/AGENTS.md#versioning). The short version:
+
+| Change | Bump |
+|--------|------|
+| Bug fix, doc/log change, no API change | `patch` |
+| New feature, new optional API field | `minor` |
+| Removed/renamed export, required new field | `major` |
+
+Every PR that changes behavior needs a **changeset** before merging:
+
+```bash
+# Core monorepo
+pnpm changeset
+
+# Adapter repos
+npx changeset
+```
+
+Follow the prompts: choose `patch` / `minor` / `major`, write a one-line user-facing summary, and commit the generated `.changeset/*.md` file in the same PR. The Release GitHub Action bumps the version and publishes to npm automatically when the changeset PR merges to `main`.

packages/core/src/create-adapter.ts

@@ -264,14 +264,15 @@ describe("${name} adapter", () => {
 }
 
 function readme(name: string): string {
+  const coreVersion = readCoreVersion();
   return `# browserkit adapter: ${name}
 
-A [browserkit](https://github.com/jzarecki/browserkit) adapter for ${name}.
+A [browserkit](https://github.com/browserkit-dev/browserkit) adapter for ${name}.
 
 ## Installation
 
 \`\`\`bash
-pnpm add @browserkit-dev/core browserkit-adapter-${name}
+pnpm add @browserkit-dev/core @browserkit-dev/adapter-${name}
 \`\`\`
 
 ## Usage
@@ -283,7 +284,7 @@ import { defineConfig } from "@browserkit-dev/core";
 
 export default defineConfig({
   adapters: {
-    "browserkit-adapter-${name}": { port: 3847 },
+    "@browserkit-dev/adapter-${name}": { port: 3847 },
   },
 });
 \`\`\`
@@ -308,5 +309,17 @@ pnpm install
 pnpm test
 pnpm run build
 \`\`\`
+
+## Versioning
+
+This adapter requires \`@browserkit-dev/core >= ${coreVersion}\` (declared via \`minCoreVersion\`).
+
+Bump rules for this adapter:
+- **patch** — bug fix, selector update, no tool API change
+- **minor** — new tool added, new optional input/output field
+- **major** — tool removed or renamed, required input added, output type changed
+
+Every PR that changes behavior should include a changeset (\`npx changeset\`).
+See [browserkit versioning guidelines](https://github.com/browserkit-dev/browserkit/blob/main/AGENTS.md#versioning) for the full rules.
 `;
 }

packages/core/src/version-check.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
+import { createRequire } from "node:module";
 
 /**
  * Parse a semver string into [major, minor, patch] tuple.
@@ -47,26 +48,45 @@ export function readCoreVersion(): string {
 /**
  * Read a package.json version from a file path or npm package name.
  * Returns null if not found.
+ *
+ * For file paths: walks up from the given path to find the nearest package.json.
+ * For npm package names: resolves the main entry via createRequire, then walks
+ *   up the directory tree to find the package.json whose "name" matches.
  */
 export function readAdapterVersion(packageNameOrPath: string): string | null {
   try {
-    let pkgJsonPath: string;
-
     if (packageNameOrPath.startsWith("/") || packageNameOrPath.startsWith(".")) {
-      // File path: look for package.json next to the dist file
-      const dir = path.dirname(packageNameOrPath);
-      // Try sibling package.json (e.g. dist/index.js → package.json one level up)
-      pkgJsonPath = fs.existsSync(path.join(dir, "package.json"))
-        ? path.join(dir, "package.json")
-        : path.join(dir, "..", "package.json");
-    } else {
-      // npm package: resolve from node_modules
-      // Use require.resolve to find it regardless of cwd
-      pkgJsonPath = require.resolve(`${packageNameOrPath}/package.json`);
+      // File path: walk up at most 5 levels to find package.json
+      let dir = path.dirname(packageNameOrPath);
+      for (let i = 0; i < 5; i++) {
+        const candidate = path.join(dir, "package.json");
+        if (fs.existsSync(candidate)) {
+          const pkg = JSON.parse(fs.readFileSync(candidate, "utf8")) as { version?: string };
+          return pkg.version ?? null;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) break; // reached filesystem root
+        dir = parent;
+      }
+      return null;
     }
 
-    const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8")) as { version?: string };
-    return pkg.version ?? null;
+    // npm package: use createRequire (ESM-safe) to resolve the main entry,
+    // then walk up to find the package.json whose "name" matches.
+    const require = createRequire(import.meta.url);
+    const mainEntry = require.resolve(packageNameOrPath);
+    let dir = path.dirname(mainEntry);
+    while (true) {
+      const candidate = path.join(dir, "package.json");
+      if (fs.existsSync(candidate)) {
+        const pkg = JSON.parse(fs.readFileSync(candidate, "utf8")) as { name?: string; version?: string };
+        if (pkg.name === packageNameOrPath) return pkg.version ?? null;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break; // reached filesystem root
+      dir = parent;
+    }
+    return null;
   } catch {
     return null;
   }