refactor: console improvements — auto-discovery, centralized bootstrap, per-command help

- ConsoleApplication.discoverCommands() scans lib/Console/Commands/ automatically;
  adding a new command no longer requires editing bin/console
- Command base class provides bootstrapApp(), bootstrapModuleApp(), requireBinScript()
  and projectRoot() helpers — eliminates fragile 4-level relative require_once paths
- Per-command --help support via optional usage() method on Command
- Docker-compose scheduler updated to use bin/console scheduler:run
- Old bin scripts now emit deprecation hint to stderr when called directly

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

tests/Console/ConsoleApplicationTest.php

@@ -81,6 +81,65 @@ final class ConsoleApplicationTest extends TestCase
         self::assertSame([], $command->lastArgs);
         self::assertSame(['module' => 'addressbook'], $command->lastOptions);
     }
+
+    public function testHelpOptionShowsUsageAndReturnsZero(): void
+    {
+        $command = new CommandWithUsage();
+        $app = new ConsoleApplication();
+        $app->register($command);
+
+        $exitCode = $app->run(['bin/console', 'test:usage', '--help']);
+
+        self::assertSame(0, $exitCode);
+        self::assertFalse($command->wasExecuted, 'Command should not execute when --help is passed');
+    }
+
+    public function testHelpOnCommandWithoutUsageShowsNameAndDescription(): void
+    {
+        $command = new DummyCommand();
+        $app = new ConsoleApplication();
+        $app->register($command);
+
+        $exitCode = $app->run(['bin/console', 'test:dummy', '--help']);
+
+        self::assertSame(0, $exitCode);
+        self::assertSame([], $command->lastArgs, 'Command should not execute when --help is passed');
+    }
+
+    public function testAutoDiscoverFindsCommandsInDirectory(): void
+    {
+        $app = new ConsoleApplication();
+        $commandsDir = dirname(__DIR__, 2) . '/lib/Console/Commands';
+        $app->discoverCommands($commandsDir);
+
+        // Should find at least the 8 commands we have
+        $exitCode = $app->run(['bin/console', 'module:sync', '--help']);
+        self::assertSame(0, $exitCode);
+
+        $exitCode = $app->run(['bin/console', 'scheduler:run', '--help']);
+        self::assertSame(0, $exitCode);
+
+        $exitCode = $app->run(['bin/console', 'doctor', '--help']);
+        self::assertSame(0, $exitCode);
+    }
+
+    public function testAutoDiscoverIgnoresNonexistentDirectory(): void
+    {
+        $app = new ConsoleApplication();
+        $app->discoverCommands(sys_get_temp_dir() . '/nonexistent-console-' . uniqid());
+
+        // Should not throw, just have no commands
+        $exitCode = $app->run(['bin/console', 'anything']);
+        self::assertSame(1, $exitCode);
+    }
+
+    public function testProjectRootResolvesCorrectly(): void
+    {
+        $command = new ProjectRootTestCommand();
+        $expectedRoot = realpath(dirname(__DIR__, 2));
+
+        self::assertSame($expectedRoot, realpath($command->getProjectRoot()));
+    }
 }
 
 final class DummyCommand extends Command
@@ -123,3 +182,52 @@ final class FailingCommand extends Command
         return 42;
     }
 }
+
+final class CommandWithUsage extends Command
+{
+    public bool $wasExecuted = false;
+
+    public function name(): string
+    {
+        return 'test:usage';
+    }
+
+    public function description(): string
+    {
+        return 'Has custom usage text';
+    }
+
+    public function usage(): string
+    {
+        return "Usage: php bin/console test:usage <arg>\n\nA test command with usage.";
+    }
+
+    public function execute(array $args, array $options): int
+    {
+        $this->wasExecuted = true;
+        return 0;
+    }
+}
+
+final class ProjectRootTestCommand extends Command
+{
+    public function name(): string
+    {
+        return 'test:root';
+    }
+
+    public function description(): string
+    {
+        return 'Tests project root';
+    }
+
+    public function getProjectRoot(): string
+    {
+        return $this->projectRoot();
+    }
+
+    public function execute(array $args, array $options): int
+    {
+        return 0;
+    }
+}