stealthos-cli 0.1.0-alpha.2 → 0.1.0-alpha.4

package/ai/scripts/lint-os.ps1

@@ -0,0 +1,99 @@
+# lint-os.ps1
+# Valida integridade do AI Operating System:
+#  - Todos os arquivos do manifest existem
+#  - Links markdown internos resolvem
+#  - Frontmatter valido em arquivos .ai/
+
+param(
+    [string]$TargetPath = (Get-Location).Path
+)
+
+$ErrorActionPreference = "Continue"
+$errors = @()
+$warnings = @()
+
+function Add-Error($msg) { $script:errors += $msg; Write-Host "[ERR] $msg" -ForegroundColor Red }
+function Add-Warn($msg) { $script:warnings += $msg; Write-Host "[WARN] $msg" -ForegroundColor Yellow }
+
+# ----- Manifest check -----
+$manifestPath = Join-Path $TargetPath ".ai\manifest.json"
+if (-not (Test-Path $manifestPath)) {
+    Add-Error ".ai\manifest.json nao encontrado"
+    exit 1
+}
+
+$manifest = Get-Content $manifestPath -Raw | ConvertFrom-Json
+
+foreach ($f in $manifest.required_files) {
+    $full = Join-Path $TargetPath ($f -replace '/', '\')
+    if (-not (Test-Path $full)) {
+        Add-Error "Arquivo obrigatorio ausente: $f"
+    }
+}
+
+# ----- Link check -----
+$mdFiles = Get-ChildItem -Path (Join-Path $TargetPath ".ai") -Filter "*.md" -Recurse -ErrorAction SilentlyContinue |
+    Where-Object { $_.FullName -notmatch '\\node_modules\\' -and $_.FullName -notmatch '\\dist\\' }
+$mdFiles += Get-ChildItem -Path $TargetPath -Filter "CLAUDE.md" -ErrorAction SilentlyContinue
+$mdFiles += Get-ChildItem -Path $TargetPath -Filter "GEMINI.md" -ErrorAction SilentlyContinue
+$mdFiles += Get-ChildItem -Path $TargetPath -Filter "GPT.md" -ErrorAction SilentlyContinue
+
+foreach ($file in $mdFiles) {
+    $content = Get-Content $file.FullName -Raw
+    $relFile = $file.FullName.Substring($TargetPath.Length + 1)
+
+    # Matches [texto](path) onde path comeca com . ou /
+    $matches = [regex]::Matches($content, '\[([^\]]+)\]\((\.{1,2}[^\)\s#]+)(?:#[^\)]*)?\)')
+    foreach ($m in $matches) {
+        $link = $m.Groups[2].Value
+        # Resolve relative to file dir
+        $resolved = Join-Path $file.DirectoryName $link
+        try {
+            $abs = [System.IO.Path]::GetFullPath($resolved)
+            if (-not (Test-Path $abs)) {
+                Add-Warn "${relFile}: link quebrado -> $link"
+            }
+        } catch {
+            Add-Warn "${relFile}: link nao resolvivel -> $link"
+        }
+    }
+}
+
+# ----- Frontmatter check -----
+$aiMdFiles = Get-ChildItem -Path (Join-Path $TargetPath ".ai") -Filter "*.md" -Recurse -ErrorAction SilentlyContinue |
+    Where-Object { $_.FullName -notmatch '\\node_modules\\' -and $_.FullName -notmatch '\\dist\\' }
+foreach ($file in $aiMdFiles) {
+    $content = Get-Content $file.FullName -Raw
+    $relFile = $file.FullName.Substring($TargetPath.Length + 1)
+
+    # Pular arquivos de log/append (memory/*, evolution/*) — frontmatter eh opcional
+    if ($relFile -match '\\memory\\(?!project-context)' -or $relFile -match '\\evolution\\') { continue }
+    # Pular .ai/server/README.md (codigo, nao doc do OS)
+    if ($relFile -match '\\server\\') { continue }
+    # Pular specs templates (estrutura de template, nao OS docs)
+    if ($relFile -match '\\specs\\' -and $relFile -match '_TEMPLATE\.md$') { continue }
+
+    # Verifica se arquivo comeca com bloco de frontmatter YAML (--- ... ---)
+    if ($content -notmatch '(?s)^\s*---\s*\r?\n.*?\r?\n---\s*\r?\n') {
+        Add-Warn "${relFile}: sem frontmatter (version/tier/tokens)"
+    }
+}
+
+# ----- Runtime v0.1 build check (warn-only) -----
+$capabilities = $manifest.capabilities
+if ($capabilities -and $capabilities.runtime_v0_1) {
+    $distPath = Join-Path $TargetPath ".ai\server\dist\index.mjs"
+    if (-not (Test-Path $distPath)) {
+        Add-Warn "Runtime v0.1 declarado no manifest mas dist/index.mjs ausente. Rode: cd .ai\server; npm install; npm run build"
+    } else {
+        Write-Host "[OK] Runtime v0.1 dist presente: .ai\server\dist\index.mjs" -ForegroundColor Green
+    }
+}
+
+# ----- Resumo -----
+Write-Host ""
+Write-Host "===== Lint Summary =====" -ForegroundColor Cyan
+Write-Host "Errors:   $($errors.Count)"
+Write-Host "Warnings: $($warnings.Count)"
+
+if ($errors.Count -gt 0) { exit 1 } else { exit 0 }

package/ai/scripts/lint-os.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# lint-os.sh - Valida integridade do AI OS (Unix)
+set -euo pipefail
+
+TARGET="$(pwd)"
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --target) TARGET="$2"; shift 2 ;;
+        *) shift ;;
+    esac
+done
+
+errors=0
+warnings=0
+add_err() { echo -e "\033[0;31m[ERR]\033[0m $1"; errors=$((errors+1)); }
+add_warn() { echo -e "\033[0;33m[WARN]\033[0m $1"; warnings=$((warnings+1)); }
+
+MANIFEST="$TARGET/.ai/manifest.json"
+[[ -f "$MANIFEST" ]] || { add_err ".ai/manifest.json ausente"; exit 1; }
+
+# required_files (precisa jq OU node OU python3)
+if command -v jq &>/dev/null; then
+    REQ_FILES=$(jq -r '.required_files[]' "$MANIFEST")
+elif command -v python3 &>/dev/null; then
+    REQ_FILES=$(python3 -c "import json,sys; print('\n'.join(json.load(open('$MANIFEST'))['required_files']))")
+elif command -v node &>/dev/null; then
+    REQ_FILES=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$MANIFEST','utf8')).required_files.join('\n'))")
+else
+    add_warn "Sem jq/python3/node — pulando validacao de manifest"
+    REQ_FILES=""
+fi
+
+while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    [[ -e "$TARGET/$f" ]] || add_err "Arquivo obrigatorio ausente: $f"
+done <<< "$REQ_FILES"
+
+# Frontmatter check em .ai/**.md (ignora memory/archive, evolution/, e arquivos especificos)
+while IFS= read -r mdfile; do
+    rel="${mdfile#$TARGET/}"
+    # Pular node_modules, dist, e specs templates
+    [[ "$rel" =~ /node_modules/ ]] && continue
+    [[ "$rel" =~ /dist/ ]] && continue
+    [[ "$rel" =~ \.ai/server/ ]] && continue
+    [[ "$rel" =~ /specs/.*_TEMPLATE\.md$ ]] && continue
+    # Pular memory/* (exceto project-context.md) e evolution/*
+    [[ "$rel" =~ \.ai/memory/(.*\.md)$ && ! "$rel" =~ project-context\.md$ ]] && continue
+    [[ "$rel" =~ \.ai/evolution/ ]] && continue
+    [[ "$rel" =~ \.ai/memory/archive/ ]] && continue
+    # Verificar frontmatter YAML --- ... ---
+    head -1 "$mdfile" | grep -q '^---' || add_warn "$rel: sem frontmatter"
+done < <(find "$TARGET/.ai" -name "*.md" -type f 2>/dev/null | grep -v node_modules | grep -v '/dist/')
+
+# Link check basico — procura links [texto](./...) e verifica existencia
+while IFS= read -r mdfile; do
+    rel="${mdfile#$TARGET/}"
+    [[ "$rel" =~ /node_modules/ ]] && continue
+    [[ "$rel" =~ /dist/ ]] && continue
+    file_dir="$(dirname "$mdfile")"
+    grep -oE '\]\(\.{1,2}[^)#[:space:]]+(\#[^)]*)?\)' "$mdfile" 2>/dev/null | \
+        sed -E 's/\]\((.+)\)/\1/; s/#.*$//' | \
+        while IFS= read -r link; do
+            [[ -z "$link" ]] && continue
+            resolved="$(cd "$file_dir" && cd "$(dirname "$link")" 2>/dev/null && pwd)/$(basename "$link")"
+            [[ -e "$resolved" ]] || add_warn "$rel: link quebrado -> $link"
+        done
+done < <(find "$TARGET/.ai" "$TARGET" -maxdepth 2 -name "*.md" -type f 2>/dev/null | grep -v node_modules | grep -v '/dist/')
+
+# Runtime v0.1 build check (warn-only)
+if command -v jq &>/dev/null; then
+    has_runtime=$(jq -r '.capabilities.runtime_v0_1 // false' "$MANIFEST" 2>/dev/null)
+    if [[ "$has_runtime" == "true" ]]; then
+        if [[ ! -f "$TARGET/.ai/server/dist/index.mjs" ]]; then
+            add_warn "Runtime v0.1 declarado no manifest mas dist/index.mjs ausente. Rode: cd .ai/server && npm install && npm run build"
+        else
+            echo -e "\033[0;32m[OK]\033[0m Runtime v0.1 dist presente: .ai/server/dist/index.mjs"
+        fi
+    fi
+fi
+
+echo ""
+echo "===== Lint Summary ====="
+echo "Errors:   $errors"
+echo "Warnings: $warnings"
+[[ $errors -gt 0 ]] && exit 1 || exit 0

