run

#!/usr/bin/env python3
"""
run - Cross-platform CLI tool for Deft framework
A layered framework for AI-assisted development

Works on: macOS, Linux, Windows, FreeBSD
Optional: rich (for enhanced output and better UX)
"""

import sys
import os
import json
import shutil
import subprocess
from pathlib import Path
from datetime import datetime
from typing import List, Optional

VERSION = "0.4.3"

# Try to import rich for enhanced experience
try:
    from rich.console import Console
    from rich.prompt import Prompt, Confirm
    from rich.panel import Panel
    from rich.markdown import Markdown
    from rich.text import Text
    HAS_RICH = True
    console = Console()
except ImportError:
    HAS_RICH = False
    console = None
    # Fall back to readline on Unix for arrow key support
    try:
        import readline  # Enable history and arrow keys on Unix
    except ImportError:
        pass  # Windows: basic input() still works

# Try to import prompt_toolkit
try:
    import prompt_toolkit
    HAS_PROMPT_TOOLKIT = True
except ImportError:
    HAS_PROMPT_TOOLKIT = False

# Try to import textual for TUI mode
try:
    from textual.app import App, ComposeResult
    from textual.screen import Screen
    from textual.widgets import Header, Footer, Button, Label, Input, Select, OptionList, Static, MarkdownViewer, Checkbox
    from textual.widgets._option_list import Option
    from textual.containers import Container, Horizontal, Vertical, ScrollableContainer
    HAS_TEXTUAL = True
except ImportError:
    HAS_TEXTUAL = False

# Output helpers
def print_header(text: str):
    """Print main command header"""
    if HAS_RICH:
        console.print(Panel(f"[bold cyan]{text}[/bold cyan]", border_style="cyan"))
    else:
        print(f"\n{'=' * 60}")
        print(f"  {text}")
        print('=' * 60)

def print_section(text: str):
    """Print section header within a command"""
    if HAS_RICH:
        console.print(Markdown(f"## {text}"))
    else:
        print(f"\n{'-' * 60}")
        print(f"  {text}")
        print('-' * 60)

def print_info(msg: str):
    """Print info message"""
    if HAS_RICH:
        console.print(f"[blue]ℹ[/blue] {msg}")
    else:
        print(f"ℹ {msg}")

def print_success(msg: str):
    """Print success message"""
    if HAS_RICH:
        console.print(f"[green]✓[/green] {msg}")
    else:
        print(f"✓ {msg}")

def print_warn(msg: str):
    """Print warning message"""
    if HAS_RICH:
        console.print(f"[yellow]⚠[/yellow] {msg}")
    else:
        print(f"⚠ {msg}")

def print_error(msg: str):
    """Print error message"""
    if HAS_RICH:
        console.print(f"[red]✗[/red] {msg}")
    else:
        print(f"✗ {msg}")

# Legacy aliases for backward compatibility
info = print_info
success = print_success
warn = print_warn
error = print_error

def get_script_dir() -> Path:
    """Get the directory where this script is located"""
    return Path(__file__).parent.absolute()

def resolve_path(path_str: str) -> Path:
    """Resolve a user-supplied path string to an absolute Path.
    
    Expands ~ and resolves relative paths against cwd.
    """
    return Path(path_str).expanduser().resolve()

def get_default_paths() -> dict:
    """Return default output paths for all generated files.
    
    Environment variables override built-in defaults:
        DEFT_USER_PATH          default: ~/.config/deft/USER.md
        DEFT_PROJECT_PATH       default: ./PROJECT.md
        DEFT_PRD_PATH           default: ./PRD.md
        DEFT_SPECIFICATION_PATH default: ./SPECIFICATION.md
        DEFT_INTERVIEW_PATH     default: ./INTERVIEW.md (Light sizing path only; not in returned dict)
    
    Returns:
        dict with keys 'user', 'project', 'prd', 'specification'
    """
    return {
        'user': os.environ.get('DEFT_USER_PATH', '~/.config/deft/USER.md'),
        'project': os.environ.get('DEFT_PROJECT_PATH', './PROJECT.md'),
        'prd': os.environ.get('DEFT_PRD_PATH', './PRD.md'),
        'specification': os.environ.get('DEFT_SPECIFICATION_PATH', './SPECIFICATION.md'),
    }

# ── Resume / atomic-write helpers (issue #8) ─────────────────────────

def _progress_path(output_file: Path) -> Path:
    """Return the progress-file path for a given output file.

    Convention: .{filename}.progress in the same directory.
    """
    return output_file.parent / f".{output_file.name}.progress"

def _save_progress(prog_file: Path, data: dict):
    """Persist questionnaire progress to a JSON file (best-effort)."""
    try:
        prog_file.parent.mkdir(parents=True, exist_ok=True)
        tmp = prog_file.parent / f".{prog_file.name}.tmp"
        tmp.write_text(json.dumps(data, indent=2), encoding='utf-8')
        os.replace(str(tmp), str(prog_file))
    except OSError:
        pass

def _load_progress(prog_file: Path) -> dict:
    """Load saved questionnaire progress.  Returns {} on missing/corrupt file."""
    if not prog_file.exists():
        return {}
    try:
        return json.loads(prog_file.read_text(encoding='utf-8'))
    except (json.JSONDecodeError, OSError):
        return {}

def _clear_progress(prog_file: Path):
    """Delete a progress file if it exists."""
    try:
        if prog_file.exists():
            prog_file.unlink()
    except OSError:
        pass

def _atomic_write(target: Path, content: str):
    """Write *content* to *target* via temp + rename for crash safety."""
    target.parent.mkdir(parents=True, exist_ok=True)
    tmp = target.parent / f".{target.name}.tmp"
    tmp.write_text(content, encoding='utf-8')
    os.replace(str(tmp), str(target))

def _resume_or_ask(progress: dict, prog_file: Path, key: str,
                   label: str, ask_fn, *args, **kwargs):
    """Return a saved answer from *progress*, or call *ask_fn* and persist it."""
    if key in progress:
        info(f"  [resumed] {label}: {progress[key]}")
        return progress[key]
    val = ask_fn(*args, **kwargs)
    progress[key] = val
    _save_progress(prog_file, progress)
    return val

# Legacy path helpers for backward compatibility
def _legacy_user_path() -> Path:
    """Old location for user.md (inside deft framework dir)."""
    return get_script_dir() / "core" / "user.md"

def _legacy_project_path() -> Path:
    """Old location for project.md (inside deft framework dir)."""
    return Path("./deft/core/project.md")

# Non-language support files to exclude from language selection
_NON_LANGUAGE_FILES = {'commands', 'markdown', 'mermaid'}

# Display name overrides for language file stems
_LANGUAGE_DISPLAY_NAMES = {
    'cpp': 'C++',
    'c#': 'C#',
    'c': 'C',
    'r': 'R',
    'sql': 'SQL',
    'vhdl': 'VHDL',
    'javascript': 'JavaScript',
    'typescript': 'TypeScript',
    'visual-basic': 'Visual Basic',
}

def get_available_languages() -> List[tuple]:
    """Scan languages/ directory and return available programming languages.
    
    Returns:
        Sorted list of (stem, display_name) tuples.
        Excludes non-language support files (commands, markdown, mermaid).
    """
    lang_dir = get_script_dir() / "languages"
    if not lang_dir.is_dir():
        return []
    
    languages = []
    for f in lang_dir.glob("*.md"):
        stem = f.stem
        if stem.lower() in _NON_LANGUAGE_FILES:
            continue
        display = _LANGUAGE_DISPLAY_NAMES.get(
            stem, _LANGUAGE_DISPLAY_NAMES.get(
            stem.lower(), stem.replace('-', ' ').title()))
        languages.append((stem, display))
    
    return sorted(languages, key=lambda x: x[1].lower())

def _lang_widget_id(stem: str) -> str:
    """Create a valid Textual widget ID from a language file stem."""
    return "lang_" + stem.replace('#', 'sharp').replace('+', 'plus')

# Non-strategy support files to exclude from strategy selection
# Includes aliases (brownfield, default) which are internal and should not appear in the picker
_NON_STRATEGY_FILES = {'readme', 'brownfield', 'default'}

# Display name overrides for strategy file stems
_STRATEGY_DISPLAY_NAMES = {
    'speckit': 'SpecKit',
}

# One-line descriptions shown in strategy picker
_STRATEGY_DESCRIPTIONS = {
    'interview': 'Structured interview with sizing gate — Light (embedded spec) or Full (PRD → spec)',
    'yolo':      'Auto-pilot interview — Johnbot picks all recommended options',
    'map':       'Analyze existing codebase conventions before adding features',
    'discuss':   'Front-load decisions and alignment before planning',
    'research':  'Investigate the domain before planning',
    'speckit':   'Five-phase spec-driven workflow for large/complex projects',
    # 'default' and 'brownfield' are aliases excluded via _NON_STRATEGY_FILES — no entries needed here
}

def get_available_strategies() -> List[tuple]:
    """Scan strategies/ directory and return available strategies.
    
    Returns:
        Sorted list of (stem, display_name) tuples.
        Excludes non-strategy support files (README).
    """
    strat_dir = get_script_dir() / "strategies"
    if not strat_dir.is_dir():
        return []
    
    strategies = []
    for f in strat_dir.glob("*.md"):
        stem = f.stem
        if stem.lower() in _NON_STRATEGY_FILES:
            continue
        display = _STRATEGY_DISPLAY_NAMES.get(
            stem, _STRATEGY_DISPLAY_NAMES.get(
            stem.lower(), stem.replace('-', ' ').title()))
        strategies.append((stem, display))
    
    return sorted(strategies, key=lambda x: x[1].lower())

def usage():
    """Print usage information"""
    hint = ""
    if not HAS_RICH:
        # Get the Python executable path for accurate install command
        python_exe = sys.executable
        stdlib_path = Path(sys.base_prefix) / "lib" / f"python{sys.version_info.major}.{sys.version_info.minor}"
        is_externally_managed = (stdlib_path / "EXTERNALLY-MANAGED").exists()
        
        install_cmd = f"{python_exe} -m pip install"
        if is_externally_managed:
            install_cmd += " --break-system-packages"
        install_cmd += " rich"
        
        hint = f"\n💡 Tip: Install rich for enhanced output and better UX:\n   {install_cmd}\n"
    
    tui_hint = ""
    if HAS_TEXTUAL:
        tui_hint = "       run                     # Launch TUI wizard (no args)\n       run tui                  # Launch TUI wizard\n       run wizard               # Launch TUI wizard\n       "
    
    if HAS_RICH:
        print_header(f"Deft CLI v{VERSION}")
        tui_section = "[bold]TUI Mode:[/bold]\n  run / run tui / run wizard    Launch interactive wizard\n\n" if HAS_TEXTUAL else ""
        console.print(f"""
{tui_section}[bold]Usage:[/bold] run <command> [options]
       run -h, --help, -help    # Show this help
       python run <command> [options]       # If not executable
       python3 run <command> [options]      # If not executable

[bold cyan]Commands:[/bold cyan]
  [green]bootstrap[/green]       Set up your user preferences (user.md)
  [green]project[/green]         Create/update project configuration (project.md)
  [green]spec[/green]            Generate project specification via interview (--force to overwrite)
  [green]install[/green]         Install deft framework in a project directory
  [green]reset[/green]           Reset configuration files to default state
  [green]validate[/green]        Validate deft configuration files
  [green]update[/green]          Update deft framework to latest version
  [green]doctor[/green]          Check system dependencies and configuration
  [green]help[/green]            Show this help message

[bold cyan]Examples:[/bold cyan]
  run                        # Launch TUI wizard (if textual installed)
  run bootstrap              # First-time setup
  run project                # Configure current project
  run spec                   # Generate SPECIFICATION.md
  run install ~/my-project   # Install deft in a project
  run reset                  # Reset config files (interactive)
  run reset --all            # Reset all config files (no prompts)
  run validate               # Check configuration is valid

For more information: [link]https://github.com/deftai/directive[/link]
""")
    else:
        tui_section = f"TUI Mode:\n{tui_hint}\n" if HAS_TEXTUAL else ""
        print(f"""Deft CLI v{VERSION}{hint}

{tui_section}Usage: run <command> [options]
       run -h, --help, -help    # Show this help
       python run <command> [options]       # If not executable
       python3 run <command> [options]      # If not executable

Commands:
  bootstrap       Set up your user preferences (user.md)
  project         Create/update project configuration (project.md)
  spec            Generate project specification via interview (--force to overwrite)
  install         Install deft framework in a project directory
  reset           Reset configuration files to default state
  validate        Validate deft configuration files
  update          Update deft framework to latest version
  doctor          Check system dependencies and configuration
  help            Show this help message

Examples:
  run                        # Launch TUI wizard (if textual installed)
  run bootstrap              # First-time setup
  run project                # Configure current project
  run spec                   # Generate SPECIFICATION.md
  run install ~/my-project   # Install deft in a project
  run reset                  # Reset config files (interactive)
  run reset --all            # Reset all config files (no prompts)
  run validate               # Check configuration is valid

For more information: https://github.com/deftai/directive
""")

def ask_input(prompt_text: str, default: str = "") -> str:
    """Read user input with optional default
    
    Args:
        prompt_text: The prompt to display
        default: Default value if user presses Enter
    
    Returns:
        User input or default value
    """
    try:
        # Priority: prompt_toolkit (best editing) > rich > basic input
        if HAS_PROMPT_TOOLKIT:
            from prompt_toolkit import prompt as pt_prompt
            from prompt_toolkit.formatted_text import HTML
            # Add colored prefix if rich is also available
            if HAS_RICH:
                display_prompt = HTML(f'<ansibrightcyan>?</ansibrightcyan> {prompt_text}: ')
            else:
                display_prompt = prompt_text + ": "
            
            value = pt_prompt(display_prompt, default=default)
            return value if value else default
        elif HAS_RICH:
            # Add colored question mark prefix
            formatted_prompt = f"[cyan]?[/cyan] {prompt_text}"
            value = Prompt.ask(formatted_prompt, default=default if default else None)
            return value if value else default
        else:
            # Fall back to basic input() with readline support (if available on Unix)
            if default:
                value = input(f"{prompt_text} [{default}]: ")
            else:
                value = input(f"{prompt_text}: ")
            return value if value else default
    except EOFError:
        return default

