docs: enhance README and blueprint with Money Heist theme (#136)

README.md

@@ -1,9 +1,8 @@
-
 <div align="center">
 
-# 🛡️ SecureFlow
+# 🎭 SecureFlow
 
-## AI-Powered GitHub Pull Request Security Scanner
+## The Digital Heist Defense System — AI-Powered GitHub Pull Request Security Scanner
 
 [![GitHub stars](https://img.shields.io/github/stars/GauravKarakoti/SecureFlow?style=for-the-badge&color=gold)](https://github.com/GauravKarakoti/SecureFlow/stargazers)
 [![GitHub forks](https://img.shields.io/github/forks/GauravKarakoti/SecureFlow?style=for-the-badge&color=blue)](https://github.com/GauravKarakoti/SecureFlow/network)
@@ -15,7 +14,8 @@
 [![Prisma](https://img.shields.io/badge/Prisma-3982CE?style=for-the-badge&logo=Prisma&logoColor=white)](https://www.prisma.io/)
 [![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-38B2AC?style=for-the-badge&logo=tailwind-css&logoColor=white)](https://tailwindcss.com/)
 
-> **Automatically detect vulnerabilities, hardcoded secrets, and code flaws before they reach production.**
+> *"In this heist, we're not stealing — we're protecting."*
+> **SecureFlow automatically detects vulnerabilities, hardcoded secrets, and code flaws before they reach production.**
 
 </div>
 
@@ -24,42 +24,48 @@
 ## 📋 Table of Contents
 <details>
 <summary><b>Click to expand</b></summary>
-- [🌟 Features](#-features)
-- [🧠 How It Works](#-how-it-works)
+
+- [🌟 The Crew's Abilities (Features)](#-the-crews-abilities-features)
+- [🧠 The Blueprint (How It Works)](#-the-blueprint-how-it-works)
 - [🛠️ Tech Stack](#️-tech-stack)
 - [📁 Project Structure](#-project-structure)
-- [🚀 Getting Started](#-getting-started)
+- [🚀 Joining the Resistance (Getting Started)](#-joining-the-resistance-getting-started)
   - [Prerequisites](#prerequisites)
   - [1. Fork & Clone](#1-fork--clone)
   - [2. Environment Variables](#2-environment-variables)
   - [3. GitHub App Setup](#3-github-app-setup)
   - [4. Database Setup](#4-database-setup)
   - [5. Run the App](#5-run-the-app)
-- [Docker Setup](#-docker-setup)
-
+- [🐳 Docker Setup](#-docker-setup)
 - [🔑 Environment Variables Reference](#-environment-variables-reference)
 - [📝 Available Scripts](#-available-scripts)
-- [🔒 Security Policies](#-security-policies)
+- [🔒 Defense Strategy (Security Policies)](#-defense-strategy-security-policies)
 - [📊 Architecture](#-architecture)
 - [🤝 Contributing](#-contributing)
 - [❓ FAQ](#-faq)
 - [📄 License](#-license)
+
 </details>
+
 ---
 
-SecureFlow integrates directly with GitHub via a GitHub App and webhooks. Every time a Pull Request is opened or updated, it extracts the code diff, runs it through Groq's LLM (Llama 3.1), and generates actionable security findings with AI-written explanations and remediation steps — all visible on a centralized dashboard.
+SecureFlow integrates directly with GitHub via a GitHub App and webhooks. Every time a Pull Request is opened or updated, **The Professor** — SecureFlow's AI mastermind — extracts the code diff, runs it through Groq's LLM (Llama 3.1), and returns actionable security findings with AI-written explanations and remediation steps, all visible on a centralized Mission Control dashboard.
+
+Think of every Pull Request as a member of the crew trying to get into **The Vault** (your codebase). The Professor checks their credentials at the door — no leaked keys, no sloppy code, no breaches on his watch.
+
+## 🌟 The Crew's Abilities (Features)
 
 ### 🤖 AI-Powered Detection
 Uses Groq's Llama 3.1 to detect hardcoded secrets, vulnerabilities, and misconfigurations in your code.
 
 ### ⚡ Real-time Scanning
-Automatically scans every opened or updated Pull Request as soon as it's created.
+Automatically scans every opened or updated Pull Request as soon as it's created — The Professor never sleeps.
 
 ### 🛡️ Smart Remediation
 Generates precise explanations and concrete code fixes for each security finding.
 
-### 📊 Centralized Dashboard
-View all your repositories, PRs, findings, and audit logs in one unified interface.
+### 📊 Mission Control Dashboard
+View all your repositories, PRs, findings, and audit logs in one unified command center.
 
 ### 💬 GitHub PR Comments
 Posts detailed security reports directly on your PRs with collapsible remediation blocks.
@@ -68,14 +74,14 @@ Posts detailed security reports directly on your PRs with collapsible remediatio
 Sets Pass/Review Required/Blocked status on PR commits for clear CI/CD integration.
 
 ### 🎯 Custom Policies
-Create, toggle, and manage security policies per user or organization.
+Create, toggle, and manage security policies per user or organization — write your own rules for the plan.
 
 ### 🚫 Smart Exclusions
 Intelligently ignores non-executable files and mock placeholders to reduce noise.
 
 ---
 
-## 🧠 How It Works
+## 🧠 The Blueprint (How It Works)
 
 ```
 Developer opens or updates a Pull Request
@@ -88,13 +94,13 @@ ArmorIQScanner sends the diff to Groq LLM with active policy context
               ↓
 LLM returns structured findings (type, severity, file, snippet)
               ↓
-For each finding → AI generates explanation + remediation steps
+For each finding → The Professor generates explanation + remediation steps
               ↓
-Findings saved to PostgreSQL via Prisma
+Findings saved to PostgreSQL via Prisma — the Vault Logs
               ↓
 Results posted as a GitHub PR comment + commit check status
               ↓
-Everything visible on the SecureFlow Dashboard
+Everything visible on the SecureFlow Mission Control Dashboard
 ```
 
 ### What Gets Detected
@@ -134,7 +140,7 @@ secureflow/
 ├── src/
 │   ├── ai/
 │   │   └── flows/
-│   │       └── developer-receives-ai-security-explanations.ts  # Genkit AI flow
+│   │       └── developer-receives-ai-security-explanations.ts  # The Professor's Genkit AI flow
 │   │
 │   ├── app/
 │   │   ├── api/
@@ -144,10 +150,10 @@ secureflow/
 │   │   │           └── route.ts # Main webhook handler (PR scanning logic)
 │   │   │
 │   │   ├── dashboard/
-│   │   │   ├── audit/           # Audit log page
-│   │   │   ├── findings/        # Security findings page
-│   │   │   ├── policies/        # Policy management page
-│   │   │   └── page.tsx         # Main dashboard overview
+│   │   │   ├── audit/           # Vault Logs (audit log page)
+│   │   │   ├── findings/        # Breach Attempts (security findings page)
+│   │   │   ├── policies/        # Defense Strategy (policy management page)
+│   │   │   └── page.tsx         # Mission Control (main dashboard overview)
 │   │   │
 │   │   ├── login/               # Login page
 │   │   └── setup/               # GitHub App installation setup page
@@ -165,11 +171,11 @@ secureflow/
 
 ---
 
-## 🚀 Getting Started
+## 🚀 Joining the Resistance (Getting Started)
 
 ### Prerequisites
 
-Make sure you have the following installed and ready:
+Make sure you have the following installed and ready before the heist begins:
 
 - [Node.js v20+](https://nodejs.org/)
 - [PostgreSQL](https://www.postgresql.org/) (local) or a free cloud DB ([Neon](https://neon.tech) / [Supabase](https://supabase.com))
@@ -180,10 +186,14 @@ Make sure you have the following installed and ready:
 
 ### 1. Fork & Clone
 
+- Fork the repo on GitHub first, then:
 ```bash
-# Fork the repo on GitHub first, then:
 git clone https://github.com/YOUR_USERNAME/secureflow.git
+```
+```bash
 cd secureflow
+```
+```bash
 npm install
 ```
 
@@ -237,14 +247,16 @@ Then set `DATABASE_URL="postgresql://postgres:yourpassword@localhost:5432/secure
 - Create a new project and copy the connection string directly into `DATABASE_URL`
 
 **Then run:**
+- Generate Prisma Client
 ```bash
-# Generate Prisma Client
 npm run db:gen
-
-# Apply migrations (creates all tables)
+```
+- Apply migrations (creates all tables)
+```bash
 npm run db:migrate
-
-# Seed default security policy templates
+```
+- Seed default security policy templates
+```bash
 npm run db:seed
 ```
 
@@ -260,7 +272,7 @@ Open [http://localhost:9002](http://localhost:9002) in your browser.
 
 - Sign in with GitHub
 - Install the GitHub App on your repositories via the Setup page
-- Open a Pull Request on any linked repo to trigger a scan
+- Open a Pull Request on any linked repo to trigger a scan — and let The Professor take it from there
 
 **Optional — Genkit AI dev environment** (for working on AI explanation flows):
 ```bash
@@ -313,9 +325,9 @@ npm run genkit:dev
 
 ---
 
-## 🔒 Security Policies
+## 🔒 Defense Strategy (Security Policies)
 
-SecureFlow ships with pre-built policy templates that are seeded into the database. Users can toggle them on/off from the dashboard.
+SecureFlow ships with pre-built policy templates that are seeded into the database. Users can toggle them on/off from the dashboard — think of it as briefing the crew before every job.
 
 | Policy | Severity | Default |
 |--------|----------|---------|
@@ -335,59 +347,65 @@ SecureFlow ships with pre-built policy templates that are seeded into the databa
 
 The architecture follows a modern Next.js full-stack approach with real-time GitHub integration:
 
-- **Frontend**: Next.js App Router with Tailwind CSS for the dashboard
+- **Frontend**: Next.js App Router with Tailwind CSS for the Mission Control dashboard
 - **Backend**: API routes handle authentication, webhooks, and business logic
-- **AI Layer**: Groq SDK processes code diffs through Llama 3.1 model
-- **Database**: PostgreSQL with Prisma ORM for data persistence
+- **AI Layer**: Groq SDK processes code diffs through Llama 3.1 model — The Professor's brain
+- **Database**: PostgreSQL with Prisma ORM for data persistence — the Vault Logs
 - **GitHub Integration**: Octokit manages webhooks, PR comments, and checks
 
 ---
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on branching, commit messages, and the PR process.
+Every good heist needs a crew. Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on branching, commit messages, and the PR process.
 
 ```bash
 # Create a branch following the naming convention
+
+
 git checkout -b fix/your-issue-name   # bug fix
+
 git checkout -b feat/your-feature     # new feature
+
 git checkout -b docs/update-readme    # documentation
 ```
 
 Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages:
 
 ```bash
 git commit -m "fix: description of what you fixed"
+
 git commit -m "feat: description of new feature"
+
 git commit -m "docs: description of documentation change"
 ```
 
 ---
 
 ## ❓ FAQ
 
-**How does SecureFlow protect my secrets?**  
+**How does SecureFlow protect my secrets?**
 SecureFlow uses AI to detect hardcoded secrets and sensitive data in your code. It's designed to catch API keys, passwords, tokens, and other credentials that might accidentally be committed to your repository.
 
-**Can I customize the scanning rules?**  
+**Can I customize the scanning rules?**
 Yes! You can create, toggle, and manage custom policies through the dashboard. This allows you to enforce organization-specific security rules.
 
-**Is my data sent to external services?**  
+**Is my data sent to external services?**
 Your code diffs are sent to Groq's LLM service for analysis. We do not store your code or share it with third parties. The service is compliant with data protection standards.
 
-**How much does it cost to use SecureFlow?**  
+**How much does it cost to use SecureFlow?**
 SecureFlow is open-source and free to self-host. You'll need a Groq API key (free tier available) and your own PostgreSQL database.
 
 ---
 
-
-
 <div align="center">
 
 **Built with ❤️ to make every Pull Request safer.**
 
+*"The vault is empty. Zero traces left behind." — every clean audit, thanks to The Professor.*
+
 **⭐ Star us on GitHub — it helps!**
 
 [Report Bug](https://github.com/GauravKarakoti/SecureFlow/issues) · [Request Feature](https://github.com/GauravKarakoti/SecureFlow/issues) · [View Demo](https://secure-flow-six.vercel.app/)
 
-</div>
+</div>

docs/blueprint.md

@@ -1,21 +1,40 @@
 # **App Name**: SecureFlow
 
+*"In this heist, we're not stealing — we're protecting." SecureFlow casts every Pull Request as a member of the crew trying to reach The Vault (your codebase), with **The Professor** — SecureFlow's AI mastermind — checking credentials at the door before any breach gets through.*
+
 ## Core Features:
 
-- GitHub App Integration: Streamlined GitHub OAuth flow for repository selection and automated pull request webhook listeners.
-- ArmorIQ Scanner: High-fidelity security scan implementation that identifies hardcoded secrets, vulnerable dependencies, and insecure code patterns during PR cycles.
-- AI Reasoner Tool: An AI tool that applies logical reasoning to scanner findings to provide human-readable risk summaries and direct remediation advice in plain English.
-- ArmorIQ Policy Engine: Logic engine for automated risk evaluation, mapping findings to customizable policy states: Pass, Review Required, or Blocked.
-- Executive Security Dashboard: Centralized workspace featuring high-level risk trends, PR status visualizations, and active vulnerability metrics built with shadcn/ui and Recharts.
-- Audit Transparency Logs: A persistent audit trail stored in PostgreSQL for all automated security decisions, actions, and scanner results.
-- PR Status Reporter: Automated commit status updates and granular inline GitHub comments with direct feedback and action buttons.
+- **GitHub App Integration — The Inside Job**: Streamlined GitHub OAuth flow for repository selection and automated pull request webhook listeners. This is how the crew gets access to the building in the first place.
+- **ArmorIQ Scanner — The Professor's Eyes**: High-fidelity security scan implementation that identifies hardcoded secrets, vulnerable dependencies, and insecure code patterns during PR cycles.
+- **AI Reasoner Tool — The Professor's Voice**: An AI tool that applies logical reasoning to scanner findings to provide human-readable risk summaries and direct remediation advice in plain English, in-character as "The Professor."
+- **ArmorIQ Policy Engine — The Plan**: Logic engine for automated risk evaluation, mapping findings to customizable policy states: Pass, Review Required, or Blocked.
+- **Mission Control Dashboard**: Centralized workspace featuring high-level risk trends, PR status visualizations, and active vulnerability metrics built with shadcn/ui and Recharts.
+- **Vault Logs — Audit Transparency**: A persistent audit trail stored in PostgreSQL for all automated security decisions, actions, and scanner results.
+- **PR Status Reporter — The Getaway Signal**: Automated commit status updates and granular inline GitHub comments with direct feedback and action buttons.
 
 ## Style Guidelines:
 
-- Primary Color: Vibrant Deep Violet (#927BFF), providing a futuristic and high-tech feel that contrasts against deep surfaces.
-- Background Color: Deep Graphite Charcoal (#0C0B0F), a desaturated variation of the primary hue to create an immersive, distraction-free dark interface.
-- Accent Color: Electric Azure (#4D7BFF), an analogous hue that provides strong functional contrast for success states and interactive call-to-actions.
-- Font Pairing: 'Space Grotesk' (Sans-serif) for sharp, technical-feeling headlines and 'Inter' (Sans-serif) for clean, highly-readable UI controls and density-rich scan results.
-- Ultra-thin, mono-lineal strokes for icons, utilizing high-contrast borders to suggest precision and structural integrity.
-- Spacious, container-less dashboard layout with high-blur background glass effects (Glassmorphism) to define hierarchy without visual clutter.
-- Sophisticated micro-interactions using framer-motion, featuring rhythmic horizontal loaders that simulate continuous scanning pulses.
+- **Primary Color**: Heist Red (`hsl(356 96% 47%)` ≈ `#EB0514`) — the signature red of the crew's jumpsuits, used for primary actions, alerts, and the accent color throughout the app.
+- **Background Color**: Deep Cinematic Black (`hsl(0 0% 4%)` ≈ `#0A0A0A`) in dark mode — evoking the shadows of the vault. Light mode uses a crisp off-white (`hsl(0 0% 98%)`) for high-contrast daytime use.
+- **Card/Surface Color**: Slightly raised black (`hsl(0 0% 7%)` ≈ `#121212`) to separate cards and panels from the background without breaking the dark aesthetic.
+- **Font Pairing**: 'Roboto' (Sans-serif) for bold, cinematic headlines and 'Inter' (Sans-serif) for clean, highly-readable body text and UI controls.
+- **Iconography**: Ultra-thin, mono-lineal strokes for icons, utilizing high-contrast borders to suggest precision and structural integrity — every line as deliberate as the heist itself.
+- **Layout**: Spacious, container-less dashboard layout with high-blur background glass effects (Glassmorphism) to define hierarchy without visual clutter.
+- **Motion**: Sophisticated micro-interactions using framer-motion, featuring rhythmic horizontal loaders that simulate continuous scanning pulses — The Professor, always watching.
+
+## Narrative & Copy Guidelines:
+
+Use these terms consistently across UI copy, docs, and marketing surfaces so the theme stays coherent app-wide:
+
+| Theme Term | Refers To |
+|---|---|
+| The Professor | The AI security reasoner/persona behind explanations and remediation |
+| The Vault | The codebase / protected repository |
+| Mission Control | Main dashboard overview (`/dashboard`) |
+| Breach Attempts | Security findings page (`/dashboard/findings`) |
+| Defense Strategy | Policy management page (`/dashboard/policies`) |
+| Vault Logs | Audit log page (`/dashboard/audit`) |
+| The Resistance | SecureFlow's users/community defending their codebases |
+| Bella Ciao | Tagline motif used for "all clear" / passed-audit moments |
+
+Keep the tone confident and cinematic, never juvenile — SecureFlow is a serious security tool wearing a fun theme, not the other way around.