yggtree 1.4.3 → 1.4.5

package/dist/index.js

@@ -1,7 +1,8 @@
 import { Command, Option } from 'commander';
 import inquirer from 'inquirer';
 import chalk from 'chalk';
-import { welcome, log } from './lib/ui.js';
+import { formatMainMenuChoice, renderMainMenuIntro, welcome, log, } from './lib/ui.js';
+import { applyHelp, checkoutHelp, createHelp, createMultiHelp, createSandboxHelp, 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';
@@ -15,13 +16,24 @@ import { pathCommand } from './commands/wt/path.js';
 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 { 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';
 const program = new Command();
 const argv = process.argv.map((arg) => arg === '-v' || arg === '—version' ? '--version' : arg);
+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}`));
+}
 function registerWorktreeCommands(parent) {
     parent.command('list')
         .description('List all repo-linked worktrees')
@@ -34,16 +46,17 @@ 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)')
         .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('--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')
+        .addHelpText('after', createHelp)
         .action(async (branch, options) => {
         await createCommandNew({
             ...options,
@@ -51,10 +64,11 @@ 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)')
+        .addHelpText('after', createMultiHelp)
         .action(async (options) => {
         await createCommandMulti(options);
     });
@@ -66,10 +80,11 @@ function registerWorktreeCommands(parent) {
             .option('--no-bootstrap', 'Skip bootstrap (npm install + submodules)')
             .option('--open', 'Open editors or run a startup command before entering')
             .option('--no-open', 'Skip opening editors or startup commands before entering')
-            .option('--tool <command>', 'Editor or app command to open after checkout (skips open prompt)')
+            .option('--tool <command>', 'Editor, app, or terminal command to open after checkout (skips open prompt)')
             .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')
+            .addHelpText('after', checkoutHelp)
             .action(async (name, ref, options) => {
             await createCommand({
                 ...options,
@@ -82,15 +97,16 @@ function registerWorktreeCommands(parent) {
     registerWorktreeCheckout('wc', 'Alias for worktree-checkout');
     parent.command('delete')
         .description('Delete managed worktrees')
-        .option('-a, --all', 'Include repo-linked worktrees outside ~/.yggtree (except main/current)')
+        .option('-a, --all', 'Include repo-linked worktrees outside the managed root (except main/current)')
         .action(async (options) => {
         await deleteCommand(options);
     });
     parent.command('open [worktree]')
-        .description('Open a worktree in an editor or supported app')
-        .option('--tool <command>', 'Editor or app command to use (e.g. cursor, code, codex-app)')
+        .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,24 +129,40 @@ function registerWorktreeCommands(parent) {
         await pathCommand(worktree);
     });
     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')
+        .addHelpText('after', createSandboxHelp)
         .action(async (options) => {
         await createSandboxCommand(options);
     });
+    parent.command('handoff')
+        .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')
+        .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')
+        .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) {
@@ -149,54 +181,69 @@ 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 update = await checkForUpdate();
+    await welcome({ update });
     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: `🧪 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 dailyChoices = [
+        mainMenuChoice('create-smart', '◆', 'Grow new realm', 'create a branch-backed worktree', 'growth'),
+        mainMenuChoice('worktree-checkout', '⇄', 'Check out branch', 'open an existing ref in a new realm', 'travel'),
+        mainMenuChoice('handoff', '✦', 'Hand off current work', 'carry dirty work into a named sandbox', 'sandbox'),
+        mainMenuChoice('open', '◇', 'Open realm', 'jump into an existing worktree', 'travel'),
+        mainMenuChoice('list', '○', 'Survey realms', 'scan active worktrees and PR state', 'tending'),
+    ];
+    const growthChoices = [
+        mainMenuChoice('create-multi', '✧', 'Grow many realms', 'create multiple branch worktrees', 'growth'),
+        mainMenuChoice('create-sandbox', '△', 'Forge sandbox', 'create a local experiment realm', 'sandbox'),
+    ];
+    const tendingChoices = [
+        mainMenuChoice('bootstrap', '↳', 'Bootstrap realm', 'install dependencies and submodules', 'tending'),
+        mainMenuChoice('exec', '⌁', 'Cast command', 'run a command inside a worktree', 'tending'),
+        mainMenuChoice('path', '⌖', 'Reveal path', 'print a worktree cd command', 'tending'),
+        mainMenuChoice('delete', '×', 'Fell realm', 'delete managed worktrees', 'danger'),
+        mainMenuChoice('prune', '⌫', 'Prune stale realms', 'remove stale worktree metadata', 'danger'),
     ];
     const sandboxChoices = [
-        { name: `✅ Graft Sandbox Changes ${chalk.dim('(apply sandbox changes)')}`, value: 'apply' },
-        { name: `↩️ Undo Sandbox Graft ${chalk.dim('(unapply sandbox changes)')}`, value: 'unapply' },
+        mainMenuChoice('apply', '◆', 'Graft sandbox changes', 'apply sandbox changes to origin', 'sandbox'),
+        mainMenuChoice('unapply', '↶', 'Undo sandbox graft', 'restore origin from sandbox backups', 'sandbox'),
+    ];
+    const loreChoices = [
+        mainMenuChoice('bifrost', '✺', 'Summon the Bifrost', 'open the long way around', 'lore'),
+        mainMenuChoice('thor', 'ϟ', 'Consult Thor', 'ask the thunder route', 'lore'),
+        mainMenuChoice('exit', '·', 'Leave Yggdrasil', 'exit without changing anything', 'exit'),
     ];
     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' },
+            mainMenuSeparator('Daily routes'),
+            ...dailyChoices,
+            mainMenuSeparator('Growth and experiments'),
+            ...growthChoices,
+            mainMenuSeparator('Tend realms'),
+            ...tendingChoices,
+            mainMenuSeparator('Lore'),
+            ...loreChoices,
         ]
         : [
-            ...realmChoices,
-            new inquirer.Separator(),
+            ...dailyChoices,
+            mainMenuSeparator('Growth and experiments'),
+            ...growthChoices,
+            mainMenuSeparator('Tend realms'),
+            ...tendingChoices,
+            mainMenuSeparator('Sandbox grafts'),
             ...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' },
+            mainMenuSeparator('Lore'),
+            ...loreChoices,
         ];
