@dokebi/cli 0.4.2 → 0.4.27

package/dist/commands.js

@@ -5,12 +5,12 @@
 export const COMMANDS = [
     {
         name: 'guide',
-        usage: 'dokebi guide [--json]',
+        usage: 'dokebi guide [--sync [--dry-run]] [--json]',
         summary: 'AI first page: how to turn a one-line request into an app (ask, install, verify) — read this first',
     },
     {
         name: 'init',
-        usage: 'dokebi init <directory> [--core <package|local.tgz>] [--dry-run] [--json]',
+        usage: 'dokebi init <directory> [--core <package|local.tgz>] [--deploy] [--dry-run] [--json]',
         summary: 'Create a project (new folder, or an empty one such as .) with core, config, this CLI (@dokebi/cli) and TypeScript; prints next steps',
     },
     {
@@ -20,7 +20,7 @@ export const COMMANDS = [
     },
     {
         name: 'recipe',
-        usage: 'dokebi recipe <name> [--dir <directory>] [--view <v>] [--db <d>] [--dev-infra <i>] [--admin <a>] [--port <n>] [--db-port <n>] [--answers-from <user|defaults>] [--defaults] [--dry-run] [--json]',
+        usage: 'dokebi recipe <name> [--dir <directory>] [--view <v>] [--db <d>] [--dev-infra <i>] [--admin <a>] [--mail <m>] [--apps <list>] [--domains <map>] [--realms <map>] [--worker <kind>] [--port <n>] [--db-port <n>] [--answers-from <user|defaults>] [--ai-chose <ids>] [--ai-reason <id=why>] [--defaults] [--dry-run] [--json]',
         summary: "Without every answer: the questions to ask the user, then end your turn (installs nothing); with the user's answers: plan, then apply with --answers-from user",
     },
     {
@@ -45,7 +45,7 @@ export const COMMANDS = [
     },
     {
         name: 'add',
-        usage: 'dokebi add <package|local.tgz> [--set <path>=<value>]... [--adapter <pg|mysql2|mariadb|mongodb>] [--no-first-app] [--dry-run] [--json]',
+        usage: 'dokebi add <package|local.tgz> [--set <path>=<value>]... [--adapter <pg|mysql2|mariadb|mongodb>] [--startup <required|optional>] [--no-first-app] [--dry-run] [--json]',
         summary: 'Install and register a plugin (and the plugins it requires); no version picks the newest one for this core',
     },
     {
@@ -58,20 +58,55 @@ export const COMMANDS = [
         usage: 'dokebi remove <plugin-id> [--dry-run] [--json]',
         summary: 'Unregister and uninstall a plugin; user options are kept and marked',
     },
+    {
+        name: 'config show',
+        usage: 'dokebi config show [<plugin-id>[.<path>]] [--json]',
+        summary: 'Print the options of dokebi.yaml (with schema defaults) with every secret hidden, for output you share',
+    },
+    {
+        name: 'config diff',
+        usage: 'dokebi config diff [<plugin-id>] [--write [--values] [--prune] [--dry-run]] [--json]',
+        summary: 'Name the options dokebi.yaml and dokebi.example.yaml do not share, by path only (values are never shown); --write copies the ones only in dokebi.yaml into the sample without secrets; never dump or hand-edit the two files',
+    },
     {
         name: 'config set',
         usage: 'dokebi config set <plugin-id>.<path>=<value>... [--dry-run] [--json]',
-        summary: 'Set non-secret options in dokebi.yaml (checked against the plugin schema)',
+        summary: 'Set non-secret options in dokebi.yaml (checked against the plugin schema); logging.<path> sets options.logging',
+    },
+    {
+        name: 'config unset',
+        usage: 'dokebi config unset <plugin-id>[.<path>]... [--dry-run] [--json]',
+        summary: 'Remove options from dokebi.yaml (and dokebi.example.yaml where it has them), e.g. a key the plugin no longer knows; never prints values',
+    },
+    {
+        name: 'config init',
+        usage: 'dokebi config init [--dry-run] [--json]',
+        summary: 'Write dokebi.yaml for a fresh copy of the project (a clone) from dokebi.example.yaml, with new generated secrets; never replaces an existing one',
     },
     {
         name: 'config secret',
-        usage: 'dokebi config secret <plugin-id>.<path> [--dry-run] [--json]',
-        summary: 'Write a generated secret (never shown) into dokebi.yaml, e.g. dokebi-session.secrets',
+        usage: 'dokebi config secret <plugin-id>.<path> [--stdin] [--rotate] [--dry-run] [--json]',
+        summary: 'Write a generated secret (never shown) into dokebi.yaml, e.g. dokebi-session.secrets, or with --stdin one you were given, e.g. logging.targets.studio.token; --rotate replaces one',
+    },
+    {
+        name: 'config secrets',
+        usage: 'dokebi config secrets [--json]',
+        summary: 'The secret option paths the app needs, by name (never values): set in dokebi.yaml or in the DOKEBI_SECRETS file, or missing; exit 1 when one is missing',
+    },
+    {
+        name: 'deploy init',
+        usage: 'dokebi deploy init [--target <systemd|compose>] [--instance <name>]... [--port <n>] [--dry-run] [--json]',
+        summary: 'Write deploy/ for an existing project: a systemd unit or a compose file per instance (staging and production on one server never share a port, unit, settings, data, log or database name), a settings sample without secrets, a secrets sample, backup scripts and DEPLOY.md',
+    },
+    {
+        name: 'deploy proxy',
+        usage: 'dokebi deploy proxy --caddy|--nginx --domain <host>... [--instance <name>] [--dry-run] [--json]',
+        summary: 'Write the reverse proxy configuration of an instance (TLS, forwarded headers, WebSocket upgrade, unbuffered SSE, /health/*, static caching) from its settings sample',
     },
     {
         name: 'dev-infra',
-        usage: 'dokebi dev-infra [--db-port <n>] [--dry-run] [--json]',
-        summary: 'Write compose.yaml, .env (generated password) and the dokebi.yaml address of the development database',
+        usage: 'dokebi dev-infra [up|start|stop|down|status] [--file <path>] [--db-port <n>] [--dry-run] [--json]',
+        summary: 'Prepare a database with YAML-only credentials, or manage development Compose services',
     },
     {
         name: 'migrate',
@@ -85,23 +120,38 @@ export const COMMANDS = [
     },
     {
         name: 'doctor',
-        usage: 'dokebi doctor [--verbose] [--json]',
-        summary: 'Run all checks; exit 1 on an error diagnostic (repairs nothing)',
+        usage: 'dokebi doctor [--production] [--verbose] [--json]',
+        summary: 'Run all checks; exit 1 on an error diagnostic (repairs nothing); --production adds the checks of a server: NODE_ENV, state every process shares, trustProxy, secrets, migrations',
     },
     {
         name: 'check',
         usage: 'dokebi check [--json]',
         summary: 'User-code conventions: empty catch, floating promises, syntax Node cannot strip, private or missing @dokebi imports, edited generated files, committable secrets',
     },
+    {
+        name: 'mail preview',
+        usage: 'dokebi mail preview <name> [--locale <locale>] [--json]',
+        summary: 'Render a mail template with preview.json in describe mode, without sending or connecting.',
+    },
+    {
+        name: 'describe',
+        usage: 'dokebi describe [--with-db] [--openapi [--app <name>]] [--timeout-ms <ms>] [--json]',
+        summary: 'What the app has, without serving: routes (auth, csrf), pages, jobs, schedules, error codes, option keys and env names (never values); --with-db adds the tables; --openapi: OpenAPI 3.1 per app',
+    },
+    {
+        name: 'drift',
+        usage: 'dokebi drift --expected <file> [--timeout-ms <ms>] [--json]',
+        summary: 'Compare the databases (connections, tables, collections, columns, column comments) with an expected file of the describe shape; it connects like describe --with-db; exit 1 on a difference',
+    },
     {
         name: 'verify',
-        usage: 'dokebi verify [--wait-ms <ms>] [--json]',
-        summary: 'doctor, check, typecheck, build, start, HTTP checks and stop; ok only when all pass (say done only then)',
+        usage: 'dokebi verify [--wait-ms <ms>] [--test-timeout-ms <ms>] [--remote <https-url> [--timeout-ms <ms>]] [--json]',
+        summary: 'doctor, check, typecheck, build, test, start, HTTP checks and stop; ok only when all pass (say done only then); --remote checks a deployed site instead: TLS, redirect, health, security headers',
     },
     {
         name: 'app add',
-        usage: 'dokebi app add <name> [--domain <host>]... [--template <name>] [--inertia [--ssr]] [--dry-run] [--json]',
-        summary: 'Create the app src/apps/<name> (EJS, or Vue with --inertia) and map its domains',
+        usage: 'dokebi app add <name> [--domain <host>]... [--template <name>] [--inertia [--ssr]] [--view <ejs|none>] [--seal] [--answers-from <user|defaults>] [--ai-chose view] [--ai-reason view=<why>] [--dry-run] [--json]',
+        summary: 'Create the app src/apps/<name> (EJS, or Vue with --inertia: the default view) and map its domains; records who chose its view',
     },
     {
         name: 'app remove',
@@ -110,7 +160,7 @@ export const COMMANDS = [
     },
     {
         name: 'app link',
-        usage: 'dokebi app link <name> <domain> [--template <name>] [--dry-run] [--json]',
+        usage: 'dokebi app link <name> <domain> [--template <name>] [--seal] [--dry-run] [--json]',
         summary: 'Serve an app on one more domain, optionally with another template',
     },
     {
@@ -130,10 +180,30 @@ export const COMMANDS = [
         summary: 'Unregister a feature module; its folder is kept',
     },
     { name: 'module list', usage: 'dokebi module list [--json]', summary: 'List feature modules' },
+    {
+        name: 'settings add',
+        usage: 'dokebi settings add <section> [--dry-run] [--json]',
+        summary: 'Declare the settings of the application in options.<section> (src/shared/settings/<section>.ts): checked at start, known to config and doctor, reloadable options apply live',
+    },
+    {
+        name: 'settings sync',
+        usage: 'dokebi settings sync [--dry-run] [--json]',
+        summary: 'Write the schema of every settings section again from its declaration and add new defaults to dokebi.yaml',
+    },
+    {
+        name: 'settings remove',
+        usage: 'dokebi settings remove <section> [--dry-run] [--json]',
+        summary: 'Unregister a settings section; its files and options are kept',
+    },
+    {
+        name: 'settings list',
+        usage: 'dokebi settings list [--json]',
+        summary: 'List the settings sections of the application',
+    },
     {
         name: 'dev',
         usage: 'dokebi dev',
-        summary: 'Run the app in the foreground and restart it when src or dokebi.yaml change',
+        summary: 'Run the app in the foreground; restart it when src changes, reload dokebi.yaml in place when every changed option is reloadable',
     },
     {
         name: 'start',
@@ -145,6 +215,11 @@ export const COMMANDS = [
         usage: 'dokebi stop [--timeout-ms <ms>] [--force] [--json]',
         summary: 'Stop the background app (SIGTERM drain; SIGKILL with --force after the timeout)',
     },
+    {
+        name: 'reload',
+        usage: 'dokebi reload [--timeout-ms <ms>] [--json]',
+        summary: 'Make the background app read dokebi.yaml again (SIGHUP); options marked reloadable apply without a restart, others are refused with RELOAD_RESTART_REQUIRED',
+    },
     {
         name: 'status',
         usage: 'dokebi status [--json]',
@@ -163,14 +238,41 @@ export function commandHasFlag(command, flag) {
         return false;
     return new RegExp(`(^|[\\s\\[|])${flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=[\\s\\]|]|$)`).test(usage);
 }
+/**
+ * The commands whose usage line takes --dry-run, in table order (AI-M04 F8: `--help` said only
+ * "changing commands", and an agent tried `start --dry-run`). Derived, so it cannot drift.
+ */
+export const DRY_RUN_COMMANDS = COMMANDS.filter((item) => commandHasFlag(item.name, '--dry-run')).map((item) => item.name);
+/** DRY_RUN_COMMANDS on one line, subcommands grouped: `app add/remove/link/unlink`. */
+export function dryRunList() {
+    const groups = new Map();
+    for (const name of DRY_RUN_COMMANDS) {
+        const [head = name, sub] = name.split(' ');
+        const subs = groups.get(head) ?? [];
+        if (sub)
+            subs.push(sub);
+        groups.set(head, subs);
+    }
+    return [...groups]
+        .map(([head, subs]) => (subs.length ? `${head} ${subs.join('/')}` : head))
+        .join(', ');
+}
 /** `dokebi <command> --help`: what each flag does, and one example (D-0065, AI-M01). */
 export const COMMAND_DETAILS = {
     guide: {
-        flags: [['--json', 'the guide as data: steps, rules, recipes, absent, commands']],
+        flags: [
+            ['--json', 'the guide as data: steps, rules, recipes, absent, commands'],
+            ['--sync', 'Refresh maintained AGENTS.md blocks, preserving project instructions'],
+            ['--dry-run', 'Preview --sync without writing files'],
+        ],
         example: 'npx dokebi guide --json',
     },
     init: {
         flags: [
+            [
+                '--deploy',
+                'also create Dockerfile, .dockerignore, compose.deploy.yaml and DEPLOY.md; does not start or publish anything',
+            ],
             ['--core <package|local.tgz>', 'core to install (default: @dokebi/core in this CLI range)'],
             [
                 '<directory>',
@@ -178,7 +280,7 @@ export const COMMAND_DETAILS = {
             ],
             ['--dry-run', 'check the folder and print the next steps; nothing is installed or written'],
         ],
-        example: 'npx -y @dokebi/cli init my-blog && cd my-blog && npx dokebi guide --json\nnpx -y @dokebi/cli init . --json   # in an empty work folder',
+        example: 'npx -y @dokebi/cli init my-app && cd my-app && npx dokebi guide --json\nnpx -y @dokebi/cli init . --json   # in an empty work folder',
     },
     'recipe list': { flags: [], example: 'npx dokebi recipe list --json' },
     recipe: {
@@ -187,13 +289,33 @@ export const COMMAND_DETAILS = {
                 '--dir <directory>',
                 'project folder; a new folder is created with init first (default: current project)',
             ],
+            ['--apps <list>', 'site: comma-separated web,admin,api in that order, or none'],
+            [
+                '--domains <map>',
+                'site: app=host pairs separated by commas, or auto for <app>.<project>.localhost',
+            ],
+            [
+                '--realms <map>',
+                'site: app=realm pairs separated by commas, or auto for separate app realms',
+            ],
+            [
+                '--worker <kind>',
+                'site: none | thread (CPU pool) | job (NATS queue; configure before starting)',
+            ],
             ['--view <v>', 'blog: ejs | inertia-vue | inertia-vue-ssr (inertia-react is absent)'],
             ['--db <d>', 'postgres | mysql | mariadb | mongodb | none (sqlite is absent)'],
             [
                 '--dev-infra <i>',
                 'docker (compose.yaml, generated password) | url (you write the URL); only with a database',
             ],
-            ['--admin <a>', 'blog: none | app-code (no auth plugin: the app writes the login)'],
+            [
+                '--admin <a>',
+                'blog: none | login (@dokebi/auth, needs a database) | app-code (an admin app whose login you write)',
+            ],
+            [
+                '--mail <m>',
+                'none | mailpit (local Docker inbox and queue) | smtp | ses (existing configuration)',
+            ],
             ['--port <n>', 'web port (default 3000)'],
             [
                 '--db-port <n>',
@@ -201,7 +323,15 @@ export const COMMAND_DETAILS = {
             ],
             [
                 '--answers-from <user|defaults>',
-                'where the answers came from; applying needs it. user: the user answered these questions (ask, end your turn, wait). defaults: the user said to decide (same as --defaults). Recorded in `answersFrom` and `report`',
+                'where the answers came from; applying needs it. user: the given flags are choices the user or the request explicitly made (ask, end your turn, wait), except those in --ai-chose. defaults: the user said to decide everything (same as --defaults). Recorded per answer (`answeredBy`) and in `report`',
+            ],
+            [
+                '--ai-chose <ids>',
+                'comma-separated question ids of the given flags you chose yourself because the user left them to you (D-0095); recorded as `answeredBy: ai`. Never for a choice the user made',
+            ],
+            [
+                '--ai-reason <id=why>',
+                'repeatable: one line (at most 200 characters) why you chose an --ai-chose answer; the user reads it in `report` and verify `tellUser`',
             ],
             [
                 '--defaults',
@@ -209,7 +339,7 @@ export const COMMAND_DETAILS = {
             ],
             ['--dry-run', 'plan and preflight only; nothing is written'],
         ],
-        example: 'npx dokebi recipe blog --json   # the questions (exit 2, nothing installed): ask them and end your turn\nnpx dokebi recipe blog --view ejs --db postgres --dev-infra docker --admin none --answers-from user --dry-run --json',
+        example: 'npx dokebi recipe blog --json   # the questions (exit 2, nothing installed): ask them and end your turn\nnpx dokebi recipe blog --view ejs --db postgres --dev-infra docker --admin none --mail none --answers-from user --dry-run --json',
     },
     'plugins list': {
         flags: [
@@ -223,7 +353,7 @@ export const COMMAND_DETAILS = {
     },
     'plugins search': {
         flags: [],
-        example: 'npx dokebi plugins search login --json   # status: absent (auth)',
+        example: 'npx dokebi plugins search upload --json   # @dokebi/storage',
     },
     'plugins info': { flags: [], example: 'npx dokebi plugins info db --json' },
     'plugins doc': { flags: [], example: 'npx dokebi plugins doc dokebi-db --json' },
@@ -241,6 +371,10 @@ export const COMMAND_DETAILS = {
                 '--adapter <id>',
                 '@dokebi/db: pg | mysql2 | mariadb | mongodb (adapter file, connection main, driver, @types/pg)',
             ],
+            [
+                '--startup <required|optional>',
+                '@dokebi/db with --adapter: connections.main.startup (optional: the app starts and runs while that database is down; written only when given)',
+            ],
             [
                 '--no-first-app',
                 '@dokebi/app: do not create the EJS app main (add the first app with app add)',
@@ -260,29 +394,146 @@ export const COMMAND_DETAILS = {
         flags: [['--dry-run', 'plan only']],
         example: 'npx dokebi remove dokebi-health --dry-run --json',
     },
+    'config show': {
+        flags: [
+            [
+                '<id>[.<path>]',
+                'one section or value (default: every section); a value that is not set and has no default is UNKNOWN_OPTION',
+            ],
+            [
+                '--json',
+                '{ value, defaults, secrets }: secrets (schema writeOnly, keys named like secret/password/token/key, a URL password) show as <secret: set>; never a value',
+            ],
+        ],
+        example: 'npx dokebi config show dokebi-web --json\nnpx dokebi config show dokebi-web.port',
+    },
+    'config diff': {
+        flags: [
+            ['<plugin-id>', 'one section (default: every section)'],
+            [
+                '--json',
+                '{ inSync, onlyInConfig, onlyInExample, different, secrets, exampleSecrets }: option paths only; secrets are never compared, and a secret with a value in the sample is listed in exampleSecrets',
+            ],
+            [
+                '--write',
+                'copy the options only in dokebi.yaml into dokebi.example.yaml (comments kept): secrets inside them are left out, a list holding a secret is left out whole, values both files set stay as the sample has them; the result adds { written, diff } (diff: the comparison after the copy)',
+            ],
+            [
+                '--values',
+                'with --write: also write the value dokebi.yaml has into dokebi.example.yaml for every path both set to different non-secret values (the paths of different); secrets are never compared, so never copied; the result adds { valuesWritten }',
+            ],
+            [
+                '--prune',
+                'with --write: also remove from dokebi.example.yaml what only it has (an old section such as dokebi-logger, an option the plugin no longer has) and any secret with a value in it; dokebi.yaml is never changed; the result adds { pruned }',
+            ],
+            ['--dry-run', 'with --write: what would be copied or removed, nothing written'],
+        ],
+        example: 'npx dokebi config diff --json\nnpx dokebi config diff dokebi-web\nnpx dokebi config diff --write --json\nnpx dokebi config diff --write --values --json',
+    },
     'config set': {
         flags: [
-            ['<id>.<path>=<value>', 'JSON when it parses, else text; checked against the plugin schema'],
+            [
+                '<id>.<path>=<value>',
+                'JSON when it parses, else text; checked against the plugin schema. logging.<path> is options.logging (the @dokebi/logger options; without it level and plugins.<plugin> only); a list item is named by its name (else its type) or its index, as in logging.targets.file.enabled=true',
+            ],
             ['--dry-run', 'plan only'],
         ],
-        example: 'npx dokebi config set dokebi-web.port=3000 --json',
+        example: 'npx dokebi config set dokebi-web.port=3000 --json\nnpx dokebi config set logging.level=debug logging.targets.file.enabled=true --json',
+    },
+    'config unset': {
+        flags: [
+            [
+                '<id>.<path>',
+                'removes it (and mappings left empty) from dokebi.yaml and dokebi.example.yaml; a path that is not set is OPTION_NOT_SET (a warning); a secret is removed with SECRET_REMOVED; values are never printed. logging.<path> is options.logging; list items by name (else type) or index. A section a file still holds as written is that section, never the plugin it names (the old options.dokebi-logger of a sample is removed as written, SECTION_NOT_READ, and options.logging stays)',
+            ],
+            [
+                '<id>',
+                'a whole section, only one no installed plugin reads (an old section left in the files); a plugin section is INVALID_SET (remove the plugin instead)',
+            ],
+            ['--dry-run', 'plan only'],
+        ],
+        example: 'npx dokebi config unset dokebi-web.files --json\nnpx dokebi config unset dokebi-web.files --dry-run --json\nnpx dokebi config unset dokebi-logger --json',
+    },
+    'config init': {
+        flags: [
+            [
+                '--dry-run',
+                'plan only: the result names the secrets it would generate (never their values) and the placeholders left to fill',
+            ],
+        ],
+        example: 'npx dokebi config init --json\nnpx dokebi dev-infra --json\nnpx dokebi doctor --json',
     },
     'config secret': {
         flags: [
             [
                 '<id>.<path>',
-                'writes a random secret there (a list when the schema wants one); never printed',
+                'writes a random secret there (a list when the schema wants one); never printed; an existing value is kept (SECRET_KEPT), an empty one or a <placeholder> is filled; a URL takes only --stdin. logging.<path> is options.logging; a list item by its name (else type) or index',
+            ],
+            [
+                '--stdin',
+                'write the secret read from stdin (one line, piped, or typed without echo on a terminal) instead of a generated one: a token someone issued, such as the token of a log receiver',
+            ],
+            [
+                '--rotate',
+                'replace an existing value: a list gets the new secret first (it signs) and keeps the previous 2 after it (they still verify; older ones are dropped, SECRETS_DROPPED); a string is replaced. Restart the app afterwards',
+            ],
+            ['--dry-run', 'plan only'],
+        ],
+        example: 'npx dokebi config secret dokebi-session.secrets --json\nnpx dokebi config secret dokebi-csrf.secrets --rotate --json\nnpx dokebi config secret logging.targets.studio.token --stdin --json < studio-token.txt',
+    },
+    'config secrets': {
+        flags: [
+            [
+                '--json',
+                '{ file, secretsFile, listed, secrets[{path, source, listed, required}], missing }; source is config, secrets or null; exit 1 when missing is not empty',
+            ],
+        ],
+        example: 'npx dokebi config secrets --json\nDOKEBI_CONFIG=/etc/shop/production/dokebi.yaml DOKEBI_SECRETS=/etc/shop/production/secrets.yaml npx dokebi config secrets --json',
+    },
+    'deploy init': {
+        flags: [
+            [
+                '--target <systemd|compose>',
+                'systemd (default): a unit per instance running node src/main.ts; compose: a compose file per instance (and Dockerfile, .dockerignore when missing)',
+            ],
+            [
+                '--instance <name>',
+                'repeatable; default production. production uses port 3000, staging 3001, any other name needs --port',
+            ],
+            ['--port <n>', 'the local port of the one instance named (1024-65535)'],
+            [
+                '--dry-run',
+                'plan only: the files it would write or keep (a file you edited is kept: DEPLOY_FILE_KEPT)',
+            ],
+        ],
+        example: 'npx dokebi deploy init --instance staging --instance production --json\nnpx dokebi deploy init --target compose --instance production --json',
+    },
+    'deploy proxy': {
+        flags: [
+            ['--caddy', 'write deploy/proxy/<app>-<instance>.Caddyfile (automatic HTTPS)'],
+            [
+                '--nginx',
+                'write deploy/proxy/<app>-<instance>.nginx.conf (certificate paths of certbot; HTTP redirected to HTTPS)',
+            ],
+            ['--domain <host>', 'repeatable; the first is the main name'],
+            [
+                '--instance <name>',
+                'the instance whose deploy/<instance>/dokebi.example.yaml it reads (default production)',
             ],
             ['--dry-run', 'plan only'],
         ],
-        example: 'npx dokebi config secret dokebi-session.secrets --json',
+        example: 'npx dokebi deploy proxy --caddy --domain shop.example.com --json\nnpx dokebi deploy proxy --nginx --domain staging.shop.example.com --instance staging --json',
     },
     'dev-infra': {
         flags: [
+            [
+                '--file <path>',
+                'Compose file for an action; repeat for multiple files (default compose.yaml)',
+            ],
             ['--db-port <n>', 'host port of the database container (PORT_IN_USE names a free one)'],
             ['--dry-run', 'plan only'],
         ],
-        example: 'npx dokebi dev-infra --db-port 5433 --json && docker compose up -d --wait',
+        example: 'npx dokebi dev-infra --db-port 5433 --json && npx dokebi dev-infra up --json',
     },
     migrate: { flags: [['--dry-run', 'plan only']], example: 'npx dokebi migrate --dry-run --json' },
     inspect: {
@@ -290,8 +541,14 @@ export const COMMAND_DETAILS = {
         example: 'npx dokebi inspect --json',
     },
     doctor: {
-        flags: [['--verbose', 'the whole inspection (default: a summary; --json is always complete)']],
-        example: 'npx dokebi doctor',
+        flags: [
+            ['--verbose', 'the whole inspection (default: a summary; --json is always complete)'],
+            [
+                '--production',
+                'also the server checks, with the settings the app reads (DOKEBI_CONFIG, DOKEBI_SECRETS): NODE_ENV=production, no per-process state (memory session store, local rate limits, …), trustProxy, a fixed port, absolute storage folder, placeholders, listed secrets, pending migrations',
+            ],
+        ],
+        example: 'npx dokebi doctor\nNODE_ENV=production DOKEBI_CONFIG=/etc/shop/production/dokebi.yaml DOKEBI_SECRETS=/etc/shop/production/secrets.yaml npx dokebi doctor --production --json',
     },
     check: {
         flags: [
@@ -302,19 +559,84 @@ export const COMMAND_DETAILS = {
         ],
         example: 'npx dokebi check --json\n# a justified empty catch or background promise: // dokebi-check: allow empty-catch <reason>',
     },
+    'mail preview': {
+        flags: [
+            ['--locale <locale>', 'locale to render (falls back to the configured default)'],
+            ['--json', 'subject, html, text and resolved locale in the standard envelope'],
+        ],
+        example: 'npx dokebi mail preview welcome --locale en --json',
+    },
+    describe: {
+        flags: [
+            [
+                '--with-db',
+                'also read the tables of each dokebi-db connection with dokebi-migrate schema (this step connects); a connection it cannot read gets db.connections[].unavailable',
+            ],
+            [
+                '--timeout-ms <ms>',
+                'how long loading and describing the app may take (default 30000); DESCRIBE_TIMEOUT after it',
+            ],
+            [
+                '--openapi',
+                'one OpenAPI 3.1 document per app (operationId = route id); several apps: { apps: { <name>: document } }',
+            ],
+            ['--app <name>', 'with --openapi: only this app'],
+            [
+                '--json',
+                '{ schemaVersion, app, routes, pages, jobs, schedules, errors, config: { keys, env }, db, unavailable } (describe.schema.json); with --openapi the document(s)',
+            ],
+        ],
+        example: 'npx dokebi describe --json\nnpx dokebi describe --openapi --app main > openapi.json',
+    },
+    drift: {
+        flags: [
+            [
+                '--expected <file>',
+                'JSON of the describe shape (only db.connections is read; a describe --json envelope works): connections, then tables or collections and columns where the file lists them, and a column comment where it gives a non-empty one (whitespace normalized)',
+            ],
+            [
+                '--timeout-ms <ms>',
+                'how long loading the app and reading each database may take (default 30000)',
+            ],
+            [
+                '--json',
+                '{ ok, drift[{kind, connection, target, expected_value, code_value}], unavailable[{connection, reason}], compared, ms }; kind: connection | table | collection | column | column_comment; null means that side has none',
+            ],
+        ],
+        example: 'npx dokebi drift --expected design/describe.json --json',
+    },
     verify: {
-        flags: [['--wait-ms <ms>', 'how long start waits for the started line (default 30000)']],
-        example: 'npx dokebi verify --json',
+        flags: [
+            ['--wait-ms <ms>', 'how long start waits for the started line (default 30000)'],
+            [
+                '--test-timeout-ms <ms>',
+                'time limit of the test step, the package.json test script (default 300000)',
+            ],
+            [
+                '--remote <https-url>',
+                'check a deployed site only (nothing local runs): TLS certificate and days left, http to https redirect, live and ready health routes, security headers; exit 1 on a failed check',
+            ],
+            ['--timeout-ms <ms>', 'with --remote: the limit of each request (default 10000)'],
+        ],
+        example: 'npx dokebi verify --json\nnpx dokebi verify --remote https://shop.example.com --json',
     },
     'app add': {
         flags: [
-            ['--domain <host>', 'host name served by the app (repeatable, no port)'],
+            [
+                '--domain <host>',
+                'host name served by the app (repeatable, no port); auto: <app>.<project>.localhost',
+            ],
             ['--template <name>', 'views folder for those domains (default: default)'],
             ['--inertia', 'Vue pages with Vite (adds vite.config.ts, the build script, vite and vue)'],
             ['--ssr', 'with --inertia: server-rendered first HTML'],
+            [
+                '--view <ejs|none>',
+                'EJS pages, or no views (a JSON API); unset: none where the recipe built no screens (api), else EJS',
+            ],
+            ['--seal', 'seal those domains (domains.<host>.seal: true; needs @dokebi/seal)'],
             ['--dry-run', 'plan only'],
         ],
-        example: 'npx dokebi app add admin --domain admin.localhost --inertia --json',
+        example: 'npx dokebi app add admin --domain auto --inertia --json',
     },
     'app remove': {
         flags: [['--dry-run', 'plan only']],
@@ -323,6 +645,7 @@ export const COMMAND_DETAILS = {
     'app link': {
         flags: [
             ['--template <name>', 'views folder for this domain'],
+            ['--seal', 'seal this domain (domains.<host>.seal: true; needs @dokebi/seal)'],
             ['--dry-run', 'plan only'],
         ],
         example: 'npx dokebi app link shop sale.localhost --template sale --json',
@@ -337,13 +660,26 @@ export const COMMAND_DETAILS = {
             ['--no-views', 'routes answer JSON (no views folder)'],
             ['--dry-run', 'plan only'],
         ],
-        example: 'npx dokebi module add posts --json',
+        example: 'npx dokebi module add items --json',
     },
     'module remove': {
         flags: [['--dry-run', 'plan only']],
-        example: 'npx dokebi module remove posts --json',
+        example: 'npx dokebi module remove items --json',
     },
     'module list': { flags: [], example: 'npx dokebi module list --json' },
+    'settings add': {
+        flags: [['--dry-run', 'plan only']],
+        example: 'npx dokebi settings add survey --json',
+    },
+    'settings sync': {
+        flags: [['--dry-run', 'plan only']],
+        example: 'npx dokebi settings sync --json',
+    },
+    'settings remove': {
+        flags: [['--dry-run', 'plan only']],
+        example: 'npx dokebi settings remove survey --json',
+    },
+    'settings list': { flags: [], example: 'npx dokebi settings list --json' },
     dev: { flags: [], example: 'npx dokebi dev' },
     start: {
         flags: [
@@ -361,6 +697,15 @@ export const COMMAND_DETAILS = {
         ],
         example: 'npx dokebi stop --json',
     },
+    reload: {
+        flags: [
+            [
+                '--timeout-ms <ms>',
+                'how long to wait for the outcome in the app log (default options.reload.prepareTimeoutMs + 5000)',
+            ],
+        ],
+        example: 'npx dokebi reload --json',
+    },
     status: { flags: [], example: 'npx dokebi status --json' },
     logs: {
         flags: [