@xelth/eck-snapshot 6.0.1 → 6.0.3

package/README.md

@@ -1,15 +1,17 @@
 # 📸 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 (Author's Note)
 
-* **🧠 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 both **Claude Code** and **OpenCode**. My reliable, heavily-tested workflow is:
+
+1. **Full Snapshots:** I take a full snapshot (`eck-snapshot snapshot`) and feed it to a powerful Web LLM (Senior Architect like Gemini 1.5 Pro or Grok 3).
+2. **Context Profiles:** If the project is huge, I use context profiles (`--profile frontend`) to slice it into manageable pieces.
+3. **Direct Execution:** I write code directly using the Senior Architect's guidance and execute tasks via local Coders (Claude/OpenCode).
+4. **Incremental Updates:** After changes are made, I use delta updates (`eck-snapshot update`) to keep the Architect's context perfectly synced without resending the whole repo.
+
+This core loop is highly polished, actively maintained, and works exceptionally well.
 
 ## 🚀 Quick Start
 
@@ -20,52 +22,32 @@ npm install -g @xelth/eck-snapshot
 
 ### Basic Usage
 ```bash
-# Create a standard full snapshot
+# 1. Create a standard full snapshot (Core Workflow)
 eck-snapshot snapshot
 
-# Create a highly compressed skeleton snapshot
-eck-snapshot snapshot --skeleton
+# 2. Use profiles for large monorepos
+eck-snapshot snapshot --profile backend
 
-# Create an incremental update (only changed/deleted files)
+# 3. Create an incremental update (only changed/deleted files)
 eck-snapshot update
 ```
 
-## 🤖 AI Swarm Setup (GLM Z.AI)
-
-eckSnapshot v6 acts as the bridge between your primary AI IDE (Claude Code or OpenCode) and a cost-effective GLM-4.7 worker swarm.
-
-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)
-   ```
+## 🌟 Core Features
 
-## 📁 The `.eck/` Manifest Directory
+* **🔄 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.
 
-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
+---
 
-*Note: The tool automatically filters confidential files like `SERVER_ACCESS.md` from snapshots to ensure security.*
+## 🧪 Experimental / Advanced Features
 
-## 📈 Token Estimation
+*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!)*
 
-Train the local estimator to perfectly predict token counts for your specific project:
-```bash
-# Manually push agent telemetry
-eck-snapshot telemetry push
-
-# 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-4.7 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.1",
+  "version": "6.0.3",
   "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
+   As you or your local coders (Claude/OpenCode) apply changes, the Web AI loses context.
+   Instead of re-sending the full repo, send only what changed.
 
-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/templates/opencode/coder.template.md

@@ -6,17 +6,20 @@ You are an Expert Developer. The architecture is already decided. Your job is to
 ## DEFINITION OF DONE (CRITICAL)
 When task is complete, you must report back and sync context.
 
