@xelth/eck-snapshot 5.9.0 → 6.4.1

package/src/cli/commands/trainTokens.js

@@ -1,38 +1,48 @@
-import { addTrainingPoint, showEstimationStats } from '../../utils/tokenEstimator.js';
+import chalk from 'chalk';
+import ora from 'ora';
+import { addTrainingPoint, showEstimationStats, syncTokenWeights } from '../../utils/tokenEstimator.js';
 
-/**
- * Train token estimation with actual results
- * @param {string} projectType - Type of project (android, nodejs, etc.)
- * @param {string} fileSizeStr - File size in bytes
- * @param {string} estimatedStr - Estimated tokens
- * @param {string} actualStr - Actual tokens (from user input)
- */
-export async function trainTokens(projectType, fileSizeStr, estimatedStr, actualStr) {
+export async function runTokenTools(payload) {
+  const toolName = payload.name;
+  const args = payload.arguments || {};
+
+  if (toolName === 'eck_train_tokens') {
+    await handleTrainTokens(args);
+  } else if (toolName === 'eck_token_stats') {
+    await handleTokenStats();
+  }
+}
+
+async function handleTrainTokens(args) {
+  const { projectType, fileSizeBytes, estimatedTokens, actualTokens } = args;
+
+  if (!projectType || fileSizeBytes === undefined || estimatedTokens === undefined || actualTokens === undefined) {
+    console.log(chalk.red('❌ Error: Missing required arguments for eck_train_tokens.'));
+    console.log(chalk.yellow('Expected: { projectType, fileSizeBytes, estimatedTokens, actualTokens }'));
+    return;
+  }
+
+  const spinner = ora('Calibrating token estimation polynomial...').start();
   try {
-    const fileSizeInBytes = parseInt(fileSizeStr, 10);
-    const estimatedTokens = parseInt(estimatedStr, 10);
-    
-    // Parse actual tokens from user input (remove any text like "tokens", commas, etc.)
-    const actualTokens = parseInt(actualStr.replace(/[^\d]/g, ''), 10);
-    
-    if (isNaN(fileSizeInBytes) || isNaN(estimatedTokens) || isNaN(actualTokens)) {
-      throw new Error('Invalid numeric values provided');
-    }
-    
-    await addTrainingPoint(projectType, fileSizeInBytes, estimatedTokens, actualTokens);
-    
-    console.log('\n📈 Updated polynomial coefficients for improved estimation.');
-    
+    await addTrainingPoint(
+      projectType,
+      Number(fileSizeBytes),
+      Number(estimatedTokens),
+      Number(actualTokens)
+    );
+    spinner.succeed('Token estimation calibrated successfully.');
   } catch (error) {
-    console.error(`❌ Error training token estimation: ${error.message}`);
-    console.error('Usage: eck-snapshot train-tokens <project-type> <file-size-bytes> <estimated-tokens> <actual-tokens>');
-    process.exit(1);
+    spinner.fail(`Calibration failed: ${error.message}`);
   }
 }
 
-/**
- * Show token estimation statistics
- */
-export async function showTokenStats() {
-  await showEstimationStats();
-}
+async function handleTokenStats() {
+  const spinner = ora('Fetching latest token statistics and weights...').start();
+  try {
+    await syncTokenWeights(true);
+    spinner.stop();
+    await showEstimationStats();
+  } catch (error) {
+    spinner.fail(`Failed to fetch statistics: ${error.message}`);
+  }
+}

package/src/cli/commands/updateSnapshot.js

@@ -1,15 +1,16 @@
-import fs from 'fs/promises';
-import path from 'path';
-import ora from 'ora';
-import chalk from 'chalk';
-import isBinaryPath from 'is-binary-path';
-import { getGitAnchor, getChangedFiles } from '../../utils/gitUtils.js';
-import { loadSetupConfig } from '../../config.js';
-import { readFileWithSizeCheck, parseSize, formatSize, matchesPattern, loadGitignore, generateTimestamp, getShortRepoName } from '../../utils/fileUtils.js';
-import { detectProjectType, getProjectSpecificFiltering } from '../../utils/projectDetector.js';
-import { execa } from 'execa';
-import { fileURLToPath } from 'url';
-import { pushTelemetry } from '../../utils/telemetry.js';
+import fs from 'fs/promises';
+import path from 'path';
+import ora from 'ora';
+import chalk from 'chalk';
+import isBinaryPath from 'is-binary-path';
+import { getGitAnchor, getChangedFiles } from '../../utils/gitUtils.js';
+import { loadSetupConfig } from '../../config.js';
+import { readFileWithSizeCheck, parseSize, formatSize, matchesPattern, loadGitignore, generateTimestamp, getShortRepoName } from '../../utils/fileUtils.js';
+import { detectProjectType, getProjectSpecificFiltering } from '../../utils/projectDetector.js';
+import { execa } from 'execa';
+import { fileURLToPath } from 'url';
+import { pushTelemetry } from '../../utils/telemetry.js';
+import { syncTokenWeights } from '../../utils/tokenEstimator.js';
 
 // Mirror the same hidden-path guard used in createSnapshot.js
 function isHiddenPath(filePath) {
@@ -42,52 +43,95 @@ async function generateSnapshotContent(repoPath, changedFiles, anchor, config, g
   let includedCount = 0;
   const fileList = [];
 
-  // Include Agent Report if it exists and hasn't been embedded yet
-  let agentReport = null;
-  const reportPath = path.join(repoPath, '.eck', 'lastsnapshot', 'AnswerToSA.md');
-  try {
-    const reportContent = await fs.readFile(reportPath, 'utf-8');
-    if (!reportContent.includes('[SYSTEM: EMBEDDED]')) {
-      agentReport = reportContent;
-      await fs.appendFile(reportPath, '\n\n[SYSTEM: EMBEDDED]\n', 'utf-8');
-    }
-  } catch (e) { /* File not found or unreadable */ }
+  // Include Agent Report if it exists and hasn't been embedded yet
+  let agentReport = null;
+  const reportPath = path.join(repoPath, '.eck', 'lastsnapshot', 'AnswerToSA.md');
+  const lockPath = path.join(repoPath, '.eck', 'lastsnapshot', 'AnswerToSA.lock');
+  try {
+    // Use atomic directory creation as a lock to prevent race conditions
+    await fs.mkdir(lockPath);
+    const reportContent = await fs.readFile(reportPath, 'utf-8');
+    
+    if (!reportContent.includes('[SYSTEM: EMBEDDED]')) {
+      agentReport = reportContent;
+
+      // Immediately mark as embedded to release the race window
+      await fs.appendFile(reportPath, '\n\n[SYSTEM: EMBEDDED]\n', 'utf-8');
+
+      // Auto-Journaling: prepend agent report to JOURNAL.md
+      const journalPath = path.join(repoPath, '.eck', 'JOURNAL.md');
+      try {
+        const dateStr = new Date().toISOString().split('T')[0];
+        const journalEntry = `## ${dateStr} — Agent Report\n\n${reportContent.trim()}\n`;
+
+        let existingJournal = '';
+        try {
+          existingJournal = await fs.readFile(journalPath, 'utf-8');
+        } catch (e) { /* might not exist */ }
+
+        const insertPos = existingJournal.indexOf('\n## ');
+        if (insertPos !== -1) {
+          const newJournal = existingJournal.slice(0, insertPos) + '\n\n' + journalEntry + existingJournal.slice(insertPos);
+          await fs.writeFile(journalPath, newJournal, 'utf-8');
+        } else {
+          await fs.writeFile(journalPath, (existingJournal ? existingJournal + '\n\n' : '') + journalEntry + '\n', 'utf-8');
+        }
+      } catch (je) {
+        console.warn('Could not auto-update JOURNAL.md', je.message);
+      }
+    }
+    await fs.rmdir(lockPath);
+  } catch (e) { 
+    // File not found or locked by another process
+    try { await fs.rmdir(lockPath); } catch (_) {} 
+  }
 
   const cleanDirsToIgnore = (config.dirsToIgnore || []).map(d => d.replace(/\/$/, ''));
 
-  for (const filePath of changedFiles) {
-    const normalizedPath = filePath.replace(/\\/g, '/');
-
-    // Skip hidden paths (.idea/, .vscode/, etc.) — mirrors createSnapshot.js
-    if (isHiddenPath(normalizedPath)) continue;
-
-    // Skip binary files — mirrors createSnapshot.js
-    if (isBinaryPath(filePath)) continue;
-
-    const pathParts = normalizedPath.split('/');
-    let isIgnoredDir = false;
-    for (let i = 0; i < pathParts.length - 1; i++) {
-      if (cleanDirsToIgnore.includes(pathParts[i])) {
-        isIgnoredDir = true;
-        break;
-      }
-    }
-    if (isIgnoredDir) continue;
-
-    const fileExt = path.extname(filePath);
-    // Use matchesPattern (glob support) instead of exact includes() — mirrors createSnapshot.js
-    if (config.filesToIgnore && matchesPattern(normalizedPath, config.filesToIgnore)) continue;
-    if (fileExt && config.extensionsToIgnore?.includes(fileExt)) continue;
-    if (gitignore.ignores(normalizedPath)) continue;
-
-    try {
-      const fullPath = path.join(repoPath, filePath);
-      const content = await readFileWithSizeCheck(fullPath, parseSize(config.maxFileSize));
-      contentOutput += `--- File: /${normalizedPath} ---\n\n${content}\n\n`;
-      fileList.push(`- ${normalizedPath}`);
-      includedCount++;
-    } catch (e) { /* Skip */ }
-  }
+  for (const filePath of changedFiles) {
+    const normalizedPath = filePath.replace(/\\/g, '/');
+
+    // Skip hidden paths (.idea/, .vscode/, etc.) — mirrors createSnapshot.js
+    if (isHiddenPath(normalizedPath)) continue;
+
+    // Skip binary files — mirrors createSnapshot.js
+    if (isBinaryPath(filePath)) continue;
+
+    const pathParts = normalizedPath.split('/');
+    let isIgnoredDir = false;
+    for (let i = 0; i < pathParts.length - 1; i++) {
+      if (cleanDirsToIgnore.includes(pathParts[i])) {
+        isIgnoredDir = true;
+        break;
+      }
+    }
+    if (isIgnoredDir) continue;
+
+    const fileExt = path.extname(filePath);
+    // Use matchesPattern (glob support) instead of exact includes() — mirrors createSnapshot.js
+    if (config.filesToIgnore && matchesPattern(normalizedPath, config.filesToIgnore)) continue;
+    if (fileExt && config.extensionsToIgnore?.includes(fileExt)) continue;
+    if (gitignore.ignores(normalizedPath)) continue;
+
+    try {
+      const fullPath = path.join(repoPath, filePath);
+
+      // Explicitly check if file was deleted
+      try {
+        await fs.access(fullPath);
+      } catch (accessErr) {
+        contentOutput += `--- File: /${normalizedPath} ---\n\n[FILE DELETED]\n\n`;
+        fileList.push(`- ${normalizedPath} (Deleted)`);
+        includedCount++;
+        continue;
+      }
+
+      const content = await readFileWithSizeCheck(fullPath, parseSize(config.maxFileSize));
+      contentOutput += `--- File: /${normalizedPath} ---\n\n${content}\n\n`;
+      fileList.push(`- ${normalizedPath} (Modified/Added)`);
+      includedCount++;
+    } catch (e) { /* Skip */ }
+  }
 
   // Load Template
   const templatePath = path.join(__dirname, '../../templates/update-prompt.template.md');
@@ -122,17 +166,22 @@ export async function updateSnapshot(repoPath, options) {
     }
 
     // Auto-commit any uncommitted changes so they appear in the diff
-    const didCommit = await autoCommit(repoPath);
-    if (didCommit) {
-      spinner.info('Auto-committed uncommitted changes.');
-      spinner.start('Generating update snapshot...');
+    let didCommit = false;
+    if (!options.fail) {
+      didCommit = await autoCommit(repoPath);
+      if (didCommit) {
+        spinner.info('Auto-committed uncommitted changes.');
+      }
+    } else {
+      spinner.info('Fail flag passed: skipping auto-commit.');
     }
+    spinner.start('Generating update snapshot...');
 
-    const changedFiles = await getChangedFiles(repoPath, anchor);
-    if (changedFiles.length === 0) {
-      spinner.succeed('No changes detected since last full snapshot.');
-      return;
-    }
+    const changedFiles = await getChangedFiles(repoPath, anchor, options.fail);
+    if (changedFiles.length === 0) {
+      spinner.succeed('No changes detected since last full snapshot.');
+      return;
+    }
 
     const setupConfig = await loadSetupConfig();
     let config = { ...setupConfig.fileFiltering, ...setupConfig.performance, ...options };
@@ -216,7 +265,7 @@ export async function updateSnapshot(repoPath, options) {
 }
 
 // New Silent/JSON command for Agents
-export async function updateSnapshotJson(repoPath) {
+export async function updateSnapshotJson(repoPath, options = {}) {
   try {
     const anchor = await getGitAnchor(repoPath);
     if (!anchor) {
@@ -225,9 +274,11 @@ export async function updateSnapshotJson(repoPath) {
     }
 
     // Auto-commit any uncommitted changes
-    await autoCommit(repoPath);
+    if (!options.fail) {
+      await autoCommit(repoPath);
+    }
 
-    const changedFiles = await getChangedFiles(repoPath, anchor);
+    const changedFiles = await getChangedFiles(repoPath, anchor, !!options.fail);
     if (changedFiles.length === 0) {
       console.log(JSON.stringify({ status: "no_changes", message: "No changes detected" }));
       return;
@@ -294,15 +345,16 @@ export async function updateSnapshotJson(repoPath) {
     }
     // --------------------------------------------
 
-    console.log(JSON.stringify({
-      status: "success",
-      snapshot_file: `.eck/snapshots/${outputFilename}`,
-      files_count: includedCount,
-      timestamp: timestamp
-    }));
-
-    // Auto-push telemetry (fire and forget so it doesn't break JSON output)
-    pushTelemetry(repoPath, true).catch(() => {});
+    console.log(JSON.stringify({
+      status: "success",
+      snapshot_file: `.eck/snapshots/${outputFilename}`,
+      files_count: includedCount,
+      timestamp: timestamp
+    }));
+
+    // Auto-push telemetry and sync weights (fire and forget so it doesn't break JSON output)
+    pushTelemetry(repoPath, true).catch(() => {});
+    syncTokenWeights(true).catch(() => {});
 
   } catch (error) {
     console.log(JSON.stringify({ status: "error", message: error.message }));

package/src/core/depthConfig.js

@@ -0,0 +1,54 @@
+/**
+ * Shared depth configuration for link and scout commands.
+ * Scale: 0-9
+ *
+ * @param {number} depth - Depth level (0-9)
+ * @returns {object} Configuration object with mode settings
+ */
+export function getDepthConfig(depth) {
+  const d = Math.max(0, Math.min(9, parseInt(depth, 10) || 0));
+
+  if (d === 0) {
+    return { mode: 'tree', skipContent: true };
+  }
+
+  if (d >= 1 && d <= 4) {
+    const linesMap = { 1: 10, 2: 30, 3: 60, 4: 100 };
+    return { mode: 'truncated', maxLinesPerFile: linesMap[d], skeleton: false };
+  }
+
+  if (d === 5) {
+    return { mode: 'skeleton', skeleton: true, preserveDocs: false, maxLinesPerFile: 0 };
+  }
+
+  if (d === 6) {
+    return { mode: 'skeleton+docs', skeleton: true, preserveDocs: true, maxLinesPerFile: 0 };
+  }
+
+  if (d === 7) {
+    return { mode: 'full', skeleton: false, maxLinesPerFile: 500 };
+  }
+
+  if (d === 8) {
+    return { mode: 'full', skeleton: false, maxLinesPerFile: 1000 };
+  }
+
+  // d === 9
+  return { mode: 'full', skeleton: false, maxLinesPerFile: 0 };
+}
+
+/**
+ * Human-readable depth scale table for documentation/headers.
+ */
+export const DEPTH_SCALE = [
+  { depth: 0, mode: 'Tree only',        description: 'Directory structure, no file contents' },
+  { depth: 1, mode: 'Truncated 10',     description: '10 lines per file (imports/header)' },
+  { depth: 2, mode: 'Truncated 30',     description: '30 lines per file' },
+  { depth: 3, mode: 'Truncated 60',     description: '60 lines per file' },
+  { depth: 4, mode: 'Truncated 100',    description: '100 lines per file' },
+  { depth: 5, mode: 'Skeleton',         description: 'Function/class signatures only' },
+  { depth: 6, mode: 'Skeleton + docs',  description: 'Signatures + docstrings/comments' },
+  { depth: 7, mode: 'Full (compact)',   description: 'Full content, truncated at 500 lines' },
+  { depth: 8, mode: 'Full (standard)',  description: 'Full content, truncated at 1000 lines' },
+  { depth: 9, mode: 'Full (unlimited)', description: 'Everything, no limits' },
+];

package/src/core/skeletonizer.js

@@ -64,14 +64,17 @@ const languages = {
  * Strips implementation details from code.
  * @param {string} content - Full file content
  * @param {string} filePath - File path to determine language
+ * @param {object} [options] - Options
+ * @param {boolean} [options.preserveDocs=true] - Keep JSDoc/docstrings (depth 6) or strip them (depth 5)
  * @returns {Promise<string>} - Skeletonized code
  */
-export async function skeletonize(content, filePath) {
+export async function skeletonize(content, filePath, options = {}) {
     if (!content) return content;
+    const preserveDocs = options.preserveDocs !== undefined ? options.preserveDocs : true;
 
     // 1. JS/TS Strategy (Babel is better for JS ecosystem)
     if (/\.(js|jsx|ts|tsx|mjs|cjs)$/.test(filePath)) {
-        return skeletonizeJs(content);
+        return skeletonizeJs(content, preserveDocs);
     }
 
     // 2. Tree-sitter Strategy (Python, Java, Kotlin, C, Rust, Go)
@@ -83,7 +86,7 @@ export async function skeletonize(content, filePath) {
 
         // Only attempt tree-sitter if both the parser and the specific language module are ready
         if (available && Parser && langModule) {
-            return skeletonizeTreeSitter(content, langModule, ext);
+            return skeletonizeTreeSitter(content, langModule, ext, preserveDocs);
         }
         return content; // Fallback: return original content if tree-sitter unavailable
     }
@@ -92,7 +95,7 @@ export async function skeletonize(content, filePath) {
     return content;
 }
 
-function skeletonizeJs(content) {
+function skeletonizeJs(content, preserveDocs = true) {
     try {
         const ast = parse(content, {
             sourceType: 'module',
@@ -100,27 +103,27 @@ function skeletonizeJs(content) {
             errorRecovery: true
         });
 
-        traverse(ast, {
-            Function(path) {
-                if (path.node.body && path.node.body.type === 'BlockStatement') {
-                    // Preserve leading comments (JSDoc) before emptying body
+        const emptyBody = (path) => {
+            if (path.node.body && path.node.body.type === 'BlockStatement') {
+                if (preserveDocs) {
+                    // Keep leading comments (JSDoc) before emptying body
                     const leadingComments = path.node.leadingComments || [];
                     path.node.body.body = [];
                     path.node.body.innerComments = leadingComments.length > 0
                         ? leadingComments
                         : [{ type: 'CommentBlock', value: ' ... ' }];
-                }
-            },
-            ClassMethod(path) {
-                if (path.node.body && path.node.body.type === 'BlockStatement') {
-                    // Preserve leading comments (JSDoc) before emptying body
-                    const leadingComments = path.node.leadingComments || [];
+                } else {
+                    // Strip everything including docs
+                    path.node.leadingComments = null;
                     path.node.body.body = [];
-                    path.node.body.innerComments = leadingComments.length > 0
-                        ? leadingComments
-                        : [{ type: 'CommentBlock', value: ' ... ' }];
+                    path.node.body.innerComments = [{ type: 'CommentBlock', value: ' ... ' }];
                 }
             }
+        };
+
+        traverse(ast, {
+            Function: emptyBody,
+            ClassMethod: emptyBody
         });
 
         const output = generate(ast, {}, content);
@@ -130,7 +133,7 @@ function skeletonizeJs(content) {
     }
 }
 
-function skeletonizeTreeSitter(content, language, ext) {
+function skeletonizeTreeSitter(content, language, ext, preserveDocs = true) {
     try {
         const parser = new Parser();
         parser.setLanguage(language);
@@ -172,6 +175,19 @@ function skeletonizeTreeSitter(content, language, ext) {
                 }
 
                 if (bodyNode) {
+                    // For Python with preserveDocs: keep docstring as first statement
+                    if (preserveDocs && ext === '.py' && bodyNode.childCount > 0) {
+                        const docstring = extractPythonDocstring(bodyNode);
+                        if (docstring) {
+                            replacements.push({
+                                start: bodyNode.startIndex,
+                                end: bodyNode.endIndex,
+                                text: docstring + '\n    ...'
+                            });
+                            return;
+                        }
+                    }
+
                     replacements.push({
                         start: bodyNode.startIndex,
                         end: bodyNode.endIndex,
@@ -181,6 +197,16 @@ function skeletonizeTreeSitter(content, language, ext) {
                 }
             }
 
+            // If not preserveDocs, also strip standalone comment blocks
+            if (!preserveDocs && type === 'comment') {
+                replacements.push({
+                    start: node.startIndex,
+                    end: node.endIndex,
+                    text: ''
+                });
+                return;
+            }
+
             for (let i = 0; i < node.childCount; i++) {
                 visit(node.child(i));
             }
@@ -194,8 +220,35 @@ function skeletonizeTreeSitter(content, language, ext) {
             currentContent = currentContent.substring(0, rep.start) + rep.text + currentContent.substring(rep.end);
         }
 
+        // Clean up excessive blank lines from stripped comments
+        if (!preserveDocs) {
+            currentContent = currentContent.replace(/\n{3,}/g, '\n\n');
+        }
+
         return currentContent;
     } catch (e) {
         return content + `\n// [Skeleton error: ${e.message}]`;
     }
 }
+
+/**
+ * Extract Python docstring from the first statement of a function body block.
+ */
+function extractPythonDocstring(bodyNode) {
+    for (let i = 0; i < bodyNode.childCount; i++) {
+        const child = bodyNode.child(i);
+        // Python docstrings are expression_statement containing a string
+        if (child.type === 'expression_statement') {
+            const expr = child.child(0);
+            if (expr && expr.type === 'string') {
+                // Return the indented docstring text
+                return '\n    ' + expr.text;
+            }
+        }
+        // Skip newline/indent tokens, but stop at first real statement
+        if (child.type !== 'newline' && child.type !== 'indent' && child.type !== 'NEWLINE' && child.type !== 'INDENT') {
+            if (child.type !== 'expression_statement') break;
+        }
+    }
+    return null;
+}

package/src/templates/architect-prompt.template.md

@@ -19,6 +19,7 @@ You MUST wrap your ENTIRE response (Analysis + Changes + Metadata) in a single `
 ### Command Format (Wrapped)
 
 ````text
+<eck_task id="{{repoName}}:short-task-description">
 # Analysis
 
 [Explain your reasoning: what you're doing and why.
@@ -48,6 +49,7 @@ async function example() {
   }
 }
 ```
+</eck_task id="{{repoName}}:short-task-description">
 ````
 
 ### File Actions Reference
@@ -62,6 +64,7 @@ async function example() {
 ### Complete Example
 
 ````text
+<eck_task id="{{repoName}}:add-user-validation">
 # Analysis
 
 The authentication module needs a null check to prevent crashes when
@@ -111,6 +114,7 @@ export function validateUser(user) {
   }
 }
 ```
+</eck_task id="{{repoName}}:add-user-validation">
 ````
 
 ### Why Eck-Protocol v2?
@@ -133,6 +137,36 @@ To understand the project state, you can command the `eck-snapshot` tool directl
 - `eck-snapshot query "<question>"`: Search the codebase
 - `eck-snapshot detect`: Analyze the project structure
 - `eck-snapshot restore <snapshot_file> --include ...`: View specific files
+- `eck-snapshot link <depth>`: Run inside a related repository to generate a read-only companion snapshot.
+
+## SCOUT & FETCH: Cross-Repository Intelligence
+
+When working with multiple repositories, use `scout` and `fetch` to gather context:
+
+**CRITICAL:** Both `scout` and `fetch` operate on the **current working directory only**. They scan files relative to `cwd` — absolute paths will NOT work.
+
+**Single-repo fetch:**
+```bash
+cd /path/to/project-a
+eck-snapshot fetch "**/SyncManager.kt" "**/RelayClient.kt"
+```
+
+**Multi-repo fetch (MUST be separate commands):**
+```bash
+# Fetch from first project
+cd /path/to/project-a
+eck-snapshot fetch "**/SyncManager.kt"
+
+# Fetch from second project
+cd /path/to/project-b
+eck-snapshot fetch "**/AppDatabase.kt"
+```
+
+**Rules:**
+- Always use **relative glob patterns**, never absolute paths
+- Always specify which directory to `cd` into before each command
+- Use `**/<filename>` to find files regardless of nesting depth
+- One `fetch` command = one repo. For multiple repos, issue multiple commands.
 
 ## CAPABILITIES & DELEGATION PROTOCOL