crackerjack 0.28.0__py3-none-any.whl → 0.30.3__py3-none-any.whl

crackerjack/crackerjack.py

@@ -5,21 +5,21 @@ import re
 import subprocess
 import time
 import typing as t
-from concurrent.futures import ThreadPoolExecutor, as_completed
 from contextlib import suppress
 from dataclasses import dataclass
-from functools import lru_cache
 from pathlib import Path
 from subprocess import CompletedProcess
 from subprocess import run as execute
 from tomllib import loads
 
-import aiofiles
 from pydantic import BaseModel
 from rich.console import Console
 from tomli_w import dumps
 
-from .errors import ErrorCode, ExecutionError
+from .code_cleaner import CodeCleaner
+from .dynamic_config import (
+    generate_config_for_mode,
+)
 
 
 @dataclass
@@ -274,7 +274,7 @@ python -m crackerjack --resume-from {self.progress_file.name}
 
 """
 
-        all_files = set()
+        all_files: set[str] = set()
         for task in self.tasks.values():
             if task.files_changed:
                 all_files.update(task.files_changed)
@@ -351,7 +351,7 @@ python -m crackerjack --resume-from {self.progress_file.name}
 
     @classmethod
     def find_recent_progress_files(cls, directory: Path = Path.cwd()) -> list[Path]:
-        progress_files = []
+        progress_files: list[Path] = []
         for file_path in directory.glob("SESSION-PROGRESS-*.md"):
             try:
                 if file_path.is_file():
@@ -496,9 +496,6 @@ python -m crackerjack --resume-from {self.progress_file.name}
 
 config_files = (
     ".gitignore",
-    ".pre-commit-config.yaml",
-    ".pre-commit-config-ai.yaml",
-    ".pre-commit-config-fast.yaml",
     ".libcst.codemod.yaml",
 )
 
@@ -525,6 +522,7 @@ class OptionsProtocol(t.Protocol):
     update_precommit: bool
     update_docs: bool
     force_update_docs: bool
+    compress_docs: bool
     clean: bool
     test: bool
     benchmark: bool
@@ -543,1178 +541,492 @@ class OptionsProtocol(t.Protocol):
     track_progress: bool = False
     resume_from: str | None = None
     progress_file: str | None = None
+    experimental_hooks: bool = False
+    enable_pyrefly: bool = False
+    enable_ty: bool = False
+    no_git_tags: bool = False
+    skip_version_check: bool = False
 
 
-class CodeCleaner(BaseModel, arbitrary_types_allowed=True):
+class ConfigManager(BaseModel, arbitrary_types_allowed=True):
+    our_path: Path
+    pkg_path: Path
+    pkg_name: str
     console: Console
+    our_toml_path: Path | None = None
+    pkg_toml_path: Path | None = None
+    python_version: str = default_python_version
+    dry_run: bool = False
 
-    def _analyze_workload_characteristics(self, files: list[Path]) -> dict[str, t.Any]:
-        if not files:
-            return {
-                "total_files": 0,
-                "total_size": 0,
-                "avg_file_size": 0,
-                "complexity": "low",
-            }
-        total_size = 0
-        large_files = 0
-        for file_path in files:
-            try:
-                size = file_path.stat().st_size
-                total_size += size
-                if size > 50_000:
-                    large_files += 1
-            except (OSError, PermissionError):
-                continue
-        avg_file_size = total_size / len(files) if files else 0
-        large_file_ratio = large_files / len(files) if files else 0
-        if len(files) > 100 or avg_file_size > 20_000 or large_file_ratio > 0.3:
-            complexity = "high"
-        elif len(files) > 50 or avg_file_size > 10_000 or large_file_ratio > 0.1:
-            complexity = "medium"
+    def swap_package_name(self, value: list[str] | str) -> list[str] | str:
+        if isinstance(value, list):
+            value.remove("crackerjack")
+            value.append(self.pkg_name)
         else:
-            complexity = "low"
-
-        return {
-            "total_files": len(files),
-            "total_size": total_size,
-            "avg_file_size": avg_file_size,
-            "large_files": large_files,
-            "large_file_ratio": large_file_ratio,
-            "complexity": complexity,
-        }
+            value = value.replace("crackerjack", self.pkg_name)
+        return value
 
-    def _calculate_optimal_workers(self, workload: dict[str, t.Any]) -> int:
-        import os
+    def update_pyproject_configs(self) -> None:
+        self._setup_toml_paths()
+        if self._is_crackerjack_project():
+            self._handle_crackerjack_project()
+            return
+        our_toml_config = self._load_our_toml()
+        pkg_toml_config = self._load_pkg_toml()
+        self._ensure_required_sections(pkg_toml_config)
+        self._update_tool_settings(our_toml_config, pkg_toml_config)
+        self._update_python_version(our_toml_config, pkg_toml_config)
+        self._save_pkg_toml(pkg_toml_config)
 
-        cpu_count = os.cpu_count() or 4
-        if workload["complexity"] == "high":
-            max_workers = min(cpu_count // 2, 3)
-        elif workload["complexity"] == "medium":
-            max_workers = min(cpu_count, 6)
-        else:
-            max_workers = min(cpu_count + 2, 8)
+    def _setup_toml_paths(self) -> None:
+        toml_file = "pyproject.toml"
+        self.our_toml_path = self.our_path / toml_file
+        self.pkg_toml_path = self.pkg_path / toml_file
 
-        return min(max_workers, workload["total_files"])
+    def _is_crackerjack_project(self) -> bool:
+        return self.pkg_path.stem == "crackerjack"
 
-    def clean_files(self, pkg_dir: Path | None) -> None:
-        if pkg_dir is None:
-            return
-        python_files = [
-            file_path
-            for file_path in pkg_dir.rglob("*.py")
-            if not str(file_path.parent).startswith("__")
-        ]
-        if not python_files:
-            return
-        workload = self._analyze_workload_characteristics(python_files)
-        max_workers = self._calculate_optimal_workers(workload)
-        if len(python_files) > 10:
-            self.console.print(
-                f"[dim]Cleaning {workload['total_files']} files "
-                f"({workload['complexity']} complexity) with {max_workers} workers[/dim]"
-            )
-        with ThreadPoolExecutor(max_workers=max_workers) as executor:
-            future_to_file = {
-                executor.submit(self.clean_file, file_path): file_path
-                for file_path in python_files
-            }
-            for future in as_completed(future_to_file):
-                file_path = future_to_file[future]
-                try:
-                    future.result()
-                except Exception as e:
-                    self.console.print(
-                        f"[bold bright_red]❌ Error cleaning {file_path}: {e}[/bold bright_red]"
-                    )
-        self._cleanup_cache_directories(pkg_dir)
-
-    def _cleanup_cache_directories(self, pkg_dir: Path) -> None:
-        with suppress(PermissionError, OSError):
-            pycache_dir = pkg_dir / "__pycache__"
-            if pycache_dir.exists():
-                for cache_file in pycache_dir.iterdir():
-                    with suppress(PermissionError, OSError):
-                        cache_file.unlink()
-                pycache_dir.rmdir()
-            parent_pycache = pkg_dir.parent / "__pycache__"
-            if parent_pycache.exists():
-                for cache_file in parent_pycache.iterdir():
-                    with suppress(PermissionError, OSError):
-                        cache_file.unlink()
-                parent_pycache.rmdir()
-
-    def clean_file(self, file_path: Path) -> None:
-        from crackerjack.errors import ExecutionError, handle_error
+    def _handle_crackerjack_project(self) -> None:
+        if self.our_toml_path and self.pkg_toml_path:
+            self.our_toml_path.write_text(self.pkg_toml_path.read_text())
 
-        try:
-            code = file_path.read_text(encoding="utf-8")
-            original_code = code
-            cleaning_failed = False
-            try:
-                code = self.remove_line_comments_streaming(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to remove line comments from {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            try:
-                code = self.remove_docstrings_streaming(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to remove docstrings from {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            try:
-                code = self.remove_extra_whitespace_streaming(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to remove extra whitespace from {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            try:
-                code = self.reformat_code(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to reformat {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            file_path.write_text(code, encoding="utf-8")
-            if cleaning_failed:
-                self.console.print(
-                    f"[bold yellow]⚡ Partially cleaned:[/bold yellow] [dim bright_white]{file_path}[/dim bright_white]"
-                )
-            else:
-                self.console.print(
-                    f"[bold green]✨ Cleaned:[/bold green] [dim bright_white]{file_path}[/dim bright_white]"
-                )
-        except PermissionError as e:
-            self.console.print(
-                f"[red]Failed to clean: {file_path} (Permission denied)[/red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message=f"Permission denied while cleaning {file_path}",
-                    error_code=ErrorCode.PERMISSION_ERROR,
-                    details=str(e),
-                    recovery=f"Check file permissions for {file_path} and ensure you have write access",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
-        except OSError as e:
-            self.console.print(
-                f"[red]Failed to clean: {file_path} (File system error)[/red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message=f"File system error while cleaning {file_path}",
-                    error_code=ErrorCode.FILE_WRITE_ERROR,
-                    details=str(e),
-                    recovery=f"Check that {file_path} exists and is not being used by another process",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
-        except UnicodeDecodeError as e:
-            self.console.print(
-                f"[red]Failed to clean: {file_path} (Encoding error)[/red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message=f"Encoding error while reading {file_path}",
-                    error_code=ErrorCode.FILE_READ_ERROR,
-                    details=str(e),
-                    recovery=f"File {file_path} contains non-UTF-8 characters. Please check the file encoding.",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
-        except Exception as e:
-            self.console.print(
-                f"[red]Failed to clean: {file_path} (Unexpected error)[/red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message=f"Unexpected error while cleaning {file_path}",
-                    error_code=ErrorCode.UNEXPECTED_ERROR,
-                    details=str(e),
-                    recovery="This is an unexpected error. Please report this issue with the file content if possible.",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
+    def _load_our_toml(self) -> dict[str, t.Any]:
+        if self.our_toml_path:
+            return loads(self.our_toml_path.read_text())
+        return {}
 
-    def _initialize_docstring_state(self) -> dict[str, t.Any]:
-        return {
-            "in_docstring": False,
-            "delimiter": None,
-            "waiting": False,
-            "function_indent": 0,
-            "removed_docstring": False,
-            "in_multiline_def": False,
-        }
+    def _load_pkg_toml(self) -> dict[str, t.Any]:
+        if self.pkg_toml_path:
+            return loads(self.pkg_toml_path.read_text())
+        return {}
 
-    def _handle_function_definition(
-        self, line: str, stripped: str, state: dict[str, t.Any]
-    ) -> bool:
-        if self._is_function_or_class_definition(stripped):
-            state["waiting"] = True
-            state["function_indent"] = len(line) - len(line.lstrip())
-            state["removed_docstring"] = False
-            state["in_multiline_def"] = not stripped.endswith(":")
-            return True
-        return False
+    def _ensure_required_sections(self, pkg_toml_config: dict[str, t.Any]) -> None:
+        pkg_toml_config.setdefault("tool", {})
+        pkg_toml_config.setdefault("project", {})
 
-    def _handle_multiline_definition(
-        self, line: str, stripped: str, state: dict[str, t.Any]
-    ) -> bool:
-        if state["in_multiline_def"]:
-            if stripped.endswith(":"):
-                state["in_multiline_def"] = False
-            return True
-        return False
+    def _update_tool_settings(
+        self, our_toml_config: dict[str, t.Any], pkg_toml_config: dict[str, t.Any]
+    ) -> None:
+        for tool, settings in our_toml_config.get("tool", {}).items():
+            if tool not in pkg_toml_config["tool"]:
+                pkg_toml_config["tool"][tool] = {}
+            pkg_tool_config = pkg_toml_config["tool"][tool]
+            self._merge_tool_config(settings, pkg_tool_config, tool)
 
-    def _handle_waiting_docstring(
-        self, lines: list[str], i: int, stripped: str, state: dict[str, t.Any]
-    ) -> tuple[bool, str | None]:
-        if state["waiting"] and stripped:
-            if self._handle_docstring_start(stripped, state):
-                pass_line = None
-                if not state["in_docstring"]:
-                    function_indent: int = state["function_indent"]
-                    if self._needs_pass_statement(lines, i + 1, function_indent):
-                        pass_line = " " * (function_indent + 4) + "pass"
-                state["removed_docstring"] = True
-                return True, pass_line
-            else:
-                state["waiting"] = False
-        return False, None
-
-    def _handle_docstring_content(
-        self, lines: list[str], i: int, stripped: str, state: dict[str, t.Any]
-    ) -> tuple[bool, str | None]:
-        if state["in_docstring"]:
-            if self._handle_docstring_end(stripped, state):
-                pass_line = None
-                function_indent: int = state["function_indent"]
-                if self._needs_pass_statement(lines, i + 1, function_indent):
-                    pass_line = " " * (function_indent + 4) + "pass"
-                state["removed_docstring"] = False
-                return True, pass_line
+    def _merge_tool_config(
+        self, our_config: dict[str, t.Any], pkg_config: dict[str, t.Any], tool: str
+    ) -> None:
+        for setting, value in our_config.items():
+            if isinstance(value, dict):
+                self._merge_nested_config(
+                    setting, t.cast(dict[str, t.Any], value), pkg_config
+                )
             else:
-                return True, None
-        return False, None
-
-    def _process_line(
-        self, lines: list[str], i: int, line: str, state: dict[str, t.Any]
-    ) -> tuple[bool, str | None]:
-        stripped = line.strip()
-        if self._handle_function_definition(line, stripped, state):
-            return True, line
-        if self._handle_multiline_definition(line, stripped, state):
-            return True, line
-        handled, pass_line = self._handle_waiting_docstring(lines, i, stripped, state)
-        if handled:
-            return True, pass_line
-        handled, pass_line = self._handle_docstring_content(lines, i, stripped, state)
-        if handled:
-            return True, pass_line
-        if state["removed_docstring"] and stripped:
-            state["removed_docstring"] = False
-        return False, line
-
-    def remove_docstrings(self, code: str) -> str:
-        lines = code.split("\n")
-        cleaned_lines: list[str] = []
-        docstring_state = self._initialize_docstring_state()
-        for i, line in enumerate(lines):
-            handled, result_line = self._process_line(lines, i, line, docstring_state)
-            if handled:
-                if result_line is not None:
-                    cleaned_lines.append(result_line)
+                self._merge_direct_config(setting, value, pkg_config)
+
+    def _merge_nested_config(
+        self, setting: str, value: dict[str, t.Any], pkg_config: dict[str, t.Any]
+    ) -> None:
+        if setting not in pkg_config:
+            pkg_config[setting] = {}
+        elif not isinstance(pkg_config[setting], dict):
+            pkg_config[setting] = {}
+        self._merge_tool_config(value, pkg_config[setting], "")
+        for k, v in value.items():
+            self._merge_nested_value(k, v, pkg_config[setting])
+
+    def _merge_nested_value(
+        self, key: str, value: t.Any, nested_config: dict[str, t.Any]
+    ) -> None:
+        if isinstance(value, str | list) and "crackerjack" in str(value):
+            nested_config[key] = self.swap_package_name(t.cast(str | list[str], value))
+        elif self._is_mergeable_list(key, value):
+            existing = nested_config.get(key, [])
+            if isinstance(existing, list) and isinstance(value, list):
+                nested_config[key] = list(
+                    set(t.cast(list[str], existing) + t.cast(list[str], value))
+                )
             else:
-                cleaned_lines.append(line)
-        return "\n".join(cleaned_lines)
+                nested_config[key] = value
+        elif key not in nested_config:
+            nested_config[key] = value
 
-    def _is_function_or_class_definition(self, stripped_line: str) -> bool:
-        return stripped_line.startswith(("def ", "class ", "async def "))
+    def _merge_direct_config(
+        self, setting: str, value: t.Any, pkg_config: dict[str, t.Any]
+    ) -> None:
+        if isinstance(value, str | list) and "crackerjack" in str(value):
+            pkg_config[setting] = self.swap_package_name(t.cast(str | list[str], value))
+        elif self._is_mergeable_list(setting, value):
+            existing = pkg_config.get(setting, [])
+            if isinstance(existing, list) and isinstance(value, list):
+                pkg_config[setting] = list(
+                    set(t.cast(list[str], existing) + t.cast(list[str], value))
+                )
+            else:
+                pkg_config[setting] = value
+        elif setting not in pkg_config:
+            pkg_config[setting] = value
 
-    def _handle_docstring_start(self, stripped: str, state: dict[str, t.Any]) -> bool:
-        if not stripped.startswith(('"""', "'''", '"', "'")):
-            return False
-        if stripped.startswith(('"""', "'''")):
-            delimiter = stripped[:3]
-        else:
-            delimiter = stripped[0]
-        state["delimiter"] = delimiter
-        if self._is_single_line_docstring(stripped, delimiter):
-            state["waiting"] = False
-            return True
-        else:
-            state["in_docstring"] = True
-            state["waiting"] = False
-            return True
+    def _is_mergeable_list(self, key: str, value: t.Any) -> bool:
+        return key in (
+            "exclude-deps",
+            "exclude",
+            "excluded",
+            "skips",
+            "ignore",
+        ) and isinstance(value, list)
 