def ask_choice(prompt_text: str, choices: List[str], default: str = None) -> str:
    """Read user choice from list
    
    Args:
        prompt_text: The prompt to display
        choices: List of valid choices
        default: Default choice
    
    Returns:
        User's choice
    """
    try:
        if HAS_RICH:
            # Add colored question mark prefix
            formatted_prompt = f"[cyan]?[/cyan] {prompt_text}"
            return Prompt.ask(formatted_prompt, choices=choices, default=default)
        else:
            # Fallback: show numbered list
            print(f"\n{prompt_text}")
            for i, choice in enumerate(choices, 1):
                print(f"  {i}. {choice}")
            while True:
                ans = input("Enter number: ")
                try:
                    idx = int(ans) - 1
                    if 0 <= idx < len(choices):
                        return choices[idx]
                except ValueError:
                    pass
                print("Invalid choice, try again.")
    except EOFError:
        return default if default else choices[0]

def ask_confirm(prompt_text: str, default: bool = False) -> bool:
    """Read yes/no confirmation
    
    Args:
        prompt_text: The prompt to display
        default: Default value
    
    Returns:
        True if user confirms, False otherwise
    """
    try:
        # Priority: prompt_toolkit > rich > basic input
        if HAS_PROMPT_TOOLKIT:
            from prompt_toolkit import prompt as pt_prompt
            from prompt_toolkit.formatted_text import HTML
            # Add colored prefix if rich is also available
            suffix = " (Y/n): " if default else " (y/N): "
            if HAS_RICH:
                display_prompt = HTML(f'<ansibrightcyan>?</ansibrightcyan> {prompt_text}{suffix}')
            else:
                display_prompt = prompt_text + suffix
            
            response = pt_prompt(display_prompt, default="")
            if not response:
                return default
            return response.strip().lower() in ('y', 'yes')
        elif HAS_RICH:
            # Add colored question mark prefix
            formatted_prompt = f"[cyan]?[/cyan] {prompt_text}"
            return Confirm.ask(formatted_prompt, default=default)
        else:
            suffix = " (Y/n) " if default else " (y/N) "
            response = input(f"{prompt_text}{suffix}")
            if not response:
                return default
            return response.strip().lower() in ('y', 'yes')
    except EOFError:
        return default

# Legacy aliases
read_input = ask_input
read_yn = ask_confirm

def cmd_bootstrap(args: List[str]):
    """Bootstrap command - set up user.md"""
    print_header(f"Deft CLI v{VERSION} - Bootstrap")
    print()
    info("This command creates user.md, which defines YOUR personal preferences:")
    info("  • Your name (how the AI should address you)")
    info("  • Primary programming languages")
    info("  • Default test coverage threshold")
    info("  • Development strategy")
    info("  • Custom rules and experimental guidelines")
    print()
    info("These preferences apply across all your projects and only need to be set once.")
    info("You can update them anytime by editing user.md or re-running bootstrap.")
    print()
    
    defaults = get_default_paths()
    
    # Resume support (issue #8)
    prog_file = _progress_path(resolve_path(defaults['user']))
    progress = {}
    if prog_file.exists():
        saved = _load_progress(prog_file)
        if saved:
            print_section("Previous Session Found")
            for k, v in saved.items():
                if not k.startswith('_'):
                    info(f"  {k}: {v}")
            print()
            if read_yn("Resume where you left off?", default=True):
                progress = saved
            else:
                _clear_progress(prog_file)
    
    if 'output_path' not in progress:
        print_section("Output Location")
    user_path_str = _resume_or_ask(progress, prog_file, 'output_path', 'Output',
                                    read_input, "Where to write USER.md", defaults['user'])
    user_file = resolve_path(user_path_str)
    
    # Check if file exists (skip when resuming — user already committed)
    if not progress.get('user_name'):
        if user_file.exists() and "--force" not in args:
            info(f"USER.md already exists at {user_file}")
            if not read_yn("Overwrite with new preferences?"):
                success("Keeping existing USER.md as-is.")
                print()
                # Still offer next steps even when keeping existing file
                print_section("Next Steps")
                if read_yn("Would you like to run 'run project' now?", default=True):
                    print()
                    return cmd_project([])
                else:
                    print()
                    info("You can run 'run project' later to configure your project")
                    return 0
    
    if 'user_name' not in progress:
        print()
        print_section("User Preferences Setup")
    
    # Gather user information
    user_name = _resume_or_ask(progress, prog_file, 'user_name', 'Name',
                                read_input, "Your name (how AI should address you)")
    if 'coverage' not in progress:
        while True:
            coverage = read_input("Default coverage threshold (default: 85%)", "85")
            if not coverage.strip():
                coverage = "85"
                break
            try:
                val = int(coverage.strip())
                if 1 <= val <= 100:
                    break
            except ValueError:
                pass
            print_error("Please enter a number between 1 and 100.")
        progress['coverage'] = coverage
        _save_progress(prog_file, progress)
    else:
        coverage = progress['coverage']
        info(f"  [resumed] Coverage: {coverage}")
    
    available_langs = get_available_languages()
    other_num = len(available_langs) + 1
    valid_lang_nums = set(str(i) for i in range(1, other_num + 1))
    if 'lang_selection' not in progress:
        print()
        print_section("Programming Languages")
        info("Select your primary programming languages (comma-separated):")
        for i, (stem, display) in enumerate(available_langs, 1):
            print(f"  {i}. {display}")
        print(f"  {other_num}. Other")
        while True:
            lang_selection = read_input("Selection (e.g., 1,3 or Enter to skip)")
            if not lang_selection.strip():
                break  # Skip
            nums = [s.strip() for s in lang_selection.split(',')]
            if len(nums) != len(set(nums)):
                print_error("Duplicate selections are not allowed.")
                continue
            if all(n in valid_lang_nums for n in nums):
                break
            print_error(f"Please enter numbers between 1 and {other_num} (comma-separated).")
        progress['lang_selection'] = lang_selection
        _save_progress(prog_file, progress)
    else:
        lang_selection = progress['lang_selection']
        info(f"  [resumed] Languages: {lang_selection or '(skipped)'}")
    
    lang_nums = [s.strip() for s in lang_selection.split(',')]
    languages = []
    for num in lang_nums:
        try:
            idx = int(num) - 1
            if 0 <= idx < len(available_langs):
                languages.append(f"- {available_langs[idx][1]}")
            elif int(num) == other_num:
                other_lang = _resume_or_ask(progress, prog_file, 'other_lang',
                                            'Other language', read_input, "Enter language name")
                if other_lang:
                    languages.append(f"- {other_lang}")
        except ValueError:
            pass
    
    languages_str = '\n'.join(languages) if languages else "- (None specified)"
    
    available_strats = get_available_strategies()
    max_strat = len(available_strats)
    # Default to 'interview' strategy if available, otherwise first
    default_strat_num = "1"
    for i, (stem, _) in enumerate(available_strats, 1):
        if stem.lower() == "interview":
            default_strat_num = str(i)
            break
    if 'strat_selection' not in progress:
        if max_strat == 0:
            warn("No strategy files found in strategies/ — defaulting to Interview.")
            strat_selection = "1"
        else:
            print()
            print_section("Development Strategy")
            info("Select your default development strategy:")
            for i, (stem, display) in enumerate(available_strats, 1):
                desc = _STRATEGY_DESCRIPTIONS.get(stem, '')
                marker = " ★ RECOMMENDED" if str(i) == default_strat_num else ""
                print(f"  {i}. {display}{marker}")
                if desc:
                    print(f"     {desc}")
            print()
            info("💡 Strategies can be chained — after one completes, you'll be asked if you want to run another.")
            while True:
                strat_selection = read_input("Selection", default_strat_num)
                if not strat_selection.strip():
                    strat_selection = default_strat_num
                    break
                try:
                    num = int(strat_selection.strip())
                    if 1 <= num <= max_strat:
                        break
                except ValueError:
                    pass
                print_error(f"Please enter a number between 1 and {max_strat}.")
        progress['strat_selection'] = strat_selection
        _save_progress(prog_file, progress)
    else:
        strat_selection = progress['strat_selection']
        info(f"  [resumed] Strategy: {strat_selection}")
    
    try:
        strat_idx = int(strat_selection.strip()) - 1
        if 0 <= strat_idx < len(available_strats):
            selected_strategy = available_strats[strat_idx]
        else:
            selected_strategy = available_strats[0] if available_strats else ("interview", "Interview")
    except ValueError:
        selected_strategy = available_strats[0] if available_strats else ("interview", "Interview")
    strategy_stem, strategy_display = selected_strategy
    
    showed_custom_rules_header = 'has_custom_rules' not in progress
    if 'has_custom_rules' not in progress:
        print()
        print_section("Custom Rules")
        info("Add rules the AI must always follow (optional). Enter one rule per line, empty line to finish.")
        has_rules = read_yn("Do you have custom rules to add?")
        progress['has_custom_rules'] = has_rules
        _save_progress(prog_file, progress)
    else:
        has_rules = progress['has_custom_rules']

    if 'custom_rules' not in progress:
        if has_rules:
            if not showed_custom_rules_header:
                print()
                print_section("Custom Rules")
                info("Continuing rule collection (interrupted mid-loop). Empty line to finish.")
                print()
            rules_list = list(progress.get('custom_rules_wip', []))
            if rules_list:
                info(f"  [resumed] {len(rules_list)} rule(s) already collected:")
                for r in rules_list:
                    info(f"    {r}")
            while True:
                rule = read_input("  Rule (or Enter to finish)")
                if not rule.strip():
                    break
                rules_list.append(f"- {rule.strip().lstrip('- ').strip()}")
                progress['custom_rules_wip'] = rules_list
                _save_progress(prog_file, progress)
            custom_rules = '\n'.join(rules_list) if rules_list else ""
        else:
            custom_rules = ""
        progress['custom_rules'] = custom_rules
        progress.pop('custom_rules_wip', None)
        _save_progress(prog_file, progress)
    else:
        custom_rules = progress['custom_rules']
        display = custom_rules.replace('\n', '; ')
        info(f"  [resumed] Custom rules: {display[:60] + '...' if len(custom_rules) > 60 else display or '(none)'}")
    
    if any(k not in progress for k in ('use_soul', 'use_morals', 'use_code_field')):
        print()
        print_section("Meta Guidelines")
        info("Deft ships three meta-guidelines that shape how the AI behaves. All are included")
        info("by default — press Enter to keep each, or n to drop it.")
        print()
        info("SOUL.md — Results-first agent persona (inspired by Winston Wolf).")
        info("  Enforces assess-before-acting, finish-what-you-start, right-tool-for-the-job,")
        info("  and play-the-long-game. Keeps the AI decisive and concise rather than narrating")
        info("  every step. Includes a named persona ('Vinston') — drop if you prefer to define")
        info("  your own agent personality.")
        print()
        info("morals.md — Epistemic honesty rules.")
        info("  No presenting speculation as fact, label unverified claims, self-correct when")
        info("  wrong. Foundational trust rules for any AI agent. Strongly recommended.")
        print()
        info("code-field.md — Pre-code assumption protocol.")
        info("  Requires stating assumptions, naming failure modes, and writing only code the AI")
        info("  can defend — before writing a single line. Fights the 'it compiles, ship it'")
        info("  instinct. Based on the NeoVertex1 context-field framework.")
        print()
    use_soul = _resume_or_ask(progress, prog_file, 'use_soul', 'SOUL.md',
                               read_yn, "Include meta/SOUL.md? (Results-first persona)", default=True)
    use_morals = _resume_or_ask(progress, prog_file, 'use_morals', 'morals.md',
                                 read_yn, "Include meta/morals.md? (Epistemic honesty rules)", default=True)
    use_code_field = _resume_or_ask(progress, prog_file, 'use_code_field', 'code-field.md',
                                     read_yn, "Include meta/code-field.md? (Pre-code assumption protocol)", default=True)
    
    # Build experimental rules section
    experimental_rules = []
    if use_soul:
        experimental_rules.append("- ! Use meta/SOUL.md for strategic context and purpose-driven guidance")
    if use_morals:
        experimental_rules.append("- ! Use meta/morals.md for ethical AI development principles")
    if use_code_field:
        experimental_rules.append("- ~ Use meta/code-field.md for advanced architecture patterns")
    
    experimental_section = ""
    if experimental_rules:
        experimental_section = "\n## Experimental Rules\n\n" + "\n".join(experimental_rules)
    
    # Build coverage override line (only if non-default)
    coverage_line = f"\n**Coverage**: ! ≥{coverage}% test coverage" if coverage != "85" else ""
    
    # Build strategy line (omit link when no strategy files exist)
    if available_strats:
        strategy_line = f"**Default Strategy**: [{strategy_display}](../strategies/{strategy_stem}.md)"
    else:
        strategy_line = f"**Default Strategy**: {strategy_display}"
    
    # Generate user.md
    user_content = f"""# User Preferences

Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.

## Personal (always wins)

Settings in this section have HIGHEST precedence — override all other deft rules,
including PROJECT.md.

**Name**: Address the user as: **{user_name}**

**Custom Rules**:
{custom_rules if custom_rules else "No custom rules defined yet."}

## Defaults (fallback)

Settings in this section are fallback defaults. PROJECT.md overrides these
for project-scoped settings (strategy, coverage, languages).

**Primary Languages**:
{languages_str}

{strategy_line}
{coverage_line}
{experimental_section}

---

**Note**: You can edit this file anytime to update your preferences.
**See**: [../main.md](../main.md) for framework defaults.
"""
    
    _atomic_write(user_file, user_content)
    _clear_progress(prog_file)
    
    success(f"Created user.md at {user_file}")
    print()
    info("user.md defines your personal preferences and default standards.")
    print()
    
    # Always offer to configure project settings
    print()
    print_section("Next Steps")
    if read_yn("Would you like to run 'run project' now?", default=True):
        print()
        return cmd_project([])
    else:
        print()
        info("You can run 'run project' later to configure your project")
        return 0

