tokensafe 1.1.0 → 1.2.0

package/README.md

@@ -56,13 +56,34 @@ Traditional AI code interactions suffer from massive context bloat:
 3. **Stuck Loops & Bloated Diffs:** Terminal `git diff` and repetitive failed commands spiral context into overflow.
 
 ### TokenSafe Solves All Three Autonomously:
+- **Graph-Guided AST Skeletonization:** Folds inactive function bodies into signatures, keeping target functions and 1-hop dependencies full while collapsing unrelated code (`-85% to -92%`).
+- **God Nodes & Architectural Hub Detection:** Calculates Degree Centrality to identify structural project hubs and injects topology awareness into agent sessions without expensive file crawling.
 - **TOCP Prompt Distillation:** Intercepts prompts and distills intent into lean S-Expressions via **Google Gemini (2.0 Flash-Lite), OpenAI ChatGPT (gpt-4o-mini), or DeepSeek-Flash** (`-40% to -70%`). Automatically detects `GEMINI_API_KEY`, `OPENAI_API_KEY`, or `DEEPSEEK_API_KEY`.
-- **AST Skeletonization & Slicing:** Folds inactive function bodies into signatures and windows targeted symbols (`-80% to -92%`).
+- **API Surface Map Generator:** Generates high-density `tokensafe-out/API_SURFACE.md` (~1.5k tokens) for instant agent codebase onboarding.
 - **Predictive Dependency Prefetcher:** Attaches imported symbol signatures to eliminate downstream exploratory `read_file` roundtrips.
+- **Local Secret Redactor:** Sanitizes Stripe, AWS, JWT, and database credentials before network transmission.
 - **Output Guard & Loop Guard:** Blocks destructive full-file rewrites on files $\ge 40$ lines and halts command loops.
 
 ---
 
+## ⚡ TokenSafe vs. Graphify: Dynamic In-Flight Defense vs. Static Reports
+
+How TokenSafe complements or supersedes static graph tools like **Graphify** (`graphify-labs/graphify`):
+
+| Capability | Graphify | TokenSafe |
+|---|---|---|
+| **Primary Focus** | Static knowledge graph reports & MCP queries | **In-flight real-time token compression & defense** |
+| **Indexing Cost** | Expensive LLM tokens / heavy graph extraction | **0 tokens, 100% deterministic local AST (< 30ms)** |
+| **Execution Latency** | Offline / CLI-initiated build | **Sub-millisecond inline proxy & lifecycle hooks** |
+| **Active Slicing** | Static file output (`GRAPH_REPORT.md`) | **Dynamic call-graph skeletonization (85–92% saved)** |
+| **Multi-Project Workspace** | Requires manual directory targeting | **Auto-detects project roots per file on the fly** |
+| **Agent Prompt Optimization** | None | **TOCP S-Expression prompt distillation (-40% to -70%)** |
+| **Safety & Runaway Prevention** | None | **Output rewrite guard, loop detector, secret scrubbing** |
+
+> **Complements & Replaces**: If you already use Graphify for repository mapping, TokenSafe works alongside it by compressing real-time agent tool reads on the wire. Or use TokenSafe standalone for a zero-configuration, zero-cost, sub-30ms architecture engine out of the box.
+
+---
+
 ## 🤖 Universal LLM Distillation Providers
 
 TokenSafe supports any key you already have:
@@ -110,6 +131,12 @@ Verified across 5 real-world production scenarios:
 ## 🛠️ CLI Quickstart
 
 ```bash
+# Analyze repository God Nodes and dependency topology
+tokensafe graph
+
+# Generate compact tokensafe-out/API_SURFACE.md interface snapshot
+tokensafe map
+
 # View live savings dashboard in your terminal
 tokensafe stats
 

package/hooks/pre_tool_use.py

@@ -110,8 +110,29 @@ def main():
             print(json.dumps(response))
             return
 
-        # Step 3B: If a specific symbol/function is targeted in user prompt, slice to it
+        # Step 3B: If a specific symbol/function is targeted in user prompt, check graph-guided skeleton first
         overwrite_args, metrics = ToolSlicer.optimize_read_file(args, context_hint=last_user_input)
+        target_sym = metrics.get("target_symbol")
+        if target_sym and path and os.path.exists(path):
+            skel_path, orig_t, skel_t = Skeletonizer.get_skeleton_file(path, target_symbol=target_sym)
+            if skel_path and orig_t > skel_t:
+                saved = orig_t - skel_t
+                response["overwrite"] = {"Path": skel_path}
+                response["reason"] = f"Token Optimizer: Graph-guided AST view for '{target_sym}' (Saved ~{saved} tokens)"
+                tracker.record_event(
+                    session_id=conversation_id,
+                    event_type="GRAPH_SKELETON",
+                    original_tokens=orig_t,
+                    optimized_tokens=skel_t,
+                    details={
+                        "target_file": os.path.basename(path),
+                        "symbol": target_sym,
+                        "saved_tokens": saved
+                    }
+                )
+                print(json.dumps(response))
+                return
+
         if overwrite_args and metrics.get("saved_tokens", 0) > 0:
             response["overwrite"] = overwrite_args
             response["reason"] = (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokensafe",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Autonomous Zero-Loss Token Economy & Context Optimizer for AI Coding Agents",
   "main": "bin/tokensafe.js",
   "bin": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agy-token-optimizer",
   "displayName": "TokenSafe",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Zero-Loss Token Economy & Context Optimizer for AI Agents. Compresses prompts, slices AST/tool outputs, and prevents stuck loops.",
   "logo": "assets/logo.svg",
   "author": {

package/rules/AGENTS.md

@@ -24,3 +24,8 @@ Execute the specified action directly based on these extracted parameters.
 2. **Surgical Code Edits**: Prefer `edit_file` with concise `Target` and `Replacement` over `write_file` on large existing files.
 3. **Diff-Centric Responses**: Never reprint entire unmodified files or long boilerplate blocks. Reference file lines instead (e.g., `wallet.ts#L42-L50`).
 4. **Dense Formatting**: Use compact bullet points and direct technical prose.
+
+### 3. Architecture & Code Navigation Directives (Graph-Guided)
+1. **Never Crawl with Raw Grep/Find**: Before executing exploratory searches or answering architecture questions, inspect `tokensafe:get_architecture_graph` or `tokensafe-out/API_SURFACE.md`. It provides project God Nodes and dependencies in < 250 tokens without file crawling.
+2. **Graph-Guided File Reading**: When inspecting code implementations, call `tokensafe:smart_read_file` with the targeted `symbol`. It preserves full executable bodies for the target function and its 1-hop callees while folding inert code into signatures (-85% to -92% tokens).
+3. **Bounded Reads**: Never call `read_file` without `StartLine`/`EndLine` on files > 100 lines unless inspecting a skeleton.

package/skills/token-optimizer/SKILL.md

@@ -2,47 +2,85 @@
 name: token-optimizer
 description: >-
   Inspect token efficiency metrics, view cost savings dashboard, test prompt compression,
