prometeu-vsf

2026-03-31 08:00:10 +01:00 · 2026-03-31 08:00:10 +01:00 · 0f056a1ea1
commit 0f056a1ea1
parent d9ba5e3cb4
8 changed files with 1052 additions and 1 deletions
--- a/discussion/index.ndjson
+++ b/discussion/index.ndjson
@ -1,4 +1,4 @@
-{"type":"meta","next_id":{"DSC":12,"AGD":12,"DEC":9,"PLN":15,"LSN":27,"CLSN":1}}
+{"type":"meta","next_id":{"DSC":13,"AGD":13,"DEC":10,"PLN":19,"LSN":27,"CLSN":1}}
 {"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
 {"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
@ -10,3 +10,4 @@
 {"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
 {"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
+{"type":"discussion","id":"DSC-0012","status":"open","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[{"id":"AGD-0012","file":"AGD-0012-studio-editor-document-vfs-boundary.md","status":"in_progress","created_at":"2026-03-31","updated_at":"2026-03-31"}],"decisions":[{"id":"DEC-0009","file":"DEC-0009-studio-prometeu-vfs-project-document-boundary.md","status":"in_progress","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0012"}],"plans":[{"id":"PLN-0015","file":"PLN-0015-propagate-dec-0009-into-studio-specs.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]},{"id":"PLN-0016","file":"PLN-0016-build-prometeu-vfs-filesystem-backed-core.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]},{"id":"PLN-0017","file":"PLN-0017-add-studio-project-session-ownership-for-prometeu-vfs.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]},{"id":"PLN-0018","file":"PLN-0018-migrate-code-editor-to-prometeu-vfs.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]}],"lessons":[]}
--- a/discussion/workflow/agendas/AGD-0012-studio-editor-document-vfs-boundary.md
+++ b/discussion/workflow/agendas/AGD-0012-studio-editor-document-vfs-boundary.md
@ -0,0 +1,200 @@
+---
+id: AGD-0012
+ticket: studio-editor-document-vfs-boundary
+title: Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio
+status: in_progress
+created: 2026-03-31
+resolved: 2026-03-31
+decision: DEC-0009
+tags:
+  - studio
+  - editor
+  - workspace
+  - vfs
+  - filesystem
+  - boundary
+---
+
+## Pain
+
+O `Code Editor` do Studio ja fechou a primeira wave como shell editorial read-only, mas a composicao concreta ainda instancia diretamente os servicos que leem arvore e conteudo do filesystem.
+
+Isso deixa uma ambiguidade arquitetural:
+
+- o shell do workspace deveria coordenar layout, sessao e sincronizacao;
+- mas hoje ele ainda conhece diretamente os adaptadores de leitura estrutural e de leitura de documento;
+- e nao esta explicito se a proxima evolucao deve continuar como `filesystem services` locais ou subir para um boundary mais claro de `document/tree VFS`.
+
+Sem fechar esse ponto agora, o editor corre risco de crescer com responsabilidades misturadas:
+
+- tree snapshot;
+- open-file buffers;
+- refresh/watchers;
+- overlays de documento em memoria;
+- e futuras fontes nao estritamente filesystem-backed.
+
+## Context
+
+Domain owner: `studio`
+Owner surface: `docs/specs/studio`
+
+Superficies relevantes:
+
+- `docs/specs/studio/5. Code Editor Workspace Specification.md` ja exige separacao entre structural snapshot e opened-file content, mantendo o filesystem como source of truth nesta wave;
+- `discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md` consolida que o Studio possui o shell editorial, nao um IDE semantico completo;
+- `EditorWorkspace` ainda instancia diretamente `EditorProjectSnapshotService` e `EditorFileBufferLoader`;
+- `EditorProjectSnapshotService` e `EditorFileBufferLoader` usam `Files.*` diretamente como backend concreto.
+- o workspace Gradle ja reserva `prometeu-lsp:prometeu-lsp-api` e `prometeu-lsp:prometeu-lsp-v1`, mas hoje esses modulos ainda nao tem codigo;
+- os roadmaps de LSP tratam `prometeu-lsp` como superficie futura para handlers/endpoints semanticos e itens como `didChangeWatchedFiles`.
+
+Clarificacao importante para esta discussion:
+
+- quando falamos em `VFS` aqui, nao estamos propondo um filesystem universal do produto;
+- o packer continua com ownership proprio de runtime/workspace/asset semantics;
+- as entidades nao se veem por padrao;
+- o recorte aqui e um boundary do `Code Editor` para `tree`, `view` e `open files`, inclusive conteudo em memoria.
+
+## Open Questions
+
+- [x] Nesta etapa, o boundary transporta apenas o que o `workspace editor` ja tem hoje; nada novo entra no escopo funcional.
+- [x] O `prometeu-vfs` nao deve expor apenas RPC; ele tambem deve receber e emitir um subconjunto selecionado de eventos como parte explicita da propria API.
+- [x] O `Project Navigator` consome uma entidade que representa a arvore inteira, sem acessar filesystem diretamente, mas deve poder requerer atualizacoes mais pontuais do que um reload completo.
+- [x] A `tree` do `prometeu-vfs` deve ser estrutural e de dados apenas, nao uma tree visual nem um view model de UI.
+- [x] O `open files` passa a abrir a partir do `prometeu-vfs`, inclusive quando o backend concreto continuar sendo o disco.
+- [x] Regras de arquivos, plugins e de suporte ou nao suporte pertencem ao `prometeu-vfs`; o Studio apenas apresenta o erro/estado ao usuario.
+- [x] Nesta primeira wave, eventos publicos ficam de fora; tudo permanece interno ate existir necessidade clara de exposicao contratual.
+- [x] `Watchers` ficam fora desta primeira decisao; `refresh` permanece somente manual.
+- [x] O boundary nasce como primitive util para o dominio `studio`; hoje o editor consome, e futuramente o `prometeu-lsp` podera consumir tambem.
+- [x] O `document/tree manager` vive na sessao de projeto do Studio, e o snapshot do `prometeu-vfs` cobre apenas conteudo do projeto.
+- [x] Criar um novo `prometeu-vfs` e manter `prometeu-lsp` reservado para a camada futura de protocolo/handlers parece melhor do que renomear o namespace atual.
+
+## Options
+
+### Option A - Manter servicos filesystem locais no editor
+- **Approach:** Continuar com `EditorProjectSnapshotService` e `EditorFileBufferLoader` como helpers concretos do workspace, extraindo apenas pequenos refinamentos locais.
+- **Pro:** Menor custo imediato e menos abstracao.
+- **Con:** O shell continua acoplado ao backend concreto e a evolucao para overlays, watchers ou backends alternativos fica difusa.
+- **Maintainability:** Media para baixa. Funciona enquanto o editor permanecer estritamente read-only e filesystem-first.
+
+### Option B - Extrair portas pequenas separadas, sem chamar isso de VFS
+- **Approach:** Definir interfaces independentes para `project tree snapshot` e `document content loading`, ambas filesystem-backed por baixo.
+- **Pro:** Resolve o acoplamento principal com mudanca pequena e preserva clareza.
+- **Con:** Pode virar um VFS fatiado informalmente, sem um modelo claro quando overlays de memoria entrarem.
+- **Maintainability:** Media. Boa transicao curta, mas com risco de proliferar portas parciais.
+
+### Option C - Definir um VFS documental estreito para o Code Editor
+- **Approach:** Criar um boundary explicito do editor que seja owner de arvore virtual do projeto e documentos abertos/em memoria, com backend inicial filesystem-backed e overlays de sessao como extensao prevista.
+- **Pro:** Fecha a fronteira certa: o workspace consome um modelo de documentos/arvore e deixa de conhecer `Files.*` ou loaders concretos.
+- **Con:** Exige nomear melhor contratos, identidade de documento, estrategia de refresh e como snapshot estrutural convive com buffers abertos.
+- **Maintainability:** Forte. Preserva a intencao de shell editorial e abre caminho limpo para write wave, overlays e fontes alternativas sem acoplar isso ao packer.
+
+### Option D - Criar um novo modulo `prometeu-vfs` com lifecycle de projeto no Studio
+- **Approach:** Criar um modulo-base de VFS/document manager (`prometeu-vfs`) que o Studio instancia por projeto, fora do foco do workspace, com watchers/refresh/overlays encapsulados ali; o editor vira consumidor desse servico, enquanto `prometeu-lsp` permanece reservado para a futura camada de protocolo/handlers. O modulo deve expor uma API mista de chamadas RPC e um subconjunto disciplinado de eventos publicos.
+- **Pro:** Alinha melhor a ownership real do estado documental, porque ele continua vivo mesmo sem o `Code Editor` estar ativo; tambem prepara o caminho para um futuro `prometeu-lsp` consumir o mesmo substrate em vez de reinventar sincronizacao.
+- **Con:** Obriga a decidir desde ja a topologia entre `studio`, `vfs` e um futuro `lsp`, alem de exigir definicao disciplinada da fronteira entre eventos publicos e eventos internos para nao vazar detalhes internos como API acidental.
+- **Maintainability:** Forte, desde que o scope continue estrito a documentos/arvore de projeto e nao derive para um filesystem universal do produto.
+
+### Option E - Criar um VFS generico de Studio desde ja
+- **Approach:** Elevar o boundary para uma primitive ampla do Studio, candidata a servir editor, assets, debugger e outras workspaces.
+- **Pro:** Promete reutilizacao ampla.
+- **Con:** Generaliza antes de existir evidencia suficiente de consumo compartilhado e arrisca misturar dominios que hoje precisam continuar separados.
+- **Maintainability:** Baixa neste momento. A abstracao tende a nascer grande demais e cedo demais.
+
+## Discussion
+
+O ponto principal nao e substituir o disco por uma simulacao abstrata.
+O ponto principal e impedir que o `Code Editor` continue dono acidental de concerns que deveriam morar em um boundary proprio de documentos e arvore.
+
+O estado normativo atual ja separa corretamente:
+
+1. snapshot estrutural do projeto para navegacao;
+2. buffers de documentos abertos para sessao;
+3. filesystem como source of truth na primeira wave.
+
+O que falta e transformar essa separacao conceitual em uma fronteira arquitetural explicita.
+
+Se o boundary nascer estreito, ele pode continuar filesystem-backed sem conflito:
+
+- o navigator pede uma arvore/snapshot;
+- o open-files pede documentos;
+- overlays de memoria podem passar a viver no mesmo boundary quando write/draft semantics entrarem;
+- e o workspace continua coordenando UX, nao I/O.
+
+O novo ponto trazido nesta discussion refinou ainda mais o boundary correto:
+
+- o estado documental do projeto pode precisar continuar vivo mesmo quando o `Code Editor` nao estiver no foco;
+- refresh manual e reconciliacao de documento sao concerns de runtime do boundary, nao do layout do workspace;
+- portanto, o owner mais coerente deixa de ser o `EditorWorkspace` e passa a ser um servico de projeto do Studio que o editor consome.
+
+Outro fechamento importante e que esse servico nao deve ser pensado como biblioteca puramente sincrona de funcoes:
+
+- o `prometeu-vfs` deve oferecer chamadas de API para comandos/queries diretas;
+- o modulo pode manter eventos internos como parte do seu runtime;
+- mas nesta primeira wave nenhum evento precisa sair como API publica;
+- isso preserva flexibilidade interna enquanto o boundary estrutural e documental ainda esta sendo estabilizado.
+
+Nesse modelo, a pilha correta tende a ser:
+
+1. `Studio project session` instancia o manager documental;
+2. `prometeu-vfs` ou equivalente implementa tree/document/watchers/overlays;
+3. `EditorWorkspace` observa e consome esse estado;
+4. um futuro `prometeu-lsp` pode consumir o mesmo substrate acima dele, e nao o contrario.
+
+Um fechamento importante desta agenda e que a palavra `tree` em `prometeu-vfs` significa estrutura de dados do projeto, nao componente visual:
+
+- o `prometeu-vfs` deve publicar nos estruturais, paths, parent/children, tipos de entrada, identidades e metadados documentais necessarios;
+- o `prometeu-vfs` nao deve carregar concerns de UI como expansao visual, selecao, foco, scroll, reveal, icones ou chrome de navigator;
+- o `Project Navigator` do Studio continua owner do tree visual e de qualquer view model derivado para apresentacao;
+- tags ou metadados produzidos pelo `prometeu-vfs` podem informar a UI, mas a decisao de como renderizar continua no Studio.
+
+O mesmo vale para o modelo de comunicacao:
+
+- RPC cobre comandos/queries como abrir documento, pedir snapshot, reconciliar, listar documentos ou obter conteudo atual;
+- eventos internos podem cobrir transicoes observaveis do runtime como snapshot atualizado, documento mutado, divergencia detectada ou refresh concluido;
+- esses eventos permanecem encapsulados nesta wave;
+- a API oficial inicial fica concentrada em RPC/comandos/queries, sem publication obrigatoria para fora do modulo.
+
+O fato de `prometeu-lsp` ainda estar vazio torna qualquer mudanca barata em codigo, mas a decisao mais limpa continua sendo criar `prometeu-vfs` como modulo novo:
+
+- o nome `prometeu-lsp` ja esta referenciado nos roadmaps como superficie futura de protocolo/handlers;
+- renomear agora e barato em codigo, mas continua sendo ruidoso editorialmente;
+- criar `prometeu-vfs` preserva a hierarquia conceitual certa: `vfs` como substrate, `lsp` como consumidor futuro.
+
+Isso e diferente de um `VFS universal`:
+
+- nao absorve regras do packer;
+- nao redefine ownership de assets;
+- nao cria dependencia cruzada entre domínios;
+- e nao exige que todas as workspaces do Studio passem a usar o mesmo modelo desde o dia 1.
+
+O nome `VFS` so vale a pena se o contrato realmente virar owner de:
+
+- identificacao de documentos,
+- leitura estrutural,
+- conteudo resolvido para open files,
+- e futura sobreposicao de estado em memoria.
+
+Se a equipe quiser evitar peso terminologico agora, `Option B` e um passo valido.
+Mas a direcao arquitetural mais coerente parece ser nomear logo o boundary correto e mantê-lo deliberadamente estreito.
+
+## Resolution
+
+Recommended direction: seguir com **Option D**, com o escopo estrito de `Option C` e o corte funcional limitado ao que o `EditorWorkspace` ja faz hoje.
+
+Fechamento recomendado para a proxima `decision`:
+
+1. o `Code Editor` deve consumir um boundary proprio de `tree + document content`, em vez de instanciar loaders filesystem concretos;
+2. nesta etapa, o boundary deve transportar apenas as capacidades que o `EditorWorkspace` ja possui hoje, sem adicionar novas features editoriais;
+3. esse boundary deve viver como servico de sessao de projeto do Studio, nao como detalhe de lifecycle do `EditorWorkspace`;
+4. esse boundary comeca como `filesystem-backed`, e o Studio passa a tocar o disco atraves do `prometeu-vfs`;
+5. `refresh` permanece somente manual, e `watchers` ficam explicitamente fora desta primeira decisao;
+6. regras de arquivos, plugins e suporte/não-suporte pertencem ao `prometeu-vfs`; o Studio apenas apresenta o erro ou estado correspondente;
+7. o nome/namespace recomendado e criar um novo modulo-base `prometeu-vfs`, deixando `prometeu-lsp` intacto como consumidor superior futuro quando a camada de protocolo existir;
+8. a API oficial inicial do `prometeu-vfs` fica concentrada em RPC/comandos/queries; eventos podem existir internamente, mas nao precisam ser publicados nesta wave;
+9. a `tree` do `prometeu-vfs` deve ser estrutural e de dados apenas; tree visual, estado de apresentacao e navigator chrome continuam no Studio;
+10. o `Project Navigator` consome uma entidade-arvore do projeto inteiro, sem ver filesystem diretamente, mas pode solicitar atualizacoes pontuais;
+11. o boundary nasce como primitive util para `studio`; hoje o editor consome, e futuramente o `prometeu-lsp` pode consumir tambem;
+12. o snapshot do `prometeu-vfs` cobre apenas conteudo do projeto;
+13. packer, assets e demais dominios continuam com ownership proprio e fora desse boundary, salvo decisao posterior explicita.
+
+Next step suggestion: converter esta agenda em uma `decision` que feche o nome do modulo-base, seu lifecycle de sessao de projeto no Studio, o contrato minimo inicial de `tree/document/RPC`, e a linha exata entre `workspace shell`, `prometeu-vfs` e um futuro `prometeu-lsp`.
--- a/discussion/workflow/decisions/DEC-0009-studio-prometeu-vfs-project-document-boundary.md
+++ b/discussion/workflow/decisions/DEC-0009-studio-prometeu-vfs-project-document-boundary.md
@ -0,0 +1,178 @@
+---
+id: DEC-0009
+ticket: studio-editor-document-vfs-boundary
+title: Estabelecer `prometeu-vfs` como boundary documental de projeto para o Studio
+status: in_progress
+created: 2026-03-31
+accepted: 2026-03-31
+agenda: AGD-0012
+plans:
+  - PLN-0015
+  - PLN-0016
+  - PLN-0017
+  - PLN-0018
+tags:
+  - studio
+  - editor
+  - workspace
+  - vfs
+  - filesystem
+  - boundary
+---
+
+## Context
+
+O `Code Editor` do Studio ja fechou sua primeira wave como shell editorial read-only, mas a implementacao concreta ainda instancia diretamente servicos filesystem-backed para:
+
+- montar a arvore estrutural do projeto;
+- abrir arquivos;
+- carregar conteudo de documentos;
+- e aplicar regras de suporte ou nao suporte a arquivos.
+
+Isso mantem concerns de I/O e sincronizacao acoplados ao `EditorWorkspace`, quando o owner correto desses concerns deve ser um boundary documental de projeto.
+
+Tambem ficou fechado na agenda que:
+
+- esta etapa nao introduz novas capacidades editoriais alem das que o `EditorWorkspace` ja possui hoje;
+- o estado documental precisa continuar vivo mesmo quando o `Code Editor` nao esta em foco;
+- o `Project Navigator` nao deve ver filesystem diretamente;
+- `prometeu-lsp` deve continuar reservado para a futura camada de protocolo/handlers;
+- e packer/assets permanecem fora deste boundary.
+
+## Decision
+
+1. O repositório SHALL introduzir um novo modulo-base chamado `prometeu-vfs`.
+2. `prometeu-vfs` SHALL ser o boundary documental de projeto consumido pelo Studio para `tree`, `open files` e `document content`.
+3. O Studio MUST passar a tocar o disco atraves de `prometeu-vfs` para o escopo coberto por este boundary.
+4. O escopo desta primeira wave MUST transportar apenas as capacidades hoje existentes no `EditorWorkspace`; nenhuma nova feature editorial SHALL ser adicionada nesta etapa.
+5. `prometeu-vfs` SHALL viver no lifecycle de sessao de projeto do Studio, nao no lifecycle de foco do `EditorWorkspace`.
+6. O snapshot de `prometeu-vfs` MUST cobrir apenas conteudo do projeto.
+7. A `tree` exposta por `prometeu-vfs` MUST ser estrutural e de dados apenas; ela MUST NOT carregar concerns visuais ou view-model concerns de UI.
+8. O `Project Navigator` do Studio SHALL consumir uma entidade que representa a arvore inteira do projeto e MAY solicitar atualizacoes mais pontuais do que um reload completo.
+9. A abertura de arquivos no Studio MUST passar por `prometeu-vfs`, inclusive quando o backend concreto continuar sendo filesystem.
+10. Regras de arquivos, plugins e suporte ou nao suporte MUST morar em `prometeu-vfs`; o Studio SHALL apenas apresentar o erro ou estado resultante.
+11. A API oficial inicial de `prometeu-vfs` SHALL ficar concentrada em RPC/comandos/queries.
+12. `prometeu-vfs` MAY manter eventos internos como parte de seu runtime, mas esses eventos MUST NOT ser publicados como API oficial nesta primeira wave.
+13. `refresh` SHALL permanecer somente manual nesta primeira wave.
+14. `watchers` MUST permanecer fora de escopo desta decisao e MUST NOT ser introduzidos por inferencia durante planning ou implementation.
+15. `prometeu-vfs` SHALL nascer como primitive util do dominio `studio`: hoje para o editor, e futuramente podendo servir `prometeu-lsp`.
+16. `prometeu-lsp` MUST permanecer como namespace/modulo separado, reservado para a futura camada de protocolo/handlers acima de `prometeu-vfs`.
+17. Packer, assets e demais dominios MUST manter ownership proprio e MUST NOT ser absorvidos por `prometeu-vfs` sem decisao posterior explicita.
+
+## Rationale
+
+Esta decisao fecha a fronteira correta entre shell editorial e runtime documental.
+
+O Studio precisa continuar owner de:
+
+- layout;
+- controls;
+- navigator visual;
+- estado de apresentacao;
+- e UX de erro.
+
+`prometeu-vfs` precisa passar a ser owner de:
+
+- leitura estrutural do projeto;
+- resolucao de documentos;
+- abertura de arquivos;
+- regras de suporte;
+- refresh manual;
+- e sincronizacao documental de sessao.
+
+Isso remove do `EditorWorkspace` um conjunto de concerns que nao pertencem ao shell.
+
+Criar `prometeu-vfs` como modulo novo e superior a renomear `prometeu-lsp` porque:
+
+- preserva a hierarquia conceitual correta;
+- evita ruido editorial nos roadmaps ja existentes;
+- e mantem `lsp` como consumidor futuro do substrate documental, nao como nome prematuro do substrate em si.
+
+Manter eventos publicos fora da primeira wave tambem e deliberado:
+
+- o modulo continua livre para estabilizar sua maquina interna;
+- o contrato externo inicial permanece menor e mais controlado;
+- e nenhum consumidor passa a depender de detalhes de runtime antes da hora.
+
+## Technical Specification
+
+### 1. Module Boundary
+
+- O workspace Gradle MUST incluir um novo modulo `prometeu-vfs`.
+- Esse modulo SHALL ser a superficie de integracao documental do Studio para o escopo coberto por esta decisao.
+- `prometeu-lsp` SHALL permanecer separado e sem reaproveitamento nominal do namespace.
+
+### 2. Project Session Ownership
+
+- A instancia principal de `prometeu-vfs` MUST pertencer a uma sessao de projeto do Studio.
+- O `EditorWorkspace` MUST consumir essa instancia, e MUST NOT ser o owner do lifecycle documental.
+- Troca de foco entre workspaces MUST NOT destruir o estado documental da sessao.
+
+### 3. Filesystem Access
+
+- Para o escopo coberto por esta decisao, o Studio MUST acessar o disco atraves de `prometeu-vfs`.
+- O backend inicial de `prometeu-vfs` SHALL ser filesystem-backed.
+- Essa decisao MUST NOT ser interpretada como criacao de um filesystem universal para todos os dominios do produto.
+
+### 4. Structural Tree Contract
+
+- `prometeu-vfs` MUST expor uma representacao estrutural do projeto inteiro.
+- Essa representacao MUST incluir apenas dados e metadados estruturais/documentais necessarios ao consumo.
+- Essa representacao MUST NOT conter:
+  - estado de expansao visual;
+  - selecao;
+  - foco;
+  - scroll;
+  - reveal;
+  - icones;
+  - ou qualquer chrome de navigator.
+- O Studio MAY derivar view models visuais a partir dessa estrutura.
+- O `Project Navigator` MAY solicitar atualizacoes pontuais, sem obrigar reload completo da arvore a cada interacao.
+
+### 5. Document and Open-File Contract
+
+- Abrir um arquivo no Studio MUST significar resolver esse arquivo atraves de `prometeu-vfs`.
+- O conteudo de documento devolvido por `prometeu-vfs` SHALL representar apenas o estado documental do projeto dentro da sessao atual.
+- Esta decisao MUST NOT ser interpretada como permissao para introduzir novas features de edicao, save, dirty tracking, merge ou write semantics.
+
+### 6. Support Rules and Errors
+
+- A determinacao de suporte ou nao suporte de um arquivo MUST ocorrer em `prometeu-vfs`.
+- Regras relacionadas a plugins e resolucao de handlers de arquivo MUST morar em `prometeu-vfs`.
+- O Studio SHALL apenas reagir ao resultado, exibindo erro ou estado apropriado com os mecanismos de UI existentes ou futuros.
+
+### 7. Communication Model
+
+- A API oficial inicial de `prometeu-vfs` MUST ser RPC-oriented.
+- O modulo MAY manter eventos internos para coordenacao de runtime.
+- Esses eventos internos MUST NOT ser expostos como API publica nesta primeira wave.
+- Nenhum plano ou implementacao posterior MAY promover eventos internos a API publica por inferencia; isso exigira decisao posterior explicita.
+
+### 8. Refresh and Watchers
+
+- `refresh` SHALL permanecer manual.
+- `watchers` MUST permanecer fora de escopo.
+- Nenhum plano posterior MAY introduzir watching automatico por aproximacao arquitetural.
+
+### 9. Domain Boundaries
+
+- O escopo de `prometeu-vfs` SHALL permanecer restrito ao boundary documental de projeto do dominio `studio`.
+- `prometeu-vfs` MUST NOT absorver responsabilidades do packer.
+- `prometeu-vfs` MUST NOT redefinir ownership de assets.
+- Um futuro `prometeu-lsp` MAY consumir `prometeu-vfs`, mas `prometeu-vfs` MUST NOT depender de uma camada LSP para justificar seu contrato.
+
+## Constraints
+
+- Esta decisao e normativamente travada ao escopo hoje existente no `EditorWorkspace`.
+- Nenhuma feature nova de editor pode ser adicionada por conveniencia durante a migracao para `prometeu-vfs`.
+- O contrato inicial deve permanecer pequeno o suficiente para planejamento e implementacao direta.
+- Qualquer tentativa de:
+  - expor eventos publicos;
+  - introduzir watchers;
+  - ampliar o snapshot para fora do conteudo do projeto;
+  - ou absorver outros dominios;
+  exigira nova decisao explicita.
+
+## Revision Log
+
+- 2026-03-31: Initial draft from AGD-0012.
--- a/discussion/workflow/plans/PLN-0015-propagate-dec-0009-into-studio-specs.md
+++ b/discussion/workflow/plans/PLN-0015-propagate-dec-0009-into-studio-specs.md
@ -0,0 +1,156 @@
+---
+id: PLN-0015
+ticket: studio-editor-document-vfs-boundary
+title: Propagate DEC-0009 into Studio shell, editor, and VFS specs
+status: review
+created: 2026-03-31
+completed:
+tags:
+  - studio
+  - vfs
+  - specs
+  - editor
+  - shell
+---
+
+## Briefing
+
+Translate DEC-0009 into the normative Studio specification set before code migration starts, so the new `prometeu-vfs` boundary is explicit in shell, editor, and module-level documentation.
+
+## Objective
+
+Make the accepted `prometeu-vfs` project-document boundary normative in Studio specs without adding scope beyond the current read-only editor wave.
+
+## Background
+
+DEC-0009 locks the following architectural choices:
+
+- Studio accesses project-document filesystem state through `prometeu-vfs`.
+- `prometeu-vfs` is project-session owned rather than editor-focus owned.
+- `prometeu-vfs` exposes structural project data, not visual tree state.
+- the first migration wave carries only current `EditorWorkspace` capabilities;
+- manual refresh remains in scope, while watchers and public event APIs remain out of scope.
+
+The current spec set documents shell and editor behavior, but it does not yet define the `prometeu-vfs` boundary explicitly.
+
+## Dependencies
+
+- DEC-0009 accepted and normatively locked
+
+## Scope
+
+### Included
+
+- add or update Studio normative text for the `prometeu-vfs` boundary
+- propagate project-session ownership rules into the shell spec
+- propagate structural tree, support-rule ownership, and `prometeu-vfs` document access rules into the Code Editor spec
+- update the Studio specs index if a new Studio spec is introduced
+
+### Excluded
+
+- implementation code
+- public event API exposure
+- watcher-based refresh
+- new editor capabilities beyond the current read-only wave
+
+## Non-Goals
+
+- redesign the shell
+- define a public event catalog for `prometeu-vfs`
+- generalize `prometeu-vfs` into a product-wide filesystem abstraction
+
+## Execution Method
+
+### Step 1 - Introduce a Normative `prometeu-vfs` Boundary Spec
+
+**What:**
+Create a dedicated Studio spec for the project-document boundary so DEC-0009 does not have to be split awkwardly across unrelated shell and editor documents.
+
+**How:**
+Add a new Studio spec that defines:
+
+- `prometeu-vfs` module role
+- project-session ownership
+- filesystem-backed first-wave contract
+- structural tree contract
+- RPC-first public API baseline
+- manual refresh rule
+- non-goals for public events and watchers
+
+**File(s):**
+- `docs/specs/studio/6. Project Document VFS Specification.md`
+
+### Step 2 - Propagate Session Ownership into the Shell Spec
+
+**What:**
+Update shell-level architecture rules so the shell explicitly owns project-session services that survive workspace focus changes.
+
+**How:**
+Amend the shell spec to state that workspace-local composition may consume project-session-owned services such as `prometeu-vfs`, while shell/workspace responsibility boundaries remain intact.
+
+**File(s):**
+- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md`
+
+### Step 3 - Propagate Editor-Local Boundary Rules
+
+**What:**
+Update the Code Editor spec so all project-tree and document access rules point to `prometeu-vfs` instead of direct filesystem readers inside the workspace.
+
+**How:**
+Amend the editor spec to state that:
+
+- the navigator consumes a structural tree entity provided by `prometeu-vfs`
+- the editor opens files through `prometeu-vfs`
+- support and unsupported-file rules belong to `prometeu-vfs`
+- visual tree state remains in Studio UI
+- refresh remains manual
+
+**File(s):**
+- `docs/specs/studio/5. Code Editor Workspace Specification.md`
+
+### Step 4 - Update the Studio Spec Index
+
+**What:**
+Keep the Studio spec corpus discoverable after adding the new boundary spec.
+
+**How:**
+Update the index/read-order document to include the new `prometeu-vfs` spec and place it in a reading order that preserves shell -> shared boundary -> workspace detail.
+
+**File(s):**
+- `docs/specs/studio/README.md`
+
+## Test Requirements
+
+### Unit Tests
+
+- none
+
+### Integration Tests
+
+- none
+
+### Manual Verification
+
+- verify the new spec set contains no contradiction between shell ownership, `prometeu-vfs` ownership, and Code Editor ownership
+- verify the new spec wording does not introduce watchers, public events, write semantics, or non-project content by implication
+
+## Acceptance Criteria
+
+- [ ] DEC-0009 is fully represented in the Studio spec corpus without reopening the agenda
+- [ ] shell, `prometeu-vfs`, and editor responsibilities are separated unambiguously
+- [ ] the spec set states that `prometeu-vfs` provides structural data only, not visual tree state
+- [ ] the spec set states that the first wave remains limited to current editor capabilities
+- [ ] the spec set states that refresh is manual and watchers remain out of scope
+
+## Affected Artifacts
+
+- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md`
+- `docs/specs/studio/5. Code Editor Workspace Specification.md`
+- `docs/specs/studio/6. Project Document VFS Specification.md`
+- `docs/specs/studio/README.md`
+
+## Risks
+
+- splitting the rules across too many documents could make the boundary harder to follow
+- forcing all rules into the editor spec could bury project-session ownership in a workspace-local document
+- imprecise wording here would leak directly into implementation scope
--- a/discussion/workflow/plans/PLN-0016-build-prometeu-vfs-filesystem-backed-core.md
+++ b/discussion/workflow/plans/PLN-0016-build-prometeu-vfs-filesystem-backed-core.md
@ -0,0 +1,185 @@
+---
+id: PLN-0016
+ticket: studio-editor-document-vfs-boundary
+title: Build the filesystem-backed `prometeu-vfs` core for project tree and documents
+status: review
+created: 2026-03-31
+completed:
+tags:
+  - studio
+  - vfs
+  - filesystem
+  - rpc
+  - module
+---
+
+## Briefing
+
+Create the first `prometeu-vfs` module implementation as a filesystem-backed project-document core that carries only the current Code Editor capabilities.
+
+## Objective
+
+Introduce a testable `prometeu-vfs` module that owns structural project snapshots, document loading, support classification, and manual refresh operations for project content.
+
+## Background
+
+The current editor owns three separate local responsibilities:
+
+- project tree snapshot building
+- file buffer loading and unsupported-file classification
+- session-local opened-file coordination
+
+DEC-0009 moves the first two responsibilities into `prometeu-vfs` while preserving the current functional surface and deferring watchers, public events, and write semantics.
+
+## Dependencies
+
+- DEC-0009 accepted and normatively locked
+- PLN-0015 accepted or otherwise completed enough to make the target spec language stable
+
+## Scope
+
+### Included
+
+- add the new Gradle module wiring for `prometeu-vfs`
+- define the initial RPC-oriented public API for project tree and document access
+- implement a filesystem-backed first version
+- move file support classification into `prometeu-vfs`
+- add unit tests that cover the new module behavior
+
+### Excluded
+
+- project-session ownership in Studio bootstrap
+- workspace UI changes beyond dependency wiring needed for compilation
+- public event API exposure
+- watchers
+- save, dirty tracking, writes, merge handling, or conflict handling
+- non-project content snapshots
+
+## Non-Goals
+
+- create a general VFS for packer, assets, or debugger
+- redesign the editor session model
+- introduce a second backend beyond filesystem
+
+## Execution Method
+
+### Step 1 - Add `prometeu-vfs` to the Gradle Workspace
+
+**What:**
+Make the new module part of the build and available to Studio code.
+
+**How:**
+Update the root Gradle settings and module dependencies so the Studio can compile against `prometeu-vfs`.
+
+**File(s):**
+- `settings.gradle.kts`
+- `prometeu-studio/build.gradle.kts`
+- new `prometeu-vfs/**`
+
+### Step 2 - Define the Initial RPC-Oriented Contract
+
+**What:**
+Create the public API surface for structural tree retrieval, point refresh requests, document resolution, and support classification.
+
+**How:**
+Define models and service interfaces in `prometeu-vfs` for:
+
+- project-scoped tree snapshots
+- structural tree nodes
+- document open/load results
+- unsupported-file or unsupported-handler outcomes
+- manual refresh commands, including targeted refresh requests for narrower scope than full reload
+
+The API must remain RPC-oriented and must not expose public events in this wave.
+
+**File(s):**
+- new `prometeu-vfs/src/main/java/p/studio/vfs/**`
+
+### Step 3 - Implement the Filesystem-Backed First Version
+
+**What:**
+Move direct filesystem behavior out of editor-local services and into `prometeu-vfs`.
+
+**How:**
+Implement the first module version using filesystem access for:
+
+- full-project structural snapshot construction
+- folder-first alphabetical ordering
+- project-only scope
+- UTF-8 text loading
+- binary or unsupported-file rejection
+- support-rule evaluation
+
+Port the logic now living in:
+
+- `EditorProjectSnapshotService`
+- `EditorFileBufferLoader`
+
+without adding new end-user behavior.
+
+**File(s):**
+- new `prometeu-vfs/src/main/java/p/studio/vfs/**`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshotService.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorFileBufferLoader.java`
+
+### Step 4 - Move Core Tests to the Module Boundary
+
+**What:**
+Place structural snapshot and document-loading tests at the new ownership boundary.
+
+**How:**
+Port and expand the current editor service tests into `prometeu-vfs` module tests, covering:
+
+- hidden file inclusion
+- folder-first ordering
+- project-only root handling
+- unsupported file outcomes
+- UTF-8 and NUL-byte handling
+- targeted refresh request behavior
+
+**File(s):**
+- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorProjectSnapshotServiceTest.java`
+- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorFileBufferLoaderTest.java`
+- new `prometeu-vfs/src/test/java/p/studio/vfs/**`
+
+## Test Requirements
+
+### Unit Tests
+
+- structural tree snapshot coverage
+- document load and unsupported-file coverage
+- targeted refresh request coverage
+- project-only scope coverage
+
+### Integration Tests
+
+- module-level integration test that builds a snapshot and resolves documents from a test project root
+
+### Manual Verification
+
+- verify the module can build against Studio without introducing UI dependencies
+- verify no public event API leaks into the first-wave contract
+
+## Acceptance Criteria
+
+- [ ] the build contains a new `prometeu-vfs` module wired into Studio
+- [ ] project tree and document loading behavior now exist in `prometeu-vfs`
+- [ ] the public contract is RPC-oriented and does not expose public events
+- [ ] unsupported-file classification is owned by `prometeu-vfs`
+- [ ] module tests cover the current editor-visible filesystem behavior
+
+## Affected Artifacts
+
+- `settings.gradle.kts`
+- `prometeu-studio/build.gradle.kts`
+- new `prometeu-vfs/**`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshotService.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorFileBufferLoader.java`
+- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorProjectSnapshotServiceTest.java`
+- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorFileBufferLoaderTest.java`
+
+## Risks
+
+- overfitting the first API to current editor internals could make later Studio and LSP consumers awkward
+- keeping too much logic in the editor during migration would weaken the ownership boundary
+- adding too much abstraction now would violate the first-wave scope limit
--- a/discussion/workflow/plans/PLN-0017-add-studio-project-session-ownership-for-prometeu-vfs.md
+++ b/discussion/workflow/plans/PLN-0017-add-studio-project-session-ownership-for-prometeu-vfs.md
@ -0,0 +1,153 @@
+---
+id: PLN-0017
+ticket: studio-editor-document-vfs-boundary
+title: Add Studio project-session ownership for `prometeu-vfs`
+status: review
+created: 2026-03-31
+completed:
+tags:
+  - studio
+  - vfs
+  - project-session
+  - shell
+  - lifecycle
+---
+
+## Briefing
+
+Move `prometeu-vfs` ownership into the Studio project session so document state survives workspace focus changes and is not owned by `EditorWorkspace`.
+
+## Objective
+
+Create a project-session integration path in Studio that constructs, passes, and disposes `prometeu-vfs` state outside workspace focus transitions.
+
+## Background
+
+DEC-0009 requires `prometeu-vfs` to live at project-session scope rather than editor-workspace scope. The current project-open path builds a `MainView` directly from `ProjectReference` and has no dedicated project-session service layer for editor document runtime state.
+
+## Dependencies
+
+- DEC-0009 accepted and normatively locked
+- PLN-0016 accepted or otherwise completed enough to provide the `prometeu-vfs` contract
+
+## Scope
+
+### Included
+
+- add a Studio-side project-session owner for `prometeu-vfs`
+- construct that session during project open
+- keep the session alive while the project window is open
+- dispose the session when the project window closes
+- pass the session or a focused `prometeu-vfs` facade down to `MainView` and workspace consumers
+
+### Excluded
+
+- editor behavior changes beyond consuming the new session-owned dependency
+- public event API exposure
+- watchers
+- shared product-wide session framework beyond what this boundary needs
+
+## Non-Goals
+
+- move packer ownership into the same session abstraction
+- create a multi-project global VFS cache
+- redesign the project launcher UX
+
+## Execution Method
+
+### Step 1 - Introduce a Studio Project-Session Holder for `prometeu-vfs`
+
+**What:**
+Create the Studio-side owner that keeps `prometeu-vfs` alive for the lifetime of an opened project window.
+
+**How:**
+Add a project-session abstraction or holder in `prometeu-studio` that stores:
+
+- the `ProjectReference`
+- the session-owned `prometeu-vfs` instance or facade
+- shutdown/close behavior
+
+This holder must not be tied to workspace focus.
+
+**File(s):**
+- new `prometeu-studio/src/main/java/p/studio/projectsessions/**`
+- `prometeu-studio/src/main/java/p/studio/Container.java`
+
+### Step 2 - Wire Session Creation into the Project Open Path
+
+**What:**
+Construct and dispose the project-session-owned `prometeu-vfs` at the same level where the project window lifecycle is managed.
+
+**How:**
+Update project-open flow so `StudioWindowCoordinator` creates the project session before the main window is shown and closes it when the project window is torn down.
+
+**File(s):**
+- `prometeu-studio/src/main/java/p/studio/window/StudioWindowCoordinator.java`
+- `prometeu-app/src/main/java/p/studio/AppContainer.java`
+
+### Step 3 - Pass the Session into the Main Shell
+
+**What:**
+Make the project-session-owned `prometeu-vfs` available to shell consumers without making the container globally own per-project state.
+
+**How:**
+Update `MainView` construction and related shell wiring so project-scoped consumers receive the session-owned dependency explicitly.
+
+**File(s):**
+- `prometeu-studio/src/main/java/p/studio/window/MainView.java`
+- new `prometeu-studio/src/main/java/p/studio/projectsessions/**`
+
+### Step 4 - Add Session Lifecycle Tests
+
+**What:**
+Verify that `prometeu-vfs` lifecycle follows project-window lifetime rather than workspace focus changes.
+
+**How:**
+Add tests that cover:
+
+- session creation on project open
+- session reuse while switching workspaces
+- session shutdown on project window close
+
+**File(s):**
+- new `prometeu-studio/src/test/java/p/studio/projectsessions/**`
+- new `prometeu-studio/src/test/java/p/studio/window/**`
+
+## Test Requirements
+
+### Unit Tests
+
+- session holder lifecycle behavior
+- shutdown behavior
+
+### Integration Tests
+
+- coordinator-level test for project-open and project-close lifecycle
+
+### Manual Verification
+
+- open a project, switch between workspaces, and confirm document state is not recreated by workspace focus changes
+- close the project window and confirm project-session resources are released
+
+## Acceptance Criteria
+
+- [ ] `prometeu-vfs` is owned by a Studio project session rather than `EditorWorkspace`
+- [ ] opening a project creates the session before normal editor consumption
+- [ ] workspace focus changes do not destroy the project-document state
+- [ ] closing the project window releases session-owned resources
+
+## Affected Artifacts
+
+- `prometeu-studio/src/main/java/p/studio/Container.java`
+- `prometeu-app/src/main/java/p/studio/AppContainer.java`
+- `prometeu-studio/src/main/java/p/studio/window/StudioWindowCoordinator.java`
+- `prometeu-studio/src/main/java/p/studio/window/MainView.java`
+- new `prometeu-studio/src/main/java/p/studio/projectsessions/**`
+- new `prometeu-studio/src/test/java/p/studio/projectsessions/**`
+- new `prometeu-studio/src/test/java/p/studio/window/**`
+
+## Risks
+
+- letting the container own per-project state globally would collapse window boundaries
+- placing ownership too low in the shell would recreate the same focus-coupling problem under a different name
+- weak disposal semantics would leak project-session resources after window close
--- a/discussion/workflow/plans/PLN-0018-migrate-code-editor-to-prometeu-vfs.md
+++ b/discussion/workflow/plans/PLN-0018-migrate-code-editor-to-prometeu-vfs.md
@ -0,0 +1,168 @@
+---
+id: PLN-0018
+ticket: studio-editor-document-vfs-boundary
+title: Migrate the Code Editor workspace to consume `prometeu-vfs`
+status: review
+created: 2026-03-31
+completed:
+tags:
+  - studio
+  - editor
+  - vfs
+  - migration
+  - tests
+---
+
+## Briefing
+
+Replace direct editor-local filesystem services with `prometeu-vfs` while preserving current read-only behavior, current unsupported-file UX, and current session-local open-tab behavior.
+
+## Objective
+
+Make the Code Editor workspace consume the project-session-owned `prometeu-vfs` for tree and document access without changing the visible behavior of the current editor wave.
+
+## Background
+
+The editor currently wires `EditorProjectSnapshotService` and `EditorFileBufferLoader` directly into `EditorWorkspace`. DEC-0009 requires those concerns to move behind `prometeu-vfs`, while the editor remains owner of layout, visual tree state, open-tab presentation, and error presentation.
+
+## Dependencies
+
+- DEC-0009 accepted and normatively locked
+- PLN-0016 accepted or otherwise completed enough to provide the new module contract
+- PLN-0017 accepted or otherwise completed enough to provide project-session ownership
+
+## Scope
+
+### Included
+
+- update `EditorWorkspace` to consume `prometeu-vfs` instead of direct filesystem services
+- preserve existing `EditorOpenFileSession` ownership for session-local tab state
+- preserve the existing unsupported-file modal behavior while moving support determination into `prometeu-vfs`
+- remove or retire editor-local filesystem services whose ownership moved into `prometeu-vfs`
+- adjust tests accordingly
+
+### Excluded
+
+- write support
+- dirty tracking
+- watchers
+- public event API exposure
+- visual redesign of the editor
+
+## Non-Goals
+
+- replace `EditorOpenFileSession`
+- introduce outline semantics or helper-region behavior
+- change the supported-file UX from modal to another surface
+
+## Execution Method
+
+### Step 1 - Rewire Editor Construction Around `prometeu-vfs`
+
+**What:**
+Inject the project-session-owned `prometeu-vfs` dependency into the editor workspace and route tree/document actions through it.
+
+**How:**
+Update shell/editor construction so `EditorWorkspace` receives the `prometeu-vfs` consumer dependency it needs and uses it for:
+
+- navigator refresh
+- file open
+- support resolution
+
+while keeping `EditorOpenFileSession` as the owner of open-tab presentation state.
+
+**File(s):**
+- `prometeu-studio/src/main/java/p/studio/window/MainView.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorOpenFileSession.java`
+
+### Step 2 - Remove Direct Filesystem Ownership from the Editor
+
+**What:**
+Stop the editor package from owning project-tree and document-loading filesystem code.
+
+**How:**
+Delete, deprecate, or reduce editor-local classes once their behavior lives in `prometeu-vfs`, ensuring no direct filesystem responsibility remains in the editor workspace boundary for those concerns.
+
+**File(s):**
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshotService.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorFileBufferLoader.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshot.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectNode.java`
+
+### Step 3 - Preserve Visual Ownership in the Navigator and Status Surfaces
+
+**What:**
+Keep the Studio UI responsible for presentation and view-model concerns after the data-source migration.
+
+**How:**
+Update navigator/status consumers to derive their presentation state from `prometeu-vfs` structural data without moving visual state into the module boundary.
+
+**File(s):**
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectNavigatorPanel.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorStatusBar.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspaceIcons.java`
+
+### Step 4 - Rebalance the Test Suite Around the New Ownership Boundary
+
+**What:**
+Keep editor tests focused on editor-owned behavior after tree/document ownership moves to `prometeu-vfs`.
+
+**How:**
+
+- keep `EditorOpenFileSessionTest` for tab/session behavior
+- move filesystem behavior tests to `prometeu-vfs`
+- add editor-facing tests where necessary for VFS integration, unsupported-file modal routing, and refresh wiring
+
+**File(s):**
+- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorOpenFileSessionTest.java`
+- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorProjectSnapshotServiceTest.java`
+- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorFileBufferLoaderTest.java`
+- new `prometeu-studio/src/test/java/p/studio/workspaces/editor/**`
+
+## Test Requirements
+
+### Unit Tests
+
+- editor session/tab behavior remains covered
+- unsupported-file modal routing remains covered if testable at this layer
+- no editor-local tree/document filesystem tests remain after migration
+
+### Integration Tests
+
+- editor workspace integration test using a project-session-owned `prometeu-vfs` dependency
+
+### Manual Verification
+
+- open a project and confirm the navigator still shows the whole project
+- use manual refresh and confirm the editor tree updates through `prometeu-vfs`
+- open supported text files and confirm content still appears read-only
+- open unsupported files and confirm the existing modal behavior remains intact
+
+## Acceptance Criteria
+
+- [ ] `EditorWorkspace` no longer instantiates direct filesystem tree/document loaders
+- [ ] current read-only editor behavior remains unchanged from the user perspective
+- [ ] unsupported-file handling still appears through Studio UI while support classification lives in `prometeu-vfs`
+- [ ] editor tests now cover editor-owned behavior rather than filesystem ownership that moved to `prometeu-vfs`
+
+## Affected Artifacts
+
+- `prometeu-studio/src/main/java/p/studio/window/MainView.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshotService.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorFileBufferLoader.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshot.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectNode.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectNavigatorPanel.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorStatusBar.java`
+- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorOpenFileSessionTest.java`
+- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorProjectSnapshotServiceTest.java`
+- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorFileBufferLoaderTest.java`
+- new `prometeu-studio/src/test/java/p/studio/workspaces/editor/**`
+
+## Risks
+
+- a shallow adapter-only migration could leave hidden direct filesystem access in the editor package
+- moving too much presentation logic into `prometeu-vfs` would violate DEC-0009
+- changing unsupported-file UX during the migration would exceed the first-wave scope
--- a/test-projects/fragments/.studio/activities.json
+++ b/test-projects/fragments/.studio/activities.json
@ -178,6 +178,16 @@
  "message" : "Asset scan started",
  "severity" : "INFO",
  "sticky" : false
+}, {
+  "source" : "Assets",
+  "message" : "0 assets loaded",
+  "severity" : "SUCCESS",
+  "sticky" : false
+}, {
+  "source" : "Assets",
+  "message" : "Asset scan started",
+  "severity" : "INFO",
+  "sticky" : false
 }, {
  "source" : "Studio",
  "message" : "Project ready",