feat(hover): format definition code blocks with clang-format

Use the project's .clang-format style to format the code snippets shown
in hover popups, so they match the user's formatting preferences instead
of Clang's raw pretty-printer output.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.clang-format

@@ -100,7 +100,7 @@ SortIncludes: true
 SortUsingDeclarations: Never
 IncludeBlocks: Regroup
 IncludeCategories:
-  - Regex: '^["<](spdlog|toml\+\+|coraing|cpptrace|flatbuffers)/'
+  - Regex: '^["<](spdlog|toml\+\+|coraing|cpptrace|flatbuffers|kota)/'
     Priority: 30
     SortPriority: 31
 

.clang-tidy

@@ -0,0 +1,50 @@
+---
+Checks: >
+  -*,
+  bugprone-*,
+  modernize-*,
+  performance-*,
+  readability-*,
+  -modernize-use-trailing-return-type,
+  -readability-magic-numbers,
+  -readability-else-after-return,
+  -readability-braces-around-statements,
+  -readability-avoid-const-params-in-decls,
+  -readability-named-parameter,
+  -readability-implicit-bool-conversion,
+  -readability-use-anyofallof,
+  -bugprone-easily-swappable-parameters,
+  -bugprone-exception-escape,
+  -bugprone-narrowing-conversions,
+  -modernize-use-nodiscard,
+
+WarningsAsErrors: ""
+
+HeaderFilterRegex: "(src|tests)/.*"
+
+CheckOptions:
+  # Naming conventions matching project style
+  - key: readability-identifier-naming.ClassCase
+    value: CamelCase
+  - key: readability-identifier-naming.StructCase
+    value: CamelCase
+  - key: readability-identifier-naming.EnumCase
+    value: CamelCase
+  - key: readability-identifier-naming.EnumConstantCase
+    value: CamelCase
+  - key: readability-identifier-naming.TemplateParameterCase
+    value: CamelCase
+  - key: readability-identifier-naming.TypeAliasCase
+    value: CamelCase
+  - key: readability-identifier-naming.FunctionCase
+    value: lower_case
+  - key: readability-identifier-naming.MethodCase
+    value: lower_case
+  - key: readability-identifier-naming.VariableCase
+    value: lower_case
+  - key: readability-identifier-naming.ParameterCase
+    value: lower_case
+  - key: readability-identifier-naming.MemberCase
+    value: lower_case
+  - key: readability-identifier-naming.NamespaceCase
+    value: lower_case

.claude/CLAUDE.md

@@ -0,0 +1,268 @@
+# clice — Project Guide
+
+## Project Overview
+
+clice is a next-generation C++ language server (LSP) built on LLVM/Clang, targeting modern C++ (C++20/23). It uses a multi-process architecture with a master server coordinating stateless and stateful workers.
+
+## Core Correction Patterns — Lessons from Past Interactions
+
+The following patterns were extracted from extensive real-world collaboration. These are recurring mistakes that MUST be avoided. Read them carefully — they represent hard-won lessons, not hypothetical concerns.
+
+### Pattern 1: Misjudging Real-World Priorities
+
+AI tends to optimize whatever metric looks most impressive, rather than what actually matters in the user's real scenario.
+
+**Example**: During performance optimization, the AI proudly reported "hot cache is 4-7x faster!" — but the function in question runs at LSP server startup, which is ALWAYS a cold start. Optimizing hot cache was completely meaningless.
+
+**Rule**: Before optimizing or analyzing anything, first understand the REAL usage scenario. Ask yourself: "When does this code actually run? What does the user actually experience?" Do not chase metrics that look good on paper but are irrelevant in practice.
+
+### Pattern 2: Pushing Without Local Verification
+
+The most common and most damaging pattern. AI proposes a fix, pushes it immediately, CI fails, then another fix, push, fail again — wasting CI cycles and the user's time.
+
+**Rule**: NEVER push code that you haven't verified locally. Before every push:
+
+- Build locally with the same configuration CI uses.
+- Run the relevant tests locally and confirm they pass.
+- If you cannot reproduce the CI environment locally, say so — do not just "try and see."
+- "It compiles" is NOT sufficient. Tests must pass.
+
+### Pattern 3: Superficial Refactoring
+
+When asked to refactor, AI tends to do mechanical code movement (copy functions from A to B) without understanding the deeper design intent (ownership, responsibility boundaries, API cleanliness).
+
+**Example**: When splitting `MasterServer` into `Workspace` and `Session`, the AI moved functions but kept ugly APIs like `f(path_id, sessions_map)` instead of the clean `f(Session&)` that the refactoring was meant to achieve.
+
+**Rule**: When refactoring, understand the WHY. Ask: "What design problem is this refactoring solving?" If you're just moving code around without improving the abstractions, you're not refactoring — you're rearranging deck chairs.
+
+### Pattern 4: Fixing Only the Immediate Instance, Not the Pattern
+
+When given a cleanup instruction, AI applies it to the single file or function currently being discussed, ignoring all other occurrences in the project.
+
+**Example**: User says "remove decorative `===` comment separators." AI removes them from `workspace.cpp` only. User has to say: "The other files too!"
+
+**Rule**: When given a cleanup or style instruction, apply it project-wide. Use `Grep` to find ALL occurrences and fix them all in one pass. Think: "Where else does this pattern appear?"
+
+### Pattern 5: Never Skip, Disable, or Work Around Failing Tests
+
+When stuck on a difficult bug (especially flaky CI, race conditions, platform-specific issues), AI may propose marking tests as `continue-on-error`, skipping them, or adding `expected-failure` annotations to make CI green.
+
+**Rule**: This is ABSOLUTELY FORBIDDEN. If a test fails, fix the root cause. There are ZERO exceptions. Skipping a test to make CI green is not "fixing" — it is hiding a bug. If you ever find yourself thinking "maybe we should just skip this test," stop and reconsider your approach entirely.
+
+### Pattern 6: Excessive Confirmation Seeking vs. Premature Execution
+
+AI oscillates between two extremes: asking "should I do X?" for every trivial decision, or silently executing major changes without confirmation.
+
+**Rule**: Calibrate based on reversibility and impact:
+
+- **Small, reversible changes** (formatting, renaming a local variable, adding a test): just do it.
+- **Architecture decisions, API changes, large refactors**: propose the plan first, wait for confirmation.
+- **Pushing to remote, creating PRs, modifying CI**: always confirm.
+- When the user says "go ahead" or "do it," execute fully without asking again mid-way.
+
+## Code Reuse & Understanding Before Implementation
+
+**This is the single most important rule in this project.** Before writing ANY new code, you MUST thoroughly read and understand the existing codebase first. This project has a rich set of utilities, abstractions, and patterns already in place — duplicating them wastes effort and creates maintenance burden.
+
+Concrete requirements:
+
+1. **Read before you write.** Before implementing a feature or fix, explore the relevant modules in `src/`. Search for existing helpers, utilities, and patterns that solve the same or similar problems. Use `Grep`, `Glob`, and `Agent` tools to investigate thoroughly — do not assume something doesn't exist just because you haven't seen it yet.
+
+2. **Reuse existing infrastructure.** This project already has:
+   - A `Lexer` class (`src/syntax/lexer.h`) — do not hand-write token scanning logic.
+   - A `PositionMapper` for source location conversion — do not reimplement offset-to-line/column math.
+   - `CompilationUnitRef` methods (`decompose_location`, `decompose_range`, `file_path`, `directives`, etc.) — use them instead of raw Clang APIs.
+   - `SemanticVisitor` for AST traversal — extend it, do not write custom recursive AST walkers.
+   - `Tester` framework for unit tests with VFS, annotation support, and multi-phase compilation — use it, do not create ad-hoc test setups.
+   - Utility functions in `src/support/` — check there before writing new helpers.
+
+3. **Follow established patterns.** When adding a new feature (e.g., a new LSP request handler), look at how 2-3 existing features of the same kind are implemented. Match their structure: same file organization, same function signatures, same error handling patterns. If every other feature in `src/feature/` follows a certain pattern, yours should too.
+
+4. **Do not reinvent what the project already has.** If you find yourself writing a helper function that feels generic (string manipulation, path handling, JSON serialization, source range conversion), STOP and search the codebase first. There is a high probability it already exists. Creating duplicates leads to inconsistencies and bugs when one copy gets updated but the other doesn't.
+
+5. **When in doubt, ask.** If you're unsure whether an existing utility covers your use case or whether to extend an existing abstraction vs. create a new one, ask the user rather than guessing.
+
+## Source Layout
+
+- `src/server/` — LSP server core: master server, compiler, indexer, stateful/stateless workers
+- `src/feature/` — LSP feature implementations: hover, completion, document links, semantic tokens, etc.
+- `src/compile/` — Compilation orchestration: compilation unit, directives, diagnostics
+- `src/index/` — Symbol indexing: TUIndex, ProjectIndex, MergedIndex, include graph
+- `src/semantic/` — Semantic analysis: symbol kinds, relations, AST visitor, template resolver
+- `src/syntax/` — Lexer, scanner, token types, dependency graph
+- `src/command/` — CLI parsing, compilation database, toolchain detection
+- `src/support/` — Utilities: logging, filesystem, JSON, string helpers
+
+## Build System
+
+- Uses **pixi** for environment management and **CMake + Ninja** for building.
+- Two build types: `Debug` and `RelWithDebInfo` (default).
+- Build output goes to `build/[type]/`.
+- See `/build`, `/test`, `/format` commands for common operations.
+
+## Commit Message Format
+
+Use **conventional commits** — enforced by CI:
+
+```
+<type>(<scope>): <short description>
+```
+
+- **Types**: `feat`, `fix`, `refactor`, `chore`, `docs`, `ci`, `test`
+- **Scopes**: match `src/` subdirectories or feature names, e.g. `completion`, `server`, `index`, `tests`, `document links`
+- Keep the subject line under 70 characters.
+
+## Tests
+
+Three types of tests, all must pass before committing:
+
+- **Unit tests** (`tests/unit/`): C++ tests using the project's own test framework. Test names should be at most 4 words.
+- **Integration tests** (`tests/integration/`): Python pytest tests that start a real clice server and communicate via LSP.
+- **Smoke tests** (`tests/smoke/`): Replay recorded LSP sessions via `tests/replay.py`.
+
+### Integration Test Style
+
+- Keep tests concise. Do NOT write large comment blocks explaining the test layout or expected behavior.
+- Use descriptive test function names and short inline comments only where logic is non-obvious.
+
+## Pre-PR Review
+
+Before opening a PR, launch **3 parallel subagents** to review the diff independently:
+
+1. **Correctness reviewer**: Check for logic errors, edge cases, undefined behavior, and off-by-one mistakes.
+2. **Style reviewer**: Verify the code follows this project's naming conventions, coding style, and CLAUDE.md rules.
+3. **Test reviewer**: Confirm test coverage is adequate — new functionality has tests, edge cases are covered, and no existing tests were broken or weakened.
+
+Each agent should read the full diff (`git diff main...HEAD`) and report issues. Fix all reported issues before opening the PR.
+
+## Pre-commit Checklist
+
+Before committing code, you MUST:
+
+1. **Run `pixi run format`** to format all source files.
+2. **Pass all three types of tests:**
+   - Unit tests: `pixi run unit-test [type]`
+   - Integration tests: `pixi run integration-test [type]`
+   - Smoke tests: `pixi run smoke-test [type]`
+3. **All test failures must be fixed before committing.** This is a HARD REQUIREMENT with NO exceptions:
+   - If a test fails, it MUST be fixed before you commit. Do NOT commit with known failures.
+   - Do NOT skip, disable, or mark tests as expected-failure to work around breakage.
+   - Do NOT argue "this test was already broken before my changes" — if it fails on your branch, it is YOUR responsibility to fix it before committing. The main branch CI is green; any failure on your branch is caused by your changes, period.
+   - Do NOT defer fixing to a follow-up PR. Fix it NOW, in this branch, before committing.
+
+---
+
+## C++ Coding Style
+
+### Template & Type Traits
+
+- Do NOT blindly add `std::remove_cvref_t` on every template parameter. Understand C++ template argument deduction rules:
+  - `template<typename T> void f(T x)` — `T` is always deduced as a non-reference, non-cv-qualified type. No need for `remove_cvref_t`.
+  - `template<typename T> void f(T& x)` — `T` is deduced as the referred-to type (possibly cv-qualified, but never a reference). No need for `remove_cvref_t` to strip references.
+  - `template<typename T> void f(const T& x)` — `T` is deduced as a non-const, non-reference type. No need for `remove_cvref_t`.
+  - `template<typename T> void f(T&& x)` — **forwarding reference**: `T` CAN be deduced as an lvalue reference (e.g., `int&`). This is the ONLY case where `std::remove_cvref_t<T>` is needed to get the bare type.
+  - Class template parameters and return types are also never deduced as references; don't add `remove_cvref_t` on them either.
+
+### Type Traits & Concepts (C++20/23)
+
+- This project targets C++20/23. Use variable templates directly for type traits — do NOT use the old pattern of wrapping a class template static member in a variable template. Prefer:
+
+  ```cpp
+  // Good: directly specialize a variable template
+  template<typename T>
+  inline constexpr bool is_my_type_v = false;
+
+  template<>
+  inline constexpr bool is_my_type_v<MyType> = true;
+  ```
+
+  ```cpp
+  // Bad: unnecessary class template wrapper
+  template<typename T>
+  struct is_my_type : std::false_type {};
+
+  template<>
+  struct is_my_type<MyType> : std::true_type {};
+
+  template<typename T>
+  inline constexpr bool is_my_type_v = is_my_type<T>::value;
+  ```
+
+- When defining a concept that checks a type trait, do NOT add `std::remove_cvref_t` unless you specifically intend the concept to see through references/cv-qualifiers. If the concept is meant for a bare type, just use `T` directly — the caller is responsible for passing the right type.
+
+  ```cpp
+  // Good
+  template<typename T>
+  concept MyTrait = is_my_type_v<T>;
+
+  // Bad: unnecessary remove_cvref_t
+  template<typename T>
+  concept MyTrait = is_my_type_v<std::remove_cvref_t<T>>;
+  ```
+
+### Naming Conventions
+
+- **Variables, member fields, function names**: `snake_case`. Class member fields do NOT use any special suffix/prefix (no trailing `_`, no `m_` prefix).
+- **Class names, template parameter names, enum names**: `PascalCase`. Exception: some class names also use `snake_case` — follow the existing style in the project.
+- **Enum values**: `PascalCase`.
+
+### String Literals
+
+- Prefer C++11 raw string literals `R"(...)"` over escaped strings. Avoid `\"`, `\\`, `\n` in string literals when a raw literal is cleaner.
+
+### Error Handling
+
+- **Prefer `if` with init-statements to tightly scope error variables**, but avoid them when they compromise code readability or flatten control flow.
+- **Omit redundant conditions:** If the error type provides an `operator bool` or evaluates implicitly (e.g., standard error codes, custom error wrappers), omit the redundant condition check.
+- **Avoid forced `else` branches:** If scoping the variable inside the `if` requires you to introduce an `else` block for the success path (especially when returning early on error), declare the variable in the local scope instead to keep the control flow flat.
+
+```cpp
+// Good: Omit redundant condition when the type has operator bool
+if (auto err = foo()) {
+    /* handle error */
+}
+
+// Bad: Redundant condition check
+if (auto err = foo(); err) {
+    /* handle error */
+}
+
+// Good: Use init-statement when a custom condition is required,
+// AND the variable isn't needed outside the if-statement
+if (auto result = foo(); !result.has_value()) {
+    /* handle error */
+}
+
+// --- Scope and Control Flow Considerations ---
+
+// Bad: Using init-statement forces an 'else' block because 'result'
+// goes out of scope, leading to nested/redundant code.
+if (auto result = get_data(); !result.has_value()) {
+    return result.error();
+} else {
+    process(result.value()); // Success path is forced into a nested block
+}
+
+// Good: Declare as a regular local variable to allow early exit
+// and keep the success path un-nested (flat control flow).
+auto result = get_data();
+if (!result.has_value()) {
+    return result.error();
+}
+process(result.value());
+```
+
+### Style
+
+- Prefer `[[maybe_unused]]` over `(void)` for intentionally unused variables or parameters.
+
+### Modern C++ Usage
+
+- Use C++20/23 APIs whenever possible. Do NOT use `<iostream>` facilities (`std::cout`, `std::cin`, `std::cerr`, etc.). Also do NOT use C-style I/O (`printf`, `fprintf`, etc.).
+- Prefer `std::ranges` / `std::views` APIs over raw loops and traditional `<algorithm>` calls.
+- If the project depends on LLVM, prefer LLVM's efficient data structures (e.g., `llvm::SmallVector`, `llvm::DenseMap`, `llvm::StringMap`, `llvm::StringRef`) over their `std` counterparts when appropriate.
+
+### Parameter Passing Preferences
+
+- For string parameters, prefer `llvm::StringRef` > `std::string_view` > `const std::string&`.
+- For array/span parameters, prefer `llvm::ArrayRef` > `std::span` > `const std::vector&`.

.claude/commands/build.md

@@ -0,0 +1,15 @@
+Build the project. Accepts an optional argument for build type: `Debug` or `RelWithDebInfo` (default).
+
+Available build commands:
+
+- CMake configure only: `pixi run cmake-config [type]`
+- CMake build only (skip configure): `pixi run cmake-build [type]`
+- Full build (configure + build): `pixi run build [type]`
+- Build a specific target: `pixi run cmake-build [type]` then `cmake --build build/[type] --target [target]`
+
+Common targets: `clice`, `unit_tests`
+
+Example usage:
+
+- `/build` — full build RelWithDebInfo
+- `/build Debug` — full build Debug

.claude/commands/format.md

@@ -0,0 +1,5 @@
+Format all project source files.
+
+Run: `pixi run format`
+
+Formats C++, Python, Lua, JS/TS, Markdown, JSON, TOML, and YAML files.

.claude/commands/test.md

@@ -0,0 +1,19 @@
+Run tests. Accepts an optional argument for build type: `Debug` or `RelWithDebInfo` (default).
+
+Available test commands:
+
+- Unit tests: `pixi run unit-test [type]`
+- Integration tests: `pixi run integration-test [type]`
+- Smoke tests: `pixi run smoke-test [type]`
+- All tests (unit + integration): `pixi run test [type]`
+
+Filtering specific tests:
+
+- Unit tests: `pixi run unit-test [type] --test-filter=SuiteName.CaseName`
+- Integration tests: `pixi run pytest tests/integration -k "test_name" --executable=./build/[type]/bin/clice`
+- Smoke tests: `pixi run python tests/replay.py tests/smoke/specific.jsonl --clice=./build/[type]/bin/clice`
+
+Example usage:
+
+- `/test` — run all tests (RelWithDebInfo)
+- `/test Debug` — run all tests (Debug)

.coderabbit.yaml

@@ -1,2 +1,7 @@
 chat:
   auto_reply: false
+reviews:
+  auto_review:
+    enabled: true
+  summary:
+    enabled: false

.github/actions/setup-pixi/action.yml

@@ -13,7 +13,7 @@ runs:
     - name: Setup Pixi
       uses: prefix-dev/setup-pixi@v0.9.3
       with:
-        pixi-version: v0.62.0
+        pixi-version: v0.67.0
         environments: ${{ inputs.environments }}
         activate-environment: true
         cache: true

.github/workflows/benchmark.yml

@@ -1,8 +1,7 @@
 name: benchmark
 
 on:
-  pull_request:
-    branches: [main]
+  workflow_dispatch:
 
 jobs:
   benchmark:
@@ -22,7 +21,7 @@ jobs:
 
       - name: Build scan_benchmark
         run: |
-          pixi run cmake-config RelWithDebInfo ON "-DCLICE_ENABLE_BENCHMARK=ON"
+          pixi run cmake-config RelWithDebInfo ON -- -DCLICE_ENABLE_BENCHMARK=ON
           cmake --build build/RelWithDebInfo --target scan_benchmark
 
       - name: Clone LLVM

.github/workflows/build-llvm.yml

@@ -1,6 +1,22 @@
 name: build llvm
 
 on:
+  workflow_dispatch:
+    inputs:
+      llvm_version:
+        description: "LLVM version to build (e.g., 21.1.8)"
+        required: true
+        type: string
+      skip_upload:
+        description: "Skip upload and PR creation (build-only mode)"
+        required: false
+        type: boolean
+        default: false
+      skip_pr:
+        description: "Skip PR creation (upload only, no PR)"
+        required: false
+        type: boolean
+        default: false
   pull_request:
     # if you want to run this workflow, change the branch name to main,
     # if you want to turn off it, change it to non existent branch.
@@ -12,9 +28,7 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - os: windows-2025
-            llvm_mode: Debug
-            lto: OFF
+          # Native builds
           - os: windows-2025
             llvm_mode: RelWithDebInfo
             lto: OFF
@@ -39,6 +53,42 @@ jobs:
           - os: macos-15
             llvm_mode: RelWithDebInfo
             lto: ON
+
+          # Cross-compilation builds
+          # macOS x64 (from arm64 macos-15)
+          - os: macos-15
+            llvm_mode: RelWithDebInfo
+            lto: OFF
+            target_triple: x86_64-apple-darwin
+          - os: macos-15
+            llvm_mode: RelWithDebInfo
+            lto: ON
+            target_triple: x86_64-apple-darwin
+
+          # Linux aarch64 (from x64 ubuntu-24.04)
+          - os: ubuntu-24.04
+            llvm_mode: RelWithDebInfo
+            lto: OFF
+            target_triple: aarch64-linux-gnu
+            pixi_env: cross-linux-aarch64
+          - os: ubuntu-24.04
+            llvm_mode: RelWithDebInfo
+            lto: ON
+            target_triple: aarch64-linux-gnu
+            pixi_env: cross-linux-aarch64
+
+          # Windows arm64 (from x64 windows-2025)
+          - os: windows-2025
+            llvm_mode: RelWithDebInfo
+            lto: OFF
+            target_triple: aarch64-pc-windows-msvc
+            pixi_env: cross-windows-arm64
+          - os: windows-2025
+            llvm_mode: RelWithDebInfo
+            lto: ON
+            target_triple: aarch64-pc-windows-msvc
+            pixi_env: cross-windows-arm64
+
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout repository
@@ -67,49 +117,91 @@ jobs:
           free -h
           df -h
 
-      - name: Setup Pixi
-        uses: prefix-dev/setup-pixi@v0.9.3
+      - uses: ./.github/actions/setup-pixi
         with:
-          pixi-version: v0.59.0
-          environments: package
-          activate-environment: true
-          cache: true
-          locked: true
+          environments: ${{ matrix.pixi_env || 'package' }}
 
-      - name: Clone llvm-project (21.1.4)
+      - name: Clone llvm-project
         shell: bash
         run: |
-          git clone --branch llvmorg-21.1.4 --depth 1 https://github.com/llvm/llvm-project.git .llvm
+          VERSION="${{ inputs.llvm_version || '21.1.8' }}"
+          echo "Cloning LLVM ${VERSION}..."
+          git clone --branch "llvmorg-${VERSION}" --depth 1 https://github.com/llvm/llvm-project.git .llvm
+
+      - name: Validate distribution components
+        shell: bash
+        run: |
+          python3 scripts/validate-llvm-components.py \
+            --llvm-src=.llvm \
+            --components-file=scripts/llvm-components.json
 
       - name: Build LLVM (install-distribution)
         shell: bash
         run: |
-          pixi run build-llvm --llvm-src=.llvm --mode="${{ matrix.llvm_mode }}" --lto="${{ matrix.lto }}" --build-dir=build
+          ENV="${{ matrix.pixi_env || 'package' }}"
+          EXTRA_ARGS=""
+          if [[ -n "${{ matrix.target_triple }}" ]]; then
+            EXTRA_ARGS="--target-triple=${{ matrix.target_triple }}"
+          fi
+          pixi run -e "$ENV" build-llvm \
+            --llvm-src=.llvm \
+            --mode="${{ matrix.llvm_mode }}" \
+            --lto="${{ matrix.lto }}" \
+            --build-dir=build \
+            ${EXTRA_ARGS}
 
       - name: Build clice using installed LLVM
+        if: ${{ !matrix.target_triple }}
         shell: bash
         run: |
-          cmake -B build -G Ninja \
-            -DCMAKE_BUILD_TYPE=${{ matrix.llvm_mode }} \
-            -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain.cmake \
-            -DCLICE_ENABLE_TEST=ON \
-            -DCLICE_CI_ENVIRONMENT=ON \
-            -DCLICE_ENABLE_LTO=${{ matrix.lto }} \
-            -DLLVM_INSTALL_PATH=".llvm/build-install"
-          cmake --build build
+          pixi run cmake-config ${{ matrix.llvm_mode }} ON -- \
+            "-DCLICE_ENABLE_LTO=${{ matrix.lto }}" \
+            "-DLLVM_INSTALL_PATH=.llvm/build-install"
+          pixi run cmake-build ${{ matrix.llvm_mode }}
+
+      - name: Build clice using installed LLVM (cross-compile)
+        if: ${{ matrix.target_triple }}
+        shell: bash
+        run: |
+          ENV="${{ matrix.pixi_env || 'package' }}"
+          pixi run -e "$ENV" cmake-config ${{ matrix.llvm_mode }} ON -- \
+            "-DCLICE_ENABLE_LTO=${{ matrix.lto }}" \
+            "-DCLICE_TARGET_TRIPLE=${{ matrix.target_triple }}" \
+            "-DLLVM_INSTALL_PATH=.llvm/build-install"
+          pixi run -e "$ENV" cmake-build ${{ matrix.llvm_mode }}
+
+      - name: Verify cross-compiled binary architecture
+        if: ${{ matrix.target_triple && runner.os != 'Windows' }}
+        shell: bash
+        run: |
+          BINARY="build/${{ matrix.llvm_mode }}/bin/clice"
+          echo "Binary info:"
+          file "$BINARY"
+          case "${{ matrix.target_triple }}" in
+            aarch64-linux-gnu)   file "$BINARY" | grep -q "aarch64" ;;
+            x86_64-apple-darwin) file "$BINARY" | grep -q "x86_64" ;;
+          esac
+
+      - name: Upload cross-compiled clice for functional test
+        if: ${{ matrix.target_triple && matrix.lto == 'OFF' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: cross-clice-${{ matrix.target_triple }}-${{ matrix.llvm_mode }}
+          path: |
+            build/${{ matrix.llvm_mode }}/bin/
+            build/${{ matrix.llvm_mode }}/lib/
+          if-no-files-found: error
+          retention-days: 1
 
       - name: Run tests
+        if: ${{ !matrix.target_triple }}
         shell: bash
-        run: |
-          EXE_EXT=""
-          if [[ "${{ runner.os }}" == "Windows" ]]; then
-            EXE_EXT=".exe"
-          fi
-          ./build/bin/unit_tests${EXE_EXT} --test-dir="./tests/data"
-          uv run --project tests pytest -s --log-cli-level=INFO tests/integration --executable=./build/bin/clice${EXE_EXT}
+        run: pixi run test ${{ matrix.llvm_mode }}
 
+      # Prune is only supported for native builds (requires linking clice to test).
+      # Cross-compiled targets reuse the native prune manifest of the same OS.
       - name: Prune LLVM static libraries (Debug/RelWithDebInfo no LTO)
-        if: matrix.llvm_mode == 'Debug' || (matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'OFF')
+        if: (!matrix.target_triple) && (matrix.llvm_mode == 'Debug' || (matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'OFF'))
         shell: bash
         run: |
           MANIFEST="pruned-libs-${{ matrix.os }}.json"
@@ -117,13 +209,13 @@ jobs:
           python3 scripts/prune-llvm-bin.py \
             --action discover \
             --install-dir ".llvm/build-install/lib" \
-            --build-dir "build" \
+            --build-dir "build/${{ matrix.llvm_mode }}" \
             --max-attempts 60 \
             --sleep-seconds 60 \
             --manifest "${MANIFEST}"
 
       - name: Upload pruned-libs manifest
-        if: matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'OFF'
+        if: (!matrix.target_triple) && matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'OFF'
         uses: actions/upload-artifact@v4
         with:
           name: llvm-pruned-libs-${{ matrix.os }}
@@ -131,8 +223,8 @@ jobs:
           if-no-files-found: error
           compression-level: 0
 
-      - name: Apply pruned-libs manifest (RelWithDebInfo + LTO)
-        if: matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'ON'
+      - name: Apply pruned-libs manifest (RelWithDebInfo + LTO, native only)
+        if: (!matrix.target_triple) && matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'ON'
         shell: bash
         env:
           GH_TOKEN: ${{ github.token }}
@@ -142,7 +234,27 @@ jobs:
             --action apply \
             --manifest "${MANIFEST}" \
             --install-dir ".llvm/build-install/lib" \
-            --build-dir "build" \
+            --build-dir "build/${{ matrix.llvm_mode }}" \
+            --gh-run-id "${{ github.run_id }}" \
+            --gh-artifact "llvm-pruned-libs-${{ matrix.os }}" \
+            --gh-download-dir "artifacts" \
+            --max-attempts 60 \
+            --sleep-seconds 60
+
+      # For cross-compiled LTO builds, apply the native prune manifest.
+      # The unused library set is arch-independent (same API surface).
+      - name: Apply pruned-libs manifest (cross-compile + LTO)
+        if: matrix.target_triple && matrix.lto == 'ON'
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          MANIFEST="pruned-libs-${{ matrix.os }}.json"
+          python3 scripts/prune-llvm-bin.py \
+            --action apply \
+            --manifest "${MANIFEST}" \
+            --install-dir ".llvm/build-install/lib" \
+            --build-dir "build/${{ matrix.llvm_mode }}" \
             --gh-run-id "${{ github.run_id }}" \
             --gh-artifact "llvm-pruned-libs-${{ matrix.os }}" \
             --gh-download-dir "artifacts" \
@@ -157,23 +269,35 @@ jobs:
             MODE_TAG="debug"
           fi
 
-          ARCH="x64"
-          PLATFORM="linux"
-          TOOLCHAIN="gnu"
-          if [[ "${{ matrix.os }}" == windows-* ]]; then
-            PLATFORM="windows"
-            TOOLCHAIN="msvc"
-          elif [[ "${{ matrix.os }}" == macos-* ]]; then
-            ARCH="arm64"
-            PLATFORM="macos"
-            TOOLCHAIN="clang"
+          # Determine arch/platform/toolchain from target triple or runner OS
+          if [[ -n "${{ matrix.target_triple }}" ]]; then
+            case "${{ matrix.target_triple }}" in
+              x86_64-apple-darwin)
+                ARCH="x64"; PLATFORM="macos"; TOOLCHAIN="clang" ;;
+              aarch64-linux-gnu)
+                ARCH="aarch64"; PLATFORM="linux"; TOOLCHAIN="gnu" ;;
+              aarch64-pc-windows-msvc)
+                ARCH="aarch64"; PLATFORM="windows"; TOOLCHAIN="msvc" ;;
+            esac
+          else
+            ARCH="x64"
+            PLATFORM="linux"
+            TOOLCHAIN="gnu"
+            if [[ "${{ matrix.os }}" == windows-* ]]; then
+              PLATFORM="windows"
+              TOOLCHAIN="msvc"
+            elif [[ "${{ matrix.os }}" == macos-* ]]; then
+              ARCH="arm64"
+              PLATFORM="macos"
+              TOOLCHAIN="clang"
+            fi
           fi
 
           SUFFIX=""
           if [[ "${{ matrix.lto }}" == "ON" ]]; then
             SUFFIX="-lto"
           fi
-          if [[ "${{ matrix.llvm_mode }}" == "Debug" ]]; then
+          if [[ "${{ matrix.llvm_mode }}" == "Debug" && "${{ matrix.os }}" != windows-* ]]; then
             SUFFIX="${SUFFIX}-asan"
           fi
 
@@ -189,3 +313,134 @@ jobs:
           name: ${{ env.LLVM_INSTALL_ARCHIVE }}
           path: ${{ env.LLVM_INSTALL_ARCHIVE }}
           if-no-files-found: error
