mcp-efficiency-engine 0.1.1 → 0.1.3

package/.githooks/post-commit

@@ -0,0 +1,20 @@
+#!/usr/bin/env sh
+set -eu
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
+if [ -z "$REPO_ROOT" ]; then
+  exit 0
+fi
+
+if command -v pwsh >/dev/null 2>&1; then
+  pwsh -NoProfile -ExecutionPolicy Bypass -File "$REPO_ROOT/scripts/ops/post-commit-refresh.ps1"
+  exit 0
+fi
+
+if command -v powershell >/dev/null 2>&1; then
+  powershell -NoProfile -ExecutionPolicy Bypass -File "$REPO_ROOT/scripts/ops/post-commit-refresh.ps1"
+  exit 0
+fi
+
+# No PowerShell available; skip silently to avoid blocking commits.
+exit 0

package/.github/workflows/autodocs-sync.yml

@@ -30,6 +30,55 @@ jobs:
         run: py -3 -m scripts.wiki.wiki_compiler
         shell: pwsh
 
+      - name: Ensure npm README is updated when package surface changes
+        shell: pwsh
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          $script = @'
+          const fs = require("node:fs");
+          const { execSync } = require("node:child_process");
+
+          const baseSha = process.env.BASE_SHA;
+          if (!baseSha) {
+            console.log("BASE_SHA is not available; skipping npm README check.");
+            process.exit(0);
+          }
+
+          const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+          const publishEntries = (pkg.files || []).map((entry) =>
+            entry.startsWith("./") ? entry.slice(2) : entry
+          );
+
+          const changed = execSync("git diff --name-only " + baseSha + "...HEAD", { encoding: "utf8" })
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean);
+
+          const readmeChanged = changed.includes("README.md");
+          const isNpmRelevant = (file) =>
+            file === "package.json" ||
+            file === "package-lock.json" ||
+            publishEntries.some((entry) => (entry.endsWith("/") ? file.startsWith(entry) : file === entry));
+
+          const npmRelevantChanges = changed.filter((file) => file !== "README.md" && isNpmRelevant(file));
+          if (npmRelevantChanges.length > 0 && !readmeChanged) {
+            console.error("Detected npm-impacting changes without README.md update.");
+            console.error("npm-impacting files:");
+            for (const file of npmRelevantChanges) console.error("- " + file);
+            console.error("Please update README.md (npm docs) in the same PR.");
+            process.exit(1);
+          }
+
+          if (npmRelevantChanges.length > 0) {
+            console.log("npm-impacting changes detected and README.md was updated.");
+          } else {
+            console.log("No npm-impacting changes detected.");
+          }
+          '@
+
+          node -e $script
+
       - name: Validate generated artifacts are committed
         shell: pwsh
         run: |

package/FINAL_USAGE_GUIDE.md

@@ -136,6 +136,28 @@ Archivo `telemetry/config.json`:
 
 Si falta configuración, se omite automáticamente.
 
+## Flujo post-commit para proyectos consumidores
+
+El install host configura hooks git locales (`core.hooksPath=.githooks`).
+
+Hook incluido:
+
+- `post-commit` -> `scripts/ops/post-commit-refresh.ps1`
+
+Regla:
+
+- Solo actua cuando el commit toca rutas bajo `projects/`.
+
+Pipeline ejecutado en ese caso:
+
+1. AutoDocs incremental (`scripts/wiki/compiler_main.py`)
+2. Refresh de reportes de learning/value (`scripts/learning/*.py`)
+3. Publicacion de snapshots KPI a LangSmith (`scripts/ops/publish-langsmith-kpis.py`)
+
+Log de ejecucion:
+
+- `observability/logs/session/post-commit-refresh-*.json`
+
 ### Cómo deshabilitar exporters
 
 - Desactivar todo: `TELEMETRY_ENABLED=false`

package/README.md

@@ -192,6 +192,16 @@ Comportamiento esperado:
 - si no existe `repo-registry/repos.yml`, pregunta por owner/prefix y si quieres registrar un repo inicial para intake
 - si no añades repos en ese momento, deja el registry plantilla listo para añadirlos despues y rerun de intake
 
