yggtree 1.4.4 → 1.4.5

package/README.md

@@ -40,8 +40,8 @@ worktree workflow first, then load the smallest reference they need:
   the work already in progress.
 * **Bootstrap and use a realm**: prepare a worktree, open it in your IDE, or
   run commands inside it.
-* **Run sandbox experiments**: try alternative approaches locally and
-  apply/unapply the winner safely.
+* **Run sandbox experiments**: try alternative approaches locally, then copy the
+  winner back with sandbox-backed apply/unapply.
 
 This skill is especially useful with agents like **Claude Code**,
 **Codex**, **Cursor**, **Gemini CLI**, and other tools that support the open
@@ -110,6 +110,7 @@ All managed worktrees live under:
 ```
 
 This keeps your main repository clean while enabling true parallelism.
+You can change the global managed worktree location with `yggtree config`.
 
 ---
 
@@ -146,7 +147,7 @@ Create, manage, and navigate Git worktrees as a primary workflow, not an afterth
 Work on multiple branches at the same time, each in its own isolated environment.
 
 🧪 **Sandbox worktrees for experimentation**
-Prototyping something risky? Create a sandbox, try different strategies, and apply the winner back to your origin branch.
+Prototyping something risky? Create a sandbox, try different strategies, and copy the winner back to your origin checkout.
 
 🤝 **Handoff current work**
 Started in your main checkout? Carry staged, unstaged, and untracked work into a named sandbox worktree and continue there.
@@ -161,7 +162,7 @@ Run installs, submodules, and setup scripts automatically for each worktree.
 Enter worktrees, execute commands, or run tasks without changing directories.
 
 📍 **Predictable structure**
-All managed worktrees live under `~/.yggtree`, keeping your repository clean.
+Managed worktrees default to `~/.yggtree`, with an optional global path setting for agent-native layouts.
 
 🧭 **Interactive or scriptable**
 Use the interactive UI or drive everything through commands and flags.
@@ -217,12 +218,12 @@ Sometimes you don't want to "commit to a branch" yet. You just want to try somet
 
 1.  **Create**: `yggtree create-sandbox` (creates something like `sandbox-a3f2_feature-branch`).
 2.  **Experiment**: Change files, run tests, try that risky refactor.
-3.  **Apply**: `yggtree apply` to "push" those file changes back to your origin directory.
-4.  **Unapply**: Don't like it? `yggtree unapply` restores your origin to exactly how it was before.
+3.  **Apply**: `yggtree apply` to copy changed sandbox files back to your origin directory with backups.
+4.  **Unapply**: Don't like it? `yggtree unapply` restores those backed-up origin files while the sandbox still exists.
 
 Sandboxes are **not pushed to remote**. Omit the name for a generated temporary sandbox, or provide one when the work needs to be easy to find later.
 
-Use `handoff` when you started in the origin checkout and want to continue that dirty work in a sandbox:
+Use `handoff` when you started in the origin checkout and want to continue that dirty work in a sandbox. This is the taught path for staged, unstaged, or untracked work:
 
 ```bash
 yggtree handoff --name auth-refactor
@@ -259,6 +260,48 @@ Resolution order:
 
 ---
 
+## 🗂️ Global Worktree Paths
+
+By default, managed worktrees use the Yggtree layout:
+
+```bash
+~/.yggtree/<repo-name>/<worktree-slug>
+```
+
+Show the active global setting:
+
+```bash
+yggtree config get
+```
+
+Use the Codex-style layout when you want Yggtree-created worktrees to live under Codex's worktree root:
+
+```bash
+yggtree config use codex
+```
+
+That preset creates new managed worktrees like:
+
+```bash
+~/.codex/worktrees/<worktree-slug>/<repo-name>
+```
+
+Set a custom managed root while keeping the Yggtree layout:
+
+```bash
+yggtree config set-worktrees-root ~/Worktrees
+```
+
+Return to defaults:
+
+```bash
+yggtree config reset
+```
+
+Claude and Cursor do not currently have a confirmed native worktree directory pattern in Yggtree. Until that is explicit, use `set-worktrees-root` with the directory you want rather than relying on an unverified preset.
+
+---
+
 ## 🛠️ Command Reference
 
 ### `yggtree`
