@norskvideo/ctl-dev-kit 0.2.42 → 0.2.44

package/build/ctl-shell.nix

@@ -0,0 +1,110 @@
+# The shared pieces of every ctl product's dev shell. Single-sourced in
+# @norskvideo/ctl-dev-kit (build/ctl-shell.nix), copied verbatim to
+# nix/ctl-shell.nix in each product repo and drift-gated; norsk-ctl's own flake
+# imports this file in place, so ctl and every product get the same browser.
+# A product's flake.nix is its own: it imports this and adds what it alone needs.
+#
+# A plain function rather than a flake input: a flake only sees git-tracked
+# files, so it cannot reach into node_modules, and a private-repo input would
+# need GitHub auth in every shell and CI runner.
+{ pkgs, biome }:
+let
+  # Playwright doc-guide browser. nix-pinned headless Chromium needs a real X
+  # display on a truly headless box (page.fill silently no-ops on plain HTML
+  # inputs; some pages crash the renderer). Ubuntu's apt Xvfb is too old for
+  # Chromium 148's input dispatch — the nix xorg-server works. A product's
+  # scripts/with-display.sh wraps playwright in xvfb-run iff DISPLAY is unset.
+  browserInputs = pkgs.lib.optionals pkgs.stdenv.isLinux [
+    pkgs.chromium
+    pkgs.xvfb-run
+    pkgs.xorg.xorgserver
+  ];
+  # Headless Chromium finds no system fonts on NixOS, so text renders at zero
+  # advance width — invisible, and every toBeVisible() on text times out. Point
+  # fontconfig at a minimal bundled set so glyphs have real metrics.
+  fontsConf = pkgs.makeFontsConf {
+    fontDirectories = [ pkgs.dejavu_fonts pkgs.liberation_ttf ];
+  };
+  browserHook = pkgs.lib.optionalString pkgs.stdenv.isLinux ''
+    export BROWSER_FOR_TESTING=${pkgs.chromium}/bin/chromium
+    export PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
+    export FONTCONFIG_FILE=${fontsConf}
+  '' + pkgs.lib.optionalString pkgs.stdenv.isDarwin ''
+    # nixpkgs has no darwin chromium, so thread the ambient Chrome
+    # through the same variable everything already honours.
+    macos_chrome="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+    if [ -z "''${BROWSER_FOR_TESTING:-}" ] && [ -x "$macos_chrome" ]; then
+      export BROWSER_FOR_TESTING="$macos_chrome"
+      export PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
+    fi
+    unset macos_chrome
+  '';
+
+  buildTools = [
+    biome
+    pkgs.bun
+    pkgs.nodejs # @biomejs/biome's bin is a JS wrapper, not the binary — it is
+                # what reads BIOME_BINARY and execs the nix build. Something has
+                # to *parse* that wrapper first, so a modern node has to be on
+                # PATH or the host's is used: on an older distro node (Ubuntu
+                # noble ships v12) `bun run lint` dies on the wrapper's optional
+                # chaining before biome ever starts.
+    pkgs.cargo # builds the native product-signer addon (probe/native)
+    pkgs.rustc
+    pkgs.git
+    pkgs.ffmpeg # integration suites spawn a local ffmpeg (e.g. SRT egress capture)
+    pkgs.imagemagick # doc-guide manual assembly shells out to `magick` to embed captures
+    pkgs.gh # publish-docs uploads the built manual via `gh release`; runners have no system gh
+  ];
+
+  # The released norsk-ctl daemon, pinned by version + per-platform hash in the
+  # repo's own flake.nix (the nightly bumps it there). It is NOT built from
+  # source: a product dev consumes the shipped ctl exactly as a customer does.
+  mkCtl = { version, asset, base ? "https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl" }:
+    pkgs.stdenv.mkDerivation {
+      pname = "norsk-ctl";
+      inherit version;
+      src = pkgs.fetchurl {
+        url = "${base}/${version}/norsk-ctl-${version}-${asset.plat}";
+        hash = asset.hash;
+      };
+      dontUnpack = true;
+      # bun single-file executables embed a trailing payload; stripping
+      # corrupts them, and on Linux the raw binary needs its interpreter +
+      # libstdc++ rpath patched to the nix store.
+      dontStrip = true;
+      nativeBuildInputs = pkgs.lib.optionals pkgs.stdenv.isLinux [ pkgs.autoPatchelfHook ];
+      buildInputs = pkgs.lib.optionals pkgs.stdenv.isLinux [ pkgs.stdenv.cc.cc.lib ];
+      installPhase = ''
+        runHook preInstall
+        install -Dm755 "$src" "$out/bin/norsk-ctl"
+        runHook postInstall
+      '';
+    };
+
+  # Biome from its own pin so `bun run lint` works on NixOS: the node_modules
+  # @biomejs/biome binary is glibc-linked and can't run there. Each shell
+  # exports BIOME_BINARY so the npm wrapper execs this nix build instead.
+  shell = buildInputs: shellHook: pkgs.mkShell {
+    BIOME_BINARY = "${biome}/bin/biome";
+    inherit buildInputs shellHook;
+  };
+in
+{
+  inherit browserInputs browserHook buildTools mkCtl shell;
+
+  # The Studio-product shells:
+  #   default / dev -> build tools + the pinned norsk-ctl daemon on PATH
+  #   build         -> build tools only; what CI (build-image / integration)
+  #                    uses, so image builds never depend on the ctl channel.
+  mkProductShells = { ctl, extraInputs ? [ ], extraShellHook ? "" }:
+    let
+      inputs = buildTools ++ browserInputs ++ extraInputs;
+      hook = browserHook + extraShellHook;
+    in
+    {
+      default = shell (inputs ++ [ ctl ]) hook;
+      dev = shell (inputs ++ [ ctl ]) hook;
+      build = shell inputs hook;
+    };
+}

