synapse-hub 2.2.4 → 2.4.1

package/tools/TOOLS_RUNBOOK.md

@@ -10,12 +10,18 @@
 | Practical Agent Context | Required Tool | Typical Execution Command |
 | :--- | :--- | :--- |
 | **Autonomous Bootstrap (New project / "setup project")** | `tools/setup_project.py` | `python tools/setup_project.py [target]` (or `agent-qa setup`).<br/>*Autonomous:* Detects stack, generates `PROJECT_AI_GUIDE.md`, installs `pre-push` Git hook, runs initial audit. |
+| **Prerequisites & Environment Health Diagnostic ("doctor")** | `tools/check_env.py` | `agent-qa doctor` (or `npx synapse-hub doctor`) |
+| **Visual Product Landing Page & Interactive Guide ("welcome")** | `tools/welcome_page.py` | `agent-qa welcome` (or `npx synapse-hub welcome`) |
+| **Flaky Test Detection & Quarantine Governance ("flaky")** | `tools/flaky_detector.py` | `agent-qa flaky --detect` (or `npx synapse-hub flaky`) |
+| **Executive Project Health & Quality Dashboard ("dashboard")** | `tools/dashboard_generator.py` | `agent-qa dashboard` (or `npx synapse-hub dashboard`) |
+| **Clean Uninstall of AI Bridges & Global Plugins ("uninstall")** | `tools/cli.py` | `agent-qa uninstall` (or `npx synapse-hub uninstall`) |
 | **Comprehensive Health & AST Analysis ("analyze project")** | `tools/analyze_project.py` | `python tools/analyze_project.py [target]` (or `agent-qa analyze`).<br/>*Post-Audit:* Stages, commits, and pushes `PROJECT_HEALTH_REPORT.md` & `repo_map.txt` to project Git. |
 | **Action Safety Firewall (Environment Protection)** | `tools/safety_firewall.py` | `python tools/safety_firewall.py --text "Delete" --action click` (or `agent-qa safety-check`) |
 | **API Contract Drift (Breaking Change Detection)** | `tools/api_drift_sentinel.py` | `python tools/api_drift_sentinel.py --old base.json --new curr.json` (or `agent-qa contract-drift`) |
 | **Autonomous API Fuzzing & Chaos Breaker** | `tools/api_fuzzer.py` | `agent-qa fuzz-api --base-url <url> --spec <swagger.json>` (Catches 500, DB leaks, SLA breach) |
 | **FastMCP JSON-RPC Server (Cursor/Claude/Antigravity)** | `tools/mcp_server.py` | `python tools/mcp_server.py` (or `agent-qa mcp-serve`) |
-| **AST Micro-Mutation (Assertion Quality Verification)** | `tools/micro_mutator.py` | `python tools/micro_mutator.py [target]` (or `agent-qa mutate`) |
+| **Syntactic Micro-Mutation (Assertion Quality Verification)** | `tools/micro_mutator.py` | `python tools/micro_mutator.py [target]` (or `agent-qa mutate`) |
+| **Gherkin BDD Suite Compiler (Natural-Language Ingestion, 0-token)** | `tools/gherkin_suite.py` | `python tools/gherkin_suite.py tests/bdd/` (or `agent-qa gherkin`; `--emit-ir` for Universal IR) |
 | **Self-Healing PR Automator (Trace & Visual Diff Proof)** | `tools/heal_pr_automator.py` | `python tools/heal_pr_automator.py --page P.groovy --old "//a" --new "//b" --trace-zip trace.zip` (or `agent-qa heal-pr`) |
 | **Duration-Balanced Matrix Sharder (CI/CD Load Balancing)** | `tools/matrix_sharder.py` | `python tools/matrix_sharder.py [target] --shards 4` (or `agent-qa shard`) |
 | **Enterprise ALM & TMS Sync Bridge (Jira/Xray/TestRail)** | `tools/tms_sync_bridge.py` | `python tools/tms_sync_bridge.py pull PROJ-1042` / `report-bug` |
