discussion/index.ndjson

@@ -1,7 +1,7 @@
-{"type":"meta","next_id":{"DSC":39,"AGD":42,"DEC":39,"PLN":92,"LSN":55,"CLSN":1}}
+{"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":"open","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-05-08","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":"open","created_at":"2026-05-08","updated_at":"2026-05-08"}],"decisions":[],"plans":[],"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":"open","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":"open","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":"open","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":"open","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":"open","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-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/agendas/AGD-0039-pbs-symbol-documentation-and-hover-markdown.md

@@ -2,7 +2,7 @@
 id: AGD-0039
 ticket: pbs-symbol-documentation-and-hover-markdown
 title: Modelo de documentacao de simbolos em PBS e consumo markdown no hover
-status: open
+status: accepted
 created: 2026-05-08
 tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
 ---
@@ -20,9 +20,9 @@ Sem esse modelo, o hover pode até mostrar:
 
 Mas continua sem uma superficie limpa para explicar intencao de uso, contrato semantico, detalhes de parametros ou observacoes de API.
 
-Hoje a ideia proposta eh algo como:
+Hoje a direcao consolidada eh algo como:
 
-- `Document(qualquer markdown aqui dentro...)`
+- `[Doc(markdown = """qualquer markdown aqui dentro...""")]`
 
 como anotacao consumida diretamente pelo hover.
 
@@ -49,19 +49,19 @@ O objetivo eh evitar que a primeira wave de assistencia editorial fique bloquead
 
 ## Open Questions
 
-- A autoria da documentacao deve acontecer por anotacao explicita como `Document(...)`, por comentario estruturado, ou por outro mecanismo?
+- A autoria da documentacao deve acontecer por anotacao explicita como `[Doc(...)]`, por comentario estruturado, ou por outro mecanismo?
-- O payload authored deve aceitar markdown arbitrario como fonte canonica, ou deve haver alguma normalizacao/restricao?
+- O payload authored deve aceitar um subset Markdown como fonte canonica, ou deve haver outra normalizacao/restricao?
-- Quais simbolos podem carregar documentacao na wave inicial:
+- Quais declaracoes nomeadas de API podem carregar documentacao na wave inicial:
-  funcoes, methods, services, hosts, builtin types, structs, enums, fields, constructors?
+  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 `Document(...)`?
+- 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 `Document(...)` com markdown como payload canonico
+### 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.
@@ -94,14 +94,25 @@ Se a equipe realmente quer markdown authored pronto para consumo no hover, Optio
 
 ## Recommendation
 
-Discutir esta agenda com viés inicial para **Option A**, mas sem fechar ainda a sintaxe final.
+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 `Document(...)` seja a direcao vencedora, a decisao deve deixar claro:
+Mesmo que `[Doc(...)]` seja a direcao vencedora, a decision deve deixar claro:
 
 - onde ela pode ser usada;
 - qual formato textual aceita;
@@ -109,6 +120,45 @@ Mesmo que `Document(...)` seja a direcao vencedora, a decisao deve deixar claro:
 - 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".
@@ -130,8 +180,8 @@ Por isso, mesmo sendo uma agenda separada, ela conversa diretamente com a futura
 
 ## Resolution
 
-Ainda em aberto.
+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
 
-Se o enquadramento fizer sentido, o proximo passo eh discutir as open questions e fechar uma `decision` propria para o modelo de documentacao de simbolos em PBS.
+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

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

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

@@ -0,0 +1,62 @@
+---
+id: PLN-0093
+ticket: pbs-symbol-documentation-and-hover-markdown
+title: Implement PBS lexer support for documentation text blocks
+status: open
+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

@@ -0,0 +1,59 @@
+---
+id: PLN-0094
+ticket: pbs-symbol-documentation-and-hover-markdown
+title: Extend PBS attribute parser and AST for Doc markdown payloads
+status: open
+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

@@ -0,0 +1,59 @@
+---
+id: PLN-0095
+ticket: pbs-symbol-documentation-and-hover-markdown
+title: Implement documentation text block normalization
+status: open
+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

