create-snowline-agents 1.0.0

package/install.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+
+echo "Installing Snowline Agent Ecosystem (Project-Level)..."
+
+PROJECT_ROOT=$(pwd)
+AGENTS_DIR="$PROJECT_ROOT/.agents"
+SKILLS_DIR="$AGENTS_DIR/skills"
+KNOWLEDGE_DIR="$AGENTS_DIR/knowledge"
+REPO_URL="https://github.com/UsmanAzizz/snowline-agent-tools.git"
+IS_NEW_INSTALL=false
+
+# Ensure .agents and .agents/knowledge exist
+mkdir -p "$AGENTS_DIR"
+mkdir -p "$KNOWLEDGE_DIR"
+
+# Scaffold skills
+if [ -d "$SKILLS_DIR" ]; then
+    echo "Found existing skills directory at $SKILLS_DIR"
+    if [ -d "$SKILLS_DIR/.git" ]; then
+        echo "Pulling latest updates..."
+        (cd "$SKILLS_DIR" && git pull origin main) || echo "Failed to update repository."
+    else
+        echo "Existing skills directory is not a git repository. Skipping git pull."
+    fi
+else
+    IS_NEW_INSTALL=true
+    echo "Downloading Snowline Agent skills..."
+    if ! git clone "$REPO_URL" "$SKILLS_DIR"; then
+        echo "Failed to clone repository. Make sure git is installed."
+        exit 1
+    fi
+fi
+
+# Copy AGENTS_TEMPLATE.md to AGENTS.md
+TEMPLATE_PATH="$SKILLS_DIR/AGENTS_TEMPLATE.md"
+LOCAL_AGENTS_PATH="$AGENTS_DIR/AGENTS.md"
+
+if [ -f "$TEMPLATE_PATH" ]; then
+    if [ ! -f "$LOCAL_AGENTS_PATH" ]; then
+        echo "Creating Project AGENTS.md..."
+        cp "$TEMPLATE_PATH" "$LOCAL_AGENTS_PATH"
+        echo "Project AGENTS.md created successfully."
+    else
+        echo "Project AGENTS.md already exists. Skipping overwrite."
+    fi
+fi
+
+# Scaffold PLAN.md
+PLAN_PATH="$PROJECT_ROOT/PLAN.md"
+if [ ! -f "$PLAN_PATH" ]; then
+    echo "Creating PLAN.md..."
+    echo -e "# Project Plan / Task Tracker\n\n- [ ] Initial task" > "$PLAN_PATH"
+fi
+
+if [ "$IS_NEW_INSTALL" = true ]; then
+    echo -e "\nInstallation Complete!"
+    echo "This project is now powered by the Snowline Agent Ecosystem."
+fi

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "create-snowline-agents",
+  "version": "1.0.0",
+  "description": "One-Liner installer for the Snowline Agent AI Agents ecosystem (Global Rules & Python Skills)",
+  "main": "index.js",
+  "bin": {
+    "create-snowline-agents": "bin/install.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UsmanAzizz/snowline-agent-tools.git"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "gemini",
+    "tools",
+    "scaffolding",
+    "Snowline Agent"
+  ],
+  "author": "UsmanAzizz",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/UsmanAzizz/snowline-agent-tools/issues"
+  },
+  "homepage": "https://github.com/UsmanAzizz/snowline-agent-tools#readme",
+  "dependencies": {}
+}

package/plan_tracker/PLAN_TEMPLATE.md

@@ -0,0 +1,20 @@
+# Task: [Nama Task Singkat]
+Status: [not-started | in-progress | menunggu-konfirmasi | selesai]
+Skill/tool dipakai: [Sebutkan alat yang dominan dipakai, misal: smart_replace, clean_sweeper, atau view_file]
+
+## Konteks
+[Satu atau dua kalimat tentang alasan task ini dikerjakan dan apa tujuannya]
+
+## Log Langkah
+- [Waktu] [Deskripsi singkat aksi yang dilakukan] -> [Status/Hasil]
+- [Waktu] [Deskripsi singkat aksi yang dilakukan] -> [Status/Hasil]
+
+## Keputusan & Asumsi
+- [Catat jika ada keputusan desain, trade-off, atau asumsi yang diambil saat coding]
+
+## Menunggu Konfirmasi Saya
+[BAGIAN KRITIKAL: Jika butuh persetujuan user (misal sebelum hapus file atau sebelum eksekusi replace masal), tulis pertanyaannya di sini, DILARANG MELANJUTKAN sebelum dijawab]
+- [Tulis pertanyaan/permintaan konfirmasi di sini...]
+
+## Anomali / Peringatan
+- [Catat jika ada pesan error, behavior aneh, atau sesuatu yang butuh perhatian nanti]

