docs: add CI discipline rule to AGENTS.md; rewrite CLAUDE.md with accurate repo + CI context

Made-with: Cursor

Author: jonzarecki

AGENTS.md

@@ -122,3 +122,32 @@ 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`.
+
+## CI Discipline
+
+**After every significant change, verify CI passes before considering the task done.**
+
+"Significant" means: any commit that touches `packages/core/src/`, adapter source files, `.github/workflows/`, `package.json` deps, or any change that gets pushed to `main`.
+
+### How to check
+
+```bash
+# Monorepo CI (unit + E2E):
+gh run list --repo browserkit-dev/browserkit --workflow=ci.yml --limit 1 --json status,conclusion
+
+# All repos at once:
+for repo in browserkit adapter-hackernews adapter-google-discover adapter-linkedin adapter-reddit adapter-booking; do
+  r=$(gh run list --repo browserkit-dev/$repo --workflow=ci.yml --limit 1 --json status,conclusion --jq '.[0] | "\(.status) \(.conclusion)"')
+  echo "$repo: $r"
+done
+```
+
+### If CI fails
+
+1. Read the failing step logs: `gh api repos/browserkit-dev/<repo>/actions/runs/<run_id>/jobs`  
+2. Fix the root cause (don't push empty retrigger commits to mask real failures)  
+3. Push the fix and wait for green before closing out the task
+
+### Known flaky test
+
+`tests/e2e/smoke.test.ts > Phase 1 > get_top returns real HN articles` occasionally fails with `net::ERR_ABORTED` when GitHub Actions IPs are rate-limited by HN. If **only** this test fails and the error is a network error (not a code error), retrigger once. If it fails twice in a row, investigate whether HN's DOM changed.

CLAUDE.md

@@ -2,42 +2,109 @@
 
 Open-source framework for building site-specific MCP servers over real authenticated user browser sessions. Turns your logged-in web sessions into composable, testable AI tools — locally.
 
-## Quick start
+## Repo layout
 
-No runtime code yet. See SPEC.md for the full product spec.
+```
+packages/
+  core/           @browserkit-dev/core — the framework (published to npm)
+  adapter-hackernews/   gitignored — clone of browserkit-dev/adapter-hackernews
+  adapter-linkedin/     gitignored — clone of browserkit-dev/adapter-linkedin
+  adapter-rescue-flights/  personal adapter, local-only (never in browserkit-dev org)
+tests/
+  e2e/            Full-daemon smoke tests (require Chromium)
+.github/workflows/
+  ci.yml          Unit tests (job: unit) + E2E smoke (job: e2e, needs: unit)
+  release.yml     Changesets publish pipeline — publishes @browserkit-dev/core on merge
+  test-adapters.yml  Matrix CI: tests all 5 external adapters after core releases
+```
 
 ## Build & test
 
-TBD — stack not decided yet (TypeScript + Playwright or Python + Playwright).
+```bash
+pnpm install
+pnpm build        # builds core + workspace adapters
+pnpm test         # unit tests across all workspace packages (192 tests)
+pnpm test:e2e     # E2E smoke tests (requires Chromium — run after pnpm build)
+pnpm lint         # tsc --noEmit across all packages
+```
+
+Individual packages:
+```bash
+pnpm --filter @browserkit-dev/core build
+pnpm --filter @browserkit-dev/core test
+```
 
 ## Architecture
 
-- **Session Manager** — persistent auth browser processes
-- **Site Adapter** — per-site structured action modules
-- **MCP Server** — wraps adapters as typed MCP tools
-- **Human Handoff** — foregrounds browser for 2FA/confirmation
-- See `ARCH.md` for full architecture and file tree
-- See `SPEC.md` for detailed product spec
+- **`SessionManager`** — owns all browser contexts (one per adapter site), handles persistent profiles, headed/headless switching, storage-state injection
+- **`SiteAdapter` interface** — adapters implement `site`, `domain`, `loginUrl`, `isLoggedIn()`, `tools()` — optional: `preparePage()`, `getLoginOptions()`, `minCoreVersion`, `requirements`
+- **`createAdapterServer`** — wraps an adapter as an HTTP MCP server; each connecting client gets its own `McpServer + StreamableHTTPServerTransport`
+- **`LockManager`** — FIFO serialization of tool calls per site; `holdForUser` for paused mode
+- **`withLoginFlow`** — opt-in automated form-fill login; falls back to human-handoff if not configured
+- See `ARCH.md` for full file tree, `SPEC.md` for product requirements
+
+## External adapter repos (all under `browserkit-dev/`)
+
+All 5 adapters are published on npm at `@browserkit-dev/adapter-*`:
+
+| Adapter | Repo | npm |
+|---------|------|-----|
+| HackerNews | `browserkit-dev/adapter-hackernews` | `@browserkit-dev/adapter-hackernews@0.1.0` |
+| Google Discover | `browserkit-dev/adapter-google-discover` | `@browserkit-dev/adapter-google-discover@0.1.0` |
+| LinkedIn | `browserkit-dev/adapter-linkedin` | `@browserkit-dev/adapter-linkedin@0.1.0` |
+| Reddit | `browserkit-dev/adapter-reddit` | `@browserkit-dev/adapter-reddit@0.1.0` |
+| Booking.com | `browserkit-dev/adapter-booking` | `@browserkit-dev/adapter-booking@0.1.0` |
+
+Local dev: clone any adapter into `packages/` — pnpm workspace links `@browserkit-dev/core` automatically.
+
+## CI overview
+
+```
+browserkit-dev/browserkit  ci.yml
+  job: unit     pnpm install → pnpm build → pnpm test
+  job: e2e      (needs: unit) install Chromium → build → checkout HN adapter → pnpm test:e2e
+
+browserkit-dev/adapter-*   ci.yml (all identical)
+  npm ci → install Chromium → npm run build → npm test
+
+browserkit-dev/browserkit  release.yml
+  On push to main: changesets/action → version bump PR or npm publish
+
+browserkit-dev/browserkit  test-adapters.yml
+  After Release workflow succeeds: matrix job runs each adapter's CI against latest core
+```
+
+**After every significant change, verify CI is green** before closing out a task:
+```bash
+for repo in browserkit adapter-hackernews adapter-google-discover adapter-linkedin adapter-reddit adapter-booking; do
+  r=$(gh run list --repo browserkit-dev/$repo --workflow=ci.yml --limit 1 --json status,conclusion --jq '.[0] | "\(.status) \(.conclusion)"')
+  echo "$repo: $r"
+done
+```
+
+Known flaky: `e2e > get_top returns real HN articles` fails with `net::ERR_ABORTED` when GitHub IPs are rate-limited by HN — retrigger once if only this test fails with a network error.
 
 ## Non-negotiables
 
-- Strict typing — no `any` (TS) or untyped functions (Python)
+- Strict typing — no `any` (TS)
 - Every new module must have tests
-- Reference `SPEC.md` for product requirements
-- Never cloud-sync credentials — local-only
+- No `console.log` in committed code (use `getLogger()` from `logger.ts`)
+- No hardcoded credentials — local-only, never committed
+- No new top-level folders without updating `ARCH.md`
+- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`
+- Every behavioral change needs a changeset (`pnpm changeset`) before merging to main
 
 ## How to work here
 
-- Small incremental commits with conventional messages
-- Update `.context/progress.md` after completing tasks
-- Update `.context/activeContext.md` when switching focus
-- Run `/status` to see current project state
-- Run `/plan` to decide what to work on next
-- Run `/review` before committing
+- `AGENTS.md` — durable workspace facts; read before starting a session
+- `ARCH.md` — file tree and component map
+- `.context/progress.md` — update after completing tasks
+- `browserkit doctor --config browserkit.config.js` — check adapter compatibility
 
 ## Forbidden patterns
 
-- No `any` types (TS) or untyped functions (Python)
+- No `any` types
 - No hardcoded credentials anywhere
-- No `console.log` in committed code (use proper logging)
-- No new top-level folders without updating ARCH.md
+- No `console.log` (use `log.info()` / `log.warn()` / `log.error()`)
+- No new top-level folders without updating `ARCH.md`
+- No pushing to main without verifying CI passes