discussion updated

.gitignore

@@ -10,6 +10,9 @@ build
 # Ignore Kotlin plugin data
 .kotlin
 
+.python-version
+.venv
+
 /debug/
 !prometeu-studio/src/main/java/p/studio/workspaces/debug/
 !prometeu-studio/src/main/java/p/studio/workspaces/debug/**

discussion/index.ndjson

@@ -1,4 +1,5 @@
-{"type":"meta","next_id":{"DSC":37,"AGD":40,"DEC":36,"PLN":78,"LSN":52,"CLSN":1}}
+{"type":"meta","next_id":{"DSC":38,"AGD":41,"DEC":36,"PLN":78,"LSN":52,"CLSN":1}}
+{"type":"discussion","id":"DSC-0037","status":"open","ticket":"pbs-autocomplete-parameter-names","title":"PBS autocomplete parameter names for stdlib and method calls","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["compiler-pbs","studio","lsp","autocomplete","signature-help","stdlib"],"agendas":[{"id":"AGD-0040","file":"AGD-0040-pbs-autocomplete-parameter-names-for-stdlib-and-method-calls.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08"}],"decisions":[],"plans":[],"lessons":[]}
 {"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":"done","ticket":"pbs-lsp-editor-assistance-wave-1","title":"Wave 1 de assistencia editorial via LSP para PBS no VS Code","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["studio","lsp","vscode","compiler","compiler-pbs","editor","completion","hover","signature-help"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0051","file":"discussion/lessons/DSC-0035-pbs-lsp-editor-assistance-wave-1/LSN-0051-compiler-backed-editor-assistance-for-pbs.md","status":"done","created_at":"2026-05-08","updated_at":"2026-05-08"}]}
 {"type":"discussion","id":"DSC-0034","status":"done","ticket":"frontend-semantic-host-projection-flexibility","title":"Frontend semantic vocabulary flexibility and declarative host projection","created_at":"2026-05-06","updated_at":"2026-05-07","tags":["compiler","compiler-general","frontend","semantics","vscode","host-projection","lsp"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0034-frontend-semantic-host-projection-flexibility/LSN-0048-frontend-owned-semantic-vocabularies-with-declarative-host-projection.md","status":"done","created_at":"2026-05-07","updated_at":"2026-05-07"}]}

discussion/lessons/DSC-0035-pbs-lsp-editor-assistance-wave-1/LSN-0051-compiler-backed-editor-assistance-for-pbs.md

@@ -0,0 +1,78 @@
+---
+id: LSN-0051
+ticket: pbs-lsp-editor-assistance-wave-1
+title: Compiler-Backed Editor Assistance for PBS
+created: 2026-05-08
+tags: [studio, lsp, vscode, compiler, compiler-pbs, editor, completion, hover, signature-help]
+---
+
+## Original Problem
+
+PBS editing in VS Code already had basic diagnostics and frontend-owned semantic highlighting, but it still lacked the minimum assistance expected during everyday code authoring:
+
+1. no `completion`;
+2. placeholder-only `hover`;
+3. no `signature help`.
+
+Without those features, the editor behaved more like a colored diagnostic viewer than a practical PBS authoring surface.
+
+## Consolidated Decision
+
+Wave 1 of PBS editor assistance is `completion`, symbol-resolved `hover`, and `signature help`.
+
+These features must be built on one compiler-backed editorial resolution surface. The VS Code extension remains a thin LSP client, and the LSP layer projects compiler knowledge into protocol responses instead of inventing editor-local semantic tables.
+
+The shared surface must be able to describe:
+
+1. symbol identity and kind;
+2. module or origin when relevant;
+3. signature or shape when applicable;
+4. available members for recognized receivers;
+5. optional documentation when available.
+
+The wave explicitly excludes formatter work, robust automatic indentation, `go to definition`, `references`, `rename`, quick fixes, broad code actions, and the PBS authored-documentation syntax.
+
+## Final Implementation Shape
+
+The work was decomposed into three execution fronts:
+
+1. `compiler/pbs` owns the editorial resolution model for symbols, members, signatures, and optional documentation.
+2. `studio/lsp` exposes completion, hover, and signature-help request handling over that model and advertises the corresponding LSP capabilities.
+3. `tools/vscode-extension` consumes the LSP responses as a thin client and must not add hardcoded PBS semantic tables for members, stdlib, or signatures.
+
+This split keeps semantic truth in the compiler, protocol ownership in the LSP server, and UI integration in the extension.
+
+## Examples
+
+Completion should cover at least:
+
+1. language keywords;
+2. local names in scope;
+3. relevant imported or public symbols;
+4. members after `.` for recognized surfaces such as services, hosts, builtin types, structs, and related callable surfaces.
+
+Hover should include, when available:
+
+1. symbol kind;
+2. signature;
+3. module or origin;
+4. basic type or shape.
+
+Signature help should cover function, method, and constructor calls with active signature and active parameter information.
+
+## Pitfalls
+
+Do not implement completion, hover, and signature help as three independent semantic paths. That duplicates parser, linking, stdlib, and member knowledge, then makes the editor inconsistent.
+
+Do not patch around missing server behavior in the VS Code extension. Client-local tables for PBS members, stdlib, or signatures turn the extension into a second semantic engine.
+
+Do not block this wave on authored PBS documentation syntax. The editorial model should have an optional documentation slot, but the language feature for authoring that documentation belongs to a separate discussion.
+
+Do not broaden this wave into general IDE support. Definition, references, rename, formatter, quick fixes, and broad code actions are later work.
+
+## References
+
+- `DEC-0035` captured the normative decision for wave 1.
+- `PLN-0075` covered the compiler-side editorial resolution surface.
+- `PLN-0076` covered LSP projection and protocol capabilities.
+- `PLN-0077` covered VS Code thin-client consumption and validation.

discussion/workflow/agendas/AGD-0040-pbs-autocomplete-parameter-names-for-stdlib-and-method-calls.md

@@ -0,0 +1,153 @@
+---
+id: AGD-0040
+ticket: pbs-autocomplete-parameter-names
+title: PBS autocomplete parameter names for stdlib and method calls
+status: open
+created: 2026-05-08
+resolved:
+decision:
+tags: [compiler-pbs, studio, lsp, autocomplete, signature-help, stdlib]
+---
+
+## Pain
+
+Domain owner: `compiler/pbs`
+
+Autocomplete and signature help currently show method/function parameters as arg0, arg1, etc., especially for stdlib APIs, making calls hard to understand at the point of use.
+
+The immediate user-facing problem is not just cosmetic. When a completion inserts or previews something like:
+
+- `draw(arg0, arg1, arg2)`
+- `setTile(arg0, arg1, arg2)`
+- `loadSprite(arg0)`
+
+the editor fails at the exact moment it should reduce lookup cost. The user has to leave the call site, inspect docs/source, or guess what each argument means.
+
+For PBS, this is especially damaging because stdlib and host-backed APIs are likely to be the most frequently discovered through autocomplete.
+
+## Context
+
+The compiler-backed LSP wave can surface completions, hover, and signature help, but the parameter identity exposed to editor consumers is not yet reliable or authored enough for ergonomic API use.
+
+Subdomains touched:
+
+- `compiler/general`
+- `studio/lsp`
+- `tools/vscode-extension`
+
+Related discussions:
+
+- `DSC-0035` established the compiler-backed editor assistance wave.
+- `DSC-0036` is discussing authored symbol documentation and markdown hover.
+
+This agenda is narrower than `DSC-0036`.
+
+`DSC-0036` asks how symbol documentation should be authored and transported. This agenda asks where canonical parameter names come from and how completion/signature surfaces should consume them. Parameter names may later connect to documentation, but they need their own canonical identity even without full prose documentation.
+
+## Open Questions
+
+- [ ] Where should canonical parameter names for stdlib and builtins live?
+- [ ] Should parameter names be part of the compiler semantic model, external stdlib metadata, authored documentation, or derived from declarations?
+- [ ] How should completion snippets, signature help, and hover consume the same parameter identity?
+- [ ] Should generated fallback names like `arg0` be allowed to reach user-facing editor UI at all?
+- [ ] Do user-authored PBS functions already preserve parameter names well enough, or is the problem shared by all callable symbols?
+- [ ] Are stdlib APIs represented as PBS declarations, Java/Kotlin host descriptors, compiler intrinsics, generated metadata, or a mix?
+- [ ] Should parameter names be normative API surface, meaning renames require compatibility/release discipline?
+- [ ] How should optional/default/rest parameters be represented if PBS supports or later adds them?
+- [ ] Should completion snippets include placeholders named from canonical parameters, or should names appear only in detail/signature help?
+
+## Options
+
+### Option A - Canonical parameter names live in the compiler semantic callable model
+
+- **Approach:** every callable symbol resolved by the compiler has an explicit parameter list with stable names, types, order, and origin. LSP completion, signature help, and hover all read from that same semantic shape.
+- **Pro:** one authoritative contract; works for user code, stdlib, builtins, and host-backed APIs if they are projected into the semantic model.
+- **Con:** requires stdlib/builtin surfaces to provide or be lowered into real parameter metadata instead of ad hoc editor-only labels.
+- **Maintainability:** strong. It makes `arg0` a compiler/model quality issue rather than a UI formatting problem.
+
+### Option B - Parameter names live in stdlib/API metadata consumed by the LSP adapter
+
+- **Approach:** stdlib and host-backed APIs carry external metadata for names and docs; LSP consumes that metadata when building completion items and signatures.
+- **Pro:** fast path for the worst current pain if the main offender is stdlib; avoids forcing every host descriptor into a richer compiler model immediately.
+- **Con:** risks splitting callable truth between compiler semantics and editor metadata. User-authored and stdlib callables may drift.
+- **Maintainability:** medium. Acceptable as a migration step, but weak as the final owner if the compiler and editor can disagree.
+
+### Option C - Derive display names in the editor/LSP when semantic names are missing
+
+- **Approach:** keep existing compiler output and have LSP/VS Code replace `arg0`, `arg1` with guessed names from docs, method names, types, or curated maps.
+- **Pro:** minimal compiler change; can improve a handful of visible APIs quickly.
+- **Con:** guessing parameter names is fragile and can mislead users. It treats presentation as truth.
+- **Maintainability:** weak. This should be reserved only as a temporary compatibility shim with clear diagnostics.
+
+### Option D - Bind parameter names to the documentation model from `DSC-0036`
+
+- **Approach:** parameter names and descriptions are authored together in the symbol documentation surface, then completion/signature help extract display names from docs.
+- **Pro:** ties names and descriptions together; can produce rich signature help.
+- **Con:** parameter identity becomes dependent on documentation authoring. A callable without docs could still degrade to `arg0`.
+- **Maintainability:** medium-to-weak as a canonical source. Good for prose descriptions, poor for structural identity.
+
+### Option E - Allow `arg0`/`arg1` internally but ban them from user-facing LSP output
+
+- **Approach:** define a conformance rule: generated fallback parameter names may exist internally, but completion/signature/hover must either show canonical names or omit placeholder names instead of exposing `argN`.
+- **Pro:** creates a clear UX quality gate and prevents the worst editor output.
+- **Con:** does not by itself solve where real names come from.
+- **Maintainability:** strong as a guardrail, incomplete as the main design.
+
+## Tradeoffs
+
+The central tradeoff is speed versus ownership.
+
+An editor-only fix can make the UI look better quickly, but it creates a second source of truth for API shape. That is exactly the kind of split that becomes expensive once hover, snippets, signature help, diagnostics, docs, and future refactors all need the same callable metadata.
+
+Putting names into the compiler semantic model is heavier, but it matches the long-term direction implied by compiler-backed editor assistance. The editor should not need to know why a callable is user-authored, stdlib, host-backed, or intrinsic in order to display a usable signature.
+
+There is still room for a staged path:
+
+- immediately block or reduce `argN` in user-facing output;
+- add canonical names for stdlib APIs through the nearest existing stdlib descriptor;
+- converge those descriptors into the compiler's callable semantic model;
+- let documentation add descriptions, examples, and prose later without owning structural names.
+
+`DSC-0036` should remain complementary. Documentation can describe what a parameter means, but the parameter name itself should be structural metadata.
+
+## Recommendation
+
+Use **Option A** as the target design and **Option E** as a non-negotiable editor quality guardrail.
+
+Recommended direction:
+
+1. Treat canonical parameter names as part of the resolved callable symbol model.
+2. Require stdlib, builtin, host-backed, and user-authored callables to expose the same parameter shape to editor assistance.
+3. Define `arg0`, `arg1`, etc. as internal fallback names only; they should not appear in completion labels, snippets, signature help, or hover unless explicitly authored as real API names.
+4. Let the documentation model from `DSC-0036` attach parameter descriptions later, but not replace structural parameter identity.
+
+If implementation needs to be staged, the first slice should target the stdlib because that is where the current UX pain is most visible.
+
+## Discussion
+
+This agenda should avoid reducing the problem to "prettier snippets".
+
+The real question is ownership:
+
+- who owns a callable's parameter names?
+- does the compiler know them?
+- does the editor receive them as structured data?
+- can tests assert that stdlib APIs do not leak fallback names?
+
+The minimum acceptable outcome is that a user can discover a stdlib call from autocomplete and understand what each argument is supposed to represent without leaving the call site.
+
+Potential acceptance examples for a later decision/plan:
+
+- completion insert text uses named placeholders where snippets are enabled;
+- signature help displays stable parameter names and types;
+- hover can show a callable signature using the same names;
+- conformance tests fail if public stdlib callables expose `argN` placeholders;
+- fallback behavior is explicit when a callable genuinely lacks parameter names.
+
+## Resolution
+
+Ainda em aberto.
+
+## Next Step
+
+Discutir se a equipe aceita `compiler/pbs` como owner dos nomes canonicos de parametros e se `argN` deve ser banido de qualquer surface LSP user-facing.