package/project_guardian/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: Project Guardian (Security & Health Auditor)
+description: Use this skill when the user asks you to audit the project for security leaks, secret credentials, vulnerable dependencies, or environment file (.gitignore) issues.
+---
+
+## Instructions for AI Agent
+
+When the user asks you to "audit project", "cek keamanan", or "jalankan project guardian", use this tool to scan the repository.
+
+**Command to run:**
+```powershell
+python .agents/skills/project_guardian/guardian.py
+```
+*(Make sure your current working directory `Cwd` is set to the root of the project).*
+
+**Expected Output:**
+The script will output a report directly to standard output. It will highlight specific modules:
+1. **Secret Scanner**: Identifies hardcoded API keys and passwords.
+2. **Env & Gitignore Verifier**: Ensures `.env` files are not exposed.
+3. **Physical Import Checker**: Checks if relative imports exist.
+4. **Dependencies**: Reports unused packages and high/critical npm audit vulnerabilities.
+
+### 🛑 CRITICAL BEHAVIORAL RULE
+1. Present the findings clearly to the user.
+2. Group the findings into **[FAIL]** (Must fix immediately, like exposed `.env`) and **[WARN]** (Should be reviewed).
+3. Do NOT automatically fix or modify files. Ask the user which items they want you to fix first.

package/project_guardian/guardian.py