package/build/flake.nix

@@ -1,20 +1,19 @@
-# Product build + dev shell — single-sourced in @norskvideo/ctl-dev-kit and
-# copied verbatim into each split product repo (nix needs a flake.nix at the repo
-# root for `nix develop`; it can't pull one from an npm package at CI bootstrap).
-# The copy is to be drift-gated (Workstream I; not yet enforced), same model as
-# the fenced CLAUDE.md core.
+# This product's build + dev shells. The file is the product's own: add what
+# this product alone needs through mkProductShells' extraInputs /
+# extraShellHook. The shared pieces (build tools, the test browser, biome, the
+# norsk-ctl fetch) come from nix/ctl-shell.nix — a verbatim, drift-gated copy of
+# @norskvideo/ctl-dev-kit build/ctl-shell.nix; edit that in the dev-kit, never
+# the copy. The dev-kit's build/flake.nix is the starter a new product begins
+# from.
 #
 # Three shells:
-#   nix develop         -> build tools (bun, cargo/rustc, git) + the pinned
-#   nix develop .#dev      `norsk-ctl` daemon on PATH. The everyday product dev
-#                          shell; the two are equivalent.
+#   nix develop         -> build tools + the pinned `norsk-ctl` daemon on PATH.
+#   nix develop .#dev      The everyday product dev shell; the two are equivalent.
 #   nix develop .#build -> build tools only, no ctl. What CI (build-image /
 #                          integration) uses, so image builds never depend on the
 #                          ctl binary channel.
 #
