@arcadialdev/arcality 3.0.4 → 4.0.1

package/scripts/init.mjs

@@ -2,39 +2,39 @@
 // scripts/init.mjs — Command: arcality init
 // Single-configuration setup flow:
 //   1. Prompt API key → validate with backend
-//   2. Prompt project name, baseUrl, username, password
+//   2. Prompt project name, baseUrl, username, password
 //   3. Detect framework (package.json only, NO .git)
 //   4. Create project via POST /api/v1/projects
-//   5. Write arcality.config
-
-import 'dotenv/config';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'url';
-import { intro, outro, text, password as passwordPrompt, spinner, note, isCancel, cancel, confirm } from '@clack/prompts';
-import chalk from 'chalk';
-import {
-    configExists,
-    loadProjectConfig,
-    saveProjectConfig,
-    createConfig,
-    isRealProjectId,
-} from '../src/configManager.mjs';
-import { getApiUrl } from '../src/configLoader.mjs';
-import { installPlaywrightAssets, getPlaywrightInstallCommand } from '../src/playwrightAssets.mjs';
+//   5. Write arcality.config
+
+import 'dotenv/config';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'url';
+import { intro, outro, text, password as passwordPrompt, spinner, note, isCancel, cancel, confirm } from '@clack/prompts';
+import chalk from 'chalk';
+import {
+    configExists,
+    loadProjectConfig,
+    saveProjectConfig,
+    createConfig,
+    isRealProjectId,
+} from '../src/configManager.mjs';
+import { getApiUrl } from '../src/configLoader.mjs';
+import { installPlaywrightAssets, getPlaywrightInstallCommand } from '../src/playwrightAssets.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PACKAGE_ROOT = process.env.ARCALITY_ROOT || path.resolve(__dirname, '..');
 
-// ── Helpers ──
+// ── Helpers ──
 
-function getVersion() {
-    try {
-        const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
-        return pkg.version || 'unknown';
-    } catch {
-        return 'unknown';
+function getVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+        return pkg.version || 'unknown';
+    } catch {
+        return 'unknown';
     }
 }
 
@@ -57,93 +57,93 @@ function detectFramework(projectRoot) {
     }
 }
 
