@awesomate/hosting-mcp 0.54.0 → 0.56.0

package/skill/awesomate-email/references/segmentation.md

@@ -0,0 +1,107 @@
+# Groups (segments) that a small business can actually use
+
+Read this when choosing who gets a particular email, or when the owner asks
+for "a segment", "a group", "just the people who...".
+
+In Awesomate an email goes to everyone on one list who may be emailed, and
+can't be narrowed to a group. There, groups decide what to write, which list
+fits, and when a handful of personal notes would do better than a broadcast.
+Count them with `awesomate_crm_query` and check examples with
+`awesomate_crm_rows`. On a platform that sends to groups, they also decide
+who gets it.
+
+## Start from what the business recorded
+
+In order of usefulness for a small business:
+
+1. **What they bought, booked or had done**, and when. The strongest signal
+   there is.
+2. **What is due.** Last service date plus the interval: gas appliance
+   service, hot water check, dental recall, car service, term enrolment, tax
+   lodgement, lease renewal.
+3. **What they clicked or replied to.** Interest shown in a past email.
+4. **What they told you.** Answers on a sign-up or preferences page.
+5. **Where they are.** Suburb or postcode, for anything local.
+6. **Their role.** Owner vs tenant vs landlord; who pays vs who is on site.
+
+Opens are not on this list. Apple Mail and many inbox scanners open emails
+automatically, so "opened" does not mean "read". Never build an "engaged"
+group from opens alone.
+
+## Tags: how what the business knows gets in
+
+When the email system holds contacts and email activity but not jobs or
+orders, everything else arrives as **tags**. On most platforms an n8n workflow
+can tag people when a job finishes in ServiceM8, an import brings the old
+platform's tags, and the owner can tag people by hand. In Awesomate's Contacts
+& email, tags and fields come in with an import. Tags are what most groups are
+built from, so keep them tidy:
+
+- **One idea per tag, in the owner's words, with a consistent prefix** when
+  there are many: `service: hot water`, `suburb: Carindale`, `customer:
+  regular`, `installed: 2016`. Prefixes make groups easy to read and stop
+  near-duplicates ("hotwater", "hot water", "HWS").
+- **Say where each tag comes from**: "added by the ServiceM8 workflow when a
+  job is invoiced". A tag nobody can explain is a tag nobody should send on.
+- **A tag is a fact, never permission.** Tagging someone "customer" does not
+  put them on a list or make them emailable. Only their consent does.
+- **Retire tags that stop being true** ("quote pending") or the groups built
+  on them quietly go wrong.
+- Before creating a tag, look for an existing one that means the same thing.
+
+## Recipes
+
+| Group | Rule, in a sentence |
+|---|---|
+| New in the last 30 days | Joined any list in the last 30 days. Gets the welcome, not the backlog. |
+| Active customers | Job, booking or purchase in the last 12 months. |
+| Lapsed customers | Last job or purchase more than one buying cycle ago (12 to 18 months for most services; a term for classes). |
+| Subscribers who never bought | On a list, no job or purchase ever. |
+| Due for service | Last service of type X more than its interval ago, no open booking. |
+| Clicked, didn't act | Clicked the booking or buy link in the last send, no booking or order since. |
+| Quiet for six months | No click, reply, booking or purchase in six months. Candidates for one "still want these?" email, then stop. |
+| Local | Postcode in a list, or within N km of the business. |
+| High value | Top 20% by spend in 24 months (retail), or repeat customers (services). |
+| Interested in X | Ticked X on the preferences page, or clicked an X link twice. |
+
+For retail, recency, frequency and spend (RFM) groups work well: recent and
+frequent buyers get new arrivals first; high spend but lapsed get a personal
+win-back.
+
+## Always leave out
+
+- Unsubscribed, hard-bounced and complained. Not a choice.
+- Anyone emailed in the last few days, unless the list promised more.
+- Anyone with an open complaint or a job in dispute. An offer to an unhappy
+  customer is how a complaint becomes a review.
+- Staff, family and test addresses (put them in a test group instead).
+- People whose only consent is for another list.
+
+## Never build a group from
+
+Health conditions or diagnoses, disability, financial hardship, criminal
+record, religion, ethnicity, sexuality, union or political membership, unless
+the person explicitly consented to that information being used for that
+purpose. In Australia most of these are "sensitive information" under the
+Privacy Act and need consent to collect at all. In practice: use an opt-in
+interest ("interested in our Pilates classes") instead of a condition ("has
+back pain").
+
+Also avoid groups that feel creepy even when legal: "looked at this page
+three times", "lives on your street". Use what the person would expect the
+business to know.
+
+## Size sense
+
+- Under about 20 people: consider personal emails from the owner instead of
+  a broadcast. They will out-perform any template.
+- A group that is most of the list is not a group. Ask what makes this email
+  relevant to only some people.
+- Show the count and two or three example names before using a group, so
+  the owner can spot a wrong rule ("why is my accountant in here?").
+
+## How to write a group down
+
+Name, rule as one sentence, count, and when it was counted. Groups update
+themselves: the count at send time can differ from the count at drafting,
+and each batch re-checks who may be emailed at that moment.

package/skill/awesomate-knowledge/references/ingestion-sources.md

@@ -10,9 +10,9 @@ estimating BEFORE asking approval.
 |---|---|---|
 | Web page / blog post | `add {url}` | One page per URL; extraction skips pages under ~200 chars of real text |
 | Whole site / blog | `add {sitemap, since?}` | sitemap.xml; default cap 500 pages per job — a bigger sitemap FAILS the job loudly rather than truncating silently. `since` skips entries with older `<lastmod>` |
-| YouTube / hosted video, podcast audio | `add {url}` | Transcribed (Deepgram); language defaults to English |
+| YouTube / hosted video, podcast audio | `add {url}` | **Not transcribed today**: a link to a recording is read as a web page (title and description). Pro and above only; below Pro, or in a trial, it is refused (403 `media_ingest`). To transcribe a recording, upload the file |
 | PDF / book / document / markdown | hub upload page | Text layer used; scanned pages OCR'd automatically (`auto` mode, capped at 300 OCR pages per job — over that the job fails BEFORE any vision spend) |
-| Video/audio FILES | hub upload page (≤ 100 MB) | Bigger media: host it and add by URL |
+| Video/audio FILES | hub upload page (≤ 100 MB) | Transcribed (Deepgram, language defaults to English). Pro and above, within the month's media hours. A longer recording: split or compress it and upload each part |
 | Images | hub upload page | Vision-described, then indexed |
 | Facebook export | hub upload page | The platform's facebook-export lane |
 | FAQs | Markdown file via `awesomate_knowledge_upload` | One `##` per question, so each becomes its own citable section. **Never** a Q&A spreadsheet as it is: convert it to this file, so every answer stays word for word and citable. Full recipe: [faqs.md](faqs.md) |

package/skill/awesomate-knowledge/references/quotas-and-packs.md

@@ -33,8 +33,9 @@ Knowledge → Usage page. A full library on Support Plus and up answers 402
 `addon_required` with the add-on's details when the owner can buy it, or 402
 `storage_full` with a sentence when they can't (in a trial, at the cap, or
 not the owner). Relay either one as it is; never buy anything.