@@ -27,21 +33,25 @@
 | **Pre-Commit / Completing Task** | `tools/verify_all.py` | `python tools/verify_all.py` |
 | **After creating/editing Test Script (Fake-Pass scan)**| `tools/infer_linter.py` | `python tools/infer_linter.py` |
 | **After modifying Page Class (Impact Analysis)** | `tools/test_impact.py` | `python tools/test_impact.py --git-diff` |
-| **When Test FAILS (Pinpoint line & error in 0.1s)** | `tools/pinpoint_failure.py` | `python tools/pinpoint_failure.py` |
+| **When Test FAILS (Pinpoint line & error in 0.1s)** | `tools/pinpoint_failure.py` | `python tools/pinpoint_failure.py <report.xml>` (or `agent-qa pinpoint-failure report.xml`) |
 | **When CLI/Gradle logs are verbose (Observation Masking)**| `tools/distill_log.py` | `python tools/distill_log.py <path_to_log>` |
 | **When encountering UI error / Overlay / Stale Element**| `tools/cache_resolver.py` | `python tools/cache_resolver.py query "<error_msg>"` |
 | **Before authoring test for Page/Flow** | `tools/cache_resolver.py` | `python tools/cache_resolver.py get-lessons --context "<page>"` (or `agent-qa heal get-lessons --context "<page>"`) |
 | **After healing a test failure** | `tools/cache_resolver.py` | `python tools/cache_resolver.py record-lesson --context "<page>" --error "<sig>" --lesson "<summary>"` |
-| **Generating test scripts from Natural Language Story** | `tools/generate_tc_from_story.py`| `python tools/generate_tc_from_story.py "<story>"` |
+| **Generating test scripts from Natural Language Story** | `tools/generate_tc_from_story.py`| `python tools/generate_tc_from_story.py "<story>"` (or `agent-qa generate-tc story.md`) |
 | **Generating E2E matrix from OpenAPI/Swagger** | `tools/generate_api_matrix.py` | `python tools/generate_api_matrix.py --spec <swagger.json>` |
 | **Exporting API tests to Postman Collection v2.1** | `tools/export_postman_collection.py` | `agent-qa export-postman --spec <swagger.json> -o col.json` |
 | **Analyzing Newman Results & CI/CD Gatekeeper** | `tools/newman_analyzer.py` | `agent-qa analyze-newman report.json --max-failures 0` |
 | **Generating JMeter Performance Test Plan (.jmx)** | `tools/generate_jmx_plan.py` | `agent-qa generate-jmx --spec <swagger.json> --vus 100 -o plan.jmx` |
 | **Analyzing JMeter JTL & Enforcing CI/CD SLA Gate** | `tools/jtl_analyzer.py` | `agent-qa analyze-jtl results.jtl --sla-p95 500 --max-error-rate 1.0` |
 | **Full-Stack APM & Server Telemetry RCA Correlator** | `tools/telemetry_correlator.py` | `agent-qa correlate-telemetry --jtl results.jtl --server-metrics srv.csv` |
-| **Auditing Web Accessibility (WCAG 2.2)** | `tools/wcag_audit.py` | `python tools/wcag_audit.py <path_to_html_or_url>` |
+| **Auditing Web Accessibility (WCAG 2.2)** | `tools/wcag_audit.py` | `python tools/wcag_audit.py <path_to_html_or_url>` (or `agent-qa wcag-audit`) |
 | **0-Token Polyglot Test Transpilation** | `tools/omni_transpiler.py` | `agent-qa transpile <file> --to <target>` (Playwright TS, Python, Java, Katalon, Cypress) |
 | **0-Token Repository Polyglot AST Scan** | `tools/omni_transpiler.py` | `agent-qa omni-scan [path]` (Instant inventory of Pages, Locators, Tests across languages) |