+    console.log(renderMainMenuIntro({ isInSandbox }));
     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,
         },
     ]);
@@ -240,6 +287,9 @@ program
         case 'create-sandbox':
             await createSandboxCommand({ bootstrap: true });
             break;
+        case 'handoff':
+            await handoffCommand({ bootstrap: true });
+            break;
         case 'bifrost':
             await bifrostCommand();
             break;
@@ -253,6 +303,7 @@ program
 });
 // --- Worktree Commands ---
 const wt = program.command('wt').description('Manage git worktrees');
+wt.addHelpText('after', intentRouterHelp);
 registerWorktreeCommands(program);
 registerWorktreeCommands(wt);
 program.addHelpCommand(true);
@@ -262,5 +313,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)')
+    .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 or codex)')
+    .action(configSetWorktreeLayoutCommand);
+config.command('reset')
+    .description('Reset global settings to defaults')
+    .action(configResetCommand);
 rejectUnknownTopLevelCommand(argv);
 program.parse(argv);

package/dist/lib/global-config.js

@@ -0,0 +1,89 @@
+import os from 'os';
+import path from 'path';
+import fs from 'fs-extra';
+import { YGG_ROOT } from './paths.js';
+const CONFIG_PATH = path.join(YGG_ROOT, 'config.json');
+const DEFAULT_WORKTREE_LAYOUT = 'yggtree';
+export function expandHome(value) {
+    if (value === '~')
+        return os.homedir();
+    if (value.startsWith('~/'))
+        return path.join(os.homedir(), value.slice(2));
+    return value;
+}
+export function formatHome(value) {
+    const home = os.homedir();
+    if (value === home)
+        return '~';
+    if (value.startsWith(`${home}${path.sep}`))
+        return `~/${path.relative(home, value)}`;
+    return value;
+}
+function normalizeRoot(value) {
+    return path.resolve(expandHome(value || YGG_ROOT));
+}
+export function normalizeWorktreesRootInput(value) {
+    return path.resolve(expandHome(value));
+}
+function normalizeLayout(value) {
+    return value || DEFAULT_WORKTREE_LAYOUT;
+}
+export async function readGlobalConfig() {
+    try {
+        if (await fs.pathExists(CONFIG_PATH)) {
+            const config = await fs.readJSON(CONFIG_PATH);
+            return {
+                worktreesRoot: typeof config.worktreesRoot === 'string' ? config.worktreesRoot : undefined,
+                worktreeLayout: config.worktreeLayout === 'codex' ? 'codex' : undefined,
+            };
+        }
+    }
+    catch {
+        return {};
+    }
+    return {};
+}
+export async function writeGlobalConfig(config) {
+    await fs.ensureDir(YGG_ROOT);
+    await fs.writeJSON(CONFIG_PATH, config, { spaces: 2 });
+}
+export async function getWorktreePathConfig() {
+    const config = await readGlobalConfig();
+    return {
+        root: normalizeRoot(config.worktreesRoot),
+        layout: normalizeLayout(config.worktreeLayout),
+    };
+}
+export async function getManagedWorktreesRoot() {
+    const config = await getWorktreePathConfig();
+    return config.root;
+}
+export function buildManagedWorktreePath(repoName, worktreeSlug, config) {
+    if (config.layout === 'codex') {
+        return path.join(config.root, worktreeSlug, repoName);
+    }
+    return path.join(config.root, repoName, worktreeSlug);
+}
+export function getPresetConfig(preset) {
+    const normalized = preset.trim().toLowerCase();
+    if (normalized === 'default' || normalized === 'yggtree') {
+        return {};
+    }
+    if (normalized === 'codex') {
+        return {
+            worktreesRoot: '~/.codex/worktrees',
+            worktreeLayout: 'codex',
+        };
+    }
+    return undefined;
+}
+export function formatGlobalConfig(config, resolved) {
+    return [
+        `worktreesRoot: ${formatHome(resolved.root)}`,
+        `worktreeLayout: ${resolved.layout}`,
+        `configFile: ${formatHome(CONFIG_PATH)}`,
+        config.worktreesRoot || config.worktreeLayout
+            ? 'preset: custom'
+            : 'preset: default',
+    ];
+}

