discussion/index.ndjson

@@ -1,7 +1,7 @@
 {"type":"meta","next_id":{"DSC":39,"AGD":42,"DEC":40,"PLN":103,"LSN":55,"CLSN":1}}
 {"type":"discussion","id":"DSC-0038","status":"done","ticket":"studio-packer-rgba8888-asset-pipeline","title":"Studio and Packer RGBA8888 Asset Pipeline Alignment","created_at":"2026-05-23","updated_at":"2026-07-14","tags":["studio","packer","assets","glyph-bank","palette","rgba8888","runtime-alignment"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0053","file":"discussion/lessons/DSC-0038-studio-packer-rgba8888-asset-pipeline/LSN-0053-rgba8888-is-the-canonical-studio-packer-palette-contract.md","status":"done","created_at":"2026-07-14","updated_at":"2026-07-14"}]}
 {"type":"discussion","id":"DSC-0037","status":"done","ticket":"pbs-autocomplete-parameter-names","title":"PBS autocomplete parameter names for stdlib and method calls","created_at":"2026-05-08","updated_at":"2026-05-14","tags":["compiler-pbs","studio","lsp","autocomplete","signature-help","stdlib"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0052","file":"discussion/lessons/DSC-0037-pbs-autocomplete-parameter-names/LSN-0052-canonical-callable-parameter-names-through-pbs-editor-assistance.md","status":"done","created_at":"2026-05-14","updated_at":"2026-05-14"}]}
-{"type":"discussion","id":"DSC-0036","status":"in_progress","ticket":"pbs-symbol-documentation-and-hover-markdown","title":"Modelo de documentacao de simbolos em PBS e consumo markdown no hover","created_at":"2026-05-08","updated_at":"2026-07-15","tags":["compiler","compiler-pbs","studio","lsp","vscode","editor","hover","documentation","markdown"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-pbs-symbol-documentation-and-hover-markdown.md","status":"accepted","created_at":"2026-05-08","updated_at":"2026-07-15"}],"decisions":[{"id":"DEC-0039","file":"DEC-0039-pbs-symbol-documentation-with-doc-markdown-text-blocks.md","status":"accepted","created_at":"2026-07-15","updated_at":"2026-07-15","ref_agenda":"AGD-0039"}],"plans":[{"id":"PLN-0092","file":"PLN-0092-specify-pbs-doc-attribute-and-markdown-text-block-syntax.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0093","file":"PLN-0093-implement-pbs-lexer-support-for-documentation-text-blocks.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0094","file":"PLN-0094-extend-pbs-attribute-parser-and-ast-for-doc-markdown-payloads.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0095","file":"PLN-0095-implement-documentation-text-block-normalization.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0096","file":"PLN-0096-validate-doc-attribute-semantics-and-diagnostics.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0097","file":"PLN-0097-attach-doc-metadata-to-pbs-semantic-symbols.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0098","file":"PLN-0098-expose-doc-metadata-through-pbs-editorial-and-lsp-surfaces.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0099","file":"PLN-0099-render-doc-markdown-in-hover-composition.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0100","file":"PLN-0100-author-doc-metadata-for-stdlib-sdk-and-interface-declarations.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0101","file":"PLN-0101-protect-runtime-artifacts-from-doc-metadata-lowering.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0102","file":"PLN-0102-add-end-to-end-doc-documentation-conformance-coverage.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]}],"lessons":[]}
+{"type":"discussion","id":"DSC-0036","status":"in_progress","ticket":"pbs-symbol-documentation-and-hover-markdown","title":"Modelo de documentacao de simbolos em PBS e consumo markdown no hover","created_at":"2026-05-08","updated_at":"2026-07-15","tags":["compiler","compiler-pbs","studio","lsp","vscode","editor","hover","documentation","markdown"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-pbs-symbol-documentation-and-hover-markdown.md","status":"accepted","created_at":"2026-05-08","updated_at":"2026-07-15"}],"decisions":[{"id":"DEC-0039","file":"DEC-0039-pbs-symbol-documentation-with-doc-markdown-text-blocks.md","status":"accepted","created_at":"2026-07-15","updated_at":"2026-07-15","ref_agenda":"AGD-0039"}],"plans":[{"id":"PLN-0092","file":"PLN-0092-specify-pbs-doc-attribute-and-markdown-text-block-syntax.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0093","file":"PLN-0093-implement-pbs-lexer-support-for-documentation-text-blocks.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0094","file":"PLN-0094-extend-pbs-attribute-parser-and-ast-for-doc-markdown-payloads.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0095","file":"PLN-0095-implement-documentation-text-block-normalization.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0096","file":"PLN-0096-validate-doc-attribute-semantics-and-diagnostics.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0097","file":"PLN-0097-attach-doc-metadata-to-pbs-semantic-symbols.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0098","file":"PLN-0098-expose-doc-metadata-through-pbs-editorial-and-lsp-surfaces.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0099","file":"PLN-0099-render-doc-markdown-in-hover-composition.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0100","file":"PLN-0100-author-doc-metadata-for-stdlib-sdk-and-interface-declarations.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0101","file":"PLN-0101-protect-runtime-artifacts-from-doc-metadata-lowering.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0102","file":"PLN-0102-add-end-to-end-doc-documentation-conformance-coverage.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]}],"lessons":[]}
 {"type":"discussion","id":"DSC-0035","status":"done","ticket":"pbs-lsp-editor-assistance-wave-1","title":"Wave 1 de assistencia editorial via LSP para PBS no VS Code","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["studio","lsp","vscode","compiler","compiler-pbs","editor","completion","hover","signature-help"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0051","file":"discussion/lessons/DSC-0035-pbs-lsp-editor-assistance-wave-1/LSN-0051-compiler-backed-editor-assistance-for-pbs.md","status":"done","created_at":"2026-05-08","updated_at":"2026-05-08"}]}
 {"type":"discussion","id":"DSC-0034","status":"done","ticket":"frontend-semantic-host-projection-flexibility","title":"Frontend semantic vocabulary flexibility and declarative host projection","created_at":"2026-05-06","updated_at":"2026-05-07","tags":["compiler","compiler-general","frontend","semantics","vscode","host-projection","lsp"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0034-frontend-semantic-host-projection-flexibility/LSN-0048-frontend-owned-semantic-vocabularies-with-declarative-host-projection.md","status":"done","created_at":"2026-05-07","updated_at":"2026-05-07"}]}
 {"type":"discussion","id":"DSC-0033","status":"done","ticket":"frontend-visual-theme-spec-and-css-retirement","title":"Frontend visual theme spec and retirement of host-consumed semantic CSS","created_at":"2026-05-06","updated_at":"2026-05-08","tags":["compiler","compiler-general","frontend","presentation","theming","studio","vscode","lsp","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0050","file":"discussion/lessons/DSC-0033-frontend-visual-theme-spec-and-css-retirement/LSN-0050-frontend-owned-visual-themes-with-structured-contract-and-host-adapters.md","status":"done","created_at":"2026-05-08","updated_at":"2026-05-08"}]}

discussion/workflow/plans/PLN-0098-expose-doc-metadata-through-pbs-editorial-and-lsp-surfaces.md

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

prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialCompletionCandidate.java

@@ -6,12 +6,22 @@ public record PbsEditorialCompletionCandidate(
         String label,
         PbsEditorialSymbolKind kind,
         String detail,
-        String origin) {
+        String origin,
+        String documentation) {
+    public PbsEditorialCompletionCandidate(
+            final String label,
+            final PbsEditorialSymbolKind kind,
+            final String detail,
+            final String origin) {
+        this(label, kind, detail, origin, "");
+    }
+
     public PbsEditorialCompletionCandidate {
         label = requireText(label, "label");
         kind = Objects.requireNonNull(kind, "kind");
         detail = normalize(detail);
         origin = normalize(origin);
+        documentation = normalize(documentation);
     }
 
     private static String requireText(

prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialSupportService.java

@@ -482,10 +482,11 @@ public final class PbsEditorialSupportService {
                     }
                     for (final var method : structInfo.methods().entrySet()) {
                         completions.put(method.getKey(), new PbsEditorialCompletionCandidate(
-                                method.getKey(),
+                        method.getKey(),
-                                PbsEditorialSymbolKind.METHOD,
+                        PbsEditorialSymbolKind.METHOD,
-                                formatCallableDetails(method.getValue()),
+                        formatCallableDetails(method.getValue()),
-                                receiverType.name()));
+                        receiverType.name(),
+                        documentationFromCallables(method.getValue())));
                     }
                 }
             } else if (receiverType.kind() == Kind.SERVICE || receiverType.kind() == Kind.CONTRACT) {
@@ -494,10 +495,11 @@ public final class PbsEditorialSupportService {
                         : Optional.ofNullable(model.contracts.get(receiverType.name())).map(ContractInfo::methods).orElse(Map.of());
                 for (final var method : methods.entrySet()) {
                     completions.put(method.getKey(), new PbsEditorialCompletionCandidate(
-                            method.getKey(),
+                        method.getKey(),
-                            PbsEditorialSymbolKind.METHOD,
+                        PbsEditorialSymbolKind.METHOD,
-                            formatCallableDetails(method.getValue()),
+                        formatCallableDetails(method.getValue()),
-                            receiverType.name()));
+                        receiverType.name(),
+                        documentationFromCallables(method.getValue())));
                 }
             }
             return List.copyOf(completions.values());
