add LSP agendas

discussion/index.ndjson

@@ -1,4 +1,19 @@
-{"type":"meta","next_id":{"DSC":39,"AGD":42,"DEC":40,"PLN":103,"LSN":55,"CLSN":1}}
+{"type":"meta","next_id":{"DSC":54,"AGD":57,"DEC":40,"PLN":103,"LSN":55,"CLSN":1}}
+{"type":"discussion","id":"DSC-0053","status":"open","ticket":"pbs-lsp-call-and-type-hierarchy","title":"PBS LSP Call and Type Hierarchy","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","call-hierarchy","type-hierarchy"],"agendas":[{"id":"AGD-0056","file":"AGD-0056-pbs-lsp-call-and-type-hierarchy.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0052","status":"open","ticket":"pbs-lsp-document-links","title":"PBS LSP Document Links","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","document-links","imports"],"agendas":[{"id":"AGD-0055","file":"AGD-0055-pbs-lsp-document-links.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0051","status":"open","ticket":"pbs-lsp-diagnostics-ux","title":"PBS LSP Diagnostics UX","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","diagnostics","ux"],"agendas":[{"id":"AGD-0054","file":"AGD-0054-pbs-lsp-diagnostics-ux.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0050","status":"open","ticket":"pbs-lsp-folding-and-selection-ranges","title":"PBS LSP Folding and Selection Ranges","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","folding","selection-range"],"agendas":[{"id":"AGD-0053","file":"AGD-0053-pbs-lsp-folding-and-selection-ranges.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0049","status":"open","ticket":"pbs-lsp-completion-depth","title":"PBS LSP Completion Depth","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","completion"],"agendas":[{"id":"AGD-0052","file":"AGD-0052-pbs-lsp-completion-depth.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0048","status":"open","ticket":"pbs-lsp-performance-cache-and-snapshots","title":"PBS LSP Performance Cache and Snapshots","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","performance","caching"],"agendas":[{"id":"AGD-0051","file":"AGD-0051-pbs-lsp-performance-cache-and-snapshots.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0047","status":"open","ticket":"pbs-lsp-semantic-tokens-semantic-classification","title":"PBS LSP Semantic Token Classification","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","semantic-tokens"],"agendas":[{"id":"AGD-0050","file":"AGD-0050-pbs-lsp-semantic-token-classification.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0046","status":"open","ticket":"pbs-lsp-import-assistance","title":"PBS LSP Import Assistance","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","imports","completion"],"agendas":[{"id":"AGD-0049","file":"AGD-0049-pbs-lsp-import-assistance.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0045","status":"open","ticket":"pbs-lsp-formatting","title":"PBS LSP Formatting","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","formatting"],"agendas":[{"id":"AGD-0048","file":"AGD-0048-pbs-lsp-formatting.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0044","status":"open","ticket":"pbs-lsp-code-actions","title":"PBS LSP Code Actions and Quick Fixes","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","code-actions","quick-fix"],"agendas":[{"id":"AGD-0047","file":"AGD-0047-pbs-lsp-code-actions-and-quick-fixes.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0043","status":"open","ticket":"pbs-lsp-rename-symbol","title":"PBS LSP Rename Symbol","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","rename"],"agendas":[{"id":"AGD-0046","file":"AGD-0046-pbs-lsp-rename-symbol.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0042","status":"open","ticket":"pbs-lsp-workspace-symbols","title":"PBS LSP Workspace Symbols","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","workspace-symbols"],"agendas":[{"id":"AGD-0045","file":"AGD-0045-pbs-lsp-workspace-symbols.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0041","status":"open","ticket":"pbs-lsp-document-symbols-outline","title":"PBS LSP Document Symbols and Outline","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","outline","document-symbols"],"agendas":[{"id":"AGD-0044","file":"AGD-0044-pbs-lsp-document-symbols-and-outline.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0040","status":"open","ticket":"pbs-lsp-find-references","title":"PBS LSP Find References","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","references"],"agendas":[{"id":"AGD-0043","file":"AGD-0043-pbs-lsp-find-references.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0039","status":"open","ticket":"pbs-lsp-go-to-definition","title":"PBS LSP Go to Definition","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","definition"],"agendas":[{"id":"AGD-0042","file":"AGD-0042-pbs-lsp-go-to-definition.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0038","status":"done","ticket":"studio-packer-rgba8888-asset-pipeline","title":"Studio and Packer RGBA8888 Asset Pipeline Alignment","created_at":"2026-05-23","updated_at":"2026-07-14","tags":["studio","packer","assets","glyph-bank","palette","rgba8888","runtime-alignment"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0053","file":"discussion/lessons/DSC-0038-studio-packer-rgba8888-asset-pipeline/LSN-0053-rgba8888-is-the-canonical-studio-packer-palette-contract.md","status":"done","created_at":"2026-07-14","updated_at":"2026-07-14"}]}
 {"type":"discussion","id":"DSC-0037","status":"done","ticket":"pbs-autocomplete-parameter-names","title":"PBS autocomplete parameter names for stdlib and method calls","created_at":"2026-05-08","updated_at":"2026-05-14","tags":["compiler-pbs","studio","lsp","autocomplete","signature-help","stdlib"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0052","file":"discussion/lessons/DSC-0037-pbs-autocomplete-parameter-names/LSN-0052-canonical-callable-parameter-names-through-pbs-editor-assistance.md","status":"done","created_at":"2026-05-14","updated_at":"2026-05-14"}]}
 {"type":"discussion","id":"DSC-0036","status":"in_progress","ticket":"pbs-symbol-documentation-and-hover-markdown","title":"Modelo de documentacao de simbolos em PBS e consumo markdown no hover","created_at":"2026-05-08","updated_at":"2026-07-15","tags":["compiler","compiler-pbs","studio","lsp","vscode","editor","hover","documentation","markdown"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-pbs-symbol-documentation-and-hover-markdown.md","status":"accepted","created_at":"2026-05-08","updated_at":"2026-07-15"}],"decisions":[{"id":"DEC-0039","file":"DEC-0039-pbs-symbol-documentation-with-doc-markdown-text-blocks.md","status":"accepted","created_at":"2026-07-15","updated_at":"2026-07-15","ref_agenda":"AGD-0039"}],"plans":[{"id":"PLN-0092","file":"PLN-0092-specify-pbs-doc-attribute-and-markdown-text-block-syntax.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0093","file":"PLN-0093-implement-pbs-lexer-support-for-documentation-text-blocks.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0094","file":"PLN-0094-extend-pbs-attribute-parser-and-ast-for-doc-markdown-payloads.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0095","file":"PLN-0095-implement-documentation-text-block-normalization.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0096","file":"PLN-0096-validate-doc-attribute-semantics-and-diagnostics.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0097","file":"PLN-0097-attach-doc-metadata-to-pbs-semantic-symbols.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0098","file":"PLN-0098-expose-doc-metadata-through-pbs-editorial-and-lsp-surfaces.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0099","file":"PLN-0099-render-doc-markdown-in-hover-composition.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0100","file":"PLN-0100-author-doc-metadata-for-stdlib-sdk-and-interface-declarations.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0101","file":"PLN-0101-protect-runtime-artifacts-from-doc-metadata-lowering.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0102","file":"PLN-0102-add-end-to-end-doc-documentation-conformance-coverage.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]}],"lessons":[]}

discussion/workflow/agendas/AGD-0042-pbs-lsp-go-to-definition.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0042
+ticket: pbs-lsp-go-to-definition
+title: PBS LSP Go to Definition
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, definition]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+PBS users cannot jump from a symbol use to its declaration, which makes navigation across source files, stdlib imports, services, and generated/editorial surfaces slow and error-prone.
+
+## Context
+
+The current LSP exposes diagnostics, hover, completion, signature help, and semantic tokens. The compiler already builds semantic read surfaces and editorial symbol resolution for hover/completion, but there is no LSP definition capability or stable location mapping exposed to VS Code.
+
+## Open Questions
+
+- [ ] Which symbol categories must be supported in the first definition wave?
+- [ ] Should stdlib and generated/supplemental declarations navigate to source files, virtual documents, or remain hover-only?
+- [ ] What identity model should connect an editor token to the canonical declaration without relying on text search?
+
+## Options
+
+### Option A - Syntactic location lookup
+
+- **Approach:** Use parser spans and local AST traversal to map the token under cursor to a declaration with matching text.
+- **Pro:** Fast to implement and useful for same-file declarations.
+- **Con:** Breaks on overloads, imports, stdlib, aliases, and same-name symbols.
+- **Maintainability:** Weak; it creates a second navigation model separate from semantic resolution.
+
+### Option B - Semantic identity lookup
+
+- **Approach:** Extend the compiler/editorial surface with resolved declaration locations keyed by symbol identity, then expose `textDocument/definition`.
+- **Pro:** Correct for imports, overloads, methods, stdlib-backed declarations, and future references/rename.
+- **Con:** Requires explicit location metadata in semantic/editorial surfaces.
+- **Maintainability:** Strong; it becomes shared infrastructure for references, rename, hierarchy, and code actions.
+
+## Tradeoffs
+
+The syntactic option is tempting for speed, but it would likely be thrown away once references and rename arrive. The main tradeoff is whether stdlib/supplemental declarations must navigate to physical files immediately or can initially return no location while still supporting project symbols.
+
+## Recommendation
+
+Prefer Option B. Build a reusable semantic location index and implement the first wave for project source declarations, then define a policy for stdlib/supplemental targets.
+
+## Discussion
+
+This should probably be the first navigation agenda to resolve because references, rename, workspace symbols, and hierarchy depend on the same symbol identity/location model.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Decide the first-wave symbol categories and whether stdlib/supplemental declarations require virtual document support.

discussion/workflow/agendas/AGD-0043-pbs-lsp-find-references.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0043
+ticket: pbs-lsp-find-references
+title: PBS LSP Find References
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, references]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+PBS users cannot ask where a symbol is used, so changes to functions, services, structs, constants, and stdlib-facing APIs require manual search that confuses overloads and unrelated text matches.
+
+## Context
+
+Completion and hover already resolve symbols in local editor context, but the LSP does not expose references and the compiler/editorial layer does not yet provide project-wide usage locations keyed by semantic identity.
+
+## Open Questions
+
+- [ ] Which declarations need reference tracking first: local functions, methods, types, constants, imports, stdlib symbols, or all of them?
+- [ ] How should overloads and same-name symbols in different scopes be disambiguated?
+- [ ] Should references include declarations, write/read classification, or only usage sites in the first wave?
+
+## Options
+
+### Option A - Text search with filters
+
+- **Approach:** Search workspace text for the selected identifier and filter obvious false positives by token kind.
+- **Pro:** Simple and fast for early demos.
+- **Con:** Incorrect for overloads, scope, shadowing, fields, methods, imports, and generated/stdlib surfaces.
+- **Maintainability:** Poor; later semantic references would duplicate and replace it.
+
+### Option B - Semantic usage index
+
+- **Approach:** During semantic analysis, emit definition and usage sites tied to stable symbol identities and expose `textDocument/references`.
+- **Pro:** Correct foundation for rename, call hierarchy, diagnostics UX, and code actions.
+- **Con:** Requires compiler-facing usage modeling and careful invalidation.
+- **Maintainability:** Strong; one source of truth for all symbol usage features.
+
+## Tradeoffs
+
+Reference accuracy matters more than early breadth. False positives are worse than missing unsupported categories because users will trust rename and references for safe edits.
+
+## Recommendation
+
+Prefer Option B, but scope the first wave to project-owned declarations whose identity is already resolved reliably.
+
+## Discussion
+
+References should follow go-to-definition because both need the same identity and location model.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Define first-wave symbol categories and whether declarations are included in reference results.

discussion/workflow/agendas/AGD-0044-pbs-lsp-document-symbols-and-outline.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0044
+ticket: pbs-lsp-document-symbols-outline
+title: PBS LSP Document Symbols and Outline
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, outline, document-symbols]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+PBS files do not populate a reliable VS Code outline, forcing users to navigate long source files manually instead of scanning declarations and members structurally.
+
+## Context
+
+The parser and semantic surfaces know top-level declarations and many member declarations. The LSP currently does not announce documentSymbolProvider and does not map PBS declarations to DocumentSymbol or SymbolInformation payloads.
+
+## Open Questions
+
+- [ ] Should the first outline be syntactic, semantic, or hybrid?
+- [ ] Which hierarchy should be shown for structs, services, hosts, contracts, builtin types, enums, and methods?
+- [ ] How should invalid or partially parsed files contribute to outline during editing?
+
+## Options
+
+### Option A - AST-only outline
+
+- **Approach:** Map parsed declarations and member spans directly to LSP `DocumentSymbol`.
+- **Pro:** Works even when semantic analysis is incomplete and gives immediate editor value.
+- **Con:** Cannot classify every symbol with semantic precision.
+- **Maintainability:** Good if kept as structural outline, not overloaded with semantic behavior.
+
+### Option B - Semantic outline
+
+- **Approach:** Build outline from semantic symbols after analysis.
+- **Pro:** More accurate kinds and can hide invalid/unresolved surfaces.
+- **Con:** More fragile during active editing and depends on full semantic success.
+- **Maintainability:** Good for final precision, but heavier than needed for outline.
+
+## Tradeoffs
+
+Outline should remain available during broken intermediate edits. Semantic precision is useful, but not at the cost of disappearing structure while typing.
+
+## Recommendation
+
+Prefer Option A with semantic enrichment where available. Use AST spans as the stable backbone.
+
+## Discussion
+
+Document symbols are relatively independent and can be implemented before definition/references.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Decide hierarchy and symbol kinds for PBS declarations and members.

discussion/workflow/agendas/AGD-0045-pbs-lsp-workspace-symbols.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0045
+ticket: pbs-lsp-workspace-symbols
+title: PBS LSP Workspace Symbols
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, workspace-symbols]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+VS Code cannot search PBS symbols across the workspace, so users cannot quickly jump to functions, services, structs, constants, or stdlib-exposed APIs by name.
+
+## Context
+
+Document-level editorial features exist, but the LSP does not announce workspaceSymbolProvider and the compiler pipeline does not expose a project-wide symbol index designed for editor queries.
+
+## Open Questions
+
+- [ ] Should workspace symbols include only project files or also imported stdlib and SDK surfaces?
+- [ ] What symbol kinds and ranking should be returned for duplicate names or overloads?
+- [ ] Should the symbol index be cached from analysis snapshots or rebuilt per request in the first implementation?
+
+## Options
+
+### Option A - Project source index only
+
+- **Approach:** Index project-owned declarations from analysis snapshots and expose `workspace/symbol`.
+- **Pro:** Clear ownership and physical locations.
+- **Con:** Does not help users discover stdlib/SDK symbols.
+- **Maintainability:** Strong as a first wave.
+
+### Option B - Project plus stdlib index
+
+- **Approach:** Include project declarations and imported stdlib/SDK surfaces in the workspace symbol result set.
+- **Pro:** Better discovery, especially for new users.
+- **Con:** Requires a navigation policy for stdlib source or virtual targets.
+- **Maintainability:** Good if stdlib target handling is solved; awkward otherwise.
+
+## Tradeoffs
+
+Workspace symbols are partly navigation and partly discovery. Including stdlib too early can create broken jumps if target locations are not defined.
+
+## Recommendation
+
+Prefer Option A first, then add stdlib once definition has a target policy.
+
+## Discussion
+
+This should follow document symbols and the semantic location/index work.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Decide whether first-wave workspace search includes stdlib or project-only symbols.

discussion/workflow/agendas/AGD-0046-pbs-lsp-rename-symbol.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0046
+ticket: pbs-lsp-rename-symbol
+title: PBS LSP Rename Symbol
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, rename]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+PBS users cannot safely rename a symbol through the editor, so they must edit text manually and risk missing references or changing unrelated overloads and same-name declarations.
+
+## Context
+
+Rename requires the same semantic identity and reference machinery needed by definition/references, plus workspace edits and conflict detection. The current LSP does not announce renameProvider.
+
+## Open Questions
+
+- [ ] Which symbols should be renameable in the first wave, and which should be protected such as stdlib, generated, host, or builtin declarations?
+- [ ] How should rename handle overloads, member methods, imports, and labels with the same text?
+- [ ] What validation should run before returning a WorkspaceEdit?
+
+## Options
+
+### Option A - Local file rename
+
+- **Approach:** Rename only references in the current file using local semantic resolution.
+- **Pro:** Smaller blast radius and easier conflict handling.
+- **Con:** Incomplete for imported symbols and project-wide APIs.
+- **Maintainability:** Acceptable only if explicitly presented as limited.
+
+### Option B - Workspace semantic rename
+
+- **Approach:** Use a project-wide reference index and return a `WorkspaceEdit` for all usage and declaration sites.
+- **Pro:** Matches user expectations for editor rename.
+- **Con:** Requires reliable references, collision checks, and write-safety across files.
+- **Maintainability:** Strong once references exist.
+
+## Tradeoffs
+
+Rename is high trust. A partial or text-based rename can corrupt code silently, so scope must be explicit and conservative.
+
+## Recommendation
+
+Prefer Option B after semantic references are implemented. If delivered earlier, ship only a clearly limited local rename.
+
+## Discussion
+
+Do not implement rename before definition/references are resolved.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Decide whether rename waits for workspace references or ships a limited local-only wave.

discussion/workflow/agendas/AGD-0047-pbs-lsp-code-actions-and-quick-fixes.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0047
+ticket: pbs-lsp-code-actions
+title: PBS LSP Code Actions and Quick Fixes
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, code-actions, quick-fix]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+PBS diagnostics are visible, but users do not get actionable quick fixes for common compiler/editor problems, making simple repairs slower than necessary.
+
+## Context
+
+The LSP maps diagnostics but does not announce codeActionProvider. Compiler diagnostics already carry codes and ranges, but not every diagnostic has enough structured repair data to generate safe edits.
+
+## Open Questions
+
+- [ ] Which diagnostics should receive quick fixes first?
+- [ ] Should code actions be produced from diagnostic codes only, or from structured compiler repair hints?
+- [ ] How should imports, reserved attributes, missing methods, and invalid Doc shapes be prioritized?
+
+## Options
+
+### Option A - Diagnostic-code quick fixes
+
+- **Approach:** Map known diagnostic codes to simple edits in the LSP layer.
+- **Pro:** Fast for a small set of obvious repairs.
+- **Con:** Couples fixes to diagnostic text/ranges and can become brittle.
+- **Maintainability:** Moderate if limited to trivial edits.
+
+### Option B - Compiler repair hints
+
+- **Approach:** Extend diagnostics with structured repair metadata and let the LSP map hints to code actions.
+- **Pro:** Keeps product logic close to compiler knowledge.
+- **Con:** Requires a new diagnostic/repair contract.
+- **Maintainability:** Strong for non-trivial fixes and future frontends.
+
+## Tradeoffs
+
+Quick fixes are only useful if safe. Simple code-based fixes can ship first, but imports and generated stubs need stronger compiler context.
+
+## Recommendation
+
+Prefer Option B as the target design, with Option A allowed only for a small bootstrap set of unambiguous repairs.
+
+## Discussion
+
+This should follow diagnostics UX and import assistance for the first high-value fixes.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Pick the first three diagnostic codes eligible for safe quick fixes.

discussion/workflow/agendas/AGD-0048-pbs-lsp-formatting.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0048
+ticket: pbs-lsp-formatting
+title: PBS LSP Formatting
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, formatting]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+PBS formatting is not automated, so style drifts across files, especially around attributes, services, blocks, imports, and multi-line Doc text blocks.
+
+## Context
+
+The LSP does not announce documentFormattingProvider. PBS has a parser and AST, but formatting must preserve documentation text block content while normalizing surrounding syntax and indentation.
+
+## Open Questions
+
+- [ ] Should formatting be AST-based, token-based, or hybrid to preserve comments and text blocks?
+- [ ] What canonical style should PBS use for attributes, braces, imports, params, and text blocks?
+- [ ] Should the first wave support full document formatting only, or also range/on-type formatting?
+
+## Options
+
+### Option A - Token-preserving formatter
+
+- **Approach:** Format from tokens and trivia, preserving comments and documentation text block contents.
+- **Pro:** Safer for active editing and text blocks.
+- **Con:** Harder to enforce deep structural layout.
+- **Maintainability:** Good if PBS formatting remains mostly syntactic.
+
+### Option B - AST pretty-printer
+
+- **Approach:** Reprint code from the AST using canonical style rules.
+- **Pro:** Produces consistent output.
+- **Con:** Risks losing comments/trivia and cannot handle malformed files well.
+- **Maintainability:** Strong only after AST/trivia ownership is explicit.
+
+## Tradeoffs
+
+Formatting must not damage `Doc` text blocks. That makes trivia preservation a first-class requirement rather than an implementation detail.
+
+## Recommendation
+
+Prefer Option A or a hybrid token/AST formatter. Avoid a pure AST pretty-printer until comments/trivia are modeled.
+
+## Discussion
+
+Formatter decision should define canonical style before implementation.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Decide PBS canonical formatting rules for attributes, braces, imports, params, and text blocks.

discussion/workflow/agendas/AGD-0049-pbs-lsp-import-assistance.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0049
+ticket: pbs-lsp-import-assistance
+title: PBS LSP Import Assistance
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, imports, completion]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+PBS users do not get import-aware assistance, so discovering exported symbols and adding the right import from barrels, stdlib, or project modules remains manual.
+
+## Context
+
+Completion already exists for local/editorial contexts, and stdlib imports are understood by the compiler pipeline. The LSP does not yet provide auto-import completion, organize imports, or import quick fixes.
+
+## Open Questions
+
+- [ ] Should auto-import target project modules, stdlib modules, or both in the first wave?
+- [ ] How should barrels and explicit module imports be ranked and rendered in completion?
+- [ ] Should organize imports be a code action, source action, formatter responsibility, or separate feature?
+
+## Options
+
+### Option A - Import completion only
+
+- **Approach:** Suggest symbols from known modules and include import detail, but do not edit imports automatically.
+- **Pro:** Low risk and improves discovery.
+- **Con:** Still leaves manual import edits.
+- **Maintainability:** Good as a stepping stone.
+
+### Option B - Auto-import and organize imports
+
+- **Approach:** Completion/code actions insert missing imports and source actions sort/remove unused imports.
+- **Pro:** Matches modern editor expectations.
+- **Con:** Requires robust module export indexing and edit placement rules.
+- **Maintainability:** Strong if built on a proper import graph.
+
+## Tradeoffs
+
+Auto-import depends on knowing canonical exports and choosing an edit location. Doing that ad hoc in completion would create formatting and duplicate import issues.
+
+## Recommendation
+
+Prefer Option B as the target, but start with import-aware suggestions plus a limited missing-import quick fix.
+
+## Discussion
+
+This should be coordinated with code actions and formatter.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Decide first-wave import sources: stdlib only, project modules only, or both.

discussion/workflow/agendas/AGD-0050-pbs-lsp-semantic-token-classification.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0050
+ticket: pbs-lsp-semantic-tokens-semantic-classification
+title: PBS LSP Semantic Token Classification
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, semantic-tokens]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+PBS semantic highlighting exists, but parts of the token classification can remain lexical or superficial, which limits visual accuracy for same-looking identifiers with different semantic roles.
+
+## Context
+
+The current LSP announces full semantic tokens and maps frontend semantic presentation to VS Code. The compiler has semantic read surfaces that can classify symbols more accurately than raw tokenization.
+
+## Open Questions
+
+- [ ] Which token categories must become semantic identity-based first?
+- [ ] Should semantic tokens be produced from compiler semantic surfaces, parser AST, lexer tokens, or layered output?
+- [ ] How should tokens behave in files with syntax or semantic errors during active editing?
+
+## Options
+
+### Option A - Lexical tokens with semantic overlays
+
+- **Approach:** Keep lexer-based tokenization as baseline and overlay semantic categories where resolution succeeds.
+- **Pro:** Stable during broken edits and incremental to improve.
+- **Con:** Some unresolved identifiers remain visually generic.
+- **Maintainability:** Strong because fallback behavior is explicit.
+
+### Option B - Fully semantic token stream
+
+- **Approach:** Generate all semantic tokens from compiler semantic surfaces.
+- **Pro:** Maximum accuracy when analysis succeeds.
+- **Con:** Highlighting may disappear or degrade sharply on incomplete code.
+- **Maintainability:** Risky unless snapshot/error recovery is excellent.
+
+## Tradeoffs
+
+Highlighting must be resilient while the user is typing. A perfect semantic pass that fails on partial code is worse than a layered model.
+
+## Recommendation
+
+Prefer Option A: lexical baseline plus semantic overlays from resolved symbols.
+
+## Discussion
+
+This can proceed independently but benefits from LSP snapshot/cache work.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Choose semantic overlay categories for the first pass.

discussion/workflow/agendas/AGD-0051-pbs-lsp-performance-cache-and-snapshots.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0051
+ticket: pbs-lsp-performance-cache-and-snapshots
+title: PBS LSP Performance Cache and Snapshots
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, performance, caching]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+Several PBS LSP requests rebuild or reanalyze substantial project state, which can become slow or jittery as projects grow and as richer features are added.
+
+## Context
+
+The current bridge favors correctness and simplicity by invoking compiler pipeline analysis for diagnostics and editorial documents. A complete LSP needs snapshot caching, invalidation, cancellation, and predictable latency.
+
+## Open Questions
+
+- [ ] What is the canonical project/document snapshot boundary for LSP requests?
+- [ ] Which requests can reuse semantic read surfaces safely across document changes?
+- [ ] How should cancellation, stale responses, and background reanalysis be handled?
+
+## Options
+
+### Option A - Request-local analysis
+
+- **Approach:** Keep each LSP request self-contained and rebuild analysis as needed.
+- **Pro:** Simple, deterministic, and less stateful.
+- **Con:** Latency grows with project size and feature richness.
+- **Maintainability:** Good for correctness, weak for interactive performance.
+
+### Option B - Project snapshot cache
+
+- **Approach:** Maintain per-project analysis snapshots with document overlays, invalidation, and cancellation-aware request handling.
+- **Pro:** Required for responsive definition, references, rename, and semantic tokens.
+- **Con:** Introduces lifecycle complexity and stale-result risks.
+- **Maintainability:** Strong if snapshot ownership and invalidation are explicit.
+
+## Tradeoffs
+
+A complete LSP needs shared state, but shared state must not leak stale analysis into edits. The decision is about the boundary, not just caching.
+
+## Recommendation
+
+Prefer Option B before implementing workspace-wide features like references and rename.
+
+## Discussion
+
+Define snapshot lifecycle, invalidation triggers, and cancellation policy.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Decide whether snapshot caching is a prerequisite for references/rename or can be staged later.

discussion/workflow/agendas/AGD-0052-pbs-lsp-completion-depth.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0052
+ticket: pbs-lsp-completion-depth
+title: PBS LSP Completion Depth
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, completion]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+PBS completion works for core cases, but a complete daily-use experience needs ranking, resolve details, snippets, overload handling, context-aware suggestions, and richer documentation.
+
+## Context
+
+The current LSP announces completion with trigger character '.' and returns detail/documentation for resolved compiler candidates. It does not use resolveProvider, snippets, broad trigger contexts, or advanced ranking.
+
+## Open Questions
+
+- [ ] Which completion contexts should be supported first beyond member access?
+- [ ] Should completion use resolveProvider for expensive documentation/details or return everything eagerly?
+- [ ] How should overloads, snippets, imports, keywords, and stdlib candidates be ranked?
+
+## Options
+
+### Option A - Eager rich completion
+
+- **Approach:** Return labels, details, docs, and snippets directly in every completion response.
+- **Pro:** Simple client behavior and immediate docs.
+- **Con:** Can become expensive for broad/global completion.
+- **Maintainability:** Good while candidate sets remain small.
+
+### Option B - Completion resolve provider
+
+- **Approach:** Return lightweight candidates first and populate expensive docs/details through `completionItem/resolve`.
+- **Pro:** Scales better for large candidate sets and import-aware suggestions.
+- **Con:** Requires client/server resolve plumbing and stable candidate identities.
+- **Maintainability:** Strong for a full LSP.
+
+## Tradeoffs
+
+The current eager model is fine for scoped completions, but global/import-aware completion may need resolve to avoid latency.
+
+## Recommendation
+
+Prefer a staged approach: keep eager for current contexts, design resolve before broad workspace/import completion.
+
+## Discussion
+
+Define completion contexts and ranking before adding snippets or resolve.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+List first-wave completion contexts beyond member access.

discussion/workflow/agendas/AGD-0053-pbs-lsp-folding-and-selection-ranges.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0053
+ticket: pbs-lsp-folding-and-selection-ranges
+title: PBS LSP Folding and Selection Ranges
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, folding, selection-range]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+PBS users do not get structural folding or smart selection ranges, so navigating and selecting nested functions, blocks, services, attributes, and Doc text blocks is more manual than it should be.
+
+## Context
+
+The parser knows syntactic spans for declarations and blocks. The LSP currently does not announce foldingRangeProvider or selectionRangeProvider.
+
+## Open Questions
+
+- [ ] Should folding ranges be computed from AST spans, token pairs, or a hybrid that handles malformed files?
+- [ ] Which constructs should fold in the first wave: imports, declarations, blocks, attributes, text blocks, or all of them?
+- [ ] What selection range hierarchy should VS Code expose for identifiers, calls, params, blocks, and declarations?
+
+## Options
+
+### Option A - Parser span ranges
+
+- **Approach:** Use AST spans for declarations, blocks, parameter lists, and text blocks.
+- **Pro:** Accurate for well-formed code and easy to map to LSP ranges.
+- **Con:** Can degrade when parsing fails mid-file.
+- **Maintainability:** Good because parser owns structure.
+
+### Option B - Token pair scanning
+
+- **Approach:** Compute ranges from brace/paren/text-block tokens without relying on full AST validity.
+- **Pro:** More resilient during malformed edits.
+- **Con:** Less semantically meaningful and can produce noisy ranges.
+- **Maintainability:** Good only as fallback.
+
+## Tradeoffs
+
+Folding and selection should keep working while typing. AST ranges are higher quality, but token fallback may be needed for broken files.
+
+## Recommendation
+
+Prefer a hybrid: AST ranges first, token fallback for unmatched/incomplete constructs.
+
+## Discussion
+
+This is an editor UX feature with low semantic dependency and can be planned independently.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Decide first-wave foldable constructs and selection hierarchy.

discussion/workflow/agendas/AGD-0054-pbs-lsp-diagnostics-ux.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0054
+ticket: pbs-lsp-diagnostics-ux
+title: PBS LSP Diagnostics UX
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, diagnostics, ux]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+PBS diagnostics reach VS Code, but the editor experience can still be hard to act on when ranges, related information, severity, and phase context are too generic.
+
+## Context
+
+The LSP maps compiler diagnostics to LSP diagnostics. Compiler diagnostics include phase/code/message/range in several paths, but not all editor-friendly fields are consistently exposed.
+
+## Open Questions
+
+- [ ] Which diagnostics need better ranges or related information first?
+- [ ] Should diagnostic source include compiler phase, frontend, or both?
+- [ ] What structured diagnostic metadata is needed for future quick fixes without coupling UI to text messages?
+
+## Options
+
+### Option A - Mapper-only UX improvements
+
+- **Approach:** Improve LSP diagnostic mapping using existing diagnostic fields.
+- **Pro:** Quick improvements to source, severity, and display consistency.
+- **Con:** Cannot add missing related spans or repair metadata that compiler diagnostics do not expose.
+- **Maintainability:** Good for presentation-only changes.
+
+### Option B - Structured diagnostic contract
+
+- **Approach:** Extend compiler diagnostics with editor-facing metadata such as phase, related locations, stable quick-fix hints, and refined ranges.
+- **Pro:** Enables better diagnostics and future code actions without parsing message text.
+- **Con:** Requires compiler/core diagnostic API changes.
+- **Maintainability:** Strong as the foundation for quick fixes and richer UX.
+
+## Tradeoffs
+
+Some improvements belong in the LSP mapper, but the most valuable changes require structured information at diagnostic creation time.
+
+## Recommendation
+
+Prefer Option B as the target, with mapper-only cleanup allowed for low-risk display fixes.
+
+## Discussion
+
+This agenda should inform code actions before quick fixes become broad.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Inventory high-frequency diagnostics and identify which need better ranges, related information, or repair hints.

discussion/workflow/agendas/AGD-0055-pbs-lsp-document-links.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0055
+ticket: pbs-lsp-document-links
+title: PBS LSP Document Links
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, document-links, imports]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+PBS import/module references and asset-like surfaces are plain text in VS Code, so users cannot click through to imported modules or related project resources.
+
+## Context
+
+The compiler understands module references and project files. The LSP does not announce documentLinkProvider, and the VS Code extension delegates all language behavior to the server.
+
+## Open Questions
+
+- [ ] Which references should become document links first: imports, barrels, stdlib modules, assets/addressables, or docs?
+- [ ] How should virtual or stdlib resources be represented as link targets?
+- [ ] Should document links overlap with go-to-definition or remain a separate lightweight navigation feature?
+
+## Options
+
+### Option A - Import/module links only
+
+- **Approach:** Expose `documentLink` for module references such as `@sdk:gfx` and barrel paths.
+- **Pro:** Narrow, useful, and mostly aligned with existing module resolution.
+- **Con:** Does not cover assets/addressables or documentation links.
+- **Maintainability:** Strong first wave.
+
+### Option B - General resource links
+
+- **Approach:** Link imports, stdlib modules, assets, addressables, and possibly documentation/resource surfaces.
+- **Pro:** Richer navigation across project resources.
+- **Con:** Requires resource-specific target policy and may overlap with definition.
+- **Maintainability:** Good only after resource ownership is defined.
+
+## Tradeoffs
+
+Document links should remain lightweight. If a link requires semantic identity and symbol resolution, it may belong in go-to-definition instead.
+
+## Recommendation
+
+Prefer Option A first: imports and module references only.
+
+## Discussion
+
+Coordinate stdlib target handling with go-to-definition.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Decide first-wave link targets and how stdlib/module URIs are represented.

discussion/workflow/agendas/AGD-0056-pbs-lsp-call-and-type-hierarchy.md

@@ -0,0 +1,62 @@
+---
+id: AGD-0056
+ticket: pbs-lsp-call-and-type-hierarchy
+title: PBS LSP Call and Type Hierarchy
+status: open
+created: 2026-07-15
+resolved:
+decision:
+tags: [studio, lsp, vscode, compiler-pbs, editor, call-hierarchy, type-hierarchy]
+---
+
+## Pain
+
+Domain owner: `studio/lsp`
+
+PBS users cannot inspect call relationships or type/member relationships from the editor, which limits understanding of larger projects after basic navigation exists.
+
+## Context
+
+Call hierarchy and type hierarchy are advanced LSP features. They depend on reliable semantic identity, references, callsite classification, and type ownership surfaces, so they should probably follow definition/references rather than precede them.
+
+## Open Questions
+
+- [ ] Should call hierarchy and type hierarchy be one discussion or split after dependencies are clearer?
+- [ ] Which relationships are valuable for PBS: function call graph, service method calls, struct methods, contract implementations, host/intrinsic calls, or all of them?
+- [ ] What prerequisite symbol/reference infrastructure must be completed before this feature is safe to implement?
+
+## Options
+
+### Option A - Call hierarchy only
+
+- **Approach:** Implement incoming/outgoing calls for functions and methods after callsite references are stable.
+- **Pro:** Directly useful and builds on executable call resolution.
+- **Con:** Does not cover type ownership, contracts, or implementations.
+- **Maintainability:** Strong if based on the reference/callsite index.
+
+### Option B - Split call hierarchy and type hierarchy
+
+- **Approach:** Treat call graph and type/member/contract hierarchy as separate decisions and implementations.
+- **Pro:** Avoids mixing two different semantic models.
+- **Con:** Creates more workflow artifacts and sequencing work.
+- **Maintainability:** Strong; each feature can evolve on its own contract.
+
+## Tradeoffs
+
+Call hierarchy and type hierarchy share LSP vocabulary but not the same compiler data. Coupling them too early would make the first implementation harder to reason about.
+
+## Recommendation
+
+Prefer Option B: split after this agenda confirms dependencies, likely implementing call hierarchy first.
+
+## Discussion
+
+This should wait until definition and references are complete.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Decide whether to split into two discussions before moving to decisions.