barebrowse 0.2.2 → 0.3.1

package/cli.js

@@ -2,28 +2,192 @@
 /**
  * cli.js -- barebrowse CLI entry point.
  *
- * Usage:
- *   npx barebrowse mcp            Start the MCP server (JSON-RPC over stdio)
- *   npx barebrowse install        Auto-configure MCP in Claude Desktop / Cursor / Claude Code
- *   npx barebrowse browse <url>   One-shot browse, print snapshot to stdout
+ * Session commands:
+ *   barebrowse open [url] [flags]     Open browser session (daemon)
+ *   barebrowse close                  Close session + kill daemon
+ *   barebrowse status                 Check if session is running
+ *
+ * Navigation:
+ *   barebrowse goto <url>             Navigate to URL
+ *   barebrowse snapshot [--mode]      Get pruned ARIA snapshot → file
+ *   barebrowse screenshot [--format]  Take screenshot → file
+ *
+ * Interaction:
+ *   barebrowse click <ref>            Click element by ref
+ *   barebrowse type <ref> <text>      Type text into element
+ *   barebrowse fill <ref> <text>      Clear + type (replace content)
+ *   barebrowse press <key>            Press special key
+ *   barebrowse scroll <deltaY>        Scroll page
+ *   barebrowse hover <ref>            Hover over element
+ *   barebrowse select <ref> <value>   Select dropdown value
+ *
+ * Self-sufficiency:
+ *   barebrowse eval <expression>      Evaluate JS in page
+ *   barebrowse wait-idle [--timeout]  Wait for network idle
+ *   barebrowse console-logs           Dump console logs → file
+ *   barebrowse network-log            Dump network log → file
+ *
+ * Legacy / tools:
+ *   barebrowse browse <url> [mode]    One-shot browse (stdout)
+ *   barebrowse mcp                    Start MCP server (stdio)
+ *   barebrowse install [--skill]      Auto-configure MCP or install skill
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { homedir, platform } from 'node:os';
+import { fileURLToPath } from 'node:url';
 
-const cmd = process.argv[2];
+const args = process.argv.slice(2);
+const cmd = args[0];
 
-if (cmd === 'mcp') {
+// Hidden internal flag: --daemon-internal
+if (args.includes('--daemon-internal')) {
+  await runDaemonInternal();
+} else if (cmd === 'mcp') {
   await import('./mcp-server.js');
-
 } else if (cmd === 'install') {
   install();
+} else if (cmd === 'browse' && args[1]) {
+  await oneShot();
+} else if (cmd === 'open') {
+  await cmdOpen();
+} else if (cmd === 'close') {
+  await cmdProxy('close');
+} else if (cmd === 'status') {
+  await cmdStatus();
+} else if (cmd === 'goto' && args[1]) {
+  await cmdProxy('goto', { url: args[1], timeout: parseFlag('--timeout') });
+} else if (cmd === 'snapshot') {
+  await cmdProxy('snapshot', { mode: parseFlag('--mode') });
+} else if (cmd === 'screenshot') {
+  await cmdProxy('screenshot', { format: parseFlag('--format') });
+} else if (cmd === 'click' && args[1]) {
+  await cmdProxy('click', { ref: args[1] });
+} else if (cmd === 'type' && args[1] && args[2]) {
+  await cmdProxy('type', { ref: args[1], text: args.slice(2).filter(a => !a.startsWith('--')).join(' '), clear: hasFlag('--clear') });
+} else if (cmd === 'fill' && args[1] && args[2]) {
+  await cmdProxy('fill', { ref: args[1], text: args.slice(2).filter(a => !a.startsWith('--')).join(' ') });
+} else if (cmd === 'press' && args[1]) {
+  await cmdProxy('press', { key: args[1] });
+} else if (cmd === 'scroll' && args[1]) {
+  await cmdProxy('scroll', { deltaY: Number(args[1]) });
+} else if (cmd === 'hover' && args[1]) {
+  await cmdProxy('hover', { ref: args[1] });
+} else if (cmd === 'select' && args[1] && args[2]) {
+  await cmdProxy('select', { ref: args[1], value: args[2] });
+} else if (cmd === 'eval' && args[1]) {
+  await cmdProxy('eval', { expression: args.slice(1).join(' ') });
+} else if (cmd === 'wait-idle') {
+  await cmdProxy('wait-idle', { timeout: parseFlag('--timeout') });
+} else if (cmd === 'console-logs') {
+  await cmdProxy('console-logs', { level: parseFlag('--level'), clear: hasFlag('--clear') });
+} else if (cmd === 'network-log') {
+  await cmdProxy('network-log', { failed: hasFlag('--failed') });
+} else {
+  printUsage();
+}
+
+
+// --- Command implementations ---
+
+async function cmdOpen() {
+  const { startDaemon } = await import('./src/daemon.js');
+  const { isAlive } = await import('./src/session-client.js');
+  const outputDir = resolve('.barebrowse');
+
+  // Check for existing session
+  if (await isAlive(outputDir)) {
+    process.stdout.write('Session already running. Use `barebrowse close` first.\n');
+    process.exit(1);
+  }
+
+  const url = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
+  const opts = {
+    mode: parseFlag('--mode') || 'headless',
+    port: parseFlag('--port'),
+    cookies: !hasFlag('--no-cookies'),
+    browser: parseFlag('--browser'),
+    timeout: parseFlag('--timeout'),
+    pruneMode: parseFlag('--prune-mode') || 'act',
+    consent: !hasFlag('--no-consent'),
+  };
+
+  try {
+    const session = await startDaemon(opts, outputDir, url);
+    process.stdout.write(`Session started (pid ${session.pid}, port ${session.port})\n`);
+    if (url) process.stdout.write(`Navigated to ${url}\n`);
+    process.stdout.write(`Output dir: ${outputDir}\n`);
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(1);
+  }
+}
 
-} else if (cmd === 'browse' && process.argv[3]) {
+async function cmdStatus() {
+  const { readSession, isAlive } = await import('./src/session-client.js');
+  const outputDir = resolve('.barebrowse');
+  const session = readSession(outputDir);
+
+  if (!session) {
+    process.stdout.write('No session found.\n');
+    process.exit(1);
+  }
+
+  const alive = await isAlive(outputDir);
+  if (alive) {
+    process.stdout.write(`Session running (pid ${session.pid}, port ${session.port}, started ${session.startedAt})\n`);
+  } else {
+    process.stdout.write(`Session stale (pid ${session.pid} not responding). Run \`barebrowse close\` to clean up.\n`);
+    process.exit(1);
+  }
+}
+
+async function cmdProxy(command, cmdArgs) {
+  const { sendCommand, readSession } = await import('./src/session-client.js');
+  const { unlinkSync } = await import('node:fs');
+  const outputDir = resolve('.barebrowse');
+
+  try {
+    const result = await sendCommand(command, cmdArgs, outputDir);
+
+    if (!result.ok) {
+      process.stderr.write(`Error: ${result.error}\n`);
+      process.exit(1);
+    }
+
+    // Print result
+    if (result.file && result.count !== undefined) {
+      process.stdout.write(`${result.file} (${result.count} entries)\n`);
+    } else if (result.file) {
+      process.stdout.write(`${result.file}\n`);
+    } else if (result.value !== undefined) {
+      process.stdout.write(JSON.stringify(result.value) + '\n');
+    } else if (command === 'close') {
+      // Clean up session.json in case daemon didn't
+      const sessionPath = join(outputDir, 'session.json');
+      try { unlinkSync(sessionPath); } catch { /* already gone */ }
+      process.stdout.write('Session closed.\n');
+    } else {
+      process.stdout.write('ok\n');
+    }
+  } catch (err) {
+    if (command === 'close') {
+      // Daemon may have exited before responding — that's fine
+      const sessionPath = join(outputDir, 'session.json');
+      try { unlinkSync(sessionPath); } catch { /* already gone */ }
+      process.stdout.write('Session closed.\n');
+    } else {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exit(1);
+    }
+  }
+}
+
+async function oneShot() {
   const { browse } = await import('./src/index.js');
-  const url = process.argv[3];
-  const mode = process.argv[4] || 'headless';
+  const url = args[1];
+  const mode = args[2] || 'headless';
   try {
     const snapshot = await browse(url, { mode });
     process.stdout.write(snapshot + '\n');
@@ -32,28 +196,50 @@ if (cmd === 'mcp') {
     process.stderr.write(`Error: ${err.message}\n`);
     process.exit(1);
   }
+}
 
-} else {
-  process.stdout.write(`barebrowse -- CDP-direct browsing for autonomous agents
+async function runDaemonInternal() {
+  const { runDaemon } = await import('./src/daemon.js');
+  const opts = {
+    mode: parseFlag('--mode') || 'headless',
+    port: parseFlag('--port'),
+    cookies: !hasFlag('--no-cookies'),
+    browser: parseFlag('--browser'),
+    timeout: parseFlag('--timeout'),
+    pruneMode: parseFlag('--prune-mode') || 'act',
+    consent: !hasFlag('--no-consent'),
+  };
+  const outputDir = parseFlag('--output-dir') || resolve('.barebrowse');
+  const url = parseFlag('--url');
+  await runDaemon(opts, outputDir, url || undefined);
+}
 
-Usage:
-  barebrowse mcp                Start MCP server (JSON-RPC over stdio)
-  barebrowse install            Auto-configure MCP for Claude Desktop / Cursor / Claude Code
-  barebrowse browse <url>       One-shot browse, print ARIA snapshot
 
-As a library:
-  import { browse, connect } from 'barebrowse';
+// --- Flag parsing helpers ---
 
-As bareagent tools:
-  import { createBrowseTools } from 'barebrowse/bareagent';
+function parseFlag(name) {
+  // --name=value or --name value
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith(name + '=')) return args[i].slice(name.length + 1);
+    if (args[i] === name && args[i + 1] && !args[i + 1].startsWith('--')) return args[i + 1];
+  }
+  return undefined;
+}
 
-More: see README.md or barebrowse.context.md
-`);
+function hasFlag(name) {
+  return args.includes(name);
 }
 
+
 // --- MCP auto-installer ---
 
 function install() {
+  // Handle --skill flag
+  if (hasFlag('--skill')) {
+    installSkill();
+    return;
+  }
+
   const mcpEntry = {
     command: 'npx',
     args: ['barebrowse', 'mcp'],
@@ -62,10 +248,7 @@ function install() {
   const targets = detectTargets();
 
   if (targets.length === 0) {
-    console.log('No MCP clients detected. You can manually add this to your MCP config:\n');
-    console.log(JSON.stringify({ mcpServers: { barebrowse: mcpEntry } }, null, 2));
-    console.log('\nSupported clients: Claude Desktop, Cursor, Claude Code');
-    return;
+    console.log('No MCP clients detected.\n');
   }
 
   let installed = 0;
@@ -83,7 +266,6 @@ function install() {
 
       config.mcpServers.barebrowse = mcpEntry;
 
-      // Ensure parent dir exists
       const dir = join(target.path, '..');
       mkdirSync(dir, { recursive: true });
 
@@ -97,8 +279,28 @@ function install() {
 
   if (installed > 0) {
     console.log(`\nDone. Restart your MCP client to pick up the new server.`);
-    console.log('Tools available: browse, goto, snapshot, click, type, press, scroll');
   }
+
+  // Always print Claude Code hint (it uses `claude mcp add`, not JSON config)
+  console.log(`\nClaude Code: run this instead of install:`);
+  console.log(`  claude mcp add barebrowse -- npx barebrowse mcp\n`);
+}
+
+function installSkill() {
+  const thisDir = fileURLToPath(new URL('.', import.meta.url));
+  const src = join(thisDir, '.claude', 'skills', 'barebrowse', 'SKILL.md');
+
+  if (!existsSync(src)) {
+    console.error('SKILL.md not found in package. Reinstall barebrowse.');
+    process.exit(1);
+  }
+
+  const dest = join(homedir(), '.config', 'claude', 'skills', 'barebrowse', 'SKILL.md');
+  const destDir = join(dest, '..');
+  mkdirSync(destDir, { recursive: true });
+  copyFileSync(src, dest);
+  console.log(`Skill installed: ${dest}`);
+  console.log('Claude Code will now see barebrowse as an available skill.');
 }
 
 function detectTargets() {
@@ -116,7 +318,6 @@ function detectTargets() {
     claudeDesktop = join(home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json');
   }
   if (claudeDesktop) {
-    // Check if Claude Desktop dir exists (even if config doesn't yet)
     const dir = join(claudeDesktop, '..');
     if (existsSync(dir)) {
       targets.push({ name: 'Claude Desktop', path: claudeDesktop });
@@ -124,26 +325,11 @@ function detectTargets() {
   }
 
   // Cursor
-  let cursorDir;
-  if (os === 'darwin') {
-    cursorDir = join(home, '.cursor');
-  } else if (os === 'linux') {
-    cursorDir = join(home, '.cursor');
-  } else if (os === 'win32') {
-    cursorDir = join(home, '.cursor');
-  }
-  if (cursorDir && existsSync(cursorDir)) {
+  const cursorDir = join(home, '.cursor');
+  if (existsSync(cursorDir)) {
     targets.push({ name: 'Cursor', path: join(cursorDir, 'mcp.json') });
   }
 
-  // Claude Code (project-level .mcp.json in cwd)
-  const cwd = process.cwd();
-  const claudeCodePath = join(cwd, '.mcp.json');
-  // Only suggest if we're in a project directory (has package.json or .git)
-  if (existsSync(join(cwd, 'package.json')) || existsSync(join(cwd, '.git'))) {
-    targets.push({ name: 'Claude Code (this project)', path: claudeCodePath });
-  }
-
   return targets;
 }
 
@@ -154,3 +340,58 @@ function readJsonOrEmpty(path) {
     return {};
   }
 }
+
+
+// --- Usage ---
+
+function printUsage() {
+  process.stdout.write(`barebrowse -- CDP-direct browsing for autonomous agents
+
+Session:
+  barebrowse open [url] [flags]     Open browser session
+  barebrowse close                  Close session
+  barebrowse status                 Check session status
+
+  Open flags:
+    --mode=headless|headed|hybrid   Browser mode (default: headless)
+    --port=N                        CDP port for headed mode
+    --no-cookies                    Skip cookie injection
+    --browser=firefox|chromium      Cookie source browser
+    --timeout=N                     Navigation timeout in ms
+    --prune-mode=act|read           Default pruning mode
+    --no-consent                    Skip consent dismissal
+
+Navigation:
+  barebrowse goto <url>             Navigate to URL
+  barebrowse snapshot [--mode=M]    ARIA snapshot -> .barebrowse/page-*.yml
+  barebrowse screenshot [--format]  Screenshot -> .barebrowse/screenshot-*.png
+
+Interaction:
+  barebrowse click <ref>            Click element
+  barebrowse type <ref> <text>      Type text (--clear to replace)
+  barebrowse fill <ref> <text>      Clear + type
+  barebrowse press <key>            Press key (Enter, Tab, Escape, ...)
+  barebrowse scroll <deltaY>        Scroll (positive=down)
+  barebrowse hover <ref>            Hover element
+  barebrowse select <ref> <value>   Select dropdown value
+
+Debugging:
+  barebrowse eval <expression>      Run JS in page context
+  barebrowse wait-idle [--timeout]  Wait for network idle
+  barebrowse console-logs           Console logs -> .barebrowse/console-*.json
+  barebrowse network-log            Network log -> .barebrowse/network-*.json
+
+One-shot:
+  barebrowse browse <url> [mode]    Browse + print snapshot to stdout
+
+MCP:
+  barebrowse mcp                    Start MCP server (JSON-RPC over stdio)
+  barebrowse install                Auto-configure MCP for Claude Desktop / Cursor
+  barebrowse install --skill        Install SKILL.md for Claude Code
+
+As a library:
+  import { browse, connect } from 'barebrowse';
+
+More: see README.md or barebrowse.context.md
+`);
+}

package/docs/00-context/assumptions.md

@@ -0,0 +1,38 @@
+# barebrowse -- Assumptions & Constraints
+
+## Hard constraints
+
+| Constraint | Detail |
+|-----------|--------|
+| **Chromium-only** | CDP protocol. Covers Chrome, Chromium, Edge, Brave, Vivaldi, Arc, Opera (~80% desktop share). Firefox later via WebDriver BiDi. |
+| **Node >= 22** | Built-in WebSocket (`globalThis.WebSocket`), built-in SQLite (`node:sqlite`). No polyfills. |
+| **Linux first** | Tested on Fedora/KDE/Wayland. macOS/Windows cookie extraction paths exist in auth.js but are untested. |
+| **Zero required deps** | Everything uses Node stdlib. Vanilla JS, ES modules, no build step. |
+| **Not a server** | Library that agents import. MCP wrapper included, HTTP wrapper is DIY. |
+
+## Assumptions
+
+- **User has Chromium installed.** At least one of: chromium-browser, google-chrome, brave-browser, microsoft-edge. `chromium.js` searches common paths.
+- **Cookie extraction needs unlocked profile.** Chromium cookies are AES-encrypted with a keyring key (KWallet on KDE, GNOME Keyring on GNOME). Firefox cookies are plaintext SQLite and always accessible.
+- **Headed mode requires manual browser launch.** User must start their browser with `--remote-debugging-port=9222`. barebrowse connects to it -- does not launch it.
+- **Hybrid fallback needs a running headed browser.** If headless is bot-blocked, hybrid kills headless and connects to headed on port 9222. That browser must already be running.
+- **Cookies expire.** Cookie injection works for existing sessions, not new logins. For sites requiring fresh auth, headed mode with user interaction is the fallback.
+- **One page per connect().** Each `connect()` call creates one page. For multiple tabs, call `connect()` multiple times.
+
+## Known limitations
+
+| Limitation | Impact | Workaround |
+|-----------|--------|------------|
+| No Firefox/WebKit support | ~20% of desktop users can't use native browser | Use Chromium as the automation target, Firefox as cookie source |
+| No file upload | Can't interact with file inputs | Not yet implemented (`Input.setFiles` via CDP) |
+| No drag and drop | Can't use drag-based UIs | Not yet implemented |
+| No cross-origin iframes | Content inside iframes invisible to ARIA tree | Frame tree traversal via CDP (medium effort) |
+| No CAPTCHAs | Cannot solve challenge pages | Headed mode lets user solve manually |
+| Canvas/WebGL opaque | No ARIA representation | Needs screenshot + vision model |
+| macOS/Windows untested | Cookie paths exist but may not work | Linux-only for now |
+
+## Risks
+
+- **CDP is not a stable API.** Chrome team can change it across versions. Mitigation: we use well-established domains (Accessibility, Input, Page, Network, DOM) that rarely break.
+- **Cookie consent patterns evolve.** New consent frameworks may not be detected by `consent.js`. Mitigation: best-effort, opt-out with `{ consent: false }`.
+- **Stealth patches are an arms race.** Bot detection evolves. Mitigation: headed mode with real browser profile is the ultimate fallback.

package/docs/{blueprint.md → 00-context/system-state.md}

@@ -163,7 +163,7 @@ Every action returns a **pruned ARIA snapshot** -- the agent's view of the page
 
 ### Module table
 
-Eleven modules, 2,396 lines, zero required dependencies.
+Thirteen modules, zero required dependencies.
 
 | Module | Lines | Purpose |
 |---|---|---|
@@ -177,6 +177,8 @@ Eleven modules, 2,396 lines, zero required dependencies.
 | `src/consent.js` | 210 | Auto-dismiss cookie consent dialogs, 7 languages |
 | `src/stealth.js` | 51 | Navigator patches for headless anti-detection |
 | `src/bareagent.js` | 161 | Tool adapter for bareagent Loop |
+| `src/daemon.js` | ~230 | Background HTTP server holding connect() session for CLI mode |
+| `src/session-client.js` | ~60 | HTTP client to daemon (sendCommand, readSession, isAlive) |
 | `mcp-server.js` | 216 | MCP server (JSON-RPC 2.0 over stdio) |
 
 ---
@@ -254,11 +256,12 @@ Anti-detection for headless mode via `Page.addScriptToEvaluateOnNewDocument` (ru
 - `Permissions.prototype.query` -> notifications return 'prompt'
 - Applied automatically in headless mode
 
-### Tests -- 47+ passing
+### Tests -- 64 passing
 - 16 unit tests (pruning logic)
 - 7 unit tests (cookie extraction -- 2 skip when Chromium profile locked)
 - 5 unit tests (CDP client + browser launch)
 - 11 integration tests (end-to-end browse pipeline)
+- 10 integration tests (CLI session lifecycle: open/snapshot/goto/click/eval/console/network/close)
 - 15 integration tests (real-world interactions: data: URL fixture + live sites)
 
 ---
@@ -302,6 +305,26 @@ Raw JSON-RPC 2.0 over stdio. Zero SDK dependencies. `npm install barebrowse` the
 Action tools return `'ok'` -- agent calls `snapshot` explicitly (MCP tool calls are cheap to chain).
 Session tools share a singleton page, lazy-created on first use.
 
+### CLI session -- for coding agents + human devs
+
+Shell commands that output to disk. Coding agents (Claude Code, Copilot, Cursor) read output files with their file tools -- no tokens wasted in tool responses.
+
+```bash
+barebrowse open https://example.com    # Start daemon + navigate
+barebrowse snapshot                    # → .barebrowse/page-*.yml
+barebrowse click 8                     # Click element
+barebrowse console-logs                # → .barebrowse/console-*.json
+barebrowse close                       # Kill daemon + browser
+```
+
+Architecture: `open` spawns a detached child process running an HTTP server on a random localhost port. Session state stored in `.barebrowse/session.json`. Subsequent commands POST to the daemon. `close` sends shutdown, daemon calls `page.close()` + `process.exit(0)`.
+
+Full commands: open, close, status, goto, snapshot, screenshot, click, type, fill, press, scroll, hover, select, eval, wait-idle, console-logs, network-log.
+
+Self-sufficiency features (console/network capture, eval) let agents debug without guessing -- they see JS errors and failed requests directly.
+
+SKILL.md (`.claude/skills/barebrowse/SKILL.md`) teaches Claude Code the CLI commands. Install with `barebrowse install --skill`.
+
 ---
 
 ## Ecosystem
@@ -339,10 +362,12 @@ barebrowse/
 │   ├── interact.js    # Click, type, press, scroll, hover, select
 │   ├── consent.js     # Auto-dismiss cookie consent dialogs
 │   ├── stealth.js     # Navigator patches for headless anti-detection
-│   └── bareagent.js   # Tool adapter for bareagent Loop
+│   ├── bareagent.js   # Tool adapter for bareagent Loop
+│   ├── daemon.js      # Background HTTP server for CLI session
+│   └── session-client.js  # HTTP client to daemon
 ├── test/
 │   ├── unit/          # prune, auth, cdp tests
-│   └── integration/   # browse + interact tests (real sites)
+│   └── integration/   # browse, interact, cli tests
 ├── examples/
 │   ├── headed-demo.js # Interactive demo: Wikipedia → DuckDuckGo
 │   └── yt-demo.js     # YouTube demo: Firefox cookies → search → play video
@@ -352,7 +377,7 @@ barebrowse/
 │   ├── blueprint.md   # This file
 │   └── testing.md     # Test guide: pyramid, all 54 tests, CI strategy
 ├── mcp-server.js      # MCP server (JSON-RPC 2.0 over stdio)
-├── cli.js             # CLI entry: `npx barebrowse mcp` or `npx barebrowse browse <url>`
+├── cli.js             # CLI entry: session commands, MCP, browse, install
 ├── .mcp.json          # MCP server config for Claude Desktop / Cursor
 ├── barebrowse.context.md  # LLM-consumable integration guide
 ├── package.json

package/docs/00-context/vision.md

@@ -0,0 +1,52 @@
+# barebrowse -- Vision
+
+## What it is
+
+A standalone vanilla JavaScript library that gives autonomous agents authenticated access to the web through the user's own Chromium browser. One package, one import, three modes.
+
+```js
+import { browse } from 'barebrowse';
+const snapshot = await browse('https://any-page.com');
+```
+
+barebrowse handles: finding the browser, connecting via CDP, injecting cookies, navigating, extracting the ARIA accessibility tree, and pruning it down to what an agent actually needs. The output is a clean, token-efficient snapshot of any web page -- authenticated as the real user.
+
+## What it is NOT
+
+- **Not a framework.** No plugin system, no config files, no lifecycle hooks.
+- **Not Playwright.** No bundled browser, no cross-engine abstraction, no 200MB download.
+- **Not an agent.** No LLM, no planning, no orchestration -- that's bareagent's job.
+- **Not a scraper.** It browses as the user, not as a bot harvesting data.
+
+## The core insight
+
+The user already has a browser. It's already logged in. It already passes Cloudflare. Instead of fighting the web with headless stealth tricks, **use what's already there**.
+
+CDP (Chrome DevTools Protocol) lets us connect to any Chromium-based browser -- the same one the user browses with daily. We get their cookies, their sessions, their anti-detection posture, for free.
+
+## The problem it solves
+
+Every AI agent that needs to read or interact with the web hits the same walls:
+
+1. **Cloudflare / bot detection** -- headless browsers get blocked
+2. **Authentication** -- sites require login, OAuth, session cookies
+3. **Token bloat** -- raw DOM is 100K+ tokens; agents need ~5K
+4. **Two consumers, same need** -- research agents (read pages) and personal assistants (click/type) both need an authenticated browser, but existing tools force you to choose one path
+
+## The bare- ecosystem
+
+```
+bareagent  = the brain  (orchestration, LLM loop, memory, retries)
+barebrowse = the eyes + hands  (browse, read, interact with the web)
+```
+
+barebrowse is a library. bareagent imports it as a capability. barebrowse doesn't know about bareagent. bareagent doesn't know about CDP. Clean boundary. Each ships and tests independently.
+
+## Success criteria
+
+1. `browse(url)` returns a pruned ARIA snapshot of any page, authenticated as the user
+2. Zero heavy dependencies -- no Playwright, no Puppeteer, no bundled browser
+3. Works with any installed Chromium-based browser
+4. Headless for research, headed for interaction, hybrid for autonomous agents
+5. Plugs into bareagent as plain tool functions
+6. An agent using barebrowse + bareagent can autonomously research the web and act on pages