# Pipeup

> Pipeup lets people comment on any HTML file (documents, slide decks, whole sites) right on the page, with no accounts or servers. Comments are kept in each reviewer's browser and are copied as Markdown that says exactly where each comment is, ready to send to the author or paste into an AI agent. Reviewers can comment with a mouse, the keyboard or a screen reader.

## Where it installs and where feedback goes

- Nothing to install: one script goes in the HTML file (loaded from a CDN, or a copy the user saves next to the page). An AI agent can add it with the steps below, by editing the HTML file only.
- Comments are stored only in the reviewer's own browser, on their device. Pipeup never sends them to any server.
- Feedback leaves only when the reviewer copies it (Copy as Markdown or Copy as Text) and sends it themselves, for example to the author or into an AI agent.

## Add Pipeup to an HTML page

1. Add the script tag just before `</body>`, pinned to a release: `<script src="https://cdn.jsdelivr.net/npm/pipeup@0.5.4/dist/pipeup.min.js"></script>`. Only edit the HTML file; there is nothing to download, fetch or run. The reader's browser loads the script when the page is opened.
2. On the `<html>` element, add `data-pipeup-doc="<key>"`. A key can be made in any browser with `await Pipeup.newDocumentAttribute()`. Keep it exactly as it is once people have commented.
3. Only if the page must work offline or from a file: tell the user to save https://pipeup-ai.github.io/pipeup/pipeup.min.js next to the HTML file themselves, then use `<script src="pipeup.min.js"></script>` instead of the CDN tag. Don't download it for them.
4. Mark stable blocks with short `data-pipeup-id` names, label charts and images with `data-pipeup-label`, and mark navigation and toolbars with `data-pipeup-ignore`.
5. Don't change the page's layout or styling to make room for Pipeup.

## Add-ons (only when the author asks)

Pipeup itself sends nothing anywhere. Optional add-ons are extra scripts, each saying what it sends: `@pipeup/share` (comments reach everyone who has the page, through an encrypted service the author picks), `@pipeup/voice` (dictating comments with the browser's own speech engine), `@pipeup/live` (live comments and presence, peer to peer), `@pipeup/assist` (a small AI model on the reviewer's device reads the page and points to related parts of it; nothing is sent anywhere). Authors who want sharing without a public service can run their own mailbox (`npx @pipeup/mailbox`, a server, not a page script); you only ever put the address they give you on `data-pipeup-share`. Add one only when the author asks for that feature, tell them in plain words what it sends and to whom, and never pick a sharing service for them. When you rewrite a page, keep `data-pipeup-doc`, `data-pipeup-share` and `data-pipeup-addons` exactly as they are; a new document gets a new `data-pipeup-doc` and no `data-pipeup-share`. Never put a stop key in a page.

When you add an add-on (best effort, to keep add-ons intentional): pin its script to the release with its `integrity` hash (from the release notes, or the Add-ons page's script tag); add its id to `data-pipeup-addons` on the `<html>` element, so only the add-ons the author chose run (append to an existing list, never remove an entry); and tell the author, in your reply, about a Content-Security-Policy that allows scripts only from the page and the CDN and connections only to the hosts the add-on names. Don't apply a policy yourself, because a strict one can break a page. This protects against stray scripts, not against a page that is already compromised.

Add-ons from other people run with the page's full power and Pipeup doesn't vouch for them. To make one (a company's own), see https://pipeup-ai.github.io/pipeup/addons-guide.html.md. To get a review into Git as a Markdown file, see the two worked examples "Save to GitHub" (no server, no token: opens GitHub's new-file page filled in) and "Send to Git" (through the company's own service), and the skill pipeup-send-to-git-setup, which covers both (https://pipeup-ai.github.io/pipeup/skills/pipeup-send-to-git-setup/SKILL.md): never put a Git token in a page or ask for one in a chat.

## Files

The site is https://pipeup-ai.github.io/pipeup/; the source is https://github.com/pipeup-ai/pipeup.

- [Everything in one file](https://pipeup-ai.github.io/pipeup/llms-full.txt): this guide plus all three skills.
- [This site as Markdown](https://pipeup-ai.github.io/pipeup/index.html.md): the home page's content.
- [Add comments to an HTML, as Markdown](https://pipeup-ai.github.io/pipeup/add-comments.html.md): someone sent you an HTML file and you want to give feedback.
- [Create comment-enabled HTML, as Markdown](https://pipeup-ai.github.io/pipeup/create-html.html.md): you are making a page to share and want feedback.
- [Making your own add-on, as Markdown](https://pipeup-ai.github.io/pipeup/addons-guide.html.md): the guide, including inside a company and setting up Send to Git.
- [Add-ons as Markdown](https://pipeup-ai.github.io/pipeup/addons.html.md): what each add-on sends, and how to add it.

- [Integration skill](https://pipeup-ai.github.io/pipeup/skills/pipeup-integrate/SKILL.md): how to add Pipeup to a page, by page type, with every option.
- [Summarise skill](https://pipeup-ai.github.io/pipeup/skills/pipeup-summarise/SKILL.md): summarise feedback by theme, section and status.
- [Apply skill](https://pipeup-ai.github.io/pipeup/skills/pipeup-apply/SKILL.md): act on approved feedback and reply with what changed.
- [pipeup.min.js](https://pipeup-ai.github.io/pipeup/pipeup.min.js): the library, one file.