@promptbook/cli 0.114.0-1 → 0.114.0-2

package/apps/agents-server/src/components/UsersList/generateSecurePassword.ts

@@ -1,50 +1,138 @@
 /**
- * Default length of passwords generated for new admin users.
+ * Configuration for a generated password.
+ *
+ * @private utility of <PasswordGeneratorDialog/>
+ */
+export type PasswordGeneratorOptions = {
+    readonly length: number;
+    readonly isUppercaseLettersIncluded: boolean;
+    readonly isLowercaseLettersIncluded: boolean;
+    readonly isNumbersIncluded: boolean;
+    readonly isSpecialCharactersIncluded: boolean;
+};
+
+/**
+ * Names of the configurable character categories.
+ *
+ * @private utility of <PasswordGeneratorDialog/>
  */
-const GENERATED_PASSWORD_LENGTH = 20;
+export type PasswordCharacterOptionName = Exclude<keyof PasswordGeneratorOptions, 'length'>;
 
 /**
- * Characters used by generated passwords.
+ * Default configuration for securely generated passwords.
+ *
+ * @private utility of <PasswordGeneratorDialog/>
  */
-const GENERATED_PASSWORD_CHARACTERS = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz23456789!@#$%^&*+-_=~';
+export const DEFAULT_PASSWORD_GENERATOR_OPTIONS: PasswordGeneratorOptions = {
+    length: 16,
+    isUppercaseLettersIncluded: true,
+    isLowercaseLettersIncluded: true,
+    isNumbersIncluded: true,
+    isSpecialCharactersIncluded: true,
+};
+
+/**
+ * Character categories that can be included in a generated password.
+ *
+ * @private utility of <PasswordGeneratorDialog/>
+ */
+export const PASSWORD_CHARACTER_OPTION_NAMES: ReadonlyArray<PasswordCharacterOptionName> = [
+    'isUppercaseLettersIncluded',
+    'isLowercaseLettersIncluded',
+    'isNumbersIncluded',
+    'isSpecialCharactersIncluded',
+];
+
+/**
+ * Character sets used for the configurable password categories.
+ */
+const PASSWORD_CHARACTERS_BY_OPTION_NAME: Readonly<Record<PasswordCharacterOptionName, string>> = {
+    isUppercaseLettersIncluded: 'ABCDEFGHJKLMNPQRSTUVWXYZ',
+    isLowercaseLettersIncluded: 'abcdefghijkmnopqrstuvwxyz',
+    isNumbersIncluded: '23456789',
+    isSpecialCharactersIncluded: '!@#$%^&*+-_=~',
+};
+
+/**
+ * Obtains one unbiased random index from a character set using the browser Web Crypto API.
+ *
+ * @private utility of generateSecurePassword
+ */
+function getSecureRandomIndex(secureRandomSource: Crypto, characterCount: number): number {
+    const largestAcceptableRandomValue = Math.floor(0x1_0000_0000 / characterCount) * characterCount;
+    const randomValues = new Uint32Array(1);
+
+    let randomValue: number | undefined;
+
+    do {
+        secureRandomSource.getRandomValues(randomValues);
+        randomValue = randomValues[0];
+    } while (randomValue === undefined || randomValue >= largestAcceptableRandomValue);
+
+    return randomValue % characterCount;
+}
+
+/**
+ * Randomly reorders password characters with the Fisher-Yates algorithm.
+ *
+ * @private utility of generateSecurePassword
+ */
+function shufflePasswordCharacters(passwordCharacters: Array<string>, secureRandomSource: Crypto): void {
+    for (let index = passwordCharacters.length - 1; index > 0; index--) {
+        const randomIndex = getSecureRandomIndex(secureRandomSource, index + 1);
+        const currentPasswordCharacter = passwordCharacters[index];
+        const randomPasswordCharacter = passwordCharacters[randomIndex];
+
+        if (currentPasswordCharacter === undefined || randomPasswordCharacter === undefined) {
+            continue;
+        }
+
+        passwordCharacters[index] = randomPasswordCharacter;
+        passwordCharacters[randomIndex] = currentPasswordCharacter;
+    }
+}
 
 /**
  * Generates a password using the browser Web Crypto API.
  *
- * Rejection sampling keeps every character equally likely even though the
- * alphabet length is not a power of two.
+ * Rejection sampling keeps every selected character equally likely even when
+ * the character-set length is not a power of two. Every selected character
+ * category is guaranteed to occur at least once.
  *
- * @returns A cryptographically random password, or an empty string when a secure random source is unavailable.
+ * @param options - Length and character categories to use for the password.
+ * @returns A cryptographically random password, or an empty string when the configuration is invalid or a secure random source is unavailable.
  *
- * @private utility of <CreateUserDialog/>
+ * @private utility of <PasswordGeneratorDialog/>
  */
