Pivot to Electron-first desktop intake

Author: fallintoplace

.gitignore

@@ -16,3 +16,7 @@ node_modules/
 upstream/downloads/
 upstream/work/
 tmp/
+electron/vendor/current/
+electron/vendor/staging/
+electron/manifest/*.local.json
+review-bundle/

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 Thanks for helping make `codex-ubuntu` better.
 
-This project is still early, but it is not casual about launcher safety. Small-looking changes in runtime discovery, PID handling, or browser launch behavior can break trust fast, so please read the docs before editing core flows.
+This project is still early, but it is not casual about desktop-launch safety. Small-looking changes in runtime discovery, PID handling, browser fallback behavior, or future Electron intake can break trust fast, so please read the docs before editing core flows.
 
 ## Before you open a pull request
 
@@ -35,6 +35,7 @@ make install-local
 
 Good first contributions:
 
+- Electron-first repo shaping
 - launcher hardening
 - test coverage improvements
 - desktop integration polish
@@ -46,7 +47,7 @@ Changes that need extra care:
 - process stop or reuse logic
 - provider contract changes
 - token handling or logging changes
-- anything that touches auth, runtime metadata, or port ownership
+- anything that touches auth, runtime metadata, port ownership, or desktop identity
 
 ## Style expectations
 

Makefile

@@ -1,9 +1,12 @@
 SHELL := /usr/bin/env bash
 
-.PHONY: check validate-desktop test install-local build-deb
+.PHONY: check validate-desktop test install-local install-electron-local import-electron-payload build-deb
 
 check: validate-desktop
+	bash -n electron/codex-desktop
 	bash -n launcher/codex-ubuntu
+	bash -n scripts/import-electron-payload.sh
+	bash -n scripts/install-electron-local.sh
 	bash -n scripts/install-local.sh
 	bash -n scripts/build-deb.sh
 	bash -n tests/launcher_smoke.sh
@@ -22,5 +25,11 @@ test: check
 install-local:
 	scripts/install-local.sh
 
+install-electron-local:
+	scripts/install-electron-local.sh
+
+import-electron-payload:
+	scripts/import-electron-payload.sh "$(SOURCE_ROOT)"
+
 build-deb:
 	scripts/build-deb.sh

README.md

@@ -6,91 +6,128 @@
 [![Security](https://img.shields.io/badge/runtime-stop%20verified-2E7D32)](docs/security.md)
 [![License](https://img.shields.io/badge/license-MIT-111111)](LICENSE)
 
-Unofficial Ubuntu-first launcher and packaging project for Codex.
+Unofficial Ubuntu-first Electron desktop project, with a browser fallback for recovery and constrained environments.
 
-`codex-ubuntu` is trying to solve a very specific problem well: make the app feel at home on Ubuntu without pretending Linux support is already finished upstream, and without baking in fragile local assumptions that break as soon as the machine changes.
+`codex-ubuntu` is trying to solve a very specific problem well: make the app feel genuinely at home on Ubuntu. The browser wrapper was useful as a safety exercise, but it is not the end state. The product target is now an Electron-first Ubuntu desktop experience, because that is the path that actually feels like a real app in daily use.
 
 ## Why this exists
 
-Ubuntu users currently end up choosing between:
+Ubuntu users usually end up choosing between:
 
 - browser-first one-off launch scripts
 - brittle personal-machine wrappers
 - heavy unofficial ports with a large maintenance surface
 
-This repository takes the narrower path:
+This repository now takes the harder but more honest path:
 
-- real Ubuntu launcher behavior
+- Electron-first desktop direction
+- browser launcher retained only as fallback and recovery
 - explicit security rules around runtime ownership
 - `.deb`-first packaging direction
-- provider boundaries that leave room for future runtime strategies
+- clear boundaries between desktop payload, compatibility patches, and fallback tooling
 
 ## What works today
 
-The current repository is not just a design memo. It ships a working launcher foundation with:
+The current repository is not just a design memo. It already ships:
 
-- dedicated app-window flow
+- a repo-owned local Electron launcher wrapper for dogfooding
+- a minimum Electron payload intake workflow
+- a strict browser fallback launcher
 - XDG config, cache, and state handling
 - verified process ownership before stop or reuse
 - runtime and browser discovery without hardcoded personal paths
 - local install flow
-- `.deb` build path
+- local Electron install flow
+- `.deb` build path for the fallback utility
 - smoke tests and CI
+- Electron-first repo structure and migration docs
 
 ## What it is not claiming
 
 This repository is not yet:
 
 - an official Linux desktop release
-- a full upstream desktop-payload repackager
+- a self-contained Electron desktop payload inside this repo
 - a finished updater
 - a promise to redistribute proprietary upstream app assets
 
-The local repackager path is still exploratory, not a committed milestone.
+The Electron direction is the main product path, but the exact asset and distribution model still has to stay explicit and careful.
 
 ## Current strategy
 
-The recommended v1 is intentionally launcher-first.
+The project is now Electron-first.
 
 That means:
 
-1. the Ubuntu launcher and desktop integration are real now
-2. the browser-shell runtime path is implemented now
-3. the provider contract is defined now
-4. future runtime modes can be added without rewriting the project shape
+1. the product target is an Ubuntu desktop app, not a dressed-up browser tab
+2. the browser-shell path stays only as fallback and recovery mode
+3. the provider contract still matters because both paths need safe runtime ownership rules
+4. packaging remains `.deb`-first
 
 ### Runtime model
 
 Implemented today:
 
-- `browser-shell`
+- `browser-shell` fallback
 
-Planned but not implemented:
+Primary target:
+
+- `desktop-payload` (Electron-first)
+
+Optional later:
 
 - `app-server`
-- `desktop-payload`
 
-See [providers/contract.md](providers/contract.md), [providers/browser-shell.md](providers/browser-shell.md), and [docs/architecture.md](docs/architecture.md).
+See [providers/contract.md](providers/contract.md), [providers/browser-shell.md](providers/browser-shell.md), [docs/architecture.md](docs/architecture.md), and [docs/electron-first-plan.md](docs/electron-first-plan.md).
 
 ## Feature matrix
 
 | Area | Current | Notes |
 | --- | --- | --- |
-| Ubuntu launcher | Yes | Dedicated app-window flow and desktop identity |
-| Process-safe stop/reuse | Yes | Refuses to kill unverified runtimes |
+| Repo-owned Electron launcher | Partial | Local dogfood wrapper around the current working desktop payload |
+| Minimum payload intake | Yes | Imports `app.asar`, `start.sh`, version, build metadata, and icon into an ignored local vendor area |
+| Browser fallback launcher | Yes | Strict launcher and recovery path |
+| Electron-first repo structure | Yes | Docs and repo layout now point at the desktop path |
+| Process-safe stop/reuse | Yes | Fallback launcher refuses to kill unverified runtimes |
 | XDG state layout | Yes | Config, cache, and state are separated |
-| Local install | Yes | `make install-local` |
-| Debian package build | Yes | `make build-deb` |
+| Local install | Yes | `make install-local` installs the fallback utility |
+| Local Electron install | Yes | `make install-electron-local` swaps the active desktop launcher to repo code with rollback preserved |
+| Debian package build | Yes | Today this packages the fallback utility |
 | CI | Yes | Syntax, smoke tests, packaging |
-| App Server provider | Not yet | Tracked as a future provider |
-| Desktop-payload repackager | Exploratory | Not tied to a committed release phase |
+| Desktop-payload provider | Not yet | Main implementation target |
+| App Server provider | Not yet | Optional future provider |
 | Updater | Not yet | Deliberately deferred |
 
 ## Quick start
 
-### 1. Install runtime prerequisites
+### Electron dogfood quick start
+
+If you want the current `Codex Desktop` launch chain to come from this repo while still using the working Electron payload already on your machine:
+
+```bash
+make install-electron-local
+```
+
+That swaps the active local `Codex Desktop` wrapper to the repo-owned Electron launcher and preserves a `Codex Desktop (Legacy)` rollback entry.
+
+### Minimum payload intake
+
+If you want the repo to import the current local desktop payload slice for patch planning and provenance:
+
+```bash
+make import-electron-payload
+```
+
+That writes:
+
+- `electron/vendor/current/`
+- `electron/manifest/current.local.json`
+
+### Fallback launcher quick start
 
-The current launcher expects:
+If you want the current runnable implementation from this repo today, that is still the fallback launcher.
+
+The fallback launcher expects:
 
 - `codex-app-linux` on `PATH`, or `CODEX_UBUNTU_APP_LINUX_CMD` set
 - a supported browser on `PATH`, or `CODEX_UBUNTU_BROWSER` set
@@ -101,7 +138,7 @@ Strict behavior:
 - invalid explicit runtime or browser overrides fail loudly
 - non-loopback bind values require `CODEX_UBUNTU_ALLOW_NON_LOOPBACK=1`
 
-### 2. Install locally
+Install it locally:
 
 ```bash
 make install-local
@@ -113,7 +150,7 @@ That installs:
 - `${XDG_DATA_HOME:-~/.local/share}/applications/codex-ubuntu.desktop`
 - `${XDG_DATA_HOME:-~/.local/share}/icons/hicolor/scalable/apps/codex-ubuntu.svg`
 
-### 3. Launch
+Launch it:
 
 ```bash
 codex-ubuntu
@@ -125,18 +162,20 @@ Or open `Codex Ubuntu (Unofficial)` from the Ubuntu app grid.
 
 ```mermaid
 flowchart LR
-  user["User"] --> desktop["Ubuntu desktop entry"]
-  desktop --> launcher["Launcher"]
-  launcher --> provider["Runtime provider"]
-  launcher --> state["XDG state, cache, config"]
+  user["User"] --> desktop["Ubuntu desktop integration"]
+  desktop --> payload["Electron desktop payload (target)"]
+  desktop --> fallback["Browser fallback launcher (implemented)"]
+  payload --> state["XDG state, cache, config"]
+  fallback --> provider["browser-shell provider"]
   provider --> runtime["Local web runtime"]
+  fallback --> state
 ```
 
 More detail lives in [docs/architecture.md](docs/architecture.md).
 
 ## Security baseline
 
-This project is opinionated about launcher safety:
+This project is opinionated about runtime safety even in preview form:
 
 - never trust a stale PID file by itself
 - verify runtime ownership before stop or reuse
@@ -145,12 +184,13 @@ This project is opinionated about launcher safety:
 - do not hardcode personal machine paths
 - do not globally fake another operating system
 
-Read [docs/security.md](docs/security.md) before extending runtime control logic.
+Read [docs/security.md](docs/security.md) before extending runtime or desktop-launch logic.
 
 ## Repository layout
 
-- `launcher/` launcher executable
-- `desktop/` desktop entry template and icon assets
+- `electron/` Electron-first intake plan and future desktop payload structure
+- `launcher/` browser fallback launcher
+- `desktop/` desktop entry templates and icon assets
 - `packaging/deb/` Debian packaging templates
 - `providers/` runtime/provider contract docs
 - `tests/` smoke tests and fixtures
@@ -171,6 +211,12 @@ Build a Debian package:
 make build-deb
 ```
 
+Install the repo-owned Electron dogfood launcher locally:
+
+```bash
+make install-electron-local
+```
+
 Read before contributing:
 
 - [CONTRIBUTING.md](CONTRIBUTING.md)
@@ -179,13 +225,13 @@ Read before contributing:
 
 ## Design review questions
 
-These are the intended pushback points:
+These are the intended pushback points now:
 
-1. Is launcher-first still the right v1?
-2. Is the provider contract concrete enough?
-3. When should the exploratory repackager track graduate into an explicit milestone?
-4. Is the current browser-shell runtime boundary too narrow or appropriately conservative?
-5. What must be true before calling the project a public preview?
+1. Which parts of the working Electron desktop should be brought into the repo first?
+2. Where should the browser fallback stop being part of the default user story?
+3. How thin can the Ubuntu-specific patch layer stay while preserving the app feel people actually want?
+4. What must be true before the Electron path becomes the default shipped experience?
+5. What asset and distribution model is acceptable before broader release?
 
 ## License
 

SECURITY.md

@@ -1,6 +1,6 @@
 # Security policy
 
-`codex-ubuntu` is an unofficial Ubuntu launcher project, but it still handles:
+`codex-ubuntu` is an unofficial Ubuntu desktop project, but it still handles:
 
 - local auth-bearing URLs
 - process reuse and process termination
@@ -17,6 +17,7 @@ The current security focus is:
 - token redaction and log hygiene
 - XDG path handling
 - desktop integration correctness
+- safe fallback behavior while the Electron path is being built
 
 ## Reporting a vulnerability
 

desktop/README.md

@@ -1,3 +1,5 @@
 # desktop
 
 Desktop integration assets for `codex-ubuntu`.
+
+This directory needs to serve both the future Electron desktop path and the current browser fallback utility without letting their app identities drift apart.