mega-brain-ai 1.1.0

package/system/docs/architecture/01-system-context.md

@@ -0,0 +1,136 @@
+# Mega Brain - System Context
+
+## Overview
+
+Mega Brain is an intelligent knowledge management system designed for building high-ticket B2B sales playbooks. The system processes video content, transcriptions, and documents to extract, classify, and organize actionable sales knowledge into a structured knowledge base.
+
+## Purpose
+
+Transform unstructured sales content (videos, podcasts, courses) into organized, searchable, and actionable knowledge documents that can be used to train sales teams and build consistent playbooks.
+
+## Target Domain
+
+- **Industry**: B2B Sales
+- **Ticket Size**: High-ticket ($10k+)
+- **Focus Areas**: Outbound sales, team structure, compensation, hiring, metrics
+
+---
+
+## System Boundaries
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        MEGA BRAIN SYSTEM                        │
+│                                                                 │
+│  ┌──────────┐    ┌──────────────┐    ┌───────────────────────┐ │
+│  │ inbox │───▶│ Processing   │───▶│ KNOWLEDGE/            │ │
+│  │          │    │ Pipeline     │    │ (10 theme folders)    │ │
+│  └──────────┘    └──────────────┘    └───────────────────────┘ │
+│       ▲               │                                         │
+│       │               ▼                                         │
+│  ┌────┴─────┐   ┌──────────────┐                               │
+│  │ .claude/ │   │ scripts/     │                               │
+│  │ configs  │   │ utilities    │                               │
+│  └──────────┘   └──────────────┘                               │
+└─────────────────────────────────────────────────────────────────┘
+         ▲                    ▲
+         │                    │
+    ┌────┴────┐          ┌────┴────┐
+    │ YouTube │          │Assembly │
+    │   API   │          │   AI    │
+    └─────────┘          └─────────┘
+```
+
+---
+
+## External Actors
+
+### Human Actors
+
+| Actor | Role | Interactions |
+|-------|------|--------------|
+| **Content Curator** | Identifies and drops content into INBOX | Adds videos, URLs, documents |
+| **Knowledge Consumer** | Uses extracted knowledge | Reads KNOWLEDGE files |
+| **System Administrator** | Configures and maintains system | Edits .claude/ configs |
+
+### System Actors
+
+| System | Purpose | Integration Type |
+|--------|---------|------------------|
+| **YouTube** | Source of video transcripts | API (youtube-transcript-api) |
+| **AssemblyAI** | Transcription service for local files | REST API |
+| **Claude Code** | AI-powered extraction and analysis | Native (CLI) |
+
+---
+
+## Key Interactions
+
+### 1. Content Ingestion
+```
+User drops content → inbox/
+                         ↓
+              /scan-inbox detects new files
+                         ↓
+              Suggests processing action
+```
+
+### 2. Video Processing
+```
+YouTube URL → youtube-transcript-api → Transcript (.txt)
+Local Video → AssemblyAI API → Transcript (.txt)
+```
+
+### 3. Knowledge Extraction
+```
+Transcript → b2b-sales-expert agent → Theme classification
+                                          ↓
+                              KNOWLEDGE/[theme]/[topic].md
+```
+
+---
+
+## Quality Attributes
+
+| Attribute | Requirement |
+|-----------|-------------|
+| **Accuracy** | Preserve exact numbers and metrics from sources |
+| **Traceability** | Every piece of knowledge must have source attribution |
+| **Organization** | Knowledge organized by 10 predefined themes |
+| **Language** | Output in Portuguese (BR) |
+| **Specificity** | Actionable insights only, no generic advice |
+
+---
+
+## Constraints
+
+1. **Data Privacy**: Local processing, no cloud storage of sensitive content
+2. **API Dependencies**: Requires AssemblyAI API key for local file transcription
+3. **Format Support**: Limited to specific video/audio formats (MP4, MP3, WAV, M4A)
+4. **Language**: Primary focus on English content sources, Portuguese output
+
+---
+
+## Context Diagram (C4 Level 1)
+
+```
+┌─────────────┐         ┌─────────────────────────────┐
+│   Content   │         │                             │
+│   Curator   │────────▶│                             │
+└─────────────┘  drops  │                             │
+                content │                             │
+                        │        MEGA BRAIN           │
+┌─────────────┐         │                             │
+│  Knowledge  │◀────────│   Knowledge Management      │
+│  Consumer   │  reads  │        System               │
+└─────────────┘ playbook│                             │
+                        │                             │
+                        └──────────┬──────────────────┘
+                                   │
+                    ┌──────────────┼──────────────┐
+                    │              │              │
+                    ▼              ▼              ▼
+              ┌──────────┐  ┌──────────┐  ┌──────────┐
+              │ YouTube  │  │ Assembly │  │  Claude  │
+              │   API    │  │    AI    │  │   Code   │
+              └──────────┘  └──────────┘  └──────────┘
+```

package/system/docs/architecture/02-components.md

@@ -0,0 +1,225 @@
+# Mega Brain - Component Architecture
+
+## Component Overview (C4 Level 2)
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                            MEGA BRAIN                                    │
+│                                                                         │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │                        .claude/ (Configuration Layer)            │   │
+│  │  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌─────────────┐  │   │
+│  │  │  agents/  │  │ commands/ │  │  skills/  │  │  settings   │  │   │
+│  │  └───────────┘  └───────────┘  └───────────┘  └─────────────┘  │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                                                         │
+│  ┌──────────────┐  ┌──────────────────┐  ┌─────────────────────────┐  │
+│  │   inbox   │  │     scripts/     │  │       KNOWLEDGE/        │  │
+│  │  (Input)     │──│   (Processing)   │──│       (Output)          │  │
+│  └──────────────┘  └──────────────────┘  └─────────────────────────┘  │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Configuration Components (.claude/)
+
+### Agents
+
+| Agent | File | Purpose |
+|-------|------|---------|
+| **b2b-sales-expert** | `agents/b2b-sales-expert.md` | Specialized agent for analyzing B2B sales content with domain expertise |
+
+**Agent Capabilities:**
+- Team structure analysis (Christmas Tree, Farm System)
+- Sales process evaluation (CLOSER framework)
+- Compensation plan validation
+- Metric benchmarking
+- Context-aware advice (ticket size, industry)
+
+---
+
+### Commands
+
+| Command | File | Trigger | Description |
+|---------|------|---------|-------------|
+| `/process-video` | `commands/process-video.md` | URL or path | Process YouTube or local video |
+| `/extract-knowledge` | `commands/extract-knowledge.md` | File path | Extract knowledge from transcript |
+| `/scan-inbox` | `commands/scan-inbox.md` | None | Scan INBOX for pending files |
+| `/documentation/create-architecture-documentation` | `commands/documentation/...` | None | Generate architecture docs |
+
+**Command Flow:**
+```
+/scan-inbox → Lists pending files
+       ↓
+/process-video [URL] → Creates transcript
+       ↓
+/extract-knowledge [path] → Creates knowledge files
+```
+
+---
+
+### Skills
+
+| Skill | Directory | Capabilities |
+|-------|-----------|--------------|
+| **video-processing** | `skills/video-processing/` | YouTube transcript fetch, AssemblyAI integration, format handling |
+| **knowledge-extraction** | `skills/knowledge-extraction/` | Theme detection, content classification, structured output |
+
+**Skill Structure:**
+```
+skills/
+├── video-processing/
+│   └── SKILL.md          # Skill definition and capabilities
+└── knowledge-extraction/
+    └── SKILL.md          # Extraction rules and patterns
+```
+
+---
+
+### Settings
+
+**File:** `settings.local.json`
+
+| Section | Purpose |
+|---------|---------|
+| `permissions.allow` | Allowed tools and domains |
+| `permissions.deny` | Blocked operations |
+| `hooks.PreToolUse` | Pre-execution triggers |
+| `hooks.PostToolUse` | Post-execution triggers |
+| `mcpServers` | MCP server configurations |
+| `env` | Environment variables |
+
+**Configured Permissions:**
+- Bash operations: mkdir, cp, mv, ls, python, pip, npm, node, git, yt-dlp
+- File operations: Read, Write, Edit
+- Web access: youtube.com, youtu.be, api.assemblyai.com
+- Web search enabled
+
+**Configured Hooks:**
+- `PreToolUse:WebSearch` - Adds current year to searches
+- `PostToolUse:Write` - Detects new transcripts in INBOX
+
+---
+
+## Processing Components (scripts/)
+
+### transcribe.py
+
+**Purpose:** Transcribe local audio/video files using AssemblyAI API
+
+**Dependencies:**
+- `assemblyai` Python package
+- `ASSEMBLYAI_API_KEY` environment variable
+
+**Features:**
+- Supports MP4, MP3, WAV, M4A formats
+- Auto language detection
+- Punctuation and formatting
+- Auto chapters
+- Speaker labels
+- Entity detection
+
+---
+
+### auto_organize_inbox.py
+
+**Purpose:** Scan INBOX folder and suggest actions for each file
+
+**Features:**
+- File type detection
+- Theme keyword matching
+- Word count for transcripts
+- Action suggestions
+
+**Output:**
+```
+MEGA BRAIN - INBOX SCANNER
+============================================================
+File: transcript.txt
+  Type: transcript
+  Words: 15,234
+  Detected themes: 01-estrutura-time, 03-contratacao
+  Action: Run /extract-knowledge inbox/transcript.txt
+============================================================
+```
+
+---
+
+## Data Components
+
+### inbox (Input)
+
+**Purpose:** Drop zone for unprocessed content
+
+**Accepted Formats:**
+| Type | Extensions |
+|------|------------|
+| Video | .mp4 |
+| Audio | .mp3, .wav, .m4a |
+| Transcript | .txt |
+| Document | .pdf, .docx, .xlsx |
+
+---
+
+### KNOWLEDGE (Output)
+
+**Purpose:** Organized knowledge base with themed folders
+
+| Folder | Theme | Content Type |
+|--------|-------|--------------|
+| `01-estrutura-time/` | Team Structure | Org charts, roles, hierarchy |
+| `02-processo-vendas/` | Sales Process | Closing, qualification, scripts |
+| `03-contratacao/` | Hiring | Recruiting, interviews, onboarding |
+| `04-comissionamento/` | Compensation | OTE, commissions, incentives |
+| `05-metricas/` | Metrics | KPIs, benchmarks, conversion rates |
+| `06-funil-aplicacao/` | Application Funnel | Lead qualification, pipeline |
+| `07-pricing/` | Pricing | High-ticket strategies |
+| `08-ferramentas/` | Tools | CRM, tech stack |
+| `09-gestao/` | Management | Leadership, coaching |
+| `99-secundario/` | Secondary | Other supporting topics |
+
+**Current Knowledge Files (16):**
+- 01-estrutura-time: 2 files
+- 02-processo-vendas: 3 files
+- 03-contratacao: 1 file
+- 04-comissionamento: 1 file
+- 05-metricas: 2 files
+- 06-funil-aplicacao: 1 file
+- 07-pricing: 1 file
+- 08-ferramentas: 1 file
+- 99-secundario: 4 files
+
+---
+
+## Component Dependencies
+
+```
+┌────────────────┐     ┌────────────────┐
+│    Commands    │────▶│     Skills     │
+└───────┬────────┘     └───────┬────────┘
+        │                      │
+        ▼                      ▼
+┌────────────────┐     ┌────────────────┐
+│    Agents      │     │    Scripts     │
+└───────┬────────┘     └───────┬────────┘
+        │                      │
+        └──────────┬───────────┘
+                   ▼
+           ┌────────────────┐
+           │   KNOWLEDGE    │
+           └────────────────┘
+```
+
+---
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| **AI Runtime** | Claude Code CLI |
+| **Configuration** | JSON, Markdown |
+| **Scripts** | Python 3.x |
+| **APIs** | youtube-transcript-api, AssemblyAI |
+| **MCP** | @anthropic-ai/mcp-server-filesystem |

package/system/docs/architecture/03-data-flow.md

@@ -0,0 +1,235 @@
+# Mega Brain - Data Flow Architecture
+
+## High-Level Data Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           DATA FLOW OVERVIEW                             │
+└─────────────────────────────────────────────────────────────────────────┘
+
+ EXTERNAL SOURCES                    PROCESSING                    OUTPUT
+ ═══════════════                    ══════════                    ══════
+
+ ┌─────────────┐                                              ┌──────────┐
+ │   YouTube   │──┐                                           │ 01-time  │
+ │    Video    │  │                                           ├──────────┤
+ └─────────────┘  │   ┌──────────┐   ┌──────────────────┐    │ 02-sales │
+                  ├──▶│ inbox │──▶│ Knowledge        │───▶├──────────┤
+ ┌─────────────┐  │   │          │   │ Extraction       │    │ 03-hire  │
+ │ Local Video │──┘   └──────────┘   │ Pipeline         │    ├──────────┤
+ │   (.mp4)    │                     └──────────────────┘    │   ...    │
+ └─────────────┘                                              └──────────┘
+```
+
+---
+
+## Processing Pipelines
+
+### Pipeline 1: YouTube Video Processing
+
+```
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│ YouTube URL  │───▶│ Extract      │───▶│ Fetch        │───▶│ Save to      │
+│              │    │ Video ID     │    │ Transcript   │    │ inbox     │
+└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
+                                              │
+                                    youtube-transcript-api
+                                              │
+                                    ┌─────────▼─────────┐
+                                    │ Returns: list of  │
+                                    │ {text, start,     │
+                                    │  duration}        │
+                                    └───────────────────┘
+```
+
+**Data Transformation:**
+```python
+# Input
+url = "https://youtube.com/watch?v=VIDEO_ID"
+
+# Processing
+video_id = extract_video_id(url)  # "VIDEO_ID"
+transcript = api.fetch(video_id)   # [{text: "...", start: 0.0}, ...]
+text = " ".join([t['text'] for t in transcript])
+
+# Output
+# inbox/Video Title.txt (plain text, UTF-8)
+```
+
+---
+
+### Pipeline 2: Local File Transcription
+
+```
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│ Local File   │───▶│ Upload to    │───▶│ AssemblyAI   │───▶│ Save to      │
+│ (.mp4/.mp3)  │    │ AssemblyAI   │    │ Transcribe   │    │ inbox     │
+└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
+                                              │
+                                    AssemblyAI API
+                                              │
+                                    ┌─────────▼─────────┐
+                                    │ Returns: text,    │
+                                    │ chapters,         │
+                                    │ speakers,         │
+                                    │ entities          │
+                                    └───────────────────┘
+```
+
+**Configuration:**
+```python
+config = aai.TranscriptionConfig(
+    language_code="en",
+    punctuate=True,
+    format_text=True,
+    auto_chapters=True,
+    speaker_labels=True,
+    entity_detection=True,
+)
+```
+
+---
+
+### Pipeline 3: Knowledge Extraction
+
+```
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│ Transcript   │───▶│ Theme        │───▶│ AI Agent     │───▶│ Knowledge    │
+│ (.txt)       │    │ Detection    │    │ Extraction   │    │ Files        │
+└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
+        │                  │                   │                   │
+        ▼                  ▼                   ▼                   ▼
+   Plain text        Keyword         b2b-sales-expert      Markdown files
+   78,000+ chars     matching        agent analysis        in KNOWLEDGE/
+```
+
+**Theme Detection Keywords:**
+```python
+THEMES = {
+    "01-estrutura-time": ["team", "bdr", "sds", "bc", "christmas tree"],
+    "02-processo-vendas": ["sales", "closer", "closing", "objection"],
+    "03-contratacao": ["hiring", "recruit", "farm system"],
+    "04-comissionamento": ["compensation", "commission", "ote"],
+    "05-metricas": ["kpi", "metric", "cac", "ltv", "conversion"],
+    ...
+}
+```
+
+---
+
+## Data Formats
+
+### Input Formats
+
+| Format | Extension | Source | Handler |
+|--------|-----------|--------|---------|
+| YouTube URL | - | Web | youtube-transcript-api |
+| Video | .mp4 | Local | AssemblyAI |
+| Audio | .mp3, .wav, .m4a | Local | AssemblyAI |
+| Transcript | .txt | INBOX | Direct read |
+| Document | .pdf, .docx | Local | Manual |
+
+### Output Format
+
+**Knowledge File Template:**
+```markdown
+# [Topic Title]
+
+## Resumo Executivo
+[1-2 sentence summary]
+
+---
+
+## Visão [Source Name]
+
+### Contexto
+[Industry, ticket size, team stage]
+
+### [Subtopic 1]
+- Point 1 with specific numbers
+- Point 2 with exact metrics
+- Actionable recommendation
+
+### Fonte
+- Video: [Title]
+- Fonte: [Speaker/Company]
+- Confiabilidade: Alta/Média
+```
+
+---
+
+## Data Transformation Rules
+
+### 1. Number Preservation
+```
+Input:  "We had a 25% close rate"
+Output: "Close rate: 25%" (exact, never rounded)
+```
+
+### 2. Context Annotation
+```
+Input:  "Our BDRs make 100 calls per day"
+Output: "BDR calls: 100/dia (contexto: high-ticket B2B, $20k+ ticket)"
+```
+
+### 3. Source Attribution
+```
+Every extracted insight MUST include:
+- Source video/document name
+- Speaker/author
+- Reliability rating
+```
+
+### 4. Language Handling
+```
+Input:  English transcripts
+Output: Portuguese (BR) knowledge files
+        (Technical terms may remain in English)
+```
+
+---
+
+## Data Volume Estimates
+
+| Stage | Typical Size |
+|-------|--------------|
+| YouTube transcript | 15,000 - 100,000 chars |
+| Local video (1 hour) | 10,000 - 50,000 words |
+| Knowledge file | 500 - 2,000 words |
+| Themes per source | 2-5 themes |
+
+---
+
+## State Transitions
+
+```
+┌────────────────┐
+│   UNPROCESSED  │ ◀─── File dropped in inbox
+└───────┬────────┘
+        │ /scan-inbox or /process-video
+        ▼
+┌────────────────┐
+│  TRANSCRIBED   │ ◀─── Transcript created in inbox
+└───────┬────────┘
+        │ /extract-knowledge
+        ▼
+┌────────────────┐
+│   EXTRACTED    │ ◀─── Knowledge files in KNOWLEDGE/
+└───────┬────────┘
+        │ Manual review (optional)
+        ▼
+┌────────────────┐
+│   VALIDATED    │ ◀─── Ready for use in playbook
+└────────────────┘
+```
+
+---
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| No transcript available | YouTube video without captions | Use local transcription |
+| API rate limit | Too many requests | Wait and retry |
+| Theme not detected | Content doesn't match keywords | Put in 99-secundario |
+| File too large | Video > 1GB | Split or compress |