# Take the pictures

A screenshot of a rendered page is evidence. A reading of the markup is not. This is how you get a
complete set of full-page pictures — desktop and phone — so that a person, or a model standing in for
one, can look at what a visitor would actually see.

**This file is only how to take the pictures. It is not how to judge them.** Judging is a separate pass
and it comes after.

Commands assume a folder named `beargrassai` on the machine running them. If you do not have that
folder, you cannot run these commands. Do not invent a path.

---

## What you are doing here

Making a record, not forming an opinion. Your job is finished when there is one full-page picture for
every page in scope, at every screen size that matters, and the number of files matches the number of
pages you asked for.

**A green exit code is not the job.** The tool can succeed and write nothing. Count the files.

---

## Take them

One address, default screen sizes:

```
node agent-tools/picviewer/capture.mjs --url https://example.com
```

A named set of pages — use this whenever you will compare, repeat, or send the result:

```
node agent-tools/picviewer/capture.mjs --project <name>
```

Pictures land in `agent-tools/picviewer/out/<timestamp>/<project>/`.

`--project` takes the **bare name**, never a path. The tool adds `projects/<name>.json` itself, so a path
doubles up into nonsense and exits 1.

A repeatable set uses a small JSON file naming the addresses and the screen sizes: desktop 1280×800 and
phone 390×844. Files come out named `desktop__<page>.png` and `mobile__<page>.png`.

**If these pictures are a deliverable, copy them into the client's dated folder.** Do not leave the only
copy inside the tool's own output tree, where the next run will bury it.

### A site behind a sign-in wall

A page behind a sign-in wall returns the sign-in page, not the site. Captured bare, you get a picture of
a login box and it looks like a real capture.

```
agent-tools/picviewer/pv-walled.sh <project-name>
```

That wrapper loads a credential and fails loudly if it is missing. Do not put the credential in this
file. Do not capture a login box and report it as the site.

---

## Check the pictures before you call this done

**Count them.** The number of files must equal the number of pages × the number of screen sizes. Not
"about right" — equal. A green exit with a short folder is a false pass and it has happened here.

**Look at one.** Open a picture with something that renders the image. If the first one is a login box,
a blank page, or an error, every other file in the folder is too.

**Full page, not a crop.** A screenshot of the visible window is not a capture of the page.

**Watch for pages that never finish loading.** Sites with heavy analytics or built on some website
builders hold connections open, so the tool waits, times out, writes nothing, and still exits 0. If a
folder is short, this is usually why: capture those with a setting that waits for the page to load
rather than for the network to go quiet.

---

## What good looks like

- One full-page picture per page, per screen size, and the counts match
- Every picture shows the actual page, not a sign-in box or an error
- Pictures a person can open and read
- If they matter beyond today, a copy in the client's dated folder

## Definition of done

1. Every page in scope has a desktop picture and a phone picture.
2. File count equals pages × screen sizes. You counted; you did not assume.
3. At least one picture opened and confirmed to be the real page.
4. Pictures are full-page.
5. If they are a deliverable, they are copied out of the tool's output tree.

Then, and only then, go and look at them.

## Refuse these

- Judging a page from filenames, markup, or "the capture ran"
- Reporting a site from a bare address when it sits behind a sign-in wall
- Treating a green exit code as proof that files exist
- Calling a window-sized crop a full-page capture
- Using this pass to claim two versions of a page match. That is a different pass and it needs both sides on one image