@@ -349,12 +392,12 @@ yggtree wc hotfix-auth main --open --no-enter
 
 ### `yggtree create-sandbox`
 
-Create a temporary sandbox from your current local branch.
+Create a temporary local-only sandbox from your current branch.
 
 Options:
 
 *   `-n, --name <name>`: Optional sandbox name (auto-generated if omitted).
-*   `--carry / --no-carry`: Bring uncommitted changes (staged/unstaged/untracked) with you.
+*   `--carry / --no-carry`: Explicitly choose whether to copy uncommitted changes into the sandbox. Prefer `handoff` when the intent is continuing dirty work.
 *   `--no-bootstrap`
 *   `--open / --no-open`
 *   `--exec "<command>"`
@@ -378,29 +421,32 @@ Options:
 *   `--open / --no-open`
 *   `--exec "<command>"`
 
-This is the continuation-focused version of `create-sandbox --carry`: it keeps sandbox metadata and apply/unapply behavior, but defaults to carrying staged, unstaged, and untracked files.
+This is the continuation-focused semantic path for dirty work. It uses sandbox metadata and apply/unapply behavior, but defaults to carrying staged, unstaged, and untracked files.
 
 ---
 
 ### `yggtree apply`
 
-Apply changes from the current sandbox back to the origin repository. 
-*   **Backs up** origin files before overwriting.
+Copy changed files from the current sandbox back to the origin checkout.
+*   **Backs up** origin files in sandbox metadata before overwriting.
 *   **Offers to delete** the sandbox after applying.
+*   **Is not a Git merge**: review the origin diff after applying, especially when deletions are involved.
 
 ---
 
 ### `yggtree unapply`
 
 Undo a previous `apply` operation.
-*   Restores origin files from the sandbox's backup.
+*   Restores origin files from the sandbox's backup metadata.
 *   *Note: Only works if the sandbox worktree still exists.*
 
 ---
 
 ### `yggtree create-multi`
 
-Create multiple worktrees at once.
+Create multiple official branch-backed worktrees at once. This is a bulk setup
+command; it does not have the full `create` lifecycle flags such as `--open`,
+`--enter`, or `--exec`.
 
 Options:
 
@@ -434,7 +480,7 @@ Columns:
 Notes:
 
 * Entries are grouped by `TYPE`.
-* `SANDBOX` and `MANAGED` are worktrees inside `~/.yggtree`.
+* `SANDBOX` and `MANAGED` are worktrees inside the configured managed worktree root.
 * External worktrees are labeled `LINKED`.
 * Use `--open` to switch this flow into "pick and open in tool" mode.
 * The **PR** column shows the pull request status for each branch (e.g. `OPEN`, `IN REVIEW`, `APPROVED`, `MERGED`, `DRAFT`, `CHANGES`). It only appears when `gh` CLI is installed and authenticated — otherwise it's silently omitted.
@@ -449,7 +495,7 @@ Behavior:
 
 * If `[worktree]` is omitted, you can pick from the worktree list with type-to-filter search.
 * Detects available editor commands in your `PATH` (for example: `cursor`, `code`, `zed`, `webstorm`).
-* Detects Codex App on macOS and launches it with `open -b com.openai.codex`.
+* Detects Codex App on macOS and launches the selected worktree with `codex app <path>`.
 * Detects Cmux and Tmux when their CLI commands are available.
 * Lets you choose one editor, app, or terminal target interactively, or pass `--tool`.
 * Keeps Cmux, Tmux, and `Other command...` mutually exclusive by using a single action picker.
@@ -517,7 +563,7 @@ Behavior:
 
 Optional:
 
-* `--all` includes linked worktrees outside `~/.yggtree` (main/current worktree is excluded for safety)
+* `--all` includes linked worktrees outside the configured managed root (main/current worktree is excluded for safety)
 
 ---
 
@@ -661,7 +707,7 @@ Useful when you want to manually navigate or copy the path into scripts.
 **Command:**
 
 ```bash
-yggtree create-sandbox --carry
+yggtree handoff --name risky-refactor
 ```
 
 **Scenario:**
@@ -670,7 +716,7 @@ yggtree create-sandbox --carry
 2.  Run `handoff --name risky-refactor` to carry those changes into an isolated `sandbox-risky-refactor` folder.
 3.  Experiment freely.
 4.  If it works: `yggtree apply`.
-5.  If it fails: Just delete the sandbox or `unapply`.
+5.  If it fails after applying: run `yggtree unapply` before deleting the sandbox.
 
 </details>
 

package/dist/commands/config.js

@@ -0,0 +1,53 @@
+import chalk from 'chalk';
+import { formatGlobalConfig, getPresetConfig, getWorktreePathConfig, normalizeWorktreesRootInput, readGlobalConfig, writeGlobalConfig, } from '../lib/global-config.js';
+import { log } from '../lib/ui.js';
+export async function configGetCommand() {
+    const [rawConfig, resolvedConfig] = await Promise.all([
+        readGlobalConfig(),
+        getWorktreePathConfig(),
+    ]);
+    console.log(chalk.bold('\n  Yggtree config\n'));
+    formatGlobalConfig(rawConfig, resolvedConfig)
+        .forEach(line => console.log(`  ${line}`));
+    console.log('');
+}
+export async function configUseCommand(preset) {
+    const presetConfig = getPresetConfig(preset);
+    if (!presetConfig) {
+        log.error(`Unknown config preset "${preset}".`);
+        log.dim('Available presets: default, yggtree, codex');
+        return;
+    }
+    await writeGlobalConfig(presetConfig);
+    log.success(`Using ${preset} worktree layout.`);
+    await configGetCommand();
+}
+export async function configSetWorktreesRootCommand(root) {
+    const currentConfig = await readGlobalConfig();
+    await writeGlobalConfig({
+        ...currentConfig,
+        worktreesRoot: normalizeWorktreesRootInput(root),
+        worktreeLayout: currentConfig.worktreeLayout || 'yggtree',
+    });
+    log.success('Updated worktrees root.');
+    await configGetCommand();
+}
+export async function configSetWorktreeLayoutCommand(layout) {
+    if (layout !== 'yggtree' && layout !== 'codex') {
+        log.error(`Unknown worktree layout "${layout}".`);
+        log.dim('Available layouts: yggtree, codex');
+        return;
+    }
+    const currentConfig = await readGlobalConfig();
+    await writeGlobalConfig({
+        ...currentConfig,
+        worktreeLayout: layout,
+    });
+    log.success('Updated worktree layout.');
+    await configGetCommand();
+}
+export async function configResetCommand() {
+    await writeGlobalConfig({});
+    log.success('Reset Yggtree config to defaults.');
+    await configGetCommand();
+}

package/dist/commands/wt/bootstrap.js

@@ -2,23 +2,25 @@ import chalk from 'chalk';
 import inquirer from 'inquirer';
 import path from 'path';
 import { listWorktrees, getRepoRoot } from '../../lib/git.js';
-import { WORKTREES_ROOT } from '../../lib/paths.js';
+import { getManagedWorktreesRoot } from '../../lib/global-config.js';
 import { log } from '../../lib/ui.js';
 import { runBootstrap } from '../../lib/config.js';
+import { isManagedWorktreePath } from '../../lib/worktree.js';
 export async function bootstrapCommand() {
     try {
         const _ = await getRepoRoot();
         const worktrees = await listWorktrees();
+        const managedRoot = await getManagedWorktreesRoot();
         // 1. Select Worktree
         // Filter managed or just show all? The prompt said "managed", let's prioritize managed but maybe allow all if needed?
         // User requirements say "managed", sticking to that for consistency.
-        const managedWts = worktrees.filter(wt => wt.path.startsWith(WORKTREES_ROOT));
+        const managedWts = worktrees.filter(wt => isManagedWorktreePath(wt.path, managedRoot));
         if (managedWts.length === 0) {
             log.info('No managed worktrees found to bootstrap.');
             return;
         }
         const choices = managedWts.map(wt => {
-            const relative = path.relative(WORKTREES_ROOT, wt.path);
+            const relative = path.relative(managedRoot, wt.path);
             return {
                 name: `${chalk.bold(relative)} (${chalk.dim(wt.branch || wt.HEAD)})`,
                 value: wt.path,

package/dist/commands/wt/create-branch.js

@@ -3,7 +3,7 @@ import inquirer from 'inquirer';
 import path from 'path';
 import { getRepoRoot, getRepoName, verifyRef, fetchAll, getCurrentBranch, ensureCorrectUpstream, publishBranch } from '../../lib/git.js';
 import { runBootstrap } from '../../lib/config.js';
-import { WORKTREES_ROOT } from '../../lib/paths.js';
+import { buildManagedWorktreePath, getWorktreePathConfig } from '../../lib/global-config.js';
 import { log, ui, createSpinner } from '../../lib/ui.js';
 import { promptAndCopyEnvFiles } from '../../lib/env-files.js';
 import { detectInstalledOpenTools, launchOpenTool, promptOpenToolSelection, } from './open.js';
@@ -89,7 +89,8 @@ export async function createCommandNew(options) {
         // e.g. feat/new-button -> feat-new-button
         const slug = branchName.replace(/[\/\\]/g, '-').replace(/\s+/g, '-');
         const repoName = await getRepoName();
-        const wtPath = path.join(WORKTREES_ROOT, repoName, slug);
+        const worktreePathConfig = await getWorktreePathConfig();
+        const wtPath = buildManagedWorktreePath(repoName, slug, worktreePathConfig);
         // 2. Validation
         if (!slug)
             throw new Error('Invalid name');

package/dist/commands/wt/create-multi.js

@@ -3,7 +3,7 @@ import inquirer from 'inquirer';
 import path from 'path';
 import { getRepoRoot, getRepoName, verifyRef, fetchAll, getCurrentBranch, ensureCorrectUpstream, publishBranch } from '../../lib/git.js';
 import { runBootstrap } from '../../lib/config.js';
-import { WORKTREES_ROOT } from '../../lib/paths.js';
+import { buildManagedWorktreePath, getWorktreePathConfig } from '../../lib/global-config.js';
 import { log, ui, createSpinner } from '../../lib/ui.js';
 import { findLocalEnvFiles, promptAndCopyEnvFilesToWorktrees } from '../../lib/env-files.js';
 import { execa } from 'execa';
@@ -70,9 +70,10 @@ export async function createCommandMulti(options) {
         const createdWorktrees = [];
         // 3. Execution for each branch
         const repoName = await getRepoName();
+        const worktreePathConfig = await getWorktreePathConfig();
         for (const branchName of branchNames) {
             const slug = branchName.replace(/[\/\\]/g, '-').replace(/\s+/g, '-');
-            const wtPath = path.join(WORKTREES_ROOT, repoName, slug);
+            const wtPath = buildManagedWorktreePath(repoName, slug, worktreePathConfig);
             log.header(`Processing: ${branchName}`);
             const wtSpinner = createSpinner(`Creating worktree at ${ui.path(wtPath)}...`).start();
             // Check if target branch already exists

package/dist/commands/wt/create-sandbox.js

@@ -3,7 +3,7 @@ import inquirer from 'inquirer';
 import path from 'path';
 import { getRepoRoot, getRepoName, getCurrentBranch } from '../../lib/git.js';
 import { runBootstrap } from '../../lib/config.js';
-import { WORKTREES_ROOT } from '../../lib/paths.js';
+import { buildManagedWorktreePath, getWorktreePathConfig } from '../../lib/global-config.js';
 import { log, ui, createSpinner } from '../../lib/ui.js';
 import { generateSandboxName, normalizeSandboxName, writeSandboxMeta } from '../../lib/sandbox.js';
 import { promptAndCopyEnvFiles } from '../../lib/env-files.js';
@@ -136,7 +136,8 @@ export async function createSandboxCommand(options = {}) {
         }
         // 5. Create worktree
         const repoName = await getRepoName();
-        const wtPath = path.join(WORKTREES_ROOT, repoName, sandboxName);
+        const worktreePathConfig = await getWorktreePathConfig();
+        const wtPath = buildManagedWorktreePath(repoName, sandboxName, worktreePathConfig);
         const spinner = createSpinner('Creating sandbox worktree...').start();
         try {
             await fs.ensureDir(path.dirname(wtPath));

package/dist/commands/wt/create.js

@@ -3,7 +3,7 @@ import inquirer from 'inquirer';
 import path from 'path';
 import { getRepoName, createWorktree, fetchAll, listWorktrees } from '../../lib/git.js';
 import { runBootstrap } from '../../lib/config.js';
-import { WORKTREES_ROOT } from '../../lib/paths.js';
+import { buildManagedWorktreePath, getWorktreePathConfig } from '../../lib/global-config.js';
 import { log, ui, createSpinner } from '../../lib/ui.js';
 import { ensureAutocompletePrompt } from '../../lib/prompt.js';
 import { promptAndCopyEnvFiles } from '../../lib/env-files.js';
@@ -204,7 +204,8 @@ export async function createCommand(options) {
         // 3. Gather remaining inputs
         const defaultSlug = toSlug(selectedBranch.branchName);
         const repoName = await getRepoName();
-        const resolveWorktreePath = (name) => path.join(WORKTREES_ROOT, repoName, toSlug(name));
+        const worktreePathConfig = await getWorktreePathConfig();
+        const resolveWorktreePath = (name) => buildManagedWorktreePath(repoName, toSlug(name), worktreePathConfig);
         const answers = await inquirer.prompt([
             {
                 type: 'input',

package/dist/commands/wt/delete.js

@@ -1,19 +1,21 @@
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { listWorktrees, removeWorktree, getRepoRoot, getLastActivity } from '../../lib/git.js';
+import { getManagedWorktreesRoot } from '../../lib/global-config.js';
 import { log, createSpinner, timeAgo } from '../../lib/ui.js';
 import { detectWorktreeType, formatWorktreeDisplayPath, formatWorktreeType, getWorktreeBranchName, isManagedWorktreePath, } from '../../lib/worktree.js';
 export async function deleteCommand(options = {}) {
     try {
         const currentWorktreePath = await getRepoRoot();
         const worktrees = await listWorktrees();
+        const managedRoot = await getManagedWorktreesRoot();
         let showAll = options.all;
         if (showAll === undefined) {
             const { includeExternal } = await inquirer.prompt([
                 {
                     type: 'confirm',
                     name: 'includeExternal',
-                    message: 'Include external linked worktrees (outside ~/.yggtree)?',
+                    message: 'Include external linked worktrees (outside the managed root)?',
                     default: false,
                 },
             ]);
@@ -27,7 +29,7 @@ export async function deleteCommand(options = {}) {
                 const isCurrentWorktree = wt.path === currentWorktreePath;
                 return !isMainWorktree && !isCurrentWorktree;
             }
-            return isManagedWorktreePath(wt.path);
+            return isManagedWorktreePath(wt.path, managedRoot);
         });
         if (deletableWts.length === 0) {
             log.info(includeAll
@@ -38,11 +40,11 @@ export async function deleteCommand(options = {}) {
         const choices = await Promise.all(deletableWts.map(async (wt) => {
             const [activity, type] = await Promise.all([
                 getLastActivity(wt.path),
-                detectWorktreeType(wt, mainWorktreePath || ''),
+                detectWorktreeType(wt, mainWorktreePath || '', managedRoot),
             ]);
             const branchName = getWorktreeBranchName(wt);
             const active = activity ? chalk.magenta(timeAgo(activity)) : chalk.dim('—');
-            const displayPath = formatWorktreeDisplayPath(wt.path);
+            const displayPath = formatWorktreeDisplayPath(wt.path, managedRoot);
             return {
                 name: `${formatWorktreeType(type)} ${chalk.bold.yellow(branchName)} ${chalk.dim('·')} ${active} ${chalk.dim('·')} ${chalk.dim(displayPath)}`,
                 value: wt.path,
@@ -62,7 +64,7 @@ export async function deleteCommand(options = {}) {
             return;
         }
         const count = selectedPaths.length;
-        const names = selectedPaths.map((p) => formatWorktreeDisplayPath(p));
+        const names = selectedPaths.map((p) => formatWorktreeDisplayPath(p, managedRoot));
         const { confirm } = await inquirer.prompt([
             {
                 type: 'confirm',
@@ -76,7 +78,7 @@ export async function deleteCommand(options = {}) {
             return;
         }
         for (const wtPath of selectedPaths) {
-            const worktreeName = formatWorktreeDisplayPath(wtPath);
+            const worktreeName = formatWorktreeDisplayPath(wtPath, managedRoot);
             const spinner = createSpinner(`Deleting ${worktreeName}...`).start();
             try {
                 await removeWorktree(wtPath);

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';
@@ -40,13 +41,14 @@ export async function enterCommand(wtName, options = {}) {
         await ensureRepoContext();
         const worktrees = await listWorktrees();
         const mainWorktreePath = worktrees[0]?.path || '';
+        const managedRoot = await getManagedWorktreesRoot();
         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) {
@@ -10,12 +11,13 @@ export async function execCommand(wtName, commandArgs) {
     try {
         await getRepoRoot();
         const worktrees = await listWorktrees();
+        const managedRoot = await getManagedWorktreesRoot();
         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,5 +1,6 @@
 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() {
@@ -7,6 +8,7 @@ export async function listCommand() {
         await getRepoRoot(); // Verify we are in a git repo
         const worktrees = await listWorktrees();
         const mainWorktreePath = worktrees[0]?.path || '';
+        const managedRoot = await getManagedWorktreesRoot();
         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',
@@ -367,13 +384,14 @@ export async function openCommand(wtName, options = {}) {
         await getRepoRoot();
         const worktrees = await listWorktrees();
         const mainWorktreePath = worktrees[0]?.path || '';
+        const managedRoot = await getManagedWorktreesRoot();
         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 worktrees = await listWorktrees();
+        const managedRoot = await getManagedWorktreesRoot();
         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,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';
@@ -16,13 +17,23 @@ 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')
@@ -35,7 +46,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 +56,7 @@ 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')
+        .addHelpText('after', createHelp)
         .action(async (branch, options) => {
         await createCommandNew({
             ...options,
@@ -52,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);
     });
@@ -71,6 +84,7 @@ 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')
+            .addHelpText('after', checkoutHelp)
             .action(async (name, ref, options) => {
             await createCommand({
                 ...options,
@@ -83,7 +97,7 @@ 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);
     });
@@ -92,6 +106,7 @@ function registerWorktreeCommands(parent) {
         .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);
     });
@@ -114,21 +129,22 @@ 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 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 +152,17 @@ 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')
+        .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 +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: `🤝 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 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,
         },
     ]);
@@ -270,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);
@@ -279,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.4",
+  "version": "1.4.5",
   "packageManager": "pnpm@11.0.9",
   "description": "Interactive CLI for managing git worktrees and configs",
   "main": "dist/index.js",