-export function generateSecurePassword(): string {
+export function generateSecurePassword(options: PasswordGeneratorOptions = DEFAULT_PASSWORD_GENERATOR_OPTIONS): string {
     const secureRandomSource = globalThis.crypto;
 
     if (!secureRandomSource?.getRandomValues) {
         return '';
     }
 
-    const characterCount = GENERATED_PASSWORD_CHARACTERS.length;
-    const largestAcceptableRandomValue = Math.floor(0x1_0000_0000 / characterCount) * characterCount;
-    const passwordCharacters: Array<string> = [];
-    const randomValues = new Uint32Array(64);
+    const characterSets = PASSWORD_CHARACTER_OPTION_NAMES.filter((optionName) => options[optionName]).map(
+        (optionName) => PASSWORD_CHARACTERS_BY_OPTION_NAME[optionName],
+    );
 
-    while (passwordCharacters.length < GENERATED_PASSWORD_LENGTH) {
-        secureRandomSource.getRandomValues(randomValues);
+    if (!Number.isSafeInteger(options.length) || options.length < characterSets.length || characterSets.length === 0) {
+        return '';
+    }
 
-        for (const randomValue of randomValues) {
-            if (randomValue >= largestAcceptableRandomValue) {
-                continue;
-            }
+    const allPasswordCharacters = characterSets.join('');
+    const passwordCharacters: Array<string> = [];
 
-            passwordCharacters.push(GENERATED_PASSWORD_CHARACTERS.charAt(randomValue % characterCount));
+    for (const characterSet of characterSets) {
+        passwordCharacters.push(characterSet.charAt(getSecureRandomIndex(secureRandomSource, characterSet.length)));
+    }
 
-            if (passwordCharacters.length === GENERATED_PASSWORD_LENGTH) {
-                break;
-            }
-        }
+    while (passwordCharacters.length < options.length) {
+        passwordCharacters.push(
+            allPasswordCharacters.charAt(getSecureRandomIndex(secureRandomSource, allPasswordCharacters.length)),
+        );
     }
 
+    shufflePasswordCharacters(passwordCharacters, secureRandomSource);
+
     return passwordCharacters.join('');
 }

package/apps/agents-server/src/components/UsersList/userDialogClassNames.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared secondary-button styling used by the user-management dialogs.
+ */
+export const USER_DIALOG_SECONDARY_BUTTON_CLASS_NAME =
+    'inline-flex items-center justify-center gap-2 rounded-md border border-gray-300 bg-white px-3 py-2 text-sm font-semibold text-gray-700 hover:bg-gray-50 disabled:cursor-not-allowed disabled:opacity-60';
+
+/**
+ * Shared primary-button styling used by the user-management dialogs.
+ */
+export const USER_DIALOG_PRIMARY_BUTTON_CLASS_NAME =
+    'inline-flex items-center justify-center gap-2 rounded-md bg-blue-600 px-3 py-2 text-sm font-semibold text-white hover:bg-blue-700 disabled:cursor-not-allowed disabled:opacity-60';

package/apps/agents-server/src/languages/ServerTranslationKeys.ts

@@ -437,7 +437,18 @@ export const SERVER_TRANSLATION_KEYS = [
     'users.passwordPlaceholder',
     'users.passwordAriaLabel',
     'users.generatePassword',
+    'users.passwordGeneratorTitle',
+    'users.closePasswordGeneratorDialog',
     'users.passwordGeneratorDescription',
+    'users.passwordGeneratorLength',
+    'users.passwordGeneratorCharacters',
+    'users.passwordGeneratorIncludeUppercaseLetters',
+    'users.passwordGeneratorIncludeLowercaseLetters',
+    'users.passwordGeneratorIncludeNumbers',
+    'users.passwordGeneratorIncludeSpecialCharacters',
+    'users.generatedPassword',
+    'users.regeneratePassword',
+    'users.useGeneratedPassword',
     'users.isAdminCheckbox',
     'users.adminRoleDescription',
     'users.createUser',

package/apps/agents-server/src/languages/translations/czech.yaml

@@ -431,7 +431,18 @@ users.passwordLabel: Heslo
 users.passwordPlaceholder: Heslo
 users.passwordAriaLabel: Heslo
 users.generatePassword: Vygenerovat bezpečné heslo
+users.passwordGeneratorTitle: Generátor hesla
+users.closePasswordGeneratorDialog: Zavřít generátor hesla
 users.passwordGeneratorDescription: Používá bezpečný generátor náhodných hodnot vašeho prohlížeče.
+users.passwordGeneratorLength: Délka hesla
+users.passwordGeneratorCharacters: Zahrnout znaky
+users.passwordGeneratorIncludeUppercaseLetters: Zahrnout velká písmena
+users.passwordGeneratorIncludeLowercaseLetters: Zahrnout malá písmena
+users.passwordGeneratorIncludeNumbers: Zahrnout čísla
+users.passwordGeneratorIncludeSpecialCharacters: Zahrnout speciální znaky
+users.generatedPassword: Vygenerované heslo
+users.regeneratePassword: Vygenerovat jiné heslo
+users.useGeneratedPassword: Použít vygenerované heslo
 users.isAdminCheckbox: Administrátor
 users.adminRoleDescription: Správci mohou spravovat tento server a jeho uživatele.
 users.createUser: Vytvořit uživatele

package/apps/agents-server/src/languages/translations/english.yaml

@@ -435,7 +435,18 @@ users.passwordLabel: Password
 users.passwordPlaceholder: Password
 users.passwordAriaLabel: Password
 users.generatePassword: Generate secure password
+users.passwordGeneratorTitle: Password generator
+users.closePasswordGeneratorDialog: Close password generator
 users.passwordGeneratorDescription: Uses your browser's secure random generator.
+users.passwordGeneratorLength: Password length
+users.passwordGeneratorCharacters: Include characters
+users.passwordGeneratorIncludeUppercaseLetters: Include uppercase letters
+users.passwordGeneratorIncludeLowercaseLetters: Include lowercase letters
+users.passwordGeneratorIncludeNumbers: Include numbers
+users.passwordGeneratorIncludeSpecialCharacters: Include special characters
+users.generatedPassword: Generated password
+users.regeneratePassword: Generate another password
+users.useGeneratedPassword: Use generated password
 users.isAdminCheckbox: Is Admin
 users.adminRoleDescription: Administrators can manage this server and its users.
 users.createUser: Create User

package/apps/agents-server/src/utils/agentProjects/agentProjectHrefs.ts

@@ -43,6 +43,17 @@ export function buildAgentProjectProfileHref(agentPermanentId: string, projectNa
     return `${buildAgentProjectsDashboardHref(agentPermanentId)}/${encodeURIComponent(projectName)}`;
 }
 
+/**
+ * Builds the href prefix serving files from one agent project.
+ *
+ * @param agentPermanentId - Permanent id of the agent.
+ * @param projectName - Project directory name.
+ * @returns Project file href prefix.
+ */
+export function buildAgentProjectFilesHrefPrefix(agentPermanentId: string, projectName: string): string {
+    return `${buildAgentProjectProfileHref(agentPermanentId, projectName)}/files/`;
+}
+
 /**
  * Builds the href of one project on its owning server.
  *

package/apps/agents-server/src/utils/agentProjects/createAgentProjectDnsRecords.ts

@@ -33,19 +33,52 @@ export type AgentProjectDnsRecord = {
 };
 
 /**
- * Creates the one DNS record shown for a selected project-domain setup.
+ * Placeholder used when preventive project DNS guidance has no assigned project domain yet.
  *
- * @param options - Project domain, server domain, and selected DNS variants.
- * @returns One DNS record instruction.
+ * @private helper for the Agents Server project DNS instructions
+ */
+const PROJECT_DOMAIN_NAME_PLACEHOLDER = '<PROJECT_NAME>';
+
+/**
+ * Inputs used to create one project DNS record instruction.
+ *
+ * @private helper for the Agents Server project DNS instructions
  */
-export function createAgentProjectDnsRecord(options: {
+type CreateAgentProjectDnsRecordOptions = {
+    /**
+     * Whether the resulting DNS record should be a CNAME instead of an A record.
+     */
     readonly isCnameRecord: boolean;
+
+    /**
+     * Whether the resulting DNS record should cover every generated project domain.
+     */
     readonly isWildcardDomain: boolean;
-    readonly projectDomain: string;
+
+    /**
+     * Assigned project hostname used by the single-project variant, when available.
+     */
+    readonly projectDomain?: string | null;
+
+    /**
+     * Public VPS IP address used by the A-record variant, when known.
+     */
     readonly publicIpAddress: string | null | undefined;
+
+    /**
+     * Base server domain used by generated project hostnames.
+     */
     readonly serverDomain: string;
-}): AgentProjectDnsRecord {
-    const name = options.isWildcardDomain ? `*.${options.serverDomain}` : options.projectDomain;
+};
+
+/**
+ * Creates the one DNS record shown for a selected project-domain setup.
+ *
+ * @param options - Project domain, server domain, and selected DNS variants.
+ * @returns One DNS record instruction.
+ */
+export function createAgentProjectDnsRecord(options: CreateAgentProjectDnsRecordOptions): AgentProjectDnsRecord {
+    const name = createAgentProjectDnsRecordName(options);
 
     if (options.isCnameRecord) {
         return {
@@ -65,3 +98,16 @@ export function createAgentProjectDnsRecord(options: {
             : 'Replace <VPS_PUBLIC_IP> with the public IP address of this VPS.',
     };
 }
+
+/**
+ * Resolves the DNS hostname displayed for one project DNS record instruction.
+ *
+ * @private helper for createAgentProjectDnsRecord
+ */
+function createAgentProjectDnsRecordName(options: CreateAgentProjectDnsRecordOptions): string {
+    if (options.isWildcardDomain) {
+        return `*.${options.serverDomain}`;
+    }
+
+    return options.projectDomain || `${PROJECT_DOMAIN_NAME_PLACEHOLDER}.${options.serverDomain}`;
+}

package/apps/agents-server/src/utils/agentProjects/createAgentProjectMarkdownReferences.ts

@@ -1,6 +1,6 @@
 import type { MarkdownInlineReference } from '@promptbook-local/types';
 import type { AgentProjectReferenceInfo } from './AgentProjectReferenceInfo';
-import { buildAgentProjectProfileHref } from './agentProjectHrefs';
+import { buildAgentProjectFilesHrefPrefix, buildAgentProjectProfileHref } from './agentProjectHrefs';
 
 /**
  * Markdown inline reference data consumed by chat markdown rendering.
@@ -39,31 +39,41 @@ type AgentProjectMarkdownReferenceInfo = Pick<
 export function createAgentProjectMarkdownReferences(
     options: CreateAgentProjectMarkdownReferencesOptions,
 ): ReadonlyArray<AgentProjectMarkdownReference> {
-    return options.projects.map((project) => ({
-        reference: project.projectName,
-        label: project.displayName || project.projectName,
-        href: buildAgentProjectProfileHref(options.agentPermanentId, project.projectName),
-        title: project.description || project.displayName || project.projectName,
-        menu: {
-            status: {
-                label: project.isRunning ? 'Project is running' : 'Project is not running',
-                isActive: project.isRunning ?? false,
-            },
-            options: [
-                {
-                    label: 'Open the project in a new tab',
-                    href: project.isRunning ? project.projectUrl ?? null : null,
-                    title:
-                        project.isRunning && project.projectUrl
-                            ? 'Open the project in a new tab'
-                            : 'The project must run before it can be opened.',
-                },
-                {
-                    label: 'Open the project page in a new tab',
-                    href: buildAgentProjectProfileHref(options.agentPermanentId, project.projectName),
-                    title: 'Open the project page in a new tab',
-                },
+    return options.projects.map((project) => {
+        const projectProfileHref = buildAgentProjectProfileHref(options.agentPermanentId, project.projectName);
+        const projectUrl = project.projectUrl || null;
+
+        return {
+            reference: project.projectName,
+            label: project.displayName || project.projectName,
+            href: projectProfileHref,
+            sourceHrefPrefixes: [
+                projectProfileHref,
+                buildAgentProjectFilesHrefPrefix(options.agentPermanentId, project.projectName),
+                ...(projectUrl ? [projectUrl] : []),
             ],
-        },
-    }));
+            title: project.description || project.displayName || project.projectName,
+            menu: {
+                status: {
+                    label: project.isRunning ? 'Project is running' : 'Project is not running',
+                    isActive: project.isRunning ?? false,
+                },
+                options: [
+                    {
+                        label: 'Open the project in a new tab',
+                        href: project.isRunning ? projectUrl : null,
+                        title:
+                            project.isRunning && projectUrl
+                                ? 'Open the project in a new tab'
+                                : 'The project must run before it can be opened.',
+                    },
+                    {
+                        label: 'Open the project page in a new tab',
+                        href: projectProfileHref,
+                        title: 'Open the project page in a new tab',
+                    },
+                ],
+            },
+        };
+    });
 }

package/apps/agents-server/src/utils/manGoOnboarding/manGoOnboardingAgentBooks.ts

@@ -1,18 +1,7 @@
 import { spaceTrim } from 'spacetrim';
 
 /**
- * Agent book copied from the manGo onboarding experiment and used as the drafting specialist.
- *
- * @private internal constant of manGo onboarding agent utilities
- */
-export const MAN_GO_DRAFT_EXPERT_BOOK = spaceTrim(`
-    Book language expert
-
-    LANGUAGE Čeština
-`);
-
-/**
- * Agent book copied from the manGo onboarding experiment and used to convert free-form drafts to Book language.
+ * Agent book copied from the manGo onboarding experiment and used to generate Book language directly.
  *
  * @private internal constant of manGo onboarding agent utilities
  */
@@ -22,7 +11,7 @@ export const MAN_GO_BOOK_EXPERT_BOOK = spaceTrim(`
     PERSONA You are expert in book language
     RULE You can work with the book language and write, modify, or consult the agents based on the book language.
 
-    KNOWLEDGE https://core.ptbk.io/api/docs/book-language.md
+    KNOWLEDGE https://live.ptbk.io/api/docs/book-language.md?language=en
 
     RULE When creating agents, use code blocks with book language:
 

package/apps/agents-server/src/utils/manGoOnboarding/manGoOnboardingAgentRuntime.ts

@@ -5,11 +5,7 @@ import { LiteAgent } from '../../../../../src/book-3.0/LiteAgent';
 import type { string_markdown } from '../../../../../src/types/string_markdown';
 import { validateBook } from '../../../../../src/book-2.0/agent-source/string_book';
 import { spaceTrim } from 'spacetrim';
-import {
-    MAN_GO_BOOK_EXPERT_BOOK,
-    MAN_GO_DRAFT_EXPERT_BOOK,
-    MAN_GO_REPLY_REVIEWER_BOOK,
-} from './manGoOnboardingAgentBooks';
+import { MAN_GO_BOOK_EXPERT_BOOK, MAN_GO_REPLY_REVIEWER_BOOK } from './manGoOnboardingAgentBooks';
 
 /**
  * Chat message accepted by the manGo onboarding test runner.
@@ -36,20 +32,13 @@ export type ManGoOnboardingReplyCheck = {
 };
 
 /**
- * Inputs used to generate the first editable Book draft.
+ * Inputs used to generate the first editable Book.
  */
-export type GenerateManGoBookDraftInput = {
+export type GenerateManGoBookInput = {
     readonly agentName: string;
     readonly agentBrief: string;
 };
 
-/**
- * Input used by the Book language conversion panel.
- */
-export type ConvertManGoDraftToBookInput = {
-    readonly input: string;
-};
-
 /**
  * Input used by the step 4 live agent test.
  */
@@ -69,7 +58,7 @@ export type EvaluateManGoAgentReplyInput = {
 };
 
 /**
- * Fallback source used when step 4 is called before the draft exists.
+ * Fallback source used when step 4 is called before the Book exists.
  *
  * @private internal constant of manGo onboarding agent utilities
  */
@@ -121,24 +110,27 @@ function extractSingleBlockContent(response: string): string {
 }
 
 /**
- * Creates a prompt that asks the imported draft expert for a real Book-language draft.
+ * Creates a prompt that asks the imported Book expert for a complete Book-language source.
  *
  * @param input - Wizard name and brief.
- * @returns Prompt for the draft expert agent.
+ * @returns Prompt for the Book expert agent.
  *
  * @private internal utility of manGo onboarding agent utilities
  */
-function createBookDraftPrompt(input: GenerateManGoBookDraftInput): string {
+function createBookPrompt(input: GenerateManGoBookInput): string {
     return spaceTrim(`
-        Write an editable Promptbook Book-language draft for an AI agent.
+        Create a complete Promptbook Book-language source for one AI agent.
 
         Return only one \`book\` code block. Do not include any explanation outside the block.
+        This source is the final editable Book.
 
         Requirements:
         - Use the provided name as the agent title.
         - Write natural-language commitments in Czech unless the brief clearly asks for another language.
-        - Include a useful PERSONA, GOAL, and practical RULE commitments derived from the brief.
+        - Include a useful PERSONA, GOAL, and practical RULE commitments derived from the description.
         - Keep commitment keywords in English.
+        - Use Book-language commitments such as WRITING SAMPLE, WRITING RULES, MESSAGE SUFFIX, and NOTE when they fit the agent.
+        - Do not use Markdown headings such as \`##\` as a substitute for Book-language commitments.
         - End the book with CLOSED.
 
         Name: ${input.agentName}
@@ -147,86 +139,42 @@ function createBookDraftPrompt(input: GenerateManGoBookDraftInput): string {
 }
 
 /**
- * Creates a first editable Book draft through the imported manGo onboarding AI agent.
+ * Creates the first editable Book through the imported manGo onboarding AI agent.
  *
  * @param input - Agent name and brief captured by the entry step.
  * @returns Editable Book source for the next wizard steps.
  */
-export async function generateManGoBookDraft(input: GenerateManGoBookDraftInput): Promise<string> {
+export async function generateManGoBook(input: GenerateManGoBookInput): Promise<string> {
     const agentName = input.agentName.trim();
     const agentBrief = input.agentBrief.trim();
 
     if (!agentName || !agentBrief) {
         throw new NotAllowed(
             spaceTrim(`
-                Cannot generate a manGo Book draft without both \`agentName\` and \`agentBrief\`.
+                Cannot generate a manGo Book without both \`agentName\` and \`agentBrief\`.
 
-                Fill in the onboarding assignment before generating the draft.
+                Fill in the onboarding assignment before generating the Book.
             `),
         );
     }
 
     const response = await runManGoLiteAgent({
-        bookSource: MAN_GO_DRAFT_EXPERT_BOOK,
-        message: createBookDraftPrompt({ agentName, agentBrief }),
+        bookSource: MAN_GO_BOOK_EXPERT_BOOK,
+        message: createBookPrompt({ agentName, agentBrief }),
     });
     const book = extractSingleBlockContent(response);
 
     if (!book) {
         throw new PipelineExecutionError(
             spaceTrim(`
-                The manGo draft expert returned an empty Book draft.
+                The manGo Book expert returned an empty Book.
 
-                Try regenerating the draft from the onboarding step.
+                Try generating the Book again from the onboarding step.
             `),
         );
     }
 
-    return book;
-}
-
-/**
- * Converts free-form draft text into canonical Book language through the imported book expert.
- *
- * @param input - Free-form editor content.
- * @returns Generated Book source and validation flag.
- */
-export async function convertManGoDraftToBook(
-    input: ConvertManGoDraftToBookInput,
-): Promise<{ readonly book: string; readonly isValid: boolean }> {
-    const normalizedInput = input.input.trim();
-
-    if (!normalizedInput) {
-        throw new NotAllowed(
-            spaceTrim(`
-                Cannot convert an empty draft to Book language.
-
-                Add draft content before running the manGo Book conversion.
-            `),
-        );
-    }
-
-    const response = await runManGoLiteAgent({
-        bookSource: MAN_GO_BOOK_EXPERT_BOOK,
-        message: spaceTrim(`
-            Create a book that defines an agent with the following input:
-
-            Wrap the output in a single \`book\` code block.
-
-            Input:
-            ${normalizedInput}
-        `),
-    });
-    const book = extractSingleBlockContent(response);
-
-    let isValid = true;
-    try {
-        validateBook(book);
-    } catch {
-        isValid = false;
-    }
-
-    return { book, isValid };
+    return validateBook(book);
 }
 
 /**

package/apps/agents-server/src/utils/stalwart/createEmailDnsInstructions.ts

@@ -1,4 +1,5 @@
 import type { DnsRecordInstruction } from '../dnsRecords/DnsRecordInstruction';
+import { buildStalwartMailServerHostname } from './stalwartMailBridge';
 
 /**
  * One DNS record required or recommended for reliable mail delivery.
@@ -15,18 +16,21 @@ export type EmailDnsInstruction = DnsRecordInstruction & {
  *
  * DKIM records are intentionally read from Stalwart's generated zone because their public keys must never be guessed.
  */
-export function createEmailDnsInstructions(domain: string): EmailDnsInstruction[] {
+export function createEmailDnsInstructions(domain: string, publicIpAddress?: string | null): EmailDnsInstruction[] {
+    const mailServerHostname = buildStalwartMailServerHostname(domain);
+    const resolvedPublicIpAddress = publicIpAddress?.trim() || '<VPS_PUBLIC_IP>';
+
     return [
         {
             type: 'A',
-            name: `mail.${domain}`,
-            value: '<VPS_PUBLIC_IP>',
+            name: mailServerHostname,
+            value: resolvedPublicIpAddress,
             note: 'Mail server host. Use the same public IPv4 address as this VPS.',
         },
         {
             type: 'MX',
             name: domain,
-            value: `10 mail.${domain}.`,
+            value: `10 ${mailServerHostname}.`,
             note: 'Routes inbound mail for the Agents Server domain to Stalwart.',
         },
         {
@@ -50,7 +54,7 @@ export function createEmailDnsInstructions(domain: string): EmailDnsInstruction[
         {
             type: 'A',
             name: `mta-sts.${domain}`,
-            value: '<VPS_PUBLIC_IP>',
+            value: resolvedPublicIpAddress,
             note: 'Hosts the HTTPS MTA-STS policy for this mail domain.',
         },
         {