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).

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.

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.

4.3 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.

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 Test Reports

Assertions are evaluated automatically during playback after their assigned step. When playback completes, a Test Report displays pass/fail results for each assertion with details about what was expected versus what was found.

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 Reports

Export captured errors and steps 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
• Browser and page metadata

8.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.

8.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.

8.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.

9.1 Side Panel Layout

The Sentinel side panel is organized into collapsible sections:

9.2 Captured Keyboard Events

During recording, Sentinel captures these keyboard events:

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

10.1 Overview

Sentinel includes a Model Context Protocol (MCP) server that lets AI assistants (Claude Code, Cursor, Copilot, etc.) control the extension programmatically. The AI can record guides, capture errors, take screenshots, navigate pages, and read your source code—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.”
• “Record me logging in and export a step-by-step guide.”

The AI will call sentinel_status() to load your project context, read source files, navigate to your dev server, and use Sentinel tools to produce the output.

10.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.

10.3 MCP Tools Reference

10.4 Settings Tab

The Settings tab (gear icon) is the main control center for MCP. It has three relevant sections:

MCP Bridge

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

Project

The Project section gives the AI persistent context about your codebase. Set three fields:

All three fields are returned in sentinel_status() under project.name, project.path, and project.devUrl.

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, without global configuration.

Supported AI Tools

Lists all compatible AI clients (Claude Code, Claude Desktop, Cursor, VS Code Copilot, Codex). Click Install next to a tool to copy its config snippet to the clipboard, then paste it into the tool’s config file. A green check marks tools you have already set up. The Remove icon clears the installed state.

10.5 Troubleshooting MCP

10.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:

11.1 Project Structure

extension/
  src/
    types.ts                — Shared TypeScript interfaces
    background.ts           — Service worker (state, screenshots, routing)
    content.ts              — Content script (recording, playback, inspection)
    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 CRUD operations
      guideHtml.ts          — HTML generation for guides & reports
    hooks/
      useExtensionState.ts  — Reactive hook via chrome.storage.onChanged
    components/
      Header.tsx            — Logo + title + quick controls
      StatusBar.tsx         — State indicator
      RecordingControls.tsx — Start/Stop recording
      PlaybackControls.tsx  — Speed, step-by-step, progress
      StepList.tsx          — Live action list
      ExportButton.tsx      — Export HTML guide
      SessionManager.tsx    — Session CRUD UI
      AssertionBuilder.tsx  — Element inspector + assertions
      TestReport.tsx        — Pass/fail results table
      Footer.tsx            — Version info
  public/
    manifest.json           — MV3 manifest
  dist/                     — Production build output

11.2 Tech Stack

11.3 Chrome APIs

12.1 Common Issues

12.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.