@dokebi/cli 0.2.5 → 0.4.0

package/dist/project.js

@@ -1,27 +1,117 @@
+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 lt from 'semver/functions/lt.js';
 import satisfies from 'semver/functions/satisfies.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 { debug, describeError, isMissing } from './diagnostics.js';
+import { checkEnvText } 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, TSCONFIG_SOURCE, } from './generator.js';
-import { orderPlugins, PACKAGE_NAME, readManifest, } from './manifest.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 { mergeInstallDefaults } from './merge-install-defaults.js';
-import { dependencyMap, NpmClient, packageSpec, validateProjectPackage } from './npm-client.js';
+import { dependencyMap, NpmClient, packageSpec, stageNpmConfig, validateProjectPackage, } from './npm-client.js';
+import { CLI_VERSION } from './output.js';
 import { checkAll, optionsOf, planLifecycle, } from './plugin-lifecycle.js';
 import { PluginOptionsValidator, validatePluginOptions } from './plugin-options.js';
-import { PROJECT_GUIDE } from './project-guide.js';
+import { AGENTS_FILE, CLAUDE_FILE, CLAUDE_GUIDE, guideEntries, installedBlock, projectGuide, replaceInstalledBlock, } from './project-guide.js';
 import { APP_NAME, defaultInstallation, emptyState, readState, } from './project-state.js';
+import { resolveVersion } from './registry.js';
 import { readRequiredPlugins } from './required-plugins.js';
 import { Transaction } from './transaction.js';
 import { installedPath, packageFile, workspacePackages, workspaceRootOf, } from './workspace.js';
 const GENERATED = 'src/dokebi.generated.ts';
 const EXAMPLE = 'dokebi.example.yaml';
+/**
+ * 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.
+ */
+export function initNextSteps(target) {
+    return [
+        {
+            command: `cd ${JSON.stringify(target)} && npx dokebi guide --json`,
+            why: 'read the AI flow first (in the project root): ask the recipe questions, install, verify',
+        },
+        {
+            command: 'npx dokebi recipe list --json',
+            why: 'the main path: pick a recipe (blog, api) for the request',
+        },
+        {
+            command: 'npx dokebi recipe <name> --json',
+            why: 'returns the questions to ask the user (installs nothing); answer with flags, --dry-run first, then apply',
+        },
+        {
+            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)',
+        },
+        {
+            command: 'npx dokebi verify --json',
+            why: 'doctor, typecheck, build, start, HTTP checks and stop; say done only when ok is true',
+        },
+    ];
+}
+/**
+ * Entries `dokebi init` leaves in an existing folder (D-0065 §11, AI-M02: agents are often handed
+ * an empty work folder, sometimes with npm or editor files in it). Nothing here is written by init
+ * or is part of a Node project; `.npmrc` is also used for init's own npm install.
+ */
+export const INIT_HARMLESS = [
+    '.git',
+    '.npmrc',
+    '.npm',
+    '.npm-cache',
+    '.DS_Store',
+    'Thumbs.db',
+    '.idea',
+    '.vscode',
+];
+function initRefused(target, entries, why) {
+    return new CliError('PROJECT_EXISTS', `${target} is not empty: ${entries.slice(0, 10).join(', ')}${entries.length > 10 ? ', …' : ''} ${why}`, {
+        phase: 'arguments',
+        details: {
+            target,
+            entries: entries.slice(0, 50),
+            allowed: INIT_HARMLESS,
+            fix: `init a new folder inside it (npx -y @dokebi/cli init <name>, then cd <name>), or empty it; only ${INIT_HARMLESS.join(', ')} may already be there`,
+        },
+    });
+}
+/**
+ * Whether `dokebi init` may use `target`: absent (created), or a folder that is empty or holds
+ * only INIT_HARMLESS entries (`kept`). Anything else (a file, other entries) is PROJECT_EXISTS.
+ */
+export async function initFolder(target, 
+/** init's own staging folder inside `target` (checked again before the move). */
+staging) {
+    let names;
+    try {
+        names = (await readdir(target)).filter((name) => name !== staging);
+    }
+    catch (error) {
+        const code = error.code;
+        // A file (or a path through one) is not a folder to create the project in.
+        if (code === 'ENOTDIR')
+            throw initRefused(target, [basename(target)], 'is a file');
+        if (code === 'ENOENT')
+            return { exists: false, kept: [] };
+        throw error;
+    }
+    const blocking = names.filter((name) => !INIT_HARMLESS.includes(name)).sort();
+    if (blocking.length)
+        throw initRefused(target, blocking, blocking.includes('package.json') || blocking.includes('.dokebi')
+            ? '(already a project: run npx dokebi … inside it instead of init)'
+            : '(dokebi init writes into an empty folder only)');
+    return { exists: true, kept: names.sort() };
+}
 const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'optionalDependencies'];
 function union(...lists) {
     return [...new Set(lists.flat())];
@@ -31,36 +121,61 @@ export class Project {
     constructor(npm = new NpmClient()) {
         this.npm = npm;
     }
-    async init(target, core = '@dokebi/core@^0.2.2') {
+    async init(target, core = '@dokebi/core@^0.4.0', dryRun = false) {
         target = resolve(target);
-        if (await exists(target))
-            throw new CliError('PROJECT_EXISTS', target);
-        const parent = await realpath(dirname(target));
-        const staging = await mkdtemp(join(parent, '.dokebi-init-'));
+        // 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);
+        if (dryRun)
+            return {
+                changed: [target],
+                preserved: folder.kept.map((name) => join(target, name)),
+                nextSteps: initNextSteps(target),
+            };
+        // 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.
+        const staging = folder.exists
+            ? await mkdtemp(join(await realpath(target), '.dokebi-init-'))
+            : await mkdtemp(join(await realpath(dirname(target)), '.dokebi-init-'));
         try {
+            // A project .npmrc already in the folder (registry, cache) applies to this install too.
+            if (folder.kept.includes('.npmrc'))
+                await stageNpmConfig(target, staging);
             await mkdir(join(staging, 'src'));
             await mkdir(join(staging, '.dokebi'));
             await writeFile(join(staging, 'package.json'), json({
                 name: basename(target)
                     .toLowerCase()
-                    .replace(/[^a-z0-9-]/g, '-') || 'dokebi-app',
+                    .replace(/[^a-z0-9-]/g, '-') || FALLBACK_PROJECT_NAME,
                 private: true,
                 type: 'module',
-                scripts: { start: 'node src/main.ts' },
+                scripts: { start: 'node src/main.ts', typecheck: TYPECHECK_SCRIPT },
                 engines: { node: '>=24.0.0' },
+                // npm installs these together with core (one npm run); --save-exact keeps them pinned.
+                devDependencies: PROJECT_DEV_DEPENDENCIES,
             }));
+            debug('Initializing project', { target, core, devDependencies: PROJECT_DEV_DEPENDENCIES });
             await this.npm.install(staging, packageSpec(core, process.cwd()));
-            await this.coreVersion(staging);
-            await readRequiredPlugins(staging);
             const generated = generateRegistration([]);
             await writeFile(join(staging, GENERATED), generated);
             await writeFile(join(staging, 'src/main.ts'), MAIN_SOURCE);
-            await writeFile(join(staging, 'AGENTS.md'), PROJECT_GUIDE);
+            const requiredPlugins = await readRequiredPlugins(staging);
+            await writeFile(join(staging, AGENTS_FILE), projectGuide(guideEntries(await this.coreVersion(staging), requiredPlugins, [], CLI_VERSION)));
+            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'));
+            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),
+                };
+            }
             // Reserve the destination before moving anything so existing projects are never replaced.
             await mkdir(target);
             try {
@@ -75,12 +190,43 @@ export class Project {
                 }
                 throw cause;
             }
-            return { changed: [target], preserved: [] };
+            return { changed: [target], preserved: [], nextSteps: initNextSteps(target) };
         }
         finally {
             await rm(staging, { recursive: true, force: true });
         }
     }