@@ -0,0 +1,206 @@
+import os
+import re
+import sys
+import json
+import subprocess
+import argparse
+
+if sys.stdout.encoding != 'utf-8':
+    sys.stdout.reconfigure(encoding='utf-8')
+
+exclude_dirs = {'.git', 'node_modules', 'vendor', 'dist', 'build', 'quarantine', '.backup_replace', '.agents', '.history'}
+js_py_exts = {'.js', '.jsx', '.ts', '.tsx', '.py'}
+MAX_FILE_SIZE = 500 * 1024
+
+target_dir = os.getcwd()
+
+total_fails = 0
+total_warns = 0
+
+def print_fail(msg, summary_mode):
+    global total_fails
+    total_fails += 1
+    if not summary_mode:
+        print(f"[FAIL] {msg}")
+
+def print_warn(msg, summary_mode):
+    global total_warns
+    total_warns += 1
+    if not summary_mode:
+        print(f"[WARN] {msg}")
+
+def print_info(msg, summary_mode):
+    if not summary_mode:
+        print(f"[INFO] {msg}")
+
+def scan_secrets(summary_mode):
+    if not summary_mode: print("\n--- MODULE 1: SECRET SCANNER ---")
+    secret_patterns = [
+        r'(?i)(password\s*[:=]\s*[\'"].+[\'"])',
+        r'(?i)(api_key\s*[:=]\s*[\'"].+[\'"])',
+        r'(?i)(secret\s*[:=]\s*[\'"].+[\'"])',
+        r'(mongodb\+srv://.+)',
+        r'(mysql://.+)',
+        r'(Bearer\s+[A-Za-z0-9\-\._~+/]+=*)'
+    ]
+    compiled_patterns = [re.compile(p) for p in secret_patterns]
+    
+    for root, dirs, files in os.walk(target_dir):
+        dirs[:] = [d for d in dirs if d not in exclude_dirs]
+        for file in files:
+            if file.startswith('.env'): continue
+            filepath = os.path.join(root, file)
+            if os.path.getsize(filepath) > MAX_FILE_SIZE: continue
+            
+            try:
+                with open(filepath, 'r', encoding='utf-8') as f:
+                    for line_num, line in enumerate(f, 1):
+                        for pattern in compiled_patterns:
+                            if pattern.search(line):
+                                rel_path = os.path.relpath(filepath, target_dir)
+                                print_fail(f"Potential credential leak in {rel_path} line {line_num}", summary_mode)
+            except UnicodeDecodeError:
+                pass
+
+def check_env_gitignore(summary_mode):
+    if not summary_mode: print("\n--- MODULE 2: ENV & GITIGNORE VERIFIER ---")
+    gitignore_path = os.path.join(target_dir, '.gitignore')
+    ignored_lines = set()
+    if os.path.exists(gitignore_path):
+        with open(gitignore_path, 'r', encoding='utf-8') as f:
+            ignored_lines = set(line.strip() for line in f if line.strip() and not line.startswith('#'))
+    
+    env_files = [f for f in os.listdir(target_dir) if f.startswith('.env') and os.path.isfile(os.path.join(target_dir, f))]
+    for env_file in env_files:
+        if env_file == '.env.example': continue
+        if env_file not in ignored_lines and f"/{env_file}" not in ignored_lines and "*.env" not in ignored_lines and ".env*" not in ignored_lines:
+            print_fail(f"File {env_file} is missing from .gitignore!", summary_mode)
+    
+    env_example_path = os.path.join(target_dir, '.env.example')
+    example_keys = set()
+    if os.path.exists(env_example_path):
+        with open(env_example_path, 'r', encoding='utf-8') as f:
+            for line in f:
+                if '=' in line and not line.startswith('#'):
+                    key = line.split('=')[0].strip()
+                    example_keys.add(key)
+                    
+    used_keys = set()
+    process_env_pattern = re.compile(r'process\.env\.([A-Za-z0-9_]+)')
+    for root, dirs, files in os.walk(target_dir):
+        dirs[:] = [d for d in dirs if d not in exclude_dirs]
+        for file in files:
+            if not any(file.endswith(ext) for ext in js_py_exts): continue
+            filepath = os.path.join(root, file)
+            if os.path.getsize(filepath) > MAX_FILE_SIZE: continue
+            try:
+                with open(filepath, 'r', encoding='utf-8') as f:
+                    for line in f:
+                        for m in process_env_pattern.findall(line):
+                            used_keys.add(m)
+            except: pass
+            
+    for key in used_keys:
+        if key not in example_keys and key != 'NODE_ENV':
+            print_warn(f"process.env.{key} is used, but missing from .env.example", summary_mode)
+
+def check_physical_imports(summary_mode):
+    if not summary_mode: print("\n--- MODULE 3: PHYSICAL IMPORT CHECKER ---")
+    import_pattern = re.compile(r'(?:import\s+.*?from\s+|require\()[\'"]([^\'"]+)[\'"]')
+    for root, dirs, files in os.walk(target_dir):
+        dirs[:] = [d for d in dirs if d not in exclude_dirs]
+        for file in files:
+            if not any(file.endswith(ext) for ext in js_py_exts): continue
+            filepath = os.path.join(root, file)
+            if os.path.getsize(filepath) > MAX_FILE_SIZE: continue
+            try:
+                with open(filepath, 'r', encoding='utf-8') as f:
+                    for line_num, line in enumerate(f, 1):
+                        for match in import_pattern.findall(line):
+                            import_path = match
+                            if import_path.startswith('.'):
+                                dir_path = os.path.dirname(filepath)
+                                target_p = os.path.normpath(os.path.join(dir_path, import_path))
+                                found = False
+                                for suffix in ['', '.js', '.jsx', '.ts', '.tsx', '/index.js', '/index.jsx']:
+                                    if os.path.exists(target_p + suffix):
+                                        found = True
+                                        break
+                                if not found:
+                                    rel_source = os.path.relpath(filepath, target_dir)
+                                    print_warn(f"Relative import '{import_path}' at {rel_source}:{line_num} does not exist physically!", summary_mode)
+            except: pass
+
+def check_dependencies(summary_mode):
+    if not summary_mode: print("\n--- MODULE 4: DEPENDENCIES & UNUSED PACKAGES ---")
+    package_json_path = os.path.join(target_dir, 'package.json')
+    if not os.path.exists(package_json_path):
+        return
+        
+    try:
+        with open(package_json_path, 'r', encoding='utf-8') as f:
+            pkg = json.load(f)
+    except: return
+        
+    deps = list(pkg.get('dependencies', {}).keys())
+    used_deps = set()
+    import_pattern = re.compile(r'(?:import\s+.*?from\s+|require\()[\'"]([^\'"]+)[\'"]')
+    
+    for root, dirs, files in os.walk(target_dir):
+        dirs[:] = [d for d in dirs if d not in exclude_dirs]
+        for file in files:
+            if not any(file.endswith(ext) for ext in js_py_exts): continue
+            filepath = os.path.join(root, file)
+            if os.path.getsize(filepath) > MAX_FILE_SIZE: continue
+            try:
+                with open(filepath, 'r', encoding='utf-8') as f:
+                    for line in f:
+                        for match in import_pattern.findall(line):
+                            pkg_name = match.split('/')[0]
+                            if pkg_name.startswith('@'):
+                                parts = match.split('/')
+                                if len(parts) > 1:
+                                    pkg_name = f"{parts[0]}/{parts[1]}"
+                            used_deps.add(pkg_name)
+            except: pass
+            
+    for dep in deps:
+        if dep not in used_deps and not dep.startswith('@vite') and not dep.startswith('@babel') and not dep.startswith('react'):
+            print_warn(f"Package '{dep}' is installed but appears unused.", summary_mode)
+
+    if not summary_mode: print("\nRunning npm audit (this may take a while)...")
+    try:
+        result = subprocess.run('npm audit --json', shell=True, capture_output=True, text=True, check=False, timeout=15)
+        try:
+            audit_data = json.loads(result.stdout)
+            vulns = audit_data.get('metadata', {}).get('vulnerabilities', {})
+            high = vulns.get('high', 0)
+            critical = vulns.get('critical', 0)
+            if high > 0 or critical > 0:
+                print_fail(f"npm audit detected {high} HIGH and {critical} CRITICAL vulnerabilities!", summary_mode)
+        except: pass
+    except: pass
+
+def main():
+    parser = argparse.ArgumentParser(description="Project Guardian")
+    parser.add_argument("--summary", action="store_true", help="Only show final score")
+    args = parser.parse_args()
+
+    if not args.summary:
+        print("🛡️ PROJECT GUARDIAN AUDITOR 🛡️")
+        
+    scan_secrets(args.summary)
+    check_env_gitignore(args.summary)
+    check_physical_imports(args.summary)
+    check_dependencies(args.summary)
+    
+    if args.summary:
+        print(f"🛡️ RINGKASAN GUARDIAN: 🔴 {total_fails} FAIL | 🟡 {total_warns} WARN | 🟢 Sektor lainnya Aman.")
+    else:
+        print("\n" + "=" * 60)
+        print(f"🛡️ RINGKASAN: 🔴 {total_fails} FAIL | 🟡 {total_warns} WARN | 🟢 Sektor lainnya Aman.")
+        print("\n💡 PROMPT UNTUK AI (Copy-Paste ini):")
+        print('"Tolong perbaiki semua temuan [FAIL] di atas (khususnya .gitignore dan env). Untuk [WARN], abaikan jika itu adalah dummy data atau file test."')
+
+if __name__ == '__main__':
+    main()

