oh-my-opencode 4.8.0 → 4.9.0

package/packages/shared-skills/skills/lsp-setup/references/bash/README.md

@@ -0,0 +1,60 @@
+# Bash — LSP setup
+
+- **Builtin server:** `bash` — `bash-language-server start`
+- **Extensions:** `.sh .bash .zsh .ksh`
+- **Install hint:** `npm install -g bash-language-server`
+
+An alias id `bash-ls` exists with the identical command; either id works.
+
+## Install
+
+- **macOS:** `npm install -g bash-language-server`
+- **Linux:** `npm install -g bash-language-server`
+- **Windows:** `npm install -g bash-language-server` (PowerShell)
+
+For real diagnostics, also install `shellcheck`:
+
+- **macOS:** `brew install shellcheck`
+- **Linux:** `apt install shellcheck` (or `dnf install ShellCheck`)
+- **Windows:** `scoop install shellcheck`
+
+Confirm it resolves:
+
+```bash
+command -v bash-language-server
+command -v shellcheck
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "bash": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. `bash-language-server` discovers `shellcheck` on PATH automatically. To point at a non-PATH binary, export `SHELLCHECK_PATH` via `env`:
+
+```json
+{ "lsp": { "bash": { "env": { "SHELLCHECK_PATH": "/opt/bin/shellcheck" } } } }
+```
+
+## Alternatives
+
+- `shellcheck` standalone as a linter-only flow (no LSP).
+- `shfmt` for formatting (complements, does not replace, the LSP).
+
+## Troubleshooting
+- **PATH:** `bash-language-server` on PATH; reopen shell after `npm -g` install.
+- **No diagnostics:** `shellcheck` missing — diagnostics are powered by it; install and reopen.
+- **Wrong shell dialect:** `.zsh`/`.ksh` are linted as bash; shellcheck may flag shell-specific syntax.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.sh
+```

package/packages/shared-skills/skills/lsp-setup/references/c-cpp/README.md

@@ -0,0 +1,61 @@
+# C / C++ — LSP setup
+
+- **Builtin server:** `clangd` — `clangd --background-index --clang-tidy`
+- **Extensions:** `.c .cpp .cc .cxx .c++ .h .hpp .hh .hxx .h++`
+- **Install hint:** `https://clangd.llvm.org/installation`
+
+## Install
+
+- **macOS:** `brew install llvm` (clangd ships in the LLVM keg; add its `bin` to PATH)
+- **Linux:** `apt install clangd` (Debian/Ubuntu); use your distro package elsewhere
+- **Windows:** install LLVM from `https://releases.llvm.org` or `winget install LLVM.LLVM`
+
+See `https://clangd.llvm.org/installation` for other platforms.
+
+Confirm it resolves:
+
+```bash
+command -v clangd
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "clangd": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. clangd reads flags from a project `.clangd` file rather
+than initializationOptions. The builtin command already passes
+`--background-index --clang-tidy`.
+
+## Compile commands
+
+clangd needs a `compile_commands.json` at the project root (or in `build/`) for
+accurate diagnostics and cross-file navigation. Generate it with:
+
+- **CMake:** `cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON` (symlink/copy `build/compile_commands.json` to the root)
+- **Make / other:** `bear -- make`
+
+Without it, clangd falls back to heuristic flags and reports spurious errors.
+
+## Alternatives
+
+None builtin. `ccls` exists as a third-party server but is not builtin — it would
+need a custom `command` in the USER config.
+
+## Troubleshooting
+- **PATH:** `clangd` must be on PATH; reopen shell after install. Homebrew LLVM is keg-only — add `$(brew --prefix llvm)/bin` to PATH.
+- **Spurious "file not found" / unknown flags:** missing or stale `compile_commands.json` — regenerate it after changing the build.
+- **Header-only diagnostics wrong:** ensure the header's translation unit appears in the compile database, or add a `.clangd` `CompileFlags` block.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.cpp
+```

package/packages/shared-skills/skills/lsp-setup/references/csharp/README.md