+    /**
+     * Moves the staged project into an existing folder entry by entry. The folder is checked again
+     * first (something may have appeared during npm install); a failure moves back what was moved,
+     * so the folder ends as it was.
+     */
+    async #moveInto(staging, target, kept) {
+        await initFolder(target, basename(staging));
+        // The staged .npmrc is a copy of the folder's own (kept), so it is not moved.
+        const staged = (await readdir(staging)).filter((name) => !kept.includes(name));
+        const moved = [];
+        try {
+            for (const name of staged) {
+                await rename(join(staging, name), join(target, name));
+                moved.push(name);
+            }
+        }
+        catch (cause) {
+            const failed = [cause];
+            for (const name of moved.reverse()) {
+                try {
+                    await rename(join(target, name), join(staging, name));
+                }
+                catch (cleanup) {
+                    failed.push(cleanup);
+                }
+            }
+            if (failed.length > 1)
+                throw new AggregateError(failed, 'Initialization and destination cleanup failed');
+            throw cause;
+        }
+    }
     async migrate(root, dryRun = false) {
         root = await realpath(root);
         await readFile(await securePath(root, '.dokebi/state.json'));
@@ -123,28 +269,79 @@ export class Project {
             await tx.close();
         }
     }
-    async add(root, spec, dryRun = false, sets = []) {
-        const operation = packageSpec(spec, root);
+    async add(root, spec, dryRun = false, sets = [], options = {}) {
+        let operation = packageSpec(spec, root);
         const session = await this.#begin(root);
         const { tx, state } = session;
         try {
+            const warnings = setWarnings(sets);
+            // No version: the highest one this project's core supports (D-0065).
+            const resolution = await this.#resolve(session, operation, warnings);
+            if (resolution)
+                operation = `${resolution.package}@${resolution.version}`;
             const dependencies = dependencyMap(session.pkg);
-            const staging = await this.#stage(session, session.pkg, dependencies, operation);
+            let staging;
+            try {
+                staging = await this.#stage(session, session.pkg, dependencies, operation);
+            }
+            catch (error) {
+                // Offline: say the version came from the snapshot (CATALOG_OFFLINE) next to npm's error.
+                if (error instanceof CliError &&
+                    error.code === 'NPM_FAILED' &&
+                    warnings.some((warning) => warning.code === 'CATALOG_OFFLINE'))
+                    throw new CliError(error.code, error.message, {
+                        cause: error.cause ?? error,
+                        details: {
+                            ...error.details,
+                            warnings,
+                            ...(resolution ? { resolved: resolution } : {}),
+                        },
+                        phase: 'install',
+                    });
+                throw error;
+            }
             const after = await this.#installedDependencies(staging);
             const name = operation.startsWith('file:')
                 ? Object.keys(after).find((key) => after[key] === operation)
                 : /^(@[^/]+\/[^@]+|[^@]+)/.exec(operation)?.[1];
             if (!name || !Object.hasOwn(after, name))
                 throw new CliError('INVALID_PACKAGE', 'Cannot identify installed package');
+            // Only @dokebi packages are this framework's; anything else needs the user's consent.
+            if (!name.startsWith('@dokebi/'))
+                warnings.push({ code: 'THIRD_PARTY_PACKAGE', path: name });
             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');
+            if (options.adapter !== undefined && added.id !== 'dokebi-db')
+                throw new CliError('USAGE', '--adapter applies to @dokebi/db 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"])');
             const existing = state.plugins.find((plugin) => plugin.id === added.id || plugin.packageName === added.packageName);
             if (existing) {
                 if (existing.id === added.id &&
                     existing.packageName === added.packageName &&
-                    existing.version === added.version)
-                    return { changed: [], preserved: [] };
+                    existing.version === added.version) {
+                    if (options.adapter === undefined)
+                        return { changed: [], preserved: [] };
+                    // An installed db gets its adapter now (adapter file, connection, driver).
+                    const adapted = await this.#dbAdapter(session, staging, options.adapter, {
+                        configSource: session.configSource,
+                        fresh: false,
+                        warnings,
+                    });
+                    await this.#syncExamples(tx, session.root, warnings, [
+                        { id: 'dokebi-db', update: { changes: adapted.changes } },
+                    ]);
+                    await this.writeConfiguration(tx, state, adapted.configSource);
+                    await this.#replacePackages(session, staging, session.pkg);
+                    return await this.#finish(session, {
+                        changed: tx.paths,
+                        preserved: [],
+                        ...(warnings.length ? { warnings } : {}),
+                        nextSteps: adapted.nextSteps,
+                    }, dryRun);
+                }
                 throw new CliError('UPGRADE_UNSUPPORTED', `Use dokebi upgrade ${added.id}`);
             }
             if (Object.hasOwn(dependencies, name))
