Sentinel User Guide

1.1 Prerequisites

• Node.js 18+ and npm installed on your system.
• A Chromium-based browser: Google Chrome 114+, Microsoft Edge, or Brave.

1.2 Build from Source

Open a terminal in the project root and run:

cd extension
npm install
npm run build

This creates the extension/dist/ folder containing the production-ready extension files.

1.3 Load in Your Browser

1. Open your browser and navigate to chrome://extensions/.
2. Enable Developer mode using the toggle in the top-right corner.
3. Click Load unpacked.
4. Select the extension/dist folder from this project.
5. Sentinel appears in your toolbar. Pin it for easy access.

1.4 Open the Side Panel

Click the Sentinel icon in your browser toolbar. The side panel opens alongside your current page and stays open while you interact with websites — unlike popups, it won't close when you click away.

2.1 Start a Recording

1. Open the Sentinel side panel by clicking its toolbar icon.
2. Click Start Recording in the header controls.
3. Interact with any website — clicks, typing, form submissions, keyboard shortcuts, and scrolling are all captured automatically.
4. Watch recorded steps appear live in the Steps tab as you work.
5. Click Stop Recording when finished.

2.2 What Gets Captured

2.3 Noise Reduction

Sentinel applies intelligent filtering to keep recordings clean and readable:

• Input debouncing — 800ms per element; only emits the final value on blur or timeout.
• Keyboard filtering — only special keys and modifier combos are recorded; regular typing is captured as input events.
• Click deduplication — clicks within 300ms of each other on the same element are merged.
• Layout container rejection — clicks on div, section, main, etc. are suppressed unless the element has a role, onclick, or tabindex.
• Scroll throttling — 1-second debounce with a 200px minimum distance threshold.
• Change events — removed entirely (redundant with debounced input).

2.4 Smart Selectors

Each recorded action stores multiple selector strategies for reliable playback:

• Primary selector — the most specific CSS selector (by ID, data-testid, aria-label, or nth-child path).
• Candidate selectors — alternative selectors ranked by confidence, used as fallbacks during playback.
• Target snapshot — element attributes (tag, text, role, classes) stored for heuristic recovery when all selectors fail.
• Selector confidence — a score indicating how reliable the primary selector is expected to be.

3.1 Save & Load

3.2 Rename & Delete

3.3 Storage

Sessions are stored in chrome.storage.local and persist across browser restarts. Storage is per-browser-profile — sessions are not synced across devices.

3.4 Session Tags & Metadata

Sessions can include additional metadata for organization and automation:

• Tags — label sessions with custom tags for filtering and grouping.
• Session kind — recording for standard sessions or suite for test suites.
• Export options — configure redaction profiles and diagnostic inclusion per session.
• Run stats — track pass/fail counts, flaky scores, and last run summaries across multiple playback runs.

4.1 Export an HTML Guide

Turn any recording into a polished, self-contained HTML document with screenshots:

1. Stop the current recording (or load a saved session).
2. Click Export HTML Guide.
3. A .html file downloads automatically.
4. Open it in any browser to see a step-by-step walkthrough with screenshots, selectors, and timestamps.

4.2 Guide Editor

Before exporting, refine your guide in the built-in editor. Click Edit Guide to open it in a new tab.

• Three-column layout — table of contents sidebar, step editor, and live preview.
• Edit step descriptions — rewrite auto-generated text to match your documentation style.
• Reorder or remove steps — drag steps or delete irrelevant ones.
• Live preview — see exactly how the exported guide will look as you edit, with contenteditable support.
• Guide title & intro — set a custom title and introductory paragraph for the exported guide.

4.3 Custom Sections

Insert custom sections between steps to add context and documentation:

Sections can be added via the guide editor UI or programmatically through the sentinel_edit_guide MCP tool.

4.4 Export Profiles

Choose an export profile to control what information is included in the generated guide:

4.5 Sharing Guides

Exported guides are completely standalone — no external dependencies, all images embedded as base64. Share them via email, Slack, your team wiki, or any file-sharing platform. Anyone with a web browser can open them.

5.1 Start Playback

1. Navigate to the page where the recording started.
2. Open the Sentinel side panel.
3. Choose a playback speed: 0.5x, 1x, 1.5x, 2x, or 4x.
4. Click Start Playback.

A progress bar shows the current step number and total steps. During playback, the target element is highlighted with a visual indicator.

5.2 Playback Controls

5.3 Step-by-Step Mode

