browsertrack 0.1.0 → 0.1.1

package/dist/core/index.d.ts

@@ -1,5 +1,7 @@
 export { B as Breadcrumb, C as CaptureElementParams, a as CaptureElementResult, b as ClientCommand, c as ClientEventMessage, d as CommandResponse, e as CommandType, f as ConsoleEvent, g as ConsoleLevel, D as DOMRectJson, E as ElementContext, h as ElementStyleResult, i as ElementSummary, j as EventType, H as HelloMessage, N as NavigateParams, k as NavigationEvent, l as NetworkEvent, m as NoteStatus, n as NoteTarget, o as NoteType, p as NoteVerificationResult, O as OverflowCheckResult, P as PageStateResult, Q as QueryElementParams, q as QueryElementResult, R as RegionContext, r as ReloadParams, s as RuntimeErrorEvent, S as ScrollContext, V as ViewportContext, t as VisualNote } from '../notes-CBvN91Wf.js';
 export { I as Incident, a as IncidentOccurrence, b as IncidentSeverity, c as IncidentSource, d as IncidentStatus, P as ProbeResult, e as ProbeType, f as Project, S as Session, V as VerificationProbe, g as VerificationRecipe, h as VerificationResult } from '../projects-CY8ungMt.js';
+import { Rules } from '@visulima/redact';
+export { Rules, standardRules, redact as visulimaRedact } from '@visulima/redact';
 
 /**
  * Error fingerprinting and normalization utilities
@@ -35,11 +37,16 @@ declare function extractSourceFromStack(stack?: string): {
 declare function computeFingerprint(input: FingerprintInput): string;
 
 /**
- * Security and Redaction Utilities
+ * Security and Redaction Utilities powered by @visulima/redact
  */
+declare const REDACTED_PLACEHOLDER = "[REDACTED]";
 declare const SENSITIVE_KEY_PATTERNS: RegExp[];
 declare const SENSITIVE_QUERY_PARAMS: string[];
-declare const REDACTED_PLACEHOLDER = "[REDACTED]";
+/**
+ * Developer security rules for @visulima/redact
+ */
+declare const BROWSER_SECURITY_RULES: Rules;
+
 /**
  * Checks if a property name matches any sensitive pattern
  */
@@ -53,7 +60,8 @@ declare function redactUrl(rawUrl: string): string;
  */
 declare function redactHeaders(headers: Record<string, string>): Record<string, string>;
 /**
- * Deeply redacts sensitive keys from an object or array
+ * Deeply redacts sensitive keys and payload data from an object or array,
+ * leveraging @visulima/redact rules combined with BrowserTrack URL/header sanitizers.
  */
 declare function redactSensitiveData<T = any>(data: T, maxDepth?: number, currentDepth?: number): T;
 
