@ds9-solutions/mcp 0.1.0 → 0.3.0

package/content/skills/hex-pattern-dart/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: hex-pattern-dart
+description: Padrão hexagonal (ports & adapters) da DS9 para projetos Dart, independente de framework — organização por contexto em domain (models, ports, services) e adapter (controllers, dtos, repository), regra de dependência, camadas de erro fixas (BusinessException, ClientException, MiddlewareException), composição de dependências na borda e resultado tipado com TaskEither. Use ao criar, revisar ou refatorar módulos/features, definir camadas, ports, services, adapters ou repositórios em Dart, ou quando o usuário pedir "arquitetura hexagonal", "ports and adapters" ou "organização de novo contexto".
+---
+
+# Padrão Hexagonal DS9 para Dart (`hex-pattern-dart`)
+
+Base arquitetural dos projetos Dart da DS9. Isola a regra de negócio de protocolo, banco e framework, deixando o núcleo testável e substituível. Siga junto com a skill `dart` (nomenclatura, `///`, OOP). Para um framework específico, use também a skill dele (ex.: `dart-frog` aplica este padrão em APIs HTTP). Esta skill não depende de nenhum framework nem de projeto específico. **Escopo:** back-end e pacotes Dart de domínio. Apps Flutter seguem a skill `flutter` (organização própria em components/providers/services); dela aproveite só os princípios (regra de dependência, ports, `TaskEither`).
+
+Os blocos de código nos arquivos complementares são **pseudocódigo** ilustrativo: adapte à sintaxe e às versões do projeto.
+
+## 1. Regras inegociáveis
+
+1. **Regra de dependência:** `adapter → domain`. O `domain` nunca importa `adapter`, framework, driver de banco nem tipos de protocolo (request/response).
+2. **Resultado tipado:** operações que podem falhar retornam `TaskEither<Exception, T>` (`fpdart`), criado com `TaskEither.tryCatch`. Não lance exceção através das camadas. Se `fpdart` não estiver no `pubspec.yaml`, informe que ele é obrigatório para seguir o padrão DS9 e peça autorização para instalar.
+3. **Composição na borda:** dependências são montadas em um único ponto (composition root) e injetadas por construtor. Nunca instancie service, repositório ou controller dentro da rota/handler.
+4. **Camadas de erro fixas:** `BusinessException` (domínio), `ClientException` (resposta ao cliente) e `MiddlewareException` (borda). Erro 5xx nunca expõe mensagem interna.
+5. **Sem regra de negócio no adapter:** controller traduz protocolo ↔ chamada do service; repositório só persiste e mapeia.
+6. **Projeto existente:** preserve a estrutura atual; aplique o padrão no código novo e no que for pedido, sem refatorar o restante.
+
+## 2. Estrutura por contexto
+
+```text
+lib/
+├── <contexto>/                  # bounded context (ex.: orders)
+│   ├── domain/
+│   │   ├── models/              # entidades e value objects (invariantes)
+│   │   ├── ports/               # contratos que o domínio precisa (saída)
+│   │   └── services/            # casos de uso; dependem só de ports e models
+│   └── adapter/
+│       ├── controllers/         # entrada: traduz protocolo → service → resposta
+│       ├── dtos/                # contratos de entrada/saída + validação
+│       └── repository/          # saída: implementa ports (persistência, clients)
+└── common/                      # exceções, tipos e utilitários compartilhados
+```
+
+- Imports **relativos** dentro de `lib/`; o composition root e os testes usam `package:`.
+- Um contexto não importa `domain`/`adapter` de outro. Comunique-se por port ou por tipos em `common/`.
+
+## 3. Responsabilidades
+
+| Peça | Faz | Não faz |
+|---|---|---|
+| `model` | Invariantes, comportamento do negócio | I/O, serialização de protocolo |
+| `port` | Declara o contrato (`abstract interface class`) | Implementação |
+| `service` | Orquestra ports, aplica regra e autorização de recurso, retorna `TaskEither` | Conhece HTTP, SQL, DTO |
+| `controller` | Valida DTO, chama service, mapeia erro de negócio → `ClientException` | Regra de negócio |
+| `dto` | Entrada/saída do protocolo, `fromJson`/`toJson` | Ser usado no domínio |
+| `repository` | Implementa port, mapeia modelo ↔ persistência | Regra de negócio |
+
+## 4. Erros por camada
+
+- Repositório/service: `TaskEither.tryCatch` converte falha em `BusinessException` (com `domainName`, `statusCode`, mensagem segura, erro original e stack).
+- Controller: converte `BusinessException` em `ClientException` (mensagem segura; 5xx genérico).
+- Borda (middleware/handler): converte `ClientException`/`MiddlewareException` em resposta de protocolo.
+
+## 5. Checklist rápido
+
+- [ ] O `domain` não importa nada de `adapter` nem de framework?
+- [ ] Todo retorno que pode falhar é `TaskEither` via `tryCatch`?
+- [ ] Dependências vêm do composition root por construtor?
+- [ ] Os erros usam as 3 camadas e 5xx não vaza detalhe?
+- [ ] Controller sem regra de negócio; repositório sem regra de negócio?
+- [ ] DTO fica fora do `domain`?
+- [ ] Existem testes do service com fakes das ports?
+
+## 6. Arquivos complementares (leitura sob demanda)
+
+Use `list_skill_files` e `get_skill_file` com `skill: hex-pattern-dart`.
+
+| Dúvida | Arquivo |
+|---|---|
+| Camadas e regra de dependência | `references/layers-and-dependency-rule.md` |
+| Como desenhar ports e adapters | `references/ports-and-adapters.md` |
+| Camadas de erro | `references/error-layers.md` |
+| Injeção e composition root | `references/dependency-injection.md` |
+| Persistência agnóstica e mapper | `references/persistence.md` |
+| Estratégia de testes | `references/testing.md` |
+| Erros comuns | `references/anti-patterns.md` |
+| Checklist completo de review | `references/checklist.md` |
+| Árvore de pastas de exemplo | `examples/structure-tree.md` |
+| Port (`<Papel>Port`), service e adapters (pseudocódigo) | `examples/port.md`, `examples/service.md`, `examples/adapter-in.md`, `examples/adapter-out.md` |
+| Hierarquia de exceções | `examples/errors.md` |

