@xelth/eck-snapshot 4.3.0 → 4.3.2

package/README.md

@@ -32,33 +32,9 @@ npm install -g @xelth/eck-snapshot
 
 Once installed, you can run the tool using the `eck-snapshot` command from any directory.
 
-## Workflow Options
+## Getting Started: Full Snapshot Workflow
 
-### Option 1: Skeleton Workflow (Recommended for Large Projects)
-
-The skeleton workflow is optimized for web-based LLMs (Gemini, ChatGPT) with large context windows. It uses a three-step approach:
-
-1. **Initial Context (Maximum Compression):** Create a lightweight map of your entire project where function/method bodies are hidden, showing only signatures and structure.
-   ```bash
-   eck-snapshot --skeleton
-   ```
-   This generates `.eck/snapshots/<name>_sk.md` - a compressed overview that fits even large monoliths into the context window.
-
-2. **Lazy Loading (On-Demand Details):** When the AI needs implementation details, use the `show` command to display specific files:
-   ```bash
-   eck-snapshot show src/auth.js src/utils/hash.js
-   ```
-   Copy-paste the output back to your AI chat.
-
-3. **Incremental Updates:** As you make changes, send only what changed since the last snapshot instead of the entire repo:
-   ```bash
-   eck-snapshot update
-   ```
-   This generates `.eck/snapshots/update_<timestamp>.md` containing only changed files and git diffs.
-
-### Option 2: Full Snapshot Workflow
-
-Here's the traditional workflow for creating complete snapshots and focusing on specific features.
+This is the primary workflow for creating complete snapshots of your project.
 
 #### Step 1: Create a Full Project Snapshot
 
@@ -130,6 +106,70 @@ A faster, non-AI method to reduce snapshot size. This command keeps only the top
 > eck-snapshot --max-lines-per-file 200
 > ```
 
+## Skeleton Workflow (Advanced for Large Projects)
+
+The skeleton workflow is optimized for web-based LLMs (Gemini, ChatGPT) with large context windows. It uses a three-step approach for maximum compression:
+
+### 1. Initial Context (Maximum Compression)
+
+Create a lightweight map of your entire project where function/method bodies are hidden, showing only signatures and structure.
+
+```bash
+eck-snapshot --skeleton
+```
+
+This generates `.eck/snapshots/<name>_sk.md` - a compressed overview that fits even large monoliths into the context window.
+
+### 2. Lazy Loading (On-Demand Details)
+
+When the AI needs implementation details, use the `show` command to display specific files:
+
+```bash
+eck-snapshot show src/auth.js src/utils/hash.js
+```
+
+Copy-paste the output back to your AI chat.
+
+### 3. Incremental Updates
+
+After making changes, use the `update` command (see section below) to send only what changed.
+
+## Incremental Updates: The `update` Command
+
+The `update` command is a powerful feature that creates **delta snapshots** containing only the files that changed since your last full snapshot. This is essential for maintaining AI context efficiently during active development.
+
+### How It Works
+
+1. **Anchor Point:** When you create a full snapshot (with `eck-snapshot` or `eck-snapshot --skeleton`), the current git commit hash is saved as an "anchor" in `.eck/.snapshot-anchor`.
+
+2. **Change Detection:** The `update` command compares your current working directory against this anchor to identify all modified, added, or deleted files.
+
+3. **Delta Generation:** It creates a new snapshot file containing:
+   - Only the changed files (with full content)
+   - A git diff showing all changes for context
+   - Clear instructions for the AI to merge these changes with the base snapshot
+
+### Usage
+
+```bash
+eck-snapshot update
+```
+
+This generates `.eck/snapshots/update_<timestamp>.md`.
+
+### When to Use
+
+- **During active development:** After making changes based on AI suggestions, send an update instead of the entire codebase
+- **Iterative workflows:** Keep the AI synchronized with your latest code without re-uploading everything
+- **Large projects:** Especially valuable when the full snapshot is large - updates are typically much smaller
+
+### Important Notes
+
+- You must create a full snapshot first before using `update`
+- Each update is self-contained - send only the latest update to the AI, not all previous updates
+- The AI is instructed to "merge" the update over the base snapshot mentally
+- Works with both regular and skeleton snapshots
+
 ## Auxiliary Commands
 
 *   `restore <snapshot_file>`: Recreates a project's file structure from a snapshot.

package/package.json

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