biaws 0.1.0 → 0.2.0

package/README.md

@@ -1,229 +1,200 @@
 # Bondia Workspaces CLI
 
-CLI do Bondia Workspaces para configurar capacidades locais e integrar agentes
-externos aos contratos operacionais da plataforma.
+CLI do Bondia Workspaces para administrar instalações, configurar o acesso
+global e operar os recursos do workspace associado à pasta atual.
 
 ## Instalação
 
-O pacote público usa o nome `biaws` e expõe um binário com shebang portátil:
-
 ```bash
 npm install --global biaws
-biaws --help
+biaws help
 biaws --version
 ```
 
-Para uma execução descartável, use `npx biaws --help`. Em um checkout para
-desenvolvimento, `npm --prefix biaws-cli link` cria o mesmo comando global; a
-rota direta equivalente é `./biaws-cli/bin/biaws.js`.
+Uma execução descartável pode usar `npx biaws help`. Em um checkout de
+desenvolvimento, `npm --prefix biaws-cli link` cria o mesmo comando global.
+
+O pacote requer Node.js 20.19 ou superior. Operações administrativas de
+instância também exigem Git, Docker e Docker Compose. Windows é suportado por
+WSL2, não de forma nativa.
+
+## Organização
+
+```text
+biaws admin ...      # instalação e instâncias; não exige credencial
+biaws config ...     # URL, perfis e credenciais globais
+biaws workspace ...  # associação da pasta e recursos do workspace
+biaws help [...]     # introdução ou ajuda contextual
+```
+
+Consulte a árvore completa em
+[`docs/command-taxonomy.md`](docs/command-taxonomy.md).
+
+## Primeiros passos
+
+Configure um perfil. A chave é lida de forma mascarada no terminal; em CI, use
+`BIAWS_API_KEY`.
+
+```bash
+biaws config init --api-url https://biaws.example.com
+biaws config doctor
+biaws config show
+```
+
+Depois, associe a pasta atual a um workspace autorizado:
+
+```bash
+cd /caminho/do/projeto
+biaws workspace init
+biaws workspace current
+biaws workspace applications list
+```
+
+Em modo não interativo, informe o ID ou o nome:
+
+```bash
+biaws workspace init WORKSPACE_ID
+```
+
+## Configuração
+
+Os arquivos globais ficam em `~/.config/biaws/` por padrão:
+
+```text
+config.json       perfis, URLs e preferências não secretas
+credentials.json  chaves de API; permissão 0600
+```
+
+`BIAWS_CONFIG_HOME` e `XDG_CONFIG_HOME` podem alterar esse diretório. A pasta do
+projeto recebe apenas `.biaws/config.json`, com o perfil e o ID do workspace.
+Nenhuma chave é gravada no projeto.
+
+A precedência é:
+
+```text
+flags > variáveis de ambiente > configuração da pasta > perfil global > defaults
+```
+
+Variáveis canônicas:
+
+- `BIAWS_API_URL`: endereço da API;
+- `BIAWS_API_KEY`: chave de API, recomendada para CI;
+- `BIAWS_WORKSPACE_ID`: seleção temporária do workspace;
+- `BIAWS_CONFIG_HOME`: diretório global de configuração;
+- `BIAWS_ROOT`: raiz administrativa de um checkout da plataforma.
+
+Perfis permitem usar instalações diferentes:
+
+```bash
+BIAWS_API_KEY=... biaws config init --profile producao --api-url https://biaws.example.com
+biaws config profiles list
+biaws config profiles use producao
+biaws config login --profile producao
+```
+
+Nomes de perfil usam letras minúsculas ASCII, números, ponto, hífen ou
+sublinhado.
+
+## Recursos do workspace
+
+```bash
+biaws workspace list
+biaws workspace applications list
+biaws workspace demands get CLI-123
+biaws workspace demands tasks CLI-123 --status Pendente
+biaws workspace issues list --status open
+biaws workspace issues transition ISSUE_ID --status Resolvido --yes
+```
+
+`--json` emite envelopes estruturados em stdout. Leituras preservam escopo e
+paginação. Escritas resolvem a entidade antes da alteração, exigem confirmação
+e não repetem uma escrita quando o status já é o solicitado.
 
