@damiangilgonzalez/harness 1.3.7

package/skills/retention/references/health-score-and-metrics.md

@@ -0,0 +1,97 @@
+# Health score & retention metrics
+
+The long lookup material most operators consult once when standing the program up.
+
+## Dimension catalog
+
+Pick **4+** dimensions. A composite of 4+ weighted signals predicts churn ~34%
+more accurately than a single-dimension gauge (Totango 2025). Weight activity
+heaviest — absence precedes every other failure.
+
+| Dimension | Default weight | Candidate signals | Notes |
+|---|---|---|---|
+| Product usage / activity | ~40% | login recency, sessions/week, DAU/WAU, depth of feature adoption, % of seats active | the dominant predictor; under-weight it and the score lags reality |
+| Engagement | ~25–30% | email open/reply, QBR attendance, NPS response, champion still employed, community presence | the relationship layer |
+| Milestones / business fit | ~20% | onboarding goals hit, first value realized, ROI demonstrated, plan matches stated need | "are they getting what they bought?" |
+| Recency | ~10% | days since last meaningful action | a fast decay signal that sharpens the others |
+
+Add product-specific dimensions (e.g. integration depth, API call volume) by
+splitting a category's weight — keep the total at 100.
+
+## Normalize to 0–100
+
+For each dimension, map the raw signal onto 0–100 before weighting:
+
+```text
+1. Define the healthy range per signal (e.g. logins/week: 0 = none, 5+ = full).
+2. Linear-scale the raw value into 0–100 within that range, clamp at the ends.
+3. If a dimension has several signals, average their 0–100 scores first.
+4. Multiply each dimension's 0–100 by its weight, sum → the account score.
+```
+
+## Cutoff tuning
+
+Starting cutoffs: **green ≥70, yellow 40–69, red <40.**
+
+Tune them against history: pull the last ~2 quarters of cancellations, score each
+account at "30 days before they churned," and move the red line until most real
+churners were already red or yellow at that point. If everything was green until
+the day they left, your dimensions or weights are wrong — usually activity is
+under-weighted.
+
+## Worked scored account
+
+```text
+Account: Acme Co, mid-market, renewal in 45 days
+
+Usage      30/100  × 0.40 = 12.0   (logins halved, two features abandoned)
+Engagement 60/100  × 0.28 = 16.8   (champion still replies, missed last QBR)
+Fit        80/100  × 0.20 = 16.0   (hit onboarding goals, ROI shown)
+Recency    20/100  × 0.10 =  2.0   (last meaningful action 18 days ago)
+                              -----
+Score = 46.8  →  YELLOW
+
+Read: usage is collapsing while the relationship is intact — classic "not using
+it" pattern. Play: pause + re-onboard touch, not a discount. Flag now: 45 days
+of lead time is exactly the window the score is meant to buy.
+```
+
+## Metrics reference
+
+### Formulas
+
+```text
+GRR = (start MRR − contraction − churn) / start MRR        (never > 100%)
+NRR = (start MRR − contraction − churn + expansion) / start MRR   (can be > 100%)
+Logo churn    = customers lost in period / customers at start
+Revenue churn = MRR lost in period / MRR at start
+Save rate     = cancel attempts saved / total cancel attempts
+```
+
+### Worked numbers
+
+```text
+Start MRR 100k; expansion +15k; contraction −5k; churned −12k.
+GRR = (100 − 5 − 12) / 100 = 83%
+NRR = (100 − 5 − 12 + 15) / 100 = 98%
+
+Read: NRR 98% looks fine, but GRR 83% is barely above the 80% alarm line —
+expansion is papering over real base loss. Optimize the base, not upsell.
+```
+
+### Segment benchmark table (2025 B2B SaaS)
+
+| Segment | NRR | Monthly logo churn | Annual churn |
+|---|---|---|---|
+| SMB | ~97% | 3–7% | ≈31–58% |
+| Mid-market | ~108% | 1.5–3% | — |
+| Enterprise | ~118% | <1.5% | — |
+| "Good" benchmark | NRR median ~106%, GRR median ~90% | <1%/mo | <5%/yr |
+
+The alarm restated: **GRR < 80% means a few expanding accounts are masking a
+fundamental retention failure.** And **43% of SMB losses happen in the first 90
+days** — that early window is an activation problem (`../client-onboarding/SKILL.md`),
+not a renewal-program problem.
+
+Sources: Totango 2025, customerscore.io, SaaS Capital, Fiscallion, ChurnZero,
+Vena, Vitally, Optifai, Churnkey 2025 — accessed 2026-06-02.