Enable step-by-step mode to advance one action at a time. After each step executes, playback pauses and waits for you to click Next Step. This is useful for debugging workflows or demonstrating processes to others.

5.4 Selector Recovery

When a recorded element can't be found by its primary selector, Sentinel automatically attempts recovery:

1. Primary selector — the original CSS selector is tried first.
2. Candidate selectors — alternative selectors stored during recording are tried in confidence order.
3. Heuristic matching — the target snapshot (tag, text, role, attributes) is used to find the best match in the current DOM.
4. Failed — if no match is found after all strategies, the step is marked as failed in the test report.

Each step's resolution strategy is tracked (primary, candidate, heuristic, or failed) and included in playback metrics.

6.1 Adding Assertions

Add assertions to turn recordings into automated tests that validate your application's state.

1. Expand the Assertions panel in the side panel.
2. Click Inspect Element — hover over any element on the page to highlight it, then click to select.
3. Choose an assertion type from the dropdown.
4. Enter an expected value (if required) and click Add Assertion.

6.2 Assertion Types

6.3 Retry Logic

Assertions support configurable retry behavior for elements that appear asynchronously:

• retryMs — total retry window in milliseconds (e.g., 3000 = retry for up to 3 seconds).
• retryIntervalMs — interval between retry attempts (e.g., 200 = check every 200ms).

This is especially useful for SPAs where elements appear after async operations like API calls or route transitions.

6.4 Test Reports

Assertions are evaluated automatically during playback after their assigned step. When playback completes, a Test Report displays:

• Pass/fail status for each assertion with actual vs. expected values.
• Step resolution details — which selector strategy succeeded.
• Playback metrics — total duration, recovery warnings, confidence scores.

6.5 Flakiness Detection

When sessions are replayed multiple times, Sentinel tracks run statistics including pass/fail counts and computes a flaky score. Sessions with inconsistent results are flagged, helping you identify tests that need stabilization.

7.1 Captured Errors

Sentinel automatically captures JavaScript errors and network failures from the pages you're testing. View them in the Errors tab.

Errors are linked to the recording timeline, so you can see exactly when they occurred relative to your actions.

7.2 Issue Management

Captured errors can be promoted to issues with additional metadata:

• Severity levels — Critical, High, Medium, or Low priority.
• Issue types — bug or feature-request.
• Fingerprinting — each issue gets a unique fingerprint for duplicate detection.
• Step correlation — issues are linked to specific recorded steps by index.
• Manual entry — add bugs manually without relying on error tracking.

Manage issues in the Findings tab — update severity, edit descriptions, or delete resolved issues.

7.3 Issue Analysis

The sentinel_analyze_issues tool (available via MCP) performs intelligent analysis on your issue list:

• Duplicate detection — identifies issues with matching fingerprints or similar error messages.
• Clustering — groups related issues by error source, page URL, or selector patterns.
• Pattern recognition — detects recurring patterns like same-page errors, same-error-source issues, and error clusters.

7.4 Error Context

Each issue can include rich context captured at the time of the error:

• Network log — XHR/fetch requests captured around the error, including URLs, status codes, and timing.
• Console log — browser console output leading up to the error.
• JS errors — full stack traces with file, line, and column references.

Context is retrieved via sentinel_get_issue_context and included in exported reports.

7.5 Issue Reports

Export captured issues as a standalone issue report HTML document designed for sharing with developers. Reports include:

• Error messages and stack traces
• Steps to reproduce (from the recording)
• Screenshots at each step
• Network and console log context
• Browser and page metadata
• Severity and priority indicators

Custom reports can be generated via sentinel_export_custom_report using the block-based renderer for full layout control.

8.1 Creating Requests

Create feature requests tied to specific page elements. The feature request builder is available in the side panel:

1. Open the Feature Req panel in the Steps tab.
2. Click Inspect Element to select the relevant UI element.
3. Enter a title and description for the enhancement.
4. Set a priority level (Critical, High, Medium, or Low).
5. Click Submit — a screenshot is captured automatically and attached to the request.

8.2 Element Inspection

When inspecting an element for a feature request, Sentinel captures:

• CSS selector for the target element
• Element tag, classes, and attributes
• Current visual state (screenshot)
• Page URL and timestamp

This gives developers full context about where the enhancement should apply.

8.3 Exporting Requests

Feature requests are exported alongside bug reports in the issue report. They appear with a distinct "Feature Request" label and include the inspection screenshot and element context. Via MCP, use sentinel_save_issue with type: "feature-request".

