barebrowse 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.1
+
+- README rewritten: no code blocks, full obstacle course table with mode column, two usage paths (MCP vs framework), mcprune credited, measured token savings, context.md as code reference
+- MCP auto-installer: `npx barebrowse install` detects Claude Desktop, Cursor, Claude Code and writes config
+- MCP config uses `npx barebrowse mcp` instead of local file paths (works for npm consumers)
+- CLI help updated with install command
+
 ## 0.2.0
 
 Agent integration release. MCP server, bareagent adapter, and interaction features that make barebrowse usable as a standalone tool or embedded browsing layer.

package/README.md

@@ -1,18 +1,26 @@
-# barebrowse
-
-**URL in, agent-ready snapshot out.** Zero dependencies. Uses your own browser.
+```
+  ~~~~~~~~~~~~~~~~~~~~
+  ~~~ .---------. ~~~
+  ~~~ | · clear | ~~~
+  ~~~ | · focus | ~~~
+  ~~~ '---------' ~~~
+  ~~~~~~~~~~~~~~~~~~~~
+
+  barebrowse
+```
 
-barebrowse gives autonomous agents eyes and hands on the web. It launches your installed Chromium, navigates to any page, and returns a pruned ARIA snapshot — a compact, semantic representation of what's on screen. The agent reads the snapshot, picks an element by ref, acts, and reads the next snapshot. Observe, think, act.
+> Your agent browses like you do -- same browser, same logins, same cookies.
+> Prunes pages down to what matters. 40-90% fewer tokens, zero wasted context.
 
-No Playwright. No bundled browser. No 200MB download. Just CDP over a WebSocket to whatever Chromium you already have.
+---
 
-## The idea
+## What this is
 
-LLMs don't need DOM. They need to know what's on the page and what they can interact with. That's exactly what the browser's accessibility tree provides — every heading, button, link, input, and landmark, structured semantically.
+barebrowse is agentic browsing stripped to the bone. It gives your AI agent eyes and hands on the web -- navigate any page, see what's there, click buttons, fill forms, scroll, and move on. It uses your installed Chromium browser (Chrome, Brave, Edge -- whatever you have), reuses your existing login sessions, and handles all the friction automatically: cookie consent walls, permission prompts, bot detection, GDPR dialogs.
 
