# 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 | No | 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.
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.
- 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 (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
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
(UTC), 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.