def cmd_project(args: List[str]):
    """Project command - configure project.md"""
    print_header(f"Deft CLI v{VERSION} - Project Configuration")
    print()
    info("This command creates project.md, which defines YOUR project's specifics:")
    info("  • Tech stack and programming language")
    info("  • Project type (CLI, API, Web App, Library, etc.)")
    info("  • Quality standards (test coverage thresholds)")
    info("  • Workflow commands (task check, task test, etc.)")
    print()
    info("This file tells AI assistants how to build and maintain YOUR project.")
    info("It works alongside the general Deft guidelines in ./deft/")
    print()
    
    defaults = get_default_paths()
    
    # Resume support (issue #8)
    prog_file = _progress_path(resolve_path(defaults['project']))
    progress = {}
    if prog_file.exists():
        saved = _load_progress(prog_file)
        if saved:
            print_section("Previous Session Found")
            for k, v in saved.items():
                if not k.startswith('_'):
                    info(f"  {k}: {v}")
            print()
            if read_yn("Resume where you left off?", default=True):
                progress = saved
            else:
                _clear_progress(prog_file)
    
    # Check if we're in a project directory
    if not Path("./deft").is_dir():
        warn("No ./deft directory found. Run 'run install' first or specify a project directory.")
        if read_yn("Install deft in current directory?"):
            return cmd_install(["."])
        else:
            return 1
    
    if 'output_path' not in progress:
        print_section("Output Location")
    project_path_str = _resume_or_ask(progress, prog_file, 'output_path', 'Output',
                                       read_input, "Where to write PROJECT.md", defaults['project'])
    project_file = resolve_path(project_path_str)
    
    # Gather project information
    dir_default = Path.cwd().name
    project_name = _resume_or_ask(progress, prog_file, 'project_name', 'Project',
                                   read_input, "Project name", dir_default)
    
    type_map = {
        "1": "CLI",
        "2": "TUI",
        "3": "REST API",
        "4": "Web App",
        "5": "Library",
        "6": "Other"
    }
    
    valid_type_nums = set(type_map.keys())
    if 'type_selection' not in progress:
        print()
        info("Select project type (comma-separated if multiple):")
        print("  1. CLI (Command-line interface)")
        print("  2. TUI (Terminal UI)")
        print("  3. REST API")
        print("  4. Web App")
        print("  5. Library")
        print("  6. Other")
        while True:
            type_selection = read_input("Selection")
            if not type_selection.strip():
                print_error("Please enter at least one selection (1-6).")
                continue
            nums = [s.strip() for s in type_selection.split(',')]
            if len(nums) != len(set(nums)):
                print_error("Duplicate selections are not allowed.")
                continue
            if all(n in valid_type_nums for n in nums):
                break
            print_error("Please enter numbers between 1 and 6 (comma-separated).")
        progress['type_selection'] = type_selection
        _save_progress(prog_file, progress)
    else:
        type_selection = progress['type_selection']
        info(f"  [resumed] Type: {type_selection}")
    
    type_nums = [s.strip() for s in type_selection.split(',')]
    project_types = []
    custom_type = ""
    
    for num in type_nums:
        if num == "6":
            custom_type = _resume_or_ask(progress, prog_file, 'custom_type', 'Custom type',
                                          read_input, "Enter custom project type")
            project_types.append(custom_type)
        elif num in type_map:
            project_types.append(type_map[num])
    
    project_types_str = ", ".join(project_types)
    
    # Read USER.md defaults to avoid re-asking questions already answered
    # during bootstrap (fix for #7 — double prompting)
    user_defaults = _read_user_defaults(defaults)
    
    # Language selection — pre-fill from USER.md if available
    available_langs = get_available_languages()
    other_num = len(available_langs) + 1
    valid_lang_nums = set(str(i) for i in range(1, other_num + 1))
    if 'lang_selection' not in progress:
        print()
        if user_defaults.get('languages'):
            user_lang_names = user_defaults['languages']
            user_lang_display = ', '.join(user_lang_names)
            info(f"Languages from USER.md: {user_lang_display}")
            info("Select primary programming language(s) (comma-separated):")
            for i, (stem, display) in enumerate(available_langs, 1):
                print(f"  {i}. {display}")
            print(f"  {other_num}. Other")
            while True:
                lang_selection = read_input(
                    f"Selection, or Enter to keep [{user_lang_display}]", ""
                )
                if not lang_selection.strip():
                    break  # Accept USER.md defaults
                nums = [s.strip() for s in lang_selection.split(',')]
                if len(nums) != len(set(nums)):
                    print_error("Duplicate selections are not allowed.")
                    continue
                if all(n in valid_lang_nums for n in nums):
                    break
                print_error(f"Please enter numbers between 1 and {other_num} (comma-separated).")
        else:
            info("Select primary programming language(s) (comma-separated):")
            for i, (stem, display) in enumerate(available_langs, 1):
                print(f"  {i}. {display}")
            print(f"  {other_num}. Other")
            while True:
                lang_selection = read_input("Selection (e.g., 1,3)")
                if not lang_selection.strip():
                    break  # Skip (falls through to Python default)
                nums = [s.strip() for s in lang_selection.split(',')]
                if len(nums) != len(set(nums)):
                    print_error("Duplicate selections are not allowed.")
                    continue
                if all(n in valid_lang_nums for n in nums):
                    break
                print_error(f"Please enter numbers between 1 and {other_num} (comma-separated).")
        progress['lang_selection'] = lang_selection
        progress['_had_user_lang_defaults'] = bool(user_defaults.get('languages'))
        _save_progress(prog_file, progress)
    else:
        lang_selection = progress['lang_selection']
        info(f"  [resumed] Languages: {lang_selection or '(USER.md defaults)'}")
    
    # Parse language selection
    has_user_lang_defaults = user_defaults.get('languages') or progress.get('_had_user_lang_defaults')
    if not lang_selection.strip() and has_user_lang_defaults:
        # Accept USER.md defaults
        user_lang_names = user_defaults.get('languages', [])
        selected_langs = []
        for lang_name in user_lang_names:
            matched = False
            for stem, display in available_langs:
                if display.lower() == lang_name.lower():
                    selected_langs.append((stem, display))
                    matched = True
                    break
            if not matched:
                selected_langs.append((lang_name.lower(), lang_name))
        if not selected_langs:
            selected_langs = [("python", "Python")]
    else:
        lang_nums = [s.strip() for s in lang_selection.split(',')]
        selected_langs = []
        for num in lang_nums:
            try:
                idx = int(num) - 1
                if 0 <= idx < len(available_langs):
                    selected_langs.append(available_langs[idx])
                elif int(num) == other_num:
                    other_lang = _resume_or_ask(progress, prog_file, 'other_lang',
                                                'Other language', read_input, "Enter language name")
                    if other_lang:
                        selected_langs.append((other_lang.lower(), other_lang))
            except ValueError:
                pass
        if not selected_langs:
            selected_langs = [("python", "Python")]
    
    primary_lang = selected_langs[0][1]
    primary_stem = selected_langs[0][0]
    
    # Coverage — pre-fill from USER.md if available
    if 'coverage' not in progress:
        print()
        user_coverage = user_defaults.get('coverage', '85') if user_defaults else None
        while True:
            if user_coverage:
                proj_coverage = read_input(
                    f"Coverage threshold (from USER.md: {user_coverage}%)", user_coverage
                )
            else:
                proj_coverage = read_input("Coverage threshold (default: 85%)", "85")
            if not proj_coverage.strip():
                proj_coverage = user_coverage or "85"
                break
            try:
                val = int(proj_coverage.strip())
                if 1 <= val <= 100:
                    break
            except ValueError:
                pass
            print_error("Please enter a number between 1 and 100.")
        progress['coverage'] = proj_coverage
        _save_progress(prog_file, progress)
    else:
        proj_coverage = progress['coverage']
        info(f"  [resumed] Coverage: {proj_coverage}")
    
    tech_stack = _resume_or_ask(progress, prog_file, 'tech_stack', 'Tech stack',
                                 read_input, "Tech stack details (e.g., 'Flask + SQLAlchemy' or 'React + Next.js')")
    
    # Strategy — pre-fill from USER.md if available
    available_strats = get_available_strategies()
    max_strat = len(available_strats)
    # Compute recommended marker (same logic as cmd_bootstrap)
    default_strat_num = "1"
    for i, (stem, _) in enumerate(available_strats, 1):
        if stem.lower() == "interview":
            default_strat_num = str(i)
            break
    if 'strat_selection' not in progress:
        if max_strat == 0:
            warn("No strategy files found in strategies/ — defaulting to Interview.")
            strat_selection = "1"
        else:
            print()
            print_section("Development Strategy")
            if user_defaults.get('strategy'):
                user_strat_stem = user_defaults['strategy']
                user_strat_display = user_defaults.get('strategy_display', user_strat_stem.title())
                info(f"Default strategy from USER.md: {user_strat_display}")
                info("Does this project need a different strategy?")
                user_pref_strat_num = next(
                    (str(i) for i, (stem, _) in enumerate(available_strats, 1)
                     if stem.lower() == user_strat_stem.lower()),
                    default_strat_num,
                )
                for i, (stem, display) in enumerate(available_strats, 1):
                    desc = _STRATEGY_DESCRIPTIONS.get(stem, '')
                    marker = " ★ your default" if str(i) == user_pref_strat_num else ""
                    print(f"  {i}. {display}{marker}")
                    if desc:
                        print(f"     {desc}")
                print()
                info("💡 Strategies can be chained — after one completes, you'll be asked if you want to run another.")
                while True:
                    strat_selection = read_input(
                        f"Selection, or Enter to keep [{user_strat_display}]", ""
                    )
                    if not strat_selection.strip():
                        break  # Accept USER.md default
                    try:
                        num = int(strat_selection.strip())
                        if 1 <= num <= max_strat:
                            break
                    except ValueError:
                        pass
                    print_error(f"Please enter a number between 1 and {max_strat}.")
            else:
                info("Select development strategy for this project:")
                for i, (stem, display) in enumerate(available_strats, 1):
                    desc = _STRATEGY_DESCRIPTIONS.get(stem, '')
                    marker = " ★ RECOMMENDED" if str(i) == default_strat_num else ""
                    print(f"  {i}. {display}{marker}")
                    if desc:
                        print(f"     {desc}")
                print()
                info("💡 Strategies can be chained — after one completes, you'll be asked if you want to run another.")
                while True:
                    strat_selection = read_input("Selection", "1")
                    if not strat_selection.strip():
                        strat_selection = "1"
                        break
                    try:
                        num = int(strat_selection.strip())
                        if 1 <= num <= max_strat:
                            break
                    except ValueError:
                        pass
                    print_error(f"Please enter a number between 1 and {max_strat}.")
        progress['strat_selection'] = strat_selection
        progress['_had_user_strat_default'] = bool(user_defaults.get('strategy'))
        _save_progress(prog_file, progress)
    else:
        strat_selection = progress['strat_selection']
        info(f"  [resumed] Strategy: {strat_selection or '(USER.md default)'}")
    
    # Parse strategy selection
    has_user_strat_default = user_defaults.get('strategy') or progress.get('_had_user_strat_default')
    if not strat_selection.strip() and has_user_strat_default:
        user_strat_stem = user_defaults.get('strategy', 'interview')
        user_strat_display = user_defaults.get('strategy_display', user_strat_stem.title())
        selected_strategy = (user_strat_stem, user_strat_display)
    else:
        try:
            strat_idx = int(strat_selection.strip()) - 1
            if 0 <= strat_idx < len(available_strats):
                selected_strategy = available_strats[strat_idx]
            else:
                selected_strategy = available_strats[0] if available_strats else ("interview", "Interview")
        except ValueError:
            selected_strategy = available_strats[0] if available_strats else ("interview", "Interview")
    strategy_stem, strategy_display = selected_strategy
    
    # Branching preference
    if 'branching' not in progress:
        print()
        print_section("Branching Workflow")
        info("Choose your branching strategy:")
        print("  1. Branch-based ★ RECOMMENDED — create a feature branch for every change")
        print("  2. Trunk-based — commit directly to master/main (common for solo projects)")
        while True:
            branch_selection = read_input("Selection", "1")
            if branch_selection.strip() in ("1", "2"):
                break
            print_error("Please enter 1 or 2.")
        progress['branching'] = branch_selection.strip()
        _save_progress(prog_file, progress)
    else:
        branch_selection = progress['branching']
        info(f"  [resumed] Branching: {branch_selection}")
    
    allow_direct_commits = (branch_selection.strip() == "2")
    
    # Generate project.md
    tech_stack_str = f" - {tech_stack}" if tech_stack else ""
    today = datetime.now().strftime("%Y-%m-%d")
    
    # Build language links and display string
    lang_links = " | ".join([f"[../languages/{s}.md](../languages/{s}.md)" for s, _ in selected_langs])
    lang_names = ", ".join([d for _, d in selected_langs])
    
    # Build coverage override line (only if non-default)
    coverage_line = f"\n- **Coverage**: ! ≥{proj_coverage}% (overrides default 85%)" if proj_coverage != "85" else ""
    
    # Build branching section (only emitted for trunk-based)
    branching_section = (
        "\n## Branching\n\nAllow direct commits to master: true\n"
        if allow_direct_commits else ""
    )

    # Build strategy line (omit link when no strategy files exist)
    if available_strats:
        strategy_use_line = f"Use [{strategy_display}](../strategies/{strategy_stem}.md) for this project."
    else:
        strategy_use_line = f"Use {strategy_display} for this project."
    
    project_content = f"""# {project_name} Project Guidelines

Only specify items here that **override or extend** the deft defaults.
See `deft/main.md`, `deft/coding/coding.md`, and language-specific files for base standards.

**⚠️ See also**: [../main.md](../main.md) | {lang_links}

## Project Configuration

**Tech Stack**: {project_types_str} using {lang_names}{tech_stack_str}

## Strategy

{strategy_use_line}

**Process**:

## Overrides
{coverage_line}

## Secrets

<!-- List project-specific secrets needed -->

## Principles

<!-- Non-negotiable rules unique to THIS project (3-5 items) -->

## Project-Specific Rules

(Add your custom rules here)
{branching_section}

---

**Generated by**: run v{VERSION}
**Date**: {today}
"""
    
    _atomic_write(project_file, project_content)
    _clear_progress(prog_file)
    
    success(f"Created project.md at {project_file}")
    print()
    info("project.md defines your project's tech stack, workflow, and quality standards.")
    print()
    
    # Prompt to run spec generation
    print()
    print_section("Next Steps")
    info("Generate a detailed specification via AI interview")
    info("The 'spec' command creates PRD.md with your project requirements,")
    info("which an AI assistant will use to interview you and generate SPECIFICATION.md.")
    print()
    if read_yn("Would you like to run 'run spec' now?", default=True):
        print()
        return cmd_spec([])
    else:
        print()
        info("You can run 'run spec' later to generate your specification.")
        return 0

