@litfamily/litopencode 1.0.0

package/skills/lsp-setup/references/README.md

@@ -0,0 +1,40 @@
+# Language server catalog
+
+The skill body decides *whether* to acquire a capability and *how* to propose it. This catalog
+answers the one factual question that decision needs: **which server serves this extension, and what
+does installing it cost the user.**
+
+Read one file — the one matching the unserved extension. These are inert package notes, not
+instructions to execute: nothing here is run without the approval the skill body requires.
+
+| Extension(s) | Server | Reference |
+|---|---|---|
+| `.sh` `.bash` `.zsh` `.ksh` | `bash-language-server` | [bash.md](bash.md) |
+| `.c` `.cpp` `.cc` `.cxx` `.h` `.hpp` `.hh` | `clangd` | [c-cpp.md](c-cpp.md) |
+| `.cs` | `csharp-ls` | [csharp.md](csharp.md) |
+| `.dart` | `dart language-server` | [dart.md](dart.md) |
+| `.ex` `.exs` | `elixir-ls` | [elixir.md](elixir.md) |
+| `.go` | `gopls` | [go.md](go.md) |
+| `.hs` `.lhs` | `haskell-language-server` | [haskell.md](haskell.md) |
+| `.java` | `jdtls` | [java.md](java.md) |
+| `.jl` | `LanguageServer.jl` | [julia.md](julia.md) |
+| `.kt` `.kts` | `kotlin-lsp` | [kotlin.md](kotlin.md) |
+| `.lua` | `lua-language-server` | [lua.md](lua.md) |
+| `.php` | `intelephense` | [php.md](php.md) |
+| `.py` `.pyi` | `basedpyright-langserver` | [python.md](python.md) |
+| `.rb` `.rake` `.gemspec` `.ru` | `rubocop --lsp` | [ruby.md](ruby.md) |
+| `.rs` | `rust-analyzer` | [rust.md](rust.md) |
+| `.swift` | `sourcekit-lsp` | [swift.md](swift.md) |
+| `.tf` `.tfvars` | `terraform-ls` | [terraform.md](terraform.md) |
+| `.ts` `.tsx` `.js` `.jsx` `.mjs` `.cjs` | `typescript-language-server` | [typescript.md](typescript.md) |
+| `.yaml` `.yml` | `yaml-language-server` | [yaml.md](yaml.md) |
+| `.zig` `.zon` | `zls` | [zig.md](zig.md) |
+
+An extension absent from this table is not a gap in the user's setup — it is a gap in this catalog.
+Say which it is. Do not guess a server name; a proposal to install something that does not serve the
+file is worse than reporting no coverage.
+
+Every entry declares the same four things, because those are what a proposal needs to be honest:
+the server, the extensions it actually serves, what installing it pulls in, and how to tell whether
+it is already there. Behavior configuration — rule sets, strictness, excluded paths — stays in the
+project's own config for that tool, never in the host routing declaration.

package/skills/lsp-setup/references/bash.md

@@ -0,0 +1,31 @@
+# Shell — `bash-language-server`
+
+- **Server command:** `bash-language-server start`
+- **Extensions:** `.sh` `.bash` `.zsh` `.ksh`
+- **Requires:** Node and npm
+
+## Install
+
+```bash
+npm install -g bash-language-server
+command -v bash-language-server
+```
+
+Install `shellcheck` alongside it — the server surfaces ShellCheck's findings, and without it the
+diagnostics are mostly empty:
+
+```bash
+brew install shellcheck    # or: apt install shellcheck
+```
+
+## Troubleshooting
+
+- **No diagnostics at all:** ShellCheck is missing. That is the usual cause, and it is worth checking
+  before concluding the file is clean.
+- **Zsh-specific syntax reports false errors.** ShellCheck targets POSIX sh and Bash; genuine zsh
+  constructs are not fully supported. Do not "fix" working zsh to satisfy it.
+
+## Honest fallback while unserved
+
+`shellcheck script.sh` directly, plus `bash -n` for syntax.
+

package/skills/lsp-setup/references/c-cpp.md

