Why

Klipstack will charge for hosted accounts: a 30-day trial, then a paid plan, with existing accounts free for a while. This lays the ground in the database and the caps before any payment provider (Polar comes later). Nothing changes until BILLING_STARTS_AT is set.

What changes

• From BILLING_STARTS_AT, each account has a plan: a 30-day trial for accounts made after it, the paid plan free for a year from it for older ones, always free for admins, or an admin's "free until" date, which replaces either. Worked out in SQL (packages/db/src/plan.ts), so web and worker agree.
• Caps follow the plan: trial (300 saves, 500 MB, 50 AI…) or paid (2,000 saves, 2 GB, 300 AI…), each its own LIMIT_TRIAL_* / LIMIT_PAID_* setting.
• A lapsed account reads, exports, organizes and deletes, and its public pages stay up. Anything new (saves, feeds, AI, publishing or updating editions and shares, highlights, notes) gets a new error, 402 subscription_required, from the commands, so web, API and MCP agree. The worker stops its feeds and topic runs.
• Admin account page: a Plan card with the state and a "free until" field, audited.
• A start date instead of an on/off switch: it also dates the founding year, so nothing is stored per account.
• Tags, saved searches and edition drafts stay open to lapsed accounts (owner's call): both already have per-account maximums.

Verification

• pnpm verify passes. New tests cover plan dates and caps, every refusal above, the API's 402, the admin change and its audit event, and the worker's filters; each was seen failing without its code.
• Demo app with billing on: the admin page in the trial, founding-year and lapsed states; setting and clearing "free until" moved an account from lapsed to free and back, with both audit events.
• A review (task, commands, security, migrations, i18n, public repo, tests) found that highlight notes, edition and share-link updates and non-monthly topic runs were still open to lapsed accounts, that an admin's past date did not end a trial, and that day arithmetic depended on the database's time zone; all fixed, with tests. Dismissed: re-extracting a failed save (keeps what the account has), the trimming difference in parsing the date.
• Not run: Playwright specs.

Risk and follow-ups

• Migration: one new, empty table, account_billing.
• Self-hosters: nothing to do; the docs say to leave BILLING_STARTS_AT unset.
• The web app, extension and iPhone app have no message of their own for subscription_required yet: the add-feed dialog would say the link is invalid. Needed before billing starts, with the trial banner.
• Later: Polar checkout and webhooks, deleting lapsed accounts after the readable period, terms of payment.