package/skills/retention/references/save-and-winback-plays.md

@@ -0,0 +1,65 @@
+# Save plays & win-back ladder
+
+A ready-to-lift playbook. The skeletons below are structure and offer shape — not
+finished copy. Polished email/in-app wording is `../newsletter/SKILL.md`.
+
+## The one-question exit survey
+
+Rules:
+- **One question, 5–7 preset reasons, one tap, answerable in <5 seconds.**
+- Always show a free-text "other" but branch on the preset.
+- The cancel button stays reachable in one click throughout (CA ARL floor — see
+  `../compliance/SKILL.md`).
+
+```text
+Before you go — what's the main reason?
+  ( ) Too expensive
+  ( ) Not using it right now
+  ( ) Missing a feature I need
+  ( ) Switching to another tool
+  ( ) Just a temporary project / seasonal
+  ( ) Something else ____________
+```
+
+## Save-play library (exit reason → ranked play)
+
+Ranked by retained life. Save rate benchmark ≈34% (Churnkey 2025). Personalized
+offers prevent ~23% of cancellations; generic flat offers do not.
+
+| Exit reason | Play 1 | Play 2 | Offer shape | Retained-life rationale |
+|---|---|---|---|---|
+| Too expensive | Downgrade to lower tier | Temporary discount | tier move; or 20–30% off, 2–3 mo | downgraders stay **7–8 mo longer**; lower revenue > $0 |
+| Not using it right now | Pause | Re-onboarding touch | freeze 1–3 mo + scheduled setup call | pausers stay **~5.5 mo longer**; ~25% of would-be churners pause |
+| Missing a feature | Human / roadmap | — | connect to PM, show roadmap, NO discount | money does not close a capability gap |
+| Switching vendor | Save call | — | book a person fast | only a human counters a competitor decision |
+| Temporary / seasonal | Pause | Downgrade | freeze to reactivation date | preserves the account for the obvious return |
+| Bad fit / price-only | Graceful let-go | — | clean cancel + enroll in win-back | retaining bad fit just delays churn, inflates support |
+
+Tie-breaker when the reason is fuzzy: **downgrade > pause > temporary discount >
+human save call > let-go.** Discount last — it permanently cuts revenue and only
+tests price sensitivity. **Temporary 20–30% off for 2–3 months, never permanent.**
+
+Pause economics worth remembering: pause programs generate $200M+ in industry
+re-subscription revenue precisely because ~25% of cancellers will accept "freeze"
+when they would have rejected "stay."
+
+## Win-back ladder (30 / 60 / 90)
+
+For customers who left anyway. Recovers ~5–15%. Value-first, then escalate — never
+lead with the deal or you train healthy customers to churn for a discount.
+
+```text
+Day 30  Value reminder. NO discount.
+        "Here's what's shipped / what your team is missing." Re-open the door.
+
+Day 60  Modest incentive.
+        ~15–20% off for 3 months. "Come back and pick up where you left off."
+
+Day 90  Best offer.
+        ~30–40% off for 6 months. Final, time-boxed. "Last chance at this rate."
+```
+
+After Day 90, drop to a low-frequency nurture (quarterly product news) — do not
+keep escalating discounts indefinitely.
+
+Sources: Churnkey 2025, Recurly, SmartSMS, Userpilot, ChurnWard — accessed 2026-06-02.