-  and operate the Token-Optimized Communication Protocol (TOCP) in Antigravity.
+  navigate codebases via zero-token AST architecture graphs, and operate the Token-Optimized Communication Protocol (TOCP).
 ---
 
-# Token Optimizer Skill
+# TokenSafe Optimization & Architecture Intelligence Skill
 
-This skill allows the agent to inspect token savings, query the metrics database,
-and report resource utilization efficiency.
+This skill provides autonomous AI coding assistants with deterministic, zero-token AST architecture indexing, graph-guided code slicing, command sanitization, and context optimization metrics.
 
-## Quick CLI Commands
+## When to Activate This Skill
+1. **Architecture Discovery**: Mapping new or unfamiliar codebases, finding God Nodes and key dependency hubs without LLM token burn.
+2. **Graph-Guided Code Inspection**: Reading functions or classes with their 1-hop dependencies while folding inert boilerplate (-85% to -92% tokens).
+3. **Telemetry & Economics**: Inspecting token savings, breakdown by optimization source, and ROI.
+4. **Command & Prompt Optimization**: Sanitizing terminal output and testing TOCP compression.
 
-Use the bundled `agy-tokens` CLI from this plugin directory:
+## Core MCP Tools (`tokensafe`)
 
-```bash
-# Display visual terminal dashboard
-./bin/agy-tokens stats
+| MCP Tool | Purpose | Token Cost |
+|---|---|---|
+| `tokensafe:get_architecture_graph` | Analyzes AST topology, God Nodes, and hub centrality for `project_path`. | ~150-250 tokens |
+| `tokensafe:get_api_surface` | Exports public signatures and types for the entire project. | ~300-600 tokens |
+| `tokensafe:smart_read_file` | Reads `path` focusing on `symbol` + 1-hop dependencies; folds inert code into signatures. | -85% to -92% vs raw read |
+| `tokensafe:sanitize_command` | Strips lockfiles, limits test/build output, and prevents context poisoning. | Saves 10k-50k tokens |
+| `tokensafe:compress_prompt` | Compresses verbose user instructions into lean TOCP S-expressions. | -40% to -65% |
+| `tokensafe:get_token_savings_metrics` | Returns total tokens saved, USD value, and breakdown by source. | ~100 tokens |
 
-# Test compression on a prompt and view savings
-./bin/agy-tokens test "Слушай, перепиши функцию get_balance в wallet.ts, добавь redis cache"
+## Agent Graph-First Workflow
 
-# Export Markdown summary for artifacts or chat
-./bin/agy-tokens markdown
+### 1. Zero-Token Architecture Survey
+Before running recursive searches or reading multi-file structures, query the architecture graph:
+```json
+{
+  "ServerName": "tokensafe",
+  "ToolName": "get_architecture_graph",
+  "Arguments": {
+    "project_path": "/absolute/path/to/project"
+  }
+}
+```
+* **Output**: Centrality scores, dependent counts, and identified God Nodes (e.g., `src/graph_engine.py (71 deps)`).
 
-# Reset metrics database
-./bin/agy-tokens reset
+### 2. Graph-Guided Symbol Inspection
+To read a targeted function or class without reading hundreds of lines of inert code:
+```json
+{
+  "ServerName": "tokensafe",
+  "ToolName": "smart_read_file",
+  "Arguments": {
+    "path": "/absolute/path/to/file.py",
+    "symbol": "TargetClassName"
+  }
+}
 ```
+* **Output**: The target definition and its direct 1-hop callees are shown in full; all other classes/methods are folded into 1-line signatures.
 
-## Programmatic Usage
+### 3. Command Sanitization
+Before executing potentially verbose terminal commands (`git diff`, `git grep`, `pytest`, `find`):
+```json
+{
+  "ServerName": "tokensafe",
+  "ToolName": "sanitize_command",
+  "Arguments": {
+    "command": "git diff HEAD~1"
+  }
+}
+```
 
-To inspect current metrics programmatically:
+## CLI Usage
 
-```python
-from src.metrics import MetricsTracker
-from src.dashboard import Dashboard
+Developers and agents can run `tokensafe` (or `./bin/agy-tokens`) directly from the terminal:
 
-tracker = MetricsTracker()
-dashboard = Dashboard(tracker)
-print(dashboard.render_markdown())
-```
+```bash
+# View terminal breakdown & recent optimizations
+tokensafe stats
+
+# Open interactive Apple-style HTML dashboard in browser
+tokensafe html
 