package/ai/scripts/start-os.ps1

@@ -0,0 +1,151 @@
+# start-os.ps1 — Inicia o daemon AI OS (Windows)
+# Uso:
+#   .\scripts\start-os.ps1                    # MCP stdio (foreground)
+#   .\scripts\start-os.ps1 -Http              # HTTP em background, porta 47781 (auto-fallback)
+#   .\scripts\start-os.ps1 -Http -Port 8080
+#   .\scripts\start-os.ps1 -Status            # checa se daemon esta rodando
+#   .\scripts\start-os.ps1 -Stop
+
+param(
+    [switch]$Http,
+    [int]$Port = 47781,
+    [switch]$Status,
+    [switch]$Stop,
+    [switch]$Build,
+    [switch]$NoRuntime,
+    [string]$ProjectRoot = (Split-Path (Split-Path $PSScriptRoot -Parent) -Parent)
+)
+
+$ErrorActionPreference = "Stop"
+$serverPath = Join-Path $ProjectRoot ".ai\server\aios-server.mjs"
+$serverDir = Join-Path $ProjectRoot ".ai\server"
+$distPath = Join-Path $serverDir "dist\index.mjs"
+$nodeModulesPath = Join-Path $serverDir "node_modules"
+$runtimeDir = Join-Path $ProjectRoot ".ai\.runtime"
+$pidFile = Join-Path $runtimeDir "daemon.pid"
+$portFile = Join-Path $runtimeDir "port"
+$logFile = Join-Path $runtimeDir "daemon.log"
+
+function Write-Ok($m) { Write-Host "[OK] $m" -ForegroundColor Green }
+function Write-Info($m) { Write-Host "[..] $m" -ForegroundColor Cyan }
+function Write-Warn($m) { Write-Host "[WARN] $m" -ForegroundColor Yellow }
+function Write-Err($m) { Write-Host "[ERR] $m" -ForegroundColor Red }
+
+# Verifica Node
+if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+    Write-Err "Node.js nao encontrado. Instale Node >= 18 e tente novamente."
+    exit 1
+}
+
+if (-not (Test-Path $serverPath)) {
+    Write-Err "Servidor nao encontrado em: $serverPath"
+    exit 1
+}
+
+# Runtime v0.1: verificar dist/index.mjs
+if (-not $NoRuntime -and -not ($Status -or $Stop)) {
+    $distExists = Test-Path $distPath
+    if (-not $distExists -and $Build) {
+        if (-not (Get-Command npm -ErrorAction SilentlyContinue)) {
+            Write-Err "npm nao encontrado mas -Build foi solicitado. Instale Node >= 18 (npm vem junto)."
+            exit 1
+        }
+        Write-Info "Runtime v0.1 nao compilado. Rodando npm install + npm run build em $serverDir..."
+        Push-Location $serverDir
+        try {
+            if (-not (Test-Path $nodeModulesPath)) {
+                & npm install
+                if ($LASTEXITCODE -ne 0) { Write-Err "npm install falhou (exit $LASTEXITCODE)"; Pop-Location; exit 1 }
+            }
+            & npm run build
+            if ($LASTEXITCODE -ne 0) { Write-Err "npm run build falhou (exit $LASTEXITCODE)"; Pop-Location; exit 1 }
+            Write-Ok "Runtime v0.1 compilado em $distPath"
+        } finally {
+            Pop-Location
+        }
+    } elseif (-not $distExists) {
+        Write-Warn "Runtime v0.1 nao compilado (dist/index.mjs ausente). Daemon iniciara com 12 tools base apenas."
+        Write-Warn "Para habilitar as 5 tools v0.1 (analyze_project/build_context_package/snapshot*):"
+        Write-Warn "  cd .ai\server; npm install; npm run build"
+        Write-Warn "Ou rode este script com -Build para compilar automaticamente."
+    }
+}
+
+# ---- STATUS ----
+if ($Status) {
+    if (Test-Path $pidFile) {
+        $existingPid = Get-Content $pidFile -ErrorAction SilentlyContinue
+        $running = Get-Process -Id $existingPid -ErrorAction SilentlyContinue
+        if ($running) {
+            $port = if (Test-Path $portFile) { Get-Content $portFile } else { "n/a" }
+            Write-Ok "Daemon ativo: PID $existingPid, porta $port"
+            exit 0
+        } else {
+            Write-Info "Daemon inativo (PID file antigo)"
+            Remove-Item $pidFile -Force -ErrorAction SilentlyContinue
+            exit 1
+        }
+    } else {
+        Write-Info "Daemon inativo"
+        exit 1
+    }
+}
+
+# ---- STOP ----
+if ($Stop) {
+    if (Test-Path $pidFile) {
+        $existingPid = Get-Content $pidFile
+        $proc = Get-Process -Id $existingPid -ErrorAction SilentlyContinue
+        if ($proc) {
+            Stop-Process -Id $existingPid -Force
+            Write-Ok "Daemon parado (PID $existingPid)"
+        } else {
+            Write-Info "Processo $existingPid ja nao existe"
+        }
+        Remove-Item $pidFile -Force -ErrorAction SilentlyContinue
+        Remove-Item $portFile -Force -ErrorAction SilentlyContinue
+    } else {
+        Write-Info "Nenhum daemon registrado"
+    }
+    exit 0
+}
+
+# ---- START ----
+New-Item -ItemType Directory -Force -Path $runtimeDir | Out-Null
+
+# Checa se ja existe um rodando
+if (Test-Path $pidFile) {
+    $existingPid = Get-Content $pidFile
+    if (Get-Process -Id $existingPid -ErrorAction SilentlyContinue) {
+        Write-Info "Daemon ja rodando (PID $existingPid). Use -Stop para parar primeiro."
+        exit 0
+    } else {
+        Remove-Item $pidFile -Force
+    }
+}
+
+if ($Http) {
+    Write-Info "Iniciando daemon AI OS em modo HTTP (porta inicial: $Port)..."
+    # Quotar args com espaco para Start-Process -ArgumentList
+    $procArgs = @("`"$serverPath`"", "--http", "--port", "$Port")
+    $proc = Start-Process -FilePath "node" -ArgumentList $procArgs -WorkingDirectory $ProjectRoot `
+        -RedirectStandardOutput $logFile -RedirectStandardError "$logFile.err" `
+        -WindowStyle Hidden -PassThru
+    $proc.Id | Out-File -FilePath $pidFile -Encoding ascii
+    Start-Sleep -Seconds 2
+    if (Test-Path $portFile) {
+        $actualPort = Get-Content $portFile
+        Write-Ok "Daemon ativo: PID $($proc.Id), HTTP em http://127.0.0.1:$actualPort"
+        Write-Host "  Health: http://127.0.0.1:$actualPort/health"
+        Write-Host "  Tools:  http://127.0.0.1:$actualPort/tools"
+        Write-Host "  Logs:   $logFile"
+    } else {
+        Write-Info "Daemon iniciado (PID $($proc.Id)). Aguarde alguns segundos e cheque logs em $logFile"
+    }
+} else {
+    Write-Info "Iniciando daemon AI OS em modo MCP stdio (foreground)..."
+    Write-Info "Conecte seu cliente MCP usando: node `"$serverPath`""
+    Write-Info "Para rodar em background HTTP, use: -Http"
+    Write-Host ""
+    & node "$serverPath"
+}

package/ai/scripts/start-os.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# start-os.sh - Inicia o daemon AI OS (macOS/Linux)
+# Uso:
+#   ./scripts/start-os.sh                 # MCP stdio (foreground)
+#   ./scripts/start-os.sh --http          # HTTP em background, porta 47781
+#   ./scripts/start-os.sh --http --port 8080
+#   ./scripts/start-os.sh --status
+#   ./scripts/start-os.sh --stop
+
+set -euo pipefail
+
+MODE="stdio"
+PORT=47781
+ACTION="start"
+DO_BUILD=0
+NO_RUNTIME=0
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$(dirname "$SCRIPT_DIR")")"
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --http) MODE="http"; shift ;;
+        --port) PORT="$2"; shift 2 ;;
+        --status) ACTION="status"; shift ;;
+        --stop) ACTION="stop"; shift ;;
+        --build) DO_BUILD=1; shift ;;
+        --no-runtime) NO_RUNTIME=1; shift ;;
+        --project-root) PROJECT_ROOT="$2"; shift 2 ;;
+        *) echo "Arg desconhecido: $1" >&2; exit 1 ;;
+    esac
+done
+
+SERVER_PATH="$PROJECT_ROOT/.ai/server/aios-server.mjs"
+SERVER_DIR="$PROJECT_ROOT/.ai/server"
+DIST_PATH="$SERVER_DIR/dist/index.mjs"
+RUNTIME_DIR="$PROJECT_ROOT/.ai/.runtime"
+PID_FILE="$RUNTIME_DIR/daemon.pid"
+PORT_FILE="$RUNTIME_DIR/port"
+LOG_FILE="$RUNTIME_DIR/daemon.log"
+
+c_g='\033[0;32m'; c_c='\033[0;36m'; c_r='\033[0;31m'; c_y='\033[0;33m'; c_n='\033[0m'
+ok() { printf "${c_g}[OK]${c_n} %s\n" "$1"; }
+info() { printf "${c_c}[..]${c_n} %s\n" "$1"; }
+warn() { printf "${c_y}[WARN]${c_n} %s\n" "$1"; }
+err() { printf "${c_r}[ERR]${c_n} %s\n" "$1" >&2; }
+
+command -v node &>/dev/null || { err "Node.js nao encontrado (instale Node >= 18)"; exit 1; }
+[[ -f "$SERVER_PATH" ]] || { err "Servidor nao encontrado: $SERVER_PATH"; exit 1; }
+
+# Runtime v0.1: verificar dist/index.mjs
+if [[ $NO_RUNTIME -eq 0 && "$ACTION" == "start" ]]; then
+    if [[ ! -f "$DIST_PATH" ]]; then
+        if [[ $DO_BUILD -eq 1 ]]; then
+            command -v npm &>/dev/null || { err "npm nao encontrado mas --build foi solicitado"; exit 1; }
+            info "Runtime v0.1 nao compilado. Rodando npm install + npm run build em $SERVER_DIR..."
+            (cd "$SERVER_DIR" && {
+                if [[ ! -d "node_modules" ]]; then npm install || { err "npm install falhou"; exit 1; } fi
+                npm run build || { err "npm run build falhou"; exit 1; }
+            })
+            ok "Runtime v0.1 compilado em $DIST_PATH"
+        else
+            warn "Runtime v0.1 nao compilado (dist/index.mjs ausente). Daemon iniciara com 12 tools base apenas."
+            warn "Para habilitar as 5 tools v0.1 (analyze_project/build_context_package/snapshot*):"
+            warn "  cd .ai/server && npm install && npm run build"
+            warn "Ou rode este script com --build para compilar automaticamente."
+        fi
+    fi
+fi
+
+case "$ACTION" in
+    status)
+        if [[ -f "$PID_FILE" ]]; then
+            existing=$(cat "$PID_FILE")
+            if kill -0 "$existing" 2>/dev/null; then
+                port=$([[ -f "$PORT_FILE" ]] && cat "$PORT_FILE" || echo "n/a")
+                ok "Daemon ativo: PID $existing, porta $port"
+                exit 0
+            else
+                info "Daemon inativo (PID file antigo)"
+                rm -f "$PID_FILE"
+                exit 1
+            fi
+        else
+            info "Daemon inativo"
+            exit 1
+        fi
+        ;;
+
+    stop)
+        if [[ -f "$PID_FILE" ]]; then
+            existing=$(cat "$PID_FILE")
+            if kill -0 "$existing" 2>/dev/null; then
+                kill "$existing"
+                ok "Daemon parado (PID $existing)"
+            else
+                info "Processo $existing ja nao existe"
+            fi
+            rm -f "$PID_FILE" "$PORT_FILE"
+        else
+            info "Nenhum daemon registrado"
+        fi
+        exit 0
+        ;;
+
+    start)
+        mkdir -p "$RUNTIME_DIR"
+        if [[ -f "$PID_FILE" ]]; then
+            existing=$(cat "$PID_FILE")
+            if kill -0 "$existing" 2>/dev/null; then
+                info "Daemon ja rodando (PID $existing). Use --stop primeiro."
+                exit 0
+            fi
+            rm -f "$PID_FILE"
+        fi
+
+        if [[ "$MODE" == "http" ]]; then
+            info "Iniciando AI OS em modo HTTP (porta inicial: $PORT)..."
+            nohup node "$SERVER_PATH" --http --port "$PORT" \
+                >"$LOG_FILE" 2>"$LOG_FILE.err" &
+            new_pid=$!
+            echo "$new_pid" > "$PID_FILE"
+            disown
+            sleep 1
+            if [[ -f "$PORT_FILE" ]]; then
+                actual=$(cat "$PORT_FILE")
+                ok "Daemon ativo: PID $new_pid, HTTP em http://127.0.0.1:$actual"
+                echo "  Health: http://127.0.0.1:$actual/health"
+                echo "  Tools:  http://127.0.0.1:$actual/tools"
+                echo "  Logs:   $LOG_FILE"
+            else
+                info "Daemon iniciado (PID $new_pid). Aguarde e cheque logs em $LOG_FILE"
+            fi
+        else
+            info "Iniciando AI OS em modo MCP stdio (foreground)..."
+            info "Conecte seu cliente MCP usando: node $SERVER_PATH"
+            info "Para rodar em background HTTP, use: --http"
+            echo ""
+            exec node "$SERVER_PATH"
+        fi
+        ;;
+esac