@@ -0,0 +1,71 @@
+# C# — LSP setup
+
+- **Builtin server:** `csharp` — `csharp-ls`
+- **Extensions:** `.cs`
+- **Install hint:** `dotnet tool install -g csharp-ls`
+
+## Install
+
+Requires the **.NET SDK**. Install the tool globally:
+
+- **macOS:** `dotnet tool install -g csharp-ls`
+- **Linux:** `dotnet tool install -g csharp-ls`
+- **Windows:** `dotnet tool install -g csharp-ls`
+
+Global .NET tools land in `~/.dotnet/tools` — ensure that directory is on PATH (Windows: `%USERPROFILE%\.dotnet\tools`).
+
+Confirm it resolves:
+
+```bash
+command -v csharp-ls
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "csharp": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. `csharp-ls` picks up the nearest `.sln` or `.csproj`; keep the solution restorable (`dotnet restore`).
+
+## Razor / Blazor
+
+Razor and Blazor files use a separate builtin server:
+
+- **Builtin server:** `razor` — `roslyn-language-server --stdio`
+- **Extensions:** `.razor .cshtml`
+- **Install hint:** `dotnet tool install -g roslyn-language-server --prerelease` (requires **v5.8.0+**; see [dotnet/razor](https://github.com/dotnet/razor))
+
+```bash
+dotnet tool install -g roslyn-language-server --prerelease
+command -v roslyn-language-server
+```
+
+Enable it in a project/user config:
+
+```json
+{ "lsp": { "razor": { } } }
+```
+
+## Alternatives
+
+- **OmniSharp** — legacy C# language server (not builtin). Still works but is being superseded by the Roslyn-based servers; prefer `csharp-ls` / `roslyn-language-server`.
+
+## Troubleshooting
+
+- **PATH:** `csharp-ls` / `roslyn-language-server` on PATH (`~/.dotnet/tools`); reopen shell after install.
+- **No .NET SDK:** install the SDK (not just the runtime) before installing the tool.
+- **No symbols:** run `dotnet restore`; an unrestored solution yields empty results.
+- **Razor needs v5.8.0+:** older `roslyn-language-server` builds lack the `--stdio` Razor support — install with `--prerelease`.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/File.cs
+```

package/packages/shared-skills/skills/lsp-setup/references/dart/README.md

@@ -0,0 +1,48 @@
+# Dart — LSP setup
+
+- **Builtin server:** `dart` — `dart language-server --lsp`
+- **Extensions:** `.dart`
+- **Install hint:** `Included with the Dart/Flutter SDK`
+
+## Install
+
+The language server ships inside the Dart SDK (and the Flutter SDK, which bundles Dart). There is no separate package to install — just put `dart` (or `flutter`) on PATH.
+
+- **macOS:** `brew install dart` (or install Flutter and use its bundled `dart`)
+- **Linux:** install the Dart SDK from your package manager / `https://dart.dev/get-dart`, or install Flutter
+- **Windows:** install the Dart SDK or Flutter SDK and add its `bin` to PATH
+
+Confirm it resolves:
+
+```bash
+command -v dart
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "dart": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required.
+
+## Alternatives
+
+None.
+
+## Troubleshooting
+- **PATH:** `dart` must be on PATH; reopen the shell after installing the SDK. Flutter users: ensure `<flutter>/bin/cache/dart-sdk/bin` or the Flutter `bin` is exported.
+- **Flutter vs Dart:** if you only have Flutter installed, the bundled `dart` works — make sure Flutter's `bin` is on PATH rather than relying on a separate Dart install.
+- **SDK out of date:** run `dart --version` / `flutter upgrade` if analysis behaves oddly on newer language features.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.dart
+```

package/packages/shared-skills/skills/lsp-setup/references/elixir/README.md