-Consultas e escritas na API funcionam somente com o pacote npm. Operações de
-instância e a configuração completa de MCP/skills também precisam dos assets
-Docker e scripts do repositório. Nesse caso, execute a partir do checkout ou
-defina sua raiz explicitamente:
+Para uma rota ainda não coberta por um comando de domínio:
 
 ```bash
-export BIAWS_ROOT=/caminho/absoluto/para/biaws
-biaws instance list
+biaws workspace api GET /catalog/workspaces
+biaws workspace api PATCH /recurso/ID --body '{"status":"Ativo"}'
 ```
 
-Windows é suportado por WSL2; o binário e os scripts não têm suporte em Windows
-nativo.
+## Agentes e skills
+
+```bash
+biaws workspace agent configure codex
+biaws workspace agent configure claude
+biaws workspace agent doctor codex
+biaws workspace skills list
+biaws workspace skills install SKILL_ID
+biaws workspace skills update
+biaws workspace skills status
+```
 
-## Uso
+O Codex usa `.codex/config.toml` e `.agents/skills`. O Claude Code usa
+`.mcp.json` e `.claude/skills`. Configurações de terceiros são preservadas e
+nenhuma credencial é gravada no projeto.
 
-Com a `biaws-api` em execução:
+## Monitoramento
 
 ```bash
-biaws skills list
-biaws skills publish \
-  --dir ../../.agents/skills/biaws-example \
-  --version 1.0.0 \
-  --changelog "Publicação inicial"
-biaws skills publish-all \
-  --dir ../../.agents/skills \
-  --initial-version 1.0.0 \
-  --changelog "Publicação inicial do catálogo"
-biaws skills install biaws-example
-biaws skills install-all
-biaws skills status
-biaws skills update
-biaws agent configure codex --project /caminho/do/projeto --workspace id-do-workspace
-biaws agent configure claude --project /caminho/do/projeto --workspace id-do-workspace
-biaws agent doctor codex --project /caminho/do/projeto --workspace id-do-workspace
-biaws monitoring signal <aplicação.componente.deployment.runtime> \
+biaws workspace monitoring signal <runtime> \
   --status healthy \
-  --source zabbix \
-  --signal-id zabbix:event:18492 \
-  --message "Serviço saudável" \
-  --metadata-profile sgmp-health/v1 \
-  --metadata '{"service_up":true,"database_up":true,"disk_usage_percent":73.42}'
-biaws monitoring signals <runtime-uuid-ou-caminho> --limit 20
-biaws monitoring describe --template sgmp-health --template-version 1
-biaws monitoring validate --template sgmp-health --template-version 1 \
-  --payload '{"status":"healthy","message":"OK","metadata":{"service_up":true}}'
-biaws monitoring signal <runtime-uuid-ou-caminho> \
-  --source external-monitor --template sgmp-health --template-version 1 \
-  --payload '{"status":"healthy","message":"OK","metadata":{"service_up":true}}'
-```
-
-### Consultas de domínio
-
-As rotas `workspaces`, `applications`, `demands` e `issues` oferecem `list` e
-`get`; `demands tasks <melhoria>` lista tarefas por ID ou código. Filtros de
-workspace/aplicação, busca, status, página e limite são enviados à API sem
-ampliar o escopo. A saída humana sempre informa escopo e paginação. `--json`
-emite somente o envelope versionado `biaws.read.v1` em stdout; diagnósticos
-permanecem em stderr.
-
-As escritas remotas são restritas às ações `demands task-status`,
-`demands complete-task` e `issues transition`. Elas resolvem a entidade antes
-da alteração, exigem confirmação (`--yes` em CI), enviam somente o novo status
-e retornam `biaws.write.v1`. Repetir o status atual não envia outra escrita.
+  --source synthetic-http \
+  --signal-id check:42
+
+biaws workspace monitoring signals <runtime> --limit 20
+biaws workspace monitoring describe --template sgmp-health --template-version 1
+biaws workspace monitoring validate --template sgmp-health --template-version 1 \
+  --payload '{"status":"healthy"}'
+```
+
+O contrato completo está em [`../docs/monitoring.md`](../docs/monitoring.md).
+
+## Administração da instalação
+
+Diagnostique os pré-requisitos e baixe uma release verificada:
 
 ```bash
