@sidebase/base-config 0.2.0 → 0.2.2

package/README.md

@@ -19,10 +19,10 @@ pnpm add -D @sidebase/base-config eslint jiti
 required because the config file is TypeScript. `prisma` and `@prisma/client` (`^6.19`)
 are optional peers, install them only if you use `/prisma`.
 
-**`jiti` is not a declared peer** -- `peerDependencies` is `eslint`, `prisma` and
-`@prisma/client`. It is in the command above because `/eslint` genuinely needs it, but
-since nothing declares it, **pnpm emits no missing-peer warning if you leave it out**.
-This README is the only thing that will tell you. See Requirements below.
+**`jiti` is not a declared peer.** `peerDependencies` is `eslint`, `prisma` and
+`@prisma/client`. It is in the command above because `/eslint` genuinely needs it. Since
+nothing declares it, pnpm emits no missing-peer warning if you leave it out. This README is
+the only thing that will tell you. See Requirements below.
 
 For the file-sync channel, see Adopting below. The CLI wires the dependency itself.
 
@@ -137,7 +137,7 @@ real CLI binary, so both resolve `@sidebase/streamctl` from the registry.
 This payload needs **streamctl >= 0.3.0**: its manifest declares `schemaVersion` 3 (the
 `fromDependency` placeholder behind the derived Prisma ARG), which a 0.2.x CLI rejects with
 `SCHEMA_UNSUPPORTED`. The root `streamctl.config.ts` location it documents arrived in
-0.2.0 — see "Config location" below.
+0.2.0. See "Config location" below.
 
 ## Typed config
 
@@ -275,7 +275,7 @@ The custom bans map to these ESLint rule IDs. Use the exact ID in an
 "Re-export" is not a figure of speech: a barrel file doing `export * from "node:process"`
 reports, as do `export { env } from "node:process"` and `export { default as p } from
 "node:process"`. The one shape that does **not** report is a bare side-effect import with
-no bindings, `import "node:process"` -- it cannot reach `env`, so there is nothing to ban.
+no bindings, `import "node:process"`. It cannot reach `env`, so there is nothing to ban.
 
 The `process.env` ban is enforced by **two** rules, and which one reports depends on the
 shape, so suppressing the wrong one fails twice over: the directive does not suppress
@@ -303,14 +303,15 @@ entirely, as does running on Deno or Bun, which import TypeScript directly.
 #### Type-aware linting prerequisite
 
 Type-aware linting is gated behind `LINT_TYPEAWARE=true` (off by default), so this only
-matters on the opt-in / CI path. When type-aware lint is on, the Prisma client and Nuxt types must be
-generated **before** `lint` runs, otherwise type-aware rules fail on missing generated types. This is
-satisfied by ordering, not a preflight check:
+matters on the opt-in and CI path. When type-aware lint is on, the Prisma client and Nuxt
+types must be generated **before** `lint` runs, otherwise type-aware rules fail on missing
+generated types. Ordering satisfies this, not a preflight check:
 
 - the managed `ci.yml` runs `prisma generate` (and `nuxi prepare`) before `pnpm lint`, and
 - `scripts.postinstall: "nuxt prepare"` regenerates Nuxt types on install.
 
-So a standard `pnpm install` + the managed CI ordering covers the prerequisite; no separate check is run.
+A standard `pnpm install` plus the managed CI ordering covers the prerequisite. No separate
+check runs.
 
 ## Prisma factory
 
@@ -442,8 +443,9 @@ existing `onlyBuiltDependencies` allowlist and `ignoredBuiltDependencies` are bo
 by the baked-in baseline, and **nothing warns about it**. Most affected packages ship a
 prebuilt native binary and keep working either way, so the practical breakage is limited to
 architectures with no prebuild and to postinstalls doing essential non-native work. Capture
-the old list before you adopt and re-add it via `pnpm.onlyBuiltDependencies` above. A repo that genuinely needs its own `packages:` list
-(a real monorepo) or its own exclude list should opt the file out entirely instead:
+the old list before you adopt and re-add it via `pnpm.onlyBuiltDependencies` above. A repo
+that genuinely needs its own `packages:` list (a real monorepo) or its own exclude list
+should opt the file out entirely instead:
 
 ```ts
 files: { "pnpm-workspace.yaml": "off" },
@@ -464,7 +466,7 @@ The `nuxt-app` preset ships a managed `.github/workflows/ci.yml`. Its `lint-type
 on top of what the runner image already carries, for a binary the suite needs and
 `ubuntu-latest` does not ship. The motivating case is `libxml2-utils`, for `xmllint`.
 
