---
id: PLN-0098
ticket: pbs-symbol-documentation-and-hover-markdown
title: Expose Doc metadata through PBS editorial and LSP surfaces
status: done
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---

## Briefing

Transport compiler-resolved documentation through the existing PBS editorial and LSP message boundaries.

## Objective

Expose normalized Markdown documentation to LSP consumers without source reparsing.

## Dependencies

- Depends on `PLN-0097`.

## Scope

- Extend compiler editorial result models to include documentation metadata.
- Extend LSP baseline messages where required.
- Keep documentation as Markdown-oriented structured data at the boundary.

## Non-Goals

- Final hover layout composition.
- VSCode automated rendering tests.
- Runtime artifact changes.

## Execution Method

1. Extend PBS editorial models such as `PbsEditorialResolvedSymbol`, completion candidates, or hover source models with optional documentation metadata.
2. Extend LSP API records under `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/messages` only where the baseline protocol needs to carry documentation.
3. Update bridge code under `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler` to map compiler documentation to LSP baseline messages.
4. Preserve backward-compatible behavior for symbols without documentation.
5. Add tests proving the LSP service receives compiler-resolved documentation.

## Acceptance Criteria

- LSP-facing code consumes compiler-resolved documentation metadata.
- No LSP code reparses PBS source to discover `[Doc]`.
- Existing completion, hover, and signature help behavior remains stable for undocumented code.

## Tests

- PBS editorial support tests.
- LSP bridge tests.
- Existing `prometeu-lsp` protocol mapping tests.

## Affected Artifacts

- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialResolvedSymbol.java`
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/messages`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler`
- Related LSP tests