@@ -0,0 +1,51 @@
+# Elixir — LSP setup
+
+- **Builtin server:** `elixir-ls` — `elixir-ls`
+- **Extensions:** `.ex .exs`
+- **Install hint:** `https://github.com/elixir-lsp/elixir-ls`
+
+## Install
+
+ElixirLS needs Erlang/OTP and Elixir installed first. Build the release from
+`https://github.com/elixir-lsp/elixir-ls` and put the `elixir-ls` launcher script on PATH.
+
+- **macOS:** `brew install elixir-ls` (Homebrew provides the launcher), or build the release manually
+- **Linux:** clone elixir-ls, run `mix deps.get && mix compile && mix elixir_ls.release2 -o release`, then add `release/` to PATH
+- **Windows:** build the release and add the `release` dir (use the `.bat` launcher) to PATH
+
+Confirm it resolves:
+
+```bash
+command -v elixir-ls
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "elixir-ls": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required.
+
+## Alternatives
+
+- **lexical** (not builtin): `lexical` — fast, modern alternative LSP.
+- **next-ls** (not builtin): `nextls --stdio` — from the elixir-tools project.
+
+## Troubleshooting
+- **PATH:** `elixir-ls` must be on PATH; reopen the shell after install.
+- **asdf users:** the launcher is a shim — after `asdf install`, run `asdf reshim elixir` so the `elixir-ls` shim resolves, and ensure the Erlang/Elixir versions match the build.
+- **First start is slow:** ElixirLS compiles your deps on first run; initial diagnostics can take a while on large projects.
+- **OTP mismatch:** build elixir-ls with the same Erlang/Elixir versions you use for the project to avoid bytecode errors.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.ex
+```

package/packages/shared-skills/skills/lsp-setup/references/go/README.md

@@ -0,0 +1,57 @@
+# Go — LSP setup
+
+- **Builtin server:** `gopls` — `gopls`
+- **Extensions:** `.go`
+- **Install hint:** `go install golang.org/x/tools/gopls@latest`
+
+## Install
+
+- **macOS:** `go install golang.org/x/tools/gopls@latest` (or `brew install gopls`)
+- **Linux:** `go install golang.org/x/tools/gopls@latest`
+- **Windows:** `go install golang.org/x/tools/gopls@latest`
+
+Requires the Go toolchain. `go install` drops the binary in `$GOPATH/bin`
+(default `~/go/bin`) — that directory must be on PATH.
+
+```bash
+export PATH="$PATH:$(go env GOPATH)/bin"
+```
+
+Confirm it resolves:
+
+```bash
+command -v gopls
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "gopls": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. To enable extra analyses or staticcheck:
+
+```json
+{ "lsp": { "gopls": { "initialization": { "staticcheck": true } } } }
+```
+
+## Alternatives
+
+None — `gopls` is the official and de facto sole Go language server.
+
+## Troubleshooting
+- **PATH:** `gopls` must be on PATH; ensure `$(go env GOPATH)/bin` is exported, then reopen the shell.
+- **No diagnostics / "no required module":** open the directory containing `go.mod` as the workspace root. Outside a module, gopls degrades. Run `go mod tidy` if dependencies are unresolved.
+- **Stale toolchain:** reinstall with `go install golang.org/x/tools/gopls@latest` after upgrading Go.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.go
+```

package/packages/shared-skills/skills/lsp-setup/references/haskell/README.md

