feat(gtm): finalize sales intelligence, comprehensive documentation audit, and future-proof hardening

Author: darestack

.gitignore

@@ -156,8 +156,7 @@ cython_debug/
 *.sqlite
 .ruff_cache/
 brain/
-docs/reference/prospecting_log.md
-docs/reference/demo_script.md
+seed_log.txt
 # Ignore reports content but keep the folder
 reports/*
 !reports/.gitkeep

README.md

@@ -13,7 +13,7 @@
 
 > **"One Engine. Two Worlds. Total Accountability."**
 
-[**Full Documentation 📚**](https://daretechie.github.io/CommitVigil/) | [**Live Site 🌐**](https://daretechie.github.io/CommitVigil/) | [**Safety Validation Report 🛡️**](https://daretechie.github.io/CommitVigil/validation/safety_validation_report/) | [**Manager Feedback Guide 🎮**](docs/guides/feedback_loop.md)
+[**Full Documentation 📚**](https://daretechie.github.io/CommitVigil/) | [**Live Site 🌐**](https://daretechie.github.io/CommitVigil/) | [**Safety Validation Report 🛡️**](https://daretechie.github.io/CommitVigil/validation/safety_validation_report/) | [**Manager Feedback Guide 🎮**](docs/guides/feedback_loop.md) | [**Integration Guide 🔌**](docs/guides/integrations.md)
 
 ---
 
@@ -52,6 +52,12 @@ Every commitment—whether from Slack or a Git Commit—passes through a determi
 3.  **Language & Culture Router**: Identifies the primary language and selects the appropriate cultural persona.
 4.  **Safety Supervisor (`Overwatch`)**: Audits final communications for HR/Legal ethics and **Industry-Specific Semantic Compliance**.
 
+### 💼 Phase 6: Enterprise Sales Intelligence (New)
+Transform your security audit into a revenue engine.
+- **Automated Prospecting**: The `ProspectingScout` agent generates realistic "Drift Scenarios" for demos based on industry (e.g., Finance, Energy).
+- **Multi-Currency ROI**: Interactive calculator for predicting savings in USD, EUR, and GBP.
+- **Executive Briefs**: Generates premium HTML one-pagers for C-Level meetings.
+
 ---
 
 ## 🛠️ Core Tech Stack

docs/adr/ADR-002-Sales-Intelligence-Layer.md

@@ -0,0 +1,19 @@
+# ADR-002: Sales Intelligence & Prospecting Layer
+
+**Date**: 2026-01-30  
+**Status**: Accepted  
+**Context**:  
+As CommitVigil evolves into an enterprise GTM tool, there is a need for a layer that simulates findinds for demos and calculates ROI without contaminating the core, forensic accountability engine.
+
+**Decision**:  
+We will implement a dedicated `Sales Intelligence` layer consisting of the `ProspectingScout` agent and a specialized `sales` API router.
+
+**Rationale**:  
+1. **Separation of Concerns**: Core agents (`brain.py`, `safety.py`) focus on real-world transaction analysis. The `ProspectingScout` focuses on simulation and synthetic scenario generation.
+2. **Performance**: Sales-specific endpoints are treated as "high-intensity" but lower frequency, allowing for independent rate-limiting and scaling tiers.
+3. **Multi-Currency Support**: By normalizing ROI math to USD in the core `reporting.py` but and converting at the edge in `sales.py`, we maintain architectural simplicity while serving global markets.
+
+**Consequences**:  
+- All Sales-related logic must reside in `src.api.v1.sales` or `src.agents.prospector`.
+- Core reporting utilities in `reporting.py` are extended to support sales outputs (e.g., Executive Briefs) but remain usable by the standard audit flow.
+- Increased token usage for sales demos is managed via a dedicated 10 req/min rate limit.

docs/guides/feedback_loop.md

@@ -9,7 +9,7 @@ CommitGuard AI's "Safety Supervisor" monitors all communications. Sometimes, the
 3. The manager submits feedback (Accept, Reject, or Modify).
 
 ## API Integration
-To submit feedback via the API, use the `POST /api/v1/feedback/safety` endpoint.
+To submit feedback via the API, use the `POST /api/v1/safety/feedback` endpoint.
 
 ### Example Request
 ```json

docs/guides/integrations.md

@@ -0,0 +1,53 @@
+# Integration & Pluggability Guide 🔌
+
+CommitVigil is designed with a **"Source-Agnostic"** core. While Slack and Git are the primary supported platforms, the system can be easily extended to any tool that supports Webhooks or REST APIs.
+
+---
+
+## 1. Inbound Ingestion (Incoming Data)
+The system can ingest commitments from any source via the `/api/v1/ingest/raw` endpoint.
+
+### Examples:
+*   **Jira**: Set up a Jira Webhook that triggers on "Issue Commented" and send the comment body to CommitVigil.
+*   **Linear**: Sync Linear comments to track engineering promises made in task descriptions.
+*   **Calendly**: Map calendar bookings to commitments (e.g., "I will have the demo ready by the meeting time").
+
+### How to Implement:
+Simply call the endpoint with the raw text and a `user_id`:
+```bash
+curl -X POST "$API_URL/api/v1/ingest/raw?user_id=john_dev&raw_text=I promise to fix the DB by Friday"
+```
+
+---
+
+## 2. Outbound Notifications (Interventions)
+Currently, CommitVigil uses the `SlackConnector` for follow-ups. However, the architecture is modular.
+
+### Adding a New Tool (e.g., MS Teams or Discord):
+1.  **Create a Connector**: Add a new file in `src/core/` (e.g., `teams.py`) following the `SlackConnector` pattern.
+2.  **Update the Worker**: In `src/worker.py`, update the `send_follow_up` function to route messages to your new connector:
+
+```python
+# src/worker.py
+async def send_follow_up(user_id: str, message: str, slack_id: str | None = None, teams_webhook: str | None = None):
+    if teams_webhook:
+        await TeamsConnector.send(message, teams_webhook)
+    else:
+        await SlackConnector.send_notification(message, slack_id)
+```
+
+---
+
+## 3. The "Tool-Agnostic" Brain
+The core reasoning engine (`CommitVigilBrain`) never interacts with Slack or Git directly. It processes **semantic commitments** and returns **behavioral decisions**. This means you can swap the entire communication layer without touching the AI logic.
+
+### Supported Data Formats:
+*   **JSON API**: For direct application integration.
+*   **Markdown**: For documentation and PR reviews.
+*   **HTML**: For executive reporting.
+
+---
+
+## 🚀 Future Golden Paths
+*   **Jira Adapter**: Automatically close Jira tickets when the "Fulfillment Analysis" confirms the task is done in Git.
+*   **Email Gateway**: Send "Professional Nudges" via SendGrid for high-context executive summaries.

docs/guides/managers.md

@@ -51,3 +51,9 @@ Managers can now generate high-value, professional audit reports for their team
 
 > [!TIP]
 > Use the **Markdown** format for embedding audit summaries directly into GitHub Pull Request comments for collective accountability.
+
+## 6. Sales Enablement & ROI 💰
+For leaders justifying the budget for CommitVigil, use the **ROI Calculator**:
+
+*   **Projected Savings**: Calculates recovered developer hours based on a 40% reduction in "Engagement Slippage".
+*   **Executive Briefs**: Generate a one-page HTML summary for your CFO using the `/sales/executive-brief` endpoint.

docs/guides/production.md

@@ -14,7 +14,7 @@ For large-scale teams, we separate the **Ingestion Layer** (API) from the **Proc
 
 ## ☸️ Kubernetes Orchestration
 
-We provide production-ready K8s manifests in [`infra/k8s/`](file:///home/daretechie/DevProject/GitHub/CommitVigil-AI/infra/k8s/).
+We provide production-ready K8s manifests in [`infra/k8s/`](file:///home/daretechie/DevProject/GitHub/CommitGuard-AI/infra/k8s/).
 
 ### Key Scaling Features:
 - **Replica Sets**: Run multiple API instances to handle high traffic.

docs/guides/quickstart.md

@@ -31,6 +31,23 @@ docker compose up --build
 
 ---
 
+## 🎮 Interactive Demos
+See the system in action with these pre-configured scenarios:
+
+### 1. High-Stakes Accountability
+Simulates a manager-developer interaction with tone adaptation and safety checks.
+```bash
+./scripts/demo.sh
+```
+
+### 2. Sales Intelligence & ROI
+Simulates a prospecting flow with automated scenario generation and multi-currency ROI.
+```bash
+./scripts/demo_sales.sh
+```
+
+---
+
 ## 🧪 Quality and Stability
 CommitVigil enforces military-grade engineering standards:
 - **Mock Mode**: Set `LLM_PROVIDER="mock"` in `.env` to run the entire system with zero token cost.

docs/guides/sales.md

@@ -0,0 +1,51 @@
+# Sales Enablement Guide 🚀
+
+CommitVigil isn't just a tool; it's a platform with built-in sales intelligence to help you close enterprise deals.
+
+---
+
+## 1. The "Drift Scenario" Generator
+Prospects often don't realize how much "Engagement Slippage" costs them. Use the **Prospecting Agent** to generate industry-specific examples of failed commitments.
+
+### Usage
+```bash
+curl -X POST "$API_URL/sales/prospect?company_name=AcmeCorp&industry=healthcare"
+```
+
+### Output Value
+*   **Realistic Scenarios**: The AI will generate examples like *"Lead Researcher promised safety data by Friday but no commit was found."*
+*   **Targeted Role**: It automatically targets the persona (e.g., CTO, VP Eng) relevant to that industry.
+
+---
+
+## 2. Multi-Currency ROI Calculator
+Close deals faster by showing the math. The calculator supports `USD`, `EUR`, and `GBP`.
+
+### Usage
+```bash
+curl -X GET "$API_URL/sales/roi-calculator?team_size=50&avg_salary=120000&currency=EUR"
+```
+
+### Key Metrics
+*   **Annual Savings**: The raw cash value of recovered time.
+*   **Payback Period**: Usually < 1 month for teams > 10.
+*   **Efficiency Gain**: The % improvement in delivery velocity.
+
+---
+
+## 3. The Executive Brief (The "Closer")
+Generate a premium, glassmorphic HTML one-pager to send as a follow-up after your demo.
+
+### Steps
+1.  Run the generation command:
+    ```bash
+    curl -X POST "$API_URL/sales/executive-brief?company_name=BigBank..." > brief.html
+    ```
+2.  Print to PDF.
+3.  Email to the Champion/Decision Maker.
+
+---
+
+## 🔒 Internal Use Only
+*   **Demo Mode**: Ensure `DEMO_MODE=false` in production to use real reasoning.
+*   **Rate Limits**: The sales endpoints are rate-limited to 10 requests/minute.

docs/index.md

@@ -25,3 +25,14 @@ CommitVigil is built on a **Decoupled Event-Driven Architecture**:
 - **Redis & ARQ**: Distributed background processing for high-volume orchestration.
 - **The Brain**: Multi-agent LLM reasoning loop.
 - **PostgreSQL**: Industrial-grade persistence with atomic row-locking for score integrity.
+- **Pluggable Connectors**: Source-agnostic design ready for Jira, MS Teams, Linear, and custom CRM integrations.
+
+---
+
+## 💰 Sales Intelligence (ROI)
+Calculate the projected savings for a prospective client.
+```bash
+curl -X 'GET' \
+  -H 'X-API-Key: YOUR_API_KEY' \
+  'http://localhost:8000/api/v1/sales/roi-calculator?team_size=50&currency=USD'
+```