Merge pull request #55 from YagoBorba/feature/educational-mode-35

Feature/educational mode 35

Author: YagoBorba

README.md

@@ -61,7 +61,10 @@ StackCode is a suite of tools designed to work together seamlessly:
   Integrates seamlessly with Husky git hooks. The `stc validate` command ensures that no non-conventional commit ever makes it into your repository.
 
 - ⚙️ **Flexible Configuration (`config`):**
-  Manage global preferences (like language) and project-specific settings (like enabling commit validation) with a simple, interactive command.
+  Manage global preferences (like language and educational mode) and project-specific settings (like enabling commit validation) with a simple, interactive command.
+
+- 🎓 **Educational Mode (`--educate`):**
+  **NEW!** Learn while you work. Enable educational mode to receive helpful explanations about best practices behind every action. Configure globally with `stc config set educate true` or use the `--educate` flag on any command for on-demand learning.
 
 ## 🛠️ Under the Hood (Main Technologies)
 
@@ -102,6 +105,22 @@ This is the best approach for ensuring everyone on a project uses the exact same
     npx stc commit
     ```
 
+### 🎓 Enable Educational Mode (Recommended for Beginners)
+
+StackCode can teach you best practices as you work. To enable educational explanations:
+
+```bash
+# Enable educational mode globally (shows explanations on all commands)
+stc config set educate true
+
+# Or use on-demand with any command
+stc validate "feat: new feature" --educate
+stc commit --educate
+stc init --educate
+```
+
+Educational mode explains the "why" behind each action, making it perfect for learning DevOps best practices!
+
 ## 📚 Documentation
 
 For detailed information about the project:

docs/ARCHITECTURE.md

@@ -53,6 +53,7 @@ StackCode follows a **modular monorepo architecture** with clear separation of c
 - **Command Layer:** Entry points for all CLI operations
 - **Command Handlers:** Individual command implementations
 - **Interactive Prompts:** User guidance and input collection
+- **Educational Mode:** Contextual learning system with best practice explanations
 - **Error Handling:** Consistent error reporting and recovery
 
 **Architecture:**
@@ -61,14 +62,16 @@ StackCode follows a **modular monorepo architecture** with clear separation of c
 cli/
 ├── src/
 │   ├── index.ts              # Main CLI entry point
+│   ├── educational-mode.ts   # Educational mode management
 │   ├── commands/             # Command implementations
 │   │   ├── init.ts           # Project scaffolding
 │   │   ├── generate.ts       # File generation
 │   │   ├── commit.ts         # Conventional commits
 │   │   ├── git.ts            # Git workflow management
 │   │   ├── release.ts        # Version management
 │   │   ├── validate.ts       # Commit validation
-│   │   └── config.ts         # Configuration management
+│   │   ├── config.ts         # Configuration management
+│   │   └── ui.ts             # Interactive prompts and feedback
 │   └── types/                # CLI-specific type definitions
 └── test/                     # Command tests
 ```
@@ -402,6 +405,49 @@ const result = await validateStackDependencies("go");
 | `python`                             | `pip`, `python`   | ✅                |
 | `node-js`, `node-ts`, `react`, `vue` | `npm`             | ✅                |
 
+## 🎓 Educational Mode Architecture
+
+### Overview
+
+The Educational Mode is a cross-cutting feature that enhances the user experience by providing contextual explanations and best practice guidance throughout the StackCode toolkit.
+
+### Implementation
+
+```typescript
+// Educational Mode Flow
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   User Command  │ -> │ Mode Detection  │ -> │  Show Messages  │
+│  --educate or   │    │ Global Config + │    │  Best Practices │
+│  global config  │    │ Command Flag    │    │  & Explanations │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+### Key Components
+
+- **`educational-mode.ts`:** Core educational mode logic
+  - `initEducationalMode()`: Detects configuration and command flags
+  - `showEducationalMessage()`: Displays contextual tips
+  - `showBestPractice()`: Shows best practice explanations
+  - `showSecurityTip()`: Highlights security considerations
+
+- **Configuration Integration:**
+  - Global setting: `stackcode config set educate true/false`
+  - Per-command flag: `--educate` on any command
+  - Interactive setup via `stackcode config`
+
+- **Message System:**
+  - Internationalized explanations (PT/EN)
+  - Fallback messages for reliability
+  - Context-aware content based on command
+
+### Educational Content Coverage
+
+- **Project Initialization:** Explains scaffolding decisions and dependencies
+- **File Generation:** Describes purpose of .gitignore, README, etc.
+- **Git Workflows:** Explains conventional commits and version control benefits
+- **Security Practices:** Highlights importance of .gitignore for secrets
+- **Automation Benefits:** Shows value of Husky, CI/CD, and release automation
+
 ## 🚀 Deployment and Distribution
 
 ### NPM Packages