+Nota npm (entornos con politicas de scripts):
+
+- si `npm` bloquea `install`/`postinstall` (por ejemplo con `allow-scripts`), el scaffold/bootstrapping puede no ejecutarse automaticamente
+- en ese caso, aprueba scripts (`npm approve-scripts`) o ejecuta manualmente:
+
+```powershell
+npx mcp-efficiency-engine install
+npx mcp-efficiency-engine validate -PortableMode
+```
+
 Tambien puedes relanzar la instalacion manualmente sobre el proyecto actual:
 
 ```powershell
@@ -229,6 +239,32 @@ py -3 .\scripts\intake\agent-pipeline-preflight.py
 py -3 .\scripts\intake\validate-repo-registry.py --strict
 ```
 
+### Flujo automatico al hacer commit en projects/
+
+Cuando instalas el engine en un proyecto host (`mcpee install`), se configura `core.hooksPath=.githooks` con un `post-commit` que ejecuta `scripts/ops/post-commit-refresh.ps1`.
+
+Comportamiento del hook:
+
+- si el ultimo commit no toca `projects/`, no hace nada
+- si detecta cambios en `projects/`, ejecuta:
+  - `scripts/wiki/compiler_main.py` (AutoDocs incremental)
+  - `scripts/learning/learning-loop-report.py`
+  - `scripts/learning/iteration-value-report.py`
+  - `scripts/ops/publish-langsmith-kpis.py` (best effort)
+
+Artefactos/resultados:
+
+- AutoDocs actualizado en `autodocs/generated` y `autodocs/site`
+- reportes de observabilidad actualizados en `observability/evals`
+- snapshots KPI publicados a LangSmith para dashboards
+- resumen local en `observability/logs/session/post-commit-refresh-*.json`
+
+Instalacion manual de hooks (si necesitas reprovisionar):
+
+```powershell
+.\scripts\setup\install-project-hooks.ps1
+```
+
 ## Flujo De Intake
 
 `repo-intake` soporta dos modos:
@@ -344,6 +380,68 @@ $env:LANGSMITH_ENABLED='false'
 $env:TELEMETRY_EXPORTERS='console,json'
 ```
 
+Troubleshooting rapido: no aparecen dashboards/runs en LangSmith
+
+Importante: en LangSmith, los runs se validan primero en `Tracing` (y opcionalmente `Monitoring`). La seccion `Custom Dashboards` no se autogenera por defecto; puede aparecer vacia aunque la telemetria este funcionando correctamente.
+
+Checklist minimo (debe cumplirse todo):
+
+- `LANGSMITH_ENABLED=true`
+- `LANGSMITH_API_KEY` definido
+- `LANGSMITH_PROJECT` definido
+- `TELEMETRY_EXPORTERS=console,json,langsmith`
+- el flujo que ejecutas realmente emite telemetria (por ejemplo `hi.ps1`, intake o routing-evals)
+
+Comprobacion en PowerShell:
+
+```powershell
+Write-Host "LANGSMITH_ENABLED=$env:LANGSMITH_ENABLED"
+Write-Host "LANGSMITH_PROJECT=$env:LANGSMITH_PROJECT"
+Write-Host "TELEMETRY_EXPORTERS=$env:TELEMETRY_EXPORTERS"
+```
+
+Si `LANGSMITH_WORKSPACE_ID` no coincide con tu workspace real, los runs pueden quedar en otro workspace y "no verse" en la UI esperada.
+
+Verificacion local (aunque LangSmith falle):
+
+- revisa que se siguen generando logs en `observability/logs/` (la app no debe romperse por un fallo del exporter)
+- si hay trazas locales pero no runs remotos, el problema es de configuracion/conectividad de LangSmith y no del flujo principal
+
+### Alinear KPIs locales con LangSmith
+
+Para enviar a LangSmith los KPIs que ya calcula el engine en local (`learning-loop-report.json` e `iteration-value-report.json`) y poder construir dashboards con esa señal:
+
+```powershell
+npm run langsmith:kpis
+```
+
+Este comando publica runs de resumen con tags `mcpee`, `kpi`, `dashboard` y nombres:
+
+- `KPI::LearningLoop`
+- `KPI::IterationValue`
+- `KPI::AlignmentSnapshot`
+
+Con eso puedes filtrar en `Tracing` por `tag:kpi` y montar dashboards manuales en `Custom Dashboards` sobre esos runs.
+
+Separacion plataforma vs proyecto consumidor:
+
+- los runs KPI incluyen metadata y tags de scope automaticamente
+- metadata: `host_project`, `host_project_slug`, `telemetry_scope` (`platform` o `consumer`)
+- tags: `scope:<valor>` y `host:<slug>`
+
+Ejemplos de filtro para un dashboard de proyecto consumidor:
+
+- `Tag contains kpi`
+- `Tag contains scope:consumer`
+- `Tag contains host:<slug-del-proyecto>`
+
+Si quieres forzar nombre de proyecto host (por ejemplo en CI):
+
+```powershell
+$env:MCPEE_HOST_PROJECT='mi-proyecto-app'
+npm run langsmith:kpis
+```
+
 Variables de entorno soportadas:
 
 - `TELEMETRY_ENABLED`

package/bin/install-host.js

@@ -6,6 +6,7 @@ const { spawnSync } = require("node:child_process");
 
 const packageRoot = path.resolve(__dirname, "..");
 const scaffoldEntries = [
+  ".githooks",
   ".github",
   ".vscode",
   "autodocs/README.md",
@@ -260,6 +261,15 @@ function runBootstrap(targetRoot) {
   return runPowerShell(bootstrapScript, [], targetRoot);
 }
 
+function installProjectHooks(targetRoot) {
+  const hookScript = path.join(targetRoot, "scripts", "setup", "install-project-hooks.ps1");
+  if (!fs.existsSync(hookScript)) {
+    return 0;
+  }
+
+  return runPowerShell(hookScript, [], targetRoot);
+}
+
 function runHostInstall(rawOptions) {
   const options = rawOptions;
   const targetRoot = normalizePath(options.targetDir);
@@ -284,6 +294,11 @@ function runHostInstall(rawOptions) {
       return initStatus;
     }
 
+    const hookStatus = installProjectHooks(targetRoot);
+    if (hookStatus !== 0) {
+      return hookStatus;
+    }
+
     process.stdout.write("[mcpee] Bootstrap omitido. Puedes ejecutar .\\scripts\\bootstrap-portable.cmd mas tarde.\n");
     return 0;
   }
@@ -294,11 +309,21 @@ function runHostInstall(rawOptions) {
       return initStatus;
     }
 
+    const hookStatus = installProjectHooks(targetRoot);
+    if (hookStatus !== 0) {
+      return hookStatus;
+    }
+
     process.stdout.write("[mcpee] Modo no interactivo detectado. Se inicializo el registry plantilla y se omitio bootstrap interactivo.\n");
     return 0;
   }
 
-  return runBootstrap(targetRoot);
+  const bootstrapStatus = runBootstrap(targetRoot);
+  if (bootstrapStatus !== 0) {
+    return bootstrapStatus;
+  }
+
+  return installProjectHooks(targetRoot);
 }
 
 function runHostInstallFromCli(argv = process.argv.slice(2)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-efficiency-engine",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Motor de orquestacion para agentes MCP con routing por dominio y bootstrap portable.",
   "license": "MIT",
   "type": "commonjs",
@@ -9,6 +9,7 @@
     "mcp-efficiency-engine": "./bin/mcpee.js"
   },
   "files": [
+    ".githooks/",
     "bin/",
     "telemetry/",
     "autodocs/README.md",
@@ -50,6 +51,7 @@
     "hi": "node ./bin/mcpee.js hi",
     "bye": "node ./bin/mcpee.js bye",
     "intake": "node ./bin/mcpee.js intake",
+    "langsmith:kpis": "py -3 ./scripts/ops/publish-langsmith-kpis.py",
     "pack:check": "npm pack --dry-run"
   },
   "engines": {

package/requirements.txt

@@ -1,2 +1,3 @@
 graphifyy[mcp]
 langsmith
+mcp

package/scripts/ops/bye.ps1

@@ -73,6 +73,26 @@ function Test-CommandAvailable {
     return [bool](Get-Command $Name -ErrorAction SilentlyContinue)
 }
 
+function Ensure-SetupPrerequisites {
+    if ($script:SetupAttempted) {
+        if (-not $script:SetupSucceeded) {
+            throw 'setup-prerequisites was already attempted and failed earlier in this run'
+        }
+        return $true
+    }
+
+    $script:SetupAttempted = $true
+    Write-Host '[info] Missing prerequisite detected. Running setup-prerequisites automatically...' -ForegroundColor DarkYellow
+    & pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup\setup-prerequisites.ps1 -PortableMode
+    if ($LASTEXITCODE -ne 0) {
+        $script:SetupSucceeded = $false
+        throw "setup-prerequisites failed with exit code $LASTEXITCODE"
+    }
+
+    $script:SetupSucceeded = $true
+    return $true
+}
+
 function Invoke-ObservabilityRetentionCleanup {
     param(
         [string]$RepoRoot,
@@ -320,6 +340,8 @@ Set-Location $repoRoot
 
 $script:Steps = @()
 $script:HasFailures = $false
+$script:SetupAttempted = $false
+$script:SetupSucceeded = $false
 $script:StepLogs = [ordered]@{}
 $script:RetentionCleanupReport = [ordered]@{
     applied = $false
@@ -367,6 +389,10 @@ else {
 
 if (-not $SkipGraphRefresh) {
     Invoke-Step -Name 'Refresh codegraph index sync' -Action {
+        if (-not (Get-Command codegraph -ErrorAction SilentlyContinue)) {
+            [void](Ensure-SetupPrerequisites)
+        }
+
         if (-not (Get-Command codegraph -ErrorAction SilentlyContinue)) {
             throw 'codegraph command not found'
         }
@@ -548,6 +574,10 @@ else {
 
 if (-not $SkipCodegraphStatus) {
     Invoke-Step -Name 'Check codegraph status' -Action {
+        if (-not (Get-Command codegraph -ErrorAction SilentlyContinue)) {
+            [void](Ensure-SetupPrerequisites)
+        }
+
         if (-not (Get-Command codegraph -ErrorAction SilentlyContinue)) {
             throw 'codegraph command not found'
         }

package/scripts/ops/hi.ps1

@@ -835,6 +835,19 @@ else {
 
 if (-not $SkipMcpStartupChecks) {
     Invoke-Step -Name 'Validate MCP servers start/listen capability' -Action {
+        $requiredCommands = @(
+            'token-saver-mcp',
+            'codebase-memory-mcp',
+            'codegraph',
+            'npx'
+        )
+
+        $missingCommands = @($requiredCommands | Where-Object { -not (Test-CommandAvailable -Name $_) })
+        if ($missingCommands.Count -gt 0) {
+            Write-Host ("[info] Missing MCP prerequisites detected ({0}). Running setup-prerequisites automatically..." -f ($missingCommands -join ', ')) -ForegroundColor DarkYellow
+            [void](Ensure-SetupPrerequisites)
+        }
+
         $py = Get-PythonCommand
         $pyCmd = $py[0]
         $pyParts = @()

package/scripts/ops/post-commit-refresh.ps1

@@ -0,0 +1,110 @@
+param(
+    [switch]$Force,
+    [switch]$SkipLangSmith,
+    [switch]$SkipLearningReports,
+    [switch]$SkipAutoDocs
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+function Get-PythonCommand {
+    if (Get-Command py -ErrorAction SilentlyContinue) {
+        return @('py', '-3')
+    }
+    if (Get-Command python -ErrorAction SilentlyContinue) {
+        return @('python')
+    }
+    throw 'Python is required (py or python not found in PATH).'
+}
+
+function Invoke-PythonScript {
+    param(
+        [string]$ScriptPath,
+        [string[]]$Args = @(),
+        [switch]$IgnoreErrors
+    )
+
+    $python = Get-PythonCommand
+    & $python[0] $python[1] $ScriptPath @Args
+    $exitCode = $LASTEXITCODE
+    if ($exitCode -ne 0 -and -not $IgnoreErrors) {
+        throw "Command failed ($exitCode): $ScriptPath"
+    }
+    return $exitCode
+}
+
+$repoRoot = (& git rev-parse --show-toplevel 2>$null)
+if (-not $repoRoot) {
+    Write-Host '[mcpee] post-commit-refresh skipped: git repo not detected.'
+    exit 0
+}
+
+Set-Location $repoRoot
+
+$changedFiles = (& git diff-tree --no-commit-id --name-only -r HEAD 2>$null)
+if ($LASTEXITCODE -ne 0) {
+    Write-Host '[mcpee] post-commit-refresh skipped: unable to inspect last commit.'
+    exit 0
+}
+
+$projectChanges = @($changedFiles | Where-Object { $_ -match '^projects/' })
+if (-not $Force -and $projectChanges.Count -eq 0) {
+    Write-Host '[mcpee] post-commit-refresh skipped: no changes under projects/ in last commit.'
+    exit 0
+}
+
+$started = Get-Date
+$status = 'ok'
+$errors = @()
+$steps = @()
+
+try {
+    if (-not $SkipAutoDocs) {
+        Write-Host '[mcpee] AutoDocs: compiling incremental projection...'
+        Invoke-PythonScript -ScriptPath '.\scripts\wiki\compiler_main.py'
+        $steps += 'autodocs'
+    }
+
+    if (-not $SkipLearningReports) {
+        Write-Host '[mcpee] Observability: refreshing learning reports...'
+        Invoke-PythonScript -ScriptPath '.\scripts\learning\learning-loop-report.py'
+        Invoke-PythonScript -ScriptPath '.\scripts\learning\iteration-value-report.py'
+        $steps += 'learning-reports'
+    }
+
+    if (-not $SkipLangSmith) {
+        Write-Host '[mcpee] LangSmith: publishing KPI snapshots...'
+        Invoke-PythonScript -ScriptPath '.\scripts\ops\publish-langsmith-kpis.py' -IgnoreErrors
+        $steps += 'langsmith-kpis'
+    }
+}
+catch {
+    $status = 'failed'
+    $errors += $_.Exception.Message
+    Write-Warning ("[mcpee] post-commit-refresh failed: {0}" -f $_.Exception.Message)
+}
+
+$finished = Get-Date
+$duration = [math]::Round((($finished - $started).TotalSeconds), 2)
+
+$summary = [ordered]@{
+    timestamp = $finished.ToString('o')
+    operation = 'post-commit-refresh'
+    status = $status
+    duration_sec = $duration
+    changed_projects_files = $projectChanges.Count
+    steps = $steps
+    errors = $errors
+}
+
+$sessionDir = Join-Path $repoRoot 'observability/logs/session'
+New-Item -ItemType Directory -Path $sessionDir -Force | Out-Null
+$stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
+$reportPath = Join-Path $sessionDir ("post-commit-refresh-$stamp.json")
+$summary | ConvertTo-Json -Depth 8 | Set-Content -Path $reportPath -Encoding UTF8
+
+Write-Host ("[mcpee] post-commit-refresh {0}. report: {1}" -f $status, $reportPath)
+
+# Never block commit history after it was created.
+exit 0

package/scripts/ops/publish-langsmith-kpis.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from telemetry.config import load_config
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _iso_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _slug(value: str) -> str:
+    return "".join(ch.lower() if ch.isalnum() else "-" for ch in value).strip("-")
+
+
+def _resolve_host_scope(repo_root: Path) -> tuple[str, str]:
+    host_project = (os.getenv("MCPEE_HOST_PROJECT") or repo_root.name or "unknown-project").strip()
+    host_slug = _slug(host_project) or "unknown-project"
+    platform_slugs = {"mcp-efficiency-engine", "efficiency", "mcpee"}
+    scope = "platform" if host_slug in platform_slugs else "consumer"
+    return host_project, scope
+
+
+def _flatten_kpis(payload: dict[str, Any]) -> dict[str, Any]:
+    flat: dict[str, Any] = {}
+    for key, value in payload.items():
+        flat[f"kpi_{key}"] = value
+    return flat
+
+
+def _publish_run(
+    client: Any,
+    *,
+    project: str,
+    name: str,
+    inputs: dict[str, Any],
+    outputs: dict[str, Any],
+    tags: list[str],
+    metadata: dict[str, Any] | None = None,
+    total_cost: float | None = None,
+    total_tokens: int | None = None,
+    run_type: str = "chain",
+) -> str:
+    now = _iso_now()
+    run_id = str(uuid.uuid4())
+    payload: dict[str, Any] = {
+        "id": run_id,
+        "project_name": project,
+        "name": name,
+        "run_type": run_type,
+        "inputs": inputs,
+        "outputs": outputs,
+        "start_time": now,
+        "end_time": now,
+        "tags": tags,
+        "extra": {"metadata": metadata or {}},
+    }
+
+    if total_cost is not None:
+        payload["total_cost"] = float(total_cost)
+        payload["prompt_cost"] = 0.0
+        payload["completion_cost"] = float(total_cost)
+    if total_tokens is not None:
+        payload["total_tokens"] = int(total_tokens)
+        # For LLM-compatible dashboard metrics, expose token fields explicitly.
+        payload["prompt_tokens"] = 0
+        payload["completion_tokens"] = int(total_tokens)
+
+    usage_metadata: dict[str, Any] = {
+        "input_tokens": int(payload.get("prompt_tokens", 0) or 0),
+        "output_tokens": int(payload.get("completion_tokens", 0) or 0),
+        "total_tokens": int(payload.get("total_tokens", 0) or 0),
+        "total_cost": float(payload.get("total_cost", 0.0) or 0.0),
+    }
+
+    outputs_kpi = payload.setdefault("outputs", {})
+    outputs_kpi["usage_metadata"] = usage_metadata
+
+    meta = payload.setdefault("extra", {}).setdefault("metadata", {})
+    meta["usage_metadata"] = usage_metadata
+
+    client.create_run(**payload)
+    return run_id
+
+
+def _publish_feedback_metrics(client: Any, *, run_id: str, metrics: dict[str, Any], source: str) -> None:
+    for key, raw_value in metrics.items():
+        try:
+            value = float(raw_value)
+        except Exception:
+            continue
+
+        try:
+            client.create_feedback(
+                run_id=run_id,
+                key=str(key),
+                score=value,
+                comment=f"mcpee kpi:{source}",
+            )
+        except Exception:
+            # Feedback is optional. Keep publishing resilient.
+            continue
+
+
+def main() -> int:
+    repo_root = REPO_ROOT
+    cfg = load_config(repo_root)
+    host_project, telemetry_scope = _resolve_host_scope(repo_root)
+    host_slug = _slug(host_project)
+
+    if not cfg.langsmith.enabled:
+        print("LangSmith disabled in effective config. Nothing to publish.")
+        return 0
+
+    if not cfg.langsmith.api_key.strip() or not cfg.langsmith.project.strip():
+        print("LangSmith config missing api_key or project. Nothing to publish.")
+        return 0
+
+    try:
+        from langsmith import Client  # type: ignore
+    except Exception as exc:
+        print(f"langsmith SDK is not available: {exc}")
+        return 1
+
+    kwargs: dict[str, Any] = {"api_key": cfg.langsmith.api_key}
+    if cfg.langsmith.endpoint:
+        kwargs["api_url"] = cfg.langsmith.endpoint
+    if cfg.langsmith.workspace_id:
+        kwargs["workspace_id"] = cfg.langsmith.workspace_id
+
+    client = Client(**kwargs)
+
+    learning_path = repo_root / "observability" / "evals" / "learning-loop-report.json"
+    value_path = repo_root / "observability" / "evals" / "iteration-value-report.json"
+
+    learning = _read_json(learning_path)
+    value = _read_json(value_path)
+
+    published = 0
+
+    if learning:
+        learning_kpis = learning.get("kpis", {}) if isinstance(learning.get("kpis", {}), dict) else {}
+        learning_flat_kpis = _flatten_kpis(learning_kpis)
+        run_id = _publish_run(
+            client,
+            project=cfg.langsmith.project,
+            name="KPI::LearningLoop",
+            inputs={
+                "source_file": str(learning_path),
+                "timestamp": learning.get("timestamp"),
+            },
+            outputs={
+                "kpis": learning_kpis,
+                **learning_flat_kpis,
+                "health": learning.get("health", {}),
+                "totals": {
+                    "total_events": learning.get("total_events"),
+                    "confirmed_events": learning.get("confirmed_events"),
+                    "pending_events": learning.get("pending_events"),
+                },
+            },
+            tags=[
+                "mcpee",
+                "kpi",
+                "learning-loop",
+                "dashboard",
+                f"scope:{telemetry_scope}",
+                f"host:{host_slug}",
+            ],
+            metadata={
+                "kpi_source": "learning-loop",
+                "kpi_kind": "snapshot",
+                "host_project": host_project,
+                "host_project_slug": host_slug,
+                "telemetry_scope": telemetry_scope,
+                **learning_flat_kpis,
+            },
+        )
+        _publish_feedback_metrics(client, run_id=run_id, metrics=learning_flat_kpis, source="learning-loop")
+        published += 1
+
+    if value:
+        value_kpis = value.get("kpis", {}) if isinstance(value.get("kpis", {}), dict) else {}
+        value_flat_kpis = _flatten_kpis(value_kpis)
+        run_id = _publish_run(
+            client,
+            project=cfg.langsmith.project,
+            name="KPI::IterationValue",
+            inputs={
+                "source_file": str(value_path),
+                "timestamp": value.get("timestamp"),
+            },
+            outputs={
+                "kpis": value_kpis,
+                **value_flat_kpis,
+                "totals": value.get("totals", {}),
+                "assessment": value.get("assessment", {}),
+            },
+            tags=[
+                "mcpee",
+                "kpi",
+                "iteration-value",
+                "dashboard",
+                f"scope:{telemetry_scope}",
+                f"host:{host_slug}",
+            ],
+            metadata={
+                "kpi_source": "iteration-value",
+                "kpi_kind": "snapshot",
+                "host_project": host_project,
+                "host_project_slug": host_slug,
+                "telemetry_scope": telemetry_scope,
+                **value_flat_kpis,
+            },
+            total_cost=float(value_kpis.get("total_cost_usd", 0.0) or 0.0),
+            total_tokens=int(value_kpis.get("total_tokens", 0) or 0),
+            run_type="llm",
+        )
+        _publish_feedback_metrics(client, run_id=run_id, metrics=value_flat_kpis, source="iteration-value")
+        published += 1
+
+    if learning or value:
+        learning_kpis = learning.get("kpis", {}) if isinstance(learning.get("kpis", {}), dict) else {}
+        value_kpis = value.get("kpis", {}) if isinstance(value.get("kpis", {}), dict) else {}
+        learning_flat_kpis = _flatten_kpis(learning_kpis)
+        value_flat_kpis = _flatten_kpis(value_kpis)
+        run_id = _publish_run(
+            client,
+            project=cfg.langsmith.project,
+            name="KPI::AlignmentSnapshot",
+            inputs={
+                "source": "local-observability-evals",
+                "learning_present": bool(learning),
+                "value_present": bool(value),
+            },
+            outputs={
+                "learning_kpis": learning_kpis,
+                "value_kpis": value_kpis,
+                **{f"learning_{k}": v for k, v in learning_flat_kpis.items()},
+                **{f"value_{k}": v for k, v in value_flat_kpis.items()},
+                "published_at": _iso_now().isoformat(),
+            },
+            tags=[
+                "mcpee",
+                "kpi",
+                "alignment",
+                "dashboard",
+                f"scope:{telemetry_scope}",
+                f"host:{host_slug}",
+            ],
+            metadata={
+                "kpi_source": "alignment",
+                "kpi_kind": "snapshot",
+                "host_project": host_project,
+                "host_project_slug": host_slug,
+                "telemetry_scope": telemetry_scope,
+                **{f"learning_{k}": v for k, v in learning_flat_kpis.items()},
+                **{f"value_{k}": v for k, v in value_flat_kpis.items()},
+            },
+            total_cost=float(value_kpis.get("total_cost_usd", 0.0) or 0.0),
+            total_tokens=int(value_kpis.get("total_tokens", 0) or 0),
+            run_type="llm",
+        )
+        alignment_feedback = {
+            **{f"learning_{k}": v for k, v in learning_flat_kpis.items()},
+            **{f"value_{k}": v for k, v in value_flat_kpis.items()},
+        }
+        _publish_feedback_metrics(client, run_id=run_id, metrics=alignment_feedback, source="alignment")
+        published += 1
+
+    print(
+        f"Published KPI runs: {published} to project '{cfg.langsmith.project}' "
+        f"(host_project='{host_project}', scope='{telemetry_scope}')."
+    )
+    if published == 0:
+        print("No local KPI report JSON files were found in observability/evals.")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/setup/install-project-hooks.ps1

@@ -0,0 +1,33 @@
+param(
+    [switch]$Force
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$repoRoot = (& git rev-parse --show-toplevel 2>$null)
+if (-not $repoRoot) {
+    throw 'Not inside a git repository.'
+}
+
+Set-Location $repoRoot
+$hooksDir = Join-Path $repoRoot '.githooks'
+$postCommitHook = Join-Path $hooksDir 'post-commit'
+
+if (-not (Test-Path $postCommitHook)) {
+    throw "Missing hook template: $postCommitHook"
+}
+
+$currentHooksPath = (& git config --local --get core.hooksPath 2>$null)
+if (-not $Force -and $currentHooksPath -and $currentHooksPath -ne '.githooks') {
+    Write-Warning "core.hooksPath is already set to '$currentHooksPath'. Skipping update. Use -Force to override."
+    exit 0
+}
+
+& git config --local core.hooksPath .githooks
+if ($LASTEXITCODE -ne 0) {
+    throw 'Failed to configure core.hooksPath.'
+}
+
+Write-Host '[mcpee] Git hooks configured: core.hooksPath=.githooks'
+Write-Host '[mcpee] Hook active: post-commit -> scripts/ops/post-commit-refresh.ps1'

package/scripts/setup/setup-prerequisites.ps1

@@ -111,12 +111,36 @@ function Install-PythonRequirements {
 
 function Resolve-PythonCommand {
     if (Test-Command 'py') {
-        return @('py', '-3.14')
+        return @('py', '-3')
     }
     if (Test-Command 'python') {
         return @('python')
     }
-    throw 'Python 3.14 is required for graphify MCP. Install Python first: https://www.python.org/downloads/'
+    throw 'Python 3 is required for MCP scripts. Install Python first: https://www.python.org/downloads/'
+}
+
+function Ensure-PythonModuleInstalled {
+    param(
+        [Parameter(Mandatory = $true)][string]$PythonCommand,
+        [string[]]$PythonArgs = @(),
+        [Parameter(Mandatory = $true)][string]$Module,
+        [Parameter(Mandatory = $true)][string]$Package
+    )
+
+    if (Test-PythonImport -PythonCommand $PythonCommand -PythonArgs $PythonArgs -Module $Module) {
+        Write-Host "[ok] Python module '$Module' already available"
+        return
+    }
+
+    Write-Host "[install] $PythonCommand $($PythonArgs -join ' ') -m pip install $Package"
+    & $PythonCommand @PythonArgs -m pip install $Package
+    if ($LASTEXITCODE -ne 0) {
+        throw "Failed to install Python package '$Package'"
+    }
+
+    if (-not (Test-PythonImport -PythonCommand $PythonCommand -PythonArgs $PythonArgs -Module $Module)) {
+        throw "Python module '$Module' is still unavailable after installing '$Package'"
+    }
 }
 
 Write-Host '== MCP platform prerequisites setup =='
@@ -159,21 +183,24 @@ if (-not $SkipRepomix) {
     Install-ToolFromManifest -Tool $toolByCommand['repomix']
 }
 
-if (-not $SkipGraphify) {
-    $py = Resolve-PythonCommand
-    $pyCmd = $py[0]
-    $pyArgs = @()
-    if ($py.Length -gt 1) {
-        $pyArgs = $py[1..($py.Length - 1)]
-    }
+$py = Resolve-PythonCommand
+$pyCmd = $py[0]
+$pyArgs = @()
+if ($py.Length -gt 1) {
+    $pyArgs = $py[1..($py.Length - 1)]
+}
 
-    if ($py.Length -gt 1) {
-        Write-Host "[setup] Using Python launcher: $($py -join ' ')"
-    }
-    else {
-        Write-Host "[setup] Using Python launcher: $pyCmd"
-    }
+if ($py.Length -gt 1) {
+    Write-Host "[setup] Using Python launcher: $($py -join ' ')"
+}
+else {
+    Write-Host "[setup] Using Python launcher: $pyCmd"
+}
+
+# Core observability dependency used by KPI publishing and telemetry export.
+Ensure-PythonModuleInstalled -PythonCommand $pyCmd -PythonArgs $pyArgs -Module 'langsmith' -Package 'langsmith'
 
+if (-not $SkipGraphify) {
     Install-PythonRequirements -PythonCommand $pyCmd -PythonArgs $pyArgs -RequirementsPath 'requirements.txt'
 
     if (-not (Test-PythonImport -PythonCommand $pyCmd -PythonArgs $pyArgs -Module 'graphify.serve')) {