From 1d76100fbb96cfa6bfa21bbad49657535b9f3d1a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 18 Oct 2026 20:58:57 +0000
Subject: [PATCH] docs: add JSDoc to VitNode core and the blog plugin

Add concise English JSDoc to the developer-facing APIs of @vitnode/core
and @vitnode/blog: plugin foundations (buildPlugin, buildApiPlugin,
bindApiPlugin, buildModule, buildRoute, manifests), the Content Engine,
fetchers and the API registry, events, cron, queues, notifications,
WebSockets, widgets, the editor adapter, routing, app configuration,
TanStack entry points, server context, AutoForm and form fields, tables,
UI primitives, and every symbol the MDX docs import. Every batch was
fact-checked against the source.

Keep JSDoc in published declarations: the shared tsconfig sets
removeComments, which stripped every comment from the .d.ts files the
package build emits.

Fixes:
- AutoFormDateTime spread its rest props after its own onChange/onBlur,
  so a caller's onChange replaced the handler that writes the form
  value. The caller's handlers now run after the form update.
- Plugin dashboard widgets never reached the AdminCP in TanStack hosts.
  They now travel on adminNav.admin.dashboard.widgets through
  admin-nav.gen.ts to the dashboard screen, which also loads the
  plugins' widget message namespaces.

Docs: fix MDX examples importing APIs that don't exist (email adapters,
search indexers, captcha, ApiPluginContract), the widget component props
and the blog post event note. AGENTS.md gains a JSDoc rule and describes
the generated plugin API registry entry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016fFJwQoQUcq6FtMdeGUaHc
---
 AGENTS.md                                     |   7 +-
 apps/web/content/docs/dev/captcha/index.mdx   |  51 +++--
 apps/web/content/docs/dev/email/index.mdx     |  28 ++-
 .../docs/dev/events/built-in-events.mdx       |   2 +-
 apps/web/content/docs/dev/fetcher.mdx         |   2 +-
 .../dev/plugins/admin/dashboard-widgets.mdx   |  81 ++++---
 apps/web/content/docs/dev/search.mdx          |  62 +++---
 .../docs/dev/widgets/defining-a-block.mdx     |   4 +-
 .../scripts/cli/builder/package-build.ts      |   8 +-
 .../vitnode/src/api/adapters/sso/discord.ts   |  27 +++
 .../vitnode/src/api/adapters/sso/facebook.ts  |  27 +++
 .../vitnode/src/api/adapters/sso/google.ts    |  27 +++
 .../vitnode/src/api/adapters/storage/local.ts |  18 ++
 packages/vitnode/src/api/builders.ts          |   1 +
 packages/vitnode/src/api/config.ts            |  25 +++
 packages/vitnode/src/api/lib/ai/action.ts     |  79 +++++++
 packages/vitnode/src/api/lib/ai/decimal.ts    |  10 +
 packages/vitnode/src/api/lib/ai/errors.ts     |  17 ++
 .../vitnode/src/api/lib/ai/html-structure.ts  |  10 +
 packages/vitnode/src/api/lib/ai/registry.ts   |   5 +
 packages/vitnode/src/api/lib/ai/usage-cost.ts |  15 ++
 .../vitnode/src/api/lib/bind-api-plugin.ts    |  20 ++
 packages/vitnode/src/api/lib/cache-client.ts  |   6 +
 packages/vitnode/src/api/lib/cache.ts         |  43 +++-
 .../src/api/lib/check-staff-permission.ts     |  34 +++
 .../vitnode/src/api/lib/content-modules.ts    |  31 +++
 packages/vitnode/src/api/lib/cron.ts          |  62 ++++++
 .../vitnode/src/api/lib/editable-pages.ts     |  15 ++
 packages/vitnode/src/api/lib/events.ts        |  41 ++++
 .../vitnode/src/api/lib/logger-middleware.ts  |   5 +
 .../src/api/lib/moderation/registry.ts        |   3 +
 .../vitnode/src/api/lib/moderation/scopes.ts  |  44 ++++
 .../vitnode/src/api/lib/moderation/targets.ts |  38 ++++
 packages/vitnode/src/api/lib/module.ts        |  41 ++++
 .../src/api/lib/notifications/registry.ts     |  93 ++++++++
 .../vitnode/src/api/lib/passkey-config.ts     |  21 ++
 .../vitnode/src/api/lib/permission-staff.ts   |  38 ++++
 packages/vitnode/src/api/lib/plugin.ts        |  73 +++++++
 packages/vitnode/src/api/lib/queue.ts         |  55 +++++
 packages/vitnode/src/api/lib/route.ts         |  60 ++++++
 .../src/api/lib/save-language-words.ts        |  25 +++
 packages/vitnode/src/api/lib/websocket.ts     |  31 +++
 .../vitnode/src/api/lib/with-pagination.ts    |  52 +++++
 .../src/api/middlewares/global.middleware.ts  |  74 +++++++
 .../api/middlewares/rate-limiter-config.ts    |  35 +++
 packages/vitnode/src/api/models/ai.ts         |  54 +++++
 packages/vitnode/src/api/models/email.ts      |  46 ++++
 packages/vitnode/src/api/models/events.ts     |  62 ++++++
 packages/vitnode/src/api/models/i18n.ts       |  24 +++
 .../src/api/models/notifications/index.ts     |  30 +++
 .../src/api/models/notifications/publish.ts   |  19 ++
 packages/vitnode/src/api/models/queue.ts      |  30 +++
 packages/vitnode/src/api/models/search.ts     |  52 ++++-
 packages/vitnode/src/api/models/sso.ts        |  29 +++
 packages/vitnode/src/api/models/storage.ts    |  61 +++++-
 packages/vitnode/src/blocks/area.ts           |   5 +
 .../vitnode/src/blocks/built-in/index.tsx     |   5 +
 packages/vitnode/src/blocks/define.ts         |  53 +++++
 packages/vitnode/src/blocks/edit.tsx          |  15 ++
 packages/vitnode/src/blocks/instance.ts       |   2 +
 packages/vitnode/src/blocks/page.tsx          |  16 ++
 packages/vitnode/src/blocks/registry.ts       |  19 ++
 packages/vitnode/src/blocks/renderer.tsx      |  21 ++
 packages/vitnode/src/blocks/schema.ts         |   7 +
 packages/vitnode/src/blocks/types.ts          |  39 ++++
 packages/vitnode/src/blocks/variant.ts        |   5 +
 packages/vitnode/src/blocks/zone-meta.ts      |  22 ++
 packages/vitnode/src/blocks/zone.tsx          |  32 +++
 .../components/ai/use-available-ai-actions.ts |   6 +
 .../confirm-action-alert-dialog.tsx           |  21 ++
 .../src/components/confirm-action/content.tsx |   3 +
 .../vitnode/src/components/date-format.tsx    |  11 +
 .../src/components/editor-provider.tsx        |   4 +
 .../form/auto-form-sheet-footer.tsx           |  28 +++
 .../vitnode/src/components/form/auto-form.tsx | 123 +++++++++++
 .../src/components/form/common/desc.tsx       |   5 +
 .../src/components/form/common/label.tsx      |   6 +
 .../src/components/form/fields/array.tsx      |  12 ++
 .../src/components/form/fields/cascader.tsx   |   7 +
 .../src/components/form/fields/checkbox.tsx   |   1 +
 .../src/components/form/fields/color.tsx      |   6 +
 .../src/components/form/fields/combobox.tsx   |  16 ++
 .../components/form/fields/date-picker.tsx    |   6 +
 .../src/components/form/fields/date-time.tsx  |  14 +-
 .../src/components/form/fields/editor.tsx     |  12 ++
 .../src/components/form/fields/emoji-icon.tsx |   5 +
 .../components/form/fields/file-shared.tsx    |  11 +
 .../form/fields/file-upload-queue.ts          |   3 +
 .../src/components/form/fields/file.tsx       |  13 ++
 .../src/components/form/fields/files.tsx      |   9 +
 .../src/components/form/fields/input-otp.tsx  |  11 +
 .../components/form/fields/input-roles.tsx    |   9 +
 .../components/form/fields/input-users.tsx    |   7 +
 .../src/components/form/fields/input.tsx      |   9 +
 .../fields/multi-lang-default-language.ts     |   6 +
 .../form/fields/multi-lang-language.ts        |  12 ++
 .../form/fields/multi-lang-presence.ts        |   5 +
 .../src/components/form/fields/multi-lang.tsx |  20 ++
 .../form/fields/nullable-number.tsx           |   7 +
 .../src/components/form/fields/number.tsx     |   2 +
 .../components/form/fields/radio-group.tsx    |   3 +
 .../src/components/form/fields/roles.ts       |   4 +
 .../src/components/form/fields/select.tsx     |   5 +
 .../src/components/form/fields/switch.tsx     |   1 +
 .../src/components/form/fields/textarea.tsx   |   4 +
 .../vitnode/src/components/logo-context.tsx   |   1 +
 .../vitnode/src/components/logo-vitnode.tsx   |   1 +
 packages/vitnode/src/components/pet/pet.tsx   |   6 +
 .../rich-text/rich-text-content.tsx           |   9 +
 .../src/components/role-format-content.tsx    |   5 +
 .../components/staff-permission/provider.tsx  |  16 ++
 .../vitnode/src/components/table/content.tsx  |   9 +
 .../components/table/data-table-content.tsx   |  19 ++
 .../src/components/table/expansion.tsx        |  11 +
 .../vitnode/src/components/table/filters.tsx  |  22 ++
 .../src/components/table/navigation.tsx       |  13 ++
 .../src/components/table/reorder-handle.tsx   |   2 +
 .../src/components/table/reorder-state.ts     |   9 +
 .../vitnode/src/components/table/reorder.tsx  |   2 +
 .../vitnode/src/components/table/row-order.ts |  13 ++
 .../src/components/table/selection.tsx        |  44 ++++
 .../vitnode/src/components/table/url-state.ts |  12 ++
 .../vitnode/src/components/ui/accordion.tsx   |  14 ++
 .../src/components/ui/alert-dialog.tsx        |  28 +++
 packages/vitnode/src/components/ui/alert.tsx  |  12 ++
 .../src/components/ui/aspect-ratio.tsx        |   4 +
 .../vitnode/src/components/ui/attachment.tsx  |  26 +++
 packages/vitnode/src/components/ui/avatar.tsx |  16 ++
 packages/vitnode/src/components/ui/badge.tsx  |   8 +
 packages/vitnode/src/components/ui/bubble.tsx |  11 +
 .../src/components/ui/button-group.tsx        |  10 +
 packages/vitnode/src/components/ui/button.tsx |  17 ++
 .../vitnode/src/components/ui/calendar.tsx    |  14 ++
 packages/vitnode/src/components/ui/card.tsx   |  10 +
 .../vitnode/src/components/ui/carousel.tsx    |  24 +++
 .../src/components/ui/cascader-utils.ts       |   4 +
 .../vitnode/src/components/ui/cascader.tsx    |  28 +++
 .../vitnode/src/components/ui/chart-utils.ts  |   6 +
 packages/vitnode/src/components/ui/chart.tsx  |  22 ++
 .../vitnode/src/components/ui/checkbox.tsx    |   4 +
 .../src/components/ui/color-picker.tsx        |   6 +
 .../src/components/ui/color-preset-picker.tsx |   4 +
 .../vitnode/src/components/ui/combobox.tsx    |  13 ++
 .../vitnode/src/components/ui/command.tsx     |  16 ++
 .../vitnode/src/components/ui/comparison.tsx  |  13 ++
 .../src/components/ui/context-menu.tsx        |   9 +
 .../vitnode/src/components/ui/copy-button.tsx |  13 ++
 .../vitnode/src/components/ui/counter.tsx     |   6 +
 .../vitnode/src/components/ui/date-picker.tsx |  14 ++
 .../src/components/ui/date-range-picker.tsx   |  26 +++
 packages/vitnode/src/components/ui/dialog.tsx |  23 ++
 packages/vitnode/src/components/ui/drawer.tsx |  20 ++
 .../src/components/ui/dropdown-menu.tsx       |  16 ++
 .../src/components/ui/dynamic-icon.tsx        |   7 +
 .../src/components/ui/editor-content.tsx      |   1 +
 packages/vitnode/src/components/ui/editor.tsx |   4 +
 .../src/components/ui/emoji-icon-picker.tsx   |   6 +
 .../vitnode/src/components/ui/emoji-icon.tsx  |   5 +
 .../src/components/ui/emoji-picker.tsx        |   4 +
 packages/vitnode/src/components/ui/empty.tsx  |   9 +
 packages/vitnode/src/components/ui/field.tsx  |  25 +++
 packages/vitnode/src/components/ui/form.tsx   |  37 ++++
 packages/vitnode/src/components/ui/frame.tsx  |  13 ++
 .../vitnode/src/components/ui/hover-card.tsx  |   6 +
 .../vitnode/src/components/ui/icon-picker.tsx |   5 +
 .../vitnode/src/components/ui/image-zoom.tsx  |   5 +
 .../vitnode/src/components/ui/input-group.tsx |  17 ++
 .../vitnode/src/components/ui/input-otp.tsx   |  12 ++
 packages/vitnode/src/components/ui/input.tsx  |   1 +
 packages/vitnode/src/components/ui/item.tsx   |  18 ++
 packages/vitnode/src/components/ui/kbd.tsx    |   2 +
 packages/vitnode/src/components/ui/label.tsx  |   1 +
 packages/vitnode/src/components/ui/marker.tsx |   9 +
 .../vitnode/src/components/ui/menubar.tsx     |  12 ++
 .../vitnode/src/components/ui/message.tsx     |  11 +
 .../src/components/ui/number-field.tsx        |  10 +
 .../vitnode/src/components/ui/page-title.tsx  |   5 +
 .../vitnode/src/components/ui/pagination.tsx  |  16 ++
 .../vitnode/src/components/ui/popover.tsx     |   8 +
 .../vitnode/src/components/ui/progress.tsx    |   7 +
 .../vitnode/src/components/ui/radio-group.tsx |   2 +
 .../vitnode/src/components/ui/resizable.tsx   |   6 +
 .../vitnode/src/components/ui/scroll-area.tsx |   4 +
 packages/vitnode/src/components/ui/select.tsx |   8 +
 .../vitnode/src/components/ui/separator.tsx   |   1 +
 packages/vitnode/src/components/ui/sheet.tsx  |  15 ++
 .../vitnode/src/components/ui/skeleton.tsx    |   3 +
 .../src/components/ui/sliding-number.tsx      |   5 +
 packages/vitnode/src/components/ui/sonner.tsx |   9 +
 .../vitnode/src/components/ui/spinner.tsx     |   5 +
 packages/vitnode/src/components/ui/switch.tsx |   4 +
 packages/vitnode/src/components/ui/tabs.tsx   |  14 ++
 .../vitnode/src/components/ui/textarea.tsx    |   3 +
 .../src/components/ui/toggle-group.tsx        |  10 +
 packages/vitnode/src/components/ui/toggle.tsx |   4 +
 .../vitnode/src/components/ui/tooltip.tsx     |  22 ++
 .../vitnode/src/components/user-format.tsx    |   4 +
 .../vitnode/src/content/admin/registry.ts     |  10 +
 packages/vitnode/src/content/cache.ts         |  43 +++-
 packages/vitnode/src/content/conflicts.ts     |   8 +
 packages/vitnode/src/content/const.ts         |   1 +
 .../vitnode/src/content/containers/define.ts  |  27 +++
 .../content/containers/server/admin-routes.ts |   5 +
 .../containers/server/public-routes.ts        |   4 +
 .../src/content/containers/server/service.ts  |  13 ++
 .../vitnode/src/content/containers/tree.ts    |   6 +
 .../vitnode/src/content/containers/types.ts   |  12 ++
 packages/vitnode/src/content/define.ts        | 115 +++++++++-
 packages/vitnode/src/content/delivery.ts      |  35 +++
 .../vitnode/src/content/editor/adapter.ts     |  12 ++
 packages/vitnode/src/content/editor/define.ts |  38 ++++
 packages/vitnode/src/content/editor/types.ts  |  26 +++
 packages/vitnode/src/content/errors.ts        |   5 +
 packages/vitnode/src/content/events.ts        |  24 +++
 packages/vitnode/src/content/fields.ts        | 124 ++++++++++-
 packages/vitnode/src/content/hash.ts          |   5 +
 packages/vitnode/src/content/ids.ts           |   5 +
 packages/vitnode/src/content/localization.ts  |   2 +
 packages/vitnode/src/content/publication.ts   |   2 +
 packages/vitnode/src/content/revisions.ts     |  12 ++
 .../vitnode/src/content/rich-text/document.ts |  20 ++
 .../vitnode/src/content/rich-text/html.ts     |   5 +
 .../src/content/rich-text/plain-text.ts       |   4 +
 packages/vitnode/src/content/schedules.ts     |   6 +
 packages/vitnode/src/content/server/actor.ts  |   5 +
 .../src/content/server/bind-content-plugin.ts |  25 +++
 .../src/content/server/delivery-effects.ts    |  13 ++
 .../src/content/server/delivery-routes.ts     |   5 +
 .../src/content/server/delivery-service.ts    |   4 +
 .../src/content/server/duplicate-effects.ts   |   7 +
 .../src/content/server/editorial-effects.ts   |  21 ++
 .../src/content/server/editorial-service.ts   |   4 +
 packages/vitnode/src/content/server/emit.ts   |   9 +
 .../server/localized-public-service.ts        |   4 +
 .../src/content/server/localized-service.ts   |   4 +
 packages/vitnode/src/content/server/model.ts  |  50 +++++
 packages/vitnode/src/content/server/module.ts |   8 +
 .../src/content/server/public-module.ts       |   8 +
 .../src/content/server/public-routes.ts       |   5 +
 .../src/content/server/public-service.ts      |  38 ++++
 .../src/content/server/public-write-routes.ts |  11 +
 .../content/server/public-write-service.ts    |  13 ++
 .../vitnode/src/content/server/publication.ts |  45 ++++
 .../src/content/server/revalidate-bridge.ts   |  14 ++
 packages/vitnode/src/content/server/routes.ts |   5 +-
 .../src/content/server/search-indexer.ts      |  15 ++
 .../vitnode/src/content/server/search-sync.ts |  19 ++
 .../vitnode/src/content/server/service.ts     |  31 +++
 packages/vitnode/src/content/server/table.ts  |  28 +++
 .../server/translation-editorial-service.ts   |   4 +
 .../src/content/server/translation-effects.ts |  10 +
 .../src/content/server/translation-model.ts   |   4 +
 .../src/content/server/translation-routes.ts  |   4 +
 .../src/content/server/translation-table.ts   |   8 +
 .../src/content/server/visibility-effects.ts  |  13 ++
 .../src/content/server/write-effects.ts       |   4 +
 packages/vitnode/src/content/sitemap.ts       |   5 +
 packages/vitnode/src/content/types.ts         | 124 +++++++++++
 packages/vitnode/src/content/visibility.ts    |   2 +
 packages/vitnode/src/editor/adapter/memory.ts |   7 +
 .../vitnode/src/editor/adapter/refusal.ts     |   2 +
 .../vitnode/src/editor/adapter/save-input.ts  |   1 +
 packages/vitnode/src/editor/adapter/types.ts  |  19 ++
 .../vitnode/src/emails/default-template.tsx   |  30 +++
 packages/vitnode/src/emails/ui/button.tsx     |   7 +
 packages/vitnode/src/emails/ui/card.tsx       |  10 +
 .../src/framework/api-registry/generate.ts    |   6 +
 .../src/framework/api-registry/types.ts       |   1 +
 .../vitnode/src/framework/dev-error/hints.ts  |  20 ++
 .../src/framework/plugin-routes/compile.ts    |  15 ++
 .../vitnode/src/framework/vite/dev-error.ts   |   5 +
 packages/vitnode/src/framework/vite/env.ts    |   9 +
 .../src/framework/vite/optimize-deps.ts       |   5 +
 .../src/framework/vite/plugin-routes.ts       |  17 ++
 .../src/framework/vite/prerender-routes.ts    |  19 ++
 .../src/framework/vite/ssr-externals.ts       |   6 +
 .../src/framework/vite/tailwind-sources.ts    |   7 +
 .../vitnode/src/framework/vite/vitnode.ts     |  20 ++
 .../vitnode/src/hooks/use-before-unload.ts    |   7 +
 packages/vitnode/src/hooks/use-captcha.ts     |  12 ++
 .../src/hooks/use-intersection-observer.ts    |   6 +
 .../vitnode/src/hooks/use-local-storage.ts    |   7 +
 packages/vitnode/src/hooks/use-mobile.ts      |   1 +
 .../src/hooks/use-sliding-indicator.ts        |  13 ++
 packages/vitnode/src/lib/ai/assist-client.ts  |  18 ++
 packages/vitnode/src/lib/ai/stream-client.ts  |  16 ++
 packages/vitnode/src/lib/config.ts            |  29 +++
 packages/vitnode/src/lib/emoji-icon.ts        |   8 +
 packages/vitnode/src/lib/fetcher-client.ts    |  15 ++
 packages/vitnode/src/lib/fetcher/raw.ts       |  16 ++
 packages/vitnode/src/lib/fetcher/registry.ts  |   4 +
 packages/vitnode/src/lib/fetcher/types.ts     |  29 ++-
 packages/vitnode/src/lib/files/resolve-alt.ts |  15 ++
 .../vitnode/src/lib/helpers/multi-lang.ts     |   5 +
 packages/vitnode/src/lib/i18n/types.ts        |  35 +++
 packages/vitnode/src/lib/metadata.ts          |  14 +-
 packages/vitnode/src/lib/navigation.ts        |  22 ++
 packages/vitnode/src/lib/plugin-manifest.ts   |  33 +++
 packages/vitnode/src/lib/plugin.ts            | 203 +++++++++++++++++-
 packages/vitnode/src/lib/query-client.ts      |   6 +
 packages/vitnode/src/page-cache/config.ts     |  14 +-
 .../vitnode/src/page-cache/store.server.ts    |   1 +
 packages/vitnode/src/routing/authoring.ts     |  14 ++
 packages/vitnode/src/routing/module.ts        |  10 +
 packages/vitnode/src/routing/tree.ts          |  64 ++++++
 .../vitnode/src/tanstack/admin/breadcrumb.tsx |  13 ++
 .../src/tanstack/admin/dashboard/route.tsx    |   1 +
 .../src/tanstack/admin/dashboard/screen.tsx   |  59 +++--
 packages/vitnode/src/tanstack/admin/index.ts  |   8 +-
 .../src/tanstack/admin/layout-route.tsx       |  18 ++
 packages/vitnode/src/tanstack/admin/nav.tsx   |  26 ++-
 .../src/tanstack/admin/permissions.tsx        |  15 ++
 packages/vitnode/src/tanstack/admin/screen.ts |   8 +
 .../src/tanstack/admin/session-query.ts       |   7 +
 packages/vitnode/src/tanstack/admin/shell.tsx |   5 +-
 packages/vitnode/src/tanstack/admin/state.ts  |   1 +
 .../src/tanstack/auth/middleware-config.ts    |  19 ++
 .../src/tanstack/auth/session-query.ts        |  30 +++
 packages/vitnode/src/tanstack/auth/state.ts   |   2 +
 .../tanstack/breadcrumb/main-breadcrumb.tsx   |   5 +
 .../vitnode/src/tanstack/breadcrumb/model.ts  |  37 ++++
 .../src/tanstack/content/delivery-page.ts     |  47 ++++
 .../vitnode/src/tanstack/fetcher/index.ts     |  46 ++++
 .../vitnode/src/tanstack/fetcher/server.ts    |  47 ++++
 packages/vitnode/src/tanstack/i18n/locale.ts  |  14 ++
 .../vitnode/src/tanstack/i18n/messages.ts     |  20 ++
 .../src/tanstack/i18n/route-messages.tsx      |  20 ++
 packages/vitnode/src/tanstack/i18n/runtime.ts |  37 ++++
 packages/vitnode/src/tanstack/icons/ssr.ts    |   8 +
 .../src/tanstack/layout/document-head.tsx     |   5 +
 .../src/tanstack/layout/document-scripts.tsx  |   5 +
 .../src/tanstack/layout/error-actions.tsx     |   1 +
 .../vitnode/src/tanstack/layout/header.tsx    |  24 +++
 .../src/tanstack/layout/main-header.tsx       |   1 +
 .../vitnode/src/tanstack/layout/not-found.tsx |   2 +
 .../src/tanstack/layout/root-providers.tsx    |   6 +
 .../src/tanstack/layout/route-error.tsx       |   4 +
 .../vitnode/src/tanstack/link/href-link.tsx   |  33 +++
 .../src/tanstack/metadata/alternates.ts       |  19 ++
 .../vitnode/src/tanstack/metadata/index.ts    |  33 ++-
 .../src/tanstack/moderation/report-button.tsx |  26 +++
 .../src/tanstack/notifications/actions.ts     |   7 +
 .../src/tanstack/notifications/bell.tsx       |   1 +
 .../vitnode/src/tanstack/page-cache/server.ts |  12 +-
 .../pending/route-pending-skeleton.tsx        |  12 ++
 .../vitnode/src/tanstack/pending/shapes.tsx   |   4 +
 .../src/tanstack/plugin-routes/authoring.ts   |  28 +++
 .../src/tanstack/plugin-routes/mount.tsx      |  24 +++
 .../src/tanstack/plugin-routes/specs.ts       |   8 +
 .../tanstack/realtime/realtime-listeners.tsx  |   5 +
 .../vitnode/src/tanstack/search/sources.ts    |  27 +++
 .../src/tanstack/search/use-record-view.ts    |  13 ++
 .../src/tanstack/start/create-start.ts        |  24 +++
 .../src/tanstack/view-transitions/index.ts    |  10 +
 .../src/tanstack/widgets/page-widgets.tsx     |  25 +++
 .../admin/layouts/sidebar/nav/nav-model.tsx   |  19 +-
 .../admin/views/content/form/context.tsx      |  25 +++
 .../views/content/form/layout-primitives.tsx  |   9 +
 .../admin/views/content/form/primitives.tsx   |  13 ++
 .../content/form/translation-freshness.ts     |  18 ++
 .../views/admin/views/content/form/values.ts  |   2 +
 .../admin/views/content/live/presence.tsx     |   7 +
 .../views/admin/views/content/live/status.tsx |   6 +
 .../views/core/users/list/users-query.ts      |   6 +
 .../views/core/users/roles/roles-query.ts     |   7 +
 packages/vitnode/src/views/auth/sso/icons.ts  |   7 +
 .../views/layouts/theme/layout-content.tsx    |  20 +-
 packages/vitnode/src/vitnode.config.ts        | 191 ++++++++++++++++
 packages/vitnode/src/ws/handle.ts             |  10 +
 packages/vitnode/src/ws/notifications.ts      |   8 +
 packages/vitnode/src/ws/provider.tsx          |   8 +
 packages/vitnode/src/ws/registry.ts           |  30 +++
 packages/vitnode/src/ws/types.ts              |   6 +
 packages/vitnode/src/ws/use-websocket.ts      |  18 ++
 plugins/blog/src/admin/content.tsx            |   8 +
 plugins/blog/src/admin/nav.tsx                |   4 +
 plugins/blog/src/api/builders.ts              |   5 +
 plugins/blog/src/api/lib/events.ts            |  33 ++-
 plugins/blog/src/config.api.ts                |  32 +++
 plugins/blog/src/config.tsx                   |  22 ++
 plugins/blog/src/content.ts                   |   6 +
 plugins/blog/src/content/category.ts          |  11 +
 plugins/blog/src/content/post.ts              |  18 ++
 plugins/blog/src/database/categories.ts       |   5 +
 plugins/blog/src/database/posts.ts            |  10 +
 plugins/blog/src/pages/post-query.ts          |  27 +++
 plugins/blog/src/plugin-info.ts               |   4 +
 plugins/blog/src/routes.ts                    |   5 +
 388 files changed, 6795 insertions(+), 145 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index d762a0d79c..d22e3fa454 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -38,7 +38,7 @@ import { Activity } from "react";
 
 - `fetcher` from `@vitnode/core/tanstack/fetcher` is universal - one call, SSR and browser. Never hand-write `createIsomorphicFn().server(...).client(...)` for a fetch.
 - A call names the plugin, never an API module: `fetcher({ plugin: "@vitnode/core", method: "get", module: "users", path: "/devices" })`. `plugin`, `module` (any nesting depth, `admin/advanced/cron`), `path`, `method`, `args` and the response are all inferred from the plugin API registry; an invalid combination is a compile error at the offending property.
-- The registry is `ApiPluginRegistry` in `@vitnode/core/lib/fetcher/registry`. Core registers itself; an app's `src/api-registry.gen.ts` registers every configured plugin that exports `config.api`, with type-only imports; a plugin registers its own API in its `global.d.ts` so its pages can call it. Never import a plugin API factory as a value outside `vitnode.api.config.ts`.
+- The registry is `ApiPluginRegistry` in `@vitnode/core/lib/fetcher/registry`. Core registers itself; an app's `src/api-registry.gen.ts` registers every configured plugin that exports `config.api`, with type-only imports; `vitnode build`/`vitnode dev` write a plugin's own entry to its `types/api-registry.gen.d.ts` (kept out of the published package) so its pages can call it. Never import a plugin API factory as a value outside `vitnode.api.config.ts`.
 - `@vitnode/core/tanstack/fetcher/server` is for work that is genuinely server-only: server functions, `allowSaveCookies` cookie relay, cron/jobs, upstream secrets or a different `origin`. Same call shape, more options.
 - Shared `views/*` query modules call `fetcher` directly - no injected transport, no browser-only twin. `@vitnode/core/lib/fetcher-client` is the framework-neutral browser primitive the universal fetcher is built on, for code that never renders on a server.
 - Write the route inline at the call site - never build a request object elsewhere and pass it in.
@@ -81,6 +81,11 @@ import { Activity } from "react";
 - Document every new feature. Keep it simple, SEO-friendly, and understandable at any skill level.
 - Friendly and lightly funny tone - don't overdo it.
 - Skip big comments; code is self-documenting.
+- Developer-facing APIs in feature code (exports of `@vitnode/core` and plugins that app or plugin authors call) need concise English JSDoc on the original declaration:
+  - Say what it is for, plus constraints, side effects, runtime (server-only, browser-only or universal) and `@throws` only when they are real and non-obvious.
+  - Document configuration properties one by one, including non-obvious defaults and constraints.
+  - Give major entry points a minimal `@example` with real imports.
+  - A behavior change updates the JSDoc in the same change. Keep tutorials in the MDX docs.
 - Request images with a comment: `// Image prompt: {here_prompt_to_generate_image}`
 - Put install commands in tabbed code blocks with correct syntax highlighting:
 
diff --git a/apps/web/content/docs/dev/captcha/index.mdx b/apps/web/content/docs/dev/captcha/index.mdx
index 45b0c78187..f1863c9565 100644
--- a/apps/web/content/docs/dev/captcha/index.mdx
+++ b/apps/web/content/docs/dev/captcha/index.mdx
@@ -48,8 +48,8 @@ Enable captcha verification on any custom Hono endpoint with `withCaptcha: true`
 import { buildRoute } from "@/api/builders"
 
 export const createCommentRoute = buildRoute({
-  withCaptcha: true, // [!code ++]
   route: {
+    withCaptcha: true, // [!code ++]
     method: "post",
     path: "/",
     responses: { 201: { description: "Comment created" } },
@@ -64,36 +64,47 @@ export const createCommentRoute = buildRoute({
 
 ### 3. Render the Frontend Widget
 
-Include `<Captcha />` in your form and supply the received token to the fetcher:
+Pass the app's captcha config to `AutoForm`. It loads the widget, keeps the submit button disabled until the captcha is ready, and hands `onSubmit` a fresh token to forward as the fetcher's `captchaToken`:
 
 ```tsx title="plugins/blog/src/views/comment-form.tsx"
-import { Captcha } from "@vitnode/core/components/captcha"
+import { AutoForm } from "@vitnode/core/components/form/auto-form"
+import { AutoFormTextarea } from "@vitnode/core/components/form/fields/textarea"
+import { useMiddlewareConfigQuery } from "@vitnode/core/tanstack/auth"
 import { fetcher } from "@vitnode/core/tanstack/fetcher"
+import { z } from "zod"
+
+const formSchema = z.object({ text: z.string().min(1) })
 
 export const CommentForm = () => {
-  const [captchaToken, setCaptchaToken] = React.useState<string>()
-
-  const handleSubmit = async () => {
-    await fetcher({
-      plugin: "@acme/blog",
-      method: "post",
-      module: "comments",
-      path: "/",
-      captchaToken, // [!code ++]
-      args: { body: { text: "Nice article!" } },
-    })
-  }
+  const { data: config } = useMiddlewareConfigQuery()
 
   return (
-    <form onSubmit={handleSubmit}>
-      <textarea />
-      <Captcha onVerify={setCaptchaToken} />
-      <button disabled={!captchaToken}>Submit Comment</button>
-    </form>
+    <AutoForm
+      captcha={config.captcha} // [!code ++]
+      fields={[
+        {
+          id: "text",
+          component: (props) => <AutoFormTextarea {...props} label="Comment" />,
+        },
+      ]}
+      formSchema={formSchema}
+      onSubmit={async (values, form, { captchaToken }) => {
+        await fetcher({
+          plugin: "@acme/blog",
+          method: "post",
+          module: "comments",
+          path: "/",
+          captchaToken, // [!code ++]
+          args: { body: values },
+        })
+      }}
+    />
   )
 }
 ```
 
+`useMiddlewareConfigQuery` suspends until the config loads, so render the form under a `Suspense` boundary. Outside `AutoForm`, use the `useCaptcha` hook from `@vitnode/core/hooks/use-captcha`: it returns `isReady`, `getToken()` and `onReset()`, and for Turnstile your form must contain an element with `id="vitnode_captcha"`.
+
 ---
 
 ## Supported Providers
diff --git a/apps/web/content/docs/dev/email/index.mdx b/apps/web/content/docs/dev/email/index.mdx
index 0f7f11aa78..bec8356017 100644
--- a/apps/web/content/docs/dev/email/index.mdx
+++ b/apps/web/content/docs/dev/email/index.mdx
@@ -71,39 +71,45 @@ use this for every send.
 
 Configure your delivery transport in `apps/api/src/vitnode.api.config.ts`:
 
+Each provider ships as its own package. Install one, then pass it as `email.adapter` - the sender address belongs to the adapter.
+
 ### 1. Resend Adapter
 
 ```ts title="apps/api/src/vitnode.api.config.ts"
-import { ResendEmailAdapter } from '@vitnode/core/api/adapters/email/resend'
+import { ResendEmailAdapter } from '@vitnode/resend'
 
 export const vitNodeApiConfig = buildApiConfig({
   email: {
-    from: 'noreply@yourdomain.com',
     adapter: ResendEmailAdapter({
-      apiKey: process.env.RESEND_API_KEY!,
+      apiKey: process.env.RESEND_API_KEY,
+      from: process.env.RESEND_FROM_EMAIL,
     }),
   },
 })
 ```
 
-### 2. SMTP Adapter
+See [Resend](/docs/dev/email/resend) for installation and setup.
+
+### 2. SMTP Adapter (Nodemailer)
 
 ```ts title="apps/api/src/vitnode.api.config.ts"
-import { SmtpEmailAdapter } from '@vitnode/core/api/adapters/email/smtp'
+import { NodemailerEmailAdapter } from '@vitnode/nodemailer'
 
 export const vitNodeApiConfig = buildApiConfig({
   email: {
-    from: 'noreply@yourdomain.com',
-    adapter: SmtpEmailAdapter({
-      host: process.env.SMTP_HOST!,
-      port: Number(process.env.SMTP_PORT ?? 587),
-      user: process.env.SMTP_USER!,
-      password: process.env.SMTP_PASSWORD!,
+    adapter: NodemailerEmailAdapter({
+      from: process.env.NODE_MAILER_FROM,
+      host: process.env.NODE_MAILER_HOST,
+      port: Number(process.env.NODE_MAILER_PORT ?? 587),
+      user: process.env.NODE_MAILER_USER,
+      password: process.env.NODE_MAILER_PASSWORD,
     }),
   },
 })
 ```
 
+`port` defaults to `587` and `secure` to `false`. See [Nodemailer](/docs/dev/email/nodemailer) for installation and setup.
+
 ---
 
 ## Testing Email in AdminCP
diff --git a/apps/web/content/docs/dev/events/built-in-events.mdx b/apps/web/content/docs/dev/events/built-in-events.mdx
index 098bef4cb3..6fb07331e5 100644
--- a/apps/web/content/docs/dev/events/built-in-events.mdx
+++ b/apps/web/content/docs/dev/events/built-in-events.mdx
@@ -1292,7 +1292,7 @@ categories yet.
     },
     categoryId: {
       description:
-        "The post's first category. An article is in many categories now and this payload has room for one - watch content.blog.post.created for the whole set.",
+        "The post's first category. An article is in many categories now and this payload has room for one. content.blog.post.created only carries the contentId, so read the full set from the article's relations.",
       type: 'number',
     },
   }}
diff --git a/apps/web/content/docs/dev/fetcher.mdx b/apps/web/content/docs/dev/fetcher.mdx
index 794d153e93..41083a5018 100644
--- a/apps/web/content/docs/dev/fetcher.mdx
+++ b/apps/web/content/docs/dev/fetcher.mdx
@@ -100,7 +100,7 @@ The response is status-aware: `response.status` is typed as a union of declared
 Each plugin exports a lightweight contract type from its `config.api.ts`:
 
 ```ts title="plugins/site-notes/src/config.api.ts"
-import type { ApiPluginContract } from '@vitnode/core/lib/fetcher'
+import type { ApiPluginContract } from '@vitnode/core/api/lib/plugin'
 
 export type VitNodeApiPlugin = ApiPluginContract<
   ReturnType<typeof siteNotesApiPlugin>
diff --git a/apps/web/content/docs/dev/plugins/admin/dashboard-widgets.mdx b/apps/web/content/docs/dev/plugins/admin/dashboard-widgets.mdx
index ef204390fb..68d5946f94 100644
--- a/apps/web/content/docs/dev/plugins/admin/dashboard-widgets.mdx
+++ b/apps/web/content/docs/dev/plugins/admin/dashboard-widgets.mdx
@@ -7,8 +7,8 @@ icon: LayoutDashboard
 import { BarChart3Icon, Settings2Icon } from 'lucide-react'
 
 Dashboard widgets are **AdminCP plugin extensions**. Define the component and
-register it in the same plugin factory that owns the feature; the host dashboard
-then discovers it automatically.
+list it on the plugin's `adminNav` export, next to its sidebar entries; the
+AdminCP dashboard then discovers it automatically.
 
 {/* Image prompt: VitNode AdminCP dashboard with a “Site notes” statistics widget in a draggable grid. Show the widget panel, the corner resize bracket on each card, and the settings gear. Dark theme, 1600x900. */}
 
@@ -33,34 +33,39 @@ export const StatsWidget = ({ settings }: AdminDashboardWidgetProps) => (
   </Step>
   <Step>
 
-### Register it in the existing plugin factory
+### Register it on the plugin's `adminNav`
+
+Add it to the `adminNav` your plugin exports from its `admin/nav` module (the
+same object that holds its [sidebar entries](/docs/dev/plugins/admin)). VitNode
+collects every plugin's `adminNav` into the app's generated `admin-nav.gen.ts`,
+and the AdminCP shell hands the widgets to the dashboard.
+
+```tsx title="plugins/site-notes/src/admin/nav.tsx"
+import type { AdminNavPluginSource } from '@vitnode/core/lib/plugin'
 
-```tsx title="plugins/site-notes/src/config.tsx"
 import { BarChart3Icon } from 'lucide-react'
 
-import { StatsWidget } from './views/admin/widgets/stats-widget'
-
-export const siteNotesPlugin = () =>
-  buildPlugin({
-    admin: {
-      dashboard: {
-        widgets: [
-          // [!code ++:9]
-          {
-            component: StatsWidget,
-            defaultEnabled: true,
-            defaultRows: 1,
-            defaultSpan: 1,
-            icon: <BarChart3Icon />,
-            id: 'stats',
-          },
-        ],
-      },
+import { manifest } from '@/manifest.gen'
+import { StatsWidget } from '@/views/admin/widgets/stats-widget'
+
+export const adminNav = {
+  pluginId: manifest.id,
+  admin: {
+    dashboard: {
+      widgets: [
+        // [!code ++:8]
+        {
+          component: StatsWidget,
+          defaultEnabled: true,
+          defaultRows: 1,
+          defaultSpan: 1,
+          icon: <BarChart3Icon />,
+          id: 'stats',
+        },
+      ],
     },
-    messages,
-    pluginId: '@acme/site-notes',
-    routes,
-  })
+  },
+} satisfies AdminNavPluginSource
 ```
 
 The full widget id is namespaced by the plugin, so `stats` will not collide with
@@ -70,13 +75,35 @@ enough already.
   </Step>
   <Step>
 
+### Name it
+
+The widget's title comes from your plugin's frontend messages, under
+`admin.dashboard.widgets.{id}`. A `desc` is optional and shows in the widget panel.
+
+```json title="plugins/site-notes/src/locales/en.json"
+{
+  "@acme/site-notes": {
+    "admin": {
+      "dashboard": {
+        "widgets": {
+          "stats": { "title": "Note stats", "desc": "How many notes are live." }
+        }
+      }
+    }
+  }
+}
+```
+
+  </Step>
+  <Step>
+
 ### Add a permission or settings UI when needed
 
 Add `permission` to hide a widget from staff who should not see it. Add
 `settingsComponent` when administrators need to save preferences; both stay in
 the plugin alongside the widget.
 
-```tsx title="plugins/site-notes/src/config.tsx"
+```tsx title="plugins/site-notes/src/admin/nav.tsx"
 {
   component: StatsWidget,
   // [!code ++:4]
diff --git a/apps/web/content/docs/dev/search.mdx b/apps/web/content/docs/dev/search.mdx
index d1732a04e2..ba93fa35b4 100644
--- a/apps/web/content/docs/dev/search.mdx
+++ b/apps/web/content/docs/dev/search.mdx
@@ -52,45 +52,55 @@ await c.get('search').delete('article', article.id)
 
 ### Register a rebuild indexer
 
-To allow admins to re-index all historical content from the AdminCP, register a search indexer in your plugin's `config.api.ts`:
+To allow admins to re-index all historical content from the AdminCP, give your plugin a search indexer. It rebuilds one item type page by page: `load` returns the documents for up to `limit` source rows starting at `offset`, plus how many rows it read (`0` ends the rebuild). `count` is optional and powers the coverage report.
 
-```ts title="plugins/blog/src/api/indexers/post.indexer.ts"
-import { buildSearchIndexer } from '@vitnode/core/api/lib/search'
-import { blog_posts } from '@/database/posts'
+<Callout type="info" title="Content types index themselves">
+  A Content Engine type with `search` enabled gets its indexer automatically.
+  Write one only for data of your own.
+</Callout>
 
-export const postSearchIndexer = buildSearchIndexer({
-  itemType: 'article',
-  totalCount: async (c) => {
-    return await c.get('db').$count(blog_posts)
-  },
-  batch: async (c, { limit, offset }) => {
-    const posts = await c
+```ts title="plugins/recipes/src/api/indexers/recipe.indexer.ts"
+import type { SearchIndexer } from '@vitnode/core/api/models/search'
+
+import { asc } from 'drizzle-orm'
+
+import { recipes } from '@/database/recipes'
+
+export const recipeSearchIndexer: SearchIndexer = {
+  itemType: 'recipe',
+  count: async (c) => await c.get('db').$count(recipes),
+  load: async (c, offset, limit) => {
+    const rows = await c
       .get('db')
       .select()
-      .from(blog_posts)
+      .from(recipes)
+      .orderBy(asc(recipes.id))
       .limit(limit)
       .offset(offset)
 
-    return posts.map((post) => ({
-      itemType: 'article',
-      itemId: post.id,
-      title: post.title,
-      content: post.content,
-      url: `/articles/${post.slug}`,
-      authorIds: [post.authorId],
-      createdAt: post.createdAt,
-    }))
+    return {
+      documents: rows.map((recipe) => ({
+        itemType: 'recipe',
+        itemId: recipe.id,
+        title: recipe.title,
+        content: recipe.description,
+        url: `/recipes/${recipe.slug}`,
+        authorIds: [recipe.authorId],
+        createdAt: recipe.createdAt,
+      })),
+      itemsRead: rows.length,
+    }
   },
-})
+}
 ```
 
-Register it in `config.api.ts`:
+Register it in `config.api.ts` (a module's `searchIndexers` works too):
 
-```ts title="plugins/blog/src/config.api.ts"
-export const blogApiPlugin = () =>
+```ts title="plugins/recipes/src/config.api.ts"
+export const recipesApiPlugin = () =>
   buildApiPlugin({
     manifest,
-    searchIndexers: [postSearchIndexer], // [!code ++]
+    searchIndexers: [recipeSearchIndexer], // [!code ++]
   })
 ```
 
diff --git a/apps/web/content/docs/dev/widgets/defining-a-block.mdx b/apps/web/content/docs/dev/widgets/defining-a-block.mdx
index 068f73f1de..fc4935275e 100644
--- a/apps/web/content/docs/dev/widgets/defining-a-block.mdx
+++ b/apps/web/content/docs/dev/widgets/defining-a-block.mdx
@@ -67,7 +67,7 @@ The icon only shows up in the editor. Your widget's component on the public page
 ```ts
 interface WidgetComponentProps<TData> {
   /** The instance's own stable id - not the widget's. */
-  widgetId: string
+  blockId: string
   data: TData
   index: number
   type: string
@@ -75,7 +75,7 @@ interface WidgetComponentProps<TData> {
 }
 ```
 
-`data` has already been through the widget's schema when the component runs, so a component never checks for missing fields. `variant` is the look this instance picked, and is `undefined` for a widget that offers none.
+`data` is checked against the widget's schema when the page is saved, and its shape is checked again before render, so a component never checks for missing fields. Defaults are filled in when it is saved, not at render. `variant` is the look this instance picked, and is `undefined` for a widget that offers none.
 
 <Callout type="warn" title="A text field is not a safe link">
   The schema checks that a `field.text()` is a string, not that it is a URL you want people clicking. If your widget turns one into an `href`, check it with `isValidNavigationHref` from `@vitnode/core/lib/navigation` first - it allows a site path (`/discover`) or an `https://` URL and refuses `javascript:` and friends. Core's Hero and Call to action widgets simply leave the link out when it fails.
diff --git a/packages/vitnode/scripts/cli/builder/package-build.ts b/packages/vitnode/scripts/cli/builder/package-build.ts
index 99711709f1..f29e063926 100644
--- a/packages/vitnode/scripts/cli/builder/package-build.ts
+++ b/packages/vitnode/scripts/cli/builder/package-build.ts
@@ -320,7 +320,13 @@ export const packageTsdownConfig = ({
   dts:
     output === "javascript"
       ? false
-      : { eager: true, emitDtsOnly: output === "declarations" },
+      : {
+          // The shared tsconfig sets `removeComments`, which would strip the
+          // JSDoc an IDE shows on hover from every published declaration.
+          compilerOptions: { removeComments: false },
+          eager: true,
+          emitDtsOnly: output === "declarations",
+        },
   entry: listPackageEntries(root),
   fixedExtension: false,
   format: "esm",
diff --git a/packages/vitnode/src/api/adapters/sso/discord.ts b/packages/vitnode/src/api/adapters/sso/discord.ts
index a6b0d470a0..9ecfd08341 100644
--- a/packages/vitnode/src/api/adapters/sso/discord.ts
+++ b/packages/vitnode/src/api/adapters/sso/discord.ts
@@ -28,11 +28,38 @@ const discordAvatarUrl = ({
   return `https://cdn.discordapp.com/avatars/${id}/${avatar}.png?size=512`;
 };
 
+/**
+ * Sign in with Discord: an SSO adapter for the API config's
+ * `authorization.ssoAdapters`. Requests the `identify email` scopes and
+ * redirects back to `login/sso/discord` under `VITNODE_WEB_URL` - register that URL
+ * as the OAuth redirect URI. Refuses (`400`) a Discord account whose email is not verified. Supplies the avatar for profile sync.
+ *
+ * Server-only.
+ *
+ * @example
+ * ```ts
+ * import { DiscordSSOApiPlugin } from "@vitnode/core/api/adapters/sso/discord";
+ *
+ * buildApiConfig({
+ *   authorization: {
+ *     ssoAdapters: [
+ *       DiscordSSOApiPlugin({
+ *         clientId: process.env.DISCORD_CLIENT_ID,
+ *         clientSecret: process.env.DISCORD_CLIENT_SECRET,
+ *       }),
+ *     ],
+ *   },
+ *   // ...
+ * });
+ * ```
+ */
 export const DiscordSSOApiPlugin = ({
   clientId = "",
   clientSecret = "",
 }: {
+  /** The OAuth client ID. `undefined` still registers the button, but signing in throws until it is set. */
   clientId: string | undefined;
+  /** The OAuth client secret. Needed to exchange the code; signing in throws without it. */
   clientSecret: string | undefined;
 }): SSOApiPlugin => {
   const id = "discord";
diff --git a/packages/vitnode/src/api/adapters/sso/facebook.ts b/packages/vitnode/src/api/adapters/sso/facebook.ts
index c1d12b3e6b..6a899e2f2a 100644
--- a/packages/vitnode/src/api/adapters/sso/facebook.ts
+++ b/packages/vitnode/src/api/adapters/sso/facebook.ts
@@ -17,11 +17,38 @@ export const FACEBOOK_GRAPH_VERSION = "v26.0";
 const FACEBOOK_USER_FIELDS =
   "id,name,email,first_name,last_name,picture.width(512).height(512){url,is_silhouette}";
 
+/**
+ * Sign in with Facebook: an SSO adapter for the API config's
+ * `authorization.ssoAdapters`. Requests the `public_profile,email` scopes and
+ * redirects back to `login/sso/facebook` under `VITNODE_WEB_URL` - register that URL
+ * as the OAuth redirect URI. Supplies the avatar, first and last name for profile sync.
+ *
+ * Server-only.
+ *
+ * @example
+ * ```ts
+ * import { FacebookSSOApiPlugin } from "@vitnode/core/api/adapters/sso/facebook";
+ *
+ * buildApiConfig({
+ *   authorization: {
+ *     ssoAdapters: [
+ *       FacebookSSOApiPlugin({
+ *         clientId: process.env.FACEBOOK_CLIENT_ID,
+ *         clientSecret: process.env.FACEBOOK_CLIENT_SECRET,
+ *       }),
+ *     ],
+ *   },
+ *   // ...
+ * });
+ * ```
+ */
 export const FacebookSSOApiPlugin = ({
   clientId,
   clientSecret,
 }: {
+  /** The OAuth client ID. `undefined` still registers the button, but signing in throws until it is set. */
   clientId: string | undefined;
+  /** The OAuth client secret. Needed to exchange the code; signing in throws without it. */
   clientSecret: string | undefined;
 }): SSOApiPlugin => {
   const id = "facebook";
diff --git a/packages/vitnode/src/api/adapters/sso/google.ts b/packages/vitnode/src/api/adapters/sso/google.ts
index e2ab02df39..89af62a7bf 100644
--- a/packages/vitnode/src/api/adapters/sso/google.ts
+++ b/packages/vitnode/src/api/adapters/sso/google.ts
@@ -12,11 +12,38 @@ import { GOOGLE_ICON } from "./icons";
 // A provider that stops answering would otherwise hang the sign-in request.
 const PROVIDER_TIMEOUT_MS = 10_000;
 
+/**
+ * Sign in with Google: an SSO adapter for the API config's
+ * `authorization.ssoAdapters`. Requests the `openid profile email` scopes and
+ * redirects back to `login/sso/google` under `VITNODE_WEB_URL` - register that URL
+ * as the OAuth redirect URI. Refuses (`400`) a Google account whose email is not verified. Supplies the avatar, first and last name for profile sync.
+ *
+ * Server-only.
+ *
+ * @example
+ * ```ts
+ * import { GoogleSSOApiPlugin } from "@vitnode/core/api/adapters/sso/google";
+ *
+ * buildApiConfig({
+ *   authorization: {
+ *     ssoAdapters: [
+ *       GoogleSSOApiPlugin({
+ *         clientId: process.env.GOOGLE_CLIENT_ID,
+ *         clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+ *       }),
+ *     ],
+ *   },
+ *   // ...
+ * });
+ * ```
+ */
 export const GoogleSSOApiPlugin = ({
   clientId,
   clientSecret,
 }: {
+  /** The OAuth client ID. `undefined` still registers the button, but signing in throws until it is set. */
   clientId: string | undefined;
+  /** The OAuth client secret. Needed to exchange the code; signing in throws without it. */
   clientSecret: string | undefined;
 }): SSOApiPlugin => {
   const id = "google";
diff --git a/packages/vitnode/src/api/adapters/storage/local.ts b/packages/vitnode/src/api/adapters/storage/local.ts
index 5c7b0d6add..9c17467d42 100644
--- a/packages/vitnode/src/api/adapters/storage/local.ts
+++ b/packages/vitnode/src/api/adapters/storage/local.ts
@@ -9,11 +9,29 @@ import type {
 
 import { CONFIG } from "@/lib/config";
 
+/**
+ * Stores uploads on the API server's disk, under `public/uploads` in the
+ * process's working directory. For development and single-server installs; use
+ * a cloud adapter when the API runs on more than one machine or on an
+ * ephemeral filesystem.
+ *
+ * Files are served only once the app mounts `serveStatic` from the adapter's
+ * `static` descriptor in its server entry. Server-only.
+ *
+ * @example
+ * ```ts
+ * import { LocalStorageAdapter } from "@vitnode/core/api/adapters/storage/local";
+ *
+ * buildApiConfig({ storage: { adapter: LocalStorageAdapter() } });
+ * ```
+ */
 export const LocalStorageAdapter = ({
   baseUrl,
   publicPath = "/api/uploads",
 }: {
+  /** The origin public URLs start with. Defaults to the origin of `VITNODE_API_URL` (`http://localhost:3000` when unset). */
   baseUrl?: string;
+  /** The URL path files are served under. Defaults to `/api/uploads`. */
   publicPath?: string;
 } = {}): StorageApiPlugin => {
   // Static path segments (not a variable) so Next's file tracer can scope the
diff --git a/packages/vitnode/src/api/builders.ts b/packages/vitnode/src/api/builders.ts
index 253a8c9bd2..7d863600eb 100644
--- a/packages/vitnode/src/api/builders.ts
+++ b/packages/vitnode/src/api/builders.ts
@@ -2,4 +2,5 @@ import { manifest } from "@/manifest";
 
 import { bindApiPlugin } from "./lib/bind-api-plugin";
 
+/** Core's own builders, bound to `@vitnode/core`. Plugins bind their own with `bindApiPlugin`. */
 export const { buildModule, buildRoute } = bindApiPlugin(manifest);
diff --git a/packages/vitnode/src/api/config.ts b/packages/vitnode/src/api/config.ts
index d7c41dd5f8..121bbb8307 100644
--- a/packages/vitnode/src/api/config.ts
+++ b/packages/vitnode/src/api/config.ts
@@ -64,6 +64,29 @@ interface CSRFOptions {
   origin?: IsAllowedOriginHandler | string | string[];
 }
 
+/**
+ * Mounts VitNode on a Hono app: security headers, CORS, CSRF, the body limit,
+ * rate limiting, the per-request context (`c.get("db")`, `c.get("cache")` and
+ * friends), core and every plugin at `/{pluginId}`, cron registration, and an
+ * error handler that hides details outside development. Call it once at
+ * startup; it returns the same `app`.
+ *
+ * Server-only. Give `app` its base path (`/api`) before calling it.
+ *
+ * @throws At startup when the configuration is invalid - plugin content
+ * modules, colliding registrations, misconfigured passkeys or locale domains.
+ *
+ * @example
+ * ```ts
+ * import { OpenAPIHono } from "@hono/zod-openapi";
+ * import { VitNodeAPI } from "@vitnode/core/api/config";
+ *
+ * import { vitNodeApiConfig } from "./vitnode.api.config";
+ *
+ * const app = new OpenAPIHono().basePath("/api");
+ * VitNodeAPI({ app, vitNodeApiConfig });
+ * ```
+ */
 export function VitNodeAPI({
   app,
   cors: corsOptions,
@@ -71,7 +94,9 @@ export function VitNodeAPI({
   vitNodeApiConfig,
 }: {
   app: OpenAPIHono<Env, Schema, string>;
+  /** Replaces the default CORS policy: credentials from `VITNODE_WEB_URL` only. */
   cors?: CORSOptions;
+  /** Replaces the default CSRF check: requests from `VITNODE_WEB_URL` or the API's own origin. */
   csrf?: CSRFOptions;
   vitNodeApiConfig: VitNodeApiConfig;
 }) {
diff --git a/packages/vitnode/src/api/lib/ai/action.ts b/packages/vitnode/src/api/lib/ai/action.ts
index 4700e66fa9..e9bfe6f0d9 100644
--- a/packages/vitnode/src/api/lib/ai/action.ts
+++ b/packages/vitnode/src/api/lib/ai/action.ts
@@ -19,6 +19,7 @@ export type AiPrompt =
   | { prompt: string; system?: string };
 
 export interface AiPromptContext {
+  /** Extra guidance an admin set for this action in the AdminCP, or `null`. Append it to the system prompt. */
   instructions: null | string;
 }
 
@@ -29,18 +30,27 @@ export interface AiAuthorizeContext<Input> {
   userId: number;
 }
 
+/** The AI permission admins grant per role. Actions sharing a key share one switch and one daily counter. */
 export interface AiPermissionDescriptor {
+  /** Whether roles hold it until an admin changes it. */
   defaultGranted: boolean;
   key: string;
 }
 
+/** Per-action limits; admins can change them in the AdminCP. Ranges are in {@link AI_ACTION_LIMITS}. */
 export interface AiActionDefaults {
+  /** Runs per user per day for the action's permission; `null` (default) for no limit. */
   dailyLimit: null | number;
+  /** Images per run. Defaults to 1 with the `image-input` capability, else 0. */
   maxImages: number;
+  /** Input size, counted by `measureInput` or every string in the input. */
   maxInputCharacters: number;
   maxOutputTokens: number;
+  /** Provider retries. Defaults to 0. */
   maxRetries: number;
+  /** Tool-loop steps. Defaults to 1. */
   maxSteps: number;
+  /** Provider timeout in milliseconds. */
   timeoutMs: number;
 }
 
@@ -54,25 +64,46 @@ interface AiActionDefinitionBase<
   InputSchema extends z.ZodType,
   OutputSchema extends z.ZodType,
 > {
+  /**
+   * Who may run it: `user` through `c.get("ai").run()`, `system` through
+   * `runAsSystem()`. Defaults to `["user"]`.
+   */
   actors?: readonly AiActorType[];
+  /**
+   * Checks the caller may read the content the input refers to - the AI
+   * permission never replaces that. Required when `actors` includes `user`.
+   */
   authorize?(
     context: AiAuthorizeContext<z.output<InputSchema>>,
   ): boolean | Promise<boolean>;
+  /** Builds the prompt from the validated input. */
   buildPrompt(input: z.output<InputSchema>, context: AiPromptContext): AiPrompt;
   defaults: Partial<AiActionDefaults> &
     Pick<
       AiActionDefaults,
       "maxInputCharacters" | "maxOutputTokens" | "timeoutMs"
     >;
+  /** Message key of one sentence on what the action does. */
   description: string;
+  /** Lucide icon name in kebab case, e.g. `"languages"`. */
   icon?: string;
+  /**
+   * Lowercase, dot-separated id local to the plugin, e.g. `"excerpt.generate"`.
+   * Core stores it as `<pluginId>:<id>`.
+   */
   id: Id;
   inputSchema: InputSchema;
+  /** Characters counted against `maxInputCharacters`; by default every string in the input. */
   measureInput?(input: z.output<InputSchema>): number;
+  /** Validates the model's answer. */
   outputSchema: OutputSchema;
+  /** A permission key (not granted by default) or a full descriptor. */
   permission: AiPermissionDescriptor | string;
+  /** Whole number of 1 or more, stored with every run. Bump it when the prompt changes meaningfully. */
   promptVersion: number;
+  /** Model capabilities the action needs: at least one (normally `"text"`), plus `"structured-output"` for `output: "object"`. */
   requiredCapabilities: readonly AiModelCapability[];
+  /** Message key of a short name for the AdminCP and member settings. */
   title: string;
 }
 
@@ -82,6 +113,7 @@ export interface AiTextActionDefinition<
   OutputSchema extends z.ZodType,
 > extends AiActionDefinitionBase<Id, InputSchema, OutputSchema> {
   output: "text";
+  /** Turns the model's text into the value checked by `outputSchema`. */
   parseText(text: string, input: z.output<InputSchema>): z.input<OutputSchema>;
 }
 
@@ -95,6 +127,7 @@ export interface AiObjectActionDefinition<
 
 /* oxlint-enable typescript/method-signature-style */
 
+/** What a plugin passes to {@link defineAiAction}: a text action or a structured-object action. */
 export type AiActionDefinition<
   Id extends string = string,
   InputSchema extends z.ZodType = z.ZodType,
@@ -103,6 +136,7 @@ export type AiActionDefinition<
   | AiObjectActionDefinition<Id, InputSchema, OutputSchema>
   | AiTextActionDefinition<Id, InputSchema, OutputSchema>;
 
+/** An action after {@link defineAiAction} filled in `actors`, `defaults` and `permission`. */
 export type ResolvedAiActionDefinition<
   Id extends string = string,
   InputSchema extends z.ZodType = z.ZodType,
@@ -125,6 +159,7 @@ export type ResolvedAiActionDefinition<
 
 export type AnyAiActionDefinition = ResolvedAiActionDefinition;
 
+/** Thrown by {@link defineAiAction} when the module loads with an invalid definition. */
 export class AiActionDefinitionError extends Error {
   constructor(message: string) {
     super(message);
@@ -132,6 +167,7 @@ export class AiActionDefinitionError extends Error {
   }
 }
 
+/** Allowed range of each {@link AiActionDefaults} value. */
 export const AI_ACTION_LIMITS = {
   maxInputCharacters: { max: 1_000_000, min: 1 },
   maxOutputTokens: { max: 200_000, min: 1 },
@@ -162,6 +198,49 @@ const assertInRange = (
   }
 };
 
+/**
+ * Declares a managed AI feature. Register it in `buildApiPlugin({ aiActions })`
+ * and run it with `c.get("ai").run()`; core picks the model and enforces
+ * permissions, limits and budgets, and records every run.
+ *
+ * @throws {AiActionDefinitionError} For an invalid id, icon, permission key or
+ * `promptVersion`, an empty title or description, missing or unsupported
+ * capabilities, a default outside {@link AI_ACTION_LIMITS}, no actors, or a
+ * `user` action without `authorize`.
+ *
+ * @example
+ * ```ts
+ * import { defineAiAction } from "@vitnode/core/api/lib/ai/action";
+ * import { checkStaffPermission } from "@vitnode/core/api/lib/check-staff-permission";
+ * import { z } from "zod";
+ *
+ * export const summarizeAiAction = defineAiAction({
+ *   id: "topic.summarize",
+ *   title: "ai_actions.@acme/forum.topic_summarize.title",
+ *   description: "ai_actions.@acme/forum.topic_summarize.description",
+ *   promptVersion: 1,
+ *   permission: "summarize",
+ *   requiredCapabilities: ["text"],
+ *   defaults: { maxInputCharacters: 50_000, maxOutputTokens: 300, timeoutMs: 30_000 },
+ *   inputSchema: z.object({ content: z.string().min(1) }),
+ *   output: "text",
+ *   outputSchema: z.string().min(1),
+ *   parseText: text => text.trim(),
+ *   buildPrompt: (input, { instructions }) => ({
+ *     system: ["Summarize in two sentences.", instructions].filter(Boolean).join("\n"),
+ *     prompt: input.content,
+ *   }),
+ *   // The AI permission never replaces access to the content itself.
+ *   authorize: async ({ c }) =>
+ *     await checkStaffPermission(c, {
+ *       type: "admin",
+ *       plugin: "@acme/forum",
+ *       module: "topics",
+ *       permission: "can_view",
+ *     }),
+ * });
+ * ```
+ */
 export function defineAiAction<
   const Id extends string,
   InputSchema extends z.ZodType,
diff --git a/packages/vitnode/src/api/lib/ai/decimal.ts b/packages/vitnode/src/api/lib/ai/decimal.ts
index e48523a031..4c8e5bcb28 100644
--- a/packages/vitnode/src/api/lib/ai/decimal.ts
+++ b/packages/vitnode/src/api/lib/ai/decimal.ts
@@ -30,6 +30,16 @@ export const parseDecimalOrNull = (
 ): Decimal | null =>
   value === null || value === undefined ? null : parseDecimal(value);
 
+/**
+ * Converts a JavaScript number to a {@link Decimal} (a `bigint` with 12
+ * fractional digits), rounded half away from zero at the 12th digit (after
+ * first rounding to 14 digits). Use it for costs
+ * a provider reports as a number, e.g. in an `AiProviderAdapter`'s
+ * `reportedCost`.
+ *
+ * @throws {DecimalParseError} When `value` is `NaN`, infinite, or has a
+ * magnitude of 1e21 or more.
+ */
 export const decimalFromNumber = (value: number): Decimal => {
   if (!Number.isFinite(value)) {
     throw new DecimalParseError(String(value));
diff --git a/packages/vitnode/src/api/lib/ai/errors.ts b/packages/vitnode/src/api/lib/ai/errors.ts
index d946c92636..699be73ef4 100644
--- a/packages/vitnode/src/api/lib/ai/errors.ts
+++ b/packages/vitnode/src/api/lib/ai/errors.ts
@@ -55,5 +55,22 @@ export class AiError extends HTTPException {
   readonly code: AiErrorCode;
 }
 
+/**
+ * Whether `error` is an {@link AiError} thrown by `c.get("ai")`, so its `code`
+ * (e.g. `"AI_BUDGET_EXHAUSTED"`) can be checked.
+ *
+ * @example
+ * ```ts
+ * import { isAiError } from "@vitnode/core/api/lib/ai/errors";
+ *
+ * // `TAGS_AI_ACTION`: a key from your `defineAiAction`; `input`: its input.
+ * try {
+ *   await c.get("ai").runAsSystem({ action: TAGS_AI_ACTION, input });
+ * } catch (error) {
+ *   if (isAiError(error) && error.code === "AI_BUDGET_EXHAUSTED") return;
+ *   throw error;
+ * }
+ * ```
+ */
 export const isAiError = (error: unknown): error is AiError =>
   error instanceof AiError;
diff --git a/packages/vitnode/src/api/lib/ai/html-structure.ts b/packages/vitnode/src/api/lib/ai/html-structure.ts
index be7304893c..ce07ebeb4c 100644
--- a/packages/vitnode/src/api/lib/ai/html-structure.ts
+++ b/packages/vitnode/src/api/lib/ai/html-structure.ts
@@ -55,6 +55,16 @@ export class HtmlStructureError extends Error {
   }
 }
 
+/**
+ * Checks that a translated HTML string keeps the source's structure: the same
+ * tags in the same order, with the same attributes. Text and the `alt`,
+ * `aria-label`, `placeholder` and `title` attributes may differ; comments are
+ * ignored. Call it from an AI action's `parseText` so a translation that
+ * breaks markup or links fails the run.
+ *
+ * @throws {HtmlStructureError} With the first difference, when the structure
+ * changed.
+ */
 export const assertSameHtmlStructure = (
   source: string,
   translated: string,
diff --git a/packages/vitnode/src/api/lib/ai/registry.ts b/packages/vitnode/src/api/lib/ai/registry.ts
index 89f17897f1..b57f35741b 100644
--- a/packages/vitnode/src/api/lib/ai/registry.ts
+++ b/packages/vitnode/src/api/lib/ai/registry.ts
@@ -34,6 +34,7 @@ export interface AiActionPublicMetadata {
   title: string;
 }
 
+/** The canonical `<pluginId>:<localId>` key core stores settings, limits and history under. */
 export const aiActionKey = (pluginId: string, localId: string): AiActionKey =>
   `${pluginId}:${localId}`;
 
@@ -41,6 +42,10 @@ export type TypedAiActionKey<Input, Output> = AiActionKey & {
   readonly __aiAction?: { input: Input; output: Output };
 };
 
+/**
+ * The canonical `<pluginId>:<id>` key of an action, typed with its input and
+ * output so `c.get("ai").run({ action })` checks `input` and infers `output`.
+ */
 export const aiActionRef = <Definition extends AnyAiActionDefinition>(
   pluginId: string,
   definition: Definition,
diff --git a/packages/vitnode/src/api/lib/ai/usage-cost.ts b/packages/vitnode/src/api/lib/ai/usage-cost.ts
index 03f159bf27..095324f4d2 100644
--- a/packages/vitnode/src/api/lib/ai/usage-cost.ts
+++ b/packages/vitnode/src/api/lib/ai/usage-cost.ts
@@ -74,11 +74,26 @@ export const normalizeUsage = (
   };
 };
 
+/**
+ * Reads cost and request ids from one AI provider's response metadata, for the
+ * API config's `ai.providerAdapters`. Custom adapters are tried before the
+ * built-in AI Gateway and OpenRouter ones; the first whose `matches` returns
+ * `true` is used. A provider without one reports no cost, so `pricing`
+ * estimates it.
+ */
 export interface AiProviderAdapter {
+  /** A unique adapter id, e.g. `"gateway"`. */
   id: string;
+  /**
+   * Asks the provider for a call's billed amount later, during reconciliation
+   * of calls whose cost was estimated or unknown. `null` when not available.
+   */
   lookupCost?: (requestId: string) => Promise<Decimal | null>;
+  /** Whether this adapter handles a model, given its provider id: `"gateway"` for AI Gateway string ids, otherwise the SDK model's `provider`. */
   matches: (providerId: string) => boolean;
+  /** The cost the provider reported in the response metadata (see {@link decimalFromNumber}), or `null`. */
   reportedCost: (metadata: ProviderMetadata | undefined) => Decimal | null;
+  /** The provider's id for the call, used by `lookupCost`; `null` when there is none. */
   requestId: (args: {
     metadata: ProviderMetadata | undefined;
     responseId: string | undefined;
diff --git a/packages/vitnode/src/api/lib/bind-api-plugin.ts b/packages/vitnode/src/api/lib/bind-api-plugin.ts
index e294bec4c9..803526d61e 100644
--- a/packages/vitnode/src/api/lib/bind-api-plugin.ts
+++ b/packages/vitnode/src/api/lib/bind-api-plugin.ts
@@ -10,9 +10,28 @@ import type { BuildRouteConfig, BuildRouteOptions, Route } from "./route";
 import { buildModule } from "./module";
 import { buildRoute } from "./route";
 
+/**
+ * Binds the module and route builders to one plugin, so its routes carry the
+ * plugin id - for OpenAPI tags, `c.get("plugin")`, staff-permission checks and
+ * the fetcher's type inference - without repeating it.
+ *
+ * Call it once per plugin, in a builders module the plugin's API code imports.
+ * Server-only.
+ *
+ * @example
+ * ```ts
+ * // src/api/builders.ts
+ * import { bindApiPlugin } from "@vitnode/core/api/lib/bind-api-plugin";
+ *
+ * import { manifest } from "@/manifest.gen";
+ *
+ * export const { buildModule, buildRoute } = bindApiPlugin(manifest);
+ * ```
+ */
 export const bindApiPlugin = <const Plugin extends string>(
   manifest: Pick<PluginManifest<Plugin>, "id">,
 ) => ({
+  /** {@link buildModule}, with this plugin's id filled in. */
   buildModule: <
     const M extends string,
     const Routes extends Route<Plugin>[],
@@ -24,6 +43,7 @@ export const bindApiPlugin = <const Plugin extends string>(
       ...options,
       pluginId: manifest.id,
     }),
+  /** {@link buildRoute}, with this plugin's id filled in. */
   buildRoute: <P extends string, R extends BuildRouteConfig<P>>(
     options: BuildRouteOptions<P, R>,
   ): Route<Plugin, R & { path: P }> =>
diff --git a/packages/vitnode/src/api/lib/cache-client.ts b/packages/vitnode/src/api/lib/cache-client.ts
index 1bfa310f38..03dee02e9c 100644
--- a/packages/vitnode/src/api/lib/cache-client.ts
+++ b/packages/vitnode/src/api/lib/cache-client.ts
@@ -2,6 +2,12 @@ import { createClient } from "redis";
 
 import type { CacheClient, CacheConfig } from "./cache";
 
+/**
+ * Creates the Redis client the cache, rate limiter and WebSocket pub/sub share,
+ * or `null` without a config. Connects in the background and keeps retrying;
+ * until it is ready, commands fail fast and callers treat Redis as absent.
+ * Called once by `VitNodeAPI` with the API config's `redis` option.
+ */
 export const createCacheClient = (config?: CacheConfig): CacheClient | null => {
   if (!config) return null;
 
diff --git a/packages/vitnode/src/api/lib/cache.ts b/packages/vitnode/src/api/lib/cache.ts
index 72359466a4..d49825ec8e 100644
--- a/packages/vitnode/src/api/lib/cache.ts
+++ b/packages/vitnode/src/api/lib/cache.ts
@@ -3,7 +3,10 @@ import type { RedisClientOptions, RedisClientType } from "redis";
 
 import type { MemoryCacheStore } from "./cache-memory";
 
-/** Connection options accepted by `redis` - `url` plus any client option. */
+/**
+ * Connection options accepted by `redis` - `url` plus any client option of
+ * node-redis `createClient`. The API config's `redis`.
+ */
 export type CacheConfig = RedisClientOptions;
 
 /** The connected `node-redis` client shared by the cache, rate limiter and ws. */
@@ -13,10 +16,25 @@ const CACHE_PREFIX = "vitnode:cache:";
 const SYSTEM_NAMESPACE = "__system__";
 
 /**
- * Per-request cache facade. Backed by Redis when a client is configured; without
- * one, by the process-wide {@link MemoryCacheStore} the global middleware passes
- * in (short TTLs, single-instance only - see `MEMORY_CACHE_MAX_TTL_SECONDS`).
- * With neither, every method is a no-op.
+ * Server-side domain cache, read in a route as `c.get("cache")`. Values are
+ * stored as JSON, so dates come back as strings.
+ *
+ * Backed by Redis when the API config has `redis` (the starter apps pass
+ * `REDIS_URL`); without it, by the process-wide {@link MemoryCacheStore} the
+ * global middleware passes in (short TTLs, single-instance only - see
+ * `MEMORY_CACHE_MAX_TTL_SECONDS`). With neither, every method is a no-op.
+ * Redis errors are swallowed: caching never fails a request.
+ *
+ * Keys are prefixed with the current plugin (`vitnode:cache:{pluginId}:`), so
+ * plugins cannot read or clobber each other's keys. The `*System` methods use a
+ * shared framework namespace instead.
+ *
+ * @example
+ * ```ts
+ * const stats = await c.get("cache").remember("stats", 300, async () => countPosts(c));
+ * // after a write:
+ * await c.get("cache").delete("stats");
+ * ```
  */
 export class CacheModel {
   constructor(
@@ -206,6 +224,7 @@ export class CacheModel {
     return this.readKey<T>(this.key(key));
   }
 
+  /** {@link CacheModel.get} in the framework system namespace, shared by every plugin. */
   async getSystem<T>(key: string): Promise<null | T> {
     return this.readKey<T>(this.systemKey(key));
   }
@@ -234,6 +253,12 @@ export class CacheModel {
     await this.removeKeys([this.systemKey(`lock:${key}`)]);
   }
 
+  /**
+   * Returns the cached value, or runs `loader`, caches its result for
+   * `ttlSeconds` and returns it. A `null` result is never served from the
+   * cache, so a loader answering `null` runs every time. Without Redis it
+   * always runs `loader`.
+   */
   async remember<T>(
     key: string,
     ttlSeconds: number,
@@ -248,12 +273,17 @@ export class CacheModel {
     return value;
   }
 
+  /**
+   * Store a JSON value. Omit `ttlSeconds` (or pass `0`) to keep it until
+   * deleted. No-op without Redis or on error.
+   */
   async set<T>(key: string, value: T, ttlSeconds?: number): Promise<void> {
     await this.writeKey(this.key(key), value, ttlSeconds);
   }
 
   /**
-   * `strict` rethrows a failed write instead of swallowing it - for an
+   * {@link CacheModel.set} in the framework system namespace, shared by every
+   * plugin. `strict` rethrows a failed write instead of swallowing it - for an
    * invalidation stamp, whose caller has to know it did not land so it can
    * retry rather than leave readers on the old generation.
    */
@@ -272,6 +302,7 @@ export class CacheModel {
     await this.writeKey(fullKey, value, ttlSeconds);
   }
 
+  /** Whether Redis is configured, and whether it answers a `PING` right now. */
   async status(): Promise<{ configured: boolean; connected: boolean }> {
     if (!this.client) return { configured: false, connected: false };
 
diff --git a/packages/vitnode/src/api/lib/check-staff-permission.ts b/packages/vitnode/src/api/lib/check-staff-permission.ts
index f86b0e20a1..02f5736f21 100644
--- a/packages/vitnode/src/api/lib/check-staff-permission.ts
+++ b/packages/vitnode/src/api/lib/check-staff-permission.ts
@@ -39,6 +39,10 @@ interface StaffUser {
   roleId: number;
 }
 
+/**
+ * Every role id a user has - the primary `roleId` plus secondary roles - with
+ * duplicates removed. Reads the database on each call.
+ */
 export const getUserRoleIds = async (
   c: Context,
   user: StaffUser,
@@ -146,6 +150,11 @@ const loadAndCacheStaffPermissions = async (
   return resolved;
 };
 
+/**
+ * The effective staff permission set of a user for one staff type, from the
+ * staff permission cache or, on a miss, from the database (then cached). Root
+ * roles and unrestricted entries resolve to `root: true`.
+ */
 export const resolveStaffPermissions = async (
   c: Context,
   { type, user }: { type: PermissionStaffType; user: StaffUser },
@@ -286,6 +295,7 @@ export const getStaffFlags = async (
   };
 };
 
+/** {@link checkStaffPermission} for an explicit user instead of the request's. */
 export const checkStaffPermissionOfUser = async (
   c: Context,
   user: StaffUser,
@@ -296,6 +306,15 @@ export const checkStaffPermissionOfUser = async (
   return hasStaffPermission(set, args);
 };
 
+/**
+ * Whether the current request's staff member holds a permission. `type:
+ * "admin"` checks the AdminCP session (`c.get("admin")`), `"moderator"` the
+ * signed-in user. Returns `false` when there is no such user.
+ *
+ * Pass `resource` to check a scoped grant for one resource. Without it, a
+ * grant scoped to selected resources does not count; one scoped to all
+ * resources of its family does.
+ */
 export const checkStaffPermission = async (
   c: Context,
   args: StaffPermissionCheck & { type: PermissionStaffType },
@@ -306,6 +325,21 @@ export const checkStaffPermission = async (
   return await checkStaffPermissionOfUser(c, user, args);
 };
 
+/**
+ * {@link checkStaffPermission}, throwing instead of returning `false`.
+ *
+ * @throws HTTPException 403 when the permission is missing.
+ *
+ * @example
+ * ```ts
+ * await assertStaffPermission(c, {
+ *   type: "admin",
+ *   plugin: "@vitnode/blog",
+ *   module: "posts",
+ *   permission: "can_delete",
+ * });
+ * ```
+ */
 export const assertStaffPermission = async (
   c: Context,
   args: StaffPermissionCheck & { type: PermissionStaffType },
diff --git a/packages/vitnode/src/api/lib/content-modules.ts b/packages/vitnode/src/api/lib/content-modules.ts
index b185e08445..b5f4529a30 100644
--- a/packages/vitnode/src/api/lib/content-modules.ts
+++ b/packages/vitnode/src/api/lib/content-modules.ts
@@ -10,11 +10,23 @@ import {
   ContentUrlError,
 } from "@/content/public-urls";
 
+/**
+ * Where an API process finds each plugin's browser-safe `{pluginId}/content`
+ * module - the one exporting `contentTypes` - to check it against the content
+ * types the plugin's API publishes.
+ */
 export interface ContentModuleLoader {
+  /** Where modules are looked up, for error messages. */
   describe: string;
+  /** The plugin's content module, or `undefined` when there is none. */
   load: (pluginId: string) => unknown;
 }
 
+/**
+ * A {@link ContentModuleLoader} that wraps the `contentModules` record (the
+ * app's generated `src/content-modules.gen.ts`) passed to `buildApiConfig`, in
+ * an app whose API runs inside the web build. `VitNodeAPI` applies it.
+ */
 export const generatedContentModules = (
   modules: Readonly<Record<string, unknown>>,
 ): ContentModuleLoader => ({
@@ -36,6 +48,15 @@ const errorCode = (error: unknown): string | undefined =>
     ? error.code
     : undefined;
 
+/**
+ * A {@link ContentModuleLoader} that resolves `{pluginId}/content` from the
+ * packages installed under `root` (the working directory by default) - the
+ * fallback for a standalone API without generated content modules. Server-only.
+ *
+ * Its `load` throws a `ContentUrlError` when the module resolves but this
+ * Node.js cannot `require()` it (before 22.12, or with top-level `await`), and
+ * rethrows any other error the module raises while loading.
+ */
 export const packageContentModules = (
   root: string = process.cwd(),
 ): ContentModuleLoader => {
@@ -68,6 +89,16 @@ export const packageContentModules = (
   };
 };
 
+/**
+ * Checks, at API startup, that every plugin publishing content types with
+ * public URLs also exports those content types, with the same public URLs,
+ * from its `./content` module - which is how the web build verifies a page
+ * serves each URL. Extra exported types are allowed.
+ *
+ * @throws A `ContentUrlError` when a plugin's content module is missing, has
+ * no valid `contentTypes` export, or omits a published type or exports it with
+ * different URLs. Loader errors propagate.
+ */
 export const assertPluginContentModules = ({
   loader,
   plugins,
diff --git a/packages/vitnode/src/api/lib/cron.ts b/packages/vitnode/src/api/lib/cron.ts
index f908f83973..cb73dda87d 100644
--- a/packages/vitnode/src/api/lib/cron.ts
+++ b/packages/vitnode/src/api/lib/cron.ts
@@ -5,22 +5,74 @@ import { CONFIG } from "@/lib/config";
 import type { EnvVitNode } from "../middlewares/global.middleware";
 import type { BuildPluginApiReturn } from "./plugin";
 
+/**
+ * Drives the cron runner in a long-running API process - set it as `cron` in
+ * the API config. `schedule()` is called once at boot and should call
+ * {@link handleCronJobs} on a timer (`@vitnode/node-cron` does it every
+ * minute). Without an adapter, something external has to `POST` the
+ * `/api/@vitnode/core/cron` endpoint instead.
+ */
 export interface CronAdapter {
+  /** Starts the timer. Called once by `VitNodeAPI` when the API app is created. */
   schedule: () => void;
 }
 
+/** A cron job, as returned by {@link buildCron}. */
 export interface BuildCronReturn {
+  /** Shown to admins in the cron job list. */
   description?: string;
+  /**
+   * The job's work, run server-side with a request context. A throw is logged,
+   * and the job's `lastRun` is left unchanged, so it is due again on the next
+   * tick.
+   */
   handler: (c: Context<EnvVitNode>) => Promise<void> | void;
+  /**
+   * Unique within the module. Together with the plugin id and module name it
+   * identifies the job's database row, so renaming a job creates a new row.
+   */
   name: string;
+  /**
+   * A cron expression with 5 fields (`minute hour day month weekday`) or 6
+   * (`second` first). An invalid expression is warned about and the job is
+   * skipped. The runner is only as precise as its tick - every minute with
+   * `@vitnode/node-cron`.
+   */
   schedule: string;
 }
 
+/** A cron job after registration, tagged with the module and plugin that declared it. */
 export interface CronJobConfig extends BuildCronReturn {
   module: string;
   pluginId: string;
 }
 
+/**
+ * Declares a recurring server-side job. Add it to a top-level module's
+ * `cronJobs` array (`buildModule({ cronJobs })`).
+ *
+ * On each tick the runner executes every job whose `schedule` has come due
+ * since its last successful run; due jobs run concurrently. For heavy or
+ * retryable work, have the job dispatch queue tasks instead of doing the work
+ * itself. A job runs inside core's cron request, so `c.get("plugin")` is
+ * `@vitnode/core`: pass your plugin's id to `dispatch` explicitly.
+ *
+ * @example
+ * ```ts
+ * import { buildCron } from "@vitnode/core/api/lib/cron";
+ *
+ * export const cleanDraftsCron = buildCron({
+ *   name: "clean-drafts",
+ *   description: "Delete abandoned drafts",
+ *   schedule: "0 3 * * *",
+ *   handler: async c => {
+ *     await c
+ *       .get("queue")
+ *       .dispatch({ name: "clean-drafts", pluginId: "@acme/blog" });
+ *   },
+ * });
+ * ```
+ */
 export function buildCron({
   name,
   schedule,
@@ -30,6 +82,7 @@ export function buildCron({
   return { name, schedule, handler, description };
 }
 
+/** Flattens every plugin's cron jobs, tagging each with its plugin id. */
 export function collectCronJobs(
   plugins: BuildPluginApiReturn[],
 ): CronJobConfig[] {
@@ -58,6 +111,15 @@ const reportFailedCronTick = (reason: string) => {
 // later tick.
 const CRON_TICK_TIMEOUT_MS = 55_000;
 
+/**
+ * One cron tick: `POST`s the API's own `/api/@vitnode/core/cron` endpoint,
+ * authenticated with the `CRON_SECRET` environment variable (which falls back
+ * to a development-only default that production refuses). Call it from a
+ * {@link CronAdapter}'s timer.
+ *
+ * Never throws once the API URL is valid - a failed request or non-2xx
+ * response is written to `console.error`.
+ */
 export const handleCronJobs = async () => {
   const url = new URL("/api/@vitnode/core/cron", CONFIG.api.origin);
   const headers: HeadersInit = {
diff --git a/packages/vitnode/src/api/lib/editable-pages.ts b/packages/vitnode/src/api/lib/editable-pages.ts
index 397daf83eb..36a21fb204 100644
--- a/packages/vitnode/src/api/lib/editable-pages.ts
+++ b/packages/vitnode/src/api/lib/editable-pages.ts
@@ -20,6 +20,12 @@ export interface RegisteredEditablePage {
   pluginId: string;
 }
 
+/**
+ * Thrown at API startup when an editable page is misconfigured: no
+ * `permission`, a duplicate page id, or a permission its owning plugin
+ * (`permission.plugin`, defaulting to the registering plugin) does not
+ * declare in `permissionStaff.moderator`.
+ */
 export class EditablePageRegistryError extends Error {
   constructor(message: string) {
     super(message);
@@ -27,6 +33,7 @@ export class EditablePageRegistryError extends Error {
   }
 }
 
+/** Pairs a page with the plugin registering it and resolves its permission's `plugin`. */
 export const registerEditablePage = (
   page: AnyEditablePageDefinition,
   pluginId: string,
@@ -76,6 +83,14 @@ export const validateEditablePages = (
   return [...byId.values()];
 };
 
+/**
+ * Checks, once every plugin is loaded, that each page's moderator permission is
+ * declared in its owning plugin's `permissionStaff.moderator` (`permission.plugin`,
+ * defaulting to the plugin that registers the page).
+ *
+ * @throws {EditablePageRegistryError} When the owning plugin is not installed
+ * or does not declare the permission.
+ */
 export const assertEditablePagePermissionsGrantable = ({
   pages,
   permissionStaff,
diff --git a/packages/vitnode/src/api/lib/events.ts b/packages/vitnode/src/api/lib/events.ts
index 3192a95260..774902f30c 100644
--- a/packages/vitnode/src/api/lib/events.ts
+++ b/packages/vitnode/src/api/lib/events.ts
@@ -7,24 +7,65 @@ import type {
   VitNodeEvents,
 } from "../models/events";
 
+/**
+ * A listener for one VitNode event, as returned by {@link buildEventListener}.
+ *
+ * Register it in a top-level module's `events` array (`buildModule({ events })`);
+ * listeners in nested modules are not collected.
+ */
 export interface BuildEventListenerReturn<
   K extends VitNodeEventName = VitNodeEventName,
 > {
+  /** Human-readable note for developers; not shown to end users. */
   description?: string;
+  /** The event to react to - a key of `VitNodeEvents`. */
   event: K;
+  /**
+   * Runs for every emit of `event`, with the emitter's request context.
+   *
+   * With the default local adapter, listeners run one after another and the
+   * emitter awaits them all. A thrown error is logged and reported in the
+   * emitter's `EventEmitResult.failures`; it never reaches the emitter and
+   * does not stop the remaining listeners.
+   */
   handler: (
     c: Context<EnvVitNode>,
     payload: VitNodeEvents[K],
     envelope: EventEnvelope<K>,
   ) => Promise<void> | void;
+  /** Identifies the listener in logs and failure reports. */
   name: string;
 }
 
+/** A listener after registration, tagged with the module and plugin that declared it. */
 export interface EventListenerConfig extends BuildEventListenerReturn {
   module: string;
   pluginId: string;
 }
 
+/**
+ * Declares a server-side listener for a VitNode event, with the payload typed
+ * from `event`.
+ *
+ * Add your own events by augmenting `VitNodeEvents` in
+ * `@vitnode/core/api/models/events`, and emit them with
+ * `c.get("events").emit(name, payload)`.
+ *
+ * @example
+ * ```ts
+ * import { buildEventListener } from "@vitnode/core/api/lib/events";
+ *
+ * export const welcomeListener = buildEventListener({
+ *   event: "user.created",
+ *   name: "send-welcome",
+ *   handler: async (c, payload) => {
+ *     await c.get("log").debug(`Welcome, ${payload.name}`);
+ *   },
+ * });
+ *
+ * // buildModule({ name: "users", routes: [], events: [welcomeListener] })
+ * ```
+ */
 export function buildEventListener<K extends VitNodeEventName>(
   args: BuildEventListenerReturn<K>,
 ): BuildEventListenerReturn {
diff --git a/packages/vitnode/src/api/lib/logger-middleware.ts b/packages/vitnode/src/api/lib/logger-middleware.ts
index 087d2d374d..c33a0eb6b2 100644
--- a/packages/vitnode/src/api/lib/logger-middleware.ts
+++ b/packages/vitnode/src/api/lib/logger-middleware.ts
@@ -5,6 +5,11 @@ import { core_logs } from "@/database/logs";
 
 type CoreLogsType = "debug" | "error" | "warn";
 
+/**
+ * `c.get("log")`: each method writes an entry to the `core_logs` table (shown
+ * in AdminCP debug logs) with the request's plugin, path, IP and user, and
+ * echoes it to the console.
+ */
 export interface LoggerMiddlewareType {
   debug: (content: string) => Promise<void>;
   error: (content: string) => Promise<void>;
diff --git a/packages/vitnode/src/api/lib/moderation/registry.ts b/packages/vitnode/src/api/lib/moderation/registry.ts
index 0cd952de54..389fdf3a1d 100644
--- a/packages/vitnode/src/api/lib/moderation/registry.ts
+++ b/packages/vitnode/src/api/lib/moderation/registry.ts
@@ -16,8 +16,11 @@ import type {
 
 import { ModerationRegistryError } from "./scopes";
 
+/** The `moderation` option of `buildApiPlugin`. */
 export interface ModerationPluginConfig {
+  /** Custom report targets; content types with `reports` add theirs automatically. */
   reportTargets?: ModerationReportTargetDefinition[];
+  /** Scope families moderator permissions can be limited by. */
   scopes?: ModerationScopeDefinition[];
 }
 
diff --git a/packages/vitnode/src/api/lib/moderation/scopes.ts b/packages/vitnode/src/api/lib/moderation/scopes.ts
index 89f01d1b77..23788ef2f5 100644
--- a/packages/vitnode/src/api/lib/moderation/scopes.ts
+++ b/packages/vitnode/src/api/lib/moderation/scopes.ts
@@ -5,28 +5,53 @@ import {
   MODERATION_RESOURCE_ID_PATTERN,
 } from "@/lib/moderation/const";
 
+/** One resource a moderator permission can be limited to, e.g. a forum section. */
 export interface ModerationScopeResource {
+  /** Where a nested resource sits, outermost first, e.g. `["Games"]`. Shown next to the label. */
   context?: string[];
+  /** The resource id as a string: 1-64 characters of `A-Z`, `a-z`, `0-9`, `.`, `_`, `:`, `-`, starting with a letter or digit. */
   id: string;
+  /** The resource's display name, shown as is (not translated). */
   label: string;
 }
 
+/** What the AdminCP picker asks {@link ModerationScopeDefinition.list} for. */
 export interface ModerationScopeListArgs {
+  /** The `nextCursor` of the previous page, or `null` for the first. */
   cursor: null | string;
+  /** Page size; the picker asks for 20 and ignores any extra items. */
   limit: number;
+  /** Trimmed search text, or `undefined` for none. */
   search?: string;
 }
 
+/** One page of resources. */
 export interface ModerationScopeListResult {
   items: ModerationScopeResource[];
+  /** Passed back as `cursor` for the next page; `null` on the last page. */
   nextCursor: null | string;
 }
 
+/**
+ * A scope family: a set of resources (forum sections, categories...) that
+ * moderator permissions can be limited to. Register it in `buildApiPlugin`'s
+ * `moderation.scopes`, and name it as a permission's or report target's `scope`.
+ * Server-only - both callbacks read the database.
+ */
 export interface ModerationScopeDefinition {
+  /** Describes the family in the AdminCP permission editor; an i18n key, as for `label`. Dropped when the key is not found. */
   description?: string;
+  /**
+   * Returns the resources among `ids` that exist. Used to label a saved
+   * selection and to refuse grants for ids that are gone. Omit missing ids
+   * rather than throwing.
+   */
   find: (c: Context, ids: string[]) => Promise<ModerationScopeResource[]>;
+  /** Lowercase family id, `a-z0-9` parts joined by `.`, `_` or `-`, e.g. `"forum.section"`. */
   id: string;
+  /** The family's name in the AdminCP permission editor, as an i18n key; when the key is not found, the family `id` is shown instead. */
   label: string;
+  /** One page of resources for the AdminCP picker, filtered by `search`. */
   list: (
     c: Context,
     args: ModerationScopeListArgs,
@@ -45,6 +70,25 @@ export class ModerationRegistryError extends Error {
   }
 }
 
+/**
+ * Declares a scope family for moderator permissions. Returns the definition
+ * unchanged after checking its id.
+ *
+ * @throws {ModerationRegistryError} When `id` is not one or more lowercase
+ * `a-z0-9` parts joined by `.`, `_` or `-` (e.g. `"forum.section"`).
+ *
+ * @example
+ * ```ts
+ * import { defineModerationScope } from "@vitnode/core/api/moderation";
+ *
+ * export const categoryScope = defineModerationScope({
+ *   id: "example.category",
+ *   label: "@vitnode/example.moderation.category.label",
+ *   list: async (c, { cursor, limit, search }) => ({ items: [], nextCursor: null }),
+ *   find: async (c, ids) => [],
+ * });
+ * ```
+ */
 export const defineModerationScope = (
   definition: ModerationScopeDefinition,
 ): ModerationScopeDefinition => {
diff --git a/packages/vitnode/src/api/lib/moderation/targets.ts b/packages/vitnode/src/api/lib/moderation/targets.ts
index 4b524de540..f9ce8dab38 100644
--- a/packages/vitnode/src/api/lib/moderation/targets.ts
+++ b/packages/vitnode/src/api/lib/moderation/targets.ts
@@ -8,6 +8,7 @@ import { MODERATION_IDENTIFIER_PATTERN } from "@/lib/moderation/const";
 
 import { ModerationRegistryError } from "./scopes";
 
+/** A report target as it is now. */
 export interface ModerationTargetState {
   hidden: boolean;
   url: null | string;
@@ -23,43 +24,74 @@ export type ModerationCaptureResult = Omit<
   "capturedAt" | "target" | "truncated" | "version"
 >;
 
+/** What a moderator action's `run` receives. */
 export interface ModerationActionArgs {
   actorUserId: number;
   targetId: string;
+  /** The report's transaction; write through it so the action and the report commit together. */
   tx: ContentDatabase;
 }
 
 export interface ModerationActionOutcome {
+  /** `false` when the target was already in the requested state. */
   changed: boolean;
+  /** Side effects (cache, search, events) run after the transaction commits. */
   effects: () => Promise<void>;
 }
 
+/** A content action, such as hide or unhide, that moderators run from a report. */
 export interface ModerationTargetActionDefinition {
+  /** Whether the action applies to the target's current state. */
   available: (state: ModerationTargetState) => boolean;
+  /** Moderator permission in the target's `permissionModule` that allows it. */
   permission: string;
+  /**
+   * Runs inside the report's transaction. Throwing rolls it back and records
+   * nothing; `null` means the target no longer exists.
+   */
   run: (
     c: Context,
     args: ModerationActionArgs,
   ) => Promise<ModerationActionOutcome | null>;
 }
 
+/**
+ * Something members can report that is not a Content Engine type (those
+ * register their target automatically). Create it with
+ * {@link defineReportTarget} and register it in
+ * `buildApiPlugin({ moderation: { reportTargets } })`.
+ */
 export interface ModerationReportTargetDefinition {
   actions?: Partial<
     Record<ModerationTargetAction, ModerationTargetActionDefinition>
   >;
+  /**
+   * The snapshot stored with a new report, or `null` when the reporter cannot
+   * read the target. Runs as the reporter.
+   */
   capture: (
     c: Context,
     args: ModerationCaptureArgs,
   ) => Promise<ModerationCaptureResult | null>;
+  /** The target now, or `null` once it is deleted. */
   current: (
     c: Context,
     args: { locale: null | string; targetId: string },
   ) => Promise<ModerationTargetState | null>;
+  /** i18n key naming the kind of thing, an ICU plural called with `count: 1`. */
   label: string;
+  /** Validates and normalizes a client-sent id before anything reads it; `null` rejects it. */
   parseId: (value: string) => null | string;
+  /** Moderator permission module the report permissions are added to. */
   permissionModule: string;
+  /**
+   * The target's resource id in the `scope` family: `""` for none,
+   * `undefined` once the target is deleted. Required with `scope`.
+   */
   resolveScope?: (c: Context, targetId: string) => Promise<string | undefined>;
+  /** Scope family id that limits which moderators see these reports. */
   scope?: string;
+  /** Stable id stored in reports, lowercase and dot-separated, e.g. `"forum.topic"`. */
   type: string;
 }
 
@@ -68,6 +100,12 @@ export interface RegisteredReportTarget {
   pluginId: string;
 }
 
+/**
+ * Validates a custom report target when the module loads.
+ *
+ * @throws {ModerationRegistryError} When `type` is not lowercase and
+ * dot-separated, or `scope` is set without `resolveScope`.
+ */
 export const defineReportTarget = (
   definition: ModerationReportTargetDefinition,
 ): ModerationReportTargetDefinition => {
diff --git a/packages/vitnode/src/api/lib/module.ts b/packages/vitnode/src/api/lib/module.ts
index 97a0f65bd2..21524c3975 100644
--- a/packages/vitnode/src/api/lib/module.ts
+++ b/packages/vitnode/src/api/lib/module.ts
@@ -17,6 +17,7 @@ export interface BuildModuleType<T extends Route, Plugin extends string> {
   routes: T;
 }
 
+/** A built module, as a parent module or `buildApiPlugin` receives it. */
 export interface BaseBuildModuleReturn<
   P extends string = string,
   M extends string = string,
@@ -49,27 +50,67 @@ export interface BuildModuleReturn<
   modules?: Modules;
 }
 
+/** What `buildModule` accepts. */
 export interface BuildModuleOptions<
   P extends string,
   M extends string,
   Routes extends Route<P>[],
   Modules extends BaseBuildModuleReturn<P>[],
 > {
+  /** Content containers this module registers. Collected from any depth. */
   contentContainers?: AnyContentContainerDefinition[];
+  /** Content models this module registers. Collected from any depth. */
   contentModels?: AnyContentModel[];
+  /** Content types this module registers. Collected from any depth. */
   contentTypes?: AnyContentTypeDefinition[];
+  /** Scheduled jobs. Only read from a plugin's top-level modules. */
   cronJobs?: BuildCronReturn[];
+  /** Event listeners. Only read from a plugin's top-level modules. */
   events?: BuildEventListenerReturn[];
+  /** Child modules, each mounted at `/{child.name}` below this one. */
   modules?: Modules;
+  /**
+   * The path segment the module is mounted at, and its part of the fetcher's
+   * `module` path (`admin/ai` for an `ai` module inside `admin`).
+   */
   name: M;
+  /** Notification types this module registers. Collected from any depth. */
   notificationTypes?: AnyNotificationTypeDefinition[];
+  /**
+   * Content types handed to this module's public API; the plugin keeps those
+   * that declare public URLs. Collected from any depth.
+   */
   publicContentTypes?: AnyContentTypeDefinition[];
+  /** Background queue tasks. Only read from a plugin's top-level modules. */
   queueTasks?: BuildQueueTaskReturn[];
+  /** Routes built with the plugin's bound `buildRoute`. Pass `[]` for a module with only children. */
   routes: Routes;
+  /** Search indexers this module registers. Collected from any depth. */
   searchIndexers?: SearchIndexer[];
+  /** WebSocket endpoints. Only read from a plugin's top-level modules. */
   webSockets?: BuildWebSocketReturn[];
 }
 
+/**
+ * Groups routes, child modules and what they register into one Hono
+ * sub-application. Plugins call the bound version from `bindApiPlugin`, which
+ * supplies `pluginId`.
+ *
+ * Mind the depth: content types, models, containers, notification types and
+ * search indexers are collected from the whole module tree, but cron jobs,
+ * events, queue tasks and WebSockets only from the modules passed to
+ * `buildApiPlugin` directly - declared on a nested module, they never run.
+ *
+ * @example
+ * ```ts
+ * import { buildModule } from "@/api/builders";
+ *
+ * export const postsModule = buildModule({
+ *   name: "posts",
+ *   routes: [listPostsRoute, showPostRoute],
+ * });
+ * ```
+ */
 export function buildModule<
   const P extends string,
   const M extends string,
diff --git a/packages/vitnode/src/api/lib/notifications/registry.ts b/packages/vitnode/src/api/lib/notifications/registry.ts
index 4fc621c96e..1140bfac98 100644
--- a/packages/vitnode/src/api/lib/notifications/registry.ts
+++ b/packages/vitnode/src/api/lib/notifications/registry.ts
@@ -10,12 +10,21 @@ import type {
 
 import { NOTIFICATION_EMAIL_MODES } from "@/lib/notifications/types";
 
+/**
+ * One inbox item as plain text. Core removes control characters, collapses
+ * whitespace and cuts each string at 500 characters; it does not strip HTML.
+ */
 export interface NotificationPresentation {
   body?: string;
+  /**
+   * Same-site path the item links to, e.g. `/forum/topics/42`. Absolute URLs
+   * and unsafe values are dropped, leaving the item without a link.
+   */
   target?: null | string;
   title: string;
 }
 
+/** The wording of a notification email, when it differs from `present`. */
 export interface NotificationEmailPresentation {
   actionLabel?: string;
   body?: string;
@@ -28,13 +37,19 @@ export interface NotificationActorPreview {
   name: string;
 }
 
+/** What `present` and `email` receive, once per recipient language. */
 export interface NotificationPresentArgs<TData> {
+  /** Distinct people across every notification grouped into the item. */
   actorCount: number;
+  /** Up to 3 people who caused the item, newest first; in emails, only that event's actor. */
   actors: NotificationActorPreview[];
+  /** The stored data, migrated and parsed with the current `schema`. */
   data: TData;
+  /** Notifications grouped into the item; always 1 without `grouping` and in emails. */
   eventCount: number;
   locale: string;
   subject: NotificationSubject | null;
+  /** Translator for the recipient's language, reading API messages. */
   t: Translator;
 }
 
@@ -45,32 +60,78 @@ export interface NotificationAccessArgs<TData> {
   userIds: number[];
 }
 
+/**
+ * Merges notifications of one type for the same member into one inbox item
+ * while they share a group key and a fixed UTC time window.
+ */
 export interface NotificationGroupingConfig<TData> {
+  /**
+   * The group key; defaults to the subject (no subject means no grouping). A
+   * `null` or empty key is never grouped. Cut at 200 characters.
+   */
   key?: (args: {
     data: TData;
     subject: NotificationSubject | null;
   }) => null | string;
+  /** Window length in minutes, 1 to 10080 (one week). */
   windowMinutes: number;
 }
 
+/** One kind of persistent notification. Build it with {@link buildNotificationType}. */
 export interface NotificationTypeDefinition<TData = Record<string, unknown>> {
+  /**
+   * Returns which of `userIds` may see the notification; without it every
+   * recipient may. Called in batches on delivery, before each email and when
+   * an inbox loads, so answer the whole batch with one query. Return fewer ids
+   * for "no access" - a throw fails the delivery batch for a retry.
+   */
   access?: (
     args: NotificationAccessArgs<TData>,
   ) => number[] | Promise<number[]>;
+  /**
+   * Groups types on the preferences page and in inbox filters: 1-50 of
+   * `a-z`, `0-9`, `_`, `-`.
+   */
   category: string;
+  /**
+   * What a member gets before choosing; administrators can override it in the
+   * AdminCP. `email` other than `"none"` requires `email`.
+   */
   defaults: { email: NotificationEmailMode; inApp: boolean };
+  /** API message key for a one-line explanation under the label. */
   description?: string;
+  /**
+   * Enables email. `true` reuses `present`; a function words the email
+   * separately.
+   */
   email?:
     | ((args: NotificationPresentArgs<TData>) => NotificationEmailPresentation)
     | boolean;
+  /** Merges repeat notifications into one inbox item within a time window. Off by default: each publish is its own item. */
   grouping?: NotificationGroupingConfig<TData>;
+  /**
+   * Dot-separated, plugin-scoped id such as `"forum.topic_reply"`: at least
+   * two segments of `a-z`, `0-9`, `_`, `-`, at most 100 characters. Stored
+   * notifications refer to it, so never rename it.
+   */
   id: string;
+  /** API message key for the type name on the preferences page. */
   label: string;
+  /** Always delivered to the inbox; members cannot turn it off. */
   mandatory?: boolean;
+  /** Upgrades data stored by an older `version` before it is parsed. */
   migrate?: (data: unknown, fromVersion: number) => unknown;
+  /**
+   * Renders one inbox item in the recipient's language. Runs on the API each
+   * time the item is listed or emailed; a throw or empty title shows a "no
+   * longer available" placeholder.
+   */
   present: (args: NotificationPresentArgs<TData>) => NotificationPresentation;
+  /** Validates `data` on publish and whenever stored data is read. */
   schema: z.ZodType<TData>;
+  /** The only subject type `publish()` accepts for this type, e.g. `"forum.topic"`. */
   subjectType?: string;
+  /** Integer of 1 or more. Increase it when `schema` changes shape, and add `migrate`. */
   version: number;
 }
 
@@ -89,6 +150,7 @@ const CATEGORY_PATTERN = /^[a-z0-9_-]{1,50}$/;
 export const SUBJECT_TYPE_PATTERN = /^[a-z0-9_-]+(\.[a-z0-9_-]+)*$/;
 const MAX_GROUPING_WINDOW_MINUTES = 60 * 24 * 7;
 
+/** Thrown when a notification type is invalid or two plugins register the same id. */
 export class NotificationRegistryError extends Error {
   constructor(message: string) {
     super(`[Notifications] ${message}`);
@@ -96,6 +158,37 @@ export class NotificationRegistryError extends Error {
   }
 }
 
+/**
+ * Declares a persistent notification type and checks it when the module loads.
+ * Register the returned object in `buildApiPlugin({ notificationTypes })` or
+ * `buildModule({ notificationTypes })`, and pass the same object to
+ * `c.get("notifications").publish({ type })` so `data` is type-checked.
+ *
+ * @throws {NotificationRegistryError} For an invalid `id`, `category` or
+ * `subjectType`, a `version` below 1, a grouping window outside 1-10080
+ * minutes, or `defaults.email` other than `"none"` without `email`.
+ *
+ * @example
+ * ```ts
+ * import { buildNotificationType } from "@vitnode/core/api/lib/notifications/registry";
+ * import { z } from "zod";
+ *
+ * export const topicReplyNotification = buildNotificationType({
+ *   id: "forum.topic_reply",
+ *   version: 1,
+ *   schema: z.object({ topicId: z.number(), topicTitle: z.string() }),
+ *   category: "content",
+ *   label: "@acme/forum.notifications.topic_reply.label",
+ *   defaults: { inApp: true, email: "none" },
+ *   present: ({ data, t }) => ({
+ *     title: t("@acme/forum.notifications.topic_reply.title", {
+ *       title: data.topicTitle,
+ *     }),
+ *     target: `/forum/topics/${data.topicId}`,
+ *   }),
+ * });
+ * ```
+ */
 export function buildNotificationType<TData>(
   definition: NotificationTypeDefinition<TData>,
 ): NotificationTypeDefinition<TData> {
diff --git a/packages/vitnode/src/api/lib/passkey-config.ts b/packages/vitnode/src/api/lib/passkey-config.ts
index 6db2c5196c..3f8d014055 100644
--- a/packages/vitnode/src/api/lib/passkey-config.ts
+++ b/packages/vitnode/src/api/lib/passkey-config.ts
@@ -1,6 +1,21 @@
+/**
+ * Passkey (WebAuthn) settings, the API config's `authorization.passkeys` when
+ * it is an object (`true` uses every default). Checked at startup: a bad
+ * origin or RP ID throws.
+ */
 export interface PasskeysConfig {
+  /**
+   * Bare origins (`https://example.com`, no path) passkeys are accepted from.
+   * HTTPS only, except `localhost`. Defaults to the web origin
+   * (`VITNODE_WEB_URL`).
+   */
   origins?: string[];
+  /**
+   * The relying party ID: a lowercase domain (not an IP) that every origin's
+   * host equals or is a subdomain of. Defaults to the first origin's host.
+   */
   rpId?: string;
+  /** The name shown in the browser's passkey prompt. Defaults to `metadata.shortTitle ?? metadata.title`. */
   rpName?: string;
 }
 
@@ -77,6 +92,12 @@ export const passkeyConfigProblems = ({
   return problems;
 };
 
+/**
+ * The passkey settings with defaults filled in, or `enabled: false` when
+ * passkeys are off.
+ *
+ * @throws When the resolved origins or RP ID are invalid.
+ */
 export const resolvePasskeysConfig = ({
   config,
   rpNameFallback,
diff --git a/packages/vitnode/src/api/lib/permission-staff.ts b/packages/vitnode/src/api/lib/permission-staff.ts
index 11b638a1d5..8c0252ae38 100644
--- a/packages/vitnode/src/api/lib/permission-staff.ts
+++ b/packages/vitnode/src/api/lib/permission-staff.ts
@@ -1,8 +1,22 @@
+/**
+ * One permission a plugin declares: its key (e.g. `"can_delete"`), or an object
+ * when it has dependencies or a scope. Labels come from the plugin's locale
+ * file as `"{pluginId}:{module}:{permission}"`.
+ */
 export type PermissionStaffEntryInput =
   | string
   | {
+      /**
+       * Permissions of the same module this one requires. The AdminCP staff
+       * editor keeps them granted together, and a scoped moderator grant is
+       * narrowed to the scope of its dependencies.
+       */
       dependsOn?: string[];
       permission: string;
+      /**
+       * A moderation scope family id (e.g. `"forum.section"`), so the grant can
+       * be limited to selected resources. Moderator permissions only.
+       */
       scope?: string;
     };
 
@@ -22,8 +36,29 @@ export interface PermissionStaffEntry {
 
 export type PermissionStaffModules = Record<string, PermissionStaffEntry[]>;
 
+/**
+ * The staff permissions a plugin declares in `buildApiPlugin({ permissionStaff })`,
+ * grouped by staff type and then by module.
+ *
+ * Core adds the generated content permissions (at least
+ * `can_view`/`can_create`/`can_edit`/`can_delete`) for each content type and
+ * container collection, plus report-target permissions, unless the plugin
+ * declares that module itself. Enforce an admin permission with `adminStaffPermission` in
+ * `buildRoute`, or any permission with `assertStaffPermission`.
+ *
+ * @example
+ * ```ts
+ * permissionStaff: {
+ *   admin: {
+ *     posts: ["can_view", { permission: "can_delete", dependsOn: ["can_view"] }],
+ *   },
+ * }
+ * ```
+ */
 export interface PermissionStaffConfig {
+  /** Permissions grantable to AdminCP administrators. */
   admin?: PermissionStaffModulesInput;
+  /** Permissions grantable to moderators. */
   moderator?: PermissionStaffModulesInput;
 }
 
@@ -47,10 +82,12 @@ export const normalizePermissionStaffModules = (
     ]),
   );
 
+/** Limits a grant to every resource of a scope family, or to the selected ids. */
 export type PermissionStaffScope =
   | { family: string; ids: string[]; mode: "selected" }
   | { family: string; mode: "all" };
 
+/** One permission tuple: which plugin, module and permission key. */
 export interface PermissionsStaffArgs {
   module: string;
   permission: string;
@@ -58,6 +95,7 @@ export interface PermissionsStaffArgs {
   scope?: PermissionStaffScope;
 }
 
+/** The resource a scoped permission is checked against, e.g. a forum section. */
 export interface PermissionStaffResource {
   family: string;
   id: string;
diff --git a/packages/vitnode/src/api/lib/plugin.ts b/packages/vitnode/src/api/lib/plugin.ts
index df7c250b42..baab563b26 100644
--- a/packages/vitnode/src/api/lib/plugin.ts
+++ b/packages/vitnode/src/api/lib/plugin.ts
@@ -49,6 +49,16 @@ import { applyModuleTags } from "./openapi-tags";
 
 export type { ApiPluginContract };
 
+/**
+ * A plugin's API half, as {@link buildApiPlugin} returns it. An app lists it in
+ * `buildApiConfig({ plugins })` and `VitNodeAPI` mounts it at `/{pluginId}`
+ * under the API's base path (`/api` in the starter apps).
+ *
+ * Everything the modules declared is already collected and validated here:
+ * content types, models and containers from the whole module tree; cron jobs,
+ * event listeners, queue tasks and WebSockets from top-level modules only, each
+ * stamped with the module that declared it.
+ */
 export interface BuildPluginApiReturn<
   P extends string = string,
   Modules extends readonly BaseBuildModuleReturn<P>[] =
@@ -62,15 +72,24 @@ export interface BuildPluginApiReturn<
   cronJobs?: Omit<CronJobConfig, "pluginId">[];
   editablePages?: AnyEditablePageDefinition[];
   events?: Omit<EventListenerConfig, "pluginId">[];
+  /** Every module's routes, each module mounted at `/{module.name}`. */
   hono: OpenAPIHono;
   manifest?: PluginManifest<P>;
   messages?: LocaleMessagesMap;
+  /**
+   * Declared targets and scopes, plus one report target per content model with
+   * reports enabled and one scope per content container with policies enabled.
+   */
   moderation?: Required<ModerationPluginConfig>;
+  /** The module tuple as passed in; the fetcher's types resolve calls through it. */
   modules: Modules;
   notificationTypes?: AnyNotificationTypeDefinition[];
   openApiTags?: string[];
+  /** The declared permissions, plus the ones content types, containers and report targets add. */
   permissionStaff?: PermissionStaffConfig;
+  /** The plugin's npm package name, taken from `manifest.id`. */
   pluginId: P;
+  /** Content types the plugin serves public URLs for. */
   publicContentTypes?: AnyContentTypeDefinition[];
   queueTasks?: Omit<QueueTaskConfig, "pluginId">[];
   searchIndexers?: SearchIndexer[];
@@ -82,6 +101,44 @@ export type AnyBuildPluginApiReturn = BuildPluginApiReturn<
   readonly BaseBuildModuleReturn[]
 >;
 
+/**
+ * Declares a plugin's API half: its Hono modules plus everything they bring -
+ * content types, cron jobs, events, queues, notifications, WebSockets, staff
+ * permissions. Its frontend half is `buildPlugin` from
+ * `@vitnode/core/lib/plugin`; both take the plugin's generated manifest, whose
+ * `id` (the package name) keys every registration.
+ *
+ * Server-only. Call it from the plugin's `src/config.api.ts`, which an app
+ * imports in its `vitnode.api.config.ts` and nowhere a browser bundle reaches.
+ *
+ * Staff permissions: every content type adds `can_view`, `can_create`,
+ * `can_edit` and `can_delete` (plus `can_publish`, `can_hide` and
+ * `can_restore` when publication, visibility or editorial is on) under its
+ * permission module, and every content container and report target adds its
+ * own entries, unless `permissionStaff` already declares that module.
+ *
+ * @throws When `manifest` is malformed; when `blocks` belongs to another
+ * plugin; when content types, containers, editable pages, AI actions, search
+ * indexers or notification types are invalid or collide. In development, also
+ * when no installed package's `package.json` has the plugin id as its name.
+ *
+ * @example
+ * ```ts
+ * // src/config.api.ts
+ * import type { ApiPluginContract } from "@vitnode/core/api/lib/plugin";
+ *
+ * import { buildApiPlugin } from "@vitnode/core/api/lib/plugin";
+ *
+ * import { postsModule } from "@/api/modules/posts/posts.module";
+ * import { manifest } from "@/manifest.gen";
+ *
+ * export const blogApiPlugin = () =>
+ *   buildApiPlugin({ manifest, modules: [postsModule] });
+ *
+ * // What the fetcher's registry reads to type calls to this plugin.
+ * export type VitNodeApiPlugin = ApiPluginContract<ReturnType<typeof blogApiPlugin>>;
+ * ```
+ */
 export function buildApiPlugin<
   const P extends string,
   const Modules extends readonly BuildModuleReturn<P, string>[] = readonly [],
@@ -97,15 +154,31 @@ export function buildApiPlugin<
   permissionStaff,
   searchIndexers,
 }: {
+  /**
+   * Managed AI actions the plugin runs with `c.get("ai").run()` or
+   * `runAsSystem()`; admins configure them and grant their permission per role.
+   */
   aiActions?: AnyAiActionDefinition[];
+  /** The object the plugin's own widgets (`blocks`) module exports; its `pluginId` must match. */
   blocks?: BlockPluginSource;
+  /** Pages built from widgets that admins edit in place. Page ids must be unique within the plugin. */
   editablePages?: AnyEditablePageDefinition[];
+  /** The plugin's generated manifest (`src/manifest.gen.ts`). */
   manifest: PluginManifest<P>;
+  /**
+   * Lazy loaders for the plugin's server-side messages (emails, notifications),
+   * keyed by locale code. Separate from the frontend tree `buildPlugin` takes.
+   */
   messages?: LocaleMessagesMap;
+  /** Report targets and moderation scopes beyond those content models add. */
   moderation?: ModerationPluginConfig;
+  /** Top-level modules, each mounted at `/{pluginId}/{name}` under the API's base path. */
   modules?: Modules;
+  /** Notification types in addition to those modules declare. */
   notificationTypes?: AnyNotificationTypeDefinition[];
+  /** Staff permissions the plugin's routes check, grouped by permission module. */
   permissionStaff?: PermissionStaffConfig;
+  /** Search indexers in addition to those modules declare. */
   searchIndexers?: SearchIndexer[];
 }): BuildPluginApiReturn<P, Modules> {
   const pluginId = manifest.id;
diff --git a/packages/vitnode/src/api/lib/queue.ts b/packages/vitnode/src/api/lib/queue.ts
index fd76dad12f..d3c347d907 100644
--- a/packages/vitnode/src/api/lib/queue.ts
+++ b/packages/vitnode/src/api/lib/queue.ts
@@ -2,22 +2,72 @@ import type { Context } from "hono";
 
 import type { EnvVitNode } from "../middlewares/global.middleware";
 
+/** A background task handler, as returned by {@link buildQueueTask}. */
 export interface BuildQueueTaskReturn {
+  /** A note on what the task does. Kept on the definition only; core does not display it. */
   description?: string;
+  /**
+   * Runs once per claimed task with the payload given to `dispatch()`. The
+   * payload is stored as JSON, so validate it before use.
+   *
+   * Returning completes the task. Throwing retries it with exponential backoff
+   * (10 s, doubling, capped at 1 hour) until `maxAttempts` is reached, then
+   * marks it failed. Throw {@link QueueDeferError} to postpone without using
+   * up an attempt.
+   */
   handler: (
     c: Context<EnvVitNode>,
     payload: Record<string, unknown>,
   ) => Promise<void> | void;
+  /**
+   * Seconds a worker may hold a claimed task before it is treated as
+   * abandoned and returned to the queue (or failed, once out of attempts).
+   * Defaults to 600. Raise it for tasks that legitimately run longer.
+   */
   leaseSeconds?: number;
+  /**
+   * Default attempt limit for tasks dispatched without their own
+   * `maxAttempts`. Defaults to 3.
+   */
   maxAttempts?: number;
+  /**
+   * Unique within the plugin - tasks are matched to handlers by plugin id and
+   * `name`, not by module.
+   */
   name: string;
 }
 
+/** A queue task after registration, tagged with the module and plugin that declared it. */
 export interface QueueTaskConfig extends BuildQueueTaskReturn {
   module: string;
   pluginId: string;
 }
 
+/**
+ * Declares a handler for durable background work stored in the `core_queue`
+ * table. Add it to a top-level module's `queueTasks` array, then enqueue work
+ * with `c.get("queue").dispatch({ name, payload })`.
+ *
+ * Tasks are processed by the core `process-queue` cron job (every minute, up
+ * to 25 per tick, highest `priority` first), so a cron adapter or an external
+ * cron trigger must be running.
+ *
+ * @example
+ * ```ts
+ * import { buildQueueTask } from "@vitnode/core/api/lib/queue";
+ *
+ * export const reindexPostTask = buildQueueTask({
+ *   name: "reindex-post",
+ *   maxAttempts: 5,
+ *   handler: async (c, payload) => {
+ *     const postId = Number(payload.postId);
+ *     // ...
+ *   },
+ * });
+ *
+ * // In a route: await c.get("queue").dispatch({ name: "reindex-post", payload: { postId } });
+ * ```
+ */
 export function buildQueueTask({
   name,
   handler,
@@ -28,6 +78,11 @@ export function buildQueueTask({
   return { name, handler, description, leaseSeconds, maxAttempts };
 }
 
+/**
+ * Throw from a queue task handler to put the task back to `pending` until
+ * `until`, without counting the current attempt - for example while waiting
+ * on a rate limit or an external resource.
+ */
 export class QueueDeferError extends Error {
   constructor(until: Date, reason: string) {
     super(reason);
diff --git a/packages/vitnode/src/api/lib/route.ts b/packages/vitnode/src/api/lib/route.ts
index 784f46fef1..e01491062e 100644
--- a/packages/vitnode/src/api/lib/route.ts
+++ b/packages/vitnode/src/api/lib/route.ts
@@ -11,14 +11,23 @@ import { pluginMiddleware } from "../middlewares/plugin.middleware";
 import { assertStaffPermission } from "./check-staff-permission";
 import { pluginTag } from "./openapi-tags";
 
+/**
+ * Runs after request validation, as `@hono/zod-openapi`'s hook. Return a
+ * `Response` to answer a failed validation yourself; return nothing for the
+ * default handling.
+ */
 export type RouteValidationHook = (
   result: { error: ZodError; success: false } | { success: true },
   c: Context,
 ) => Promise<Response | undefined> | Response | undefined;
 
+/** The admin staff permission a route requires. */
 export interface AdminStaffPermission {
+  /** The permission module, e.g. `posts`. */
   module: string;
+  /** The permission within it, e.g. `can_edit`. */
   permission: string;
+  /** The plugin that declares the permission. Defaults to the route's own plugin. */
   plugin?: string;
 }
 
@@ -35,6 +44,11 @@ const unwrapHandler = (handler: unknown): unknown =>
     ? unwrapHandler(handler.__COMPOSED_HANDLER)
     : handler;
 
+/**
+ * Every route under an `admin` path segment without an `adminStaffPermission`
+ * guard, as sorted `METHOD /path` labels. Use it in a test (core and the
+ * bundled plugins do) to keep an admin API from shipping an unguarded route.
+ */
 export const findAdminRoutesWithoutStaffPermission = (hono: {
   routes: readonly MountedRoute[];
 }): string[] => {
@@ -57,21 +71,66 @@ export const findAdminRoutesWithoutStaffPermission = (hono: {
     .sort();
 };
 
+/** A `@hono/zod-openapi` route definition, plus VitNode's own options. */
 export type BuildRouteConfig<P extends string> = Omit<RouteConfig, "path"> & {
+  /** Relative to the module, with OpenAPI-style params, e.g. `/{id}`. Also the fetcher's `path`. */
   path: P;
+  /**
+   * Requires a valid captcha token in the `x-vitnode-captcha-token` header
+   * when the app has a captcha configured; answers `400` otherwise. Callers
+   * pass it as the fetcher's `captchaToken`. No effect without a captcha config.
+   */
   withCaptcha?: boolean;
 };
 
+/** What `buildRoute` accepts. */
 export interface BuildRouteOptions<
   P extends string,
   R extends BuildRouteConfig<P>,
 > {
+  /**
+   * Requires an admin with this staff permission; anyone else gets `403`.
+   * Paths containing `/admin/` already require an admin session, but this is
+   * the only per-permission check, so every admin route should set it.
+   */
   adminStaffPermission?: AdminStaffPermission;
+  /** The Hono handler, typed from `route`: `c.req.valid(...)` and `c.json(...)` follow its schemas. */
   handler: RouteHandler<R & { path: P }, EnvVitNode>;
   hook?: RouteValidationHook;
   route: R;
 }
 
+/**
+ * Defines one typed API route. Plugins call the bound version from
+ * `bindApiPlugin`, which supplies `pluginId`.
+ *
+ * The route is tagged with its plugin for OpenAPI and runs behind middleware
+ * that sets `c.get("plugin")`, then the staff-permission guard and the captcha
+ * check when requested, then the route's own `middleware`.
+ *
+ * @example
+ * ```ts
+ * import { z } from "@hono/zod-openapi";
+ *
+ * import { buildRoute } from "@/api/builders";
+ *
+ * export const showPostRoute = buildRoute({
+ *   adminStaffPermission: { module: "posts", permission: "can_view" },
+ *   route: {
+ *     method: "get",
+ *     path: "/{id}",
+ *     request: { params: z.object({ id: z.string() }) },
+ *     responses: {
+ *       200: {
+ *         content: { "application/json": { schema: z.object({ title: z.string() }) } },
+ *         description: "The post",
+ *       },
+ *     },
+ *   },
+ *   handler: c => c.json({ title: c.req.valid("param").id }, 200),
+ * });
+ * ```
+ */
 export const buildRoute = <
   Plugin extends string,
   P extends string,
@@ -129,6 +188,7 @@ export const buildRoute = <
   };
 };
 
+/** A built route, ready for `buildModule`'s `routes`. */
 export interface Route<
   Plugin extends string = string,
   R extends RouteConfig = RouteConfig,
diff --git a/packages/vitnode/src/api/lib/save-language-words.ts b/packages/vitnode/src/api/lib/save-language-words.ts
index 6abf4f6e5d..b5678258e3 100644
--- a/packages/vitnode/src/api/lib/save-language-words.ts
+++ b/packages/vitnode/src/api/lib/save-language-words.ts
@@ -6,14 +6,39 @@ import type { MultiLangValue } from "@/lib/helpers/multi-lang";
 
 import { core_languages_words } from "@/database/languages";
 
+/** Which field of which record a multi-language value belongs to, plus the value. */
 export interface SaveLanguageWordsArgs {
+  /** The record's id. */
   itemId: number;
+  /** The owning plugin's code, e.g. `"blog"`. */
   pluginCode: string;
+  /** The record's table, e.g. `"blog_categories"`. */
   tableName: string;
+  /** The `multiLang` field's value: one `{ languageCode, value }` per language. Empty or missing clears it. */
   values: MultiLangValue;
+  /** The field name, e.g. `"name"`. */
   variable: string;
 }
 
+/**
+ * Saves a multi-language field value (an `AutoForm` `multiLang` field) to
+ * `core_languages_words`, replacing every stored translation of that field in
+ * one transaction. Server-only; read the rows back by the same
+ * `(pluginCode, tableName, variable, itemId)` to prefill an edit form.
+ *
+ * @example
+ * ```ts
+ * import { saveLanguageWords } from "@vitnode/core/api/lib/save-language-words";
+ *
+ * await saveLanguageWords(c, {
+ *   pluginCode: "blog",
+ *   tableName: "blog_categories",
+ *   variable: "name",
+ *   itemId: category.id,
+ *   values: name,
+ * });
+ * ```
+ */
 // Write mirror of `resolveRoleNames`: persists a `multiLang` field value (the
 // `{ languageCode, value }[]` produced by the form) into `core_languages_words`.
 // The remaining columns - the `(pluginCode, tableName, variable, itemId)` tuple
diff --git a/packages/vitnode/src/api/lib/websocket.ts b/packages/vitnode/src/api/lib/websocket.ts
index 47d537dd9b..16f4236a13 100644
--- a/packages/vitnode/src/api/lib/websocket.ts
+++ b/packages/vitnode/src/api/lib/websocket.ts
@@ -7,6 +7,7 @@ export { getWebSocketId } from "@/ws/types";
 
 export type VitNodeWSContext = WSContext;
 
+/** What a WebSocket handler's `onMessage` receives for each matching client message. */
 export interface VitNodeWSMessageParams<TReceive = unknown, TSend = unknown> {
   /** Hono request context - reach the db, the user, the logger, etc. */
   c: Context<EnvVitNode>;
@@ -18,6 +19,7 @@ export interface VitNodeWSMessageParams<TReceive = unknown, TSend = unknown> {
   ws: VitNodeWSContext;
 }
 
+/** A WebSocket handler, as returned by {@link buildWebSocket}. */
 export interface BuildWebSocketReturn {
   description?: string;
   /**
@@ -25,14 +27,43 @@ export interface BuildWebSocketReturn {
    * is `{pluginId}_{module}_{id}`.
    */
   id: string;
+  /**
+   * Called for every client message whose `id` matches this socket. Errors,
+   * sync or async, are logged to the console and never close the connection.
+   */
   onMessage: (params: VitNodeWSMessageParams) => Promise<void> | void;
 }
 
+/** A WebSocket handler after registration, tagged with the module and plugin that declared it. */
 export interface WebSocketConfig extends BuildWebSocketReturn {
   module: string;
   pluginId: string;
 }
 
+/**
+ * Declares a server handler for messages sent over the shared `/api/ws`
+ * connection. Add it to a top-level module's `webSockets` array.
+ *
+ * Clients address it as `{pluginId}_{module}_{id}`; share that id and the
+ * message types with the browser through `createWebSocketChannel` from
+ * `@vitnode/core/ws/types`, and talk to it with `useVitNodeWebSocket`. To push
+ * without a client message, use `c.get("realtime")`.
+ *
+ * Only active when the app mounts the WebSocket endpoint
+ * (`handleVitNodeWebSocket`).
+ *
+ * @example
+ * ```ts
+ * import { buildWebSocket } from "@vitnode/core/api/lib/websocket";
+ *
+ * export const echoSocket = buildWebSocket<{ text: string }, { text: string }>({
+ *   id: "echo",
+ *   onMessage: ({ data, send }) => {
+ *     send({ text: data.text });
+ *   },
+ * });
+ * ```
+ */
 export function buildWebSocket<TReceive = unknown, TSend = unknown>(webSocket: {
   description?: string;
   id: string;
diff --git a/packages/vitnode/src/api/lib/with-pagination.ts b/packages/vitnode/src/api/lib/with-pagination.ts
index 695d004b41..a4f26aa175 100644
--- a/packages/vitnode/src/api/lib/with-pagination.ts
+++ b/packages/vitnode/src/api/lib/with-pagination.ts
@@ -228,6 +228,43 @@ export type PaginationCursorColumn = PgColumn<
   PgColumnBaseConfig<PaginationIdentifierDataType>
 >;
 
+/**
+ * Pages a Drizzle query by cursor (`first`/`last` + `cursor`) or by page
+ * number (`page`), and returns `{ edges, pageInfo }` ready for a list route.
+ * Server-only.
+ *
+ * Rows are ordered by `orderBy.column` with `primaryCursor` as the tiebreaker,
+ * so pages never skip or repeat rows. Page size defaults to 50 and is capped at
+ * 100. With `search`, `params.query.search` filters to rows where any of those
+ * columns contains the term (case-insensitive).
+ *
+ * Validate the query with {@link zodPaginationQuery} and describe the response
+ * with {@link zodPaginationPageInfo}.
+ *
+ * @throws `HTTPException(400)` for invalid or conflicting paging params, a
+ * tampered or stale cursor, a `primaryCursor` that is not an integer, bigint
+ * or UUID column, or an order column that cannot be paged.
+ *
+ * @example
+ * ```ts
+ * const { edges, pageInfo } = await withPagination({
+ *   c,
+ *   params: { query: c.req.valid("query") },
+ *   table: core_logs,
+ *   primaryCursor: core_logs.id,
+ *   orderBy: { column: core_logs.createdAt, order: "desc" },
+ *   query: async ({ cursorSelection, limit, offset, where, orderBy }) =>
+ *     await c
+ *       .get("db")
+ *       .select({ ...cursorSelection, id: core_logs.id, content: core_logs.content })
+ *       .from(core_logs)
+ *       .where(where)
+ *       .orderBy(orderBy)
+ *       .limit(limit)
+ *       .offset(offset),
+ * });
+ * ```
+ */
 export async function withPagination<
   QueryMin extends Record<string, unknown>,
   T extends TableConfig,
@@ -242,6 +279,7 @@ export async function withPagination<
   c,
 }: {
   c: Context;
+  /** The sort column (a column of `table`) and direction. */
   orderBy: {
     column: PgColumn;
     order: "asc" | "desc";
@@ -255,7 +293,12 @@ export async function withPagination<
       search?: string;
     };
   };
+  /** The table's unique id column, the ordering's tiebreaker. */
   primaryCursor: PaginationCursorColumn;
+  /**
+   * Runs the page query with the `where`, `orderBy`, `limit` and `offset` it is
+   * given - `limit` is one more than the page size, to detect a next page.
+   */
   query: (args: {
     /**
      * Spread this into the projection: `.select({ ...fields, ...cursorSelection })`.
@@ -270,8 +313,11 @@ export async function withPagination<
     orderBy: SQL;
     where: SQL | undefined;
   }) => Promise<QueryMin[]>;
+  /** Text columns `params.query.search` is matched against. */
   search?: T["columns"][keyof T["columns"]][];
+  /** The table being paged, for the total count and the cursor columns. */
   table: Omit<PgTableWithColumns<T>, "enableRLS">;
+  /** Your own filter, applied to the page and to `totalCount`. */
   where?: SQL;
 }): Promise<{
   edges: Omit<QueryMin, typeof PAGINATION_CURSOR_FIELD>[];
@@ -532,6 +578,7 @@ const zodPageSize = z
   .refine(value => Number(value) >= 1, "Must be greater than zero.")
   .refine(value => Number.isSafeInteger(Number(value)), "Too large.");
 
+/** The `pageInfo` a {@link withPagination} list route returns, for its response schema. */
 export const zodPaginationPageInfo = z.object({
   totalCount: z.number(),
   totalPages: z.number(),
@@ -548,6 +595,11 @@ export const zodPaginationPageInfo = z.object({
   endCursor: z.string().nullable(),
 });
 
+/**
+ * The paging query params {@link withPagination} reads - `cursor`, `first`,
+ * `last`, `page` - for a list route's request schema. Extend it with your own
+ * filters, sort options and `search`.
+ */
 export const zodPaginationQuery = z
   .object({
     cursor: z
diff --git a/packages/vitnode/src/api/middlewares/global.middleware.ts b/packages/vitnode/src/api/middlewares/global.middleware.ts
index 00a1326b3a..251af43773 100644
--- a/packages/vitnode/src/api/middlewares/global.middleware.ts
+++ b/packages/vitnode/src/api/middlewares/global.middleware.ts
@@ -95,11 +95,39 @@ declare module "hono" {
   interface ContextVariableMap extends EnvVariablesVitNode {}
 }
 
+/** The Hono environment of every VitNode API route: see {@link EnvVariablesVitNode}. */
 export interface EnvVitNode extends Env {
   Variables: EnvVariablesVitNode;
 }
 
+/**
+ * What a route handler reads with `c.get(...)`. All are set before the route
+ * runs: the global middleware sets most of them, `buildRoute` sets `plugin`,
+ * and the admin middleware fills `admin` on `/admin/` paths. They are also
+ * typed on Hono's own `Context` through `ContextVariableMap`.
+ *
+ * The models (`ai`, `cache`, `email`, ...) are per-request objects bound to the
+ * context, so they act for the current user and plugin.
+ *
+ * @example
+ * ```ts
+ * handler: async c => {
+ *   const user = c.get("user");
+ *   if (!user) throw new HTTPException(401);
+ *   const posts = await c.get("cache").remember("latest", 60, async () =>
+ *     c.get("db").select().from(blog_posts).limit(10),
+ *   );
+ *
+ *   return c.json({ posts }, 200);
+ * },
+ * ```
+ */
 export interface EnvVariablesVitNode {
+  /**
+   * The signed-in admin, on paths containing `/admin/` only - such a request
+   * without a valid admin session is answered `403` before the route runs.
+   * `null` everywhere else.
+   */
   admin: null | {
     user: {
       avatarColor: string;
@@ -123,9 +151,17 @@ export interface EnvVariablesVitNode {
       timeZone: null | string;
     };
   };
+  /** When the admin session expires; `null` outside `/admin/` paths. */
   adminSessionExpiresAt: Date | null;
+  /** The AI model registry and action runner: see {@link AIModel}. */
   ai: AIModel;
+  /** Plugin-scoped JSON cache, Redis-backed when the API config has `redis`, a no-op otherwise. */
   cache: CacheModel;
+  /**
+   * The resolved installation: the API config with its defaults applied, plus
+   * everything every plugin registered. Read-only, and mostly for core's own
+   * routes - prefer the models above.
+   */
   core: {
     ai?: VitNodeApiConfig["ai"];
     aiActions: AiActionRegistry;
@@ -193,20 +229,43 @@ export interface EnvVariablesVitNode {
     };
     webSockets: WebSocketConfig[];
   };
+  /** The Drizzle database from the API config's `dbProvider`. */
   db: Pick<VitNodeApiConfig, "dbProvider">["dbProvider"];
+  /** Renders and sends emails through the configured email adapter: see {@link EmailModel}. */
   email: EmailModel;
+  /** Emits events to registered listeners. */
   events: EventsModel;
+  /** Server-side translations, for output with no UI such as emails: see {@link I18nModel}. */
   i18n: I18nModel;
+  /**
+   * The client's IP: from a signed forwarded header (server-side fetcher
+   * calls), else the socket address (or the `x-forwarded-for` hop behind
+   * `VITNODE_TRUSTED_PROXY_HOPS` proxies), else `127.0.0.1`.
+   */
   ipAddress: string;
+  /**
+   * Writes a `debug`, `warn` or `error` entry to the `core_logs` table, with
+   * the request's plugin, path, IP and user, and echoes it to the console.
+   */
   log: LoggerMiddlewareType;
+  /** Creates and delivers user notifications. */
   notifications: NotificationsModel;
+  /**
+   * The plugin whose route is handling the request, set by every route built
+   * with `buildRoute`. Scopes `cache` keys and stored files to that plugin.
+   */
   plugin: {
     id: string;
   };
+  /** Dispatches background queue tasks. */
   queue: QueueModel;
+  /** Pushes payloads to open WebSocket connections, across instances when Redis is configured. */
   realtime: VitNodeRealtime;
+  /** Indexes and queries the search adapter: see {@link SearchModel}. */
   search: SearchModel;
+  /** Uploads, reads and deletes files through the storage adapter: see {@link StorageModel}. */
   storage: StorageModel;
+  /** The signed-in user from the session cookie, or `null` for a guest. */
   user: null | {
     avatarColor: string;
     avatarUrl: null | string;
@@ -232,6 +291,14 @@ export interface EnvVariablesVitNode {
 
 type CoreVariables = EnvVariablesVitNode["core"];
 
+/**
+ * Validates every registration once, then sets the {@link EnvVariablesVitNode}
+ * variables on each request. Mounted by `VitNodeAPI`; plugins never call it.
+ *
+ * @throws At startup, when the plugins' registrations are invalid or collide
+ * (content types, containers, editable pages, AI actions, search indexers,
+ * moderation targets and scopes).
+ */
 export const globalMiddleware = ({
   ai,
   authorization,
@@ -618,6 +685,13 @@ export const globalMiddleware = ({
   };
 };
 
+/**
+ * Requires a valid admin session and sets `admin`. `VitNodeAPI` runs it for
+ * every path containing `/admin/`; a passive request (`?passive=true`) reads
+ * the session without extending it.
+ *
+ * @throws `HTTPException(403)` without a valid admin session.
+ */
 export const globalAdminMiddleware = () => {
   return async (c: Context, next: Next) => {
     const session = await new SessionAdminModel(c).getSession({
diff --git a/packages/vitnode/src/api/middlewares/rate-limiter-config.ts b/packages/vitnode/src/api/middlewares/rate-limiter-config.ts
index a2a132a68d..71d376bc39 100644
--- a/packages/vitnode/src/api/middlewares/rate-limiter-config.ts
+++ b/packages/vitnode/src/api/middlewares/rate-limiter-config.ts
@@ -1,5 +1,11 @@
 import type { IRateLimiterOptions } from "rate-limiter-flexible";
 
+/**
+ * One category's limit, passed to `rate-limiter-flexible`: `points` requests
+ * per `duration` seconds. A request over the limit gets `429` with
+ * `Retry-After` and `X-RateLimit-Category` headers (`OPTIONS` preflights are
+ * never refused). Off in development.
+ */
 export type RateLimiterCategoryOptions = Partial<
   Pick<
     IRateLimiterOptions,
@@ -11,10 +17,23 @@ export type RateLimiterCategoryOptions = Partial<
   >
 >;
 
+/**
+ * Request limits per category, the API config's `rateLimiter`. Each request
+ * counts against `safety` plus the categories its method and path fall in.
+ * Unset categories keep their defaults.
+ */
 export interface RateLimiterConfig {
+  /**
+   * POSTs to core's sign-in, sign-up, password, email verification and passkey
+   * sign-in routes. Always counted per IP. Defaults to 10 per 60 s.
+   */
   auth?: RateLimiterCategoryOptions;
   /** @deprecated Moved to `rateLimiter.safety.blockDuration`. */
   blockDuration?: number;
+  /**
+   * POST and PATCH requests to non-admin Content Engine routes (paths with
+   * `/content/` and no `/admin/`). Defaults to 20 per 60 s.
+   */
   contentWrite?: RateLimiterCategoryOptions;
   /** @deprecated Moved to `rateLimiter.safety.duration`. */
   duration?: number;
@@ -22,11 +41,22 @@ export interface RateLimiterConfig {
   execEvenly?: boolean;
   /** @deprecated Moved to `rateLimiter.safety.execEvenlyMinDelayMs`. */
   execEvenlyMinDelayMs?: number;
+  /**
+   * Counts `read`, `write` and `contentWrite` per signed-in user instead of per
+   * IP for requests that carry a session cookie. `safety` and `auth` stay per
+   * IP. Defaults to `true`.
+   */
   perUser?: boolean;
   /** @deprecated Moved to `rateLimiter.safety.points`. */
   points?: number;
+  /** `GET` and `HEAD` requests. Defaults to 300 per 60 s. */
   read?: RateLimiterCategoryOptions;
+  /**
+   * The cap on every request, counted per IP. Defaults to 1000 per 60 s (80
+   * per 60 s while the deprecated top-level options are used).
+   */
   safety?: RateLimiterCategoryOptions;
+  /** Every request other than `GET`, `HEAD` and `OPTIONS`. Defaults to 60 per 60 s. */
   write?: RateLimiterCategoryOptions;
 }
 
@@ -101,6 +131,11 @@ const resolveCategory = (
   return resolved;
 };
 
+/**
+ * Every category's limit, with defaults filled in.
+ *
+ * @throws When the deprecated top-level options and `safety` are both set.
+ */
 export const resolveRateLimiterConfig = (
   config: RateLimiterConfig | undefined,
 ): Record<RateLimiterCategory, ResolvedRateLimiterOptions> => {
diff --git a/packages/vitnode/src/api/models/ai.ts b/packages/vitnode/src/api/models/ai.ts
index c08c3306a2..46bc0e08e6 100644
--- a/packages/vitnode/src/api/models/ai.ts
+++ b/packages/vitnode/src/api/models/ai.ts
@@ -23,6 +23,7 @@ import {
   openRouterProviderAdapter,
 } from "../lib/ai/usage-cost";
 
+/** A run request whose `action` key carries its input and output types. */
 export type TypedAiRunRequest<Input, Output> = Omit<
   AiRunRequest,
   "action" | "input"
@@ -31,12 +32,19 @@ export type TypedAiRunRequest<Input, Output> = Omit<
   input: Input;
 };
 
+/** A language model the installation offers, in the API config's `ai.models`. */
 export interface AIModelDefinition {
+  /** What the model can do; AI actions needing a capability skip models without it. Defaults to `["text"]`. */
   capabilities?: AiModelCapability[];
+  /** Stable id actions and settings refer to. The first model is the default. */
   id: string;
+  /** Tokens one input image is estimated at when reserving budget. Defaults to `2000`. */
   imageInputTokens?: number;
+  /** A Vercel AI SDK language model, e.g. `openai("gpt-5-mini")`. */
   model: LanguageModel;
+  /** Display name in the AdminCP. */
   name: string;
+  /** Per-token prices: used to reserve budget before a run, and to cost it when the provider reports no cost. */
   pricing?: AiPricing;
 }
 
@@ -54,13 +62,16 @@ export interface AIImageModelDefinition {
   name: string;
 }
 
+/** The API config's `ai` option: the models AI features may use. */
 export interface AIConfig {
   /** Text embedding models, resolved with `c.get("ai").embeddingModel(id?)`. */
   embeddingModels?: AIEmbeddingModelDefinition[];
   /** Image models, resolved with `c.get("ai").imageModel(id?)`. */
   imageModels?: AIImageModelDefinition[];
 
+  /** Language models; the first is the default. */
   models: AIModelDefinition[];
+  /** Read provider-reported costs for providers beyond the built-in AI Gateway and OpenRouter ones. */
   providerAdapters?: AiProviderAdapter[];
 }
 
@@ -77,6 +88,26 @@ export interface AIPublicModel {
 const toModelId = (model: string | { modelId: string }): string =>
   typeof model === "string" ? model : model.modelId;
 
+/**
+ * The installation's AI registry, read in a route as `c.get("ai")`.
+ *
+ * Two ways to use it: resolve a model with {@link AIModel.model} and call the Vercel
+ * AI SDK yourself, or run a registered AI action with {@link AIModel.run} or
+ * {@link AIModel.stream}, which also checks the action's permissions, enforces budgets
+ * and records usage.
+ *
+ * Model lookups throw `HTTPException(500)` when no model (or no model with
+ * that id) is configured. Action runs throw `AiError`, an `HTTPException`
+ * whose JSON body carries a `code` such as `AI_UNAUTHORIZED`, `AI_DISABLED` or
+ * `AI_NOT_CONFIGURED`.
+ *
+ * @example
+ * ```ts
+ * import { generateText } from "ai";
+ *
+ * const { text } = await generateText({ model: c.get("ai").model(), prompt });
+ * ```
+ */
 export class AIModel {
   constructor(c: Context, { ledger }: { ledger?: AiLedger } = {}) {
     this.c = c;
@@ -115,16 +146,19 @@ export class AIModel {
     return this.runnerInstance;
   }
 
+  /** Every registered AI action. */
   actions(): AiActionRegistry {
     return this.c.get("core")?.aiActions ?? new AiActionRegistry([]);
   }
 
+  /** A model's capabilities; omit `id` for the default model. */
   capabilities(id?: string): AiModelCapability[] {
     const entry = this.definition(id);
 
     return [...(entry.capabilities ?? DEFAULT_AI_MODEL_CAPABILITIES)];
   }
 
+  /** A model's configured definition; omit `id` for the default (first) model. */
   definition(id?: string): AIModelDefinition {
     const { models } = this.config();
     const found = id ? models.find(entry => entry.id === id) : models[0];
@@ -159,6 +193,7 @@ export class AIModel {
     return found.model;
   }
 
+  /** The most a run could cost, in points and USD; `null` when the price is unknown. */
   async estimate(
     request: AiRunRequest,
   ): Promise<{ maxPoints: null | string; maxUsd: null | string }> {
@@ -187,6 +222,7 @@ export class AIModel {
     return found.model;
   }
 
+  /** Where runs and usage are recorded: Postgres unless the model was built with another ledger. */
   ledger(): AiLedger {
     return this.ledgerOverride ?? new PostgresAiLedger(this.c.get("db"));
   }
@@ -199,6 +235,7 @@ export class AIModel {
     return this.definition(id).model;
   }
 
+  /** The configured models as serializable info, safe to send to the browser. Empty when AI is off. */
   models(): AIPublicModel[] {
     const ai = this.c.get("core").ai;
 
@@ -210,6 +247,15 @@ export class AIModel {
       provider: providerIdOf(entry.model),
     }));
   }
+  /**
+   * Runs a registered AI action for the signed-in user (the admin on admin
+   * paths), validating its input and output, checking its permissions and
+   * budgets, and recording usage.
+   *
+   * @throws `AiError` with `AI_UNAUTHORIZED` for a guest or a user the action
+   * does not allow, or another code when the action is unknown, disabled,
+   * unconfigured, over budget or fails.
+   */
   async run<Input, Output>(
     request: TypedAiRunRequest<Input, Output>,
   ): Promise<AiRunResult<Output>>;
@@ -217,6 +263,10 @@ export class AIModel {
   async run(request: AiRunRequest): Promise<AiRunResult<unknown>> {
     return await this.runner().run(request);
   }
+  /**
+   * {@link AIModel.run} without a user, for jobs and other background work. Only for
+   * actions whose `actors` include `system`; usage is recorded against no user.
+   */
   async runAsSystem<Input, Output>(
     request: TypedAiRunRequest<Input, Output>,
   ): Promise<AiRunResult<Output>>;
@@ -225,6 +275,10 @@ export class AIModel {
     return await this.runner().runAsSystem(request);
   }
 
+  /**
+   * {@link AIModel.run}, streaming the text as it arrives. Only for actions with text
+   * output; `result` settles once the stream ends.
+   */
   async stream<Input, Output>(
     request: TypedAiRunRequest<Input, Output>,
   ): Promise<AiStreamResult<Output>>;
diff --git a/packages/vitnode/src/api/models/email.ts b/packages/vitnode/src/api/models/email.ts
index b48f0da783..e20f4a2ce5 100644
--- a/packages/vitnode/src/api/models/email.ts
+++ b/packages/vitnode/src/api/models/email.ts
@@ -31,7 +31,16 @@ interface EmailModelSendArgsWithEmail {
   user?: never;
 }
 
+/**
+ * What an email adapter implements (e.g. `@vitnode/nodemailer`,
+ * `@vitnode/resend`); set it as the API config's `email.adapter`.
+ */
 export interface EmailApiPlugin {
+  /**
+   * Sends one rendered email. Throw to fail the send: an email sent through
+   * `EmailModel.send` is retried by its queue task when that task runs. `idempotencyKey`, when a
+   * caller of `deliver` passes one, should reach providers that support it.
+   */
   sendEmail: (args: {
     html: string;
     idempotencyKey?: string;
@@ -48,7 +57,16 @@ export interface EmailSendResult {
   id?: string;
 }
 
+/**
+ * One email to send: to a user (in their own language) or to an address with
+ * an explicit `locale`.
+ */
 export type EmailModelSendArgs = {
+  /**
+   * Returns the email's React tree, called with the recipient's locale and
+   * messages plus the site's template props. Wrap it in `DefaultTemplateEmail`
+   * yourself to get the standard layout. Ignored when `html` is given.
+   */
   content: (
     props: Omit<DefaultTemplateEmailProps, "children"> &
       Pick<EmailModelSendArgs, "user">,
@@ -56,6 +74,7 @@ export type EmailModelSendArgs = {
   html?: string;
   locale?: string;
   replyTo?: string;
+  /** A string, or a function translating it with the recipient's locale and messages. */
   subject:
     | ((props: Pick<DefaultTemplateEmailProps, "i18n">) => string)
     | string;
@@ -69,6 +88,14 @@ export interface BuiltEmail {
   to: string;
 }
 
+/**
+ * Renders React Email templates and sends them through the configured email
+ * adapter, read in a route as `c.get("email")`.
+ *
+ * Emails are written in the recipient's language - the user's own, or the
+ * `locale` given - falling back to the default locale when it is not offered,
+ * never in the language of whoever triggered the send.
+ */
 export class EmailModel {
   constructor(c: Context) {
     this.c = c;
@@ -88,6 +115,11 @@ export class EmailModel {
     return provider;
   }
 
+  /**
+   * Renders an email to HTML and plain text without sending it.
+   *
+   * @throws `HTTPException(400)` when there is no recipient address.
+   */
   async build({
     html,
     replyTo,
@@ -148,6 +180,11 @@ export class EmailModel {
     };
   }
 
+  /**
+   * Sends an already built email right away, through the adapter.
+   *
+   * @throws `HTTPException(500)` when no email adapter is configured.
+   */
   async deliver(
     email: BuiltEmail,
     { idempotencyKey }: { idempotencyKey?: string } = {},
@@ -190,6 +227,15 @@ export class EmailModel {
     );
   }
 
+  /**
+   * Renders the email now and queues core's `send-email` task (always under
+   * `@vitnode/core`, so plugin routes work too) - the request does not wait
+   * for the provider. Delivery is attempted right after the response, and the
+   * queue retries it if that fails.
+   *
+   * @throws `HTTPException(500)` when no email adapter is configured, and
+   * `HTTPException(400)` when there is no recipient address.
+   */
   async send(args: EmailModelSendArgs): Promise<void> {
     this.requireProvider();
     const email = await this.build(args);
diff --git a/packages/vitnode/src/api/models/events.ts b/packages/vitnode/src/api/models/events.ts
index 1c323a2ee2..8ed841ce79 100644
--- a/packages/vitnode/src/api/models/events.ts
+++ b/packages/vitnode/src/api/models/events.ts
@@ -23,6 +23,21 @@ export interface ContentApprovalEventPayload {
   submissionId: number;
 }
 
+/**
+ * Every server-side event, mapped to its payload. Emitting and listening are
+ * type-checked against this map.
+ *
+ * A plugin adds its own events by augmenting the interface:
+ *
+ * @example
+ * ```ts
+ * declare module "@vitnode/core/api/models/events" {
+ *   interface VitNodeEvents {
+ *     "blog.post.created": { categoryId: number; postId: number };
+ *   }
+ * }
+ * ```
+ */
 export interface VitNodeEvents {
   "ai.run.completed": {
     actionKey: string;
@@ -209,22 +224,35 @@ export interface VitNodeEvents {
 
 export type VitNodeEventName = keyof VitNodeEvents;
 
+/**
+ * Who caused an event, resolved from the emitting request: the admin on an
+ * AdminCP route, else the signed-in user, else `system` (cron, queue tasks,
+ * guests).
+ */
 export interface EventActor {
   id?: number;
   type: "admin" | "system" | "user";
 }
 
+/** An emitted event with its metadata, passed to listeners and adapters. */
 export interface EventEnvelope<K extends VitNodeEventName = VitNodeEventName> {
+  /** Who caused the event. */
   actor: EventActor;
+  /** When `emit()` was called. */
   emittedAt: Date;
+  /** A random UUID, unique per emit; also returned in the result. */
   eventId: string;
+  /** The event name, e.g. `"role.created"`. */
   name: K;
+  /** The event's data, typed by its {@link VitNodeEvents} entry. */
   payload: VitNodeEvents[K];
   /** Plugin that emitted the event. */
   pluginId: string;
 }
 
+/** One listener (or the adapter itself) that failed to handle an event. */
 export interface EventEmitFailure {
+  /** The thrown error's message. */
   error: string;
   /** Listener `name` as declared in `buildEventListener`. */
   listener: string;
@@ -233,24 +261,44 @@ export interface EventEmitFailure {
   pluginId: string;
 }
 
+/** What `emit()` reports back about delivery. */
 export interface EventEmitResult {
   /** Listeners that ran successfully before `emit()` resolved. */
   delivered: number;
+  /** The emitted envelope's id. */
   eventId: string;
+  /** Listeners that threw. When the adapter itself throws, one entry with `module: "adapter"`. */
   failures: EventEmitFailure[];
 
+  /** `delivered` when listeners ran before `emit()` resolved (the local adapter); `queued` when an adapter hands the event off. */
   status: "delivered" | "queued";
 }
 
+/**
+ * Transport for events, set as `events.adapter` in the API config. Defaults to
+ * the in-process local adapter, which runs matching listeners sequentially
+ * inside the emitting request.
+ *
+ * A custom adapter may deliver elsewhere and report `status: "queued"`.
+ * Throwing from `publish` is caught by `emit()`, logged, and reported as a
+ * failure.
+ */
 export interface EventsApiPlugin {
+  /** Shown in logs and returned by `c.get("events").name()`, e.g. `"local"`. */
   name: string;
+  /** Delivers one event to its listeners (read them from `c.get("core").events.listeners`) or hands it off. */
   publish: (c: Context, envelope: EventEnvelope) => Promise<EventEmitResult>;
 }
 
 export interface EventEmitOptions {
+  /**
+   * Plugin recorded as the emitter. Defaults to the plugin of the current
+   * route, then `@vitnode/core`.
+   */
   pluginId?: string;
 }
 
+/** Server-side events API, available as `c.get("events")` in API handlers. */
 export class EventsModel {
   constructor(c: Context) {
     this.c = c;
@@ -262,6 +310,19 @@ export class EventsModel {
     return this.c.get("core").events.adapter;
   }
 
+  /**
+   * Publishes an event to its listeners through the configured adapter.
+   *
+   * Never throws: listener and adapter errors are logged and returned in
+   * `failures`. With the local adapter the promise resolves after every
+   * listener has finished, so await it when listeners must run before the
+   * response, and keep listeners fast.
+   *
+   * @example
+   * ```ts
+   * await c.get("events").emit("role.created", { roleId: role.id });
+   * ```
+   */
   async emit<K extends VitNodeEventName>(
     name: K,
     payload: VitNodeEvents[K],
@@ -310,6 +371,7 @@ export class EventsModel {
     }
   }
 
+  /** Name of the configured adapter, e.g. `"local"`. */
   name(): string {
     return this.adapter().name;
   }
diff --git a/packages/vitnode/src/api/models/i18n.ts b/packages/vitnode/src/api/models/i18n.ts
index 3234ce34fe..872ce97e61 100644
--- a/packages/vitnode/src/api/models/i18n.ts
+++ b/packages/vitnode/src/api/models/i18n.ts
@@ -10,6 +10,11 @@ import { negotiateLocale } from "@/lib/i18n/negotiate-locale";
 
 export type Translator = ReturnType<typeof createTranslator>;
 
+/**
+ * Server-side translations, read in a route as `c.get("i18n")`. For output with
+ * no UI only, such as emails - API responses return i18n keys and let the web
+ * translate them.
+ */
 export class I18nModel {
   constructor(c: Context) {
     this.c = c;
@@ -17,6 +22,7 @@ export class I18nModel {
 
   protected readonly c: Context;
 
+  /** The merged messages of core, every plugin and the app for a locale (see {@link I18nModel.resolveLocale}). */
   async getMessages(locale?: string): Promise<Messages> {
     const core = this.c.get("core");
 
@@ -27,6 +33,16 @@ export class I18nModel {
     });
   }
 
+  /**
+   * A `use-intl` translator for a locale (see {@link I18nModel.resolveLocale}).
+   *
+   * @example
+   * ```ts
+   * const i18n = c.get("i18n");
+   * // The recipient's language, not the request's.
+   * const t = await i18n.getTranslator(i18n.resolveSupportedLocale(recipient.language));
+   * ```
+   */
   async getTranslator(locale?: string): Promise<Translator> {
     const resolved = this.resolveLocale(locale);
 
@@ -36,6 +52,10 @@ export class I18nModel {
     });
   }
 
+  /**
+   * The locale for this request: `explicit` when offered, else the signed-in
+   * user's language, else the best `Accept-Language` match, else the default.
+   */
   resolveLocale(explicit?: string): string {
     const supported = this.locales.map(locale => locale.code);
 
@@ -50,6 +70,10 @@ export class I18nModel {
     );
   }
 
+  /**
+   * `preferred` when offered, else the default locale - never the request's
+   * language. For output addressed to someone else, such as an email.
+   */
   resolveSupportedLocale(preferred?: string): string {
     const supported = this.locales.map(locale => locale.code);
 
diff --git a/packages/vitnode/src/api/models/notifications/index.ts b/packages/vitnode/src/api/models/notifications/index.ts
index 3e72b6dea0..e3fc5d7258 100644
--- a/packages/vitnode/src/api/models/notifications/index.ts
+++ b/packages/vitnode/src/api/models/notifications/index.ts
@@ -17,6 +17,7 @@ import { publishNotification } from "./publish";
 
 export type { PublishNotificationArgs, PublishNotificationResult };
 
+/** Server-side notifications API, available as `c.get("notifications")` in API handlers. */
 export class NotificationsModel {
   constructor(c: NotificationsContext) {
     this.c = c;
@@ -41,6 +42,29 @@ export class NotificationsModel {
     );
   }
 
+  /**
+   * Stores a notification event and queues delivery to its recipients. With
+   * recipients, delivery also starts once the handler returns, without
+   * delaying the response; the queue worker covers anything that does not
+   * finish then. Invalid recipient ids (and the actor, unless `allowSelf`) are
+   * dropped silently.
+   *
+   * @throws NotificationPublishError When the type is not registered or passed
+   * as a definition other than the registered one, `data` fails the schema,
+   * the idempotency key or subject is invalid, there are more than 100000
+   * recipients, or the same event is being published concurrently.
+   *
+   * @example
+   * ```ts
+   * await c.get("notifications").publish({
+   *   type: topicReplyNotification,
+   *   data: { topicId: topic.id, topicTitle: topic.title },
+   *   recipients: watcherIds,
+   *   subject: { type: "forum.topic", id: topic.id },
+   *   idempotencyKey: `reply:${reply.id}`,
+   * });
+   * ```
+   */
   async publish<TData>(
     args: PublishNotificationArgs<TData>,
   ): Promise<PublishNotificationResult> {
@@ -49,6 +73,12 @@ export class NotificationsModel {
     );
   }
 
+  /**
+   * Deletes inbox items about `subject` (optionally only one `type` or some
+   * `userIds`) and lowers unread counts in the same transaction.
+   *
+   * @returns How many items were deleted.
+   */
   async remove({
     subject,
     type,
diff --git a/packages/vitnode/src/api/models/notifications/publish.ts b/packages/vitnode/src/api/models/notifications/publish.ts
index 0f2f03aa9d..1fdc214b90 100644
--- a/packages/vitnode/src/api/models/notifications/publish.ts
+++ b/packages/vitnode/src/api/models/notifications/publish.ts
@@ -19,14 +19,32 @@ import {
 
 const MAX_EXPLICIT_RECIPIENTS = 100_000;
 
+/** What `c.get("notifications").publish()` takes. */
 export interface PublishNotificationArgs<TData> {
+  /**
+   * Who caused it. Defaults to the request's admin or signed-in user; `null`
+   * for none. The actor is dropped from `recipients` unless `allowSelf`.
+   */
   actorId?: null | number;
   allowSelf?: boolean;
+  /** Validated against the type's `schema`. */
   data: NoInfer<TData>;
+  /**
+   * One key per real-world event, 1-255 characters. Publishing the same type
+   * with the same key again returns `duplicate: true` instead of notifying
+   * twice.
+   */
   idempotencyKey: string;
+  /**
+   * Candidate user ids, at most 100000. Core still drops deleted users,
+   * members who turned the type off and those `access` rejects.
+   */
   recipients?: readonly number[];
+  /** What the notification is about; used by `remove()`, grouping and `subjectType`. */
   subject?: NotificationSubject;
+  /** A transaction to publish in, so the event only exists if it commits. */
   tx?: NotificationsDb;
+  /** The registered definition (preferred, for typed `data`) or its id. */
   type: NotificationTypeDefinition<TData> | string;
 }
 
@@ -35,6 +53,7 @@ export interface PublishNotificationResult {
   eventId: number;
 }
 
+/** Thrown by `publish()` for invalid input; see {@link PublishNotificationArgs}. */
 export class NotificationPublishError extends Error {
   constructor(message: string) {
     super(`[Notifications] ${message}`);
diff --git a/packages/vitnode/src/api/models/queue.ts b/packages/vitnode/src/api/models/queue.ts
index 8e03b12778..2be85946cc 100644
--- a/packages/vitnode/src/api/models/queue.ts
+++ b/packages/vitnode/src/api/models/queue.ts
@@ -2,20 +2,43 @@ import type { Context } from "hono";
 
 import { core_queue } from "@/database/queue";
 
+/** What to enqueue with `c.get("queue").dispatch()`. */
 export interface QueueDispatchArgs {
+  /** Earliest time the task may run. Defaults to now. */
   availableAt?: Date;
+  /**
+   * While a task with the same plugin id and `dedupeKey` is pending or
+   * processing, a new dispatch is dropped and reported as `deduplicated`.
+   */
   dedupeKey?: string;
+  /** Overrides the handler's `maxAttempts`; falls back to 3. */
   maxAttempts?: number;
+  /** The `name` of a task registered with `buildQueueTask`. */
   name: string;
+  /** JSON-serializable data passed to the handler. Defaults to `{}`. */
   payload?: Record<string, unknown>;
 
+  /**
+   * Plugin that owns the handler. Defaults to the plugin of the current
+   * request's route, then `@vitnode/core`.
+   */
   pluginId?: string;
+  /** Higher runs first. Defaults to 0. */
   priority?: number;
+  /**
+   * Queue name. Defaults to `"default"`. The default worker drains every queue
+   * except `ai`, which core's AI cron drains on its own.
+   */
   queue?: string;
 
+  /**
+   * A transaction to insert with, so the task is only enqueued if the
+   * surrounding write commits.
+   */
   tx?: Omit<Context["var"]["db"], "$client">;
 }
 
+/** Server-side queue API, available as `c.get("queue")` in API handlers. */
 export class QueueModel {
   constructor(c: Context) {
     this.c = c;
@@ -23,6 +46,13 @@ export class QueueModel {
 
   protected readonly c: Context;
 
+  /**
+   * Enqueues a task. Does not run it - the queue worker picks it up on a
+   * later tick.
+   *
+   * @returns The new row's id, or `{ deduplicated: true, id: null }` when an
+   * active task with the same `dedupeKey` already exists.
+   */
   async dispatch({
     dedupeKey,
     name,
diff --git a/packages/vitnode/src/api/models/search.ts b/packages/vitnode/src/api/models/search.ts
index 47a09b3394..f1a9f86c37 100644
--- a/packages/vitnode/src/api/models/search.ts
+++ b/packages/vitnode/src/api/models/search.ts
@@ -44,20 +44,37 @@ const SEARCH_TOP_AUTHORS_TTL_SECONDS = 5 * 60;
 // bind-parameter cap while still turning a rebuild page into one round trip.
 const BULK_UPSERT_CHUNK = 500;
 
+/**
+ * One searchable item (or one language of it), as an indexer or a write hands
+ * it to {@link SearchModel}.
+ */
 export interface SearchDocument {
+  /** Users credited for the item, for author filters and author hits. */
   authorIds?: readonly number[];
+  /** The forum, category or other container holding the item. */
   containerId?: number;
   containerType?: string;
+  /** Searchable body text. HTML is stripped before it is indexed. */
   content: string;
   createdAt: Date;
+  /** A `core_files` id shown as the hit's image. */
   imageId?: null | number;
+  /**
+   * With `isPublic: false`, still lets its authors and viewers with moderator
+   * access to its item type find it. Hides nothing on its own. Defaults to
+   * `false`.
+   */
   isHidden?: boolean;
+  /** Found by everyone. Defaults to `true`; `false` hides it from ordinary searches. */
   isPublic?: boolean;
+  /** The item's id; with `itemType` (and `languageCode`) it identifies the document. */
   itemId: ContentId;
+  /** The collection, e.g. a content type id. One indexer owns each item type. */
   itemType: string;
   // Locale of this projection. Multi-language content emits one document per
   // language; single-language content may leave it empty.
   languageCode?: string;
+  /** Extra data returned with the hit. */
   metadata?: Record<string, unknown>;
   // The plugin that owns this item. Omit it and {@link SearchModel} falls back
   // to the request's plugin - which is only right while the request *is* the
@@ -66,9 +83,11 @@ export interface SearchDocument {
   pluginId?: string;
   title: string;
   updatedAt?: Date;
+  /** Where the hit links to. */
   url?: string;
 }
 
+/** A search query: filters, sorting and cursor pagination. */
 export interface SearchQueryParams {
   authorId?: number;
   authorIds?: readonly number[];
@@ -77,7 +96,9 @@ export interface SearchQueryParams {
   dateFrom?: Date;
   dateTo?: Date;
   first?: number;
+  /** Lets this viewer also find hidden documents they wrote or moderate. */
   hiddenAccess?: SearchHiddenAccess;
+  /** Skips every visibility check - for admin and diagnostic reads only. */
   includePrivate?: boolean;
   itemTypes?: string[];
   // Restrict results to one locale (the viewer's). Rows with an empty
@@ -209,12 +230,27 @@ export type SearchIndexerLoadResult =
 
   LegacySearchIndexerPage | SearchIndexerPage;
 
+/**
+ * Rebuilds one item type's search documents from its source, page by page,
+ * when an admin reindexes it. Register it on a module's (or the plugin's)
+ * `searchIndexers`; live writes keep the index current in between with
+ * `c.get("search").index()` and `.delete()`.
+ *
+ * Content types with `search` enabled get one from the Content Engine; write
+ * one only for data of your own.
+ */
 export interface SearchIndexer {
   // Total number of source items available to index for this type. Powers the
   // admin coverage report (indexed vs. total). Omit when the source count is
   // unknown or expensive; coverage then falls back to the indexed count (100%).
   count?: (c: Context) => Promise<number>;
+  /** The collection this indexer owns. Two indexers for one item type fail at startup. */
   itemType: string;
+  /**
+   * Reads up to `limit` source rows starting at `offset` and returns their
+   * documents, plus how many source rows it read; `itemsRead: 0` ends the
+   * rebuild. The rebuild clears the item type first.
+   */
   load: (
     c: Context,
     offset: number,
@@ -375,6 +411,13 @@ const toRow = (doc: SearchDocument) => ({
   indexedAt: new Date(),
 });
 
+/**
+ * The search index, read in a route as `c.get("search")`.
+ *
+ * Every write goes to the canonical `core_search_index` table and is mirrored
+ * to the configured search adapter (Postgres by default), which answers
+ * queries.
+ */
 export class SearchModel {
   constructor(c: Context) {
     this.c = c;
@@ -695,6 +738,7 @@ export class SearchModel {
     });
   }
 
+  /** {@link SearchModel.index} for many documents at once. */
   async bulkIndex(docs: SearchDocument[]): Promise<void> {
     const clean = docs.map(doc =>
       this.resolveOwner({ ...doc, content: stripHtml(doc.content) }),
@@ -704,6 +748,7 @@ export class SearchModel {
     await this.provider().bulkIndex(this.c, clean);
   }
 
+  /** Removes every document of one item type, or of all of them when omitted. */
   async clear(itemType?: string): Promise<void> {
     await this.c
       .get("db")
@@ -832,7 +877,10 @@ export class SearchModel {
       );
   }
 
-  /** Canonical projection lives in `core_search_index`; the provider mirrors it. */
+  /**
+   * Adds or replaces one document. Canonical projection lives in
+   * `core_search_index`; the provider mirrors it.
+   */
   async index(doc: SearchDocument): Promise<void> {
     const clean = this.resolveOwner({
       ...doc,
@@ -862,6 +910,7 @@ export class SearchModel {
     return this.provider().capabilities?.canonicalStorage === true;
   }
 
+  /** Whether the item has a public document in the index. */
   async isListed(itemType: string, itemId: string): Promise<boolean> {
     const [row] = await this.c
       .get("db")
@@ -916,6 +965,7 @@ export class SearchModel {
     await recordSearchPopularity(this.c, { itemId, itemType, signal });
   }
 
+  /** Runs a query on the search adapter and attaches each hit's authors and image. */
   async search(params: SearchQueryParams): Promise<SearchResult> {
     const result = await this.provider().search(
       this.c,
diff --git a/packages/vitnode/src/api/models/sso.ts b/packages/vitnode/src/api/models/sso.ts
index e8fbe090e6..f70156ac62 100644
--- a/packages/vitnode/src/api/models/sso.ts
+++ b/packages/vitnode/src/api/models/sso.ts
@@ -32,28 +32,52 @@ import {
 } from "./sso-link-token";
 import { UserModel } from "./user";
 
+/** The account an SSO provider returned, as an adapter's `fetchUser` maps it. */
 export interface SSOProviderUser {
+  /** Profile picture URL, for profile sync. */
   avatarUrl?: null | string;
+  /** The account's email. Matched against existing VitNode accounts on first sign-in. */
   email: string;
   firstName?: null | string;
+  /** The provider's stable account id, stored to recognise the account next time. */
   id: string;
   lastName?: null | string;
+  /** Becomes the new user's name (special characters removed) on sign-up. */
   username: string;
 }
 
+/**
+ * An SSO (OAuth) provider adapter, listed in the API config's
+ * `authorization.ssoAdapters`. Core's built-in adapters live in
+ * `@vitnode/core/api/adapters/sso/*`; a custom provider implements this shape.
+ *
+ * Sign-in flow: `getUrl` sends the browser to the provider, which redirects to
+ * {@link getRedirectUri} with a `code`; core verifies the `state` cookie, then
+ * calls `fetchToken` and `fetchUser`. An unknown account signs up, a known one
+ * signs in, and an email that matches an existing account asks for that
+ * account's password before linking. Server-only.
+ */
 export interface SSOApiPlugin {
+  /** The sign-in button's background color, e.g. `"#5865f2"`; the text color is picked for contrast. */
   brandColor?: string;
+  /** Exchanges the authorization code for an access token. Throw an `HTTPException` to fail the sign-in. */
   fetchToken: (
     code: string,
   ) => Promise<{ access_token: string; token_type: string }>;
+  /** Reads the provider account with the token. Throw an `HTTPException` (e.g. `400` for an unverified email) to refuse it. */
   fetchUser: (args: {
     access_token: string;
     token_type: string;
   }) => Promise<SSOProviderUser>;
+  /** The provider's authorization URL. Must pass `state` through unchanged and use {@link getRedirectUri} as the redirect URI. */
   getUrl: (props: { state: string }) => string;
+  /** The button's icon, as SVG markup. */
   icon?: string;
+  /** Unique provider id, used in URLs (`login/sso/{id}`) and to store linked accounts. */
   id: string;
+  /** The provider's display name, e.g. `"Google"`. */
   name: string;
+  /** Which profile fields `fetchUser` supplies, so users can sync them from this provider. Defaults to none. */
   profileFields?: readonly SsoProfileField[];
 }
 
@@ -66,6 +90,11 @@ export type SSOCallbackOutcome =
     }
   | { kind: "signed_in"; userId: number };
 
+/**
+ * The OAuth redirect URI for provider `code`: `login/sso/{code}` under
+ * `VITNODE_WEB_URL`. Register it with the provider, and send the same value
+ * from `getUrl` and `fetchToken`.
+ */
 export const getRedirectUri = (code: string) =>
   new URL(`${CONFIG.web.href}login/sso/${code}`).toString();
 
diff --git a/packages/vitnode/src/api/models/storage.ts b/packages/vitnode/src/api/models/storage.ts
index 4368720ac1..d964bdfa5a 100644
--- a/packages/vitnode/src/api/models/storage.ts
+++ b/packages/vitnode/src/api/models/storage.ts
@@ -41,23 +41,34 @@ const PROCESSABLE_IMAGE_MIME_TYPES = new Set([
   "image/webp",
 ]);
 
+/** One object for a storage adapter to write. */
 export interface StorageUploadArgs {
+  /** The file's bytes, after any image processing. */
   body: Buffer;
+  /** The MIME type to store with the object, when known. */
   contentType?: string;
+  /** The full object key, e.g. `2026/07/avatars/{uuid}.webp`, already unique. */
   key: string;
 }
 
+/** What a storage adapter's `upload` returns. */
 export interface StorageUploadResult {
+  /** The key the object was stored under, normally the one it was given. */
   key: string;
+  /** The object's public URL, usually `getUrl(key)`. */
   url: string;
 }
 
+/** An uploaded file, as {@link StorageModel.upload} recorded it. */
 export interface StorageFileUploadResult extends StorageUploadResult {
+  /** Pixel size when `storage.image` processing read the image; `null` otherwise. */
   dimensions: null | { height: number; width: number };
+  /** The `core_files` row id - what content file fields reference. */
   id: number;
   mimeType: null | string;
   /** The display name as stored, which a format conversion may have changed. */
   name: string;
+  /** Bytes stored, after any image processing. */
   size: number;
 }
 
@@ -65,6 +76,7 @@ export type { StorageFileInUseBody } from "@/lib/files/in-use";
 export { STORAGE_FILE_IN_USE } from "@/lib/files/in-use";
 
 export interface StorageDeleteFileOptions {
+  /** Also drop pins held by retained content revisions. A live reference still refuses. */
   force?: boolean;
   /** Scopes the delete to one user's own uploads. */
   ownerId?: number;
@@ -79,29 +91,46 @@ const storageFileInUse = (body: Omit<StorageFileInUseBody, "code">) =>
   });
 
 /**
- * Present only on disk-backed adapters (e.g. Local). The Node entry point reads
- * it to mount `serveStatic` for the stored files. Cloud adapters omit it.
+ * Present only on disk-backed adapters (e.g. Local). The app's server entry
+ * reads it to mount `serveStatic` for the stored files; core mounts nothing by
+ * itself. Cloud adapters omit it.
  */
 export interface StorageStaticConfig {
+  /** The route pattern to mount, relative to the API app, e.g. `/uploads/*`. */
   mountPath: string;
+  /** The folder the files are served from, e.g. `./public/uploads`. */
   root: string;
+  /** Removed from the request path before looking the file up in `root`. */
   stripPrefix: string;
 }
 
+/**
+ * What a storage adapter implements (e.g. `@vitnode/s3`,
+ * `@vitnode/supabase-storage`); set it as the API config's `storage.adapter`.
+ */
 export interface StorageApiPlugin {
+  /** Removes a stored object. Core also calls it to clean up an upload whose `core_files` row could not be written. */
   delete: (key: string) => Promise<void>;
+  /** The public URL of a stored object. */
   getUrl: (key: string) => string;
+  /**
+   * Reads an object's bytes, or `null` when missing. Optional: without it,
+   * reads fetch `getUrl`.
+   */
   read?: (
     key: string,
     options: { maxBytes: number },
   ) => Promise<null | Uint8Array>;
+  /** How to serve stored files from disk; only for disk-backed adapters. */
   static?: StorageStaticConfig;
+  /** Writes one object under `args.key` and returns its key and public URL. */
   upload: (args: StorageUploadArgs) => Promise<StorageUploadResult>;
 }
 
 export interface StorageUploadOptions {
   /** Allowed MIME types (e.g. `["image/png", "image/jpeg"]`). Omit to allow any. */
   allowedMimeTypes?: string[];
+  /** The uploaded file, e.g. from `c.req.valid("form")`. */
   file: File;
   /** Sub-folder under the dated prefix, e.g. `avatars` -> `2026/07/avatars/…`. */
   folder: string;
@@ -110,6 +139,7 @@ export interface StorageUploadOptions {
   /** Extra data stored in the `core_files.metadata` JSON column. */
   metadata?: Record<string, unknown>;
 
+  /** The owner recorded on the file. Defaults to the signed-in admin or user; `null` for none. */
   userId?: null | number;
 }
 
@@ -243,6 +273,13 @@ const imageEncodeFailure = ({
   });
 };
 
+/**
+ * Stores files through the configured storage adapter and records each one in
+ * `core_files`, read in a route as `c.get("storage")`.
+ *
+ * Every method except `deleteFile` throws `HTTPException(500)` when no
+ * storage adapter is configured.
+ */
 export class StorageModel {
   constructor(c: Context) {
     this.c = c;
@@ -374,6 +411,10 @@ export class StorageModel {
     return provider;
   }
 
+  /**
+   * Deletes the stored object only, leaving any `core_files` row. To remove an
+   * uploaded file, use {@link StorageModel.deleteFile}.
+   */
   async delete(key: string): Promise<void> {
     await this.requireProvider().delete(key);
   }
@@ -478,10 +519,12 @@ export class StorageModel {
     await releaseUserImageHolders(this.c, deleted.holders);
   }
 
+  /** The public URL of a stored object. */
   getUrl(key: string): string {
     return this.requireProvider().getUrl(key);
   }
 
+  /** An object's bytes, or `null` when it is missing, unreadable or larger than `maxBytes`. */
   async readBytes(key: string, maxBytes: number): Promise<Buffer | null> {
     const provider = this.requireProvider();
     if (provider.read) {
@@ -517,6 +560,20 @@ export class StorageModel {
     return Buffer.concat(chunks);
   }
 
+  /**
+   * Validates, stores and records one uploaded file, owned by the current
+   * plugin and user.
+   *
+   * When the API config sets `storage.image`, JPEG, PNG, WebP, AVIF and TIFF
+   * images are re-encoded at its quality and, by default, converted to WebP;
+   * the key and name follow any new extension. SVG, GIF and other files are
+   * stored as they are. An AI alt-text job is queued for images when that
+   * feature is on.
+   *
+   * @throws `HTTPException(400)` when the file is over `maxBytes`, not an
+   * allowed type, or an image that does not match its declared type, cannot be
+   * decoded or exceeds `storage.image.maxPixels`.
+   */
   async upload({
     allowedMimeTypes,
     file,
diff --git a/packages/vitnode/src/blocks/area.ts b/packages/vitnode/src/blocks/area.ts
index 4b6fda2e9b..437f8d9015 100644
--- a/packages/vitnode/src/blocks/area.ts
+++ b/packages/vitnode/src/blocks/area.ts
@@ -95,6 +95,7 @@ export const isAreaLike = (value: unknown): boolean =>
   !Array.isArray(value) &&
   (value as Record<string, unknown>).kind === CONTENT_AREA_KIND;
 
+/** Whether a stored zone node is a layout Area (`kind: "area"` with an id, a valid layout and a children array) rather than a widget. */
 export const isBlockAreaInstance = (
   value: unknown,
 ): value is BlockAreaInstance => {
@@ -237,6 +238,10 @@ export const contentNodeKey = (node: unknown, index: number): string => {
 export const areaChildren = (node: ContentNode): readonly AnyBlockInstance[] =>
   isBlockAreaInstance(node) ? node.children : [];
 
+/**
+ * Every widget in a zone's nodes, with each Area replaced by its children -
+ * for counting, indexing or checking widgets regardless of layout.
+ */
 export const contentNodeBlocks = (
   nodes: readonly ContentNode[],
 ): readonly AnyBlockInstance[] =>
diff --git a/packages/vitnode/src/blocks/built-in/index.tsx b/packages/vitnode/src/blocks/built-in/index.tsx
index af43812831..4d5fa51ac0 100644
--- a/packages/vitnode/src/blocks/built-in/index.tsx
+++ b/packages/vitnode/src/blocks/built-in/index.tsx
@@ -10,10 +10,15 @@ export { ctaBlock } from "./cta";
 export { heroBlock } from "./hero";
 export { textBlock } from "./text";
 
+/**
+ * Core's built-in widgets - Call to action, Hero and Text - under the `core`
+ * namespace (`core:hero`, ...). Core registers them itself.
+ */
 export const blocks = {
   pluginId: manifest.id,
   blocks: [ctaBlock, heroBlock, textBlock],
   namespace: "core",
 } satisfies BlockPluginSource;
 
+/** Alias of {@link blocks}. */
 export const widgets = blocks;
diff --git a/packages/vitnode/src/blocks/define.ts b/packages/vitnode/src/blocks/define.ts
index 5151631840..6463065208 100644
--- a/packages/vitnode/src/blocks/define.ts
+++ b/packages/vitnode/src/blocks/define.ts
@@ -13,18 +13,38 @@ import { BLOCK_VARIANT_ID_MAX_LENGTH, BLOCK_VARIANT_PATTERN } from "./const";
 import { BlockError } from "./errors";
 import { assertBlockName } from "./namespace";
 
+/** What {@link defineBlock} (exported as `defineWidget`) takes. */
 export interface DefineBlockArgs<
   TId extends string,
   TFields extends BlockFieldMap,
   TVariant extends string = string,
 > {
+  /** Renders one instance; `data` is as stored - validated on write and shape-checked before render. */
   component: BlockComponent<BlockData<TFields>, TVariant>;
+  /** Variant used when an instance stores none. Must be one of `variants`. */
   defaultVariant?: NoInfer<TVariant>;
+  /** Shown in the Visual Editor's catalogue. */
   description?: string;
+  /**
+   * Content Engine fields (`field.text()`, `field.enum()`, ...) the data is
+   * validated and edited with. Only boolean, dateTime, enum, group, number,
+   * text and textarea fields are accepted, at least one, and fields are never
+   * localized.
+   */
   fields: TFields;
+  /** Icon component (not an element) for the editor; defaults to a generic widget icon. */
   icon?: BlockIcon;
+  /**
+   * Name without a namespace, e.g. `"callout"`. The registry prefixes the
+   * plugin's namespace, so it is stored as `example:callout`.
+   */
   id: TId;
+  /** Display name in the editor. */
   name?: string;
+  /**
+   * Alternative looks for the same data. The chosen id is stored beside the
+   * instance's data, and the editor shows a picker for it.
+   */
   variants?: readonly BlockVariantDefinition<TVariant>[];
 }
 
@@ -83,6 +103,39 @@ const assertBlockVariants = (
   }
 };
 
+/**
+ * Declares a widget: an id, Content Engine fields and one React component. The
+ * data type is inferred from `fields` (`WidgetData<typeof fields>`).
+ *
+ * Universal and validation-free at render time - the data schema is derived
+ * on demand by `parseWidgetData` / `widgetDataSchema`. List the definition in
+ * the plugin's widgets source and pass that to `buildApiPlugin({ blocks })`.
+ *
+ * @throws {BlockError} For an invalid or namespaced `id`, an unsupported
+ * field kind, invalid or duplicate variant ids, an empty `variants`, or a
+ * `defaultVariant` that is not declared.
+ *
+ * @example
+ * ```tsx
+ * import { field } from "@vitnode/core/content";
+ * import { defineWidget, type WidgetComponentProps, type WidgetData } from "@vitnode/core/widgets";
+ *
+ * const calloutFields = {
+ *   title: field.text({ required: true, maxLength: 120 }),
+ * };
+ *
+ * const Callout = ({ data }: WidgetComponentProps<WidgetData<typeof calloutFields>>) => (
+ *   <aside>{data.title}</aside>
+ * );
+ *
+ * export const calloutWidget = defineWidget({
+ *   id: "callout",
+ *   name: "Callout",
+ *   fields: calloutFields,
+ *   component: Callout,
+ * });
+ * ```
+ */
 export const defineBlock = <
   const TFields extends BlockFieldMap,
   TId extends string = string,
diff --git a/packages/vitnode/src/blocks/edit.tsx b/packages/vitnode/src/blocks/edit.tsx
index a53ebe0069..9ca2b77a52 100644
--- a/packages/vitnode/src/blocks/edit.tsx
+++ b/packages/vitnode/src/blocks/edit.tsx
@@ -24,9 +24,16 @@ import { BlockError } from "./errors";
 const EditorRoot = lazy(async () => await import("../editor/root"));
 
 export interface ContentEditorRuntimeProps {
+  /** Where **Save** sends the zones. Without one, Save shows an error toast and saves nothing. */
   adapter?: VisualEditorAdapter;
+  /** The page; every `ContentZone` inside it becomes editable while `enabled`. */
   children: ReactNode;
+  /**
+   * `false` renders only `children` (after a short closing transition); `true`
+   * lazy-loads and mounts the editor.
+   */
   enabled: boolean;
+  /** Called when the editor is closed (**Finish editing**), after its unsaved-changes prompt. */
   onExit?: () => void;
 }
 
@@ -37,6 +44,14 @@ const duplicateContentZone = (id: string): BlockError =>
     `Two \`<ContentZone id=${JSON.stringify(id)} />\` outlets are on the page at the same time. A zone id names one place on one page, and the editor stores, moves and saves blocks by it - with two of them it cannot tell which one a block belongs to, and saving would write one over the other. Give each zone its own id, or render only one of them.`,
   );
 
+/**
+ * The low-level Visual Editor host: wraps a page and, while `enabled`, turns
+ * its `ContentZone`s into editable outlets. For a host that owns edit mode and
+ * persistence itself; a declared editable page uses `EditablePage` instead.
+ *
+ * @throws {BlockError} When two `ContentZone`s with the same id are mounted
+ * at once while editing.
+ */
 export const ContentEditorRuntime = ({
   adapter,
   children,
diff --git a/packages/vitnode/src/blocks/instance.ts b/packages/vitnode/src/blocks/instance.ts
index 99617aa5af..6ac70d9d52 100644
--- a/packages/vitnode/src/blocks/instance.ts
+++ b/packages/vitnode/src/blocks/instance.ts
@@ -37,6 +37,7 @@ const encodeTime = (time: number): string => {
   return out;
 };
 
+/** A new time-sortable, ULID-style instance id. */
 export const createBlockInstanceId = (now = Date.now()): string => {
   const bytes = randomBytes(RANDOM_LENGTH);
   let random = "";
@@ -49,6 +50,7 @@ export const createBlockInstanceId = (now = Date.now()): string => {
 export const isBlockInstanceId = (value: unknown): value is string =>
   typeof value === "string" && BLOCK_INSTANCE_ID_PATTERN.test(value);
 
+/** A new instance with a fresh id. Pass the qualified `type`, e.g. `"example:callout"`. */
 export const createBlockInstance = <TType extends string, TData>(
   type: TType,
   data: TData,
diff --git a/packages/vitnode/src/blocks/page.tsx b/packages/vitnode/src/blocks/page.tsx
index fe5ac4f8df..2581f334a8 100644
--- a/packages/vitnode/src/blocks/page.tsx
+++ b/packages/vitnode/src/blocks/page.tsx
@@ -25,15 +25,31 @@ import { EditablePageContext } from "./page-context";
 import { adoptedZones, layoutKey, layoutZones } from "./page-layout";
 
 export interface EditablePageProps {
+  /** Where **Save** goes, e.g. one from `createContentEditorAdapter`. */
   adapter?: VisualEditorAdapter;
+  /**
+   * Mounts the editor runtime and offers **Edit widgets** in the user menu.
+   * UI only - the save route checks the page's permission again.
+   */
   canEdit?: boolean;
   children: ReactNode;
+  /** The effective layout from the page-layout API; zones it lacks fall back to the declared defaults. */
   layout?: EditablePageLayoutPayload | null;
+  /** Called by **Finish editing**, after the unsaved-changes prompt. */
   onExit?: () => void;
+  /** Open in edit mode on arrival (`?edit=true`). Ignored unless `canEdit`. */
   openEditing?: boolean;
+  /** The page from `defineEditablePage`. */
   page: AnyEditablePageDefinition;
 }
 
+/**
+ * Wraps the `ContentZone`s of a page declared with `defineEditablePage`, so
+ * they render the stored layout and can be rearranged in the Visual Editor.
+ * After a save it adopts the canonical zones the server returned.
+ *
+ * @throws {ContentEngineError} When `layout` belongs to a different page id.
+ */
 export const EditablePage = ({
   adapter,
   canEdit,
diff --git a/packages/vitnode/src/blocks/registry.ts b/packages/vitnode/src/blocks/registry.ts
index b060a313c2..bd53200d80 100644
--- a/packages/vitnode/src/blocks/registry.ts
+++ b/packages/vitnode/src/blocks/registry.ts
@@ -18,6 +18,14 @@ import {
 const describe = (entry: RegisteredBlock): string =>
   `${entry.pluginId} -> ${entry.type}`;
 
+/**
+ * Builds a registry from every plugin's widgets, prefixing each id with its
+ * namespace. The app's generated `src/blocks.gen.ts` calls this and installs
+ * the result as the default.
+ *
+ * @throws {BlockError} When two plugins claim one namespace, one plugin uses
+ * two, or a qualified id is registered twice.
+ */
 export const createBlockRegistry = (
   sources: readonly BlockPluginSource[],
 ): BlockRegistry => {
@@ -85,6 +93,7 @@ export const createBlockRegistry = (
   };
 };
 
+/** Whether a qualified widget id matches an allowlist. */
 export const isBlockAllowed = (
   allowed: BlockAllowedSpec,
   type: string,
@@ -116,6 +125,11 @@ export const allowedBlocks = (
 
 let processDefault: BlockRegistry | undefined;
 
+/**
+ * Installs the process-wide registry used when none is passed explicitly.
+ *
+ * @returns A function restoring the previous default.
+ */
 export const setDefaultBlockRegistry = (
   registry: BlockRegistry | undefined,
 ): (() => void) => {
@@ -130,6 +144,11 @@ export const setDefaultBlockRegistry = (
 export const getDefaultBlockRegistry = (): BlockRegistry | undefined =>
   processDefault;
 
+/**
+ * The given registry, else the process default.
+ *
+ * @throws {BlockRegistryMissingError} When neither exists.
+ */
 export const resolveBlockRegistry = (
   registry?: BlockRegistry,
 ): BlockRegistry => {
diff --git a/packages/vitnode/src/blocks/renderer.tsx b/packages/vitnode/src/blocks/renderer.tsx
index 0214578821..69a41aff63 100644
--- a/packages/vitnode/src/blocks/renderer.tsx
+++ b/packages/vitnode/src/blocks/renderer.tsx
@@ -243,13 +243,34 @@ const renderNode = ({
 };
 
 export interface ContentRendererProps {
+  /** The zone's allowlist. A stored widget it does not allow is skipped, but only when `validate` diagnoses. */
   allowed?: BlockAllowedSpec;
+  /** The zone's stored nodes (widgets and Areas). Nothing renders when empty or missing. */
   blocks?: null | readonly unknown[] | undefined;
+  /**
+   * Renders a skipped widget (unknown type or variant, mismatched data, not
+   * allowed). Defaults to a notice in development and nothing in production.
+   */
   fallback?: BlockRenderFallback;
+  /** The widget registry to look types up in. Defaults to the process-wide registry. */
   registry?: BlockRegistry;
+  /**
+   * Whether the zone allowlist is enforced and data mismatches are logged
+   * (`"always"`, `"development"`, `"never"`). Defaults to `"development"`.
+   * Other warnings log in development regardless, and nothing logs in
+   * production.
+   */
   validate?: BlockValidationMode;
 }
 
+/**
+ * Renders a zone's stored widgets and layout Areas read-only, looking each
+ * widget up in the registry. Universal; data is not re-validated here - only a
+ * structural check against the widget's current fields runs before render.
+ *
+ * @throws {BlockRegistryMissingError} When no `registry` is passed and no
+ * process-wide registry is installed.
+ */
 export const ContentRenderer = ({
   allowed,
   blocks,
diff --git a/packages/vitnode/src/blocks/schema.ts b/packages/vitnode/src/blocks/schema.ts
index 7a25b58e70..d0cddb169d 100644
--- a/packages/vitnode/src/blocks/schema.ts
+++ b/packages/vitnode/src/blocks/schema.ts
@@ -12,6 +12,7 @@ export const buildBlockDataSchema = (
   fields: ContentFieldMap,
 ): z.ZodObject<z.ZodRawShape> => contentFieldValuesObject(fields);
 
+/** The Zod object for a widget's data, built from its fields once and cached per definition. */
 export const blockDataSchema = (
   definition: AnyBlockDefinition,
 ): z.ZodObject<z.ZodRawShape> => {
@@ -39,6 +40,12 @@ export const safeParseBlockData = (
 ): z.ZodSafeParseResult<unknown> =>
   blockDataSchema(definition).safeParse(value);
 
+/**
+ * Validates widget data and applies defaults - for seeds, migrations and
+ * importers; the Content Engine already does this on every write.
+ *
+ * @throws {BlockError} Naming the failing fields.
+ */
 export const parseBlockData = <TFields extends ContentFieldMap>(
   definition: BlockDefinition<string, TFields>,
   value: unknown,
diff --git a/packages/vitnode/src/blocks/types.ts b/packages/vitnode/src/blocks/types.ts
index 72e9daaf71..ef9162e4ee 100644
--- a/packages/vitnode/src/blocks/types.ts
+++ b/packages/vitnode/src/blocks/types.ts
@@ -11,26 +11,34 @@ import type {
 
 export type BlockFieldMap = Record<string, { kind: string }>;
 
+/** A widget's data type, inferred from its field map. */
 export type BlockData<TFields> = ContentValuesOf<TFields>;
 
 export type BlockUnknownData = Record<string, unknown>;
 
 export interface BlockVariantDefinition<TId extends string = string> {
   description?: string;
+  /** Lowercase letters, digits and single hyphens. Stored in every instance that picks it, so keep it stable. */
   id: TId;
   label?: string;
 }
 
 export type AnyBlockVariantDefinition = BlockVariantDefinition;
 
+/** Props of a widget's component. */
 export interface BlockComponentProps<
   TData = BlockUnknownData,
   TVariant extends string = string,
 > {
+  /** The instance's own stable id, not the widget's type. */
   blockId: string;
+  /** The stored data: validated when saved, shape-checked before render. Defaults are applied at write time only. */
   data: TData;
+  /** Position among its siblings. */
   index: number;
+  /** The qualified widget id, e.g. `"example:callout"`. */
   type: string;
+  /** The look this instance picked, resolved against the declared variants; `undefined` for a widget with none. */
   variant?: TVariant;
 }
 
@@ -46,18 +54,27 @@ export interface BlockDefinition<
   TFields extends BlockFieldMap = ContentFieldMap,
   TVariant extends string = string,
 > {
+  /** Renders one instance. */
   component: BlockComponent;
+  /** Variant used when an instance stores none. */
   defaultVariant?: TVariant;
+  /** Shown in the Visual Editor's catalogue. */
   description?: string;
+  /** Content Engine fields the data is validated and edited with. */
   fields: TFields;
+  /** Icon component for the editor; a generic widget icon when missing. */
   icon?: BlockIcon;
+  /** Name without a namespace; the registry stores it as `{namespace}:{id}`. */
   id: TId;
+  /** Display name in the editor. */
   name?: string;
+  /** Alternative looks for the same data. */
   variants?: readonly BlockVariantDefinition<TVariant>[];
 }
 
 export type AnyBlockDefinition = BlockDefinition;
 
+/** One stored widget: `{ id, type, data, variant? }`. Create one with `createWidgetInstance`. */
 export interface BlockInstance<
   TType extends string = string,
   TData = BlockUnknownData,
@@ -102,6 +119,7 @@ export interface BlockAreaStoredLayout extends Omit<
   marginY?: AreaStoredSpacing;
 }
 
+/** A layout area grouping widgets in a grid, stored next to widget instances. */
 export interface BlockAreaInstance {
   children: readonly AnyBlockInstance[];
   id: string;
@@ -113,11 +131,26 @@ export type ContentNode = AnyBlockInstance | BlockAreaInstance;
 
 export type BlockAllowedEntry = string;
 
+/**
+ * Which widgets a zone accepts: `"*"` for all, or a list of qualified ids
+ * (`"blog:latest-posts"`) and namespace wildcards (`"blog:*"`).
+ */
 export type BlockAllowedSpec = "*" | readonly BlockAllowedEntry[];
 
+/**
+ * A plugin's widgets, passed to `buildApiPlugin({ blocks })` and collected
+ * into the app's generated registry. Export it from a module of its own so
+ * the API and the browser register the same object.
+ */
 export interface BlockPluginSource {
+  /** The plugin's widget definitions, from `defineWidget`. */
   blocks?: readonly AnyBlockDefinition[];
+  /**
+   * Overrides the id prefix, which defaults to the last segment of `pluginId`
+   * (`@vitnode/blog` -> `blog`). Only needed when two plugins' names end the same.
+   */
   namespace?: string;
+  /** The plugin's id (`manifest.id`); must match the plugin passing it to `buildApiPlugin`. */
   pluginId: string;
 }
 
@@ -128,6 +161,7 @@ export interface RegisteredBlock {
   type: string;
 }
 
+/** Every installed widget by qualified id. Built by `createWidgetRegistry`. */
 export interface BlockRegistry {
   all: () => readonly RegisteredBlock[];
   byNamespace: (namespace: string) => readonly RegisteredBlock[];
@@ -147,6 +181,11 @@ export interface BlockRenderFallbackProps {
   reason: BlockRenderFallbackReason;
 }
 
+/**
+ * Whether rendering enforces a zone's allowlist and logs warnings. A data
+ * shape check and skipping unknown types or variants always apply; full
+ * validation happens on write.
+ */
 export type BlockValidationMode = "always" | "development" | "never";
 
 export type BlockRenderFallback = (
diff --git a/packages/vitnode/src/blocks/variant.ts b/packages/vitnode/src/blocks/variant.ts
index 2849da96b2..a74a06f698 100644
--- a/packages/vitnode/src/blocks/variant.ts
+++ b/packages/vitnode/src/blocks/variant.ts
@@ -23,6 +23,11 @@ export const findBlockVariant = (
 ): AnyBlockVariantDefinition | undefined =>
   blockVariants(definition).find(entry => entry.id === variant);
 
+/**
+ * Resolves an instance's stored variant against a widget definition: no
+ * variant gives the definition's `defaultVariant` (possibly `undefined`), a
+ * declared one is kept, and an undeclared one comes back as `kind: "unknown"`.
+ */
 export const resolveBlockVariant = (
   definition: AnyBlockDefinition,
   variant: string | undefined,
diff --git a/packages/vitnode/src/blocks/zone-meta.ts b/packages/vitnode/src/blocks/zone-meta.ts
index 5774a74901..0fe013d977 100644
--- a/packages/vitnode/src/blocks/zone-meta.ts
+++ b/packages/vitnode/src/blocks/zone-meta.ts
@@ -18,11 +18,21 @@ import {
 import { BlockError } from "./errors";
 import { parseBlockId } from "./namespace";
 
+/**
+ * Whether a value is a usable zone id: `:`-separated segments of lowercase
+ * letters, digits and single hyphens, at most 64 characters (`"main"`,
+ * `"settings:before-profile"`).
+ */
 export const isContentZoneId = (value: unknown): value is string =>
   typeof value === "string" &&
   value.length <= CONTENT_ZONE_ID_MAX_LENGTH &&
   CONTENT_ZONE_ID_PATTERN.test(value);
 
+/**
+ * Returns `id` when it is a usable zone id.
+ *
+ * @throws {BlockError} When it is not (see {@link isContentZoneId}).
+ */
 export const assertContentZoneId = (id: string): string => {
   if (isContentZoneId(id)) return id;
 
@@ -31,6 +41,11 @@ export const assertContentZoneId = (id: string): string => {
   );
 };
 
+/**
+ * Splits a zone id at its last `:` into `scope` and `name` (`"settings:before-profile"`
+ * gives scope `settings`, name `before-profile`; an id without `:` has no
+ * scope). `null` for an invalid id.
+ */
 export const parseContentZoneId = (id: string): null | ParsedContentZoneId => {
   if (!isContentZoneId(id)) return null;
 
@@ -43,6 +58,13 @@ export const parseContentZoneId = (id: string): null | ParsedContentZoneId => {
 export const formatBlockAllowed = (allowed: BlockAllowedSpec): string =>
   allowed === BLOCK_WILDCARD ? BLOCK_WILDCARD : allowed.join(",");
 
+/**
+ * The DOM attributes that mark an element as a zone: `data-vitnode-zone`
+ * with the id, plus `data-vitnode-zone-allowed` (comma-separated, or `*`)
+ * when `allowedBlocks` is given.
+ *
+ * @throws {BlockError} When `id` is not a usable zone id.
+ */
 export const contentZoneAttributes = ({
   allowedBlocks,
   id,
diff --git a/packages/vitnode/src/blocks/zone.tsx b/packages/vitnode/src/blocks/zone.tsx
index 254883645f..b0db5c5c44 100644
--- a/packages/vitnode/src/blocks/zone.tsx
+++ b/packages/vitnode/src/blocks/zone.tsx
@@ -21,18 +21,50 @@ import {
 import { ContentZoneOutlet } from "./zone-outlet";
 
 export interface ContentZoneProps {
+  /** What may be placed here. Under an editable page it may only narrow what the page allows. */
   allowedBlocks?: BlockAllowedSpec;
+  /** HTML element to wrap the widgets in; without `as` or `className` nothing is added. */
   as?: keyof JSX.IntrinsicElements;
+  /**
+   * The instances to render; `null` and `[]` render nothing. Left out under an
+   * `EditablePage`, the page's stored layout for this zone is used.
+   */
   blocks?: null | readonly unknown[];
+  /** Class for the wrapper; implies `as="div"`. */
   className?: string;
+  /** What to render for a widget that is skipped; defaults to a development-only notice. */
   fallback?: BlockRenderFallback;
+  /**
+   * Stable name of this place on the page: `:`-separated segments of
+   * lowercase letters, digits and single hyphens, up to 64 characters, e.g.
+   * `"settings:before-profile"`. Saved layouts address zones by it.
+   */
   id: string;
+  /** Editor bounds on the number of widgets; may only tighten an editable page's own. */
   max?: number;
   min?: number;
+  /** Defaults to the process default registry installed by `src/blocks.gen.ts`. */
   registry?: BlockRegistry;
+  /** Defaults to `"development"`. */
   validate?: BlockValidationMode;
 }
 
+/**
+ * A named place on a page where widgets render. Renders the instances it is
+ * given through `ContentRenderer`, makes no request, and adds no element
+ * unless `as` or `className` is set. In edit mode it registers itself with the
+ * Visual Editor instead.
+ *
+ * @throws {BlockError} On an invalid `id`, or when two zones with one id are
+ * mounted at the same time in edit mode.
+ *
+ * @example
+ * ```tsx
+ * import { ContentZone } from "@vitnode/core/widgets/zone";
+ *
+ * <ContentZone id="main" blocks={page.content} registry={blocksRegistry} />;
+ * ```
+ */
 export const ContentZone = ({
   allowedBlocks,
   as,
diff --git a/packages/vitnode/src/components/ai/use-available-ai-actions.ts b/packages/vitnode/src/components/ai/use-available-ai-actions.ts
index db2b3832a1..9f615816ab 100644
--- a/packages/vitnode/src/components/ai/use-available-ai-actions.ts
+++ b/packages/vitnode/src/components/ai/use-available-ai-actions.ts
@@ -5,6 +5,12 @@ import type { AiAssistScope } from "@/lib/ai/stream-client";
 import { manifest } from "@/manifest";
 import { fetcher } from "@/tanstack/fetcher";
 
+/**
+ * The AI action keys the current user may run, as a TanStack Query result
+ * (`data` is a string array; `[]` on an error response). Use it to hide AI
+ * buttons nobody can use. `scope` picks the endpoint: `admin` (the default)
+ * asks the AdminCP route for staff, `user` the public one. Cached for 5 minutes.
+ */
 export const useAvailableAiActions = (scope: AiAssistScope = "admin") =>
   useQuery({
     queryFn: async () => {
diff --git a/packages/vitnode/src/components/confirm-action/confirm-action-alert-dialog.tsx b/packages/vitnode/src/components/confirm-action/confirm-action-alert-dialog.tsx
index d9a94a48c3..c40b94ee18 100644
--- a/packages/vitnode/src/components/confirm-action/confirm-action-alert-dialog.tsx
+++ b/packages/vitnode/src/components/confirm-action/confirm-action-alert-dialog.tsx
@@ -13,6 +13,27 @@ import {
 } from "../ui/alert-dialog";
 import { ContentConfirmAction } from "./content";
 
+/**
+ * Asks for confirmation before a destructive action, such as a delete. The
+ * `children` element opens it; omit it to control the dialog with `open` and
+ * `onOpenChange`.
+ *
+ * `onSubmit` runs as a form action, with the confirm button spinning until it
+ * settles; call its `onClose` to close the dialog after success. `title` and
+ * `description` default to a generic "Are you sure?" text.
+ *
+ * @example
+ * ```tsx
+ * <ConfirmActionAlertDialog
+ *   onSubmit={async ({ onClose }) => {
+ *     await deletePost(id);
+ *     onClose();
+ *   }}
+ * >
+ *   <Button variant="destructive">Delete</Button>
+ * </ConfirmActionAlertDialog>
+ * ```
+ */
 export const ConfirmActionAlertDialog = ({
   children,
   title,
diff --git a/packages/vitnode/src/components/confirm-action/content.tsx b/packages/vitnode/src/components/confirm-action/content.tsx
index 48b60d1014..2eca01aed4 100644
--- a/packages/vitnode/src/components/confirm-action/content.tsx
+++ b/packages/vitnode/src/components/confirm-action/content.tsx
@@ -13,8 +13,11 @@ export const ContentConfirmAction = ({
   submitVariant = "destructive",
   textSubmit,
 }: {
+  /** Runs on confirm; call `onClose` to close the dialog. */
   onSubmit: (props: { onClose: () => void }) => Promise<void> | void;
+  /** Defaults to `destructive`. */
   submitVariant?: React.ComponentProps<typeof Button>["variant"];
+  /** The confirm button's label. Defaults to a translated "Yes, confirm". */
   textSubmit?: string;
 }) => {
   const t = useTranslations("core.global.confirm_action");
diff --git a/packages/vitnode/src/components/date-format.tsx b/packages/vitnode/src/components/date-format.tsx
index 497707f4f7..c7ff684132 100644
--- a/packages/vitnode/src/components/date-format.tsx
+++ b/packages/vitnode/src/components/date-format.tsx
@@ -2,13 +2,24 @@ import { useFormatter, useNow } from "use-intl";
 
 import { TooltipWithContent } from "./ui/tooltip";
 
+/**
+ * A date in the visitor's language: relative ("5 minutes ago", with the full
+ * date in a tooltip) when it is less than a week old, the full date and time
+ * otherwise. The year is left out for dates in the current year.
+ */
 export const DateFormat = ({
   date,
   updateInterval,
   showFullDate,
 }: {
+  /** A `Date` or anything `new Date()` parses, such as an ISO string from the API. */
   date: Date | string;
+  /** Always shows the full date and time. */
   showFullDate?: boolean;
+  /**
+   * How often a relative date re-renders, in ms. Defaults to every minute for
+   * dates less than a day old and never otherwise.
+   */
   updateInterval?: number;
 }) => {
   const dateToFormat = typeof date === "string" ? new Date(date) : date;
diff --git a/packages/vitnode/src/components/editor-provider.tsx b/packages/vitnode/src/components/editor-provider.tsx
index 6596ea023f..8595b4f358 100644
--- a/packages/vitnode/src/components/editor-provider.tsx
+++ b/packages/vitnode/src/components/editor-provider.tsx
@@ -15,12 +15,15 @@ export interface EditorEmojiSection {
   label: string;
 }
 
+/** Editor settings, from the `editor` option of the app's `buildConfig`. */
 export interface VitNodeEditorConfig {
+  /** Custom emoji sections in the picker. Empty sections are dropped. */
   emojis?: EditorEmojiSection[];
 }
 
 const EditorConfigContext = React.createContext<VitNodeEditorConfig>({});
 
+/** Provides the app's {@link VitNodeEditorConfig} to every editor below it. */
 export const EditorConfigProvider = ({
   children,
   config = {},
@@ -36,5 +39,6 @@ export const EditorConfigProvider = ({
   return <EditorConfigContext value={value}>{children}</EditorConfigContext>;
 };
 
+/** The editor config from the nearest {@link EditorConfigProvider}; `{}` without one. */
 export const useEditorConfig = (): VitNodeEditorConfig =>
   React.use(EditorConfigContext);
diff --git a/packages/vitnode/src/components/form/auto-form-sheet-footer.tsx b/packages/vitnode/src/components/form/auto-form-sheet-footer.tsx
index 00936547fd..e2cd27e683 100644
--- a/packages/vitnode/src/components/form/auto-form-sheet-footer.tsx
+++ b/packages/vitnode/src/components/form/auto-form-sheet-footer.tsx
@@ -5,10 +5,38 @@ import { Button } from "../ui/button";
 import { useFormApi } from "../ui/form";
 import { SheetClose } from "../ui/sheet";
 
+/**
+ * The footer of an `AutoForm` in a `Sheet`: an "unsaved changes" note, Cancel
+ * (closes the sheet) and Submit. Render it from the form's `layout`, below a
+ * scrollable body.
+ *
+ * Submit stays disabled until a value differs from its default, and shows a
+ * spinner while submitting. Closing the sheet after a successful save is the
+ * caller's job.
+ *
+ * @example
+ * ```tsx
+ * <AutoForm
+ *   className="flex min-h-0 flex-1 flex-col gap-0"
+ *   fields={fields}
+ *   formSchema={formSchema}
+ *   onSubmit={onSubmit}
+ *   layout={rendered => (
+ *     <>
+ *       <div className="flex flex-1 flex-col gap-5 overflow-y-auto p-4">
+ *         {rendered.title}
+ *       </div>
+ *       <AutoFormSheetFooter submitLabel="Save" />
+ *     </>
+ *   )}
+ * />
+ * ```
+ */
 export const AutoFormSheetFooter = ({
   disabled = false,
   submitLabel,
 }: {
+  /** Disables Submit even with unsaved changes. Defaults to `false`. */
   disabled?: boolean;
   submitLabel: string;
 }) => {
diff --git a/packages/vitnode/src/components/form/auto-form.tsx b/packages/vitnode/src/components/form/auto-form.tsx
index 08440bafc8..d80958b60a 100644
--- a/packages/vitnode/src/components/form/auto-form.tsx
+++ b/packages/vitnode/src/components/form/auto-form.tsx
@@ -42,17 +42,36 @@ export type { AnyFormFieldApi, FormFieldApi } from "../ui/form";
 export { setFormFieldError } from "../ui/form";
 
 interface ItemAutoFormSharedProps<T extends z.ZodObject<z.ZodRawShape>> {
+  /**
+   * Nested fields, rendered and passed to this field's component as
+   * `children` - e.g. extra inputs inside a group.
+   */
   children?: ItemAutoFormProps<T>[];
+  /** Hides the field while it returns `true`; re-evaluated on every change. */
   hidden?: (values: z.input<T>) => boolean;
+  /** The `value` of the {@link AutoFormTab} the field shows in. Defaults to the first tab. */
   tab?: string;
 }
 
+/**
+ * One entry of `AutoForm`'s `fields`. Either a field rendered by `component`,
+ * or - without a component - a heading with a `label` and `description`.
+ *
+ * Either way, `id` must name a key of `formSchema` (a dotted path for a nested
+ * object, e.g. `seo.title`); an id the schema does not have renders nothing.
+ */
 type ItemAutoFormProps<
   T extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>,
 > = ItemAutoFormSharedProps<T> &
   (
     | {
+        /**
+         * Renders the field, usually one of the `AutoForm*` field components
+         * from `@vitnode/core/components/form/fields/*` with the props spread
+         * in and a `label` added.
+         */
         component: (props: ItemAutoFormComponentProps) => React.ReactNode;
+        /** The schema key the field edits. */
         id: string;
       }
     | {
@@ -63,19 +82,35 @@ type ItemAutoFormProps<
       }
   );
 
+/** One tab of a tabbed `AutoForm`. Fields pick a tab with their `tab`. */
 export interface AutoFormTab {
   label: React.ReactNode;
   value: string;
 }
 
+/**
+ * What `AutoForm` passes to a field's `component`. Spread it into an
+ * `AutoForm*` field component, or build a custom field on `field`.
+ */
 export interface ItemAutoFormComponentProps {
+  /** The rendered nested fields declared in the item's `children`. */
   children?: React.ReactNode;
+  /**
+   * Help text under the field. `AutoForm` fills it from the schema's
+   * description (`.describe()`); a component may override it.
+   */
   description?: React.ReactNode;
+  /** The field's value and change/blur handlers, bound to the form. */
   field: AnyFormFieldApi;
+  /** Constraints of an array field's items, read from the schema. */
   itemParams?: InputParams;
+  /** Not filled by `AutoForm`; pass it to the field component yourself. */
   label?: React.ReactNode;
+  /** Content shown at the right end of the label row. */
   labelRight?: React.ReactNode;
+  /** Edit one value per enabled language. Supported by `AutoFormInput`, `AutoFormTextarea` and `AutoFormEditor`. */
   multiLang?: boolean;
+  /** Constraints read from the field's Zod schema, plus the field's `aria-invalid` state. */
   otherProps: {
     ["aria-invalid"]?: boolean;
     clearsToEmpty?: boolean;
@@ -95,6 +130,10 @@ type AutoFormValidator<T extends z.ZodObject<z.ZodRawShape>> = StandardSchemaV1<
   z.output<T>
 >;
 
+/**
+ * The TanStack Form instance behind an `AutoForm`, as its `onSubmit` receives
+ * it - for `form.reset()`, or {@link setFormFieldError} after an API error.
+ */
 export type AutoFormApi<T extends z.ZodObject<z.ZodRawShape>> = FormApi<
   z.input<T>,
   AutoFormValidator<T>,
@@ -131,6 +170,7 @@ const hiddenIdsOf = <T extends z.ZodObject<z.ZodRawShape>>(
     })
     .join("\n");
 
+/** Renders one field's `component` with its props. Used by `AutoForm` and `AutoFormArray`. */
 export const AutoFormFieldSlot = ({
   component,
   ...props
@@ -175,6 +215,13 @@ type SubmitButtonProps =
       : never
     : never;
 
+/**
+ * A submit button for an `AutoForm` with a custom `layout`, which renders no
+ * button of its own. Shows a spinner while the form submits.
+ *
+ * Several buttons with different `intent` values can share one form: the
+ * clicked button's intent reaches `onSubmit` as `options.intent`.
+ */
 export const AutoFormSubmitButton = ({
   children,
   className,
@@ -203,6 +250,14 @@ export const AutoFormSubmitButton = ({
   );
 };
 
+/**
+ * `AutoForm`'s submit handler. Runs only with values that passed the schema,
+ * already parsed (Zod output, so transforms and defaults are applied).
+ *
+ * `options.captchaToken` is a fresh token when the form has `captcha`, `""`
+ * otherwise; pass it to the fetcher's `captchaToken`. `options.intent` is the
+ * `value` of the submit button that was clicked, if any.
+ */
 export type AutoFormOnSubmit<T extends z.ZodObject<z.ZodRawShape>> = (
   values: z.infer<T>,
   form: AutoFormApi<T>,
@@ -303,6 +358,49 @@ const fieldOtherProps = ({
 
 const emptySubmitMeta: FormSubmitMeta = {};
 
+/**
+ * A form generated from a Zod object schema: validation, default values,
+ * required markers, length limits and error display all come from the schema,
+ * and `fields` only says which component renders each key. The form to use for
+ * any form in VitNode and its plugins.
+ *
+ * - Defaults come from the schema's `.default()` values.
+ * - The schema validates on mount, on change and on submit; `mode` only decides
+ *   when errors become visible. A failed submit reveals every error, switches
+ *   to the first tab with one, focuses it and shakes the invalid fields.
+ * - Inside a `Dialog` it renders a footer with Cancel and Submit, and the dialog
+ *   asks before closing with unsaved changes. Closing or reloading the tab with
+ *   unsaved changes asks too (browser `beforeunload`); in-app navigation is not
+ *   blocked.
+ * - With `layout`, no submit button is rendered: add `AutoFormSubmitButton`, or
+ *   `AutoFormSheetFooter` in a sheet.
+ *
+ * Browser-only interaction, but safe to render during SSR.
+ *
+ * @example
+ * ```tsx
+ * import { AutoForm } from "@vitnode/core/components/form/auto-form";
+ * import { AutoFormInput } from "@vitnode/core/components/form/fields/input";
+ * import { z } from "zod";
+ *
+ * const formSchema = z.object({ title: z.string().min(3).max(100) });
+ *
+ * export const TitleForm = () => (
+ *   <AutoForm
+ *     fields={[
+ *       {
+ *         id: "title",
+ *         component: props => <AutoFormInput {...props} label="Title" />,
+ *       },
+ *     ]}
+ *     formSchema={formSchema}
+ *     onSubmit={async values => {
+ *       // values.title is a string of 3-100 characters
+ *     }}
+ *   />
+ * );
+ * ```
+ */
 export function AutoForm<T extends z.ZodObject<z.ZodRawShape>>({
   formSchema,
   mode,
@@ -316,14 +414,39 @@ export function AutoForm<T extends z.ZodObject<z.ZodRawShape>>({
   children,
   ...props
 }: Omit<React.ComponentProps<"form">, "onSubmit"> & {
+  /**
+   * Passed to TanStack Form. With `true` (the default) every submit re-runs
+   * the schema before deciding; with `false` a submit of a form already known
+   * to be invalid skips straight to revealing the errors. Invalid fields are
+   * revealed and focused either way, and `onSubmit` never runs with invalid
+   * values.
+   */
   canSubmitWhenInvalid?: boolean;
+  /**
+   * The app's captcha config, from the middleware API. When set, the built-in
+   * submit button stays disabled until the captcha loads and `onSubmit` gets a
+   * token.
+   */
   captcha?: z.infer<typeof routeMiddlewareSchema>["captcha"];
+  /** Which component renders each schema key, in display order. */
   fields: ItemAutoFormProps<T>[];
+  /** Validates the values, and supplies defaults and field constraints. */
   formSchema: T;
+  /**
+   * Places the rendered fields yourself; receives them keyed by `id`. Replaces
+   * the tabs and the built-in submit button.
+   */
   layout?: (renderedFields: Record<string, React.ReactNode>) => React.ReactNode;
+  /**
+   * When a field's errors become visible: after blur (`onTouched`, `onBlur`),
+   * after the first change or blur (`onChange`, `all`) or only after a submit
+   * (`onSubmit`). Every error shows after a submit. Defaults to `onTouched`.
+   */
   mode?: FormMode;
   onSubmit?: AutoFormOnSubmit<T>;
+  /** Props of the built-in submit button; `children` replaces its label. */
   submitButtonProps?: SubmitButtonProps;
+  /** Splits the fields into tabs; a tab with an error is marked. */
   tabs?: AutoFormTab[];
 }) {
   const {
diff --git a/packages/vitnode/src/components/form/common/desc.tsx b/packages/vitnode/src/components/form/common/desc.tsx
index bb1a003a20..941ff213b2 100644
--- a/packages/vitnode/src/components/form/common/desc.tsx
+++ b/packages/vitnode/src/components/form/common/desc.tsx
@@ -2,6 +2,11 @@ import { cn } from "cn";
 
 import { useFormDescriptionId } from "../../ui/form";
 
+/**
+ * A form field's help text, wired to the field through
+ * `aria-describedby`. Render it inside a form field, below the control - for
+ * a custom field component the same way built-in fields do.
+ */
 export const AutoFormDesc = ({
   children,
   className,
diff --git a/packages/vitnode/src/components/form/common/label.tsx b/packages/vitnode/src/components/form/common/label.tsx
index 5cbe184467..83803e87b7 100644
--- a/packages/vitnode/src/components/form/common/label.tsx
+++ b/packages/vitnode/src/components/form/common/label.tsx
@@ -4,6 +4,10 @@ import { useTranslations } from "use-intl";
 import { FieldLabel } from "@/components/ui/field";
 import { useFormField } from "@/components/ui/form";
 
+/**
+ * A form field's label, linked to the field's control by id. Render it inside
+ * a form field, above the control, in a custom field component.
+ */
 export const AutoFormLabel = ({
   children,
   labelRight,
@@ -11,7 +15,9 @@ export const AutoFormLabel = ({
   isOptional,
   ...props
 }: React.ComponentProps<typeof FieldLabel> & {
+  /** Appends the translated "optional" hint after the label. */
   isOptional?: boolean;
+  /** Content pushed to the end of the label row, e.g. a language switcher. */
   labelRight?: React.ReactNode;
 }) => {
   const t = useTranslations("core.global");
diff --git a/packages/vitnode/src/components/form/fields/array.tsx b/packages/vitnode/src/components/form/fields/array.tsx
index 8c2e69551c..5e684d5597 100644
--- a/packages/vitnode/src/components/form/fields/array.tsx
+++ b/packages/vitnode/src/components/form/fields/array.tsx
@@ -42,22 +42,34 @@ const reconcileRowKeys = (previous: number[], length: number): number[] => {
   ];
 };
 
+/** One input of every row in an {@link AutoFormArray}. */
 export interface AutoFormArrayField {
   className?: string;
   component: (props: ItemAutoFormComponentProps) => React.ReactNode;
+  /** The key of the row object the input edits. */
   id: string;
 }
 
 export interface AutoFormArrayProps extends ItemAutoFormComponentProps {
+  /** Defaults to "Add Item" (not translated - pass your own). */
   addButtonLabel?: string;
   className?: string;
+  /** The inputs of each row, one per key of the array's item object. */
   fields: AutoFormArrayField[];
   itemParams?: InputParams;
+  /** Overrides the schema's `.max()`; Add is disabled at the limit. */
   maxItems?: number;
+  /** Overrides the schema's `.min()`; Remove buttons are hidden at the limit. */
   minItems?: number;
+  /** Defaults to `true`. */
   showRemoveButton?: boolean;
 }
 
+/**
+ * A repeatable group of inputs for an `AutoForm` field holding an array of
+ * objects (`z.array(z.object(...))`): one row per item, with Add and Remove
+ * buttons. A new row starts with every key `undefined`.
+ */
 export const AutoFormArray = ({
   label,
   field: parentField,
diff --git a/packages/vitnode/src/components/form/fields/cascader.tsx b/packages/vitnode/src/components/form/fields/cascader.tsx
index 9a7c941c82..7290d858a8 100644
--- a/packages/vitnode/src/components/form/fields/cascader.tsx
+++ b/packages/vitnode/src/components/form/fields/cascader.tsx
@@ -7,6 +7,13 @@ import { AutoFormLabel } from "../common/label";
 
 type CascaderProps = React.ComponentProps<typeof Cascader>;
 
+/**
+ * A nested picker for an `AutoForm` string field: the admin drills through
+ * `options` and only a leaf (an option without children) can be chosen. Stores
+ * the leaf's `value`, or `undefined` when cleared; `showClear` defaults to
+ * whether the field is optional. Spread the props `AutoForm` passes and add a
+ * `label` and `options`.
+ */
 export const AutoFormCascader = ({
   label,
   labelRight,
diff --git a/packages/vitnode/src/components/form/fields/checkbox.tsx b/packages/vitnode/src/components/form/fields/checkbox.tsx
index 5dd6aab670..a48e1d99f8 100644
--- a/packages/vitnode/src/components/form/fields/checkbox.tsx
+++ b/packages/vitnode/src/components/form/fields/checkbox.tsx
@@ -7,6 +7,7 @@ import { FormControl, FormMessage } from "../../ui/form";
 import { AutoFormDesc } from "../common/desc";
 import { AutoFormLabel } from "../common/label";
 
+/** A checkbox for an `AutoForm` boolean field. Spread the props `AutoForm` passes and add a `label`. */
 export const AutoFormCheckbox = ({
   label,
   labelRight,
diff --git a/packages/vitnode/src/components/form/fields/color.tsx b/packages/vitnode/src/components/form/fields/color.tsx
index 846d2b3ae4..22060cb1d9 100644
--- a/packages/vitnode/src/components/form/fields/color.tsx
+++ b/packages/vitnode/src/components/form/fields/color.tsx
@@ -8,6 +8,12 @@ import type { ItemAutoFormComponentProps } from "../auto-form";
 import { AutoFormDesc } from "../common/desc";
 import { AutoFormLabel } from "../common/label";
 
+/**
+ * A color picker for an `AutoForm` string field. Stores a CSS color string -
+ * the picker writes `hsl(...)`, presets write their own value, and the text
+ * box accepts anything typed. Spread the props `AutoForm` passes and add a
+ * `label`.
+ */
 export const AutoFormColor = ({
   label,
   labelRight,
diff --git a/packages/vitnode/src/components/form/fields/combobox.tsx b/packages/vitnode/src/components/form/fields/combobox.tsx
index 12208df687..3ca4aa6606 100644
--- a/packages/vitnode/src/components/form/fields/combobox.tsx
+++ b/packages/vitnode/src/components/form/fields/combobox.tsx
@@ -31,6 +31,7 @@ import { AutoFormDesc } from "../common/desc";
 import { AutoFormLabel } from "../common/label";
 import { groupComboboxItems } from "./combobox-groups";
 
+/** One option of an async combobox; the field stores the whole object. */
 export interface ComboboxAsyncItem {
   label: string;
   value: string;
@@ -44,7 +45,9 @@ export const COMBOBOX_INERT_QUERY_KEY = "combobox:no-fetcher";
 type AutoFormComboboxProps = ItemAutoFormComponentProps &
   Omit<React.ComponentProps<typeof Combobox>, "items" | "value"> & {
     className?: string;
+    /** Display labels (and optional groups) for the schema's enum values. */
     labels?: ComboboxOption[];
+    /** With `multiple`, how many selected chips show before the rest collapse. */
     maxVisibleChips?: number;
     placeholder?: string;
     renderChip?: (item: ComboboxAsyncItem) => React.ReactNode;
@@ -52,8 +55,14 @@ type AutoFormComboboxProps = ItemAutoFormComponentProps &
     showClear?: boolean;
   } & (
     | {
+        /**
+         * Loads the options for the typed search (debounced by 500 ms). The
+         * field then stores {@link ComboboxAsyncItem} objects instead of enum
+         * strings.
+         */
         fetchData: ComboboxFetchData;
         id: string;
+        /** The TanStack Query key prefix; the search is appended to it. */
         queryKey: readonly unknown[];
         searchPlaceholder?: string;
       }
@@ -322,6 +331,13 @@ const toComboboxValue = <Value,>(
   return value;
 };
 
+/**
+ * A searchable select for an `AutoForm` field, single or `multiple`.
+ *
+ * Without `fetchData` the options are the schema's enum values, filtered in
+ * the browser. With `fetchData` they are loaded per search through TanStack
+ * Query. Spread the props `AutoForm` passes and add a `label`.
+ */
 export const AutoFormCombobox = ({
   label,
   field,
diff --git a/packages/vitnode/src/components/form/fields/date-picker.tsx b/packages/vitnode/src/components/form/fields/date-picker.tsx
index c4872f89b9..bec47c9c63 100644
--- a/packages/vitnode/src/components/form/fields/date-picker.tsx
+++ b/packages/vitnode/src/components/form/fields/date-picker.tsx
@@ -9,6 +9,11 @@ import type { ItemAutoFormComponentProps } from "../auto-form";
 import { AutoFormDesc } from "../common/desc";
 import { AutoFormLabel } from "../common/label";
 
+/**
+ * A calendar picker for an `AutoForm` date field. Stores a local
+ * `YYYY-MM-DD` string, or `undefined` when cleared. Spread the props
+ * `AutoForm` passes and add a `label`.
+ */
 export const AutoFormDatePicker = ({
   label,
   labelRight,
@@ -26,6 +31,7 @@ export const AutoFormDatePicker = ({
   ...props
 }: ItemAutoFormComponentProps &
   Omit<React.ComponentProps<typeof DatePicker>, "onChange" | "value"> & {
+    /** Called after the form value changes, with the new `YYYY-MM-DD` string, or `undefined` when cleared. */
     onChange?: (value: string | undefined) => void;
   }) => (
   <>
diff --git a/packages/vitnode/src/components/form/fields/date-time.tsx b/packages/vitnode/src/components/form/fields/date-time.tsx
index a2f57a280d..7d3e47fca4 100644
--- a/packages/vitnode/src/components/form/fields/date-time.tsx
+++ b/packages/vitnode/src/components/form/fields/date-time.tsx
@@ -19,6 +19,14 @@ const toInputValue = (value: unknown): string => {
   return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}`;
 };
 
+/**
+ * A native `datetime-local` input for an `AutoForm` date-time field. Shows
+ * the value in the browser's time zone and stores it as an ISO string in UTC;
+ * clearing it stores `null` (`""` when `otherProps.clearsToEmpty` is set, as the Content Engine does for
+ * optional, non-nullable fields). Spread the
+ * props `AutoForm` passes and add a `label`; your own `onChange` and `onBlur`
+ * run after the form value updates.
+ */
 export const AutoFormDateTime = ({
   label,
   labelRight,
@@ -31,6 +39,8 @@ export const AutoFormDateTime = ({
   // oxlint-disable-next-line no-unused-vars
   multiLang,
   otherProps: { clearsToEmpty, isOptional },
+  onBlur,
+  onChange,
   ...props
 }: ItemAutoFormComponentProps &
   Omit<React.ComponentProps<typeof Input>, "type" | "value">) => {
@@ -48,7 +58,7 @@ export const AutoFormDateTime = ({
         <Input
           onBlur={event => {
             field.onBlur();
-            props.onBlur?.(event);
+            onBlur?.(event);
           }}
           onChange={event => {
             const { value } = event.target;
@@ -58,7 +68,7 @@ export const AutoFormDateTime = ({
                 ? date.toISOString()
                 : cleared,
             );
-            props.onChange?.(event);
+            onChange?.(event);
           }}
           type="datetime-local"
           value={toInputValue(field.value)}
diff --git a/packages/vitnode/src/components/form/fields/editor.tsx b/packages/vitnode/src/components/form/fields/editor.tsx
index ff2253df6a..6eac437e4c 100644
--- a/packages/vitnode/src/components/form/fields/editor.tsx
+++ b/packages/vitnode/src/components/form/fields/editor.tsx
@@ -40,7 +40,13 @@ const useEditorLabelledBy = (label: React.ReactNode): string | undefined => {
 
 type AutoFormEditorProps = ItemAutoFormComponentProps &
   TipTapEditorBaseProps & {
+    /**
+     * What the field stores: an HTML string (`html`) or a Tiptap JSON document
+     * (`json`, required for rich text in the Content Engine and for
+     * collaborative editing). Defaults to `html`.
+     */
     format?: "html" | "json";
+    /** Edits one document per enabled language. */
     multiLang?: boolean;
   };
 
@@ -196,6 +202,12 @@ const MultiLangJsonEditor = ({
   );
 };
 
+/**
+ * The rich-text editor (Tiptap) as an `AutoForm` field. Spread the props `AutoForm` passes and add a `label`.
+ *
+ * Inside a collaborative editing context, a `json` field edits the shared
+ * document instead of a local one.
+ */
 export const AutoFormEditor = ({
   label,
   labelRight,
diff --git a/packages/vitnode/src/components/form/fields/emoji-icon.tsx b/packages/vitnode/src/components/form/fields/emoji-icon.tsx
index 032a5b2837..66dfb811df 100644
--- a/packages/vitnode/src/components/form/fields/emoji-icon.tsx
+++ b/packages/vitnode/src/components/form/fields/emoji-icon.tsx
@@ -9,6 +9,11 @@ import type { ItemAutoFormComponentProps } from "../auto-form";
 import { AutoFormDesc } from "../common/desc";
 import { AutoFormLabel } from "../common/label";
 
+/**
+ * An emoji or Lucide icon picker for an `AutoForm` string field. Stores
+ * `emoji:<emoji>` or `icon:<lucide-name>`, or `""` when cleared. Spread the
+ * props `AutoForm` passes and add a `label`.
+ */
 export const AutoFormEmojiIcon = ({
   label,
   labelRight,
diff --git a/packages/vitnode/src/components/form/fields/file-shared.tsx b/packages/vitnode/src/components/form/fields/file-shared.tsx
index bc6317aebe..b4718a8c37 100644
--- a/packages/vitnode/src/components/form/fields/file-shared.tsx
+++ b/packages/vitnode/src/components/form/fields/file-shared.tsx
@@ -28,13 +28,24 @@ import { Spinner } from "@/components/ui/spinner";
 import { fileFormatLabels } from "@/lib/file-constraints";
 import { formatBytes } from "@/lib/format-bytes";
 
+/**
+ * A stored file as a file field shows it - what an upload resolves with and
+ * what `file`/`files` props pass in. The field's own value is only `id`.
+ */
 export interface AutoFormFileValue {
+  /** Image height in pixels, for the preview's layout. */
   height?: number;
+  /** The stored file's id; this becomes the field value. */
   id: number;
+  /** Decides whether the file is previewed as an image (`image/*`). */
   mimeType?: null | string;
+  /** The file name shown to the user. */
   name: string;
+  /** Size in bytes. */
   size: number;
+  /** Where the file can be loaded from; `""` shows no image preview. */
   url: string;
+  /** Image width in pixels, for the preview's layout. */
   width?: number;
 }
 
diff --git a/packages/vitnode/src/components/form/fields/file-upload-queue.ts b/packages/vitnode/src/components/form/fields/file-upload-queue.ts
index b0d7f407a0..d553df5338 100644
--- a/packages/vitnode/src/components/form/fields/file-upload-queue.ts
+++ b/packages/vitnode/src/components/form/fields/file-upload-queue.ts
@@ -11,8 +11,11 @@ import { placeUploadedFile } from "./file-order";
 
 export const FILE_UPLOAD_CONCURRENCY = 6;
 
+/** What a file field passes to your upload function for each file. */
 export interface FileUploadOptions {
+  /** Report upload progress from `0` to `1`; values outside are clamped. */
   onProgress: (fraction: number) => void;
+  /** Aborted when the user cancels the upload; stop the request then. */
   signal: AbortSignal;
 }
 
diff --git a/packages/vitnode/src/components/form/fields/file.tsx b/packages/vitnode/src/components/form/fields/file.tsx
index 02795794c5..6345149a38 100644
--- a/packages/vitnode/src/components/form/fields/file.tsx
+++ b/packages/vitnode/src/components/form/fields/file.tsx
@@ -37,11 +37,19 @@ export type { AutoFormFileValue } from "./file-shared";
 export type { FileUploadOptions } from "./file-upload-queue";
 
 export interface AutoFormFileProps extends ItemAutoFormComponentProps {
+  /** Files with other extensions are rejected before upload. */
   allowedExtensions?: readonly string[];
+  /** Files with other MIME types are rejected before upload. */
   allowedMimeTypes?: readonly string[];
+  /** The stored file the field's initial id points at, so it can be shown. */
   file?: AutoFormFileValue | null;
   label?: React.ReactNode;
+  /** The largest accepted file, in bytes. */
   maxBytes: number;
+  /**
+   * Uploads a picked file and resolves with the stored file; its `id` becomes
+   * the field value. Report progress and honour `signal` to support cancel.
+   */
   onUpload: (
     file: File,
     options: FileUploadOptions,
@@ -169,6 +177,11 @@ const useFileUpload = ({
   };
 };
 
+/**
+ * A single-file upload for an `AutoForm` field that stores a file id (or
+ * `null` after removal). The file is uploaded as soon as it is picked, through
+ * `onUpload`; the form only ever holds the id.
+ */
 export const AutoFormFile = ({
   allowedExtensions,
   allowedMimeTypes,
diff --git a/packages/vitnode/src/components/form/fields/files.tsx b/packages/vitnode/src/components/form/fields/files.tsx
index 525343ff24..0d7112e594 100644
--- a/packages/vitnode/src/components/form/fields/files.tsx
+++ b/packages/vitnode/src/components/form/fields/files.tsx
@@ -35,18 +35,27 @@ import {
 export interface AutoFormFilesProps extends ItemAutoFormComponentProps {
   allowedExtensions?: readonly string[];
   allowedMimeTypes?: readonly string[];
+  /** The stored files the field's initial ids point at, so they can be shown. */
   files?: AutoFormFileValue[];
   label?: React.ReactNode;
+  /** The largest accepted file, in bytes. */
   maxBytes: number;
   maxItems: number;
+  /** Defaults to `0`. */
   minItems?: number;
+  /** Uploads one picked file and resolves with the stored file. Up to six run at once. */
   onUpload: (
     file: File,
     options: FileUploadOptions,
   ) => Promise<AutoFormFileValue>;
+  /** Lets the user reorder the files; the order is kept in the value. Defaults to `true`. */
   ordered?: boolean;
 }
 
+/**
+ * A multi-file upload for an `AutoForm` field that stores an array of file
+ * ids. Picked files upload right away through `onUpload`.
+ */
 export const AutoFormFiles = ({
   allowedExtensions,
   allowedMimeTypes,
diff --git a/packages/vitnode/src/components/form/fields/input-otp.tsx b/packages/vitnode/src/components/form/fields/input-otp.tsx
index 41bf882d8f..8ebca9869a 100644
--- a/packages/vitnode/src/components/form/fields/input-otp.tsx
+++ b/packages/vitnode/src/components/form/fields/input-otp.tsx
@@ -22,11 +22,22 @@ type AutoFormInputOTPProps = ItemAutoFormComponentProps &
     React.ComponentProps<typeof InputOTP>,
     "children" | "maxLength" | "onChange" | "render" | "value"
   > & {
+    /**
+     * Slot counts per group, separated visually, e.g. `[3, 3]`. Defaults to
+     * two equal halves for an even length of 6 or more, else one group.
+     */
     groups?: number[];
+    /** Number of slots. Defaults to the schema's max length, else 6. */
     maxLength?: number;
+    /** Called after the form value changes. */
     onChange?: (value: string) => void;
   };
 
+/**
+ * A one-time-code input for an `AutoForm` string field: one box per
+ * character. `pattern` defaults to the schema's regex. Spread the props
+ * `AutoForm` passes and add a `label`.
+ */
 export const AutoFormInputOTP = ({
   label,
   labelRight,
diff --git a/packages/vitnode/src/components/form/fields/input-roles.tsx b/packages/vitnode/src/components/form/fields/input-roles.tsx
index 33e5080534..4307f96528 100644
--- a/packages/vitnode/src/components/form/fields/input-roles.tsx
+++ b/packages/vitnode/src/components/form/fields/input-roles.tsx
@@ -39,15 +39,24 @@ const RoleLabel = ({
 /** What the role field takes. `search` is the whole of its host coupling. */
 export type AutoFormRolesProps = ItemAutoFormComponentProps & {
   disabled?: boolean;
+  /** Roles that cannot be picked, by id. */
   excludeIds?: number[];
+  /** Stores an array of role ids instead of one id. Defaults to `false`. */
   multiple?: boolean;
   placeholder?: string;
 
+  /** Finds roles for the typed text. */
   search: RoleSearch;
   searchPlaceholder?: string;
+  /** The roles the field's initial ids belong to, so they show names before any search. */
   selected?: RoleOption[];
 };
 
+/**
+ * A role picker for an `AutoForm` field that stores a role id (or `null`), or
+ * an array of ids with `multiple`. Spread the props `AutoForm` passes and add a
+ * `label`.
+ */
 export const AutoFormRoles = ({
   description,
   disabled,
diff --git a/packages/vitnode/src/components/form/fields/input-users.tsx b/packages/vitnode/src/components/form/fields/input-users.tsx
index ea2aa601ba..8d09b08495 100644
--- a/packages/vitnode/src/components/form/fields/input-users.tsx
+++ b/packages/vitnode/src/components/form/fields/input-users.tsx
@@ -92,6 +92,10 @@ export const UserOptionRow = ({
   </div>
 );
 
+/**
+ * A user picker for an `AutoForm` field that stores a user id (or `null`).
+ * Spread the props `AutoForm` passes and add a `label`.
+ */
 export const AutoFormUser = ({
   clearable = false,
   description,
@@ -111,12 +115,15 @@ export const AutoFormUser = ({
   selected,
 }: ItemAutoFormComponentProps & {
   className?: string;
+  /** Adds a button that sets the field back to `null`. */
   clearable?: boolean;
   disabled?: boolean;
   placeholder?: string;
 
+  /** Finds users for the typed text. */
   search: (value: string) => Promise<UserOption[]>;
   searchPlaceholder?: string;
+  /** The user the field's initial id belongs to, so it shows a name before any search. */
   selected?: null | PartialUserOption;
 }) => {
   const t = useTranslations("core.global");
diff --git a/packages/vitnode/src/components/form/fields/input.tsx b/packages/vitnode/src/components/form/fields/input.tsx
index 23a1ca5afb..05b30b43e0 100644
--- a/packages/vitnode/src/components/form/fields/input.tsx
+++ b/packages/vitnode/src/components/form/fields/input.tsx
@@ -83,6 +83,15 @@ const MultiLangInput = ({
   );
 };
 
+/**
+ * A single-line text input for an `AutoForm` string field. Length limits and
+ * `pattern` come from the schema; `type` comes from the schema (`email`
+ * format) or the key name (`password`). Other input props pass through.
+ * Spread the props `AutoForm` passes and add a `label`.
+ *
+ * With `multiLang`, edits one value per enabled language. Pass `children` to
+ * render them as addons inside an input group.
+ */
 export const AutoFormInput = ({
   label,
   labelRight,
diff --git a/packages/vitnode/src/components/form/fields/multi-lang-default-language.ts b/packages/vitnode/src/components/form/fields/multi-lang-default-language.ts
index 4e9bb97658..e9810f0106 100644
--- a/packages/vitnode/src/components/form/fields/multi-lang-default-language.ts
+++ b/packages/vitnode/src/components/form/fields/multi-lang-default-language.ts
@@ -1,8 +1,14 @@
 import React from "react";
 
+/**
+ * The language a multi-language field falls back to when picking which
+ * language to show first. The Content Engine form provides the content type's
+ * `defaultLocale`.
+ */
 export const MultiLangDefaultLanguageContext = React.createContext<
   null | string
 >(null);
 
+/** The language from {@link MultiLangDefaultLanguageContext}, or `null`. */
 export const useMultiLangDefaultLanguage = (): null | string =>
   React.use(MultiLangDefaultLanguageContext);
diff --git a/packages/vitnode/src/components/form/fields/multi-lang-language.ts b/packages/vitnode/src/components/form/fields/multi-lang-language.ts
index da97870e66..e0ad9138de 100644
--- a/packages/vitnode/src/components/form/fields/multi-lang-language.ts
+++ b/packages/vitnode/src/components/form/fields/multi-lang-language.ts
@@ -1,15 +1,27 @@
 import React from "react";
 
+/**
+ * Pins every multi-language field below it to one language and hides their
+ * language switchers - e.g. a side-by-side translation view rendering the
+ * source and target languages separately.
+ */
 export const MultiLangLanguageContext = React.createContext<null | string>(
   null,
 );
 
+/** The pinned language from {@link MultiLangLanguageContext}, or `null`. */
 export const useMultiLangLanguage = (): null | string =>
   React.use(MultiLangLanguageContext);
 
+/**
+ * The language a multi-language field is showing, provided to its label's
+ * `labelRight` content and to a multi-language editor's body (e.g. AI assist
+ * acting on that language).
+ */
 export const MultiLangSelectedContext = React.createContext<null | string>(
   null,
 );
 
+/** The language from {@link MultiLangSelectedContext}, or `null` outside a multi-language field. */
 export const useMultiLangSelected = (): null | string =>
   React.use(MultiLangSelectedContext);
diff --git a/packages/vitnode/src/components/form/fields/multi-lang-presence.ts b/packages/vitnode/src/components/form/fields/multi-lang-presence.ts
index 8efd6ed268..8b790b7e16 100644
--- a/packages/vitnode/src/components/form/fields/multi-lang-presence.ts
+++ b/packages/vitnode/src/components/form/fields/multi-lang-presence.ts
@@ -1,13 +1,18 @@
 import React from "react";
 
+/** Who else is editing which language of a field, for its language switcher. */
 export interface MultiLangPresence {
+  /** Whether someone else is editing this language; marks the switcher. */
   busy: (code: string) => boolean;
+  /** Rendered next to each language in the switcher's list. */
   marker: (code: string) => React.ReactNode;
 }
 
+/** Provided by Content Engine live editing; `null` elsewhere. */
 export const MultiLangPresenceContext =
   React.createContext<MultiLangPresence | null>(null);
 
+/** Receives the language a multi-language field is showing, whenever it changes. */
 export const MultiLangShownLanguageContext = React.createContext<
   ((code: string) => void) | null
 >(null);
diff --git a/packages/vitnode/src/components/form/fields/multi-lang.tsx b/packages/vitnode/src/components/form/fields/multi-lang.tsx
index 6bb1c7a1c4..5ac08312bd 100644
--- a/packages/vitnode/src/components/form/fields/multi-lang.tsx
+++ b/packages/vitnode/src/components/form/fields/multi-lang.tsx
@@ -38,6 +38,7 @@ export type {
   MultiLangValueItem,
 } from "@/lib/helpers/multi-lang";
 
+/** A form field holding one value per language. */
 export interface MultiLangFieldProps {
   field: FormFieldApi<MultiLangValue | undefined>;
 }
@@ -72,6 +73,16 @@ const useMultiLangSelection = (
   };
 };
 
+/**
+ * Drives a custom multi-language text field: which language is shown, its
+ * text, and a setter that updates only that language's entry.
+ *
+ * It first shows the first language that already has text (`isFilled`,
+ * default: not blank), checking the UI locale, then the default language, then
+ * the rest; with none filled, the UI locale (or the first language). A pinned
+ * `MultiLangLanguageContext` language always wins. `canSelect` is `false` when
+ * pinned or when there is only one language.
+ */
 export const useMultiLangField = (
   field: MultiLangFieldProps["field"],
   { isFilled = hasText }: { isFilled?: (text: string) => boolean } = {},
@@ -95,6 +106,10 @@ export const useMultiLangField = (
   };
 };
 
+/**
+ * {@link useMultiLangField} for non-string values (e.g. a rich-text document):
+ * `isFilled` decides which languages count as having a value.
+ */
 export const useMultiLangValueField = <TValue,>(
   field: FormFieldApi<MultiLangValue<TValue> | undefined>,
   { isFilled }: { isFilled: (value: TValue | undefined) => boolean },
@@ -118,6 +133,7 @@ export const useMultiLangValueField = <TValue,>(
   };
 };
 
+/** The compact language switcher shown in a multi-language field's label row. */
 export const MultiLangSelect = ({
   languages,
   onSelect,
@@ -166,6 +182,10 @@ export const MultiLangSelect = ({
   );
 };
 
+/**
+ * A multi-language field's label row: the label, plus the language switcher
+ * when `canSelect`. Renders nothing without either.
+ */
 export const MultiLangLabel = ({
   canSelect,
   isOptional,
diff --git a/packages/vitnode/src/components/form/fields/nullable-number.tsx b/packages/vitnode/src/components/form/fields/nullable-number.tsx
index e83829fbec..b7edfebb9f 100644
--- a/packages/vitnode/src/components/form/fields/nullable-number.tsx
+++ b/packages/vitnode/src/components/form/fields/nullable-number.tsx
@@ -21,14 +21,21 @@ type AutoFormNullableNumberProps = ItemAutoFormComponentProps &
     React.ComponentProps<typeof NumberField>,
     "children" | "defaultValue" | "id" | "name" | "onValueChange" | "value"
   > & {
+    /** Text between the input and the toggle, e.g. "or". */
     orLabel?: React.ReactNode;
     placeholder?: string;
     /** The number restored when the toggle is unchecked before anything was typed. */
     resumeValue?: number;
+    /** The checkbox that sets the value to `null`, e.g. "Unlimited". */
     toggleLabel: React.ReactNode;
+    /** Shown after the input, e.g. `MB` or `days`. */
     unitLabel?: React.ReactNode;
   };
 
+/**
+ * A number input with a checkbox that stores `null` instead - for a limit that
+ * can be switched off. Use with a `z.number().nullable()` field. Spread the props `AutoForm` passes and add a `label`.
+ */
 export const AutoFormNullableNumber = ({
   label,
   labelRight,
diff --git a/packages/vitnode/src/components/form/fields/number.tsx b/packages/vitnode/src/components/form/fields/number.tsx
index 26eefa2ecf..69e9274e72 100644
--- a/packages/vitnode/src/components/form/fields/number.tsx
+++ b/packages/vitnode/src/components/form/fields/number.tsx
@@ -21,9 +21,11 @@ type AutoFormNumberProps = ItemAutoFormComponentProps &
     "children" | "defaultValue" | "id" | "name" | "onValueChange" | "value"
   > & {
     placeholder?: string;
+    /** Shown after the input, e.g. `MB` or `days`. */
     unitLabel?: React.ReactNode;
   };
 
+/** A number input with steppers for an `AutoForm` number field. Spread the props `AutoForm` passes and add a `label`. */
 export const AutoFormNumber = ({
   className,
   description,
diff --git a/packages/vitnode/src/components/form/fields/radio-group.tsx b/packages/vitnode/src/components/form/fields/radio-group.tsx
index a8c1f8ae8e..5a7211ac48 100644
--- a/packages/vitnode/src/components/form/fields/radio-group.tsx
+++ b/packages/vitnode/src/components/form/fields/radio-group.tsx
@@ -22,6 +22,7 @@ interface ItemAutoFormRadioGroupLabelsProps {
   value: string;
 }
 
+/** Radio buttons for an `AutoForm` enum field, one per enum value. Spread the props `AutoForm` passes and add a `label`. */
 export const AutoFormRadioGroup = ({
   label,
   labelRight,
@@ -39,7 +40,9 @@ export const AutoFormRadioGroup = ({
   ...props
 }: ItemAutoFormComponentProps &
   Omit<React.ComponentProps<typeof RadioGroup>, "value"> & {
+    /** Labels, descriptions and disabled flags for the enum values. */
     labels?: ItemAutoFormRadioGroupLabelsProps[];
+    /** `blocks` renders each option as a selectable card. Defaults to `default`. */
     variant?: "blocks" | "default";
   }) => {
   const values: ItemAutoFormRadioGroupLabelsProps[] = enumValues.map(value => {
diff --git a/packages/vitnode/src/components/form/fields/roles.ts b/packages/vitnode/src/components/form/fields/roles.ts
index 319b9ad1cb..16dcd0df23 100644
--- a/packages/vitnode/src/components/form/fields/roles.ts
+++ b/packages/vitnode/src/components/form/fields/roles.ts
@@ -1,11 +1,15 @@
+/** A role as the roles picker lists it. */
 export interface RoleOption {
+  /** The role's color, or `null` for none. */
   color: null | string;
   id: number;
+  /** The role's name in each language it was given. */
   name: { languageCode: string; name: string }[];
 }
 
 export type RoleSearch = (search: string) => Promise<RoleOption[]>;
 
+/** A role's name in `locale`, else its first name, else its id as text. */
 export const roleOptionName = (role: RoleOption, locale: string): string =>
   role.name.find(item => item.languageCode === locale)?.name ??
   role.name[0]?.name ??
diff --git a/packages/vitnode/src/components/form/fields/select.tsx b/packages/vitnode/src/components/form/fields/select.tsx
index dd69c7d3df..d9f85114fe 100644
--- a/packages/vitnode/src/components/form/fields/select.tsx
+++ b/packages/vitnode/src/components/form/fields/select.tsx
@@ -16,6 +16,10 @@ import type { ItemAutoFormComponentProps } from "../auto-form";
 import { AutoFormDesc } from "../common/desc";
 import { AutoFormLabel } from "../common/label";
 
+/**
+ * A dropdown for an `AutoForm` enum field: the options are the schema's
+ * `z.enum()` values. Spread the props `AutoForm` passes and add a `label`.
+ */
 export const AutoFormSelect = ({
   label,
   field,
@@ -33,6 +37,7 @@ export const AutoFormSelect = ({
   ...props
 }: ItemAutoFormComponentProps &
   Omit<React.ComponentProps<typeof Select>, "value"> & {
+    /** Display labels for the enum values; a value without one shows as is. */
     labels?: { label: string; value: string }[];
     placeholder?: string;
   }) => {
diff --git a/packages/vitnode/src/components/form/fields/switch.tsx b/packages/vitnode/src/components/form/fields/switch.tsx
index d19ab6829a..c69d1045ef 100644
--- a/packages/vitnode/src/components/form/fields/switch.tsx
+++ b/packages/vitnode/src/components/form/fields/switch.tsx
@@ -16,6 +16,7 @@ import { AutoFormLabel } from "../common/label";
 
 const FIELDS_PANEL = "fields";
 
+/** A switch for an `AutoForm` boolean field. Spread the props `AutoForm` passes and add a `label`. */
 export const AutoFormSwitch = ({
   label,
   field,
diff --git a/packages/vitnode/src/components/form/fields/textarea.tsx b/packages/vitnode/src/components/form/fields/textarea.tsx
index 377a62227c..79bd997740 100644
--- a/packages/vitnode/src/components/form/fields/textarea.tsx
+++ b/packages/vitnode/src/components/form/fields/textarea.tsx
@@ -82,6 +82,10 @@ const MultiLangTextarea = ({
   );
 };
 
+/**
+ * A multi-line text input for an `AutoForm` string field, with the schema's
+ * length limits. Supports `multiLang`. Spread the props `AutoForm` passes and add a `label`.
+ */
 export const AutoFormTextarea = ({
   label,
   description,
diff --git a/packages/vitnode/src/components/logo-context.tsx b/packages/vitnode/src/components/logo-context.tsx
index 207df7daba..4b0f8d2fcd 100644
--- a/packages/vitnode/src/components/logo-context.tsx
+++ b/packages/vitnode/src/components/logo-context.tsx
@@ -2,6 +2,7 @@ import React from "react";
 
 import { LogoVitNodeBrand } from "./logo-vitnode";
 
+/** A component that renders the site logo, the frontend config's `logo`. Takes no props. */
 export type VitNodeLogo = React.ComponentType;
 
 export const LogoContext = React.createContext<React.ReactNode>(
diff --git a/packages/vitnode/src/components/logo-vitnode.tsx b/packages/vitnode/src/components/logo-vitnode.tsx
index c8c229cb36..c951a0f699 100644
--- a/packages/vitnode/src/components/logo-vitnode.tsx
+++ b/packages/vitnode/src/components/logo-vitnode.tsx
@@ -107,6 +107,7 @@ export const LogoVitNode = ({
   );
 };
 
+/** The VitNode logo at brand size - the default for `logo` in the frontend config. */
 export const LogoVitNodeBrand = () => (
   <LogoVitNode className="w-34" idPrefix="vitnode-brand" />
 );
diff --git a/packages/vitnode/src/components/pet/pet.tsx b/packages/vitnode/src/components/pet/pet.tsx
index 5b441f98c5..577a658ff6 100644
--- a/packages/vitnode/src/components/pet/pet.tsx
+++ b/packages/vitnode/src/components/pet/pet.tsx
@@ -7,13 +7,19 @@ export type { PetState } from "./states";
 
 export const PET_STATE_NAMES = Object.keys(PET_STATES) as PetState[];
 
+/**
+ * VitNode's animated mascot as an inline SVG. Its CSS is injected once per
+ * page. Decorative (hidden from screen readers) unless you pass `label`.
+ */
 export const Pet = ({
   className,
   label,
   state = "idle",
 }: {
   className?: string;
+  /** Accessible name; without it the SVG is `aria-hidden`. */
   label?: string;
+  /** Which animation to play, one of {@link PET_STATE_NAMES}. Defaults to `idle`. */
   state?: PetState;
 }) => {
   const State = PET_STATES[state];
diff --git a/packages/vitnode/src/components/rich-text/rich-text-content.tsx b/packages/vitnode/src/components/rich-text/rich-text-content.tsx
index 655043c83a..324d8ab8c7 100644
--- a/packages/vitnode/src/components/rich-text/rich-text-content.tsx
+++ b/packages/vitnode/src/components/rich-text/rich-text-content.tsx
@@ -36,8 +36,11 @@ export type RichTextMarkRenderer = (
 
 export interface RichTextContentProps {
   className?: string;
+  /** The document to render. Nothing renders for `null` or `undefined`. */
   content: null | RichTextDocument | undefined;
+  /** Custom renderers by mark type (e.g. `link`), replacing the built-in element. */
   marks?: Readonly<Record<string, RichTextMarkRenderer>>;
+  /** Custom renderers by node type (e.g. `image`), receiving the rendered children. */
   nodes?: Readonly<Record<string, RichTextNodeRenderer>>;
 }
 
@@ -138,6 +141,12 @@ const renderNode = (
   );
 };
 
+/**
+ * Renders a stored rich-text document as React elements, without an editor
+ * and without `dangerouslySetInnerHTML`. Built-in nodes and marks map to
+ * sanitised HTML elements; unknown ones render only their children unless
+ * `nodes` or `marks` supplies a renderer. Universal - works in SSR.
+ */
 export const RichTextContent = ({
   className,
   content,
diff --git a/packages/vitnode/src/components/role-format-content.tsx b/packages/vitnode/src/components/role-format-content.tsx
index 6dca671ccc..970ef99183 100644
--- a/packages/vitnode/src/components/role-format-content.tsx
+++ b/packages/vitnode/src/components/role-format-content.tsx
@@ -8,6 +8,11 @@ import type { RoleNameEntry } from "./role-name";
 import { resolveRoleName } from "./role-name";
 import { EmojiIcon } from "./ui/emoji-icon";
 
+/**
+ * A role's name in the current language (else its first name, else its id),
+ * in the role's color, after its emoji or icon prefix. Extra props go to the
+ * outer `<span>`.
+ */
 export const RoleFormatContent = ({
   className,
   role,
diff --git a/packages/vitnode/src/components/staff-permission/provider.tsx b/packages/vitnode/src/components/staff-permission/provider.tsx
index b92cefe117..a26b61982e 100644
--- a/packages/vitnode/src/components/staff-permission/provider.tsx
+++ b/packages/vitnode/src/components/staff-permission/provider.tsx
@@ -31,6 +31,10 @@ const isPending = (
 ): value is Promise<StaffPermissionSet> =>
   typeof (value as Partial<Promise<StaffPermissionSet>>).then === "function";
 
+/**
+ * The current admin's staff permission set from the AdminCP layout. Suspends
+ * while it loads. For hiding UI only - the API enforces permissions itself.
+ */
 export const useAdminStaffPermissions = (): StaffPermissionSet => {
   const value = React.use(AdminStaffPermissionContext);
 
@@ -61,6 +65,18 @@ const AdminStaffPermissionGateResolved = ({
   return <>{allowed ? children : fallback}</>;
 };
 
+/**
+ * Renders `children` only when the current admin holds the permission,
+ * otherwise `fallback` (also shown while permissions load). UI only - guard
+ * the matching API route with `adminStaffPermission` as well.
+ *
+ * @example
+ * ```tsx
+ * <AdminStaffPermissionGate plugin="@vitnode/blog" module="posts" permission="can_delete">
+ *   <DeletePostButton />
+ * </AdminStaffPermissionGate>
+ * ```
+ */
 export const AdminStaffPermissionGate = ({
   children,
   fallback = null,
diff --git a/packages/vitnode/src/components/table/content.tsx b/packages/vitnode/src/components/table/content.tsx
index ee3d27d95c..ba3ec28aea 100644
--- a/packages/vitnode/src/components/table/content.tsx
+++ b/packages/vitnode/src/components/table/content.tsx
@@ -131,6 +131,15 @@ const ReorderableBodyDataTable = React.lazy(async () =>
   })),
 );
 
+/**
+ * A server-paginated data table driven by the URL: sorting, cursor paging,
+ * search and filters are read from and written to the query string through
+ * the enclosing `DataTableNavigationProvider`, so the route's loader fetches
+ * each page. Optional row selection with bulk actions, expandable and
+ * reorderable rows, and grouping.
+ *
+ * Pass the API's `edges` and `pageInfo` for the current page.
+ */
 export function ContentDataTable<T extends DataTableTMin>({
   bulkActions,
   columns = [],
diff --git a/packages/vitnode/src/components/table/data-table-content.tsx b/packages/vitnode/src/components/table/data-table-content.tsx
index d989fb0641..1e0fb6da9f 100644
--- a/packages/vitnode/src/components/table/data-table-content.tsx
+++ b/packages/vitnode/src/components/table/data-table-content.tsx
@@ -36,12 +36,14 @@ export type AlignDataTable = "center" | "left" | "right";
 
 interface ColumnDefBase<T extends DataTableTMin> {
   align?: AlignDataTable;
+  /** Renders the cell. Defaults to the `accessorKey` value. */
   cell?: (data: { allData: T[]; row: T }) => React.ReactNode;
   className?: string;
   header: React.ReactNode;
 }
 
 interface AccessorColumnDef<T extends DataTableTMin> extends ColumnDefBase<T> {
+  /** The row key the column shows, and sorts by when listed in `order.columns`. */
   accessorKey: keyof T;
   id?: string;
 }
@@ -51,46 +53,63 @@ interface DisplayColumnDef<T extends DataTableTMin> extends ColumnDefBase<T> {
   id: string;
 }
 
+/** One column of a `ContentDataTable`: bound to a row key, or a display column with its own `id`. */
 export type ColumnDef<T extends DataTableTMin> =
   | AccessorColumnDef<T>
   | DisplayColumnDef<T>;
 
+/** What `ContentDataTable` accepts. */
 export type DataTableProps<T extends DataTableTMin> = Omit<
   React.ComponentProps<typeof Table>,
   "columns"
 > &
   React.ComponentProps<typeof PaginationDataTable> &
   React.ComponentProps<typeof SearchDataTable> & {
+    /** Adds a checkbox per row and shows these actions while rows are selected. */
     bulkActions?: React.ReactNode;
     columns?: ColumnDef<T>[];
+    /** Replaces the default empty state. */
     customNoResults?: {
       description?: string;
       footer?: React.ReactNode;
       icon?: React.ReactNode;
       title?: string;
     };
+    /** The rows of the current page. */
     edges: T[];
     expandable?: ExpandableDataTable<T>;
+    /** Faceted filters in the toolbar, kept in the URL. */
     filters?: FilterDataTable[];
     groupBy?: GroupByDataTable<T>;
+    /** A band above the table, e.g. a count or an action button. */
     header?: React.ReactNode;
     id: string;
     order: {
+      /** The columns a header click sorts by. */
       columns?: (keyof T)[];
+      /** The sort used while the URL names none. */
       defaultOrder: {
         column: keyof T;
         order: "asc" | "desc";
       };
     };
+    /** Renders each row as one full-width cell instead of `columns`. */
     renderRow?: (data: { allData: T[]; row: T }) => React.ReactNode;
+    /** Lets rows be dragged into a new order. */
     reorderable?: ReorderableDataTable<T>;
+    /**
+     * Makes a whole row clickable (and Enter/Space-activatable); clicks on
+     * controls inside it are ignored. Ignored when `bulkActions` is set.
+     */
     rowOpens?: (row: T) => void;
+    /** Shows a search box in the toolbar, kept in the URL. */
     search?: boolean;
   };
 
 const SKELETON_HEAD_WIDTHS = ["w-24", "w-16", "w-20", "w-14"];
 const SKELETON_CELL_WIDTHS = ["w-full", "w-3/4", "w-1/2", "w-5/6", "w-2/3"];
 
+/** A loading placeholder shaped like a `ContentDataTable`, for `Suspense` fallbacks. */
 export const DataTableSkeleton = ({
   columns,
   header = false,
diff --git a/packages/vitnode/src/components/table/expansion.tsx b/packages/vitnode/src/components/table/expansion.tsx
index 5cfae78edb..030209bb07 100644
--- a/packages/vitnode/src/components/table/expansion.tsx
+++ b/packages/vitnode/src/components/table/expansion.tsx
@@ -11,12 +11,20 @@ import { MotionFeatures } from "../motion-features";
 import { Button } from "../ui/button";
 import { TableCell, TableRow } from "../ui/table";
 
+/**
+ * Expandable rows: each row gets a toggle that opens a full-width panel below
+ * it. Rows that leave the page are collapsed.
+ */
 export interface ExpandableDataTable<T> {
+  /** Whether a row gets a toggle. Defaults to every row. */
   canExpand?: (row: T) => boolean;
+  /** Row ids open on first render. */
   defaultExpanded?: DataTableRowId[];
+  /** The panel's content, rendered only while the row is open. */
   render: (row: T) => React.ReactNode;
 }
 
+/** Which rows are open. Ids no longer on the page are dropped when it changes. */
 export const useRowExpansionDataTable = ({
   defaultExpanded,
   rowIds,
@@ -56,12 +64,14 @@ export const useRowExpansionDataTable = ({
   return { isExpanded, toggle };
 };
 
+/** The toggle column's header: a screen-reader-only label. */
 export function ExpandHeaderDataTable() {
   const t = useTranslations("core.global.data_table");
 
   return <span className="sr-only">{t("row_details")}</span>;
 }
 
+/** A row's open/close button, linked to its panel through `aria-controls`. */
 export function ExpandToggleDataTable({
   controls,
   expanded,
@@ -94,6 +104,7 @@ export function ExpandToggleDataTable({
   );
 }
 
+/** The full-width row holding an open panel; `id` is what the toggle controls. */
 export function ExpandedRowDataTable({
   children,
   colSpan,
diff --git a/packages/vitnode/src/components/table/filters.tsx b/packages/vitnode/src/components/table/filters.tsx
index c78f53ace1..a1df1f524e 100644
--- a/packages/vitnode/src/components/table/filters.tsx
+++ b/packages/vitnode/src/components/table/filters.tsx
@@ -21,20 +21,41 @@ import { Spinner } from "../ui/spinner";
 import { useDataTableUrl } from "./navigation";
 import { readTableFilter, withTableFilter } from "./url-state";
 
+/** One choice in a faceted filter. */
 export interface FilterOption {
+  /** Extra words the filter's search box matches, for static `options` only. */
   keywords?: string[];
+  /** What the option shows in the filter list. */
   label: React.ReactNode;
+  /** Written to the URL; matched by the search box for static `options`. */
   value: string;
 }
 
+/**
+ * A faceted filter in a data table's toolbar. The selection lives in the URL
+ * as `?{id}=a,b`, so the page's query reads it from there; changing it returns
+ * the table to the first page.
+ */
 export interface FilterDataTable {
+  /** The URL parameter the selected values are written to, comma-separated. */
   id: string;
+  /** The button's text and the search box's placeholder. */
   label: string;
+  /**
+   * Loads options from the server instead of `options`: called with `""` when
+   * the popover opens, then with the typed text after a 400 ms pause.
+   */
   onSearch?: (search: string) => Promise<FilterOption[]>;
+  /** A fixed list of choices, searched in the browser. Ignored with `onSearch`. */
   options?: FilterOption[];
+  /**
+   * Allows one value at a time and adds an "all" entry with this label that
+   * clears it. Picking the selected value again also clears it.
+   */
   single?: { allLabel: string };
 }
 
+/** The selection after toggling `value`; with `single`, at most that one value. */
 export const nextFilterSelection = (
   selected: readonly string[],
   value: string,
@@ -199,6 +220,7 @@ function FilterItem({ filter }: { filter: FilterDataTable }) {
   );
 }
 
+/** One filter button per entry; `ContentDataTable` renders it from its `filters` prop. */
 export function FiltersDataTable({ filters }: { filters: FilterDataTable[] }) {
   return (
     <>
diff --git a/packages/vitnode/src/components/table/navigation.tsx b/packages/vitnode/src/components/table/navigation.tsx
index 575b7abf87..7536e9b487 100644
--- a/packages/vitnode/src/components/table/navigation.tsx
+++ b/packages/vitnode/src/components/table/navigation.tsx
@@ -1,6 +1,12 @@
 import React from "react";
 
+/**
+ * How a data table reads and writes the URL. Sorting, paging, search and
+ * filters all live in the query string, so the host decides how a change
+ * navigates (e.g. TanStack Router's `navigate({ search })`).
+ */
 export interface DataTableNavigation {
+  /** Navigates to the given query string. Runs inside a React transition. */
   navigate: (nextSearch: string) => Promise<void> | void;
   /** The query string the table is currently rendering. Never mutated. */
   searchParams: URLSearchParams;
@@ -9,6 +15,7 @@ export interface DataTableNavigation {
 const DataTableNavigationContext =
   React.createContext<DataTableNavigation | null>(null);
 
+/** Provides {@link DataTableNavigation} to every data table control below it. Required by `ContentDataTable`. */
 export const DataTableNavigationProvider = ({
   children,
   value,
@@ -21,6 +28,12 @@ export const DataTableNavigationProvider = ({
   </DataTableNavigationContext.Provider>
 );
 
+/**
+ * The table's current query string and a `navigate` wrapped in a transition,
+ * whose `isPending` controls can show while the next page loads.
+ *
+ * @throws Outside a {@link DataTableNavigationProvider}.
+ */
 export const useDataTableUrl = (): {
   isPending: boolean;
   navigate: (nextSearch: string) => void;
diff --git a/packages/vitnode/src/components/table/reorder-handle.tsx b/packages/vitnode/src/components/table/reorder-handle.tsx
index c91fbb4f93..78cab6de54 100644
--- a/packages/vitnode/src/components/table/reorder-handle.tsx
+++ b/packages/vitnode/src/components/table/reorder-handle.tsx
@@ -9,12 +9,14 @@ export const SortableRowHandleContext =
 export const ROW_GROUP_CLASS =
   "[&:last-child>tr:last-child]:border-0 [&:last-child>tr:last-child>td]:border-b-0 [&>tr>td]:border-b";
 
+/** The handle column's header: a screen-reader-only label. */
 export function ReorderHeaderDataTable() {
   const t = useTranslations("core.global.data_table");
 
   return <span className="sr-only">{t("reorder_column")}</span>;
 }
 
+/** The current row's drag handle, from the nearest `SortableRowGroupDataTable`. */
 export function ReorderHandleDataTable() {
   return <>{React.use(SortableRowHandleContext)}</>;
 }
diff --git a/packages/vitnode/src/components/table/reorder-state.ts b/packages/vitnode/src/components/table/reorder-state.ts
index 56a62430f9..aacebe1e05 100644
--- a/packages/vitnode/src/components/table/reorder-state.ts
+++ b/packages/vitnode/src/components/table/reorder-state.ts
@@ -2,13 +2,17 @@ import type { DataTableRowId } from "./data-table-content";
 
 import { readTableOrder, readTableSearch, type TableOrder } from "./url-state";
 
+/** One drag, as `onReorder` receives it. Indexes are positions on the current page. */
 export interface ReorderDetailsDataTable {
+  /** The dragged row. */
   activeId: DataTableRowId;
   from: number;
+  /** The row it was dropped on. */
   overId: DataTableRowId;
   to: number;
 }
 
+/** A drag plus the page's row ids in their new order. */
 export interface RowMoveDataTable extends ReorderDetailsDataTable {
   ids: DataTableRowId[];
 }
@@ -23,6 +27,7 @@ const arrayMove = <T>(items: readonly T[], from: number, to: number): T[] => {
   return next;
 };
 
+/** Moves `activeId` to `overId`'s position; `null` when either is missing or they are the same row. */
 export const moveRowId = (
   ids: readonly DataTableRowId[],
   activeId: DataTableRowId,
@@ -42,6 +47,10 @@ export const moveRowId = (
   };
 };
 
+/**
+ * Whether the table shows rows in their stored order - no search, no filter
+ * and the default sort - which is the only time dragging can mean anything.
+ */
 export const isTableInStoredOrder = (
   searchParams: URLSearchParams,
   {
diff --git a/packages/vitnode/src/components/table/reorder.tsx b/packages/vitnode/src/components/table/reorder.tsx
index e8c9e22f22..fc79a3716d 100644
--- a/packages/vitnode/src/components/table/reorder.tsx
+++ b/packages/vitnode/src/components/table/reorder.tsx
@@ -42,6 +42,7 @@ const subscribeToNothing = () => () => undefined;
 const getAnnouncementContainer = () => document.body;
 const getNoAnnouncementContainer = () => null;
 
+/** The drag-and-drop context for one page of sortable rows. */
 export function ReorderProviderDataTable({
   children,
   ids,
@@ -111,6 +112,7 @@ export function ReorderProviderDataTable({
   );
 }
 
+/** One sortable row (a `tbody`, so an expanded panel moves with it), providing its handle. */
 export function SortableRowGroupDataTable({
   children,
   disabled,
diff --git a/packages/vitnode/src/components/table/row-order.ts b/packages/vitnode/src/components/table/row-order.ts
index 032c340ae2..c5c58e9739 100644
--- a/packages/vitnode/src/components/table/row-order.ts
+++ b/packages/vitnode/src/components/table/row-order.ts
@@ -8,9 +8,21 @@ import { moveRowId, type ReorderDetailsDataTable } from "./reorder-state";
 
 type RowIdOf<T> = T extends { id: infer TId } ? TId : DataTableRowId;
 
+/**
+ * Drag-to-reorder rows, by pointer, touch (press and hold) or keyboard, with
+ * screen-reader announcements. Dragging is turned off while the table is
+ * searched, filtered or sorted by anything but its `defaultOrder`.
+ */
 export interface ReorderableDataTable<T> {
+  /** Turns dragging off; the handles stay, disabled, with an explanation. */
   disabled?: boolean;
+  /** The row's name in the drag handle's label and in announcements. Defaults to its position. */
   getRowLabel?: (row: T) => string;
+  /**
+   * Saves the page's new order, given every row id on the page in that order.
+   * The table shows the new order at once; if this throws or rejects, it goes
+   * back and shows an error toast.
+   */
   onReorder: (
     ids: RowIdOf<T>[],
     details: ReorderDetailsDataTable,
@@ -22,6 +34,7 @@ interface RowOrderOverride {
   key: string;
 }
 
+/** The rows in their optimistic order, and the move that persists through `onReorder`. */
 export const useRowOrderDataTable = <T extends DataTableTMin>({
   edges,
   onReorder,
diff --git a/packages/vitnode/src/components/table/selection.tsx b/packages/vitnode/src/components/table/selection.tsx
index 8099079e43..85f3f555bd 100644
--- a/packages/vitnode/src/components/table/selection.tsx
+++ b/packages/vitnode/src/components/table/selection.tsx
@@ -15,13 +15,21 @@ import { SlidingNumber } from "../ui/sliding-number";
 import { TableRow } from "../ui/table";
 import { TooltipWithContent } from "../ui/tooltip";
 
+/**
+ * Row selection on the current page, from {@link useDataTableSelection}.
+ * Selection never spans pages: ids that leave the page are dropped.
+ */
 export interface SelectionDataTable {
+  /** Every row on the page is selected (and there is at least one). */
   allSelected: boolean;
   clear: () => void;
   isSelected: (id: DataTableRowId) => boolean;
+  /** The selected row ids. */
   selected: DataTableRowId[];
+  /** Some, but not all, rows are selected. */
   someSelected: boolean;
   toggle: (id: DataTableRowId) => void;
+  /** Selects every row on the page (`true`) or none (`false`). */
   toggleAll: (next: boolean) => void;
 }
 
@@ -33,6 +41,33 @@ const getPortalContainer = () => document.body;
 /** No DOM to portal into on the server, and the bar starts empty anyway. */
 const getNoPortalContainer = () => null;
 
+/**
+ * The table's row selection, for the buttons passed as `ContentDataTable`'s
+ * `bulkActions` - e.g. a delete action reading `selected`.
+ *
+ * @throws Outside a `ContentDataTable` that has `bulkActions`.
+ *
+ * @example
+ * ```tsx
+ * import { useDataTableSelection } from "@vitnode/core/components/table/selection";
+ * import { Button } from "@vitnode/core/components/ui/button";
+ *
+ * const DeleteSelected = ({ onDelete }: { onDelete: (ids: number[]) => void }) => {
+ *   const { clear, selected } = useDataTableSelection();
+ *
+ *   return (
+ *     <Button
+ *       onClick={() => {
+ *         onDelete(selected.filter(id => typeof id === "number"));
+ *         clear();
+ *       }}
+ *     >
+ *       Delete
+ *     </Button>
+ *   );
+ * };
+ * ```
+ */
 export const useDataTableSelection = (): SelectionDataTable => {
   const value = React.use(SelectionContext);
 
@@ -45,6 +80,7 @@ export const useDataTableSelection = (): SelectionDataTable => {
   return value;
 };
 
+/** Holds the selection for one page of rows. `ContentDataTable` mounts it for `bulkActions`. */
 export function SelectionProviderDataTable({
   children,
   rowIds,
@@ -92,6 +128,7 @@ export function SelectionProviderDataTable({
   );
 }
 
+/** The header checkbox: selects every row on the page, indeterminate when only some are. */
 export function SelectAllDataTable() {
   const t = useTranslations("core.global.data_table");
   const { allSelected, someSelected, toggleAll } = useDataTableSelection();
@@ -106,6 +143,7 @@ export function SelectAllDataTable() {
   );
 }
 
+/** One row's checkbox. */
 export function SelectRowDataTable({ id }: { id: DataTableRowId }) {
   const t = useTranslations("core.global.data_table");
   const { isSelected, toggle } = useDataTableSelection();
@@ -119,6 +157,7 @@ export function SelectRowDataTable({ id }: { id: DataTableRowId }) {
   );
 }
 
+/** A row marked `data-state="selected"` while it is selected. */
 export function RowSelectableDataTable({
   children,
   id,
@@ -135,6 +174,11 @@ export function RowSelectableDataTable({
   );
 }
 
+/**
+ * The floating bar at the bottom of the viewport while rows are selected: the
+ * count, `actions`, and a button that clears the selection. Rendered into
+ * `document.body`, and only in the browser.
+ */
 export function BulkActionsDataTable({
   actions,
 }: {
diff --git a/packages/vitnode/src/components/table/url-state.ts b/packages/vitnode/src/components/table/url-state.ts
index ff3a55847a..fc8ea6da81 100644
--- a/packages/vitnode/src/components/table/url-state.ts
+++ b/packages/vitnode/src/components/table/url-state.ts
@@ -6,8 +6,10 @@ const LAST = "last";
 const CURSOR = "cursor";
 const PAGE = "page";
 
+/** Rows per page while the URL names no `first` or `last`. */
 export const DEFAULT_TABLE_PAGE_SIZE = 10;
 
+/** Shorter search text is dropped from the URL instead of searched for. */
 export const MIN_TABLE_SEARCH_LENGTH = 3;
 
 export type TableOrderDirection = "asc" | "desc";
@@ -15,6 +17,7 @@ export type TableOrderDirection = "asc" | "desc";
 /** Whatever the caller has: a raw query string, or the params it parsed. */
 export type TableSearch = string | URLSearchParams;
 
+/** A sort: the column (the `orderBy` param) and its direction (`order`). */
 export interface TableOrder {
   column: string;
   order: TableOrderDirection;
@@ -31,6 +34,7 @@ const resetPagination = (params: URLSearchParams): void => {
   params.delete(PAGE);
 };
 
+/** Whether the URL is past the first page in cursor mode (`cursor` or `last` set). */
 export const hasTableCursor = (search: TableSearch): boolean => {
   const params = copy(search);
 
@@ -39,12 +43,18 @@ export const hasTableCursor = (search: TableSearch): boolean => {
   );
 };
 
+/** The page number in page-number mode; `1` when missing or invalid. */
 export const readTablePage = (search: TableSearch): number => {
   const page = Number(copy(search).get(PAGE));
 
   return Number.isInteger(page) && page > 0 ? page : 1;
 };
 
+/**
+ * Goes to `page` in page-number mode. Page 1 removes the parameter, and the
+ * `cursor` and `last` are dropped so the two modes never mix (`first` stays as
+ * the page size).
+ */
 export const withTablePageNumber = (
   search: TableSearch,
   page: number | string,
@@ -90,6 +100,7 @@ export const withTableOrder = (
   return params.toString();
 };
 
+/** A header click: `desc` when `column` is already sorted `asc`, otherwise `asc`. */
 export const toggleTableOrder = (
   search: TableSearch,
   { column, defaultOrder }: { column: string; defaultOrder: TableOrder },
@@ -111,6 +122,7 @@ export const readTablePageSize = (search: TableSearch): number => {
   return Number.isInteger(size) && size > 0 ? size : DEFAULT_TABLE_PAGE_SIZE;
 };
 
+/** Shows `pageSize` rows per page, back on the first page. */
 export const withTablePageSize = (
   search: TableSearch,
   pageSize: number | string,
diff --git a/packages/vitnode/src/components/ui/accordion.tsx b/packages/vitnode/src/components/ui/accordion.tsx
index 01654e74e4..ec352a3f2e 100644
--- a/packages/vitnode/src/components/ui/accordion.tsx
+++ b/packages/vitnode/src/components/ui/accordion.tsx
@@ -3,6 +3,9 @@ import { cn } from "cn";
 import { ChevronDownIcon } from "lucide-react";
 import React from "react";
 
+/**
+ * A Base UI accordion of collapsible sections, laid out as a full-width column.
+ */
 function Accordion({
   className,
   ...props
@@ -16,6 +19,9 @@ function Accordion({
   );
 }
 
+/**
+ * One section of an {@link Accordion}; every item but the last gets a bottom border.
+ */
 function AccordionItem({
   className,
   ...props
@@ -29,6 +35,10 @@ function AccordionItem({
   );
 }
 
+/**
+ * The section's header button, with a chevron that rotates while the section is
+ * open.
+ */
 function AccordionTrigger({
   className,
   children,
@@ -54,6 +64,10 @@ function AccordionTrigger({
   );
 }
 
+/**
+ * The section's collapsible panel, which animates its height (only its opacity
+ * under reduced motion).
+ */
 function AccordionContent({
   className,
   children,
diff --git a/packages/vitnode/src/components/ui/alert-dialog.tsx b/packages/vitnode/src/components/ui/alert-dialog.tsx
index d10c451956..17773d411c 100644
--- a/packages/vitnode/src/components/ui/alert-dialog.tsx
+++ b/packages/vitnode/src/components/ui/alert-dialog.tsx
@@ -14,8 +14,17 @@ const AlertDialogContext = React.createContext<{
   setOpen: () => {},
 });
 
+/**
+ * The surrounding {@link AlertDialog}'s `open` state and its `setOpen`, for
+ * closing the dialog from inside it, e.g. after an async confirm.
+ */
 const useAlertDialog = () => React.use(AlertDialogContext);
 
+/**
+ * A Base UI alert dialog for confirming a destructive or important action.
+ * Works controlled (`open`) or uncontrolled, and shares its state through
+ * {@link useAlertDialog}.
+ */
 function AlertDialog({
   onOpenChange,
   open: openProp,
@@ -51,6 +60,7 @@ function AlertDialog({
   );
 }
 
+/** The element that opens the dialog. */
 function AlertDialogTrigger({ ...props }: AlertDialogPrimitive.Trigger.Props) {
   return (
     <AlertDialogPrimitive.Trigger data-slot="alert-dialog-trigger" {...props} />
@@ -80,6 +90,10 @@ function AlertDialogOverlay({
   );
 }
 
+/**
+ * The centered dialog panel, rendered in a portal over a scrim. `size` is
+ * `"default"` (max width `lg`) or `"sm"`; defaults to `"default"`.
+ */
 function AlertDialogContent({
   className,
   size = "default",
@@ -103,6 +117,7 @@ function AlertDialogContent({
   );
 }
 
+/** Holds the title, description and optional media. */
 function AlertDialogHeader({
   className,
   ...props
@@ -119,6 +134,7 @@ function AlertDialogHeader({
   );
 }
 
+/** Holds the cancel and action buttons. */
 function AlertDialogFooter({
   className,
   ...props
@@ -135,6 +151,7 @@ function AlertDialogFooter({
   );
 }
 
+/** An icon or image shown in the header. */
 function AlertDialogMedia({
   className,
   ...props
@@ -151,6 +168,7 @@ function AlertDialogMedia({
   );
 }
 
+/** The dialog's accessible title. */
 function AlertDialogTitle({
   className,
   ...props
@@ -167,6 +185,7 @@ function AlertDialogTitle({
   );
 }
 
+/** The dialog's accessible description. */
 function AlertDialogDescription({
   className,
   ...props
@@ -185,6 +204,10 @@ function AlertDialogDescription({
 
 type AlertDialogButtonSize = "default" | "lg" | "sm" | "xs";
 
+/**
+ * A {@link Button} that closes the dialog. `variant` and `size` default to
+ * `"default"`; the label defaults to the translated "Confirm".
+ */
 function AlertDialogAction({
   children,
   className,
@@ -209,6 +232,11 @@ function AlertDialogAction({
   );
 }
 
+/**
+ * A {@link Button} that closes the dialog without acting. `variant` defaults to
+ * `"outline"`, `size` to `"default"`; the label defaults to the translated
+ * "Cancel".
+ */
 function AlertDialogCancel({
   children,
   className,
diff --git a/packages/vitnode/src/components/ui/alert.tsx b/packages/vitnode/src/components/ui/alert.tsx
index 5450d00670..a71fadcc76 100644
--- a/packages/vitnode/src/components/ui/alert.tsx
+++ b/packages/vitnode/src/components/ui/alert.tsx
@@ -49,8 +49,14 @@ const ALERT_VARIANTS: Record<
   },
 };
 
+/** The look and meaning of an {@link Alert}. */
 export type AlertVariant = keyof typeof ALERT_VARIANTS;
 
+/**
+ * A callout box for a message. `variant` (default `"default"`) sets its colors
+ * and icon; `warning` and `destructive` use `role="alert"`, the rest
+ * `role="status"`. `icon` replaces the variant's icon, and `null` hides it.
+ */
 function Alert({
   className,
   variant = "default",
@@ -98,6 +104,7 @@ function Alert({
   );
 }
 
+/** The alert's heading line. */
 function AlertTitle({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -111,6 +118,7 @@ function AlertTitle({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** The alert's body text. */
 function AlertDescription({
   className,
   ...props
@@ -127,6 +135,10 @@ function AlertDescription({
   );
 }
 
+/**
+ * A control pinned to the alert's top-right (end) corner, such as a dismiss
+ * button.
+ */
 function AlertAction({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
diff --git a/packages/vitnode/src/components/ui/aspect-ratio.tsx b/packages/vitnode/src/components/ui/aspect-ratio.tsx
index 407726f496..2690798a8d 100644
--- a/packages/vitnode/src/components/ui/aspect-ratio.tsx
+++ b/packages/vitnode/src/components/ui/aspect-ratio.tsx
@@ -1,6 +1,10 @@
 import { cn } from "cn";
 import React from "react";
 
+/**
+ * Keeps its content at a fixed width-to-height `ratio` (e.g. `16 / 9`);
+ * defaults to `1`.
+ */
 function AspectRatio({
   ratio = 1,
   className,
diff --git a/packages/vitnode/src/components/ui/attachment.tsx b/packages/vitnode/src/components/ui/attachment.tsx
index 8aad68b15e..6bef21788d 100644
--- a/packages/vitnode/src/components/ui/attachment.tsx
+++ b/packages/vitnode/src/components/ui/attachment.tsx
@@ -24,6 +24,12 @@ const attachmentVariants = cva(
   },
 );
 
+/**
+ * A card for one attached file. `state` (default `"done"`) styles it - dashed
+ * while `idle`, red on `error`; `size` is `"default"`, `"sm"` or `"xs"`
+ * (default `"default"`); `orientation` is `"horizontal"` (default) or
+ * `"vertical"`.
+ */
 function Attachment({
   className,
   state = "done",
@@ -62,6 +68,10 @@ const attachmentMediaVariants = cva(
   },
 );
 
+/**
+ * The file's icon or thumbnail. `variant` is `"icon"` (default) or `"image"`,
+ * which dims the image until the upload is done.
+ */
 function AttachmentMedia({
   className,
   variant = "icon",
@@ -77,6 +87,7 @@ function AttachmentMedia({
   );
 }
 
+/** Holds the title and description. */
 function AttachmentContent({
   className,
   ...props
@@ -106,6 +117,10 @@ const splitFileName = (name: string): [string, string] => {
   return [name.slice(0, dot), name.slice(dot)];
 };
 
+/**
+ * The file name. A string keeps its extension visible while the name truncates,
+ * and the full name becomes the `title` tooltip.
+ */
 function AttachmentTitle({
   children,
   className,
@@ -130,6 +145,7 @@ function AttachmentTitle({
   );
 }
 
+/** Secondary text, such as the file size or upload progress. */
 function AttachmentDescription({
   className,
   ...props
@@ -147,6 +163,7 @@ function AttachmentDescription({
   );
 }
 
+/** Holds the attachment's action buttons. */
 function AttachmentActions({
   className,
   ...props
@@ -163,6 +180,10 @@ function AttachmentActions({
   );
 }
 
+/**
+ * A small ghost icon {@link Button} for one action (size `"icon-xs"` by
+ * default). Has a generic `aria-label`; pass your own describing the action.
+ */
 function AttachmentAction({
   className,
   variant,
@@ -181,6 +202,10 @@ function AttachmentAction({
   );
 }
 
+/**
+ * An invisible button over the whole card that makes it clickable
+ * (`type="button"` unless you `render` something else).
+ */
 function AttachmentTrigger({
   className,
   render,
@@ -203,6 +228,7 @@ function AttachmentTrigger({
   });
 }
 
+/** A horizontally scrolling, snapping row of attachments. */
 function AttachmentGroup({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
diff --git a/packages/vitnode/src/components/ui/avatar.tsx b/packages/vitnode/src/components/ui/avatar.tsx
index 67b35786ca..a08ebeced4 100644
--- a/packages/vitnode/src/components/ui/avatar.tsx
+++ b/packages/vitnode/src/components/ui/avatar.tsx
@@ -15,6 +15,10 @@ import {
   useIsInTooltipGroup,
 } from "./tooltip";
 
+/**
+ * A round user avatar. `size` is `"sm"`, `"default"` or `"lg"` (24, 32 and 40
+ * px); defaults to `"default"`.
+ */
 function Avatar({
   className,
   size = "default",
@@ -35,6 +39,7 @@ function Avatar({
   );
 }
 
+/** The avatar's image. */
 function AvatarImage({
   className,
   ...props
@@ -51,6 +56,7 @@ function AvatarImage({
   );
 }
 
+/** Shown while the image loads or when it fails, e.g. initials. */
 function AvatarFallback({
   className,
   ...props
@@ -67,6 +73,7 @@ function AvatarFallback({
   );
 }
 
+/** A small status dot on the avatar's edge. */
 function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) {
   return (
     <span
@@ -83,6 +90,7 @@ function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) {
   );
 }
 
+/** Overlapping avatars in a row, sharing one tooltip group. */
 function AvatarGroup({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <TooltipGroup>
@@ -104,6 +112,11 @@ const AVATAR_LIFT_TRANSITION = {
   bounce: 0.15,
 } as const;
 
+/**
+ * One avatar in an {@link AvatarGroup}. With a `label`, it becomes focusable
+ * and shows the label as a tooltip; it lifts on hover and focus unless reduced
+ * motion is on.
+ */
 function AvatarGroupItem({
   children,
   className,
@@ -154,6 +167,9 @@ function AvatarGroupItem({
   );
 }
 
+/**
+ * A "+N" bubble for the avatars a group leaves out, sized to match the group.
+ */
 function AvatarGroupCount({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/badge.tsx b/packages/vitnode/src/components/ui/badge.tsx
index 7b0a4d9a57..4f78a0f2a7 100644
--- a/packages/vitnode/src/components/ui/badge.tsx
+++ b/packages/vitnode/src/components/ui/badge.tsx
@@ -5,6 +5,9 @@ import { cn } from "cn";
 
 import { FEEDBACK_TONE_TEXT, SOLID_PRIMARY_SURFACE } from "./feedback-tone";
 
+/**
+ * The badge class names per `variant`, for styling another element as a badge.
+ */
 const badgeVariants = cva(
   "group/badge inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-4xl border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap tabular-nums transition-[color,background-color,border-color,box-shadow] focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 has-data-[icon=inline-end]:pe-1.5 has-data-[icon=inline-start]:ps-1.5 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&>svg]:pointer-events-none [&>svg]:size-3!",
   {
@@ -38,6 +41,11 @@ const badgeVariants = cva(
   },
 );
 
+/**
+ * A small label, rendered as a `span` (or your `render`). `variant` is
+ * `default`, `secondary`, `destructive`, `success`, `warning`, `outline`,
+ * `ghost` or `link`; defaults to `"default"`.
+ */
 function Badge({
   className,
   variant = "default",
diff --git a/packages/vitnode/src/components/ui/bubble.tsx b/packages/vitnode/src/components/ui/bubble.tsx
index 9fd69d8a3c..d5945d3b78 100644
--- a/packages/vitnode/src/components/ui/bubble.tsx
+++ b/packages/vitnode/src/components/ui/bubble.tsx
@@ -4,6 +4,7 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "cn";
 import * as React from "react";
 
+/** Stacks chat bubbles in a column. */
 function BubbleGroup({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -41,6 +42,11 @@ const bubbleVariants = cva(
   },
 );
 
+/**
+ * A chat message bubble. `variant` is `default`, `secondary`, `muted`,
+ * `tinted`, `outline`, `ghost` or `destructive` (default `"default"`); `align`
+ * (`"start"` by default, or `"end"`) sets which side it sits on.
+ */
 function Bubble({
   variant = "default",
   align = "start",
@@ -61,6 +67,7 @@ function Bubble({
   );
 }
 
+/** The bubble's message body, rendered as a `div` (or your `render`). */
 function BubbleContent({
   className,
   render,
@@ -104,6 +111,10 @@ const bubbleReactionsVariants = cva(
   },
 );
 
+/**
+ * Reactions pinned to the bubble's edge. `side` defaults to `"bottom"` (or
+ * `"top"`), `align` to `"end"` (or `"start"`).
+ */
 function BubbleReactions({
   side = "bottom",
   align = "end",
diff --git a/packages/vitnode/src/components/ui/button-group.tsx b/packages/vitnode/src/components/ui/button-group.tsx
index e829f65845..6a4624f4bf 100644
--- a/packages/vitnode/src/components/ui/button-group.tsx
+++ b/packages/vitnode/src/components/ui/button-group.tsx
@@ -5,6 +5,7 @@ import { cn } from "cn";
 
 import { Separator } from "@/components/ui/separator";
 
+/** The button group class names per `orientation`. */
 const buttonGroupVariants = cva(
   "group/button-group flex w-fit items-stretch *:data-[slot=button]:active:not-aria-[haspopup]:brightness-95 *:focus-visible:relative *:focus-visible:z-10 has-[>[data-slot=button-group]]:gap-2 has-[select[aria-hidden=true]:last-child]:[&>[data-slot=select-trigger]:last-of-type]:rounded-e-md [&>[data-slot=select-trigger]:not([class*='w-'])]:w-fit [&>input]:flex-1",
   {
@@ -22,6 +23,10 @@ const buttonGroupVariants = cva(
   },
 );
 
+/**
+ * Joins buttons and inputs into one connected control, with `role="group"`.
+ * `orientation` defaults to `"horizontal"`.
+ */
 function ButtonGroup({
   className,
   orientation,
@@ -38,6 +43,10 @@ function ButtonGroup({
   );
 }
 
+/**
+ * A static text segment inside a {@link ButtonGroup}, rendered as a `div` (or
+ * your `render`).
+ */
 function ButtonGroupText({
   className,
   render,
@@ -61,6 +70,7 @@ function ButtonGroupText({
   });
 }
 
+/** A divider between segments of a {@link ButtonGroup}; vertical by default. */
 function ButtonGroupSeparator({
   className,
   orientation = "vertical",
diff --git a/packages/vitnode/src/components/ui/button.tsx b/packages/vitnode/src/components/ui/button.tsx
index 5b2104775b..12abb968ad 100644
--- a/packages/vitnode/src/components/ui/button.tsx
+++ b/packages/vitnode/src/components/ui/button.tsx
@@ -9,6 +9,10 @@ import { ClientButton } from "./button-client";
 const coarsePointerHitArea =
   "relative pointer-coarse:after:absolute pointer-coarse:after:top-1/2 pointer-coarse:after:left-1/2 pointer-coarse:after:size-11 pointer-coarse:after:-translate-1/2";
 
+/**
+ * The button class names per `variant` and `size`, for styling another element
+ * (such as a link) as a button.
+ */
 const buttonVariants = cva(
   "group/button inline-flex shrink-0 items-center justify-center rounded-md border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-[color,background-color,border-color,box-shadow,opacity,scale,filter] duration-150 ease-out outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 active:not-aria-[haspopup]:not-in-data-[slot=button-group]:scale-97 disabled:pointer-events-none disabled:opacity-50 aria-disabled:cursor-not-allowed aria-disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 cursor-pointer",
   {
@@ -55,6 +59,10 @@ const buttonVariants = cva(
   },
 );
 
+/**
+ * Props of {@link Button}. The icon sizes require an `aria-label`, since the
+ * button has no visible text.
+ */
 type ButtonProps = Omit<ButtonPrimitive.Props, "className"> &
   VariantProps<typeof buttonVariants> &
   (
@@ -66,6 +74,15 @@ type ButtonProps = Omit<ButtonPrimitive.Props, "className"> &
     isLoading?: boolean;
   };
 
+/**
+ * A Base UI button. `variant` is `default`, `outline`, `secondary`, `ghost`,
+ * `destructive`, `success`, `warning` or `link`; `size` is `default`, `xs`,
+ * `sm`, `lg` or an icon size (`icon`, `icon-xs`, `icon-sm`, `icon-lg`), both
+ * defaulting to `"default"`. `isLoading` disables it and swaps its content for
+ * a spinner, with a translated "Loading..." label; `disabledTooltip` explains
+ * why a disabled button is disabled and keeps it focusable. The `icon`,
+ * `icon-xs` and `icon-sm` sizes get a 44px touch target on coarse pointers.
+ */
 function Button(props: ButtonProps) {
   return <ClientButton {...props} />;
 }
diff --git a/packages/vitnode/src/components/ui/calendar.tsx b/packages/vitnode/src/components/ui/calendar.tsx
index 178b2cbf5b..a7089680e7 100644
--- a/packages/vitnode/src/components/ui/calendar.tsx
+++ b/packages/vitnode/src/components/ui/calendar.tsx
@@ -18,6 +18,10 @@ import { useLocale, useTranslations } from "use-intl";
 import { type ButtonProps, buttonVariants } from "./button";
 import { getFirstDayOfWeek, toDateString } from "./calendar-utils";
 
+/**
+ * Props of {@link Calendar}: every `react-day-picker` `DayPicker` prop, plus
+ * the nav buttons' `buttonVariant`.
+ */
 type CalendarProps = React.ComponentProps<typeof DayPicker> & {
   buttonVariant?: ButtonProps["variant"];
 };
@@ -72,6 +76,12 @@ const CalendarWeekNumber = ({
   </td>
 );
 
+/**
+ * A `react-day-picker` calendar styled for VitNode. Without a `locale` prop it
+ * follows the UI language: month captions are formatted in it, the week starts
+ * on its first day, and the accessibility labels are translated. Shows outside
+ * days by default; `buttonVariant` for the nav buttons defaults to `"ghost"`.
+ */
 const Calendar = ({
   className,
   classNames,
@@ -240,6 +250,10 @@ const Calendar = ({
   );
 };
 
+/**
+ * The button for one day, used by {@link Calendar}; it takes focus when the day
+ * is focused and exposes the selection and range state as `data-*` attributes.
+ */
 const CalendarDayButton = ({
   className,
   day,
diff --git a/packages/vitnode/src/components/ui/card.tsx b/packages/vitnode/src/components/ui/card.tsx
index d798eb8005..3b6957afb1 100644
--- a/packages/vitnode/src/components/ui/card.tsx
+++ b/packages/vitnode/src/components/ui/card.tsx
@@ -1,6 +1,10 @@
 import { cn } from "cn";
 import React from "react";
 
+/**
+ * A bordered surface for grouped content. `size` is `"default"` or `"sm"`
+ * (tighter spacing); defaults to `"default"`.
+ */
 function Card({
   className,
   size = "default",
@@ -19,6 +23,7 @@ function Card({
   );
 }
 
+/** The card's top area for its title, description and action. */
 function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -32,6 +37,7 @@ function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** The card's heading. */
 function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -45,6 +51,7 @@ function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** Secondary text under the title. */
 function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -55,6 +62,7 @@ function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** A control placed at the header's top-right (end) corner. */
 function CardAction({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -68,6 +76,7 @@ function CardAction({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** The card's main body. */
 function CardContent({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -78,6 +87,7 @@ function CardContent({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** The card's bottom area, e.g. for buttons. */
 function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
diff --git a/packages/vitnode/src/components/ui/carousel.tsx b/packages/vitnode/src/components/ui/carousel.tsx
index 57bd19b6aa..b7f55d6ac6 100644
--- a/packages/vitnode/src/components/ui/carousel.tsx
+++ b/packages/vitnode/src/components/ui/carousel.tsx
@@ -20,15 +20,24 @@ import {
   isRtlElement,
 } from "./carousel-utils";
 
+/** The Embla carousel API, received through {@link Carousel}'s `setApi`. */
 type CarouselApi = UseEmblaCarouselType[1];
 type UseCarouselParameters = Parameters<typeof useEmblaCarousel>;
 type CarouselOptions = UseCarouselParameters[0];
 type CarouselPlugin = UseCarouselParameters[1];
 
+/** Options of {@link Carousel}. */
 interface CarouselProps {
+  /** Embla options, e.g. `{ loop: true }`. */
   opts?: CarouselOptions;
+  /** Scroll axis. Defaults to `"horizontal"`. */
   orientation?: "horizontal" | "vertical";
+  /** Embla plugins, e.g. autoplay. */
   plugins?: CarouselPlugin;
+  /**
+   * Receives the Embla API once the carousel is ready, for driving it from
+   * outside.
+   */
   setApi?: (api: CarouselApi) => void;
 }
 
@@ -53,6 +62,11 @@ function useCarousel() {
   return context;
 }
 
+/**
+ * An Embla carousel region (`aria-roledescription="carousel"`). Arrow keys move
+ * between slides, respecting right-to-left layouts, except while typing in a
+ * field.
+ */
 function Carousel({
   orientation = "horizontal",
   opts,
@@ -159,6 +173,7 @@ function Carousel({
   );
 }
 
+/** The scrolling track that holds the slides. */
 function CarouselContent({ className, ...props }: React.ComponentProps<"div">) {
   const { carouselRef, orientation } = useCarousel();
 
@@ -180,6 +195,7 @@ function CarouselContent({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** One slide (`aria-roledescription="slide"`). */
 function CarouselItem({ className, ...props }: React.ComponentProps<"div">) {
   const { orientation } = useCarousel();
 
@@ -198,6 +214,10 @@ function CarouselItem({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/**
+ * Scrolls to the previous slide; disabled at the start. Labelled with the
+ * translated "Previous".
+ */
 function CarouselPrevious({
   className,
   variant = "outline",
@@ -233,6 +253,10 @@ function CarouselPrevious({
   );
 }
 
+/**
+ * Scrolls to the next slide; disabled at the end. Labelled with the translated
+ * "Next".
+ */
 function CarouselNext({
   className,
   variant = "outline",
diff --git a/packages/vitnode/src/components/ui/cascader-utils.ts b/packages/vitnode/src/components/ui/cascader-utils.ts
index e8d151b7af..9d80423490 100644
--- a/packages/vitnode/src/components/ui/cascader-utils.ts
+++ b/packages/vitnode/src/components/ui/cascader-utils.ts
@@ -1,5 +1,9 @@
 import type React from "react";
 
+/**
+ * One option in a {@link Cascader}-style tree. An option with `children` is a
+ * branch that opens the next level; only leaves can be chosen.
+ */
 export interface CascaderOption {
   children?: CascaderOption[];
   disabled?: boolean;
diff --git a/packages/vitnode/src/components/ui/cascader.tsx b/packages/vitnode/src/components/ui/cascader.tsx
index 62dbdc34af..e5bd23c352 100644
--- a/packages/vitnode/src/components/ui/cascader.tsx
+++ b/packages/vitnode/src/components/ui/cascader.tsx
@@ -51,17 +51,41 @@ interface CascaderProps {
   "aria-invalid"?: boolean;
   "aria-labelledby"?: string;
   className?: string;
+  /** The selected leaf's `value` when uncontrolled. Defaults to `null`. */
   defaultValue?: null | string;
   disabled?: boolean;
+  /**
+   * Opens a branch on `"click"` (default) or `"hover"`; hover only applies to
+   * the columns layout.
+   */
   expandTrigger?: "click" | "hover";
   id?: string;
+  /**
+   * `"drill"` (default) shows one level at a time; `"columns"` shows every
+   * level side by side. Phones always use drill.
+   */
   layout?: "columns" | "drill";
+  /**
+   * Called with the chosen leaf's `value` (or `null` when cleared) and the path
+   * of options leading to it.
+   */
   onValueChange?: (value: null | string, path: CascaderOption[]) => void;
+  /** The option tree. */
   options: CascaderOption[];
+  /** Shown on the trigger while nothing is selected. */
   placeholder?: string;
+  /**
+   * Adds a search box that matches option labels across every level, ignoring
+   * accents. Defaults to `false`.
+   */
   searchable?: boolean;
+  /**
+   * Joins the labels of the selected path on the trigger. Defaults to `" / "`.
+   */
   separator?: string;
+  /** Shows a button that clears the selection. Defaults to `false`. */
   showClear?: boolean;
+  /** The selected leaf's `value` when controlled; `null` for none. */
   value?: null | string;
 }
 
@@ -569,6 +593,10 @@ const CascaderTrigger = ({
   );
 };
 
+/**
+ * A popover picker for one leaf in a tree of options, controlled (`value`) or
+ * uncontrolled (`defaultValue`).
+ */
 const Cascader = ({
   defaultValue = null,
   disabled = false,
diff --git a/packages/vitnode/src/components/ui/chart-utils.ts b/packages/vitnode/src/components/ui/chart-utils.ts
index 3cd0fb644a..01501d0b62 100644
--- a/packages/vitnode/src/components/ui/chart-utils.ts
+++ b/packages/vitnode/src/components/ui/chart-utils.ts
@@ -10,12 +10,18 @@ export const chartColorKeys = (config: ChartConfig) =>
     .filter(([, item]) => item.theme ?? item.color)
     .map(([key]) => key);
 
+/**
+ * The `@tanstack/charts` color scale for a {@link ChartConfig}: each key that
+ * has a color maps to its `var(--color-<key>)` CSS variable, which
+ * `ChartContainer` defines.
+ */
 export const chartColor = (config: ChartConfig): ChartColorOptions => {
   const domain = chartColorKeys(config);
 
   return { domain, range: domain.map(key => `var(--color-${key})`) };
 };
 
+/** The spring VitNode charts use to move their tooltip. */
 export const chartTooltipMotion = {
   damping: 40,
   mass: 1,
diff --git a/packages/vitnode/src/components/ui/chart.tsx b/packages/vitnode/src/components/ui/chart.tsx
index 07d91d9c4a..37fa4e9125 100644
--- a/packages/vitnode/src/components/ui/chart.tsx
+++ b/packages/vitnode/src/components/ui/chart.tsx
@@ -9,6 +9,11 @@ import { chartColorKeys } from "./chart-utils";
 // Format: { THEME_NAME: CSS_SELECTOR }
 const THEMES = { light: "", dark: ".dark" } as const;
 
+/**
+ * Each series' label, icon and color, keyed by the series key. Give a `color`
+ * or a `theme` with a `light` and a `dark` color; each becomes the CSS variable
+ * `--color-<key>` inside the chart.
+ */
 export type ChartConfig = Record<
   string,
   (
@@ -58,6 +63,12 @@ const CHART_THEME = {
   "--ts-chart-tooltip-active-row-shadow": "none",
 } as React.CSSProperties;
 
+/**
+ * Wraps a `@tanstack/charts` chart: it applies the VitNode chart theme, defines
+ * a `--color-<key>` variable per {@link ChartConfig} entry that has a color,
+ * and provides the
+ * config to the tooltip and legend.
+ */
 function ChartContainer({
   id,
   className,
@@ -143,6 +154,12 @@ const formatValue = (value: unknown, locale: string) => {
   return typeof value === "string" ? value : "";
 };
 
+/**
+ * Tooltip body for a chart inside {@link ChartContainer}. Labels come from the
+ * config and values are formatted in the UI language. `indicator` is `"dot"`
+ * (default), `"line"` or `"dashed"`; `hideLabel` and `hideIndicator` default to
+ * `false`.
+ */
 function ChartTooltipContent({
   points,
   className,
@@ -298,6 +315,11 @@ function ChartTooltipContent({
   );
 }
 
+/**
+ * A legend for the series in the surrounding {@link ChartContainer}'s config
+ * that have a color, or only `keys` when given. Renders nothing when there are no series;
+ * `hideIcon` defaults to `false`.
+ */
 function ChartLegend({
   className,
   hideIcon = false,
diff --git a/packages/vitnode/src/components/ui/checkbox.tsx b/packages/vitnode/src/components/ui/checkbox.tsx
index a744139f0f..151f630ecb 100644
--- a/packages/vitnode/src/components/ui/checkbox.tsx
+++ b/packages/vitnode/src/components/ui/checkbox.tsx
@@ -11,6 +11,10 @@ const indeterminatePath = "M5 12h14";
 const CHECK_SPRING = { type: "spring", duration: 0.35, bounce: 0 } as const;
 const UNCHECK_TRANSITION = { duration: 0.1, ease: "easeOut" } as const;
 
+/**
+ * A Base UI checkbox whose check (or indeterminate dash) draws itself in;
+ * instant under reduced motion.
+ */
 function Checkbox({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/color-picker.tsx b/packages/vitnode/src/components/ui/color-picker.tsx
index b409b0c675..0281b99f96 100644
--- a/packages/vitnode/src/components/ui/color-picker.tsx
+++ b/packages/vitnode/src/components/ui/color-picker.tsx
@@ -18,6 +18,12 @@ const HslStringColorPicker = React.lazy(async () => ({
 
 const FALLBACK_PICKER_COLOR = "hsl(0, 0%, 0%)";
 
+/**
+ * An outline button that opens a color popover: preset swatches, a free HSL
+ * picker (loaded lazily) and a text input for any CSS color. Calls `onChange`
+ * with the new color string; `allowRemoveColor` adds a button that clears it to
+ * `""`. Shows `placeholder`, else the translated "Pick a color", while empty.
+ */
 export const ColorPicker = ({
   value = "",
   onChange,
diff --git a/packages/vitnode/src/components/ui/color-preset-picker.tsx b/packages/vitnode/src/components/ui/color-preset-picker.tsx
index 300fe40596..6e1805cc31 100644
--- a/packages/vitnode/src/components/ui/color-preset-picker.tsx
+++ b/packages/vitnode/src/components/ui/color-preset-picker.tsx
@@ -34,6 +34,10 @@ const ColorPresetSwatch = ({ preset }: { preset: ColorPreset }) => {
   );
 };
 
+/**
+ * A radio grid of VitNode's preset colors, each labelled with its translated
+ * name. Calls `onChange` with the chosen preset's color value.
+ */
 export const ColorPresetPicker = ({
   value = "",
   onChange,
diff --git a/packages/vitnode/src/components/ui/combobox.tsx b/packages/vitnode/src/components/ui/combobox.tsx
index e082ef4a80..98376272f6 100644
--- a/packages/vitnode/src/components/ui/combobox.tsx
+++ b/packages/vitnode/src/components/ui/combobox.tsx
@@ -15,6 +15,7 @@ import {
   InputGroupInput,
 } from "@/components/ui/input-group";
 
+/** Base UI's combobox root: a text input that filters a list of options. */
 const Combobox = ComboboxPrimitive.Root;
 
 function ComboboxValue({ ...props }: ComboboxPrimitive.Value.Props) {
@@ -54,6 +55,11 @@ function ComboboxClear({ className, ...props }: ComboboxPrimitive.Clear.Props) {
   );
 }
 
+/**
+ * The combobox's text input inside an input group. `showTrigger` (default
+ * `true`) adds a button that opens the list; `showClear` (default `false`) adds
+ * a clear button, which takes the trigger's place while there is a value.
+ */
 function ComboboxInput({
   className,
   children,
@@ -89,6 +95,10 @@ function ComboboxInput({
   );
 }
 
+/**
+ * The popup holding the option list, rendered in a portal; opens below and
+ * aligned to the start of the input by default.
+ */
 function ComboboxContent({
   className,
   side = "bottom",
@@ -126,6 +136,7 @@ function ComboboxContent({
   );
 }
 
+/** The scrolling list of options. */
 function ComboboxList({ className, ...props }: ComboboxPrimitive.List.Props) {
   return (
     <ComboboxPrimitive.List
@@ -139,6 +150,7 @@ function ComboboxList({ className, ...props }: ComboboxPrimitive.List.Props) {
   );
 }
 
+/** One option, with a check mark while selected. */
 function ComboboxItem({
   className,
   children,
@@ -194,6 +206,7 @@ function ComboboxCollection({ ...props }: ComboboxPrimitive.Collection.Props) {
   );
 }
 
+/** Shown when no option matches the input. */
 function ComboboxEmpty({ className, ...props }: ComboboxPrimitive.Empty.Props) {
   return (
     <ComboboxPrimitive.Empty
diff --git a/packages/vitnode/src/components/ui/command.tsx b/packages/vitnode/src/components/ui/command.tsx
index 49b3aee449..5960db1d0e 100644
--- a/packages/vitnode/src/components/ui/command.tsx
+++ b/packages/vitnode/src/components/ui/command.tsx
@@ -12,6 +12,7 @@ import {
 } from "@/components/ui/dialog";
 import { InputGroup, InputGroupAddon } from "@/components/ui/input-group";
 
+/** A `cmdk` command menu: a filterable list of actions. */
 function Command({
   className,
   ...props
@@ -28,6 +29,11 @@ function Command({
   );
 }
 
+/**
+ * A {@link Command} inside a dialog, e.g. a command palette. `title` and
+ * `description` are read by screen readers only and default to English text, so
+ * pass translated ones; `showCloseButton` defaults to `false`.
+ */
 function CommandDialog({
   title = "Command Palette",
   description = "Search for a command to run...",
@@ -60,6 +66,7 @@ function CommandDialog({
   );
 }
 
+/** The search input that filters the menu, with a search icon. */
 function CommandInput({
   className,
   ...props
@@ -83,6 +90,7 @@ function CommandInput({
   );
 }
 
+/** The scrolling list of groups and items. */
 function CommandList({
   className,
   ...props
@@ -99,6 +107,7 @@ function CommandList({
   );
 }
 
+/** Shown when nothing matches the search. */
 function CommandEmpty({
   className,
   ...props
@@ -112,6 +121,7 @@ function CommandEmpty({
   );
 }
 
+/** A titled group of items (`heading`). */
 function CommandGroup({
   className,
   ...props
@@ -128,6 +138,7 @@ function CommandGroup({
   );
 }
 
+/** A divider between groups. */
 function CommandSeparator({
   className,
   ...props
@@ -141,6 +152,10 @@ function CommandSeparator({
   );
 }
 
+/**
+ * One action; shows a check mark while `data-checked` is true, unless it has a
+ * shortcut.
+ */
 function CommandItem({
   className,
   children,
@@ -161,6 +176,7 @@ function CommandItem({
   );
 }
 
+/** A keyboard shortcut hint at the item's end. */
 function CommandShortcut({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/comparison.tsx b/packages/vitnode/src/components/ui/comparison.tsx
index 4ec0faad92..18caaf3f45 100644
--- a/packages/vitnode/src/components/ui/comparison.tsx
+++ b/packages/vitnode/src/components/ui/comparison.tsx
@@ -36,6 +36,13 @@ const useComparison = () => {
   return context;
 };
 
+/**
+ * A before/after slider over two overlaid {@link ComparisonItem}s. `mode` is
+ * `"drag"` (default) or `"hover"`; `defaultPosition` is a percentage, default
+ * `50`. It is a keyboard slider: arrow keys move 5% (10% with Shift), and the
+ * label defaults to the translated "Comparison slider". `onPositionChange` gets
+ * the new percentage.
+ */
 function Comparison({
   "aria-label": ariaLabel,
   className,
@@ -144,6 +151,11 @@ function Comparison({
   );
 }
 
+/**
+ * One side of a {@link Comparison}, clipped at the current position. `position`
+ * is `"left"` or `"right"`. Hidden from screen readers, so describe the
+ * comparison in the slider's label.
+ */
 function ComparisonItem({
   className,
   position: side,
@@ -170,6 +182,7 @@ function ComparisonItem({
   );
 }
 
+/** The divider line and grip at the current position. */
 function ComparisonHandle({
   children,
   className,
diff --git a/packages/vitnode/src/components/ui/context-menu.tsx b/packages/vitnode/src/components/ui/context-menu.tsx
index f6d5edf391..d04182401a 100644
--- a/packages/vitnode/src/components/ui/context-menu.tsx
+++ b/packages/vitnode/src/components/ui/context-menu.tsx
@@ -3,12 +3,14 @@ import { cn } from "cn";
 import { CheckIcon, ChevronRightIcon } from "lucide-react";
 import React from "react";
 
+/** A Base UI menu opened by right-click or long-press on its trigger. */
 function ContextMenu({
   ...props
 }: React.ComponentProps<typeof ContextMenuPrimitive.Root>) {
   return <ContextMenuPrimitive.Root data-slot="context-menu" {...props} />;
 }
 
+/** The area that opens the menu. */
 function ContextMenuTrigger({
   className,
   ...props
@@ -57,6 +59,7 @@ function ContextMenuRadioGroup({
   );
 }
 
+/** The menu popup, rendered in a portal. */
 function ContextMenuContent({
   className,
   align = "start",
@@ -93,6 +96,10 @@ function ContextMenuContent({
   );
 }
 
+/**
+ * One action. `variant` is `"default"` or `"destructive"`; `inset` indents it
+ * to line up with items that have icons.
+ */
 function ContextMenuItem({
   className,
   inset,
@@ -260,6 +267,7 @@ function ContextMenuLabel({
   );
 }
 
+/** A divider between items. */
 function ContextMenuSeparator({
   className,
   ...props
@@ -273,6 +281,7 @@ function ContextMenuSeparator({
   );
 }
 
+/** A keyboard shortcut hint at the item's end. */
 function ContextMenuShortcut({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/copy-button.tsx b/packages/vitnode/src/components/ui/copy-button.tsx
index 9fbb3e6044..0926b68407 100644
--- a/packages/vitnode/src/components/ui/copy-button.tsx
+++ b/packages/vitnode/src/components/ui/copy-button.tsx
@@ -22,9 +22,16 @@ type CopyButtonProps = Omit<
   VariantProps<typeof buttonVariants> & {
     children?: React.ReactNode;
     className?: string;
+    /**
+     * The text to copy, or a function returning it (possibly async). A function
+     * is called on click, with the button showing as busy until it resolves.
+     */
     content: (() => Promise<string> | string) | string;
+    /** Controls the copied state yourself. */
     copied?: boolean;
+    /** How long the copied state lasts, in milliseconds. Defaults to `2000`. */
     delay?: number;
+    /** Called when the copied state turns on or off. */
     onCopiedChange?: (copied: boolean) => void;
   };
 
@@ -100,6 +107,12 @@ const CopiedCheck = ({
   </svg>
 );
 
+/**
+ * A button styled like {@link Button} that copies `content` to the clipboard and swaps its icon
+ * for a check while copied. `variant` defaults to `"outline"`, and without
+ * children it is an icon button labelled with the translated "Copy" / "Copied",
+ * announced to screen readers. A failed copy shows an error toast.
+ */
 function CopyButton({
   "aria-label": ariaLabel,
   children,
diff --git a/packages/vitnode/src/components/ui/counter.tsx b/packages/vitnode/src/components/ui/counter.tsx
index 415b04f739..4903221470 100644
--- a/packages/vitnode/src/components/ui/counter.tsx
+++ b/packages/vitnode/src/components/ui/counter.tsx
@@ -9,6 +9,12 @@ import { SlidingNumber } from "./sliding-number";
 const clampCounterValue = (value: number, min: number, max: number) =>
   Math.min(max, Math.max(min, value));
 
+/**
+ * A number with decrease and increase buttons (translated labels), controlled
+ * (`value`) or uncontrolled (`defaultValue`, default `0`). Each press moves by
+ * `step` (default `1`) within `min` and `max` (unbounded by default) and calls
+ * `onValueChange`.
+ */
 function Counter({
   className,
   defaultValue = 0,
diff --git a/packages/vitnode/src/components/ui/date-picker.tsx b/packages/vitnode/src/components/ui/date-picker.tsx
index 94d1fd2afe..6321b0f8c1 100644
--- a/packages/vitnode/src/components/ui/date-picker.tsx
+++ b/packages/vitnode/src/components/ui/date-picker.tsx
@@ -11,17 +11,31 @@ type DatePickerProps = Omit<
   React.ComponentProps<"button">,
   "children" | "defaultValue" | "onChange" | "value"
 > & {
+  /** Adds a "Clear" button to the popover, shown while a date is set, that calls `onChange` with `undefined`. */
   allowClear?: boolean;
+  /** Extra props for the {@link Calendar} in the popover. */
   calendarProps?: Omit<
     Extract<CalendarProps, { mode: "single" }>,
     "mode" | "onSelect" | "selected"
   >;
+  /**
+   * How the trigger shows the date, in the UI language. Defaults to `{
+   * dateStyle: "long" }`.
+   */
   dateFormat?: Intl.DateTimeFormatOptions;
+  /** Called with the picked date; the popover closes. */
   onChange?: (date: Date | undefined) => void;
+  /** Shown while empty. Defaults to the translated "Pick a date". */
   placeholder?: string;
+  /** The selected date. */
   value?: Date;
 };
 
+/**
+ * An outline button that opens a {@link Calendar} for one date. Its `onBlur`
+ * fires only while the popover is closed, so opening the calendar does not
+ * count as leaving the field.
+ */
 const DatePicker = ({
   value,
   onChange,
diff --git a/packages/vitnode/src/components/ui/date-range-picker.tsx b/packages/vitnode/src/components/ui/date-range-picker.tsx
index d0aa6001ed..6a5ceefa6c 100644
--- a/packages/vitnode/src/components/ui/date-range-picker.tsx
+++ b/packages/vitnode/src/components/ui/date-range-picker.tsx
@@ -9,11 +9,16 @@ import { Button } from "./button";
 import { Calendar, type DateRange, type Matcher } from "./calendar";
 import { Popover, PopoverContent, PopoverTrigger } from "./popover";
 
+/** A date range; both ends are inclusive. */
 export interface DateRangeValue {
   from: Date;
   to: Date;
 }
 
+/**
+ * A one-click range such as "Last 7 days". `key` is yours, `label` is shown as
+ * is (translate it first).
+ */
 export interface DateRangePreset<TKey extends string = string> {
   key: TKey;
   label: string;
@@ -23,14 +28,29 @@ type DateRangePickerProps<TKey extends string> = Omit<
   React.ComponentProps<"button">,
   "children" | "defaultValue" | "onChange" | "value"
 > & {
+  /**
+   * The preset the current `value` came from; the trigger shows its label
+   * instead of the dates.
+   */
   activePreset?: null | TKey;
+  /** Popover alignment to the trigger. Defaults to `"end"`. */
   align?: "center" | "end" | "start";
+  /** Days that cannot be picked. */
   disabledDays?: Matcher | Matcher[];
+  /** The latest month the calendar can show. */
   endMonth?: Date;
+  /** Called with the new range when the user applies it. */
   onChange: (range: DateRangeValue) => void;
+  /**
+   * Called with a preset's `key` when it is picked; the popover closes. Set
+   * `value` from it yourself.
+   */
   onPresetSelect?: (preset: TKey) => void;
+  /** Preset ranges listed beside the calendar. */
   presets?: readonly DateRangePreset<TKey>[];
+  /** The earliest month the calendar can show. */
   startMonth?: Date;
+  /** The applied range. */
   value: DateRangeValue;
 };
 
@@ -44,6 +64,12 @@ const dayCount = ({ from, to }: DateRangeValue) =>
       86_400_000,
   ) + 1;
 
+/**
+ * An outline button that opens a range calendar with optional presets. The user
+ * picks a draft range and confirms it with "Apply range" (or discards it with Cancel);
+ * two months show side by side, one on phones. Dates are formatted in the UI
+ * language.
+ */
 const DateRangePicker = <TKey extends string>({
   activePreset,
   align = "end",
diff --git a/packages/vitnode/src/components/ui/dialog.tsx b/packages/vitnode/src/components/ui/dialog.tsx
index 36d08237a1..2c7a17fb54 100644
--- a/packages/vitnode/src/components/ui/dialog.tsx
+++ b/packages/vitnode/src/components/ui/dialog.tsx
@@ -30,10 +30,19 @@ const DialogContext = React.createContext<{
   setOpenAlertDialogBeforeClose: () => {},
 });
 
+/**
+ * The surrounding {@link Dialog}'s state: `open`, `setOpen`, and the unsaved-
+ * changes flag (`isDirty`, `setIsDirty`) that forms inside it set.
+ */
 const useDialog = () => React.use(DialogContext);
 
 const alwaysRestoreFocus = () => true;
 
+/**
+ * A Base UI modal dialog, controlled (`open`) or uncontrolled. While a form
+ * inside it reports unsaved changes, closing asks for confirmation first;
+ * clicks on a toast do not count as clicking outside.
+ */
 function Dialog({
   onOpenChange,
   open: openProp,
@@ -135,6 +144,7 @@ function Dialog({
   );
 }
 
+/** The element that opens the dialog. */
 function DialogTrigger({ ...props }: DialogPrimitive.Trigger.Props) {
   return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />;
 }
@@ -143,6 +153,7 @@ function DialogPortal({ ...props }: DialogPrimitive.Portal.Props) {
   return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />;
 }
 
+/** An element that closes the dialog. */
 function DialogClose({ ...props }: DialogPrimitive.Close.Props) {
   return <DialogPrimitive.Close data-slot="dialog-close" {...props} />;
 }
@@ -164,6 +175,11 @@ function DialogOverlay({
   );
 }
 
+/**
+ * The dialog panel, rendered in a portal over a scrim. `showCloseButton`
+ * (default `true`) adds an icon close button labelled with the translated
+ * "Close".
+ */
 function DialogContent({
   className,
   children,
@@ -208,6 +224,7 @@ function DialogContent({
   );
 }
 
+/** Holds the title and description. */
 function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -218,6 +235,10 @@ function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/**
+ * Holds the dialog's actions. `showCloseButton` (default `false`) adds an
+ * outline "Close" button.
+ */
 function DialogFooter({
   className,
   showCloseButton = false,
@@ -248,6 +269,7 @@ function DialogFooter({
   );
 }
 
+/** The dialog's accessible title. */
 function DialogTitle({ className, ...props }: DialogPrimitive.Title.Props) {
   return (
     <DialogPrimitive.Title
@@ -261,6 +283,7 @@ function DialogTitle({ className, ...props }: DialogPrimitive.Title.Props) {
   );
 }
 
+/** The dialog's accessible description. */
 function DialogDescription({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/drawer.tsx b/packages/vitnode/src/components/ui/drawer.tsx
index fbf1bb4340..ad0e313eb1 100644
--- a/packages/vitnode/src/components/ui/drawer.tsx
+++ b/packages/vitnode/src/components/ui/drawer.tsx
@@ -24,6 +24,10 @@ const asChildProps = (
     ? { render: children }
     : { children };
 
+/**
+ * A Base UI drawer that slides in from an edge and can be swiped closed.
+ * `direction` is `"bottom"` (default), `"top"`, `"left"` or `"right"`.
+ */
 function Drawer({
   direction = "bottom",
   ...props
@@ -38,6 +42,10 @@ function Drawer({
   );
 }
 
+/**
+ * The element that opens the drawer. `asChild` renders your child element as
+ * the trigger instead of a button.
+ */
 function DrawerTrigger({
   asChild,
   children,
@@ -56,6 +64,10 @@ function DrawerPortal({ ...props }: DrawerPrimitive.Portal.Props) {
   return <DrawerPrimitive.Portal data-slot="drawer-portal" {...props} />;
 }
 
+/**
+ * An element that closes the drawer. `asChild` renders your child element
+ * instead of a button.
+ */
 function DrawerClose({
   asChild,
   children,
@@ -87,6 +99,10 @@ function DrawerOverlay({
   );
 }
 
+/**
+ * The drawer panel, rendered in a portal over a scrim, with a decorative drag
+ * handle.
+ */
 function DrawerContent({
   className,
   children,
@@ -119,6 +135,7 @@ function DrawerContent({
   );
 }
 
+/** Holds the title and description. */
 function DrawerHeader({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -132,6 +149,7 @@ function DrawerHeader({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** Holds the drawer's actions. */
 function DrawerFooter({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -142,6 +160,7 @@ function DrawerFooter({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** The drawer's accessible title. */
 function DrawerTitle({ className, ...props }: DrawerPrimitive.Title.Props) {
   return (
     <DrawerPrimitive.Title
@@ -152,6 +171,7 @@ function DrawerTitle({ className, ...props }: DrawerPrimitive.Title.Props) {
   );
 }
 
+/** The drawer's accessible description. */
 function DrawerDescription({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/dropdown-menu.tsx b/packages/vitnode/src/components/ui/dropdown-menu.tsx
index 9be2dccab1..6920520879 100644
--- a/packages/vitnode/src/components/ui/dropdown-menu.tsx
+++ b/packages/vitnode/src/components/ui/dropdown-menu.tsx
@@ -3,6 +3,7 @@ import { cn } from "cn";
 import { CheckIcon, ChevronRightIcon } from "lucide-react";
 import React from "react";
 
+/** A Base UI menu opened from a trigger button. */
 function DropdownMenu({
   ...props
 }: React.ComponentProps<typeof MenuPrimitive.Root>) {
@@ -15,12 +16,17 @@ function DropdownMenuPortal({
   return <MenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />;
 }
 
+/** The element that opens the menu. */
 function DropdownMenuTrigger({
   ...props
 }: React.ComponentProps<typeof MenuPrimitive.Trigger>) {
   return <MenuPrimitive.Trigger data-slot="dropdown-menu-trigger" {...props} />;
 }
 
+/**
+ * The menu popup, rendered in a portal; opens below the trigger, aligned to its
+ * start, by default.
+ */
 function DropdownMenuContent({
   className,
   side = "bottom",
@@ -63,6 +69,10 @@ function DropdownMenuGroup({
   return <MenuPrimitive.Group data-slot="dropdown-menu-group" {...props} />;
 }
 
+/**
+ * One action. `variant` is `"default"` or `"destructive"`; `inset` indents it
+ * to line up with items that have icons.
+ */
 function DropdownMenuItem({
   className,
   inset,
@@ -161,6 +171,10 @@ function DropdownMenuRadioItem({
   );
 }
 
+/**
+ * A non-interactive heading for a group of items; `inset` indents it like an
+ * item with an icon.
+ */
 function DropdownMenuLabel({
   className,
   inset,
@@ -181,6 +195,7 @@ function DropdownMenuLabel({
   );
 }
 
+/** A divider between items. */
 function DropdownMenuSeparator({
   className,
   ...props
@@ -194,6 +209,7 @@ function DropdownMenuSeparator({
   );
 }
 
+/** A keyboard shortcut hint at the item's end. */
 function DropdownMenuShortcut({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/dynamic-icon.tsx b/packages/vitnode/src/components/ui/dynamic-icon.tsx
index 1ae1d30250..73e49c63c5 100644
--- a/packages/vitnode/src/components/ui/dynamic-icon.tsx
+++ b/packages/vitnode/src/components/ui/dynamic-icon.tsx
@@ -9,14 +9,21 @@ import {
   subscribeLucideIcons,
 } from "./icon-registry";
 
+/** Props of {@link DynamicIcon}, passed to Lucide's `Icon`. */
 export interface DynamicIconProps {
   absoluteStrokeWidth?: boolean;
   className?: string;
+  /** The Lucide icon name in kebab case, e.g. `"newspaper"`. */
   name: string;
   size?: number | string;
   strokeWidth?: number | string;
 }
 
+/**
+ * A Lucide icon chosen by name at runtime, loaded on demand. Shows `fallback`
+ * (a blank, hidden placeholder by default) while it loads and `missing`
+ * (nothing by default) for an unknown name.
+ */
 export const DynamicIcon = ({
   className,
   fallback,
diff --git a/packages/vitnode/src/components/ui/editor-content.tsx b/packages/vitnode/src/components/ui/editor-content.tsx
index 01d77b814a..6d8b5fa9e0 100644
--- a/packages/vitnode/src/components/ui/editor-content.tsx
+++ b/packages/vitnode/src/components/ui/editor-content.tsx
@@ -2,6 +2,7 @@ import { useMemo } from "react";
 
 import { sanitizeEditorHtml } from "@/lib/sanitize-editor-html";
 
+/** Renders stored editor HTML with the editor's styles, sanitized first. */
 export const EditorContent = ({ content }: { content: string }) => {
   // Sanitizing parses the whole document, so it runs once per content, not
   // once per parent render.
diff --git a/packages/vitnode/src/components/ui/editor.tsx b/packages/vitnode/src/components/ui/editor.tsx
index 7d47aaa396..8984030df5 100644
--- a/packages/vitnode/src/components/ui/editor.tsx
+++ b/packages/vitnode/src/components/ui/editor.tsx
@@ -14,6 +14,10 @@ const subscribeNever = () => () => {};
 const getIsHydrated = () => true;
 const getIsHydratedOnServer = () => false;
 
+/**
+ * The Tiptap rich-text editor, loaded lazily and only in the browser; a
+ * skeleton shows during SSR and while it loads.
+ */
 export const Editor = (props: TipTapEditorProps) => {
   const isHydrated = React.useSyncExternalStore(
     subscribeNever,
diff --git a/packages/vitnode/src/components/ui/emoji-icon-picker.tsx b/packages/vitnode/src/components/ui/emoji-icon-picker.tsx
index 2dddb09c0f..4bdd2ac35a 100644
--- a/packages/vitnode/src/components/ui/emoji-icon-picker.tsx
+++ b/packages/vitnode/src/components/ui/emoji-icon-picker.tsx
@@ -23,6 +23,12 @@ const EmojiIconPickerPanel = React.lazy(async () =>
   })),
 );
 
+/**
+ * An outline button that opens a picker for an emoji or a Lucide icon. Calls
+ * `onChange` with the picked value and closes; `allowRemove` adds a remove
+ * button that calls it with `undefined`. Shows `placeholder`, else the
+ * translated "Pick an emoji or icon", while empty.
+ */
 export const EmojiIconPicker = ({
   allow = EMOJI_ICON_PICKER_KINDS,
   allowRemove,
diff --git a/packages/vitnode/src/components/ui/emoji-icon.tsx b/packages/vitnode/src/components/ui/emoji-icon.tsx
index 772c30d9f5..28b8d53376 100644
--- a/packages/vitnode/src/components/ui/emoji-icon.tsx
+++ b/packages/vitnode/src/components/ui/emoji-icon.tsx
@@ -4,6 +4,11 @@ import type { EmojiIconValue } from "@/lib/emoji-icon";
 
 import { DynamicIcon } from "./dynamic-icon";
 
+/**
+ * Renders an emoji-or-icon value at icon size: the emoji as text, or the Lucide
+ * icon via {@link DynamicIcon}. Renders nothing for an empty value. Decorative:
+ * the emoji is `aria-hidden`, and the icon is hidden by Lucide's default.
+ */
 export const EmojiIcon = ({
   className,
   value,
diff --git a/packages/vitnode/src/components/ui/emoji-picker.tsx b/packages/vitnode/src/components/ui/emoji-picker.tsx
index eb0526414b..6b21847c2d 100644
--- a/packages/vitnode/src/components/ui/emoji-picker.tsx
+++ b/packages/vitnode/src/components/ui/emoji-picker.tsx
@@ -8,6 +8,10 @@ export const EMOJI_PICKER_LIST_HEIGHT = 288;
 export const EMOJI_PICKER_INPUT_CLASS =
   "bg-muted text-foreground focus:ring-ring h-8 text-base focus:ring-2 md:text-sm";
 
+/**
+ * A searchable emoji grid. Calls `onSelect` with the picked emoji; `height` is
+ * the list height in pixels, default `288`.
+ */
 export const EmojiPicker = ({
   autoFocus,
   height = EMOJI_PICKER_LIST_HEIGHT,
diff --git a/packages/vitnode/src/components/ui/empty.tsx b/packages/vitnode/src/components/ui/empty.tsx
index 96f2f01b06..d125ed53d5 100644
--- a/packages/vitnode/src/components/ui/empty.tsx
+++ b/packages/vitnode/src/components/ui/empty.tsx
@@ -3,6 +3,7 @@ import { useRender } from "@base-ui/react/use-render";
 import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "cn";
 
+/** A centered empty state, e.g. for a list with no items. */
 function Empty({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -16,6 +17,7 @@ function Empty({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** Holds the media, title and description. */
 function EmptyHeader({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -41,6 +43,10 @@ const emptyMediaVariants = cva(
   },
 );
 
+/**
+ * An illustration or icon. `variant` is `"default"` or `"icon"`, which puts the
+ * icon in a muted tile; defaults to `"default"`.
+ */
 function EmptyMedia({
   className,
   variant = "default",
@@ -56,6 +62,7 @@ function EmptyMedia({
   );
 }
 
+/** The empty state's heading. */
 function EmptyTitle({
   className,
   render,
@@ -79,6 +86,7 @@ function EmptyTitle({
   });
 }
 
+/** Explains why it is empty or what to do next. */
 function EmptyDescription({
   className,
   ...props
@@ -95,6 +103,7 @@ function EmptyDescription({
   );
 }
 
+/** Actions, such as a create button. */
 function EmptyContent({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
diff --git a/packages/vitnode/src/components/ui/field.tsx b/packages/vitnode/src/components/ui/field.tsx
index c9c4292cad..9876c4ff20 100644
--- a/packages/vitnode/src/components/ui/field.tsx
+++ b/packages/vitnode/src/components/ui/field.tsx
@@ -5,6 +5,7 @@ import { useMemo } from "react";
 import { Label } from "@/components/ui/label";
 import { Separator } from "@/components/ui/separator";
 
+/** A `fieldset` grouping related fields. */
 function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
   return (
     <fieldset
@@ -18,6 +19,10 @@ function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
   );
 }
 
+/**
+ * The fieldset's caption. `variant` is `"legend"` (default) or `"label"`, which
+ * styles it like a field label.
+ */
 function FieldLegend({
   className,
   variant = "legend",
@@ -36,6 +41,7 @@ function FieldLegend({
   );
 }
 
+/** Stacks fields with consistent spacing. */
 function FieldGroup({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -67,6 +73,12 @@ const fieldVariants = cva(
   },
 );
 
+/**
+ * One form field (`role="group"`): its label, control, description and error.
+ * `orientation` is `"vertical"` (default), `"horizontal"` or `"responsive"`,
+ * which turns horizontal once the surrounding {@link FieldGroup} is at least
+ * 28rem (`@md` container) wide.
+ */
 function Field({
   className,
   orientation = "vertical",
@@ -83,6 +95,10 @@ function Field({
   );
 }
 
+/**
+ * Groups a field's label and description beside a control, e.g. next to a
+ * checkbox.
+ */
 function FieldContent({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -96,6 +112,7 @@ function FieldContent({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** The field's label, a {@link Label}. */
 function FieldLabel({
   className,
   ...props
@@ -113,6 +130,7 @@ function FieldLabel({
   );
 }
 
+/** A label-styled title for a field whose control has its own label. */
 function FieldTitle({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -126,6 +144,7 @@ function FieldTitle({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** Help text under the field. */
 function FieldDescription({ className, ...props }: React.ComponentProps<"p">) {
   return (
     <p
@@ -141,6 +160,7 @@ function FieldDescription({ className, ...props }: React.ComponentProps<"p">) {
   );
 }
 
+/** A divider between fields, with optional centered text such as "or". */
 function FieldSeparator({
   children,
   className,
@@ -171,6 +191,11 @@ function FieldSeparator({
   );
 }
 
+/**
+ * The field's error, with `role="alert"`. Shows `children`, or the messages of
+ * `errors` (duplicates removed; several become a list); renders nothing without
+ * either.
+ */
 function FieldError({
   className,
   children,
diff --git a/packages/vitnode/src/components/ui/form.tsx b/packages/vitnode/src/components/ui/form.tsx
index 44be7893ab..86389a7320 100644
--- a/packages/vitnode/src/components/ui/form.tsx
+++ b/packages/vitnode/src/components/ui/form.tsx
@@ -14,9 +14,15 @@ import { useBeforeUnload } from "../../hooks/use-before-unload";
 import { useDialog } from "./dialog";
 import { FieldError } from "./field";
 
+/**
+ * When a field's validation errors become visible: after blur (`onTouched`,
+ * `onBlur`), after the first change or blur (`onChange`, `all`) or only after a submit
+ * (`onSubmit`). After any submit attempt every error is shown.
+ */
 export type FormMode = "all" | "onBlur" | "onChange" | "onSubmit" | "onTouched";
 
 export interface FormSubmitMeta {
+  /** The `value` of the submit button that was clicked, if it has one. */
   intent?: string;
 }
 
@@ -24,10 +30,14 @@ export interface FormFieldChangeEvent {
   target: { checked?: boolean; type?: string; value?: unknown };
 }
 
+/** One field's value and handlers, as a field component receives them. */
 export interface FormFieldApi<TValue = unknown> {
   disabled?: boolean;
+  /** The field's key in the form values; also the base of its element ids. */
   name: string;
+  /** Marks the field blurred, which reveals its errors in the `onBlur` and `onTouched` modes. */
   onBlur: () => void;
+  /** Takes the new value, or an input's change event (a checkbox's `checked` is read). */
   onChange: (change: FormFieldChangeEvent | TValue) => void;
   value: TValue;
 }
@@ -164,6 +174,16 @@ const submitIntentOf = (
     : undefined;
 };
 
+/**
+ * Shows an error on one field after a submit - typically a server answer such
+ * as "this title is taken". It stays until the field's value changes, and the
+ * field is focused unless `shouldFocus` is `false`.
+ *
+ * @example
+ * ```ts
+ * if (res.status === 409) setFormFieldError(form, "title", t("errors.unique"));
+ * ```
+ */
 const setFormFieldError = (
   form: AnyFormApi,
   name: string,
@@ -193,6 +213,14 @@ const removeFormFieldValue = (
   void form.removeFieldValue(name as never, index);
 };
 
+/**
+ * The `<form>` behind `AutoForm`, for a form built on a TanStack Form instance
+ * directly. Prefer `AutoForm`.
+ *
+ * Unless `disableBeforeUnload` is set, closing or reloading the tab with
+ * unsaved changes asks for confirmation (browser `beforeunload`; in-app
+ * navigation is not blocked), and an enclosing `Dialog` asks before closing.
+ */
 function Form({
   children,
   className,
@@ -303,6 +331,11 @@ const useFormField = () => {
   };
 };
 
+/**
+ * Wraps a field's input (its single child element) and gives it the field's
+ * `id`, `aria-invalid` and `aria-describedby` (the description, plus the error
+ * message while one is shown). Use inside `FormField`.
+ */
 function FormControl({ children, ...props }: React.ComponentProps<"div">) {
   const { error, formItemId, formDescriptionId, formMessageId } =
     useFormField();
@@ -322,6 +355,10 @@ function FormControl({ children, ...props }: React.ComponentProps<"div">) {
   });
 }
 
+/**
+ * The field's error messages, once the form's `mode` reveals them; renders
+ * nothing otherwise. Duplicate messages are shown once. Use inside `FormField`.
+ */
 function FormMessage(props: React.ComponentProps<typeof FieldError>) {
   const { errors, formMessageId } = useFormField();
 
diff --git a/packages/vitnode/src/components/ui/frame.tsx b/packages/vitnode/src/components/ui/frame.tsx
index 4f6990bf89..21b9134ae7 100644
--- a/packages/vitnode/src/components/ui/frame.tsx
+++ b/packages/vitnode/src/components/ui/frame.tsx
@@ -3,6 +3,10 @@ import { useRender } from "@base-ui/react/use-render";
 import { cn } from "cn";
 import React from "react";
 
+/**
+ * A muted outer surface that frames one or more {@link FramePanel}s with a
+ * header and footer; renders a `div` (or your `render`).
+ */
 function Frame({
   className,
   render,
@@ -24,6 +28,7 @@ function Frame({
   });
 }
 
+/** The frame's top area for its title, description and action. */
 function FrameHeader({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -37,6 +42,7 @@ function FrameHeader({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** The frame's heading. */
 function FrameTitle({
   className,
   render,
@@ -58,6 +64,7 @@ function FrameTitle({
   });
 }
 
+/** Secondary text under the title. */
 function FrameDescription({ className, ...props }: React.ComponentProps<"p">) {
   return (
     <p
@@ -71,6 +78,7 @@ function FrameDescription({ className, ...props }: React.ComponentProps<"p">) {
   );
 }
 
+/** A control in the header's end corner. */
 function FrameAction({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -84,6 +92,10 @@ function FrameAction({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/**
+ * The raised card inside a {@link Frame}; its children are separated by
+ * borders, and `Item`s inside it lose their own borders.
+ */
 function FramePanel({
   className,
   render,
@@ -105,6 +117,7 @@ function FramePanel({
   });
 }
 
+/** The frame's bottom area. */
 function FrameFooter({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
diff --git a/packages/vitnode/src/components/ui/hover-card.tsx b/packages/vitnode/src/components/ui/hover-card.tsx
index e703178f54..5bae0356ba 100644
--- a/packages/vitnode/src/components/ui/hover-card.tsx
+++ b/packages/vitnode/src/components/ui/hover-card.tsx
@@ -2,12 +2,14 @@ import { PreviewCard as PreviewCardPrimitive } from "@base-ui/react/preview-card
 import { cn } from "cn";
 import React from "react";
 
+/** A Base UI preview card that opens while its trigger is hovered or focused. */
 function HoverCard({
   ...props
 }: React.ComponentProps<typeof PreviewCardPrimitive.Root>) {
   return <PreviewCardPrimitive.Root data-slot="hover-card" {...props} />;
 }
 
+/** The element that opens the card. */
 function HoverCardTrigger({
   ...props
 }: React.ComponentProps<typeof PreviewCardPrimitive.Trigger>) {
@@ -16,6 +18,10 @@ function HoverCardTrigger({
   );
 }
 
+/**
+ * The card popup, rendered in a portal; centered against the trigger by
+ * default.
+ */
 function HoverCardContent({
   className,
   side,
diff --git a/packages/vitnode/src/components/ui/icon-picker.tsx b/packages/vitnode/src/components/ui/icon-picker.tsx
index 11291fe347..c57aa06ae5 100644
--- a/packages/vitnode/src/components/ui/icon-picker.tsx
+++ b/packages/vitnode/src/components/ui/icon-picker.tsx
@@ -220,6 +220,11 @@ const IconGrid = ({
   );
 };
 
+/**
+ * A searchable, virtualized grid of Lucide icons with arrow-key navigation.
+ * Calls `onSelect` with the picked icon's name; `height` is the grid height in
+ * pixels, default `288`.
+ */
 export const IconPicker = ({
   autoFocus,
   height = 288,
diff --git a/packages/vitnode/src/components/ui/image-zoom.tsx b/packages/vitnode/src/components/ui/image-zoom.tsx
index ce7c24d362..1c0722abf4 100644
--- a/packages/vitnode/src/components/ui/image-zoom.tsx
+++ b/packages/vitnode/src/components/ui/image-zoom.tsx
@@ -30,6 +30,11 @@ const measureZoom = (image: HTMLImageElement) => {
   return { origin: zoomOrigin(thumb, target), target };
 };
 
+/**
+ * An image that opens full screen when clicked, zooming from its place on the
+ * page; drag it away or use the close button (translated "Close") to dismiss.
+ * `zoomSrc` is an optional larger image for the zoomed view; `alt` is required.
+ */
 function ImageZoom({
   alt,
   className,
diff --git a/packages/vitnode/src/components/ui/input-group.tsx b/packages/vitnode/src/components/ui/input-group.tsx
index 97531c419c..2ec4d6b690 100644
--- a/packages/vitnode/src/components/ui/input-group.tsx
+++ b/packages/vitnode/src/components/ui/input-group.tsx
@@ -6,6 +6,10 @@ import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Textarea } from "@/components/ui/textarea";
 
+/**
+ * Wraps an input with addons such as icons, text or buttons into one bordered
+ * control.
+ */
 function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -41,6 +45,11 @@ const inputGroupAddonVariants = cva(
   },
 );
 
+/**
+ * An icon, text or button beside or above the input. `align` is `"inline-
+ * start"` (default), `"inline-end"`, `"block-start"` or `"block-end"`. Clicking
+ * it focuses the input, except on a button.
+ */
 function InputGroupAddon({
   className,
   align = "inline-start",
@@ -82,6 +91,11 @@ const inputGroupButtonVariants = cva(
   },
 );
 
+/**
+ * A compact {@link Button} inside an {@link InputGroup}. `variant` defaults to
+ * `"ghost"` and `type` to `"button"`, so it never submits the form by
+ * accident. `size` is `xs` (default), `sm`, `icon-xs` or `icon-sm`.
+ */
 function InputGroupButton({
   className,
   type = "button",
@@ -103,6 +117,7 @@ function InputGroupButton({
   );
 }
 
+/** Static text inside the group, such as a unit or prefix. */
 function InputGroupText({ className, ...props }: React.ComponentProps<"span">) {
   return (
     <span
@@ -115,6 +130,7 @@ function InputGroupText({ className, ...props }: React.ComponentProps<"span">) {
   );
 }
 
+/** The group's {@link Input}, styled to sit flush inside it. */
 function InputGroupInput({
   className,
   ...props
@@ -131,6 +147,7 @@ function InputGroupInput({
   );
 }
 
+/** The group's textarea, styled to sit flush inside it. */
 function InputGroupTextarea({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/input-otp.tsx b/packages/vitnode/src/components/ui/input-otp.tsx
index 237f5b35f8..888251640f 100644
--- a/packages/vitnode/src/components/ui/input-otp.tsx
+++ b/packages/vitnode/src/components/ui/input-otp.tsx
@@ -15,6 +15,11 @@ import { MotionFeatures } from "@/components/motion-features";
 const slotValueHidden = { opacity: 0, y: 8, scale: 0.8 };
 const slotValueVisible = { opacity: 1, y: 0, scale: 1 };
 
+/**
+ * A one-time-code input from `input-otp`. Pass `maxLength`, and `pattern` such
+ * as `REGEXP_ONLY_DIGITS` (also exported from this module) to restrict
+ * characters.
+ */
 function InputOTP({
   className,
   containerClassName,
@@ -36,6 +41,7 @@ function InputOTP({
   );
 }
 
+/** A row of {@link InputOTPSlot}s. */
 function InputOTPGroup({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -46,6 +52,11 @@ function InputOTPGroup({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/**
+ * One character box of the code, for the slot at `index`; animates the typed
+ * character in (instantly under reduced motion) and shows a fake caret while
+ * active.
+ */
 function InputOTPSlot({
   index,
   className,
@@ -94,6 +105,7 @@ function InputOTPSlot({
   );
 }
 
+/** A decorative dash between groups, hidden from screen readers. */
 function InputOTPSeparator({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/input.tsx b/packages/vitnode/src/components/ui/input.tsx
index 023eec822d..b0a39fefc6 100644
--- a/packages/vitnode/src/components/ui/input.tsx
+++ b/packages/vitnode/src/components/ui/input.tsx
@@ -2,6 +2,7 @@ import { Input as InputPrimitive } from "@base-ui/react/input";
 import { cn } from "cn";
 import React from "react";
 
+/** A Base UI text input with VitNode styling. */
 function Input({ className, type, ...props }: React.ComponentProps<"input">) {
   return (
     <InputPrimitive
diff --git a/packages/vitnode/src/components/ui/item.tsx b/packages/vitnode/src/components/ui/item.tsx
index 9fa1b240be..2f6dbb58d0 100644
--- a/packages/vitnode/src/components/ui/item.tsx
+++ b/packages/vitnode/src/components/ui/item.tsx
@@ -6,6 +6,7 @@ import React from "react";
 
 import { Separator } from "@/components/ui/separator";
 
+/** A list of {@link Item}s (`role="list"`). */
 function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -20,6 +21,7 @@ function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** A divider between items. */
 function ItemSeparator({
   className,
   ...props
@@ -56,6 +58,12 @@ const itemVariants = cva(
   },
 );
 
+/**
+ * A row for one thing in a list, such as a setting, file or person; renders a
+ * `div` (or your `render`, e.g. a link). `variant` is `"default"`, `"outline"`
+ * or `"muted"`; `size` is `"default"`, `"sm"` or `"xs"`; both default to
+ * `"default"`.
+ */
 function Item({
   className,
   variant = "default",
@@ -98,6 +106,10 @@ const itemMediaVariants = cva(
   },
 );
 
+/**
+ * The item's leading icon or image. `variant` is `"default"`, `"icon"`,
+ * `"tile"` (a muted square) or `"image"`; defaults to `"default"`.
+ */
 function ItemMedia({
   className,
   variant = "default",
@@ -113,6 +125,7 @@ function ItemMedia({
   );
 }
 
+/** Holds the title and description. */
 function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -126,6 +139,7 @@ function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** The item's main line. */
 function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -139,6 +153,7 @@ function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** Secondary text under the title. */
 function ItemDescription({ className, ...props }: React.ComponentProps<"p">) {
   return (
     <p
@@ -152,6 +167,7 @@ function ItemDescription({ className, ...props }: React.ComponentProps<"p">) {
   );
 }
 
+/** Buttons or controls at the item's end. */
 function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -162,6 +178,7 @@ function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** A full-width line above the item's main row. */
 function ItemHeader({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -175,6 +192,7 @@ function ItemHeader({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** A full-width line below the item's main row. */
 function ItemFooter({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
diff --git a/packages/vitnode/src/components/ui/kbd.tsx b/packages/vitnode/src/components/ui/kbd.tsx
index 16a95f7e96..82cfb2a706 100644
--- a/packages/vitnode/src/components/ui/kbd.tsx
+++ b/packages/vitnode/src/components/ui/kbd.tsx
@@ -1,5 +1,6 @@
 import { cn } from "cn";
 
+/** A keyboard key, e.g. `Ctrl` or `K`, rendered as `kbd`. */
 function Kbd({ className, ...props }: React.ComponentProps<"kbd">) {
   return (
     <kbd
@@ -13,6 +14,7 @@ function Kbd({ className, ...props }: React.ComponentProps<"kbd">) {
   );
 }
 
+/** Groups keys of one shortcut, e.g. `Ctrl` + `K`. */
 function KbdGroup({ className, ...props }: React.ComponentProps<"kbd">) {
   return (
     <kbd
diff --git a/packages/vitnode/src/components/ui/label.tsx b/packages/vitnode/src/components/ui/label.tsx
index c4afcdf25d..f8c87ba8c1 100644
--- a/packages/vitnode/src/components/ui/label.tsx
+++ b/packages/vitnode/src/components/ui/label.tsx
@@ -1,6 +1,7 @@
 import { cn } from "cn";
 import React from "react";
 
+/** A styled `label` element; associate it with its control via `htmlFor`. */
 function Label({ className, ...props }: React.ComponentProps<"label">) {
   return (
     <label
diff --git a/packages/vitnode/src/components/ui/marker.tsx b/packages/vitnode/src/components/ui/marker.tsx
index defc1e7c19..c41f8be975 100644
--- a/packages/vitnode/src/components/ui/marker.tsx
+++ b/packages/vitnode/src/components/ui/marker.tsx
@@ -7,6 +7,13 @@ import * as React from "react";
 
 import { markerVariants } from "./marker-variants";
 
+/**
+ * A short inline note row, e.g. "Edited" or a divider label in a feed.
+ *
+ * `variant`: `default`, `separator` (lines either side) or `border` (bottom
+ * border); defaults to `default`. `tone`: `neutral` (default), `info`,
+ * `success`, `warning` or `destructive`. Pass `render` to swap the element.
+ */
 function Marker({
   className,
   variant = "default",
@@ -31,6 +38,7 @@ function Marker({
   });
 }
 
+/** The leading icon of a {@link Marker}, sized to `size-4`. */
 function MarkerIcon({ className, ...props }: React.ComponentProps<"span">) {
   return (
     <span
@@ -45,6 +53,7 @@ function MarkerIcon({ className, ...props }: React.ComponentProps<"span">) {
   );
 }
 
+/** The text of a {@link Marker}; links inside it are underlined. */
 function MarkerContent({ className, ...props }: React.ComponentProps<"span">) {
   return (
     <span
diff --git a/packages/vitnode/src/components/ui/menubar.tsx b/packages/vitnode/src/components/ui/menubar.tsx
index 72bee061b8..e989c85cfd 100644
--- a/packages/vitnode/src/components/ui/menubar.tsx
+++ b/packages/vitnode/src/components/ui/menubar.tsx
@@ -4,6 +4,7 @@ import { cn } from "cn";
 import { CheckIcon, ChevronRightIcon } from "lucide-react";
 import React from "react";
 
+/** A horizontal bar of menus, like a desktop app's File / Edit / View. */
 function Menubar({
   className,
   ...props
@@ -20,6 +21,7 @@ function Menubar({
   );
 }
 
+/** One menu in a {@link Menubar}: wraps its trigger and content. */
 function MenubarMenu({
   ...props
 }: React.ComponentProps<typeof MenuPrimitive.Root>) {
@@ -46,6 +48,7 @@ function MenubarRadioGroup({
   );
 }
 
+/** The button that opens a {@link MenubarMenu}. */
 function MenubarTrigger({
   className,
   ...props
@@ -62,6 +65,9 @@ function MenubarTrigger({
   );
 }
 
+/**
+ * The menu's popup, portaled. Opens below the trigger, start-aligned, 8px away.
+ */
 function MenubarContent({
   className,
   align = "start",
@@ -98,6 +104,10 @@ function MenubarContent({
   );
 }
 
+/**
+ * A menu entry. `variant="destructive"` colors it for a dangerous action;
+ * `inset` indents it to line up with checkbox and radio items.
+ */
 function MenubarItem({
   className,
   inset,
@@ -205,6 +215,7 @@ function MenubarLabel({
   );
 }
 
+/** A line between groups of menu items. */
 function MenubarSeparator({
   className,
   ...props
@@ -218,6 +229,7 @@ function MenubarSeparator({
   );
 }
 
+/** A keyboard shortcut hint at the end of a {@link MenubarItem}. */
 function MenubarShortcut({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/message.tsx b/packages/vitnode/src/components/ui/message.tsx
index 79a348c994..fecb05fdc5 100644
--- a/packages/vitnode/src/components/ui/message.tsx
+++ b/packages/vitnode/src/components/ui/message.tsx
@@ -1,6 +1,7 @@
 import { cn } from "cn";
 import * as React from "react";
 
+/** A vertical stack of chat {@link Message}s. */
 function MessageGroup({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -11,6 +12,10 @@ function MessageGroup({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/**
+ * One chat message: avatar plus content. `align="end"` (default `"start"`)
+ * mirrors it for the current user's own messages.
+ */
 function Message({
   className,
   align = "start",
@@ -29,6 +34,7 @@ function Message({
   );
 }
 
+/** The author's avatar beside a {@link Message}. */
 function MessageAvatar({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -42,6 +48,7 @@ function MessageAvatar({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** The bubbles or body of a {@link Message}. */
 function MessageContent({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -55,6 +62,7 @@ function MessageContent({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** Small muted line above the content, e.g. the author's name. */
 function MessageHeader({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -68,6 +76,9 @@ function MessageHeader({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/**
+ * Small muted line below the content, e.g. the time; aligned with the message.
+ */
 function MessageFooter({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
diff --git a/packages/vitnode/src/components/ui/number-field.tsx b/packages/vitnode/src/components/ui/number-field.tsx
index fa95a1477e..9f23e11d84 100644
--- a/packages/vitnode/src/components/ui/number-field.tsx
+++ b/packages/vitnode/src/components/ui/number-field.tsx
@@ -9,6 +9,10 @@ type NumberFieldSize = "default" | "lg" | "sm";
 const stepperButtonClassName =
   "text-muted-foreground hover:bg-muted hover:text-foreground relative flex shrink-0 cursor-pointer items-center justify-center px-2.5 transition-colors outline-none select-none active:bg-muted disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:bg-transparent aria-disabled:cursor-not-allowed aria-disabled:opacity-50 aria-disabled:hover:bg-transparent group-data-[size=lg]/number-field:px-3 group-data-[size=sm]/number-field:px-2 pointer-coarse:after:absolute pointer-coarse:after:top-1/2 pointer-coarse:after:left-1/2 pointer-coarse:after:size-11 pointer-coarse:after:-translate-1/2 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg]:transition-transform [&_svg]:duration-150 [&_svg]:ease-out active:[&_svg]:scale-90 motion-reduce:[&_svg]:transition-none [&_svg:not([class*='size-'])]:size-4 group-data-[size=sm]/number-field:[&_svg:not([class*='size-'])]:size-3.5";
 
+/**
+ * A numeric input with stepper buttons (Base UI `NumberField`).
+ * `size`: `sm`, `default` (default) or `lg`, applied to every part inside.
+ */
 function NumberField({
   className,
   locale,
@@ -31,6 +35,7 @@ function NumberField({
   );
 }
 
+/** The bordered box holding the input and the stepper buttons. */
 function NumberFieldGroup({
   className,
   ...props
@@ -47,6 +52,7 @@ function NumberFieldGroup({
   );
 }
 
+/** The number input itself, centered with tabular figures. */
 function NumberFieldInput({
   className,
   ...props
@@ -63,6 +69,9 @@ function NumberFieldInput({
   );
 }
 
+/**
+ * The minus button, with a translated `aria-label`. Defaults to a minus icon.
+ */
 function NumberFieldDecrement({
   children,
   className,
@@ -82,6 +91,7 @@ function NumberFieldDecrement({
   );
 }
 
+/** The plus button, with a translated `aria-label`. Defaults to a plus icon. */
 function NumberFieldIncrement({
   children,
   className,
diff --git a/packages/vitnode/src/components/ui/page-title.tsx b/packages/vitnode/src/components/ui/page-title.tsx
index 778afc70b9..247e5585c9 100644
--- a/packages/vitnode/src/components/ui/page-title.tsx
+++ b/packages/vitnode/src/components/ui/page-title.tsx
@@ -29,6 +29,11 @@ interface PageTitleBaseProps {
 export type PageTitleProps = PageTitleBaseProps &
   (PageTitleH1Props | PageTitleH2Props);
 
+/**
+ * A page heading row: optional back link and subtitle, an `h1` (or `h2`),
+ * an optional `desc`, and action buttons (`children`) on the right, stacked
+ * on mobile. Pass exactly one of `h1` or `h2`.
+ */
 export const PageTitle = ({
   back,
   children,
diff --git a/packages/vitnode/src/components/ui/pagination.tsx b/packages/vitnode/src/components/ui/pagination.tsx
index 4be21c4aec..f7485b8327 100644
--- a/packages/vitnode/src/components/ui/pagination.tsx
+++ b/packages/vitnode/src/components/ui/pagination.tsx
@@ -11,6 +11,7 @@ import { useTranslations } from "use-intl";
 
 import { buttonVariants } from "@/components/ui/button";
 
+/** A `<nav>` for page links, with a translated `aria-label`. */
 function Pagination({ className, ...props }: React.ComponentProps<"nav">) {
   const t = useTranslations("core.global");
 
@@ -25,6 +26,7 @@ function Pagination({ className, ...props }: React.ComponentProps<"nav">) {
   );
 }
 
+/** The list of {@link PaginationItem}s. */
 function PaginationContent({
   className,
   ...props
@@ -38,6 +40,7 @@ function PaginationContent({
   );
 }
 
+/** One entry in the pagination list. */
 function PaginationItem({ ...props }: React.ComponentProps<"li">) {
   return <li data-slot="pagination-item" {...props} />;
 }
@@ -47,6 +50,10 @@ type PaginationLinkProps = Pick<VariantProps<typeof buttonVariants>, "size"> &
     isActive?: boolean;
   };
 
+/**
+ * A page link. `isActive` marks the current page (`aria-current="page"`,
+ * outline style); `size` defaults to `icon`.
+ */
 function PaginationLink({
   className,
   isActive,
@@ -68,6 +75,10 @@ function PaginationLink({
   );
 }
 
+/**
+ * A link to the previous page. The label hides on small screens; `text`
+ * replaces the translated "Previous".
+ */
 function PaginationPrevious({
   className,
   text,
@@ -88,6 +99,10 @@ function PaginationPrevious({
   );
 }
 
+/**
+ * A link to the next page. The label hides on small screens; `text` replaces
+ * the translated "Next".
+ */
 function PaginationNext({
   className,
   text,
@@ -108,6 +123,7 @@ function PaginationNext({
   );
 }
 
+/** A `…` gap between page links, with a translated screen-reader label. */
 function PaginationEllipsis({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/popover.tsx b/packages/vitnode/src/components/ui/popover.tsx
index 943bad1142..d17bfc3776 100644
--- a/packages/vitnode/src/components/ui/popover.tsx
+++ b/packages/vitnode/src/components/ui/popover.tsx
@@ -2,18 +2,23 @@ import { Popover as PopoverPrimitive } from "@base-ui/react/popover";
 import { cn } from "cn";
 import React from "react";
 
+/** A non-modal floating panel anchored to its trigger (Base UI `Popover`). */
 function Popover({
   ...props
 }: React.ComponentProps<typeof PopoverPrimitive.Root>) {
   return <PopoverPrimitive.Root data-slot="popover" {...props} />;
 }
 
+/** The element that opens the {@link Popover}. */
 function PopoverTrigger({
   ...props
 }: React.ComponentProps<typeof PopoverPrimitive.Trigger>) {
   return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />;
 }
 
+/**
+ * The popover's panel, portaled. Defaults: below the trigger, centered, 4px away.
+ */
 function PopoverContent({
   className,
   side,
@@ -50,6 +55,7 @@ function PopoverContent({
   );
 }
 
+/** Groups a {@link PopoverTitle} and {@link PopoverDescription}. */
 function PopoverHeader({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -60,6 +66,7 @@ function PopoverHeader({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** The popover's accessible title. */
 function PopoverTitle({
   className,
   ...props
@@ -73,6 +80,7 @@ function PopoverTitle({
   );
 }
 
+/** The popover's accessible description, muted. */
 function PopoverDescription({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/progress.tsx b/packages/vitnode/src/components/ui/progress.tsx
index 9fc0cb1b30..a7e1d9a33a 100644
--- a/packages/vitnode/src/components/ui/progress.tsx
+++ b/packages/vitnode/src/components/ui/progress.tsx
@@ -34,6 +34,11 @@ const IndeterminateSweep = () => {
   );
 };
 
+/**
+ * A progress bar. `value` within `min` (0) and `max` (100); a `null` value
+ * shows an indeterminate sweep. Put {@link ProgressLabel} and
+ * {@link ProgressValue} inside as `children`; `indicatorClassName` styles the bar.
+ */
 function Progress({
   className,
   children,
@@ -89,6 +94,7 @@ function Progress({
   );
 }
 
+/** The bar's accessible label, shown above it. */
 function ProgressLabel({
   className,
   ...props
@@ -102,6 +108,7 @@ function ProgressLabel({
   );
 }
 
+/** The formatted value, shown above the bar at the end. */
 function ProgressValue({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/radio-group.tsx b/packages/vitnode/src/components/ui/radio-group.tsx
index 2d26401c60..4569d8b489 100644
--- a/packages/vitnode/src/components/ui/radio-group.tsx
+++ b/packages/vitnode/src/components/ui/radio-group.tsx
@@ -3,6 +3,7 @@ import { RadioGroup as RadioGroupPrimitive } from "@base-ui/react/radio-group";
 import { cn } from "cn";
 import React from "react";
 
+/** A group of radio buttons (Base UI `RadioGroup`). */
 function RadioGroup({ className, ...props }: RadioGroupPrimitive.Props) {
   return (
     <RadioGroupPrimitive
@@ -13,6 +14,7 @@ function RadioGroup({ className, ...props }: RadioGroupPrimitive.Props) {
   );
 }
 
+/** One radio button in a {@link RadioGroup}. */
 function RadioGroupItem({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/resizable.tsx b/packages/vitnode/src/components/ui/resizable.tsx
index b5d0746972..289ba6c3af 100644
--- a/packages/vitnode/src/components/ui/resizable.tsx
+++ b/packages/vitnode/src/components/ui/resizable.tsx
@@ -1,6 +1,10 @@
 import { cn } from "cn";
 import * as ResizablePrimitive from "react-resizable-panels";
 
+/**
+ * A row or column of panels the user can resize by dragging
+ * (`react-resizable-panels`).
+ */
 function ResizablePanelGroup({
   className,
   ...props
@@ -17,10 +21,12 @@ function ResizablePanelGroup({
   );
 }
 
+/** One panel in a {@link ResizablePanelGroup}. */
 function ResizablePanel({ ...props }: ResizablePrimitive.PanelProps) {
   return <ResizablePrimitive.Panel data-slot="resizable-panel" {...props} />;
 }
 
+/** The drag handle between two panels. `withHandle` shows a visible grip. */
 function ResizableHandle({
   withHandle,
   className,
diff --git a/packages/vitnode/src/components/ui/scroll-area.tsx b/packages/vitnode/src/components/ui/scroll-area.tsx
index 93256d1a45..4ef7c174f7 100644
--- a/packages/vitnode/src/components/ui/scroll-area.tsx
+++ b/packages/vitnode/src/components/ui/scroll-area.tsx
@@ -2,6 +2,10 @@ import { ScrollArea as ScrollAreaPrimitive } from "@base-ui/react/scroll-area";
 import { cn } from "cn";
 import React from "react";
 
+/**
+ * A scroll container with a styled vertical scrollbar; content fades out at
+ * the scrolled edges.
+ */
 function ScrollArea({
   className,
   children,
diff --git a/packages/vitnode/src/components/ui/select.tsx b/packages/vitnode/src/components/ui/select.tsx
index 59680d537c..ae9600e3c5 100644
--- a/packages/vitnode/src/components/ui/select.tsx
+++ b/packages/vitnode/src/components/ui/select.tsx
@@ -3,6 +3,7 @@ import { cn } from "cn";
 import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react";
 import React from "react";
 
+/** A dropdown to pick one option (Base UI `Select`). */
 function Select({
   ...props
 }: React.ComponentProps<typeof SelectPrimitive.Root>) {
@@ -22,12 +23,14 @@ function SelectGroup({
   );
 }
 
+/** Shows the selected option inside the trigger. */
 function SelectValue({
   ...props
 }: React.ComponentProps<typeof SelectPrimitive.Value>) {
   return <SelectPrimitive.Value data-slot="select-value" {...props} />;
 }
 
+/** The button that opens the {@link Select}. `size`: `default` or `sm`. */
 function SelectTrigger({
   className,
   size = "default",
@@ -56,6 +59,10 @@ function SelectTrigger({
   );
 }
 
+/**
+ * The options popup, portaled. Defaults: below the trigger, start-aligned,
+ * 4px away, not aligned over the selected item (`alignItemWithTrigger: false`).
+ */
 function SelectContent({
   className,
   children,
@@ -117,6 +124,7 @@ function SelectLabel({
   );
 }
 
+/** One option, with a check mark when selected. */
 function SelectItem({
   className,
   children,
diff --git a/packages/vitnode/src/components/ui/separator.tsx b/packages/vitnode/src/components/ui/separator.tsx
index 23cde3c20a..dece8e40c6 100644
--- a/packages/vitnode/src/components/ui/separator.tsx
+++ b/packages/vitnode/src/components/ui/separator.tsx
@@ -2,6 +2,7 @@ import { Separator as SeparatorPrimitive } from "@base-ui/react/separator";
 import { cn } from "cn";
 import React from "react";
 
+/** A thin divider line; `orientation` defaults to `horizontal`. */
 function Separator({
   className,
   orientation = "horizontal",
diff --git a/packages/vitnode/src/components/ui/sheet.tsx b/packages/vitnode/src/components/ui/sheet.tsx
index 6b40370529..14f738ba23 100644
--- a/packages/vitnode/src/components/ui/sheet.tsx
+++ b/packages/vitnode/src/components/ui/sheet.tsx
@@ -7,14 +7,20 @@ import { useTranslations } from "use-intl";
 import { Button } from "@/components/ui/button";
 import { modalScrimClassName } from "@/components/ui/modal-scrim";
 
+/**
+ * A panel that slides in from a screen edge (Base UI `Dialog`). Use it for
+ * short settings; see `AutoFormSheetFooter` for a form footer.
+ */
 function Sheet({ ...props }: SheetPrimitive.Root.Props) {
   return <SheetPrimitive.Root data-slot="sheet" {...props} />;
 }
 
+/** The element that opens the {@link Sheet}. */
 function SheetTrigger({ ...props }: SheetPrimitive.Trigger.Props) {
   return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />;
 }
 
+/** A control that closes the {@link Sheet}. */
 function SheetClose({ ...props }: SheetPrimitive.Close.Props) {
   return <SheetPrimitive.Close data-slot="sheet-close" {...props} />;
 }
@@ -37,6 +43,11 @@ function SheetOverlay({ className, ...props }: SheetPrimitive.Backdrop.Props) {
   );
 }
 
+/**
+ * The sheet's panel with a backdrop. `side`: `right` (default), `left`, `top`
+ * or `bottom`. `showCloseButton` (default `true`) adds a close button with a
+ * translated label; `keepMounted` keeps it in the DOM while closed.
+ */
 function SheetContent({
   className,
   children,
@@ -89,6 +100,7 @@ function SheetContent({
   );
 }
 
+/** The top area for the title and description. */
 function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -99,6 +111,7 @@ function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** The bottom area for actions, pinned to the end of the sheet. */
 function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -109,6 +122,7 @@ function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** The sheet's accessible title. */
 function SheetTitle({ className, ...props }: SheetPrimitive.Title.Props) {
   return (
     <SheetPrimitive.Title
@@ -119,6 +133,7 @@ function SheetTitle({ className, ...props }: SheetPrimitive.Title.Props) {
   );
 }
 
+/** The sheet's accessible description, muted. */
 function SheetDescription({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/skeleton.tsx b/packages/vitnode/src/components/ui/skeleton.tsx
index 0190115650..307c81a4b5 100644
--- a/packages/vitnode/src/components/ui/skeleton.tsx
+++ b/packages/vitnode/src/components/ui/skeleton.tsx
@@ -1,5 +1,8 @@
 import { cn } from "cn";
 
+/**
+ * A pulsing placeholder block for loading content; hidden from screen readers.
+ */
 function Skeleton({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
diff --git a/packages/vitnode/src/components/ui/sliding-number.tsx b/packages/vitnode/src/components/ui/sliding-number.tsx
index 71755ee162..db401e0970 100644
--- a/packages/vitnode/src/components/ui/sliding-number.tsx
+++ b/packages/vitnode/src/components/ui/sliding-number.tsx
@@ -74,6 +74,11 @@ const DigitRoller = ({
   );
 };
 
+/**
+ * A number whose digits roll to the new value when `value` changes. Pass an
+ * `Intl.NumberFormat` as `formatter` for grouping, decimals or units. Jumps
+ * without animation when the user prefers reduced motion.
+ */
 function SlidingNumber({
   className,
   formatter,
diff --git a/packages/vitnode/src/components/ui/sonner.tsx b/packages/vitnode/src/components/ui/sonner.tsx
index b30bc6c2e8..5af74a6543 100644
--- a/packages/vitnode/src/components/ui/sonner.tsx
+++ b/packages/vitnode/src/components/ui/sonner.tsx
@@ -99,6 +99,10 @@ const Toaster = ({
   );
 };
 
+/**
+ * An avatar for a toast; without `src` it shows `fallback` or the first
+ * letter of `alt`.
+ */
 const ToastAvatar = ({
   alt,
   fallback,
@@ -122,6 +126,11 @@ interface ToastMessageAction {
   variant?: "default" | "outline" | "secondary";
 }
 
+/**
+ * Rich toast content: an avatar, a title with an optional `time`, an
+ * optional `description`, and action buttons. Render it with `toast.custom()`
+ * from `sonner`.
+ */
 const ToastMessage = ({
   actions = [],
   avatar,
diff --git a/packages/vitnode/src/components/ui/spinner.tsx b/packages/vitnode/src/components/ui/spinner.tsx
index d15812192d..db9a326304 100644
--- a/packages/vitnode/src/components/ui/spinner.tsx
+++ b/packages/vitnode/src/components/ui/spinner.tsx
@@ -36,6 +36,11 @@ const TranslatedSpinner = (props: SpinnerProps) => {
   return <SpinnerIcon aria-label={t("loading")} {...props} />;
 };
 
+/**
+ * An animated loading icon with `role="status"`. Gets a translated
+ * "Loading..." label unless you pass `aria-label` or `aria-hidden`. `size`: `sm`,
+ * `default` (default), `lg` or `xl`.
+ */
 function Spinner(props: SpinnerProps) {
   const isLabelled =
     props["aria-label"] !== undefined ||
diff --git a/packages/vitnode/src/components/ui/switch.tsx b/packages/vitnode/src/components/ui/switch.tsx
index 4ae0a653c8..cc0af3edf1 100644
--- a/packages/vitnode/src/components/ui/switch.tsx
+++ b/packages/vitnode/src/components/ui/switch.tsx
@@ -8,6 +8,10 @@ import { MotionFeatures } from "@/components/motion-features";
 
 const THUMB_SPRING = { type: "spring", duration: 0.3, bounce: 0 } as const;
 
+/**
+ * An on/off toggle (Base UI `Switch`) with an animated thumb. `size`:
+ * `default` or `sm`.
+ */
 function Switch({
   className,
   size = "default",
diff --git a/packages/vitnode/src/components/ui/tabs.tsx b/packages/vitnode/src/components/ui/tabs.tsx
index 90f5d8be0e..27330a5564 100644
--- a/packages/vitnode/src/components/ui/tabs.tsx
+++ b/packages/vitnode/src/components/ui/tabs.tsx
@@ -3,6 +3,7 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "cn";
 import React from "react";
 
+/** Tabbed content (Base UI `Tabs`); `orientation` defaults to `horizontal`. */
 function Tabs({
   className,
   orientation = "horizontal",
@@ -57,6 +58,10 @@ function TabsIndicator({
   );
 }
 
+/**
+ * The row of tab buttons with an animated indicator. `variant`: `default`
+ * (pill on a muted background) or `line` (underline).
+ */
 function TabsList({
   children,
   className,
@@ -77,6 +82,7 @@ function TabsList({
   );
 }
 
+/** One tab button. */
 function TabsTrigger({
   className,
   ...props
@@ -94,6 +100,10 @@ function TabsTrigger({
   );
 }
 
+/**
+ * Wraps the {@link TabsContent} panels and animates the height between tabs.
+ * Optional; without it, panels change height instantly.
+ */
 function TabsPanels({
   children,
   className,
@@ -156,6 +166,10 @@ function TabsPanels({
   );
 }
 
+/**
+ * One tab's panel. Slides in from the side it was activated from, unless the
+ * user prefers reduced motion.
+ */
 function TabsContent({
   className,
   ...props
diff --git a/packages/vitnode/src/components/ui/textarea.tsx b/packages/vitnode/src/components/ui/textarea.tsx
index eede770cb7..1ed91bb7cf 100644
--- a/packages/vitnode/src/components/ui/textarea.tsx
+++ b/packages/vitnode/src/components/ui/textarea.tsx
@@ -2,6 +2,9 @@ import type * as React from "react";
 
 import { cn } from "cn";
 
+/**
+ * A multi-line text input that grows with its content (`field-sizing: content`).
+ */
 function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
   return (
     <textarea
diff --git a/packages/vitnode/src/components/ui/toggle-group.tsx b/packages/vitnode/src/components/ui/toggle-group.tsx
index f61e4257c7..2a14621728 100644
--- a/packages/vitnode/src/components/ui/toggle-group.tsx
+++ b/packages/vitnode/src/components/ui/toggle-group.tsx
@@ -38,6 +38,12 @@ const SelectionIndicator = ({ layoutId }: { layoutId: string }) => {
   );
 };
 
+/**
+ * A set of {@link ToggleGroupItem}s. Single-select by default, with an
+ * animated selection indicator; `multiple` allows several. `variant` and
+ * `size` apply to every item; `spacing` is the gap in spacing units (`0`, the
+ * default, joins the items into one control).
+ */
 function ToggleGroup({
   className,
   variant,
@@ -93,6 +99,10 @@ function ToggleGroup({
   );
 }
 
+/**
+ * One option in a {@link ToggleGroup}; the group's `variant` and `size` win
+ * over its own.
+ */
 function ToggleGroupItem({
   className,
   children,
diff --git a/packages/vitnode/src/components/ui/toggle.tsx b/packages/vitnode/src/components/ui/toggle.tsx
index 7ad1c950ab..89b88ef036 100644
--- a/packages/vitnode/src/components/ui/toggle.tsx
+++ b/packages/vitnode/src/components/ui/toggle.tsx
@@ -25,6 +25,10 @@ const toggleVariants = cva(
   },
 );
 
+/**
+ * A two-state button (Base UI `Toggle`). `variant`: `default` or `outline`;
+ * `size`: `sm`, `default` or `lg`.
+ */
 function Toggle({
   className,
   variant = "default",
diff --git a/packages/vitnode/src/components/ui/tooltip.tsx b/packages/vitnode/src/components/ui/tooltip.tsx
index f207f19df9..6e22d89363 100644
--- a/packages/vitnode/src/components/ui/tooltip.tsx
+++ b/packages/vitnode/src/components/ui/tooltip.tsx
@@ -21,10 +21,15 @@ function TooltipProvider({
   );
 }
 
+/**
+ * A tooltip (Base UI `Tooltip`). Opens after 200ms unless a
+ * `TooltipProvider` or the trigger sets another `delay`.
+ */
 function Tooltip({ ...props }: TooltipPrimitive.Root.Props) {
   return <TooltipPrimitive.Root data-slot="tooltip" {...props} />;
 }
 
+/** The element that shows the {@link Tooltip} on hover or focus. */
 function TooltipTrigger({ delay, ...props }: TooltipPrimitive.Trigger.Props) {
   const providerDelay = React.use(TooltipDelayContext);
 
@@ -37,6 +42,10 @@ function TooltipTrigger({ delay, ...props }: TooltipPrimitive.Trigger.Props) {
   );
 }
 
+/**
+ * The tooltip bubble with an arrow, portaled. Defaults: above the trigger,
+ * centered, 8px away.
+ */
 function TooltipContent({
   className,
   side = "top",
@@ -75,6 +84,10 @@ function TooltipContent({
   );
 }
 
+/**
+ * A tooltip in one element: wraps `children` (the trigger) and shows `text`.
+ * Inside a {@link TooltipGroup} with no extra props, it joins the group.
+ */
 function TooltipWithContent({
   children,
   text,
@@ -107,6 +120,11 @@ const TooltipGroupContext = React.createContext<null | TooltipGroupHandle>(
 const GLIDE =
   "duration-300 ease-fluid data-instant:transition-none motion-reduce:transition-none";
 
+/**
+ * Shares one tooltip between many triggers, so it glides from one to the next
+ * instead of closing and reopening (e.g. a toolbar). Positioning defaults:
+ * above, centered, 8px away.
+ */
 function TooltipGroup({
   children,
   side = "top",
@@ -173,6 +191,10 @@ function useIsInTooltipGroup() {
   return React.use(TooltipGroupContext) !== null;
 }
 
+/**
+ * A trigger inside a {@link TooltipGroup}; `content` is what the shared
+ * tooltip shows for it.
+ */
 function TooltipGroupTrigger({
   content,
   delay,
diff --git a/packages/vitnode/src/components/user-format.tsx b/packages/vitnode/src/components/user-format.tsx
index 7961f5a7ca..6ec121adf0 100644
--- a/packages/vitnode/src/components/user-format.tsx
+++ b/packages/vitnode/src/components/user-format.tsx
@@ -5,9 +5,11 @@ import { parseEmojiIcon } from "@/lib/emoji-icon";
 
 import { EmojiIcon } from "./ui/emoji-icon";
 
+/** The path of a user's public profile page. */
 export const userProfileHref = (nameCode: string): string =>
   `/users/${encodeURIComponent(nameCode)}`;
 
+/** A user's display name, optionally styled by their role and linked to their profile. */
 export const UserFormat = ({
   user,
   format,
@@ -16,7 +18,9 @@ export const UserFormat = ({
   style,
   ...props
 }: React.ComponentProps<"span"> & {
+  /** Colors the name and adds the role's prefix icon. */
   format?: boolean;
+  /** Links to the profile page; needs `user.nameCode`. */
   link?: boolean;
   user: {
     name: string;
diff --git a/packages/vitnode/src/content/admin/registry.ts b/packages/vitnode/src/content/admin/registry.ts
index 5c171e0661..348d8c7604 100644
--- a/packages/vitnode/src/content/admin/registry.ts
+++ b/packages/vitnode/src/content/admin/registry.ts
@@ -33,6 +33,7 @@ export interface ContentContainerFrontendRegistry {
   ) => RegisteredFrontendContentContainer | undefined;
 }
 
+/** Lookups over every content type the installed plugins register for the AdminCP. */
 export interface ContentFrontendRegistry {
   /** Every registration, sorted by content type id. */
   all: () => readonly RegisteredFrontendContentType[];
@@ -73,6 +74,14 @@ const buildContainerRegistry = (
   };
 };
 
+/**
+ * Collects the `contentTypes` and `containers` of every frontend plugin
+ * (`buildPlugin()`) into one registry. Called by the app's generated
+ * `src/content-registry.gen.ts`; plugin code rarely needs it.
+ *
+ * @throws A `ContentEngineError` when two content types clash - the same id,
+ * table, admin path or delivery path - as `validateContentTypes` reports.
+ */
 export const buildContentFrontendRegistry = (
   plugins: readonly ContentFrontendPluginSource[],
 ): ContentFrontendRegistry => {
@@ -111,6 +120,7 @@ export const CONTENT_FRONTEND_REGISTRY_MISSING =
 
 let registered: ContentFrontendRegistry | undefined;
 
+/** Installs the app-wide registry. Done by the generated `src/content-registry.gen.ts`. */
 export const setContentFrontendRegistry = (
   registry: ContentFrontendRegistry,
 ): void => {
diff --git a/packages/vitnode/src/content/cache.ts b/packages/vitnode/src/content/cache.ts
index afdfef604a..707f1d8dab 100644
--- a/packages/vitnode/src/content/cache.ts
+++ b/packages/vitnode/src/content/cache.ts
@@ -20,6 +20,18 @@ const localeParts = (locale: string | undefined): string[] => {
   return normalized === "" ? [] : [normalized];
 };
 
+/*
+ * Cache tags for a content type's public reads. Pure strings
+ * (`content:{contentTypeId}:{kind}[:{locale}][:{key}]`, clamped with a
+ * fingerprint when too long), safe on any runtime. Tag a cached read with the
+ * matching builder. `contentInvalidationTags` lists the tags one write
+ * expires; the engine sends that input to `content.revalidateOrigins` after
+ * scheduled publishes and hide/unhide. Its own page cache expires only the
+ * locale-less list and item tags. Pass `locale` only for a localized content
+ * type.
+ */
+
+/** Every public list page of a content type, in one locale. */
 export const contentPublicListTag = (
   contentTypeId: string,
   locale?: string,
@@ -33,12 +45,14 @@ export const contentPublicItemTag = (
 ): string =>
   tag(contentTypeId, "item", ...localeParts(locale), contentIdKey(id));
 
+/** One row, by slug, in one locale. Expired for both the old and new slug on a slug change. */
 export const contentPublicSlugTag = (
   contentTypeId: string,
   slug: string,
   locale?: string,
 ): string => tag(contentTypeId, "slug", ...localeParts(locale), slug);
 
+/** A record's delivery resolution (canonical URL, alternates, SEO), in one locale. */
 export const contentDeliveryTag = (
   contentTypeId: string,
   id: ContentId,
@@ -46,27 +60,41 @@ export const contentDeliveryTag = (
 ): string =>
   tag(contentTypeId, "delivery", ...localeParts(locale), contentIdKey(id));
 
+/** The redirect resolution of one historical slug, in one locale. */
 export const contentDeliveryRedirectTag = (
   contentTypeId: string,
   slug: string,
   locale?: string,
 ): string => tag(contentTypeId, "redirect", ...localeParts(locale), slug);
 
+/**
+ * One locale's sitemap file. Without `locale` it is the sitemap index of a
+ * localized content type, or the only sitemap file of one that is not.
+ */
 export const contentDeliverySitemapTag = (
   contentTypeId: string,
   locale?: string,
 ): string => tag(contentTypeId, "sitemap", ...localeParts(locale));
 
+/** Every public read of a content container definition's containers. */
 export const contentContainerTag = (definitionId: string): string =>
   tag(definitionId, "containers");
 
+/**
+ * A hint for the receiving front end on how to expire tags: `immediate` drops
+ * them now, `stale-while-revalidate` serves the old value while it refetches.
+ * The engine currently always sends `immediate`.
+ */
 export type ContentInvalidationMode = "immediate" | "stale-while-revalidate";
 
+/** One locale's reachability across a write, for a localized content type. */
 export interface ContentLocaleInvalidation {
+  /** Whether this locale is publicly reachable *after* the write. */
   isPublic: boolean;
   locale: string;
   /** Every slug this locale answered to across the mutation. */
   slugs: readonly string[];
+  /** Whether it was publicly reachable *before*. */
   wasPublic: boolean;
 }
 
@@ -80,13 +108,20 @@ export interface ContentSitemapChange {
   indexChanged: boolean;
 }
 
+/** What one write did to a record's public reachability, for {@link contentInvalidationTags}. */
 export interface ContentInvalidationInput {
   contentTypeId: string;
+  /** Set for a content type with `delivery`, to add its delivery tags. */
   delivery?: ContentDeliveryInvalidation;
+  /** The record's id. */
   id: ContentId;
   /** Whether the row is publicly reachable *after* the mutation. */
   isPublic: boolean;
-
+  /**
+   * Per-locale reachability for a localized type. When set, tags are built per
+   * locale from these entries and the top-level `isPublic`, `wasPublic` and
+   * `slugs` are ignored.
+   */
   locales?: readonly ContentLocaleInvalidation[];
   /**
    * Every slug the row answered to across the mutation. On a slug change that
@@ -106,6 +141,12 @@ const slugTags = (
     .filter(slug => slug !== "")
     .map(slug => contentPublicSlugTag(contentTypeId, slug, locale));
 
+/**
+ * The cache tags one write expires. Nothing when the record was neither public
+ * before nor after the write; otherwise the list, item and slug tags (per
+ * locale when `locales` is given) plus the delivery tags when `delivery` is
+ * set.
+ */
 export const contentInvalidationTags = ({
   contentTypeId,
   delivery,
diff --git a/packages/vitnode/src/content/conflicts.ts b/packages/vitnode/src/content/conflicts.ts
index 4c14de9524..f3f0bb0814 100644
--- a/packages/vitnode/src/content/conflicts.ts
+++ b/packages/vitnode/src/content/conflicts.ts
@@ -236,10 +236,18 @@ export const zodContentPublicWriteRejection = z.object({
   ),
 });
 
+/**
+ * The JSON body of a refused public write: `code` (one of the
+ * `CONTENT_PUBLIC_WRITE_CODES`), the content type and the field `issues`.
+ */
 export type ContentPublicWriteRejection = z.infer<
   typeof zodContentPublicWriteRejection
 >;
 
+/**
+ * Reads a refused public write's body. Takes the already-parsed JSON (not a
+ * string) and returns `null` for any other shape.
+ */
 export const parseContentPublicWriteRejection = (
   body: unknown,
 ): ContentPublicWriteRejection | null => {
diff --git a/packages/vitnode/src/content/const.ts b/packages/vitnode/src/content/const.ts
index e9ce3e0234..c02a5d0bd0 100644
--- a/packages/vitnode/src/content/const.ts
+++ b/packages/vitnode/src/content/const.ts
@@ -389,6 +389,7 @@ const sitemapChangeFrequencies: ReadonlySet<string> = new Set(
   CONTENT_SITEMAP_CHANGE_FREQUENCIES,
 );
 
+/** Whether a value is one of the seven sitemap `changefreq` values. */
 export const isContentSitemapChangeFrequency = (
   value: unknown,
 ): value is (typeof CONTENT_SITEMAP_CHANGE_FREQUENCIES)[number] =>
diff --git a/packages/vitnode/src/content/containers/define.ts b/packages/vitnode/src/content/containers/define.ts
index 1183668eed..5da837bf0e 100644
--- a/packages/vitnode/src/content/containers/define.ts
+++ b/packages/vitnode/src/content/containers/define.ts
@@ -324,6 +324,33 @@ const buildSchemas = (
   };
 };
 
+/**
+ * Declares a collection of containers - forums, boards, categories - that
+ * records of other content types are filed into with `field.container()`.
+ * Containers are stored in core tables, so a collection needs no table of its
+ * own; it adds AdminCP screens, optional nesting and ordering, a public API,
+ * and per-container publishing policies. Universal.
+ *
+ * Register it on the server with `buildContentAdminModule({ containers })` /
+ * `buildContentPublicModule({ containers })`, and in the AdminCP with
+ * `buildPlugin({ containers })`.
+ *
+ * @throws A `ContentEngineError` at import time for an invalid id, a field
+ * kind containers cannot store, or an invalid option.
+ *
+ * @example
+ * ```ts
+ * import { defineContentContainer, field } from "@vitnode/core/content";
+ *
+ * export const forumContainers = defineContentContainer({
+ *   id: "forum.forums",
+ *   fields: { description: field.textarea({ maxLength: 500, nullable: true }) },
+ *   hierarchy: { maxDepth: 4 },
+ *   publicApi: { path: "forums", fields: ["description"] },
+ *   admin: { path: "forum/forums" },
+ * });
+ * ```
+ */
 export const defineContentContainer = <
   const TId extends string,
   const TFields extends ContentContainerFieldMap = Record<never, never>,
diff --git a/packages/vitnode/src/content/containers/server/admin-routes.ts b/packages/vitnode/src/content/containers/server/admin-routes.ts
index 4291585fe8..aeb5e2a55e 100644
--- a/packages/vitnode/src/content/containers/server/admin-routes.ts
+++ b/packages/vitnode/src/content/containers/server/admin-routes.ts
@@ -26,6 +26,7 @@ import {
   createContentContainerService,
 } from "./service";
 
+/** The error body the container admin routes answer with. */
 export const zodContentContainerError = z.object({
   code: z.enum(CONTENT_CONTAINER_ERROR_CODES),
   message: z.string(),
@@ -78,6 +79,10 @@ const errorResponse = (description: string) => ({
   description,
 });
 
+/**
+ * The AdminCP routes of one content container type, mounted by
+ * `buildContentAdminModule`; plugins do not call this directly.
+ */
 export const buildContentContainerAdminRoutes = <
   TDefinition extends AnyContentContainerDefinition,
   P extends string,
diff --git a/packages/vitnode/src/content/containers/server/public-routes.ts b/packages/vitnode/src/content/containers/server/public-routes.ts
index 6ed538bbe4..1de5014f59 100644
--- a/packages/vitnode/src/content/containers/server/public-routes.ts
+++ b/packages/vitnode/src/content/containers/server/public-routes.ts
@@ -15,6 +15,10 @@ import { createContentContainerService } from "./service";
 
 const NUMERIC_ID = /^[1-9][0-9]{0,15}$/;
 
+/**
+ * The public routes of one content container type, mounted by
+ * `buildContentPublicModule`; plugins do not call this directly.
+ */
 export const buildContentContainerPublicRoutes = <
   TDefinition extends AnyContentContainerDefinition,
   P extends string,
diff --git a/packages/vitnode/src/content/containers/server/service.ts b/packages/vitnode/src/content/containers/server/service.ts
index 731f06933a..9a864b3f9f 100644
--- a/packages/vitnode/src/content/containers/server/service.ts
+++ b/packages/vitnode/src/content/containers/server/service.ts
@@ -182,6 +182,19 @@ export const contentContainerInputRefusal = (
   message: zodErrorMessage(error),
 });
 
+/**
+ * The server service for one container collection: list, read, create,
+ * update, move and delete containers, and read or change their publishing
+ * policies. The AdminCP routes use it, and it emits the
+ * `content.container.*` events, so custom code calling it emits the same ones.
+ * Server-only.
+ *
+ * `usage` decides whether a container still holds content before a delete;
+ * it defaults to checking every content model that references this collection.
+ *
+ * @throws {ContentContainerError} With a `code` such as `notFound`,
+ * `slugTaken`, `hasContent` or `invalidMetadata`.
+ */
 export const createContentContainerService = <
   TDefinition extends AnyContentContainerDefinition,
 >(
diff --git a/packages/vitnode/src/content/containers/tree.ts b/packages/vitnode/src/content/containers/tree.ts
index c878efa34b..1ac7be5d9e 100644
--- a/packages/vitnode/src/content/containers/tree.ts
+++ b/packages/vitnode/src/content/containers/tree.ts
@@ -10,6 +10,7 @@ export interface ContentContainerTreeRow {
   position: number;
 }
 
+/** A row from {@link contentContainerTree}, with its nested `children`. */
 export type ContentContainerTreeNode<TRow> = TRow & {
   children: ContentContainerTreeNode<TRow>[];
 };
@@ -81,6 +82,11 @@ export const orderContentContainers = <TRow extends ContentContainerTreeRow>(
   return ordered;
 };
 
+/**
+ * Nests a flat list of rows with `id` and `parentId` into a tree, keeping the
+ * input order among siblings. A row whose parent is missing from the list
+ * becomes a root. Universal.
+ */
 export const contentContainerTree = <
   TRow extends { id: number; parentId: null | number },
 >(
diff --git a/packages/vitnode/src/content/containers/types.ts b/packages/vitnode/src/content/containers/types.ts
index 804de540aa..fb518b2dd7 100644
--- a/packages/vitnode/src/content/containers/types.ts
+++ b/packages/vitnode/src/content/containers/types.ts
@@ -35,11 +35,14 @@ export type ContentContainerErrorCode =
   (typeof CONTENT_CONTAINER_ERROR_CODES)[number];
 
 export interface ContentContainerHierarchyInput {
+  /** Containers may nest under a parent. Defaults to `true`. */
   enabled?: boolean;
+  /** Deepest nesting level. Defaults to 5; `1` without a hierarchy. */
   maxDepth?: number;
 }
 
 export interface ContentContainerOrderingInput {
+  /** `"manual"` (default, drag to reorder) or `"alphabetical"`. */
   mode?: ContentContainerOrderingMode;
 }
 
@@ -47,13 +50,21 @@ export interface ContentContainerPublicApiInput<
   TField extends string = string,
   TPath extends string = string,
 > {
+  /**
+   * Metadata fields exposed publicly, besides the built-in columns (id,
+   * parent, name, slug, position, timestamps). Defaults to none.
+   */
   fields?: readonly TField[];
+  /** The public module segment, e.g. `"forums"`. */
   path: TPath;
 }
 
 export interface ContentContainerAdminInput {
+  /** Show the containers screen in the AdminCP sidebar. Defaults to `true`. */
   navigation?: boolean;
+  /** The AdminCP path under `/admin/content/`. Defaults to the id with dots as slashes. */
   path?: string;
+  /** Staff permission module. Defaults to the id in snake_case, e.g. `forum_forums`. */
   permissionModule?: string;
 }
 
@@ -77,6 +88,7 @@ export interface ContentContainerSchemas {
   update: z.ZodObject<z.ZodRawShape>;
 }
 
+/** A resolved container collection, returned by `defineContentContainer()`. */
 export interface ContentContainerDefinition<
   TId extends string = string,
   TFields extends ContentContainerFieldMap = ContentContainerFieldMap,
diff --git a/packages/vitnode/src/content/define.ts b/packages/vitnode/src/content/define.ts
index 5ad2965c1e..b16e39cd15 100644
--- a/packages/vitnode/src/content/define.ts
+++ b/packages/vitnode/src/content/define.ts
@@ -157,6 +157,42 @@ const assertIndexable = (
   }
 };
 
+/**
+ * Declares a Content Engine content type: its fields, its storage and the
+ * capabilities (publication, localization, public API, editorial workflow,
+ * delivery, search, reports, ...) the engine generates for it.
+ *
+ * Universal and side-effect free: import the result from browser and server
+ * code alike. It returns the **resolved** definition - every option normalised
+ * and defaulted, plus the generated Zod schemas - which the server turns into
+ * tables (`createContentTable()`), a model (`createContentModel()`) and generated API
+ * modules, and the AdminCP turns into list and form screens.
+ *
+ * Mistakes are reported twice: option combinations that cannot work (a preview
+ * without a public API, scheduling without publication, a private field in
+ * search) are compile errors where the types can express them, and everything
+ * is checked again at runtime, so a JavaScript caller gets the same answer.
+ *
+ * @throws {ContentEngineError} When the definition is invalid - a malformed
+ * `id` or `tableName`, an empty `fields` map, an unknown or reserved field
+ * name, or an option whose requirements are not met. Thrown at import time.
+ *
+ * @example
+ * ```ts
+ * import { defineContentType, field } from "@vitnode/core/content";
+ *
+ * export const blogCategoryContentType = defineContentType({
+ *   id: "blog.category",
+ *   tableName: "blog_categories",
+ *   localization: { defaultLocale: "en", fallback: "default" },
+ *   fields: {
+ *     name: field.text({ localized: true, required: true, maxLength: 100 }),
+ *     color: field.text({ maxLength: 50, nullable: true }),
+ *   },
+ *   admin: { titleField: "name", list: { columns: ["name", "color"] } },
+ * });
+ * ```
+ */
 export const defineContentType = <
   TId extends string,
   TFields extends ContentFieldsConstraint<
@@ -247,29 +283,77 @@ export const defineContentType = <
   thread,
   visibility,
 }: {
+  /**
+   * How the generated AdminCP screens present the content type: list columns,
+   * form layout, dialog or page mode, title field, URL path and the staff
+   * permission module. Every property is optional.
+   */
   admin?: ContentAdminConfig<
     TFields,
     TPublication,
     ContentEditorialEnabled<TEditorial>
   >;
 
+  /**
+   * Public delivery: canonical URLs (`/{publicApi.path}/:slug` by default), SEO
+   * metadata, localized alternates, sitemap entries and, with `redirects`, slug
+   * history. Needs `publicApi`. `true` enables it with every default.
+   */
   delivery?: TDelivery;
 
+  /**
+   * Adds a "Duplicate" action that copies a record as a new draft. With
+   * `titleSuffix` (on by default when `admin.titleField` is a text field), the
+   * copy's title gets a translated "(Copy)" suffix.
+   */
   duplication?: TDuplication;
 
+  /**
+   * The editorial workflow: a `version` column for optimistic locking, revision
+   * history (`revisions.retention`, default 50), share-able draft previews
+   * (`preview`, needs `publicApi`) and scheduled publishing (`scheduling`,
+   * needs `publication`). `true` enables revisions with defaults only.
+   */
   editorial?: TEditorial;
+  /**
+   * The content type's own fields, built with `field.*`. At least one. System
+   * columns (`id`, `createdAt`, `updatedAt`, plus the ones each option adds)
+   * are generated and cannot be redeclared.
+   */
   fields: TFields;
+  /**
+   * Stable identifier, `plugin.entity` (lowercase, dot separated), e.g.
+   * `blog.post`. Used for events, cache tags, i18n keys and the permission
+   * module, so changing it is a breaking change.
+   */
   id: TId;
+  /** Primary key type: `"serial"` (default, a number), `"uuid"` or `"bigint"` (both strings). */
   idStrategy?: TIdStrategy;
+  /**
+   * Extra base-table indexes. Indexes for slugs, unique fields, relations and
+   * the enabled options are generated automatically; a declared index that
+   * duplicates one is merged. Localized fields cannot be indexed here.
+   */
   indexes?: ContentIndexInput<
     TFields,
     TPublication,
     ContentEditorialEnabled<TEditorial>
   >[];
 
+  /**
+   * Real-time collaborative editing in the AdminCP: field locks and a shared
+   * draft. Needs `editorial`. Defaults to `false`.
+   */
   liveEditing?: ContentEditorialEnabled<TEditorial> extends true
     ? boolean
     : false;
+  /**
+   * Enables per-language values for fields marked `localized: true`, stored in
+   * a generated `<tableName>_translations` table. `defaultLocale` is the
+   * language every record is first created in; `fallback: "default"` serves
+   * that language's translation publicly when the requested one is missing
+   * (default `"none"`: no fallback).
+   */
   localization?: TLocalization;
   /**
    * Opts into a generated read-only public API. Needs `publication` and exactly
@@ -278,18 +362,47 @@ export const defineContentType = <
   publicApi?:
     | ContentPublicApiConfig<TPublicField, TPublicPath, TPublicPeople>
     | false;
-  /** Opts into the draft/published lifecycle. Omit to stay on Stage 1 behaviour. */
+  /**
+   * Opts into the draft/published lifecycle: adds `status` and `publishedAt`,
+   * and only published records reach the public API. Defaults to `false`.
+   */
   publication?: TPublication;
+  /**
+   * Generated public create/update routes for signed-in users. Needs
+   * `publicApi` and a single, shared `field.user()` as `ownership.field`, which
+   * the server stamps from the session. `create.status` defaults to `"draft"`
+   * and `update.own` to `true`. Not available on localized content types.
+   */
   publicWrite?: TPublicWrite;
+  /**
+   * Lets users report records to moderators. Needs `publicApi`. `true` uses
+   * `admin.titleField` (when public) as the report title and snapshots the
+   * public text, textarea, rich text, enum and file fields other than the
+   * title field.
+   */
   reports?: ContentReportsInput<keyof TFields & string>;
 
+  /**
+   * Indexes published records into the site-wide search. Every indexed field
+   * must also be in `publicApi.fields`, and `pathTemplate` must contain one
+   * `{slug}` placeholder.
+   */
   search?: TSearch;
+  /**
+   * The base table's Postgres name: snake_case, starting with a letter, at
+   * most 63 characters. Generated child, junction and translation tables are
+   * named after it.
+   */
   tableName: string;
   /**
    * Records that answer each other under one root - forum replies under a
    * topic. Adds the public `GET /thread` route and server-side parent checks.
    */
   thread?: ContentThreadInput<keyof TFields & string> | false;
+  /**
+   * Lets moderators hide a record from the public site without unpublishing
+   * it (`hiddenAt`, `hiddenBy`). Needs `publication: true`. Defaults to `false`.
+   */
   visibility?: TVisibility;
 }): ContentTypeDefinition<
   TId,
diff --git a/packages/vitnode/src/content/delivery.ts b/packages/vitnode/src/content/delivery.ts
index 7434d040a6..c3a59c631d 100644
--- a/packages/vitnode/src/content/delivery.ts
+++ b/packages/vitnode/src/content/delivery.ts
@@ -462,6 +462,10 @@ export const resolveContentDelivery = ({
 // Canonical URLs
 // ---------------------------------------------------------------------------
 
+/**
+ * A record's route path with its slug filled into `delivery.path`, before any
+ * locale prefix. `null` when delivery is off or the slug is empty.
+ */
 export const contentDeliveryInternalPath = ({
   definition,
   slug,
@@ -483,6 +487,11 @@ export const contentDeliveryInternalPath = ({
     .join("/");
 };
 
+/**
+ * A record's canonical public URL, with the locale placed by the install's
+ * i18n routing (prefix, domain or translated route). `null` when there is no
+ * delivery path.
+ */
 export const contentDeliveryPublicUrl = ({
   definition,
   host,
@@ -509,6 +518,7 @@ export const contentDeliveryPublicUrl = ({
   });
 };
 
+/** The pathname of {@link contentDeliveryPublicUrl}, or `null`. */
 export const contentDeliveryPath = (args: {
   definition: AnyContentTypeDefinition;
   locale?: null | string;
@@ -550,6 +560,7 @@ export interface ContentDeliveryAlternate {
   path: string;
 }
 
+/** `hreflang` links for a record: one URL per published locale. */
 export interface ContentDeliveryHreflang {
   languages: Record<string, string>;
   /** Present only with `delivery.hreflang.xDefault` and a resolvable default. */
@@ -561,6 +572,11 @@ export const contentDeliveryAlternateHref = (
 ): string =>
   contentPublicHref({ origin: alternate.origin, pathname: alternate.path });
 
+/**
+ * Builds the `hreflang` map from a record's alternates, adding `x-default`
+ * (the default locale's URL) when `delivery.hreflang.xDefault` is set and that
+ * locale is among the alternates.
+ */
 export const contentDeliveryHreflang = ({
   alternates,
   definition,
@@ -599,6 +615,7 @@ const contentDeliveryLocalesMatch = (a: string, b: string): boolean =>
 // SEO projection
 // ---------------------------------------------------------------------------
 
+/** Resolved `<title>` and meta description text, or `null` per slot. */
 export interface ContentDeliverySeo {
   description: null | string;
   title: null | string;
@@ -628,6 +645,11 @@ const readSeoText = (
   return null;
 };
 
+/**
+ * Reads the SEO title and description from a public row using
+ * `delivery.seo`: the primary field, then its fallback field. Rich text is
+ * flattened to plain text; empty values count as missing.
+ */
 export const contentDeliverySeo = (
   definition: AnyContentTypeDefinition,
   row: Record<string, unknown>,
@@ -644,6 +666,10 @@ export const contentDeliverySeo = (
   };
 };
 
+/**
+ * Open Graph title and description, falling back to {@link contentDeliverySeo}
+ * per slot. `null` when `delivery.seo.openGraph` is not configured.
+ */
 export const contentDeliveryOpenGraph = (
   definition: AnyContentTypeDefinition,
   row: Record<string, unknown>,
@@ -661,6 +687,10 @@ export const contentDeliveryOpenGraph = (
   };
 };
 
+/**
+ * `robots` metadata from `delivery.seo.noIndexField`: `index: false` when the
+ * field is `true`. `null` when no such field is configured.
+ */
 export const contentDeliveryRobots = (
   definition: AnyContentTypeDefinition,
   row: Record<string, unknown>,
@@ -747,6 +777,11 @@ const parseLegacyDeliveryPath = (
   };
 };
 
+/**
+ * The inverse of {@link contentDeliveryPublicUrl}: splits a public path into
+ * its locale and slug. `null` when the path matches neither the content type's
+ * delivery route nor the legacy `/{locale}/{publicApi.path}/{slug}` form.
+ */
 export const parseContentDeliveryPath = (
   definition: AnyContentTypeDefinition,
   path: string,
diff --git a/packages/vitnode/src/content/editor/adapter.ts b/packages/vitnode/src/content/editor/adapter.ts
index d282beba55..13ca31a739 100644
--- a/packages/vitnode/src/content/editor/adapter.ts
+++ b/packages/vitnode/src/content/editor/adapter.ts
@@ -11,6 +11,10 @@ import { ContentEngineError } from "../errors";
 const quoted = (values: readonly string[]): string =>
   values.map(value => JSON.stringify(value)).join(", ");
 
+/**
+ * A save the visual editor should report to the user instead of treating as a
+ * crash. `conflict` marks a save refused because the layout changed meanwhile.
+ */
 export class EditablePageSaveRefused extends ContentEngineError {
   constructor(
     refusal: string,
@@ -27,6 +31,14 @@ export class EditablePageSaveRefused extends ContentEngineError {
   readonly refusal: string;
 }
 
+/**
+ * Adapts an editable page to the visual editor: on save it sends only the
+ * changed zones the page declares (with what they held before) to your `save`
+ * callback, and hands the stored zones back to the editor.
+ *
+ * Saving an undeclared zone throws {@link EditablePageSaveRefused} before
+ * anything is sent.
+ */
 export const createContentEditorAdapter = ({
   page,
   save,
diff --git a/packages/vitnode/src/content/editor/define.ts b/packages/vitnode/src/content/editor/define.ts
index 474dd4cc1c..e9bed4aa3b 100644
--- a/packages/vitnode/src/content/editor/define.ts
+++ b/packages/vitnode/src/content/editor/define.ts
@@ -30,6 +30,12 @@ const quoted = (values: readonly string[]): string =>
 const isStringArray = (value: unknown): value is readonly string[] =>
   Array.isArray(value) && value.every(entry => typeof entry === "string");
 
+/**
+ * Checks an editable page id: `plugin:page` - two or more `:`-separated
+ * lowercase segments, e.g. `"example:settings"`.
+ *
+ * @throws A `ContentEngineError` for anything else.
+ */
 export const assertEditablePageId = (pageId: unknown): string => {
   if (
     typeof pageId !== "string" ||
@@ -273,6 +279,11 @@ const readZone = (
   return { allowed, default: shipped, max, min, zoneId };
 };
 
+/**
+ * One declared zone of a page.
+ *
+ * @throws A `ContentEngineError` when the page does not declare `zoneId`.
+ */
 export const editablePageZone = (
   page: AnyEditablePageDefinition,
   zoneId: string,
@@ -291,9 +302,36 @@ export const editablePageZone = (
   return found;
 };
 
+/**
+ * Declares a page whose block zones moderators arrange in the visual editor,
+ * while the rest of the page stays application code. Universal: use the same
+ * definition in the page component and in the API plugin's `editablePages`,
+ * which registers it for storage and permission checks.
+ *
+ * @throws A `ContentEngineError` at import time for an invalid id or
+ * permission, no zones, an invalid zone id, or a zone whose limits or
+ * `default` contradict each other.
+ *
+ * @example
+ * ```ts
+ * import { defineEditablePage } from "@vitnode/core/content/editor";
+ *
+ * export const settingsPage = defineEditablePage({
+ *   id: "example:settings",
+ *   permission: { module: "widgets", permission: "can_edit" },
+ *   zones: {
+ *     header: { max: 10 },
+ *     footer: { allowed: ["core:text"], max: 10 },
+ *   },
+ * });
+ * ```
+ */
 export const defineEditablePage = <const TZoneId extends string>(args: {
+  /** Stable `plugin:page` id. Stored layouts are keyed by it, so never change it. */
   id: string;
+  /** The moderator permission required to open the editor. */
   permission: EditablePagePermission;
+  /** At least one zone, keyed by zone id. */
   zones: Record<TZoneId, EditablePageZoneInput>;
 }): EditablePageDefinition<TZoneId> => {
   const pageId = assertEditablePageId(args.id);
diff --git a/packages/vitnode/src/content/editor/types.ts b/packages/vitnode/src/content/editor/types.ts
index 5cadfae005..306f66b1a2 100644
--- a/packages/vitnode/src/content/editor/types.ts
+++ b/packages/vitnode/src/content/editor/types.ts
@@ -1,15 +1,24 @@
 import type { BlockAllowedSpec, ContentNode } from "../../blocks/types";
 
+/** The moderator permission a member needs before the visual editor opens on a page. */
 export interface EditablePagePermission {
+  /** The permission module, e.g. `"widgets"`. */
   module: string;
+  /** The permission inside it, e.g. `"can_edit"`. */
   permission: string;
+  /** The plugin that owns the module. Defaults to the page's own plugin. */
   plugin?: string;
 }
 
+/** One zone of {@link EditablePageDefinition} as it is declared. */
 export interface EditablePageZoneInput {
+  /** Block ids the zone accepts, e.g. `["core:text"]`, or `"*"` (default) for every installed block. */
   allowed?: BlockAllowedSpec;
+  /** Blocks served until somebody saves the zone. Must satisfy `min`, `max` and `allowed`. */
   default?: readonly ContentNode[];
+  /** The most blocks the zone holds. Defaults to 200. */
   max?: number;
+  /** The fewest blocks the zone must hold. */
   min?: number;
 }
 
@@ -26,9 +35,14 @@ export interface EditablePageZoneProps {
   id: string;
 }
 
+/** A validated editable page, returned by `defineEditablePage()`. */
 export interface EditablePageDefinition<TZoneId extends string = string> {
   id: string;
   permission: EditablePagePermission;
+  /**
+   * Props for the widget zone that renders `zoneId`. Throws for a zone the
+   * page does not declare.
+   */
   zone: (zoneId: TZoneId) => EditablePageZoneProps;
   zoneIds: readonly string[];
   zones: Readonly<Record<string, EditablePageZone>>;
@@ -36,12 +50,15 @@ export interface EditablePageDefinition<TZoneId extends string = string> {
 
 export type AnyEditablePageDefinition = EditablePageDefinition<never>;
 
+/** What a save sends: the changed zones, and what they held when editing began. */
 export interface EditablePageSavePayload {
+  /** The zones as they were loaded, so the server can refuse a save over a newer one. */
   expectedZones: Record<string, ContentNode[]>;
   pageId: string;
   zones: Record<string, ContentNode[]>;
 }
 
+/** A page's stored layout. Zones nobody has saved are absent and use their `default`. */
 export interface EditablePageLayoutPayload {
   pageId: string;
   updatedAt: null | string;
@@ -49,7 +66,16 @@ export interface EditablePageLayoutPayload {
 }
 
 export interface EditablePageAdapterArgs {
+  /**
+   * The page from `defineEditablePage`. A save that changed a zone it does not
+   * declare is refused as a whole (`EditablePageSaveRefused`).
+   */
   page: AnyEditablePageDefinition;
+  /**
+   * Persists the changed zones and resolves with the stored layout. Throw
+   * `EditablePageSaveRefused` to show the editor a refusal (with
+   * `conflict: true` for a save over a newer layout).
+   */
   save: (
     payload: EditablePageSavePayload,
   ) => Promise<EditablePageLayoutPayload>;
diff --git a/packages/vitnode/src/content/errors.ts b/packages/vitnode/src/content/errors.ts
index 9ca352084b..e6ae956a52 100644
--- a/packages/vitnode/src/content/errors.ts
+++ b/packages/vitnode/src/content/errors.ts
@@ -431,6 +431,11 @@ export type ContentPublicWriteDenial =
   | "notFound"
   | "unauthenticated";
 
+/**
+ * A public write refused: `reason` is `unauthenticated`, `forbidden` or
+ * `notFound` (also used when `create`/`update` is switched off), and `issue` names a container rule
+ * (`edit_window_closed`, `moderators_only`) when one decided it.
+ */
 export class ContentPublicWriteDenied extends ContentEngineError {
   constructor({
     contentTypeId,
diff --git a/packages/vitnode/src/content/events.ts b/packages/vitnode/src/content/events.ts
index ed4fe79f93..9937dc07a1 100644
--- a/packages/vitnode/src/content/events.ts
+++ b/packages/vitnode/src/content/events.ts
@@ -1,6 +1,11 @@
 import type { ContentIdOf } from "./ids";
 import type { ContentFieldName, ContentLocalizedFieldName } from "./types";
 
+/**
+ * The last segment of a content event name, `content.{contentTypeId}.{action}`.
+ * Which actions a content type emits depends on the options it enables - see
+ * {@link ContentEventsFor}.
+ */
 export type ContentEventAction =
   | "created"
   | "deleted"
@@ -22,52 +27,67 @@ export type ContentEventAction =
   | "unpublished"
   | "updated";
 
+/** Payload of `content.{id}.created`. */
 export interface ContentCreatedPayload<TId = number> {
   contentId: TId;
 }
 
+/** Payload of `content.{id}.created` on a content type with `duplication`. */
 export interface ContentDuplicableCreatedPayload<TId = number> {
   contentId: TId;
+  /** The source record, when the new record is a duplicate. */
   duplicatedFromId?: TId;
 }
 
+/** Payload of `content.{id}.duplicated`. */
 export interface ContentDuplicatedPayload<TId = number> {
   actorUserId: null | number;
+  /** The new copy. */
   contentId: TId;
   contentTypeId: string;
+  /** The record that was copied. */
   sourceId: TId;
 }
 
+/** Payload of `content.{id}.hidden` (needs `visibility`). */
 export interface ContentHiddenPayload<TId = number> {
   actorUserId: null | number;
   contentId: TId;
   hiddenAt: Date;
 }
 
+/** Payload of `content.{id}.unhidden` (needs `visibility`). */
 export interface ContentUnhiddenPayload<TId = number> {
   actorUserId: null | number;
   contentId: TId;
 }
 
+/** Payload of `content.{id}.deleted`. */
 export interface ContentDeletedPayload<TId = number> {
   contentId: TId;
 }
 
+/** Payload of `content.{id}.updated`, a change to the record's shared fields. */
 export interface ContentUpdatedPayload<TDefinition> {
+  /** Shared fields whose value changed. Translation changes have their own events. */
   changedFields: ContentFieldName<TDefinition>[];
   contentId: ContentIdOf<TDefinition>;
 }
 
+/** Payload of `content.{id}.published` (needs `publication`). */
 export interface ContentPublishedPayload<TId = number> {
   contentId: TId;
   /** When the row was published for the *first* time; never rewritten. */
   publishedAt: Date;
 
+  /** Who booked the schedule, when a schedule fired it. */
   scheduledBy?: null | number;
 
+  /** The schedule that fired it, and the idempotency key for retries. */
   scheduleId?: number;
 }
 
+/** Payload of `content.{id}.unpublished` (needs `publication`). */
 export interface ContentUnpublishedPayload<TId = number> {
   contentId: TId;
   /** As on `published`: who scheduled it, when a schedule fired it. */
@@ -76,6 +96,7 @@ export interface ContentUnpublishedPayload<TId = number> {
   scheduleId?: number;
 }
 
+/** Payload of `content.{id}.restored` - a revision restored (needs `editorial`). */
 export interface ContentRestoredPayload<TDefinition> {
   changedFields: ContentFieldName<TDefinition>[];
   contentId: ContentIdOf<TDefinition>;
@@ -86,6 +107,7 @@ export interface ContentRestoredPayload<TDefinition> {
   version: number;
 }
 
+/** Payload of `content.{id}.scheduled` (needs `editorial.scheduling`). */
 export interface ContentScheduledPayload<TId = number> {
   action: "publish" | "unpublish";
   /** The staff member who booked it. */
@@ -95,6 +117,7 @@ export interface ContentScheduledPayload<TId = number> {
   scheduleId: number;
 }
 
+/** Payload of `content.{id}.schedule_cancelled` (needs `editorial.scheduling`). */
 export interface ContentScheduleCancelledPayload<TId = number> {
   action: "publish" | "unpublish";
   actorUserId: null | number;
@@ -391,6 +414,7 @@ export type ContentEventsFor<TDefinition extends { id: string }> =
       ContentUpdatedPayload<TDefinition>
     >;
 
+/** Builds a content event name, `content.{contentTypeId}.{action}`, as a literal type. */
 export const contentEventName = <
   TId extends string,
   TAction extends ContentEventAction,
diff --git a/packages/vitnode/src/content/fields.ts b/packages/vitnode/src/content/fields.ts
index ddba623049..645dfa5dd9 100644
--- a/packages/vitnode/src/content/fields.ts
+++ b/packages/vitnode/src/content/fields.ts
@@ -34,8 +34,17 @@ interface SharedArgs<
   TRequired extends boolean = false,
   TNullable extends boolean = false,
 > {
+  /** Help text shown as-is under a group or repeatable field in the AdminCP form. */
   description?: string;
+  /**
+   * The column accepts `NULL` and `null` is a valid value. Defaults to `false`
+   * (`true` for a single `field.file()` / `field.user()`).
+   */
   nullable?: TNullable;
+  /**
+   * The value must be present in a create payload. Defaults to `false`; the
+   * inferred create input type makes the property optional accordingly.
+   */
   required?: TRequired;
 }
 
@@ -51,6 +60,11 @@ const localizedOf = <TLocalized extends boolean>(
 ): TLocalized => (args.localized ?? false) as TLocalized;
 
 interface LocalizableArgs<TLocalized extends boolean = false> {
+  /**
+   * Store one value per language in the generated translation table instead of
+   * one shared value on the base table. Needs the content type's
+   * `localization: { defaultLocale }`. Defaults to `false`.
+   */
   localized?: TLocalized;
 }
 
@@ -62,10 +76,17 @@ const text = <
 >(
   args: LocalizableArgs<TLocalized> &
     SharedArgs<TRequired, TNullable> & {
+      /** Lets an AI action suggest a value from other fields in the AdminCP. */
       ai?: ContentFieldAiAssist;
+      /** Column default, used when a create payload leaves the field out. */
       defaultValue?: TDefault;
+      /**
+       * `varchar` length and validation limit. The column defaults to 255;
+       * nothing is validated unless set.
+       */
       maxLength?: number;
       minLength?: number;
+      /** Adds a unique index on the column. */
       unique?: boolean;
     } = {},
 ): ContentTextField<TRequired, TNullable, TDefault, TLocalized> => ({
@@ -84,8 +105,11 @@ const textarea = <
 >(
   args: LocalizableArgs<TLocalized> &
     SharedArgs<TRequired, TNullable> & {
+      /** Lets an AI action suggest a value from other fields in the AdminCP. */
       ai?: ContentFieldAiAssist;
+      /** Column default, used when a create payload leaves the field out. */
       defaultValue?: TDefault;
+      /** Validation limit for the stored `text`. Unlimited when omitted. */
       maxLength?: number;
       minLength?: number;
     } = {},
@@ -104,6 +128,7 @@ const richText = <
 >(
   args: LocalizableArgs<TLocalized> &
     SharedArgs<TRequired, TNullable> & {
+      /** Largest serialised document accepted, in bytes. Defaults to 1 MiB. */
       maxBytes?: number;
     } = {},
 ): ContentRichTextField<TRequired, TNullable, TLocalized> => ({
@@ -120,6 +145,7 @@ const number = <
 >(
   args: SharedArgs<TRequired, TNullable> & {
     defaultValue?: TDefault;
+    /** `true` stores an `integer` and rejects fractions; `false` stores `double precision`. */
     integer: boolean;
     max?: number;
     min?: number;
@@ -152,8 +178,11 @@ const enumField = <
 >(
   args: SharedArgs<TRequired, TNullable> & {
     defaultValue?: TDefault;
+    /** AdminCP control only - storage is always `varchar`. */
     display?: "radio" | "select";
+    /** `varchar` length. Defaults to 64. */
     length?: number;
+    /** The allowed values, inferred as a literal union. */
     values: TValues;
   },
 ): ContentEnumField<TValues, TRequired, TNullable, TDefault> => ({
@@ -174,6 +203,10 @@ const slug = <
     generated?: TGenerated;
     /** `varchar` length and the truncation point. Defaults to 160. */
     maxLength?: number;
+    /**
+     * A text field the server derives the slug from when none is sent. Without
+     * `source` or `generated`, the slug is required in the create payload.
+     */
     source?: TSource;
   } = {},
 ): ContentSlugField<TSource, TLocalized, TGenerated> => {
@@ -198,7 +231,10 @@ const dateTime = <
   TNullable extends boolean = false,
   TDefaultNow extends boolean = false,
 >(
-  args: SharedArgs<TRequired, TNullable> & { defaultNow?: TDefaultNow } = {},
+  args: SharedArgs<TRequired, TNullable> & {
+    /** Defaults the column to the insert time, which makes it optional on create. */
+    defaultNow?: TDefaultNow;
+  } = {},
 ): ContentDateTimeField<TRequired, TNullable, TDefaultNow> => ({
   ...args,
   ...shared(args),
@@ -216,14 +252,19 @@ const file = <
   TOrdered extends boolean = TMultiple,
 >(
   args: SharedArgs<TRequired, TNullable> & {
+    /** Accepted extensions such as `".png"`, normalised to lowercase. Any when omitted. */
     allowedExtensions?: readonly string[];
+    /** Accepted media types, normalised to lowercase. Any when omitted. */
     allowedMimeTypes?: readonly string[];
     /** The most files to accept. `multiple: true` only. */
     max?: number;
+    /** Largest accepted upload, in bytes. Required, finite and greater than zero. */
     maxBytes: number;
     /** The fewest files to accept. `multiple: true` only. */
     min?: number;
+    /** Several files, stored in a generated junction table. Defaults to `false`. */
     multiple?: TMultiple;
+    /** Keep the files in the order they were given. Defaults to `multiple`. */
     ordered?: TOrdered;
   },
 ): ContentFileField<TRequired, TNullable, TMultiple, TOrdered> => {
@@ -265,8 +306,15 @@ const user = <
   args: SharedArgs<TRequired, TNullable> & {
     /** The fewest people to accept. `multiple: true` only. */
     min?: number;
+    /** Several people, stored in a generated junction table. Defaults to `false`. */
     multiple?: TMultiple;
+    /**
+     * What happens when the referenced account is deleted. Defaults to
+     * `cascade` for `multiple`, `set null` for a nullable field, and `restrict`
+     * otherwise.
+     */
     onDelete?: ContentOnDelete;
+    /** Keep the people in the order they were given. Defaults to `false`. */
     ordered?: TOrdered;
   } = {},
 ): ContentUserField<TRequired, TNullable, TMultiple, TOrdered> => {
@@ -316,12 +364,20 @@ const relation = <
      * topic's forum. To-one, required and never `self`.
      */
     container?: TContainer;
+    /** The fewest related records to accept. `multiple: true` only. */
     min?: number;
+    /** Several records, stored in a generated junction table. Defaults to `false`. */
     multiple?: TMultiple;
+    /** What happens when the referenced record is deleted. Defaults to `restrict`. */
     onDelete?: ContentOnDelete;
+    /** Keep the related records in the order they were given. Defaults to `false`. */
     ordered?: TOrdered;
     /** The target is this content type. Mutually exclusive with `target`. */
     self?: TSelf;
+    /**
+     * The related content type, behind a thunk so two content types can
+     * reference each other without a circular import.
+     */
     target?: () => TTarget;
   },
 ): ContentRelationField<
@@ -356,7 +412,10 @@ const group = <
   TLocalized extends boolean = false,
 >(
   args: LocalizableArgs<TLocalized> &
-    SharedArgs<TRequired, TNullable> & { fields: TFields },
+    SharedArgs<TRequired, TNullable> & {
+      /** Scalar leaves only, stored as columns addressed by `group.leaf` paths. */
+      fields: TFields;
+    },
 ): ContentGroupField<TFields, TRequired, TNullable, TLocalized> => ({
   ...args,
   ...shared(args),
@@ -367,6 +426,7 @@ const group = <
 const repeatable = <const TFields extends Record<string, { kind: string }>>(
   args: {
     description?: string;
+    /** Scalar leaves only, stored as columns of a generated child table. */
     fields: TFields;
     /** Upper bound on child rows. Defaults to 100. */
     max?: number;
@@ -385,9 +445,12 @@ const blocks = <
   TLocalized extends boolean = false,
 >(
   args: LocalizableArgs<TLocalized> & {
+    /** Which block types the zone accepts. Defaults to `"*"`, every registered block. */
     allowed?: TAllowed;
     description?: string;
+    /** The most blocks the zone stores. Defaults to 200. */
     max?: number;
+    /** The fewest blocks the zone must hold. */
     min?: number;
   } = {},
 ): ContentBlocksField<TAllowed, TLocalized> => ({
@@ -403,8 +466,10 @@ const container = <
   const TDefinition extends AnyContentContainerDefinition,
   TRequired extends boolean = false,
 >(args: {
+  /** The container definition from `defineContentContainer()`. */
   definition: TDefinition;
   description?: string;
+  /** Every record must belong to a container. Nullable when `false` (the default). */
   required?: TRequired;
 }): ContentContainerField<TRequired, TDefinition> => {
   const required = (args.required ?? false) as TRequired;
@@ -417,21 +482,76 @@ const container = <
   };
 };
 
+/**
+ * Field builders for the `fields` map of `defineContentType()`.
+ *
+ * Each builder returns a plain descriptor object. Its literal options
+ * (`required`, `nullable`, `localized`, `multiple`, ...) drive the inferred
+ * create, update, select and public types; `defineContentType` validates the
+ * combination at runtime and generates the columns, schemas and AdminCP inputs.
+ * Universal: safe to import in browser and server code.
+ *
+ * @example
+ * ```ts
+ * import { defineContentType, field } from "@vitnode/core/content";
+ *
+ * export const noteContentType = defineContentType({
+ *   id: "notes.note",
+ *   tableName: "notes_notes",
+ *   fields: {
+ *     title: field.text({ required: true, maxLength: 120 }),
+ *     slug: field.slug({ source: "title" }),
+ *     body: field.richText(),
+ *     authorId: field.user(),
+ *   },
+ * });
+ * ```
+ */
 export const field = {
+  /** A zone of nested blocks (widgets), stored as one JSONB document. Never required or nullable. */
   blocks,
+  /** A `boolean` column. */
   boolean,
+  /** The content container (e.g. a forum board) a record belongs to. At most one per content type. */
   container,
+  /** A `timestamp` column, read as a `Date`. */
   dateTime,
+  /** One of a fixed list of string values, stored as `varchar`. */
   enum: enumField,
+  /**
+   * One uploaded file, or several with `multiple: true`. Stored as a
+   * `core_files` reference; public reads return a file descriptor, never the id.
+   * Nullable by default for a single file.
+   */
   file,
+  /** A named set of scalar leaves stored as columns on the same row (e.g. `seo.title`). */
   group,
+  /** A numeric column. `integer` is required so the storage type is always explicit. */
   number,
+  /**
+   * A reference to another content type's record (`target`) or to this one
+   * (`self: true`). To-one is a foreign-key column; `multiple: true` uses a
+   * generated junction table.
+   */
   relation,
+  /** An ordered list of rows of scalar leaves, stored in a generated child table. Cannot be localized. */
   repeatable,
+  /** A rich-text document stored as `jsonb`, validated and size-limited on write. */
   richText,
+  /**
+   * A URL-safe identifier, unique per table (or per language when localized).
+   * Derived from `source`, minted with `generated: true`, or sent explicitly.
+   */
   slug,
+  /** A single-line string stored as `varchar`. */
   text,
+  /** A multi-line plain-text string stored as `text`. */
   textarea,
+  /**
+   * A reference to a user account. Nullable by default for a single user, so a
+   * deleted account clears the reference instead of blocking the delete.
+   */
   user,
+  /** Alias of {@link field.blocks}. */
   widgets: blocks,
 };
diff --git a/packages/vitnode/src/content/hash.ts b/packages/vitnode/src/content/hash.ts
index f38dac7f93..59eae274d3 100644
--- a/packages/vitnode/src/content/hash.ts
+++ b/packages/vitnode/src/content/hash.ts
@@ -13,6 +13,11 @@ export const fingerprint = (value: string): string => {
   return hash.toString(36).padStart(7, "0");
 };
 
+/**
+ * Returns `value` unchanged when it fits `maxLength`; otherwise truncates it
+ * and appends `_{fingerprint}` of the full value, so distinct long values stay
+ * distinct. Used for generated Postgres identifiers and cache tags.
+ */
 export const clampWithFingerprint = (
   value: string,
   maxLength: number,
diff --git a/packages/vitnode/src/content/ids.ts b/packages/vitnode/src/content/ids.ts
index 768b31677b..102c51e59c 100644
--- a/packages/vitnode/src/content/ids.ts
+++ b/packages/vitnode/src/content/ids.ts
@@ -71,6 +71,11 @@ export const parseContentId = (
   return null;
 };
 
+/**
+ * Validates an id from a request, a job payload or a URL against a content
+ * type's `idStrategy`: a positive serial number, a bigint string or a UUID.
+ * `null` when it is not one.
+ */
 export const parseContentIdOf = <
   TDefinition extends { idStrategy: ContentIdStrategy },
 >(
diff --git a/packages/vitnode/src/content/localization.ts b/packages/vitnode/src/content/localization.ts
index 0cbd7ae966..fc8d5f932f 100644
--- a/packages/vitnode/src/content/localization.ts
+++ b/packages/vitnode/src/content/localization.ts
@@ -25,6 +25,7 @@ export const isLocalizedContentField = (
 ): boolean => fieldValue.localized === true;
 
 export interface ContentFieldPartition {
+  /** To-many relations, users and files, and repeatables: stored in generated junction or child tables. */
   collectionFields: ContentFieldMap;
   /** Fields stored in the translation table, one row per language. */
   localizedFields: ContentFieldMap;
@@ -32,6 +33,7 @@ export interface ContentFieldPartition {
   sharedFields: ContentFieldMap;
 }
 
+/** Splits a field map by where each field is stored: base table, translation table, or a side table. */
 export const partitionContentFields = (
   fields: ContentFieldMap,
 ): ContentFieldPartition => {
diff --git a/packages/vitnode/src/content/publication.ts b/packages/vitnode/src/content/publication.ts
index dac77c0554..4b8fc12516 100644
--- a/packages/vitnode/src/content/publication.ts
+++ b/packages/vitnode/src/content/publication.ts
@@ -10,6 +10,7 @@ export const CONTENT_DEFAULT_PUBLICATION_STATUS: ContentPublicationStatus =
 
 export type { ContentPublicationStatus };
 
+/** Reads a row's `status`, treating anything unrecognised as `"draft"`. */
 export const contentPublicationStatus = (
   value: unknown,
 ): ContentPublicationStatus =>
@@ -49,6 +50,7 @@ const UNPUBLISH: ContentPublicationTransition = {
   to: "draft",
 };
 
+/** The transition a publish toggle offers for a record in `value`'s status. */
 export const contentPublicationTransition = (
   value: unknown,
 ): ContentPublicationTransition =>
diff --git a/packages/vitnode/src/content/revisions.ts b/packages/vitnode/src/content/revisions.ts
index 7a9ecedfdc..1cd3b068fa 100644
--- a/packages/vitnode/src/content/revisions.ts
+++ b/packages/vitnode/src/content/revisions.ts
@@ -14,6 +14,7 @@ export type ContentTranslationRevisionOperation =
 
 export type ContentActorType = (typeof CONTENT_ACTOR_TYPES)[number];
 
+/** Who made a content write, as recorded on its revision. `userId` is `null` for system writes. */
 export interface ContentActor {
   type: ContentActorType;
   userId: null | number;
@@ -28,6 +29,12 @@ export type ContentSnapshotValue =
   | Record<string, ContentSnapshotScalar>[]
   | RichTextDocument;
 
+/**
+ * The state of a record's shared fields - to-many relations and repeatables
+ * included - after one editorial write, as stored in a revision. Values are JSON-safe (dates as ISO strings). A
+ * localized content type keeps its translations' history in
+ * {@link ContentTranslationRevisionSnapshot} instead.
+ */
 export interface ContentRevisionSnapshot {
   contentTypeId: string;
   createdAt: string;
@@ -42,6 +49,7 @@ export interface ContentRevisionSnapshot {
   visibility?: { hiddenAt: null | string; hiddenBy: null | number };
 }
 
+/** The state of one translation after one editorial write. */
 export interface ContentTranslationRevisionSnapshot {
   contentTypeId: string;
   createdAt: string;
@@ -103,6 +111,10 @@ const sameSnapshotValue = (
   return JSON.stringify(before) === JSON.stringify(after);
 };
 
+/**
+ * The fields among `names` whose value differs between two snapshots. With no
+ * `before` (the first revision), every named field is listed.
+ */
 export const contentRevisionDiff = (
   names: readonly string[],
   before: ContentRevisionSnapshot | null,
diff --git a/packages/vitnode/src/content/rich-text/document.ts b/packages/vitnode/src/content/rich-text/document.ts
index b793d7a27d..eec3fbba0d 100644
--- a/packages/vitnode/src/content/rich-text/document.ts
+++ b/packages/vitnode/src/content/rich-text/document.ts
@@ -11,6 +11,7 @@ export interface RichTextMark {
   type: string;
 }
 
+/** One node of a rich-text document, in the TipTap/ProseMirror JSON shape. */
 export interface RichTextNode {
   attrs?: RichTextAttrs;
   content?: RichTextNode[];
@@ -19,14 +20,18 @@ export interface RichTextNode {
   type: string;
 }
 
+/** The value of a `field.richText()`: a TipTap/ProseMirror JSON document rooted at `doc`. */
 export interface RichTextDocument extends RichTextNode {
+  /** Always `"doc"`, the root node type. */
   type: "doc";
 }
 
 export const RICH_TEXT_MAX_DEPTH = 64;
 
+/** Default size limit of a serialised document, in bytes (1 MiB). */
 export const RICH_TEXT_DEFAULT_MAX_BYTES = 1024 * 1024;
 
+/** Upper bound any `maxBytes` may raise the limit to, in bytes (16 MiB). */
 export const RICH_TEXT_ABSOLUTE_MAX_BYTES = 16 * 1024 * 1024;
 
 const RICH_TEXT_TYPE_PATTERN = /^[A-Za-z][\w-]{0,63}$/;
@@ -74,6 +79,10 @@ const zodDocumentShape = z.strictObject({
 const utf8Length = (value: string): number =>
   new TextEncoder().encode(value).length;
 
+/**
+ * Checks a document's nesting depth and serialised UTF-8 size. Returns the
+ * first problem as a message, or `null` when it is within limits.
+ */
 export const richTextLimitIssue = (
   value: unknown,
   {
@@ -114,11 +123,19 @@ export const richTextLimitIssue = (
 };
 
 export interface RichTextSchemaOptions {
+  /** Largest serialised document accepted, in bytes. Defaults to 1 MiB. */
   maxBytes?: number;
+  /** Deepest nesting accepted. Defaults to 64. */
   maxDepth?: number;
+  /** Reject an empty document (see {@link isRichTextEmpty}). Defaults to `false`. */
   required?: boolean;
 }
 
+/**
+ * A Zod schema for a rich-text document: checks the node shape (any
+ * well-formed node or mark type name is accepted), the size and the depth,
+ * and with `required` also that the document is not empty.
+ */
 export const createRichTextDocumentSchema = ({
   maxBytes = RICH_TEXT_DEFAULT_MAX_BYTES,
   maxDepth = RICH_TEXT_MAX_DEPTH,
@@ -142,6 +159,7 @@ export const createRichTextDocumentSchema = ({
     : schema;
 };
 
+/** {@link createRichTextDocumentSchema} with the default limits. */
 export const zodRichTextDocument = createRichTextDocumentSchema();
 
 export const isRichTextDocument = (value: unknown): value is RichTextDocument =>
@@ -151,6 +169,7 @@ export const isRichTextDocument = (value: unknown): value is RichTextDocument =>
   "type" in value &&
   value.type === "doc";
 
+/** A new document holding one empty paragraph. */
 export const emptyRichTextDocument = (): RichTextDocument => ({
   content: [{ type: "paragraph" }],
   type: "doc",
@@ -176,6 +195,7 @@ const STRUCTURAL_TYPES: ReadonlySet<string> = new Set([
   "taskList",
 ]);
 
+/** Whether a document has no visible content: only empty structural nodes and whitespace. */
 export const isRichTextEmpty = (
   doc: null | RichTextNode | undefined,
 ): boolean => {
diff --git a/packages/vitnode/src/content/rich-text/html.ts b/packages/vitnode/src/content/rich-text/html.ts
index 84567f92ae..0331bf256b 100644
--- a/packages/vitnode/src/content/rich-text/html.ts
+++ b/packages/vitnode/src/content/rich-text/html.ts
@@ -79,5 +79,10 @@ const renderNode = (node: RichTextNode, depth: number): string => {
   return element ? renderElement(element, inner) : inner;
 };
 
+/**
+ * Renders a rich-text document to an HTML string, e.g. for emails or RSS.
+ * Text and attribute values are escaped, URLs and styles are sanitised, and
+ * nodes or marks without a known element render only their children.
+ */
 export const richTextToHtml = (doc: null | RichTextNode | undefined): string =>
   doc && typeof doc === "object" ? renderNode(doc, 0) : "";
diff --git a/packages/vitnode/src/content/rich-text/plain-text.ts b/packages/vitnode/src/content/rich-text/plain-text.ts
index 6a9f1eb656..dd717843ab 100644
--- a/packages/vitnode/src/content/rich-text/plain-text.ts
+++ b/packages/vitnode/src/content/rich-text/plain-text.ts
@@ -45,6 +45,10 @@ const textOf = (node: RichTextNode, depth: number): string => {
     .join(ROW_TYPES.has(node.type) ? " " : "\n");
 };
 
+/**
+ * Flattens a rich-text document to plain text - block nodes on their own
+ * lines, emojis and mentions as text - for excerpts, search and meta tags.
+ */
 export const richTextToPlainText = (
   doc: null | RichTextNode | undefined,
 ): string => {
diff --git a/packages/vitnode/src/content/schedules.ts b/packages/vitnode/src/content/schedules.ts
index 1e85d4e641..1ff922e171 100644
--- a/packages/vitnode/src/content/schedules.ts
+++ b/packages/vitnode/src/content/schedules.ts
@@ -37,6 +37,12 @@ export interface ContentScheduleTimingInput {
   scheduledFor: Date;
 }
 
+/**
+ * Validates a new schedule's time against the clock and the record's pending
+ * schedules. `null` when it is acceptable; otherwise the error code:
+ * `CONTENT_SCHEDULE_IN_PAST` (more than a short tolerance before `now`) or
+ * `CONTENT_SCHEDULE_ORDER` (an unpublish at or before a pending publish).
+ */
 export const contentScheduleTimingError = ({
   action,
   now,
diff --git a/packages/vitnode/src/content/server/actor.ts b/packages/vitnode/src/content/server/actor.ts
index e98ae5f302..4c74a602ae 100644
--- a/packages/vitnode/src/content/server/actor.ts
+++ b/packages/vitnode/src/content/server/actor.ts
@@ -2,6 +2,11 @@ import type { Context } from "hono";
 
 import type { ContentActor } from "../revisions";
 
+/**
+ * Who a Content Engine write is attributed to (in revisions, and the
+ * `actorUserId` of hide/unhide events): the
+ * AdminCP admin as `staff`, else the signed-in user as `api`, else `system`.
+ */
 export const resolveContentActor = (c: Context): ContentActor => {
   const admin = c.get("admin") as null | { user?: { id?: unknown } };
   const adminId = admin?.user?.id;
diff --git a/packages/vitnode/src/content/server/bind-content-plugin.ts b/packages/vitnode/src/content/server/bind-content-plugin.ts
index c697445257..8184b2fd28 100644
--- a/packages/vitnode/src/content/server/bind-content-plugin.ts
+++ b/packages/vitnode/src/content/server/bind-content-plugin.ts
@@ -5,6 +5,31 @@ import type { AnyContentModel } from "./model";
 import { buildContentAdminModule } from "./module";
 import { buildContentPublicModule } from "./public-module";
 
+/**
+ * Binds the Content Engine's module builders to one plugin, so the generated
+ * modules are registered under its id. Call it once per plugin, typically in
+ * `src/api/builders.ts`, next to `bindApiPlugin`. Server-only.
+ *
+ * - `buildContentAdminModule` mounts the AdminCP CRUD routes of every model
+ *   under the `content` module, one sub-module per `permissionModule`, and
+ *   registers the content types (and their staff permissions), the models
+ *   background tasks need, and the search indexers. Nest it inside the plugin's
+ *   `admin` module.
+ * - `buildContentPublicModule` mounts the public read routes - list, detail,
+ *   preview, thread, delivery and public-write routes as enabled - under
+ *   `content/{publicApi.path}`. Models without `publicApi` are skipped, so both
+ *   builders can take the same array.
+ *
+ * @example
+ * ```ts
+ * import { bindContentPlugin } from "@vitnode/core/content/server";
+ *
+ * import { manifest } from "@/manifest.gen";
+ *
+ * export const { buildContentAdminModule, buildContentPublicModule } =
+ *   bindContentPlugin(manifest);
+ * ```
+ */
 export const bindContentPlugin = <const Plugin extends string>(
   manifest: Pick<PluginManifest<Plugin>, "id">,
 ) => ({
diff --git a/packages/vitnode/src/content/server/delivery-effects.ts b/packages/vitnode/src/content/server/delivery-effects.ts
index cbbb54d1f2..bf0b059097 100644
--- a/packages/vitnode/src/content/server/delivery-effects.ts
+++ b/packages/vitnode/src/content/server/delivery-effects.ts
@@ -9,10 +9,18 @@ import type { ContentDeliveryOutcome } from "./delivery-writes";
 import { reportContentEventFailures } from "./effects-log";
 import { emitContentEvent } from "./emit";
 
+/** The delivery events {@link contentDeliveryEffects} emitted. */
 export interface ContentDeliveryEffectsResult {
   events: EventEmitResult[];
 }
 
+/**
+ * Emits `delivery_slug_changed` when a write moved a record's canonical URL,
+ * and `delivery_redirect_created` when it also left a redirect from the old
+ * path. Emits nothing when the slug did not change or the engine could not
+ * build a canonical path. Listener failures are logged, not thrown.
+ * Called by the editorial and translation effects for types with `delivery`.
+ */
 export const contentDeliveryEffects = async (
   c: Context,
   definition: AnyContentTypeDefinition,
@@ -99,6 +107,11 @@ export const contentDeliveryEffects = async (
   return { events };
 };
 
+/**
+ * The delivery part of a revalidation request: always present for a type with
+ * `delivery` (a shared SEO field can change every locale's `<head>`), with the
+ * sitemap flags from the write's outcome. `undefined` without `delivery`.
+ */
 export const contentDeliveryInvalidation = (
   definition: AnyContentTypeDefinition,
   delivery: ContentDeliveryOutcome | undefined,
diff --git a/packages/vitnode/src/content/server/delivery-routes.ts b/packages/vitnode/src/content/server/delivery-routes.ts
index c08b6d45bb..b076ee2972 100644
--- a/packages/vitnode/src/content/server/delivery-routes.ts
+++ b/packages/vitnode/src/content/server/delivery-routes.ts
@@ -23,6 +23,11 @@ import { listContentLanguages } from "./language-resolver";
 import { contentRecordPageCacheTags } from "./page-cache";
 import { contentIdentifier } from "./route-helpers";
 
+/**
+ * The public delivery routes of a content type with `delivery`:
+ * `/delivery/resolve/{slug}`, `/delivery/item/{id}` and `/delivery/sitemap`.
+ * Mounted with its public routes.
+ */
 export const buildContentDeliveryRoutes = <
   TDefinition extends AnyContentTypeDefinition,
   P extends string,
diff --git a/packages/vitnode/src/content/server/delivery-service.ts b/packages/vitnode/src/content/server/delivery-service.ts
index 49fc26da55..c42d69ec15 100644
--- a/packages/vitnode/src/content/server/delivery-service.ts
+++ b/packages/vitnode/src/content/server/delivery-service.ts
@@ -130,6 +130,10 @@ const localeOf = (
   return typeof row.locale === "string" ? row.locale : null;
 };
 
+/**
+ * Builds the delivery service (canonical URLs, redirects, alternates, sitemap). Plugins use the model's `deliveryService` factory instead,
+ * which passes the right tables and columns.
+ */
 export const createContentDeliveryService = <
   TDefinition extends AnyContentTypeDefinition,
 >({
diff --git a/packages/vitnode/src/content/server/duplicate-effects.ts b/packages/vitnode/src/content/server/duplicate-effects.ts
index 1dca738f92..fb5548eb96 100644
--- a/packages/vitnode/src/content/server/duplicate-effects.ts
+++ b/packages/vitnode/src/content/server/duplicate-effects.ts
@@ -22,6 +22,7 @@ import {
 } from "./search-sync";
 import { contentTranslationEffects } from "./translation-effects";
 
+/** The result of a duplicate, from the editorial or the plain write path. */
 export type ContentDuplicateEffectsInput =
   | {
       kind: "editorial";
@@ -37,6 +38,12 @@ export interface ContentDuplicateEffectsOptions {
   pluginId: string;
 }
 
+/**
+ * The follow-up to a committed duplicate: the copy's create effects (its
+ * `created` event, its search documents and one translation event per copied
+ * translation), then the `duplicated` event. Listener failures are logged, not
+ * thrown. Server-only.
+ */
 export const contentDuplicateEffects = async (
   c: Context,
   model: AnyContentModel,
diff --git a/packages/vitnode/src/content/server/editorial-effects.ts b/packages/vitnode/src/content/server/editorial-effects.ts
index b326e9c5bd..007d979961 100644
--- a/packages/vitnode/src/content/server/editorial-effects.ts
+++ b/packages/vitnode/src/content/server/editorial-effects.ts
@@ -97,20 +97,30 @@ const payloadFor = (
   }
 };
 
+/** Options for {@link contentEditorialEffects}. */
 export interface ContentEditorialEffectsOptions {
+  /**
+   * The model, needed to re-index a localized type (every locale's document)
+   * and to read the collection values a search document includes.
+   */
   model?: AnyContentModel;
   /** The plugin that owns the content type, and therefore the event. */
   pluginId: string;
 
+  /** The user who scheduled the change, for a write run by the scheduler. */
   scheduledBy?: null | number;
 
+  /** The schedule that ran, for a write run by the scheduler. */
   scheduleId?: number;
 }
 
+/** What {@link contentEditorialEffects} did; `event` is `null` when nothing changed. */
 export interface ContentEditorialEffectsResult {
+  /** The delivery events, for a content type with `delivery`. */
   delivery?: ContentDeliveryEffectsResult;
 
   event: EventEmitResult | null;
+  /** The search sync outcome; `null` when nothing changed, or for a localized type with `search` (see `searchByLocale`). */
   search: ContentSearchSyncOutcome | null;
   /**
    * One outcome per language, for a localized content type. Empty for every
@@ -119,6 +129,17 @@ export interface ContentEditorialEffectsResult {
   searchByLocale?: ContentSearchSyncOutcome[];
 }
 
+/**
+ * The follow-up to a committed write made through the editorial service: the
+ * content event (via `emitContentEvent`, which also expires the engine's
+ * page-cache tags), a log entry for any listener that failed, the delivery
+ * events for a slug change or redirect, and the search re-index. Server-only.
+ *
+ * The generated routes call it after every editorial write; a custom write
+ * path through `model.editorialService` must call it too, since the service
+ * itself emits nothing. Does nothing when `outcome.changed` is false. Listener
+ * failures are logged, never thrown - the write has already committed.
+ */
 export const contentEditorialEffects = async (
   c: Context,
   definition: AnyContentTypeDefinition,
diff --git a/packages/vitnode/src/content/server/editorial-service.ts b/packages/vitnode/src/content/server/editorial-service.ts
index 8d93c8d666..f8add3b3b5 100644
--- a/packages/vitnode/src/content/server/editorial-service.ts
+++ b/packages/vitnode/src/content/server/editorial-service.ts
@@ -277,6 +277,10 @@ export interface ContentEditorialRepeatableMethods<TDefinition, TName> {
   ) => Promise<ContentEditorialOutcome<TDefinition> | null>;
 }
 
+/**
+ * Builds the editorial (versioned) write service. Plugins use the model's `editorialService` factory instead,
+ * which passes the right tables and columns.
+ */
 export const createContentEditorialService = <
   TDefinition extends AnyContentTypeDefinition,
 >({
diff --git a/packages/vitnode/src/content/server/emit.ts b/packages/vitnode/src/content/server/emit.ts
index 7950f895c6..dfa4ee7c5c 100644
--- a/packages/vitnode/src/content/server/emit.ts
+++ b/packages/vitnode/src/content/server/emit.ts
@@ -55,6 +55,15 @@ interface ContentEventEmitter {
   ) => Promise<EventEmitResult>;
 }
 
+/**
+ * Emits `content.{definition.id}.{action}` on the request's event bus and then
+ * invalidates the cached pages that show the content type. Call it after the
+ * write's transaction has committed. The generated routes already emit every
+ * built-in event; use this from custom write paths. Server-only.
+ *
+ * @returns The event bus result, with a page-cache invalidation failure, if
+ * any, appended to `failures` rather than thrown.
+ */
 export const emitContentEvent = async (
   c: Context,
   definition: AnyContentTypeDefinition,
diff --git a/packages/vitnode/src/content/server/localized-public-service.ts b/packages/vitnode/src/content/server/localized-public-service.ts
index a173cb39c9..f54e9a1755 100644
--- a/packages/vitnode/src/content/server/localized-public-service.ts
+++ b/packages/vitnode/src/content/server/localized-public-service.ts
@@ -89,6 +89,10 @@ const EMPTY_PAGE = {
   totalCount: 0,
 };
 
+/**
+ * Builds the public read service of a localized content type. Plugins use the model's `publicService` factory instead,
+ * which passes the right tables and columns.
+ */
 export const createContentLocalizedPublicService = <
   TDefinition extends AnyContentTypeDefinition,
 >({
diff --git a/packages/vitnode/src/content/server/localized-service.ts b/packages/vitnode/src/content/server/localized-service.ts
index 3cd8b450eb..21a0a55101 100644
--- a/packages/vitnode/src/content/server/localized-service.ts
+++ b/packages/vitnode/src/content/server/localized-service.ts
@@ -45,6 +45,10 @@ export interface ContentLocalizedService<TDefinition> {
   ) => Promise<ContentLocalizedCreateResult<TDefinition>>;
 }
 
+/**
+ * Builds the service that reads and writes a record with one language's translation. Plugins use the model's `localizedService` factory instead,
+ * which passes the right tables and columns.
+ */
 export const createContentLocalizedService = <
   TDefinition extends AnyContentTypeDefinition,
 >({
diff --git a/packages/vitnode/src/content/server/model.ts b/packages/vitnode/src/content/server/model.ts
index 8dc4b55ceb..867fed5722 100644
--- a/packages/vitnode/src/content/server/model.ts
+++ b/packages/vitnode/src/content/server/model.ts
@@ -46,18 +46,33 @@ export interface ContentModerationScope<TColumn extends string = string> {
   family: string;
 }
 
+/**
+ * The server-side half of a content type: its Drizzle tables and the services
+ * that read and write them. Built by {@link createContentModel}; server-only.
+ *
+ * Every service is a factory taking the request's Hono context, so it runs on
+ * that request's database handle. Services for options the definition did not
+ * enable are `undefined`.
+ */
 export interface ContentModel<TDefinition extends AnyContentTypeDefinition> {
+  /** Reads and writes of to-many relations and repeatable rows. */
   advanced: ContentAdvancedStore;
 
+  /** Generated junction and repeatable child tables. Export them for Drizzle Kit. */
   advancedTables: ContentAdvancedTables;
   /** Column name -> Drizzle column, for filters, ordering and custom queries. */
   columns: Record<ContentColumnName<TDefinition>, PgColumn>;
   definition: TDefinition;
 
+  /** Canonical URLs, redirects, alternates and sitemap entries. Needs `delivery`. */
   deliveryService:
     | ((c: Context, options: { pluginId: string }) => ContentDeliveryService)
     | undefined;
 
+  /**
+   * Versioned writes with revisions, publish/unpublish and schedules.
+   * Needs `editorial`.
+   */
   editorialService:
     | ((
         c: Context,
@@ -67,6 +82,7 @@ export interface ContentModel<TDefinition extends AnyContentTypeDefinition> {
 
   localization: ResolvedContentLocalizationConfig;
 
+  /** Reads and writes a record together with one language's translation. Needs `localization`. */
   localizedService:
     | ((
         c: Context,
@@ -75,6 +91,7 @@ export interface ContentModel<TDefinition extends AnyContentTypeDefinition> {
     | undefined;
 
   moderationScope: ContentModerationScope | null;
+  /** Public, allowlisted reads of published records. Needs `publicApi`. */
   publicService:
     | ((c: Context) => ContentPublicService<TDefinition>)
     | undefined;
@@ -93,6 +110,7 @@ export interface ContentModel<TDefinition extends AnyContentTypeDefinition> {
     PgColumn
   >;
 
+  /** Editorial operations on one translation. Needs `editorial` and `localization`. */
   translationEditorialService:
     | ((
         c: Context,
@@ -102,10 +120,12 @@ export interface ContentModel<TDefinition extends AnyContentTypeDefinition> {
   /** The per-language schemas, or `null`. Mirrored off `schemas.translation`. */
   translationSchemas: ContentTranslationSchemas<TDefinition> | null;
 
+  /** Raw access to translation rows. Needs `localization`. */
   translationService:
     | ((c: Context) => ContentTranslationModel<TDefinition>)
     | undefined;
 
+  /** The generated `<tableName>_translations` table, or `null`. Export it for Drizzle Kit. */
   translationTable: ContentTranslationTableFor<TDefinition> | null;
 }
 
@@ -147,6 +167,36 @@ export const findContentModel = (
 ): RegisteredContentModel | undefined =>
   models.find(entry => entry.model.definition.id === contentTypeId);
 
+/**
+ * Builds the {@link ContentModel} of a content type: generates its Drizzle
+ * tables and wires its services. Call it once per content type in the plugin's
+ * `src/database/*.ts` and export every table it generates, so Drizzle Kit can
+ * discover them. Server-only.
+ *
+ * @param definition The result of `defineContentType()`.
+ * @param options.references Target columns of `field.relation()` fields, as
+ * thunks, so the foreign key can point at a table defined in another file.
+ * Self-relations need none.
+ * @param options.moderationScope `{ column, family }`: the column whose value
+ * scopes moderator permissions, e.g. the category or container a record
+ * belongs to.
+ *
+ * @example
+ * ```ts
+ * import { createContentModel } from "@vitnode/core/content/server";
+ *
+ * import { blogPostContentType } from "@/content/post";
+ *
+ * import { blog_categories } from "./categories";
+ *
+ * export const postContent = createContentModel(blogPostContentType, {
+ *   references: { categoryId: () => blog_categories.id },
+ * });
+ *
+ * export const blog_posts = postContent.table;
+ * export const blog_posts_translations = postContent.translationTable;
+ * ```
+ */
 export const createContentModel = <
   TDefinition extends AnyContentTypeDefinition,
 >(
diff --git a/packages/vitnode/src/content/server/module.ts b/packages/vitnode/src/content/server/module.ts
index a23c0d95a7..2789f1b3ad 100644
--- a/packages/vitnode/src/content/server/module.ts
+++ b/packages/vitnode/src/content/server/module.ts
@@ -11,6 +11,14 @@ import {
 } from "./search-indexer";
 import { assertContentReferences } from "./table";
 
+/**
+ * The generated AdminCP module, named `content`. Prefer the plugin-bound
+ * version from `bindContentPlugin()`.
+ *
+ * Resolves every relation's foreign key while building, so a reference whose
+ * target column is missing or has the wrong key type fails at boot rather than
+ * at the first query.
+ */
 export const buildContentAdminModule = <P extends string>({
   containers = [],
   contentTypes,
diff --git a/packages/vitnode/src/content/server/public-module.ts b/packages/vitnode/src/content/server/public-module.ts
index 0bede64a33..de5be4daec 100644
--- a/packages/vitnode/src/content/server/public-module.ts
+++ b/packages/vitnode/src/content/server/public-module.ts
@@ -52,6 +52,14 @@ export type ContentPublicModule<
   )[]
 >;
 
+/**
+ * The generated public module, named `content`, with one sub-module per
+ * content type (or container) that has `publicApi`, at its `publicApi.path`.
+ * Prefer the plugin-bound version from `bindContentPlugin()`.
+ *
+ * The return type carries every generated route, which is what lets
+ * `fetcher({ module: "content/blog", path: "/{slug}" })` infer its response.
+ */
 export const buildContentPublicModule = <
   const P extends string,
   const Models extends readonly AnyContentModel[],
diff --git a/packages/vitnode/src/content/server/public-routes.ts b/packages/vitnode/src/content/server/public-routes.ts
index 1017d3122f..de877b7326 100644
--- a/packages/vitnode/src/content/server/public-routes.ts
+++ b/packages/vitnode/src/content/server/public-routes.ts
@@ -67,6 +67,11 @@ import {
 } from "./revision-snapshot";
 import { readContentThread } from "./thread";
 
+/**
+ * The public routes of one content type: list and detail, plus preview,
+ * delivery, thread and public-write routes when the definition enables them.
+ * `buildContentPublicModule` mounts them; plugins do not call this directly.
+ */
 export const buildContentPublicRoutes = <
   TDefinition extends AnyContentTypeDefinition,
   P extends string,
diff --git a/packages/vitnode/src/content/server/public-service.ts b/packages/vitnode/src/content/server/public-service.ts
index c816d25891..45eb6f1aec 100644
--- a/packages/vitnode/src/content/server/public-service.ts
+++ b/packages/vitnode/src/content/server/public-service.ts
@@ -47,10 +47,15 @@ import {
 export { nestContentPublicRow } from "./public-row-hydration";
 
 export interface ContentPublicReadOptions {
+  /** Language to read, on a localized content type. Defaults to `localization.defaultLocale`. */
   locale?: string;
 }
 
 export interface ContentPublicItemReadOptions extends ContentPublicReadOptions {
+  /**
+   * Read a published record a moderator has *hidden*, instead of a visible
+   * one. Defaults to `false`.
+   */
   hidden?: boolean;
   /**
    * Only these exposed fields, and no `publicApi.people` - for an internal
@@ -62,6 +67,11 @@ export interface ContentPublicItemReadOptions extends ContentPublicReadOptions {
 }
 
 export interface ContentPublicSlugReadOptions extends ContentPublicItemReadOptions {
+  /**
+   * On a localized content type with `fallback: "default"`, also match the
+   * slug of the default-language translation when the requested language has
+   * none.
+   */
   fallback?: boolean;
 }
 
@@ -84,6 +94,15 @@ export interface ContentPublicFindManyArgs<
   };
 }
 
+/**
+ * Public reads of one content type, from `model.publicService(c)`.
+ * Server-only.
+ *
+ * Every read returns the {@link ContentPublicSelect} projection - only the
+ * `publicApi.fields` allowlist ever leaves the database - and only records that
+ * are published, with `publishedAt` in the past, and not hidden (unless
+ * `hidden: true` asks for hidden ones).
+ */
 export interface ContentPublicService<TDefinition> {
   /** `null` unless the row exists *and* is published. */
   findById: (
@@ -91,10 +110,12 @@ export interface ContentPublicService<TDefinition> {
     options?: ContentPublicItemReadOptions,
   ) => Promise<ContentPublicSelect<TDefinition> | null>;
 
+  /** The published record answering to `slug`, or `null`. */
   findBySlug: (
     slug: string,
     options?: ContentPublicSlugReadOptions,
   ) => Promise<ContentPublicSelect<TDefinition> | null>;
+  /** One page of published records, filtered and ordered within the public allowlists. */
   findMany: (args?: ContentPublicFindManyArgs<TDefinition>) => Promise<{
     edges: ContentPublicListRow<TDefinition>[];
     pageInfo: ContentPageInfo;
@@ -148,6 +169,15 @@ export const contentPublicSelectProjection = (
   };
 };
 
+/**
+ * The function that turns a selected row into a content type's public shape:
+ * only the fields and people `projection` names (by default every
+ * `publicApi.fields` and `publicApi.people` entry; to-one relations as `{ id }`,
+ * to-many as ids, people as hydrated summaries), never other columns. Resolve
+ * files before projecting.
+ *
+ * @throws {ContentEngineError} When the content type has no `publicApi`.
+ */
 export const createContentPublicProjector = <
   TDefinition extends AnyContentTypeDefinition,
 >(
@@ -255,6 +285,10 @@ const pick = (
 ): Record<string, unknown> =>
   Object.fromEntries(keys.map(key => [key, values[key] ?? null]));
 
+/**
+ * The columns a public read selects: `id`, the `publicApi.people` user ids
+ * (later swapped for public summaries) and the exposed field columns.
+ */
 export const contentPublicSelection = (
   definition: AnyContentTypeDefinition,
   columns: Record<string, PgColumn>,
@@ -321,6 +355,10 @@ export const clampContentPublicPageSize = (
   return String(Math.min(parsed, CONTENT_PUBLIC_MAX_PAGE_SIZE));
 };
 
+/**
+ * Builds the public read service of a non-localized content type. Plugins use the model's `publicService` factory instead,
+ * which passes the right tables and columns.
+ */
 export const createContentPublicService = <
   TDefinition extends AnyContentTypeDefinition,
 >({
diff --git a/packages/vitnode/src/content/server/public-write-routes.ts b/packages/vitnode/src/content/server/public-write-routes.ts
index fb93ca24e6..ecc66a5bad 100644
--- a/packages/vitnode/src/content/server/public-write-routes.ts
+++ b/packages/vitnode/src/content/server/public-write-routes.ts
@@ -182,6 +182,11 @@ const rejection = (description: string) => ({
   description,
 });
 
+/**
+ * Every public-write route of one content type (create, the "may I edit"
+ * check, and update), whatever `publicWrite` enables. Use
+ * {@link contentPublicWriteRoutes} for only the enabled ones.
+ */
 export const buildContentPublicWriteRoutes = <
   TDefinition extends AnyContentTypeDefinition,
   P extends string,
@@ -349,6 +354,7 @@ type PublicWriteRoutes<
   P extends string,
 > = ReturnType<typeof buildContentPublicWriteRoutes<TDefinition, P>>;
 
+/** The public-write routes a definition's `publicWrite` enables, as a type. */
 export type ContentPublicWriteRoutesOf<
   TDefinition extends AnyContentTypeDefinition,
   P extends string,
@@ -362,6 +368,11 @@ export type ContentPublicWriteRoutesOf<
           | PublicWriteRoutes<TDefinition, P>["update"]
       : never);
 
+/**
+ * The public-write routes `publicWrite` enables: `create` when
+ * `publicWrite.create` is enabled, `editable` and `update` when
+ * `publicWrite.update` is. Empty without `publicWrite`. Mounted by the public routes.
+ */
 export const contentPublicWriteRoutes = <
   TDefinition extends AnyContentTypeDefinition,
   P extends string,
diff --git a/packages/vitnode/src/content/server/public-write-service.ts b/packages/vitnode/src/content/server/public-write-service.ts
index 451e6b483b..6db4be9f36 100644
--- a/packages/vitnode/src/content/server/public-write-service.ts
+++ b/packages/vitnode/src/content/server/public-write-service.ts
@@ -147,6 +147,19 @@ export const resolveContentPublicationPolicy = async ({
   return { approval: true, policy, status: "draft" };
 };
 
+/**
+ * The service behind a content type's public-write routes, for a plugin's own
+ * write route with the same ownership, authorization and effects. Acts as the
+ * user session of `c`. `create` and `update` run the same write effects as the
+ * generated routes (events, search) after the commit; an owner's edit that
+ * needs review becomes a proposal and runs none of them. Server-only.
+ *
+ * @throws From its methods: `ContentPublicWriteDenied` for an unauthenticated,
+ * forbidden or missing request (also `notFound` when `create`/`update` is off,
+ * or `create` has no `ownerField`); `ContentPublicWriteInputError` for an
+ * invalid relation target or container placement; a `ZodError` for invalid
+ * values; `ContentVersionConflict` for a stale `expectedVersion`.
+ */
 export const createContentPublicWriteService = <
   TDefinition extends AnyContentTypeDefinition,
 >({
diff --git a/packages/vitnode/src/content/server/publication.ts b/packages/vitnode/src/content/server/publication.ts
index 9328b32b46..96cd8ce701 100644
--- a/packages/vitnode/src/content/server/publication.ts
+++ b/packages/vitnode/src/content/server/publication.ts
@@ -8,12 +8,32 @@ import type { ContentPublicationMethods, ContentService } from "./service";
 
 import { ContentEngineError } from "../errors";
 
+/**
+ * The columns the published predicates read. `hiddenAt` is present only when
+ * the content type has `visibility`.
+ */
 export interface PublicationColumns {
   hiddenAt?: PgColumn;
   publishedAt: PgColumn;
   status: PgColumn;
 }
 
+/**
+ * Picks the publication columns out of a model's column map, for building
+ * your own published-only queries with {@link publishedCondition}.
+ *
+ * @throws {ContentEngineError} When the content type has no `publication`, or
+ * has `visibility` but the column map has no `hiddenAt`.
+ *
+ * @example
+ * ```ts
+ * import { publicationColumns, publishedCondition } from "@vitnode/core/content/server";
+ *
+ * const isPublic = publishedCondition(
+ *   publicationColumns(topicContent.definition, topicContent.columns),
+ * );
+ * ```
+ */
 export const publicationColumns = (
   definition: AnyContentTypeDefinition,
   columns: Record<string, PgColumn>,
@@ -39,6 +59,11 @@ export const publicationColumns = (
   return { hiddenAt, publishedAt, status };
 };
 
+/**
+ * The SQL condition for a publicly visible record: `status` is `published`,
+ * `publishedAt` is set and not in the future (database `now()`), and - when
+ * the type has visibility - `hiddenAt` is null.
+ */
 export const publishedCondition = (
   columns: PublicationColumns,
 ): SQL | undefined =>
@@ -59,12 +84,23 @@ const hiddenPublishedCondition = (
         isNotNull(columns.hiddenAt),
       );
 
+/**
+ * {@link publishedCondition}, or with `hidden: true` its opposite for hidden
+ * records: published rows whose `hiddenAt` is set (`false` without visibility).
+ */
 export const contentPublicReadCondition = (
   columns: PublicationColumns,
   { hidden = false }: { hidden?: boolean } = {},
 ): SQL | undefined =>
   hidden ? hiddenPublishedCondition(columns) : publishedCondition(columns);
 
+/**
+ * {@link publicationColumns} for a localized type's translation table, whose
+ * rows have their own `status` and `publishedAt`.
+ *
+ * @throws {ContentEngineError} Unless the type has both `localization` and
+ * `publication`.
+ */
 export const contentTranslationPublicationColumns = (
   definition: AnyContentTypeDefinition,
   translationColumns: Record<string, PgColumn>,
@@ -86,6 +122,10 @@ export const contentTranslationPublicationColumns = (
   return { publishedAt, status };
 };
 
+/**
+ * The published condition for a record and, when given, its translation: both
+ * must pass {@link publishedCondition}.
+ */
 export const contentPublicCondition = (
   base: PublicationColumns,
   translation?: PublicationColumns,
@@ -94,6 +134,11 @@ export const contentPublicCondition = (
     ? publishedCondition(base)
     : and(publishedCondition(base), publishedCondition(translation));
 
+/**
+ * Narrows a content service to its publish/unpublish methods.
+ *
+ * @throws {ContentEngineError} When the content type has no `publication`.
+ */
 export const publicationMethods = <
   TDefinition extends AnyContentTypeDefinition,
 >(
diff --git a/packages/vitnode/src/content/server/revalidate-bridge.ts b/packages/vitnode/src/content/server/revalidate-bridge.ts
index 23a937cd4a..9fdb3c60c6 100644
--- a/packages/vitnode/src/content/server/revalidate-bridge.ts
+++ b/packages/vitnode/src/content/server/revalidate-bridge.ts
@@ -55,6 +55,20 @@ const sleep = async (ms: number): Promise<void> =>
 const originsFor = (c: Context): string[] =>
   c.get("core")?.contentRevalidateOrigins ?? [];
 
+/**
+ * Tells external front ends that a write expired some content cache tags, by
+ * POSTing the request to `{origin}/api/vitnode/content/revalidate` on every
+ * origin in the install's `content.revalidateOrigins`. Server-only; the
+ * engine calls it after a scheduled publish/unpublish runs and after a
+ * hide/unhide that changes public reachability.
+ *
+ * Best effort and never throws: each origin gets two attempts (a `403` is not
+ * retried), authenticated with `CRON_SECRET` as a bearer token and a timestamp
+ * header. Nothing is sent when the write expired no tags, no origin is
+ * configured, or `CRON_SECRET` is unset, or still the default outside
+ * development. Outside development, only `https` origins (or `http` on
+ * localhost) are notified.
+ */
 export const dispatchContentRevalidation = async (
   c: Context,
   input: ContentRevalidationRequest,
diff --git a/packages/vitnode/src/content/server/routes.ts b/packages/vitnode/src/content/server/routes.ts
index 7914cf2b3b..aa54b19d1f 100644
--- a/packages/vitnode/src/content/server/routes.ts
+++ b/packages/vitnode/src/content/server/routes.ts
@@ -168,7 +168,10 @@ const advancedForSearch = async (
 };
 
 /**
- * The five CRUD routes plus the picker-options route for one content type.
+ * The five CRUD routes plus the picker-options route for one content type,
+ * and every admin route its options add (revisions, schedules, translations,
+ * duplicates, uploads and more). `buildContentAdminModule` mounts them; plugins
+ * do not call this directly.
  *
  * Every route carries an explicit `adminStaffPermission`, and every path sits
  * under `/admin/` so the global admin session middleware runs - both are
diff --git a/packages/vitnode/src/content/server/search-indexer.ts b/packages/vitnode/src/content/server/search-indexer.ts
index bf1c718b8a..a3c1cd5abb 100644
--- a/packages/vitnode/src/content/server/search-indexer.ts
+++ b/packages/vitnode/src/content/server/search-indexer.ts
@@ -171,6 +171,7 @@ const assertPublicationColumns = (
   }
 };
 
+/** A content type's search indexer, which loads its documents page by page for a rebuild. */
 export interface ContentSearchIndexer extends SearchIndexer {
   load: (
     c: Context,
@@ -198,6 +199,13 @@ export interface ContentSearchRelationIndexer extends ContentSearchIndexer {
   ) => Promise<ContentSearchRelationPage>;
 }
 
+/**
+ * The search indexer for a non-localized content type, used to rebuild its
+ * documents. `buildContentAdminModule` registers one for every model with
+ * `search`, so plugins rarely call this.
+ *
+ * @throws {ContentEngineError} When the content type has no `publication`.
+ */
 export const createContentSearchIndexer = <
   TDefinition extends AnyContentTypeDefinition,
 >(
@@ -346,6 +354,13 @@ export const createContentSearchIndexer = <
   };
 };
 
+/**
+ * {@link createContentSearchIndexer} for a localized content type: it pages
+ * over translations, one document per record and language.
+ *
+ * @throws {ContentEngineError} When the content type has no `localization` or
+ * no `publication`.
+ */
 export const createContentLocalizedSearchIndexer = <
   TDefinition extends AnyContentTypeDefinition,
 >(
diff --git a/packages/vitnode/src/content/server/search-sync.ts b/packages/vitnode/src/content/server/search-sync.ts
index 4458ecf0dc..bf2400afbc 100644
--- a/packages/vitnode/src/content/server/search-sync.ts
+++ b/packages/vitnode/src/content/server/search-sync.ts
@@ -52,9 +52,12 @@ const isReachabilityOperation = (operation: ContentSearchOperation): boolean =>
   operation === "hide" ||
   operation === "unhide";
 
+/** What {@link syncContentSearch} needs to know about one committed write. */
 export interface ContentSearchSyncInput {
+  /** The record's advanced collection values, when the search document includes any. */
   advanced?: Record<string, unknown>;
 
+  /** `publish`, `unpublish`, `hide` and `unhide` only: `false` when nothing moved. */
   changed?: boolean;
   /**
    * `update` and `restore` only. A write that touched no indexed field changes
@@ -68,6 +71,7 @@ export interface ContentSearchSyncInput {
   row: object;
 }
 
+/** What the sync did to the record's search document. */
 export interface ContentSearchSyncOutcome {
   action: "delete" | "skip" | "upsert";
   /** `"example.article:7"` - for logs and diagnostics, never a storage key. */
@@ -103,6 +107,20 @@ const decide = (
     : "skip";
 };
 
+/**
+ * Brings one record's search document in line with a committed write on a
+ * non-localized content type: deletes it on `delete`, writes it on `create`,
+ * on a publication or visibility change that moved something, and on an
+ * update or restore that changed an indexed field, and otherwise skips. A row
+ * the document builder rejects has its document removed. Skips everything
+ * for a type without `search`.
+ *
+ * Search-engine errors are logged and returned on `error`, never thrown,
+ * because the write itself has already committed. Loading the related context
+ * reads the database, and that read can still throw. The effects helpers call
+ * it for you; call it directly only from a custom write path that does not
+ * use them.
+ */
 export const syncContentSearch = async (
   c: Context,
   definition: AnyContentTypeDefinition,
@@ -450,6 +468,7 @@ export const syncContentSearchContainerDependents = async (
   }
 };
 
+/** {@link ContentSearchSyncInput} for a localized content type. */
 export interface ContentLocalizedSearchSyncInput {
   /**
    * The record's shared advanced collections, when the content type indexes one.
diff --git a/packages/vitnode/src/content/server/service.ts b/packages/vitnode/src/content/server/service.ts
index 331dea7459..ddefdfd574 100644
--- a/packages/vitnode/src/content/server/service.ts
+++ b/packages/vitnode/src/content/server/service.ts
@@ -103,10 +103,12 @@ import {
 /** Display labels for `user` and `relation` values, keyed by field name. */
 export type ContentLabels = Record<string, null | string>;
 
+/** A list row: the base-table row plus display labels for its reference fields. */
 export type ContentListRow<TDefinition> = ContentSelect<TDefinition> & {
   labels: ContentLabels;
 };
 
+/** Pagination metadata of a `findMany` page, cursor- or page-based. */
 export interface ContentPageInfo {
   count: number;
   currentPage: null | number;
@@ -145,6 +147,7 @@ export interface ContentServiceOptions {
   tx?: ContentDatabase;
 }
 
+/** A write's new row and the field paths whose value actually changed. */
 export interface ContentUpdateResult<TDefinition> {
   changedFields: ContentChangedPath<TDefinition>[];
   row: ContentSelect<TDefinition>;
@@ -253,6 +256,20 @@ export interface ContentPublicationMethods<TDefinition> {
   ) => Promise<ContentPublicationResult<TDefinition> | null>;
 }
 
+/**
+ * The typed repository of one content type, from `model.service(c)`.
+ * Server-only.
+ *
+ * Validates input against the generated schemas and writes the base table,
+ * its junction and child tables. It is deliberately low level: it emits no
+ * events, records no revisions and expires no caches - and neither does
+ * `model.editorialService`. Custom write paths must follow up the way the
+ * generated routes do: `emitContentEvent`, or `contentPlainWriteEffects` /
+ * `contentEditorialEffects` after an `editorialService` write.
+ *
+ * Publication, visibility and duplication methods exist only when the
+ * definition enables them.
+ */
 export type ContentService<TDefinition> = ContentServiceBase<TDefinition> &
   ContentVisibilityMembers<TDefinition, ContentVisibilityMethods<TDefinition>> &
   (TDefinition extends { duplication: { enabled: true } }
@@ -269,6 +286,7 @@ export interface ContentServiceBase<TDefinition> {
     options?: ContentServiceOptions,
   ) => Promise<ContentAdvancedValues<TDefinition>>;
 
+  /** Only the named to-many relations and repeatables of one record. */
   advancedFields: (
     id: ContentIdOf<TDefinition>,
     fields: readonly string[],
@@ -279,19 +297,23 @@ export interface ContentServiceBase<TDefinition> {
     values: ContentCreateInput<TDefinition>,
     options?: ContentServiceOptions,
   ) => Promise<ContentSelect<TDefinition>>;
+  /** Deletes a record and returns the deleted row, or `null` when it did not exist. */
   delete: (
     id: ContentIdOf<TDefinition>,
     options?: ContentServiceOptions,
   ) => Promise<ContentSelect<TDefinition> | null>;
+  /** The base-table row, or `null`. */
   findById: (
     id: ContentIdOf<TDefinition>,
     options?: ContentServiceOptions,
   ) => Promise<ContentSelect<TDefinition> | null>;
 
+  /** The base-table row plus its to-many relations and repeatables, or `null`. */
   findDetail: (
     id: ContentIdOf<TDefinition>,
     options?: ContentServiceOptions,
   ) => Promise<ContentDetail<TDefinition> | null>;
+  /** One page of rows with labels, filtered, ordered and searched as the admin list is. */
   findMany: (args?: ContentFindManyArgs<TDefinition>) => Promise<{
     edges: ContentListRow<TDefinition>[];
     pageInfo: ContentPageInfo;
@@ -302,12 +324,17 @@ export interface ContentServiceBase<TDefinition> {
     options?: ContentServiceOptions,
   ) => Promise<ContentListRow<TDefinition> | null>;
 
+  /**
+   * Picker options for a `relation` or `user` field: matching `search`, or the
+   * given `ids` when resolving current values.
+   */
   options: (
     field: ContentReferenceFieldName<TDefinition>,
     search?: string,
     ids?: readonly ContentId[],
   ) => Promise<{ color?: string; label: string; value: ContentId }[]>;
 
+  /** Typed operations on each to-many relation, keyed by field name. */
   relations: {
     [K in ContentRelationCollectionName<TDefinition>]: ContentRelationMethods<
       TDefinition,
@@ -451,6 +478,10 @@ const contentServiceShape = ({
   return shape;
 };
 
+/**
+ * Builds the typed repository behind `ContentModel.service`. Plugins use the model's `service` factory instead,
+ * which passes the right tables and columns.
+ */
 export const createContentService = <
   TDefinition extends AnyContentTypeDefinition,
 >({
diff --git a/packages/vitnode/src/content/server/table.ts b/packages/vitnode/src/content/server/table.ts
index 5287144228..a3574b9254 100644
--- a/packages/vitnode/src/content/server/table.ts
+++ b/packages/vitnode/src/content/server/table.ts
@@ -204,6 +204,24 @@ const resolveReference = (
   );
 };
 
+/**
+ * Builds a content type's Drizzle `pgTable` (with RLS enabled): the system
+ * columns (`id`, `createdAt`, `updatedAt`), the publication, editorial and
+ * visibility columns the definition enables, one column per shared scalar, to-one relation and group leaf
+ * (collections live in their own tables), and
+ * the definition's indexes. Localized fields live on the translation table
+ * instead ({@link createContentTranslationTable}).
+ *
+ * Usually called for you by `createContentModel`. Every relation except a
+ * self-relation needs a `references` thunk to its target's `id` (to-many ones
+ * for their junction table); file,
+ * user and container fields reference core's tables by themselves.
+ *
+ * @throws {ContentEngineError} When `definition` is missing (often a
+ * half-built plugin `dist` or a circular import), when a relation has no
+ * `references` entry, a self-relation has one, or `references` names a field
+ * that is not a relation.
+ */
 export const createContentTable = <
   TDefinition extends AnyContentTypeDefinition,
 >(
@@ -314,12 +332,22 @@ export const createContentTable = <
   return table as unknown as ContentTableFor<TDefinition>;
 };
 
+/**
+ * Resolves every foreign-key thunk on a content table now, so a broken
+ * reference fails here rather than at the first query.
+ * `buildContentAdminModule` calls it for every model it is given.
+ */
 export const assertContentReferences = (table: PgTable): void => {
   for (const foreignKey of getTableConfig(table).foreignKeys) {
     foreignKey.reference();
   }
 };
 
+/**
+ * Column name -> Drizzle column for a content table: the system,
+ * publication, editorial and visibility columns the definition enables, every
+ * shared field, and the non-localized advanced-field leaves (keyed by path).
+ */
 export const contentTableColumns = <
   TDefinition extends AnyContentTypeDefinition,
 >(
diff --git a/packages/vitnode/src/content/server/translation-editorial-service.ts b/packages/vitnode/src/content/server/translation-editorial-service.ts
index 879d8ba287..1a820774be 100644
--- a/packages/vitnode/src/content/server/translation-editorial-service.ts
+++ b/packages/vitnode/src/content/server/translation-editorial-service.ts
@@ -144,6 +144,10 @@ export interface ContentRevisionDetailForLocale extends ContentRevisionMeta {
   snapshot: ContentTranslationRevisionSnapshot;
 }
 
+/**
+ * Builds the editorial service for one translation. Plugins use the model's `translationEditorialService` factory instead,
+ * which passes the right tables and columns.
+ */
 export const createContentTranslationEditorialService = <
   TDefinition extends AnyContentTypeDefinition,
 >({
diff --git a/packages/vitnode/src/content/server/translation-effects.ts b/packages/vitnode/src/content/server/translation-effects.ts
index 983db77d97..9a4a7a38dc 100644
--- a/packages/vitnode/src/content/server/translation-effects.ts
+++ b/packages/vitnode/src/content/server/translation-effects.ts
@@ -97,12 +97,15 @@ const publicStateFor = (
   }
 };
 
+/** Options for {@link contentTranslationEffects}. */
 export interface ContentTranslationEffectsOptions {
+  /** The model, needed to re-index the translation's search document. */
   model?: AnyContentModel;
   /** The plugin that owns the content type, and therefore the event. */
   pluginId: string;
 }
 
+/** What {@link contentTranslationEffects} did; `event` is `null` when nothing changed. */
 export interface ContentTranslationEffectsResult {
   /**
    * The delivery events this translation mutation emitted, or `undefined` for a
@@ -115,6 +118,13 @@ export interface ContentTranslationEffectsResult {
   search?: ContentSearchSyncOutcome[];
 }
 
+/**
+ * The follow-up to a committed write on one translation: the content event,
+ * a log entry for failed listeners, the delivery events for a type with
+ * `delivery`, and - for a type with `search` when `model` is given and the
+ * record still exists - a re-index of that one locale's search document.
+ * Does nothing when `outcome.changed` is false. Server-only.
+ */
 export const contentTranslationEffects = async (
   c: Context,
   definition: AnyContentTypeDefinition,
diff --git a/packages/vitnode/src/content/server/translation-model.ts b/packages/vitnode/src/content/server/translation-model.ts
index 6164212749..929d27f50c 100644
--- a/packages/vitnode/src/content/server/translation-model.ts
+++ b/packages/vitnode/src/content/server/translation-model.ts
@@ -180,6 +180,10 @@ const toNullableDate = (value: unknown): Date | null => {
   return Number.isNaN(parsed.getTime()) ? null : parsed;
 };
 
+/**
+ * Builds raw access to a localized type's translation rows. Plugins use the model's `translationService` factory instead,
+ * which passes the right tables and columns.
+ */
 export const createContentTranslationModel = <
   TDefinition extends AnyContentTypeDefinition,
 >({
diff --git a/packages/vitnode/src/content/server/translation-routes.ts b/packages/vitnode/src/content/server/translation-routes.ts
index 2e887d766a..3385008984 100644
--- a/packages/vitnode/src/content/server/translation-routes.ts
+++ b/packages/vitnode/src/content/server/translation-routes.ts
@@ -47,6 +47,10 @@ import {
 import { contentTranslationEffects } from "./translation-effects";
 import { withTranslationHttpErrors } from "./translation-http-errors";
 
+/**
+ * The admin routes for a localized content type's translations, mounted with
+ * the rest of its admin routes by `buildContentRoutes`.
+ */
 export const buildContentTranslationRoutes = <
   TDefinition extends AnyContentTypeDefinition,
   P extends string,
diff --git a/packages/vitnode/src/content/server/translation-table.ts b/packages/vitnode/src/content/server/translation-table.ts
index 54c4f1fe2b..3f268d5ab1 100644
--- a/packages/vitnode/src/content/server/translation-table.ts
+++ b/packages/vitnode/src/content/server/translation-table.ts
@@ -27,6 +27,14 @@ import {
   buildTranslationSystemColumns,
 } from "./column-builders";
 
+/**
+ * Builds a localized content type's `<tableName>_translations` table: one row
+ * per record and language, holding the localized fields (plus their own
+ * publication columns when the type has `publication`). Usually called for
+ * you by `createContentModel`.
+ *
+ * @throws {ContentEngineError} When the content type has no `localization`.
+ */
 export const createContentTranslationTable = <
   TDefinition extends AnyContentTypeDefinition,
 >(
diff --git a/packages/vitnode/src/content/server/visibility-effects.ts b/packages/vitnode/src/content/server/visibility-effects.ts
index cb93e4ae59..7c34fe6e02 100644
--- a/packages/vitnode/src/content/server/visibility-effects.ts
+++ b/packages/vitnode/src/content/server/visibility-effects.ts
@@ -20,6 +20,7 @@ import { contentDefinitionOf } from "./model";
 import { contentPublicLocaleStates } from "./public-locales";
 import { dispatchContentRevalidation } from "./revalidate-bridge";
 
+/** {@link contentEditorialEffects}'s result plus how many revalidation origins were tried and reached. */
 export interface ContentVisibilityEffectsResult extends ContentEditorialEffectsResult {
   revalidation: { attempted: number; delivered: number };
 }
@@ -30,6 +31,12 @@ const NOTHING: ContentVisibilityEffectsResult = {
   search: null,
 };
 
+/**
+ * The revalidation request a hide or unhide sends to `content.revalidateOrigins`:
+ * the record, its slug, whether it was and is public, the locales whose
+ * public state changed, and the sitemap flags for a type with `delivery`.
+ * Always `mode: "immediate"`.
+ */
 export const contentVisibilityRevalidation = async (
   c: Context,
   model: AnyContentModel,
@@ -84,6 +91,12 @@ export const contentVisibilityRevalidation = async (
   };
 };
 
+/**
+ * The follow-up to a committed hide or unhide: {@link contentEditorialEffects},
+ * then a revalidation request (`dispatchContentRevalidation`) to the
+ * configured front-end origins. Does nothing when the outcome changed nothing
+ * or carries no visibility change.
+ */
 export const contentVisibilityEffects = async (
   c: Context,
   model: AnyContentModel,
diff --git a/packages/vitnode/src/content/server/write-effects.ts b/packages/vitnode/src/content/server/write-effects.ts
index 62b9dc9d60..0b61e9d6e9 100644
--- a/packages/vitnode/src/content/server/write-effects.ts
+++ b/packages/vitnode/src/content/server/write-effects.ts
@@ -90,6 +90,10 @@ export const contentPlainWriteEffects = async <
   });
 };
 
+/**
+ * Runs {@link contentEditorialEffects} for each outcome in order, skipping
+ * `null`s - for a write that produced several editorial outcomes.
+ */
 export const contentEditorialWriteEffects = async <
   TDefinition extends AnyContentTypeDefinition,
 >(
diff --git a/packages/vitnode/src/content/sitemap.ts b/packages/vitnode/src/content/sitemap.ts
index e45547ec75..fc9f8aada9 100644
--- a/packages/vitnode/src/content/sitemap.ts
+++ b/packages/vitnode/src/content/sitemap.ts
@@ -39,6 +39,11 @@ const absolute = (origin: string, path: string): null | string => {
 /** `priority` at the one precision the protocol illustrates, without a float tail. */
 const formatPriority = (priority: number): string => priority.toFixed(1);
 
+/**
+ * A `<urlset>` sitemap document from sitemap entries. Paths resolve against
+ * the entry's own `origin` or `origin`; an entry whose URL cannot be built is
+ * skipped. `changefreq` and `priority` are left out when `null`.
+ */
 export const contentSitemapXml = ({
   alternates,
   entries,
diff --git a/packages/vitnode/src/content/types.ts b/packages/vitnode/src/content/types.ts
index 614a5abdc1..c91950c6d4 100644
--- a/packages/vitnode/src/content/types.ts
+++ b/packages/vitnode/src/content/types.ts
@@ -51,6 +51,7 @@ export type ContentTranslationSystemField =
 export type ContentPublicationStatus =
   (typeof CONTENT_PUBLICATION_STATUSES)[number];
 
+/** Postgres `ON DELETE` behaviour of a reference column when its target row is deleted. */
 export type ContentOnDelete = "cascade" | "restrict" | "set null";
 
 /** Flattens intersections so editor tooltips show the real shape. */
@@ -66,9 +67,13 @@ export type Prettify<T> = { [K in keyof T]: T[K] } & {};
 // derived from them.
 // ---------------------------------------------------------------------------
 
+/** Lets a registered AI action suggest a field's value in the AdminCP form. */
 export interface ContentFieldAiAssist {
+  /** The AI action's `{pluginId}:{actionId}` key, e.g. `"@vitnode/blog:excerpt.generate"`. */
   action: `${string}:${string}`;
+  /** The result is offered to the editor as a suggestion to accept. */
   mode: "suggestion";
+  /** Fields of the same record whose current values are sent to the action. */
   sourceFields: readonly string[];
 }
 
@@ -79,6 +84,7 @@ export interface ContentFieldShared<
   /** Free text or an i18n key surfaced in AdminCP and OpenAPI. */
   description?: string;
 
+  /** Value lives in the translation table, one per language. See `localization`. */
   localized?: boolean;
   /** Column accepts NULL, and `null` is a legal value. */
   nullable: TNullable;
@@ -256,6 +262,11 @@ interface ContentReferenceCollection {
   multiple: true;
 }
 
+/**
+ * A relation target with a known id strategy. Annotate a `target` thunk with
+ * it (`(): ContentRelationTarget<"uuid"> => tags`) when two content type
+ * modules import each other and TypeScript falls back to serial ids.
+ */
 export type ContentRelationTarget<
   TStrategy extends ContentIdStrategy = ContentIdStrategy,
 > = AnyContentTypeDefinition & { idStrategy: TStrategy };
@@ -720,7 +731,9 @@ export interface ContentAdminListConfig<
     | ContentDisplayColumn<TFields, TPublication, TEditorial>
     | ContentReferenceListFieldKeys<TFields>
   )[];
+  /** Direction of the initial sort. */
   defaultOrder?: "asc" | "desc";
+  /** Column of the initial sort. */
   defaultOrderBy?: ContentAddressableColumn<TFields, TPublication, TEditorial>;
   /**
    * Allowlist for `orderBy`. System columns - and the publication columns when
@@ -732,6 +745,7 @@ export interface ContentAdminListConfig<
    * localized field matches its value in any language.
    */
   searchableFields?: ScalarDisplayFieldKeys<TFields>[];
+  /** A single `field.file()` used as each row's thumbnail in the list. */
   thumbnailField?: ContentSingleFileFieldKeys<TFields>;
 }
 
@@ -816,7 +830,9 @@ export interface ContentAdminConfig<
     fields?: (keyof TFields)[];
     sections?: ContentAdminFormSection<TFields>[];
   };
+  /** Columns, ordering and search of the generated list screen. */
   list?: ContentAdminListConfig<TFields, TPublication, TEditorial>;
+  /** Show the content type in the AdminCP sidebar. Defaults to `true`. */
   navigation?: boolean;
   /**
    * Where the generated screens live under `/admin/content/`. Defaults to the id
@@ -911,10 +927,12 @@ export interface ContentIndexInput<
 > {
   /** Defaults to `<table>_<columns>_idx`, or `_key` when unique. */
   name?: string;
+  /** Indexed columns, in order: shared fields, group leaf paths, system and option columns. */
   on: [
     ContentIndexColumn<TFields, TPublication, TEditorial>,
     ...ContentIndexColumn<TFields, TPublication, TEditorial>[],
   ];
+  /** Creates a unique index. Defaults to `false`. */
   unique?: boolean;
 }
 
@@ -998,11 +1016,23 @@ type ContentVisibilityColumns<TDefinition> = TDefinition extends {
   ? { hiddenAt: Date | null; hiddenBy: null | number }
   : Record<never, never>;
 
+/** Options for `reports`. Every field named here must be a field of the content type. */
 export interface ContentReportsConfig<TField extends string = string> {
+  /**
+   * Fields copied into the report when it is filed, so moderators see what was
+   * reported even after an edit. Self-contained kinds only (text, textarea,
+   * rich text, slug, number, boolean, enum, date, file). Defaults to the public
+   * text, textarea, rich text, enum and file fields other than the title field.
+   */
   snapshotFields?: TField[];
+  /**
+   * A text, textarea or slug field used as the report's title. Defaults to
+   * `admin.titleField` when it is public, otherwise none.
+   */
   titleField?: TField;
 }
 
+/** `true` for the defaults, an options object, or `false`/omitted to disable reporting. */
 export type ContentReportsInput<TField extends string = string> =
   | boolean
   | ContentReportsConfig<TField>;
@@ -1032,6 +1062,11 @@ export interface ResolvedContentReportsConfig<
 }
 
 export interface ContentDuplicationConfig {
+  /**
+   * Append a translated "(Copy)" to the copy's title. Applied by default when
+   * `admin.titleField` is a text field; `true` makes that a requirement and
+   * `false` turns it off.
+   */
   titleSuffix?: boolean;
 }
 
@@ -1109,6 +1144,7 @@ export interface ContentPublicApiConfig<
   TPath extends string = string,
   TPeople extends string = string,
 > {
+  /** Direction of the list route's default order. */
   defaultOrder?: "asc" | "desc";
   /** Defaults to `publishedAt`. Must be orderable. */
   defaultOrderBy?: "publishedAt" | TField;
@@ -1192,26 +1228,44 @@ export type ContentPublicOwnershipField<TFields> = string &
       : never;
   }[keyof TFields];
 
+/** The generated public create route. */
 export interface ContentPublicWriteCreateConfig<
   TField extends string = string,
 > {
+  /** Require a captcha token on create. Defaults to `false`. */
   captcha?: boolean;
+  /** The fields a visitor may send. Anything else in the payload is rejected. */
   fields: readonly [TField, ...TField[]];
+  /** Status a publicly created record starts in. Defaults to `"draft"`. */
   status?: ContentPublicationStatus;
 }
 
+/** The generated public update route. */
 export interface ContentPublicWriteUpdateConfig<
   TField extends string = string,
 > {
+  /** The fields a visitor may change. Container fields cannot be moved here. */
   fields: readonly [TField, ...TField[]];
+  /**
+   * Owners may edit their own records. Defaults to `true`. Moderators with the
+   * content type's `can_edit` moderator permission may edit any record.
+   */
   own?: boolean;
 }
 
+/**
+ * Public writing for signed-in users. At least one of `create` and `update`
+ * is required; there is no public delete.
+ */
 export interface ContentPublicWriteConfig<
   TField extends string = string,
   TOwner extends string = string,
 > {
   create?: ContentPublicWriteCreateConfig<TField>;
+  /**
+   * A single, shared `field.user()` holding the record's owner. The server
+   * sets it from the session on create; it is never read from the payload.
+   */
   ownership: { field: TOwner };
   update?: ContentPublicWriteUpdateConfig<TField>;
 }
@@ -1438,13 +1492,25 @@ export interface ContentSearchConfig<
   TText extends string = string,
   TAuthor extends string = string,
 > {
+  /** A top-level `field.user()` credited as the result's author. */
   authorField?: TAuthor;
   /** Concatenated into the indexed body, in order. At least one. */
   contentFields: readonly [TText, ...TText[]];
+  /**
+   * The record this one belongs to in results - a `field.container()` (needs a
+   * `pathTemplate`) or a to-one `field.relation()` (must not have one).
+   * Defaults to the relation `titleField` borrows its title from, if any.
+   */
   context?: ContentSearchContextInput;
   /** Prepended to the indexed body so it shows up in result excerpts. */
   descriptionField?: TDescription;
+  /** A shared, single `field.file()` in `publicApi.fields`, shown beside the result. */
   imageField?: string;
+  /**
+   * The result's URL, relative to the site root, with exactly one `{slug}`
+   * placeholder, e.g. `/blog/{slug}`. The locale prefix is added by the i18n
+   * routing, not the template.
+   */
   pathTemplate: string;
   /** The result heading. Weighted above the body by the index. */
   titleField: TTitle;
@@ -1632,10 +1698,21 @@ export interface ContentDeliveryConfig<
   TDescription extends string = string,
   TNoIndex extends string = string,
 > {
+  /** Emit an `x-default` alternate. Needs `localization`. */
   hreflang?: ContentDeliveryHreflangConfig;
+  /**
+   * The canonical page route, with exactly one `:slug` parameter. Defaults to
+   * `/{publicApi.path}/:slug`. Cannot start with `/admin` or `/api`.
+   */
   path?: string;
+  /**
+   * Remember every slug a record was publicly reachable under and redirect
+   * old URLs (308). Needs `editorial`. Defaults to `false`.
+   */
   redirects?: TEditorialEnabled extends true ? boolean : false;
+  /** Which public fields fill `<title>`, the description and Open Graph tags. */
   seo?: ContentDeliverySeoConfig<TTitle, TDescription, TNoIndex>;
+  /** List published records in the sitemap. Needs `publication`. Off unless set. */
   sitemap?: boolean | ContentDeliverySitemapConfig;
 }
 
@@ -1704,17 +1781,28 @@ export interface ContentEditorialPreviewConfig {
   /** How long a link stays valid. 1-1440 minutes, defaults to 15. */
   expiresInMinutes?: number;
 
+  /**
+   * The frontend page that renders a preview, relative to the site root, with
+   * exactly one `{token}` placeholder, e.g. `/blog/preview/{token}`.
+   */
   pathTemplate?: string;
 }
 
+/** Options for `editorial`. `true` is the same as `{}`. */
 export interface ContentEditorialConfig<
   TPublicEnabled extends boolean = boolean,
   TPublication extends boolean = boolean,
 > {
+  /**
+   * Signed, expiring links that show a draft's public projection. Needs
+   * `publicApi`. Off unless set.
+   */
   preview?: TPublicEnabled extends true
     ? boolean | ContentEditorialPreviewConfig
     : false;
+  /** Revision history kept per record. Always on with `editorial`. */
   revisions?: ContentEditorialRevisionsConfig;
+  /** Schedule a publish or unpublish for later. Needs `publication`. Defaults to `false`. */
   scheduling?: TPublication extends true ? boolean : false;
 }
 
@@ -1767,9 +1855,19 @@ type ContentEditorialColumns<TDefinition> = TDefinition extends {
 export type ContentLocalizationFallback =
   (typeof CONTENT_LOCALIZATION_FALLBACKS)[number];
 
+/** Options for `localization`. Enabling it requires at least one `localized: true` field. */
 export interface ContentLocalizationConfig {
+  /**
+   * The locale code (e.g. `"en"`, `"pt-BR"`) every record is first created in.
+   * Must exist in `core_languages` on the installation.
+   */
   defaultLocale: string;
 
+  /**
+   * What a public read returns for a language with no translation of its own:
+   * `"none"` (default) returns nothing, `"default"` serves the default locale's
+   * translation and reports the served `locale` in the response.
+   */
   fallback?: ContentLocalizationFallback;
 }
 
@@ -1921,6 +2019,14 @@ export interface ContentLeafColumn {
   path: string;
 }
 
+/**
+ * A **resolved** content type, as returned by `defineContentType()`.
+ *
+ * Every option is normalised (`enabled` flags, defaults filled in) and the
+ * generic parameters carry what was enabled, so services, routes and inferred
+ * row types (`ContentSelect`, `ContentPublicSelect`, ...) can tell at compile
+ * time which columns and capabilities exist. Not meant to be written by hand.
+ */
 export interface ContentTypeDefinition<
   TId extends string = string,
   TFields = ContentFieldMap,
@@ -2044,6 +2150,14 @@ type ContentBindSelfRelations<TFields, TStrategy extends ContentIdStrategy> = {
     : TFields[K];
 };
 
+/**
+ * One base-table row as the admin service returns it: every shared column
+ * field, the system columns, and the columns enabled options add (`status`,
+ * `publishedAt`, `version`, `hiddenAt`, ...).
+ *
+ * Localized values live in translation rows, and to-many relations and
+ * repeatables in {@link ContentAdvancedValues}, so neither is here.
+ */
 export type ContentSelect<TDefinition> = Prettify<
   ContentEditorialColumns<TDefinition> &
     ContentPublicationColumns<TDefinition> &
@@ -2054,6 +2168,7 @@ export type ContentSelect<TDefinition> = Prettify<
     } & { createdAt: Date; id: ContentIdOf<TDefinition>; updatedAt: Date }
 >;
 
+/** A single record's admin read: {@link ContentSelect} plus its to-many relations and repeatables. */
 export type ContentDetail<TDefinition> = Prettify<
   ContentAdvancedValues<TDefinition> & ContentSelect<TDefinition>
 >;
@@ -2061,6 +2176,7 @@ export type ContentDetail<TDefinition> = Prettify<
 /** The base-table half of a create payload. See {@link ContentSharedValues}. */
 export type ContentCreateInput<TDefinition> = ContentSharedValues<TDefinition>;
 
+/** A partial update of the base-table (shared) fields. Every property is optional. */
 export type ContentUpdateInput<TDefinition> = Prettify<{
   [K in SharedFieldKeys<ContentFieldsOf<TDefinition>>]?: ContentFieldPatch<
     ContentFieldsOf<TDefinition>[K]
@@ -2119,6 +2235,10 @@ type ContentCollectionFilters<TDefinition, TName extends PropertyKey> = {
   >;
 };
 
+/**
+ * Admin list filters: equality on filterable shared fields, `{ contains }` on
+ * to-many relations, plus `status` and `visibility` when those options are on.
+ */
 export type ContentFilterInput<TDefinition> = Partial<
   ContentCollectionFilters<
     TDefinition,
@@ -2379,11 +2499,13 @@ export type ContentPublicUpdateFieldName<TDefinition> = TDefinition extends {
   ? TField
   : never;
 
+/** The `values` a visitor may send to the public create route: only `publicWrite.create.fields`. */
 export type ContentPublicCreateInput<TDefinition> = CreateValuesOf<
   ContentFieldsOf<TDefinition>,
   ContentPublicCreateFieldName<TDefinition> & keyof ContentFieldsOf<TDefinition>
 >;
 
+/** The `values` a visitor may send to the public update route: only `publicWrite.update.fields`. */
 export type ContentPublicUpdateInput<TDefinition> = Prettify<{
   [
     K in ContentPublicUpdateFieldName<TDefinition> &
@@ -2395,6 +2517,7 @@ export interface ContentPublicCreateBody<TDefinition> {
   values: ContentPublicCreateInput<TDefinition>;
 }
 
+/** Public update body. With `editorial`, `expectedVersion` guards against overwriting a newer edit. */
 export type ContentPublicUpdateBody<TDefinition> = Prettify<
   (TDefinition extends { editorial: { enabled: true } }
     ? { expectedVersion: number }
@@ -2403,6 +2526,7 @@ export type ContentPublicUpdateBody<TDefinition> = Prettify<
   }
 >;
 
+/** What the public write routes return to the record's author. */
 export type ContentPublicWriteRecord<TDefinition> = Prettify<
   ContentEditorialColumns<TDefinition> & {
     /**
diff --git a/packages/vitnode/src/content/visibility.ts b/packages/vitnode/src/content/visibility.ts
index b3f7db9d70..a505fa3e9b 100644
--- a/packages/vitnode/src/content/visibility.ts
+++ b/packages/vitnode/src/content/visibility.ts
@@ -4,6 +4,7 @@ import type { ContentVisibilityFilter } from "./types";
 export type ContentVisibilityAction =
   (typeof CONTENT_VISIBILITY_ACTIONS)[number];
 
+/** Whether a moderator has hidden the record (`hiddenAt` is set). */
 export const isContentHidden = (row: { hiddenAt?: unknown }): boolean =>
   row.hiddenAt !== null && row.hiddenAt !== undefined && row.hiddenAt !== "";
 
@@ -25,6 +26,7 @@ const UNHIDE: ContentVisibilityTransition = {
   to: "visible",
 };
 
+/** The hide/unhide transition a moderator toggle offers for this row. */
 export const contentVisibilityTransition = (row: {
   hiddenAt?: unknown;
 }): ContentVisibilityTransition => (isContentHidden(row) ? UNHIDE : HIDE);
diff --git a/packages/vitnode/src/editor/adapter/memory.ts b/packages/vitnode/src/editor/adapter/memory.ts
index 4fde36e345..c3c75c1c0e 100644
--- a/packages/vitnode/src/editor/adapter/memory.ts
+++ b/packages/vitnode/src/editor/adapter/memory.ts
@@ -4,6 +4,13 @@ export interface MemoryVisualEditorAdapter extends VisualEditorAdapter {
   saves: readonly VisualEditorSaveInput[];
 }
 
+/**
+ * An adapter that only records each save in `saves` - for tests, demos and
+ * prototypes. Nothing is persisted.
+ *
+ * @param options.delay Milliseconds to wait before resolving, to simulate a request.
+ * @param options.onSave Called with each save input.
+ */
 export const createMemoryAdapter = ({
   delay = 0,
   onSave,
diff --git a/packages/vitnode/src/editor/adapter/refusal.ts b/packages/vitnode/src/editor/adapter/refusal.ts
index ee7d7d0654..14954fd009 100644
--- a/packages/vitnode/src/editor/adapter/refusal.ts
+++ b/packages/vitnode/src/editor/adapter/refusal.ts
@@ -1,5 +1,6 @@
 import type { VisualEditorSaveRefusal } from "./types";
 
+/** The `refusal` message of a thrown {@link VisualEditorSaveRefusal}, if it is one. */
 export const saveRefusalOf = (cause: unknown): string | undefined => {
   if (typeof cause !== "object" || cause === null) return undefined;
 
@@ -10,6 +11,7 @@ export const saveRefusalOf = (cause: unknown): string | undefined => {
     : undefined;
 };
 
+/** Whether a thrown value is a refusal marked `conflict: true`. */
 export const isSaveConflict = (cause: unknown): boolean =>
   saveRefusalOf(cause) !== undefined &&
   (cause as Partial<VisualEditorSaveRefusal>).conflict === true;
diff --git a/packages/vitnode/src/editor/adapter/save-input.ts b/packages/vitnode/src/editor/adapter/save-input.ts
index 61dfd11108..9fb5267812 100644
--- a/packages/vitnode/src/editor/adapter/save-input.ts
+++ b/packages/vitnode/src/editor/adapter/save-input.ts
@@ -7,6 +7,7 @@ import type { VisualEditorSaveInput } from "./types";
 
 import { changedZoneIds } from "../state/reducer";
 
+/** Builds the save payload from editor state: every zone, the changed ids and their baselines. */
 export const buildSaveInput = (
   state: VisualEditorState,
 ): VisualEditorSaveInput => {
diff --git a/packages/vitnode/src/editor/adapter/types.ts b/packages/vitnode/src/editor/adapter/types.ts
index 15ac7936da..4c788cdabc 100644
--- a/packages/vitnode/src/editor/adapter/types.ts
+++ b/packages/vitnode/src/editor/adapter/types.ts
@@ -1,22 +1,41 @@
 /* oxlint-disable typescript/no-invalid-void-type */
 import type { VisualEditorSnapshot } from "../state/types";
 
+/** What the Visual Editor hands its adapter on **Save**. */
 export interface VisualEditorSaveInput {
+  /** Zones that differ from what loaded - write only these. */
   changedZoneIds: readonly string[];
+  /**
+   * For each changed zone, the baseline it started from. Compare it with what
+   * is stored to refuse a save that would overwrite someone else's.
+   */
   expectedZones: VisualEditorSnapshot;
+  /** Every mounted zone keyed by id, emptied ones included. */
   zones: VisualEditorSnapshot;
 }
 
 export interface VisualEditorSaveResult {
   revision?: string;
+  /** The zones as stored; the editor rebases onto them instead of what it sent. */
   zones?: VisualEditorSnapshot;
 }
 
+/**
+ * Throw an object of this shape from `save` to show `refusal` to the editor
+ * instead of a generic error. With `conflict: true` the editor shows its own
+ * someone-saved-first message instead of `refusal`. The editor keeps the
+ * unsaved changes either way.
+ */
 export interface VisualEditorSaveRefusal {
   conflict?: boolean;
   refusal: string;
 }
 
+/**
+ * Persists Visual Editor changes - the editor itself never fetches. Resolve to
+ * mark the editor clean; throw or reject to keep the changes and show an
+ * error. Editable pages get one from `createContentEditorAdapter`.
+ */
 export interface VisualEditorAdapter {
   save: (
     input: VisualEditorSaveInput,
diff --git a/packages/vitnode/src/emails/default-template.tsx b/packages/vitnode/src/emails/default-template.tsx
index 8fa1989733..1c6d492b25 100644
--- a/packages/vitnode/src/emails/default-template.tsx
+++ b/packages/vitnode/src/emails/default-template.tsx
@@ -38,31 +38,61 @@ DefaultTemplateEmail.PreviewProps = {
   },
 } satisfies DefaultTemplateEmailProps & { children: React.ReactNode };
 
+/**
+ * What `c.get("email").send()` passes to an email's `content`, and what
+ * {@link DefaultTemplateEmail} reads. Spread them into the template unchanged.
+ */
 export interface DefaultTemplateEmailProps extends Pick<
   EmailModelSendArgs,
   "user"
 > {
+  /** The recipient's locale and its messages, for translating the email. */
   i18n: {
     locale: string;
     // oxlint-disable-next-line typescript/no-explicit-any
     messages: Record<string, any>;
   };
   templateProps: {
+    /** Extra elements for the email's `<head>`. */
     head?: React.ReactNode;
+    /** The header logo, from the API config's `email.logo`. Without `src`, `text` (or the site title) is shown as text. */
     logo?: {
       src?: string;
       text?: string;
     };
+    /** The site's title and URL, used in the header and the footer link. */
     metadata: {
       shortTitle?: string;
       title: string;
       url: string;
     };
+    /** The inbox preview line shown after the subject. */
     previewText?: string;
+    /** Extends the template's Tailwind config; `theme.extend.colors` overrides the built-in color tokens. */
     tailwindConfig?: TailwindConfig;
   };
 }
 
+/**
+ * VitNode's standard email layout: the site logo (or title), your content, and
+ * a footer linking to the site. It wraps everything in react-email's
+ * `<Tailwind>` with the color tokens (`bg-primary`, `text-muted-foreground`...)
+ * that `EmailButton` and `EmailCard` use. Rendered on the server by
+ * `c.get("email")`.
+ *
+ * @example
+ * ```tsx
+ * import DefaultTemplateEmail, {
+ *   type DefaultTemplateEmailProps,
+ * } from "@vitnode/core/emails/default-template";
+ *
+ * export const WelcomeEmail = (props: DefaultTemplateEmailProps) => (
+ *   <DefaultTemplateEmail {...props}>Welcome!</DefaultTemplateEmail>
+ * );
+ *
+ * await c.get("email").send({ user, subject: "Welcome", content: props => <WelcomeEmail {...props} /> });
+ * ```
+ */
 export default function DefaultTemplateEmail({
   children,
   i18n: { locale },
diff --git a/packages/vitnode/src/emails/ui/button.tsx b/packages/vitnode/src/emails/ui/button.tsx
index 595ef66621..f95094fd27 100644
--- a/packages/vitnode/src/emails/ui/button.tsx
+++ b/packages/vitnode/src/emails/ui/button.tsx
@@ -28,6 +28,13 @@ const buttonVariants = cva(
   },
 );
 
+/**
+ * A link styled as a button for emails, built on react-email's `Button`. Pass
+ * `href` and children; `variant` (`default`, `destructive`, `destructiveGhost`,
+ * `outline`, `secondary`, `ghost`, `link`; default `default`) and `size`
+ * (`default`, `sm`, `lg`; default `default`) pick the style. Its colors come from `DefaultTemplateEmail`, so use it
+ * inside that template.
+ */
 export const EmailButton = ({
   className,
   variant,
diff --git a/packages/vitnode/src/emails/ui/card.tsx b/packages/vitnode/src/emails/ui/card.tsx
index 9bfb0dde8c..36466fb6a6 100644
--- a/packages/vitnode/src/emails/ui/card.tsx
+++ b/packages/vitnode/src/emails/ui/card.tsx
@@ -1,6 +1,11 @@
 import { cn } from "cn";
 import { Section, Text } from "react-email";
 
+/**
+ * A bordered, rounded card for an email's message, with header, title,
+ * description, content and footer parts. Colors come from
+ * `DefaultTemplateEmail`, so use it inside that template.
+ */
 export const EmailCard = ({
   className,
   ...props
@@ -16,6 +21,7 @@ export const EmailCard = ({
   );
 };
 
+/** The card's top section, for the title and description. */
 export const EmailCardHeader = ({
   className,
   ...props
@@ -23,6 +29,7 @@ export const EmailCardHeader = ({
   return <Section className={cn("mb-6 px-6", className)} {...props} />;
 };
 
+/** The card's heading text. */
 export const EmailCardTitle = ({
   className,
   ...props
@@ -35,6 +42,7 @@ export const EmailCardTitle = ({
   );
 };
 
+/** Muted, smaller text under the title. */
 export const EmailCardDescription = ({
   className,
   ...props
@@ -47,6 +55,7 @@ export const EmailCardDescription = ({
   );
 };
 
+/** The card's main section. */
 export const EmailCardContent = ({
   className,
   ...props
@@ -54,6 +63,7 @@ export const EmailCardContent = ({
   return <Section className={cn("px-6", className)} {...props} />;
 };
 
+/** The card's bottom section, e.g. for a button. */
 export const EmailCardFooter = ({
   className,
   ...props
diff --git a/packages/vitnode/src/framework/api-registry/generate.ts b/packages/vitnode/src/framework/api-registry/generate.ts
index b3d344b0c5..a4ab046027 100644
--- a/packages/vitnode/src/framework/api-registry/generate.ts
+++ b/packages/vitnode/src/framework/api-registry/generate.ts
@@ -2,6 +2,7 @@ import type { ResolvedApiPluginModule } from "./types.js";
 
 import { toSingleQuotedLiteral } from "../plugin-routes/resolve.js";
 
+/** The module whose `ApiPluginRegistry` interface the generated files augment. */
 export const API_REGISTRY_SPECIFIER = "@vitnode/core/lib/fetcher/registry";
 
 /** The one type every plugin's `config.api.ts` exports for this file to read. */
@@ -47,6 +48,11 @@ const entryLines = (modules: readonly ResolvedApiPluginModule[]): string =>
     )
     .join("\n");
 
+/**
+ * The source of an app's `src/api-registry.gen.ts`: one type-only registry
+ * entry per configured plugin with a `config.api` module, sorted by plugin id.
+ * Build tooling, called by the VitNode Vite plugin.
+ */
 export const generateApiRegistrySource = (
   modules: readonly ResolvedApiPluginModule[],
 ): string => {
diff --git a/packages/vitnode/src/framework/api-registry/types.ts b/packages/vitnode/src/framework/api-registry/types.ts
index 36a009fc41..bf0d05d2c5 100644
--- a/packages/vitnode/src/framework/api-registry/types.ts
+++ b/packages/vitnode/src/framework/api-registry/types.ts
@@ -1,3 +1,4 @@
+/** A configured plugin whose `config.api` module resolved. */
 export interface ResolvedApiPluginModule {
   pluginId: string;
   specifier: string;
diff --git a/packages/vitnode/src/framework/dev-error/hints.ts b/packages/vitnode/src/framework/dev-error/hints.ts
index 79175bb465..45fea650d0 100644
--- a/packages/vitnode/src/framework/dev-error/hints.ts
+++ b/packages/vitnode/src/framework/dev-error/hints.ts
@@ -1,10 +1,29 @@
+/** One suggested fix, shown on the development error page under the error. */
 export interface DevErrorHint {
+  /** What to change and why, in one or two sentences. */
   description: string;
+  /** Code to copy, rendered as a code block. */
   snippet?: string;
+  /** The fix in a few words, shown as the hint's heading. */
   title: string;
 }
 
+/**
+ * An error that carries fix suggestions for the development error page.
+ * Implement it on a custom `Error` class thrown for a configuration mistake;
+ * production responses never show the hints.
+ *
+ * @example
+ * ```ts
+ * class MyConfigError extends Error implements DevErrorWithHints {
+ *   readonly hints = [
+ *     { title: "Set a title", description: "Add `metadata.title` to the config." },
+ *   ];
+ * }
+ * ```
+ */
 export interface DevErrorWithHints {
+  /** The suggestions; malformed entries are skipped. */
   readonly hints: readonly DevErrorHint[];
 }
 
@@ -20,6 +39,7 @@ const isHint = (value: unknown): value is DevErrorHint => {
   );
 };
 
+/** The well-formed hints an error carries, or `[]`. */
 export const devErrorHintsOf = (error: unknown): DevErrorHint[] => {
   if (typeof error !== "object" || error === null || !("hints" in error)) {
     return [];
diff --git a/packages/vitnode/src/framework/plugin-routes/compile.ts b/packages/vitnode/src/framework/plugin-routes/compile.ts
index 82d8137905..925e621540 100644
--- a/packages/vitnode/src/framework/plugin-routes/compile.ts
+++ b/packages/vitnode/src/framework/plugin-routes/compile.ts
@@ -12,10 +12,13 @@ import { generatePluginRoutesSource } from "./generate.js";
 import { assertNoHostRouteCollision } from "./host-routes.js";
 import { assertLocaleRoutePaths } from "./locale-route-paths.js";
 
+/** One configured plugin, as the route compiler reads it. */
 export interface PluginRouteCompilerSource {
   pluginId: string;
+  /** The plugin's `routes` declaration, as `buildPlugin` received it. */
   routes?: unknown;
 
+  /** The import specifier of the plugin's routes module, written into the generated file. */
   routesSpecifier?: string;
 }
 
@@ -31,12 +34,24 @@ export interface CompiledPluginRoutes {
 }
 
 export interface CompilePluginRoutesOptions {
+  /** Plugins' public content URLs, each of which must be served by a page. */
   contentUrls?: readonly ContentUrlSource[];
+  /** The app's own routes, which plugin routes must not collide with. */
   hostRoutes?: readonly HostRoutePath[];
+  /** The app's `i18n` config, to validate translated route paths against. */
   i18n?: LocaleRoutePathsConfig;
   sources: readonly PluginRouteCompilerSource[];
 }
 
+/**
+ * Compiles every configured plugin's routes into one manifest and the source
+ * of the app's `src/plugin-routes.gen.ts`. Build tooling: the VitNode Vite
+ * plugin and CLI call it; apps and plugins do not.
+ *
+ * @throws When a plugin's routes are invalid or collide with each other or the
+ * app's routes, when translated route paths are invalid, or when a public
+ * content URL has no page. Errors name the plugin's routes module.
+ */
 export const compilePluginRoutes = ({
   contentUrls = [],
   hostRoutes = [],
diff --git a/packages/vitnode/src/framework/vite/dev-error.ts b/packages/vitnode/src/framework/vite/dev-error.ts
index 0333bf034b..08cd935f23 100644
--- a/packages/vitnode/src/framework/vite/dev-error.ts
+++ b/packages/vitnode/src/framework/vite/dev-error.ts
@@ -35,6 +35,11 @@ const withNitroDevError = (): UserConfig => {
   return config as UserConfig;
 };
 
+/**
+ * In `vite dev`, registers Nitro handlers that answer unhandled server errors
+ * in HTML requests with VitNode's development error page, including any hints
+ * the error carries. Does nothing in a build.
+ */
 export const vitNodeDevError = (): Plugin => ({
   config: (_userConfig, { command }) =>
     command === "serve" ? withNitroDevError() : undefined,
diff --git a/packages/vitnode/src/framework/vite/env.ts b/packages/vitnode/src/framework/vite/env.ts
index ad60987148..7e4dd720ce 100644
--- a/packages/vitnode/src/framework/vite/env.ts
+++ b/packages/vitnode/src/framework/vite/env.ts
@@ -5,9 +5,18 @@ import { loadEnv } from "vite";
 const CLIENT_ENV_KEYS = ["VITNODE_API_URL", "VITNODE_WEB_URL"] as const;
 
 export interface VitNodeEnvOptions {
+  /**
+   * More environment variables to expose to the browser as
+   * `process.env.NAME`, besides `VITNODE_API_URL` and `VITNODE_WEB_URL`. Their
+   * values end up in the client bundle - never list a secret.
+   */
   clientEnv?: readonly string[];
 }
 
+/**
+ * Loads the whole `.env` into `process.env` for the server (variables already
+ * set in the environment win) and defines the public keys for the browser.
+ */
 export const vitNodeEnv = ({
   clientEnv = [],
 }: VitNodeEnvOptions = {}): Plugin => {
diff --git a/packages/vitnode/src/framework/vite/optimize-deps.ts b/packages/vitnode/src/framework/vite/optimize-deps.ts
index 2039da5b27..46d3d9e0a6 100644
--- a/packages/vitnode/src/framework/vite/optimize-deps.ts
+++ b/packages/vitnode/src/framework/vite/optimize-deps.ts
@@ -148,6 +148,11 @@ export const postcssBrowserEmptyImports = (): Rolldown.Plugin => ({
   },
 });
 
+/**
+ * In `vite dev`, pre-bundles the browser dependencies VitNode's components
+ * import, so the first page load does not trigger a dependency re-optimization
+ * and a full reload.
+ */
 export const vitNodeOptimizeDeps = (): Plugin => ({
   apply: "serve",
   config: userConfig => {
diff --git a/packages/vitnode/src/framework/vite/plugin-routes.ts b/packages/vitnode/src/framework/vite/plugin-routes.ts
index 591fd635df..200095c065 100644
--- a/packages/vitnode/src/framework/vite/plugin-routes.ts
+++ b/packages/vitnode/src/framework/vite/plugin-routes.ts
@@ -91,8 +91,15 @@ const ERROR_PREFIX = "[VitNode plugin routes]";
 const DEFAULT_HOST_ROUTES_DIR = join("src", "routes");
 
 export interface VitNodePluginRoutesOptions {
+  /** The app's root directory, where `src/vitnode.config.ts` lives. */
   appRoot: string;
 
+  /**
+   * Where the app's own route files are, relative to `appRoot`. They are read
+   * so plugin routes can be checked for collisions with them and content URLs
+   * can count them as pages. Defaults to the `routesDirectory` in
+   * `tsr.config.json`, else `src/routes`; `null` reads none.
+   */
   hostRoutesDir?: null | string;
 }
 
@@ -737,6 +744,16 @@ const newBuildId = (): string =>
   process.env.VITNODE_BUILD_ID ??
   `${Date.now().toString(36)}-${randomBytes(4).toString("hex")}`;
 
+/**
+ * Generates the app's `src/*.gen.ts` registries from the plugins configured in
+ * `src/vitnode.config.ts` - plugin routes, API registry, AdminCP navigation and
+ * content registry, widgets, package messages, page cache and plugin
+ * inventory - and regenerates them in `vite dev` when a plugin changes.
+ *
+ * Fails `vite dev` and `vite build` when plugin routes collide with each other
+ * or the app's routes, translated route paths are invalid, or a public content
+ * URL has no page.
+ */
 export const vitNodePluginRoutes = (
   options: VitNodePluginRoutesOptions,
 ): Plugin<VitNodePluginRoutesApi> => {
diff --git a/packages/vitnode/src/framework/vite/prerender-routes.ts b/packages/vitnode/src/framework/vite/prerender-routes.ts
index cb9791aa24..add0e2de0c 100644
--- a/packages/vitnode/src/framework/vite/prerender-routes.ts
+++ b/packages/vitnode/src/framework/vite/prerender-routes.ts
@@ -3,13 +3,16 @@ import type { LocaleConfig, VitNodeI18nConfig } from "@/lib/i18n/types";
 import { localeRoutingFromConfig } from "@/lib/i18n/locale-routing";
 
 export interface PrerenderRoutesOptions {
+  /** The app's `i18n` config, usually `vitNodeConfig.i18n`. */
   i18n: Pick<
     VitNodeI18nConfig,
     "defaultLocale" | "domains" | "localePrefix" | "routePaths"
   > & { locales: LocaleConfig[] };
+  /** Canonical, unlocalized paths to prerender, e.g. `/` and `/docs`. */
   paths: readonly string[];
 }
 
+/** Thrown by {@link prerenderRoutes} when the app serves locales by domain. */
 export class PrerenderDomainsError extends Error {
   constructor() {
     super(
@@ -19,6 +22,22 @@ export class PrerenderDomainsError extends Error {
   }
 }
 
+/**
+ * Expands canonical paths into the public URL of each enabled locale -
+ * prefixes and translated `routePaths` included - for Nitro's
+ * `prerender.routes`. Duplicates are removed.
+ *
+ * @throws {@link PrerenderDomainsError} when `i18n.domains` is set.
+ *
+ * @example
+ * ```ts
+ * nitro({
+ *   prerender: {
+ *     routes: prerenderRoutes({ i18n: vitNodeConfig.i18n, paths: ["/", "/about"] }),
+ *   },
+ * });
+ * ```
+ */
 export const prerenderRoutes = ({
   i18n,
   paths,
diff --git a/packages/vitnode/src/framework/vite/ssr-externals.ts b/packages/vitnode/src/framework/vite/ssr-externals.ts
index c18aa76d1a..0a9f5f7940 100644
--- a/packages/vitnode/src/framework/vite/ssr-externals.ts
+++ b/packages/vitnode/src/framework/vite/ssr-externals.ts
@@ -9,10 +9,16 @@ const ALWAYS_EXTERNAL = ["tslib"] as const;
 export const NITRO_TRACED_DEPENDENCIES = ["@simplewebauthn/server"] as const;
 
 export interface VitNodeSsrExternalsOptions {
+  /** The app's root directory, where `src/vitnode.config.ts` lives. */
   appRoot: string;
+  /** Reads the configured plugin ids. Defaults to reading the app's config; replaceable in tests. */
   readPluginIds?: (appRoot: string) => Promise<string[]>;
 }
 
+/**
+ * In a production build, keeps `@vitnode/core` and every configured plugin out
+ * of the server bundle, loaded from `node_modules` at runtime instead.
+ */
 export const vitNodeSsrExternals = ({
   appRoot,
   readPluginIds = configuredPluginIds,
diff --git a/packages/vitnode/src/framework/vite/tailwind-sources.ts b/packages/vitnode/src/framework/vite/tailwind-sources.ts
index 22fcbe86b0..9d6309fb8f 100644
--- a/packages/vitnode/src/framework/vite/tailwind-sources.ts
+++ b/packages/vitnode/src/framework/vite/tailwind-sources.ts
@@ -15,7 +15,9 @@ const TAILWIND_IMPORT = /@import\s+["']tailwindcss["']/;
 
 const RELATIVE_IMPORT = /@import\s+(?:url\()?["'](\.[^"']*)["']/g;
 
+/** Options of {@link vitNodeTailwindSources}. Everything but `appRoot` is a test seam. */
 export interface VitNodeTailwindSourcesOptions {
+  /** The app's root directory, where `src/vitnode.config.ts` lives. */
   appRoot: string;
 
   readBuildOutput?: (appRoot: string, packageName: string) => null | string;
@@ -76,6 +78,11 @@ const buildsTailwind = (
 const sourceDirective = (directory: string): string =>
   `@source "${directory.replaceAll("\\", "/")}/${SCANNED_FILES}";`;
 
+/**
+ * Adds an `@source` for the built output of `@vitnode/core` and every
+ * configured plugin to each stylesheet that imports Tailwind, so the classes
+ * those packages use are generated without listing them by hand.
+ */
 export const vitNodeTailwindSources = ({
   appRoot,
   readBuildOutput = buildOutputOf,
diff --git a/packages/vitnode/src/framework/vite/vitnode.ts b/packages/vitnode/src/framework/vite/vitnode.ts
index 995311e19e..8b3f616266 100644
--- a/packages/vitnode/src/framework/vite/vitnode.ts
+++ b/packages/vitnode/src/framework/vite/vitnode.ts
@@ -10,9 +10,29 @@ import { vitNodePluginRoutes } from "./plugin-routes";
 import { vitNodeSsrExternals } from "./ssr-externals";
 import { vitNodeTailwindSources } from "./tailwind-sources";
 
+/** Options of the {@link vitnode} Vite plugin. */
 export interface VitNodeViteOptions
   extends VitNodeEnvOptions, VitNodePluginRoutesOptions {}
 
+/**
+ * VitNode's Vite plugins for a TanStack Start app, in one call: environment
+ * variables, dependency pre-bundling, SSR externals, Tailwind sources for the
+ * installed packages, the generated plugin registries, and the development
+ * error page.
+ *
+ * Add it before `tanstackStart()` in `vite.config.ts`.
+ *
+ * @example
+ * ```ts
+ * import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+ * import { vitnode } from "@vitnode/core/framework/vite";
+ * import { defineConfig } from "vite";
+ *
+ * export default defineConfig({
+ *   plugins: [vitnode({ appRoot: import.meta.dirname }), tanstackStart()],
+ * });
+ * ```
+ */
 export const vitnode = ({
   appRoot,
   clientEnv,
diff --git a/packages/vitnode/src/hooks/use-before-unload.ts b/packages/vitnode/src/hooks/use-before-unload.ts
index ecc9629b63..218db9769d 100644
--- a/packages/vitnode/src/hooks/use-before-unload.ts
+++ b/packages/vitnode/src/hooks/use-before-unload.ts
@@ -1,5 +1,12 @@
 import React from "react";
 
+/**
+ * Asks the browser to confirm leaving the page, e.g. with unsaved changes.
+ *
+ * @param enabled `false` removes the listener; a function is called on every
+ * unload attempt to decide. Defaults to `true`.
+ * @param message Legacy custom text; most browsers show their own.
+ */
 export const useBeforeUnload = (
   enabled: (() => boolean) | boolean = true,
   message?: string,
diff --git a/packages/vitnode/src/hooks/use-captcha.ts b/packages/vitnode/src/hooks/use-captcha.ts
index 1f7626b75d..5053109aca 100644
--- a/packages/vitnode/src/hooks/use-captcha.ts
+++ b/packages/vitnode/src/hooks/use-captcha.ts
@@ -36,6 +36,18 @@ declare global {
   }
 }
 
+/**
+ * Captcha for a form that is not an `AutoForm` (which handles it already).
+ * Loads the configured provider's script and, for Turnstile, renders the
+ * widget into an element with `id="vitnode_captcha"` that the form must
+ * contain. Browser-only.
+ *
+ * @param captcha The `captcha` from `GET /api/@vitnode/core/middleware`;
+ * `undefined` when none is configured, which makes the hook a no-op.
+ * @returns `isReady` (enable submit), `getToken()` (send it as
+ * `captchaToken`; `""` without a captcha or on a reCAPTCHA error) and
+ * `onReset()` (call after each submit - a token is single-use).
+ */
 export const useCaptcha = (
   captcha: z.infer<typeof routeMiddlewareSchema>["captcha"],
 ) => {
diff --git a/packages/vitnode/src/hooks/use-intersection-observer.ts b/packages/vitnode/src/hooks/use-intersection-observer.ts
index 93776e67ac..1a83f50927 100644
--- a/packages/vitnode/src/hooks/use-intersection-observer.ts
+++ b/packages/vitnode/src/hooks/use-intersection-observer.ts
@@ -7,6 +7,12 @@ interface UseIntersectionObserverOptions {
   threshold?: number | number[];
 }
 
+/**
+ * The latest `IntersectionObserverEntry` for `target`, e.g. to load more items
+ * when a sentinel scrolls into view. `undefined` until the first observation.
+ *
+ * @param options.freezeOnceVisible Stop observing after the first intersection.
+ */
 export function useIntersectionObserver(
   target: Element | null,
   {
diff --git a/packages/vitnode/src/hooks/use-local-storage.ts b/packages/vitnode/src/hooks/use-local-storage.ts
index 144f07ddb0..16e2b159de 100644
--- a/packages/vitnode/src/hooks/use-local-storage.ts
+++ b/packages/vitnode/src/hooks/use-local-storage.ts
@@ -54,6 +54,13 @@ const subscribe = (onChange: () => void) => {
 
 const getServerSnapshot = () => null;
 
+/**
+ * State persisted as JSON in `localStorage` and kept in sync across hooks and
+ * tabs. Falls back to in-memory storage when `localStorage` is unavailable,
+ * and renders `defaultValue` on the server.
+ *
+ * @returns `[value, setValue, removeValue]`.
+ */
 export function useLocalStorage<T>(
   key: string,
   defaultValue: T,
diff --git a/packages/vitnode/src/hooks/use-mobile.ts b/packages/vitnode/src/hooks/use-mobile.ts
index 00adc729ed..d31b681911 100644
--- a/packages/vitnode/src/hooks/use-mobile.ts
+++ b/packages/vitnode/src/hooks/use-mobile.ts
@@ -16,6 +16,7 @@ const getSnapshot = () => window.matchMedia(MOBILE_QUERY).matches;
 
 const getServerSnapshot = () => false;
 
+/** Whether the viewport is narrower than 768px. Always `false` during SSR. */
 export function useIsMobile() {
   return React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
diff --git a/packages/vitnode/src/hooks/use-sliding-indicator.ts b/packages/vitnode/src/hooks/use-sliding-indicator.ts
index a451ec65df..9fb7c03b22 100644
--- a/packages/vitnode/src/hooks/use-sliding-indicator.ts
+++ b/packages/vitnode/src/hooks/use-sliding-indicator.ts
@@ -1,10 +1,23 @@
 import React from "react";
 
+/** The attribute that marks each item the indicator can slide to, in order. */
 export const SLIDING_INDICATOR_ITEM = "data-sliding-indicator-item";
 
+/** Tailwind classes that animate the indicator's move; none under reduced motion. */
 export const slidingIndicatorTransitionClassName =
   "transition-[transform,width,height] duration-300 ease-fluid motion-reduce:transition-none";
 
+/**
+ * Moves a highlight element under the active item of a tab-like row. Put
+ * `containerRef` on the row, mark each item with the
+ * {@link SLIDING_INDICATOR_ITEM} attribute, and put `indicatorRef` on the
+ * indicator element. It is sized and positioned under the `activeIndex`-th
+ * marked item, follows container resizes, and is hidden (`opacity: 0`) when
+ * that item does not exist. `isReady` turns `true` after the first frame -
+ * add the transition classes only then, so the first placement doesn't
+ * animate. Browser-only work runs in effects, so it is safe to render on the
+ * server.
+ */
 export const useSlidingIndicator = <Container extends HTMLElement>(
   activeIndex: number,
 ) => {
diff --git a/packages/vitnode/src/lib/ai/assist-client.ts b/packages/vitnode/src/lib/ai/assist-client.ts
index 3b85bb3891..cbc65137b6 100644
--- a/packages/vitnode/src/lib/ai/assist-client.ts
+++ b/packages/vitnode/src/lib/ai/assist-client.ts
@@ -38,6 +38,11 @@ export class AiRequestError extends Error {
   readonly status: number;
 }
 
+/**
+ * The AI error code of a thrown value: the `code` of an `AiRequestError`
+ * (what the AI client helpers throw), `"unknown"` for anything else. Use it in
+ * a `catch` to pick the message to show.
+ */
 export const aiErrorCodeOf = (error: unknown): AiClientErrorCode =>
   error instanceof AiRequestError ? error.code : "unknown";
 
@@ -59,15 +64,28 @@ export const readAiErrorCode = async (
   }
 };
 
+/**
+ * Runs an AI action once from the AdminCP and resolves with its whole output.
+ * Browser-only: it calls the `admin/ai` `/assist` route with the browser's
+ * session, so the signed-in admin's AI permissions apply. Each call sends a
+ * fresh idempotency key.
+ *
+ * @throws `AiRequestError` with the server's error code (`"unknown"` when the
+ * body has none) and the HTTP status, for any non-2xx response.
+ */
 export const requestAiAssist = async ({
   action,
   input,
   signal,
   sourceFingerprint,
 }: {
+  /** The qualified action key, e.g. `"@vitnode/blog:excerpt.generate"`. */
   action: string;
+  /** The action's input; validated on the server against the action's schema. */
   input: unknown;
+  /** Aborts the request. */
   signal?: AbortSignal;
+  /** Recorded with the run, e.g. a fingerprint of the source the output was made from. */
   sourceFingerprint?: string;
 }): Promise<{ output: unknown; runId: number }> => {
   const response = await fetcherClient({
diff --git a/packages/vitnode/src/lib/ai/stream-client.ts b/packages/vitnode/src/lib/ai/stream-client.ts
index 104c16c53f..a535fd492f 100644
--- a/packages/vitnode/src/lib/ai/stream-client.ts
+++ b/packages/vitnode/src/lib/ai/stream-client.ts
@@ -7,8 +7,10 @@ import {
   toAiClientErrorCode,
 } from "./assist-client";
 
+/** Which AI routes a browser call uses: the AdminCP's (`admin`) or the public ones (`user`). */
 export type AiAssistScope = "admin" | "user";
 
+/** `admin` on a page under `/admin`, `user` elsewhere and on the server. */
 export const aiAssistScope = (): AiAssistScope =>
   typeof window !== "undefined" &&
   /^\/admin(\/|$)/.test(window.location.pathname)
@@ -21,6 +23,15 @@ export interface AiStreamSummary {
   runId: number;
 }
 
+/**
+ * Runs an AI action and streams its text output, calling `onDelta` with each
+ * chunk as it arrives. Resolves with the run's summary when the stream ends.
+ * Browser-only; text actions only. Each call sends a fresh idempotency key.
+ *
+ * @throws `AiRequestError` for a non-2xx response or missing body, for an
+ * error event inside the stream (with status `200`), and with
+ * `AI_PROVIDER_FAILED` when the stream ends without a summary.
+ */
 export const streamAiAction = async ({
   action,
   input,
@@ -28,10 +39,15 @@ export const streamAiAction = async ({
   scope,
   signal,
 }: {
+  /** The qualified action key, e.g. `"@vitnode/blog:excerpt.generate"`. */
   action: string;
+  /** The action's input; validated on the server. */
   input: unknown;
+  /** Called with each new chunk of text, in order. */
   onDelta: (delta: string) => void;
+  /** Which routes to call; {@link aiAssistScope} picks it from the current page. */
   scope: AiAssistScope;
+  /** Aborts the request and the stream. */
   signal?: AbortSignal;
 }): Promise<AiStreamSummary> => {
   const body = { action, idempotencyKey: crypto.randomUUID(), input };
diff --git a/packages/vitnode/src/lib/config.ts b/packages/vitnode/src/lib/config.ts
index 3ec341d9d8..402d784559 100644
--- a/packages/vitnode/src/lib/config.ts
+++ b/packages/vitnode/src/lib/config.ts
@@ -1,6 +1,8 @@
+/** The `CRON_SECRET` used when none is set. Refused outside development. */
 export const INSECURE_DEFAULT_CRON_SECRET =
   "default-cron-secret-change-in-production";
 
+/** Placeholder values `CRON_SECRET` must not keep in production. */
 export const INSECURE_CRON_SECRETS: readonly string[] = [
   INSECURE_DEFAULT_CRON_SECRET,
   "your-secure-cron-secret-key",
@@ -16,7 +18,21 @@ const browserOrigin = (): string | undefined => {
   return location.origin.startsWith("http") ? location.origin : undefined;
 };
 
+/**
+ * Deployment settings read from environment variables. Each getter reads
+ * `process.env` on every access, so values set after import still apply.
+ * Universal: in the browser only `VITNODE_API_URL`, `VITNODE_WEB_URL` and any
+ * `clientEnv` keys (defined by the VitNode Vite plugin), plus `NODE_ENV`
+ * (replaced by Vite), are defined.
+ */
 export const CONFIG = {
+  /**
+   * The API's origin: `VITNODE_API_URL`, else the page's own origin in the
+   * browser, else `http://localhost:3000`.
+   *
+   * @throws When `VITNODE_API_URL` is set but not a valid URL - an empty value
+   * included.
+   */
   get api(): URL {
     // `??` rather than `||`, deliberately: an empty `VITNODE_API_URL` is a
     // deployment that got it wrong, and `contentPreviewConfigProblems` reads the
@@ -25,22 +41,35 @@ export const CONFIG = {
       process.env.VITNODE_API_URL ?? browserOrigin() ?? "http://localhost:3000",
     );
   },
+  /** `CRON_SECRET`, authenticating cron and revalidation calls. Falls back to an insecure default. */
   get cronJobSecret(): string {
     return process.env.CRON_SECRET ?? INSECURE_DEFAULT_CRON_SECRET;
   },
+  /** Whether `NODE_ENV` is `development`. */
   get node_development(): boolean {
     return process.env.NODE_ENV === "development";
   },
+  /**
+   * `VITNODE_TRUSTED_PROXY_HOPS`: how many reverse proxies in front of the app
+   * may be trusted in `x-forwarded-for`. Defaults to `0` (trust none); an
+   * invalid value also counts as `0`.
+   */
   get trustedProxyHops(): number {
     const hops = Number(process.env.VITNODE_TRUSTED_PROXY_HOPS ?? 0);
 
     return Number.isSafeInteger(hops) && hops > 0 ? hops : 0;
   },
+  /**
+   * The web app's origin, `VITNODE_WEB_URL`, defaulting to
+   * `http://localhost:3000`. The API's default CORS and CSRF origin, and the
+   * default passkey origin.
+   */
   get web(): URL {
     return new URL(process.env.VITNODE_WEB_URL ?? "http://localhost:3000");
   },
 };
 
+/** Whether a cron secret must be refused: empty, or a placeholder outside development. */
 export const isCronSecretRejected = (secret: string | undefined): boolean =>
   !secret ||
   (INSECURE_CRON_SECRETS.includes(secret) && !CONFIG.node_development);
diff --git a/packages/vitnode/src/lib/emoji-icon.ts b/packages/vitnode/src/lib/emoji-icon.ts
index a5ef746733..946de5e0d9 100644
--- a/packages/vitnode/src/lib/emoji-icon.ts
+++ b/packages/vitnode/src/lib/emoji-icon.ts
@@ -1,7 +1,9 @@
+/** A parsed emoji-or-icon value: one emoji, or a Lucide icon name in kebab case. */
 export type EmojiIconValue =
   | { type: "emoji"; value: string }
   | { type: "icon"; value: string };
 
+/** The longest stored value (`emoji:…` / `icon:…`) {@link parseEmojiIcon} accepts. */
 export const EMOJI_ICON_MAX_LENGTH = 64;
 
 const LUCIDE_ICON_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
@@ -17,6 +19,11 @@ export const isSingleEmoji = (value: string): boolean => {
   return singleEmoji.test(value);
 };
 
+/**
+ * Reads a stored `emoji:🚀` or `icon:newspaper` string. Returns `undefined`
+ * for anything else: empty, longer than {@link EMOJI_ICON_MAX_LENGTH}, an
+ * unknown scheme, more than one emoji, or an icon name that is not kebab case.
+ */
 export const parseEmojiIcon = (
   raw: null | string | undefined,
 ): EmojiIconValue | undefined => {
@@ -42,6 +49,7 @@ export const parseEmojiIcon = (
   return undefined;
 };
 
+/** The stored string for a value - `emoji:…` or `icon:…` - or `""` for none. */
 export const serializeEmojiIcon = (
   value: EmojiIconValue | null | undefined,
 ): string => (value ? `${value.type}:${value.value}` : "");
diff --git a/packages/vitnode/src/lib/fetcher-client.ts b/packages/vitnode/src/lib/fetcher-client.ts
index 3b4a5b34ac..262b72f75a 100644
--- a/packages/vitnode/src/lib/fetcher-client.ts
+++ b/packages/vitnode/src/lib/fetcher-client.ts
@@ -24,13 +24,28 @@ export type {
   ResponseFor,
 } from "./fetcher/types";
 
+/** What a browser call accepts besides the route and `args`. */
 export type FetcherClientOptions = Omit<
   FetcherRequestOptions,
   "additionalHeaders" | "origin"
 > & {
+  /** Sent as `x-vitnode-captcha-token`, for routes built with `withCaptcha`. */
   captchaToken?: string;
 };
 
+/**
+ * The browser primitive the universal `fetcher` is built on, framework-neutral.
+ * Use it only in code that never renders on a server; anything rendered by
+ * TanStack Start uses `fetcher` from `@vitnode/core/tanstack/fetcher`.
+ *
+ * Sends `credentials: "include"` (the API may live on another origin) and
+ * dispatches a `vitnode:rate-limit` window event on a `429`.
+ *
+ * Resolves with the `Response` for every status except `500` - check `res.ok`
+ * or `res.status` before reading the body; any other `4xx` or `5xx` is also
+ * logged to the console. Rejects on a `500` (with the response body in the
+ * message) and on network failure.
+ */
 export async function fetcherClient<
   P extends RegisteredPluginId,
   M extends string,
diff --git a/packages/vitnode/src/lib/fetcher/raw.ts b/packages/vitnode/src/lib/fetcher/raw.ts
index 9e80529d5a..ef5eda30c3 100644
--- a/packages/vitnode/src/lib/fetcher/raw.ts
+++ b/packages/vitnode/src/lib/fetcher/raw.ts
@@ -1,8 +1,10 @@
 import { CONFIG } from "../config";
 import { buildSearchParams } from "./helpers";
 
+/** An untyped API call: the URL parts and the request, with nothing inferred. */
 export interface RawApiFetchArgs {
   additionalHeaders?: HeadersInit;
+  /** Sent as JSON, with a JSON `Content-Type`. Ignored when `formData` is set. */
   body?: unknown;
   /**
    * Raw `multipart/form-data` body. When set the JSON `Content-Type` is
@@ -15,13 +17,21 @@ export interface RawApiFetchArgs {
 
   options?: Omit<RequestInit, "body" | "headers" | "method">;
 
+  /**
+   * The API's origin. Defaults to `VITNODE_API_URL`, else the page's origin in
+   * a browser, else `http://localhost:3000`.
+   */
   origin?: string;
+  /** Substituted into `{name}` placeholders in `path`. */
   params?: Record<string, unknown>;
   /** Route path within the module, e.g. `/` or `/{id}`. */
   path: string;
   pluginId: string;
+  /** Inserted between the plugin id and the module in the URL. */
   prefixPath?: string;
+  /** The search params; `undefined` values are left out. */
   query?: Record<string, string | string[] | undefined>;
+  /** Adds cursor-pagination defaults to `query`: see `FetcherRequestOptions`. */
   withPagination?: boolean;
 }
 
@@ -31,6 +41,7 @@ export interface RawApiFetchArgs {
  */
 export type ApiTransport = (request: Request) => Promise<Response>;
 
+/** The URL of an API call: `{origin}/api/{pluginId}{prefixPath}/{module}{path}?{query}`. */
 export const buildApiUrl = ({
   module,
   origin,
@@ -88,6 +99,11 @@ export const buildApiUrl = ({
  * `coreFetcher` wraps this with the route-literal type inference, and the
  * Content Engine wraps it with content-type schemas - both get the same
  * request behaviour without a second implementation.
+ *
+ * Resolves with the `Response` for every status except `500` - check `res.ok`
+ * or `res.status` before reading the body; any other `4xx` or `5xx` is also
+ * logged to the console. Rejects on a `500` (with the response body in the
+ * message) and on network failure.
  */
 export const rawApiFetch = async (
   {
diff --git a/packages/vitnode/src/lib/fetcher/registry.ts b/packages/vitnode/src/lib/fetcher/registry.ts
index ee6cbd3978..b281514397 100644
--- a/packages/vitnode/src/lib/fetcher/registry.ts
+++ b/packages/vitnode/src/lib/fetcher/registry.ts
@@ -14,6 +14,10 @@ import type { VitNodeApiPlugin } from "@/api/plugin";
  * models, the listeners, the queues and the search indexers a plugin also
  * carries are runtime concerns, and resolving them here would make every
  * keystroke in a `fetcher` call pay for them.
+ *
+ * A plugin's own pages can call its API before any app configures it:
+ * `vitnode build` and `vitnode dev` write the plugin's entry into its
+ * `types/api-registry.gen.d.ts`, which stays out of the published package.
  */
 export interface ApiPluginRegistry {
   "@vitnode/core": VitNodeApiPlugin;
diff --git a/packages/vitnode/src/lib/fetcher/types.ts b/packages/vitnode/src/lib/fetcher/types.ts
index 812b3c2180..e6b48ac9b7 100644
--- a/packages/vitnode/src/lib/fetcher/types.ts
+++ b/packages/vitnode/src/lib/fetcher/types.ts
@@ -39,14 +39,9 @@ interface ClientResponse<
   url: string;
 }
 
+/** Every plugin id in the API registry: core plus the app's configured plugins. */
 export type RegisteredPluginId = Extract<keyof ApiPluginRegistry, string>;
 
-/**
- * Every endpoint one plugin serves, as one flat union.
- *
- * A plain lookup: the flattening happened once, in the plugin's own
- * `ApiPluginContract`, and the registry stores the result.
- */
 /**
  * The three things a call reads off a registry entry, each behind its own
  * inference so that reading one never resolves the others.
@@ -68,11 +63,18 @@ type ModulesOf<P extends RegisteredPluginId> = ApiPluginRegistry[P] extends {
   ? Modules
   : never;
 
+/**
+ * Every endpoint one plugin serves, as one flat union.
+ *
+ * A plain lookup: the flattening happened once, in the plugin's own
+ * `ApiPluginContract`, and the registry stores the result.
+ */
 export type PluginEndpoints<P extends RegisteredPluginId> =
   ApiPluginRegistry[P] extends { endpoints: infer E extends ApiEndpoint }
     ? E
     : never;
 
+/** Every endpoint of every registered plugin. */
 export type AllEndpoints = PluginEndpoints<RegisteredPluginId>;
 
 type ValidModule<P extends RegisteredPluginId, M extends string> =
@@ -219,6 +221,11 @@ export type BuildArgsType<RouteCfg> = OptionalQueryArgs<RouteCfg> & {
   ]: InferInputType<RouteCfg, K>;
 };
 
+/**
+ * The `args` of a call: required when the route declares a body, params or a
+ * query - with only an optional query, `args` is still required but its
+ * `query` may be left out - and absent otherwise.
+ */
 export type FetcherArgs<RouteCfg> = keyof BuildArgsType<RouteCfg> extends never
   ? { args?: undefined }
   : { args: BuildArgsType<RouteCfg> };
@@ -290,6 +297,10 @@ export type RouteOf<
   { route: { method: Method; path: Path } }
 >["route"];
 
+/**
+ * The typed `Response` of one call: a union with one member per status the
+ * route declares, so narrowing on `status` or `ok` narrows `json()`.
+ */
 export type ResponseFor<
   P extends RegisteredPluginId,
   M extends string,
@@ -324,6 +335,11 @@ export interface FetcherRequestOptions {
    * `RawApiFetchArgs["origin"]`.
    */
   origin?: string;
+  /**
+   * For cursor-paginated routes: fills `query.first` with `10` unless
+   * `first` or `last` is set, and `query.search` with `""` unless set. Only
+   * applies when the call passes a `query`. Defaults to `false`.
+   */
   withPagination?: boolean;
 }
 
@@ -344,7 +360,6 @@ export type FetcherCall<
   FetcherRoute<P, M, Path, Method> &
   Options;
 
-/** Every module path one plugin serves. */
 /**
  * Every module path one plugin serves.
  *
diff --git a/packages/vitnode/src/lib/files/resolve-alt.ts b/packages/vitnode/src/lib/files/resolve-alt.ts
index cdbded38bc..009fe5ebb6 100644
--- a/packages/vitnode/src/lib/files/resolve-alt.ts
+++ b/packages/vitnode/src/lib/files/resolve-alt.ts
@@ -1,5 +1,8 @@
+/** What one placement of an image says about its alt text. */
 export interface ImageAltOccurrence {
+  /** Alt text written for this placement; wins over the file's own. */
   alt?: null | string;
+  /** Marks the image decorative: the alt is `""` whatever else is set. */
   decorative?: boolean;
 }
 
@@ -10,19 +13,31 @@ export type ImageAltSource =
   | "missing"
   | "occurrence";
 
+/** The alt text to render and where it came from. */
 export interface ResolvedImageAlt {
+  /** `""` when decorative or missing. */
   alt: string;
   source: ImageAltSource;
 }
 
+/**
+ * Picks an image's alt text, in this order: decorative (empty) → the
+ * placement's own trimmed `alt` → the file's alt in `locale` → the file's alt
+ * in the first of `fallbackLocales` that has one → empty with source
+ * `missing`. A locale counts when the file has an entry for it, even an empty
+ * one. Pure; runs anywhere.
+ */
 export const resolveImageAlt = ({
   alts,
   fallbackLocales = [],
   locale,
   occurrence = {},
 }: {
+  /** The file's alt texts keyed by locale code. */
   alts?: null | Record<string, string>;
+  /** Locales to try, in order, when `locale` has no entry. Defaults to none. */
   fallbackLocales?: readonly string[];
+  /** The locale being rendered. */
   locale: string;
   occurrence?: ImageAltOccurrence;
 }): ResolvedImageAlt => {
diff --git a/packages/vitnode/src/lib/helpers/multi-lang.ts b/packages/vitnode/src/lib/helpers/multi-lang.ts
index 078f09ee7b..6155eae024 100644
--- a/packages/vitnode/src/lib/helpers/multi-lang.ts
+++ b/packages/vitnode/src/lib/helpers/multi-lang.ts
@@ -11,6 +11,11 @@ export interface MultiLangValueItem<TValue = string> {
 
 export type MultiLangValue<TValue = string> = MultiLangValueItem<TValue>[];
 
+/**
+ * The Zod schema of a multi-language string: an array of
+ * `{ languageCode, value }`. Pair it with `multiLang` on `AutoFormInput`,
+ * `AutoFormTextarea` or `AutoFormEditor` to edit one value per language. `minLength` and `maxLength` apply to each value.
+ */
 export const multiLangValueSchema = ({
   maxLength,
   minLength,
diff --git a/packages/vitnode/src/lib/i18n/types.ts b/packages/vitnode/src/lib/i18n/types.ts
index d8d928bff0..ae8db231a5 100644
--- a/packages/vitnode/src/lib/i18n/types.ts
+++ b/packages/vitnode/src/lib/i18n/types.ts
@@ -18,6 +18,12 @@ export type LocaleMessagesMap = Record<string, MessagesLoader>;
  */
 export type LocaleFilesMap = Record<string, string>;
 
+/**
+ * An app's own translations: keyed by locale, then by namespace - a package id
+ * such as `@vitnode/core` to override that package's strings, or a namespace
+ * of the app's own. Merged over the packages' messages, so a key the app sets
+ * wins.
+ */
 export type AppMessagesMap = Record<string, Record<string, MessagesLoader>>;
 
 /** A package - core or a plugin - contributing messages to the merged tree. */
@@ -33,33 +39,62 @@ export interface MessagesSource {
   scope?: string;
 }
 
+/** One language the app offers. */
 export interface LocaleConfig {
+  /** The locale code used in URLs and message lookups, e.g. `en` or `pl`. */
   code: string;
+  /** `false` switches the locale off: its URLs stop routing. Defaults to `true`. */
   enabled?: boolean;
+  /** The language's own name, shown in the language switcher. */
   name: string;
 }
 
+/** A host that serves its own locales, e.g. `https://vitnode.pl` for Polish. */
 export interface LocaleDomainConfig<TLocale extends string = string> {
+  /** The host's default locale, unprefixed under `localePrefix: "as-needed"`. */
   defaultLocale: TLocale;
+  /** Every locale the host serves. Defaults to `[defaultLocale]`. */
   locales?: TLocale[];
+  /** Scheme and host only, e.g. `https://vitnode.pl` - no path, query or credentials. */
   origin: string;
 }
 
+/**
+ * Translated URL paths, per locale: canonical route path to localized path,
+ * with the same parameters - `{ pl: { "/blog/:slug": "/wpisy/:slug" } }`.
+ */
 export type LocaleRoutePaths<TLocale extends string = string> = Partial<
   Record<TLocale, Record<string, string>>
 >;
 
+/** An app's languages and how locales appear in URLs. */
 export interface VitNodeI18nConfig<
   AppLocales extends LocaleConfig[] = LocaleConfig[],
 > {
+  /** The fallback locale, and the one served without a prefix under `"as-needed"`. */
   defaultLocale: AppLocales[number]["code"];
+  /**
+   * Serves locales from separate hosts. An invalid origin, or a locale claimed
+   * twice, throws when locale routing is built.
+   */
   domains?: LocaleDomainConfig<AppLocales[number]["code"]>[];
+  /**
+   * How the locale appears in public URLs. `"as-needed"` (the default) leaves
+   * the default locale unprefixed; `"always"` prefixes every locale; `"never"`
+   * prefixes none, which needs `domains` when more than one locale is enabled.
+   * `/admin` and `/api` are never prefixed.
+   */
   localePrefix?: "always" | "as-needed" | "never";
+  /** Every language the app offers. */
   locales: AppLocales;
 
+  /** The API's message overrides; a web app passes its own to `buildServerConfig`. */
   messages?: AppMessagesMap;
+  /** Translated URL paths per locale. */
   routePaths?: LocaleRoutePaths<AppLocales[number]["code"]>;
+  /** IANA time zone for formatting dates, e.g. `Europe/Warsaw`. Defaults to `UTC`. */
   timeZone?: string;
 }
 
+/** The API's `i18n` block: the same shape, every field optional. */
 export type VitNodeApiI18nConfig = Partial<VitNodeI18nConfig>;
diff --git a/packages/vitnode/src/lib/metadata.ts b/packages/vitnode/src/lib/metadata.ts
index 53af1fb9eb..d1436b1235 100644
--- a/packages/vitnode/src/lib/metadata.ts
+++ b/packages/vitnode/src/lib/metadata.ts
@@ -1,9 +1,21 @@
-/** The app's name, as it appears in a browser tab and in an email's subject. */
+/**
+ * The app's name, used in page titles, the default email template and, on the
+ * API, as the passkey RP name fallback.
+ */
 export interface VitNodeMetadata {
+  /**
+   * A shorter name for page titles (`{page} - {shortTitle}`), the email
+   * footer and the passkey RP name. Defaults to `title`.
+   */
   shortTitle?: string;
+  /**
+   * The full name. The default email header shows it (or uses it as the logo
+   * image's alt text) when the email logo sets no `text`.
+   */
   title: string;
 }
 
+/** The page title template, `%s - {shortTitle ?? title}`. */
 export const titleTemplate = ({ shortTitle, title }: VitNodeMetadata): string =>
   `%s - ${shortTitle ?? title}`;
 
diff --git a/packages/vitnode/src/lib/navigation.ts b/packages/vitnode/src/lib/navigation.ts
index 4309090e75..b9f499ac1b 100644
--- a/packages/vitnode/src/lib/navigation.ts
+++ b/packages/vitnode/src/lib/navigation.ts
@@ -17,23 +17,45 @@ export const NAVIGATION_HREF_MAX_LENGTH = 2048;
 
 export type NavigationIcon = React.ComponentType<{ className?: string }>;
 
+/** One link in the site's header or mobile bottom bar. */
 export interface NavigationLinkConfig {
+  /**
+   * A message key (`site.menu.discover_description`) shown under the title in
+   * a header dropdown. Must be `namespace.name`.
+   */
   description?: string;
+  /** A path on this site (`/docs`) or an `https://` URL, at most 2048 characters. */
   href: string;
   icon?: NavigationIcon;
+  /** Opens the link in a new tab, with `rel="noopener noreferrer"`. */
   isOpenInNewTab?: boolean;
+  /** A message key (`site.menu.docs`), never text. Must be `namespace.name`. */
   title: string;
 }
 
+/** A header link, optionally with a dropdown. */
 export interface NavigationHeaderItemConfig extends NavigationLinkConfig {
+  /** Dropdown links. The parent opens the dropdown on hover and follows its own `href` on click, except a click on its chevron. */
   items?: NavigationLinkConfig[];
 }
 
+/**
+ * The site's own menus, the frontend config's `navigation`. Checked by
+ * `buildConfig`, which throws a {@link NavigationConfigError} on an invalid
+ * href or message key, more than 3 bottom-bar links, or keys spread over more
+ * namespaces than one request can load.
+ */
 export interface NavigationConfig {
+  /** Links in the site header, in order. */
   header?: NavigationHeaderItemConfig[];
+  /** Up to 3 links in the bottom bar on small screens. */
   mobileBottomBar?: NavigationLinkConfig[];
 }
 
+/**
+ * Thrown by `buildConfig` for an invalid `navigation`. Carries `hints` that
+ * the development error overlay shows next to the message.
+ */
 export class NavigationConfigError extends Error implements DevErrorWithHints {
   constructor(message: string, hints: readonly DevErrorHint[]) {
     super(`[VitNode navigation] ${message}`);
diff --git a/packages/vitnode/src/lib/plugin-manifest.ts b/packages/vitnode/src/lib/plugin-manifest.ts
index eb4f30e2a9..988aa6db37 100644
--- a/packages/vitnode/src/lib/plugin-manifest.ts
+++ b/packages/vitnode/src/lib/plugin-manifest.ts
@@ -1,9 +1,24 @@
 import { isLucideIconName } from "./emoji-icon";
 import { updateSourceUrlProblem } from "./updates/source-url";
 
+/**
+ * The parts of a plugin's manifest its package.json cannot express. A plugin
+ * exports it as `pluginInfo` from `src/plugin-info.ts`; `vitnode build` and
+ * `vitnode dev` merge it into the generated `src/manifest.gen.ts`.
+ *
+ * @example
+ * ```ts
+ * import type { PluginInfo } from "@vitnode/core/lib/plugin-manifest";
+ *
+ * export const pluginInfo: PluginInfo = { title: "Blog", icon: "newspaper" };
+ * ```
+ */
 export interface PluginInfo {
+  /** A Lucide icon name in kebab case, e.g. `newspaper`, shown in the AdminCP. */
   icon?: string;
+  /** The plugin's display name. Defaults to the package name. */
   title?: string;
+  /** Where the AdminCP checks for newer versions of the plugin. */
   updates?: PluginUpdateSource;
 }
 
@@ -14,13 +29,24 @@ export interface PluginAuthor {
 }
 
 export interface PluginUpdateSource {
+  /** An absolute `https://` URL of a public update manifest, without credentials, query or fragment. */
   url: string;
 }
 
+/**
+ * A plugin's identity, generated into `src/manifest.gen.ts` from its
+ * package.json (`name`, `version`, `description`, `author`, `license`) and
+ * {@link PluginInfo}. Never written by hand.
+ *
+ * Pass the same object to `buildPlugin`, `buildApiPlugin` and `bindApiPlugin`:
+ * its `id` is the plugin id every frontend and API registration is keyed by.
+ */
 export interface PluginManifest<Id extends string = string> {
   author: null | PluginAuthor;
   description: null | string;
+  /** A Lucide icon name, or `null` for the default icon. */
   icon: null | string;
+  /** The package name, e.g. `@vitnode/blog`. */
   id: Id;
   license: null | string;
   title: string;
@@ -31,6 +57,13 @@ export interface PluginManifest<Id extends string = string> {
 
 export const PLUGIN_MANIFEST_ERROR_PREFIX = "[VitNode plugin manifest]";
 
+/**
+ * Checks a manifest passed to a plugin factory; `where` names the factory in
+ * the error. A missing manifest passes.
+ *
+ * @throws When the manifest's `id` is not `pluginId`, its icon is not a Lucide
+ * icon name, or its update source URL is not a valid public `https://` URL.
+ */
 export const assertPluginManifest = (
   pluginId: string,
   manifest: Pick<PluginManifest, "icon" | "id" | "updates"> | undefined,
diff --git a/packages/vitnode/src/lib/plugin.ts b/packages/vitnode/src/lib/plugin.ts
index 99f26d6a64..869189b54d 100644
--- a/packages/vitnode/src/lib/plugin.ts
+++ b/packages/vitnode/src/lib/plugin.ts
@@ -15,17 +15,49 @@ import type { PluginManifest } from "./plugin-manifest";
 
 import { assertPluginManifest } from "./plugin-manifest";
 
+/**
+ * An admin staff permission a plugin's navigation item or dashboard widget
+ * requires. The plugin is implied: it is always checked against the plugin that
+ * declared the item, so a permission granted under another plugin never
+ * reveals it.
+ */
 export type AdminNavPermission = Omit<PermissionsStaffArgs, "plugin">;
 
 interface AdminNavItem extends Pick<
   ResolvedAdminNavItem,
   "href" | "icon" | "isOpenInNewTab"
 > {
+  /**
+   * Builds the item's title key: `{pluginId}.admin.nav.{id}` in the plugin's
+   * frontend messages (`{pluginId}.admin.nav.{parentId}.{id}` for a sub-item).
+   */
   id: string;
+  /** Hides the item from admins without this permission. Omit to show it to every admin. */
   permission?: AdminNavPermission;
 }
 
+/**
+ * A link a plugin adds to its own AdminCP sidebar group, below the entries of
+ * its content types and containers.
+ *
+ * A parent with `items` is hidden when the admin may see none of them.
+ *
+ * @example
+ * ```ts
+ * admin: {
+ *   nav: [
+ *     {
+ *       id: "reports",
+ *       href: "/admin/blog/reports",
+ *       icon: <FlagIcon />,
+ *       permission: { module: "reports", permission: "can_view" },
+ *     },
+ *   ],
+ * },
+ * ```
+ */
 export type AdminNavDeclaration = AdminNavItem & {
+  /** Nested links. Sub-items have no icon. */
   items?: Omit<AdminNavItem, "icon">[];
 };
 
@@ -35,49 +67,112 @@ export type AdminNavContentType = Pick<
   "definition" | "icon"
 >;
 
+/** A content container the AdminCP lists in the plugin's sidebar group. */
 export interface ContentContainerFrontendRegistration {
+  /** The same definition the plugin registers on its API. */
   definition: AnyContentContainerDefinition;
+  /** Sidebar icon. */
   icon?: React.ReactNode;
 }
 
+/**
+ * A plugin's AdminCP sidebar group - its content types, containers and extra
+ * links - plus the widgets it offers on the AdminCP dashboard. A plugin exports
+ * it as `adminNav` from its `admin/nav` module; the VitNode Vite plugin
+ * discovers that export and lists it in the app's generated
+ * `src/admin-nav.gen.ts`, which the AdminCP shell loads. Browser-safe.
+ *
+ * @example
+ * ```tsx
+ * // src/admin/nav.tsx
+ * export const adminNav = {
+ *   pluginId: manifest.id,
+ *   contentTypes: [{ definition: blogPostContentType, icon: <NotebookPenIcon /> }],
+ * } satisfies AdminNavPluginSource;
+ * ```
+ */
 export interface AdminNavPluginSource {
-  admin?: { nav?: AdminNavDeclaration[] };
+  admin?: {
+    dashboard?: {
+      /**
+       * Widgets this plugin offers on the AdminCP dashboard. Their strings
+       * live under `{pluginId}.admin.dashboard.widgets` in the plugin's
+       * frontend messages.
+       */
+      widgets?: AdminDashboardWidget[];
+    };
+    /** Extra links in the plugin's sidebar group. */
+    nav?: AdminNavDeclaration[];
+  };
   containers?: ContentContainerFrontendRegistration[];
   contentTypes?: AdminNavContentType[];
   pluginId: string;
 }
 
+/** How many of the dashboard grid's three columns a widget covers. */
 export type AdminDashboardWidgetSpan = 1 | 2 | 3;
+/** How many grid rows a widget covers. */
 export type AdminDashboardWidgetRows = 1 | 2 | 3;
+/** A widget instance's own settings, saved with the admin's dashboard layout. */
 export type AdminDashboardWidgetSettings = Record<string, unknown>;
 
 export interface AdminDashboardWidgetProps {
+  /** This instance's saved settings; `{}` until the admin changes any. */
   settings: AdminDashboardWidgetSettings;
+  /** The instance id, unique on the board even when the widget allows several copies. */
   widgetId: string;
 }
 
+/**
+ * A widget a plugin offers on the AdminCP dashboard. Admins add, remove,
+ * resize and reorder widgets themselves; the layout is saved per admin.
+ *
+ * Its title comes from `{pluginId}.admin.dashboard.widgets.{id}.title` and its
+ * optional description from `...{id}.desc` in the plugin's frontend messages.
+ */
 export interface AdminDashboardWidget {
+  /** Lets an admin place more than one copy, each with its own settings. */
   allowMultiple?: boolean;
+  /**
+   * Groups the widget in the "add widget" panel, titled by
+   * `{pluginId}.admin.dashboard.widgets.categories.{category}` (the raw value
+   * when that key is missing). Defaults to a group named after the plugin.
+   */
   category?: string;
+  /** Renders the widget's body. */
   component: React.ComponentType<AdminDashboardWidgetProps>;
+  /**
+   * Placed automatically, at the end of the board, for admins who have never
+   * seen this widget. Admins who removed it keep it removed.
+   */
   defaultEnabled?: boolean;
+  /** Height when first placed. Defaults to `1`. */
   defaultRows?: AdminDashboardWidgetRows;
+  /** Width when first placed. Defaults to `minSpan`. */
   defaultSpan?: AdminDashboardWidgetSpan;
   icon?: React.ReactNode;
+  /** Unique within the plugin; the board namespaces it as `{pluginId}:{id}`. */
   id: string;
+  /** The narrowest the admin can resize it to. Defaults to `1`. */
   minSpan?: AdminDashboardWidgetSpan;
+  /** Hides the widget from admins without this permission. */
   permission?: AdminNavPermission;
+  /** A form for this instance's `settings`, shown when the admin edits the widget. */
   settingsComponent?: React.ComponentType<AdminDashboardWidgetProps>;
 }
 
+/** Props of a custom AdminCP list cell, registered through {@link contentTypeAdmin}. */
 export interface ContentCellProps<
   TDefinition extends AnyContentTypeDefinition = AnyContentTypeDefinition,
 > {
+  /** The record the row shows, as the admin list returns it. */
   row: ContentSelect<TDefinition>;
 }
 
+/** What a custom create/edit form layout is told about the form it wraps. */
 export interface ContentFormLayoutProps {
   contentTypeId: string;
+  /** The record being edited; `undefined` while creating. */
   itemId?: ContentId;
   mode: "create" | "edit";
   pluginId: string;
@@ -88,12 +183,20 @@ export interface ContentFormLayoutProps {
   title?: string;
 }
 
+/**
+ * A component that replaces the generated create/edit page around a content
+ * type's form. It changes presentation only: the fields, validation and saving
+ * stay the Content Engine's.
+ */
 export type ContentFormLayout = (
   props: ContentFormLayoutProps,
 ) => React.ReactNode;
 
+/** Custom form layouts for a content type's AdminCP create and edit pages. */
 export interface ContentTypeFormsRegistration {
+  /** The create page's layout, overriding `layout`. */
   create?: { layout?: ContentFormLayout };
+  /** The edit page's layout, overriding `layout`. */
   edit?: { layout?: ContentFormLayout };
   /** Used by both create and edit unless one of them overrides it. */
   layout?: ContentFormLayout;
@@ -128,6 +231,13 @@ export interface ContentTypeFrontendRegistration {
   icon?: React.ReactNode;
 }
 
+/**
+ * A plugin's Content Engine AdminCP screens: custom cells, fields and form
+ * layouts per content type. A plugin exports it as `adminContent` from its
+ * `admin/content` module; the VitNode Vite plugin lists it in the app's
+ * generated `src/content-registry.gen.ts`, which the app loads lazily before an
+ * `/admin/content` route runs. Browser-safe, but heavy - it carries editor code.
+ */
 export interface ContentFrontendPluginSource {
   containers?: ContentContainerFrontendRegistration[];
   contentTypes?: ContentTypeFrontendRegistration[];
@@ -144,6 +254,7 @@ interface TypedContentTypeRegistration<
       { cell: (props: ContentCellProps<TDefinition>) => React.ReactNode }
     >
   >;
+  /** The content type definition the plugin also registers on its API. */
   definition: TDefinition;
   /** Replace the generated AutoForm component for a field. */
   fields?: Partial<
@@ -151,30 +262,82 @@ interface TypedContentTypeRegistration<
       keyof TDefinition["fields"] & string,
       {
         component: (props: ItemAutoFormComponentProps) => React.ReactNode;
+        /** The loading placeholder shown while the form loads. */
         skeleton?: ContentFormSkeletonControl;
       }
     >
   >;
 
+  /** Custom create/edit form layouts. Presentation only. */
   forms?: ContentTypeFormsRegistration;
   /** Sidebar icon. Defaults to a generic document icon. */
   icon?: React.ReactNode;
 }
 
+/**
+ * Registers a content type's AdminCP customizations - list cells, form fields,
+ * form layouts and the sidebar icon - in a plugin's `adminContent`
+ * ({@link ContentFrontendPluginSource}).
+ *
+ * It only exists for type checking: `columns` and `fields` are keyed by the
+ * definition's own field names, and the result is widened so content types with
+ * different fields fit in one array. Everything else about the admin screens
+ * comes from the definition itself.
+ *
+ * @example
+ * ```tsx
+ * // src/admin/content.tsx
+ * import type { ContentFrontendPluginSource } from "@vitnode/core/lib/plugin";
+ *
+ * import { contentTypeAdmin } from "@vitnode/core/lib/plugin";
+ *
+ * export const adminContent = {
+ *   pluginId: manifest.id,
+ *   contentTypes: [
+ *     contentTypeAdmin({
+ *       definition: blogCategoryContentType,
+ *       fields: { color: { component: CategoryColorField } },
+ *       columns: { color: { cell: CategoryColorCell } },
+ *     }),
+ *   ],
+ * } satisfies ContentFrontendPluginSource;
+ * ```
+ */
 export function contentTypeAdmin<TDefinition extends AnyContentTypeDefinition>(
   registration: TypedContentTypeRegistration<TDefinition>,
 ): ContentTypeFrontendRegistration {
   return registration as ContentTypeFrontendRegistration;
 }
 
+/**
+ * A plugin's frontend half, as {@link buildPlugin} returns it and an app's
+ * `buildConfig({ plugins })` receives it.
+ */
 export interface BuildPluginReturn<P extends string = string> {
+  /** What the plugin adds to the AdminCP. */
   admin?: {
     dashboard?: {
+      /**
+       * Widgets this plugin offers for the AdminCP dashboard, for hosts that
+       * build the AdminCP from the config. A TanStack Start app reads them
+       * from the plugin's `adminNav` instead ({@link AdminNavPluginSource}).
+       */
       widgets?: AdminDashboardWidget[];
     };
+    /**
+     * Extra links in the plugin's sidebar group, for hosts that build the
+     * navigation from the config. Usually declared on `adminNav` instead.
+     */
     nav?: AdminNavDeclaration[];
   };
+  /** Content containers listed in the plugin's sidebar group. */
   containers?: ContentContainerFrontendRegistration[];
+  /**
+   * Content types listed in the plugin's sidebar group, for hosts that build
+   * the AdminCP navigation from the config itself. A TanStack Start app reads
+   * them from the plugin's `admin/nav` and `admin/content` modules instead - see
+   * {@link AdminNavPluginSource} and {@link ContentFrontendPluginSource}.
+   */
   contentTypes?: ContentTypeFrontendRegistration[];
   /**
    * Every locale file this plugin ships, as literal `*.json` specifiers an
@@ -190,13 +353,23 @@ export interface BuildPluginReturn<P extends string = string> {
    * follow.
    */
   localeFiles?: LocaleFilesMap;
+  /** The plugin's generated manifest (`src/manifest.gen.ts`). */
   manifest?: PluginManifest<P>;
+  /**
+   * Lazy loaders for the plugin's frontend messages, keyed by locale code -
+   * usually the plugin's `src/locales` barrel. Deep-merged into the app's
+   * messages as they are, so each file nests its keys under the plugin id
+   * itself. Bundled apps load `localeFiles` instead.
+   */
   messages?: LocaleMessagesMap;
+  /** The plugin's npm package name, taken from `manifest.id`. */
   pluginId: P;
 
+  /** The plugin's pages, mounted into the app's router. */
   routes?: PluginRoutes;
 }
 
+/** What {@link buildPlugin} accepts: everything it returns except `pluginId`, with `manifest` required. */
 export type BuildPluginOptions<P extends string> = Omit<
   BuildPluginReturn<P>,
   "manifest" | "pluginId"
@@ -204,6 +377,34 @@ export type BuildPluginOptions<P extends string> = Omit<
   manifest: PluginManifest<P>;
 };
 
+/**
+ * Declares a plugin's frontend half: its pages and translations. Its API half is declared separately with `buildApiPlugin` from
+ * `@vitnode/core/api/lib/plugin`; both take the same generated manifest, whose
+ * `id` (the package name) is the plugin id every registration is keyed by.
+ *
+ * Browser-safe: it is imported by the app's frontend config, so keep server-only
+ * code out of everything it references.
+ *
+ * @throws When `manifest` is malformed: an invalid icon name or update source URL.
+ *
+ * @example
+ * ```ts
+ * // src/config.tsx - registered in the app's `buildConfig({ plugins: [blogPlugin()] })`
+ * import { buildPlugin } from "@vitnode/core/lib/plugin";
+ *
+ * import messages from "./locales";
+ * import { manifest } from "./manifest.gen";
+ * import { routes } from "./routes";
+ *
+ * export const blogPlugin = () =>
+ *   buildPlugin({
+ *     manifest,
+ *     localeFiles: { en: "@vitnode/blog/locales/en.json" },
+ *     messages,
+ *     routes,
+ *   });
+ * ```
+ */
 export function buildPlugin<const P extends string>({
   manifest,
   ...props
diff --git a/packages/vitnode/src/lib/query-client.ts b/packages/vitnode/src/lib/query-client.ts
index a95f0c577e..996e3a2b01 100644
--- a/packages/vitnode/src/lib/query-client.ts
+++ b/packages/vitnode/src/lib/query-client.ts
@@ -5,6 +5,12 @@ import {
   QueryClient,
 } from "@tanstack/react-query";
 
+/**
+ * Query `meta` that keeps a query out of the SSR dehydrated cache. Use it on a
+ * query whose data a route's loader already returns - the router sends that
+ * data with the HTML, so dehydrating the query too would send it twice. Leave
+ * it off for queries a page reads with `useSuspenseQuery`.
+ */
 export const LOADER_DATA_QUERY_META = { dehydrate: false } as const;
 
 const shouldDehydrateQuery = (query: Query): boolean =>
diff --git a/packages/vitnode/src/page-cache/config.ts b/packages/vitnode/src/page-cache/config.ts
index 34cb275ffa..6bae9e4773 100644
--- a/packages/vitnode/src/page-cache/config.ts
+++ b/packages/vitnode/src/page-cache/config.ts
@@ -17,17 +17,25 @@ export const PAGE_CACHE_STORAGE_KINDS: readonly PageCacheStorageKind[] = [
   "redis",
 ];
 
+/**
+ * The app's server-rendered HTML cache, `vitNodeConfig.pageCache`. Checked by
+ * the VitNode Vite plugin and by `withPageCache`; an invalid value throws a
+ * `PageCachePolicyError`.
+ */
 export interface PageCacheConfig {
   /**
-   * Turns the HTML cache off for the whole app. On by default in production;
-   * development never caches, so an edit always shows up on reload.
+   * `false` turns the HTML cache off for the whole app. Defaults to `true`;
+   * development never caches either way, so an edit always shows up on reload.
    */
   enabled?: boolean;
   /**
    * Overrides keyed by canonical route path - `"/blog/:slug"` - for a plugin's
-   * route or one of the app's own. `false` turns caching off for that route.
+   * route or one of the app's own: a policy (`{ maxAge, staleWhileRevalidate }`
+   * in whole seconds) replaces the route's own, and `false` turns caching off
+   * for that route. A path that names no page route of the app is an error.
    */
   routes?: Readonly<Record<string, PageCacheSetting>>;
+  /** Where cached pages live. Defaults to `"memory"`. */
   storage?: PageCacheStorageKind;
 }
 
diff --git a/packages/vitnode/src/page-cache/store.server.ts b/packages/vitnode/src/page-cache/store.server.ts
index c06b430f8d..c14c2adde4 100644
--- a/packages/vitnode/src/page-cache/store.server.ts
+++ b/packages/vitnode/src/page-cache/store.server.ts
@@ -17,6 +17,7 @@ import { createCacheClient } from "../api/lib/cache-client";
  */
 export type PageCacheInvalidationMode = "hard" | "soft";
 
+/** `not-configured` when this process serves no page cache, so there was nothing to invalidate. */
 export type PageCacheInvalidationResult =
   | { error: unknown; status: "failed" }
   | { status: "done" }
diff --git a/packages/vitnode/src/routing/authoring.ts b/packages/vitnode/src/routing/authoring.ts
index c4edf26851..3f9a479569 100644
--- a/packages/vitnode/src/routing/authoring.ts
+++ b/packages/vitnode/src/routing/authoring.ts
@@ -33,6 +33,20 @@ export type AuthoredPluginRouteOptions<TData, TSearch, TContext> = Omit<
   ) => Promise<TData> | TData;
 };
 
+/**
+ * A page module's route options - `load`, `head`, `breadcrumb` and friends -
+ * exported as `route` next to the page's default component. Declare `load`
+ * before `head` so `head` and `breadcrumb` receive typed `loaderData`.
+ *
+ * @example
+ * ```ts
+ * import { definePluginRoute } from "@vitnode/core/routing";
+ *
+ * export const route = definePluginRoute({
+ *   head: ({ params }) => ({ title: params.slug }),
+ * });
+ * ```
+ */
 export const definePluginRoute = <
   TData = UnknownLoaderData,
   TSearch = Record<string, never>,
diff --git a/packages/vitnode/src/routing/module.ts b/packages/vitnode/src/routing/module.ts
index 2169799f70..b46b58db01 100644
--- a/packages/vitnode/src/routing/module.ts
+++ b/packages/vitnode/src/routing/module.ts
@@ -145,12 +145,21 @@ export interface PluginRouteOptions<
   parseSearch?: (input: unknown) => TSearch;
 }
 
+/**
+ * The props VitNode passes a plugin page's default export, typed from its
+ * route options: the loader's result, the URL params and the parsed search.
+ */
 export interface PluginRoutePageProps<
   TData = undefined,
   TSearch = Record<string, never>,
 > {
+  /** What the route's `load` returned; `undefined` without one. */
   loaderData: TData;
 
+  /**
+   * Navigates to this page with new search params (same path), e.g. after a filter
+   * changes. `resetScroll: false` keeps the scroll position.
+   */
   navigate: (options: {
     resetScroll?: boolean;
     search: TSearch;
@@ -158,6 +167,7 @@ export interface PluginRoutePageProps<
   /** The route's own dynamic segments, e.g. `{ slug: "hello" }`. */
   params: Readonly<Record<string, string>>;
 
+  /** The query string, as the route's `search` schema parsed it. */
   search: TSearch;
 }
 
diff --git a/packages/vitnode/src/routing/tree.ts b/packages/vitnode/src/routing/tree.ts
index e344b81093..b342bf91e5 100644
--- a/packages/vitnode/src/routing/tree.ts
+++ b/packages/vitnode/src/routing/tree.ts
@@ -13,6 +13,15 @@ export interface PluginRouteLazyComponent<TModule = unknown> {
   readonly load: () => Promise<TModule>;
 }
 
+/**
+ * Marks a route's page module as lazily loaded, so it gets its own chunk.
+ * Every `component` must be wrapped in it.
+ *
+ * @example
+ * ```ts
+ * component: lazy(() => import("./pages/post-page")),
+ * ```
+ */
 export const lazy = <TModule>(
   load: () => Promise<TModule>,
 ): PluginRouteLazyComponent<TModule> => ({
@@ -46,6 +55,11 @@ interface PluginRouteDeclarationShared<TModule> {
   component:
     | '`component` must be lazy(() => import("./pages/my-page")): a component imported into routes.ts is in the initial bundle, so its page cannot be split into a chunk of its own.'
     | PluginRouteLazyComponent<TModule>;
+  /**
+   * Translation namespaces the route renders, as dotted paths into the
+   * plugin's message tree (e.g. `"@vitnode/blog.post"`), so only those strings
+   * are downloaded.
+   */
   messages?: readonly string[];
   /**
    * Drawn while this route loads.
@@ -55,7 +69,18 @@ interface PluginRouteDeclarationShared<TModule> {
    * bundle, and a heavy one is worth a second thought.
    */
   pendingComponent?: React.FunctionComponent;
+  /**
+   * `false` stops hovering a link from running this route's loader early.
+   * Children of a `layout()` inherit it.
+   */
   preload?: boolean;
+  /**
+   * Who may open the route, checked before its chunk downloads:
+   * `"authenticated"` redirects guests to `/login`, `"guest"` redirects
+   * signed-in users away, `"admin-guest"` sends staff with an AdminCP session
+   * into the AdminCP. Not allowed under `area: "admin"`, and a route with
+   * `requires` cannot be cached.
+   */
   requires?: PluginRouteRequirement;
 }
 
@@ -71,6 +96,11 @@ export type PluginRouteComponent<TModule = unknown> =
 export interface PluginRoutePageOptions<
   TModule,
 > extends PluginRouteDeclarationShared<TModule> {
+  /**
+   * The shell the page renders in: `"main"` (default, the public layout),
+   * `"blank"` (no chrome) or `"admin"` (AdminCP, behind the staff session).
+   * Top-level routes only - nested routes use their layout's.
+   */
   area?: PluginRouteArea;
   /**
    * Reuse this page's server-rendered HTML for every visitor, in seconds:
@@ -80,6 +110,10 @@ export interface PluginRoutePageOptions<
    * what is safe to share.
    */
   cache?: PageCacheSetting;
+  /**
+   * Parses the URL's query string before the page chunk loads; its return
+   * type is the page's `search` prop.
+   */
   search?: PluginRouteSearchSchema<TModule>;
 }
 
@@ -88,13 +122,16 @@ export interface PluginRouteIndexOptions<
 > extends PluginRouteDeclarationShared<TModule> {
   /** See {@link PluginRoutePageOptions.cache}. */
   cache?: PageCacheSetting;
+  /** See {@link PluginRoutePageOptions.search}. */
   search?: PluginRouteSearchSchema<TModule>;
 }
 
 export interface PluginRouteLayoutOptions<
   TModule,
 > extends PluginRouteDeclarationShared<TModule> {
+  /** See {@link PluginRoutePageOptions.area}. */
   area?: PluginRouteArea;
+  /** Routes rendered inside this layout; paths are relative to it. */
   children: readonly PluginRouteDeclaration[];
 }
 
@@ -114,6 +151,7 @@ export interface PluginRouteDeclaration {
   readonly search: unknown;
 }
 
+/** A plugin's route tree, as exported from its `src/routes.ts`. */
 export type PluginRoutes = readonly PluginRouteDeclaration[];
 
 export interface PluginRouteDeclarationSource {
@@ -162,6 +200,10 @@ const declaration = (
   search: options.search,
 });
 
+/**
+ * A page at `path`. Use `:name` for a dynamic segment (`/blog/:slug`) and
+ * `*` for a trailing splat.
+ */
 export const page = <TModule>(
   path: string,
   options: PluginRoutePageOptions<TModule>,
@@ -173,6 +215,7 @@ export const page = <TModule>(
     path,
   });
 
+/** The page rendered at its parent `layout()`'s own path. */
 export const index = <TModule>(
   options: PluginRouteIndexOptions<TModule>,
 ): PluginRouteDeclaration =>
@@ -183,6 +226,7 @@ export const index = <TModule>(
     path: null,
   });
 
+/** A shared UI frame around `children`, rendered for every route under `path`. */
 export const layout = <TModule>(
   path: string,
   options: PluginRouteLayoutOptions<TModule>,
@@ -194,6 +238,26 @@ export const layout = <TModule>(
     path,
   });
 
+/**
+ * Declares the URLs a plugin owns, exported as `routes` from its
+ * `src/routes.ts`. The host app turns the tree into lazy TanStack Start
+ * routes; pages never import a router themselves.
+ *
+ * @throws Error When `routes` is not an array or an entry was not built
+ * with `page()`, `layout()` or `index()`.
+ *
+ * @example
+ * ```ts
+ * import { definePluginRoutes, lazy, page } from "@vitnode/core/routing";
+ *
+ * export const routes = definePluginRoutes([
+ *   page("/blog/:slug", {
+ *     component: lazy(() => import("./pages/post-page")),
+ *     messages: ["@vitnode/blog.post"],
+ *   }),
+ * ]);
+ * ```
+ */
 export const definePluginRoutes = (routes: PluginRoutes): PluginRoutes => {
   if (!Array.isArray(routes)) {
     throw new Error(
diff --git a/packages/vitnode/src/tanstack/admin/breadcrumb.tsx b/packages/vitnode/src/tanstack/admin/breadcrumb.tsx
index 4b3d317f01..36032acbab 100644
--- a/packages/vitnode/src/tanstack/admin/breadcrumb.tsx
+++ b/packages/vitnode/src/tanstack/admin/breadcrumb.tsx
@@ -11,6 +11,7 @@ import { BreadcrumbPendingSkeleton } from "../pending/shapes";
 import { routeBreadcrumbGroup } from "../plugin-routes/authoring";
 import { useAdminNav } from "./nav";
 
+/** The AdminCP breadcrumb of the current matches, or a skeleton while navigating. Rendered by the shell. */
 export const useAdminBreadcrumb = (): React.ReactNode => {
   const entries = useBreadcrumbTrail(useMatches());
   const isNavigating = useRouteNavigationPending(
@@ -24,6 +25,10 @@ export const useAdminBreadcrumb = (): React.ReactNode => {
   return <BreadcrumbTrailContent entries={entries} scrollable />;
 };
 
+/**
+ * An AdminCP trail for a path below `/admin`, labelled from the AdminCP
+ * navigation so it matches the sidebar.
+ */
 export const AdminBreadcrumb = ({
   labels,
   overrideLastLabel,
@@ -44,6 +49,14 @@ export const AdminBreadcrumb = ({
   />
 );
 
+/**
+ * {@link AdminBreadcrumb} as a route's `staticData.breadcrumb`.
+ *
+ * @example
+ * ```ts
+ * staticData: { breadcrumb: adminBreadcrumb({ segments: ["core", "users"] }) },
+ * ```
+ */
 export const adminBreadcrumb = <TData = unknown, TSearch = unknown>(
   props: Parameters<typeof AdminBreadcrumb>[0],
 ): PluginRouteBreadcrumbGroup<TData, TSearch> =>
diff --git a/packages/vitnode/src/tanstack/admin/dashboard/route.tsx b/packages/vitnode/src/tanstack/admin/dashboard/route.tsx
index fa1b99fd14..3ad11d384e 100644
--- a/packages/vitnode/src/tanstack/admin/dashboard/route.tsx
+++ b/packages/vitnode/src/tanstack/admin/dashboard/route.tsx
@@ -20,6 +20,7 @@ export interface AdminDashboardRouteData {
   vitnodeVersion?: string;
 }
 
+/** The dashboard route's loader: warms its messages and the admin's saved layout, and returns the running version. */
 export const loadAdminDashboardRoute = async ({
   adminAccess,
   locale,
diff --git a/packages/vitnode/src/tanstack/admin/dashboard/screen.tsx b/packages/vitnode/src/tanstack/admin/dashboard/screen.tsx
index 782edd3fba..b77d8eab6e 100644
--- a/packages/vitnode/src/tanstack/admin/dashboard/screen.tsx
+++ b/packages/vitnode/src/tanstack/admin/dashboard/screen.tsx
@@ -3,12 +3,13 @@ import { AlertTriangleIcon } from "lucide-react";
 import React from "react";
 import { useTranslations } from "use-intl";
 
-import type { AdminDashboardWidget } from "@/lib/plugin";
+import type { AdminNavDashboardWidgets } from "@/views/admin/layouts/sidebar/nav/nav-model";
 import type { DashboardWidgetTranslator } from "@/views/admin/views/core/dashboard/widgets/resolve-widgets";
 
 import { Badge } from "@/components/ui/badge";
 import { PageTitle } from "@/components/ui/page-title";
 import { CONFIG } from "@/lib/config";
+import { fitNamespaceList } from "@/routing";
 import { DashboardBoardProvider } from "@/views/admin/views/core/dashboard/grid/board-provider";
 import { DashboardGrid } from "@/views/admin/views/core/dashboard/grid/dashboard-grid";
 import { DashboardEditActions } from "@/views/admin/views/core/dashboard/grid/edit-actions";
@@ -22,33 +23,59 @@ import type { AdminDashboardRouteData } from "./route";
 
 import { RouteMessages } from "../../i18n/route-messages";
 import { useAdminIdentity } from "../identity";
+import { useAdminDashboardPluginWidgets } from "../nav";
 import { useAdminPermissions } from "../permissions";
 import { dashboardLayoutQuery, useDashboardActions } from "./query";
 import { ADMIN_DASHBOARD_NAMESPACES } from "./route";
 import { coreDashboardBrowserWidgets } from "./widgets";
 
-export interface DashboardPluginWidgets {
-  pluginId: string;
-  widgets: AdminDashboardWidget[];
-}
+/** One plugin's dashboard widgets, keyed by the plugin that declared them. */
+export type DashboardPluginWidgets = AdminNavDashboardWidgets;
 
 export interface AdminDashboardRouteProps extends AdminDashboardRouteData {
+  /**
+   * Plugin widgets to offer next to core's. Defaults to the ones the AdminCP
+   * shell was given: each plugin's `adminNav.admin.dashboard.widgets`, from
+   * the app's generated `admin-nav.gen.ts`.
+   */
   pluginWidgets?: DashboardPluginWidgets[];
 }
 
+/**
+ * The AdminCP dashboard screen: the admin's widget board, saved per admin,
+ * with core's widgets plus the plugins'. Widgets the admin lacks the
+ * permission for are left out. Loads each widget plugin's `title` and
+ * `admin.dashboard.widgets` messages on top of the dashboard's own.
+ */
 export const AdminDashboardRouteContent = ({
-  pluginWidgets = [],
+  pluginWidgets,
   vitnodeVersion,
-}: AdminDashboardRouteProps) => (
-  <RouteMessages namespaces={ADMIN_DASHBOARD_NAMESPACES}>
-    <div className="p-6">
-      <AdminDashboardBoard
-        pluginWidgets={pluginWidgets}
-        vitnodeVersion={vitnodeVersion}
-      />
-    </div>
-  </RouteMessages>
-);
+}: AdminDashboardRouteProps) => {
+  const shellWidgets = useAdminDashboardPluginWidgets();
+  const widgets = pluginWidgets ?? shellWidgets;
+  const namespaces = React.useMemo(
+    () =>
+      fitNamespaceList([
+        ...ADMIN_DASHBOARD_NAMESPACES,
+        ...widgets.flatMap(({ pluginId }) => [
+          `${pluginId}.title`,
+          `${pluginId}.admin.dashboard.widgets`,
+        ]),
+      ]),
+    [widgets],
+  );
+
+  return (
+    <RouteMessages namespaces={namespaces}>
+      <div className="p-6">
+        <AdminDashboardBoard
+          pluginWidgets={widgets}
+          vitnodeVersion={vitnodeVersion}
+        />
+      </div>
+    </RouteMessages>
+  );
+};
 
 const AdminDashboardBoard = ({
   pluginWidgets,
diff --git a/packages/vitnode/src/tanstack/admin/index.ts b/packages/vitnode/src/tanstack/admin/index.ts
index 2a1ca0ec54..f0dfd09887 100644
--- a/packages/vitnode/src/tanstack/admin/index.ts
+++ b/packages/vitnode/src/tanstack/admin/index.ts
@@ -9,7 +9,12 @@ export { defaultAdminTransport } from "./default-transport";
 export * from "./intl";
 export type { AdminNavModule } from "./layout-route";
 export { adminLayoutRoute } from "./layout-route";
-export { AdminNavProvider, useAdminNav, useAdminSearchNavItems } from "./nav";
+export {
+  AdminNavProvider,
+  useAdminDashboardPluginWidgets,
+  useAdminNav,
+  useAdminSearchNavItems,
+} from "./nav";
 export * from "./permissions";
 export { removeAdminIdentityQueries, removeAdminShellQueries } from "./queries";
 export * from "./return-to";
@@ -80,6 +85,7 @@ export type {
 export type {
   AdminNavBundle,
   AdminNavConfig,
+  AdminNavDashboardWidgets,
   AdminNavGroupDeclaration,
   AdminNavItem,
   AdminNavItemDeclaration,
diff --git a/packages/vitnode/src/tanstack/admin/layout-route.tsx b/packages/vitnode/src/tanstack/admin/layout-route.tsx
index 14891b950f..4531d94ddc 100644
--- a/packages/vitnode/src/tanstack/admin/layout-route.tsx
+++ b/packages/vitnode/src/tanstack/admin/layout-route.tsx
@@ -12,8 +12,26 @@ import { adminReturnToFor } from "./return-to";
 import { ensureAdminAccess, preloadAdminAccess } from "./session-query";
 import { ADMIN_ENTRY_PATH, canEnterAdmin } from "./state";
 
+/** Lazily imports the app's generated `src/admin-nav.gen.ts`. */
 export type AdminNavModule = () => Promise<{ adminNav: AdminNavBundle }>;
 
+/**
+ * The route options of the AdminCP layout (`/_admin`): redirects anyone
+ * without admin access to the AdminCP sign-in with a `returnTo`, loads the
+ * navigation's messages, marks every page `noindex, nofollow` and lazily
+ * renders the shell. Child routes get `adminAccess` in their context.
+ *
+ * @example
+ * ```ts
+ * // src/routes/_admin.tsx
+ * import { createFileRoute } from "@tanstack/react-router";
+ * import { adminLayoutRoute } from "@vitnode/core/tanstack/admin";
+ *
+ * export const Route = createFileRoute("/_admin")(
+ *   adminLayoutRoute(async () => await import("@/admin-nav.gen")),
+ * );
+ * ```
+ */
 export const adminLayoutRoute = (navModule: AdminNavModule) => ({
   beforeLoad: async ({
     context,
diff --git a/packages/vitnode/src/tanstack/admin/nav.tsx b/packages/vitnode/src/tanstack/admin/nav.tsx
index ee3e8ba2aa..51f4feab94 100644
--- a/packages/vitnode/src/tanstack/admin/nav.tsx
+++ b/packages/vitnode/src/tanstack/admin/nav.tsx
@@ -3,6 +3,7 @@ import { useTranslations } from "use-intl";
 
 import type { AdminSearchNavItem } from "@/views/admin/layouts/search/flatten-nav";
 import type {
+  AdminNavDashboardWidgets,
   AdminNavGroupDeclaration,
   AdminNavTranslator,
   NavAdminParent,
@@ -24,16 +25,23 @@ interface AdminNavValue {
 
 const AdminNavContext = React.createContext<AdminNavValue | null>(null);
 
+const NO_DASHBOARD_WIDGETS: AdminNavDashboardWidgets[] = [];
+
+const AdminDashboardWidgetsContext =
+  React.createContext<AdminNavDashboardWidgets[]>(NO_DASHBOARD_WIDGETS);
+
 const CORE_ONLY_DECLARATIONS: AdminNavGroupDeclaration[] = adminNavDeclarations(
   { plugins: [] },
 );
 
 export const AdminNavProvider = ({
   children,
+  dashboardWidgets = NO_DASHBOARD_WIDGETS,
   declarations = CORE_ONLY_DECLARATIONS,
 }: {
   children: React.ReactNode;
-
+  /** The plugins' dashboard widgets from the app's `admin-nav.gen.ts`, for the dashboard screen. */
+  dashboardWidgets?: AdminNavDashboardWidgets[];
   declarations?: AdminNavGroupDeclaration[];
 }) => {
   const permissions = useAdminPermissions();
@@ -53,9 +61,23 @@ export const AdminNavProvider = ({
     };
   }, [declarations, permissions, t]);
 
-  return <AdminNavContext value={value}>{children}</AdminNavContext>;
+  return (
+    <AdminNavContext value={value}>
+      <AdminDashboardWidgetsContext value={dashboardWidgets}>
+        {children}
+      </AdminDashboardWidgetsContext>
+    </AdminNavContext>
+  );
 };
 
+/**
+ * The plugins' dashboard widgets the AdminCP shell was given - each plugin's
+ * `adminNav.admin.dashboard.widgets`, collected into the app's
+ * `admin-nav.gen.ts`. Empty outside the shell.
+ */
+export const useAdminDashboardPluginWidgets = (): AdminNavDashboardWidgets[] =>
+  React.use(AdminDashboardWidgetsContext);
+
 const useAdminNavValue = (): AdminNavValue => {
   const value = React.use(AdminNavContext);
 
diff --git a/packages/vitnode/src/tanstack/admin/permissions.tsx b/packages/vitnode/src/tanstack/admin/permissions.tsx
index 62e10f2ae5..87fb74be94 100644
--- a/packages/vitnode/src/tanstack/admin/permissions.tsx
+++ b/packages/vitnode/src/tanstack/admin/permissions.tsx
@@ -15,6 +15,7 @@ import type { AdminAccessState, AdminSessionApi } from "./session-api";
 import { useAdminSessionQuery } from "./session-query";
 import { adminPermissionsOf, hasAdminPermission } from "./state";
 
+/** Provides the signed-in admin's staff permissions to the hooks below. Mounted by the AdminCP shell. */
 export const AdminPermissionsProvider = ({
   children,
 }: {
@@ -29,18 +30,32 @@ export const AdminPermissionsProvider = ({
   );
 };
 
+/** The AdminCP access state: `granted` with the admin session, or `denied`. Suspends until known. */
 export const useAdminAccess = (): AdminAccessState =>
   useAdminSessionQuery().data;
 
+/** The signed-in admin, or `null` when access is not granted. */
 export const useAdminUser = (): AdminSessionApi["user"] | null => {
   const access = useAdminAccess();
 
   return access.status === "granted" ? access.session.user : null;
 };
 
+/** Every staff permission the signed-in admin holds, inside the AdminCP shell. */
 export const useAdminPermissions: () => StaffPermissionSet =
   useAdminStaffPermissions;
 
+/**
+ * Whether the signed-in admin holds one permission - for hiding a button or a
+ * tab. UI only: the API route must still check it with `adminStaffPermission`.
+ *
+ * @example
+ * ```tsx
+ * import { useAdminPermission } from "@vitnode/core/tanstack/admin";
+ *
+ * const canDelete = useAdminPermission({ plugin: "@vitnode/blog", module: "posts", permission: "can_delete" });
+ * ```
+ */
 export const useAdminPermission: (args: PermissionsStaffArgs) => boolean =
   useAdminStaffPermission;
 
diff --git a/packages/vitnode/src/tanstack/admin/screen.ts b/packages/vitnode/src/tanstack/admin/screen.ts
index 0a237eb9ac..4a6af4242b 100644
--- a/packages/vitnode/src/tanstack/admin/screen.ts
+++ b/packages/vitnode/src/tanstack/admin/screen.ts
@@ -7,10 +7,18 @@ import type { AdminAccessState } from "./session-api";
 
 import { hasAdminPermission } from "./state";
 
+/** The loader context of a route inside the AdminCP shell. */
 export interface AdminScreenContext extends AdminLoaderContext {
   adminAccess: AdminAccessState;
 }
 
+/**
+ * Stops an AdminCP route's loader unless the admin holds the permission, so the
+ * screen renders the not-found page instead. `plugin` defaults to
+ * `@vitnode/core`. Pair it with the API route's own `adminStaffPermission`.
+ *
+ * @throws TanStack Router's `notFound()` without the permission.
+ */
 export const requireAdminPermission = (
   access: AdminAccessState,
   args: Omit<PermissionsStaffArgs, "plugin"> & { plugin?: string },
diff --git a/packages/vitnode/src/tanstack/admin/session-query.ts b/packages/vitnode/src/tanstack/admin/session-query.ts
index 75597bf490..c2944d4bef 100644
--- a/packages/vitnode/src/tanstack/admin/session-query.ts
+++ b/packages/vitnode/src/tanstack/admin/session-query.ts
@@ -32,6 +32,13 @@ export const adminSessionQueryOptions = () =>
     staleTime: ADMIN_SESSION_STALE_TIME,
   });
 
+/**
+ * The admin session as a suspense query: `data` is `{ status: "granted",
+ * session }` or `{ status: "denied" }`, never empty, so the component
+ * suspends while it loads. Not retried; stale immediately (stale time 0), so
+ * an invalidation always refetches it. A session that cannot be read (not a denial) throws
+ * `AdminSessionUnavailableError` to the nearest error boundary.
+ */
 export const useAdminSessionQuery = () =>
   useSuspenseQuery(adminSessionQueryOptions());
 
diff --git a/packages/vitnode/src/tanstack/admin/shell.tsx b/packages/vitnode/src/tanstack/admin/shell.tsx
index d0012b84a3..7d5929019a 100644
--- a/packages/vitnode/src/tanstack/admin/shell.tsx
+++ b/packages/vitnode/src/tanstack/admin/shell.tsx
@@ -48,7 +48,10 @@ export const AdminShellContent = ({
     <RouteMessages namespaces={namespaces}>
       <AdminPermissionsProvider>
         <AdminSessionGuard />
-        <AdminNavProvider declarations={nav?.declarations}>
+        <AdminNavProvider
+          dashboardWidgets={nav?.dashboardWidgets}
+          declarations={nav?.declarations}
+        >
           <AdminShellFrame onNavigate={onNavigate} searchUsers={searchUsers}>
             <RouteGuardPending>
               <Outlet />
diff --git a/packages/vitnode/src/tanstack/admin/state.ts b/packages/vitnode/src/tanstack/admin/state.ts
index de190b9733..c5dd14a04f 100644
--- a/packages/vitnode/src/tanstack/admin/state.ts
+++ b/packages/vitnode/src/tanstack/admin/state.ts
@@ -106,6 +106,7 @@ export const adminPermissionsOf = <TSession extends { permissions: unknown }>(
     ? (access.session.permissions as StaffPermissionSet)
     : EMPTY_STAFF_PERMISSION_SET;
 
+/** Whether an admin access state grants one permission. `plugin` defaults to `@vitnode/core`. */
 export const hasAdminPermission = <TSession extends { permissions: unknown }>(
   access: AdminAccess<TSession>,
   {
diff --git a/packages/vitnode/src/tanstack/auth/middleware-config.ts b/packages/vitnode/src/tanstack/auth/middleware-config.ts
index 659a29bccc..e6ad5c7f4b 100644
--- a/packages/vitnode/src/tanstack/auth/middleware-config.ts
+++ b/packages/vitnode/src/tanstack/auth/middleware-config.ts
@@ -10,10 +10,15 @@ import { manifest } from "@/manifest";
 import { fetcher } from "@/tanstack/fetcher";
 import { normalizeSSOProviders } from "@/views/auth/sso/providers";
 
+/** The deployment's public configuration: enabled sign-in methods, SSO providers, email and AI availability, and the captcha provider. */
 export type MiddlewareConfig = z.infer<typeof routeMiddlewareSchema>;
 
 export interface MiddlewareConfigState extends MiddlewareConfig {
   isDeferred: boolean;
+  /**
+   * `false` when the API could not be read; the other fields then hold safe
+   * defaults (password sign-in only) and the query refetches on the next mount.
+   */
   isKnown: boolean;
 }
 
@@ -61,6 +66,11 @@ const fetchMiddlewareConfig = async (): Promise<MiddlewareConfigState> => {
 /** Everything a middleware-configuration cache entry's key starts with. */
 const MIDDLEWARE_QUERY_KEY = ["vitnode", "middleware"] as const;
 
+/**
+ * The deployment configuration as a TanStack Query. A successful answer is
+ * cached for the life of the page; a failed one resolves to defaults with
+ * `isKnown: false` (it never rejects) and is retried on the next mount.
+ */
 export const middlewareConfigQueryOptions = () =>
   queryOptions({
     gcTime: Infinity,
@@ -70,6 +80,7 @@ export const middlewareConfigQueryOptions = () =>
     staleTime: query => (query.state.data?.isKnown ? Infinity : 0),
   });
 
+/** Loads the deployment configuration in a route loader, reusing a known answer. */
 export const loadMiddlewareConfig = async (
   queryClient: QueryClient,
 ): Promise<MiddlewareConfigState> =>
@@ -85,9 +96,16 @@ export class MiddlewareConfigUnknownError extends Error {
   }
 }
 
+/**
+ * The deployment configuration in a component - which sign-in methods and SSO
+ * providers exist, whether email or AI is set up. Suspends until loaded, so
+ * render it under a `Suspense` boundary or warm it with
+ * {@link loadMiddlewareConfig}.
+ */
 export const useMiddlewareConfigQuery = () =>
   useSuspenseQuery(middlewareConfigQueryOptions());
 
+/** Refetches the deployment configuration, e.g. after an admin changes it. */
 export const invalidateMiddlewareConfig = async (
   queryClient: QueryClient,
 ): Promise<void> =>
@@ -104,6 +122,7 @@ export interface AuthMethods {
   sso: SSOProvider[];
 }
 
+/** Which sign-in, sign-up and recovery methods the deployment offers. */
 export const authMethodsOf = (config: MiddlewareConfig): AuthMethods => {
   const sso = ssoProvidersOf(config);
 
diff --git a/packages/vitnode/src/tanstack/auth/session-query.ts b/packages/vitnode/src/tanstack/auth/session-query.ts
index 8e305338d6..8587121afe 100644
--- a/packages/vitnode/src/tanstack/auth/session-query.ts
+++ b/packages/vitnode/src/tanstack/auth/session-query.ts
@@ -11,6 +11,13 @@ import { authTransport } from "./transport";
 
 const SESSION_STALE_TIME = 30_000;
 
+/**
+ * The current visitor's session as a TanStack Query: `{ user }`, the signed-in
+ * user (with `isAdmin`, `isModerator` and notification state) or `null` for a
+ * guest. Fresh for 30 seconds, never
+ * retried. Use it to warm the session in a loader; read it in components with
+ * {@link useSessionQuery}.
+ */
 export const sessionQueryOptions = () =>
   queryOptions({
     queryFn: async () => await authTransport().readSession(),
@@ -19,6 +26,7 @@ export const sessionQueryOptions = () =>
     staleTime: SESSION_STALE_TIME,
   });
 
+/** The session query's data and status, as {@link useSessionQuery} returns them. */
 export interface SessionQueryView {
   data: SessionApi | undefined;
   isError: boolean;
@@ -44,6 +52,20 @@ const renderedSessionOf = (queryClient: QueryClient): SessionQueryView => {
 
 const subscribeToNothing = () => () => undefined;
 
+/**
+ * The current visitor's session in a component - `data.user` is `null` for a
+ * guest. During hydration it returns what the server rendered with, so markup
+ * that depends on the session never mismatches; afterwards it follows the live
+ * query.
+ *
+ * @example
+ * ```tsx
+ * import { useSessionQuery } from "@vitnode/core/tanstack/auth";
+ *
+ * const { data } = useSessionQuery();
+ * if (!data?.user) return <SignInButton />;
+ * ```
+ */
 export const useSessionQuery = (): SessionQueryView => {
   const queryClient = useQueryClient();
   const { data, isError, isPending } = useQuery(sessionQueryOptions());
@@ -56,11 +78,17 @@ export const useSessionQuery = (): SessionQueryView => {
   return rendered ?? { data, isError, isPending };
 };
 
+/**
+ * Loads the session (from cache when fresh) and narrows it to an
+ * `AuthState` - for a loader or `beforeLoad` that must know whether the
+ * visitor is signed in or an admin.
+ */
 export const ensureAuthState = async (
   queryClient: QueryClient,
 ): Promise<AuthState> =>
   authStateFromSession(await queryClient.query(sessionQueryOptions()));
 
+/** Replaces the cached session, e.g. with the one a sign-in answered. */
 export const setSessionData = (
   queryClient: QueryClient,
   session: SessionApi,
@@ -68,11 +96,13 @@ export const setSessionData = (
   queryClient.setQueryData(sessionQueryOptions().queryKey, session);
 };
 
+/** Marks the cached session stale and refetches it where it is observed - after anything that changes who is signed in. */
 export const invalidateSession = async (
   queryClient: QueryClient,
 ): Promise<void> =>
   await queryClient.invalidateQueries({ queryKey: SESSION_QUERY_KEY });
 
+/** Warms the session query, ignoring failures. */
 export const prefetchSession = async (
   queryClient: QueryClient,
 ): Promise<void> => {
diff --git a/packages/vitnode/src/tanstack/auth/state.ts b/packages/vitnode/src/tanstack/auth/state.ts
index 61cf6b300f..a457697b59 100644
--- a/packages/vitnode/src/tanstack/auth/state.ts
+++ b/packages/vitnode/src/tanstack/auth/state.ts
@@ -2,6 +2,7 @@ import type { SessionApi } from "./session-api";
 
 export type AuthUser = NonNullable<SessionApi["user"]>;
 
+/** The visitor, narrowed by `isAuthenticated`: a signed-in user, or a guest with `user: null`. */
 export type AuthState =
   | {
       isAdmin: boolean;
@@ -18,6 +19,7 @@ export type AuthState =
 
 export const SESSION_QUERY_KEY = ["vitnode", "session"] as const;
 
+/** Narrows a session answer to an {@link AuthState}. */
 export const authStateFromSession = (session: SessionApi): AuthState => {
   const { user } = session;
 
diff --git a/packages/vitnode/src/tanstack/breadcrumb/main-breadcrumb.tsx b/packages/vitnode/src/tanstack/breadcrumb/main-breadcrumb.tsx
index 324342d28d..822b2b0a0a 100644
--- a/packages/vitnode/src/tanstack/breadcrumb/main-breadcrumb.tsx
+++ b/packages/vitnode/src/tanstack/breadcrumb/main-breadcrumb.tsx
@@ -6,6 +6,11 @@ import { useRouteNavigationPending } from "../pending/navigation-pending";
 import { BreadcrumbPendingSkeleton } from "../pending/shapes";
 import { useBreadcrumbTrail } from "./model";
 
+/**
+ * The site breadcrumb, built from the matched routes' `staticData.breadcrumb`.
+ * Renders nothing when no route declares one, and a skeleton while a
+ * navigation is pending. Rendered by the main layout.
+ */
 export const MainBreadcrumb = () => {
   const entries = useBreadcrumbTrail(useMatches());
   const isNavigating = useRouteNavigationPending(
diff --git a/packages/vitnode/src/tanstack/breadcrumb/model.ts b/packages/vitnode/src/tanstack/breadcrumb/model.ts
index a9dfc37696..b762d2780f 100644
--- a/packages/vitnode/src/tanstack/breadcrumb/model.ts
+++ b/packages/vitnode/src/tanstack/breadcrumb/model.ts
@@ -6,6 +6,7 @@ declare module "@tanstack/react-router" {
   }
 }
 
+/** What a breadcrumb component receives: its route match's data. */
 export interface RouteBreadcrumbProps {
   loaderData: unknown;
   params: Readonly<Record<string, string>>;
@@ -14,25 +15,59 @@ export interface RouteBreadcrumbProps {
   search: unknown;
 }
 
+/** A crumb component that renders several `<BreadcrumbItem>`s itself. Create it with {@link breadcrumbGroup}. */
 export interface RouteBreadcrumbGroup {
   group: React.ComponentType<RouteBreadcrumbProps>;
 }
 
+/**
+ * What a route declares as `staticData.breadcrumb`: a node (`<span>Docs</span>`),
+ * a component reading the match (`({ loaderData }) => ...`), a group, or `false`
+ * for no crumb.
+ */
 export type RouteBreadcrumbDeclaration =
   | false
   | React.ComponentType<RouteBreadcrumbProps>
   | React.ReactNode
   | RouteBreadcrumbGroup;
 
+/** A crumb only known later (e.g. registered by a lazily loaded module). Create it with {@link breadcrumbDeferred}. */
 export interface RouteBreadcrumbDeferred {
   resolve: () => RouteBreadcrumbDeclaration | undefined;
   subscribe: (listener: () => void) => () => void;
 }
 
+/**
+ * A route's breadcrumb, set as `staticData.breadcrumb` in its route options.
+ * Each matched route that declares one contributes a crumb linking to its own
+ * URL; the last one is the current page. A crumb that renders strings needs
+ * its own `RouteMessages`.
+ *
+ * @example
+ * ```tsx
+ * // src/site/solutions/breadcrumb.tsx
+ * export const SolutionsBreadcrumb = () => (
+ *   <RouteMessages>
+ *     <span>Solutions</span>
+ *   </RouteMessages>
+ * );
+ *
+ * // src/routes/_main/solutions/index.tsx
+ * export const Route = createFileRoute("/_main/solutions/")({
+ *   staticData: { breadcrumb: <SolutionsBreadcrumb /> },
+ *   component: SolutionsIndexPage,
+ * });
+ * ```
+ */
 export type RouteBreadcrumb =
   | RouteBreadcrumbDeclaration
   | RouteBreadcrumbDeferred;
 
+/**
+ * Declares a crumb resolved later. The trail re-renders when `subscribe`
+ * reports that `resolve` started (or stopped) returning a crumb - not when an
+ * already resolved crumb changes.
+ */
 export const breadcrumbDeferred = (
   resolve: RouteBreadcrumbDeferred["resolve"],
   subscribe: RouteBreadcrumbDeferred["subscribe"],
@@ -87,6 +122,7 @@ const propsFor = (match: BreadcrumbMatch): RouteBreadcrumbProps => ({
   search: match.search,
 });
 
+/** The trail for a list of route matches, outermost first - the pure half of {@link useBreadcrumbTrail}. */
 export const breadcrumbTrail = (
   matches: readonly BreadcrumbMatch[],
 ): BreadcrumbTrailEntry[] => {
@@ -157,6 +193,7 @@ const deferredCrumbs = (
 const resolutionOf = (deferred: readonly RouteBreadcrumbDeferred[]): string =>
   deferred.map(entry => (entry.resolve() === undefined ? "-" : "+")).join("");
 
+/** The breadcrumb trail of the current matches, kept in sync with deferred crumbs. */
 export const useBreadcrumbTrail = (
   matches: readonly BreadcrumbMatch[],
 ): BreadcrumbTrailEntry[] => {
diff --git a/packages/vitnode/src/tanstack/content/delivery-page.ts b/packages/vitnode/src/tanstack/content/delivery-page.ts
index a72e763b27..0dd4115cfe 100644
--- a/packages/vitnode/src/tanstack/content/delivery-page.ts
+++ b/packages/vitnode/src/tanstack/content/delivery-page.ts
@@ -6,24 +6,37 @@ import { stripHtml } from "@/lib/strip-html";
 
 const DESCRIPTION_MAX_LENGTH = 160;
 
+/** One translation of a delivered page, as an internal (unprefixed) path. */
 export interface ContentDeliveryPageAlternate {
   internalPath: string;
   locale: string;
 }
 
+/** The SEO data a Content Engine delivery answer carries for one page. */
 export interface ContentDeliveryPageMetadata {
+  /** The page in every locale it is published in, the current one included. */
   alternates: readonly ContentDeliveryPageAlternate[];
   canonicalInternalPath: null | string;
+  /** The locale the content was resolved in, which may be a fallback locale. */
   locale: null | string;
   robots: null | { follow: boolean; index: boolean };
+  /** SEO overrides; `description` may contain HTML. */
   seo: { description: null | string; title: null | string };
 }
 
+/** What resolving a public content URL answered: the page, a redirect, or nothing. */
 export type ContentDeliveryPageResolution =
   | (ContentDeliveryPageMetadata & { type: "content" })
   | { location: string; status: number; type: "redirect" }
   | { type: "not_found" };
 
+/**
+ * Returns `item`, or throws TanStack Router's `notFound()` when it is `null` or
+ * `undefined` - so a route `loader` that read a missing record renders the
+ * not-found page instead of an empty one.
+ *
+ * @throws TanStack Router's `notFound()` for a missing item.
+ */
 export const contentPageItem = <TItem>(
   item: null | TItem | undefined,
 ): TItem => {
@@ -33,6 +46,34 @@ export const contentPageItem = <TItem>(
   return item;
 };
 
+/**
+ * Turns a Content Engine delivery answer into a route loader result: follows a
+ * `redirect` (old slug, canonical locale path) with its status code, throws
+ * `notFound()` for `not_found` or a missing item, and otherwise returns the item
+ * with the page metadata for {@link contentDeliveryPageHead}.
+ *
+ * Call it in a `loader`, where TanStack Router handles the thrown redirect and
+ * not-found.
+ *
+ * @throws TanStack Router's `redirect()` or `notFound()`.
+ *
+ * @example
+ * ```ts
+ * import { contentDeliveryPage, contentDeliveryPageHead } from "@vitnode/core/tanstack/content";
+ * import { defineRoute } from "@vitnode/core/tanstack/plugin-routes";
+ *
+ * export const route = defineRoute({
+ *   load: async ({ context, params }) =>
+ *     contentDeliveryPage(
+ *       await context.queryClient.query(
+ *         blogPostQueryOptions({ locale: context.locale, slug: params.slug }),
+ *       ),
+ *     ),
+ *   head: ({ loaderData }) =>
+ *     contentDeliveryPageHead(loaderData?.metadata, { title: loaderData?.item.title }),
+ * });
+ * ```
+ */
 export const contentDeliveryPage = <
   TResolution extends ContentDeliveryPageResolution,
   TItem,
@@ -92,6 +133,12 @@ const internalAlternates = (
   return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 };
 
+/**
+ * A plugin route's `head` for a delivered content page: the SEO title (or
+ * `title` as fallback), a plain-text description cut to 160 characters, the
+ * locale alternates, and `noindex, nofollow` when the page must not be
+ * indexed. Returns just `title` while there is no metadata yet.
+ */
 export const contentDeliveryPageHead = (
   metadata: ContentDeliveryPageMetadata | undefined,
   { title }: { title?: string } = {},
diff --git a/packages/vitnode/src/tanstack/fetcher/index.ts b/packages/vitnode/src/tanstack/fetcher/index.ts
index 17d3a31b3d..361c919e28 100644
--- a/packages/vitnode/src/tanstack/fetcher/index.ts
+++ b/packages/vitnode/src/tanstack/fetcher/index.ts
@@ -29,10 +29,56 @@ export type {
 
 type IsomorphicFetcher = (request: never) => Promise<Response>;
 
+/**
+ * Calls a VitNode API route with types inferred from the plugin API registry.
+ * Universal: the same call runs during SSR and in the browser, so use it in
+ * route loaders, query functions and shared `views/*` modules.
+ *
+ * `plugin`, `module` (any nesting depth, e.g. `admin/advanced/cron`), `path`
+ * and `method` must name a registered route - a wrong one is a compile error
+ * at that property. `args` (`body`, `params`, `query`) is typed by the route's
+ * Zod schemas and required exactly when the route declares one of them. The
+ * response's `json()` and `status` are typed per declared response.
+ *
+ * On the server it forwards the visitor's cookie, user agent and IP to the API
+ * at `VITNODE_API_URL` (or this request's origin). In the browser it sends
+ * credentials and reports a `429` as a `vitnode:rate-limit` window event. For
+ * server-only options - `allowSaveCookies`, `additionalHeaders`, `origin` - use
+ * the fetcher from `@vitnode/core/tanstack/fetcher/server`.
+ *
+ * Resolves with the `Response` for every status except `500` - check `res.ok`
+ * or `res.status` before reading the body; any other `4xx` or `5xx` is also
+ * logged to the console. Rejects on a `500` (with the response body in the
+ * message) and on network failure.
+ *
+ * @example
+ * ```ts
+ * import { fetcher } from "@vitnode/core/tanstack/fetcher";
+ *
+ * const res = await fetcher({
+ *   plugin: "@vitnode/core",
+ *   method: "get",
+ *   module: "users",
+ *   path: "/devices",
+ * });
+ * if (!res.ok) throw new Error("Could not load devices");
+ * const devices = await res.json();
+ * ```
+ */
 export const fetcher = createIsomorphicFn()
   .server(serverFetcher as IsomorphicFetcher)
   .client(fetcherClient) as UniversalFetcher;
 
+/**
+ * An untyped, universal API call, for the Content Engine's generated admin
+ * modules, which have no route types to infer from. Everything else - including
+ * a content type's public routes (`module: "content/<publicApi.path>"`) - uses
+ * the typed {@link fetcher}.
+ *
+ * Same transport and status handling as {@link fetcher}, except that a browser
+ * `429` dispatches no `vitnode:rate-limit` event. `pluginId`, `module`, `path`,
+ * `params`, `query` and `body` are passed as they are.
+ */
 export const rawFetcher = createIsomorphicFn()
   .server(serverRawFetcher)
   .client(rawFetcherClient) as UniversalRawFetcher;
diff --git a/packages/vitnode/src/tanstack/fetcher/server.ts b/packages/vitnode/src/tanstack/fetcher/server.ts
index 72da87fd90..030534e887 100644
--- a/packages/vitnode/src/tanstack/fetcher/server.ts
+++ b/packages/vitnode/src/tanstack/fetcher/server.ts
@@ -38,6 +38,10 @@ import { recordPageCacheApiResponse } from "@/page-cache/render-context.server";
 
 config({ quiet: true });
 
+/**
+ * The origin server-side API calls go to: `VITNODE_API_URL` when set (a
+ * separate API server), otherwise the origin of the request being handled.
+ */
 export const resolveApiOrigin = (): string => {
   // Through `CONFIG` rather than the variable directly, so the empty-value
   // throw stays in one place - see the `??` note there.
@@ -115,6 +119,11 @@ const withRequestSignal = (options: FetchOptions): FetchOptions => {
   };
 };
 
+/**
+ * The headers that make a server-side API call act for the current visitor:
+ * their cookie, user agent and IP (`x-forwarded-for`, signed when a forwarding
+ * secret is configured), plus the captcha token when given.
+ */
 export const getForwardedApiHeaders = ({
   captchaToken,
 }: { captchaToken?: string } = {}): Record<string, string> => {
@@ -141,6 +150,7 @@ export const getForwardedApiHeaders = ({
   };
 };
 
+/** Copies an API response's `Set-Cookie` headers onto the current SSR response. */
 export const saveApiCookies = (response: Response): void => {
   for (const { name, options, value } of parseSetCookies(
     response.headers.getSetCookie(),
@@ -149,6 +159,10 @@ export const saveApiCookies = (response: Response): void => {
   }
 };
 
+/**
+ * The server-only {@link fetcher} for untyped calls - generated Content Engine
+ * admin modules. Forwards the visitor's headers like the typed one.
+ */
 export const rawFetcher = async ({
   additionalHeaders,
   options,
@@ -169,11 +183,44 @@ export const rawFetcher = async ({
   return response;
 };
 
+/** What the server-only {@link fetcher} accepts besides the route and `args`. */
 export type FetcherServerOptions = FetcherRequestOptions & {
+  /**
+   * Relays the API's `Set-Cookie` headers to the visitor's browser on a `2xx`
+   * response - for sign-in, sign-out and other calls that change the session
+   * from a server function. Defaults to `false`.
+   */
   allowSaveCookies?: boolean;
+  /** Sent as `x-vitnode-captcha-token`, for routes built with `withCaptcha`. */
   captchaToken?: string;
 };
 
+/**
+ * The server-only twin of the universal `fetcher` from
+ * `@vitnode/core/tanstack/fetcher`: same call shape and inference, plus
+ * `allowSaveCookies`, `additionalHeaders` and `origin`.
+ *
+ * Use it only for work that is genuinely server-side: server functions, cookie
+ * relay, cron and jobs, calls that carry upstream secrets or target another
+ * origin. Importing it into a browser bundle fails the build.
+ *
+ * Resolves with the `Response` for every status except `500` and rejects on a
+ * `500` or a network failure, like the universal fetcher.
+ *
+ * @example
+ * ```ts
+ * import { fetcher } from "@vitnode/core/tanstack/fetcher/server";
+ *
+ * const res = await fetcher({
+ *   plugin: "@vitnode/core",
+ *   method: "delete",
+ *   module: "users",
+ *   path: "/sign_out",
+ *   args: { body: {} },
+ *   allowSaveCookies: true,
+ * });
+ * ```
+ */
 export async function fetcher<
   P extends RegisteredPluginId,
   M extends string,
diff --git a/packages/vitnode/src/tanstack/i18n/locale.ts b/packages/vitnode/src/tanstack/i18n/locale.ts
index fe3907ab52..1617af7f41 100644
--- a/packages/vitnode/src/tanstack/i18n/locale.ts
+++ b/packages/vitnode/src/tanstack/i18n/locale.ts
@@ -44,6 +44,15 @@ export const readRequestHost: LocaleHostReader = createIsomorphicFn()
   })
   .client(() => browserHostOf(globalThis.location));
 
+/**
+ * The locale a request renders in. On a public path: the locale prefix, else
+ * the host's domain default, else the default locale. Only on paths without a
+ * locale (`/admin`, `/api`) do the locale cookie and `Accept-Language` decide.
+ * Universal: reads the request on the server and `document`/`location` in the
+ * browser.
+ *
+ * @throws When `configureIntl` has not run yet.
+ */
 export const resolveLocale = <TLocale extends string = string>(
   publicPathname: string,
   { readHost = readRequestHost }: LocaleHostOptions = {},
@@ -60,12 +69,17 @@ export const resolveLocale = <TLocale extends string = string>(
   }) as TLocale;
 };
 
+/** The pathname of a public href - prefix included, search and hash dropped. */
 export const publicPathnameOf = ({
   publicHref,
 }: {
   publicHref: string;
 }): string => new URL(publicHref, RELATIVE_BASE).pathname;
 
+/**
+ * An internal href in `locale`'s public form - with its prefix, or as an
+ * absolute URL when the locale lives on another domain.
+ */
 export const localizeHref = (
   href: string,
   locale: string,
diff --git a/packages/vitnode/src/tanstack/i18n/messages.ts b/packages/vitnode/src/tanstack/i18n/messages.ts
index 9d28a1be97..45dc339132 100644
--- a/packages/vitnode/src/tanstack/i18n/messages.ts
+++ b/packages/vitnode/src/tanstack/i18n/messages.ts
@@ -70,6 +70,26 @@ const loaderOptionsFrom = (
       }
     : options;
 
+/**
+ * Builds the server-side loader `configureIntl`'s `fetchMessages` calls: it
+ * merges core's, each plugin's and the app's messages for a locale over the
+ * default locale (so a missing key falls back key by key) and returns only the
+ * requested namespaces. Merged trees are cached per process in production.
+ *
+ * Server-only - import it from `@vitnode/core/tanstack/i18n/server`. Pass the
+ * app's server config, or the sources explicitly.
+ *
+ * @example
+ * ```ts
+ * // src/server/messages.server.ts
+ * import "@tanstack/react-start/server-only";
+ * import { createIntlMessagesLoader } from "@vitnode/core/tanstack/i18n/server";
+ *
+ * import { vitNodeServerConfig } from "@/vitnode.server.config";
+ *
+ * export const loadIntlMessages = createIntlMessagesLoader(vitNodeServerConfig);
+ * ```
+ */
 export function createIntlMessagesLoader(
   options: IntlMessagesLoaderOptions | VitNodeServerConfig,
 ): IntlMessagesLoader {
diff --git a/packages/vitnode/src/tanstack/i18n/route-messages.tsx b/packages/vitnode/src/tanstack/i18n/route-messages.tsx
index fccbf3a3f9..4af8372815 100644
--- a/packages/vitnode/src/tanstack/i18n/route-messages.tsx
+++ b/packages/vitnode/src/tanstack/i18n/route-messages.tsx
@@ -8,11 +8,31 @@ import { useLocale } from "./locale";
 import { GLOBAL_NAMESPACE, intlQueryOptions } from "./query";
 import { getIntlRuntime } from "./runtime";
 
+/**
+ * Provides translations for a subtree: loads the given message namespaces for
+ * the current locale (suspending until they arrive) and mounts `use-intl`'s
+ * provider with them, so `useTranslations` works below it.
+ *
+ * Plugin pages get their declared `messages` automatically; reach for this in
+ * the app's own routes, layouts and components that render outside one - a
+ * breadcrumb crumb with its own strings, for example. Warm the same namespaces
+ * in the route's loader with `intlQueryOptions` to avoid a waterfall.
+ *
+ * @example
+ * ```tsx
+ * import { RouteMessages } from "@vitnode/core/tanstack/i18n";
+ *
+ * <RouteMessages namespaces={["core.global", "@vitnode/blog.post"]}>
+ *   <PostTitle />
+ * </RouteMessages>;
+ * ```
+ */
 export const RouteMessages = ({
   children,
   namespaces = [GLOBAL_NAMESPACE],
 }: {
   children: React.ReactNode;
+  /** Message namespaces to load, e.g. `@vitnode/blog.post`. Defaults to `core.global`. */
   namespaces?: readonly string[];
 }) => {
   const locale = useLocale();
diff --git a/packages/vitnode/src/tanstack/i18n/runtime.ts b/packages/vitnode/src/tanstack/i18n/runtime.ts
index 4b349b571d..293dc48e58 100644
--- a/packages/vitnode/src/tanstack/i18n/runtime.ts
+++ b/packages/vitnode/src/tanstack/i18n/runtime.ts
@@ -12,6 +12,11 @@ export interface IntlMessages {
   messages: AbstractIntlMessages;
 }
 
+/**
+ * Loads one locale's messages for a set of namespaces. Usually a server
+ * function wrapping `createIntlMessagesLoader`, so locale files stay on the
+ * server.
+ */
 export type IntlMessagesFetcher = (input: {
   locale: string;
   namespaces: readonly string[];
@@ -25,9 +30,14 @@ export type HostIntlProvider = React.ComponentType<{
 }>;
 
 export interface ConfigureIntlOptions {
+  /**
+   * The TanStack Query fetcher for messages, run on the server and in the
+   * browser when a locale and namespace set is not cached yet.
+   */
   fetchMessages: IntlMessagesFetcher;
   /** The host's own `IntlProvider`. See {@link HostIntlProvider}. */
   hostIntlProvider?: HostIntlProvider;
+  /** The app's `vitNodeConfig.i18n`: locales, prefixes, domains, time zone. */
   i18n: VitNodeI18nConfig;
 }
 
@@ -46,6 +56,27 @@ export interface IntlRuntime {
 
 let runtime: IntlRuntime | undefined;
 
+/**
+ * Registers the app's locale rules and message loader for every VitNode
+ * route, link and `RouteMessages` in this process. Call it once, at module
+ * scope, in a module the router entry imports - before the router is created.
+ *
+ * @example
+ * ```ts
+ * // src/lib/i18n.ts
+ * import { createServerFn } from "@tanstack/react-start";
+ * import { configureIntl, validateIntlInput } from "@vitnode/core/tanstack/i18n";
+ *
+ * const getIntlMessages = createServerFn()
+ *   .validator(validateIntlInput)
+ *   .handler(async ({ data }) => await loadIntlMessages(data));
+ *
+ * export const { localeRouting } = configureIntl({
+ *   fetchMessages: async input => await getIntlMessages({ data: input }),
+ *   i18n: vitNodeConfig.i18n,
+ * });
+ * ```
+ */
 export const configureIntl = ({
   fetchMessages,
   hostIntlProvider,
@@ -65,6 +96,12 @@ export const configureIntl = ({
   return runtime;
 };
 
+/**
+ * The runtime {@link configureIntl} registered: default locale, locale routing,
+ * time zone and the message fetcher. Universal.
+ *
+ * @throws When `configureIntl` has not run yet.
+ */
 export const getIntlRuntime = (): IntlRuntime => {
   if (!runtime) {
     throw new Error(
diff --git a/packages/vitnode/src/tanstack/icons/ssr.ts b/packages/vitnode/src/tanstack/icons/ssr.ts
index 1fcd95d9a9..919837203b 100644
--- a/packages/vitnode/src/tanstack/icons/ssr.ts
+++ b/packages/vitnode/src/tanstack/icons/ssr.ts
@@ -41,6 +41,14 @@ const iconsRenderedBy = async (
     router.serverSsr.onCleanup(settle);
   });
 
+/**
+ * Makes icons rendered by name (dynamic Lucide icons, e.g. a plugin's or a
+ * search result's) appear in the server HTML and hydrate without a flash: the
+ * server records which icons a render used and sends them with the dehydrated
+ * router state, and the client seeds its registry from it. Call it once in
+ * `getRouter()`, after creating the router; it wraps the router's existing
+ * `dehydrate`/`hydrate`.
+ */
 export const setupLucideIconSsr = ({ router }: { router: AnyRouter }): void => {
   const collector = createLucideIconCollector();
 
diff --git a/packages/vitnode/src/tanstack/layout/document-head.tsx b/packages/vitnode/src/tanstack/layout/document-head.tsx
index 56f2716311..c75d1a2fe5 100644
--- a/packages/vitnode/src/tanstack/layout/document-head.tsx
+++ b/packages/vitnode/src/tanstack/layout/document-head.tsx
@@ -47,6 +47,11 @@ const HeadContentWithoutPreloads = () => {
   );
 };
 
+/**
+ * The root document's `<head>` tags, in place of TanStack Router's
+ * `<HeadContent />`. In production it leaves out module preloads, which
+ * `DocumentScripts` adds after first paint.
+ */
 export const DocumentHead = () =>
   process.env.NODE_ENV === "production" ? (
     <HeadContentWithoutPreloads />
diff --git a/packages/vitnode/src/tanstack/layout/document-scripts.tsx b/packages/vitnode/src/tanstack/layout/document-scripts.tsx
index ae75a086ce..dd6877037a 100644
--- a/packages/vitnode/src/tanstack/layout/document-scripts.tsx
+++ b/packages/vitnode/src/tanstack/layout/document-scripts.tsx
@@ -138,5 +138,10 @@ const DeferredScripts = () => {
   );
 };
 
+/**
+ * The root document's scripts, in place of TanStack Router's `<Scripts />`. In
+ * production the app's module scripts and preloads load after the first
+ * contentful paint (or within three seconds), so they never delay it.
+ */
 export const DocumentScripts = () =>
   process.env.NODE_ENV === "production" ? <DeferredScripts /> : <Scripts />;
diff --git a/packages/vitnode/src/tanstack/layout/error-actions.tsx b/packages/vitnode/src/tanstack/layout/error-actions.tsx
index fba587f48f..5414045e56 100644
--- a/packages/vitnode/src/tanstack/layout/error-actions.tsx
+++ b/packages/vitnode/src/tanstack/layout/error-actions.tsx
@@ -5,6 +5,7 @@ import { useTranslations } from "use-intl";
 
 import { Button, buttonVariants } from "@/components/ui/button";
 
+/** "Go back" and "Back to home" buttons for the `actions` slot of the error pages. */
 export const ErrorActions = () => {
   const router = useRouter();
   const t = useTranslations("core.global");
diff --git a/packages/vitnode/src/tanstack/layout/header.tsx b/packages/vitnode/src/tanstack/layout/header.tsx
index 5619872ab0..4f4da5279d 100644
--- a/packages/vitnode/src/tanstack/layout/header.tsx
+++ b/packages/vitnode/src/tanstack/layout/header.tsx
@@ -62,14 +62,22 @@ const headerNavTranslator = (
   };
 };
 
+/**
+ * The site header: logo, the configured `navigation.header` links (labels
+ * translated from their message keys), search, notifications and the mobile
+ * bottom bar. Most apps render `MainHeader`, which adds the user menu.
+ */
 export const Header = ({
   firstSearchSourceId,
   leading,
   user,
   variant,
 }: {
+  /** The search source whose results the dialog lists first. */
   firstSearchSourceId?: string;
+  /** Rendered before the logo, e.g. a sidebar toggle. */
   leading?: React.ReactNode;
+  /** The signed-in user's menu slot. */
   user?: React.ReactNode;
   variant?: HeaderVariant;
 }) => {
@@ -135,6 +143,22 @@ const loadNavigationMessages = async ({
   });
 };
 
+/**
+ * The main layout route's loader: warms the header's navigation messages, the
+ * deployment configuration and the session so the shell renders without
+ * waterfalls. During a shared (prerendered or page-cached) render it loads only
+ * the navigation messages: it skips the session and puts a deferred placeholder
+ * in place of the deployment configuration.
+ *
+ * @example
+ * ```ts
+ * // src/routes/_main.tsx
+ * export const Route = createFileRoute("/_main")({
+ *   loader: async ({ context }) => await loadMainShell(context),
+ *   component: MainLayout,
+ * });
+ * ```
+ */
 export const loadMainShell = async (
   context: { locale: string; queryClient: QueryClient },
   {
diff --git a/packages/vitnode/src/tanstack/layout/main-header.tsx b/packages/vitnode/src/tanstack/layout/main-header.tsx
index 8b16f77013..f9bed610ef 100644
--- a/packages/vitnode/src/tanstack/layout/main-header.tsx
+++ b/packages/vitnode/src/tanstack/layout/main-header.tsx
@@ -1,6 +1,7 @@
 import { Header } from "./header";
 import { UserHeader } from "./user-header";
 
+/** The site `Header` with the signed-in user's menu - what the main layout renders. */
 export const MainHeader = (
   props: Omit<React.ComponentProps<typeof Header>, "user">,
 ) => <Header {...props} user={<UserHeader />} />;
diff --git a/packages/vitnode/src/tanstack/layout/not-found.tsx b/packages/vitnode/src/tanstack/layout/not-found.tsx
index e874170f59..b8ce81f055 100644
--- a/packages/vitnode/src/tanstack/layout/not-found.tsx
+++ b/packages/vitnode/src/tanstack/layout/not-found.tsx
@@ -2,6 +2,7 @@ import { useTranslations } from "use-intl";
 
 import { ErrorContent } from "@/views/error/error-content";
 
+/** The translated 404 page, e.g. the router's `defaultNotFoundComponent`. Needs `core.global` messages. */
 export const NotFound = ({ actions }: { actions?: React.ReactNode }) => {
   const t = useTranslations("core.global");
 
@@ -15,6 +16,7 @@ export const NotFound = ({ actions }: { actions?: React.ReactNode }) => {
   );
 };
 
+/** The translated 500 page. Needs `core.global` messages. */
 export const Error500Page = ({ actions }: { actions?: React.ReactNode }) => {
   const t = useTranslations("core.global");
 
diff --git a/packages/vitnode/src/tanstack/layout/root-providers.tsx b/packages/vitnode/src/tanstack/layout/root-providers.tsx
index 75c97abb3c..240e9e51f7 100644
--- a/packages/vitnode/src/tanstack/layout/root-providers.tsx
+++ b/packages/vitnode/src/tanstack/layout/root-providers.tsx
@@ -11,6 +11,12 @@ import { RouteMessages } from "../i18n/route-messages";
 import { lucideIconCollectorOf } from "../icons/ssr";
 import { RealtimeListeners } from "../realtime/realtime-listeners";
 
+/**
+ * Everything VitNode's UI needs above the app: `core.global` messages, theme,
+ * toaster, tooltips, languages, editor config and logo from `config`, the
+ * WebSocket connection with its realtime listeners, and SSR icon collection. Render it once in the root route's
+ * component, around the `<Outlet />`.
+ */
 export const VitNodeRootProviders = ({
   children,
   config,
diff --git a/packages/vitnode/src/tanstack/layout/route-error.tsx b/packages/vitnode/src/tanstack/layout/route-error.tsx
index 566224a91c..973700fa48 100644
--- a/packages/vitnode/src/tanstack/layout/route-error.tsx
+++ b/packages/vitnode/src/tanstack/layout/route-error.tsx
@@ -21,6 +21,10 @@ const DevErrorDetails = ({ error }: { error: unknown }) => (
   </>
 );
 
+/**
+ * The router's `defaultErrorComponent`: the 500 page, plus - in development
+ * only - an overlay with the error's details.
+ */
 export const RouteErrorPage = ({
   actions,
   error,
diff --git a/packages/vitnode/src/tanstack/link/href-link.tsx b/packages/vitnode/src/tanstack/link/href-link.tsx
index 74d209d345..82e39cb3a6 100644
--- a/packages/vitnode/src/tanstack/link/href-link.tsx
+++ b/packages/vitnode/src/tanstack/link/href-link.tsx
@@ -22,9 +22,20 @@ const hrefDestination = (href: string, parseSearch: SearchParser) => {
 };
 
 export interface HrefLinkProps extends Omit<React.ComponentProps<"a">, "href"> {
+  /**
+   * When the link counts as active (`data-status="active"`). Defaults to an
+   * exact match of path, search and hash. Ignored for external links.
+   */
   activeOptions?: ActiveOptions;
+  /**
+   * A full URL string - path, search and hash - such as a stored or
+   * API-provided link. An absolute URL (`https:`, `mailto:`, `//...`) renders
+   * a plain `<a>`.
+   */
   href: string;
+  /** TanStack Router preloading for internal links. */
   preload?: LinkProps["preload"];
+  /** Milliseconds before an intent preload starts, for internal links. */
   preloadDelay?: number;
 }
 
@@ -46,6 +57,22 @@ const InternalHrefLink = ({
   );
 };
 
+/**
+ * A link for an `href` string you did not build from a route - navigation
+ * entries, content URLs, links returned by the API. Internal hrefs become a
+ * TanStack Router `<Link>` (client-side navigation, preloading, active state)
+ * with the search string parsed by the router; external ones render a plain
+ * `<a>`.
+ *
+ * Prefer TanStack Router's own `<Link to>` when the target is a typed route.
+ *
+ * @example
+ * ```tsx
+ * import { HrefLink } from "@vitnode/core/tanstack/link";
+ *
+ * <HrefLink href={`/blog/${post.slug}#comments`}>{post.title}</HrefLink>;
+ * ```
+ */
 export const HrefLink = ({
   activeOptions,
   preload,
@@ -63,6 +90,12 @@ export const HrefLink = ({
     />
   );
 
+/**
+ * Imperative counterpart of {@link HrefLink}: returns `navigate(href, { replace })`,
+ * which routes an internal href through the router and sends an external one
+ * through `window.location`. Browser-only - call the returned function from
+ * event handlers or effects.
+ */
 export const useHrefNavigate = () => {
   const router = useRouter();
 
diff --git a/packages/vitnode/src/tanstack/metadata/alternates.ts b/packages/vitnode/src/tanstack/metadata/alternates.ts
index 856b02c729..a37f976fba 100644
--- a/packages/vitnode/src/tanstack/metadata/alternates.ts
+++ b/packages/vitnode/src/tanstack/metadata/alternates.ts
@@ -6,20 +6,29 @@ import { getIntlRuntime } from "../i18n/runtime";
 
 export const X_DEFAULT_HREFLANG = "x-default";
 
+/** A `<link>` a route's `head` emits. */
 export interface RouteHeadLink {
   href: string;
   hrefLang?: string;
   rel: "alternate" | "canonical";
 }
 
+/** A page's internal (unprefixed) path per locale code, e.g. `{ en: "/blog/hello" }`. */
 export type LocaleAlternates = Readonly<Record<string, string>>;
 
 interface LocaleAlternateLinksBase {
+  /** The locale being rendered; picks the canonical link. */
   locale: string;
+  /** Defaults to the app's configured locale routing. */
   localeRouting?: LocaleRouting;
+  /** Defaults to the configured web origin; a locale bound to its own domain uses that domain. */
   webOrigin?: string | URL;
 }
 
+/**
+ * Either explicit per-locale paths (`alternates`), or one `internalPathname`
+ * that exists in every locale (`locales`, defaulting to all configured ones).
+ */
 export type LocaleAlternateLinksOptions = LocaleAlternateLinksBase &
   (
     | { alternates: LocaleAlternates }
@@ -62,6 +71,16 @@ const absoluteHref = (
   }
 };
 
+/**
+ * The canonical link and `hreflang` alternates of a page that exists in several
+ * locales, as absolute URLs with each locale's prefix or domain applied: a
+ * `canonical` for `locale` (the default locale's URL when `locale` has none),
+ * one `alternate` per locale, and `x-default` pointing at the default locale
+ * when it is one of them.
+ *
+ * Unsupported locales and paths that are not internal (`/...`) are skipped;
+ * returns `[]` when nothing is left. Universal.
+ */
 export const localeAlternateLinks = (
   options: LocaleAlternateLinksOptions,
 ): RouteHeadLink[] => {
diff --git a/packages/vitnode/src/tanstack/metadata/index.ts b/packages/vitnode/src/tanstack/metadata/index.ts
index b3871aae09..d542b7e04a 100644
--- a/packages/vitnode/src/tanstack/metadata/index.ts
+++ b/packages/vitnode/src/tanstack/metadata/index.ts
@@ -28,22 +28,30 @@ export interface RouteOpenGraph {
   /** The `<meta property="og:description">`. */
   description?: string;
 
+  /** The `<meta property="og:title">`, used as is - no site-name suffix. */
   title?: string;
   /** `article` for a document, `website` for a landing page. */
   type?: RouteOpenGraphType;
 }
 
+/** What a page puts in its `<head>`. Every field is optional and emits nothing when unset. */
 export interface RouteHeadOptions {
+  /**
+   * The page's internal path per locale. With `locale`, emits the canonical
+   * link and `hreflang` alternates (see `localeAlternateLinks`).
+   */
   alternates?: LocaleAlternates;
   /** The `<meta name="description">`, when the page has one. */
   description?: string;
 
+  /** The locale being rendered; required for `alternates` to emit anything. */
   locale?: string;
 
   openGraph?: RouteOpenGraph;
 
+  /** The `<meta name="robots">`. A deeper route's value replaces its parent's. */
   robots?: RouteRobots;
-  /** The page's own title, already translated. */
+  /** The page's own title, already translated. The site name is appended (`Title - Site`). */
   title?: string;
 }
 
@@ -52,6 +60,7 @@ export type RouteHeadMeta =
   | { content: string; property: string }
   | { title: string };
 
+/** A TanStack Router `head` return value. */
 export interface RouteHeadResult {
   links?: RouteHeadLink[];
   meta: RouteHeadMeta[];
@@ -93,6 +102,7 @@ const routeMeta = (
     : []),
 ];
 
+/** {@link pageHead} with explicit site metadata, for code that runs before the config is registered. */
 export const routeHead = (
   metadata: VitNodeMetadata,
   {
@@ -112,10 +122,31 @@ export const routeHead = (
   };
 };
 
+/** Binds {@link routeHead} to one site's metadata. */
 export const createRouteHead =
   (metadata: VitNodeMetadata) =>
   (options: RouteHeadOptions = {}) =>
     routeHead(metadata, options);
 
+/**
+ * A route's `head` from translated page data: title (suffixed with the site
+ * name from `buildConfig({ metadata })`), description, robots, Open Graph and
+ * locale alternates. Universal; use it in a route's `head`, written after
+ * `loader` so `loaderData` is typed.
+ *
+ * @throws When the VitNode config has not been registered with `buildConfig`.
+ *
+ * @example
+ * ```ts
+ * import { pageHead } from "@vitnode/core/tanstack/metadata";
+ *
+ * head: ({ loaderData }) =>
+ *   pageHead({
+ *     title: loaderData?.title,
+ *     description: loaderData?.description,
+ *     robots: loaderData ? "index, follow" : "noindex, nofollow",
+ *   }),
+ * ```
+ */
 export const pageHead = (options: RouteHeadOptions = {}): RouteHeadResult =>
   routeHead(getVitNodeConfig().metadata, options);
diff --git a/packages/vitnode/src/tanstack/moderation/report-button.tsx b/packages/vitnode/src/tanstack/moderation/report-button.tsx
index 19b0eedaf4..6381eda742 100644
--- a/packages/vitnode/src/tanstack/moderation/report-button.tsx
+++ b/packages/vitnode/src/tanstack/moderation/report-button.tsx
@@ -25,11 +25,17 @@ export const REPORT_NAMESPACES = ["core.global", "core.moderation"] as const;
 
 export interface ReportButtonProps {
   className?: string;
+  /** The locale the reported content was shown in, for moderators. */
   locale?: null | string;
+  /** The plugin that registered the report target. */
   pluginId: string;
+  /** The locale the visitor asked for, when the content fell back to another. */
   requestedLocale?: null | string;
+  /** The reported item's id. */
   targetId: number | string;
+  /** The report target type - for a content type with reports enabled, its id. */
   targetType: string;
+  /** What the item is called, already translated, for the dialog title ("Report {type}"). */
   typeLabel: string;
 }
 
@@ -112,6 +118,26 @@ const ReportButtonInner = ({
   );
 };
 
+/**
+ * A flag button that opens the "report this" dialog for one item. Guests are
+ * offered a sign-in link instead of the form. Loads its own messages and the
+ * dialog lazily, so it can go anywhere on a public page.
+ *
+ * The target must be registered on the API - a content type with `reports`
+ * enabled, or a plugin's `moderation.reportTargets` - or the report is refused.
+ *
+ * @example
+ * ```tsx
+ * import { ReportButton } from "@vitnode/core/tanstack/moderation";
+ *
+ * <ReportButton
+ *   pluginId={manifest.id}
+ *   targetId={metadata.itemId}
+ *   targetType={blogPostContentType.id}
+ *   typeLabel={t("report_type")}
+ * />;
+ * ```
+ */
 export const ReportButton = (props: ReportButtonProps) => (
   <React.Suspense
     fallback={
diff --git a/packages/vitnode/src/tanstack/notifications/actions.ts b/packages/vitnode/src/tanstack/notifications/actions.ts
index 404f634887..f67a2d698d 100644
--- a/packages/vitnode/src/tanstack/notifications/actions.ts
+++ b/packages/vitnode/src/tanstack/notifications/actions.ts
@@ -22,6 +22,13 @@ import {
   patchCachedNotification,
 } from "./cache";
 
+/**
+ * Notification actions for a signed-in user - `archive`, `markAllRead`,
+ * `toggleRead` and `open` (marks it read if unread and, unless opened in a new
+ * tab, goes to its target). Each updates the
+ * cached lists optimistically; on failure it shows an error toast and
+ * refetches the real state.
+ */
 export const useNotificationActions = (userId: number) => {
   const queryClient = useQueryClient();
   const router = useRouter();
diff --git a/packages/vitnode/src/tanstack/notifications/bell.tsx b/packages/vitnode/src/tanstack/notifications/bell.tsx
index 027637be9a..9a5007487e 100644
--- a/packages/vitnode/src/tanstack/notifications/bell.tsx
+++ b/packages/vitnode/src/tanstack/notifications/bell.tsx
@@ -45,6 +45,7 @@ const SignedInBell = ({
   );
 };
 
+/** The header's notifications bell and popover. Renders nothing for guests. */
 export const NotificationsBell = () => {
   const { data: session } = useSessionQuery();
   const user = session?.user;
diff --git a/packages/vitnode/src/tanstack/page-cache/server.ts b/packages/vitnode/src/tanstack/page-cache/server.ts
index abf5afeda6..9ee59a5d7f 100644
--- a/packages/vitnode/src/tanstack/page-cache/server.ts
+++ b/packages/vitnode/src/tanstack/page-cache/server.ts
@@ -101,10 +101,11 @@ export type PageCacheRender = (
 export interface PageCacheHandlerOptions<
   AppLocales extends LocaleConfig[] = LocaleConfig[],
 > {
-  /** `pageCacheBuildId` from `src/page-cache.gen.ts`. */
+  /** `pageCacheBuildId` from `src/page-cache.gen.ts`; a new build never serves an old build's pages. */
   buildId: string;
+  /** The app's `vitNodeConfig`; `pageCache` and `i18n` are read from it. */
   config: VitNodeConfig<AppLocales>;
-  /** Overrides the production-only default. For tests. */
+  /** Overrides the default (on outside development). For tests. */
   enabled?: boolean;
   /** `pageCacheRoutes` from `src/page-cache.gen.ts`. */
   routes: PageCacheRouteTable;
@@ -462,10 +463,17 @@ export const createPageCacheHandler = <AppLocales extends LocaleConfig[]>(
 
 /** A TanStack Start server entry, as `@tanstack/react-start/server-entry` exports it. */
 export interface StartServerEntry {
+  /** Answers one request; `withPageCache` wraps it. */
   fetch: (request: Request, ...rest: never[]) => Promise<Response> | Response;
 }
 
 /**
+ * Wraps the TanStack Start server entry with VitNode's shared HTML page cache
+ * (see `createPageCacheHandler` for which requests are cached and when a
+ * render is stored). Only routes with a policy in `routes` - e.g. a plugin
+ * `page()`'s `cache` option - are cached, only outside development, and not when
+ * `pageCache.enabled` is `false`. Server-only.
+ *
  * The host app's `src/server.ts`:
  *
  * ```ts
diff --git a/packages/vitnode/src/tanstack/pending/route-pending-skeleton.tsx b/packages/vitnode/src/tanstack/pending/route-pending-skeleton.tsx
index 255157a242..dca0523ed4 100644
--- a/packages/vitnode/src/tanstack/pending/route-pending-skeleton.tsx
+++ b/packages/vitnode/src/tanstack/pending/route-pending-skeleton.tsx
@@ -3,10 +3,14 @@ import { cn } from "cn";
 import { Skeleton } from "@/components/ui/skeleton";
 import { Spinner } from "@/components/ui/spinner";
 
+/** Props shared by the route pending skeletons. */
 export interface RoutePendingSkeletonProps {
   className?: string;
+  /** Screen-reader status text. Defaults to `Loading`; pass a translated string when you have one. */
   label?: string;
+  /** How many placeholder rows, cards or fields to draw. Each skeleton has its own default. */
   rows?: number;
+  /** Draws a description line under the heading placeholder. Defaults to `true`. */
   withDescription?: boolean;
 }
 
@@ -46,6 +50,13 @@ export const PendingHeading = ({
 export const pendingRowKeys = (rows: number): number[] =>
   Array.from({ length: Math.max(rows, 0) }, (_, index) => index);
 
+/**
+ * A generic page placeholder - heading plus text blocks - announced to screen
+ * readers as busy. Use it as a route's `pendingComponent` (a plugin page's
+ * `pendingComponent`, or the router's default); pick the closer shape when one
+ * exists: `FeedPendingSkeleton`, `CardsPendingSkeleton`, `FormPendingSkeleton`,
+ * `TablePendingSkeleton`.
+ */
 export const RoutePendingSkeleton = ({
   className,
   label,
@@ -68,6 +79,7 @@ export const RoutePendingSkeleton = ({
   </PendingFrame>
 );
 
+/** A centered spinner, for pending states with no predictable layout - e.g. the router's `defaultPendingComponent`. */
 export const RoutePendingSpinner = ({
   className,
   label = "Loading",
diff --git a/packages/vitnode/src/tanstack/pending/shapes.tsx b/packages/vitnode/src/tanstack/pending/shapes.tsx
index 633998a45d..3ab15f1945 100644
--- a/packages/vitnode/src/tanstack/pending/shapes.tsx
+++ b/packages/vitnode/src/tanstack/pending/shapes.tsx
@@ -11,6 +11,7 @@ import {
   pendingRowKeys,
 } from "./route-pending-skeleton";
 
+/** Placeholder for a narrow list of posts or topics. Draws 3 rows by default. */
 export const FeedPendingSkeleton = ({
   className,
   label,
@@ -106,6 +107,7 @@ export const SearchPendingSkeleton = ({
   </PendingFrame>
 );
 
+/** Placeholder for a data table. Draws 6 rows by default. */
 export const TablePendingSkeleton = ({
   className,
   label,
@@ -152,6 +154,7 @@ export const TablePendingSkeleton = ({
   </PendingFrame>
 );
 
+/** Placeholder for a form in a card. Draws 4 fields by default. */
 export const FormPendingSkeleton = ({
   className,
   label,
@@ -180,6 +183,7 @@ export const FormPendingSkeleton = ({
   </PendingFrame>
 );
 
+/** Placeholder for a responsive card grid. Draws 6 cards by default. */
 export const CardsPendingSkeleton = ({
   className,
   label,
diff --git a/packages/vitnode/src/tanstack/plugin-routes/authoring.ts b/packages/vitnode/src/tanstack/plugin-routes/authoring.ts
index c6008a9411..0350a246d0 100644
--- a/packages/vitnode/src/tanstack/plugin-routes/authoring.ts
+++ b/packages/vitnode/src/tanstack/plugin-routes/authoring.ts
@@ -50,6 +50,14 @@ export interface AdminRouteLoadContext extends RouteLoadContext {
 }
 
 /**
+ * Declares a plugin page's data and head: `load` runs as the route's loader
+ * (SSR and client navigation) and `head` builds its metadata. A page module
+ * exports it as `route`, next to its default-exported component, which
+ * receives the loaded data as `loaderData`.
+ *
+ * Use {@link defineAuthenticatedRoute} for a page declared with `requires`, and
+ * {@link defineAdminRoute} for one in the `admin` area.
+ *
  * `definePluginRoute`, with the context a mounted route actually gets.
  *
  * Three doors rather than one, because the difference between them is a promise
@@ -58,6 +66,26 @@ export interface AdminRouteLoadContext extends RouteLoadContext {
  * is in the `admin` area and renders inside the AdminCP shell. A route that made
  * neither declaration is handed neither, and asking for one is a type error
  * rather than an `undefined` at runtime.
+ *
+ * @example
+ * ```tsx
+ * import type { PluginRoutePageProps } from "@vitnode/core/routing";
+ *
+ * import { defineRoute } from "@vitnode/core/tanstack/plugin-routes";
+ *
+ * const loadPost = async (slug: string) => ({ title: slug });
+ *
+ * export const route = defineRoute({
+ *   load: async ({ params }) => await loadPost(params.slug),
+ *   head: ({ loaderData }) => ({ title: loaderData?.title }),
+ * });
+ *
+ * const PostPage = ({ loaderData }: PluginRoutePageProps<Awaited<ReturnType<typeof loadPost>>>) => (
+ *   <h1>{loaderData.title}</h1>
+ * );
+ *
+ * export default PostPage;
+ * ```
  */
 export const defineRoute = <TData = never, TSearch = Record<string, never>>(
   options: AuthoredPluginRouteOptions<TData, TSearch, RouteLoadContext>,
diff --git a/packages/vitnode/src/tanstack/plugin-routes/mount.tsx b/packages/vitnode/src/tanstack/plugin-routes/mount.tsx
index cbf823ff86..a6248b26ee 100644
--- a/packages/vitnode/src/tanstack/plugin-routes/mount.tsx
+++ b/packages/vitnode/src/tanstack/plugin-routes/mount.tsx
@@ -50,9 +50,15 @@ export type PluginRoutePageHead = (
   options: RouteHeadOptions,
 ) => RouteHeadResult;
 
+/** The route each area's pages hang from - usually the app's layout (shell) routes. */
 export type PluginRouteAreaRoutes = Partial<Record<PluginRouteArea, AnyRoute>>;
 
 export interface PluginRoutesMountOptions {
+  /**
+   * Where each area's routes are mounted, e.g. `main` under the main layout and
+   * `admin` under the AdminCP shell. When omitted, `main` and `blank` routes
+   * hang from the tree's root; when given, a route in an area left out throws.
+   */
   mountUnder?: PluginRouteAreaRoutes;
   /**
    * Optional, and only for an application that formats its titles differently:
@@ -334,6 +340,24 @@ const mountPluginSubtree = (
  * through the same registry a plugin does, so an application no longer composes
  * `withCoreRootRoutes(withCoreAdminRoutes(withCoreMainRoutes(…)))` around it
  * and can no longer get that nesting wrong.
+ *
+ * @throws When a route's area has no mount point, or a plugin route claims a
+ * URL the app's own file routes already answer.
+ *
+ * @example
+ * ```ts
+ * // src/router.tsx
+ * import { pluginRouteSpecs, withVitNodeRoutes } from "@vitnode/core/tanstack/plugin-routes";
+ *
+ * import { pluginRouteSources } from "./plugin-routes.gen";
+ * import { Route as adminShellRoute } from "./routes/_admin";
+ * import { Route as mainShellRoute } from "./routes/_main";
+ * import { routeTree as fileRouteTree } from "./routeTree.gen";
+ *
+ * const routeTree = withVitNodeRoutes(fileRouteTree, pluginRouteSpecs(pluginRouteSources), {
+ *   mountUnder: { admin: adminShellRoute, blank: fileRouteTree, main: mainShellRoute },
+ * });
+ * ```
  */
 export const withVitNodeRoutes = <TRouteTree extends AnyRoute>(
   routeTree: TRouteTree,
diff --git a/packages/vitnode/src/tanstack/plugin-routes/specs.ts b/packages/vitnode/src/tanstack/plugin-routes/specs.ts
index ff519a4c42..ed5fb1e725 100644
--- a/packages/vitnode/src/tanstack/plugin-routes/specs.ts
+++ b/packages/vitnode/src/tanstack/plugin-routes/specs.ts
@@ -66,6 +66,14 @@ export const pluginRouteSearchDeps = (
   );
 };
 
+/**
+ * Compiles the route declarations of core and every configured plugin - the
+ * app's generated `src/plugin-routes.gen.ts` - into the specs
+ * `withVitNodeRoutes` mounts: one per route, parents first, each with its lazy
+ * module, message namespaces, search validator and pending component.
+ *
+ * @throws When the declarations are invalid (see `PluginRouteError`).
+ */
 export const pluginRouteSpecs = (
   sources: readonly PluginRouteDeclarationSource[],
 ): PluginRouteSpec[] => {
diff --git a/packages/vitnode/src/tanstack/realtime/realtime-listeners.tsx b/packages/vitnode/src/tanstack/realtime/realtime-listeners.tsx
index 51f66045a8..d717c1b679 100644
--- a/packages/vitnode/src/tanstack/realtime/realtime-listeners.tsx
+++ b/packages/vitnode/src/tanstack/realtime/realtime-listeners.tsx
@@ -5,6 +5,11 @@ import { useSessionQuery } from "../auth/session-query";
 import { NotificationStateSync } from "../notifications/state-sync";
 import { socketUserIdFromSession } from "./session";
 
+/**
+ * Keeps the WebSocket connection's identity in step with the session and
+ * listens for notification events. Rendered by `VitNodeRootProviders`; mount
+ * it yourself only when not using those providers.
+ */
 export const RealtimeListeners = () => {
   const { data: session } = useSessionQuery();
 
diff --git a/packages/vitnode/src/tanstack/search/sources.ts b/packages/vitnode/src/tanstack/search/sources.ts
index dbe52fabdb..acd9682201 100644
--- a/packages/vitnode/src/tanstack/search/sources.ts
+++ b/packages/vitnode/src/tanstack/search/sources.ts
@@ -2,27 +2,50 @@ import type { LucideIcon } from "lucide-react";
 
 import { queryOptions } from "@tanstack/react-query";
 
+/** One result a {@link SearchSource} returns. */
 export interface SearchSourceItem {
+  /** A CSS color for the icon tile, e.g. `var(--docs-color)`. */
   color?: string;
+  /** Where the result lives (a section or breadcrumb trail), shown under the title. */
   context?: null | string;
+  /** Plain text; the part around the search term is shown and highlighted. */
   excerpt?: null | string;
+  /** A Lucide icon name; the source's icon when unset. */
   icon?: string;
+  /** Unique within the source. */
   id: string;
   title: string;
+  /** An internal path such as `/docs/start`; results with any other URL are dropped. */
   url: string;
 }
 
 export interface SearchSourceQuery {
   locale: string;
+  /** Aborted when the term changes; pass it to `fetch`. */
   signal: AbortSignal;
+  /** The trimmed search term. */
   term: string;
 }
 
+/**
+ * An extra result group in the header search dialog, next to the indexed
+ * content - documentation, an external catalog. Registered with
+ * {@link configureSearchSources}.
+ */
 export interface SearchSource {
+  /** The fallback icon for results without their own. */
   icon: LucideIcon;
+  /** Unique across sources; part of the query key. */
   id: string;
+  /** The full message key of the group heading (e.g. `site.search.docs`), which must live in `namespace`. */
   labelKey: string;
+  /** The message namespace the dialog loads for `labelKey`. */
   namespace: string;
+  /**
+   * Returns results for a term. Runs in the browser while the dialog suggests
+   * (fresh for a minute per locale and term, never retried); a rejection
+   * leaves the group empty.
+   */
   search: (query: SearchSourceQuery) => Promise<SearchSourceItem[]>;
 }
 
@@ -30,6 +53,10 @@ const SEARCH_SOURCE_STALE_TIME = 60 * 1000;
 
 let searchSources: readonly SearchSource[] = [];
 
+/**
+ * Registers the app's extra header-search sources, replacing any registered
+ * before. Call it once at module scope in a module the router entry imports.
+ */
 export const configureSearchSources = (sources: readonly SearchSource[]) => {
   searchSources = sources;
 };
diff --git a/packages/vitnode/src/tanstack/search/use-record-view.ts b/packages/vitnode/src/tanstack/search/use-record-view.ts
index 02bfd6aa9a..f4d12359bb 100644
--- a/packages/vitnode/src/tanstack/search/use-record-view.ts
+++ b/packages/vitnode/src/tanstack/search/use-record-view.ts
@@ -2,6 +2,19 @@ import React from "react";
 
 import { recordSearchPopularity } from "@/views/search/search-suggest-query";
 
+/**
+ * Records one view of a content item for search popularity ("popular" results
+ * and suggestion ranking) when the page mounts or the item changes. Pass
+ * `itemId: null` to skip - for a hidden or not-yet-loaded item. Fire and
+ * forget: failures are ignored.
+ *
+ * @example
+ * ```tsx
+ * import { useRecordView } from "@vitnode/core/tanstack/search";
+ *
+ * useRecordView({ itemId: metadata.hidden ? null : metadata.itemId, itemType: blogPostContentType.id });
+ * ```
+ */
 export const useRecordView = ({
   itemId,
   itemType,
diff --git a/packages/vitnode/src/tanstack/start/create-start.ts b/packages/vitnode/src/tanstack/start/create-start.ts
index d73ca6c704..77e8f91e22 100644
--- a/packages/vitnode/src/tanstack/start/create-start.ts
+++ b/packages/vitnode/src/tanstack/start/create-start.ts
@@ -15,12 +15,36 @@ import { createLocaleRequestMiddleware } from "./locale-middleware";
 export interface VitNodeStartOptions<
   AppLocales extends LocaleConfig[] = LocaleConfig[],
 > {
+  /** The app's `vitNodeConfig`; its `i18n` drives locale redirects. */
   config: VitNodeConfig<AppLocales>;
 
+  /** The app's own request middleware, run after VitNode's. */
   requestMiddleware?: readonly AnyRequestMiddleware[];
+  /**
+   * Overrides of the security headers set on HTML documents, by header name.
+   * `false` removes a default. Defaults include `x-frame-options: SAMEORIGIN`
+   * and `referrer-policy: strict-origin-when-cross-origin`.
+   */
   securityHeaders?: DocumentSecurityHeaders;
 }
 
+/**
+ * The app's TanStack Start instance with VitNode's request middleware: CSRF
+ * protection for server functions; locale redirects and the locale cookie;
+ * `private, no-store` caching and security headers on HTML documents (the
+ * page cache sets its own cache headers on pages it serves); then
+ * `requestMiddleware`.
+ *
+ * @example
+ * ```ts
+ * // src/start.ts
+ * import { createVitNodeStart } from "@vitnode/core/tanstack/start";
+ *
+ * import { vitNodeConfig } from "@/vitnode.config";
+ *
+ * export const startInstance = createVitNodeStart({ config: vitNodeConfig });
+ * ```
+ */
 export const createVitNodeStart = <AppLocales extends LocaleConfig[]>({
   config,
   requestMiddleware = [],
diff --git a/packages/vitnode/src/tanstack/view-transitions/index.ts b/packages/vitnode/src/tanstack/view-transitions/index.ts
index 378dd1335d..ae00561e4a 100644
--- a/packages/vitnode/src/tanstack/view-transitions/index.ts
+++ b/packages/vitnode/src/tanstack/view-transitions/index.ts
@@ -1,3 +1,7 @@
+/**
+ * The `view-transition-name` of the site logo, so it morphs between pages.
+ * Give your own logo element this name (once per page) to keep the effect.
+ */
 export const LOGO_VIEW_TRANSITION_NAME = "vitnode-logo";
 
 export const HEADER_VIEW_TRANSITION_NAMES = {
@@ -25,5 +29,11 @@ export const pageViewTransitionTypes = ({
   return [PAGE_VIEW_TRANSITION_TYPE];
 };
 
+/**
+ * The router's `defaultViewTransition`: a page transition (type
+ * `vitnode-page`) when the path changes, nothing for search or hash changes or
+ * when the visitor prefers reduced motion. Pass `false` to turn transitions off,
+ * e.g. from `vitNodeConfig.viewTransitions`.
+ */
 export const navigationViewTransition = (enabled = true) =>
   enabled ? { types: pageViewTransitionTypes } : false;
diff --git a/packages/vitnode/src/tanstack/widgets/page-widgets.tsx b/packages/vitnode/src/tanstack/widgets/page-widgets.tsx
index 3e5ee046dc..86c2e28314 100644
--- a/packages/vitnode/src/tanstack/widgets/page-widgets.tsx
+++ b/packages/vitnode/src/tanstack/widgets/page-widgets.tsx
@@ -23,6 +23,30 @@ import { pageWidgetsRegistry } from "./registry";
  * Core owns the two routes a page layout is read and written through, so it
  * owns talking to them: a page wraps its zones in this and declares nothing
  * else - no query, no adapter, no permission check of its own.
+ *
+ * Staff holding the page definition's permission get an edit mode; everyone
+ * else sees the saved widgets. Warm its data with `loadPageWidgets` in the
+ * route's loader. The page must also be registered on the API
+ * (`buildApiPlugin({ editablePages })`).
+ *
+ * @example
+ * ```tsx
+ * import { defineEditablePage } from "@vitnode/core/content/editor";
+ * import { PageWidgets, PageWidgetsZone } from "@vitnode/core/tanstack/widgets";
+ *
+ * // Placeholder names: register the same definition on the API.
+ * export const examplePage = defineEditablePage({
+ *   id: "example:home",
+ *   permission: { module: "widgets", permission: "can_edit" },
+ *   zones: { sidebar: { max: 10 } },
+ * });
+ *
+ * export const ExampleHome = () => (
+ *   <PageWidgets page={examplePage}>
+ *     <PageWidgetsZone id="sidebar" />
+ *   </PageWidgets>
+ * );
+ * ```
  */
 export const PageWidgets = ({
   children,
@@ -88,6 +112,7 @@ export const PageWidgetsZone = ({
   id,
 }: {
   className?: string;
+  /** One of the zone ids the page definition declares. */
   id: string;
 }) => (
   <ContentZone className={className} id={id} registry={pageWidgetsRegistry()} />
diff --git a/packages/vitnode/src/views/admin/layouts/sidebar/nav/nav-model.tsx b/packages/vitnode/src/views/admin/layouts/sidebar/nav/nav-model.tsx
index d96131141a..f06ff46b5a 100644
--- a/packages/vitnode/src/views/admin/layouts/sidebar/nav/nav-model.tsx
+++ b/packages/vitnode/src/views/admin/layouts/sidebar/nav/nav-model.tsx
@@ -12,6 +12,7 @@ import type {
   PermissionsStaffArgs,
   StaffPermissionSet,
 } from "@/api/lib/permission-staff";
+import type { AdminDashboardWidget } from "@/lib/plugin";
 import type { VitNodeConfig } from "@/vitnode.config";
 
 import { hasStaffPermission } from "@/api/lib/staff-permission";
@@ -429,10 +430,18 @@ export const adminNavNamespaces = (
  * than as an error.
  */
 export interface AdminNavBundle {
+  /** Each plugin's dashboard widgets, in the order of `plugins` (sorted by plugin id in the generated `admin-nav.gen.ts`); plugins with none are left out. */
+  dashboardWidgets: AdminNavDashboardWidgets[];
   declarations: AdminNavGroupDeclaration[];
   namespaces: string[];
 }
 
+/** One plugin's dashboard widgets, keyed by the plugin that declared them. */
+export interface AdminNavDashboardWidgets {
+  pluginId: string;
+  widgets: AdminDashboardWidget[];
+}
+
 /**
  * Declarations and their namespaces, from configured plugins.
  *
@@ -446,7 +455,15 @@ export const adminNavBundle = (
 ): AdminNavBundle => {
   const declarations = adminNavDeclarations(vitNodeConfig);
 
-  return { declarations, namespaces: adminNavNamespaces(declarations) };
+  return {
+    dashboardWidgets: vitNodeConfig.plugins.flatMap(plugin => {
+      const widgets = plugin.admin?.dashboard?.widgets ?? [];
+
+      return widgets.length > 0 ? [{ pluginId: plugin.pluginId, widgets }] : [];
+    }),
+    declarations,
+    namespaces: adminNavNamespaces(declarations),
+  };
 };
 
 /**
diff --git a/packages/vitnode/src/views/admin/views/content/form/context.tsx b/packages/vitnode/src/views/admin/views/content/form/context.tsx
index 7d6125fa9f..95c17c29b2 100644
--- a/packages/vitnode/src/views/admin/views/content/form/context.tsx
+++ b/packages/vitnode/src/views/admin/views/content/form/context.tsx
@@ -17,14 +17,30 @@ export interface ContentFormTranslationMeta {
   updatedAt?: null | string;
 }
 
+/**
+ * What a custom content form layout (`contentTypeAdmin({ forms })`) reads
+ * through {@link useContentForm}: the rendered field inputs, the form mode and
+ * the publication/visibility state of the record being edited.
+ */
 export interface ContentFormContextValue {
+  /** The content type's `localization.defaultLocale`, when localized. */
   defaultLocale?: null | string;
+  /** Every field the form renders, in order (`admin.form.fields` or sections). */
   fieldNames: string[];
+  /** The ready-to-render input of each field, by name. Prefer `<ContentFormField>`. */
   fields: Record<string, React.ReactNode>;
   files?: Record<string, ContentFileFieldValue | undefined>;
   header?: ContentFormHeaderValue;
   localizedFieldNames: string[];
+  /**
+   * Records that the layout placed the header. In development the form warns
+   * when a page-mode layout never renders `<ContentFormHeader>`.
+   */
   markHeaderRendered?: () => void;
+  /**
+   * Records that the layout placed a field. In development the form warns
+   * about fields no layout rendered. The provided primitives call it for you.
+   */
   markRendered?: (name: string) => void;
   mode: "create" | "edit";
   onSaved?: (
@@ -37,7 +53,9 @@ export interface ContentFormContextValue {
     status?: unknown;
     transition?: (action: "publish" | "unpublish") => Promise<boolean>;
   };
+  /** The content type's singular noun, already translated. */
   singular: string;
+  /** `true` while the layout renders as a loading placeholder. */
   skeleton?: boolean;
   title?: string;
   translations?: readonly ContentFormTranslationMeta[];
@@ -53,6 +71,12 @@ const ContentFormContext = React.createContext<ContentFormContextValue | null>(
   null,
 );
 
+/**
+ * The surrounding Content Engine form, for custom layouts and field components.
+ *
+ * @throws When called outside a Content Engine form layout. Use
+ * {@link useContentFormOptional} for components that also render elsewhere.
+ */
 export const useContentForm = (): ContentFormContextValue => {
   const value = React.use(ContentFormContext);
 
@@ -65,6 +89,7 @@ export const useContentForm = (): ContentFormContextValue => {
   return value;
 };
 
+/** Like {@link useContentForm}, but `null` outside a Content Engine form. */
 export const useContentFormOptional = (): ContentFormContextValue | null =>
   React.use(ContentFormContext);
 
diff --git a/packages/vitnode/src/views/admin/views/content/form/layout-primitives.tsx b/packages/vitnode/src/views/admin/views/content/form/layout-primitives.tsx
index 16e0db453d..c5f0d16761 100644
--- a/packages/vitnode/src/views/admin/views/content/form/layout-primitives.tsx
+++ b/packages/vitnode/src/views/admin/views/content/form/layout-primitives.tsx
@@ -8,6 +8,11 @@ import { ContentLivePresence } from "../live/presence";
 import { ContentLiveStatus } from "../live/status";
 import { useContentForm } from "./context";
 
+/**
+ * The page-mode heading with its back link and, during live editing, presence
+ * and autosave status. Required in a page-mode layout; renders nothing in a
+ * dialog.
+ */
 export const ContentFormHeader = ({
   children,
   className,
@@ -46,6 +51,7 @@ export const ContentFormHeader = ({
   );
 };
 
+/** A responsive two-column grid: main content, plus a 20rem sidebar from `lg` up. */
 export const ContentFormLayoutGrid = ({
   children,
   className,
@@ -62,6 +68,7 @@ export const ContentFormLayoutGrid = ({
   </div>
 );
 
+/** The main column of {@link ContentFormLayoutGrid}. */
 export const ContentFormMain = ({
   children,
   className,
@@ -72,6 +79,7 @@ export const ContentFormMain = ({
   </div>
 );
 
+/** The sidebar column of {@link ContentFormLayoutGrid}, sticky on large screens. */
 export const ContentFormSidebar = ({
   children,
   className,
@@ -85,6 +93,7 @@ export const ContentFormSidebar = ({
   </div>
 );
 
+/** A titled card grouping fields in a custom layout. */
 export const ContentFormSection = ({
   children,
   className,
diff --git a/packages/vitnode/src/views/admin/views/content/form/primitives.tsx b/packages/vitnode/src/views/admin/views/content/form/primitives.tsx
index 8ee3cddd6f..c586769a1f 100644
--- a/packages/vitnode/src/views/admin/views/content/form/primitives.tsx
+++ b/packages/vitnode/src/views/admin/views/content/form/primitives.tsx
@@ -122,6 +122,7 @@ const ContentFormPublicationToggle = () => {
   );
 };
 
+/** Renders one field's generated (or registered custom) input where a custom layout places it. */
 export const ContentFormField = ({ name }: { name: string }) => {
   const { fields, markRendered } = useContentForm();
 
@@ -130,6 +131,10 @@ export const ContentFormField = ({ name }: { name: string }) => {
   return <>{fields[name] ?? null}</>;
 };
 
+/**
+ * Renders every form field, in order, except those in `exclude` - typically
+ * the ones a custom layout already placed with `<ContentFormField>`.
+ */
 export const ContentFormRemainingFields = ({
   exclude = [],
 }: {
@@ -150,6 +155,7 @@ export const ContentFormRemainingFields = ({
   );
 };
 
+/** The record's publication (and hidden) status. Renders nothing on create or without `publication`. */
 export const ContentFormStatus = () => {
   const { mode, publication, skeleton, visibility } = useContentForm();
 
@@ -169,6 +175,13 @@ export const ContentFormStatus = () => {
   );
 };
 
+/**
+ * The form's submit buttons - "Save draft", plus "Publish" when the user may
+ * publish, when creating a record with publication; one submit button
+ * (`submitLabel`) otherwise - after
+ * any `children` and an optional cancel link. When editing, the visibility and
+ * publication toggles render beside it unless turned off.
+ */
 export const ContentFormActions = ({
   cancelHref,
   children,
diff --git a/packages/vitnode/src/views/admin/views/content/form/translation-freshness.ts b/packages/vitnode/src/views/admin/views/content/form/translation-freshness.ts
index 532b5454f5..a5915452ca 100644
--- a/packages/vitnode/src/views/admin/views/content/form/translation-freshness.ts
+++ b/packages/vitnode/src/views/admin/views/content/form/translation-freshness.ts
@@ -26,6 +26,20 @@ const recordsKey = (contentTypeId: string, itemId: ContentId) => [
   itemId,
 ];
 
+/**
+ * Tracks whether each translated field still matches its source-language
+ * text, for a localized content form. Must render inside the content form
+ * (it uses `useContentForm`). Records load for an existing item only.
+ *
+ * Returns:
+ * - `freshnessOf(locale)`: per field, `missing` (empty), `untracked` (no
+ *   record), `outdated` (the source text changed since), `edited` (changed
+ *   after it was translated) or `fresh`.
+ * - `outdatedFields(locale)` and `editedByPerson(locale, field)`.
+ * - `rememberAiTranslation(locale, field)` and `markReviewed(locale, fields)`:
+ *   queue a record; queued records are written after the form saves, one
+ *   request per locale.
+ */
 export const useTranslationFreshness = <Field extends string>({
   contentTypeId,
   fields,
@@ -34,9 +48,13 @@ export const useTranslationFreshness = <Field extends string>({
   values,
 }: {
   contentTypeId: string;
+  /** The localized fields to track. */
   fields: readonly Field[];
+  /** The record being edited; `undefined` while creating. */
   itemId: ContentId | undefined;
+  /** The source locale translations are compared against. */
   source: string;
+  /** The form's current values for `fields`. */
   values: Partial<Record<Field, unknown>>;
 }) => {
   const queryClient = useQueryClient();
diff --git a/packages/vitnode/src/views/admin/views/content/form/values.ts b/packages/vitnode/src/views/admin/views/content/form/values.ts
index 7a9b2b5555..3338eec8ee 100644
--- a/packages/vitnode/src/views/admin/views/content/form/values.ts
+++ b/packages/vitnode/src/views/admin/views/content/form/values.ts
@@ -3,6 +3,7 @@ import React from "react";
 
 import { useFormApi } from "@/components/ui/form";
 
+/** The form's current values, re-rendering on every change. */
 export const useContentFormValues = (): Record<string, unknown> => {
   const { form } = useFormApi();
 
@@ -12,6 +13,7 @@ export const useContentFormValues = (): Record<string, unknown> => {
   );
 };
 
+/** Returns a stable `(name, value) => void` that sets one form field's value. */
 export const useSetContentFormValue = () => {
   const { form } = useFormApi();
 
diff --git a/packages/vitnode/src/views/admin/views/content/live/presence.tsx b/packages/vitnode/src/views/admin/views/content/live/presence.tsx
index 740c994861..e3ba6d8b96 100644
--- a/packages/vitnode/src/views/admin/views/content/live/presence.tsx
+++ b/packages/vitnode/src/views/admin/views/content/live/presence.tsx
@@ -57,11 +57,18 @@ const useActivity = () => {
   };
 };
 
+/**
+ * Avatars of the other people editing this record live, one per person, each
+ * with a tooltip saying what they are on (a field and language, or just
+ * viewing). Renders nothing outside a live editing session or when you are
+ * alone. Place it in a custom content form layout's header.
+ */
 export const ContentLivePresence = ({
   className,
   max = 5,
 }: {
   className?: string;
+  /** Avatars shown before the rest collapse into a `+N` count. Defaults to 5. */
   max?: number;
 }) => {
   const t = useTranslations("core.content.live.presence");
diff --git a/packages/vitnode/src/views/admin/views/content/live/status.tsx b/packages/vitnode/src/views/admin/views/content/live/status.tsx
index bdb76b4545..594e9ddd2a 100644
--- a/packages/vitnode/src/views/admin/views/content/live/status.tsx
+++ b/packages/vitnode/src/views/admin/views/content/live/status.tsx
@@ -93,6 +93,12 @@ const AutosavedDraft = ({ savedAt }: { savedAt: null | string }) => {
   );
 };
 
+/**
+ * The live session's save state - saving, failed, an autosaved draft with a
+ * Discard button, or when it was last saved - as a `role="status"` line.
+ * Renders nothing outside a live editing session or before anything changes.
+ * Place it in a custom content form layout's header.
+ */
 export const ContentLiveStatus = ({ className }: { className?: string }) => {
   const t = useTranslations("core.content.live.status");
   const live = useContentLive();
diff --git a/packages/vitnode/src/views/admin/views/core/users/list/users-query.ts b/packages/vitnode/src/views/admin/views/core/users/list/users-query.ts
index cf5a5ad0cc..de89c60605 100644
--- a/packages/vitnode/src/views/admin/views/core/users/list/users-query.ts
+++ b/packages/vitnode/src/views/admin/views/core/users/list/users-query.ts
@@ -200,6 +200,12 @@ export const adminUserOptionsFrom = (
     role: { color: role.color, prefix: role.prefix ?? null },
   }));
 
+/**
+ * Searches users for a user picker, from the browser with the admin's
+ * session (`admin/users/list`). Resolves with the first 20 matches, or `[]` -
+ * never throws: an error response resolves with `[]`, and a thrown error
+ * (e.g. network) is also logged to the console. Browser-only.
+ */
 export const searchAdminUsersInBrowser: AdminUserSearchOptions =
   async search => {
     try {
diff --git a/packages/vitnode/src/views/admin/views/core/users/roles/roles-query.ts b/packages/vitnode/src/views/admin/views/core/users/roles/roles-query.ts
index 034b08cc0f..ea7efbab32 100644
--- a/packages/vitnode/src/views/admin/views/core/users/roles/roles-query.ts
+++ b/packages/vitnode/src/views/admin/views/core/users/roles/roles-query.ts
@@ -148,6 +148,13 @@ export const adminRoleOptionsFrom = (
     .filter(role => !role.guest)
     .map(({ color, id, name, prefix }) => ({ color, id, name, prefix }));
 
+/**
+ * Searches roles for a role picker, from the browser with the admin's
+ * session (`admin/roles/list`). Leaves out the guest role. Resolves with the
+ * first 20 matches, or `[]` - never throws: an error response resolves with
+ * `[]`, and a thrown error (e.g. network) is also logged to the console.
+ * Browser-only.
+ */
 export const searchAdminRolesInBrowser: AdminRoleSearch = async search => {
   try {
     const response = await fetcherClient({
diff --git a/packages/vitnode/src/views/auth/sso/icons.ts b/packages/vitnode/src/views/auth/sso/icons.ts
index 1c9723bf84..cdce75ac10 100644
--- a/packages/vitnode/src/views/auth/sso/icons.ts
+++ b/packages/vitnode/src/views/auth/sso/icons.ts
@@ -4,6 +4,13 @@ export type SSOIcon = React.ReactElement | SSOIconComponent;
 
 const registered = new Map<string, SSOIcon>();
 
+/**
+ * Registers custom icons for SSO providers, keyed by provider id. A
+ * registered icon wins over the one the provider's adapter sends; a component
+ * is rendered with `className="size-4"`. Calls merge, so plugins can each add
+ * their own. Call it from a module the router entry imports, so it runs before
+ * the login screen renders.
+ */
 export const configureSSOIcons = (icons: Record<string, SSOIcon>) => {
   for (const [providerId, icon] of Object.entries(icons)) {
     registered.set(providerId, icon);
diff --git a/packages/vitnode/src/views/layouts/theme/layout-content.tsx b/packages/vitnode/src/views/layouts/theme/layout-content.tsx
index 6e90a3140a..5c21bc3918 100644
--- a/packages/vitnode/src/views/layouts/theme/layout-content.tsx
+++ b/packages/vitnode/src/views/layouts/theme/layout-content.tsx
@@ -1,3 +1,21 @@
+/**
+ * The public site's page frame: `listeners`, then `header`, then `breadcrumb`,
+ * then the page inside `<main>`. Each slot is optional and renders nothing
+ * when unset. Universal.
+ *
+ * @example
+ * ```tsx
+ * import { Outlet } from "@tanstack/react-router";
+ * import { MainBreadcrumb } from "@vitnode/core/tanstack/breadcrumb";
+ * import { MainHeader, ThemeLayoutContent } from "@vitnode/core/tanstack/layout";
+ *
+ * const MainLayout = () => (
+ *   <ThemeLayoutContent breadcrumb={<MainBreadcrumb />} header={<MainHeader />}>
+ *     <Outlet />
+ *   </ThemeLayoutContent>
+ * );
+ * ```
+ */
 export const ThemeLayoutContent = ({
   breadcrumb,
   children,
@@ -9,7 +27,7 @@ export const ThemeLayoutContent = ({
   children: React.ReactNode;
   /** The site header. A slot, because its contents are framework-bound. */
   header?: React.ReactNode;
-
+  /** Invisible components rendered before the header, e.g. event listeners. */
   listeners?: React.ReactNode;
 }) => (
   <>
diff --git a/packages/vitnode/src/vitnode.config.ts b/packages/vitnode/src/vitnode.config.ts
index 6e3bfadf2c..b5b9095936 100644
--- a/packages/vitnode/src/vitnode.config.ts
+++ b/packages/vitnode/src/vitnode.config.ts
@@ -35,67 +35,156 @@ import { assertNavigationConfig } from "./lib/navigation";
 
 export type { LocaleConfig };
 
+/**
+ * An app's frontend configuration, written in `src/vitnode.config.ts` with
+ * {@link buildConfig}. It reaches the browser, so it must not hold secrets;
+ * server-only settings go in {@link VitNodeServerConfig} and
+ * {@link VitNodeApiConfig}.
+ */
 export interface VitNodeConfig<
   AppLocales extends LocaleConfig[] = LocaleConfig[],
 > {
+  /** Starts `react-scan` render highlighting in development. Ignored in production. */
   debug?: boolean;
   /** Editor settings shared by every `Editor` in the app. */
   editor?: VitNodeEditorConfig;
+  /** Languages and locale routing. */
   i18n: VitNodeI18nConfig<AppLocales>;
+  /** The site logo component. Defaults to the VitNode logo. */
   logo?: VitNodeLogo;
+  /** The site title, used in page titles as `{page} - {shortTitle ?? title}`. */
   metadata: VitNodeMetadata;
+  /**
+   * The header menu and the mobile bottom bar. Titles are message keys, and
+   * `buildConfig` checks them along with the links.
+   */
   navigation?: NavigationConfig;
   /**
    * The server-rendered HTML cache: where it is stored, and per-route
    * overrides of the policies plugins declare. See `PageCacheConfig`.
    */
   pageCache?: PageCacheConfig;
+  /**
+   * The installed plugins' frontend halves, each a plugin's `buildPlugin()`
+   * result. The VitNode Vite plugin reads this list to generate the app's plugin
+   * routes, API registry, AdminCP registries and message loaders.
+   */
   plugins: BuildPluginReturn[];
+  /** Theme provider options, e.g. `defaultTheme: "system"`. */
   theme?: Omit<
     ThemeProviderProps,
     "attribute" | "children" | "disableTransitionOnChange" | "enableSystem"
   >;
+  /**
+   * `false` turns off page view transitions (the page fade and the logo
+   * morph). The app's router reads it through `navigationViewTransition()`
+   * from `@vitnode/core/tanstack/view-transitions`. Defaults to on.
+   */
   viewTransitions?: boolean;
 }
 
+/**
+ * The frontend settings only the server reads, written with
+ * {@link buildServerConfig} in a module the browser bundle never imports.
+ */
 export interface VitNodeServerConfig<
   AppLocales extends LocaleConfig[] = LocaleConfig[],
 > {
   /** The shared config this app also serves to the browser. */
   config: VitNodeConfig<AppLocales>;
 
+  /**
+   * The app's own translations, merged over the packages' strings: keyed by
+   * locale, then by namespace - a package id to override that package, or the
+   * app's own namespace.
+   */
   messages?: AppMessagesMap;
 
+  /** Each package's message loaders - the generated `src/package-messages.gen.ts`. */
   packageMessages?: Record<string, LocaleMessagesMap | undefined>;
 }
 
+/**
+ * An API's configuration, written in `src/vitnode.api.config.ts` with
+ * {@link buildApiConfig}. Server-only: it holds the database and secrets.
+ */
 export interface VitNodeApiConfig {
+  /** AI models and providers, resolved through `c.get("ai")`. AI features are off without it. */
   ai?: AIConfig;
+  /** Sessions, cookies and sign-in methods. */
   authorization?: {
+    /**
+     * How long an AdminCP session lasts without activity, in milliseconds;
+     * activity extends it. Defaults to one hour.
+     */
     adminCookieExpires?: number;
+    /** Defaults to `vitnode_auth_admin`. */
     adminCookieName?: string;
 
+    /**
+     * The `Domain` of the auth cookies, to share a session across subdomains.
+     * Unset means host-only cookies, right for most installs.
+     */
     cookieDomain?: string;
+    /** Session lifetime in milliseconds. Defaults to 90 days. */
     cookieExpires?: number;
+    /** Defaults to `vitnode_auth`. */
     cookieName?: string;
+    /** Sets `Secure` on the auth cookies. Defaults to `true`; turn off only for plain-HTTP development. */
     cookieSecure?: boolean;
+    /** How long a device is remembered, in milliseconds. Defaults to one year. */
     deviceCookieExpires?: number;
+    /** Defaults to `vitnode_device`. */
     deviceCookieName?: string;
+    /**
+     * Enables passkey sign-in. Off by default; `true` uses the web origin
+     * (`VITNODE_WEB_URL`) as the only origin and its host as the RP ID.
+     * Misconfigured origins or RP ID stop the API from starting.
+     */
     passkeys?: boolean | PasskeysConfig;
+    /** Email and password sign-in. Defaults to `true`. */
     password?: boolean;
+    /** Single sign-on providers. Defaults to none. */
     ssoAdapters?: SSOApiPlugin[];
   };
+  /**
+   * Requires a captcha on routes built with `withCaptcha`. Without it those
+   * routes skip the check.
+   */
   captcha?: {
+    /** The provider's secret key. A missing key fails every captcha check. */
     secretKey: string | undefined;
+    /** The public key the browser renders the widget with. */
     siteKey: string | undefined;
     type: "cloudflare_turnstile" | "recaptcha_v3";
   };
   /** Content Engine settings that are deployment-shaped rather than per type. */
   content?: {
+    /**
+     * Front-end origins told to revalidate their cached content after a
+     * background write (a scheduled publish, say): each one gets a POST to
+     * `{origin}/api/vitnode/content/revalidate` carrying `CRON_SECRET`.
+     * Outside development, only `https` origins (or `http` on localhost) are
+     * notified, and only once `CRON_SECRET` is set to a non-default value.
+     */
     revalidateOrigins?: string[];
   };
+  /**
+   * The web build's generated `src/content-modules.gen.ts`. At startup the API
+   * checks that every plugin publishing content URLs also exports those
+   * content types from its `./content` module, which is how the web build
+   * checks a page serves each URL. Without it, each plugin's `./content` is
+   * resolved from the working directory instead.
+   */
   contentModules?: Readonly<Record<string, unknown>>;
+  /**
+   * Runs the registered cron jobs on an in-process scheduler (e.g.
+   * `@vitnode/node-cron`, ticking every minute). Its `schedule()` is called
+   * once at startup; without it, jobs run only when the cron endpoint is
+   * called externally.
+   */
   cron?: CronAdapter;
+  /** The Drizzle database, available to routes as `c.get("db")`. */
   dbProvider: ReturnType<typeof drizzle>;
   /**
    * Publishes the OpenAPI document at `/swagger/doc` and Swagger UI at
@@ -108,18 +197,29 @@ export interface VitNodeApiConfig {
    * something in front of it if the install is public.
    */
   docs?: { enabled?: boolean };
+  /** Outgoing email. Sending fails with a `500` until an `adapter` is set. */
   email?: {
+    /** The email provider, e.g. `@vitnode/nodemailer` or `@vitnode/resend`. */
     adapter?: EmailApiPlugin;
+    /** The logo in the default email template. */
     logo?: DefaultTemplateEmailProps["templateProps"]["logo"];
+    /** Tailwind theme overrides for the default email template. */
     tailwindConfig?: DefaultTemplateEmailProps["templateProps"]["tailwindConfig"];
   };
 
+  /** How `c.get("events")` delivers events to listeners. */
   events?: {
+    /** Where events are dispatched. Defaults to the in-process adapter. */
     adapter?: EventsApiPlugin;
   };
 
+  /**
+   * The web build's generated `src/plugin-inventory.gen.ts`, so the AdminCP
+   * can list plugins installed only on the frontend and check them for updates.
+   */
   frontendPlugins?: FrontendPluginInventory;
 
+  /** The API's locales and server-side message overrides. Usually the app's own `i18n` block. */
   i18n?: VitNodeApiI18nConfig;
   /**
    * Largest request body the API will read, in bytes. Defaults to 25 MB.
@@ -131,7 +231,13 @@ export interface VitNodeApiConfig {
    * unauthenticated caller was choosing.
    */
   maxBodySize?: number;
+  /** The site title, used in emails and as the passkey RP name. */
   metadata: VitNodeMetadata;
+  /**
+   * Notification worker tuning. Integers only, clamped to safe ranges. Defaults:
+   * `emailBatchSize` 50, `emailConcurrency` 4, `fanoutBatchSize` 500,
+   * `retentionDays` 90.
+   */
   notifications?: Partial<NotificationWorkerSettings>;
   /**
    * For an API that runs in its own process, next to a web app that caches
@@ -145,21 +251,43 @@ export interface VitNodeApiConfig {
     maxLifetime?: number;
     storage: "redis";
   };
+  /** The installed plugins' API halves, each a plugin's `buildApiPlugin()` result. Core is added automatically. */
   plugins: BuildPluginApiReturn[];
+  /**
+   * Request limits per category. `safety` and `auth` are always counted per
+   * IP; `read`, `write` and `contentWrite` are counted per signed-in user when
+   * `perUser` is on (the default), else per IP. Stored in Redis when `redis`
+   * is set, in memory otherwise.
+   */
   rateLimiter?: RateLimiterConfig;
 
+  /**
+   * Redis connection options (node-redis `createClient`), e.g. `{ url:
+   * process.env.REDIS_URL }`. Enables `c.get("cache")`, a shared rate-limit
+   * store and cross-instance WebSocket messages. Without it caching is a no-op.
+   */
   redis?: CacheConfig;
 
+  /** The search engine behind `c.get("search")` and the site search. */
   search?: {
+    /** The search provider. Defaults to PostgreSQL full-text search. */
     adapter?: SearchProviderApiPlugin;
   };
 
+  /** File uploads, served through `c.get("storage")`. */
   storage?: {
+    /**
+     * Where uploaded files are stored. Without one, uploads fail with `500`.
+     */
     adapter?: StorageApiPlugin;
 
+    /** Re-encodes uploaded images with `sharp`. Images are stored as uploaded when unset. */
     image?: {
+      /** Largest image accepted, in total pixels. Defaults to 40,000,000. */
       maxPixels?: number;
+      /** Encoder quality, 1-100. Defaults to 85. */
       quality?: number;
+      /** Converts images to WebP. Defaults to `true`. */
       webp?: boolean;
     };
   };
@@ -178,6 +306,7 @@ export interface VitNodeApiConfig {
     /** `false` turns checking off - for an install without outbound network access. Defaults to `true`. */
     enabled?: boolean;
   };
+  /** Member profile settings. */
   users?: {
     /**
      * Which personal-information fields this install offers. Every field is on
@@ -194,6 +323,33 @@ const DEFAULT_TIME_ZONE = "UTC";
 
 let registeredVitNodeConfig: undefined | VitNodeConfig;
 
+/**
+ * Declares the app's frontend configuration and registers it for core's own
+ * screens ({@link getVitNodeConfig}). Fills `i18n.localePrefix` with
+ * `"as-needed"` and `i18n.timeZone` with `"UTC"` when unset.
+ *
+ * Universal: the browser loads it too.
+ *
+ * @throws `NavigationConfigError` when `navigation` has an invalid link or
+ * message key, more than three bottom-bar links, or too many message
+ * namespaces.
+ *
+ * @example
+ * ```ts
+ * // src/vitnode.config.ts
+ * import { blogPlugin } from "@vitnode/blog/config";
+ * import { buildConfig } from "@vitnode/core/vitnode.config";
+ *
+ * export const vitNodeConfig = buildConfig({
+ *   i18n: {
+ *     defaultLocale: "en",
+ *     locales: [{ code: "en", name: "English" }],
+ *   },
+ *   metadata: { title: "My community" },
+ *   plugins: [blogPlugin()],
+ * });
+ * ```
+ */
 export function buildConfig<const AppLocales extends LocaleConfig[]>(
   args: VitNodeConfig<AppLocales>,
 ): VitNodeConfig<AppLocales> {
@@ -215,12 +371,23 @@ export function buildConfig<const AppLocales extends LocaleConfig[]>(
   return config;
 }
 
+/**
+ * Declares the server-only part of the frontend configuration: app message
+ * overrides and the generated package message loaders. Import it only from
+ * server code.
+ */
 export function buildServerConfig<const AppLocales extends LocaleConfig[]>(
   args: VitNodeServerConfig<AppLocales>,
 ): VitNodeServerConfig<AppLocales> {
   return args;
 }
 
+/**
+ * The config {@link buildConfig} registered, for framework code that cannot
+ * receive it as a prop.
+ *
+ * @throws When `buildConfig` has not run yet in this runtime.
+ */
 export const getVitNodeConfig = (): VitNodeConfig => {
   if (!registeredVitNodeConfig) {
     throw new Error(
@@ -231,6 +398,30 @@ export const getVitNodeConfig = (): VitNodeConfig => {
   return registeredVitNodeConfig;
 };
 
+/**
+ * Declares an API's configuration. Returns it unchanged; validation happens
+ * when the API starts.
+ *
+ * Server-only.
+ *
+ * @example
+ * ```ts
+ * // src/vitnode.api.config.ts
+ * import { blogApiPlugin } from "@vitnode/blog/config.api";
+ * import { coreRelations } from "@vitnode/core/database/relations";
+ * import { buildApiConfig } from "@vitnode/core/vitnode.config";
+ * import { drizzle } from "drizzle-orm/postgres-js";
+ *
+ * export const vitNodeApiConfig = buildApiConfig({
+ *   dbProvider: drizzle({
+ *     connection: process.env.POSTGRES_URL ?? "",
+ *     relations: coreRelations,
+ *   }),
+ *   metadata: { title: "My community" },
+ *   plugins: [blogApiPlugin()],
+ * });
+ * ```
+ */
 export function buildApiConfig(args: VitNodeApiConfig): VitNodeApiConfig {
   return args;
 }
diff --git a/packages/vitnode/src/ws/handle.ts b/packages/vitnode/src/ws/handle.ts
index 27ccc199db..454e390f46 100644
--- a/packages/vitnode/src/ws/handle.ts
+++ b/packages/vitnode/src/ws/handle.ts
@@ -28,6 +28,16 @@ const parseMessage = (raw: unknown): undefined | VitNodeWSMessage => {
   return undefined;
 };
 
+/**
+ * Builds the Hono `upgradeWebSocket` handler for the app's `/ws` route: tracks
+ * each connection with its signed-in user and routes incoming messages to the
+ * matching `buildWebSocket` handler by id.
+ *
+ * Server-only. Call it once where the API mounts WebSockets.
+ *
+ * @param createEvents Optional connection-level handlers. Their `onMessage`
+ * only receives messages that matched no registered socket.
+ */
 export function handleVitNodeWebSocket(
   createEvents?: (c: Context<EnvVitNode>) => Promise<WSEvents> | WSEvents,
 ) {
diff --git a/packages/vitnode/src/ws/notifications.ts b/packages/vitnode/src/ws/notifications.ts
index f40793c346..2e12b3c4cb 100644
--- a/packages/vitnode/src/ws/notifications.ts
+++ b/packages/vitnode/src/ws/notifications.ts
@@ -8,11 +8,19 @@ export type VitNodeNotificationType = "error" | "info" | "success" | "warning";
 
 /** A notification pushed to a single user over the WebSocket. */
 export interface VitNodeNotification {
+  /** Shown under the title. */
   description?: string;
   title: string;
+  /** The toast's style; a plain toast when omitted. */
   type?: VitNodeNotificationType;
 }
 
+/**
+ * Core's channel for transient toast notifications to one user: send with
+ * `c.get("realtime").sendToUser(userId, notificationsChannel, { title, … })`.
+ * They reach open tabs only and are gone on reload; for a persistent inbox
+ * entry use `c.get("notifications").publish()`.
+ */
 export const notificationsChannel = createWebSocketChannel<
   never,
   VitNodeNotification
diff --git a/packages/vitnode/src/ws/provider.tsx b/packages/vitnode/src/ws/provider.tsx
index 1b6e522b22..8ea7253277 100644
--- a/packages/vitnode/src/ws/provider.tsx
+++ b/packages/vitnode/src/ws/provider.tsx
@@ -41,6 +41,14 @@ const shouldConnectWebSocket = (): boolean =>
   CONFIG.api.pathname !== CONFIG.web.pathname ||
   CONFIG.api.port !== CONFIG.web.port;
 
+/**
+ * Owns the browser's single WebSocket connection to `/api/ws` for
+ * `useVitNodeWebSocket` hooks below it. Tabs share one socket
+ * (one tab holds it and relays for the others) and it reconnects after a drop.
+ *
+ * It does not connect when the API is served from the same path and port as
+ * the web app.
+ */
 export const VitNodeWebSocketProvider = ({
   children,
 }: {
diff --git a/packages/vitnode/src/ws/registry.ts b/packages/vitnode/src/ws/registry.ts
index 36aa0a4abf..0247cf25eb 100644
--- a/packages/vitnode/src/ws/registry.ts
+++ b/packages/vitnode/src/ws/registry.ts
@@ -53,7 +53,13 @@ const unindexUser = (ws: WSContext, userId: null | number | undefined) => {
   if (sockets.size === 0) connectionsByUser.delete(userId);
 };
 
+/**
+ * This process's open WebSocket connections and rooms. Server-only. Every
+ * method acts on this instance only; for delivery across instances (via
+ * Redis) use `c.get("realtime")`. A socket whose send fails is removed.
+ */
 export const wsRegistry = {
+  /** Tracks a new connection and the signed-in user who owns it (`null` for a guest). */
   add: (ws: WSContext, userId: null | number): void => {
     unindexUser(ws, connections.get(ws));
     connections.set(ws, userId);
@@ -68,6 +74,10 @@ export const wsRegistry = {
     if (connections.size === 0) return;
     sendRawToAll(connections.keys(), encode(id, data));
   },
+  /**
+   * Adds `memberId` on this socket to `room`; `true` if it was not there yet.
+   * Check who may join before calling it - a room is only as private as that.
+   */
   join: (ws: WSContext, room: string, memberId: string): boolean => {
     const sockets = rooms.get(room) ?? new Map<WSContext, Set<string>>();
     rooms.set(room, sockets);
@@ -82,6 +92,7 @@ export const wsRegistry = {
 
     return true;
   },
+  /** Removes `memberId` on this socket from `room`; `true` if it was there. */
   leave: (ws: WSContext, room: string, memberId: string): boolean => {
     const sockets = rooms.get(room);
     const members = sockets?.get(ws);
@@ -97,10 +108,16 @@ export const wsRegistry = {
 
     return true;
   },
+  /** Every member of `room` on this instance, with its socket. */
   membersOf: (room: string): { memberId: string; ws: WSContext }[] =>
     [...(rooms.get(room) ?? new Map<WSContext, Set<string>>())].flatMap(
       ([ws, members]) => [...members].map(memberId => ({ memberId, ws })),
     ),
+  /**
+   * Runs `listener` when a socket that was in a room closes, with the rooms
+   * and members it left. Returns an unsubscribe function. Listener errors are
+   * logged, not thrown.
+   */
   onConnectionClose: (listener: ConnectionCloseListener): (() => void) => {
     closeListeners.add(listener);
 
@@ -108,6 +125,7 @@ export const wsRegistry = {
       closeListeners.delete(listener);
     };
   },
+  /** Forgets a closed connection and takes it out of every room. */
   remove: (ws: WSContext): void => {
     unindexUser(ws, connections.get(ws));
     connections.delete(ws);
@@ -138,7 +156,9 @@ export const wsRegistry = {
       }
     });
   },
+  /** The rooms one socket is in. */
   roomsOf: (ws: WSContext): string[] => [...(roomsBySocket.get(ws) ?? [])],
+  /** Send `{ id, data }` to every socket in `room` on this instance. */
   toRoom: (room: string, id: string, data: unknown): void => {
     const sockets = rooms.get(room);
     if (!sockets) return;
@@ -300,7 +320,16 @@ export const publishToInstances = (topic: string, data: unknown): void => {
   publish({ data, id: topic, type: "instance" });
 };
 
+/**
+ * Server push to browsers over the shared WebSocket, available as
+ * `c.get("realtime")` in API handlers.
+ *
+ * Delivery is best effort and fire-and-forget: clients that are not connected
+ * miss the message. Without Redis (`REDIS_URL`) only clients connected to the
+ * current instance receive it; with Redis it is relayed to every instance.
+ */
 export interface VitNodeRealtime {
+  /** Push a payload to every open connection. */
   broadcast: <Receive>(
     channel: VitNodeWSChannel<unknown, Receive>,
     data: Receive,
@@ -323,6 +352,7 @@ export interface VitNodeRealtime {
     channel: VitNodeWSChannel<unknown, Receive>,
     messages: Iterable<{ data: Receive; userId: number }>,
   ) => void;
+  /** Push a payload to the connections that joined `room`. */
   toRoom: <Receive>(
     room: string,
     channel: VitNodeWSChannel<unknown, Receive>,
diff --git a/packages/vitnode/src/ws/types.ts b/packages/vitnode/src/ws/types.ts
index 079516419e..2bf5518172 100644
--- a/packages/vitnode/src/ws/types.ts
+++ b/packages/vitnode/src/ws/types.ts
@@ -1,8 +1,14 @@
+/** The JSON frame exchanged in both directions over the shared connection. */
 export interface VitNodeWSMessage<TData = unknown> {
   data: TData;
   id: string;
 }
 
+/**
+ * A socket's public id plus its message types: `Send` is what the browser
+ * sends, `Receive` what the server pushes. Create one with
+ * {@link createWebSocketChannel}.
+ */
 export interface VitNodeWSChannel<Send = unknown, Receive = unknown> {
   /**
    * Phantom field - never present at runtime. It only exists to carry the
diff --git a/packages/vitnode/src/ws/use-websocket.ts b/packages/vitnode/src/ws/use-websocket.ts
index ca511249aa..198236d2b4 100644
--- a/packages/vitnode/src/ws/use-websocket.ts
+++ b/packages/vitnode/src/ws/use-websocket.ts
@@ -14,6 +14,24 @@ export interface UseVitNodeWebSocketReturn<Send> {
   send: (data: Send) => void;
 }
 
+/**
+ * Subscribes a component to one socket on the shared connection and returns a
+ * typed `send`. Browser-only; requires `<VitNodeWebSocketProvider>` higher in
+ * the tree and throws without it.
+ *
+ * Messages sent before the connection opens are queued by the provider.
+ *
+ * @param channel A channel from `createWebSocketChannel`, or a raw socket id.
+ * @param options.onMessage Called with each payload the server sends to this
+ * socket. The latest function is always used, so it need not be memoized.
+ *
+ * @example
+ * ```tsx
+ * const { send } = useVitNodeWebSocket(echoChannel, {
+ *   onMessage: data => setText(data.text),
+ * });
+ * ```
+ */
 export function useVitNodeWebSocket<Send = unknown, Receive = unknown>(
   channel: string | VitNodeWSChannel<Send, Receive>,
   options?: {
diff --git a/plugins/blog/src/admin/content.tsx b/plugins/blog/src/admin/content.tsx
index a1d12e96f4..cda2c1c5de 100644
--- a/plugins/blog/src/admin/content.tsx
+++ b/plugins/blog/src/admin/content.tsx
@@ -16,6 +16,14 @@ import { BlogCategoryColorField } from "@/views/admin/category/color-field";
 
 import { blogCategoryNav, blogPostNav } from "./nav";
 
+/**
+ * The blog's AdminCP content screens, loaded from `@vitnode/blog/admin/content`
+ * into the app's generated `src/content-registry.gen.ts`.
+ *
+ * Articles swap the generated inputs for the Tiptap editor and the AI-assisted
+ * text fields, and share one custom layout between create and edit.
+ * Categories get a colour picker and a colour swatch column.
+ */
 export const adminContent = {
   pluginId: manifest.id,
   contentTypes: [
diff --git a/plugins/blog/src/admin/nav.tsx b/plugins/blog/src/admin/nav.tsx
index 667577fd81..620706090f 100644
--- a/plugins/blog/src/admin/nav.tsx
+++ b/plugins/blog/src/admin/nav.tsx
@@ -18,6 +18,10 @@ export const blogCategoryNav = {
   icon: <ListIcon />,
 };
 
+/**
+ * The blog's AdminCP sidebar entries, loaded from `@vitnode/blog/admin/nav`
+ * into the app's generated `src/admin-nav.gen.ts`.
+ */
 export const adminNav = {
   pluginId: manifest.id,
   contentTypes: [blogPostNav, blogCategoryNav],
diff --git a/plugins/blog/src/api/builders.ts b/plugins/blog/src/api/builders.ts
index 1ab9de62d3..4efc57c281 100644
--- a/plugins/blog/src/api/builders.ts
+++ b/plugins/blog/src/api/builders.ts
@@ -3,6 +3,11 @@ import { bindContentPlugin } from "@vitnode/core/content/server";
 
 import { manifest } from "@/manifest.gen";
 
+/** Module and route builders bound to the `@vitnode/blog` plugin id. */
 export const { buildModule, buildRoute } = bindApiPlugin(manifest);
+/**
+ * The blog's generated Content Engine modules: `buildContentAdminModule` for
+ * the AdminCP CRUD routes and `buildContentPublicModule` for the public ones.
+ */
 export const { buildContentAdminModule, buildContentPublicModule } =
   bindContentPlugin(manifest);
diff --git a/plugins/blog/src/api/lib/events.ts b/plugins/blog/src/api/lib/events.ts
index b01622b2bf..240b92c160 100644
--- a/plugins/blog/src/api/lib/events.ts
+++ b/plugins/blog/src/api/lib/events.ts
@@ -10,31 +10,49 @@ import type { blogCategoryContentType } from "@/content/category";
 import { blogPostContentType } from "@/content/post";
 import { postContent } from "@/database/posts";
 
+// Types every `content.blog.post.*` / `content.blog.category.*` event the
+// Content Engine emits, plus the six older `blog.*` names re-emitted below.
 declare module "@vitnode/core/api/models/events" {
   interface VitNodeEvents
     extends
       ContentEventsFor<typeof blogCategoryContentType>,
       ContentEventsFor<typeof blogPostContentType> {
+    /** Compatibility name for `content.blog.category.created`. */
     "blog.category.created": {
       categoryId: number;
     };
+    /** Compatibility name for `content.blog.category.deleted`. */
     "blog.category.deleted": {
       categoryId: number;
-
+      /**
+       * Always empty: a category that still has articles cannot be deleted
+       * (`onDelete: "restrict"`), so a deletion never removes any.
+       */
       postIds: number[];
     };
+    /** Compatibility name for `content.blog.category.updated`. */
     "blog.category.updated": {
       categoryId: number;
     };
+    /**
+     * Compatibility name for `content.blog.post.created`. Skipped when no
+     * category can be read back for the article.
+     */
     "blog.post.created": {
+      /** The article's first category only, although it can have several. */
       categoryId: number;
       postId: number;
     };
-
+    /** Compatibility name for `content.blog.post.deleted`. */
     "blog.post.deleted": {
       postId: number;
     };
+    /**
+     * Compatibility name for `content.blog.post.updated`. Skipped when no
+     * category can be read back for the article.
+     */
     "blog.post.updated": {
+      /** The article's first category only, although it can have several. */
       categoryId: number;
       postId: number;
     };
@@ -130,6 +148,17 @@ export const legacyCategoryDeletedListener = buildEventListener({
   },
 });
 
+/**
+ * Listeners that re-emit the Content Engine's `content.blog.*` created, updated
+ * and deleted events under the blog's older `blog.*` names, so existing
+ * consumers keep working. Each runs as an ordinary listener of the `content.*`
+ * event, through the installation's events adapter. Prefer the `content.*`
+ * events for new code: they also cover publication, visibility, translations
+ * and the other lifecycle actions, which have no `blog.*` name.
+ *
+ * Registered on the blog's top-level `admin` module, because event listeners
+ * are only collected from top-level modules.
+ */
 export const blogLegacyEventListeners = [
   legacyCategoryCreatedListener,
   legacyCategoryDeletedListener,
diff --git a/plugins/blog/src/config.api.ts b/plugins/blog/src/config.api.ts
index 1fe2234b96..1d5dc385c8 100644
--- a/plugins/blog/src/config.api.ts
+++ b/plugins/blog/src/config.api.ts
@@ -9,6 +9,33 @@ import { categoryContent } from "@/database/categories";
 import { postContent } from "@/database/posts";
 import { manifest } from "@/manifest.gen";
 
+/**
+ * The blog's API half, registered in the app's `src/vitnode.api.config.ts`
+ * (`buildApiConfig({ plugins: [blogApiPlugin()] })`).
+ *
+ * It mounts:
+ * - `admin` - the generated AdminCP content modules for articles and
+ *   categories, the AI writing routes, and the compatibility event listeners
+ *   from `@/api/lib/events`.
+ * - `content/blog` - the public read and delivery routes the Content Engine
+ *   generates from the article's `publicApi`. Categories have no `publicApi`,
+ *   so they are not exposed publicly.
+ *
+ * The blog's AI actions (field translation, excerpt and article review) are
+ * registered here too.
+ *
+ * @example
+ * ```ts
+ * // src/vitnode.api.config.ts
+ * import { blogApiPlugin } from "@vitnode/blog/config.api";
+ * import { buildApiConfig } from "@vitnode/core/vitnode.config";
+ *
+ * export const vitNodeApiConfig = buildApiConfig({
+ *   // ...
+ *   plugins: [blogApiPlugin()],
+ * });
+ * ```
+ */
 export const blogApiPlugin = () =>
   buildApiPlugin({
     manifest,
@@ -23,6 +50,11 @@ export const blogApiPlugin = () =>
     ],
   });
 
+/**
+ * The blog API's route contract, which the generated app API registry reads so
+ * `fetcher({ plugin: "@vitnode/blog", ... })` infers modules, paths and
+ * responses.
+ */
 export type VitNodeApiPlugin = ApiPluginContract<
   ReturnType<typeof blogApiPlugin>
 >;
diff --git a/plugins/blog/src/config.tsx b/plugins/blog/src/config.tsx
index d172abfaa4..73d32f46b8 100644
--- a/plugins/blog/src/config.tsx
+++ b/plugins/blog/src/config.tsx
@@ -4,6 +4,28 @@ import messages from "./locales";
 import { manifest } from "./manifest.gen";
 import { routes } from "./routes";
 
+/**
+ * The blog's frontend half: its manifest, locale files and the public
+ * `/blog/:slug` article page.
+ *
+ * Register it in the app's `src/vitnode.config.ts`, next to
+ * `blogApiPlugin` in `src/vitnode.api.config.ts` - both read the same
+ * `@vitnode/blog` manifest. The AdminCP sidebar entries and content forms are
+ * not passed here: VitNode discovers them from the package's `admin/nav` and
+ * `admin/content` exports when it generates the app's registries.
+ *
+ * @example
+ * ```ts
+ * // src/vitnode.config.ts
+ * import { blogPlugin } from "@vitnode/blog/config";
+ * import { buildConfig } from "@vitnode/core/vitnode.config";
+ *
+ * export const vitNodeConfig = buildConfig({
+ *   // ...
+ *   plugins: [blogPlugin()],
+ * });
+ * ```
+ */
 export const blogPlugin = () =>
   buildPlugin({
     manifest,
diff --git a/plugins/blog/src/content.ts b/plugins/blog/src/content.ts
index 16cc98f071..970f25c414 100644
--- a/plugins/blog/src/content.ts
+++ b/plugins/blog/src/content.ts
@@ -1,4 +1,10 @@
 import { blogCategoryContentType } from "@/content/category";
 import { blogPostContentType } from "@/content/post";
 
+/**
+ * The blog's content type definitions, read from `@vitnode/blog/content` by the
+ * VitNode Vite plugin to check that a page serves every public URL they declare
+ * (only the article has one: its `search.pathTemplate`, `/blog/{slug}`).
+ * Browser-safe: it imports only the definitions, never the database models.
+ */
 export const contentTypes = [blogPostContentType, blogCategoryContentType];
diff --git a/plugins/blog/src/content/category.ts b/plugins/blog/src/content/category.ts
index cf6eee15a7..5ef0769ec3 100644
--- a/plugins/blog/src/content/category.ts
+++ b/plugins/blog/src/content/category.ts
@@ -1,5 +1,16 @@
 import { defineContentType, field } from "@vitnode/core/content";
 
+/**
+ * The blog category (`blog.category`, table `blog_categories`): a localized
+ * name, with `en` as the fallback translation, and a shared colour.
+ *
+ * Deliberately minimal - no publication lifecycle and no `publicApi`, so
+ * categories are managed only in the AdminCP (in dialogs) and reach readers
+ * only through an article's `categoryId`.
+ *
+ * Browser-safe: the server model is `categoryContent` in
+ * `@vitnode/blog/database/categories`.
+ */
 export const blogCategoryContentType = defineContentType({
   id: "blog.category",
   tableName: "blog_categories",
diff --git a/plugins/blog/src/content/post.ts b/plugins/blog/src/content/post.ts
index 72ba7df7e4..755fbf1639 100644
--- a/plugins/blog/src/content/post.ts
+++ b/plugins/blog/src/content/post.ts
@@ -2,6 +2,24 @@ import { defineContentType, field } from "@vitnode/core/content";
 
 import { blogCategoryContentType } from "./category";
 
+/**
+ * The blog article (`blog.post`, table `blog_posts`) - the blog's reference
+ * for a fully featured content type.
+ *
+ * - Localized title, slug, body, excerpt and cover alt text, falling back to
+ *   the `en` translation when a locale has none of its own. Categories,
+ *   authors and the cover image are shared across languages.
+ * - Draft/publish lifecycle with scheduling, revisions (20 kept per article),
+ *   30-minute preview links and live editing in the AdminCP.
+ * - Duplication, hiding (visibility) and user reports for moderation.
+ * - A public API at `content/blog`, site search, and delivery with SEO
+ *   metadata, sitemap and hreflang entries and redirects from retired slugs.
+ * - At least one category; a category that still has articles cannot be
+ *   deleted.
+ *
+ * Browser-safe: the server model that binds it to Drizzle is `postContent` in
+ * `@vitnode/blog/database/posts`.
+ */
 export const blogPostContentType = defineContentType({
   id: "blog.post",
   tableName: "blog_posts",
diff --git a/plugins/blog/src/database/categories.ts b/plugins/blog/src/database/categories.ts
index 3cdc05b466..f276a2a0f9 100644
--- a/plugins/blog/src/database/categories.ts
+++ b/plugins/blog/src/database/categories.ts
@@ -2,6 +2,11 @@ import { createContentModel } from "@vitnode/core/content/server";
 
 import { blogCategoryContentType } from "@/content/category";
 
+/**
+ * The server-side model of {@link blogCategoryContentType}: its Drizzle tables
+ * and `categoryContent.service(c)` for reads and writes inside a request.
+ * Server-only - import it from API code, never from a page.
+ */
 export const categoryContent = createContentModel(blogCategoryContentType);
 
 // Two exports for a localized content type, not one. Drizzle Kit discovers each
diff --git a/plugins/blog/src/database/posts.ts b/plugins/blog/src/database/posts.ts
index 92a50cc5b7..2573deba40 100644
--- a/plugins/blog/src/database/posts.ts
+++ b/plugins/blog/src/database/posts.ts
@@ -4,10 +4,20 @@ import { blogPostContentType } from "@/content/post";
 
 import { blog_categories } from "./categories";
 
+/**
+ * The server-side model of {@link blogPostContentType}: its Drizzle tables and
+ * `postContent.service(c)` for reads and writes inside a request. Server-only -
+ * import it from API code, never from a page.
+ *
+ * `categoryId` is bound to `blog_categories.id`, which is where the article's
+ * `onDelete: "restrict"` foreign key points.
+ */
 export const postContent = createContentModel(blogPostContentType, {
   references: { categoryId: () => blog_categories.id },
 });
 
+// Every table is exported on its own: Drizzle Kit discovers tables from the
+// exports of the built `dist/src/database/*.js` when generating migrations.
 export const blog_posts = postContent.table;
 export const blog_posts_translations = postContent.translationTable;
 
diff --git a/plugins/blog/src/pages/post-query.ts b/plugins/blog/src/pages/post-query.ts
index 6a00ee1bcc..da3fbd7275 100644
--- a/plugins/blog/src/pages/post-query.ts
+++ b/plugins/blog/src/pages/post-query.ts
@@ -22,6 +22,11 @@ const zodBlogPost = z.object({
 
 const all = [manifest.id] as const;
 
+/**
+ * TanStack Query keys for the blog. Every key starts with `["@vitnode/blog"]`,
+ * so `queryClient.invalidateQueries({ queryKey: blogQueryKeys.all })` refreshes
+ * all of them.
+ */
 export const blogQueryKeys = {
   all,
   post: (request: { locale: string; slug: string }) =>
@@ -70,12 +75,34 @@ const fetchBlogPost = async ({
   };
 };
 
+/**
+ * One article lookup: the delivery `resolution` (content, redirect or not
+ * found) and the localized `item`, or `null` when the detail route did not
+ * answer `200`.
+ */
 export type BlogPostAnswer = Awaited<ReturnType<typeof fetchBlogPost>>;
 
 const isSharedAnswer = ({ item, resolution }: BlogPostAnswer): boolean =>
   resolution.type === "redirect" ||
   (resolution.type === "content" && !resolution.hidden && item !== null);
 
+/**
+ * Query options for the article at `/blog/:slug` in one locale, used by the
+ * page's loader. The resolve and detail routes are fetched in parallel.
+ *
+ * A published article or a redirect is the same for every reader, so it stays
+ * fresh for `RECORD_STALE_TIME` (one minute); a hidden article (only staff see it) or a miss
+ * is stale at once, so the next load asks again. The result is kept out of SSR
+ * dehydration, because the route's loader data already carries it to the
+ * browser. The query fails when the resolve route answers anything but `200`.
+ *
+ * @example
+ * ```ts
+ * const answer = await queryClient.query(
+ *   blogPostQueryOptions({ locale: "en", slug: "hello-world" }),
+ * );
+ * ```
+ */
 export const blogPostQueryOptions = (request: {
   locale: string;
   slug: string;
diff --git a/plugins/blog/src/plugin-info.ts b/plugins/blog/src/plugin-info.ts
index 0116c1e1eb..dcb7415be5 100644
--- a/plugins/blog/src/plugin-info.ts
+++ b/plugins/blog/src/plugin-info.ts
@@ -1,5 +1,9 @@
 import type { PluginInfo } from "@vitnode/core/lib/plugin-manifest";
 
+/**
+ * The blog's AdminCP title, Lucide icon and update source, merged into the
+ * generated `src/manifest.gen.ts`.
+ */
 export const pluginInfo: PluginInfo = {
   title: "Blog",
   icon: "newspaper",
diff --git a/plugins/blog/src/routes.ts b/plugins/blog/src/routes.ts
index bd65f38cb6..7738c0d0b6 100644
--- a/plugins/blog/src/routes.ts
+++ b/plugins/blog/src/routes.ts
@@ -1,5 +1,10 @@
 import { definePluginRoutes, lazy, page } from "@vitnode/core/routing";
 
+/**
+ * The blog's public pages. `/blog/:slug` serves the article's
+ * `search.pathTemplate` (`/blog/{slug}`); the web build fails if that URL has no
+ * matching page.
+ */
 export const routes = definePluginRoutes([
   page("/blog/:slug", {
     // Published articles read the same for everybody, so their HTML is reused