wegho-agentes 7.0.4 → 7.0.6

package/.agent/agents/documentation-writer.md

@@ -3,7 +3,7 @@ name: documentation-writer
 description: Expert in technical documentation. Use ONLY when user explicitly requests documentation (README, API docs, changelog). DO NOT auto-invoke during normal development.
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
-skills: wegho-global-rules, clean-code, documentation-templates
+skills: wegho-global-rules, clean-code, documentation-templates, file-doc-sync
 ---
 
 # Documentation Writer

package/.agent/agents/orchestrator.md

@@ -3,7 +3,7 @@ name: orchestrator
 description: Multi-agent coordination and task orchestration. Use when a task requires multiple perspectives, parallel analysis, or coordinated execution across different domains. Invoke this agent for complex tasks that benefit from security, backend, frontend, testing, and DevOps expertise combined.
 tools: Read, Grep, Glob, Bash, Write, Edit, Agent
 model: inherit
-skills: wegho-global-rules, clean-code, parallel-agents, behavioral-modes, plan-writing, brainstorming, architecture, lint-and-validate, powershell-windows, bash-linux
+skills: wegho-global-rules, clean-code, parallel-agents, behavioral-modes, plan-writing, brainstorming, architecture, lint-and-validate, powershell-windows, bash-linux, file-doc-sync
 ---
 
 # Orchestrator - Native Multi-Agent Coordination

package/.agent/mcp_config.md

@@ -0,0 +1,30 @@
+# mcp_config.json
+
+> Arquivo fonte: `.agent/mcp_config.json`
+
+## O que este arquivo faz
+Este arquivo concentra configuração ou metadados usados pelo sistema para definir comportamento, integração ou execução.
+
+## Principais Responsabilidades
+- Declarar dados ou configuração consumidos em tempo de execução.
+- Servir como ponto de manutenção para esta parte da funcionalidade.
+
+## Como funciona
+1. Carrega definições locais e dependências necessárias.
+2. Fornece valores de configuração para leitura por outros módulos ou ferramentas.
+3. Entrega a saída esperada para os consumidores diretos deste arquivo.
+
+## Dependências
+- Nenhuma dependência explícita identificada pelo gerador.
+
+## Integrações
+- Não há integração externa explícita identificada neste arquivo.
+
+## Segurança
+- Não há controle de segurança explícito neste arquivo; a proteção depende das camadas consumidoras e das regras globais do sistema.
+
+## Impacto da Remoção
+Sem este arquivo, o sistema perde configuração necessária e pode falhar na inicialização, na integração ou na execução esperada.
+
+## Resumo Técnico
+Arquivo técnico de configuração, usado para controlar o comportamento do sistema e suas integrações.

package/.agent/skills/database-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: database-design
-description: Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.
+description: Database design, data modeling, governance, and query-organization skill. Use for schema design, indexing, migrations, relational modeling, SQL quality, metadata organization, data lineage thinking, dbt-style modeling, and governance-oriented data structure decisions.
 allowed-tools: Read, Write, Edit, Glob, Grep
 ---
 
@@ -20,6 +20,19 @@ allowed-tools: Read, Write, Edit, Glob, Grep
 | `indexing.md` | Index types, composite indexes | Performance tuning |
 | `optimization.md` | N+1, EXPLAIN ANALYZE | Query optimization |
 | `migrations.md` | Safe migrations, serverless DBs | Schema changes |
+| `github-benchmarks.md` | Current GitHub-aligned references for data organization | Governance, metadata, SQL quality |
+| `supabase-security-egress.md` | Supabase security, egress, and cost controls | Supabase/PostgreSQL systems |
+
+## GitHub benchmark sources
+
+Use these repositories as the main external benchmark for modern data organization:
+- `supabase/supabase`
+- `supabase/agent-skills`
+- `datahub-project/datahub`
+- `open-metadata/OpenMetadata`
+- `open-metadata/OpenMetadataStandards`
+- `dbt-labs/dbt-core`
+- `sqlfluff/sqlfluff`
 
 ---
 
@@ -28,6 +41,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep
 - ASK user for database preferences when unclear
 - Choose database/ORM based on CONTEXT
 - Don't default to PostgreSQL for everything
+- Model data ownership, discoverability, and governance early
+- Treat metadata, lineage, and naming consistency as first-class design concerns
 
 ---
 
@@ -40,6 +55,9 @@ Before designing schema:
 - [ ] Considered deployment environment?
 - [ ] Planned index strategy?
 - [ ] Defined relationship types?
+- [ ] Defined ownership and naming conventions?
+- [ ] Considered lineage / downstream consumers?
+- [ ] Considered retention, privacy, and minimization rules?
 
 ---
 
@@ -50,3 +68,36 @@ Before designing schema:
 ❌ Use SELECT * in production
 ❌ Store JSON when structured data is better
 ❌ Ignore N+1 queries
+❌ Model tables without ownership, lifecycle, or retention thinking
+❌ Treat analytics/data-governance layers as an afterthought
+
+## Modern organization baseline
+
+When the task touches data organization, cover these layers:
+1. Operational schema quality
+2. Naming and ownership clarity
+3. Lineage and downstream impact
+4. Query linting and maintainability
+5. Governance, retention, and sensitive-data handling
+
+This aligns better with the direction seen in DataHub, OpenMetadata, dbt, and SQLFluff.
+
+## Repository-specific expectations
+
+For `wegho-agentes` and similar PHP + TS/TSX + Supabase/PostgreSQL systems:
+- Prefer explicit relational structure over unbounded JSON
+- Document RLS assumptions alongside table design
+- Minimize sensitive data storage and define retention clearly
+- Keep file/blob payloads out of Supabase when rules require external storage
+- Treat SQL readability and predictable naming as review criteria, not polish
+
+## Supabase security and traffic baseline
+
+When the task uses Supabase, treat these as default architecture rules:
+1. Enable RLS on every exposed table and review policy cost
+2. Keep `service_role` strictly server-side
+3. Select only needed columns and always paginate large lists
+4. Index filter columns, join keys, and columns referenced by RLS
+5. Prefer metadata + external file hosting over storing large files in Supabase
+6. Use CDN-friendly public delivery only for non-sensitive assets
+7. Monitor egress, top paths, and query volume before scaling compute

package/.agent/skills/database-design/github-benchmarks.md

@@ -0,0 +1,35 @@
+# GitHub Benchmarks for Data Organization Skill
+
+Use these repositories as the benchmark for what strong data organization looks like today:
+
+## `supabase/supabase`
+- Official reference for RLS-first browser access, storage delivery, Edge Functions, and platform usage controls
+- Important benchmark when data modeling decisions affect egress, auth, storage, and operational cost
+
+## `supabase/agent-skills`
+- Good benchmark for Supabase-specific agent guidance around schema quality, RLS performance, and safe platform usage
+
+## `datahub-project/datahub`
+- Reference for metadata-driven discovery, governance, and observability
+- Strong mental model for ownership, lineage, and searchable context
+
+## `open-metadata/OpenMetadata`
+- Reference for trusted data context, cataloging, profiling, lineage, and governance
+- Useful when designing systems that need clearer metadata and business semantics
+
+## `open-metadata/OpenMetadataStandards`
+- Good benchmark for structured metadata contracts and interoperability
+
+## `dbt-labs/dbt-core`
+- Strong reference for model layering, testing culture, transformation discipline, and SQL-as-code workflow
+
+## `sqlfluff/sqlfluff`
+- Strong reference for SQL quality, style, linting, and maintainability
+
+Translate lessons from these projects into:
+- clearer schema boundaries
+- naming standards
+- ownership and lineage
+- maintainable SQL
+- governance-aware data structures
+- Supabase-aware egress and storage discipline

package/.agent/skills/database-design/supabase-security-egress.md

@@ -0,0 +1,42 @@
+# Supabase Security and Egress Baseline
+
+Use this reference when the system depends on Supabase and the goal includes security, traffic reduction, or storage economy.
+
+## Security defaults
+
+- Enable RLS on every table in exposed schemas such as `public`
+- Grant only the minimum role privileges required for `anon`, `authenticated`, and `service_role`
+- Never expose `service_role` in frontend code or `NEXT_PUBLIC_*`
+- Keep sensitive logic in server code, RPCs, or Edge Functions with strict auth checks
+- If using `SECURITY DEFINER`, keep it in a non-exposed schema, lock `search_path`, and restrict `EXECUTE`
+
+## Query and egress reduction
+
+- Avoid `SELECT *`; return only required columns
+- Always paginate list endpoints and apply `LIMIT`
+- Index columns used by filters, joins, sorting, and RLS predicates
+- Review repeated expensive joins; consider RPCs or materialized views when the access pattern is stable
+- For RLS policies using `auth.uid()` or similar helpers, prefer the cached `select auth.uid()` pattern when row-independent
+
+## Storage economy
+
+- Do not store large PDFs, videos, backups, archives, or heavy images in Supabase when project rules require external storage
+- Store only the link, minimal metadata, checksum, and ownership reference in Supabase
+- Use public buckets only for non-sensitive assets that benefit from CDN caching
+- Prefer Smart CDN and image transformations for cacheable images
+
+## Traffic control
+
+- Check Billing Dashboard, project reports, Top Paths, and query performance before changing compute size
+- Watch database egress, storage egress, auth egress, realtime usage, and edge function invocations separately
+- Use rate limiting for auth flows and expensive Edge Functions
+- For data-heavy Edge Functions, prefer running in the same region as the database
+- Avoid Realtime subscriptions when polling or one-time reads are enough
+
+## Review questions
+
+1. Is the data sensitive enough to require private access only?
+2. Can this response return fewer columns or fewer rows?
+3. Can this file live outside Supabase with only metadata stored here?
+4. Is egress coming from database rows, storage assets, auth churn, realtime, or functions?
+5. Are we paying compute to compensate for inefficient queries or missing indexes?

package/.agent/skills/file-doc-sync/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: file-doc-sync
+description: Generate and keep technical `.md` documentation synchronized beside each supported source or configuration file in the project. Use when the system needs a first-pass documentation sweep, when code changes require updating sibling docs, or when every file must maintain an always-current technical `.md` in the same folder.
+---
+
+# File Doc Sync
+
+Keep per-file technical documentation synchronized with the codebase.
+
+This skill creates one sibling `.md` file for each supported file and refreshes that documentation whenever the original file changes. The generated docs must stay short, technical, objective, and focused on the real role of the file in the system.
+
+## Workflow
+
+1. Run `tsx .agents/sync-docs.ts`.
+2. Scan the workspace recursively.
+3. Ignore generated directories, markdown files, and binaries.
+4. Create or update each sibling `.md`.
+5. Rerun after every implementation change before finalizing work.
+
+## Required sections
+
+Every generated `.md` must contain, in this order:
+- `## O que este arquivo faz`
+- `## Principais Responsabilidades`
+- `## Como funciona`
+- `## Dependências`
+- `## Integrações`
+- `## Segurança`
+- `## Impacto da Remoção`
+- `## Resumo Técnico`
+
+## Rules
+
+- Explain the real function of the file in the system.
+- Avoid line-by-line commentary.
+- Prefer short paragraphs and 3-5 bullets when list-shaped.
+- Mention only real dependencies, integrations, and security controls detected in the file.
+- If no direct security rule exists, say that security depends on external layers.
+- Keep the `.md` beside the original file.
+
+## Resources
+
+- Script: `scripts/sync-file-docs.ts`
+- Reference: `references/document-structure.md`

package/.agent/skills/file-doc-sync/references/document-structure.md

@@ -0,0 +1,20 @@
+# Estrutura da Documentação por Arquivo
+
+Use sempre esta ordem:
+
+1. `## O que este arquivo faz`
+2. `## Principais Responsabilidades`
+3. `## Como funciona`
+4. `## Dependências`
+5. `## Integrações`
+6. `## Segurança`
+7. `## Impacto da Remoção`
+8. `## Resumo Técnico`
+
+Regras:
+- Texto curto, técnico e objetivo.
+- Sem explicação linha por linha.
+- Sem repetição desnecessária.
+- Sempre gerar a documentação na mesma pasta do arquivo original.
+- O nome do arquivo deve trocar apenas a extensão para `.md` quando possível.
+- Para arquivos iniciados por ponto, manter o nome original e adicionar `.md` ao final.

package/.agent/skills/file-doc-sync/scripts/sync-file-docs.md

@@ -0,0 +1,45 @@
+# sync-file-docs.ts
+
+> Arquivo fonte: `.agent/skills/file-doc-sync/scripts/sync-file-docs.ts`
+
+## O que este arquivo faz
+Este arquivo expõe lógica reutilizável para outras partes do sistema, centralizando comportamento, configuração ou execução especializada.
+
+## Principais Responsabilidades
+- Expor 2 item(ns) reutilizável(is) para outras partes do sistema.
+- Definir classes ou estruturas centrais para encapsular comportamento.
+- Concentrar funções que executam a lógica principal deste arquivo.
+- Servir como ponto de manutenção para esta parte da funcionalidade.
+
+## Como funciona
+1. Carrega definições locais e dependências necessárias.
+2. Expõe a interface pública consumida por outros arquivos do projeto.
+3. Executa etapas assíncronas quando precisa consultar arquivos, serviços ou processos externos.
+4. Processa a responsabilidade principal do arquivo e retorna ou aplica o resultado esperado.
+5. Entrega a saída esperada para os consumidores diretos deste arquivo.
+
+## Dependências
+- fs
+- path
+- url
+
+## Integrações
+- Supabase
+- PostgreSQL
+- HostGator
+- HTTP APIs externas
+- Variáveis de ambiente
+- Sistema de arquivos
+
+## Segurança
+- Aplica ou referencia regras de RLS.
+- Inclui verificação ou dependência de autenticação/autorização.
+- Manipula dados sensíveis e exige cuidado com exposição em logs e cliente.
+- Utiliza mecanismos de proteção criptográfica ou hashing.
+- Define ou consome regras de acesso baseadas em policy.
+
+## Impacto da Remoção
+Sem este arquivo, consumidores diretos perdem a lógica ou a configuração que ele centraliza, causando erro funcional ou regressão de comportamento.
+
+## Resumo Técnico
+Arquivo técnico de suporte ao sistema, responsável por fornecer lógica, configuração ou interface reutilizável para outros módulos.

package/.agent/skills/file-doc-sync/scripts/sync-file-docs.ts

