freeman-1984-coder · freeman-1984-coder · Sep 13, 2026 · Sep 13, 2026
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -3,7 +3,7 @@ recursive-include examples *.py *.gd *.uid *.godot *.tscn *.md
 recursive-include scripts *.py *.mjs
 recursive-include models *.json *.md
 recursive-include tests *.py *.json
-recursive-include docs *.md
+recursive-include docs *.md *.json *.xml *.txt *.csv
 recursive-include site *.json *.html *.css *.txt *.xml *.js *.wav .nojekyll
 recursive-include .github *.yml *.md
 include packages/js/package.json packages/js/package-lock.json packages/js/tsconfig.json

diff --git a/README.md b/README.md
@@ -1,9 +1,9 @@
 # flybrain-sdk
 
-> Development branch: [experimental CUDA backend](docs/cuda.md). [Full FlyWire benchmark](docs/validation/flywire-full-a16.md): 139,255 neurons, all 16.85M source rows, CPU/CUDA parity and 10 seconds of continuous simulation on A16-8Q. CUDA median 11.55 seconds per simulated second (not real time). [Train an external reflex readout](examples/REFLEX_TRAINING.md). Released v0.4.0a4 is CPU-only.
+**No CUDA required.** A Python SDK for connecting small connectome simulations to games and experiments, starting with a working NumPy CPU backend.
 
