Glossary
Every term used in this site, in the order it tends to come up.
| Term | Means |
|---|---|
| Agent | A catalog listing (agents row) plus a separately hosted runtime service. The two are joined by id / slug and an OAuth clientId. |
| Slug | URL-safe identifier for an agent (e.g. ai-support). Used in /agent/:slug, /pricing/:slug, agent OAuth scopes, and tier upgrade CTAs. Immutable after publish. |
| Agent status | draft, active, coming_soon, inactive. Drafts and inactive are filtered from the public catalog. coming_soon agents render with a "Notify me" CTA backed by the waitlist. |
| Capability | A marketing bullet point — icon, title, description, sortOrder. Rendered on the agent detail page. CRUD via /agents/:agentId/capabilities. Display only. |
| Step | A "how it works" card — title, description, sortOrder. Same lifecycle as Capability. Not an execution unit. |
| Tag | A category-like label (e.g. voice, developer, sales). M:N with agents via agent_tags. Drives the catalog filter chips and the per-category color theme (themeFor). |
| Pricing Tier | A purchasable plan attached to an agent — name, price, currency, billingInterval (month / year / one_time), isFree, recommended, trialDays, featuresIncluded. Paid tiers auto-create Stripe Product + Price. |
| Metric Definition | A meterable thing an agent charges against — slug (immutable), displayName, unit, kind (fixed allocation or rolling per-cycle). Example: sessions, voice, avatar, sites, max_session_seconds. |
| Tier Quota | The quotaLimit of a MetricDefinition granted by a PricingTier. NULL = unlimited, 0 = explicit deny (feature gated off), positive int = cap. No row defaults to deny. |
| Effective Quota | baseQuota + sum(activeAddons) at consume time. The marketplace computes it atomically inside consume. |
| Addon | A grant on top of a subscription's tier quota — one_cycle (resets next period) or permanent. Created by admin grants or future purchase flows. |
| Subscription | A (userId, agentId, tierId) row with a Stripe-tracked status (active, trialing, past_due, canceled, incomplete, incomplete_expired, unpaid). Unique on (userId, agentId) where status is active or trialing. |
| Install | A (userId, agentId) row recording that a user clicked "install". Idempotent. Does not trigger provisioning or runtime. |
| Interaction | A marketing/sales event — user_signup, demo_request, notify_request, subscription_created. Fans out emails to recipients listed in interaction_recipients. Not an agent runtime event. |
| Review | A (userId, agentId) row with rating (1–5, CHECK), title, body. Unique on (agentId, userId) — second submit upserts. |
| Waitlist | Email signup for a coming_soon agent. (agentId, email) is unique. Also writes an Interaction of type notify_request. |
| OAuth client | Created automatically when an agent is created via POST /agents. Type public, no client secret, PKCE-S256 required. redirectUris lives on the agents row and is mirrored into the OAuth client row. |
| First-party agent | An agent owned by the marketplace operator. Backed by skipConsent: true so the user isn't prompted to grant scopes. |
| Scope | openid, profile, email, marketplace:role, marketplace:installs, marketplace:agentTiers, offline_access. The last issues a refresh token. |
| ID token claim | sub, email, name, picture, plus marketplace:role and marketplace:agentTiers. marketplace:installs is only in UserInfo, not ID token. |
| Tier hint | The marketplace:agentTiers claim — a snapshot of the user's tier per agent at token issue time. Always treat as a hint; the source of truth is /me/subscriptions/:agentId. |
| Quota envelope | The JSON shape returned by consume and release — { ok, status, used, effectiveQuota, remaining, resetsAt }. |
| clientReqId | An idempotency key passed by the agent backend on every consume / release call. Stored in usage_ledger. Resubmitting the same clientReqId is a no-op. |
| Platform admin | Role platform_admin. Can create/edit/delete agents and tiers, manage users, grant addons. |
| Org admin | Role org_admin. Manages own organization and members. Cannot create agents. |
| Org member | Role org_member. Read-only over the catalog, owns their own subscriptions. Default for new sign-ups. |
| ApiResponse envelope | The wrapper every non-auth endpoint returns: { requestId, timestamp, status, statusCode, data, error, pagination? }. |
| better-auth | The library that implements signup/signin, sessions, OAuth/OIDC provider, admin plugin, and JWKS. |
| Drizzle | The ORM used by the backend. pgTable with snake_case columns in SQL and camelCase in TypeScript. |
| AppConfigService | The single source of truth for environment variables. Never read process.env directly outside main.ts, migrate.ts, seed.ts. |
If a term shows up in code that isn't in this list, it's either an internal detail or a stale name. Open an issue.