package/ai/server/README.md

@@ -0,0 +1,105 @@
+# `.ai/server/` — MCP Daemon + Runtime v0.1
+
+Este diretório contém **dois componentes**:
+
+1. **`aios-server.mjs`** — MCP daemon Node puro (zero deps em runtime). Implementa JSON-RPC 2.0 sobre stdio + HTTP opcional na porta 47781. Expõe **17 tools** (12 base + 5 do Runtime v0.1).
+2. **`src/` + `dist/`** — Runtime v0.1 em TypeScript (compilado para `dist/index.mjs` via `esbuild --bundle`). Implementa os três motores executáveis do AI-DOS v0.1.
+
+## Arquitetura
+
+```
+aios-server.mjs (entry point .mjs, zero deps)
+    │
+    └─ import('dist/index.mjs')  ← bundle único gerado pelo esbuild
+                │
+                ├─ analyzer/   ← Project State Engine
+                ├─ packager/   ← Context Packager
+                └─ snapshot/   ← Snapshot System
+```
+
+O `aios-server.mjs` **continua funcionando sem `dist/`** (graceful degradation): só as 12 tools base ficam disponíveis. As 5 tools v0.1 retornam erro descritivo orientando o usuário a rodar o build.
+
+## Setup (primeira vez)
+
+```bash
+cd .ai/server
+npm install
+npm run build
+```
+
+Isso instala `ts-morph`, `commander`, e devDeps (`typescript`, `esbuild`, `@types/node`). Gera `dist/index.mjs` (bundle único, sem `node_modules` em runtime).
+
+## Comandos npm
+
+| Comando | Ação |
+|---|---|
+| `npm run build` | Type-check + esbuild bundle → `dist/index.mjs`. Mantém `ts-morph` e `commander` como external (importados em runtime do `node_modules`). |
+| `npm run build:standalone` | Bundle 100% self-contained (inclui `ts-morph` no bundle). Maior, mas remove dependência de `node_modules` em runtime. |
+| `npm run dev` | `tsc --watch` (apenas type-check incremental). |
+| `npm run typecheck` | `tsc --noEmit`. |
+| `npm start` | Inicia o daemon stdio. |
+| `npm run http` | Inicia o daemon em HTTP (porta 47781, auto-fallback). |
+
+## Estrutura `src/`
+
+```
+src/
+├── types.ts                        # tipos compartilhados (ProjectState, ContextPackage, SnapshotManifest, ...)
+├── index.ts                        # API pública (re-exports)
+├── analyzer/
+│   ├── index.ts                    # analyzeProject(root, options)
+│   ├── stack-detector.ts           # envelope dos scripts detect-stack.{ps1,sh}
+│   ├── module-mapper.ts            # ts-morph para TS/JS, regex fallback p/ outras
+│   ├── graph-builder.ts            # grafo de dependências + detecção de ciclos (DFS coloring)
+│   └── smell-detector.ts           # circular dep / large file / TODO / FIXME
+├── packager/
+│   ├── index.ts                    # buildContextPackage(root, options)
+│   ├── context-builder.ts          # orquestrador
+│   ├── module-summarizer.ts        # ModuleInfo → YAML block
+│   ├── memory-injector.ts          # lê memory/decisions, errors, issues + ranking por keywords
+│   └── token-estimator.ts          # chars/3.8 heurística + headroom check (regra 40%)
+└── snapshot/
+    ├── index.ts
+    ├── snapshot-creator.ts         # captura state + SHA-256 hashes + memory snapshot
+    ├── snapshot-diff.ts            # list + diff de snapshots
+    └── snapshot-restore.ts         # stub v0.1 (throw); v0.2 implementa
+```
+
+## Tools expostas (MCP)
+
+### Base (sempre disponíveis)
+- `aios_get_core_bundle`, `aios_route_query`, `aios_classify_task`
+- `aios_read`, `aios_list`, `aios_search_memory`
+- `aios_get_summary`, `aios_get_manifest`
+- `aios_lint`, `aios_detect_stack`, `aios_validate_audit`, `aios_health`
+
+### Runtime v0.1 (requer `dist/`)
+- `aios_analyze_project` — gera `.ai/context/project-state.{json,md}`
+- `aios_build_context_package` — gera `.ai/context/packages/<slug>.{md,json}`
+- `aios_snapshot` — gera `.ai/snapshots/<id>/`
+- `aios_snapshot_list`
+- `aios_snapshot_diff`
+
+## Slash commands relacionados
+
+- `/analyze` → chama `aios_analyze_project`
+- `/context --for "<intent>"` → chama `aios_build_context_package`
+- `/snapshot <label>` → chama `aios_snapshot`
+
+## Decisões arquiteturais
+
+- **ADR-0002** — adoção de TypeScript + `ts-morph` + `commander` + `esbuild`. Quebra "zero-deps" (apenas em dev). Justificativa em `.ai/specs/ADR/ADR-0002-typescript-runtime.md`.
+
+## Debug
+
+- `dist/` não gerou: `npm run build` falha → ver erro do `tsc`; geralmente é uma referência quebrada em `src/`.
+- Daemon não importa `dist/`: ver stderr do daemon — log `[aios] Runtime v0.1 dist failed to load: <razão>`.
+- Tools v0.1 retornam erro mesmo após build: rodar `aios_health` e checar campo `runtime_v0_1` + `runtime_load_error`.
+
+## Próximos passos (v0.2 — fora deste sprint)
+
+- `/dialog` e `/start` interativos
+- Intent Analyzer + Spec Generator
+- Embeddings + retrieval semântico
+- Agentes executáveis
+- Workflow engine (DAG)