@xelth/eck-snapshot 6.0.2 → 6.0.4

package/README.md

@@ -1,71 +1,52 @@
 # 📸 eckSnapshot v6.0
 
-A specialized, AI-native CLI tool designed to create and restore single-file text snapshots of Git repositories. Optimized for providing full project context to Large Language Models (LLMs) and serving as the coordination hub for Multi-Agent AI Architectures.
+A specialized, AI-native CLI tool designed to create and restore single-file text snapshots of Git repositories. Optimized for providing full project context to Large Language Models (LLMs) and serving as the coordination hub for AI Coders.
 
-## 🌟 Key Features
+## 🎯 The Battle-Tested Workflow & Quick Start
 
-* **🧠 Multi-Agent Protocol (Royal Court):** Built-in support for the "Royal Court" architecture. Delegate tasks from a Senior Architect (Claude/Gemini) to Junior Managers, who orchestrate a swarm of specialized GLM-4.7 workers.
-* **☠️ Skeleton Mode:** Uses `Tree-sitter` and `Babel` to strip function bodies, drastically reducing token count while preserving structural context. Supports JS/TS, Rust, Go, Python, C, Java, and Kotlin.
-* **🔄 Smart Delta Updates:** Tracks incremental changes via Git anchors with sequential numbering. Now accurately tracks and reports deleted files to prevent LLM hallucinations.
-* **🛡️ Security (SecretScanner):** Automatically redacts API keys and credentials before sending context to LLMs. Features both Regex matching and **Shannon Entropy** analysis for catching non-standard hardcoded secrets.
-* **📊 Telemetry Hub:** Integrated with a Rust-based microservice (`eck-telemetry`) for tracking agent execution metrics, auto-syncing token estimation weights via linear regression, and in-memory caching.
-* **🔌 Native MCP Integration:** Instantly spins up Model Context Protocol (MCP) servers (`eck-core` for context sync and `glm-zai` for worker swarms) for Claude Code and OpenCode.
+I personally use this tool daily with local AI coding agents (**Claude Code** using Claude, and **OpenCode** using GLM). My reliable, heavily-tested workflow is:
 
-## 🚀 Quick Start
-
-### Installation
+### 1. Installation
 ```bash
 npm install -g @xelth/eck-snapshot
 ```
 
-### Basic Usage
+### 2. Initial Context (Full Snapshots)
+Take a full snapshot and feed it to a powerful Web LLM (Senior Architect like **Gemini** or **Grok**). *(Note: **ChatGPT** also works, but you MUST paste the specific prompt provided at the end of the snapshot output as your first prompt).*
 ```bash
-# Create a standard full snapshot
 eck-snapshot snapshot
-
-# Create a highly compressed skeleton snapshot
-eck-snapshot snapshot --skeleton
-
-# Create an incremental update (only changed/deleted files)
-eck-snapshot update
 ```
+*(For massive monorepos, slice the context using profiles: `eck-snapshot snapshot --profile frontend`)*
 
-## 🤖 AI Swarm Setup (GLM Z.AI)
+### 3. Direct Execution
+Pass the Architect's technical plan to your local Coder agent (Claude Code / OpenCode). The Coder will implement the changes directly in your repository.
 
-eckSnapshot v6 acts as the bridge between your primary AI IDE (Claude Code or OpenCode) and a cost-effective GLM-4.7 worker swarm.
+### 4. Auto-Updates vs Manual Updates
+When the Coder agent finishes a task, it automatically calls the built-in MCP tool (`eck_finish_task`), which commits the code and automatically generates an incremental delta update snapshot.
 