-An answers pack counts only for the calendar month (UTC) it is bought in, so
-buying one late in the month buys less; say so before they confirm.
+An answers pack and a media-hours pack count only for the calendar month (UTC)
+they are bought in, so buying one late in the month buys less; say so before
+they confirm. A media-hours pack is Pro and above (audio and video are).
 
 - An ingest that would exceed included+packs returns `pack_required`. The
   tool response purchases NOTHING and queues NOTHING.
@@ -45,6 +46,20 @@ buying one late in the month buys less; say so before they confirm.
 - Insufficient credits → 402 `insufficient_credits`: top up from Billing
   first. Never loop on it.
 
+## Media hours
+
+Audio and video are Pro and above. The month's media hours are where
+transcription stops: the plan's hours, plus the one-off onboarding hours in the
+workspace's first month, plus this month's media-hours packs, plus the monthly
+media-hours add-on. Past them, a new recording is refused (`media_hours_exceeded`)
+until the 1st of next month (UTC); a recording already transcribed once is never
+charged again. The owner is told at 80% and 100%.
+
+The ways past it: a media-hours pack (40 hours for the rest of this month,
+1 credit, via the pack flow above), the monthly media-hours add-on (40 more hours
+in every month it runs, $100 a month on the card, added by the owner on Knowledge
+→ Usage; don't buy it from here), or a bigger plan.
+
 ## Answer limit
 
 Answers are a hard stop. The allowance is the plan's monthly answers plus