-function isValidUrl(url) {
-    try {
-        const u = new URL(url);
-        return u.protocol === 'http:' || u.protocol === 'https:';
-    } catch {
-        return false;
-    }
-}
-
-function showInitBanner(version, projectRoot) {
-    const sentinelAscii = `
- █████  ██████   ██████  █████  ██      ██ ████████ ██    ██
-██   ██ ██   ██ ██      ██   ██ ██      ██    ██     ██  ██
-███████ ██████  ██      ███████ ██      ██    ██      ████
-██   ██ ██   ██ ██      ██   ██ ██      ██    ██       ██
-██   ██ ██   ██  ██████ ██   ██ ███████ ██    ██       ██`;
-
-    intro(chalk.gray(sentinelAscii));
-
-    note(
-        chalk.gray('◉ Modo de Configuración: ') + chalk.bold.white('ACTIVO') + '\n' +
-        chalk.gray('◉ Enlace con Backend:    ') + chalk.bold.white('PREPARANDO') + '\n' +
-        chalk.gray('◉ Generador de Contexto: ') + chalk.bold.white('DISPONIBLE') + '\n' +
-        chalk.gray('─'.repeat(50)) + '\n' +
-        chalk.gray('Versión del Sistema: ') + chalk.white(`v${version}`),
-        'Estado Central de Arcality'
-    );
-
-    note(
-        chalk.gray('Nodo Objetivo: ') + chalk.white(process.env.NODE_ENV ?? 'development') + '\n' +
-        chalk.gray('Proyecto Local: ') + chalk.white(projectRoot) + '\n' +
-        chalk.gray('Comando:       ') + chalk.white('arcality init'),
-        'Inicialización del Proyecto'
-    );
-}
+function isValidUrl(url) {
+    try {
+        const u = new URL(url);
+        return u.protocol === 'http:' || u.protocol === 'https:';
+    } catch {
+        return false;
+    }
+}
+
+function showInitBanner(version, projectRoot) {
+    const sentinelAscii = `
+ █████  ██████   ██████  █████  ██      ██ ████████ ██    ██
+██   ██ ██   ██ ██      ██   ██ ██      ██    ██     ██  ██
+███████ ██████  ██      ███████ ██      ██    ██      ████
+██   ██ ██   ██ ██      ██   ██ ██      ██    ██       ██
+██   ██ ██   ██  ██████ ██   ██ ███████ ██    ██       ██`;
+
+    intro(chalk.gray(sentinelAscii));
+
+    note(
+        chalk.gray('◉ Modo de Configuración: ') + chalk.bold.white('ACTIVO') + '\n' +
+        chalk.gray('◉ Enlace con Backend:    ') + chalk.bold.white('PREPARANDO') + '\n' +
+        chalk.gray('◉ Generador de Contexto: ') + chalk.bold.white('DISPONIBLE') + '\n' +
+        chalk.gray('─'.repeat(50)) + '\n' +
+        chalk.gray('Versión del Sistema: ') + chalk.white(`v${version}`),
+        'Estado Central de Arcality'
+    );
+
+    note(
+        chalk.gray('Nodo Objetivo: ') + chalk.white(process.env.NODE_ENV ?? 'development') + '\n' +
+        chalk.gray('Proyecto Local: ') + chalk.white(projectRoot) + '\n' +
+        chalk.gray('Comando:       ') + chalk.white('arcality init'),
+        'Inicialización del Proyecto'
+    );
+}
 
 // ── Main ──
 
