Installation and distribution implementation plan#

This engineering record is intentionally separate from the authoritative HTML design. It tracks the bounded implementation, verification, and review evidence for the current distribution work.

Release gate repair for v0.6.1#

• Removed four unreferenced legacy Channel modules after the implementations had moved under openprogram/channels/implementations/; the runtime HTTP inventory now scans only active Channel code.
• Renamed the Research writer's dropped context parameter to the runtime-supported project_context field.
• Recorded Browser Agent as an explicitly deferred internal tool loop without changing its current behavior.
• Local acceptance: the previously failing four tests pass; affected tests report 461 passed; the full non-integration suite reports 5274 passed, 11 skipped, and 1 expected failure. Desktop, Web, release-script, runtime-HTTP, Ruff, and documentation gates pass.
• Windows native packaging remains deferred for a later release decision. This repair does not add a Windows artifact or introduce constraints that prevent a later implementation.

Native release result and v0.6.2 correction#

• Tag v0.6.1 remained immutable after release run 31820999574 failed while resolving the complete macOS x86_64 runtime. No GitHub Release was published from that tag.
• Root cause: semble 0.2.0 constrained tree-sitter-language-pack below 1.8, and the locked 1.6.2 package published no macOS x86_64 wheel.
• Correction: require semble>=0.5.3, whose grammar dependency is semble-grammars; the locked grammar package publishes native wheels for macOS x86_64/arm64 and Linux x86_64/arm64 while preserving the search capability.
• Regression gate: resolve the complete locked product requirements for CPython 3.12 on macOS x86_64 and assert the locked grammar artifact includes that platform. The release retry uses the higher patch version v0.6.2.
• Tag v0.6.2 remained immutable after run 31822787529 passed the search dependency step but found that torch 2.13.0 no longer publishes macOS x86_64 wheels. No GitHub Release was published from that tag.
• The v0.6.3 retry uses the last upstream macOS x86_64-compatible pair, torch 2.2.2 and torchvision 0.17.2, together with numpy 1.26.4 for NumPy ABI compatibility. All four release targets must resolve this same GUI stack; Linux continues to use the official CPU wheel index.
• Tag v0.6.3 remained immutable after run 31823941178 showed that unconstrained GUI harness installation upgraded NumPy back to 2.x through the current OpenCV dependency, invalidating the Torch 2.2.2 NumPy ABI. No GitHub Release was published from that tag.
• The v0.6.4 retry pins opencv-python 4.11.0.86 and applies one constraints file to every first-party Program installation so later dependency resolution cannot replace the verified NumPy, OpenCV, Torch, or Torchvision stack.
• Tag v0.6.4 remained immutable after run 31824996497 built and installed all four complete runtimes but exposed an architecture-name mismatch in the Intel macOS Desktop command: release archives use x86_64, while electron-builder accepts x64. No GitHub Release was published from that tag.
• The v0.6.5 retry keeps runtime artifact naming unchanged and maps the Intel Desktop builder argument to x64; a release-workflow regression test enforces the explicit mapping for both macOS architectures.

Short public installer batch#

• Base commit: c1886a3fdf7ba196c42ec9a2c19dca7fe86c12e7.
• Public command: curl -fsSL https://openprogram.io/install | sh for normal macOS/Linux CLI and server installations.
• Boundary: the root script resolves the latest stable GitHub Release, validates a three-part numeric version, downloads the immutable tagged installer, and forwards the version. It does not assemble a second installer and does not weaken runtime checksum, capability-manifest, or worker cold-start verification.
• Reproducibility: advanced users and CI may pass OPENPROGRAM_VERSION=X.Y.Z to the sh process. The tagged scripts/install-release.sh remains the authoritative versioned installer.
• Publication: docs/_static_root/install.sh must be renamed to the deployed site root as /install; /docs/install/ remains the installation documentation directory.
• Tests: execute the public root script with a fake curl for automatic latest-version resolution and explicit pinning, assert the tagged installer handoff, build the docs site, verify the assembled root file, and run the existing distribution release suite.
• RED evidence: the two public-entry tests initially failed because the root bootstrap did not exist and the Pages workflow did not publish /install.
• GREEN evidence: the distribution release file reports 25 passed; docs build reports 509 pages; landing check passes; link check reports 0 broken links; an assembled-site probe preserves /docs/install/ and validates the root /install script.
• Release-state evidence on 2026-08-15: GitHub latest resolves to v0.6.0, whose release has no assets and whose tag has no scripts/install-release.sh; v0.6.1 has not been tagged. The bootstrap therefore fails without installing a reduced product until a complete release is published. This batch does not create or move a tag.

Unified complete-product batch#

• Base commit: e6ec8694977080153a3c94e50a5080d2ff43b69b.
• Product contract: every supported non-developer installation contains the same complete capability set for its platform and architecture. A Desktop artifact must use the same runtime archive as CLI/server and may differ only by its Electron shell. If that complete packaged entry does not pass, the Desktop artifact is absent rather than reduced.
• Required capabilities: Web, providers, MCP, memory, channels, search, default Playwright Chromium, default OCR, the GUI detector model, and the GUI, Research, and Wiki first-party Programs.
• Developer installations add editable sources, tests, diagnostics, local frontend builds, and replaceable OCR/browser backends. They do not define a smaller or different product edition.
• Ordinary users install from GitHub Release artifacts. PyPI wheels remain internal build inputs and developer artifacts, not a product installation path.
• macOS artifacts are explicitly unsigned DMG/ZIP files. Apple Developer ID signing and notarization are not release requirements. Linux publishes complete x86_64/arm64 CLI/server runtimes; no Linux Desktop artifact is published after the complete AppImage failed its packaging gate.
• Windows native packaging is deferred from this release, while the runtime/Desktop separation must preserve later implementation feasibility. OS credential-store integration remains excluded.