-## How It Works Under the Hood
-1. **PreInvocation Hook**: Intercepts verbose user prompts and generates a concise S-expression `(ACTION target symbol [traits] "intent")`, stripping politeness filler.
-2. **PreToolUse Hook**: Prevents dumping 800+ lines into the context window by slicing `read_file` to relevant line ranges.
-3. **Prompt Cache Anchor**: Static TOCP rules in `rules/AGENTS.md` hit Gemini's prompt cache with 100% stability.
-4. **Persistent Metrics**: Every token saved is recorded in SQLite (`data/metrics.db`) with timestamp, percentage reduction, and estimated USD value.
+# Run universal agent installer/synchronizer
+tokensafe install
+
+# Test prompt compression
+tokensafe test "Refactor get_user_balance with redis caching"
+```

package/src/__init__.py

@@ -2,5 +2,5 @@
 TokenSafe: Autonomous Zero-Loss Token Economy & Context Optimizer for AI Coding Agents.
 """
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"
 __author__ = "TokenSafe Team"

package/src/command_sanitizer.py

@@ -10,14 +10,17 @@ from typing import Tuple, Dict, Any, Optional
 class CommandSanitizer:
     """Optimizes terminal command lines to eliminate token waste."""
 
-    # Lockfiles and binary patterns that should never be dumped in git diffs
+    # Lockfiles and binary patterns that should never be dumped in git diffs or searches
     LOCKFILE_EXCLUDES = [
         "':!package-lock.json'",
         "':!pnpm-lock.yaml'",
         "':!yarn.lock'",
+        "':!bun.lock'",
+        "':!bun.lockb'",
         "':!Cargo.lock'",
         "':!go.sum'",
         "':!composer.lock'",
+        "':!*.lock'",
         "':!*.min.js'",
         "':!*.min.css'",
         "':!*.bundle.js'",
@@ -80,11 +83,36 @@ class CommandSanitizer:
                 est_saved = 1500
                 return new_cmd, est_saved, "Pruned .git, node_modules, and venv from find"
 
-        # 5. grep / ripgrep unbounded search
-        if re.search(r"\b(grep|egrep)\b", cmd):
-            if "--exclude-dir" not in cmd and "node_modules" not in cmd:
-                new_cmd = f"{cmd} --exclude-dir={{dist,build,node_modules,.git,coverage,__pycache__,.next,data}}"
-                if "|" not in new_cmd:
+        # 5. git grep search (Exclude lockfiles & directories via pathspecs)
+        if re.search(r"\bgit\b.*?\bgrep\b", cmd):
+            if ":!*.lock" not in cmd and ":!bun.lock" not in cmd:
+                git_excludes = "':!*.lock' ':!bun.lock' ':!bun.lockb' ':!package-lock.json' ':!dist' ':!build' ':!node_modules'"
+                stages = [s.strip() for s in re.split(r'(?<!\|)\|(?!\|)', cmd)]
+                for i, stage in enumerate(stages):
+                    if re.search(r"\bgit\b.*?\bgrep\b", stage):
+                        if " -- " in stage:
+                            stages[i] = f"{stage} {git_excludes}"
+                        else:
+                            stages[i] = f"{stage} -- . {git_excludes}"
+                new_cmd = " | ".join(stages)
+                has_limiter = any(re.search(r'\b(head|tail|less)\b', s) for s in stages)
+                if not has_limiter:
+                    new_cmd = f"{new_cmd} | head -n 30"
+                est_saved = 3500
+                return new_cmd, est_saved, "Excluded lockfiles from git grep and capped output"
+
+        # 6. grep / ripgrep unbounded search (only when recursive or scanning directory)
+        if re.search(r"\b(grep|egrep)\b", cmd) and not re.search(r"\bgit\b.*?\bgrep\b", cmd):
+            is_recursive = bool(re.search(r"\b(grep|egrep)\b.*?\s-[a-zA-Z]*[rR]", cmd))
+            if is_recursive and "--exclude-dir" not in cmd and "node_modules" not in cmd:
+                excludes = "--exclude='*.lock' --exclude='*.lockb' --exclude-dir={dist,build,node_modules,.git,coverage,__pycache__,.next,data}"
+                stages = [s.strip() for s in re.split(r'(?<!\|)\|(?!\|)', cmd)]
+                for i, stage in enumerate(stages):
+                    if re.search(r"\b(grep|egrep)\b", stage):
+                        stages[i] = f"{stage} {excludes}"
+                new_cmd = " | ".join(stages)
+                has_limiter = any(re.search(r'\b(head|tail|less)\b', s) for s in stages)
+                if not has_limiter:
                     new_cmd = f"{new_cmd} | head -n 30"
                 est_saved = 2500
                 return new_cmd, est_saved, "Sanitized grep directories and capped output to 30 matches"

package/src/dashboard.py

@@ -35,6 +35,8 @@ EVENT_NAMES = {
     "PROMPT": "Prompt Compactor (TOCP)",
     "TOOL_READ": "File Line Slicer (AST)",
     "AST_SKELETON": "AST Skeletonizer (Signatures)",
+    "GRAPH_SKELETON": "Graph-Guided Slicer (Call-Graph)",
+    "GRAPH_TOPOLOGY": "Architecture Graph (God Nodes)",
     "COMMAND_FILTER": "Command Sanitizer (CLI)",
     "OUTPUT_GUARD": "Output Token Guard (write_file)",
     "LOOP_GUARD": "Anti-Stuck Loop Guard",

package/src/graph_engine.py

@@ -415,20 +415,48 @@ class CodeGraph:
 
 
 class GraphEngine:
-    """Singleton Manager for automatic background graph execution."""
+    """Multi-Project Manager for automatic background graph execution."""
 
-    _instance: Optional[CodeGraph] = None
+    _instances: Dict[str, CodeGraph] = {}
+
+    @classmethod
+    def find_project_root(cls, start_path: str) -> str:
+        """Walks up from start_path to locate project boundary markers."""
+        curr = os.path.abspath(start_path)
+        if os.path.isfile(curr):
+            curr = os.path.dirname(curr)
+
+        root = os.path.abspath(os.sep)
+        while curr and curr != root:
+            for marker in (".git", "package.json", "pyproject.toml", "go.mod", "Cargo.toml", "requirements.txt"):
+                if os.path.exists(os.path.join(curr, marker)):
+                    return curr
+            parent = os.path.dirname(curr)
+            if parent == curr:
+                break
+            curr = parent
+        return os.path.abspath(start_path if os.path.isdir(start_path) else os.path.dirname(start_path))
 
     @classmethod
     def get_instance(cls, root_dir: str = ".") -> CodeGraph:
-        if cls._instance is None or cls._instance.root_dir != os.path.abspath(root_dir):
-            cls._instance = CodeGraph(root_dir)
-            cls._instance.scan()
+        root_abs = os.path.abspath(root_dir)
+        if root_abs not in cls._instances:
+            graph = CodeGraph(root_abs)
+            graph.scan()
+            cls._instances[root_abs] = graph
         else:
-            # Incremental scan if older than 3 seconds
-            if time.time() - cls._instance.last_scanned > 3.0:
-                cls._instance.scan()
-        return cls._instance
+            graph = cls._instances[root_abs]
+            if time.time() - graph.last_scanned > 3.0:
+                graph.scan()
+        return graph
+
+    @classmethod
+    def for_file(cls, file_path: str) -> Tuple[CodeGraph, str]:
+        """Resolves the owning project graph and relative file path for any arbitrary file."""
+        root = cls.find_project_root(file_path)
+        graph = cls.get_instance(root)
+        rel_path = os.path.relpath(os.path.abspath(file_path), root).replace("\\", "/")
+        return graph, rel_path
 
 def main():
     import sys

package/src/installer.py

@@ -57,6 +57,14 @@ AGENTS_REGISTRY = {
         "config_path": os.path.join(HOME, "Library", "Application Support", "Code", "User", "globalStorage", "saoudrizwan.claude-dev", "settings", "cline_mcp_settings.json"),
         "detect_path": os.path.join(HOME, "Library", "Application Support", "Code")
     },
+    "claude_code": {
+        "name": "Claude Code CLI",
+        "type": "claude_md",
+        "config_path": os.path.join(HOME, ".claude.json"),
+        "agents_md_path": os.path.join(HOME, ".claude", "CLAUDE.md"),
+        "skills_path": os.path.join(HOME, ".claude", "skills", "token-optimizer"),
+        "detect_path": os.path.join(HOME, ".claude")
+    },
     "codex": {
         "name": "OpenAI Codex",
         "type": "codex_toml",
@@ -66,12 +74,19 @@ AGENTS_REGISTRY = {
         "plugin_path": os.path.join(HOME, ".codex", "plugins", "tokensafe"),
         "detect_path": os.path.join(HOME, ".codex")
     },
+    "copilot": {
+        "name": "GitHub Copilot",
+        "type": "copilot_json",
+        "config_path": os.path.join(HOME, ".copilot", "mcp-config.json"),
+        "detect_path": os.path.join(HOME, ".copilot")
+    },
     "zcode": {
         "name": "Z.ai Code",
         "type": "zcode_json",
         "config_path": os.path.join(HOME, ".zcode", "cli", "config.json"),
         "skills_path": os.path.join(HOME, ".zcode", "skills", "token-optimizer"),
         "plugin_path": os.path.join(HOME, ".zcode", "cli", "plugins", "tokensafe"),
+        "agents_md_path": os.path.join(HOME, ".zcode", "AGENTS.md"),
         "detect_path": os.path.join(HOME, ".zcode")
     }
 }
@@ -144,15 +159,16 @@ class AgentInstaller:
             if "rules_path" in info:
                 rule_text = (
                     "---\n"
-                    "description: TokenSafe token economy and context optimization protocol\n"
+                    "description: TokenSafe token economy, graph-first navigation and context optimization protocol\n"
                     "globs: *\n"
                     "alwaysApply: true\n"
                     "---\n\n"
-                    "# TokenSafe Optimization Protocol\n"
-                    "Always prioritize `tokensafe` MCP tools (`smart_read_file`, `compress_prompt`, `sanitize_command`) "
-                    "over default raw file reads or high-output terminal executions to preserve context tokens and prevent context overflow.\n"
-                    "- When inspecting code files, use `smart_read_file` with `symbol` or line range.\n"
-                    "- Sanitize verbose commands (`git diff`, `pytest`, `find`, `grep`) via `sanitize_command`.\n"
+                    "# TokenSafe Graph-First Optimization Protocol\n"
+                    "Always prioritize `tokensafe` MCP tools over default raw file reads or high-output terminal executions to prevent context window exhaustion.\n\n"
+                    "1. **Architecture Discovery**: Always call `tokensafe:get_architecture_graph` before grep or multi-file reading. Returns project God Nodes and key dependency hubs in < 250 tokens without file crawling.\n"
+                    "2. **Graph-Guided Symbol Inspection**: When inspecting code implementations, prioritize `tokensafe:smart_read_file` with the targeted `symbol`. Returns full executable bodies for the symbol and 1-hop dependencies while folding inert code into signatures (-85% to -92% tokens).\n"
+                    "3. **No Unconstrained Shell Grep/Find**: Strictly avoid running raw recursive grep/find across projects. Use `get_architecture_graph` or `get_api_surface`.\n"
+                    "4. **Command Sanitization**: Use `sanitize_command` on high-output terminal commands (`git diff`, `pytest`, `find`, `grep`) to prevent lockfile or test log context contamination.\n"
                 )
                 cls._write_file_safely(info["rules_path"], rule_text)
 
@@ -229,16 +245,74 @@ class AgentInstaller:
 
             if "agents_md_path" in info:
                 codex_rule = (
-                    "## TOKENSAFE TOKEN OPTIMIZATION PROTOCOL\n"
-                    "Always prioritize `tokensafe` MCP tools (`smart_read_file`, `compress_prompt`, `sanitize_command`) "
-                    "over default raw file reads or high-token shell executions to preserve context tokens and prevent context overflow.\n"
-                    "- When inspecting code files, use `smart_read_file` with `symbol` or line range.\n"
-                    "- When running verbose commands (`git diff`, `pytest`, `find`, `grep`), sanitize them with `sanitize_command`.\n"
+                    "## TOKENSAFE GRAPH-FIRST OPTIMIZATION PROTOCOL\n"
+                    "Always prioritize `tokensafe` MCP tools over default raw file reads or high-output terminal executions to prevent context window exhaustion.\n"
+                    "1. **Architecture Discovery**: Always call `tokensafe:get_architecture_graph` before grep or multi-file reading. Returns project God Nodes and key dependency hubs in < 250 tokens without file crawling.\n"
+                    "2. **Graph-Guided Symbol Inspection**: When inspecting code implementations, prioritize `tokensafe:smart_read_file` with the targeted `symbol`. Returns full executable bodies for the symbol and 1-hop dependencies while folding inert code into signatures (-85% to -92% tokens).\n"
+                    "3. **No Unconstrained Shell Grep/Find**: Strictly avoid running raw recursive grep/find across projects. Use `get_architecture_graph` or `get_api_surface`.\n"
+                    "4. **Command Sanitization**: Use `sanitize_command` on high-output terminal commands (`git diff`, `pytest`, `find`, `grep`) to prevent lockfile or test log context contamination.\n"
                 )
                 cls._inject_global_rule(info["agents_md_path"], codex_rule)
 
             return True, f"Configured MCP, Plugin, Skill & AGENTS.md in {config_file}"
 
+        elif info["type"] == "claude_md":
+            if "config_path" in info:
+                config_file = info["config_path"]
+                data = {}
+                if os.path.exists(config_file):
+                    try:
+                        with open(config_file, "r", encoding="utf-8") as f:
+                            data = json.load(f)
+                    except Exception:
+                        data = {}
+                if "mcpServers" not in data or not isinstance(data["mcpServers"], dict):
+                    data["mcpServers"] = {}
+                data["mcpServers"]["tokensafe"] = {
+                    "command": PYTHON_BIN,
+                    "args": [MCP_SERVER_PATH]
+                }
+                with open(config_file, "w", encoding="utf-8") as f:
+                    json.dump(data, f, indent=2)
+
+            if "agents_md_path" in info:
+                claude_rule = (
+                    "## TOKENSAFE GRAPH-FIRST OPTIMIZATION PROTOCOL\n"
+                    "Always prioritize `tokensafe` MCP tools over default raw file reads or recursive grep/find.\n"
+                    "1. **Architecture Discovery**: Always call `tokensafe:get_architecture_graph` before grep or multi-file reading. Returns project God Nodes and key dependency hubs in < 250 tokens without file crawling.\n"
+                    "2. **Graph-Guided Symbol Inspection**: When inspecting code implementations, prioritize `tokensafe:smart_read_file` with the targeted `symbol`. Returns full executable bodies for the symbol and 1-hop dependencies while folding inert code into signatures (-85% to -92% tokens).\n"
+                    "3. **No Unconstrained Shell Grep/Find**: Strictly avoid running raw recursive grep/find across projects. Use `get_architecture_graph` or `get_api_surface`.\n"
+                    "4. **Command Sanitization**: Use `sanitize_command` on high-output terminal commands (`git diff`, `pytest`, `find`, `grep`) to prevent lockfile or test log context contamination.\n"
+                )
+                cls._inject_global_rule(info["agents_md_path"], claude_rule)
+
+            if "skills_path" in info:
+                cls._symlink_skill(info["skills_path"])
+
+            return True, f"Configured MCP, Rule & Skill in {info.get('agents_md_path')}"
+
+        elif info["type"] == "copilot_json":
+            config_file = info["config_path"]
+            os.makedirs(os.path.dirname(config_file), exist_ok=True)
+            data = {}
+            if os.path.exists(config_file):
+                try:
+                    with open(config_file, "r", encoding="utf-8") as f:
+                        data = json.load(f)
+                except Exception:
+                    data = {}
+            if "mcpServers" not in data or not isinstance(data["mcpServers"], dict):
+                data["mcpServers"] = {}
+            data["mcpServers"]["tokensafe"] = {
+                "type": "stdio",
+                "command": PYTHON_BIN,
+                "args": [MCP_SERVER_PATH],
+                "tools": ["*"]
+            }
+            with open(config_file, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2)
+            return True, f"Configured MCP for GitHub Copilot in {config_file}"
+
         elif info["type"] == "zcode_json":
             config_file = info["config_path"]
             os.makedirs(os.path.dirname(config_file), exist_ok=True)
@@ -271,7 +345,18 @@ class AgentInstaller:
             if "plugin_path" in info:
                 cls._symlink_dir(PROJECT_ROOT, info["plugin_path"])
 
-            return True, f"Configured MCP, Plugin & Skill in {config_file}"
+            if "agents_md_path" in info:
+                zcode_rule = (
+                    "## TOKENSAFE GRAPH-FIRST OPTIMIZATION PROTOCOL\n"
+                    "Always prioritize `tokensafe` MCP tools over default raw file reads or high-output terminal executions to prevent context window exhaustion.\n"
+                    "1. **Architecture Discovery**: Always call `tokensafe:get_architecture_graph` before grep or multi-file reading. Returns project God Nodes and key dependency hubs in < 250 tokens without file crawling.\n"
+                    "2. **Graph-Guided Symbol Inspection**: When inspecting code implementations, prioritize `tokensafe:smart_read_file` with the targeted `symbol`. Returns full executable bodies for the symbol and 1-hop dependencies while folding inert code into signatures (-85% to -92% tokens).\n"
+                    "3. **No Unconstrained Shell Grep/Find**: Strictly avoid running raw recursive grep/find across projects. Use `get_architecture_graph` or `get_api_surface`.\n"
+                    "4. **Command Sanitization**: Use `sanitize_command` on high-output terminal commands (`git diff`, `pytest`, `find`, `grep`) to prevent lockfile or test log context contamination.\n"
+                )
+                cls._inject_global_rule(info["agents_md_path"], zcode_rule)
+
+            return True, f"Configured MCP, Plugin, Skill & AGENTS.md in {config_file}"
 
         return False, "Unsupported type"
 

package/src/mailer.py

@@ -0,0 +1,327 @@
+"""
+TokenSafe Transactional Email Service.
+Handles transactional emails via ImprovMX SMTP (port 587 TLS)
+with beautiful responsive dark-mode HTML templates and asynchronous delivery.
+"""
+
+import os
+import ssl
+import smtplib
+import threading
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from typing import Optional, Dict, Any
+
+class TokenSafeMailer:
+    """Dispatches transactional notifications (Welcome, Team Seat Invites)."""
+
+    SMTP_HOST = os.environ.get("SMTP_HOST", "smtp.improvmx.com")
+    SMTP_PORT = int(os.environ.get("SMTP_PORT", "587"))
+    SMTP_USER = os.environ.get("SMTP_USER", "any-alias-1@tokensafe.dev")
+    SMTP_PASS = os.environ.get("SMTP_PASS", "g7Qw8nB1U1Q9")
+    SMTP_FROM = os.environ.get("SMTP_FROM", "TokenSafe <support@tokensafe.dev>")
+    SMTP_TIMEOUT = 10
+
+    @classmethod
+    def _send_raw(cls, recipient: str, subject: str, text_content: str, html_content: str) -> bool:
+        """Sends an email synchronously via SMTP with STARTTLS."""
+        msg = MIMEMultipart("alternative")
+        msg["Subject"] = subject
+        msg["From"] = cls.SMTP_FROM
+        msg["To"] = recipient
+
+        # Attach plain text and HTML alternatives
+        msg.attach(MIMEText(text_content, "plain", "utf-8"))
+        msg.attach(MIMEText(html_content, "html", "utf-8"))
+
+        try:
+            server = smtplib.SMTP(cls.SMTP_HOST, cls.SMTP_PORT, timeout=cls.SMTP_TIMEOUT)
+            server.ehlo()
+            context = ssl.create_default_context()
+            server.starttls(context=context)
+            server.ehlo()
+            server.login(cls.SMTP_USER, cls.SMTP_PASS)
+            server.sendmail(cls.SMTP_USER, [recipient], msg.as_string())
+            server.quit()
+            return True
+        except Exception as e:
+            # Log error in production
+            print(f"[Mailer Error] Failed to send email to {recipient}: {e}")
+            return False
+
+    @classmethod
+    def send_async(cls, recipient: str, subject: str, text_content: str, html_content: str):
+        """Dispatches email sending in a non-blocking background daemon thread."""
+        thread = threading.Thread(
+            target=cls._send_raw,
+            args=(recipient, subject, text_content, html_content),
+            daemon=True
+        )
+        thread.start()
+
+    @classmethod
+    def send_welcome_email(cls, recipient: str, license_key: str, tier: str = "solo", is_trial: bool = True):
+        """Sends welcome email with license key and 1-click onboarding instructions."""
+        plan_name = "Solo Developer (7-Day Trial)" if tier == "solo" else "Engineering Team (7-Day Trial)"
+        subject = f"Welcome to TokenSafe — Your {plan_name} License Key"
+
+        text_content = f"""Welcome to TokenSafe!
+
+Your {plan_name} has been activated.
+
+Your License Key:
+{license_key}
+
+Quick Setup (1 command):
+npx tokensafe
+
+Or connect existing tools:
+tokensafe auth {license_key}
+
+Open your cloud dashboard:
+https://tokensafe.dev/dashboard
+
+If you need any assistance, simply reply to this email.
+— The TokenSafe Team
+https://tokensafe.dev
+"""
+
+        html_content = f"""<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{subject}</title>
+</head>
+<body style="margin: 0; padding: 0; background-color: #030712; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; color: #f3f4f6;">
+  <table role="presentation" width="100%" cellspacing="0" cellpadding="0" style="background-color: #030712; padding: 40px 20px;">
+    <tr>
+      <td align="center">
+        <table role="presentation" width="100%" style="max-width: 580px; background-color: #0f172a; border: 1px solid rgba(255, 255, 255, 0.08); border-radius: 16px; padding: 36px; box-shadow: 0 20px 40px rgba(0,0,0,0.4);">
+          
+          <!-- Logo / Header -->
+          <tr>
+            <td style="padding-bottom: 24px; border-bottom: 1px solid rgba(255, 255, 255, 0.06);">
+              <span style="font-size: 20px; font-weight: 800; color: #ffffff; letter-spacing: -0.5px;">
+                Token<span style="color: #10b981;">Safe</span>
+              </span>
+              <span style="float: right; font-size: 11px; font-weight: 700; color: #10b981; background: rgba(16, 185, 129, 0.1); border: 1px solid rgba(16, 185, 129, 0.2); padding: 4px 10px; border-radius: 999px; text-transform: uppercase;">
+                {tier.upper()} ACTIVE
+              </span>
+            </td>
+          </tr>
+
+          <!-- Title -->
+          <tr>
+            <td style="padding-top: 28px; padding-bottom: 12px;">
+              <h1 style="margin: 0; font-size: 22px; font-weight: 700; color: #ffffff; line-height: 1.3;">
+                Welcome to Autonomous Token Economy
+              </h1>
+              <p style="margin: 8px 0 0; font-size: 14px; color: #94a3b8; line-height: 1.6;">
+                Your plan <strong style="color: #f1f5f9;">{plan_name}</strong> is ready. Your agents will now compress context, eliminate stuck loops, and protect token budgets.
+              </p>
+            </td>
+          </tr>
+
+          <!-- License Key Box -->
+          <tr>
+            <td style="padding: 20px 0;">
+              <div style="background-color: #020617; border: 1px solid rgba(16, 185, 129, 0.3); border-radius: 12px; padding: 18px; text-align: center;">
+                <div style="font-size: 11px; font-weight: 600; text-transform: uppercase; color: #94a3b8; letter-spacing: 0.5px; margin-bottom: 8px;">
+                  Your Cryptographic License Key
+                </div>
+                <div style="font-family: ui-monospace, Menlo, Consolas, monospace; font-size: 15px; font-weight: 700; color: #34d399; letter-spacing: 0.5px; word-break: break-all;">
+                  {license_key}
+                </div>
+              </div>
+            </td>
+          </tr>
+
+          <!-- Quick Setup Steps -->
+          <tr>
+            <td style="padding-bottom: 24px;">
+              <h3 style="font-size: 14px; font-weight: 600; color: #e2e8f0; margin: 0 0 12px;">
+                🚀 Quick Start (Instant Installation)
+              </h3>
+              
+              <!-- Command 1 -->
+              <div style="background-color: #020617; border: 1px solid rgba(255, 255, 255, 0.06); border-radius: 8px; padding: 12px 16px; margin-bottom: 10px; font-family: ui-monospace, Menlo, Consolas, monospace; font-size: 13px; color: #f8fafc;">
+                <span style="color: #10b981;">$</span> npx tokensafe
+              </div>
+
+              <!-- Command 2 -->
+              <div style="background-color: #020617; border: 1px solid rgba(255, 255, 255, 0.06); border-radius: 8px; padding: 12px 16px; margin-bottom: 16px; font-family: ui-monospace, Menlo, Consolas, monospace; font-size: 13px; color: #f8fafc;">
+                <span style="color: #10b981;">$</span> tokensafe auth {license_key}
+              </div>
+
+              <p style="margin: 0; font-size: 13px; color: #94a3b8; line-height: 1.5;">
+                Or install via Python PyPI: <code style="color: #38bdf8; background: rgba(56, 189, 248, 0.1); padding: 2px 6px; border-radius: 4px;">pip install tokensafe</code>. Compatible with Cursor, Claude Desktop, Antigravity, and Codex.
+              </p>
+            </td>
+          </tr>
+
+          <!-- CTA Button -->
+          <tr>
+            <td align="center" style="padding: 16px 0 28px;">
+              <a href="https://tokensafe.dev/dashboard?key={license_key}" style="display: inline-block; background-color: #10b981; color: #020617; font-size: 14px; font-weight: 700; text-decoration: none; padding: 14px 32px; border-radius: 10px; box-shadow: 0 8px 16px rgba(16, 185, 129, 0.2);">
+                Open Cloud Analytics Dashboard →
+              </a>
+            </td>
+          </tr>
+
+          <!-- Footer -->
+          <tr>
+            <td style="border-top: 1px solid rgba(255, 255, 255, 0.06); padding-top: 20px; font-size: 12px; color: #64748b; line-height: 1.5;">
+              Need help or custom integrations? Just reply to this email or reach us at <a href="mailto:support@tokensafe.dev" style="color: #10b981; text-decoration: none;">support@tokensafe.dev</a>.<br>
+              © 2026 TokenSafe. Autonomous Zero-Loss Token Economy.
+            </td>
+          </tr>
+
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>
+"""
+        cls.send_async(recipient, subject, text_content, html_content)
+
+    @classmethod
+    def send_team_invite_email(cls, recipient: str, seat_license_key: str, owner_email: str):
+        """Sends team member onboarding email with instructions on connecting IDEs."""
+        subject = f"Your TokenSafe Team Seat License — Invited by {owner_email}"
+
+        text_content = f"""Hi there!
+
+Your team lead ({owner_email}) has granted you a TokenSafe Team developer seat.
+
+Your Personal Seat Key:
+{seat_license_key}
+
+Setup Guide:
+1. Run the instant setup:
+   npx tokensafe
+
+2. Connect your personal seat license:
+   tokensafe auth {seat_license_key}
+
+3. IDE Integrations:
+   - Cursor: Extension is activated automatically.
+   - Claude Desktop: MCP server is configured in ~/Library/Application Support/Claude/claude_desktop_config.json.
+   - Terminal: Run 'tokensafe stats' anytime to see your saved context and tokens.
+
+Track your developer economics:
+https://tokensafe.dev/dashboard
+
+If you have any questions, contact your team lead ({owner_email}) or reply to this email.
+— The TokenSafe Team
+"""
+
+        html_content = f"""<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{subject}</title>
+</head>
+<body style="margin: 0; padding: 0; background-color: #030712; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; color: #f3f4f6;">
+  <table role="presentation" width="100%" cellspacing="0" cellpadding="0" style="background-color: #030712; padding: 40px 20px;">
+    <tr>
+      <td align="center">
+        <table role="presentation" width="100%" style="max-width: 580px; background-color: #0f172a; border: 1px solid rgba(255, 255, 255, 0.08); border-radius: 16px; padding: 36px; box-shadow: 0 20px 40px rgba(0,0,0,0.4);">
+          
+          <!-- Logo / Header -->
+          <tr>
+            <td style="padding-bottom: 24px; border-bottom: 1px solid rgba(255, 255, 255, 0.06);">
+              <span style="font-size: 20px; font-weight: 800; color: #ffffff; letter-spacing: -0.5px;">
+                Token<span style="color: #10b981;">Safe</span>
+              </span>
+              <span style="float: right; font-size: 11px; font-weight: 700; color: #38bdf8; background: rgba(56, 189, 248, 0.1); border: 1px solid rgba(56, 189, 248, 0.2); padding: 4px 10px; border-radius: 999px; text-transform: uppercase;">
+                TEAM SEAT INVITE
+              </span>
+            </td>
+          </tr>
+
+          <!-- Title -->
+          <tr>
+            <td style="padding-top: 28px; padding-bottom: 12px;">
+              <h1 style="margin: 0; font-size: 22px; font-weight: 700; color: #ffffff; line-height: 1.3;">
+                You've been added to TokenSafe Team
+              </h1>
+              <p style="margin: 8px 0 0; font-size: 14px; color: #94a3b8; line-height: 1.6;">
+                Team lead <strong style="color: #38bdf8;">{owner_email}</strong> has provisioned a dedicated TokenSafe developer seat for you. Context compression and token guards are now active for your workflow.
+              </p>
+            </td>
+          </tr>
+
+          <!-- License Key Box -->
+          <tr>
+            <td style="padding: 20px 0;">
+              <div style="background-color: #020617; border: 1px solid rgba(56, 189, 248, 0.3); border-radius: 12px; padding: 18px; text-align: center;">
+                <div style="font-size: 11px; font-weight: 600; text-transform: uppercase; color: #94a3b8; letter-spacing: 0.5px; margin-bottom: 8px;">
+                  Your Dedicated Team Seat Key
+                </div>
+                <div style="font-family: ui-monospace, Menlo, Consolas, monospace; font-size: 15px; font-weight: 700; color: #38bdf8; letter-spacing: 0.5px; word-break: break-all;">
+                  {seat_license_key}
+                </div>
+              </div>
+            </td>
+          </tr>
+
+          <!-- Setup Instructions -->
+          <tr>
+            <td style="padding-bottom: 24px;">
+              <h3 style="font-size: 14px; font-weight: 600; color: #e2e8f0; margin: 0 0 12px;">
+                ⚙️ Quick 3-Step Setup
+              </h3>
+              
+              <div style="margin-bottom: 16px;">
+                <div style="font-size: 12px; font-weight: 600; color: #cbd5e1; margin-bottom: 4px;">Step 1: Install TokenSafe CLI</div>
+                <div style="background-color: #020617; border: 1px solid rgba(255, 255, 255, 0.06); border-radius: 8px; padding: 10px 14px; font-family: ui-monospace, Menlo, Consolas, monospace; font-size: 13px; color: #f8fafc;">
+                  <span style="color: #10b981;">$</span> npx tokensafe
+                </div>
+              </div>
+
+              <div style="margin-bottom: 16px;">
+                <div style="font-size: 12px; font-weight: 600; color: #cbd5e1; margin-bottom: 4px;">Step 2: Bind your seat license</div>
+                <div style="background-color: #020617; border: 1px solid rgba(255, 255, 255, 0.06); border-radius: 8px; padding: 10px 14px; font-family: ui-monospace, Menlo, Consolas, monospace; font-size: 13px; color: #f8fafc;">
+                  <span style="color: #10b981;">$</span> tokensafe auth {seat_license_key}
+                </div>
+              </div>
+
+              <div style="margin-bottom: 16px;">
+                <div style="font-size: 12px; font-weight: 600; color: #cbd5e1; margin-bottom: 4px;">Step 3: IDE Agents Automatic Hook</div>
+                <ul style="margin: 6px 0 0 18px; padding: 0; font-size: 13px; color: #94a3b8; line-height: 1.6;">
+                  <li><strong>Cursor / VSCode:</strong> Hooks directly into extension background loop.</li>
+                  <li><strong>Claude Desktop:</strong> MCP server runs at <code style="color: #34d399;">tokensafe-mcp</code>.</li>
+                  <li><strong>Terminal:</strong> Check your stats with <code style="color: #38bdf8;">tokensafe stats</code>.</li>
+                </ul>
+              </div>
+            </td>
+          </tr>
+
+          <!-- CTA Button -->
+          <tr>
+            <td align="center" style="padding: 16px 0 28px;">
+              <a href="https://tokensafe.dev/dashboard?key={seat_license_key}" style="display: inline-block; background-color: #0284c7; color: #ffffff; font-size: 14px; font-weight: 700; text-decoration: none; padding: 14px 32px; border-radius: 10px; box-shadow: 0 8px 16px rgba(2, 132, 199, 0.25);">
+                View Your Developer Portal →
+              </a>
+            </td>
+          </tr>
+
+          <!-- Footer -->
+          <tr>
+            <td style="border-top: 1px solid rgba(255, 255, 255, 0.06); padding-top: 20px; font-size: 12px; color: #64748b; line-height: 1.5;">
+              Invited by {owner_email}. Have questions? Contact your team lead or reach us at <a href="mailto:support@tokensafe.dev" style="color: #38bdf8; text-decoration: none;">support@tokensafe.dev</a>.<br>
+              © 2026 TokenSafe. Autonomous Zero-Loss Token Economy.
+            </td>
+          </tr>
+
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>
+"""
+        cls.send_async(recipient, subject, text_content, html_content)

package/src/mcp_server.py

@@ -21,10 +21,12 @@ from src.command_sanitizer import CommandSanitizer
 from src.loop_detector import LoopDetector
 from src.metrics import MetricsTracker
 from src.dashboard import Dashboard
+from src.graph_engine import GraphEngine
+from src.tokenizer import count_tokens
 
 SERVER_INFO = {
     "name": "tokensafe-mcp",
-    "version": "1.0.0"
+    "version": "1.2.0"
 }
 
 TOOLS = [
@@ -35,13 +37,33 @@ TOOLS = [
             "type": "object",
             "properties": {
                 "path": {"type": "string", "description": "Absolute path to the code file"},
-                "symbol": {"type": "string", "description": "Optional: targeted function or class name"},
+                "symbol": {"type": "string", "description": "Optional: targeted function or class name for graph-guided skeletonization"},
                 "start_line": {"type": "integer", "description": "Optional: starting line number"},
                 "end_line": {"type": "integer", "description": "Optional: ending line number"}
             },
             "required": ["path"]
         }
     },
+    {
+        "name": "get_architecture_graph",
+        "description": "Returns top architectural God Nodes and dependency topology for the target project.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project_path": {"type": "string", "description": "Optional: root directory or file path of the project"}
+            }
+        }
+    },
+    {
+        "name": "get_api_surface",
+        "description": "Generates and returns a compact markdown map of all exported interfaces, classes, and types in the project.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project_path": {"type": "string", "description": "Optional: root directory or file path of the project"}
+            }
+        }
+    },
     {
         "name": "compress_prompt",
         "description": "Compresses a verbose developer prompt into an ultra-dense TOCP S-Expression via DeepSeek-V3 / Regex.",
@@ -102,6 +124,27 @@ def handle_tool_call(name: str, args: dict) -> dict:
             return {"content": [{"type": "text", "text": (prefetch_block or "") + content}]}
 
         if symbol:
+            try:
+                graph, rel_path = GraphEngine.for_file(path)
+                graph_skel = graph.graph_guided_skeletonize(path, target_symbol=symbol)
+                if graph_skel:
+                    with open(path, "r", encoding="utf-8", errors="replace") as f:
+                        raw_code = f.read()
+                    orig_t = count_tokens(raw_code)
+                    skel_t = count_tokens(graph_skel)
+                    saved = max(0, orig_t - skel_t)
+                    tracker.record_event(
+                        session_id="mcp_session",
+                        event_type="GRAPH_SKELETON",
+                        original_tokens=orig_t,
+                        optimized_tokens=skel_t,
+                        details={"file": os.path.basename(path), "symbol": symbol, "saved_tokens": saved}
+                    )
+                    header = f"// [TokenSafe Graph-Guided Skeleton for '{symbol}' | Full body + 1-hop dependencies]\n"
+                    return {"content": [{"type": "text", "text": (prefetch_block or "") + header + graph_skel}]}
+            except Exception:
+                pass
+
             overwrite, metrics = ToolSlicer.optimize_read_file({"Path": path}, context_hint=symbol)
             if overwrite:
                 with open(path, "r", encoding="utf-8", errors="replace") as f:
@@ -144,6 +187,44 @@ def handle_tool_call(name: str, args: dict) -> dict:
         dashboard = Dashboard(tracker)
         return {"content": [{"type": "text", "text": dashboard.render_markdown()}]}
 
+    elif name == "get_architecture_graph":
+        target = args.get("project_path") or os.getcwd()
+        graph = GraphEngine.get_instance(target)
+        god_nodes = graph.get_god_nodes(7)
+        banner = graph.format_topology_banner()
+        payload = {
+            "project_root": graph.root_dir,
+            "banner": banner,
+            "total_files": len(graph.file_symbols),
+            "total_symbols": len(graph.symbols),
+            "god_nodes": god_nodes
+        }
+        est_crawl_tokens = max(5000, len(graph.file_symbols) * 800)
+        topo_tokens = 250
+        tracker.record_event(
+            session_id="mcp_session",
+            event_type="GRAPH_TOPOLOGY",
+            original_tokens=est_crawl_tokens,
+            optimized_tokens=topo_tokens,
+            details={"hubs_count": len(god_nodes), "indexed_files": len(graph.file_symbols)}
+        )
+        return {"content": [{"type": "text", "text": json.dumps(payload, indent=2, ensure_ascii=False)}]}
+
+    elif name == "get_api_surface":
+        target = args.get("project_path") or os.getcwd()
+        graph = GraphEngine.get_instance(target)
+        surface_md = graph.generate_api_surface()
+        surface_tokens = count_tokens(surface_md)
+        est_orig_tokens = max(10000, len(graph.file_symbols) * 1200)
+        tracker.record_event(
+            session_id="mcp_session",
+            event_type="GRAPH_TOPOLOGY",
+            original_tokens=est_orig_tokens,
+            optimized_tokens=surface_tokens,
+            details={"type": "API_SURFACE", "symbols_count": len(graph.symbols)}
+        )
+        return {"content": [{"type": "text", "text": surface_md}]}
+
     return {"isError": True, "content": [{"type": "text", "text": f"Unknown tool: {name}"}]}
 
 def run_mcp_server():

package/src/skeletonizer.py

@@ -77,9 +77,10 @@ class Skeletonizer:
         return "\n".join(out)
 
     @classmethod
-    def get_skeleton_file(cls, original_path: str) -> Tuple[Optional[str], int, int]:
+    def get_skeleton_file(cls, original_path: str, target_symbol: Optional[str] = None) -> Tuple[Optional[str], int, int]:
         """
         Reads original_path, checks mtime cache, generates skeleton if modified or absent.
+        If target_symbol is provided, applies Graph-Guided AST skeletonization retaining 1-hop dependencies.
         Returns: (skeleton_path_or_none, orig_tokens, skeleton_tokens)
         """
         if not original_path or not os.path.exists(original_path):
@@ -95,9 +96,10 @@ class Skeletonizer:
         os.makedirs(cls.CACHE_DIR, exist_ok=True)
         path_hash = hashlib.md5(original_path.encode("utf-8")).hexdigest()[:8]
         base_name = os.path.basename(original_path)
-        skeleton_filename = f"{path_hash}_{base_name}"
+        sym_suffix = f"_{target_symbol}" if target_symbol else ""
+        skeleton_filename = f"{path_hash}{sym_suffix}_{base_name}"
         skeleton_path = os.path.join(cls.CACHE_DIR, skeleton_filename)
-        meta_path = os.path.join(cls.CACHE_DIR, f"{path_hash}_{base_name}.meta.json")
+        meta_path = os.path.join(cls.CACHE_DIR, f"{path_hash}{sym_suffix}_{base_name}.meta.json")
 
         # 1. Check incremental mtime cache
         if os.path.exists(skeleton_path) and os.path.exists(meta_path):
@@ -122,7 +124,18 @@ class Skeletonizer:
             return None, 0, 0
 
         ext = os.path.splitext(original_path)[1]
-        skeleton_content = cls.skeletonize_code(code, ext)
+        
+        # If target symbol specified, use Graph-Guided skeletonization
+        if target_symbol:
+            try:
+                from src.graph_engine import GraphEngine
+                graph, rel_path = GraphEngine.for_file(original_path)
+                graph_content = graph.graph_guided_skeletonize(original_path, target_symbol=target_symbol)
+                skeleton_content = graph_content if graph_content else cls.skeletonize_code(code, ext)
+            except Exception:
+                skeleton_content = cls.skeletonize_code(code, ext)
+        else:
+            skeleton_content = cls.skeletonize_code(code, ext)
 
         # Prefetch local dependency signatures
         from src.dependency_prefetcher import DependencyPrefetcher
@@ -134,13 +147,20 @@ class Skeletonizer:
         if skel_tokens >= orig_tokens * 0.7:
             return None, 0, 0
 
-        header_comment = (
-            f"// [TOCP AST Skeleton: {lines_count} lines folded into API signatures]\n"
-            f"// [To inspect implementation of a specific method, call read_file with StartLine/EndLine]\n\n"
-        ) if ext != ".py" else (
-            f"# [TOCP AST Skeleton: {lines_count} lines folded into API signatures]\n"
-            f"# [To inspect implementation of a specific method, call read_file with StartLine/EndLine]\n\n"
-        )
+        if target_symbol:
+            header_comment = (
+                f"// [TokenSafe Graph-Guided Skeleton for '{target_symbol}': target & 1-hop dependencies kept full]\n\n"
+            ) if ext != ".py" else (
+                f"# [TokenSafe Graph-Guided Skeleton for '{target_symbol}': target & 1-hop dependencies kept full]\n\n"
+            )
+        else:
+            header_comment = (
+                f"// [TOCP AST Skeleton: {lines_count} lines folded into API signatures]\n"
+                f"// [To inspect implementation of a specific method, call read_file with StartLine/EndLine]\n\n"
+            ) if ext != ".py" else (
+                f"# [TOCP AST Skeleton: {lines_count} lines folded into API signatures]\n"
+                f"# [To inspect implementation of a specific method, call read_file with StartLine/EndLine]\n\n"
+            )
 
         full_content = header_comment + (prefetch_block + "\n" if prefetch_block else "") + skeleton_content
 

package/src/slicer.py

@@ -91,7 +91,8 @@ class ToolSlicer:
                 "original_tokens": total_tokens,
                 "optimized_tokens": sliced_tokens,
                 "lines_total": total_lines,
-                "lines_sliced": (new_end - new_start + 1)
+                "lines_sliced": (new_end - new_start + 1),
+                "target_symbol": target_symbol
             }
             return overwrite, metrics