-biaws workspaces list --json
-biaws applications list --workspace "$ISSUE_WORKSPACE_ID" --page 1 --limit 20
-biaws demands get CLI-OCLIF-2026-08-18 --workspace "$ISSUE_WORKSPACE_ID"
-biaws demands tasks CLI-OCLIF-2026-08-18 --status Pendente --json
-biaws issues list --application APPLICATION_ID --status open --json
-biaws demands complete-task CLI-OCLIF-2026-08-18 CLI-OCLIF-09 --yes --json
-biaws issues transition ISSUE_ID --status Resolvido --yes --json
-```
-
-`monitoring signal` envia uma observação passiva para um runtime. A referência
-pode ser o UUID ou o caminho de identificadores
-`<aplicação>.<componente>.<deployment>.<runtime>`. Use
-`--signal-id` para que retries sejam idempotentes e `--observed-at` quando a
-observação ocorreu antes do envio. Estados aceitos: `unknown`, `healthy`,
-`degraded`, `unavailable` e `stopped`. O contrato completo está em
-[`../docs/monitoring.md`](../docs/monitoring.md).
-
-`monitoring describe` retorna contrato, amostra e apresentação da versão;
-`monitoring validate` executa JSONata sem persistir sinal. Ao enviar
-`--template` e `--template-version`, informe `--payload`; `--status` deixa de ser
-obrigatório porque o resultado é calculado pela API.
-
-Por padrão, as skills são instaladas em `.agents/skills`, considerando o diretório
-corrente. Outro destino pode ser informado com `--target`.
-
-O CLI mantém `.agents/biaws-skills.lock.json` com as versões instaladas. Ao usar
-`--force` ou `skills update`, a instalação anterior é preservada ao lado da nova com
-o sufixo `.backup-<data>`.
-
-`skills publish-all` examina somente os subdiretórios imediatos da pasta informada
-que contenham `SKILL.md`. Uma skill cuja versão já esteja no catálogo é ignorada,
-permitindo repetir a carga inicial sem gerar conflito. Falhas em uma skill não
-interrompem as demais e fazem o comando terminar com código de saída diferente de
-zero.
-
-`agent configure` registra o `biaws-mcp` e instala todas as skills do catálogo.
-Para Codex, usa `.codex/config.toml` e `.agents/skills`. Para Claude Code, usa
-`.mcp.json` e `.claude/skills`. O comando preserva outros servidores MCP e não
-altera configuração global. Ele grava `ISSUE_WORKSPACE_ID` na configuração MCP
-do projeto; informe `--workspace` quando a chave acessar mais de um workspace.
-Use `agent doctor` para verificar Node.js, API, autenticação, workspace,
-configuração e skills.
-
-As rotas `skills`, `agent` e `monitoring` são subcomandos oclif nativos: seus
-argumentos, flags, ajuda e erros de uso são descobertos e validados pelo
-framework. `agent configure` e `agent doctor` permanecem como aliases de
-compatibilidade; para novas automações, prefira `configure codex|claude` e
-`configure doctor`.
+biaws admin doctor
+biaws admin install --version 1.0.0 --dry-run
+biaws admin install --version 1.0.0 --directory /opt/biaws
+```
 
-## Configuração
+O instalador busca `biaws-<versão>.tar.gz` e seu arquivo `.sha256` na release do
+GitHub. Ele recusa diretórios não vazios e extrai somente depois de verificar o
+checksum.
+
+Gerencie as instâncias:
+
+```bash
+biaws admin instance setup --interactive
+biaws admin instance list
+biaws admin instance status local
+biaws admin instance start local
+biaws admin instance stop local
+biaws admin instance backup local
+```
+
+Os executores de monitoramento ativo também pertencem ao nível administrativo:
 