+| **Sync Single-Source Agent Rules ("sync-rules")** | `tools/sync_agent_rules.py` | `agent-qa sync-rules` (or `python tools/sync_agent_rules.py --check`) |
+| **Lookup Test Case Identifier Index ("lookup-tc")** | `tools/lookup_tc.py` | `agent-qa lookup-tc [query]` (or `python tools/lookup_tc.py [query]`) |
+| **Lookup Cached Element XPaths / AOM ("lookup-xpath")** | `tools/lookup_xpath.py` | `agent-qa lookup-xpath [query]` (or `python tools/lookup_xpath.py [query]`) |
+| **Trace Data Flow & Teardown Verification ("trace-data-flow")** | `tools/trace_data_flow.py` | `agent-qa trace-data-flow ./tests` (or `python tools/trace_data_flow.py`) |
 | **Autonomous Legacy Suite Migration** | `tools/cli.py` | `agent-qa migrate --src ./katalon_project --dest ./playwright_ts` |
 | **Environment & Secret Decoupling Engine** | `tools/config_decoupler.py` | `agent-qa decouple-config [target] --fix` (Extracts env.default.json & .env.example) |
 | **Single Portable Binary Distribution** | `scripts/package_dist.py` | `python scripts/package_dist.py --binary` (Builds standalone omni-qc.exe) |
@@ -50,13 +60,21 @@
 | **Smart Visual Masking (Anti-Flake)** | `tools/smart_visual_masker.py` | `agent-qa visual-mask --playwright-snippet` |
 | **CI/CD Silent Self-Healing Hook & Auto-PR** | `tools/ci_healing_hook.py` | `agent-qa ci-hook --file <f> --old-loc <old> --new-loc <new>` |
 | **Checking DB data leaks (Taint Analysis)** | `tools/trace_data_flow.py` | `python tools/trace_data_flow.py` |
-| **Detecting Canvas / GIS Map visual regression** | `tools/visual_diff_canvas.py` | `python tools/visual_diff_canvas.py --baseline <b> --actual <a>` |
+| **Detecting Canvas / GIS Map visual regression** | `tools/visual_diff_canvas.py` | `python tools/visual_diff_canvas.py compare <b> <a> --diff <d>` (or `agent-qa canvas-diff`) |
+| **Universal Release Version Synchronization Audit** | `tools/check_version_sync.py` | `python tools/check_version_sync.py` (or `agent-qa check-version`) |
+| **Groovy Scripts & Keywords Syntax Pre-check** | `tools/validate_groovy_scripts.py` | `python tools/validate_groovy_scripts.py` (or `agent-qa validate-groovy`) |
+| **Model Context Protocol (MCP) Excel Server** | `tools/mcp_excel_server.py` | `python tools/mcp_excel_server.py` (or `agent-qa mcp-excel`) |
+| **3-Layer Heuristic Locator Matcher (0-Token Recovery)** | `tools/heuristic_locator_matcher.py` | `python tools/heuristic_locator_matcher.py` (Internal autonomous fallback engine) |
+| **Output Formatter & Exit Code Spec (NO_COLOR standard)** | `tools/output_formatter.py` | `from output_formatter import is_color_enabled, EXIT_SUCCESS` |
 | **Canary Self-Healing Audit** | `tools/agent_canary.py` | `python tools/agent_canary.py --run` |
 | **Lookup XPath Locator in cached memory** | `tools/lookup_xpath.py` | `python tools/lookup_xpath.py "<keyword>"` |
 | **Lookup Test Case metadata** | `tools/lookup_tc.py` | `python tools/lookup_tc.py "<keyword_or_id>"` |
 | **Linting Markdown documentation quality** | `tools/lint_ai_docs.py` | `python tools/lint_ai_docs.py` |
 | **Auditing AI Agent Skills & MCP Security** | `tools/skillspector.py` | `python tools/skillspector.py [path]` (or `agent-qa skillspector [path]` / `npx synapse-hub skillspector`) |
 | **Author Provenance & Anti-Tamper Integrity Guard** | `tools/author_integrity.py` | `python tools/author_integrity.py` (or `agent-qa verify-author` / `verify_all Gate 0`) |
+| **Cross-Platform Token & Cost Auditor (Antigravity / Cursor / Claude)** | `tools/count_tokens.py` | `python tools/count_tokens.py` (or `--platform cursor` / `--platform all --list` / `--file <path>`) |
+| **Standalone Executive HTML Dashboard Generator** | `tools/dashboard_generator.py` | `python tools/dashboard_generator.py` (or `agent-qa dashboard [--open]`) |
+| **Real-Time Incremental Watch Mode Sentinel** | `tools/watch_mode.py` | `python tools/watch_mode.py` (or `agent-qa watch [--once]`) |
 | **Upstream Version Check & 1-Click Self-Update** | `tools/update_sentinel.py` | `python tools/update_sentinel.py --check / --update` (or `agent-qa update` / `npx synapse-hub update`) |
 
 ---
