@juangadm/pre-post 1.2.0 → 1.4.0

package/skill/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: pre-post
 description: Before/after screenshots for the current PR. Use when the user says "take before and after", "pre-post", "screenshot comparison", "visual diff", "PR screenshots", or after making visual UI changes.
+version: 1.4.0
 allowed-tools:
-  - Bash(npx -y @juangadm/pre-post@latest *)
+  - Bash(npx -y @juangadm/pre-post@1.4.0 *)
   - Bash(npx pre-post *)
   - Bash(pre-post *)
 ---
@@ -11,7 +12,7 @@ allowed-tools:
 
 One command does everything: detects the routes this branch changed, screenshots them on
 desktop, pixel-diffs them, uploads the images to a `pre-post-assets` branch, and
-posts or updates a single comment on the open PR. The human reviews on GitHub.
+puts them at the top of the open PR description. The human reviews on GitHub.
 
 It picks both sides itself:
 
@@ -39,10 +40,16 @@ the Post side. Pass `--no-local-baseline` to turn it off.
 ## Run
 
 ```bash
-npx -y @juangadm/pre-post@latest pr
+npx -y @juangadm/pre-post@1.4.0 pr
 ```
 
-Add `--routes /a,/b` when the user names pages explicitly. Add
+The version is pinned on purpose: this file describes that release. If the run starts with
+`Note:` lines about another version, relay them; they mean a copy of these instructions is
+out of date.
+
+If you have a folder the user can open from wherever they are following you (a scratchpad
+or workspace directory in a hosted session), add `-o <that folder>/pre-post` so the images
+land somewhere they can see. Add `--routes /a,/b` when the user names pages explicitly. Add
 `--before https://production-url` only if the run reports it cannot work out the baseline
 (it is then saved to `.pre-post.json` for next time).
 
@@ -53,16 +60,30 @@ re-runs replace in place — the author's own text is never touched. If the PR c
 edited (a fork, a read-only token) it falls back to a single sticky comment.
 
 Each changed route shows **Pre beside Post**, per viewport, full pages in a `<details>`. No
-overlay, no percentage. A page that moved says `Content shifted down 48px`; relay as written.
+overlay, no percentage. A page that moved says `Content shifted down 48px`; relay as written. A pure move
+("Nothing else changed.") shows the full pages with no crop and no `<details>`, by design.
+
+## Show the user
+
+When anything changed, the command prints `Sheet: <path>`: one image with Pre beside Post for
+every change. If you can send files to the user, send that one file, even when the PR was
+updated. Someone following you from a phone sees it there before they open GitHub.
 
 ## Rules
 
-- Run the command once. Do not open, read, or describe the screenshot files; the PR
-  comment is the deliverable. Report the summary the command prints, plus the comment link.
+- Run the command once. Do not open, read, or describe the screenshot files. The block in
+  the PR description is the deliverable, and the sheet is the one image you pass along. Tell
+  the user what the summary says, plus the PR link. Never paste the terminal output into the
+  PR: ports, timings and percentages there are for you, not for a reviewer.
 - Do not switch branches, start dev servers, or use a browser tool yourself. The command
   handles all three.
-- Exit code 3 means a human must do one thing (log in, start the dev server, pass
-  `--before`). Relay that one sentence verbatim and stop.
+- Exit code 4 means a page rendered an error (a build error, a 500) instead of itself. No
+  screenshots were published and the PR says so in one sentence. Relay that sentence; the
+  branch needs fixing before a visual comparison means anything.
+- Exit code 3 means a human must do one thing (set a token, start the dev server, pass
+  `--before`). Relay that one sentence verbatim and stop. If GitHub refused the token, the
+  screenshots were still taken: send the sheet first, then relay the sentence. Never ask the
+  user to paste a token into the chat; the sentence names where it goes.
 - Do not use `--dry-run` unless the user asks to preview without posting.
 - If the summary lists routes that "need a sample URL", ask the user for one example URL per
   dynamic route and add it under `"samples"` in `.pre-post.json`, then re-run.
@@ -78,5 +99,8 @@ overlay, no percentage. A page that moved says `Content shifted down 48px`; rela
 | `--dry-run` | Preview locally, post nothing |
 | `--header k=v` / `--cookie k=v` | The site needs auth headers or cookies |
 
-Login-protected sites: `npx -y @juangadm/pre-post@latest login https://site` opens a browser
+To run on every PR without anyone invoking it, point the user to the GitHub Action guide
+(https://github.com/juangadm/pre-post/blob/main/docs/github-action.md). It posts with GitHub's own token, which also covers work done in cloud sessions.
+
+Login-protected sites: `npx -y @juangadm/pre-post@1.4.0 login https://site` opens a browser
 once; the saved session is reused automatically.