feat(cli): setup overhaul + archon doctor + complete bundled skill

CLAUDE.md

@@ -152,7 +152,7 @@ bun run format:check
 bun run validate
 ```
 
-This runs `check:bundled`, type-check, lint, format check, and tests. All five must pass for CI to succeed.
+This runs `check:bundled`, `check:bundled-skill`, type-check, lint, format check, and tests. All six must pass for CI to succeed.
 
 ### ESLint Guidelines
 
@@ -257,6 +257,9 @@ bun run cli serve --download-only  # Download without starting
 bun run cli skill install
 bun run cli skill install /path/to/project
 
+# Verify your Archon setup (Claude binary, gh auth, DB, adapters)
+bun run cli doctor
+
 # Show version
 bun run cli version
 ```
@@ -723,7 +726,7 @@ async function createSession(conversationId: string, codebaseId: string) {
 - Source builds: Loaded from filesystem at runtime
 - Merged with repo-specific commands/workflows (repo overrides defaults by name)
 - Opt-out: Set `defaults.loadDefaultCommands: false` or `defaults.loadDefaultWorkflows: false` in `.archon/config.yaml`
-- **After adding, removing, or editing a default file, run `bun run generate:bundled`** to refresh the embedded bundle. `bun run validate` (and CI) run `check:bundled` and will fail loudly if the generated file is stale.
+- **After adding, removing, or editing a default file, run `bun run generate:bundled`** to refresh the embedded bundle. `bun run validate` (and CI) run `check:bundled` and `check:bundled-skill` and will fail loudly if either generated file is stale.
 
 **Home-scoped ("global") workflows, commands, and scripts** (user-level, applies to every project):
 - Workflows: `~/.archon/workflows/` (or `$ARCHON_HOME/workflows/`)

package.json

@@ -16,6 +16,7 @@
     "build:checksums": "bash scripts/checksums.sh",
     "generate:bundled": "bun run scripts/generate-bundled-defaults.ts",
     "check:bundled": "bun run scripts/generate-bundled-defaults.ts --check",
+    "check:bundled-skill": "bun run scripts/check-bundled-skill.ts --check",
     "test": "bun --filter '*' --parallel test",
     "test:watch": "bun --filter @archon/server test:watch",
     "type-check": "bun --filter '*' type-check && bun x tsc --noEmit -p scripts/tsconfig.json",
@@ -27,7 +28,7 @@
     "build:web": "bun --filter @archon/web build",
     "dev:docs": "bun --filter @archon/docs-web dev",
     "build:docs": "bun --filter @archon/docs-web build",
-    "validate": "bun run check:bundled && bun run type-check && bun run lint --max-warnings 0 && bun run format:check && bun run test",
+    "validate": "bun run check:bundled && bun run check:bundled-skill && bun run type-check && bun run lint --max-warnings 0 && bun run format:check && bun run test",
     "prepare": "husky",
     "setup-auth": "bun --filter @archon/server setup-auth"
   },

packages/cli/package.json

@@ -8,7 +8,7 @@
   },
   "scripts": {
     "cli": "bun src/cli.ts",
-    "test": "bun test src/commands/version.test.ts src/commands/setup.test.ts src/commands/skill.test.ts && bun test src/commands/workflow.test.ts && bun test src/commands/isolation.test.ts && bun test src/commands/chat.test.ts && bun test src/commands/serve.test.ts",
+    "test": "bun test src/commands/version.test.ts src/commands/setup.test.ts src/commands/skill.test.ts src/commands/doctor.test.ts && bun test src/commands/workflow.test.ts && bun test src/commands/isolation.test.ts && bun test src/commands/chat.test.ts && bun test src/commands/serve.test.ts",
     "type-check": "bun x tsc --noEmit"
   },
   "dependencies": {

packages/cli/src/bundled-skill.ts

@@ -9,7 +9,7 @@
  */
 
 // =============================================================================
-// Skill Files (18 total)
+// Skill Files (21 total)
 // =============================================================================
 
 import skillMd from '../../../.claude/skills/archon/SKILL.md' with { type: 'text' };
@@ -26,8 +26,11 @@ import telegramGuide from '../../../.claude/skills/archon/guides/telegram.md' wi
 import authoringCommands from '../../../.claude/skills/archon/references/authoring-commands.md' with { type: 'text' };
 import cliCommands from '../../../.claude/skills/archon/references/cli-commands.md' with { type: 'text' };
 import dagAdvanced from '../../../.claude/skills/archon/references/dag-advanced.md' with { type: 'text' };
+import goodPractices from '../../../.claude/skills/archon/references/good-practices.md' with { type: 'text' };
 import interactiveWorkflows from '../../../.claude/skills/archon/references/interactive-workflows.md' with { type: 'text' };
+import parameterMatrix from '../../../.claude/skills/archon/references/parameter-matrix.md' with { type: 'text' };
 import repoInit from '../../../.claude/skills/archon/references/repo-init.md' with { type: 'text' };
+import troubleshooting from '../../../.claude/skills/archon/references/troubleshooting.md' with { type: 'text' };
 import variables from '../../../.claude/skills/archon/references/variables.md' with { type: 'text' };
 import workflowDag from '../../../.claude/skills/archon/references/workflow-dag.md' with { type: 'text' };
 
@@ -53,8 +56,11 @@ export const BUNDLED_SKILL_FILES: Record<string, string> = {
   'references/authoring-commands.md': authoringCommands,
   'references/cli-commands.md': cliCommands,
   'references/dag-advanced.md': dagAdvanced,
+  'references/good-practices.md': goodPractices,
   'references/interactive-workflows.md': interactiveWorkflows,
+  'references/parameter-matrix.md': parameterMatrix,
   'references/repo-init.md': repoInit,
+  'references/troubleshooting.md': troubleshooting,
   'references/variables.md': variables,
   'references/workflow-dag.md': workflowDag,
 };

packages/cli/src/cli.ts

@@ -65,6 +65,7 @@ import { setupCommand } from './commands/setup';
 import { skillInstallCommand } from './commands/skill';
 import { validateWorkflowsCommand, validateCommandsCommand } from './commands/validate';
 import { serveCommand } from './commands/serve';
+import { doctorCommand } from './commands/doctor';
 import { closeDatabase } from '@archon/core';
 import {
   setLogLevel,
@@ -106,6 +107,7 @@ Commands:
   complete <branch> [...]    Complete branch lifecycle (remove worktree + branches)
   serve                      Start the web UI server (downloads web UI on first run)
   skill install [path]       Install the bundled Archon skill into .claude/skills/archon
+  doctor                     Verify your Archon setup (Claude binary, gh auth, DB, adapters)
   validate workflows [name]  Validate workflow definitions and their references
   validate commands [name]   Validate command files
   version, --version, -V     Show version info (also -v when used alone)
@@ -267,7 +269,16 @@ async function main(): Promise<number> {
   const subcommand = positionals[1];
 
   // Commands that don't require git repo validation
-  const noGitCommands = ['version', 'help', 'setup', 'chat', 'continue', 'serve', 'skill'];
+  const noGitCommands = [
+    'version',
+    'help',
+    'setup',
+    'chat',
+    'continue',
+    'serve',
+    'skill',
+    'doctor',
+  ];
   const requiresGitRepo = !noGitCommands.includes(command ?? '');
 
   try {
@@ -600,6 +611,10 @@ async function main(): Promise<number> {
         return await serveCommand({ port: servePort, downloadOnly });
       }
 
+      case 'doctor': {
+        return await doctorCommand();
+      }
+
       case 'skill': {
         switch (subcommand) {
           case 'install': {