@@ -152,10 +349,15 @@ export class Project {
             // 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);
+            // The adapter's driver joins the same staging install before the checks run.
+            const adapter = options.adapter === undefined
+                ? undefined
+                : await this.#adapterVariant(staging, options.adapter);
+            if (adapter)
+                await this.#installDriver(session, staging, adapter.variant, dependencies);
             const installed = await this.#installedDependencies(staging);
             await this.#verifyManifests(staging, state.plugins);
             const ordered = await this.#order(staging, [...state.plugins, ...automatic, added], session.required);
-            const warnings = setWarnings(sets);
             let configSource = sets.length
                 ? applySetOptions(session.configSource, added.id, sets)
                 : session.configSource;
@@ -165,6 +367,8 @@ export class Project {
             const installations = { ...state.installations };
             const newIds = new Set([...automatic, added].map((plugin) => plugin.id));
             const examples = [];
+            const nextSteps = [];
+            const envSecrets = [];
             // 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({
@@ -185,22 +389,41 @@ export class Project {
                     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);
-                await this.#addFiles(tx, staging, state, plugin, this.#planFiles(plan));
+                // `--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 },
                 });
             }
             // The first app comes with the plugin, so a new multi-app project runs right away.
-            if (added.id === 'dokebi-app' && !(state.apps ?? []).length) {
-                const first = await this.#addApp(tx, staging, state, configSource, 'main', {
+            if (hostsApps && !(state.apps ?? []).length && options.firstApp !== false) {
+                const first = await this.#addApp(tx, staging, added, state, configSource, 'main', {
                     domains: ['localhost'],
                 });
                 configSource = first.configSource;
                 config = parseProjectConfig(configSource);
-                examples.push({ id: 'dokebi-app', update: { changes: first.changes } });
+                examples.push({ id: added.id, update: { changes: first.changes } });
             }
             await this.#syncExamples(tx, session.root, warnings, examples);
             const configRequired = [];
@@ -209,10 +432,25 @@ export class Project {
             state.plugins = ordered;
             state.installations = installations;
             await this.writeConfiguration(tx, state, configSource);
+            const generatedSecrets = await this.#generateEnvSecrets(session, envSecrets);
+            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.
+            for (const plugin of ordered.filter((item) => newIds.has(item.id)))
+                if (plugin.documentation)
+                    nextSteps.push({
+                        command: `npx dokebi plugins doc ${plugin.id} --json`,
+                        why: `read node_modules/${plugin.packageName}/${plugin.documentation} (the installed ${plugin.version} contract) before using ${plugin.id}`,
+                    });
+            if (hostsApps && options.firstApp === false)
+                nextSteps.push({
+                    command: 'npx dokebi app add <name> --domain localhost [--inertia [--ssr]]',
+                    why: `--no-first-app: no app exists yet; ${added.id} needs one before the project starts`,
+                });
             const result = {
                 changed: tx.paths,
                 preserved: [],
+                ...(resolution ? { resolved: resolution } : {}),
                 ...(configRequired.length ? { configRequired } : {}),
                 ...(automatic.length
                     ? {
@@ -224,6 +462,8 @@ export class Project {
                     }
                     : {}),
                 ...(warnings.length ? { warnings } : {}),
+                ...(generatedSecrets.length ? { generatedSecrets } : {}),
+                nextSteps,
             };
             return await this.#finish(session, result, dryRun);
         }
@@ -231,6 +471,177 @@ export class Project {
             await tx.close();
         }
     }