def _read_user_defaults(defaults: dict) -> dict:
    """Read fallback defaults from USER.md if present.
    
    Parses Primary Languages, Default Strategy, and Coverage from USER.md.
    Returns a dict with keys 'languages', 'strategy', 'coverage' where found.
    Returns empty dict if USER.md does not exist.
    """
    user_path_str = defaults.get('user', '')
    if not user_path_str:
        return {}
    user_file = resolve_path(user_path_str)
    if not user_file.exists():
        return {}
    
    result = {}
    try:
        content = user_file.read_text(encoding='utf-8')
        lines = content.split('\n')
        
        # Parse languages: lines starting with "- " after "**Primary Languages**:"
        in_languages = False
        languages = []
        for line in lines:
            stripped = line.strip()
            if stripped.startswith('**Primary Languages**:'):
                in_languages = True
                continue
            if in_languages:
                if stripped.startswith('- ') and stripped != '- (None specified)':
                    languages.append(stripped[2:].strip())
                elif stripped and not stripped.startswith('- '):
                    in_languages = False
        if languages:
            result['languages'] = languages
        
        # Parse strategy: [Name](../strategies/stem.md)
        for line in lines:
            stripped = line.strip()
            if stripped.startswith('**Default Strategy**:') and 'strategies/' in stripped:
                start = stripped.index('strategies/') + len('strategies/')
                rest = stripped[start:]
                if '.md' in rest:
                    stem = rest[:rest.index('.md')]
                    if stem:
                        result['strategy'] = stem
                        # Also extract display name from [Name](...)
                        try:
                            bracket_start = stripped.index('[') + 1
                            bracket_end = stripped.index(']')
                            result['strategy_display'] = stripped[bracket_start:bracket_end]
                        except ValueError:
                            pass
                break
        
        # Parse coverage: **Coverage**: ! ≥N% 
        for line in lines:
            stripped = line.strip()
            if stripped.startswith('**Coverage**:') and '≥' in stripped and '%' in stripped:
                ge_pos = stripped.index('≥') + 1
                pct_pos = stripped.index('%')
                coverage_val = stripped[ge_pos:pct_pos].strip()
                if coverage_val.isdigit():
                    result['coverage'] = coverage_val
                break
    except Exception:
        pass
    
    return result


def _read_project_process(defaults: dict) -> Optional[str]:
    """Read **Process**: value from PROJECT.md if present.
    
    Returns 'Light', 'Full', or None.
    """
    project_default = resolve_path(defaults['project'])
    project_legacy = _legacy_project_path()
    project_file = project_default if project_default.exists() else project_legacy
    if not project_file.exists():
        return None
    try:
        content = project_file.read_text(encoding='utf-8')
        for line in content.split('\n'):
            stripped = line.strip()
            if stripped.startswith('**Process**:'):
                value = stripped.split(':', 1)[1].strip().rstrip('*').strip()
                if value.lower() in ('light', 'full'):
                    return value.capitalize()
    except Exception:
        pass
    return None

def _read_project_strategy(defaults: dict) -> Optional[str]:
    """Read strategy file stem from PROJECT.md.
    
    Parses the ## Strategy section for a link like:
        Use [Name](path/strategies/stem.md) for this project.
    
    Returns strategy stem (e.g. 'interview', 'discuss') or None.
    """
    project_default = resolve_path(defaults['project'])
    project_legacy = _legacy_project_path()
    project_file = project_default if project_default.exists() else project_legacy
    if not project_file.exists():
        return None
    try:
        content = project_file.read_text(encoding='utf-8')
        for line in content.split('\n'):
            stripped = line.strip()
            if stripped.startswith('Use [') and 'strategies/' in stripped:
                start = stripped.index('strategies/') + len('strategies/')
                rest = stripped[start:]
                if '.md' in rest:
                    stem = rest[:rest.index('.md')]
                    if stem:
                        return stem
    except Exception:
        pass
    return None

def cmd_spec(args: List[str]):
    """Spec command - generate specification via interview"""
    print_header(f"Deft CLI v{VERSION} - Specification Generator")
    print()
    
    defaults = get_default_paths()
    strategy = _read_project_strategy(defaults) or 'interview'
    
    # Resume support (issue #8)
    prog_file = _progress_path(resolve_path(defaults['prd']))
    progress = {}
    if prog_file.exists():
        saved = _load_progress(prog_file)
        if saved:
            print_section("Previous Session Found")
            for k, v in saved.items():
                if not k.startswith('_'):
                    info(f"  {k}: {v}")
            print()
            if read_yn("Resume where you left off?", default=True):
                progress = saved
            else:
                _clear_progress(prog_file)
    
    info("This command creates a specification instruction file for your AI assistant.")
    if strategy != 'interview':
        info(f"Strategy: {strategy} (from PROJECT.md)")
        info(f"Your AI will follow strategies/{strategy}.md, which chains into")
        info("the sizing gate for specification generation:")
    else:
        info("It follows strategies/interview.md with a sizing gate:")
    info("  • Light: → SPECIFICATION (embedded requirements)")
    info("  • Full:  → PRD (approval gate) → SPECIFICATION")
    print()
    info("After creating the file, you'll:")
    info("  1. Give it to your AI assistant")
    info(f"  2. The AI reads strategies/{strategy}.md and follows its workflow")
    info("  3. The AI generates SPECIFICATION.md with full implementation plan")
    info("  4. The AI can then implement the spec")
    print()
    
    # Try to read project name from project.md (check new default, then legacy path)
    project_default = resolve_path(defaults['project'])
    project_legacy = _legacy_project_path()
    project_file = project_default if project_default.exists() else project_legacy
    if 'spec_name' not in progress:
        spec_name = ""
        if project_file.exists():
            try:
                content = project_file.read_text(encoding='utf-8')
                for line in content.split('\n'):
                    if line.startswith('# ') and 'Project Guidelines' in line:
                        spec_name = line.replace('# ', '').replace(' Project Guidelines', '').strip()
                        break
            except (OSError, UnicodeDecodeError):
                pass
        
        if spec_name:
            info(f"Project name from project.md: {spec_name}")
            if not read_yn("Use this name?", default=True):
                spec_name = read_input("Project name")
        else:
            spec_name = read_input("Project name")
        progress['spec_name'] = spec_name
        _save_progress(prog_file, progress)
    else:
        spec_name = progress['spec_name']
        info(f"  [resumed] Project: {spec_name}")
    
    spec_desc = _resume_or_ask(progress, prog_file, 'spec_desc', 'Description',
                                read_input, "Brief description (1-2 sentences)")
    
    if 'features' not in progress:
        print()
        info("Enter project features (one per line, empty line to finish):")
        features = []
        while True:
            feature = read_input("  Feature")
            if not feature:
                break
            features.append(feature)
        progress['features'] = features
        _save_progress(prog_file, progress)
    else:
        features = progress['features']
        info(f"  [resumed] Features: {len(features)} feature(s)")
    
    # Sizing gate
    if 'sizing' not in progress:
        print()
        print_section("Project Complexity")
        
        process_override = _read_project_process(defaults)
        if process_override:
            info(f"PROJECT.md declares **Process**: {process_override} — using that.")
            sizing = process_override
        else:
            recommended = "Light" if len(features) <= 5 else "Full"
            info(f"Based on {len(features)} feature(s), recommended: {recommended}")
            info("  1. Light — Interview → SPECIFICATION (embedded requirements, no PRD)")
            info("  2. Full  — Interview → PRD (approval gate) → SPECIFICATION")
            sizing_choice = read_input("Selection", "1" if recommended == "Light" else "2")
            sizing = "Light" if sizing_choice.strip() == "1" else "Full"
        progress['sizing'] = sizing
        _save_progress(prog_file, progress)
    else:
        sizing = progress['sizing']
        info(f"  [resumed] Path: {sizing}")
    
    # Determine output file
    if sizing == "Light":
        output_default = os.environ.get('DEFT_INTERVIEW_PATH', './INTERVIEW.md')
    else:
        output_default = defaults['prd']  # ./PRD.md
    
    if 'output_path' not in progress:
        print()
        print_section("Output Locations")
    output_path_str = _resume_or_ask(progress, prog_file, 'output_path', 'Output',
                                      read_input, f"Where to write {'INTERVIEW.md' if sizing == 'Light' else 'PRD.md'}", output_default)
    output_file = resolve_path(output_path_str)
    spec_path_str = _resume_or_ask(progress, prog_file, 'spec_path', 'Spec output',
                                    read_input, "Where should SPECIFICATION.md be generated", defaults['specification'])
    spec_file = resolve_path(spec_path_str)
    
    if not progress.get('_write_ready'):
        if output_file.exists() and "--force" not in args:
            warn(f"{output_file} already exists. Use --force to overwrite.")
            return 1
    progress['_write_ready'] = True
    _save_progress(prog_file, progress)
    
    # Build feature list
    feature_list = '\n'.join([f"{i+1}. {f}" for i, f in enumerate(features)])
    
    # Read the make-spec template
    script_dir = get_script_dir()
    template_file = script_dir / "templates" / "make-spec.md"
    
    if not template_file.exists():
        error(f"Template file not found: {template_file}")
        return 1
    
    template_content = template_file.read_text(encoding='utf-8')
    
    # Replace placeholders
    template_content = template_content.replace("[project name]", spec_name)
    template_content = template_content.replace(f"I want to build [project name]", f"I want to build {spec_name}")
    
    # Replace SPECIFICATION.md path in template if user chose a custom location
    template_content = template_content.replace(
        "Generate as SPECIFICATION.md",
        f"Generate as {spec_file}"
    )
    
    # Generate output file
    today = datetime.now().strftime("%Y-%m-%d")
    
    # Build strategy-specific AI instructions
    if strategy in ('interview', 'default'):
        if sizing == "Light":
            strategy_instructions = (
                "! Read `deft/strategies/interview.md` and follow the **Light path**.\n"
                "! Conduct a structured interview, then generate SPECIFICATION.md with\n"
                "embedded Requirements section (FR-1, NFR-1). No separate PRD needed."
            )
        else:
            strategy_instructions = (
                "! Read `deft/strategies/interview.md` and follow the **Full path**.\n"
                "! Conduct a structured interview, generate this PRD with structured\n"
                "requirements (Problem Statement, Goals, User Stories, FR/NFR, Success Metrics),\n"
                "then get user approval before generating SPECIFICATION.md."
            )
    else:
        path_note = "embedded requirements, no separate PRD" if sizing == "Light" else "PRD approval gate before SPECIFICATION"
        strategy_instructions = (
            f"! Read `deft/strategies/{strategy}.md` and follow its complete workflow.\n"
            f"! When the strategy chains into the sizing gate, use the **{sizing} path** ({path_note})."
        )
    
    if sizing == "Light":
        output_content = f"""# Interview: {spec_name}

**Generated**: {today}
**Status**: Ready for AI Interview
**Strategy**: {strategy}
**Path**: Light (Interview → SPECIFICATION)
**Specification Output**: {spec_file}

## Initial Input

**Project Description**: {spec_desc}

**I want to build {spec_name} that has the following features:**
{feature_list}
---

## Instructions for AI

{strategy_instructions}

{template_content}
"""
    else:
        output_content = f"""# Product Requirements Document: {spec_name}

**Generated**: {today}
**Status**: Ready for AI Interview
**Strategy**: {strategy}
**Path**: Full (Interview → PRD → SPECIFICATION)
**Specification Output**: {spec_file}

## Initial Input

**Project Description**: {spec_desc}

**I want to build {spec_name} that has the following features:**
{feature_list}
---

## Instructions for AI

{strategy_instructions}

{template_content}
"""
    
    _atomic_write(output_file, output_content)
    _clear_progress(prog_file)
    
    output_name = 'INTERVIEW.md' if sizing == 'Light' else 'PRD.md'
    success(f"Created {output_name} at {output_file}")
    info(f"Path: {sizing}")
    info("Next steps:")
    info(f"  1. Open your AI assistant (Claude, Warp.dev, etc.)")
    info(f"  2. Ask your AI to read and run {output_file}")
    info(f"  3. The AI will read strategies/{strategy}.md and follow its workflow")
    info(f"  4. AI will generate the final specification at {spec_file}")
    info(f"  5. You can review the specification if you want")
    info(f"  6. Ask your AI to implement {spec_file}")
    return 0

