# Tugboat

> Tugboat is an embeddable beta-feedback widget for web apps. Drop in one <script> tag and testers can send annotated screenshots, screen recordings with voice narration, voice notes and text — each with console/network logs, environment metadata and a session replay attached automatically. Every submission gets a canonical number and a full activity/audit trail (with submission context + inline note/reply text) and internal team comments; managers can export a PDF audit report over any date range. Each submission is tagged with its capture device/OS (Android, iOS, Windows, macOS, Linux, or native app). Every tester gets a private status link to track and reply back (two-way), and those who opt in also get email updates; resolved fixes can auto-publish to the widget's What's New. Non-technical testers can be guided with structured prompts. Developers triage everything in a dashboard, publish a two-way changelog and a votable roadmap back into the widget, and push feedback to Jira.

## Install (2 minutes)

Add this before your closing </body> tag (any framework; no npm install):

    <script src="https://tugboatapp.com/widget.js" data-project-key="pk_your_key"></script>

Replace `pk_your_key` with the project key from the dashboard (Projects → Settings). A floating "Feedback" button appears immediately.

## Configuration

- Keyboard shortcut: add `data-hotkey="mod+shift+k"` (mod = Ctrl/⌘); `data-hotkey="none"` disables it.
- Manual trigger: set the project to "manual" mode in Settings and call `Tugboat.open()` from your own UI.
- Public API: `Tugboat.open()`, `Tugboat.close()`, `Tugboat.toggle()`, `Tugboat.identify({ plan, role, segments })`.
- Audience targeting: identify the user via `Tugboat.identify(...)` or `window.tugboatUser = {...}` before the script loads, then target changelog/roadmap posts by plan, role or segment.
- Privacy: session replays mask all inputs and auto-redact emails/phones/card numbers client-side. Mark regions with `data-tugboat-block` (never recorded) or `data-tugboat-mask` (text masked). Toggle auto-redaction per project in Settings → Privacy.
- Isolation: the widget renders inside a Shadow DOM (~22KB gzipped), so host CSS never leaks in or out.

## Capture types

- Screenshot — annotation editor (box/arrow/pen) opens on capture + optional voice note. Widget hides itself during capture.
- Screen recording — screen video with microphone narration mixed in.
- Voice note — quick audio explanation.
- Text note — written context.
- Optional emoji sentiment rating (😠🙁😐🙂😍) on every submission.
- Guided submissions (optional, per project): structured prompts ("What were you trying to do? / expected? / actually happened?") plus an optional "I'm reporting as…" persona dropdown, assembled into one clean note — helps non-technical testers give useful context.

## Triage, activity & reporting

- Canonical numbers: every submission is numbered per project (e.g. #42) for easy reference.
- Views & filters: an independent view control (Inbox / Archived / All) works alongside status, subject and signal filters (all stack), so archived items stay filterable by status. Status is editable on any row, including archived.
- Activity/audit trail: status/priority changes, tags, archive, Jira links, comments and replies are all logged with who + when — shown per submission and in a project-wide Activity tab. Every entry shows which submission it belongs to (number + subject/note), and note/reply text is shown inline.
- Internal team comments: team-only notes on a submission.
- Device tag: every submission shows the OS/device it came from — Android or iOS (mobile), Windows/macOS/Linux (desktop), or a native platform (iOS/Android app) — on the list, the detail view and next to the session replay.
- PDF audit report: export all activity over a date range from the Activity tab; includes columns Date, Ref, Submission (subject/note), Change (with full note/reply text) and By.

## Tester updates & two-way replies

- Instant status link: right after submitting, the widget "Thank you" screen shows every tester a private link to their report (/s/<token>) with a Copy button — bookmarkable, no email or account required.
- Opt-in: testers who leave an email can tick "Email me when there's an update" to also be emailed on replies/status changes.
- Public reply vs internal note: a public reply is shared with the tester (and emailed if opted in via Resend); internal notes stay team-only. Reports with no contact info allow internal notes only.
- Public status page: a secure tokenized page (/s/<token>) shows the tester their status and the public conversation, and lets them reply back into the dashboard.
- Auto-publish resolved fixes: optionally post a "Fixed:" entry to the widget's What's New whenever a submission is marked Resolved.

## Docs

- [Full documentation (machine-readable)](https://tugboatapp.com/llms-full.txt)
- [Docs site](https://tugboatapp.com/docs)