-- `ISSUE_API_URL` ou `ISSUE_API_BASE_URL`: endereço da API.
-- `ISSUE_API_KEY`: chave enviada como `Authorization: Bearer`.
-- `ISSUE_WORKSPACE_ID`: workspace usado em execuções diretas do CLI. Para MCP,
-  o `agent configure` grava esse valor na configuração local do projeto.
-- `BIAWS_ENV_FILE`: caminho absoluto para o `.env` da instância selecionada;
-  contém URL e chave, e o setup o grava na configuração MCP do cliente.
-- `--api-url`: sobrescreve o endereço apenas para a execução atual.
-- `--api-key`: sobrescreve a chave apenas para a execução atual; evite porque o
-  valor pode ficar visível na lista de processos ou no histórico do shell.
-- `--workspace`: seleciona o workspace e, em `agent configure`, persiste a
-  seleção na configuração MCP do projeto. A seleção não amplia as permissões da
-  identidade técnica.
-
-O valor padrão é `http://127.0.0.1:3100`.
-
-## Fundação de comandos
-
-Os novos comandos usam bases separadas por contexto:
-
-- `LocalInstanceCommand` resolve raiz, diretório de instâncias e `.env` sem
-  exigir credenciais;
-- `AuthenticatedApiCommand` valida a autenticação antes de criar o cliente HTTP;
-- `ProjectCommand` acrescenta a resolução explícita do diretório do projeto.
-
-Filesystem, processos, API e terminal ficam atrás de adapters injetáveis. A
-resolução cria um snapshot do ambiente e não altera `process.env`. Subprocessos
-são executados sem shell, recebem argumentos separados e encaminham sinais; ao
-receber segredos para redaction, sua saída é sanitizada antes de chegar ao
-terminal ou a erros.
-
-## Wizards e planos
-
-Fluxos interativos usam `@inquirer/prompts` somente por meio de um
-`PromptAdapter`. Há adapters real, não interativo e programável para testes. A
-camada de wizard resolve flags e ambiente, coleta apenas campos ausentes, valida
-o conjunto, cria um plano imutável, apresenta um resumo redigido, confirma e só
-então chama o executor.
-
-- `--interactive` habilita perguntas quando há TTY;
-- `--non-interactive` nunca pergunta e lista todos os campos obrigatórios
-  ausentes;
-- `--defaults` aplica defaults declarados explicitamente e é sempre opt-in;
-- `--yes` pula somente a confirmação, sem preencher campos;
-- `--json` não muda coleta ou confirmação e reserva o resumo serializado para
-  saída estruturada.
-
-Segredos podem ser acessados pelo executor com `plan.get(campo)`, mas aparecem
-como `[REDACTED]` em `plan.values`, `toJSON()` e no resumo. Cancelamento, EOF e
-sinais abortam antes da chamada do executor com código estável.
-
-## Instâncias locais
-
-`biaws instance setup`, `list`, `show`, `status`, `start` e `stop` cobrem o
-setup e o ciclo de vida local sem exigir chave da API. O setup valida nomes,
-URL, portas e storage antes de chamar Docker, preserva segredos existentes e
-alerta quando uma reexecução muda os destinos persistentes sem mover dados.
-
-A senha administrativa não possui flag: informe-a no prompt mascarado ou em
-`BIAWS_BOOTSTRAP_ADMIN_PASSWORD` num ambiente privado. Consulte o fluxo de
-automação e o smoke test Docker em
+```bash
+biaws admin monitoring validate --instance local
+biaws admin monitoring start --instance local
+biaws admin monitoring status --instance local
+biaws admin monitoring logs --instance local
+biaws admin monitoring provision WORKSPACE_ID --instance local
+```
+
+Detalhes e automação estão em
 [`docs/instance-lifecycle.md`](docs/instance-lifecycle.md).
 
 ## Desenvolvimento
 
 ```bash
 npm ci
+npm run format:check
 npm run check
 npm test
 npm run package:verify
 ```
 
