npm - orbital-command - Versions diffs - 1.0.1 → 1.1.0 - Mend

orbital-command 1.0.1 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (45) hide show

package/dist/assets/{zap-C9wqYMpl.js → zap-eJ3z8HRI.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{c as a}from"./index-o4ScMAuR.js";/**
+import{c as a}from"./index-DQVAzHMu.js";/**
  * @license lucide-react v0.577.0 - ISC
  *
  * This source code is licensed under the ISC license.

package/dist/index.html CHANGED Viewed

@@ -8,11 +8,11 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;600;700&family=Space+Grotesk:wght@300;400;500;600;700&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-o4ScMAuR.js"></script>
+    <script type="module" crossorigin src="/assets/index-DQVAzHMu.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/vendor-Bqt8AJn2.js">
-    <link rel="modulepreload" crossorigin href="/assets/ui-BmsSg9jU.js">
+    <link rel="modulepreload" crossorigin href="/assets/ui-QhrRH5wk.js">
     <link rel="modulepreload" crossorigin href="/assets/charts-LGLb8hyU.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-BdJ57EhC.css">
+    <link rel="stylesheet" crossorigin href="/assets/index-B-B-tTjw.css">
   </head>
   <body class="h-full">
     <div id="root" class="h-full"></div>

package/dist/server/server/index.js CHANGED Viewed

@@ -104,7 +104,14 @@ export async function startCentralServer(overrides) {
     app.use('/api/orbital', createAggregateRoutes({ projectManager, io, syncService }));
     // ─── Static File Serving ─────────────────────────────────
     const __selfDir = path.dirname(fileURLToPath(import.meta.url));
-    const distDir = path.resolve(__selfDir, '../dist');
+    // Find package root — works from both source (server/) and compiled (dist/server/server/)
+    let pkgRoot = __selfDir;
+    while (pkgRoot !== path.dirname(pkgRoot)) {
+        if (fs.existsSync(path.join(pkgRoot, 'package.json')))
+            break;
+        pkgRoot = path.dirname(pkgRoot);
+    }
+    const distDir = path.join(pkgRoot, 'dist');
     const hasBuiltFrontend = fs.existsSync(path.join(distDir, 'index.html'));
     const devMode = !hasBuiltFrontend;
     if (hasBuiltFrontend) {

package/dist/server/server/routes/sync-routes.js CHANGED Viewed

@@ -1,5 +1,11 @@
 import { Router } from 'express';
+import fs from 'fs';
+import path from 'path';
+import { execFile } from 'child_process';
 import { isValidRelativePath } from '../utils/route-helpers.js';
+import { runInit } from '../init.js';
+import { loadGlobalConfig } from '../global-config.js';
+import { getPackageVersion } from '../utils/package-info.js';
 export function createSyncRoutes({ syncService, projectManager }) {
     const router = Router();
     // ─── Sync State ─────────────────────────────────────────
@@ -130,5 +136,174 @@ export function createSyncRoutes({ syncService, projectManager }) {
             return res.status(404).json({ error: 'Project not found' });
         res.json(updated);
     });
+    // ─── Project Creation (Frontend Setup) ───────────────────
+    /** POST /projects/browse — open native folder picker (macOS) */
+    router.post('/projects/browse', (_req, res) => {
+        if (process.platform !== 'darwin') {
+            return res.json({ error: 'not_supported' });
+        }
+        execFile('osascript', ['-e', 'POSIX path of (choose folder with prompt "Select your project folder")'], { timeout: 60_000 }, (err, stdout) => {
+            if (err) {
+                // User pressed Cancel — osascript exits with code 1
+                if (err.code === 1) {
+                    return res.json({ cancelled: true });
+                }
+                return res.json({ error: err.message });
+            }
+            const selectedPath = stdout.trim();
+            if (!selectedPath)
+                return res.json({ cancelled: true });
+            res.json({ path: selectedPath });
+        });
+    });
+    /** POST /projects/check-path — validate a path and detect git status */
+    router.post('/projects/check-path', (req, res) => {
+        const { path: rawPath } = req.body;
+        if (!rawPath || !rawPath.trim()) {
+            return res.json({ valid: false, error: 'Path is required' });
+        }
+        const absPath = path.resolve(rawPath.trim());
+        if (!fs.existsSync(absPath)) {
+            return res.json({ valid: false, absPath, error: 'Directory does not exist' });
+        }
+        try {
+            const stat = fs.statSync(absPath);
+            if (!stat.isDirectory()) {
+                return res.json({ valid: false, absPath, error: 'Path must be a directory' });
+            }
+        }
+        catch {
+            return res.json({ valid: false, absPath, error: 'Cannot access path' });
+        }
+        const hasGit = fs.existsSync(path.join(absPath, '.git'));
+        const suggestedName = path.basename(absPath)
+            .replace(/[-_]/g, ' ')
+            .replace(/\b\w/g, c => c.toUpperCase());
+        // Check if already registered
+        const config = loadGlobalConfig();
+        const alreadyRegistered = config.projects.some(p => p.path === absPath);
+        res.json({
+            valid: true,
+            absPath,
+            hasGit,
+            suggestedName,
+            alreadyRegistered,
+        });
+    });
+    /** POST /projects/create — full project initialization (init + register + seed) */
+    router.post('/projects/create', async (req, res) => {
+        const { path: rawPath, name, color, preset, initGit } = req.body;
+        if (!rawPath || !name || !color) {
+            return res.status(400).json({ error: 'path, name, and color are required' });
+        }
+        const absPath = path.resolve(rawPath.trim());
+        // Validate directory exists
+        if (!fs.existsSync(absPath) || !fs.statSync(absPath).isDirectory()) {
+            return res.status(400).json({ error: 'Path must be an existing directory' });
+        }
+        // Check if already registered
+        const config = loadGlobalConfig();
+        if (config.projects.some(p => p.path === absPath)) {
+            return res.status(409).json({ error: 'A project is already registered at this path' });
+        }
+        try {
+            // 1. Optional git init
+            if (initGit && !fs.existsSync(path.join(absPath, '.git'))) {
+                await new Promise((resolve, reject) => {
+                    execFile('git', ['init'], { cwd: absPath, timeout: 10_000 }, (err) => {
+                        if (err)
+                            reject(new Error(`git init failed: ${err.message}`));
+                        else
+                            resolve();
+                    });
+                });
+            }
+            // 2. Run full project init (templates, hooks, skills, agents, config, etc.)
+            const selectedPreset = preset || 'default';
+            runInit(absPath, {
+                quiet: true,
+                preset: selectedPreset,
+                projectName: name,
+            });
+            // 3. Stamp template version
+            const pkgVersion = getPackageVersion();
+            const configPath = path.join(absPath, '.claude', 'orbital.config.json');
+            if (fs.existsSync(configPath)) {
+                try {
+                    const projConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+                    projConfig.templateVersion = pkgVersion;
+                    const tmp = configPath + `.tmp.${process.pid}`;
+                    fs.writeFileSync(tmp, JSON.stringify(projConfig, null, 2) + '\n', 'utf8');
+                    fs.renameSync(tmp, configPath);
+                }
+                catch { /* ignore malformed config */ }
+            }
+            // 4. Register + initialize context + emit socket event
+            const summary = await projectManager.addProject(absPath, { name, color });
+            // 5. Seed welcome scope card
+            seedWelcomeCard(absPath, selectedPreset);
+            res.status(201).json(summary);
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
     return router;
 }
+// ─── Helpers ──────────────────────────────────────────────
+function seedWelcomeCard(projectRoot, preset) {
+    // Determine the planning directory from the preset
+    const presetsDir = path.join(path.dirname(path.dirname(new URL(import.meta.url).pathname)), 'templates', 'presets');
+    let planningDir = 'planning'; // default fallback
+    try {
+        const presetPath = path.join(presetsDir, `${preset}.json`);
+        if (fs.existsSync(presetPath)) {
+            const workflow = JSON.parse(fs.readFileSync(presetPath, 'utf8'));
+            // Find the first list that has a directory and isn't an entry point
+            const entryId = workflow.entryPoint;
+            const entryList = workflow.lists?.find((l) => l.id === entryId);
+            // Use the first forward target of the entry point, or the second list
+            if (entryList?.forwardTargets?.[0]) {
+                planningDir = entryList.forwardTargets[0];
+            }
+            else if (workflow.lists?.[1]?.hasDirectory) {
+                planningDir = workflow.lists[1].id;
+            }
+        }
+    }
+    catch { /* use default */ }
+    const scopesDir = path.join(projectRoot, 'scopes', planningDir);
+    if (!fs.existsSync(scopesDir)) {
+        fs.mkdirSync(scopesDir, { recursive: true });
+    }
+    const cardPath = path.join(scopesDir, '001-welcome.md');
+    if (fs.existsSync(cardPath))
+        return; // don't overwrite
+    const content = `---
+title: Welcome to Orbital Command
+status: ${planningDir}
+priority: low
+tags: [onboarding]
+---
+# Welcome to Orbital Command
+Your project is set up and ready to go. Here are some things to try:
+## Getting Started
+1. **Create a scope** — Scopes are units of work. Use \`/scope-create\` in Claude Code or create a markdown file in the \`scopes/\` directory.
+2. **Explore the dashboard** — Use the sidebar to navigate between views: Kanban, Primitives, Guards, Repo, Sessions, and Workflow.
+3. **Launch a session** — Start a Claude Code session from the Sessions view to begin working on this scope.
+## Key Concepts
+- **Scopes** are markdown files with YAML frontmatter that track units of work
+- **Workflow** defines the columns and transitions on your Kanban board
+- **Guards** enforce quality gates before status transitions
+- **Primitives** are the hooks, skills, and agents that power your setup
+You can archive this card once you're comfortable with the basics.
+`;
+    fs.writeFileSync(cardPath, content, 'utf8');
+}

package/dist/server/server/wizard/index.js CHANGED Viewed

@@ -18,7 +18,6 @@ import { phaseWelcome } from './phases/welcome.js';
 import { phaseProjectSetup } from './phases/project-setup.js';
 import { phaseWorkflowSetup } from './phases/workflow-setup.js';
 import { phaseConfirm, showPostInstall } from './phases/confirm.js';
-import { NOTES } from './ui.js';
 import { runConfigEditor } from './config-editor.js';
 import { runDoctor } from './doctor.js';
 import { isITerm2Available } from '../adapters/iterm2-adapter.js';
@@ -26,24 +25,14 @@ import { registerProject } from '../global-config.js';
 export { runConfigEditor, runDoctor };
 // ─── Phase 1: Setup Wizard ─────────────────────────────────────
 /**
- * First-time setup. Creates ~/.orbital/, seeds primitives,
- * optionally links projects (running Phase 2 for each).
+ * First-time setup. Creates ~/.orbital/ and seeds primitives.
+ * Project setup is now handled by the frontend Add Project modal.
  */
 export async function runSetupWizard(packageVersion) {
     const state = buildSetupState(packageVersion);
     p.intro(`${pc.bgCyan(pc.black(' Orbital Command '))} ${pc.dim(`v${packageVersion}`)}`);
     await phaseSetupWizard(state);
-    // If user linked projects, run Phase 2 for each
-    for (const projectRoot of state.linkedProjects) {
-        p.log.step(`Setting up ${pc.cyan(path.basename(projectRoot))}...`);
-        await runProjectSetupInline(projectRoot, packageVersion);
-    }
-    if (state.linkedProjects.length === 0) {
-        p.note(NOTES.setupComplete, 'Done');
-    }
-    p.outro(state.linkedProjects.length > 0
-        ? `Run ${pc.cyan('orbital')} to launch the dashboard.`
-        : `Run ${pc.cyan('orbital')} in a project directory to get started.`);
+    p.outro(`Run ${pc.cyan('orbital')} to launch the dashboard and add your first project.`);
 }
 // ─── Phase 2: Project Setup ────────────────────────────────────
 /**
@@ -94,21 +83,26 @@ async function runProjectPhases(state, useForce) {
     }
     showPostInstall(state);
 }
-/**
- * Inline project setup — called from Phase 1 when user links a project.
- * Skips intro/outro since the setup wizard already has those.
- */
-async function runProjectSetupInline(projectRoot, packageVersion) {
-    const state = buildProjectState(projectRoot, packageVersion);
-    // Skip welcome gate for inline — this is a fresh project being linked
-    await runProjectPhases(state, false);
+/** Returns true if `a` is older than `b` (semver comparison). */
+function isOlderThan(a, b) {
+    const pa = a.match(/^(\d+)\.(\d+)\.(\d+)/);
+    const pb = b.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!pa || !pb)
+        return false;
+    for (let i = 1; i <= 3; i++) {
+        if (parseInt(pa[i]) < parseInt(pb[i]))
+            return true;
+        if (parseInt(pa[i]) > parseInt(pb[i]))
+            return false;
+    }
+    return false;
 }
 async function checkForUpdate(currentVersion, cache) {
     // Use cache if checked within 24 hours
     if (cache.lastUpdateCheck && cache.latestVersion) {
         const age = Date.now() - new Date(cache.lastUpdateCheck).getTime();
         if (age < 24 * 60 * 60 * 1000) {
-            const isOutdated = cache.latestVersion !== currentVersion;
+            const isOutdated = isOlderThan(currentVersion, cache.latestVersion);
             return {
                 info: { current: currentVersion, latest: cache.latestVersion, isOutdated },
                 cacheChanged: false,
@@ -123,7 +117,7 @@ async function checkForUpdate(currentVersion, cache) {
         const data = await res.json();
         const latest = data.version;
         return {
-            info: { current: currentVersion, latest, isOutdated: latest !== currentVersion },
+            info: { current: currentVersion, latest, isOutdated: isOlderThan(currentVersion, latest) },
             cacheChanged: true,
         };
     }

package/dist/server/server/wizard/phases/setup-wizard.js CHANGED Viewed

@@ -6,10 +6,9 @@
  */
 import fs from 'fs';
 import * as p from '@clack/prompts';
-import pc from 'picocolors';
 import { NOTES } from '../ui.js';
-import { isValidProjectPath, resolveProjectPath, ORBITAL_HOME } from '../detect.js';
-export async function phaseSetupWizard(state) {
+import { ORBITAL_HOME } from '../detect.js';
+export async function phaseSetupWizard(_state) {
     // Welcome and core concepts
     p.note(NOTES.setupWelcome, 'Welcome');
     // Create ~/.orbital/ and seed primitives
@@ -32,35 +31,6 @@ export async function phaseSetupWizard(state) {
         p.log.error(err instanceof Error ? err.message : String(err));
         process.exit(1);
     }
-    // Offer to link projects
-    p.note(NOTES.addProject, 'Projects');
-    let addMore = true;
-    while (addMore) {
-        const wantsProject = await p.confirm({
-            message: state.linkedProjects.length === 0
-                ? 'Add a project now?'
-                : 'Add another project?',
-            initialValue: state.linkedProjects.length === 0,
-        });
-        if (p.isCancel(wantsProject) || !wantsProject) {
-            addMore = false;
-            break;
-        }
-        const projectPath = await p.text({
-            message: 'Project path',
-            placeholder: '~/Code/my-project',
-            validate: (val) => {
-                if (!val || !val.trim())
-                    return 'Path is required';
-                return isValidProjectPath(val.trim());
-            },
-        });
-        if (p.isCancel(projectPath)) {
-            addMore = false;
-            break;
-        }
-        const resolved = resolveProjectPath(projectPath.trim());
-        state.linkedProjects.push(resolved);
-        p.log.success(`Added: ${pc.cyan(resolved)}`);
-    }
+    // Direct user to the dashboard for project setup
+    p.note('Launch the dashboard to add your first project.\nThe setup wizard will guide you through it.', 'Next Steps');
 }

package/dist/server/server/wizard/types.js CHANGED Viewed

@@ -5,25 +5,4 @@
  *   Phase 1 (SetupState)        — first-time Orbital setup, ~/.orbital/ creation
  *   Phase 2 (ProjectSetupState) — per-project scaffolding into .claude/
  */
-export const WORKFLOW_PRESETS = [
-    {
-        value: 'default',
-        label: 'Default',
-        hint: '7 lists, trunk-based — Icebox → Planning → Backlog → Implementing → Review → Completed → Main',
-    },
-    {
-        value: 'minimal',
-        label: 'Minimal',
-        hint: '3 lists — To Do → In Progress → Done',
-    },
-    {
-        value: 'development',
-        label: 'Development',
-        hint: '5 lists, dev branch — Backlog → Implementing → Review → Completed → Dev',
-    },
-    {
-        value: 'gitflow',
-        label: 'Gitflow',
-        hint: '9 lists, multi-branch — Full pipeline with Dev, Staging, and Production',
-    },
-];
+export { WORKFLOW_PRESETS } from '../../shared/workflow-presets.js';

package/dist/server/shared/workflow-presets.js ADDED Viewed

@@ -0,0 +1,22 @@
+export const WORKFLOW_PRESETS = [
+    {
+        value: 'default',
+        label: 'Default',
+        hint: '7 lists, trunk-based — Icebox → Planning → Backlog → Implementing → Review → Completed → Main',
+    },
+    {
+        value: 'minimal',
+        label: 'Minimal',
+        hint: '3 lists — To Do → In Progress → Done',
+    },
+    {
+        value: 'development',
+        label: 'Development',
+        hint: '5 lists, dev branch — Backlog → Implementing → Review → Completed → Dev',
+    },
+    {
+        value: 'gitflow',
+        label: 'Gitflow',
+        hint: '9 lists, multi-branch — Full pipeline with Dev, Staging, and Production',
+    },
+];

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "orbital-command",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Orbital Command — mission control dashboard for Claude Code projects",
   "type": "module",
   "license": "MIT",

package/server/index.ts CHANGED Viewed

@@ -148,7 +148,13 @@ export async function startCentralServer(overrides?: CentralServerOverrides): Pr
   // ─── Static File Serving ─────────────────────────────────
   const __selfDir = path.dirname(fileURLToPath(import.meta.url));
-  const distDir = path.resolve(__selfDir, '../dist');
+  // Find package root — works from both source (server/) and compiled (dist/server/server/)
+  let pkgRoot = __selfDir;
+  while (pkgRoot !== path.dirname(pkgRoot)) {
+    if (fs.existsSync(path.join(pkgRoot, 'package.json'))) break;
+    pkgRoot = path.dirname(pkgRoot);
+  }
+  const distDir = path.join(pkgRoot, 'dist');
   const hasBuiltFrontend = fs.existsSync(path.join(distDir, 'index.html'));
   const devMode = !hasBuiltFrontend;
   if (hasBuiltFrontend) {

package/server/routes/sync-routes.ts CHANGED Viewed

@@ -1,7 +1,13 @@
 import { Router } from 'express';
+import fs from 'fs';
+import path from 'path';
+import { execFile } from 'child_process';
 import type { SyncService } from '../services/sync-service.js';
 import type { ProjectManager } from '../project-manager.js';
 import { isValidRelativePath } from '../utils/route-helpers.js';
+import { runInit } from '../init.js';
+import { loadGlobalConfig } from '../global-config.js';
+import { getPackageVersion } from '../utils/package-info.js';
 interface SyncRouteDeps {
   syncService: SyncService;
@@ -171,5 +177,204 @@ export function createSyncRoutes({ syncService, projectManager }: SyncRouteDeps)
     res.json(updated);
   });
+  // ─── Project Creation (Frontend Setup) ───────────────────
+  /** POST /projects/browse — open native folder picker (macOS) */
+  router.post('/projects/browse', (_req, res) => {
+    if (process.platform !== 'darwin') {
+      return res.json({ error: 'not_supported' });
+    }
+    execFile(
+      'osascript',
+      ['-e', 'POSIX path of (choose folder with prompt "Select your project folder")'],
+      { timeout: 60_000 },
+      (err, stdout) => {
+        if (err) {
+          // User pressed Cancel — osascript exits with code 1
+          if (err.code === 1) {
+            return res.json({ cancelled: true });
+          }
+          return res.json({ error: err.message });
+        }
+        const selectedPath = stdout.trim();
+        if (!selectedPath) return res.json({ cancelled: true });
+        res.json({ path: selectedPath });
+      },
+    );
+  });
+  /** POST /projects/check-path — validate a path and detect git status */
+  router.post('/projects/check-path', (req, res) => {
+    const { path: rawPath } = req.body as { path: string };
+    if (!rawPath || !rawPath.trim()) {
+      return res.json({ valid: false, error: 'Path is required' });
+    }
+    const absPath = path.resolve(rawPath.trim());
+    if (!fs.existsSync(absPath)) {
+      return res.json({ valid: false, absPath, error: 'Directory does not exist' });
+    }
+    try {
+      const stat = fs.statSync(absPath);
+      if (!stat.isDirectory()) {
+        return res.json({ valid: false, absPath, error: 'Path must be a directory' });
+      }
+    } catch {
+      return res.json({ valid: false, absPath, error: 'Cannot access path' });
+    }
+    const hasGit = fs.existsSync(path.join(absPath, '.git'));
+    const suggestedName = path.basename(absPath)
+      .replace(/[-_]/g, ' ')
+      .replace(/\b\w/g, c => c.toUpperCase());
+    // Check if already registered
+    const config = loadGlobalConfig();
+    const alreadyRegistered = config.projects.some(p => p.path === absPath);
+    res.json({
+      valid: true,
+      absPath,
+      hasGit,
+      suggestedName,
+      alreadyRegistered,
+    });
+  });
+  /** POST /projects/create — full project initialization (init + register + seed) */
+  router.post('/projects/create', async (req, res) => {
+    const { path: rawPath, name, color, preset, initGit } = req.body as {
+      path: string;
+      name: string;
+      color: string;
+      preset?: string;
+      initGit?: boolean;
+    };
+    if (!rawPath || !name || !color) {
+      return res.status(400).json({ error: 'path, name, and color are required' });
+    }
+    const absPath = path.resolve(rawPath.trim());
+    // Validate directory exists
+    if (!fs.existsSync(absPath) || !fs.statSync(absPath).isDirectory()) {
+      return res.status(400).json({ error: 'Path must be an existing directory' });
+    }
+    // Check if already registered
+    const config = loadGlobalConfig();
+    if (config.projects.some(p => p.path === absPath)) {
+      return res.status(409).json({ error: 'A project is already registered at this path' });
+    }
+    try {
+      // 1. Optional git init
+      if (initGit && !fs.existsSync(path.join(absPath, '.git'))) {
+        await new Promise<void>((resolve, reject) => {
+          execFile('git', ['init'], { cwd: absPath, timeout: 10_000 }, (err) => {
+            if (err) reject(new Error(`git init failed: ${err.message}`));
+            else resolve();
+          });
+        });
+      }
+      // 2. Run full project init (templates, hooks, skills, agents, config, etc.)
+      const selectedPreset = preset || 'default';
+      runInit(absPath, {
+        quiet: true,
+        preset: selectedPreset,
+        projectName: name,
+      });
+      // 3. Stamp template version
+      const pkgVersion = getPackageVersion();
+      const configPath = path.join(absPath, '.claude', 'orbital.config.json');
+      if (fs.existsSync(configPath)) {
+        try {
+          const projConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+          projConfig.templateVersion = pkgVersion;
+          const tmp = configPath + `.tmp.${process.pid}`;
+          fs.writeFileSync(tmp, JSON.stringify(projConfig, null, 2) + '\n', 'utf8');
+          fs.renameSync(tmp, configPath);
+        } catch { /* ignore malformed config */ }
+      }
+      // 4. Register + initialize context + emit socket event
+      const summary = await projectManager.addProject(absPath, { name, color });
+      // 5. Seed welcome scope card
+      seedWelcomeCard(absPath, selectedPreset);
+      res.status(201).json(summary);
+    } catch (err) {
+      res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+    }
+  });
   return router;
 }
+// ─── Helpers ──────────────────────────────────────────────
+function seedWelcomeCard(projectRoot: string, preset: string): void {
+  // Determine the planning directory from the preset
+  const presetsDir = path.join(path.dirname(path.dirname(new URL(import.meta.url).pathname)), 'templates', 'presets');
+  let planningDir = 'planning'; // default fallback
+  try {
+    const presetPath = path.join(presetsDir, `${preset}.json`);
+    if (fs.existsSync(presetPath)) {
+      const workflow = JSON.parse(fs.readFileSync(presetPath, 'utf8'));
+      // Find the first list that has a directory and isn't an entry point
+      const entryId = workflow.entryPoint;
+      const entryList = workflow.lists?.find((l: { id: string }) => l.id === entryId);
+      // Use the first forward target of the entry point, or the second list
+      if (entryList?.forwardTargets?.[0]) {
+        planningDir = entryList.forwardTargets[0];
+      } else if (workflow.lists?.[1]?.hasDirectory) {
+        planningDir = workflow.lists[1].id;
+      }
+    }
+  } catch { /* use default */ }
+  const scopesDir = path.join(projectRoot, 'scopes', planningDir);
+  if (!fs.existsSync(scopesDir)) {
+    fs.mkdirSync(scopesDir, { recursive: true });
+  }
+  const cardPath = path.join(scopesDir, '001-welcome.md');
+  if (fs.existsSync(cardPath)) return; // don't overwrite
+  const content = `---
+title: Welcome to Orbital Command
+status: ${planningDir}
+priority: low
+tags: [onboarding]
+---
+# Welcome to Orbital Command
+Your project is set up and ready to go. Here are some things to try:
+## Getting Started
+1. **Create a scope** — Scopes are units of work. Use \`/scope-create\` in Claude Code or create a markdown file in the \`scopes/\` directory.
+2. **Explore the dashboard** — Use the sidebar to navigate between views: Kanban, Primitives, Guards, Repo, Sessions, and Workflow.
+3. **Launch a session** — Start a Claude Code session from the Sessions view to begin working on this scope.
+## Key Concepts
+- **Scopes** are markdown files with YAML frontmatter that track units of work
+- **Workflow** defines the columns and transitions on your Kanban board
+- **Guards** enforce quality gates before status transitions
+- **Primitives** are the hooks, skills, and agents that power your setup
+You can archive this card once you're comfortable with the basics.
+`;
+  fs.writeFileSync(cardPath, content, 'utf8');
+}