@scribe-platform/cli 0.7.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.

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

@@ -0,0 +1,192 @@
+# Recipe: prospects
+
+Ashley's calling pipeline lives in Scribe as Clients with `status: 'prospect'`.
+This recipe is about **recording and nurturing prospects she already has** —
+logging what happened on a call, scheduling the next touch, and moving one
+through the funnel. Finding new leads is not covered here: wherever a name comes
+from (a Places sweep, a referral, a drive-by), this recipe starts once it exists.
+
+The same operations are available two ways — `scribe prospect …` on the command
+line, and the `list_prospects` / `get_prospect` / `create_prospect` /
+`log_prospect_call` / `set_prospect_status` MCP tools. They are the same
+endpoints; use whichever the session has.
+
+§3 is the part to actually read. Everything else is mechanics.
+
+## 1. The pipeline
+
+Four statuses, and a prospect only ever sits in the first one:
+`prospect` → `active` (won) or `lost`, with `active` ↔ `churned` afterwards for
+a real client. Nothing is deleted on the way through — a lost prospect keeps its
+whole call log, because the reason it was lost is the point of recording it.
+
+```
+scribe prospect create "A+ Plumbing" \
+  --contact-name "Dana" --phone "555-0101" \
+  --note "Found on the Yelp sweep — no website, 4.6 stars over 90 reviews"
+
+scribe prospect list --due                 # who to call today
+scribe prospect show <id>                  # the full call log before dialling
+
+scribe prospect log <id> \
+  --note "Left a voicemail, no callback yet" \
+  --outcome left-message \
+  --next 2026-10-14
+
+scribe prospect status <id> active         # won
+scribe prospect status <id> lost --reason "Nephew builds their sites"
+```
+
+`list` defaults to a table and takes `--json` for parsing; so does every other
+subcommand. `--status` and `--search` filter, and the default list is
+due-sorted — soonest or most overdue first, undated prospects last.
+
+## 1b. Always pass `--outcome` on a real call
+
+`--outcome` is how far the attempt got, shallowest to deepest:
+
+| Outcome | Use when |
+|---|---|
+| `no-answer` | Nobody picked up |
+| `left-message` | Voicemail, or a message left with someone |
+| `gatekeeper` | Spoke to a person, but not the decision-maker |
+| `reached` | Spoke to the decision-maker |
+| `meeting-set` | Spoke to them **and** got a forward commitment |
+
+**It is optional in the CLI and should be treated as required for any note that
+describes a contact attempt.** It is the only input to the prospect's warmth, so
+a call logged without it leaves the pipeline reading colder and less-worked than
+it really is — and a prospect that was genuinely called three times without an
+outcome recorded will never show as `stalled`, so Ashley keeps calling a dead
+number.
+
+Leave it off only for a note that wasn't an attempt: research, a finding from a
+sweep, a reminder to self.
+
+## 1c. Reading warmth
+
+Every prospect carries a derived `warmth` plus an attempt count. Nothing stores
+it — it is computed from the call log every time it's read, so it changes on its
+own as a prospect goes quiet.
+
+| Warmth | Means | Worth more effort? |
+|---|---|---|
+| `hot` | Meeting set, recently | Yes — this is the closest to a sale |
+| `warm` | Real conversation, recently | Yes |
+| `untouched` | Nobody has called yet | Yes — needs a first attempt |
+| `cold` | Tried a few times, or a conversation that went quiet | Yes — re-warmable |
+| `stalled` | Called repeatedly and **never once** reached a human | No — this one is spent |
+
+`stalled` is the only warmth that means stop. Note that a prospect you once
+reached can never stall, however many no-answers follow — a conversation
+happened, so going quiet is re-warmable rather than unreachable.
+
+Sort with `--sort warm` to rank by likelihood to buy, or `--sort neglected` to
+find prospects nobody has followed up on. `--sort neglected` is worth running
+periodically: a prospect with no follow-up date never appears in `--due` at all,
+so it's the only way those surface.
+
+## 1d. "Do I need more leads?"
+
+```
+scribe prospect pipeline
+```
+
+Reports counts per warmth and a **workable** total, which is everything except
+`stalled`. Read the shape, not the total — a wall of `cold` that hasn't hit the
+stall cutoff is a calling backlog and the answer is "go call them", while a wall
+of `stalled` with workable near zero is a real shortage and the answer is "go
+find names". A low workable count is the signal to prospect; a low total with
+healthy warmth is not.
+
+## 2. Logging a call is the only way to reschedule
+
+`scribe prospect log` is the one command that moves `nextFollowUpAt`. There is
+no "set the follow-up date" command, deliberately: a date that changed with no
+note is a reschedule nobody can explain a month later. Every change to when
+Ashley next calls someone arrives attached to a dated note saying why.
+
+- `--note <text>` is **required**. A reschedule with nothing to say is still
+  worth a sentence ("no answer, trying again Tuesday").
+- `--next <date>` (re)schedules; `--clear-next` removes the scheduled follow-up
+  entirely. They're mutually exclusive.
+- Omit both and the note is appended with the existing follow-up untouched.
+
+Notes are append-only. Nothing edits or deletes one, from either surface.
+
+## 3. What to do unprompted, and what to ask about first
+
+Nothing below is enforced by the CLI or the API — there is no approval flag to
+set and no permission that blocks any of it. It is a judgment call every time,
+and this table is the judgment. Ashley's use of Claude here is a long-term
+mixture of "just handle it" and "check with me first"; getting this wrong in the
+cautious direction wastes a message, and getting it wrong in the other direction
+means she finds out a prospect was written off without her.
+
+| Action | Do it, or propose it? |
+|---|---|
+| `prospect log` — recording a call, a voicemail, a reschedule | **Do it.** This is the routine nurture action. It's additive, it's reversible by logging again, and asking first defeats the point. Include `--outcome`. |
+| `prospect list` / `prospect show` / `prospect pipeline` | **Do it.** Read-only. |
+| `prospect create` | **Check for a near-duplicate first** — `prospect list --search "<part of the name>"`. A clean miss means create it. Anything that looks like the same business under a different spelling, propose it rather than creating a second record. |
+| `prospect update` — a name fix, a new phone number | **Do it** when the correction is unambiguous (a typo, a number from a call she just logged). Propose a wholesale rename. |
+| `prospect status … lost` | **Propose it, with the reason, and wait for a yes.** It removes the prospect from her working list. Being wrong here looks identical to her forgetting about them. |
+| `prospect status … active` | **Always Ashley's call.** A won deal is a business fact she knows and the data doesn't. Never infer it from an enthusiastic note. |
+
+The two `status` rows are the load-bearing ones. When proposing either, say which
+prospect, which reason, and what the last note said — enough that she can answer
+without opening the console.
+
+## 4. Where this is a contract, and where it's advice
+
+| Contract | Advice |
+|---|---|
+| `nextFollowUpAt` changes **only** through `prospect log` — nothing else writes it | How far out to schedule a follow-up |
+| Notes are append-only; no surface edits or deletes one | How much detail to put in a note |
+| A status move never deletes anything, including `lost` | When to give up on a prospect |
+| Deletion isn't in the CLI or the API at all — it's console-only | — |
+| Warmth is derived from the call log; there's no field to set | Which warmth is worth your attention today |
+| `outcome` is a **contact result** only — there is no `demo-sent` | Whether a given note needs an outcome at all |
+
+## Gotchas
+
+- **A prospect's demo site is a real Scribe Site.** Ashley builds it in the CMS
+  because the CMS is what she's selling — own repo in the org, same as a
+  production site (RFC 0006). Create it with the normal `scribe site add`
+  flow; a won deal provisions nothing new, it just points `site.clientId` at the
+  now-`active` Client. RFC 0001's original summary describes a shared static
+  `demos` repo — that is historical and was never built. Don't repeat it.
+- **Attaching that Site to the Client is console-only.** There is no `scribe`
+  command and no `--client` flag on `site add`: it's the **Client** box on
+  Staff console → **Sites** → the site. So "they bought" is two actions — the
+  status move, which you can run, and the attach, which you hand over as a step
+  for Ashley to click. Say both; an `active` Client whose Site is still attached
+  to nobody reads as "nobody is being billed for it" on that page.
+- **`lost` is a status, not a delete.** A lost prospect keeps its whole call log
+  and gains a `lostReason`. It also stays in the default list — both
+  `prospect list` and the console's prospects view cover `prospect` **and**
+  `lost` — so narrow with `--status prospect` to see only live ones. What a
+  lost prospect does drop out of is the due queue: `--due` is prospect-only.
+- **There is no `scribe prospect delete`**, and no `DELETE` under
+  `/api/v1/prospects`. Deleting a Client is reachable only from the staff
+  console, behind its confirmation dialog. If something genuinely needs
+  removing, that's a thing to hand to Ashley, not to work around.
+- **Every prospect command needs a staff-role API key.** A non-staff key gets a
+  403 from the whole `/api/v1/prospects` surface, and a read-only key gets one
+  from everything except `list` and `show`.
+- **`--due` is "now or overdue", not "upcoming".** A prospect scheduled for next
+  week won't appear until the date arrives. Use `prospect list` for the whole
+  funnel.
+- **A prospect with no follow-up scheduled sorts last, not first.** Undated
+  isn't urgent — but it does mean nobody has decided what happens next, so it's
+  worth surfacing to Ashley if one sits there. `--sort neglected` is how.
+- **`demo-sent` is not an outcome**, and neither is `not-interested`. The first
+  is just a note; the second is `prospect status <id> lost --reason ...`.
+  Outcomes record how far a *contact attempt* got, nothing else.
+- **Warmth decays on its own.** A `hot` prospect you don't log anything against
+  becomes `warm` and then `cold` with no action from anyone, because the clock
+  moved. That's intended — it's what stops a stale meeting looking like your
+  best lead — but it means warmth you read last week may differ today.
+- **Don't treat warmth as a prediction.** It's a triage order. The real buying
+  signal is usually in the note prose ("lost a bid because the GC couldn't find
+  them online"), which the enum flattens. Read the notes before telling Ashley
+  who's closest to buying; use the sort to decide where to start reading.

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

@@ -0,0 +1,145 @@
+# Recipe: requests
+
+A **Request** is a Client asking the Agency to do work — a content change, a new
+page, a bug report, a question (RFC 0005). It is the mirror image of a
+submission, and conflating the two is the mistake to avoid:
+
+| | Who wrote it | Who owes the answer | Where it lives |
+|---|---|---|---|
+| **Submission** | a Visitor, through the Client's form | the Client | `scribe submission …`, per site + collection |
+| **Request** | the Client, through their dashboard | **the Agency — you** | `scribe request …`, one queue across every site |
+
+Requests belong to the relationship rather than to a repo: nothing about one is
+in the site's files, and archiving a site doesn't touch them.
+
+§4 is the part to actually read. The rest is mechanics.
+
+## 1. The queue
+
+```
+scribe request list                        # the queue, oldest activity first
+scribe request list --unassigned           # nobody has picked these up
+scribe request list --mine                 # claimed by this key's owner
+scribe request list --site rods-auto-body  # one site's requests
+scribe request list --status done --all    # finished ones, normally hidden
+scribe request show <id>                   # the ask + the whole thread
+```
+
+`list` is the staff queue, so it defaults to **oldest first** — a queue is worked
+from the end that has waited longest — and **hides `done`/`cancelled`**. Asking
+for a closed status by name shows it anyway, so `--status done` doesn't come back
+empty. `--json` on anything; the table prints the ids you need.
+
+`total` in the JSON (and the line under the table) is the whole result, not the
+page. A queue quietly showing 25 of 60 is how one stops being believed.
+
+**Every command here needs a staff-role key.** A site user's key gets a 403 from
+the whole surface, because a thread carries internal notes and claiming one only
+means something from inside the Agency. A key restricted to specific sites must
+pass `--site`, rather than being handed a "queue" that is silently a subset.
+
+## 2. The statuses, and the one that reads backwards
+
+Fixed by the platform — unlike a form's workflow, there is nothing per-site to
+read out of `.scribe.yml`.
+
+| Status | Means | Who owes the next action |
+|---|---|---|
+| `open` | Filed, nobody has picked it up | **The Agency** |
+| `in-progress` | Picked up, and the Client has been told | The Agency |
+| `waiting-on-you` | **Waiting on the *Client*** | The Client |
+| `done` | Finished | Nobody |
+| `cancelled` | Dropped | Nobody |
+
+**`waiting-on-you` is phrased from the Client's side**, because they read it on
+their own dashboard — it is the Client who is being waited on, not Ashley. Read
+as an agency instruction it means the opposite of what it says, and it is the one
+status an agent will get backwards. The CLI prints "Waiting on client" beside it
+for exactly this reason.
+
+Use it only when the work genuinely cannot continue without an answer: it puts a
+"needs you" badge on the Client's dashboard. When they reply, the request comes
+back to `open` on its own.
+
+## 3. Working one
+
+```
+scribe request claim <id>                          # take it; --release hands it back
+scribe request reply <id> --message "On it — today."
+scribe request reply <id> --message "DNS still at their old host" --internal
+scribe request status <id> waiting-on-you
+scribe request status <id> done
+```
+
+The loop that matches how the queue is meant to read:
+
+1. `request show <id>` — the whole thread, before touching anything.
+2. `request claim <id>`.
+3. A short visible reply saying it's picked up. **A reply on an `open` request
+   moves it to `in-progress` by itself** — don't follow it with a `status` call.
+4. Do the work. Usually this is an ordinary content/design change in the site's
+   repo: the request names its site, and `page` often names the page.
+5. Reply with what changed, including the URL, **then** `status done`.
+
+**Never mark a request done without a visible reply.** From the Client's side a
+request that silently turns Done is indistinguishable from being ignored, and
+they have no way to see what was changed.
+
+An **internal note** (`--internal`) is Agency-only: filtered out of every read a
+Client can reach, and it emails nobody. It also moves no status — thinking out
+loud isn't picking something up. Use it for what you found, especially anything
+that needs Dave.
+
+## 4. What to do unprompted, and what to show her first
+
+Nothing below is enforced. There is no approval flag on any of these commands,
+and the API will do whatever it is asked.
+
+| Action | Do it, or propose it? |
+|---|---|
+| `request list` / `request show` | **Do it.** Read-only. |
+| `request claim` | **Do it.** It's a label saying someone is on this, and `--release` undoes it. |
+| `request reply --internal` | **Do it.** The Client never sees it, nothing is emailed, and a note nobody needed is harmless. |
+| The actual work — a content change, a fix, a new page | **Do it**, to the same standard as any other edit: preview before publishing, and say what you changed. |
+| `request reply` (visible) | **Show her the text first**, unless she has said otherwise this session. It is emailed to the Client the moment it's sent, it is permanent, and it speaks for her business. |
+| `request status done` / `cancelled` | **Propose it.** Closing a request is a claim that the work is finished, and the Client reads the close. |
+| `request status waiting-on-you` | **Propose it**, and say what you'd be asking for. It parks the request on the Client's desk. |
+
+The visible-reply row is the load-bearing one, and it is the difference between
+a useful agent and an embarrassing one. "Draft it and let me read it" is the
+default posture; she can and will say "just send them" for a run of routine
+ones, which is a fine thing to honour for that session.
+
+A good way to offer the whole thing, if she asks you to work the queue: do the
+changes, show each reply before sending, propose each close.
+
+## 5. Where this is a contract, and where it's advice
+
+| Contract | Advice |
+|---|---|
+| A Request is created **only** by the Client — there is no `scribe request create`, and no POST on `/api/v1/requests` | What to do when they ask by phone instead |
+| A visible reply on an `open` request moves it to `in-progress` | How quickly to acknowledge |
+| Internal notes are filtered server-side from every Client-reachable read | How much to put in one |
+| Messages are append-only — nothing edits or deletes one | — |
+| A visible reply or a status change emails the Client; an internal note does not | — |
+| `assignTo` is only ever "me" or "nobody" — assigning someone else isn't built | When to release one |
+| Nothing is ever deleted, including a cancelled request | — |
+
+## Gotchas
+
+- **There is no `create`.** A Request filed by the Agency on the Client's behalf
+  would put words in their mouth and make the queue a measure of us rather than
+  of them. If a Client asks for something by phone, either do it as an ordinary
+  edit or ask them to file it so there's a thread. Say that rather than looking
+  for a flag.
+- **A reply is email.** Each one reaches the Client's inbox immediately; there is
+  no draft state and no recall. Compose it as the message it is.
+- **Claiming is Agency-private.** The Client never sees who holds their request —
+  the assignment writes an internal note, not a thread message, so "why isn't
+  Ashley on this one?" is a question they can't ask.
+- **Re-running a status change is safe.** A no-op transition writes no message
+  and sends no email, so setting `done` twice doesn't double-notify.
+- **`--all` is history, not a wider filter.** It only adds `done` and
+  `cancelled`; everything else is in the default list already.
+- **Requests survive their site being archived**, and are unreachable through
+  anything in the repo. Don't go looking for them in the site's files.