@@ -1,37 +1,24 @@
-// Decides which CI jobs a change needs. Prints `key=value` lines for
-// $GITHUB_OUTPUT; a job runs unless its key is "false".
-//
-//   node ci-changes.cjs --paths <file>          gate by the listed paths
-//   node ci-changes.cjs --paths <file> --full   run every Linux job, gate only the macOS lint
-//   node ci-changes.cjs                         changed paths unknown: run everything
-//
-// scripts/check-changed.ts requires the same decisions so local runs match CI.
-//
-// Every changed path maps to workspace packages, which then pull in their
-// dependents from package.json. A path this file does not recognize runs
-// everything, so a new root file or directory can only cost minutes.
+// Unknown paths run every job; recognized packages pull in their dependents.
+// scripts/check-changed.ts shares these decisions so local checks match CI.
 const fs = require("node:fs");
 const path = require("node:path");
 
 const root = path.resolve(__dirname, "../..");
 
-// Never read by a build, typecheck, or test. Lint still formats them.
 const INERT = [
   /^docs\//,
   /^\.(agents|cursor|vscode|devcontainer|macroscope|repos)\//,
   /^[^/]+\.md$/,
   /^LICENSE$/,
 ];
 
-// Run everything: the root vite.config.ts loads the first as setup for every
-// package's tests, and the vendored mobile tarballs are installed dependencies.
+// Shared test setup and vendored mobile dependencies affect every package.
 const RUNS_EVERYTHING = [
   /^packages\/shared\/src\/(HostProcess|testing\/longTempDir)\.ts$/,
   /^apps\/mobile\/deps\//,
 ];
 