9.1 Creating Notes

Manual notes allow you to document observations that aren't tied to a specific recorded action. Access the Notes tab from the bottom navigation bar.

• Click New Note to start a draft.
• Notes are persistent and saved automatically as you type, even if you switch tabs.
• Port tools: Attach screenshots or create bug reports directly from the note editor.

9.2 Tagging & Organization

Organize your documentation with custom tags. Type a tag (e.g., #regression) in the tag input field and press Enter. You can filter the note list by clicking these tags in the main Notes view.

9.3 Annotation Editor

Sentinel includes a professional PowerPoint-style annotation suite for screenshots and captured video frames:

• Selection: Use the select tool to drag shapes or resize them using the corner handles.
• Shapes: Pen, Rectangle, and Arrow tools for visual highlighting.
• Highlight: A semi-transparent brush for non-obscuring emphasis.
• In-Place Text: Double-click any text or arrow-text element to edit content directly on the canvas.
• Font Controls: Real-time sliders for font size and stroke width.

9.4 Layer Management

The right-hand panel manages your annotation layers:

• Z-Ordering: Drag and drop layers in the list to move them behind or in front of other shapes.
• Deletion: Click the trash icon on a layer to remove specific annotations.
• Grouping: Mark layers as grouped for better visual organization in the sidebar.

10.1 Project Management

Organize your work into Workspaces (Projects). Each workspace tracks its own set of notes, findings, and resources.

• Define local source paths and dev server URLs per project.
• Switch the active project from the dropdown in the header bar.
• Manage all workspaces from the dedicated Workspaces tab.

10.2 Resource Gallery

The Resources tab provides a centralized gallery of all project assets:

• Screenshots: Every annotated or captured screenshot in the workspace.
• Videos: All recorded video feed clips.
• Findings: Quick links to bugs and feature requests.

10.3 Quick Actions

Hover over any card in the Resource Gallery to access one-click actions: Open Full Preview, Rename, Download, or Delete.

11.1 Capture a Video

Click Record Video in the header controls to start a screen capture of the active browser tab. The recording runs alongside step recording — you can capture both simultaneously.

• Video is encoded as WebM (VP9/VP8 codec) at 1 Mbps.
• Maximum recording duration is 5 minutes per clip.

11.2 Managing Clips

View all recorded clips in the Videos tab. Each clip shows a thumbnail preview. Click any clip to enlarge it in a modal viewer.

11.3 Limitations

Video clips are stored as blob URLs in memory and are not persisted across browser restarts. Export or download clips before closing the browser if you need to keep them.

12.1 Side Panel Layout

The Sentinel side panel is organized into tabs and collapsible sections:

12.2 AI Activity Log

The AI tab displays a real-time log of all MCP tool invocations from connected AI assistants. Each entry shows:

• Tool name and timestamp
• Command parameters
• Success/error status and duration

This is useful for debugging AI automation workflows and understanding what the AI is doing at each step.

12.3 Keyboard Events

During recording, Sentinel captures these keyboard events:

Regular character typing is captured as text input events (debounced), not individual key presses.

13.1 Overview

Sentinel includes a Model Context Protocol (MCP) server with 50+ tools that let AI assistants (Claude Code, Cursor, Copilot, etc.) control the extension programmatically. The AI can navigate pages, query elements, record guides, track errors, take and compare screenshots, drag-and-drop, manage sessions, and generate custom reports — all in a single conversation.

Once configured, you can give the AI high-level instructions like:

• “Perform the task addition flow and write a guide.”
• “Evaluate task addition for JS errors.”
• “Compare screenshots before and after my CSS changes.”
• “Find all buttons on the page and test each one.”

13.2 Setup & Installation

There are two ways to run the MCP server. Option A (recommended) lets you start and stop it with a button inside the extension. Option B is the manual terminal fallback.

Option A — Start/Stop from the Settings tab (recommended)

1. Install Python dependencies (once):

   pip install -r mcp-server/requirements.txt

2. Register the native launcher (once). Open the Sentinel Settings tab → MCP Bridge. If the launcher is not yet installed you will see an amber banner with your exact command — copy and run it:

   python mcp-server/install_host.py <your-extension-id>

   The extension ID is shown in the banner and has a Copy button. After running the command, reload the extension in chrome://extensions/.
3. From now on, use the Start and Stop buttons in the Settings tab to control the server — no terminal needed.
4. Configure your AI client. In the Supported AI Tools section, click Install next to your tool to copy the correct config snippet, then paste it into the tool’s config file.

Option B — Manual terminal

1. Install dependencies (once):

   pip install -r mcp-server/requirements.txt

2. Start the server:

   python mcp-server/sentinel_mcp.py

3. Keep the terminal open while using AI tools. Open the Sentinel side panel in Chrome and check for the green Connected badge.

13.3 MCP Tools Reference

Sentinel provides 50+ MCP tools organized into categories:

Navigation & Page Interaction

Element Querying

Actions & Input

Recording & Sessions

Guide & Report Generation

Error Tracking & Issues

Network & Console Monitoring

One-Shot Workflows

13.4 Settings & Projects

The Settings tab (gear icon) is the main control center for MCP and project management.

MCP Bridge

Shows the server name, live WebSocket status badge, and process controls.

Multi-Project Manager

Sentinel supports multiple projects, each with its own configuration. Use the project manager to:

• Add projects — create new project profiles with name, source folder, and dev server URL.
• Switch projects — click any project to make it active. The AI receives the active project's context via sentinel_status().
• Edit or delete — update project details or remove projects you no longer need.

Each project configuration includes:

Install MCP locally — once you have set a Source Folder, this button writes a .mcp.json to that folder pointing to the Sentinel MCP server. This lets any AI tool that starts from that project directory pick up the server automatically.

Supported AI Tools

Lists all compatible AI clients. Click Install next to a tool to copy its config snippet to the clipboard, then paste it into the tool’s config file.

13.5 Troubleshooting MCP

13.6 AI Workflow Examples

Once your project is configured in Settings, the AI loads context automatically via sentinel_status() and can act on high-level instructions. Here are common patterns:

14.1 Project Structure

extension/
  src/
    types.ts                — Shared TypeScript interfaces
    background.ts           — Service worker (state, screenshots, routing, AI logging)
    content.ts              — Content script (recording, playback, inspection, element querying)
    App.tsx                 — Main React shell
    main.tsx                — React entry point
    index.css               — Tailwind CSS entry
    editor.tsx              — Guide editor entry point
    EditorApp.tsx           — Guide editor React app
    lib/
      messages.ts           — Typed message bus
      storage.ts            — Session & project CRUD operations
      guideHtml.ts          — HTML generation for guides, reports & block rendering
    hooks/
      useExtensionState.ts  — Reactive hook via chrome.storage.onChanged
      useGuideEditor.ts     — Guide editor state management
      useVideoRecorder.ts   — Video recording hook
    components/
      Header.tsx            — Logo, title, status pills, quick controls
      StepList.tsx          — Live action list
      ErrorFeed.tsx         — Captured errors display
      ErrorBoundary.tsx     — React error boundary
      IssueList.tsx         — Bug tracker & findings panel
      FeatureRequestBuilder.tsx — Feature request builder
      AiLog.tsx             — AI activity log
      AssertionBuilder.tsx  — Element inspector & assertions
      TestReport.tsx        — Pass/fail results & playback metrics
      SessionManager.tsx    — Session CRUD UI
      SettingsPanel.tsx     — MCP bridge, project manager, AI tool config
      PlaybackControls.tsx  — Speed, step-by-step, progress
      NoteModule.tsx        — Notes list, filtering, and management
      NoteEditor.tsx        — Rich note editor with attachments and video
      ProjectModule.tsx     — Multi-project workspace manager
      ResourceModule.tsx    — Centralized resource gallery (screenshots, videos, findings)
      GuideEditor.tsx       — Guide editor component
      GuidePreview.tsx      — Live guide preview
      GuideStepEditor.tsx   — Individual step editing
      BugTracker.tsx        — Bug tracking panel
      Footer.tsx            — Version info
  public/
    manifest.json           — MV3 manifest
    page-error-bridge.js    — MAIN world script for capturing page-level errors
  dist/                     — Production build output

mcp-server/
  sentinel_mcp.py           — MCP server (50+ tools)
  launcher.py               — Native messaging launcher
  install_host.py           — Native host registration script
  requirements.txt          — Python dependencies

14.2 Tech Stack

14.3 Chrome APIs

15.1 Common Issues

15.2 Development Workflow

1. Edit source files in extension/src/.
2. Run npm run build (or use npm run dev for watch mode).
3. Open chrome://extensions/ and click the reload icon on the Sentinel card.
4. Click the toolbar icon to reopen the side panel with your changes.