package/run_all.py

@@ -0,0 +1,115 @@
+import os
+import sys
+import subprocess
+
+if sys.stdout.encoding != 'utf-8':
+    sys.stdout.reconfigure(encoding='utf-8')
+
+TOOLS = [
+    {
+        "name": "Project Guardian (Security & Health Auditor)",
+        "script": "project_guardian/guardian.py",
+        "args": ["--summary"]
+    },
+    {
+        "name": "Clean Sweeper (Leftover & Tech Debt Scanner)",
+        "script": "clean_sweeper/sweeper.py",
+        "args": [os.getcwd()]
+    },
+    {
+        "name": "Context Mapper (Knowledge Catalog Builder)",
+        "script": "context_mapper/context_mapper.py",
+        "args": []
+    },
+    {
+        "name": "Smart Replace (Pure Python RegEx Replacer)",
+        "script": "smart_replace/replace_text.py",
+        "args": [os.getcwd(), "<search_string>", "<replace_string>"]
+    },
+    {
+        "name": "Smart Search (5-Lines Context Code Finder)",
+        "script": "smart_search/code_finder.py",
+        "args": [os.getcwd(), "<keyword>"]
+    },
+    {
+        "name": "Selective Reader (TOC Extractor)",
+        "script": "selective_reader/reader.py",
+        "args": ["<absolute_file_path>"]
+    },
+    {
+        "name": "Deep Analyzer (Project Profiler)",
+        "script": "deep_analyzer/analyzer.py",
+        "args": [os.getcwd()]
+    },
+    {
+        "name": "Crash Decoder (Error Trace Analyzer)",
+        "script": "crash_decoder/decoder.py",
+        "args": ["<path_to_error_log.txt>"]
+    },
+    {
+        "name": "Auto-Scaffolder (Pattern Generator)",
+        "script": "auto_scaffolder/scaffolder.py",
+        "args": ["<react_or_api>", "<ComponentName>"]
+    },
+    {
+        "name": "Smart Import Fixer",
+        "script": "import_fixer/fixer.py",
+        "args": ["<source_file>", "<broken_import_string>"]
+    }
+]
+
+def print_menu():
+    print("\n" + "=" * 60)
+    print("❄️ SNOWLINE AGENT TOOLS - INTERACTIVE DASHBOARD ❄️")
+    print("=" * 60)
+    print("Select a tool to run (Powered by 4-Pillars Vision):")
+    for i, tool in enumerate(TOOLS, 1):
+        print(f"[{i}] {tool['name']}")
+    print("[0] Exit")
+    print("=" * 60)
+
+def main():
+    while True:
+        print_menu()
+        try:
+            choice = input("\nEnter your choice (0-10): ").strip()
+        except KeyboardInterrupt:
+            break
+            
+        if choice == '0':
+            print("Exiting dashboard.")
+            break
+            
+        if not choice.isdigit() or not (1 <= int(choice) <= len(TOOLS)):
+            print("[FAIL] Invalid choice.")
+            continue
+            
+        idx = int(choice) - 1
+        tool = TOOLS[idx]
+        
+        script_path = os.path.join(os.path.dirname(__file__), tool["script"])
+        if not os.path.exists(script_path):
+            print(f"[FAIL] Script not found at {script_path}")
+            continue
+            
+        args = []
+        for arg in tool["args"]:
+            if arg.startswith("<") and arg.endswith(">"):
+                val = input(f"Enter {arg}: ").strip()
+                args.append(val)
+            else:
+                args.append(arg)
+                
+        cmd = [sys.executable, script_path] + args
+        print(f"\nRunning: {' '.join(cmd)}")
+        print("-" * 60)
+        
+        try:
+            subprocess.run(cmd, check=False)
+        except Exception as e:
+            print(f"[FAIL] Error during execution: {e}")
+            
+        input("\nPress Enter to return to main menu...")
+
+if __name__ == "__main__":
+    main()

