@dokebi/cli 0.4.1 → 0.4.26

package/dist/project.js

@@ -1,36 +1,310 @@
 import { randomBytes } from 'node:crypto';
-import { mkdir, mkdtemp, readdir, readFile, realpath, rename, rm, rmdir, writeFile, } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
-import { parseEnv } from 'node:util';
+import { copyFile, lstat, mkdir, mkdtemp, readdir, readFile, realpath, rename, rm, rmdir, writeFile, } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { RELOAD_OPTIONS_KEY, reloadOptions } from '@dokebi/core';
 import lt from 'semver/functions/lt.js';
 import satisfies from 'semver/functions/satisfies.js';
+import validVersion from 'semver/functions/valid.js';
 import validRange from 'semver/ranges/valid.js';
 import { parse } from 'yaml';
-import { HOST_CAPABILITY, loadCatalog, providersOf } from './catalog.js';
-import { applyConfigChanges, applySetOptions, markRemoved, removeAppSettings, setWarnings, } from './config-edit.js';
-import { CONFIG_BACKUP, CONFIG_EXAMPLE, CONFIG_FILE, CONFIG_TEMPLATE, ignoreConfig, LEGACY_CONFIG_FILE, migrateConfig, parseProjectConfig, } from './configuration.js';
-import { scaffoldConfig } from './configuration-scaffold.js';
-import { COMPOSE_FILE, composeProject, composeText, connectionUrl, DB_SERVICE, ENV_FILE, envValue, FALLBACK_PROJECT_NAME, freePortAfter, generatePassword, PASSWORD_VARIABLE, portInUse, portQuestion, redactUrl, URL_PLACEHOLDER_PREFIX, withEnv, } from './dev-infra.js';
+import { apiAppFiles } from './api-app.js';
+import { capabilityBlock, syncCapabilityBlock } from './capability-guide.js';
+import { findPackage, HOST_CAPABILITY, loadCatalog, providersOf, } from './catalog.js';
+import { sampleAdditions } from './config-diff.js';
+import { applyConfigChanges, applySetOptions, applyUnsetOptions, markRemoved, namedItems, optionAtPath, removeAppSettings, } from './config-edit.js';
+import { isPlaceholder, issuePathOf, placeholderPaths, secretInSchema } from './config-init.js';
+import { filePaths, outsideRequested, requestedPath } from './config-paths.js';
+import { commandLineSecret } from './config-show.js';
+import { addLoggingTargets, CONFIG_BACKUP, CONFIG_EXAMPLE, CONFIG_FILE, CONFIG_TEMPLATE, configOutsideProject, configTarget, FRESH_COPY_FIX, ignoreConfig, LEGACY_CONFIG_FILE, migrateConfig, parseProjectConfig, readProjectSettings, } from './configuration.js';
+import { aliasConflicts, followDefaults, pruneUndeclared, scaffoldConfig, } from './configuration-scaffold.js';
+import { DEPLOYMENT_FILES } from './deployment.js';
+import { connectionSecrets } from './dev-compose.js';
+import { AUTO_DOMAIN, devHost, projectHostLabel } from './dev-host.js';
+import { COMPOSE_FILE, composeProject, composePublishedPort, composeText, composeUnsetVariables, composeVariablesHint, connectionUrl, DB_SERVICE, ENV_FILE, envKeys, envValue, FALLBACK_PROJECT_NAME, freePortAfter, generatePassword, PASSWORD_VARIABLE, portInUse, portQuestion, redactUrl, replicaSetOf, runsReplicaSet, URL_PLACEHOLDER_PREFIX, withComposePort, withEnv, } from './dev-infra.js';
 import { debug, describeError, isMissing } from './diagnostics.js';
-import { checkEnvText } from './env-file.js';
+import { envFileWarnings, parseEnvText } from './env-file.js';
 import { CliError } from './errors.js';
 import { markExampleRemoved, syncExample } from './example-config.js';
 import { exists, fingerprint, hash, json, object, parseObject, securePath, templateTarget, } from './filesystem.js';
-import { generateRegistration, LEGACY_MAIN_SOURCE, MAIN_SOURCE, MAIN_SOURCE_V1, PROJECT_DEV_DEPENDENCIES, TSCONFIG_SOURCE, TYPECHECK_SCRIPT, } from './generator.js';
-import { findHost, HOST_ROLES, orderPlugins, PACKAGE_NAME, readManifest, } from './manifest.js';
+import { adminSections } from './first-admin.js';
+import { biomeConfigText, biomeMajor, formatterFix, formatterUses, GENERATED_FILE, migrationsFolder, PRETTIER_IGNORE, prettierIgnoreText, } from './formatter-ignore.js';
+import { generateRegistration, LEGACY_MAIN_SOURCE, MAIN_SOURCE, MAIN_SOURCE_V1, MAIN_SOURCE_V2, MAIN_SOURCE_V3, MAIN_SOURCE_V4, MAIN_SOURCE_V5, PROJECT_DEV_DEPENDENCIES, TEST_SCRIPT, TSCONFIG_SOURCE, TYPECHECK_SCRIPT, } from './generator.js';
+import { findHost, HOST_ROLES, missingDependency, optionsKey, orderPlugins, PACKAGE_NAME, readManifest, } from './manifest.js';
 import { mergeInstallDefaults } from './merge-install-defaults.js';
-import { dependencyMap, NpmClient, packageSpec, stageNpmConfig, validateProjectPackage, } from './npm-client.js';
+import { dependencyMap, NpmClient, packageSpec, projectTarball, stageNpmConfig, validateProjectPackage, } from './npm-client.js';
+import { optionsFix, unknownOptionPaths } from './option-fixes.js';
 import { CLI_VERSION } from './output.js';
-import { checkAll, optionsOf, planLifecycle, } from './plugin-lifecycle.js';
+import { checkAll, checkPluginsOptions, optionsOf, planLifecycle, } from './plugin-lifecycle.js';
 import { PluginOptionsValidator, validatePluginOptions } from './plugin-options.js';
-import { AGENTS_FILE, CLAUDE_FILE, CLAUDE_GUIDE, guideEntries, installedBlock, projectGuide, replaceInstalledBlock, } from './project-guide.js';
+import { AGENTS_FILE, CLAUDE_FILE, CLAUDE_GUIDE, guideEntries, installedBlock, projectBlockState, projectGuide, replaceInstalledBlock, withProjectBlock, } from './project-guide.js';
 import { APP_NAME, defaultInstallation, emptyState, readState, } from './project-state.js';
-import { resolveVersion } from './registry.js';
+import { companionVersions, conflictFix, describeConflicts, fetchPackument, missingOnRegistry, resolveVersion, versionConflicts, } from './registry.js';
+import { markReloadable, reloadSchemas } from './reloadable.js';
 import { readRequiredPlugins } from './required-plugins.js';
-import { Transaction } from './transaction.js';
+import { CONVENTION_SECTIONS, catalogPackageOf, RESERVED_SECTIONS, renderSettingsSchema, renderSettingsSchemaFrom, SETTINGS_FOLDER, SETTINGS_SECTION, settingsFile, settingsIdentifier, settingsSchemaFile, settingsSource, undeclaredSection, undeclaredSectionError, } from './settings.js';
+import { templateFixes } from './template-fixes.js';
+import { Interruption, interruptedError, Transaction } from './transaction.js';
+import { appViewValue, NO_VIEW, projectView } from './view-choice.js';
 import { installedPath, packageFile, workspacePackages, workspaceRootOf, } from './workspace.js';
 const GENERATED = 'src/dokebi.generated.ts';
 const EXAMPLE = 'dokebi.example.yaml';
