Categories
The twelve categories every MainSDK interface and spec belongs to, so people and coding agents find a capability in the same place.
Every MainSDK interface belongs to exactly one category, and so does every spec. The docs nav, the interface list, the agent skill, the specs index and the requirements all group by the same twelve categories, so a person browsing the docs and a coding agent loading the skill look in the same place (ADR-0065).
The twelve categories
| Category | Slug | What you find there |
|---|---|---|
| Identity and access | identity | Who the user is, which tenant they act in and what they may do: sign-in, connections, verification, API keys, tenants, permissions and policy |
| Data | data | Records and what you do with them: the database, imports, key-value cache, search, feeds, calendars and offline sync |
| AI and agents | ai | Model calls, actions and MCP tools, app agents, agent memory and remote GPU compute |
| Messaging and notifications | messaging | Reaching people and live screens: notifications, email, inbound mail, realtime updates and in-app feedback |
| Events, jobs and webhooks | events | Work that happens later or elsewhere: webhooks in and out, background jobs and durable workflows |
| Files, sharing and media | files | User uploads, share links and QR codes, app links, images and video, documents and PDFs |
| Payments and plans | payments | Taking money and deciding what each plan gets: payments, usage metering and entitlements |
| Security and privacy | security | Keeping data and the app safe: secrets, keys, cryptography, end-to-end encryption, sandboxes, rate limits, moderation, protected files and privacy rights |
| Platform, OS and network | platform | What the app uses from its machine, its network and the device platform: hosts, folders, programs, languages, location and app versions |
| Reliability and operations | reliability | Keeping the app up and telling people when it isn't: health probes, shutdown, SLOs, resource pressure, alerts and backups |
| Observability and analytics | observability | Seeing what the app does: logs, audit, telemetry and product analytics |
| Developer experience | dx | Building, configuring and testing the app: runtime settings, feature flags, schemas, the typed API and the testing kit |
The interface list shows each category's interfaces with their status. The catalog, docs/catalog/interfaces.yaml, is the source: its categories and category_summaries keys hold the list, and each interface's category says where it goes.
Where you meet them
| Place | How it groups |
|---|---|
| Docs | The Interfaces area of the nav, the interface list and the docs home, one group per category |
| Agent skill | SKILL.md has a category index; references/categories/<slug>.md holds one category's interfaces, so an agent loads only the one it needs instead of every interface |
| Specs | Each spec's front matter has category:; the specs index shows it next to the area |
| Requirements | The interface reference opens with every interface by category |
Category, area and section
Three words sound alike and mean different things:
- category: one of the twelve groups on this page, for interfaces and specs.
- area: the org topic word on a spec, an issue, an ADR and a commit scope (
auth,api,reliability,dxand the rest of the org list), or theAREAin aMAIN-<AREA>-<NNNN>code. A spec has both:area: observabilityandcategory: securityfor security events, because the work is telemetry and the reader looks for it under security. - section: a top-level key in
main.yaml(pay,alerts), or a part of the docs site (concepts,guides).
Adding something new
- A new interface goes in the category where a developer would look for it first. If two fit, pick the one its users name:
computeruns GPU jobs as workflows, but its users are building AI, so it is in AI and agents. - A new spec that owns an interface takes that interface's category. A spec that owns two interfaces in different categories, such as
config-secrets, names the one its readers look under. A spec that owns none (a CLI command, a Cloud plan) picks the category its readers would browse. - A new category needs an ADR. Twelve is a ceiling, not a target.
python3 tools/lint_align.py fails when an interface has no valid category, when a spec has no category: or one that differs from the interfaces it owns, or when a page under docs/site/interfaces/ belongs to no catalog interface, which would leave it out of the nav.
Next
Was this page helpful?