docs: consolidate documentation into organized structure

- Move 12 markdown files from root to docs/ subdirectories
- Organize documentation by category:
  • docs/troubleshooting/ (1 file)  - Technical troubleshooting guides
  • docs/deployment/      (4 files) - Deployment and security documentation
  • docs/guides/          (3 files) - Feature-specific guides
  • docs/planning/        (4 files) - Planning and improvement proposals

Root directory cleanup:
- Reduced from 16 to 4 markdown files in root
- Only essential project files remain:
  • CLAUDE.md (AI instructions)
  • README.md (Main project readme)
  • CLEANUP_PLAN.md (Current cleanup plan)
  • SRC_STRUCTURE_IMPROVEMENTS.md (Structure improvements)

This improves:
✅ Documentation discoverability
✅ Logical organization by purpose
✅ Clean root directory
✅ Better maintainability

src/Framework/Console/Examples/CreateUserCommand.php

@@ -0,0 +1,126 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Console\Examples;
+
+use App\Framework\Console\ArgumentParser;
+use App\Framework\Console\ConsoleCommand;
+use App\Framework\Console\ConsoleInput;
+use App\Framework\Console\ConsoleOutputInterface;
+use App\Framework\Console\ExitCode;
+use App\Framework\Console\HelpGenerator;
+use App\Framework\Core\ValueObjects\Email;
+
+/**
+ * Example command demonstrating the enhanced parameter parsing system
+ */
+final readonly class CreateUserCommand
+{
+    private ArgumentParser $parser;
+
+    public function __construct()
+    {
+        // Define command arguments using the fluent builder
+        $this->parser = ArgumentParser::create()
+            ->requiredString('email', 'User email address')
+            ->requiredString('name', 'Full name of the user')
+            ->choice('role', ['user', 'admin', 'moderator'], false, 'user', 'User role')
+            ->flag('force', 'f', 'Skip confirmation prompts')
+            ->flag('notify', null, 'Send welcome email to user')
+            ->integer('quota', false, 100, 'Storage quota in MB')
+            ->build();
+    }
+
+    #[ConsoleCommand('user:create', 'Create a new user account')]
+    public function execute(ConsoleInput $input, ConsoleOutputInterface $output): ExitCode
+    {
+        try {
+            // Set the enhanced parser for this command
+            $input->setArgumentParser($this->parser);
+
+            // Validate all required arguments
+            $input->validate();
+
+            // Get typed arguments with automatic validation
+            $email = new Email($input->getString('email'));
+            $name = $input->getString('name');
+            $role = $input->getString('role');
+            $force = $input->getBool('force');
+            $notify = $input->getBool('notify');
+            $quota = $input->getInt('quota');
+
+            // Display what we're about to do
+            $output->writeLine("Creating user with the following details:");
+            $output->writeLine("  Email: {$email->toString()}");
+            $output->writeLine("  Name: {$name}");
+            $output->writeLine("  Role: {$role}");
+            $output->writeLine("  Quota: {$quota} MB");
+            $output->writeLine("  Notify: " . ($notify ? 'Yes' : 'No'));
+            $output->newLine();
+
+            // Confirm unless forced
+            if (! $force && ! $input->confirm('Create this user?', false)) {
+                $output->writeInfo('User creation cancelled.');
+
+                return ExitCode::SUCCESS;
+            }
+
+            // Simulate user creation
+            $output->writeSuccess("User '{$name}' created successfully!");
+
+            if ($notify) {
+                $output->writeInfo("Welcome email sent to {$email->toString()}");
+            }
+
+            return ExitCode::SUCCESS;
+
+        } catch (\InvalidArgumentException $e) {
+            $output->writeError($e->getMessage());
+            $this->showHelp($output);
+
+            return ExitCode::INVALID_INPUT;
+
+        } catch (\Exception $e) {
+            $output->writeError("Failed to create user: " . $e->getMessage());
+
+            return ExitCode::GENERAL_ERROR;
+        }
+    }
+
+    #[ConsoleCommand('user:create:help', 'Show help for user:create command')]
+    public function showHelp(ConsoleInput $input, ConsoleOutputInterface $output): ExitCode
+    {
+        $helpGenerator = new HelpGenerator($output);
+        $helpGenerator->display(
+            'user:create',
+            $this->parser->getDefinitions(),
+            'Create a new user account with email, name, and optional settings.'
+        );
+
+        return ExitCode::SUCCESS;
+    }
+
+    /**
+     * Example usage methods to demonstrate all features
+     */
+    public function getExampleUsages(): array
+    {
+        return [
+            // Basic usage
+            'php console user:create john@example.com "John Doe"',
+
+            // With role
+            'php console user:create john@example.com "John Doe" --role=admin',
+
+            // With short flags
+            'php console user:create john@example.com "John Doe" -f --notify',
+
+            // With quota
+            'php console user:create john@example.com "John Doe" --quota=500 --role=moderator',
+
+            // All options
+            'php console user:create john@example.com "John Doe" --role=admin --force --notify --quota=1000',
+        ];
+    }
+}