package/skills/review-management/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: review-management
+description: "Use when a public review needs an on-voice reply, when you need to earn more reviews legally, or when an aggregate rating is slipping across Google Business Profile, Trustpilot, the App Store or Google Play — including deciding reply versus flag, getting an unfair one-star removed rather than merely answered, and wiring programmatic replies. NOT a private support ticket against an SLA (that is `customer-support`), NOT churn, NPS or save plays (that is `retention`)."
+tags: [reviews, reputation, google-business-profile, trustpilot, ftc, responses, app-store]
+recommends: [customer-support, retention, seo-geo, brand-voice, social-publisher]
+origin: risco
+---
+
+# review-management
+
+You run public reputation as a program. A review is the one customer message every
+future prospect also reads, so it rolls up into an aggregate that moves local rank and
+the buy decision. Your job is three artifacts: a **review-request flow** (earn more,
+the legal way), a **response playbook** (reply on-voice, within the SLA, to every
+rating), and a **reputation scorecard** (the aggregate signal across surfaces).
+
+You do not write the brand's voice — you consume it. You do not run the private inbox.
+You do not make the page rank. You own what is public and what it averages to.
+
+## What this owns vs route elsewhere
+
+The dividing line is one question: **can a stranger read it?** If your reply is visible
+to every future prospect, it's a review — yours. If it's a private channel, it's not.
+
+| The ask | Route to | Why |
+|---|---|---|
+| Private email/chat/ticket against an SLA | `../customer-support/SKILL.md` | 1:1, non-public, macro library + queue — not a public reply |
+| Churn risk, NPS, save plays, win-back | `../retention/SKILL.md` | A bad review may *signal* churn; the save play lives there |
+| Make the profile rank (schema, GEO, local pack beyond reviews) | `../seo-geo/SKILL.md` | Reviews feed rank, but on-page/schema is a different lever |
+| Repurpose a 5-star into a social post | `../social-publisher/SKILL.md` | Scheduling/cadence of the post, not the review reply |
+
+The reply voice — traits, word bank, tone matrix — comes from `../brand-voice/SKILL.md`.
+This skill applies that guide; it never authors it.
+
+## The legal floor — read before you ask
+
+The **FTC Consumer Review Rule** is in force (final rule effective **2024-10-21**) and
+being enforced — the FTC sent warning letters to 10 companies on **2025-12-22**.
+Penalties run up to **$53,088 per violation** (per the FTC 2025-12 warning letters /
+press release, the inflation-adjusted figure in force from Jan 2025). Four moves are
+banned. Internalize them before you draft a single request:
+
+1. **No fake or insider reviews.** Don't write, buy, or solicit reviews from people who
+   didn't transact. *Why: they're deceptive on their face and the per-violation fine is
+   ruinous.*
+2. **No review gating (suppression).** You may **not** screen for sentiment before the
+   ask — no "rate us 1–5, and only the happy ones get routed to Google." Routing unhappy
+   customers to a private form while sending happy ones to the public link is illegal
+   suppression. *Why: it manufactures a rating that doesn't reflect reality — the exact
+   harm the rule targets.*
+3. **No incentivizing a particular sentiment.** You may offer an incentive to review
+   (if disclosed) — you may **not** condition it on the review being positive. *Why:
+   "$10 for a 5-star" buys sentiment, not feedback.*
+4. **No misrepresenting that reviews are independent** when they're insider/company-controlled.
+
+The one rule that resolves 90% of cases: **you may ask everyone; you may not condition
+the ask, the routing, or the reward on how they feel.**
+
+```text
+Bad  (gating — illegal):  "Loved us? Leave a 5-star here →. Had a problem? Email us instead."
+Good (neutral — clean):   "Thanks for choosing us. Share your honest experience here → [link]."
+```
+
+## Earn reviews cleanly
+
+Ask within **24–48h** of the transaction — peak emotional recency. Pick the channel by
+context; a hybrid SMS-then-email (48–72h gap) lifts total collection **40–60%**.
+
+| Channel | Use when | Open / reply | Note |
+|---|---|---|---|
+| SMS | You have a verified mobile + recent transaction | ~98% open, 15–25% reply | Highest yield; keep it one line + link |
+| Email | No phone, or B2B with work addresses | ~20% open, 2–5% reply | Personalization merge tags lift response 20–30% |
+| QR on receipt | On-site retail / hospitality | walk-up | Print it; ask at the moment of satisfaction |
+| In-app prompt | Mobile app, after a success moment | varies | Triggers the OS review sheet (App Store / Play) |
+
+**Message anatomy** (two sentences): name → one specific reference to what they bought →
+direct link to the review surface. No sentiment screen, no "if you're happy."
+
+```text
+Hi Marta — thanks for the kitchen install last Tuesday. If you have 30 seconds,
+your honest review helps other homeowners decide → [direct Google review link].
+```
+
+The link points **straight to the review form** (GBP "write a review" deep link,
+Trustpilot service-review invite, the app's store page). Never to an internal star-picker
+that branches on the rating — that's gating.
+
+## Respond — the playbook
+
+Reply to **every** review within **48h** (within 24h correlates with better local
+ranking; 52% of customers expect a reply within 7 days). On Google Play a developer
+response raises that review's rating by **~0.7 stars on average** — replies are not
+optional hygiene, they move the number.
+
+| Review type | The move | Reply shape | SLA |
+|---|---|---|---|
+| 5-star praise | Thank + reinforce one specific they mentioned | 1–2 sentences, named, warm, on-voice | 48h |
+| Positive + a question/ask | Thank, then answer the question publicly | Answer first, gratitude second | 48h |
+| Vague 1–2 star (no detail) | Acknowledge, invite the detail offline | "Sorry to hear this — we'd like to understand, reach us at…" | 48h |
+| Specific complaint (fair) | Own it, move offline, state the fix | The sequence below | 24–48h |
+| Suspected fake / off-topic | Flag for removal **and** post a calm holding reply | See "Flag vs reply" | 48h |
+
+**The negative-review sequence** (write it fresh every time; never paste a template):
+
+1. **Acknowledge** the person and the feeling, by name. No "we're sorry you feel that way."
+2. **Own the specific** thing that went wrong — name it, don't deflect.
+3. **Move it offline** — give a direct contact (name + email/phone), once.
+4. **State the concrete fix** or what you've changed, briefly.
+5. **Invite an update** — leave the door open for them to revise the review.
+
+```text
+Bad  (defensive, public argument):
+  "That's not what happened. Our records show you were 40 minutes late, which is
+   why the install ran over. We followed our standard process."
+
+Good (own → offline → fix → invite):
+  "Hi James — you're right that the install ran past the window we promised, and
+   that's on us. I'd like to make it right; please email me directly at
+   ops@acme.co. We've since added a buffer to every booking so this doesn't
+   repeat. — Lena, Ops Lead"
+```
+
+## Flag vs reply
+
+Replying is the default. Flagging is the exception — and mass-flagging legitimate
+negatives is itself a reputation and policy risk. **Flag for removal only when the
+review is:**
+
+- **Fake** — from someone who never transacted.
+- **Off-topic** — not about your business / a different location.
+- **Conflict of interest** — competitor, ex-employee, personal feud.
+- **Policy violation** — profanity, hate, doxxing, illegal content.
+
+A review that is negative, harsh, or even partly inaccurate but reflects a real
+experience is **not** flag-eligible. Answer it. Per-platform flag paths and dispute forms
+are in `references/platform-apis.md`.
+
+## The platforms (programmatic)
+
+Most of this is offloaded to `references/platform-apis.md` (endpoints, scopes, roles,
+limits, gotchas). The three facts you must not get wrong, inline:
+
+- **GBP reply is live and still on v4** — not migrated to v1, no announced deprecation:
+  ```text
+  PUT https://mybusiness.googleapis.com/v4/{name=accounts/*/locations/*/reviews/*}/reply
+  scope: https://www.googleapis.com/auth/business.manage   # verified locations only
+  ```
+  This single `PUT` both creates and updates the reply.
+- **The Google Q&A API is dead** (shut down November 2025). Do **not** build against
+  Questions-and-Answers endpoints — review listing + reply survive, Q&A does not.
+- **Apple allows exactly one editable response per review** via App Store Connect
+  (get/create/update/delete; requires Account Holder, Admin, or Customer Support role).
+  Apple also surfaces AI review summaries on iOS 18.4+, so themes in your reviews now
+  feed an auto-generated digest — fix recurring complaints, don't just reply to them.
+
+## Reputation scorecard
+
+Track six metrics per surface, reviewed **weekly**:
+
+| Metric | What it is | Target signal |
+|---|---|---|
+| Rating | Aggregate stars | Trend, not snapshot |
+| Volume | Total reviews | More = more trust + rank weight |
+| Velocity | Reviews/month | Steady inflow beats a stale 5.0 |
+| Recency | Days since last review | Fresh reviews are weighted heavier |
+| Response rate % | Replies ÷ reviews | Aim ~100% — the +0.7-star Play effect compounds |
+| Sentiment by theme | Complaints/praise clustered | Drives fixes, feeds Apple's AI summary |
+
+Cluster the negatives by theme weekly. Three reviews about "slow checkout" is a product
+ticket, not three replies — route the fix, then close the loop in your replies.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Gating (route unhappy away from the public link) | Illegal FTC suppression, up to $53,088/violation | Ask everyone the same neutral way |
+| Buying / incentivizing-by-sentiment | Banned; deceptive; fines | Disclose any incentive, never tie it to positivity |
+| Copy-paste reply on every review | Reads robotic; kills the +0.7-star effect | Write fresh, name one specific each time |
+| Arguing in public / "that's not what happened" | Every prospect reads you losing | Own it, move offline, state the fix |
+| Ignoring positive reviews | Leaves trust + ranking weight on the table | Reply to 5-stars too, within SLA |
+| Replying off the brand-voice guide | Inconsistent, off-brand surface | Pull traits from `../brand-voice/SKILL.md` |
+| Building on the Google Q&A API | Shut down Nov 2025 — it's gone | Use v4 reviews + `updateReply` only |
+| Mass-flagging legitimate negatives | Policy risk; doesn't remove real feedback | Flag only fake/off-topic/conflict/policy |
+
+## Verify the copy
+
+Before you ship any request template or reply, run the copy-banlist linter — it fails on
+gating, sentiment-incentive, and dead-Q&A-API phrasing:
+
+```bash
+./scripts/verify.sh path/to/review-copy.md
+```
+
+It's read-only and exits 0 on clean or empty input. See `evals/README.md` for how the
+capability eval is graded.
+
+## Cross-references
+
+- `../customer-support/SKILL.md` — the private 1:1 ticket against an SLA
+- `../retention/SKILL.md` — churn, NPS, save plays a bad review may signal
+- `../seo-geo/SKILL.md` — making the profile rank beyond review signals
+- `../brand-voice/SKILL.md` — the voice your replies are written in
+- `../social-publisher/SKILL.md` — repurposing a glowing review into a post
+- `references/platform-apis.md` — per-surface endpoints, scopes, roles, limits, gotchas

package/skills/review-management/evals/README.md

@@ -0,0 +1,13 @@
+# Evals — review-management
+
+`cases.yaml` holds three groups. `should_trigger` lists prompts that must load this
+skill (including a non-obvious compliance question and a Catalan phrasing);
+`should_not_trigger` lists near-miss prompts that must route to a real sibling
+(`customer-support`, `retention`, `seo-geo`, `brand-voice`, `social-publisher`) with the
+reason; `capability` is a graded scenario with a `must_include` rubric. There is no
+automated runner here — drive a model with each prompt, check routing for the trigger
+sets, and score the capability answer against every rubric bullet (own-it reply,
+do-NOT-flag-a-legit-negative, the 24-48h SLA, an FTC-clean no-gating request flow, and
+the +0.7-star / $53,088 rationale). For the copy this skill emits, also run
+`../scripts/verify.sh` against a request template or reply to confirm it has no gating,
+sentiment-incentive, or dead-Q&A-API phrasing.

package/skills/review-management/evals/cases.yaml

@@ -0,0 +1,60 @@
+skill: review-management
+
+# review-management owns the PUBLIC review and the AGGREGATE reputation it rolls
+# up to: earning reviews legally (FTC-clean request flow), replying on-voice within
+# the 24-48h SLA, deciding reply-vs-flag, and the cross-surface scorecard (Google
+# Business Profile, Trustpilot, App Store, Google Play). It does NOT handle private
+# 1:1 tickets (customer-support), churn/save plays (retention), ranking beyond
+# reviews (seo-geo), authoring the voice (brand-voice), or scheduling posts
+# (social-publisher).
+should_trigger:
+  - prompt: "A customer left us a 2-star Google review complaining about wait times — draft a reply."
+    why: "Core job: an on-voice public reply to a specific negative, within the 48h SLA, own-it-and-move-offline shape."
+
+  - prompt: "We want more Trustpilot reviews but only have 12 — set up a request flow."
+    why: "Earn-reviews flow: Trustpilot Invitation API, 24-48h timing, channel choice, FTC-clean no-gating ask."
+
+  - prompt: "Are we allowed to only ask our happy customers to leave reviews?"
+    why: "Non-obvious: the user doesn't name reviews-management, they ask a compliance question. The FTC gating rule lives here and the answer must be a clear NO."
+
+  - prompt: "Someone posted an obviously fake 1-star — can we get it removed or just reply?"
+    why: "The reply-vs-flag decision is owned here: flag only for fake/off-topic/conflict/policy, else reply."
+
+  - prompt: "Respon aquesta ressenya d'una estrella d'un client emprenyat."
+    why: "Catalan phrasing for a public 1-star reply — same skill regardless of language; the negative-review sequence applies."
+
+  - prompt: "Build me a dashboard of our rating and response rate across Google and the App Store."
+    why: "The reputation scorecard (rating, volume, velocity, recency, response-rate, sentiment-by-theme) across surfaces is owned here."
+
+  - prompt: "How do I post a developer reply to a Google review programmatically — what endpoint and scope?"
+    why: "Non-obvious wiring trigger: the GBP v4 updateReply PUT endpoint + business.manage scope + verified-location gate are the load-bearing facts this skill holds."
+
+should_not_trigger:
+  - prompt: "A customer emailed support angry about a refund — write the reply."
+    route_to: customer-support
+    why: "Private 1:1 channel against an SLA; no future prospect reads it. The public-vs-private line routes this to support."
+
+  - prompt: "Our churn is up; build a save play for at-risk accounts."
+    route_to: retention
+    why: "A bad review may signal churn, but the save play / win-back sequence is retention's job."
+
+  - prompt: "Make our location page rank in the Google local pack."
+    route_to: seo-geo
+    why: "Ranking levers beyond reviews — schema, on-page, GEO, local-pack signals — are seo-geo."
+
+  - prompt: "Define our brand's tone of voice so replies sound consistent."
+    route_to: brand-voice
+    why: "This skill consumes the voice guide; brand-voice authors it (traits, word bank, tone matrix)."
+
+  - prompt: "Turn this 5-star review into an Instagram carousel and schedule it."
+    route_to: social-publisher
+    why: "Repurposing + scheduling the post is social-publisher; review-management only owns the reply to the review itself."
+
+capability:
+  - scenario: "We got a specific, fair 1-star Google review about a botched install. Reply on-voice, tell me whether to flag it, and what to put in our review-request flow so this doesn't tank our rating."
+    must_include:
+      - "A reply that names the specific issue (the botched install), owns it, moves the customer to a private channel, states a concrete fix, and shows no defensiveness or public arguing."
+      - "An explicit 'do NOT flag this — it is a legitimate negative' with the flag-only-for-{fake / off-topic / conflict-of-interest / policy-violation} rule."
+      - "The 24-48h response SLA stated for the reply (within 24h helps ranking; reply to every review within 48h)."
+      - "An FTC-clean request flow: ask EVERY customer (no gating), within 24-48h of the transaction, via SMS and/or email with a direct link to the public review form."
+      - "Rationale citing the ~+0.7-star average lift from a developer/business response AND the FTC gating penalty of up to $53,088 per violation."

package/skills/review-management/references/platform-apis.md

@@ -0,0 +1,86 @@
+# Platform APIs — review surfaces
+
+Per-surface wiring: endpoints, auth, roles, limits, and the gotchas that bite. Facts
+dated 2026-06-02. APIs here change faster than the playbook — confirm against the live
+docs before you ship a quota-sensitive integration.
+
+## Google Business Profile (GBP)
+
+**Still on v4 for reviews.** Review management was *not* migrated to the v1 Business
+Profile APIs and has no announced deprecation. List and reply both live under v4.
+
+- **Reply (create or update):**
+  ```text
+  PUT https://mybusiness.googleapis.com/v4/{name=accounts/*/locations/*/reviews/*}/reply
+  body: { "comment": "your reply text" }
+  ```
+  The same `PUT` creates a reply if none exists and overwrites it if one does. There is
+  one reply per review.
+- **Delete a reply:**
+  ```text
+  DELETE https://mybusiness.googleapis.com/v4/{name=...}/reply
+  ```
+- **Auth:** OAuth 2.0, scope `https://www.googleapis.com/auth/business.manage`.
+- **Gate:** only **verified** locations can reply. Unverified → the call fails.
+- **Dead — do not build:** the **Questions-and-Answers API was shut down in November
+  2025.** Any `.../questions` endpoint is gone. Review listing + reply survive; Q&A does
+  not. If old code references Q&A, rip it out.
+- **Quota:** GBP APIs are quota-gated per project; request increases via the API console
+  if you batch replies across many locations.
+
+## Trustpilot
+
+Two **separate** APIs — don't conflate them.
+
+- **Invitation / Invitations API** (earn reviews): generates unique service- or
+  product-review invitation links and emails.
+  - Needs: **Business Unit ID**, customer email, customer name, locale, a `reference`
+    (your order/txn id), and a **template ID**.
+  - Templates exist in **16 languages** — pass the matching `locale`.
+  - This is how you send the FTC-clean ask without gating: same invite to every
+    customer, no sentiment screen.
+- **Service Reviews API** (respond): post a public reply to a service review.
+  - Auth: **Business user OAuth token** (not the public API key).
+  - One reply per review, editable.
+
+## Apple — App Store Connect
+
+**Customer Review Responses** resource: get / create / update / delete.
+
+- **Exactly one response per review**, and it is **editable** (re-`update` to revise).
+- **Roles:** the API user must be **Account Holder, Admin, or Customer Support**. Other
+  roles can read reviews but not respond.
+- **AI review summaries (iOS 18.4+, 2025):** Apple auto-generates a summary of your
+  reviews on the product page. Recurring complaint themes now feed that digest — fixing
+  the underlying issue changes the summary, replying alone does not.
+- Auth: App Store Connect API JWT (issuer + key id + private key), standard ASC scopes.
+
+## Google Play
+
+**Reply-to-Reviews API** via the Google Play Developer API (also available in Play
+Console).
+
+- A developer response is **public** and, per Google's own figure, raises that review's
+  rating by **~0.7 stars on average** — the strongest single argument for ~100% response
+  rate.
+- **Reply window:** Play historically restricts programmatic replies to reviews within a
+  rolling window (commonly cited as ~7 days for the reply API; **confirm against the
+  current Developer API docs** before relying on it for old reviews — answer fresh ones
+  fast).
+- Auth: a Google Play service account with the Developer API enabled.
+
+## Flag / dispute paths (removal, not reply)
+
+Use these only for fake / off-topic / conflict-of-interest / policy-violation reviews —
+never for legitimate negatives.
+
+- **Google:** flag the review from the GBP reviews UI (the three-dot menu → "Report
+  review") or the Business Profile "report a review" support flow. There is no public
+  removal API — it's a human review against Google's content policy.
+- **Trustpilot:** flag the review in the Business portal with a reported reason
+  (defamatory, fake, not based on a genuine experience, etc.); Trustpilot adjudicates.
+- **Apple / Google Play:** report policy-violating reviews through the respective
+  console; removal is at the platform's discretion.
+
+Expect days, not minutes — and expect most legitimate-but-harsh reviews to stay up.
+Plan to reply, not to delete.

package/skills/review-management/scripts/verify.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+#
+# verify.sh — FTC copy-banlist linter for review-request & reply copy.
+#
+# WHAT IT DOES (read-only; never edits or writes a file)
+#   Static, network-free scan over ONE copy file you point it at (a review-request
+#   template, a reply, or a config snippet) — or stdin. It catches the three ways
+#   review copy crosses the FTC Consumer Review Rule line, plus the dead Q&A API:
+#
+#     1. GATING / sentiment-screen phrasing (HARD FAIL) — e.g. "if you loved",
+#        "only if you're happy", "had a bad experience? contact us instead",
+#        "give us 5 stars", "rate us 5". FTC review-suppression risk.
+#     2. INCENTIVE-BY-SENTIMENT phrasing (HARD FAIL) — e.g. "leave a positive
+#        review", "in exchange for a good review", "discount for a 5-star".
+#        You may incentivize a review; you may NOT condition it on sentiment.
+#     3. DEAD-API usage (HARD FAIL) — a "...googleapis.com/v4/.../questions"
+#        endpoint or the literal "Q&A API" in config. Shut down Nov 2025.
+#
+#   A clean OR empty/missing-content file (or empty stdin) exits 0 — no false fail.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh review-copy.md          # scan a file
+#   cat reply.txt | ./verify.sh -        # scan stdin
+#   ./verify.sh -h                       # this help
+#
+# EXIT CODES
+#   0  clean, or empty/missing-content input
+#   1  one or more banlist hits (each printed with its line number)
+#   2  bad usage (no input given, or file does not exist)
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, no bc.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+hit()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; }
+note() { printf '%s%s%s\n'        "$YELLOW" "$*" "$NC"; }
+
+usage() { sed -n '2,38p' "$0" | sed 's/^# \{0,1\}//'; }
+
+INPUT=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    --) shift; INPUT="${1:-}"; shift || true ;;
+    -) INPUT="-"; shift ;;
+    -*) printf '%sunknown option: %s%s\n' "$RED" "$1" "$NC" >&2; usage; exit 2 ;;
+    *) if [ -z "$INPUT" ]; then INPUT="$1"; fi; shift ;;
+  esac
+done
+
+if [ -z "$INPUT" ]; then
+  printf '%sno input given (pass a file or "-" for stdin)%s\n' "$RED" "$NC" >&2
+  usage; exit 2
+fi
+
+# Resolve input to a temp file so we can grep with line numbers uniformly.
+TMP=""
+cleanup() { [ -n "$TMP" ] && rm -f "$TMP"; return 0; }
+trap cleanup EXIT
+
+if [ "$INPUT" = "-" ]; then
+  TMP="$(mktemp 2>/dev/null || mktemp -t revmgmt)"
+  cat > "$TMP"
+  SRC="$TMP"
+  LABEL="stdin"
+else
+  if [ ! -f "$INPUT" ]; then
+    printf '%sfile not found: %s%s\n' "$RED" "$INPUT" "$NC" >&2
+    exit 2
+  fi
+  SRC="$INPUT"
+  LABEL="$INPUT"
+fi
+
+# Empty / whitespace-only: nothing to check, never a false failure.
+if [ ! -s "$SRC" ] || ! grep -q '[^[:space:]]' "$SRC" 2>/dev/null; then
+  ok "empty input — nothing to check"
+  exit 0
+fi
+
+note "review-management verify — $LABEL"
+printf '\n'
+
+fail_count=0
+
+# Each entry: a label, then an extended-regex of banned phrasings (case-insensitive).
+# Printed with grep -nEi so every hit carries its line number.
+scan() {
+  # $1 = human label, $2 = regex
+  local label="$1" rx="$2" out
+  out="$(grep -nEi "$rx" "$SRC" 2>/dev/null || true)"
+  if [ -n "$out" ]; then
+    while IFS= read -r line; do
+      [ -n "$line" ] && hit "$label — line $line"
+      fail_count=$((fail_count + 1))
+    done <<EOF
+$out
+EOF
+  fi
+}
+
+# 1. Gating / sentiment-screen.
+scan "GATING (FTC review-suppression)" \
+  "if you('| a)?re? (loved|happy|satisfied)|if you loved|only if you('| a)?re? (happy|satisfied)|loved us\??|had a (bad|poor|negative) experience.*(contact|email|reach|instead)|tell us (privately|directly) (first|instead)|give (us|me) (a |an )?5|rate (us|me) (a |an )?5|leave (us )?(a |an )?5[ -]?star|5[ -]?stars? (please|if)|please (give|leave|rate).*5"
+
+# 2. Incentive conditioned on sentiment.
+scan "INCENTIVE-BY-SENTIMENT (FTC banned)" \
+  "leave (a |an )?positive review|positive review (in|for) (exchange|return)|in exchange for (a |an )?(good|positive|5)|discount for (a |an )?(5|positive|good)|(\\\$|€|gift).* for (a |an )?(5|positive|good) (star|review)|reward.* (positive|5[ -]?star) review"
+
+# 3. Dead Google Q&A API.
+scan "DEAD Q&A API (shut down Nov 2025)" \
+  "googleapis\.com/v4/[^[:space:]]*questions|/questions[^a-z]|\bq&a api\b|questions-?and-?answers api"
+
+printf '\n'
+if [ "$fail_count" -gt 0 ]; then
+  printf '%s%d banlist hit(s) — fix before shipping (FTC Consumer Review Rule)%s\n' \
+    "$RED" "$fail_count" "$NC"
+  exit 1
+fi
+ok "clean — no gating, sentiment-incentive, or dead-API phrasing"
+exit 0