-O roteiro de publicação, migração dos wrappers e rollback está em
-[`docs/releasing.md`](docs/releasing.md). O comando de publicação é dry-run por
-padrão e nunca publica sem `--publish` explícito.
-
-### Configuração de clientes e skills
-
-Os comandos nativos de projeto mantêm a chave exclusivamente no ambiente privado
-(`ISSUE_API_KEY` ou `--env-file`) e gravam no projeto apenas a URL indireta do
-runtime, o workspace e a configuração MCP gerenciada:
-
-```bash
-biaws configure codex --project . --workspace <workspace-id>
-biaws configure claude --project . --workspace <workspace-id>
-biaws configure skills list --json
-biaws configure skills install <skill-id>
-biaws configure skills update [skill-id]
-biaws configure skills verify
-biaws configure doctor codex
-```
-
-Configurações preexistentes de terceiros são preservadas. Um bloco `biaws`
-conflitante só é assumido pelo CLI com `--force`. Sem TTY, cliente, workspace e
-seleção de skill devem ser informados explicitamente; `--all` instala o catálogo.
+O processo de publicação está em [`docs/releasing.md`](docs/releasing.md).

package/docs/command-taxonomy.md

@@ -1,36 +1,76 @@
 # Taxonomia de comandos do BIAWS CLI
 
-O executável `biaws` organiza os comandos em três contextos canônicos:
+O executável `biaws` possui três níveis canônicos e um comando explícito de
+ajuda. Não há aliases para a taxonomia anterior.
 
-- `biaws instance ...`: administração local de instâncias. Não exige API key.
-- `biaws configure ...`: configuração de projeto, Codex, Claude e skills.
-- `biaws api ...`: leitura e escrita autenticadas em recursos do BIAWS.
+```text
+biaws
+├── help [comando...]
+├── admin
+│   ├── install
+│   ├── doctor
+│   ├── config
+│   ├── instance setup|list|show|status|start|stop|backup|restore|remove
+│   └── monitoring build|validate|start|stop|status|logs|provision
+├── config
+│   ├── init|login|show|set|unset|doctor
+│   └── profiles list|use
+└── workspace
+    ├── list|get|init|use|current|unlink
+    ├── agent configure codex|claude
+    ├── agent doctor
+    ├── applications list|get
+    ├── demands list|get|tasks|task-status|complete-task
+    ├── issues list|get|transition
+    ├── skills list|install|install-all|status|update|publish|publish-all
+    ├── monitoring signal|signals|describe|validate
+    └── api <método> <caminho>
+```
 
-Durante a migração, `skills`, `agent` e `monitoring` continuam disponíveis como
-rotas de compatibilidade. Seus argumentos e opções são encaminhados às
-implementações existentes; a substituição por comandos oclif específicos será
-feita incrementalmente.
+## Nível administrativo
 
-## Convenções
+`biaws admin ...` não exige URL, chave de API nem workspace. Ele opera a
+instalação da plataforma, seus pré-requisitos e as instâncias locais. O comando
+`admin install` baixa uma release versionada, exige checksum SHA-256 e não
+sobrescreve diretórios que contenham arquivos.
 
-- nomes de comandos e flags usam kebab-case;
-- ajuda e versão são fornecidas pelo oclif;
-- erros de uso retornam código 2 e falhas operacionais retornam código 1;
-- `--json` reserva stdout para JSON e envia diagnósticos para stderr;
-- aliases `get` e `set` só serão adicionados quando não reduzirem a descoberta;
-- rotas antigas devem emitir depreciação antes de serem removidas.
+## Configuração global
+
+`biaws config ...` gerencia perfis, URLs e credenciais em um diretório XDG. A
+localização segue esta ordem:
+
+1. `BIAWS_CONFIG_HOME`;
+2. `$XDG_CONFIG_HOME/biaws`;
+3. `$HOME/.config/biaws`.
+
+`config.json` armazena somente dados não secretos. As chaves ficam em
+`credentials.json`, criado com permissão `0600`. Um perfil pode ser selecionado
+globalmente ou pela configuração da pasta.
 