+
+  test-cross:
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-15-intel
+            llvm_mode: RelWithDebInfo
+            target_triple: x86_64-apple-darwin
+          - os: ubuntu-24.04-arm
+            llvm_mode: RelWithDebInfo
+            target_triple: aarch64-linux-gnu
+          - os: windows-11-arm
+            llvm_mode: RelWithDebInfo
+            target_triple: aarch64-pc-windows-msvc
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - uses: ./.github/actions/setup-pixi
+        with:
+          environments: test-run
+
+      - name: Download cross-compiled clice
+        uses: actions/download-artifact@v4
+        with:
+          name: cross-clice-${{ matrix.target_triple }}-${{ matrix.llvm_mode }}
+          path: build/${{ matrix.llvm_mode }}/
+
+      - name: Make binaries executable
+        if: runner.os != 'Windows'
+        run: chmod +x build/${{ matrix.llvm_mode }}/bin/*
+
+      - name: Run tests
+        run: pixi run -e test-run test ${{ matrix.llvm_mode }}
+
+  upload:
+    needs: build
+    if: ${{ !cancelled() && inputs.llvm_version && !inputs.skip_upload }}
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download all build artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: scripts/download-llvm.sh "${{ github.run_id }}"
+
+      - name: Upload to clice-llvm
+        env:
+          GH_TOKEN: ${{ secrets.UPLOAD_LLVM }}
+          TARGET_REPO: clice-io/clice-llvm
+        run: python3 scripts/upload-llvm.py "${{ inputs.llvm_version }}" "${TARGET_REPO}" "${{ github.run_id }}"
+
+      - name: Save manifest for update-clice job
+        uses: actions/upload-artifact@v4
+        with:
+          name: llvm-manifest-final
+          path: artifacts/llvm-manifest.json
+          if-no-files-found: error
+          compression-level: 0
+
+  update-clice:
+    needs: upload
+    if: ${{ !inputs.skip_pr }}
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download manifest
+        uses: actions/download-artifact@v4
+        with:
+          name: llvm-manifest-final
+          path: .
+
+      - name: Update manifest and version
+        run: |
+          python3 scripts/update-llvm-version.py \
+            --version "${{ inputs.llvm_version }}" \
+            --manifest-src llvm-manifest.json \
+            --manifest-dest config/llvm-manifest.json \
+            --package-cmake cmake/package.cmake
+
+      - name: Create or update PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          VERSION="${{ inputs.llvm_version }}"
+          BRANCH="chore/update-llvm-${VERSION}"
+          RUN_URL="https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          RELEASE_URL="https://github.com/clice-io/clice-llvm/releases/tag/${VERSION}"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "${BRANCH}"
+          git add config/llvm-manifest.json cmake/package.cmake
+          git commit -m "chore: update LLVM to ${VERSION}"
+          git push --force-with-lease origin "${BRANCH}"
+
+          # Check if PR already exists for this branch
+          EXISTING_PR=$(gh pr list --head "${BRANCH}" --json number --jq '.[0].number // empty')
+
+          BODY="$(cat <<EOF
+          ## Summary
+          - Update LLVM prebuilt binaries to version ${VERSION}
+          - Updated \`config/llvm-manifest.json\` with new SHA256 hashes
+          - Updated \`cmake/package.cmake\` version string
+
+          **Artifacts:** [clice-llvm release](${RELEASE_URL})
+          **Build:** [workflow run](${RUN_URL})
+
+          > Auto-generated by build-llvm workflow
+          EOF
+          )"
+
+          if [[ -n "${EXISTING_PR}" ]]; then
+            echo "Updating existing PR #${EXISTING_PR}"
+            gh pr edit "${EXISTING_PR}" --body "${BODY}"
+          else
+            gh pr create \
+              --title "chore: update LLVM to ${VERSION}" \
+              --body "${BODY}" \
+              --base main
+          fi

.github/workflows/check-format.yml

@@ -14,6 +14,12 @@ jobs:
         with:
           environments: format
 
+      - name: Validate update-llvm-version.py can still patch package.cmake
+        run: |
+          python3 scripts/update-llvm-version.py --check \
+            --manifest-dest config/llvm-manifest.json \
+            --package-cmake cmake/package.cmake
+
       - name: Run formatter
         run: pixi run format
         continue-on-error: true

.github/workflows/main.yml

@@ -7,6 +7,10 @@ on:
   pull_request:
     branches: [main]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
 jobs:
   changes:
     if: ${{ !startsWith(github.ref, 'refs/tags/') }}
@@ -19,7 +23,7 @@ jobs:
       clice: ${{ steps.filter.outputs.clice }}
       vscode: ${{ steps.filter.outputs.vscode }}
       cmake: ${{ steps.filter.outputs.cmake }}
-      xmake: ${{ steps.filter.outputs.xmake }}
+
     steps:
       - uses: actions/checkout@v4
       - uses: dorny/paths-filter@v3
@@ -46,13 +50,31 @@ jobs:
               - 'tests/**'
               - 'config/**'
               - '.github/workflows/test-cmake.yml'
-            xmake:
-              - 'xmake.lua'
-              - 'src/**'
-              - 'include/**'
-              - 'tests/**'
-              - 'config/**'
-              - '.github/workflows/test-xmake.yml'
+
+  conventional-commit:
+    if: ${{ !startsWith(github.ref, 'refs/tags/') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check conventional commit format
+        env:
+          IS_PR: ${{ github.event_name == 'pull_request' }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          COMMIT_MSG: ${{ github.event.head_commit.message }}
+        run: |
+          pattern='^(feat|fix|refactor|chore|build|ci|docs|test|perf|style|revert)(\(.+\))?: .+'
+          if [[ "$IS_PR" == "true" ]]; then
+            subject="$PR_TITLE"
+            label="PR title"
+          else
+            subject=$(echo "$COMMIT_MSG" | head -n1)
+            label="Commit message"
+          fi
+          if [[ ! "$subject" =~ $pattern ]]; then
+            echo "::error::$label must follow conventional commit format: type(scope)?: description"
+            echo "  Valid types: feat, fix, refactor, chore, build, ci, docs, test, perf, style, revert"
+            echo "  Got: '$subject'"
+            exit 1
+          fi
 
   format:
     needs: changes
@@ -82,11 +104,6 @@ jobs:
     if: ${{ needs.changes.outputs.cmake == 'true' }}
     uses: ./.github/workflows/test-cmake.yml
 
-  # xmake:
-  #   needs: changes
-  #   if: ${{ needs.changes.outputs.xmake == 'true' }}
-  #   uses: ./.github/workflows/test-xmake.yml
-
   release-clice:
     permissions:
       contents: write
@@ -104,16 +121,17 @@ jobs:
   checks-passed:
     if: ${{ always() && !startsWith(github.ref, 'refs/tags/') }}
     needs:
+      - conventional-commit
       - format
       - deploy
       # - clice
       - vscode
       - cmake
-      # - xmake
+
     runs-on: ubuntu-latest
     steps:
       - name: Check results
         uses: re-actors/alls-green@release/v1
         with:
-          allowed-skips: format,deploy,clice,vscode,cmake,xmake
+          allowed-skips: conventional-commit,format,deploy,clice,vscode,cmake
           jobs: ${{ toJSON(needs) }}

.github/workflows/publish-clice.yml

@@ -9,6 +9,7 @@ jobs:
       fail-fast: false
       matrix:
         include:
+          # Native builds
           - os: windows-2025
             artifact_name: clice.zip
             asset_name: clice-x64-windows-msvc.zip
@@ -27,43 +28,63 @@ jobs:
             symbol_artifact_name: clice-symbol.tar.gz
             symbol_asset_name: clice-arm64-macos-darwin-symbol.tar.gz
 
+          # Cross-compilation builds
+          - os: macos-15
+            target_triple: x86_64-apple-darwin
+            pixi_env: cross-macos-x64
+            artifact_name: clice.tar.gz
+            asset_name: clice-x86_64-macos-darwin.tar.gz
+            symbol_artifact_name: clice-symbol.tar.gz
+            symbol_asset_name: clice-x86_64-macos-darwin-symbol.tar.gz
+
+          - os: ubuntu-24.04
+            target_triple: aarch64-linux-gnu
+            pixi_env: cross-linux-aarch64
+            artifact_name: clice.tar.gz
+            asset_name: clice-aarch64-linux-gnu.tar.gz
+            symbol_artifact_name: clice-symbol.tar.gz
+            symbol_asset_name: clice-aarch64-linux-gnu-symbol.tar.gz
+
+          - os: windows-2025
+            target_triple: aarch64-pc-windows-msvc
+            pixi_env: cross-windows-arm64
+            artifact_name: clice.zip
+            asset_name: clice-aarch64-windows-msvc.zip
+            symbol_artifact_name: clice-symbol.zip
+            symbol_asset_name: clice-aarch64-windows-msvc-symbol.zip
+
     runs-on: ${{ matrix.os }}
 
+    defaults:
+      run:
+        shell: bash
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup xmake
-        uses: xmake-io/github-action-setup-xmake@v1
-        with:
-          xmake-version: 3.0.5
-          actions-cache-folder: ".xmake-cache"
-          actions-cache-key: ${{ matrix.os }}
-          package-cache: true
-          package-cache-key: ${{ matrix.os }}-pkg-release-v1
-          build-cache: true
-          build-cache-key: ${{ matrix.os }}-build-release-v1
-
       - uses: ./.github/actions/setup-pixi
         with:
-          environments: package
+          environments: ${{ matrix.pixi_env || 'package' }}
 
-      - name: Remove ci llvm toolchain on Windows
-        if: runner.os == 'Windows'
-        run: |
-          # @see https://github.com/xmake-io/xmake/issues/7158
-          xmake lua os.rmdir "C:/Program Files/Microsoft Visual Studio/2022/Enterprise/VC/Tools/Llvm"
-          xmake lua os.rmdir "C:/Program Files/LLVM"
-
-      - name: Package
+      - name: Package (native)
+        if: ${{ !matrix.target_triple }}
         run: pixi run package
 
+      - name: Package (cross-compile)
+        if: ${{ matrix.target_triple }}
+        run: |
+          ENV="${{ matrix.pixi_env }}"
+          pixi run -e "$ENV" package-config -- \
+            "-DCLICE_TARGET_TRIPLE=${{ matrix.target_triple }}"
+          pixi run -e "$ENV" cmake-build
+
       - name: Upload Main Package to Release
         if: startsWith(github.ref, 'refs/tags/v')
         uses: svenstaro/upload-release-action@v2
         with:
           repo_token: ${{ secrets.GITHUB_TOKEN }}
-          file: build/xpack/clice/${{ matrix.artifact_name }}
+          file: build/RelWithDebInfo/${{ matrix.artifact_name }}
           asset_name: ${{ matrix.asset_name }}
           tag: ${{ github.ref }}
           overwrite: true
@@ -73,7 +94,7 @@ jobs:
         uses: svenstaro/upload-release-action@v2
         with:
           repo_token: ${{ secrets.GITHUB_TOKEN }}
-          file: build/xpack/clice/${{ matrix.symbol_artifact_name }}
+          file: build/RelWithDebInfo/${{ matrix.symbol_artifact_name }}
           asset_name: ${{ matrix.symbol_asset_name }}
           tag: ${{ github.ref }}
           overwrite: true

.github/workflows/test-cmake.yml

@@ -17,53 +17,154 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [windows-2025, ubuntu-24.04, macos-15]
-        build_type: [Debug, RelWithDebInfo]
+        include:
+          # Native builds
+          - os: windows-2025
+            build_type: RelWithDebInfo
+          - os: ubuntu-24.04
+            build_type: Debug
+          - os: ubuntu-24.04
+            build_type: RelWithDebInfo
+          - os: macos-15
+            build_type: Debug
+          - os: macos-15
+            build_type: RelWithDebInfo
+          # Cross-compile (build only; tests run on native runners)
+          - os: macos-15
+            build_type: RelWithDebInfo
+            target_triple: x86_64-apple-darwin
+            build_only: true
+          - os: ubuntu-24.04
+            build_type: RelWithDebInfo
+            target_triple: aarch64-linux-gnu
+            build_only: true
+            pixi_env: cross-linux-aarch64
+          - os: windows-2025
+            build_type: RelWithDebInfo
+            target_triple: aarch64-pc-windows-msvc
+            build_only: true
+            pixi_env: cross-windows-arm64
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
       - uses: ./.github/actions/setup-pixi
+        with:
+          environments: ${{ matrix.pixi_env || 'default' }}
 
       - name: Restore compiler cache
         uses: actions/cache@v4
         with:
           path: ${{ runner.os == 'Windows' && '.cache/sccache' || '.cache/ccache' }}
-          key: ${{ runner.os }}-${{ matrix.build_type }}-ccache-${{ github.sha }}
+          key: ${{ runner.os }}-${{ matrix.build_type }}-${{ matrix.target_triple || 'native' }}-ccache-${{ github.sha }}
           restore-keys: |
-            ${{ runner.os }}-${{ matrix.build_type }}-ccache-
+            ${{ runner.os }}-${{ matrix.build_type }}-${{ matrix.target_triple || 'native' }}-ccache-
 
       - name: Zero cache stats
         run: |
+          ENV="${{ matrix.pixi_env || 'default' }}"
           if [ "$RUNNER_OS" = "Windows" ]; then
-            pixi run -- sccache --stop-server || true
-            pixi run -- sccache --zero-stats || true
+            pixi run -e "$ENV" -- sccache --stop-server || true
+            pixi run -e "$ENV" -- sccache --zero-stats || true
           else
-            pixi run -- ccache --zero-stats || true
+            pixi run -e "$ENV" -- ccache --zero-stats || true
           fi
         shell: bash
 
-      - name: Build
+      - name: Build (native)
+        if: ${{ !matrix.target_triple }}
         run: pixi run build ${{ matrix.build_type }} ON
 
-      - name: Unit Test
+      - name: Build (cross-compile)
+        if: ${{ matrix.target_triple }}
+        shell: bash
+        run: |
+          ENV="${{ matrix.pixi_env || 'default' }}"
+          pixi run -e "$ENV" cmake-config ${{ matrix.build_type }} OFF -- \
+            "-DCLICE_TARGET_TRIPLE=${{ matrix.target_triple }}"
+          pixi run -e "$ENV" cmake-build ${{ matrix.build_type }}
+
+      - name: Upload cross-compiled binaries
+        if: ${{ matrix.build_only }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: cross-build-${{ matrix.target_triple }}
+          path: |
+            build/${{ matrix.build_type }}/bin/
+            build/${{ matrix.build_type }}/lib/
+          if-no-files-found: error
+          retention-days: 1
+
+      - name: Unit tests
+        if: ${{ !matrix.build_only }}
+        timeout-minutes: 5
         run: pixi run unit-test ${{ matrix.build_type }}
 
-      - name: Integration Test
+      - name: Integration tests
+        if: ${{ !matrix.build_only }}
+        timeout-minutes: 20
         run: pixi run integration-test ${{ matrix.build_type }}
 
-      - name: Smoke Test
-        if: success() || failure()
+      - name: Smoke tests
+        if: ${{ !matrix.build_only }}
+        timeout-minutes: 15
         run: pixi run smoke-test ${{ matrix.build_type }}
 
       - name: Print cache stats and stop server
         if: always()
         run: |
+          ENV="${{ matrix.pixi_env || 'default' }}"
           if [ "$RUNNER_OS" = "Windows" ]; then
-            pixi run -- sccache --show-stats
-            pixi run -- sccache --stop-server || true
+            pixi run -e "$ENV" -- sccache --show-stats
+            pixi run -e "$ENV" -- sccache --stop-server || true
           else
-            pixi run -- ccache --show-stats
+            pixi run -e "$ENV" -- ccache --show-stats
           fi
         shell: bash
+
+  test-cross:
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-15-intel
+            build_type: RelWithDebInfo
+            target_triple: x86_64-apple-darwin
+          - os: ubuntu-24.04-arm
+            build_type: RelWithDebInfo
+            target_triple: aarch64-linux-gnu
+          - os: windows-11-arm
+            build_type: RelWithDebInfo
+            target_triple: aarch64-pc-windows-msvc
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - uses: ./.github/actions/setup-pixi
+        with:
+          environments: test-run
+
+      - name: Download cross-compiled binaries
+        uses: actions/download-artifact@v4
+        with:
+          name: cross-build-${{ matrix.target_triple }}
+          path: build/${{ matrix.build_type }}/
+
+      - name: Make binaries executable
+        if: runner.os != 'Windows'
+        run: chmod +x build/${{ matrix.build_type }}/bin/*
+
+      - name: Unit tests
+        timeout-minutes: 5
+        run: pixi run -e test-run unit-test ${{ matrix.build_type }}
+
+      - name: Integration tests
+        timeout-minutes: 20
+        run: pixi run -e test-run integration-test ${{ matrix.build_type }}
+
+      - name: Smoke tests
+        timeout-minutes: 10
+        run: pixi run -e test-run smoke-test ${{ matrix.build_type }}

.github/workflows/test-xmake.yml

@@ -1,42 +0,0 @@
-name: xmake
-
-on:
-  workflow_call:
-
-jobs:
-  build:
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [windows-2025, ubuntu-24.04, macos-15]
-        build_type: [debug, releasedbg]
-        exclude:
-          - os: windows-2025
-            build_type: debug
-    runs-on: ${{ matrix.os }}
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Setup xmake
-        uses: xmake-io/github-action-setup-xmake@v1
-        with:
-          xmake-version: 3.0.5
-          actions-cache-folder: ".xmake-cache"
-          actions-cache-key: ${{ matrix.os }}
-          package-cache: true
-          package-cache-key: ${{ matrix.os }}-pixi
-          build-cache: true
-          build-cache-key: ${{ matrix.os }}-${{ matrix.build_type }}
-
-      - uses: ./.github/actions/setup-pixi
-
-      - name: Build
-        run: pixi run xmake ${{ matrix.build_type }}
-
-      - name: Test
-        run: pixi run xmake-test
-
-      - name: Remove llvm package (Linux)
-        if: runner.os == 'Linux'
-        run: xmake require --uninstall clice-llvm

.gitignore

@@ -35,7 +35,7 @@
 *build*/
 temp/
 .cache/
-.xmake/
+
 .llvm*/
 .clice/
 compile_commands.json
@@ -56,10 +56,11 @@ __pycache__/
 tests/unit/Local/
 
 # IDEs & Editors
-/.vscode/
+/.vscode/*
+!/.vscode/launch.json
+!/.vscode/tasks.json
 .vs/
 .idea/
-.claude
 .clangd
 
 # pixi environments
@@ -68,5 +69,7 @@ tests/unit/Local/
 !.pixi/config.toml
 
 .codex/
-.claude/
-openspec/
+.claude/*
+!.claude/CLAUDE.md
+!.claude/commands/
+openspec/

.vscode/launch.json

@@ -0,0 +1,83 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug clice",
+      "program": "${workspaceFolder}/build/Debug/bin/clice",
+      "args": ["--mode=socket", "--port=50051"],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug clice (socket, RelWithDebInfo)",
+      "program": "${workspaceFolder}/build/RelWithDebInfo/bin/clice",
+      "args": ["--mode=socket", "--port=50051"],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "name": "VSCode Extension (pipe)",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": [
+        "--disable-extension=llvm-vs-code-extensions.vscode-clangd",
+        "--disable-extension=ms-vscode.cpptools",
+        "--disable-extension=ms-vscode.cpptools-extension-pack",
+        "--extensionDevelopmentPath=${workspaceFolder}/editors/vscode"
+      ],
+      "env": {
+        "CLICE_MODE": "pipe"
+      },
+      "outFiles": ["${workspaceFolder}/editors/vscode/dist/**/*.js"],
+      "preLaunchTask": "npm: watch vscode ext"
+    },
+    {
+      "name": "VSCode Extension (socket)",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": [
+        "--disable-extension=llvm-vs-code-extensions.vscode-clangd",
+        "--disable-extension=ms-vscode.cpptools",
+        "--disable-extension=ms-vscode.cpptools-extension-pack",
+        "--extensionDevelopmentPath=${workspaceFolder}/editors/vscode"
+      ],
+      "env": {
+        "CLICE_MODE": "socket"
+      },
+      "outFiles": ["${workspaceFolder}/editors/vscode/dist/**/*.js"],
+      "preLaunchTask": "npm: watch vscode ext"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Unit Test",
+      "program": "${workspaceFolder}/build/Debug/bin/unit_tests",
+      "args": ["--test-dir=./tests/data", "--test-filter=${input:filter}"],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Release Unit Test",
+      "program": "${workspaceFolder}/build/RelWithDebInfo/bin/unit_tests",
+      "args": ["--test-dir=./tests/data", "--test-filter=${input:filter}"],
+      "cwd": "${workspaceFolder}"
+    }
+  ],
+  "compounds": [
+    {
+      "name": "clice + VSCode Extension (socket)",
+      "configurations": ["Debug clice", "VSCode Extension (socket)"],
+      "stopAll": true
+    }
+  ],
+  "inputs": [
+    {
+      "id": "filter",
+      "type": "promptString",
+      "description": "Unit Test Filter"
+    }
+  ]
+}

.vscode/tasks.json

@@ -0,0 +1,42 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "npm: install vscode deps",
+      "type": "shell",
+      "command": "pnpm",
+      "args": ["install"],
+      "options": {
+        "cwd": "${workspaceFolder}/editors/vscode"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "npm: watch vscode ext",
+      "type": "shell",
+      "command": "pnpm",
+      "args": ["run", "watch"],
+      "options": {
+        "cwd": "${workspaceFolder}/editors/vscode"
+      },
+      "dependsOn": "npm: install vscode deps",
+      "problemMatcher": "$ts-webpack-watch",
+      "isBackground": true,
+      "presentation": {
+        "reveal": "never",
+        "group": "watchers"
+      }
+    },
+    {
+      "label": "npm: package vscode ext",
+      "type": "shell",
+      "command": "pnpm",
+      "args": ["run", "package"],
+      "options": {
+        "cwd": "${workspaceFolder}/editors/vscode"
+      },
+      "dependsOn": "npm: install vscode deps",
+      "problemMatcher": []
+    }
+  ]
+}

CMakeLists.txt

@@ -127,9 +127,16 @@ endif()
 set(FBS_SCHEMA_FILE "${PROJECT_SOURCE_DIR}/src/index/schema.fbs")
 set(GENERATED_HEADER "${PROJECT_BINARY_DIR}/generated/schema_generated.h")
 
+if(CMAKE_CROSSCOMPILING)
+    find_program(FLATC_EXECUTABLE flatc REQUIRED)
+    set(FLATC_CMD "${FLATC_EXECUTABLE}")
+else()
+    set(FLATC_CMD "$<TARGET_FILE:flatc>")
+endif()
+
 add_custom_command(
     OUTPUT "${GENERATED_HEADER}"
-    COMMAND $<TARGET_FILE:flatc> --cpp -o "${PROJECT_BINARY_DIR}/generated" "${FBS_SCHEMA_FILE}"
+    COMMAND ${FLATC_CMD} --cpp -o "${PROJECT_BINARY_DIR}/generated" "${FBS_SCHEMA_FILE}"
     DEPENDS "${FBS_SCHEMA_FILE}"
     COMMENT "Generating C++ header from ${FBS_SCHEMA_FILE}"
 )
@@ -151,13 +158,13 @@ target_link_libraries(clice-core PUBLIC
     spdlog::spdlog
     roaring::roaring
     flatbuffers
-    eventide::ipc::lsp
-    eventide::serde::toml
+    kota::ipc::lsp
+    kota::codec::toml
     simdjson::simdjson
 )
 
 add_executable(clice "${PROJECT_SOURCE_DIR}/src/clice.cc")