@@ -108,7 +126,7 @@ agent-qa update
 ---
 
 ### 3. `tools/verify_all.py`
-- **Purpose:** Supreme Definition of Done (DoD) verification gate running all 8 Quality Gates (including AST Micro-Mutation >= 80%) prior to completing tasks or git commits. Supports dual operational modes (`hub` vs `target`) and dynamic target project resolution.
+- **Purpose:** Supreme Definition of Done (DoD) verification gate running all 9 Quality Gates (including Syntactic Micro-Mutation >= 80%) prior to completing tasks or git commits. Supports dual operational modes (`hub` vs `target`) and dynamic target project resolution.
 - **CLI Syntax:**
   ```bash
   # Auto-detection (automatically targets CWD if inside a test project, otherwise falls back to QA Hub)
@@ -190,7 +208,7 @@ agent-qa update
 ---
 
 ### 11. `tools/analyze_project.py`
-- **Purpose:** Comprehensive 5-in-1 Project Health & AST Intelligence Suite. Aggregates environment checks (`check_env`), Page Class AST mapping (`repo_map`), Static Defect Sentinel (`infer_linter`), Teardown Data Flow (`trace_data_flow`), and 8 Quality Gates (`verify_all`). Generates `reports/PROJECT_HEALTH_REPORT.md` and synchronizes all AI data context in < 1 second.
+- **Purpose:** Comprehensive 5-in-1 Project Health & AST Intelligence Suite. Aggregates environment checks (`check_env`), Page Class AST mapping (`repo_map`), Static Defect Sentinel (`infer_linter`), Teardown Data Flow (`trace_data_flow`), and 9 Quality Gates (`verify_all`). Generates `reports/PROJECT_HEALTH_REPORT.md` and synchronizes all AI data context in < 1 second.
 - **Trigger:** Whenever user says: "analyze project", "re-analyze project", "audit project", or during initial project onboarding.
 - **CLI Syntax:**
   ```bash
@@ -208,23 +226,23 @@ agent-qa update
 ---
 
 ### 12. `tools/tms_sync_bridge.py`
-- **Purpose:** Bi-directional Enterprise ALM Bridge connecting autonomous agents with Jira, Xray, and TestRail. Pulls Given-When-Then Acceptance Criteria from User Stories to seed tests, and automatically creates Bug Tickets with complete reproduction steps and screenshot attachments upon test failure.
+- **Purpose:** Bi-directional Enterprise ALM Bridge connecting autonomous agents with Jira REST API v3 (live mode) and TestRail/Xray (mock simulation mode). Pulls Given-When-Then Acceptance Criteria from User Stories to seed tests, and automatically creates Bug Tickets with complete reproduction steps and screenshot attachments upon test failure.
 - **CLI Syntax:**
   ```bash
   # Pull Acceptance Criteria from Jira Story
   python tools/tms_sync_bridge.py pull PROJ-1042
 
-  # Create Bug Ticket with repro steps and failure screenshots
+  # Create Bug Ticket with repro steps and failure screenshots (Jira live, or Mock preview)
   python tools/tms_sync_bridge.py report-bug --project BILLING --tc-id TC-01 --summary "Payment failed" --error "Timeout" --screenshot "Screenshots/FAILED_TC-01.png"
 
-  # Sync execution batch to Xray Test Plan
+  # Sync execution batch (mock simulation / live Jira)
   python tools/tms_sync_bridge.py sync-run --plan-key XRAY-PLAN-1 --json
   ```
 
 ---
 
 ### 13. `tools/db_sandbox.py`