package/selective_reader/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: Selective File Reader (TOC Generator)
+description: Use this skill when you need to inspect a large file but don't want to waste tokens reading the entire file. This script parses the file using regex heuristics and returns a Table of Contents with exact line numbers for all functions, components, and classes.
+---
+
+## Instructions for AI Agent
+
+Reading massive files (800+ lines) blindly wastes context limits and degrades performance. 
+
+**When to use this skill:**
+Before reading any JS/React/Py file that you suspect is large, or when the user asks you to "inspect" or "modify" a specific function within a file, use this skill to generate a "Table of Contents" (TOC) of that file first.
+
+**Command to run:**
+```powershell
+python .agents/skills/selective_reader/reader.py "<absolute_path_to_file>"
+```
+
+**Expected Behavior & Next Steps:**
+1. The script will output a Markdown list of all classes, functions, and top-level variables along with their precise start lines.
+2. Review the TOC to locate the exact function or component you need.
+3. Once you know the line numbers, use your native `view_file` tool and supply `StartLine` and `EndLine` parameters to read ONLY that specific block of code!
+
+By doing this, you act as a "Selective Reader" and dramatically optimize your memory usage.
+
+## ⚠️ Known Limitations & Future Enhancements
+- **Monolithic JSX Components**: The heuristic regex currently only detects function and class declarations. If a file contains a single massive React component returning a huge block of JSX (e.g., hundreds of lines of <table> or <form>), the TOC will only show the top-level function. You may still need to manually paginate through the file to find specific HTML structures. 
+- *Future Enhancement Idea:* Add regex rules to detect major JSX landmarks (like <table, <form, or <Modal) to improve precision in UI components.

package/selective_reader/reader.py