package/content/skills/hex-pattern-dart/examples/adapter-in.md

@@ -0,0 +1,24 @@
+# Adapter de entrada — controller (pseudocódigo)
+
+```text
+// adapter/controllers/order_controller.dart
+/// Traduz o protocolo para o service e o resultado para a resposta.
+class OrderController
+  final OrderService _service
+
+  OrderController(this._service)
+
+  Task<Response> getById(Context context, String id)
+    return _service.getById(id, context.requesterId)
+      .mapLeft(toClientException)                  // BusinessException -> ClientException
+      .match(
+        (client) => Response(status: client.statusCode, body: client.message),
+        (order)  => Response.ok(OrderResponse.from(order)),
+      )
+
+toClientException(BusinessException e)
+  safe = e.statusCode >= 500 ? "Erro interno" : e.message   // 5xx genérico
+  return ClientException(statusCode: e.statusCode, message: safe)
+```
+
+Pontos-chave: sem regra de negócio; service recebido por construtor; erro 5xx sem detalhe interno; o log guarda `e.error` e `e.stackTrace`.

package/content/skills/hex-pattern-dart/examples/adapter-out.md

@@ -0,0 +1,20 @@
+# Adapter de saída — repository (pseudocódigo)
+
+```text
+// adapter/repository/order_repository.dart
+/// Implementa OrderRepositoryPort sobre a tecnologia de persistência do projeto.
+class OrderRepository implements OrderRepositoryPort
+  final DataSource _source              // abstração do acesso físico
+
+  OrderRepository(this._source)
+
+  TaskEither<BusinessException, Order> findById(String id)
+    return TaskEither.tryCatch(
+      () async => OrderMapper.toDomain(await _source.read(id)),
+      (error, stack) => BusinessException(
+        domainName: "orders", statusCode: 500,
+        message: "Falha ao consultar pedido", error: error, stackTrace: stack),
+    )
+```
+
+Pontos-chave: toda chamada de I/O em `tryCatch`; mapper converte persistência → domínio; a falha vira `BusinessException` com mensagem segura.

package/content/skills/hex-pattern-dart/examples/errors.md

@@ -0,0 +1,25 @@
+# Hierarquia de exceções (pseudocódigo)
+
+```text
+// common/exceptions
+/// Falha de regra de negócio ou de infraestrutura vista pelo domínio.
+class BusinessException implements Exception
+  String domainName
+  int    statusCode
+  String message            // segura para o cliente
+  Object? error             // causa original (somente log)
+  StackTrace? stackTrace
+
+/// Falha pronta para ser devolvida ao cliente.
+class ClientException implements Exception
+  int    statusCode
+  String message
+
+/// Falha da borda (autenticação, parsing, composição).
+class MiddlewareException implements Exception
+  int    statusCode
+  String message
+  StackTrace? stackTrace
+```
+
+Regra: `BusinessException` → (controller) → `ClientException`. A borda converte qualquer uma das duas, ou `MiddlewareException`, em resposta de protocolo.

package/content/skills/hex-pattern-dart/examples/port.md

@@ -0,0 +1,11 @@
+# Port (pseudocódigo)
+
+```text
+// domain/ports/order_repository.dart
+/// Contrato de persistência de pedidos exigido pelo domínio.
+abstract interface class OrderRepositoryPort
+  TaskEither<BusinessException, Order>  findById(String id)
+  TaskEither<BusinessException, Unit>   save(Order order)
+```
+
+Pontos-chave: só depende de `Order` e de `BusinessException`; nenhuma menção a banco, SQL ou protocolo.

package/content/skills/hex-pattern-dart/examples/service.md

@@ -0,0 +1,20 @@
+# Service (pseudocódigo)
+
+```text
+// domain/services/order_service.dart
+/// Casos de uso de pedidos.
+class OrderService
+  final OrderRepositoryPort _repository          // recebido por construtor
+
+  OrderService(this._repository)
+
+  TaskEither<BusinessException, Order> getById(String id, String requesterId)
+    return _repository.findById(id).flatMap((order) =>
+      order.belongsTo(requesterId)                       // autorização de recurso aqui
+        ? TaskEither.right(order)
+        : TaskEither.left(BusinessException(
+            domainName: "orders", statusCode: 403, message: "Acesso negado"))
+    )
+```
+
+Pontos-chave: depende só da port; sem DTO, sem protocolo; regra e autorização no service; retorno `TaskEither`.

package/content/skills/hex-pattern-dart/examples/structure-tree.md

@@ -0,0 +1,28 @@
+# Árvore de pastas (exemplo)
+
+```text
+lib/
+├── common/
+│   ├── exceptions/
+│   │   ├── business_exception.dart
+│   │   ├── client_exception.dart
+│   │   └── middleware_exception.dart
+│   └── error_response.dart
+└── orders/
+    ├── domain/
+    │   ├── models/order.dart
+    │   ├── ports/order_repository.dart
+    │   └── services/order_service.dart
+    └── adapter/
+        ├── controllers/order_controller.dart
+        ├── dtos/create_order_dto.dart
+        └── repository/
+            ├── order_mapper.dart
+            └── order_repository.dart
+test/
+└── orders/
+    ├── domain/services/order_service_test.dart
+    └── adapter/controllers/order_controller_test.dart
+```
+
+Adicione um novo contexto criando a mesma árvore sob `lib/<contexto>/`.

package/content/skills/hex-pattern-dart/references/anti-patterns.md

@@ -0,0 +1,16 @@
+# Anti-padrões
+
+| Anti-padrão | Por que é problema | Correção |
+|---|---|---|
+| Instanciar controller/service dentro da rota | Impede troca e teste; acopla borda ao concreto | Injetar pelo composition root |
+| Regra de negócio em middleware/controller | Some em testes de domínio; duplica em outros adapters | Mover para o service |
+| Ler segmento de path por posição para autorizar | Frágil e fácil de burlar | Autorizar no service com o identificador do recurso |
+| `error.toString()` na resposta | Vaza detalhe interno ao cliente | Mensagem segura em `ClientException` |
+| `catch (_) {}` genérico | Engole a causa e o stack | `TaskEither.tryCatch` + `BusinessException` |
+| DTO usado no `domain` | Acopla negócio ao protocolo | DTO só em `adapter/dtos` |
+| Model de persistência exposto ao `domain` | Acopla negócio ao banco | Mapper no repositório |
+| Service que acessa banco/HTTP direto | Quebra a regra de dependência | Criar port e adapter |
+| Service "faz tudo" (god service) | Difícil de testar e evoluir | Um service por caso de uso/agregado |
+| Contexto importando `domain` de outro | Acoplamento entre contextos | Port ou tipo em `common/` |
+| Exceção lançada entre camadas | Fluxo de erro invisível no tipo | Retornar `TaskEither` |
+| `null` como "não encontrado" | Ambíguo | `Option`/`left` explícito |

package/content/skills/hex-pattern-dart/references/checklist.md

@@ -0,0 +1,34 @@
+# Checklist de review — hexagonal DS9 (Dart)
+
+## Estrutura
+- [ ] Organização por contexto com `domain/{models,ports,services}` e `adapter/{controllers,dtos,repository}`.
+- [ ] Imports relativos dentro de `lib/`.
+- [ ] Nenhum contexto importa `domain`/`adapter` de outro.
+
+## Dependência
+- [ ] `domain` sem import de `adapter`, framework, driver ou tipos de protocolo.
+- [ ] Ports como `abstract interface class` em `domain/ports`.
+- [ ] Repositórios implementam ports e vivem em `adapter/repository`.
+
+## Erros
+- [ ] `TaskEither` + `TaskEither.tryCatch` em toda operação falível.
+- [ ] `BusinessException` → `ClientException` → `MiddlewareException`.
+- [ ] 5xx com mensagem genérica; sem `toString()`/stack no cliente.
+- [ ] Sem `catch (_)` genérico nem exceção lançada entre camadas.
+
+## Composição
+- [ ] Dependências por construtor e montadas no composition root.
+- [ ] Nada instanciado dentro de rota/handler/controller.
+- [ ] `fpdart` presente no `pubspec.yaml` (ou usuário informado).
+
+## Responsabilidades
+- [ ] Controller sem regra de negócio; repositório sem regra de negócio.
+- [ ] Autorização de recurso no service.
+- [ ] DTO fora do `domain`; mapper entre persistência e model.
+
+## Testes
+- [ ] Service testado com fakes das ports (sucesso e cada erro).
+- [ ] `test/` espelha `lib/`.
+
+## Dart
+- [ ] Regras da skill `dart`: nomenclatura, `///` em APIs públicas, OOP, null safety.

package/content/skills/hex-pattern-dart/references/dependency-injection.md

@@ -0,0 +1,32 @@
+# Injeção de dependência e composition root
+
+## Princípio
+
+Existe **um** lugar onde o grafo de dependências é montado (composition root). O restante do código recebe dependências por construtor e só conhece abstrações (ports).
+
+## Regras
+
+1. Dependências entram por construtor, como `final` e por interface.
+2. Nunca instancie service, repositório ou controller dentro de rota/handler/controller.
+3. O composition root escolhe a implementação concreta de cada port.
+4. Ordem de montagem: infraestrutura → repositórios → services → controllers.
+5. Reaproveite instâncias (cache/singleton no composition root) quando o recurso for caro (conexão, cliente HTTP).
+6. Em frameworks com middleware ou provider, use o mecanismo do framework como composition root (ver a skill do framework, ex.: `dart-frog`).
+7. Em testes, o composition root é substituído por fakes das ports.
+
+## Pseudocódigo
+
+```text
+compose():
+  dataSource  = ConcreteDataSource(config)
+  repository  = OrderRepository(dataSource)
+  service     = OrderService(repository)
+  controller  = OrderController(service)
+  return controller
+```
+
+## Evite
+
+- Localizador global (`ServiceLocator.get()`) dentro do `domain`.
+- Dependência criada com `new`/construtor direto dentro do método que a usa.
+- Ler configuração/ambiente fora do composition root.

package/content/skills/hex-pattern-dart/references/error-layers.md

@@ -0,0 +1,27 @@
+# Camadas de erro
+
+Os nomes das camadas são fixos em todo projeto DS9.
+
+| Camada | Tipo | Onde nasce | Campos | Quem consome |
+|---|---|---|---|---|
+| Negócio | `BusinessException` | service / repository | `domainName`, `statusCode`, `message` (segura), `error`, `stackTrace` | controller |
+| Cliente | `ClientException` | controller | `statusCode`, `message` | borda (handler/middleware) |
+| Borda | `MiddlewareException` | middleware / handler | `statusCode`, `message`, `stackTrace?` | resposta final |
+
+## Regras
+
+1. Falhas esperadas viajam como valor: `TaskEither.left(BusinessException(...))`.
+2. `tryCatch` converte qualquer exceção inesperada em `BusinessException`, preservando `error` e `stackTrace` para log.
+3. Mensagem para o cliente é sempre segura. Para 5xx use texto genérico; detalhes ficam no log.
+4. Nunca devolva `error.toString()` nem stack ao cliente.
+5. Evite `catch (_)` genérico sem converter para a camada correta.
+6. `domainName` identifica o contexto de origem e ajuda a rastrear logs.
+
+## Fluxo
+
+```text
+repository.tryCatch(falha) ──► BusinessException
+service repassa / enriquece ──► BusinessException
+controller.mapLeft ──────────► ClientException (5xx genérico)
+borda.match ─────────────────► resposta de protocolo
+```

package/content/skills/hex-pattern-dart/references/layers-and-dependency-rule.md

@@ -0,0 +1,29 @@
+# Camadas e regra de dependência
+
+## Sentido das dependências
+
+```text
+adapter/controllers ─┐
+adapter/dtos ────────┼──► domain/services ──► domain/ports ◄── adapter/repository
+                     │          │
+                     └──────────┴──► domain/models
+```
+
+- `domain` conhece apenas `domain` e `common`.
+- `adapter` conhece `domain` e `common`.
+- O `domain` declara a port; o `adapter/repository` a implementa (inversão de dependência).
+
+## O que pertence a cada camada
+
+- **models:** entidades, value objects, regras que valem em qualquer protocolo ou banco.
+- **ports:** contratos de saída (persistência, mensageria, serviços externos). Nomeie `<Papel>Port`: `OrderRepositoryPort`, `PaymentGatewayPort`.
+- **services:** um caso de uso por método público. Aplicam regra e autorização de recurso.
+- **controllers/dtos:** tudo que depende de protocolo (HTTP, fila, CLI).
+- **repository:** tudo que depende de infraestrutura (banco, API externa).
+
+## Sinais de violação
+
+- `import` de pacote de framework, driver ou `adapter` dentro de `domain/`.
+- DTO ou tipo de request/response aparecendo em assinatura de service.
+- Service que monta SQL, chama HTTP ou lê variável de ambiente.
+- Controller com `if` de regra de negócio.

package/content/skills/hex-pattern-dart/references/persistence.md

@@ -0,0 +1,23 @@
+# Persistência agnóstica
+
+O padrão não prescreve banco nem ORM. Para a tecnologia do projeto, consulte a skill correspondente via `list_skills`/`recommend_for_task` e preserve o que já existe.
+
+## Contrato
+
+- O `domain` declara a port (`OrderRepositoryPort`).
+- O `adapter/repository` implementa a port usando a tecnologia do projeto.
+- Opcionalmente, o repositório delega a um `DataSource` (abstração do acesso físico), facilitando trocar ou simular o banco.
+
+## Mapper
+
+- Modelo de persistência (linha/documento) e model do domínio são tipos distintos.
+- Um mapper converte nos dois sentidos e vive no `adapter/repository`.
+- O `domain` nunca importa o tipo de persistência.
+
+## Regras
+
+1. Toda chamada de I/O dentro de `TaskEither.tryCatch`.
+2. Falha vira `BusinessException` com mensagem segura.
+3. "Não encontrado" é resultado explícito (`left` com status adequado ou `Option`), nunca `null` implícito.
+4. Transação: abra no adapter; o service expõe a operação de negócio completa, sem conhecer a transação.
+5. Migrations seguem a skill de persistência do projeto e não alteram estrutura existente sem pedido.

package/content/skills/hex-pattern-dart/references/ports-and-adapters.md