-    def _is_single_line_docstring(self, stripped: str, delimiter: str) -> bool:
-        return stripped.endswith(delimiter) and len(stripped) > len(delimiter)
+    def _update_python_version(
+        self, our_toml_config: dict[str, t.Any], pkg_toml_config: dict[str, t.Any]
+    ) -> None:
+        python_version_pattern = "\\s*W*(\\d\\.\\d*)"
+        requires_python = our_toml_config.get("project", {}).get("requires-python", "")
+        classifiers: list[str] = []
+        for classifier in pkg_toml_config.get("project", {}).get("classifiers", []):
+            classifier = re.sub(
+                python_version_pattern, f" {self.python_version}", classifier
+            )
+            classifiers.append(classifier)
+        pkg_toml_config["project"]["classifiers"] = classifiers
+        if requires_python:
+            pkg_toml_config["project"]["requires-python"] = requires_python
 
-    def _handle_docstring_end(self, stripped: str, state: dict[str, t.Any]) -> bool:
-        if state["delimiter"] and stripped.endswith(state["delimiter"]):
-            state["in_docstring"] = False
-            state["delimiter"] = None
-            return True
-        return False
+    def _save_pkg_toml(self, pkg_toml_config: dict[str, t.Any]) -> None:
+        if self.pkg_toml_path:
+            self.pkg_toml_path.write_text(dumps(pkg_toml_config))
 
-    def _needs_pass_statement(
-        self, lines: list[str], start_index: int, function_indent: int
-    ) -> bool:
-        for i in range(start_index, len(lines)):
-            line = lines[i]
-            stripped = line.strip()
-            if not stripped:
+    def copy_configs(self) -> None:
+        configs_to_add: list[str] = []
+        for config in config_files:
+            config_path = self.our_path / config
+            pkg_config_path = self.pkg_path / config
+            pkg_config_path.touch()
+            if self.pkg_path.stem == "crackerjack":
+                config_path.write_text(pkg_config_path.read_text())
                 continue
-            line_indent = len(line) - len(line.lstrip())
-            if line_indent <= function_indent:
-                return True
-            if line_indent > function_indent:
-                return False
-        return True
+            if config != ".gitignore":
+                pkg_config_path.write_text(
+                    config_path.read_text().replace("crackerjack", self.pkg_name)
+                )
+                configs_to_add.append(config)
+        if configs_to_add:
+            self.execute_command(["git", "add"] + configs_to_add)
 
-    def remove_line_comments(self, code: str) -> str:
-        lines = code.split("\n")
-        cleaned_lines: list[str] = []
-        for line in lines:
-            if not line.strip():
-                cleaned_lines.append(line)
-                continue
-            cleaned_line = self._process_line_for_comments(line)
-            if cleaned_line or not line.strip():
-                cleaned_lines.append(cleaned_line or line)
-        return "\n".join(cleaned_lines)
-
-    def _process_line_for_comments(self, line: str) -> str:
-        result: list[str] = []
-        string_state = {"in_string": None}
-        for i, char in enumerate(line):
-            if self._handle_string_character(char, i, line, string_state, result):
-                continue
-            elif self._handle_comment_character(char, i, line, string_state, result):
-                break
-            else:
-                result.append(char)
-        return "".join(result).rstrip()
+    def copy_documentation_templates(
+        self, force_update: bool = False, compress_docs: bool = False
+    ) -> None:
+        docs_to_add: list[str] = []
+        for doc_file in documentation_files:
+            if self._should_process_doc_file(doc_file):
+                self._process_single_doc_file(
+                    doc_file, force_update, compress_docs, docs_to_add
+                )
 
-    def _handle_string_character(
-        self,
-        char: str,
-        index: int,
-        line: str,
-        string_state: dict[str, t.Any],
-        result: list[str],
-    ) -> bool:
-        if char not in ("'", '"'):
+        if docs_to_add:
+            self.execute_command(["git", "add"] + docs_to_add)
+
+    def _should_process_doc_file(self, doc_file: str) -> bool:
+        doc_path = self.our_path / doc_file
+        if not doc_path.exists():
             return False
-        if index > 0 and line[index - 1] == "\\":
+        if self.pkg_path.stem == "crackerjack":
             return False
-        if string_state["in_string"] is None:
-            string_state["in_string"] = char
-        elif string_state["in_string"] == char:
-            string_state["in_string"] = None
-        result.append(char)
         return True
 
-    def _handle_comment_character(
+    def _process_single_doc_file(
         self,
-        char: str,
-        index: int,
-        line: str,
-        string_state: dict[str, t.Any],
-        result: list[str],
-    ) -> bool:
-        if char != "#" or string_state["in_string"] is not None:
-            return False
-        comment = line[index:].strip()
-        if self._is_special_comment_line(comment):
-            result.append(line[index:])
-        return True
+        doc_file: str,
+        force_update: bool,
+        compress_docs: bool,
+        docs_to_add: list[str],
+    ) -> None:
+        doc_path = self.our_path / doc_file
+        pkg_doc_path = self.pkg_path / doc_file
+        should_update = force_update or not pkg_doc_path.exists()
 
-    def _is_special_comment_line(self, comment: str) -> bool:
-        special_comment_pattern = (
-            r"^#\s*(?:type:\s*ignore(?:\[.*?\])?|noqa|nosec|pragma:\s*no\s*cover"
-            r"|pylint:\s*disable|mypy:\s*ignore)"
-        )
-        return bool(re.match(special_comment_pattern, comment))
+        if should_update:
+            pkg_doc_path.touch()
+            content = doc_path.read_text(encoding="utf-8")
 
-    def remove_extra_whitespace(self, code: str) -> str:
-        lines = code.split("\n")
-        cleaned_lines: list[str] = []
-        function_tracker = {"in_function": False, "function_indent": 0}
-        import_tracker = {"in_imports": False, "last_import_type": None}
-        for i, line in enumerate(lines):
-            line = line.rstrip()
-            stripped_line = line.lstrip()
-            self._update_function_state(line, stripped_line, function_tracker)
-            self._update_import_state(line, stripped_line, import_tracker)
-            if not line:
-                if self._should_skip_empty_line(
-                    i, lines, cleaned_lines, function_tracker, import_tracker
-                ):
-                    continue
-            cleaned_lines.append(line)
-        return "\n".join(self._remove_trailing_empty_lines(cleaned_lines))
-
-    def remove_docstrings_streaming(self, code: str) -> str:
-        if len(code) < 10000:
-            return self.remove_docstrings(code)
-
-        def process_lines():
-            lines = code.split("\n")
-            docstring_state = self._initialize_docstring_state()
-            for i, line in enumerate(lines):
-                handled, result_line = self._process_line(
-                    lines, i, line, docstring_state
-                )
-                if handled:
-                    if result_line is not None:
-                        yield result_line
-                else:
-                    yield line
+            auto_compress = self._should_compress_doc(doc_file, compress_docs)
+            updated_content = self._customize_documentation_content(
+                content, doc_file, auto_compress
+            )
+            pkg_doc_path.write_text(updated_content, encoding="utf-8")
+            docs_to_add.append(doc_file)
 
-        return "\n".join(process_lines())
+            self._print_doc_update_message(doc_file, auto_compress)
 
-    def remove_line_comments_streaming(self, code: str) -> str:
-        if len(code) < 10000:
-            return self.remove_line_comments(code)
+    def _should_compress_doc(self, doc_file: str, compress_docs: bool) -> bool:
+        return compress_docs or (
+            self.pkg_path.stem != "crackerjack" and doc_file == "CLAUDE.md"
+        )
 
-        def process_lines():
-            for line in code.split("\n"):
-                if not line.strip():
-                    yield line
-                    continue
-                cleaned_line = self._process_line_for_comments(line)
-                if cleaned_line or not line.strip():
-                    yield cleaned_line or line
+    def _print_doc_update_message(self, doc_file: str, auto_compress: bool) -> None:
+        compression_note = (
+            " (compressed for Claude Code)"
+            if auto_compress and doc_file == "CLAUDE.md"
+            else ""
+        )
+        self.console.print(
+            f"[green]📋[/green] Updated {doc_file} with latest Crackerjack quality standards{compression_note}"
+        )
 
-        return "\n".join(process_lines())
-
-    def remove_extra_whitespace_streaming(self, code: str) -> str:
-        if len(code) < 10000:
-            return self.remove_extra_whitespace(code)
+    def _customize_documentation_content(
+        self, content: str, filename: str, compress: bool = False
+    ) -> str:
+        if filename == "CLAUDE.md":
+            return self._customize_claude_md(content, compress)
+        elif filename == "RULES.md":
+            return self._customize_rules_md(content)
+        return content
 
-        def process_lines():
-            lines = code.split("\n")
-            function_tracker: dict[str, t.Any] = {
-                "in_function": False,
-                "function_indent": 0,
-            }
-            import_tracker: dict[str, t.Any] = {
-                "in_imports": False,
-                "last_import_type": None,
-            }
-            previous_lines: list[str] = []
-            for i, line in enumerate(lines):
-                line = line.rstrip()
-                stripped_line = line.lstrip()
-                self._update_function_state(line, stripped_line, function_tracker)
-                self._update_import_state(line, stripped_line, import_tracker)
-                if not line:
-                    if self._should_skip_empty_line(
-                        i, lines, previous_lines, function_tracker, import_tracker
-                    ):
-                        continue
-                previous_lines.append(line)
-                yield line
+    def _compress_claude_md(self, content: str, target_size: int = 30000) -> str:
+        content.split("\n")
+        current_size = len(content)
+        if current_size <= target_size:
+            return content
+        essential_sections = [
+            "# ",
+            "## Project Overview",
+            "## Key Commands",
+            "## Development Guidelines",
+            "## Code Quality Compliance",
+            "### Refurb Standards",
+            "### Bandit Security Standards",
+            "### Pyright Type Safety Standards",
+            "## AI Code Generation Best Practices",
+            "## Task Completion Requirements",
+        ]
+        compression_strategies = [
+            self._remove_redundant_examples,
+            self._compress_command_examples,
+            self._remove_verbose_sections,
+            self._compress_repeated_patterns,
+            self._summarize_long_sections,
+        ]
+        compressed_content = content
+        for strategy in compression_strategies:
+            compressed_content = strategy(compressed_content)
+            if len(compressed_content) <= target_size:
+                break
+        if len(compressed_content) > target_size:
+            compressed_content = self._extract_essential_sections(
+                compressed_content, essential_sections, target_size
+            )
 
-        processed_lines = list(process_lines())
-        return "\n".join(self._remove_trailing_empty_lines(processed_lines))
+        return self._add_compression_notice(compressed_content)
 
-    def _update_function_state(
-        self, line: str, stripped_line: str, function_tracker: dict[str, t.Any]
-    ) -> None:
-        if stripped_line.startswith(("def ", "async def ")):
-            function_tracker["in_function"] = True
-            function_tracker["function_indent"] = len(line) - len(stripped_line)
-        elif self._is_function_end(line, stripped_line, function_tracker):
-            function_tracker["in_function"] = False
-            function_tracker["function_indent"] = 0
-
-    def _update_import_state(
-        self, line: str, stripped_line: str, import_tracker: dict[str, t.Any]
-    ) -> None:
-        if stripped_line.startswith(("import ", "from ")):
-            import_tracker["in_imports"] = True
-            if self._is_stdlib_import(stripped_line):
-                current_type = "stdlib"
-            elif self._is_local_import(stripped_line):
-                current_type = "local"
+    def _remove_redundant_examples(self, content: str) -> str:
+        lines = content.split("\n")
+        result = []
+        in_example_block = False
+        example_count = 0
+        max_examples_per_section = 2
+        for line in lines:
+            if line.strip().startswith("```"):
+                if not in_example_block:
+                    example_count += 1
+                    if example_count <= max_examples_per_section:
+                        result.append(line)
+                        in_example_block = True
+                    else:
+                        in_example_block = "skip"
+                else:
+                    if in_example_block != "skip":
+                        result.append(line)
+                    in_example_block = False
+            elif in_example_block == "skip":
+                continue
+            elif line.startswith(("## ", "### ")):
+                example_count = 0
+                result.append(line)
             else:
-                current_type = "third_party"
-            import_tracker["last_import_type"] = current_type
-        elif stripped_line and not stripped_line.startswith("#"):
-            import_tracker["in_imports"] = False
-            import_tracker["last_import_type"] = None
-
-    @staticmethod
-    @lru_cache(maxsize=256)
-    def _is_stdlib_module(module: str) -> bool:
-        stdlib_modules = {
-            "os",
-            "sys",
-            "re",
-            "json",
-            "datetime",
-            "time",
-            "pathlib",
-            "typing",
-            "collections",
-            "itertools",
-            "functools",
-            "operator",
-            "math",
-            "random",
-            "uuid",
-            "urllib",
-            "http",
-            "html",
-            "xml",
-            "email",
-            "csv",
-            "sqlite3",
-            "subprocess",
-            "threading",
-            "multiprocessing",
-            "asyncio",
-            "contextlib",
-            "dataclasses",
-            "enum",
-            "abc",
-            "io",
-            "tempfile",
-            "shutil",
-            "glob",
-            "pickle",
-            "copy",
-            "heapq",
-            "bisect",
-            "array",
-            "struct",
-            "zlib",
-            "hashlib",
-            "hmac",
-            "secrets",
-            "base64",
-            "binascii",
-            "codecs",
-            "locale",
-            "platform",
-            "socket",
-            "ssl",
-            "ipaddress",
-            "logging",
-            "warnings",
-            "inspect",
-            "ast",
-            "dis",
-            "tokenize",
-            "keyword",
-            "linecache",
-            "traceback",
-            "weakref",
-            "gc",
-            "ctypes",
-            "unittest",
-            "doctest",
-            "pdb",
-            "profile",
-            "cProfile",
-            "timeit",
-            "trace",
-            "calendar",
-            "decimal",
-            "fractions",
-            "statistics",
-            "tomllib",
-        }
-        return module in stdlib_modules
+                result.append(line)
 
-    def _is_stdlib_import(self, stripped_line: str) -> bool:
-        try:
-            if stripped_line.startswith("from "):
-                module = stripped_line.split()[1].split(".")[0]
-            else:
-                module = stripped_line.split()[1].split(".")[0]
-        except IndexError:
-            return False
-        return CodeCleaner._is_stdlib_module(module)
+        return "\n".join(result)
 
-    def _is_local_import(self, stripped_line: str) -> bool:
-        return stripped_line.startswith("from .") or " . " in stripped_line
+    def _compress_command_examples(self, content: str) -> str:
+        import re
 
-    def _is_function_end(
-        self, line: str, stripped_line: str, function_tracker: dict[str, t.Any]
-    ) -> bool:
-        return (
-            function_tracker["in_function"]
-            and bool(line)
-            and (len(line) - len(stripped_line) <= function_tracker["function_indent"])
-            and (not stripped_line.startswith(("@", "#")))
+        content = re.sub(
+            r"```bash\n((?:[^`]+\n){3,})```",
+            lambda m: "```bash\n"
+            + "\n".join(m.group(1).split("\n")[:3])
+            + "\n# ... (additional commands available)\n```",
+            content,
+            flags=re.MULTILINE,
         )
 
-    def _should_skip_empty_line(
-        self,
-        line_idx: int,
-        lines: list[str],
-        cleaned_lines: list[str],
-        function_tracker: dict[str, t.Any],
-        import_tracker: dict[str, t.Any],
-    ) -> bool:
-        if line_idx > 0 and cleaned_lines and (not cleaned_lines[-1]):
-            return True
-
-        if self._is_import_section_separator(line_idx, lines, import_tracker):
-            return False
-
-        if function_tracker["in_function"]:
-            return self._should_skip_function_empty_line(line_idx, lines)
-        return False
-
-    def _is_import_section_separator(
-        self, line_idx: int, lines: list[str], import_tracker: dict[str, t.Any]
-    ) -> bool:
-        if not import_tracker["in_imports"]:
-            return False
-
-        next_line_idx = line_idx + 1
-        while next_line_idx < len(lines) and not lines[next_line_idx].strip():
-            next_line_idx += 1
-
-        if next_line_idx >= len(lines):
-            return False
-
-        next_line = lines[next_line_idx].strip()
-        if not next_line.startswith(("import ", "from ")):
-            return False
-
-        if self._is_stdlib_import(next_line):
-            next_type = "stdlib"
-        elif self._is_local_import(next_line):
-            next_type = "local"
-        else:
-            next_type = "third_party"
-
-        return import_tracker["last_import_type"] != next_type
-
-    def _should_skip_function_empty_line(self, line_idx: int, lines: list[str]) -> bool:
-        next_line_idx = line_idx + 1
-        if next_line_idx >= len(lines):
-            return False
-        next_line = lines[next_line_idx].strip()
-        return not self._is_significant_next_line(next_line)
-
-    def _is_significant_next_line(self, next_line: str) -> bool:
-        if next_line.startswith(("return", "class ", "def ", "async def ", "@")):
-            return True
-        if next_line in ("pass", "break", "continue", "raise"):
-            return True
-        return self._is_special_comment(next_line)
-
-    def _is_special_comment(self, line: str) -> bool:
-        if not line.startswith("#"):
-            return False
-        special_patterns = ("type:", "noqa", "nosec", "pragma:", "pylint:", "mypy:")
-        return any(pattern in line for pattern in special_patterns)
-
-    def _remove_trailing_empty_lines(self, lines: list[str]) -> list[str]:
-        while lines and (not lines[-1]):
-            lines.pop()
-        return lines
-
-    def reformat_code(self, code: str) -> str:
-        from crackerjack.errors import handle_error
-
-        try:
-            import tempfile
-
-            with tempfile.NamedTemporaryFile(
-                suffix=".py", mode="w+", delete=False
-            ) as temp:
-                temp_path = Path(temp.name)
-                temp_path.write_text(code)
-            try:
-                result = subprocess.run(
-                    ["uv", "run", "ruff", "format", str(temp_path)],
-                    check=False,
-                    capture_output=True,
-                    text=True,
-                )
-                if result.returncode == 0:
-                    formatted_code = temp_path.read_text()
-                else:
-                    self.console.print(
-                        f"[bold bright_yellow]⚠️  Ruff formatting failed: {result.stderr}[/bold bright_yellow]"
-                    )
-                    handle_error(
-                        ExecutionError(
-                            message="Code formatting failed",
-                            error_code=ErrorCode.FORMATTING_ERROR,
-                            details=result.stderr,
-                            recovery="Check Ruff configuration and formatting rules",
-                        ),
-                        console=self.console,
-                        exit_on_error=False,
-                    )
-                    formatted_code = code
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_red]❌ Error running Ruff: {e}[/bold bright_red]"
-                )
-                handle_error(
-                    ExecutionError(
-                        message="Error running Ruff",
-                        error_code=ErrorCode.FORMATTING_ERROR,
-                        details=str(e),
-                        recovery="Verify Ruff is installed and configured correctly",
-                    ),
-                    console=self.console,
-                    exit_on_error=False,
-                )
-                formatted_code = code
-            finally:
-                with suppress(FileNotFoundError):
-                    temp_path.unlink()
-            return formatted_code
-        except Exception as e:
-            self.console.print(
-                f"[bold bright_red]❌ Error during reformatting: {e}[/bold bright_red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message="Error during reformatting",
-                    error_code=ErrorCode.FORMATTING_ERROR,
-                    details=str(e),
-                    recovery="Check file permissions and disk space",
-                ),
-                console=self.console,
-            )
-            return code
+        return content
 