-- **Purpose:** Zero-Pollution Database Sandbox and Ephemeral Teardown Engine. Takes pristine database baseline snapshots, instantly restores clean states (< 0.1s), runs tests inside transactional savepoints (automatic rollback), and audits/purges orphan test data junk.
+- **Purpose:** Zero-Pollution Database Sandbox and Ephemeral Teardown Engine. Takes pristine database baseline snapshots, instantly restores clean states (< 0.1s), runs tests inside transactional savepoints (automatic rollback), and safely audits/purges orphan test data junk with literal prefix matching (escaped SQL wildcards) and dry-run preview.
 - **CLI Syntax:**
   ```bash
   # Snapshot database before suite execution
@@ -233,7 +251,12 @@ agent-qa update
   # Restore pristine clean database after suite execution
   python tools/db_sandbox.py restore --id baseline
 
-  # Execute SQL statements inside an isolated transaction savepoint (auto-rollback)
+  # Preview orphan test junk without deleting (Dry-Run)
+  python tools/db_sandbox.py audit --dry-run
+
+  # Purge orphan test records matching literal prefixes (AUTO_, TEST_, TEMP_)
+  python tools/db_sandbox.py audit
+  ```
   python tools/db_sandbox.py rollback-test
 
   # Audit database for orphan test junk and purge
@@ -397,164 +420,108 @@ agent-qa update
 
 ---
 
-### 24. `tools/telemetry_correlator.py`
-- **Purpose:** Full-Stack APM & Server Telemetry Performance Correlator. Performs time-aligned Pearson correlation between Client-Side perceived response times (`.jtl`) and Server-Side infrastructure metrics (CPU, RAM, Database Connection Pool, Disk I/O). Automatically isolates bottlenecks and produces Root Cause Analysis (RCA) diagnostic reports.
+### 36. `tools/author_integrity.py` (Author Provenance & Anti-Tamper Integrity Guard)
+- **Purpose:** Cryptographic and textual provenance validator enforcing the mandatory author attribution condition of the MIT License:
+  *"The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software."*
+  Protects original creator **Thế Vị (@TeeVee998)** against unauthorized author stripping or copyright tampering across `LICENSE`, `package.json`, `README.md`, and `pyproject.toml`.
+- **Trigger Condition:** Runs autonomously as **Gate 0** in `tools/verify_all.py`, pre-dispatch in `agent-qa` CLI, or on-demand via `agent-qa verify-author`.
 - **CLI Syntax:**
   ```bash
-  # Correlate client JTL latency with server infrastructure telemetry
-  agent-qa correlate-telemetry --jtl results.jtl --server-metrics server_metrics.csv --markdown rca_report.md
+  # 1. Verify author attribution and provenance
+  python tools/author_integrity.py
+  agent-qa verify-author
 
-  # Dry-run sample correlation verification
-  agent-qa correlate-telemetry --sample
+  # 2. Enforced autonomously during Quality Gate verification
+  python tools/verify_all.py
+  agent-qa verify
   ```
 
 ---
 
