bong-water-water-bong · Sep 23, 2026 · Sep 23, 2026
diff --git a/README.md b/README.md
@@ -16,10 +16,10 @@ limitations under the License.
 -->
 # 1bit engine
 
-An inference engine for AMD Ryzen AI, built to run inside
-[Lemonade](https://github.com/lemonade-sdk/lemonade): the `1bit` binary serves one model behind an
-OpenAI-compatible API, whatever device runs it, and Lemonade (or any OpenAI client) launches it
-the way it launches `llama-server`. Behind that one API:
+**The 1bit engine runs inside [Lemonade](https://github.com/lemonade-sdk/lemonade).** Lemonade stays
+the server you talk to (its catalog, downloads, router and UI), and for the models it hands to 1bit,
+Lemonade runs the engine as one of its backends, the same way it runs `llama-server`. The engine
+serves each model behind an OpenAI-compatible API (`1bit serve`), whatever device runs it:
 
 - the XDNA 2 NPU engine
 - HRX and Vulkan on the Radeon iGPU, compiled together in one llama.cpp build
@@ -28,18 +28,18 @@ the way it launches `llama-server`. Behind that one API:
 - Laya, which decides where each request runs
 - every Hugging Face model architecture, kept current by a daily census
 
-> **Status:** `1bit serve` is the engine's front door ([docs/serve.md](docs/serve.md)): the NPU,
-> Vulkan, HRX and ZINC each pass its end-to-end test on Strix Halo. Following geramyL's review, the
-> engine is embedded into Lemonade rather than embedding it: the vendored Lemonade is gone, and a
-> Lemonade recipe that launches `1bit serve` is being prepared for upstream ([docs/lemonade.md](docs/lemonade.md)).
-> Ported so far: HRX + Vulkan in one build on AMD's live ggml-hrx ([docs/hrx.md](docs/hrx.md)), the NPU
-> engine on full ELFs with the upstream XDNA stack pinned ([docs/npu.md](docs/npu.md); its layer kernel
-> is not yet built from source), ZINC ([docs/zinc.md](docs/zinc.md)) and MLX
-> ([docs/apple.md](docs/apple.md)). Next is step 4, the Laya router. The working engine is being ported
-> from [1bit-MONSTER](https://github.com/1bit-MONSTER/1bit-MONSTER); see
-> [docs/PORTING.md](docs/PORTING.md). Measured results are on the
-> [wiki](https://github.com/1bit-MONSTER/engine/wiki). This repository holds the verified code
-> without the development history.
+> **Status:** the engine runs inside Lemonade through `1bit serve` ([docs/lemonade.md](docs/lemonade.md),
+> [docs/serve.md](docs/serve.md)); the NPU, Vulkan, HRX and ZINC each pass its end-to-end test on
+> Strix Halo, and the Lemonade recipe that runs it (`onebit`) passes Lemonade's own LLM test suite on
+> Vulkan and HRX and is being prepared for upstream. Following geramyL's review the engine no longer
+> vendors Lemonade: Lemonade is the host, 1bit is the engine inside it. Ported so far: HRX + Vulkan in
+> one build on AMD's live ggml-hrx ([docs/hrx.md](docs/hrx.md)), the NPU engine on full ELFs with the
+> upstream XDNA stack pinned ([docs/npu.md](docs/npu.md); its layer kernel is not yet built from
+> source), ZINC ([docs/zinc.md](docs/zinc.md)) and MLX ([docs/apple.md](docs/apple.md)). Next is step 4,
+> the Laya router. The working engine is being ported from
+> [1bit-MONSTER](https://github.com/1bit-MONSTER/1bit-MONSTER); see [docs/PORTING.md](docs/PORTING.md).
+> Measured results are on the [wiki](https://github.com/1bit-MONSTER/engine/wiki). This repository
+> holds the verified code without the development history.
 
 ## License
 
@@ -51,7 +51,7 @@ Apache-2.0. See [LICENSE](LICENSE).
 vibecoding, and that is where all of this started. Without it, this engine would not exist.
 
 **The Lemonade team and AMD's developers.** [Lemonade](https://github.com/lemonade-sdk/lemonade)
-is the home this engine is built to run in. AMD's developers left breadcrumbs all over the place: the XDNA driver
+is where this engine runs. AMD's developers left breadcrumbs all over the place: the XDNA driver
 and XRT, IRON and Peano, HRX, their tested llama.cpp integration, their issues, their examples.
 This engine is what following those breadcrumbs built.
 

diff --git a/app/main.cpp b/app/main.cpp
@@ -16,7 +16,7 @@
 //
 //   1bit serve -m <model>            one model on any device (NPU, Vulkan, HRX,
 //                                    ZINC, MLX) behind an OpenAI-compatible API;
-//                                    what a host such as Lemonade launches (docs/serve.md).
+//                                    how the engine runs inside Lemonade (docs/serve.md).
 //   1bit unified -m <model dir>      one native model on the NPU fast lane behind
 //                                    OpenAI endpoints; serve's NPU route.
 //   1bit npu-run [options]           token ids in, token ids out, on the NPU fast

diff --git a/app/serve.cpp b/app/serve.cpp
@@ -16,8 +16,8 @@
 // `1bit serve -m <model> [--port 8000] [--device auto|npu|vulkan|hrx|zinc]`
 //
 // The engine's one front door (docs/serve.md): one model per process behind an
-// OpenAI-compatible API, the contract a host such as Lemonade launches a
-// backend with:
+// OpenAI-compatible API. It is how the engine runs inside Lemonade: Lemonade's
+// onebit backend runs `1bit serve` the way it runs llama-server:
 //
 //   GET  /health, /v1/health     503 while the model loads, then 200
 //   GET  /v1/models              the one model

diff --git a/docs/PORTING.md b/docs/PORTING.md
@@ -21,7 +21,7 @@ Each step below is one PR (or a short series) that builds and runs on Strix Halo
 
 | Step | Component | Source in 1bit-MONSTER | Done when |
 |---|---|---|---|
-| 1 | **The engine as a backend.** One model per process behind an OpenAI-compatible API, `1bit serve`, for Lemonade (or any OpenAI client) to launch | `tools/unified_server.cpp` | **landed** ([docs/serve.md](serve.md)): NPU, Vulkan, HRX and ZINC pass `serve_e2e` on Strix Halo; `smoke_serve` runs in CI. The engine first embedded Lemonade (v11.9.0 plus local recipes); after geramyL's review it is embedded *into* Lemonade instead: the vendored copy is removed, and a Lemonade recipe that launches `1bit serve` is being prepared for upstream ([docs/lemonade.md](lemonade.md)) |
+| 1 | **The engine runs inside Lemonade.** Lemonade runs `1bit serve` as a backend: one model per process behind an OpenAI-compatible API | `tools/unified_server.cpp` | **landed** ([docs/serve.md](serve.md)): NPU, Vulkan, HRX and ZINC pass `serve_e2e` on Strix Halo; `smoke_serve` runs in CI. The engine first embedded Lemonade (v11.9.0 plus local recipes); after geramyL's review it is embedded *into* Lemonade instead: the vendored copy is removed, and a Lemonade recipe that launches `1bit serve` is being prepared for upstream ([docs/lemonade.md](lemonade.md)) |
 | 2 | **HRX with Vulkan.** llama.cpp with `GGML_HRX=ON` and `GGML_VULKAN=ON` in one build, on AMD's tested pair | `1bit-MONSTER/llama.cpp` `1bit/hrx-vulkan` (AMD's `hrx-graph-develop-v2`) + `ROCm/hrx-system`, pinned from `ROCm/ggml-staging-automation` | **landed** ([docs/hrx.md](hrx.md)): `1bit serve` runs the same checkpoint on `Vulkan0` and `HRX0`; kept current by `bump-hrx.yml` |
 | 3 | **NPU engine.** Full ELFs only, and the open 16-tile layer kernel built from source | `engine/npu` (`npu_engine_universal.cpp`, `I8Ctx::init_elf`); ELF dispatch table on `backup/iso-build-elf-native-2026-09-22`; kernel on `bench/fastlane-16tile-corrections-2026-09-22` | **3a–3c landed** ([docs/npu.md](npu.md)). 3a (#8): full ELFs generated in C++, reproducing all 5,153 captured contexts. 3b/3c (#9): the lane runtime (logits bit-identical to the reference lane, 24/24 steps, 11.0 ms/token), tokenizer, `1bit unified`, and Qwen3-0.6B served on the NPU (now through `1bit serve`). The XDNA driver and XRT are pinned upstream and built privately (#12). **Open:** the layer kernel and lm-head artifacts are not yet built from source (npu.md, "Open") |
 | + | **Linux kernel.** The kernel that provides `amdxdna` and `amdgpu`, pinned to upstream | `torvalds/linux` release tags; config from the Strix Halo kernel of 2026-09-23 | **pinned** ([docs/kernel.md](kernel.md)): v7.3-rc4 builds into Debian packages with `amdxdna` in-tree; kept current by `bump-linux.yml`. Installing it on Strix Halo is a separate, deliberate step |
@@ -32,8 +32,8 @@ Each step below is one PR (or a short series) that builds and runs on Strix Halo
 ## How the pieces fit
 
 ```
-Lemonade (or any OpenAI client)
-  └─ launches ─> 1bit serve -m <model> --port <p>      one OpenAI-compatible API
+Lemonade (the host users talk to)
+  └─ runs, as its onebit backend ─> 1bit serve -m <model> --port <p>   one OpenAI-compatible API
                    ├─ NPU model directory ──> NPU fast lane (full ELFs), in process
                    ├─ .gguf --device vulkan|hrx ──> this build's llama.cpp (ggml-vulkan + ggml-hrx)
                    ├─ .gguf --device zinc ──> this build's ZINC (Vulkan, ROCm, CUDA)

diff --git a/docs/lemonade.md b/docs/lemonade.md
@@ -16,11 +16,11 @@ limitations under the License.
 -->
 # Lemonade
 
-The engine is a backend that [Lemonade](https://github.com/lemonade-sdk/lemonade)
-launches, the way it launches `llama-server`. The engine exposes only an
-OpenAI-compatible API (`1bit serve`, [serve.md](serve.md)), and Lemonade stays
-what it is: the server users talk to, with its own catalog, downloads, router
-and UI.
+**The 1bit engine runs inside [Lemonade](https://github.com/lemonade-sdk/lemonade).** Lemonade is
+the server users talk to, with its own catalog, downloads, router and UI. For the models it
+serves with 1bit, it runs the engine as a backend, the same way it runs `llama-server`: it starts
+`1bit serve` ([serve.md](serve.md)), waits for `/health`, and forwards OpenAI requests to it. The
+engine exposes nothing but that OpenAI-compatible API.
 
 ## How it got here
 
@@ -35,22 +35,25 @@ the reverse. So on 2026-09-23:
 - `1bit serve` took over what the local recipes did, for every device: NPU,
   Vulkan, HRX, ZINC and MLX.
 
-## What Lemonade needs
+## The recipe that runs it
 
-One recipe in upstream Lemonade that launches the engine, in the same shape as
-its `llama-server` recipe:
+One recipe in Lemonade runs the engine, `onebit`, in the same shape as its
+`llama-server` recipe:
 
 ```
 1bit serve -m <model> --port <p> [--device ...] [--ctx-size N] [--alias <name>]
 ```
 
-It then waits for `/health` to answer 200 and forwards OpenAI requests to
-`/v1/chat/completions` and `/v1/completions`. That recipe is being prepared as
-a pull request to `lemonade-sdk/lemonade`.
+Lemonade downloads and resolves GGUF checkpoints as for llamacpp, and its
+backend selector picks the device (`vulkan`, `hrx`, `npu`, or `cuda` through
+ZINC). Replies already carry Lemonade's model name (`--alias`), so requests pass
+through unchanged. On Strix Halo the recipe passes Lemonade's own LLM test suite
+(`test/server_llm.py --wrapped-server onebit`) on Vulkan and HRX. It is being
+prepared as a pull request to `lemonade-sdk/lemonade`.
 
-## Until then
+## On its own
 
-Point any OpenAI client at `1bit serve` directly:
+`1bit serve` also works without Lemonade, for any OpenAI client:
 
 ```sh
 1bit serve -m ~/models/Qwen3-0.6B-Q4_K_M.gguf --device vulkan --port 8000

diff --git a/docs/npu.md b/docs/npu.md
@@ -45,8 +45,8 @@ Step 3 lands in three parts:
 ```
 
 `1bit serve -m <model dir>` serves such a directory on the NPU behind the
-OpenAI-compatible API ([serve.md](serve.md)); a host such as Lemonade launches
-it like any other backend.
+OpenAI-compatible API ([serve.md](serve.md)); inside Lemonade, that is what its
+onebit backend runs (`--onebit npu`).
 
 ## Inputs
 

diff --git a/docs/serve.md b/docs/serve.md
@@ -16,9 +16,10 @@ limitations under the License.
 -->
 # `1bit serve`: the engine behind one OpenAI-compatible API
 
-The engine is a backend that a host launches, the way Lemonade launches
-`llama-server`. It exposes nothing but an OpenAI-compatible API
-([lemonade.md](lemonade.md)).
+The engine runs inside Lemonade ([lemonade.md](lemonade.md)): Lemonade runs
+`1bit serve` as a backend, the way it runs `llama-server`. `1bit serve` exposes
+nothing but an OpenAI-compatible API, so it also works on its own with any
+OpenAI client.
 
 ```sh
 1bit serve -m <model> [--port 8000] [--host 127.0.0.1]