@xelth/eck-snapshot 6.0.3 → 6.0.5

package/README.md

@@ -2,35 +2,35 @@
 
 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.
 
-## 🎯 The Battle-Tested Workflow (Author's Note)
 
-I personally use this tool daily with both **Claude Code** and **OpenCode**. My reliable, heavily-tested workflow is:
+## 🎯 The Battle-Tested Workflow & Quick Start
 
-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.
+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:
 
-This core loop is highly polished, actively maintained, and works exceptionally well.
-
-## 🚀 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
-# 1. Create a standard full snapshot (Core Workflow)
-eck-snapshot snapshot
+eck-snapshot
+```
+*(For massive monorepos, slice the context using profiles: `eck-snapshot --profile frontend`)*
 
-# 2. Use profiles for large monorepos
-eck-snapshot snapshot --profile backend
+### 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.
 
-# 3. Create an incremental update (only changed/deleted files)
+### 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.
+
+**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.
 
 ## 🌟 Core Features
 
@@ -45,9 +45,20 @@ eck-snapshot update
 
 *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!)*
 
-* **🧠 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.
+* **🧠 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.
 
+
+## 💡 The Philosophy: Why force a full snapshot?
+
+You've probably noticed a pattern: the longer you chat with an LLM about your codebase, the smarter it gets and the better its code becomes. 
+
+How do you get that expert-level understanding from the very first prompt? You can't rely on an agent guessing which isolated files to read based on filenames. You need to force-feed it the entire context at once. 
+
+Think of AI models like human engineers. Imagine a person standing next to a massive bookshelf of programming textbooks. The total amount of information available to them is exactly the same before they go to university and after they graduate. Both can open a book, check the table of contents, and look up a formula. Yet, the results they produce are vastly different. Why? Because the graduate has the structural context *inside their head*. 
+
+LLMs work the exact same way. Giving an AI a "file search" tool is like putting a beginner next to the bookshelf. Forcing a complete project snapshot into the LLM's massive context window is like giving it a university degree in your specific codebase. That is what `eck-snapshot` does.
+
 ## License
 MIT © xelth-com

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "6.0.3",
+  "version": "6.0.5",
   "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

@@ -116,8 +116,8 @@ export function run() {
    (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.
+   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:
 
    $ eck-snapshot update
    -> Generates: .eck/snapshots/update_<timestamp>.md (Contains changed/deleted files)