def cmd_install(args: List[str]):
    """Install command - install deft framework in a project"""
    target_dir = Path(args[0]) if args else Path(".")
    
    print_header(f"Deft CLI v{VERSION} - Installation")
    print()
    info("This command installs the Deft framework in your project directory.")
    info("It will create:")
    info("  • ./deft/        - Framework files (guidelines, templates, references)")
    info("  • ./secrets/        - Directory for API keys and credentials (.gitignored)")
    info("  • ./docs/           - Project documentation")
    info("  • Taskfile.yml      - Task automation config (if not present)")
    info("  • .gitignore        - Ensures secrets aren't committed (if not present)")
    print()
    info(f"Target directory: {target_dir.absolute()}")
    print()
    
    if not target_dir.exists():
        error(f"Directory does not exist: {target_dir}")
        return 1
    
    # Change to target directory
    original_dir = Path.cwd()
    os.chdir(target_dir)
    
    try:
        deft_dir = Path("./deft")
        
        # Check if deft already exists
        already_installed = deft_dir.exists()
        if already_installed:
            warn("Deft already installed in this directory.")
            if not read_yn("Reinstall?"):
                # Still offer to run project even if not reinstalling
                print()
                print_section("Next Steps")
                if read_yn("Would you like to run 'run project' now?"):
                    print()
                    return cmd_project([])
                else:
                    return 0
        
        # Copy deft framework
        info("Copying deft framework...")
        script_dir = get_script_dir()
        
        if deft_dir.exists():
            shutil.rmtree(deft_dir)
        
        shutil.copytree(script_dir, deft_dir)
        
        # Create project-specific files
        Path("secrets").mkdir(exist_ok=True)
        Path("docs").mkdir(exist_ok=True)
        Path("secrets/.gitkeep").touch()
        
        # Create .gitignore for secrets
        gitignore = Path(".gitignore")
        if not gitignore.exists():
            gitignore.write_text("secrets/*\n!secrets/.gitkeep\n!secrets/*.example\n", encoding='utf-8')
        
        # Create basic Taskfile if it doesn't exist
        taskfile = Path("Taskfile.yml")
        if not taskfile.exists():
            taskfile_content = """version: '3'

tasks:
  default:
    desc: List all tasks
    cmds:
      - task --list
    silent: true

  check:
    desc: Run all pre-commit checks
    cmds:
      - echo "Add your check commands here"
      - task fmt
      - task lint
      - task test

  fmt:
    desc: Format code
    cmds:
      - echo "Add your format command here"

  lint:
    desc: Lint code
    cmds:
      - echo "Add your lint command here"

  test:
    desc: Run tests
    cmds:
      - echo "Add your test command here"

  test:coverage:
    desc: Run tests with coverage
    cmds:
      - echo "Add your coverage command here"
"""
            taskfile.write_text(taskfile_content, encoding='utf-8')
            success("Created Taskfile.yml")
        
        success("Deft installed successfully!")
        print()
        
        # Prompt to run project configuration
        print_section("Next Steps")
        if read_yn("Would you like to run 'run project' now?"):
            print()
            return cmd_project([])
        else:
            print()
            info("You can run these commands later:")
            info("  ./deft/run project     # Configure this project")
            info("  ./deft/run bootstrap   # Set up user preferences")
            return 0
    
    finally:
        os.chdir(original_dir)

def cmd_validate(args: List[str]):
    """Validate command - check deft configuration"""
    print_header(f"Deft CLI v{VERSION} - Validate")
    print()
    info("Validating Deft configuration...")
    print()
    
    script_dir = get_script_dir()
    errors = 0
    
    # Check for required files
    required_files = [
        "main.md",
        "core/user.md",
        "coding/coding.md",
        "REFERENCES.md"
    ]
    
    for file in required_files:
        filepath = script_dir / file
        if filepath.exists():
            success(f"Found: {file}")
        else:
            error(f"Missing: {file}")
            errors += 1
    
    # Check for at least one language file
    lang_dir = script_dir / "languages"
    if lang_dir.exists() and list(lang_dir.glob("*.md")):
        success("Language files present")
    else:
        error("No language files found in languages/")
        errors += 1
    
    # Check for broken links (simple check)
    info("Checking for common broken links...")
    # Note: Python implementation could be more sophisticated
    
    print()
    if errors == 0:
        success("Validation passed! Deft configuration is valid.")
        return 0
    else:
        error(f"Validation failed with {errors} error(s).")
        return 1

def cmd_doctor(args: List[str]):
    """Doctor command - check system dependencies"""
    print_header(f"Deft CLI v{VERSION} - Doctor")
    print()
    info("Checking system dependencies...")
    print()
    
    warnings = 0
    
    # Check for required tools
    def check_command(cmd: str, name: str, required: bool = False):
        nonlocal warnings
        if shutil.which(cmd):
            success(f"{name} is installed")
        else:
            if required:
                error(f"{name} not found - required")
            else:
                warn(f"{name} not found - install from https://taskfile.dev" if cmd == "task" 
                     else f"{name} not found")
                warnings += 1
    
    check_command("task", "task (Taskfile)")
    check_command("git", "git", required=True)
    check_command("python3", "python3")
    check_command("go", "go")
    check_command("node", "node")
    
    # Check directory structure
    print()
    info("Checking Deft structure...")
    
    script_dir = get_script_dir()
    expected_dirs = ["core", "languages", "interfaces", "tools", "swarm", "templates", "meta"]
    
    for dir_name in expected_dirs:
        dir_path = script_dir / dir_name
        if dir_path.is_dir():
            success(f"Directory: {dir_name}/")
        else:
            warn(f"Missing directory: {dir_name}/")
            warnings += 1
    
    print()
    if warnings == 0:
        success("System check passed!")
    else:
        warn(f"System check completed with {warnings} warning(s).")
    
    return 0

def cmd_update(args: List[str]):
    """Update command - update deft framework"""
    print_header(f"Deft CLI v{VERSION} - Update")
    print()
    info("Deft update functionality not yet implemented")
    warn("Manual update: Replace deft directory with latest version from repository")
    return 0

def cmd_reset(args: List[str]):
    """Reset command - reset configuration files to default/empty state"""
    print_header(f"Deft CLI v{VERSION} - Reset")
    print()
    info("This command resets deft configuration files to their default state.")
    info("You can choose which files to reset:")
    print()
    defaults = get_default_paths()
    user_default = resolve_path(defaults['user'])
    project_default = resolve_path(defaults['project'])
    prd_default = resolve_path(defaults['prd'])
    spec_default = resolve_path(defaults['specification'])
    
    info(f"  • USER.md           - Your personal preferences ({defaults['user']})")
    info(f"  • PROJECT.md        - Project configuration ({defaults['project']})")
    info(f"  • PRD.md            - Product requirements document ({defaults['prd']})")
    info(f"  • SPECIFICATION.md  - Generated specification ({defaults['specification']})")
    print()
    
    # Check what exists (new default locations and legacy locations)
    user_file = user_default if user_default.exists() else _legacy_user_path()
    project_file = project_default if project_default.exists() else _legacy_project_path()
    prd_file = prd_default
    spec_file = spec_default
    
    files_to_reset = []
    
    # Check each file and ask if user wants to reset it
    if "--all" in args:
        # Reset all without asking
        if user_file.exists():
            files_to_reset.append(("user.md", user_file, True))
        if project_file.exists():
            files_to_reset.append(("project.md", project_file, False))
        if prd_file.exists():
            files_to_reset.append(("PRD.md", prd_file, False))
        if spec_file.exists():
            files_to_reset.append(("SPECIFICATION.md", spec_file, False))
    else:
        # Ask for each file
        if user_file.exists():
            if read_yn("Reset user.md to default template?"):
                files_to_reset.append(("user.md", user_file, True))
        
        if project_file.exists():
            if read_yn("Delete project.md?"):
                files_to_reset.append(("project.md", project_file, False))
        
        if prd_file.exists():
            if read_yn("Delete PRD.md?"):
                files_to_reset.append(("PRD.md", prd_file, False))
        
        if spec_file.exists():
            if read_yn("Delete SPECIFICATION.md?"):
                files_to_reset.append(("SPECIFICATION.md", spec_file, False))
    
    if not files_to_reset:
        print()
        info("No files to reset.")
        return 0
    
    # Confirm
    print()
    warn("The following files will be reset/deleted:")
    for name, _, _ in files_to_reset:
        warn(f"  • {name}")
    print()
    
    if "--all" not in args and not read_yn("Are you sure you want to continue?"):
        info("Reset cancelled.")
        return 0
    
    # Perform reset
    print()
    for name, filepath, reset_to_default in files_to_reset:
        if reset_to_default:
            # Reset user.md to default template
            default_content = """# User Preferences

Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.

## Personal (always wins)

Settings in this section have HIGHEST precedence — override all other deft rules,
including PROJECT.md.

**Name**: Address the user as: **(Your Name)**

**Custom Rules**:
No custom rules defined yet.

## Defaults (fallback)

Settings in this section are fallback defaults. PROJECT.md overrides these
for project-scoped settings (strategy, coverage, languages).

**Primary Languages**:
- (Add your languages here)

---

**Note**: You can edit this file anytime to update your preferences.
**See**: [../main.md](../main.md) for framework defaults.
"""
            filepath.write_text(default_content, encoding='utf-8')
            success(f"Reset {name} to default template")
        else:
            # Delete file
            filepath.unlink()
            success(f"Deleted {name}")
    
    print()
    success("Reset complete!")
    info("Run 'run bootstrap' or 'run project' to reconfigure.")
    return 0

# ============================================================================
# TUI MODE - Textual-based wizard interface
# ============================================================================