-But raw ARIA trees are noisy. A typical page produces 50-100KB of ARIA data. Most of it is decorative wrappers, hidden elements, and structural noise. barebrowse includes a 9-step pruning pipeline (ported from [mcprune](https://github.com/nickvdyck/mcprune)) that strips 47-95% of tokens while keeping every interactive element and meaningful label. A page that costs $0.15 in tokens raw costs $0.02-0.08 pruned.
+Instead of dumping raw DOM or taking screenshots, barebrowse returns a **pruned ARIA snapshot** -- a compact semantic view of what's on the page and what the agent can interact with. Buttons, links, inputs, headings -- labeled with `[ref=N]` markers the agent uses to act. The pruning pipeline is ported from [mcprune](https://github.com/hamr0/mcprune) and cuts 40-90% of tokens compared to raw page output. Every token your agent reads is meaningful.
 
-The snapshot format uses `[ref=N]` markers on interactive elements. The agent says "click ref 8" and barebrowse scrolls the element into view, calculates coordinates, and dispatches real mouse events. No CSS selectors. No XPath. Just semantic refs from the ARIA tree.
+No Playwright. No bundled browser. No 200MB download. No broken dependencies. Zero deps. Just CDP over a WebSocket to whatever Chromium you already have.
 
 ## Install
 
@@ -20,204 +28,117 @@ The snapshot format uses `[ref=N]` markers on interactive elements. The agent sa
 npm install barebrowse
 ```
 
-Requires Node.js >= 22 and any installed Chromium-based browser (Chrome, Chromium, Brave, Edge, Vivaldi).
-
-## Quick start
-
-```javascript
-import { browse } from 'barebrowse';
-
-// One line. That's it.
-const snapshot = await browse('https://news.ycombinator.com');
-console.log(snapshot);
-```
-
-Output (pruned, ~50% smaller than raw):
-```
-- WebArea "Hacker News" [ref=1]
-  - link "Hacker News" [ref=4]
-  - link "new" [ref=7]
-  - link "past" [ref=9]
-  - link "comments" [ref=11]
-  ...
-  - link "Show HN: I built a thing" [ref=42]
-  - link "197 comments" [ref=45]
-```
+Requires Node.js >= 22 and any installed Chromium-based browser.
 
 ## Two ways to use it
 
-### 1. As a library (framework mode)
+### 1. MCP server -- for Claude Desktop, Cursor, Claude Code
 
-Import and call directly. You control the loop.
-
-**One-shot** — read a page and get the snapshot:
-
-```javascript
-import { browse } from 'barebrowse';
-
-const snapshot = await browse('https://example.com', {
-  mode: 'headless',      // 'headless' | 'headed' | 'hybrid'
-  cookies: true,         // inject cookies from your browser
-  prune: true,           // ARIA pruning (47-95% token reduction)
-  consent: true,         // auto-dismiss cookie consent dialogs
-});
 ```
-
-**Session** — navigate and interact across multiple pages:
-
-```javascript
-import { connect } from 'barebrowse';
-
-const page = await connect();
-await page.goto('https://duckduckgo.com');
-
-let snap = await page.snapshot();
-// Agent sees: combobox "Search" [ref=5]
-
-await page.type('5', 'barebrowse github');
-await page.press('Enter');
-await page.waitForNavigation();
-
-snap = await page.snapshot();
-// Agent sees search results with clickable refs
-
-await page.click('12');  // click first result
-await page.close();
-```
-
-### 2. As an MCP server
-
-For Claude Desktop, Cursor, Windsurf, or any MCP client.
-
-```bash
 npm install -g barebrowse
 npx barebrowse install
 ```
 
-That's it. `install` auto-detects Claude Desktop, Cursor, and Claude Code, and writes the MCP config for you. No manual JSON editing.
-
-If you prefer manual setup, add this to your MCP config:
-```json
-{
-  "mcpServers": {
-    "barebrowse": {
-      "command": "npx",
-      "args": ["barebrowse", "mcp"]
-    }
-  }
-}
-```
+That's it. `install` auto-detects your MCP client and writes the config. No manual JSON editing. Restart your client and you have 7 browsing tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`.
 
-This exposes 7 tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`. The LLM calls `goto` to navigate, `snapshot` to observe, and action tools to interact. Action tools return `'ok'` -- the LLM calls `snapshot` explicitly to see what changed.
+### 2. Framework -- for agentic automation
 
-**Same package, two entry points.** `npm install barebrowse` gives you both the library (`import { browse } from 'barebrowse'`) and the MCP server (`npx barebrowse mcp`). Pick whichever fits your setup.
+Import barebrowse in your agent code. One-shot reads, interactive sessions, full observe-think-act loops. Works with any LLM orchestration library. Ships with a ready-made adapter for [bareagent](https://www.npmjs.com/package/bare-agent) (9 tools, auto-snapshot after every action).
 
-## Three modes
+For code examples, API reference, and wiring instructions, see **[barebrowse.context.md](barebrowse.context.md)** -- the full integration guide.
 
-| Mode | Flag | What happens | Use for |
-|------|------|-------------|---------|
-| **Headless** | `mode: 'headless'` (default) | Launches a fresh Chromium, no UI | Scraping, reading, fast automation |
-| **Headed** | `mode: 'headed'` | Connects to your running browser via CDP port | Bot-detected sites, visual debugging |
-| **Hybrid** | `mode: 'hybrid'` | Tries headless first, falls back to headed if bot-blocked | General-purpose agent browsing |
+## Three modes
 
-Headed mode requires your browser running with `--remote-debugging-port=9222`.
+| Mode | What happens | Best for |
+|------|-------------|----------|
+| **Headless** (default) | Launches a fresh Chromium, no UI | Fast automation, scraping, reading pages |
+| **Headed** | Connects to your running browser on CDP port | Bot-detected sites, visual debugging, CAPTCHAs |
+| **Hybrid** | Tries headless first, falls back to headed if blocked | General-purpose agent browsing |
 
 ## What it handles automatically
 
-You don't need to write code for any of this:
-
-- **Cookie consent dialogs** — ARIA scan + jsClick across 7 languages (EN, NL, DE, FR, ES, IT, PT). Tested on 16+ sites.
-- **Permission prompts** — notifications, geolocation, camera, mic all auto-denied via CDP
-- **Login walls** — cookies extracted from your Firefox or Chromium profile, injected via CDP
-- **Off-screen elements** — scrolled into view before every click
-- **Bot detection** — stealth patches in headless (navigator.webdriver, plugins, chrome object)
-- **Profile locking** — unique temp dir per headless instance
-- **ARIA noise** — 9-step pruning pipeline strips decorative wrappers, hidden nodes, structural noise
-
-## connect() API reference
-
-| Method | Description |
+This is the obstacle course your agent doesn't have to think about:
+
+| Obstacle | How it's handled | Mode |
+|----------|-----------------|------|
+| **Cookie consent walls** (GDPR) | ARIA tree scan + jsClick accept button, 7 languages (EN, NL, DE, FR, ES, IT, PT) | Both |
+| **Consent in dialog role** | Detect `dialog`/`alertdialog` with consent hints, click accept inside | Both |
+| **Consent outside dialog** (BBC SourcePoint) | Fallback global button scan when dialog has no accept button | Both |
+| **Consent behind iframe overlay** | JS click via DOM.resolveNode bypasses z-index/overlay issues | Both |
+| **Permission prompts** (location, camera, mic) | Launch flags + CDP Browser.setPermission auto-deny | Both |
+| **Media autoplay blocked** | Autoplay policy flag on launch | Both |
+| **Login walls** | Cookie extraction from Firefox/Chromium, injected via CDP | Both |
+| **Pre-filled form inputs** | Select-all + delete before typing | Both |
+| **Off-screen elements** | Scrolled into view before every click | Both |
+| **Form submission** | Enter key triggers onsubmit | Both |
+| **Tab between fields** | Tab key moves focus correctly | Both |
+| **SPA navigation** (YouTube, GitHub) | SPA-aware wait: frameNavigated + loadEventFired | Both |
+| **Bot detection** (Google, Reddit) | Stealth patches (headless) + headed fallback with real cookies | Both |
+| **navigator.webdriver leak** | Patched before page scripts run: webdriver, plugins, languages, chrome object | Headless |
+| **Profile locking** | Unique temp dir per headless instance | Headless |
+| **ARIA noise** | 9-step pruning pipeline (ported from mcprune): wrapper collapse, noise removal, landmark promotion | Both |
+
+## What the agent sees
+
+Raw ARIA output from a page is noisy -- decorative wrappers, hidden elements, structural junk. The pruning pipeline (ported from [mcprune](https://github.com/hamr0/mcprune)) strips it down to what matters.
+
+| Page | Raw | Pruned | Reduction |
+|------|-----|--------|-----------|
+| example.com | 377 chars | 45 chars | 88% |
+| Hacker News | 51,726 chars | 27,197 chars | 47% |
+| Wikipedia (article) | 109,479 chars | 40,566 chars | 63% |
+| DuckDuckGo | 42,254 chars | 5,407 chars | 87% |
+
+Two pruning modes: **act** (default) keeps interactive elements and visible labels -- for clicking, typing, navigating. **read** keeps all text content -- for reading articles and extracting information.
+
+## Actions
+
+Everything the agent can do through barebrowse:
+
+| Action | What it does |
 |--------|-------------|
-| `goto(url)` | Navigate + wait for load + dismiss consent |
-| `snapshot()` | Pruned ARIA tree with `[ref=N]` markers |
-| `click(ref)` | Scroll into view + mouse click at element center |
-| `type(ref, text, opts?)` | Focus + insert text. `{ clear: true }` replaces existing. |
-| `press(key)` | Special key: Enter, Tab, Escape, Backspace, Delete, arrows, Space |
-| `scroll(deltaY)` | Mouse wheel. Positive = down, negative = up. |
-| `hover(ref)` | Move mouse to element center |
-| `select(ref, value)` | Set `<select>` value or click custom dropdown option |
-| `screenshot(opts?)` | Returns base64 PNG/JPEG/WebP |
-| `waitForNavigation()` | Wait for page load (SPA-aware) |
-| `waitForNetworkIdle()` | Wait until no pending requests for 500ms |
-| `injectCookies(url)` | Extract + inject cookies from your browser |
-| `cdp` | Raw CDP session escape hatch |
-| `close()` | Clean up everything |
-
-## bareagent integration
-
-barebrowse ships a tool adapter for [bareagent](https://github.com/nickvdyck/bareagent):
-
-```javascript
-import { Loop } from 'bare-agent';
-import { Anthropic } from 'bare-agent/providers';
-import { createBrowseTools } from 'barebrowse/bareagent';
-
-const provider = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
-const loop = new Loop({ provider });
-
-const { tools, close } = createBrowseTools();
-try {
-  const result = await loop.run(
-    [{ role: 'user', content: 'Find the top story on Hacker News' }],
-    tools
-  );
-  console.log(result.text);
-} finally {
-  await close();
-}
-```
+| **Navigate** | Load a URL, wait for page load, auto-dismiss consent |
+| **Snapshot** | Pruned ARIA tree with `[ref=N]` markers (40-90% token reduction) |
+| **Click** | Scroll into view + mouse click at element center |
+| **Type** | Focus + insert text, with option to clear existing content first |
+| **Press** | Special keys: Enter, Tab, Escape, Backspace, Delete, arrows, Space |
+| **Scroll** | Mouse wheel up or down |
+| **Hover** | Move mouse to element center (triggers tooltips, hover states) |
+| **Select** | Set dropdown value (native select or custom dropdown) |
+| **Screenshot** | Page capture as base64 PNG/JPEG/WebP |
+| **Wait for navigation** | SPA-aware: works for full page loads and pushState |
+| **Wait for network idle** | Resolve when no pending requests for 500ms |
+| **Inject cookies** | Extract from Firefox/Chromium and inject via CDP |
+| **Raw CDP** | Escape hatch for any Chrome DevTools Protocol command |
+
+## Tested against
+
+16+ sites across 8 countries, all consent dialogs dismissed, all interactions working:
+
+Google, YouTube, BBC, Wikipedia, GitHub, DuckDuckGo, Hacker News, Amazon DE, The Guardian, Spiegel, Le Monde, El Pais, Corriere, NOS, Bild, Nu.nl, Booking, NYT, Stack Overflow, CNN, Reddit
 
-`createBrowseTools(opts)` returns 9 tools: browse, goto, snapshot, click, type, press, scroll, select, screenshot. Action tools auto-return a fresh snapshot after each action so the LLM always sees the result.
+## Context file
 
-You can pass any `connect()` options to `createBrowseTools()` — mode, port, cookies, consent.
+**[barebrowse.context.md](barebrowse.context.md)** is the full integration guide. Feed it to an AI assistant or read it yourself -- it covers the complete API, snapshot format, interaction loop, auth options, bareagent wiring, MCP setup, and gotchas. Everything you need to wire barebrowse into a project.
 
 ## How it works
 
 ```
-URL -> chromium.js     find/launch browser, permission-suppressing flags
-    -> cdp.js          WebSocket CDP client, flattened sessions
-    -> stealth.js      navigator.webdriver patches (headless only)
-    -> Browser.setPermission    suppress all prompts
-    -> auth.js         extract cookies from Firefox/Chromium -> inject via CDP
-    -> Page.navigate   go to URL, wait for load
-    -> consent.js      detect + dismiss cookie consent dialogs
-    -> aria.js         Accessibility.getFullAXTree -> nested tree
-    -> prune.js        9-step pruning: wrappers, noise, landmarks
-    -> interact.js     click/type/scroll/hover/select via CDP Input domain
-    -> snapshot        agent-ready ARIA text with [ref=N] markers
+URL -> find/launch browser (chromium.js)
+    -> WebSocket CDP connection (cdp.js)
+    -> stealth patches before page scripts (stealth.js, headless only)
+    -> suppress all permission prompts (Browser.setPermission)
+    -> extract + inject cookies from your browser (auth.js)
+    -> navigate to URL, wait for load
+    -> detect + dismiss cookie consent dialogs (consent.js)
+    -> get full ARIA accessibility tree (aria.js)
+    -> 9-step pruning pipeline from mcprune (prune.js)
+    -> dispatch real input events: click/type/scroll (interact.js)
+    -> agent-ready snapshot with [ref=N] markers
 ```
 
 11 modules, 2,400 lines, zero dependencies.
 
-## Token savings
-
-Real-world measurements on the pruning pipeline:
-
-| Page | Raw ARIA | Pruned (act) | Reduction | Est. cost saved |
-|------|----------|-------------|-----------|----------------|
-| Hacker News | 52K chars | 27K chars | 47% | ~$0.04/call |
-| Wikipedia article | 180K chars | 12K chars | 93% | ~$0.25/call |
-| Amazon product | 95K chars | 8K chars | 92% | ~$0.13/call |
-| Google results | 45K chars | 5K chars | 89% | ~$0.06/call |
-
-Two pruning modes:
-- **act** (default) — keeps interactive elements + visible labels. For clicking, typing, navigating.
-- **read** — keeps all text content. For reading articles, extracting information.
-
-## Context file
-
-`barebrowse.context.md` in the repo root is an LLM-consumable integration guide. Feed it to an AI assistant that needs to wire barebrowse into a project — it covers the full API, snapshot format, interaction loop, auth options, and gotchas.
-
 ## Requirements
 
 - Node.js >= 22 (built-in WebSocket, built-in SQLite)

package/mcp-server.js

@@ -149,7 +149,7 @@ async function handleMessage(msg) {
     return jsonrpcResponse(id, {
       protocolVersion: '2024-11-05',
       capabilities: { tools: {} },
-      serverInfo: { name: 'barebrowse', version: '0.2.0' },
+      serverInfo: { name: 'barebrowse', version: '0.2.2' },
     });
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
   "type": "module",
   "main": "src/index.js",

package/.claude/memory/AGENT_RULES.md

@@ -1,251 +0,0 @@
-# AI Agent Collaboration Guide
-
-## Table of Contents
-1. [Communication Protocol](#communication-protocol)
-2. [Development Standards](#development-standards)
-3. [Testing Standards](#testing-standards)
-4. [Environment](#environment)
-5. [Development Workflow](#development-workflow)
-6. [Twelve-Factor Reference](#twelve-factor-reference)
-7. [CLAUDE.md Stub](#claudemd-stub)
-8. [AI Agent Instructions](#ai-agent-instructions)
-
----
-
-## Communication Protocol
-
-### Core Rules
-- **Clarity First**: Always ask clarifying questions when requirements are ambiguous
-- **Fact-Based**: Base all recommendations on verified, current information
-- **Simplicity Advocate**: Call out overcomplications and suggest simpler alternatives
-- **Safety First**: Never modify critical systems without explicit understanding and approval
-
-### User Profile
-- **Technical Level**: Non-coder but technically savvy
-- **Learning Style**: Understands concepts, needs executable instructions
-- **Expects**: Step-by-step guidance with clear explanations
-- **Comfortable with**: Command-line operations and scripts
-
-### Required Safeguards
-- Always identify affected files before making changes
-- Never modify authentication systems without explicit permission
-- Never alter database schema without proper migration files
-- Explain what changes will be made and why
-
----
-
-## Development Standards
-
-### Validate Before You Build
-
-- **POC everything first.** Before committing to a design, build a quick proof-of-concept (~15 min) that validates the core logic. Keep it stupidly simple — manual steps are fine, hardcoded values are fine, no tests needed yet
-- **POC scope:** Cover the happy path and 2-3 common edge cases. If those work, the idea is sound
-- **Graduation criteria:** POC validates logic and covers most common scenarios → stop, design properly, then build with structure, tests, and error handling. Never ship the POC — rewrite it
-- **Build incrementally.** After POC graduates, break the work into small, independent modules. Focus on one at a time. Each piece must work on its own before integrating with the next
-
-### Dependency Hierarchy
-
-Always exhaust the simpler option before reaching for the next:
-
-1. **Vanilla language** — Write it yourself using only language primitives. If it's <50 lines and not security-critical, this is the answer
-2. **Standard library** — Use built-in modules (`os`, `json`, `pathlib`, `http`, `fs`, `crypto`). The stdlib is tested, maintained, and has zero supply chain risk
-3. **External library** — Only when both vanilla and stdlib are insufficient. Must pass the checklist below
-
-### External Dependency Checklist
-
-Before adding any external dependency, all of these must be true:
-- **Necessity:** Can't reasonably implement this with stdlib in <100 lines
-- **Maintained:** Active commits in the last 6 months, responsive maintainer
-- **Lightweight:** Few transitive dependencies (check the dep tree, not just the top-level)
-- **Established:** Widely used, not a single-maintainer hobby project for production-critical code
-- **Security-aware:** For security-critical domains (crypto, auth, sanitization, parsing untrusted input), a vetted library is *required* — never roll your own
-
-### Language Selection
-
-- **Use widely-adopted languages only** — Python, JavaScript/TypeScript, Go, Rust. No niche languages unless the domain demands it
-- **Pick the lightest language that fits the domain:** shell scripts for automation, Python for data/backend/CLI, TypeScript for web, Go for systems/infra, Rust for performance-critical
-- **Minimize the polyglot tax.** Every language in the stack adds CI config, tooling, and onboarding friction. Do not add a new language for one microservice — use what's already in the stack unless there's a compelling reason
-- **Vanilla over frameworks.** Express over NestJS, Flask over Django, unless the project genuinely needs the framework's structure. Structure can always be added later; removing a framework is painful
-
-### Build Rules
-
-- **Open-source only.** Always use open-source solutions. No vendor lock-in
-- **Lightweight over complex.** If two solutions solve the same problem, use the one with fewer moving parts, fewer dependencies, and less configuration
-- **Every line must have a purpose.** No speculative code, no "might need this later", no abstractions for one use case
-- **Simple > clever.** Readable code that a junior can follow beats elegant code that requires a PhD to debug
-- **Containerize only when necessary.** Start with a virtualenv or bare metal. Docker adds value for deployment parity and isolation — not for running a script
-
-### Red Flags — Stop and Flag These
-- Over-engineering simple problems
-- Adding external dependencies for trivial operations
-- Frameworks where a library or stdlib would suffice
-- Vendor-specific implementations when open alternatives exist
-- Skipping POC validation for unproven ideas
-
----
-
-## Testing Standards
-
-### Rules
-
-**Test behavior, not implementation.** A test suite must give you confidence to refactor freely. If changing internal code (without changing behavior) breaks tests, those tests are liabilities, not assets.
-
-**Follow the Testing Trophy** (not the Testing Pyramid):
-- Few unit tests — only for pure logic, algorithms, and complex calculations
-- Many integration tests — the sweet spot; test real components working together
-- Some E2E tests — cover critical user journeys end-to-end
-- Static analysis — types and linters catch bugs cheaper than tests
-
-### When to Write Tests
-
-- **After the design stabilizes, not during exploration.** Do not TDD a prototype — you'll write 500 tests for code you delete tomorrow. First make it work (POC), then make it right (refactor + tests), then make it fast
-- **Write tests when the code has users.** If a function is called by other modules or exposed to users, it needs tests. Internal helpers that only serve one caller don't need their own test file
-- **Write tests for bugs.** Every bug fix must include a regression test that fails before the fix and passes after. This is the highest-value test you can write
-- **Write tests before refactoring.** Before changing working code, write characterization tests first to lock in current behavior, then refactor with confidence
-- **Do not write tests for glue code.** Code that just wires components together (calls A then B then C) is tested at the integration level, not unit level
-
-### TDD: When It Works and When It Doesn't
-
-- **TDD works for:** Pure functions, algorithms, parsers, validators, data transformations — anything with clear inputs and outputs
-- **TDD does not work for:** Exploring a design, building a POC, or unstable interfaces. Writing tests for unstable APIs creates churn and false confidence
-- **The rule:** You must understand what you're building before you TDD it. TDD is a design tool for known problems, not a discovery tool for unknown ones
-- **Red-green-refactor discipline:** If you do TDD, follow the cycle strictly. Write a failing test, write minimal code to pass, refactor. Do not write 20 tests then implement — that's front-loading waste
-
-### What Makes a Good Test
-
-- **Tests real behavior.** Call the public API, assert on observable output. Do not reach into internals
-- **Fails for the right reason.** A good test fails when the feature is broken, not when the implementation changes
-- **Reads like a spec.** Someone unfamiliar with the code must understand what the feature does by reading the test
-- **Self-contained.** Each test sets up its own state, runs, and cleans up. No ordering dependencies between tests
-- **Fast and deterministic.** Flaky tests erode trust. If a test depends on timing, network, or global state, fix that dependency
-
-### Anti-Patterns — Do Not Do These
-
-- **Mocking more than 60% of the test.** If most of the test is mock setup, you're testing mocks, not code. Use real implementations with `tmp_path`, `:memory:` SQLite, or test containers
-- **Smoke tests.** `assert result is not None` proves nothing. Assert on specific values, structure, or side effects
-- **Testing private methods.** If you need to test a private method, either it should be public or the public method's tests should cover it
-- **Mirroring implementation.** Tests that replicate the source code line-by-line break on every refactor and catch zero bugs
-- **Test-only production code.** Never add methods, flags, or branches to production code solely for testing. Use dependency injection instead
-
-### Test Organization
-
-- **Co-locate tests with packages:** `packages/<pkg>/tests/` not a root `tests/` directory. Each package owns its tests
-- **Separate by type:**
-  ```
-  packages/<pkg>/tests/
-    unit/           # Fast, isolated, mocked deps, <1s each
-    integration/    # Real DB, filesystem, multi-component, <10s each
-    e2e/            # Full workflows, subprocess calls, <60s each
-    conftest.py     # Shared fixtures for this package
-  ```
-- **One test file per module** (not per function). `test_auth.py` tests the auth module, not `test_login.py` + `test_logout.py` + `test_session.py`
-- **No duplicate test files.** Before creating a new test file, check if one already exists for that module
-
-### Markers and Signals
-
-| Marker | Purpose | CI Behavior |
-|--------|---------|-------------|
-| `@pytest.mark.slow` | Runtime > 5s | Run in full suite, skip in quick checks |
-| `@pytest.mark.ml` | Requires ML deps (torch, etc.) | Skip if deps not installed |
-| `@pytest.mark.real_api` | Calls external APIs | Skip in CI — run manually before release |
-
-**CI runs for fast signals:**
-- `pytest -m "not slow and not ml and not real_api"` — fast gate on every push (~30s)
-- `pytest` — full suite on PR merge or nightly
-- Package-level runs for targeted debugging: `pytest packages/core/tests/`
-
-### Coverage and Ratios
-
-- **Do not chase a coverage number.** 80% coverage with meaningless tests is worse than 40% with behavior-testing integration tests
-- **Cover the critical path first.** Data layer, auth, payment, core business logic — before helper utilities
-- **Coverage tells you what's NOT tested, not what IS tested.** High coverage with bad assertions is false confidence
-- **Delete tests that don't catch bugs.** If a test has never failed (or only fails on refactors), it's not providing value
-
-**Target ratio:** ~20% unit, ~60% integration, ~15% E2E, ~5% manual/exploratory
-
-### Test Tooling Standards
-
-- Use `tmp_path` for filesystem tests, `:memory:` or `tmp_path` SQLite for DB tests
-- Use dependency injection over `@patch` — it's more readable and survives refactors
-- Tests must be self-sufficient — no dependency on project directories, user config, or environment state
-- Use factories or builders for test data, not raw constructors with 15 arguments
-- Keep test fixtures close to where they're used. Shared fixtures in `conftest.py`, not a global test utilities package
-
----
-
-## Environment
-
-- **OS**: Fedora Linux (use `dnf` for packages, `systemctl` for services)
-- **Testing**: pytest (Python), Jest/Vitest (JS/TS), Playwright (browser automation)
-
----
-
-## Development Workflow
-
-### Environments
-- **Development**: Local machines
-- **Staging**: VPS with isolated database
-- **Production**: VPS with containerized setup
-
-### Deployment Strategy
-
-**Simple Projects:** `Local → GitHub → VPS (direct deployment)`
-
-**Complex Projects:** `Local → GitHub → GHCR → VPS (containerized)`
-
----
-
-## Twelve-Factor Reference
-
-The [Twelve-Factor App](https://12factor.net) methodology for modern, scalable applications:
-
-| # | Factor | Rule |
-|---|--------|------|
-| 1 | Codebase | One repo per app, multiple deploys from same codebase |
-| 2 | Dependencies | Explicitly declare and isolate all dependencies |
-| 3 | Config | Store config in environment variables, never in code |
-| 4 | Backing Services | Treat databases, caches, queues as attached resources |
-| 5 | Build, Release, Run | Strict separation between build, release, and run stages |
-| 6 | Processes | Run as stateless processes, persist state externally |
-| 7 | Port Binding | Apps are self-contained, export services via port binding |
-| 8 | Concurrency | Scale out via the process model, not bigger instances |
-| 9 | Disposability | Fast startup, graceful shutdown, idempotent operations |
-| 10 | Dev/Prod Parity | Keep dev, staging, and production as similar as possible |
-| 11 | Logs | Treat logs as event streams to stdout |
-| 12 | Admin Processes | Run admin/maintenance tasks as one-off processes |
-
----
-
-## CLAUDE.md Stub
-
-Copy this to any project's CLAUDE.md. These are mandatory rules, not suggestions.
-
-```markdown
-## Dev Rules
-
-**POC first.** Always validate logic with a ~15min proof-of-concept before building. Cover happy path + common edges. POC works → design properly → build with tests. Never ship the POC.
-
-**Build incrementally.** Break work into small independent modules. One piece at a time, each must work on its own before integrating.
-
-**Dependency hierarchy — follow strictly:** vanilla language → standard library → external (only when stdlib can't do it in <100 lines). External deps must be maintained, lightweight, and widely adopted. Exception: always use vetted libraries for security-critical code (crypto, auth, sanitization).
-
-**Lightweight over complex.** Fewer moving parts, fewer deps, less config. Express over NestJS, Flask over Django, unless the project genuinely needs the framework. Simple > clever. Readable > elegant.
-
-**Open-source only.** No vendor lock-in. Every line of code must have a purpose — no speculative code, no premature abstractions.
-
-For full development and testing standards, see `.claude/memory/AGENT_RULES.md`.
-```
-
----
-
-## AI Agent Instructions
-
-When working with this user:
-1. **Always verify** you understand the requirements before proceeding
-2. **Provide step-by-step** instructions with clear explanations
-3. **Include ready-to-run** scripts and commands
-4. **Explain the "why"** behind technical recommendations
-5. **Flag potential issues** before they become problems
-6. **Suggest simpler alternatives** when appropriate
-7. **Never modify** authentication or database schema without explicit permission
-8. **Always identify** which files will be affected by changes

package/.claude/settings.local.json

@@ -1,30 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(wc:*)",
-      "Bash(flatpak list)",
-      "WebSearch",
-      "Bash(tail:*)",
-      "Bash(grep:*)",
-      "Bash(rpm -qa)",
-      "Bash(node:*)",
-      "Bash(cp:*)",
-      "Bash(ls:*)",
-      "Bash(head:*)",
-      "Bash(which kwalletcli:*)",
-      "Bash(kwallet-query:*)",
-      "WebFetch(domain:github.com)",
-      "WebFetch(domain:raw.githubusercontent.com)",
-      "Bash(npm view:*)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(npm whoami:*)",
-      "Bash(npm pack:*)",
-      "Bash(npm publish:*)",
-      "Skill(git-commit)",
-      "Bash(python3:*)",
-      "Bash(printf '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}\\\\n{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}\\\\n' | timeout 5 node /home/hamr/PycharmProjects/barebrowse/mcp-server.js 2>/dev/null)",
-      "Bash(chmod +x:*)"
-    ]
-  }
-}