@awesomate/hosting-mcp/skill/awesomate-knowledge/references/quotas-and-packs.md

Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases

# Quotas, allowances, and Ingestion Packs

Live numbers ALWAYS come from `awesomate_knowledge_status` (`usage` vs
`usage.included` + `usage.packs`). This file explains the model.

## Plan allowances

Every plan includes the Knowledge Base. The NUMBERS (pages, answers a month,
storage, business data) are not written here on purpose: they change as we learn
real usage. Read them from `awesomate_knowledge_status` (`usage.included`), or
from `awesomate_get_plan_features` for another plan.

| | Essentials | Support Plus | Pro |
|---|---|---|---|
| What it is for | Trying it out: your FAQs and an agent that answers from them | Day-to-day use | Everything, at the highest usage |
| FAQs | Yes | Yes | Yes |
| Documents, spreadsheets, web pages, pasted text | A small allowance | More | The most |
| Website chat widget, unanswered-questions inbox | Yes | Yes | Yes |
| Audio and video, scanned documents and images | No | No | Yes |
| Ingestion Packs (below) | No: the answer is an upgrade | Yes | Yes |

FAQ entries don't use up the page allowance. When an Essentials client outgrows
it, say so plainly and point to Support Plus or Pro at hub.awesomate.ai/billing;
never offer a pack, since Essentials cannot buy one.

## Ingestion Packs (overage)

One pack = **1 credit ($100)**, the user picks the dimension at purchase:
+40 media-hours OR +5,000 pages OR +2,500 answers. The storage pack is no
longer sold (packs already held still count): extra storage is the monthly
storage add-on, 1 TB for $100 a month, which the owner adds on the hub's
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.
Every monthly allowance runs from midnight on the 1st in the business's own
time zone (its Timezone on Your business), not UTC. The status reports the zone
in force as `usage.time_zone` and when the month starts again as
`usage.resets_at`; quote that date rather than working one out. An answers pack
and a media-hours pack count only for the month 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.
- Flow: state the price and what the pack adds → explicit yes → the user
  buys on the hub's Knowledge → Usage page, or you call
  `POST /api/knowledge/packs {pack}` with an `Idempotency-Key` header after
  their clear approval. Retries with the same key never double-charge.
- 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 (`usage.resets_at`); 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
every answer pack held. When it is used up, every answer route (widget, agent
chat, n8n, `ask`) returns 429 `quota_exceeded` until the 1st of next month
in the business's time zone, and a visitor sees "This assistant has reached its limit for this
month". Answers on the client's own OpenRouter key never count.

- The owner is emailed at 80% and again when the limit is reached.
- Nothing ever debits credits on its own. The ways past the limit, all applied
  straight away:
  - an answer pack: 2,500 for the rest of this month, 1 credit, via the pack
    flow above;
  - the monthly answers add-on: 2,500 more answers in every month it runs,
    $100 a month on the card, stop anytime (the paid month runs out). The
    owner adds it on the hub's Knowledge → Usage page. Don't buy it from here;
  - an upgrade.
  Packs and the add-on are Support Plus and above, so for Essentials it's the
  upgrade.
- If a 429 `quota_exceeded` comes back from `ask` or a test chat, say so
  plainly and offer those two routes. Don't retry: nothing changes until the
  month turns or the allowance rises.

## Videos watched

`usage.playback_gb` in `awesomate_knowledge_status` is the GB of video and
audio people played this month: in the hub, and on the public player for
videos anyone can watch. It is shown, not limited, so never call it an
allowance or say anything will stop.