package/dist/lib/help.js

@@ -0,0 +1,93 @@
+export const intentRouterHelp = `
+Choose by intent:
+  New official task branch      yggtree create feat/name --base main --source remote
+  Existing branch/interruption  yggtree wc --ref branch-name
+  Continue dirty current work   yggtree handoff --name task-name
+  Disposable local experiment   yggtree create-sandbox
+  Copy sandbox files to origin  yggtree apply   # from inside sandbox, not a Git merge
+  Bulk official worktrees       yggtree create-multi
+
+More detail: run yggtree help <command>, for example yggtree help handoff.
+`;
+export const createHelp = `
+Behavior:
+  Creates an official branch-backed worktree, publishes the branch to origin, and enters the shell by default.
+  Use for real task branches. For disposable experiments, use create-sandbox.
+
+Examples:
+  yggtree create feat/new-flow --base main --source remote
+  yggtree create feat/background-task --base main --source remote --no-open --no-enter
+`;
+export const createMultiHelp = `
+Behavior:
+  Bulk-creates official branch-backed worktrees.
+  This does not share create's open/enter/exec lifecycle. Use create for one task branch.
+
+Example:
+  yggtree create-multi --base main --source remote
+`;
+export const checkoutHelp = `
+Behavior:
+  Creates or reuses a worktree for an existing branch or ref without disturbing current work.
+  Use for interruptions and branch review. Use create for a new official task branch.
+  Enters the worktree shell by default; add --no-enter when automation should return.
+
+Examples:
+  yggtree wc --ref hotfix/payment-timeout
+  yggtree wc --ref main --name fresh-main --no-open --no-enter
+`;
+export const openHelp = `
+Behavior:
+  Opens an existing worktree in an editor, desktop app, or terminal target.
+  Returns by default after opening. Add --enter only when the shell should continue inside the worktree.
+
+Examples:
+  yggtree open my-feature --tool cursor
+  yggtree open my-feature --tool codex-app
+  yggtree list --open
+`;
+export const createSandboxHelp = `
+Behavior:
+  Creates a local-only disposable experiment from the current branch.
+  For continuing current dirty work, prefer handoff instead of teaching create-sandbox --carry.
+
+Examples:
+  yggtree create-sandbox
+  yggtree create-sandbox --name ui-option-a --no-open
+
+Related:
+  handoff carries current dirty work into a named sandbox.
+  apply copies changed sandbox files back to origin.
+`;
+export const handoffHelp = `
+Behavior:
+  Carry staged, unstaged, and untracked work into a named sandbox so you can continue there.
+  The origin checkout is not cleaned; review or reset it separately if needed.
+
+Example:
+  yggtree handoff --name continue-auth-refactor
+
+Related:
+  create-sandbox starts a disposable local experiment.
+  apply copies changed sandbox files back to origin.
+`;
+export const applyHelp = `
+Behavior:
+  Copies changed files from the current sandbox back to the origin checkout.
+  Stores backups in sandbox metadata before overwriting origin files.
+  Not a Git merge, rebase, patch, or cherry-pick. Review the origin diff afterward.
+
+Example:
+  yggtree apply
+
+Related:
+  unapply restores from the sandbox backup metadata while the sandbox still exists.
+`;
+export const unapplyHelp = `
+Behavior:
+  Restores origin files from sandbox metadata created by apply.
+  Only works while the sandbox still exists.
+
+Example:
+  yggtree unapply
+`;