+/** Previous secrets `config secret --rotate` keeps after the new one in a list (AI-M05). */
+/** An option key that holds an address (`url`, `uri`, `databaseUrl`, `endpointURI`). */
+const URL_KEY = /^(url|uri)$|(Url|URL|Uri|URI)$/;
+export const ROTATE_KEEP = 2;
+/** The generated registration differs from what the CLI wrote (D-0116: a sentence and a fix). */
+function modifiedRegistration() {
+    return new CliError('MODIFIED_REGISTRATION', `${GENERATED} was edited by hand; the CLI writes it and does not change a project whose registration differs`, {
+        details: {
+            path: GENERATED,
+            fix: `undo the edits to ${GENERATED} (for example from Git) and put your own code in src/main.ts or a plugin entry file, then repeat this command`,
+        },
+        phase: 'plan',
+    });
+}
+/**
+ * PACKAGE_CONFLICT (D-0116): package.json already depends on the npm package of a plugin the
+ * project has not registered, so the CLI does not take it over silently.
+ */
+function packageConflict(name, range, requiredBy) {
+    return new CliError('PACKAGE_CONFLICT', `package.json already depends on ${name} (${range}), but it is not a registered plugin of this project${requiredBy ? `; ${requiredBy} requires it` : ''}`, {
+        details: {
+            package: name,
+            range,
+            ...(requiredBy ? { requiredBy } : {}),
+            fix: `npm uninstall ${name}, then npx dokebi add ${name} (the CLI installs and registers it in one transaction)`,
+        },
+        phase: 'plan',
+    });
+}
+/** REVERSE_DEPENDENCY (D-0116): `dependents` still require the plugin `remove` was asked for. */
+function reverseDependency(id, dependents) {
+    return new CliError('REVERSE_DEPENDENCY', `${id} cannot be removed: ${dependents.join(', ')} ${dependents.length === 1 ? 'requires' : 'require'} it`, {
+        details: {
+            plugin: dependents[0],
+            dependents,
+            requires: [id],
+            fix: `first run ${dependents.map((item) => `npx dokebi remove ${item}`).join(', ')}, or keep ${id}`,
+        },
+        phase: 'plan',
+    });
+}
+/**
+ * MANIFEST_CHANGED during a change (D-0116): npm put another manifest of a registered plugin into
+ * the staged install than the one the project records.
+ */
+function stagedManifestChanged(plugin, actual) {
+    return new CliError('MANIFEST_CHANGED', `npm installed ${plugin.packageName} ${actual.version} for this change, but the project records ${plugin.id} ${plugin.version} with another manifest`, {
+        details: {
+            plugin: plugin.id,
+            recorded: plugin.version,
+            staged: actual.version,
+            fix: `npx dokebi upgrade ${plugin.id} first (or pin ${plugin.packageName} to ${plugin.version} in package.json), then repeat this command`,
+        },
+        phase: 'plan',
+    });
+}
+/** INVALID_PLUGIN_OPTIONS (D-0116): options of a plugin break its schema (not only missing). */
+function invalidPluginOptions(id, errors, phase, 
+/** The section of dokebi.yaml (options.logging for the logger host); `id` names the plugin. */
+section = id, 
+/** D-0162: `rules` for the plugin's own checks (the schema passed); their message is said. */
+broken = 'schema', 
+/** The options schema: the fix says what the refused field expects (community request D3). */
+schema) {
+    const first = errors[0];
+    const where = first
+        ? `options.${section}${first.instancePath.replaceAll('/', '.')} (${broken === 'rules' && first.message ? first.message : first.keyword})`
+        : `options.${section}`;
+    return new CliError('INVALID_PLUGIN_OPTIONS', `The options of ${id} do not match its ${broken === 'rules' ? 'rules (the app refuses them at start)' : 'schema'}: ${where}${errors.length > 1 ? ` (and ${errors.length - 1} more)` : ''}`, {
+        details: {
+            plugin: id,
+            errors: errors.slice(0, 20),
+            errorCount: errors.length,
+            // D-0153: unknown keys get `config unset`, moved ones where they went.
+            fix: optionsFix(id, errors, `correct options.${section} in dokebi.yaml (npx dokebi config set ${section}.<path>=<value>; npx dokebi plugins info ${id} --json lists the option keys)`, section, schema),
+        },
+        phase,
+    });
+}
+/**
+ * INVALID_PLUGIN_OPTIONS for an old option name set together with the field it now sets (D-0071):
+ * the schema takes both, the plugin's options parser refuses them at start (`conflict`).
+ */
+function aliasConflictError(id, section, conflicts) {
+    const [first] = conflicts;
+    return new CliError('INVALID_PLUGIN_OPTIONS', `options.${section}.${first?.alias} is the old name of ${first?.field}; ${id} refuses both set at start${conflicts.length > 1 ? ` (and ${conflicts.length - 1} more)` : ''}`, {
+        details: {
+            plugin: id,
+            errors: conflicts.map((conflict) => ({
+                instancePath: `/${conflict.alias.replaceAll('.', '/')}`,
+                keyword: 'conflict',
+                field: `${section}.${conflict.field}`,
+            })),
+            errorCount: conflicts.length,
+            fix: `keep one name: npx dokebi config unset ${conflicts.map((conflict) => `${section}.${conflict.alias}`).join(' ')} (the old name; its value then comes from the new one, so set that first if it should stay)`,
+        },
+        phase: 'arguments',
+    });
+}
+/**
+ * AI-M49 D2: `settings sync` with options the new schema refuses (a value set by hand above a
+ * lowered maximum): the code doctor gives them, with the paths and a fix that works before the
+ * sync (config set checks the old schema until then); nothing is written.
+ */
+function settingsStillInvalid(section, errors, configFile) {
+    const paths = [
+        ...new Set(errors.map((error) => [section, ...error.instancePath.split('/').slice(1), error.additionalProperty ?? '']
+            .filter(Boolean)
+            .join('.'))),
+    ];
+    const first = errors[0];
+    return new CliError('INVALID_PLUGIN_OPTIONS', `The new declaration of ${section} refuses what ${configFile} holds: options.${paths[0] ?? section}${first ? ` (${first.keyword})` : ''}${paths.length > 1 ? ` (and ${paths.length - 1} more)` : ''}; nothing was written`, {
+        details: {
+            plugin: section,
+            errors: errors.slice(0, 20),
+            errorCount: errors.length,
+            paths,
+            fix: `bring each value within the new declaration: npx dokebi config unset ${paths.join(' ')} (the new default then applies), or correct it in ${configFile} by hand; then npx dokebi settings sync again`,
+        },
+        phase: 'plan',
+    });
+}
+/** UNKNOWN_APP (D-0116): the app command names an app the project does not register. */
+function unknownApp(name, apps) {
+    return new CliError('UNKNOWN_APP', `The project has no app named ${name}`, {
+        details: {
+            app: name,
+            apps,
+            fix: apps.length
+                ? `use one of ${apps.join(', ')}, or create it with npx dokebi app add ${name} --domain auto`
+                : `create it with npx dokebi app add ${name} --domain auto`,
+        },
+        phase: 'arguments',
+    });
+}
+/** DOMAIN_IN_USE (D-0116): another app already serves the domain. */
+function domainInUse(domain, app) {
+    return new CliError('DOMAIN_IN_USE', `The domain ${domain} already belongs to the app ${app}`, {
+        details: {
+            domain,
+            app,
+            fix: `choose another domain, or first npx dokebi app unlink ${domain}`,
+        },
+        phase: 'arguments',
+    });
+}
+/** A path of the change that holds something else (D-0116: a sentence, details and a fix). */
+function fileConflict(path, why, fix, extra = {}) {
+    return new CliError('FILE_CONFLICT', `${path} ${why}`, {
+        details: { path, ...extra, fix },
+        phase: 'plan',
+    });
+}
+/** The plugin among `plugins` that declares `id` as a required dependency (D-0116). */
+function requirerOf(plugins, id) {
+    const found = plugins.find((plugin) => plugin.dependencies.some((dependency) => dependency.name === id && !dependency.optional));
+    if (!found)
+        throw new Error(`No plugin of the change requires ${id}`);
+    return found;
+}
+/** The dependency entry by which a plugin of `plugins` requires `id` (D-0116). */
+function declaredDependency(plugins, id) {
+    return requirerOf(plugins, id).dependencies.find((dependency) => dependency.name === id && !dependency.optional);
+}
+/** The value at `options.<id>.<path…>` of a dokebi.yaml source, or undefined. */
+/** Levels core reads in options.logging (D-0047): `level` and the values of `plugins`. */
+const LOGGING_LEVELS = ['debug', 'info', 'warn', 'error', 'silent'];
+/**
+ * The sections something reads — doctor's rule: core's (logging, reload), the conventions
+ * (application-runtime, …), a first admin's section, each installed plugin's section, the
+ * required plugins and the application's settings. A plugin id that is not its section (the
+ * logger's old dokebi-logger) is not read.
+ */
+function readSections(state, options) {
+    return new Set([
+        'logging',
+        RELOAD_OPTIONS_KEY,
+        ...CONVENTION_SECTIONS,
+        ...options.flatMap((item) => adminSections(item)),
+        ...state.plugins.map((plugin) => optionsKey(plugin)),
+        ...(state.settings ?? []),
+    ]);
+}
+/**
+ * The installed plugin whose options section `section` names: `options.<id>`, or
+ * `options.logging` for the logger host (D-0151 follow-up: `config set logging.level=debug`,
+ * `config secret logging.targets.studio.token --stdin`).
+ */
+function sectionPlugin(plugins, section) {
+    return (plugins.find((item) => item.id === section) ??
+        plugins.find((item) => optionsKey(item) === section));
+}
+/** The section of dokebi.yaml of a plugin (options.logging for the logger host) or settings. */
+function targetSection(target) {
+    return 'settingsSection' in target ? target.settingsSection : optionsKey(target);
+}
+/** Checks a section against the plugin's schema, or the settings schema file (D-0155). */
+function checkTarget(validator, root, target, options) {
+    return 'settingsSection' in target
+        ? validator.checkSettings(root, target.settingsSection, options)
+        : validator.check(root, target, options);
+}
+/** options.reload (D-0154): core's declaration decides; a refused value names the paths only. */
+function checkCoreReload(section) {
+    const checked = reloadOptions.check(section);
+    if (checked.ok)
+        return;
+    const paths = checked.issues.map((issue) => `reload.${issue.path}`);
+    throw new CliError('INVALID_SET', `${paths.join(', ')} is not a valid setting of options.reload`, {
+        details: {
+            paths,
+            issues: checked.issues.map((issue) => ({
+                path: `reload.${issue.path}`,
+                message: issue.message,
+            })),
+            allowed: 'reload.watch and reload.signal (true or false), reload.debounceMs (50–60000), reload.prepareTimeoutMs (1000–600000), reload.watchRetryMs (1000–3600000)',
+        },
+        phase: 'arguments',
+    });
+}
+/**
+ * options.logging without a logger plugin: core reads `level` and `plugins` only (D-0047), so
+ * `config set` takes those with core's levels and refuses the rest with the command that adds
+ * the logger.
+ */
+function checkCoreLogging(sets) {
+    const level = (value) => typeof value === 'string' && LOGGING_LEVELS.includes(value);
+    for (const set of sets) {
+        const [first, name, ...rest] = set.path;
+        const valid = (first === 'level' && name === undefined && level(set.value)) ||
+            (first === 'plugins' &&
+                ((name === undefined &&
+                    set.value !== null &&
+                    typeof set.value === 'object' &&
+                    !Array.isArray(set.value) &&
+                    Object.values(set.value).every(level)) ||
+                    (name !== undefined && !rest.length && level(set.value))));
+        if (!valid)
+            throw new CliError('INVALID_SET', `logging.${set.path.join('.')} is not a setting of options.logging without @dokebi/logger`, {
+                details: {
+                    path: `logging.${set.path.join('.')}`,
+                    allowed: `logging.level and logging.plugins.<plugin> (${LOGGING_LEVELS.join(', ')})`,
+                    fix: `npx dokebi add ${LOGGER_PACKAGE} adds the logger whose options (targets, redact, …) live in options.logging too`,
+                },
+                phase: 'arguments',
+            });
+    }
+}
+function optionAt(source, id, path) {
+    let current = parseProjectConfig(source).options[id];
+    for (const key of path)
+        current =
+            current && typeof current === 'object' && Object.hasOwn(current, key)
+                ? current[key]
+                : undefined;
+    return current;
+}
 /**
  * Follow-ups after init (D-0065): read the guide, pick a recipe and ask its questions, find
  * plugins, read the core contract, and verify before saying done.
@@ -53,9 +327,14 @@ export function initNextSteps(target) {
             command: 'npx dokebi plugins search <words> --json',
             why: 'outside a recipe: find a plugin; `absent` entries are features Dokebi does not have (do not invent them)',
         },
+        {
+            // AI-M04 F7: the exact path (agents guessed `plugins doc dokebi-core`).
+            command: 'read node_modules/@dokebi/core/AI.md',
+            why: 'the core guide before writing app code: entry points, lifecycle, configuration, logging (the same text: npx dokebi plugins doc @dokebi/core --json)',
+        },
         {
             command: 'npx dokebi verify --json',
-            why: 'doctor, typecheck, build, start, HTTP checks and stop; say done only when ok is true',
+            why: "doctor, check, typecheck, build, the project's tests, start, HTTP checks and stop; say done only when ok is true",
         },
     ];
 }
@@ -116,21 +395,165 @@ const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'optionalDepende
 function union(...lists) {
     return [...new Set(lists.flat())];
 }
+/** D-0151: the app logger every new project gets. */
+export const LOGGER_PACKAGE = '@dokebi/logger';
+/**
+ * R4CA-3: what the project's .env sets that the app does not get from it (DOKEBI_CONFIG), as the
+ * warnings of the config commands: they work on the file the environment names.
+ */
+function envWarnings(root) {
+    return envFileWarnings(root).map(({ code, path, hint }) => ({ code, path, hint }));
+}
+/**
+ * A `file:<absolute>.tgz` spec of a tarball inside the project (`dokebi add ./vendor/x.tgz`,
+ * `upgrade --to vendor/x.tgz`) as the project-relative `file:vendor/x.tgz`, so npm writes it
+ * relative into package.json and package-lock.json like the tarballs the project lists (it was
+ * written absolute, R5C-3); any other spec as it is. Links are resolved first, and the relative
+ * path has none, so the staging copy (securePath) takes it; a tarball outside stays absolute.
+ */
+async function projectSpec(root, spec) {
+    if (!spec.startsWith('file:') || !spec.endsWith('.tgz'))
+        return spec;
+    const file = spec.slice(5);
+    // A missing tarball is npm's error to give, as before.
+    if (!(await exists(file)))
+        return spec;
+    const real = await realpath(file);
+    const path = projectTarball(`file:${relative(await realpath(root), real)
+        .split(sep)
+        .join('/')}`);
+    if (path === undefined)
+        return spec;
+    debug('A tarball inside the project is installed by its relative path', { path });
+    return `file:${path}`;
+}
+/**
+ * A command run outside a Dokebi project (no .dokebi/state.json or dokebi.yaml) is NOT_A_PROJECT
+ * with the file and a fix, never an INTERNAL_ERROR with a bare ENOENT (R1: add, upgrade and remove
+ * in the wrong folder).
+ */
+function notAProject(root, file) {
+    return new CliError('NOT_A_PROJECT', `No ${file}: run this in a Dokebi project (the folder with package.json, dokebi.yaml and .dokebi/state.json)`, {
+        phase: 'arguments',
+        details: {
+            root,
+            file,
+            fix: file === CONFIG_FILE
+                ? FRESH_COPY_FIX
+                : 'run the command in the project folder, or make a project first with npx -y @dokebi/cli init <name>; .dokebi/state.json is written by the CLI and belongs in version control',
+        },
+    });
+}
+/** The text of .dokebi/state.json; a missing file is NOT_A_PROJECT. */
+async function projectStateText(root) {
+    const path = await securePath(root, '.dokebi/state.json');
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            throw notAProject(root, '.dokebi/state.json');
+        throw new CliError('READ_FAILED', 'Cannot read .dokebi/state.json', { cause: error });
+    }
+}
 export class Project {
     npm;
     constructor(npm = new NpmClient()) {
         this.npm = npm;
     }
-    async init(target, core = '@dokebi/core@^0.4.0', dryRun = false) {
+    /**
+     * A new project (D-0065). D-0151: every new project gets @dokebi/logger, added by `add` once
+     * the project exists (stdout JSON, pretty output in dokebi dev, a file target to turn on for
+     * production). When that install fails (offline, a registry without it) the project stays on
+     * core's console logger and the result says so (warning LOGGER_NOT_INSTALLED and the command).
+     */
+    async init(target, core = '@dokebi/core@^0.4.0', dryRun = false, deploy = false, logger = true) {
+        // R4CB-3: a termination signal before the project is in place cancels init (INTERRUPTED,
+        // the staging folder removed); one that came while it was moved in skips the logger.
+        const interruption = dryRun ? undefined : Interruption.open();
+        let created;
+        try {
+            created = await this.#init(target, core, dryRun, deploy, interruption);
+        }
+        finally {
+            interruption?.close();
+        }
+        if (dryRun || !logger)
+            return created;
+        if (interruption?.interrupted)
+            return {
+                ...created,
+                warnings: [
+                    ...(created.warnings ?? []),
+                    {
+                        code: 'LOGGER_NOT_INSTALLED',
+                        path: LOGGER_PACKAGE,
+                        hint: `INTERRUPTED: npx dokebi add ${LOGGER_PACKAGE} installs it later`,
+                    },
+                ],
+                nextSteps: [
+                    {
+                        command: `npx dokebi add ${LOGGER_PACKAGE}`,
+                        why: 'install the default app logger that init skipped after the termination signal',
+                    },
+                    ...created.nextSteps,
+                ],
+            };
+        try {
+            const added = await this.add(resolve(target), LOGGER_PACKAGE);
+            debug('Added the default logger to the new project', {
+                target,
+                changed: added.changed.length,
+                resolved: added.resolved?.version ?? null,
+            });
+            return added.warnings?.length
+                ? { ...created, warnings: [...(created.warnings ?? []), ...added.warnings] }
+                : created;
+        }
+        catch (error) {
+            // The project exists and runs with core's console logger; the caller sees why and how.
+            debug('The default logger could not be added; the project keeps the console logger', {
+                target,
+                error: describeError(error),
+            });
+            return {
+                ...created,
+                warnings: [
+                    ...(created.warnings ?? []),
+                    {
+                        code: 'LOGGER_NOT_INSTALLED',
+                        path: LOGGER_PACKAGE,
+                        hint: `${error instanceof CliError ? error.code : 'ADD_FAILED'}: npx dokebi add ${LOGGER_PACKAGE} installs it later`,
+                    },
+                ],
+                nextSteps: [
+                    {
+                        command: `npx dokebi add ${LOGGER_PACKAGE}`,
+                        why: 'install the default app logger (rotating files, redaction, pretty dev output) that init could not add',
+                    },
+                    ...created.nextSteps,
+                ],
+            };
+        }
+    }
+    async #init(target, core, dryRun, deploy, interruption) {
         target = resolve(target);
         // D-0065 §11: an existing folder is accepted when it is empty or holds only entries that
         // are not part of a Node project (INIT_HARMLESS); anything else is PROJECT_EXISTS.
         const folder = await initFolder(target);
+        const deployment = deploy ? { files: Object.keys(DEPLOYMENT_FILES) } : undefined;
+        const nextSteps = initNextSteps(target);
+        if (deploy)
+            nextSteps.push({
+                command: 'read DEPLOY.md',
+                why: 'configure deployment, runtime credentials and infrastructure before building or starting containers',
+            });
         if (dryRun)
             return {
                 changed: [target],
                 preserved: folder.kept.map((name) => join(target, name)),
-                nextSteps: initNextSteps(target),
+                nextSteps,
+                ...(deployment ? { deployment } : {}),
             };
         // A new folder is staged next to it and renamed into place (atomic). An existing folder is
         // staged inside itself (an agent sandbox may allow writes only there), then moved in.
@@ -142,6 +565,7 @@ export class Project {
             if (folder.kept.includes('.npmrc'))
                 await stageNpmConfig(target, staging);
             await mkdir(join(staging, 'src'));
+            await mkdir(join(staging, 'tests'));
             await mkdir(join(staging, '.dokebi'));
             await writeFile(join(staging, 'package.json'), json({
                 name: basename(target)
@@ -149,7 +573,7 @@ export class Project {
                     .replace(/[^a-z0-9-]/g, '-') || FALLBACK_PROJECT_NAME,
                 private: true,
                 type: 'module',
-                scripts: { start: 'node src/main.ts', typecheck: TYPECHECK_SCRIPT },
+                scripts: { start: 'node src/main.ts', typecheck: TYPECHECK_SCRIPT, test: TEST_SCRIPT },
                 engines: { node: '>=24.0.0' },
                 // npm installs these together with core (one npm run); --save-exact keeps them pinned.
                 devDependencies: PROJECT_DEV_DEPENDENCIES,
@@ -160,20 +584,30 @@ export class Project {
             await writeFile(join(staging, GENERATED), generated);
             await writeFile(join(staging, 'src/main.ts'), MAIN_SOURCE);
             const requiredPlugins = await readRequiredPlugins(staging);
-            await writeFile(join(staging, AGENTS_FILE), projectGuide(guideEntries(await this.coreVersion(staging), requiredPlugins, [], CLI_VERSION)));
+            await writeFile(join(staging, AGENTS_FILE), projectGuide(guideEntries(await this.coreVersion(staging), requiredPlugins, [], CLI_VERSION), await loadCatalog()));
             await writeFile(join(staging, CLAUDE_FILE), CLAUDE_GUIDE);
             await writeFile(join(staging, 'tsconfig.json'), TSCONFIG_SOURCE);
             await writeFile(join(staging, CONFIG_FILE), CONFIG_TEMPLATE, { mode: 0o600 });
             await writeFile(join(staging, EXAMPLE), CONFIG_EXAMPLE);
             await writeFile(join(staging, '.dokebi/state.json'), json(emptyState(hash(generated))));
-            await writeFile(join(staging, '.gitignore'), ignoreConfig('node_modules/\n.dokebi/lock\n.dokebi/transaction-*/\n'));
+            await writeFile(join(staging, '.gitignore'), 
+            // `*.mmdb`: IP geolocation databases (@dokebi/geoip) are licensed data, never committed.
+            ignoreConfig('node_modules/\n.dokebi/lock\n.dokebi/transaction-*/\n*.mmdb\n'));
+            if (deploy) {
+                debug('Writing deployment skeleton', { files: Object.keys(DEPLOYMENT_FILES) });
+                for (const [file, content] of Object.entries(DEPLOYMENT_FILES))
+                    await writeFile(join(staging, file), content);
+            }
+            // The move below makes the project visible: a signal before it cancels init.
+            interruption?.check();
             if (folder.exists) {
                 await this.#moveInto(staging, target, folder.kept);
                 debug('Initialized the project in an existing folder', { target, kept: folder.kept });
                 return {
                     changed: [target],
                     preserved: folder.kept.map((name) => join(target, name)),
-                    nextSteps: initNextSteps(target),
+                    nextSteps,
+                    ...(deployment ? { deployment } : {}),
                 };
             }
             // Reserve the destination before moving anything so existing projects are never replaced.
@@ -190,7 +624,11 @@ export class Project {
                 }
                 throw cause;
             }
-            return { changed: [target], preserved: [], nextSteps: initNextSteps(target) };
+            return { changed: [target], preserved: [], nextSteps, ...(deployment ? { deployment } : {}) };
+        }
+        catch (error) {
+            // npm got the signal from its forwarder and failed (or check() above): nothing is in place.
+            throw interruption ? interruption.failure(error) : error;
         }
         finally {
             await rm(staging, { recursive: true, force: true });
@@ -229,7 +667,7 @@ export class Project {
     }
     async migrate(root, dryRun = false) {
         root = await realpath(root);
-        await readFile(await securePath(root, '.dokebi/state.json'));
+        await projectStateText(root);
         const tx = await Transaction.begin(root);
         try {
             for (const path of [CONFIG_FILE, CONFIG_BACKUP, EXAMPLE])
@@ -240,9 +678,15 @@ export class Project {
                 throw new CliError('BACKUP_EXISTS', 'Preserve the existing legacy configuration backup before migrating');
             const state = readState(parseObject(await tx.read('.dokebi/state.json'), 'state'));
             if (hash(await tx.read(GENERATED)) !== state.generatedHash)
-                throw new CliError('MODIFIED_REGISTRATION', GENERATED);
+                throw modifiedRegistration();
             const main = await tx.read('src/main.ts');
-            if (main !== LEGACY_MAIN_SOURCE && main !== MAIN_SOURCE_V1 && main !== MAIN_SOURCE)
+            if (main !== LEGACY_MAIN_SOURCE &&
+                main !== MAIN_SOURCE_V1 &&
+                main !== MAIN_SOURCE_V2 &&
+                main !== MAIN_SOURCE_V3 &&
+                main !== MAIN_SOURCE_V4 &&
+                main !== MAIN_SOURCE_V5 &&
+                main !== MAIN_SOURCE)
                 throw new CliError('MIGRATION_MAIN_REQUIRED', 'Automatic migration supports generated entry points only; migrate custom src/main.ts and configuration manually using the documented flow');
             const original = await tx.read(LEGACY_CONFIG_FILE);
             const source = migrateConfig(original);
@@ -252,7 +696,7 @@ export class Project {
             await validatePluginOptions(root, orderPlugins(state.plugins, version, required), config.options);
             await tx.write(CONFIG_BACKUP, original);
             await tx.replace(LEGACY_CONFIG_FILE);
-            await this.writeConfiguration(tx, state, source);
+            await this.writeConfiguration(tx, state, source, CONFIG_FILE);
             if (main === LEGACY_MAIN_SOURCE)
                 await tx.write('src/main.ts', MAIN_SOURCE);
             if (!(await exists(await securePath(root, EXAMPLE))))
@@ -265,6 +709,10 @@ export class Project {
                 await tx.commit();
             return result;
         }
+        catch (error) {
+            // R4CB-4: after a termination signal, whatever failed before the commit is INTERRUPTED.
+            throw tx.failure(error);
+        }
         finally {
             await tx.close();
         }
@@ -274,15 +722,17 @@ export class Project {
         const session = await this.#begin(root);
         const { tx, state } = session;
         try {
-            const warnings = setWarnings(sets);
+            if (!session.workspace)
+                operation = await projectSpec(session.root, operation);
+            const warnings = [];
             // No version: the highest one this project's core supports (D-0065).
-            const resolution = await this.#resolve(session, operation, warnings);
+            const { resolution, companions } = await this.#resolve(session, operation, warnings);
             if (resolution)
                 operation = `${resolution.package}@${resolution.version}`;
             const dependencies = dependencyMap(session.pkg);
             let staging;
             try {
-                staging = await this.#stage(session, session.pkg, dependencies, operation);
+                staging = await this.#stage(session, session.pkg, dependencies, operation, companions);
             }
             catch (error) {
                 // Offline: say the version came from the snapshot (CATALOG_OFFLINE) next to npm's error.
@@ -312,8 +762,20 @@ export class Project {
             const added = await this.#readPackageManifest(staging, name);
             if (session.required.some((plugin) => plugin.id === added.id || plugin.packageName === added.packageName))
                 throw new CliError('REQUIRED_PLUGIN', 'Core already supplies this required plugin');
+            // D-0155: the section of the plugin may not be an application settings section.
+            if ((state.settings ?? []).includes(optionsKey(added)))
+                throw new CliError('SETTINGS_SECTION_CONFLICT', `options.${optionsKey(added)} is the settings section of the application; ${added.packageName} reads the same section`, {
+                    details: {
+                        section: optionsKey(added),
+                        plugin: added.id,
+                        fix: `give the application settings another section (rename src/shared/settings/${optionsKey(added)}.ts, its defineSettings section and options.${optionsKey(added)}; npx dokebi settings remove ${optionsKey(added)}, then settings add <new>), then add the plugin`,
+                    },
+                    phase: 'plan',
+                });
             if (options.adapter !== undefined && added.id !== 'dokebi-db')
                 throw new CliError('USAGE', '--adapter applies to @dokebi/db only');
+            if (options.startup !== undefined && options.adapter === undefined)
+                throw new CliError('USAGE', '--startup applies to @dokebi/db with --adapter only');
             const hostsApps = added.hosts?.includes('apps') === true;
             if (options.firstApp === false && !hostsApps)
                 throw new CliError('USAGE', '--no-first-app applies only to the plugin that hosts apps (dokebi.hosts: ["apps"])');
@@ -322,6 +784,20 @@ export class Project {
                 if (existing.id === added.id &&
                     existing.packageName === added.packageName &&
                     existing.version === added.version) {
+                    // R4CB-5: the plugin is installed, so add writes no options: --set was dropped and the
+                    // result said nothing. config set is the command that changes an installed plugin's.
+                    if (sets.length) {
+                        const paths = sets.map((set) => `${optionsKey(added)}.${set.path.join('.')}`);
+                        debug('add --set refused: the plugin is installed', { plugin: added.id, paths });
+                        throw new CliError('INVALID_SET', `${added.id} ${existing.version} is installed: add does not change its options, so --set would be dropped`, {
+                            details: {
+                                plugin: added.id,
+                                paths,
+                                fix: `npx dokebi config set ${paths.map((path) => `${path}=<value>`).join(' ')} (secrets: npx dokebi config secret <path>)`,
+                            },
+                            phase: 'arguments',
+                        });
+                    }
                     if (options.adapter === undefined)
                         return { changed: [], preserved: [] };
                     // An installed db gets its adapter now (adapter file, connection, driver).
@@ -329,11 +805,12 @@ export class Project {
                         configSource: session.configSource,
                         fresh: false,
                         warnings,
+                        ...(options.startup === undefined ? {} : { startup: options.startup }),
                     });
                     await this.#syncExamples(tx, session.root, warnings, [
                         { id: 'dokebi-db', update: { changes: adapted.changes } },
                     ]);
-                    await this.writeConfiguration(tx, state, adapted.configSource);
+                    await this.writeConfiguration(tx, state, adapted.configSource, session.configFile);
                     await this.#replacePackages(session, staging, session.pkg);
                     return await this.#finish(session, {
                         changed: tx.paths,
@@ -342,10 +819,18 @@ export class Project {
                         nextSteps: adapted.nextSteps,
                     }, dryRun);
                 }
-                throw new CliError('UPGRADE_UNSUPPORTED', `Use dokebi upgrade ${added.id}`);
+                throw new CliError('UPGRADE_UNSUPPORTED', `${added.id} ${existing.version} is installed; add does not change its version (use dokebi upgrade ${added.id})`, {
+                    details: {
+                        plugin: added.id,
+                        installed: existing.version,
+                        requested: added.version,
+                        fix: `npx dokebi upgrade ${added.id} --to ${added.version}`,
+                    },
+                    phase: 'plan',
+                });
             }
             if (Object.hasOwn(dependencies, name))
-                throw new CliError('PACKAGE_CONFLICT', name);
+                throw packageConflict(name, dependencies[name]);
             // Required dependencies that name their npm package are installed in the same staging
             // and transaction, before the requested plugin (D-0030 §9).
             const automatic = await this.#automaticDependencies(staging, state, session, added, dependencies);
@@ -358,72 +843,65 @@ export class Project {
             const installed = await this.#installedDependencies(staging);
             await this.#verifyManifests(staging, state.plugins);
             const ordered = await this.#order(staging, [...state.plugins, ...automatic, added], session.required);
-            let configSource = sets.length
-                ? applySetOptions(session.configSource, added.id, sets)
-                : session.configSource;
-            let config = parseProjectConfig(configSource);
             const projectPackages = Object.keys(installed);
             const validator = new PluginOptionsValidator({ allErrors: true });
-            const installations = { ...state.installations };
             const newIds = new Set([...automatic, added].map((plugin) => plugin.id));
-            const examples = [];
             const nextSteps = [];
-            const envSecrets = [];
+            const pending = {
+                configSource: sets.length
+                    ? applySetOptions(session.configSource, added.id, sets)
+                    : session.configSource,
+                installations: { ...state.installations },
+                examples: [],
+                envSecrets: [],
+                generatedSecrets: [],
+                warnings,
+            };
             // Plans run in dependency order so each plugin sees the ones it builds on.
-            for (const plugin of ordered.filter((item) => newIds.has(item.id))) {
-                const plan = await planLifecycle({
-                    base: staging,
-                    plugin,
-                    options: config.options,
-                    plugins: ordered,
-                    projectPackages,
-                }, 'planInstall');
-                for (const defaults of plan.defaults)
-                    configSource = mergeInstallDefaults(configSource, plugin.id, defaults);
-                config = parseProjectConfig(configSource);
-                const initial = await validator.check(staging, plugin, optionsOf(config.options, plugin.id));
-                configSource = scaffoldConfig(configSource, plugin.id, initial.schema);
-                config = parseProjectConfig(configSource);
-                installations[plugin.id] = {
-                    requires: plan.requires,
-                    directories: plan.directories ?? [],
-                    ...(plan.entry ? { entry: plan.entry.target } : {}),
-                };
-                for (const variable of plan.envSecrets)
-                    envSecrets.push({ plugin: plugin.id, variable });
-                for (const directory of plan.directories ?? [])
-                    await tx.ensureDirectory(directory);
-                // `--adapter`: the db entry file is written with the adapter's connection instead of the
-                // empty template (the template's hash is recorded, so upgrades keep this file).
-                const override = new Map();
-                if (adapter && plugin.id === 'dokebi-db' && plan.entry) {
-                    const adapted = await this.#dbAdapter(session, staging, adapter.name, {
-                        configSource,
-                        fresh: true,
-                        warnings,
-                        entry: plan.entry.target,
-                    });
-                    configSource = adapted.configSource;
-                    config = parseProjectConfig(configSource);
-                    if (adapted.entryContent !== undefined)
-                        override.set(plan.entry.target, adapted.entryContent);
-                    examples.push({ id: plugin.id, update: { changes: adapted.changes } });
-                    nextSteps.push(...adapted.nextSteps);
-                }
-                await this.#addFiles(tx, staging, state, plugin, this.#planFiles(plan), override);
-                examples.push({
-                    id: plugin.id,
-                    update: { defaults: plan.defaults, schema: initial.schema },
+            for (const plugin of ordered.filter((item) => newIds.has(item.id)))
+                await this.#planInstall(session, staging, plugin, ordered, projectPackages, validator, pending, {
+                    ...(plugin.id === added.id && sets.length ? { sets } : {}),
+                    // `--adapter`: the db entry file is written with the adapter's connection instead of
+                    // the empty template (the template's hash is recorded, so upgrades keep this file).
+                    ...(adapter && plugin.id === 'dokebi-db'
+                        ? {
+                            entry: async (target, source) => {
+                                const adapted = await this.#dbAdapter(session, staging, adapter.name, {
+                                    configSource: source,
+                                    fresh: true,
+                                    warnings,
+                                    entry: target,
+                                    ...(options.startup === undefined ? {} : { startup: options.startup }),
+                                });
+                                pending.examples.push({ id: plugin.id, update: { changes: adapted.changes } });
+                                nextSteps.push(...adapted.nextSteps);
+                                return {
+                                    configSource: adapted.configSource,
+                                    ...(adapted.entryContent !== undefined
+                                        ? { content: adapted.entryContent }
+                                        : {}),
+                                };
+                            },
+                        }
+                        : {}),
                 });
-            }
+            let configSource = pending.configSource;
+            let config = parseProjectConfig(configSource);
+            const { installations, examples, envSecrets, generatedSecrets } = pending;
             // The first app comes with the plugin, so a new multi-app project runs right away.
+            let firstApp;
             if (hostsApps && !(state.apps ?? []).length && options.firstApp !== false) {
-                const first = await this.#addApp(tx, staging, added, state, configSource, 'main', {
-                    domains: ['localhost'],
+                firstApp = 'main';
+                // D-0102: a host of its own per project, so cookies of two projects never collide.
+                const domain = devHost('main', projectHostLabel(session.pkg.name, session.root));
+                const first = await this.#addApp(tx, staging, added, ordered, state, configSource, 'main', {
+                    domains: [domain],
                 });
                 configSource = first.configSource;
                 config = parseProjectConfig(configSource);
                 examples.push({ id: added.id, update: { changes: first.changes } });
+                if (first.layout)
+                    examples.push({ id: first.layout.engine, update: { changes: first.layout.changes } });
             }
             await this.#syncExamples(tx, session.root, warnings, examples);
             const configRequired = [];
@@ -431,8 +909,11 @@ export class Project {
             await this.#validateOptions(validator, staging, ordered, config, configRequired);
             state.plugins = ordered;
             state.installations = installations;
-            await this.writeConfiguration(tx, state, configSource);
-            const generatedSecrets = await this.#generateEnvSecrets(session, envSecrets);
+            await this.writeConfiguration(tx, state, configSource, session.configFile);
+            if (added.hosts?.includes('logger'))
+                await this.#wireLogger(tx, session.root, added, warnings, nextSteps);
+            generatedSecrets.push(...(await this.#generateEnvSecrets(session, envSecrets)));
+            await this.#protectMigrations(session, ordered, warnings);
             await this.#syncGuide(session, staging, ordered, warnings);
             await this.#replacePackages(session, staging, session.pkg);
             // Read the installed guide of every plugin this command added before using it.
@@ -444,7 +925,7 @@ export class Project {
                     });
             if (hostsApps && options.firstApp === false)
                 nextSteps.push({
-                    command: 'npx dokebi app add <name> --domain localhost [--inertia [--ssr]]',
+                    command: 'npx dokebi app add <name> --domain auto [--inertia [--ssr]]',
                     why: `--no-first-app: no app exists yet; ${added.id} needs one before the project starts`,
                 });
             const result = {
@@ -463,28 +944,90 @@ export class Project {
                     : {}),
                 ...(warnings.length ? { warnings } : {}),
                 ...(generatedSecrets.length ? { generatedSecrets } : {}),
+                ...(firstApp ? { firstApp } : {}),
                 nextSteps,
             };
             return await this.#finish(session, result, dryRun);
         }
+        catch (error) {
+            // R4CB-4: after a termination signal, whatever failed before the commit is INTERRUPTED.
+            throw tx.failure(error);
+        }
         finally {
             await tx.close();
         }
     }
+    /**
+     * D-0151: the logger host writes only when src/main.ts passes its logger to the Application.
+     * An unchanged generated main.ts of before D-0151 (or of before D-0154, without configFile)
+     * is rewritten to the current one; a main.ts
+     * that already calls createLogger stays; any other gets warning LOGGER_MAIN_MANUAL and the
+     * line to write (the plugin also warns LOGGER_NOT_WIRED at startup until it is there).
+     */
+    async #wireLogger(tx, root, plugin, warnings, nextSteps) {
+        const path = 'src/main.ts';
+        if (!(await exists(await securePath(root, path)))) {
+            debug('No src/main.ts to wire the logger into', { plugin: plugin.id });
+            return;
+        }
+        const main = await tx.read(path);
+        if (main === MAIN_SOURCE_V2 || main === MAIN_SOURCE_V3) {
+            await tx.write(path, MAIN_SOURCE);
+            debug('Rewrote the generated src/main.ts to pass the app logger', { plugin: plugin.id });
+            return;
+        }
+        if (/\bcreateLogger\s*\(/.test(main)) {
+            debug('src/main.ts already passes the app logger', { plugin: plugin.id });
+            return;
+        }
+        warnings.push({
+            code: 'LOGGER_MAIN_MANUAL',
+            path,
+            plugin: plugin.id,
+            hint: "src/main.ts is your own: import { createLogger } from './dokebi.generated.ts' and create the app with new Application({ config: document.options, logger: createLogger(document.options) })",
+        });
+        nextSteps.push({
+            command: 'edit src/main.ts',
+            why: `pass createLogger(document.options) from ./dokebi.generated.ts as the Application logger, so ${plugin.packageName} writes the app's records (until then it warns LOGGER_NOT_WIRED)`,
+        });
+    }
     /**
      * The version for a registry spec without one (D-0065): highest compatible with the project
      * core, from the registry, else the CLI snapshot. Workspace packages and local archives keep
      * their own resolution (D-0035).
      */
-    async #resolve(session, operation, warnings) {
+    async #resolve(session, operation, warnings, command = {
+        next: `npx dokebi add ${operation}`,
+        at: (version) => `npx dokebi add ${operation}@${version}`,
+    }) {
         if (operation.startsWith('file:'))
-            return undefined;
+            return { companions: [] };
         const bare = /^(@[^/@]+\/[^@]+|[^@]+)$/.exec(operation)?.[1];
         if (!bare || session.workspace?.packages.has(bare))
-            return undefined;
+            return { companions: [] };
         const core = await this.coreVersion(session.root);
+        // The version must fit what is installed: its peers accept the installed versions, and the
+        // installed plugins' dependency ranges accept it (else npm stops with ERESOLVE).
+        const constraints = this.#constraints(session, core, bare);
         // npm's registry for this package as npm resolves it in the project (scoped .npmrc, env).
-        const found = await resolveVersion(bare, core, await loadCatalog(), session.root);
+        const found = await resolveVersion(bare, core, await loadCatalog(), session.root, {
+            constraints,
+            next: command.next,
+        });
+        if (found.heldBack && found.resolution) {
+            const { version, conflicts } = found.heldBack;
+            warnings.push({
+                code: 'NEWER_VERSION_HELD_BACK',
+                path: `${bare}@${version}`,
+                hint: `${describeConflicts(bare, version, conflicts)}, so ${found.resolution.version} is used. For ${version}: ${conflictFix(conflicts, constraints, command.at(version))}`,
+            });
+            debug('A newer version does not fit the installed packages', {
+                package: bare,
+                heldBack: version,
+                resolved: found.resolution.version,
+                conflicts,
+            });
+        }
         if (found.offline !== undefined) {
             warnings.push({ code: 'CATALOG_OFFLINE', path: bare });
             debug('Registry unreachable while resolving a version', {
@@ -500,7 +1043,39 @@ export class Project {
             });
         if (found.resolution)
             debug('Resolved a version for add', { ...found.resolution });
-        return found.resolution;
+        // The required plugins it brings, at versions that fit too (npm would take the newest).
+        const companions = found.manifest
+            ? await companionVersions(found.manifest, core, constraints, session.root, command.next, (name) => session.workspace?.packages.has(name) === true)
+            : [];
+        return { ...(found.resolution ? { resolution: found.resolution } : {}), companions };
+    }
+    /**
+     * What the installed project asks of a version of `name` (registry.ts ProjectConstraints): the
+     * exact versions package.json pins and the registered plugins' versions (core's own), and the
+     * ranges the registered plugins declare for each plugin id. `name` itself is left out, so an
+     * upgrade is not held back by the version it replaces.
+     */
+    #constraints(session, core, name) {
+        const installed = {};
+        for (const [dependency, spec] of Object.entries(dependencyMap(session.pkg)))
+            if (validVersion(spec))
+                installed[dependency] = spec;
+        const ids = {};
+        const required = {};
+        for (const plugin of session.state.plugins) {
+            installed[plugin.packageName] = plugin.version;
+            ids[plugin.packageName] = plugin.id;
+            if (plugin.packageName === name)
+                continue;
+            for (const dependency of plugin.dependencies) {
+                const list = required[dependency.name] ?? [];
+                list.push({ plugin: plugin.id, range: dependency.version });
+                required[dependency.name] = list;
+            }
+        }
+        installed['@dokebi/core'] = core;
+        delete installed[name];
+        return { installed, ids, required };
     }
     /** The db variant (from the staged @dokebi/db, else the CLI snapshot) for `--adapter`. */
     async #adapterVariant(base, adapter) {
@@ -560,8 +1135,10 @@ export class Project {
     /**
      * `add @dokebi/db --adapter <id>`: the adapter file (src/infra/db/adapters/<id>.ts, user code),
      * the entry file content with a `main` connection, and options.dokebi-db.connections.main in
-     * dokebi.yaml and the sample. The address is a placeholder until `dokebi dev-infra` (docker)
-     * or the developer (url) writes it; secrets never come from the command line.
+     * dokebi.yaml and the sample (the URL and the template's pool limits with their defaults,
+     * `connectionOptions` of the variant, D-0112). The address is a placeholder until
+     * `dokebi dev-infra` (docker) or the developer (url) writes it; secrets never come from the
+     * command line.
      */
     async #dbAdapter(session, staging, adapter, input) {
         const { tx, state } = session;
@@ -617,13 +1194,19 @@ export class Project {
             {
                 op: 'default',
                 path: ['connections', 'main'],
-                value: { adapter, options: { url: placeholder } },
+                // D-0112: the template's limits with their defaults, so dokebi.yaml shows what to size.
+                value: {
+                    adapter,
+                    // D-0127: only when --startup is given (required is the default and stays implicit).
+                    ...(input.startup === undefined ? {} : { startup: input.startup }),
+                    options: { url: placeholder, ...variant.connectionOptions },
+                },
             },
         ];
         if (connection && connection.adapter !== adapter)
             input.warnings.push({
                 code: 'CONNECTION_KEPT',
-                path: 'dokebi.yaml#options.dokebi-db.connections.main',
+                path: `${session.configFile}#options.dokebi-db.connections.main`,
             });
         const configSource = applyConfigChanges(input.configSource, 'dokebi-db', changes);
         if (!connection)
@@ -632,8 +1215,8 @@ export class Project {
                     ? 'npx dokebi dev-infra --json'
                     : `edit dokebi.yaml: options.dokebi-db.connections.main.options.url`,
                 why: variant.devInfra?.docker
-                    ? `writes compose.yaml, a generated password in .env and the ${variant.name} URL in dokebi.yaml (or write your own URL in dokebi.yaml; never pass it with --set)`
-                    : 'write the database URL (with its password) in dokebi.yaml; never pass it with --set',
+                    ? `writes compose.yaml and the ${variant.name} URL with a generated password only in dokebi.yaml (or write your own URL in dokebi.yaml with your file editor; never put it on a command line such as --set, sed or echo)`
+                    : 'write the database URL (with its password) in dokebi.yaml with your file editor; never put it on a command line such as --set, sed or echo',
             });
         return {
             configSource,
@@ -642,6 +1225,140 @@ export class Project {
             nextSteps,
         };
     }
+    /**
+     * The install plan of one plugin this command installs (add: the requested plugin and its
+     * automatic dependencies; upgrade: the automatic dependencies its new version brings, D-0116):
+     * install defaults, the options scaffold, generated secrets, directories and files, written
+     * into the transaction and `pending`. Plugins are planned in dependency order.
+     */
+    async #planInstall(session, staging, plugin, ordered, projectPackages, validator, pending, hooks = {}) {
+        const { tx, state } = session;
+        let configSource = pending.configSource;
+        const plan = await planLifecycle({
+            base: staging,
+            plugin,
+            options: parseProjectConfig(configSource).options,
+            plugins: ordered,
+            projectPackages,
+        }, 'planInstall');
+        // D-0151: the logger host's options are options.logging (optionsKey), not options.<id>.
+        const key = optionsKey(plugin);
+        for (const defaults of plan.defaults)
+            configSource = mergeInstallDefaults(configSource, key, defaults);
+        if (plugin.hosts?.includes('logger'))
+            configSource = addLoggingTargets(configSource);
+        const initial = await validator.check(staging, plugin, optionsOf(parseProjectConfig(configSource).options, key));
+        configSource = scaffoldConfig(configSource, key, initial.schema);
+        if (initial.schema)
+            session.schemas.set(key, initial.schema);
+        // D-0073 addendum 2: generated secrets go into dokebi.yaml (0600, kept out of Git by init).
+        for (const path of plan.configSecrets) {
+            const option = `${plugin.id}.${path.join('.')}`;
+            if (optionAt(configSource, key, path) !== undefined) {
+                debug('Secret option already set; nothing generated', { option });
+                continue;
+            }
+            const written = await this.#withGeneratedSecret(staging, validator, plugin, configSource, path);
+            configSource = written.source;
+            pending.generatedSecrets.push({ plugin: plugin.id, option, file: session.configFile });
+            debug('Generated a secret option', { option, list: written.list });
+        }
+        if (plan.envSecrets.length) {
+            // Kept for plugins published before configSecrets (session 0.4.1); removed in 0.5.
+            debug('Install plan uses the deprecated envSecrets; secrets belong in dokebi.yaml', {
+                plugin: plugin.id,
+                variables: plan.envSecrets,
+            });
+            pending.warnings.push({
+                code: 'DEPRECATED_PLAN_FIELD',
+                plugin: plugin.id,
+                deprecated: 'envSecrets',
+            });
+        }
+        pending.installations[plugin.id] = {
+            requires: plan.requires,
+            directories: plan.directories ?? [],
+            ...(plan.entry ? { entry: plan.entry.target } : {}),
+        };
+        for (const variable of plan.envSecrets)
+            pending.envSecrets.push({ plugin: plugin.id, variable });
+        for (const directory of plan.directories ?? [])
+            await tx.ensureDirectory(directory);
+        const override = new Map();
+        if (hooks.entry && plan.entry) {
+            const written = await hooks.entry(plan.entry.target, configSource);
+            configSource = written.configSource;
+            if (written.content !== undefined)
+                override.set(plan.entry.target, written.content);
+        }
+        await this.#addFiles(tx, staging, state, plugin, this.#planFiles(plan), override);
+        // The example's section is the same as dokebi.yaml's: options.logging for the logger host.
+        pending.examples.push({
+            id: key,
+            update: {
+                defaults: plan.defaults,
+                schema: initial.schema,
+                // The targets addLoggingTargets wrote into dokebi.yaml above (no secret in them).
+                ...(plugin.hosts?.includes('logger') ? { loggingTargets: true } : {}),
+            },
+        });
+        pending.configSource = configSource;
+    }
+    /**
+     * D-0116: a required dependency of `plugins` that neither the project nor the change has and
+     * whose manifest names no npm package cannot be installed by upgrade: MISSING_DEPENDENCY with
+     * the catalog's package in `details.fix`, before anything is written.
+     */
+    async #refuseUnnamedDependencies(session, plugins, rerun) {
+        const known = new Set([
+            ...session.state.plugins.map((plugin) => plugin.id),
+            ...session.required.map((plugin) => plugin.id),
+            ...plugins.map((plugin) => plugin.id),
+        ]);
+        for (const plugin of plugins)
+            for (const dependency of plugin.dependencies) {
+                if (dependency.optional || dependency.package || known.has(dependency.name))
+                    continue;
+                const listed = findPackage(await loadCatalog(), dependency.name);
+                debug('Upgrade refused: a new required dependency names no package', {
+                    plugin: plugin.id,
+                    dependency: dependency.name,
+                    catalog: listed?.package ?? null,
+                });
+                throw missingDependency(plugin, dependency, {
+                    reason: 'no-package',
+                    ...(listed?.package ? { package: listed.package } : {}),
+                    why: 'its manifest names no npm package for it, so the upgrade cannot install it',
+                    afterwards: rerun,
+                });
+            }
+    }
+    /**
+     * D-0116: an automatic dependency with more than one install variant (a choice such as the db
+     * adapter) is the user's to choose: MISSING_DEPENDENCY, before anything is written.
+     */
+    async #refuseChoiceDependencies(staging, plugins, automatic, rerun) {
+        for (const dependency of automatic) {
+            const pkg = parseObject(await readFile(await packageFile(staging, dependency.packageName, 'package.json'), 'utf8'), dependency.packageName);
+            const catalog = pkg.dokebiCatalog;
+            const variants = Array.isArray(catalog?.variants)
+                ? catalog.variants.map((variant) => String(variant.name))
+                : [];
+            if (variants.length < 2)
+                continue;
+            debug('Upgrade refused: a new required dependency needs a choice', {
+                dependency: dependency.id,
+                variants,
+            });
+            throw missingDependency(requirerOf(plugins, dependency.id), declaredDependency(plugins, dependency.id), {
+                reason: 'needs-choice',
+                package: dependency.packageName,
+                why: `${dependency.id} needs a choice (${variants.join(', ')}), so the upgrade does not install it`,
+                afterwards: rerun,
+                extra: { variants },
+            });
+        }
+    }
     /**
      * Installs, into the staging directory, every missing required dependency (recursively) whose
      * manifest entry names an npm `package`. Returns their manifests; optional ones are skipped and
@@ -654,23 +1371,63 @@ export class Project {
             added.id,
         ]);
         const result = [];
-        const pending = [added];
-        while (pending.length) {
-            const plugin = pending.shift();
-            for (const dependency of plugin.dependencies) {
-                if (dependency.optional || !dependency.package || known.has(dependency.name))
-                    continue;
-                if (result.length >= 16)
-                    throw new CliError('INVALID_MANIFEST', 'Too many automatic dependencies');
-                if (Object.hasOwn(dependencies, dependency.package))
-                    throw new CliError('PACKAGE_CONFLICT', dependency.package);
-                await this.#stageInstall(session, staging, `${dependency.package}@${dependency.version}`);
+        // One npm run per dependency level, not per dependency (D-0116: @dokebi/app's three
+        // automatic dependencies were three more full npm runs in staging).
+        let level = [added];
+        while (level.length) {
+            const wanted = [];
+            for (const plugin of level)
+                for (const dependency of plugin.dependencies) {
+                    if (dependency.optional || !dependency.package || known.has(dependency.name))
+                        continue;
+                    if (result.length + wanted.length >= 16)
+                        throw new CliError('INVALID_MANIFEST', `${added.id} brings more than 16 automatic dependencies; the CLI installs at most 16 at once`, {
+                            details: {
+                                plugin: added.id,
+                                automatic: [
+                                    ...result.map((item) => item.id),
+                                    ...wanted.map((item) => item.dependency.name),
+                                ],
+                                fix: 'add some of these plugins first with npx dokebi add <package>, then repeat this command',
+                            },
+                            phase: 'plan',
+                        });
+                    if (Object.hasOwn(dependencies, dependency.package))
+                        throw packageConflict(dependency.package, dependencies[dependency.package], plugin.id);
+                    known.add(dependency.name);
+                    wanted.push({ plugin, dependency: dependency });
+                }
+            if (!wanted.length)
+                break;
+            // Already a direct dependency of the staged install (picked with the package itself by
+            // companionVersions): installing the range again would let npm take the newest one.
+            const staged = await this.#installedDependencies(staging);
+            const install = wanted
+                .filter(({ dependency }) => !Object.hasOwn(staged, dependency.package))
+                .map(({ dependency }) => `${dependency.package}@${dependency.version}`);
+            debug('Installing automatic dependencies into staging', {
+                plugin: added.id,
+                packages: install,
+                staged: wanted.length - install.length,
+            });
+            if (install.length)
+                await this.#stageInstall(session, staging, install);
+            level = [];
+            for (const { plugin, dependency } of wanted) {
                 const manifest = await this.#readPackageManifest(staging, dependency.package);
                 if (manifest.id !== dependency.name)
-                    throw new CliError('INVALID_MANIFEST', `${dependency.package} is not ${dependency.name}`);
-                known.add(manifest.id);
+                    throw new CliError('INVALID_MANIFEST', `${plugin.id} names ${dependency.package} as the package of ${dependency.name}, but that package is the plugin ${manifest.id}`, {
+                        details: {
+                            plugin: plugin.id,
+                            dependency: dependency.name,
+                            package: dependency.package,
+                            actual: manifest.id,
+                            fix: `the manifest of ${plugin.packageName} ${plugin.version} is wrong: use another version, or report it to its authors`,
+                        },
+                        phase: 'plan',
+                    });
                 result.push(manifest);
-                pending.push(manifest);
+                level.push(manifest);
             }
         }
         return result;
@@ -690,10 +1447,28 @@ export class Project {
             if (session.required.some((plugin) => plugin.id === id || plugin.packageName === id))
                 throw new CliError('REQUIRED_PLUGIN', 'Core-required plugins cannot be removed');
             const removed = state.plugins.find((plugin) => plugin.id === id);
+            // R4CB-10: remove takes the plugin id. A package name of an installed plugin was "not
+            // installed", so `remove @dokebi/web` answered ok with nothing changed and web stayed.
+            const byPackage = removed
+                ? undefined
+                : state.plugins.find((plugin) => plugin.packageName === id);
+            if (byPackage)
+                throw new CliError('UNKNOWN_PLUGIN', `${id} is the package of the plugin ${byPackage.id}; remove takes the plugin id`, {
+                    details: {
+                        plugin: id,
+                        package: byPackage.packageName,
+                        installed: state.plugins.map((plugin) => plugin.id),
+                        fix: `npx dokebi remove ${byPackage.id}`,
+                    },
+                    phase: 'arguments',
+                });
             if (!removed)
                 return { changed: [], preserved: [] };
-            if (state.plugins.some((plugin) => plugin.dependencies.some((dep) => dep.name === removed.id && !dep.optional)))
-                throw new CliError('REVERSE_DEPENDENCY', removed.id);
+            const dependents = state.plugins
+                .filter((plugin) => plugin.dependencies.some((dep) => dep.name === removed.id && !dep.optional))
+                .map((plugin) => plugin.id);
+            if (dependents.length)
+                throw reverseDependency(removed.id, dependents);
             const dependencies = dependencyMap(session.pkg);
             delete dependencies[removed.packageName];
             const staging = await this.#stage(session, session.pkg, dependencies, undefined);
@@ -708,9 +1483,7 @@ export class Project {
             const checks = await this.#runChecks(staging, ordered, config, installations, Object.keys(after));
             for (const plugin of ordered) {
                 if (checks.get(plugin.id)?.requires.includes(removed.id))
-                    throw new CliError('REVERSE_DEPENDENCY', removed.id, {
-                        details: { plugin: plugin.id, requires: [removed.id] },
-                    });
+                    throw reverseDependency(removed.id, [plugin.id]);
             }
             for (const plugin of ordered)
                 installations[plugin.id] = {
@@ -737,10 +1510,11 @@ export class Project {
                     preserved.push(path);
                 delete state.files[path];
             }
-            const marked = markRemoved(configSource, removed.id);
+            // The plugin's section, as the sample's mark below (options.logging for the logger host).
+            const marked = markRemoved(configSource, optionsKey(removed));
             configSource = marked.source;
             if (marked.marked)
-                preserved.push(`${CONFIG_FILE}#options.${removed.id}`);
+                preserved.push(`${session.configFile}#options.${optionsKey(removed)}`);
             for (const directory of state.installations[removed.id]?.directories ?? []) {
                 if (await exists(await securePath(session.root, directory)))
                     preserved.push(directory);
@@ -750,7 +1524,7 @@ export class Project {
                 const example = await tx.read(EXAMPLE);
                 let updated;
                 try {
-                    updated = markExampleRemoved(example, removed.id);
+                    updated = markExampleRemoved(example, optionsKey(removed));
                 }
                 catch {
                     // The removal still proceeds; the caller sees why the example was left as it was.
@@ -761,7 +1535,7 @@ export class Project {
             }
             state.plugins = ordered;
             state.installations = installations;
-            await this.writeConfiguration(tx, state, configSource);
+            await this.writeConfiguration(tx, state, configSource, session.configFile);
             await this.#syncGuide(session, staging, ordered, warnings);
             await this.#replacePackages(session, staging, session.pkg);
             const result = {
@@ -772,6 +1546,10 @@ export class Project {
             };
             return await this.#finish(session, result, dryRun);
         }
+        catch (error) {
+            // R4CB-4: after a termination signal, whatever failed before the commit is INTERRUPTED.
+            throw tx.failure(error);
+        }
         finally {
             await tx.close();
         }
@@ -782,39 +1560,122 @@ export class Project {
         try {
             const current = state.plugins.find((plugin) => plugin.id === id);
             if (!current)
-                throw new CliError('UNKNOWN_PLUGIN', id);
-            // A bare version or range applies to the installed package; otherwise use a full spec.
-            const operation = to === undefined
-                ? `${current.packageName}@latest`
+                throw new CliError('UNKNOWN_PLUGIN', `${id} is not a registered plugin of this project`, {
+                    details: {
+                        plugin: id,
+                        installed: state.plugins.map((plugin) => plugin.id),
+                        fix: 'upgrade takes a plugin id from details.installed; install a new plugin with npx dokebi add <package>',
+                    },
+                    phase: 'arguments',
+                });
+            const identityChanged = (actual) => new CliError('UPGRADE_IDENTITY_CHANGED', `${to ?? 'latest'} is ${actual}, not ${current.packageName} (${id}); upgrade keeps the package of a plugin`, {
+                details: {
+                    plugin: id,
+                    package: current.packageName,
+                    requested: to ?? 'latest',
+                    actual,
+                    fix: `name a version or archive of ${current.packageName}; to switch packages, npx dokebi remove ${id} and npx dokebi add <package>`,
+                },
+                phase: 'plan',
+            });
+            // Without --to: the highest version that fits the core and the installed packages, as add
+            // picks (a newer one they hold back is NEWER_VERSION_HELD_BACK), else npm's latest
+            // (workspace packages, an unreachable registry).
+            const resolveWarnings = [];
+            const found = to === undefined
+                ? await this.#resolve(session, current.packageName, resolveWarnings, {
+                    next: `npx dokebi upgrade ${id}`,
+                    at: (version) => `npx dokebi upgrade ${id} --to ${version}`,
+                })
+                : undefined;
+            const resolved = found?.resolution;
+            const picked = resolved?.source === 'registry' && !lt(resolved.version, current.version)
+                ? resolved.version
+                : undefined;
+            // A bare version or range applies to the installed package; otherwise use a full spec.
+            const requested = to === undefined
+                ? `${current.packageName}@${picked ?? 'latest'}`
                 : to !== 'latest' && !to.endsWith('.tgz') && validRange(to) !== null
                     ? packageSpec(`${current.packageName}@${to}`, session.root)
                     : packageSpec(to, session.root);
+            const operation = session.workspace ? requested : await projectSpec(session.root, requested);
             const dependencies = dependencyMap(session.pkg);
-            const staging = await this.#stage(session, session.pkg, dependencies, operation);
+            const staging = await this.#stage(session, session.pkg, dependencies, operation, picked ? (found?.companions ?? []) : []);
             const after = await this.#installedDependencies(staging);
-            if (operation.startsWith('file:') &&
-                Object.keys(after).find((key) => after[key] === operation) !== current.packageName)
-                throw new CliError('UPGRADE_IDENTITY_CHANGED', id);
+            if (operation.startsWith('file:')) {
+                const archive = Object.keys(after).find((key) => after[key] === operation);
+                if (archive !== current.packageName)
+                    throw identityChanged(archive ?? operation);
+            }
             if (!operation.startsWith('file:') && !operation.startsWith(current.packageName + '@'))
-                throw new CliError('UPGRADE_IDENTITY_CHANGED', id);
+                throw identityChanged(operation);
             const upgraded = await this.#readPackageManifest(staging, current.packageName);
             if (upgraded.id !== current.id || upgraded.packageName !== current.packageName)
-                throw new CliError('UPGRADE_IDENTITY_CHANGED', id);
+                throw identityChanged(`${upgraded.packageName} (${upgraded.id})`);
             if (lt(upgraded.version, current.version))
-                throw new CliError('UPGRADE_DOWNGRADE', id);
+                throw new CliError('UPGRADE_DOWNGRADE', `${id} ${current.version} is installed and ${to ?? 'latest'} is the older ${upgraded.version}; upgrade does not go back`, {
+                    details: {
+                        plugin: id,
+                        from: current.version,
+                        to: upgraded.version,
+                        fix: `name a version of ${current.packageName} at or above ${current.version}; to go back, npx dokebi remove ${id} and npx dokebi add ${current.packageName}@${upgraded.version}`,
+                    },
+                    phase: 'plan',
+                });
             // Same version and same manifest: nothing to do. Same version with a different manifest
             // (a package changed without a version bump) is applied again so the project can follow
             // what is installed (D-0037).
             const sameVersion = upgraded.version === current.version;
-            if (sameVersion && json(upgraded) === json(current))
-                return { changed: [], preserved: [], from: current.version, to: upgraded.version };
+            // An unpublished version keeps its number while its code changes (AGENTS.md): a rebuilt
+            // tarball of the same version and manifest is still new code. The lock's integrity of the
+            // package tells it apart (2026-10-28: web 0.4.3 from a tarball with a fix was a no-op).
+            const contentChanged = sameVersion &&
+                json(upgraded) === json(current) &&
+                (await this.#contentChanged(session, staging, current.packageName));
+            if (sameVersion && json(upgraded) === json(current) && !contentChanged)
+                return {
+                    changed: [],
+                    preserved: [],
+                    ...(resolveWarnings.length ? { warnings: resolveWarnings } : {}),
+                    from: current.version,
+                    to: upgraded.version,
+                };
             const others = state.plugins.filter((plugin) => plugin.id !== id);
-            await this.#verifyManifests(staging, others);
-            const ordered = await this.#order(staging, state.plugins.map((plugin) => (plugin.id === id ? upgraded : plugin)), session.required);
+            const warnings = [...resolveWarnings];
+            // D-0116: a required dependency the new version declares and the project lacks is
+            // installed with the upgrade, as `add` would (same staging, same transaction), when its
+            // manifest names the package and it needs no choice or settings; otherwise the upgrade is
+            // refused before anything is written, with the add command to run first.
+            const rerun = `npx dokebi upgrade ${id}${to === undefined ? '' : ` --to ${to}`}`;
+            await this.#refuseUnnamedDependencies(session, [upgraded], rerun);
+            const automatic = await this.#automaticDependencies(staging, state, session, upgraded, dependencies);
+            if (automatic.length) {
+                await this.#refuseUnnamedDependencies(session, [upgraded, ...automatic], rerun);
+                await this.#refuseChoiceDependencies(staging, [upgraded, ...automatic], automatic, rerun);
+                debug('Upgrade installs new required dependencies', {
+                    plugin: id,
+                    to: upgraded.version,
+                    dependencies: automatic.map((plugin) => `${plugin.id}@${plugin.version}`),
+                });
+            }
+            await this.#verifyUpgradeOthers(session, staging, others, warnings);
+            const ordered = await this.#order(staging, [...state.plugins.map((plugin) => (plugin.id === id ? upgraded : plugin)), ...automatic], session.required);
             const installation = state.installations[id] ?? defaultInstallation(current);
-            let configSource = session.configSource;
+            const projectPackages = Object.keys(await this.#installedDependencies(staging));
+            const validator = new PluginOptionsValidator({ allErrors: true });
+            const autoIds = new Set(automatic.map((plugin) => plugin.id));
+            const pending = {
+                configSource: session.configSource,
+                installations: { ...state.installations },
+                examples: [],
+                envSecrets: [],
+                generatedSecrets: [],
+                warnings,
+            };
+            for (const plugin of ordered.filter((item) => autoIds.has(item.id)))
+                await this.#planInstall(session, staging, plugin, ordered, projectPackages, validator, pending);
+            let configSource = pending.configSource;
             let config = parseProjectConfig(configSource);
-            const projectPackages = Object.keys(after);
             const plan = await planLifecycle({
                 base: staging,
                 plugin: upgraded,
@@ -828,59 +1689,154 @@ export class Project {
                 installation: installation.entry ? { entry: installation.entry } : {},
             });
             if (plan.entry && installation.entry && plan.entry.target !== installation.entry)
-                throw new CliError('UPGRADE_ENTRY_MOVED', id);
-            configSource = applyConfigChanges(configSource, id, plan.configChanges);
+                throw new CliError('UPGRADE_ENTRY_MOVED', `${id} ${upgraded.version} moves its entry file from ${installation.entry} to ${plan.entry.target}; upgrade does not move user files`, {
+                    details: {
+                        plugin: id,
+                        from: current.version,
+                        to: upgraded.version,
+                        entry: installation.entry,
+                        target: plan.entry.target,
+                        fix: `move ${installation.entry} to ${plan.entry.target} yourself (it is your code), or stay on ${current.version}`,
+                    },
+                    phase: 'plan',
+                });
+            // The plugin's section: options.logging for the logger host (D-0151), else options.<id>.
+            const key = optionsKey(upgraded);
+            configSource = applyConfigChanges(configSource, key, plan.configChanges);
             for (const defaults of plan.defaults)
-                configSource = mergeInstallDefaults(configSource, id, defaults);
+                configSource = mergeInstallDefaults(configSource, key, defaults);
             config = parseProjectConfig(configSource);
-            const validator = new PluginOptionsValidator({ allErrors: true });
-            const initial = await validator.check(staging, upgraded, optionsOf(config.options, id));
-            configSource = scaffoldConfig(configSource, id, initial.schema);
+            const initial = await validator.check(staging, upgraded, optionsOf(config.options, key));
+            configSource = scaffoldConfig(configSource, key, initial.schema);
+            if (initial.schema)
+                session.schemas.set(key, initial.schema);
             config = parseProjectConfig(configSource);
             const installations = {
-                ...state.installations,
+                ...pending.installations,
                 [id]: {
                     requires: plan.requires,
                     directories: union(installation.directories, plan.directories ?? []),
                     ...(plan.entry ? { entry: plan.entry.target } : {}),
                 },
             };
-            const warnings = [];
             const configRequired = [];
             await this.#check(staging, ordered, config, installations, projectPackages, { id, requires: plan.requires }, configRequired, warnings);
             await this.#validateOptions(validator, staging, ordered, config, configRequired);
+            // A new dependency that would be left without its required values is the user's to set up:
+            // nothing is written, `add` reports the values (D-0116).
+            const unset = configRequired.filter((item) => autoIds.has(item.plugin));
+            if (unset.length) {
+                const first = unset[0];
+                const dependency = automatic.find((plugin) => plugin.id === first.plugin);
+                throw missingDependency(requirerOf([upgraded, ...automatic], dependency.id), declaredDependency([upgraded, ...automatic], dependency.id), {
+                    reason: 'needs-settings',
+                    package: dependency.packageName,
+                    why: `${dependency.id} needs settings of its own (${unset.map((item) => item.plugin).join(', ')}), so the upgrade does not install it`,
+                    afterwards: rerun,
+                    extra: { configRequired: unset },
+                });
+            }
             for (const directory of plan.directories ?? [])
                 await tx.ensureDirectory(directory);
             const details = await this.#reconcileFiles(tx, staging, state, upgraded, this.#planFiles(plan));
-            await this.#syncExample(tx, session.root, id, warnings, {
-                changes: plan.configChanges,
-                defaults: plan.defaults,
-                schema: initial.schema,
-            });
+            await this.#syncExamples(tx, session.root, warnings, [
+                ...pending.examples,
+                {
+                    id: optionsKey(upgraded),
+                    update: {
+                        changes: plan.configChanges,
+                        defaults: plan.defaults,
+                        schema: initial.schema,
+                    },
+                },
+            ]);
             state.plugins = ordered;
             state.installations = installations;
-            await this.writeConfiguration(tx, state, configSource);
+            await this.writeConfiguration(tx, state, configSource, session.configFile);
+            const generatedSecrets = [
+                ...pending.generatedSecrets,
+                ...(await this.#generateEnvSecrets(session, pending.envSecrets)),
+            ];
             await this.#syncGuide(session, staging, ordered, warnings);
+            // S-c: copies of this plugin's templates (owner: user) keep what they had; the fixes the
+            // new templates carry and the copies lack are named, as doctor will (TEMPLATE_FIX_MISSING).
+            const touched = new Set([id, ...autoIds]);
+            const appsHost = ordered.find((plugin) => plugin.hosts?.includes('apps'));
+            for (const item of await templateFixes(session.root, staging, {
+                db: ordered.find((plugin) => plugin.id === 'dokebi-db')?.packageName,
+                apps: appsHost ? { id: appsHost.id, packageName: appsHost.packageName } : undefined,
+                inertia: ordered.some((plugin) => plugin.id === 'dokebi-template-inertia'),
+            }))
+                if (touched.has(item.plugin ?? '') ||
+                    (item.path.startsWith('vite.') && touched.has('dokebi-template-inertia')))
+                    warnings.push({
+                        code: item.code,
+                        path: item.path,
+                        ...(item.plugin ? { plugin: item.plugin } : {}),
+                        ...(item.hint ? { hint: item.hint } : {}),
+                    });
             await this.#replacePackages(session, staging, session.pkg);
+            const nextSteps = automatic
+                .filter((plugin) => plugin.documentation)
+                .map((plugin) => ({
+                command: `npx dokebi plugins doc ${plugin.id} --json`,
+                why: `${id} ${upgraded.version} requires it, so the upgrade installed it: read node_modules/${plugin.packageName}/${plugin.documentation} (the installed ${plugin.version} contract)`,
+            }));
             const result = {
                 changed: tx.paths,
                 preserved: details.map((detail) => detail.path),
                 ...(details.length ? { preservedDetails: details } : {}),
                 ...(configRequired.length ? { configRequired } : {}),
+                ...(automatic.length
+                    ? {
+                        autoInstalled: automatic.map(({ id, packageName, version }) => ({
+                            id,
+                            packageName,
+                            version,
+                        })),
+                    }
+                    : {}),
                 ...(warnings.length ? { warnings } : {}),
-                ...(sameVersion ? { reason: 'MANIFEST_CHANGED' } : {}),
+                ...(generatedSecrets.length ? { generatedSecrets } : {}),
+                ...(sameVersion
+                    ? {
+                        reason: contentChanged ? 'PACKAGE_CHANGED' : 'MANIFEST_CHANGED',
+                    }
+                    : {}),
                 from: current.version,
                 to: upgraded.version,
+                ...(nextSteps.length ? { nextSteps } : {}),
             };
             return await this.#finish(session, result, dryRun);
         }
+        catch (error) {
+            // R4CB-4: after a termination signal, whatever failed before the commit is INTERRUPTED.
+            throw tx.failure(error);
+        }
         finally {
             await tx.close();
         }
     }
+    /** Refresh only maintained AGENTS blocks; project instructions remain byte-for-byte intact. */
+    async syncGuide(root, dryRun = false) {
+        const session = await this.#begin(root);
+        try {
+            const warnings = [];
+            if (!(await exists(await securePath(session.root, AGENTS_FILE))))
+                throw new CliError('GUIDE_BLOCK_MISSING', 'AGENTS.md is missing; restore its project instructions before syncing');
+            await this.#syncGuide(session, session.root, session.state.plugins, warnings);
+            return await this.#finish(session, { changed: session.tx.paths, preserved: [], ...(warnings.length ? { warnings } : {}) }, dryRun);
+        }
+        finally {
+            await session.tx.close();
+        }
+    }
     /**
      * Rewrites the installed list in AGENTS.md (between the dokebi:installed markers) in the same
-     * transaction (D-0065). Missing markers leave the file alone with GUIDE_BLOCK_MISSING.
+     * transaction (D-0065). Missing markers leave the file alone with GUIDE_BLOCK_MISSING. The
+     * project block (dokebi:project markers, D-0077 G) is carried over as it is: only the installed
+     * list is replaced, an older file without the block gets an empty one at the end, and broken
+     * project markers leave the whole file alone with GUIDE_PROJECT_BLOCK_INVALID.
      */
     async #syncGuide(session, base, plugins, warnings) {
         if (!(await exists(await securePath(session.root, AGENTS_FILE))))
@@ -889,11 +1845,26 @@ export class Project {
         const devDependencies = object(session.pkg.devDependencies ?? {}, 'devDependencies');
         const cli = devDependencies['@dokebi/cli'];
         const block = installedBlock(guideEntries(await this.coreVersion(base), session.required, plugins, typeof cli === 'string' && /^\d+\.\d+\.\d+/.test(cli) ? cli : CLI_VERSION));
-        const next = replaceInstalledBlock(text, block);
-        if (next === undefined) {
+        const replaced = replaceInstalledBlock(text, block);
+        if (replaced === undefined) {
             warnings.push({ code: 'GUIDE_BLOCK_MISSING', path: AGENTS_FILE });
             return;
         }
+        const project = projectBlockState(text);
+        if (project === 'invalid') {
+            // Where the project's text begins and ends is not known: writing could cut into it.
+            debug('AGENTS.md left alone: project block markers are broken', { path: AGENTS_FILE });
+            warnings.push({ code: 'GUIDE_PROJECT_BLOCK_INVALID', path: AGENTS_FILE });
+            return;
+        }
+        const updated = syncCapabilityBlock(replaced, capabilityBlock(await loadCatalog()));
+        if (updated === undefined) {
+            warnings.push({ code: 'GUIDE_CAPABILITIES_BLOCK_INVALID', path: AGENTS_FILE });
+            return;
+        }
+        const next = project === 'missing' ? withProjectBlock(updated) : updated;
+        if (project === 'missing')
+            debug('AGENTS.md project block added', { path: AGENTS_FILE });
         if (next !== text)
             await session.tx.write(AGENTS_FILE, next);
     }
@@ -906,22 +1877,43 @@ export class Project {
         const { tx, state } = session;
         try {
             let configSource = session.configSource;
-            const warnings = [];
+            const warnings = envWarnings(session.root);
             const byPlugin = new Map();
             for (const { plugin, set } of assignments)
                 byPlugin.set(plugin, [...(byPlugin.get(plugin) ?? []), set]);
             const configRequired = [];
             const validator = new PluginOptionsValidator({ allErrors: true });
             for (const [id, sets] of byPlugin) {
-                const plugin = state.plugins.find((item) => item.id === id);
-                if (!plugin)
-                    throw new CliError('UNKNOWN_PLUGIN', `${id} is not installed`, {
-                        details: { plugin: id, installed: state.plugins.map((item) => item.id) },
-                        phase: 'arguments',
-                    });
-                configSource = applySetOptions(configSource, id, sets);
-                warnings.push(...setWarnings(sets).map((warning) => ({ ...warning, plugin: id })));
-                const checked = await validator.check(session.root, plugin, optionsOf(parseProjectConfig(configSource).options, id));
+                const plugin = sectionPlugin(state.plugins, id);
+                if (!plugin && id === 'logging') {
+                    // options.logging without the logger: core's level and plugins only (D-0047).
+                    checkCoreLogging(sets);
+                    configSource = applySetOptions(configSource, id, sets);
+                    continue;
+                }
+                if (!plugin && id === RELOAD_OPTIONS_KEY) {
+                    // options.reload: core's reload settings (D-0154), checked by core's declaration.
+                    configSource = applySetOptions(configSource, id, sets);
+                    checkCoreReload(optionsOf(parseProjectConfig(configSource).options, id));
+                    continue;
+                }
+                const settings = !plugin && (state.settings ?? []).includes(id);
+                // D-0155: a section nobody declares cannot be checked, so nothing is written to it.
+                if (!plugin && !settings)
+                    throw undeclaredSectionError(undeclaredSection(id, await catalogPackageOf(), state.plugins.map((item) => item.id), state.settings ?? []));
+                // The section of the plugin: options.<id>, options.logging for the logger (D-0151); an
+                // application settings section is its own name (D-0155).
+                const section = plugin ? optionsKey(plugin) : id;
+                configSource = applySetOptions(configSource, section, sets);
+                const value = optionsOf(parseProjectConfig(configSource).options, section);
+                const checked = plugin
+                    ? await validator.check(session.root, plugin, value)
+                    : await validator.checkSettings(session.root, section, value);
+                // An old name (D-0071 alias) and its field both set: valid by the schema, refused by the
+                // plugin at start (INVALID_OPTIONS conflict), so never written.
+                const conflicts = checked.schema ? aliasConflicts(value, checked.schema) : [];
+                if (conflicts.length)
+                    throw aliasConflictError(plugin?.id ?? id, section, conflicts);
                 if (checked.errors.every((error) => error.keyword === 'required')) {
                     if (checked.errors.length)
                         configRequired.push({
@@ -931,28 +1923,486 @@ export class Project {
                         });
                 }
                 else
-                    throw new CliError('INVALID_PLUGIN_OPTIONS', id, {
-                        details: {
+                    throw invalidPluginOptions(plugin?.id ?? id, checked.errors, 'arguments', section, 'schema', checked.schema);
+                // D-0162: the plugin's own rules (cross-field checks) once the schema passes, so a value
+                // the app would refuse at start is never written (R2 Claude T4: unknownDomain = an app name).
+                if (plugin && !checked.errors.length) {
+                    const verdict = (await checkPluginsOptions(session.root, [plugin], parseProjectConfig(configSource).options)).get(plugin.id);
+                    if (verdict && 'failed' in verdict)
+                        warnings.push({
+                            code: 'PLUGIN_OPTIONS_CHECK_FAILED',
                             plugin: id,
-                            errors: checked.errors.slice(0, 20),
-                            errorCount: checked.errors.length,
-                        },
+                            hint: `the plugin's own option rules could not run here (${verdict.failed}); npx dokebi start checks them too`,
+                        });
+                    else if (verdict?.issues.length)
+                        throw invalidPluginOptions(plugin.id, verdict.issues, 'arguments', section, 'rules');
+                }
+            }
+            const installations = { ...state.installations };
+            await this.#check(session.root, state.plugins, parseProjectConfig(configSource), installations, Object.keys(dependencyMap(session.pkg)), { id: '', requires: [] }, configRequired, warnings);
+            state.installations = installations;
+            const paths = filePaths([[session.configFile, session.configSource, configSource]]);
+            this.#checkPaths(paths, assignments.map(({ plugin, set }) => requestedPath(session.configSource, plugin, set.path)), dryRun, warnings);
+            await this.writeConfiguration(tx, state, configSource, session.configFile);
+            debug('Options set', { plugins: [...byPlugin.keys()], dryRun, file: session.configFile });
+            return {
+                ...(await this.#finish(session, {
+                    changed: tx.paths,
+                    preserved: [],
+                    paths,
+                    ...(configRequired.length ? { configRequired } : {}),
+                    ...(warnings.length ? { warnings } : {}),
+                }, dryRun)),
+                file: session.configFile,
+            };
+        }
+        catch (error) {
+            // R4CA-12: after a termination signal, whatever failed before the commit (a plugin check
+            // or a settings declaration the terminal's Ctrl+C reached too) is INTERRUPTED.
+            throw tx.failure(error);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /**
+     * `dokebi config unset <plugin>.<path>…` (D-0153): removes options from dokebi.yaml, and from
+     * dokebi.example.yaml where the sample has them, in one transaction. A path that is not set is
+     * a warning (OPTION_NOT_SET), not an error, so a repeated call changes nothing. Values are never
+     * returned or logged; removing a secret is allowed and warned (SECRET_REMOVED: what it signed
+     * no longer verifies). The plugin need not be installed (a section kept by `dokebi remove`).
+     * Removing may only leave issues the options already had, or missing required values
+     * (configRequired); issues that remain are a warning that carries the next fix.
+     */
+    async configUnset(root, targets, dryRun = false) {
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            let configSource = session.configSource;
+            const warnings = envWarnings(session.root);
+            const configRequired = [];
+            const removed = [];
+            const byPlugin = new Map();
+            for (const { plugin, path } of targets)
+                byPlugin.set(plugin, [...(byPlugin.get(plugin) ?? []), [...path]]);
+            const examplePath = await securePath(session.root, EXAMPLE);
+            const exampleSource = (await exists(examplePath)) ? await tx.read(EXAMPLE) : undefined;
+            let example = exampleSource;
+            const validator = new PluginOptionsValidator({ allErrors: true });
+            const key = (error) => `${error.keyword} ${error.instancePath} ${error.additionalProperty ?? ''}`;
+            const exampleHas = (name) => example !== undefined && Object.hasOwn(parseProjectConfig(example).options, name);
+            // The section each typed name means. Names that mean one section (the logger's plugin id
+            // and options.logging) are one group: their list indexes are all of the file as it is, so
+            // one removal never moves the item another index names.
+            const bySection = new Map();
+            for (const [section, paths] of byPlugin) {
+                let plugin = sectionPlugin(state.plugins, section);
+                let notRead;
+                // A section typed by its plugin id that a file still holds as written (the sample's old
+                // options.dokebi-logger, now options.logging): that section is meant, never the
+                // plugin's live options.
+                if (plugin &&
+                    optionsKey(plugin) !== section &&
+                    (Object.hasOwn(parseProjectConfig(configSource).options, section) || exampleHas(section))) {
+                    // Said once something of it is removed (below), never for a path it does not have.
+                    notRead = {
+                        code: 'SECTION_NOT_READ',
+                        plugin: section,
+                        hint: `options.${section} is not read: ${plugin.packageName} reads options.${optionsKey(plugin)}; removed as written (npx dokebi config unset ${optionsKey(plugin)}.<path> changes the live options)`,
+                    };
+                    plugin = undefined;
+                }
+                // The section of the plugin (options.logging for the logger, D-0151), else as typed.
+                const id = plugin ? optionsKey(plugin) : section;
+                const group = bySection.get(id);
+                if (group)
+                    group.paths.push(...paths);
+                else
+                    bySection.set(id, { plugin, notRead, paths: [...paths] });
+            }
+            for (const [id, { plugin, notRead, paths: asked }] of bySection) {
+                // The same path typed twice through two names is one path.
+                const paths = [...new Map(asked.map((path) => [path.join('.'), path])).values()];
+                const before = parseProjectConfig(configSource);
+                // D-0155: an application settings section is checked against its schema file too.
+                const settings = !plugin && (state.settings ?? []).includes(id);
+                const core = !plugin && (id === 'logging' || id === RELOAD_OPTIONS_KEY);
+                // A whole section only when nothing reads it: a plugin's, the application's settings or
+                // core's (logging, reload) are live options.
+                const read = plugin ||
+                    settings ||
+                    core ||
+                    readSections(state, [
+                        before.options,
+                        example === undefined ? {} : parseProjectConfig(example).options,
+                    ]).has(id);
+                if (paths.some((path) => path.length === 0) && read)
+                    throw new CliError('INVALID_SET', plugin
+                        ? `options.${id} is read by ${plugin.packageName}: name the options to remove, or remove the plugin (npx dokebi remove ${plugin.packageName})`
+                        : settings
+                            ? `options.${id} is the application's settings section: name the options to remove, or remove the section (npx dokebi settings remove ${id})`
+                            : core
+                                ? `options.${id} is read by core: name the options to remove`
+                                : `options.${id} is read by the application (a convention section such as application-runtime, or the first admin's): name the options to remove`, { phase: 'arguments', details: { section: id } });
+                if (!plugin && !settings && !core) {
+                    // A section nobody declares: removing what is there needs no schema (the section a
+                    // removed plugin left, D-0153), so it proceeds with the code config set would refuse.
+                    const found = undeclaredSection(id, await catalogPackageOf(), state.plugins.map((item) => item.id), state.settings ?? []);
+                    if (!Object.hasOwn(before.options, id) && !exampleHas(id))
+                        throw undeclaredSectionError(found);
+                    if (!notRead)
+                        warnings.push({
+                            code: found.code,
+                            plugin: id,
+                            hint: `${found.message}; ${found.details.fix}`,
+                        });
+                }
+                const checkSection = (options) => plugin
+                    ? validator.check(session.root, plugin, optionsOf(options, id))
+                    : validator.checkSettings(session.root, id, optionsOf(options, id));
+                const checkedBefore = plugin || settings ? await checkSection(before.options) : undefined;
+                const edited = applyUnsetOptions(configSource, id, paths);
+                // Secret or not is decided on the values being removed; nothing of them is kept.
+                for (const path of edited.removed) {
+                    const value = optionAtPath(configSource, id, path);
+                    if (commandLineSecret(path, value, checkedBefore?.schema ?? undefined))
+                        warnings.push({
+                            code: 'SECRET_REMOVED',
+                            plugin: id,
+                            path: [id, ...path].join('.'),
+                            hint: `what this secret signed no longer verifies once the app restarts; to replace a secret instead use npx dokebi config secret ${[id, ...path].join('.')} --rotate`,
+                        });
+                }
+                configSource = edited.source;
+                let inExample = [];
+                if (example !== undefined) {
+                    // A list item named by its index in dokebi.yaml is the same item in the sample only by
+                    // its name (or type): the two lists may have another order. One without either is not
+                    // touched in the sample (SAMPLE_ITEM_UNKNOWN).
+                    const pairs = [];
+                    for (const path of paths) {
+                        const named = namedItems(session.configSource, id, path);
+                        if (named)
+                            pairs.push({ asked: path, sample: named });
+                        else
+                            warnings.push({
+                                code: 'SAMPLE_ITEM_UNKNOWN',
+                                plugin: id,
+                                path: [id, ...path].join('.'),
+                                hint: 'the list item has no name or type, so the same item cannot be found in dokebi.example.yaml; it was left there (npx dokebi config diff names what differs)',
+                            });
+                    }
+                    // One item named two ways (`targets.studio`, `targets.3`) is one path in the sample.
+                    const sample = applyUnsetOptions(example, id, [
+                        ...new Map(pairs.map((pair) => [pair.sample.join('.'), pair.sample])).values(),
+                    ]);
+                    example = sample.source;
+                    // Reported as asked (the index of dokebi.yaml), whatever the sample's order.
+                    const gone = new Set(sample.removed.map((removedPath) => removedPath.join('.')));
+                    inExample = pairs
+                        .filter((pair) => gone.has(pair.sample.join('.')))
+                        .map((pair) => pair.asked);
+                }
+                if (notRead && (edited.removed.length || inExample.length))
+                    warnings.push(notRead);
+                for (const path of paths) {
+                    const option = [id, ...path].join('.');
+                    const files = [
+                        ...(edited.removed.some((item) => item.join('.') === path.join('.'))
+                            ? [session.configFile]
+                            : []),
+                        ...(inExample.some((item) => item.join('.') === path.join('.')) ? [EXAMPLE] : []),
+                    ];
+                    if (files.length)
+                        removed.push({ option, files });
+                    else
+                        warnings.push({ code: 'OPTION_NOT_SET', plugin: id, path: option });
+                }
+                if (!checkedBefore)
+                    continue;
+                const checked = await checkSection(parseProjectConfig(configSource).options);
+                const had = new Set(checkedBefore.errors.map(key));
+                const added = checked.errors.filter((error) => error.keyword !== 'required' && !had.has(key(error)));
+                if (added.length)
+                    throw invalidPluginOptions(plugin?.id ?? id, added, 'arguments', id, 'schema', checked.schema);
+                const required = checked.errors.filter((error) => error.keyword === 'required');
+                if (required.length)
+                    configRequired.push({
+                        plugin: id,
+                        errors: required.slice(0, 20),
+                        errorCount: required.length,
+                    });
+                const left = checked.errors.filter((error) => error.keyword !== 'required');
+                if (left.length)
+                    warnings.push({
+                        code: 'OPTIONS_STILL_INVALID',
+                        plugin: id,
+                        hint: optionsFix(plugin?.id ?? id, left, `correct options.${id} in dokebi.yaml (npx dokebi plugins info ${plugin?.id ?? id} --json lists the option keys)`, id, checked.schema),
                     });
             }
-            if (configSource !== session.configSource)
-                await tx.write(CONFIG_FILE, configSource);
-            debug('Options set', { plugins: [...byPlugin.keys()], dryRun });
-            return await this.#finish(session, {
-                changed: tx.paths,
-                preserved: [],
-                ...(configRequired.length ? { configRequired } : {}),
-                ...(warnings.length ? { warnings } : {}),
-            }, dryRun);
+            const installations = { ...state.installations };
+            await this.#check(session.root, state.plugins, parseProjectConfig(configSource), installations, Object.keys(dependencyMap(session.pkg)), { id: '', requires: [] }, configRequired, warnings);
+            const requirementsChanged = json(installations) !== json(state.installations);
+            state.installations = installations;
+            const paths = filePaths([
+                [session.configFile, session.configSource, configSource],
+                [EXAMPLE, exampleSource, example],
+            ]);
+            this.#checkPaths(paths, targets.map(({ plugin, path }) => requestedPath(session.configSource, plugin, path)), dryRun, warnings);
+            // Nothing set: nothing written (a requirement refreshed by the checks is written too).
+            if (configSource !== session.configSource || requirementsChanged)
+                await this.writeConfiguration(tx, state, configSource, session.configFile);
+            if (example !== undefined && example !== exampleSource)
+                await tx.write(EXAMPLE, example);
+            debug('Options unset', {
+                plugins: [...byPlugin.keys()],
+                removed: removed.length,
+                dryRun,
+            });
+            return {
+                ...(await this.#finish(session, {
+                    changed: tx.paths,
+                    preserved: [],
+                    paths,
+                    ...(configRequired.length ? { configRequired } : {}),
+                    ...(warnings.length ? { warnings } : {}),
+                }, dryRun)),
+                file: session.configFile,
+                removed,
+            };
+        }
+        catch (error) {
+            // R4CA-12: after a termination signal, whatever failed before the commit (a plugin check
+            // or a settings declaration the terminal's Ctrl+C reached too) is INTERRUPTED.
+            throw tx.failure(error);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /**
+     * A config command may change only what it was asked for: a changed option path outside the
+     * requested ones (an alias that reaches another section, a renamed or old section) is refused
+     * before anything is written, or warned in a dry run so the plan shows it (PATH_MISMATCH).
+     */
+    #checkPaths(paths, requested, dryRun, warnings) {
+        const outside = outsideRequested(paths, requested);
+        if (!outside.length)
+            return;
+        const asked = requested.map((path) => path.join('.'));
+        const message = `The command would change ${outside.join(', ')}, which it was not asked for (asked: ${asked.join(', ')})`;
+        const fix = 'name the options as the files spell them (npx dokebi config show lists them; the logger options are logging.<path>), then run it again';
+        debug('Config change reaches options it was not asked for', { outside, asked, dryRun });
+        if (!dryRun)
+            throw new CliError('PATH_MISMATCH', message, {
+                phase: 'plan',
+                details: { requested: asked, outside, paths, fix },
+            });
+        warnings.push({ code: 'PATH_MISMATCH', hint: `${message}; ${fix}` });
+    }
+    /**
+     * `dokebi config diff [<id>] --write` (AI-M46): copies the options only in dokebi.yaml into
+     * dokebi.example.yaml without their secrets, in one transaction. Paths both files set keep the
+     * sample's value (a sample may differ) unless `values` (`--values`, Studio v2) writes
+     * dokebi.yaml's; secrets inside a copied path are left out. The written sample is compared
+     * again and refused if it would hold a secret (fail closed).
+     */
+    async configSample(root, section, dryRun = false, prune = false, values = false) {
+        const session = await this.#begin(root);
+        const { tx } = session;
+        try {
+            const examplePath = await securePath(session.root, EXAMPLE);
+            if (!(await exists(examplePath)))
+                throw new CliError('EXAMPLE_MISSING', `No ${EXAMPLE} to write (it is the sample of dokebi.yaml without secrets)`, { phase: 'arguments', details: { root: session.root, file: EXAMPLE } });
+            const exampleSource = await tx.read(EXAMPLE);
+            const found = await sampleAdditions(session.root, session.configSource, exampleSource, section, session.configFile);
+            let example = exampleSource;
+            const bySection = new Map();
+            const queue = (op, items) => {
+                for (const { path, value } of items) {
+                    const [id, ...rest] = path;
+                    if (id === undefined)
+                        continue;
+                    // A whole section the sample lacks goes in by its keys: edit creates options.<id>
+                    // first, so a default at the section itself found it there and wrote nothing.
+                    const entries = rest.length === 0 &&
+                        value !== null &&
+                        typeof value === 'object' &&
+                        !Array.isArray(value)
+                        ? Object.entries(value).map(([key, item]) => ({ op, path: [key], value: item }))
+                        : [{ op, path: rest, value }];
+                    bySection.set(id, [...(bySection.get(id) ?? []), ...entries]);
+                }
+            };
+            queue('default', found.additions);
+            if (values)
+                queue('set', found.changes);
+            // A section the sample lacks is created (edit makes options.<id> a mapping first).
+            for (const [id, changes] of bySection)
+                example = applyConfigChanges(example, id, changes);
+            // --prune removes from the sample only what nothing reads — a section no installed plugin,
+            // settings declaration or core reads (an old options.dokebi-logger), and the keys a schema
+            // does not declare (an option a plugin dropped) — and secrets with a value in it. A
+            // declared option only the sample shows stays (a documented value is the sample's job).
+            // dokebi.yaml is never touched.
+            const pruned = [];
+            if (prune) {
+                const targets = new Map();
+                const add = (id, path) => targets.set(id, [...(targets.get(id) ?? []), path]);
+                const validator = new PluginOptionsValidator({ allErrors: true });
+                const options = parseProjectConfig(example).options;
+                const read = readSections(session.state, [
+                    parseProjectConfig(session.configSource).options,
+                    options,
+                ]);
+                const schemas = new Map();
+                /** Keys of the sample the schema refuses as unknown (`additionalProperties`), dotted. */
+                const unknownKeys = new Map();
+                const schemaOf = async (id) => {
+                    if (schemas.has(id))
+                        return schemas.get(id);
+                    const plugin = session.state.plugins.find((item) => optionsKey(item) === id);
+                    const settings = (session.state.settings ?? []).includes(id);
+                    const checked = plugin
+                        ? await validator.check(session.root, plugin, optionsOf(options, id))
+                        : settings
+                            ? await validator.checkSettings(session.root, id, optionsOf(options, id))
+                            : undefined;
+                    const schema = checked?.schema && typeof checked.schema === 'object'
+                        ? checked.schema
+                        : undefined;
+                    schemas.set(id, schema);
+                    unknownKeys.set(id, new Set(unknownOptionPaths(id, checked?.errors ?? []).paths));
+                    return schema;
+                };
+                // Leaked secrets: what config diff calls one (a schema mark, a name — unless the schema
+                // marks it plain — or a URL with a password).
+                for (const [id, ...rest] of found.prunable)
+                    if (id !== undefined)
+                        add(id, rest);
+                for (const id of Object.keys(options)) {
+                    if (section !== undefined && id !== section)
+                        continue;
+                    if (!read.has(id)) {
+                        add(id, []);
+                        continue;
+                    }
+                    const schema = await schemaOf(id);
+                    // Only a schema that lists its keys at the top can say which key it does not declare.
+                    if (!schema ||
+                        typeof schema.properties !== 'object' ||
+                        ['$ref', 'allOf', 'anyOf', 'oneOf'].some((key) => key in schema))
+                        continue;
+                    // A key no property declares is pruned only when the schema also refuses it: an object
+                    // that leaves additionalProperties out takes any key (JSON Schema), so it is an option.
+                    for (const path of pruneUndeclared(example, id, null, schema).kept)
+                        if (unknownKeys.get(id)?.has(`${id}.${path}`))
+                            add(id, path.split('.'));
+                }
+                // Never what this same call copied in.
+                const copied = new Set([...found.additions, ...(values ? found.changes : [])].map((item) => item.path.join('.')));
+                for (const [id, paths] of targets)
+                    targets.set(id, paths.filter((path) => {
+                        const at = [id, ...path].join('.');
+                        return ![...copied].some((written) => written === at || written.startsWith(`${at}.`) || at.startsWith(`${written}.`));
+                    }));
+                for (const [id, paths] of targets) {
+                    // A whole section first covers whatever was named inside it.
+                    const unique = paths.some((path) => path.length === 0)
+                        ? [[]]
+                        : [...new Map(paths.map((path) => [path.join('.'), path])).values()];
+                    const removed = applyUnsetOptions(example, id, unique);
+                    example = removed.source;
+                    for (const path of removed.removed)
+                        pruned.push([id, ...path].join('.'));
+                }
+            }
+            const after = await sampleAdditions(session.root, session.configSource, example, section, session.configFile);
+            if (after.result.exampleSecrets.length > (prune ? 0 : found.result.exampleSecrets.length))
+                throw new CliError('SAMPLE_SECRET', `The copy would put a secret into ${EXAMPLE}; nothing was written`, { details: { paths: after.result.exampleSecrets } });
+            if (example !== exampleSource)
+                await tx.write(EXAMPLE, example);
+            const paths = filePaths([[EXAMPLE, exampleSource, example]]);
+            const written = found.additions.map((item) => item.path.join('.'));
+            const valuesWritten = values ? found.changes.map((item) => item.path.join('.')) : undefined;
+            debug('Sample settings written', {
+                section: section ?? null,
+                written: written.length,
+                ...(valuesWritten ? { valuesWritten: valuesWritten.length } : {}),
+                dryRun,
+            });
+            const warnings = envWarnings(session.root);
+            return {
+                ...(await this.#finish(session, { changed: tx.paths, preserved: [], paths, ...(warnings.length ? { warnings } : {}) }, dryRun)),
+                file: session.configFile,
+                written,
+                pruned,
+                ...(valuesWritten ? { valuesWritten } : {}),
+                diff: after.result,
+            };
+        }
+        catch (error) {
+            // R4CA-12: after a termination signal, whatever failed before the commit (a plugin check
+            // or a settings declaration the terminal's Ctrl+C reached too) is INTERRUPTED.
+            throw tx.failure(error);
         }
         finally {
             await tx.close();
         }
     }
+    /**
+     * D-0145: keeps the migrations folder out of the project's code formatters, so an applied
+     * migration keeps its bytes: a CLI-owned entry in .prettierignore, `!<folder>` in biome.json
+     * files.includes. A formatter the CLI cannot configure (biome.jsonc with comments, an ESLint
+     * config with formatting rules) is a warning with the fix. Only for a project with migrations
+     * (dokebi-migrate installed, or the folder present).
+     */
+    async #protectMigrations(session, plugins, warnings) {
+        const { root, tx } = session;
+        const migrations = await migrationsFolder(root);
+        // R1 measurement: the registration the CLI writes, too (a reformatted copy is
+        // MODIFIED_REGISTRATION); the migrations folder only in a project with migrations.
+        const targets = [GENERATED_FILE];
+        if (plugins.some((plugin) => plugin.id === 'dokebi-migrate') ||
+            (await exists(await securePath(root, migrations))))
+            targets.push(migrations);
+        // Each config file is written once (the transaction refuses a second write of one path): the
+        // texts are built over every target first.
+        const texts = new Map();
+        const text = async (path, fallback) => {
+            const known = texts.get(path);
+            if (known !== undefined)
+                return known;
+            return (await exists(await securePath(root, path))) ? await tx.read(path) : fallback;
+        };
+        for (const folder of targets)
+            for (const use of await formatterUses(root, folder)) {
+                if (use.covered)
+                    continue;
+                if (use.tool === 'prettier') {
+                    texts.set(PRETTIER_IGNORE, prettierIgnoreText(await text(PRETTIER_IGNORE, ''), folder));
+                    debug('Kept out of prettier', { folder, config: use.config });
+                    continue;
+                }
+                if (use.tool === 'biome') {
+                    const edited = biomeConfigText(await text(use.config, ''), folder, biomeMajor(session.pkg) === 1);
+                    if (edited !== undefined) {
+                        texts.set(use.config, edited);
+                        debug('Kept out of biome', { folder, config: use.config });
+                        continue;
+                    }
+                }
+                warnings.push({
+                    code: folder === GENERATED_FILE
+                        ? 'FORMATTER_FORMATS_GENERATED'
+                        : 'FORMATTER_FORMATS_MIGRATIONS',
+                    path: use.config,
+                    hint: formatterFix(use, folder),
+                });
+            }
+        for (const [path, content] of texts)
+            await tx.write(path, content);
+    }
     /** Adds `.env` to .gitignore unless a line already ignores it (D-0065, D-0073). */
     async #ignoreEnv(session) {
         const { tx } = session;
@@ -962,9 +2412,10 @@ export class Project {
             await tx.write('.gitignore', `${ignore}${ignore && !ignore.endsWith('\n') ? '\n' : ''}${ENV_FILE}\n`);
     }
     /**
-     * D-0073: a generated secret (48 random bytes, base64url) in .env for each variable an install
-     * plan names (`envSecrets`), unless the CLI's environment or .env already has it. The value is
-     * never returned, printed or logged; .env is git-ignored and read by dev, start and verify.
+     * D-0073 §2, deprecated (addendum 2; removed in 0.5): a generated secret (48 random bytes,
+     * base64url) in .env for each variable an install plan names (`envSecrets`), unless the CLI's
+     * environment or .env already has it. The value is never returned, printed or logged; .env is
+     * git-ignored and read by dev, start and verify.
      */
     async #generateEnvSecrets(session, requests) {
         if (!requests.length)
@@ -972,9 +2423,9 @@ export class Project {
         const { tx } = session;
         const envPath = await securePath(session.root, ENV_FILE);
         const original = (await exists(envPath)) ? await tx.read(ENV_FILE) : '';
-        // Never append to a file the apps could not read (ENV_FILE_INVALID names the line).
-        checkEnvText(original);
-        const present = parseEnv(original);
+        // Never append to a file the apps could not read (ENV_FILE_INVALID names the line); read as
+        // the apps read it (R4CA-11: a byte order mark is not part of the first name).
+        const present = parseEnvText(original);
         let text = original;
         const generated = [];
         for (const { plugin, variable } of requests) {
@@ -998,9 +2449,10 @@ export class Project {
         return generated;
     }
     /**
-     * `dokebi dev-infra` (D-0065): compose.yaml for the database of connection `main`, a generated
-     * password in .env (git-ignored) and the matching URL in dokebi.yaml. An existing compose.yaml
-     * with a `db` service and an existing password are kept; nothing is started here.
+     * `dokebi dev-infra` (D-0065): compose.yaml for the database of connection `main` and the URL
+     * with a generated password in dokebi.yaml (no .env is written; a legacy .env password is reused
+     * only when the YAML has no URL). An existing compose.yaml with a `db` service and an existing
+     * password are kept; nothing is started here.
      */
     async devInfra(root, options = {}) {
         const session = await this.#begin(root);
@@ -1022,17 +2474,105 @@ export class Project {
                 });
             const warnings = [];
             let port = options.dbPort ?? docker.port;
+            // D-0103: a MongoDB is generated as a single-node replica set; a kept file decides.
+            let replicaSet = replicaSetOf(docker);
             const composePath = await securePath(session.root, COMPOSE_FILE);
+            let composeUnset = [];
             if (await exists(composePath)) {
-                const existing = parse(await tx.read(COMPOSE_FILE));
+                const composeSource = await tx.read(COMPOSE_FILE);
+                // R2 Codex T2: a kept file may need variables dev-infra up does not set; the plan says
+                // so before it names dev-infra up as the next step.
+                const envPath = await securePath(session.root, ENV_FILE);
+                composeUnset = composeUnsetVariables(composeSource, [
+                    // D-0165: the passwords of dokebi.yaml that dev-infra up passes.
+                    ...Object.keys(connectionSecrets(parseProjectConfig(session.configSource).options)),
+                    ...((await exists(envPath)) ? envKeys(await readFile(envPath, 'utf8')) : []),
+                ]);
+                if (composeUnset.length)
+                    warnings.push({
+                        code: 'COMPOSE_VARIABLES_UNSET',
+                        path: COMPOSE_FILE,
+                        hint: composeVariablesHint(composeUnset),
+                    });
+                const existing = parse(composeSource);
                 const service = existing?.services?.[DB_SERVICE];
                 if (!service)
                     throw new CliError('COMPOSE_CONFLICT', `${COMPOSE_FILE} exists without a "${DB_SERVICE}" service; add the service yourself or move the file`, { details: { file: COMPOSE_FILE } });
-                // The kept file decides the published port.
-                const published = String(service.ports?.[0] ?? '').match(/(?:^|:)(\d+):\d+$/)?.[1];
-                if (published)
-                    port = Number(published);
-                warnings.push({ code: 'COMPOSE_KEPT', path: COMPOSE_FILE });
+                // The kept file decides the published port, unless --db-port changes it: then only that
+                // port entry is rewritten (the rest of the user's file stays as it is).
+                const published = composePublishedPort(composeSource);
+                const portFix = `set the first ports entry of services.${DB_SERVICE} in ${COMPOSE_FILE} to "127.0.0.1:<host port>:${docker.port}" yourself, then run npx dokebi dev-infra --json again`;
+                if (options.dbPort !== undefined && options.dbPort !== published) {
+                    const rewritten = withComposePort(composeSource, options.dbPort);
+                    if (rewritten === undefined)
+                        throw new CliError('COMPOSE_PORT_UNKNOWN', `--db-port ${options.dbPort} was not applied: ${COMPOSE_FILE} publishes the ${DB_SERVICE} port in a form the CLI does not rewrite`, { phase: 'arguments', details: { file: COMPOSE_FILE, fix: portFix } });
+                    if (await portInUse(options.dbPort)) {
+                        const alternative = await freePortAfter(options.dbPort);
+                        throw new CliError('PORT_IN_USE', `Port ${options.dbPort} on 127.0.0.1 is in use`, {
+                            phase: 'arguments',
+                            details: {
+                                port: options.dbPort,
+                                ...(alternative ? { alternative } : {}),
+                                hint: `run again with --db-port ${alternative ?? '<free port>'}; compose.yaml and dokebi.yaml get the same port`,
+                                ...portQuestion({
+                                    what: 'Database',
+                                    port: options.dbPort,
+                                    alternative,
+                                    flag: '--db-port',
+                                    delegated: false,
+                                }),
+                            },
+                        });
+                    }
+                    await tx.write(COMPOSE_FILE, rewritten);
+                    port = options.dbPort;
+                    debug('Kept compose.yaml gets another published port', { from: published, to: port });
+                    warnings.push({
+                        code: 'COMPOSE_PORT_CHANGED',
+                        path: COMPOSE_FILE,
+                        hint: `only the published port of services.${DB_SERVICE} changed (${published} to ${port}); npx dokebi dev-infra up recreates a running container on the new port and keeps its data volume`,
+                    });
+                }
+                else if (published !== undefined) {
+                    port = published;
+                    warnings.push({ code: 'COMPOSE_KEPT', path: COMPOSE_FILE });
+                }
+                else {
+                    // Unreadable (a variable, a range): the port of the URL already in dokebi.yaml stays
+                    // (the catalog port for a first URL), and the warning says which one.
+                    const configured = main.options?.url;
+                    if (typeof configured === 'string' && !configured.startsWith(URL_PLACEHOLDER_PREFIX)) {
+                        let kept;
+                        try {
+                            kept = Number(new URL(configured).port) || undefined;
+                        }
+                        catch (error) {
+                            // The password-free reason only; the URL check below refuses it with its code.
+                            debug('The main database URL could not be read for its port', {
+                                code: error.code,
+                            });
+                        }
+                        if (kept)
+                            port = kept;
+                    }
+                    warnings.push({ code: 'COMPOSE_KEPT', path: COMPOSE_FILE });
+                    warnings.push({
+                        code: 'COMPOSE_PORT_UNKNOWN',
+                        path: COMPOSE_FILE,
+                        hint: `the published port of services.${DB_SERVICE} could not be read, so the URL in dokebi.yaml uses port ${port}; if the file publishes another one, ${portFix}`,
+                    });
+                }
+                if (replicaSet && !runsReplicaSet(service)) {
+                    // Written before D-0103: the URL stays a standalone one, or the driver would wait for
+                    // a replica set that is not there. Transactions need the regenerated file.
+                    debug('Kept compose.yaml runs a standalone MongoDB', { file: COMPOSE_FILE });
+                    replicaSet = undefined;
+                    warnings.push({
+                        code: 'DEV_INFRA_STANDALONE',
+                        path: COMPOSE_FILE,
+                        hint: `${COMPOSE_FILE} runs a standalone MongoDB, which refuses multi-document transactions. To make it the single-node replica set ${replicaSetOf(docker)}: npx dokebi dev-infra down, move ${COMPOSE_FILE} away (carry over your own changes later), npx dokebi dev-infra (a new file on the same port with --db-port ${port}; the password and the data volume are kept), npx dokebi dev-infra up`,
+                    });
+                }
             }
             else {
                 // The container would not start on a taken port: refuse, and name a free one.
@@ -1057,42 +2597,65 @@ export class Project {
                 }
                 await tx.write(COMPOSE_FILE, composeText(composeProject(String(session.pkg.name ?? '')), variant.name, docker, port));
             }
-            const envPath = await securePath(session.root, ENV_FILE);
-            const envText = (await exists(envPath)) ? await tx.read(ENV_FILE) : '';
-            let password = envValue(envText, PASSWORD_VARIABLE);
-            if (!password) {
-                password = generatePassword();
-                await tx.write(ENV_FILE, withEnv(envText, PASSWORD_VARIABLE, password, 'development database password (dokebi dev-infra); not committed'));
+            // Reuse the YAML credential on reruns. Read legacy .env only when no YAML URL exists;
+            // never rotate an existing database password or rewrite the user's legacy file.
+            const currentUrl = main.options?.url;
+            let password;
+            if (typeof currentUrl === 'string' && !currentUrl.startsWith(URL_PLACEHOLDER_PREFIX)) {
+                try {
+                    password = decodeURIComponent(new URL(currentUrl).password);
+                }
+                catch {
+                    // dokebi-check: allow missing-cause the URL error carries its input, which holds the database password
+                    throw new CliError('DEV_INFRA_CONFIG_INVALID', 'The main database URL is invalid');
+                }
+            }
+            else {
+                const envPath = await securePath(session.root, ENV_FILE);
+                if (await exists(envPath))
+                    password = envValue(await tx.read(ENV_FILE), PASSWORD_VARIABLE);
             }
-            const url = connectionUrl(docker, password, port);
+            password ??= generatePassword();
+            const url = connectionUrl(docker, password, port, replicaSet);
             const current = main.options?.url;
             if (current !== url) {
                 if (typeof current === 'string' && !current.startsWith(URL_PLACEHOLDER_PREFIX))
                     warnings.push({
                         code: 'URL_REPLACED',
-                        path: 'dokebi.yaml#options.dokebi-db.connections.main',
+                        path: `${session.configFile}#options.dokebi-db.connections.main`,
                     });
-                await tx.write(CONFIG_FILE, applyConfigChanges(session.configSource, 'dokebi-db', [
+                await tx.write(session.configFile, applyConfigChanges(session.configSource, 'dokebi-db', [
                     { op: 'remove', path: ['connections', 'main', 'options', 'url'] },
                     { op: 'default', path: ['connections', 'main', 'options', 'url'], value: url },
                 ]));
             }
             await this.#ignoreEnv(session);
-            debug('Development database prepared', { variant: variant.name, port, image: docker.image });
+            debug('Development database prepared', {
+                variant: variant.name,
+                port,
+                image: docker.image,
+                replicaSet: replicaSet ?? null,
+            });
             return {
                 ...(await this.#finish(session, {
                     changed: tx.paths,
-                    preserved: warnings.map((warning) => warning.path ?? '').filter(Boolean),
+                    // What was kept as it is: a compose.yaml the run did not touch (a replaced URL or a
+                    // rewritten port is a change, not a kept file).
+                    preserved: warnings.some((warning) => warning.code === 'COMPOSE_KEPT')
+                        ? [COMPOSE_FILE]
+                        : [],
                     ...(warnings.length ? { warnings } : {}),
                     nextSteps: [
                         {
-                            command: 'docker compose up -d --wait',
-                            why: `start the ${variant.name} container (${docker.image}) on 127.0.0.1:${port}`,
+                            command: 'npx dokebi dev-infra up --json',
+                            why: composeUnset.length
+                                ? `first give ${composeUnset.join(', ')} a default in ${COMPOSE_FILE} or a value in ${ENV_FILE} (COMPOSE_VARIABLES_UNSET); then it starts the ${variant.name} container (${docker.image}) on 127.0.0.1:${port}`
+                                : `start the ${variant.name} container (${docker.image}) on 127.0.0.1:${port}`,
                         },
                         { command: 'npx dokebi verify --json', why: 'start the app against it and check it' },
                         {
-                            command: 'docker compose down',
-                            why: 'stop it when you are done (add -v to delete the data volume)',
+                            command: 'npx dokebi dev-infra down --json',
+                            why: 'stop it when you are done (data volumes are retained)',
                         },
                     ],
                 }, options.dryRun)),
@@ -1101,9 +2664,10 @@ export class Project {
                     variant: variant.name,
                     image: docker.image,
                     port,
+                    ...(replicaSet ? { replicaSet } : {}),
                     url: redactUrl(url),
                     compose: COMPOSE_FILE,
-                    passwordIn: ENV_FILE,
+                    passwordIn: session.configFile,
                 },
             };
         }
@@ -1111,55 +2675,395 @@ export class Project {
             await tx.close();
         }
     }
+    /**
+     * dokebi.yaml source with a generated random secret (32 bytes, base64url) at `<id>.<path>`: a
+     * string, or a one-item list when the schema wants a list. Shared by `config secret` and the
+     * `configSecrets` of `add`. Schema errors the source already had do not count against a shape.
+     */
+    async #withGeneratedSecret(root, validator, plugin, source, path, secret = randomBytes(32).toString('base64url')) {
+        // The plugin's section: options.<id>, options.logging for the logger host (D-0151).
+        const id = targetSection(plugin);
+        const where = `${id}.${path.join('.')}`;
+        const key = (error) => `${error.keyword} ${error.instancePath}`;
+        const options = (text) => optionsOf(parseProjectConfig(text).options, id);
+        const before = new Set((await checkTarget(validator, root, plugin, options(source))).errors.map(key));
+        for (const value of [secret, [secret]]) {
+            const candidate = applySetOptions(source, id, [{ path: [...path], value }]);
+            const checked = await checkTarget(validator, root, plugin, options(candidate));
+            if (checked.errors.every((error) => error.keyword === 'required' || before.has(key(error))))
+                return { source: candidate, list: Array.isArray(value) };
+        }
+        throw new CliError('INVALID_PLUGIN_OPTIONS', `${where} does not take a secret string`, {
+            details: { plugin: id, path: where },
+        });
+    }
     /**
      * `dokebi config secret <plugin>.<path>`: a generated random secret (32 bytes, base64url) in
      * dokebi.yaml, as a one-item list when the schema wants a list. The value is never returned or
-     * logged; an existing value is kept (SECRET_KEPT). Secrets never pass the command line.
+     * logged; an existing value is kept (SECRET_KEPT) unless `rotate` (`--rotate`, AI-M05): a string
+     * is replaced; a list gets the new secret first (it signs) and keeps the previous ones after it,
+     * at most ROTATE_KEEP of them (older ones are dropped: SECRETS_DROPPED), so what the old ones
+     * signed still verifies during the rotation. Secrets never pass the command line. `value`
+     * (`--stdin`, D-0151 follow-up): a secret someone else issued, such as the token of a log
+     * receiver (`logging.targets.studio.token`), written instead of a generated one; never returned
+     * or logged either. A list item is named by its `name` (else `type`) or its index.
      */
-    async configSecret(root, id, path, dryRun = false) {
+    async configSecret(root, id, path, dryRun = false, rotate = false, value) {
         const session = await this.#begin(root);
         const { tx, state } = session;
         try {
-            const plugin = state.plugins.find((item) => item.id === id);
-            if (!plugin)
-                throw new CliError('UNKNOWN_PLUGIN', `${id} is not installed`, {
-                    details: { plugin: id, installed: state.plugins.map((item) => item.id) },
+            const installed = sectionPlugin(state.plugins, id);
+            // D-0155: an application settings section takes secrets like a plugin's.
+            const plugin = installed ?? ((state.settings ?? []).includes(id) ? { settingsSection: id } : undefined);
+            if (!plugin && id === RELOAD_OPTIONS_KEY)
+                throw new CliError('INVALID_SET', 'options.reload holds no secrets', {
+                    details: { section: id, fix: 'set its values with npx dokebi config set reload.<key>=…' },
                     phase: 'arguments',
                 });
+            // D-0155: a section nobody declares cannot say which value is a secret: refused.
+            if (!plugin)
+                throw undeclaredSectionError(undeclaredSection(id, await catalogPackageOf(), state.plugins.map((item) => item.id), state.settings ?? []));
             const where = `${id}.${path.join('.')}`;
-            let current = parseProjectConfig(session.configSource).options[id];
-            for (const key of path)
-                current =
-                    current && typeof current === 'object'
-                        ? current[key]
-                        : undefined;
-            if (current !== undefined)
+            const section = targetSection(plugin);
+            // A path through a list must name an item that is there (INVALID_SET with the names).
+            applySetOptions(session.configSource, section, [{ path: [...path], value: '' }]);
+            // R4CA-5: an empty value (`token:`, `token: ''`, `secrets: []`) holds no secret: it is
+            // filled, never kept (SECRET_KEPT) or rotated. R5 Codex T4 review: nor does the sample's
+            // placeholder (`<set the postgres URL here …>`, what `config init` lists as placeholders).
+            const found = optionAtPath(session.configSource, section, path);
+            const current = found === null ||
+                found === '' ||
+                isPlaceholder(found) ||
+                (Array.isArray(found) && (found.length === 0 || found.every(isPlaceholder)))
+                ? undefined
+                : found;
+            if (current !== undefined && !rotate)
                 return {
-                    ...(await this.#finish(session, { changed: [], preserved: [], warnings: [{ code: 'SECRET_KEPT', path: where }] }, dryRun)),
+                    ...(await this.#finish(session, {
+                        changed: [],
+                        preserved: [],
+                        warnings: [
+                            ...envWarnings(session.root),
+                            {
+                                code: 'SECRET_KEPT',
+                                path: where,
+                                hint: `npx dokebi config secret ${where} --rotate replaces it (a list keeps the previous ones after the new one)`,
+                            },
+                        ],
+                    }, dryRun)),
+                    file: session.configFile,
                     secret: { path: where, list: Array.isArray(current), generated: false },
                 };
-            const secret = randomBytes(32).toString('base64url');
+            // A random string is never a working address: a URL (a placeholder or a rotated one) is
+            // the user's, piped in (R5 Codex T4 review: filling the placeholder opened this path).
+            if (value === undefined && URL_KEY.test(path.at(-1) ?? ''))
+                throw new CliError('INVALID_SET', `${where} is an address, not a generated secret`, {
+                    details: {
+                        path: where,
+                        fix: `npx dokebi config secret ${where} --stdin < <file with the URL>`,
+                    },
+                    phase: 'arguments',
+                });
             const validator = new PluginOptionsValidator({ allErrors: true });
-            let chosen;
-            let list = false;
-            for (const value of [secret, [secret]]) {
-                const source = applySetOptions(session.configSource, id, [{ path: [...path], value }]);
-                const checked = await validator.check(session.root, plugin, optionsOf(parseProjectConfig(source).options, id));
-                if (checked.errors.every((error) => error.keyword === 'required')) {
-                    chosen = source;
-                    list = Array.isArray(value);
-                    break;
+            const rotated = current !== undefined && Array.isArray(current)
+                ? await this.#rotatedList(session.root, validator, plugin, session.configSource, path, current, ...(value === undefined ? [] : [value]))
+                : undefined;
+            const { source: chosen, list } = rotated ??
+                (await this.#withGeneratedSecret(session.root, validator, plugin, session.configSource, path, ...(value === undefined ? [] : [value])));
+            // R4CA-6: a list no kept-secrets list fits (the schema then took one new string or a
+            // one-item list) lost every previous secret: said like any other drop.
+            const dropped = rotated?.dropped ?? (Array.isArray(current) ? current.length : 0);
+            const warnings = [
+                ...envWarnings(session.root),
+                ...(dropped ? [{ code: 'SECRETS_DROPPED', path: where, count: dropped }] : []),
+            ];
+            const paths = filePaths([[session.configFile, session.configSource, chosen]]);
+            this.#checkPaths(paths, [requestedPath(session.configSource, id, path)], dryRun, warnings);
+            await tx.write(session.configFile, chosen);
+            const outcome = {
+                path: where,
+                list,
+                generated: value === undefined,
+                ...(value === undefined ? {} : { stdin: true }),
+                ...(current !== undefined ? { rotated: true, kept: rotated?.kept ?? 0, dropped } : {}),
+            };
+            debug(current === undefined ? 'Wrote a secret option' : 'Rotated a secret option', {
+                path: where,
+                list,
+                source: value === undefined ? 'generated' : 'stdin',
+                ...(current !== undefined ? { kept: outcome.kept, dropped: outcome.dropped } : {}),
+            });
+            return {
+                ...(await this.#finish(session, {
+                    changed: tx.paths,
+                    preserved: [],
+                    paths,
+                    ...(warnings.length ? { warnings } : {}),
+                    ...(current !== undefined
+                        ? {
+                            nextSteps: [
+                                {
+                                    command: 'npx dokebi verify --json',
+                                    why: `restart the app (dev restarts by itself on a dokebi.yaml change; a started app needs npx dokebi stop and start): it uses the new secret from then on. ${list
+                                        ? `What the previous secret${outcome.kept === 1 ? '' : 's'} signed keeps verifying while ${outcome.kept === 1 ? 'it stays' : 'they stay'} in the list`
+                                        : 'What the old value signed or opened no longer works'}; the plugin AI.md says what a rotation changes. An environment override of this option, where the plugin has one, still wins`,
+                                },
+                            ],
+                        }
+                        : {}),
+                }, dryRun)),
+                file: session.configFile,
+                secret: outcome,
+            };
+        }
+        catch (error) {
+            // R4CA-12: after a termination signal, whatever failed before the commit (a plugin check
+            // or a settings declaration the terminal's Ctrl+C reached too) is INTERRUPTED.
+            throw tx.failure(error);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /**
+     * `dokebi config init` (D-0163, R3 Claude T4 review): a fresh copy of a project (a clone, a CI
+     * checkout) has no dokebi.yaml, which stays out of version control, and no command made one:
+     * `dev-infra up` failed with INTERNAL_ERROR. Writes it from dokebi.example.yaml with a generated
+     * secret for every required secret option the sample leaves out (the sample holds none), and
+     * names the placeholders (`<set … here>`) still to fill. Never replaces an existing file.
+     */
+    async configInit(root, dryRun = false) {
+        root = await realpath(root);
+        await projectStateText(root);
+        const target = await configTarget(root);
+        if (!target.inside)
+            throw configOutsideProject(target);
+        if (await exists(target.path))
+            throw new CliError('CONFIG_EXISTS', `${target.file} already exists; config init writes a new one only`, {
+                phase: 'arguments',
+                details: {
+                    file: target.file,
+                    fix: 'nothing to do: npx dokebi config diff compares it with dokebi.example.yaml, npx dokebi config secret <id>.<path> fills a missing secret',
+                },
+            });
+        let sample;
+        try {
+            sample = await readFile(await securePath(root, EXAMPLE), 'utf8');
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw new CliError('READ_FAILED', `Cannot read ${EXAMPLE}`, { cause: error });
+            throw new CliError('EXAMPLE_MISSING', `No ${EXAMPLE} to start ${target.file} from`, {
+                phase: 'arguments',
+                details: {
+                    file: EXAMPLE,
+                    fix: `restore ${EXAMPLE} from version control (the CLI writes it and it belongs there)`,
+                },
+            });
+        }
+        const session = await this.#begin(root, sample);
+        const { tx, state } = session;
+        try {
+            const validator = new PluginOptionsValidator({ allErrors: true });
+            let source = session.configSource;
+            const generatedSecrets = [];
+            const generate = async (item, path) => {
+                const section = targetSection(item);
+                // As config secret (R4CA-5): an empty value (`token:`, `''`, `[]`) holds no secret.
+                const found = optionAtPath(source, section, path);
+                if (found !== undefined &&
+                    found !== null &&
+                    found !== '' &&
+                    !(Array.isArray(found) && !found.length))
+                    return;
+                source = (await this.#withGeneratedSecret(session.root, validator, item, source, path))
+                    .source;
+                const option = `${section}.${path.join('.')}`;
+                generatedSecrets.push({
+                    plugin: 'settingsSection' in item ? item.settingsSection : item.id,
+                    option,
+                    file: session.configFile,
+                });
+                debug('config init generated a secret option', { option });
+            };
+            // A plugin's secrets are the ones `add` generates: its install plan's configSecrets (a
+            // secret the user supplies, such as an SMTP password, is never made up).
+            const projectPackages = Object.keys(await this.#installedDependencies(session.root));
+            for (const plugin of state.plugins) {
+                const plan = await planLifecycle({
+                    base: session.root,
+                    plugin,
+                    options: parseProjectConfig(source).options,
+                    plugins: state.plugins,
+                    projectPackages,
+                }, 'planInstall');
+                for (const path of plan.configSecrets)
+                    await generate(plugin, path);
+            }
+            // An application settings section (D-0155) has no install plan: its required options that
+            // are secrets by schema mark or name (as `config show` hides them).
+            for (const settingsSection of state.settings ?? []) {
+                const item = { settingsSection };
+                const checked = await checkTarget(validator, session.root, item, optionsOf(parseProjectConfig(source).options, settingsSection));
+                for (const issue of checked.errors)
+                    if (issue.keyword === 'required' && issue.missingProperty) {
+                        const path = [...issuePathOf(issue.instancePath), issue.missingProperty];
+                        if (secretInSchema(checked.schema, path))
+                            await generate(item, path);
+                    }
+            }
+            const placeholders = placeholderPaths(parseProjectConfig(source).options);
+            debug('config init writes the settings file from the sample', {
+                file: session.configFile,
+                secrets: generatedSecrets.length,
+                placeholders: placeholders.length,
+            });
+            await tx.write(session.configFile, source);
+            const databaseUrl = placeholders.some((path) => /^dokebi-db\..*\.url$/.test(path));
+            const nextSteps = [
+                ...(databaseUrl
+                    ? [
+                        {
+                            command: 'npx dokebi dev-infra --json',
+                            why: 'writes the development database URL into the placeholder (and compose.yaml when the project has none); then npx dokebi dev-infra up starts the database',
+                        },
+                    ]
+                    : []),
+                ...(placeholders.some((path) => !(databaseUrl && /^dokebi-db\..*\.url$/.test(path)))
+                    ? [
+                        {
+                            command: 'npx dokebi config show --json',
+                            why: `fill the other placeholders with your file editor or ask the user for them: ${placeholders.filter((path) => !/^dokebi-db\..*\.url$/.test(path) || !databaseUrl).join(', ')}`,
+                        },
+                    ]
+                    : []),
+                {
+                    command: 'npx dokebi doctor --json',
+                    why: "checks the new file against every plugin; the project's README says how its database is migrated and seeded",
+                },
+            ];
+            return {
+                ...(await this.#finish(session, {
+                    changed: tx.paths,
+                    preserved: [],
+                    ...(generatedSecrets.length ? { generatedSecrets } : {}),
+                    nextSteps,
+                }, dryRun)),
+                file: session.configFile,
+                generatedSecrets,
+                placeholders,
+            };
+        }
+        catch (error) {
+            throw tx.failure(error);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /**
+     * dokebi.yaml source with a new generated secret first in the list at `<id>.<path>` and the
+     * previous ones after it (at most ROTATE_KEEP; fewer when the schema allows fewer items).
+     * Undefined when no such list passes the schema (the caller then writes a single new secret).
+     */
+    async #rotatedList(root, validator, plugin, source, path, current, secret = randomBytes(32).toString('base64url')) {
+        const id = targetSection(plugin);
+        const key = (error) => `${error.keyword} ${error.instancePath}`;
+        const options = (text) => optionsOf(parseProjectConfig(text).options, id);
+        const before = new Set((await checkTarget(validator, root, plugin, options(source))).errors.map(key));
+        for (let keep = Math.min(current.length, ROTATE_KEEP); keep >= 0; keep--) {
+            const candidate = applySetOptions(source, id, [
+                { path: [...path], value: [secret, ...current.slice(0, keep)] },
+            ]);
+            const checked = await checkTarget(validator, root, plugin, options(candidate));
+            if (checked.errors.every((error) => error.keyword === 'required' || before.has(key(error))))
+                return { source: candidate, list: true, kept: keep, dropped: current.length - keep };
+            debug('Rotated secret list refused by the schema; keeping fewer', {
+                path: `${id}.${path.join('.')}`,
+                keep,
+                errors: checked.errors.map(key),
+            });
+        }
+        return undefined;
+    }
+    /**
+     * User code a recipe writes (D-0076 §6, `recipe blog --admin login`), in one transaction under
+     * the project lock. A new file is written; a file with the same content is left alone; a file
+     * marked `replaceTemplate` is replaced only while it still is the untouched template its plugin
+     * installed (the hash `state.files` recorded); anything else is RECIPE_FILE_CONFLICT. `edits`
+     * change existing files (they return the text unchanged when already applied). `config` sets
+     * values of a dokebi.yaml section no plugin owns; a `secret` value is generated (never returned
+     * or logged) and an existing one is kept. Nothing is written when nothing changes.
+     */
+    async writeRecipeFiles(root, request) {
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            const written = [];
+            const kept = [];
+            for (const file of request.files) {
+                await tx.capture(file.path);
+                const target = await securePath(session.root, file.path);
+                const current = await fingerprint(target);
+                if (current === hash(file.content)) {
+                    kept.push(file.path);
+                    continue;
+                }
+                if (current !== null && !(file.replaceTemplate && current === state.files[file.path]?.hash))
+                    throw new CliError('RECIPE_FILE_CONFLICT', `${file.path} exists and is not what the recipe writes`, {
+                        details: {
+                            path: file.path,
+                            fix: `${file.path} was edited or made elsewhere: the recipe never overwrites it. Move it away and run the same recipe command again, or write the change yourself`,
+                        },
+                        phase: 'plan',
+                    });
+                const directory = dirname(file.path);
+                if (directory !== '.')
+                    await tx.ensureDirectory(directory);
+                await tx.write(file.path, file.content);
+                written.push(file.path);
+            }
+            for (const change of request.edits ?? []) {
+                const before = await tx.read(change.path);
+                const after = change.edit(before);
+                if (after === before)
+                    kept.push(change.path);
+                else {
+                    await tx.write(change.path, after);
+                    written.push(change.path);
+                }
+            }
+            let configSource = session.configSource;
+            const generatedSecrets = [];
+            if (request.config) {
+                const { section, values } = request.config;
+                if (state.plugins.some((plugin) => plugin.id === section))
+                    throw new CliError('INVALID_SET', `${section} is a plugin's options, not a recipe section`);
+                for (const { key, value } of values) {
+                    if (optionAt(configSource, section, [key]) !== undefined)
+                        continue;
+                    // A value of undefined is a secret: generated here, never returned or logged.
+                    configSource = applySetOptions(configSource, section, [
+                        { path: [key], value: value ?? generatePassword() },
+                    ]);
+                    if (value === undefined)
+                        generatedSecrets.push({
+                            plugin: section,
+                            option: `${section}.${key}`,
+                            file: session.configFile,
+                        });
+                }
+                if (configSource !== session.configSource) {
+                    await tx.write(session.configFile, configSource);
+                    written.push(session.configFile);
                 }
             }
-            if (chosen === undefined)
-                throw new CliError('INVALID_PLUGIN_OPTIONS', `${where} does not take a secret string`, {
-                    details: { plugin: id, path: where },
-                });
-            await tx.write(CONFIG_FILE, chosen);
-            debug('Generated a secret option', { path: where, list });
+            debug('Recipe files written', { written, kept, secrets: generatedSecrets.length });
             return {
-                ...(await this.#finish(session, { changed: tx.paths, preserved: [] }, dryRun)),
-                secret: { path: where, list, generated: true },
+                ...(await this.#finish(session, { changed: tx.paths, preserved: [] })),
+                ...(generatedSecrets.length ? { generatedSecrets } : {}),
+                written,
+                kept,
             };
         }
         finally {
@@ -1174,11 +3078,32 @@ export class Project {
             throw new CliError('CORE_UPGRADE_REQUIRED', 'Dokebi YAML projects require @dokebi/core 0.2.0 or newer');
         return pkg.version;
     }
-    /** Takes the project lock and reads the common state every mutation needs. */
-    async #begin(root) {
+    /**
+     * Takes the project lock and reads the common state every mutation needs. `fresh`: the text a
+     * missing settings file starts from (config init, D-0163); every other command needs the file.
+     */
+    async #begin(root, fresh) {
         root = await realpath(root);
         // Do not create control files in arbitrary non-Dokebi projects.
-        await readFile(await securePath(root, '.dokebi/state.json'));
+        await projectStateText(root);
+        // M50: every changing command works on the settings file the app reads — DOKEBI_CONFIG when
+        // set (from the project folder), else dokebi.yaml. Never a file outside the project
+        // (UNSAFE_PATH, as a linked dokebi.yaml), never dokebi.yaml in place of a missing named file.
+        const settings = await configTarget(root);
+        if (!settings.inside)
+            throw configOutsideProject(settings);
+        if (settings.fromEnvironment && !(await exists(settings.path)))
+            throw new CliError('READ_FAILED', `Cannot read ${settings.file}, the settings file DOKEBI_CONFIG names`, {
+                phase: 'arguments',
+                details: {
+                    file: settings.file,
+                    fix: 'point DOKEBI_CONFIG at the settings file the app reads, or unset it to use dokebi.yaml',
+                },
+            });
+        const missing = !settings.fromEnvironment && !(await exists(settings.path));
+        if (missing && fresh === undefined)
+            throw notAProject(root, CONFIG_FILE);
+        const configFile = settings.file;
         const workspaceRoot = await workspaceRootOf(root);
         const tx = await Transaction.begin(root);
         try {
@@ -1189,40 +3114,210 @@ export class Project {
                     ? 'CONFIG_CONFLICT'
                     : 'MIGRATION_REQUIRED', 'Run dokebi migrate after resolving conflicting configuration files');
             }
-            const configSource = await tx.read(CONFIG_FILE);
+            let configSource;
+            if (missing && fresh !== undefined) {
+                await tx.capture(configFile);
+                configSource = fresh;
+            }
+            else
+                configSource = await tx.read(configFile);
             parseProjectConfig(configSource);
+            // D-0154: what the CLI writes into dokebi.yaml and the example marks reloadable options:
+            // with the schemas of the installed plugins and those staged in this session.
+            const schemas = new Map();
+            tx.transformText = async (path, text) => {
+                if (path !== CONFIG_FILE && path !== configFile && path !== EXAMPLE)
+                    return text;
+                const known = await reloadSchemas(root, state.plugins, state.settings ?? []);
+                for (const [section, schema] of schemas)
+                    known.set(section, schema);
+                return markReloadable(text, known);
+            };
             const required = await readRequiredPlugins(root);
             const pkg = parseObject(await tx.read('package.json'), 'package.json');
             validateProjectPackage(pkg);
             if (hash(await tx.read(GENERATED)) !== state.generatedHash)
-                throw new CliError('MODIFIED_REGISTRATION', GENERATED);
+                throw modifiedRegistration();
             if (!workspaceRoot)
-                return { root, tx, state, configSource, required, pkg };
+                return { root, tx, schemas, state, configSource, configFile, required, pkg };
             const workspace = {
                 root: workspaceRoot,
                 packages: await workspacePackages(workspaceRoot),
                 lock: await readOptional(join(workspaceRoot, 'package-lock.json')),
             };
-            return { root, tx, state, configSource, required, pkg, workspace };
+            return { root, tx, schemas, state, configSource, configFile, required, pkg, workspace };
         }
         catch (error) {
             await tx.close();
             throw error;
         }
     }
-    async #stage(session, pkg, dependencies, spec) {
+    async #stage(session, pkg, dependencies, spec, companions = []) {
+        try {
+            return await this.#stageProject(session, pkg, dependencies, spec, companions);
+        }
+        catch (error) {
+            // Ctrl+C during the staging install: npm got the signal and failed; nothing was applied.
+            if (session.tx.interrupted)
+                throw interruptedError(session.tx.interrupted, error);
+            const mismatch = await this.#registryMismatch(session, error);
+            throw mismatch === error ? await this.#peerConflict(session, spec, error) : mismatch;
+        }
+    }
+    /**
+     * npm's ERESOLVE for a named version (`add <package>@<version>`, `upgrade --to <version>`)
+     * whose peers do not accept what the project has installed (a session that needs a newer
+     * @dokebi/web): the error keeps npm's words and gets `details.conflicts` and a `fix` that
+     * upgrades the installed package first. Anything else is returned as it was.
+     */
+    async #peerConflict(session, spec, error) {
+        if (!(error instanceof CliError) || error.code !== 'NPM_FAILED' || !spec)
+            return error;
+        const details = (error.details ?? {});
+        const match = /^((?:@[^/@]+\/)?[^@]+)@(.+)$/.exec(spec);
+        if (details.npmCode !== 'ERESOLVE' || !match?.[1] || !match[2] || !validVersion(match[2]))
+            return error;
+        const [, name, version] = match;
+        const found = await fetchPackument(name, session.root);
+        const manifest = found.status === 'found' ? found.versions[version] : undefined;
+        if (!manifest)
+            return error;
+        const constraints = this.#constraints(session, await this.coreVersion(session.root), name);
+        const conflicts = versionConflicts(version, manifest, constraints);
+        debug('Peer ranges of the named version checked after ERESOLVE', { spec, conflicts });
+        if (!conflicts.length)
+            return error;
+        return new CliError('NPM_FAILED', `${error.message}: ${describeConflicts(name, version, conflicts)}`, {
+            cause: error,
+            details: {
+                ...Object.fromEntries(Object.entries(details).filter(([key]) => key !== 'hint')),
+                conflicts,
+                fix: conflictFix(conflicts, constraints, 'repeat this command'),
+            },
+            ...(error.phase ? { phase: error.phase } : {}),
+        });
+    }
+    /**
+     * D-0138: npm failed in staging. When packages this project has installed (exact registry
+     * versions) are missing from the registry npm uses now, that is the cause, whatever npm says
+     * (ERESOLVE "Found: @dokebi/core@undefined" in AI-M27): REGISTRY_MISMATCH names them, the
+     * registry and where the lock says they came from, so nobody retries with --legacy-peer-deps
+     * (which installed @dokebi/module 0.4.0 from the public registry next to the run's 0.4.2 core).
+     * Any other failure is returned as it was.
+     */
+    async #registryMismatch(session, error) {
+        if (!(error instanceof CliError) || error.code !== 'NPM_FAILED')
+            return error;
+        const details = (error.details ?? {});
+        if (details.network === true || details.timedOut === true)
+            return error;
+        let lock = {};
+        const lockText = session.workspace
+            ? session.workspace.lock
+            : (await exists(await securePath(session.tx.root, 'package-lock.json')))
+                ? await session.tx.read('package-lock.json')
+                : undefined;
+        if (typeof lockText === 'string') {
+            try {
+                lock = object(JSON.parse(lockText).packages ?? {}, 'lock packages');
+            }
+            catch (cause) {
+                debug('package-lock.json not readable; installed origins unknown', {
+                    error: describeError(cause),
+                });
+            }
+        }
+        const installed = DEPENDENCY_SECTIONS.flatMap((section) => Object.entries(object(session.pkg[section] ?? {}, section)).flatMap(([name, spec]) => {
+            if (!name.startsWith('@dokebi/') || session.workspace?.packages.has(name))
+                return [];
+            if (typeof spec !== 'string' || validVersion(spec) !== spec)
+                return [];
+            const entry = lock[`node_modules/${name}`];
+            const resolved = typeof entry?.resolved === 'string' ? entry.resolved : undefined;
+            return [{ package: name, version: spec, ...(resolved ? { resolved } : {}) }];
+        }));
+        const missing = await missingOnRegistry(installed, session.root);
+        debug('Installed packages checked against the registry after an npm failure', {
+            checked: installed.length,
+            missing,
+        });
+        if (!missing.length)
+            return error;
+        // The core first (every add picks its version for it), then at most two more by name.
+        const named = [...missing].sort((a, b) => a.package === '@dokebi/core' ? -1 : b.package === '@dokebi/core' ? 1 : 0);
+        const list = `${named
+            .slice(0, 3)
+            .map((item) => `${item.package} ${item.version}`)
+            .join(', ')}${named.length > 3 ? ` and ${named.length - 3} more (details.missing)` : ''}`;
+        const registries = [...new Set(missing.map((item) => item.registry))].join(', ');
+        const origins = [
+            ...new Set(named.flatMap((item) => (item.installedFrom ? [item.installedFrom] : []))),
+        ];
+        return new CliError('REGISTRY_MISMATCH', `npm now installs from ${registries}, which does not have ${list} that this project has installed${origins.length ? ` (package-lock.json: ${origins[0]})` : ''}`, {
+            cause: error,
+            details: {
+                // npm's words stay; its generic ERESOLVE hint gives way to the fix below.
+                ...Object.fromEntries(Object.entries(details).filter(([key]) => key !== 'hint')),
+                stage: 'staging',
+                missing,
+                fix: `run dokebi with the npm configuration that installed this project: npm config get @dokebi:registry in the project folder must name the registry in package-lock.json's resolved URLs (the project .npmrc, npm_config_userconfig or npm_config_@dokebi:registry), then run the same command again. Do not retry with --legacy-peer-deps or --force: npm would install packages from ${registries} next to a core that registry does not have.`,
+            },
+            phase: 'install',
+        });
+    }
+    async #stageProject(session, pkg, dependencies, spec, companions = []) {
         const { tx, workspace } = session;
         const staging = join(tx.directory, 'npm');
         await mkdir(staging);
         // npm in staging reads the project's .npmrc too (the registry resolution did, D-0065).
         await stageNpmConfig(workspace?.root ?? session.root, staging);
         if (!workspace) {
+            // Tarballs the project names by a relative path (`file:vendor/x.tgz`): the same path in
+            // staging, so npm resolves them there and the files it writes back keep them relative.
+            const copy = async (path) => {
+                // Checked before anything is created: no folder is made for a path that is refused.
+                const source = await securePath(tx.root, path);
+                // One the folder lacks (an ignored vendor/): npm in staging names it with NPM_FAILED, as
+                // it does an absolute path (R6-cli-2: a bare ENOENT of the copy was INTERNAL_ERROR).
+                if (!(await exists(source))) {
+                    debug('A project tarball is missing; the staging install reports it', { path });
+                    return;
+                }
+                // A folder (or another non-file) at the tarball's path: npm cannot install it either, and
+                // the copy failed with a bare EISDIR or ENOTSUP, an INTERNAL_ERROR (R7-cli-2). securePath
+                // has refused a symbolic link already.
+                if (!(await lstat(source)).isFile()) {
+                    debug('A project tarball path is not a file; refused', { path });
+                    throw new CliError('UNSUPPORTED_PROJECT', `A file: tarball is not a file: ${path}`, {
+                        details: {
+                            path,
+                            fix: `put the package's .tgz at ${path}, or change its dependency in package.json`,
+                        },
+                    });
+                }
+                await mkdir(dirname(join(staging, path)), { recursive: true });
+                await copyFile(source, join(staging, path));
+            };
+            for (const section of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+                const listed = (section === 'dependencies' ? dependencies : pkg[section]) ?? {};
+                for (const value of Object.values(listed)) {
+                    const path = typeof value === 'string' ? projectTarball(value) : undefined;
+                    if (path === undefined)
+                        continue;
+                    await copy(path);
+                }
+            }
+            // A tarball named on the command line inside the project, made relative by projectSpec.
+            const named = spec === undefined ? undefined : projectTarball(spec);
+            if (named !== undefined)
+                await copy(named);
             await writeFile(join(staging, 'package.json'), json({ ...pkg, dependencies }));
             const lock = await securePath(tx.root, 'package-lock.json');
             if (await exists(lock))
                 await writeFile(join(staging, 'package-lock.json'), await tx.read('package-lock.json'));
             await tx.capture('node_modules');
-            await this.npm.install(staging, spec);
+            // Required plugins the package brings, pinned in the same run (companionVersions).
+            await this.npm.install(staging, companions.length ? [spec ?? '', ...companions].filter(Boolean) : spec);
             return staging;
         }
         // A standalone copy of the member. Workspace packages (maybe unpublished) come in as packed
@@ -1242,7 +3337,7 @@ export class Project {
             ...Object.fromEntries(packs),
         };
         await writeFile(join(staging, 'package.json'), json(staged));
-        await this.#stageInstall(session, staging, spec);
+        await this.#stageInstall(session, staging, companions.length ? [spec ?? '', ...companions].filter(Boolean) : spec);
         return staging;
     }
     /**
@@ -1251,23 +3346,31 @@ export class Project {
      * differs from the direct dependency) and installed from there (D-0035 §3).
      */
     async #stageInstall(session, staging, spec) {
+        const specs = spec === undefined ? [] : typeof spec === 'string' ? [spec] : [...spec];
         const workspace = session.workspace;
-        const local = workspace && spec !== undefined && this.#workspacePackage(workspace, spec);
-        if (!local)
-            return this.npm.install(staging, spec);
-        const packs = await this.#packWorkspace(session, [local.name]);
+        const locals = workspace
+            ? specs.flatMap((item) => {
+                const found = this.#workspacePackage(workspace, item);
+                return found ? [{ spec: item, name: found.name }] : [];
+            })
+            : [];
+        // One npm run for every spec (D-0116: a dependency level of add or upgrade at once).
+        const remote = specs.filter((item) => !locals.some((local) => local.spec === item));
+        if (!locals.length)
+            return this.npm.install(staging, remote.length ? remote : undefined);
+        const packs = await this.#packWorkspace(session, locals.map((local) => local.name));
         const path = join(staging, 'package.json');
         const staged = parseObject(await readFile(path, 'utf8'), 'staged');
         staged.dependencies = {
             ...object(staged.dependencies ?? {}, 'dependencies'),
-            [local.name]: packs.get(local.name),
+            ...Object.fromEntries(locals.map((local) => [local.name, packs.get(local.name)])),
         };
         staged.overrides = {
             ...object(staged.overrides ?? {}, 'overrides'),
             ...Object.fromEntries(packs),
         };
         await writeFile(path, json(staged));
-        await this.npm.install(staging);
+        await this.npm.install(staging, remote.length ? remote : undefined);
     }
     /**
      * `file:` archives of the named workspace packages and every workspace package they depend on
@@ -1314,6 +3417,28 @@ export class Project {
             throw new CliError('WORKSPACE_VERSION_MISMATCH', `${match[1]} is ${found.version} in the workspace`, { details: { package: match[1], workspace: found.version, requested: range } });
         return { name: match[1], spec: `file:${found.directory}` };
     }
+    /**
+     * Whether the staged install holds other content of `name` than the project's: the
+     * package-lock integrity of `node_modules/<name>` differs (both must be known; a workspace
+     * member's lock lives at the workspace root and is not compared).
+     */
+    async #contentChanged(session, staging, name) {
+        if (session.workspace)
+            return false;
+        const integrity = (text) => {
+            if (text === undefined || text === null)
+                return undefined;
+            const packages = (parseObject(text, 'package-lock.json').packages ?? {});
+            const value = packages[`node_modules/${name}`]?.integrity;
+            return typeof value === 'string' ? value : undefined;
+        };
+        const lock = await securePath(session.tx.root, 'package-lock.json');
+        const before = integrity((await exists(lock)) ? await session.tx.read('package-lock.json') : undefined);
+        const after = integrity(await readOptional(join(staging, 'package-lock.json')));
+        const changed = before !== undefined && after !== undefined && before !== after;
+        debug('Same-version upgrade compares the package content', { name, changed });
+        return changed;
+    }
     async #installedDependencies(staging) {
         return dependencyMap(parseObject(await readFile(join(staging, 'package.json'), 'utf8'), 'installed package'));
     }
@@ -1325,7 +3450,38 @@ export class Project {
         for (const plugin of plugins) {
             const actual = await this.#readPackageManifest(staging, plugin.packageName);
             if (json(actual) !== json(plugin))
-                throw new CliError('MANIFEST_CHANGED', plugin.id);
+                throw stagedManifestChanged(plugin, actual);
+        }
+    }
+    /**
+     * The other registered plugins of an upgrade come out of staging as recorded, or as the project
+     * has them installed already. The second case is a package.json that moved several plugins at
+     * once (`npm install`/`npm update`, doctor MANIFEST_CHANGED for each): such a plugin stays
+     * recorded as it was and is reported with its own `dokebi upgrade`, so the plugins can be
+     * upgraded one after another. A plugin that npm changes in staging is still MANIFEST_CHANGED.
+     */
+    async #verifyUpgradeOthers(session, staging, others, warnings) {
+        for (const plugin of others) {
+            const actual = await this.#readPackageManifest(staging, plugin.packageName);
+            if (json(actual) === json(plugin))
+                continue;
+            const file = await packageFile(session.root, plugin.packageName, 'package.json');
+            const installed = (await exists(file))
+                ? readManifest(parseObject(await readFile(file, 'utf8'), plugin.packageName))
+                : undefined;
+            if (!installed || json(installed) !== json(actual))
+                throw stagedManifestChanged(plugin, actual);
+            debug('Upgrade leaves a plugin whose installed package already changed', {
+                plugin: plugin.id,
+                recorded: plugin.version,
+                installed: installed.version,
+            });
+            warnings.push({
+                code: 'MANIFEST_CHANGED',
+                path: `node_modules/${plugin.packageName}/package.json`,
+                plugin: plugin.id,
+                hint: `dokebi upgrade ${plugin.id}`,
+            });
         }
     }
     async #order(staging, plugins, required) {
@@ -1358,10 +3514,19 @@ export class Project {
             const result = checks.get(plugin.id) ?? { requires: [], diagnostics: [] };
             const requires = plugin.id === target.id ? union(target.requires, result.requires) : result.requires;
             const missing = requires.filter((id) => !installed.has(id));
-            if (missing.length)
-                throw new CliError('MISSING_REQUIRED_PLUGIN', plugin.id, {
-                    details: { plugin: plugin.id, requires: missing },
+            if (missing.length) {
+                const catalog = await loadCatalog();
+                const packages = missing.map((id) => findPackage(catalog, id)?.package ?? id);
+                throw new CliError('MISSING_REQUIRED_PLUGIN', `${plugin.id} ${plugin.version} requires ${missing.join(', ')} with the current settings, and ${missing.length === 1 ? 'it is' : 'they are'} not installed`, {
+                    details: {
+                        plugin: plugin.id,
+                        version: plugin.version,
+                        requires: missing,
+                        fix: `${packages.map((name) => `npx dokebi add ${name}`).join(', then ')}, or change the options of ${plugin.id} that need ${missing.length === 1 ? 'it' : 'them'}`,
+                    },
+                    phase: 'plan',
                 });
+            }
             installations[plugin.id] = {
                 ...(installations[plugin.id] ?? defaultInstallation(plugin)),
                 requires,
@@ -1387,14 +3552,22 @@ export class Project {
                 });
                 continue;
             }
-            throw new CliError('PLUGIN_CHECK_FAILED', plugin.id, {
-                details: { plugin: plugin.id, diagnostics: errors.slice(0, 20) },
+            const first = errors[0];
+            throw new CliError('PLUGIN_CHECK_FAILED', `The check of ${plugin.id} ${plugin.version} failed: ${first.code}${first.optionPath?.length ? ` at options.${optionsKey(plugin)}.${first.optionPath.join('.')}` : ''}${errors.length > 1 ? ` (and ${errors.length - 1} more)` : ''}`, {
+                details: {
+                    plugin: plugin.id,
+                    diagnostics: errors.slice(0, 20),
+                    fix: typeof first.hint === 'string'
+                        ? first.hint
+                        : `correct what details.diagnostics names (npx dokebi plugins doc ${plugin.id} --json), then repeat this command`,
+                },
+                phase: 'plan',
             });
         }
     }
     async #validateOptions(validator, staging, ordered, config, configRequired) {
         for (const plugin of ordered) {
-            const checked = await validator.check(staging, plugin, optionsOf(config.options, plugin.id));
+            const checked = await validator.check(staging, plugin, optionsOf(config.options, optionsKey(plugin)));
             if (!checked.errors.length)
                 continue;
             // Only missing required values (this plugin or one installed earlier) do not block the
@@ -1406,15 +3579,8 @@ export class Project {
                     errorCount: checked.errors.length,
                 });
             }
-            else {
-                throw new CliError('INVALID_PLUGIN_OPTIONS', plugin.id, {
-                    details: {
-                        plugin: plugin.id,
-                        errors: checked.errors.slice(0, 20),
-                        errorCount: checked.errors.length,
-                    },
-                });
-            }
+            else
+                throw invalidPluginOptions(plugin.id, checked.errors, 'plan', optionsKey(plugin), 'schema', checked.schema);
         }
     }
     #planFiles(plan) {
@@ -1434,12 +3600,12 @@ export class Project {
             if (owned) {
                 // A shared file needs the same content and the same owner class from every plugin.
                 if (current !== digest || owned.hash !== digest || owned.owner !== owner)
-                    throw new CliError('FILE_CONFLICT', file.target);
+                    throw fileConflict(file.target, `is shared with ${owned.owners.join(', ')}, and ${plugin.id} ${plugin.version} brings other content or another owner for it`, `the packages disagree about this file: install versions that agree, or report it to the authors of ${plugin.packageName}`, { plugin: plugin.id, owners: owned.owners });
                 owned.owners.push(plugin.id);
             }
             else {
                 if (current !== null)
-                    throw new CliError('FILE_CONFLICT', file.target);
+                    throw fileConflict(file.target, `already exists and ${plugin.id} ${plugin.version} would write it`, `move ${file.target} away (it is not the CLI's), then repeat this command; put your content back into the new file afterwards`, { plugin: plugin.id });
                 await tx.write(file.target, override.get(file.target) ?? content);
                 state.files[file.target] = { hash: digest, owners: [plugin.id], owner };
             }
@@ -1479,6 +3645,12 @@ export class Project {
                     details.push({ path, reason: 'SHARED', ...(update ? { update } : {}) });
                 continue;
             }
+            if (source === undefined && owned.owner === 'user') {
+                // Retiring a scaffold is not authorization to delete the user's resource.
+                details.push({ path, reason: 'RETIRED_USER_FILE' });
+                delete state.files[path];
+                continue;
+            }
             if (source === undefined) {
                 await tx.replace(path);
                 delete state.files[path];
@@ -1494,11 +3666,8 @@ export class Project {
         await this.#addFiles(tx, staging, state, plugin, [...planned.values()]);
         return details;
     }
-    async #syncExample(tx, root, id, warnings, update) {
-        await this.#syncExamples(tx, root, warnings, [{ id, update }]);
-    }
     /** Applies several plugin updates to dokebi.example.yaml and writes it once. */
-    async #syncExamples(tx, root, warnings, updates) {
+    async #syncExamples(tx, root, warnings, updates, before = (source) => source) {
         if (!(await exists(await securePath(root, EXAMPLE)))) {
             warnings.push({ code: 'EXAMPLE_MISSING', path: EXAMPLE });
             return;
@@ -1506,6 +3675,7 @@ export class Project {
         const source = await tx.read(EXAMPLE);
         let next = source;
         try {
+            next = before(next);
             for (const { id, update } of updates)
                 next = syncExample(next, id, update);
         }
@@ -1596,12 +3766,33 @@ export class Project {
                 await this.npm.installWorkspace(workspace.root);
             }
             catch (cause) {
-                throw new CliError('WORKSPACE_SYNC_FAILED', 'Project files were rolled back; run npm install at the workspace root', {
-                    cause: new AggregateError([failure, cause]),
-                    details: { workspaceRoot: workspace.root },
+                // A rollback that kept user changes (RECOVERY_REQUIRED) stays in the cause and message.
+                const recovery = error instanceof CliError && error.code === 'RECOVERY_REQUIRED' ? error : undefined;
+                throw new CliError('WORKSPACE_SYNC_FAILED', recovery
+                    ? `Project rollback needs recovery (${recovery.message}); then run npm install at the workspace root`
+                    : 'Project files were rolled back; run npm install at the workspace root', {
+                    cause: new AggregateError(recovery ? [recovery, failure, cause] : [failure, cause]),
+                    details: {
+                        workspaceRoot: workspace.root,
+                        ...(recovery ? { recovery: recovery.details } : {}),
+                    },
                 });
             }
-            throw error instanceof CliError && error.code === 'RECOVERY_REQUIRED' ? error : failure;
+            if (error instanceof CliError && error.code === 'RECOVERY_REQUIRED')
+                throw error;
+            // R4CB-9: the project files, the root lock and node_modules are back, which is what
+            // COMMIT_FAILED says (mutation rolled-back); the root install's own error was thrown
+            // before, and an envelope then said mutation unknown although nothing stayed changed.
+            const failed = failure instanceof CliError ? failure : undefined;
+            throw new CliError('COMMIT_FAILED', `Changes were rolled back: ${failed?.message ?? describeError(failure).split('\n')[0]}`, {
+                cause: failure,
+                details: {
+                    failed: failed?.code ?? 'INTERNAL_ERROR',
+                    ...(failed?.details && typeof failed.details === 'object' ? failed.details : {}),
+                    workspaceRoot: workspace.root,
+                },
+                phase: 'commit',
+            });
         }
         return result;
     }
@@ -1613,24 +3804,70 @@ export class Project {
         const session = await this.#begin(root);
         const { tx, state } = session;
         try {
+            if (options.view !== undefined && options.inertia)
+                throw new CliError('USAGE', '--view and --inertia both choose the view: give one', {
+                    details: {
+                        fix: 'an Inertia app: --inertia; EJS pages: --view ejs; no views: --view none',
+                    },
+                    phase: 'arguments',
+                });
+            // D-0098: an app of a project without screens is a JSON API too, unless asked otherwise.
+            const recipeView = options.inertia || options.view ? undefined : await projectView(session.root);
+            const view = options.inertia
+                ? undefined
+                : (options.view ?? (recipeView === NO_VIEW ? 'none' : 'ejs'));
+            if (view === 'none' && (options.template ?? 'default') !== 'default')
+                throw new CliError('USAGE', 'An app without views (--view none) has no templates (--template)', {
+                    details: { fix: 'leave out --template, or choose EJS pages with --view ejs' },
+                    phase: 'arguments',
+                });
+            debug('app add: the view of the app', {
+                app: name,
+                view: view ?? 'inertia',
+                from: options.view === undefined && !options.inertia ? 'recipe' : 'flags',
+            });
             const host = await this.#requireHost(state, 'apps');
-            const added = await this.#addApp(tx, session.root, host, state, session.configSource, name, options);
+            // D-0102: `--domain auto` is this project's development host `<app>.<project>.localhost`.
+            const label = projectHostLabel(session.pkg.name, session.root);
+            const domains = options.domains?.map((domain) => domain === AUTO_DOMAIN ? devHost(name, label) : domain);
+            const added = await this.#addApp(tx, session.root, host, state.plugins, state, session.configSource, name, {
+                ...options,
+                ...(domains ? { domains } : {}),
+                ...(view ? { view } : {}),
+            });
             const warnings = [];
             if (options.inertia && !(await this.#providesInstalled(state, 'view.inertia')))
                 warnings.push({ code: 'INERTIA_PLUGIN_MISSING', path: `src/apps/${name}` });
+            // A sealed domain without the provider fails the start (SEAL_PROVIDER_MISSING).
+            if (options.seal && !(await this.#providesInstalled(state, 'security.seal')))
+                warnings.push({ code: 'SEAL_PLUGIN_MISSING', path: `src/apps/${name}` });
             if (options.ssr && !options.inertia)
                 throw new CliError('USAGE', 'Server rendering (--ssr) needs --inertia');
+            // D-0062 §5: SSR writes the page props into plain HTML, so @dokebi/template-inertia refuses
+            // to start an SSR scope on a seal host. Refuse the pair here instead of at the first start.
+            if (options.ssr && options.seal)
+                throw new CliError('USAGE', 'Server rendering (--ssr) cannot be sealed (--seal): SSR writes the page props into the first HTML as plain text, so the start fails with SEAL_SSR_CONFLICT. Choose one with the user.');
             if (options.inertia)
                 await this.#inertiaBuild(tx, session, host, warnings, options.ssr === true);
             // Domains are not secrets: the shared sample keeps them so `setup` scripts see them too.
             await this.#syncExamples(tx, session.root, warnings, [
                 { id: host.id, update: { changes: added.changes } },
+                ...(added.layout
+                    ? [{ id: added.layout.engine, update: { changes: added.layout.changes } }]
+                    : []),
             ]);
-            await this.writeConfiguration(tx, state, parseAndRender(added.configSource));
+            await this.writeConfiguration(tx, state, parseAndRender(added.configSource), session.configFile);
             const result = {
                 changed: tx.paths,
                 preserved: [],
                 ...(warnings.length ? { warnings } : {}),
+                // What verify's tellUser will say about this app's view (view-choice.ts recordAppView).
+                appView: {
+                    value: appViewValue(options.inertia === true, options.ssr === true, view === 'none'),
+                    from: options.view === undefined && !options.inertia && recipeView === NO_VIEW
+                        ? 'recipe'
+                        : 'flags',
+                },
                 ...(options.inertia
                     ? {
                         nextSteps: [
@@ -1655,7 +3892,7 @@ export class Project {
         try {
             const host = await this.#requireHost(state, 'apps');
             if (!(state.apps ?? []).includes(name))
-                throw new CliError('UNKNOWN_APP', name);
+                throw unknownApp(name, state.apps ?? []);
             const template = options.template ?? 'default';
             if (!APP_NAME.test(template))
                 throw new CliError('INVALID_APP', 'Template names match ' + APP_NAME.source);
@@ -1663,14 +3900,16 @@ export class Project {
                 throw new CliError('INVALID_APP', 'Domains are lower-case host names without a port');
             const current = domainTarget(parseProjectConfig(session.configSource).options, host.id, domain);
             if (current && current !== name)
-                throw new CliError('DOMAIN_IN_USE', domain, { details: { domain, app: current } });
+                throw domainInUse(domain, current);
             const views = `src/apps/${name}/views/${template}`;
             if (template !== 'default' && !(await exists(await securePath(tx.root, views))))
                 await tx.ensureDirectory(views);
-            const changes = domainChanges([domain], template === 'default' ? { app: name } : { app: name, template });
+            const changes = domainChanges([domain], domainTargetOf(name, template, options.seal));
             const warnings = [];
+            if (options.seal && !(await this.#providesInstalled(state, 'security.seal')))
+                warnings.push({ code: 'SEAL_PLUGIN_MISSING', path: `src/apps/${name}` });
             await this.#syncExamples(tx, session.root, warnings, [{ id: host.id, update: { changes } }]);
-            await tx.write(CONFIG_FILE, applyConfigChanges(session.configSource, host.id, changes));
+            await tx.write(session.configFile, applyConfigChanges(session.configSource, host.id, changes));
             const result = {
                 changed: tx.paths,
                 preserved: [],
@@ -1689,11 +3928,17 @@ export class Project {
         try {
             const host = await this.#requireHost(state, 'apps');
             if (!domainTarget(parseProjectConfig(session.configSource).options, host.id, domain))
-                throw new CliError('UNKNOWN_DOMAIN', domain);
+                throw new CliError('UNKNOWN_DOMAIN', `No app is linked to the domain ${domain}`, {
+                    details: {
+                        domain,
+                        fix: 'npx dokebi app list --json lists the linked domains; unlink one of those',
+                    },
+                    phase: 'arguments',
+                });
             const changes = [{ op: 'remove', path: ['domains', domain] }];
             const warnings = [];
             await this.#syncExamples(tx, session.root, warnings, [{ id: host.id, update: { changes } }]);
-            await tx.write(CONFIG_FILE, applyConfigChanges(session.configSource, host.id, changes));
+            await tx.write(session.configFile, applyConfigChanges(session.configSource, host.id, changes));
             const result = {
                 changed: tx.paths,
                 preserved: [],
@@ -1712,10 +3957,17 @@ export class Project {
         try {
             const host = await this.#requireHost(state, 'apps');
             if (!(state.apps ?? []).includes(name))
-                throw new CliError('UNKNOWN_APP', name);
+                throw unknownApp(name, state.apps ?? []);
             const domains = appDomains(parseProjectConfig(session.configSource).options, host.id, name);
             if (domains.length)
-                throw new CliError('APP_IN_USE', name, { details: { app: name, domains } });
+                throw new CliError('APP_IN_USE', `The app ${name} still serves ${domains.map((entry) => entry.domain).join(', ')}; remove its domains first`, {
+                    details: {
+                        app: name,
+                        domains,
+                        fix: `${domains.map((entry) => `npx dokebi app unlink ${entry.domain}`).join(', then ')}, then repeat this command`,
+                    },
+                    phase: 'arguments',
+                });
             state.apps = (state.apps ?? []).filter((app) => app !== name);
             if (!state.apps.length)
                 delete state.apps;
@@ -1736,13 +3988,26 @@ export class Project {
                 if (next !== example)
                     await tx.write(EXAMPLE, next);
             }
-            await this.writeConfiguration(tx, state, removeAppSettings(session.configSource, host.id, name));
+            await this.writeConfiguration(tx, state, removeAppSettings(session.configSource, host.id, name), session.configFile);
+            // The folder is user code and stays; say so (studio request Q: an `ok` alone read as if
+            // everything went).
+            const folder = `src/apps/${name}`;
+            if (await exists(await securePath(session.root, folder)))
+                warnings.push({ code: 'APP_FOLDER_KEPT', path: folder });
             const result = {
                 changed: tx.paths,
-                preserved: [`src/apps/${name}`],
+                preserved: [folder],
                 ...(warnings.length ? { warnings } : {}),
             };
-            return await this.#finish(session, result, dryRun);
+            const finished = await this.#finish(session, result, dryRun);
+            // The view choice recorded for the app (D-0098) goes too, so verify's tellUser never
+            // relays a decision of an app that no longer exists.
+            if (!dryRun) {
+                const { forgetAppChoices } = await import('./recipe-record.js');
+                if (await forgetAppChoices(session.root, name))
+                    return { ...finished, changed: [...finished.changed, '.dokebi/recipe.json'] };
+            }
+            return finished;
         }
         finally {
             await tx.close();
@@ -1750,8 +4015,9 @@ export class Project {
     }
     /** `dokebi app list`: apps with the domains and templates that show them. */
     async appList(root) {
-        const state = readState(parseObject(await readFile(await securePath(root, '.dokebi/state.json'), 'utf8'), 'state'));
-        const config = parseProjectConfig(await readFile(await securePath(root, CONFIG_FILE), 'utf8')).options;
+        const state = readState(parseObject(await projectStateText(root), 'state'));
+        // M50: the settings file the app reads (DOKEBI_CONFIG, else dokebi.yaml).
+        const config = parseProjectConfig((await readProjectSettings(root)).source).options;
         const host = findHost(state.plugins, 'apps');
         return {
             apps: (state.apps ?? []).map((name) => ({
@@ -1773,11 +4039,17 @@ export class Project {
             if (!APP_NAME.test(name))
                 throw new CliError('INVALID_MODULE', 'Module names match ' + APP_NAME.source);
             if ((state.modules ?? []).includes(name))
-                throw new CliError('MODULE_EXISTS', name);
+                throw new CliError('MODULE_EXISTS', `The project already has a module named ${name}`, {
+                    details: {
+                        module: name,
+                        fix: 'choose another name; npx dokebi module list --json lists the modules',
+                    },
+                    phase: 'arguments',
+                });
             const folder = `src/shared/modules/${name}`;
             templateTarget(folder + '/module.ts');
             if (await exists(await securePath(tx.root, folder)))
-                throw new CliError('FILE_CONFLICT', folder);
+                throw fileConflict(folder, `already exists, so module add does not write the module ${name} there`, `choose another name, or move ${folder} away and repeat this command`, { module: name });
             const skeleton = options.views === false ? 'module-api' : 'module';
             const source = await packageFile(session.root, host.packageName, `templates/${skeleton}`);
             if (!(await exists(source)))
@@ -1791,7 +4063,7 @@ export class Project {
                     : content);
             }
             state.modules = [...(state.modules ?? []), name];
-            await this.writeConfiguration(tx, state, session.configSource);
+            await this.writeConfiguration(tx, state, session.configSource, session.configFile);
             const result = {
                 changed: tx.paths,
                 preserved: [],
@@ -1814,11 +4086,18 @@ export class Project {
         const { tx, state } = session;
         try {
             if (!(state.modules ?? []).includes(name))
-                throw new CliError('UNKNOWN_MODULE', name);
+                throw new CliError('UNKNOWN_MODULE', `The project has no module named ${name}`, {
+                    details: {
+                        module: name,
+                        modules: state.modules ?? [],
+                        fix: 'name one of details.modules (npx dokebi module list --json)',
+                    },
+                    phase: 'arguments',
+                });
             state.modules = (state.modules ?? []).filter((module) => module !== name);
             if (!state.modules.length)
                 delete state.modules;
-            await this.writeConfiguration(tx, state, session.configSource);
+            await this.writeConfiguration(tx, state, session.configSource, session.configFile);
             const result = {
                 changed: tx.paths,
                 preserved: [`src/shared/modules/${name}`],
@@ -1831,7 +4110,7 @@ export class Project {
     }
     /** `dokebi module list`: the registered modules in registration order. */
     async moduleList(root) {
-        const state = readState(parseObject(await readFile(await securePath(root, '.dokebi/state.json'), 'utf8'), 'state'));
+        const state = readState(parseObject(await projectStateText(root), 'state'));
         return {
             modules: (state.modules ?? []).map((name) => ({
                 name,
@@ -1839,21 +4118,297 @@ export class Project {
             })),
         };
     }
+    /**
+     * D-0155: `dokebi settings add <section>`: the settings of the application in options.<section>.
+     * Writes src/shared/settings/<section>.ts (or keeps one that is already there and default-exports
+     * defineSettings for this section), its schema file from the declaration, the defaults of the
+     * section in dokebi.yaml and the example (with the reloadable marks), and registers it so the
+     * app checks the section at start. A plugin's section, logging or reload is refused.
+     */
+    async settingsAdd(root, section, options = {}) {
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            if (!SETTINGS_SECTION.test(section))
+                throw new CliError('INVALID_SETTINGS', `Settings sections match ${SETTINGS_SECTION.source}`, {
+                    details: { section },
+                    phase: 'arguments',
+                });
+            const owner = state.plugins.find((plugin) => plugin.id === section || optionsKey(plugin) === section)
+                ?.id ?? session.required.find((plugin) => plugin.id === section)?.id;
+            if (owner !== undefined || RESERVED_SECTIONS.has(section))
+                throw new CliError('SETTINGS_SECTION_CONFLICT', `options.${section} belongs to ${owner ?? 'core'}, not to the application`, {
+                    details: {
+                        section,
+                        owner: owner ?? 'core',
+                        fix: 'choose another section name for the settings of the application',
+                    },
+                    phase: 'arguments',
+                });
+            if ((state.settings ?? []).includes(section))
+                throw new CliError('SETTINGS_EXISTS', `The application already has settings ${section}`, {
+                    details: {
+                        section,
+                        fix: 'edit the declaration, then npx dokebi settings sync; npx dokebi settings list lists them',
+                    },
+                    phase: 'arguments',
+                });
+            const file = settingsFile(section);
+            templateTarget(file);
+            const existing = await exists(await securePath(tx.root, file));
+            let schemaText;
+            if (existing)
+                schemaText = await renderSettingsSchema(session.root, section);
+            else {
+                // The declaration is read from a copy beside where it goes (same imports), then written.
+                const draft = join(session.root, SETTINGS_FOLDER, `.${section}.${process.pid}.draft.ts`);
+                // R4CA-8: the folders made for the draft go with it (a dry run applies nothing; the
+                // transaction makes them again for the real files).
+                const made = await mkdir(dirname(draft), { recursive: true });
+                try {
+                    await writeFile(draft, settingsSource(section));
+                    schemaText = await renderSettingsSchemaFrom(session.root, section, draft);
+                }
+                finally {
+                    await rm(draft, { force: true });
+                    if (made !== undefined)
+                        await rm(made, { recursive: true, force: true });
+                }
+                await tx.write(file, settingsSource(section));
+            }
+            await tx.write(settingsSchemaFile(section), schemaText);
+            const schema = JSON.parse(schemaText);
+            session.schemas.set(section, schema);
+            const configSource = scaffoldConfig(session.configSource, section, schema);
+            const warnings = [];
+            await this.#syncExamples(tx, session.root, warnings, [{ id: section, update: { schema } }]);
+            state.settings = [...(state.settings ?? []), section];
+            await this.writeConfiguration(tx, state, configSource, session.configFile);
+            const identifier = settingsIdentifier(section);
+            const result = {
+                changed: tx.paths,
+                preserved: existing ? [file] : [],
+                ...(warnings.length ? { warnings } : {}),
+                nextSteps: [
+                    {
+                        command: `edit ${file}`,
+                        why: `declare the options of options.${section} (every count, size and time with minimum, maximum and default; reloadable: true where a running app may take a change), then npx dokebi settings sync`,
+                    },
+                    {
+                        command: `import ${identifier} from '<relative path>/shared/settings/${section}.ts' and read ${identifier}.read(context.app.config)`,
+                        why: 'typed settings, cached per configuration and new after a reload; never read options.<section> by hand',
+                    },
+                ],
+            };
+            return await this.#finish(session, result, options.dryRun);
+        }
+        catch (error) {
+            // R4CA-12: after a termination signal, whatever failed before the commit (a plugin check
+            // or a settings declaration the terminal's Ctrl+C reached too) is INTERRUPTED.
+            throw tx.failure(error);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /**
+     * D-0155: `dokebi settings sync`: writes the schema file of every settings section again from
+     * its declaration and adds the defaults of new options to dokebi.yaml and the example (with the
+     * reloadable marks). Nothing is written when every schema is current. AI-M49 D2: a value that
+     * is still the old default (the CLI wrote it) follows a changed default (`followed`), and the
+     * options are checked against the new schema as doctor checks them: a missing required value
+     * is `configRequired`, anything else INVALID_PLUGIN_OPTIONS and nothing is written.
+     */
+    async settingsSync(root, dryRun = false) {
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            const sections = [];
+            const validator = new PluginOptionsValidator({ allErrors: true });
+            const configRequired = [];
+            let configSource = session.configSource;
+            const examples = [];
+            const warnings = [];
+            /** The schema before this sync, per section: what the CLI wrote as defaults (S-b). */
+            const previous = new Map();
+            for (const section of state.settings ?? []) {
+                const text = await renderSettingsSchema(session.root, section);
+                const path = settingsSchemaFile(section);
+                const current = (await exists(await securePath(tx.root, path)))
+                    ? await tx.read(path)
+                    : undefined;
+                const changed = current !== text;
+                if (changed)
+                    await tx.write(path, text);
+                const schema = JSON.parse(text);
+                session.schemas.set(section, schema);
+                const before = current === undefined ? null : JSON.parse(current);
+                previous.set(section, before);
+                // Options the declaration dropped: defaults the CLI wrote go, values set by hand are named.
+                const pruned = pruneUndeclared(configSource, section, before, schema);
+                // A default the CLI wrote follows the new default; a value set by hand stays (D2).
+                const followed = followDefaults(pruned.source, section, before, schema);
+                configSource = scaffoldConfig(followed.source, section, schema);
+                for (const key of pruned.kept)
+                    warnings.push({
+                        code: 'SETTINGS_KEY_UNDECLARED',
+                        path: `${session.configFile}#options.${section}.${key}`,
+                        hint: `${settingsFile(section)} no longer declares it and its value was set by hand: npx dokebi config unset ${section}.${key}, or declare it again`,
+                    });
+                // What doctor would refuse is never answered ok (D2: a lowered maximum under a value set
+                // by hand). A missing required value is reported, as add and config set report it.
+                const checked = await validator.checkSettingsWith(section, schema, optionsOf(parseProjectConfig(configSource).options, section));
+                const required = checked.errors.filter((error) => error.keyword === 'required');
+                const invalid = checked.errors.filter((error) => error.keyword !== 'required');
+                if (invalid.length)
+                    throw settingsStillInvalid(section, invalid, session.configFile);
+                if (required.length)
+                    configRequired.push({
+                        plugin: section,
+                        errors: required.slice(0, 20),
+                        errorCount: required.length,
+                    });
+                if (followed.updated.length)
+                    debug('Settings defaults the CLI wrote follow the new declaration', {
+                        section,
+                        paths: followed.updated,
+                    });
+                examples.push({ id: section, update: { schema } });
+                sections.push({
+                    section,
+                    changed,
+                    ...(followed.updated.length
+                        ? { followed: followed.updated.map((key) => `${section}.${key}`) }
+                        : {}),
+                });
+            }
+            // The example's values of dropped options go too (they are the old defaults), in the same
+            // write as the rest of its sync.
+            if (examples.length)
+                await this.#syncExamples(tx, session.root, warnings, examples, (source) => examples.reduce((next, { id, update }) => {
+                    const pruned = pruneUndeclared(next, id, previous.get(id) ?? null, update.schema);
+                    // R10: a value of a dropped option the example keeps (not the old default) is named too.
+                    for (const key of pruned.kept)
+                        warnings.push({
+                            code: 'SETTINGS_KEY_UNDECLARED',
+                            path: `${EXAMPLE}#options.${id}.${key}`,
+                            hint: `the declaration no longer has it: remove it from ${EXAMPLE}`,
+                        });
+                    // D2: the sample's copies of the CLI's defaults follow too.
+                    return followDefaults(pruned.source, id, previous.get(id) ?? null, update.schema)
+                        .source;
+                }, source));
+            if (configSource !== session.configSource || sections.some((item) => item.changed))
+                await this.writeConfiguration(tx, state, configSource, session.configFile);
+            debug('Settings schemas synchronized', {
+                sections: sections.length,
+                changed: sections.filter((item) => item.changed).length,
+            });
+            const result = await this.#finish(session, {
+                changed: tx.paths,
+                preserved: [],
+                ...(configRequired.length ? { configRequired } : {}),
+                ...(warnings.length ? { warnings } : {}),
+            }, dryRun);
+            return { ...result, sections };
+        }
+        catch (error) {
+            // R4CA-12: after a termination signal, whatever failed before the commit (a plugin check
+            // or a settings declaration the terminal's Ctrl+C reached too) is INTERRUPTED.
+            throw tx.failure(error);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /** `dokebi settings remove <section>`: unregisters it; its files and its options stay. */
+    async settingsRemove(root, section, dryRun = false) {
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            if (!(state.settings ?? []).includes(section))
+                throw new CliError('UNKNOWN_SETTINGS', `The application has no settings ${section}`, {
+                    details: {
+                        section,
+                        settings: state.settings ?? [],
+                        fix: 'name one of details.settings (npx dokebi settings list --json)',
+                    },
+                    phase: 'arguments',
+                });
+            state.settings = (state.settings ?? []).filter((item) => item !== section);
+            if (!state.settings.length)
+                delete state.settings;
+            await this.writeConfiguration(tx, state, session.configSource, session.configFile);
+            return await this.#finish(session, {
+                changed: tx.paths,
+                preserved: [
+                    settingsFile(section),
+                    settingsSchemaFile(section),
+                    `${session.configFile}#options.${section}`,
+                ],
+            }, dryRun);
+        }
+        catch (error) {
+            // R4CA-12: after a termination signal, whatever failed before the commit (a plugin check
+            // or a settings declaration the terminal's Ctrl+C reached too) is INTERRUPTED.
+            throw tx.failure(error);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /** `dokebi settings list`: the settings sections with their declaration and schema files. */
+    async settingsList(root) {
+        const state = readState(parseObject(await projectStateText(root), 'state'));
+        return {
+            settings: (state.settings ?? []).map((section) => ({
+                section,
+                file: settingsFile(section),
+                schema: settingsSchemaFile(section),
+            })),
+        };
+    }
     /**
      * What an Inertia app needs to be built (D-0031 supplement): one project-wide vite.config.ts
      * that finds every src/apps/<app>/views/app.js, a `build` script, the Vite and Vue packages as
      * dev dependencies, and dist/ in .gitignore. Existing files, scripts and versions are kept.
      * With server rendering (D-0039) also vite.ssr.config.ts, and `build` runs both builds.
+     * The Vue pages are type-checked too (AI-M23): `typecheck` runs typecheck-vue.mjs (vue-tsc on
+     * the TypeScript 6 API of @typescript/typescript6, since TypeScript 7 has no JavaScript API)
+     * with tsconfig.vue.json after tsc, and src/infra/inertia/page.d.ts types the shared props.
      */
     async #inertiaBuild(tx, session, host, warnings, ssr) {
         const source = await packageFile(session.root, host.packageName, 'templates/inertia-build');
+        // R4CC-6: an @dokebi/app older than this CLI (0.4.2 and before) has no Vue type check in its
+        // build template; that is a refusal of the plan before anything is written, with the upgrade.
+        const outdated = (what) => new CliError('INVALID_MANIFEST', `${host.packageName} ${host.version} has an Inertia build template without ${what}, which app add --inertia of this CLI writes`, {
+            phase: 'plan',
+            details: {
+                package: host.packageName,
+                version: host.version,
+                missing: what,
+                fix: `npx dokebi upgrade ${host.id}, then run the same app add again`,
+            },
+        });
+        for (const file of ['build.json', 'tsconfig.vue.json', 'typecheck-vue.mjs', 'page.d.ts'])
+            if (!(await exists(join(source, file))))
+                throw outdated(`templates/inertia-build/${file}`);
         const build = parseObject(await readFile(join(source, 'build.json'), 'utf8'), 'build.json');
         const wanted = object(build.devDependencies ?? {}, 'devDependencies');
-        const { build: browserScript, buildSsr: ssrScript } = object(build.scripts ?? {}, 'scripts');
+        const { build: browserScript, buildSsr: ssrScript, typecheck: typecheckScript, } = object(build.scripts ?? {}, 'scripts');
         const pkg = structuredClone(session.pkg);
         const scripts = object(pkg.scripts ?? {}, 'scripts');
-        if (typeof browserScript !== 'string' || typeof ssrScript !== 'string')
-            throw new CliError('INVALID_MANIFEST', 'build.json scripts');
+        if (typeof browserScript !== 'string' ||
+            typeof ssrScript !== 'string' ||
+            typeof typecheckScript !== 'string')
+            throw outdated(`the ${[
+                ['build', browserScript],
+                ['buildSsr', ssrScript],
+                ['typecheck', typecheckScript],
+            ]
+                .filter(([, value]) => typeof value !== 'string')
+                .map(([name]) => name)
+                .join(', ')} script of build.json`);
         const script = ssr ? ssrScript : browserScript;
         // The browser-only script of an earlier `app add --inertia` grows into the SSR one; a script
         // the developer wrote is kept, and the warning says to add the server build by hand.
@@ -1861,6 +4416,14 @@ export class Project {
             scripts.build = script;
         else if (scripts.build !== script && !(!ssr && scripts.build === ssrScript))
             warnings.push({ code: 'BUILD_SCRIPT_KEPT', path: 'package.json' });
+        // The server-only check init wrote grows into one that checks the .vue files too; a script
+        // the developer wrote is kept, and the warning says to add the Vue check by hand.
+        if (scripts.typecheck === undefined || scripts.typecheck === TYPECHECK_SCRIPT)
+            scripts.typecheck = typecheckScript;
+        else if (scripts.typecheck !== typecheckScript) {
+            debug('Kept the typecheck script of the project', { script: scripts.typecheck });
+            warnings.push({ code: 'TYPECHECK_SCRIPT_KEPT', path: 'package.json' });
+        }
         pkg.scripts = scripts;
         const devDependencies = object(pkg.devDependencies ?? {}, 'devDependencies');
         const dependencies = dependencyMap(pkg);
@@ -1881,11 +4444,31 @@ export class Project {
         else if (json(pkg) !== json(session.pkg))
             await tx.write('package.json', json(pkg));
         const configs = ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs'];
-        let configured = false;
+        let configured;
         for (const file of configs)
-            configured ||= await exists(await securePath(session.root, file));
+            if (!configured && (await exists(await securePath(session.root, file))))
+                configured = file;
         if (!configured)
             await tx.write('vite.config.ts', await readFile(join(source, 'vite.config.ts'), 'utf8'));
+        // D-0062 addendum (2026-10-20): views/app.js imports '@dokebi/seal/http', which the
+        // template-inertia Vite plugin maps to the module the app serves. A config of the project's
+        // own without it would bundle a second seal client (or fail to resolve the package).
+        else if (!(await readFile(await securePath(session.root, configured), 'utf8')).includes('dokebiInertia')) {
+            debug('Kept a Vite config without the Inertia plugin', { file: configured });
+            warnings.push({ code: 'VITE_PLUGIN_MISSING', path: configured });
+        }
+        // The Vue type check: its tsconfig, its runner and the shared page props, each written once.
+        for (const [file, target] of [
+            ['tsconfig.vue.json', 'tsconfig.vue.json'],
+            ['typecheck-vue.mjs', 'typecheck-vue.mjs'],
+            ['page.d.ts', 'src/infra/inertia/page.d.ts'],
+        ])
+            if (!(await exists(await securePath(session.root, target)))) {
+                const directory = dirname(target);
+                if (directory !== '.')
+                    await tx.ensureDirectory(directory);
+                await tx.write(target, await readFile(join(source, file), 'utf8'));
+            }
         if (ssr) {
             let ssrConfigured = false;
             for (const file of configs.map((name) => name.replace('vite.config', 'vite.ssr.config')))
@@ -1919,19 +4502,50 @@ export class Project {
         return catalog.packages.some((item) => installed.has(item.package) &&
             item.provides.some((capability) => capability.startsWith(prefix)));
     }
-    /** Shared by `app add` and the first app created when the apps host is added. */
-    async #addApp(tx, packagesRoot, host, state, configSource, name, options) {
+    /**
+     * The one path of every new app: `app add` and the first app created when the apps host is
+     * added. `plugins` are the plugins installed once the command is done (`add` passes the new
+     * list, which state does not hold yet). `layout` names the EJS view engine whose options the
+     * shared layout changed, for the caller to write into the shared sample too.
+     */
+    async #addApp(tx, packagesRoot, host, plugins, state, configSource, name, options) {
         if (!APP_NAME.test(name))
             throw new CliError('INVALID_APP', 'App names match ' + APP_NAME.source);
         const template = options.template ?? 'default';
         if (!APP_NAME.test(template))
             throw new CliError('INVALID_APP', 'Template names match ' + APP_NAME.source);
         if ((state.apps ?? []).includes(name))
-            throw new CliError('APP_EXISTS', name);
+            throw new CliError('APP_EXISTS', `The project already has an app named ${name}`, {
+                details: {
+                    app: name,
+                    fix: `choose another name, or give ${name} another domain with npx dokebi app link ${name} <domain>`,
+                },
+                phase: 'arguments',
+            });
         const folder = `src/apps/${name}`;
         templateTarget(folder + '/app.ts');
         if (await exists(await securePath(tx.root, folder)))
-            throw new CliError('FILE_CONFLICT', folder);
+            throw fileConflict(folder, `already exists, so app add does not write the app ${name} there`, `choose another name, or move ${folder} away and repeat this command`, { app: name });
+        // EJS or Inertia skeleton; `{{app}}` in text files becomes the app name (paths to its views).
+        // Server rendering lays app-inertia-ssr (views/ssr.js, an app.ts naming the bundle) on top.
+        const skeletons = options.inertia
+            ? ['app-inertia', ...(options.ssr ? ['app-inertia-ssr'] : [])]
+            : options.view === 'none'
+                ? []
+                : ['app'];
+        const files = new Map();
+        for (const skeleton of skeletons) {
+            const source = await packageFile(packagesRoot, host.packageName, `templates/${skeleton}`);
+            for (const file of await listFiles(source))
+                files.set(file, join(source, file));
+        }
+        // No views: two files of the CLI's own text instead of the host's EJS skeleton.
+        const texts = options.view === 'none' ? apiAppFiles(name) : new Map();
+        const layout = await this.#sharedLayout(tx, packagesRoot, plugins, configSource, [
+            ...files.keys(),
+            ...texts.keys(),
+        ]);
+        configSource = layout.configSource;
         const domains = [...new Set(options.domains ?? [])];
         const config = parseProjectConfig(configSource).options;
         for (const domain of domains) {
@@ -1939,22 +4553,11 @@ export class Project {
                 throw new CliError('INVALID_APP', 'Domains are lower-case host names without a port');
             const current = domainTarget(config, host.id, domain);
             if (current && current !== name)
-                throw new CliError('DOMAIN_IN_USE', domain, { details: { domain, app: current } });
+                throw domainInUse(domain, current);
         }
         // Directories first: commit creates them in order, before files create parents themselves.
         if (template !== 'default')
             await tx.ensureDirectory(`${folder}/views/${template}`);
-        // EJS or Inertia skeleton; `{{app}}` in text files becomes the app name (paths to its views).
-        // Server rendering lays app-inertia-ssr (views/ssr.js, an app.ts naming the bundle) on top.
-        const skeletons = options.inertia
-            ? ['app-inertia', ...(options.ssr ? ['app-inertia-ssr'] : [])]
-            : ['app'];
-        const files = new Map();
-        for (const skeleton of skeletons) {
-            const source = await packageFile(packagesRoot, host.packageName, `templates/${skeleton}`);
-            for (const file of await listFiles(source))
-                files.set(file, join(source, file));
-        }
         for (const [file, path] of files) {
             const target = `${folder}/${file}`;
             templateTarget(target);
@@ -1963,18 +4566,87 @@ export class Project {
                 ? content.toString('utf8').replaceAll('{{app}}', name)
                 : content);
         }
-        const changes = domainChanges(domains, template === 'default' ? { app: name } : { app: name, template });
+        for (const [file, text] of texts) {
+            templateTarget(`${folder}/${file}`);
+            await tx.write(`${folder}/${file}`, text);
+        }
+        const changes = domainChanges(domains, domainTargetOf(name, template, options.seal));
         state.apps = [...(state.apps ?? []), name];
-        return { configSource: applyConfigChanges(configSource, host.id, changes), changes };
+        return {
+            configSource: applyConfigChanges(configSource, host.id, changes),
+            changes,
+            ...(layout.engine ? { layout: { engine: layout.engine, changes: layout.changes } } : {}),
+        };
     }
-    async writeConfiguration(tx, state, configSource) {
-        const generated = generateRegistration(state.plugins, state.installations, state.apps ?? [], state.modules ?? []);
+    /**
+     * The shared layout of an app whose skeleton has EJS views (D-0110 §3). Its view engine is the
+     * installed plugin that provides the catalog capability `view.ejs`, found by capability as
+     * D-0070 finds hosts, never by package name: that plugin's `templates/layouts/main.ejs` goes to
+     * src/shared/views/layouts/main.ejs (kept when it is there) and its `defaultLayout` becomes
+     * `layouts/main`, once. The engine installs no page scaffolds itself, so a project of Inertia
+     * apps only keeps the engine entry (mail templates, error pages) without unused HTML.
+     */
+    async #sharedLayout(tx, packagesRoot, plugins, configSource, skeletonFiles) {
+        if (!skeletonFiles.some((file) => file.endsWith('.ejs'))) {
+            debug('App skeleton has no EJS views; no shared EJS layout');
+            return { configSource, changes: [] };
+        }
+        const installed = new Map(plugins.map((plugin) => [plugin.packageName, plugin]));
+        const providers = providersOf(await loadCatalog(), EJS_VIEW)
+            .map((item) => installed.get(item.package))
+            .filter((plugin) => plugin !== undefined);
+        const engine = providers[0];
+        if (!engine) {
+            debug('No installed plugin provides the EJS view; the app has no shared layout', {
+                capability: EJS_VIEW,
+            });
+            return { configSource, changes: [] };
+        }
+        if (providers.length > 1)
+            debug('More than one installed plugin provides the EJS view; the first in the catalog', {
+                capability: EJS_VIEW,
+                plugins: providers.map((plugin) => plugin.id),
+                engine: engine.id,
+            });
+        if (optionAt(configSource, engine.id, [EJS_LAYOUT.option]) !== undefined) {
+            debug('The EJS view engine already has a default layout', { engine: engine.id });
+            return { configSource, changes: [] };
+        }
+        if (await exists(await securePath(tx.root, EJS_LAYOUT.target)))
+            debug('Shared layout kept', { path: EJS_LAYOUT.target });
+        else {
+            const source = await packageFile(packagesRoot, engine.packageName, EJS_LAYOUT.source);
+            await tx.write(EJS_LAYOUT.target, await readFile(source));
+            debug('Shared layout written', { path: EJS_LAYOUT.target, engine: engine.id });
+        }
+        const changes = [
+            { op: 'default', path: [EJS_LAYOUT.option], value: EJS_LAYOUT.value },
+        ];
+        return {
+            configSource: applyConfigChanges(configSource, engine.id, changes),
+            engine: engine.id,
+            changes,
+        };
+    }
+    async writeConfiguration(tx, state, configSource, 
+    /** The settings file (M50: the one DOKEBI_CONFIG names for the config commands). */
+    configFile) {
+        const generated = generateRegistration(state.plugins, state.installations, state.apps ?? [], state.modules ?? [], state.settings ?? []);
         state.generatedHash = hash(generated);
         await tx.write(GENERATED, generated);
-        await tx.write(CONFIG_FILE, configSource);
+        await tx.write(configFile, configSource);
         await tx.write('.dokebi/state.json', json(state));
     }
 }
+/** The catalog capability of the view engine of EJS app skeletons (D-0110 §3). */
+const EJS_VIEW = 'view.ejs';
+/** What a `view.ejs` provider ships for a new EJS app: its shared layout and the option naming it. */
+const EJS_LAYOUT = {
+    source: 'templates/layouts/main.ejs',
+    target: 'src/shared/views/layouts/main.ejs',
+    option: 'defaultLayout',
+    value: 'layouts/main',
+};
 const HOST = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;
 /** `options.<apps host>.domains` (D-0030): domain → { app, template? }. */
 function domainsOf(options, host) {
@@ -2016,6 +4688,14 @@ function parseAndRender(source) {
     return source;
 }
 /** Replaces each domain mapping (remove, then set) so a re-link changes app or template. */
+/** One `domains.<host>` entry: the app, its template unless default, and `seal: true` if asked. */
+function domainTargetOf(app, template, seal) {
+    return {
+        app,
+        ...(template === 'default' ? {} : { template }),
+        ...(seal ? { seal: true } : {}),
+    };
+}
 function domainChanges(domains, target) {
     return domains.flatMap((domain) => [
         { op: 'remove', path: ['domains', domain] },