yggtree 1.4.4 → 1.4.6

package/dist/commands/wt/enter.js

@@ -3,6 +3,7 @@ import { spawn } from 'child_process';
 import { execa } from 'execa';
 import chalk from 'chalk';
 import { listWorktrees } from '../../lib/git.js';
+import { getManagedWorktreesRoot } from '../../lib/global-config.js';
 import { log, ui } from '../../lib/ui.js';
 import { ensureRepoContext } from '../../lib/repo-context.js';
 import { detectWorktreeType, findWorktreeByName, formatWorktreeDisplayPath, formatWorktreeType, getWorktreeBranchName, } from '../../lib/worktree.js';
@@ -37,16 +38,17 @@ function formatChoiceLabel(type, branchName, displayPath, terminalColumns) {
 }
 export async function enterCommand(wtName, options = {}) {
     try {
-        await ensureRepoContext();
+        const repoRoot = await ensureRepoContext();
         const worktrees = await listWorktrees();
         const mainWorktreePath = worktrees[0]?.path || '';
+        const managedRoot = await getManagedWorktreesRoot(repoRoot);
         if (worktrees.length === 0) {
             log.info('No worktrees found.');
             return;
         }
         let targetWt;
         if (wtName) {
-            targetWt = findWorktreeByName(worktrees, wtName);
+            targetWt = findWorktreeByName(worktrees, wtName, managedRoot);
             if (!targetWt) {
                 log.error(`Worktree "${wtName}" not found.`);
                 return;
@@ -56,9 +58,9 @@ export async function enterCommand(wtName, options = {}) {
             // Interactive Selection
             const terminalColumns = process.stdout.columns || 100;
             const choices = await Promise.all(worktrees.map(async (wt) => {
-                const type = await detectWorktreeType(wt, mainWorktreePath);
+                const type = await detectWorktreeType(wt, mainWorktreePath, managedRoot);
                 const branchName = getWorktreeBranchName(wt);
-                const displayPath = formatWorktreeDisplayPath(wt.path);
+                const displayPath = formatWorktreeDisplayPath(wt.path, managedRoot);
                 return {
                     name: formatChoiceLabel(type, branchName, displayPath, terminalColumns),
                     value: wt

package/dist/commands/wt/exec.js

@@ -1,6 +1,7 @@
 import inquirer from 'inquirer';
 import { execa } from 'execa';
 import { listWorktrees, getRepoRoot } from '../../lib/git.js';
+import { getManagedWorktreesRoot } from '../../lib/global-config.js';
 import { log } from '../../lib/ui.js';
 import { findWorktreeByName, formatWorktreeDisplayPath, getWorktreeBranchName } from '../../lib/worktree.js';
 export async function execCommand(wtName, commandArgs) {
@@ -8,14 +9,15 @@ export async function execCommand(wtName, commandArgs) {
     let command = '';
     let args = [];
     try {
-        await getRepoRoot();
+        const repoRoot = await getRepoRoot();
         const worktrees = await listWorktrees();
+        const managedRoot = await getManagedWorktreesRoot(repoRoot);
         if (worktrees.length === 0) {
             log.info('No worktrees found.');
             return;
         }
         if (wtName) {
-            targetWt = findWorktreeByName(worktrees, wtName);
+            targetWt = findWorktreeByName(worktrees, wtName, managedRoot);
             if (!targetWt) {
                 log.error(`Worktree "${wtName}" not found.`);
                 return;
@@ -25,7 +27,7 @@ export async function execCommand(wtName, commandArgs) {
             // Interactive Selection
             const choices = worktrees.map(wt => {
                 const branchName = getWorktreeBranchName(wt);
-                const displayPath = formatWorktreeDisplayPath(wt.path);
+                const displayPath = formatWorktreeDisplayPath(wt.path, managedRoot);
                 return {
                     name: `${branchName.padEnd(20)} ${displayPath}`,
                     value: wt

package/dist/commands/wt/list.js

@@ -1,12 +1,14 @@
 import chalk from 'chalk';
 import { listWorktrees, getRepoRoot, isGitClean, getLastActivity, isGhAvailable, getPrStatusBatch } from '../../lib/git.js';
+import { getManagedWorktreesRoot } from '../../lib/global-config.js';
 import { log, timeAgo } from '../../lib/ui.js';
 import { detectWorktreeType, formatWorktreeType, formatPrStatus, getWorktreeBranchName, WORKTREE_TYPE_ORDER, } from '../../lib/worktree.js';
 export async function listCommand() {
     try {
-        await getRepoRoot(); // Verify we are in a git repo
+        const repoRoot = await getRepoRoot(); // Verify we are in a git repo
         const worktrees = await listWorktrees();
         const mainWorktreePath = worktrees[0]?.path || '';
+        const managedRoot = await getManagedWorktreesRoot(repoRoot);
         if (worktrees.length === 0) {
             log.info('No worktrees found.');
             return;
@@ -24,7 +26,7 @@ export async function listCommand() {
         console.log(chalk.dim('  ' + '-'.repeat(showPr ? 90 : 70)));
         const rows = await Promise.all(worktrees.map(async (wt, index) => {
             const [typeKey, isClean, lastActive] = await Promise.all([
-                detectWorktreeType(wt, mainWorktreePath),
+                detectWorktreeType(wt, mainWorktreePath, managedRoot),
                 isGitClean(wt.path),
                 getLastActivity(wt.path),
             ]);

package/dist/commands/wt/open.js

@@ -5,6 +5,7 @@ import fs from 'fs-extra';
 import { constants as fsConstants } from 'fs';
 import { execa } from 'execa';
 import { listWorktrees, getRepoRoot } from '../../lib/git.js';
+import { getManagedWorktreesRoot } from '../../lib/global-config.js';
 import { log, ui } from '../../lib/ui.js';
 import { ensureAutocompletePrompt } from '../../lib/prompt.js';
 import { detectWorktreeType, findWorktreeByName, formatWorktreeDisplayPath, formatWorktreeType, getWorktreeBranchName, } from '../../lib/worktree.js';
@@ -24,6 +25,7 @@ export const OPEN_TOOL_CANDIDATES = [
         kind: 'app',
         aliases: ['codex', 'codex-app'],
         bundleId: 'com.openai.codex',
+        requiredCommand: 'codex',
     },
     { id: 'cmux', name: 'Cmux Panel', command: 'cmux', kind: 'terminal', aliases: ['cmux', 'cmux-panel'] },
     { id: 'tmux', name: 'Tmux Session', command: 'tmux', kind: 'terminal', aliases: ['tmux', 'tmux-session'] },
@@ -175,16 +177,27 @@ export async function macOSAppBundleExists(bundleId) {
 export async function detectInstalledOpenTools() {
     const checks = await Promise.all(OPEN_TOOL_CANDIDATES.map(async (tool) => ({
         tool,
-        exists: tool.bundleId
-            ? await macOSAppBundleExists(tool.bundleId)
-            : await commandExists(tool.command),
+        exists: await isOpenToolAvailable(tool),
     })));
     return checks
         .filter(check => check.exists)
         .map(check => check.tool);
 }
-function resolveWorktreeByName(worktrees, wtName) {
-    return findWorktreeByName(worktrees, wtName);
+export async function isOpenToolAvailable(tool, checks = {}) {
+    const hasCommand = checks.commandExists || commandExists;
+    const hasAppBundle = checks.macOSAppBundleExists || macOSAppBundleExists;
+    if (tool.requiredCommand) {
+        const commandAvailable = await hasCommand(tool.requiredCommand);
+        if (!commandAvailable)
+            return false;
+    }
+    if (tool.bundleId) {
+        return hasAppBundle(tool.bundleId);
+    }
+    return hasCommand(tool.command);
+}
+function resolveWorktreeByName(worktrees, wtName, managedRoot) {
+    return findWorktreeByName(worktrees, wtName, managedRoot);
 }
 export function resolveOpenToolOption(input, installed) {
     const normalized = input.trim().toLowerCase();
@@ -202,9 +215,7 @@ async function resolveKnownOpenToolOption(input) {
     const candidate = resolveOpenToolCandidate(input);
     if (!candidate)
         return undefined;
-    const exists = candidate.bundleId
-        ? await macOSAppBundleExists(candidate.bundleId)
-        : await commandExists(candidate.command);
+    const exists = await isOpenToolAvailable(candidate);
     return exists ? candidate : undefined;
 }
 export async function resolveOpenToolAction(input, installed) {
@@ -331,6 +342,12 @@ export async function launchOpenTool(tool, wtPath) {
     });
 }
 export function buildOpenToolLaunchCommand(tool, wtPath) {
+    if (tool.id === 'codex-app') {
+        return {
+            executable: 'codex',
+            args: ['app', wtPath],
+        };
+    }
     if (tool.bundleId) {
         return {
             executable: '/usr/bin/open',
@@ -364,16 +381,17 @@ export async function runOpenActions(actions, wtPath, options = {}) {
 }
 export async function openCommand(wtName, options = {}) {
     try {
-        await getRepoRoot();
+        const repoRoot = await getRepoRoot();
         const worktrees = await listWorktrees();
         const mainWorktreePath = worktrees[0]?.path || '';
+        const managedRoot = await getManagedWorktreesRoot(repoRoot);
         if (worktrees.length === 0) {
             log.info('No worktrees found.');
             return;
         }
         let targetWt;
         if (wtName) {
-            targetWt = resolveWorktreeByName(worktrees, wtName);
+            targetWt = resolveWorktreeByName(worktrees, wtName, managedRoot);
             if (!targetWt) {
                 log.error(`Worktree "${wtName}" not found.`);
                 return;
@@ -383,9 +401,9 @@ export async function openCommand(wtName, options = {}) {
             ensureAutocompletePrompt();
             const terminalColumns = process.stdout.columns || 100;
             const candidates = await Promise.all(worktrees.map(async (wt) => {
-                const type = await detectWorktreeType(wt, mainWorktreePath);
+                const type = await detectWorktreeType(wt, mainWorktreePath, managedRoot);
                 const branchName = getWorktreeBranchName(wt);
-                const displayPath = formatWorktreeDisplayPath(wt.path);
+                const displayPath = formatWorktreeDisplayPath(wt.path, managedRoot);
                 const rawType = type.toLowerCase();
                 const rawDisplayPath = displayPath.toLowerCase();
                 const rawBranchName = branchName.toLowerCase();

package/dist/commands/wt/path.js

@@ -1,18 +1,20 @@
 import inquirer from 'inquirer';
 import { listWorktrees, getRepoRoot } from '../../lib/git.js';
+import { getManagedWorktreesRoot } from '../../lib/global-config.js';
 import { log } from '../../lib/ui.js';
 import { findWorktreeByName, formatWorktreeDisplayPath, getWorktreeBranchName } from '../../lib/worktree.js';
 export async function pathCommand(wtName) {
     try {
-        await getRepoRoot();
+        const repoRoot = await getRepoRoot();
         const worktrees = await listWorktrees();
+        const managedRoot = await getManagedWorktreesRoot(repoRoot);
         if (worktrees.length === 0) {
             log.info('No worktrees found.');
             return;
         }
         let targetWt;
         if (wtName) {
-            targetWt = findWorktreeByName(worktrees, wtName);
+            targetWt = findWorktreeByName(worktrees, wtName, managedRoot);
             if (!targetWt) {
                 log.error(`Worktree "${wtName}" not found.`);
                 return;
@@ -22,7 +24,7 @@ export async function pathCommand(wtName) {
             // Interactive Selection
             const choices = worktrees.map(wt => {
                 const branchName = getWorktreeBranchName(wt);
-                const displayPath = formatWorktreeDisplayPath(wt.path);
+                const displayPath = formatWorktreeDisplayPath(wt.path, managedRoot);
                 return {
                     name: `${branchName.padEnd(20)} ${displayPath}`,
                     value: wt

package/dist/index.js

@@ -1,7 +1,10 @@
 import { Command, Option } from 'commander';
 import inquirer from 'inquirer';
 import chalk from 'chalk';
-import { welcome, log } from './lib/ui.js';
+import path from 'path';
+import { execa } from 'execa';
+import { formatMainMenuChoice, renderMainMenuIntro, welcome, log, } from './lib/ui.js';
+import { applyHelp, checkoutHelp, createHelp, createMultiHelp, createSandboxHelp, deleteHelp, handoffHelp, intentRouterHelp, openHelp, unapplyHelp, } from './lib/help.js';
 import { listCommand } from './commands/wt/list.js';
 import { createCommand } from './commands/wt/create.js';
 import { createCommandNew } from './commands/wt/create-branch.js';
@@ -16,13 +19,83 @@ import { openCommand } from './commands/wt/open.js';
 import { applyCommand } from './commands/wt/apply.js';
 import { unapplyCommand } from './commands/wt/unapply.js';
 import { handoffCommand } from './commands/wt/handoff.js';
+import { copyEnvCommand } from './commands/wt/copy-env.js';
+import { configGetCommand, configResetCommand, configSetWorktreeLayoutCommand, configSetWorktreesRootCommand, configUseCommand, } from './commands/config.js';
 import { getVersion } from './lib/version.js';
-import { notifyIfUpdateAvailable } from './lib/update-check.js';
+import { checkForUpdate } from './lib/update-check.js';
 import { findSandboxRoot } from './lib/sandbox.js';
 import { bifrostCommand } from './commands/bifrost.js';
 import { thorCommand } from './commands/thor.js';
+import { buildMainMenuEntries, } from './lib/main-menu.js';
+import { getRepoRoot, listWorktrees } from './lib/git.js';
 const program = new Command();
 const argv = process.argv.map((arg) => arg === '-v' || arg === '—version' ? '--version' : arg);
+const DOCS_URL = 'https://yggtree.logbookfordevs.com/docs';
+function mainMenuChoice(value, glyph, label, detail, tone) {
+    return {
+        name: formatMainMenuChoice({ glyph, label, detail, tone }),
+        value,
+    };
+}
+function mainMenuSeparator(label) {
+    return new inquirer.Separator(chalk.dim(`  · ${label}`));
+}
+const mainMenuChoices = {
+    'create-smart': mainMenuChoice('create-smart', '◆', 'Grow new realm', 'create a branch-backed worktree', 'growth'),
+    'worktree-checkout': mainMenuChoice('worktree-checkout', '⇄', 'Check out branch', 'open an existing ref in a new realm', 'travel'),
+    handoff: mainMenuChoice('handoff', '✦', 'Hand off current work', 'carry dirty work into a named sandbox', 'sandbox'),
+    open: mainMenuChoice('open', '◇', 'Open realm', 'jump into an existing worktree', 'travel'),
+    list: mainMenuChoice('list', '○', 'Survey realms', 'scan active worktrees and PR state', 'tending'),
+    'create-multi': mainMenuChoice('create-multi', '✧', 'Grow many realms', 'create multiple branch worktrees', 'growth'),
+    'create-sandbox': mainMenuChoice('create-sandbox', '△', 'Forge sandbox', 'create a local experiment realm', 'sandbox'),
+    bootstrap: mainMenuChoice('bootstrap', '↳', 'Bootstrap realm', 'install dependencies and submodules', 'tending'),
+    exec: mainMenuChoice('exec', '⌁', 'Cast command', 'run a command inside a worktree', 'tending'),
+    path: mainMenuChoice('path', '⌖', 'Reveal path', 'print a worktree cd command', 'tending'),
+    'copy-env': mainMenuChoice('copy-env', '≋', 'Bring env files', 'copy local env files from main realm', 'tending'),
+    delete: mainMenuChoice('delete', '×', 'Fell realm', 'delete managed worktrees', 'danger'),
+    prune: mainMenuChoice('prune', '⌫', 'Prune stale realms', 'remove stale worktree metadata', 'danger'),
+    apply: mainMenuChoice('apply', '◆', 'Graft sandbox changes', 'apply sandbox changes to origin', 'sandbox'),
+    unapply: mainMenuChoice('unapply', '↶', 'Undo sandbox graft', 'restore origin from sandbox backups', 'sandbox'),
+    bifrost: mainMenuChoice('bifrost', '✺', 'Summon the Bifrost', 'open the long way around', 'lore'),
+    thor: mainMenuChoice('thor', 'ϟ', 'Consult Thor', 'ask the thunder route', 'lore'),
+    docs: mainMenuChoice('docs', '?', 'Open docs', 'read the Yggtree documentation', 'tending'),
+    exit: mainMenuChoice('exit', '·', 'Leave Yggdrasil', 'exit without changing anything', 'exit'),
+};
+async function detectMainMenuContext() {
+    if (await findSandboxRoot(process.cwd())) {
+        return 'sandbox';
+    }
+    try {
+        const repoRoot = await getRepoRoot();
+        const worktrees = await listWorktrees();
+        const mainWorktreePath = worktrees[0]?.path;
+        if (mainWorktreePath && path.resolve(repoRoot) !== path.resolve(mainWorktreePath)) {
+            return 'worktree';
+        }
+    }
+    catch {
+        return 'main';
+    }
+    return 'main';
+}
+async function openDocs() {
+    const command = process.platform === 'darwin'
+        ? 'open'
+        : process.platform === 'win32'
+            ? 'cmd'
+            : 'xdg-open';
+    const args = process.platform === 'win32'
+        ? ['/c', 'start', '', DOCS_URL]
+        : [DOCS_URL];
+    try {
+        await execa(command, args, { stdio: 'ignore' });
+        log.success(`Opened docs: ${DOCS_URL}`);
+    }
+    catch {
+        log.warning('Could not open the docs in your browser.');
+        log.info(DOCS_URL);
+    }
+}
 function registerWorktreeCommands(parent) {
     parent.command('list')
         .description('List all repo-linked worktrees')
@@ -35,7 +108,7 @@ function registerWorktreeCommands(parent) {
         await listCommand();
     });
     parent.command('create [branch]')
-        .description('Create a new worktree (Smart branch detection)')
+        .description('Create an official branch-backed task worktree')
         .option('-b, --branch <name>', 'Branch name (e.g. feat/new-ui)')
         .option('--base <ref>', 'Base ref (e.g. main)')
         .option('--source <type>', 'Base source (local or remote)')
@@ -45,6 +118,8 @@ function registerWorktreeCommands(parent) {
         .option('--enter', 'Enter the worktree sub-shell after creation')
         .option('--no-enter', 'Do not enter the worktree sub-shell after creation')
         .option('--exec <command>', 'Command to execute after creation')
+        .option('--config <preset>', 'Use a path preset for this run only (yggtree, codex, claude)')
+        .addHelpText('after', createHelp)
         .action(async (branch, options) => {
         await createCommandNew({
             ...options,
@@ -52,10 +127,12 @@ function registerWorktreeCommands(parent) {
         });
     });
     parent.command('create-multi')
-        .description('Create multiple worktrees (Smart branch detection)')
+        .description('Bulk-create official branch-backed worktrees')
         .option('--base <ref>', 'Base ref (e.g. main)')
         .option('--source <type>', 'Base source (local or remote)')
         .option('--no-bootstrap', 'Skip bootstrap (npm install + submodules)')
+        .option('--config <preset>', 'Use a path preset for this run only (yggtree, codex, claude)')
+        .addHelpText('after', createMultiHelp)
         .action(async (options) => {
         await createCommandMulti(options);
     });
@@ -71,6 +148,8 @@ function registerWorktreeCommands(parent) {
             .addOption(new Option('--enter', 'Enter the worktree sub-shell after checkout/opening').hideHelp())
             .option('--no-enter', 'Do not enter the worktree sub-shell after checkout/opening')
             .option('--exec <command>', 'Command to execute after creation')
+            .option('--config <preset>', 'Use a path preset for this run only (yggtree, codex, claude)')
+            .addHelpText('after', checkoutHelp)
             .action(async (name, ref, options) => {
             await createCommand({
                 ...options,
@@ -81,17 +160,20 @@ function registerWorktreeCommands(parent) {
     };
     registerWorktreeCheckout('worktree-checkout', 'Create a checkout-style worktree from an existing branch');
     registerWorktreeCheckout('wc', 'Alias for worktree-checkout');
-    parent.command('delete')
+    parent.command('delete [worktrees...]')
         .description('Delete managed worktrees')
-        .option('-a, --all', 'Include repo-linked worktrees outside ~/.yggtree (except main/current)')
-        .action(async (options) => {
-        await deleteCommand(options);
+        .option('-a, --all', 'Include external LINKED worktrees outside the managed root (except main/current)')
+        .option('-y, --yes', 'Confirm deletion without prompts')
+        .addHelpText('after', deleteHelp)
+        .action(async (worktrees, options) => {
+        await deleteCommand(worktrees, options);
     });
     parent.command('open [worktree]')
         .description('Open a worktree in an editor, supported app, or terminal target')
         .option('--tool <command>', 'Editor, app, or terminal command to use (e.g. cursor, code, codex-app, tmux)')
         .option('--enter', 'Enter the worktree sub-shell after opening')
         .addOption(new Option('--no-enter', 'Do not enter the worktree sub-shell after opening').hideHelp())
+        .addHelpText('after', openHelp)
         .action(async (worktree, options) => {
         await openCommand(worktree, options);
     });
@@ -113,22 +195,27 @@ function registerWorktreeCommands(parent) {
         .action(async (worktree) => {
         await pathCommand(worktree);
     });
+    parent.command('copy-env')
+        .description('Copy local env files from the main worktree to the current worktree')
+        .action(copyEnvCommand);
     parent.command('create-sandbox')
-        .description('Create a sandbox worktree from current branch')
+        .description('Create a local-only disposable experiment sandbox')
         .option('-n, --name <name>', 'Optional sandbox name (auto-generated when omitted)')
-        .option('--carry', 'Carry uncommitted changes to sandbox')
-        .option('--no-carry', 'Do not carry uncommitted changes')
+        .option('--carry', 'Copy uncommitted changes to sandbox')
+        .option('--no-carry', 'Do not copy uncommitted changes')
         .option('--no-bootstrap', 'Skip bootstrap (npm install + submodules)')
         .option('--open', 'Open an editor after creation')
         .option('--no-open', 'Skip opening an editor after creation')
         .addOption(new Option('--enter', 'Deprecated alias for --open').hideHelp())
         .addOption(new Option('--no-enter', 'Deprecated alias for --no-open').hideHelp())
         .option('--exec <command>', 'Command to execute after creation')
+        .option('--config <preset>', 'Use a path preset for this run only (yggtree, codex, claude)')
+        .addHelpText('after', createSandboxHelp)
         .action(async (options) => {
         await createSandboxCommand(options);
     });
     parent.command('handoff')
-        .description('Carry uncommitted work into a sandbox worktree')
+        .description('Carry dirty current work into a named sandbox')
         .option('-n, --name <name>', 'Optional handoff name (prompted when omitted)')
         .option('--no-bootstrap', 'Skip bootstrap (npm install + submodules)')
         .option('--open', 'Open an editor after creation')
@@ -136,14 +223,18 @@ function registerWorktreeCommands(parent) {
         .addOption(new Option('--enter', 'Deprecated alias for --open').hideHelp())
         .addOption(new Option('--no-enter', 'Deprecated alias for --no-open').hideHelp())
         .option('--exec <command>', 'Command to execute after creation')
+        .option('--config <preset>', 'Use a path preset for this run only (yggtree, codex, claude)')
+        .addHelpText('after', handoffHelp)
         .action(async (options) => {
         await handoffCommand(options);
     });
     parent.command('apply')
-        .description('Apply sandbox changes to origin directory')
+        .description('Copy sandbox file changes to the origin checkout')
+        .addHelpText('after', applyHelp)
         .action(applyCommand);
     parent.command('unapply')
-        .description('Undo applied sandbox changes in origin')
+        .description('Restore origin files from sandbox apply backups')
+        .addHelpText('after', unapplyHelp)
         .action(unapplyCommand);
 }
 function rejectUnknownTopLevelCommand(args) {
@@ -162,55 +253,25 @@ program
     .description('Interactive CLI for managing git worktrees and configs')
     .version(getVersion())
     .allowExcessArguments(false)
+    .addHelpText('after', intentRouterHelp)
     .action(async () => {
-    // Interactive Menu if no command is provided
-    await welcome();
-    await notifyIfUpdateAvailable();
-    const isInSandbox = Boolean(await findSandboxRoot(process.cwd()));
-    const realmChoices = [
-        { name: `🌿 Grow New Realm ${chalk.dim('(create worktree)')}`, value: 'create-smart' },
-        { name: `🔀 Traverse to Another Realm ${chalk.dim('(checkout existing branch in new worktree)')}`, value: 'worktree-checkout' },
-        { name: `🌳 Grow Many Realms ${chalk.dim('(create multiple worktrees)')}`, value: 'create-multi' },
-        { name: `🤝 Hand Off Current Work ${chalk.dim('(carry dirty work into a sandbox)')}`, value: 'handoff' },
-        { name: `🧪 Forge Sandbox Realm ${chalk.dim('(create sandbox worktree)')}`, value: 'create-sandbox' },
-        { name: `🗺️  Survey Realms ${chalk.dim('(list worktrees)')}`, value: 'list' },
-        { name: `🧭 Open Realm in Editor ${chalk.dim('(open worktree in editor)')}`, value: 'open' },
-        { name: `🪓 Fell a Realm ${chalk.dim('(delete worktree)')}`, value: 'delete' },
-        { name: `🚀 Bless Realm Setup ${chalk.dim('(bootstrap worktree)')}`, value: 'bootstrap' },
-        { name: `🧹 Prune Withered Realms ${chalk.dim('(prune stale worktrees)')}`, value: 'prune' },
-        { name: `🐚 Cast a Command ${chalk.dim('(exec command in worktree)')}`, value: 'exec' },
-        { name: `📍 Reveal Realm Path ${chalk.dim('(show worktree path)')}`, value: 'path' },
-    ];
-    const sandboxChoices = [
-        { name: `✅ Graft Sandbox Changes ${chalk.dim('(apply sandbox changes)')}`, value: 'apply' },
-        { name: `↩️ Undo Sandbox Graft ${chalk.dim('(unapply sandbox changes)')}`, value: 'unapply' },
-    ];
-    const choices = isInSandbox
-        ? [
-            ...sandboxChoices,
-            new inquirer.Separator(),
-            ...realmChoices,
-            new inquirer.Separator(),
-            { name: `🌈 Summon the Bifrost ${chalk.dim('(easter egg)')}`, value: 'bifrost' },
-            { name: `⚡ Consult Thor ${chalk.dim('(easter egg)')}`, value: 'thor' },
-            { name: `🚪 Leave Yggdrasil ${chalk.dim('(exit)')}`, value: 'exit' },
-        ]
-        : [
-            ...realmChoices,
-            new inquirer.Separator(),
-            ...sandboxChoices,
-            new inquirer.Separator(),
-            { name: `🌈 Summon the Bifrost ${chalk.dim('(easter egg)')}`, value: 'bifrost' },
-            { name: `⚡ Consult Thor ${chalk.dim('(easter egg)')}`, value: 'thor' },
-            { name: `🚪 Leave Yggdrasil ${chalk.dim('(exit)')}`, value: 'exit' },
-        ];
+    const update = await checkForUpdate();
+    await welcome({ update });
+    const menuContext = await detectMainMenuContext();
+    const choices = buildMainMenuEntries(menuContext).map((entry) => {
+        if (entry.type === 'separator') {
+            return mainMenuSeparator(entry.label);
+        }
+        return mainMenuChoices[entry.value];
+    });
+    console.log(renderMainMenuIntro({ context: menuContext }));
     const { action } = await inquirer.prompt([
         {
             type: 'list',
             name: 'action',
-            message: 'What would you like to do?',
+            message: 'Which route should Yggtree follow?',
             loop: false,
-            pageSize: 12,
+            pageSize: 14,
             choices,
         },
     ]);
@@ -245,6 +306,9 @@ program
         case 'path':
             await pathCommand();
             break;
+        case 'copy-env':
+            await copyEnvCommand();
+            break;
         case 'apply':
             await applyCommand();
             break;
@@ -263,6 +327,9 @@ program
         case 'thor':
             await thorCommand();
             break;
+        case 'docs':
+            await openDocs();
+            break;
         case 'exit':
             log.info('Bye! 👋');
             process.exit(0);
@@ -270,6 +337,7 @@ program
 });
 // --- Worktree Commands ---
 const wt = program.command('wt').description('Manage git worktrees');
+wt.addHelpText('after', intentRouterHelp);
 registerWorktreeCommands(program);
 registerWorktreeCommands(wt);
 program.addHelpCommand(true);
@@ -279,5 +347,21 @@ program.command('bifrost')
 program.command('thor')
     .description('Consult the God of Thunder (Easter Egg)')
     .action(thorCommand);
+const config = program.command('config').description('Inspect or update global Yggtree settings');
+config.command('get')
+    .description('Show resolved global settings')
+    .action(configGetCommand);
+config.command('use <preset>')
+    .description('Use a global worktree path preset (default, yggtree, codex, claude)')
+    .action(configUseCommand);
+config.command('set-worktrees-root <path>')
+    .description('Set the global managed worktrees root')
+    .action(configSetWorktreesRootCommand);
+config.command('set-worktree-layout <layout>')
+    .description('Set the managed worktree path layout (yggtree, codex, or claude)')
+    .action(configSetWorktreeLayoutCommand);
+config.command('reset')
+    .description('Reset global settings to defaults')
+    .action(configResetCommand);
 rejectUnknownTopLevelCommand(argv);
 program.parse(argv);