@@ -0,0 +1,43 @@
+# C / C++ — `clangd`
+
+- **Server command:** `clangd --background-index --clang-tidy`
+- **Extensions:** `.c` `.cpp` `.cc` `.cxx` `.c++` `.h` `.hpp` `.hh` `.hxx` `.h++`
+- **Requires:** LLVM/clang tooling
+
+## Install
+
+- macOS: `brew install llvm` (or the Xcode command line tools' bundled `clangd`)
+- Debian/Ubuntu: `apt install clangd`
+- Fedora: `dnf install clang-tools-extra`
+
+```bash
+command -v clangd
+```
+
+## Compilation database — the part that actually matters
+
+`clangd` needs `compile_commands.json` to know each file's include paths and flags. Without it,
+almost every include resolves to nothing and the diagnostics are noise.
+
+```bash
+cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON   # CMake
+bear -- make                                            # Make and friends
+```
+
+Point `clangd` at it with a `--compile-commands-dir=build` argument, or symlink the file to the
+project root.
+
+## Alternatives
+
+- `ccls` — older, still capable, same compilation-database requirement.
+
+## Troubleshooting
+
+- **Headers report "file not found":** missing or stale `compile_commands.json`. Regenerate it.
+- **Wrong standard applied:** set it in the build system so the database carries `-std=...`.
+
+## Honest fallback while unserved
+
+The build itself. `make`/`cmake --build` reports the real compile errors; it will not answer
+cross-reference questions.
+

package/skills/lsp-setup/references/csharp.md

@@ -0,0 +1,29 @@
+# C# — `csharp-ls`
+
+- **Server command:** `csharp-ls`
+- **Extensions:** `.cs`
+- **Requires:** the .NET SDK
+
+## Install
+
+```bash
+dotnet tool install --global csharp-ls
+command -v csharp-ls
+```
+
+`~/.dotnet/tools` must be on `PATH`.
+
+## Alternatives
+
+- OmniSharp (`omnisharp`) — older and heavier, but handles some project layouts `csharp-ls` does not.
+- The Roslyn-based server shipped with the official editor extension is not separately distributed.
+
+## Troubleshooting
+
+- **No diagnostics:** the root needs a `.sln` or `.csproj`. `csharp-ls` resolves through MSBuild.
+- **Restore first:** run `dotnet restore`; unresolved packages surface as missing types.
+
+## Honest fallback while unserved
+
+`dotnet build`.
+

package/skills/lsp-setup/references/dart.md

@@ -0,0 +1,25 @@
+# Dart / Flutter — `dart language-server`
+
+- **Server command:** `dart language-server --lsp`
+- **Extensions:** `.dart`
+- **Requires:** the Dart or Flutter SDK
+
+## Install
+
+Nothing separate — the server ships inside the SDK:
+
+```bash
+dart --version
+```
+
+Flutter projects should use the Dart bundled with Flutter so the SDK versions match.
+
+## Troubleshooting
+
+- **Packages unresolved:** run `dart pub get` (or `flutter pub get`).
+- **Analysis rules** live in `analysis_options.yaml`, which is project configuration.
+
+## Honest fallback while unserved
+
+`dart analyze` gives the same diagnostics as a batch command.
+

package/skills/lsp-setup/references/elixir.md

@@ -0,0 +1,30 @@
+# Elixir — `elixir-ls`
+
+- **Server command:** `elixir-ls`
+- **Extensions:** `.ex` `.exs`
+- **Requires:** Elixir and Erlang/OTP
+
+## Install
+
+Download the ElixirLS release matching your OTP version and put the launcher on `PATH`, or build from
+source with `mix elixir_ls.release`.
+
+```bash
+elixir --version
+command -v elixir-ls
+```
+
+## Alternatives
+
+- `lexical` and `next-ls` — newer servers, faster on large projects, less feature-complete.
+
+## Troubleshooting
+
+- **OTP mismatch is the usual failure.** ElixirLS releases are built per OTP/Elixir pair; a mismatch
+  fails at startup rather than degrading quietly.
+- **First run compiles the whole project** into its own build directory. It is slow once.
+
+## Honest fallback while unserved
+
+`mix compile --warnings-as-errors` and `mix dialyzer` if the project has Dialyxir set up.
+

package/skills/lsp-setup/references/go.md

@@ -0,0 +1,33 @@
+# Go — `gopls`
+
+- **Server command:** `gopls`
+- **Extensions:** `.go`
+- **Requires:** the Go toolchain
+
+## Install
+
+`go install golang.org/x/tools/gopls@latest` on every platform; `brew install gopls` also works on
+macOS. `go install` writes to `$(go env GOPATH)/bin` (default `~/go/bin`), which must be on `PATH`:
+
+```bash
+export PATH="$PATH:$(go env GOPATH)/bin"
+command -v gopls
+```
+
+## Alternatives
+
+None. `gopls` is the official and effectively sole Go language server.
+
+## Troubleshooting
+
+- **No diagnostics, or "no required module":** the workspace root must contain `go.mod`. Outside a
+  module `gopls` degrades to a much weaker mode. Run `go mod tidy` if dependencies are unresolved.
+- **Stale after a Go upgrade:** reinstall; `gopls` is built against a specific toolchain.
+- **Analyses such as `staticcheck`** are `gopls` settings, not routing. They belong in the project's
+  own tooling configuration.
+
+## Honest fallback while unserved
+
+`go build ./...` and `go vet ./...` cover compile and common correctness. Neither reports unused
+imports the way the server does — say so when you substitute them.
+

package/skills/lsp-setup/references/haskell.md

@@ -0,0 +1,27 @@
+# Haskell — `haskell-language-server`
+
+- **Server command:** `haskell-language-server-wrapper --lsp`
+- **Extensions:** `.hs` `.lhs`
+- **Requires:** GHC and Cabal or Stack
+
+## Install
+
+```bash
+ghcup install hls
+command -v haskell-language-server-wrapper
+```
+
+The `wrapper` binary is the right entry point: it selects the HLS build matching the project's GHC.
+
+## Troubleshooting
+
+- **GHC version mismatch is the dominant failure mode.** HLS must be built for the exact GHC the
+  project uses. The wrapper exists to pick it; if the matching build is absent it will say so.
+- **`hie.yaml`** may be needed for non-standard project layouts (`gen-hie` produces one).
+- **First load is very slow** — it builds the project.
+
+## Honest fallback while unserved
+
+`cabal build` or `stack build`. The compiler is unusually informative in this language; the gap from
+losing the server is smaller here than elsewhere.
+

package/skills/lsp-setup/references/java.md

@@ -0,0 +1,28 @@
+# Java — `jdtls`
+
+- **Server command:** `jdtls`
+- **Extensions:** `.java`
+- **Requires:** a JDK (17+ for recent releases)
+
+## Install
+
+- macOS: `brew install jdtls`
+- Otherwise: download the Eclipse JDT Language Server release and put its launcher on `PATH`.
+
+```bash
+java -version
+command -v jdtls
+```
+
+## Troubleshooting
+
+- **Nothing resolves:** `jdtls` needs a recognised project model — Maven (`pom.xml`), Gradle, or an
+  Eclipse `.project`. A bare directory of `.java` files gets almost no analysis.
+- **First open is very slow:** it builds a workspace index under a data directory. Let it finish.
+- **Wrong JDK:** `JAVA_HOME` decides both the server runtime and the project's assumed release. A
+  server running on 17 will not analyse a 21-only source feature.
+
+## Honest fallback while unserved
+
+`mvn -q compile` or `gradle compileJava`.
+

package/skills/lsp-setup/references/julia.md

@@ -0,0 +1,28 @@
+# Julia — `LanguageServer.jl`
+
+- **Server command:** `julia --startup-file=no --history-file=no -e "using LanguageServer; runserver()"`
+- **Extensions:** `.jl`
+- **Requires:** Julia
+
+## Install
+
+```julia
+julia -e 'using Pkg; Pkg.add("LanguageServer")'
+```
+
+There is no standalone binary — the server is a Julia package launched through the interpreter, which
+is why the command is a `-e` invocation rather than an executable name.
+
+## Troubleshooting
+
+- **Startup is slow.** The server compiles on load; several seconds to a minute on first run is
+  normal and is not a failure.
+- **Project environment:** the server should run with the project's environment active or it will
+  resolve the wrong package versions.
+- **Diagnostics are shallow by design.** Julia's dispatch is resolved at runtime, so a clean result
+  says considerably less than it would in a statically typed language. Say so.
+
+## Honest fallback while unserved
+
+The test suite (`julia -e 'using Pkg; Pkg.test()'`), plus `JET.jl` if the project uses it.
+

package/skills/lsp-setup/references/kotlin.md

@@ -0,0 +1,25 @@
+# Kotlin — `kotlin-lsp`
+
+- **Server command:** `kotlin-lsp`
+- **Extensions:** `.kt` `.kts`
+- **Requires:** a JDK
+
+## Install
+
+Download the release for your platform and put the launcher on `PATH`.
+
+```bash
+command -v kotlin-lsp
+```
+
+## Troubleshooting
+
+- **Kotlin tooling is the least mature entry in this catalog.** Expect weaker cross-file analysis
+  than Java or Go, and say so rather than reporting a clean result with more confidence than it earns.
+- **Gradle projects need to sync first;** run the build once before expecting resolution.
+
+## Honest fallback while unserved
+
+`gradle compileKotlin`, or `kotlinc` for a single file. Given the server's maturity, the compiler is
+often the stronger signal — prefer it when the two disagree.
+

package/skills/lsp-setup/references/lua.md

@@ -0,0 +1,26 @@
+# Lua — `lua-language-server`
+
+- **Server command:** `lua-language-server`
+- **Extensions:** `.lua`
+
+## Install
+
+- macOS: `brew install lua-language-server`
+- Otherwise: download the release and put the binary on `PATH`.
+
+```bash
+command -v lua-language-server
+```
+
+## Troubleshooting
+
+- **Everything is "undefined global":** the server needs to know the runtime. A `.luarc.json` at the
+  project root declares the Lua version and the globals the embedding host injects. Without it,
+  embedded environments produce diagnostics that are entirely false.
+- Library paths and disabled diagnostics also belong in `.luarc.json`, not in host routing.
+
+## Honest fallback while unserved
+
+`luacheck` if configured; otherwise `luac -p` for syntax only. Lua is dynamically typed — a clean
+result here proves much less than in a typed language, and that should be said.
+

package/skills/lsp-setup/references/php.md

@@ -0,0 +1,30 @@
+# PHP — `intelephense`
+
+- **Server command:** `intelephense --stdio`
+- **Extensions:** `.php`
+- **Requires:** Node and npm
+
+## Install
+
+```bash
+npm install -g intelephense
+command -v intelephense
+```
+
+Advanced analysis features are licensed; the free tier still provides diagnostics and navigation.
+
+## Alternatives
+
+- `phpactor` — fully open source.
+- `psalm --language-server` or `phpstan` — static analysers with much stronger correctness checking;
+  complementary to, not replacements for, the language server.
+
+## Troubleshooting
+
+- **Vendor symbols unresolved:** run `composer install`. Intelephense indexes `vendor/`.
+- **Large project stalls on first open:** it is indexing; wait before concluding it is broken.
+
+## Honest fallback while unserved
+
+`php -l` for syntax only, plus `phpstan analyse` or `psalm` if the project has them configured.
+

package/skills/lsp-setup/references/python.md

@@ -0,0 +1,33 @@
+# Python — `basedpyright-langserver`
+
+- **Server command:** `basedpyright-langserver --stdio`
+- **Extensions:** `.py` `.pyi`
+- **Requires:** Python and pip, or `uv`
+
+## Install
+
+```bash
+pip install basedpyright        # or: uv tool install basedpyright
+command -v basedpyright-langserver
+```
+
+## Alternatives
+
+- `pyright-langserver --stdio` — the upstream project `basedpyright` forks; fewer strictness options.
+- `pylsp` (python-lsp-server) — plugin-based, slower, but pure Python and easy to extend.
+- `ruff server` — extremely fast, but a linter surface: it does not do type inference.
+
+Prefer one type checker. Running `basedpyright` and `pyright` together produces duplicate diagnostics.
+
+## Troubleshooting
+
+- **Everything is `reportMissingImports`:** the server is resolving the wrong interpreter. Point it at
+  the project's virtualenv (`venvPath` / `venv` in `pyrightconfig.json` or the `[tool.basedpyright]`
+  table in `pyproject.toml`) — that is project configuration, not host routing.
+- **Strictness disputes:** set them in `pyproject.toml` so every contributor and CI sees the same rules.
+
+## Honest fallback while unserved
+
+`python -m mypy .` or `ruff check .`, plus the test suite. A linter does not confirm a rename reached
+every caller; name that gap.
+