-It applies to the `test` and `e2e` jobs **only** -- never `lint-typecheck` or `build` -- and
+It applies to the `test` and `e2e` jobs only, never `lint-typecheck` or `build`. The step
 installs directly after `checkout`, before `pnpm install`, so a package needed by an install
 lifecycle script is covered as well as one needed by the tests. Leave it unset and the step
 is skipped entirely: it renders with a guard on the value being non-empty, so the default
@@ -498,7 +500,7 @@ out:
 | `docker.prismaRuntime` | final stage | copy the schema + install the `migrate deploy` CLI |
 | `docker.startCommand` | inside `CMD` | `prisma migrate deploy` then the node server |
 
-A seventh knob is different in kind — a validated version, not raw text:
+A seventh knob is different in kind: a validated version, not raw text.
 
 | Knob | Position | Default |
 | ---- | -------- | ------- |
@@ -525,8 +527,10 @@ export default {
 > shell-metacharacter check runs on them. The trust level is exactly that of
 > `files: { "Dockerfile": "off" }`, which any consumer can already set: whoever
 > can edit `streamctl.config.ts` can already replace the whole file. The
-> `USER node` switch and the `.output` ownership stay FIXED outside every knob,
-> so an override cannot re-root the container or drop the runtime user.
+> `.output` ownership stays FIXED outside every knob. The container itself runs
+> as **root**: a fixed `USER node` broke every deployment that overrides the image
+> CMD with a root-requiring command, so a repo that wants an unprivileged runtime
+> opts in with `docker.finalStage: "USER node"`.
 
 Setting a knob replaces its default outright, it does not append. So a `docker.buildSteps`
 override must restate every build command you still want, and `docker.prismaRuntime: ""`
@@ -534,8 +538,8 @@ removes the Prisma runtime block entirely. The three knobs that default to real
 (`buildSteps`, `prismaRuntime`, `startCommand`) are the ones where this matters; the other
 three default to `""`.
 
-**`prismaRuntime` and `startCommand` are coupled -- override one and you must override the
-other.** `prismaRuntime` is what installs the Prisma CLI into the final stage, and the
+**`prismaRuntime` and `startCommand` are coupled.** Override one and you must override the
+other. `prismaRuntime` is what installs the Prisma CLI into the final stage, and the
 DEFAULT `startCommand` is `npm exec prisma migrate deploy && node ...`. Setting only
 `prismaRuntime: ""` therefore produces an image whose `CMD` invokes a CLI that is no longer
 installed, and the container fails to start. The example above overrides both, which is why
@@ -552,7 +556,7 @@ The base preset owns its own keys in `.vscode/settings.json` and leaves the rest
 to the project. Among them is i18n-ally, configured for the fleet's standard setup:
 `@nuxtjs/i18n` with flat dotted keys under `i18n/locales`.
 
-Everything the payload does not write is yours and survives a sync untouched -- your
+Everything the payload does not write is yours and survives a sync untouched: your
 `editor.fontSize`, your `files.exclude`, any unrelated key at all. Six of those are named in
 the manifest as project-owned on top of that (`editor.fontSize`, `editor.rulers`,
 `editor.formatOnSave`, `files.exclude`, `search.exclude`, `files.watcherExclude`), which
@@ -561,7 +565,7 @@ payload writes are reverted, and they are the ones below.
 
 | Knob | Default | Effect |
 | ---- | ------- | ------ |
-| `editor.i18nSourceLanguage` | `"de"` | The locale i18n-ally translates FROM (`i18n-ally.sourceLanguage`). Payload-enforced -- see below |
+| `editor.i18nSourceLanguage` | `"de"` | The locale i18n-ally translates FROM (`i18n-ally.sourceLanguage`). Payload-enforced; see below |
 
 ```ts
 export default {
@@ -571,7 +575,7 @@ export default {
 ```
 
 **If your repo authors its source strings in English, set this.** The source language is
-payload-owned, so leaving it unset does not mean "keep what I have" -- every sync writes
+payload-owned, so leaving it unset does not mean "keep what I have". Every sync writes
 `"de"` into the file, over the top of an `"en"` you put there by hand. Nothing warns, and
 `streamctl check` stays green afterwards, because the value it finds is the value the payload
 intends. Setting the knob is the only thing that makes `"en"` survive a sync.
@@ -586,15 +590,18 @@ sync. A repo that genuinely needs a different layout should opt the file out
 
 The base preset ships `.github/workflows/streamctl-upgrade.yml`, a scheduled workflow
 that opens a PR when a payload update is available. It is an `enabledBy`-gated managed
-file, off by default: it only lands once a repo opts in, and it is inert until the
-required token exists.
+file, off by default. It only lands once a repo opts in.
 
 Enable it in `streamctl.config.ts`, then `streamctl sync`:
 
 ```ts
 export default {
   // ...
-  automation: { upgradePr: true },
+  automation: {
+    upgradePr: true,
+    // allowWorkflowUpdates: true,
+    // prTokenSecret: "STREAMCTL_PR_TOKEN",
+  },
   // optional: version pins, default to the payload's baseline. `node` feeds
   // ci.yml + the Dockerfile; `pnpm` feeds the Dockerfile only (CI pins pnpm
   // via package.json#packageManager):
@@ -602,30 +609,56 @@ export default {
 };
 ```
 
-Required secrets:
-
-| Secret | Purpose |
-| ------ | ------- |
-| `STREAMCTL_PR_TOKEN` | A GitHub App installation token or machine-account PAT used to open the PR. **Not** the default `GITHUB_TOKEN`: a PR opened with `GITHUB_TOKEN` does not trigger `pull_request` workflows, so the repo's own `check` gate would never run on the bot PR. |
-
-That is the only one, because the payload is public npm, so the install step needs no registry
-token. A repo whose *other* dependencies are private must opt this full-owned workflow
-out and wire its own auth.
+By default, the workflow uses `GITHUB_TOKEN` and omits changes under
+`.github/workflows/**`. If an update contains workflow changes, it opens a draft PR
+with every other safe change and lists the omitted files and completion commands.
 
-The workflow branches on the CLI exit codes: `check` exit 4 opens a PR; exit 0 stops;
-exit 3 (pre-existing drift) opens a drift issue instead. A clean `upgrade` (exit 0)
-produces a reconcile PR; a conflicted `upgrade` (exit 2, rolled back) produces a
-plan-only PR labelled `needs-interactive-upgrade` for a human to finish with
-`streamctl sync --interactive`.
+Set `automation.allowWorkflowUpdates` to `true` to include workflow changes. Add a
+`STREAMCTL_PR_TOKEN` repository secret with `Contents`, `Pull requests`, and
+`Workflows` write access. Change `automation.prTokenSecret` when the secret has another
+name. A fine-grained PAT or GitHub App token works. The built-in `GITHUB_TOKEN` cannot
+receive `Workflows` permission.
 
-> The org bot identity is still being decided. Until the runbook lands, leave the
-> workflow disabled. Design only; nothing is enabled anywhere.
+| Knob | Default | Effect |
+| ---- | ------- | ------ |
+| `automation.upgradePr` | `false` | Sync the scheduled upgrade workflow |
+| `automation.allowWorkflowUpdates` | `false` | Include `.github/workflows/**` changes in upgrade PRs |
+| `automation.prTokenSecret` | `"STREAMCTL_PR_TOKEN"` | Secret used when workflow updates are enabled |
+
+The upgrade job runs `streamctl check` and every available lint, typecheck, test, and
+build script before opening a ready PR. PRs created with `GITHUB_TOKEN` do not trigger
+their own `pull_request` workflows, so these inline checks are required. The external
+token allows the new PR to trigger them normally.
+
+The workflow handles CLI results as follows:
+
+- `check` exit 0: stop without a PR.
+- `check` exit 3: open or update one drift issue.
+- `check` exit 4: attempt the upgrade.
+- `upgrade` exit 0: validate and open a ready PR, or a draft when workflow files were omitted.
+- `upgrade` exit 2: inspect conflicts using the pre-upgrade status.
+- Any other exit: fail the workflow.
+
+A conflict is safe to apply when the same path was previously `full` managed and
+`in-sync`. The workflow retries those generated replacements with `--force`. Any new,
+modified, malformed, or structurally conflicting path produces a draft PR instead.
+Workflow changes also produce a draft unless explicitly allowed. Drafts contain every
+safe change, keep conflicting and omitted workflow files at their current content, list
+what remains, and give the commands needed to finish the upgrade. When a malformed or
+structurally invalid file blocks `--force`, the draft only updates the payload version
+and lockfile.
+
+Diagnostic JSON stays under the runner's temporary directory. Upgrade branches include
+the target version, so a later release does not overwrite an older open PR.
+
+The payload is public npm. A repo with other private dependencies must opt this workflow
+out and provide its own install authentication.
 
 ### Action pinning policy
 
-Every action in every managed workflow and CI job fragment is pinned by full commit
-SHA (with the version tag in a trailing comment), since moving tags can be re-pointed, so
-tags are never trusted, secrets or not. `test/workflow-pins.test.ts` sweeps all preset
+Every action in every managed workflow and CI job fragment is pinned by full commit SHA,
+with the version tag in a trailing comment. Moving tags can be re-pointed, so tags are
+never trusted, secrets or not. `test/workflow-pins.test.ts` sweeps all preset
 templates and fails on any `uses:` that is not a 40-hex SHA.
 
 The shipped pins track `actions/checkout` v6, `actions/setup-node` v6, and

package/dist/config.d.mts

@@ -1,19 +1,16 @@
-import { C as CreateSidebaseEslintOptions } from './shared/base-config.CuUhyvQo.mjs';
+import { C as CreateSidebaseEslintOptions } from './shared/base-config.BoberVUk.mjs';
 
 /**
- * Version-baseline profile, named for the framework AND its major so two majors can
- * coexist during a migration: the manifest declares one profile per major with its own
- * `detect.majorIs`, and each repo detects the one matching its own Nuxt version.
+ * Version-baseline profile, named for the framework and its major so two majors can
+ * coexist during a migration.
  *
- * The name MUST match a `versionProfiles` key in the preset chain. The CLI resolves the
- * baseline with `versionProfiles?.[profile] ?? {}`, so a name nothing declares reconciles
- * NOTHING, silently. `scripts/validate-presets.mjs` fails the build on that mismatch.
+ * An unknown name reconciles nothing, silently. `scripts/validate-presets.mjs` fails
+ * the build on that mismatch.
  */
 type Profile = "nuxt-4";
 /**
- * Optional CI knobs (`config.ci.*`) the nuxt-app preset understands: the job
- * toggles. Keys mirror the manifest's `ci.*` `configKeys`; the consistency test
- * in `test/config.test.ts` proves they stay in lockstep.
+ * CI job knobs (`config.ci.*`). Keys mirror the manifest's `ci.*` `configKeys`, and
+ * `test/config.test.ts` proves the two stay in lockstep.
  */
 interface NuxtBaseCiConfig {
     /** Include the `pnpm test` job. */
@@ -21,22 +18,19 @@ interface NuxtBaseCiConfig {
     /** Include the e2e job + postgres service. */
     e2e?: boolean;
     /**
-     * System packages apt-installed in the `test` and `e2e` jobs before
-     * `pnpm install`, for a binary the suite needs that `ubuntu-latest` does not
-     * ship (the motivating case: `libxml2-utils` for `xmllint`). Empty by default,
-     * which renders the install step inert rather than absent. Package names only:
-     * each element is metacharacter-checked, then the joined string is re-validated
-     * by the manifest pattern, because the rendered `run:` line is deliberately
-     * unquoted so word splitting reaches apt-get.
+     * Packages apt-installed in the `test` and `e2e` jobs, for a binary the suite needs
+     * that `ubuntu-latest` lacks. Empty renders the install step inert, not absent.
+     *
+     * Package names only: the rendered `run:` line is unquoted so word splitting reaches
+     * apt-get, so every element is metacharacter-checked.
      */
     aptPackages?: string[];
 }
 /**
- * Optional runtime version pins (`config.versions.*`). `node` feeds every
- * render (`ci.yml`, the Dockerfile, the upgrade-PR workflow); `pnpm` feeds the
- * Dockerfile only. CI takes its pnpm from `package.json#packageManager`, the
- * single reconciled source, so it is never passed to `pnpm/action-setup`.
- * Defaults come from the version baseline (node 24.13.0, pnpm 10.28.1).
+ * Runtime version pins (`config.versions.*`). `node` feeds every render (`ci.yml`,
+ * the Dockerfile, the upgrade workflow); `pnpm` feeds the Dockerfile only, because CI
+ * takes pnpm from `package.json#packageManager`. Defaults come from the version
+ * baseline (node 24.13.0, pnpm 10.28.1).
  */
 interface NuxtBaseVersionsConfig {
     /** Node version for CI jobs, the Docker base image, and the upgrade workflow. */
@@ -52,16 +46,15 @@ interface NuxtBaseVersionsConfig {
  */
 interface NuxtBaseDockerConfig {
     /**
-     * Project-owned apt packages for the production stage, ON TOP of the baked-in
-     * baseline (`openssl`: the Prisma query engine generated in the build stage
-     * dynamically links libssl3, which slim images do not ship).
+     * Apt packages for the production stage, on top of the baked-in `openssl`, which is
+     * always installed because the Prisma query engine links libssl3 and slim images do
+     * not ship it.
      */
     aptPackages?: string[];
     /**
-     * Raw Dockerfile text injected in the build stage BEFORE `pnpm install`, e.g.
-     * a `COPY ./vendor ./vendor` a repo needs present at install time. Lands
-     * verbatim; see the trust note below. Global installs must use `npm i -g`
-     * (`PNPM_HOME` is not set, so `pnpm add -g` fails to find its bin dir).
+     * Raw Dockerfile text injected in the build stage before `pnpm install`, e.g. a
+     * `COPY ./vendor ./vendor` needed at install time. Lands verbatim. Global installs
+     * must use `npm i -g`: `PNPM_HOME` is unset, so `pnpm add -g` cannot find its bin dir.
      */
     preInstall?: string;
     /**
@@ -77,15 +70,14 @@ interface NuxtBaseDockerConfig {
     buildSteps?: string;
     /**
      * Raw Dockerfile text injected in the final stage BEFORE `CMD`, e.g. extra
-     * `ENV`, `COPY --from`, or `RUN`. Lands verbatim. Cannot drop the fixed
-     * `USER node` switch, which sits below it.
+     * `ENV`, `COPY --from`, or `RUN`. Lands verbatim. The container runs as root,
+     * so a repo that wants an unprivileged runtime appends its own `USER` here.
      */
     finalStage?: string;
     /**
      * The final-stage Prisma runtime block (copy the schema, install the CLI for
      * `migrate deploy`). Defaults to that block; set `""` for a repo with no
-     * Prisma. The `USER node` switch and the `.output` ownership are FIXED outside
-     * this knob, so an override cannot re-root the container. Lands verbatim.
+     * Prisma. The `.output` ownership is FIXED outside this knob. Lands verbatim.
      */
     prismaRuntime?: string;
     /**
@@ -101,25 +93,26 @@ interface NuxtBaseDockerConfig {
     startCommand?: string;
 }
 /**
- * Optional automation knobs (`config.automation.*`) the base preset understands:
- * the opt-in upgrade-PR workflow and its runtime version pins. Keys mirror the
- * manifest's `automation.*` `configKeys`; the consistency test in
- * `test/config.test.ts` proves they stay in lockstep.
+ * Automation knobs (`config.automation.*`) for the opt-in upgrade-PR workflow. Keys
+ * mirror the manifest's `automation.*` `configKeys`, checked by `test/config.test.ts`.
  */
 interface NuxtBaseAutomationConfig {
     /** Sync the weekly streamctl upgrade-PR workflow (default: off, no workflow lands). */
     upgradePr?: boolean;
+    /** Let upgrade PRs change GitHub Actions workflows (default: false). */
+    allowWorkflowUpdates?: boolean;
+    /** Repository secret used when workflow updates are allowed. */
+    prTokenSecret?: string;
 }
 /**
- * Optional supply-chain knobs (`config.security.*`) the base preset understands:
- * the pnpm install cooldown rendered into the managed `pnpm-workspace.yaml`.
+ * Supply-chain knobs (`config.security.*`): the pnpm install cooldown rendered into
+ * the managed `pnpm-workspace.yaml`.
  */
 interface NuxtBaseSecurityConfig {
     /**
-     * Minutes a version must have been published before pnpm resolves it
-     * (`minimumReleaseAge`). Default `"10080"` (7 days); `"0"` disables the cooldown.
-     * A STRING because the manifest's `configKeys` has no number type, same as the
-     * `versions.*` pins.
+     * Minutes a version must have been published before pnpm resolves it. Default
+     * `"10080"` (7 days), `"0"` disables it. A string because the manifest's
+     * `configKeys` has no number type, same as the `versions.*` pins.
      */
     minimumReleaseAge?: string;
 }
@@ -129,33 +122,29 @@ interface NuxtBaseSecurityConfig {
  */
 interface NuxtBasePnpmConfig {
     /**
-     * Packages allowed to run install lifecycle scripts, ON TOP of the baked-in
-     * baseline (`@prisma/client`, `esbuild`, `prisma`). Use this instead of
-     * `pnpm approve-builds`, which writes to the managed file and is reverted on
-     * the next sync.
+     * Packages allowed to run install lifecycle scripts, on top of the baseline
+     * (`@prisma/client`, `esbuild`, `prisma`). Use this instead of `pnpm approve-builds`,
+     * which writes to the managed file and is reverted on the next sync.
      */
     onlyBuiltDependencies?: string[];
 }
 /**
- * Optional editor knobs (`config.editor.*`) rendered into the managed
- * `.vscode/settings.json`. Only the i18n-ally source language varies across the
- * fleet; the locales path and key style are payload-enforced.
+ * Editor knobs (`config.editor.*`) rendered into the managed `.vscode/settings.json`.
+ * Only the i18n-ally source language varies across the fleet.
  */
 interface NuxtBaseEditorConfig {
     /**
-     * Source locale i18n-ally translates FROM (`i18n-ally.sourceLanguage`).
-     * Default `"de"`, the fleet majority; repos authoring in English set `"en"`.
-     * A BCP-47-ish tag (`de`, `pt-BR`, `zh-Hans-CN`); the manifest's `pattern`
-     * rejects anything that could break the rendered JSON string.
+     * Source locale i18n-ally translates from. Default `"de"`; repos authoring in
+     * English set `"en"`. A BCP-47-ish tag (`de`, `pt-BR`, `zh-Hans-CN`); the manifest
+     * pattern rejects anything that could break the rendered JSON string.
      */
     i18nSourceLanguage?: string;
 }
 /**
- * The typed `streamctl.config.ts` shape for the `@sidebase/base-config` payload:
- * the CLI-universal fields plus this payload's declared knobs (`ci`, `versions`,
- * `docker`, `automation`, `eslint`) with their real option types. The generic CLI only
- * shape-checks these against the manifest's `configKeys`, so the precise types live
- * here, next to the payload that owns them, and consumers keep a fully typed config.
+ * The typed `streamctl.config.ts` shape for this payload: the CLI-universal fields plus
+ * the declared knobs with their real option types. The CLI only shape-checks knobs
+ * against the manifest's `configKeys`, so the precise types live here, next to the
+ * payload that owns them, and consumers keep a fully typed config.
  */
 interface NuxtBaseConfig {
     /** The payload package this repo syncs from. */
@@ -190,9 +179,8 @@ interface NuxtBaseConfig {
     eslint?: CreateSidebaseEslintOptions;
 }
 /**
- * Identity helper for a typed `streamctl.config.ts`, the payload analog of the
- * CLI's `defineStreamctlConfig`, adding editor inference for this payload's knobs.
- * Returns the config unchanged; the CLI validates it at load.
+ * Identity helper giving editor inference for this payload's knobs, the analog of the
+ * CLI's `defineStreamctlConfig`. Returns the config unchanged; the CLI validates it.
  */
 declare function defineNuxtBaseConfig(config: NuxtBaseConfig): NuxtBaseConfig;
 /** Runtime list of every {@link NuxtBaseCiConfig} key. */
@@ -210,11 +198,9 @@ declare const NUXT_BASE_PNPM_KEYS: string[];
 /** Runtime list of every {@link NuxtBaseEditorConfig} key. */
 declare const NUXT_BASE_EDITOR_KEYS: string[];
 /**
- * Every payload KNOB dot-path {@link NuxtBaseConfig} declares (the `ci.*` and
- * `automation.*` leaves plus the top-level knobs); excludes the CLI-universal
- * fields. The consistency test asserts this set equals the RESOLVED preset chain's
- * declared `configKeys` (base + nuxt-app), catching drift between the type and the
- * manifest in either direction.
+ * Every knob dot-path {@link NuxtBaseConfig} declares, excluding the CLI-universal
+ * fields. The consistency test asserts this set equals the resolved preset chain's
+ * `configKeys`, catching drift between the type and the manifest in either direction.
  */
 declare const NUXT_BASE_CONFIG_KEYS: string[];