+    /**
+     * 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) {
+        if (operation.startsWith('file:'))
+            return undefined;
+        const bare = /^(@[^/@]+\/[^@]+|[^@]+)$/.exec(operation)?.[1];
+        if (!bare || session.workspace?.packages.has(bare))
+            return undefined;
+        const core = await this.coreVersion(session.root);
+        // 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);
+        if (found.offline !== undefined) {
+            warnings.push({ code: 'CATALOG_OFFLINE', path: bare });
+            debug('Registry unreachable while resolving a version', {
+                package: bare,
+                error: found.offline,
+                snapshot: found.resolution?.version ?? null,
+            });
+        }
+        if (found.resolution?.deprecated)
+            warnings.push({
+                code: 'DEPRECATED_VERSION',
+                path: `${found.resolution.package}@${found.resolution.version}`,
+            });
+        if (found.resolution)
+            debug('Resolved a version for add', { ...found.resolution });
+        return found.resolution;
+    }
+    /** The db variant (from the staged @dokebi/db, else the CLI snapshot) for `--adapter`. */
+    async #adapterVariant(base, adapter) {
+        let variants = [];
+        try {
+            const pkg = parseObject(await readFile(await packageFile(base, '@dokebi/db', 'package.json'), 'utf8'), '@dokebi/db');
+            variants = pkg.dokebiCatalog?.variants ?? [];
+        }
+        catch (error) {
+            if (!(error instanceof CliError) && !isMissing(error))
+                throw error;
+            debug('Installed @dokebi/db has no readable catalog; using the CLI snapshot', {
+                error: describeError(error),
+            });
+        }
+        if (!variants.length)
+            variants =
+                (await loadCatalog()).packages.find((item) => item.package === '@dokebi/db')?.variants ??
+                    [];
+        const variant = variants.find((item) => item.adapter === adapter);
+        if (!variant)
+            throw new CliError('UNKNOWN_ADAPTER', `No database adapter "${adapter}"`, {
+                details: {
+                    adapter,
+                    adapters: variants.map((item) => item.adapter).filter(Boolean),
+                },
+                phase: 'arguments',
+            });
+        return { name: adapter, variant };
+    }
+    /** Adds the variant's driver (and its types) to the staged project and installs them. */
+    async #installDriver(session, staging, variant, dependencies) {
+        const path = join(staging, 'package.json');
+        const staged = parseObject(await readFile(path, 'utf8'), 'staged');
+        let changed = false;
+        if (variant.driver && !Object.hasOwn(dependencies, variant.driver.package)) {
+            staged.dependencies = {
+                ...object(staged.dependencies ?? {}, 'dependencies'),
+                [variant.driver.package]: variant.driver.version,
+            };
+            changed = true;
+        }
+        const dev = object(staged.devDependencies ?? {}, 'devDependencies');
+        if (variant.types && !Object.hasOwn(dev, variant.types.package)) {
+            staged.devDependencies = { ...dev, [variant.types.package]: variant.types.version };
+            changed = true;
+        }
+        if (!changed)
+            return;
+        debug('Installing the database driver', {
+            driver: variant.driver?.package ?? null,
+            types: variant.types?.package ?? null,
+        });
+        await writeFile(path, json(staged));
+        await this.#stageInstall(session, staging, undefined);
+    }
+    /**
+     * `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.
+     */
+    async #dbAdapter(session, staging, adapter, input) {
+        const { tx, state } = session;
+        const { variant } = await this.#adapterVariant(staging, adapter);
+        if (!input.fresh) {
+            await this.#installDriver(session, staging, variant, dependencyMap(session.pkg));
+        }
+        const templates = 'templates/adapters';
+        const adapterSource = await packageFile(staging, '@dokebi/db', `${templates}/${adapter}.ts`);
+        const connectionsSource = await packageFile(staging, '@dokebi/db', `${templates}/connections.ts`);
+        if (!(await exists(adapterSource)) || !(await exists(connectionsSource)))
+            throw new CliError('ADAPTER_TEMPLATE_MISSING', 'This @dokebi/db has no adapter templates', {
+                details: { adapter },
+            });
+        const adapterText = await readFile(adapterSource, 'utf8');
+        const exportName = /export const (\w+)/.exec(adapterText)?.[1];
+        if (!exportName)
+            throw new CliError('INVALID_MANIFEST', `${templates}/${adapter}.ts`);
+        const adapterTarget = `src/infra/db/adapters/${adapter}.ts`;
+        templateTarget(adapterTarget);
+        const nextSteps = [];
+        const current = await fingerprint(await securePath(session.root, adapterTarget));
+        if (current === null) {
+            await tx.ensureDirectory('src/infra/db/adapters');
+            await tx.write(adapterTarget, adapterText);
+        }
+        else if (current !== hash(adapterText))
+            input.warnings.push({ code: 'ADAPTER_FILE_KEPT', path: adapterTarget });
+        const entryContent = (await readFile(connectionsSource, 'utf8'))
+            .replaceAll('__ADAPTER_ID__', adapter)
+            .replaceAll('__ADAPTER__', exportName);
+        const entry = input.entry ?? state.installations['dokebi-db']?.entry ?? 'src/infra/db/connections.ts';
+        let written;
+        if (input.fresh)
+            written = entryContent;
+        else {
+            // An entry file still equal to the installed template is replaced; an edited one is kept.
+            const owned = state.files[entry];
+            const now = await fingerprint(await securePath(session.root, entry));
+            if (owned && now === owned.hash)
+                await tx.write(entry, entryContent);
+            else {
+                input.warnings.push({ code: 'CONNECTIONS_KEPT', path: entry });
+                nextSteps.push({
+                    command: `edit ${entry}`,
+                    why: `add: import { ${exportName} } from './adapters/${adapter}.ts'; export const main = defineConnection('main', ${exportName}); and put main in connections`,
+                });
+            }
+        }
+        const placeholder = `${URL_PLACEHOLDER_PREFIX}set the ${variant.name} URL here or run npx dokebi dev-infra>`;
+        const connection = parseProjectConfig(input.configSource).options['dokebi-db']?.connections?.main;
+        const changes = [
+            {
+                op: 'default',
+                path: ['connections', 'main'],
+                value: { adapter, options: { url: placeholder } },
+            },
+        ];
+        if (connection && connection.adapter !== adapter)
+            input.warnings.push({
+                code: 'CONNECTION_KEPT',
+                path: 'dokebi.yaml#options.dokebi-db.connections.main',
+            });
+        const configSource = applyConfigChanges(input.configSource, 'dokebi-db', changes);
+        if (!connection)
+            nextSteps.push({
+                command: variant.devInfra?.docker
+                    ? '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',
+            });
+        return {
+            configSource,
+            changes,
+            ...(written !== undefined ? { entryContent: written } : {}),
+            nextSteps,
+        };
+    }
     /**
      * 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
@@ -268,11 +679,13 @@ export class Project {
         const session = await this.#begin(root);
         const { tx, state } = session;
         try {
-            if (id === 'dokebi-app' && (state.apps ?? []).length)
+            // The host of apps or modules (D-0070) stays while its units are registered.
+            const hosts = state.plugins.find((plugin) => plugin.id === id)?.hosts ?? [];
+            if (hosts.includes('apps') && (state.apps ?? []).length)
                 throw new CliError('APPS_PRESENT', 'Remove the apps first (dokebi app remove <name>)', {
                     details: { apps: state.apps },
                 });
-            if (id === 'dokebi-module' && (state.modules ?? []).length)
+            if (hosts.includes('modules') && (state.modules ?? []).length)
                 throw new CliError('MODULES_PRESENT', 'Remove the modules first (dokebi module remove <name>)', { details: { modules: state.modules } });
             if (session.required.some((plugin) => plugin.id === id || plugin.packageName === id))
                 throw new CliError('REQUIRED_PLUGIN', 'Core-required plugins cannot be removed');
@@ -349,6 +762,7 @@ export class Project {
             state.plugins = ordered;
             state.installations = installations;
             await this.writeConfiguration(tx, state, configSource);
+            await this.#syncGuide(session, staging, ordered, warnings);
             await this.#replacePackages(session, staging, session.pkg);
             const result = {
                 changed: tx.paths,
@@ -446,6 +860,7 @@ export class Project {
             state.plugins = ordered;
             state.installations = installations;
             await this.writeConfiguration(tx, state, configSource);
+            await this.#syncGuide(session, staging, ordered, warnings);
             await this.#replacePackages(session, staging, session.pkg);
             const result = {
                 changed: tx.paths,
@@ -463,6 +878,294 @@ export class Project {
             await 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.
+     */
+    async #syncGuide(session, base, plugins, warnings) {
+        if (!(await exists(await securePath(session.root, AGENTS_FILE))))
+            return;
+        const text = await session.tx.read(AGENTS_FILE);
+        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) {
+            warnings.push({ code: 'GUIDE_BLOCK_MISSING', path: AGENTS_FILE });
+            return;
+        }
+        if (next !== text)
+            await session.tx.write(AGENTS_FILE, next);
+    }
+    /**
+     * `dokebi config set <plugin>.<path>=<value>…`: non-secret options in dokebi.yaml, checked
+     * against that plugin's schema (only missing required values are tolerated and reported).
+     */
+    async configSet(root, assignments, dryRun = false) {
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            let configSource = session.configSource;
+            const warnings = [];
+            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));
+                if (checked.errors.every((error) => error.keyword === 'required')) {
+                    if (checked.errors.length)
+                        configRequired.push({
+                            plugin: id,
+                            errors: checked.errors.slice(0, 20),
+                            errorCount: checked.errors.length,
+                        });
+                }
+                else
+                    throw new CliError('INVALID_PLUGIN_OPTIONS', id, {
+                        details: {
+                            plugin: id,
+                            errors: checked.errors.slice(0, 20),
+                            errorCount: checked.errors.length,
+                        },
+                    });
+            }
+            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);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /** Adds `.env` to .gitignore unless a line already ignores it (D-0065, D-0073). */
+    async #ignoreEnv(session) {
+        const { tx } = session;
+        const ignorePath = await securePath(session.root, '.gitignore');
+        const ignore = (await exists(ignorePath)) ? await tx.read('.gitignore') : '';
+        if (!ignore.split(/\r?\n/).some((line) => [ENV_FILE, `/${ENV_FILE}`].includes(line.trim())))
+            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.
+     */
+    async #generateEnvSecrets(session, requests) {
+        if (!requests.length)
+            return [];
+        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);
+        let text = original;
+        const generated = [];
+        for (const { plugin, variable } of requests) {
+            const kept = process.env[variable] !== undefined
+                ? 'environment'
+                : Object.hasOwn(present, variable) || generated.some((item) => item.variable === variable)
+                    ? ENV_FILE
+                    : undefined;
+            if (kept) {
+                debug('Secret variable already set; nothing generated', { plugin, variable, in: kept });
+                continue;
+            }
+            text = withEnv(text, variable, randomBytes(48).toString('base64url'), `${plugin} secret, generated by dokebi add; not committed (the environment wins over this file)`);
+            generated.push({ variable, file: ENV_FILE, plugin });
+            debug('Generated a secret into .env', { plugin, variable });
+        }
+        if (!generated.length)
+            return [];
+        await tx.write(ENV_FILE, text);
+        await this.#ignoreEnv(session);
+        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.
+     */
+    async devInfra(root, options = {}) {
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            if (!state.plugins.some((plugin) => plugin.id === 'dokebi-db'))
+                throw new CliError('DB_PLUGIN_MISSING', 'Run dokebi add @dokebi/db --adapter <id> first', {
+                    phase: 'arguments',
+                });
+            const connections = parseProjectConfig(session.configSource).options['dokebi-db']?.connections;
+            const main = connections?.main;
+            if (typeof main?.adapter !== 'string')
+                throw new CliError('CONNECTION_MISSING', 'dokebi.yaml has no options.dokebi-db.connections.main; run dokebi add @dokebi/db --adapter <id>', { phase: 'arguments' });
+            const { variant } = await this.#adapterVariant(session.root, main.adapter);
+            const docker = variant.devInfra?.docker;
+            if (!docker)
+                throw new CliError('DEV_INFRA_UNSUPPORTED', `No Docker setup for ${variant.name}`, {
+                    details: { adapter: main.adapter },
+                });
+            const warnings = [];
+            let port = options.dbPort ?? docker.port;
+            const composePath = await securePath(session.root, COMPOSE_FILE);
+            if (await exists(composePath)) {
+                const existing = parse(await tx.read(COMPOSE_FILE));
+                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 });
+            }
+            else {
+                // The container would not start on a taken port: refuse, and name a free one.
+                if (await portInUse(port)) {
+                    const alternative = await freePortAfter(port);
+                    throw new CliError('PORT_IN_USE', `Port ${port} on 127.0.0.1 is in use`, {
+                        phase: 'arguments',
+                        details: {
+                            port,
+                            ...(alternative ? { alternative } : {}),
+                            hint: `run again with --db-port ${alternative ?? '<free port>'}; compose.yaml and dokebi.yaml get the same port`,
+                            // AI-M03: the port is the user's call (dev-infra has no --defaults).
+                            ...portQuestion({
+                                what: 'Database',
+                                port,
+                                alternative,
+                                flag: '--db-port',
+                                delegated: false,
+                            }),
+                        },
+                    });
+                }
+                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'));
+            }
+            const url = connectionUrl(docker, password, port);
+            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',
+                    });
+                await tx.write(CONFIG_FILE, 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 });
+            return {
+                ...(await this.#finish(session, {
+                    changed: tx.paths,
+                    preserved: warnings.map((warning) => warning.path ?? '').filter(Boolean),
+                    ...(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 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)',
+                        },
+                    ],
+                }, options.dryRun)),
+                service: {
+                    name: DB_SERVICE,
+                    variant: variant.name,
+                    image: docker.image,
+                    port,
+                    url: redactUrl(url),
+                    compose: COMPOSE_FILE,
+                    passwordIn: ENV_FILE,
+                },
+            };
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /**
+     * `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.
+     */
+    async configSecret(root, id, path, dryRun = false) {
+        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) },
+                    phase: 'arguments',
+                });
+            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)
+                return {
+                    ...(await this.#finish(session, { changed: [], preserved: [], warnings: [{ code: 'SECRET_KEPT', path: where }] }, dryRun)),
+                    secret: { path: where, list: Array.isArray(current), generated: false },
+                };
+            const secret = randomBytes(32).toString('base64url');
+            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;
+                }
+            }
+            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 });
+            return {
+                ...(await this.#finish(session, { changed: tx.paths, preserved: [] }, dryRun)),
+                secret: { path: where, list, generated: true },
+            };
+        }
+        finally {
+            await tx.close();
+        }
+    }
     async coreVersion(root) {
         const pkg = parseObject(await readFile(await packageFile(root, '@dokebi/core', 'package.json'), 'utf8'), 'core');
         if (pkg.name !== '@dokebi/core' ||
@@ -511,6 +1214,8 @@ export class Project {
         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) {
             await writeFile(join(staging, 'package.json'), json({ ...pkg, dependencies }));
             const lock = await securePath(tx.root, 'package-lock.json');
@@ -627,7 +1332,11 @@ export class Project {
         const stagedRequired = await readRequiredPlugins(staging);
         if (json(stagedRequired) !== json(required))
             throw new CliError('MANIFEST_CHANGED', 'Core-required plugins changed during dependency installation');
-        return orderPlugins(plugins, await this.coreVersion(staging), stagedRequired);
+        const ordered = orderPlugins(plugins, await this.coreVersion(staging), stagedRequired);
+        // One host per role (D-0070): a second plugin that hosts apps or modules is HOST_CONFLICT.
+        for (const role of HOST_ROLES)
+            findHost(ordered, role);
+        return ordered;
     }
     #runChecks(base, ordered, config, installations, projectPackages) {
         return checkAll(ordered.map((plugin) => ({
@@ -709,37 +1418,46 @@ export class Project {
         }
     }
     #planFiles(plan) {
-        return plan.entry ? [...plan.files, plan.entry] : plan.files;
+        // The entry is the developer's code (D-0064): always user-owned.
+        return plan.entry ? [...plan.files, { ...plan.entry, owner: 'user' }] : plan.files;
     }
-    async #addFiles(tx, staging, state, plugin, files) {
+    async #addFiles(tx, staging, state, plugin, files, 
+    /** Content to write instead of a template (its template hash is still recorded). */
+    override = new Map()) {
         for (const file of files) {
             const content = await readFile(await packageFile(staging, plugin.packageName, file.source));
             const digest = hash(content);
             await tx.capture(file.target);
             const current = await fingerprint(await securePath(tx.root, file.target));
             const owned = state.files[file.target];
+            const owner = file.owner ?? 'user';
             if (owned) {
-                if (current !== digest || owned.hash !== digest)
+                // 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);
                 owned.owners.push(plugin.id);
             }
             else {
                 if (current !== null)
                     throw new CliError('FILE_CONFLICT', file.target);
-                await tx.write(file.target, content);
-                state.files[file.target] = { hash: digest, owners: [plugin.id] };
+                await tx.write(file.target, override.get(file.target) ?? content);
+                state.files[file.target] = { hash: digest, owners: [plugin.id], owner };
             }
         }
     }
     /** Applies a new template set while preserving files the user changed or deleted. */
     async #reconcileFiles(tx, staging, state, plugin, files) {
-        const planned = new Map(files.map((file) => [file.target, file.source]));
+        const planned = new Map(files.map((file) => [file.target, file]));
         const details = [];
         for (const [path, owned] of Object.entries(state.files)) {
             if (!owned.owners.includes(plugin.id))
                 continue;
-            const source = planned.get(path);
+            const template = planned.get(path);
+            const source = template?.source;
             planned.delete(path);
+            // The new version decides who edits the file (a single owner only: shared stays as is).
+            if (template && owned.owners.length === 1)
+                owned.owner = template.owner ?? 'user';
             await tx.capture(path);
             const current = await fingerprint(await securePath(tx.root, path));
             const update = source === undefined ? undefined : 'node_modules/' + plugin.packageName + '/' + source;
@@ -773,7 +1491,7 @@ export class Project {
                 owned.hash = digest;
             }
         }
-        await this.#addFiles(tx, staging, state, plugin, [...planned].map(([target, source]) => ({ source, target })));
+        await this.#addFiles(tx, staging, state, plugin, [...planned.values()]);
         return details;
     }
     async #syncExample(tx, root, id, warnings, update) {
@@ -888,33 +1606,41 @@ export class Project {
         return result;
     }
     /**
-     * `dokebi app add <name>`: copies the app skeleton of @dokebi/app to src/apps/<name>, maps the
-     * given domains to it in dokebi.yaml and registers it in the generated code (D-0030 §7).
+     * `dokebi app add <name>`: copies the app skeleton of the apps host (D-0070) to src/apps/<name>,
+     * maps the given domains to it in dokebi.yaml and registers it in the generated code (D-0030 §7).
      */
     async appAdd(root, name, options = {}) {
         const session = await this.#begin(root);
         const { tx, state } = session;
         try {
-            this.#requireAppPlugin(state);
-            const added = await this.#addApp(tx, session.root, state, session.configSource, name, options);
+            const host = await this.#requireHost(state, 'apps');
+            const added = await this.#addApp(tx, session.root, host, state, session.configSource, name, options);
             const warnings = [];
-            if (options.inertia &&
-                !state.plugins.some((plugin) => plugin.id === 'dokebi-template-inertia'))
+            if (options.inertia && !(await this.#providesInstalled(state, 'view.inertia')))
                 warnings.push({ code: 'INERTIA_PLUGIN_MISSING', path: `src/apps/${name}` });
             if (options.ssr && !options.inertia)
                 throw new CliError('USAGE', 'Server rendering (--ssr) needs --inertia');
             if (options.inertia)
-                await this.#inertiaBuild(tx, session, warnings, options.ssr === true);
+                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: 'dokebi-app', update: { changes: added.changes } },
+                { id: host.id, update: { changes: added.changes } },
             ]);
             await this.writeConfiguration(tx, state, parseAndRender(added.configSource));
             const result = {
                 changed: tx.paths,
                 preserved: [],
                 ...(warnings.length ? { warnings } : {}),
-                ...(options.inertia ? { nextSteps: ['npm run build'] } : {}),
+                ...(options.inertia
+                    ? {
+                        nextSteps: [
+                            {
+                                command: 'npm run build',
+                                why: 'build the Vue pages with Vite (dist/); `npx dokebi dev` serves them with hot reload instead',
+                            },
+                        ],
+                    }
+                    : {}),
             };
             return await this.#finish(session, result, options.dryRun);
         }
@@ -927,7 +1653,7 @@ export class Project {
         const session = await this.#begin(root);
         const { tx, state } = session;
         try {
-            this.#requireAppPlugin(state);
+            const host = await this.#requireHost(state, 'apps');
             if (!(state.apps ?? []).includes(name))
                 throw new CliError('UNKNOWN_APP', name);
             const template = options.template ?? 'default';
@@ -935,7 +1661,7 @@ export class Project {
                 throw new CliError('INVALID_APP', 'Template names match ' + APP_NAME.source);
             if (!HOST.test(domain) || domain.length > 253)
                 throw new CliError('INVALID_APP', 'Domains are lower-case host names without a port');
-            const current = domainTarget(parseProjectConfig(session.configSource).options, domain);
+            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 } });
             const views = `src/apps/${name}/views/${template}`;
@@ -943,10 +1669,8 @@ export class Project {
                 await tx.ensureDirectory(views);
             const changes = domainChanges([domain], template === 'default' ? { app: name } : { app: name, template });
             const warnings = [];
-            await this.#syncExamples(tx, session.root, warnings, [
-                { id: 'dokebi-app', update: { changes } },
-            ]);
-            await tx.write(CONFIG_FILE, applyConfigChanges(session.configSource, 'dokebi-app', changes));
+            await this.#syncExamples(tx, session.root, warnings, [{ id: host.id, update: { changes } }]);
+            await tx.write(CONFIG_FILE, applyConfigChanges(session.configSource, host.id, changes));
             const result = {
                 changed: tx.paths,
                 preserved: [],
@@ -963,15 +1687,13 @@ export class Project {
         const session = await this.#begin(root);
         const { tx, state } = session;
         try {
-            this.#requireAppPlugin(state);
-            if (!domainTarget(parseProjectConfig(session.configSource).options, domain))
+            const host = await this.#requireHost(state, 'apps');
+            if (!domainTarget(parseProjectConfig(session.configSource).options, host.id, domain))
                 throw new CliError('UNKNOWN_DOMAIN', domain);
             const changes = [{ op: 'remove', path: ['domains', domain] }];
             const warnings = [];
-            await this.#syncExamples(tx, session.root, warnings, [
-                { id: 'dokebi-app', update: { changes } },
-            ]);
-            await tx.write(CONFIG_FILE, applyConfigChanges(session.configSource, 'dokebi-app', changes));
+            await this.#syncExamples(tx, session.root, warnings, [{ id: host.id, update: { changes } }]);
+            await tx.write(CONFIG_FILE, applyConfigChanges(session.configSource, host.id, changes));
             const result = {
                 changed: tx.paths,
                 preserved: [],
@@ -988,23 +1710,23 @@ export class Project {
         const session = await this.#begin(root);
         const { tx, state } = session;
         try {
-            this.#requireAppPlugin(state);
+            const host = await this.#requireHost(state, 'apps');
             if (!(state.apps ?? []).includes(name))
                 throw new CliError('UNKNOWN_APP', name);
-            const domains = appDomains(parseProjectConfig(session.configSource).options, name);
+            const domains = appDomains(parseProjectConfig(session.configSource).options, host.id, name);
             if (domains.length)
                 throw new CliError('APP_IN_USE', name, { details: { app: name, domains } });
             state.apps = (state.apps ?? []).filter((app) => app !== name);
             if (!state.apps.length)
                 delete state.apps;
-            // Its `apps.<name>` settings (D-0061) go too: dokebi-app refuses an entry for an app that
+            // Its `apps.<name>` settings (D-0061) go too: the host refuses an entry for an app that
             // is not defined (UNKNOWN_APP). The sample keeps the same shape when it has the entry.
             const warnings = [];
             if (await exists(await securePath(session.root, EXAMPLE))) {
                 const example = await tx.read(EXAMPLE);
                 let next = example;
                 try {
-                    next = removeAppSettings(example, name);
+                    next = removeAppSettings(example, host.id, name);
                 }
                 catch (error) {
                     if (!(error instanceof CliError))
@@ -1014,7 +1736,7 @@ export class Project {
                 if (next !== example)
                     await tx.write(EXAMPLE, next);
             }
-            await this.writeConfiguration(tx, state, removeAppSettings(session.configSource, name));
+            await this.writeConfiguration(tx, state, removeAppSettings(session.configSource, host.id, name));
             const result = {
                 changed: tx.paths,
                 preserved: [`src/apps/${name}`],
@@ -1030,12 +1752,16 @@ export class Project {
     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 host = findHost(state.plugins, 'apps');
         return {
-            apps: (state.apps ?? []).map((name) => ({ name, domains: appDomains(config, name) })),
+            apps: (state.apps ?? []).map((name) => ({
+                name,
+                domains: host ? appDomains(config, host.id, name) : [],
+            })),
         };
     }
     /**
-     * `dokebi module add <name>` (D-0032): copies the module skeleton of @dokebi/module to
+     * `dokebi module add <name>` (D-0032): copies the module skeleton of the modules host to
      * src/shared/modules/<name> and registers it in the generated code. `views: false` copies the
      * skeleton without views (routes answer JSON).
      */
@@ -1043,8 +1769,7 @@ export class Project {
         const session = await this.#begin(root);
         const { tx, state } = session;
         try {
-            if (!state.plugins.some((plugin) => plugin.id === 'dokebi-module'))
-                throw new CliError('MODULE_PLUGIN_MISSING', 'Run dokebi add @dokebi/module first');
+            const host = await this.#requireHost(state, 'modules');
             if (!APP_NAME.test(name))
                 throw new CliError('INVALID_MODULE', 'Module names match ' + APP_NAME.source);
             if ((state.modules ?? []).includes(name))
@@ -1054,9 +1779,9 @@ export class Project {
             if (await exists(await securePath(tx.root, folder)))
                 throw new CliError('FILE_CONFLICT', folder);
             const skeleton = options.views === false ? 'module-api' : 'module';
-            const source = await packageFile(session.root, '@dokebi/module', `templates/${skeleton}`);
+            const source = await packageFile(session.root, host.packageName, `templates/${skeleton}`);
             if (!(await exists(source)))
-                throw new CliError('INVALID_MANIFEST', 'Upgrade @dokebi/module (no module skeleton)');
+                throw new CliError('INVALID_MANIFEST', `Upgrade ${host.packageName} (no module skeleton templates/${skeleton})`);
             for (const file of await listFiles(source)) {
                 const target = `${folder}/${file}`;
                 templateTarget(target);
@@ -1071,7 +1796,10 @@ export class Project {
                 changed: tx.paths,
                 preserved: [],
                 nextSteps: [
-                    `mount it in an app: modules: { '/${name}': <import of src/shared/modules/${name}/module.ts> }`,
+                    {
+                        command: `edit src/apps/<app>/app.ts: import ${camel(name)} from '../../shared/modules/${name}/module.ts' and add modules: { '/${name}': ${camel(name)} }`,
+                        why: "a module answers only where an app mounts it, under that prefix and on that app's domains",
+                    },
                 ],
             };
             return await this.#finish(session, result, options.dryRun);
@@ -1117,8 +1845,8 @@ export class Project {
      * 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.
      */
-    async #inertiaBuild(tx, session, warnings, ssr) {
-        const source = await packageFile(session.root, '@dokebi/app', 'templates/inertia-build');
+    async #inertiaBuild(tx, session, host, warnings, ssr) {
+        const source = await packageFile(session.root, host.packageName, 'templates/inertia-build');
         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');
@@ -1170,12 +1898,29 @@ export class Project {
         if (!ignore.split(/\r?\n/).some((line) => ['dist', 'dist/', '/dist', '/dist/'].includes(line)))
             await tx.write('.gitignore', `${ignore}${ignore && !ignore.endsWith('\n') ? '\n' : ''}dist/\n`);
     }
-    #requireAppPlugin(state) {
-        if (!state.plugins.some((plugin) => plugin.id === 'dokebi-app'))
-            throw new CliError('APP_PLUGIN_MISSING', 'Run dokebi add @dokebi/app first');
+    /**
+     * The installed plugin that hosts `role` (D-0070). None is APP_PLUGIN_MISSING /
+     * MODULE_PLUGIN_MISSING, whose fix names the catalog plugin that provides the role.
+     */
+    async #requireHost(state, role) {
+        const host = findHost(state.plugins, role);
+        if (host) {
+            debug('Host plugin found', { role, plugin: host.id, package: host.packageName });
+            return host;
+        }
+        const capability = HOST_CAPABILITY[role];
+        const suggested = providersOf(await loadCatalog(), capability).find((item) => item.kind === 'plugin')?.package;
+        throw new CliError(role === 'apps' ? 'APP_PLUGIN_MISSING' : 'MODULE_PLUGIN_MISSING', `No installed plugin hosts ${role}; run dokebi add ${suggested ?? `<a plugin that provides ${capability}>`} first`, { details: { role, capability, ...(suggested ? { package: suggested } : {}) } });
     }
-    /** Shared by `app add` and the first app created with `dokebi add @dokebi/app`. */
-    async #addApp(tx, packagesRoot, state, configSource, name, options) {
+    /** Whether an installed plugin provides a catalog capability starting with `prefix`. */
+    async #providesInstalled(state, prefix) {
+        const catalog = await loadCatalog();
+        const installed = new Set(state.plugins.map((plugin) => plugin.packageName));
+        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) {
         if (!APP_NAME.test(name))
             throw new CliError('INVALID_APP', 'App names match ' + APP_NAME.source);
         const template = options.template ?? 'default';
@@ -1192,7 +1937,7 @@ export class Project {
         for (const domain of domains) {
             if (!HOST.test(domain) || domain.length > 253)
                 throw new CliError('INVALID_APP', 'Domains are lower-case host names without a port');
-            const current = domainTarget(config, domain);
+            const current = domainTarget(config, host.id, domain);
             if (current && current !== name)
                 throw new CliError('DOMAIN_IN_USE', domain, { details: { domain, app: current } });
         }
@@ -1206,7 +1951,7 @@ export class Project {
             : ['app'];
         const files = new Map();
         for (const skeleton of skeletons) {
-            const source = await packageFile(packagesRoot, '@dokebi/app', `templates/${skeleton}`);
+            const source = await packageFile(packagesRoot, host.packageName, `templates/${skeleton}`);
             for (const file of await listFiles(source))
                 files.set(file, join(source, file));
         }
@@ -1220,7 +1965,7 @@ export class Project {
         }
         const changes = domainChanges(domains, template === 'default' ? { app: name } : { app: name, template });
         state.apps = [...(state.apps ?? []), name];
-        return { configSource: applyConfigChanges(configSource, 'dokebi-app', changes), changes };
+        return { configSource: applyConfigChanges(configSource, host.id, changes), changes };
     }
     async writeConfiguration(tx, state, configSource) {
         const generated = generateRegistration(state.plugins, state.installations, state.apps ?? [], state.modules ?? []);
@@ -1231,20 +1976,21 @@ export class Project {
     }
 }
 const HOST = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;
-function domainsOf(options) {
-    const section = options['dokebi-app'];
+/** `options.<apps host>.domains` (D-0030): domain → { app, template? }. */
+function domainsOf(options, host) {
+    const section = options[host];
     const domains = section && typeof section === 'object'
         ? section.domains
         : undefined;
     return domains && typeof domains === 'object' ? domains : {};
 }
-function domainTarget(options, domain) {
-    const target = domainsOf(options)[domain];
+function domainTarget(options, host, domain) {
+    const target = domainsOf(options, host)[domain];
     const app = target && typeof target === 'object' ? target.app : undefined;
     return typeof app === 'string' ? app : undefined;
 }
-function appDomains(options, name) {
-    return Object.entries(domainsOf(options))
+function appDomains(options, host, name) {
+    return Object.entries(domainsOf(options, host))
         .filter(([, target]) => target?.app === name)
         .map(([domain, target]) => ({
         domain,
@@ -1286,3 +2032,7 @@ async function readOptional(path) {
         throw error;
     }
 }
+/** `board-items` → `boardItems`: a module's default import name. */
+function camel(name) {
+    return name.replace(/-([a-z0-9])/g, (_match, letter) => letter.toUpperCase());
+}