[comment audit] Finish launcher and configuration comment review (#33513)

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>

.gitattributes

@@ -1,6 +1,4 @@
-# A shebang plus CRLF makes vite's SSR transform emit a literal `#!` mid-module,
-# so any suite importing the script dies at load with a SyntaxError. Pin the whole
-# directory rather than the scripts that happen to have a test today.
+# CRLF shebangs break Vite's SSR transform.
 /config/scripts/**/*.mjs text eol=lf
 /skill-guides/*.md text eol=lf
 /skill-stubs/*.md text eol=lf
@@ -15,55 +13,33 @@
 *.html text eol=lf
 # Bundled plugin trees are byte-hashed; CRLF checkout would break the pinned hash.
 /resources/plugins/** text eol=lf
-# Relay assets are copied verbatim into the bundle and hashed byte-for-byte into
-# .version, which names the immutable remote install dir. A CRLF checkout makes a
-# Windows-built client disagree with a mac/Linux-built one on the same release,
-# so one host ends up with two relay trees (#17886 review).
-# Pin the bytes so a patch reads and diffs identically on every host. It is NOT
-# what makes the hash right: pnpm hashes a patch LF-normalized, so a CRLF checkout
-# cannot change it. Believing otherwise put a hand-computed raw digest in the
-# lockfile twice and broke every install (#17886).
-# These files are stored LF, which is not always the encoding they were written
-# against -- @vscode/windows-process-tree ships CRLF sources -- so any code that
-# runs `git apply` on one must force `-c core.autocrlf=input` rather than trust
-# the host's setting. See config/scripts/windows-process-tree-gyp-rebuild.mjs.
+# Keep patch diffs stable; pnpm hashes them with LF normalization.
+# CRLF upstream sources still need git -c core.autocrlf=input apply (windows-process-tree-gyp-rebuild.mjs).
 /config/patches/*.patch -text
-# Same reason, and pnpm parses these too: a CRLF checkout makes the mobile
-# patches unparseable, so Windows packaging dies on ERR_PNPM_INVALID_PATCH.
+# CRLF patches fail pnpm parsing on Windows.
 /mobile/patches/*.patch -text
-# The xterm bundle hunks also make a diff nobody can read; review the hand-written
-# source patch under xterm-src/ instead. The sibling patches stay diffable.
+# Review xterm-src/ instead of generated bundle hunks.
 /config/patches/@xterm__xterm@*.patch -diff
 /config/patches/xterm-src/*.patch text eol=lf
 # pnpm parses these unified diffs during Windows installs; keep checkout bytes stable.
 /mobile/patches/*.patch -text
-# Generated wrapper fixtures: collapse them in the PR diff so they stop drowning
-# the reviewable change, and pin LF because they are compared byte-for-byte.
-# Not -diff: the shell diff is the review surface when a wrapper does change.
+# Collapse generated wrappers but keep diffs available; tests compare LF bytes.
 /src/main/__fixtures__/shell-wrapper-snapshots/*.txt linguist-generated=true text eol=lf
-# Captured agent PTY transcripts. -text, not `text eol=lf` like the wrapper snapshots above:
-# these carry real CR and CRLF bytes as the terminal emitted them, and line-ending
-# normalisation on a Windows checkout would rewrite the evidence the fixture exists to be.
+# PTY transcripts must retain captured CR and CRLF bytes.
 /src/main/runtime/__fixtures__/*.txt -text
 /src/main/daemon/__fixtures__/pty-transcripts/*.txt -text
 /src/renderer/src/components/terminal-pane/terminal-link-transcripts/*.txt -text whitespace=cr-at-eol
-# Generated runtime English subset: compared byte-for-byte by
-# verify:localization-runtime-catalog, so a CRLF checkout would fail the gate.
+# verify:localization-runtime-catalog compares LF bytes.
 /src/renderer/src/i18n/en-runtime-required.json linguist-generated=true text eol=lf
-# Generated method->params catalog: compared byte-for-byte by
-# verify:rpc-params-catalog, so a CRLF checkout would fail the gate.
+# verify:rpc-params-catalog compares LF bytes.
 /src/shared/rpc-contract/rpc-params-catalog.generated.ts linguist-generated=true text eol=lf
-# Mobile RPC recording goldens: replay requires the file text to equal what rpc:record writes
-# (LF), so a CRLF checkout would fail every golden.
+# RPC recording goldens must match rpc:record's LF output.
 /mobile/rpc-foundation/goldens/*.json text eol=lf
-# Mobile web page source. Every text byte here is hashed into an asset digest and from
-# there into buildId, so a CRLF Windows checkout would ship a different bundle id for
-# identical source (91af2897 vs 9d78435e, measured on the bundle this replaced).
+# Mobile build IDs hash source bytes; checkout line endings must match across hosts.
 /mobile/src/** text eol=lf
 /mobile/app/** text eol=lf
 /mobile/web-entry/** text eol=lf
-# The blanket pin above would mark a future binary as text; exempt the asset types an
-# RN page actually carries.
+# Preserve binary assets under the text-pinned mobile directories.
 /mobile/src/**/*.png -text
 /mobile/src/**/*.jpg -text
 /mobile/src/**/*.jpeg -text

.github/CODEOWNERS

@@ -1,10 +1,8 @@
-# Product source remains owned by its normal reviewers; localization inputs need focused review.
 /src/renderer/src/i18n/locales/ @brennanb2025
 /config/scripts/*localization*.mjs @brennanb2025
 /config/scripts/*locale*.mjs @brennanb2025
 /config/i18next.config.ts @brennanb2025
 
-# The relay's deploy and operate surface: workspace, workflows, and the rollout lease action.
 /cloud/ @Jinwoo-H
 /.github/workflows/cloud-*.yml @Jinwoo-H
 /.github/actions/cloud-sql-rollout-lease/ @Jinwoo-H

.gitignore

@@ -1,9 +1,6 @@
-# Build artifacts
 tsconfig.*.tsbuildinfo
 
-# TypeScript emit artifacts next to sources (tsc produced these accidentally;
-# real source lives in .ts/.tsx). Hand-authored declaration files are
-# re-included below.
+# Exclude accidental tsc output; retain hand-authored declarations below.
 src/**/*.js
 src/**/*.d.ts
 /electron.vite.config.js
@@ -15,13 +12,10 @@ src/**/*.d.ts
 !src/renderer/src/mermaid.d.ts
 !src/types/build-constants.d.ts
 
-# Dependencies
 node_modules/
-# Why: the trailing-slash form matches directories only, so a node_modules SYMLINK (how agent
-# worktrees share an install) slipped past a bulk `git add` and got committed — twice.
+# Match symlinked installs too; the trailing-slash pattern only matches directories.
 node_modules
 
-# Build output
 dist/
 dist-electron/
 out/
@@ -37,16 +31,13 @@ native/windows-security/build/
 native/windows-security/bin/
 .build/windows-security/
 
-# pnpm
 .pnpm-store/
 package-lock.json
 
-# Environment
 .env
 .env.local
 .env.*.local
 
-# IDE
 .vscode/
 .idea/
 .serena/
@@ -54,10 +45,7 @@ package-lock.json
 *.swo
 *~
 
-# OS
-# Keep these in step with isOsMetadataSkillEntryName (skill-package-identity.ts): both disk
-# walkers skip a plain file with one of these names, the git-tree producer does not, and
-# ignoring them here is what keeps `git add -A` from committing a stray one.
+# Keep metadata exclusions in sync with isOsMetadataSkillEntryName (skill-package-identity.ts).
 *.stackdump
 .DS_Store
 ._*
@@ -65,7 +53,6 @@ Thumbs.db
 ehthumbs.db
 desktop.ini
 
-# Lint/cache
 .oxlintcache
 /.cache/vite/
 /.cache/vite.lock/
@@ -73,13 +60,11 @@ desktop.ini
 /.cache/fixtures/
 /.cache/check-changed.json
 
-# Logs
 *.log
 *.log.*
 npm-debug.log*
 pnpm-debug.log*
 
-# Coverage
 coverage/
 
 # Prod release scan output (accidental adds)
@@ -89,7 +74,6 @@ prod-release-scan-*.md
 /tests/tools/benchmarks/results/*.json
 /.bench-fixtures/
 
-# Temp
 tmp/
 .tmp/
 design-docs/
@@ -99,12 +83,9 @@ design-docs/
 # Machine-local agent hook endpoint files may contain auth tokens.
 /agent-hooks/
 
-# Local-only design/planning docs (not checked in).
-# Durable docs that should be tracked must live in one of the allow-listed
-# locations below (assets, readme, STYLEGUIDE + styleguide/, and mobile terminal shortcut bar).
+# Planning docs stay local; allow durable documentation below.
 docs/**
 !docs/
-# The deployable docs app is source, not local engineering notes.
 !docs/site/
 !docs/site/**
 !docs/assets/
@@ -124,7 +105,6 @@ docs/**
 !docs/agent-skill-sharing-implementation-checklist.md
 !docs/mobile-terminal-shortcut-bar.md
 
-# Stably CLI (only docs/ are tracked)
 .stably/*
 !.stably/docs/
 .playwright-cli
@@ -136,11 +116,10 @@ validation-screenshots/
 /notes/
 /pr-evidence/
 
-# Playwright
 test-results/
 playwright-report/
 
-# Agent skill installations (machine-local, populated by agent tooling)
+# Agent skills are installed per machine.
 /.claude/skills/
 /.agents/skills/
 /skills-lock.json
@@ -153,22 +132,18 @@ playwright-report/
 /agent-hooks/
 validation-screenshots/
 
-# Localization bootstrap cache (regenerated by bootstrap:*-catalog)
 src/renderer/src/i18n/locales/.zh-catalog-cache.json
 src/renderer/src/i18n/locales/.ko-catalog-cache.json
 src/renderer/src/i18n/locales/.ja-catalog-cache.json
 src/renderer/src/i18n/locales/.es-catalog-cache.json
 src/renderer/src/i18n/locales/.fr-catalog-cache.json
 
-# Bench result JSONs are working artifacts
 tests/tools/benchmarks/results/terminal-pipeline-*.json
 
 # Old release trees the cross-version wire harness extracts on demand
 tests/e2e/.cross-version-checkouts/
 
-# Bundler's install path for the mobile release toolchain (mobile/Gemfile.lock
-# IS committed). Also keeps oxfmt/oxlint, which honor this file, from walking
-# vendored gems.
+# Bundler installs gems here; keep linters out of the vendored tree.
 /mobile/vendor/
 
 # Generated by config/scripts/sync-anti-slop-plugin.mjs from the pinned oxlint-plugin-anti-slop
@@ -177,7 +152,6 @@ tests/e2e/.cross-version-checkouts/
 # Generated by the CI unit-test sequencer (and by reproducing a shard locally).
 ci-shards/
 
-# Paired CI timing reports and temporary baseline plugin.
 .build/preflight-benchmark/
 /.build/windows-native-benchmark/
 

cloud/.gitignore

@@ -8,7 +8,6 @@ coverage/
 .env.local.generated
 *.log
 
-# Terraform/OpenTofu local state and plans must stay out of git.
 **/.terraform/
 *.tfstate
 *.tfstate.*
@@ -19,6 +18,5 @@ override.tf.json
 *_override.tf
 *_override.tf.json
 
-# Local dev signing key + SQLite live under data/ — never commit (contains a
-# private key and dev PII). Prod supplies the key via ORCA_CLOUD_SIGNING_KEY_PEM.
+# Contains development signing keys and personal data.
 data/

config/scripts/orca-dev

@@ -1,8 +1,7 @@
 #!/usr/bin/env bash
-# Dev CLI wrapper — uses a separate userData path to avoid clobbering production Orca data.
+# Keep development CLI data separate from production.
 set -euo pipefail
 
-# Resolve through symlinks so this works when called via /usr/local/bin/orca-dev
 SOURCE="$0"
 while [ -L "$SOURCE" ]; do
   DIR="$(cd "$(dirname "$SOURCE")" && pwd)"

docs/site/.gitignore

@@ -5,7 +5,5 @@ out
 .vercel
 next-env.d.ts
 *.tsbuildinfo
-# Keep local deployment credentials out of the publication boundary.
 .env
 .env.*
-# Package policy lives in pnpm-workspace.yaml; keep credentials in user-level npm config.

resources/darwin/bin/orca

@@ -20,9 +20,7 @@ fi
 
 CONTENTS="$APP_PATH/Contents"
 ELECTRON="$CONTENTS/MacOS/Orca"
-# Why: Orca packages the CLI entrypoint outside app.asar so the public shell
-# command can execute it directly with ELECTRON_RUN_AS_NODE, mirroring VS Code's
-# launcher model instead of requiring a separate npm-distributed binary.
+# The unpacked entrypoint runs directly in Electron's Node mode.
 CLI="$CONTENTS/Resources/app.asar.unpacked/out/cli/index.js"
 
 export ORCA_NODE_OPTIONS="${NODE_OPTIONS-}"

resources/linux/bin/orca-ide

@@ -1,8 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Why: invoked via ~/.local/bin/orca-ide symlink (from CliInstaller); resolve it
-# so APP_DIR points at the real install, not the symlink's parent.
+# Installed commands are symlinks; locate resources relative to their target.
 SOURCE="${BASH_SOURCE[0]}"
 while [ -h "$SOURCE" ]; do
 	DIR="$(cd "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd)"