src/Framework/Console/Examples/UserRole.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Console\Examples;
+
+/**
+ * User role enumeration for console commands
+ */
+enum UserRole: string
+{
+    case USER = 'user';
+    case ADMIN = 'admin';
+    case MODERATOR = 'moderator';
+
+    /**
+     * Get human-readable description
+     */
+    public function getDescription(): string
+    {
+        return match($this) {
+            self::USER => 'Regular user with basic permissions',
+            self::ADMIN => 'Administrator with full system access',
+            self::MODERATOR => 'Moderator with content management permissions',
+        };
+    }
+
+    /**
+     * Get all role values as array
+     */
+    public static function getValues(): array
+    {
+        return array_column(self::cases(), 'value');
+    }
+
+    /**
+     * Check if role has admin privileges
+     */
+    public function hasAdminPrivileges(): bool
+    {
+        return $this === self::ADMIN;
+    }
+
+    /**
+     * Check if role can moderate content
+     */
+    public function canModerate(): bool
+    {
+        return in_array($this, [self::ADMIN, self::MODERATOR], true);
+    }
+}

src/Framework/Console/Examples/WorkflowDemoCommand.php

@@ -0,0 +1,197 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Console\Examples;
+
+use App\Framework\Console\CommandGroup;
+use App\Framework\Console\CommandWorkflow;
+use App\Framework\Console\ConsoleColor;
+use App\Framework\Console\ConsoleCommand;
+use App\Framework\Console\ConsoleInput;
+use App\Framework\Console\ConsoleOutputInterface;
+use App\Framework\Console\ExitCode;
+
+/**
+ * Demo commands to showcase the new command groups and workflow system
+ */
+#[CommandGroup(
+    name: 'Workflow Demo',
+    description: 'Demo commands showcasing workflow and group features',
+    icon: '🎭',
+    priority: 100,
+    tags: ['demo', 'workflow', 'showcase']
+)]
+final readonly class WorkflowDemoCommand
+{
+    #[ConsoleCommand('workflow:setup', 'Set up a complete development environment')]
+    #[CommandWorkflow(
+        name: 'Development Setup',
+        description: 'Complete development environment setup workflow',
+        steps: [
+            [
+                'command' => 'workflow:check-system',
+                'description' => 'Check system requirements',
+                'optional' => false,
+            ],
+            [
+                'command' => 'workflow:install-deps',
+                'description' => 'Install dependencies',
+                'optional' => false,
+                'retryCount' => 2,
+            ],
+            [
+                'command' => 'workflow:setup-db',
+                'description' => 'Set up database',
+                'optional' => false,
+                'environment' => ['DB_SETUP' => 'true'],
+            ],
+            [
+                'command' => 'workflow:seed-data',
+                'description' => 'Seed initial data',
+                'optional' => true,
+                'condition' => 'development',
+            ],
+        ],
+        prerequisites: ['database'],
+        stopOnError: true,
+        rollbackSteps: [
+            [
+                'command' => 'workflow:cleanup-db',
+                'description' => 'Clean up database on failure',
+            ],
+        ]
+    )]
+    public function setupWorkflow(ConsoleInput $input, ConsoleOutputInterface $output): ExitCode
+    {
+        $output->writeLine('🚀 Development setup workflow started!', ConsoleColor::BRIGHT_GREEN);
+        $output->writeLine('This workflow will be handled by the WorkflowExecutor.', ConsoleColor::GRAY);
+
+        return ExitCode::SUCCESS;
+    }
+
+    #[ConsoleCommand('workflow:check-system', 'Check system requirements')]
+    public function checkSystem(ConsoleInput $input, ConsoleOutputInterface $output): ExitCode
+    {
+        $output->writeLine('🔍 Checking system requirements...', ConsoleColor::CYAN);
+
+        $checks = [
+            'PHP Version' => PHP_VERSION_ID >= 80200,
+            'Extensions' => extension_loaded('pdo'),
+            'Memory Limit' => (int)ini_get('memory_limit') >= 128,
+            'Disk Space' => disk_free_space('.') > 1024 * 1024 * 100, // 100MB
+        ];
+
+        foreach ($checks as $check => $result) {
+            $status = $result ? '✅' : '❌';
+            $color = $result ? ConsoleColor::GREEN : ConsoleColor::RED;
+            $output->writeLine("  {$status} {$check}", $color);
+        }
+
+        return ExitCode::SUCCESS;
+    }
+
+    #[ConsoleCommand('workflow:install-deps', 'Install project dependencies')]
+    public function installDependencies(ConsoleInput $input, ConsoleOutputInterface $output): ExitCode
+    {
+        $output->writeLine('📦 Installing dependencies...', ConsoleColor::CYAN);
+
+        $steps = [
+            'Composer dependencies',
+            'NPM packages',
+            'Framework assets',
+        ];
+
+        foreach ($steps as $step) {
+            $output->writeLine("  Installing {$step}...", ConsoleColor::WHITE);
+            usleep(500000); // Simulate installation time
+            $output->writeLine("  ✅ {$step} installed", ConsoleColor::GREEN);
+        }
+
+        return ExitCode::SUCCESS;
+    }
+
+    #[ConsoleCommand('workflow:setup-db', 'Set up database and run migrations')]
+    public function setupDatabase(ConsoleInput $input, ConsoleOutputInterface $output): ExitCode
+    {
+        $output->writeLine('🗄️ Setting up database...', ConsoleColor::CYAN);
+
+        $steps = [
+            'Create database',
+            'Run migrations',
+            'Set up indexes',
+        ];
+
+        foreach ($steps as $step) {
+            $output->writeLine("  {$step}...", ConsoleColor::WHITE);
+            usleep(300000); // Simulate operation time
+            $output->writeLine("  ✅ {$step} completed", ConsoleColor::GREEN);
+        }
+
+        return ExitCode::SUCCESS;
+    }
+
+    #[ConsoleCommand('workflow:seed-data', 'Seed initial development data')]
+    public function seedData(ConsoleInput $input, ConsoleOutputInterface $output): ExitCode
+    {
+        $output->writeLine('🌱 Seeding development data...', ConsoleColor::CYAN);
+
+        $datasets = [
+            'Test users',
+            'Sample content',
+            'Configuration data',
+        ];
+
+        foreach ($datasets as $dataset) {
+            $output->writeLine("  Seeding {$dataset}...", ConsoleColor::WHITE);
+            usleep(200000); // Simulate seeding time
+            $output->writeLine("  ✅ {$dataset} seeded", ConsoleColor::GREEN);
+        }
+
+        return ExitCode::SUCCESS;
+    }
+
+    #[ConsoleCommand('workflow:cleanup-db', 'Clean up database (rollback operation)')]
+    public function cleanupDatabase(ConsoleInput $input, ConsoleOutputInterface $output): ExitCode
+    {
+        $output->writeLine('🧹 Cleaning up database...', ConsoleColor::YELLOW);
+
+        $steps = [
+            'Drop test tables',
+            'Clear cache',
+            'Reset connections',
+        ];
+
+        foreach ($steps as $step) {
+            $output->writeLine("  {$step}...", ConsoleColor::WHITE);
+            usleep(100000); // Simulate cleanup time
+            $output->writeLine("  ✅ {$step} completed", ConsoleColor::GREEN);
+        }
+
+        return ExitCode::SUCCESS;
+    }
+
+    #[ConsoleCommand('workflow:status', 'Show workflow and group information')]
+    public function showStatus(ConsoleInput $input, ConsoleOutputInterface $output): ExitCode
+    {
+        $output->writeLine('📋 Workflow System Status', ConsoleColor::BRIGHT_CYAN);
+        $output->newLine();
+
+        $output->writeLine('Command Groups:', ConsoleColor::BRIGHT_WHITE);
+        $output->writeLine('  • This command belongs to: "Workflow Demo" group', ConsoleColor::WHITE);
+        $output->writeLine('  • Group icon: 🎭', ConsoleColor::WHITE);
+        $output->writeLine('  • Group priority: 100', ConsoleColor::WHITE);
+        $output->writeLine('  • Group tags: demo, workflow, showcase', ConsoleColor::WHITE);
+
+        $output->newLine();
+        $output->writeLine('Available Workflows:', ConsoleColor::BRIGHT_WHITE);
+        $output->writeLine('  • Development Setup (workflow:setup)', ConsoleColor::WHITE);
+        $output->writeLine('    - 4 steps with prerequisites and rollback', ConsoleColor::GRAY);
+        $output->writeLine('    - Stops on error with automatic cleanup', ConsoleColor::GRAY);
+
+        $output->newLine();
+        $output->writeLine('💡 Try running "workflow:setup" to see the workflow in action!', ConsoleColor::BRIGHT_YELLOW);
+
+        return ExitCode::SUCCESS;
+    }
+}