Current-batch files#

• Product contract: docs/reference/design/distribution/installation-packaging.html and this implementation record.
• Runtime assembly: a checked-in product manifest, runtime builder/archive scripts, desktop runtime staging, and the CLI release installer.
• Launchers: Electron and CLI launch paths that set bundled browser/OCR/model locations and validate the capability manifest.
• Release: .github/workflows/release.yml, desktop artifact naming, runtime archives, checksums, and public-entry smoke checks.
• Product documentation: install, desktop, server, upgrade, Programs, and README entry points that describe one complete product rather than optional first-party components.
• Tests: tests/unit/test_distribution_release.py plus focused Program/runtime and packaged-entry probes.

Current-batch public-entry acceptance#

1. Each platform runtime archive contains a manifest with present and verified entries for web, providers, mcp, memory, channels, search, browser.playwright, ocr.default, model.gpa_detector, program.gui, program.research, and program.wiki.
2. Supported Desktop packaging consumes the already-built runtime archive. The CLI installer consumes the byte-identical archive from GitHub Release. Neither path resolves product dependencies independently.
3. A normal-user install performs no PyPI dependency resolution, repository clone, npm build, or first-use download for the default browser, OCR, detector model, or first-party Programs.
4. Public-entry probes verify the worker, Web assets, first-party Program registration, channel/search imports, Playwright Chromium executable, OCR model data, and detector model before an artifact is published or a CLI current link is switched.
5. macOS artifact names and documentation state unsigned; the release workflow requires no Apple or PyPI credentials and does not run signing, notarization, or PyPI publication.
6. Documentation does not present pip install openprogram, optional GUI/Research/Wiki installation, component-selection prompts, or an unverified Linux Desktop package as normal product installation.

Current-batch gate manifest#

python -m pytest tests/unit/test_distribution_release.py tests/unit/test_desktop_packaged_files.py tests/unit/test_webui_frontend.py
python -m tools.docs_site.checklinks
python -m tools.docs_site.build
python -m pytest tests/ --ignore=tests/integration
npm run check --prefix desktop
npm run check --prefix web
bash -n scripts/build-product-runtime.sh scripts/install-release.sh scripts/prepare-desktop-runtime.sh
git diff --check
git status --short

The platform runtime and public desktop artifact probes run on native release runners. A platform artifact is absent rather than published with a reduced capability manifest.

Current-batch evidence#

Prior packaging batch (historical evidence)#

• Base commit: 717d4e176307e08cc4ae4facd3c484511684746c.
• Public behavior: released wheels serve prebuilt Web assets without Node.js; packaged Electron apps start an embedded CPython runtime; macOS builds DMG and ZIP artifacts; Linux builds AppImage artifacts; release CI verifies versions and checksums.
• Product documentation describes only behavior whose acceptance checks pass.
• Windows native packaging was not implemented in this historical batch; it remains a deferred product decision rather than a rejected direction.
• OS credential-store integration remains excluded.

Prior-batch files#

• Production: openprogram/webui/frontend.py, pyproject.toml, desktop/main.js, desktop/package.json, release staging scripts, and the release workflow.
• Tests: frontend package-resource tests, desktop packaged-runtime checks, and release configuration checks.
• Documentation: the distribution HTML design, related design links, and install/upgrade/desktop/server product pages.

Prior-batch public-entry acceptance#

1. A wheel built after release asset staging contains openprogram/webui/_frontend/index.html and hashed Next.js assets; an isolated wheel install serves /chat without repository sources or Node.js.
2. A packaged Electron launch resolves the Python executable exclusively from process.resourcesPath, invokes -I -B -m openprogram worker start, does not fall back to PATH, and does not write bytecode into the signed application.
3. electron-builder declares macOS DMG/ZIP and Linux AppImage targets and includes the staged runtime as an immutable resource.
4. A tag-triggered release workflow builds each platform on its native runner, runs focused acceptance checks, and publishes checksums only after artifacts exist.

Prior-batch full gate manifest#

python -m pytest tests/unit/test_webui_frontend.py tests/unit/test_desktop_packaged_files.py tests/unit/test_distribution_release.py
python -m tools.docs_site.checklinks
python -m tools.docs_site.build
python -m pytest tests/ --ignore=tests/integration
npm run check --prefix desktop
npm run check --prefix web
git diff --check
git status --short

Platform artifact builds run in the release workflow because a macOS host cannot validate a Linux CPython/AppImage runtime and a Linux host cannot sign or notarize a macOS app.

Prior Linux completion batch#

• Base commit: 540591e9f628498dee87a1c2ebb30ab4c5e757f6.
• Production files: desktop/package.json, scripts/smoke-packaged-runtime.sh, scripts/install-release.sh, .github/workflows/release.yml, and .github/workflows/linux-release-smoke.yml.
• Test file: tests/unit/test_distribution_release.py.
• Linux x86_64 acceptance: build the AppImage on a native x86_64 runner, execute its public entry under Xvfb, let Electron start the embedded worker, verify /healthz, /chat, immutable Program behavior, and matching freedesktop filename/StartupWMClass metadata.
• Linux CLI acceptance: on native x86_64 and arm64 runners, install the release wheel with the pinned uv and managed CPython, cold-start the worker before switching current, and verify the installed launcher version.
• Pre-release execution: the manually dispatched Linux smoke workflow requires no Apple signing or PyPI credentials and uploads the verified wheel and AppImage only as CI artifacts. It does not create a stable release.
• This historical batch did not add Linux arm64 desktop artifacts, distro-native deb/rpm packages, Windows implementation, or OS credential-store integration. Windows remains deferred for a later product decision.

Prior-batch ledger#

Prior Linux completion evidence#