@sidebase/base-config 0.1.0

package/docs/migration.md

@@ -0,0 +1,764 @@
+# Migrating from `@sidestream-tech/nuxt-config` to `@sidebase/base-config`
+
+An ordered runbook for moving one repository onto the renamed payload.
+
+The rename is not a version bump. `@sidebase/base-config` is a new npm package with its
+own name, scope, and version line, so no automated upgrade path crosses it. You do the
+steps below by hand, once, per repository.
+
+**Read "Why the order matters" below before you start.** Step 2 must happen before step 4. Getting
+that wrong does not produce an error. It produces a repository that reports "all clean"
+and exits 0 while receiving no dependency updates at all.
+
+## Scope
+
+This is written for a real migration. At the time of writing, the known adopters are all
+on unmerged branches, and none of them can install at all: every one pins both the payload
+and the CLI, through `pnpm.overrides` or a direct `file:` dependency, into a `/tmp`
+directory that no longer exists. For a branch in that state, re-running
+`streamctl init` against the published package on a fresh branch is usually less work than
+migrating it. Use this runbook when you have a working checkout worth preserving.
+
+## CLI prerequisite
+
+Your `@sidebase/streamctl` must satisfy two separate requirements. They landed in that
+order, so the second one is the binding constraint:
+
+1. **The undeclared-profile guard.** Makes a profile name that the payload does not declare
+   a hard error, instead of an empty baseline that reconciles nothing and fails no command.
+   This is what protects step 4.
+2. **The `scripts.*` reconcile widening** (`RECONCILABLE_KEY_PATTERN`, streamctl commit
+   `090c674`). This payload's version baseline includes `scripts.lint`, and a CLI without
+   the widening rejects the whole payload at load time with `CONFIG_INVALID`, so `init`,
+   `sync`, `check`, `upgrade`, and `status` all fail.
+
+The widening came after the guard, so **a build containing the widening also contains the
+guard, and the widening is the effective minimum.** Requiring it is sufficient.
+
+> **Minimum version: `0.2.0`.**
+> That release carries both prerequisites above, and one more that binds harder: it reads
+> `streamctl.config.ts` from the repo root, which is the layout this payload's fixtures,
+> docs, and `ignoresTypeAware` default all assume. `0.1.0` already has the widening, so on
+> that build the payload loads — it just cannot find a root config file.
+
+### Verify your CLI has both, without needing the version number
+
+You do not need a version number to check this. The payload itself is the test. Run this
+once you have completed step 3 and the `package:` half of step 4, and before you change
+`profile:`:
+
+```sh
+pnpm streamctl check
+```
+
+Read the result against this table:
+
+| What you see | What it means |
+| ------------ | ------------- |
+| `[ERROR] Invalid presets/nuxt-app/preset.json: ... "scripts.lint" must be a reconcilable version key ...` | The widening is MISSING. Upgrade the CLI. Nothing else will work until you do. |
+| `[ERROR] profile "nuxt" is not declared in presets/manifest.json profiles[]; declared: nuxt-4.` with exit 1 | Both requirements are met. This error is the guard doing its job. Continue to the `profile:` edit. |
+| `all clean.` with exit 0, while `profile:` is still `nuxt` | The guard is MISSING. Stop. Do not continue. Upgrade the CLI first. See "Why the order matters". This should be impossible on any build cut from the current source, since the widening implies the guard; if you see it, you are on an older published build that predates both. |
+
+The middle row is the expected outcome on a correct CLI. It looks like a failure and is
+not one: you are deliberately in a half-migrated state, and the CLI is telling you the
+profile name has not been updated yet.
+
+## Why the order matters
+
+**Skip this section if you already confirmed your CLI with the table above.** The failure it
+describes cannot happen on a CLI that has the guard. It is here because every adopter branch
+today runs a build that does not, and because the failure is invisible if you meet it.
+
+The CLI resolves a version baseline with `versionProfiles?.[profile] ?? {}`. A profile name
+that no preset declares therefore resolves to an empty object rather than raising an error.
+An empty baseline reconciles nothing.
+
+On a CLI **with** the guard, an undeclared profile is a hard error and exit 1. You cannot
+get into the bad state.
+
+On a CLI **without** the guard, renaming the profile to `nuxt-4` before the payload that
+declares `nuxt-4` is resolvable gives you a repository where:
+
+- `streamctl check` prints `all clean.` and exits 0,
+- `streamctl sync` reports that everything is up to date and writes nothing,
+- every managed file really is in sync, so the report is not lying about files,
+- and yet `eslint`, `jiti`, `prisma`, `@prisma/client`, `typescript`, and the
+  `scripts.postinstall` and `scripts.lint` entries are never reconciled again.
+
+Exactly one thing surfaces, a non-blocking warning on stderr:
+
+```
+[WARN] profile "nuxt-4" does not match the profile detected from package.json: "nuxt" (nuxt ^4.3.0 in devDependencies).
+```
+
+Do not count on that line to save you. It does not fail the command, it does not change the
+exit code, and it prints directly above a green `all clean.` in a CI log that nobody opens
+when the job passes. Treat it as the only warning you will get, not as a safety net.
+
+The repository quietly stops receiving the version floors the fleet relies on, and the next
+person to look sees a green check. This was reproduced deliberately, not theorised: on a
+guardless CLI with the profile renamed ahead of the payload, `jiti` was hand-edited down to
+`^1.0.0`, `eslint` down to `^8.0.0`, and `scripts.postinstall` deleted outright. The next
+`sync` restored none of the three and reported nothing to write, and `check` still exited 0
+with `all clean.`
+
+If you suspect a repository is already in this state, do not trust `check`. Open
+`package.json` and confirm the pins actually match the baseline in
+`presets/nuxt-app/preset.json`.
+
+## Why `streamctl upgrade` cannot do this
+
+`upgrade` moves the version pin and nothing else. Internally it builds the new config as
+`{ ...config, version: toVersion }`, so `package:` is carried through untouched, and it
+bumps the devDependency under that same unchanged name. There is no code path in which it
+rewrites `package:` from one npm name to another.
+
+So `upgrade` can take you from `@sidebase/base-config@0.1.0` to a later `@sidebase/base-config`,
+but it cannot take you from `@sidestream-tech/nuxt-config` to `@sidebase/base-config`. That
+is why this runbook exists and why step 4 is a manual edit.
+
+## The runbook
+
+### 0. Remove any dead local override
+
+Skip this if `pnpm install` already works. If it does not, this is almost certainly why, and
+every later step runs an install.
+
+A repository that installed the payload through a local override, for example
+`pnpm.overrides` pointing at a checkout or a tarball path, cannot install once that path
+disappears. Every known adopter branch is in exactly this state, pinned into a `/tmp`
+directory that no longer exists.
+
+```sh
+grep -n "file:" package.json
+```
+
+If a `file:` entry points somewhere that no longer exists, there is nothing to repoint and
+nothing to preserve: delete it. Note that `pnpm remove` in step 3 does NOT clear a matching
+`pnpm.overrides` entry, so the override survives the swap unless you remove it by hand.
+
+If the path still exists and you are deliberately testing a local build, repoint it at the
+artifact you actually want before continuing. The CLI never rewrites an override for you,
+because that is package-manager specific.
+
+### 1. Get to a clean check first
+
+```sh
+pnpm streamctl check
+```
+
+Expected before you go any further: exit 0 and `all clean.`
+
+If the repository has pre-existing drift, `check` exits 3 and prints the drifted paths:
+
+```
+streamctl check
+
+  [x]  drift  1   AGENTS.md (content)
+
+DRIFT_DETECTED. Run `streamctl sync` to reconcile.
+```
+
+Resolve it now, either by accepting the payload version with `pnpm streamctl sync`, or by
+opting the file out (see the escapes section) if the repository genuinely owns it. Do not
+carry drift into a rename: any automated path takes the drift branch instead of the
+upgrade branch, and hand-resolving a conflict at the same time as a rename makes it much
+harder to tell which change caused what.
+
+### 2. Upgrade the CLI
+
+Do this BEFORE touching the config.
+
+```sh
+pnpm add -D @sidebase/streamctl@^0.2.0
+```
+
+### 3. Swap the payload package
+
+```sh
+pnpm remove @sidestream-tech/nuxt-config
+pnpm add -D @sidebase/base-config
+```
+
+### 4. Edit `streamctl.config.ts`
+
+Do this in two parts so you get the CLI verification for free.
+
+First change `package:` and `version:`, and leave `profile:` alone:
+
+```ts
+export default defineNuxtBaseConfig({
+  package: "@sidebase/base-config",   // was @sidestream-tech/nuxt-config
+  base: "nuxt-app",                   // unchanged
+  version: "0.1.0",                   // the @sidebase/base-config version you installed
+  profile: "nuxt",                    // still the OLD name, on purpose, for one command
+});
+```
+
+Run `pnpm streamctl check` and read it against the table in the CLI prerequisite section.
+You want the `profile "nuxt" is not declared` error with exit 1.
+
+If you instead get `CONFIG_INVALID` naming a key in your own config, that key was removed in
+this release; `ci.deploy` and `ci.migrationLint` are the two. The CLI shape-checks the config
+against the payload's declared `configKeys`, so a key that no longer exists is a hard error
+rather than an ignored field. Delete it and re-run.
+
+Then change the profile:
+
+```ts
+  profile: "nuxt-4",
+```
+
+The import in that file changes too, since `defineNuxtBaseConfig` now comes from the new
+package:
+
+```ts
+import { defineNuxtBaseConfig } from "@sidebase/base-config";
+```
+
+### 5. Update the other import specifiers
+
+Two files import from the payload by name. The ESLint factory was also RENAMED in this
+release, from `createStreamctlEslint` to `createSidebaseEslint`, so that call changes too:
+
+```ts
+// eslint.config.ts
+import { createSidebaseEslint } from "@sidebase/base-config/eslint";
+
+export default createSidebaseEslint();
+```
+
+```ts
+// prisma.config.ts
+import { applyPrismaDevEnv, buildPrismaConfig } from "@sidebase/base-config/prisma";
+```
+
+`eslint.config.ts` is a scaffold, written once and then owned by your project, so streamctl
+will not rewrite this for you. If you skip it, ESLint fails to load the config because the
+old name no longer exists.
+
+Check for any others:
+
+```sh
+grep -rn "@sidestream-tech/nuxt-config\|createStreamctlEslint" . --exclude-dir=node_modules --exclude=pnpm-lock.yaml
+```
+
+That command should return nothing when you are done.
+
+`pnpm-lock.yaml` is excluded on purpose. It still names the old package until both new
+packages are published and you can regenerate it, so leaving it in would make a correctly
+migrated repository fail its own check. Do not hand-edit the lockfile to make hits go away.
+
+### 6. Decide how you own `pnpm-workspace.yaml`, BEFORE you sync
+
+Do this first. Once sync has adopted the file, the content you need is gone.
+
+`pnpm-workspace.yaml` is managed as a WHOLE FILE, not a block, so adopting it replaces
+everything in it. This step applies to a fresh `streamctl init` just as much as to a
+migration; the only difference is that a fresh repository may have nothing to lose.
+
+Look at what yours currently holds:
+
+```sh
+cat pnpm-workspace.yaml
+```
+
+If the file does not exist, there is nothing to preserve. Skip to step 7 and let sync
+create the managed one. Otherwise take exactly one of the two branches below.
+
+**Branch A: your file declares a real workspace.** That means a `packages:` key with
+entries in it, or an `ignoredBuiltDependencies` key, or any other pnpm setting the payload
+does not render. A real example, from a repository that would have lost its monorepo:
+
+```yaml
+packages:
+  - modules/*
+
+ignoredBuiltDependencies:
+  - puppeteer
+
+onlyBuiltDependencies:
+  - '@parcel/watcher'
+  # ...nine more
+```
+
+Opt the file out entirely:
+
+```ts
+files: { "pnpm-workspace.yaml": "off" },
+```
+
+Do NOT use the `pnpm.onlyBuiltDependencies` knob for this case. The managed file hardcodes
+`packages: []`, so adopting it deletes your workspace definition and every setting the
+payload does not know about, and the knob only carries the build allowlist back. A real
+monorepo that adopts this file stops being a monorepo. Opting out preserves the workspace,
+the ignore lists, and the full build allowlist in one move.
+
+The cost of opting out is that you no longer receive the supply-chain cooldown or any
+future change to this file. If you want the cooldown, copy these into your own file and
+maintain them yourself:
+
+```yaml
+minimumReleaseAge: 10080
+minimumReleaseAgeExclude:
+  - "@sidebase/*"
+```
+
+**Branch B: your file is only an `onlyBuiltDependencies` list.** Adopt the managed file and
+carry your approvals across. `onlyBuiltDependencies` is the allowlist of packages permitted
+to run install lifecycle scripts, and the payload's baseline is just three entries:
+`@prisma/client`, `esbuild`, and `prisma`. Everything else you have is project-specific and
+must be re-added, or it is dropped.
+
+Record the list first:
+
+```sh
+sed -n '/onlyBuiltDependencies:/,/^[^ -]/p' pnpm-workspace.yaml
+```
+
+Then add the non-baseline entries to `streamctl.config.ts`. The knob is additive on top of
+the baseline, so list only the extras:
+
+```ts
+pnpm: {
+  onlyBuiltDependencies: ["@parcel/watcher", "@prisma/engines", "@tailwindcss/oxide", "sharp", "unrs-resolver", "vue-demi"],
+},
+```
+
+Those six are a real example, from a repository that had approved nine and would have been
+left with three. Use the knob rather than `pnpm approve-builds`, which writes straight into
+the managed file and is reverted on the next sync.
+
+**Why this is worth doing before anything else: losing an approval is silent.** Nothing
+warns you. `streamctl check` stays green, the file looks deliberate, and a package whose
+install scripts are blocked still installs.
+
+Be precise about the consequence, because it is narrower than it first appears. The usual
+suspects (`sharp`, `@tailwindcss/oxide`, `unrs-resolver`, `@parcel/watcher`) ship their
+native binary as a prebuilt optional dependency, so on a platform with a prebuild they keep
+working whether or not they are approved, cold install included. Verified across pnpm
+10.28.1, 10.29.1 and 10.29.3. Where the loss is real:
+
+- architectures with no prebuild, where the binary genuinely has to be compiled
+- packages whose postinstall does essential work that is not a native build
+
+So this is not usually a broken CI on day one. It is an unrequested, unannounced change to
+a config your project owns, whose cost lands later and somewhere else. Re-add the entries.
+
+### 7. Sync, then install
+
+```sh
+pnpm streamctl sync
+pnpm install
+```
+
+**Expect sync to stop the first time, without writing anything.** On any repository
+migrating from `@sidestream-tech/nuxt-config` it reports something like:
+
+```
+  [!]  adoption (4)  pre-existing file(s) streamctl now manages
+      tsconfig.json - pre-existing file streamctl now manages; adopting is expected
+      .dockerignore - pre-existing file streamctl now manages; adopting is expected
+      pnpm-workspace.yaml - pre-existing file streamctl now manages; adopting is expected
+      Dockerfile - pre-existing file streamctl now manages; adopting is expected
+      -> `sync --interactive` to adopt per file, `sync --force` to take ownership, or `--only <glob>` to scope
+
+4 conflict(s) pending; see the per-kind guidance above.
+```
+
+This is not a failure and it is not something to route around. A fully-managed file whose
+on-disk content differs from what the payload would write becomes an adoption conflict, and
+the managed content changed substantially between the old payload and this one, so every
+migrating repository hits it. The stop is the CLI refusing to overwrite files it has not
+been told it owns.
+
+Resolve it deliberately, in this order:
+
+1. Finish step 6 first if you have not. `pnpm-workspace.yaml` is in that conflict list, and
+   adopting it is exactly what discards your build approvals, or your whole workspace
+   definition if you are a monorepo. If you took branch A and opted the file out, it will
+   not appear in the conflict list at all.
+2. Adopt. Only `--interactive` and `--force` actually resolve a conflict; without one of
+   them the command repeats the same message and writes nothing.
+   - `pnpm streamctl sync --interactive` walks the files one at a time. Best if you are not
+     sure what your repository has customised.
+   - `pnpm streamctl sync --force` takes ownership of all of them at once. Only reach for
+     this once you have read what it will overwrite, because it is what silently replaces
+     your `onlyBuiltDependencies` list, and your `packages:` entries with it.
+   - `--only <glob>` scopes WHICH files are considered; it does not adopt anything by
+     itself. Combine it with `--force` to take one file at a time and read each diff
+     separately, which is the reviewable middle ground if you have no terminal for
+     `--interactive`:
+
+     ```sh
+     pnpm streamctl sync --force --only 'Dockerfile'
+     git diff Dockerfile
+     ```
+
+   One more thing `--force` does: it overrides the refusal to sync when streamctl-owned
+   files have uncommitted changes. Commit or stash your work first, so `git diff` after
+   each adoption shows only what sync did.
+3. `pnpm install` afterwards. It is separate and required, because `sync` edits
+   `package.json` but does not install. **Commit the regenerated `pnpm-lock.yaml` with the
+   rest of the migration**, then confirm it is actually usable:
+
+   ```sh
+   pnpm install --frozen-lockfile --ignore-scripts --offline
+   ```
+
+   That is what CI and the managed Dockerfile run. It fails before any network call, so it
+   needs no registry token. A stale lockfile fails here with `ERR_PNPM_OUTDATED_LOCKFILE`
+   (or `ERR_PNPM_LOCKFILE_CONFIG_MISMATCH` if you also changed `pnpm.overrides`), long
+   before anyone sees it in CI.
+
+Expect a large diff regardless: it carries every payload change since the adoption branch
+was cut, including the `scripts.lint` reconcile and the renamed Dockerfile stage. If any
+deploy workflow or compose file builds with `--target pro`, update it to `--target
+production` now, because the final stage was renamed.
+
+Read the diff before committing. The GitHub release notes for the version you pinned say
+what changed and what each change requires of you.
+
+### 8. Reconcile `.editorconfig` by hand
+
+**This is not migration-specific.** It happens to any repository that already has an
+`.editorconfig` when the payload first manages one, including a fresh `streamctl init`. The
+block writer appends its managed block without looking at what is already in the file, so
+whatever was there stays above the block, duplicated or contradicted by it.
+
+Check whether anything at all sits above the managed block:
+
+```sh
+awk '/# BEGIN streamctl MANAGED BLOCK editorconfig/{exit} {print}' .editorconfig \
+  | command grep -qv '^[[:space:]]*\([#;].*\)\?$' && echo AFFECTED || echo clean
+```
+
+Use `command grep`, not bare `grep`. Some shells (and some dotfiles) alias or wrap `grep`
+with a tool that does not preserve `-q` exit codes, and this detector reads that exit code
+as its entire answer. A wrapped `grep` can return `clean` on an affected file, which is the
+same silent miss the step exists to catch.
+
+`clean` means there is nothing to do. `AFFECTED` means which fix you need depends on whether
+your existing settings AGREE with the payload's. Paste this helper, then run it:
+
+```sh
+# Flatten an .editorconfig into "section<TAB>key = value" pairs. Comparing whole
+# lines is not enough: sorting separates a setting from its section header, and a
+# header that also appears in the managed block gets subtracted away, so a value
+# can be reported under the wrong section.
+ec_pairs() {
+  awk '
+    /^[[:space:]]*[#;]/ { next }
+    /^[[:space:]]*$/    { next }
+    /^[[:space:]]*\[/   { s=$0; gsub(/^[[:space:]]+|[[:space:]]+$/,"",s); next }
+                        { l=$0; gsub(/^[[:space:]]+|[[:space:]]+$/,"",l)
+                          print (s==""?"(preamble)":s) "\t" l }
+  ' | sort -u
+}
+
+BLOCK=$(mktemp)
+sed -n '/# BEGIN streamctl MANAGED BLOCK editorconfig/,/# END streamctl MANAGED BLOCK editorconfig/p' \
+  .editorconfig | sed '1d;$d' > "$BLOCK"
+
+# Every setting above the block that the block does not already provide, either
+# under the same section or globally via [*].
+awk -F'\t' 'NR==FNR{star[$0];next} !($2 in star)' \
+  <(ec_pairs < "$BLOCK" | awk -F'\t' '$1=="[*]"{print $2}') \
+  <(comm -23 \
+      <(awk '/# BEGIN streamctl MANAGED BLOCK editorconfig/{exit} {print}' .editorconfig | ec_pairs) \
+      <(ec_pairs < "$BLOCK"))
+```
+
+Every line it prints carries its own section, so there is never any doubt about where a
+setting belongs:
+
+```
+[*.md]	indent_size = 4
+```
+
+Do not test this by counting `root = true`. That key is conventional, not required, and a
+pre-existing file without it still leaves the count at `1` after sync while its settings are
+being silently overridden. The `awk` above the block is deliberate for a related reason: a
+`sed` end-regex is searched from the line AFTER the start, so if the marker lands on line 1
+the range never closes and the whole file is printed. (The `sed` range that extracts the
+block is safe, because `# BEGIN` cannot be the last line of a well-formed file.)
+
+**If it prints nothing, your copy is redundant.** Delete everything ABOVE the
+`# BEGIN streamctl MANAGED BLOCK editorconfig` line, keeping the managed block and anything
+below the `# END` line that your project genuinely owns.
+
+**If it prints anything, do NOT just delete your copy: you would be throwing away a real
+preference.** Recreate each printed line below the `# END` marker, under the section header
+printed beside it, then delete the rest of the pre-block content. Order matters here, and it
+is the whole reason the payload wants project overrides underneath: EditorConfig applies
+later matching sections over earlier ones, so a section below the block wins and a section
+above it loses.
+
+A repository with `indent_size = 4` above the block, against the payload's `indent_size = 2`
+inside it, is silently switched to 2. Nothing warns, and the file still contains the 4 you
+wrote, which makes it look intentional. The result should be:
+
+```
+# BEGIN streamctl MANAGED BLOCK editorconfig
+...payload settings, including indent_size = 2...
+# END streamctl MANAGED BLOCK editorconfig
+
+[*]
+indent_size = 4
+```
+
+Either way, finish by re-running the `AFFECTED`/`clean` detector above. It should now say
+`clean`.
+
+**Also check your pre-adoption `.editorconfig`, not only the current one.** If this
+repository already synced the payload at some earlier version, and that version managed
+`.editorconfig` with the `full` strategy rather than `block`, your settings were replaced
+wholesale instead of being left above the block. The detector then reports `clean` while a
+preference is already gone, because the current file no longer contains the evidence. Run
+the same comparison against the version from before the first sync:
+
+```sh
+git show origin/main:.editorconfig > /tmp/ec-before   # or the commit before your first sync
+awk -F'\t' 'NR==FNR{star[$0];next} !($2 in star)' \
+  <(ec_pairs < .editorconfig | awk -F'\t' '$1=="[*]"{print $2}') \
+  <(comm -23 <(ec_pairs < /tmp/ec-before) <(ec_pairs < .editorconfig))
+```
+
+Note this one compares against the WHOLE current file, not just `$BLOCK`, so it also sees
+the overrides you have already put below `# END`. That makes it self-verifying: it goes
+empty once you have restored everything, whereas a block-only comparison would keep
+reporting your own fix back at you forever.
+
+Anything it prints was lost earlier and should be restored below `# END` the same way. A
+real case: a repository whose old file set `[*.md] indent_size = 4` had it replaced by a
+block that sets only `trim_trailing_whitespace` for `[*.md]`, so its markdown silently
+started following the `[*]` value of 2.
+
+**`streamctl check` exits 0 either way, so it will not catch this for you.** The block
+strategy only inspects its own markers, and the block is present and correct; anything
+outside it is invisible to the check. That is why this is a manual step rather than
+something drift detection reports.
+
+### 9. Clean up what the payload no longer manages
+
+Two different kinds of leftover, with the same cause: streamctl manages by path, so
+anything it managed under an old path or an old payload is simply dropped from the
+managed set rather than removed. `check` reports clean either way, because it only
+inspects paths that are currently managed. Nothing will ever tell you these are there.
+
+#### 9a. The two orphaned workflow files
+
+Do this only if your repository synced the payload before the workflow extensions were
+normalized, which is the case for every adoption branch cut before this release. Check:
+
+```sh
+ls .github/workflows/
+```
+
+If you see `ci.yaml` or `pr-preview-cleanup.yaml` sitting next to `ci.yml` and
+`pr-preview-cleanup.yml`, remove the `.yaml` pair:
+
+```sh
+git rm --ignore-unmatch .github/workflows/ci.yaml .github/workflows/pr-preview-cleanup.yaml
+```
+
+`--ignore-unmatch` matters: the condition above is "either file", but `git rm` is atomic, so
+naming a path that does not exist aborts with `fatal: pathspec ... did not match any files`
+and removes NEITHER. A repository that opted one workflow out, or never enabled preview
+cleanup, would skim that error and keep running both copies of the other.
+
+This is required, not tidying. The payload renamed those two managed files from `.yaml` to
+`.yml`. streamctl manages files by path, so the sync in step 7 wrote the new `.yml` files
+but did NOT delete the old `.yaml` ones: they are simply no longer in the managed set.
+GitHub Actions runs every file in `.github/workflows/`, so if you leave them the
+repository runs BOTH copies. That means duplicate CI on every push, and two
+`pr-preview-cleanup` jobs racing to tear down the same preview environment. The leftover
+copies are also frozen forever, so they never receive later fixes, including security
+updates to pinned action SHAs.
+
+While you are here, if your config opts out of either workflow by its old path, for
+example `files: { ".github/workflows/ci.yaml": "off" }`, re-key it to the `.yml` path.
+An opt-out naming a path that is no longer managed does nothing, so the file you meant to
+suppress would start arriving on the next sync.
+
+#### 9b. Orphaned managed BLOCKS
+
+The same problem in a harder-to-see form. A `block` file keeps its markers after the
+payload stops managing that path, so the block sits there forever: never updated, never
+reported, and indistinguishable from a block that is still live. The two `.yaml`
+workflows above are the known orphaned FILES for this release; orphaned blocks are not
+enumerable in advance, because they depend on which payload version your repository
+adopted first.
+
+Do not hardcode a list. Ask the repository instead: every file carrying a streamctl
+marker, minus everything the payload currently manages.
+
+```sh
+LC_ALL=C comm -23 \
+  <(git grep -lI "BEGIN streamctl MANAGED BLOCK" -- . | LC_ALL=C sort -u) \
+  <(pnpm streamctl status --json \
+      | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{
+          JSON.parse(s).data.files.forEach(f=>console.log(f.path));});' \
+      | LC_ALL=C sort -u)
+# anything printed is an orphaned block
+```
+
+**Do not add a comment prefix to that marker string.** streamctl picks the comment syntax
+from the file extension, so the same block opens three different ways:
+
+| Extension | Marker |
+| --------- | ------ |
+| `.js`, `.mjs`, `.cjs`, `.ts`, `.mts`, `.cts`, `.json`, `.jsonc`, `.json5` | `// BEGIN streamctl MANAGED BLOCK x` |
+| `.md`, `.markdown`, `.html`, `.htm`, `.vue` | `<!-- BEGIN streamctl MANAGED BLOCK x -->` |
+| everything else (`.editorconfig`, `.gitignore`, `.npmrc`, yaml, toml, ini, sh, Dockerfile) | `# BEGIN streamctl MANAGED BLOCK x` |
+
+Anchoring on `# BEGIN ...`, which is what step 8 above uses because it is specifically
+about `.editorconfig`, silently returns clean for an orphan in any `.md`, `.ts`, `.json`
+or `.vue`. Seeded against a repository with one orphan in each of the three syntaxes:
+
+```
+un-prefixed anchor (correct)   ->  .npmrc, NOTES.md, legacy.ts
+# BEGIN ... (hash-anchored)    ->  .npmrc
+```
+
+Both current block-strategy files are hash-syntax, so the wrong version gives the right
+answer on every repository we have today and fails on the first one nobody has yet. The
+whole point of this step is repositories migrating from OLDER payloads whose block files
+cannot be enumerated.
+
+`status` rather than `sync --dry-run`: it reports the managed set directly, including
+files this repository has disabled with `files: { ... : "off" }` -- a disabled file is
+still managed, and treating it as unmanaged would report it as an orphan. It also writes
+nothing and prints no plan diff.
+
+**Judge this by its OUTPUT, not its exit code.** `streamctl status --help` claims it
+always exits 0; it does not -- it exits 1 when the payload is declared but not installed.
+That state does not arise here, because step 7 installed two steps ago, but do not build
+an `if` around the exit status.
+
+`LC_ALL=C` on **all three** commands, not just the sorts. `comm` validates its input
+against the collation of the locale it is running in, and the default UTF-8 collation
+orders `AGENTS.md` before `.dockerignore` while `C` does the reverse. Mixing them makes
+`comm` emit `file 2 is not in sorted order` and compare two orderings it cannot reconcile.
+
+`git grep` searches tracked files only. That is the right scope here -- an orphaned block
+is by definition pre-existing committed content -- but it means a block in an untracked
+file will not be reported.
+
+**What to do with a hit depends on what the block provides. Do not delete on sight.**
+
+- **The block is still doing a job.** The registry block is the case that actually
+  occurs: a `@sidestream-tech:registry=...` line in `.npmrc` is no longer managed by this
+  payload, but if anything in the repository still resolves from that scope, deleting it
+  breaks `pnpm install` on the next cold run and the failure surfaces in CI rather than
+  here. Check before touching it:
+
+  ```sh
+  if [ ! -f package.json ] || [ ! -f pnpm-lock.yaml ]; then
+    echo "CANNOT TELL - a file this check reads is missing. Keep the block."
+  elif command grep -rn '@sidestream-tech/' package.json pnpm-lock.yaml; then
+    echo "IN USE - keep the block."
+  else
+    echo "UNUSED - safe to delete."
+  fi
+  ```
+
+  **The existence guard is the load-bearing part, not the grep.** A missing
+  `pnpm-lock.yaml` is not evidence that nothing uses the scope; it is evidence that the
+  question cannot be answered yet. Silencing the error with a bare
+  `2>/dev/null` produces empty output and routes straight to "nothing depends on it,
+  delete" -- the one action this section warns against, in exactly the situation that
+  makes the answer unknowable. Missing input must reach the "you cannot tell" branch
+  below, which keeps the block.
+
+  Note which way the unguarded version failed: `grep: pnpm-lock.yaml: No such file or
+  directory` on stderr reads as output, so it produced **keep**. That was wrong for the
+  wrong reason but landed on the safe action. Both states are defects; only one of them
+  breaks an install.
+
+  If you keep it, consider removing the streamctl markers around the block so it reads
+  as the repository's own content, which is now what it is -- the markers are the only
+  thing implying something else maintains it.
+
+- **Nothing depends on it any more.** Delete the block, markers included. If the block
+  was the entire file, delete the file.
+
+- **You cannot tell.** Leave it and note it in the PR. An orphaned block is inert; a
+  wrongly deleted one is a broken install. The asymmetry favours leaving it.
+
+### 10. Verify
+
+```sh
+pnpm streamctl check
+```
+
+Expected:
+
+```
+streamctl check
+
+  [+]  in sync  all managed files match
+
+all clean.
+```
+
+Exit 0. Then confirm the migration actually reconciled, which `check` alone does not tell
+you:
+
+```sh
+grep -E '"(@prisma/client|eslint|jiti|prisma|typescript)"' package.json
+grep -E '"(lint|postinstall)"' package.json
+```
+
+The versions should match the `nuxt-4` baseline in
+`node_modules/@sidebase/base-config/presets/nuxt-app/preset.json`, and `scripts.lint`
+should now be the oxlint-then-eslint command. If `check` says clean but these did not
+move, you are in the silent-failure state described above.
+
+Finally, run the repository's own gates:
+
+```sh
+pnpm lint
+pnpm test
+```
+
+## If you keep a `file:` override after migrating
+
+Step 0 covers removing a dead one. If you deliberately keep a local override, for example to
+test an unreleased payload build, later `streamctl upgrade` runs need `--to <version>`
+explicitly: with an override in place the CLI cannot resolve the latest release from the
+registry and fails with `CONFIG_INVALID` asking for a target. It also refuses if the
+override embeds a version different from the target, so repoint it first.
+
+## Two per-repo escapes
+
+A migrating repository often needs one or both of these. Both go in `streamctl.config.ts`.
+
+**Stop managing one file.**
+
+```ts
+files: { "Dockerfile": "off" },
+```
+
+Use this when the repository genuinely owns a file the payload also manages. The cost is
+total: that file stops receiving every future payload fix, including security ones. Prefer
+the `docker.*` knobs or the `.editorconfig` managed block over opting out, when the change
+you need is only part of a file.
+
+**Keep your own value for one reconciled key.**
+
+```ts
+versionSyncExclude: ["scripts.lint"],
+```
+
+Use this when the repository needs a different value for a specific key. `scripts.lint` is
+the common one, because the reconcile is a plain overwrite with no version floor: every
+sync replaces whatever you have. A repository that runs type-aware linting, for example,
+keeps its own command this way.
+
+## Rollback
+
+Nothing here is destructive if you work on a branch. `sync` rewrites tracked files, so
+`git diff` shows everything it did and `git restore` undoes it. Keep the migration on its
+own branch and its own commit so that if the sync diff turns out to be larger than
+expected, reverting it is one operation rather than an archaeology exercise.