@@ -0,0 +1,64 @@
+---
+id: PLN-0096
+ticket: pbs-symbol-documentation-and-hover-markdown
+title: Validate Doc attribute semantics and diagnostics
+status: open
+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

@@ -0,0 +1,60 @@
+---
+id: PLN-0097
+ticket: pbs-symbol-documentation-and-hover-markdown
+title: Attach Doc metadata to PBS semantic symbols
+status: open
+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

@@ -0,0 +1,60 @@
+---
+id: PLN-0098
+ticket: pbs-symbol-documentation-and-hover-markdown
+title: Expose Doc metadata through PBS editorial and LSP surfaces
+status: open
+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

@@ -0,0 +1,60 @@
+---
+id: PLN-0099
+ticket: pbs-symbol-documentation-and-hover-markdown
+title: Render Doc markdown in hover composition
+status: open
+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

@@ -0,0 +1,60 @@
+---
+id: PLN-0100
+ticket: pbs-symbol-documentation-and-hover-markdown
+title: Author Doc metadata for stdlib SDK and interface declarations
+status: open
+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

@@ -0,0 +1,58 @@
+---
+id: PLN-0101
+ticket: pbs-symbol-documentation-and-hover-markdown
+title: Protect runtime artifacts from Doc metadata lowering
+status: open
+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

@@ -0,0 +1,62 @@
+---
+id: PLN-0102
+ticket: pbs-symbol-documentation-and-hover-markdown
+title: Add end-to-end Doc documentation conformance coverage
+status: open
+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.
+
+## 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

docs/specs/compiler-languages/pbs/11. AST Specification.md

@@ -76,10 +76,18 @@ Mandatory declaration metadata on required declaration nodes includes:
 2. declared signature/surface when applicable (parameters/return),
 3. declaration-level syntactic flags/attributes required by later phases,
 4. stable `file/start/end` attribution,
-5. lifecycle-marker metadata when a declaration carries `[Init]` or `[Frame]`.
+5. lifecycle-marker metadata when a declaration carries `[Init]` or `[Frame]`,
+6. documentation attribute metadata when a declaration carries `[Doc(markdown = """...""")]`.
 
 Missing required attribution or metadata on mandatory nodes is non-conformant.
 
+Documentation metadata rules:
+
+- The AST MUST preserve the `Doc` attribute name, the `markdown` argument name, the raw documentation text block payload, and source attribution for the whole attribute and payload.
+- The AST MUST distinguish documentation text block payloads from ordinary string literals.
+- The AST MUST preserve enough attribution for later diagnostics to point at malformed or invalid `Doc` usage.
+- AST construction MUST NOT normalize documentation text block content in a way that loses source-observable parse meaning before the semantic normalization step.
+
 ## 8. Mandatory Declaration Families
 
 The v1 AST must represent, at minimum, declaration families for:
@@ -104,6 +112,8 @@ Lifecycle-observable declarations must preserve marker metadata explicitly:
 - top-level `fn` marked with `[Frame]`,
 - and host method signatures marked with `[InitAllowed]`.
 
+Documentation-observable declarations must preserve `Doc` metadata explicitly on every accepted named API declaration surface that carries `[Doc(markdown = """...""")]`.
+
 ## 9. Mandatory Statement and Expression Families
 
 The v1 AST must represent statement/expression families for the supported core syntax slice, including at minimum:

docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md

@@ -214,6 +214,19 @@ Reserved-attribute diagnostics for host-backed asset lowering must also cover:
 - out-of-range `AssetLowering.param` indexes,
 - and `AssetLowering` targets whose selected parameter is not statically typed as `Addressable`.
 
+Documentation attribute diagnostics must cover:
+
+- unterminated documentation text block syntax,
+- `Doc` used without the required `markdown` argument,
+- `Doc` with extra or unknown arguments,
+- `Doc` with a non-documentation-text-block payload,
+- duplicate `Doc` on the same declaration,
+- `Doc` applied to a parameter or other non-documentable surface,
+- normalized empty or whitespace-only documentation payload,
+- and rejected aliases or alternate forms such as `text`, positional arguments, `html`, `format`, `Document`, `Documentation`, or `md"""..."""`.
+
+Diagnostics for duplicate `Doc` attributes must be static semantic diagnostics and should include a related site for the conflicting declaration attribute when available.
+
 At minimum, host-admission diagnostics must cover missing or malformed host capability metadata and unknown or undeclared capability names.
 
 Only backend-originated failures that remain source-attributable and user-actionable belong to the PBS-facing diagnostics contract.

docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md

@@ -114,6 +114,13 @@ String literals:
 - delimited by `"`.
 - supported escapes: `\\`, `\"`, `\n`, `\r`, `\t`.
 
+Documentation text block literals:
+
+- delimited by `"""`.
+- valid only as the value of the `markdown` argument in the reserved `[Doc(markdown = """...""")]` attribute surface.
+- not part of the runtime expression literal surface in v1 core.
+- preserve authored text for later documentation normalization.
+
 Boolean literals:
 
 - `true`, `false`.
@@ -241,7 +248,8 @@ Attribute ::= '[' Identifier AttrArgs? ']'
 AttrArgs ::= '(' AttrArgList? ')'
 AttrArgList ::= AttrArg (',' AttrArg)*
 AttrArg ::= Identifier '=' AttrValue
-AttrValue ::= StringLit | IntLit | BoolLit
+AttrValue ::= StringLit | IntLit | BoolLit | DocTextBlock
+DocTextBlock ::= '"""' DocTextBlockChar* '"""'
 ```
 
 Rules:
@@ -250,11 +258,16 @@ Rules:
 - Attributes do not introduce values, types, callables, or modules by themselves.
 - In v1 core, ordinary user-authored modules MUST reject attributes unless another specification explicitly permits them.
 - Ordinary userland source MAY use `[Init]` and `[Frame]` only on top-level `fn` declarations.
+- Ordinary userland source MAY use `[Doc(markdown = """...""")]` on named API declarations where the static semantics specification permits documentation.
 - Reserved stdlib/toolchain interface modules MAY use attributes where explicitly allowed by syntax and semantics.
 - Reserved stdlib/toolchain interface modules MAY additionally use `[InitAllowed]` only on `declare host` method signatures where another specification explicitly permits it.
 - Attribute interpretation is compile-time only unless another specification explicitly lowers its effect into runtime-facing metadata.
 - Reserved attribute names used by builtin-type and intrinsic shells do not become ordinary value-level syntax.
 - `Slot(...)` is not part of the v1 attribute surface; source that uses `Slot` must be rejected in syntax phase.
+- `Doc` is a reserved documentation attribute name. Its only v1 syntactic shape is `[Doc(markdown = """...""")]`.
+- The `Doc` attribute MUST NOT accept positional arguments, `text`, `html`, `format`, `Document`, `Documentation`, or prefixed text block forms such as `md"""..."""`.
+- Documentation text blocks are not string literals and MUST NOT appear in ordinary expressions, parameter defaults, or non-`Doc` attribute arguments.
+- Attribute ordering is syntactically insignificant; semantic validation determines duplicate or invalid attribute combinations.
 
 ### 6.2 Top-level declarations
 

docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md

@@ -80,7 +80,7 @@ Rules:
 - Attributes are not first-class values and are not reflectable in v1 core.
 - Attributes do not automatically survive into runtime or bytecode artifacts.
 - An attribute affects runtime artifacts only when another specification defines an explicit lowering for its semantic effect.
-- In v1 core, the normative reserved attributes are `Host`, `Capability`, `AssetLowering`, `BuiltinType`, `BuiltinConst`, `IntrinsicCall`, `Init`, `Frame`, and `InitAllowed`.
+- In v1 core, the normative reserved attributes are `Host`, `Capability`, `AssetLowering`, `BuiltinType`, `BuiltinConst`, `IntrinsicCall`, `Init`, `Frame`, `InitAllowed`, and `Doc`.
 - `Host` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
 - `Capability` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
 - `AssetLowering` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
@@ -100,6 +100,42 @@ Rules:
 - Builtin metadata is consumed by the compiler during VM-owned builtin and intrinsic lowering rather than by host-binding lowering.
 - `Init` and `Frame` are consumed by lifecycle analysis and lowering rather than by ordinary runtime reflection.
 - `InitAllowed` is consumed by init-time host-admission analysis and does not become ordinary userland metadata.
+- `Doc` is compile/editor documentation metadata and is consumed by compiler-owned editorial surfaces.
+- `Doc` MUST NOT be lowered into bytecode, PBX, cartridge, or runtime-facing artifacts unless a future specification explicitly defines such lowering.
+
+### 2.3.1 `Doc` documentation metadata
+
+`Doc` attaches authored Markdown documentation to a named API declaration.
+
+Canonical v1 shape:
+
+```pbs
+[Doc(markdown = """
+Draws a sprite.
+
+- `x`: screen x
+- `y`: screen y
+""")]
+```
+
+Rules:
+
+- `Doc` MUST declare exactly one named argument, `markdown`.
+- `Doc.markdown` MUST be a documentation text block.
+- `Doc` MUST NOT accept aliases or alternate forms such as `text`, positional arguments, `html`, `format`, `Document`, `Documentation`, or `md"""..."""`.
+- A declaration MUST NOT carry more than one `Doc` attribute.
+- Duplicate `Doc` attributes are static semantic errors and must not be rejected only as parser errors.
+- Attribute order is semantically irrelevant; `Doc` colocated with other valid attributes has the same meaning regardless of ordering.
+- `Doc` is 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, services, hosts, builtin and stdlib declarations, and interface declarations.
+- Parameters MUST NOT receive `Doc` in v1. Parameter documentation, when present, 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 documentable named API declarations.
+- Documentation text block content MUST be normalized before semantic empty-payload validation and before exposure to editor consumers.
+- Normalization MUST remove an incidental leading empty line, remove an incidental trailing empty line, compute the common indentation of non-empty content lines, remove that common indentation, preserve internal line breaks, and preserve Markdown content after indentation normalization.
+- A normalized empty or whitespace-only `Doc.markdown` payload is invalid.
+- The authored format is a supported Markdown subset. Rendering, sanitization, and unsupported Markdown constructs are consumer responsibilities.
+- Compiler semantic metadata MUST preserve normalized Markdown documentation as metadata of the documented symbol.
+- LSP and editor consumers MUST consume compiler-resolved documentation metadata rather than reparsing source text.
 
 ### 2.4 Tuple shapes
 

docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md

@@ -354,6 +354,8 @@ Rules:
 - Renaming a public stdlib or host-backed parameter is API compatibility-sensitive and MUST be reviewed with the same discipline as other public callable-shape changes.
 - Interface-module loaders MUST NOT replace missing or unavailable public parameter names with generated ordinal placeholders such as `arg0` or `arg1`.
 - Missing canonical parameter identity MUST be represented as incomplete semantic metadata, not as a fabricated public name.
+- Stdlib, SDK, and interface-module API declarations SHOULD carry authored English documentation through `[Doc(markdown = """...""")]` once the documentation surface is implemented.
+- Stdlib and SDK parameter documentation MUST be authored inside the owning declaration's Markdown payload; parameters MUST NOT carry `[Doc]`.
 
 ### 9.3 Interface-module restrictions
 
@@ -441,6 +443,15 @@ Rules:
 - Attributes are not exported as ordinary values, types, or runtime-reflectable objects.
 - Attributes do not automatically survive into bytecode, PBX, or runtime metadata.
 
+`Doc` is a reserved documentation attribute for compiler/editor metadata.
+
+Rules:
+
+- Stdlib, SDK, and interface modules MUST use the same `[Doc(markdown = """...""")]` surface as ordinary PBS source for authored API documentation.
+- Authored source documentation takes precedence over imported or generated documentation for the same symbol.
+- Conflicts between authored and imported/generated documentation MUST be resolved deterministically or reported through explicit diagnostics.
+- `Doc` metadata enriches compiler/editor surfaces and MUST NOT change import resolution, host binding, ABI identity, executable lowering, or runtime behavior.
+
 ### 11.2 `Host` attribute
 
 The canonical reserved host-binding attribute is: