@pathbit/agentdevkit 0.0.0-stage → 0.0.6

package/README.es.md

@@ -0,0 +1,91 @@
+---
+description: Instrucciones y herramientas portátiles para agentes de desarrollo.
+language: es
+---
+
+# AgentDevKit
+
+[Português](README.md) · [English](README.en.md) · [Paquete npm][npm-package]
+
+[![npm][npm-badge]][npm-package] [![MIT][license-badge]](LICENSE)
+
+Organiza el trabajo con agentes de código, desde la planificación hasta la
+verificación. Mantén skills, reglas, comandos y perfiles en `.pbai4devs`;
+el kit genera las referencias de cada [cliente compatible][clients].
+El código vive en `src/`, las pruebas del producto en `tests/` y los recursos
+compartidos en `.pbai4devs/`. Las carpetas, entradas y preferencias generadas
+son locales y no se versionan.
+
+## Empezar en tu proyecto
+
+Con Node.js 18+ y npm, ejecuta en tu proyecto, sin iniciar sesión:
+
+```console
+npx @pathbit/agentdevkit init
+```
+
+Elige tus agentes en la pregunta inicial o usa `--agents codex,claude`.
+La selección se guarda en el proyecto; `agents` permite consultarla o cambiarla.
+Sin interacción ni selección anterior, el valor predeterminado es `all`.
+
+Después, abre el proyecto en tu agente y pide:
+
+> Lee AGENTS.md y usa la skill proximos-passos para orientar mi trabajo.
+
+La [guía de instalación](docs/guides/installation.md) incluye Windows, Node ausente,
+simulación y actualización. Instala y actualiza mediante el
+[paquete npm público][packages];
+la [release v0.0.6][release] conserva artefactos y checksums para verificarlos.
+No requiere instalación global.
+La CLI guarda el idioma `pt`, `en` o `es` por proyecto.
+
+## Explorar
+
+| Quiero… | Leer |
+| --- | --- |
+| Entender el kit | [Wiki](docs/README.md) |
+| Planificar o retomar un proyecto | [Flujo](docs/guides/workflow.md) |
+| Crear una skill o comando | [Recursos](docs/guides/resources.md) |
+| Instalar herramientas y verificar | [Herramientas y pruebas][tests] |
+| Consultar opciones o resolver un error | [CLI][cli] · [Soluciones][help] |
+| Mejorar el kit | [Contribuir](CONTRIBUTING.md) |
+| Probar los escenarios | [Ejemplos](https://github.com/pathbit/AgentDevKit/tree/master/examples) |
+
+## Desarrollar este repositorio
+
+Usa Node.js 24+ con npm. Ejecuta `npm ci --ignore-scripts`, `npm run check`,
+`npm test` y `npm run examples`. Los ejemplos se generan localmente en
+`examples/generated/`; `npm run test:examples` ejecuta los escenarios.
+Consulta la [guía de desarrollo](docs/maintainers/development.md) para conocer
+la estructura.
+
+Las guías detalladas están en portugués. Instalar el kit prepara instrucciones;
+las herramientas se instalan por separado. Los documentos de producto siguen
+las decisiones de planificación. Los proyectos existentes conservan su código.
+Una referencia no demuestra que un cliente haya cargado la skill.
+
+## Licencia y autoría
+
+Mantenido por [PathBit](https://www.pathbit.com.br),
+con licencia [MIT](LICENSE).
+La instalación incluye la licencia del kit en `.pbai4devs/LICENSE` y conserva
+la licencia y los archivos propios de tu proyecto.
+
+[Changelog](CHANGELOG.md) · [Roadmap](docs/product/roadmap.md)
+
+¿Encontraste un problema o tienes una idea? [Abre una issue][issues] con los
+formularios. Consulta [cómo participar](docs/maintainers/community.md).
+
+**[ Próximo paso ]** Sigue la [instalación](docs/guides/installation.md) y pide
+al agente que lea `AGENTS.md`.
+
+[clients]: .pbai4devs/COMPATIBILIDADE.md
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.6
+[npm-package]: https://www.npmjs.com/package/@pathbit/agentdevkit
+[npm-badge]: https://img.shields.io/npm/v/%40pathbit%2Fagentdevkit
+[license-badge]: https://img.shields.io/badge/license-MIT-blue
+[tests]: docs/guides/tools-and-testing.md
+[cli]: docs/guides/cli.md
+[help]: docs/guides/troubleshooting.md
+[issues]: https://github.com/pathbit/AgentDevKit/issues/new/choose
+[packages]: docs/maintainers/packages.md

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# AgentDevKit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English](https://github.com/pathbit/AgentDevKit/blob/master/README.en.md) · [Español](https://github.com/pathbit/AgentDevKit/blob/master/README.es.md) · [Pacote npm][npm-package]
+
+[![npm][npm-badge]][npm-package] [![MIT][license-badge]](https://github.com/pathbit/AgentDevKit/blob/master/LICENSE)
+
+Uma forma de organizar o trabalho com agentes de código, do planejamento à
+verificação. Você mantém skills, regras, comandos e perfis em `.pbai4devs`;
+o kit gera os apontamentos que cada cliente sabe encontrar.
+
+Use com Codex, Claude, Cursor, Copilot, OpenCode e outros
+[clientes compatíveis](https://github.com/pathbit/AgentDevKit/blob/master/.pbai4devs/COMPATIBILIDADE.md). Há uma origem;
+cada cliente conserva seu formato de descoberta. No repositório, o código
+fica em `src/`, os testes em `tests/` e os recursos compartilhados em
+`.pbai4devs/`. Pastas nativas, entradas e preferências são geradas localmente.
+
+## Começar em um projeto
+
+Com Node.js 18+ e npm, execute na pasta do seu projeto, sem login:
+
+```console
+npx @pathbit/agentdevkit init
+```
+
+Escolha os agentes na pergunta inicial ou informe `--agents codex,claude`.
+A escolha fica salva no projeto; `agents` permite consultá-la ou alterá-la.
+Sem interação ou escolha anterior, o padrão é `all` (todos os clientes).
+
+Depois, abra o projeto no seu agente e peça:
+
+> Leia AGENTS.md e use a skill proximos-passos para orientar meu trabalho.
+
+Windows, instalação sem Node, simulação e atualização estão no
+[guia de instalação](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/installation.md). A distribuição usa a
+versão publicada no [npm público][packages] e na [release v0.0.6][release],
+sem instalação global. Instalação e atualização usam o pacote do registro;
+os arquivos da release servem para conferir os artefatos publicados.
+O idioma da CLI pode ser `pt`, `en` ou `es`.
+
+## Encontre o que precisa
+
+| Quero… | Ler |
+| --- | --- |
+| Entender e começar | [Wiki](https://github.com/pathbit/AgentDevKit/blob/master/docs/README.md) |
+| Planejar ou retomar um projeto | [Fluxo de trabalho](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/workflow.md) |
+| Criar uma skill ou comando | [Recursos](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/resources.md) |
+| Instalar ferramentas e comprovar uma entrega | [Ferramentas e testes][tests] |
+| Consultar opções ou resolver um erro | [CLI][cli] · [Soluções][help] |
+| Melhorar o próprio kit | [Contribuir](https://github.com/pathbit/AgentDevKit/blob/master/CONTRIBUTING.md) |
+| Experimentar os cenários | [Exemplos](https://github.com/pathbit/AgentDevKit/tree/master/examples) |
+
+## Desenvolver este repositório
+
+Com Node.js 24+ e npm, na raiz:
+
+```console
+npm ci --ignore-scripts
+npm run check
+npm test
+npm run examples
+```
+
+Os exemplos aparecem em `examples/generated/`. Para testar todos os cenários,
+use `npm run test:examples`; para verificar o pacote, `npm run verify`.
+O [guia de desenvolvimento](https://github.com/pathbit/AgentDevKit/blob/master/docs/maintainers/development.md) explica a árvore
+e os comandos.
+
+Instalar o kit prepara instruções. As ferramentas são instaladas por uma ação
+separada; PRD, design e specs surgem quando você inicia o planejamento.
+Projetos existentes preservam seu código e suas decisões.
+
+## Licença e autoria
+
+Mantido pela [PathBit](https://www.pathbit.com.br),
+sob a licença [MIT](https://github.com/pathbit/AgentDevKit/blob/master/LICENSE).
+A instalação inclui a licença do kit em `.pbai4devs/LICENSE` e preserva
+a licença e os arquivos próprios do seu projeto.
+
+[Changelog](https://github.com/pathbit/AgentDevKit/blob/master/CHANGELOG.md) · [Roadmap](https://github.com/pathbit/AgentDevKit/blob/master/docs/product/roadmap.md)
+
+Encontrou um problema ou tem uma ideia? [Abra uma issue][issues] pelos
+[formulários de contribuição](https://github.com/pathbit/AgentDevKit/blob/master/docs/maintainers/community.md).
+
+**[ Próximo passo ]** Siga a [instalação](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/installation.md) e peça
+ao seu agente para ler `AGENTS.md`.
+
+[tests]: https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/tools-and-testing.md
+[cli]: https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/cli.md
+[help]: https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/troubleshooting.md
+[issues]: https://github.com/pathbit/AgentDevKit/issues/new/choose
+[packages]: https://github.com/pathbit/AgentDevKit/blob/master/docs/maintainers/packages.md
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.6
+[npm-package]: https://www.npmjs.com/package/@pathbit/agentdevkit
+[npm-badge]: https://img.shields.io/npm/v/%40pathbit%2Fagentdevkit
+[license-badge]: https://img.shields.io/badge/license-MIT-blue

package/bin/README.md

@@ -0,0 +1,8 @@
+---
+description: Entrada executável do pacote AgentDevKit.
+---
+
+# Executável
+
+`agentdevkit.mjs` prepara Node.js 24+ quando necessário e inicia a CLI.
+Este diretório pertence ao pacote; não é copiado para projetos atendidos.

package/bin/agentdevkit.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ensureRuntime, environmentWithNode } from '../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.mjs';
+
+const file = fileURLToPath(import.meta.url);
+export async function run(argv = process.argv.slice(2), options = {}) {
+  const version = options.nodeVersion || process.versions.node;
+  const language = argv.includes('en') ? 'en' : argv.includes('es') ? 'es' : 'pt';
+  if (!(options.bun ?? process.versions.bun) && Number(version.split('.')[0]) >= 24) {
+    const { main } = await import('../src/cli.mjs'); return main(argv, options);
+  }
+  let error;
+  try {
+    if (Number(version.split('.')[0]) < 18) throw new Error('Instale Node.js 24+ pelo gerenciador do sistema operacional.');
+    const runtime = await (options.ensureRuntime || ensureRuntime)({ root: resolve(dirname(file), '..'), run: options.spawn || spawnSync });
+    const result = (options.spawn || spawnSync)(runtime.node, [file, ...argv], { stdio: 'inherit', env: environmentWithNode(process.env, runtime.node) });
+    if (result.error) throw result.error;
+    return result.status ?? 1;
+  } catch (cause) { error = cause; }
+  const message = language === 'en' ? 'Could not prepare Node.js 24+.' : language === 'es' ? 'No se pudo preparar Node.js 24+.' : 'Não foi possível preparar Node.js 24+.';
+  const next = [{ command: 'https://nodejs.org/en/download', label: 'Node.js 24+' }];
+  const output = options.stdout || process.stdout;
+  if (argv.includes('--json')) output.write(`${JSON.stringify({ ok: false, command: 'runtime', language, message, detail: error?.message, next })}\n`);
+  else output.write(`${message}\n\n[ ${language === 'en' ? 'Next step' : language === 'es' ? 'Próximo paso' : 'Próximo passo'} ]\n  > ${next[0].command}\n`);
+  return 1;
+}
+
+function isEntrypoint() {
+  try { return Boolean(process.argv[1]) && realpathSync(resolve(process.argv[1])) === realpathSync(file); }
+  catch { return false; }
+}
+if (isEntrypoint()) process.exitCode = await run();

package/docs/README.md

@@ -0,0 +1,81 @@
+---
+description: Wiki do AgentDevKit, do primeiro uso à manutenção do kit.
+language: pt
+---
+
+# Wiki do AgentDevKit
+
+O AgentDevKit organiza instruções de trabalho para agentes de código. A pasta
+`.pbai4devs` guarda a origem; as pastas dos clientes apontam para ela. Você
+pode trocar de agente sem manter várias cópias das mesmas instruções.
+
+## Organização
+
+| Pasta | Conteúdo |
+| --- | --- |
+| [Guias](guides/README.md) | Instalação, uso, comandos e solução de problemas. |
+| [Produto](product/README.md) | Requisitos, experiência, arquitetura e roadmap. |
+| [Manutenção](maintainers/README.md) | Desenvolvimento, comunidade e publicação. |
+| [Specs](specs/README.md) | Escopo e critérios de aceite de cada incremento. |
+
+## Comece pelo seu objetivo
+
+| Objetivo | Caminho |
+| --- | --- |
+| Primeiro uso | [Instalar][install] → [seguir o fluxo][flow] |
+| Projeto em andamento | [Instalar com simulação][install] → [retomar][flow] |
+| Personalizar agentes | [Recursos][resources] → [compatibilidade][clients] |
+| Executar ou verificar algo | [CLI](guides/cli.md) → [ferramentas e testes][tests] |
+| Corrigir uma dificuldade | [Soluções e recuperação](guides/troubleshooting.md) |
+| Contribuir com o kit | [Contribuir][contrib] → [design](product/design.md) |
+| Desenvolver e experimentar | [Guia rápido][development] → [exemplos][examples] |
+| Preparar uma versão | [Manutenção e releases](maintainers/maintenance.md) |
+| Publicar ou instalar o pacote npm | [npm público](maintainers/packages.md) |
+| Relatar um bug ou propor melhoria | [Participar](maintainers/community.md) |
+
+## Entenda os termos
+
+| Termo | Significado |
+| --- | --- |
+| Skill | Procedimento que o agente segue para uma tarefa. |
+| Regra | Orientação aplicável a um contexto de trabalho. |
+| Comando | Entrada para executar um caso de uso. |
+| Perfil de agente | Papel especializado, como revisão. |
+| Adaptador | Traduz referências para o formato de cada cliente. |
+| Espelho | Apontamento gerado para um recurso da origem. |
+| Template | Modelo que será preenchido com decisões do projeto. |
+| Spec | Escopo de uma entrega com critérios verificáveis. |
+| Evidência | Registro de uma verificação realmente executada. |
+
+O agente lê e executa as instruções conforme as capacidades de seu cliente.
+A CLI instala, sincroniza e diagnostica arquivos. Ter um apontamento correto
+não comprova que determinado cliente carregou ou executou a skill.
+
+## Conheça este produto
+
+- [PRD](product/prd.md): problema, público, requisitos e limites.
+- [Experiência da CLI](product/ux-ui.md): interação, idiomas e saídas.
+- [Design técnico](product/design.md): componentes, estado e preservação de arquivos.
+- [Roadmap](product/roadmap.md) e [specs](specs/README.md): escopo das entregas.
+- [Changelog](../CHANGELOG.md): mudanças por versão.
+
+Esta wiki documenta **o AgentDevKit** e fica versionada junto ao código.
+Os projetos que recebem o kit usam os
+[templates](../.pbai4devs/templates/README.md) para seus próprios documentos,
+após perguntas e decisões. A instalação não copia esta wiki para `docs/`
+do projeto atendido.
+
+Os guias completos estão em português; os READMEs de entrada também existem
+em [inglês](../README.en.md) e [espanhol](../README.es.md). O idioma salvo pela
+CLI orienta a comunicação dos agentes, sem traduzir documentos existentes.
+
+[Voltar ao projeto](../README.md)
+
+[install]: guides/installation.md#instalar
+[flow]: guides/workflow.md
+[clients]: ../.pbai4devs/COMPATIBILIDADE.md
+[tests]: guides/tools-and-testing.md
+[contrib]: ../CONTRIBUTING.md
+[examples]: https://github.com/pathbit/AgentDevKit/tree/master/examples
+[resources]: guides/resources.md
+[development]: maintainers/development.md

package/docs/guides/README.md

@@ -0,0 +1,14 @@
+---
+description: Guias de instalação, uso e verificação do AgentDevKit.
+---
+
+# Guias de uso
+
+- [Instalação](installation.md)
+- [Comandos da CLI](cli.md)
+- [Fluxo de trabalho](workflow.md)
+- [Recursos dos agentes](resources.md)
+- [Ferramentas e testes](tools-and-testing.md)
+- [Solução de problemas](troubleshooting.md)
+
+[Voltar à documentação](../README.md)

package/docs/guides/cli.md

@@ -0,0 +1,81 @@
+---
+description: Comandos, opções e respostas do AgentDevKit.
+---
+
+# Referência da CLI
+
+Execute o pacote do npm público por `npx`, sem login:
+
+```console
+npx @pathbit/agentdevkit --help
+```
+
+Nas tabelas, `agentdevkit` representa esse executável. No checkout das fontes,
+use `npm run cli -- <comando>` ou `node bin/agentdevkit.mjs`.
+Esse código não é copiado ao projeto
+atendido; lá os comandos de manutenção usam o pacote por `npx`.
+
+## Comandos
+
+| Comando | Resultado |
+| --- | --- |
+| `init [pasta]` | Instala ou reaplica os recursos. |
+| `update` | Usa os recursos da versão do pacote executado. |
+| `sync` | Reconstrói as derivações da fonte do projeto. |
+| `sync --check` | Confere as derivações sem escrever. |
+| `doctor` | Diagnostica a instalação. |
+| `next` | Orienta a próxima etapa do projeto. |
+| `lang [idioma]` | Consulta ou altera o idioma: pt, en ou es. |
+| `agents` | Consulta clientes disponíveis e seleção local. |
+| `agents codex,claude` | Altera a seleção local. |
+| `agents all` | Habilita todos os clientes. |
+| `tools <ação>` | Executa o gerenciador de ferramentas. |
+| `--help`, `--version` | Ajuda ou versão do pacote. |
+
+Sem comando, a CLI executa `init`, que pode criar arquivos. `language` é alias
+de `lang`; `clients`, de `agents`. O idioma não traduz documentos existentes.
+
+## Opções
+
+| Opção | Uso |
+| --- | --- |
+| `--target <pasta>` | Projeto-alvo; não combine com a pasta de `init`. |
+| `--lang <idioma>` | Idioma desta execução. |
+| `--agents <lista>` | IDs separados por vírgula, ou `all`. |
+| `--clients <lista>` | Alias de `--agents`. |
+| `--yes`, `-y` | Evita perguntas iniciais; não força conflitos. |
+| `--dry-run` | Exibe o plano sem aplicar alterações. |
+| `--force` | Substitui conflitos gerenciados, com backup. |
+| `--json` | Produz uma resposta JSON para automação. |
+
+O primeiro uso interativo reúne idioma e clientes. Sem interação, valem as
+opções explícitas, a escolha local salva e, por último, `all`. Confira os
+[IDs e dependências](../../.pbai4devs/COMPATIBILIDADE.md).
+
+`update` não procura automaticamente a próxima versão: execute o pacote
+da versão desejada. `sync` não atualiza a fonte distribuída.
+A seleção e os derivados são locais; o source compartilhado permanece no Git.
+
+## Ferramentas
+
+As ações são `list`, `setup`, `install`, `update`, `check`, `info`, `run`
+e `unlock`. Consultar ou executar não instala silenciosamente.
+`setup` prepara as ferramentas compatíveis; outros comandos podem receber
+um nome ou grupo. Consulte [ferramentas e testes](tools-and-testing.md).
+
+## JSON e retorno
+
+As respostas incluem `ok`, `command`, `version`, `language`, `target` e
+`next`. Conforme a operação, há seleção, plano, conflitos, backup e erros.
+Leia os campos estruturados, não dependa da tradução da mensagem.
+
+| Código | Significado |
+| --- | --- |
+| `0` | Operação concluída; examine também o tipo da resposta. |
+| `1` | Falha, conflito ou diagnóstico com pendências. |
+| `2` | Argumentos inválidos; ferramentas podem propagar outros códigos. |
+
+`doctor` verifica o kit, não o produto inteiro. `next` pode terminar com
+sucesso enquanto orienta uma etapa ainda pendente.
+
+[Wiki](../README.md) · [Solução de problemas](troubleshooting.md)

package/docs/guides/installation.md

@@ -0,0 +1,86 @@
+---
+description: Instalação do AgentDevKit e geração local dos agentes.
+---
+
+# Instalação
+
+O pacote traz o gerador e as fontes compartilhadas. A instalação prepara
+`.pbai4devs` e cria somente os apontamentos dos agentes escolhidos.
+
+## Pré-requisitos
+
+Use Node.js 18+ com npm para iniciar o pacote. O launcher prepara Node 24+
+quando o runtime atual é antigo; o núcleo e as ferramentas usam Node 24+.
+A extração de runtime usa o executável nativo `tar`, sem scripts shell.
+
+Sem Node/npm, o agente precisa primeiro instalar o runtime pelo mecanismo do
+sistema operacional e continuar. `npx` não funciona antes dessa instalação.
+O [guia de preparo][bootstrap] explica as duas situações.
+
+## Instalar
+
+O pacote [`@pathbit/agentdevkit`](../maintainers/packages.md) é publicado no
+npm público. Execute na pasta do projeto, sem login:
+
+```console
+npx @pathbit/agentdevkit init
+```
+
+Sem comando adicional, o pacote executa `init`. Em terminal interativo,
+pergunta idioma e agentes. No aplicativo desktop, peça ao agente para reunir
+as escolhas no chat e usar `--lang` e `--agents` na CLI.
+
+Consulte [CLI](cli.md) para acrescentar seleção, destino e simulação. `--json`,
+`--yes`, `--dry-run` ou ausência de terminal interativo evitam perguntas.
+Sem escolha explícita ou salva, `all` mantém todos os clientes compatíveis.
+
+## O que fica no projeto
+
+| Conteúdo | Tratamento |
+| --- | --- |
+| `.pbai4devs` com recursos e templates | Fonte compartilhada versionável. |
+| Skills, regras e comandos nos clientes | Apontamentos locais gerados. |
+| Entradas da raiz criadas pelo kit | Arquivos locais gerados. |
+| Índices, manifesto e seleção pessoal | Derivados locais ignorados. |
+| Código, documentos e configurações humanas | Preservados. |
+| Downloads e resultados de testes | Locais e ignorados. |
+| `.pbai4devs/LICENSE` | Licença MIT do kit, copiada do pacote. |
+
+O gerador completo permanece no pacote npm. Ele não copia `bin/`, `src/`,
+`scripts/release/` ou os testes do produto para o projeto atendido.
+Instalar o kit não inicia uma aplicação nem instala todas as ferramentas.
+A licença existente na raiz do projeto não é substituída. A cópia do hub
+identifica a licença dos recursos do AgentDevKit, sem redefinir a do projeto.
+
+## Git e migração
+
+Um `.gitignore` dentro de `.pbai4devs` só controla essa árvore. Para os
+apontamentos externos, o kit gera exclusões locais do Git, sem ignorar
+workflows, formulários de issues ou configurações humanas em `.github`.
+Sem Git, uma proteção no `.gitignore` da raiz evita incluir os derivados
+quando o repositório for iniciado.
+
+Arquivos já rastreados exigem migração do índice: apenas saídas identificadas
+do kit podem deixar de ser rastreadas, preservando seus bytes no disco.
+Revise o plano e os conflitos em um projeto existente; use `--dry-run` antes
+de aplicar. Conteúdo humano não deve ser classificado como saída do gerador.
+
+## Atualizar e escolher agentes
+
+Use a versão desejada do pacote para executar `update`. A escolha salva
+continua válida; `agents` consulta e `agents codex,claude` altera a seleção.
+`agents all` habilita todos. As pastas compartilhadas permanecem quando
+necessárias para outro cliente, como `.agents` para Codex e Antigravity.
+
+Confira a simulação antes de atualizar um projeto existente. Arquivos
+gerenciados alterados geram conflito; use `--force` somente após revisar o
+backup e o conteúdo que será substituído. Preserve os dados locais, as
+configurações próprias e os commits do projeto.
+
+O [fluxo de trabalho](workflow.md) orienta a próxima etapa do projeto.
+Se houver erro, consulte [solução de problemas](troubleshooting.md).
+
+[Wiki](../README.md) · [Spec v0.0.6][spec]
+
+[bootstrap]: ../../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.md
+[spec]: ../specs/v0.0.6/SPEC.md

package/docs/guides/resources.md

@@ -0,0 +1,121 @@
+---
+description: Tipos de recursos, fontes compartilhadas e ciclo de manutenção.
+---
+
+# Recursos compartilhados
+
+[Documentação](../README.md) · [Fluxo](workflow.md) ·
+[Ferramentas e testes](tools-and-testing.md)
+
+Edite a origem em `.pbai4devs`. As pastas dos clientes contêm referências e
+metadados de descoberta; editar uma cópia gerada cria divergência.
+O catálogo local `catalog.json` permite encontrar recursos por tipo.
+O hub permanece completo mesmo com poucos clientes selecionados. Apenas os
+apontamentos necessários são gerados; consulte ou altere a seleção com `agents`
+na [CLI](cli.md). Pastas compartilhadas podem atender mais de um cliente.
+
+## Escolher o tipo certo
+
+Os caminhos abaixo são relativos a `.pbai4devs/`.
+
+| Tipo | Responsabilidade | Fonte |
+| --- | --- | --- |
+| Skill | Procedimento e decisões. | `skills/<grupo>/<nome>/SKILL.md` |
+| Regra | Convenção aplicada a um contexto. | `rules/<nome>/RULE.md` |
+| Comando | Entrada de um caso de uso. | `commands/<nome>/COMMAND.md` |
+| Agente | Papel, ferramentas e limites. | `agents/<nome>/AGENT.md` |
+| Modelo | Base a preencher. | `templates/<nome>/TEMPLATE.md` |
+| Tool | Configuração e entrada de uma CLI. | `tools/<nome>/TOOL.json` |
+| Script | Automação executável reutilizável. | `scripts/<nome>/SCRIPT.mjs` |
+
+Uma skill explica como decidir; um script executa a operação. Um comando
+encaminha a essas fontes, sem repetir suas instruções. Uma regra mantém uma
+convenção recorrente; um agente define quem revisa ou executa determinado papel.
+
+Modelos não são documentos aprovados do produto. Ferramentas usam um
+`SCRIPT.mjs` fino para delegar ao instalador comum; não precisam de cópias em
+cada cliente nem de outro instalador escrito do zero.
+
+## Criar ou evoluir
+
+Comece por [criar-recurso][recurso] para localizar um fluxo já existente.
+Use o criador específico quando souber o tipo:
+
+- [criar-skill][skill]: procedimento reutilizável.
+- [criar-regra][regra]: convenção com contexto e ativação definidos.
+- [criar-comando][comando]: caso de uso e encaminhamento.
+- [criar-agente][agente]: perfil especializado, como revisão em leitura.
+
+```text
+Use criar-skill para orientar a revisão de contratos de API.
+Confira se há algo equivalente, reúna dúvidas e proponha uma fonte concisa.
+Reutilize scripts e ferramentas existentes; não copie instruções nos clientes.
+```
+
+Defina finalidade, entrada, saída, pré-requisitos e o que comprova a conclusão.
+Reúna dúvidas antes de tomar decisões. Detalhes opcionais podem ficar em
+referências próximas; o arquivo principal deve continuar fácil de encontrar.
+
+## Metadados e formatos
+
+Markdown usa frontmatter YAML e um H1. Skills precisam de `name` e
+`description`. Regras definem `trigger`: `always_on`, `model_decision`, `glob`
+ou `manual`; `glob` exige `globs`, e decisão do modelo exige descrição útil.
+
+Metadados específicos de um cliente ficam em YAML ao lado da fonte, como
+`agents/revisor/claude.yaml`. O manifesto registra sua aplicação. Para evoluir
+os adaptadores do AgentDevKit, edite `templates/clients/ADAPTERS.json` no hub.
+Consulte a [compatibilidade][compatibilidade] antes de prometer descoberta.
+
+O agrupamento varia conforme o formato realmente suportado pelo cliente.
+Uma referência correta não prova que o aplicativo a carregou automaticamente.
+Não use symlinks para substituir os apontamentos Markdown.
+
+## Sincronizar e conferir
+
+Após criar, editar, renomear ou remover uma fonte, execute na raiz do projeto:
+
+```sh
+node .pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs
+node .pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs --check
+node .pbai4devs/scripts/verificar-recursos/SCRIPT.mjs
+```
+
+O primeiro comando atualiza apontamentos e índices; `--check` só compara.
+O manifesto instalado respeita os clientes escolhidos. Não o substitua por uma
+lista de todos para reparar recursos; altere a seleção pela CLI se necessário.
+Conflitos de conteúdo próprio exigem revisão. Quando a substituição for
+intencional, `--force` faz backup local antes de reparar caminhos gerenciados.
+Não apague pastas inteiras para contornar um conflito.
+
+O `--force` desse script pode limpar extras nas quatro áreas dos clientes,
+com backup. Ele não equivale a `agentdevkit sync --force`: a CLI controla sua
+própria lista de arquivos e preserva recursos locais não registrados por ela.
+Escolha a operação pelo escopo; não prometa preservação indistinta.
+
+Não edite ou versione `catalog.json`, `skills.json`, `rules.json` ou
+`agents.json`: são derivados locais. Configurações nativas e documentos
+do projeto não devem ser substituídos por cópias desses índices.
+
+## O que permanece fora dos espelhos
+
+Somente os quatro tipos agênticos têm apontamentos: skills, regras, comandos
+e agentes. Modelos, scripts, tools, testes, estado e guias ficam na origem.
+Downloads de tools e [skills externas][externas] permanecem locais e ignorados.
+
+O código de testes e as fixtures necessárias são fontes versionáveis.
+Resultados não são fontes. Consulte os [modelos de ignore][ignore] e confira
+com Git que a alteração não ocultou arquivos necessários ou incluiu artefatos.
+Mantenha um README conciso ao criar uma pasta de primeiro nível no hub.
+
+**[ Próximo passo ]** Escolha o criador, edite a fonte e use sync/check.
+Para provas reais, consulte [ferramentas e testes](tools-and-testing.md).
+
+[recurso]: ../../.pbai4devs/skills/projeto/criar-recurso/SKILL.md
+[skill]: ../../.pbai4devs/skills/projeto/criar-skill/SKILL.md
+[regra]: ../../.pbai4devs/skills/projeto/criar-regra/SKILL.md
+[comando]: ../../.pbai4devs/skills/projeto/criar-comando/SKILL.md
+[agente]: ../../.pbai4devs/skills/projeto/criar-agente/SKILL.md
+[compatibilidade]: ../../.pbai4devs/COMPATIBILIDADE.md
+[externas]: ../../.pbai4devs/external-skills/README.md
+[ignore]: ../../.pbai4devs/templates/gitignore/TEMPLATE.md