@uxmaltech/collab-cli 0.1.0

package/README.md

@@ -0,0 +1,227 @@
+# collab-cli
+
+Orchestration CLI for collaborative workflows with canonical architecture. Manages the complete lifecycle: from initial repository setup to Docker infrastructure, AI provider configuration, and architectural canon synchronization.
+
+## Collab Ecosystem
+
+```mermaid
+graph TD
+    DEV[Developer] --> CLI[collab-cli<br><i>infrastructure</i>]
+
+    subgraph APP["collab-laravel-app"]
+        CHAT[collab-chat-ai-pkg<br><i>Chat UI</i>]
+        CORE[collab-core-pkg<br><i>Discovery Agent</i>]
+        PM[collab-project-manager-pkg]
+        CHAT -- interface --> CORE
+    end
+
+    DEV -- "chat · GOV-R-001" --> CHAT
+
+    CLI -- canon-sync --> CA[collab-architecture<br><i>framework canon</i>]
+    CLI -- docker compose up --> MCP[collab-architecture-mcp<br><i>NebulaGraph · Qdrant</i>]
+    CA -- seed + ingest --> MCP
+
+    CORE -- research --> MCP
+    CORE -- "Epic + Stories" --> GH[GitHub Issues]
+
+    GH -- "GOV-R-002" --> REPOS[Target Repos]
+    REPOS -- "merge → GOV-R-003" --> BCA[collab-app-architecture<br><i>application canon</i>]
+    BCA -- ingest --> MCP
+
+    style CLI fill:#4a9eff,stroke:#2b7de9,color:#fff
+    style APP fill:#e8f4f8,stroke:#4a9eff
+```
+
+| Repository | Role | Relation to this repo |
+|------------|------|----------------------|
+| [`collab-architecture`](https://github.com/uxmaltech/collab-architecture) | Framework canon | Framework-level rules, patterns, and governance |
+| [`collab-app-architecture`](https://github.com/uxmaltech/collab-app-architecture) | Application canon | Application-specific rules, patterns, and decisions |
+| **`collab-cli`** | **Orchestrator CLI** | **This repo — infrastructure CLI — canon sync, init, domain generation** |
+| [`collab-architecture-mcp`](https://github.com/uxmaltech/collab-architecture-mcp) | MCP server | NebulaGraph + Qdrant — indexes canon for AI agents |
+| [`collab-laravel-app`](https://github.com/uxmaltech/collab-laravel-app) | Host application | Laravel app that installs the ecosystem packages |
+| [`collab-chat-ai-pkg`](https://github.com/uxmaltech/collab-chat-ai-pkg) | AI Chat package | Chat UI and prompt admin |
+| [`collab-core-pkg`](https://github.com/uxmaltech/collab-core-pkg) | Issue orchestration | AI agent pipeline for issue creation |
+| [`collab-project-manager-pkg`](https://github.com/uxmaltech/collab-project-manager-pkg) | Project manager | Project management functionality |
+
+## Prerequisites
+
+| Requirement | Version | Notes |
+|-------------|---------|-------|
+| Node.js | >= 20 | Required |
+| npm | >= 10 | Required |
+| git | any | Required for install script |
+| Docker | any | Indexed mode only |
+
+## Installation
+
+**npm (global):**
+```bash
+npm install -g @uxmaltech/collab-cli
+collab --version
+```
+
+**npx (ephemeral):**
+```bash
+npx @uxmaltech/collab-cli --help
+```
+
+**Installer script (latest-main):**
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/uxmaltech/collab-cli/main/install.sh)"
+```
+
+**Local development:**
+```bash
+npm install && npm run build
+bin/collab --help
+```
+
+**Uninstall:**
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/uxmaltech/collab-cli/main/uninstall.sh)"
+```
+
+## Quick start
+
+```bash
+collab init                          # interactive wizard
+collab init --yes                    # automatic mode (file-only, defaults)
+collab init --yes --mode indexed     # automatic with Docker infrastructure
+collab init --resume                 # resume from last failed stage
+```
+
+## Operation modes
+
+| Aspect | File-only | Indexed |
+|--------|-----------|---------|
+| **Description** | Agents read `.md` files directly | Agents query NebulaGraph + Qdrant via MCP |
+| **Docker** | Not required | Required (Qdrant, NebulaGraph, MCP server) |
+| **MCP** | No | Yes — endpoint `http://127.0.0.1:7337/mcp` |
+| **Wizard stages** | 8 | 14 |
+| **Use case** | Small projects, no Docker, quick start | Multi-repo ecosystems, large canons |
+
+**Transition heuristic:** Consider indexed mode when the canon exceeds ~50,000 tokens (~375 files).
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `collab init` | Onboarding wizard (complete setup) |
+| `collab compose generate` | Generate docker-compose files (consolidated \| split) |
+| `collab compose validate` | Validate compose files via `docker compose config` |
+| `collab infra up\|down\|status` | Manage infrastructure services (Qdrant + NebulaGraph) |
+| `collab mcp start\|stop\|status` | Manage MCP runtime service |
+| `collab up` | Full startup pipeline (infra → MCP) |
+| `collab seed` | Preflight check for infrastructure before seeding |
+| `collab doctor` | System diagnostics: config, health, and versions |
+| `collab update-canons` | Download/update canon from GitHub |
+
+## Global options
+
+| Option | Description |
+|--------|-------------|
+| `--cwd <path>` | Working directory for collab operations |
+| `--dry-run` | Preview actions without side effects |
+| `--verbose` | Detailed command logging |
+| `--quiet` | Reduce output to results and errors only |
+| `-v, --version` | Show CLI version |
+
+## AI providers
+
+| Provider | Env var | CLI detection | Default models |
+|----------|---------|---------------|----------------|
+| Codex (OpenAI) | `OPENAI_API_KEY` | `codex` | o3-pro, gpt-4.1, o4-mini |
+| Claude (Anthropic) | `ANTHROPIC_API_KEY` | `claude` | claude-sonnet-4, claude-opus-4 |
+| Gemini (Google) | `GOOGLE_AI_API_KEY` | `gemini` | gemini-2.5-pro, gemini-2.5-flash |
+| Copilot (GitHub) | — | `gh` | GitHub Copilot backend |
+
+**Auto-detection:** Providers are detected automatically if their env var is set or their CLI is in PATH.
+
+**MCP snippets:** During `collab init`, MCP configuration files are generated per provider (`claude-mcp-config.json`, `gemini-mcp-config.json`) to connect agents to the MCP server.
+
+## Wizard pipeline (`collab init`)
+
+### File-only (8 stages)
+
+1. Preflight checks (docker, node, npm, git)
+2. Environment setup (`.collab/config.json`)
+3. Assistant setup (AI provider configuration)
+4. Canon sync (download collab-architecture from GitHub)
+5. Repo scaffold (`docs/architecture` and `docs/ai` structure)
+6. Repo analysis (basic structure and dependency analysis)
+7. CI setup (GitHub Actions templates)
+8. Agent skills setup (skills and prompts registration)
+
+### Indexed (14 stages)
+
+**Phase A — Local setup (stages 1-8):** Same as file-only, but repo analysis uses AI.
+
+**Phase B — Infrastructure (stages 9-11):**
+
+9. Compose generation (docker-compose.yml or split files)
+10. Infra startup (Qdrant + NebulaGraph via Docker)
+11. MCP startup (MCP service + health checks)
+
+**Phase C — Ingestion (stages 12-14):**
+
+12. MCP client config (provider snippets)
+13. Graph seeding (initialize graph with architecture data)
+14. Canon ingest (ingest collab-architecture into Qdrant/Nebula)
+
+**Useful flags:**
+- `--resume` — resume from last incomplete stage
+- `--force` — overwrite existing config
+- `--skip-analysis` — skip code analysis
+- `--skip-ci` — skip CI generation
+- `--providers codex,claude` — specify providers
+
+## Workspace mode
+
+For multi-repo ecosystems, collab-cli automatically detects the workspace root and allows repository selection:
+
+```bash
+collab init --repos repo-a,repo-b,repo-c
+```
+
+When run from a directory containing multiple repos, the wizard presents repository selection interactively.
+
+## Local development
+
+| Script | Description |
+|--------|-------------|
+| `npm run build` | Compile TypeScript to `dist/` |
+| `npm run lint` | ESLint on `src/**/*.ts` |
+| `npm run format` | Prettier (check) |
+| `npm run format:write` | Prettier (write) |
+| `npm test` | Build + run tests |
+| `npm run test:e2e` | E2E with Docker (`collab init --mode indexed` → MCP tool call) |
+| `npm run typecheck` | TypeScript without emit |
+| `npm run pack:dry-run` | Verify npm package contents |
+
+## Project structure
+
+```
+bin/                     # executable entrypoint (bin/collab)
+src/
+  cli.ts                 # main entry point, registers commands
+  commands/              # command hierarchy (init, compose, infra, mcp, up, seed, doctor)
+  lib/                   # shared utilities (config, orchestrator, health, providers, executor)
+  stages/                # pipeline stages (preflight, canon-sync, repo-analysis, graph-seed...)
+  templates/             # compose and CI templates
+tests/                   # integration and orchestration tests
+scripts/                 # auxiliary scripts (test runner)
+docs/
+  release.md             # distribution and versioning strategy
+  ai/                    # AI agent context (brief, domain map, module map)
+  architecture/          # architectural knowledge
+ecosystem.manifest.json  # cross-repo compatibility ranges
+```
+
+## Governance and releases
+
+- [CONTRIBUTING](CONTRIBUTING.md) — contribution rules and language policy
+- [Release strategy](docs/release.md) — distribution, SemVer, CI pinning, rollback
+
+## License
+
+MIT

package/bin/collab

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const scriptPath = fs.realpathSync(process.argv[1]);
+const projectRoot = path.resolve(path.dirname(scriptPath), '..');
+const entrypoint = path.join(projectRoot, 'dist', 'index.js');
+
+require(entrypoint);

package/dist/cli.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCli = createCli;
+exports.run = run;
+const commander_1 = require("commander");
+const commands_1 = require("./commands");
+const update_checker_1 = require("./lib/update-checker");
+const version_1 = require("./lib/version");
+function createCli() {
+    const program = new commander_1.Command();
+    program
+        .name('collab')
+        .description('CLI for collaborative architecture and delivery workflows')
+        .version((0, version_1.readCliVersion)(), '-v, --version', 'Show CLI version')
+        .option('--cwd <path>', 'Working directory for collab operations')
+        .option('--dry-run', 'Preview actions without side effects')
+        .option('--verbose', 'Enable verbose command logging')
+        .option('--quiet', 'Reduce output to results and errors')
+        .showHelpAfterError(true)
+        .addHelpCommand(true);
+    // Daily update check — shows a non-blocking banner if a new version is available.
+    // Skips the upgrade command itself (it does its own check).
+    program.hook('preAction', async (_thisCommand, actionCommand) => {
+        if (actionCommand.name() === 'upgrade')
+            return;
+        await (0, update_checker_1.maybeNotifyUpdate)();
+    });
+    (0, commands_1.registerCommands)(program);
+    return program;
+}
+async function run(argv = process.argv) {
+    const program = createCli();
+    await program.parseAsync(argv);
+}

package/dist/commands/canon/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCanonCommand = registerCanonCommand;
+const rebuild_1 = require("./rebuild");
+function registerCanonCommand(program) {
+    const canon = program
+        .command('canon')
+        .description('Manage canonical architecture artifacts')
+        .addHelpText('after', `
+Examples:
+  collab canon rebuild --confirm
+  collab canon rebuild --confirm --indexes
+  collab canon rebuild --confirm --graph --dry-run
+`);
+    (0, rebuild_1.registerCanonRebuildCommand)(canon);
+}

package/dist/commands/canon/rebuild.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRebuildPipeline = buildRebuildPipeline;
+exports.registerCanonRebuildCommand = registerCanonRebuildCommand;
+const command_context_1 = require("../../lib/command-context");
+const errors_1 = require("../../lib/errors");
+const orchestrator_1 = require("../../lib/orchestrator");
+const canon_rebuild_snapshot_1 = require("../../stages/canon-rebuild-snapshot");
+const canon_rebuild_indexes_1 = require("../../stages/canon-rebuild-indexes");
+const canon_rebuild_graph_1 = require("../../stages/canon-rebuild-graph");
+const canon_rebuild_vectors_1 = require("../../stages/canon-rebuild-vectors");
+const canon_rebuild_validate_1 = require("../../stages/canon-rebuild-validate");
+/**
+ * Builds the ordered list of orchestration stages for a canon rebuild.
+ *
+ * The pipeline always starts with a snapshot and ends with validation.
+ * Middle stages depend on the workspace mode and the selective flags
+ * provided by the user.
+ */
+function buildRebuildPipeline(isFileOnly, flags) {
+    const selective = flags.graph || flags.vectors || flags.indexes;
+    const stages = [];
+    // 1. Snapshot always runs first
+    stages.push(canon_rebuild_snapshot_1.canonRebuildSnapshotStage);
+    // 2. Selective or full rebuild
+    if (!selective) {
+        // Full rebuild: all applicable stages for the mode
+        stages.push(canon_rebuild_indexes_1.canonRebuildIndexesStage);
+        if (!isFileOnly) {
+            stages.push(canon_rebuild_graph_1.canonRebuildGraphStage);
+            stages.push(canon_rebuild_vectors_1.canonRebuildVectorsStage);
+        }
+    }
+    else {
+        if (flags.indexes)
+            stages.push(canon_rebuild_indexes_1.canonRebuildIndexesStage);
+        if (flags.graph)
+            stages.push(canon_rebuild_graph_1.canonRebuildGraphStage);
+        if (flags.vectors)
+            stages.push(canon_rebuild_vectors_1.canonRebuildVectorsStage);
+    }
+    // 3. Validation always runs last
+    stages.push(canon_rebuild_validate_1.canonRebuildValidateStage);
+    return stages;
+}
+function registerCanonRebuildCommand(parent) {
+    parent
+        .command('rebuild')
+        .description('Destroy and recreate all derived canon artifacts for the current workspace')
+        .option('--confirm', 'Required flag to confirm destructive rebuild')
+        .option('--graph', 'Only rebuild graph seeds via MCP')
+        .option('--vectors', 'Only rebuild vector embeddings')
+        .option('--indexes', 'Only rebuild README/index files')
+        .addHelpText('after', `
+Examples:
+  collab canon rebuild --confirm
+  collab canon rebuild --confirm --indexes
+  collab canon rebuild --confirm --graph --vectors
+  collab canon rebuild --dry-run
+`)
+        .action(async (options, command) => {
+        const context = (0, command_context_1.createCommandContext)(command);
+        // Safety: --confirm is mandatory unless in dry-run
+        if (!options.confirm && !context.dryRun) {
+            throw new errors_1.CliError('Canon rebuild is destructive. Pass --confirm to proceed, or --dry-run to preview.');
+        }
+        const isFileOnly = context.config.mode === 'file-only';
+        const selectiveMode = options.graph || options.vectors || options.indexes;
+        // Mode-aware validation
+        if (isFileOnly && (options.graph || options.vectors)) {
+            throw new errors_1.CliError('Flags --graph and --vectors require indexed mode. ' +
+                'Current workspace is file-only. Only --indexes is available.');
+        }
+        const stages = buildRebuildPipeline(isFileOnly, options);
+        const modeLabel = isFileOnly ? 'file-only' : 'indexed';
+        const scopeLabel = selectiveMode
+            ? [options.graph && 'graph', options.vectors && 'vectors', options.indexes && 'indexes']
+                .filter(Boolean)
+                .join('+')
+            : 'full';
+        await (0, orchestrator_1.runOrchestration)({
+            workflowId: 'canon-rebuild',
+            config: context.config,
+            executor: context.executor,
+            logger: context.logger,
+            mode: `${modeLabel} (${scopeLabel})`,
+            stageOptions: {
+                rebuildGraph: !selectiveMode || Boolean(options.graph),
+                rebuildVectors: !selectiveMode || Boolean(options.vectors),
+                rebuildIndexes: !selectiveMode || Boolean(options.indexes),
+            },
+        }, stages);
+        context.logger.result('Canon rebuild complete.');
+    });
+}

package/dist/commands/compose/generate.js

@@ -0,0 +1,63 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerComposeGenerateCommand = registerComposeGenerateCommand;
+const node_path_1 = __importDefault(require("node:path"));
+const command_context_1 = require("../../lib/command-context");
+const compose_validator_1 = require("../../lib/compose-validator");
+const compose_renderer_1 = require("../../lib/compose-renderer");
+const errors_1 = require("../../lib/errors");
+function parseGenerationMode(value) {
+    if (!value || value === 'consolidated' || value === 'split') {
+        return (value ?? 'consolidated');
+    }
+    throw new errors_1.CliError(`Invalid mode '${value}'. Use 'consolidated' or 'split'.`);
+}
+function registerComposeGenerateCommand(program) {
+    program
+        .command('generate')
+        .description('Generate Docker Compose templates for collab services')
+        .option('--mode <mode>', 'Generation mode: consolidated|split', 'consolidated')
+        .option('--output <file>', 'Output path for consolidated mode')
+        .option('--output-dir <directory>', 'Output directory for generated compose files')
+        .option('--env-file <file>', 'Path to environment override file')
+        .option('--skip-validate', 'Skip docker compose validation after generation')
+        .addHelpText('after', `
+Examples:
+  collab compose generate --mode consolidated
+  collab compose generate --mode consolidated --output docker-compose.local.yml
+  collab compose generate --mode split --output-dir ./deploy
+`)
+        .action((options, command) => {
+        const context = (0, command_context_1.createCommandContext)(command);
+        const mode = parseGenerationMode(options.mode);
+        if (options.output && mode !== 'consolidated') {
+            throw new errors_1.CliError('--output can only be used with --mode consolidated.');
+        }
+        if (options.outputDir) {
+            context.executor.ensureDirectory(node_path_1.default.resolve(context.config.workspaceDir, options.outputDir));
+        }
+        const generation = (0, compose_renderer_1.generateComposeFiles)({
+            config: context.config,
+            logger: context.logger,
+            executor: context.executor,
+            mode,
+            outputDirectory: options.outputDir,
+            outputFile: options.output,
+            envFile: options.envFile,
+        });
+        for (const warning of generation.driftWarnings) {
+            context.logger.warn(warning);
+        }
+        for (const file of generation.files) {
+            context.logger.info(`Generated ${file.filePath}`);
+        }
+        context.logger.info(`Using environment file ${generation.envFilePath}`);
+        if (!options.skipValidate) {
+            (0, compose_validator_1.assertComposeFilesValid)(generation.files.map((file) => file.filePath), context.config.workspaceDir, context.executor);
+        }
+        context.logger.result('Compose generation completed successfully.');
+    });
+}

package/dist/commands/compose/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerComposeCommand = registerComposeCommand;
+const generate_1 = require("./generate");
+const validate_1 = require("./validate");
+function registerComposeCommand(program) {
+    const composeCommand = program
+        .command('compose')
+        .description('Generate and validate Docker Compose files')
+        .addHelpText('after', `
+Examples:
+  collab compose generate --mode consolidated
+  collab compose generate --mode split
+  collab compose validate --mode auto
+`);
+    (0, generate_1.registerComposeGenerateCommand)(composeCommand);
+    (0, validate_1.registerComposeValidateCommand)(composeCommand);
+}

package/dist/commands/compose/validate.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerComposeValidateCommand = registerComposeValidateCommand;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const command_context_1 = require("../../lib/command-context");
+const compose_validator_1 = require("../../lib/compose-validator");
+const compose_paths_1 = require("../../lib/compose-paths");
+const errors_1 = require("../../lib/errors");
+function parseValidateMode(value) {
+    if (!value || value === 'auto' || value === 'consolidated' || value === 'split') {
+        return (value ?? 'auto');
+    }
+    throw new errors_1.CliError(`Invalid mode '${value}'. Use 'auto', 'consolidated', or 'split'.`);
+}
+function resolveFiles(options, config, mode) {
+    if (options.file && options.file.length > 0) {
+        return options.file.map((item) => node_path_1.default.resolve(config.workspaceDir, item));
+    }
+    const paths = (0, compose_paths_1.getComposeFilePaths)(config, options.outputDir);
+    if (mode === 'consolidated') {
+        return [paths.consolidated];
+    }
+    if (mode === 'split') {
+        return [paths.infra, paths.mcp];
+    }
+    const splitExists = [paths.infra, paths.mcp].every((candidate) => node_fs_1.default.existsSync(candidate));
+    return splitExists ? [paths.infra, paths.mcp] : [paths.consolidated];
+}
+function registerComposeValidateCommand(program) {
+    program
+        .command('validate')
+        .description('Validate generated Docker Compose files via docker compose config')
+        .option('--mode <mode>', 'Validation mode: auto|consolidated|split', 'auto')
+        .option('--file <path...>', 'Explicit compose files to validate')
+        .option('--output-dir <directory>', 'Compose directory when using mode selection')
+        .addHelpText('after', `
+Examples:
+  collab compose validate --mode auto
+  collab compose validate --mode split
+  collab compose validate --file docker-compose.yml
+`)
+        .action((options, command) => {
+        const context = (0, command_context_1.createCommandContext)(command);
+        const mode = parseValidateMode(options.mode);
+        const files = resolveFiles(options, context.config, mode);
+        (0, compose_validator_1.assertComposeFilesValid)(files, context.config.workspaceDir, context.executor);
+        context.logger.result(`Compose validation successful for ${files.length} file(s).`);
+    });
+}

package/dist/commands/doctor.js

@@ -0,0 +1,153 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDoctorCommand = registerDoctorCommand;
+const node_fs_1 = __importDefault(require("node:fs"));
+const command_context_1 = require("../lib/command-context");
+const compose_defaults_1 = require("../lib/compose-defaults");
+const compose_paths_1 = require("../lib/compose-paths");
+const compose_validator_1 = require("../lib/compose-validator");
+const docker_checks_1 = require("../lib/docker-checks");
+const ecosystem_1 = require("../lib/ecosystem");
+const errors_1 = require("../lib/errors");
+const service_health_1 = require("../lib/service-health");
+const preflight_1 = require("../lib/preflight");
+function printCheck(check) {
+    const prefix = check.ok ? '[PASS]' : '[FAIL]';
+    process.stdout.write(`${prefix} ${check.id}: ${check.detail}\n`);
+    if (!check.ok && check.fix) {
+        process.stdout.write(`       fix: ${check.fix}\n`);
+    }
+}
+function registerDoctorCommand(program) {
+    program
+        .command('doctor')
+        .description('Run diagnostics across system, infra, MCP, config, and versions')
+        .addHelpText('after', `
+Examples:
+  collab doctor
+  collab doctor --verbose
+`)
+        .action(async (_options, command) => {
+        const context = (0, command_context_1.createCommandContext)(command);
+        const checks = [];
+        checks.push({
+            id: 'workspace',
+            ok: true,
+            detail: context.config.workspaceDir,
+        });
+        const preflight = (0, preflight_1.runPreflightChecks)(context.executor);
+        checks.push(...preflight.map((item) => ({
+            id: `system:${item.id}`,
+            ok: item.ok,
+            detail: item.detail,
+            fix: item.fix,
+        })));
+        // ── Docker daemon check ───────────────────────────────
+        const dockerBinaryOk = preflight.find((item) => item.id === 'docker')?.ok ?? false;
+        const daemonResult = (0, docker_checks_1.checkDockerDaemon)(context.executor);
+        const daemonFix = !dockerBinaryOk
+            ? 'Install Docker Desktop or Docker Engine.'
+            : 'Start Docker Desktop or run: sudo systemctl start docker';
+        checks.push({
+            id: 'docker:daemon',
+            ok: daemonResult.ok,
+            detail: daemonResult.ok
+                ? `Docker daemon v${daemonResult.version}`
+                : (daemonResult.error ?? 'Docker daemon unavailable'),
+            fix: daemonFix,
+        });
+        // ── Docker image checks ────────────────────────────────
+        const env = (0, service_health_1.loadRuntimeEnv)(context.config);
+        const imagesToCheck = [
+            env.MCP_IMAGE || compose_defaults_1.COMPOSE_ENV_DEFAULTS.MCP_IMAGE,
+            env.QDRANT_IMAGE || compose_defaults_1.COMPOSE_ENV_DEFAULTS.QDRANT_IMAGE,
+        ];
+        const imageResults = (0, docker_checks_1.checkDockerImages)(context.executor, imagesToCheck);
+        for (const img of imageResults) {
+            checks.push({
+                id: `docker:image:${img.image.split('/').pop()?.split(':')[0] ?? img.image}`,
+                ok: img.ok,
+                detail: img.ok ? `${img.image} available locally` : (img.error ?? `${img.image} not found`),
+                fix: img.error && !/not found locally/i.test(img.error)
+                    ? img.error
+                    : `Pull with: docker pull ${img.image}`,
+            });
+        }
+        const envFileExists = node_fs_1.default.existsSync(context.config.envFile);
+        checks.push({
+            id: 'config:env-file',
+            ok: envFileExists,
+            detail: envFileExists ? `${context.config.envFile} found` : `${context.config.envFile} missing`,
+            fix: 'Run collab init or collab compose generate to create .env defaults.',
+        });
+        const composePaths = (0, compose_paths_1.getComposeFilePaths)(context.config);
+        const composeCandidates = [composePaths.consolidated, composePaths.infra, composePaths.mcp].filter((p) => node_fs_1.default.existsSync(p));
+        if (composeCandidates.length === 0) {
+            checks.push({
+                id: 'config:compose-files',
+                ok: false,
+                detail: 'No compose files found in workspace.',
+                fix: 'Run collab compose generate first.',
+            });
+        }
+        else {
+            const errors = (0, compose_validator_1.validateComposeFiles)(composeCandidates, context.config.workspaceDir, context.executor);
+            checks.push({
+                id: 'config:compose-files',
+                ok: errors.length === 0,
+                detail: errors.length === 0
+                    ? `${composeCandidates.length} compose file(s) validated`
+                    : `${errors.length} compose validation error(s)`,
+                fix: 'Run collab compose validate to inspect exact compose errors.',
+            });
+        }
+        const infraHealth = await (0, service_health_1.waitForInfraHealth)(env, {
+            timeoutMs: 2_000,
+            retries: 1,
+            retryDelayMs: 0,
+            dryRun: context.executor.dryRun,
+        });
+        checks.push({
+            id: 'infra:qdrant-nebula',
+            ok: infraHealth.ok,
+            detail: infraHealth.ok
+                ? infraHealth.checks.join('; ')
+                : infraHealth.errors.join('; '),
+            fix: 'Run collab infra up and verify ports in .env.',
+        });
+        const mcpHealth = await (0, service_health_1.waitForMcpHealth)(env, {
+            timeoutMs: 2_000,
+            retries: 1,
+            retryDelayMs: 0,
+            dryRun: context.executor.dryRun,
+        });
+        checks.push({
+            id: 'mcp:health',
+            ok: mcpHealth.ok,
+            detail: mcpHealth.ok ? mcpHealth.checks.join('; ') : mcpHealth.errors.join('; '),
+            fix: 'Run collab mcp start and verify MCP_PORT/MCP_HOST in .env.',
+        });
+        const compatibility = await (0, ecosystem_1.checkEcosystemCompatibility)(context.config, {
+            dryRun: context.executor.dryRun,
+        });
+        checks.push(...compatibility.map((item) => ({
+            id: `version:${item.id}`,
+            ok: item.ok,
+            detail: item.detail,
+            fix: item.fix,
+        })));
+        process.stdout.write(`node: ${process.version}\n`);
+        process.stdout.write(`platform: ${process.platform}/${process.arch}\n`);
+        process.stdout.write(`docker: ${daemonResult.version ?? 'not available'}\n`);
+        for (const check of checks) {
+            printCheck(check);
+        }
+        const failed = checks.filter((item) => !item.ok);
+        if (failed.length > 0) {
+            throw new errors_1.CliError(`Doctor found ${failed.length} failing check(s).`);
+        }
+    });
+}