From 240525286b34348bf3b9b10d84b4d7900f0da892 Mon Sep 17 00:00:00 2001
From: bQUARKz <bquarkz@gmail.com>
Date: Fri, 8 May 2026 09:48:14 +0100
Subject: [PATCH] Wave 1 de assistencia editorial via LSP para PBS no VS Code

---
 discussion/index.ndjson                       |   4 +-
 ...D-0038-pbs-lsp-editor-assistance-wave-1.md | 207 ++++++++++++++++++
 ...symbol-documentation-and-hover-markdown.md | 137 ++++++++++++
 ...C-0035-pbs-lsp-editor-assistance-wave-1.md | 192 ++++++++++++++++
 ...face-for-symbols-members-and-signatures.md | 135 ++++++++++++
 ...ignature-help-over-editorial-resolution.md | 121 ++++++++++
 ...and-wave-1-editor-assistance-validation.md | 103 +++++++++
 7 files changed, 898 insertions(+), 1 deletion(-)
 create mode 100644 discussion/workflow/agendas/AGD-0038-pbs-lsp-editor-assistance-wave-1.md
 create mode 100644 discussion/workflow/agendas/AGD-0039-pbs-symbol-documentation-and-hover-markdown.md
 create mode 100644 discussion/workflow/decisions/DEC-0035-pbs-lsp-editor-assistance-wave-1.md
 create mode 100644 discussion/workflow/plans/PLN-0075-pbs-editorial-resolution-surface-for-symbols-members-and-signatures.md
 create mode 100644 discussion/workflow/plans/PLN-0076-lsp-completion-hover-and-signature-help-over-editorial-resolution.md
 create mode 100644 discussion/workflow/plans/PLN-0077-vscode-consumption-and-wave-1-editor-assistance-validation.md

diff --git a/discussion/index.ndjson b/discussion/index.ndjson
index 67ad4756..f52fcf37 100644
--- a/discussion/index.ndjson
+++ b/discussion/index.ndjson
@@ -1,4 +1,6 @@
-{"type":"meta","next_id":{"DSC":35,"AGD":38,"DEC":35,"PLN":75,"LSN":51,"CLSN":1}}
+{"type":"meta","next_id":{"DSC":37,"AGD":40,"DEC":36,"PLN":78,"LSN":51,"CLSN":1}}
+{"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-0035","status":"in_progress","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":[{"id":"AGD-0038","file":"AGD-0038-pbs-lsp-editor-assistance-wave-1.md","status":"accepted","created_at":"2026-05-08","updated_at":"2026-05-08"}],"decisions":[{"id":"DEC-0035","file":"DEC-0035-pbs-lsp-editor-assistance-wave-1.md","status":"accepted","created_at":"2026-05-08","updated_at":"2026-05-08","ref_agenda":"AGD-0038"}],"plans":[{"id":"PLN-0075","file":"PLN-0075-pbs-editorial-resolution-surface-for-symbols-members-and-signatures.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08","ref_decisions":["DEC-0035"]},{"id":"PLN-0076","file":"PLN-0076-lsp-completion-hover-and-signature-help-over-editorial-resolution.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08","ref_decisions":["DEC-0035"]},{"id":"PLN-0077","file":"PLN-0077-vscode-consumption-and-wave-1-editor-assistance-validation.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08","ref_decisions":["DEC-0035"]}],"lessons":[]}
 {"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"}]}
 {"type":"discussion","id":"DSC-0032","status":"done","ticket":"studio-new-lsp-api-and-v1-boundary","title":"Novo boundary entre lsp-api, lsp-v1 e a extensao VS Code","created_at":"2026-05-05","updated_at":"2026-05-07","tags":["studio","lsp","vscode","protocol","api","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0047","file":"discussion/lessons/DSC-0032-studio-new-lsp-api-and-v1-boundary/LSN-0047-project-scoped-lsp-boundary-and-protocol-containment.md","status":"done","created_at":"2026-05-07","updated_at":"2026-05-07"}]}