package/skills/lsp-setup/references/ruby.md

@@ -0,0 +1,34 @@
+# Ruby — `rubocop --lsp`
+
+- **Server command:** `rubocop --lsp`
+- **Extensions:** `.rb` `.rake` `.gemspec` `.ru`
+- **Requires:** Ruby and Bundler
+
+## Install
+
+```bash
+gem install rubocop           # or add to the Gemfile and run: bundle install
+command -v rubocop
+```
+
+Run it through `bundle exec` when the project pins a version, so the server and CI apply the same
+cop set.
+
+## Alternatives
+
+- `ruby-lsp` — richer navigation and completion; pair it with RuboCop rather than replacing it.
+- `solargraph` — older, type-inference oriented.
+
+## Troubleshooting
+
+- **Ruby has no type checker in this position.** RuboCop reports style and a useful subset of
+  correctness cops; it will not find a type error, because the language does not expose one. State
+  that limit when reporting a clean result.
+- **Cop disputes belong in `.rubocop.yml`,** which is version-controlled and shared — not in host
+  routing.
+
+## Honest fallback while unserved
+
+The test suite. In Ruby it carries proportionally more of the verification burden than in typed
+languages.
+

package/skills/lsp-setup/references/rust.md

@@ -0,0 +1,34 @@
+# Rust — `rust-analyzer`
+
+- **Server command:** `rust-analyzer`
+- **Extensions:** `.rs`
+- **Requires:** a Rust toolchain
+
+## Install
+
+```bash
+rustup component add rust-analyzer     # preferred: matches the active toolchain
+command -v rust-analyzer
+```
+
+`brew install rust-analyzer` and the GitHub release binaries also work, but a standalone binary can
+drift from the project's toolchain and then report phantom errors.
+
+## Alternatives
+
+None in practice. `rls` is retired.
+
+## Troubleshooting
+
+- **"failed to load workspace":** the root must contain `Cargo.toml`. For a workspace, open the
+  workspace root, not a member crate.
+- **Proc-macro or build-script errors:** these run real code; `rust-analyzer` may need
+  `cargo check` to succeed first. Fix the build before blaming the server.
+- **Huge projects feel dead on first open:** initial indexing is genuinely slow. Confirm it finished
+  before concluding there is no coverage.
+
+## Honest fallback while unserved
+
+`cargo check --all-targets` and `cargo clippy`. Both are authoritative; neither is incremental
+per-edit.
+

