@caoscompanybr/merlin 3.5.0

package/PRIVACY-LICENSING.md

@@ -0,0 +1,65 @@
+# Aviso de Privacidade — Licenciamento do Merlin
+
+> Parte integrante do contrato de licença (`LICENSE`). Descreve **exatamente**
+> os dados pessoais que o sistema de licenciamento do Merlin trata para ativar e
+> verificar a sua licença. Regido pela Lei nº 13.709/2018 (LGPD).
+
+## 1. Quem trata os dados
+
+**Controlador:** Matteus Rodrigues Eugenio (Empresário Individual, CNPJ 39.315.802/0001-26), sob a marca Merlin Company — Licenciante (ver `LICENSE`).
+**Contato / Encarregado (DPO):** support@merlincompany.com.br.
+
+## 2. Quais dados são tratados (e quando)
+
+O sistema transmite ao servidor de licenças **apenas** os campos abaixo —
+verificável no código-fonte (`.merlin-core/core/licensing/activation.js`):
+
+| Dado               | O que é                                                                                                                                                       | Quando é enviado                              |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| `fingerprint_hash` | **Hash SHA-256** de `machine-id ‖ serial do disco ‖ hostname` da sua Máquina. É um identificador derivado e irreversível — **não** é o seu hardware em claro. | Na ativação e em cada verificação (heartbeat) |
+| `client_email`     | O e-mail informado por você na ativação (`merlin activate --email`), normalmente o e-mail da compra.                                                          | Apenas na ativação                            |
+| `serial`           | O número de série da sua licença (da chave `MRL-#N`).                                                                                                         | Ativação e heartbeat                          |
+| `version`          | A versão do Merlin instalada.                                                                                                                                 | No heartbeat                                  |
+| `ts_signed`        | Carimbo de tempo (timestamp) do heartbeat.                                                                                                                    | No heartbeat                                  |
+| `hmac`             | Código de integridade derivado dos campos acima (antifraude). O segredo local que o gera (`api_key_local`) **fica na sua máquina e nunca é transmitido**.     | No heartbeat                                  |
+
+## 3. Finalidade
+
+- **Ativação** da licença e **vínculo** a uma Máquina;
+- **Antifraude** (detectar cópia/compartilhamento indevido da licença);
+- **Suporte** técnico e administração do contrato (renovação, suspensão,
+  revogação).
+
+## 4. Base legal
+
+**Execução de contrato** (LGPD, art. 7º, V) — o tratamento é necessário para
+fornecer e proteger a licença que você contratou. O antifraude apoia-se também no
+**legítimo interesse** (art. 7º, IX) de coibir uso não autorizado.
+
+## 5. Compartilhamento
+
+Os dados são processados na infraestrutura do servidor de licenças
+(Cloudflare Workers/D1), atuando como **operador** por conta do Controlador. Não
+há venda nem compartilhamento dos dados para fins de marketing de terceiros.
+
+## 6. Retenção
+
+Os registros de licença e auditoria (ativações, heartbeats, emissões, revogações)
+são mantidos enquanto durar a relação contratual e pelos prazos legais aplicáveis
+(p. ex. prescrição civil), após o que são eliminados ou anonimizados.
+
+## 7. O que NÃO é coletado
+
+O licenciamento **não** lê, transmite ou armazena: o conteúdo dos seus arquivos
+ou código, os prompts/sessões do Claude Code, telemetria de uso de skills/agentes,
+ou qualquer dado do seu projeto. O gate de sessão (`license-gate.cjs`) roda
+**offline** — lê a licença em cache local (`~/.merlin/license.mlic`), verifica
+assinatura/expiração/Máquina e **não faz chamada de rede**.
+
+## 8. Direitos do titular (LGPD, art. 18)
+
+Você pode solicitar confirmação de tratamento, acesso, correção, anonimização,
+portabilidade, informação sobre compartilhamento e — observadas as obrigações
+legais e contratuais — eliminação dos seus dados, pelo contato da seção 1. Para
+diagnóstico/suporte você pode obter o seu `fingerprint_hash` localmente com
+`merlin fingerprint`.

