# ForgeWorks Workbench — guia de uso Para Michel, Manolo, André e Daniel. A bancada tem duas portas para a mesma coisa: o navegador e o `fwx` no terminal. Não são dois produtos. Uma sessão aberta no terminal já está no navegador, e o contrário também — quem guarda a sessão é o servidor, não o cliente. --- ## 1. Acesso | Endereço | O que é | |---|---| | `https://workbench.forgeworks.digital` | a bancada: sessões, agentes, terminal, diff | | `https://registeros.forgeworks.digital` | o registro de evidência: linha do tempo e busca na memória | | `https://ai.forgeworks.digital` | o gateway de IA (API, para produtos — não é tela de uso) | **Um login só.** A mesma conta abre as três. Se você abrir o RegisterOS sem estar logado, é mandado para o login e volta sozinho para onde estava. Sua senha inicial foi gerada uma vez e está guardada no servidor, legível só pelo root. Michel entrega. Para trocar: ```bash docker exec forge-workbench python -m agentos_runtime.fwxadmin reset-password SEU_USUARIO ``` Isso gera outra senha **e desloga todas as suas sessões** — um reset que deixa sessão antiga viva não é um reset. ### Permissões Cada pessoa recebe um papel **por projeto**: | Papel | Pode | |---|---| | `observer` | ler | | `reviewer` | ler e aprovar | | `developer` | ler, aprovar e executar | | `admin` | tudo, inclusive administrar | Se um projeto não aparece para você, é porque não há concessão — e o erro é o mesmo para "sem permissão" e "não existe", de propósito: a tela não serve para descobrir quais projetos existem. **Chat livre não precisa de permissão nenhuma.** Não toca repositório, então não há o que proteger. --- ## 2. O fwx Um arquivo só, sem dependências. Copie para a sua máquina e torne executável: ```bash scp root@187.77.78.156:/usr/local/bin/fwx ~/.local/bin/fwx chmod +x ~/.local/bin/fwx ``` Funciona dentro do terminal integrado do VS Code, que é o jeito mais rápido de usar a bancada sem sair do editor. ### Entrar ```bash fwx login ``` Pede usuário e senha, guarda **um token** (nunca a senha) em `~/.config/fwx/config.json`, com permissão só para você. Confira com: ```bash fwx whoami ``` ### Começar a trabalhar ```bash fwx projects # o que você pode abrir fwx start --project forgeworks-digital/FW-Marketing-OS --pr 145 fwx start --project forgeworks-digital/portalliz --issue 812 fwx start --project __free__ --objective "Decidir se vale separar o RegisterOS" ``` Ao abrir com `--pr`, a bancada clona o repositório no workspace da sessão e **já troca para a branch daquela PR**. O agente lê o código de verdade; não peça para colar diff. ### Conduzir ```bash fwx ls # tudo que você enxerga, com estado e duração fwx status FWX-abc123 # uma sessão em detalhe fwx attach FWX-abc123 # acompanhar ao vivo fwx ask FWX-abc123 "revise o diff e aponte riscos de segurança" ``` `fwx ask` já fica acompanhando até o agente parar. Se você não quiser esperar, use `--no-follow`. ### Trocar de agente ```bash fwx agent FWX-abc123 codex-cli --reason "usage limit" ``` A sessão **não recomeça**. Objetivo, branch, arquivos, transcript e decisões seguem com ela. Agentes disponíveis: `claude-code`, `codex-cli`, `cursor-agent`, `gemini` (sem sessão ainda), e `auto` para deixar a plataforma escolher. ### Outros ```bash fwx skills # o catálogo (capítulo 5) fwx test FWX-abc123 --run # roda os testes do projeto no container fwx ci FWX-abc123 # o CI da PR desta sessão (a plataforma consulta) fwx diff FWX-abc123 # o que a sessão mudou fwx logs FWX-abc123 # os eventos da sessão fwx approve FWX-abc123 # o que está esperando decisão fwx session-skills FWX-abc123 # o que esta sessão consegue usar fwx editor FWX-abc123 # abre o VS Code desta sessão e imprime a URL fwx editor FWX-abc123 --stop # fecha o editor fwx checkpoint FWX-abc123 --note "antes de mexer no schema" fwx logout ``` `fwx phase` continua existindo e é resquício: a bancada escolhe a etapa sozinha desde que o conceito de fase manual foi aposentado. Use só se souber exatamente por que está forçando. ### O que ainda não existe `fwx pause`, `resume` e `finish` estão registrados e **dizem que não existem** quando chamados — a plataforma não tem estado pausado nem terminal. Preferimos isso a um comando que aceita e não faz nada. `diff`, `logs`, `test` e `approve` deixaram de ser promessa em 17/09/2026. --- ## 3. A tela **Coluna da esquerda** — projetos e sessões. Cada sessão fechada ocupa uma linha com o título; a aberta mostra projeto, agente e hora. O pontinho diz o estado: ``` ● executando ● falhou (laranja: precisa de você) ● ociosa ● sem execução ainda ``` **Coluna do meio** — a conversa, que fica com quase toda a largura de propósito. **Coluna da direita** — o *Session Inspector*, fechado por padrão (botão "Contexto"). Diz onde a sessão roda, com qual agente, em que branch, com qual checkpoint e — importante — **onde o agente executou**: container isolado, processo no runner, ou gateway de capacidades. **Abas embaixo** — Terminal, Arquivos, Diff, Git, Testes, CI, Skills, Decisões. Nascem fechadas; clicar na aba aberta fecha de novo e a conversa recupera a altura. **Precisam de você** — aparece no topo quando alguma sessão falhou e ninguém respondeu. Some sozinha quando você responde. Resposta do agente não limpa a fila; só a sua. ### O terminal Roda **um comando por vez, sem shell**. Não existe `&&`, `|`, `>` nem `$(...)` ali — se você digitar, ele avisa em vez de rodar torto. Ele executa dentro do container da própria sessão: sem socket do Docker, sem rota para o banco, raiz não gravável, só aquele workspace montado. Não é SSH na VPS, e não deve virar. --- ## 4. VS Code na sessão No cabeçalho da sessão tem um botão **VS Code**. Ele abre, numa aba nova, um VS Code de verdade — o mesmo editor, no navegador — já apontado para o checkout **daquela sessão**. Pelo terminal é a mesma coisa: ```bash fwx editor FWX-abc123 ``` A primeira abertura demora alguns segundos: o editor é um container que sobe na hora. Da segunda em diante é imediato, porque reaproveita o que já está de pé. **É o mesmo diretório que o agente está usando.** Você e ele mexem no mesmo checkout, de propósito: é isso que permite pedir uma alteração ao agente e conferir o resultado sem sincronizar nada. **É o mesmo login.** Sem senha nova, sem token. Quem não puder abrir a sessão recebe o mesmo "não encontrada" de sempre — a tela não serve para descobrir o que existe. **Precisa da mesma permissão de executar**, não de ler. O editor tem terminal dentro dele; tratar isso como leitura seria dar execução por outro nome. ### O que ele pode e não pode Vale o mesmo do capítulo anterior: editar, rodar, commitar local. **Push não**, porque o container não tem credencial do GitHub. O terminal *de dentro do VS Code* é um shell completo (diferente da aba Terminal da bancada, que roda um comando por vez). Ele está dentro do container do editor: sem socket do Docker, sem rota para o banco, só aquele workspace. ### Suas configurações ficam Extensões e preferências ficam guardadas por pessoa e seguem você de uma sessão para outra. Por pessoa e nunca por projeto — configuração não é evidência, e não deve virar um caminho entre dois projetos em que você tem permissões diferentes. ### Ele fecha sozinho Um editor aberto segura memória enquanto existir, e o jeito normal de parar de trabalhar é fechar o notebook. Depois de **oito horas** aberto ele é encerrado. Reabrir é clicar de novo; o que estava salvo no workspace continua lá — o que não estava salvo, não. --- ## 5. Skills **A resposta curta:** suas Skills do Codex e do Claude Code continuam sendo suas e continuam funcionando. A bancada **não** te obriga a recriar nada. Ela descobre as que já existem nesta máquina, mostra quais estão disponíveis em cada sessão, e deixa você referenciar, aprovar ou promover as que valem para o time. ### Os três nomes que confundem | | O que é | |---|---| | **Capacidade** | o que a plataforma consegue fazer (`github.pr.read`) | | **Skill** | o procedimento reusável de *como* um agente faz uma tarefa | | **Receita** | uma sequência de Skills com aprovações no meio | Uma Skill não é um agente, um modelo, um provedor nem uma automação. ### De onde elas vêm Quatro origens, e nenhuma anula a outra: - **ForgeWorks** — as nossas, da organização, no catálogo da bancada; - **Projeto** — no próprio repositório, em `.forgeworks/skills/`; - **Pessoal** — suas, privadas por padrão; - **Nativas do runtime** — o que o Codex, o Claude Code e o Cursor já trazem. O que vale numa sessão é a soma disso, menos o que estiver bloqueado e menos o que não for compatível com o agente daquela sessão. ### Ver o que existe Na tela: aba **Skills**, embaixo da conversa. Ela responde a pergunta que importa na frente de uma sessão — *o que este agente consegue usar agora* — e cada linha que não pode rodar diz o porquê. O **Catálogo completo** mostra tudo o que o host conhece. No terminal: ```bash fwx skills # tudo, com origem, escopo e compatibilidade fwx skills list --source runtime # só as nativas dos agentes fwx skills list --compatible codex-cli # só as com resultado registrado no codex fwx skills list -q review # procurar fwx skills show review.code # uma em detalhe fwx skills show review.code --body # com o SKILL.md junto fwx session-skills FWX-abc123 # o que esta sessão consegue usar fwx skills sources # onde o host procura, e se consegue ``` ### Descobrir não é confiar Isto é o ponto mais importante do desenho, e é deliberado: **Uma Skill encontrada não ganha permissão nenhuma.** Ela entra como `discovered`, aparece na lista, e **não roda**. Se ela declara `github.write`, a declaração fica registrada e a permissão continua valendo zero até alguém conceder. Caso contrário, instalar um CLI daria acesso de escrita aos nossos repositórios. O ciclo é: ``` descoberta → revisada → aprovada → ativa → descontinuada → arquivada (e, a qualquer momento: bloqueada) ``` E se o conteúdo de uma Skill mudar depois de aprovada, ela **volta para descoberta**. A aprovação era daquele procedimento, não daquele nome. ### Compatibilidade é medida, não presumida Uma Skill achada no Codex é `native` no Codex e **`unknown`** em todo o resto — não `portable`. `unknown` quer dizer *ninguém testou*, que é diferente de *funciona*. Fingir portabilidade quebra exatamente num handoff, no meio do trabalho de alguém. Quando você testar e funcionar, registre: ```bash fwx skills compat minha-skill claude-code portable --note "rodou na PR 145" ``` Fica gravado com o seu nome e a data. Uma matriz que ninguém assinou é uma matriz que ninguém pode questionar. ### Adotar uma Skill nativa ```bash fwx skills import architecture-review --mode reference ``` `reference` indexa e **deixa o conteúdo onde está** — a sua Skill do Codex continua sendo a sua Skill do Codex. `mirror` (cópia gerenciada) e `promote` (virar Skill portável da ForgeWorks) são fase 2 e hoje **recusam dizendo isso**, em vez de aceitar e fazer um reference por baixo. ### Governança (admin) ```bash fwx skills sync # procurar de novo no host fwx skills sync --source codex-cli # só um runtime fwx skills approve # torna utilizável fwx skills block --reason ... # tira de circulação fwx skills grant repository.read fwx skills revoke repository.read ``` Listar é aberto a qualquer pessoa logada — um catálogo que precisa de permissão para ser lido não resolve o problema que ele existe para resolver. **Alterar** exige papel `admin`, e cada alteração grava quem fez. Conceder só funciona para permissão que a Skill **declarou**. Pedir para conceder algo que ela não pede é recusado, porque seria uma permissão que ninguém consegue explicar lendo a Skill. ### Onde isso ainda não chegou Honestamente, para não te fazer procurar: - **Skill pessoal ainda não tem de onde sair.** O escopo existe e filtra, mas o assistente de criação (`fwx skills create`) é fase 2. - **A escolha é por palavra, e o time escreve em português.** Os triggers das Skills estão em inglês, então "revisar segurança" não casa com `security`. Quando nada casa, o prompt **diz que nada casou** e manda o conjunto padrão em vez de fingir que escolheu. Busca semântica é fase 3. - **`mirror`, `promote`, testes de Skill e seleção automática pelo Hermes** são fase 2. - **Execução direta (`fwx skill run`)** ainda não existe. --- ## 6. Testes, CI e o Command Center ### Testes Aba **Testes**. Ela mostra **o comando antes de rodar**, e de onde ele veio: declarado pelo projeto ou inferido. A bancada não adivinha — um repositório com `package.json` sem script `test` recebe essa resposta, em vez de levar um `npm test` que sai com erro e parece uma suíte quebrada. Para declarar de uma vez, no repositório: ``` .forgeworks/tests # uma linha, o comando. Ex.: pytest -q ``` Roda no container da própria sessão, como o terminal: sem socket, sem rota para o banco, só aquele workspace. Pelo terminal: ```bash fwx test FWX-abc123 # só diz o que rodaria fwx test FWX-abc123 --run # roda ``` ### CI Aba **CI**, ou `fwx ci`. Diz se os checks da PR desta sessão passaram. Quem consulta é **a plataforma**, que tem o token do GitHub — o container do agente não tem, de propósito. Por isso não peça ao agente para "verificar se o CI passou": ele não tem credencial e responderá que não consegue, corretamente. Desde 17/09/2026 o estado do CI já vai junto no contexto da sessão, então ele consegue responder sem consultar nada. ### Command Center `https://workbench.forgeworks.digital/workbench`, ou o botão no cabeçalho. Uma página para deixar aberta: o que está parado esperando uma pessoa, a contagem de sessões por estado, todas as sessões que você enxerga agrupadas por projeto, e o estado da plataforma. Ela **só lê** — cada botão abre a sessão onde a ação pertence, porque agir sobre uma sessão a partir de uma lista é como se age na sessão errada. ### Aprovações Quando uma skill tem permissão de alto risco concedida — `github.write`, `github.merge`, `repository.write`, `secret.request`, `infra.execute` — ela **não entra na sessão** até alguém decidir. Aparece na fila "Precisam de você" e na aba de aprovações. ```bash fwx approve FWX-abc123 # o que está esperando fwx approve FWX-abc123 --skill # aprovar fwx approve FWX-abc123 --skill --refuse ``` Decidir exige papel **reviewer** ou acima — é uma decisão de revisão sobre um trabalho. Conceder a permissão em si é decisão de admin, e acontece no registry. A aprovação vale **para aquela sessão**: aprovar `repository.write` uma vez não é aprovar para sempre. --- ## 7. O que o agente pode e não pode **Pode:** ler o checkout, criar e editar arquivos, rodar comandos, commitar localmente. **Não pode:** dar push. O container não tem credencial do GitHub, de propósito. Publicar é trabalho da plataforma, depois de revisão — e enquanto não existir credencial de curta duração por sessão, continua assim. Se o agente disser que não consegue empurrar, ele está certo. --- ## 8. Onde as decisões ficam O que uma sessão conclui vai para o **Engram**, a memória da plataforma, e é lá que o RegisterOS busca. Não é transcrição: é o resultado, com chave e revisão, atualizado a cada rodada em vez de virar um monte de fragmentos. Por isso vale terminar um chat livre com uma conclusão clara — é o que sobra depois que a conversa fecha. --- ## 9. Quando algo dá errado **"not signed in" numa das telas** — entre de novo uma vez. Se persistir, limpe os cookies de `forgeworks.digital`. **A sessão falhou** — o motivo fica no evento `execution_failed` e na fila de atenção. Falha de cota troca de agente sozinha quando a sessão está em `auto`. **As abas Arquivos e Diff estão vazias** — a sessão foi aberta sem projeto (chat livre) ou o clone falhou; nesse caso existe um evento `workspace_unavailable` dizendo por quê. **502 no navegador** — alguém está subindo uma versão nova. Recarregue em alguns segundos. **O VS Code abre no tema claro** — não deveria mais: desde 17/09/2026 um editor novo nasce no tema escuro. Se o seu continua claro, é porque seu volume de configurações já existia antes disso; troque em File → Preferences → Color Theme e fica gravado para você. **O VS Code abriu e ficou branco** — quase sempre é a aba tendo sido aberta sem a barra final. O endereço certo termina em `/editor//`; sem a barra, o editor procura os próprios arquivos um nível acima e não acha nenhum. O botão e o `fwx editor` já colocam a barra. **O agente não lembra do que foi dito antes** — não deveria mais: desde 17/09/2026 ele recebe a conversa da própria sessão junto com o pedido. Ele vê as **10 últimas mensagens** (com limite de tamanho); numa sessão muito longa as mais antigas ficam de fora, e o prompt diz quantas foram omitidas. Se precisar que ele considere algo antigo, repita o ponto — ou abra uma sessão nova com o objetivo já ajustado. **A aba Skills diz que nada está disponível** — quase sempre é compatibilidade, não erro. As Skills nativas entram como `discovered` e não rodam até alguém aprovar; as da ForgeWorks só valem nos agentes em que alguém registrou um resultado. Cada linha diz qual dos dois é. **"o editor subiu mas não respondeu a tempo"** — o container subiu e o code-server ainda estava carregando. Abrir de novo resolve; se repetir, o `docker logs fwx-editor-` diz por quê.