diff --git a/records/plugin-dev/KB-PLUGIN-031-plugin-dev-workflow-runbook.md b/records/plugin-dev/KB-PLUGIN-031-plugin-dev-workflow-runbook.md
index 4759198..2e4167f 100644
--- a/records/plugin-dev/KB-PLUGIN-031-plugin-dev-workflow-runbook.md
+++ b/records/plugin-dev/KB-PLUGIN-031-plugin-dev-workflow-runbook.md
@@ -69,8 +69,9 @@ Durante TODO o processo de desenvolvimento:
 | Diretório de plugins | `/opt/projects/GLPI11/docker/glpi/plugins/` (bind → `/var/www/glpi/plugins`, ver [KB-INFRA-001]) |
 | Container GLPI | `glpi11-app` (GLPI dev em `http://192.168.100.49:8081`) |
 | Knowledge-base | `/opt/projects/GLPI11/knowledge-base/` (repo no Forgejo dev) |
-| Forgejo DEV | `git@192.168.100.101:administrador/<plugin>.git` (remote `origin`) |
+| Forgejo DEV | `git@192.168.100.101:administrador/<plugin>.git` (remote `origin`) — web `http://192.168.100.101:3000` / `https://forgejo.lab.coretoai.com`, usuário `administrador` |
 | Forgejo PROD | `servicedesk.mindtek.com.br/git/rodolpho.lopes/<plugin>` (remote `production`) |
+| Credencial Forgejo DEV | **PAT** em `/opt/projects/GLPI11/bin/.forgejo-dev.token` (gitignored — NUNCA versionar; padrão igual ao PROD, ver [KB-PLUGIN-027]). O segredo não fica na KB. |
 
 ## Passo 1 — Acessar o ambiente DEV
 
@@ -132,15 +133,22 @@ docker exec glpi11-app sh -c '
 
 ## Passo 3 — Push para o Forgejo DEV
 
-Criar o repo (API ou UI em `http://192.168.100.101:3000`):
+Criar o repo (API ou UI em `http://192.168.100.101:3000`). Via API, usar o **PAT**
+do arquivo gitignored (ver Mapa do ambiente) — não usar senha em texto:
 
 ```bash
-curl -s -u 'administrador:<senha>' -X POST \
+TOKEN=$(cat /opt/projects/GLPI11/bin/.forgejo-dev.token)
+curl -s -H "Authorization: token $TOKEN" -X POST \
   http://192.168.100.101:3000/api/v1/user/repos \
   -H 'Content-Type: application/json' \
   -d '{"name":"<key>","private":true,"default_branch":"main"}'
 ```
 
+⚠️ **Escopos do PAT:** criar repo via API exige `write:user` **e** `write:repository`.
+Sem `write:user`, a API retorna 403 (`token does not have ... write:user`) e só a
+senha (basic auth) cria o repo. Gerar o token com ambos os escopos para dispensar a senha.
+⚠️ **Push-to-create está DESABILITADO** no Forgejo DEV — o repo precisa existir antes do push.
+
 ```bash
 git remote add origin git@192.168.100.101:administrador/<key>.git
 git add -A && git commit -m "<key> 0.1.0: scaffold"