biaws 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Fabiano Bondia
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,229 @@
+# Bondia Workspaces CLI
+
+CLI do Bondia Workspaces para configurar capacidades locais e integrar agentes
+externos aos contratos operacionais da plataforma.
+
+## 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 --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`.
+
+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:
+
+```bash
+export BIAWS_ROOT=/caminho/absoluto/para/biaws
+biaws instance list
+```
+
+Windows é suportado por WSL2; o binário e os scripts não têm suporte em Windows
+nativo.
+
+## Uso
+
+Com a `biaws-api` em execução:
+
+```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> \
+  --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.
+
+```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`.
+
+## Configuração
+
+- `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
+[`docs/instance-lifecycle.md`](docs/instance-lifecycle.md).
+
+## Desenvolvimento
+
+```bash
+npm ci
+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.

package/bin/biaws.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../src/index.js";

package/docs/command-taxonomy.md

@@ -0,0 +1,36 @@
+# Taxonomia de comandos do BIAWS CLI
+
+O executável `biaws` organiza os comandos em três contextos canônicos:
+
+- `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.
+
+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.
+
+## Convenções
+
+- 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.
+
+## Árvore planejada
+
+```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)
+```

package/docs/instance-lifecycle.md

@@ -0,0 +1,82 @@
+# Ciclo de vida de instâncias
+
+## Setup
+
+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
+```
+
+Em automação, defaults precisam ser autorizados e a senha deve vir de um
+ambiente privado, nunca de argv:
+
+```bash
+BIAWS_BOOTSTRAP_ADMIN_PASSWORD='...' \
+  biaws instance setup --name local --defaults --non-interactive --yes
+```
+
+Use `--storage volumes` ou `--storage directories --storage-root /srv/biaws`.
+Uma mudança de estratégia apenas atualiza a configuração e emite um alerta; o
+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
+```
+
+`list` e `show` omitem o conteúdo integral do `.env`. `start`, `stop` e
+`status` invocam Docker Compose sem shell e com projeto, arquivo Compose e env
+da instância resolvidos explicitamente.
+
+## Smoke test Docker real
+
+Em um checkout descartável com Docker e OpenSSL disponíveis:
+
+1. Reserve as portas `27117`, `3110` e `4410`.
+2. Execute o setup não interativo abaixo.
+3. Confirme que `status` lista `mongo`, `api` e `ui` saudáveis.
+4. Pare e reinicie a instância, verificando que o mesmo `.env`, chave mestra e
+   volumes são reutilizados.
+
+```bash
+BIAWS_BOOTSTRAP_ADMIN_PASSWORD='smoke-only-change-me' \
+  biaws 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 \
+  --api-rate-limit-max 300 --api-rate-limit-window 60 \
+  --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
+```
+
+## Backup, restore e remoção
+
+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
+```
+
+Em TTY, a senha pode ser solicitada de forma mascarada. Restore e remove
+exigem o nome da instância como confirmação; em automação, `--yes` é
+obrigatório. A remoção preserva bind mounts externos por padrão e só os apaga
+com `--delete-external-data`.
+
+O restore valida checksum, descriptografia, versão e entradas do tar antes de
+substituir dados. Portas, URLs e caminhos de storage do destino são
+preservados. Em falhas após a pausa, o mecanismo tenta recompor os serviços e
+mantém o erro original como evidência.

package/docs/releasing.md

@@ -0,0 +1,105 @@
+# Publicação, migração e rollback do CLI
+
+## Publicar no npm
+
+O pacote sem escopo chama-se `biaws`; o executável instalado também se chama
+`biaws`. Antes de publicar, autentique a conta que controla o pacote:
+
+```bash
+npm login
+npm whoami
+```
+
+Da raiz do repositório, valide testes, metadados, shebang e o conteúdo que seria
+empacotado. Este é o modo padrão e não altera o registro npm:
+
+```bash
+./scripts/publish-biaws-cli.sh
+```
+
+Revise a lista do `npm pack --dry-run`, atualize `version` em `package.json` e
+`package-lock.json`, mantenha a árvore Git limpa e só então publique:
+
+```bash
+./scripts/publish-biaws-cli.sh --publish
+```
+
+O script exige autenticação, recusa árvore suja, confirma que a versão ainda
+retorna 404 no registro e executa toda a verificação novamente. MFA continua
+sob controle do próprio npm; não passe OTP por arquivo versionado ou argumento
+de outro wrapper. O nome disponível hoje ainda não fica reservado até a
+primeira publicação bem-sucedida.
+
+## Validar uma instalação limpa
+
+O CI empacota e instala o tarball em prefixo isolado no Node.js 20.19 e 22, em
+Linux e macOS. O ensaio manual equivalente é:
+
+```bash
+cd biaws-cli
+package_file="$(npm pack --pack-destination /tmp)"
+npm install --global --prefix /tmp/biaws-global "/tmp/${package_file}"
+/tmp/biaws-global/bin/biaws --help
+/tmp/biaws-global/bin/biaws --version
+```
+
+Não use um prefixo real nesse ensaio: isso evita substituir outra instalação
+global. Depois da publicação, confirme também `npx biaws@<versão> --help`.
+
+## Compatibilidade e migração
+
+O shebang canônico está em `biaws-cli/bin/biaws.js`. O pacote npm cria o comando
+`biaws`; no checkout, `npm --prefix biaws-cli link` oferece a mesma experiência.
+O antigo `node biaws-cli/src/index.js ...` continua funcional durante a série
+`0.x`, mas documentação e automações novas devem usar `biaws ...`.
+
+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`.
+
+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
+somente as dependências de produção do CLI antes da primeira configuração.
+
+Os scripts `setup-server.sh`, `backup-instance.sh`, `restore-instance.sh` e
+`remove-instance.sh` são engines operacionais invocados pelos comandos oclif;
+não são aliases circulares. A remoção dos wrappers públicos só pode ocorrer
+após aviso de depreciação em uma release `0.x`, telemetria ou evidência de
+adoção e um runbook de substituição atualizado.
+
+O pacote npm isolado cobre ajuda e API remota. Instância, MCP e catálogo local
+dependem do checkout completo; defina `BIAWS_ROOT` para sua raiz quando o
+executável global for chamado fora dela.
+
+## Exercício de release
+
+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`;
+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
+   API/UI;
+6. `biaws 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
+`.env`, API keys, senhas, cookies, arquivos de password, chaves mestras ou
+archives em snapshots, fixtures, logs ou artefatos de CI.
+
+## Rollback
+
+`npm deprecate biaws@<versão> "mensagem"` é preferível a `npm unpublish`, que
+quebra instalações reproduzíveis. Publique uma versão corretiva e fixe
+temporariamente a última versão saudável (`npm install -g biaws@<versão>`).
+Se o problema afetar somente o launcher, o comando legado
+`node biaws-cli/src/index.js ...` permanece como fallback no checkout.
+
+Não reverta dados de instância junto com o pacote CLI. Para mudanças de runtime
+ou dados, siga o backup e rollback de `docs/operations.md` do repositório.