@xelth/eck-snapshot 4.2.3 → 4.3.1

package/README.md

@@ -32,9 +32,29 @@ npm install -g @xelth/eck-snapshot
 
 Once installed, you can run the tool using the `eck-snapshot` command from any directory.
 
-## A Step-by-Step Guide to Using eckSnapshot
+## Workflow Options
 
-Here’s the most common workflow, from creating a full snapshot to focusing on specific features.
+### 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:** See the dedicated section below for details on the `update` command.
+
+### Option 2: Full Snapshot Workflow
+
+Here's the traditional workflow for creating complete snapshots and focusing on specific features.
 
 #### Step 1: Create a Full Project Snapshot
 
@@ -106,16 +126,56 @@ A faster, non-AI method to reduce snapshot size. This command keeps only the top
 > eck-snapshot --max-lines-per-file 200
 > ```
 
+## 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.
 *   `generate-profile-guide`: Creates a guide for manual profile creation. Use this if `profile-detect` fails on very large projects, as it allows you to use an LLM with a larger context window (e.g., a web UI).
 *   `detect`: Shows how `eckSnapshot` has identified your project type and what default file filters are being applied.
-*   `ask-gpt` / `ask-claude`: Directly delegate a task to your configured AI coder agents from the command line.
+*   `ask-claude`: Directly delegate a task to your configured Claude Code CLI agent from the command line.
 *   `setup-gemini`: A utility to automatically configure integration with the `gemini-cli`.
 
 For a full list of commands and options, run `eck-snapshot --help`.
 
+## Experimental Features
+
+⚠️ **juniorArchitect**: This feature is currently under development and not yet functional. It's intended to provide automated architectural analysis and suggestions. Contributions to complete this feature are welcome!
+
 ## License
 
 This project is licensed under the MIT License.

package/package.json

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