pipeup 0.9.0 → 1.0.0

package/skills/pipeup-apply/SKILL.md

@@ -5,16 +5,21 @@ description: Use when someone asks you to act on Pipeup feedback for an HTML pag
 
 # Apply Pipeup feedback
 
-Written for Pipeup 0.9.0 This skill is published at https://pipeup-ai.github.io/pipeup/skills/pipeup-apply/SKILL.md. Its companions: [integrate](https://pipeup-ai.github.io/pipeup/skills/pipeup-integrate/SKILL.md), [summarise](https://pipeup-ai.github.io/pipeup/skills/pipeup-summarise/SKILL.md).
+Written for Pipeup 1.0.0 This skill is published at https://pipeup-ai.github.io/pipeup/skills/pipeup-apply/SKILL.md. Its companions: [integrate](https://pipeup-ai.github.io/pipeup/skills/pipeup-integrate/SKILL.md), [summarise](https://pipeup-ai.github.io/pipeup/skills/pipeup-summarise/SKILL.md).
 
 ## 1. Read the comments
 
 Use the first of these that works:
 
-0. **A live link** (the author runs `npx --yes pipeup@0 watch report.html --agent Claude` on this computer, opens the page it
-   prints, and switches on **Share with my agent**): run `npx --yes pipeup@0 comments report.html` (add `--all` for resolved
+0. **A live link** (the author runs `npx --yes pipeup@1 watch report.html --agent Claude` on this computer, opens the page it
+   prints, and switches on **Share with my agent**): run `npx --yes pipeup@1 comments report.html` (add `--all` for resolved
    threads, `--json` for data). No browser needed. If it says nothing is shared, ask the author to switch the switch on.
    Your replies below reach the open page within seconds. The link lists your key for the page while it runs.
+   **Sent from the browser extension** (the reviewer pressed **Send to my agent** in Pipeup's menu, on any website):
+   run `npx --yes pipeup@1 browser` to list the pages sent, newest first, and `npx --yes pipeup@1 browser read <page>`
+   for one page's comments (`<page>` is part of its address or title). Answer each thread with
+   `npx --yes pipeup@1 browser reply <page> --thread <id> --agent <your name> "<words>"`; the extension puts the reply
+   in the thread when the page is next open. There's no page file to edit: tell the author what to change on the site.
 1. **Run the page** in a browser (you can drive one, or the author has it open) and evaluate
    `await Pipeup.comments()`. It returns `{ markdown, threads }`: `markdown` is the same text as **Copy as
    Markdown**, and `threads` is the same threads as data (`id`, `state`, `where`, `element`, `quote`, and each
@@ -44,9 +49,9 @@ Answer a question with an answer, not a change.
 You answer in the page's **replies file**, next to the page (`report.html` → `report.replies.js`), signed with your
 own key. The key stays on this computer in `~/.pipeup/agent.json`; never put it in the page or its folder.
 
-Run these commands exactly as written: `--yes` stops npx asking "Ok to proceed?", and `pipeup@0` takes any release npm
-will give (some computers only accept packages a few days old). Every release from 0.6 answers them the same way. A
-pre-release page's prompt names its pre-release; if npm refuses that one, use `pipeup@0`.
+Run these commands exactly as written: `--yes` stops npx asking "Ok to proceed?", and `pipeup@1` takes any release npm
+will give (some computers only accept packages a few days old). Every 1.x release answers them the same way. A
+pre-release page's prompt names its pre-release; if npm refuses that one, use `pipeup@1`.
 
 `--page` is **the HTML file that runs Pipeup**, the one the author opened, never a file it shows: on a viewer such as
 `wiki/viewer.html?file=notes.md`, pass `wiki/viewer.html`. The prompt the author copies names it. If you can't tell,
@@ -58,13 +63,13 @@ and lists it; without `--yes` it only shows the change. The author also needs th
 key and adds the add-on for you):
 
 ```bash
-npx --yes pipeup@0 agent --name Claude --page report.html --yes
+npx --yes pipeup@1 agent --name Claude --page report.html --yes
 ```
 
 Then, for each thread:
 
 ```bash
-npx --yes pipeup@0 reply --page report.html --thread <Thread id> "Changed the 20% to 15 to 20%, in the second paragraph." --addressed "addressed in revision 2"
+npx --yes pipeup@1 reply --page report.html --thread <Thread id> "Changed the 20% to 15 to 20%, in the second paragraph." --addressed "addressed in revision 2"
 ```
 
 It says where it wrote the replies, and, if the page doesn't list you yet, that the page will ignore them until it does.
@@ -100,7 +105,7 @@ addressed: short note, only if you made the change
 ````
 
 If you keep a Pipeup key between sessions (`~/.pipeup/agent.json`), sign each reply so it shows as yours rather than as
-pasted by the author: `npx --yes pipeup@0 reply --print --doc <document id> --thread <Thread id> "…" --addressed "…"` prints the
+pasted by the author: `npx --yes pipeup@1 reply --print --doc <document id> --thread <Thread id> "…" --addressed "…"` prints the
 entry, signed (Copy for my agent gives the document id). Ask the author to list your key only when you can sign; if you
 can't keep a key, the plain block works and the reply shows as pasted by them.
 

package/skills/pipeup-integrate/SKILL.md

@@ -5,7 +5,7 @@ description: Use when creating or editing an HTML document, slide deck, report,
 
 # Add Pipeup to a page: the full reference
 
-Written for Pipeup 0.9.0 For a quick "add comments to this page", [pipeup-add](https://pipeup-ai.github.io/pipeup/skills/pipeup-add/SKILL.md) is the short version; this is the full reference. This skill is published at https://pipeup-ai.github.io/pipeup/skills/pipeup-integrate/SKILL.md. Its companions: [summarise](https://pipeup-ai.github.io/pipeup/skills/pipeup-summarise/SKILL.md), [apply](https://pipeup-ai.github.io/pipeup/skills/pipeup-apply/SKILL.md).
+Written for Pipeup 1.0.0 For a quick "add comments to this page", [pipeup-add](https://pipeup-ai.github.io/pipeup/skills/pipeup-add/SKILL.md) is the short version; this is the full reference. This skill is published at https://pipeup-ai.github.io/pipeup/skills/pipeup-integrate/SKILL.md. Its companions: [summarise](https://pipeup-ai.github.io/pipeup/skills/pipeup-summarise/SKILL.md), [apply](https://pipeup-ai.github.io/pipeup/skills/pipeup-apply/SKILL.md).
 
 Pipeup lets people comment on an HTML page in place: select text, click any element (including
 buttons and charts) or drop a pin on a slide. Your job is to make the page *reviewable* while it
@@ -75,7 +75,7 @@ Then choose the options (see "Options" below): usually just the defaults.
    - Just before `</body>`, add the script pinned to an exact version:
 
      ```html
-     <script src="https://cdn.jsdelivr.net/npm/pipeup@0.9.0/dist/pipeup.min.js"
+     <script src="https://cdn.jsdelivr.net/npm/pipeup@1.0.0/dist/pipeup.min.js"
              integrity="sha384-…" crossorigin="anonymous"></script>
      ```
 
@@ -141,7 +141,7 @@ Then choose the options (see "Options" below): usually just the defaults.
    never a revision, version or date: those change for every comment already made, which then counts as
    somewhere else.
 
-8. **Check, and fix until it passes:** once it ships, run `npx --yes pipeup@0 check page.html`; until then, open the page and check the items below by eye. Fix every `fail`; fix
+8. **Check, and fix until it passes:** once it ships, run `npx --yes pipeup@1 check page.html`; until then, open the page and check the items below by eye. Fix every `fail`; fix
    `warn` items unless the author says otherwise. Typical fixes:
    - *layout changed* — you edited styles or wrappers; undo that.
    - *closed UI overlaps content* — add `data-pipeup-ignore` to a floating element that shouldn't be covered, or set
@@ -160,7 +160,7 @@ Then choose the options (see "Options" below): usually just the defaults.
 - Don't wrap content in new elements or add classes for Pipeup.
 - Don't add inline styles, z-index changes or padding "for the comment column".
 - Don't load the script from anywhere but the pinned CDN URL
-  (`https://cdn.jsdelivr.net/npm/pipeup@0.9.0/dist/pipeup.min.js`, with the `integrity` value from
+  (`https://cdn.jsdelivr.net/npm/pipeup@1.0.0/dist/pipeup.min.js`, with the `integrity` value from
   the release notes) or a copy of that same file next to the page. Never use an unpinned URL.
 - Don't put secrets in `data-pipeup-doc`; it *is* the document's key — anyone with the file can
   read its feedback, which is the intended audience.
@@ -183,9 +183,12 @@ page opened from disk and in any script order, and they are released with Pipeup
   with `data-pipeup-id`, `data-pipeup-ask="<question>"` and `data-pipeup-ask-kind` (`agree`, `choice` with
   `data-pipeup-ask-options="One|Two"`, or none for words), and keep the question in the element's own words for anyone
   without the add-on (https://pipeup-ai.github.io/pipeup/addons/inline.html.md). Never answer a question yourself.
+  Asks are compact and take the page's font. To match the page's look, set `--pipeup-ask-accent`, `--pipeup-ask-font`
+  and `--pipeup-ask-radius` in the page's CSS (on `:root` or one ask's element); don't hide or rebuild the ask's
+  controls. Pipeup's mark and a light tint of the accent always stay, so reviewers can see where to answer.
 - **Ask first, and say in plain words what it sends and to whom** (the line above, and the add-on's README). Never
   pick a sharing service yourself: the author chooses one.
-- Add it as one more `<script>` after Pipeup's, pinned the same way (`https://cdn.jsdelivr.net/npm/@pipeup/share@0.9.0/dist/share.min.js`
+- Add it as one more `<script>` after Pipeup's, pinned the same way (`https://cdn.jsdelivr.net/npm/@pipeup/share@1.0.0/dist/share.min.js`
   with its `integrity` from the release notes), or use the combined file `pipeup+share.min.js` instead of Pipeup's.
 - Sharing is set up by the author with the command line (`npx @pipeup/share create page.html --server …`), which writes
   `data-pipeup-share` into the file and prints a stop key once. **Never write `data-pipeup-share` yourself and never
@@ -228,7 +231,7 @@ page opened from disk and in any script order, and they are released with Pipeup
 - **Letting an agent answer comments.** Only when the author asks. Agents read a page's comments with
   `await Pipeup.comments()` (part of Pipeup itself) and answer in a replies file next to the page (`pipeup-apply` is the
   skill for that). Showing those answers in the page is the **agents add-on**, so listing an agent means two things:
-  1. With the author's yes, the agent lists itself: `npx --yes pipeup@0 agent --name Claude --page page.html --yes`
+  1. With the author's yes, the agent lists itself: `npx --yes pipeup@1 agent --name Claude --page page.html --yes`
      adds its public key to `<html>` as `data-pipeup-agents` (appended to an existing list) and changes nothing else.
      Or add a key you were given by hand, keeping every entry. Never write a key you weren't given, and never put an
      agent's private key in the page.
@@ -239,14 +242,42 @@ page opened from disk and in any script order, and they are released with Pipeup
      sends the page's comments to the program on their computer; nothing leaves the computer. It also lets the agent
      reply in threads and mark them addressed, never resolve or change anyone's comment. The page ignores replies from
      keys it doesn't list. Without the add-on the page says so once in the browser console and no replies show.
-  On their own computer the author can instead run `npx --yes pipeup@0 watch page.html --agent Claude`: it shows the page with a
+  On their own computer the author can instead run `npx --yes pipeup@1 watch page.html --agent Claude`: it shows the page with a
   **Share with my agent** switch (off until they turn it on), lists the agent while it runs, **adds the agents add-on to
-  the page it shows itself**, and lets the agent read with `npx --yes pipeup@0 comments page.html`. Nothing is written into the
+  the page it shows itself**, and lets the agent read with `npx --yes pipeup@1 comments page.html`. Nothing is written into the
   page file. (It refuses a page whose Pipeup is older than 0.6 and says what to change; a 0.6.x page already has agent
   support built in.)
 - `data-pipeup-live="auto"` makes "Go live" the default, but nobody connects before they have seen the sentence
   about their network address. `data-pipeup-live-relays="wss://…,wss://…"` replaces the default meeting-point relays.
 
+## A page with its own Comment button
+
+A page can make reviewing part of its own design: a Comment button in its header instead of Pipeup's control in the
+corner. Use Pipeup's page API (the instance `Pipeup.mount()` resolves to; it returns the running one if Pipeup started
+on its own):
+
+```html
+<button id="comment" aria-pressed="false">Comment</button>
+<button id="comments">Comments</button>
+<script>
+  Pipeup.mount().then((pu) => {
+    const comment = document.getElementById("comment");
+    comment.addEventListener("click", () => pu.setCommentMode(!pu.commentMode));
+    // Heard however comment mode changed: this button, the shortcut, Esc or Pipeup's own control.
+    pu.on("change", (s) => comment.setAttribute("aria-pressed", String(s.commentMode)));
+    document.getElementById("comments").addEventListener("click", () => pu.openMenu());
+  });
+</script>
+```
+
+- `pu.setCommentMode(on)`, `pu.commentMode` and `pu.on("change", fn)` start and stop comment mode and follow it.
+- `pu.openMenu()` opens Pipeup's menu (All comments, Copy comments, Hide comments, the add-ons' rows) and
+  `pu.openAllComments()` opens All comments. What the menu holds is Pipeup's: a page can't remove a row.
+- `data-pipeup-control="off"` on `<html>` hides Pipeup's control. Only do this when the page gives reviewers its own
+  way to the menu, because copying and sending comments live there; `pipeup check` warns if nothing calls
+  `openMenu()`. The shortcut keeps working.
+- Change the reviewer's note to match: name your button instead of "the comment button in the bottom-right corner".
+
 ## Options
 
 Markup on the page:
@@ -259,6 +290,7 @@ Markup on the page:
 | `data-pipeup-addons` | `<html>` | Which add-ons may run, by id (`share,voice`; `none` for none). Without it every add-on runs. Keep every entry; add yours. |
 | `data-pipeup-layout="column"` / `"bubbles"` | `<html>` | Force where comments show (column or bubbles). Pipeup reads it and never sets it. |
 | `data-pipeup-auto="off"` | `<html>` | Don't start automatically; the page calls `Pipeup.mount()` itself. |
+| `data-pipeup-control="off"` | `<html>` | Hide Pipeup's control, for a page with its own Comment button that opens Pipeup's menu (see "A page with its own Comment button"). |
 | `data-pipeup-edition` | `<html>` | The edition the page shows (a daily briefing in one shell); set it again when the next is swapped in. Comments stay with their edition. |
 | `data-pipeup-id` | any block | Stable identity so comments stay attached (Step 3). |
 | `data-pipeup-label` | charts, images, icons | The name reviewers and AI tools see (Step 4). |

package/skills/pipeup-send-to-git-setup/SKILL.md

@@ -5,7 +5,7 @@ description: Use when someone wants Pipeup reviews saved as Markdown files in th
 
 # Set up "Save to GitHub" or "Send to Git"
 
-Written for Pipeup 0.9.0 This skill is published at https://pipeup-ai.github.io/pipeup/skills/pipeup-send-to-git-setup/SKILL.md.
+Written for Pipeup 1.0.0 This skill is published at https://pipeup-ai.github.io/pipeup/skills/pipeup-send-to-git-setup/SKILL.md.
 
 Two example add-ons (written the way a company writes its own; **not** from the Pipeup project) get a review into Git as a
 Markdown file, the same Markdown that Copy comments › As Markdown makes (each comment says where it is, ready for an AI to act on):

package/skills/pipeup-summarise/SKILL.md

@@ -5,7 +5,7 @@ description: Use when someone has Pipeup feedback on an HTML page — text a rev
 
 # Summarise Pipeup feedback
 
-Written for Pipeup 0.9.0 This skill is published at https://pipeup-ai.github.io/pipeup/skills/pipeup-summarise/SKILL.md. Its companions: [integrate](https://pipeup-ai.github.io/pipeup/skills/pipeup-integrate/SKILL.md), [apply](https://pipeup-ai.github.io/pipeup/skills/pipeup-apply/SKILL.md).
+Written for Pipeup 1.0.0 This skill is published at https://pipeup-ai.github.io/pipeup/skills/pipeup-summarise/SKILL.md. Its companions: [integrate](https://pipeup-ai.github.io/pipeup/skills/pipeup-integrate/SKILL.md), [apply](https://pipeup-ai.github.io/pipeup/skills/pipeup-apply/SKILL.md).
 
 ## 1. Get the feedback as text