-async function main() {
-    const version = getVersion();
-    const projectRoot = process.cwd();
-
-    console.clear();
-    showInitBanner(version, projectRoot);
+async function main() {
+    const version = getVersion();
+    const projectRoot = process.cwd();
+
+    console.clear();
+    showInitBanner(version, projectRoot);
 
     // ── Check for existing config ──
-    if (configExists(projectRoot)) {
-        const existing = loadProjectConfig(projectRoot);
-        if (existing) {
-            note(
-                chalk.yellow('⚠️  Ya existe un arcality.config en este proyecto.') + '\n\n' +
-                chalk.white('  Proyecto: ') + chalk.cyan(existing.project?.name || 'unknown') + '\n' +
-                chalk.white('  Base URL: ') + chalk.cyan(existing.project?.baseUrl || 'unknown') + '\n' +
-                chalk.white('  ID del Proyecto: ') + chalk.gray(existing.projectId || 'desconocido'),
-                'Configuración Existente'
-            );
-
-            const overwrite = await confirm({
-                message: '¿Deseas reconfigurar? Esto creará un NUEVO proyecto en backend.',
-            });
-
-            if (isCancel(overwrite) || !overwrite) {
-                outro(chalk.cyan('Configuración sin cambios. Usa `arcality run` para iniciar.'));
-                return;
-            }
-        }
-    }
+    if (configExists(projectRoot)) {
+        const existing = loadProjectConfig(projectRoot);
+        if (existing) {
+            note(
+                chalk.yellow('⚠️  Ya existe un arcality.config en este proyecto.') + '\n\n' +
+                chalk.white('  Proyecto: ') + chalk.cyan(existing.project?.name || 'unknown') + '\n' +
+                chalk.white('  Base URL: ') + chalk.cyan(existing.project?.baseUrl || 'unknown') + '\n' +
+                chalk.white('  ID del Proyecto: ') + chalk.gray(existing.projectId || 'desconocido'),
+                'Configuración Existente'
+            );
+
+            const overwrite = await confirm({
+                message: '¿Deseas reconfigurar? Esto creará un NUEVO proyecto en backend.',
+            });
+
+            if (isCancel(overwrite) || !overwrite) {
+                outro(chalk.cyan('Configuración sin cambios. Usa `arcality run` para iniciar.'));
+                return;
+            }
+        }
+    }
 
     // ── Step 1: API Key ──
     const apiKey = await text({
-        message: chalk.cyan('🔑 Ingresa tu API Key de Arcality:'),
+        message: chalk.cyan('🔑 Ingresa tu API Key de Arcality:'),
         placeholder: 'arc_live_xxxxx',
         validate: (v) => {
-            if (!v || !v.trim()) return 'La API Key es obligatoria.';
-            if (!v.startsWith('arc_')) return 'La API Key debe iniciar con "arc_"';
+            if (!v || !v.trim()) return 'La API Key es obligatoria.';
+            if (!v.startsWith('arc_')) return 'La API Key debe iniciar con "arc_"';
         },
     });
 
     if (isCancel(apiKey)) {
-        cancel('Configuración cancelada.');
+        cancel('Configuración cancelada.');
         process.exit(0);
     }
 
     // ── Step 2: Validate API Key (uses internal API URL) ──
     const apiUrl = getApiUrl();
     const s = spinner();
-    s.start('Validando API Key...');
+    s.start('Validando API Key...');
 
     let organizationId = null;
 
@@ -159,12 +159,12 @@ async function main() {
         if (!res.ok) {
             const errText = await res.text().catch(() => '');
             const errorMap = {
-                401: '❌ API Key inválida. Revísala e inténtalo de nuevo.',
-                403: `❌ Autenticación fallida (HTTP 403). El servidor respondió: ${errText.slice(0, 150)}`,
-            };
-            const msg = errorMap[res.status] || `❌ Error del servidor (HTTP ${res.status}): ${errText.slice(0, 150)}`;
-            s.stop(chalk.red(msg));
-            console.log(chalk.yellow('\n   Presiona Enter para volver al menú...'));
+                401: '❌ API Key inválida. Revísala e inténtalo de nuevo.',
+                403: `❌ Autenticación fallida (HTTP 403). El servidor respondió: ${errText.slice(0, 150)}`,
+            };
+            const msg = errorMap[res.status] || `❌ Error del servidor (HTTP ${res.status}): ${errText.slice(0, 150)}`;
+            s.stop(chalk.red(msg));
+            console.log(chalk.yellow('\n   Presiona Enter para volver al menú...'));
             // Salida limpia (código 0) para que el menú padre no interprete esto como crash
             await new Promise(r => setTimeout(r, 3000));
             process.exit(0);
@@ -173,77 +173,77 @@ async function main() {
         const data = await res.json();
         organizationId = data.organizationId || data.organization_id || null;
 
-        s.stop(chalk.green('✅ API Key validada correctamente'));
+        s.stop(chalk.green('✅ API Key validada correctamente'));
 
         if (data.plan) {
             note(
-                chalk.bold.white('📋 Plan: ') + chalk.cyan(data.plan) + '\n' +
-                chalk.bold.white('🏢 Organización: ') + chalk.cyan(organizationId || 'N/A'),
-                'Información de la Cuenta'
+                chalk.bold.white('📋 Plan: ') + chalk.cyan(data.plan) + '\n' +
+                chalk.bold.white('🏢 Organización: ') + chalk.cyan(organizationId || 'N/A'),
+                'Información de la Cuenta'
             );
         }
     } catch (err) {
-        s.stop(chalk.red(`❌ No se pudo conectar al backend de Arcality: ${err.message}`));
-        console.log(chalk.yellow('   Asegúrate de que el backend esté activo y accesible.'));
+        s.stop(chalk.red(`❌ No se pudo conectar al backend de Arcality: ${err.message}`));
+        console.log(chalk.yellow('   Asegúrate de que el backend esté activo y accesible.'));
         await new Promise(r => setTimeout(r, 3000));
         process.exit(0);
     }
 
     // ── Step 3: Project details ──
     const projectName = await text({
-        message: chalk.cyan('📋 Nombre del proyecto:'),
-        placeholder: 'Mi Portal QA',
-        validate: (v) => {
-            if (!v || v.trim().length < 2) return 'El nombre del proyecto es obligatorio (mínimo 2 caracteres).';
-        },
-    });
-    if (isCancel(projectName)) { cancel('Configuración cancelada.'); process.exit(0); }
-
-    const baseUrl = await text({
-        message: chalk.cyan('🌐 URL base de la aplicación a probar:'),
-        placeholder: 'https://staging.example.com',
-        validate: (v) => {
-            if (!v || !v.trim()) return 'La URL base es obligatoria.';
-            if (!isValidUrl(v)) return 'URL inválida. Usa http:// o https://';
-        },
-    });
-    if (isCancel(baseUrl)) { cancel('Configuración cancelada.'); process.exit(0); }
-
-    const hasLogin = await confirm({
-        message: chalk.cyan('🔐 ¿Tu aplicación requiere inicio de sesión/autenticación?'),
-    });
-    if (isCancel(hasLogin)) { cancel('Configuración cancelada.'); process.exit(0); }
+        message: chalk.cyan('📋 Nombre del proyecto:'),
+        placeholder: 'Mi Portal QA',
+        validate: (v) => {
+            if (!v || v.trim().length < 2) return 'El nombre del proyecto es obligatorio (mínimo 2 caracteres).';
+        },
+    });
+    if (isCancel(projectName)) { cancel('Configuración cancelada.'); process.exit(0); }
+
+    const baseUrl = await text({
+        message: chalk.cyan('🌐 URL base de la aplicación a probar:'),
+        placeholder: 'https://staging.example.com',
+        validate: (v) => {
+            if (!v || !v.trim()) return 'La URL base es obligatoria.';
+            if (!isValidUrl(v)) return 'URL inválida. Usa http:// o https://';
+        },
+    });
+    if (isCancel(baseUrl)) { cancel('Configuración cancelada.'); process.exit(0); }
+
+    const hasLogin = await confirm({
+        message: chalk.cyan('🔐 ¿Tu aplicación requiere inicio de sesión/autenticación?'),
+    });
+    if (isCancel(hasLogin)) { cancel('Configuración cancelada.'); process.exit(0); }
 
     let username = '';
     let password = '';
 
     if (hasLogin) {
-        username = await text({
-            message: chalk.cyan('👤 Usuario o correo de acceso:'),
-            validate: (v) => {
-                if (!v || !v.trim()) return 'El usuario es obligatorio.';
-            },
-        });
-        if (isCancel(username)) { cancel('Configuración cancelada.'); process.exit(0); }
-
-        password = await passwordPrompt({
-            message: chalk.cyan('🔒 Contraseña de acceso:'),
-            validate: (v) => {
-                if (!v || !v.length) return 'La contraseña es obligatoria.';
-            },
-        });
-        if (isCancel(password)) { cancel('Configuración cancelada.'); process.exit(0); }
+        username = await text({
+            message: chalk.cyan('👤 Usuario o correo de acceso:'),
+            validate: (v) => {
+                if (!v || !v.trim()) return 'El usuario es obligatorio.';
+            },
+        });
+        if (isCancel(username)) { cancel('Configuración cancelada.'); process.exit(0); }
+
+        password = await passwordPrompt({
+            message: chalk.cyan('🔒 Contraseña de acceso:'),
+            validate: (v) => {
+                if (!v || !v.length) return 'La contraseña es obligatoria.';
+            },
+        });
+        if (isCancel(password)) { cancel('Configuración cancelada.'); process.exit(0); }
     }
 
     // ── Step 4: Detect framework ──
     const frameworkDetected = detectFramework(projectRoot);
     if (frameworkDetected) {
-        console.log(chalk.gray(`   🛠️  Framework detectado: ${chalk.magenta(frameworkDetected)}`));
+        console.log(chalk.gray(`   🛠️  Framework detectado: ${chalk.magenta(frameworkDetected)}`));
     }
 
     // ── Step 5: Create project in backend ──
     const sCreate = spinner();
-    sCreate.start('Creando proyecto en el backend de Arcality...');
+    sCreate.start('Creando proyecto en el backend de Arcality...');
 
     let projectId = null;
     try {
@@ -273,152 +273,177 @@ async function main() {
             // If response is HTML (e.g. Cloudflare 521), show a clean message
             const isHtml = errText.trim().startsWith('<');
             const displayError = isHtml
-                ? `El servidor backend de Arcality no esta disponible temporalmente (HTTP ${res.status}).`
-                : `HTTP ${res.status}: ${errText.slice(0, 200)}`;
+                ? `El servidor backend de Arcality no esta disponible temporalmente (HTTP ${res.status}).`
+                : `HTTP ${res.status}: ${errText.slice(0, 200)}`;
 
-            sCreate.stop(chalk.red(`No se pudo crear el proyecto en Arcality: ${displayError.replace(/El proyecto.*$/i, '').trim()}`));
+            sCreate.stop(chalk.red(`No se pudo crear el proyecto en Arcality: ${displayError.replace(/El proyecto.*$/i, '').trim()}`));
             // Don't exit — write the config with a local-only project ID so user can still run
-            note(
-                chalk.white('No se guardo arcality.config porque Arcality requiere un proyecto real conectado al backend.'),
-                'Configuracion detenida'
-            );
-            process.exit(1);
+            note(
+                chalk.white('No se guardo arcality.config porque Arcality requiere un proyecto real conectado al backend.'),
+                'Configuracion detenida'
+            );
+            process.exit(1);
         } else {
             const created = await res.json();
-            projectId = created.id || created.Id;
-            if (!isRealProjectId(projectId)) {
-                sCreate.stop(chalk.red('El backend no devolvio un Project ID valido.'));
-                note(
-                    chalk.white('No se guardo arcality.config. Toda instancia de Arcality debe estar ligada a un proyecto real.'),
-                    'Configuracion detenida'
-                );
-                process.exit(1);
-            }
+            projectId = created.id || created.Id;
+            if (!isRealProjectId(projectId)) {
+                sCreate.stop(chalk.red('El backend no devolvio un Project ID valido.'));
+                note(
+                    chalk.white('No se guardo arcality.config. Toda instancia de Arcality debe estar ligada a un proyecto real.'),
+                    'Configuracion detenida'
+                );
+                process.exit(1);
+            }
             organizationId = organizationId || created.organizationId || created.organization_id || null;
-            sCreate.stop(chalk.green(`✅ Proyecto creado: "${projectName.trim()}" (${projectId})`));
-        }
-    } catch (err) {
-        sCreate.stop(chalk.red(`No se pudo conectar con el servidor de Arcality: ${err.message}`));
-        note(
-            chalk.white('No se guardo arcality.config porque la herramienta no funciona en modo offline/local.'),
-            'Configuracion detenida'
-        );
-        process.exit(1);
-    }
+            sCreate.stop(chalk.green(`✅ Proyecto creado: "${projectName.trim()}" (${projectId})`));
+        }
+    } catch (err) {
+        sCreate.stop(chalk.red(`No se pudo conectar con el servidor de Arcality: ${err.message}`));
+        note(
+            chalk.white('No se guardo arcality.config porque la herramienta no funciona en modo offline/local.'),
+            'Configuracion detenida'
+        );
+        process.exit(1);
+    }
 
     // ── Step 6: Write arcality.config ──
     const config = createConfig({
         apiKey: apiKey.trim(),
         organizationId,
         projectId,
-        projectName: projectName.trim(),
-        baseUrl: baseUrl.trim(),
-        frameworkDetected,
-        username: username.trim(),
-        password,
-        arcalityVersion: version,
-    });
-
-    saveProjectConfig(config, projectRoot);
-
-    const sPlaywright = spinner();
-    sPlaywright.start('Preparando navegador de pruebas (Chromium + ffmpeg)...');
-    let playwrightReady = true;
-
-    try {
-        await installPlaywrightAssets({ cwd: PACKAGE_ROOT });
-        sPlaywright.stop(chalk.green('Playwright listo para ejecutar misiones'));
-    } catch (err) {
-        playwrightReady = false;
-        sPlaywright.stop(chalk.yellow(`No se pudieron instalar los assets de Playwright: ${err.message}`));
-        note(
-            chalk.white('La configuracion del proyecto ya fue guardada, pero antes de la primera mision ejecuta:') + '\n\n' +
-            chalk.cyan(getPlaywrightInstallCommand()),
-            'Accion Manual Requerida'
-        );
-    }
+        projectName: projectName.trim(),
+        baseUrl: baseUrl.trim(),
+        frameworkDetected,
+        username: username.trim(),
+        password,
+        arcalityVersion: version,
+    });
+
+    saveProjectConfig(config, projectRoot);
 