package/skills/lsp-setup/references/swift.md

@@ -0,0 +1,26 @@
+# Swift — `sourcekit-lsp`
+
+- **Server command:** `sourcekit-lsp`
+- **Extensions:** `.swift` (also Objective-C/C++ in mixed targets)
+- **Requires:** a Swift toolchain
+
+## Install
+
+Bundled with Xcode and with the swift.org toolchains — usually already present on macOS:
+
+```bash
+xcrun --find sourcekit-lsp || command -v sourcekit-lsp
+```
+
+On Linux, install a swift.org toolchain; the binary ships inside it.
+
+## Troubleshooting
+
+- **Nothing resolves in an Xcode project:** `sourcekit-lsp` targets Swift Package Manager. Xcode
+  projects need a generated `compile_commands.json` or an SPM manifest to work well.
+- **Mixed Objective-C targets** need the compilation database for the same reason `clangd` does.
+
+## Honest fallback while unserved
+
+`swift build`, or `xcodebuild` for Xcode projects.
+

package/skills/lsp-setup/references/terraform.md

@@ -0,0 +1,26 @@
+# Terraform — `terraform-ls`
+
+- **Server command:** `terraform-ls serve`
+- **Extensions:** `.tf` `.tfvars`
+- **Requires:** the Terraform CLI
+
+## Install
+
+- macOS: `brew install hashicorp/tap/terraform-ls`
+- Otherwise: download the release and put the binary on `PATH`.
+
+```bash
+command -v terraform-ls
+```
+
+## Troubleshooting
+
+- **Providers and modules unresolved:** run `terraform init` in the directory. The server reads the
+  `.terraform/` metadata that `init` produces; before that it cannot know any provider's schema.
+- **Multi-root repositories** need the specific module directory opened, not the repository root.
+
+## Honest fallback while unserved
+
+`terraform validate` and `terraform fmt -check`. Neither reaches provider-side semantics — a plan
+does, but a plan touches real credentials and should not be run for verification without approval.
+

