@jaguilar87/gaia-ops 5.0.0-beta.4 → 5.0.0-beta.6

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "gaia-security",
       "description": "Keeps you in the loop only when it matters. Gaia Security analyzes every command and classifies it into risk tiers: read-only queries run freely, simulations and validations pass through, and state-changing operations (create, delete, apply, push) pause for your explicit approval before executing. Irreversible commands like dropping databases or deleting cloud infrastructure are permanently blocked.",
-      "version": "5.0.0-beta.4",
+      "version": "5.0.0-beta.6",
       "source": "./dist/gaia-security"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-ops",
-  "version": "5.0.0-beta.4",
+  "version": "5.0.0-beta.6",
   "description": "Security-first orchestrator with specialized agents, hooks, and governance for AI coding",
   "author": {
     "name": "jaguilar87"

package/bin/gaia-doctor.js

@@ -6,6 +6,25 @@
  * Verifies the complete Gaia-Ops installation is healthy.
  * Run after install, update, or when things seem broken.
  *
+ * Checks (in order):
+ *   1. Gaia-Ops version    - package.json readable
+ *   2. Claude Code         - CLI installed (prerequisite)
+ *   3. Python              - Python 3.9+ available (hooks need it)
+ *   4. Plugin mode         - ops vs security, registry valid
+ *   5. Symlinks            - .claude/ symlinks resolve to package content
+ *   6. Identity            - orchestrator agent configured in settings
+ *   7. Settings            - hooks registered, permissions, deny rules
+ *   8. Hook files          - all hook scripts present on disk
+ *   9. project-context     - project-context.json valid and enriched
+ *  10. Project dirs        - paths declared in context exist
+ *  11. Memory dirs         - speckit, episodic memory dirs present
+ *
+ * Severity levels:
+ *   pass    - check passed
+ *   info    - informational, not an issue
+ *   warning - degrades functionality
+ *   error   - critical, Gaia will not work
+ *
  * Usage:
  *   npx gaia-doctor              # Full health check
  *   npx gaia-doctor --fix        # Attempt auto-fix for common issues
@@ -28,6 +47,17 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const CWD = process.cwd();
 
+// ============================================================================
+// Severity helpers
+// ============================================================================
+
+/** Create a check result with explicit severity. */
+function result(name, severity, detail, fix = null) {
+  // Backward-compatible `ok` field: pass and info are considered ok
+  const ok = severity === 'pass' || severity === 'info';
+  return { name, severity, ok, detail, ...(fix ? { fix } : {}) };
+}
+
 // ============================================================================
 // Health Checks
 // ============================================================================
@@ -35,111 +65,180 @@ const CWD = process.cwd();
 async function checkGaiaVersion() {
   try {
     const pkg = JSON.parse(await fs.readFile(join(__dirname, '..', 'package.json'), 'utf-8'));
-    return { name: 'Gaia-Ops', ok: true, detail: `v${pkg.version}` };
+    return result('Gaia-Ops', 'pass', `v${pkg.version}`);
+  } catch {
+    return result('Gaia-Ops', 'error', 'Version unknown', 'Reinstall @jaguilar87/gaia-ops');
+  }
+}
+
+async function checkPluginMode() {
+  // Determine plugin mode (ops vs security) and verify the registry.
+  const registryPath = join(CWD, '.claude', 'plugin-registry.json');
+
+  if (!existsSync(registryPath)) {
+    return result('Plugin mode', 'warning', 'No plugin-registry.json', 'Run gaia-scan or restart Claude Code');
+  }
+
+  try {
+    const registry = JSON.parse(await fs.readFile(registryPath, 'utf-8'));
+    const installed = (registry.installed || []).map(p => p.name);
+    const source = registry.source || 'unknown';
+
+    if (installed.includes('gaia-ops')) {
+      return result('Plugin mode', 'pass', `ops (source: ${source})`);
+    } else if (installed.includes('gaia-security')) {
+      return result('Plugin mode', 'pass', `security (source: ${source})`);
+    } else {
+      return result('Plugin mode', 'warning', `Unknown plugin: ${installed.join(', ')}`, 'Verify installation');
+    }
   } catch {
-    return { name: 'Gaia-Ops', ok: false, detail: 'Version unknown', fix: 'Reinstall @jaguilar87/gaia-ops' };
+    return result('Plugin mode', 'warning', 'Invalid plugin-registry.json', 'Delete and restart Claude Code');
   }
 }
 
 async function checkSymlinks() {
   const names = ['agents', 'tools', 'hooks', 'commands', 'templates', 'config', 'speckit', 'skills', 'CHANGELOG.md'];
-  const results = [];
+  // Critical symlinks that break core functionality if missing
+  const critical = new Set(['agents', 'hooks', 'skills']);
+  const sub = [];
   let valid = 0;
+  let hasCriticalMissing = false;
 
   for (const name of names) {
     const linkPath = join(CWD, '.claude', name);
     const exists = existsSync(linkPath);
 
     if (exists) {
-      // Verify symlink target actually resolves
       try {
         await fs.realpath(linkPath);
         valid++;
-        results.push({ name, status: 'ok' });
+        sub.push({ name, status: 'ok' });
       } catch {
-        results.push({ name, status: 'broken', fix: `rm .claude/${name} && gaia-scan` });
+        if (critical.has(name)) hasCriticalMissing = true;
+        sub.push({ name, status: 'broken', fix: `rm .claude/${name} && gaia-scan` });
       }
     } else {
-      results.push({ name, status: 'missing', fix: 'Run gaia-scan to recreate' });
+      if (critical.has(name)) hasCriticalMissing = true;
+      sub.push({ name, status: 'missing', fix: 'Run gaia-scan to recreate' });
     }
   }
 
+  if (valid === names.length) {
+    return { ...result('Symlinks', 'pass', `${valid}/${names.length} valid`), sub };
+  }
+
+  const severity = hasCriticalMissing ? 'error' : 'warning';
   return {
-    name: 'Symlinks',
-    ok: valid === names.length,
-    detail: `${valid}/${names.length} valid`,
-    fix: valid < names.length ? 'Run gaia-scan to recreate symlinks' : null,
-    sub: results
+    ...result('Symlinks', severity, `${valid}/${names.length} valid`, 'Run gaia-scan to recreate symlinks'),
+    sub
   };
 }
 
-async function checkClaudeMd() {
-  // CLAUDE.md is no longer generated -- identity is injected by UserPromptSubmit hook.
-  // If a project still has a CLAUDE.md from a previous version, that's fine but not required.
-  const path = join(CWD, 'CLAUDE.md');
-  if (existsSync(path)) {
-    return { name: 'CLAUDE.md', ok: true, detail: 'Present (legacy -- identity now injected by hook)' };
+async function checkIdentity() {
+  // Identity is defined in the orchestrator agent definition (.md file) and
+  // activated by the `agent` field in settings.local.json.  CLAUDE.md is no
+  // longer used and should not be present.
+  const issues = [];
+  const infos = [];
+
+  // 1. Check that orchestrator agent definition exists
+  const agentPath = join(CWD, '.claude', 'agents', 'gaia-orchestrator.md');
+  if (!existsSync(agentPath)) {
+    issues.push('gaia-orchestrator.md not found');
   }
-  return { name: 'CLAUDE.md', ok: true, detail: 'Not present (identity injected by UserPromptSubmit hook)' };
+
+  // 2. Check that settings.local.json has `agent` field pointing to orchestrator
+  const localSettingsPath = join(CWD, '.claude', 'settings.local.json');
+  if (existsSync(localSettingsPath)) {
+    try {
+      const data = JSON.parse(await fs.readFile(localSettingsPath, 'utf-8'));
+      if (data.agent === 'gaia-orchestrator') {
+        // pass -- correct agent configured
+      } else if (data.agent) {
+        issues.push(`Agent set to "${data.agent}" (expected "gaia-orchestrator")`);
+      } else {
+        issues.push('No agent field in settings.local.json');
+      }
+    } catch { /* handled by settings check */ }
+  } else {
+    issues.push('settings.local.json missing');
+  }
+
+  // 3. Warn if legacy CLAUDE.md is still present
+  const claudeMdPath = join(CWD, 'CLAUDE.md');
+  if (existsSync(claudeMdPath)) {
+    infos.push('Legacy CLAUDE.md present (no longer used)');
+  }
+
+  if (issues.length > 0) {
+    return result('Identity', 'error', issues.join('; '), 'Run gaia-scan or npx gaia-update');
+  }
+
+  if (infos.length > 0) {
+    return result('Identity', 'info', `Orchestrator configured -- ${infos.join('; ')}`);
+  }
+
+  return result('Identity', 'pass', 'Orchestrator agent configured');
 }
 
-async function checkSettingsJson() {
-  const path = join(CWD, '.claude', 'settings.json');
+async function checkSettings() {
+  // Configuration lives in settings.local.json (hooks, permissions, agent, env).
+  // settings.json exists for Claude Code to detect the project but may be empty.
+  const localPath = join(CWD, '.claude', 'settings.local.json');
 
-  if (!existsSync(path)) {
-    return { name: 'settings.json', ok: false, detail: 'Missing', fix: 'Run gaia-scan' };
+  if (!existsSync(localPath)) {
+    return result('Settings', 'error', 'settings.local.json missing', 'Run gaia-scan or npx gaia-update');
   }
 
   try {
-    const data = JSON.parse(await fs.readFile(path, 'utf-8'));
+    const data = JSON.parse(await fs.readFile(localPath, 'utf-8'));
     const issues = [];
+    const infos = [];
 
-    // Check hooks are configured — hooks may live in settings.json OR
-    // settings.local.json (gaia-update/gaia-scan puts them in local).
-    let hooksConfig = data.hooks || null;
-    const localPath = join(CWD, '.claude', 'settings.local.json');
-    if (!hooksConfig && existsSync(localPath)) {
-      try {
-        const localData = JSON.parse(await fs.readFile(localPath, 'utf-8'));
-        if (localData.hooks) hooksConfig = localData.hooks;
-      } catch { /* ignore parse errors */ }
-    }
-
+    // Check hooks configuration
+    const hooksConfig = data.hooks || null;
     if (!hooksConfig) {
-      issues.push('No hooks configured (check settings.json and settings.local.json)');
+      issues.push('No hooks configured');
     } else {
       const hookTypes = Object.keys(hooksConfig);
-      if (!hookTypes.includes('PreToolUse')) issues.push('Missing PreToolUse hook');
-      if (!hookTypes.includes('PostToolUse')) issues.push('Missing PostToolUse hook');
+      const required = ['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'SessionStart'];
+      const missing = required.filter(h => !hookTypes.includes(h));
+      if (missing.length > 0) {
+        issues.push(`Missing hooks: ${missing.join(', ')}`);
+      }
     }
 
-    // Check permissions — now live in settings.local.json (not settings.json)
-    // localPath already declared above for hooks check
-    let permCount = 0;
-    if (existsSync(localPath)) {
-      try {
-        const localData = JSON.parse(await fs.readFile(localPath, 'utf-8'));
-        if (localData.permissions) {
-          permCount = Object.values(localData.permissions).flat().length;
-        }
-      } catch { /* ignore parse errors */ }
+    // Check permissions
+    const perms = data.permissions || {};
+    const allowCount = (perms.allow || []).length;
+    const denyCount = (perms.deny || []).length;
+    if (allowCount === 0) {
+      infos.push('No allow rules (tools will prompt for approval)');
     }
-    // Also count permissions in settings.json (legacy installs)
-    if (data.permissions) {
-      permCount += Object.values(data.permissions).flat().length;
+    if (denyCount === 0) {
+      issues.push('No deny rules (destructive commands not blocked)');
     }
-    if (permCount === 0) {
-      issues.push('No permissions configured (check settings.local.json)');
+
+    // Check env vars
+    const env = data.env || {};
+    if (!env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) {
+      infos.push('AGENT_TEAMS env not set');
     }
 
     if (issues.length > 0) {
-      return { name: 'settings.json', ok: false, detail: issues.join('; '), fix: 'Run gaia-scan or npx gaia-update' };
+      return result('Settings', 'error', issues.join('; '), 'Run gaia-scan or npx gaia-update');
     }
 
     const hookCount = hooksConfig ? Object.keys(hooksConfig).length : 0;
-    return { name: 'settings.json', ok: true, detail: `${hookCount} hook types, ${permCount} rules` };
+    const permCount = allowCount + denyCount;
+
+    if (infos.length > 0) {
+      return result('Settings', 'info', `${hookCount} hook types, ${permCount} rules -- ${infos.join('; ')}`);
+    }
+
+    return result('Settings', 'pass', `${hookCount} hook types, ${permCount} rules`);
   } catch {
-    return { name: 'settings.json', ok: false, detail: 'Invalid JSON', fix: 'Delete and run gaia-scan' };
+    return result('Settings', 'error', 'Invalid JSON in settings.local.json', 'Delete and run gaia-scan');
   }
 }
 
@@ -147,15 +246,16 @@ async function checkProjectContext() {
   const path = join(CWD, '.claude', 'project-context', 'project-context.json');
 
   if (!existsSync(path)) {
-    return { name: 'project-context', ok: false, detail: 'Missing', fix: 'Run gaia-scan or /speckit.init' };
+    return result('project-context', 'warning', 'Missing', 'Run gaia-scan or /speckit.init');
   }
 
   try {
     const data = JSON.parse(await fs.readFile(path, 'utf-8'));
-    const issues = [];
+    const warnings = [];
+    const infos = [];
 
-    if (!data.metadata) issues.push('Missing metadata section');
-    if (!data.sections) issues.push('Missing sections');
+    if (!data.metadata) warnings.push('Missing metadata section');
+    if (!data.sections) warnings.push('Missing sections');
 
     // Detect schema version: v2.0 uses metadata.version, v1.0 does not
     const isV2 = data.metadata?.version === '2.0' || data.metadata?.created_by === 'gaia-scan';
@@ -164,46 +264,52 @@ async function checkProjectContext() {
     const hasPaths = isV2
       ? !!data.sections?.infrastructure?.paths
       : !!data.paths;
-    if (!hasPaths) issues.push('Missing paths section');
+    if (!hasPaths) infos.push('No paths section');
 
-    // Check cloud provider: v2.0 in sections.infrastructure.cloud_providers, v1.0 in metadata
+    // Cloud provider and region are informational -- not all projects use cloud
     if (data.metadata) {
       const cloudProvider = isV2
         ? data.sections?.infrastructure?.cloud_providers?.[0]?.name
         : data.metadata.cloud_provider;
-      if (!cloudProvider) issues.push('No cloud provider set');
+      if (!cloudProvider) infos.push('No cloud provider set');
 
-      // Check region: v2.0 in terraform_infrastructure, v1.0 in metadata
       const region = isV2
         ? data.sections?.terraform_infrastructure?.provider_credentials?.gcp?.region
         : data.metadata.primary_region;
-      // Region is optional in v2.0 (not all providers use gcp credentials)
-      if (!isV2 && !region) issues.push('No region set');
+      if (!isV2 && !region) infos.push('No region set');
     }
 
     if (data.sections) {
       const sectionCount = Object.keys(data.sections).length;
-      if (sectionCount < 3) issues.push(`Only ${sectionCount} sections (expected >=3)`);
+      if (sectionCount < 3) infos.push(`Only ${sectionCount} sections (expected >=3)`);
     }
 
-    if (issues.length > 0) {
-      return { name: 'project-context', ok: false, detail: issues.join('; '), fix: 'Run /speckit.init to enrich' };
+    // Warnings are real problems
+    if (warnings.length > 0) {
+      const detail = [...warnings, ...infos].join('; ');
+      return result('project-context', 'warning', detail, 'Run /speckit.init to enrich');
+    }
+
+    // Info-only items are not problems
+    if (infos.length > 0) {
+      const sectionCount = data.sections ? Object.keys(data.sections).length : 0;
+      return result('project-context', 'info', `${sectionCount} sections -- ${infos.join('; ')}`);
     }
 
     const sectionCount = Object.keys(data.sections).length;
     const cloud = isV2
       ? (data.sections?.infrastructure?.cloud_providers?.[0]?.name?.toUpperCase() || '?')
       : (data.metadata.cloud_provider?.toUpperCase() || '?');
-    return { name: 'project-context', ok: true, detail: `${sectionCount} sections, ${cloud}` };
+    return result('project-context', 'pass', `${sectionCount} sections, ${cloud}`);
   } catch {
-    return { name: 'project-context', ok: false, detail: 'Invalid JSON', fix: 'Regenerate with /speckit.init' };
+    return result('project-context', 'warning', 'Invalid JSON', 'Regenerate with /speckit.init');
   }
 }
 
 async function checkPython() {
   const pyCmd = findPython();
   if (!pyCmd) {
-    return { name: 'Python', ok: false, detail: 'Not found', fix: 'Install Python 3.9+' };
+    return result('Python', 'error', 'Not found (hooks require Python)', 'Install Python 3.9+');
   }
 
   try {
@@ -215,98 +321,129 @@ async function checkPython() {
       const major = parseInt(match[1]);
       const minor = parseInt(match[2]);
       if (major < 3 || (major === 3 && minor < 9)) {
-        return { name: 'Python', ok: false, detail: `${version} (need >=3.9)`, fix: 'Upgrade Python to 3.9+' };
+        return result('Python', 'error', `${version} (need >=3.9)`, 'Upgrade Python to 3.9+');
       }
     }
 
-    return { name: 'Python', ok: true, detail: version };
+    return result('Python', 'pass', version);
   } catch {
-    return { name: 'Python', ok: false, detail: 'Not found', fix: 'Install Python 3.9+' };
+    return result('Python', 'error', 'Not found (hooks require Python)', 'Install Python 3.9+');
   }
 }
 
 async function checkClaudeCode() {
   try {
     const { stdout } = await execAsync('claude --version 2>/dev/null || claude-code --version 2>/dev/null');
-    return { name: 'Claude Code', ok: true, detail: stdout.trim().split('\n')[0] };
+    return result('Claude Code', 'pass', stdout.trim().split('\n')[0]);
   } catch {
-    return { name: 'Claude Code', ok: false, detail: 'Not installed', fix: 'npm install -g @anthropic-ai/claude-code' };
+    // Claude Code is a prerequisite, not a Gaia issue -- informational only
+    return result('Claude Code', 'info', 'Not installed', 'npm install -g @anthropic-ai/claude-code');
   }
 }
 
 async function checkHooks() {
+  // Hook files that must exist for Gaia to function.
+  // Required: break core functionality if missing.
+  // Expected: part of the standard pipeline but non-fatal if absent.
   const hooks = [
     { file: 'pre_tool_use.py', required: true },
     { file: 'post_tool_use.py', required: true },
-    { file: 'subagent_stop.py', required: false }
+    { file: 'user_prompt_submit.py', required: true },
+    { file: 'session_start.py', required: true },
+    { file: 'subagent_stop.py', expected: true },
+    { file: 'subagent_start.py', expected: true },
+    { file: 'stop_hook.py', expected: true },
+    { file: 'task_completed.py', expected: true },
+    { file: 'post_compact.py', expected: true },
+    { file: 'elicitation_result.py', expected: true }
   ];
 
-  const issues = [];
+  const errors = [];
+  const warnings = [];
   let valid = 0;
 
-  for (const { file, required } of hooks) {
+  for (const { file, required, expected } of hooks) {
     const hookPath = join(CWD, '.claude', 'hooks', file);
     if (existsSync(hookPath)) {
       valid++;
     } else if (required) {
-      issues.push(`${file} missing`);
+      errors.push(`${file} missing`);
+    } else if (expected) {
+      warnings.push(file);
     }
   }
 
-  if (issues.length > 0) {
-    return { name: 'Hooks', ok: false, detail: issues.join('; '), fix: 'Recreate symlinks: gaia-scan' };
+  if (errors.length > 0) {
+    return result('Hook files', 'error', errors.join('; '), 'Recreate symlinks: gaia-scan');
+  }
+
+  if (warnings.length > 0) {
+    return result('Hook files', 'warning', `${valid}/${hooks.length} found (missing: ${warnings.join(', ')})`, 'Run gaia-scan to recreate symlinks');
   }
 
-  return { name: 'Hooks', ok: true, detail: `${valid}/${hooks.length} found` };
+  return result('Hook files', 'pass', `${valid}/${hooks.length} found`);
 }
 
 async function checkMemoryDirs() {
+  // Each memory dir has its own severity -- some are auto-created, some need manual setup
   const checks = [
     {
       path: join(CWD, '.claude', 'project-context', 'speckit-project-specs'),
       label: 'speckit-project-specs',
+      severity: 'warning',
       fix: 'Run gaia-scan or /speckit.init'
     },
     {
       path: join(CWD, '.claude', 'project-context', 'speckit-project-specs', 'governance.md'),
       label: 'governance.md',
+      severity: 'warning',
       fix: 'Run /speckit.init to generate governance.md'
     },
     {
       path: join(CWD, '.claude', 'project-context', 'workflow-episodic-memory'),
       label: 'workflow-episodic-memory',
+      severity: 'warning',
       fix: 'Run gaia-scan to create workflow memory directory'
     },
     {
       path: join(CWD, '.claude', 'project-context', 'episodic-memory'),
       label: 'episodic-memory',
-      fix: 'Directory is created automatically on first agent run'
+      severity: 'info',  // Auto-created on first agent run
+      fix: 'Created automatically on first agent run'
     },
   ];
 
-  const issues = [];
+  const warnings = [];
+  const infos = [];
   let found = 0;
-  for (const { path, label, fix } of checks) {
+
+  for (const { path, label, severity, fix } of checks) {
     if (existsSync(path)) {
       found++;
+    } else if (severity === 'info') {
+      infos.push({ label, fix });
     } else {
-      issues.push({ label, fix });
+      warnings.push({ label, fix });
     }
   }
 
-  if (issues.length > 0) {
-    const detail = issues.map(i => `${i.label} missing`).join('; ');
-    const fix = issues[0].fix;
-    return { name: 'Memory dirs', ok: false, detail, fix };
+  if (warnings.length > 0) {
+    const detail = warnings.map(i => `${i.label} missing`).join('; ');
+    return result('Memory dirs', 'warning', detail, warnings[0].fix);
   }
 
-  return { name: 'Memory dirs', ok: true, detail: `${found}/${checks.length} present` };
+  if (infos.length > 0) {
+    const detail = `${found}/${checks.length} present (${infos.map(i => `${i.label}: ${i.fix}`).join('; ')})`;
+    return result('Memory dirs', 'info', detail);
+  }
+
+  return result('Memory dirs', 'pass', `${found}/${checks.length} present`);
 }
 
 async function checkProjectDirs() {
   const contextPath = join(CWD, '.claude', 'project-context', 'project-context.json');
   if (!existsSync(contextPath)) {
-    return { name: 'Project dirs', ok: true, detail: 'Skipped (no context)' };
+    return result('Project dirs', 'pass', 'Skipped (no context)');
   }
 
   try {
@@ -322,12 +459,12 @@ async function checkProjectDirs() {
     }
 
     if (issues.length > 0) {
-      return { name: 'Project dirs', ok: false, detail: issues.join('; '), fix: 'Create missing directories or update paths' };
+      return result('Project dirs', 'warning', issues.join('; '), 'Create missing directories or update paths');
     }
 
-    return { name: 'Project dirs', ok: true, detail: `${Object.keys(paths).length} paths verified` };
+    return result('Project dirs', 'pass', `${Object.keys(paths).length} paths verified`);
   } catch {
-    return { name: 'Project dirs', ok: true, detail: 'Skipped (parse error)' };
+    return result('Project dirs', 'pass', 'Skipped (parse error)');
   }
 }
 
@@ -369,8 +506,6 @@ async function autoFix() {
     }
   }
 
-  // CLAUDE.md no longer generated -- identity injected by UserPromptSubmit hook
-
   // Create missing project dirs
   const contextPath = join(CWD, '.claude', 'project-context', 'project-context.json');
   if (existsSync(contextPath)) {
@@ -394,6 +529,32 @@ async function autoFix() {
   return fixed;
 }
 
+// ============================================================================
+// Display helpers
+// ============================================================================
+
+const SEVERITY_ICONS = {
+  pass:    { icon: '\u2713', color: chalk.green },     // check mark
+  info:    { icon: '\u2139', color: chalk.cyan },      // info symbol
+  warning: { icon: '\u26A0', color: chalk.yellow },    // warning triangle
+  error:   { icon: '\u2717', color: chalk.red },       // X mark
+};
+
+function severityIcon(severity) {
+  const entry = SEVERITY_ICONS[severity] || SEVERITY_ICONS.warning;
+  return entry.color(entry.icon);
+}
+
+function severityDetail(severity, detail) {
+  switch (severity) {
+    case 'pass': return chalk.gray(detail || '');
+    case 'info': return chalk.cyan(detail);
+    case 'warning': return chalk.yellow(detail);
+    case 'error': return chalk.red(detail);
+    default: return detail;
+  }
+}
+
 // ============================================================================
 // Main
 // ============================================================================
@@ -407,16 +568,18 @@ async function main() {
     .version(false)
     .parse();
 
-  // Run all checks
+  // Run all checks -- ordered from most fundamental to most specific.
+  // Core platform first, then Gaia configuration, then project-specific.
   const checks = [
     checkGaiaVersion,
     checkClaudeCode,
-    checkSymlinks,
-    checkClaudeMd,
-    checkSettingsJson,
-    checkProjectContext,
     checkPython,
+    checkPluginMode,
+    checkSymlinks,
+    checkIdentity,
+    checkSettings,
     checkHooks,
+    checkProjectContext,
     checkProjectDirs,
     checkMemoryDirs
   ];
@@ -426,52 +589,57 @@ async function main() {
     try {
       results.push(await check());
     } catch (error) {
-      results.push({ name: check.name, ok: false, detail: `Error: ${error.message}` });
+      results.push(result(check.name, 'error', `Error: ${error.message}`));
     }
   }
 
+  // Compute overall status from severity levels
+  const hasErrors = results.some(r => r.severity === 'error');
+  const hasWarnings = results.some(r => r.severity === 'warning');
+
   // JSON output mode
   if (args.json) {
-    const allOk = results.every(r => r.ok);
-    console.log(JSON.stringify({ healthy: allOk, checks: results }, null, 2));
-    process.exit(allOk ? 0 : 1);
+    const status = hasErrors ? 'critical' : hasWarnings ? 'degraded' : 'healthy';
+    console.log(JSON.stringify({ healthy: !hasErrors && !hasWarnings, status, checks: results }, null, 2));
+    process.exit(hasErrors ? 2 : hasWarnings ? 1 : 0);
   }
 
   // Human-readable output
-  // Extract version for header
   const gaiaCheck = results.find(r => r.name === 'Gaia-Ops');
-  const versionTag = gaiaCheck?.ok ? chalk.gray(` (${gaiaCheck.detail})`) : '';
+  const versionTag = gaiaCheck?.severity === 'pass' ? chalk.gray(` (${gaiaCheck.detail})`) : '';
   console.log(chalk.cyan(`\n  Gaia-Ops Health Check${versionTag}\n`));
 
-  let allOk = true;
+  for (const r of results) {
+    const icon = severityIcon(r.severity);
+    const detail = severityDetail(r.severity, r.detail || '');
+    console.log(`    ${icon} ${r.name.padEnd(18)} ${detail}`);
 
-  for (const result of results) {
-    const icon = result.ok ? chalk.green('✓') : chalk.yellow('⚠');
-    const detail = result.ok ? chalk.gray(result.detail || '') : chalk.yellow(result.detail);
-    console.log(`    ${icon} ${result.name.padEnd(18)} ${detail}`);
-
-    if (!result.ok && result.fix) {
-      console.log(chalk.gray(`      Fix: ${result.fix}`));
+    if ((r.severity === 'warning' || r.severity === 'error') && r.fix) {
+      console.log(chalk.gray(`      Fix: ${r.fix}`));
     }
-
-    if (!result.ok) allOk = false;
   }
 
   console.log('');
 
-  if (allOk) {
-    console.log(chalk.green.bold('  Status: HEALTHY\n'));
-  } else {
+  if (hasErrors) {
+    console.log(chalk.red.bold('  Status: CRITICAL\n'));
+    if (args.fix) {
+      await autoFix();
+    } else {
+      console.log(chalk.gray('  Run with --fix to attempt auto-repair\n'));
+    }
+  } else if (hasWarnings) {
     console.log(chalk.yellow.bold('  Status: ISSUES FOUND\n'));
-
     if (args.fix) {
       await autoFix();
     } else {
       console.log(chalk.gray('  Run with --fix to attempt auto-repair\n'));
     }
+  } else {
+    console.log(chalk.green.bold('  Status: HEALTHY\n'));
   }
 
-  process.exit(allOk ? 0 : 1);
+  process.exit(hasErrors ? 2 : hasWarnings ? 1 : 0);
 }
 
 main();

package/bin/gaia-update.js

@@ -121,6 +121,32 @@ async function updateLocalPermissions() {
       return false;
     }
 
+    // Load existing settings.local.json — preserve everything (enabledPlugins, MCP servers, etc.)
+    let existing = {};
+    if (existsSync(localPath)) {
+      try {
+        existing = JSON.parse(await fs.readFile(localPath, 'utf-8'));
+      } catch {
+        existing = {};
+      }
+    }
+
+    // Track what changed
+    let changed = false;
+
+    // Set the orchestrator agent identity (always, even if Python extraction fails)
+    if (existing.agent !== 'gaia-orchestrator') {
+      existing.agent = 'gaia-orchestrator';
+      changed = true;
+    }
+
+    // Add env vars (smart merge: add if not present, don't overwrite)
+    existing.env = existing.env || {};
+    if (!('CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS' in existing.env)) {
+      existing.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
+      changed = true;
+    }
+
     // Load permissions from plugin_setup.py — the single source of truth.
     // We use ast.literal_eval to extract the constants without importing
     // the module (which has relative imports that fail standalone).
@@ -128,11 +154,16 @@ async function updateLocalPermissions() {
     try {
       const setupPath = join(__dirname, '..', 'hooks', 'modules', 'core', 'plugin_setup.py');
       const pythonCmd = findPython() || 'python3';
-      const { stdout } = await execAsync(
-        `${pythonCmd} -c "
-import ast, json, re
 
-source = open('${setupPath.replace(/'/g, "\\'")}').read()
+      // Write the extraction script to a temp file instead of using -c with
+      // inline code.  This avoids shell quoting issues on Windows where
+      // backslash paths and nested quotes break the inline Python string.
+      const tempScript = join(claudeDir, '.gaia-extract-perms.py');
+      const scriptContent = `
+import ast, json, re, sys
+
+setup_path = sys.argv[1]
+source = open(setup_path, encoding="utf-8").read()
 
 # Extract _DENY_RULES list
 deny_match = re.search(r'^_DENY_RULES\\s*=\\s*\\[', source, re.MULTILINE)
@@ -163,28 +194,32 @@ else:
     ops_perms = {'permissions': {'allow': [], 'deny': deny_rules, 'ask': []}}
 
 print(json.dumps(ops_perms))
-"`,
-        { timeout: 10000 }
-      );
-      gaiaPerms = JSON.parse(stdout.trim());
+`;
+      await fs.writeFile(tempScript, scriptContent);
+      try {
+        const { stdout } = await execAsync(
+          `${pythonCmd} "${tempScript}" "${setupPath}"`,
+          { timeout: 10000 }
+        );
+        gaiaPerms = JSON.parse(stdout.trim());
+      } finally {
+        // Clean up temp script
+        try { await fs.unlink(tempScript); } catch { /* ignore */ }
+      }
     } catch (pyError) {
       spinner.warn(`Could not load permissions from Python — ${pyError.message || 'unknown error'}`);
+      // Still write agent and env changes even if permissions extraction fails
+      if (changed) {
+        await fs.writeFile(localPath, JSON.stringify(existing, null, 2) + '\n');
+        spinner.succeed('settings.local.json agent and env merged (permissions skipped)');
+        return true;
+      }
       return false;
     }
 
     const ourAllow = new Set(gaiaPerms.permissions.allow || []);
     const ourDeny = new Set(gaiaPerms.permissions.deny || []);
 
-    // Load existing settings.local.json — preserve everything (enabledPlugins, MCP servers, etc.)
-    let existing = {};
-    if (existsSync(localPath)) {
-      try {
-        existing = JSON.parse(await fs.readFile(localPath, 'utf-8'));
-      } catch {
-        existing = {};
-      }
-    }
-
     const perms = existing.permissions || {};
     const currentAllow = new Set(perms.allow || []);
     const currentDeny = new Set(perms.deny || []);
@@ -193,9 +228,6 @@ print(json.dumps(ops_perms))
     const mergedAllow = [...new Set([...currentAllow, ...ourAllow])].sort();
     const mergedDeny = [...new Set([...currentDeny, ...ourDeny])].sort();
 
-    // Track what changed
-    let changed = false;
-
     // Check if permissions changed
     const allowChanged = mergedAllow.length !== currentAllow.size
       || mergedAllow.some(r => !currentAllow.has(r));
@@ -210,19 +242,6 @@ print(json.dumps(ops_perms))
       changed = true;
     }
 
-    // Add env vars (smart merge: add if not present, don't overwrite)
-    existing.env = existing.env || {};
-    if (!('CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS' in existing.env)) {
-      existing.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
-      changed = true;
-    }
-
-    // Set the orchestrator agent identity
-    if (existing.agent !== 'gaia-orchestrator') {
-      existing.agent = 'gaia-orchestrator';
-      changed = true;
-    }
-
     if (!changed) {
       spinner.succeed('settings.local.json permissions already up to date');
       return false;

package/dist/gaia-ops/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-ops",
-  "version": "5.0.0-beta.4",
+  "version": "5.0.0-beta.6",
   "description": "Full DevOps orchestration for Claude Code. Six specialized agents handle the complete development lifecycle \u2014 analysis, planning, execution, and deployment. Gaia-Ops scans your codebase to understand it and injects the right context into each sub-agent. Every command is classified by risk: read-only runs freely, state changes pause for your approval, and irreversible operations are permanently blocked.",
   "author": {
     "name": "jaguilar87"

package/dist/gaia-ops/skills/blog-writing/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: blog-writing
+description: Use when writing, drafting, or publishing a blog article for metraton.github.io
+metadata:
+  user-invocable: true
+  type: technique
+---
+
+# Blog Writing
+
+Jorge's blog (metraton.github.io) is where he thinks out loud about agentic systems, context engineering, and the intersection of architecture and AI. The articles are bilingual (English and Spanish), grounded in real experience, and written in first person. They are not corporate content -- they are reflections from someone building these systems daily.
+
+## The Writing Process
+
+### 1. Find the story first
+
+Every article starts with something that actually happened -- a deployment that went sideways, a late-night refactor, a conversation that shifted your thinking. The story is the anchor. Without it, you are writing a tutorial, not an article.
+
+Ask Jorge: "What happened recently that surprised you or changed how you think about something?" The best topics come from moments where the outcome was different from the expectation.
+
+### 2. Build the brief
+
+Before writing a single paragraph, define: title, audience, core thesis (one sentence), and format. Jorge's natural format is **Strategic Insight** -- personal experience analyzed through a technical lens, ending with a transferable lesson.
+
+The audience is engineers, solution architects, AI practitioners, and tech leaders. They do not need hand-holding but they appreciate honesty about what did not work.
+
+### 3. Draft in Markdown, iterate with Jorge
+
+Write the first draft in Markdown at `/home/jorge/ws/me/<slug>.md`. Work section by section -- do not dump an entire draft and ask "what do you think?" Each section should be reviewed before moving to the next.
+
+**Article structure** (not rigid, but this is Jorge's natural flow):
+- Opening story -- what happened, told personally
+- The problem -- what was broken or surprising
+- Investigation -- what you looked into and found
+- The shift -- the insight or reframe
+- In practice -- what changed, concretely
+- Results -- evidence it worked
+- Closing thought -- punchy, memorable, one line
+
+### 4. Principles that matter
+
+**Examples must be real.** Not "imagine a team that..." but "I was deploying to Cloud Run when..." If you cannot point to something that actually happened, the example does not belong.
+
+**Each section adds something new.** Do not repeat the same example or insight across sections. If the investigation section already showed the problem, the "in practice" section should show the solution -- not restate the problem.
+
+**Quotes add weight when grounded.** Citing Anthropic, Hinton, or other thought leaders works when the quote connects directly to the experience. A quote floating without context is decoration.
+
+**Technical terms stay in English in both languages.** LLM, skills, agent, Cloud Run, Terraform -- these do not get translated.
+
+**Closing lines are signatures.** "Built with context.", "Built with reasoning." -- short, confident, tied to the article's thesis.
+
+### 5. Convert to bilingual HTML
+
+Once the Markdown draft is approved, convert to the bilingual HTML format. The Spanish version is not a mechanical translation -- it is natural Latin American Spanish, with the same voice and directness. Read `reference.md` for the HTML template and front matter structure.
+
+Final HTML goes in: `/home/jorge/ws/me/metraton.github.io/_posts/YYYY-MM-DD-slug.html`
+
+### 6. Preview and publish
+
+Run Jekyll locally for preview (port 4000). Then commit and push to publish via GitHub Pages.
+
+## Jorge's Voice
+
+- First person, always. "I was deploying..." not "The team deployed..."
+- Honest about failures and iterations -- does not pretend things worked the first time
+- Confident but not preachy. States what he found, not what everyone should do
+- Direct. Short sentences when making a point. Longer when telling a story
+- Latin American perspective -- references to the region's tech community are natural, not forced
+
+## Anti-Patterns
+
+- Writing generic content that could appear on any corporate blog
+- Translating English to Spanish mechanically instead of rewriting naturally
+- Dumping an entire draft without iterating section by section
+- Using hypothetical examples when real ones exist
+- Repeating the same insight across multiple sections

package/dist/gaia-ops/skills/blog-writing/reference.md

@@ -0,0 +1,102 @@
+# Blog Writing Reference
+
+## Blog Repository
+
+- **Repo path:** `/home/jorge/ws/me/metraton.github.io/`
+- **Site:** https://metraton.github.io/
+- **Engine:** Jekyll static site, GitHub Pages hosted
+- **Posts directory:** `_posts/`
+- **Draft workspace:** `/home/jorge/ws/me/<slug>.md`
+
+## Front Matter Template
+
+Every post requires this YAML front matter. All fields are mandatory for the bilingual layout to work correctly.
+
+```yaml
+---
+layout: bilingual
+title: "English Title Here"
+title_en: "English Title Here"
+title_es: "Spanish Title Here"
+post_title_es: "Spanish Title Here"
+date: YYYY-MM-DD
+terminal_title: "jaguilar@github:~/posts$ cat slug-name"
+terminal_title_es: "jaguilar@github:~/posts$ cat slug-name"
+excerpt: "English excerpt -- one compelling sentence."
+excerpt_es: "Spanish excerpt -- one compelling sentence."
+---
+```
+
+**Notes:**
+- `title` and `title_en` are always identical
+- `title_es` and `post_title_es` are always identical
+- `terminal_title` and `terminal_title_es` are usually the same (the cat command)
+- `date` is the publication date in `YYYY-MM-DD` format
+- Excerpts use HTML entities for special characters (e.g., `&eacute;` for accented characters in Spanish)
+- Some older posts include `permalink:` -- newer posts rely on the filename for the URL
+
+## HTML Structure
+
+The file is named `YYYY-MM-DD-slug.html` and placed in `_posts/`.
+
+```html
+---
+(front matter as above)
+---
+
+      <div class="bilingual-content" lang="en" data-lang-section="en">
+        <!-- English content here -->
+        <!-- Use proper HTML entities: &mdash; &rsquo; &ldquo; &rdquo; etc. -->
+
+        <p class="closing-line"><em>Built with [theme]. Jorge Aguilar, 2025&ndash;2026.</em></p>
+      </div>
+      <div class="bilingual-content" lang="es" data-lang-section="es" hidden>
+        <!-- Spanish content here -->
+        <!-- Same structure as English, naturally rewritten -->
+
+        <p class="closing-line"><em>Construido con [tema]. Jorge Aguilar, 2025&ndash;2026.</em></p>
+      </div>
+```
+
+**HTML conventions observed in existing posts:**
+- Content is indented with 8 spaces (two levels inside the layout)
+- Use `&mdash;` for em dashes, `&rsquo;` for apostrophes, `&ldquo;`/`&rdquo;` for quotes
+- Use `&eacute;`, `&aacute;`, `&iacute;`, `&oacute;`, `&uacute;`, `&ntilde;` for Spanish accented characters
+- Section headings are `<h2>`, subsection headings are `<h3>`
+- Horizontal rules (`<hr />`) separate major sections
+- Blockquotes (`<blockquote>`) are used for key insights and external quotes
+- Code inline uses `<code>`, code blocks use `<pre><code>`
+- The Spanish section has `hidden` attribute (JavaScript toggles it)
+- The closing line uses `class="closing-line"` with `<em>` wrapper
+
+## Existing Articles (for style reference)
+
+| Date | Slug | Theme |
+|------|------|-------|
+| 2025-09-29 | context-design-agentic-deployment | Context engineering and agentic deployment on GCP |
+| 2025-11-01 | beyond-delegation-agentic-systems | Moving past simple delegation in agentic workflows |
+| 2026-04-02 | faster-development-orchestration | How orchestration improves faster development cycles |
+| 2026-04-10 | writing-skills-that-actually-work | Skill design for LLM agents -- judgment over compliance |
+
+## Local Preview
+
+```bash
+cd /home/jorge/ws/me/metraton.github.io
+bundle exec jekyll serve
+# Preview at http://localhost:4000
+# Note: WSL2 may require port forwarding for browser access
+```
+
+## Publication
+
+```bash
+cd /home/jorge/ws/me/metraton.github.io
+git add _posts/YYYY-MM-DD-slug.html
+git commit -m "Add: article title"
+git push origin main
+# GitHub Pages deploys automatically
+```
+
+## Pending Article Ideas
+
+- **"How to Build an Agent Identity"** -- about agent identities, what they contain, how to structure them, the relationship between identity and skills. More reflective than technical.

package/dist/gaia-security/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-security",
-  "version": "5.0.0-beta.4",
+  "version": "5.0.0-beta.6",
   "description": "Keeps you in the loop only when it matters. Gaia Security analyzes every command and classifies it into risk tiers: read-only queries run freely, simulations and validations pass through, and state-changing operations (create, delete, apply, push) pause for your explicit approval before executing. Irreversible commands like dropping databases or deleting cloud infrastructure are permanently blocked.",
   "author": {
     "name": "jaguilar87"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaguilar87/gaia-ops",
-  "version": "5.0.0-beta.4",
+  "version": "5.0.0-beta.6",
   "description": "Multi-agent orchestration system for Claude Code - DevOps automation toolkit",
   "main": "index.js",
   "type": "module",

package/skills/blog-writing/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: blog-writing
+description: Use when writing, drafting, or publishing a blog article for metraton.github.io
+metadata:
+  user-invocable: true
+  type: technique
+---
+
+# Blog Writing
+
+Jorge's blog (metraton.github.io) is where he thinks out loud about agentic systems, context engineering, and the intersection of architecture and AI. The articles are bilingual (English and Spanish), grounded in real experience, and written in first person. They are not corporate content -- they are reflections from someone building these systems daily.
+
+## The Writing Process
+
+### 1. Find the story first
+
+Every article starts with something that actually happened -- a deployment that went sideways, a late-night refactor, a conversation that shifted your thinking. The story is the anchor. Without it, you are writing a tutorial, not an article.
+
+Ask Jorge: "What happened recently that surprised you or changed how you think about something?" The best topics come from moments where the outcome was different from the expectation.
+
+### 2. Build the brief
+
+Before writing a single paragraph, define: title, audience, core thesis (one sentence), and format. Jorge's natural format is **Strategic Insight** -- personal experience analyzed through a technical lens, ending with a transferable lesson.
+
+The audience is engineers, solution architects, AI practitioners, and tech leaders. They do not need hand-holding but they appreciate honesty about what did not work.
+
+### 3. Draft in Markdown, iterate with Jorge
+
+Write the first draft in Markdown at `/home/jorge/ws/me/<slug>.md`. Work section by section -- do not dump an entire draft and ask "what do you think?" Each section should be reviewed before moving to the next.
+
+**Article structure** (not rigid, but this is Jorge's natural flow):
+- Opening story -- what happened, told personally
+- The problem -- what was broken or surprising
+- Investigation -- what you looked into and found
+- The shift -- the insight or reframe
+- In practice -- what changed, concretely
+- Results -- evidence it worked
+- Closing thought -- punchy, memorable, one line
+
+### 4. Principles that matter
+
+**Examples must be real.** Not "imagine a team that..." but "I was deploying to Cloud Run when..." If you cannot point to something that actually happened, the example does not belong.
+
+**Each section adds something new.** Do not repeat the same example or insight across sections. If the investigation section already showed the problem, the "in practice" section should show the solution -- not restate the problem.
+
+**Quotes add weight when grounded.** Citing Anthropic, Hinton, or other thought leaders works when the quote connects directly to the experience. A quote floating without context is decoration.
+
+**Technical terms stay in English in both languages.** LLM, skills, agent, Cloud Run, Terraform -- these do not get translated.
+
+**Closing lines are signatures.** "Built with context.", "Built with reasoning." -- short, confident, tied to the article's thesis.
+
+### 5. Convert to bilingual HTML
+
+Once the Markdown draft is approved, convert to the bilingual HTML format. The Spanish version is not a mechanical translation -- it is natural Latin American Spanish, with the same voice and directness. Read `reference.md` for the HTML template and front matter structure.
+
+Final HTML goes in: `/home/jorge/ws/me/metraton.github.io/_posts/YYYY-MM-DD-slug.html`
+
+### 6. Preview and publish
+
+Run Jekyll locally for preview (port 4000). Then commit and push to publish via GitHub Pages.
+
+## Jorge's Voice
+
+- First person, always. "I was deploying..." not "The team deployed..."
+- Honest about failures and iterations -- does not pretend things worked the first time
+- Confident but not preachy. States what he found, not what everyone should do
+- Direct. Short sentences when making a point. Longer when telling a story
+- Latin American perspective -- references to the region's tech community are natural, not forced
+
+## Anti-Patterns
+
+- Writing generic content that could appear on any corporate blog
+- Translating English to Spanish mechanically instead of rewriting naturally
+- Dumping an entire draft without iterating section by section
+- Using hypothetical examples when real ones exist
+- Repeating the same insight across multiple sections

package/skills/blog-writing/reference.md

@@ -0,0 +1,102 @@
+# Blog Writing Reference
+
+## Blog Repository
+
+- **Repo path:** `/home/jorge/ws/me/metraton.github.io/`
+- **Site:** https://metraton.github.io/
+- **Engine:** Jekyll static site, GitHub Pages hosted
+- **Posts directory:** `_posts/`
+- **Draft workspace:** `/home/jorge/ws/me/<slug>.md`
+
+## Front Matter Template
+
+Every post requires this YAML front matter. All fields are mandatory for the bilingual layout to work correctly.
+
+```yaml
+---
+layout: bilingual
+title: "English Title Here"
+title_en: "English Title Here"
+title_es: "Spanish Title Here"
+post_title_es: "Spanish Title Here"
+date: YYYY-MM-DD
+terminal_title: "jaguilar@github:~/posts$ cat slug-name"
+terminal_title_es: "jaguilar@github:~/posts$ cat slug-name"
+excerpt: "English excerpt -- one compelling sentence."
+excerpt_es: "Spanish excerpt -- one compelling sentence."
+---
+```
+
+**Notes:**
+- `title` and `title_en` are always identical
+- `title_es` and `post_title_es` are always identical
+- `terminal_title` and `terminal_title_es` are usually the same (the cat command)
+- `date` is the publication date in `YYYY-MM-DD` format
+- Excerpts use HTML entities for special characters (e.g., `&eacute;` for accented characters in Spanish)
+- Some older posts include `permalink:` -- newer posts rely on the filename for the URL
+
+## HTML Structure
+
+The file is named `YYYY-MM-DD-slug.html` and placed in `_posts/`.
+
+```html
+---
+(front matter as above)
+---
+
+      <div class="bilingual-content" lang="en" data-lang-section="en">
+        <!-- English content here -->
+        <!-- Use proper HTML entities: &mdash; &rsquo; &ldquo; &rdquo; etc. -->
+
+        <p class="closing-line"><em>Built with [theme]. Jorge Aguilar, 2025&ndash;2026.</em></p>
+      </div>
+      <div class="bilingual-content" lang="es" data-lang-section="es" hidden>
+        <!-- Spanish content here -->
+        <!-- Same structure as English, naturally rewritten -->
+
+        <p class="closing-line"><em>Construido con [tema]. Jorge Aguilar, 2025&ndash;2026.</em></p>
+      </div>
+```
+
+**HTML conventions observed in existing posts:**
+- Content is indented with 8 spaces (two levels inside the layout)
+- Use `&mdash;` for em dashes, `&rsquo;` for apostrophes, `&ldquo;`/`&rdquo;` for quotes
+- Use `&eacute;`, `&aacute;`, `&iacute;`, `&oacute;`, `&uacute;`, `&ntilde;` for Spanish accented characters
+- Section headings are `<h2>`, subsection headings are `<h3>`
+- Horizontal rules (`<hr />`) separate major sections
+- Blockquotes (`<blockquote>`) are used for key insights and external quotes
+- Code inline uses `<code>`, code blocks use `<pre><code>`
+- The Spanish section has `hidden` attribute (JavaScript toggles it)
+- The closing line uses `class="closing-line"` with `<em>` wrapper
+
+## Existing Articles (for style reference)
+
+| Date | Slug | Theme |
+|------|------|-------|
+| 2025-09-29 | context-design-agentic-deployment | Context engineering and agentic deployment on GCP |
+| 2025-11-01 | beyond-delegation-agentic-systems | Moving past simple delegation in agentic workflows |
+| 2026-04-02 | faster-development-orchestration | How orchestration improves faster development cycles |
+| 2026-04-10 | writing-skills-that-actually-work | Skill design for LLM agents -- judgment over compliance |
+
+## Local Preview
+
+```bash
+cd /home/jorge/ws/me/metraton.github.io
+bundle exec jekyll serve
+# Preview at http://localhost:4000
+# Note: WSL2 may require port forwarding for browser access
+```
+
+## Publication
+
+```bash
+cd /home/jorge/ws/me/metraton.github.io
+git add _posts/YYYY-MM-DD-slug.html
+git commit -m "Add: article title"
+git push origin main
+# GitHub Pages deploys automatically
+```
+
+## Pending Article Ideas
+
+- **"How to Build an Agent Identity"** -- about agent identities, what they contain, how to structure them, the relationship between identity and skills. More reflective than technical.