cleanup

discussion/index.ndjson

@@ -1,4 +1,4 @@
-{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":42,"PLN":111,"LSN":57,"CLSN":1}}
+{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":42,"PLN":111,"LSN":58,"CLSN":1}}
 {"type":"discussion","id":"DSC-0065","status":"open","ticket":"multi-frontend-avoid-premature-abstractions","title":"Evitar abstracoes prematuras na preparacao multi-frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","architecture","multi-frontend","simplicity"],"agendas":[{"id":"AGD-0068","file":"AGD-0068-multi-frontend-avoid-premature-abstractions.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0064","status":"open","ticket":"multi-frontend-architectural-tests","title":"Testes arquiteturais para fronteiras multi-frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","architecture","tests","multi-frontend"],"agendas":[{"id":"AGD-0067","file":"AGD-0067-multi-frontend-architectural-tests.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0063","status":"open","ticket":"multi-frontend-synthetic-test-frontend","title":"Frontend sintetico de teste para provar neutralidade do pipeline","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","frontend","tests","backend","multi-frontend"],"agendas":[{"id":"AGD-0066","file":"AGD-0066-multi-frontend-synthetic-test-frontend.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
@@ -28,7 +28,7 @@
 {"type":"discussion","id":"DSC-0039","status":"open","ticket":"pbs-lsp-go-to-definition","title":"PBS LSP Go to Definition","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","definition"],"agendas":[{"id":"AGD-0042","file":"AGD-0042-pbs-lsp-go-to-definition.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
 {"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":"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":"done","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":"done","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":"done","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":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]}],"lessons":[]}
+{"type":"discussion","id":"DSC-0036","status":"done","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":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0057","file":"discussion/lessons/DSC-0036-pbs-symbol-documentation-and-hover-markdown/LSN-0057-compiler-owned-pbs-doc-markdown-for-editor-assistance.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
 {"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/lessons/DSC-0036-pbs-symbol-documentation-and-hover-markdown/LSN-0057-compiler-owned-pbs-doc-markdown-for-editor-assistance.md

@@ -0,0 +1,104 @@
+---
+id: LSN-0057
+ticket: pbs-symbol-documentation-and-hover-markdown
+title: Compiler-Owned PBS Doc Markdown for Editor Assistance
+created: 2026-07-15
+tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
+---
+
+## Original Problem
+
+PBS editor assistance had compiler-backed completion, hover, and signature-help surfaces, but it did not yet have a canonical authored documentation model for named API symbols.
+
+Without that model, hover could show mechanical facts such as kind, signature, origin, and type shape, but it could not reliably explain intent, parameter meaning, semantic constraints, or usage notes. Any editor-side solution would have risked reparsing PBS source or inventing a second documentation binding model outside the compiler.
+
+## Consolidated Decision
+
+PBS symbol documentation is authored with a reserved compiler-recognized `Doc` attribute:
+
+```pbs
+[Doc(markdown = """
+Draws a sprite.
+
+- `x`: screen x coordinate
+- `y`: screen y coordinate
+""")]
+```
+
+The v1 shape is intentionally narrow:
+
+1. `Doc` has exactly one required named argument, `markdown`.
+2. The `markdown` argument uses a triple-quoted documentation text block.
+3. The text block is documentation-only metadata, not a general runtime multiline string literal.
+4. `[Doc]` attaches to the following declaration using the normal PBS attribute association rule.
+5. Attribute order is semantically irrelevant.
+6. Parameters do not receive `[Doc]` in v1; parameter notes live inside the owning declaration's Markdown.
+7. Duplicate `Doc`, missing `markdown`, extra arguments, aliases, positional arguments, empty normalized payloads, and invalid targets are semantic errors.
+
+The compiler owns documentation resolution. LSP and editor consumers receive normalized compiler metadata; they must not reparse PBS source to discover documentation.
+
+## Final Implementation Shape
+
+The work landed as a staged compiler-to-editor pipeline:
+
+1. PBS specs define the syntax, static semantics, AST shape, diagnostics, and stdlib documentation policy for `[Doc(markdown = """...""")]`.
+2. The PBS lexer recognizes triple-quoted documentation text blocks without changing ordinary string literal behavior.
+3. The parser and AST preserve documentation text block payloads and spans as structured attribute values.
+4. A shared normalizer removes incidental surrounding blank lines and common indentation while preserving Markdown content and internal line breaks.
+5. Semantic validation reserves `Doc` and enforces the single canonical v1 shape.
+6. Normalized Markdown is attached to resolved PBS semantic symbols as structured documentation metadata.
+7. PBS editorial and LSP surfaces transport that metadata without source reparsing.
+8. Hover composition includes the normalized Markdown while preserving existing fallback behavior for undocumented symbols.
+9. Stdlib, SDK, and interface declarations use the same authored documentation surface.
+10. Runtime-facing artifacts remain unchanged by documentation metadata.
+
+This preserves a clean boundary: PBS source authors write documentation in the language, the compiler resolves it, LSP transports it, and editors render it.
+
+## Examples
+
+Valid documentation belongs on named API declarations that introduce semantic symbols and can carry attributes, such as functions, methods, services, hosts, interface declarations, and repository-owned stdlib or SDK declarations.
+
+Parameter documentation is written inside the callable's Markdown:
+
+```pbs
+[Doc(markdown = """
+Fills a rectangle.
+
+- `x`: left edge in screen coordinates
+- `y`: top edge in screen coordinates
+- `width`: rectangle width in pixels
+- `height`: rectangle height in pixels
+""")]
+```
+
+Invalid v1 forms include:
+
+```pbs
+[Doc("Draws a sprite.")]
+[Doc(text = """Draws a sprite.""")]
+[Doc(markdown = """Draws a sprite.""", format = "markdown")]
+[Documentation(markdown = """Draws a sprite.""")]
+```
+
+These are rejected because accepting aliases or positional shortcuts would immediately expand the language contract and make future compatibility harder.
+
+## Pitfalls
+
+Do not treat `"""..."""` as a general PBS runtime string literal. Runtime multiline strings raise separate questions about type behavior, lowering, constant pools, equality, escaping, and artifact representation.
+
+Do not let LSP or editor code rediscover documentation by scanning source. That duplicates language semantics outside the compiler and breaks as soon as imports, stdlib declarations, interface modules, or generated sources participate.
+
+Do not attach `[Doc]` to parameters in v1. Parameter docs are authored inside the declaration Markdown so the compiler can keep one documentation payload per API symbol.
+
+Do not reflow authored Markdown in a formatter or hover composer. The normalizer may remove incidental indentation, but it must preserve the author's Markdown content.
+
+Do not lower documentation into runtime artifacts by default. Documentation is compile/editor metadata unless a future runtime or packaging decision explicitly changes that boundary.
+
+## References
+
+- `DEC-0039` captured the normative decision for PBS `Doc` markdown text blocks.
+- `PLN-0092` specified the PBS docs and diagnostics contract.
+- `PLN-0093` through `PLN-0099` implemented lexer, parser, normalization, semantics, symbol metadata, LSP exposure, and hover composition.
+- `PLN-0100` authored stdlib, SDK, and interface documentation.
+- `PLN-0101` protected runtime artifacts from documentation lowering.
+- `PLN-0102` closed end-to-end conformance coverage.

discussion/workflow/agendas/AGD-0039-pbs-symbol-documentation-and-hover-markdown.md

@@ -1,187 +0,0 @@
----
-id: AGD-0039
-ticket: pbs-symbol-documentation-and-hover-markdown
-title: Modelo de documentacao de simbolos em PBS e consumo markdown no hover
-status: accepted
-created: 2026-05-08
-tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
----
-
-## Pain
-
-A wave atual de assistencia editorial quer `hover` util, mas ainda nao existe um modelo claro para documentacao authored dentro de PBS.
-
-Sem esse modelo, o hover pode até mostrar:
-
-- kind;
-- assinatura;
-- origem;
-- tipo/shape.
-
-Mas continua sem uma superficie limpa para explicar intencao de uso, contrato semantico, detalhes de parametros ou observacoes de API.
-
-Hoje a direcao consolidada eh algo como:
-
-- `[Doc(markdown = """qualquer markdown aqui dentro...""")]`
-
-como anotacao consumida diretamente pelo hover.
-
-Isso parece simples no uso, mas toca em decisoes de linguagem e contrato editorial que merecem discussao propria.
-
-## Context
-
-Domain owner: `compiler/pbs`
-
-Subdomains touched:
-
-- `compiler/general`
-- `studio/lsp`
-- `tools/vscode-extension`
-
-Esta agenda eh deliberadamente separada de `AGD-0038`.
-
-Razao:
-
-- `AGD-0038` trata da wave 1 de `completion`, `hover` e `signature help`;
-- esta nova agenda trata da autoria, armazenamento, propagacao e consumo de documentacao de simbolos.
-
-O objetivo eh evitar que a primeira wave de assistencia editorial fique bloqueada por uma decisao de linguagem ainda nao fechada.
-
-## Open Questions
-
-- A autoria da documentacao deve acontecer por anotacao explicita como `[Doc(...)]`, por comentario estruturado, ou por outro mecanismo?
-- O payload authored deve aceitar um subset Markdown como fonte canonica, ou deve haver outra normalizacao/restricao?
-- Quais declaracoes nomeadas de API podem carregar documentacao na wave inicial:
-  funcoes, methods, classes/structs, services, hosts, builtin/stdlib declarations e interface declarations?
-- A documentacao deve viver no AST/semantics como superficie compiler-backed explicita?
-- Como a documentacao authored em PBS se relaciona com documentacao de stdlib gerada ou importada de outras fontes?
-- O hover deve consumir markdown pronto sem transformacao, ou deve haver um pipeline intermediario de sanitizacao/normalizacao?
-- Como tratar multilinhas, escaping e ergonomia de escrita se a surface for `[Doc(...)]`?
-- A agenda deve definir apenas o modelo de autoria, ou tambem o transporte LSP e a composicao final do hover?
-
-## Options
-
-### Option A - Anotacao `[Doc(...)]` com Markdown subset como payload canonico
-
-- **Approach:** introduzir uma anotacao explicita na linguagem PBS cujo conteudo ja eh markdown pronto para o hover.
-- **Pro:** autoria direta, intencao clara, pipeline simples de consumo no LSP e no hover.
-- **Con:** precisa desenhar sintaxe, escaping, multiline e regras de onde a anotacao eh permitida.
-- **Maintainability:** forte se a surface de linguagem ficar limpa.
-
-### Option B - Comentarios estruturados como fonte de documentacao
-
-- **Approach:** usar comentarios especiais ou doc-comments, com parser especifico para gerar documentacao de simbolo.
-- **Pro:** mais familiar para quem vem de outras linguagens e menos intrusivo no corpo semantico da linguagem.
-- **Con:** exige novo contrato de binding entre comentarios e simbolos, e pode aumentar ambiguidade editorial.
-- **Maintainability:** media.
-
-### Option C - Nao definir autoria em PBS agora e suportar apenas docs de stdlib por metadata externa
-
-- **Approach:** deixar a linguagem sem surface authored por enquanto e alimentar hover apenas com docs externas/geradas.
-- **Pro:** menor custo imediato de linguagem.
-- **Con:** resolve mal a autoria de codigo de usuario e deixa o modelo incompleto.
-- **Maintainability:** fraca.
-
-## Tradeoffs
-
-Option C nao parece suficiente como direcao de produto se a intencao eh ter hover realmente util para APIs authored em PBS.
-
-Option B eh plausivel, mas move o problema para um binding entre comentario e simbolo que tambem precisa ser projetado com cuidado. Isso costuma parecer mais barato do que realmente eh.
-
-Option A tem um custo claro de sintaxe e modelo, mas pelo menos deixa explicito que documentacao eh metadado semantico e nao apenas texto solto ao redor do codigo.
-
-Se a equipe realmente quer markdown authored pronto para consumo no hover, Option A parece a discussao mais direta e honesta.
-
-## Recommendation
-
-Discutir esta agenda com viés inicial para **Option A** e fechar a decision com um shape canonico unico:
-
-```pbs
-[Doc(markdown = """
-Draws a sprite.
-
-- `x`: screen x
-- `y`: screen y
-""")]
-```
-
-O consenso da discussao eh que `Doc` eh curto e pratico, e que o nome do argumento `markdown` ja carrega a semantica do payload. Um prefixo lexical como `md"""..."""` nao deve entrar na v1 porque adiciona uma nova familia de literais antes de haver necessidade concreta para multiplos payloads especializados.
-
-A recomendacao preliminar eh separar o problema em duas perguntas:
-
-1. qual eh a surface canonical de autoria da documentacao em PBS?
-2. como essa documentacao vira um payload editorial resolvido para hover e futuros consumers?
-
-Mesmo que `[Doc(...)]` seja a direcao vencedora, a decision deve deixar claro:
-
-- onde ela pode ser usada;
-- qual formato textual aceita;
-- como ela eh preservada no compiler;
-- como chega ao LSP;
-- e como o hover deve compor isso com assinatura e metadados do simbolo.
-
-## Proposed Resolution
-
-Fechar a agenda com a seguinte direcao:
-
-- PBS deve suportar documentacao explicita de simbolos por atributo `[Doc(markdown = """...""")]`.
-- `Doc` deve ter um unico shape canonico na v1: argumento nomeado `markdown` com payload em triple-quoted text block.
-- O atributo segue a regra normal de atributos PBS: associa-se a declaracao imediatamente seguinte.
-- `[Doc]` deve ser valido para declaracoes nomeadas de API que introduzem simbolo semantico nomeado e que possam carregar atributos, incluindo funcoes, methods, classes/structs, services, hosts, builtin/stdlib declarations e interface declarations.
-- Parametros nao devem receber `[Doc]` na v1 em nenhuma situacao; a documentacao de parametros deve viver no Markdown da declaracao que os possui.
-- A intencao normativa eh nao limitar artificialmente declaracoes documentaveis por origem; se algum ponto da gramatica de declaracao ainda nao aceita atributos, o plano deve tratar isso como trabalho sintatico explicito.
-- A ordem entre `[Doc]` e outros atributos deve ser irrelevante.
-- Mais de um `[Doc]` no mesmo simbolo deve ser erro semantico, nao erro de parse.
-- `[Doc]` sem `markdown`, com argumentos extras, com payload vazio/whitespace-only, ou aplicado fora da superficie documentavel deve produzir diagnostico claro.
-- O payload `"""..."""` deve ser tratado inicialmente como text block documental, nao como string runtime geral de PBS.
-- O text block deve aplicar normalizacao de indentacao equivalente ao modelo de text blocks de Java/Javadoc: remover linhas externas vazias incidentais, calcular indentacao comum das linhas nao vazias, remover essa indentacao comum, preservar quebras internas e preservar o conteudo Markdown.
-- O compiler deve preservar o Markdown normalizado como metadata semantica do simbolo.
-- O LSP e demais consumers devem consumir documentacao resolvida pelo compiler; nao devem reparsear source para descobrir docs.
-- Um subset Markdown deve ser o protocolo de documentacao authored em PBS.
-- O Markdown deve ser definido como payload editorial preservado, nao como garantia de renderizacao identica em todos os clientes. Renderizacao, sanitizacao e suporte a constructs especificos sao responsabilidades do consumer.
-- Formatters devem preservar o conteudo interno do text block e nao devem reflowar Markdown authored.
-- Rename/refactor nao precisa atualizar referencias textuais dentro do Markdown nesta fase do projeto.
-- Specs e documentacao da stdlib devem ser escritas em ingles.
-- Testes devem validar o payload Markdown normalizado no compiler/LSP; validacao visual no VSCode pode ser manual.
-- Stdlib, SDK e interface modules devem usar o mesmo modelo `[Doc(markdown = """...""")]` para documentacao authored.
-- Se no futuro houver documentacao importada ou gerada, documentacao authored no source deve ter precedencia, e conflitos devem ter regra deterministica ou diagnostico explicito.
-
-## Maintenance Friction Points
-
-Pontos que a decision e o plano devem proteger para evitar que uma feature simples de editor vire divida de linguagem:
-
-- "Todas as declaracoes nomeadas de API documentaveis" precisa ser especificado como "toda declaracao de API que introduz simbolo semantico nomeado", evitando ambiguidade sobre parametros, fields, enum cases, tuple fields, expressoes e variaveis locais.
-- A gramatica de atributos pode precisar ser expandida para declaracoes que hoje ainda nao aceitam atributos; isso deve ser tratado como parte real do trabalho, nao como excecao informal.
-- A v1 nao deve aceitar aliases como `text`, argumento posicional, `html`, `format`, `Document`, `Documentation`, ou `md"""..."""`.
-- `"""..."""` nao deve virar literal runtime geral sem uma decision propria.
-- A normalizacao do text block deve ser especificada no texto normativo, nao apenas referenciada informalmente como "igual Java".
-- Parametros nao recebem `[Doc]` na v1; fields, enum cases e tuple fields so devem receber `[Doc]` se a decision os classificar explicitamente como declaracoes nomeadas de API documentaveis.
-- O formatter futuro eh um ponto sensivel: ele pode alinhar a declaracao, mas nao pode alterar o Markdown authored dentro do text block.
-- A composicao visual do hover pode ficar para plano/implementacao, mas a ownership deve ficar clara: compiler resolve documentacao; LSP transporta; editor renderiza.
-
-## Discussion
-
-Esta agenda nao deve ser reduzida a "mostrar markdown no hover".
-
-O problema real eh definir ownership e boundary da documentacao:
-
-- o author escreve onde?
-- o compiler preserva como?
-- o LSP transporta em qual shape?
-- o hover monta o resultado com qual ordem e responsabilidade?
-
-Tambem vale observar que a escolha aqui pode influenciar mais do que hover:
-
-- completions futuras podem querer `detail` e `documentation`;
-- signature help pode querer descricoes de parametros;
-- docs de stdlib podem querer surface unificada com docs authored.
-
-Por isso, mesmo sendo uma agenda separada, ela conversa diretamente com a futura qualidade do editor.
-
-## Resolution
-
-Consenso de agenda formado em favor de `[Doc(markdown = """...""")]` como anotacao explicita, compiler-owned, com payload em subset Markdown e text block documental normalizado.
-
-## Next Step
-
-Aceitar a agenda e fechar uma `decision` propria para o modelo de documentacao de simbolos em PBS.

discussion/workflow/decisions/DEC-0039-pbs-symbol-documentation-with-doc-markdown-text-blocks.md

@@ -1,137 +0,0 @@
----
-id: DEC-0039
-ticket: pbs-symbol-documentation-and-hover-markdown
-title: PBS symbol documentation with Doc markdown text blocks
-status: accepted
-created: 2026-07-15
-ref_agenda: AGD-0039
-tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
----
-
-## Context
-
-PBS editor assistance needs hover content that can explain author intent, API contracts, parameter meaning, semantic constraints, and usage notes. Existing symbol surfaces can expose mechanical information such as kind, signature, origin, and type/shape, but PBS does not yet define a canonical authored documentation model.
-
-This decision belongs to domain owner `compiler/pbs`.
-
-Touched subdomains:
-
-- `compiler/general`
-- `studio/lsp`
-- `tools/vscode-extension`
-
-This decision resolves `AGD-0039`. It does not replace the existing wave-1 editor-assistance work; it defines the source-language and compiler-backed documentation model that hover, completion, signature help, stdlib documentation, and future editor consumers can reuse.
-
-## Decision
-
-PBS MUST support explicit authored documentation for named API declarations through a reserved `[Doc]` attribute.
-
-The only canonical v1 shape is:
-
-```pbs
-[Doc(markdown = """
-Draws a sprite.
-
-- `x`: screen x
-- `y`: screen y
-""")]
-```
-
-`Doc` MUST be a reserved compiler-recognized attribute name. It MUST NOT be treated as an ordinary user-defined attribute with language-specific reinterpretation.
-
-`Doc` MUST use a single required argument named `markdown`. The `markdown` argument MUST use a triple-quoted documentation text block as its payload. The v1 surface MUST NOT accept aliases or alternate forms such as `text`, positional arguments, `html`, `format`, `Document`, `Documentation`, or `md"""..."""`.
-
-`[Doc]` MUST attach to the declaration immediately following it, following the normal PBS attribute association rule. Attribute order MUST be semantically irrelevant; `[Doc]` before or after other attributes on the same declaration MUST produce the same documentation result.
-
-`[Doc]` MUST be valid only on named API declarations that introduce named semantic symbols and can carry attributes. The v1 documentable surface includes:
-
-- functions;
-- methods;
-- classes/structs, when present in the PBS declaration surface;
-- services;
-- hosts;
-- builtin and stdlib declarations;
-- interface declarations.
-
-Parameters MUST NOT receive `[Doc]` in v1 under any circumstance. Parameter documentation, when needed, MUST be authored inside the Markdown payload of the owning declaration.
-
-Fields, enum cases, tuple fields, local variables, expressions, and other non-API declaration surfaces MUST NOT receive `[Doc]` unless a future decision explicitly classifies them as named API declarations documentable by `[Doc]`.
-
-The `markdown` payload MUST be a PBS documentation text block, not a general runtime string literal. `"""..."""` MUST NOT become a general PBS runtime string literal as part of this decision.
-
-The documentation text block MUST be normalized before semantic validation and before exposure to editor consumers. Normalization MUST:
-
-- remove an incidental leading empty line after the opening delimiter;
-- remove an incidental trailing empty line before the closing delimiter;
-- compute the common indentation of non-empty content lines;
-- remove that common indentation;
-- preserve internal line breaks;
-- preserve Markdown content after indentation normalization.
-
-After normalization, an empty or whitespace-only documentation payload MUST be rejected.
-
-The authored documentation format for PBS v1 MUST be a supported Markdown subset. PBS defines Markdown as the documentation protocol, not as a guarantee that every client renders every Markdown construct identically.
-
-The compiler MUST preserve normalized Markdown documentation as semantic metadata of the documented symbol. LSP and editor consumers MUST consume compiler-resolved documentation metadata; they MUST NOT reparse PBS source to discover documentation.
-
-`[Doc]` MUST be compile/editor metadata. It MUST NOT be lowered into runtime or cartridge artifacts unless a future runtime or packaging decision explicitly requires that.
-
-Stdlib, SDK, and interface modules MUST use the same `[Doc(markdown = """...""")]` model for authored documentation. If imported or generated documentation exists in the future, authored source documentation MUST take precedence. Conflicts MUST be deterministic or produce explicit diagnostics.
-
-## Rationale
-
-An explicit attribute keeps documentation attached to language-owned semantic symbols instead of relying on proximity between comments and declarations. This avoids a separate comment-binding model and gives the compiler one canonical source of truth for editor assistance.
-
-The short attribute name `Doc` is practical at the authoring site and remains clear when paired with the required `markdown` argument. The argument name carries the payload format, so a prefixed literal such as `md"""..."""` would add lexer and grammar surface without enough v1 benefit.
-
-Restricting the v1 shape to `[Doc(markdown = """...""")]` protects maintainability. It avoids aliases, ambiguous forms, and compatibility pressure around multiple documentation payload formats.
-
-Restricting triple-quoted text blocks to documentation avoids accidentally introducing general multiline runtime strings. Runtime strings raise separate questions about type behavior, lowering, constant pools, equality, escapes, and artifact representation; those questions do not belong to this documentation decision.
-
-Compiler ownership keeps hover, completion, signature help, stdlib docs, and future editor consumers aligned. The LSP layer should transport resolved documentation, not infer language semantics from raw source text.
-
-## Implications
-
-- PBS syntax and parsing MUST recognize triple-quoted documentation text blocks in `[Doc(markdown = ...)]`.
-- PBS semantic validation MUST enforce the canonical `Doc` shape, allowed declaration sites, duplicate detection, empty-payload rejection, and invalid-argument diagnostics.
-- A declaration MUST NOT have more than one `[Doc]`; duplicates MUST be semantic errors rather than parse errors.
-- Formatter implementations MUST preserve the internal Markdown text of documentation blocks and MUST NOT reflow authored Markdown.
-- Rename/refactor tools are not required in this phase to update textual references inside Markdown documentation.
-- Specs and stdlib documentation authored for repository-owned surfaces MUST be written in English.
-- Tests SHOULD validate normalized Markdown payloads at compiler and LSP boundaries. VSCode visual validation may remain manual for this wave.
-- Hover composition may be implemented later, but the ownership boundary is fixed: compiler resolves documentation, LSP transports it, and the editor renders it.
-
-## Propagation Targets
-
-- specs:
-  - `docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md`
-  - `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md`
-  - `docs/specs/compiler-languages/pbs/11. AST Specification.md`
-  - `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md`
-  - `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
-  - LSP/editor-facing specs if/when a dedicated Studio/LSP spec surface exists.
-- plans:
-  - Create an implementation plan for syntax, AST, semantics, documentation metadata, LSP exposure, tests, and stdlib authoring.
-- code:
-  - PBS lexer/parser/AST.
-  - PBS semantic validation and symbol/editorial surfaces.
-  - LSP hover/editorial transport.
-  - Stdlib/interface PBS sources.
-- tests:
-  - Lexer/parser coverage for documentation text blocks.
-  - Semantic diagnostics for invalid `Doc` usage.
-  - Normalization tests for indentation and empty payloads.
-  - Compiler/editorial surface tests proving documentation is attached to resolved symbols.
-  - LSP hover or symbol-documentation payload tests.
-- docs:
-  - PBS language specs.
-  - Any lessons generated after implementation and housekeeping.
-
-## References
-
-- Agenda: AGD-0039
-- Source discussion: DSC-0036
-
-## Revision Log
-
-- 2026-07-15: Initial decision drafted from accepted `AGD-0039`.

discussion/workflow/plans/PLN-0092-specify-pbs-doc-attribute-and-markdown-text-block-syntax.md

@@ -1,63 +0,0 @@
----
-id: PLN-0092
-ticket: pbs-symbol-documentation-and-hover-markdown
-title: Specify PBS Doc attribute and markdown text block syntax
-status: done
-created: 2026-07-15
-ref_decisions: [DEC-0039]
-tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
----
-
-## Briefing
-
-Update the PBS normative specs so `DEC-0039` is reflected before code changes begin. This plan is the specification gate for the `[Doc(markdown = """...""")]` feature.
-
-## Objective
-
-Define the syntax, static semantics, AST shape, diagnostics, and stdlib documentation policy for compiler-owned PBS symbol documentation.
-
-## Dependencies
-
-- Requires accepted decision `DEC-0039`.
-- Must be completed before parser, semantic, LSP, and stdlib implementation plans are accepted as complete.
-
-## Scope
-
-- Add `[Doc(markdown = """...""")]` to the PBS attribute surface.
-- Define triple-quoted documentation text blocks as documentation-only payloads, not runtime strings.
-- Define documentable named API declarations and explicitly exclude parameters.
-- Define normalization, duplicate handling, invalid shape diagnostics, and non-runtime lowering rules.
-
-## Non-Goals
-
-- Implement lexer, parser, semantics, or LSP code.
-- Define general multiline runtime strings.
-- Define VSCode rendering details beyond the compiler/LSP ownership boundary.
-
-## Execution Method
-
-1. Update `docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md` with the canonical `[Doc(markdown = """...""")]` syntax, allowed declaration sites, attribute ordering rule, and text block delimiter rules.
-2. Update `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md` with reserved `Doc` validation, duplicate rejection, parameter exclusion, empty normalized payload rejection, and non-documentable target diagnostics.
-3. Update `docs/specs/compiler-languages/pbs/11. AST Specification.md` with an AST representation for documentation attributes and documentation text block payloads.
-4. Update `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md` with required diagnostic categories for unterminated text block, invalid `Doc` shape, duplicate `Doc`, empty payload, and invalid target.
-5. Update `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md` with the rule that stdlib, SDK, and interface modules use the same authored `Doc` surface.
-
-## Acceptance Criteria
-
-- Specs define all normative rules from `DEC-0039` without deferring syntax or semantics to implementation judgment.
-- The specs explicitly state that `"""..."""` is documentation-only for this feature.
-- The specs explicitly state that parameters never receive `[Doc]` in v1.
-- The specs identify propagation boundaries: compiler resolves, LSP transports, editor renders.
-
-## Tests
-
-- Run any existing spec conformance tests that validate PBS spec references.
-- No code behavior tests are required in this plan.
-
-## Affected Artifacts
-
-- `docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md`
-- `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md`
-- `docs/specs/compiler-languages/pbs/11. AST Specification.md`
-- `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md`
-- `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md`

discussion/workflow/plans/PLN-0093-implement-pbs-lexer-support-for-documentation-text-blocks.md

@@ -1,62 +0,0 @@
----
-id: PLN-0093
-ticket: pbs-symbol-documentation-and-hover-markdown
-title: Implement PBS lexer support for documentation text blocks
-status: done
-created: 2026-07-15
-ref_decisions: [DEC-0039]
-tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
----
-
-## Briefing
-
-Add lexical support for triple-quoted documentation text blocks required by `[Doc(markdown = """...""")]`.
-
-## Objective
-
-Teach the PBS lexer to tokenize documentation text blocks without turning triple quotes into a general runtime string feature.
-
-## Dependencies
-
-- Depends on `PLN-0092` for the normative syntax.
-
-## Scope
-
-- Add a dedicated token kind for documentation text block payloads or an equivalent lexer representation.
-- Recognize `"""` open and close delimiters.
-- Preserve source text and spans for parser and diagnostics.
-- Report unterminated documentation text blocks with useful span information.
-
-## Non-Goals
-
-- Parse or validate `[Doc]` attribute shapes.
-- Normalize indentation.
-- Lower documentation to runtime artifacts.
-- Add general multiline string expressions.
-
-## Execution Method
-
-1. Update `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsTokenKind.java` with a documentation text block token if a distinct token is the cleanest local pattern.
-2. Update `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsLexer.java` to recognize `"""..."""` and preserve its raw lexeme and span.
-3. Ensure ordinary string scanning remains unchanged for `"..."`.
-4. Add or update lexer diagnostics in `LexErrors.java` only if existing unterminated-string diagnostics cannot accurately represent unterminated documentation text blocks.
-5. Add focused tests in `PbsLexerTest` for valid text blocks, multiline payloads, embedded single quotes/double quotes, and unterminated blocks.
-
-## Acceptance Criteria
-
-- The lexer can tokenize a multiline documentation text block.
-- Unterminated documentation text blocks produce a deterministic diagnostic.
-- Ordinary string literals keep current behavior.
-- `"""..."""` is not accepted as an expression-level runtime string by this plan.
-
-## Tests
-
-- `./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test` or the repository-equivalent targeted compiler frontend test task.
-- Focused `PbsLexerTest` cases for documentation text blocks.
-
-## Affected Artifacts
-
-- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsLexer.java`
-- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsTokenKind.java`
-- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/LexErrors.java`
-- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/lexer/PbsLexerTest.java`

discussion/workflow/plans/PLN-0094-extend-pbs-attribute-parser-and-ast-for-doc-markdown-payloads.md

@@ -1,59 +0,0 @@
----
-id: PLN-0094
-ticket: pbs-symbol-documentation-and-hover-markdown
-title: Extend PBS attribute parser and AST for Doc markdown payloads
-status: done
-created: 2026-07-15
-ref_decisions: [DEC-0039]
-tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
----
-
-## Briefing
-
-Extend parsing and AST representation so `[Doc(markdown = """...""")]` can be represented structurally before semantic validation.
-
-## Objective
-
-Parse documentation text block attribute values and expose them in AST without accepting alternate `Doc` shapes as valid semantics.
-
-## Dependencies
-
-- Depends on `PLN-0092`.
-- Depends on `PLN-0093` for lexer support.
-
-## Scope
-
-- Extend attribute values to carry documentation text block payloads.
-- Preserve raw payload and spans needed for normalization and diagnostics.
-- Keep parser recovery consistent with existing attribute parsing.
-
-## Non-Goals
-
-- Validate whether `Doc` is allowed on a declaration.
-- Normalize the text block.
-- Attach documentation to semantic symbols.
-
-## Execution Method
-
-1. Update `PbsAst.AttributeValue` variants in `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/ast/PbsAst.java` to include a documentation text block value or equivalent typed payload.
-2. Update `PbsAttributeParser` so attribute arguments can parse `markdown = """..."""`.
-3. Keep existing string, int, and bool attribute argument parsing unchanged.
-4. Ensure parser diagnostics remain syntax-level: malformed attribute structure is parse error; invalid `Doc` shape is left to semantic validation where possible.
-5. Add parser tests proving `Doc` attributes parse on top-level and nested declaration forms that already support attributes.
-
-## Acceptance Criteria
-
-- `[Doc(markdown = """...""")]` parses into a distinct AST value or unambiguous attribute value representation.
-- Existing attributes such as `[Init]`, `[Frame]`, `[Host(...)]`, and `[InitAllowed]` continue to parse.
-- Invalid generic attribute syntax still recovers at the same boundaries as before.
-
-## Tests
-
-- Targeted parser tests under `prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/parser`.
-- Existing PBS parser test suite.
-
-## Affected Artifacts
-
-- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/ast/PbsAst.java`
-- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsAttributeParser.java`
-- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/parser/PbsParserTest.java`

discussion/workflow/plans/PLN-0095-implement-documentation-text-block-normalization.md

@@ -1,59 +0,0 @@
----
-id: PLN-0095
-ticket: pbs-symbol-documentation-and-hover-markdown
-title: Implement documentation text block normalization
-status: done
-created: 2026-07-15
-ref_decisions: [DEC-0039]
-tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
----
-
-## Briefing
-
-Implement the normalization algorithm required before semantic validation and editor exposure.
-
-## Objective
-
-Produce normalized Markdown text from a raw documentation text block using the rules locked by `DEC-0039`.
-
-## Dependencies
-
-- Depends on `PLN-0092`.
-- Depends on `PLN-0094` for AST access to raw text block payloads.
-
-## Scope
-
-- Strip incidental leading and trailing empty lines.
-- Compute and remove common indentation from non-empty lines.
-- Preserve internal line breaks and Markdown content after normalization.
-- Provide a single reusable normalization implementation for parser/semantics/editorial surfaces.
-
-## Non-Goals
-
-- Render Markdown.
-- Sanitize Markdown for a specific editor.
-- Reflow authored text.
-
-## Execution Method
-
-1. Add a small normalization helper in the PBS frontend package, colocated with parser or semantic support according to local patterns.
-2. Feed the helper raw documentation text block content without delimiters.
-3. Normalize line endings deterministically before indentation calculation if existing source handling requires it.
-4. Validate empty/whitespace-only content after normalization.
-5. Add unit tests for no indentation, common indentation, blank first/last lines, mixed blank internal lines, Markdown lists, code spans, and whitespace-only payloads.
-
-## Acceptance Criteria
-
-- Normalized output matches the spec for all required indentation cases.
-- Whitespace-only content is detectable after normalization.
-- The normalizer does not interpret Markdown and does not alter non-indentation content.
-
-## Tests
-
-- New focused unit tests for the normalizer.
-- Parser/semantic tests that consume normalized output through `[Doc]`.
-
-## Affected Artifacts
-
-- New or existing PBS frontend helper under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs`
-- Corresponding tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs`

discussion/workflow/plans/PLN-0096-validate-doc-attribute-semantics-and-diagnostics.md

@@ -1,64 +0,0 @@
----
-id: PLN-0096
-ticket: pbs-symbol-documentation-and-hover-markdown
-title: Validate Doc attribute semantics and diagnostics
-status: done
-created: 2026-07-15
-ref_decisions: [DEC-0039]
-tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
----
-
-## Briefing
-
-Enforce the semantic contract of `[Doc]` after syntax can represent it.
-
-## Objective
-
-Reject invalid `Doc` usage and produce clear diagnostics for all invalid shapes and targets required by `DEC-0039`.
-
-## Dependencies
-
-- Depends on `PLN-0092`.
-- Depends on `PLN-0094`.
-- Depends on `PLN-0095`.
-
-## Scope
-
-- Reserve `Doc` as a compiler-recognized attribute.
-- Accept only `Doc(markdown = """...""")`.
-- Reject aliases, positional arguments, extra arguments, duplicate `Doc`, empty normalized payload, parameter targets, and non-documentable targets.
-- Keep duplicates as semantic errors rather than parse errors.
-
-## Non-Goals
-
-- Attach documentation to final symbol metadata.
-- Expose documentation through LSP.
-- Author stdlib documentation.
-
-## Execution Method
-
-1. Locate existing declaration and reserved attribute validators, including `PbsDeclarationSemanticsValidator`, `PbsDeclarationRuleValidator`, and interface-module reserved attribute checks.
-2. Add `Doc` validation in the semantic phase that already validates declaration attributes.
-3. Define allowed declaration categories according to the spec: named API declarations that can carry attributes.
-4. Add or extend `PbsSemanticsErrors` diagnostics for invalid `Doc` target, invalid shape, duplicate attribute, missing `markdown`, extra arguments, and empty payload.
-5. Add tests covering valid declaration targets and every invalid case.
-
-## Acceptance Criteria
-
-- Every invalid shape named by `DEC-0039` produces a semantic diagnostic.
-- Parameters never accept `[Doc]`.
-- Duplicate `[Doc]` on one declaration is rejected semantically.
-- Existing reserved attributes keep their current behavior.
-
-## Tests
-
-- `PbsSemanticsDeclarationsTest`
-- `PbsInterfaceModuleSemanticsTest`
-- `PbsDiagnosticsContractTest`
-
-## Affected Artifacts
-
-- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsDeclarationSemanticsValidator.java`
-- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsDeclarationRuleValidator.java`
-- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsSemanticsErrors.java`
-- PBS semantics tests

discussion/workflow/plans/PLN-0097-attach-doc-metadata-to-pbs-semantic-symbols.md

@@ -1,60 +0,0 @@
----
-id: PLN-0097
-ticket: pbs-symbol-documentation-and-hover-markdown
-title: Attach Doc metadata to PBS semantic symbols
-status: done
-created: 2026-07-15
-ref_decisions: [DEC-0039]
-tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
----
-
-## Briefing
-
-Once `[Doc]` is syntactically and semantically valid, attach normalized documentation to compiler-owned semantic symbol data.
-
-## Objective
-
-Make documentation available from resolved PBS symbols without requiring LSP or editor code to reparse source.
-
-## Dependencies
-
-- Depends on `PLN-0095`.
-- Depends on `PLN-0096`.
-
-## Scope
-
-- Introduce an internal documentation metadata model with format and text.
-- Attach normalized Markdown to documented named API symbols.
-- Preserve the distinction between documentation metadata and runtime semantics.
-
-## Non-Goals
-
-- Render hover markdown.
-- Write stdlib documentation content.
-- Lower documentation into runtime artifacts.
-
-## Execution Method
-
-1. Add a compiler-side documentation metadata model, for example `format = markdown` plus normalized `text`.
-2. Extend symbol or editorial-resolution structures so documented declarations expose this metadata.
-3. Update symbol collection/binding paths for functions, methods, structs/classes, services, hosts, builtin/stdlib declarations, and interface declarations.
-4. Ensure imported/stdlib declarations can carry the same metadata once parsed.
-5. Add compiler tests proving documentation is attached to the intended declaration and not to parameters or unrelated symbols.
-
-## Acceptance Criteria
-
-- Resolved symbols can expose documentation as structured metadata, not an untyped hover-only string.
-- Documentation metadata is absent for undocumented symbols.
-- Documentation does not change type checking, name resolution, or runtime behavior.
-
-## Tests
-
-- Focused PBS semantic/editorial support tests.
-- Existing name resolution and declaration tests to catch regressions.
-
-## Affected Artifacts
-
-- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics`
-- `PbsEditorialResolvedSymbol`
-- `PbsEditorialSupportService`
-- Symbol/declaration binding code touched by documented declaration categories

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

@@ -1,60 +0,0 @@
----
-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

discussion/workflow/plans/PLN-0099-render-doc-markdown-in-hover-composition.md

@@ -1,60 +0,0 @@
----
-id: PLN-0099
-ticket: pbs-symbol-documentation-and-hover-markdown
-title: Render Doc markdown in hover composition
-status: done
-created: 2026-07-15
-ref_decisions: [DEC-0039]
-tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
----
-
-## Briefing
-
-Use transported documentation metadata in hover output while preserving the compiler/LSP/editor ownership boundary.
-
-## Objective
-
-Compose hover Markdown from signature/kind metadata and normalized `[Doc]` documentation.
-
-## Dependencies
-
-- Depends on `PLN-0098`.
-
-## Scope
-
-- Add documentation content to PBS hover composition.
-- Keep Markdown rendering responsibility in the editor/client.
-- Preserve hover behavior for undocumented symbols.
-
-## Non-Goals
-
-- Automate VSCode visual tests.
-- Define a full documentation website generator.
-- Change signature help parameter documentation behavior.
-
-## Execution Method
-
-1. Locate the PBS hover composition path in `PbsEditorialSupportService` and LSP bridge/mapping code.
-2. Compose hover Markdown in deterministic order: signature/kind surface, documentation Markdown, then origin/type/shape metadata as currently appropriate.
-3. Avoid escaping or reflowing normalized Markdown beyond safe composition separators.
-4. Ensure undocumented symbols keep existing hover output.
-5. Add hover tests with paragraphs, lists, and code spans from `[Doc]`.
-
-## Acceptance Criteria
-
-- Hover includes normalized authored Markdown for documented symbols.
-- Hover does not include empty documentation sections.
-- Markdown lists do not become accidental code blocks due to indentation.
-- VSCode validation remains manual for this wave.
-
-## Tests
-
-- PBS editorial hover tests.
-- LSP hover mapping tests that assert `MarkupKind.MARKDOWN` payloads.
-
-## Affected Artifacts
-
-- `PbsEditorialSupportService`
-- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler`
-- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/mapping`
-- Hover-related tests

discussion/workflow/plans/PLN-0100-author-doc-metadata-for-stdlib-sdk-and-interface-declarations.md

@@ -1,60 +0,0 @@
----
-id: PLN-0100
-ticket: pbs-symbol-documentation-and-hover-markdown
-title: Author Doc metadata for stdlib SDK and interface declarations
-status: done
-created: 2026-07-15
-ref_decisions: [DEC-0039]
-tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
----
-
-## Briefing
-
-Apply the new documentation model to repository-owned PBS stdlib, SDK, and interface declarations.
-
-## Objective
-
-Author English `[Doc(markdown = """...""")]` documentation for stdlib/API surfaces so editor assistance has useful content.
-
-## Dependencies
-
-- Depends on `PLN-0092`.
-- Should run after `PLN-0096` so authored docs are validated by compiler tests.
-- Benefits from `PLN-0099` for hover verification but does not require it to author source docs.
-
-## Scope
-
-- Add English Markdown documentation to stdlib, SDK, and interface declarations.
-- Document parameters inside the owning declaration Markdown.
-- Keep documentation concise and API-focused.
-
-## Non-Goals
-
-- Add `[Doc]` to parameters.
-- Generate external documentation sites.
-- Change stdlib semantics or host binding behavior.
-
-## Execution Method
-
-1. Inventory stdlib and SDK PBS files under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib`.
-2. Add `[Doc(markdown = """...""")]` to public named API declarations that users see in completion/hover.
-3. Document parameter meaning inside callable Markdown when needed.
-4. Ensure host/interface declarations use the same `Doc` shape.
-5. Run stdlib compile and interface conformance tests.
-
-## Acceptance Criteria
-
-- Public stdlib/SDK declarations that are user-facing have concise English documentation.
-- No parameters receive `[Doc]`.
-- Existing stdlib behavior and host ABI bindings are unchanged.
-
-## Tests
-
-- `PbsGateUStdlibCompileTest`
-- `PbsGateUSdkInterfaceConformanceTest`
-- Relevant PBS frontend tests.
-
-## Affected Artifacts
-
-- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/**`
-- Stdlib/interface compile tests

discussion/workflow/plans/PLN-0101-protect-runtime-artifacts-from-doc-metadata-lowering.md

@@ -1,58 +0,0 @@
----
-id: PLN-0101
-ticket: pbs-symbol-documentation-and-hover-markdown
-title: Protect runtime artifacts from Doc metadata lowering
-status: done
-created: 2026-07-15
-ref_decisions: [DEC-0039]
-tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
----
-
-## Briefing
-
-Guard the decision that `[Doc]` is compile/editor metadata and must not be lowered into runtime artifacts by default.
-
-## Objective
-
-Ensure documentation metadata does not affect IR, bytecode, cartridge output, stack behavior, or runtime validation.
-
-## Dependencies
-
-- Depends on `PLN-0097`.
-- Should be validated before end-to-end conformance closure.
-
-## Scope
-
-- Confirm lowering ignores `Doc` metadata.
-- Add regression tests comparing runtime-facing output with and without docs where practical.
-- Protect constant pool and cartridge artifacts from documentation payload bloat.
-
-## Non-Goals
-
-- Define a future packaging format for documentation.
-- Remove compiler/editor metadata before LSP consumption.
-
-## Execution Method
-
-1. Inspect PBS lowering paths under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering`.
-2. Ensure documented declarations lower identically to undocumented declarations for runtime-facing IR/backend artifacts.
-3. Add golden or structural tests comparing compiled output for equivalent documented and undocumented programs.
-4. Ensure large documentation payloads do not appear in runtime constant pools unless a future decision explicitly changes that.
-
-## Acceptance Criteria
-
-- Runtime-facing artifacts are unchanged by adding `[Doc]`.
-- Compiler/editor metadata remains available before lowering for LSP/editor consumers.
-- Golden artifact tests or equivalent regression tests cover this boundary.
-
-## Tests
-
-- `PbsGoldenArtifactsTest`
-- Backend/lowering tests relevant to PBS IR output.
-- Any artifact comparison test already used by the compiler frontend.
-
-## Affected Artifacts
-
-- PBS lowering package
-- Golden artifact test resources if needed
-- Compiler backend artifact tests

discussion/workflow/plans/PLN-0102-add-end-to-end-doc-documentation-conformance-coverage.md

@@ -1,73 +0,0 @@
----
-id: PLN-0102
-ticket: pbs-symbol-documentation-and-hover-markdown
-title: Add end-to-end Doc documentation conformance coverage
-status: done
-created: 2026-07-15
-ref_decisions: [DEC-0039]
-tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
----
-
-## Briefing
-
-Close the feature with end-to-end tests that prove the whole `[Doc]` contract works across compiler and LSP boundaries.
-
-## Objective
-
-Validate that syntax, normalization, semantics, metadata attachment, LSP exposure, hover composition, stdlib docs, and runtime exclusion all satisfy `DEC-0039`.
-
-## Dependencies
-
-- Depends on `PLN-0092` through `PLN-0101`.
-
-## Scope
-
-- Add integrated compiler tests for valid and invalid `[Doc]`.
-- Add LSP tests for hover documentation payloads.
-- Add conformance coverage for normalization and runtime exclusion.
-- Define a manual VSCode checklist for final visual validation.
-
-## Non-Goals
-
-- Automate VSCode UI rendering.
-- Add new documentation syntax beyond `[Doc(markdown = """...""")]`.
-- Reopen decision scope.
-
-## Execution Method
-
-1. Create one or more fixture PBS files using `[Doc]` on functions, methods, structs/classes when available, services, hosts, and interface declarations.
-2. Add negative fixtures for parameters, duplicate `Doc`, empty payload, missing `markdown`, extra arguments, alias names, and invalid targets.
-3. Add LSP tests proving hover transports Markdown and does not reparse source.
-4. Add runtime artifact tests proving docs do not lower.
-5. Record a short manual VSCode validation checklist covering paragraph rendering, list rendering, code spans, indentation behavior, and undocumented-symbol fallback.
-
-## Acceptance Criteria
-
-- All decision rules have at least one compiler or LSP test.
-- Manual VSCode validation scope is documented but not automated.
-- The feature can be implemented without returning to the agenda or decision for missing requirements.
-
-## Tests
-
-- Full relevant PBS frontend test suite.
-- Relevant LSP module tests.
-- Runtime/lowering golden tests.
-- Manual VSCode checklist execution before final housekeeping.
-
-## Manual VSCode Validation Checklist
-
-This plan intentionally does not automate VSCode UI rendering. Before final housekeeping, validate manually that:
-
-- hover renders a `Doc` paragraph below the symbol signature and kind;
-- Markdown lists render from `- item` documentation lines;
-- code spans such as `` `color` `` render as inline code;
-- normalized indentation from `[Doc(markdown = """...""")]` does not leak leading source indentation into hover;
-- undocumented symbols still show the existing hover fallback without an empty documentation block;
-- completion documentation matches the same Markdown payload used by hover.
-
-## Affected Artifacts
-
-- PBS frontend tests and fixtures
-- LSP tests and fixtures
-- Golden/runtime artifact tests
-- Optional manual validation note in the implementation PR or plan completion record