@@ -0,0 +1,33 @@
+# Ports e adapters
+
+## Ports (saída)
+
+- Declare como `abstract interface class` dentro de `domain/ports/`.
+- Expresse a necessidade do domínio, não a tecnologia: `save(order)`, não `insertRow(map)`.
+- Assinaturas usam apenas models e tipos de `common/`.
+- Toda operação que pode falhar retorna `TaskEither<BusinessException, T>`.
+
+```text
+abstract interface class OrderRepositoryPort
+  TaskEither<BusinessException, Order>  findById(String id)
+  TaskEither<BusinessException, Unit>   save(Order order)
+```
+
+## Adapters de entrada (controllers)
+
+- Recebem o contexto do protocolo (request) a cada chamada de método.
+- Validam o DTO, chamam o service e mapeiam o resultado para resposta.
+- Mapeiam `BusinessException` → `ClientException`; 5xx com mensagem genérica.
+- Recebem o service por construtor; nunca o criam.
+
+## Adapters de saída (repository)
+
+- Implementam a port e escondem o detalhe de persistência.
+- Mapeiam modelo de persistência ↔ model do domínio (mapper dedicado).
+- Envolvem cada chamada externa em `TaskEither.tryCatch` e convertem a falha em `BusinessException`.
+
+## Nomenclatura
+
+- Arquivos `snake_case`; classes `UpperCamelCase`.
+- Port: `<Papel>Port` (`OrderRepositoryPort`). Implementação: nome do papel sem sufixo (`OrderRepository`), sem prefixo `I` e sem sufixo `Impl`.
+- DTO: `<Acao><Entidade>Dto` / `<Entidade>Response`.

package/content/skills/hex-pattern-dart/references/testing.md

@@ -0,0 +1,30 @@
+# Testes na arquitetura hexagonal
+
+## Estratégia
+
+| Alvo | Como testar | Dublês |
+|---|---|---|
+| `model` | Unitário puro | Nenhum |
+| `service` | Unitário com ports falsas | Fakes/mocks das ports |
+| `controller` | Unitário com service falso e contexto de protocolo simulado | Service falso |
+| `repository` | Integração com a tecnologia real ou em memória | Opcional |
+| Borda (rota/handler) | Teste de contrato: status, corpo e método não suportado | Composition root de teste |
+
+## Regras
+
+1. A árvore de `test/` espelha `lib/`.
+2. Teste o caminho feliz **e** cada `left` (erro de negócio, erro inesperado, 5xx genérico).
+3. Verifique que o 5xx não vaza mensagem interna.
+4. Para `TaskEither`, execute com `.run()` e inspecione o `Either` resultante.
+5. Prefira fakes simples a mocks com muitas expectativas quando a port for pequena.
+6. Nenhum teste de `domain` pode precisar de rede, banco ou framework.
+7. Nome: `<comportamento> quando <condição>`.
+
+## Pseudocódigo
+
+```text
+test "retorna Right quando o pedido existe":
+  repo = FakeOrderRepository(with: order)
+  result = await OrderService(repo).getById("1").run()
+  expect(result.isRight)
+```

package/content/skills/mysql/SKILL.md

@@ -5,7 +5,7 @@ description: Diretrizes de modelagem, indexação, migrations, performance e seg
 
 # MySQL — Diretrizes DS9
 
-Convenções obrigatórias para schema, queries e migrations em MySQL (compatível com MariaDB), usadas em conjunto com a skill `typeorm` para a camada de persistência em projetos NestJS/hexagonal.
+Convenções obrigatórias para schema, queries e migrations em MySQL (compatível com MariaDB), usadas com a camada de persistência do projeto.
 
 ## Engine e charset
 
@@ -52,7 +52,7 @@ deleted_at DATETIME(3) NULL          -- se o domínio usa soft delete
 
 ## Migrations
 
-- Toda alteração de schema é uma migration versionada (via TypeORM migrations — ver skill `typeorm`), nunca alteração manual direto no banco de produção.
+- Toda alteração de schema é uma migration versionada (via o mecanismo de migrations do projeto), nunca alteração manual direto no banco de produção.
 - Migrations são **imutáveis** após merge/deploy: para corrigir, crie uma nova migration (nunca edite uma já aplicada em outro ambiente).
 - Toda migration precisa de `up` e `down` reversível. Se o `down` não for possível com segurança (ex.: `DROP COLUMN`), documente explicitamente no corpo da migration.
 - Alterações em tabelas grandes (`ADD COLUMN`, `ADD INDEX`) em produção devem considerar lock de tabela: preferir `ALGORITHM=INPLACE, LOCK=NONE` quando suportado, e avaliar janela de manutenção para tabelas muito grandes.
@@ -66,7 +66,7 @@ deleted_at DATETIME(3) NULL          -- se o domínio usa soft delete
 
 ## Queries
 