-    // ── Step 7: Custom QA Context ──
+    const sPlaywright = spinner();
+    sPlaywright.start('Preparando navegador de pruebas (Chromium + ffmpeg)...');
+    let playwrightReady = true;
+
+    try {
+        await installPlaywrightAssets({ cwd: PACKAGE_ROOT });
+        sPlaywright.stop(chalk.green('Playwright listo para ejecutar misiones'));
+    } catch (err) {
+        playwrightReady = false;
+        sPlaywright.stop(chalk.yellow(`No se pudieron instalar los assets de Playwright: ${err.message}`));
+        note(
+            chalk.white('La configuracion del proyecto ya fue guardada, pero antes de la primera mision ejecuta:') + '\n\n' +
+            chalk.cyan(getPlaywrightInstallCommand()),
+            'Accion Manual Requerida'
+        );
+    }
+
+    // ── Step 7: Custom QA Context ──
     note(
         chalk.white('El archivo ') + chalk.cyan('.arcality/qa-context.md') + chalk.white(' se inyecta al prompt del agente antes de cada misión.') + '\n' +
-        chalk.white('Úsalo para reglas del negocio, navegación especial y anti-patrones que Arcality deba respetar siempre.'),
+        chalk.white('Úsalo para reglas del negocio, navegación especial y anti-patrones que Arcality deba respetar siempre.') + '\n' +
+        chalk.white('Complementa el archivo con ') + chalk.cyan('.arcality/qa-context.meta.json') + chalk.white(' para versionar responsables y cambios.'),
         'QA Context Local'
     );
