fix(packaging): include dashboard assets in fork source installs

.github/simplicity-budgets.toml

@@ -111,6 +111,7 @@ allowed = [
   "flake.lock",
   "flake.nix",
   "frontend",
+  "issues-check.md",
   "mkdocs.yml",
   "openspec",
   "pyproject.toml",

.github/workflows/windows-startup.yml

@@ -39,6 +39,12 @@ jobs:
       - name: Install dependencies
         run: uv sync --dev --frozen
 
+      - name: Verify editable setup leaves frontend compilation explicit
+        run: |
+          if (Test-Path "app/static/index.html") {
+            throw "Editable dependency setup unexpectedly compiled the dashboard"
+          }
+
       - name: Run portability regression tests
         run: uv run pytest tests/unit/test_memory_monitor.py tests/unit/test_check_proxy_architecture.py tests/unit/test_proxy_header_launcher_contract.py -q
 

COMMUNITY_RELEASE.md

@@ -213,7 +213,10 @@ sudo systemctl restart codex-lb
 ---
 
 ### 2. If using pip or uv pre-built wheel
-Upgrade to the latest wheel release:
+The URLs below install the historical hardened.3 artifact. Its package version
+is 1.25.1 but runtime is 1.25.0-beta.9; it does not include later checkout fixes.
+Select a verified newer artifact URL explicitly when available. See the
+[Python installation guide](docs/deployment/python.md) for source and package channels.
 
 **pip:**
 ```bash
@@ -230,18 +233,33 @@ codex-lb
 ---
 
 ### 3. If running via uvx (zero install)
-Use `--refresh` to invalidate the cached build and fetch the newest HEAD commit:
+For the historical fork wheel, refresh its cached tool environment explicitly:
 ```bash
-uvx --refresh --from git+https://github.com/Frozen811/codex-lb.git codex-lb
+uvx --refresh --from https://github.com/Frozen811/codex-lb/releases/download/v1.25.0-hardened.3/codex_lb-1.25.1-py3-none-any.whl codex-lb
 ```
 
+Refreshing this URL does not select new source fixes. Git installs require the
+selected source SHA and Bun 1.3.14 when dashboard assets need building; see the
+Python guide. Keep the data directory/encryption key and back up the database
+before switching code or package sources. Do not assume a downgrade can read
+an upgraded database schema.
+
 ---
 
 ### 4. If using Docker / Docker Compose
-Pull the repository update and rebuild the container (your database and settings in volumes are preserved):
+For a source build, back up the application volume and database, select the
+desired fork revision, and rebuild only the application. Server-only Compose:
 ```bash
 git pull origin main
-docker compose down
-docker compose up -d --build
+docker compose -f docker-compose.prod.yml up -d --force-recreate server
 ```
 
+Root `docker-compose.yml` is development (backend + Vite frontend); use
+`docker compose up -d --build --force-recreate server frontend` for that setup.
+Keep the same volumes and database URL. A source pull/rebuild does not update
+an installation made from a public image. Public `latest`/`1.25.1` still refer
+to historical source `f622c563`; choose a tested release digest deliberately.
+See the [fork Docker guide](docs/deployment/docker.md) for image provenance,
+database profiles, external PostgreSQL and recreation. Restoring older code
+may also require restoring the matching database backup.
+

README.md

@@ -22,7 +22,7 @@ python oauth sqlalchemy dashboard load-balancer openai rate-limit api-proxy code
 
 Load balancer for ChatGPT accounts. Pool multiple accounts, track usage, manage API keys, view everything in a dashboard.
 
-**Documentation: <https://soju06.github.io/codex-lb/>** — getting started, client setup, configuration, deployment, troubleshooting, and more screenshots.
+**Fork Docker guide: [Docker](docs/deployment/docker.md)** · [Upstream documentation](https://soju06.github.io/codex-lb/) — client setup, configuration, troubleshooting, and screenshots.
 
 > [!NOTE]
 > ### 🛡️ Hardened Community Edition (by [@Frozen811](https://github.com/Frozen811))
@@ -40,20 +40,20 @@ Load balancer for ChatGPT accounts. Pool multiple accounts, track usage, manage
 > 
 > ### 🚀 Quick Install & Run:
 > 
-> **Option 1: Pre-built Docker Image (instant run, zero build)**
+> **Option 1: Historical public Docker image (linux/amd64, source `f622c563`; newer fixes require [a source build](docs/deployment/docker.md))**
 > ```bash
 > docker network inspect codex-lb-net >/dev/null 2>&1 || docker network create codex-lb-net
 > docker run -d --name codex-lb \
 >   --network codex-lb-net \
 >   -p 2455:2455 -p 1455:1455 \
 >   -v codex-lb-data:/var/lib/codex-lb \
->   ghcr.io/frozen811/codex-lb:latest
+>   ghcr.io/frozen811/codex-lb@sha256:ad9aa84b12bce9f6afc63adb3aa86e73f6aafca1814e6f20b486b00f21c60447
 > ```
 > 
-> **Option 2: Direct installation with uvx or pip**
+> **Option 2: Historical release wheel with uvx or pip ([identity and source-build guide](docs/deployment/python.md))**
 > ```bash
 > # Run via uvx:
-> uvx --from git+https://github.com/Frozen811/codex-lb.git codex-lb
+> uvx --from https://github.com/Frozen811/codex-lb/releases/download/v1.25.0-hardened.3/codex_lb-1.25.1-py3-none-any.whl codex-lb
 > 
 > # Or install pre-built wheel directly:
 > pip install https://github.com/Frozen811/codex-lb/releases/download/v1.25.0-hardened.3/codex_lb-1.25.1-py3-none-any.whl
@@ -84,7 +84,7 @@ Load balancer for ChatGPT accounts. Pool multiple accounts, track usage, manage
 | **Dead Client Continuation Anchor ([#2493](https://github.com/Soju06/codex-lb/issues/2493))** | ❌ Client hangs without terminal frame | ✅ Clean terminal `response.failed` event |
 | **Replay Relocation Engine ([PR #2428](https://github.com/Soju06/codex-lb/pull/2428))** | ❌ Unmerged open PR | ✅ Fully integrated & regression-tested |
 | **Log Credential Redaction ([#2028](https://github.com/Soju06/codex-lb/issues/2028))** | ❌ Unhandled loop errors leak credentials | ✅ Sanitized with `_RedactedRepr` |
-| **Pre-built Docker Image** | ⚠️ Outdated | ✅ `ghcr.io/frozen811/codex-lb:latest` |
+| **Pre-built Docker Image** | Separate upstream artifact | Historical fork image; see [Docker provenance](docs/deployment/docker.md#public-fork-image) |
 | **OpenSpec Validation** | ⚠️ Partial / Untracked PRs | ✅ 67/67 Specifications strictly validated |
 
 ## Features
@@ -108,17 +108,17 @@ Load balancer for ChatGPT accounts. Pool multiple accounts, track usage, manage
 ## Quick Start
 
 ```bash
-# Docker (recommended)
-docker volume create codex-lb-data
+# Docker (run from a fork checkout; see the Docker guide)
+docker build -t codex-lb:local .
 docker network inspect codex-lb-net >/dev/null 2>&1 || docker network create codex-lb-net
 docker run -d --name codex-lb \
   --network codex-lb-net \
   -p 2455:2455 -p 1455:1455 \
   -v codex-lb-data:/var/lib/codex-lb \
-  ghcr.io/soju06/codex-lb:latest
+  codex-lb:local
 
-# or uvx
-uvx codex-lb
+# or the historical fork wheel (see the Python guide for current source)
+uvx --from https://github.com/Frozen811/codex-lb/releases/download/v1.25.0-hardened.3/codex_lb-1.25.1-py3-none-any.whl codex-lb
 
 # or nix
 nix run github:Soju06/codex-lb

README.zh-CN.md

@@ -39,17 +39,17 @@ ChatGPT 账户负载均衡器。聚合多个账户、追踪用量、管理 API K
 ## 快速开始
 
 ```bash
-# Docker（推荐）
-docker volume create codex-lb-data
+# Docker（在 Frozen811/codex-lb 仓库目录中运行；参见 docs/deployment/docker.md）
+docker build -t codex-lb:local .
 docker network inspect codex-lb-net >/dev/null 2>&1 || docker network create codex-lb-net
 docker run -d --name codex-lb \
   --network codex-lb-net \
   -p 2455:2455 -p 1455:1455 \
   -v codex-lb-data:/var/lib/codex-lb \
-  ghcr.io/soju06/codex-lb:latest
+  codex-lb:local
 
-# 或者使用 uvx
-uvx codex-lb
+# 或者安装历史 fork wheel（版本差异及源码安装见 docs/deployment/python.md）
+uvx --from https://github.com/Frozen811/codex-lb/releases/download/v1.25.0-hardened.3/codex_lb-1.25.1-py3-none-any.whl codex-lb
 
 # 或者使用 nix
 nix run github:Soju06/codex-lb

docs/deployment/python.md

@@ -0,0 +1,101 @@
+# Python installation
+
+Use Python 3.13 or newer. This fork keeps the distribution name `codex-lb`:
+bare `pip install codex-lb` and `uvx codex-lb` select upstream PyPI. Select a
+fork artifact URL or fork Git source explicitly. Docker source installs have
+a separate [guide](docker.md).
+
+## Historical release packages
+
+The public `v1.25.0-hardened.3` wheel and sdist were checked on 2026-10-01.
+Their metadata version is `1.25.1`, while runtime is `1.25.0-beta.9`; root
+application code corresponds to the historical release, not newer checkout
+fixes. Both install with working dashboard assets and migrations. The public
+sdist also contains 5967 nested agent-worktree entries; prefer the wheel for
+historical reproduction. No historical asset was replaced during the audit.
+
+For an isolated pip environment on Windows (PowerShell):
+
+```powershell
+python -m venv .venv
+.venv\Scripts\python.exe -m pip install https://github.com/Frozen811/codex-lb/releases/download/v1.25.0-hardened.3/codex_lb-1.25.1-py3-none-any.whl
+.venv\Scripts\codex-lb.exe
+```
+
+On Linux/macOS:
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install https://github.com/Frozen811/codex-lb/releases/download/v1.25.0-hardened.3/codex_lb-1.25.1-py3-none-any.whl
+.venv/bin/codex-lb
+```
+
+With uv, without activating a project environment:
+
+```bash
+uvx --python 3.13 --from https://github.com/Frozen811/codex-lb/releases/download/v1.25.0-hardened.3/codex_lb-1.25.1-py3-none-any.whl codex-lb
+```
+
+For a persistent uv tool install:
+
+```bash
+uv tool install --python 3.13 https://github.com/Frozen811/codex-lb/releases/download/v1.25.0-hardened.3/codex_lb-1.25.1-py3-none-any.whl
+codex-lb
+```
+
+These commands deliberately select the historical wheel. A pinned old URL
+does not become a newer release when refreshed. For updates, replace the URL
+with the artifact you verified; `uv tool install --reinstall <artifact-url>`
+replaces an existing tool source, including when package version metadata is
+unchanged. See the [uv tool guide](https://docs.astral.sh/uv/guides/tools/).
+
+## Install selected fork source
+
+Choose an audited commit SHA from the fork and replace `<source-sha>` below.
+Install [Bun](https://bun.sh/docs/installation) **1.3.14**, matching
+`frontend/package.json`, before building a source tree without dashboard assets:
+
+```bash
+bun --version  # must print 1.3.14
+uvx --python 3.13 --from git+https://github.com/Frozen811/codex-lb.git@<source-sha> codex-lb
+```
+
+The package build hook runs `bun install --frozen-lockfile` and `bun run build`
+when dashboard assets are absent. Missing/wrong Bun or an incomplete build
+fails with prerequisite guidance. A complete release wheel or sdist already
+contains assets and does not require Bun at install time. Source installation
+needs network access for Python and frontend dependencies; build failure is
+reported instead of producing a package whose dashboard is missing.
+
+Editable development setup (`uv sync`) installs Python dependencies without
+compiling the dashboard or requiring Bun. Build the frontend explicitly before
+using its dashboard; this exception does not apply to distributable wheels/sdists.
+
+For a checkout of the selected source, build distributable packages with
+`uv build`, then install the wheel with `uv pip install --python <venv-python>
+<wheel-path>` or pip. A source distribution can be installed the same way;
+the corrected source distribution includes build helpers, frontend inputs and
+assets, and excludes local dependencies/worktrees. The ordinary GitHub source
+archive has no prebuilt assets and requires the pinned Bun prerequisite.
+
+## Startup and retained data
+
+Open `http://localhost:2455` and check `/health/ready`. Both `codex-lb` and
+`codex-lb-db` console scripts are installed; `codex-lb-db upgrade` and
+`codex-lb-db check` expose migration diagnostics. Startup migrations use the
+configured database. Optional external DB configuration follows [Database](../database.md).
+
+Host installs default to `~/.codex-lb/` independent of the venv/tool directory;
+`CODEX_LB_DATA_DIR` overrides it. Retain this directory and its encryption key,
+back up the database before an update, and keep the same configuration when
+recreating the tool environment. An isolated uv tool replacement passed data
+and key retention checks. Do not run two writers against the same SQLite data.
+
+Audit startup was verified on Windows/Python 3.13 in clean venvs outside the
+checkout. Real account OAuth/Codex routing, macOS/Linux native installs and
+custom enterprise network policies require separate checks. Package startup
+does not prove that the fork's newer code is in a historical release.
+
+---
+
+*Spec: [deployment-installation](https://github.com/Frozen811/codex-lb/tree/main/openspec/specs/deployment-installation)*

docs/getting-started.md

@@ -5,22 +5,29 @@ codex-lb runs with zero configuration — every setting has a working default, a
 ## Quick Start
 
 ```bash
-# Docker (recommended)
-docker volume create codex-lb-data
+# Docker (from a Frozen811/codex-lb checkout; see the Docker guide)
+docker build -t codex-lb:local .
+docker network inspect codex-lb-net >/dev/null 2>&1 || docker network create codex-lb-net
 docker run -d --name codex-lb \
+  --network codex-lb-net \
   -p 2455:2455 -p 1455:1455 \
   -v codex-lb-data:/var/lib/codex-lb \
-  ghcr.io/soju06/codex-lb:latest
+  codex-lb:local
 
-# or uvx
-uvx codex-lb
+# or the historical fork wheel (see the Python guide before choosing)
+uvx --from https://github.com/Frozen811/codex-lb/releases/download/v1.25.0-hardened.3/codex_lb-1.25.1-py3-none-any.whl codex-lb
 
 # or Nix
 nix run github:Soju06/codex-lb
 ```
 
 Open [localhost:2455](http://localhost:2455) → Add account → Done.
 
+Choose the installation channel deliberately: [Docker](deployment/docker.md)
+builds the selected fork checkout; [Python packages](deployment/python.md)
+explains historical wheel identity and current source prerequisites. Bare
+`uvx codex-lb` selects upstream PyPI, and the Nix example above is also upstream.
+
 Next: point your coding agent at codex-lb — see [Client Setup](client-setup.md).
 
 ## Remote setup (bootstrap token)
@@ -46,7 +53,7 @@ docker run -d --name codex-lb \
   -e CODEX_LB_DASHBOARD_BOOTSTRAP_TOKEN=your-secret-token \
   -p 2455:2455 -p 1455:1455 \
   -v codex-lb-data:/var/lib/codex-lb \
-  ghcr.io/soju06/codex-lb:latest
+  codex-lb:local
 ```
 
 **Local access** (localhost) bypasses bootstrap entirely — no token needed.
@@ -55,4 +62,4 @@ Running behind a reverse proxy or exposing codex-lb to other machines? See [Remo
 
 ---
 
-*Spec: [deployment-installation](https://github.com/Soju06/codex-lb/tree/main/openspec/specs/deployment-installation)*
+*Spec: [deployment-installation](https://github.com/Frozen811/codex-lb/tree/main/openspec/specs/deployment-installation)*

flake.nix

@@ -75,6 +75,8 @@
           ./LICENSE
           ./README.md
           ./pyproject.toml
+          ./scripts/hatch_build.py
+          ./scripts/build_dashboard.py
         ];
       };
 
@@ -86,6 +88,8 @@
           ./LICENSE
           ./README.md
           ./pyproject.toml
+          ./scripts/hatch_build.py
+          ./scripts/build_dashboard.py
         ];
       };