@@ -75,4 +83,4 @@ declare function getSemanticSelector(element: HTMLElement | Element, options?: S
  */
 declare function truncate(str: string | undefined | null, maxLength?: number): string;
 
-export { type FingerprintInput, REDACTED_PLACEHOLDER, SENSITIVE_KEY_PATTERNS, SENSITIVE_QUERY_PARAMS, type SelectorOptions, computeFingerprint, extractSourceFromStack, getSemanticSelector, isSensitiveKey, normalizeErrorMessage, normalizeSourceFile, redactHeaders, redactSensitiveData, redactUrl, truncate };
+export { BROWSER_SECURITY_RULES, type FingerprintInput, REDACTED_PLACEHOLDER, SENSITIVE_KEY_PATTERNS, SENSITIVE_QUERY_PARAMS, type SelectorOptions, computeFingerprint, extractSourceFromStack, getSemanticSelector, isSensitiveKey, normalizeErrorMessage, normalizeSourceFile, redactHeaders, redactSensitiveData, redactUrl, truncate };

package/dist/core/index.js

@@ -1,4 +1,5 @@
 import {
+  BROWSER_SECURITY_RULES,
   REDACTED_PLACEHOLDER,
   SENSITIVE_KEY_PATTERNS,
   SENSITIVE_QUERY_PARAMS,
@@ -11,9 +12,12 @@ import {
   redactHeaders,
   redactSensitiveData,
   redactUrl,
-  truncate
-} from "../chunk-6A7FFDIB.js";
+  standardRules,
+  truncate,
+  visulimaRedact
+} from "../chunk-6VA7GBAO.js";
 export {
+  BROWSER_SECURITY_RULES,
   REDACTED_PLACEHOLDER,
   SENSITIVE_KEY_PATTERNS,
   SENSITIVE_QUERY_PARAMS,
@@ -26,6 +30,8 @@ export {
   redactHeaders,
   redactSensitiveData,
   redactUrl,
-  truncate
+  standardRules,
+  truncate,
+  visulimaRedact
 };
 //# sourceMappingURL=index.js.map

package/dist/daemon/index.d.ts

@@ -1,4 +1,4 @@
-import { S as StorageDB, b as ScreenshotStore, a as SessionManager, c as NotesEngine, V as VerificationEngine, N as NoteVerificationEngine } from '../engine-DKloFjvs.js';
+import { S as StorageDB, b as ScreenshotStore, a as SessionManager, c as NotesEngine, V as VerificationEngine, N as NoteVerificationEngine } from '../engine-CeT9URuN.js';
 import { c as ClientEventMessage } from '../notes-CBvN91Wf.js';
 import { I as Incident } from '../projects-CY8ungMt.js';
 import http from 'node:http';

package/dist/daemon/index.js

@@ -4,8 +4,8 @@ import {
   createDaemon,
   createHttpHandler,
   setupWebSocketServer
-} from "../chunk-ZLNGOOH2.js";
-import "../chunk-6A7FFDIB.js";
+} from "../chunk-SPCIROIU.js";
+import "../chunk-6VA7GBAO.js";
 import {
   NoteVerificationEngine,
   NotesEngine,
@@ -14,7 +14,7 @@ import {
   StorageDB,
   VerificationEngine,
   getDaemonConfig
-} from "../chunk-BSKNG4V7.js";
+} from "../chunk-ILRYKMME.js";
 export {
   BrowserTrackDaemon,
   IncidentEngine,

package/dist/{engine-DKloFjvs.d.ts → engine-CeT9URuN.d.ts}

@@ -70,8 +70,10 @@ declare class StorageDB {
     listNotes(options?: {
         projectId?: string;
         status?: NoteStatus;
+        route?: string;
         limit?: number;
     }): VisualNote[];
+    deleteNote(id: string): void;
     updateNoteStatus(id: string, status: NoteStatus): void;
     updateNote(id: string, updates: Partial<VisualNote>): void;
     insertNoteVerification(v: NoteVerificationResult): void;
@@ -103,6 +105,8 @@ declare class SessionManager {
     getActiveSessionForProject(projectId: string): Session | null;
     getAnyActiveSession(): Session | null;
     getActiveCount(): number;
+    broadcastToProject(projectId: string, message: any): void;
+    sendToSession(sessionId: string, message: any): void;
 }
 
 declare class NotesEngine {

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 export { B as Breadcrumb, C as CaptureElementParams, a as CaptureElementResult, b as ClientCommand, c as ClientEventMessage, d as CommandResponse, e as CommandType, f as ConsoleEvent, g as ConsoleLevel, D as DOMRectJson, E as ElementContext, h as ElementStyleResult, i as ElementSummary, j as EventType, H as HelloMessage, N as NavigateParams, k as NavigationEvent, l as NetworkEvent, m as NoteStatus, n as NoteTarget, o as NoteType, p as NoteVerificationResult, O as OverflowCheckResult, P as PageStateResult, Q as QueryElementParams, q as QueryElementResult, R as RegionContext, r as ReloadParams, s as RuntimeErrorEvent, S as ScrollContext, V as ViewportContext, t as VisualNote } from './notes-CBvN91Wf.js';
 export { I as Incident, a as IncidentOccurrence, b as IncidentSeverity, c as IncidentSource, d as IncidentStatus, P as ProbeResult, e as ProbeType, f as Project, S as Session, V as VerificationProbe, g as VerificationRecipe, h as VerificationResult } from './projects-CY8ungMt.js';
-export { FingerprintInput, REDACTED_PLACEHOLDER, SENSITIVE_KEY_PATTERNS, SENSITIVE_QUERY_PARAMS, SelectorOptions, computeFingerprint, extractSourceFromStack, getSemanticSelector, isSensitiveKey, normalizeErrorMessage, normalizeSourceFile, redactHeaders, redactSensitiveData, redactUrl, truncate } from './core/index.js';
+export { BROWSER_SECURITY_RULES, FingerprintInput, REDACTED_PLACEHOLDER, SENSITIVE_KEY_PATTERNS, SENSITIVE_QUERY_PARAMS, SelectorOptions, computeFingerprint, extractSourceFromStack, getSemanticSelector, isSensitiveKey, normalizeErrorMessage, normalizeSourceFile, redactHeaders, redactSensitiveData, redactUrl, truncate } from './core/index.js';
 export { BrowserTrackClient, getClient, init as initClient } from './client/index.js';
 export { BrowserTrackDaemon, createDaemon } from './daemon/index.js';
-export { c as createMcpServer } from './server-CN-se8td.js';
-import './engine-DKloFjvs.js';
+export { c as createMcpServer } from './server-Dd8NX2Mk.js';
+export { Rules, standardRules, redact as visulimaRedact } from '@visulima/redact';
+import './engine-CeT9URuN.js';
 import 'ws';
 import 'node:http';
 import '@modelcontextprotocol/sdk/server/index.js';

package/dist/index.js

@@ -2,12 +2,13 @@ import {
   BrowserTrackClient,
   getClient,
   init
-} from "./chunk-X7C5CHBO.js";
+} from "./chunk-SKCMT2DE.js";
 import {
   BrowserTrackDaemon,
   createDaemon
-} from "./chunk-ZLNGOOH2.js";
+} from "./chunk-SPCIROIU.js";
 import {
+  BROWSER_SECURITY_RULES,
   REDACTED_PLACEHOLDER,
   SENSITIVE_KEY_PATTERNS,
   SENSITIVE_QUERY_PARAMS,
@@ -20,13 +21,16 @@ import {
   redactHeaders,
   redactSensitiveData,
   redactUrl,
-  truncate
-} from "./chunk-6A7FFDIB.js";
+  standardRules,
+  truncate,
+  visulimaRedact
+} from "./chunk-6VA7GBAO.js";
 import {
   createMcpServer
-} from "./chunk-ANMR5WBH.js";
-import "./chunk-BSKNG4V7.js";
+} from "./chunk-G2Y3CXCY.js";
+import "./chunk-ILRYKMME.js";
 export {
+  BROWSER_SECURITY_RULES,
   BrowserTrackClient,
   BrowserTrackDaemon,
   REDACTED_PLACEHOLDER,
@@ -45,6 +49,8 @@ export {
   redactHeaders,
   redactSensitiveData,
   redactUrl,
-  truncate
+  standardRules,
+  truncate,
+  visulimaRedact
 };
 //# sourceMappingURL=index.js.map

package/dist/mcp/index.d.ts

@@ -1,7 +1,7 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-export { M as McpContext, a as McpServerOptions, c as createMcpServer, h as handleToolCall } from '../server-CN-se8td.js';
+export { M as McpContext, a as McpServerOptions, c as createMcpServer, h as handleToolCall } from '../server-Dd8NX2Mk.js';
 import '@modelcontextprotocol/sdk/server/index.js';
-import '../engine-DKloFjvs.js';
+import '../engine-CeT9URuN.js';
 import '../notes-CBvN91Wf.js';
 import '../projects-CY8ungMt.js';
 import 'ws';

package/dist/mcp/index.js

@@ -2,8 +2,8 @@ import {
   TOOLS,
   createMcpServer,
   handleToolCall
-} from "../chunk-ANMR5WBH.js";
-import "../chunk-BSKNG4V7.js";
+} from "../chunk-G2Y3CXCY.js";
+import "../chunk-ILRYKMME.js";
 export {
   TOOLS,
   createMcpServer,

package/dist/{server-CN-se8td.d.ts → server-Dd8NX2Mk.d.ts}

@@ -1,5 +1,5 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { S as StorageDB, a as SessionManager, V as VerificationEngine, N as NoteVerificationEngine } from './engine-DKloFjvs.js';
+import { S as StorageDB, a as SessionManager, V as VerificationEngine, N as NoteVerificationEngine } from './engine-CeT9URuN.js';
 
 interface McpContext {
     db: StorageDB;

package/docboot.config.js

@@ -0,0 +1,16 @@
+/** @type {import('docboot').DocbootConfig} */
+export default {
+  title: "BrowserTrack",
+  description: "Local browser diagnostics shared with coding agents through MCP",
+  docs: "./docs",
+  out: "./dist-docs",
+  theme: {
+    preset: "zinc",
+    defaultMode: "dark"
+  },
+  search: {
+    fuzzy: 0.2,
+    prefix: true,
+    maxResults: 10
+  }
+};

package/docs/cli.md

@@ -0,0 +1,51 @@
+---
+title: CLI Reference
+description: Command-line interface commands for daemon control, project tracking, error logs, and documentation
+order: 8
+---
+
+# CLI Reference 💻
+
+BrowserTrack provides a complete command-line interface for managing the daemon, tracked projects, and runtime errors.
+
+---
+
+## ⚡ Commands
+
+### Daemon Management
+```bash
+browsertrack start             # Start local daemon on http://127.0.0.1:7331
+browsertrack start --verbose   # Start with verbose message logging
+browsertrack stop              # Stop running daemon process
+browsertrack status            # Check status and connected browser sessions
+```
+
+### Project Registry
+```bash
+browsertrack projects          # List all tracked projects
+browsertrack project add <name> --origin <url> --path <path>
+```
+
+### Incident & Log Inspection
+```bash
+browsertrack errors            # List open runtime error incidents
+browsertrack errors --project <name>
+browsertrack clear             # Wipe stored logs, screenshots, and incidents
+```
+
+### MCP Integration
+```bash
+browsertrack mcp               # Start Model Context Protocol server over stdio
+```
+
+---
+
+## 📖 Documentation Commands (Docboot)
+
+To preview or build this documentation locally using [Docboot](https://github.com/litepacks/docboot):
+
+```bash
+npm run docs:dev     # Start live documentation server on http://localhost:3000
+npm run docs:build   # Build static production documentation to dist-docs/
+npm run docs:serve   # Preview production build locally
+```

package/docs/closed-loop-verification.md

@@ -0,0 +1,57 @@
+---
+title: Closed-Loop Verification
+description: Automated bug-fix verification, visual layout probes, before/after screenshot comparisons, and resolution verdicts
+order: 5
+---
+
+# Closed-Loop Verification 🔄
+
+BrowserTrack features an automated closed-loop verification engine for both runtime bug fixes and visual layout fixes.
+
+---
+
+## 🐞 Bug Fix Verification (`verify_incident`)
+
+When an agent fixes a code bug, it triggers `verify_incident`:
+
+1. **Browser Reload**: Reloads the active browser tab (or navigates to the incident route).
+2. **Error Monitoring**: Watches for the incident fingerprint during an observation window (e.g. 2000ms).
+3. **Probe Evaluation**: Evaluates custom verification probes:
+   - `no_incident`: Confirms zero runtime errors occurred.
+   - `element_exists`: Checks if a specific selector exists in the DOM.
+   - `element_visible`: Confirms the target is rendered and visible.
+   - `text_contains`: Asserts expected text content.
+   - `route_is`: Verifies current SPA route.
+4. **After Screenshot**: Automatically captures an after-fix screenshot.
+5. **Verdict**: Returns `VERIFIED`, `FAILED`, or `INCONCLUSIVE`.
+
+```typescript
+// Example MCP call
+await client.callTool("verify_incident", {
+  incidentId: "inc_19a31a28",
+  expect: [
+    { type: "no_incident" },
+    { type: "element_visible", selector: "#user-card" }
+  ]
+});
+```
+
+---
+
+## 📐 Layout & Visual Note Verification (`verify_note`)
+
+When an agent modifies CSS or HTML to resolve visual feedback, it triggers `verify_note`:
+
+1. **Target Element Inspection**: Queries element visibility, bounding rect, and computed styles.
+2. **Viewport Overflow Probe**: Checks if `rect.right > viewportWidth` or if container has unintended horizontal scroll.
+3. **Geometry Diff**: Calculates before vs after dimensional delta (`widthDiff`, `heightDiff`, `overflowFixed`).
+4. **After Screenshot**: Captures an updated visual snapshot.
+5. **Verdict & Auto-Resolution**: If all checks pass and overflow is eliminated, returns `VERIFIED`.
+
+```typescript
+// Example MCP call
+await client.callTool("verify_note", {
+  noteId: "note_30a89599",
+  observationWindowMs: 1000
+});
+```

package/docs/getting-started.md

@@ -0,0 +1,122 @@
+---
+title: Getting Started
+description: Installation, daemon setup, and browser client integration guide for BrowserTrack
+order: 2
+---
+
+# Getting Started 🚀
+
+Follow this guide to get BrowserTrack up and running in under 2 minutes.
+
+---
+
+## 1. Install & Start Daemon
+
+Install BrowserTrack globally via npm:
+
+```bash
+npm install -g browsertrack
+```
+
+Start the background diagnostics server:
+
+```bash
+browsertrack start
+```
+
+This will initialize the local server at `http://127.0.0.1:7331` (WebSocket bridge on `ws://127.0.0.1:7331`) and SQLite database at `~/.browsertrack/browsertrack.db`.
+
+---
+
+## 2. Connect Your Web Application
+
+Choose the integration method that best suits your tech stack:
+
+### Option A: Zero-Install Script Tag (Plain HTML / Vite / Next.js / Astro)
+
+Add the script tag to your root HTML or document layout:
+
+```html
+<script src="http://127.0.0.1:7331/client.js"></script>
+```
+
+> **Tip (Next.js / SSR)**: You can conditionally load this script tag only in development environments (`process.env.NODE_ENV !== 'production'`).
+
+### Option B: NPM Package (React / Vue / Svelte / Angular)
+
+Install the client package:
+
+```bash
+npm install -D browsertrack
+```
+
+Import the client in your main application entry point (e.g. `main.ts` or `src/index.tsx`):
+
+```typescript
+import 'browsertrack/client';
+```
+
+Or configure custom options programmatically:
+
+```typescript
+import { BrowserTrackClient } from 'browsertrack/client';
+
+const client = new BrowserTrackClient({
+  daemonUrl: 'ws://127.0.0.1:7331',
+  captureErrors: true,
+  captureConsole: true,
+  captureNetwork: true,
+  captureInteractions: true,
+  notes: {
+    enabled: true,
+    shortcut: 'Alt+Click',
+  },
+}).init();
+```
+
+---
+
+## 3. Configure Your IDE for MCP
+
+Add BrowserTrack MCP server to your AI editor configuration:
+
+### Antigravity (`~/.gemini/antigravity-ide/mcp_config.json`)
+```json
+{
+  "mcpServers": {
+    "browsertrack": {
+      "command": "browsertrack",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### Cursor (`~/.cursor/mcp.json`) & Claude Code
+```json
+{
+  "mcpServers": {
+    "browsertrack": {
+      "command": "npx",
+      "args": ["browsertrack", "mcp"]
+    }
+  }
+}
+```
+
+---
+
+## 4. Add Project Agent Guidelines
+
+Place an `AGENTS.md` file in the root of your project to instruct AI agents on how and when to use BrowserTrack tools:
+
+```markdown
+# AGENTS.md
+This project is integrated with BrowserTrack MCP. Always check `list_incidents` and `list_notes` when debugging runtime errors or fixing layout feedback. Use `verify_incident` and `verify_note` after making code changes.
+```
+
+---
+
+## 5. Verify the Connection
+
+Open your web application in any browser. You will see the floating BrowserTrack dock in the bottom-right corner with **Element**, **Region**, **Page**, and **Notes** controls!

package/docs/incidents-diagnostics.md

@@ -0,0 +1,61 @@
+---
+title: Incidents & Diagnostics
+description: Automatic error grouping, runtime crash diagnostics, network tracking, and interaction breadcrumbs
+order: 4
+---
+
+# Incidents & Diagnostics ⚠️
+
+BrowserTrack continuously captures runtime errors, unhandled promise rejections, console warnings/errors, failed network calls, and user interaction breadcrumbs.
+
+---
+
+## ⚡ Automatic Error Grouping (Incidents)
+
+Instead of overwhelming AI agents with duplicate errors, BrowserTrack uses intelligent fingerprinting:
+- Grouped by `errorType`, normalized message, and source file line/column.
+- Tracks `occurrences`, `firstSeen`, and `lastSeen` timestamps.
+- Captures stack traces, route, and surrounding DOM state.
+
+---
+
+## 🍞 User Interaction Breadcrumbs
+
+BrowserTrack maintains a bounded chronological timeline of events leading up to an error:
+- **User Clicks**: Target selector, tag, text, and timestamp.
+- **Form Focus/Blur**: Inputs engaged prior to crash (values are never recorded).
+- **SPA & Browser Navigation**: `history.pushState` and URL route changes.
+- **Console Logs**: `console.log`, `console.warn`, `console.error`.
+- **Network Requests**: Method, URL, status code, and duration.
+
+---
+
+## 🌐 Network Failure Tracking
+
+Failed HTTP requests (`4xx`, `5xx`, timeouts, and aborts) are captured with:
+- Request method and sanitized URL (sensitive query parameters redacted by `@visulima/redact`).
+- HTTP status code and response duration in ms.
+- Error status and aborted flags.
+
+---
+
+## 🤖 Diagnostics Workflow for Coding Agents
+
+```mermaid
+sequenceDiagram
+    participant Agent as AI Coding Agent
+    participant MCP as BrowserTrack MCP
+    participant Daemon as Local Daemon
+    participant Browser as Browser Client
+
+    Agent->>MCP: list_incidents({ status: "OPEN" })
+    MCP->>Daemon: Query incidents from SQLite
+    Daemon-->>Agent: Returns grouped incidents
+    Agent->>MCP: get_incident({ incidentId: "inc_xxx" })
+    MCP-->>Agent: Stack trace, source line, breadcrumbs, screenshot
+    Agent->>Agent: Modifies code to fix bug
+    Agent->>MCP: verify_incident({ incidentId: "inc_xxx" })
+    MCP->>Browser: Dispatches reload & executes probes
+    Browser-->>Daemon: Reports runtime status & captures screenshot
+    Daemon-->>Agent: Verdict (VERIFIED / FAILED)
+```

package/docs/index.md

@@ -0,0 +1,46 @@
+---
+title: Introduction
+description: Overview of BrowserTrack - local browser diagnostics bridge for AI coding agents via MCP
+order: 1
+---
+
+# BrowserTrack 🔍
+
+> **Local browser diagnostics shared with AI coding agents through Model Context Protocol (MCP).**
+
+BrowserTrack is a lightweight, framework-agnostic local development daemon and MCP bridge. It continuously captures browser runtime errors, unhandled promise rejections, console logs, network failures (4xx/5xx), user interaction breadcrumbs, live DOM snapshots, and visual design annotations—making them instantly accessible to AI coding assistants (Antigravity, Cursor, Claude Code, Windsurf) for autonomous debugging and closed-loop verification.
+
+---
+
+## ⚡ Why BrowserTrack?
+
+Traditional browser debugging with AI coding agents relies on manual copy-pasting of truncated error messages or sending cropped screenshots. BrowserTrack removes the human in the middle:
+
+- 🚀 **Real-time Diagnostics Pipeline**: Your browser communicates with the local daemon via WebSockets.
+- 🎯 **Visual Annotations & Notes**: Hold <kbd>Alt</kbd> and click any element (or drag a region) to leave notes with DOM context and screenshots directly for coding agents.
+- 📌 **Persistent On-Screen Markers**: Visual note pins appear directly on your web pages and can be inspected or resolved with a single click.
+- 🤖 **Closed-Loop Verification**: After an agent edits your code, it automatically reloads the browser, executes verification probes, checks for regressions, and captures before/after screenshots.
+- 🛡️ **Zero-Leak Security**: Integrated with `@visulima/redact` to automatically sanitize passwords, auth tokens, cookies, credit cards, and secret query parameters.
+
+---
+
+## 🏗️ Architecture Overview
+
+```mermaid
+graph TD
+    A[Browser Client<br>Vanilla / React / Vue / Vite] <-->|WebSocket ws://127.0.0.1:7331| B[Local Daemon<br>SQLite Storage + Verification Engine]
+    B <-->|Model Context Protocol / stdio| C[AI Coding Agents<br>Antigravity / Cursor / Claude Code]
+    B -->|Static Docs & Web UI| D[Local Dashboard / Dev Server]
+```
+
+---
+
+## 🚀 Quick Navigation
+
+- [Getting Started](./getting-started.md) — Quick installation and setup in under 2 minutes.
+- [Visual Notes & Annotations](./visual-notes.md) — Screen notes, region selection, and persistent markers.
+- [Incidents & Error Diagnostics](./incidents-diagnostics.md) — Ingest runtime errors, stack traces, and breadcrumbs.
+- [Closed-Loop Verification](./closed-loop-verification.md) — Automated bug-fix and layout verification.
+- [MCP Tool Reference](./mcp-reference.md) — Complete guide to all 16 MCP tools.
+- [Security & Redaction](./security-privacy.md) — Privacy architecture and `@visulima/redact` integration.
+- [CLI Reference](./cli.md) — Command-line interface usage.