hooserguide

Hooserguide turns Gherkin BDD specs into verified user manuals. An AI agent writes the workflow, Playwright executes it, and screenshots are annotated with boxes, arrows, numbers and letters. One command exports a pdfcn PDF, a responsive HTML handbook, Markdown and a JSON execution report.

Your existing agent supplies the reasoning. Hooserguide supplies repeatable browser execution, screenshot annotation and document generation. There is no embedded model, model subscription or API key to configure.

See the annotations

This is an actual screenshot from the included HooTasks demo. The account email is masked in both the original and annotated images.

After the workflow runs, a second screenshot shows the asserted result:

Related MCP server: AIQUAA Playwright MCP Server

See the finished guide

The HTML handbook includes chapter navigation, offline search, annotated/original image switching, prerequisites and callouts, mobile layout and print controls.

The same screenshots and legends are rendered through pdfcn's Forme components into a configurable A4 or Letter PDF, in portrait or landscape, with a cover, chapters, page numbers and readable slices for long screenshots.

Explore the complete example: ZIP bundle · PDF · Markdown · HTML source · Execution report · BDD feature.

Alignment and layout review

Version 0.2.1 corrects mobile viewport scaling, animation timing, overlapping reference badges and edge outlines. PDF captions paginate safely, and long screenshot slices keep annotation groups together where possible.

These are real browser regression captures comparing the pinned 0.2.0 implementation with the corrected renderer:

See the review evidence and remaining limits. Maintainers can reproduce this comparison with npm run review:gallery.

New in 0.8

• Authoring toolkit: source-located lint diagnostics, repair suggestions, chapter outlines, task/form/read-only templates and an editor workspace with snippets and schema completion.

• Richer prose: chapter-specific introductions and multiline instructions in HTML, Markdown and PDF.

• Two skill audiences: contributor development guidance and self-contained consumer author/review skills, with real install and package checks.

• Agent interfaces: searchable step discovery plus authoring lint and outline MCP tools.

New in 0.6

• Automatic Pages publishing: reusable GitLab Pages component and GitHub generation/Pages-upload actions.

• Verified static export with responsive HTML, PDF/ZIP downloads, sanitized evidence and success-only deployments.

• Full pipeline examples, packaged actions and agent guidance for live-site verification.

New in 0.5

• Responsive feature presentations: execute the same BDD scenarios on Desktop, Tablet and Mobile, with annotated screenshots next to each other or stacked.

• Shared CLI, MCP and GitLab selection, profile labels, responsive HTML, Markdown tables and PDF comparison overviews with readable device details.

• Evidence, failure handling, rebuilds, comparisons and bundles retain each screen's independent execution.

New in 0.4

• A reusable GitLab CI/CD component with typed inputs, readiness checks, browser/profile selection, PDF customization, portable ZIPs and failed-run artifacts.

• Dedicated Linux qualification jobs for Chromium, Firefox and WebKit, covering real workflows, saved-state assertions, high-DPI/masked captures, HTML controls, PDF export and cancellation.

The same high-DPI crop, privacy mask and reference arrow across the three engines:

New in 0.3

• Choose the workflows: Cucumber tag expressions, scenario-name filters and fail-fast with explicit skipped coverage.

• Explain the task: prerequisites and styled notes, tips and warnings in every export.

• Customize the manual: guide/product version, audience, summary, German/English labels and optional dates/contents.

• Choose PDF geometry: A4 or Letter, portrait or landscape and configurable margins, still powered by pdfcn.

• Set screenshot defaults: automatic letters/numbers, mark color, crop padding and full-page behavior with local overrides.

• Read offline: search chapters, switch masked raw/annotated screenshots and print the whole guide.

• Review changes: verified report inspection and run comparison distinguish prose, annotation and screenshot changes.

• Share one file: portable ZIP with regenerated manuals, verified masked screenshots and a hash manifest.

• Integrate agents: eleven MCP tools plus project and exact-run artifact resources; both skills cover the new workflow.

The offline reader adds these controls without external dependencies:

Prerequisites and tips render as clear chapter guidance:

A German Letter landscape export uses the same pdfcn pipeline:

Open the landscape example · See all customization options.

Screenshot and workflow features

• Focused screenshots: capture one form, panel or dialog with padding and aligned annotations.

• Automatic references: number or letter your marks, with explicit labels preserved and duplicates rejected.

• More BDD steps: form tables, uploads, hover, double-click, drag-and-drop, browser history and saved-state checks after reload.