package/dist/lib/paths.js

@@ -1,4 +1,3 @@
 import os from 'os';
 import path from 'path';
 export const YGG_ROOT = path.join(os.homedir(), '.yggtree');
-export const WORKTREES_ROOT = YGG_ROOT;

package/dist/lib/repo-context.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { getRepoRoot } from './git.js';
+import { getManagedWorktreesRoot } from './global-config.js';
 import { getValidRegisteredRepos } from './registry.js';
 import { log } from './ui.js';
 import { formatWorktreeDisplayPath } from './worktree.js';
@@ -11,6 +12,7 @@ export async function ensureRepoContext() {
     catch {
         const validRepos = await getValidRegisteredRepos();
         const repoEntries = Object.entries(validRepos);
+        const managedRoot = await getManagedWorktreesRoot();
         if (repoEntries.length === 0) {
             log.error('Not inside a git repository and no registered realms found.');
             log.dim('Run `yggtree` inside an existing git project first to register it.');
@@ -34,7 +36,7 @@ export async function ensureRepoContext() {
                 name: 'selectedRepoPath',
                 message: 'Select a realm:',
                 choices: repoEntries.map(([name, repoPath]) => ({
-                    name: `${chalk.bold.yellow(name)} ${chalk.dim(formatWorktreeDisplayPath(repoPath))}`,
+                    name: `${chalk.bold.yellow(name)} ${chalk.dim(formatWorktreeDisplayPath(repoPath, managedRoot))}`,
                     value: repoPath,
                 })),
                 pageSize: 10,

package/dist/lib/ui.js

@@ -6,15 +6,80 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { getVersion } from './version.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// --- Personality & Branding ---
-export const welcome = async () => {
-    console.log('');
+const yggAccent = chalk.hex('#DEADED');
+const yggLeaf = chalk.hex('#9AD68B');
+const yggSky = chalk.hex('#7AC7D8');
+const yggBark = chalk.hex('#C99A5B');
+const yggRoot = chalk.hex('#B48AE8');
+const yggWarn = chalk.hex('#E4B85E');
+const yggDanger = chalk.hex('#E06C75');
+const yggMuted = chalk.hex('#8D8D8D');
+export function renderWelcome(options = {}) {
+    const rule = yggAccent('─'.repeat(54));
     const title = figlet.textSync('Yggdrasil', { font: 'Standard' });
-    console.log(gradient.mind.multiline(title));
     const version = getVersion();
-    console.log(chalk.dim(`  v${version} • The World Tree Worktree Assistant`));
-    console.log('');
+    const updateLines = renderUpdateNotice(options.update);
+    return [
+        '',
+        rule,
+        gradient.mind.multiline(title),
+        chalk.bold(yggAccent('  Yggdrasil')),
+        chalk.dim(`  v${version} • The World Tree Worktree Assistant`),
+        ...updateLines,
+        rule,
+        '',
+    ].join('\n');
+}
+export const welcome = async (options = {}) => {
+    console.log(renderWelcome(options));
 };
+export function renderMainMenuIntro(options) {
+    const detail = options.isInSandbox
+        ? 'Sandbox tools appear first because this realm can apply or undo grafted changes.'
+        : 'Create, enter, inspect, or tend your worktrees.';
+    return [
+        'Choose the next realm action.',
+        yggMuted('Daily routes first. Maintenance and lore wait below.'),
+        '',
+        `${yggBark('┌')}   ${badge('route 01')} ${chalk.bold('Realm')}`,
+        `${yggBark('│')}   ${yggMuted(detail)}`,
+    ].join('\n');
+}
+export function formatMainMenuChoice(options) {
+    const tone = menuTone(options.tone);
+    const label = options.label.padEnd(24);
+    return `${tone(options.glyph)}  ${chalk.bold(label)} ${yggMuted(options.detail)}`;
+}
+function renderUpdateNotice(update) {
+    if (!update?.updateAvailable)
+        return [];
+    return [
+        '',
+        `${yggWarn('Update available')} ${yggMuted(`yggtree ${update.currentVersion} -> ${update.latestVersion}`)}`,
+        yggMuted('Run: npm install -g yggtree'),
+    ];
+}
+function badge(value) {
+    return yggRoot(` ${value} `);
+}
+function menuTone(tone) {
+    switch (tone) {
+        case 'growth':
+            return yggLeaf;
+        case 'travel':
+            return yggSky;
+        case 'sandbox':
+            return yggRoot;
+        case 'tending':
+            return yggBark;
+        case 'danger':
+            return yggDanger;
+        case 'lore':
+            return yggAccent;
+        case 'exit':
+            return yggMuted;
+    }
+}
 // --- Logger ---
 export const log = {
     info: (msg) => console.log(chalk.blue('ℹ'), msg),

package/dist/lib/worktree.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 import fs from 'fs-extra';
 import path from 'path';
-import { WORKTREES_ROOT } from './paths.js';
+import { YGG_ROOT } from './paths.js';
 import { getSandboxMetaPath } from './sandbox.js';
 export const WORKTREE_TYPE_ORDER = {
     MAIN: 0,
@@ -12,19 +12,23 @@ export const WORKTREE_TYPE_ORDER = {
 export function getWorktreeBranchName(worktree) {
     return worktree.branch || worktree.HEAD || 'detached';
 }
-export function isManagedWorktreePath(worktreePath) {
-    return worktreePath.startsWith(WORKTREES_ROOT);
+function isPathInsideRoot(worktreePath, managedRoot) {
+    const relative = path.relative(managedRoot, worktreePath);
+    return relative === '' || Boolean(relative && !relative.startsWith('..') && !path.isAbsolute(relative));
 }
-export function formatWorktreeDisplayPath(worktreePath) {
-    if (isManagedWorktreePath(worktreePath)) {
-        return path.relative(WORKTREES_ROOT, worktreePath);
+export function isManagedWorktreePath(worktreePath, managedRoot = YGG_ROOT) {
+    return isPathInsideRoot(path.resolve(worktreePath), path.resolve(managedRoot));
+}
+export function formatWorktreeDisplayPath(worktreePath, managedRoot = YGG_ROOT) {
+    if (isManagedWorktreePath(worktreePath, managedRoot)) {
+        return path.relative(managedRoot, worktreePath);
     }
     return worktreePath.replace(process.env.HOME || '', '~');
 }
-export function findWorktreeByName(worktrees, worktreeName) {
+export function findWorktreeByName(worktrees, worktreeName, managedRoot = YGG_ROOT) {
     return worktrees.find(worktree => {
         const branchName = getWorktreeBranchName(worktree);
-        const relativePath = path.relative(WORKTREES_ROOT, worktree.path);
+        const relativePath = path.relative(managedRoot, worktree.path);
         const basename = path.basename(worktree.path);
         return branchName === worktreeName ||
             relativePath === worktreeName ||
@@ -32,8 +36,8 @@ export function findWorktreeByName(worktrees, worktreeName) {
             basename === worktreeName;
     });
 }
-export async function detectWorktreeType(worktree, mainWorktreePath) {
-    const isManaged = isManagedWorktreePath(worktree.path);
+export async function detectWorktreeType(worktree, mainWorktreePath, managedRoot = YGG_ROOT) {
+    const isManaged = isManagedWorktreePath(worktree.path, managedRoot);
     if (!isManaged) {
         return worktree.path === mainWorktreePath ? 'MAIN' : 'LINKED';
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yggtree",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "packageManager": "pnpm@11.0.9",
   "description": "Interactive CLI for managing git worktrees and configs",
   "main": "dist/index.js",