@@ -751,7 +753,8 @@ public final class PbsEditorialSupportService {
                     topDeclSymbol.localName(),
                     symbolKind(topDeclSymbol.decl()),
                     detail,
-                    topDeclSymbol.origin());
+                    topDeclSymbol.origin(),
+                    documentationFromTopDecl(topDeclSymbol.decl()));
         }
 
         private List<PbsEditorialSignature> signaturesForTopDecl(final PbsAst.TopDecl topDecl) {

prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridge.java

@@ -288,7 +288,7 @@ public final class CompilerLanguageServiceBridge implements LanguageServiceBridg
                 candidate.label(),
                 mapCompletionKind(candidate.kind()),
                 candidate.detail(),
-                candidate.origin());
+                candidate.documentation().isBlank() ? candidate.origin() : candidate.documentation());
     }
 
     private BaselineVisualTheme mapVisualTheme(final FrontendVisualThemeSpec theme) {

prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridgeTest.java

@@ -217,6 +217,50 @@ class CompilerLanguageServiceBridgeTest {
         assertFalse(signatureHelp.signatures().getFirst().label().contains("arg0"));
     }
 
+    @Test
+    void hoverAndCompletionExposeCompilerResolvedDocMarkdown() {
+        final Path projectRoot = findRepoRoot(Path.of("").toAbsolutePath().normalize())
+                .resolve("test-projects")
+                .resolve("main")
+                .toAbsolutePath()
+                .normalize();
+        final Path documentPath = projectRoot.resolve("src").resolve("main.pbs");
+        final String overlay = """
+                [Doc(markdown = \"""
+                Computes the answer.
+                \""")]
+                fn helper() -> int { return 42; }
+
+                fn frame() -> void {
+                  helper();
+                }
+                """;
+        final CompilerLanguageServiceBridge bridge = new CompilerLanguageServiceBridge();
+        final LspProjectContext context = new LspProjectContext("main", "pbs", projectRoot);
+        final DocumentPositionMapper mapper = new DocumentPositionMapper(overlay);
+        final var helperPosition = mapper.positionOf(overlay.indexOf("helper();"));
+
+        final var hover = bridge.hover(
+                context,
+                documentPath.toUri().toString(),
+                overlay,
+                helperPosition.line(),
+                helperPosition.character());
+        assertTrue(hover.markdown().contains("Computes the answer."));
+
+        final var completion = bridge.completion(
+                context,
+                documentPath.toUri().toString(),
+                overlay,
+                helperPosition.line(),
+                helperPosition.character());
+        final var helper = completion.items().stream()
+                .filter(item -> item.label().equals("helper"))
+                .findFirst()
+                .orElseThrow();
+        assertEquals("Computes the answer.", helper.documentation());
+    }
+
     @Test
     void describeServerPublishesFrontendVisualThemes() {
         final CompilerLanguageServiceBridge bridge = new CompilerLanguageServiceBridge();