From 8eb396e983c8ceaea202c3a671b8a89bb19994f8 Mon Sep 17 00:00:00 2001
From: nandi <nandi@nandi.uk>
Date: Sun, 26 Jul 2026 01:20:33 -0700
Subject: [PATCH] Document why editors/zed still has Rust.

Explain that Zed Install Dev Extension always cargo-builds a Rust guest, so
src/glint.rs is temporary; pure Gleam remains the target via the wasm fork.
---
 README.md             | 26 +++++++++++++++++++++++
 editors/zed/README.md | 49 ++++++++++++++++++++++++++++++++++++-------
 2 files changed, 68 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index a1e5003..d51f133 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,32 @@ vim.api.nvim_create_autocmd("FileType", {
 
 **Zed** (dev extension in this repo — see also [`editors/zed/README.md`](editors/zed/README.md)):
 
+#### Why is there Rust under `editors/zed/`?
+
+Not because we want the extension authored in Rust. **Zed forces it today.**
+
+On **Install Dev Extension**, when `extension.toml` has `[lib] kind = "Rust"`
+(the only allowed kind), Zed always runs roughly:
+
+```text
+cargo build --target wasm32-wasip2
+```
+
+and writes `extension.wasm` from that crate. There is **no** install path that
+only loads a prebuilt component from `gleam export zed-extension`. Without
+`Cargo.toml` + `src/*.rs` you get `failed to compile Rust extension`.
+
+So `editors/zed/src/glint.rs` is a **thin temporary guest** (same behaviour as
+`zed_glint.gleam`: resolve `glint`, start LSP). Direction of travel is pure
+Gleam via our [wasm fork](https://tangled.org/nandi.uk/gleam); the `.rs` crate
+can go once Zed accepts prebuilt guests (or we use another install path).
+
+| Path | Role |
+|------|------|
+| `editors/zed/src/glint.rs` | What Zed can compile and install **now** |
+| `editors/zed/src/zed_glint.gleam` | Target authoring surface (pure Gleam) |
+| [nandi.uk/gleam](https://tangled.org/nandi.uk/gleam) `wasm` | Compiler that builds a real `zed:extension` component |
+
 ### 1. Build the glint binary
 
 ```sh
diff --git a/editors/zed/README.md b/editors/zed/README.md
index 5bec886..50f87b5 100644
--- a/editors/zed/README.md
+++ b/editors/zed/README.md
@@ -3,6 +3,44 @@
 Zed extension for Glint — language config, tree-sitter highlighting (via
 tree-sitter-gleam), and the glint language server.
 
+## Why is there Rust code here?
+
+Not because we want the extension authored in Rust. **Zed forces it today.**
+
+On **Install Dev Extension**, when `extension.toml` has:
+
+```toml
+[lib]
+kind = "Rust"
+```
+
+(`"Rust"` is the only allowed `kind`.) Zed always runs roughly:
+
+```text
+cargo build --target wasm32-wasip2
+```
+
+and writes `extension.wasm` from that crate. There is **no** install path that
+only loads a prebuilt Wasm from `gleam export zed-extension`.
+
+Without `Cargo.toml` + `src/*.rs` you get:
+
+- `failed to compile Rust extension` (no Cargo.toml), or  
+- invalid `kind` if you try anything other than `"Rust"`.
+
+So `src/glint.rs` is a **thin temporary guest** that implements the same idea
+as `src/zed_glint.gleam` (resolve `glint` on PATH / fallback, start the LSP).
+It is a **host/toolchain constraint**, not the product direction.
+
+| Path | Role |
+|------|------|
+| `src/glint.rs` | What Zed can compile and install **now** |
+| `src/zed_glint.gleam` | Target authoring surface (pure Gleam) |
+| [nandi.uk/gleam](https://tangled.org/nandi.uk/gleam) (`wasm` branch) | Compiler that builds a real `zed:extension` component |
+
+Once Zed accepts a prebuilt component (or we stop using Install Dev’s cargo
+path), the `.rs` crate can go away and the Gleam export path can own the guest.
+
 ## Compile
 
 ### Glint binary (LSP)
@@ -12,10 +50,7 @@ cd /home/nandi/code/glint
 nix build    # → result/bin/glint
 ```
 
-### Zed guest (Rust — what Install Dev Extension builds)
-
-Zed always runs `cargo build --target wasm32-wasip2` when
-`[lib] kind = "Rust"`. Local check:
+### Zed guest (Rust — required for Install Dev Extension today)
 
 ```sh
 cd /home/nandi/code/glint/editors/zed
@@ -42,8 +77,8 @@ cd /home/nandi/code/glint/editors/zed
 ```
 
 See `docs/compiler/wasm-zed-extensions.md` in that repo. Until Zed can load a
-prebuilt guest without cargo, **Install Dev Extension still uses the Rust
-crate** (`src/glint.rs`). `src/zed_glint.gleam` is the pure-Gleam sketch.
+prebuilt guest without cargo, **Install Dev Extension still overwrites with the
+Rust build**.
 
 ## Install in Zed
 
@@ -80,7 +115,7 @@ crate** (`src/glint.rs`). `src/zed_glint.gleam` is the pure-Gleam sketch.
 | Path | Role |
 |------|------|
 | `extension.toml` | Zed manifest |
-| `src/glint.rs` | Installable guest (`zed_extension_api`) |
+| `src/glint.rs` | Temporary installable guest (Zed cargo path) |
 | `src/zed_glint.gleam` | Pure-Gleam authoring sketch |
 | `languages/glint/` | Tree-sitter queries + language config |
 | `extension.wasm` | Built component (Zed / cargo) |
-- 
2.51.2