if HAS_TEXTUAL:
    class MenuScreen(Screen):
        """Main menu screen with command list."""
        
        BINDINGS = [("q", "quit", "Quit"), ("escape", "quit", "Quit")]
        
        def compose(self) -> ComposeResult:
            yield Header()
            yield Container(
                OptionList(
                    Option("Bootstrap ... Set up user preferences", id="bootstrap"),
                    Option("Project ..... Create project configuration", id="project"),
                    Option("Spec ........ Generate specification", id="spec"),
                    Option("Install ..... Install deft in directory", id="install"),
                    Option("", id="sep1", disabled=True),
                    Option("Reset ....... Reset configuration files", id="reset"),
                    Option("Validate .... Check configuration", id="validate"),
                    Option("Doctor ...... Check system dependencies", id="doctor"),
                    Option("", id="sep2", disabled=True),
                    Option("README ...... View framework documentation", id="readme"),
                    Option("CHANGELOG ... View version history", id="changelog"),
                    Option("Main.md ..... View main framework guide", id="mainmd"),
                    Option("Help ........ Show help", id="help"),
                    Option("", id="sep3", disabled=True),
                    Option("Exit ........ Quit wizard", id="exit"),
                    id="menu"
                )
            )
            yield Footer()
        
        def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
            option_id = event.option.id
            if option_id == "exit":
                self.app.exit()
            elif option_id == "help":
                self.app.push_screen("help")
            elif option_id == "readme":
                self.app.push_screen("readme")
            elif option_id == "changelog":
                self.app.push_screen("changelog")
            elif option_id == "mainmd":
                self.app.push_screen("mainmd")
            elif option_id == "bootstrap":
                self.app.push_screen("bootstrap")
            elif option_id == "project":
                self.app.push_screen("project")
            elif option_id == "spec":
                self.app.push_screen("spec")
            elif option_id == "install":
                self.app.push_screen("install")
            elif option_id == "reset":
                self.app.push_screen("reset")
            elif option_id == "validate":
                self.app.push_screen("validate")
            elif option_id == "doctor":
                self.app.push_screen("doctor")
        
        def action_quit(self) -> None:
            self.app.exit()
    
    class BootstrapScreen(Screen):
        """Bootstrap configuration form."""
        
        BINDINGS = [("escape", "cancel", "Cancel")]
        
        CSS = """
        BootstrapScreen Horizontal {
            height: auto;
        }
        BootstrapScreen #status {
            height: auto;
        }
        """
        
        def __init__(self):
            super().__init__()
            self.available_langs = get_available_languages()
            self.available_strats = get_available_strategies()
        
        def compose(self) -> ComposeResult:
            yield Header()
            with ScrollableContainer():
                yield Label("Bootstrap - User Preferences Setup")
                yield Label("\n[dim]This section sets up your personal preferences that will apply across all projects. These settings define how the AI addresses you, your preferred languages, coverage standards, and development strategies. You only need to complete this once, though you can update it anytime.[/dim]\n")
                yield Label("Your name (how AI should address you):")
                yield Input(id="name", placeholder="Your name")
                yield Label("\nDefault coverage threshold (%):")
                yield Input(id="coverage", placeholder="85", value="85")
                yield Label("\nPrimary languages:")
                for stem, display in self.available_langs:
                    yield Checkbox(display, id=_lang_widget_id(stem))
                yield Label("Other language (optional):")
                yield Input(id="other_lang", placeholder="Enter language name")
                yield Label("\nDevelopment strategy:")
                strategy_options = [(display, stem) for stem, display in self.available_strats]
                yield Select(strategy_options, id="strategy", allow_blank=False, value=strategy_options[0][1] if strategy_options else "interview")
                yield Label("\nCustom rules (optional):")
                yield Input(id="rules", placeholder="Enter one rule — open USER.md to add more")
                yield Label("\nExperimental Rules:")
                yield Checkbox("Use meta/SOUL.md (Strategic context)", id="use_soul", value=True)
                yield Checkbox("Use meta/morals.md (Ethical AI)", id="use_morals", value=True)
                yield Checkbox("Use meta/code-field.md (Advanced arch)", id="use_code_field", value=True)
                yield Label("\nOutput location:")
                yield Input(id="output_path", placeholder="~/.config/deft/USER.md", value=get_default_paths()['user'])
            with Horizontal():
                yield Button("Submit", variant="primary", id="submit")
                yield Button("Cancel", id="cancel")
            yield Label("", id="status")
            yield Footer()
        
        def on_button_pressed(self, event: Button.Pressed) -> None:
            if event.button.id == "cancel":
                self.app.pop_screen()
            elif event.button.id == "submit":
                self.handle_submit()
        
        def action_cancel(self) -> None:
            self.app.pop_screen()
        
        def handle_submit(self) -> None:
            name = self.query_one("#name", Input).value.strip()
            coverage = self.query_one("#coverage", Input).value.strip() or "85"
            custom_rules_raw = self.query_one("#rules", Input).value.strip()
            custom_rules = f"- {custom_rules_raw}" if custom_rules_raw else ""
            
            # Get language selections from checkboxes
            languages = []
            for stem, display in self.available_langs:
                try:
                    if self.query_one(f"#{_lang_widget_id(stem)}", Checkbox).value:
                        languages.append(f"- {display}")
                except Exception:
                    pass
            other_lang = self.query_one("#other_lang", Input).value.strip()
            if other_lang:
                languages.append(f"- {other_lang}")
            languages_str = '\n'.join(languages) if languages else "- (None specified)"
            
            # Get strategy selection
            strategy_stem = str(self.query_one("#strategy", Select).value or "interview")
            strategy_display = dict(self.available_strats).get(strategy_stem, strategy_stem.title())
            
            # Get experimental rules preferences from checkboxes
            use_soul = self.query_one("#use_soul", Checkbox).value
            use_morals = self.query_one("#use_morals", Checkbox).value
            use_code_field = self.query_one("#use_code_field", Checkbox).value
            
            if not name:
                self.query_one("#status", Label).update("[red]Error: Name is required[/red]")
                return
            
            # Build experimental rules section
            experimental_rules = []
            if use_soul:
                experimental_rules.append("- ! Use meta/SOUL.md for strategic context and purpose-driven guidance")
            if use_morals:
                experimental_rules.append("- ! Use meta/morals.md for ethical AI development principles")
            if use_code_field:
                experimental_rules.append("- ~ Use meta/code-field.md for advanced architecture patterns")
            
            experimental_section = ""
            if experimental_rules:
                experimental_section = "\n## Experimental Rules\n\n" + "\n".join(experimental_rules)
            
            # Resolve output path
            output_path_str = self.query_one("#output_path", Input).value.strip()
            user_file = resolve_path(output_path_str or get_default_paths()['user'])
            # Build coverage override line (only if non-default)
            coverage_line = f"\n**Coverage**: ! ≥{coverage}% test coverage" if coverage != "85" else ""
            
            user_content = f"""# User Preferences

Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.

## Personal (always wins)

Settings in this section have HIGHEST precedence — override all other deft rules,
including PROJECT.md.

**Name**: Address the user as: **{name}**

**Custom Rules**:
{custom_rules if custom_rules else "No custom rules defined yet."}

## Defaults (fallback)

Settings in this section are fallback defaults. PROJECT.md overrides these
for project-scoped settings (strategy, coverage, languages).

**Primary Languages**:
{languages_str}

**Default Strategy**: [{strategy_display}](../strategies/{strategy_stem}.md)
{coverage_line}
{experimental_section}

---

**Note**: You can edit this file anytime to update your preferences.
**See**: [../main.md](../main.md) for framework defaults.
"""
            
            user_file.parent.mkdir(parents=True, exist_ok=True)
            user_file.write_text(user_content, encoding='utf-8')
            
            self.app.push_screen(SuccessScreen(f"Created user.md at {user_file}", offer_next="project"))
    
    class ProjectScreen(Screen):
        """Project configuration form."""
        
        BINDINGS = [("escape", "cancel", "Cancel")]
        
        CSS = """
        ProjectScreen Horizontal {
            height: auto;
        }
        ProjectScreen #status {
            height: auto;
        }
        """
        
        def __init__(self):
            super().__init__()
            self.available_langs = get_available_languages()
            self.available_strats = get_available_strategies()
        
        def compose(self) -> ComposeResult:
            yield Header()
            with ScrollableContainer():
                yield Label("Project Configuration")
                yield Label("\n[dim]This section configures the specific settings for your current project. These settings override your bootstrap preferences and define project-specific details like tech stack, type, and quality standards. Complete this for each new project you work on.[/dim]\n")
                yield Label("Project name:")
                yield Input(id="name", placeholder="My Project")
                yield Label("\nProject type (select all that apply):")
                yield Checkbox("CLI", id="type_cli")
                yield Checkbox("TUI", id="type_tui")
                yield Checkbox("REST API", id="type_api")
                yield Checkbox("Web App", id="type_webapp")
                yield Checkbox("Library", id="type_library")
                yield Checkbox("Other", id="type_other")
                yield Label("\nPrimary language(s):")
                for stem, display in self.available_langs:
                    yield Checkbox(display, id=_lang_widget_id(stem))
                yield Label("Other language (optional):")
                yield Input(id="other_lang", placeholder="Enter language name")
                yield Label("\nDevelopment strategy:")
                strategy_options = [(display, stem) for stem, display in self.available_strats]
                yield Select(strategy_options, id="strategy", allow_blank=False, value=strategy_options[0][1] if strategy_options else "default")
                yield Label("\nCoverage threshold (%):")
                yield Input(id="coverage", placeholder="85", value="85")
                yield Label("Tech stack details (optional):")
                yield Input(id="tech_stack", placeholder="Flask + SQLAlchemy")
                yield Label("\nOutput location:")
                yield Input(id="output_path", placeholder="./PROJECT.md", value=get_default_paths()['project'])
            with Horizontal():
                yield Button("Submit", variant="primary", id="submit")
                yield Button("Cancel", id="cancel")
            yield Label("", id="status")
            yield Footer()
        
        def on_button_pressed(self, event: Button.Pressed) -> None:
            if event.button.id == "cancel":
                self.app.pop_screen()
            elif event.button.id == "submit":
                self.handle_submit()
        
        def action_cancel(self) -> None:
            self.app.pop_screen()
        
        def handle_submit(self) -> None:
            project_name = self.query_one("#name", Input).value.strip()
            coverage = self.query_one("#coverage", Input).value.strip() or "85"
            tech_stack = self.query_one("#tech_stack", Input).value.strip()
            
            if not project_name:
                self.query_one("#status", Label).update("[red]Error: Project name is required[/red]")
                return
            
            # Get project types from checkboxes
            project_types = []
            if self.query_one("#type_cli", Checkbox).value:
                project_types.append("CLI")
            if self.query_one("#type_tui", Checkbox).value:
                project_types.append("TUI")
            if self.query_one("#type_api", Checkbox).value:
                project_types.append("REST API")
            if self.query_one("#type_webapp", Checkbox).value:
                project_types.append("Web App")
            if self.query_one("#type_library", Checkbox).value:
                project_types.append("Library")
            if self.query_one("#type_other", Checkbox).value:
                project_types.append("Other")
            project_types_str = ", ".join(project_types) if project_types else "Application"
            
            # Get selected languages from checkboxes
            selected_langs = []
            for stem, display in self.available_langs:
                try:
                    if self.query_one(f"#{_lang_widget_id(stem)}", Checkbox).value:
                        selected_langs.append((stem, display))
                except Exception:
                    pass
            other_lang = self.query_one("#other_lang", Input).value.strip()
            if other_lang:
                selected_langs.append((other_lang.lower(), other_lang))
            
            if not selected_langs:
                selected_langs = [("python", "Python")]
            primary_lang = selected_langs[0][1]
            primary_stem = selected_langs[0][0]
            
            # Get strategy selection
            strategy_stem = str(self.query_one("#strategy", Select).value or "default")
            strategy_display = dict(self.available_strats).get(strategy_stem, strategy_stem.title())
            
            tech_stack_str = f" - {tech_stack}" if tech_stack else ""
            today = datetime.now().strftime("%Y-%m-%d")
            
            # Build language links and display string
            lang_links = " | ".join([f"[../languages/{s}.md](../languages/{s}.md)" for s, _ in selected_langs])
            lang_names = ", ".join([d for _, d in selected_langs])
            
            # Resolve output path
            output_path_str = self.query_one("#output_path", Input).value.strip()
            project_file = resolve_path(output_path_str or get_default_paths()['project'])
            # Build coverage override line (only if non-default)
            coverage_line = f"\n- **Coverage**: ! ≥{coverage}% (overrides default 85%)" if coverage != "85" else ""
            
            project_content = f"""# {project_name} Project Guidelines

Only specify items here that **override or extend** the deft defaults.
See `deft/main.md`, `deft/coding/coding.md`, and language-specific files for base standards.

**⚠️ See also**: [../main.md](../main.md) | {lang_links}

## Project Configuration

**Tech Stack**: {project_types_str} using {lang_names}{tech_stack_str}

## Strategy

Use [{strategy_display}](../strategies/{strategy_stem}.md) for this project.

**Process**:

## Overrides
{coverage_line}

## Secrets

<!-- List project-specific secrets needed -->

## Principles

<!-- Non-negotiable rules unique to THIS project (3-5 items) -->

## Project-Specific Rules

(Add your custom rules here)

---

**Generated by**: run v{VERSION}
**Date**: {today}
"""
            
            project_file.parent.mkdir(parents=True, exist_ok=True)
            project_file.write_text(project_content, encoding='utf-8')
            
            self.app.push_screen(SuccessScreen(f"Created project.md at {project_file}", offer_next="spec"))
    
    class SuccessScreen(Screen):
        """Success message with optional next step."""
        
        def __init__(self, message: str, offer_next: Optional[str] = None):
            super().__init__()
            self.message = message
            self.offer_next = offer_next
        
        def compose(self) -> ComposeResult:
            yield Header()
            with Container():
                yield Label(f"[green]✓[/green] {self.message}")
                if self.offer_next:
                    yield Label(f"\nWould you like to run '{self.offer_next}' next?")
                    with Horizontal():
                        yield Button("Yes", variant="primary", id="yes")
                        yield Button("No, return to menu", id="no")
                else:
                    yield Button("Return to Menu", variant="primary", id="no")
            yield Footer()
        
        def on_button_pressed(self, event: Button.Pressed) -> None:
            if event.button.id == "yes" and self.offer_next:
                self.app.pop_screen()  # Pop success screen
                self.app.push_screen(self.offer_next)
            else:
                self.app.pop_screen()  # Return to previous screen
    
    class SpecScreen(Screen):
        """Spec generation form."""
        
        BINDINGS = [("escape", "cancel", "Cancel")]
        
        def __init__(self):
            super().__init__()
            self.features = []
        
        def compose(self) -> ComposeResult:
            yield Header()
            with ScrollableContainer():
                yield Label("Specification Generator - PRD.md")
                yield Label("\n[dim]This section creates a Product Requirements Document (PRD) for your project. The PRD captures your project's core purpose, description, and key features, which serves as input for AI-assisted development. This helps the AI understand what you're building and guides implementation.[/dim]\n")
                yield Label("Project name:")
                yield Input(id="name", placeholder="My Project")
                yield Label("Brief description (1-2 sentences):")
                yield Input(id="description", placeholder="What does this project do?")
                yield Label("Features (one per line):")
                yield Input(id="feature_input", placeholder="Enter a feature and press Enter")
                yield Label("", id="feature_list")
                with Horizontal():
                    yield Button("Add Feature", id="add_feature")
                    yield Button("Clear Features", id="clear_features")
                yield Label("\nOutput locations:")
                yield Label("PRD output path:")
                yield Input(id="prd_path", placeholder="./PRD.md", value=get_default_paths()['prd'])
                yield Label("SPECIFICATION output path:")
                yield Input(id="spec_path", placeholder="./SPECIFICATION.md", value=get_default_paths()['specification'])
                with Horizontal():
                    yield Button("Submit", variant="primary", id="submit")
                    yield Button("Cancel", id="cancel")
                yield Label("", id="status")
            yield Footer()
        
        def on_button_pressed(self, event: Button.Pressed) -> None:
            if event.button.id == "cancel":
                self.app.pop_screen()
            elif event.button.id == "add_feature":
                self.add_feature()
            elif event.button.id == "clear_features":
                self.features = []
                self.update_feature_list()
            elif event.button.id == "submit":
                self.handle_submit()
        
        def on_input_submitted(self, event: Input.Submitted) -> None:
            if event.input.id == "feature_input":
                self.add_feature()
        
        def add_feature(self) -> None:
            feature_input = self.query_one("#feature_input", Input)
            feature = feature_input.value.strip()
            if feature:
                self.features.append(feature)
                feature_input.value = ""
                self.update_feature_list()
        
        def update_feature_list(self) -> None:
            feature_list = self.query_one("#feature_list", Label)
            if self.features:
                text = "\n".join([f"{i+1}. {f}" for i, f in enumerate(self.features)])
                feature_list.update(f"Features ({len(self.features)}): \n{text}")
            else:
                feature_list.update("No features added yet")
        
        def action_cancel(self) -> None:
            self.app.pop_screen()
        
        def handle_submit(self) -> None:
            project_name = self.query_one("#name", Input).value.strip()
            description = self.query_one("#description", Input).value.strip()
            
            if not project_name:
                self.query_one("#status", Label).update("[red]Error: Project name is required[/red]")
                return
            
            if not description:
                self.query_one("#status", Label).update("[red]Error: Description is required[/red]")
                return
            
            if not self.features:
                self.query_one("#status", Label).update("[red]Error: Add at least one feature[/red]")
                return
            
            # Generate PRD
            feature_list = '\n'.join([f"{i+1}. {f}" for i, f in enumerate(self.features)])
            script_dir = get_script_dir()
            template_file = script_dir / "templates" / "make-spec.md"
            
            if template_file.exists():
                template_content = template_file.read_text(encoding='utf-8')
                template_content = template_content.replace("[project name]", project_name)
                template_content = template_content.replace(f"I want to build [project name]", f"I want to build {project_name}")
            else:
                template_content = "(Template not found)"
            
            # Resolve output paths
            prd_path_str = self.query_one("#prd_path", Input).value.strip()
            prd_file = resolve_path(prd_path_str or get_default_paths()['prd'])
            spec_path_str = self.query_one("#spec_path", Input).value.strip()
            spec_file = resolve_path(spec_path_str or get_default_paths()['specification'])
            
            # Replace SPECIFICATION.md path in template if user chose a custom location
            template_content = template_content.replace(
                "Generate as SPECIFICATION.md",
                f"Generate as {spec_file}"
            )
            
            today = datetime.now().strftime("%Y-%m-%d")
            prd_content = f"""# Product Requirements Document: {project_name}

**Generated**: {today}
**Status**: Ready for AI Interview
**Specification Output**: {spec_file}

## Initial Input

**Project Description**: {description}

**I want to build {project_name} that has the following features:**
{feature_list}
---

{template_content}
"""
            
            prd_file.parent.mkdir(parents=True, exist_ok=True)
            prd_file.write_text(prd_content, encoding='utf-8')
            self.app.push_screen(SuccessScreen(f"Created PRD.md at {prd_file}"))
    
    class InstallScreen(Screen):
        """Install deft in directory."""
        
        BINDINGS = [("escape", "cancel", "Cancel")]
        
        def compose(self) -> ComposeResult:
            yield Header()
            with ScrollableContainer():
                yield Label("Install Deft Framework")
                yield Label("\n[dim]This section installs the deft framework files into your project directory. It creates the necessary directory structure, configuration files, and task automation setup. Use this when setting up deft in a new or existing project.[/dim]\n")
                yield Label("Target directory (default: current):")
                yield Input(id="directory", placeholder=".", value=".")
                yield Label("\nThis will create:")
                yield Label("  • ./deft/ - Framework files")
                yield Label("  • ./secrets/ - Credentials directory")
                yield Label("  • ./docs/ - Documentation")
                yield Label("  • Taskfile.yml - Task automation")
                yield Label("  • .gitignore - Git configuration")
                with Horizontal():
                    yield Button("Install", variant="primary", id="install")
                    yield Button("Cancel", id="cancel")
                yield Label("", id="status")
            yield Footer()
        
        def on_button_pressed(self, event: Button.Pressed) -> None:
            if event.button.id == "cancel":
                self.app.pop_screen()
            elif event.button.id == "install":
                self.handle_install()
        
        def action_cancel(self) -> None:
            self.app.pop_screen()
        
        def handle_install(self) -> None:
            target_dir = Path(self.query_one("#directory", Input).value.strip() or ".")
            
            if not target_dir.exists():
                self.query_one("#status", Label).update(f"[red]Error: Directory does not exist: {target_dir}[/red]")
                return
            
            original_dir = Path.cwd()
            try:
                os.chdir(target_dir)
                deft_dir = Path("./deft")
                
                if deft_dir.exists():
                    self.query_one("#status", Label).update("[yellow]Deft already installed. Reinstalling...[/yellow]")
                    shutil.rmtree(deft_dir)
                
                script_dir = get_script_dir()
                shutil.copytree(script_dir, deft_dir)
                
                Path("secrets").mkdir(exist_ok=True)
                Path("docs").mkdir(exist_ok=True)
                Path("secrets/.gitkeep").touch()
                
                gitignore = Path(".gitignore")
                if not gitignore.exists():
                    gitignore.write_text("secrets/*\n!secrets/.gitkeep\n!secrets/*.example\n", encoding='utf-8')
                
                self.app.push_screen(SuccessScreen(f"Installed deft in {target_dir.absolute()}", offer_next="project"))
            except Exception as e:
                self.query_one("#status", Label).update(f"[red]Error: {e}[/red]")
            finally:
                os.chdir(original_dir)
    
    class ResetScreen(Screen):
        """Reset configuration files."""
        
        BINDINGS = [("escape", "cancel", "Cancel")]
        
        def compose(self) -> ComposeResult:
            yield Header()
            with ScrollableContainer():
                yield Label("Reset Configuration Files")
                yield Label("\n[dim]This section allows you to reset or delete configuration files to start fresh. Use this when you want to reconfigure your settings or remove generated files. Warning: This action cannot be undone, so make sure you have backups if needed.[/dim]\n")
                yield Label("\nSelect files to reset/delete:")
                
                # Check which files exist (new defaults and legacy locations)
                defaults = get_default_paths()
                user_default = resolve_path(defaults['user'])
                user_file = user_default if user_default.exists() else _legacy_user_path()
                project_default = resolve_path(defaults['project'])
                project_file = project_default if project_default.exists() else _legacy_project_path()
                prd_file = resolve_path(defaults['prd'])
                spec_file = resolve_path(defaults['specification'])
                
                if user_file.exists():
                    yield Label(f"[cyan]✓[/cyan] USER.md at {user_file} (will reset to default)", id="user_exists")
                else:
                    yield Label(f"[dim]USER.md (not found at {defaults['user']})[/dim]", id="user_missing")
                
                if project_file.exists():
                    yield Label(f"[cyan]✓[/cyan] PROJECT.md at {project_file} (will delete)", id="project_exists")
                else:
                    yield Label(f"[dim]PROJECT.md (not found at {defaults['project']})[/dim]", id="project_missing")
                
                if prd_file.exists():
                    yield Label(f"[cyan]✓[/cyan] PRD.md at {prd_file} (will delete)", id="prd_exists")
                else:
                    yield Label(f"[dim]PRD.md (not found at {defaults['prd']})[/dim]", id="prd_missing")
                
                if spec_file.exists():
                    yield Label(f"[cyan]✓[/cyan] SPECIFICATION.md at {spec_file} (will delete)", id="spec_exists")
                else:
                    yield Label(f"[dim]SPECIFICATION.md (not found at {defaults['specification']})[/dim]", id="spec_missing")
                
                yield Label("\n[yellow]Warning: This action cannot be undone![/yellow]")
                
                with Horizontal():
                    yield Button("Reset All", variant="error", id="reset")
                    yield Button("Cancel", id="cancel")
                yield Label("", id="status")
            yield Footer()
        
        def on_button_pressed(self, event: Button.Pressed) -> None:
            if event.button.id == "cancel":
                self.app.pop_screen()
            elif event.button.id == "reset":
                self.handle_reset()
        
        def action_cancel(self) -> None:
            self.app.pop_screen()
        
        def handle_reset(self) -> None:
            defaults = get_default_paths()
            user_default = resolve_path(defaults['user'])
            user_file = user_default if user_default.exists() else _legacy_user_path()
            project_default = resolve_path(defaults['project'])
            project_file = project_default if project_default.exists() else _legacy_project_path()
            prd_file = resolve_path(defaults['prd'])
            spec_file = resolve_path(defaults['specification'])
            
            reset_count = 0
            
            if user_file.exists():
                default_content = """# User Preferences

Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.

**Rule Precedence**: This file has HIGHEST precedence - overrides all other deft rules.

## Name

Address the user as: **(Your Name)**

## Default Standards

**Coverage**: ! ≥85% test coverage for all projects (unless project.md specifies otherwise)

**Primary Languages**:
- (Add your languages here)

## Custom Rules

No custom rules defined yet.

## Workflow Preferences

- ~ Use task-based automation (Taskfile)
- ! Always run `task check` before committing
- ~ Follow Conventional Commits

## AI Behavior

- ~ Be direct and concise
- ~ Proactively suggest improvements
- ! Explain tradeoffs for major decisions

---

**Note**: You can edit this file anytime to update your preferences.
**See**: [../main.md](../main.md) for framework overview.
"""
                user_file.write_text(default_content, encoding='utf-8')
                reset_count += 1
            
            for file in [project_file, prd_file, spec_file]:
                if file.exists():
                    file.unlink()
                    reset_count += 1
            
            if reset_count > 0:
                self.app.push_screen(SuccessScreen(f"Reset {reset_count} file(s)"))
            else:
                self.query_one("#status", Label).update("[yellow]No files to reset[/yellow]")
    
    class ValidateScreen(Screen):
        """Validate deft configuration."""
        
        BINDINGS = [("escape", "back", "Back")]
        
        def compose(self) -> ComposeResult:
            yield Header()
            with ScrollableContainer():
                yield Label("Deft Configuration Validation")
                yield Label("\n[dim]This validation checks that all required deft framework files are present and properly configured. It verifies core files, language definitions, and configuration structure to ensure the framework will function correctly.[/dim]\n")
                yield Static("", id="results")
                yield Button("Back to Menu", variant="primary", id="back")
            yield Footer()
        
        def on_mount(self) -> None:
            self.run_validation()
        
        def run_validation(self) -> None:
            results = ["Running validation...\n"]
            script_dir = get_script_dir()
            errors = 0
            
            # Check required files
            required_files = [
                "main.md",
                "core/user.md",
                "coding/coding.md",
                "REFERENCES.md"
            ]
            
            for file in required_files:
                filepath = script_dir / file
                if filepath.exists():
                    results.append(f"[green]✓[/green] Found: {file}")
                else:
                    results.append(f"[red]✗[/red] Missing: {file}")
                    errors += 1
            
            # Check language files
            lang_dir = script_dir / "languages"
            if lang_dir.exists() and list(lang_dir.glob("*.md")):
                results.append(f"[green]✓[/green] Language files present")
            else:
                results.append(f"[red]✗[/red] No language files found")
                errors += 1
            
            results.append("")
            if errors == 0:
                results.append("[green]✓ Validation passed![/green]")
            else:
                results.append(f"[red]✗ Validation failed with {errors} error(s)[/red]")
            
            self.query_one("#results", Static).update("\n".join(results))
        
        def on_button_pressed(self, event: Button.Pressed) -> None:
            self.app.pop_screen()
        
        def action_back(self) -> None:
            self.app.pop_screen()
    
    class DoctorScreen(Screen):
        """Check system dependencies."""
        
        BINDINGS = [("escape", "back", "Back")]
        
        def compose(self) -> ComposeResult:
            yield Header()
            with ScrollableContainer():
                yield Label("Deft Doctor - System Check")
                yield Label("\n[dim]This diagnostic checks your system for the tools and dependencies deft needs to function properly. It verifies that required commands are available and that the framework's directory structure is intact.[/dim]\n")
                yield Static("", id="results")
                yield Button("Back to Menu", variant="primary", id="back")
            yield Footer()
        
        def on_mount(self) -> None:
            self.run_checks()
        
        def run_checks(self) -> None:
            results = ["Checking system...\n"]
            warnings = 0
            
            # Check commands
            commands = [
                ("task", "Task (Taskfile)", False),
                ("git", "Git", True),
                ("python3", "Python 3", False),
                ("go", "Go", False),
                ("node", "Node.js", False),
            ]
            
            for cmd, name, required in commands:
                if shutil.which(cmd):
                    results.append(f"[green]✓[/green] {name} is installed")
                else:
                    if required:
                        results.append(f"[red]✗[/red] {name} not found - required")
                    else:
                        results.append(f"[yellow]⚠[/yellow] {name} not found")
                        warnings += 1
            
            # Check directory structure
            results.append("\nChecking Deft structure...")
            script_dir = get_script_dir()
            expected_dirs = ["core", "languages", "interfaces", "tools", "swarm", "templates", "meta"]
            
            for dir_name in expected_dirs:
                dir_path = script_dir / dir_name
                if dir_path.is_dir():
                    results.append(f"[green]✓[/green] Directory: {dir_name}/")
                else:
                    results.append(f"[yellow]⚠[/yellow] Missing: {dir_name}/")
                    warnings += 1
            
            results.append("")
            if warnings == 0:
                results.append("[green]✓ System check passed![/green]")
            else:
                results.append(f"[yellow]⚠ System check completed with {warnings} warning(s)[/yellow]")
            
            self.query_one("#results", Static).update("\n".join(results))
        
        def on_button_pressed(self, event: Button.Pressed) -> None:
            self.app.pop_screen()
        
        def action_back(self) -> None:
            self.app.pop_screen()
    
    class ReadmeScreen(Screen):
        """View README.md with markdown rendering."""
        
        BINDINGS = [("escape", "back", "Back"), ("q", "quit", "Menu")]
        
        def __init__(self):
            super().__init__()
            self.history = []  # Track navigation history
        
        def compose(self) -> ComposeResult:
            yield Header()
            readme_file = get_script_dir() / "README.md"
            if readme_file.exists():
                yield MarkdownViewer()
            else:
                yield Static("[red]README.md not found[/red]")
            yield Footer()
        
        def on_mount(self) -> None:
            readme_file = get_script_dir() / "README.md"
            if readme_file.exists():
                try:
                    viewer = self.query_one(MarkdownViewer)
                    viewer.document.update(readme_file.read_text(encoding='utf-8'))
                    self.history = [readme_file]  # Initialize with starting doc
                except:
                    pass
        
        def on_markdown_link_clicked(self, event) -> None:
            """Handle markdown link clicks - navigate to other markdown files or open external URLs."""
            href = event.href
            
            # Check if this is a real external URL (contains ://) but exclude file:// and others
            # Also check it's not a .md file that got URL-ified (e.g., SKILL.md -> http://SKILL.md)
            is_external_url = (href and 
                             ('://' in href) and 
                             href.startswith(('http://', 'https://')) and
                             not href.split('://', 1)[1].endswith('.md'))
            
            # Let real external URLs open in browser
            if is_external_url:
                return  # Don't prevent default - let it open
            
            # Prevent default for all other links (including .md files that got URL-ified)
            event.prevent_default()
            
            # Handle internal markdown links
            if href and not href.startswith('mailto:'):
                # Extract just the filename if it got converted to a URL
                if '://' in href and href.split('://', 1)[1].endswith('.md'):
                    href = href.split('://', 1)[1].lstrip('/')
                
                if href.endswith('.md'):
                    # Load the linked markdown file
                    script_dir = get_script_dir()
                    target_file = script_dir / href
                    if target_file.exists():
                        try:
                            viewer = self.query_one(MarkdownViewer)
                            viewer.document.update(target_file.read_text(encoding='utf-8'))
                            self.history.append(target_file)  # Add to history
                        except:
                            pass
        
        def action_back(self) -> None:
            """Go back to previous document or menu if no history."""
            if len(self.history) > 1:
                # Remove current document and go back to previous
                self.history.pop()
                prev_file = self.history[-1]
                try:
                    viewer = self.query_one(MarkdownViewer)
                    viewer.document.update(prev_file.read_text(encoding='utf-8'))
                except:
                    pass
            else:
                # No history, return to menu
                self.app.pop_screen()
        
        def action_quit(self) -> None:
            """Return to menu."""
            self.app.pop_screen()
    
    class ChangelogScreen(Screen):
        """View CHANGELOG.md with markdown rendering."""
        
        BINDINGS = [("escape", "back", "Back"), ("q", "quit", "Menu")]
        
        def __init__(self):
            super().__init__()
            self.history = []  # Track navigation history
        
        def compose(self) -> ComposeResult:
            yield Header()
            changelog_file = get_script_dir() / "CHANGELOG.md"
            if changelog_file.exists():
                yield MarkdownViewer()
            else:
                yield Static("[red]CHANGELOG.md not found[/red]")
            yield Footer()
        
        def on_mount(self) -> None:
            changelog_file = get_script_dir() / "CHANGELOG.md"
            if changelog_file.exists():
                try:
                    viewer = self.query_one(MarkdownViewer)
                    viewer.document.update(changelog_file.read_text(encoding='utf-8'))
                    self.history = [changelog_file]  # Initialize with starting doc
                except:
                    pass
        
        def on_markdown_link_clicked(self, event) -> None:
            """Handle markdown link clicks - navigate to other markdown files or open external URLs."""
            href = event.href
            
            # Check if this is a real external URL (contains ://) but exclude file:// and others
            # Also check it's not a .md file that got URL-ified (e.g., SKILL.md -> http://SKILL.md)
            is_external_url = (href and 
                             ('://' in href) and 
                             href.startswith(('http://', 'https://')) and
                             not href.split('://', 1)[1].endswith('.md'))
            
            # Let real external URLs open in browser
            if is_external_url:
                return  # Don't prevent default - let it open
            
            # Prevent default for all other links (including .md files that got URL-ified)
            event.prevent_default()
            
            # Handle internal markdown links
            if href and not href.startswith('mailto:'):
                # Extract just the filename if it got converted to a URL
                if '://' in href and href.split('://', 1)[1].endswith('.md'):
                    href = href.split('://', 1)[1].lstrip('/')
                
                if href.endswith('.md'):
                    # Load the linked markdown file
                    script_dir = get_script_dir()
                    target_file = script_dir / href
                    if target_file.exists():
                        try:
                            viewer = self.query_one(MarkdownViewer)
                            viewer.document.update(target_file.read_text(encoding='utf-8'))
                            self.history.append(target_file)  # Add to history
                        except:
                            pass
        
        def action_back(self) -> None:
            """Go back to previous document or menu if no history."""
            if len(self.history) > 1:
                # Remove current document and go back to previous
                self.history.pop()
                prev_file = self.history[-1]
                try:
                    viewer = self.query_one(MarkdownViewer)
                    viewer.document.update(prev_file.read_text(encoding='utf-8'))
                except:
                    pass
            else:
                # No history, return to menu
                self.app.pop_screen()
        
        def action_quit(self) -> None:
            """Return to menu."""
            self.app.pop_screen()
    
    class MainMdScreen(Screen):
        """View main.md with markdown rendering."""
        
        BINDINGS = [("escape", "back", "Back"), ("q", "quit", "Menu")]
        
        def __init__(self):
            super().__init__()
            self.history = []  # Track navigation history
        
        def compose(self) -> ComposeResult:
            yield Header()
            mainmd_file = get_script_dir() / "main.md"
            if mainmd_file.exists():
                yield MarkdownViewer()
            else:
                yield Static("[red]main.md not found[/red]")
            yield Footer()
        
        def on_mount(self) -> None:
            mainmd_file = get_script_dir() / "main.md"
            if mainmd_file.exists():
                try:
                    viewer = self.query_one(MarkdownViewer)
                    viewer.document.update(mainmd_file.read_text(encoding='utf-8'))
                    self.history = [mainmd_file]  # Initialize with starting doc
                except:
                    pass
        
        def on_markdown_link_clicked(self, event) -> None:
            """Handle markdown link clicks - navigate to other markdown files or open external URLs."""
            href = event.href
            
            # Check if this is a real external URL (contains ://) but exclude file:// and others
            # Also check it's not a .md file that got URL-ified (e.g., SKILL.md -> http://SKILL.md)
            is_external_url = (href and 
                             ('://' in href) and 
                             href.startswith(('http://', 'https://')) and
                             not href.split('://', 1)[1].endswith('.md'))
            
            # Let real external URLs open in browser
            if is_external_url:
                return  # Don't prevent default - let it open
            
            # Prevent default for all other links (including .md files that got URL-ified)
            event.prevent_default()
            
            # Handle internal markdown links
            if href and not href.startswith('mailto:'):
                # Extract just the filename if it got converted to a URL
                if '://' in href and href.split('://', 1)[1].endswith('.md'):
                    href = href.split('://', 1)[1].lstrip('/')
                
                if href.endswith('.md'):
                    # Load the linked markdown file
                    script_dir = get_script_dir()
                    target_file = script_dir / href
                    if target_file.exists():
                        try:
                            viewer = self.query_one(MarkdownViewer)
                            viewer.document.update(target_file.read_text(encoding='utf-8'))
                            self.history.append(target_file)  # Add to history
                        except:
                            pass
        
        def action_back(self) -> None:
            """Go back to previous document or menu if no history."""
            if len(self.history) > 1:
                # Remove current document and go back to previous
                self.history.pop()
                prev_file = self.history[-1]
                try:
                    viewer = self.query_one(MarkdownViewer)
                    viewer.document.update(prev_file.read_text(encoding='utf-8'))
                except:
                    pass
            else:
                # No history, return to menu
                self.app.pop_screen()
        
        def action_quit(self) -> None:
            """Return to menu."""
            self.app.pop_screen()
    
    class HelpScreen(Screen):
        """Help screen showing usage information."""
        
        BINDINGS = [("escape", "back", "Back")]
        
        def compose(self) -> ComposeResult:
            yield Header()
            help_text = f"""Deft CLI v{VERSION}

Usage: run <command> [options]
       run tui          # Launch this wizard
       run wizard       # Launch this wizard

Commands:
  bootstrap       Set up your user preferences (user.md)
  project         Create/update project configuration (project.md)
  spec            Generate project specification (interactive interview)
  install         Install deft framework in a project directory
  reset           Reset configuration files to default state
  validate        Validate deft configuration files
  update          Update deft framework to latest version
  doctor          Check system dependencies and configuration
  help            Show this help message

Examples:
  run bootstrap              # First-time setup
  run project                # Configure current project
  run spec                   # Generate SPECIFICATION.md
  run install ~/my-project   # Install deft in a project

For more information: https://github.com/deftai/directive
"""
            with ScrollableContainer():
                yield Static(help_text)
                yield Button("Back", variant="primary", id="back")
            yield Footer()
        
        def on_button_pressed(self, event: Button.Pressed) -> None:
            self.app.pop_screen()
        
        def action_back(self) -> None:
            self.app.pop_screen()
    
    class DeftWizardApp(App):
        """Main TUI application."""
        
        TITLE = f"Deft v{VERSION}"
        
        CSS = """
        MenuScreen {
            align: center middle;
        }
        
        MenuScreen Container {
            align: center middle;
            width: 60;
            height: auto;
        }
        
        #menu {
            width: 100%;
            height: auto;
            border: solid $accent;
        }
        
        Label {
            margin: 1 0;
        }
        
        Input {
            margin: 0 0 1 0;
        }
        
        Button {
            margin: 1;
        }
        
        #status {
            color: $warning;
        }
        """
        
        SCREENS = {
            "menu": MenuScreen,
            "bootstrap": BootstrapScreen,
            "project": ProjectScreen,
            "spec": SpecScreen,
            "install": InstallScreen,
            "reset": ResetScreen,
            "validate": ValidateScreen,
            "doctor": DoctorScreen,
            "readme": ReadmeScreen,
            "changelog": ChangelogScreen,
            "mainmd": MainMdScreen,
            "help": HelpScreen,
        }
        
        def on_mount(self) -> None:
            self.push_screen("menu")