@@ -0,0 +1,57 @@
+# Haskell — LSP setup
+
+- **Builtin server:** `haskell-language-server` — `haskell-language-server-wrapper --lsp`
+- **Extensions:** `.hs .lhs`
+- **Install hint:** `ghcup install hls`
+
+The `-wrapper` binary detects your project's GHC version and dispatches to the matching HLS build.
+
+## Install
+
+- **macOS:** `ghcup install hls` (install ghcup via `brew install ghcup` or the official script)
+- **Linux:** `ghcup install hls` (ghcup script from https://www.haskell.org/ghcup/)
+- **Windows:** `ghcup install hls` (ghcup is installed via the Windows installer / PowerShell bootstrap)
+
+HLS needs a working GHC plus Cabal and/or Stack. Install a matching toolchain first:
+
+```bash
+ghcup install ghc
+ghcup install cabal
+```
+
+Confirm it resolves:
+
+```bash
+command -v haskell-language-server-wrapper
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "haskell-language-server": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. Per-project plugin/formatter settings normally live in a `hie.yaml` (cradle) and `.haskell-language-server` files rather than init options.
+
+## Alternatives
+
+- `ghcide` (the core HLS engine, standalone) — largely superseded by HLS.
+- `hlint` standalone for lint-only checks; `ormolu`/`fourmolu` for formatting.
+
+## Troubleshooting
+- **PATH:** `haskell-language-server-wrapper` on PATH; reopen shell after `ghcup install`.
+- **GHC mismatch:** the installed HLS must support your project's GHC version — run `ghcup install hls` for that GHC, or align GHC to a supported one.
+- **No cradle:** multi-package repos may need a `hie.yaml`; generate one with `gen-hie > hie.yaml`.
+- **Slow first load:** HLS compiles dependencies on first open; let it finish indexing.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.hs
+```

package/packages/shared-skills/skills/lsp-setup/references/java/README.md

@@ -0,0 +1,57 @@
+# Java — LSP setup
+
+- **Builtin server:** `jdtls` — `jdtls`
+- **Extensions:** `.java`
+- **Install hint:** `https://github.com/eclipse-jdtls/eclipse.jdt.ls`
+
+## Install
+
+- **macOS:** `brew install jdtls`
+- **Linux:** Download from [eclipse-jdtls/eclipse.jdt.ls](https://github.com/eclipse-jdtls/eclipse.jdt.ls) releases, extract, and wrap the launcher as `jdtls` on PATH (some distros package it as `jdtls`/`jdt-language-server`).
+- **Windows:** Download the release archive and add the `jdtls` launcher (`bin/jdtls.bat` or the Python wrapper) to PATH.
+
+Requires a **JDK 17+** to run the language server itself (the project may target an older Java version).
+
+Confirm it resolves:
+
+```bash
+command -v jdtls
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "jdtls": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+jdtls maintains a per-project **workspace data directory** and the **first index is slow** (it resolves the full classpath and builds). Point `JAVA_HOME` at a JDK 17+ if `jdtls` cannot find one:
+
+```json
+{ "lsp": { "jdtls": { "env": { "JAVA_HOME": "/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home" } } } }
+```
+
+Most settings (runtimes, format, import order) are passed via `settings.java.*` initialization options; defaults work for Maven/Gradle projects with a standard layout.
+
+## Alternatives
+
+- **No mainstream alternative.** `jdtls` (Eclipse JDT Language Server) is the de-facto standard and powers the official VS Code Java extension.
+
+## Troubleshooting
+
+- **PATH:** `jdtls` on PATH; reopen shell after install.
+- **No JDK found:** server exits immediately — set `JAVA_HOME` to a JDK 17+.
+- **Slow / no completions at first:** the initial classpath index can take a minute or more on large Maven/Gradle projects; wait for it to finish.
+- **Stale state:** delete the jdtls workspace data dir to force a clean re-index if results go wrong after big dependency changes.
+- **Build tool required:** keep `pom.xml` / `build.gradle` valid; a broken build descriptor breaks symbol resolution.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/File.java
+```

package/packages/shared-skills/skills/lsp-setup/references/julia/README.md

@@ -0,0 +1,60 @@
+# Julia — LSP setup
+
+- **Builtin server:** `julials` — `julia --startup-file=no --history-file=no -e using LanguageServer; runserver()`
+- **Extensions:** `.jl`
+- **Install hint:** `julia -e 'using Pkg; Pkg.add("LanguageServer")'`
+
+The PATH executable is `julia`; LanguageServer.jl is launched through the `-e` snippet, not as its own binary.
+
+## Install
+
+Install Julia (juliaup recommended), then add the `LanguageServer` package:
+
+- **macOS:** `brew install juliaup && juliaup add release`
+- **Linux:** `curl -fsSL https://install.julialang.org | sh` (installs juliaup)
+- **Windows:** `winget install julia -s msstore` (installs juliaup)
+
+Then add the package — ideally into a shared `@lsp` environment so it is not tied to one project:
+
+```bash
+julia --project=@lsp -e 'using Pkg; Pkg.add("LanguageServer")'
+```
+
+Confirm Julia resolves (the LSP binary IS `julia`):
+
+```bash
+command -v julia
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "julials": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. To pin which environment hosts LanguageServer.jl, set `JULIA_PROJECT` (or `JULIA_DEPOT_PATH`) via `env`:
+
+```json
+{ "lsp": { "julials": { "env": { "JULIA_PROJECT": "@lsp" } } } }
+```
+
+## Alternatives
+
+- The VS Code Julia extension bundles the same LanguageServer.jl server.
+
+## Troubleshooting
+- **PATH:** `julia` on PATH (not a `julials` binary); reopen shell after juliaup install.
+- **First run precompiles — be patient:** the initial launch compiles LanguageServer.jl and may take minutes with no output; do not kill it. Subsequent starts are fast.
+- **Package not found:** `LanguageServer` must be installed in the environment the server runs in (e.g. `@lsp`); add it there and set `JULIA_PROJECT`.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.jl
+```

package/packages/shared-skills/skills/lsp-setup/references/kotlin/README.md

@@ -0,0 +1,59 @@
+# Kotlin — LSP setup
+
+- **Builtin server:** `kotlin-ls` — `kotlin-lsp`
+- **Extensions:** `.kt .kts`
+- **Install hint:** `https://github.com/Kotlin/kotlin-lsp`
+
+## Install
+
+The official **JetBrains Kotlin LSP** is pre-release. Download a build from the [Kotlin/kotlin-lsp](https://github.com/Kotlin/kotlin-lsp) releases and put the `kotlin-lsp` launcher on PATH.
+
+- **macOS:** Download the release archive, extract, then symlink the launcher: `ln -s /path/to/kotlin-lsp/kotlin-lsp.sh /usr/local/bin/kotlin-lsp`
+- **Linux:** Same as macOS — extract the release and place/symlink `kotlin-lsp` on PATH.
+- **Windows:** Extract the release and add the directory containing `kotlin-lsp.bat` to PATH (invoke as `kotlin-lsp`).
+
+Requires a **JDK** on the machine to run the server.
+
+Confirm it resolves:
+
+```bash
+command -v kotlin-lsp
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "kotlin-ls": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. If `kotlin-lsp` cannot find a Java runtime, set `JAVA_HOME`:
+
+```json
+{ "lsp": { "kotlin-ls": { "env": { "JAVA_HOME": "/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home" } } } }
+```
+
+The server resolves classpath from Gradle/Maven; keep the build descriptor importable.
+
+## Alternatives
+
+- **`fwcd/kotlin-language-server`** — older community server (not builtin). Still usable but less actively maintained than the official JetBrains one.
+
+## Troubleshooting
+
+- **PATH:** `kotlin-lsp` on PATH; reopen shell after install.
+- **Pre-release churn:** the JetBrains server is early; pin a known-good release and expect occasional breakage.
+- **No JDK:** server fails to start — install a JDK and/or set `JAVA_HOME`.
+- **Slow first import:** Gradle resolution on first open can be slow on large projects; let it complete.
+- **`.kts` scripts:** build/script files resolve more slowly than `.kt` sources; this is expected.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/File.kt
+```

package/packages/shared-skills/skills/lsp-setup/references/lua/README.md

@@ -0,0 +1,66 @@
+# Lua — LSP setup
+
+- **Builtin server:** `lua-ls` — `lua-language-server`
+- **Extensions:** `.lua`
+- **Install hint:** `https://github.com/LuaLS/lua-language-server`
+
+## Install
+
+See `https://github.com/LuaLS/lua-language-server`.
+
+- **macOS:** `brew install lua-language-server`
+- **Linux:** download a release from GitHub, or `pacman -S lua-language-server` (Arch) / AUR
+- **Windows:** download a release from the GitHub releases page and add its `bin` to PATH
+
+Confirm it resolves:
+
+```bash
+command -v lua-language-server
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "lua-ls": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+For Neovim config development, point the server at the Neovim runtime and set the Lua runtime version so `vim` globals and stdlib resolve:
+
+```json
+{
+  "lsp": {
+    "lua-ls": {
+      "initialization": {
+        "Lua": {
+          "runtime": { "version": "LuaJIT" },
+          "workspace": {
+            "library": ["/usr/share/nvim/runtime/lua"]
+          },
+          "diagnostics": { "globals": ["vim"] }
+        }
+      }
+    }
+  }
+}
+```
+
+## Alternatives
+
+None.
+
+## Troubleshooting
+- **PATH:** `lua-language-server` must be on PATH; reopen the shell after install.
+- **Undefined `vim` global:** add `vim` to `Lua.diagnostics.globals` and set `Lua.workspace.library` (see above) for Neovim work.
+- **Wrong runtime version:** set `Lua.runtime.version` (`LuaJIT`, `Lua 5.4`, etc.) to match your interpreter, or stdlib functions report as undefined.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.lua
+```