> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puggy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Flow reference

> Learn the main Puggy flows for recording sessions, reviewing evidence, generating AI reports, sharing sessions, and connecting integrations.

This page gives you the shortest useful path through the main Puggy workflows. For setup details, start with [Getting started](./getting-started).

## Before you start

You need:

* Access to a Puggy organization.
* The Puggy Chrome extension installed and signed in.
* A supported browser for the console.
* Admin access when configuring organization settings, integrations, AI providers, or API keys.

## Basic flow

1. Sign in to Puggy.
2. Select your organization.
3. Open the Chrome extension.
4. Record a full session or capture a screenshot-only session.
5. Open the uploaded session in the console.
6. Review the captured video, screenshots, console logs, network requests, interactions, and metadata.
7. Generate or edit a bug report and Playwright test script.
8. Share the session with a link, ticket, Slack message, or MCP client.

## Sign in

### Console

1. Open the Puggy console.
2. Choose the sign-in option.
3. Complete OAuth.
4. Select an organization or accept an invitation.

### Chrome extension

1. Open the extension popup.
2. Choose **Sign in with Google** or **Sign in with Microsoft**.
3. Complete OAuth.
4. Select the organization where new sessions should upload.

If you belong to multiple organizations, the extension stores the active organization for future recordings.

## Record a session

Before recording, choose:

* **Source**: current tab or window/screen.
* **Audio**: tab audio, microphone, both, or neither.
* **Options**: interaction capture and on-screen controls.
* **Accessibility capture**: available when enabled for the workspace.

To record:

1. Open the extension popup.
2. Choose **Record**.
3. Confirm the organization and capture options.
4. Click the primary record button.
5. Grant browser capture permission.
6. Reproduce the issue.
7. Stop recording from the popup, on-screen dock, or browser capture controls.

Puggy uploads the session in the background and opens a local session viewer so you can inspect evidence while upload finishes.

## Capture a screenshot-only session

Use screenshot-only capture when a static visual issue is enough.

1. Open the extension popup.
2. Choose **Screenshot**.
3. Choose **Visible area** or **Region**.
4. Capture the screenshot.
5. Annotate it if needed.
6. Create the session.

Screenshot-only sessions appear in the console with screenshot evidence and without video.

## Review sessions in the console

Open **Sessions** from your organization workspace.

You can:

* Select a session from the session list.
* Rename a session.
* Page through older sessions.
* Search and filter sessions from **Search Sessions**.
* Sort search results by created date, start time, duration, or title.

## Review session evidence

Open a session detail page to inspect:

* **Recording**: video playback with console and network timeline markers when available.
* **Screenshots**: captured screenshots and saved annotations.
* **Transcript**: video intelligence output when enabled.
* **Info**: metadata and linked tickets.
* **Console Logs**: captured browser logs, warnings, and errors.
* **Network Requests**: HAR-compatible request data.
* **Performance Metrics**: captured browser performance data.
* **User Interactions**: clicks, inputs, scrolls, and navigation events.
* **Accessibility**: findings when accessibility capture is enabled.

When video clipping is enabled, you can trim a long recording into a shorter clip.

## Generate AI output

Before generating AI output, configure an AI provider from **Integrations > AI Bug Report**.

Supported provider options in the console are:

* Claude
* OpenAI
* Gemini

After configuration:

1. Open a session.
2. Use the right panel.
3. Select **Bug Report** or **Test Script**.
4. Click the AI generate control.
5. Review and edit the result.
6. Save the result.

Bug reports help with triage. Test scripts generate Playwright-oriented reproduction code from captured interactions.

## Share a session

To create a public session link:

1. Open a session.
2. Click the share action.
3. Copy the generated link.

To revoke a link:

1. Open the session.
2. Open the share menu.
3. Choose **Revoke Share Link**.

Treat public share links as externally visible evidence links.

## Create tickets and messages

Before creating tickets, configure the provider from **Integrations**.

| Provider | Required credentials                                                     | Result                                        |
| -------- | ------------------------------------------------------------------------ | --------------------------------------------- |
| Jira     | Site URL, Atlassian email, API token                                     | Creates Jira issues linked to sessions        |
| GitHub   | Personal access token, optional default owner and destination repository | Creates GitHub issues linked to sessions      |
| ClickUp  | API token                                                                | Creates ClickUp tasks from sessions           |
| Slack    | Bot User OAuth token                                                     | Posts session links and summaries to channels |
| YouTrack | Base URL and permanent token                                             | Creates YouTrack issues linked to sessions    |

From a session, use **Create Ticket** in the right panel and choose the configured provider.

## Manage organization access

Admins can open **Organization Settings** to:

* Update the organization name.
* Invite members by email.
* Copy pending invite links.
* Revoke pending invitations.
* Change member roles.
* Remove members.

Invited users accept access from the `/invite/:token` link.

## Use API keys and MCP

API keys enable programmatic access and MCP clients.

1. Open **API Keys**.
2. Create an active key with the required scopes.
3. Copy the key when it is shown.
4. Open the **MCP** tab.
5. Copy the server URL and client configuration.

MCP clients authenticate with the `X-Puggy-API-Key` header.

The Puggy MCP server exposes these tools:

* `list_sessions`
* `search_sessions`
* `get_session`
* `get_session_debug_data`
* `get_session_files`

## Advanced use cases

### Debug with an AI agent

Use MCP when an agent needs real session evidence instead of a written summary. Ask the agent to list recent sessions, inspect the failing session, and use `get_session_debug_data` before proposing a fix.

### Create a reproducible test

Record with interaction capture enabled, open the session, generate a test script, then review selectors and assertions before adding it to your test suite.

### Send a validated report to your tracker

Generate a bug report, edit it for accuracy, save it, then create a ticket. Puggy sends the session context and report content to the configured integration.

## Troubleshooting

### Recording does not start

* Confirm browser capture permission.
* Try switching between current-tab and window/screen capture.
* Reload the target page and try again.

### Session does not appear in the console

* Confirm the extension is signed in.
* Confirm the correct organization is selected.
* Wait for upload progress to finish.
* Check the local session viewer for upload errors.

### AI generation fails

* Test the AI provider connection.
* Confirm provider quota or monthly Puggy AI credits are available.
* Try again with a shorter session if the evidence set is large.

### Ticket creation fails

* Re-test the integration connection.
* Confirm the token still has the required permissions.
* Confirm the target destination exists and your token can access it.

### MCP client cannot connect

* Confirm the API key is active.
* Confirm the client sends `X-Puggy-API-Key`.
* Confirm the MCP server URL is correct.
* Restart the MCP client after changing configuration.