-
-    const wantsContext = await confirm({
-        message: chalk.cyan('📄 ¿Deseas generar un archivo local QA Context (.arcality/qa-context.md) para enseñarle al agente reglas del negocio?'),
-    });
-    
-    if (!isCancel(wantsContext) && wantsContext) {
-        const arcalityDir = path.join(projectRoot, '.arcality');
-        if (!fs.existsSync(arcalityDir)) {
+
+    const wantsContext = await confirm({
+        message: chalk.cyan('📄 ¿Deseas generar un archivo local QA Context (.arcality/qa-context.md) para enseñarle al agente reglas del negocio?'),
+    });
+    
+    if (!isCancel(wantsContext) && wantsContext) {
+        const arcalityDir = path.join(projectRoot, '.arcality');
+        if (!fs.existsSync(arcalityDir)) {
             fs.mkdirSync(arcalityDir, { recursive: true });
         }
         
         const qaContextPath = path.join(arcalityDir, 'qa-context.md');
+        const qaContextMetaPath = path.join(arcalityDir, 'qa-context.meta.json');
         const qaTemplate = `# Arcality QA Context
 <!--
 Este archivo se inyecta antes de cada mision.
 Escribe reglas cortas, especificas y accionables.
-Usa un bullet por regla real.
-Los bullets que empiecen con "Ejemplo:" se ignoran hasta que los reemplaces.
--->
-
-## Reglas del Dominio
-<!-- Restricciones de negocio, validaciones duras, formatos, limites -->
-- Ejemplo: Un usuario no puede registrar mas de 24 horas en un mismo dia.
-- Ejemplo: El campo "Numero de empleado" debe conservar ceros a la izquierda.
-
-## Navegacion y UI Especial
-<!-- Pasos raros de la interfaz, cargas lentas, modales, menus no obvios -->
-- Ejemplo: Despues de elegir un proyecto, espera a que cargue la tabla antes de registrar horas.
-- Ejemplo: El menu de acciones siempre se abre desde el icono ":" de la primera fila.
-
-## Casos Prohibidos y Anti-patrones
-<!-- Cosas que Arcality nunca debe intentar -->
-- Ejemplo: No uses "Continuar con Microsoft".
-- Ejemplo: No cierres el modal con Escape; usa el boton "Cancelar".
-
-## Datos y Credenciales de Prueba
-<!-- Usuarios de prueba, ambientes, datos obligatorios o datos que deben evitarse -->
-- Ejemplo: Usa el usuario QA_TIMESHEET_01 para pruebas de captura diaria.
-- Ejemplo: No reutilices folios ya aprobados.
-
+Usa un bullet por regla real.
+Los bullets que empiecen con "Ejemplo:" se ignoran hasta que los reemplaces.
+-->
+
+## Reglas del Dominio
+<!-- Restricciones de negocio, validaciones duras, formatos, limites -->
+- Ejemplo: Un usuario no puede registrar mas de 24 horas en un mismo dia.
+- Ejemplo: El campo "Numero de empleado" debe conservar ceros a la izquierda.
+
+## Navegacion y UI Especial
+<!-- Pasos raros de la interfaz, cargas lentas, modales, menus no obvios -->
+- Ejemplo: Despues de elegir un proyecto, espera a que cargue la tabla antes de registrar horas.
+- Ejemplo: El menu de acciones siempre se abre desde el icono ":" de la primera fila.
+
+## Casos Prohibidos y Anti-patrones
+<!-- Cosas que Arcality nunca debe intentar -->
+- Ejemplo: No uses "Continuar con Microsoft".
+- Ejemplo: No cierres el modal con Escape; usa el boton "Cancelar".
+
+## Datos y Credenciales de Prueba
+<!-- Usuarios de prueba, ambientes, datos obligatorios o datos que deben evitarse -->
+- Ejemplo: Usa el usuario QA_TIMESHEET_01 para pruebas de captura diaria.
+- Ejemplo: No reutilices folios ya aprobados.
+
 ## Resultado Esperado y Validaciones Clave
 <!-- Como saber que la mision realmente termino bien -->
 - Ejemplo: La prueba termina cuando el registro aparece en la tabla "Timesheet - Hoy" de /welcome.
 - Ejemplo: Si aparece la leyenda "Expirado" en el proyecto, la prueba sigue siendo valida.
 `;
+        const qaMetaTemplate = {
+            version: '1.0.0',
+            updated_by: username.trim() || 'qa.owner@empresa.com',
+            approved_by: '',
+            owner_team: 'QA',
+            effective_from: new Date().toISOString().slice(0, 10),
+            change_summary: 'Creacion inicial del QA Context para este proyecto.',
+            tags: ['business-rules', 'ui-navigation']
+        };
         if (!fs.existsSync(qaContextPath)) {
             fs.writeFileSync(qaContextPath, qaTemplate);
             note(chalk.green(`✅ QA Context creado en: ${qaContextPath}`), 'Contexto Guardado');
         } else {
             note(chalk.cyan(`ℹ️ QA Context ya existente: ${qaContextPath}`), 'Contexto Detectado');
         }
+        if (!fs.existsSync(qaContextMetaPath)) {
+            fs.writeFileSync(qaContextMetaPath, JSON.stringify(qaMetaTemplate, null, 2), 'utf8');
+            note(chalk.green(`✅ QA Context metadata creada en: ${qaContextMetaPath}`), 'Metadata Guardada');
+        } else {
+            note(chalk.cyan(`ℹ️ QA Context metadata ya existente: ${qaContextMetaPath}`), 'Metadata Detectada');
+        }
+
+        note(
+            chalk.white('Si ejecutas Arcality en CI, la gobernanza del contexto se aplica en modo ') +
+            chalk.cyan('strict') + chalk.white(' por defecto.') + '\n' +
+            chalk.white('Puedes controlarlo con la variable ') + chalk.cyan('ARCALITY_QA_CONTEXT_GOVERNANCE') +
+            chalk.white(' usando ') + chalk.cyan('off') + chalk.white(', ') + chalk.cyan('warn') + chalk.white(' o ') + chalk.cyan('strict') + chalk.white('.'),
+            'Gobernanza del Contexto'
+        );
     }
 
     // ── Summary ──
     note(
-        chalk.green('✅ arcality.config creado correctamente') + '\n\n' +
-        chalk.bold.white('  Proyecto: ') + chalk.cyan(config.project.name) + '\n' +
-        chalk.bold.white('  URL Base: ') + chalk.cyan(config.project.baseUrl) + '\n' +
-        chalk.bold.white('  Framework: ') + chalk.magenta(config.project.frameworkDetected || 'N/A') + '\n' +
-        chalk.bold.white('  ID del Proyecto: ') + chalk.gray(config.projectId) + '\n' +
-        chalk.bold.white('  Carpeta de Misiones: ') + chalk.yellow(config.runtime.yamlOutputDir) + '\n' +
-        chalk.bold.white('  Playwright: ') + (playwrightReady ? chalk.green('listo') : chalk.yellow('pendiente de instalacion manual')),
-        'Configuración Guardada'
-    );
-
-    outro(
-        chalk.cyanBright('🚀 Listo. Ejecuta ') +
-        chalk.bold.white('arcality run') +
-        chalk.cyanBright(' o ') +
-        chalk.bold.white('arcality') +
-        chalk.cyanBright(' para comenzar a probar.')
-    );
-}
-
-main().catch(err => {
-    console.error(chalk.red('  ❌ Error durante init:'), err.message);
-    process.exit(1);
-});
+        chalk.green('✅ arcality.config creado correctamente') + '\n\n' +
+        chalk.bold.white('  Proyecto: ') + chalk.cyan(config.project.name) + '\n' +
+        chalk.bold.white('  URL Base: ') + chalk.cyan(config.project.baseUrl) + '\n' +
+        chalk.bold.white('  Framework: ') + chalk.magenta(config.project.frameworkDetected || 'N/A') + '\n' +
+        chalk.bold.white('  ID del Proyecto: ') + chalk.gray(config.projectId) + '\n' +
+        chalk.bold.white('  Carpeta de Misiones: ') + chalk.yellow(config.runtime.yamlOutputDir) + '\n' +
+        chalk.bold.white('  Playwright: ') + (playwrightReady ? chalk.green('listo') : chalk.yellow('pendiente de instalacion manual')),
+        'Configuración Guardada'
+    );
+
+    outro(
+        chalk.cyanBright('🚀 Listo. Ejecuta ') +
+        chalk.bold.white('arcality run') +
+        chalk.cyanBright(' o ') +
+        chalk.bold.white('arcality') +
+        chalk.cyanBright(' para comenzar a probar.')
+    );
+}
+
+main().catch(err => {
+    console.error(chalk.red('  ❌ Error durante init:'), err.message);
+    process.exit(1);
+});