-target_link_libraries(clice PRIVATE clice::core eventide::deco)
+target_link_libraries(clice PRIVATE clice::core kota::deco)
 install(TARGETS clice RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
 
 add_custom_target(copy_clang_resource ALL
@@ -189,7 +196,7 @@ if(CLICE_ENABLE_TEST)
         "${PROJECT_SOURCE_DIR}/src"
         "${PROJECT_SOURCE_DIR}/tests/unit"
     )
-    target_link_libraries(unit_tests PRIVATE clice::core eventide::zest eventide::deco)
+    target_link_libraries(unit_tests PRIVATE clice::core kota::zest kota::deco)
 endif()
 
 if(CLICE_ENABLE_BENCHMARK)
@@ -199,7 +206,7 @@ if(CLICE_ENABLE_BENCHMARK)
     target_include_directories(scan_benchmark PRIVATE
         "${PROJECT_SOURCE_DIR}/src"
     )
-    target_link_libraries(scan_benchmark PRIVATE clice::core eventide::deco)
+    target_link_libraries(scan_benchmark PRIVATE clice::core kota::deco)
 endif()
 
 if(CLICE_RELEASE)

benchmarks/scan_benchmark.cpp

@@ -21,17 +21,15 @@
 #include <thread>
 
 #include "command/command.h"
-#include "eventide/deco/deco.h"
-#include "eventide/serde/json/serializer.h"
 #include "support/filesystem.h"
 #include "support/logging.h"
 #include "support/path_pool.h"
 #include "syntax/dependency_graph.h"
 
+#include "kota/codec/json/json.h"
+#include "kota/deco/deco.h"
 #include "llvm/Support/FileSystem.h"
 
-namespace et = eventide;
-
 using namespace clice;
 
 struct BenchmarkOptions {
@@ -97,7 +95,7 @@ void export_graph_json(const PathPool& path_pool,
         export_data.files.push_back(std::move(node));
     }
 
-    auto json = et::serde::json::to_json(export_data);
+    auto json = kota::codec::json::to_json(export_data);
     if(!json) {
         std::println(stderr, "Failed to serialize dependency graph");
         return;
@@ -221,8 +219,8 @@ void print_report(const ScanReport& report) {
 }
 
 int main(int argc, const char** argv) {
-    auto args = deco::util::argvify(argc, argv);
-    auto result = deco::cli::parse<BenchmarkOptions>(args);
+    auto args = kota::deco::util::argvify(argc, argv);
+    auto result = kota::deco::cli::parse<BenchmarkOptions>(args);
 
     if(!result.has_value()) {
         std::println(stderr, "Error: {}", result.error().message);
@@ -233,7 +231,7 @@ int main(int argc, const char** argv) {
 
     if(opts.help.value_or(false) || !opts.cdb_path.has_value()) {
         std::ostringstream oss;
-        deco::cli::write_usage_for<BenchmarkOptions>(oss, "scan_benchmark [OPTIONS] <cdb>");
+        kota::deco::cli::write_usage_for<BenchmarkOptions>(oss, "scan_benchmark [OPTIONS] <cdb>");
         std::print("{}", oss.str());
         return opts.help.value_or(false) ? 0 : 1;
     }

cmake/llvm.cmake

@@ -25,6 +25,22 @@ function(setup_llvm LLVM_VERSION)
         list(APPEND LLVM_SETUP_ARGS "--offline")
     endif()
 
+    if(DEFINED CLICE_TARGET_TRIPLE)
+        if(CLICE_TARGET_TRIPLE MATCHES "linux")
+            list(APPEND LLVM_SETUP_ARGS "--target-platform" "Linux")
+        elseif(CLICE_TARGET_TRIPLE MATCHES "darwin")
+            list(APPEND LLVM_SETUP_ARGS "--target-platform" "macosx")
+        elseif(CLICE_TARGET_TRIPLE MATCHES "windows")
+            list(APPEND LLVM_SETUP_ARGS "--target-platform" "Windows")
+        endif()
+
+        if(CLICE_TARGET_TRIPLE MATCHES "^aarch64")
+            list(APPEND LLVM_SETUP_ARGS "--target-arch" "arm64")
+        elseif(CLICE_TARGET_TRIPLE MATCHES "^x86_64")
+            list(APPEND LLVM_SETUP_ARGS "--target-arch" "x64")
+        endif()
+    endif()
+
     execute_process(
         COMMAND "${Python3_EXECUTABLE}" "${LLVM_SETUP_SCRIPT}" ${LLVM_SETUP_ARGS}
         RESULT_VARIABLE LLVM_SETUP_RESULT
@@ -101,8 +117,15 @@ function(setup_llvm LLVM_VERSION)
             clangToolingSyntax
         )
     else()
-        file(GLOB LLVM_LIBRARIES CONFIGURE_DEPENDS "${LLVM_INSTALL_PATH}/lib/*${CMAKE_STATIC_LIBRARY_SUFFIX}")
-        target_link_libraries(llvm-libs INTERFACE ${LLVM_LIBRARIES})
+        file(GLOB LLVM_LIBRARIES CONFIGURE_DEPENDS "${LLVM_INSTALL_PATH}/lib/${CMAKE_STATIC_LIBRARY_PREFIX}LLVM[a-zA-Z]*${CMAKE_STATIC_LIBRARY_SUFFIX}")
+        file(GLOB CLANG_LIBRARIES CONFIGURE_DEPENDS "${LLVM_INSTALL_PATH}/lib/${CMAKE_STATIC_LIBRARY_PREFIX}clang[a-zA-Z]*${CMAKE_STATIC_LIBRARY_SUFFIX}")
+        # TODO: find a better way to find out whether zlib and zstd are needed
+        # Currently link if present in the LLVM lib directory
+        file(GLOB OTHER_REQUIRED_LIBS CONFIGURE_DEPENDS
+            "${LLVM_INSTALL_PATH}/lib/${CMAKE_STATIC_LIBRARY_PREFIX}z${CMAKE_STATIC_LIBRARY_SUFFIX}"
+            "${LLVM_INSTALL_PATH}/lib/${CMAKE_STATIC_LIBRARY_PREFIX}zstd${CMAKE_STATIC_LIBRARY_SUFFIX}"
+        )
+        target_link_libraries(llvm-libs INTERFACE ${LLVM_LIBRARIES} ${CLANG_LIBRARIES} ${OTHER_REQUIRED_LIBS})
         target_compile_definitions(llvm-libs INTERFACE CLANG_BUILD_STATIC=1)
     endif()
 endfunction()

cmake/package.cmake

@@ -1,7 +1,7 @@
 include_guard()
 
 include(${CMAKE_CURRENT_LIST_DIR}/llvm.cmake)
-setup_llvm("21.1.4+r1")
+setup_llvm("21.1.8")
 
 # install dependencies
 include(FetchContent)
@@ -39,18 +39,17 @@ set(FLATBUFFERS_BUILD_TESTS OFF CACHE BOOL "" FORCE)
 set(FLATBUFFERS_BUILD_FLATHASH OFF CACHE BOOL "" FORCE)
 
 FetchContent_Declare(
-    eventide
-    GIT_REPOSITORY https://github.com/clice-io/eventide
-    GIT_TAG main
-    GIT_SHALLOW TRUE
+    kotatsu
+    GIT_REPOSITORY https://github.com/clice-io/kotatsu
+    GIT_TAG e024f3b427a554502c4aa015952800a03ca4384b
 )
 
-set(ETD_ENABLE_ZEST ON)
-set(ETD_ENABLE_TEST OFF)
-set(ETD_SERDE_ENABLE_SIMDJSON ON)
-set(ETD_SERDE_ENABLE_YYJSON ON)
-set(ETD_SERDE_ENABLE_TOML ON)
-set(ETD_ENABLE_EXCEPTIONS OFF)
-set(ETD_ENABLE_RTTI OFF)
+set(KOTA_ENABLE_ZEST ON)
+set(KOTA_ENABLE_TEST OFF)
+set(KOTA_CODEC_ENABLE_SIMDJSON ON)
+set(KOTA_CODEC_ENABLE_YYJSON ON)
+set(KOTA_CODEC_ENABLE_TOML ON)
+set(KOTA_ENABLE_EXCEPTIONS OFF)
+set(KOTA_ENABLE_RTTI OFF)
 
-FetchContent_MakeAvailable(eventide spdlog croaring flatbuffers)
+FetchContent_MakeAvailable(kotatsu spdlog croaring flatbuffers)

cmake/toolchain.cmake

@@ -1,5 +1,29 @@
 cmake_minimum_required(VERSION 3.30)
 
+# Cross-compilation support via CLICE_TARGET_TRIPLE.
+# Examples:
+#   -DCLICE_TARGET_TRIPLE=x86_64-apple-darwin      (macOS x64 from arm64)
+#   -DCLICE_TARGET_TRIPLE=aarch64-linux-gnu         (Linux arm64 from x64)
+#   -DCLICE_TARGET_TRIPLE=aarch64-pc-windows-msvc   (Windows arm64 from x64)
+if(DEFINED CLICE_TARGET_TRIPLE)
+    if(CLICE_TARGET_TRIPLE MATCHES "^x86_64-apple-darwin")
+        set(CMAKE_OSX_ARCHITECTURES "x86_64" CACHE STRING "")
+    elseif(CLICE_TARGET_TRIPLE MATCHES "^aarch64-.*linux")
+        set(CMAKE_SYSTEM_NAME Linux)
+        set(CMAKE_SYSTEM_PROCESSOR aarch64)
+        set(CMAKE_C_COMPILER_TARGET "aarch64-linux-gnu" CACHE STRING "")
+        set(CMAKE_CXX_COMPILER_TARGET "aarch64-linux-gnu" CACHE STRING "")
+        if(DEFINED ENV{CONDA_PREFIX} AND NOT DEFINED CMAKE_SYSROOT)
+            set(CMAKE_SYSROOT "$ENV{CONDA_PREFIX}/aarch64-conda-linux-gnu/sysroot" CACHE PATH "")
+        endif()
+    elseif(CLICE_TARGET_TRIPLE MATCHES "^aarch64-.*-windows")
+        set(CMAKE_SYSTEM_NAME Windows)
+        set(CMAKE_SYSTEM_PROCESSOR ARM64)
+        set(CMAKE_C_COMPILER_TARGET "aarch64-pc-windows-msvc" CACHE STRING "")
+        set(CMAKE_CXX_COMPILER_TARGET "aarch64-pc-windows-msvc" CACHE STRING "")
+    endif()
+endif()
+
 set(CMAKE_C_COMPILER clang CACHE STRING "")
 set(CMAKE_CXX_COMPILER clang++ CACHE STRING "")
 

config/llvm-manifest.json

@@ -1,83 +1,142 @@
 [
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
+    "filename": "aarch64-linux-gnu-releasedbg-lto.tar.xz",
+    "sha256": "f3444ee840b50933c23656cbee7c4d010e752ac55ca66095b97f7c0e997b13b5",
+    "lto": true,
+    "asan": false,
+    "platform": "linux",
+    "arch": "arm64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
+    "filename": "aarch64-linux-gnu-releasedbg.tar.xz",
+    "sha256": "b9012bf059e4d8673fb564b5780e5fc78c6a2e47f5cc6a39f444d1879b42dd2a",
+    "lto": false,
+    "asan": false,
+    "platform": "linux",
+    "arch": "arm64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
+    "filename": "aarch64-windows-msvc-releasedbg-lto.tar.xz",
+    "sha256": "8870d16141ba7f9ea12f5147b8d91329abbbaa4376cd4576667dd323d896dd08",
+    "lto": true,
+    "asan": false,
+    "platform": "windows",
+    "arch": "arm64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
+    "filename": "aarch64-windows-msvc-releasedbg.tar.xz",
+    "sha256": "ad394e79ec85dd40f942671bb0342ffe54a103eb2baabacb773999d57d80134b",
+    "lto": false,
+    "asan": false,
+    "platform": "windows",
+    "arch": "arm64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
     "filename": "arm64-macos-clang-debug-asan.tar.xz",
-    "sha256": "7da4b7d63edefecaf11773e7e701c575140d1a07329bbbb038673b6ee4516ff5",
+    "sha256": "b02d20e4f7294ee33f49a09dfdd765b3b44135e003ef50e3a760aeee39e3f993",
     "lto": false,
     "asan": true,
     "platform": "macosx",
+    "arch": "arm64",
     "build_type": "Debug"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "arm64-macos-clang-releasedbg-lto.tar.xz",
-    "sha256": "300455b169448f9f01ae95e3bc269f489558a4ca3955e3032171cc75feca0e30",
+    "sha256": "e40c21eb0d0b91d9d4ab31212a5cb01ea46707f5c29839414567857e4147604d",
     "lto": true,
     "asan": false,
     "platform": "macosx",
+    "arch": "arm64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "arm64-macos-clang-releasedbg.tar.xz",
-    "sha256": "9abfc6cd65b957d734ffb97610a634fb4a66d3fbe0fcfb5a1c9124ef693c1495",
+    "sha256": "e1b01de34f0edfd41c118e4981a93afb35556ae369597e864f4a393db623b926",
     "lto": false,
     "asan": false,
     "platform": "macosx",
+    "arch": "arm64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "x64-linux-gnu-debug-asan.tar.xz",
-    "sha256": "c1ad3ec476911596a842ac67dd9c9c9475ce9f0a77b81101d3c801840292e7bc",
+    "sha256": "76bb82d822b5377fb5e0fac8abcfba125142e6a0acc02bb36d1fa1532a268646",
     "lto": false,
     "asan": true,
     "platform": "linux",
+    "arch": "x64",
     "build_type": "Debug"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "x64-linux-gnu-releasedbg-lto.tar.xz",
-    "sha256": "8a869c2184d139dbba704e2d712e7a68336458ad2d70622b3eb906c3e3511e54",
+    "sha256": "32f5edddec1e689124f045b586fb402ae30febc05203af7391b088bc8494cd53",
     "lto": true,
     "asan": false,
     "platform": "linux",
+    "arch": "x64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "x64-linux-gnu-releasedbg.tar.xz",
-    "sha256": "552bab86f715d4f2c027f07eaaf5b3d6b8e430af0b74b470142f3f00da4feec6",
+    "sha256": "8ba3c84f23a2a81a86c54780754a61adf99048aa2ac0dc9b9708d0f842d553de",
     "lto": false,
     "asan": false,
     "platform": "linux",
+    "arch": "x64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
-    "filename": "x64-windows-msvc-debug-asan.tar.xz",
-    "sha256": "093667a493d336c22ff3c604c5f1fea2a7d2c927c1179cec44e9a03726906ac1",
-    "lto": false,
-    "asan": true,
-    "platform": "windows",
-    "build_type": "Debug"
+    "version": "21.1.8",
+    "filename": "x64-macos-clang-releasedbg-lto.tar.xz",
+    "sha256": "97e81d6296896d7237f118f728d05291707b9e4e5791e07ce4be8aee0517505d",
+    "lto": true,
+    "asan": false,
+    "platform": "macosx",
+    "arch": "x64",
+    "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
+    "filename": "x64-macos-clang-releasedbg.tar.xz",
+    "sha256": "53c13f8e1082fa2fe2f9c05303de48cb3133bf5f24271f4b3062f1dec578159c",
+    "lto": false,
+    "asan": false,
+    "platform": "macosx",
+    "arch": "x64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
     "filename": "x64-windows-msvc-releasedbg-lto.tar.xz",
-    "sha256": "010539e85621dc3c6ecf359d899feb4075aeca5d0bba6625cdbec0e570e79129",
+    "sha256": "16bcf0e4cbc3d2b1204edd619a3837004dacea28eeff0a101c8d0212f936427d",
     "lto": true,
     "asan": false,
     "platform": "windows",
+    "arch": "x64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "x64-windows-msvc-releasedbg.tar.xz",
-    "sha256": "f473c09fbea10053fac00be409d75dc228d4a38bcbc5e4aeb58b56a4b0dde78e",
+    "sha256": "81d31fad05e200726c8178314b0b2045c947483dddd8cb974f4c376ae5f441fa",
     "lto": false,
     "asan": false,
     "platform": "windows",
+    "arch": "x64",
     "build_type": "RelWithDebInfo"
   }
 ]

docs/clice.toml

@@ -20,7 +20,7 @@ max_active_file = 8
 cache_dir = "${workspace}/.clice/cache"
 # Directory for storing index files.
 index_dir = "${workspace}/.clice/index"
-logging_dir = "${workspace}/.clice/logging"
+logging_dir = "${workspace}/.clice/logs"
 # Compile commands files or directories to search for compile_commands.json files.
 compile_commands_paths = ["${workspace}/build"]
 

docs/en/architecture.md

@@ -91,7 +91,7 @@ The worker pool (`src/server/worker_pool.cpp`) manages spawning and communicatin
 
 ### Communication
 
-Workers communicate with the master via **stdio pipes** using a **bincode** serialization format (via `eventide::ipc::BincodePeer`). This is more compact and faster than JSON for internal IPC, while the master handles JSON for the external LSP protocol.
+Workers communicate with the master via **stdio pipes** using a **bincode** serialization format (via `kota::ipc::BincodePeer`). This is more compact and faster than JSON for internal IPC, while the master handles JSON for the external LSP protocol.
 
 ### Stateful Worker Routing
 
@@ -111,7 +111,7 @@ The stateful worker (`src/server/stateful_worker.cpp`) caches compiled ASTs in m
 - **Feature queries**: Look up the cached AST and invoke the corresponding `feature::*` function (hover, semantic tokens, etc.), serializing the result to JSON
 - **Document updates**: Received as notifications — the worker updates the stored text and marks the document as `dirty`, causing feature queries to return `null` until recompilation
 - **Eviction**: LRU-based; evicts the oldest document when capacity is exceeded, notifying the master
-- **Concurrency**: Each document has a per-document `et::mutex` (strand) to serialize compilation and feature queries. Heavy work (compilation, feature extraction) runs on a thread pool via `et::queue`.
+- **Concurrency**: Each document has a per-document `kota::mutex` (strand) to serialize compilation and feature queries. Heavy work (compilation, feature extraction) runs on a thread pool via `kota::queue`.
 
 ## Stateless Worker
 
@@ -123,7 +123,7 @@ The stateless worker (`src/server/stateless_worker.cpp`) handles one-shot reques
 - **Build PCM**: Compiles a C++20 module interface to a temporary file
 - **Index**: Compiles a file for indexing (TUIndex generation — currently a stub)
 
-All requests are dispatched to a thread pool via `et::queue`.
+All requests are dispatched to a thread pool via `kota::queue`.
 
 ## Compile Graph
 
@@ -132,7 +132,7 @@ The compile graph (`src/server/compile_graph.cpp`) tracks compilation unit depen
 - **Registration**: Each file registers its included dependencies
 - **Cascade invalidation**: When a file changes, all transitive dependents are marked dirty and their ongoing compilations are cancelled
 - **Dependency compilation**: Before compiling a file, `compile_deps` ensures all dependencies (PCH, PCMs) are built first
-- **Cancellation**: Uses `et::cancellation_source` to abort in-flight compilations when files are invalidated
+- **Cancellation**: Uses `kota::cancellation_source` to abort in-flight compilations when files are invalidated
 
 ## Configuration
 
@@ -153,7 +153,7 @@ String values support `${workspace}` substitution.
 
 ## IPC Protocol
 
-The master and workers communicate using custom RPC messages defined in `src/server/protocol.h`. Each message type has a `RequestTraits` or `NotificationTraits` specialization that defines the method name and result type.
+The master and workers communicate using custom RPC messages defined in `src/server/protocol/`. Each message type has a `RequestTraits` or `NotificationTraits` specialization that defines the method name and result type.
 
 ### Stateful Worker Messages
 

docs/en/dev/build.md

@@ -32,18 +32,6 @@ pixi run integration-test Debug
 > [!TIP]
 > If you want to develop directly with `cmake`, `ninja`, `clang++`, etc., run `pixi shell` to enter a shell with all env vars configured.
 
-### XMake
-
-We also support building with XMake:
-
-```shell
-# config & build (default releasedbg)
-pixi run xmake
-
-# unit & integration
-pixi run xmake-test
-```
-
 ## Manual Build
 
 If you plan to build manually, first ensure your toolchain matches the versions defined in `pixi.toml`.
@@ -70,30 +58,13 @@ Optional build options:
 | CLICE_USE_LIBCXX     | OFF     | Build clice with libc++ (adds `-std=libc++`); if enabled, ensure the LLVM libs are also built with libc++ |
 | CLICE_CI_ENVIRONMENT | OFF     | Enable the `CLICE_CI_ENVIRONMENT` macro; some tests only run in CI                                        |
 
-### XMake
-
-Build clice with:
-
-```bash
-xmake f -c --mode=releasedbg --toolchain=clang
-xmake build --all
-```
-
-Optional build options:
-
-| Option        | Default | Effect                                   |
-| ------------- | ------- | ---------------------------------------- |
-| --llvm        | ""      | Build clice with LLVM from a custom path |
-| --enable_test | false   | Build clice unit tests                   |
-| --ci          | false   | Enable `CLICE_CI_ENVIRONMENT`            |
-
 ## About LLVM
 
 clice calls Clang APIs to parse C++ code, so it must link against LLVM/Clang. Because clice uses Clang's private headers (usually absent from distro packages), the system LLVM package cannot be used directly.
 
 Two ways to satisfy this dependency:
 
-1. We publish prebuilt binaries of the LLVM version we use at [clice-llvm](https://github.com/clice-io/clice-llvm/releases) for CI and release builds. During builds, cmake and xmake download these LLVM libs by default.
+1. We publish prebuilt binaries of the LLVM version we use at [clice-llvm](https://github.com/clice-io/clice-llvm/releases) for CI and release builds. During builds, cmake downloads these LLVM libs by default.
 
 > [!IMPORTANT]
 >

docs/en/dev/test-and-debug.md

@@ -18,13 +18,6 @@ We use pytest to run integration tests. Please refer to `pyproject.toml` to inst
 $ pytest -s --log-cli-level=INFO tests/integration --executable=./build/bin/clice
 ```
 
-If you use xmake as your build system, you can run the tests directly with xmake:
-
-```shell
-$ xmake run --verbose unit_tests
-$ xmake test --verbose integration_tests/default
-```
-
 ## Debug
 
 If you want to attach a debugger to clice for debugging, it is recommended to first start clice in socket mode independently, and then connect the client to it.

docs/en/guide/quick-start.md

@@ -54,14 +54,73 @@ bazel run @hedron_compile_commands//:refresh_all
 
 ### Visual Studio
 
-TODO:
+Visual Studio (2019 16.1+) can generate a compilation database via CMake integration. Open your project as a CMake project, then configure the generation in `CMakeSettings.json`:
+
+```json
+{
+  "configurations": [
+    {
+      "name": "x64-Debug",
+      "generator": "Ninja",
+      "buildRoot": "${projectDir}\\build",
+      "cmakeCommandArgs": "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON"
+    }
+  ]
+}
+```
+
+Alternatively, for MSBuild-based projects (`.vcxproj`), you can use [compiledb-vs](https://github.com/pjbroad/compiledb-vs) or [catter](https://github.com/clice-io/catter) to generate the compilation database.
 
 ### Makefile
 
-TODO:
+For Makefile-based projects, use [bear](https://github.com/rizsotto/Bear) to intercept compilation commands:
+
+```bash
+bear -- make
+```
+
+This will generate a `compile_commands.json` in the current directory. Note that `bear` requires a clean build to capture all commands — run `make clean` before `bear -- make` if needed.
+
+Alternatively, if you use GNU Make, you can use [compiledb](https://github.com/nicktimko/compiledb):
+
+```bash
+compiledb make
+```
+
+### Meson
+
+Meson generates a compilation database automatically during setup:
+
+```bash
+meson setup build
+```
+
+The `compile_commands.json` will be in the `build` directory.
 
 ### Xmake
 
+Use one of the following approaches to generate a compilation database.
+
+#### Command Line
+
+Run the following command to manually generate a compilation database:
+
+```bash
+xmake project -k compile_commands --lsp=clangd build
+```
+
+> Compilation database generated manually doesn't automatically update itself. Re-generate if changes are made to the project.
+
+#### VSCode Extension
+
+The Xmake official VSCode extension automatically generates the compilation database when `xmake.lua` is updated. However, it generates the database to the `.vscode` directory by default. Add this setting in `settings.json`:
+
+```json
+"xmake.compileCommandsDirectory": "build"
+```
+
+to explicitly ask the extension to generate the compilation database in `build`.
+
 ### Others
 
-For any other build system, you can try using [bear](https://github.com/rizsotto/Bear) or [scan-build](https://github.com/rizsotto/scan-build) to intercept compilation commands and obtain the compilation database (no guarantee of success). We plan to write a **new tool** in the future that captures compilation commands through a fake compiler approach.
+For any other build system, you can use [catter](https://github.com/clice-io/catter) to generate a compilation database. It captures compilation commands through a fake compiler approach and is designed to work reliably with any build system that invokes a compiler executable.

docs/zh/dev/build.md

@@ -32,18 +32,6 @@ pixi run integration-test Debug
 > [!TIP]
 > 如果你想直接使用 `cmake`, `ninja`, `clang++` 等命令进行开发，请运行 `pixi shell` 进入已配置好环境变量的终端
 
-### XMake
-
-我们同样支持使用 XMake 构建：
-
-```shell
-# config & build (default releasedbg)
-pixi run xmake
-
-# unit & integration
-pixi run xmake-test
-```
-
 ## Manual Build
 
 如果你打算手动构建，请务必先确认你的工具链满足 pixi.toml 中定义的版本要求。
@@ -70,30 +58,13 @@ cmake -B build -G Ninja \
 | CLICE_USE_LIBCXX     | OFF    | 是否使用 libc++ 来构建 clice（添加 `-std=libc++`），如果开启，请确保 LLVM 库也是使用 libc++ 编译的 |
 | CLICE_CI_ENVIRONMENT | OFF    | 是否打开 `CLICE_CI_ENVIRONMENT` 这个宏，有些测试在 CI 环境才会执行                                 |
 
-### XMake
-
-使用如下命令即可构建 clice：
-
-```bash
-xmake f -c --mode=releasedbg --toolchain=clang
-xmake build --all
-```
-
-可选的构建选项：
-
-| 选项          | 默认值 | 效果                                 |
-| ------------- | ------ | ------------------------------------ |
-| --llvm        | ""     | 使用自定义路径的 LLVM 库来构建 clice |
-| --enable_test | false  | 是否构建 clice 的单元测试            |
-| --ci          | false  | 是否打开 `CLICE_CI_ENVIRONMENT`      |
-
 ## About LLVM
 
 clice 调用 Clang API 来解析 C++ 代码，因此必须链接 LLVM/Clang 库。由于 clice 使用了 Clang 的私有头文件（这些文件通常不包含在发行版中），不能直接使用系统安装的 LLVM 包。
 
 主要有两种方式解决这个依赖问题：
 
-1. 我们在 [clice-llvm](https://github.com/clice-io/clice-llvm/releases) 上会发布使用的 LLVM 版本的预编译二进制，用于 CI 或者 release 构建。在构建时 cmake 和 xmake 默认会从此处下载 LLVM 库然后使用。
+1. 我们在 [clice-llvm](https://github.com/clice-io/clice-llvm/releases) 上会发布使用的 LLVM 版本的预编译二进制，用于 CI 或者 release 构建。在构建时 cmake 默认会从此处下载 LLVM 库然后使用。
 
 > [!IMPORTANT]
 >

docs/zh/dev/extension.md

@@ -30,7 +30,7 @@ pixi run publish-vscode
 
 1. `pixi shell -e node`
 2. 在 `editors/vscode` 下运行 `pnpm run watch`（增量构建）
-3. VSCode 中使用 “Run Extension/Launch Extension” 调试配置，或执行 `code --extensionDevelopmentPath=$(pwd)/editors/vscode`
+3. VSCode 中使用”Run Extension/Launch Extension”调试配置，或执行 `code --extensionDevelopmentPath=$(pwd)/editors/vscode`
 
 常用脚本（在 `pixi shell -e node` 下）：
 

docs/zh/dev/test-and-debug.md

@@ -18,13 +18,6 @@ $ ./build/bin/unit_tests --test-dir="./tests/data"
 $ pytest -s --log-cli-level=INFO tests/integration --executable=./build/bin/clice
 ```
 
-如果你使用 xmake 作为构建系统，可以直接通过 xmake 运行测试：
-
-```shell
-$ xmake run --verbose unit_tests
-$ xmake test --verbose integration_tests/default
-```
-
 ## Debug
 
 如果想在 clice 上附加调试器并进行调试，推荐先单独以 socket 模式启动 clice，然后再将客户端连接到 clice 上

docs/zh/guide/quick-start.md

@@ -54,14 +54,73 @@ bazel run @hedron_compile_commands//:refresh_all
 
 ### Visual Studio
 
-TODO:
+Visual Studio（2019 16.1+）可以通过 CMake 集成来生成编译数据库。将项目作为 CMake 项目打开，然后在 `CMakeSettings.json` 中配置：
+
+```json
+{
+  "configurations": [
+    {
+      "name": "x64-Debug",
+      "generator": "Ninja",
+      "buildRoot": "${projectDir}\\build",
+      "cmakeCommandArgs": "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON"
+    }
+  ]
+}
+```
+
+对于基于 MSBuild 的项目（`.vcxproj`），可以使用 [compiledb-vs](https://github.com/pjbroad/compiledb-vs) 或 [catter](https://github.com/clice-io/catter) 来生成编译数据库。
 
 ### Makefile
 
-TODO:
+对于基于 Makefile 的项目，使用 [bear](https://github.com/rizsotto/Bear) 来拦截编译命令：
+
+```bash
+bear -- make
+```
+
+这会在当前目录生成 `compile_commands.json`。注意 `bear` 需要干净的构建来捕获所有命令——如果需要的话，在运行 `bear -- make` 之前先执行 `make clean`。
+
+另外，如果使用 GNU Make，也可以使用 [compiledb](https://github.com/nicktimko/compiledb)：
+
+```bash
+compiledb make
+```
+
+### Meson
+
+Meson 在配置阶段会自动生成编译数据库：
+
+```bash
+meson setup build
+```
+
+`compile_commands.json` 会生成在 `build` 目录下。
 
 ### Xmake
 
+用下列任意方法生成编译数据库。
+
+#### 命令行手动生成
+
+在命令行中执行以下命令：
+
+```bash
+xmake project -k compile_commands --lsp=clangd build
+```
+
+> 通过这种方法生成的编译数据库无法自动更新，需要在项目编译配置更改时手动重新生成。
+
+#### VSCode 扩展
+
+Xmake 提供的官方 VSCode 扩展会在 `xmake.lua` 更新时自动生成编译数据库。然而默认情况下，它将编译数据库生成到了 `.vscode` 文件夹。在 `settings.json` 中添加以下配置：
+
+```json
+"xmake.compileCommandsDirectory": "build"
+```
+
+以将编译数据库的生成目录调整到 `build`，供 clice 使用。
+
 ### Others
 
-对于任意其它的构建系统，可以尝试使用 [bear](https://github.com/rizsotto/Bear) 或者 [scan-build](https://github.com/rizsotto/scan-build) 来拦截编译命令并获取到编译数据库（不保证成功）。我们计划在未来编写一个**新的工具**，通过假编译器的方式来实现编译命令的捕获。
+对于任意其它的构建系统，可以使用 [catter](https://github.com/clice-io/catter) 来生成编译数据库。它通过伪装编译器的方式来捕获编译命令，能够可靠地与任何调用编译器可执行文件的构建系统配合工作。

editors/vscode/.vscode/extensions.json

@@ -1,9 +0,0 @@
-{
-  // See http://go.microsoft.com/fwlink/?LinkId=827846
-  // for the documentation about the extensions.json format
-  "recommendations": [
-    "dbaeumer.vscode-eslint",
-    "amodio.tsl-problem-matcher",
-    "ms-vscode.extension-test-runner"
-  ]
-}

editors/vscode/.vscode/launch.json

@@ -1,23 +0,0 @@
-{
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "name": "Run Extension (socket)",
-      "type": "extensionHost",
-      "request": "launch",
-      "args": ["--disable-extensions", "--extensionDevelopmentPath=${workspaceFolder}"],
-      "env": { "CLICE_MODE": "socket" },
-      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
-      "preLaunchTask": "${defaultBuildTask}"
-    },
-    {
-      "name": "Run Extension (pipe)",
-      "type": "extensionHost",
-      "request": "launch",
-      "args": ["--disable-extensions", "--extensionDevelopmentPath=${workspaceFolder}"],
-      "env": { "CLICE_MODE": "pipe" },
-      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
-      "preLaunchTask": "${defaultBuildTask}"
-    }
-  ]
-}

editors/vscode/.vscode/settings.json

@@ -1,13 +0,0 @@
-// Place your settings in this file to overwrite default and user settings.
-{
-  "files.exclude": {
-    "out": false, // set this to true to hide the "out" folder with the compiled JS files
-    "dist": false // set this to true to hide the "dist" folder with the compiled JS files
-  },
-  "search.exclude": {
-    "out": true, // set this to false to include "out" folder in search results
-    "dist": true // set this to false to include "dist" folder in search results
-  },
-  // Turn off tsc task auto detection since we have the necessary tasks as npm scripts
-  "typescript.tsc.autoDetect": "off"
-}

editors/vscode/.vscode/tasks.json

@@ -1,37 +0,0 @@
-// See https://go.microsoft.com/fwlink/?LinkId=733558
-// for the documentation about the tasks.json format
-{
-  "version": "2.0.0",
-  "tasks": [
-    {
-      "type": "npm",
-      "script": "watch",
-      "problemMatcher": "$ts-webpack-watch",
-      "isBackground": true,
-      "presentation": {
-        "reveal": "never",
-        "group": "watchers"
-      },
-      "group": {
-        "kind": "build",
-        "isDefault": true
-      }
-    },
-    {
-      "type": "npm",
-      "script": "watch-tests",
-      "problemMatcher": "$tsc-watch",
-      "isBackground": true,
-      "presentation": {
-        "reveal": "never",
-        "group": "watchers"
-      },
-      "group": "build"
-    },
-    {
-      "label": "tasks: watch-tests",
-      "dependsOn": ["npm: watch", "npm: watch-tests"],
-      "problemMatcher": []
-    }
-  ]
-}

openspec/changes/assess-clice-production-readiness/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-04-03

openspec/changes/assess-clice-production-readiness/design.md

@@ -1,145 +0,0 @@
-## Context
-
-`clice` already has the rough shape of a language server: a master process, stateful/stateless workers, compile scheduling, module/PCH support, an emerging index, and a set of AST-backed editor features. The current gap is not "missing framework", but a mismatch between the current implementation shape and the invariants required for real editor use.
-
-The highest-risk issues are all cross-cutting:
-
-- opened editor buffers are not yet the consistently authoritative source across compile, AST queries, and index-backed navigation
-- stateful feature reads can race with rebuilds and stale generations
-- header files and multi-context files do not yet have a sound compilation-context selection model
-- several features are either missing, stubbed, or substantially shallower than `clangd`
-- worker ownership, eviction, diagnostics, logging, and background work scheduling are not yet production-grade
-
-This design therefore treats production readiness as four coordinated workstreams with explicit boundaries: document model, compilation context, AST-only feature baseline, and runtime hardening.
-
-## Goals / Non-Goals
-
-**Goals:**
-
-- make opened-buffer semantics explicit and enforceable across compile and query paths
-- define how `clice` selects and persists compilation contexts for sources and headers
-- set a concrete AST-only feature baseline that can be implemented independently from global index work
-- define runtime invariants for worker lifecycle, resource control, logging, and stale-result handling
-- produce a task breakdown that allows server/core work and feature work to proceed in parallel with minimal overlap
-
-**Non-Goals:**
-
-- full global-index parity with `clangd`
-- final implementation details for every indexed feature such as workspace-wide rename or workspace symbols
-- performance tuning beyond the invariants needed to avoid obviously wrong scheduling and stale results
-- introducing compatibility layers or temporary abstractions whose only purpose is to avoid refactoring existing wrong-shape code
-
-## Decisions
-
-### 1. Treat the opened document as the primary source of truth
-
-Open documents with unsaved changes must override disk content for compile and AST-backed queries. This applies to on-demand compiles, stateful feature reads, and the local side of navigation requests.
-
-Why this over disk-first fallback:
-
-- it matches editor expectations
-- it removes offset mismatches between the text used to compute positions and the AST used to answer them
-- it gives a single invariant that can be tested across hover, completion, semantic tokens, and local navigation
-
-Alternative considered:
-
-- continue using disk-backed index and best-effort stale tolerance
-  Rejected because it produces silently wrong answers in the most common editing flow.
-
-### 2. Gate AST-backed feature reads on a versioned build generation
-
-Every opened document needs a version/generation model that ties together text, build scheduling, worker state, AST readiness, diagnostics publication, and feature requests. AST-backed reads must either use a generation known to match the current document or fail/retry cleanly; they must not run on a stale or fatal unit by default.
-
-Why this over the current dirty-flag shape:
-
-- `dirty` alone records staleness but does not protect the read path
-- version/generation checks let master and worker reject stale compile completions and stale feature answers deterministically
-
-Alternative considered:
-
-- optimistic reads while a rebuild is in flight
-  Rejected because it preserves responsiveness at the cost of correctness and makes debugging behavior impossible.
-
-### 3. Separate compilation-context resolution from feature implementation
-
-Header context, compilation context, and multi-command source handling must be solved in the compile layer, not feature-by-feature. Feature handlers should receive a coherent AST/index view and not carry their own header fallback logic.
-
-Why this over ad hoc per-feature fallback:
-
-- it prevents each feature from inventing a different answer for the same file
-- it keeps AST-only feature work independently assignable
-- it matches the way `clangd` centralizes command transfer and TU scheduling
-
-Alternative considered:
-
-- keeping generic fallback compile commands for headers until later
-  Rejected because it creates misleading "working" behavior with the wrong language mode and include environment.
-
-### 4. Keep AST-only feature work independent from index work
-
-The feature baseline for this change covers capabilities that can work from the current AST or local parse context. Missing index-backed features may be tracked, but they are not on the critical path for this change.
-
-Why this split:
-
-- it allows server/core work to proceed without blocking feature contributors
-- it matches the current repository structure, where most AST features already live under `src/feature`
-- it gives a realistic route to internal dogfooding before full index maturity
-
-Alternative considered:
-
-- waiting for index parity before improving features
-  Rejected because it serializes unrelated work and delays useful editor quality improvements.
-
-### 5. Remove or finish wrong-shape/stub behavior instead of hiding it
-
-Capabilities that are currently advertised but stubbed, or data structures that exist without a correct runtime selection model, should either be finished or explicitly de-scoped. Production readiness must reduce misleading behavior, not preserve it.
-
-Why this over compatibility shims:
-
-- stubs make clients believe a feature exists when it does not
-- partial lifecycle plumbing causes leaks and stale ownership even if the server appears responsive
-- cleaning up wrong-shape code reduces the long-term cost of later index and context work
-
-Alternative considered:
-
-- preserve current surface and patch around it incrementally
-  Rejected because it accumulates technical debt exactly in the areas that most need stable invariants.
-
-### 6. Use one research document as the coordination artifact, then execute by small work packages
-
-This change produces a detailed markdown report under `temp/` that groups findings into server/core and feature workstreams, then translates them into small, independently assignable tasks. The report is not the contract itself; the specs are. The report exists to preserve comparison context and justify prioritization.
-
-Why this over burying all detail in tasks:
-
-- the comparison against local `clangd` sources is too detailed to keep only in task bullets
-- the report gives future implementation agents a single place to understand gaps and evidence
-
-## Risks / Trade-offs
-
-- [Stricter generation gating may temporarily increase null/error responses] -> Mitigation: prefer explicit stale-result rejection over silently wrong data, and add targeted tests for retry behavior.
-- [Header-context design can expand into full index work] -> Mitigation: keep this change focused on command/context selection and defer cross-project index heuristics that are not needed for production dogfooding.
-- [Feature parity work may accidentally duplicate already-completed behavior] -> Mitigation: each feature task must confirm current implementation state before coding, using the gap-analysis report and local source references.
-- [Cleaning up wrong-shape code may require deleting partially integrated paths] -> Mitigation: treat deletion as part of completion criteria rather than as optional follow-up.
-- [Parallel execution can produce merge conflicts around `master_server.cpp` and protocol definitions] -> Mitigation: split tasks by ownership boundary, with server/core work owning protocol and lifecycle changes, and feature work owning only their feature modules plus the minimal routing needed for exposure.
-
-## Migration Plan
-
-1. Land the planning artifacts and the gap-analysis document.
-2. Implement server/core invariants first where feature correctness depends on them:
-   open-buffer source of truth, generation-safe AST reads, header/context selection, lifecycle cleanup.
-3. In parallel, implement AST-only feature tasks that do not depend on index maturity.
-4. Remove or hide stubbed feature advertisements that remain incomplete.
-5. Expand test coverage around document lifecycle, stale-result rejection, header handling, and feature-level golden cases.
-6. Start internal dogfooding only after the server/core acceptance criteria and the minimum AST-only baseline are both satisfied.
-
-Rollback strategy:
-
-- because this change is primarily a planning and refactoring contract, rollback means disabling newly advertised features or reverting individual implementation tasks rather than reverting the entire capability set at once
-
-## Open Questions
-
-- How should `clice` choose among multiple valid compilation contexts for the same source file before the full index is mature?
-- For headers without a direct compile command, what ranking rule should choose the preferred includer or proxy translation unit?
-- Should AST-backed requests block until a matching generation is ready, or return an explicit retriable error after a short timeout?
-- Which AST-only code actions are mandatory for first internal rollout, and which can remain behind capability flags?
-- How should dynamic, unsaved-document symbol data be combined with disk-backed merged index results without reintroducing offset drift?

openspec/changes/assess-clice-production-readiness/proposal.md

@@ -1,32 +0,0 @@
-## Why
-
-`clice` has reached the stage where the core server loop starts, responds, and already exposes a meaningful set of AST-backed language features. However, it is not yet safe to treat the server as production-usable or even stable for internal dogfooding, because open-buffer semantics, compilation-context handling, stale AST/index reads, worker lifecycle, and several AST-only editor features still diverge from the behavior expected from a real C++ language server.
-
-The project also lacks a single implementation contract that separates core server/compiler work from independently assignable feature work. A focused production-readiness change is needed now so server refactoring, feature parity work, and documentation updates can proceed in parallel without mixing concerns.
-
-## What Changes
-
-- Define a production-readiness plan for `clice` that separates core server/compiler obligations from AST-only feature work.
-- Specify correct open-buffer versus on-disk behavior for compile, query, and navigation flows.
-- Specify compilation-context and header-context behavior required for headers and multi-context source files.
-- Specify the minimum AST-only feature baseline needed before internal rollout, including feature parity gaps against `clangd` where global index is not required.
-- Specify server hardening requirements for worker lifecycle, stale-result rejection, observability, resource control, and error handling.
-- Produce a detailed gap-analysis document under `./temp` that compares current `clice` behavior against local `clangd` sources and turns the findings into implementation workstreams.
-
-## Capabilities
-
-### New Capabilities
-- `buffer-aware-document-model`: Define the source-of-truth rules for opened documents, unsaved edits, build generations, and request consistency.
-- `compilation-context-management`: Define how `clice` chooses and applies compilation contexts for source files and headers, including header context and compilation context behavior.
-- `ast-feature-baseline`: Define the AST-only feature set and quality baseline required before production dogfooding, including missing or incomplete `clangd`-style features.
-- `server-production-hardening`: Define the runtime, worker, indexing, logging, and lifecycle guarantees required for reliable day-to-day use.
-
-### Modified Capabilities
-
-None.
-
-## Impact
-
-- Affected code spans `src/server`, `src/command`, `src/compile`, `src/index`, `src/feature`, and related tests under `tests/unit` and `tests/integration`.
-- The change establishes the implementation contract for upcoming refactors to document state, compile scheduling, header/context selection, worker ownership/eviction, and AST-only LSP handlers.
-- Documentation output will include OpenSpec artifacts under `openspec/changes/assess-clice-production-readiness/` and a detailed analysis document under `temp/`.

openspec/changes/assess-clice-production-readiness/specs/ast-feature-baseline/spec.md

@@ -1,44 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Production rollout includes a minimum AST-only feature baseline
-Before internal production dogfooding, `clice` SHALL provide a stable AST-only feature baseline consisting of hover, completion, signature help, document symbols, document links, folding ranges, semantic tokens, inlay hints, formatting, diagnostics, document highlight, selection range, and AST-backed code actions that do not require a global index.
-
-#### Scenario: Missing AST-only feature is visible in capability surface
-- **WHEN** an AST-only feature is not implemented to the agreed baseline
-- **THEN** `clice` does not advertise it as available
-
-#### Scenario: Implemented AST-only feature is routed end-to-end
-- **WHEN** an AST-only feature reaches the agreed baseline
-- **THEN** `clice` exposes it through LSP capability advertisement, request routing, and worker execution
-
-### Requirement: Hover provides semantic detail beyond symbol name
-Hover responses SHALL include semantic information that is useful for real editing, such as declaration spelling, type information, or associated documentation when available.
-
-#### Scenario: Hover on function shows semantic information
-- **WHEN** a user hovers a function or method symbol
-- **THEN** the hover response includes more than a bare symbol kind and name
-
-### Requirement: Completion and signature help expose actionable assistance
-Completion and signature-help responses SHALL provide parameter-aware assistance that is suitable for day-to-day editing, including snippets or argument guidance when enabled by server options.
-
-#### Scenario: Completion inserts parameter-aware text
-- **WHEN** snippet-style completion support is enabled and a callable symbol is completed
-- **THEN** the completion response includes parameter-aware insertion behavior
-
-#### Scenario: Signature help identifies active parameter
-- **WHEN** a user requests signature help inside a callable argument list
-- **THEN** the response identifies the active parameter for the current cursor position
-
-### Requirement: Inlay hint computation respects requested scope
-Inlay hints SHALL be computed for the requested document scope rather than always forcing a full-document computation.
-
-#### Scenario: Range request limits inlay hint computation
-- **WHEN** a client requests inlay hints for a document range
-- **THEN** `clice` computes and returns hints for that range instead of scanning the entire file
-
-### Requirement: AST-only code actions are either implemented or hidden
-If an AST-only code action is advertised by `clice`, it SHALL produce a meaningful result instead of an unconditional empty placeholder response.
-
-#### Scenario: Advertised code action is not a stub
-- **WHEN** a client requests code actions for a context where an advertised AST-only code action applies
-- **THEN** `clice` returns a meaningful action or omits the capability from advertisement

openspec/changes/assess-clice-production-readiness/specs/buffer-aware-document-model/spec.md

@@ -1,41 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Opened buffer content is authoritative
-When a document is opened in the editor, `clice` SHALL treat the opened buffer content as the source of truth for compile inputs and AST-backed queries until the document is closed.
-
-#### Scenario: Hover uses unsaved content
-- **WHEN** a user edits an opened file without saving and requests hover in that file
-- **THEN** `clice` uses the opened buffer content rather than the on-disk file content to answer the request
-
-#### Scenario: Completion uses unsaved content
-- **WHEN** a user edits an opened file without saving and requests completion in that file
-- **THEN** `clice` builds completion context from the opened buffer content rather than the on-disk file content
-
-### Requirement: AST-backed requests use a matching document generation
-`clice` SHALL answer AST-backed requests only from an AST generation that matches the current opened-document version, or otherwise reject/defer the request in a defined way.
-
-#### Scenario: Stale AST result is discarded
-- **WHEN** a rebuild completes for an older document version after a newer edit has already been accepted
-- **THEN** `clice` discards the stale AST result and does not publish it as the current answer state
-
-#### Scenario: Feature request does not read stale AST
-- **WHEN** a feature request arrives while the current document version has not yet produced a matching AST
-- **THEN** `clice` does not answer from an older AST generation
-
-### Requirement: Active-file navigation starts from live document state
-For an opened file, `clice` SHALL resolve the source-side symbol and position mapping for navigation requests from the current document state before using disk-backed index data for remote results.
-
-#### Scenario: Local definition lookup uses live offsets
-- **WHEN** a user makes unsaved edits that shift symbol offsets and requests definition from the opened file
-- **THEN** `clice` resolves the queried symbol from the current opened document state instead of interpreting the request against stale disk offsets
-
-### Requirement: Closing a document ends opened-buffer authority
-When an opened document is closed, `clice` SHALL stop treating the editor buffer as authoritative and SHALL release associated opened-document runtime state.
-
-#### Scenario: Closed document falls back to disk state
-- **WHEN** a document is closed and then queried again without reopening
-- **THEN** `clice` uses persisted project state rather than the former unsaved editor buffer
-
-#### Scenario: Close releases owned runtime state
-- **WHEN** a document is closed
-- **THEN** `clice` releases worker ownership and opened-document runtime state associated with that document

openspec/changes/assess-clice-production-readiness/specs/compilation-context-management/spec.md

@@ -1,41 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Header files use a real compilation context
-When a header file lacks a direct compile command, `clice` SHALL derive its compilation context from a valid project context rather than falling back to a generic language-default command.
-
-#### Scenario: Opened header borrows project context
-- **WHEN** a user opens a header that is included by one or more project translation units but has no direct compile command entry
-- **THEN** `clice` selects a valid project-derived compilation context for that header
-
-#### Scenario: No generic fallback for project header
-- **WHEN** a project header has at least one valid project-derived compilation context
-- **THEN** `clice` does not prefer a generic fallback command over the project-derived context
-
-### Requirement: Header context and compilation context remain distinct runtime concepts
-`clice` SHALL distinguish header-context behavior from source-file compilation-context behavior in its runtime model and queries.
-
-#### Scenario: Header query selects header context
-- **WHEN** a file is analyzed as a header included through a source file context
-- **THEN** `clice` uses header-context selection rules instead of treating the file as an ordinary standalone translation unit
-
-#### Scenario: Source query selects compilation context
-- **WHEN** a file is analyzed as a directly compiled source file
-- **THEN** `clice` uses compilation-context selection rules appropriate to that source file
-
-### Requirement: Context-sensitive data is queried with an explicit active context
-If multiple valid contexts exist for the same path, `clice` SHALL retain enough context identity to select the active one during query execution.
-
-#### Scenario: Multi-context source file remains distinguishable
-- **WHEN** the same source file is compiled under multiple valid compile commands
-- **THEN** `clice` preserves distinguishable context identities instead of collapsing them into one ambiguous runtime state
-
-#### Scenario: Context-sensitive lookup does not union incompatible states
-- **WHEN** a query targets a file whose symbols differ by context
-- **THEN** `clice` does not answer by blindly unioning incompatible context-specific results
-
-### Requirement: Missing context is surfaced explicitly
-If `clice` cannot determine a valid compilation context for a file, it SHALL surface the degraded state explicitly through diagnostics or logs rather than silently pretending the file has a correct context.
-
-#### Scenario: Missing header context is observable
-- **WHEN** `clice` cannot derive a usable context for an opened header
-- **THEN** the failure is visible through diagnostics, logs, or both

openspec/changes/assess-clice-production-readiness/specs/server-production-hardening/spec.md

@@ -1,33 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Worker lifecycle changes are reflected in runtime ownership
-`clice` SHALL keep worker ownership, opened-document tracking, and eviction state consistent across open, change, save, close, and worker-failure events.
-
-#### Scenario: Closing a document releases worker ownership
-- **WHEN** a document is closed
-- **THEN** `clice` removes the document from worker ownership tracking and allows its runtime state to be evicted
-
-#### Scenario: Worker failure is surfaced
-- **WHEN** a worker crashes, times out, or fails IPC
-- **THEN** `clice` records the failure and surfaces a defined error outcome instead of silently pretending the request succeeded
-
-### Requirement: Runtime resource controls are enforced rather than decorative
-Configured runtime limits for worker memory and background work SHALL affect actual scheduling or eviction behavior.
-
-#### Scenario: Memory limit influences eviction
-- **WHEN** worker memory pressure exceeds the configured limit
-- **THEN** `clice` uses the configured limit to drive eviction or rejection behavior
-
-### Requirement: Background work does not outrank active editing
-`clice` SHALL schedule compile and indexing work so that opened-document responsiveness takes priority over background throughput.
-
-#### Scenario: Open document work outranks background indexing
-- **WHEN** a user edits an opened document while background indexing is pending
-- **THEN** `clice` prioritizes the opened-document work ahead of non-urgent background indexing
-
-### Requirement: Production debugging information is observable
-`clice` SHALL emit enough logging and trace information to diagnose compile-context selection, worker failures, and request/response mismatches in production-style usage.
-
-#### Scenario: Compile failure includes useful context
-- **WHEN** a compile, header-context selection, or worker request fails
-- **THEN** logs include enough context to identify the affected file, command/context, and failure site

openspec/changes/assess-clice-production-readiness/tasks.md

@@ -1,49 +0,0 @@
-## 1. Buffer-Aware Document Model
-
-- [ ] 1.1 Introduce an explicit opened-document state model that tracks text, editor version, build generation, AST generation, and readiness state in the master/worker boundary
-- [ ] 1.2 Make `didOpen`, `didChange`, `didSave`, and `didClose` update one consistent source-of-truth flow for opened documents
-- [ ] 1.3 Replace the `ensure_compiled()` stub with generation-aware gating for AST-backed requests
-- [ ] 1.4 Reject or defer stale AST-backed feature requests instead of serving results from older generations
-- [ ] 1.5 Prevent AST-backed feature execution on fatal or otherwise unusable compilation units
-- [ ] 1.6 Add tests that cover unsaved edits, stale compile completion discard, and close-time state release
-
-## 2. Compilation Context Management
-
-- [ ] 2.1 Implement real project-derived compilation-context selection for headers without direct compile commands
-- [ ] 2.2 Define and persist distinct runtime identities for header contexts and source-file compilation contexts
-- [ ] 2.3 Make query paths accept an explicit active context instead of blindly unioning context-sensitive results
-- [ ] 2.4 Surface missing or degraded compilation-context selection through logs or diagnostics
-- [ ] 2.5 Add tests for header opening, project-context borrowing, and multi-context file handling
-
-## 3. Server Runtime Hardening
-
-- [ ] 3.1 Wire `didClose` to worker eviction and ownership cleanup so closed documents do not linger in worker memory
-- [ ] 3.2 Surface worker IPC failures, crashes, and timeouts as explicit server-side errors with useful logs
-- [ ] 3.3 Enforce configured resource controls such as worker memory limits instead of relying on hardcoded thresholds
-- [ ] 3.4 Prioritize opened-document compile work ahead of non-urgent background indexing
-- [ ] 3.5 Expand runtime logging for compile commands, context selection, worker failure causes, and request/result mismatches
-- [ ] 3.6 Add lifecycle and scheduling tests that cover worker cleanup, timeout handling, and active-edit priority
-
-## 4. Live-State Navigation Correctness
-
-- [ ] 4.1 Resolve source-side symbol lookup for opened files from the current AST before consulting disk-backed index data
-- [ ] 4.2 Define how active-document state is combined with index-backed remote results for definition and related navigation flows
-- [ ] 4.3 Remove or disable stubbed navigation fallback paths that cannot yet return correct results
-- [ ] 4.4 Add tests for navigation from unsaved buffers and mixed AST/index result paths
-
-## 5. AST-Only Feature Baseline
-
-- [ ] 5.1 Enrich hover so it returns semantic detail beyond bare symbol kind and name
-- [ ] 5.2 Add `documentHighlight` as an AST-backed feature with end-to-end capability advertisement and routing
-- [ ] 5.3 Expose `selectionRange` using the existing local selection machinery
-- [ ] 5.4 Upgrade completion and signature help with parameter-aware insertion and richer callable assistance
-- [ ] 5.5 Respect requested scope for inlay-hint computation instead of forcing full-document evaluation
-- [ ] 5.6 Implement the first production-worthy AST-only code actions or stop advertising stubbed code-action support
-- [ ] 5.7 Audit advertised AST-only capabilities and remove any remaining stub or placeholder surfaces
-- [ ] 5.8 Add or update feature-level tests and golden cases for every newly exposed AST-only feature
-
-## 6. Documentation And Readiness Tracking
-
-- [ ] 6.1 Write and maintain the detailed production-readiness gap analysis in `temp/`
-- [ ] 6.2 Update developer documentation for opened-buffer semantics, compilation-context handling, and feature ownership boundaries
-- [ ] 6.3 Define a dogfooding readiness checklist that combines server/core acceptance criteria with the minimum AST-only feature baseline

openspec/changes/improve-code-completion-parity/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-04-03

openspec/changes/improve-code-completion-parity/design.md

@@ -1,250 +0,0 @@
-## Context
-
-`clice` currently routes `textDocument/completion` through `MasterServer::forward_stateless()`, which prepares open-buffer text plus available PCH/PCM paths and sends a one-shot completion request to the stateless worker. The worker builds `CompilationParams`, invokes `feature::code_complete()`, and returns a raw `std::vector<CompletionItem>`.
-
-The implementation in `src/feature/code_completion.cpp` is intentionally small:
-
-- run Sema code completion at a single file/offset
-- compute the local identifier prefix
-- fuzzy-match candidate labels against the typed prefix
-- emit only basic LSP fields such as `label`, `kind`, `textEdit`, and `sortText`
-- bundle function overloads only by qualified name, with `detail = "(...)"` for grouped overloads
-
-Compared with the local `clangd` implementation in `.llvm/clang-tools-extra/clangd`, the gap is large and structural rather than cosmetic. `clangd` has a full completion pipeline:
-
-- request shaping from client capabilities and trigger context in `ClangdLSPServer`
-- `CodeCompleteFlow` as a staged completion engine rather than direct Sema rendering
-- candidate fusion from Sema, project index, and raw identifiers
-- context capture such as completion kind, query scopes, expected type, and following token
-- scoring that combines name match with semantic/contextual signals
-- richer LSP rendering including signatures, return types, docs, snippets, fix-its, additional edits, deprecation, `filterText`, `isIncomplete`, and include insertion
-
-At the same time, `clice` has infrastructure that clangd either lacks or does not currently integrate into completion as deeply:
-
-- explicit header-context modeling for headers shared by multiple includers
-- existing PCH/PCM request plumbing in the master/stateless worker path
-- merged per-file index shards and project-wide symbol/reference data
-- a project goal of instantiation-aware template processing
-
-There is also a hard constraint: `clice`'s current index symbol payload only stores `name`, `kind`, and reference files. That is enough for navigation-oriented lookup, but not enough for clangd-style index completion, which needs scope, signature, return type, documentation, deprecation, canonical declaration/header ownership, and dependency insertion hints.
-
-## Goals / Non-Goals
-
-**Goals:**
-
-- close the highest-value completion gap with clangd in behavior, not in file-by-file implementation shape
-- replace the current direct Sema-to-LSP path with a staged completion pipeline
-- support rich, capability-aware LSP completion responses
-- augment Sema completion with identifier and project-index candidates
-- introduce heuristics that use semantic/contextual signals instead of raw fuzzy score alone
-- define how fix-its and dependency insertion edits attach to completion items
-- use `clice`'s header-context, module, and template machinery to define completion behaviors clangd does not currently provide
-
-**Non-Goals:**
-
-- byte-for-byte parity with clangd internals or its exact scoring constants
-- introducing `completionItem/resolve` in this change
-- shipping a learned ranking model in the first implementation; heuristic ranking is sufficient
-- requiring the global index to become fully clangd-equivalent before completion quality improves
-- solving every completion-related editor quirk across all clients before the core pipeline exists
-
-## Decisions
-
-### 1. Split completion into request shaping, candidate collection, scoring, and rendering
-
-`clice` should stop treating code completion as "run Sema and immediately serialize `CompletionItem`s". Instead, completion will become a staged pipeline:
-
-1. request shaping at the LSP/server edge
-2. candidate collection in the worker
-3. merge/deduplicate/bundle
-4. score and truncate
-5. render to LSP according to client capabilities
-
-Why this approach:
-
-- it matches the actual gap with clangd, which is pipeline depth rather than one missing field
-- it keeps protocol negotiation in the server and semantic work in the worker
-- it allows `clice`-specific signals to affect ranking without polluting the LSP layer
-
-Alternative considered:
-
-- continue returning `std::vector<CompletionItem>` directly from `feature::code_complete()`
-  Rejected because `isIncomplete`, score-aware truncation, richer origins, and delayed rendering all need an intermediate completion model.
-
-### 2. Extend the completion request contract with client capabilities and trigger context
-
-The current stateless completion request only carries file text, compile arguments, and offset. The request contract should be extended so the worker can render results correctly:
-
-- completion trigger kind/character
-- client snippet support
-- documentation format preference
-- label-details support
-- supported completion item kinds
-- requested limit
-- overload-bundling preference
-
-The master server should negotiate these from `initialize` capabilities and pass a normalized completion-options struct to the worker.
-
-Why this approach:
-
-- `clangd` already proves that completion quality depends on client capabilities
-- several existing `CodeCompletionOptions` fields in `clice` are never meaningfully driven by the LSP client today
-- it keeps editor-specific policy out of the core collector logic
-
-Alternative considered:
-
-- hardcode one rendering mode for all clients
-  Rejected because it prevents snippet/doc behavior from ever becoming correct and makes the existing options struct mostly dead code.
-
-### 3. Keep Sema as the primary source of truth, but augment it with identifiers and index symbols
-
-Collection order should be:
-
-- Sema candidates from the active compilation context
-- local/raw identifiers from the open buffer and active file context
-- project/index candidates when the completion context allows them
-
-Sema remains primary because it understands visibility, module state, recovery fix-its, and the exact active compile command. Identifier and index sources fill gaps when Sema is incomplete or when project-wide results are useful.
-
-Merge rules should deduplicate by insertion semantics, not just by display label. Function overload bundling should group only candidates that render identically and require the same dependency edits.
-
-Why this approach:
-
-- it preserves correctness for the current file while still expanding recall
-- it fits `clice`'s current stateless worker path, which already builds the correct compile inputs
-- it allows richer completion without waiting for index-only correctness
-
-Alternative considered:
-
-- move to index-first completion with Sema as fallback
-  Rejected because `clice`'s strongest current signals for modules, fix-its, and header contexts come from active compilation, not from the persisted index.
-
-### 4. Expand the index schema specifically for completion metadata
-
-`clice`'s current `index::Symbol` payload is too small for rich completion. To support index-backed completion, the index data model should be extended with completion-oriented fields such as:
-
-- qualified scope / shortest usable qualifier
-- signature and return type
-- deprecation flag
-- documentation summary or documentation lookup key
-- canonical declaration path
-- preferred include header or module/import source
-- symbol origin/category for ranking
-
-The first implementation does not need every clangd field, but it does need enough metadata to render and rank project-index candidates meaningfully.
-
-Why this approach:
-
-- without extra index payload, project-index completion can only return weak name-only suggestions
-- dependency insertion cannot be justified without declaration ownership metadata
-- the serialization boundary already exists in `TUIndex`, `ProjectIndex`, and merged shards, so this is the right architectural layer
-
-Alternative considered:
-
-- use the current index unchanged and limit project-index completion to `name + kind`
-  Rejected because it would add complexity without delivering clangd-level value, and would likely need to be rewritten immediately after.
-
-### 5. Use heuristic ranking first, and encode the signals explicitly
-
-The first ranking model should remain heuristic, but it must go beyond raw fuzzy score. Candidate scoring should combine:
-
-- prefix/exact name match
-- semantic availability from Sema
-- in-scope vs required-qualifier insertion
-- expected type / preferred type compatibility when available
-- file/header-context proximity
-- deprecation penalty
-- module availability and dependency-edit cost
-- template-instantiation compatibility when `clice` can infer it
-
-This keeps the design testable and explainable without blocking on a learned model.
-
-Why this approach:
-
-- it delivers most user-visible value quickly
-- it maps naturally onto `clice`'s existing semantics-heavy architecture
-- it leaves room for a later learned ranker without locking the system into clangd's exact model
-
-Alternative considered:
-
-- adopt clangd-style decision-forest ranking immediately
-  Rejected because `clice` does not yet have the surrounding instrumentation and labeled data pipeline, and heuristic ranking is sufficient for this change.
-
-### 6. Treat completion-related edits as first-class output, with staged support
-
-Two classes of edits matter:
-
-- Sema-provided fix-its near the completion site
-- dependency insertion edits such as `#include` or `import`
-
-The completion model should carry both as structured edits and render them into LSP `additionalTextEdits` or merged `textEdit`s where appropriate.
-
-Implementation should be staged:
-
-- stage 1: preserve and emit Sema fix-its
-- stage 2: add dependency insertion for header-backed symbols once index metadata can justify it
-- stage 3: add module import insertion where the active TU and candidate source indicate a module-based dependency is the right form
-
-Why this approach:
-
-- it closes a large clangd parity gap without forcing all edit types at once
-- module-aware insertion is a place where `clice` can exceed clangd's current include-centric design
-
-Alternative considered:
-
-- postpone all completion edits until after ranking/index parity
-  Rejected because Sema fix-its are already available and should not be discarded.
-
-### 7. Make `clice`-specific header, module, and template context part of completion semantics
-
-The main "beyond clangd" opportunities should not be separate side features. They should influence the same completion pipeline:
-
-- **Header context**: completion in a header should use the active includer/source context for that header, instead of treating the header as a single global state.
-- **Modules**: available PCM/module dependencies should affect both candidate visibility and dependency insertion strategy.
-- **Template instantiation**: when `clice` can identify concrete instantiation or expected-type information, ranking should prefer candidates compatible with that instantiated context.
-
-This means the primary completion request must always be evaluated in one active compilation context, not a union of all possible contexts. Alternate contexts can be explored later, but blindly merging them would produce unstable and misleading completions.
-
-Why this approach:
-
-- it uses the architecture `clice` already claims as a differentiator
-- it avoids the worst failure mode for shared headers: mixing incompatible contexts into one result set
-- it keeps "beyond clangd" work aligned with user-visible completion quality
-
-Alternative considered:
-
-- add cross-context completion by merging all known header contexts
-  Rejected because it sacrifices correctness and predictable ranking for recall.
-
-## Risks / Trade-offs
-
-- [Index payload expansion increases serialization and background-index cost] → Mitigation: add only completion-relevant fields first and measure shard-size growth before expanding documentation payloads further.
-- [Ranking heuristics become opaque or brittle] → Mitigation: keep signals explicit, loggable, and unit-tested rather than encoding hidden constants throughout the collector.
-- [Header-context-aware completion can produce confusing behavior if the active context is wrong] → Mitigation: bind completion to the same active header-context selection model used by navigation/AST features, not an ad hoc completion-only heuristic.
-- [Dependency insertion can apply the wrong form (`#include` vs `import`)] → Mitigation: gate edits on explicit symbol metadata and active compilation mode, and prefer no edit over a wrong edit.
-- [More completion metadata increases protocol churn between master and stateless workers] → Mitigation: add a dedicated options/result struct instead of spreading new fields loosely across existing request params.
-
-## Migration Plan
-
-1. Extend the LSP/server edge to capture completion capabilities, trigger context, and limits.
-2. Introduce an internal completion result model and return a completion list shape with `isIncomplete`.
-3. Refactor the worker pipeline to separate candidate collection, merging, scoring, and rendering while preserving current Sema behavior.
-4. Add local-identifier completion and heuristic ranking improvements.
-5. Expand the index schema and integrate project-index candidates.
-6. Add completion-related edits, first for Sema fix-its and then for dependency insertion.
-7. Integrate header-context, module, and template-instantiation signals into ranking and edit policy.
-8. Expand unit and integration coverage around rendering, ranking, index augmentation, module-aware completion, and shared-header contexts.
-
-Rollback strategy:
-
-- keep Sema-only completion as a safe fallback path until the staged pipeline is stable
-- disable index augmentation or dependency insertion independently if they prove noisy
-- prefer full completion results without advanced edits over partially wrong completion behavior
-
-## Open Questions
-
-- How much documentation should be stored directly in `clice`'s index versus fetched/lazily summarized from declarations on demand?
-- Should project-index completion support all-scopes insertion from the first version, or require explicit qualifiers only after scope metadata is fully modeled?
-- What is the right UX for exposing the currently active header context to users when completion results differ across includers?
-- How aggressive should template-instantiation-aware ranking be before users perceive it as "hiding" generic but still legal completions?
-- Whether dependency insertion for modules should be represented as ordinary additional text edits or as a future code-action-style completion extension.

openspec/changes/improve-code-completion-parity/proposal.md

@@ -1,36 +0,0 @@
-## Why
-
-`clice` already answers `textDocument/completion`, but the current implementation is still a thin Sema wrapper: it gathers only compiler candidates, applies local fuzzy filtering, and returns minimal `CompletionItem` fields. Compared with the local `clangd` implementation under `.llvm/clang-tools-extra/clangd`, it is missing most of the completion pipeline that makes results accurate, stable, and editor-friendly: client capability negotiation, context-aware triggering, richer ranking, index-backed augmentation, richer rendering, and completion-related edits.
-
-This is worth addressing now because `clice` already has the infrastructure that can support a stronger design: background project indexing, merged per-file index shards, header-context modeling, stateless completion workers, and PCH/PCM plumbing for module-aware compilation. Closing the clangd gap will materially improve day-to-day usability, while `clice`'s existing header-context, module, and instantiation-aware architecture creates opportunities to implement completion behaviors clangd does not currently provide.
-
-## What Changes
-
-- Define a full code-completion pipeline for `clice` instead of the current direct Sema-to-LSP conversion path.
-- Add parity-oriented completion behavior for the highest-value clangd features:
-  - client capability negotiation for snippets, documentation format, label details, completion item kinds, and overload bundling
-  - trigger-character handling and suppression of obviously spurious auto-triggered completion
-  - richer `CompletionItem` rendering including `filterText`, stable `sortText`, signatures/details, return types, documentation, deprecation, snippet suffixes, and completion-related edits
-  - result limiting and `isIncomplete` signaling
-  - completion candidates from project index and local identifiers in addition to Sema results
-  - ranking that combines fuzzy match with semantic/contextual signals rather than raw name matching alone
-- Define how `clice` should attach edits associated with completion candidates, including fix-its and insertion of missing dependencies when the completion source can justify them.
-- Specify `clice`-specific completion extensions that go beyond clangd's current model:
-  - header-context-aware completion for headers shared by multiple includers
-  - module-aware completion that exploits existing PCM dependency tracking
-  - instantiation-aware ranking and filtering for template-heavy code
-- Add targeted unit and integration coverage so completion behavior can evolve without regressions.
-
-## Capabilities
-
-### New Capabilities
-- `code-completion`: Provide context-aware, multi-source C++ code completion with rich LSP rendering, ranking, dependency edits, and `clice`-specific support for header contexts, modules, and template instantiation.
-
-### Modified Capabilities
-- None.
-
-## Impact
-
-- Affected code: `src/feature/code_completion.cpp`, `src/feature/feature.h`, `src/server/master_server.cpp`, `src/server/stateless_worker.cpp`, `src/server/protocol.h`, and completion-related protocol wiring in the IPC/LSP layer.
-- Likely affected subsystems: project/merged index integration, document/client capability tracking, completion request routing, and any helper code used for include/import insertion or completion scoring.
-- Affected tests: completion unit tests, stateless worker tests, server integration tests, module fixtures, and new comparison-oriented cases for header-context and template-heavy completion.

openspec/changes/improve-code-completion-parity/specs/code-completion/spec.md

@@ -1,77 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Capability-aware completion responses
-The server SHALL shape code-completion responses according to client capabilities, trigger context, and requested limits instead of returning one fixed completion-item format to every client.
-
-#### Scenario: Snippet-capable client receives snippet completions
-- **WHEN** the client advertises snippet support and a completion candidate has callable arguments, template arguments, or other structured suffix text
-- **THEN** the completion response MUST encode that candidate using snippet-formatted insertion text rather than degrading it to plain text
-
-#### Scenario: Plain-text client receives compatible completion items
-- **WHEN** the client does not advertise snippet support or label-details support
-- **THEN** the server MUST return completion items that remain correct for that client and MUST NOT require unsupported snippet or label-details fields to preserve meaning
-
-#### Scenario: Completion result limit is enforced
-- **WHEN** the client or server applies a completion result limit and more matching candidates exist than can be returned
-- **THEN** the server MUST truncate the response to the chosen limit and MUST mark the completion list as incomplete
-
-#### Scenario: Spurious auto-triggered completion is suppressed
-- **WHEN** completion is auto-triggered by a trigger character in a syntactic position that cannot produce meaningful completion candidates
-- **THEN** the server MUST return an empty completion list instead of forcing a normal completion run
-
-### Requirement: Multi-source candidate collection and semantic ranking
-The server SHALL build completion results from multiple candidate sources and rank them using semantic/contextual signals rather than using only raw label matching.
-
-#### Scenario: Sema and index candidates are merged by insertion semantics
-- **WHEN** Sema and project-index collection both produce candidates that insert the same symbol in the same way
-- **THEN** the server MUST return a single merged completion item rather than duplicate visible entries
-
-#### Scenario: Local identifiers supplement Sema completion
-- **WHEN** the open document contains matching identifiers that are not surfaced by Sema at the completion point
-- **THEN** the server MUST be able to return those identifiers as completion candidates when they are relevant to the typed prefix
-
-#### Scenario: Required qualifiers are preserved for out-of-scope symbols
-- **WHEN** a project-index completion candidate is not directly visible at the completion point but remains a valid suggestion through qualification
-- **THEN** the completion item MUST preserve the required qualifier in its rendered insertion text instead of pretending the symbol is already in scope
-
-#### Scenario: Semantic relevance outranks weaker textual matches
-- **WHEN** two otherwise similar candidates match the typed prefix but only one is strongly favored by semantic/contextual signals such as active scope, expected type, or availability in the current compilation context
-- **THEN** the semantically favored candidate MUST rank above the weaker match
-
-### Requirement: Rich completion item rendering and completion-related edits
-The server SHALL render completion items with enough metadata and edits to make them useful in modern editors, including signatures, detail fields, filtering/sorting metadata, documentation, deprecation, and completion-associated edits.
-
-#### Scenario: Function completion includes signature and return-type detail
-- **WHEN** a callable declaration is returned as a completion candidate
-- **THEN** the completion item MUST expose its callable signature and MUST expose return-type or overload-summary detail in the rendered result
-
-#### Scenario: Documentation and deprecation are preserved
-- **WHEN** a completion candidate has documentation text or is marked deprecated by Sema or index metadata
-- **THEN** the completion item MUST surface the documentation and deprecation state to the client
-
-#### Scenario: Sema fix-its are attached to the completion item
-- **WHEN** Sema provides fix-it edits that are required or strongly suggested for a completion candidate
-- **THEN** the server MUST attach those edits to the completion item so the accepted completion can apply them
-
-#### Scenario: Dependency insertion edits are attached when justified
-- **WHEN** a completion candidate refers to a symbol that requires adding a missing dependency and the completion source can identify the correct insertion form
-- **THEN** the completion item MUST attach the corresponding dependency insertion edits instead of returning only the symbol name
-
-### Requirement: Context-sensitive completion for headers, modules, and templates
-The server SHALL use `clice`'s compilation-context machinery so completion reflects the active header context, module dependency state, and template-instantiation information instead of treating all files as context-free.
-
-#### Scenario: Shared header completion follows the active header context
-- **WHEN** the same header is completed under different active includer/source contexts
-- **THEN** the completion results MUST reflect the active header context rather than a context-free union of all possible includers
-
-#### Scenario: Module-aware completion uses available PCM dependencies
-- **WHEN** the active file depends on C++20 modules whose PCMs are available to the completion worker
-- **THEN** the completion pipeline MUST consider symbols made visible by those module dependencies when producing results
-
-#### Scenario: Module dependency insertion prefers import-aware edits
-- **WHEN** the selected completion candidate is best satisfied by adding a module dependency rather than a textual include and the active translation unit supports that form
-- **THEN** the completion item MUST use a module-aware dependency insertion edit instead of forcing a header-style include edit
-
-#### Scenario: Template-instantiation-aware ranking prefers concretely compatible candidates
-- **WHEN** the active completion site provides concrete template-instantiation or expected-type information that distinguishes candidate relevance
-- **THEN** the ranking logic MUST prefer candidates compatible with that instantiated context over otherwise similar generic alternatives

openspec/changes/improve-code-completion-parity/tasks.md

@@ -1,40 +0,0 @@
-## 1. Completion Request Contract
-
-- [ ] 1.1 Audit the current `textDocument/completion` request path and extend the master/worker protocol to carry trigger context, requested limit, and normalized client completion capabilities.
-- [ ] 1.2 Store completion-related client capabilities from `initialize` in the server and thread them into completion requests instead of relying on default `CodeCompletionOptions`.
-- [ ] 1.3 Change completion responses from a raw item vector to a completion-list shape that can represent `isIncomplete` and future completion metadata cleanly.
-
-## 2. Internal Completion Pipeline
-
-- [ ] 2.1 Introduce an internal completion-candidate/result model that separates collection, deduplication/bundling, scoring, truncation, and final LSP rendering.
-- [ ] 2.2 Refactor `src/feature/code_completion.cpp` so Sema collection populates the internal model instead of directly constructing final `CompletionItem`s.
-- [ ] 2.3 Implement capability-aware rendering for snippets, signatures/details, documentation, deprecation, `filterText`, and stable `sortText`.
-- [ ] 2.4 Add request-side suppression for obviously spurious auto-triggered completions and preserve correct fallback behavior for manual completion.
-
-## 3. Candidate Sources And Ranking
-
-- [ ] 3.1 Add local-identifier collection from the active buffer/file context and merge those candidates with Sema results.
-- [ ] 3.2 Implement semantic deduplication and overload bundling based on insertion semantics rather than label-only equality.
-- [ ] 3.3 Replace raw fuzzy-only ordering with explicit heuristic scoring that incorporates scope visibility, expected type, deprecation, and active compilation-context signals.
-- [ ] 3.4 Enforce result limits after scoring and verify that truncation drives `isIncomplete` correctly.
-
-## 4. Index Completion And Completion Edits
-
-- [ ] 4.1 Extend completion-relevant index data structures and serialization to store the metadata needed for index-backed completion rendering and ranking.
-- [ ] 4.2 Add project-index candidate lookup for completion and merge index candidates with Sema/identifier candidates without duplicating visible entries.
-- [ ] 4.3 Preserve and render Sema fix-it edits as completion-associated edits.
-- [ ] 4.4 Implement dependency insertion edits for header-backed symbols once index metadata can identify the correct declaration owner and insertion path.
-
-## 5. `clice`-Specific Completion Extensions
-
-- [ ] 5.1 Bind completion in headers to the active header-context selection model instead of treating shared headers as context-free.
-- [ ] 5.2 Integrate available PCM/module dependency information into candidate visibility and ranking for module-aware completion.
-- [ ] 5.3 Implement module-aware dependency insertion policy for completion items that should add `import`-style dependencies instead of header includes.
-- [ ] 5.4 Add template-instantiation-aware ranking signals where `clice` can derive concrete instantiation or expected-type compatibility.
-
-## 6. Validation
-
-- [ ] 6.1 Add focused unit tests for completion rendering, capability negotiation, overload bundling, sorting/filtering metadata, and `isIncomplete` behavior.
-- [ ] 6.2 Add unit or fixture-based tests for identifier augmentation, index-backed completion, fix-it edits, and dependency insertion edits.
-- [ ] 6.3 Add integration coverage for shared-header contexts, module-aware completion, and template-heavy completion cases.
-- [ ] 6.4 Run the relevant completion, worker, index, and integration test targets and fix regressions uncovered during verification.

openspec/changes/improve-document-symbol-outline/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-04-03

openspec/changes/improve-document-symbol-outline/design.md

@@ -1,101 +0,0 @@
-## Context
-
-The current `src/feature/document_symbols.cpp` implementation reuses the generic `FilteredASTVisitor`. Its advantage is brevity, but it does not model outline-specific semantics such as which declarations should become outline nodes, which should only forward traversal to children, and which subtrees should be skipped entirely.
-
-Compared with `clangd`'s `DocumentOutline`, the current implementation has several structural shortcomings:
-
-- Function nodes continue recursive traversal into function bodies, so local `VarDecl`, `RecordDecl`, `EnumDecl`, `BindingDecl`, and similar declarations may leak into the document outline.
-- Only implicit template instantiations are filtered today; explicit instantiations and explicit specializations do not have distinct visit policies.
-- Declarations produced by macro expansion are placed directly according to the expanded declaration instead of being grouped under main-file macro invocations as `clangd` does.
-- The implementation computes `range` / `selection_range` per declaration but does not repair parent-child range relationships after tree construction, and it does not provide fallback handling for macro locations or inconsistent written-name ranges.
-- Existing tests mostly assert total node counts, which is too weak to prevent hierarchy, naming, and range regressions.
-
-## Goals / Non-Goals
-
-**Goals:**
-
-- Align `clice` document outline behavior with `clangd` on the core semantic cases.
-- Show only document-level symbols users actually care about while preserving namespace, type, enum, and member hierarchy.
-- Define stable, testable behavior for templates and macros.
-- Replace count-only assertions with structural assertions that provide long-term regression protection.
-
-**Non-Goals:**
-
-- This change does not introduce `#pragma mark`-style outline grouping.
-- This change does not modify `workspace/symbol` behavior or index-layer symbol handling.
-- This change does not refactor unrelated AST traversal infrastructure.
-
-## Decisions
-
-### 1. Use a dedicated outline traversal instead of piling more special cases onto `FilteredASTVisitor`
-
-The core issue in document symbol collection is not "filter a few more decl kinds". It is the need to explicitly distinguish:
-
-- do not visit
-- visit declaration only
-- visit children only
-- visit both declaration and children
-
-This is exactly what `clangd`'s `VisitKind` model addresses. Keeping the generic visitor and layering more contextual flags on top would scatter function-body filtering, template behavior, and macro-container insertion across multiple callbacks and make the implementation harder to maintain.
-
-The alternative is to keep the current visitor and add more contextual checks such as "do not collect local declarations inside function bodies". That approach is smaller, but it does not naturally express leaf-only explicit instantiations, wrapper decl pass-through, or macro container insertion, so it is not chosen.
-
-### 2. Define template and wrapper-declaration behavior using explicit visit policies
-
-The new traversal should cover at least these rules:
-
-- `LinkageSpecDecl`, `ExportDecl`, and similar wrappers do not become outline nodes and only forward traversal to their children.
-- Functions and methods become nodes, but traversal must not descend into function-local declarations.
-- Implicit template instantiations are skipped entirely.
-- Explicit instantiations are shown as declaration-only leaf nodes and do not synthesize member children.
-- Explicit specializations show both the declaration itself and the children actually written in source.
-
-This makes the outline reflect the structure users wrote in the file instead of all declarations that happen to be traversable in the AST.
-
-### 3. Create container nodes for macro invocations written in the main file
-
-`clangd` includes macro invocations written directly in the main file as outline hierarchy nodes. `clice` already has enough macro-location decomposition support to adopt a similar strategy:
-
-- When a declaration originates from macro expansion, walk up the macro-caller chain until reaching a direct invocation written in the main file.
-- Create at most one container node per invocation site.
-- Attach all outline declarations produced by that invocation under the macro container.
-
-This avoids having multiple macro-expanded declarations appear as if they were written directly in the enclosing namespace or class scope, and it keeps the outline aligned with the entry points users actually see in the source.
-
-The alternative is to keep the current behavior and only repair ranges. That is simpler to implement, but it leaves macro-heavy outlines difficult to understand, so it is not chosen.
-
-### 4. Repair ordering and ranges after building the tree
-
-The protocol requires `selectionRange` to be contained within `range`, and editors generally assume parent ranges contain child ranges. The current implementation sorts declarations individually but does not apply a tree-level repair pass.
-
-This change adds a post-processing step that:
-
-- sorts siblings stably in source order
-- expands parent ranges when child ranges extend beyond the initially collected parent range
-- repairs inconsistent `selectionRange` values by falling back to a more reliable location, and collapses to a single range if necessary
-
-This keeps editor-facing invariants centralized instead of scattering boundary-fix logic across declaration collection paths.
-
-### 5. Test structure directly instead of asserting only node counts
-
-New and updated tests should assert:
-
-- top-level and child hierarchy
-- `name` / `kind` for key nodes
-- the absence of leaked local declarations
-- macro container presence and correct children
-- expected behavior for explicit instantiations and explicit specializations
-- `selectionRange` containment within `range`
-
-This is the minimum needed to cover the semantics that actually matter in this change.
-
-## Risks / Trade-offs
-
-- [Higher implementation complexity] -> The traversal logic will be longer than the current visitor-based version. Split visit-policy handling, macro-container logic, and range repair into separate helpers to keep it manageable.
-- [Macro container icon semantics may be imperfect] -> LSP `SymbolKind` does not offer an ideal macro-specific visual category. Prioritize correct hierarchy and ranges first.
-- [Template edge cases are numerous] -> Cover the highest-value cases first with tests for implicit instantiation, explicit instantiation, and explicit specialization behavior.
-- [Snapshot-style tests would be brittle] -> Prefer structural assertions over full JSON snapshots to reduce churn from unrelated field changes.
-
-## Open Questions
-
-- Should this change also add deprecated document symbol metadata, depending on whether the current protocol schema supports `DocumentSymbol.tags` or `deprecated` fields cleanly?

openspec/changes/improve-document-symbol-outline/proposal.md

@@ -1,28 +0,0 @@
-## Why
-
-`clice`'s current `document_symbols` implementation collects `NamedDecl`s through the generic `FilteredASTVisitor`. Compared with `clangd`'s dedicated outline builder, it still lacks several important constraints: filtering function-local declarations, differentiating template specializations from instantiations, grouping macro-expanded declarations, and repairing `range` / `selectionRange` / parent-child nesting invariants.
-
-These gaps directly affect outline stability and readability in editors, and they leave a visible behavior gap between `clice` and `clangd` on real C++ code. Closing them now should materially improve document outline quality without changing the LSP surface area.
-
-## What Changes
-
-- Replace the generic "collect interesting decls during recursive traversal" approach with an outline-specific traversal model.
-- Exclude declarations that should not appear in document outline results, especially function-local declarations, implicit entities, and implicit template instantiations.
-- Define template behavior explicitly so specializations, explicit instantiations, and ordinary template declarations appear in the outline in a source-intuitive way.
-- Introduce macro container symbols for macro invocations written in the main file so expanded declarations appear under a stable hierarchy instead of leaking into the enclosing scope.
-- Normalize symbol ordering and range invariants so `selectionRange` is always contained in `range`, and parent ranges always contain child ranges.
-- Strengthen unit and integration coverage so regressions are caught by structural assertions instead of node counts alone.
-
-## Capabilities
-
-### New Capabilities
-- `document-symbols`: Provide document outline output that matches source structure more closely and behaves robustly in template and macro-heavy code.
-
-### Modified Capabilities
-- None.
-
-## Impact
-
-- Affected code: `src/feature/document_symbols.cpp` and any reused helpers for macro locations or source range repair.
-- Affected tests: `tests/unit/feature/document_symbol_tests.cpp` and `tests/integration/test_server.py`.
-- User-visible behavior: editor Outline / Breadcrumb / Document Symbols views will behave more like `clangd`, especially for local declarations, templates, and macro-heavy code.

openspec/changes/improve-document-symbol-outline/specs/document-symbols/spec.md

@@ -1,59 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Document outline excludes non-structural local declarations
-The document symbol response SHALL include user-written document-structure declarations from the main file, including namespaces, records, enums, fields, top-level variables, functions, methods, constructors, destructors, conversion functions, deduction guides, concepts, and structured bindings.
-
-The document symbol response SHALL NOT include declarations that are local to a function or method body, and SHALL NOT include implicit declarations or implicit template instantiations.
-
-#### Scenario: Local variable does not appear in outline
-- **WHEN** a function body contains a local variable declaration and a local class declaration
-- **THEN** the function itself appears in document symbols
-- **THEN** the local variable and local class do not appear as document symbol children
-
-#### Scenario: Member hierarchy is preserved
-- **WHEN** a record contains nested records, fields, methods, and enum members
-- **THEN** the outer record appears in document symbols
-- **THEN** the nested declarations appear as children of that record in source order
-
-### Requirement: Template specializations follow written-source structure
-The document symbol response SHALL ignore implicit template instantiations.
-
-The document symbol response SHALL include user-written explicit specializations and explicit instantiations exactly once. Explicit specializations that define nested members SHALL expose those nested members as children. Explicit instantiations SHALL appear as leaf symbols unless the source itself contains nested declarations at that location.
-
-#### Scenario: Explicit specialization exposes children
-- **WHEN** a class template has an explicit specialization with user-written members in the main file
-- **THEN** the explicit specialization appears in document symbols
-- **THEN** its user-written members appear as children of that specialization
-
-#### Scenario: Explicit instantiation is a leaf
-- **WHEN** the main file contains an explicit template instantiation declaration or definition
-- **THEN** the instantiated symbol appears in document symbols exactly once
-- **THEN** it does not synthesize member children that are not written at the instantiation site
-
-### Requirement: Macro-expanded declarations are grouped by macro invocation
-When a declaration included in the outline originates from a macro expansion whose invocation is written directly in the main file, the document symbol response SHALL group the expanded declarations under a macro container symbol associated with that invocation.
-
-The macro container SHALL appear at the invocation site and SHALL contain all outline declarations produced by that invocation within the current scope.
-
-#### Scenario: Function-like macro groups expanded declarations
-- **WHEN** a function-like macro invocation in the main file expands to a class declaration with members
-- **THEN** document symbols include a container node for that macro invocation
-- **THEN** the expanded class appears as a child of that container node
-
-#### Scenario: One macro invocation creates one container
-- **WHEN** a single macro invocation expands to multiple top-level declarations
-- **THEN** document symbols include one container node for that invocation
-- **THEN** all declarations produced by that invocation appear beneath the same container node
-
-### Requirement: Document symbol ranges are editor-safe
-Document symbols SHALL be returned in source order within each sibling list.
-
-For every returned symbol, `selectionRange` SHALL be contained within `range`. For every parent symbol with children, the parent `range` SHALL contain each child `range`, including declarations originating from macro expansions.
-
-#### Scenario: Selection range is repaired when written name range is inconsistent
-- **WHEN** a declaration's preferred name location would produce a `selectionRange` outside its declaration `range`
-- **THEN** the response repairs the symbol ranges so that `selectionRange` is contained within `range`
-
-#### Scenario: Parent range contains nested child symbols
-- **WHEN** a symbol has nested child declarations whose ranges extend beyond the initially collected parent range
-- **THEN** the parent symbol range is expanded so that all child ranges are contained within it

openspec/changes/improve-document-symbol-outline/tasks.md

@@ -1,17 +0,0 @@
-## 1. Outline Traversal
-
-- [ ] 1.1 Replace the generic document symbol collector with a dedicated outline traversal that can distinguish skip / only-decl / only-children / decl-and-children behavior.
-- [ ] 1.2 Filter out function-local declarations, implicit entities, and implicit template instantiations while preserving namespace, type, enum, field, and member hierarchy.
-- [ ] 1.3 Implement explicit specialization and explicit instantiation behavior so written specializations can expose children and explicit instantiations remain leaf symbols.
-
-## 2. Macro And Range Handling
-
-- [ ] 2.1 Build macro invocation container nodes for declarations expanded from main-file macro calls.
-- [ ] 2.2 Add post-processing to stabilize sibling ordering and enforce `selectionRange`-within-`range` plus parent-range-contains-child-range invariants.
-- [ ] 2.3 Confirm whether the current protocol layer can carry deprecated document symbol metadata and either implement it here or record a follow-up.
-
-## 3. Validation
-
-- [ ] 3.1 Rewrite unit tests to assert symbol names, kinds, hierarchy, and range invariants instead of only total node counts.
-- [ ] 3.2 Add regression cases covering local declarations, explicit specialization/instantiation, and macro-expanded declarations.
-- [ ] 3.3 Extend integration coverage so the server request path exercises representative document symbol responses.

openspec/changes/improve-folding-range-support/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-04-03

openspec/changes/improve-folding-range-support/design.md

@@ -1,199 +0,0 @@
-## Context
-
-`clice` currently implements folding ranges in [`src/feature/folding_ranges.cpp`](/home/ykiko/C++/clice/src/feature/folding_ranges.cpp). The implementation is primarily an AST visitor with extra handling for conditional compilation and `#pragma region` data from `CompilationUnitRef::directives()`. It already covers many structural folds that clangd does not currently expose, such as namespaces, records, function parameter lists, lambda captures, call argument lists, access-specifier sections, and initializer lists.
-
-Compared with `.llvm/clang-tools-extra/clangd`, the current gap is clear:
-
-- clangd already has behavior that `clice` still lacks:
-  - multiline comment folding
-  - `lineFoldingOnly` client-capability handling
-  - a more complete and assertion-backed folding-range test matrix
-- `clice` already has behavior that clangd does not:
-  - richer AST-structure folding
-  - `#pragma region` and some conditional-compilation folding
-  - `collapsedText`
-- `clice` still has obvious opportunities that are not fully implemented yet:
-  - fully closing the last `#if/#elif/#else` branch at `#endif`
-  - folding inactive branches
-  - folding multiline macro definitions
-  - grouping contiguous `#include` / `import` blocks
-  - capability-aware `kind` and `collapsedText` rendering
-
-In addition, the current public output exposes many internal categories directly through `FoldingRange.kind`, such as `"namespace"`, `"class"`, and `"functionBody"`. This is more aggressive than clangd, but standard LSP only defines `comment`, `imports`, and `region` as interoperable folding kinds. The design therefore needs to preserve richer internal classification while presenting a compatible external contract.
-
-## Goals / Non-Goals
-
-**Goals:**
-
-- Preserve `clice`'s current advantage in AST-structure folding instead of regressing to clangd's much narrower block-only baseline.
-- Fill the high-value baseline gaps that clangd already covers, especially multiline comments and `lineFoldingOnly`.
-- Turn preprocessor metadata into a differentiating `clice` capability covering conditional branches, macro definitions, and include/import grouping.
-- Make folding-range output respect client capabilities with predictable fallback behavior.
-- Lock behavior down with unit and integration tests across AST, comments, preprocessor handling, and protocol negotiation.
-
-**Non-Goals:**
-
-- Achieve byte-for-byte or range-for-range parity with clangd in this change.
-- Add fine-grained folding for every C++ syntax detail such as template parameter lists, requires-clauses, or attribute arguments before their value is proven.
-- Introduce editor-specific behavior that only exists to satisfy one frontend.
-- Add cross-file or index-backed folding behavior.
-
-## Decisions
-
-### 1. Split the folding-range pipeline into collection, normalization, and rendering
-
-The current implementation mixes "how a range is discovered" with "how it is emitted as LSP". The new design separates this into three layers:
-
-- collection: produce internal `RawFoldingRange` entries from AST, comment scanning, and preprocessor metadata
-- normalization: sort, deduplicate, validate, and reconcile nested or overlapping ranges
-- rendering: decide line/column boundaries, `kind`, and `collapsedText` based on client capabilities
-
-Why:
-
-- `lineFoldingOnly`, `collapsedText`, and standards-compatible kind downgrading are rendering concerns and should not pollute collection logic
-- comments, macros, and include/import groups do not naturally belong inside the AST visitor
-- future range limiting or prioritization should also live in normalization/rendering instead of collector code
-
-Alternative considered:
-
-- Keep generating final LSP ranges directly inside the visitor. Rejected because capability negotiation and multi-source collection will keep making the function larger and harder to test.
-
-### 2. Keep rich internal categories, but only promise standard-compatible public kinds
-
-Internally, the implementation may still distinguish namespace, class, function body, macro definition, conditional branch, and similar categories so tests, prioritization, and `collapsedText` selection remain precise. However, public LSP output should default to standard kinds only:
-
-- comment folds -> `comment`
-- contiguous include/import groups -> `imports`
-- all other structural and preprocessor folds -> `region`
-
-If some client later proves it needs clice-specific kinds, that can be evaluated separately. This change does not make non-standard kind strings part of the compatibility contract.
-
-Why:
-
-- many current custom strings will not be understood by clients and do not produce stable UI semantics
-- the real differentiator is what `clice` can fold, not the literal `kind` label
-- once public kinds are standardized, `collapsedText` and range boundaries become the primary user-visible expression
-
-Alternative considered:
-
-- Continue exposing all custom kinds directly. Rejected because that leaves client compatibility up to luck rather than protocol design.
-
-### 3. Implement comment folding through lexical/source scanning, not AST
-
-Multiline comments are handled independently in clangd's pseudo-parser path, and `clice` should do the same. The design adds a comment collector that scans the main-file source or token stream directly:
-
-- fold multiline `/* ... */` block comments
-- fold contiguous `//` comment groups
-- do not fold single-line comments
-- adjust closing boundaries for `lineFoldingOnly` mode so the final visible line is not swallowed incorrectly
-
-Why:
-
-- comments are not AST structure, so trying to derive them from AST produces fragile behavior
-- lexical scanning naturally handles adjacent-comment grouping and block-comment boundaries
-
-Alternative considered:
-
-- Only support block comments. Rejected because clangd already demonstrates that contiguous `//` comment groups are a useful folding case.
-
-### 4. Rework preprocessor folding around complete branch blocks instead of the current half-open stack
-
-Today `collect_condition_directives()` only closes the previous branch when it sees `#else`, but when it sees `#endif` it only pops the stack and does not emit a folding range for the final `#if/#elif/#else` branch. As a result, `#if` folding is incomplete.
-
-The new design treats conditional compilation as an explicit branch-group model:
-
-- maintain the ordered branch chain for each `#if` group
-- allow every branch to close at the next `#elif`, `#else`, or `#endif`
-- distinguish active and inactive branches
-- allow inactive branches to produce region folds, optionally with distinct `collapsedText`
-
-Why:
-
-- this is the minimum sound model needed to fix the current logical gap
-- `Condition::ConditionValue` already records true/false/skipped state and can drive inactive-branch folding directly
-
-Alternative considered:
-
-- Patch only the `#endif` closing case. Rejected because nested conditions, inactive branches, and range ordering would remain structurally weak.
-
-### 5. Add dedicated directive-based collectors for macros and include/import groups
-
-`clice` already collects:
-
-- `directive.macros`
-- `directive.includes`
-- `directive.imports`
-
-The new design therefore adds directive-based folding collectors for:
-
-- multiline `#define` macro definitions, using continuation backslashes or stable definition ranges
-- contiguous `#include` blocks, merged into a single `imports` folding range
-- contiguous `import Foo;` / `import Foo:Bar;` module-import blocks, also emitted as `imports`
-
-Why:
-
-- the necessary data already exists in preprocessing metadata and does not require new AST modeling
-- this is one of the easiest places for `clice` to provide value beyond clangd
-
-Alternative considered:
-
-- Leave include/import grouping for a later change. Rejected because the metadata already exists, the implementation cost is relatively low, and the editor-facing value is immediate.
-
-### 6. Folding-range output must be explicitly bound to client capabilities
-
-The master server currently only advertises `foldingRangeProvider = true`, but it does not read or propagate folding-specific client capabilities. The new design requires the session to track at least:
-
-- `lineFoldingOnly`
-- whether `collapsedText` is supported
-- optional `rangeLimit`
-
-Rendering rules:
-
-- when `lineFoldingOnly = true`, only emit ranges that remain meaningful as line-based folds, adjusting end lines where necessary
-- when the client does not support `collapsedText`, omit it
-- when a `rangeLimit` is declared, trim results deterministically rather than arbitrarily
-
-Alternative considered:
-
-- Continue always returning exact columns and `collapsedText`. Rejected because that relies on client tolerance instead of following the protocol contract.
-
-### 7. Organize tests by source category and protocol behavior
-
-Tests will be split into two dimensions:
-
-- source-category unit tests: AST structure, comments, conditional compilation, multiline macros, `#pragma region`, and include/import groups
-- protocol-behavior tests: `lineFoldingOnly`, `collapsedText` support, public kind mapping, and range limiting
-
-In particular, the current [`tests/unit/feature/folding_range_tests.cpp`](/home/ykiko/C++/clice/tests/unit/feature/folding_range_tests.cpp) contains `Directive` and `PragmaRegion` cases that do not actually assert results. This change upgrades them into strong assertion-based tests.
-
-Alternative considered:
-
-- Rely mostly on manual editor validation. Rejected because folding details regress easily, especially for preprocessor handling and line-only rendering.
-
-## Risks / Trade-offs
-
-- [Client capabilities must flow from initialize state into request-time rendering] -> Mitigation: introduce a dedicated folding-options structure so session details do not leak broadly into the feature layer.
-- [Inactive-branch and macro-definition ranges can be unstable around expansion locations] -> Mitigation: prefer spelling/main-file ranges and explicitly filter or special-case macro-expansion ranges when necessary.
-- [Adding comments, macros, and include/import groups can increase the number of ranges quickly] -> Mitigation: implement stable sorting and `rangeLimit` trimming in the normalization layer.
-- [Mapping public kinds back to standard values changes current metadata output] -> Mitigation: the folds themselves remain; the user-visible change is mostly in optional metadata, and tests plus change notes will make that explicit.
-- [Multiple collectors may produce overlapping or duplicate ranges] -> Mitigation: normalize by source category and boundary rules so collectors do not amplify noise.
-
-## Migration Plan
-
-1. Refactor the internal folding-range data flow and add render options plus standard kind mapping.
-2. Add the comment collector and assertion-backed tests for multiline comment folding.
-3. Rewrite conditional-directive and `#pragma region` collection so `#if` branches close correctly through `#endif`.
-4. Add multiline macro folding and grouped include/import collectors.
-5. Wire folding client capabilities through initialize/request handling and add integration coverage.
-6. Add `rangeLimit` trimming and regression cleanup after the new collectors are in place.
-
-Rollback strategy:
-
-- If protocol negotiation proves unstable, keep the new collectors but temporarily disable outward behavior changes tied to `collapsedText` or `rangeLimit`.
-- If a particular new fold category proves noisy, roll it back collector-by-collector instead of reverting the entire folding-range refactor.
-
-## Open Questions
-
-- Should multiline macro folding cover only the macro body, or the full `#define NAME(...)` line plus body as one fold region?
-- Should `rangeLimit` prioritize outer structure, top-of-file regions, or longer ranges when trimming results?
-- For structural AST folds originating from macro expansion, should `clice` preserve current behavior or restrict itself to cases with stable spelling ranges only?

openspec/changes/improve-folding-range-support/proposal.md

@@ -1,28 +0,0 @@
-## Why
-
-`clice`'s folding range support is already more aggressive than clangd's: it can fold namespaces, records, function parameter lists and bodies, lambda captures, call argument lists, access-specifier sections, and some preprocessor regions. However, it still lacks several useful baseline capabilities that clangd already has, especially multiline comment folding, client capability negotiation, and a stronger regression test matrix. Its preprocessor branch folding is also not yet fully closed.
-
-More importantly, `clice` already has preprocessor metadata that clangd does not fully exploit, such as `directive.macros`, `directive.includes`, `directive.imports`, and evaluated conditional-branch state. That means `clice` should not stop at matching clangd: folding ranges can become a feature that is more useful for real-world C/C++ editing by covering macro definitions, `#if` branches, and include/import groups that clangd does not currently handle well.
-
-## What Changes
-
-- Fill the remaining folding-range baseline gaps between `clice` and clangd, especially multiline comment folding and protocol-level client capability handling.
-- Complete preprocessor-related folding so full `#if/#elif/#else/#endif` branch regions, nested `#pragma region` blocks, and inactive branches have well-defined behavior.
-- Add folding features that take advantage of `clice`'s existing preprocessor metadata, including multiline macro definitions and grouped `#include` / `import` blocks.
-- Normalize `FoldingRange.kind` and `collapsedText` output so standard kinds remain compatible while clice-specific fold categories degrade predictably.
-- Make folding range responses honor client capabilities such as `lineFoldingOnly`, `collapsedText` support, and range limiting.
-- Expand unit and integration coverage for AST folds, comments, preprocessor regions, macros, include/import groups, and protocol negotiation behavior.
-
-## Capabilities
-
-### New Capabilities
-- `folding-ranges`: Provide LSP-compatible, C/C++-focused folding regions that cover AST structure, comments, preprocessor branches, macro definitions, and include/import groups.
-
-### Modified Capabilities
-- None.
-
-## Impact
-
-- Primary impact is in `src/feature/folding_ranges.cpp`, the compile-unit/preprocessor metadata access paths, and folding range request handling plus capability negotiation around `src/server/master_server.cpp`.
-- Tests need expansion in `tests/unit/feature/folding_range_tests.cpp`, server/integration coverage, and any required fixtures for preprocessor and module scenarios.
-- User-visible behavior will be folding results that are closer to clangd where clangd already has coverage, while also adding high-value C/C++ folds that clangd does not currently provide well, especially macro-definition and conditional-compilation folding.

openspec/changes/improve-folding-range-support/specs/folding-ranges/spec.md

@@ -1,61 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Folding range responses honor client capabilities
-The server SHALL render folding ranges according to the client's declared folding capabilities instead of always returning the richest possible payload.
-
-#### Scenario: Line-only folding is respected
-- **WHEN** the client declares `textDocument.foldingRange.lineFoldingOnly = true`
-- **THEN** the server MUST return folding ranges that remain valid when interpreted as whole-line folds, including adjusting end boundaries for bracketed or comment ranges whose closing delimiter is on the last line
-
-#### Scenario: Collapsed text is gated by client support
-- **WHEN** the client does not declare support for `textDocument.foldingRange.foldingRange.collapsedText`
-- **THEN** the server MUST omit `collapsedText` from the folding range response
-
-#### Scenario: Standard kinds are emitted compatibly
-- **WHEN** a folding range represents a comment block, an include/import block, or any other foldable region
-- **THEN** the server MUST emit `kind = comment`, `kind = imports`, or `kind = region` respectively, and MUST NOT require clients to understand clice-specific kind strings in order to fold correctly
-
-### Requirement: Structural and comment folding baseline
-The server SHALL provide folding ranges for multi-line C/C++ structural regions and multi-line comments in the main file.
-
-#### Scenario: Multi-line comment blocks can be folded
-- **WHEN** a document contains a multi-line `/* ... */` comment or a contiguous block of `//` comments spanning more than one line
-- **THEN** the server MUST return a folding range for that comment block with `kind = comment`
-
-#### Scenario: Single-line comments are not folded
-- **WHEN** a document contains a single-line comment that does not extend across multiple lines and is not part of a larger contiguous comment block
-- **THEN** the server MUST NOT return a folding range for that comment
-
-#### Scenario: Existing structural regions remain foldable
-- **WHEN** a document contains a multi-line namespace, record, function body, parameter list, lambda body, initializer list, or other supported structural region already collected by clice
-- **THEN** the server MUST continue to return a folding range for that region if its boundaries can be mapped back to the main file
-
-### Requirement: Preprocessor regions fold as complete branch blocks
-The server SHALL provide complete and nested folding ranges for preprocessor branch structures instead of leaving the final branch in a conditional block unclosed.
-
-#### Scenario: Final conditional branch closes at endif
-- **WHEN** a document contains a `#if/#elif/#else/#endif` chain
-- **THEN** the server MUST generate a folding range for each multi-line branch body, including the last branch body that ends at `#endif`
-
-#### Scenario: Inactive conditional branches can be folded
-- **WHEN** a conditional branch is known to be inactive or skipped in the current preprocessing configuration
-- **THEN** the server MUST be able to return a folding range covering that inactive branch region using `kind = region`
-
-#### Scenario: Nested pragma regions are folded
-- **WHEN** a document contains nested `#pragma region` / `#pragma endregion` pairs in the main file
-- **THEN** the server MUST return properly nested folding ranges for each matched region pair
-
-### Requirement: C/C++ directive groups and multiline macros are foldable
-The server SHALL use clice's preprocessor metadata to expose foldable ranges that clangd does not currently provide.
-
-#### Scenario: Multi-line macro definitions can be folded
-- **WHEN** a document contains a multi-line macro definition whose body spans more than one physical line
-- **THEN** the server MUST return a folding range for that macro definition using `kind = region`
-
-#### Scenario: Consecutive include directives are grouped
-- **WHEN** a document contains a contiguous block of `#include` directives with no intervening non-trivia code lines
-- **THEN** the server MUST return a folding range covering that include block using `kind = imports`
-
-#### Scenario: Consecutive module imports are grouped
-- **WHEN** a document contains a contiguous block of C++ module `import` declarations with no intervening non-trivia code lines
-- **THEN** the server MUST return a folding range covering that import block using `kind = imports`

openspec/changes/improve-folding-range-support/tasks.md

@@ -1,29 +0,0 @@
-## 1. Folding Range Pipeline
-
-- [ ] 1.1 Refactor `src/feature/folding_ranges.cpp` so collection, normalization, and LSP rendering are separated by an internal raw-range model.
-- [ ] 1.2 Add folding render options for `lineFoldingOnly`, `collapsedText` support, and optional `rangeLimit`, and thread them through the folding request path.
-- [ ] 1.3 Replace direct exposure of clice-specific public folding kinds with a stable mapping to standard LSP `comment` / `imports` / `region` kinds.
-
-## 2. Comment and Structural Baseline
-
-- [ ] 2.1 Add a comment collector that folds multi-line block comments and contiguous multi-line `//` comment groups in the main file.
-- [ ] 2.2 Preserve existing AST structural folding behavior while routing it through the new normalization/rendering pipeline.
-- [ ] 2.3 Add focused unit tests for comment folding, single-line comment exclusion, and structural folding regressions.
-
-## 3. Preprocessor Folding
-
-- [ ] 3.1 Rework conditional-directive collection so each `#if/#elif/#else/#endif` branch body closes correctly, including the final branch ending at `#endif`.
-- [ ] 3.2 Add folding support for inactive conditional branches using the existing preprocessor condition metadata.
-- [ ] 3.3 Strengthen `#pragma region` handling and add assertion-based tests for nested region folding.
-
-## 4. Clice-Specific Folding Extensions
-
-- [ ] 4.1 Add folding ranges for multi-line macro definitions using `directive.macros` and stable main-file source ranges.
-- [ ] 4.2 Add grouping folds for contiguous `#include` blocks and return them as `imports` ranges.
-- [ ] 4.3 Add grouping folds for contiguous C++ module `import` declarations and cover mixed include/import layouts with tests.
-
-## 5. Protocol and Validation
-
-- [ ] 5.1 Capture client folding capabilities during initialize and use them when serving `textDocument/foldingRange`.
-- [ ] 5.2 Add integration coverage for `lineFoldingOnly`, `collapsedText` gating, and kind/output compatibility.
-- [ ] 5.3 Run the relevant folding-range unit and integration tests, then fix any ordering, deduplication, or boundary regressions found during verification.

openspec/changes/improve-semantic-tokens-and-module-highlighting/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-04-03

openspec/changes/improve-semantic-tokens-and-module-highlighting/design.md

@@ -1,141 +0,0 @@
-## Context
-
-`clice` already exposes `textDocument/semanticTokens/full` and advertises a legend derived from `SymbolKind` and `SymbolModifiers`, but the implementation in `src/feature/semantic_tokens.cpp` only emits:
-
-- lexical tokens such as comments, strings, numbers, directives, headers, and keywords
-- declaration/definition markers for named declarations and macros
-- a template marker for templated declarations
-
-This leaves most of the declared semantic surface unused. In particular, `SymbolKind::Module`, `Attribute`, `Operator`, `Paren`, `Bracket`, `Brace`, `Angle`, `Concept`, and several declaration kinds/modifiers are either never emitted or emitted only indirectly. The current merge logic also degrades overlapping classifications to `Conflict`, which throws away useful semantic information instead of preferring the more specific token.
-
-The gap is visible when compared with clangd: clangd classifies more AST constructs, supports semantic token delta responses with `resultId`, and refreshes tokens when a more accurate AST becomes available. `clice` also already contains C++20 module infrastructure, `directive.imports`, `CompilationUnitRef::module_name()`, and a reserved `handleModuleOccurrence()` hook, so module-aware semantic tokens fit the current architecture rather than requiring a new subsystem.
-
-## Goals / Non-Goals
-
-**Goals:**
-
-- Emit materially richer semantic token kinds and modifiers from AST information instead of relying mostly on lexical fallback.
-- Highlight C++20 module declarations and imports, including named modules and partitions.
-- Replace `Conflict`-style overlap handling with deterministic precedence so semantic meaning is preserved.
-- Support semantic token `resultId` and `/full/delta` responses, with cache invalidation and refresh when rebuilds change highlighting.
-- Add tests that lock in token kinds, modifiers, and module-specific behavior.
-
-**Non-Goals:**
-
-- Achieve byte-for-byte parity with clangd's full highlighting matrix in a single change.
-- Add `textDocument/semanticTokens/range`.
-- Add end-user configuration for disabling token kinds/modifiers in this change.
-- Redesign the broader `SymbolKind` taxonomy used by completion, hover, or indexing.
-
-## Decisions
-
-### 1. Keep the existing two-phase model, but turn semantic tokens into an overlay with precedence
-
-The collector will continue to start with a lexical pass so comments, literals, directives, and headers remain available even before AST-specific enrichment. Semantic passes will then add higher-priority tokens for declarations, operators, attributes, concepts, brackets, and modules.
-
-Instead of collapsing equal-range overlaps to `Conflict`, the merge step will apply explicit precedence:
-
-- semantic classification beats lexical classification
-- more specific semantic kinds beat generic ones
-- modifiers are merged when the underlying symbol identity is compatible
-- `Conflict` remains only as a last-resort debugging state, not the normal output
-
-Why this approach:
-
-- it preserves the current fast lexical baseline
-- it minimizes churn in call sites
-- it matches how editors expect semantic tokens to augment syntax coloring rather than erase it
-
-Alternative considered:
-
-- emit semantic tokens from AST only and drop lexical fallback entirely. Rejected because it would lose highlighting for comments/directives/headers and make partially-built AST states visibly worse.
-
-### 2. Use existing compile-layer module metadata for module token extraction
-
-Module highlighting will use data already available in `CompilationUnitRef` and compile directives:
-
-- `CompilationUnitRef::module_name()` and `is_module_interface_unit()` for the current unit
-- `directives().imports` for imported module names
-- `TokenBuffer` / spelled token APIs for mapping module names and separators to source ranges
-
-This is preferred over trying to rely only on `VisitImportDecl` because the repository already captures import metadata during preprocessing, and the current `SemanticVisitor` module hooks are intentionally incomplete. The design can still route final token creation through `handleModuleOccurrence()`, but the source of truth for locating module-name tokens should be the compile-layer token data.
-
-Alternative considered:
-
-- finish the commented-out `SemanticVisitor::VisitImportDecl` path first and derive all module tokens from AST traversal. Rejected for now because preprocessing already records import structure reliably, while AST-only extraction is more fragile around partitions and special module forms.
-
-### 3. Fill the most valuable semantic gaps first
-
-The implementation should prioritize the categories that are already modeled in `SymbolKind`/`SymbolModifiers` and easy to validate in tests:
-
-- declaration kinds already discoverable from `NamedDecl`
-- module names and partitions
-- attributes such as `final` / `override` and explicit attribute syntax
-- overloaded and built-in operators
-- bracket-like punctuation tied to templates and explicit operators/casts
-- modifiers such as `Const`, `Overloaded`, and `Typed` where the current AST plumbing can support them without ambiguity
-
-Why this scope:
-
-- it closes the largest visible gap quickly
-- it avoids inventing new token kinds before the existing taxonomy is exercised
-- it keeps the change aligned with the user's clangd comparison request
-
-Alternative considered:
-
-- introduce new token kinds/modifiers to mirror clangd more directly. Rejected because `clice` already has an internal taxonomy and the first priority is to use it consistently.
-
-### 4. Add delta responses in the server layer, not inside feature collection
-
-`feature::semantic_tokens()` should continue returning a full logical token stream for one snapshot of a document. Delta computation, `resultId` assignment, and cache management belong in the server/request layer because they depend on per-document history rather than AST semantics.
-
-Expected server changes:
-
-- advertise `semanticTokensProvider.full.delta = true`
-- accept `textDocument/semanticTokens/full/delta`
-- cache the last encoded token stream per document
-- invalidate the cache on close, rebuild, and version changes that replace the document snapshot
-- send `workspace/semanticTokens/refresh` when the server has moved from a stale/partial semantic view to a fresh compiled view and the client supports refresh
-
-Alternative considered:
-
-- compute deltas in the feature layer on raw tokens. Rejected because delta state must be keyed by document lifecycle and LSP request history, which the feature layer does not own.
-
-### 5. Treat tests as the contract for token stability
-
-This change will expand test coverage instead of relying on manual editor inspection alone:
-
-- unit tests for token kinds/modifiers in small annotated snippets
-- unit tests for merge precedence and multiline encoding invariants
-- integration tests for full-token and delta requests
-- module fixture tests covering named modules, partitions, global module fragments, private fragments, and importers
-
-Alternative considered:
-
-- validate only through smoke tests in an editor. Rejected because token regressions are subtle and easy to reintroduce without precise assertions.
-
-## Risks / Trade-offs
-
-- [Token overlap rules become too ad hoc] → Define a small explicit precedence table and test it directly instead of scattering special cases through the merge code.
-- [Template angle brackets and parser-token splitting differ from `TokenBuffer` behavior] → Scope bracket highlighting to ranges that can be proven from spelled tokens and add regression tests for nested templates.
-- [Module syntax has corner cases such as global module fragments, private fragments, and partitions] → Require stable highlighting only for named module/import identifiers and avoid inventing semantics for punctuation that cannot be located robustly.
-- [Delta cache becomes stale after recompilation or close/reopen cycles] → Tie cache lifetime to document URI/version and clear it on close, invalidation, and failed rebuilds.
-- [More semantic passes increase feature latency] → Keep lexical scanning unchanged, reuse existing AST traversal hooks, and benchmark only if tests show material slowdown.
-
-## Migration Plan
-
-1. Extend token collection and merge rules while preserving the current full-token API.
-2. Add module-aware token extraction and expand unit tests.
-3. Wire server-side delta support and refresh/invalidation behavior.
-4. Update integration tests to cover both full and delta semantic token requests.
-
-Rollback strategy:
-
-- disable delta advertisement and continue serving full tokens if cache invalidation proves unstable
-- keep lexical fallback so the editor still receives usable highlighting even if some semantic categories are temporarily rolled back
-
-## Open Questions
-
-- Whether `Const`, `Typed`, and `Overloaded` should be emitted only when derived with high confidence, or whether some heuristic cases are acceptable.
-- Whether refresh notifications should be sent only after successful recompilation or also after dependency-driven module invalidation.
-- Whether bracket/operator highlighting should be limited to the kinds already modeled in `SymbolKind`, or whether a follow-up change should align names more closely with standard LSP token vocabularies.

openspec/changes/improve-semantic-tokens-and-module-highlighting/proposal.md

@@ -1,28 +0,0 @@
-## Why
-
-`clice` already advertises semantic tokens, but the current implementation only covers a narrow subset of the available `SymbolKind` and modifier space. Compared with clangd, it is missing several high-value semantic classifications, has no protocol support for semantic token deltas or refresh, and leaves C++20 module names unhighlighted even though the semantic visitor already reserves hooks for them.
-
-Improving this now will make highlighting materially more accurate in real C++ code, reduce the visible gap with clangd, and let `clice`'s existing C++20 module pipeline surface richer editor feedback instead of treating modules as plain identifiers.
-
-## What Changes
-
-- Expand semantic token collection beyond lexical tokens and basic declaration/reference handling so `clice` can emit more of its declared `SymbolKind` and modifier set.
-- Add AST-driven classification for operators, bracket-like punctuation, attributes, concepts, and other symbols that currently fall back to plain lexical highlighting or are omitted entirely.
-- Implement semantic highlighting for C++20 module declarations and imports, including named modules and partitions.
-- Improve token conflict resolution so overlapping lexical and semantic classifications prefer the most specific semantic meaning instead of collapsing to `Conflict`.
-- Add server-side support for semantic token result IDs and delta updates, with refresh support wired where document recompilation changes highlighting.
-- Strengthen unit and integration coverage for semantic tokens, especially module-specific fixtures and multi-token semantic cases.
-
-## Capabilities
-
-### New Capabilities
-- `semantic-tokens`: Provide richer semantic token classification for C++ code, including AST-derived symbol kinds, modifiers, incremental token delivery, and C++20 module-aware highlighting.
-
-### Modified Capabilities
-- None.
-
-## Impact
-
-- Affected code: `src/feature/semantic_tokens.cpp`, `src/semantic/semantic_visitor.h`, semantic token request handling in the server, and semantic token protocol wiring.
-- Affected tests: `tests/unit/feature/semantic_tokens_tests.cpp`, server integration tests, and module fixtures under `tests/data/modules/`.
-- User-visible behavior: editors will receive more accurate semantic token kinds/modifiers and module-aware highlighting without requiring API-breaking changes.

openspec/changes/improve-semantic-tokens-and-module-highlighting/specs/semantic-tokens/spec.md

@@ -1,50 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Rich semantic token classification
-The server SHALL classify semantic tokens using AST-derived symbol kinds and modifiers when that information is available, instead of limiting output to lexical token classes and basic declaration markers.
-
-#### Scenario: Declaration kinds use semantic classification
-- **WHEN** a document contains declarations and references for namespaces, records, enums, functions, methods, fields, variables, parameters, labels, concepts, or macros
-- **THEN** the semantic token response MUST encode those occurrences with the corresponding `SymbolKind` rather than a generic lexical fallback
-
-#### Scenario: Semantic modifiers are preserved
-- **WHEN** a token represents a declaration, definition, template-related symbol, const-qualified symbol, overloaded symbol, or typed punctuation that `clice` can determine from the AST
-- **THEN** the semantic token response MUST include the corresponding `SymbolModifiers` bits for that token
-
-#### Scenario: Semantic meaning wins over lexical overlap
-- **WHEN** lexical and semantic passes produce overlapping classifications for the same source token
-- **THEN** the server MUST prefer the most specific semantic classification and MUST NOT degrade the final response to `Conflict` for normal supported cases
-
-### Requirement: C++20 module-aware semantic highlighting
-The server SHALL emit semantic tokens for C++20 module declarations and imports so module names and partitions are distinguishable from ordinary identifiers.
-
-#### Scenario: Named module declaration is highlighted
-- **WHEN** a module interface or implementation unit contains a named module declaration such as `export module Foo;` or `module Foo;`
-- **THEN** the `module` keyword MUST be highlighted as a keyword and the module-name tokens MUST be highlighted with `SymbolKind::Module`
-
-#### Scenario: Module import is highlighted
-- **WHEN** a translation unit imports a named module or partition such as `import Foo;` or `import Foo:Bar;`
-- **THEN** the `import` keyword MUST be highlighted as a keyword and the imported module-name tokens MUST be highlighted with `SymbolKind::Module`
-
-#### Scenario: Non-module fragments do not invent module-name tokens
-- **WHEN** a file contains module-related fragment syntax such as `module;` or `module :private;`
-- **THEN** the server MUST highlight the language keywords normally and MUST only emit `SymbolKind::Module` tokens for the actual named module identifiers that exist in source
-
-### Requirement: Semantic token incremental delivery
-The server SHALL support stable semantic token result IDs and delta responses for documents whose previous semantic token result is known.
-
-#### Scenario: Full request returns a result identifier
-- **WHEN** a client sends `textDocument/semanticTokens/full`
-- **THEN** the response MUST include the full semantic token data for the current document snapshot and a `resultId` that can be used for a later delta request
-
-#### Scenario: Delta request returns edits when previous result matches
-- **WHEN** a client sends `textDocument/semanticTokens/full/delta` with the latest known `resultId` for a document
-- **THEN** the server MUST return semantic token edits relative to that previous result instead of forcing a full token payload
-
-#### Scenario: Delta request falls back to full tokens when history is unavailable
-- **WHEN** a client sends `textDocument/semanticTokens/full/delta` with an unknown or stale `resultId`
-- **THEN** the server MUST return a full semantic token result for the current document snapshot
-
-#### Scenario: Rebuild-driven semantic changes trigger refresh
-- **WHEN** recompilation, dependency invalidation, or module rebuild changes the semantic token output for an open document and the client supports semantic token refresh
-- **THEN** the server MUST request a semantic token refresh so the client can fetch updated tokens

openspec/changes/improve-semantic-tokens-and-module-highlighting/tasks.md

@@ -1,23 +0,0 @@
-## 1. Semantic Token Collection
-
-- [ ] 1.1 Audit `src/feature/semantic_tokens.cpp` against `SymbolKind` and `SymbolModifiers`, and add collection paths for the high-value AST-derived kinds/modifiers covered by the spec.
-- [ ] 1.2 Replace equal-range `Conflict` collapsing with explicit token precedence and modifier-merging rules, and add focused unit tests for overlap behavior.
-- [ ] 1.3 Extend token encoding tests to cover newly emitted semantic kinds/modifiers without regressing multiline and UTF-8/UTF-16 behavior.
-
-## 2. C++20 Module Highlighting
-
-- [ ] 2.1 Implement module-name token extraction for named module declarations using existing `CompilationUnitRef`, directive, and token-buffer APIs.
-- [ ] 2.2 Implement module-name token extraction for `import` statements, including partition forms such as `Foo:Bar`.
-- [ ] 2.3 Add regression tests for named modules, imports, global module fragments, private fragments, and dotted/partitioned module fixtures.
-
-## 3. LSP Semantic Token Delivery
-
-- [ ] 3.1 Extend server capability advertisement and request routing to support `textDocument/semanticTokens/full/delta`.
-- [ ] 3.2 Add per-document semantic token caching with stable `resultId` handling and full-result fallback for stale delta requests.
-- [ ] 3.3 Invalidate semantic token caches on document lifecycle changes and trigger semantic token refresh when recompilation changes highlighting for open documents.
-
-## 4. Validation
-
-- [ ] 4.1 Add or expand unit tests for operators, attributes, concepts, bracket-like tokens, and semantic modifiers that are newly emitted.
-- [ ] 4.2 Add integration coverage for semantic token full and delta requests in the server test suite.
-- [ ] 4.3 Run the relevant semantic token and module test targets, then fix any fixture or behavior mismatches discovered during verification.

openspec/changes/improve-signature-help-parity-with-clangd/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-04-03

openspec/changes/improve-signature-help-parity-with-clangd/design.md

@@ -1,115 +0,0 @@
-## Context
-
-`clice` currently implements signature help in `src/feature/signature_help.cpp` by subclassing `clang::CodeCompleteConsumer`, iterating overload candidates, and manually rendering labels for a handful of candidate kinds. That gives a usable baseline, but it leaves several visible gaps compared with clangd:
-
-- the collector always picks `active_signature = 0` and largely forwards `current_arg` directly, without clangd-style remapping for variadics or other candidate-specific parameter lists
-- signature labels are assembled manually rather than from Clang's `CodeCompletionString`, so optional parameters, documentation chunks, and rendered parameter metadata are less faithful
-- the server advertises a bare `SignatureHelpOptions{}` rather than clangd-like trigger and retrigger characters
-- the request path does not thread signature-help-specific client capabilities or context into feature generation
-- tests only verify a minimal overload case and non-crash request flow, while clangd covers overload ordering, function pointers, constructors, aggregates, nested expressions, variadics, templates, stale preambles, and prerequisite modules
-
-clangd's implementation is a good reference because it solves these problems without inventing a separate subsystem: it still uses overload candidates, but builds signatures from `CodeCompletionString`, maps active arguments to rendered parameters, negotiates documentation format and offset support, and validates the behavior with broad regression coverage.
-
-## Goals / Non-Goals
-
-**Goals:**
-
-- Align `clice`'s user-visible signature help behavior with clangd for the major C++ call forms that users hit in practice.
-- Advertise and honor signature-help protocol details that affect editor behavior, especially trigger characters, documentation format, and parameter label offsets.
-- Make active-parameter selection robust for variadic, defaulted, templated, constructor, aggregate, and function-pointer signatures.
-- Add test coverage strong enough to prevent the current behavior gap from reopening.
-
-**Non-Goals:**
-
-- Achieve byte-for-byte parity with every clangd-only extension or internal API.
-- Redesign completion, scheduling, or the broader server architecture outside what signature help needs.
-- Introduce unrelated LSP features such as snippet completion changes or semantic-token work in this change.
-
-## Decisions
-
-### 1. Keep the overload-candidate pipeline, but switch rendering to `CodeCompletionString`
-
-`clice` should keep using `clang::CodeCompleteConsumer` and `ProcessOverloadCandidates()`, but the collector should stop hand-formatting signatures for each candidate kind wherever Clang already provides a `CodeCompletionString`. This matches clangd's approach and brings several benefits at once:
-
-- rendered labels stay closer to Clang's own completion view
-- placeholder and optional chunks can drive parameter extraction directly
-- signature and parameter documentation become available without bespoke formatting logic
-
-Alternative considered:
-
-- keep the current manual `switch(candidate.getKind())` rendering and patch missing cases individually. Rejected because it duplicates logic clangd already solved and makes edge cases like optional parameters and documentation much harder to maintain.
-
-### 2. Treat active parameter as a negotiated LSP field backed by candidate-aware remapping
-
-The top-level `SignatureHelp.activeParameter` should remain the primary LSP signal, but `clice` should remap the current argument index against the rendered parameter list for the active candidate instead of forwarding `current_arg` blindly. In particular:
-
-- variadic calls should clamp to the final variadic parameter
-- constructor and aggregate initializers should map to the field or constructor slot actually being edited
-- function-pointer and template cases should use the rendered parameter list rather than raw AST counts when they differ
-
-Alternative considered:
-
-- add per-signature active-parameter support first. Rejected for now because clangd does not rely on it either, and the highest-value fix is correct top-level `activeParameter` behavior.
-
-### 3. Thread signature-help capabilities and context through the server and worker boundary
-
-The feature layer needs more than just file path and offset. This change should carry enough request metadata to shape the output:
-
-- requested documentation format
-- whether parameter label offsets are supported
-- any signature-help request context needed for retrigger behavior or follow-up refinements
-
-This keeps protocol negotiation in the server layer while allowing feature code to decide which fields to populate.
-
-Alternative considered:
-
-- hardcode plain-text output and always return offset labels regardless of client support. Rejected because clangd already demonstrates that clients negotiate these details, and ignoring them makes interoperability less predictable.
-
-### 4. Advertise clangd-like trigger coverage, but only promise behavior that `clice` can validate
-
-The server should advertise trigger and retrigger characters for the call and initializer delimiters that matter in C++ editing: `(`, `)`, `{`, `}`, `<`, `>`, and `,`. This is close to clangd and matches the call forms already exercised by clangd's tests.
-
-The implementation should still avoid overpromising beyond validated behavior. If a trigger reaches an unsupported syntactic corner case, the request may still return no signatures, but the advertised surface should cover the common forms users expect in editors.
-
-Alternative considered:
-
-- advertise only `(` and `,`. Rejected because it would keep `clice` visibly behind clangd for constructors, aggregates, and template-argument contexts.
-
-### 5. Use clangd's existing tests as the baseline for `clice` regression coverage
-
-This change should not invent a new test matrix from scratch. Instead, it should translate the highest-value clangd signature-help cases into `clice`'s unit, worker, integration, and module test suites:
-
-- overloads and ordering
-- default and optional arguments
-- active argument detection inside nested expressions
-- constructors, aggregates, and function pointers
-- variadics and template arguments
-- imported declarations and prerequisite module builds
-
-Alternative considered:
-
-- rely on manual editor checks and the current smoke tests. Rejected because most of the gap is in edge cases that regress silently without precise assertions.
-
-## Risks / Trade-offs
-
-- [Eventide LSP bindings do not expose all signature-help capability fields] -> Extend the local protocol surface or add thin adapter fields in `clice`'s request path, then lock that behavior down with serialization tests.
-- [Switching to `CodeCompletionString` changes overload ordering or rendered labels unexpectedly] -> Keep ordering rules explicit and update tests to assert the intended contract rather than incidental string formatting.
-- [Documentation lookup adds latency or becomes stale] -> Prefer AST docs when immediately available, use bounded index fallback where it materially improves output, and keep empty-documentation paths cheap.
-- [Module and imported-declaration cases depend on prerequisite build state] -> Reuse the existing module test infrastructure and make module-specific coverage part of the acceptance criteria instead of an optional follow-up.
-
-## Migration Plan
-
-1. Extend protocol and options plumbing so signature-help requests can carry client capability details and the server can advertise trigger coverage.
-2. Refactor the collector to use richer completion-string data, fix active-parameter mapping, and add documentation support.
-3. Add clangd-inspired unit, worker, integration, and module tests until the intended behavior is covered end to end.
-
-Rollback strategy:
-
-- revert to the previous manual rendering path while keeping the safer request plumbing if the richer collector proves unstable
-- reduce advertised trigger coverage temporarily if a specific delimiter family produces repeated false positives
-
-## Open Questions
-
-- Whether the current eventide protocol types already carry enough signature-help context, or whether `clice` needs to extend its local wrappers.
-- Whether parameter-level documentation is worth populating in this change, or whether signature-level documentation is sufficient for parity.
-- Whether `clice` should exactly mirror clangd's trigger set or trim it slightly if one delimiter family remains under-tested after implementation.

openspec/changes/improve-signature-help-parity-with-clangd/proposal.md

@@ -1,24 +0,0 @@
-## Why
-
-`clice` already returns basic signature help, but compared with clangd it mostly exposes raw overload candidates and misses several behaviors that make signature help reliable in real code: protocol trigger coverage, documentation, robust active-parameter mapping, and regression-tested handling for constructors, aggregates, variadics, templates, and imported declarations. Closing this gap now will make call-site assistance materially more useful and establish a spec-backed contract for one of `clice`'s core interactive features.
-
-## What Changes
-
-- Audit `clice`'s current signature help implementation against clangd and close the highest-value gaps that affect LSP-visible behavior.
-- Improve signature construction so parameter labels, optional/defaulted arguments, variadics, templates, constructors, aggregates, and function-pointer calls are rendered consistently and the active parameter is chosen correctly.
-- Extend the server and request path to advertise and honor signature-help protocol details such as trigger/retrigger characters, documentation format, and parameter label offsets where supported by the client and protocol layer.
-- Add coverage for imported or module-provided declarations and other clangd-tested edge cases so signature help stays stable as the compiler pipeline evolves.
-
-## Capabilities
-
-### New Capabilities
-- `signature-help`: Provide clangd-aligned signature help behavior for callable expressions, including robust active-parameter tracking, richer signature metadata, protocol negotiation, and regression-tested edge-case coverage.
-
-### Modified Capabilities
-- None.
-
-## Impact
-
-- Affected code: `src/feature/signature_help.cpp`, `src/feature/feature.h`, `src/server/master_server.cpp`, `src/server/stateless_worker.cpp`, `src/server/protocol.h`, and any eventide protocol bindings touched by signature-help capability negotiation.
-- Affected tests: `tests/unit/feature/signature_help_tests.cpp`, `tests/unit/server/stateless_worker_tests.cpp`, `tests/integration/test_server.py`, and new fixtures inspired by `.llvm/clang-tools-extra/clangd/unittests/CodeCompleteTests.cpp`.
-- User-visible behavior: editors should receive more complete and predictable signature help, especially while typing nested calls, constructor or aggregate initializers, variadic calls, and declarations coming from imported modules or prerequisite module builds.

openspec/changes/improve-signature-help-parity-with-clangd/specs/signature-help/spec.md

@@ -1,52 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Server advertises signature help trigger coverage
-The server SHALL advertise a signature help provider that includes the trigger and retrigger characters needed to keep signature help updated while the user edits callable and initializer argument lists.
-
-#### Scenario: Initialize returns signature help triggers
-- **WHEN** a client initializes against the server
-- **THEN** the advertised `signatureHelpProvider` includes trigger support for `(`, `)`, `{`, `}`, `<`, `>`, and `,`
-
-### Requirement: Signature help returns overload sets and the active parameter
-The server SHALL return all applicable signature candidates for the callable at the cursor and SHALL report the active signature and active parameter for the call being edited.
-
-#### Scenario: Overloaded function call
-- **WHEN** the cursor is inside a call to an overloaded function
-- **THEN** the result contains each viable overload signature
-- **THEN** the result identifies the active parameter for the preferred signature
-
-### Requirement: Signature help maps arguments to rendered parameters across C++ call forms
-The server SHALL remap the current argument index to the correct rendered parameter for variadic, defaulted, templated, constructor, aggregate, and function-pointer signatures instead of exposing raw argument indices when they exceed or differ from the displayed parameter list.
-
-#### Scenario: Variadic call stays on the variadic parameter
-- **WHEN** the user types beyond the fixed parameters of a variadic callable
-- **THEN** the reported active parameter remains the final variadic parameter instead of advancing past the signature
-
-#### Scenario: Constructor or aggregate initializer
-- **WHEN** the cursor is inside a constructor call or aggregate braced initializer
-- **THEN** the result describes the constructor or aggregate fields being initialized
-- **THEN** the reported active parameter matches the current initializer slot
-
-### Requirement: Signature help returns stable parameter metadata and documentation
-The server SHALL return parameter label metadata aligned with the rendered signature label, and SHALL include signature documentation in the format negotiated with the client when documentation is available from AST comments or indexed symbols.
-
-#### Scenario: Client supports label offsets and markdown documentation
-- **WHEN** the client declares parameter label offset support and markdown signature documentation
-- **THEN** returned signatures include offset-based parameter labels
-- **THEN** returned signatures include markdown-formatted documentation when documentation is available
-
-#### Scenario: Callable without documentation
-- **WHEN** a callable has no available documentation
-- **THEN** the server still returns the signature label and parameter metadata without failing the request
-
-### Requirement: Signature help works for imported declarations and nested expressions
-The server SHALL provide signature help for call sites that resolve through imported or prerequisite-module declarations and for cursors nested inside expressions within argument lists.
-
-#### Scenario: Imported module declaration
-- **WHEN** the user requests signature help for a function imported from a prerequisite C++20 module
-- **THEN** the result includes the imported declaration's signature
-
-#### Scenario: Cursor inside nested argument expression
-- **WHEN** the cursor is inside an expression that itself appears in an argument position
-- **THEN** the server reports signature help for the innermost active call
-- **THEN** the reported active parameter matches that nested call site

openspec/changes/improve-signature-help-parity-with-clangd/tasks.md

@@ -1,21 +0,0 @@
-## 1. Protocol And Request Plumbing
-
-- [ ] 1.1 Extend signature-help capability advertisement and request plumbing to carry trigger or retrigger characters, documentation format, parameter label-offset support, and any required request context across the server and worker boundary.
-- [ ] 1.2 Expand `SignatureHelpOptions` and related protocol serialization tests so feature code can choose output shape based on negotiated client capabilities.
-
-## 2. Signature Collection Parity
-
-- [ ] 2.1 Refactor `src/feature/signature_help.cpp` to build labels and parameters from richer completion-string data instead of relying only on manual overload formatting.
-- [ ] 2.2 Add candidate-aware active-parameter mapping for variadic, defaulted, templated, constructor, aggregate, and function-pointer signatures, keeping overload ordering deterministic.
-- [ ] 2.3 Populate signature documentation and parameter metadata from AST comments and index or preamble lookups where available, without regressing empty-documentation cases.
-
-## 3. Edge Cases And Module Coverage
-
-- [ ] 3.1 Verify signature help for nested calls, opening delimiters, braced initializers, function pointers, and imported or module-provided declarations, fixing any parser or snapshot assumptions that block these cases.
-- [ ] 3.2 Add or update worker and server handling needed for stale compile state and prerequisite module builds so signature help remains available after document edits and module preparation.
-
-## 4. Validation
-
-- [ ] 4.1 Expand `tests/unit/feature/signature_help_tests.cpp` with clangd-inspired cases for overloads, active arguments, default arguments, variadics, templates, constructors, aggregates, and nested expressions.
-- [ ] 4.2 Add server and worker tests that assert capability advertisement and returned signature metadata instead of only checking for non-crash behavior.
-- [ ] 4.3 Run the relevant signature-help, stateless-worker, integration, and module test targets, then fix any regressions uncovered during verification.

openspec/config.yaml

@@ -1,20 +0,0 @@
-schema: spec-driven
-
-# Project context (optional)
-# This is shown to AI when creating artifacts.
-# Add your tech stack, conventions, style guides, domain knowledge, etc.
-# Example:
-#   context: |
-#     Tech stack: TypeScript, React, Node.js
-#     We use conventional commits
-#     Domain: e-commerce platform
-
-# Per-artifact rules (optional)
-# Add custom rules for specific artifacts.
-# Example:
-#   rules:
-#     proposal:
-#       - Keep proposals under 500 words
-#       - Always include a "Non-goals" section
-#     tasks:
-#       - Break tasks into chunks of max 2 hours

pixi.toml

@@ -14,17 +14,24 @@ readme = "README.md"
 documentation = "https://docs.clice.io/clice/"
 repository = "https://github.com/clice-io/clice"
 channels = ["conda-forge"]
-platforms = ["win-64", "linux-64", "osx-arm64"]
+platforms = ["win-64", "linux-64", "osx-arm64", "osx-64", "linux-aarch64", "win-arm64"]
 
 [environments]
 default = ["build", "test"]
 package = ["build", "test", "package"]
+cross-macos-x64 = ["build", "package", "cross-macos-x64"]
+cross-linux-aarch64 = ["build", "package", "cross-linux-aarch64"]
+cross-windows-arm64 = ["build", "package", "cross-windows-arm64"]
 node = ["node"]
 format = ["format"]
+test-run = ["test"]
 
 # ============================================================================== #
 #                                  DEPENDENCIES                                  #
 # ============================================================================== #
+[feature.build]
+platforms = ["win-64", "linux-64", "osx-arm64", "osx-64", "linux-aarch64"]
+
 [feature.build.dependencies]
 python = ">=3.13"
 cmake = ">=3.30"
@@ -33,7 +40,9 @@ clang = "==20.1.8"
 clangxx = "==20.1.8"
 lld = "==20.1.8"
 llvm-tools = "==20.1.8"
+clang-tools = "==20.1.8"
 compiler-rt = "==20.1.8"
+flatbuffers = "==25.9.23"
 
 [feature.build.target.win-64.dependencies]
 sccache = "*"
@@ -53,15 +62,69 @@ scripts = ["scripts/activate_linux.sh"]
 [feature.build.target.win-64.activation]
 scripts = ["scripts/activate_asan.bat"]
 
+# macOS x64 (from arm64): clang natively supports cross-arch, no extra deps.
+[feature.cross-macos-x64.target.osx-arm64.dependencies]
+
+[feature.cross-macos-x64.target.osx-arm64.activation]
+scripts = ["scripts/activate_cross_macos.sh"]
+
+# Linux aarch64 (from x64): needs aarch64 sysroot and cross gcc for libstdc++.
+[feature.cross-linux-aarch64.target.linux-64.dependencies]
+sysroot_linux-aarch64 = "==2.17"
+gcc_linux-aarch64 = "==14.2.0"
+gxx_linux-aarch64 = "==14.2.0"
+
+[feature.cross-linux-aarch64.target.linux-64.activation]
+scripts = ["scripts/activate_cross_linux.sh"]
+
+# Windows arm64 (from x64): Windows SDK on CI already includes ARM64 libs.
+[feature.cross-windows-arm64.target.win-64.dependencies]
+
+[feature.cross-windows-arm64.target.win-64.activation]
+scripts = ["scripts/activate_cross_windows.bat"]
+
+[feature.test.dependencies]
+python = ">=3.13"
+
+# On macOS, the system Apple clang emits vendor-specific flags that upstream
+# LLVM cannot parse.  Providing upstream clang + lld in PATH prevents
+# fallback to /usr/bin/clang++ and satisfies toolchain.cmake's -fuse-ld=lld.
+[feature.test.target.osx-64.dependencies]
+clang = "==20.1.8"
+clangxx = "==20.1.8"
+lld = "==20.1.8"
+
+[feature.test.target.osx-arm64.dependencies]
+clang = "==20.1.8"
+clangxx = "==20.1.8"
+lld = "==20.1.8"
+
 [feature.test.pypi-dependencies]
 pytest = "*"
 pytest-asyncio = ">=1.1.0"
+pytest-timeout = "*"
 pygls = ">=2.0.0"
 lsprotocol = ">=2024.0.0"
 
 [feature.package.dependencies]
 xz = ">=5.8.1,<6"
 
+[feature.package.tasks.package-config]
+args = [{ arg = "type", default = "RelWithDebInfo" }]
+cmd = """
+cmake -B build/{{ type }} -G Ninja \
+    -DCMAKE_BUILD_TYPE={{ type }} \
+    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain.cmake \
+    -DCLICE_RELEASE=ON
+"""
+
+[feature.package.tasks.package]
+args = [{ arg = "type", default = "RelWithDebInfo" }]
+depends-on = [
+    { task = "package-config", args = ["{{ type }}"] },
+    { task = "cmake-build", args = ["{{ type }}"] },
+]
+
 # ============================================================================== #
 #                                   CMAKE                                        #
 # ============================================================================== #
@@ -69,14 +132,13 @@ xz = ">=5.8.1,<6"
 args = [
     { arg = "type", default = "RelWithDebInfo" },
     { arg = "ci", default = "OFF" },
-    { arg = "extra", default = "" },
 ]
 cmd = """
 cmake -B build/{{ type }} -G Ninja \
     -DCMAKE_BUILD_TYPE={{ type }} \
     -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain.cmake \
     -DCLICE_ENABLE_TEST=ON \
-    -DCLICE_CI_ENVIRONMENT={{ ci }} {{extra}} \
+    -DCLICE_CI_ENVIRONMENT={{ ci }}
 """
 
 [feature.build.tasks.cmake-build]
@@ -87,22 +149,25 @@ cmd = "cmake --build build/{{ type }}"
 args = [
     { arg = "type", default = "RelWithDebInfo" },
     { arg = "ci", default = "OFF" },
-    { arg = "extra", default = "" },
 ]
 depends-on = [
-    { task = "cmake-config", args = ["{{ type }}", "{{ ci }}", "{{extra}}"] },
+    { task = "cmake-config", args = ["{{ type }}", "{{ ci }}"] },
     { task = "cmake-build", args = ["{{ type }}"] },
 ]
 
-[feature.build.tasks.unit-test]
+[feature.build.tasks.clang-tidy]
+args = [{ arg = "type", default = "RelWithDebInfo" }]
+depends-on = [{ task = "lint-cpp", args = ["{{ type }}"] }]
+
+[feature.test.tasks.unit-test]
 args = [{ arg = "type", default = "RelWithDebInfo" }]
 cmd = './build/{{ type }}/bin/unit_tests --test-dir="./tests/data"'
 
 [feature.test.tasks.integration-test]
 args = [{ arg = "type", default = "RelWithDebInfo" }]
 cmd = """
-pytest -s --log-cli-level=INFO tests/integration \
-    --executable=./build/{{ type }}/bin/clice
+pytest -s --log-cli-level=INFO --timeout=300 --timeout-method=thread \
+    tests/integration --executable=./build/{{ type }}/bin/clice
 """
 
 [feature.test.tasks.smoke-test]
@@ -117,41 +182,9 @@ args = [{ arg = "type", default = "RelWithDebInfo" }]
 depends-on = [
     { task = "unit-test", args = ["{{ type }}"] },
     { task = "integration-test", args = ["{{ type }}"] },
+    { task = "smoke-test", args = ["{{ type }}"] },
 ]
 
-# ============================================================================== #
-#                                   XMAKE                                        #
-# ============================================================================== #
-[feature.build.tasks.xmake-config]
-args = [
-    { arg = "type", default = "releasedbg" },
-    { arg = "ci", default = "n" },
-]
-cmd = "xmake config --yes --mode={{ type }} --toolchain=clang --ci={{ ci }}"
-
-[feature.build.tasks.xmake-build]
-cmd = "xmake build --verbose --diagnosis --all"
-
-[feature.build.tasks.xmake]
-args = [
-    { arg = "type", default = "releasedbg" },
-    { arg = "ci", default = "n" },
-]
-depends-on = [
-    { task = "xmake-config", args = ["{{ type }}", "{{ ci }}"] },
-    { task = "xmake-build" },
-]
-
-[feature.test.tasks.xmake-test]
-cmd = "xmake test --verbose"
-
-[feature.package.tasks.package]
-cmd = """
-xmake config --yes --toolchain=clang --mode=releasedbg \
-    --enable_test=n --dev=n --release=y && \
-xmake pack --verbose
-"""
-
 # ============================================================================== #
 #                                  HELPER TASKS                                  #
 # ============================================================================== #
@@ -171,9 +204,14 @@ gh workflow run upload-llvm.yml \
 args = ["file_name"]
 cmd = ["scripts/delete-artifacts.bash", "{{ file_name }}"]
 
+[dependencies]
+
 # ============================================================================== #
 #                             DOCS & VSCODE EXTENSION                            #
 # ============================================================================== #
+[feature.node]
+platforms = ["win-64", "linux-64", "osx-arm64", "osx-64", "linux-aarch64"]
+
 [feature.node.dependencies]
 nodejs = ">=20"
 pnpm = "*"
@@ -199,6 +237,9 @@ outputs = ["editors/vscode/node_modules/.modules.yaml"]
 # ============================================================================== #
 #                                    FORMAT                                      #
 # ============================================================================== #
+[feature.format]
+platforms = ["win-64", "linux-64", "osx-arm64", "osx-64", "linux-aarch64"]
+
 [feature.format.dependencies]
 ruff = "*"
 tombi = "*"
@@ -229,3 +270,20 @@ format = { depends-on = [
     "format-toml",
     "format-yaml"
 ] }
+
+# ============================================================================== #
+#                                     LINT                                       #
+# ============================================================================== #
+[feature.format.tasks.lint-python]
+cmd = "ruff check ."
+
+[feature.build.tasks.lint-cpp]
+args = [{ arg = "type", default = "RelWithDebInfo" }]
+cmd = "python scripts/run_clang_tidy.py build/{{ type }}"
+
+[feature.build.tasks.lint]
+args = [{ arg = "type", default = "RelWithDebInfo" }]
+depends-on = [
+    "lint-python",
+    { task = "lint-cpp", args = ["{{ type }}"] },
+]

scripts/activate_cross_linux.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+# Clear conda cross-gcc flags so host x86_64 paths don't leak into the
+# aarch64 build. conda's gcc_linux-aarch64 activation sets
+# CFLAGS/CXXFLAGS/CPPFLAGS/LDFLAGS with -isystem/-L pointing at $CONDA_PREFIX
+# (x86_64 host paths). LIBRARY_PATH from ld_impl_linux-64 likewise points at
+# host libs. Empty-string export reliably overrides conda-installed values
+# regardless of whether pixi sources or calls this script.
+export CFLAGS=
+export CXXFLAGS=
+export CPPFLAGS=
+export LDFLAGS=
+export LIBRARY_PATH=

scripts/activate_cross_macos.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+# Clear conda host flags so arm64 host paths don't leak into the x86_64-macos
+# cross build. See scripts/activate_cross_linux.sh for rationale.
+export CFLAGS=
+export CXXFLAGS=
+export CPPFLAGS=
+export LDFLAGS=
+export LIBRARY_PATH=

scripts/activate_cross_windows.bat

@@ -0,0 +1,8 @@
+@echo off
+REM Clear conda host flags so host x64 paths don't leak into the aarch64-windows
+REM cross build. See scripts/activate_cross_linux.sh for rationale.
+set "CFLAGS="
+set "CXXFLAGS="
+set "CPPFLAGS="
+set "LDFLAGS="
+set "LIBRARY_PATH="

scripts/build-llvm.py

@@ -4,6 +4,7 @@ import subprocess
 import shutil
 import argparse
 import os
+import json
 from pathlib import Path
 
 
@@ -22,6 +23,66 @@ def normalize_mode(value: str) -> str:
     )
 
 
+def build_native_tools(project_root: Path, build_dir: Path) -> Path:
+    """Build native host tablegen tools for cross-compilation.
+
+    When cross-compiling LLVM, build tools like llvm-tblgen must run on the
+    host but would otherwise be compiled for the target architecture.  This
+    function performs a minimal native build and returns the bin directory
+    containing host-runnable executables.
+    """
+    native_dir = build_dir.parent / f"{build_dir.name}-native-tools"
+    native_dir.mkdir(exist_ok=True)
+    source_dir = project_root / "llvm"
+
+    cmake_args = [
+        "-G",
+        "Ninja",
+        "-DCMAKE_BUILD_TYPE=Release",
+        "-DLLVM_ENABLE_PROJECTS=clang;clang-tools-extra",
+        "-DLLVM_TARGETS_TO_BUILD=Native",
+        "-DLLVM_DISABLE_ASSEMBLY_FILES=ON",
+        "-DCMAKE_C_FLAGS=-w",
+        "-DCMAKE_CXX_FLAGS=-w",
+    ]
+
+    if sys.platform == "win32":
+        cmake_args += [
+            "-DCMAKE_C_COMPILER=clang-cl",
+            "-DCMAKE_CXX_COMPILER=clang-cl",
+        ]
+    else:
+        cmake_args += [
+            "-DCMAKE_C_COMPILER=clang",
+            "-DCMAKE_CXX_COMPILER=clang++",
+        ]
+
+    print(f"\nConfiguring native host tools in {native_dir}...")
+    subprocess.check_call(
+        ["cmake", "-S", str(source_dir), "-B", str(native_dir)] + cmake_args
+    )
+
+    required_tools = ["llvm-tblgen", "llvm-min-tblgen", "clang-tblgen"]
+    optional_tools = ["clang-tidy-confusable-chars-gen"]
+
+    for tool in required_tools:
+        print(f"Building native {tool}...")
+        subprocess.check_call(["cmake", "--build", str(native_dir), "--target", tool])
+
+    for tool in optional_tools:
+        try:
+            print(f"Building native {tool} (optional)...")
+            subprocess.check_call(
+                ["cmake", "--build", str(native_dir), "--target", tool]
+            )
+        except subprocess.CalledProcessError:
+            print(f"  {tool} not available, skipping.")
+
+    bin_dir = native_dir / "bin"
+    print(f"Native host tools ready in {bin_dir}")
+    return bin_dir
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="Build LLVM with specific configurations."
@@ -48,6 +109,10 @@ def main():
         "--build-dir",
         help="Custom build directory (relative to project root or absolute)",
     )
+    parser.add_argument(
+        "--target-triple",
+        help="Cross-compilation target triple (e.g. x86_64-apple-darwin, aarch64-linux-gnu, aarch64-pc-windows-msvc)",
+    )
 
     args = parser.parse_args()
 
@@ -85,118 +150,46 @@ def main():
     print("--- Configuration ---")
     print(f"Mode:           {args.mode}")
     print(f"LTO:            {args.lto}")
+    print(f"Target Triple:  {args.target_triple or '(native)'}")
     print(f"Root:           {project_root}")
     print(f"Build Dir:      {build_dir}")
     print(f"Install Prefix: {install_prefix}")
     print(f"Toolchain:      {toolchain_file}")
     print("---------------------")
 
-    llvm_distribution_components = [
-        "LLVMDemangle",
-        "LLVMSupport",
-        "LLVMCore",
-        "LLVMOption",
-        "LLVMBinaryFormat",
-        "LLVMMC",
-        "LLVMMCParser",
-        "LLVMObject",
-        "LLVMProfileData",
-        "LLVMBitReader",
-        "LLVMBitstreamReader",
-        "LLVMRemarks",
-        "LLVMObjectYAML",
-        "LLVMAggressiveInstCombine",
-        "LLVMInstCombine",
-        "LLVMIRReader",
-        "LLVMTextAPI",
-        "LLVMSymbolize",
-        "LLVMDebugInfoDWARF",
-        "LLVMDebugInfoDWARFLowLevel",
-        "LLVMDebugInfoCodeView",
-        "LLVMDebugInfoGSYM",
-        "LLVMDebugInfoPDB",
-        "LLVMDebugInfoBTF",
-        "LLVMDebugInfoMSF",
-        "LLVMAsmParser",
-        "LLVMTargetParser",
-        "LLVMTransformUtils",
-        "LLVMAnalysis",
-        "LLVMScalarOpts",
-        "LLVMFrontendHLSL",
-        "LLVMFrontendOpenMP",
-        "LLVMFrontendOffloading",
-        "LLVMFrontendAtomic",
-        "LLVMFrontendDirective",
-        "LLVMWindowsDriver",
-        "clangIndex",
-        "clangAPINotes",
-        "clangAST",
-        "clangASTMatchers",
-        "clangBasic",
-        "clangDriver",
-        "clangFormat",
-        "clangFrontend",
-        "clangLex",
-        "clangParse",
-        "clangSema",
-        "clangSerialization",
-        "clangRewrite",
-        "clangAnalysis",
-        "clangEdit",
-        "clangSupport",
-        "clangStaticAnalyzerCore",
-        "clangStaticAnalyzerFrontend",
-        "clangTidy",
-        "clangTidyUtils",
-        "clangTidyAndroidModule",
-        "clangTidyAbseilModule",
-        "clangTidyAlteraModule",
-        "clangTidyBoostModule",
-        "clangTidyBugproneModule",
-        "clangTidyCERTModule",
-        "clangTidyConcurrencyModule",
-        "clangTidyCppCoreGuidelinesModule",
-        "clangTidyDarwinModule",
-        "clangTidyFuchsiaModule",
-        "clangTidyGoogleModule",
-        "clangTidyHICPPModule",
-        "clangTidyLinuxKernelModule",
-        "clangTidyLLVMModule",
-        "clangTidyLLVMLibcModule",
-        "clangTidyMiscModule",
-        "clangTidyModernizeModule",
-        "clangTidyObjCModule",
-        "clangTidyOpenMPModule",
-        "clangTidyPerformanceModule",
-        "clangTidyPortabilityModule",
-        "clangTidyReadabilityModule",
-        "clangTidyZirconModule",
-        "clangTooling",
-        "clangToolingCore",
-        "clangToolingInclusions",
-        "clangToolingInclusionsStdlib",
-        "clangToolingSyntax",
-        "clangToolingRefactoring",
-        "clangTransformer",
-        "clangCrossTU",
-        "clangAnalysisFlowSensitive",
-        "clangAnalysisFlowSensitiveModels",
-        "clangStaticAnalyzerCheckers",
-        "clangIncludeCleaner",
-        "llvm-headers",
-        "clang-headers",
-        "clang-tidy-headers",
-        "clang-resource-headers",
-    ]
+    components_path = Path(__file__).resolve().parent / "llvm-components.json"
+    with components_path.open() as f:
+        llvm_distribution_components = json.load(f)["components"]
 
     components_joined = ";".join(llvm_distribution_components)
     cmake_args = [
         "-G",
         "Ninja",
-        f"-DCMAKE_TOOLCHAIN_FILE={toolchain_file.as_posix()}",
         f"-DCMAKE_INSTALL_PREFIX={install_prefix}",
-        "-DCMAKE_C_FLAGS=-w",
-        "-DCMAKE_CXX_FLAGS=-w",
+    ]
+
+    if sys.platform == "win32":
+        # Use clang-cl (MSVC driver) on Windows so that LLVM's CMake
+        # generates correct MSVC-style linker flags for LTO, etc.
+        c_flags = "-w"
+        if args.target_triple:
+            c_flags += f" --target={args.target_triple}"
+        cmake_args += [
+            "-DCMAKE_C_COMPILER=clang-cl",
+            "-DCMAKE_CXX_COMPILER=clang-cl",
+            f"-DCMAKE_C_FLAGS={c_flags}",
+            f"-DCMAKE_CXX_FLAGS={c_flags}",
+            "-DLLVM_USE_LINKER=lld-link",
+        ]
+    else:
+        cmake_args += [
+            f"-DCMAKE_TOOLCHAIN_FILE={toolchain_file.as_posix()}",
+            "-DCMAKE_C_FLAGS=-w",
+            "-DCMAKE_CXX_FLAGS=-w",
+            "-DLLVM_USE_LINKER=lld",
+        ]
+
+    cmake_args += [
         "-DLLVM_ENABLE_ZLIB=OFF",
         "-DLLVM_ENABLE_ZSTD=OFF",
         "-DLLVM_ENABLE_LIBXML2=OFF",
@@ -231,7 +224,6 @@ def main():
         "-DCMAKE_JOB_POOL_LINK=console",
         "-DLLVM_ENABLE_PROJECTS=clang;clang-tools-extra",
         "-DLLVM_TARGETS_TO_BUILD=all",
-        "-DLLVM_USE_LINKER=lld",
         "-DLLVM_DISABLE_ASSEMBLY_FILES=ON",
         # Distribution
         f"-DLLVM_DISTRIBUTION_COMPONENTS={components_joined}",
@@ -256,8 +248,10 @@ def main():
     is_shared = "OFF"
     if args.mode == "Debug":
         cmake_args.append("-DCMAKE_BUILD_TYPE=Debug")
-        cmake_args.append("-DLLVM_USE_SANITIZER=Address")
-        is_shared = "ON"
+        # ASAN is incompatible with -MDd on Windows (clang-cl), skip it there.
+        if sys.platform != "win32":
+            cmake_args.append("-DLLVM_USE_SANITIZER=Address")
+            is_shared = "ON"
     elif args.mode == "Release":
         cmake_args.append("-DCMAKE_BUILD_TYPE=Release")
     elif args.mode == "RelWithDebInfo":
@@ -272,6 +266,24 @@ def main():
     else:
         cmake_args.append("-DLLVM_ENABLE_LTO=OFF")
 
+    if args.target_triple:
+        cmake_args.append(f"-DCLICE_TARGET_TRIPLE={args.target_triple}")
+        cmake_args.append(f"-DLLVM_HOST_TRIPLE={args.target_triple}")
+
+        # When cross-compiling, clear conda's host-platform flags so they
+        # don't leak into the target build (e.g. -L pointing to x86_64 libs).
+        # This must happen before the native-tools build too so we don't
+        # contaminate the native configure with target-arch link flags.
+        for var in ["LIBRARY_PATH", "LDFLAGS", "CFLAGS", "CXXFLAGS", "CPPFLAGS"]:
+            os.environ.pop(var, None)
+
+        # Cross-compilation needs native host tools (tablegen, etc.) that can
+        # run on the build machine.  macOS handles this transparently via
+        # Rosetta 2, but Linux and Windows require a separate native build.
+        if sys.platform != "darwin":
+            native_bin_dir = build_native_tools(project_root, build_dir)
+            cmake_args.append(f"-DLLVM_NATIVE_TOOL_DIR={native_bin_dir}")
+
     build_dir.mkdir(exist_ok=True)
 
     print(f"\nConfiguring in {build_dir}...")

scripts/llvm-components.json

@@ -0,0 +1,99 @@
+{
+  "components": [
+    "LLVMDemangle",
+    "LLVMSupport",
+    "LLVMCore",
+    "LLVMOption",
+    "LLVMBinaryFormat",
+    "LLVMMC",
+    "LLVMMCParser",
+    "LLVMObject",
+    "LLVMProfileData",
+    "LLVMBitReader",
+    "LLVMBitstreamReader",
+    "LLVMRemarks",
+    "LLVMObjectYAML",
+    "LLVMAggressiveInstCombine",
+    "LLVMInstCombine",
+    "LLVMIRReader",
+    "LLVMTextAPI",
+    "LLVMSymbolize",
+    "LLVMDebugInfoDWARF",
+    "LLVMDebugInfoDWARFLowLevel",
+    "LLVMDebugInfoCodeView",
+    "LLVMDebugInfoGSYM",
+    "LLVMDebugInfoPDB",
+    "LLVMDebugInfoBTF",
+    "LLVMDebugInfoMSF",
+    "LLVMAsmParser",
+    "LLVMTargetParser",
+    "LLVMTransformUtils",
+    "LLVMAnalysis",
+    "LLVMScalarOpts",
+    "LLVMFrontendHLSL",
+    "LLVMFrontendOpenMP",
+    "LLVMFrontendOffloading",
+    "LLVMFrontendAtomic",
+    "LLVMFrontendDirective",
+    "LLVMWindowsDriver",
+    "clangIndex",
+    "clangAPINotes",
+    "clangAST",
+    "clangASTMatchers",
+    "clangBasic",
+    "clangDriver",
+    "clangFormat",
+    "clangFrontend",
+    "clangLex",
+    "clangParse",
+    "clangSema",
+    "clangSerialization",
+    "clangRewrite",
+    "clangAnalysis",
+    "clangEdit",
+    "clangSupport",
+    "clangStaticAnalyzerCore",
+    "clangStaticAnalyzerFrontend",
+    "clangTidy",
+    "clangTidyUtils",
+    "clangTidyAndroidModule",
+    "clangTidyAbseilModule",
+    "clangTidyAlteraModule",
+    "clangTidyBoostModule",
+    "clangTidyBugproneModule",
+    "clangTidyCERTModule",
+    "clangTidyConcurrencyModule",
+    "clangTidyCppCoreGuidelinesModule",
+    "clangTidyDarwinModule",
+    "clangTidyFuchsiaModule",
+    "clangTidyGoogleModule",
+    "clangTidyHICPPModule",
+    "clangTidyLinuxKernelModule",
+    "clangTidyLLVMModule",
+    "clangTidyLLVMLibcModule",
+    "clangTidyMiscModule",
+    "clangTidyModernizeModule",
+    "clangTidyObjCModule",
+    "clangTidyOpenMPModule",
+    "clangTidyPerformanceModule",
+    "clangTidyPortabilityModule",
+    "clangTidyReadabilityModule",
+    "clangTidyZirconModule",
+    "clangTooling",
+    "clangToolingCore",
+    "clangToolingInclusions",
+    "clangToolingInclusionsStdlib",
+    "clangToolingSyntax",
+    "clangToolingRefactoring",
+    "clangTransformer",
+    "clangCrossTU",
+    "clangAnalysisFlowSensitive",
+    "clangAnalysisFlowSensitiveModels",
+    "clangStaticAnalyzerCheckers",
+    "clangIncludeCleaner",
+    "llvm-headers",
+    "clang-headers",
+    "clang-tidy-headers",
+    "clang-resource-headers"
+  ]
+}

scripts/run_clang_tidy.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Run clang-tidy in parallel on all files in compile_commands.json."""
+
+import json
+import subprocess
+import sys
+import threading
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+
+def main():
+    build_dir = sys.argv[1] if len(sys.argv) > 1 else "build/RelWithDebInfo"
+    cdb_path = Path(build_dir) / "compile_commands.json"
+
+    if not cdb_path.exists():
+        print(f"Error: {cdb_path} not found. Run cmake-config first.", file=sys.stderr)
+        sys.exit(1)
+
+    project_root = Path(__file__).resolve().parent.parent
+    src_dirs = (project_root / "src", project_root / "tests")
+
+    cdb = json.loads(cdb_path.read_text())
+    files = [
+        entry["file"]
+        for entry in cdb
+        if any(Path(entry["file"]).resolve().is_relative_to(d) for d in src_dirs)
+    ]
+    total = len(files)
+
+    lock = threading.Lock()
+    done = 0
+    failed = []
+
+    def run(file: str) -> tuple[str, int, str]:
+        result = subprocess.run(
+            ["clang-tidy", "-p", build_dir, "--quiet", file],
+            capture_output=True,
+            text=True,
+        )
+        return file, result.returncode, result.stdout + result.stderr
+
+    with ThreadPoolExecutor() as pool:
+        futures = {pool.submit(run, f): f for f in files}
+        for future in as_completed(futures):
+            file, code, output = future.result()
+            with lock:
+                done += 1
+                name = Path(file).name
+                if code != 0:
+                    failed.append(file)
+                    print(f"[{done}/{total}] FAIL {name}")
+                    if output.strip():
+                        print(output, end="")
+                else:
+                    print(f"[{done}/{total}] OK   {name}")
+
+    if failed:
+        print(f"\nclang-tidy failed on {len(failed)}/{total} files.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"\nclang-tidy passed on {total} files.")
+
+
+if __name__ == "__main__":
+    main()

scripts/setup-llvm.py

@@ -40,23 +40,52 @@ def detect_platform() -> str:
     raise RuntimeError(f"Unsupported platform: {plat}")
 
 
+def detect_arch() -> str:
+    import platform
+
+    machine = platform.machine().lower()
+    if machine in ("x86_64", "amd64"):
+        return "x64"
+    if machine in ("aarch64", "arm64"):
+        return "arm64"
+    raise RuntimeError(f"Unsupported architecture: {machine}")
+
+
 def pick_artifact(
-    manifest: list[dict], version: str, build_type: str, is_lto: bool, platform: str
+    manifest: list[dict],
+    version: str,
+    build_type: str,
+    is_lto: bool,
+    platform: str,
+    arch: str,
 ) -> dict:
     base_version = version.split("+", 1)[0]
+    saw_missing_arch = False
     for entry in manifest:
         if entry.get("version") != version:
             continue
         if entry.get("platform") != platform.lower():
             continue
+        entry_arch = entry.get("arch")
+        if entry_arch is None:
+            saw_missing_arch = True
+            continue
+        if entry_arch != arch:
+            continue
         if entry.get("build_type") != build_type:
             continue
         if bool(entry.get("lto")) != is_lto:
             continue
         return entry
+    if saw_missing_arch:
+        raise RuntimeError(
+            f"Manifest contains entries without an 'arch' field for version={base_version}, "
+            f"platform={platform}. The manifest format changed to require explicit "
+            f"architectures; regenerate it via scripts/update-llvm-version.py."
+        )
     raise RuntimeError(
         f"No matching LLVM artifact in manifest for version={base_version}, platform={platform}, "
-        f"build_type={build_type}, lto={is_lto}"
+        f"arch={arch}, build_type={build_type}, lto={is_lto}"
     )
 
 
@@ -264,6 +293,14 @@ def main() -> None:
     parser.add_argument("--install-path")
     parser.add_argument("--enable-lto", action="store_true")
     parser.add_argument("--offline", action="store_true")
+    parser.add_argument(
+        "--target-platform",
+        help="Override platform for cross-compilation (e.g. macosx, linux, windows)",
+    )
+    parser.add_argument(
+        "--target-arch",
+        help="Override architecture for cross-compilation (e.g. x64, arm64)",
+    )
     parser.add_argument("--output", required=True)
     args = parser.parse_args()
 
@@ -275,8 +312,11 @@ def main() -> None:
     )
     token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
     build_type = args.build_type
-    platform_name = detect_platform()
-    log(f"Platform detected: {platform_name}, normalized build type: {build_type}")
+    platform_name = args.target_platform if args.target_platform else detect_platform()
+    arch_name = args.target_arch if args.target_arch else detect_arch()
+    log(
+        f"Platform: {platform_name}, arch: {arch_name}, normalized build type: {build_type}"
+    )
     manifest = read_manifest(Path(args.manifest))
 
     binary_dir = Path(args.binary_dir).resolve()
@@ -304,7 +344,12 @@ def main() -> None:
     if install_path is None:
         needs_install = True
         artifact = pick_artifact(
-            manifest, args.version, build_type, args.enable_lto, platform_name
+            manifest,
+            args.version,
+            build_type,
+            args.enable_lto,
+            platform_name,
+            arch_name,
         )
         log(f"Selected artifact: {artifact.get('filename')} for download")
         filename = artifact["filename"]
@@ -317,7 +362,12 @@ def main() -> None:
         install_path = install_root
     elif needs_install:
         artifact = pick_artifact(
-            manifest, args.version, build_type, args.enable_lto, platform_name
+            manifest,
+            args.version,
+            build_type,
+            args.enable_lto,
+            platform_name,
+            arch_name,
         )
         log(f"Selected artifact: {artifact.get('filename')} for download")
         filename = artifact["filename"]

scripts/update-llvm-version.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def copy_manifest(src: Path, dest: Path) -> None:
+    text = src.read_text(encoding="utf-8")
+
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as err:
+        print(f"Error: {src} is not valid JSON: {err}", file=sys.stderr)
+        sys.exit(1)
+
+    if not isinstance(data, list) or len(data) == 0:
+        print(f"Error: {src} must be a non-empty JSON array", file=sys.stderr)
+        sys.exit(1)
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with dest.open("w", encoding="utf-8") as handle:
+        json.dump(data, handle, indent=2)
+        handle.write("\n")
+
+    print(f"Copied manifest: {src} -> {dest} ({len(data)} entries)")
+
+
+def update_package_cmake(path: Path, version: str) -> None:
+    text = path.read_text(encoding="utf-8")
+
+    pattern = r'setup_llvm\("[^"]*"\)'
+    matches = re.findall(pattern, text)
+
+    if len(matches) == 0:
+        print(f"Error: no setup_llvm(...) call found in {path}", file=sys.stderr)
+        sys.exit(1)
+
+    if len(matches) > 1:
+        print(
+            f"Error: expected exactly 1 setup_llvm(...) call in {path}, "
+            f"found {len(matches)}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    old_call = matches[0]
+    new_call = f'setup_llvm("{version}")'
+
+    if old_call == new_call:
+        print(f"Version in {path} is already {version}, no change needed")
+        return
+
+    updated = text.replace(old_call, new_call)
+    path.write_text(updated, encoding="utf-8")
+    print(f"Updated {path}: {old_call} -> {new_call}")
+
+
+def check_package_cmake(path: Path) -> None:
+    """Verify package.cmake has exactly one setup_llvm(...) call that the
+    update script can rewrite. Used by CI to catch drift before the next bump."""
+    text = path.read_text(encoding="utf-8")
+    matches = re.findall(r'setup_llvm\("[^"]*"\)', text)
+    if len(matches) == 0:
+        print(f"Error: no setup_llvm(...) call found in {path}", file=sys.stderr)
+        sys.exit(1)
+    if len(matches) > 1:
+        print(
+            f"Error: expected exactly 1 setup_llvm(...) call in {path}, "
+            f"found {len(matches)}: {matches}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    print(f"OK: {path} has a single setup_llvm(...) call: {matches[0]}")
+
+
+def check_manifest(path: Path) -> None:
+    """Verify the manifest is a well-formed non-empty array with required fields."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as err:
+        print(f"Error: {path} is not valid JSON: {err}", file=sys.stderr)
+        sys.exit(1)
+    if not isinstance(data, list) or len(data) == 0:
+        print(f"Error: {path} must be a non-empty JSON array", file=sys.stderr)
+        sys.exit(1)
+    required = ("version", "platform", "arch", "build_type", "filename", "sha256")
+    for idx, entry in enumerate(data):
+        missing = [k for k in required if k not in entry]
+        if missing:
+            print(
+                f"Error: {path} entry {idx} is missing fields: {missing}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+    print(f"OK: {path} has {len(data)} well-formed entries")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Update LLVM version references in the clice project."
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Validate existing state without modifying files (for CI drift checks)",
+    )
+    parser.add_argument(
+        "--version",
+        help="New LLVM version string (e.g. 21.2.0); required unless --check",
+    )
+    parser.add_argument(
+        "--manifest-src",
+        help="Path to the source llvm-manifest.json; required unless --check",
+    )
+    parser.add_argument(
+        "--manifest-dest",
+        required=True,
+        help="Path to destination manifest (e.g. config/llvm-manifest.json)",
+    )
+    parser.add_argument(
+        "--package-cmake",
+        required=True,
+        help="Path to cmake/package.cmake",
+    )
+    args = parser.parse_args()
+
+    manifest_dest = Path(args.manifest_dest)
+    package_cmake = Path(args.package_cmake)
+
+    if not package_cmake.is_file():
+        print(f"Error: package.cmake not found: {package_cmake}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.check:
+        check_package_cmake(package_cmake)
+        check_manifest(manifest_dest)
+        print("Done (check mode).")
+        return
+
+    if not args.version or not args.manifest_src:
+        print(
+            "Error: --version and --manifest-src are required unless --check is set",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    manifest_src = Path(args.manifest_src)
+    if not manifest_src.is_file():
+        print(f"Error: manifest source not found: {manifest_src}", file=sys.stderr)
+        sys.exit(1)
+
+    copy_manifest(manifest_src, manifest_dest)
+    update_package_cmake(package_cmake, args.version)
+
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()

scripts/upload-llvm.py

@@ -27,6 +27,15 @@ def parse_platform(name: str) -> str:
     raise ValueError(f"Unable to determine platform from filename: {name}")
 
 
+def parse_arch(name: str) -> str:
+    lowered = name.lower()
+    if lowered.startswith("aarch64-") or lowered.startswith("arm64-"):
+        return "arm64"
+    if lowered.startswith("x64-") or lowered.startswith("x86_64-"):
+        return "x64"
+    raise ValueError(f"Unable to determine arch from filename: {name}")
+
+
 def parse_build_type(name: str) -> str:
     lowered = name.lower()
     if "debug" in lowered:
@@ -43,6 +52,7 @@ def build_metadata_entry(path: Path, version: str) -> dict:
         "lto": "-lto" in filename.lower(),
         "asan": "-asan" in filename.lower(),
         "platform": parse_platform(filename),
+        "arch": parse_arch(filename),
         "build_type": parse_build_type(filename),
     }
 

scripts/validate-llvm-components.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+Validate the LLVM distribution component list against the actual LLVM source tree.
+
+Scans the LLVM source for CMake library targets and compares them against
+a components JSON file to detect stale or misspelled entries.
+"""
+
+import argparse
+import difflib
+import json
+import re
+import sys
+from pathlib import Path
+
+
+# CMake function calls that define library targets.
+# The captured group uses [^\s)]+  to grab the target name without
+# trailing parentheses or whitespace.
+LLVM_LIB_PATTERNS = [
+    re.compile(r"add_llvm_component_library\(\s*([^\s)]+)"),
+    re.compile(r"add_llvm_library\(\s*([^\s)]+)"),
+]
+
+CLANG_LIB_PATTERNS = [
+    re.compile(r"add_clang_library\(\s*([^\s)]+)"),
+]
+
+# Header-only / custom install targets.
+HEADER_PATTERNS = [
+    re.compile(r"add_llvm_install_targets\(\s*([^\s)]+)"),
+    re.compile(r"add_custom_target\(\s*([^\s)]+)"),
+    re.compile(r"add_library\(\s*([^\s)]+)"),
+]
+
+# Targets we recognise as header-only distribution components.
+KNOWN_HEADER_TARGETS = {
+    "llvm-headers",
+    "clang-headers",
+    "clang-tidy-headers",
+    "clang-resource-headers",
+}
+
+
+def scan_targets(directory: Path, patterns: list[re.Pattern]) -> set[str]:
+    """Recursively scan *directory* for CMakeLists.txt files and extract target names."""
+    targets: set[str] = set()
+    if not directory.is_dir():
+        return targets
+    for cmake_file in directory.rglob("CMakeLists.txt"):
+        text = cmake_file.read_text(errors="replace")
+        for pattern in patterns:
+            for match in pattern.finditer(text):
+                targets.add(match.group(1))
+    return targets
+
+
+def scan_header_targets(llvm_src: Path) -> set[str]:
+    """Scan for well-known header / custom-install targets across the tree."""
+    found: set[str] = set()
+    for cmake_file in llvm_src.rglob("CMakeLists.txt"):
+        text = cmake_file.read_text(errors="replace")
+        for pattern in HEADER_PATTERNS:
+            for match in pattern.finditer(text):
+                name = match.group(1)
+                if name in KNOWN_HEADER_TARGETS:
+                    found.add(name)
+    return found
+
+
+def collect_source_targets(llvm_src: Path) -> set[str]:
+    """Return the full set of library / header targets found in the LLVM source tree."""
+    targets: set[str] = set()
+    targets |= scan_targets(llvm_src / "llvm" / "lib", LLVM_LIB_PATTERNS)
+    targets |= scan_targets(llvm_src / "clang" / "lib", CLANG_LIB_PATTERNS)
+    targets |= scan_targets(llvm_src / "clang-tools-extra", CLANG_LIB_PATTERNS)
+    targets |= scan_header_targets(llvm_src)
+    return targets
+
+
+def load_components(path: Path) -> list[str]:
+    with path.open("r", encoding="utf-8") as handle:
+        data = json.load(handle)
+    if isinstance(data, dict):
+        data = data.get("components", [])
+    if not isinstance(data, list) or not data:
+        print(f"Error: no component list found in {path}", file=sys.stderr)
+        sys.exit(1)
+    return data
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Validate LLVM distribution components against the source tree."
+    )
+    parser.add_argument(
+        "--llvm-src",
+        required=True,
+        help="Path to the llvm-project source root",
+    )
+    parser.add_argument(
+        "--components-file",
+        required=True,
+        help="Path to llvm-components.json",
+    )
+    args = parser.parse_args()
+
+    llvm_src = Path(args.llvm_src).expanduser().resolve()
+    components_file = Path(args.components_file).expanduser().resolve()
+
+    if not llvm_src.is_dir():
+        print(f"Error: LLVM source directory not found: {llvm_src}")
+        sys.exit(1)
+
+    if not (llvm_src / "llvm" / "CMakeLists.txt").exists():
+        print(f"Error: {llvm_src} does not look like an llvm-project root.")
+        sys.exit(1)
+
+    if not components_file.is_file():
+        print(f"Error: components file not found: {components_file}")
+        sys.exit(1)
+
+    components = load_components(components_file)
+    source_targets = collect_source_targets(llvm_src)
+
+    print(f"Found {len(source_targets)} targets in LLVM source tree")
+    print(f"Components file lists {len(components)} entries")
+
+    # Check for components that are missing from the source tree.
+    missing: list[tuple[str, list[str]]] = []
+    for name in components:
+        if name not in source_targets:
+            suggestions = difflib.get_close_matches(
+                name, source_targets, n=3, cutoff=0.6
+            )
+            missing.append((name, suggestions))
+
+    if missing:
+        print(f"\nError: {len(missing)} component(s) not found in the source tree:\n")
+        for name, suggestions in missing:
+            print(f"  - {name}")
+            if suggestions:
+                print(f"    Did you mean: {', '.join(suggestions)}?")
+        sys.exit(1)
+
+    # Warn about source targets not present in the component list.
+    component_set = set(components)
+    new_targets = sorted(source_targets - component_set - KNOWN_HEADER_TARGETS)
+    # Filter to targets that follow LLVM/Clang naming conventions to reduce noise.
+    noteworthy = [t for t in new_targets if t.startswith(("LLVM", "clang", "Clang"))]
+    if noteworthy:
+        print(
+            f"\nWarning: {len(noteworthy)} target(s) in source not listed in components:"
+        )
+        for name in noteworthy:
+            print(f"  + {name}")
+
+    print("\nAll components validated successfully.")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

src/clice.cc

@@ -1,64 +1,122 @@
+#include <csignal>
 #include <cstdint>
 #include <iostream>
 #include <print>
 #include <string>
 
-#include "eventide/async/async.h"
-#include "eventide/deco/deco.h"
-#include "eventide/ipc/peer.h"
-#include "eventide/ipc/recording_transport.h"
-#include "eventide/ipc/transport.h"
-#include "server/master_server.h"
-#include "server/stateful_worker.h"
-#include "server/stateless_worker.h"
+#include "server/service/agentic.h"
+#include "server/service/master_server.h"
+#include "server/worker/stateful_worker.h"
+#include "server/worker/stateless_worker.h"
 #include "support/logging.h"
 
+#include "kota/deco/deco.h"
+
 namespace clice {
 
+using kota::deco::decl::KVStyle;
+
 struct Options {
-    DecoKV(names = {"--mode"};
-           help = "Running mode: pipe, socket, stateless-worker, stateful-worker";
-           required = false;)
+    DecoKV(
+        style = KVStyle::JoinedOrSeparate,
+        help =
+            "Running mode: pipe, socket, daemon, relay, agentic, stateless-worker, stateful-worker",
+        required = false)
     <std::string> mode;
 
-    DecoKV(names = {"--host"}; help = "Socket mode address"; required = false;)
+    DecoKV(style = KVStyle::JoinedOrSeparate, help = "Socket mode address", required = false)
     <std::string> host = "127.0.0.1";
 
-    DecoKV(names = {"--port"}; help = "Socket mode port"; required = false;)
-    <int> port = 50051;
+    DecoKV(style = KVStyle::JoinedOrSeparate,
+           help = "Agentic TCP port (0 = disabled)",
+           required = false)
+    <int> port = 0;
 
-    DecoKV(names = {"--stateful-worker-count"}; help = "Number of stateful workers";
-           required = false;)
-    <std::uint32_t> stateful_worker_count;
-
-    DecoKV(names = {"--stateless-worker-count"}; help = "Number of stateless workers";
-           required = false;)
-    <std::uint32_t> stateless_worker_count;
-
-    DecoKV(names = {"--worker-memory-limit"}; help = "Memory limit per stateful worker (bytes)";
-           required = false;)
-    <std::uint64_t> worker_memory_limit;
-
-    DecoKV(names = {"--log-level"}; help = "Log level: trace, debug, info, warn, error, off";
-           required = false;)
+    DecoKV(style = KVStyle::JoinedOrSeparate,
+           names = {"--log-level", "--log-level="},
+           help = "Log level: trace, debug, info, warn, error, off",
+           required = false)
     <std::string> log_level = "info";
 
-    DecoKV(names = {"--record"}; help = "Record LSP input to file for replay testing";
-           required = false;)
+    DecoKV(style = KVStyle::JoinedOrSeparate,
+           help = "Record LSP input to file for replay testing",
+           required = false)
     <std::string> record;
 
-    DecoFlag(names = {"-h", "--help"}; help = "Show help message"; required = false;)
+    DecoKV(style = KVStyle::JoinedOrSeparate,
+           help = "File path for agentic queries",
+           required = false)
+    <std::string> path;
+
+    DecoKV(
+        style = KVStyle::JoinedOrSeparate,
+        help =
+            "Agentic method (compileCommand, symbolSearch, definition, references, "
+            "documentSymbols, readSymbol, callGraph, typeHierarchy, projectFiles, "
+            "fileDeps, impactAnalysis, status, shutdown)",
+        required = false)
+    <std::string> method;
+
+    DecoKV(style = KVStyle::JoinedOrSeparate,
+           help = "Symbol name for agentic queries",
+           required = false)
+    <std::string> name;
+
+    DecoKV(style = KVStyle::JoinedOrSeparate,
+           help = "Search query for symbolSearch",
+           required = false)
+    <std::string> query;
+
+    DecoKV(style = KVStyle::JoinedOrSeparate,
+           help = "Line number for position-based lookup",
+           required = false)
+    <int> line;
+
+    DecoKV(style = KVStyle::JoinedOrSeparate,
+           help = "Direction: callers/callees or supertypes/subtypes",
+           required = false)
+    <std::string> direction;
+
+    DecoKV(style = KVStyle::JoinedOrSeparate,
+           help = "Unix domain socket path for daemon mode",
+           required = false)
+    <std::string> socket;
+
+    DecoKV(style = KVStyle::JoinedOrSeparate,
+           help = "Workspace root directory for daemon mode",
+           required = false)
+    <std::string> workspace;
+
+    // Internal options (passed from master to worker processes)
+    DecoKV(style = KVStyle::JoinedOrSeparate,
+           names = {"--worker-memory-limit", "--worker-memory-limit="},
+           required = false)
+    <std::uint64_t> worker_memory_limit;
+
+    DecoKV(style = KVStyle::JoinedOrSeparate,
+           names = {"--worker-name", "--worker-name="},
+           required = false)
+    <std::string> worker_name;
+
+    DecoKV(style = KVStyle::JoinedOrSeparate, names = {"--log-dir", "--log-dir="}, required = false)
+    <std::string> log_dir;
+
+    DecoFlag(names = {"-h", "--help"}, help = "Show help message", required = false)
     help;
 
-    DecoFlag(names = {"-v", "--version"}; help = "Show version"; required = false;)
+    DecoFlag(names = {"-v", "--version"}, help = "Show version", required = false)
     version;
 };
 
 }  // namespace clice
 
 int main(int argc, const char** argv) {
-    auto args = deco::util::argvify(argc, argv);
-    auto result = deco::cli::parse<clice::Options>(args);
+#ifndef _WIN32
+    signal(SIGPIPE, SIG_IGN);
+#endif
+
+    auto args = kota::deco::util::argvify(argc, argv);
+    auto result = kota::deco::cli::parse<clice::Options>(args);
 
     if(!result.has_value()) {
         LOG_ERROR("{}", result.error().message);
@@ -68,7 +126,7 @@ int main(int argc, const char** argv) {
     auto& opts = result->options;
 
     if(opts.help.value_or(false)) {
-        deco::cli::write_usage_for<clice::Options>(std::cout, "clice [OPTIONS]");
+        kota::deco::cli::write_usage_for<clice::Options>(std::cout, "clice [OPTIONS]");
         return 0;
     }
 
@@ -93,92 +151,70 @@ int main(int argc, const char** argv) {
         return 1;
     }
 
-    std::string self_path = argv[0];
-
     auto& mode = *opts.mode;
 
+    auto worker_name = opts.worker_name.value_or("");
+    auto log_dir = opts.log_dir.value_or("");
+
     if(mode == "stateless-worker") {
-        return clice::run_stateless_worker_mode();
+        return clice::run_stateless_worker_mode(worker_name.empty() ? "stateless-worker"
+                                                                    : worker_name,
+                                                log_dir);
     }
 
     if(mode == "stateful-worker") {
         auto mem_limit = opts.worker_memory_limit.value_or(4ULL * 1024 * 1024 * 1024);
-        return clice::run_stateful_worker_mode(mem_limit);
+        return clice::run_stateful_worker_mode(mem_limit,
+                                               worker_name.empty() ? "stateful-worker"
+                                                                   : worker_name,
+                                               log_dir);
     }
 
-    if(mode == "pipe") {
-        clice::logging::stderr_logger("master", clice::logging::options);
+    if(mode == "pipe" || mode == "socket") {
+        clice::ServerOptions server_opts;
+        server_opts.mode = mode;
+        server_opts.host = opts.host.value_or("127.0.0.1");
+        server_opts.port = opts.port.value_or(0);
+        server_opts.self_path = argv[0];
+        server_opts.record = opts.record.value_or("");
+        return clice::run_server_mode(server_opts);
+    }
 
-        namespace et = eventide;
-        et::event_loop loop;
-
-        auto transport = et::ipc::StreamTransport::open_stdio(loop);
-        if(!transport) {
-            LOG_ERROR("failed to open stdio transport");
+    if(mode == "daemon") {
+        auto workspace = opts.workspace.value_or("");
+        if(workspace.empty()) {
+            LOG_ERROR("--workspace is required for daemon mode");
             return 1;
         }
 
-        std::unique_ptr<et::ipc::Transport> final_transport = std::move(*transport);
-        if(opts.record.has_value()) {
-            final_transport =
-                std::make_unique<et::ipc::RecordingTransport>(std::move(final_transport),
-                                                              *opts.record);
-        }
-
-        et::ipc::JsonPeer peer(loop, std::move(final_transport));
-        clice::MasterServer server(loop, peer, std::move(self_path));
-        server.register_handlers();
-
-        loop.schedule(peer.run());
-        loop.run();
-        return 0;
+        clice::DaemonOptions daemon_opts;
+        daemon_opts.socket_path = opts.socket.value_or("");
+        daemon_opts.workspace = std::move(workspace);
+        daemon_opts.self_path = argv[0];
+        return clice::run_daemon_mode(daemon_opts);
     }
 
-    if(mode == "socket") {
-        clice::logging::stderr_logger("master", clice::logging::options);
-
-        namespace et = eventide;
-        et::event_loop loop;
-
-        auto host = opts.host.value_or("127.0.0.1");
-        auto port = opts.port.value_or(50051);
-
-        auto acceptor = et::tcp::listen(host, port, {}, loop);
-        if(!acceptor) {
-            LOG_ERROR("failed to listen on {}:{}", host, port);
+    if(mode == "agentic") {
+        auto port = opts.port.value_or(0);
+        if(port <= 0) {
+            LOG_ERROR("--port is required for agentic mode");
             return 1;
         }
+        clice::AgenticQueryOptions aq;
+        aq.host = opts.host.value_or("127.0.0.1");
+        aq.port = port;
+        aq.method = opts.method.value_or("compileCommand");
+        aq.path = opts.path.value_or("");
+        aq.name = opts.name.value_or("");
+        aq.query = opts.query.value_or("");
+        aq.line = opts.line.value_or(0);
+        aq.direction = opts.direction.value_or("");
+        return clice::run_agentic_mode(aq);
+    }
 
-        LOG_INFO("Listening on {}:{} ...", host, port);
-
-        auto task = [&]() -> et::task<> {
-            auto client = co_await acceptor->accept();
-            if(!client.has_value()) {
-                LOG_ERROR("failed to accept connection");
-                loop.stop();
-                co_return;
-            }
-
-            LOG_INFO("Client connected");
-
-            std::unique_ptr<et::ipc::Transport> transport =
-                std::make_unique<et::ipc::StreamTransport>(std::move(client.value()));
-            if(opts.record.has_value()) {
-                transport = std::make_unique<et::ipc::RecordingTransport>(std::move(transport),
-                                                                          *opts.record);
-            }
-            et::ipc::JsonPeer peer(loop, std::move(transport));
-            clice::MasterServer server(loop, peer, std::string(self_path));
-            server.register_handlers();
-
-            co_await peer.run();
-            peer.close();
-            loop.stop();
-        };
-
-        loop.schedule(task());
-        loop.run();
-        return 0;
+    if(mode == "relay") {
+        auto socket = opts.socket.value_or("");
+        return clice::run_relay_mode(socket);
     }
 
     LOG_ERROR("unknown mode '{}'", mode);

src/command/command.cpp

@@ -23,6 +23,44 @@ namespace ranges = std::ranges;
 
 }  // namespace
 
+std::vector<const char*> CompileCommand::to_argv() const {
+    std::vector<const char*> argv;
+    argv.reserve(resolved.flags.size() + 4);
+
+    if(resolved.is_cc1 && source_file) {
+        // cc1 mode requires TWO file-related arguments (both are needed):
+        //   1. -main-file-name <basename>  — used by clang for diagnostics/debug info
+        //   2. <source_file> at the end    — the actual input file path
+        // These are NOT duplicates: (1) is just the basename, (2) is the full path.
+        for(std::size_t i = 0; i < resolved.flags.size(); ++i) {
+            argv.push_back(resolved.flags[i]);
+            if(resolved.flags[i] == llvm::StringRef("-cc1")) {
+                argv.push_back("-main-file-name");
+                // path::filename returns a suffix of source_file (a pointer into
+                // the same buffer), so .data() is null-terminated because source_file is.
+                argv.push_back(path::filename(source_file).data());
+            }
+        }
+    } else {
+        argv.insert(argv.end(), resolved.flags.begin(), resolved.flags.end());
+    }
+
+    if(source_file) {
+        argv.push_back(source_file);
+    }
+    return argv;
+}
+
+std::vector<std::string> CompileCommand::to_string_argv() const {
+    auto argv = to_argv();
+    std::vector<std::string> result;
+    result.reserve(argv.size());
+    for(auto* arg: argv) {
+        result.emplace_back(arg);
+    }
+    return result;
+}
+
 CompilationDatabase::CompilationDatabase() = default;
 
 CompilationDatabase::~CompilationDatabase() = default;
@@ -329,8 +367,8 @@ std::size_t CompilationDatabase::load(llvm::StringRef path) {
     return entries.size();
 }
 
-llvm::SmallVector<CompilationContext> CompilationDatabase::lookup(llvm::StringRef file,
-                                                                  const CommandOptions& options) {
+llvm::SmallVector<CompileCommand> CompilationDatabase::lookup(llvm::StringRef file,
+                                                              const CommandOptions& options) {
     auto path_id = paths.intern(file);
     auto matched = find_entries(path_id);
 
@@ -338,17 +376,18 @@ llvm::SmallVector<CompilationContext> CompilationDatabase::lookup(llvm::StringRe
         render_arg_to([&](llvm::StringRef s) { out.push_back(strings.save(s).data()); }, arg);
     };
 
-    /// Build one CompilationContext from a single CompilationInfo.
-    auto build_context = [&](object_ptr<CompilationInfo> info) -> CompilationContext {
+    /// Build one CompileCommand from a single CompilationInfo.
+    auto build_command = [&](object_ptr<CompilationInfo> info) -> CompileCommand {
         llvm::StringRef directory = info->directory;
-        std::vector<const char*> arguments;
+        std::vector<const char*> flags;
+        bool is_cc1 = false;
 
         auto append_arg = [&](llvm::StringRef s) {
-            arguments.emplace_back(strings.save(s).data());
+            flags.emplace_back(strings.save(s).data());
         };
 
         auto append_args = [&](llvm::ArrayRef<const char*> args) {
-            arguments.insert(arguments.end(), args.begin(), args.end());
+            flags.insert(flags.end(), args.begin(), args.end());
         };
 
         if(options.query_toolchain) {
@@ -361,23 +400,20 @@ llvm::SmallVector<CompilationContext> CompilationDatabase::lookup(llvm::StringRe
                 append_args(info->canonical->arguments);
                 append_args(info->patch);
             } else {
-                arguments.assign(cached.begin(), cached.end());
-                // TODO: add an assertion that the last arg is the temp source
-                // file (e.g., contains "query-toolchain") to guard against
-                // future changes in clang cc1 argument ordering.
-                arguments.pop_back();  // remove temp source file
+                flags.assign(cached.begin(), cached.end());
+                flags.pop_back();  // remove temp source file
 
                 // Replace resource dir if needed.
                 if(!resource_dir().empty()) {
                     llvm::StringRef old_resource_dir;
-                    for(std::size_t i = 0; i + 1 < arguments.size(); ++i) {
-                        if(arguments[i] == llvm::StringRef("-resource-dir")) {
-                            old_resource_dir = arguments[i + 1];
+                    for(std::size_t i = 0; i + 1 < flags.size(); ++i) {
+                        if(flags[i] == llvm::StringRef("-resource-dir")) {
+                            old_resource_dir = flags[i + 1];
                             break;
                         }
                     }
                     if(!old_resource_dir.empty() && old_resource_dir != resource_dir()) {
-                        for(auto& arg: arguments) {
+                        for(auto& arg: flags) {
                             llvm::StringRef s(arg);
                             if(s.starts_with(old_resource_dir)) {
                                 auto replaced =
@@ -390,39 +426,42 @@ llvm::SmallVector<CompilationContext> CompilationDatabase::lookup(llvm::StringRe
 
                 append_args(info->patch);
 
-                // Fix -main-file-name to match the actual file.
-                bool next_main_file = false;
-                for(auto& arg: arguments) {
-                    if(arg == llvm::StringRef("-main-file-name")) {
-                        next_main_file = true;
+                // Strip -main-file-name and its value from flags (to_argv() will
+                // re-inject it with the correct basename when is_cc1 is set).
+                std::vector<const char*> cleaned;
+                cleaned.reserve(flags.size());
+                for(std::size_t i = 0; i < flags.size(); ++i) {
+                    if(flags[i] == llvm::StringRef("-main-file-name") && i + 1 < flags.size()) {
+                        ++i;  // skip the value
                         continue;
                     }
-                    if(next_main_file) {
-                        arg = strings.save(path::filename(file)).data();
-                        next_main_file = false;
-                    }
+                    cleaned.push_back(flags[i]);
                 }
-            }
+                flags = std::move(cleaned);
 
-            // Inject our resource dir if not already present.
-            if(!resource_dir().empty()) {
-                bool has_resource_dir = false;
-                for(auto& arg: arguments) {
-                    if(arg == llvm::StringRef("-resource-dir")) {
-                        has_resource_dir = true;
-                        break;
-                    }
-                }
-                if(!has_resource_dir) {
-                    append_arg("-resource-dir");
-                    append_arg(resource_dir());
-                }
+                // Detect cc1 mode (search rather than assuming index).
+                is_cc1 = ranges::contains(flags, llvm::StringRef("-cc1"));
             }
         } else {
             append_args(info->canonical->arguments);
             append_args(info->patch);
         }
 
+        // Inject our resource dir if not already present.
+        if(options.inject_resource_dir && !resource_dir().empty()) {
+            bool has_resource_dir = false;
+            for(auto& arg: flags) {
+                if(arg == llvm::StringRef("-resource-dir")) {
+                    has_resource_dir = true;
+                    break;
+                }
+            }
+            if(!has_resource_dir) {
+                append_arg("-resource-dir");
+                append_arg(resource_dir());
+            }
+        }
+
         // Apply remove filter.
         if(!options.remove.empty()) {
             using Arg = std::unique_ptr<llvm::opt::Arg>;
@@ -440,12 +479,12 @@ llvm::SmallVector<CompilationContext> CompilationDatabase::lookup(llvm::StringRe
             };
             std::ranges::sort(remove_args, {}, get_id);
 
-            auto saved_args = std::move(arguments);
-            arguments.clear();
-            arguments.push_back(saved_args.front());
+            auto saved_flags = std::move(flags);
+            flags.clear();
+            flags.push_back(saved_flags.front());
 
             parser->parse(
-                llvm::ArrayRef(saved_args).drop_front(),
+                llvm::ArrayRef(saved_flags).drop_front(),
                 [&](Arg arg) {
                     auto id = arg->getOption().getID();
                     auto range = std::ranges::equal_range(remove_args, id, {}, get_id);
@@ -461,7 +500,7 @@ llvm::SmallVector<CompilationContext> CompilationDatabase::lookup(llvm::StringRe
                             return;
                         }
                     }
-                    render_arg(arguments, *arg);
+                    render_arg(flags, *arg);
                 },
                 [](int, int) {});
         }
@@ -470,26 +509,34 @@ llvm::SmallVector<CompilationContext> CompilationDatabase::lookup(llvm::StringRe
             append_arg(arg);
         }
 
-        arguments.emplace_back(paths.resolve(path_id).data());
-        return CompilationContext(directory, std::move(arguments));
+        return CompileCommand{
+            ResolvedFlags{directory, std::move(flags), is_cc1},
+            paths.resolve(path_id).data()
+        };
     };
 
-    llvm::SmallVector<CompilationContext> results;
+    llvm::SmallVector<CompileCommand> results;
 
     if(!matched.empty()) {
         for(auto& entry: matched) {
-            results.push_back(build_context(entry.info));
+            results.push_back(build_command(entry.info));
         }
     } else {
         // No matching entry — synthesize a default command.
-        std::vector<const char*> arguments;
+        std::vector<const char*> flags;
         if(file.ends_with(".cpp") || file.ends_with(".hpp") || file.ends_with(".cc")) {
-            arguments = {"clang++", "-std=c++20"};
+            flags = {"clang++", "-std=c++20"};
         } else {
-            arguments = {"clang"};
+            flags = {"clang"};
         }
-        arguments.emplace_back(paths.resolve(path_id).data());
-        results.push_back(CompilationContext({}, std::move(arguments)));
+        if(options.inject_resource_dir && !resource_dir().empty()) {
+            flags.push_back(strings.save("-resource-dir").data());
+            flags.push_back(strings.save(resource_dir()).data());
+        }
+        results.push_back(CompileCommand{
+            ResolvedFlags{{}, std::move(flags), false},
+            paths.resolve(path_id).data()
+        });
     }
 
     return results;
@@ -513,8 +560,8 @@ SearchConfig CompilationDatabase::lookup_search_config(llvm::StringRef file,
     }
 
     auto results = lookup(file, options);
-    auto& ctx = results.front();
-    auto config = extract_search_config(ctx.arguments, ctx.directory);
+    auto& cmd = results.front();
+    auto config = extract_search_config(cmd.to_argv(), cmd.resolved.directory);
 
     if(cacheable) {
         auto key = ConfigCacheKey{matched.front().info.ptr, options_bits(options)};
@@ -650,6 +697,11 @@ std::uint32_t CompilationDatabase::intern_path(llvm::StringRef path) {
     return paths.intern(path);
 }
 
+bool CompilationDatabase::has_entry(llvm::StringRef file) {
+    auto path_id = paths.intern(file);
+    return !find_entries(path_id).empty();
+}
+
 llvm::ArrayRef<CompilationEntry> CompilationDatabase::get_entries() const {
     return entries;
 }

src/command/command.h

@@ -29,6 +29,11 @@ struct CommandOptions {
     /// Set true in unittests to avoid cluttering test output.
     bool suppress_logging = false;
 
+    /// Inject our resource dir into the flags if not already present.
+    /// Enabled by default so clang tools always use matching builtin headers.
+    /// Disable in unit tests that assert exact argument counts.
+    bool inject_resource_dir = true;
+
     /// Extra arguments to remove from the original command line.
     llvm::ArrayRef<std::string> remove;
 
@@ -36,12 +41,35 @@ struct CommandOptions {
     llvm::ArrayRef<std::string> append;
 };
 
-struct CompilationContext {
+/// File-independent compilation flags (shareable, suitable as cache key input).
+/// Does NOT contain source file path or -main-file-name.
+struct ResolvedFlags {
     /// The working directory of compilation.
     llvm::StringRef directory;
 
-    /// The compilation arguments.
-    std::vector<const char*> arguments;
+    /// All flags excluding source file path and -main-file-name.
+    std::vector<const char*> flags;
+
+    /// Whether flags come from toolchain query (cc1 mode).
+    /// When true, flags are cc1 frontend args (resolved clang binary + "-cc1" + ...),
+    /// NOT the original driver command. to_argv() scans for "-cc1" in flags and
+    /// inserts -main-file-name immediately after it.
+    bool is_cc1 = false;
+};
+
+/// Compilation command = resolved flags + source file identity.
+struct CompileCommand {
+    ResolvedFlags resolved;
+
+    /// Interned, pointer-stable. Must be null-terminated (required by to_argv()
+    /// and path::filename().data() which relies on the suffix being null-terminated).
+    const char* source_file = nullptr;
+
+    /// Produce full argv: flags + [-main-file-name <basename> if cc1] + source_file.
+    std::vector<const char*> to_argv() const;
+
+    /// Convenience: to_argv() converted to vector<string>.
+    std::vector<std::string> to_string_argv() const;
 };
 
 /// Shared compiler identity — driver + all semantics-affecting flags.
@@ -174,10 +202,10 @@ public:
     /// but toolchain cache survives. Returns the number of entries loaded.
     std::size_t load(llvm::StringRef path);
 
-    /// Lookup the compilation contexts for a file. A file may have multiple
+    /// Lookup the compile commands for a file. A file may have multiple
     /// compilation commands (e.g. different build configurations); all are returned.
-    llvm::SmallVector<CompilationContext> lookup(llvm::StringRef file,
-                                                 const CommandOptions& options = {});
+    llvm::SmallVector<CompileCommand> lookup(llvm::StringRef file,
+                                             const CommandOptions& options = {});
 
     /// Combined lookup + extract_search_config with internal caching.
     SearchConfig lookup_search_config(llvm::StringRef file, const CommandOptions& options = {});
@@ -191,6 +219,10 @@ public:
     /// Intern a file path and return its path_id.
     std::uint32_t intern_path(llvm::StringRef path);
 
+    /// Check if a file has an explicit entry in the compilation database
+    /// (as opposed to a synthesized default).
+    bool has_entry(llvm::StringRef file);
+
     /// All compilation entries (sorted by path_id).
     llvm::ArrayRef<CompilationEntry> get_entries() const;
 

src/command/toolchain.cpp

@@ -5,10 +5,10 @@
 #include <vector>
 
 #include "command/argument_parser.h"
-#include "eventide/reflection/enum.h"
 #include "support/filesystem.h"
 #include "support/logging.h"
 
+#include "kota/meta/enum.h"
 #include "llvm/ADT/ScopeExit.h"
 #include "llvm/Support/CommandLine.h"
 #include "llvm/Support/FileSystem.h"
@@ -363,7 +363,7 @@ std::vector<const char*> query_toolchain(const QueryParams& params) {
         case CompilerFamily::Unknown: {
             /// TODO: nvcc and intel compilers need further exploration.
             LOG_ERROR("Fail to query driver, unknown supported driver kind: {}, driver is {}",
-                      eventide::refl::enum_name(family),
+                      kota::meta::enum_name(family),
                       driver);
 
             std::vector<const char*> result;

src/compile/compilation.cpp

@@ -219,9 +219,10 @@ public:
 
     auto CreateASTConsumer(clang::CompilerInstance& instance, llvm::StringRef file)
         -> std::unique_ptr<clang::ASTConsumer> final {
-        return std::make_unique<ProxyASTConsumer>(
-            WrapperFrontendAction::CreateASTConsumer(instance, file),
-            unit);
+        auto consumer = WrapperFrontendAction::CreateASTConsumer(instance, file);
+        if(!consumer)
+            return nullptr;
+        return std::make_unique<ProxyASTConsumer>(std::move(consumer), unit);
     }
 
     /// Make this public.

src/compile/compilation_unit.cpp

@@ -81,13 +81,16 @@ auto CompilationUnitRef::file_offset(clang::SourceLocation location) -> std::uin
 }
 
 auto CompilationUnitRef::file_path(clang::FileID fid) -> llvm::StringRef {
-    assert(fid.isValid() && "Invalid fid");
+    if(!fid.isValid())
+        return {};
     if(auto it = self->path_cache.find(fid); it != self->path_cache.end()) {
         return it->second;
     }
 
     auto entry = self->SM().getFileEntryRefForID(fid);
-    assert(entry && "Invalid file entry");
+    if(!entry) {
+        return {};
+    }
 
     llvm::SmallString<128> path;
 
@@ -242,13 +245,19 @@ std::vector<std::string> CompilationUnitRef::deps() {
     for(auto& [fid, directive]: directives()) {
         for(auto& include: directive.includes) {
             if(!include.skipped) {
-                deps.try_emplace(file_path(include.fid));
+                auto path = file_path(include.fid);
+                if(!path.empty()) {
+                    deps.try_emplace(path);
+                }
             }
         }
 
         for(auto& has_include: directive.has_includes) {
             if(has_include.fid.isValid()) {
-                deps.try_emplace(file_path(has_include.fid));
+                auto path = file_path(has_include.fid);
+                if(!path.empty()) {
+                    deps.try_emplace(path);
+                }
             }
         }
     }

src/compile/directive.cpp

@@ -65,11 +65,36 @@ public:
     ///                         Rewritten Preprocessor Callbacks
     /// ============================================================================
 
+    void HasEmbed(clang::SourceLocation location,
+                  llvm::StringRef filename,
+                  bool is_angled,
+                  clang::OptionalFileEntryRef file) override {
+        unit->directives[unit.file_id(location)].has_embeds.emplace_back(clice::HasEmbed{
+            .file_name = filename,
+            .file = file,
+            .is_angled = is_angled,
+            .loc = location,
+        });
+    }
+
+    void EmbedDirective(clang::SourceLocation location,
+                        clang::StringRef filename,
+                        bool is_angled,
+                        clang::OptionalFileEntryRef file,
+                        const clang::LexEmbedParametersResult&) override {
+        unit->directives[unit.file_id(location)].embeds.emplace_back(Embed{
+            .file_name = filename,
+            .file = file,
+            .is_angled = is_angled,
+            .loc = location,
+        });
+    }
+
     void InclusionDirective(clang::SourceLocation hash_loc,
                             const clang::Token& include_tok,
                             llvm::StringRef,
                             bool,
-                            clang::CharSourceRange filename_range,
+                            clang::CharSourceRange,
                             clang::OptionalFileEntryRef,
                             llvm::StringRef,
                             llvm::StringRef,
@@ -83,7 +108,6 @@ public:
         unit->directives[prev_fid].includes.emplace_back(Include{
             .fid = {},
             .location = include_tok.getLocation(),
-            .filename_range = filename_range.getAsRange(),
         });
     }
 

src/compile/directive.h

@@ -20,11 +20,8 @@ struct Include {
     /// The file id of included file.
     clang::FileID fid;
 
-    /// Location of the `include`.
+    /// Location of the `include` keyword.
     clang::SourceLocation location;
-
-    /// The range of filename(includes `""` or `<>`).
-    clang::SourceRange filename_range;
 };
 
 /// Information about `__has_include` directive.
@@ -132,6 +129,39 @@ struct Import {
     std::vector<clang::SourceLocation> name_locations;
 };
 
+/// Information about `#embed` directive.
+struct Embed {
+    /// The file name in the embed directive, not including quotes or angle brackets.
+    llvm::StringRef file_name;
+
+    /// The actual file that may be embedded by this embed directive.
+    clang::OptionalFileEntryRef file;
+
+    /// Whether the file name is angled.
+    bool is_angled;
+
+    /// Location of the `#` token.
+    clang::SourceLocation loc;
+
+    /// TODO: Currently we do not store parameters of the embed directive.
+    /// See clang::LexEmbedParametersResult for details.
+};
+
+/// Information about `__has_embed` directive.
+struct HasEmbed {
+    /// The file name in the embed directive, not including quotes or angle brackets.
+    llvm::StringRef file_name;
+
+    /// The actual file that may be embedded by this embed directive.
+    clang::OptionalFileEntryRef file;
+
+    /// Whether the file name is angled.
+    bool is_angled;
+
+    /// Location of the `__has_embed` token.
+    clang::SourceLocation loc;
+};
+
 struct Directive {
     std::vector<Include> includes;
     std::vector<HasInclude> has_includes;
@@ -139,6 +169,8 @@ struct Directive {
     std::vector<MacroRef> macros;
     std::vector<Pragma> pragmas;
     std::vector<Import> imports;
+    std::vector<Embed> embeds;
+    std::vector<HasEmbed> has_embeds;
 };
 
 }  // namespace clice

src/compile/tidy.cpp

@@ -92,15 +92,11 @@ tidy::ClangTidyOptions create_options() {
                          // include-cleaner is directly integrated in IncludeCleaner.cpp
                          "-misc-include-cleaner",
 
-                         // ----- False Positives -----
-
                          // Check relies on seeing ifndef/define/endif directives,
                          // clangd doesn't replay those when using a preamble.
                          "-llvm-header-guard",
                          "-modernize-macro-to-enum",
 
-                         // ----- Crashing Checks -----
-
                          // Check can choke on invalid (intermediate) c++
                          // code, which is often the case when clangd
                          // tries to build an AST.

src/feature/code_completion.cpp

@@ -53,8 +53,8 @@ auto completion_kind(const clang::NamedDecl* decl) -> protocol::CompletionItemKi
         return protocol::CompletionItemKind::Module;
     }
 
-    if(llvm::isa<clang::FunctionDecl, clang::FunctionTemplateDecl>(decl)) {
-        return protocol::CompletionItemKind::Function;
+    if(llvm::isa<clang::CXXConstructorDecl>(decl)) {
+        return protocol::CompletionItemKind::Constructor;
     }
 
     if(llvm::isa<clang::CXXMethodDecl,
@@ -64,8 +64,8 @@ auto completion_kind(const clang::NamedDecl* decl) -> protocol::CompletionItemKi
         return protocol::CompletionItemKind::Method;
     }
 
-    if(llvm::isa<clang::CXXConstructorDecl>(decl)) {
-        return protocol::CompletionItemKind::Constructor;
+    if(llvm::isa<clang::FunctionDecl, clang::FunctionTemplateDecl>(decl)) {
+        return protocol::CompletionItemKind::Function;
     }
 
     if(llvm::isa<clang::FieldDecl, clang::IndirectFieldDecl>(decl)) {
@@ -109,6 +109,115 @@ auto completion_kind(const clang::NamedDecl* decl) -> protocol::CompletionItemKi
     return protocol::CompletionItemKind::Text;
 }
 
+/// Extract the function signature (parameter list) from a CodeCompletionString.
+/// Returns something like "(int x, float y)" for display in labelDetails.detail.
+auto extract_signature(const clang::CodeCompletionString& ccs) -> std::string {
+    std::string signature;
+    bool in_parens = false;
+
+    for(const auto& chunk: ccs) {
+        using CK = clang::CodeCompletionString::ChunkKind;
+        switch(chunk.Kind) {
+            case CK::CK_LeftParen:
+                in_parens = true;
+                signature += '(';
+                break;
+            case CK::CK_RightParen:
+                signature += ')';
+                in_parens = false;
+                break;
+            case CK::CK_Placeholder:
+            case CK::CK_CurrentParameter:
+                if(in_parens && chunk.Text) {
+                    signature += chunk.Text;
+                }
+                break;
+            case CK::CK_Text:
+            case CK::CK_Informative:
+                if(in_parens && chunk.Text) {
+                    signature += chunk.Text;
+                }
+                break;
+            case CK::CK_LeftAngle:
+                signature += '<';
+                in_parens = true;
+                break;
+            case CK::CK_RightAngle:
+                signature += '>';
+                in_parens = false;
+                break;
+            case CK::CK_Comma:
+                if(in_parens) {
+                    signature += ", ";
+                }
+                break;
+            default: break;
+        }
+    }
+
+    return signature;
+}
+
+/// Build a snippet string from a CodeCompletionString.
+/// Produces e.g. "funcName(${1:int x}, ${2:float y})" for functions,
+/// or "ClassName<${1:T}>" for class templates.
+auto build_snippet(const clang::CodeCompletionString& ccs) -> std::string {
+    std::string snippet;
+    unsigned placeholder_index = 0;
+
+    for(const auto& chunk: ccs) {
+        using CK = clang::CodeCompletionString::ChunkKind;
+        switch(chunk.Kind) {
+            case CK::CK_TypedText:
+                if(chunk.Text) {
+                    snippet += chunk.Text;
+                }
+                break;
+            case CK::CK_Placeholder:
+                if(chunk.Text) {
+                    snippet += std::format("${{{0}:{1}}}", ++placeholder_index, chunk.Text);
+                }
+                break;
+            case CK::CK_LeftParen: snippet += '('; break;
+            case CK::CK_RightParen: snippet += ')'; break;
+            case CK::CK_LeftAngle: snippet += '<'; break;
+            case CK::CK_RightAngle: snippet += '>'; break;
+            case CK::CK_Comma: snippet += ", "; break;
+            case CK::CK_Text:
+                if(chunk.Text) {
+                    snippet += chunk.Text;
+                }
+                break;
+            case CK::CK_Optional:
+                // Optional chunks contain default arguments — skip for snippet.
+                break;
+            case CK::CK_Informative:
+            case CK::CK_ResultType:
+            case CK::CK_CurrentParameter:
+                // Display-only chunks, not part of insertion.
+                break;
+            default: break;
+        }
+    }
+
+    // If no placeholders were generated, return empty to signal plain text.
+    if(placeholder_index == 0) {
+        return {};
+    }
+
+    return snippet;
+}
+
+/// Extract the return type from a CodeCompletionString.
+auto extract_return_type(const clang::CodeCompletionString& ccs) -> std::string {
+    for(const auto& chunk: ccs) {
+        if(chunk.Kind == clang::CodeCompletionString::CK_ResultType && chunk.Text) {
+            return chunk.Text;
+        }
+    }
+    return {};
+}
+
 struct OverloadItem {
     protocol::CompletionItem item;
     float score = 0.0F;
@@ -159,29 +268,45 @@ public:
         overloads.reserve(candidate_count);
         std::unordered_map<std::string, std::size_t> overload_index;
 
-        auto build_item =
-            [&](llvm::StringRef label, protocol::CompletionItemKind kind, llvm::StringRef insert) {
-                protocol::CompletionItem item{
-                    .label = label.str(),
-                };
-                item.kind = kind;
+        bool prefix_starts_with_underscore = prefix.spelling.starts_with("_");
 
-                protocol::TextEdit edit{
-                    .range = replace_range,
-                    .new_text = insert.empty() ? label.str() : insert.str(),
-                };
-                item.text_edit = std::move(edit);
-                return item;
+        auto build_item = [&](llvm::StringRef label,
+                              protocol::CompletionItemKind kind,
+                              llvm::StringRef insert,
+                              bool is_snippet = false) {
+            protocol::CompletionItem item{
+                .label = label.str(),
             };
+            item.kind = kind;
+
+            protocol::TextEdit edit{
+                .range = replace_range,
+                .new_text = insert.empty() ? label.str() : insert.str(),
+            };
+            item.text_edit = std::move(edit);
+            if(is_snippet) {
+                item.insert_text_format = protocol::InsertTextFormat::Snippet;
+            }
+            return item;
+        };
 
         auto try_add = [&](llvm::StringRef label,
                            protocol::CompletionItemKind kind,
                            llvm::StringRef insert_text,
-                           llvm::StringRef overload_key) {
+                           llvm::StringRef overload_key,
+                           llvm::StringRef signature = {},
+                           llvm::StringRef return_type = {},
+                           bool is_snippet = false,
+                           bool is_deprecated = false) {
             if(label.empty()) {
                 return;
             }
 
+            // Filter out _/__ prefixed internal symbols unless user typed _.
+            if(!prefix_starts_with_underscore && label.starts_with("_")) {
+                return;
+            }
+
             auto score = matcher.match(label);
             if(!score.has_value()) {
                 return;
@@ -191,8 +316,21 @@ public:
                 auto [it, inserted] =
                     overload_index.try_emplace(overload_key.str(), overloads.size());
                 if(inserted) {
-                    auto item = build_item(label, kind, insert_text);
+                    auto item = build_item(label, kind, insert_text, is_snippet);
                     item.sort_text = std::format("{}", *score);
+                    if(!signature.empty() || !return_type.empty()) {
+                        protocol::CompletionItemLabelDetails details;
+                        if(!signature.empty()) {
+                            details.detail = signature.str();
+                        }
+                        if(!return_type.empty()) {
+                            details.description = return_type.str();
+                        }
+                        item.label_details = std::move(details);
+                    }
+                    if(is_deprecated) {
+                        item.tags = std::vector{protocol::CompletionItemTag::Deprecated};
+                    }
                     overloads.push_back({
                         .item = std::move(item),
                         .score = *score,
@@ -209,8 +347,21 @@ public:
                 return;
             }
 
-            auto item = build_item(label, kind, insert_text);
+            auto item = build_item(label, kind, insert_text, is_snippet);
             item.sort_text = std::format("{}", *score);
+            if(!signature.empty() || !return_type.empty()) {
+                protocol::CompletionItemLabelDetails details;
+                if(!signature.empty()) {
+                    details.detail = signature.str();
+                }
+                if(!return_type.empty()) {
+                    details.description = return_type.str();
+                }
+                item.label_details = std::move(details);
+            }
+            if(is_deprecated) {
+                item.tags = std::vector{protocol::CompletionItemTag::Deprecated};
+            }
             collected.push_back(std::move(item));
         };
 
@@ -242,16 +393,60 @@ public:
                         break;
                     }
 
-                    auto label = ast::name_of(declaration);
                     auto kind = completion_kind(declaration);
 
+                    // For constructors and deduction guides, use the class name
+                    // (without template args) instead of the full type name.
+                    // e.g. "vector" instead of "vector<_Tp, _Alloc>".
+                    std::string label;
+                    if(auto* ctor = llvm::dyn_cast<clang::CXXConstructorDecl>(declaration)) {
+                        label = ctor->getParent()->getName().str();
+                    } else if(auto* guide =
+                                  llvm::dyn_cast<clang::CXXDeductionGuideDecl>(declaration)) {
+                        label = guide->getDeducedTemplate()->getName().str();
+                    } else {
+                        label = ast::name_of(declaration);
+                    }
+
                     llvm::SmallString<256> qualified_name;
-                    if(options.bundle_overloads && kind == protocol::CompletionItemKind::Function) {
+                    bool is_callable = kind == protocol::CompletionItemKind::Function ||
+                                       kind == protocol::CompletionItemKind::Method ||
+                                       kind == protocol::CompletionItemKind::Constructor;
+                    if(options.bundle_overloads && is_callable) {
                         llvm::raw_svector_ostream stream(qualified_name);
                         declaration->printQualifiedName(stream);
                     }
 
-                    try_add(label, kind, label, qualified_name.str());
+                    std::string signature;
+                    std::string return_type;
+                    std::string snippet;
+                    auto* ccs =
+                        candidate.CreateCodeCompletionString(sema,
+                                                             context,
+                                                             getAllocator(),
+                                                             getCodeCompletionTUInfo(),
+                                                             /*IncludeBriefComments=*/false);
+                    if(ccs) {
+                        signature = extract_signature(*ccs);
+                        return_type = extract_return_type(*ccs);
+                        // Generate snippet for non-bundled callables.
+                        if(is_callable && !options.bundle_overloads &&
+                           options.enable_function_arguments_snippet) {
+                            snippet = build_snippet(*ccs);
+                        }
+                    }
+
+                    bool has_snippet = !snippet.empty();
+                    auto insert = has_snippet ? llvm::StringRef(snippet) : llvm::StringRef(label);
+                    bool deprecated = candidate.Availability == CXAvailability_Deprecated;
+                    try_add(label,
+                            kind,
+                            insert,
+                            qualified_name.str(),
+                            signature,
+                            return_type,
+                            has_snippet,
+                            deprecated);
                     break;
                 }
             }
@@ -259,11 +454,48 @@ public:
 
         for(auto& entry: overloads) {
             if(entry.count > 1) {
-                entry.item.detail = "(...)";
+                protocol::CompletionItemLabelDetails details;
+                details.detail = std::format("(…) +{} overloads", entry.count);
+                entry.item.label_details = std::move(details);
             }
             collected.push_back(std::move(entry.item));
         }
 
+        // In bundle mode, deduplicate by label: when the same name appears as
+        // both a class and its constructors/deduction guides, keep only the
+        // highest-priority kind (Class > Function/Method > others).
+        if(options.bundle_overloads) {
+            auto kind_priority = [](protocol::CompletionItemKind k) -> int {
+                switch(k) {
+                    case protocol::CompletionItemKind::Class:
+                    case protocol::CompletionItemKind::Struct: return 3;
+                    case protocol::CompletionItemKind::Function:
+                    case protocol::CompletionItemKind::Method: return 2;
+                    case protocol::CompletionItemKind::Constructor: return 1;
+                    default: return 0;
+                }
+            };
+
+            std::unordered_map<std::string, std::size_t> label_index;
+            std::vector<protocol::CompletionItem> deduped;
+            deduped.reserve(collected.size());
+
+            for(auto& item: collected) {
+                auto [it, inserted] = label_index.try_emplace(item.label, deduped.size());
+                if(inserted) {
+                    deduped.push_back(std::move(item));
+                } else {
+                    auto& existing = deduped[it->second];
+                    int old_prio = existing.kind.has_value() ? kind_priority(*existing.kind) : 0;
+                    int new_prio = item.kind.has_value() ? kind_priority(*item.kind) : 0;
+                    if(new_prio > old_prio) {
+                        existing = std::move(item);
+                    }
+                }
+            }
+            collected.swap(deduped);
+        }
+
         output.clear();
         output.swap(collected);
     }

src/feature/diagnostics.cpp

@@ -2,14 +2,15 @@
 #include <string>
 #include <vector>
 
-#include "eventide/ipc/lsp/uri.h"
 #include "feature/feature.h"
 
+#include "kota/ipc/lsp/uri.h"
+
 namespace clice::feature {
 
 namespace {
 
-namespace lsp = eventide::ipc::lsp;
+namespace lsp = kota::ipc::lsp;
 
 auto to_uri(llvm::StringRef file) -> std::string {
     const auto file_view = std::string_view(file.data(), file.size());

src/feature/document_links.cpp

@@ -1,14 +1,12 @@
-#include <algorithm>
 #include <cstdint>
 #include <string>
 #include <vector>
 
 #include "feature/feature.h"
+#include "syntax/lexer.h"
 
 namespace clice::feature {
 
-namespace {}  // namespace
-
 auto document_links(CompilationUnitRef unit, PositionEncoding encoding)
     -> std::vector<protocol::DocumentLink> {
     std::vector<protocol::DocumentLink> links;
@@ -22,50 +20,42 @@ auto document_links(CompilationUnitRef unit, PositionEncoding encoding)
     auto content = unit.interested_content();
     PositionMapper converter(content, encoding);
     auto& directives = directives_it->second;
+    auto* lang_opts = &unit.lang_options();
 
-    links.reserve(directives.includes.size() + directives.has_includes.size());
+    auto add_link = [&](clang::SourceLocation loc, llvm::StringRef target) {
+        auto [fid, offset] = unit.decompose_location(loc);
+        if(fid != interested || offset >= content.size())
+            return;
+        auto range = find_directive_argument(content, offset, lang_opts);
+        if(!range)
+            return;
+        protocol::DocumentLink link{.range = to_range(converter, *range)};
+        link.target = target.str();
+        links.push_back(std::move(link));
+    };
 
     for(const auto& include: directives.includes) {
-        auto [fid, range] = unit.decompose_range(include.filename_range);
-        if(fid != interested || !range.valid()) {
-            continue;
+        if(include.fid.isValid()) {
+            add_link(include.location, unit.file_path(include.fid));
         }
-
-        protocol::DocumentLink link{
-            .range = to_range(converter, range),
-        };
-        link.target = std::string(unit.file_path(include.fid));
-        links.push_back(std::move(link));
     }
 
     for(const auto& has_include: directives.has_includes) {
-        if(has_include.fid.isInvalid()) {
-            continue;
+        if(has_include.fid.isValid()) {
+            add_link(has_include.location, unit.file_path(has_include.fid));
         }
+    }
 
-        auto [fid, offset] = unit.decompose_location(has_include.location);
-        if(fid != interested || offset >= content.size()) {
-            continue;
+    for(const auto& embed: directives.embeds) {
+        if(embed.file) {
+            add_link(embed.loc, embed.file->getName());
         }
+    }
 
-        auto tail = content.substr(offset);
-        char open = tail.front();
-        if(open != '<' && open != '"') {
-            continue;
+    for(const auto& has_embed: directives.has_embeds) {
+        if(has_embed.file) {
+            add_link(has_embed.loc, has_embed.file->getName());
         }
-
-        char close = open == '<' ? '>' : '"';
-        auto close_index = tail.find(close, 1);
-        if(close_index == llvm::StringRef::npos) {
-            continue;
-        }
-
-        LocalSourceRange range(offset, offset + static_cast<std::uint32_t>(close_index + 1));
-        protocol::DocumentLink link{
-            .range = to_range(converter, range),
-        };
-        link.target = std::string(unit.file_path(has_include.fid));
-        links.push_back(std::move(link));
     }
 
     return links;

src/feature/feature.h

@@ -7,8 +7,9 @@
 
 #include "compile/compilation.h"
 #include "compile/compilation_unit.h"
-#include "eventide/ipc/lsp/position.h"
-#include "eventide/ipc/lsp/protocol.h"
+
+#include "kota/ipc/lsp/position.h"
+#include "kota/ipc/lsp/protocol.h"
 
 namespace clang {
 
@@ -18,11 +19,11 @@ class NamedDecl;
 
 namespace clice::feature {
 
-namespace protocol = eventide::ipc::protocol;
+namespace protocol = kota::ipc::protocol;
 
-using eventide::ipc::lsp::PositionEncoding;
-using eventide::ipc::lsp::PositionMapper;
-using eventide::ipc::lsp::parse_position_encoding;
+using kota::ipc::lsp::PositionEncoding;
+using kota::ipc::lsp::PositionMapper;
+using kota::ipc::lsp::parse_position_encoding;
 
 inline auto to_range(const PositionMapper& converter, LocalSourceRange range) -> protocol::Range {
     return protocol::Range{
@@ -103,4 +104,6 @@ auto document_format(llvm::StringRef file,
                      PositionEncoding encoding = PositionEncoding::UTF16)
     -> std::vector<protocol::TextEdit>;
 
+auto format_code(llvm::StringRef file, llvm::StringRef code) -> std::string;
+
 }  // namespace clice::feature

src/feature/formatting.cpp

@@ -49,7 +49,7 @@ auto document_format(llvm::StringRef file,
         range ? tooling::Range(range->begin, range->length()) : tooling::Range(0, content.size());
     auto replacements = format_content(file, content, selection);
     if(!replacements) {
-        LOG_INFO("Fail to format for {}\n{}", file, replacements.error());
+        LOG_WARN("Failed to format {}: {}", file, replacements.error());
         return edits;
     }
 
@@ -66,4 +66,20 @@ auto document_format(llvm::StringRef file,
     return edits;
 }
 
+auto format_code(llvm::StringRef file, llvm::StringRef code) -> std::string {
+    auto style = clang::format::getStyle(clang::format::DefaultFormatStyle,
+                                         file,
+                                         clang::format::DefaultFallbackStyle,
+                                         code);
+    if(!style)
+        return code.str();
+
+    auto replacements = clang::format::reformat(*style, code, {tooling::Range(0, code.size())});
+    auto result = tooling::applyAllReplacements(code, replacements);
+    if(!result)
+        return code.str();
+
+    return llvm::StringRef(*result).trim().str();
+}
+
 }  // namespace clice::feature

src/feature/semantic_tokens.cpp

@@ -12,6 +12,7 @@
 
 #include "clang/AST/Attr.h"
 #include "clang/Basic/IdentifierTable.h"
+#include "clang/Basic/Module.h"
 
 namespace clice::feature {
 
@@ -23,12 +24,8 @@ struct RawToken {
     std::uint32_t modifiers = 0;
 };
 
-constexpr std::uint32_t bit(SymbolModifiers::Kind kind) {
-    return static_cast<std::uint32_t>(kind);
-}
-
 void add_modifier(std::uint32_t& modifiers, SymbolModifiers::Kind kind) {
-    modifiers |= bit(kind);
+    modifiers |= SymbolModifiers::to_mask(kind);
 }
 
 auto type_index(SymbolKind kind) -> std::uint32_t {
@@ -39,6 +36,132 @@ auto encode_modifiers(std::uint32_t modifiers) -> std::uint32_t {
     return modifiers;
 }
 
+bool is_dependent(const clang::Decl* D) {
+    return isa<clang::UnresolvedUsingValueDecl>(D);
+}
+
+/// Returns true if `decl` is considered to be from a default/system library.
+/// This currently checks the systemness of the file by include type, although
+/// different heuristics may be used in the future (e.g. sysroot paths).
+bool is_default_library(const clang::Decl* decl) {
+    clang::SourceLocation location = decl->getLocation();
+    if(!location.isValid()) {
+        return false;
+    }
+    return decl->getASTContext().getSourceManager().isInSystemHeader(location);
+}
+
+// "Static" means many things in C++, only some get the "static" modifier.
+//
+// Meanings that do:
+// - Members associated with the class rather than the instance.
+//   This is what 'static' most often means across languages.
+// - static local variables
+//   These are similarly "detached from their context" by the static keyword.
+//   In practice, these are rarely used inside classes, reducing confusion.
+//
+// Meanings that don't:
+// - Namespace-scoped variables, which have static storage class.
+//   This is implicit, so the keyword "static" isn't so strongly associated.
+//   If we want a modifier for these, "global scope" is probably the concept.
+// - Namespace-scoped variables/functions explicitly marked "static".
+//   There the keyword changes *linkage* , which is a totally different concept.
+//   If we want to model this, "file scope" would be a nice modifier.
+//
+// This is confusing, and maybe we should use another name, but because "static"
+// is a standard LSP modifier, having one with that name has advantages.
+bool is_static(const clang::Decl* decl) {
+    if(const auto* method = llvm::dyn_cast<clang::CXXMethodDecl>(decl)) {
+        return method->isStatic();
+    }
+    if(const auto* var_decl = llvm::dyn_cast<clang::VarDecl>(decl)) {
+        return var_decl->isStaticDataMember() || var_decl->isStaticLocal();
+    }
+    if(const auto* objc_property = llvm::dyn_cast<clang::ObjCPropertyDecl>(decl)) {
+        return objc_property->isClassProperty();
+    }
+    if(const auto* objc_method = llvm::dyn_cast<clang::ObjCMethodDecl>(decl)) {
+        return objc_method->isClassMethod();
+    }
+    if(const auto* function = llvm::dyn_cast<clang::FunctionDecl>(decl)) {
+        return function->isStatic();
+    }
+    return false;
+}
+
+// Whether `type` is const in a loose sense: would a value of this type be readonly?
+bool is_const(clang::QualType type) {
+    if(type.isNull()) {
+        return false;
+    }
+    type = type.getNonReferenceType();
+    if(type.isConstQualified()) {
+        return true;
+    }
+    if(const auto* array_type = type->getAsArrayTypeUnsafe()) {
+        return is_const(array_type->getElementType());
+    }
+    if(is_const(type->getPointeeType())) {
+        return true;
+    }
+    return false;
+}
+
+// Whether `decl` is const in a loose sense (should it be highlighted as such?)
+// FIXME: This is separate from whether a particular usage can mutate `decl`.
+//        We may want a receiver in `value.size()` to be readonly even if `value` is mutable.
+bool is_const(const clang::Decl* decl) {
+    if(llvm::isa<clang::EnumConstantDecl>(decl) ||
+       llvm::isa<clang::NonTypeTemplateParmDecl>(decl)) {
+        return true;
+    }
+    if(llvm::isa<clang::FieldDecl>(decl) || llvm::isa<clang::VarDecl>(decl) ||
+       llvm::isa<clang::MSPropertyDecl>(decl) || llvm::isa<clang::BindingDecl>(decl)) {
+        if(is_const(llvm::cast<clang::ValueDecl>(decl)->getType())) {
+            return true;
+        }
+    }
+    if(const auto* objc_property = llvm::dyn_cast<clang::ObjCPropertyDecl>(decl)) {
+        if(objc_property->isReadOnly()) {
+            return true;
+        }
+    }
+    if(const auto* ms_property = llvm::dyn_cast<clang::MSPropertyDecl>(decl)) {
+        if(!ms_property->hasSetter()) {
+            return true;
+        }
+    }
+    if(const auto* method = llvm::dyn_cast<clang::CXXMethodDecl>(decl)) {
+        if(method->isConst()) {
+            return true;
+        }
+    }
+    if(const auto* function = llvm::dyn_cast<clang::FunctionDecl>(decl)) {
+        return is_const(function->getReturnType());
+    }
+    return false;
+}
+
+// Indicates whether declaration `decl` is abstract in cases where it is a struct or a
+// class.
+bool is_abstract(const clang::Decl* decl) {
+    if(const auto* method = llvm::dyn_cast<clang::CXXMethodDecl>(decl)) {
+        return method->isPureVirtual();
+    }
+    if(const auto* record = llvm::dyn_cast<clang::CXXRecordDecl>(decl)) {
+        return record->hasDefinition() && record->isAbstract();
+    }
+    return false;
+}
+
+// Indicates whether declaration `decl` is virtual in cases where it is a method.
+bool is_virtual(const clang::Decl* decl) {
+    if(const auto* method = llvm::dyn_cast<clang::CXXMethodDecl>(decl)) {
+        return method->isVirtual();
+    }
+    return false;
+}
+
 class SemanticTokensCollector : public SemanticVisitor<SemanticTokensCollector> {
 public:
     explicit SemanticTokensCollector(CompilationUnitRef unit) : SemanticVisitor(unit, true) {}
@@ -46,6 +169,7 @@ public:
     auto collect() -> std::vector<RawToken> {
         highlight_lexical(unit.interested_file());
         run();
+        highlight_modules();
         merge_tokens();
         return std::move(tokens);
     }
@@ -55,6 +179,8 @@ public:
                               clang::SourceLocation location) {
         std::uint32_t modifiers = 0;
         if(relation.is_one_of(RelationKind::Definition)) {
+            // todo: clangd add both Declaration and Definition modifiers for definitions.
+            // add_modifier(modifiers, SymbolModifiers::Declaration);
             add_modifier(modifiers, SymbolModifiers::Definition);
         } else if(relation.is_one_of(RelationKind::Declaration)) {
             add_modifier(modifiers, SymbolModifiers::Declaration);
@@ -63,6 +189,42 @@ public:
         if(ast::is_templated(decl)) {
             add_modifier(modifiers, SymbolModifiers::Templated);
         }
+        // Apply attribute-style modifiers to the underlying declaration.
+        // The attribute tests don't want to look at the template.
+        if(const auto* template_decl = llvm::dyn_cast<clang::TemplateDecl>(decl)) {
+            if(const auto* templated_decl = template_decl->getTemplatedDecl())
+                decl = templated_decl;
+        }
+
+        // TODO: add scope-based modifiers once the local model supports them.
+        // if (auto Mod = scopeModifier(Decl))
+        //     Tok.addModifier(*Mod);
+
+        if(is_const(decl)) {
+            add_modifier(modifiers, SymbolModifiers::Readonly);
+        }
+        if(is_static(decl)) {
+            add_modifier(modifiers, SymbolModifiers::Static);
+        }
+        if(is_abstract(decl)) {
+            add_modifier(modifiers, SymbolModifiers::Abstract);
+        }
+        if(is_virtual(decl)) {
+            add_modifier(modifiers, SymbolModifiers::Virtual);
+        }
+        if(is_default_library(decl)) {
+            add_modifier(modifiers, SymbolModifiers::DefaultLibrary);
+        }
+        if(decl->isDeprecated()) {
+            add_modifier(modifiers, SymbolModifiers::Deprecated);
+        }
+        if(is_dependent(decl)) {
+            add_modifier(modifiers, SymbolModifiers::DependentName);
+        }
+        if(llvm::isa<clang::CXXConstructorDecl>(decl) ||
+           llvm::isa<clang::CXXDestructorDecl>(decl)) {
+            add_modifier(modifiers, SymbolModifiers::ConstructorOrDestructor);
+        }
 
         add_token(location, SymbolKind::from(decl), modifiers);
     }
@@ -80,6 +242,10 @@ public:
         add_token(location, SymbolKind::Macro, modifiers);
     }
 
+    // handleModuleOccurrence
+
+    // handleRelation
+
     void handleAttrOccurrence(const clang::Attr* attr, clang::SourceRange range) {
         auto [begin, end] = range;
         if(llvm::isa<clang::FinalAttr, clang::OverrideAttr>(attr)) {
@@ -127,6 +293,58 @@ private:
         });
     }
 
+    void highlight_modules() {
+        auto interested = unit.interested_file();
+
+        auto directives_it = unit.directives().find(interested);
+        if(directives_it != unit.directives().end()) {
+            for(const auto& import: directives_it->second.imports) {
+                add_token(import.location, SymbolKind::Keyword, 0);
+                for(auto loc: import.name_locations) {
+                    add_token(loc, SymbolKind::Module, 0);
+                }
+            }
+        }
+
+        auto* mod = unit.context().getCurrentNamedModule();
+        if(!mod) {
+            return;
+        }
+
+        auto def_loc = mod->DefinitionLoc;
+        if(!def_loc.isValid() || !def_loc.isFileID()) {
+            return;
+        }
+
+        auto [fid, offset] = unit.decompose_location(def_loc);
+        if(fid != interested) {
+            return;
+        }
+
+        auto content = unit.file_content(fid);
+        auto& lang_opts = unit.lang_options();
+        Lexer lexer(content.substr(offset), false, &lang_opts);
+
+        auto module_token = lexer.advance();
+        if(module_token.is_identifier()) {
+            auto range = LocalSourceRange(offset + module_token.range.begin,
+                                          offset + module_token.range.end);
+            tokens.push_back({.range = range, .kind = SymbolKind::Keyword, .modifiers = 0});
+        }
+
+        // Scan for identifiers (module name parts) until semicolon/eof.
+        while(true) {
+            auto token = lexer.advance();
+            if(token.is_eof() || token.kind == clang::tok::semi) {
+                break;
+            }
+            if(token.is_identifier()) {
+                auto range = LocalSourceRange(offset + token.range.begin, offset + token.range.end);
+                tokens.push_back({.range = range, .kind = SymbolKind::Module, .modifiers = 0});
+            }
+        }
+    }
+
     void highlight_lexical(clang::FileID fid) {
         auto content = unit.file_content(fid);
         auto& lang_opts = unit.lang_options();
@@ -181,10 +399,17 @@ private:
     }
 
     static void resolve_conflict(RawToken& last, const RawToken& current) {
-        (void)current;
         if(last.kind == SymbolKind::Conflict) {
             return;
         }
+        // Directive is a low-priority lexical kind; semantic tokens override it.
+        if(last.kind == SymbolKind::Directive) {
+            last = current;
+            return;
+        }
+        if(current.kind == SymbolKind::Directive) {
+            return;
+        }
         last.kind = SymbolKind::Conflict;
     }
 

src/index/tu_index.cpp

@@ -14,8 +14,8 @@ namespace {
 
 class Builder : public SemanticVisitor<Builder> {
 public:
-    Builder(TUIndex& result, CompilationUnitRef unit) :
-        SemanticVisitor<Builder>(unit, false), result(result) {
+    Builder(TUIndex& result, CompilationUnitRef unit, bool interested_only) :
+        SemanticVisitor<Builder>(unit, interested_only), result(result) {
         result.graph = IncludeGraph::from(unit);
     }
 
@@ -188,11 +188,11 @@ std::array<std::uint8_t, 32> FileIndex::hash() {
     return hasher.final();
 }
 
-TUIndex TUIndex::build(CompilationUnitRef unit) {
+TUIndex TUIndex::build(CompilationUnitRef unit, bool interested_only) {
     TUIndex index;
     index.built_at = unit.build_at();
 
-    Builder builder(index, unit);
+    Builder builder(index, unit, interested_only);
     builder.build();
 
     return index;