-# `norsk-ctl` is the released daemon binary pulled from the S3 channel and pinned
-# by version+hash (reproducible). It is NOT built from source here — a product
-# dev consumes the shipped ctl exactly as a customer does. Bump with:
+# The norsk-ctl pin below is bumped nightly by upgrade-latest; by hand with
 #   packages/dev-kit/build/refresh-ctl-pin.sh        (writes ctlVersion + hashes)
 {
   description = "norsk-ctl product build + dev shell";
@@ -37,7 +36,6 @@
       # --- norsk-ctl channel pin -------------------------------------------
       # The released daemon, one build per platform. Bump these together.
       ctlVersion = "0.1.0-2026-09-15-81bbde8";
-      ctlBase = "https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl";
       ctlAsset = {
         "x86_64-linux"   = { plat = "linux-x64";    hash = "sha256-6Zm1iLs29o89tav+TEDfLLdq2E+blku7DSxZVAqEwF0="; };
         "aarch64-linux"  = { plat = "linux-arm64";  hash = "sha256-ziH0YFLc8j7+xuYWArCU1JzWgq3NsFvfq67FqjlxdI8="; };
@@ -45,108 +43,18 @@
         "x86_64-darwin"  = { plat = "darwin-x64";   hash = "sha256-GzlT0Rg9t8sAG6e7Deu+DzSbfSxcr+WpVmyOgit2Q4g="; };
       };
 
-      mkCtl = system:
-        let
-          pkgs = import nixpkgs { inherit system; };
-          asset = ctlAsset.${system};
-        in
-        pkgs.stdenv.mkDerivation {
-          pname = "norsk-ctl";
-          version = ctlVersion;
-          src = pkgs.fetchurl {
-            url = "${ctlBase}/${ctlVersion}/norsk-ctl-${ctlVersion}-${asset.plat}";
-            hash = asset.hash;
-          };
-          dontUnpack = true;
-          # bun single-file executables embed a trailing payload; stripping
-          # corrupts them, and on Linux the raw binary needs its interpreter +
-          # libstdc++ rpath patched to the nix store.
-          dontStrip = true;
-          nativeBuildInputs = pkgs.lib.optionals pkgs.stdenv.isLinux [ pkgs.autoPatchelfHook ];
-          buildInputs = pkgs.lib.optionals pkgs.stdenv.isLinux [ pkgs.stdenv.cc.cc.lib ];
-          installPhase = ''
-            runHook preInstall
-            install -Dm755 "$src" "$out/bin/norsk-ctl"
-            runHook postInstall
-          '';
-        };
+      ctlShell = system: import ./nix/ctl-shell.nix {
+        pkgs = import nixpkgs { inherit system; };
+        biome = (import nixpkgs-biome { inherit system; }).biome;
+      };
     in {
       packages = forAllSystems (system: {
-        norsk-ctl = mkCtl system;
+        norsk-ctl = (ctlShell system).mkCtl { version = ctlVersion; asset = ctlAsset.${system}; };
       });
 
       devShells = forAllSystems (system:
-        let
-          pkgs = import nixpkgs { inherit system; };
-          # Biome from its own pin so `bun run lint` works on NixOS: the
-          # node_modules @biomejs/biome binary is glibc-linked and can't run
-          # here. Each shell exports BIOME_BINARY so the npm wrapper execs this
-          # nix build instead -- no patchelf, no per-command env var. Keep the
-          # pin in step with package.json's @biomejs/biome version.
-          biome = (import nixpkgs-biome { inherit system; }).biome;
-          buildTools = [
-            biome
-            pkgs.bun
-            pkgs.nodejs # @biomejs/biome's bin is a JS wrapper, not the binary —
-                        # it is what reads BIOME_BINARY below and execs the nix
-                        # build. Something has to *parse* that wrapper first, so a
-                        # modern node has to be on PATH or the host's is used: on
-                        # an older distro node (Ubuntu noble ships v12) `bun run
-                        # lint` dies on the wrapper's optional chaining before
-                        # biome ever starts. norsk-ctl carries nodejs for kubb and
-                        # so never hit this; the split-out products had nothing
-                        # putting node in the shell.
-            pkgs.cargo # builds the native product-signer addon (probe/native)
-            pkgs.rustc
-            pkgs.git
-            pkgs.ffmpeg # integration suites spawn a local ffmpeg (e.g. SRT egress capture)
-            pkgs.imagemagick # doc-guide manual assembly shells out to `magick` to embed captures
-            pkgs.gh # publish-docs uploads the built manual via `gh release`; runners have no system gh
-          ];
-
-          # Playwright doc-guide browser. nix-pinned headless Chromium needs a
-          # real X display on a truly headless box (page.fill silently no-ops on
-          # plain HTML inputs; some pages crash the renderer). Ubuntu's apt Xvfb
-          # is too old for Chromium 148's input dispatch — the nix xorg-server
-          # works. A product's scripts/with-display.sh wraps playwright in
-          # xvfb-run iff DISPLAY is unset.
-          linuxBrowser = pkgs.lib.optionals pkgs.stdenv.isLinux [
-            pkgs.chromium
-            pkgs.xvfb-run
-            pkgs.xorg.xorgserver
-          ];
-          # Headless Chromium finds no system fonts on NixOS, so text renders at
-          # zero advance width — invisible, and every toBeVisible() on text times
-          # out. Point fontconfig at a minimal bundled set so glyphs have real
-          # metrics.
-          fontsConf = pkgs.makeFontsConf {
-            fontDirectories = [ pkgs.dejavu_fonts pkgs.liberation_ttf ];
-          };
-          browserHook = pkgs.lib.optionalString pkgs.stdenv.isLinux ''
-            export BROWSER_FOR_TESTING=${pkgs.chromium}/bin/chromium
-            export PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
-            export FONTCONFIG_FILE=${fontsConf}
-          '';
-        in {
-          # Everyday dev shell — build tools + the pinned norsk-ctl daemon.
-          # `nix develop` and `nix develop .#dev` are equivalent.
-          default = pkgs.mkShell {
-            BIOME_BINARY = "${biome}/bin/biome";
-            buildInputs = buildTools ++ linuxBrowser ++ [ (mkCtl system) ];
-            shellHook = browserHook;
-          };
-          dev = pkgs.mkShell {
-            BIOME_BINARY = "${biome}/bin/biome";
-            buildInputs = buildTools ++ linuxBrowser ++ [ (mkCtl system) ];
-            shellHook = browserHook;
-          };
-          # Lean shell for CI (build-image / integration) — no ctl fetch, so
-          # image builds never depend on the ctl binary channel.
-          build = pkgs.mkShell {
-            BIOME_BINARY = "${biome}/bin/biome";
-            buildInputs = buildTools ++ linuxBrowser;
-            shellHook = browserHook;
-          };
+        (ctlShell system).mkProductShells {
+          ctl = self.packages.${system}.norsk-ctl;
         });
     };
 }

package/build/flake.sdk-app.nix

@@ -1,17 +1,15 @@
 {
   # Dev shell for a ctl "sdk-app" product — a bespoke Norsk SDK application
   # (its runtime is its own daemon, not a composed Studio workflow launched by
-  # norsk-ctl). Single-sourced in @norskvideo/ctl-dev-kit (build/flake.sdk-app.nix)
-  # and copied verbatim into each sdk-app product repo (nix needs a flake.nix at
-  # the repo root for `nix develop`; it can't pull one from an npm package at CI
-  # bootstrap). Drift-gated for products whose package.json declares
-  # `"ctlProduct": { "shape": "sdk-app" }`.
+  # norsk-ctl). The file is the product's own; the dev-kit's
+  # build/flake.sdk-app.nix is the starter a new sdk-app begins from. The shared
+  # pieces (the test browser, biome) come from nix/ctl-shell.nix — a verbatim,
+  # drift-gated copy of @norskvideo/ctl-dev-kit build/ctl-shell.nix.
   #
-  # Unlike the Studio-product flake (build/flake.nix) this does NOT fetch the
-  # norsk-ctl daemon — an sdk-app's dev loop is its own SDK app plus a Norsk
-  # engine, not a ctl-launched product container. Decision: bun for tooling
-  # (install / build / test), Node for the shipped runtime (the SDK's blessed
-  # runtime).
+  # Unlike the Studio-product flake this does NOT fetch the norsk-ctl daemon —
+  # an sdk-app's dev loop is its own SDK app plus a Norsk engine, not a
+  # ctl-launched product container. Decision: bun for tooling (install / build /
+  # test), Node for the shipped runtime (the SDK's blessed runtime).
   #
   # nixpkgs is pinned to the same rev the Studio flake uses, so bun matches the
   # fleet's 1.3.13.
@@ -39,25 +37,20 @@
             config.allowUnfree = true;
           };
           biome = (import nixpkgs-biome { inherit system; }).biome;
+          ctlShell = import ./nix/ctl-shell.nix { inherit pkgs biome; };
           ffmpegFull = pkgs.ffmpeg-full;
           tools = [
-            biome # `bun run lint` execs this via BIOME_BINARY (see below)
+            biome # `bun run lint` execs this via BIOME_BINARY
             pkgs.bun # tooling: install / build / test (fleet parity, dev-kit)
             pkgs.nodejs # the shipped runtime (bin/run -> node lib/index.js); also
                         # parses @biomejs/biome's JS wrapper that reads BIOME_BINARY
             pkgs.git
             ffmpegFull # integration suites spawn a local ffmpeg (e.g. SRT egress capture)
-          ] ++ pkgs.lib.optionals pkgs.stdenv.isLinux [ pkgs.chromium ];
-          shell = pkgs.mkShell {
-            BIOME_BINARY = "${biome}/bin/biome";
-            buildInputs = tools;
-            shellHook = ''
-              export NIXPKGS_ALLOW_UNFREE=1
-              export FFMPEG_FULL=${ffmpegFull}
-            '' + pkgs.lib.optionalString pkgs.stdenv.isLinux ''
-              export BROWSER_FOR_TESTING=${pkgs.chromium}/bin/chromium
-            '';
-          };
+          ] ++ ctlShell.browserInputs;
+          shell = ctlShell.shell tools (''
+            export NIXPKGS_ALLOW_UNFREE=1
+            export FFMPEG_FULL=${ffmpegFull}
+          '' + ctlShell.browserHook);
         in {
           # One shell under every name the canonical workflows and the Studio
           # flake use: `build` is what CI enters (`nix develop .#build`). An

package/build/refresh-ctl-pin.sh

@@ -36,4 +36,4 @@ done
 
 perl -0pi -e "s{(ctlVersion = \")[^\"]*(\")}{\${1}$ver\${2}}" "$flake"
 echo "updated $flake"
-echo "next: copy this flake.nix into each split product repo root (or re-run the split)"
+echo "this is the starter's pin; each product's own flake.nix is bumped nightly by upgrade-latest"

package/conventions/CLAUDE.core.md

@@ -81,7 +81,7 @@
   stale until this loop re-runs; don't debug a ghost.
 - **The shared CI workflow is single-sourced too.** `.github/workflows/upgrade-latest.yml`
   is copied verbatim from `@norskvideo/ctl-dev-kit` (`conventions/upgrade-latest.yml`),
-  same as this core block and `flake.nix`; `check:drift` fails CI if a copy
+  same as this core block and `nix/ctl-shell.nix`; `check:drift` fails CI if a copy
   diverges. Only the `product:` key is per-repo. Never hand-edit the copy — edit
   the dev-kit source and re-sync.
 - **A config-driven workflow needs a parity-checked invariant contract.** If this

package/conventions/build-image.yml

@@ -289,6 +289,12 @@ jobs:
   gate-guides:
     needs: label
     runs-on: x64
+    # One guide run per repo at a time, nightly and publish gate alike: both
+    # launch the same instance ids on the x64 pool's shared docker daemon, and
+    # ctl names each compose project after its instance id. Queue, never cancel.
+    concurrency:
+      group: doc-guides-${{ github.repository }}
+      cancel-in-progress: false
     outputs:
       guides: ${{ steps.plan.outputs.guides }}
       reason: ${{ steps.plan.outputs.reason }}

package/conventions/check-drift.ts

@@ -1,11 +1,12 @@
 // Workstream I drift gate. Fails a product repo whose forced copies of the
 // shared conventions have diverged from this dev-kit's canonical source. Each
 // gated file uses the loosest mechanism that still pins what is shared:
-//   - byte-verbatim: CLAUDE.md fenced core, flake.nix, biome.json,
+//   - byte-verbatim: CLAUDE.md fenced core, nix/ctl-shell.nix, biome.json,
 //     tsconfig.base.json, the .gitignore core block, scripts/demo (only a
 //     product with tests/demo.spec.ts is asked for it)
 //   - masked per-repo line: checks.yml + upgrade-latest.yml (`product:` key)
 //   - base + sanctioned extension block: dprint.json (repo-specific excludes)
+//   - must import the shared module: flake.nix (otherwise the product's own)
 //   - structural: root tsconfig.json (shape-dependent includes stay free),
 //     deployment/build-image.sh (per-product wrapper around a verbatim
 //     bootstrap), manifest.seed.json (per-product pins, SDK-schema shape)
@@ -103,19 +104,19 @@ function workflowProblem(
 }
 
 // The dev-only ctl pin the nightly bumps in each repo's flake: the version
-// string and the four per-platform source hashes. CI downloads ctl directly, so
-// this pin only feeds the dev flake; it floats per repo and over time and is NOT
-// a shared convention. Mask it so the gate compares flake STRUCTURE, not the pin
-// — same idea as masking upgrade-latest's product: line.
+// string and the four per-platform source hashes. It lives in the product's own
+// flake.nix; sync-drift carries it across when it migrates a legacy flake.
 export const CTL_VERSION_LINE = /ctlVersion = "[^"]*";/;
 export const CTL_HASH_LINE = /hash = "sha256-[^"]*";/g;
 