-// Paths outside a package, or files inside one that other packages read
-// through relative imports rather than a package.json dependency.
+// Includes cross-package reads absent from package.json dependencies.
 const EXTRA_OWNERS = [
   // Vite configs and tsconfigs of these apps import scripts/lib directly.
   [/^scripts\/lib\//, ["@t3tools/desktop", "@t3tools/mobile", "@t3tools/web", "t3"]],
@@ -43,9 +30,7 @@ const EXTRA_OWNERS = [
 ];
 const RUST = /^native\/(resource-monitor|kde-snap-shot|hyprland-snap-shot)\//;
 
-// Tests that read another package's files without declaring it. The scripts
-// tests read app manifests, assets, and sources (cursor-sdk-packaging,
-// third-party-licenses, brand-assets, build-desktop-artifact).
+// These tests read other packages without declaring dependencies.
 const TEST_ONLY_DEPS = {
   "@t3tools/provider-pi": ["@t3tools/client-runtime"],
   "@t3tools/scripts": [
@@ -56,17 +41,12 @@ const TEST_ONLY_DEPS = {
     "@t3tools/provider-cursor",
   ],
 };
-// Declared dependencies that only feed a build step: the server bundles the
-// built web app (apps/server/vite.config.ts) but never imports it.
+// The server bundles the web build without importing it.
 const BUILD_ONLY_DEPS = { t3: ["@t3tools/web"] };
 
-// Sources scripts/mobile-native-static-check.ts lints, plus the tool and rule
-// configuration that decides how it lints them, plus the root package.json
-// that defines the lint:mobile command.
 const MOBILE_NATIVE =
   /^apps\/mobile\/.*\.(swift|kt|kts)$|^apps\/mobile\/(\.swiftlint\.yml|detekt\.yml|\.editorconfig|Brewfile)$|^scripts\/mobile-native-static-check\.ts$|^package\.json$|^\.github\/workflows\/ci\.yml$|^\.github\/scripts\/ci-changes\.cjs$|^\.github\/actions\/ci-changes\//;
 
-// Jobs that test every package except these, which have jobs of their own.
 const OWN_TEST_JOB = new Set(["t3", "@t3tools/web", "@t3tools/monorepo"]);
 
 function readWorkspace() {
@@ -108,8 +88,7 @@ function readWorkspace() {
   return packages;
 }
 
-// Returns the packages a path touches, [] for an inert path, or null when the
-// path is not understood and everything must run.
+// [] means inert; null means unknown and requires every job.
 function ownersOf(file, packages) {
   if (INERT.some((pattern) => pattern.test(file))) return [];
   // A manifest can change dependencies or versions other packages read.
@@ -148,7 +127,6 @@ function decide(files, packages, full) {
   if (everything) {
     affected = all;
   } else {
-    // Add dependents until nothing changes.
     let grew = true;
     while (grew) {
       grew = false;
 
@@ -1,7 +1,4 @@
-// Publishes closed-testing betas, or downloads the internal APK for a normal
-// nightly release. Play generates and signs the APK from the
-// uploaded bundle with the app signing key, so it carries the same signature
-// as the Play Store install. Run by .github/workflows/mobile-android-apk.yml.
+// Play signs generated APKs with the app signing key, matching Play Store installs.
 const { execFileSync } = require("node:child_process");
 const crypto = require("node:crypto");
 const fs = require("node:fs");
@@ -50,10 +47,7 @@ async function play(token, method, url) {
   return response;
 }
 
-// Highest version code the track serves, with its release name. Play names a
-// release after the bundle's versionName unless the uploader sets one. This
-// endpoint reads without opening an edit; an edit would invalidate any open
-// EAS Submit edit made with the same service account.
+// Opening an edit would invalidate any EAS Submit edit using the same service account.
 async function newestTrackBuild(token, appUrl, trackName) {
   const { releases = [] } = await (
     await play(token, "GET", `${appUrl}/tracks/${trackName}/releases`)
@@ -82,8 +76,7 @@ function readRelease(tag) {
   }
 }
 
-// Download to a temporary directory so a failed request cannot leave a partial
-// APK among the release assets.
+// Stage downloads so failed requests cannot leave partial release assets.
 async function downloadApk({ token, appUrl, build, apkName }) {
   const generated = await (
     await play(token, "GET", `${appUrl}/generatedApks/${build.versionCode}`)
 
@@ -12,8 +12,7 @@
     "server/dist/client/index.html",
     "desktop/dist-electron/main.cjs",
 }
-# The current bundle is about 32 MiB compressed. Bound extraction on the
-# trusted runner even when the PR replaces the uploader entirely.
+# Bound trusted-runner extraction even when a PR replaces the uploader.
 MAX_ARCHIVE_BYTES = 512 * 1024 * 1024
 MAX_EXPANDED_BYTES = 2 * 1024 * 1024 * 1024
 MAX_ENTRIES = 50_000
@@ -58,9 +57,7 @@ def stage_bundle(archive: Path, destination: Path):
                 files.add(name)
         if not REQUIRED_FILES <= files:
             raise ValueError("Preview bundle is missing required entry points")
-        # Validate all names before writing anything. This is a fresh directory
-        # outside the checkout; neither pre-existing links nor trusted files
-        # can be followed or overwritten. ZIP permissions are never restored.
+        # Validate before writing into a fresh directory so existing links/files cannot be followed or overwritten.
         destination.mkdir(parents=True, exist_ok=False)
         for entry in entries:
             target = destination / entry.filename
 
@@ -294,8 +294,7 @@ async function resolve({ github, context, core }) {
 
   const sourceArtifacts = await artifactsForRun(github, owner, repo, source.id);
   const sourceArtifact = findResultArtifact(sourceArtifacts);
-  // CI requires the artifact whenever the server tests run, so a passing run
-  // without one skipped them because the PR cannot affect the server.
+  // Successful server tests require this artifact; its absence means CI skipped them.
   if (!sourceArtifact && source.conclusion === "success") {
     core.info("CI skipped the server tests for this change; nothing to report.");
     core.setOutput("publish", "false");
 
@@ -1,8 +1,5 @@
-// Windows WSL dev mode runs the server under Linux from the same node_modules
-// as the Windows client, so Windows installs also need Linux x64 glibc native
-// modules. Other platforms install only their own binaries; setting this
-// everywhere added ~2.2 GB of foreign binaries to every macOS install.
-// Release scripts stage their own installs with explicit architectures.
+// Windows installs need Linux x64 glibc binaries because WSL shares node_modules.
+// Keep other platforms native; release scripts set their own architectures.
 module.exports = {
   hooks: {
     // `typescript` is @tsc-rs/typescript (the catalog entry). Its npm version (0.8.x) is outside
 
@@ -153,7 +153,7 @@ Most code changes do not need an internal documentation change. Agents can read
 
 - `docs/internals/` is for architectural decisions and their reasons, constraints that span components, and implementation traps that are hard to discover from the source. Before adding a paragraph, ask what a maintainer would get wrong without it. If reading the relevant code answers the question, leave it out.
 - Do not document every feature, enumerate fields or methods, narrate control flow, maintain file catalogs, or append PR summaries. Types, tests, and code already record the implementation. The glossary defines shared vocabulary; it is not a feature index.
-- Keep a local implementation explanation in a nearby code comment. Use an internal doc when the reasoning crosses boundaries or needs context the code cannot carry well. Link to the relevant source instead of copying it.
+- A local reason the code can't show goes in a short nearby code comment. Use an internal doc when the reasoning crosses boundaries or needs context the code cannot carry well. Link to the relevant source instead of copying it.
 - When a documented decision or constraint changes, rewrite or remove the affected text. Do not append another account of the new behavior. A new internal page needs a distinct, durable reason to exist.
 - `docs/user/` helps users accomplish tasks. Give each major feature a concise section explaining what it does, how to start, and anything unintuitive. A settings path is useful; descriptions of visible buttons, icons, layouts, animations, or every UI state are not. Before adding text, ask what task or decision it helps the user with.
 - Keep user docs in the shipped product's voice, without implementation details or contributor tooling. Update the relevant feature section when how to use it changes. A UI tweak does not need a documentation entry, and a new control does not need its own page.
@@ -193,7 +193,7 @@ Architecture and its constraints: `docs/internals/overview.md`. Glossary: `docs/
   Named `Effect.fn` creates a span; the unnamed form does not. Preserve existing span names and
   options, and pass combinators as additional function-builder arguments.
 - Inferred types over annotations. `any` is the enemy.
-- Comments say why: a constraint, an external quirk, or an invariant the code can't show. Don't restate names or signatures, narrate steps, or record history. `t3code/no-low-value-comments` catches the mechanical cases.
+- Default to no comment. Write one only for a constraint, an external quirk, or an invariant the code can't show, in one line where you can and four at most. Don't restate names or signatures, narrate steps, record history, or explain the fix you just made; the PR carries that. `t3code/no-low-value-comments` enforces the length cap and the mechanical cases.
 - Our users drive agents all day and notice a dropped frame, a lying spinner, and a stale label. No continuously repainting animations; they peg the GPU on high-refresh displays.
 - If a rule here fights the task in front of you, say so loudly and get a human sign-off before breaking it.
 
 
@@ -372,9 +372,7 @@ function buildMacLauncher(electronBinaryPath) {
     JSON.stringify(currentMetadata) === JSON.stringify(expectedMetadata)
   ) {
     if (isDevelopment) {
-      // The launcher also handles protocol activations outside the dev runner,
-      // so refresh its fallback environment on every launch. Never let a value
-      // captured by an older parent app override the live dev-runner environment.
+      // Protocol activations bypass the dev runner, so refresh the fallback environment on every launch.
       writeDevelopmentEnvironmentScript();
       if (writeDevelopmentLauncherScript(launcherBinaryPath, runtimeElectronBinaryPath)) {
         signMacLauncherBundle(targetAppBundlePath);
@@ -385,10 +383,7 @@ function buildMacLauncher(electronBinaryPath) {
   }
 
   NodeFS.rmSync(targetAppBundlePath, { recursive: true, force: true });
-  // verbatimSymlinks keeps the framework's relative symlinks intact
-  // (e.g. Resources -> Versions/Current/Resources). Without it cpSync
-  // rewrites them to absolute paths into node_modules, which escape the
-  // bundle and crash sandboxed helper processes (icudtl.dat not found).
+  // Without verbatimSymlinks, cpSync makes framework symlinks point outside the bundle and crashes helpers.
   NodeFS.cpSync(sourceAppBundlePath, targetAppBundlePath, {
     recursive: true,
     verbatimSymlinks: true,
@@ -400,10 +395,7 @@ function buildMacLauncher(electronBinaryPath) {
   );
   patchHelperBundleInfoPlists(targetAppBundlePath);
   if (isDevelopment) {
-    // Launching the node_modules copy makes macOS associate the process (and Dock label) with
-    // Electron.app even though this bundle's Info.plist has the T3 Code name. Its conventional
-    // executable name also keeps Electron's default-app runtime in development mode instead of
-    // making app.isPackaged report true.
+    // Electron.app's executable name keeps default-app mode active without making app.isPackaged true.
     writeDevelopmentEnvironmentScript();
     writeDevelopmentLauncherScript(launcherBinaryPath, runtimeElectronBinaryPath);
   }
 
@@ -339,11 +339,7 @@ const scopedProgram = Effect.scoped(
     const rendererHistory = yield* DesktopRendererHistory.DesktopRendererHistory;
 
     yield* Effect.addFinalizer(() =>
-      // Stop every backend in the pool, not just the primary. The
-      // electronApp.quit() path can race ahead of the layer-scope
-      // cascade, so leaving the WSL instance for its parent scope
-      // finalizer means it gets hard-killed by the OS instead of
-      // receiving SIGTERM + grace.
+      // Quit can outrun layer finalizers; stop pooled backends here so they receive SIGTERM before OS teardown.
       stopAllPoolInstances().pipe(
         Effect.ensuring(rendererHistory.shutdown),
         Effect.ensuring(shutdown.markComplete),
 
@@ -186,10 +186,7 @@ export async function startDesktopAppControlServer(input: {
       server.listen(address);
     });
 
-  // Closing a Unix socket server unlinks the path it was bound to, even when
-  // another app's socket lives there now. Bind a staging path and move it onto
-  // the address instead, so a later close only unlinks the staging path, which
-  // is already gone.
+  // Closing unlinks the original bind path, even if another app replaced it. Bind a staging path first.
 
   const bindUnix = async (directory: string, mode: "take-over" | "claim-free") => {
     const staging = NodePath.join(directory, `${NodeCrypto.randomBytes(6).toString("hex")}.tmp`);
@@ -213,7 +210,6 @@ export async function startDesktopAppControlServer(input: {
   let server: NodeNet.Server;
   let inode: number | null = null;
   if (input.directory === null) {
-    // Named pipes close with the app that owns them, so no other app can remove this one.
     server = await listen(input.address);
   } else {
     await prepareUnixDirectory({ directory: input.directory, userId: input.userId });
@@ -222,10 +218,10 @@ export async function startDesktopAppControlServer(input: {
 
   let closed = false;
   const reclaimOnce = async () => {
-    // Never replace a socket that exists, so two apps cannot trade the path back and forth.
+    // Replacing an existing socket would let two apps trade the path indefinitely.
     if (closed || input.directory === null || (await inodeAt(input.address)) !== null) return;
     if (await prepareUnixDirectory({ directory: input.directory, userId: input.userId })) {
-      // A watch follows the directory's inode, so a recreated directory needs a new one.
+      // Directory watches follow inodes, so recreate the watch after directory replacement.
       watchDirectory(input.directory);
     }
     const next = await bindUnix(input.directory, "claim-free").catch(
@@ -269,7 +265,7 @@ export async function startDesktopAppControlServer(input: {
     close: async () => {
       if (closed) return;
       closed = true;
-      // A running reclaim can replace the watcher, so close the watcher after it.
+      // Reclaim can replace the watcher; close it afterward.
       await pendingReclaim;
       watcher?.close();
       for (const socket of sockets) socket.destroy();
 
@@ -38,7 +38,7 @@ const normalizeCommitHash = (value: string): Option.Option<string> => {
     : Option.none();
 };
 
-/** @public Service construction is part of the canonical Effect module API. */
+/** @public */
 export const make = Effect.gen(function* () {
   const assets = yield* DesktopAssets.DesktopAssets;
   const electronApp = yield* ElectronApp.ElectronApp;
@@ -91,9 +91,7 @@ export const make = Effect.gen(function* () {
 
   const configure = Effect.gen(function* () {
     const commitHash = yield* resolveAboutCommitHash;
-    // Electron removes spaces from this name to build the native User-Agent
-    // product token, but leaves parentheses intact. Keep the runtime name valid
-    // without rewriting preview sessions (which breaks Turnstile, #7110).
+    // Electron strips spaces but keeps parentheses in its User-Agent token, breaking Turnstile in preview sessions.
     yield* electronApp.setName(
       `${environment.branding.baseName} ${environment.branding.stageLabel}`,
     );
@@ -107,9 +105,7 @@ export const make = Effect.gen(function* () {
       yield* electronApp.setAppUserModelId(environment.appUserModelId);
     }
 
-    // Unpackaged runs only. A packaged bundle already carries its icon in
-    // Info.plist, so setting the dock tile again changes nothing except to
-    // overwrite a custom icon the user attached to the app themselves.
+    // Packaged bundles carry their icon in Info.plist; setting it again overwrites the user's custom icon.
     if (environment.platform === "darwin" && !environment.isPackaged) {
       const iconPaths = yield* assets.iconPaths;
       yield* Option.match(iconPaths.png, {