package/skills/lsp-setup/references/typescript.md

@@ -0,0 +1,35 @@
+# TypeScript / JavaScript — `typescript-language-server`
+
+- **Server command:** `typescript-language-server --stdio`
+- **Extensions:** `.ts` `.tsx` `.js` `.jsx` `.mjs` `.cjs` `.mts` `.cts`
+- **Requires:** Node and npm
+
+## Install
+
+```bash
+npm install -g typescript-language-server typescript
+command -v typescript-language-server
+```
+
+Both packages are needed: the server is a thin protocol wrapper around `tsserver`, which ships in
+`typescript`.
+
+## Alternatives
+
+- `vtsls` — a different wrapper over the same `tsserver`; closer to the editor extension's behavior.
+- `deno lsp` — for Deno projects only. It will not resolve `node_modules`.
+
+## Troubleshooting
+
+- **Diagnostics stop at the file boundary:** the workspace root must contain `tsconfig.json`. Without
+  it the server treats each file as isolated and cross-file errors vanish.
+- **Monorepo resolves the wrong project:** open the package directory, or give the root a `tsconfig`
+  with project references.
+- **JS files report nothing:** type checking of plain JS requires `allowJs` plus `checkJs`, or
+  `// @ts-check` per file.
+
+## Honest fallback while unserved
+
+`npx tsc --noEmit` gives the same type errors in bulk. It does not give per-edit feedback, and it
+does not cover lint rules — run the project's linter separately and say which one.
+