-function flakeProblem(actual: string, canonical: string, canonicalRef = "build/flake.nix"): string | undefined {
-  const mask = (s: string) =>
-    s.replace(CTL_VERSION_LINE, 'ctlVersion = "__CTL__";').replace(CTL_HASH_LINE, 'hash = "sha256-__HASH__";');
-  const [ma, mc] = [mask(actual), mask(canonical)];
-  if (ma === mc) return undefined;
-  return `flake.nix has drifted from @norskvideo/ctl-dev-kit ${canonicalRef} (${firstDiffLine(ma, mc)}). ${RESYNC}`;
+// The shared dev-shell module and how a product's flake.nix must reach it. The
+// flake is otherwise the product's own, so a product can add what it alone
+// needs; building from the module is what keeps the shared pieces shared.
+export const CTL_SHELL_PATH = "nix/ctl-shell.nix";
+export const CTL_SHELL_IMPORT = "import ./nix/ctl-shell.nix";
+
+export function importsCtlShell(flake: string): boolean {
+  return flake.includes(CTL_SHELL_IMPORT);
 }
 
 // dprint.json is canonical-plus-extension: the shared config is verbatim, but a
@@ -250,7 +251,13 @@ function coreProblem(claude: string, canonicalCore: string): string | undefined
 
 export interface CanonicalBytes {
   core: string;
+  /** build/flake.nix — the starter flake a Studio product begins from, and what
+   *  sync-drift migrates a legacy verbatim flake to. Not gated: the flake is the
+   *  product's own. */
   flake: string;
+  /** build/ctl-shell.nix — the shared dev-shell module, gated verbatim at
+   *  nix/ctl-shell.nix for every shape. */
+  ctlShell: string;
   upgradeLatest: string;
   syncDevKit: string;
   /** conventions/sync-ctl-packages.yml — the ctl-* pin freshness PR. No per-repo
@@ -281,10 +288,10 @@ export interface CanonicalBytes {
    *  hand copy is how build-docs.yml came to fail in both turnkeys, which never
    *  made one. */
   withDisplay: string;
-  /** build/flake.sdk-app.nix — the flake canonical for a `shape: "sdk-app"`
+  /** build/flake.sdk-app.nix — the starter flake for a `shape: "sdk-app"`
    *  product (bun tooling + node runtime, no norsk-ctl daemon fetch). Optional so
-   *  a studio-only caller (and the existing test fixtures) need not supply it;
-   *  required when a repo declares the sdk-app shape. */
+   *  a studio-only caller need not supply it; sync-drift needs it to migrate a
+   *  legacy sdk-app flake. */
   flakeSdkApp?: string;
   /** conventions/checks.sdk-app.yml — the checks.yml variant for an sdk-app: the
    *  Studio licence step removed (it reads shared/src/version.ts +
@@ -530,21 +537,16 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
     push(coreProblem(readFileSync(claudePath, "utf8"), canonical.core));
   }
 
-  // flake.nix is shape-selected: the studio flake fetches the norsk-ctl daemon,
-  // the sdk-app flake does not. Both are gated the same way (ctl pins masked; the
-  // sdk-app flake carries none, so it is effectively byte-verbatim).
+  push(verbatimProblem(repoRoot, CTL_SHELL_PATH, "build/ctl-shell.nix", canonical.ctlShell));
   const flakePath = join(repoRoot, "flake.nix");
-  const flakeCanon = shape === "sdk-app" ? canonical.flakeSdkApp : canonical.flake;
-  const flakeRef = shape === "sdk-app" ? "build/flake.sdk-app.nix" : "build/flake.nix";
-  if (flakeCanon === undefined) {
-    throw new Error(`checkDrift: shape "${shape}" requires canonical.${shape === "sdk-app" ? "flakeSdkApp" : "flake"}`);
-  } else if (!existsSync(flakePath)) {
+  if (!existsSync(flakePath)) {
     problems.push(
-      `flake.nix not found at repo root (${flakePath}). It is copied verbatim from @norskvideo/ctl-dev-kit ${flakeRef}.`,
+      `flake.nix not found at repo root (${flakePath}). Start from @norskvideo/ctl-dev-kit ${shape === "sdk-app" ? "build/flake.sdk-app.nix" : "build/flake.nix"}.`,
+    );
+  } else if (!importsCtlShell(readFileSync(flakePath, "utf8"))) {
+    problems.push(
+      `flake.nix does not build its shells from ${CTL_SHELL_PATH} (no \`${CTL_SHELL_IMPORT}\`). The shared shell pieces are single-sourced there; sync-drift migrates a legacy verbatim flake.`,
     );
-  } else {
-    const problem = flakeProblem(readFileSync(flakePath, "utf8"), flakeCanon, flakeRef);
-    if (problem) problems.push(problem);
   }
   push(verbatimProblem(repoRoot, "biome.json", "conventions/biome.base.json", canonical.biome));
   push(verbatimProblem(repoRoot, "tsconfig.base.json", "conventions/tsconfig.base.json", canonical.tsconfigBase));
@@ -810,6 +812,7 @@ if (import.meta.main) {
   const canonical: CanonicalBytes = {
     core: readFileSync(join(import.meta.dir, "CLAUDE.core.md"), "utf8"),
     flake: readFileSync(join(import.meta.dir, "..", "build", "flake.nix"), "utf8"),
+    ctlShell: readFileSync(join(import.meta.dir, "..", "build", "ctl-shell.nix"), "utf8"),
     upgradeLatest: readFileSync(join(import.meta.dir, "upgrade-latest.yml"), "utf8"),
     syncDevKit: readFileSync(join(import.meta.dir, "sync-dev-kit.yml"), "utf8"),
     syncCtlPackages: readFileSync(join(import.meta.dir, "sync-ctl-packages.yml"), "utf8"),

package/conventions/checks.sdk-app.yml

@@ -8,7 +8,7 @@
 # Two jobs:
 #   - drift: the RFC 0001 Workstream I shared-conventions drift-check. Fails if
 #     this repo's forced copies have diverged from the pinned dev-kit — the
-#     fenced CLAUDE.md core, flake.nix, the shared config files, the manifest
+#     fenced CLAUDE.md core, nix/ctl-shell.nix, the shared config files, the manifest
 #     seed. Copies exist so a human reads them on GitHub with no tooling; the
 #     gate is the only thing keeping them true.
 #   - quality: the repo's own lint + typecheck + unit tests + docs path lint,

package/conventions/checks.yml

@@ -4,7 +4,7 @@
 # Two jobs:
 #   - drift: the RFC 0001 Workstream I shared-conventions drift-check. Fails if
 #     this repo's forced copies have diverged from the pinned dev-kit — the
-#     fenced CLAUDE.md core, flake.nix, the shared config files, the manifest
+#     fenced CLAUDE.md core, nix/ctl-shell.nix, the shared config files, the manifest
 #     seed. Copies exist so a human reads them on GitHub with no tooling; the
 #     gate is the only thing keeping them true.
 #   - quality: the repo's own lint + typecheck + unit tests + docs path lint,

package/conventions/publish-docs.yml

@@ -46,6 +46,12 @@ concurrency:
 jobs:
   publish:
     runs-on: x64
+    # One guide run per repo at a time, nightly and publish gate alike: both
+    # launch the same instance ids on the x64 pool's shared docker daemon, and
+    # ctl names each compose project after its instance id. Queue, never cancel.
+    concurrency:
+      group: doc-guides-${{ github.repository }}
+      cancel-in-progress: false
     steps:
       # Runs BEFORE checkout, and does two things: points the harness's temp base
       # out of the workspace for every later step in this job, and clears whatever

package/conventions/sync-dev-kit.yml

@@ -1,6 +1,6 @@
 # Keep this product's shared conventions fresh against @norskvideo/ctl-dev-kit.
 # The dev-kit single-sources the files every ctl product would otherwise
-# copy-and-drift (the fenced CLAUDE.md core, flake.nix, the biome/tsconfig/dprint
+# copy-and-drift (the fenced CLAUDE.md core, nix/ctl-shell.nix, the biome/tsconfig/dprint
 # bases, the shared workflows, the build bootstrap). check:drift fails CI when a
 # copy diverges from the *installed* dev-kit — so a product goes stale two ways:
 # its pin lags the newest published dev-kit, and once the pin bumps its copies
@@ -19,7 +19,7 @@
 #
 # sync-drift re-derives each copy from the canonical (never a second opinion that
 # can disagree), preserving the per-repo bits the gate masks -- the product: keys,
-# the flake ctl pin, the dprint/gitignore/CLAUDE repo content. The gate runs AFTER
+# the product's own flake.nix, the dprint/gitignore/CLAUDE repo content. The gate runs AFTER
 # it, so a bad rewrite fails check:drift and a breaking convention fails the build,
 # rather than landing silently. Structural per-repo files it never touches.
 #

package/conventions/sync-drift.ts

@@ -8,7 +8,8 @@
 // judgement anywhere:
 //   - verbatim (biome.json, tsconfig.base.json)      -> overwrite with canonical
 //   - masked workflows (checks / upgrade / sync)     -> canonical, repo's product: key kept
-//   - flake.nix                                      -> canonical, repo's floating ctl pin kept
+//   - nix/ctl-shell.nix                              -> overwrite with canonical (created if absent)
+//   - flake.nix (legacy verbatim copy only)          -> the starter, repo's floating ctl pin kept
 //   - marker-block (CLAUDE core, dprint, .gitignore) -> replace the shared block, keep the rest
 // Structural per-repo files (root tsconfig.json, deployment/build-image.sh,
 // manifest.seed.json) have NO canonical bytes to apply — the gate checks their
@@ -25,6 +26,7 @@ import {
   BEGIN,
   type CanonicalBytes,
   CTL_HASH_LINE,
+  CTL_SHELL_PATH,
   CTL_VERSION_LINE,
   carriesIntegrationMarker,
   DOCS_SITE_DIR,
@@ -32,6 +34,7 @@ import {
   GITIGNORE_BEGIN,
   GITIGNORE_END,
   hasDocsSite,
+  importsCtlShell,
   PRODUCT_LINE,
   PRODUCT_SENTINEL,
   type ProductShape,
@@ -149,21 +152,22 @@ function syncIntegration(repoRoot: string, canonical: string, r: SyncReport): vo
   writeIfChanged(path, out, rel, r.written);
 }
 
-// flake.nix is verbatim except the dev-only ctl pin (ctlVersion + the four
-// per-platform hashes), which floats per repo. Re-emit canonical STRUCTURE with
-// the repo's pin restored in order — so a structural edit (e.g. a stray comment)
-// is replaced while the pin is kept. Structure is identical across repos, so the
-// Nth hash line in canonical maps to the Nth in the repo.
-function syncFlake(repoRoot: string, canonical: string, r: SyncReport): void {
+// flake.nix is the product's own once it builds from nix/ctl-shell.nix, so sync
+// leaves it alone. One that does not can only be a verbatim dev-kit copy from
+// before the shared pieces moved into the module (the gate allowed no product
+// edits then), so it is replaced by the starter with the repo's floating ctl pin
+// (ctlVersion + the four per-platform hashes) carried across in order.
+function syncFlake(repoRoot: string, starter: string, r: SyncReport): void {
   const path = join(repoRoot, "flake.nix");
   if (!existsSync(path)) {
     r.skipped.push("flake.nix (absent)");
     return;
   }
   const existing = readFileSync(path, "utf8");
+  if (importsCtlShell(existing)) return;
   const version = existing.match(CTL_VERSION_LINE)?.[0];
   const hashes = existing.match(CTL_HASH_LINE) ?? [];
-  let out = version ? canonical.replace(CTL_VERSION_LINE, version) : canonical;
+  let out = version ? starter.replace(CTL_VERSION_LINE, version) : starter;
   let i = 0;
   out = out.replace(CTL_HASH_LINE, (m) => hashes[i++] ?? m);
   writeIfChanged(path, out, "flake.nix", r.written);
@@ -336,6 +340,8 @@ export function syncDrift(repoRoot: string, canonical: CanonicalBytes, shape: Pr
     writeIfChanged(join(repoRoot, buildDocsRel), canonical.buildDocs, buildDocsRel, r.written);
   }
 
+  mkdirSync(dirname(join(repoRoot, CTL_SHELL_PATH)), { recursive: true });
+  writeIfChanged(join(repoRoot, CTL_SHELL_PATH), canonical.ctlShell, CTL_SHELL_PATH, r.written);
   syncFlake(repoRoot, flakeCanon, r);
   syncClaude(repoRoot, canonical.core, r);
   syncGitignore(repoRoot, canonical.gitignoreCore, r);
@@ -353,6 +359,7 @@ if (import.meta.main) {
   const canonical: CanonicalBytes = {
     core: readFileSync(join(dir, "CLAUDE.core.md"), "utf8"),
     flake: readFileSync(join(dir, "..", "build", "flake.nix"), "utf8"),
+    ctlShell: readFileSync(join(dir, "..", "build", "ctl-shell.nix"), "utf8"),
     upgradeLatest: readFileSync(join(dir, "upgrade-latest.yml"), "utf8"),
     syncDevKit: readFileSync(join(dir, "sync-dev-kit.yml"), "utf8"),
     syncCtlPackages: readFileSync(join(dir, "sync-ctl-packages.yml"), "utf8"),

package/create-product/canon.ts

@@ -15,6 +15,8 @@ const buildDir = join(import.meta.dir, "..", "build");
 export interface Canon {
   core: string;
   flake: string;
+  /** build/ctl-shell.nix, emitted as nix/ctl-shell.nix — the flake imports it. */
+  ctlShell: string;
   flakeLock: string;
   upgradeLatest: string;
   syncDevKit: string;
@@ -41,6 +43,7 @@ export function loadCanon(): Canon {
   return {
     core: readFileSync(join(conventionsDir, "CLAUDE.core.md"), "utf8"),
     flake: readFileSync(join(buildDir, "flake.nix"), "utf8"),
+    ctlShell: readFileSync(join(buildDir, "ctl-shell.nix"), "utf8"),
     flakeLock: readFileSync(join(buildDir, "flake.lock"), "utf8"),
     upgradeLatest: readFileSync(join(conventionsDir, "upgrade-latest.yml"), "utf8"),
     syncDevKit: readFileSync(join(conventionsDir, "sync-dev-kit.yml"), "utf8"),

package/create-product/create-product.ts

@@ -203,6 +203,7 @@ function conventionFiles(ctx: ShapeContext, shape: ShapeModule): GeneratedFile[]
   return [
     { path: "CLAUDE.md", content: `${shape.claudeHead(ctx)}\n${canon.core}\n${shape.claudeTail(ctx)}` },
     { path: "flake.nix", content: canon.flake },
+    { path: "nix/ctl-shell.nix", content: canon.ctlShell },
     { path: "flake.lock", content: canon.flakeLock },
     { path: "biome.json", content: canon.biome },
     { path: "tsconfig.base.json", content: canon.tsconfigBase },

package/local-dev/README.md

@@ -9,7 +9,8 @@ test. This is the whole point of the split — you clone the product and go.
 
 `norsk-ctl` (the daemon + CLI that launches product instances) is **not** an npm
 dependency; it is the released binary, pinned by version+hash in the repo's
-`flake.nix` (single-sourced from `@norskvideo/ctl-dev-kit`). The dev shell puts
+`flake.nix` (the shared shell pieces come from `nix/ctl-shell.nix`, single-sourced
+from `@norskvideo/ctl-dev-kit`). The dev shell puts
 it on `PATH`:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.42",
+  "version": "0.2.44",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",