-## Árvore planejada
+## Nível de workspace
+
+`biaws workspace init` lista os workspaces autorizados e cria
+`.biaws/config.json` na pasta selecionada. A associação é encontrada também a
+partir dos subdiretórios dessa pasta. Comandos remotos exigem essa associação,
+uma seleção explícita por flag ou as variáveis próprias para automação.
+
+A precedência da resolução é:
 
 ```text
-biaws
-├── instance setup|list|show|status|start|stop|backup|restore|remove
-├── configure codex|claude|skills|doctor
-├── workspaces list|get
-├── applications list|get
-├── demands list|get|tasks|task-status|complete-task
-├── issues list|get|transition
-├── skills ...       (compatibilidade)
-├── agent ...        (compatibilidade)
-└── monitoring ...   (compatibilidade)
+flags > variáveis de ambiente > configuração da pasta > perfil global > defaults
 ```
+
+As variáveis canônicas são `BIAWS_API_URL`, `BIAWS_API_KEY` e
+`BIAWS_WORKSPACE_ID`. Os nomes `ISSUE_*` permanecem aceitos como variáveis de
+ambiente internas durante a transição do backend, mas não representam comandos
+antigos do CLI.
+
+## Convenções
+
+- comandos e flags usam kebab-case;
+- textos apresentados ao usuário usam português do Brasil com Unicode;
+- descrições curtas começam em letra minúscula e não terminam em ponto;
+- `--json` reserva stdout para JSON e envia diagnósticos para stderr;
+- erros de uso retornam código 2 e falhas operacionais retornam código 1;
+- segredos não são aceitos em argumentos de linha de comando;
+- `biaws help` explica o produto e `biaws help <tópico>` navega na árvore.

package/docs/instance-lifecycle.md

@@ -6,7 +6,7 @@ O setup interativo coleta entradas ausentes, mostra um plano redigido e pede
 confirmação antes de mutar arquivos ou chamar Docker:
 
 ```bash
-biaws instance setup --interactive
+biaws admin instance setup --interactive
 ```
 
 Em automação, defaults precisam ser autorizados e a senha deve vir de um
@@ -14,7 +14,7 @@ ambiente privado, nunca de argv:
 
 ```bash
 BIAWS_BOOTSTRAP_ADMIN_PASSWORD='...' \
-  biaws instance setup --name local --defaults --non-interactive --yes
+  biaws admin instance setup --name local --defaults --non-interactive --yes
 ```
 
 Use `--storage volumes` ou `--storage directories --storage-root /srv/biaws`.
@@ -24,11 +24,11 @@ CLI não move dados existentes implicitamente.
 ## Operação
 
 ```bash
-biaws instance list
-biaws instance show local
-biaws instance status local
-biaws instance start local
-biaws instance stop local
+biaws admin instance list
+biaws admin instance show local
+biaws admin instance status local
+biaws admin instance start local
+biaws admin instance stop local
 ```
 
 `list` e `show` omitem o conteúdo integral do `.env`. `start`, `stop` e
@@ -47,7 +47,7 @@ Em um checkout descartável com Docker e OpenSSL disponíveis:
 
 ```bash
 BIAWS_BOOTSTRAP_ADMIN_PASSWORD='smoke-only-change-me' \
-  biaws instance setup \
+  biaws admin instance setup \
   --name smoke --mongo-port 27117 --api-port 3110 --ui-port 4410 \
   --public-url http://localhost:4410 --storage volumes \
   --admin-email smoke@example.test --admin-name Smoke \
@@ -55,9 +55,9 @@ BIAWS_BOOTSTRAP_ADMIN_PASSWORD='smoke-only-change-me' \
   --auth-rate-limit-max 100 --auth-rate-limit-window 10 \
   --api-key-rate-limit-max 1000 --api-key-rate-limit-window 3600 \
   --no-demo-seed --non-interactive --yes
-biaws instance status smoke
-biaws instance stop smoke
-biaws instance start smoke
+biaws admin instance status smoke
+biaws admin instance stop smoke
+biaws admin instance start smoke
 ```
 
 ## Backup, restore e remoção