+> **0.5 alpha:** [optional CUDA, tested on NVIDIA hardware](docs/cuda.md), a separately versioned [synaptic mV engine](docs/synaptic-dynamics.md), and reproducible [full-brain GPU experiments](https://freeman-1984-coder.github.io/flybrain-sdk/odor-calibration.html). CPU remains the default. Full-brain navigation and real-time performance are not established.
 
-**No CUDA required.** A Python SDK for connecting small connectome simulations to games and experiments, starting with a working NumPy CPU backend.
 
 **Full-brain sensory result:** [The GPU odor probe activates the input cells but exposes a propagation limit in the benchmark weight preset](docs/validation/flywire-odor-a16.md). Numerical parity does not establish biological behavior. [Published report](https://freeman-1984-coder.github.io/flybrain-sdk/fullbrain.html#olfaction).
 
@@ -29,7 +29,7 @@ brain.step(100)
 print(brain.action().to_dict())
 ```
 
-**0.4 alpha:** the bundled offline demo is a hand-authored 12-neuron circuit. A separate 3.8 MB MaleCNS model now runs 313 real source neurons and 20,607 anatomical edges with explicitly assumed LIF parameters. [Model card and reproducible recipe](models/male-cns-escape-v1/README.md). This development branch adds an experimental CUDA runtime; WASM remains unimplemented. No GPU, credentials, or network access are needed to run the toy demo after installation.
+**0.5 alpha:** the bundled offline demo is a hand-authored 12-neuron circuit. A separate 3.8 MB MaleCNS model now runs 313 real source neurons and 20,607 anatomical edges with explicitly assumed LIF parameters. [Model card and reproducible recipe](models/male-cns-escape-v1/README.md). This release includes an experimental CUDA runtime; WASM remains unimplemented. No GPU, credentials, or network access are needed to run the toy demo after installation.
 
 ## Make your own demo
 
@@ -86,7 +86,7 @@ pytest
 The package is **not yet published to PyPI**. Install directly from GitHub without cloning:
 
 ```sh
-python -m pip install "flybrain-sdk @ git+https://github.com/freeman-1984-coder/flybrain-sdk.git"
+python -m pip install "flybrain-sdk @ git+https://github.com/freeman-1984-coder/flybrain-sdk.git@v0.5.0a1"
 ```
 
 Normal installation needs only NumPy at runtime. Offline operation means the demo makes no network requests; initial dependency installation needs an existing wheel cache or internet access.

diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md
@@ -1,5 +1,7 @@
 # flybrain-sdk：无需 CUDA 的果蝇连接组仿真 SDK
 
+**0.5 alpha：** 可选 CUDA 已通过 NVIDIA A16 实机验证；新增完整 FlyWire 脑的 GPU 实验、独立验证的突触 LIF 模型，以及气味输入和恢复期的公开记录。CPU 仍然默认可用，无需 CUDA。[GPU 使用说明](cuda.md) · [全脑气味对比](https://freeman-1984-coder.github.io/flybrain-sdk/odor-calibration.html)。全脑实验尚未证明可靠觅食或实时性能。
+
 0.4 新增：统一 Session 循环、可替换输入/输出/环境、避障和声音模板、完整过程回放，以及可继续生成的 WAV。试用[示例与音频](https://freeman-1984-coder.github.io/flybrain-sdk/demos.html)，查看[接入指南](demo-kits.md)。示例页是明确标注的录制回放；实验室仍是浏览器现场仿真。
 
 
@@ -23,7 +25,7 @@ print(brain.action().to_dict())
 ```
 
 支持按 ID/注释选择细胞、直接注入电流、只观察指定细胞，以及可恢复的静默干预。
-新检查点保存自定义输出和刺激，继续兼容旧检查点。CUDA/WASM 尚未实现。
+新检查点保存自定义输出和刺激，继续兼容旧检查点。0.5 alpha 增加可选 CUDA；WASM 仍未实现。
 详见 [API](api.md)、[模型卡](../models/male-cns-escape-v1/README.md) 和
 [整体设计](rfcs/0001-open-runtime-and-demo-kits.zh-CN.md)。
 
@@ -55,7 +57,7 @@ paths = fetch_model("flywire-v783", assets=["neuron_ids"])
 
 真实连接组是神经连接数据，还需要参数、感觉/动作映射和转换器，才能成为
 可直接加载的仿真模型。目前没有宣称全脑实时运行、学习能力或真实果蝇行为。
-WASM/CUDA 只预留接口。欢迎通过 Issue 和 Pull Request 一起完善；无需 GPU。
+WASM 仍只预留接口，CUDA 为可选实验后端。欢迎通过 Issue 和 Pull Request 一起完善；无需 GPU。
 
 [英文首页](../README.md) · [贡献指南](../CONTRIBUTING.md) · [真实数据接入计划](real-data.md)
 

diff --git a/docs/api.md b/docs/api.md
@@ -139,7 +139,7 @@ accepts an observation with `offer(seq, observation)`, then commits the actual
 engine control with `acknowledge(seq, applied)`. Only one action may be pending.
 Identical pending offers reuse their result without reintegrating the brain.
 `snapshot()` is allowed at acknowledged boundaries; `from_snapshot(data, backend=None)` restores
-the built-in linear encoder and rate readout. In this CUDA development branch,
+the built-in linear encoder and rate readout. In version 0.5 alpha,
 pass `backend="cpu"` or `backend="cuda"` to select the restore device explicitly.
 The engine must checkpoint its own
 world at the matching sequence. See the [Godot example](../examples/godot/README.md)

diff --git a/docs/cuda.md b/docs/cuda.md
@@ -1,6 +1,6 @@
 # Experimental CUDA backend — A16 hardware validation passed
 
-This development branch implements a CuPy/CUDA reference backend. **All 12 required hardware cases passed on a Vultr NVIDIA A16-2Q on 2026-09-12 UTC.** The published v0.4.0a4 remains CPU-only. This is experimental compatibility support, not a speedup claim: the 313-cell model took 2.64 seconds per simulated second on this GPU, versus 0.108 seconds on the same host CPU. See [the measured report](validation/a16-20260912.md).
+Version 0.5 alpha includes a CuPy/CUDA reference backend. **All 12 required hardware cases passed on a Vultr NVIDIA A16-2Q on 2026-09-12 UTC.** The older v0.4.0a4 release is CPU-only. This is experimental compatibility support, not a speedup claim: the 313-cell model took 2.64 seconds per simulated second on this GPU, versus 0.108 seconds on the same host CPU. See [the measured report](validation/a16-20260912.md).
 
 ## Optional installation
 
@@ -70,9 +70,9 @@ This command starts remote compute and can incur charges. As checked on 2026-09-
 
 The runner definition was checked against the local Modal SDK without invoking any remote function. It remains untested remotely. [Modal GPU documentation](https://modal.com/docs/guide/gpu) describes device selection. Recheck container termination and actual billed usage before considering the rental step finished.
 
-## Game integration (development branch only)
+## Game integration (0.5 alpha)
 
-The draft now includes the v0.4.0a4 Godot and project-generation changes.
+CUDA integrates with the Godot and project-generation APIs introduced in v0.4.0a4.
 `make_demo(..., backend="cuda")` selects CUDA for Python sessions.
 `ExternalController.from_snapshot(data, backend="cpu")` explicitly restores a
 GPU checkpoint onto CPU, or vice versa with `backend="cuda"`. The new hardware

diff --git a/docs/development-goal.md b/docs/development-goal.md
@@ -13,7 +13,7 @@ streaming audio and validated biological learning remain future work.
 The live browser game now shares the JS CPU core and is checked against Python feedback.
 Basic composable sessions, recorded dodge/sonification kits and full feedback replay
 are implemented. CUDA passed actual A16 validation and merged into main, while
-the last tagged release (v0.4.0a4) remains CPU-only.
+the older v0.4.0a4 release is CPU-only; version 0.5 integrates the CUDA engines.
 
 Acceptance criteria:
 
@@ -56,7 +56,8 @@ not. A recorded negative outcome is not evidence of learned or reliable foraging
 
 The [historical delivery audit](completion-audit-2026-09-10.md) predates CUDA
 validation. Current evidence is in [CUDA](cuda.md), [full-brain validation](fullbrain-validation.md)
-and [synaptic dynamics](synaptic-dynamics.md). The remaining delivery gate is an
-integrated release with final packaging, clean-install and public-site verification.
+and [synaptic dynamics](synaptic-dynamics.md). Integrated-release closure requires
+final packaging, clean-install and public-site verification according to the
+[release checklist](releasing.md).
 The [odor gain pilot](odor-calibration-pilot.md) is a separately documented research
 experiment, not a substitute for that release gate.
diff --git a/docs/release-v0.5.0a1.md b/docs/release-v0.5.0a1.md
@@ -0,0 +1,46 @@
+# flybrain-sdk 0.5.0a1
+
+**No CUDA required.** This alpha integrates optional, actual-device-tested CUDA
+with the CPU SDK, real MaleCNS model, browser demos and Godot adapter.
+Install from the GitHub release wheel or the `v0.5.0a1` tag; there is no PyPI/NPM
+publication. CUDA additionally needs a compatible NVIDIA driver and CuPy.
+
+## Included
+
+- CPU-default `FlyBrain` API with on-demand, checksum-verified real model downloads,
+  direct cell input/observation, custom readouts, silencing and complete checkpoints.
+- Optional CUDA backend with 12 passing actual A16 hardware cases. The 313-cell
+  workload was slower on GPU; small models should generally stay on CPU.
+- Experimental synaptic mV CPU/CUDA engines, checked against Brian2 and five actual
+  GPU cases. These explicitly require mV weights; existing dimensionless models
+  and checkpoints keep their meaning.
+- Full FlyWire numerical and sensory experiments, a GPU voxel recording, and an
+  eight-run odor gain pilot. All source neurons and aggregate edges are retained.
+  Original records, source hashes, assumptions and negative results are public.
+- Editable demo generation, verified session replay and the Godot CPU/CUDA bridge.
+  Generated project requirements pin this public Git tag.
+- Source distributions include the JSON/XML/CSV/text validation evidence referenced
+  by the documentation, in addition to reports, examples and model recipes.
+
+## Limits
+
+The packaged ready real model is still the 313-neuron MaleCNS subgraph with assumed
+LIF dynamics. Full FlyWire loading is an explicit research-script/data-download
+workflow, not a ready catalog model or a `FlyBrain.load()` preset. Its complete
+network was run on GPU, but biological physiology, reliable foraging and real-time
+performance have not been established. The voxel and reflex web pages replay
+recorded experiments; the circuit lab and game sandbox execute the JS CPU runtime.
+WASM and biological synaptic plasticity remain unimplemented.
+
+The odor pilot changed no behavior default. Its one-seed comparison could not
+establish a responsive navigation preset by scaling all contact weights alone.
+A temporary early side response must not be described as banana identification.
+
+## Evidence
+
+- [Actual CUDA validation](cuda.md) and [full FlyWire benchmark](fullbrain-validation.md).
+- [Synaptic dynamics and independent reference](synaptic-dynamics.md).
+- [Full-brain voxel experiment](validation/flywire-voxel-a16.md).
+- [All eight odor gain conditions](validation/odor-gain-pilot-a16.md).
+- [Release procedure](releasing.md), including clean-wheel installation,
+  source-archive completeness and post-tag generated-project installation.
diff --git a/docs/releasing.md b/docs/releasing.md
@@ -4,11 +4,15 @@ The repository name and package name are provisional. PyPI/NPM name availability
 and account ownership must be checked before attempting registry publication.
 This project currently supports installation from GitHub and release wheels.
 
-1. Run CI, quickstart, `python -m build` and `python -m twine check dist/*`.
-2. Install the built wheel in a clean environment, outside the checkout; verify the
+1. Update version in `pyproject.toml` and `src/flybrain/__init__.py`; write release notes.
+2. Run CI, quickstart, `python -m build` and `python -m twine check dist/*`.
+3. Install the built wheel in a clean environment, outside the checkout; verify the
    toy, registry catalog, and checkpoint roundtrip are included and usable.
-3. Update version in `pyproject.toml` and `src/flybrain/__init__.py`; write release notes.
+   Verify that the source archive includes referenced validation JSON/XML/CSV/text
+   evidence, not only the Markdown reports. Check optional CUDA imports without CuPy.
 4. Create a version tag and GitHub release, attaching the wheel and source distribution.
+   After the tag is public, install a generated demo's `requirements.txt` in another
+   clean environment and run it: project generation pins this exact public tag.
 5. Configure PyPI trusted publishing under the real package owner before publishing
    to PyPI. Start on TestPyPI if needed. Never put publishing tokens into this repo.
 

diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -1,6 +1,6 @@
 # Roadmap
 
-## Verified in current source; next release pending
+## Version 0.5.0a1
 
 - Optional CUDA backend passed actual NVIDIA A16 conformance checks. CPU remains
   the default and does not require CuPy. See [CUDA evidence](cuda.md).
@@ -14,8 +14,8 @@
 - [Odor gain pilot protocol](odor-calibration-pilot.md) separates transient side
   responses from persistent activity before further behavioral calibration.
 
-The released v0.4.0a4 remains CPU-only. An integrated CUDA release still requires
-packaging and clean-install verification at its final release commit. Raw full-brain
+The older v0.4.0a4 release is CPU-only. Version 0.5 integrates the verified CUDA
+engines; see the [release checklist](releasing.md) for distribution checks. Raw full-brain
 loading remains a research-script workflow, not a `FlyBrain.load()` catalog entry.
 
 ## Available in 0.4.0a4
@@ -92,7 +92,7 @@ proposed architecture; proposal-only APIs are not current API documentation.
 - Extend Godot, add Unity and richer game examples.
 - Compact sparse-array model/checkpoint format for large graphs.
 - WASM reference implementation and TypeScript package.
-- Publish the integrated optional CUDA release after clean-install checks.
+- Improve the optional CUDA backend with separately benchmarked batching.
 - Explore learning/plasticity separately from the fixed-connectome MVP.
 
 Open issues and propose focused milestones; these are directions, not release-date promises.
diff --git a/docs/validation/release-v05-installed.json b/docs/validation/release-v05-installed.json
@@ -0,0 +1,27 @@
+{
+  "version": "0.5.0a1",
+  "python": "3.12.14",
+  "numpy": "2.5.3",
+  "installed_from_wheel": true,
+  "cuda_absent": true,
+  "toy_continuation_ticks": 100,
+  "explicit_download_required": true,
+  "download_and_load_seconds": 1.594029749976471,
+  "bundle_sha256": "sha256:ff38cfff0c76345cc2f250e992f95b0bf19863b434d8f97f926da6975cb93a35",
+  "neurons": 313,
+  "edges": 20607,
+  "model_fingerprint": "47a0c91b3eba9c606c29faef58fe15c8846fc049c4314a5e3b6912ab22c5e68a",
+  "real_continuation_ticks": 100,
+  "paired_continuation_check_seconds": 3.8312330830376595,
+  "real_action": {
+    "walk": 0.0,
+    "turn_left": 0.0,
+    "turn_right": 0.0,
+    "jump": 0.5526662751885896
+  },
+  "corrupt_cache_rejected": true,
+  "cuda_error": "CUDA requires a working NVIDIA driver, visible GPU and compatible CuPy. Install the appropriate cupy-cuda12x or cupy-cuda13x wheel. CPU remains available without them. Cause: No module named 'cupy'",
+  "synaptic_inflight_replay_ticks": 50,
+  "generated_requirement_pins_release": true,
+  "status": "passed"
+}
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flybrain-sdk"
-version = "0.5.0.dev0"
+version = "0.5.0a1"
 description = "CPU-first connectome simulation for games and experiments. No CUDA required."
 readme = "README.md"
 requires-python = ">=3.9"

diff --git a/site/api.html b/site/api.html
@@ -4,7 +4,7 @@
 <link rel="canonical" href="https://freeman-1984-coder.github.io/flybrain-sdk/api.html"><meta name="robots" content="index,follow">
 <meta property="og:type" content="website"><meta property="og:title" content="Python API and quickstart — flybrain-sdk">
 <meta property="og:description" content="Install flybrain-sdk from GitHub and run a CPU LIF simulation with load, stimulate, step, action, save and restore. No CUDA required."><meta property="og:url" content="https://freeman-1984-coder.github.io/flybrain-sdk/api.html">
-<link rel="stylesheet" href="style.css"><script type="application/ld+json">{"@context": "https://schema.org", "@type": "SoftwareSourceCode", "name": "flybrain-sdk", "description": "Install flybrain-sdk from GitHub and run a CPU LIF simulation with load, stimulate, step, action, save and restore. No CUDA required.", "codeRepository": "https://github.com/freeman-1984-coder/flybrain-sdk", "url": "https://freeman-1984-coder.github.io/flybrain-sdk/", "programmingLanguage": ["Python", "TypeScript"], "runtimePlatform": "Python 3.9+ / NumPy CPU", "license": "https://github.com/freeman-1984-coder/flybrain-sdk/blob/main/LICENSE", "version": "0.4.0a4"}</script></head>
+<link rel="stylesheet" href="style.css"><script type="application/ld+json">{"@context": "https://schema.org", "@type": "SoftwareSourceCode", "name": "flybrain-sdk", "description": "Install flybrain-sdk from GitHub and run a CPU LIF simulation with load, stimulate, step, action, save and restore. No CUDA required.", "codeRepository": "https://github.com/freeman-1984-coder/flybrain-sdk", "url": "https://freeman-1984-coder.github.io/flybrain-sdk/", "programmingLanguage": ["Python", "TypeScript"], "runtimePlatform": "Python 3.9+ / NumPy CPU", "license": "https://github.com/freeman-1984-coder/flybrain-sdk/blob/main/LICENSE", "version": "0.5.0a1"}</script></head>
 <body><a class="skip" href="#main">Skip to content</a><div class="wrap"><header class="nav"><a class="brand" href="./">flybrain<span>_sdk</span></a><nav aria-label="Main navigation"><a href="live.html">Live sandbox</a><a href="demos.html">Demo kits</a><a href="lab.html">Circuit lab</a><a href="api.html">Python API</a><a href="models.html">Models</a><a href="contribute.html">Contribute</a><a href="https://github.com/freeman-1984-coder/flybrain-sdk">GitHub ↗</a></nav></header><main id="main"><article class="article"><div class="eyebrow">Developer guide / Python</div><h1>From install to action.</h1><p>Python 3.9+ and NumPy. No CUDA required. The package is currently installed from source; it has not yet been published to PyPI.</p><div class="code"><div class="label">Terminal</div><pre><code>git clone https://github.com/freeman-1984-coder/flybrain-sdk.git
 cd flybrain-sdk
 python -m venv .venv