@scribe-platform/cli 0.8.0 → 0.9.0

package/skills/scribe-site-builder/recipes/proofs.md

@@ -0,0 +1,311 @@
+# Recipe: proofs
+
+A **Proof** is work the Agency sends a Client to look at — a board of logo
+ideas, two colour schemes, a homepage mockup (RFC 0029). The Client opens a
+link, reacts to the ideas with a thumbs up or down, comments, and approves or
+asks for changes.
+It replaces emailing a PDF and digging through the replies.
+
+It is the mirror image of a Request, and conflating them is the mistake to
+avoid:
+
+| | Who starts it | Who owes the next move | Command |
+|---|---|---|---|
+| **Request** | the Client, asking for work | the Agency | `scribe request …` |
+| **Proof** | the Agency, showing work | **the Client** | `scribe proof …` |
+
+§6 and §10 are the parts to actually read. The rest is mechanics.
+
+## 1. Three rules that aren't negotiable
+
+1. **Never run `scribe proof send` without Ashley saying yes to that send.**
+   It emails a real person and freezes a version. Say who it is going to and
+   what the note says, then wait. Every other command here is reversible;
+   this one is not.
+2. **Never use Claude's Artifact tool for client review work.** If asked to
+   "send them an artifact", that means a Proof. An artifact lives on
+   claude.ai, is branded Claude, needs an account to open, and nothing it
+   collects reaches the client's record — which is the whole problem Proofs
+   exist to solve.
+3. **No Proof without a client.** A Proof belongs to a prospect or client. If
+   they don't exist yet, offer `scribe prospect create` first (see
+   [`prospects.md`](./prospects.md)).
+
+## 2. The folder
+
+One folder per Proof, inside the client's folder:
+
+```
+Acme Bakery/
+  research/
+  proofs/
+    logos/              ← one Proof
+      .scribe-proof.json   ← written by `proof create`; links folder → Proof
+      index.html
+      images/
+```
+
+`scribe proof create --client acme-bakery --title "Logo concepts" --dir proofs/logos`
+makes the Proof and writes `.scribe-proof.json`. Every later command run
+**inside that folder** needs no arguments — `scribe proof push`, not
+`scribe proof push acme-bakery/logo-concepts`.
+
+**The folder holds the latest version only.** Scribe keeps the history, so
+never make `logos-v1/`, `logos-v2/` copies. To get an old one back:
+`scribe proof pull --version 1 --dir <somewhere-new>`.
+
+## 3. The markup contract
+
+Anything the Client should be able to react to or comment on gets
+`data-proof-option`:
+
+```html
+<figure data-proof-option="logo-5" data-proof-label="Bold serif, navy">
+  <img src="images/logo-5.svg" alt="">
+</figure>
+```
+
+- **`data-proof-option`** is the id. Letters, numbers, `-` and `_`, up to 64.
+  It is what feedback is recorded against, so `logo-5` means logo-5 in every
+  version it appears in. **Keep ids stable across versions** — renaming one
+  orphans its feedback.
+- **`data-proof-label`** is what Ashley and the Client see next to it. Write
+  it for a human: "Bold serif, navy", not "Option 5".
+- **`data-proof-from="logo-5"`** on a revision records what it came from, so
+  the console can group "logo-5 → 5a, 5b, 5c".
+
+No script, import or stylesheet is needed for any of this. Scribe injects the
+runtime that draws the **👍 / 👎** and **Comment** affordances.
+
+**Give the main sections an `id`.** Pinned comments anchor to the nearest
+element with an `id`, so `<section id="hero">` makes "the button under the
+hero feels small" land on the hero rather than on a CSS path that moves.
+
+### Paths must be relative
+
+`src="images/logo.svg"`, never `src="/images/logo.svg"`. A Proof is served
+under a token prefix, so a root-absolute path 404s for the Client. `check`
+refuses these, and that refusal is correct — fix the path rather than
+passing `--force`.
+
+### No HTML at all
+
+If the folder holds only images (or PDFs), skip the page entirely. Scribe
+builds a gallery and names an Option after each file: `logo-5.png` →
+`logo-5`. "Send Acme these four PNGs as menu-board options" needs no markup.
+
+A hand-built page is still better when presentation matters — logos on a
+mocked storefront, light and dark grounds. The gallery is the floor.
+
+## 4. The loop
+
+```
+scribe proof check                 # what a push would refuse or warn about
+scribe proof preview               # open it locally, exactly as the client sees it
+scribe proof push --note "…"       # upload as the unsent draft. Sends nothing
+scribe proof send                  # ← asks Ashley first. Emails the client
+scribe proof show                  # status, versions, staff preview link
+scribe proof link                  # the client's link; --rotate replaces it
+```
+
+`preview` is a rehearsal: reactions, comments and pins all work, nothing is
+saved and nobody is emailed. Run it before every push and offer Ashley the
+URL.
+
+One thing it will show you: **while a Proof is open for feedback, a click
+anywhere on the work leaves a comment there** — the page's own links and
+buttons don't fire, the same bargain Figma makes. So a Proof is one page of
+work to talk about, not a clickable prototype; don't build one that needs
+navigating, and don't tell Ashley a Client can click through it. Read-only
+views (a closed Proof, an older version, the staff preview) behave like an
+ordinary page again.
+
+A **drag** rather than a click comments about a whole area: the box is drawn
+out as it's pulled, and the comment remembers it as a fraction of whatever
+element contains it, so it still covers the right thing after the page
+reflows on a narrower screen. Hovering such a comment's pin outlines the area
+again. That means a Proof wants real structure to hang those fractions off —
+a page built out of one absolutely positioned layer gives every area the same
+anchor, and the outlines drift together when the layout moves.
+
+`push` replaces the single unsent draft each time, so tinkering doesn't burn
+version numbers. **Only `send` creates a version the Client sees.** Push as
+often as you like.
+
+`check` before `push` — `push` runs it anyway, but reading the warnings
+first is cheaper than a rejected upload.
+
+## 5. Sending
+
+Confirm, then send:
+
+> "This sends *Logo concepts v1* to Dana (dana@acme.test) with the note
+> 'Six directions'. Send it?"
+
+- No `--to` sends to the client's primary contact. `--to a@b.com c@d.com`
+  replaces that list and is remembered for next time.
+- `--message "…"` overrides the push note for the email.
+- A Client replying to the email reaches whoever sent it, not an unattended
+  mailbox.
+
+If the client has no contact email, `send` fails **before** freezing
+anything — fix the contact, or pass `--to`, then send again.
+
+## 6. The next round — the reason Proofs exist
+
+**Read the feedback before changing anything:**
+
+```
+scribe proof feedback            # grouped by option: who reacted how, what they said
+scribe proof feedback --json     # same shape, for reading programmatically
+scribe proof feedback --version 1   # an older version
+```
+
+Then work the revision from what it actually says. Treat the new version as
+**the current working set** — what's still genuinely in play — not an archive
+of every option any version has ever shown. History isn't lost by leaving
+something out: it's still sitting on its own version, and the Client (or
+Ashley) can flip back to it with one tap, feedback and all (§2). So the
+question for each option is "does the Client still need to be looking at
+this?", not "did we ever show this?":
+
+- An option **nobody reacted to and nobody mentioned** is a candidate to drop.
+  Dropping is normal — `check` reports dropped ids as one neutral line, not a
+  warning.
+- An option with a **👍 and a comment** is the one to iterate on. Usually that
+  means the revision replaces it in the new version — mark it
+  `data-proof-from="<original>"` so the console shows the lineage — since the
+  Client already decided they liked the direction and is now just reacting to
+  the refinement. Keep both around instead if they genuinely still read as
+  two live contenders (two different directions both still being weighed,
+  say) rather than one superseded by the other.
+- A **👎** is one worth asking about rather than guessing — a thumbs-down with
+  no words is still an answer, and worth Ashley's phone call. What she learns
+  decides whether it's dropped, revised, or (if the room's split) left in
+  for now.
+- Push with a `--note` that says what changed in the Client's words ("Three
+  simpler takes on the one you liked"), because that note is what they read
+  in the email.
+
+Then ask before sending, as always. The new version keeps the **same link**;
+the Client lands on it with the older ones one tap away.
+
+`scribe proof reply <event-id> "…"` answers one comment. The id is printed
+beside every comment in `feedback`. The Client sees a reply the next time
+they open the Proof — **Scribe never emails a reviewer**, because it only
+ever asks their name. If a reply is urgent, tell Ashley to call.
+
+A Client replies back by clicking the pin on the work itself, which opens the
+thread with the box ready to type in — so a thread can run several turns
+without a new version. Those replies come through `feedback` like any other
+comment. The comment column beside the work is an index: clicking a row there
+opens that thread on the work rather than answering in place.
+
+Ashley can also reply by hand in the staff console, on the Proof's **Design**
+tab, the same way — a pin, or a row in the column, opens the thread on the
+work with a box to answer. Worth pointing her there when she wants to see the
+thing being talked about while she answers, or when she's on a phone. The
+**Feedback** tab answers in a list instead, grouped by idea. It is the same
+event as `scribe proof reply` whichever she uses.
+
+A **Reaction** is a comment that carries a thumb, which is why it reads in the
+same list as everything else and takes replies the same way. One per Reviewer
+per Option: a second thumb changes the first rather than adding to it, keeping
+the words and the answers already under it. The badge on an Option is both
+tools and marker — two thumbs and Comment until that Reviewer has used one,
+then their own thumb with everyone's faces beside it, opening the whole list on
+a click. A Reaction with an empty `body` is somebody who reacted without saying
+why; report it as the answer it is rather than skipping it.
+
+Whoever wrote a comment can **delete** it — the Client their own, Ashley her
+own replies — from the thread on the work or from the column. Neither can
+delete the other's. Clearing a Reaction (the same control, better named) takes
+the thumb, the words and the replies together. Deleting the comment a thread
+started with takes the whole thread with it, replies included, since a thread is one conversation and an
+answer to a withdrawn question reads as noise.
+
+A deleted comment leaves `feedback` entirely and leaves no event behind, so
+never quote one back at Ashley as still outstanding, and don't be surprised
+when a comment id from an earlier `feedback` run stops resolving — re-read the
+feedback rather than assuming the proof changed underneath you.
+
+## 7. More than one person deciding
+
+Owners forward the link to a business partner or spouse. That is supported and
+usually good news: the second person types their own name and shows up as a
+second reviewer, with their own reactions and comments.
+
+What it means when reading `feedback`:
+
+- **`👍` and `👎` list every reviewer who reacted that way**, so two people on
+  opposite sides of one option is a disagreement to surface *before* Ashley
+  calls, not during.
+- **The status follows the most recent decision.** If one approves and the
+  other asks for changes, the Proof reads `changes-requested` — but both
+  decisions are listed, and the status is not the whole story. Say both.
+- A new name appearing is worth mentioning once ("Marco's looked at it too"),
+  because it tells Ashley who is actually deciding.
+
+Don't try to reconcile them. Report who said what and let Ashley decide.
+
+## 8. Working the queue
+
+```
+scribe proof list                  # every Proof, most recently active first
+scribe proof list --status changes-requested
+scribe proof list --client acme-bakery
+scribe proof list --unopened       # sent 2+ days ago, never opened — call them
+```
+
+In the browser, **Proofs** in the staff console has the same three views:
+*Needs you*, *Waiting on client*, *Sent, not opened*. A due prospect in the
+follow-up list also carries one line about a Proof waiting on them, so it is
+in front of Ashley when she dials.
+
+## 9. Finishing, and housekeeping
+
+```
+scribe proof close --reason "delivered"   # stays readable on the same link forever
+scribe proof reopen                       # carry on the same history with a new version
+scribe proof link --rotate                # the old URL stops working. Then send again
+scribe proof link --expires 2026-12-31    # or "never" to clear it
+```
+
+Close when the work is delivered. A closed Proof still opens, read-only, so a
+Client hunting for "the logo we picked" next year finds it.
+
+**A Proof can't be deleted from the CLI**, only closed — same as a prospect.
+If one genuinely has to go, that's Dave.
+
+## 10. What to tell Ashley, and what not to
+
+**Say:** who a send is going to, before sending. What the Client actually
+said, in their words, before you change anything. That a link rotation
+breaks the old URL.
+
+**Don't say:** version numbers she didn't ask about, option ids as the
+primary way of naming things (use the labels — "the wheat star one", not
+"logo-5"), or anything about tokens, manifests or hashes. She asked for logo
+ideas, not a build report.
+
+**The one thing worth interrupting for:** a Client asked for changes, or
+approved. That is the moment the work moves.
+
+## 11. Clients who already have a site
+
+A Proof can be attached to one of the client's sites, and then asks them to
+**sign in** with their normal Scribe login instead of typing a name:
+
+```
+scribe proof create --client rods-auto --title "Homepage hero" --site rods-auto-body
+```
+
+`--site` defaults the access mode to `sign-in`, and the Proof appears under
+**Proofs** in that site's dashboard. If the person deciding has no login —
+the owner's spouse, say — switch it:
+
+```
+scribe proof link --access link
+```
+
+Everything else is identical.