@@ -0,0 +1,67 @@
+import os
+import sys
+import re
+
+if sys.stdout.encoding != 'utf-8':
+    sys.stdout.reconfigure(encoding='utf-8')
+
+MAX_FILE_SIZE = 500 * 1024 # 500 KB
+
+def parse_js(content):
+    toc = []
+    class_pattern = re.compile(r'^\s*(?:export\s+)?(?:default\s+)?class\s+([A-Za-z0-9_]+)', re.MULTILINE)
+    func_pattern = re.compile(r'^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+([A-Za-z0-9_]+)', re.MULTILINE)
+    arrow_pattern = re.compile(r'^\s*(?:export\s+)?const\s+([A-Za-z0-9_]+)\s*=\s*(?:async\s+)?(?:\([^)]*\)|[A-Za-z0-9_]+)\s*=>', re.MULTILINE)
+    
+    for match in class_pattern.finditer(content):
+        line = content.count('\n', 0, match.start()) + 1
+        toc.append((line, f"Class: {match.group(1)}"))
+        
+    for match in func_pattern.finditer(content):
+        line = content.count('\n', 0, match.start()) + 1
+        toc.append((line, f"Function: {match.group(1)}"))
+        
+    for match in arrow_pattern.finditer(content):
+        line = content.count('\n', 0, match.start()) + 1
+        toc.append((line, f"Arrow Function: {match.group(1)}"))
+        
+    toc.sort(key=lambda x: x[0])
+    return toc
+
+def main():
+    if len(sys.argv) < 2:
+        print("[FAIL] Usage: python reader.py <absolute_path_to_file>")
+        sys.exit(1)
+        
+    filepath = sys.argv[1]
+    if not os.path.exists(filepath):
+        print(f"[FAIL] File not found: {filepath}")
+        sys.exit(1)
+        
+    if os.path.getsize(filepath) > MAX_FILE_SIZE:
+        print(f"[FAIL] File too large (>500KB): {filepath}")
+        sys.exit(1)
+        
+    try:
+        with open(filepath, 'r', encoding='utf-8') as f:
+            content = f.read()
+    except Exception as e:
+        print(f"[FAIL] Failed to read file: {e}")
+        sys.exit(1)
+        
+    print(f"📄 TABLE OF CONTENTS: {os.path.basename(filepath)}")
+    print("-" * 50)
+    
+    toc = parse_js(content)
+    if not toc:
+        print("[INFO] No primary class or function declarations found.")
+    else:
+        for line, desc in toc:
+            print(f"Line {line:<5}: {desc}")
+            
+    print("-" * 50)
+    print("\n💡 PROMPT UNTUK AI (Copy-Paste ini):")
+    print(f'"Berdasarkan TOC di atas, tolong gunakan tool view_file untuk membaca hanya baris yang relevan dari fungsi yang bermasalah di file {os.path.basename(filepath)}."')
+
+if __name__ == '__main__':
+    main()

package/smart_replace/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: Smart Text Replacer (Pure Python)
+description: Use this skill to safely replace strings or regex patterns across multiple files in a project. It uses pure Python for fast matching and provides mandatory dry-run previews and automatic backups before applying changes.
+---
+
+## Instructions for AI Agent
+
+When you need to perform multi-file or token-intensive string replacements, use this skill instead of manually replacing content via `replace_file_content`. This is especially useful for refactoring names, updating URLs, or replacing specific terminology globally without reading the whole file into context.
+
+**When to use this skill:**
+- The user asks to rename a component, variable, or class globally.
+- You need to replace a string across multiple files but want to preview the changes first to avoid false positives.
+- The project is large and manual editing would exceed token limits.
+
+**Command to run:**
+```powershell
+python .agents/skills/smart_replace/replace_text.py "<absolute_target_directory>" "<search_string>" "<replace_string>" [options]
+```
+
+**Options:**
+- `--ext <ext>`: Comma-separated extensions to include (e.g. `js,jsx`).
+- `--regex`: Treat `<search_string>` as a regular expression.
+- `--whole-word`: Enforce word-boundary matching. (This is automatically set to `True` if `--regex` is not used).
+- `--exclude <dir>`: Additional folders to exclude (node_modules, .git, etc are excluded by default).
+- `--apply`: **CRITICAL FLAG**. Without this flag, the script runs in PREVIEW/DRY-RUN mode. 
+
+**Workflow Guardrails:**
+1. **ALWAYS** run the command *without* `--apply` first.
+2. Review the preview output in your terminal log. Check for false positives.
+3. Show the summary of the preview to the USER and ask for explicit confirmation.
+4. ONLY after the USER confirms, run the exact same command again but append `--apply` to execute the changes. The script will automatically backup original files to `.backup_replace/`.
+
+**Comparison with other skills:**
+- Use `smart_search` to understand *context* (how a function is used).
+- Use `smart_replace` to safely *mutate* code (rename, replace) based on patterns.