{navigableLayouts.map((layout) => {
const isActive = layout.name === activeSection;
return (
diff --git a/src/components/lists/DynamicList.tsx b/src/components/lists/DynamicList.tsx
index 20c4e93..2d04564 100644
--- a/src/components/lists/DynamicList.tsx
+++ b/src/components/lists/DynamicList.tsx
@@ -7,6 +7,7 @@
import { EmptyState } from '@/components/common/EmptyState';
import { PageHeader } from '@/components/common/PageHeader';
+import { HelpPanel } from '@/help/HelpPanel';
import { iconForView } from '@/lib/viewIcon';
import React, { useState, useEffect, useCallback, useMemo } from 'react';
import { useNavigate, useSearchParams } from 'react-router-dom';
@@ -1113,6 +1114,7 @@ export function DynamicList({ viewName }: DynamicListProps) {
+
{hasMassActions && selectedIds.size > 0 && (
diff --git a/src/help/HelpPanel.tsx b/src/help/HelpPanel.tsx
new file mode 100644
index 0000000..a9ac5da
--- /dev/null
+++ b/src/help/HelpPanel.tsx
@@ -0,0 +1,150 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Coffey Labs
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+import { useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import ReactMarkdown from 'react-markdown';
+import { ArrowUpRight, CircleHelp, Lightbulb } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from '@/components/ui/dialog';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
+import { useSchemaStore } from '@/stores/schemaStore';
+import { resolveList, resolveObject, resolveSchema } from '@/lib/schemaResolver';
+import { humanize } from '@/lib/humanize';
+import type { Schema } from '@/types/schema';
+import { fieldHelp, PAGE_HELP } from './texts';
+import { manualUrl } from './manual';
+
+interface OptionHelp {
+ id: string;
+ label: string;
+ text: string;
+}
+
+/**
+ * Everything the panel says about a page: what it's for, what people do
+ * there, and every option on its form with its explanation, in form order.
+ */
+function pageHelp(schema: Schema, viewName: string) {
+ const obj = resolveObject(schema, viewName);
+ if (!obj) return null;
+ const sch = resolveSchema(schema, obj.objectName);
+ const ours = PAGE_HELP[viewName] ?? PAGE_HELP[obj.objectName];
+ const about =
+ ours?.about ?? (schema.objects[obj.objectName] as { description?: string } | undefined)?.description ?? '';
+
+ // A view of one variant (People is x:Account of @type User) shows that variant's options.
+ const list = resolveList(schema, viewName, obj.objectName);
+ const variantName = (list?.filtersStatic as Record | undefined)?.['@type'];
+ let scope = obj.objectName;
+ let fields = sch?.type === 'single' ? sch.fields : null;
+ if (sch?.type === 'multiple') {
+ const v = sch.variants.find((x) => x.name === variantName) ?? sch.variants.find((x) => x.fields);
+ scope = v?.schemaName ?? obj.objectName;
+ fields = v?.fields ?? null;
+ }
+ const form = schema.forms[scope] ?? schema.forms[obj.objectName];
+ const order = form?.sections.flatMap((s) => s.fields.map((f) => ({ name: f.name, label: f.label }))) ?? [];
+ const names = order.length ? order : Object.keys(fields?.properties ?? {}).map((name) => ({ name, label: '' }));
+ const options: OptionHelp[] = [];
+ for (const { name, label } of names) {
+ const field = fields?.properties[name];
+ if (!field || field.update === 'serverSet' || name === '@type') continue;
+ const id = `${scope}.${name}`;
+ const text = fieldHelp(id, field.description);
+ if (text) options.push({ id, label: label || humanize(name), text });
+ }
+ return { id: obj.objectName, about, tasks: ours?.tasks ?? [], options };
+}
+
+/**
+ * The "?" at the top of a page: a panel with what the page is for, the
+ * things people usually do there, and a plain explanation of every option.
+ * The manual link appears once a manual is configured.
+ */
+export function HelpPanel({ viewName, title }: { viewName: string; title: string }) {
+ const { t } = useTranslation();
+ const schema = useSchemaStore((s) => s.schema);
+ const [open, setOpen] = useState(false);
+ const help = useMemo(() => (schema ? pageHelp(schema, viewName) : null), [schema, viewName]);
+ if (!help || (!help.about && help.options.length === 0)) return null;
+ const more = manualUrl(help.id);
+
+ return (
+ <>
+
+
+
+
+
+ {t('help.page', 'Help for this page')}
+
+
+
+
+ );
+}
diff --git a/src/help/HelpTip.tsx b/src/help/HelpTip.tsx
new file mode 100644
index 0000000..9485a97
--- /dev/null
+++ b/src/help/HelpTip.tsx
@@ -0,0 +1,62 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Coffey Labs
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+import { useTranslation } from 'react-i18next';
+import ReactMarkdown from 'react-markdown';
+import { ArrowUpRight, Info } from 'lucide-react';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
+import { cn } from '@/lib/utils';
+import { manualUrl } from './manual';
+
+/**
+ * The ⓘ beside an option: a sentence or two on what it does, on hover or
+ * focus, and a way into the manual once there is one. `id` is the option's
+ * stable help id, the key the manual links hang on.
+ */
+export function HelpTip({ id, text, className }: { id?: string; text?: string | null; className?: string }) {
+ const { t } = useTranslation();
+ if (!text) return null;
+ const more = id ? manualUrl(id) : null;
+ return (
+
+
+
+
+
+
+
+ {text.replace(/\\n/g, '\n')}
+
+ {more && (
+
+ {t('help.learnMore', 'Learn more')}
+
+
+ )}
+
+
+
+ );
+}
diff --git a/src/help/help.test.ts b/src/help/help.test.ts
new file mode 100644
index 0000000..b89c76b
--- /dev/null
+++ b/src/help/help.test.ts
@@ -0,0 +1,38 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Coffey Labs
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+import { afterEach, describe, expect, it } from 'vitest';
+import { manualUrl } from './manual';
+import { fieldHelp, FIELD_HELP } from './texts';
+
+describe('manualUrl', () => {
+ afterEach(() => document.querySelector('meta[name="manual-url"]')?.remove());
+
+ it('shows no link until a manual is configured', () => {
+ expect(manualUrl('x:Domain.dnsManagement')).toBeNull();
+ });
+
+ it('maps help ids to stable manual pages and anchors', () => {
+ const meta = document.createElement('meta');
+ meta.name = 'manual-url';
+ meta.content = 'https://docs.example.org/admin/';
+ document.head.appendChild(meta);
+ expect(manualUrl('x:Domain')).toBe('https://docs.example.org/admin/reference/domain/');
+ expect(manualUrl('x:Domain.dnsManagement')).toBe('https://docs.example.org/admin/reference/domain/#dnsmanagement');
+ expect(manualUrl('x:DnsServerCloudflare.secret')).toBe(
+ 'https://docs.example.org/admin/reference/dns-server-cloudflare/#secret',
+ );
+ expect(manualUrl('x:Account/User')).toBe('https://docs.example.org/admin/reference/account-user/');
+ });
+});
+
+describe('fieldHelp', () => {
+ it('prefers our words, then the schema description', () => {
+ expect(fieldHelp('x:Domain.catchAllAddress', 'schema text')).toBe(FIELD_HELP['x:Domain.catchAllAddress']);
+ expect(fieldHelp('x:Domain.unknownField', 'schema text')).toBe('schema text');
+ expect(fieldHelp(undefined, null)).toBeNull();
+ });
+});
diff --git a/src/help/manual.ts b/src/help/manual.ts
new file mode 100644
index 0000000..43586ad
--- /dev/null
+++ b/src/help/manual.ts
@@ -0,0 +1,39 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Coffey Labs
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+/**
+ * Links from in-app help to the INBUXA admin manual (MkDocs). Every tooltip
+ * and help panel carries a stable id, `x:Domain.dnsManagement` for a field
+ * or `x:Domain` for a page, and this is the one place that turns an id into
+ * an address. Until a manual is published there is no base URL and no link
+ * is shown.
+ *
+ * The base URL comes from VITE_MANUAL_URL at build time, or from
+ * at deploy time.
+ */
+function manualBase(): string | null {
+ const fromMeta =
+ typeof document !== 'undefined' ? document.querySelector('meta[name="manual-url"]')?.getAttribute('content') : null;
+ const base = (fromMeta || (import.meta.env.VITE_MANUAL_URL as string | undefined) || '').trim();
+ return base ? base.replace(/\/+$/, '') : null;
+}
+
+/**
+ * The manual page for a help id: `x:Domain.dnsManagement` becomes
+ * `/reference/domain/#dnsmanagement`, `x:Domain` becomes
+ * `/reference/domain/`. The manual's page names must follow this.
+ */
+export function manualUrl(id: string): string | null {
+ const base = manualBase();
+ if (!base) return null;
+ const [object, field] = id.split('.', 2);
+ const page = object
+ .replace(/^x:/, '')
+ .replace(/\//g, '-')
+ .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+ .toLowerCase();
+ return `${base}/reference/${page}/${field ? `#${field.toLowerCase()}` : ''}`;
+}
diff --git a/src/help/texts.ts b/src/help/texts.ts
new file mode 100644
index 0000000..364a627
--- /dev/null
+++ b/src/help/texts.ts
@@ -0,0 +1,153 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Coffey Labs
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+/**
+ * INBUXA's own help, in plain words, keyed by help id. Options without an
+ * entry here fall back to the description the server's schema gives. Write
+ * new entries in our own words: say what the option does for the person
+ * using it, and what goes wrong if it's set badly. Keep a tooltip to one
+ * or two sentences; the manual is where the detail goes.
+ *
+ * Keys: `object` for a page, `object.field` for an option on it.
+ */
+
+export const FIELD_HELP: Record = {
+ // Domains
+ 'x:Domain.name': 'The domain people’s addresses end in, like example.com.',
+ 'x:Domain.aliases':
+ 'Other domains that deliver to the same people. Mail to someone@alias.com lands in someone@example.com.',
+ 'x:Domain.isEnabled': 'Turn off to stop accepting mail for this domain without deleting anything.',
+ 'x:Domain.catchAllAddress':
+ 'Where mail to addresses that don’t exist goes. Handy for small teams; on a busy domain it collects spam.',
+ 'x:Domain.subAddressing':
+ 'Lets people use address+anything@example.com to sort or trace their mail. On for most domains.',
+ 'x:Domain.allowRelaying':
+ 'Forward mail for unknown people to another server, for domains split between two systems. Leave off otherwise.',
+ 'x:Domain.dkimManagement':
+ 'Signing keys that prove mail from this domain is really yours. Automatic creates and rotates them for you.',
+ 'x:Domain.certificateManagement':
+ 'The TLS certificate for this domain’s mail and web addresses. Automatic gets and renews one for you.',
+ 'x:Domain.dnsManagement':
+ 'Whether the server writes this domain’s DNS records itself through your DNS host, or you add them by hand.',
+ 'x:Domain.reportAddressUri':
+ 'Where other mail servers send reports about mail claiming to be from you (DMARC, TLS). Postmaster is a good choice.',
+ 'x:Domain.memberTenantId': 'The customer or organization this domain belongs to, if you host more than one.',
+ 'x:Domain.directoryId': 'Where this domain’s accounts and passwords are kept: here, or an outside directory.',
+ 'x:Domain.logo': 'A logo for this domain’s sign-in page and mail apps. A link or an uploaded image.',
+
+ // People
+ 'x:UserAccount.name': 'The part before the @. Together with the domain it makes the person’s address.',
+ 'x:UserAccount.description': 'The person’s full name, as others see it.',
+ 'x:UserAccount.aliases': 'More addresses that deliver to this person.',
+ 'x:UserAccount.quotas':
+ 'Limits for this person, like how much storage they may use. Empty means the server’s defaults.',
+ 'x:UserAccount.roles': 'What this person may do. Most people are plain users; admins manage the server.',
+ 'x:UserAccount.memberGroupIds': 'Groups this person belongs to. They share the group’s mail and can send as it.',
+ 'x:UserAccount.credentials': 'How this person signs in: a password, app passwords for mail apps, and more.',
+ 'x:UserAccount.locale': 'The language for messages the server sends this person.',
+ 'x:UserAccount.timeZone': 'Used for calendar invitations and scheduled messages.',
+ 'x:GroupAccount.name': 'The group’s address, before the @. Mail to it reaches every member.',
+
+ // DNS providers
+ 'x:DnsServerCloudflare.secret':
+ 'A Cloudflare API token that can edit DNS for your zone. Make it with the “Edit zone DNS” template.',
+ 'x:DnsServerCloudflare.email': 'Only for the old Global API Key. Leave empty when you use an API token.',
+ 'x:DnsServerCloud.secret': 'The API token or key from your DNS host. Give it DNS access for this domain only.',
+ 'x:DnsServerCloudflare.ttl': 'How long other servers may cache the records written. Five minutes is a good default.',
+ 'x:DnsServerCloud.ttl': 'How long other servers may cache the records written. Five minutes is a good default.',
+
+ // Security
+ 'x:BlockedIp.address': 'An address or network, like 203.0.113.7 or 203.0.113.0/24, refused before it can talk.',
+ 'x:BlockedIp.reason': 'A note for yourself on why it was blocked.',
+ 'x:BlockedIp.expiresAt': 'When the block lifts by itself. Empty means it stays until you remove it.',
+ 'x:AllowedIp.address': 'An address or network that is never blocked automatically, like your office or monitoring.',
+};
+
+export interface PageHelp {
+ /** What the page is for, in a sentence or two. */
+ about: string;
+ /** The things people come here to do. */
+ tasks?: string[];
+}
+
+export const PAGE_HELP: Record = {
+ 'x:Domain': {
+ about: 'The domains this server receives and sends mail for. Each person’s address belongs to one of them.',
+ tasks: [
+ 'Add a domain, then publish its DNS records so mail can find you.',
+ 'Let the server publish DNS for you: open a domain and use “Set it up” in its DNS section.',
+ 'Turn on automatic DKIM and certificates so keys and certificates renew themselves.',
+ ],
+ },
+ 'x:Account/User': {
+ about: 'Everyone with a mailbox here. Each person has an address, a password and, optionally, limits.',
+ tasks: [
+ 'Add a person and give them a password.',
+ 'Give someone more addresses with aliases.',
+ 'Set a storage limit under quotas.',
+ ],
+ },
+ 'x:Account/Group': {
+ about: 'Shared mailboxes, like sales@ or support@, that several people read and send from.',
+ tasks: ['Create a group, then add people to it from their own page under Groups.'],
+ },
+ 'x:MailingList': {
+ about: 'Addresses that pass each message on to a list of recipients, inside or outside this server.',
+ },
+ 'x:Tenant': {
+ about: 'Separate customers or organizations on one server, each with their own domains, people and limits.',
+ },
+ 'x:Role': {
+ about: 'Named sets of permissions. Give a role to a person to let them do more, or less.',
+ },
+ 'x:OAuthClient': {
+ about: 'Apps allowed to sign people in through this server, like INBUXA webmail and INBUXA Admin.',
+ },
+ 'x:DkimSignature': {
+ about: 'The keys that sign outgoing mail so receivers can check it really came from you.',
+ tasks: ['Let domains manage their own keys: set DKIM to automatic on the domain.'],
+ },
+ 'x:QueuedMessage': {
+ about:
+ 'Mail waiting to go out. Most leaves within seconds; what stays here is waiting for a server that isn’t answering.',
+ tasks: [
+ 'See why a message is stuck: open it and look at each recipient’s status.',
+ 'Retry now, or cancel mail that will never be delivered.',
+ ],
+ },
+ 'x:DnsServer': {
+ about: 'Connections to your DNS hosts, so the server can publish and update its own DNS records.',
+ tasks: ['Connect one the easy way: open a domain and use “Set it up” in its DNS section.'],
+ },
+ 'x:BlockedIp': {
+ about: 'Addresses refused before they can talk to the server. The server adds some itself when it spots attacks.',
+ tasks: ['Unblock someone: find their address and delete the entry.'],
+ },
+ 'x:AllowedIp': {
+ about: 'Addresses the server never blocks by itself, like your office network or monitoring.',
+ },
+ 'x:DmarcExternalReport': {
+ about:
+ 'Reports from other mail providers on mail they received claiming to be from your domains, and whether it passed.',
+ },
+ 'x:TlsExternalReport': {
+ about: 'Reports from other mail providers on whether they could reach you over an encrypted connection.',
+ },
+ 'x:Task': {
+ about: 'Background work the server has scheduled: DNS updates, key rotation, certificate renewal and upkeep.',
+ },
+ 'x:Task/TaskFailed': {
+ about: 'Background work that failed. Each entry says why; most retry by themselves once the cause is fixed.',
+ },
+ 'x:Log': {
+ about: 'What the server has been doing, newest first. Useful for tracing a problem back to its cause.',
+ },
+};
+
+/** The help text for an option: ours when written, else the schema's. */
+export function fieldHelp(id: string | undefined, fallback?: string | null): string | null {
+ return (id && FIELD_HELP[id]) || fallback || null;
+}