---
title: "Categories"
description: "The twelve categories every MainSDK interface and spec belongs to, so people and coding agents find a capability in the same place."
section: "concepts"
canonical: "https://mainsdk.dev/docs/concepts/categories"
updated: "2026-10-28"
---

# Categories

> The twelve categories every MainSDK interface and spec belongs to, so people and coding agents find a capability in the same place.

Canonical: https://mainsdk.dev/docs/concepts/categories · Updated: 2026-10-28

Every MainSDK interface belongs to exactly one category, and so does every spec. The docs nav, the [interface list](https://mainsdk.dev/docs/interfaces), 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](https://mainsdk.dev/docs/interfaces) 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`, `dx` and the rest of the org list), or the `AREA` in a `MAIN-<AREA>-<NNNN>` code. A spec has both: `area: observability` and `category: security` for 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: `compute` runs 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

- [Interfaces and drivers](https://mainsdk.dev/docs/concepts/interfaces-and-drivers)
- [Every interface](https://mainsdk.dev/docs/interfaces)
- [The words we use](https://mainsdk.dev/docs/concepts/vocabulary)