diff --git a/discussion/workflow/agendas/AGD-0038-pbs-lsp-editor-assistance-wave-1.md b/discussion/workflow/agendas/AGD-0038-pbs-lsp-editor-assistance-wave-1.md
new file mode 100644
index 00000000..f31beaf2
--- /dev/null
+++ b/discussion/workflow/agendas/AGD-0038-pbs-lsp-editor-assistance-wave-1.md
@@ -0,0 +1,207 @@
+---
+id: AGD-0038
+ticket: pbs-lsp-editor-assistance-wave-1
+title: Wave 1 de assistencia editorial via LSP para PBS no VS Code
+status: accepted
+created: 2026-05-08
+resolved: 2026-05-08
+decision: DEC-0035
+tags: [studio, lsp, vscode, compiler, compiler-pbs, editor, completion, hover, signature-help]
+---
+
+## Pain
+
+O stack atual de PBS no VS Code ja entrega duas capacidades relevantes:
+
+- diagnostics basicos;
+- semantic highlighting com tema frontend-owned.
+
+Mas ele ainda nao entrega o minimo de assistencia editorial para um fluxo real de escrita de codigo:
+
+- nao existe `completion`;
+- `hover` ainda eh placeholder;
+- nao existe `signature help`.
+
+Sem isso, o editor continua servindo mais como viewer colorido com erros do que como ambiente minimamente utilizavel para escrever PBS com conforto.
+
+## Context
+
+Domain owner: `studio`
+
+Subdomains touched:
+
+- `studio/lsp`
+- `compiler/pbs`
+- `compiler/general`
+
+Estado atual observado no codigo:
+
+- o servidor anuncia `hover` e `semanticTokens`, mas nao anuncia `completionProvider`, `signatureHelpProvider` ou `documentFormattingProvider`;
+- o bridge interno do LSP so expõe `describeServer`, `analyzeDocument`, `hover`, `semanticTokens` e `onSave`;
+- `hover` hoje retorna texto fixo, sem usar simbolo, assinatura, tipo ou docs;
+- o pipeline do compiler ja consegue analisar overlay do documento e possui superficies semanticas e de linking relevantes no PBS;
+- o highlighting recente ja resolve bastante informacao lexical e parte da superficie stdlib/imports.
+
+Esta agenda trata apenas da wave 1 de assistencia editorial.
+Ela nao tenta fechar todo o problema de IDE features.
+
+## Open Questions
+
+- Qual deve ser o escopo minimo de `completion` para chamarmos essa wave de utilizavel?
+- [x] Qual deve ser o escopo minimo de `completion` para chamarmos essa wave de utilizavel?
+  R: keywords, nomes locais em escopo, simbolos importados/publicos, e members apos `.` para superfícies reconhecidas (`service`, `host`, `builtin type`, `struct` e constructors/funcoes relacionados). Sem isso, a feature ainda nao ajuda na descoberta real da API.
+- `completion` deve nascer apenas com heuristicas lexicais/sintaticas, ou ja deve usar semantica e linking do compiler onde isso for viavel?
+- [x] `completion` deve nascer apenas com heuristicas lexicais/sintaticas, ou ja deve usar semantica e linking do compiler onde isso for viavel?
+  R: deve nascer compiler-backed sempre que a informacao ja existir de forma confiavel no pipeline semantico/linking. Heuristica local pode existir apenas como complemento estritamente limitado para casos ainda nao resolvidos, nunca como segunda semantica canônica.
+- Em `hover`, quais informacoes sao obrigatorias na primeira entrega:
+  assinatura, kind, modulo de origem, tipo inferido, documentacao?
+- [x] Em `hover`, quais informacoes sao obrigatorias na primeira entrega:
+  assinatura, kind, modulo de origem, tipo inferido, documentacao?
+  R: obrigatorios: `kind`, assinatura quando aplicavel, modulo/origem quando relevante, e tipo/shape basico quando houver. Documentacao textual eh desejavel para stdlib e builtins, mas nao deve bloquear a wave 1 se a infraestrutura de docstring ainda nao existir. Se a linguagem vier a adotar algo como `Document(...)` com markdown pronto para hover, isso deve nascer em discussao propria; nesta wave atual, basta preparar o local de consumo para documentacao opcional quando ela existir.
+- `signature help` deve usar a mesma fonte semantica de `hover/completion`, ou pode nascer numa implementacao mais local para chamadas conhecidas?
+- [x] `signature help` deve usar a mesma fonte semantica de `hover/completion`, ou pode nascer numa implementacao mais local para chamadas conhecidas?
+  R: deve usar a mesma base semantica. O objetivo da wave eh justamente evitar tres caminhos tecnicos diferentes para responder "qual assinatura esta sendo chamada?".
+- Como tratar membros de stdlib, aliases importados, services, hosts, builtin types e metodos de struct sem criar uma segunda semantica paralela no LSP?
+- [x] Como tratar membros de stdlib, aliases importados, services, hosts, builtin types e metodos de struct sem criar uma segunda semantica paralela no LSP?
+  R: o LSP deve perguntar ao compiler por uma superficie editorial/resolutiva unica, derivada das mesmas fontes usadas para analise, linking, stdlib e metadata do frontend. O LSP nao deve reconstruir manualmente tabelas paralelas de membros.
+- Esta wave deve incluir `go to definition`, ou isso deve ficar explicitamente fora do escopo para nao diluir a entrega?
+- [x] Esta wave deve incluir `go to definition`, ou isso deve ficar explicitamente fora do escopo para nao diluir a entrega?
+  R: deve ficar fora do escopo desta wave. Ele eh um proximo passo natural, mas nao eh requisito para chamar `completion + hover + signature help` de minimamente utilizaveis.
+- Formatacao e identacao automatica devem ficar fora desta agenda como non-goal explicito?
+- [x] Formatacao e identacao automatica devem ficar fora desta agenda como non-goal explicito?
+  R: sim. Podem virar discussao/plan posterior. Nesta wave, elas seriam custo adicional sem impacto proporcional comparado a completion/hover/signature help.
+
+## Options
+
+### Option A - Completion e hover por heuristica leve, com signature help posterior
+
+- **Approach:** implementar `completion` usando contexto local, imports, keywords e alguns casos de member access, implementar `hover` com informacao minima, e deixar `signature help` para uma wave seguinte.
+- **Pro:** menor custo inicial e menor risco de travar na arquitetura semantica.
+- **Con:** pode criar uma primeira entrega inconsistente, especialmente em chamadas de stdlib e tipos importados, e pode forcar refactor cedo demais depois.
+- **Maintainability:** media.
+
+### Option B - Wave 1 coerente com completion, hover e signature help sobre uma mesma base semantica
+
+- **Approach:** desenhar uma pequena superficie de assistencia editorial no LSP que use uma base comum para resolver simbolos, membros e assinaturas. Entregar juntos:
+  - completion minimo utilizavel;
+  - hover real;
+  - signature help em chamadas.
+- **Pro:** evita duplicacao conceitual e produz uma experiencia de editor mais consistente desde a primeira wave.
+- **Con:** custo maior de desenho e implementacao agora.
+- **Maintainability:** forte.
+
+### Option C - Adiar assistencia semantica e depender do VS Code + snippets
+
+- **Approach:** manter diagnostics e colors como estao, adicionar no maximo snippets ou pequenas ajudas na extensao.
+- **Pro:** quase nenhum custo de backend.
+- **Con:** nao resolve o problema real; o editor continua insuficiente para escrita cotidiana de PBS.
+- **Maintainability:** fraca.
+
+## Tradeoffs
+
+Option C nao fecha a dor real e deve ser descartada.
+
+Option A parece atraente para ganhar velocidade, mas carrega um risco ruim:
+
+- introduzir `completion`, `hover` e depois `signature help` por caminhos tecnicos diferentes;
+- duplicar logica entre parser local, heuristicas e linking;
+- e transformar a wave 2 num retrabalho de consolidacao.
+
+Option B custa mais, mas o custo eh justificavel porque estas tres features se apoiam nas mesmas perguntas:
+
+- o que este simbolo representa?
+- quais membros ele expõe?
+- qual eh a assinatura desta chamada?
+- qual o modulo/origem deste item?
+
+Se essas perguntas forem respondidas por uma base comum, a wave 1 fica mais coerente e abre caminho natural para futuras features como `definition`, `references` e `inlay hints` via LSP.
+
+## Recommendation
+
+Seguir com **Option B**.
+
+A recomendacao eh abrir uma wave 1 coerente de assistencia editorial com:
+
+- `completion` minimo utilizavel;
+- `hover` funcional;
+- `signature help` funcional.
+
+Escopo minimo recomendado para `completion`:
+
+- keywords;
+- simbolos locais em escopo;
+- nomes importados/publicos relevantes;
+- members apos `.` para stdlib, builtin types, structs e services/hosts reconhecidos.
+
+Escopo minimo recomendado para `hover`:
+
+- kind do simbolo;
+- assinatura quando aplicavel;
+- modulo/origem quando relevante;
+- tipo ou shape basico quando isso existir de forma confiavel.
+
+Escopo minimo recomendado para `signature help`:
+
+- chamadas de funcao/metodo/construtor;
+- parametro ativo;
+- labels consistentes com a mesma representacao de assinatura usada no hover.
+
+## Discussion
+
+O ponto principal desta agenda nao eh “adicionar IDE features” genericamente.
+
+O ponto principal eh definir a primeira wave de superfícies de assistencia que tiram o PBS no VS Code do estado de:
+
+- diagnostics + coloracao
+
+para um estado de:
+
+- escrita assistida minima, com descoberta de API e leitura de assinatura.
+
+Isso exige disciplina de boundary.
+
+O VS Code extension nao deve inventar semantica local.
+O servidor LSP deve continuar sendo o owner da assistencia editorial.
+
+Da mesma forma, o LSP nao deve criar uma semantica paralela desconectada do compiler se ja existe informacao aproveitavel em parser, linking, stdlib e superficies semanticas do PBS.
+
+Tambem vale explicitar o que fica fora desta agenda:
+
+- formatter completo;
+- identacao automatica robusta de documento;
+- quick fixes;
+- definition/references;
+- rename;
+- code actions mais amplas.
+
+Esses itens podem virar agenda posterior.
+
+Tambem fica registrado um criterio importante de arquitetura:
+
+- o primeiro passo nao eh encher o protocolo de features;
+- o primeiro passo eh criar uma base editorial coerente no lado `compiler/pbs` + `studio/lsp` que consiga responder simbolo, members e assinatura;
+- `completion`, `hover` e `signature help` sao projeções diferentes sobre a mesma base.
+
+E um criterio adicional de preparacao editorial:
+
+- a wave 1 deve prever um campo/superficie opcional de documentacao no modelo editorial resolvido por simbolo;
+- mas a autoria dessa documentacao na linguagem PBS, inclusive eventual anotacao `Document(...)` com markdown, fica fora desta agenda e pode seguir para discussao separada.
+
+## Resolution
+
+Resolucao preliminar:
+
+- a wave 1 deve ser considerada valida quando o VS Code conseguir oferecer descoberta minima de API, leitura de assinatura e ajuda em chamadas sem depender de conhecimento local na extensao;
+- `completion`, `hover` e `signature help` devem nascer sobre uma mesma base compiler-backed;
+- `go to definition`, formatter e outras features de IDE ficam explicitamente fora do escopo.
+
+Se esta leitura fizer sentido, o proximo passo eh aceitar a agenda e fechar uma `decision` que:
+
+1. defina o escopo normativo exato de `completion`, `hover` e `signature help`;
+2. fixe o boundary entre `compiler/pbs`, `studio/lsp` e `tools/vscode-extension`;
+3. declare explicitamente os non-goals desta wave;
+4. determine se a base deve nascer compiler-backed desde o inicio ou com alguma heuristica local estritamente limitada.
+
+## Next Step
+
+Se voce concordar com o enquadramento, eu converto esta agenda em `accepted` e escrevo a `decision` normativa da wave 1 de assistencia editorial para PBS no VS Code.
diff --git a/discussion/workflow/agendas/AGD-0039-pbs-symbol-documentation-and-hover-markdown.md b/discussion/workflow/agendas/AGD-0039-pbs-symbol-documentation-and-hover-markdown.md
new file mode 100644
index 00000000..c3c0504b
--- /dev/null
+++ b/discussion/workflow/agendas/AGD-0039-pbs-symbol-documentation-and-hover-markdown.md
@@ -0,0 +1,137 @@
+---
+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
+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 ideia proposta eh algo como:
+
+- `Document(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 `Document(...)`, por comentario estruturado, ou por outro mecanismo?
+- O payload authored deve aceitar markdown arbitrario como fonte canonica, ou deve haver alguma normalizacao/restricao?
+- Quais simbolos podem carregar documentacao na wave inicial:
+  funcoes, methods, services, hosts, builtin types, structs, enums, fields, constructors?
+- 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(...)`?
+- 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
+
+- **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**, mas sem fechar ainda a sintaxe final.
+
+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:
+
+- 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.
+
+## 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
+
+Ainda em aberto.
+
+## 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.
diff --git a/discussion/workflow/decisions/DEC-0035-pbs-lsp-editor-assistance-wave-1.md b/discussion/workflow/decisions/DEC-0035-pbs-lsp-editor-assistance-wave-1.md
new file mode 100644
index 00000000..9991f391
--- /dev/null
+++ b/discussion/workflow/decisions/DEC-0035-pbs-lsp-editor-assistance-wave-1.md
@@ -0,0 +1,192 @@
+---
+id: DEC-0035
+ticket: pbs-lsp-editor-assistance-wave-1
+title: Wave 1 de assistencia editorial via LSP para PBS no VS Code
+status: accepted
+created: 2026-05-08
+accepted: 2026-05-08
+agenda: AGD-0038
+plans: [PLN-0075, PLN-0076, PLN-0077]
+tags: [studio, lsp, vscode, compiler, compiler-pbs, editor, completion, hover, signature-help]
+---
+
+## Context
+
+O stack atual de PBS no VS Code ja entrega diagnostics basicos e semantic highlighting frontend-owned, mas ainda nao oferece assistencia editorial minima para escrita cotidiana de codigo.
+
+Hoje:
+
+1. nao existe `completion`;
+2. `hover` existe apenas como placeholder;
+3. nao existe `signature help`;
+4. o servidor ainda nao anuncia capabilities correspondentes para essas superficies;
+5. o compiler e o frontend PBS ja possuem informacao semantica, de linking, stdlib e metadata suficiente para nao precisarmos inventar uma segunda semantica local na extensao.
+
+Esta decisao trata apenas da primeira wave de assistencia editorial para PBS no VS Code.
+Ela nao cobre formatter, identacao automatica robusta, quick fixes, `go to definition`, `references`, `rename` nem code actions gerais.
+
+## Decision
+
+O repositório SHALL entregar uma wave 1 de assistencia editorial via LSP para PBS no VS Code com tres superfícies funcionais:
+
+1. `completion`;
+2. `hover`;
+3. `signature help`.
+
+Esta wave SHALL ser considerada valida quando essas tres superfícies permitirem:
+
+1. descoberta minima de API;
+2. leitura de assinatura em simbolos e chamadas;
+3. ajuda de chamada sem dependencia de conhecimento semantico local na extensao VS Code.
+
+Esta decisao ALSO locks que:
+
+1. `completion`, `hover` e `signature help` MUST nascer sobre uma mesma base editorial compiler-backed;
+2. o LSP MUST ser o owner operacional da assistencia editorial;
+3. a extensao VS Code MUST atuar apenas como cliente/adaptador do protocolo, e MUST NOT reconstruir semantica propria para simbolos, members ou assinaturas;
+4. heuristicas locais no LSP MAY existir apenas como complemento temporario e estritamente limitado para lacunas nao resolvidas, mas MUST NOT virar uma segunda semantica canônica;
+5. `go to definition`, formatter, identacao automatica robusta, quick fixes, `references`, `rename` e code actions amplas MUST ficar fora desta wave.
+
+## Rationale
+
+As tres features desta wave respondem essencialmente ao mesmo conjunto de perguntas:
+
+1. que simbolo eh este?
+2. quais members ele expõe?
+3. qual assinatura ele tem?
+4. de onde ele vem?
+
+Implementa-las por caminhos tecnicos diferentes introduziria:
+
+1. duplicacao entre parser local, heuristicas e linking;
+2. incoerencia entre o que aparece em `completion`, `hover` e `signature help`;
+3. retrabalho na wave seguinte.
+
+Portanto, a primeira entrega precisa nascer sobre uma base editorial unificada, reaproveitando o que o compiler e o frontend PBS ja sabem sobre:
+
+1. escopo local;
+2. imports e aliases;
+3. stdlib;
+4. builtin types;
+5. services, hosts, structs, enums, constructors, functions e methods.
+
+## Technical Specification
+
+### 1. Shared Editorial Resolution Surface
+
+`compiler/pbs` e `studio/lsp` MUST introduzir uma superficie editorial resolvida comum para uso de `completion`, `hover` e `signature help`.
+
+Essa superficie MUST ser capaz de responder, de forma compiler-backed:
+
+1. identidade do simbolo;
+2. `kind` do simbolo;
+3. modulo/origem quando relevante;
+4. assinatura ou shape quando aplicavel;
+5. members disponíveis para receivers reconhecidos;
+6. documentacao opcional quando existir, sem bloquear esta wave.
+
+Essa superficie MAY ser exposta por novos modelos internos do compiler, novos adapters no bridge do LSP, ou ambos.
+Mas ela MUST permanecer derivada do compiler e MUST NOT ser reautoriada na extensao.
+
+### 2. Completion Scope
+
+`completion` MUST ser entregue como superfície minima utilizavel.
+
+Na wave 1, isso MUST cobrir pelo menos:
+
+1. keywords da linguagem;
+2. nomes locais em escopo;
+3. simbolos importados/publicos relevantes;
+4. members apos `.` para superfícies reconhecidas, incluindo `service`, `host`, `builtin type`, `struct`, e call surfaces relacionadas.
+
+`completion` SHOULD expor labels, kinds e detalhes coerentes com a mesma base usada por `hover`.
+
+`completion` MUST NOT depender de tabela hardcoded na extensao para stdlib ou members de PBS.
+
+### 3. Hover Scope
+
+`hover` MUST deixar de ser placeholder e passar a ser simbolo-resolved.
+
+Na wave 1, o hover MUST incluir quando disponivel:
+
+1. `kind` do simbolo;
+2. assinatura quando aplicavel;
+3. modulo/origem quando relevante;
+4. tipo ou shape basico quando isso existir de forma confiavel.
+
+`hover` MAY incluir documentacao textual opcional.
+Mas a autoria de documentacao em PBS, incluindo eventual anotacao como `Document(...)`, MUST seguir discussao separada e MUST NOT bloquear esta wave.
+
+### 4. Signature Help Scope
+
+`signature help` MUST ser implementado para chamadas de:
+
+1. funcao;
+2. metodo;
+3. construtor.
+
+Na wave 1, ele MUST informar:
+
+1. a assinatura ativa;
+2. o parametro ativo;
+3. labels coerentes com a mesma representacao de assinatura usada no hover.
+
+`signature help` MUST usar a mesma base editorial de resolucao usada por `completion` e `hover`.
+
+### 5. Boundary Responsibilities
+
+`compiler/pbs`:
+
+1. MUST continuar sendo a fonte de verdade de semantica, linking e metadata relevante para simbolos e call surfaces;
+2. MUST fornecer a base necessaria para resolucao editorial de simbolos, members e assinaturas.
+
+`studio/lsp`:
+
+1. MUST projetar essa base editorial em endpoints/protocol features adequados;
+2. MUST anunciar as capabilities LSP necessarias para `completion`, `hover` e `signature help`;
+3. MUST manter o transporte fiel ao modelo compiler-backed.
+
+`tools/vscode-extension`:
+
+1. MUST consumir o protocolo como cliente;
+2. MUST NOT carregar tabelas paralelas de membros, stdlib ou assinaturas como fonte principal;
+3. MAY conter apenas a logica estrutural normal de integração exigida pelo VS Code.
+
+### 6. Documentation Preparation Rule
+
+Esta wave MUST preparar um campo ou superfície opcional para documentacao editorial resolvida por simbolo.
+
+Mas esta decisao ALSO locks que:
+
+1. a surface de autoria dessa documentacao em PBS nao faz parte desta wave;
+2. a sintaxe ou contrato de linguagem para documentacao authored deve ser discutido separadamente;
+3. a ausencia dessa autoria nao bloqueia `completion`, `hover` nem `signature help` da wave 1.
+
+### 7. Explicit Non-Goals
+
+Esta decisao MUST NOT:
+
+1. incluir formatter completo;
+2. incluir identacao automatica robusta de documento;
+3. incluir `go to definition`;
+4. incluir `references`;
+5. incluir `rename`;
+6. incluir quick fixes;
+7. incluir code actions mais amplas;
+8. definir o modelo de autoria de documentacao em PBS.
+
+## Constraints
+
+1. A wave 1 MUST priorizar coerencia entre `completion`, `hover` e `signature help` sobre cobertura enciclopedica de todos os casos.
+2. A extensao VS Code MUST permanecer thin; a inteligencia editorial MUST ficar no compiler/LSP.
+3. A implementacao MUST favorecer evolucao futura para `definition`, `references`, `documentation`, e outras editor features sem exigir reescrita conceitual da base editorial.
+4. A implementacao MUST evitar surfaces duplicadas para stdlib, aliases, members e signatures.
+5. Qualquer plan derivado desta decisao MUST separar claramente:
+   - base editorial compiler-backed;
+   - projeção LSP/protocolo;
+   - integração VS Code.
+
+## Revision Log
+
+- 2026-05-08: Initial draft from AGD-0038.
+- 2026-05-08: Accepted and decomposed into PLN-0075, PLN-0076, and PLN-0077.
diff --git a/discussion/workflow/plans/PLN-0075-pbs-editorial-resolution-surface-for-symbols-members-and-signatures.md b/discussion/workflow/plans/PLN-0075-pbs-editorial-resolution-surface-for-symbols-members-and-signatures.md
new file mode 100644
index 00000000..de592972
--- /dev/null
+++ b/discussion/workflow/plans/PLN-0075-pbs-editorial-resolution-surface-for-symbols-members-and-signatures.md
@@ -0,0 +1,135 @@
+---
+id: PLN-0075
+ticket: pbs-lsp-editor-assistance-wave-1
+title: PBS Editorial Resolution Surface for Symbols, Members, and Signatures
+status: open
+created: 2026-05-08
+completed:
+tags: [compiler, compiler-pbs, editor, completion, hover, signature-help, semantics]
+---
+
+## Objective
+
+Introduce a compiler-backed editorial resolution surface in `compiler/pbs` that can answer symbol identity, kind, origin, signature/shape, callable details, and receiver members for use by LSP `completion`, `hover`, and `signature help`.
+
+## Background
+
+`DEC-0035` requires all three editor-assistance features to be built over one shared compiler-backed base. The current repository already has useful pieces:
+
+- parser and AST for PBS;
+- semantic validation and flow analysis;
+- stdlib and import visibility rules;
+- semantic token classification;
+- builder-pipeline overlay analysis.
+
+What is still missing is an explicit editorial surface designed for interactive symbol resolution instead of only diagnostics or coloring.
+
+## Scope
+
+### Included
+
+- Define internal compiler-side models for editorial symbol resolution.
+- Resolve local names, imported/public symbols, and recognized member surfaces.
+- Resolve callable signatures for functions, methods, and constructors.
+- Provide optional documentation slot(s) in the model without defining authored PBS documentation syntax.
+- Add PBS-focused tests for symbol/member/signature resolution.
+
+### Excluded
+
+- LSP protocol capability changes.
+- VS Code client behavior.
+- Authored documentation syntax such as `Document(...)`.
+- `go to definition`, `references`, `rename`, formatter, or code actions.
+
+## Non-Goals
+
+- Rebuilding the full compiler around IDE concerns.
+- Solving every ambiguous or partial parse state in wave 1.
+- Designing a generic multi-language IDE framework before PBS proves the model.
+
+## Execution Steps
+
+### Step 1 - Define editorial resolution models in compiler-owned surfaces
+
+**What:** Introduce explicit models for resolved symbols, member candidates, callable signatures, and optional documentation payload.
+**How:** Add compiler-owned DTO/model types that can express:
+
+1. symbol identity and kind;
+2. declared/imported origin;
+3. callable label/signature shape;
+4. receiver member entries;
+5. optional documentation text field.
+
+The model must be expressive enough for `completion`, `hover`, and `signature help` without forcing each consumer to reinterpret raw AST nodes.
+**File(s):** `prometeu-compiler/prometeu-compiler-core/src/main/java/**` and/or `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/**` depending on final ownership split.
+
+### Step 2 - Build PBS symbol resolution for local and imported surfaces
+
+**What:** Resolve names in editorial contexts.
+**How:** Reuse parser, name/linking, stdlib import knowledge, and any existing semantic tables to resolve:
+
+1. local bindings in scope;
+2. declared top-level PBS symbols;
+3. imported/public symbols and aliases;
+4. stdlib-owned surfaces currently recognized by the frontend.
+
+The implementation must avoid duplicating semantic truth already present in compiler/linking logic.
+**File(s):** `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/**`.
+
+### Step 3 - Build member and callable resolution
+
+**What:** Resolve members and callable signatures for recognized receiver and call surfaces.
+**How:** Support at minimum:
+
+1. member lookup after `.` for services, hosts, builtin types, and structs;
+2. direct callable lookup for functions and constructors;
+3. active-call signature resolution for later `signature help` use.
+
+This step must produce stable labels/details that can be reused unchanged by LSP features.
+**File(s):** `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/**`.
+
+### Step 4 - Add editorial conformance tests
+
+**What:** Lock the compiler-backed editorial contract before LSP integration.
+**How:** Add tests for:
+
+1. local variable and parameter resolution;
+2. imported service/host/builtin-type resolution;
+3. member lookup after `.` on recognized surfaces;
+4. callable signature extraction for function/method/constructor cases;
+5. optional documentation field stability when absent.
+
+**File(s):** PBS/compiler test suites under `prometeu-compiler/**/src/test/java/**`.
+
+## Test Requirements
+
+### Unit Tests
+
+- Model invariants for symbol/member/signature payloads.
+- Resolver tests covering locals, imports, aliases, members, and constructors.
+
+### Integration Tests
+
+- Compiler-backed overlay/editorial tests using representative PBS snippets and stdlib imports.
+
+### Manual Verification
+
+- Inspect resolved payloads in tests or debug output and confirm they are sufficient to drive all three editor features without ad hoc reinterpretation.
+
+## Acceptance Criteria
+
+- [ ] Compiler-side editorial models exist for symbols, members, signatures, and optional documentation.
+- [ ] PBS can resolve local names, imported/public symbols, and recognized member surfaces.
+- [ ] Function, method, and constructor signatures are available through the shared editorial surface.
+- [ ] No consumer is required to reconstruct signature/member meaning from raw AST-only data.
+
+## Dependencies
+
+- `DEC-0035` accepted and normatively locked.
+- Existing PBS semantic and import/linking infrastructure remains the truth source.
+
+## Risks
+
+- Overfitting the first resolver to the current stdlib shape may hurt future fronts or future PBS growth.
+- Mixing diagnostics-only semantics with editorial semantics carelessly may produce partial or contradictory answers.
+- Incomplete member resolution can make `completion` appear flaky even if `hover` works.
diff --git a/discussion/workflow/plans/PLN-0076-lsp-completion-hover-and-signature-help-over-editorial-resolution.md b/discussion/workflow/plans/PLN-0076-lsp-completion-hover-and-signature-help-over-editorial-resolution.md
new file mode 100644
index 00000000..064f7d7d
--- /dev/null
+++ b/discussion/workflow/plans/PLN-0076-lsp-completion-hover-and-signature-help-over-editorial-resolution.md
@@ -0,0 +1,121 @@
+---
+id: PLN-0076
+ticket: pbs-lsp-editor-assistance-wave-1
+title: LSP Completion, Hover, and Signature Help over Editorial Resolution
+status: open
+created: 2026-05-08
+completed:
+tags: [studio, lsp, protocol, completion, hover, signature-help, editor]
+---
+
+## Objective
+
+Expose `completion`, real `hover`, and `signature help` through the project-scoped LSP stack by projecting the compiler-backed editorial resolution surface into explicit protocol capabilities and request handlers.
+
+## Background
+
+`DEC-0035` requires `studio/lsp` to be the operational owner of these editor features while remaining faithful to compiler-backed symbol, member, and signature resolution. The current LSP path only handles diagnostics, semantic tokens, and a placeholder hover.
+
+## Scope
+
+### Included
+
+- Extend the internal bridge/API with completion and signature-help operations.
+- Replace placeholder hover with symbol-resolved hover.
+- Announce LSP capabilities for completion and signature help.
+- Add message models/mappers/tests for the new request/response paths.
+
+### Excluded
+
+- Creation of the underlying compiler editorial model itself.
+- Authored documentation syntax.
+- VS Code-specific UI behavior beyond normal LSP consumption.
+
+## Non-Goals
+
+- `go to definition`, `references`, `rename`, formatter, code actions, or quick fixes.
+- Rich workspace-wide indexing beyond what the shared editorial surface already provides.
+
+## Execution Steps
+
+### Step 1 - Extend the LSP bridge contract
+
+**What:** Add compiler-backed editor-assistance operations to the bridge.
+**How:** Evolve `LanguageServiceBridge` and related internal messages to support at minimum:
+
+1. completion requests;
+2. symbol-resolved hover payloads;
+3. signature-help requests.
+
+The bridge contract must align structurally with the shared editorial resolution surface rather than inventing a second feature-specific abstraction.
+**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/**`, `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/**`.
+
+### Step 2 - Implement compiler-backed request handling
+
+**What:** Wire LSP requests to compiler-backed editorial resolution.
+**How:** Update `CompilerLanguageServiceBridge` so it:
+
+1. resolves completion candidates from local/import/member contexts;
+2. resolves hover payloads from symbol identity, origin, and signatures;
+3. resolves active call signatures for `signature help`.
+
+This step must remove the current fixed hover placeholder.
+**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/**`.
+
+### Step 3 - Announce and map protocol capabilities
+
+**What:** Make the server advertise the new feature set and map payloads into lsp4j types.
+**How:** Update protocol mappers and text-document service so the server announces:
+
+1. `completionProvider`;
+2. `signatureHelpProvider`;
+3. improved `hoverProvider` backed by real payloads.
+
+Map completion items, hover markdown, and signature-help structures into concrete LSP responses.
+**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/**`, `.../mapping/**`.
+
+### Step 4 - Add transport and conformance tests
+
+**What:** Prevent regression to placeholder/editor-local behavior.
+**How:** Add tests that verify:
+
+1. capabilities are announced correctly;
+2. completion returns compiler-backed candidates;
+3. hover no longer returns the baseline placeholder;
+4. signature-help returns deterministic active-signature information.
+
+**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/test/java/**`.
+
+## Test Requirements
+
+### Unit Tests
+
+- DTO/model invariants for completion, hover, and signature-help payloads.
+- Mapper tests for lsp4j conversion.
+
+### Integration Tests
+
+- LSP request/response tests using realistic PBS snippets with locals, imports, and member access.
+
+### Manual Verification
+
+- Connect the VS Code extension and confirm server capabilities include completion and signature help.
+- Confirm hover content changes with the hovered symbol rather than returning static baseline text.
+
+## Acceptance Criteria
+
+- [ ] The LSP bridge exposes completion and signature-help operations in addition to diagnostics, hover, and semantic tokens.
+- [ ] Hover is symbol-resolved and no longer hardcoded placeholder text.
+- [ ] The server advertises completion and signature-help capabilities.
+- [ ] Completion, hover, and signature help all derive from the same compiler-backed editorial surface.
+
+## Dependencies
+
+- `DEC-0035` accepted and normatively locked.
+- `PLN-0075` for the shared compiler-backed editorial resolution surface.
+
+## Risks
+
+- Protocol mapping can drift from compiler payload shape if feature-specific shortcuts are added.
+- Active parameter/signature calculation may be brittle around incomplete syntax unless request handling is conservative.
+- Completion can feel noisy if candidate ranking or filtering is too weak in wave 1.
diff --git a/discussion/workflow/plans/PLN-0077-vscode-consumption-and-wave-1-editor-assistance-validation.md b/discussion/workflow/plans/PLN-0077-vscode-consumption-and-wave-1-editor-assistance-validation.md
new file mode 100644
index 00000000..5dfd483c
--- /dev/null
+++ b/discussion/workflow/plans/PLN-0077-vscode-consumption-and-wave-1-editor-assistance-validation.md
@@ -0,0 +1,103 @@
+---
+id: PLN-0077
+ticket: pbs-lsp-editor-assistance-wave-1
+title: VS Code Consumption and Wave 1 Editor Assistance Validation
+status: open
+created: 2026-05-08
+completed:
+tags: [vscode, extension, editor, completion, hover, signature-help, validation]
+---
+
+## Objective
+
+Keep the VS Code extension thin while validating that the new LSP-delivered `completion`, `hover`, and `signature help` features actually produce a minimally usable PBS editing experience end to end.
+
+## Background
+
+`DEC-0035` explicitly requires the extension to remain a client/adaptor rather than a second semantic engine. Because VS Code already knows how to consume LSP completion, hover, and signature-help responses, the extension work should be small and mostly about ensuring transport, configuration, and real validation are correct.
+
+## Scope
+
+### Included
+
+- Confirm the extension does not need or gain local semantic tables for stdlib, members, or signatures.
+- Adjust only the minimal extension/bootstrap behavior needed for the new LSP features to flow correctly.
+- Add verification coverage and manual validation guidance for the full wave.
+
+### Excluded
+
+- Compiler-side editorial resolution logic.
+- LSP-side protocol feature implementation.
+- Formatter/indentation, code actions, or non-wave-1 IDE features.
+
+## Non-Goals
+
+- Turning the extension into a feature-rich semantic client.
+- Adding hardcoded completion/signature content for PBS inside TypeScript runtime code.
+
+## Execution Steps
+
+### Step 1 - Verify thin-client integration boundaries
+
+**What:** Confirm the extension remains a pure LSP consumer for the new features.
+**How:** Review and adjust the extension only where necessary so completion, hover, and signature help are obtained from the LSP session without client-side semantic fallback tables.
+**File(s):** `tools/vscode-extension/src/**`, `tools/vscode-extension/package.json`.
+
+### Step 2 - Add any minimal structural configuration required by VS Code
+
+**What:** Keep static contribution surfaces minimal and structural.
+**How:** If VS Code requires additional structural contribution metadata for the new features, add only that metadata. Do not add curated PBS semantic or signature data into the extension package.
+**File(s):** `tools/vscode-extension/package.json`.
+
+### Step 3 - Add validation coverage for end-to-end editor assistance
+
+**What:** Lock the no-local-semantics rule and the end-to-end feature expectations.
+**How:** Add tests or deterministic verification steps that ensure:
+
+1. the extension connects and receives the feature set from the server;
+2. no local completion/signature tables were introduced;
+3. the user-facing wave can be exercised end to end.
+
+**File(s):** `tools/vscode-extension/**`, existing validation harnesses if present, and related docs/test notes.
+
+### Step 4 - Define manual smoke scenarios for wave 1 usability
+
+**What:** Make the wave verifiable as a product experience rather than only a protocol exercise.
+**How:** Document and run manual checks for:
+
+1. keyword and local-name completion;
+2. imported stdlib/member completion after `.`;
+3. hover on locals, imported services, builtin types, and methods;
+4. signature help during function/method/constructor calls.
+
+**File(s):** extension verification notes or adjacent implementation docs/tests as appropriate.
+
+## Test Requirements
+
+### Unit Tests
+
+- Any extension-side helpers introduced for structural integration only.
+
+### Integration Tests
+
+- End-to-end or near-end-to-end validation that VS Code consumes the server feature set without local semantic duplication.
+
+### Manual Verification
+
+- Open representative PBS files in VS Code and verify `completion`, `hover`, and `signature help` behavior matches the expected wave-1 scope.
+
+## Acceptance Criteria
+
+- [ ] The extension remains thin and contains no new hardcoded PBS semantic tables for members or signatures.
+- [ ] VS Code can consume the new LSP completion, hover, and signature-help responses without extension-side semantic authorship.
+- [ ] Wave-1 smoke scenarios are documented and manually verifiable.
+
+## Dependencies
+
+- `DEC-0035` accepted and normatively locked.
+- `PLN-0076` for the actual LSP feature delivery.
+
+## Risks
+
+- It is easy to accidentally patch around server gaps with client-local logic; this plan must resist that.
+- Validation can become too protocol-centric and miss real usability failures if manual smoke scenarios are weak.