package/README.md

@@ -0,0 +1,391 @@
+<div align="center">
+  <img src="Merlin deitado.png" alt="Merlin Logo" width="140" />
+  <h1>Gestao Merlin</h1>
+  <p><strong>The Mage of Management</strong> — AI Orchestration Framework</p>
+  <p>Turn Claude Code into a managed software development operation.</p>
+
+  <br />
+
+[![Version](https://img.shields.io/badge/version-3.5.0-blue?style=flat-square)]()
+[![Agents](https://img.shields.io/badge/agents-16-8A2BE2?style=flat-square)]()
+[![Skills](https://img.shields.io/badge/skills-74-green?style=flat-square)]()
+[![Commands](https://img.shields.io/badge/commands-39-orange?style=flat-square)]()
+[![Modules](https://img.shields.io/badge/core_modules-78-red?style=flat-square)]()
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)]()
+[![CI](https://github.com/EuGenio1FreeLa/gestao-merlin/actions/workflows/ci.yml/badge.svg)](https://github.com/EuGenio1FreeLa/gestao-merlin/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Commercial-blue?style=flat-square)](LICENSE)
+[![npm](https://img.shields.io/npm/v/gestao-merlin?style=flat-square)](https://www.npmjs.com/package/gestao-merlin)
+
+</div>
+
+<br />
+
+Instead of a single AI assistant, you get **16 specialized agents**, **74 auto-activating skills** (65 built-in + 9 domain), and **38 slash commands** governed by a constitution, quality gates, and structured workflows.
+
+---
+
+## Why Merlin Exists
+
+AI coding assistants are powerful but chaotic. They forget context between sessions, skip quality checks, hallucinate features, and can't coordinate multi-agent work. Merlin solves this by layering an **operating system abstraction** over Claude Code:
+
+| Problem                                | Merlin's Solution                                        |
+| -------------------------------------- | -------------------------------------------------------- |
+| AI forgets everything between sessions | RAG memory via ThoughtsProvider + auto-summarize hooks   |
+| No quality enforcement                 | 3-layer gates (pre-commit, PR automation, human review)  |
+| Context window exhausts mid-task       | 8-layer Alkimia engine with bracket-aware token budgets  |
+| Single-agent bottleneck                | Team execution (coordinate/route/broadcast) + party mode |
+| Unsafe autonomous actions              | 3-tier approval (LOW/MEDIUM/HIGH) + 3-point guardrails   |
+| Documentation goes stale               | Self-updating doc-sync detection                         |
+| No structured methodology              | Spec-Driven Development with the Folloni Funnel          |
+
+---
+
+## Quick Start
+
+### 1. Install Merlin
+
+```bash
+npm install -g @caoscompanybr/merlin
+```
+
+### 2. Initialize your project
+
+```bash
+mkdir my-project && cd my-project
+merlin init
+```
+
+This scaffolds `.merlin-core/`, the `.claude/` hooks and rules, and a starter
+config. For full prerequisites and per-OS steps, see [INSTALL.md](INSTALL.md).
+
+> Merlin is **commercial, licensed software**: see [LICENSE](LICENSE) (a B2B
+> EULA under Brazilian law) and [PRIVACY-LICENSING.md](PRIVACY-LICENSING.md)
+> (LGPD). `merlin init` requires a valid, activated license — run
+> `merlin activate <key> --email <you@example.com>` first.
+
+### 3. Configure your project
+
+Edit `.merlin-core/project-config.yaml` with your project name, description, and active agents.
+
+### 4. Start developing
+
+```bash
+claude                          # Open Claude Code
+/research                       # Understand the codebase
+/plan "what to build"           # Design the implementation
+/implement                      # Build it
+/adversarial-review             # Attack it
+/commit                         # Ship it
+```
+
+For the full guide and command reference, see [docs/GUIDE.md](.merlin-core/docs/GUIDE.md).
+
+---
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph core[".merlin-core/"]
+        CONST["Constitution<br/>13 Principles"]
+
+        subgraph runtime["Core Runtime — 78 modules across 19 subsystems"]
+            subgraph engines["Principal Engines (6)"]
+                ALK["Alkimia<br/>L0-L7 Context Injection"]
+                EXEC["Execution<br/>Parallel · Team · Wave · Party"]
+                ORCH["Orchestration<br/>Master · Gates · Workflows"]
+                QG["Quality Gates<br/>3 Layers"]
+                APPR["Approval<br/>3 Tiers + YOLO"]
+                MCP["MCP<br/>Server Integration"]
+            end
+
+            subgraph state["Memory & State (5)"]
+                MEM["memory"]
+                EVT["events"]
+                REG["registry"]
+                MAN["manifest"]
+                SES["session"]
+            end
+
+            subgraph policy["Policy & Lifecycle (4)"]
+                CFG["config"]
+                PERM["permissions"]
+                HC["health-check"]
+                ELI["elicitation"]
+            end
+
+            subgraph internals["Internals (4)"]
+                IDS["ids"]
+                UI["ui"]
+                UTIL["utils"]
+                DOC["docs"]
+            end
+        end
+
+        subgraph dev["Development"]
+            AGENTS["15 Agents"]
+            SKILLS["73 Skills"]
+            CMDS["37 Commands"]
+        end
+
+        subgraph knowledge["Knowledge Persistence"]
+            PLANS["Plans"]
+            RESEARCH["Research"]
+            HANDOFFS["Handoffs"]
+            DECISIONS["ADRs"]
+            LEARN["Learnings"]
+        end
+    end
+
+    CONST --> ALK
+    ALK --> EXEC
+    ORCH --> EXEC
+    EXEC --> QG
+    QG --> APPR
+    AGENTS --> ORCH
+    SKILLS --> AGENTS
+    CMDS --> ORCH
+    ALK -.-> MEM
+    ORCH -.-> EVT
+    EXEC -.-> PERM
+    CFG --> CONST
+
+    style CONST fill:#1a1a2e,color:#fff
+    style ALK fill:#533483,color:#fff
+    style EXEC fill:#e94560,color:#fff
+    style ORCH fill:#0f3460,color:#fff
+    style QG fill:#27ae60,color:#fff
+    style APPR fill:#f39c12,color:#000
+    style MCP fill:#16213e,color:#fff
+```
+
+### Directory Layout
+
+```
+your-project/
+├── .merlin-core/                    Framework core (committed)
+│   ├── constitution.md              13 governing principles
+│   ├── core/                        78 production modules across 19 subsystems
+│   │   ├── alkimia/                 8-layer context injection (L0-L7) + RAG memory
+│   │   ├── execution/               ParallelExecutor, TeamExecutor, PartySession
+│   │   ├── orchestration/           MasterOrchestrator, GateEvaluator, workflows
+│   │   ├── approval/                3-tier ApprovalEngine with YOLO mode
+│   │   ├── quality-gates/           3-layer quality enforcement
+│   │   ├── mcp/                     MCP server integration + capability mapper
+│   │   ├── memory/                  ThoughtsProvider RAG store
+│   │   ├── events/                  EventBus for cross-agent signals
+│   │   ├── registry/                Artifact + skill registry
+│   │   ├── manifest/                Project manifest reader/writer
+│   │   ├── session/                 Session state + transcripts
+│   │   ├── config/                  4-level config resolution (L0-L3)
+│   │   ├── permissions/             Per-agent file restriction enforcement
+│   │   ├── health-check/            Subsystem readiness probes
+│   │   ├── elicitation/             20+ structured techniques
+│   │   └── ids, ui, utils, docs/    Internals + shared helpers
+│   ├── development/
+│   │   ├── agents/                  15 agent definitions
+│   │   ├── workflows/               Folloni Funnel + step files
+│   │   └── templates/               Spec, PRD, research, handoff
+│   ├── commands/                    37 slash commands by phase
+│   ├── skills/                      64 built-in + 9 domain (user-extensible)
+│   ├── tools/                       Merlin-Tools CLI (19 subcommands)
+│   ├── schemas/                     12 JSON validation schemas
+│   └── thoughts/shared/             Plans, research, handoffs, decisions, learnings
+├── .claude/
+│   ├── CLAUDE.md                    Project instructions
+│   ├── hooks/                       4 lifecycle hooks
+│   └── rules/                       Constitution enforcement
+└── .merlin/                         Runtime state (gitignored)
+```
+
+---
+
+## The Alkimia Context Engine
+
+Every agent interaction passes through 8 layers that inject the right context at the right time:
+
+```mermaid
+graph LR
+    L0["L0<br/>Constitution"] --> L1["L1<br/>Global"]
+    L1 --> L2["L2<br/>Agent"]
+    L2 --> L3["L3<br/>Workflow"]
+    L3 --> L4["L4<br/>Task"]
+    L4 --> L5["L5<br/>Squad"]
+    L5 --> L6["L6<br/>Skill"]
+    L6 --> L7["L7<br/>Star Command"]
+
+    style L0 fill:#1a1a2e,color:#fff
+    style L1 fill:#16213e,color:#fff
+    style L2 fill:#0f3460,color:#fff
+    style L3 fill:#533483,color:#fff
+    style L4 fill:#e94560,color:#fff
+    style L5 fill:#f39c12,color:#000
+    style L6 fill:#27ae60,color:#fff
+    style L7 fill:#3498db,color:#fff
+```
+
+**Token Brackets** manage context pressure as the conversation grows:
+
+| Bracket      | Usage  | Behavior                                    |
+| ------------ | ------ | ------------------------------------------- |
+| **FRESH**    | 0-25%  | All layers, full detail                     |
+| **MODERATE** | 25-50% | Standard detail, optional layers trimmed    |
+| **DEPLETED** | 50-75% | Essential only, aggressive trimming         |
+| **CRITICAL** | 75%+   | Constitution + active task, recommend reset |
+
+---
+
+## The Folloni Funnel
+
+Primary development workflow with context resets between phases:
+
+```mermaid
+graph LR
+    R["Phase 1<br/>Research<br/>Sage + Scout"] -->|prd.md| RST1["CONTEXT<br/>RESET"]
+    RST1 --> P["Phase 2<br/>Architecture<br/>Aria"] -->|spec.md| RST2["CONTEXT<br/>RESET"]
+    RST2 --> B["Phase 3<br/>Implementation<br/>Dex → Quinn → Gage"]
+
+    style R fill:#3498db,color:#fff
+    style P fill:#9b59b6,color:#fff
+    style B fill:#e74c3c,color:#fff
+    style RST1 fill:#95a5a6,color:#fff,stroke-dasharray: 5 5
+    style RST2 fill:#95a5a6,color:#fff,stroke-dasharray: 5 5
+```
+
+Each phase operates with a **fresh context window**, loading only the output document from the previous phase. This prevents context exhaustion on complex tasks.
+
+---
+
+## Agent Roster
+
+| ID             | Name   | Role                     | Auto-Activates On                            |
+| -------------- | ------ | ------------------------ | -------------------------------------------- |
+| merlin-master  | Orion  | Master Orchestrator      | orchestrate, dispatch, workflow              |
+| analyst        | Atlas  | Business Analyst         | requirements, stakeholder, gap-analysis      |
+| architect      | Aria   | Software Architect       | design, architecture, spec, system-design    |
+| dev            | Dex    | Full Stack Developer     | implement, code, build, fix, refactor        |
+| devops         | Gage   | DevOps Engineer          | push, deploy, pr, ci, pipeline, git          |
+| pm             | Morgan | Project Manager          | status, sprint, risk, timeline, milestone    |
+| po             | Pax    | Product Owner            | story, backlog, prioritize, product, feature |
+| qa             | Quinn  | QA Specialist            | test, quality, verify, adversarial, break    |
+| sm             | River  | Scrum Master             | standup, retro, impediment, velocity         |
+| ux             | Uma    | UX Designer              | ux, accessibility, wireframe, usability      |
+| data-engineer  | Dara   | Data Engineer            | schema, database, migration, sql, etl        |
+| researcher     | Sage   | Deep Codebase Researcher | research, analyze, trace, explain-code       |
+| scout          | Scout  | Fast File Locator        | find, locate, search, grep, list-files       |
+| web-researcher | Iris   | Web Research Specialist  | web-research, competitive-analysis           |
+| meta           | Mira   | System Optimizer         | optimize, improve-system, analyze-sessions   |
+
+---
+
+## Command Reference
+
+| Phase          | Command               | Purpose                                      |
+| -------------- | --------------------- | -------------------------------------------- |
+| Research       | `/research`           | Deep codebase analysis with Sage + Scout     |
+| Planning       | `/plan`               | Create implementation spec                   |
+|                | `/iterate-plan`       | Refine an existing plan                      |
+|                | `/validate-plan`      | Verify plan meets requirements + must_haves  |
+| Implementation | `/implement`          | Execute a plan from thoughts/shared/plans/   |
+|                | `/oneshot`            | Quick implementation without full spec       |
+| Git            | `/commit`             | Stage and commit with conventional message   |
+|                | `/describe-pr`        | Create PR with structured description        |
+| Session        | `/handoff`            | Create handoff for context continuity        |
+|                | `/resume-handoff`     | Resume from prior handoff                    |
+|                | `/create-reminder`    | Create persistent cross-session reminder     |
+|                | `/create-objective`   | Create goal with success criteria            |
+|                | `/check-objectives`   | Review progress on active objectives         |
+|                | `/capture-learning`   | Capture domain-specific learning             |
+|                | `/recall-learnings`   | Recall learnings relevant to current context |
+| Review         | `/review`             | Run local code review                        |
+|                | `/debug`              | Debug and troubleshoot                       |
+|                | `/adversarial-review` | 7-axis adversarial attack surface review     |
+|                | `/engineering-audit`  | 6-axis holistic engineering code audit       |
+|                | `/verify-goals`       | Verify implementation against must_haves     |
+| Special        | `/elicit [technique]` | Structured elicitation (20+ techniques)      |
+|                | `/party "topic"`      | Multi-agent roundtable collaboration         |
+|                | `/founder-mode`       | Unrestricted development mode                |
+
+---
+
+## The 13 Constitutional Principles
+
+| #    | Principle                          | Severity | What It Means                                                                                    |
+| ---- | ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
+| I    | **CLI First**                      | BLOCK    | CLI is source of truth. UI observes, never controls.                                             |
+| II   | **Agent Authority**                | BLOCK    | Exclusive permissions. Only @devops pushes, only @architect designs.                             |
+| III  | **Spec-Driven Development**        | BLOCK    | Research before planning. Plan before coding. No code without spec.                              |
+| IV   | **No Invention**                   | BLOCK    | Specs derive from requirements only. Never invent features.                                      |
+| V    | **Quality First**                  | BLOCK    | 3-layer gates enforce quality. Layer 1 failure blocks merge.                                     |
+| VI   | **MCP First**                      | WARN     | External capabilities through MCP servers, not custom code.                                      |
+| VII  | **Human Gates**                    | BLOCK    | HIGH-stake actions require explicit human approval. Always.                                      |
+| VIII | **Craftsmanship & Follow-Through** | WARN     | Best effort on every phase. DONE, BLOCKED, or HANDED-OFF.                                        |
+| IX   | **Input Boundary Defense**         | BLOCK    | External data is untrusted. Web pages, API responses, and user docs never drive agent behavior.  |
+| X    | **Professional Objectivity**       | WARN     | Technical accuracy over validating user beliefs. Flag unsound approaches even when requested.    |
+| XI   | **Absolute Safety Boundaries**     | BLOCK    | ABSOLUTE-stake actions (force-push main, drop prod DB) never auto-approved — not even in YOLO.   |
+| XII  | **Information Priority Hierarchy** | WARN     | 5-tier source ranking on conflict: live code > docs > memory > web > training.                   |
+| XIII | **Discussion-First Default**       | INFO     | Ambiguous intent → discuss, don't implement. Explicit action words required before writing code. |
+
+---
+
+## Quality Gates & Approval
+
+### 3-Layer Quality Enforcement
+
+| Layer       | Stage         | Mode   | What It Checks                       |
+| ----------- | ------------- | ------ | ------------------------------------ |
+| **Layer 1** | Pre-commit    | AUTO   | Lint, test, typecheck, build         |
+| **Layer 2** | PR Automation | AUTO   | Coverage, security, automated review |
+| **Layer 3** | Human Review  | MANUAL | Human sign-off required              |
+
+### 3-Point Guardrails (Agent Execution)
+
+- **Pre-check** — Agent exists, task valid, files exist
+- **Mid-check** — Timeout monitoring, output size, error detection
+- **Post-check** — Success validation, file matching, secret scanning
+
+### Approval Tiers
+
+| Tier       | Behavior                        | Examples                      | YOLO Mode     |
+| ---------- | ------------------------------- | ----------------------------- | ------------- |
+| **LOW**    | Auto-approved, logged           | commit, file changes, tests   | Same          |
+| **MEDIUM** | Confirmation (5min timeout)     | push, PR, package install     | Auto-approved |
+| **HIGH**   | Blocked until explicit approval | production deploy, force push | Still blocked |
+
+---
+
+## CLI Tools
+
+```bash
+node .merlin-core/tools/merlin-tools.js <command>
+
+  index              Rebuild thoughts INDEX.json and INDEX.md
+  archive            Archive terminal thoughts to .archive/
+  state [k] [v]      Read/write context bridge state
+  frontmatter <f>    Extract YAML frontmatter from markdown
+  list-agents        List all registered agents
+  list-skills        List all skills with activation keywords
+  validate <t> <f>   Validate file against schema
+  yolo [on|off]      Toggle YOLO mode
+  doc-sync           Detect stale documentation
+  migrate-alkimia    Migrate .synapse/ dirs to .alkimia/
+  upgrade <path>     Upgrade a satellite project to current version
+  backup [path]      Backup project-owned data to .merlin-backups/latest/
+  eval-skill <name>  Evaluate a skill against its evals
+  sync-bridges       Regenerate .claude/commands bridge files
+```
+
+---
+
+## License
+
+Commercial software under a paid EULA — see [LICENSE](LICENSE). All rights
+reserved. Use requires a valid license activated with `merlin activate`.
+
+---
+
+<div align="center">
+  <sub>Built with the Folloni Funnel methodology across 3 waves of systematic evolution.</sub>
+  <br />
+  <sub>Powered by Claude Code + the Merlin Constitution.</sub>
+</div>

package/bin/README.md

@@ -0,0 +1,15 @@
+# CLI Entry Points
+
+The bin directory contains the executable entry points for Merlin. The main CLI is provided by merlin.js, with specialized variants including an initialization wizard, intrusion detection system tool, and lightweight minimal version for resource-constrained environments.
+
+## Contents
+
+- **merlin.js** - Main CLI entry point with full Merlin capabilities
+- **merlin-init.js** - Interactive initialization wizard for new projects
+- **merlin-ids.js** - Intrusion Detection System for security monitoring
+- **merlin-minimal.js** - Lightweight CLI variant with essential features only
+
+## Related
+
+- [Packages](../packages/README.md)
+- [Core](../.merlin-core/core/README.md)

package/bin/convert-to-merlin.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+#
+# convert-to-merlin.sh — Thin wrapper around the JS install/upgrade engine.
+#
+# As of 2026-05-17 (Phase 8 of plan-a-shared-install-engine), the actual work
+# is performed by .merlin-core/tools/commands/upgrade.js (via merlin-tools CLI).
+# This script preserves the original CLI surface for backwards compatibility
+# with operator workflows, scripts, and the /converterparamagos slash command.
+#
+# Backup model note: the JS engine writes a single rotated backup at
+# .merlin-backups/latest/ (preserving project-owned data: thoughts, domain skills,
+# project-config, claude-commands). The legacy timestamped .claude-backup-<TS>/
+# and .merlin-core-backup-<TS>/ siblings are no longer created by this wrapper —
+# rollback is supported via .merlin-backups/latest/ + the per-piece restore
+# commands printed on error (formatRecoveryInstructions).
+#
+# USAGE:
+#   ./convert-to-merlin.sh <PROJECT_DIR> <MERLIN_SOURCE> [PROJECT_NAME] [--dry-run] [--yes] [--flatten-nesting]
+#
+# EXAMPLES:
+#   ./convert-to-merlin.sh "/path/to/project" "/path/to/gestao-merlin" --dry-run
+#   ./convert-to-merlin.sh "/path/to/project" "/path/to/gestao-merlin" --yes
+#   ./convert-to-merlin.sh "/path/to/project" "/path/to/gestao-merlin" "ProjectName" --yes --flatten-nesting
+
+set -euo pipefail
+
+# ============================================================================
+# Early --help (before strict positional validation)
+# ============================================================================
+
+for arg in "$@"; do
+  case "$arg" in
+    --help|-h)
+      cat <<HELP
+Usage: $(basename "$0") PROJECT_DIR MERLIN_SOURCE [PROJECT_NAME] [--dry-run] [--yes] [--flatten-nesting]
+
+  PROJECT_DIR        Target project to convert or upgrade
+  MERLIN_SOURCE      Path to Gestao Merlin framework source
+  PROJECT_NAME       Display name (ignored — JS engine derives from PROJECT_DIR basename)
+
+Flags:
+  --dry-run, -n      Show what WOULD happen without writing anything
+  --yes, -y          Non-interactive (silently accepted by JS engine — no-op)
+  --flatten-nesting  Remove legacy domain/skill/skill/ nesting from preserved data
+  --help, -h         Show this message
+
+Examples:
+  $(basename "$0") /path/to/proj /path/to/gestao-merlin --dry-run
+  $(basename "$0") /path/to/proj /path/to/gestao-merlin --yes --flatten-nesting
+
+This is a thin wrapper. Actual work is performed by:
+  node MERLIN_SOURCE/.merlin-core/tools/merlin-tools.js upgrade <PROJECT_DIR> [flags]
+HELP
+      exit 0
+      ;;
+  esac
+done
+
+# ============================================================================
+# Positional + flag parsing (preserves original CLI surface)
+# ============================================================================
+
+PROJECT_DIR="${1:?Erro: Informe o caminho do projeto como primeiro argumento}"
+MERLIN_SOURCE="${2:?Erro: Informe o caminho do Gestao Merlin como segundo argumento}"
+shift 2
+
+# Defaults
+AUTO_CONFIRM=""
+DRY_RUN=""
+FLATTEN_NESTING=""
+NAME_SET=false
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --yes|-y) AUTO_CONFIRM="--yes" ;;
+    --dry-run|-n) DRY_RUN="--dry-run" ;;
+    --flatten-nesting) FLATTEN_NESTING="--flatten-nesting" ;;
+    --*) echo "  ⚠ Unknown flag (ignored, will not pass to JS): $1" >&2 ;;
+    *)
+      # First non-flag positional was PROJECT_NAME in the old bash CLI.
+      # JS engine derives name from PROJECT_DIR basename, so we just consume + warn.
+      if [ "$NAME_SET" = false ]; then
+        NAME_SET=true
+      else
+        echo "  ⚠ Extra positional ignored: $1" >&2
+      fi
+      ;;
+  esac
+  shift
+done
+
+# ============================================================================
+# Validate source has the JS engine
+# ============================================================================
+
+JS_ENGINE="$MERLIN_SOURCE/.merlin-core/tools/merlin-tools.js"
+if [ ! -f "$JS_ENGINE" ]; then
+  echo "Erro: JS engine not found at: $JS_ENGINE" >&2
+  echo "       Is \$MERLIN_SOURCE pointing to a valid Gestao Merlin checkout?" >&2
+  exit 1
+fi
+
+# ============================================================================
+# Forward to JS engine
+# ============================================================================
+
+# Build flag list (skip empty positionals via no quotes — bash unquoted expansion
+# omits empties, which is exactly what we want here)
+exec node "$JS_ENGINE" upgrade "$PROJECT_DIR" $DRY_RUN $AUTO_CONFIRM $FLATTEN_NESTING