• Named profiles: run desktop or mobile workflows with viewport, touch, scale factor, browser and color scheme settings.

• Evidence-only rebuilds: export again without interacting with the app; screenshot hashes and dimensions are checked first.

• Branding: customize the guide name, subtitle and accent color across HTML and pdfcn PDF.

• Agent discovery: list every step with examples via CLI or MCP, including documented custom plugins.

This detail view uses focus and automatically assigned A/B/C references. The blue reference and its legend keep the mark's configured color.

Try it in one minute

Requirements: Node.js 22 or newer and npm. No external app or credentials are needed for the demo.

git clone https://github.com/openhoo/hooserguide.git
cd hooserguide
npm ci
npx playwright install chromium
npm run demo

The demo starts a temporary local app, executes both workflows and prints paths to the generated handbook. Open the printed index.html or handbook.pdf.

Use it in your project

Install directly from GitHub; an npm registry release is not required:

npm install -D github:openhoo/hooserguide
npm exec playwright -- install chromium
npm exec hooserguide -- init docs/user-guide --base-url http://localhost:3000 --skills --editor

Edit the generated features/get-started.feature to match your app. Then:

npm exec hooserguide -- validate --config docs/user-guide/hooserguide.config.json
npm exec hooserguide -- run --config docs/user-guide/hooserguide.config.json

The --skills option installs authoring and review skills into your project's .agents/skills/. For programmatic agents add --json. For debugging add --headed. PDF is enabled by default; --no-pdf skips it.

Authoring toolkit

Open the generated hooserguide.code-workspace for step and chapter snippets, local schema completion, authoring tasks and source-located Problems. Existing projects can add it with hooserguide editor --config <config>.

hooserguide new "Change account settings" --template form --config docs/user-guide/hooserguide.config.json
hooserguide steps --search capture
hooserguide lint --config docs/user-guide/hooserguide.config.json
hooserguide outline --config docs/user-guide/hooserguide.config.json

• Write from templates: task, form and read-only chapters with introductions, prerequisites, instructions, assertions and annotated captures.

• Find and repair problems: collect errors across files and chapters with line numbers, repair hints and similar step suggestions. lint --strict also fails on editorial warnings; --json supplies structured feedback to agents and CI.

• Review coverage before execution: the outline shows prose, figures, prerequisites, source locations, planned profile counts and excluded chapters.

• Write longer instructions: Scenario descriptions introduce individual chapters; I explain: accepts multiline text docstrings.

Lint and outlines do not open the app or create execution evidence. Replace template placeholders using actual app labels, then validate and run the same selection. See the complete authoring workflow, including editor setup, examples, diagnostics and MCP/library interfaces.

Discover the supported steps or regenerate an existing guide without rerunning the app:

npm exec hooserguide -- steps --json
npm exec hooserguide -- run --config docs/user-guide/hooserguide.config.json --profile mobile
npm exec hooserguide -- build output/guides/run-<timestamp>-<id> --output output/rebuilt

See advanced workflows for focused captures, profiles and rebuilds, and customization for layout, guidance, workflow filters, comparison and sharing.

A small spec, a complete walkthrough

@manual
Feature: Create tasks
  Create work items and check the saved result.

  Scenario: Create your first task
    Given I open "/"
    When I fill "label=Task title" with "Prepare the launch checklist"
    And I click "role=button:Create task"
    Then "role=status:Task result" has text "Task created successfully."
    And I explain "Enter a task title, select Create task and check the confirmation."
    And I capture "Your saved task"
      """json
      {
        "marks": [
          { "target": "testid=task-list", "kind": "box", "label": "A", "caption": "Your new task." },
          { "target": "role=status:Task result", "kind": "both", "label": "1", "caption": "Successful save confirmation." }
        ]
      }
      """

Backgrounds, Scenario Outlines, Examples, tags and localized Gherkin keywords work through the official Cucumber parser. Built-in action phrases remain English. Domain-specific steps can reuse your application's helpers through local plugins.

Clean integration paths

Minimal MCP configuration:

{
  "mcpServers": {
    "hooserguide": {
      "command": "node",
      "args": [
        "/absolute/path/hooserguide/dist/cli.js",
        "mcp",
        "--config",
        "/absolute/path/project/hooserguide.config.json"
      ]
    }
  }
}