@@ -13,8 +12,7 @@ SCRIPT_DIR="$(cd "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd)"
 RESOURCES_DIR="$(cd "$SCRIPT_DIR/.." >/dev/null 2>&1 && pwd)"
 APP_DIR="$(cd "$RESOURCES_DIR/.." >/dev/null 2>&1 && pwd)"
 
-# Why: Linux executableName is `orca-ide` (avoids Ubuntu GNOME Orca conflict);
-# `-f` rejects a same-named directory that `-x` alone would accept.
+# orca-ide avoids the GNOME Orca name; -f excludes executable directories.
 ELECTRON=""
 for candidate in orca-ide orca Orca; do
 	if [ -f "$APP_DIR/$candidate" ] && [ -x "$APP_DIR/$candidate" ]; then
@@ -28,9 +26,7 @@ if [ -z "$ELECTRON" ]; then
 	exit 1
 fi
 
-# Why: Orca packages the CLI entrypoint outside app.asar so the public shell
-# command can execute it directly with ELECTRON_RUN_AS_NODE, mirroring the same
-# launcher model used on macOS instead of maintaining a separate Node binary.
+# The unpacked entrypoint runs directly in Electron's Node mode.
 CLI="$RESOURCES_DIR/app.asar.unpacked/out/cli/index.js"
 
 export ORCA_NODE_OPTIONS="${NODE_OPTIONS-}"
@@ -38,5 +34,4 @@ export ORCA_NODE_REPL_EXTERNAL_MODULE="${NODE_REPL_EXTERNAL_MODULE-}"
 unset NODE_OPTIONS
 unset NODE_REPL_EXTERNAL_MODULE
 
-# CLI commands run in Electron's Node mode and must never initialize Chromium.
 ELECTRON_RUN_AS_NODE=1 exec "$ELECTRON" "$CLI" "$@"

tests/tools/relay-bench/.gitignore

@@ -1,4 +1,3 @@
-# The bench writes a resume-credential bundle here. It carries a live device token and
-# resume token for a real paired desktop; it must never reach the repo.
+# Bench output contains live device and resume tokens.
 *.json
 state*