---
id: NS-0002
type: northstar
status: ready
title: LSP and editor experience completion
refs:
  - REQUIREMENTS.md
  - docs/editor-support.md
  - docs/diagnostics.md
  - docs/hemplate-syntax.md
  - hemx-lsp/src/main.rs
  - hemx-build/src/lib.rs
---

## Objective

Complete the `.heml` editor experience around existing compiler/build authority: diagnostics parity, completion, hover, cross-file facts, and correct LSP protocol behavior without inventing a second template language or editor framework.

## Authority

- `docs/editor-support.md` says `.heml` authoring should feel like HTML first and layer hemx diagnostics/completions/hover on top.
- `docs/hemplate-syntax.md` is the stable syntax surface; LSP must not invent Vue/Handlebars-like syntax.
- `docs/diagnostics.md` keeps editor overlays subordinate to compiler/build diagnostics.
- `REQUIREMENTS.md` `diagnostics/004` through `diagnostics/008` and `check/001`/`check/003` constrain editor overlays, spans, completion, hover, and build-visible validation.
- `hemx-lsp/src/main.rs` currently owns the CLI/LSP implementation surface.

## Close when

- Diagnostics parity slices prove LSP-published diagnostics match `hemx-build` CLI diagnostics for open/save/file paths.
- Completion slices cover hemplate directives, `data-hemx-*` attributes, and context-sensitive generated facts without requiring external editor state.
- Hover slices explain real hemplate syntax and hemx attributes from docs authority.
- Cross-file fact slices describe what must fail at `cargo check` and what can remain editor-only.
- LSP protocol slices cover initialize, sync, completion, hover, diagnostics clearing, and error responses with tests.

## Verification

- `workledger check`
- `workledger list`
- Later implementation slices should prefer focused `cargo test -p hemx-lsp`/integration tests, then `cargo check --workspace` or `cargo run -p hemx-xtask -- test` when build integration changes.

## Non-goals

- Do not build a custom editor framework, formatter, Rust type system, selector model, or second `.heml` parser.
- Do not make VS Code/Cursor/Neovim provider behavior the source of truth; provider glue stays downstream of LSP/build facts.
- Do not add external publishing/signing flows without explicit authority.

## Evidence

- `hemx-lsp/src/main.rs` already exposes diagnostics, completion, and hover entry points.
- `docs/editor-support.md` and `docs/diagnostics.md` define the editor/build boundary.