feat: add Mermaid visual context protocol and flowchart guide

Author: AybarsBarut

AI_MAIN.md

@@ -13,7 +13,7 @@ Main function for AI workflow. Sequential logic. Strict execution. No fluff.
 
 ## 🚦 EXECUTION_FLOW (main)
 
-1. [x] **LOAD_CONTEXT**: Read core protocol (APCP, Decision Log, Caveman, Context Optimization).
+1. [x] **LOAD_CONTEXT**: Read core protocol (APCP, Decision Log, Caveman, Context Optimization, Mermaid).
 2. [x] **TASK_ANALYSIS**: Create AI_MAIN.md framework.
 3. [x] **MODEL_DISPATCH**: Roles assigned (Flash for setup).
 4. [x] **IMPLEMENTATION**: Created AI_MAIN, TASK_PROGRESS, scripts/ (checkpoint.ps1, validate-repo.py, apcp-gather.py).
@@ -47,6 +47,7 @@ Main function for AI workflow. Sequential logic. Strict execution. No fluff.
 - [x] Task 4: Verify Caveman compliance.
 - [x] Task 7: Synchronize `AI_MAIN.md` with current repository state.
 - [x] Task 8: Implement Second Brain Sync Scenario (Scenario 0).
+- [x] Task 9: Implement Mermaid Visual Context Flowchart Protocol.
 
 ---
 

README.md

@@ -79,6 +79,7 @@ Paste the generated `PROMPT_READY.txt` into your AI assistant, or start with the
 | [`DOMAIN_SPECIFIC_GITIGNORE_PROTOCOLS.md`](./DOMAIN_SPECIFIC_GITIGNORE_PROTOCOLS.md) | Safe publishing patterns for different technical domains. |
 | [`SETUP_GUIDE.md`](./SETUP_GUIDE.md) | Step-by-step setup instructions. |
 | [`scripts/apcp-gather.py`](./scripts/apcp-gather.py) | Context packer that generates `PROMPT_READY.txt`. |
+| [`VISUAL_CONTEXT_MERMAID.md`](./VISUAL_CONTEXT_MERMAID.md) | Standardized Mermaid.js flowchart protocol for architecture and logic visualization. |
 | [`AGENTS.md`](./AGENTS.md) | Repository instructions for AI coding assistants and automation agents. |
 | [`examples/`](./examples/README.md) | Sanitized starter kits for web apps, backend APIs, and AI/RAG systems. |
 

TASK_PROGRESS.yaml

@@ -73,8 +73,16 @@ tasks:
     assignee: "Antigravity (AI)"
     description: "Create Scenario 0 in prompt templates for NotebookLM/Obsidian Knowledge Base export."
 
+  - id: TASK-009
+    title: "Implement Mermaid Visual Context Flowchart Protocol"
+    status: COMPLETED
+    priority: MEDIUM
+    effort: 1
+    assignee: "Antigravity (AI)"
+    description: "Create VISUAL_CONTEXT_MERMAID.md and integrate it into the repository core docs."
+
 metrics:
-  tasks_completed: 8
-  total_tasks: 8
+  tasks_completed: 9
+  total_tasks: 9
   velocity: 1.0
   quality_score: 100%

VISUAL_CONTEXT_MERMAID.md

@@ -0,0 +1,76 @@
+# 📊 Visual Context Protocol: Mermaid Flowcharts
+
+## 🎯 Purpose
+Provide developers and AI agents with a standardized way to visualize project architecture, workflows, and state transitions using [Mermaid.js](https://mermaid-js.github.io/mermaid/). Visual diagrams reduce cognitive load and help AI assistants understand complex relationships faster.
+
+## ⚙️ Why use Mermaid?
+- **Text-Based**: Diagrams are stored as code (Markdown), making them version-controllable and token-efficient.
+- **AI-Friendly**: LLMs are excellent at generating and parsing Mermaid syntax.
+- **IDE Support**: Most modern IDEs (Cursor, VS Code, Obsidian) and GitHub/GitLab render Mermaid natively.
+
+---
+
+## 🏗️ Core Diagram Types
+
+### 1. Architecture Map (High-Level)
+Use flowcharts to map directory structures, service boundaries, and data flow.
+
+```mermaid
+graph TD
+    A[User/Client] --> B[API Gateway]
+    B --> C[Auth Service]
+    B --> D[Product Service]
+    D --> E[(PostgreSQL)]
+    C --> F[(Redis)]
+```
+
+### 2. Workflow / Logic Flow
+Visualize complex business logic or AI execution paths.
+
+```mermaid
+graph LR
+    Start --> CheckContext{Context Loaded?}
+    CheckContext -- No --> Load[Load APCP]
+    CheckContext -- Yes --> Task[Execute Task]
+    Load --> Task
+    Task --> Verify{Verify Quality}
+    Verify -- Fail --> Task
+    Verify -- Pass --> End
+```
+
+### 3. State Machine
+Track the lifecycle of a task, order, or system state.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Processing: New Task
+    Processing --> Validating: Code Written
+    Validating --> Done: Tests Pass
+    Validating --> Processing: Fix Needed
+    Done --> [*]
+```
+
+---
+
+## 🤖 Instructions for AI Agents
+
+When an AI agent is asked to "visualize" or "explain the architecture," it should:
+1. **Identify Entities**: Determine the key components, files, or services.
+2. **Define Relationships**: Map how data or control flows between them.
+3. **Generate Mermaid**: Output a valid `mermaid` code block.
+4. **Prefer Flowcharts**: Use `graph TD` (Top-Down) or `graph LR` (Left-Right) for most scenarios.
+
+**Prompt Snippet for Humans:**
+> "Generate a Mermaid flowchart explaining how the [Module Name] interacts with the database and external APIs."
+
+---
+
+## 🛠️ Integration with Nexus-APCP
+
+- **Location**: Store complex diagrams in `docs/diagrams/` or embed them directly in `AI_PROJECT_CONTEXT_PROTOCOL.md`.
+- **Decision Logs**: Use Mermaid in `DECISION_LOG_PROTOCOL.md` to show "Before" vs "After" architecture during major refactors.
+- **Task Progress**: Use state diagrams to visualize long-running multi-stage tasks.
+
+---
+*Nexus-APCP: Visualizing logic for faster engineering.* 📈🚀