@sidebase/base-config 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sidebase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,554 @@
+# @sidebase/base-config
+
+Shared `@sidebase` Nuxt configuration, delivered over two channels in one package:
+
+- npm channel: the root export `@sidebase/base-config` plus the subpath exports
+  `@sidebase/base-config/config`, `@sidebase/base-config/eslint`,
+  `@sidebase/base-config/prisma`, and `@sidebase/base-config/tsconfig.base`.
+- file-sync channel: the bundled `presets/` payload read by the [`@sidebase/streamctl`](https://github.com/sidebase/streamctl) CLI.
+
+## Install
+
+For the npm channel, install the package plus what the subpaths you use require:
+
+```sh
+pnpm add -D @sidebase/base-config eslint jiti
+```
+
+`eslint` (`^10.5.0`) and `jiti` (`>= 2.2.0`) are what `/eslint` needs; jiti is only
+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.
+
+For the file-sync channel, see Adopting below. The CLI wires the dependency itself.
+
+## Adopting
+
+The payload *is* the install: [`@sidebase/streamctl`](https://github.com/sidebase/streamctl)
+reads `presets/` straight from this package in a consuming repo's `node_modules`.
+
+```sh
+pnpm streamctl init --package @sidebase/base-config   # scaffold + first sync
+pnpm streamctl check                                  # CI drift gate
+pnpm streamctl upgrade --to <version>                 # move the pin forward
+```
+
+Neither package needs a registry token or private-registry setup: both target the public
+`@sidebase` scope on npm.
+
+Coming from `@sidestream-tech/nuxt-config`? That rename is a manual migration, not an
+upgrade: `streamctl upgrade` moves the version pin and never rewrites `package:`. Follow
+[`docs/migration.md`](docs/migration.md), and note that the step order is load-bearing.
+
+### Presets and profiles
+
+Two separate axes in `streamctl.config.ts`:
+
+- `base` is the preset, the set of managed files you get. `nuxt-app` names the repo
+  *type*: it ships a Dockerfile, a postgres/prisma CI pipeline, and PR-preview cleanup.
+- `profile` is the version baseline, the dependency pins reconciled into your
+  `package.json`. It names the framework and its major: `nuxt-4`.
+
+The major is in the profile name on purpose. Each profile carries its own
+`detect.majorIs`, so `init` picks the right one from your `package.json` and a future
+`nuxt-5` profile can sit alongside `nuxt-4` while repos migrate one at a time.
+
+`nuxt-4` is the only profile shipped today, so this payload is Nuxt 4 only. There is no
+`nuxt-3` profile and none is planned. Running `init` in a Nuxt 3 repo fails with
+"No version profile could be detected", because no profile's `detect.majorIs` matches the
+`nuxt` version in your `package.json`. Move the repo to Nuxt 4 before adopting.
+
+A profile name must match a `versionProfiles` key in the preset chain. If it does not, the
+CLI fails with `CONFIG_INVALID`: `profile "..." is not declared in presets/manifest.json
+profiles[]`. `pnpm validate:presets` catches the same mismatch at build time, so a broken
+profile name cannot ship in the first place.
+
+#### Reconciled `scripts.lint`
+
+The `nuxt-4` profile reconciles your `package.json` `scripts.lint` to
+`oxlint -c .oxlintrc.json --deny-warnings && eslint --max-warnings 0 .`, so the fleet
+runs `oxlint` (already pinned, with the shipped `.oxlintrc.json`) before ESLint.
+
+Unlike a version pin, a script has no forward-version floor to protect it, because a
+script is not a semver, so this is a plain **overwrite**: every `sync` replaces whatever
+your `scripts.lint` currently is. A repo that wants its own (for example
+`... && LINT_TYPEAWARE=true eslint --max-warnings 0 .` to opt into type-aware linting)
+keeps it by excluding the key:
+
+```ts
+export default {
+  // ...
+  versionSyncExclude: ["scripts.lint"],
+};
+```
+
+#### Overriding a managed file
+
+`.editorconfig` is **block**-managed: the payload owns a marked region, delimited by
+`# BEGIN streamctl MANAGED BLOCK editorconfig` / `# END ...`, and preserves everything
+outside it byte-for-byte. On first sync the managed block is appended to the end of your
+file. Because EditorConfig applies later matching sections over earlier ones, you keep a
+project override by placing it **below** the managed block:
+
+```ini
+# BEGIN streamctl MANAGED BLOCK editorconfig
+[*]
+indent_size = 2
+# END streamctl MANAGED BLOCK editorconfig
+
+# your override wins because it comes after the managed block
+[*]
+indent_size = 4
+```
+
+That way the payload keeps updating its region on every sync while your `indent_size = 4`
+survives. (A section placed *above* the block would be overridden by the block's
+`indent_size = 2`, so keep overrides below the `END` marker.)
+
+**First-sync hazard.** If your repo already has an `.editorconfig`, the block writer appends
+without looking at what is there, so all of your existing content ends up *above* the block
+and therefore loses. `streamctl check` exits 0 either way, because the block strategy only
+inspects its own markers. This applies to a fresh `streamctl init` just as much as to a
+migration, and you have to fix it by hand once. Step 8 of
+[`docs/migration.md`](docs/migration.md) has the detector and the two-case fix.
+
+If you instead want to stop managing a file entirely, opt it out per-path:
+
+```ts
+files: { ".editorconfig": "off" },
+```
+
+The cost of `off` is total: streamctl no longer touches that file, so **every future
+payload fix to it stops reaching your repo**, including new rules, security bumps, and
+format corrections. Prefer the block override above when you only need to change part of
+a file.
+
+## This repo's CLI dependency
+
+The payload is validated and dogfooded against the CLI, so `@sidebase/streamctl` is a
+`devDependency` here, pinned to the published semver range.
+`validate:presets` imports the CLI's exported manifest schema and the e2e dry-run drives the
+real CLI binary, so both resolve `@sidebase/streamctl` from the registry.
+
+The root `streamctl.config.ts` this payload documents needs **streamctl >= 0.2.0**, so the
+pin and the `pnpm-workspace.yaml` c12 override both move when that release lands. See
+"Config location" below.
+
+## Typed config
+
+The root export `@sidebase/base-config` and the subpath `@sidebase/base-config/config`
+are the same module. Both provide `defineNuxtBaseConfig` and the `NuxtBaseConfig` type,
+which is what makes a `streamctl.config.ts` typed. Every consuming repo has this file,
+and `streamctl init` scaffolds it importing from the root export:
+
+```ts
+// streamctl.config.ts
+import { defineNuxtBaseConfig } from "@sidebase/base-config";
+
+export default defineNuxtBaseConfig({
+  package: "@sidebase/base-config",
+  base: "nuxt-app",
+  version: "0.1.0",
+  profile: "nuxt-4",
+  ci: { unitTests: true },
+});
+```
+
+### Config location
+
+streamctl >= 0.2.0 reads `streamctl.config.ts` from the repo root, and `init` scaffolds it
+there. The older `.streamctl/config.ts` is still resolved, so an existing repo keeps working
+untouched and can move the file whenever it likes.
+
+Move it and nothing else changes: the contents are identical, and the CLI warns rather
+than guesses if both exist, naming the root file as the one it read. Keeping the legacy
+path is fine too. The one thing not to do is leave both in place, since only the root file
+is read and edits to the other will look like they do nothing.
+
+If you set `ignoresTypeAware` yourself, list whichever path your repo uses. The default
+covers both.
+
+`defineNuxtBaseConfig` returns the config unchanged. Its job is typed editor inference
+for this payload's knobs: completion and type checking on `ci`, `versions`, `docker`,
+`automation`, `security`, `pnpm`, and the whole `eslint` option surface, plus `profile`
+narrowed to the profile names that actually exist. Without it the object is an untyped
+literal, so a typo such as `ci: { unitTest: true }` stays silent in your editor.
+
+The CLI shape-checks the config against the manifest when it loads it, so a sync still
+works without the helper. The helper is what moves that feedback into your editor.
+
+Import `NuxtBaseConfig` directly when you need the type on its own:
+
+```ts
+import type { NuxtBaseConfig } from "@sidebase/base-config/config";
+```
+
+## Shared tsconfig
+
+`@sidebase/base-config/tsconfig.base` is the shared strict TypeScript base, exported as a
+JSON file so a `tsconfig.json` can extend it by package name. The `nuxt-app` preset ships
+a managed `tsconfig.json` that chains it with Nuxt's generated config:
+
+```json
+{
+  "extends": [
+    "@sidebase/base-config/tsconfig.base",
+    "./.nuxt/tsconfig.json"
+  ]
+}
+```
+
+Order matters: the shared base comes first, so Nuxt's generated config applies over it.
+
+## Naming convention
+
+Two rules cover every exported name, so you can predict them:
+
+- Types describing **this payload's config shape** are `NuxtBase*`: `NuxtBaseConfig`,
+  `NuxtBaseCiConfig`, `defineNuxtBaseConfig`, and the `NUXT_BASE_*_KEYS` lists. The prefix
+  is doing real work here, because these types describe the config of this specific
+  payload rather than anything generic.
+- **Everything else is domain-named with no package prefix**: `buildPrismaConfig`,
+  `applyPrismaDevEnv`, `createSidebaseEslint`, `resolveEslintOptions`. The import path
+  already states where a symbol comes from, so repeating it in the identifier adds
+  nothing.
+
+`streamctl` is reserved for the CLI (`@sidebase/streamctl`) and the files it owns:
+`streamctl.config.ts` in the repo root, and the legacy `.streamctl/` directory it still
+reads. Nothing exported from this package carries that name, because nothing
+exported from this package comes from the CLI. The ESLint layers this package builds are
+named `sidebase/*` (`sidebase/defaults`, `sidebase/console`, and so on), which is what you
+see in lint output and what you target if you `.override()` a layer by name. They are
+built at runtime by this package; the CLI never sees them.
+
+## ESLint factory
+
+`@sidebase/base-config/eslint` exports `createSidebaseEslint(options?)`, which wraps
+[`@antfu/eslint-config`](https://github.com/antfu/eslint-config) (a dependency of this
+package, so **do not add `@antfu/eslint-config` directly**) and returns its
+`FlatConfigComposer`, so you chain `.append()` / `.override()` for local rules:
+
+```ts
+// eslint.config.ts
+import { createSidebaseEslint } from "@sidebase/base-config/eslint";
+
+export default createSidebaseEslint({ zod: "full", trpcGuard: true })
+  .append({ rules: { "vue/multi-word-component-names": "off" } });
+```
+
+### Options
+
+| Option | Default | Effect |
+| ------ | ------- | ------ |
+| `zod` | `"none"` | `"full"` = ban `.extend()/.merge()/.passthrough()` + enforce `import * as z`; `"import-style"` = import style only; `"none"` = off |
+| `console` | `"error"` | `"error"` bans all `console.*`; an array is the allow-list (e.g. `["warn", "error"]`) |
+| `trpcGuard` | `false` | Ban `publicProcedure` in `server/trpc/routers/**` |
+| `prismaImportGuard` | `false` | Ban `~~/prisma/` client imports on the app side |
+| `typeDefStyle` | `"interface"` | `ts/consistent-type-definitions` |
+| `autoImportPaths` | `["utils/", "composables/", "~~/shared/types/"]` | Paths banned from direct import (Nuxt auto-imports) |
+| `autoImportTypeOnly` | `[]` | Subset of `autoImportPaths` where `import type { ... }` stays allowed (value imports still banned) |
+| `ignoresTypeAware` | `["prisma.config.ts", "eslint.config.ts", "streamctl.config.ts", ".streamctl/**/*.ts"]` | Files excluded from antfu's type-aware program (only relevant when type-aware). Covers both config locations, since `.streamctl/config.ts` stays supported after the root default lands |
+| `testFilePattern` | `["**/*.{test,spec}.{ts,tsx}", "**/*.stories.{ts,tsx}"]` | Test/spec/story globs where the `process.env` + auto-import bans are relaxed |
+
+Rare per-repo rules belong in your local `.append(...)`, not in the option surface.
+
+### Rule IDs & inline suppression
+
+The custom bans map to these ESLint rule IDs. Use the exact ID in an
+`// eslint-disable-next-line ...` directive to suppress one line:
+
+| Ban | Rule ID |
+| --- | ------- |
+| Direct `process.env` access, as a member expression (`process.env.X`, `const { env } = process`) | `no-restricted-properties` |
+| ANY import **or re-export** of `node:process` or `process` that can reach `env` (`import { env }`, `import { env as e }`, `import * as proc`, `import proc from "node:process"`, `export { env } from "node:process"`, `export * from "node:process"`) | `ts/no-restricted-imports` |
+| Auto-import path imports (`autoImportPaths`) | `ts/no-restricted-imports` |
+| App-side Prisma client import (`prismaImportGuard`) | `ts/no-restricted-imports` |
+| Zod named-`z` import style (`zod: "import-style"`/`"full"`) | `no-restricted-syntax` |
+| Zod `.extend()/.merge()/.passthrough()` (`zod: "full"`) | `no-restricted-syntax` |
+| `publicProcedure` in routers (`trpcGuard`) | `no-restricted-syntax` |
+
+"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.
+
+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
+anything, and ESLint additionally warns that it was unused.
+
+```
+// eslint-disable-next-line no-restricted-properties
+import { env } from 'node:process'
+
+1:1   warning  Unused eslint-disable directive (no problems were reported from 'no-restricted-properties')
+2:10  error    'env' import from 'node:process' is restricted...   ts/no-restricted-imports
+```
+
+### Requirements
+
+`eslint` is a peer dependency (`^10.5.0`), so consumers of `/eslint` must supply ESLint
+themselves. The peer range matches the version baseline, so `streamctl` version-sync
+keeps a repo's ESLint in step with what this package is tested against.
+
+Flat config only. To load a TypeScript `eslint.config.ts` on Node, consumers add
+`jiti` (`>= 2.2.0`) as a devDependency: ESLint has no native TS loader, and ESLint 10
+rejects jiti below 2.2.0. Writing `eslint.config.mjs` instead drops the jiti requirement
+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:
+
+- 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.
+
+## Prisma factory
+
+`@sidebase/base-config/prisma` exports `buildPrismaConfig({ views?, typedSql? })`,
+which returns a Prisma 6.19 config object you wrap in `defineConfig`:
+
+```ts
+// prisma.config.ts
+import { defineConfig } from "prisma/config";
+import { buildPrismaConfig } from "@sidebase/base-config/prisma";
+
+export default defineConfig(buildPrismaConfig({ views: true, typedSql: true }));
+```
+
+It reads `DATABASE_URL` / `DIRECT_DATABASE_URL` / `SHADOW_DATABASE_URL` from the
+environment (Pattern B): the schema engine gets a pgbouncer-free direct
+connection: `DIRECT_DATABASE_URL` if set, otherwise `DATABASE_URL` with
+pooler-only query params (`pgbouncer`, `connection_limit`, and so on) stripped via `ufo`.
+`SHADOW_DATABASE_URL` is wired only when present; with no database URL the engine
+block is omitted so the schema's own `datasource` applies.
+
+| Option | Default | Effect |
+| ------ | ------- | ------ |
+| `views` | `false` | Configure the `views` feature (`prisma/views`) |
+| `typedSql` | `false` | Configure the `typedSql` preview feature (`prisma/sql`) |
+
+### `applyPrismaDevEnv`
+
+The same subpath exports `applyPrismaDevEnv(env?)`, the companion for local development.
+It seeds `DIRECT_DATABASE_URL`, `DATABASE_URL`, and `SHADOW_DATABASE_URL` with localhost
+defaults, but only when they are unset, so a real `.env` or shell value always wins. It
+writes to the environment record you pass and defaults to `process.env`, which is a
+deliberate side effect.
+
+You need it because once a `prisma.config.ts` exists, Prisma stops auto-loading `.env`.
+A schema that reads `env("DATABASE_URL")` then fails with no environment at all. Call it
+in the config file, after loading dotenv, and the Prisma CLI runs against local postgres
+with zero setup:
+
+```ts
+// prisma.config.ts
+import "dotenv/config";
+import { defineConfig } from "prisma/config";
+import { applyPrismaDevEnv, buildPrismaConfig } from "@sidebase/base-config/prisma";
+
+applyPrismaDevEnv();
+
+export default defineConfig(buildPrismaConfig());
+```
+
+`buildPrismaConfig` alone is enough wherever the connection variables are already set,
+which is every deployed environment and CI. Add `applyPrismaDevEnv` when you want
+`prisma migrate dev` and friends to work on a fresh checkout without a `.env` file. The
+defaults are direct = local postgres, pooled = the direct URL plus `pgbouncer=1`, and
+shadow = the direct URL on a `/prisma-shadow` database.
+
+The URL helpers never log a connection string and never put one in an error message, so a
+password cannot reach your terminal or CI output through them. Keep that property if you
+wrap them.
+
+`prisma` / `@prisma/client` are peer dependencies (`^6.19`).
+
+> Prisma 7 is out of scope for now. v7 changes the config shape (`env()` helper,
+> `directUrl` becomes `url`, no `package.json` prisma block); a `buildPrismaConfig` v7
+> variant is a deliberate later bump.
+
+## Supply-chain cooldown (`pnpm-workspace.yaml`)
+
+The base preset fully owns `pnpm-workspace.yaml`, pnpm's settings file. It ships two
+supply-chain controls, both on by default for every repo:
+
+```yaml
+packages: []
+minimumReleaseAge: 10080          # 7 days, in minutes
+minimumReleaseAgeExclude:
+  - "@sidebase/*"
+onlyBuiltDependencies:            # the postinstall-script allowlist
+  - "@prisma/client"
+  - "esbuild"
+  - "prisma"
+```
+
+`minimumReleaseAge` refuses to resolve a version until it has been published for
+7 days, so a compromised release has time to be caught and yanked before the fleet
+installs it. It needs pnpm 10.16 or newer and gates *fresh resolution only*, so
+`pnpm install --frozen-lockfile` replays the lockfile untouched and CI is unaffected.
+
+The pnpm baseline shipped to consumers is 10.28.1 (`presets/*/preset.json`). This repo's
+own `packageManager` pin tracks separately and is usually newer; the two are independent
+by design, not drift.
+
+Exclusions match **package names, not dependency trees**: an excluded package's own
+dependencies still face the cooldown, and pnpm resolves the newest *eligible* older
+version in range. Only when nothing in range is old enough does resolution fail, with
+a misleading `ERR_PNPM_NO_MATCHING_VERSION` ([pnpm#9998](https://github.com/pnpm/pnpm/issues/9998)).
+
+`@sidebase/*` is exempt: the first-party scope covering both this payload and the
+`streamctl` CLI, published by the org itself, so a payload release reaches the fleet
+the same day instead of waiting out its own cooldown.
+
+**`packages: []` is load-bearing.** pnpm defaults it to `**` whenever a
+`pnpm-workspace.yaml` exists, which would silently promote every nested `package.json`
+(test fixtures, examples) to a workspace project and break `--frozen-lockfile`.
+
+`onlyBuiltDependencies` is the install-script allowlist. Everything else installs
+with its lifecycle scripts blocked. Add extras through the config, **not** through
+`pnpm approve-builds` (which writes to the managed file and is reverted on the next
+sync):
+
+```ts
+export default {
+  // ...
+  security: { minimumReleaseAge: "10080" }, // minutes; "0" disables the cooldown
+  pnpm: { onlyBuiltDependencies: ["sharp"] }, // on top of the baked-in baseline
+};
+```
+
+| Option | Default | Effect |
+| ------ | ------- | ------ |
+| `security.minimumReleaseAge` | `"10080"` | Minutes a release must age before pnpm installs it. A string, because the manifest's `configKeys` has no number type, same as the `versions.*` pins. |
+| `pnpm.onlyBuiltDependencies` | `[]` | Extra packages allowed to run install scripts, appended below the baked-in baseline |
+
+Because the file is `full`-owned, a repo that already has a `pnpm-workspace.yaml`
+raises a one-time adoption conflict on the first sync; reconcile it with
+`streamctl sync --interactive`.
+
+**Adopting it discards your existing keys.** The rendered file is the payload's, so an
+existing `onlyBuiltDependencies` allowlist and `ignoredBuiltDependencies` are both replaced
+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:
+
+```ts
+files: { "pnpm-workspace.yaml": "off" },
+```
+
+## Dockerfile knobs
+
+The `nuxt-app` preset ships a managed `Dockerfile`. Beyond `docker.aptPackages`
+(an `openssl`-plus allowlist), six `docker.*` knobs inject raw text at fixed
+positions so every fleet repo can express its own build without opting the file
+out:
+
+| Knob | Position | Default |
+| ---- | -------- | ------- |
+| `docker.preInstall` | build stage, before `pnpm install` | `""` |
+| `docker.buildArgs` | build stage, before `COPY . .` | `""` |
+| `docker.buildSteps` | the build-command block | `nuxi prepare` / `prisma generate` / `run build` |
+| `docker.finalStage` | final stage, before `CMD` | `""` |
+| `docker.prismaRuntime` | final stage | copy the schema + install the `migrate deploy` CLI |
+| `docker.startCommand` | inside `CMD` | `prisma migrate deploy` then the node server |
+
+```ts
+export default {
+  // ...
+  docker: {
+    preInstall: "COPY ./vendor ./vendor", // vendored dep needed at install time
+    buildSteps: "RUN pnpm nuxi prepare\nRUN pnpm run build", // a repo with no Prisma
+    prismaRuntime: "", // drop Prisma entirely
+    startCommand: "node .output/server/index.mjs",
+  },
+};
+```
+
+> **These six values land verbatim.** They are `string`, not `string[]`, so order
+> is preserved (a sorted array would scramble ordered `RUN` steps), and no
+> 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.
+
+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: ""`
+removes the Prisma runtime block entirely. The three knobs that default to real content
+(`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
+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
+it is safe to copy; a single-knob change is not. Drop the `migrate deploy` half of
+`startCommand` at the same time.
+
+Global installs in `docker.preInstall` must use `npm i -g <tool>`, not
+`pnpm add -g`: the image sets no `PNPM_HOME`, so pnpm's global bin dir is
+undefined.
+
+## Upgrade-PR workflow
+
+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.
+
+Enable it in `streamctl.config.ts`, then `streamctl sync`:
+
+```ts
+export default {
+  // ...
+  automation: { upgradePr: true },
+  // 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):
+  // versions: { node: "24.13.0", pnpm: "10.28.1" },
+};
+```
+
+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.
+
+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`.
+
+> The org bot identity is still being decided. Until the runbook lands, leave the
+> workflow disabled. Design only; nothing is enabled anywhere.
+
+### 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
+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
+`pnpm/action-setup` v6. These majors run on the node24 action runtime, which needs a
+GitHub Actions runner `>= v2.327.1`. GitHub-hosted `ubuntu-latest` is far past that; only
+a repo that adds its own **self-hosted** runner needs to keep it above that floor.