-- Nunca concatene valores de usuário diretamente em SQL — sempre use *prepared statements*/query builder parametrizado (via TypeORM). Isso é mandatório contra SQL Injection.
+- Nunca concatene valores de usuário diretamente em SQL — sempre use *prepared statements*/query builder parametrizado (via a biblioteca de acesso a dados do projeto). Isso é mandatório contra SQL Injection.
 - Evite `SELECT *`; liste as colunas necessárias, especialmente em tabelas largas.
 - Pagine toda listagem (`LIMIT`/`OFFSET` ou keyset pagination para datasets grandes); nunca retorne uma tabela inteira sem limite.
 - Prefira keyset pagination (`WHERE id > :lastId ORDER BY id LIMIT :n`) a `OFFSET` alto em tabelas grandes (OFFSET grande é O(n)).

package/content/skills/typescript/SKILL.md

@@ -5,7 +5,7 @@ description: Convenções de TypeScript da DS9 — tipagem estrita, modelagem de
 
 # TypeScript — Diretrizes DS9
 
-Convenções de código TypeScript aplicáveis a qualquer projeto da empresa, incluindo os que usam NestJS (skill `nestjs`) e arquitetura hexagonal (skill `hexagonal`).
+Convenções de código TypeScript aplicáveis a qualquer projeto da empresa, incluindo os que seguem arquitetura hexagonal em geral.
 
 ## Configuração do compilador
 
