Move the LSP and editor docs and the Zed scaffold from bifrost-dev

README.md

@@ -6,8 +6,8 @@ standalone Bifrost language server. It contains the independent Rust
 the extension and its release workflows. The extension remains published as
 `brokk/bifrost-vscode` on Open VSX.
 
-The first extension release from this repository is `0.12.0`, following the
-currently published `0.11.4`. Extension versions, standalone server versions,
+The current published extension release from this repository is `0.12.0`.
+Extension versions, standalone server versions,
 and compatible Bifrost engine versions are intentionally independent. Release
 qualification injects the server version and SHA-256 hashes into the VSIX.
 Extension releases use self-describing
@@ -16,6 +16,16 @@ exactly match the committed manifest.
 
 See [RELEASING.md](RELEASING.md) for qualification and external setup.
 
+## Documentation
+
+- [LSP Server](docs/lsp.md): server releases, startup, and compatibility.
+- [VS Code LSP](docs/vscode.md): install and configure the VS Code extension.
+- [RQL in VS Code](docs/rql-vscode.md): write queries and policies in VS Code.
+- [Zed LSP](docs/zed.md): status of Zed language-server support and the
+  unpublished scaffold in [`editors/zed`](editors/zed/).
+- [Neovim and Vim LSP](docs/neovim.md): configure Neovim and Vim clients.
+- [Helix LSP](docs/helix.md): configure the Helix language-server client.
+
 Open semantic packs and policies come from
 [BrokkAi/bifrost-packs](https://github.com/BrokkAi/bifrost-packs). The server
 reports the exact linked engine through `pack-engine-profile` and the LSP

docs/helix.md

@@ -0,0 +1,133 @@
+# Helix LSP
+
+Helix can start the Bifrost language server, `bifrost-lsp`, through its built-in language-server configuration. No Bifrost-specific Helix plugin is needed.
+
+> [!CAUTION]
+> **bifrost-lsp v0.1.1 is released**
+> Bifrost built after release 0.12.0 does not serve LSP: `bifrost --lsp` exits with an error. The language server is the separate `bifrost-lsp` program, now available as v0.1.1. The configuration below starts it with `bifrost-lsp --root .`. See [LSP Server](./lsp.md) for details.
+
+Put this in `~/.config/helix/languages.toml`, start Helix from the workspace root, and open a supported source file:
+
+```toml
+[language-server.bifrost]
+command = "bifrost-lsp"
+args = ["--root", "."]
+
+[[language]]
+name = "c"
+language-servers = ["bifrost"]
+
+[[language]]
+name = "cpp"
+language-servers = ["bifrost"]
+
+[[language]]
+name = "c-sharp"
+language-servers = ["bifrost"]
+
+[[language]]
+name = "go"
+language-servers = ["bifrost"]
+
+[[language]]
+name = "java"
+language-servers = ["bifrost"]
+
+[[language]]
+name = "javascript"
+language-servers = ["bifrost"]
+
+[[language]]
+name = "jsx"
+language-servers = ["bifrost"]
+
+[[language]]
+name = "typescript"
+language-servers = ["bifrost"]
+
+[[language]]
+name = "tsx"
+language-servers = ["bifrost"]
+
+[[language]]
+name = "php"
+language-servers = ["bifrost"]
+
+[[language]]
+name = "python"
+language-servers = ["bifrost"]
+
+[[language]]
+name = "ruby"
+language-servers = ["bifrost"]
+
+[[language]]
+name = "rust"
+language-servers = ["bifrost"]
+
+[[language]]
+name = "scala"
+language-servers = ["bifrost"]
+
+[[language]]
+name = "kotlin"
+language-servers = ["bifrost"]
+```
+
+This assumes `bifrost-lsp` is on `PATH`. If it is not, set `command` to the absolute path of the binary.
+
+Bifrost handles only the languages that list `bifrost` in `language-servers`. Remove the entries for languages you do not want it to handle.
+
+## Workspace Roots
+
+`--root` is the fallback workspace root. Helix sends the current working directory as `rootPath`, so `args = ["--root", "."]` works when you start Helix from the repository root:
+
+```bash
+cd /path/to/project
+hx src/main/java/example/App.java
+```
+
+If you start Helix outside the project, pass an absolute root instead:
+
+```toml
+[language-server.bifrost]
+command = "bifrost-lsp"
+args = ["--root", "/path/to/project"]
+```
+
+Helix supports multiple language servers per language. If you want Bifrost to coexist with a language-specific server, include both names in that language's list:
+
+```toml
+[[language]]
+name = "java"
+language-servers = ["bifrost", "jdtls"]
+```
+
+Running multiple servers can be useful when another server provides formatting or diagnostics, but it can also produce duplicate or competing navigation results. Keep the `language-servers` list to Bifrost alone if you want Bifrost to be the only server Helix uses for that language.
+
+## Confirm Bifrost Is Running
+
+Check that Helix can find the configured Bifrost server:
+
+```bash
+hx --health java
+```
+
+The language server section should list `bifrost` with a check mark and the command path Helix will run.
+
+To capture startup and request logs, launch Helix with an explicit log file:
+
+```bash
+hx -vvv --log /tmp/helix-bifrost.log src/main/java/example/App.java
+```
+
+Open a supported file and use Helix's normal LSP navigation commands, such as `gd` for go to definition or `gr` for references. The log should show `initialize`, `textDocument/definition`, or `textDocument/references` messages for `bifrost`.
+
+For request timing from the server, set the two variables that the VS Code extension passes to `bifrost-lsp`. `BIFROST_LSP_DEBUG = "1"` logs every request and notification. `BIFROST_LSP_SLOW_MS` logs requests that take at least that many milliseconds; `0` logs all of them. The `bifrost` CLI does not read these variables. See [LSP Server](./lsp.md).
+
+```toml
+[language-server.bifrost]
+command = "bifrost-lsp"
+args = ["--root", "."]
+environment = { BIFROST_LSP_DEBUG = "1", BIFROST_LSP_SLOW_MS = "0" }
+```

docs/lsp.md

@@ -0,0 +1,158 @@
+# LSP Server
+
+The `bifrost` command no longer serves the Language Server Protocol (LSP). The
+language server is a separate program named `bifrost-lsp`. It comes from the
+[BrokkAi/bifrost-lsp](https://github.com/BrokkAi/bifrost-lsp) repository.
+
+> [!CAUTION]
+> **bifrost-lsp v0.1.1 was released on 2026-10-08**
+> The VS Code extension source is configured to download and install the
+> standalone `bifrost-lsp` server in editor global storage. See
+> [VS Code LSP](./vscode.md) for its managed-server behavior.
+
+## Which Bifrost Versions Serve LSP
+
+| Bifrost build | `bifrost --lsp` |
+| --- | --- |
+| Released 0.12.0 and earlier | Serves LSP over stdio. |
+| Built from later source, including development builds that still report version 0.12.0 | Prints `the LSP server has moved out of this repository` and exits with status 1. |
+
+`bifrost --server lsp` behaves the same way as `bifrost --lsp`. The released
+`bifrost-lsp` server gives you two working options:
+
+- In VS Code or Cursor, use the extension's managed `bifrost-lsp` v0.1.1
+  download when using extension version 0.12.0. See [VS Code LSP](./vscode.md).
+- In another editor, start the `bifrost-lsp` v0.1.1 binary with
+  `bifrost-lsp --root <workspace-root>`.
+
+The Claude Code agent plugin registers an LSP server that runs `bifrost
+--lsp`. It works only with the plugin's pinned release, Bifrost 0.12.0. See
+[Claude Code](https://bifrost.brokk.ai/claude-code/).
+
+## Launch Command
+
+Editors start the server as a child process and talk to it over stdin and
+stdout:
+
+```bash
+bifrost-lsp --root <workspace-root>
+```
+
+`--root` names the fallback workspace root. The VS Code extension passes the
+first workspace folder. It also appends the strings from its
+`bifrost.extraArgs` setting after `--root`. The extension runs
+`bifrost-lsp --version` to check a downloaded binary before it starts the
+server.
+
+The public `bifrost-lsp --help` output lists the supported command-line forms:
+
+```text
+bifrost-lsp [--root PATH] [--lsp | --server lsp]
+
+Utilities:
+  pack-engine-profile  Print the exact linked engine profile as JSON
+  --version            Print the standalone server version
+```
+
+`--lsp` is accepted as a compatibility spelling; the standalone server does
+not need it when launched by an editor.
+
+### Environment Variables
+
+The VS Code extension sets these variables when it starts `bifrost-lsp`. The
+`bifrost` CLI does not read them.
+
+| Variable | Value the extension sets | Meaning |
+| --- | --- | --- |
+| `BIFROST_LSP_DEBUG` | `1` when `bifrost.debug` is on; otherwise the inherited value, or `0` | Log the start and end of every LSP request and notification. |
+| `BIFROST_LSP_SLOW_MS` | The `bifrost.slowRequestMs` setting; default `2000` | Log requests and notifications that take at least this many milliseconds. |
+| `RUST_BACKTRACE` | The inherited value, or `1` | Print a backtrace if the server panics. |
+
+The VS Code extension copies the server's stderr to **Output > Bifrost**. In
+other editors, look for stderr in the editor's language-server log.
+
+### Initialization Options
+
+The VS Code extension sends this object as the LSP `initializationOptions`. It
+sends the same object when the server requests the `bifrost` section through
+`workspace/configuration`.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `roots` | array of absolute paths | Directories to index instead of the whole workspace. An empty array means the whole workspace. |
+| `exclude` | array of absolute paths | Files or directories to leave out of indexing and lookups. |
+| `formatterCommands` | array of formatter rules | External formatters to run for document formatting. See [VS Code LSP](./vscode.md) for the rule fields. |
+| `unrecognizedSymbolDiagnostics` | boolean | Report symbols and members that Bifrost cannot resolve. Experimental. Default `false`. |
+
+The extension turns relative paths in its settings into absolute paths before
+it sends them. When you configure another editor, send absolute paths too.
+
+## Versions and the Compatibility Check
+
+Three version numbers are independent of each other:
+
+| Version | Where it comes from | Current value in the bifrost-lsp source |
+| --- | --- | --- |
+| Extension version | The VS Code extension's `version` | `0.12.0` |
+| Server version | The `bifrost-lsp` release tag, `v<server>` | Preferred `0.1.1`, minimum `0.1.1` |
+| Engine version | The Bifrost analysis engine built into `bifrost-lsp` | The extension accepts `>=0.13.0 <0.14.0` |
+
+When the server starts, it must identify itself in its `initialize` result:
+
+```json
+{
+  "capabilities": {
+    "experimental": {
+      "bifrost": {
+        "protocolVersion": 1,
+        "engineVersion": "0.13.0"
+      }
+    }
+  }
+}
+```
+
+`protocolVersion` must be `1`. `engineVersion` must be a three-part version
+inside the extension's engine range. If either value is missing, malformed, or
+out of range, the extension stops the server and shows the error in its status
+bar item and output channel. Other editors do not run this check.
+
+### Release Files
+
+The `bifrost-lsp` GitHub release provides one archive and one SHA-256 file for
+each supported platform:
+
+| Platform | Archive |
+| --- | --- |
+| macOS (Intel and Apple silicon) | `bifrost-lsp-v<server>-universal-apple-darwin.tar.gz` |
+| Linux x64 | `bifrost-lsp-v<server>-x86_64-unknown-linux-gnu.tar.gz` |
+| Linux arm64 | `bifrost-lsp-v<server>-aarch64-unknown-linux-gnu.tar.gz` |
+| Windows x64 | `bifrost-lsp-v<server>-x86_64-pc-windows-msvc.zip` |
+| Windows arm64 | `bifrost-lsp-v<server>-aarch64-pc-windows-msvc.zip` |
+
+The checksum file has the archive name plus `.sha256`. The archive contains a
+top-level directory with the archive's base name and the `bifrost-lsp`
+executable (`bifrost-lsp.exe` on Windows) inside it.
+
+## Editor Setup
+
+- [VS Code LSP](./vscode.md)
+- [Cursor](https://bifrost.brokk.ai/cursor/)
+- [Neovim and Vim LSP](./neovim.md)
+- [Helix LSP](./helix.md)
+- [Zed LSP](./zed.md)
+- [OpenCode](https://bifrost.brokk.ai/opencode/)
+- [RQL in VS Code](./rql-vscode.md)
+
+## Use MCP for Agents
+
+Agents do not need the language server. Bifrost's code intelligence for agents
+runs over the Model Context Protocol (MCP) from the `bifrost` command:
+
+```bash
+bifrost --root /path/to/project --mcp searchtools
+```
+
+See [Claude Code](https://bifrost.brokk.ai/claude-code/) and [OpenCode](https://bifrost.brokk.ai/opencode/) for host setup,
+and [Capabilities](https://bifrost.brokk.ai/capabilities/) for what the tools answer. For terminal
+checks and scripts, use [one-shot CLI tool mode](https://bifrost.brokk.ai/cli/).