-    async def clean_files_async(self, pkg_dir: Path | None) -> None:
-        if pkg_dir is None:
-            return
-        python_files = [
-            file_path
-            for file_path in pkg_dir.rglob("*.py")
-            if not str(file_path.parent).startswith("__")
+    def _remove_verbose_sections(self, content: str) -> str:
+        sections_to_compress = [
+            "## Recent Bug Fixes and Improvements",
+            "## Development Memories",
+            "## Self-Maintenance Protocol for AI Assistants",
+            "## Pre-commit Hook Maintenance",
         ]
-        if not python_files:
-            return
-        max_concurrent = min(len(python_files), 8)
-        semaphore = asyncio.Semaphore(max_concurrent)
+        lines = content.split("\n")
+        result = []
+        skip_section = False
+        for line in lines:
+            if any(line.startswith(section) for section in sections_to_compress):
+                skip_section = True
+                result.extend(
+                    (line, "*[Detailed information available in full CLAUDE.md]*")
+                )
+                result.append("")
+            elif line.startswith("## ") and skip_section:
+                skip_section = False
+                result.append(line)
+            elif not skip_section:
+                result.append(line)
 
-        async def clean_with_semaphore(file_path: Path) -> None:
-            async with semaphore:
-                await self.clean_file_async(file_path)
+        return "\n".join(result)
 
-        tasks = [clean_with_semaphore(file_path) for file_path in python_files]
-        await asyncio.gather(*tasks, return_exceptions=True)
+    def _compress_repeated_patterns(self, content: str) -> str:
+        import re
 
-        await self._cleanup_cache_directories_async(pkg_dir)
+        content = re.sub(r"\n{3,}", "\n\n", content)
+        content = re.sub(
+            r"(\*\*[A-Z][^*]+:\*\*[^\n]+\n){3,}",
+            lambda m: m.group(0)[:200]
+            + "...\n*[Additional patterns available in full documentation]*\n",
+            content,
+        )
 
-    async def clean_file_async(self, file_path: Path) -> None:
-        from crackerjack.errors import ExecutionError, handle_error
+        return content
 
-        try:
-            async with aiofiles.open(file_path, encoding="utf-8") as f:  # type: ignore[misc]
-                code: str = await f.read()  # type: ignore[misc]
-            original_code: str = code
-            cleaning_failed = False
-            try:
-                code = self.remove_line_comments_streaming(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to remove line comments from {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            try:
-                code = self.remove_docstrings_streaming(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to remove docstrings from {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            try:
-                code = self.remove_extra_whitespace_streaming(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to remove extra whitespace from {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            try:
-                code = await self.reformat_code_async(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to reformat {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            async with aiofiles.open(file_path, "w", encoding="utf-8") as f:  # type: ignore[misc]
-                await f.write(code)  # type: ignore[misc]
-            if cleaning_failed:
-                self.console.print(
-                    f"[bold yellow]⚡ Partially cleaned:[/bold yellow] [dim bright_white]{file_path}[/dim bright_white]"
-                )
+    def _summarize_long_sections(self, content: str) -> str:
+        lines = content.split("\n")
+        result = []
+        current_section = []
+        section_header = ""
+        for line in lines:
+            if line.startswith(("### ", "## ")):
+                if current_section and len("\n".join(current_section)) > 1000:
+                    summary = self._create_section_summary(
+                        section_header, current_section
+                    )
+                    result.extend(summary)
+                else:
+                    result.extend(current_section)
+                current_section = [line]
+                section_header = line
             else:
-                self.console.print(
-                    f"[bold green]✨ Cleaned:[/bold green] [dim bright_white]{file_path}[/dim bright_white]"
-                )
-        except PermissionError as e:
-            self.console.print(
-                f"[red]Failed to clean: {file_path} (Permission denied)[/red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message=f"Permission denied while cleaning {file_path}",
-                    error_code=ErrorCode.PERMISSION_ERROR,
-                    details=str(e),
-                    recovery=f"Check file permissions for {file_path} and ensure you have write access",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
-        except OSError as e:
-            self.console.print(
-                f"[red]Failed to clean: {file_path} (File system error)[/red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message=f"File system error while cleaning {file_path}",
-                    error_code=ErrorCode.FILE_WRITE_ERROR,
-                    details=str(e),
-                    recovery=f"Check that {file_path} exists and is not being used by another process",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
-        except UnicodeDecodeError as e:
-            self.console.print(
-                f"[red]Failed to clean: {file_path} (Encoding error)[/red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message=f"Encoding error while cleaning {file_path}",
-                    error_code=ErrorCode.FILE_READ_ERROR,
-                    details=str(e),
-                    recovery=f"Check the file encoding of {file_path} - it may not be UTF-8",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
-        except Exception as e:
-            self.console.print(f"[red]Unexpected error cleaning {file_path}: {e}[/red]")
-            handle_error(
-                ExecutionError(
-                    message=f"Unexpected error while cleaning {file_path}",
-                    error_code=ErrorCode.UNEXPECTED_ERROR,
-                    details=str(e),
-                    recovery="Please report this issue with the full error details",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
-
-    async def reformat_code_async(self, code: str) -> str:
-        from crackerjack.errors import handle_error
+                current_section.append(line)
+        if current_section:
+            if len("\n".join(current_section)) > 1000:
+                summary = self._create_section_summary(section_header, current_section)
+                result.extend(summary)
+            else:
+                result.extend(current_section)
 
-        try:
-            import tempfile
-
-            with tempfile.NamedTemporaryFile(
-                suffix=".py", mode="w+", delete=False
-            ) as temp:
-                temp_path = Path(temp.name)
-            async with aiofiles.open(temp_path, "w", encoding="utf-8") as f:  # type: ignore[misc]
-                await f.write(code)  # type: ignore[misc]
-            try:
-                proc = await asyncio.create_subprocess_exec(
-                    "uv",
-                    "run",
-                    "ruff",
-                    "format",
-                    str(temp_path),
-                    stdout=asyncio.subprocess.PIPE,
-                    stderr=asyncio.subprocess.PIPE,
-                )
-                _, stderr = await proc.communicate()
-                if proc.returncode == 0:
-                    async with aiofiles.open(temp_path, encoding="utf-8") as f:  # type: ignore[misc]
-                        formatted_code = await f.read()  # type: ignore[misc]
-                else:
-                    self.console.print(
-                        f"[bold bright_yellow]⚠️  Warning: Ruff format failed with return code {proc.returncode}[/bold bright_yellow]"
-                    )
-                    if stderr:
-                        self.console.print(f"[dim]Ruff stderr: {stderr.decode()}[/dim]")
-                    formatted_code = code
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_red]❌ Error running Ruff: {e}[/bold bright_red]"
-                )
-                handle_error(
-                    ExecutionError(
-                        message="Error running Ruff",
-                        error_code=ErrorCode.FORMATTING_ERROR,
-                        details=str(e),
-                        recovery="Verify Ruff is installed and configured correctly",
-                    ),
-                    console=self.console,
-                    exit_on_error=False,
-                )
-                formatted_code = code
-            finally:
-                with suppress(FileNotFoundError):
-                    temp_path.unlink()
+        return "\n".join(result)
 
-            return formatted_code
-        except Exception as e:
-            self.console.print(
-                f"[bold bright_red]❌ Error during reformatting: {e}[/bold bright_red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message="Error during reformatting",
-                    error_code=ErrorCode.FORMATTING_ERROR,
-                    details=str(e),
-                    recovery="Check file permissions and disk space",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
-            return code
-
-    async def _cleanup_cache_directories_async(self, pkg_dir: Path) -> None:
-        def cleanup_sync() -> None:
-            with suppress(PermissionError, OSError):
-                pycache_dir = pkg_dir / "__pycache__"
-                if pycache_dir.exists():
-                    for cache_file in pycache_dir.iterdir():
-                        with suppress(PermissionError, OSError):
-                            cache_file.unlink()
-                    pycache_dir.rmdir()
-                parent_pycache = pkg_dir.parent / "__pycache__"
-                if parent_pycache.exists():
-                    for cache_file in parent_pycache.iterdir():
-                        with suppress(PermissionError, OSError):
-                            cache_file.unlink()
-                    parent_pycache.rmdir()
-
-        loop = asyncio.get_event_loop()
-        await loop.run_in_executor(None, cleanup_sync)
+    def _create_section_summary(
+        self, header: str, section_lines: list[str]
+    ) -> list[str]:
+        summary = [header, ""]
 
+        key_points = []
+        for line in section_lines[2:]:
+            if line.strip().startswith(("- ", "* ", "1. ", "2. ")):
+                key_points.append(line)
+            elif line.strip().startswith("**") and ":" in line:
+                key_points.append(line)
 
-class ConfigManager(BaseModel, arbitrary_types_allowed=True):
-    our_path: Path
-    pkg_path: Path
-    pkg_name: str
-    console: Console
-    our_toml_path: Path | None = None
-    pkg_toml_path: Path | None = None
-    python_version: str = default_python_version
-    dry_run: bool = False
+            if len(key_points) >= 5:
+                break
 
-    def swap_package_name(self, value: list[str] | str) -> list[str] | str:
-        if isinstance(value, list):
-            value.remove("crackerjack")
-            value.append(self.pkg_name)
+        if key_points:
+            summary.extend(key_points[:5])
+            summary.append("*[Complete details available in full CLAUDE.md]*")
         else:
-            value = value.replace("crackerjack", self.pkg_name)
-        return value
-
-    def update_pyproject_configs(self) -> None:
-        self._setup_toml_paths()
-        if self._is_crackerjack_project():
-            self._handle_crackerjack_project()
-            return
-        our_toml_config = self._load_our_toml()
-        pkg_toml_config = self._load_pkg_toml()
-        self._ensure_required_sections(pkg_toml_config)
-        self._update_tool_settings(our_toml_config, pkg_toml_config)
-        self._update_python_version(our_toml_config, pkg_toml_config)
-        self._save_pkg_toml(pkg_toml_config)
-
-    def _setup_toml_paths(self) -> None:
-        toml_file = "pyproject.toml"
-        self.our_toml_path = self.our_path / toml_file
-        self.pkg_toml_path = self.pkg_path / toml_file
-
-    def _is_crackerjack_project(self) -> bool:
-        return self.pkg_path.stem == "crackerjack"
-
-    def _handle_crackerjack_project(self) -> None:
-        if self.our_toml_path and self.pkg_toml_path:
-            self.our_toml_path.write_text(self.pkg_toml_path.read_text())
-
-    def _load_our_toml(self) -> dict[str, t.Any]:
-        if self.our_toml_path:
-            return loads(self.our_toml_path.read_text())
-        return {}
-
-    def _load_pkg_toml(self) -> dict[str, t.Any]:
-        if self.pkg_toml_path:
-            return loads(self.pkg_toml_path.read_text())
-        return {}
+            content_preview = " ".join(
+                line.strip()
+                for line in section_lines[2:10]
+                if line.strip() and not line.startswith("#")
+            )[:200]
+            summary.extend(
+                (
+                    f"{content_preview}...",
+                    "*[Full section available in complete documentation]*",
+                )
+            )
 
-    def _ensure_required_sections(self, pkg_toml_config: dict[str, t.Any]) -> None:
-        pkg_toml_config.setdefault("tool", {})
-        pkg_toml_config.setdefault("project", {})
+        summary.append("")
+        return summary
 
-    def _update_tool_settings(
-        self, our_toml_config: dict[str, t.Any], pkg_toml_config: dict[str, t.Any]
-    ) -> None:
-        for tool, settings in our_toml_config.get("tool", {}).items():
-            if tool not in pkg_toml_config["tool"]:
-                pkg_toml_config["tool"][tool] = {}
-            pkg_tool_config = pkg_toml_config["tool"][tool]
-            self._merge_tool_config(settings, pkg_tool_config, tool)
+    def _extract_essential_sections(
+        self, content: str, essential_sections: list[str], target_size: int
+    ) -> str:
+        lines = content.split("\n")
+        result = []
+        current_section = []
+        keep_section = False
 
-    def _merge_tool_config(
-        self, our_config: dict[str, t.Any], pkg_config: dict[str, t.Any], tool: str
-    ) -> None:
-        for setting, value in our_config.items():
-            if isinstance(value, dict):
-                self._merge_nested_config(
-                    setting, t.cast(dict[str, t.Any], value), pkg_config
-                )
+        for line in lines:
+            new_section_started = self._process_line_for_section(
+                line, essential_sections, current_section, keep_section, result
+            )
+            if new_section_started is not None:
+                current_section, keep_section = new_section_started
             else:
-                self._merge_direct_config(setting, value, pkg_config)
+                current_section.append(line)
 
-    def _merge_nested_config(
-        self, setting: str, value: dict[str, t.Any], pkg_config: dict[str, t.Any]
-    ) -> None:
-        if setting not in pkg_config:
-            pkg_config[setting] = {}
-        elif not isinstance(pkg_config[setting], dict):
-            pkg_config[setting] = {}
-        self._merge_tool_config(value, pkg_config[setting], "")
-        for k, v in value.items():
-            self._merge_nested_value(k, v, pkg_config[setting])
+            if self._should_stop_extraction(result, target_size):
+                break
 
-    def _merge_nested_value(
-        self, key: str, value: t.Any, nested_config: dict[str, t.Any]
-    ) -> None:
-        if isinstance(value, str | list) and "crackerjack" in str(value):
-            nested_config[key] = self.swap_package_name(t.cast(str | list[str], value))
-        elif self._is_mergeable_list(key, value):
-            existing = nested_config.get(key, [])
-            if isinstance(existing, list) and isinstance(value, list):
-                nested_config[key] = list(
-                    set(t.cast(list[str], existing) + t.cast(list[str], value))
-                )
-            else:
-                nested_config[key] = value
-        elif key not in nested_config:
-            nested_config[key] = value
+        self._finalize_extraction(current_section, keep_section, result, target_size)
+        return "\n".join(result)
 
-    def _merge_direct_config(
-        self, setting: str, value: t.Any, pkg_config: dict[str, t.Any]
-    ) -> None:
-        if isinstance(value, str | list) and "crackerjack" in str(value):
-            pkg_config[setting] = self.swap_package_name(t.cast(str | list[str], value))
-        elif self._is_mergeable_list(setting, value):
-            existing = pkg_config.get(setting, [])
-            if isinstance(existing, list) and isinstance(value, list):
-                pkg_config[setting] = list(
-                    set(t.cast(list[str], existing) + t.cast(list[str], value))
-                )
-            else:
-                pkg_config[setting] = value
-        elif setting not in pkg_config:
-            pkg_config[setting] = value
+    def _process_line_for_section(
+        self,
+        line: str,
+        essential_sections: list[str],
+        current_section: list[str],
+        keep_section: bool,
+        result: list[str],
+    ) -> tuple[list[str], bool] | None:
+        if any(line.startswith(section) for section in essential_sections):
+            if current_section and keep_section:
+                result.extend(current_section)
+            return ([line], True)
+        elif line.startswith(("## ", "### ")):
+            if current_section and keep_section:
+                result.extend(current_section)
+            return ([line], False)
+        return None
 
-    def _is_mergeable_list(self, key: str, value: t.Any) -> bool:
-        return key in (
-            "exclude-deps",
-            "exclude",
-            "excluded",
-            "skips",
-            "ignore",
-        ) and isinstance(value, list)
+    def _should_stop_extraction(self, result: list[str], target_size: int) -> bool:
+        return len("\n".join(result)) > target_size
 
-    def _update_python_version(
-        self, our_toml_config: dict[str, t.Any], pkg_toml_config: dict[str, t.Any]
+    def _finalize_extraction(
+        self,
+        current_section: list[str],
+        keep_section: bool,
+        result: list[str],
+        target_size: int,
     ) -> None:
-        python_version_pattern = "\\s*W*(\\d\\.\\d*)"
-        requires_python = our_toml_config.get("project", {}).get("requires-python", "")
-        classifiers: list[str] = []
-        for classifier in pkg_toml_config.get("project", {}).get("classifiers", []):
-            classifier = re.sub(
-                python_version_pattern, f" {self.python_version}", classifier
-            )
-            classifiers.append(classifier)
-        pkg_toml_config["project"]["classifiers"] = classifiers
-        if requires_python:
-            pkg_toml_config["project"]["requires-python"] = requires_python
+        if current_section and keep_section and len("\n".join(result)) < target_size:
+            result.extend(current_section)
 
-    def _save_pkg_toml(self, pkg_toml_config: dict[str, t.Any]) -> None:
-        if self.pkg_toml_path:
-            self.pkg_toml_path.write_text(dumps(pkg_toml_config))
+    def _add_compression_notice(self, content: str) -> str:
+        notice = """
+*Note: This CLAUDE.md has been automatically compressed by Crackerjack to optimize for Claude Code usage.
+Complete documentation is available in the source repository.*
 
-    def copy_configs(self) -> None:
-        configs_to_add: list[str] = []
-        for config in config_files:
-            config_path = self.our_path / config
-            pkg_config_path = self.pkg_path / config
-            pkg_config_path.touch()
-            if self.pkg_path.stem == "crackerjack":
-                config_path.write_text(pkg_config_path.read_text())
-                continue
-            if config != ".gitignore":
-                pkg_config_path.write_text(
-                    config_path.read_text().replace("crackerjack", self.pkg_name)
-                )
-                configs_to_add.append(config)
-        if configs_to_add:
-            self.execute_command(["git", "add"] + configs_to_add)
+"""
 
-    def copy_documentation_templates(self, force_update: bool = False) -> None:
-        docs_to_add: list[str] = []
-        for doc_file in documentation_files:
-            doc_path = self.our_path / doc_file
-            pkg_doc_path = self.pkg_path / doc_file
-            if not doc_path.exists():
-                continue
-            if self.pkg_path.stem == "crackerjack":
-                continue
-            should_update = force_update or not pkg_doc_path.exists()
-            if should_update:
-                pkg_doc_path.touch()
-                content = doc_path.read_text(encoding="utf-8")
-                updated_content = self._customize_documentation_content(
-                    content, doc_file
-                )
-                pkg_doc_path.write_text(updated_content, encoding="utf-8")
-                docs_to_add.append(doc_file)
-                self.console.print(
-                    f"[green]📋[/green] Updated {doc_file} with latest Crackerjack quality standards"
-                )
-        if docs_to_add:
-            self.execute_command(["git", "add"] + docs_to_add)
+        lines = content.split("\n")
+        if len(lines) > 5:
+            lines.insert(5, notice)
 
-    def _customize_documentation_content(self, content: str, filename: str) -> str:
-        if filename == "CLAUDE.md":
-            return self._customize_claude_md(content)
-        elif filename == "RULES.md":
-            return self._customize_rules_md(content)
-        return content
+        return "\n".join(lines)
 
-    def _customize_claude_md(self, content: str) -> str:
+    def _customize_claude_md(self, content: str, compress: bool = False) -> str:
         project_name = self.pkg_name
         content = content.replace("crackerjack", project_name).replace(
             "Crackerjack", project_name.title()
@@ -1737,9 +1049,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
         if start_idx > 0:
             relevant_content = "\n".join(lines[start_idx:])
-            return header + relevant_content
+            full_content = header + relevant_content
+        else:
+            full_content = header + content
 
-        return header + content
+        if compress:
+            return self._compress_claude_md(full_content)
+        return full_content
 
     def _customize_rules_md(self, content: str) -> str:
         project_name = self.pkg_name
@@ -1833,7 +1149,30 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
 
         return env_vars
 
+    def _cleanup_legacy_config_files(self) -> None:
+        legacy_config_files = [
+            ".pre-commit-config.yaml",
+            ".pre-commit-config-ai.yaml",
+            ".pre-commit-config-fast.yaml",
+        ]
+        removed_files = []
+        for config_file in legacy_config_files:
+            config_path = Path(config_file)
+            if config_path.exists():
+                try:
+                    config_path.unlink()
+                    removed_files.append(config_file)
+                except OSError as e:
+                    self.console.print(
+                        f"[yellow]Warning: Could not remove {config_file}: {e}[/yellow]"
+                    )
+        if removed_files:
+            self.console.print(
+                f"[dim]🧹 Cleaned up legacy config files: {', '.join(removed_files)}[/dim]"
+            )
+
     def update_pkg_configs(self) -> None:
+        self._cleanup_legacy_config_files()
         self.config_manager.copy_configs()
         installed_pkgs = self.execute_command(
             ["uv", "pip", "list", "--freeze"], capture_output=True, text=True
@@ -1844,26 +1183,20 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
                 "[bold bright_blue]⚡ INIT[/bold bright_blue] [bold bright_white]First-time project setup[/bold bright_white]"
             )
             self.console.print("─" * 80 + "\n")
-            self.execute_command(["uv", "tool", "install", "keyring"])
+            if self.options and getattr(self.options, "ai_agent", False):
+                import subprocess
+
+                self.execute_command(
+                    ["uv", "tool", "install", "keyring"],
+                    capture_output=True,
+                    stderr=subprocess.DEVNULL,
+                )
+            else:
+                self.execute_command(["uv", "tool", "install", "keyring"])
             self.execute_command(["git", "init"])
             self.execute_command(["git", "branch", "-m", "main"])
             self.execute_command(["git", "add", "pyproject.toml", "uv.lock"])
             self.execute_command(["git", "config", "advice.addIgnoredFile", "false"])
-            install_cmd = ["uv", "run", "pre-commit", "install"]
-            if hasattr(self, "options") and getattr(self.options, "ai_agent", False):
-                install_cmd.extend(["-c", ".pre-commit-config-ai.yaml"])
-            else:
-                install_cmd.extend(["-c", ".pre-commit-config-fast.yaml"])
-            self.execute_command(install_cmd)
-            push_install_cmd = [
-                "uv",
-                "run",
-                "pre-commit",
-                "install",
-                "--hook-type",
-                "pre-push",
-            ]
-            self.execute_command(push_install_cmd)
         self.config_manager.update_pyproject_configs()
 
     def run_pre_commit(self) -> None:
@@ -1899,12 +1232,30 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
 
     def _select_precommit_config(self) -> str:
         if hasattr(self, "options"):
-            if getattr(self.options, "ai_agent", False):
-                return ".pre-commit-config-ai.yaml"
+            experimental_hooks = getattr(self.options, "experimental_hooks", False)
+            enable_pyrefly = getattr(self.options, "enable_pyrefly", False)
+            enable_ty = getattr(self.options, "enable_ty", False)
+            enabled_experimental = []
+            if experimental_hooks:
+                enabled_experimental = ["pyrefly", "ty"]
+            else:
+                if enable_pyrefly:
+                    enabled_experimental.append("pyrefly")
+                if enable_ty:
+                    enabled_experimental.append("ty")
+            if enabled_experimental:
+                mode = "experimental"
+                config_path = generate_config_for_mode(mode, enabled_experimental)
             elif getattr(self.options, "comprehensive", False):
-                return ".pre-commit-config.yaml"
+                mode = "comprehensive"
+                config_path = generate_config_for_mode(mode)
+            else:
+                mode = "fast"
+                config_path = generate_config_for_mode(mode)
 
-        return ".pre-commit-config-fast.yaml"
+            return str(config_path)
+        config_path = generate_config_for_mode("fast")
+        return str(config_path)
 
     def run_pre_commit_with_analysis(self) -> list[HookResult]:
         self.console.print("\n" + "-" * 80)
@@ -1927,7 +1278,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
         result = self.execute_command(cmd, capture_output=True, text=True)
         total_duration = time.time() - start_time
         hook_results = self._parse_hook_output(result.stdout, result.stderr)
-        if hasattr(self, "options") and getattr(self.options, "ai_agent", False):
+        if self.options and getattr(self.options, "ai_agent", False):
             self._generate_hooks_analysis(hook_results, total_duration)
             self._generate_quality_metrics()
             self._generate_project_structure_analysis()
@@ -2049,7 +1400,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
         return suggestions
 
     def _generate_quality_metrics(self) -> None:
-        if not (hasattr(self, "options") and getattr(self.options, "ai_agent", False)):
+        if not (self.options and getattr(self.options, "ai_agent", False)):
             return
         metrics = {
             "project_info": {
@@ -2224,7 +1575,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
         return recommendations
 
     def _generate_project_structure_analysis(self) -> None:
-        if not (hasattr(self, "options") and getattr(self.options, "ai_agent", False)):
+        if not (self.options and getattr(self.options, "ai_agent", False)):
             return
         structure = {
             "project_overview": {
@@ -2248,7 +1599,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
         )
 
     def _generate_error_context_analysis(self) -> None:
-        if not (hasattr(self, "options") and getattr(self.options, "ai_agent", False)):
+        if not (self.options and getattr(self.options, "ai_agent", False)):
             return
         context = {
             "analysis_info": {
@@ -2269,7 +1620,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
         )
 
     def _generate_ai_agent_summary(self) -> None:
-        if not (hasattr(self, "options") and getattr(self.options, "ai_agent", False)):
+        if not (self.options and getattr(self.options, "ai_agent", False)):
             return
         summary = {
             "analysis_summary": {
@@ -2549,7 +1900,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
             raise SystemExit(1)
         else:
             self.console.print(
-                "\n[bold bright_green]✅ Pre-commit passed all checks![/bold bright_green]"
+                "\n[bold bright_green]🏆 Pre-commit passed all checks![/bold bright_green]"
             )
 
     async def run_pre_commit_with_analysis_async(self) -> list[HookResult]:
@@ -2595,7 +1946,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
             raise SystemExit(1)
         else:
             self.console.print(
-                "\n[bold bright_green]✅ Pre-commit passed all checks![/bold bright_green]"
+                "\n[bold bright_green]🏆 Pre-commit passed all checks![/bold bright_green]"
             )
         self._generate_analysis_files(hook_results)
 
@@ -2686,6 +2037,7 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
     config_manager: ConfigManager | None = None
     project_manager: ProjectManager | None = None
     session_tracker: SessionTracker | None = None
+    options: t.Any = None
     _file_cache: dict[str, list[Path]] = {}
     _file_cache_with_mtime: dict[str, tuple[float, list[Path]]] = {}
     _state_file: Path = Path(".crackerjack-state")
@@ -2733,6 +2085,12 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
 
             self._state_file.write_text(json.dumps(state, indent=2), encoding="utf-8")
 
+    def _get_state(self) -> dict[str, t.Any]:
+        return self._read_state()
+
+    def _save_state(self, state: dict[str, t.Any]) -> None:
+        self._write_state(state)
+
     def _clear_state(self) -> None:
         if self._state_file.exists():
             from contextlib import suppress
@@ -2782,6 +2140,79 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
                     return data.get("project", {}).get("version", "unknown")
         return "unknown"
 
+    def _create_git_tag(self, version: str | None = None) -> None:
+        if version is None:
+            version = self._get_current_version()
+        if version == "unknown":
+            self.console.print(
+                "[bold yellow]⚠️  Warning: Could not determine version for tagging[/bold yellow]"
+            )
+            return
+        tag_name = f"v{version}"
+        result = self.execute_command(
+            ["git", "tag", "-l", tag_name], capture_output=True, text=True
+        )
+        if result.stdout.strip():
+            self.console.print(
+                f"[bold yellow]⚠️  Tag {tag_name} already exists, skipping tag creation[/bold yellow]"
+            )
+            return
+        self.console.print(
+            f"[bold bright_cyan]🏷️  Creating git tag: {tag_name}[/bold bright_cyan]"
+        )
+        package_name = self.pkg_path.stem.lower().replace("-", "_")
+        tag_message = f"Release {package_name} v{version}"
+        self.execute_command(["git", "tag", "-a", tag_name, "-m", tag_message])
+        self.console.print(f"[bold green]✅ Created tag: {tag_name}[/bold green]")
+
+    def _push_git_tags(self) -> None:
+        self.console.print(
+            "[bold bright_cyan]🚀 Pushing tags to remote repository[/bold bright_cyan]"
+        )
+        try:
+            self.execute_command(["git", "push", "origin", "--tags"])
+            self.console.print("[bold green]✅ Tags pushed successfully[/bold green]")
+        except Exception as e:
+            self.console.print(
+                f"[bold yellow]⚠️  Warning: Failed to push tags: {e}[/bold yellow]"
+            )
+
+    def _verify_version_consistency(self) -> bool:
+        current_version = self._get_current_version()
+        if current_version == "unknown":
+            self.console.print(
+                "[bold yellow]⚠️  Warning: Could not determine current version from pyproject.toml[/bold yellow]"
+            )
+            return False
+        try:
+            result = self.execute_command(
+                ["git", "describe", "--tags", "--abbrev=0"],
+                capture_output=True,
+                text=True,
+            )
+            latest_tag = result.stdout.strip()
+            if latest_tag.startswith("v"):
+                tag_version = latest_tag[1:]
+            else:
+                tag_version = latest_tag
+        except Exception:
+            self.console.print(
+                "[bold bright_cyan]ℹ️  No git tags found - this appears to be the first release[/bold bright_cyan]"
+            )
+            return True
+        if current_version != tag_version:
+            self.console.print(
+                f"[bold red]❌ Version mismatch detected:[/bold red]\n"
+                f"   pyproject.toml version: {current_version}\n"
+                f"   Latest git tag version: {tag_version}\n"
+                f"   These should match before committing or publishing."
+            )
+            return False
+        self.console.print(
+            f"[bold green]✅ Version consistency verified: {current_version}[/bold green]"
+        )
+        return True
+
     def _setup_package(self) -> None:
         self.pkg_name = self.pkg_path.stem.lower().replace("-", "_")
         self.pkg_dir = self.pkg_path / self.pkg_name
@@ -2801,6 +2232,9 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
         assert self.project_manager is not None
         if not options.no_config_updates:
             self.project_manager.update_pkg_configs()
+            self._run_automatic_updates()
+            if self.pkg_path.stem != "crackerjack":
+                self._check_and_update_crackerjack()
             result: CompletedProcess[str] = self.execute_command(
                 ["uv", "sync"], capture_output=True, text=True
             )
@@ -2813,6 +2247,133 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
                     "\n\n[bold red]❌ UV sync failed. Is UV installed? Run `pipx install uv` and try again.[/bold red]\n\n"
                 )
 
+    def _run_automatic_updates(self) -> None:
+        self.console.print("[dim]🔄 Checking for updates...[/dim]")
+        self._upgrade_dependencies()
+        self._update_hooks_if_needed()
+
+    def _upgrade_dependencies(self) -> None:
+        try:
+            result = self.execute_command(
+                ["uv", "sync", "--upgrade"], capture_output=True, text=True
+            )
+            if result.returncode == 0:
+                self._handle_upgrade_success(result)
+            else:
+                self.console.print(
+                    f"[yellow]⚠️  Dependency upgrade failed: {result.stderr}[/yellow]"
+                )
+        except Exception as e:
+            self.console.print(f"[yellow]⚠️  Error upgrading dependencies: {e}[/yellow]")
+
+    def _handle_upgrade_success(
+        self, result: "subprocess.CompletedProcess[str]"
+    ) -> None:
+        if "no changes" not in result.stdout.lower():
+            self.console.print("[green]✅ Dependencies upgraded[/green]")
+            self._show_upgrade_summary(result.stdout)
+        else:
+            self.console.print("[dim]✓ Dependencies already up to date[/dim]")
+
+    def _show_upgrade_summary(self, stdout: str) -> None:
+        if stdout.strip():
+            upgrade_lines = [line for line in stdout.split("\n") if "->" in line]
+            if upgrade_lines:
+                self.console.print(f"[dim]{len(upgrade_lines)} packages upgraded[/dim]")
+
+    def _update_hooks_if_needed(self) -> None:
+        import time
+        from pathlib import Path
+
+        marker_file = Path(".crackerjack-hooks-updated")
+        current_time = time.time()
+        week_seconds = 7 * 24 * 60 * 60
+        should_update = True
+        if marker_file.exists():
+            try:
+                last_update = float(marker_file.read_text().strip())
+                if current_time - last_update < week_seconds:
+                    should_update = False
+            except (ValueError, OSError):
+                should_update = True
+        if should_update:
+            self._update_precommit_hooks()
+            from contextlib import suppress
+
+            with suppress(OSError):
+                marker_file.write_text(str(current_time))
+        else:
+            self.console.print("[dim]✓ Pre-commit hooks recently updated[/dim]")
+
+    def _update_precommit_hooks(self) -> None:
+        try:
+            result = self.execute_command(
+                ["uv", "run", "pre-commit", "autoupdate"],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                if "updated" in result.stdout.lower():
+                    self.console.print("[green]✅ Pre-commit hooks updated[/green]")
+                    update_lines = [
+                        line for line in result.stdout.split("\n") if "->" in line
+                    ]
+                    if update_lines:
+                        self.console.print(
+                            f"[dim]{len(update_lines)} hooks updated[/dim]"
+                        )
+                else:
+                    self.console.print(
+                        "[dim]✓ Pre-commit hooks already up to date[/dim]"
+                    )
+            else:
+                self.console.print(
+                    f"[yellow]⚠️  Pre-commit update failed: {result.stderr}[/yellow]"
+                )
+        except Exception as e:
+            self.console.print(
+                f"[yellow]⚠️  Error updating pre-commit hooks: {e}[/yellow]"
+            )
+
+    def _check_and_update_crackerjack(self) -> None:
+        try:
+            import tomllib
+            from pathlib import Path
+
+            pyproject_path = Path("pyproject.toml")
+            if not pyproject_path.exists():
+                return
+            with pyproject_path.open("rb") as f:
+                config = tomllib.load(f)
+            dependencies = config.get("project", {}).get("dependencies", [])
+            dev_dependencies = config.get("dependency-groups", {}).get("dev", [])
+            has_crackerjack = any(
+                dep.startswith("crackerjack") for dep in dependencies + dev_dependencies
+            )
+            if has_crackerjack:
+                result = self.execute_command(
+                    ["uv", "sync", "--upgrade", "--upgrade-package", "crackerjack"],
+                    capture_output=True,
+                    text=True,
+                )
+                if result.returncode == 0:
+                    if "crackerjack" in result.stdout:
+                        self.console.print(
+                            "[green]✅ Crackerjack upgraded to latest version[/green]"
+                        )
+                    else:
+                        self.console.print(
+                            "[dim]✓ Crackerjack already up to date[/dim]"
+                        )
+                else:
+                    self.console.print(
+                        f"[yellow]⚠️  Crackerjack update check failed: {result.stderr}[/yellow]"
+                    )
+        except Exception as e:
+            self.console.print(
+                f"[yellow]⚠️  Error checking crackerjack updates: {e}[/yellow]"
+            )
+
     def _clean_project(self, options: t.Any) -> None:
         assert self.code_cleaner is not None
         if options.clean:
@@ -3002,152 +2563,608 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
         except (OSError, PermissionError):
             return "medium"
 
-    def _calculate_test_metrics(self, test_files: list[Path]) -> tuple[int, int]:
-        total_test_size = 0
-        slow_tests = 0
-        for test_file in test_files:
+    def _calculate_test_metrics(self, test_files: list[Path]) -> tuple[int, int]:
+        total_test_size = 0
+        slow_tests = 0
+        for test_file in test_files:
+            try:
+                size = test_file.stat().st_size
+                total_test_size += size
+                if size > 30_000 or "integration" in test_file.name.lower():
+                    slow_tests += 1
+            except (OSError, PermissionError):
+                continue
+        return total_test_size, slow_tests
+
+    def _determine_test_complexity(
+        self, test_count: int, avg_size: float, slow_ratio: float
+    ) -> str:
+        if test_count > 100 or avg_size > 25_000 or slow_ratio > 0.4:
+            return "high"
+        elif test_count > 50 or avg_size > 15_000 or slow_ratio > 0.2:
+            return "medium"
+        return "low"
+
+    def _analyze_test_workload(self) -> dict[str, t.Any]:
+        try:
+            test_files = self._get_cached_files_with_mtime("test_*.py")
+            py_files = self._get_cached_files_with_mtime("*.py")
+            total_test_size, slow_tests = self._calculate_test_metrics(test_files)
+            avg_test_size = total_test_size / len(test_files) if test_files else 0
+            slow_test_ratio = slow_tests / len(test_files) if test_files else 0
+            complexity = self._determine_test_complexity(
+                len(test_files), avg_test_size, slow_test_ratio
+            )
+            return {
+                "total_files": len(py_files),
+                "test_files": len(test_files),
+                "total_test_size": total_test_size,
+                "avg_test_size": avg_test_size,
+                "slow_tests": slow_tests,
+                "slow_test_ratio": slow_test_ratio,
+                "complexity": complexity,
+            }
+        except (OSError, PermissionError):
+            return {"complexity": "medium", "total_files": 0, "test_files": 0}
+
+    def _calculate_optimal_test_workers(self, workload: dict[str, t.Any]) -> int:
+        import os
+
+        cpu_count = os.cpu_count() or 4
+        if workload["complexity"] == "high":
+            return min(cpu_count // 3, 2)
+        elif workload["complexity"] == "medium":
+            return min(cpu_count // 2, 4)
+        return min(cpu_count, 8)
+
+    def _print_ai_agent_files(self, options: t.Any) -> None:
+        if getattr(options, "ai_agent", False):
+            self.console.print(
+                "[bold bright_black]→ Structured test results: test-results.xml[/bold bright_black]"
+            )
+            self.console.print(
+                "[bold bright_black]→ Coverage report: coverage.json[/bold bright_black]"
+            )
+            if options.benchmark or options.benchmark_regression:
+                self.console.print(
+                    "[bold bright_black]→ Benchmark results: benchmark.json[/bold bright_black]"
+                )
+
+    def _handle_test_failure(self, result: t.Any, options: t.Any) -> None:
+        if result.stderr:
+            self.console.print(result.stderr)
+        self.console.print(
+            "\n\n[bold bright_red]❌ Tests failed. Please fix errors.[/bold bright_red]\n"
+        )
+        self._print_ai_agent_files(options)
+        raise SystemExit(1)
+
+    def _handle_test_success(self, options: t.Any) -> None:
+        self.console.print(
+            "\n\n[bold bright_green]🏆 Tests passed successfully![/bold bright_green]\n"
+        )
+        self._print_ai_agent_files(options)
+
+    def _run_tests(self, options: t.Any) -> None:
+        if not options.test:
+            return
+        self.console.print("\n" + "-" * 80)
+        self.console.print(
+            "[bold bright_green]🧪 TESTING[/bold bright_green] [bold bright_white]Executing test suite[/bold bright_white]"
+        )
+        self.console.print("-" * 80 + "\n")
+        test_command = self._prepare_pytest_command(options)
+        result = self.execute_command(test_command, capture_output=True, text=True)
+        if result.stdout:
+            self.console.print(result.stdout)
+        if result.returncode > 0:
+            self._handle_test_failure(result, options)
+        else:
+            self._handle_test_success(options)
+
+    async def _run_tests_async(self, options: t.Any) -> None:
+        if not options.test:
+            return
+        self.console.print("\n" + "-" * 80)
+        self.console.print(
+            "[bold bright_green]🧪 TESTING[/bold bright_green] [bold bright_white]Executing test suite (async optimized)[/bold bright_white]"
+        )
+        self.console.print("-" * 80 + "\n")
+        test_command = self._prepare_pytest_command(options)
+        result = await self.execute_command_async(test_command)
+        if result.stdout:
+            self.console.print(result.stdout)
+        if result.returncode > 0:
+            self._handle_test_failure(result, options)
+        else:
+            self._handle_test_success(options)
+
+    def _prompt_version_selection(self) -> str:
+        from rich.prompt import Prompt
+
+        if self.options and getattr(self.options, "ai_agent", False):
+            self.console.print(
+                "[dim]AI agent mode: defaulting to patch version bump[/dim]"
+            )
+            return "patch"
+        self.console.print(
+            "\n[bold bright_yellow]📦 VERSION SELECTION[/bold bright_yellow]"
+        )
+        self.console.print("[dim]Select the type of version bump to perform:[/dim]\n")
+        choices = {
+            "1": ("patch", "Bug fixes and minor changes (0.1.0 → 0.1.1)"),
+            "2": ("minor", "New features, backwards compatible (0.1.0 → 0.2.0)"),
+            "3": ("major", "Breaking changes, major updates (0.1.0 → 1.0.0)"),
+        }
+        for key, (bump_type, description) in choices.items():
+            self.console.print(
+                f"  [bold bright_cyan]{key}[/bold bright_cyan] {bump_type:<6} - {description}"
+            )
+        while True:
+            choice = Prompt.ask(
+                "\n[bold]Select version bump type",
+                choices=list(choices.keys()),
+                default="1",
+                show_choices=False,
+            )
+            if choice in choices:
+                selected_type = choices[choice][0]
+                self.console.print(
+                    f"[green]✓ Selected: {selected_type} version bump[/green]"
+                )
+                return selected_type
+            else:
+                self.console.print(
+                    "[red]Invalid choice. Please select 1, 2, or 3.[/red]"
+                )
+
+    def _bump_version(self, options: OptionsProtocol) -> None:
+        if options.publish and str(options.publish) == "interactive":
+            return self._handle_interactive_version_selection(options)
+        for option in (options.publish, options.bump):
+            if option:
+                version_type = str(option)
+                if self._has_version_been_bumped(version_type):
+                    self._display_version_already_bumped_message(version_type)
+                    return
+                self._display_version_bump_message(option)
+                if not self._confirm_version_bump_if_needed(option, version_type):
+                    return
+                self.execute_command(["uv", "version", "--bump", option])
+                self._mark_version_bumped(version_type)
+                if not options.no_git_tags:
+                    self._create_git_tag()
+                break
+
+    def _handle_interactive_version_selection(self, options: OptionsProtocol) -> None:
+        selected_version = self._prompt_version_selection()
+        from crackerjack.__main__ import BumpOption
+
+        options_dict = vars(options).copy()
+        options_dict["publish"] = BumpOption(selected_version)
+        from types import SimpleNamespace
+
+        temp_options = SimpleNamespace(**options_dict)
+
+        return self._bump_version(temp_options)  # type: ignore[arg-type]
+
+    def _display_version_already_bumped_message(self, version_type: str) -> None:
+        self.console.print("\n" + "-" * 80)
+        self.console.print(
+            f"[bold yellow]📦 VERSION[/bold yellow] [bold bright_white]Version already bumped ({version_type}), skipping to avoid duplicate bump[/bold bright_white]"
+        )
+        self.console.print("-" * 80 + "\n")
+
+    def _display_version_bump_message(self, option: t.Any) -> None:
+        self.console.print("\n" + "-" * 80)
+        self.console.print(
+            f"[bold bright_magenta]📦 VERSION[/bold bright_magenta] [bold bright_white]Bumping {option} version[/bold bright_white]"
+        )
+        self.console.print("-" * 80 + "\n")
+
+    def _confirm_version_bump_if_needed(self, option: t.Any, version_type: str) -> bool:
+        if version_type in ("minor", "major"):
+            from rich.prompt import Confirm
+
+            if not Confirm.ask(
+                f"Are you sure you want to bump the {option} version?",
+                default=False,
+            ):
+                self.console.print(
+                    f"[bold yellow]⏭️  Skipping {option} version bump[/bold yellow]"
+                )
+                return False
+        return True
+
+    def _validate_authentication_setup(self) -> None:
+        import os
+        import shutil
+
+        keyring_provider = self._get_keyring_provider()
+        has_publish_token = bool(os.environ.get("UV_PUBLISH_TOKEN"))
+        has_keyring = shutil.which("keyring") is not None
+        self.console.print("[dim]🔐 Validating authentication setup...[/dim]")
+        if has_publish_token:
+            self._handle_publish_token_found()
+            return
+        if keyring_provider == "subprocess" and has_keyring:
+            self._handle_keyring_validation()
+            return
+        if keyring_provider == "subprocess" and not has_keyring:
+            self._handle_missing_keyring()
+        if not keyring_provider:
+            self._handle_no_keyring_provider()
+
+    def _handle_publish_token_found(self) -> None:
+        self.console.print(
+            "[dim]  ✅ UV_PUBLISH_TOKEN environment variable found[/dim]"
+        )
+
+    def _handle_keyring_validation(self) -> None:
+        self.console.print(
+            "[dim]  ✅ Keyring provider configured and keyring executable found[/dim]"
+        )
+        try:
+            result = self.execute_command(
+                ["keyring", "get", "https://upload.pypi.org/legacy/", "__token__"],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                self.console.print("[dim]  ✅ PyPI token found in keyring[/dim]")
+            else:
+                self.console.print(
+                    "[yellow]  ⚠️  No PyPI token found in keyring - will prompt during publish[/yellow]"
+                )
+        except Exception:
+            self.console.print(
+                "[yellow]  ⚠️  Could not check keyring - will attempt publish anyway[/yellow]"
+            )
+
+    def _handle_missing_keyring(self) -> None:
+        if not (self.options and getattr(self.options, "ai_agent", False)):
+            self.console.print(
+                "[yellow]  ⚠️  Keyring provider set to 'subprocess' but keyring executable not found[/yellow]"
+            )
+            self.console.print(
+                "[yellow]      Install keyring: uv tool install keyring[/yellow]"
+            )
+
+    def _handle_no_keyring_provider(self) -> None:
+        if not (self.options and getattr(self.options, "ai_agent", False)):
+            self.console.print(
+                "[yellow]  ⚠️  No keyring provider configured and no UV_PUBLISH_TOKEN set[/yellow]"
+            )
+
+    def _get_keyring_provider(self) -> str | None:
+        import os
+        import tomllib
+        from pathlib import Path
+
+        env_provider = os.environ.get("UV_KEYRING_PROVIDER")
+        if env_provider:
+            return env_provider
+        for config_file in ("pyproject.toml", "uv.toml"):
+            config_path = Path(config_file)
+            if config_path.exists():
+                try:
+                    with config_path.open("rb") as f:
+                        config = tomllib.load(f)
+                    return config.get("tool", {}).get("uv", {}).get("keyring-provider")
+                except Exception:
+                    continue
+
+        return None
+
+    def _build_publish_command(self) -> list[str]:
+        import os
+
+        cmd = ["uv", "publish"]
+        publish_token = os.environ.get("UV_PUBLISH_TOKEN")
+        if publish_token:
+            cmd.extend(["--token", publish_token])
+        keyring_provider = self._get_keyring_provider()
+        if keyring_provider:
+            cmd.extend(["--keyring-provider", keyring_provider])
+
+        return cmd
+
+    def _publish_with_retry(self) -> None:
+        max_retries = 2
+        for attempt in range(max_retries):
             try:
-                size = test_file.stat().st_size
-                total_test_size += size
-                if size > 30_000 or "integration" in test_file.name.lower():
-                    slow_tests += 1
-            except (OSError, PermissionError):
-                continue
-        return total_test_size, slow_tests
+                result = self._attempt_publish()
+                if result.returncode == 0:
+                    self._verify_pypi_upload()
+                    return
+                if not self._handle_publish_failure(result, attempt, max_retries):
+                    raise SystemExit(1)
+            except SystemExit:
+                if attempt < max_retries - 1:
+                    continue
+                raise
 
-    def _determine_test_complexity(
-        self, test_count: int, avg_size: float, slow_ratio: float
-    ) -> str:
-        if test_count > 100 or avg_size > 25_000 or slow_ratio > 0.4:
-            return "high"
-        elif test_count > 50 or avg_size > 15_000 or slow_ratio > 0.2:
-            return "medium"
-        return "low"
+    def _attempt_publish(self) -> "subprocess.CompletedProcess[str]":
+        self._validate_authentication_setup()
+        publish_cmd = self._build_publish_command()
+        self.console.print("[dim]📤 Uploading package to PyPI...[/dim]")
+        import subprocess
+        import time
+        from threading import Thread
 
-    def _analyze_test_workload(self) -> dict[str, t.Any]:
-        try:
-            test_files = self._get_cached_files_with_mtime("test_*.py")
-            py_files = self._get_cached_files_with_mtime("*.py")
-            total_test_size, slow_tests = self._calculate_test_metrics(test_files)
-            avg_test_size = total_test_size / len(test_files) if test_files else 0
-            slow_test_ratio = slow_tests / len(test_files) if test_files else 0
-            complexity = self._determine_test_complexity(
-                len(test_files), avg_test_size, slow_test_ratio
-            )
-            return {
-                "total_files": len(py_files),
-                "test_files": len(test_files),
-                "total_test_size": total_test_size,
-                "avg_test_size": avg_test_size,
-                "slow_tests": slow_tests,
-                "slow_test_ratio": slow_test_ratio,
-                "complexity": complexity,
-            }
-        except (OSError, PermissionError):
-            return {"complexity": "medium", "total_files": 0, "test_files": 0}
+        from rich.live import Live
+        from rich.spinner import Spinner
 
-    def _calculate_optimal_test_workers(self, workload: dict[str, t.Any]) -> int:
-        import os
+        result: subprocess.CompletedProcess[str] | None = None
+        start_time = time.time()
 
-        cpu_count = os.cpu_count() or 4
-        if workload["complexity"] == "high":
-            return min(cpu_count // 3, 2)
-        elif workload["complexity"] == "medium":
-            return min(cpu_count // 2, 4)
-        return min(cpu_count, 8)
+        def run_publish() -> None:
+            nonlocal result
+            result = self.execute_command(publish_cmd, capture_output=True, text=True)
 
-    def _print_ai_agent_files(self, options: t.Any) -> None:
-        if getattr(options, "ai_agent", False):
+        publish_thread = Thread(target=run_publish)
+        publish_thread.start()
+
+        elapsed_time = 0
+        while publish_thread.is_alive():
+            elapsed_time = time.time() - start_time
+
+            if elapsed_time < 5:
+                text = "[dim]📤 Uploading to PyPI...[/dim]"
+            elif elapsed_time < 15:
+                text = "[dim]📤 Uploading to PyPI... (this may take a moment)[/dim]"
+            else:
+                text = "[dim]📤 Uploading to PyPI... (large package or slow connection)[/dim]"
+
+            spinner = Spinner("dots", text=text)
+            with Live(spinner, refresh_per_second=10, transient=True):
+                time.sleep(0.5)
+
+            if not publish_thread.is_alive():
+                break
+
+        publish_thread.join()
+
+        elapsed_time = time.time() - start_time
+
+        if result and result.returncode == 0:
             self.console.print(
-                "[bold bright_black]→ Structured test results: test-results.xml[/bold bright_black]"
+                f"[green]✅ Package uploaded successfully! ({elapsed_time:.1f}s)[/green]"
             )
-            self.console.print(
-                "[bold bright_black]→ Coverage report: coverage.json[/bold bright_black]"
+        elif result and result.returncode != 0:
+            self.console.print(f"[red]❌ Upload failed after {elapsed_time:.1f}s[/red]")
+            if result.stdout:
+                self.console.print(f"[dim]stdout: {result.stdout}[/dim]")
+            if result.stderr:
+                self.console.print(f"[red]stderr: {result.stderr}[/red]")
+
+        if result is None:
+            return subprocess.CompletedProcess(
+                args=publish_cmd,
+                returncode=1,
+                stdout="",
+                stderr="Thread execution failed",
             )
-            if options.benchmark or options.benchmark_regression:
-                self.console.print(
-                    "[bold bright_black]→ Benchmark results: benchmark.json[/bold bright_black]"
-                )
 
-    def _handle_test_failure(self, result: t.Any, options: t.Any) -> None:
-        if result.stderr:
-            self.console.print(result.stderr)
+        return result
+
+    def _verify_pypi_upload(self) -> None:
+        if self.options and getattr(self.options, "ai_agent", False):
+            return
+        import time
+
+        package_name = self._get_package_name()
+        current_version = self._get_current_version()
         self.console.print(
-            "\n\n[bold bright_red]❌ Tests failed. Please fix errors.[/bold bright_red]\n"
+            f"[dim]🔍 Verifying upload of {package_name} v{current_version}...[/dim]"
         )
-        self._print_ai_agent_files(options)
-        raise SystemExit(1)
+        time.sleep(2)
+        self._retry_pypi_verification(package_name, current_version)
 
-    def _handle_test_success(self, options: t.Any) -> None:
+    def _retry_pypi_verification(self, package_name: str, current_version: str) -> None:
+        import time
+
+        max_attempts = 3
+        for attempt in range(max_attempts):
+            try:
+                if self._check_pypi_package_exists(package_name, current_version):
+                    self._show_pypi_success(package_name, current_version)
+                    return
+                if attempt < max_attempts - 1:
+                    self._show_pypi_retry_message(attempt, max_attempts)
+                    time.sleep(5)
+                    continue
+                else:
+                    self._show_pypi_not_visible(package_name, current_version)
+                    return
+            except Exception as e:
+                if attempt < max_attempts - 1:
+                    self._show_pypi_error_retry(attempt, max_attempts, e)
+                    time.sleep(5)
+                    continue
+                else:
+                    self._show_pypi_final_error(package_name, current_version, e)
+                    return
+
+    def _check_pypi_package_exists(
+        self, package_name: str, current_version: str
+    ) -> bool:
+        import json
+        import urllib.error
+        import urllib.request
+
+        url = f"https://pypi.org/pypi/{package_name}/{current_version}/json"
+        try:
+            with urllib.request.urlopen(url, timeout=10) as response:  # nosec B310
+                data = json.loads(response.read().decode())
+                return data.get("info", {}).get("version") == current_version
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                return False
+            raise
+
+    def _show_pypi_success(self, package_name: str, current_version: str) -> None:
         self.console.print(
-            "\n\n[bold bright_green]✅ Tests passed successfully![/bold bright_green]\n"
+            f"[green]✅ Verified: {package_name} v{current_version} is available on PyPI![/green]"
         )
-        self._print_ai_agent_files(options)
+        pypi_url = f"https://pypi.org/project/{package_name}/{current_version}/"
+        self.console.print(f"[dim]   📦 Package URL: {pypi_url}[/dim]")
 
-    def _run_tests(self, options: t.Any) -> None:
-        if not options.test:
-            return
-        self.console.print("\n" + "-" * 80)
+    def _show_pypi_retry_message(self, attempt: int, max_attempts: int) -> None:
         self.console.print(
-            "[bold bright_green]🧪 TESTING[/bold bright_green] [bold bright_white]Executing test suite[/bold bright_white]"
+            f"[yellow]⏳ Package not yet available on PyPI (attempt {attempt + 1}/{max_attempts}), retrying...[/yellow]"
         )
-        self.console.print("-" * 80 + "\n")
-        test_command = self._prepare_pytest_command(options)
-        result = self.execute_command(test_command, capture_output=True, text=True)
-        if result.stdout:
-            self.console.print(result.stdout)
-        if result.returncode > 0:
-            self._handle_test_failure(result, options)
-        else:
-            self._handle_test_success(options)
 
-    async def _run_tests_async(self, options: t.Any) -> None:
-        if not options.test:
-            return
-        self.console.print("\n" + "-" * 80)
+    def _show_pypi_not_visible(self, package_name: str, current_version: str) -> None:
         self.console.print(
-            "[bold bright_green]🧪 TESTING[/bold bright_green] [bold bright_white]Executing test suite (async optimized)[/bold bright_white]"
+            "[yellow]⚠️  Package uploaded but not yet visible on PyPI (this is normal)[/yellow]"
         )
-        self.console.print("-" * 80 + "\n")
-        test_command = self._prepare_pytest_command(options)
-        result = await self.execute_command_async(test_command)
-        if result.stdout:
-            self.console.print(result.stdout)
-        if result.returncode > 0:
-            self._handle_test_failure(result, options)
+        self.console.print(
+            f"[dim]   Check later at: https://pypi.org/project/{package_name}/{current_version}/[/dim]"
+        )
+
+    def _show_pypi_error_retry(
+        self, attempt: int, max_attempts: int, error: Exception
+    ) -> None:
+        self.console.print(
+            f"[yellow]⏳ Error checking PyPI (attempt {attempt + 1}/{max_attempts}): {error}[/yellow]"
+        )
+
+    def _show_pypi_final_error(
+        self, package_name: str, current_version: str, error: Exception
+    ) -> None:
+        self.console.print(f"[yellow]⚠️  Could not verify PyPI upload: {error}[/yellow]")
+        self.console.print(
+            f"[dim]   Check manually at: https://pypi.org/project/{package_name}/{current_version}/[/dim]"
+        )
+
+    def _get_package_name(self) -> str:
+        import tomllib
+        from pathlib import Path
+
+        pyproject_path = Path("pyproject.toml")
+        if pyproject_path.exists():
+            with pyproject_path.open("rb") as f:
+                data = tomllib.load(f)
+                return data.get("project", {}).get("name", "unknown")
+        return "unknown"
+
+    def _handle_publish_failure(
+        self, result: "subprocess.CompletedProcess[str]", attempt: int, max_retries: int
+    ) -> bool:
+        if self._is_auth_error(result):
+            return self._handle_auth_error(attempt, max_retries)
         else:
-            self._handle_test_success(options)
+            self._handle_non_auth_error(result)
+            return False
 
-    def _bump_version(self, options: OptionsProtocol) -> None:
-        for option in (options.publish, options.bump):
-            if option:
-                version_type = str(option)
-                if self._has_version_been_bumped(version_type):
-                    self.console.print("\n" + "-" * 80)
+    def _handle_auth_error(self, attempt: int, max_retries: int) -> bool:
+        if attempt < max_retries - 1:
+            self.console.print(
+                f"[yellow]⚠️  Authentication failed (attempt {attempt + 1}/{max_retries})[/yellow]"
+            )
+            return self._prompt_for_token()
+        self._display_authentication_help()
+        return False
+
+    def _handle_non_auth_error(
+        self, result: "subprocess.CompletedProcess[str]"
+    ) -> None:
+        self.console.print(result.stdout)
+        self.console.print(result.stderr)
+
+    def _is_auth_error(self, result: "subprocess.CompletedProcess[str]") -> bool:
+        error_text = (result.stdout + result.stderr).lower()
+        auth_indicators = (
+            "authentication",
+            "unauthorized",
+            "403",
+            "401",
+            "invalid credentials",
+            "token",
+            "password",
+            "username",
+        )
+        return any(indicator in error_text for indicator in auth_indicators)
+
+    def _prompt_for_token(self) -> bool:
+        import getpass
+        import os
+        import shutil
+
+        if self.options and getattr(self.options, "ai_agent", False):
+            return False
+        self.console.print("\n[bold yellow]🔐 PyPI Token Required[/bold yellow]")
+        self.console.print(
+            "[dim]Please enter your PyPI token (starts with 'pypi-'):[/dim]"
+        )
+        try:
+            token = getpass.getpass("PyPI Token: ")
+            if not token or not token.startswith("pypi-"):
+                self.console.print(
+                    "[red]❌ Invalid token format. Token must start with 'pypi-'[/red]"
+                )
+                return False
+            if shutil.which("keyring"):
+                try:
+                    result = self.execute_command(
+                        [
+                            "keyring",
+                            "set",
+                            "https://upload.pypi.org/legacy/",
+                            "__token__",
+                        ],
+                        input=token,
+                        capture_output=True,
+                        text=True,
+                    )
+                    if result.returncode == 0:
+                        self.console.print("[green]✅ Token stored in keyring[/green]")
+                    else:
+                        os.environ["UV_PUBLISH_TOKEN"] = token
+                        self.console.print(
+                            "[yellow]⚠️  Keyring storage failed, using environment variable[/yellow]"
+                        )
+                except Exception:
+                    os.environ["UV_PUBLISH_TOKEN"] = token
                     self.console.print(
-                        f"[bold yellow]📦 VERSION[/bold yellow] [bold bright_white]Version already bumped ({version_type}), skipping to avoid duplicate bump[/bold bright_white]"
+                        "[yellow]⚠️  Keyring storage failed, using environment variable[/yellow]"
                     )
-                    self.console.print("-" * 80 + "\n")
-                    return
-                self.console.print("\n" + "-" * 80)
+            else:
+                os.environ["UV_PUBLISH_TOKEN"] = token
                 self.console.print(
-                    f"[bold bright_magenta]📦 VERSION[/bold bright_magenta] [bold bright_white]Bumping {option} version[/bold bright_white]"
+                    "[yellow]⚠️  Keyring not available, using environment variable[/yellow]"
                 )
-                self.console.print("-" * 80 + "\n")
-                if version_type in ("minor", "major"):
-                    from rich.prompt import Confirm
 
-                    if not Confirm.ask(
-                        f"Are you sure you want to bump the {option} version?",
-                        default=False,
-                    ):
-                        self.console.print(
-                            f"[bold yellow]⏭️  Skipping {option} version bump[/bold yellow]"
-                        )
-                        return
-                self.execute_command(["uv", "version", "--bump", option])
-                self._mark_version_bumped(version_type)
-                break
+            return True
+        except KeyboardInterrupt:
+            self.console.print("\n[yellow]⚠️  Token entry cancelled[/yellow]")
+            return False
+        except Exception as e:
+            self.console.print(f"[red]❌ Error storing token: {e}[/red]")
+            return False
+
+    def _display_authentication_help(self) -> None:
+        self.console.print(
+            "\n[bold bright_red]❌ Publish failed. Run crackerjack again to retry publishing without re-bumping version.[/bold bright_red]"
+        )
+        if not (self.options and getattr(self.options, "ai_agent", False)):
+            self.console.print("\n[bold yellow]🔐 Authentication Help:[/bold yellow]")
+            self.console.print("  [dim]To fix authentication issues, you can:[/dim]")
+            self.console.print(
+                "  [dim]1. Set PyPI token: export UV_PUBLISH_TOKEN=pypi-your-token-here[/dim]"
+            )
+            self.console.print(
+                "  [dim]2. Install keyring: uv tool install keyring[/dim]"
+            )
+            self.console.print(
+                "  [dim]3. Store token in keyring: keyring set https://upload.pypi.org/legacy/ __token__[/dim]"
+            )
+            self.console.print(
+                "  [dim]4. Ensure keyring-provider is set in pyproject.toml:[/dim]"
+            )
+            self.console.print("  [dim]     [tool.uv][/dim]")
+            self.console.print('  [dim]     keyring-provider = "subprocess"[/dim]')
 
     def _publish_project(self, options: OptionsProtocol) -> None:
         if options.publish:
@@ -3156,28 +3173,187 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
                 "[bold bright_cyan]🚀 PUBLISH[/bold bright_cyan] [bold bright_white]Building and publishing package[/bold bright_white]"
             )
             self.console.print("-" * 80 + "\n")
-            build = self.execute_command(
-                ["uv", "build"], capture_output=True, text=True
-            )
-            self.console.print(build.stdout)
-            if build.returncode > 0:
-                self.console.print(build.stderr)
-                self.console.print(
-                    "[bold bright_red]❌ Build failed. Please fix errors.[/bold bright_red]"
-                )
-                raise SystemExit(1)
-            try:
-                self.execute_command(["uv", "publish"])
-                self._mark_publish_completed()
-                self._clear_state()
-                self.console.print(
-                    "\n[bold bright_green]✅ Package published successfully![/bold bright_green]"
+            if not options.skip_version_check:
+                if not self._verify_version_consistency():
+                    self.console.print(
+                        "[bold red]❌ Publishing aborted due to version mismatch. Please ensure pyproject.toml version matches git tag.[/bold red]"
+                    )
+                    raise SystemExit(1)
+            state = self._get_state()
+            if not state.get("build_completed", False):
+                build = self.execute_command(
+                    ["uv", "build"], capture_output=True, text=True
                 )
-            except SystemExit:
+                self.console.print(build.stdout)
+                if build.returncode > 0:
+                    self.console.print(build.stderr)
+                    self.console.print(
+                        "[bold bright_red]❌ Build failed. Please fix errors.[/bold bright_red]"
+                    )
+                    raise SystemExit(1)
+                state["build_completed"] = True
+                self._save_state(state)
+            else:
                 self.console.print(
-                    "\n[bold bright_red]❌ Publish failed. Run crackerjack again to retry publishing without re-bumping version.[/bold bright_red]"
+                    "[dim]📦 Using existing build artifacts (retry mode)[/dim]"
                 )
-                raise
+            self._publish_with_retry()
+            self._mark_publish_completed()
+            self._clear_state()
+            self.console.print(
+                "\n[bold bright_green]🏆 Package published successfully![/bold bright_green]"
+            )
+
+    def _analyze_git_changes(self) -> dict[str, t.Any]:
+        diff_result = self._get_git_diff_output()
+        changes = self._parse_git_diff_output(diff_result)
+        changes["stats"] = self._get_git_stats()
+        return changes
+
+    def _get_git_diff_output(self) -> t.Any:
+        diff_cmd = ["git", "diff", "--cached", "--name-status"]
+        diff_result = self.execute_command(diff_cmd, capture_output=True, text=True)
+        if not diff_result.stdout and diff_result.returncode == 0:
+            diff_cmd = ["git", "diff", "--name-status"]
+            diff_result = self.execute_command(diff_cmd, capture_output=True, text=True)
+        return diff_result
+
+    def _parse_git_diff_output(self, diff_result: t.Any) -> dict[str, t.Any]:
+        changes = {
+            "added": [],
+            "modified": [],
+            "deleted": [],
+            "renamed": [],
+            "total_changes": 0,
+        }
+        if diff_result.returncode == 0 and diff_result.stdout:
+            self._process_diff_lines(diff_result.stdout, changes)
+        return changes
+
+    def _process_diff_lines(self, stdout: str, changes: dict[str, t.Any]) -> None:
+        for line in stdout.strip().split("\n"):
+            if not line:
+                continue
+            self._process_single_diff_line(line, changes)
+
+    def _process_single_diff_line(self, line: str, changes: dict[str, t.Any]) -> None:
+        parts = line.split("\t")
+        if len(parts) >= 2:
+            status, filename = parts[0], parts[1]
+            self._categorize_file_change(status, filename, parts, changes)
+            changes["total_changes"] += 1
+
+    def _categorize_file_change(
+        self, status: str, filename: str, parts: list[str], changes: dict[str, t.Any]
+    ) -> None:
+        if status == "A":
+            changes["added"].append(filename)
+        elif status == "M":
+            changes["modified"].append(filename)
+        elif status == "D":
+            changes["deleted"].append(filename)
+        elif status.startswith("R"):
+            if len(parts) >= 3:
+                changes["renamed"].append((parts[1], parts[2]))
+            else:
+                changes["renamed"].append((filename, "unknown"))
+
+    def _get_git_stats(self) -> str:
+        stat_cmd = ["git", "diff", "--cached", "--stat"]
+        stat_result = self.execute_command(stat_cmd, capture_output=True, text=True)
+        if not stat_result.stdout and stat_result.returncode == 0:
+            stat_cmd = ["git", "diff", "--stat"]
+            stat_result = self.execute_command(stat_cmd, capture_output=True, text=True)
+        return stat_result.stdout if stat_result.returncode == 0 else ""
+
+    def _categorize_changes(self, changes: dict[str, t.Any]) -> dict[str, list[str]]:
+        categories = {
+            "docs": [],
+            "tests": [],
+            "config": [],
+            "core": [],
+            "ci": [],
+            "deps": [],
+        }
+        file_patterns = {
+            "docs": ["README.md", "CLAUDE.md", "RULES.md", "docs/", ".md"],
+            "tests": ["test_", "_test.py", "tests/", "conftest.py"],
+            "config": ["pyproject.toml", ".yaml", ".yml", ".json", ".gitignore"],
+            "ci": [".github/", "ci/", ".pre-commit"],
+            "deps": ["requirements", "pyproject.toml", "uv.lock"],
+        }
+        for file_list in ("added", "modified", "deleted"):
+            for filename in changes.get(file_list, []):
+                categorized = False
+                for category, patterns in file_patterns.items():
+                    if any(pattern in filename for pattern in patterns):
+                        categories[category].append(filename)
+                        categorized = True
+                        break
+                if not categorized:
+                    categories["core"].append(filename)
+
+        return categories
+
+    def _get_primary_changes(self, categories: dict[str, list[str]]) -> list[str]:
+        primary_changes = []
+        category_mapping = [
+            ("core", "core functionality"),
+            ("tests", "tests"),
+            ("docs", "documentation"),
+            ("config", "configuration"),
+            ("deps", "dependencies"),
+        ]
+        for key, label in category_mapping:
+            if categories[key]:
+                primary_changes.append(label)
+
+        return primary_changes or ["project files"]
+
+    def _determine_primary_action(self, changes: dict[str, t.Any]) -> str:
+        added_count = len(changes["added"])
+        modified_count = len(changes["modified"])
+        deleted_count = len(changes["deleted"])
+        if added_count > modified_count + deleted_count:
+            return "Add"
+        elif deleted_count > modified_count + added_count:
+            return "Remove"
+        elif changes["renamed"]:
+            return "Refactor"
+        return "Update"
+
+    def _generate_body_lines(self, changes: dict[str, t.Any]) -> list[str]:
+        body_lines = []
+        change_types = [
+            ("added", "Added"),
+            ("modified", "Modified"),
+            ("deleted", "Deleted"),
+            ("renamed", "Renamed"),
+        ]
+        for change_type, label in change_types:
+            items = changes.get(change_type, [])
+            if items:
+                count = len(items)
+                body_lines.append(f"- {label} {count} file(s)")
+                if change_type not in ("deleted", "renamed"):
+                    for file in items[:3]:
+                        body_lines.append(f"  * {file}")
+                    if count > 3:
+                        body_lines.append(f"  * ... and {count - 3} more")
+
+        return body_lines
+
+    def _generate_commit_message(self, changes: dict[str, t.Any]) -> str:
+        if changes["total_changes"] == 0:
+            return "Update project files"
+        categories = self._categorize_changes(changes)
+        primary_changes = self._get_primary_changes(categories)
+        primary_action = self._determine_primary_action(changes)
+        commit_subject = f"{primary_action} {' and '.join(primary_changes[:2])}"
+        body_lines = self._generate_body_lines(changes)
+        if body_lines:
+            return f"{commit_subject}\n\n" + "\n".join(body_lines)
+        return commit_subject
 
     def _commit_and_push(self, options: OptionsProtocol) -> None:
         if options.commit:
@@ -3186,23 +3362,73 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
                 "[bold bright_white]📝 COMMIT[/bold bright_white] [bold bright_white]Saving changes to git[/bold bright_white]"
             )
             self.console.print("-" * 80 + "\n")
-            commit_msg = input("\nCommit message: ")
+            if not options.skip_version_check:
+                if not self._verify_version_consistency():
+                    self.console.print(
+                        "[bold red]❌ Commit aborted due to version mismatch. Please ensure pyproject.toml version matches git tag.[/bold red]"
+                    )
+                    raise SystemExit(1)
+            changes = self._analyze_git_changes()
+            if changes["total_changes"] > 0:
+                self.console.print("[dim]🔍 Analyzing changes...[/dim]\n")
+                if changes["stats"]:
+                    self.console.print(changes["stats"])
+                suggested_msg = self._generate_commit_message(changes)
+                self.console.print(
+                    "\n[bold cyan]📋 Suggested commit message:[/bold cyan]"
+                )
+                self.console.print(f"[cyan]{suggested_msg}[/cyan]\n")
+                user_choice = (
+                    input("Use suggested message? [Y/n/e to edit]: ").strip().lower()
+                )
+                if user_choice in ("", "y"):
+                    commit_msg = suggested_msg
+                elif user_choice == "e":
+                    import os
+                    import tempfile
+
+                    with tempfile.NamedTemporaryFile(
+                        mode="w", suffix=".txt", delete=False
+                    ) as f:
+                        f.write(suggested_msg)
+                        temp_path = f.name
+                    editor = os.environ.get("EDITOR", "vi")
+                    self.execute_command([editor, temp_path])
+                    with open(temp_path) as f:
+                        commit_msg = f.read().strip()
+                    Path(temp_path).unlink()
+                else:
+                    commit_msg = input("\nEnter custom commit message: ")
+            else:
+                commit_msg = input("\nCommit message: ")
             self.execute_command(
                 ["git", "commit", "-m", commit_msg, "--no-verify", "--", "."]
             )
             self.execute_command(["git", "push", "origin", "main", "--no-verify"])
+            self._push_git_tags()
 
     def _update_precommit(self, options: OptionsProtocol) -> None:
         if options.update_precommit:
+            self.console.print(
+                "\n[bold yellow]⚠️  DEPRECATION WARNING[/bold yellow]: The --update-precommit (-u) flag is deprecated.\n"
+                "   Pre-commit hooks are now updated automatically on a weekly basis.\n"
+                "   This manual update will still work but is no longer needed.\n"
+            )
             self.console.print("\n" + "-" * 80)
             self.console.print(
                 "[bold bright_blue]🔄 UPDATE[/bold bright_blue] [bold bright_white]Updating pre-commit hooks[/bold bright_white]"
             )
             self.console.print("-" * 80 + "\n")
             if self.pkg_path.stem == "crackerjack":
-                update_cmd = ["uv", "run", "pre-commit", "autoupdate"]
-                if getattr(options, "ai_agent", False):
-                    update_cmd.extend(["-c", ".pre-commit-config-ai.yaml"])
+                config_path = self.project_manager._select_precommit_config()
+                update_cmd = [
+                    "uv",
+                    "run",
+                    "pre-commit",
+                    "autoupdate",
+                    "-c",
+                    config_path,
+                ]
                 self.execute_command(update_cmd)
             else:
                 self.project_manager.update_precommit_hooks()
@@ -3215,7 +3441,8 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
             )
             self.console.print("-" * 80 + "\n")
             self.config_manager.copy_documentation_templates(
-                force_update=options.force_update_docs
+                force_update=options.force_update_docs,
+                compress_docs=options.compress_docs,
             )
 
     def execute_command(
@@ -3268,6 +3495,7 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
             "[bold bright_magenta]🔍 COMPREHENSIVE QUALITY[/bold bright_magenta] [bold bright_white]Running all quality checks before publish/commit[/bold bright_white]"
         )
         self.console.print("-" * 80 + "\n")
+        config_path = self.project_manager._select_precommit_config()
         cmd = [
             "uv",
             "run",
@@ -3276,7 +3504,7 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
             "--all-files",
             "--hook-stage=manual",
             "-c",
-            ".pre-commit-config.yaml",
+            config_path,
         ]
         result = self.execute_command(cmd)
         if result.returncode > 0:
@@ -3289,7 +3517,7 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
             raise SystemExit(1)
         else:
             self.console.print(
-                "\n[bold bright_green]✅ All comprehensive quality checks passed![/bold bright_green]"
+                "\n[bold bright_green]🏆 All comprehensive quality checks passed![/bold bright_green]"
             )
 
     async def _run_comprehensive_quality_checks_async(
@@ -3314,6 +3542,7 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
         )
         self.console.print("-" * 80 + "\n")
 
+        config_path = self.project_manager._select_precommit_config()
         cmd = [
             "uv",
             "run",
@@ -3322,7 +3551,7 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
             "--all-files",
             "--hook-stage=manual",
             "-c",
-            ".pre-commit-config.yaml",
+            config_path,
         ]
 
         result = await self.execute_command_async(cmd)
@@ -3339,7 +3568,7 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
             raise SystemExit(1)
         else:
             self.console.print(
-                "[bold bright_green]✅ All comprehensive quality checks passed![/bold bright_green]"
+                "[bold bright_green]🏆 All comprehensive quality checks passed![/bold bright_green]"
             )
 
     def _run_tracked_task(
@@ -3358,7 +3587,9 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
 
     def _run_pre_commit_task(self, options: OptionsProtocol) -> None:
         if not options.skip_hooks:
-            if getattr(options, "ai_agent", False):
+            if getattr(options, "comprehensive", False):
+                self._run_comprehensive_hooks()
+            elif getattr(options, "ai_agent", False):
                 self.project_manager.run_pre_commit_with_analysis()
             else:
                 self.project_manager.run_pre_commit()
@@ -3369,6 +3600,33 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
             if self.session_tracker:
                 self.session_tracker.skip_task("pre_commit", "Skipped by user request")
 
+    def _run_comprehensive_hooks(self) -> None:
+        self.console.print("\n" + "-" * 80)
+        self.console.print(
+            "[bold bright_cyan]🔍 HOOKS[/bold bright_cyan] [bold bright_white]Running comprehensive quality checks[/bold bright_white]"
+        )
+        self.console.print("-" * 80 + "\n")
+        stages = ["pre-commit", "pre-push", "manual"]
+        config_path = self.project_manager._select_precommit_config()
+        for stage in stages:
+            self.console.print(f"[dim]Running {stage} stage hooks...[/dim]")
+            cmd = [
+                "uv",
+                "run",
+                "pre-commit",
+                "run",
+                "--all-files",
+                f"--hook-stage={stage}",
+                "-c",
+                config_path,
+            ]
+            result = self.execute_command(cmd)
+            if result.returncode > 0:
+                self.console.print(
+                    f"\n[bold red]❌ {stage} hooks failed. Please fix errors.[/bold red]\n"
+                )
+                raise SystemExit(1)
+
     def _initialize_session_tracking(self, options: OptionsProtocol) -> None:
         if options.resume_from:
             try:
@@ -3429,6 +3687,8 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
             options.test = True
             options.publish = options.all
             options.commit = True
+        if options.comprehensive:
+            options.test = True
         self._run_tracked_task(
             "setup", "Initialize project structure", self._setup_package
         )
@@ -3450,7 +3710,8 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
         self._run_tracked_task(
             "clean_project", "Clean project code", lambda: self._clean_project(options)
         )
-        self.project_manager.options = options
+        if self.project_manager is not None:
+            self.project_manager.options = options
         if not options.skip_hooks:
             self._run_tracked_task(
                 "pre_commit",
@@ -3480,7 +3741,7 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
         )
         self.console.print("\n" + "-" * 80)
         self.console.print(
-            "[bold bright_green]✨ CRACKERJACK COMPLETE[/bold bright_green] [bold bright_white]Workflow completed successfully![/bold bright_white]"
+            "[bold bright_green]🏆 CRACKERJACK COMPLETE[/bold bright_green] [bold bright_white]Workflow completed successfully![/bold bright_white]"
         )
         self.console.print("-" * 80 + "\n")
 
@@ -3496,11 +3757,14 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
             options.test = True
             options.publish = options.all
             options.commit = True
+        if options.comprehensive:
+            options.test = True
         self._setup_package()
         self._update_project(options)
         self._update_precommit(options)
         await self._clean_project_async(options)
-        self.project_manager.options = options
+        if self.project_manager is not None:
+            self.project_manager.options = options
         if not options.skip_hooks:
             if getattr(options, "ai_agent", False):
                 await self.project_manager.run_pre_commit_with_analysis_async()
@@ -3517,7 +3781,7 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
         self._publish_project(options)
         self.console.print("\n" + "-" * 80)
         self.console.print(
-            "[bold bright_green]✨ CRACKERJACK COMPLETE[/bold bright_green] [bold bright_white]Workflow completed successfully![/bold bright_white]"
+            "[bold bright_green]🏆 CRACKERJACK COMPLETE[/bold bright_green] [bold bright_white]Workflow completed successfully![/bold bright_white]"
         )
         self.console.print("-" * 80 + "\n")