repository-map.md

Repository map

Area	Source of truth
Signed upstream	scripts/lib/upstream-linux-package.js, .sh, pinned key under assets/
Build orchestration	install.sh, scripts/lib/install-helpers.sh, build-info.*
Launcher	launcher/start.sh.template
ASAR engine	scripts/patches/, scripts/patch-linux-window-ui.js, patch-report.js
Linux features	linux-features/<id>/feature.json, adjacent README/resources/hooks
Shared packaging	scripts/lib/package-common.sh
Package formats	scripts/build-deb.sh, build-rpm.sh, build-pacman.sh, build-appimage.sh
Native runtime hooks	packaging/linux/
AppImage runtime	packaging/appimage/
Updater	updater/src/, packaging/update-builder/
Release watchdog	scripts/automation/upstream-linux-package-watchdog/
Nix	flake.nix, nix/upstream-linux-packages.json, nix/*.nix
CI	.github/workflows/, scripts/ci/, scripts/ci-local.sh
Computer Use	computer-use-linux/ and retained feature descriptors

Common task routing

Task	Start here	Also inspect
Change package verification	scripts/lib/upstream-linux-package.js	verifier tests, pinned key, updater source path, Nix pins
Change staged app layout	install.sh, scripts/lib/install-helpers.sh	all package formats, updater builder, baseline ASAR hash
Change launch behavior	launcher/start.sh.template	AppImage runtime, desktop entries, feature hooks
Add or alter a feature	linux-features/<id>/feature.json	adjacent README/test, Nix registry, watchdog config
Change ASAR matching	the feature's descriptor	patch runner/report policy, raw official-ASAR probe
Change package content	scripts/lib/package-common.sh	deb/RPM/pacman/AppImage/Nix and updater bundle
Change update behavior	updater/src/	service files, notification/desktop actions, persisted-state migration
Refresh official pins	scripts/ci/update-official-linux-pins.sh	both architectures and signed metadata
Change public commands	Makefile or CLI source	README EN/ZH and relevant operations guide

The official Linux package supplies the complete application runtime and bundled commands. There is no repository-owned runtime replacement layer. The packaged desktop entry is ChatGPT Community; codex-desktop remains the package, executable, and installation-path identity.

Generated output includes codex-app/, codex-app.backup-*, candidates, dist/, dist-next/, and target/. Fix their source owners and regenerate.

Important contracts

• linux-features/features.example.json is the committed feature-free baseline; features.json is local state.
• packaging/update-builder/ is only the template for a minimal rebuild bundle. Shared packaging code decides which enabled descriptors, resources, plugin templates, and prebuilt helpers enter the final bundle.
• nix/upstream-linux-packages.json contains release pins derived from signed metadata. It is generated by the repository script, not edited from a moving latest URL.
• The official payload owns Electron/native modules/plugins. Repository crates and resources must have an active optional-feature or packaging consumer.
• Historical migration facts belong in CHANGELOG.md and the migration record, not in active runtime instructions.