-1. **Get an API Key:** Register at [Z.AI](https://z.ai) and set `export ZAI_API_KEY="your-key"`.
-2. **Setup MCP Servers:**
-   ```bash
-   eck-snapshot setup-mcp --both
-   ```
-3. **Initialize Project Manifests:**
-   ```bash
-   # Generates smart instructions (CLAUDE.md / AGENTS.md)
-   eck-snapshot snapshot --jas  # For Claude Code (Sonnet 4.5)
-   eck-snapshot snapshot --jaz  # For OpenCode (GLM-4.7)
-   ```
+**Optional Manual Update:**
+If you make manual changes yourself (without the agent), use this command to create a delta snapshot to sync your Web AI:
+```bash
+eck-snapshot update
+```
+This core loop is highly polished, actively maintained, and works exceptionally well.
 
-## 📁 The `.eck/` Manifest Directory
+## 🌟 Core Features
 
-eckSnapshot automatically maintains a `.eck/` directory in your project to provide deep context to AI agents:
-- `CONTEXT.md` - High-level architecture (Auto-generated)
-- `ENVIRONMENT.md` - Runtime specifics (Auto-generated)
-- `ROADMAP.md` & `TECH_DEBT.md` - Strategic planning
-- `RUNTIME_STATE.md` - Live port/process status
+* **🔄 Smart Delta Updates:** Tracks incremental changes via Git anchors with sequential numbering. Accurately tracks and reports deleted files to prevent LLM hallucinations.
+* **🛡️ Security (SecretScanner):** Automatically redacts API keys and credentials before sending context to LLMs. Features both Regex matching and **Shannon Entropy** analysis.
+* **🔌 Native MCP Integration:** Instantly spins up Model Context Protocol (MCP) servers (`eck-core` for context sync) for Claude Code and OpenCode.
+* **📁 The `.eck/` Manifest:** Automatically maintains project context files (`CONTEXT.md`, `ROADMAP.md`, `TECH_DEBT.md`) to onboard AI agents instantly.
 
-*Note: The tool automatically filters confidential files like `SERVER_ACCESS.md` from snapshots to ensure security.*
+---
 
-## 📈 Token Estimation
+## 🧪 Experimental / Advanced Features
 
-Train the local estimator to perfectly predict token counts for your specific project:
-```bash
-# Manually push agent telemetry
-eck-snapshot telemetry push
+*The following features are included in the tool, but I am not actively using them in my daily workflow right now. They are available for power users, but might have edge cases. If you use them and find issues, please open an issue on GitHub, or better yet, try fixing it yourself (you have the ultimate AI coding tool in your hands now!)*
 
-# Sync global token weights from the Telemetry Hub
-eck-snapshot telemetry sync-weights
-```
+* **🧠 Multi-Agent Protocol (Royal Court):** Built-in support for delegating tasks from a Senior Architect to Junior Managers (`--jas`, `--jao`, `--jaz`), who orchestrate a swarm of specialized GLM workers via MCP.
+* **☠️ Skeleton Mode:** Uses `Tree-sitter` and `Babel` to strip function bodies (`--skeleton`), drastically reducing token count.
+* **📊 Telemetry Hub:** Integrated with a Rust-based microservice for tracking agent execution metrics and auto-syncing token estimation weights.
 
 ## License
 MIT © xelth-com

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "6.0.2",
+  "version": "6.0.4",
   "description": "A powerful CLI tool to create and restore single-file text snapshots of Git repositories. Optimized for AI context, LLM workflows, and multi-agent Swarm coordination.",
   "main": "index.js",
   "type": "module",

package/src/cli/cli.js

@@ -106,27 +106,21 @@ export function run() {
   const pkg = createRequire(import.meta.url)('../../package.json');
   const helpGuide = `eck-snapshot (v${pkg.version}) - AI-Native Repository Context Tool.
 
---- 🚀 Core Workflow: Optimized for Web LLMs (Gemini/ChatGPT) ---
+--- 🚀 Core Workflow: Optimized for Web LLMs (Claude/Gemini/Grok) ---
+💡 Note: ChatGPT is supported but can be slow. Use the suggested prompt at the end of the snapshot.
 
-1. Initial Context (Maximum Compression)
-   Create a lightweight map of your entire project. Bodies of functions are hidden.
-   This fits huge monoliths into the context window.
-   
-   $ eck-snapshot --skeleton
-   -> Generates: .eck/snapshots/<name>_sk.md (Upload this to AI)
+1. Initial Context (Full Snapshot)
+   Create a complete map of your project to feed to the AI Architect.
+   $ eck-snapshot snapshot
 
-2. Lazy Loading (On-Demand Details)
-   If the AI needs to see the implementation of specific files, it will ask you.
-   You can display multiple files at once to copy-paste back to the chat.
-   
-   $ eck-snapshot show src/auth.js src/utils/hash.js
+   (For very large projects, use profiles: $ eck-snapshot --profile backend)
+
+2. Working & Updating
+   Local coders (Claude Code / OpenCode) will automatically sync context using MCP tools when they finish a task.
+   If YOU make manual changes, send an incremental update to the Web AI:
 
-3. Working & Updating
-   As you apply changes, the AI loses context. Instead of re-sending the full repo,
-   send only what changed since the last snapshot.
-   
    $ eck-snapshot update
-   -> Generates: .eck/snapshots/update_<timestamp>.md (Contains changed files + git diff)
+   -> Generates: .eck/snapshots/update_<timestamp>.md (Contains changed/deleted files)
 
 --- 🛠️ Managing Context Profiles ---
 
@@ -136,7 +130,7 @@ Option A: Auto-Detection (Best for start)
 
 Option B: Manual Guide (Best for large repos)
    If the project is too big for auto-detection, this generates a prompt text file
-   that you can paste into a powerful Web LLM (like Gemini 1.5 Pro) to design profiles manually.
+   that you can paste into a powerful Web LLM (like Gemini, Claude, or Grok) to design profiles manually.
    
    1. Run:  $ eck-snapshot generate-profile-guide
    2. Open: .eck/profile_generation_guide.md
@@ -155,6 +149,9 @@ Option C: Using Profiles
 - ask-claude:        Delegate tasks to Claude CLI agent.
 - setup-gemini:       Configure gemini-cli integration.
 - setup-mcp:          Setup/restore MCP servers (eck-core + glm-zai).
+
+--- 🧪 Experimental Features ---
+Run eck-snapshot snapshot --help to see experimental flags like --skeleton, --jas, --jaz.
 `;
 
   program

package/src/cli/commands/createSnapshot.js

@@ -629,19 +629,19 @@ export async function createRepoSnapshot(repoPath, options) {
       ...options // Command-line options have the final say
     };
 
-    // Detect architect modes
-    const isJas = options.jas;
-    const isJao = options.jao;
-    const isJaz = options.jaz;
-
-    // If NOT in Junior Architect mode, hide JA-specific documentation to prevent context pollution
-    if (!options.withJa && !isJas && !isJao && !isJaz) {
-      if (!config.filesToIgnore) config.filesToIgnore = [];
-      config.filesToIgnore.push(
-        'COMMANDS_REFERENCE.md',
-        'codex_delegation_snapshot.md'
-      );
-    }
+    // Detect architect modes
+    const isJas = options.jas;
+    const isJao = options.jao;
+    const isJaz = options.jaz;
+
+    // If NOT in Junior Architect mode, hide JA-specific documentation to prevent context pollution
+    if (!options.withJa && !isJas && !isJao && !isJaz) {
+      if (!config.filesToIgnore) config.filesToIgnore = [];
+      config.filesToIgnore.push(
+        'COMMANDS_REFERENCE.md',
+        'codex_delegation_snapshot.md'
+      );
+    }
 
     // Apply defaults for options that may not be provided via command line
     if (!config.output) {
@@ -720,83 +720,83 @@ export async function createRepoSnapshot(repoPath, options) {
       // File body always includes full content
       let fileBody = (directoryTree ? `\n## Directory Structure\n\n\`\`\`\n${directoryTree}\`\`\`\n\n` : '') + contentArray.join('');
 
-      // Helper to write snapshot file
-      const writeSnapshot = async (suffix, isAgentMode) => {
-        // CHANGE: Force agent to FALSE for the main snapshot header.
-        // The snapshot is read by the Human/Senior Arch, not the Agent itself.
-        // The Agent reads CLAUDE.md.
-        const opts = { ...options, agent: false, jas: isJas, jao: isJao, jaz: isJaz };
-        const header = await generateEnhancedAIHeader({ stats, repoName, mode: 'file', eckManifest, options: opts, repoPath: processedRepoPath }, isGitRepo);
-
-        // Compact filename format: eck{ShortName}{timestamp}_{hash}_{suffix}.md
-        // getShortRepoName ensures Capitalized Start/End (e.g. SnaOt)
-        const shortHash = gitHash ? gitHash.substring(0, 7) : '';
-        const shortRepoName = getShortRepoName(repoName);
-
-        let fname = `eck${shortRepoName}${timestamp}`;
-        if (shortHash) fname += `_${shortHash}`;
-
-        // Add mode suffix
-        if (options.skeleton) {
-          fname += '_sk';
-        } else if (suffix) {
-          fname += suffix;
-        }
-
-        const fullContent = header + fileBody;
-        const sizeKB = Math.max(1, Math.round(Buffer.byteLength(fullContent, 'utf-8') / 1024));
-        fname += `_${sizeKB}kb.${fileExtension}`;
-        const fpath = path.join(outputPath, fname);
-        await fs.writeFile(fpath, fullContent);
-        console.log(`📄 Generated Snapshot: ${fname}`);
-
-        // --- FEATURE: Active Snapshot (.eck/lastsnapshot/) ---
-        // Only create .eck/lastsnapshot/ entries for the main snapshot
-        if (!isAgentMode) {
-          try {
-            const snapDir = path.join(originalCwd, '.eck', 'lastsnapshot');
-            await fs.mkdir(snapDir, { recursive: true });
-
-            // 1. Clean up OLD snapshots in this specific folder
-            // We keep AnswerToSA.md, but remove old snapshots and legacy answer.md
-            const existingFiles = await fs.readdir(snapDir);
-            for (const file of existingFiles) {
-              if ((file.startsWith('eck') && file.endsWith('.md')) || file === 'answer.md') {
-                await fs.unlink(path.join(snapDir, file));
-              }
-            }
-
-            // 2. Save the NEW specific named file
-            await fs.writeFile(path.join(snapDir, fname), fullContent);
-
-            console.log(chalk.cyan(`📋 Active snapshot updated in .eck/lastsnapshot/: ${fname}`));
-          } catch (e) {
-            // Non-critical failure
-            console.warn(chalk.yellow(`⚠️  Could not update .eck/lastsnapshot/: ${e.message}`));
-          }
-        }
-        // --------------------------------------------
-
-        return fpath;
-      };
-
-      // Generate snapshot file for ALL modes
-      if (isJas) {
-        architectFilePath = await writeSnapshot('_jas', true);
-      } else if (isJao) {
-        architectFilePath = await writeSnapshot('_jao', true);
-      } else if (isJaz) {
-        architectFilePath = await writeSnapshot('_jaz', true);
-      } else {
-        // Standard snapshot behavior
-        architectFilePath = await writeSnapshot('', false);
-
-        // --- File 2: Junior Architect Snapshot (legacy --with-ja support) ---
-        if (options.withJa && fileExtension === 'md') {
-          console.log('🖋️ Generating Junior Architect (_ja) snapshot...');
-          jaFilePath = await writeSnapshot('_ja', true);
-        }
-      }
+      // Helper to write snapshot file
+      const writeSnapshot = async (suffix, isAgentMode) => {
+        // CHANGE: Force agent to FALSE for the main snapshot header.
+        // The snapshot is read by the Human/Senior Arch, not the Agent itself.
+        // The Agent reads CLAUDE.md.
+        const opts = { ...options, agent: false, jas: isJas, jao: isJao, jaz: isJaz };
+        const header = await generateEnhancedAIHeader({ stats, repoName, mode: 'file', eckManifest, options: opts, repoPath: processedRepoPath }, isGitRepo);
+
+        // Compact filename format: eck{ShortName}{timestamp}_{hash}_{suffix}.md
+        // getShortRepoName ensures Capitalized Start/End (e.g. SnaOt)
+        const shortHash = gitHash ? gitHash.substring(0, 7) : '';
+        const shortRepoName = getShortRepoName(repoName);
+
+        let fname = `eck${shortRepoName}${timestamp}`;
+        if (shortHash) fname += `_${shortHash}`;
+
+        // Add mode suffix
+        if (options.skeleton) {
+          fname += '_sk';
+        } else if (suffix) {
+          fname += suffix;
+        }
+
+        const fullContent = header + fileBody;
+        const sizeKB = Math.max(1, Math.round(Buffer.byteLength(fullContent, 'utf-8') / 1024));
+        fname += `_${sizeKB}kb.${fileExtension}`;
+        const fpath = path.join(outputPath, fname);
+        await fs.writeFile(fpath, fullContent);
+        console.log(`📄 Generated Snapshot: ${fname}`);
+
+        // --- FEATURE: Active Snapshot (.eck/lastsnapshot/) ---
+        // Only create .eck/lastsnapshot/ entries for the main snapshot
+        if (!isAgentMode) {
+          try {
+            const snapDir = path.join(originalCwd, '.eck', 'lastsnapshot');
+            await fs.mkdir(snapDir, { recursive: true });
+
+            // 1. Clean up OLD snapshots in this specific folder
+            // We keep AnswerToSA.md, but remove old snapshots and legacy answer.md
+            const existingFiles = await fs.readdir(snapDir);
+            for (const file of existingFiles) {
+              if ((file.startsWith('eck') && file.endsWith('.md')) || file === 'answer.md') {
+                await fs.unlink(path.join(snapDir, file));
+              }
+            }
+
+            // 2. Save the NEW specific named file
+            await fs.writeFile(path.join(snapDir, fname), fullContent);
+
+            console.log(chalk.cyan(`📋 Active snapshot updated in .eck/lastsnapshot/: ${fname}`));
+          } catch (e) {
+            // Non-critical failure
+            console.warn(chalk.yellow(`⚠️  Could not update .eck/lastsnapshot/: ${e.message}`));
+          }
+        }
+        // --------------------------------------------
+
+        return fpath;
+      };
+
+      // Generate snapshot file for ALL modes
+      if (isJas) {
+        architectFilePath = await writeSnapshot('_jas', true);
+      } else if (isJao) {
+        architectFilePath = await writeSnapshot('_jao', true);
+      } else if (isJaz) {
+        architectFilePath = await writeSnapshot('_jaz', true);
+      } else {
+        // Standard snapshot behavior
+        architectFilePath = await writeSnapshot('', false);
+
+        // --- File 2: Junior Architect Snapshot (legacy --with-ja support) ---
+        if (options.withJa && fileExtension === 'md') {
+          console.log('🖋️ Generating Junior Architect (_ja) snapshot...');
+          jaFilePath = await writeSnapshot('_ja', true);
+        }
+      }
 
       // Save git anchor for future delta updates
       await saveGitAnchor(processedRepoPath);
@@ -816,20 +816,20 @@ export async function createRepoSnapshot(repoPath, options) {
       console.log('🔐 Scanning for confidential files...');
       const confidentialFiles = await scanEckForConfidentialFiles(processedRepoPath, config);
 
-      let claudeMode = 'coder';
-      if (isJas) claudeMode = 'jas';
-      if (isJao) claudeMode = 'jao';
-      if (isJaz) claudeMode = 'jaz';
-
-      // Claude Code exclusively uses CLAUDE.md
-      if (isJas || isJao || (!isJaz && !options.withJa)) {
-        await updateClaudeMd(processedRepoPath, claudeMode, directoryTree, confidentialFiles, { zh: options.zh });
-      }
-
-      // OpenCode exclusively uses AGENTS.md
-      if (isJaz || (!isJas && !isJao && !options.withJa)) {
-        await generateOpenCodeAgents(processedRepoPath, claudeMode, directoryTree, confidentialFiles, { zh: options.zh });
-      }
+      let claudeMode = 'coder';
+      if (isJas) claudeMode = 'jas';
+      if (isJao) claudeMode = 'jao';
+      if (isJaz) claudeMode = 'jaz';
+
+      // Claude Code exclusively uses CLAUDE.md
+      if (isJas || isJao || (!isJaz && !options.withJa)) {
+        await updateClaudeMd(processedRepoPath, claudeMode, directoryTree, confidentialFiles, { zh: options.zh });
+      }
+
+      // OpenCode exclusively uses AGENTS.md
+      if (isJaz || (!isJas && !isJao && !options.withJa)) {
+        await generateOpenCodeAgents(processedRepoPath, claudeMode, directoryTree, confidentialFiles, { zh: options.zh });
+      }
 
       // --- Combined Report ---
       console.log('\n✅ Snapshot generation complete!');
@@ -924,6 +924,14 @@ export async function createRepoSnapshot(repoPath, options) {
         console.log('   Replace [ACTUAL_TOKENS_HERE] with the real token count from your LLM');
       }
 
+      // Output AI Prompt Suggestion for stubborn LLMs
+      console.log('\n🤖 AI PROMPT SUGGESTION (Crucial for ChatGPT, helpful for others):');
+      console.log('---------------------------------------------------');
+      console.log(chalk.yellow('💡 Tip: Claude, Gemini, and Grok handle large files best. ChatGPT works but can be slow.'));
+      console.log('If your AI ignores the file instructions and acts as an external reviewer,');
+      console.log('copy and paste this exact prompt along with your snapshot file:\n');
+      console.log(chalk.cyan.bold('Read the SYSTEM DIRECTIVE at the very beginning of the attached file. Immediately assume the role of Senior Architect as instructed, then await my first task.\n'));
+
     } finally {
       process.chdir(originalCwd); // Final reset back to original CWD
     }

package/src/cli/commands/generateProfileGuide.js

@@ -133,7 +133,7 @@ export async function generateProfileGuide(repoPath = process.cwd(), options = {
     // 3. Print clear instructions
     console.log(chalk.cyan('\n📋 Next Steps (Workflow):'));
     console.log(`1. Open: ${chalk.bold('.eck/profile_generation_guide.md')}`);
-    console.log('2. Copy the PROMPT + TREE content and paste it into an AI (Gemini 1.5 Pro, Claude Opus, ChatGPT).');
+    console.log('2. Copy the PROMPT + TREE content and paste it into an AI (Gemini, Claude, Grok).');
     console.log('3. Copy the JSON response from the AI.');
     console.log(`4. Paste the JSON into: ${chalk.bold('.eck/profiles.json')} ${profilesCreated ? '(I created this file for you)' : '(File exists)'}`);
     console.log('\n✅ Once saved, run: ' + chalk.green('eck-snapshot --profile <profile_name>'));

package/src/templates/multiAgent.md

@@ -1,8 +1,14 @@
-# AI Instructions
+# SYSTEM DIRECTIVE FOR THE ACTIVE AI AGENT
 
-## 1. How to Read This Snapshot
+**CRITICAL:** If you are the AI (LLM) reading this file in the current chat session, you must IMMEDIATELY assume the role defined below. Do not act as an external reviewer or generic assistant. This document is your active operating environment and contract.
 
-This document is a self-contained, single-file snapshot of the **{{repoName}}** software repository, generated by the `eck-snapshot` tool on **{{timestamp}}**. It is designed to provide a Large Language Model (LLM) with the complete context of a project.
+## 1. Your Role & Identity
+
+You are the **Senior Project Manager and Solution Architect AI**. Your primary goal is to translate user requests into technical plans and then generate precise commands for code-execution AI agents.
+
+## 2. How to Read This Snapshot
+
+This document is a self-contained, single-file snapshot of the **{{repoName}}** software repository, generated by the `eck-snapshot` tool on **{{timestamp}}**. Treat the file structure and code below as your absolute source of truth for the project state.
 
 * **Source of Truth:** Treat this snapshot as the complete and authoritative source code.
 * **Structure:** The file contains a **Directory Structure** tree, followed by the full content of each file, demarcated by `--- File: /path/to/file ---` headers.
@@ -13,15 +19,13 @@ This document is a self-contained, single-file snapshot of the **{{repoName}}**
 
 ---
 
-## 2. Your Core Operational Workflow
-
-You are the Project Manager and Solution Architect AI. Your primary goal is to translate user requests into technical plans and then generate precise commands for code-execution AI agents.
+## 3. Your Core Operational Workflow
 
 {{projectOverview}}
 
 {{eckManifestSection}}
 
-### 🛠 MANIFEST MAINTENANCE PROTOCOL (CRITICAL)
+### MANIFEST MAINTENANCE PROTOCOL (CRITICAL)
 
 The `.eck/` directory files are your "Source of Knowledge".
 1. **Stub Detection:** If a file starts with `# [STUB: ...]`, it means the system failed to auto-generate meaningful content.
@@ -100,7 +104,7 @@ The Coder agent is intelligent and will understand what information they need ba
 6.  **Review & Report:** After the command is executed, analyze the results and report back to the user in their language.
 7.  **Iterate:** Continue the cycle based on user feedback.
 
-### 🛡️ ANTI-TRUNCATION PROTOCOL (CRITICAL)
+### ANTI-TRUNCATION PROTOCOL (CRITICAL)
 
 Web interfaces (like Gemini or ChatGPT) sometimes silently drop the content of large text files during upload, replacing the file's content with a tiny JSON metadata string (e.g., `{"fileName": "...", "contentFetchId": "..."}`).
 
@@ -108,7 +112,7 @@ Web interfaces (like Gemini or ChatGPT) sometimes silently drop the content of l
 1. **Always check the filename:** The exact file size in kilobytes is appended to the end of every snapshot filename (e.g., `..._up7_1250kb.md`).
 2. **Verify payload length:** If the filename says `1250kb` but the text you actually received for that file is only a few lines long or looks like a system JSON string, **THE CONTENT WAS TRUNCATED BY THE UI**.
 3. **Alert the User:** DO NOT hallucinate the missing code. Immediately stop and tell the user:
-   > "🚨 **System Error:** The web interface truncated the file `[FileName]`. I only received the metadata/JSON stub, not the actual `[Size]kb` of code. Please split the snapshot or paste the text directly."
+   > "**System Error:** The web interface truncated the file `[FileName]`. I only received the metadata/JSON stub, not the actual `[Size]kb` of code. Please split the snapshot or paste the text directly."
 
 {{hierarchicalWorkflow}}
 
@@ -125,4 +129,3 @@ Web interfaces (like Gemini or ChatGPT) sometimes silently drop the content of l
 You can command multiple specialized agents. **YOU must choose the most appropriate agent** based on the task requirements and target environment:
 
 {{agentDefinitions}}
-

package/src/utils/aiHeader.js

@@ -72,11 +72,11 @@ function getVisibleAgents(executionAgents, options) {
   // These keys must match IDs in setup.json
   const standardCoders = ['local_dev', 'production_server', 'android_wsl_dev'];
 
-  // 2. Determine Priority Agent (The Junior Architect)
-  let priorityAgentKey = null;
-  if (options.jas) priorityAgentKey = 'jas';
-  if (options.jao) priorityAgentKey = 'jao';
-  if (options.jaz) priorityAgentKey = 'jaz';
+  // 2. Determine Priority Agent (The Junior Architect)
+  let priorityAgentKey = null;
+  if (options.jas) priorityAgentKey = 'jas';
+  if (options.jao) priorityAgentKey = 'jao';
+  if (options.jaz) priorityAgentKey = 'jaz';
 
   // 3. Build the list
   // If a JA is selected, add them FIRST with a note
@@ -438,10 +438,10 @@ ${operationsSection}
     // The `agent` prompt template is used ONLY in CLAUDE.md (via claudeMdGenerator.js)
     // NOT in the snapshot itself.
 
-    const isJas = context.options && context.options.jas;
-    const isJao = context.options && context.options.jao;
-    const isJaz = context.options && context.options.jaz;
-    const isJaMode = isJas || isJao || isJaz;
+    const isJas = context.options && context.options.jas;
+    const isJao = context.options && context.options.jao;
+    const isJaz = context.options && context.options.jaz;
+    const isJaMode = isJas || isJao || isJaz;
 
     // --- Determine Workflow Content based on JA Flag ---
     let hierarchicalWorkflow = '';
@@ -449,15 +449,15 @@ ${operationsSection}
 
     if (isJaMode) {
       // Instructions strictly for the Senior Architect on how to use the JA
-      hierarchicalWorkflow = `### 👑 ROYAL COURT ARCHITECTURE (Active)
-
-You are the **Senior Architect**. You have a **Junior Architect** available to handle implementation.
-
-**PROTOCOL:**
-1.  **Prefer Delegation:** Unless the task is trivial (1-2 file edits), assign it to the **Junior Architect** (ID: \`jas\`, \`jao\`, or \`jaz\` - see agents list above).
-2.  **Direct Execution:** Only use \`local_dev\` or \`production_server\` directly if the Junior Architect fails or for simple "hotfixes".
-3.  **No Micro-Management:** Do not tell the Junior Architect *how* to use GLM Z.AI or internal tools. Just give them the strategic objective.
-`;
+      hierarchicalWorkflow = `### 👑 ROYAL COURT ARCHITECTURE (Active)
+
+You are the **Senior Architect**. You have a **Junior Architect** available to handle implementation.
+
+**PROTOCOL:**
+1.  **Prefer Delegation:** Unless the task is trivial (1-2 file edits), assign it to the **Junior Architect** (ID: \`jas\`, \`jao\`, or \`jaz\` - see agents list above).
+2.  **Direct Execution:** Only use \`local_dev\` or \`production_server\` directly if the Junior Architect fails or for simple "hotfixes".
+3.  **No Micro-Management:** Do not tell the Junior Architect *how* to use GLM Z.AI or internal tools. Just give them the strategic objective.
+`;
 
       commandFormats = `### COMMAND FORMATS (Eck-Protocol v2)
 
@@ -516,11 +516,11 @@ Use \`apply_code_changes\` for simple, direct tasks where you provide all detail
   "agent_environment": "Development environment with full GUI support and development tools",
   "command_for_agent": "apply_code_changes",
   "task_id": "unique-task-id",
-    "payload": {
-      "objective": "Brief, clear task description",
-      "context": "Why this change is needed - include relevant .eck manifest context",
-      "architect_confidence": "high (90%) - I am certain of this plan / low (30%) - Please investigate first",
-      "files_to_modify": [
+    "payload": {
+      "objective": "Brief, clear task description",
+      "context": "Why this change is needed - include relevant .eck manifest context",
+      "architect_confidence": "high (90%) - I am certain of this plan / low (30%) - Please investigate first",
+      "files_to_modify": [
       {
         "path": "exact/file/path.js",
         "action": "specific action (add, modify, replace, delete)",
@@ -687,7 +687,10 @@ const x = 1;
 
   } catch (error) {
     console.warn('Warning: Could not load setup.json, using minimal header', error.message);
-    return `# Snapshot for ${context.repoName || 'Project'}
+    return `# SYSTEM DIRECTIVE FOR THE ACTIVE AI AGENT
+**CRITICAL:** If you are the AI reading this, immediately assume the role of Solution Architect for this project. Do not act as an external reviewer.
+
+# Snapshot for ${context.repoName || 'Project'}
 
 Generated: ${new Date().toISOString()}