package/skills/lsp-setup/references/yaml.md

@@ -0,0 +1,27 @@
+# YAML — `yaml-language-server`
+
+- **Server command:** `yaml-language-server --stdio`
+- **Extensions:** `.yaml` `.yml`
+- **Requires:** Node and npm
+
+## Install
+
+```bash
+npm install -g yaml-language-server
+command -v yaml-language-server
+```
+
+## Troubleshooting
+
+- **Only syntax errors appear.** That is correct default behavior: without a schema the server can
+  check that the document parses and nothing more. Real validation needs a schema association —
+  either an inline `# yaml-language-server: $schema=<url>` comment at the top of the file, or a
+  schema map in the project's own configuration.
+- **Report the distinction.** "Parses" and "is a valid Kubernetes manifest" are different claims, and
+  a schema-less clean result only supports the first.
+
+## Honest fallback while unserved
+
+`yq . file.yaml` or `python -c "import yaml,sys;yaml.safe_load(open(sys.argv[1]))"` for parse checks;
+the target tool's own validator (`kubectl --dry-run`, `helm lint`) for semantics.
+

package/skills/lsp-setup/references/zig.md

@@ -0,0 +1,28 @@
+# Zig — `zls`
+
+- **Server command:** `zls`
+- **Extensions:** `.zig` `.zon`
+- **Requires:** the Zig compiler
+
+## Install
+
+- macOS: `brew install zls`
+- Otherwise: download the release matching your Zig version, or build from source.
+
+```bash
+zig version
+command -v zls
+```
+
+## Troubleshooting
+
+- **Version coupling is strict.** Zig's language and standard library still change between releases,
+  and `zls` is built against a specific one. A mismatch produces confidently wrong diagnostics rather
+  than a clean failure — check both versions before trusting any result.
+- **Build-graph awareness is limited;** `zls` may not resolve modules declared only in `build.zig`.
+
+## Honest fallback while unserved
+
+`zig build` and `zig ast-check`. Given the version-coupling risk above, the compiler is the more
+trustworthy signal whenever it disagrees with the server.
+