MCP exposes eleven tools: project status, searchable step discovery, authoring lint, guide outline, validation, generation, exact run inspection, verified screenshot inspection, rebuild, run comparison and ZIP packaging. Read-only project and run artifact resources support client context attachment. Both author-user-guide and review-user-guide prompts guide agents through the workflow. Save the returned runId and pin it when reviewing annotated/raw screenshots or rebuilding; selection survives restarts. Generation supports progress and cancellation. See MCP contracts and examples. The server stays attached to the project config selected at startup.

import { loadConfig, run } from '@openhoo/hooserguide';

const result = await run(await loadConfig('docs/user-guide/hooserguide.config.json'));
if (result.report.status !== 'passed') throw new Error('Guide generation failed');
console.log(result.artifacts.pdf);

See integration recipes for Codex configuration, custom steps, existing Playwright tests and CI.

Show a feature on Desktop, Tablet and Mobile

Execute the same scenario in multiple screen profiles and show the annotated results next to each other or stacked:

hooserguide validate --config hooserguide.config.json --profiles desktop,tablet,mobile --scenario "Create task"
hooserguide run --config hooserguide.config.json --profiles desktop,tablet,mobile --scenario "Create task" --screen-layout side-by-side

init supplies all three profiles. Try the self-contained example with npm run demo:responsive. Alternatively enable responsive in config:

{
  "responsive": {
    "profiles": ["desktop", "tablet", "mobile"],
    "layout": "side-by-side",
    "labels": { "desktop": "Desktop", "tablet": "Tablet", "mobile": "Mobile" }
  }
}

Every screen has its own BDD assertions, privacy masks and annotation coordinates. HTML comparison columns stack on narrow reader screens; Markdown exports a table; PDF adds a comparison overview and readable detail pages. Use --screen-layout stacked for individual views or change the presentation later with build. MCP and GitLab expose the same selection. See the responsive guide for configuration, evidence review and repeated workflow behavior.

Automatically publish to Pages

GitLab: add the Pages component after your generating job:

- remote: https://raw.githubusercontent.com/openhoo/hooserguide/0.8.3/templates/pages/template.yml
  inputs:
    generate-job: user-guide
    source: output/user-guide

Include deploy in your pipeline stages. This job uses GitLab 17.10+ and publishes on the default branch after successful generation.

GitHub: use the generation action and hand its exact output to the Pages action:

- uses: openhoo/hooserguide/actions/generate@0.8.3
  id: guide
  with:
    config: docs/user-guide/hooserguide.config.json
    profiles: desktop,tablet,mobile
- uses: openhoo/hooserguide/actions/pages@0.8.3
  with:
    run-directory: ${{ steps.guide.outputs.directory }}

A dependent deployment job uses actions/deploy-pages@v4 with Pages/OIDC permissions. Select GitHub Actions as the repository's Pages source. Both platforms publish only successful, verified output with masked screenshots and PDF/ZIP downloads. See complete Pages workflows for setup, inputs, app startup and exact live-site checks.

GitLab CI/CD component

Include the pinned template directly from GitHub:

include:
  - remote: https://raw.githubusercontent.com/openhoo/hooserguide/0.8.3/templates/generate/template.yml
    inputs:
      config: docs/user-guide/hooserguide.config.json
      browser: chromium
      base-url: http://127.0.0.1:3000
      wait-url: http://127.0.0.1:3000/health
      before-script:
        - npm ci
        - npm run start > /tmp/hooserguide-app.log 2>&1 &

The job exports PDF, HTML, Markdown, verified screenshots, a status summary and an optional portable ZIP. Failed workflows fail the job and preserve available evidence. Package installation is isolated from the app's dependencies, and uploads are scoped to the current job ID. Configure profiles, filters, page geometry, services, rules and dependencies through inputs. The GitLab guide covers native component includes after importing the repository into your GitLab instance, all inputs and artifact review. Hosting on GitHub does not register the component in GitLab's catalog.

Configuration

{
  "title": "My app — User guide",
  "baseURL": "http://localhost:3000",
  "features": ["features/**/*.feature"],
  "output": "output/guides",
  "tag": "@manual",
  "language": "en",
  "viewport": { "width": 1280, "height": 800 },
  "masks": ["testid=account-email"]
}

Paths are relative to the configuration file. Feature files are sorted and deduplicated. storageState accepts an existing local Playwright authentication state. browser supports chromium, firefox and webkit; install your selected browser first. See configuration and step reference, config schema capture schema and report schema.

Manual themes

Choose a preset for both HTML and PDF with manual.theme:

{
  "manual": { "theme": "midnight" },
  "branding": { "name": "Acme" }
}

hooserguide run --config hooserguide.config.json --theme forest
hooserguide build output/guides/<run> --output output/midnight --theme midnight

HTML readers can switch themes at the top of the handbook and download the PDF using the adjacent Download PDF button. The download also works without JavaScript when a PDF was generated. The selected theme is saved for that handbook path when browser storage is available. The configured theme also works without JavaScript. Browser printing uses a light palette; the downloadable PDF retains the configured theme. Switching the HTML theme does not regenerate the PDF. PDF contents entries are clickable and jump to the actual chapter headings, including when preceding content spans multiple pages. Chapter bookmarks also appear in the PDF reader’s navigation panel. manual.contents: false hides the contents list while keeping chapter bookmarks available.

Screenshots and their annotations retain their evidence colors in every theme. Markdown has no theme styling.

branding.accentColor keeps your exact brand color for decorative accents in all presets. HTML and PDF accent text use that color only when it meets 4.5:1 contrast on every text surface; otherwise they use the preset’s readable accent text. The built-in palettes use text contrasts of at least 4.5:1, with distinct control borders and keyboard focus indicators meeting at least 3:1. Library users can import manualThemeNames, manualThemes and resolveManualTheme to discover the presets.

What you get

output/guides/run-<timestamp>-<id>/
├── handbook.pdf                 pdfcn / Forme PDF
├── index.html                   Responsive standalone guide
├── handbook.md                  Portable Markdown
├── report.json                  Scenario and step evidence + image hashes
├── pdf-layout.json              Page count and PDF content audit
└── screenshots/
    ├── 01-01.png                Annotated screenshot
    ├── 01-01.raw.png            Masked original
    └── 01-01.overlay.svg        Reusable vector annotation layer

Each run has its own directory. All evidence readers reject contradictory success records, duplicate screenshot references and invalid annotation geometry. Direct renderers verify both PNG variants before exporting. Failed assertions, missing masks, ambiguous targets and undefined steps fail the run. A failed run retains available evidence and does not export a successful handbook. The tool never changes the page's content to draw annotations; a temporary stylesheet freezes motion for capture, and the annotations are composited onto the PNG.

Agent skills

Hooserguide provides two categories of agent skills:

Install consumer skills

From the application you want to document:

npx skills add openhoo/hooserguide --skill hooserguide-author hooserguide-review

Or install them while creating a guide with hooserguide init docs/user-guide --skills. This copies only the consumer skills into the guide project's .agents/skills/. Each skill carries its own references and UI metadata; no hooserguide source checkout is needed to use it. The skills installer supplies instructions, while the CLI and Playwright browsers are installed separately as shown in Use it in your project.

Use the contributor skill

The source checkout discovers hooserguide-development through the relative .agents/skills/hooserguide-development link. The canonical source is under skills/hooserguide-development. To install it through the same skills manager:

npx skills add openhoo/hooserguide --skill hooserguide-development

All three skills are plain Markdown with bundled references and can be used by other agent runtimes. npm run test:skills checks metadata, references and source discovery. npm run test:skills:install verifies a real fresh local Skills CLI installation; package smoke tests separately verify consumer initialization.

Development

npm ci
npx playwright install chromium firefox webkit
npm run check
npm test
npm run test:browsers
npm run build
npm run test:package

Tests exercise real browser coordinates and image pixels, privacy masks, scrolled pages, failing saved-state assertions, PDF rendering/text, Gherkin outlines, escaping, initialization and MCP. See CONTRIBUTING and the architecture notes.

Scope and limitations

• An agent writes the features using its own browser and file tools. Hooserguide executes declared workflows; it does not discover an application autonomously.

• Specs and step plugins are trusted local inputs. They can interact with and change the target app. Use workflows and accounts you are authorized to operate.

• Screenshots cover the workflows in your specs. Successful generation does not establish coverage of every application feature or durable persistence unless your steps assert it.

• Standard PDF fonts support common Latin text. Other scripts may require embedded fonts and a custom theme. Tagged PDF output is enabled; PDF/UA conformance is not claimed.

• Dynamic content can still move during capture. Use stable app states and assertions, then visually review the output. Very large full-page captures may hit browser/image limits.

License

Hooserguide is Apache-2.0. Vendored pdfcn components retain their MIT license and attribution. See LICENSE, NOTICE and third-party notices.