@@ -31,7 +31,7 @@ function handle(payload: OrderPayload) { return payload.items.map((i) => i.id);
 
 ## Modelagem de domínio
 
-- Use *value objects* para conceitos com regras próprias (ex.: `Email`, `Money`), em vez de `string`/`number` soltos, quando o projeto já segue esse padrão (ver skill `hexagonal`).
+- Use *value objects* para conceitos com regras próprias (ex.: `Email`, `Money`), em vez de `string`/`number` soltos, quando o projeto já segue esse padrão.
 - Invariantes de negócio são validadas no construtor/factory da entidade (`Order.create(...)`), lançando erro de domínio em vez de permitir estado inválido existir.
 - Prefira classes/funções imutáveis (métodos retornam uma nova instância) para entidades de domínio sensíveis a concorrência, salvo quando o projeto adota mutação controlada por padrão.
 
@@ -44,7 +44,7 @@ function handle(payload: OrderPayload) { return payload.items.map((i) => i.id);
 ## Imports e organização de módulos
 
 - Imports absolutos/com alias (`@app/domain/...`) para cruzar camadas, imports relativos (`./`, `../`) dentro do mesmo módulo/camada — configurar via `paths` no `tsconfig.json`.
-- Nunca import circular entre módulos; se ocorrer, é sinal de fronteira de módulo mal definida (revisar com a skill `hexagonal`).
+- Nunca import circular entre módulos; se ocorrer, é sinal de fronteira de módulo mal definida (revisar a organização dos módulos).
 - Um export principal por arquivo quando possível (facilita navegação e testes); evite arquivos "barril" (`index.ts`) gigantes que reexportam dezenas de símbolos sem necessidade.
 
 ## Nulidade e valores opcionais
@@ -57,7 +57,7 @@ function handle(payload: OrderPayload) { return payload.items.map((i) => i.id);
 - Classes/interfaces/tipos: `PascalCase`. Variáveis/funções: `camelCase`. Constantes verdadeiramente globais/imutáveis: `UPPER_SNAKE_CASE`.
 - Nomes de função descrevem a ação (`calculateTotal`, não `total` ou `doIt`); booleanos começam com `is`/`has`/`should` (`isValid`, `hasDiscount`).
 - Evite abreviações não óbvias (`qty` ok se for convenção do domínio; `tmp`, `data2` não).
-- Nome de **arquivo**: `kebab-case`, com sufixo que indica o papel do arquivo quando aplicável (`order-repository.port.ts`, `create-order.use-case.ts`, `typeorm-order.repository.ts`, `order.entity.ts`, `order.controller.ts`, `order.module.ts`). Arquivo de teste usa o mesmo nome base + `.spec.ts`/`.e2e-spec.ts` (ver skill `jest-testing`).
+- Nome de **arquivo**: `kebab-case`, com sufixo que indica o papel do arquivo quando aplicável (`order-repository.port.ts`, `create-order.use-case.ts`, `order.repository.ts`, `order.entity.ts`, `order.controller.ts`, `order.module.ts`). Arquivo de teste usa o mesmo nome base + `.spec.ts`/`.e2e-spec.ts` (seguindo a convenção de testes do projeto).
 
 ## Checklist ao escrever/revisar código TypeScript
 

package/dist/src/content.js

@@ -9,6 +9,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse as parseYaml } from "yaml";
+import { scanSkillFiles } from "./skill-files.js";
 // Frontmatter = bloco YAML entre dois `---` no topo do arquivo. Aceita \r\n porque os arquivos
 // podem ter sido salvos no Windows.
 const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
@@ -50,9 +51,12 @@ export function resolveContentRoot() {
  * Skill = `skills/<pasta>/SKILL.md` (id = nome da pasta).
  * Agente = `agents/<nome>.agent.md` (id = nome do arquivo; estrutura plana, sem subpastas).
  */
-export function loadEntries(root = resolveContentRoot()) {
+export function loadEntries(root = resolveContentRoot(), 
+// Por padrão os avisos vão para stderr; testes podem injetar um coletor.
+onWarning = (w) => console.error(`[ds9-mcp] aviso: ${w}`)) {
     const entries = [];
     const warnings = [];
+    const fileWarnings = [];
     const skillsDir = join(root, "skills");
     for (const dirent of readdirSync(skillsDir, { withFileTypes: true })) {
         const file = join(skillsDir, dirent.name, "SKILL.md");
@@ -71,7 +75,10 @@ export function loadEntries(root = resolveContentRoot()) {
             name: String(data.name ?? dirent.name),
             description: String(data.description ?? ""),
             body,
+            files: scanSkillFiles(join(skillsDir, dirent.name), fileWarnings),
         });
+        for (const w of fileWarnings.splice(0))
+            warnings.push(`skill "${dirent.name}": ${w}`);
     }
     const agentsDir = join(root, "agents");
     if (existsSync(agentsDir)) {
@@ -87,12 +94,13 @@ export function loadEntries(root = resolveContentRoot()) {
                 name: String(data.name ?? id),
                 description: String(data.description ?? ""),
                 body,
+                files: [],
             });
         }
     }
     // stderr, nunca stdout: no transporte stdio o stdout é o canal do protocolo MCP, e qualquer
     // texto extra nele corromperia a comunicação com a IDE.
     for (const w of warnings)
-        console.error(`[ds9-mcp] aviso: ${w}`);
+        onWarning(w);
     return entries;
 }

package/dist/src/init.js

@@ -78,6 +78,7 @@ Antes de implementar, revisar ou testar código:
 1. Chame a tool \`recommend_for_task\` com a descrição da tarefa.
 2. Leia as skills e agentes recomendados com \`get_skill\` / \`get_agent\` e siga as diretrizes.
 3. Use \`search_guidelines\` para dúvidas pontuais.
+4. Se a skill tiver arquivos complementares, leia-os com \`list_skill_files\` / \`get_skill_file\`.
 ${BLOCK_END}`;
 /**
  * Insere o bloco DS9 num AGENTS.md ou, se já existir, substitui apenas o trecho entre os

package/dist/src/search.js

@@ -68,18 +68,26 @@ export function searchBodies(entries, query, limit = 8) {
         return [];
     const hits = [];
     for (const entry of entries) {
-        entry.body.split(/\r?\n/).forEach((line, i) => {
-            const score = count(line, tokens);
-            if (score > 0 && line.trim()) {
-                hits.push({
-                    kind: entry.kind,
-                    id: entry.id,
-                    line: i + 1,
-                    text: line.trim().slice(0, 300), // limita linhas gigantes
-                    score,
-                });
-            }
-        });
+        // Corpo principal + arquivos complementares (exemplos, referências) da skill.
+        const sources = [
+            { file: undefined, content: entry.body },
+            ...entry.files.map((f) => ({ file: f.path, content: f.text })),
+        ];
+        for (const src of sources) {
+            src.content.split(/\r?\n/).forEach((line, i) => {
+                const score = count(line, tokens);
+                if (score > 0 && line.trim()) {
+                    hits.push({
+                        kind: entry.kind,
+                        id: entry.id,
+                        ...(src.file ? { file: src.file } : {}),
+                        line: i + 1,
+                        text: line.trim().slice(0, 300), // limita linhas gigantes
+                        score,
+                    });
+                }
+            });
+        }
     }
     return hits
         .sort((a, b) => b.score - a.score)