-### 25. `tools/skillspector.py` (AI Agent Skill & MCP Security Sentinel)
-- **Purpose:** Autonomous security vulnerability and supply-chain auditor for AI Agent skills, prompt instructions, MCP tool configurations, and bundled automation scripts. Synthesized from **[NVIDIA/SkillSpector](https://github.com/NVIDIA/SkillSpector)** (Apache 2.0). Features 71 detection vectors across 17 categories, the NVIDIA Prohibition Context Engine to eliminate false positives in defensive rules, and multi-format outputs (Terminal, JSON, Markdown, SARIF 2.1.0).
-- **Threat Categories Covered:**
-  - Prompt Injection (`P1`, `P2`, `P3`, `P4`, `P9`)
-  - Data Exfiltration & Credential Harvesting (`E1`–`E5`)
-  - Privilege Escalation & Container Escapes (`PE1`–`PE5`)
-  - Agent Configuration Snooping (`AS1`–`AS3` targeting `~/.claude`, `~/.gemini`, `mcp.json`)
-  - System Prompt Leakage (`P6`–`P8`)
-  - Anti-Refusal Statements & Jailbreaks (`AR1`–`AR3`)
-  - MCP Tool Poisoning & Unicode Homoglyphs (`TP1`–`TP4`)
-  - MCP Least Privilege (`LP1`–`LP4`)
-  - Behavioral AST & Dangerous Deserialization (`AST1`–`AST10`)
-  - Supply Chain & SSRF (`SC1`–`SC2`, `SSRF1`–`SSRF2`)
+### 37. `tools/md_to_xlsx.py` (Enterprise Markdown-to-Excel Converter)
+- **Purpose:** Parses Markdown Test Case tables and converts them into professional, styled Excel workbooks (`.xlsx`) with Navy Blue headers, frozen header panes (`A2`), auto-filters, color-coded badges for Risk Level (High/Med/Low) and Priority (Critical/High/Med/Low), and multi-line wrapping.
 - **CLI Syntax:**
   ```bash
-  # 1. Audit a skill directory or file with rich terminal output
-  python tools/skillspector.py .agents/skills/my-skill/
-  agent-qa skillspector .agents/skills/my-skill/
-  npx synapse-hub skillspector .agents/skills/my-skill/
+  # 1. Convert markdown test cases to styled Excel (.xlsx)
+  agent-qa export-excel test_cases_crm.md
 
-  # 2. Output SARIF 2.1.0 for GitHub Security tab integration
-  python tools/skillspector.py .agents/skills/ --format sarif --output reports/skillspector.sarif
+  # 2. Specify custom output path and sheet title
+  agent-qa export-excel test_cases_crm.md -o CRM_TestCases_v1.xlsx --sheet-name "CRM Login"
 
-  # 3. Output JSON for CI/CD automated policy gate
-  python tools/skillspector.py .agents/skills/ --format json --output reports/skillspector.json
-
-  # 4. Strict CI gate: exit code 1 if any CRITICAL or DO_NOT_INSTALL findings exist
-  python tools/skillspector.py .agents/skills/ --strict
+  # 3. Direct python execution
+  python3 tools/md_to_xlsx.py path/to/cases.md -o export.xlsx
   ```
 
 ---
 
-### 26. `tools/newman_analyzer.py` (Newman CI/CD SLA Quality Gatekeeper)
-- **Purpose:** Postman / Newman Automated Test Results Analyzer & CI/CD Gatekeeper. Ingests Newman JSON reports (`newman run -r json`), parses total requests, triages failed assertions with root causes, checks average latency SLA, and enforces deterministic exit code `0` (Pass) vs `1` (Fail) to prevent broken API contracts from deploying.
+### 38. `tools/count_tokens.py` (Cross-Platform Token & Cost Auditor)
+- **Purpose:** Audits and calculates token usage (Uncached Input, KV Cache Read, and Output/Thinking tokens) and estimated API costs across **Google Antigravity, Cursor Agent, and Claude Code**. Supports turn-by-turn breakdown, per-prompt profiling, multi-client session discovery, and cache hit rate tracking.
+- **Trigger Condition:** On-demand after completing a task, turn, or test run to monitor context efficiency, detect token bloat, or calculate LLM cost across any supported AI client.
 - **CLI Syntax:**
   ```bash
-  # 1. Execute Newman with JSON report export
-  newman run collection.json -e env.json -r cli,json --reporter-json-export newman_report.json
+  # 1. Audit active Antigravity session
+  agent-qa tokens
+  python3 tools/count_tokens.py
 
-  # 2. Enforce CI/CD Quality Gate (Exit code 0 on Pass, 1 on Fail)
-  agent-qa analyze-newman newman_report.json --max-failures 0 --sla-avg 500
+  # 2. Audit Cursor Agent sessions (parses ~/.cursor/projects/*/agent-transcripts/*/*.jsonl)
+  python3 tools/count_tokens.py --platform cursor
+  python3 tools/count_tokens.py --platform cursor --last-task
+  python3 tools/count_tokens.py --platform cursor --turns
 
-  # 3. Export Pull Request Markdown report & JSON metrics
-  agent-qa analyze-newman newman_report.json --markdown pr_api_report.md --json api_metrics.json
+  # 3. List recent sessions across all platforms (Antigravity, Cursor, Claude)
+  python3 tools/count_tokens.py --platform all --list
 
-  # 4. Dry-run sample benchmark verification
-  agent-qa analyze-newman --sample
-  ```
+  # 4. Direct audit of any transcript file with auto-format detection
+  python3 tools/count_tokens.py --file /path/to/transcript.jsonl
 
----
+  # 5. Audit current active session (Antigravity)
+  agent-qa tokens --current
 
-### 27. `tools/auto_heal.py` & `tools/heuristic_locator_matcher.py` (Closed-Loop Test Failure Diagnosis & Locator Healing)
-- **Purpose:** In-place autonomous test failure healer powered by `tools/heuristic_locator_matcher.py`. Correlates JUnit XML failures and screenshots (`Screenshots/FAILED_*.png`) with live DOM state, computes semantic element diffs via Role/Label/TestId hierarchy, and patches broken Page Class locators without full rerun.
-- **CLI Syntax:**
-  ```bash
-  python tools/auto_heal.py
-  agent-qa auto-heal
-  ```
+  # 6. Show 5-hour and 7-day rolling window quota usage
+  agent-qa tokens --rolling
 
----
+  # 7. Benchmark Hub vs. Vanilla token & cost savings
+  agent-qa tokens --savings
 
-### 28. `tools/flaky_detector.py` (Flaky Test Sentinel & Quarantine Lifecycle)
-- **Purpose:** Detects non-deterministic test flakiness across test suites, calculates historical flakiness scores, and manages automated test quarantine lifecycles to protect CI/CD pipelines from false alarms.
-- **CLI Syntax:**
-  ```bash
-  python tools/flaky_detector.py --scan Reports/
-  agent-qa flaky --scan Reports/
-  ```
+  # 8. Calculate cost with specific pricing model (gemini-flash, gemini-pro, claude-sonnet, claude-opus, gpt-4o, gpt-4o-mini)
+  agent-qa tokens --pricing claude-sonnet
 
----
-
-### 29. `tools/browser_helpers.js` (In-Browser Live AOM & Safe Interaction Prober)
-- **Purpose:** Client-side JavaScript helper injected into headless Playwright/Chrome sessions. Provides `window.__helper` and `window.qa` APIs: `qa.getCompactAOM()` (extracts interactive nodes sub-200ms under 500 tokens), safe click overlay bypassing for PrimeNG/AntD backdrops, and live selector hit-rate verification.
-- **Usage:** Injected automatically by `live-explorer` subagent and Playwright test fixtures.
-
----
-
-### 30. `tools/project_state.py` (Compaction Anchoring & Persistent State Store)
-- **Purpose:** Persists mission-critical project state (active test cases, defect registers, test data tracking) into disk-anchored files (`PROJECT_STATE.md` and `.project_state.properties`). Prevents loss of context during Antigravity automated context compaction.
-- **Usage:** Autonomously invoked by the Lead Orchestrator agent across turn transitions.
-
----
-
-### 31. `tools/universal_ir.py`, `tools/omni_parser.py`, `tools/omni_emitter.py`
-- **Purpose:** Universal Intermediate Representation (IR) engine powering 0-token polyglot test transpilation (`agent-qa transpile`). Parses test scripts from Groovy, TypeScript, Python, or Java into a framework-agnostic AST and emits clean, idiomatic code for target test frameworks.
-- **CLI Syntax:**
-  ```bash
-  agent-qa transpile Scripts/TC_Login.groovy --to playwright-ts
+  # 9. Output machine-readable JSON
+  agent-qa tokens --json
   ```
 
 ---
 
-### 32. `tools/check_env.py` (Prerequisites & Toolchain Diagnostic Checker)
-- **Purpose:** Rapid diagnostic tool that checks required local execution toolchains: Python 3.9+, Node.js 18+, Java JDK 11+, Playwright browser binaries, Git, and Docker.
+### 39. `tools/dashboard_generator.py` (Standalone Executive HTML Dashboard)
+- **Purpose:** Compiles project health metrics, 9 Quality Gates status, AST repository maps, benchmark results, and skills inventory into a single, dependency-free, modern HTML dashboard (`PROJECT_DASHBOARD.html`).
+- **Trigger Condition:** On-demand when presenting project status to stakeholders, QA leads, or managers, or after completing project analysis/audits.
 - **CLI Syntax:**
   ```bash
-  python tools/check_env.py
-  ```
+  # 1. Generate dashboard for current project
+  agent-qa dashboard
+  python3 tools/dashboard_generator.py
 
----
+  # 2. Generate and open directly in browser
+  agent-qa dashboard --open
 
-### 33. `tools/git_pre_commit_guard.py` (Zero-Leakage Git Pre-Commit Hook)
-- **Purpose:** Git hook gatekeeper preventing accidental commits of UTF-8 BOM characters, hardcoded secrets/API keys, absolute machine paths, or temporary dump files into git repositories.
-- **CLI Syntax:**
-  ```bash
-  python tools/git_pre_commit_guard.py
+  # 3. Output to custom path
+  agent-qa dashboard -o reports/custom_dashboard.html
   ```
 
 ---
 
-### 34. `tools/validate_groovy_scripts.py` (Katalon / Groovy AST Syntax Guard)
-- **Purpose:** Static verification scanner for Groovy and Katalon test scripts. Ensures 100% adherence to Clean POM Flat Architecture, zero raw XPaths in test cases, and valid import signatures.
+### 40. `tools/watch_mode.py` (Real-Time Incremental Watch Mode Sentinel)
+- **Purpose:** Continuously monitors repository files for code changes and triggers near-instant (< 100ms) incremental verification (UTF-8 No BOM, absolute machine paths, AST Meta Infer-style fake-pass checks) with an interactive terminal Heads-Up Display (HUD).
+- **Trigger Condition:** During active test development or refactoring sessions to get immediate feedback without manually running commands.
 - **CLI Syntax:**
   ```bash
-  python tools/validate_groovy_scripts.py
-  ```
+  # 1. Start real-time watch mode on current directory
+  agent-qa watch
+  python3 tools/watch_mode.py
 
----
-
-### 35. Platform Scripts & Automation Utilities
-- `tools/verify_all.sh`: macOS / Linux Bash equivalent for the 8 Quality Gates DoD verification.
-- `tools/generate_allure_report.ps1`: Automated generation and serving of Allure test execution dashboards.
-- `tools/generate_test_reports.ps1`: Automated consolidation of polyglot test reports into centralized Markdown summaries.
-- `tools/mcp_excel_server.ps1`: Specialized Model Context Protocol (MCP) server for structured Excel data interaction.
-- `tools/e2e_flow_prober.ps1`: Automated E2E smoke flow prober across target web environments.
-- `tools/bump_version.py`: Automated SemVer version bumper for Synapse-Hub releases.
-
----
-
-### 36. `tools/author_integrity.py` (Author Provenance & Anti-Tamper Integrity Guard)
-- **Purpose:** Cryptographic and textual provenance validator enforcing the mandatory author attribution condition of the MIT License:
-  *"The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software."*
-  Protects original creator **Thế Vị (@TeeVee998)** against unauthorized author stripping or copyright tampering across `LICENSE`, `package.json`, `README.md`, and `pyproject.toml`.
-- **Trigger Condition:** Runs autonomously as **Gate 0** in `tools/verify_all.py`, pre-dispatch in `agent-qa` CLI, or on-demand via `agent-qa verify-author`.
-- **CLI Syntax:**
-  ```bash
-  # 1. Verify author attribution and provenance
-  python tools/author_integrity.py
-  agent-qa verify-author
+  # 2. Watch with custom debounce interval
+  agent-qa watch --debounce 0.5
 
-  # 2. Enforced autonomously during Quality Gate verification
-  python tools/verify_all.py
-  agent-qa verify
+  # 3. Run incremental scan once on all files and exit (ideal for CI/CD pre-commit hooks)
+  agent-qa watch --once
   ```
-
-
-
-

package/tools/__init__.py

@@ -0,0 +1,26 @@
+"""
+Synapse Hub — Enterprise AI Agent Quality Engineering & Automated Testing Tooling Suite.
+========================================================================================
+Author: Thế Vị (@TeeVee998)
+Repository: https://github.com/TeeVee998/Synapse-Hub
+License: MIT
+"""
+
+__version__ = "2.4.1"
+__author__ = "Thế Vị (@TeeVee998)"
+
+__all__ = [
+    "verify_all",
+    "infer_linter",
+    "micro_mutator",
+    "setup_project",
+    "analyze_project",
+    "distill_log",
+    "repo_map",
+    "cache_resolver",
+    "check_env",
+    "api_fuzzer",
+    "test_impact",
+    "watch_mode",
+    "author_integrity",
+]