-**OPTION A: Using MCP Tool (Recommended)**
-Call the \`eck_finish_task\` tool. Pass your detailed markdown report into the \`status\` argument.
-- The tool will automatically write the report to \`AnswerToSA.md\`, commit, and generate a snapshot.
-- **DO NOT** manually write to \`AnswerToSA.md\` with your file editing tools (it will fail safety checks).
-- **WARNING: USE ONLY ONCE.** Do not use \`eck_finish_task\` for intermediate testing. It spams snapshot history.
+**PRIMARY METHOD: Use `eck_finish_task` MCP tool.**
+Pass your detailed markdown report into the `status` argument.
+- The tool will automatically write the report, commit, and generate a snapshot.
+- **DO NOT** manually write to `AnswerToSA.md` with your file editing tools.
+- **WARNING: USE ONLY ONCE.** Do not use for intermediate testing.
 
-**OPTION B: Manual CLI (Fallback)**
-If the MCP tool is unavailable:
-1. **READ** \`.eck/lastsnapshot/AnswerToSA.md\` using your \`Read\` tool (REQUIRED by safety rules before overwriting).
-2. **WRITE** your report to that file.
-3. Run \`eck-snapshot update\` in terminal.
+**FALLBACK METHOD (Only if MCP tool is missing):**
+If `eck_finish_task` is NOT in your available tools, you MUST do the following:
+0. **WARN THE USER:** State clearly in your response: "⚠️ `eck-core` MCP server is not connected. Proceeding with manual fallback."
+1. **READ:** Read `.eck/lastsnapshot/AnswerToSA.md` using your `Read` tool (REQUIRED before overwriting).
+2. **WRITE:** Overwrite that file with your report.
+3. **COMMIT (CRITICAL):** Run `git add .` and `git commit -m "chore: task report"` in the terminal.
+4. **SNAPSHOT:** Run `eck-snapshot update` in the terminal.
+*(Note: The snapshot compares against the git anchor. If you skip step 3, it will say "No changes detected").*
 
 ## PROJECT CONTEXT (.eck DIRECTORY)
 The `.eck/` directory contains critical project documentation. **Before starting your task, you MUST:**

package/src/templates/opencode/junior-architect.template.md

@@ -36,18 +36,21 @@ For bulk work where delegation saves YOUR expensive context window, YOU MUST del
 ## 4. DEFINITION OF DONE (CRITICAL)
 When you have completed your coding task and verified it works, you must report back and sync context.
 
-**OPTION A: Using MCP Tool (Recommended)**
-Call the \`eck_finish_task\` tool. Pass your detailed markdown report into the \`status\` argument.
-- The tool will automatically write the report to \`AnswerToSA.md\`, commit, and generate a snapshot.
-- **DO NOT** manually write to \`AnswerToSA.md\` with your file editing tools.
-- **WARNING: USE ONLY ONCE.** Do not use \`eck_finish_task\` for intermediate testing. It spams snapshot history.
+**PRIMARY METHOD: Use `eck_finish_task` MCP tool.**
+Pass your detailed markdown report into the `status` argument.
+- The tool will automatically write the report, commit, and generate a snapshot.
+- **DO NOT** manually write to `AnswerToSA.md` with your file editing tools.
+- **WARNING: USE ONLY ONCE.** Do not use for intermediate testing.
 
-**OPTION B: Manual CLI (Fallback)**
-If the MCP tool is unavailable:
-1. **READ** \`.eck/lastsnapshot/AnswerToSA.md\` using your \`Read\` tool (REQUIRED by safety rules before overwriting).
-2. **WRITE** your report to that file.
-3. Run \`eck-snapshot update\` in terminal.
-4. If you are entirely blocked, use the \`eck_fail_task\` tool.
+**FALLBACK METHOD (Only if MCP tool is missing):**
+If `eck_finish_task` is NOT in your available tools, you MUST do the following:
+0. **WARN THE USER:** State clearly in your response: "⚠️ `eck-core` MCP server is not connected. Proceeding with manual fallback."
+1. **READ:** Read `.eck/lastsnapshot/AnswerToSA.md` using your `Read` tool (REQUIRED before overwriting).
+2. **WRITE:** Overwrite that file with your report.
+3. **COMMIT (CRITICAL):** Run `git add .` and `git commit -m "chore: task report"` in the terminal.
+4. **SNAPSHOT:** Run `eck-snapshot update` in the terminal.
+*(Note: The snapshot compares against the git anchor. If you skip step 3, it will say "No changes detected").*
+5. If you are entirely blocked, use the `eck_fail_task` tool.
 
 ## 5. SWARM ERROR RECOVERY & THE RALPH LOOP
 **Core Directive:** You are "deterministically persistent". Failures are expected, giving up is not.

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()}
 

package/src/utils/claudeMdGenerator.js

@@ -48,9 +48,18 @@ Your task is NOT complete until code works globally.
 2. **Finish & Report:** Use the \`eck_finish_task\` MCP tool.
    - Pass your full markdown report into the \`status\` argument.
    - The tool will automatically write the report to \`.eck/lastsnapshot/AnswerToSA.md\`, commit, and generate a snapshot.
-   - **DO NOT** try to manually write to \`.eck/lastsnapshot/AnswerToSA.md\` with the \`Write\` tool (it will fail safety checks).
+   - **DO NOT** try to manually write to \`.eck/lastsnapshot/AnswerToSA.md\` with the \`Write\` tool.
    - **WARNING:** USE ONLY ONCE PER TASK. Do not use this tool or \`eck-snapshot update\` for intermediate testing.
 
+**FALLBACK METHOD (Only if MCP tool is missing):**
+If \`eck_finish_task\` is NOT in your available tools, you MUST do the following:
+0. **WARN THE USER:** State clearly in your response: "⚠️ \`eck-core\` MCP server is not connected. Proceeding with manual fallback."
+1. **READ:** Read \`.eck/lastsnapshot/AnswerToSA.md\` using your \`Read\` tool (REQUIRED before overwriting).
+2. **WRITE:** Overwrite that file with your report.
+3. **COMMIT (CRITICAL):** Run \`git add .\` and \`git commit -m "chore: task report"\` in the terminal.
+4. **SNAPSHOT:** Run \`eck-snapshot update\` in the terminal.
+*(Note: The snapshot compares against the git anchor. If you skip step 3, it will say "No changes detected").*
+
 ## 5. SWARM ERROR RECOVERY & ARCHITECT HYPOTHESES
 1. **Runtime Check:** Always check the \`.eck/RUNTIME_STATE.md\` and running processes before coding.
 2. **Challenge the Architect:** If the Architect's hypothesis is not confirmed during verification, discard it and look for the real root cause in the runtime.
@@ -72,17 +81,20 @@ You are an Expert Developer. The architecture is already decided. Your job is to
 ## DEFINITION OF DONE (CRITICAL)
 When task is complete, you must report back and sync context.
 
-**OPTION A: Using MCP Tool (Recommended)**
-Call the \`eck_finish_task\` tool. Pass your detailed markdown report into the \`status\` argument.
-- The tool will automatically write the report to \`AnswerToSA.md\`, commit, and generate a snapshot.
-- **DO NOT** manually write to \`AnswerToSA.md\` with your file editing tools (it will fail safety checks).
-- **WARNING: USE ONLY ONCE.** Do not use \`eck_finish_task\` for intermediate testing.
-
-**OPTION B: Manual CLI (Fallback)**
-If the MCP tool is unavailable:
-1. **READ** \`.eck/lastsnapshot/AnswerToSA.md\` using your \`Read\` tool (REQUIRED by safety rules before overwriting).
-2. **WRITE** your report to that file.
-3. Run \`eck-snapshot update\` in terminal.
+**PRIMARY METHOD: Use \`eck_finish_task\` MCP tool.**
+Pass your detailed markdown report into the \`status\` argument.
+- The tool will automatically write the report, commit, and generate a snapshot.
+- **DO NOT** manually write to \`AnswerToSA.md\` with your file editing tools.
+- **WARNING: USE ONLY ONCE.** Do not use for intermediate testing.
+
+**FALLBACK METHOD (Only if MCP tool is missing):**
+If \`eck_finish_task\` is NOT in your available tools, you MUST do the following:
+0. **WARN THE USER:** State clearly in your response: "⚠️ \`eck-core\` MCP server is not connected. Proceeding with manual fallback."
+1. **READ:** Read \`.eck/lastsnapshot/AnswerToSA.md\` using your \`Read\` tool (REQUIRED before overwriting).
+2. **WRITE:** Overwrite that file with your report.
+3. **COMMIT (CRITICAL):** Run \`git add .\` and \`git commit -m "chore: task report"\` in the terminal.
+4. **SNAPSHOT:** Run \`eck-snapshot update\` in the terminal.
+*(Note: The snapshot compares against the git anchor. If you skip step 3, it will say "No changes detected").*
 
 ## PROJECT CONTEXT (.eck DIRECTORY)
 The \`.eck/\` directory contains critical project documentation. **Before starting your task, you MUST:**