@@ -0,0 +1,349 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+const SUPPORTED_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.php',
+    '.sql',
+    '.json',
+    '.css',
+    '.scss',
+    '.html',
+    '.yml',
+    '.yaml',
+    '.env',
+]);
+
+const IGNORED_DIRECTORIES = new Set([
+    '.git',
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.next',
+]);
+
+export interface SyncResult {
+    scanned: number;
+    created: number;
+    updated: number;
+}
+
+export function syncProjectFileDocs(projectRoot: string = process.cwd()): SyncResult {
+    const files = collectSupportedFiles(projectRoot, projectRoot);
+    let created = 0;
+    let updated = 0;
+
+    for (const filePath of files) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const relativePath = normalizePath(path.relative(projectRoot, filePath));
+        const docPath = resolveDocPath(filePath);
+        const nextDoc = buildDocumentation(relativePath, path.basename(filePath), content);
+        const currentDoc = fs.existsSync(docPath) ? fs.readFileSync(docPath, 'utf-8') : null;
+
+        if (currentDoc === nextDoc) {
+            continue;
+        }
+
+        fs.writeFileSync(docPath, nextDoc, 'utf-8');
+
+        if (currentDoc === null) {
+            created++;
+        } else {
+            updated++;
+        }
+    }
+
+    return { scanned: files.length, created, updated };
+}
+
+function collectSupportedFiles(projectRoot: string, currentDir: string): string[] {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    const results: string[] = [];
+
+    for (const entry of entries) {
+        const absolutePath = path.join(currentDir, entry.name);
+        const relativePath = normalizePath(path.relative(projectRoot, absolutePath));
+
+        if (entry.isDirectory()) {
+            if (IGNORED_DIRECTORIES.has(entry.name)) {
+                continue;
+            }
+
+            results.push(...collectSupportedFiles(projectRoot, absolutePath));
+            continue;
+        }
+
+        if (shouldDocumentFile(entry.name, relativePath)) {
+            results.push(absolutePath);
+        }
+    }
+
+    return results;
+}
+
+function shouldDocumentFile(fileName: string, relativePath: string): boolean {
+    if (fileName.endsWith('.md')) {
+        return false;
+    }
+
+    if (relativePath.includes('/node_modules/') || relativePath.includes('/coverage/')) {
+        return false;
+    }
+
+    return SUPPORTED_EXTENSIONS.has(path.extname(fileName)) || fileName === '.env';
+}
+
+function resolveDocPath(filePath: string): string {
+    const directory = path.dirname(filePath);
+    const fileName = path.basename(filePath);
+
+    if (fileName.startsWith('.') && fileName.indexOf('.', 1) === -1) {
+        return path.join(directory, `${fileName}.md`);
+    }
+
+    const extension = path.extname(fileName);
+    const baseName = extension ? fileName.slice(0, -extension.length) : fileName;
+    return path.join(directory, `${baseName}.md`);
+}
+
+function buildDocumentation(relativePath: string, fileName: string, content: string): string {
+    const dependencies = extractDependencies(content);
+    const integrations = detectIntegrations(content);
+    const securityItems = detectSecurity(content);
+    const responsibilities = inferResponsibilities(fileName, content);
+    const flow = inferFlow(fileName, content);
+
+    return [
+        `# ${fileName}`,
+        '',
+        `> Arquivo fonte: \`${relativePath}\``,
+        '',
+        '## O que este arquivo faz',
+        inferPurpose(fileName, content),
+        '',
+        '## Principais Responsabilidades',
+        ...toBulletLines(responsibilities),
+        '',
+        '## Como funciona',
+        ...toNumberLines(flow),
+        '',
+        '## Dependências',
+        ...toBulletLines(
+            dependencies.length > 0
+                ? dependencies
+                : ['Nenhuma dependência explícita identificada pelo gerador.']
+        ),
+        '',
+        '## Integrações',
+        ...toBulletLines(
+            integrations.length > 0
+                ? integrations
+                : ['Não há integração externa explícita identificada neste arquivo.']
+        ),
+        '',
+        '## Segurança',
+        ...toBulletLines(securityItems),
+        '',
+        '## Impacto da Remoção',
+        inferImpact(fileName, content),
+        '',
+        '## Resumo Técnico',
+        inferSummary(fileName, content),
+        '',
+    ].join('\n');
+}
+
+function inferPurpose(fileName: string, content: string): string {
+    const extension = path.extname(fileName);
+
+    if (extension === '.json' || extension === '.yml' || extension === '.yaml' || fileName === '.env') {
+        return 'Este arquivo concentra configuração ou metadados usados pelo sistema para definir comportamento, integração ou execução.';
+    }
+
+    if (extension === '.sql') {
+        return 'Este arquivo define estrutura ou regras de banco de dados, incluindo comandos que afetam schema, políticas ou dados controlados.';
+    }
+
+    if (extension === '.css' || extension === '.scss') {
+        return 'Este arquivo define estilos visuais utilizados pela interface e controla aparência, layout e estados visuais.';
+    }
+
+    if (content.includes('export ') || content.includes('module.exports')) {
+        return 'Este arquivo expõe lógica reutilizável para outras partes do sistema, centralizando comportamento, configuração ou execução especializada.';
+    }
+
+    return 'Este arquivo contém lógica operacional usada pelo sistema para executar uma responsabilidade específica dentro do projeto.';
+}
+
+function inferResponsibilities(fileName: string, content: string): string[] {
+    const responsibilities = new Set<string>();
+    const exports = extractExports(content);
+
+    if (exports.length > 0) {
+        responsibilities.add(`Expor ${exports.length} item(ns) reutilizável(is) para outras partes do sistema.`);
+    }
+
+    if (content.includes('class ')) {
+        responsibilities.add('Definir classes ou estruturas centrais para encapsular comportamento.');
+    }
+
+    if (content.includes('function ') || content.includes('=>')) {
+        responsibilities.add('Concentrar funções que executam a lógica principal deste arquivo.');
+    }
+
+    if (fileName.endsWith('.json')) {
+        responsibilities.add('Declarar dados ou configuração consumidos em tempo de execução.');
+    }
+
+    if (fileName.endsWith('.sql')) {
+        responsibilities.add('Aplicar comandos de banco de dados e manter regras estruturais ou de acesso.');
+    }
+
+    if (fileName.endsWith('.css') || fileName.endsWith('.scss')) {
+        responsibilities.add('Controlar estilos e variações visuais da interface.');
+    }
+
+    if (responsibilities.size === 0) {
+        responsibilities.add('Executar uma responsabilidade localizada dentro do fluxo do sistema.');
+    }
+
+    responsibilities.add('Servir como ponto de manutenção para esta parte da funcionalidade.');
+    return Array.from(responsibilities).slice(0, 5);
+}
+
+function inferFlow(fileName: string, content: string): string[] {
+    const flow: string[] = ['Carrega definições locais e dependências necessárias.'];
+
+    if (content.includes('export ') || content.includes('module.exports')) {
+        flow.push('Expõe a interface pública consumida por outros arquivos do projeto.');
+    }
+
+    if (content.includes('async ') || content.includes('await ')) {
+        flow.push('Executa etapas assíncronas quando precisa consultar arquivos, serviços ou processos externos.');
+    }
+
+    if (fileName.endsWith('.json') || fileName.endsWith('.yml') || fileName.endsWith('.yaml') || fileName === '.env') {
+        flow.push('Fornece valores de configuração para leitura por outros módulos ou ferramentas.');
+    } else if (fileName.endsWith('.sql')) {
+        flow.push('Aplica comandos SQL que alteram schema, políticas ou dados do banco.');
+    } else {
+        flow.push('Processa a responsabilidade principal do arquivo e retorna ou aplica o resultado esperado.');
+    }
+
+    flow.push('Entrega a saída esperada para os consumidores diretos deste arquivo.');
+    return flow.slice(0, 5);
+}
+
+function detectIntegrations(content: string): string[] {
+    const integrations = new Set<string>();
+    const lowerContent = content.toLowerCase();
+
+    if (lowerContent.includes('supabase')) integrations.add('Supabase');
+    if (lowerContent.includes('postgres') || lowerContent.includes('postgresql')) integrations.add('PostgreSQL');
+    if (lowerContent.includes('hostgator')) integrations.add('HostGator');
+    if (lowerContent.includes('fetch(') || lowerContent.includes('axios')) integrations.add('HTTP APIs externas');
+    if (lowerContent.includes('process.env') || lowerContent.includes('dotenv')) integrations.add('Variáveis de ambiente');
+    if (lowerContent.includes('fs.') || lowerContent.includes('readfilesync') || lowerContent.includes('writefilesync')) integrations.add('Sistema de arquivos');
+
+    return Array.from(integrations);
+}
+
+function detectSecurity(content: string): string[] {
+    const lowerContent = content.toLowerCase();
+    const security = new Set<string>();
+
+    if (lowerContent.includes('rls')) security.add('Aplica ou referencia regras de RLS.');
+    if (lowerContent.includes('auth')) security.add('Inclui verificação ou dependência de autenticação/autorização.');
+    if (lowerContent.includes('token') || lowerContent.includes('secret')) security.add('Manipula dados sensíveis e exige cuidado com exposição em logs e cliente.');
+    if (lowerContent.includes('encrypt') || lowerContent.includes('hash')) security.add('Utiliza mecanismos de proteção criptográfica ou hashing.');
+    if (lowerContent.includes('policy')) security.add('Define ou consome regras de acesso baseadas em policy.');
+
+    if (security.size === 0) {
+        security.add('Não há controle de segurança explícito neste arquivo; a proteção depende das camadas consumidoras e das regras globais do sistema.');
+    }
+
+    return Array.from(security);
+}
+
+function inferImpact(fileName: string, content: string): string {
+    if (fileName.endsWith('.json') || fileName.endsWith('.yml') || fileName.endsWith('.yaml') || fileName === '.env') {
+        return 'Sem este arquivo, o sistema perde configuração necessária e pode falhar na inicialização, na integração ou na execução esperada.';
+    }
+
+    if (fileName.endsWith('.sql')) {
+        return 'Sem este arquivo, a estrutura ou as regras de banco relacionadas deixam de ser aplicadas, podendo quebrar persistência, segurança ou compatibilidade.';
+    }
+
+    if (content.includes('export ') || content.includes('module.exports')) {
+        return 'Sem este arquivo, consumidores diretos perdem a lógica ou a configuração que ele centraliza, causando erro funcional ou regressão de comportamento.';
+    }
+
+    return 'Sem este arquivo, a responsabilidade operacional que ele concentra deixa de existir e afeta o fluxo que depende dessa implementação.';
+}
+
+function inferSummary(fileName: string, content: string): string {
+    if (content.includes('export ') || content.includes('module.exports')) {
+        return 'Arquivo técnico de suporte ao sistema, responsável por fornecer lógica, configuração ou interface reutilizável para outros módulos.';
+    }
+
+    if (fileName.endsWith('.sql')) {
+        return 'Arquivo técnico de banco de dados, responsável por manter estrutura, políticas ou dados controlados no ambiente.';
+    }
+
+    if (fileName.endsWith('.json') || fileName.endsWith('.yml') || fileName.endsWith('.yaml') || fileName === '.env') {
+        return 'Arquivo técnico de configuração, usado para controlar o comportamento do sistema e suas integrações.';
+    }
+
+    return 'Arquivo técnico com responsabilidade localizada no sistema, necessário para manter o fluxo funcional dessa parte do projeto.';
+}
+
+function extractDependencies(content: string): string[] {
+    const dependencies = new Set<string>();
+    const importRegex = /from\s+['"]([^'"]+)['"]|require\(\s*['"]([^'"]+)['"]\s*\)|use\s+([A-Za-z0-9_\\]+)/g;
+
+    for (const match of content.matchAll(importRegex)) {
+        const dependency = match[1] || match[2] || match[3];
+        if (dependency) {
+            dependencies.add(dependency);
+        }
+    }
+
+    return Array.from(dependencies).slice(0, 10);
+}
+
+function extractExports(content: string): string[] {
+    const exports = new Set<string>();
+    const exportRegex = /export\s+(?:async\s+)?(?:function|class|const|let|var|type|interface)\s+([A-Za-z0-9_]+)/g;
+
+    for (const match of content.matchAll(exportRegex)) {
+        exports.add(match[1]);
+    }
+
+    return Array.from(exports);
+}
+
+function toBulletLines(items: string[]): string[] {
+    return items.map((item) => `- ${item}`);
+}
+
+function toNumberLines(items: string[]): string[] {
+    return items.map((item, index) => `${index + 1}. ${item}`);
+}
+
+function normalizePath(value: string): string {
+    return value.replace(/\\/g, '/');
+}
+
+const __filename = fileURLToPath(import.meta.url);
+
+if (process.argv[1] === __filename) {
+    const result = syncProjectFileDocs(process.cwd());
+    console.log(
+        `[file-doc-sync] ${result.scanned} arquivo(s) verificado(s), ${result.created} .md criado(s), ${result.updated} .md atualizado(s).`
+    );
+}