@@ -66,9 +66,9 @@ Os comandos oclif usam o archive portátil existente sem colocar a senha em
 `argv`:
 
 ```bash
-biaws instance backup alpha --password-file /caminho/privado/senha
-biaws instance restore beta --archive ./alpha.tar.gz.enc --password-file /caminho/privado/senha --yes
-biaws instance remove beta --yes
+biaws admin instance backup alpha --password-file /caminho/privado/senha
+biaws admin instance restore beta --archive ./alpha.tar.gz.enc --password-file /caminho/privado/senha --yes
+biaws admin instance remove beta --yes
 ```
 
 Em TTY, a senha pode ser solicitada de forma mascarada. Restore e remove

package/docs/releasing.md

@@ -57,7 +57,7 @@ Os wrappers públicos preservados são:
 
 - `scripts/setup-local.sh`: setup co-localizado seguido de configuração;
 - `scripts/setup-client.sh`: configuração de um cliente remoto;
-- `scripts/configure.sh`: adapter legado para `biaws agent configure/doctor`.
+- `scripts/configure.sh`: adapter legado para `biaws workspace agent configure/doctor`.
 
 Esses wrappers usam `scripts/run-biaws-cli.sh`, que fixa `BIAWS_ROOT` no
 checkout e executa o entrypoint com shebang. Em um clone limpo, ele instala
@@ -79,14 +79,14 @@ Antes de marcar uma release, use credenciais descartáveis e execute, nesta
 ordem, em uma instância isolada:
 
 1. `biaws --help` e `biaws --version` pela instalação empacotada;
-2. `biaws instance setup` e `biaws configure codex|claude` com `BIAWS_ROOT`;
+2. `biaws admin instance setup` e `biaws workspace agent configure codex|claude` com `BIAWS_ROOT`;
 3. uma consulta `workspaces list --json` e outra por código, como
    `demands get <código> --json`;
 4. uma escrita idempotente com `demands task-status ... --yes --json`, seguida
    de nova leitura;
-5. `biaws instance backup`, restore em uma instância de destino e validação de
+5. `biaws admin instance backup`, restore em uma instância de destino e validação de
    API/UI;
-6. `biaws instance remove <destino> --yes`, preservando dados externos salvo
+6. `biaws admin instance remove <destino> --yes`, preservando dados externos salvo
    autorização explícita.
 
 Capture somente códigos de saída, envelopes sanitizados e checksums. Não grave

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "biaws",
-  "version": "0.1.0",
-  "description": "CLI do Bondia Workspaces para configuração do ambiente local",
+  "version": "0.2.0",
+  "description": "CLI do Bondia Workspaces para administração, configuração e operação de workspaces",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -39,8 +39,57 @@
   "oclif": {
     "bin": "biaws",
     "dirname": "biaws",
-    "commands": "./src/commands",
-    "topicSeparator": " "
+    "commands": "./src/cli",
+    "topicSeparator": " ",
+    "topics": {
+      "admin": {
+        "description": "Administra a instalação e as instâncias da plataforma",
+        "subtopics": {
+          "instance": {
+            "description": "Configura e opera instâncias locais do BIAWS"
+          },
+          "monitoring": {
+            "description": "Configura e opera executores de monitoramento"
+          }
+        }
+      },
+      "config": {
+        "description": "Gerencia perfis, URLs e credenciais globais",
+        "subtopics": {
+          "profiles": {
+            "description": "Gerencia os perfis globais de acesso"
+          }
+        }
+      },
+      "workspace": {
+        "description": "Associa a pasta e opera os recursos do workspace",
+        "subtopics": {
+          "agent": {
+            "description": "Configura e diagnostica clientes de agentes",
+            "subtopics": {
+              "configure": {
+                "description": "Configura clientes de agentes na pasta atual"
+              }
+            }
+          },
+          "applications": {
+            "description": "Consulta aplicações do workspace"
+          },
+          "demands": {
+            "description": "Consulta melhorias e suas tarefas"
+          },
+          "issues": {
+            "description": "Consulta e atualiza issues"
+          },
+          "monitoring": {
+            "description": "Envia e consulta sinais de monitoramento"
+          },
+          "skills": {
+            "description": "Gerencia as skills do workspace"
+          }
+        }
+      }
+    }
   },
   "scripts": {
     "start": "node bin/biaws.js",