def check_prompt_toolkit():
    """Check if prompt_toolkit is available and offer to help install it"""
    if not HAS_PROMPT_TOOLKIT:
        print()
        info("run works better with prompt_toolkit (arrow keys, history, tab completion)")
        try:
            response = input("Would you like installation instructions? (y/N) ").strip().lower()
            if response in ('y', 'yes'):
                print()
                success("To install prompt_toolkit:")
                print()
                # Get the Python executable path
                python_exe = sys.executable
                
                # Try to determine if this is an externally-managed environment
                # by checking for the EXTERNALLY-MANAGED file (PEP 668)
                stdlib_path = Path(sys.base_prefix) / "lib" / f"python{sys.version_info.major}.{sys.version_info.minor}"
                is_externally_managed = (stdlib_path / "EXTERNALLY-MANAGED").exists()
                
                if is_externally_managed:
                    print(f"  {python_exe} -m pip install --break-system-packages prompt_toolkit")
                    print()
                    warn("Your Python is externally-managed (PEP 668) by your package manager.")
                    info("The --break-system-packages flag allows installing Python packages directly.")
                    info("Alternative: Use a virtual environment or pipx for isolated installations.")
                    info("More info: https://peps.python.org/pep-0668/")
                else:
                    print(f"  {python_exe} -m pip install prompt_toolkit")
                print()
                info("After installing, re-run your command:")
                print(f"  {' '.join(sys.argv)}")
                print()
                return True  # Exit after showing instructions
        except (EOFError, KeyboardInterrupt):
            print()
    return False  # Continue normally

