# Using gasm-devkit with Zed

This document is deliberately blunt, because the situation is a genuine
conflict between two of the project's own commitments, and papering over it
would be dishonest.

## The conflict

gasm-devkit is **pure Go, no C, no cgo, no JavaScript runtimes, no native
binaries, no vendor lock-in, no platform-specific IDE internals.**

Zed's extension model, as verified against Zed's own documentation, is:

- Extensions are written in **Rust** and compiled to **WebAssembly**
  (`wasm32-wasip2`).
- Syntax highlighting is provided by **Tree-sitter** grammars, which are
  **C** compiled to WebAssembly with the wasi-sdk, from a grammar written in a
  **JavaScript** DSL.
- A *new* language cannot be registered through configuration alone.  Defining
  a language requires an extension, and every language extension must name a
  Tree-sitter grammar.  (Zed's `lsp` settings section configures
  already-registered servers; it does not register an arbitrary external binary
  for a brand-new language.)

There is therefore **no pure-Go path into Zed's extension host.**  This is a
property of Zed, not of gasm-devkit: no language tooling author can feed Zed a
pure-Go highlighting grammar, because Zed's highlighting engine is Tree-sitter
and its plugin runtime is Rust/WASM.

## What gasm-devkit gives Zed regardless

The toolkit's integration surface is the **Language Server Protocol**, an open
standard.  Through `gasm lsp` it provides, with zero editor-specific code:

- autocomplete (instructions, registers, pseudo-registers, labels),
- hover documentation,
- diagnostics (the linter, pushed as you type),
- document outline (functions and labels),
- **syntax highlighting, delivered as LSP semantic tokens.**

That last point matters: Zed can render highlighting entirely from LSP semantic
tokens (`"semantic_tokens": "full"` replaces Tree-sitter highlighting for a
language).  So the highlighting *capability* exists in pure Go; what Zed needs
is merely to be told that `.s` files are a language served by `gasm lsp`.

## The honest options

1. **Use an editor that registers an external LSP by configuration.**
   Neovim, Helix, VS Code and Sublime all let you associate `.s` with the
   `gasm lsp` binary and use its semantic tokens — no Rust, no C, no lock-in.
   This is the option that satisfies every stated constraint with no
   exception.

2. **Treat a Zed adapter as one quarantined exception.**  A minimal Zed
   extension — a few lines of Rust that register the language and launch
   `gasm lsp` — plus either a Tree-sitter grammar or `"full"` semantic tokens
   for highlighting.  Crucially, this adapter is the *editor's plugin format*;
   it is sandboxed inside Zed and never linked into, compiled into, or shipped
   with the Go toolkit.  gasm-devkit itself stays pure Go.  But producing it
   uses the Rust/wasi-sdk/Tree-sitter toolchain, which the project constraints
   forbid — so it must be a conscious, explicit decision, not a silent one.

The author's philosophy — digital sovereignty, no dependency on toolchains he
does not control — is the tie-breaker, and it is a value judgement rather than
a technical one.  gasm-devkit is built so that **either** choice keeps the
toolkit itself clean: the pure-Go core and the LSP are the product; a Zed
adapter, if ever wanted, is a thin, separable leaf.

## Wiring the LSP (editor-agnostic)

Run the server and point an LSP client at it:

```sh
go run ./cmd/gasm lsp        # or: go install ./cmd/gasm && gasm lsp
```

Associate the command with `*.s` (and `*_amd64.s` / `*_arm64.s`) in whichever
editor you use.  The server infers the target architecture from the file-name
suffix and selects the amd64 or arm64 instruction tables accordingly.