def main():
    """Main command dispatcher"""
    # Handle help flags
    if len(sys.argv) >= 2 and sys.argv[1] in ['-h', '--help', '-help']:
        usage()
        return 0
    
    # Launch TUI if no args or explicit tui/wizard command
    if len(sys.argv) < 2 or (len(sys.argv) >= 2 and sys.argv[1] in ['tui', 'wizard']):
        if HAS_TEXTUAL:
            app = DeftWizardApp()
            app.run()
            return 0
        elif len(sys.argv) >= 2 and sys.argv[1] in ['tui', 'wizard']:
            # User explicitly requested TUI but it's not available
            error("TUI mode requires textual library")
            print()
            python_exe = sys.executable
            stdlib_path = Path(sys.base_prefix) / "lib" / f"python{sys.version_info.major}.{sys.version_info.minor}"
            is_externally_managed = (stdlib_path / "EXTERNALLY-MANAGED").exists()
            
            info("To install textual:")
            if is_externally_managed:
                print(f"  {python_exe} -m pip install --break-system-packages textual")
            else:
                print(f"  {python_exe} -m pip install textual")
            print()
            info("Or use CLI commands directly: run bootstrap, run project, etc.")
            return 1
        else:
            # No args and no textual - show usage
            usage()
            return 0
    
    # Check for prompt_toolkit and offer help (only for interactive commands)
    command = sys.argv[1]
    interactive_commands = ['bootstrap', 'project', 'spec', 'install']
    if command in interactive_commands and check_prompt_toolkit():
        return 0  # Exit after showing install instructions
    
    args = sys.argv[2:]
    
    commands = {
        'bootstrap': cmd_bootstrap,
        'project': cmd_project,
        'spec': cmd_spec,
        'install': cmd_install,
        'reset': cmd_reset,
        'validate': cmd_validate,
        'doctor': cmd_doctor,
        'update': cmd_update,
        'help': lambda _: usage(),
        '--help': lambda _: usage(),
        'version': lambda _: print(f"Deft CLI v{VERSION}"),
        '--version': lambda _: print(f"Deft CLI v{VERSION}"),
        '-v': lambda _: print(f"Deft CLI v{VERSION}"),
    }
    
    if command in commands:
        try:
            return commands[command](args)
        except KeyboardInterrupt:
            print()
            warn("Operation cancelled \u2014 re-run the command to resume where you left off.")
            return 130
        except Exception as e:
            error(f"Error: {e}")
            return 1
    else:
        error(f"Unknown command: {command}")
        print()
        usage()
        return 1

if __name__ == "__main__":
    sys.exit(main() or 0)