velm 0.1.2__py3-none-any.whl

velm/gnosis/wisdom.py

@@ -0,0 +1,25 @@
+
+"""
+=================================================================================
+== THE SACRED GRIMOIRE OF ARCHITECTURAL WISDOM (V-Ω-ETERNAL)                   ==
+=================================================================================
+This scripture is the eternal wellspring of Gnostic wisdom. It contains the
+aphorisms and prophecies that guide the Architect's hand and illuminate the
+final proclamations of the God-Engine.
+=================================================================================
+"""
+
+# The One True, Canonical List of Architectural Wisdom.
+# To teach the engine a new verse, one must only inscribe it here.
+ARCHITECTURAL_QUOTES = [
+    'The code is the law, but the architecture is the spirit.',
+    'Simplicity is the ultimate sophistication.',
+    'Form follows function, but beauty follows truth.',
+    'A sanctum forged in order resists the chaos of entropy.',
+    'First, we shape our tools; thereafter they shape us.',
+    'Gnosis is truth made manifest.',
+    'The purest abstractions are born from the deepest understanding.',
+    'A heresy perceived is a heresy half-healed.',
+    'The cost of an error grows exponentially with its distance from its origin.',
+    'Clarity of intent is the soul of a clean architecture.'
+]

velm/gnostic_instrumentarium.py

@@ -0,0 +1,161 @@
+# Path: scaffold/gnostic_instrumentarium.py
+
+"""
+=================================================================================
+== THE GNOSTIC INSTRUMENTARIUM (V-Ω-ETERNAL. THE PROPHET'S MIND)               ==
+=================================================================================
+This is not a file of code. It is the living, eternal mind of the Gnostic Prophet
+that resides within the Quantum Creator. It is a sacred, extensible Grimoire that
+contains the Gnosis of all known mortal and divine artisans (tools) required to
+conduct the symphonies of creation.
+=================================================================================
+"""
+import os
+import platform
+import shutil
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+# =================================================================================
+# == THE SACRED CONTRACT OF GNOSTIC INSTRUMENTS                                  ==
+# =================================================================================
+#
+# Each verse in this Grimoire is a pure, declarative law with this sacred contract:
+#
+#   "purpose": A luminous scripture explaining the artisan's divine role.
+#
+#   "gaze": A divine lambda that performs a Gaze upon the mortal realm to see
+#           if the artisan is manifest.
+#
+#   "consecration_rites": A vessel containing the sacred edicts for summoning
+#                         the artisan into existence, tailored for each realm.
+# =================================================================================
+
+GNOSTIC_INSTRUMENTARIUM: Dict[str, Dict[str, Any]] = {
+    "git": {
+        "purpose": "The Divine Chronomancer, guardian of a project's history and soul.",
+        "gaze": lambda: shutil.which("git"),
+        "consecration_rites": {
+            "ubuntu/debian": "sudo apt-get install git",
+            "macos": "brew install git",
+            "windows": "choco install git",
+            "manual": "https://git-scm.com/downloads"
+        }
+    },
+    "make": {
+        "purpose": "The Universal Conductor of Rites, the one true altar for all Maestro's Edicts.",
+        "gaze": lambda: shutil.which("make"),
+        "consecration_rites": {
+            "ubuntu/debian": "sudo apt-get install make",
+            "macos": "xcode-select --install",
+            "windows": "choco install make",
+            "manual": "Consult your realm's sacred texts for 'make' or a GNU toolchain."
+        }
+    },
+    "poetry": {
+        "purpose": "The Master Artisan of Pythonic Souls, for dependency management and packaging.",
+        "gaze": lambda: shutil.which("poetry"),
+        "consecration_rites": {
+            "universal": "pip install poetry",
+            "manual": "https://python-poetry.org/docs/#installation"
+        }
+    },
+    "npm": {
+        "purpose": "The Scribe of the Node Cosmos, for managing the souls of JavaScript realities.",
+        "gaze": lambda: shutil.which("npm"),
+        "consecration_rites": {
+            "universal": "Install Node.js & npm from https://nodejs.org/",
+            "windows": "choco install nodejs",
+            "macos": "brew install node"
+        }
+    },
+    "docker": {
+        "purpose": "The Forger of Unbreakable Vessels, the God-Engine of Containerization.",
+        "gaze": lambda: shutil.which("docker"),
+        "consecration_rites": {
+            "universal": "Install Docker Desktop from https://www.docker.com/products/docker-desktop/",
+        }
+    },
+    # The Grimoire is eternal and extensible. New artisans can be added here.
+    "vscode": {
+        "purpose": "The Luminous Editor, the Sanctum of Code.",
+        "gaze": lambda: shutil.which("code"),
+        "consecration_rites": {
+            "windows": "https://code.visualstudio.com/Download", # Manual install link
+            "macos": "https://code.visualstudio.com/Download",
+            "ubuntu/debian": "https://code.visualstudio.com/Download",
+            "manual": "https://code.visualstudio.com/docs/setup/setup-overview"
+        }
+    }
+}
+
+
+def gaze_for_hidden_artisan(tool_key: str) -> Optional[Path]:
+    """
+    =================================================================================
+    == THE GNOSTIC PATHFINDER (V-Ω-DEEP-SCAN)                                      ==
+    =================================================================================
+    Performs a deep search in the probable sanctums of the OS to find a missing
+    artisan that is installed but not in the PATH.
+    """
+    system = platform.system().lower()
+
+    # The Map of Hidden Sanctums
+    SEARCH_PATHS = {
+        "windows": [
+            # VS Code User
+            Path(os.environ.get("LOCALAPPDATA", "")) / "Programs" / "Microsoft VS Code" / "bin" / "code.cmd",
+            # VS Code System
+            Path(os.environ.get("ProgramFiles", "")) / "Microsoft VS Code" / "bin" / "code.cmd",
+            Path(os.environ.get("ProgramFiles(x86)", "")) / "Microsoft VS Code" / "bin" / "code.cmd",
+            # Git
+            Path(os.environ.get("ProgramFiles", "")) / "Git" / "cmd" / "git.exe",
+            # Node
+            Path(os.environ.get("ProgramFiles", "")) / "nodejs" / "npm.cmd",
+        ],
+        "darwin": [  # MacOS
+            Path("/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code"),
+            Path("/usr/local/bin/code"),
+        ],
+        "linux": [
+            Path("/usr/bin/code"),
+            Path("/snap/bin/code"),
+        ]
+    }
+
+    # The Mapping of Tools to Filenames (if different)
+    TOOL_MAP = {
+        "vscode": "code.cmd" if system == "windows" else "code",
+        "code": "code.cmd" if system == "windows" else "code",
+        "git": "git.exe" if system == "windows" else "git",
+        "npm": "npm.cmd" if system == "windows" else "npm",
+    }
+
+    filename = TOOL_MAP.get(tool_key, tool_key)
+
+    # 1. Check standard paths
+    candidates = SEARCH_PATHS.get(system, [])
+    for candidate in candidates:
+        # Check if the path ends with our target tool name
+        if candidate.name.lower() == filename.lower() and candidate.exists():
+            return candidate
+
+    # 2. If still lost, we can try a broader heuristic if needed,
+    # but for now, we stick to known safe locations.
+
+    return None
+
+
+
+
+def get_platform_key() -> str:
+    """A Gnostic Gaze to perceive the Architect's current mortal realm."""
+    system = platform.system().lower()
+    if system == "linux":
+        # A prophecy for a more divine Gaze in the future (e.g., checking /etc/os-release)
+        return "ubuntu/debian"
+    elif system == "darwin":
+        return "macos"
+    elif system == "windows":
+        return "windows"
+    return "manual"

velm/grammar.py

@@ -0,0 +1,160 @@
+# Path: scaffold/grammar.py
+# -------------------------
+
+"""
+=================================================================================
+== THE SACRED GRAMMAR OF FORMS (V-Ω-PERCEPTION-LAYER)                          ==
+=================================================================================
+LIF: 10,000,000,000 (THE ATOMIC TRUTH)
+
+This scripture defines the fundamental regular expressions (Regex) that the
+Gnostic Lexer uses to deconstruct the Architect's Will into atomic units (Tokens).
+
+It serves as the **eyes** of the God-Engine. If a pattern is not inscribed here,
+the Engine cannot perceive it.
+
+### THE HIERARCHY OF PERCEPTION:
+1.  **Block Delimiters:** Multi-line structures must be perceived first to avoid
+    fragmentation.
+2.  **Operators & Sigils:** The verbs of the language (Create, Append, Link).
+3.  **Modifiers:** Directives that alter the nature of a scripture (@hash, @inside).
+4.  **Metadata:** Permissions, Variables, and Vows.
+5.  **Values & Identifiers:** The raw material (Paths, Strings, Numbers).
+
+### THE ASCENDED FACULTIES (V-Ω):
+*   **The Sentinel of Links:** Added `->` for symbolic linking.
+*   **The Gnostic Traits:** Added `%% trait` and `%% use` for mixin composition.
+*   **The Integrity Anchor:** Added `@hash(...)` for SRI-style verification.
+*   **The Permission Granularizer:** Expanded permission logic to accept keywords.
+=================================================================================
+"""
+
+import re
+
+# =============================================================================
+# == I. THE SCAFFOLD ATOMS (THE LANGUAGE OF FORM)                            ==
+# =============================================================================
+SCAFFOLD_ATOMS = [
+    # -------------------------------------------------------------------------
+    # 1. BLOCK DELIMITERS (The Containers of Soul)
+    # -------------------------------------------------------------------------
+    # These must be matched first. They represent the start of a multi-line content block.
+    # We match the operator + the opening quote.
+    ('SIGIL_MULTILINE_DQ', r'::\s*"""'),  # :: """ ... """
+    ('SIGIL_MULTILINE_SQ', r"::\s*'''"),  # :: ''' ... '''
+    ('SIGIL_APPEND_BLOCK_DQ', r'\+=\s*"""'),  # += """ ... """
+    ('SIGIL_APPEND_BLOCK_SQ', r"\+=\s*'''"),  # += ''' ... '''
+    ('SIGIL_TRANSFIGURE_BLOCK_DQ', r'~=\s*"""'),  # ~= """ ... """
+    ('SIGIL_TRANSFIGURE_BLOCK_SQ', r"~=\s*'''"),  # ~= ''' ... '''
+    ('SIGIL_PREPEND_BLOCK_DQ', r'\^=\s*"""'),  # ^= """ ... """
+    ('SIGIL_PREPEND_BLOCK_SQ', r"\^=\s*'''"),  # ^= ''' ... '''
+
+    # -------------------------------------------------------------------------
+    # 2. INLINE OPERATORS (The Verbs of Creation)
+    # -------------------------------------------------------------------------
+    # These define the relationship between the Path (Form) and the Content (Soul).
+    ('SIGIL_APPEND', r'\+='),  # Append content
+    ('SIGIL_SUBTRACT', r'-='),  # Remove content (Regex)
+    ('SIGIL_TRANSFIGURE', r'~='),  # Regex substitution
+    ('SIGIL_PREPEND', r'\^='),  # Prepend content
+    ('SIGIL_INLINE', r'::'),  # Define content inline
+    ('SIGIL_SEED', r'<<'),  # Seed content from external file
+    ('SIGIL_SYMLINK', r'->'),  # [NEW] Establish a symbolic link
+
+    # -------------------------------------------------------------------------
+    # 3. SEMANTIC MODIFIERS (The Adjectives of Intent)
+    # -------------------------------------------------------------------------
+    # These modify the behavior of the operation (e.g., @inside a class, @hash integrity).
+
+    # [NEW] The Hash Anchor: file.py @hash(sha256:abc...)
+    # Matches the full directive to capture the algorithm and digest.
+    ('HASH_ANCHOR', r'@hash\([a-zA-Z0-9]+:[a-fA-F0-9]+\)'),
+
+    # Generic Directives: @inside, @after, @before
+    ('SIGIL_DIRECTIVE', r'@\w+'),
+
+    # Arguments for directives: (key="value", ...)
+    ('SIGIL_LPAREN', r'\('),
+    ('SIGIL_RPAREN', r'\)'),
+    ('KEY_VALUE_PAIR', r'\w+\s*=\s*(?:"[^"]*"|\'[^\']*\')'),
+    ('OPERATOR_COMMA', r','),
+
+    # -------------------------------------------------------------------------
+    # 4. METADATA & TRAITS (The Laws of the File)
+    # -------------------------------------------------------------------------
+
+    # [NEW] Gnostic Traits: Reusable architectural DNA
+    ('SIGIL_TRAIT_DEF', r'%%\s*trait\b'),  # %% trait Auth = ...
+    ('SIGIL_TRAIT_USE', r'%%\s*use\b'),  # %% use Auth
+    ('SIGIL_ON_UNDO', r'%%\s*on-undo\b'), # [NEW] The Maestro's Counter-Edict
+    # =====================
+    ('SIGIL_PERMS', r'%%'),  # Permissions marker
+    ('SIGIL_VAR_DEF', r'\$\$'),  # Variable definition
+    ('SIGIL_VOW', r'\?\?'),  # Gnostic Vow (Assertion)
+    ('SIGIL_INDENTED', r':\s*$'),  # Start of an indented block
+
+    # -------------------------------------------------------------------------
+    # 5. VALUES (The Raw Gnosis)
+    # -------------------------------------------------------------------------
+
+    # Permissions: Octal (755) or Named (executable, readonly, secret)
+    # Note: We rely on the DeconstructionScribe to bind this to the %% sigil.
+    ('PERMISSIONS', r'(?<=%%\s)(?:[0-7]{3}|executable|readonly|secret)'),
+
+    # Seed Paths: The source of a << operation
+    ('SEED_PATH', r'(?<=\<\<\s)[\S]+'),
+
+    # Jinja2 Constructs: {{ var }} or {% if %}
+    ('JINJA_CONSTRUCT', r'\{[%#].*?[%#]\}'),
+    ('PLACEHOLDER', r'\{\{.*?\}\}'),
+
+    # Strings: Double or Single quoted, handling escaped quotes.
+    ('QUOTED_STRING', r'"(?:\\.|[^"\\])*"|\'(?:\\.|[^\'\\])*\''),
+
+    # -------------------------------------------------------------------------
+    # 6. THE PATH (The Locus of Manifestation)
+    # -------------------------------------------------------------------------
+    # A path is any sequence of characters that is NOT a sigil or operator.
+    # We explicitly exclude the new `->` sigil from being consumed as part of a filename.
+    ('PATH', r'(?:(?!\+=|-=|~=|\^=|::|<<|%%|\?\?|@|#|->)[^"\':\s])+'),
+
+    # -------------------------------------------------------------------------
+    # 7. THE VOID (Comments & Whitespace)
+    # -------------------------------------------------------------------------
+    ('COMMENT', r'#.*'),
+]
+
+# =============================================================================
+# == II. THE SYMPHONY ATOMS (THE LANGUAGE OF WILL)                           ==
+# =============================================================================
+# Used for parsing .symphony files.
+SYMPHONY_ATOMS = [
+    ('SIGIL_BLOCK_START', r'^[a-zA-Z0-9_]+\s*(?:\(.*\))?:\s*$'),  # Task/Macro definitions
+    ('SIGIL_HEREDOC', r'<<\s*(\w+)'),  # Legacy heredoc support
+    ('SIGIL_SIMPLE', r'>>|\?\?|%%'),  # Action, Vow, State
+    ('SIGIL_BREAKPOINT', r'!!'),  # Debug breakpoint
+    ('SIGIL_PARALLEL', r'&&'),  # Parallel execution
+    ('SIGIL_IF', r'@if\b'),
+    ('SIGIL_ELIF', r'@elif\b'),
+    ('SIGIL_ELSE', r'@else\b'),
+    ('SIGIL_ENDIF', r'@endif\b'),
+    ('SIGIL_FOR', r'@for\b'),
+    ('SIGIL_ENDFOR', r'@endfor\b'),
+    ('SIGIL_TRY', r'@try\b'),
+    ('SIGIL_CATCH', r'@catch\b'),
+    ('SIGIL_FINALLY', r'@finally\b'),
+    ('SIGIL_ENDTRY', r'@endtry\b'),
+    ('SIGIL_TASK_DEF', r'@task\b'),
+    ('SIGIL_TASK_END', r'@endtask\b'),
+    ('SIGIL_MACRO_DEF', r'@macro\b'),
+    ('SIGIL_MACRO_END', r'@endmacro\b'),
+    ('SIGIL_CALL', r'@call\b'),
+    ('SIGIL_IMPORT', r'@import\b'),
+    ('SIGIL_DIRECTIVE', r'@\w+'),
+    ('OPERATOR_COLON', r':'),
+    ('OPERATOR_COMMA', r','),
+    ('OPERATOR_KEYWORD', r'\b(as|using|in)\b'),
+    ('QUOTED_STRING', r'"(?:\\.|[^"\\])*"|\'(?:\\.|[^\'\\])*\''),
+    ('COMMENT', r'#.*'),
+    ('WORD', r'[^"\':,\s#]+'),
+]

velm/help_registry.py

@@ -0,0 +1,170 @@
+from typing import Dict, Type, Callable, List, Union
+
+# =================================================================================
+# ==            THE GNOSTIC REGISTRY (V-Ω-ETERNAL. THE BOOK OF SOULS)            ==
+# =================================================================================
+#
+# This is the single, sacred nexus point for the entire help system. It contains
+# no logic. It is a pure registry—a divine "Book of Souls"—where all self-aware
+# Artisans and Gnostic Topics must proclaim their existence to be perceived by
+# the Gnostic Oracle (`help_cli.py`).
+#
+# =================================================================================
+
+# The two sacred vessels that hold the souls of all known Gnosis.
+_artisans: Dict[str, Type] = {}
+_topics: Dict[str, Callable] = {}
+
+
+def register_artisan(name: str):
+    """
+    A sacred decorator spoken by a class-based Artisan (e.g., WeaveArtisan)
+    to inscribe its soul into the Gnostic Registry.
+
+    This makes the Artisan discoverable by the Oracle.
+    """
+    def decorator(cls: Type) -> Type:
+        _artisans[name] = cls
+        return cls
+    return decorator
+
+
+def register_gnosis(name_or_soul: Union[str, Callable] = None):
+    """
+    [ASCENDED] A sacred, sentient decorator for function-based Gnostic Topics.
+    It can be summoned in two divine forms:
+
+    1. With a Name: `@register_gnosis("custom_name")` - Registers the Topic
+       with a specific name, overriding its function name.
+
+    2. Without a Name: `@register_gnosis` - Intelligently perceives the
+       Topic's function name and uses it as the topic name.
+    """
+    def decorator(soul: Callable) -> Callable:
+        name = name_or_soul if isinstance(name_or_soul, str) else soul.__name__
+        _topics[name] = soul
+        return soul
+
+    if callable(name_or_soul):
+        return decorator(name_or_soul)
+    else:
+        return decorator
+
+
+def get_artisan(name: str) -> Union[Type, None]:
+    """Summons an Artisan's soul (the class itself) from the registry."""
+    return _artisans.get(name)
+
+
+def get_gnosis_topic(name: str) -> Union[Callable, None]:
+    """Summons a Gnostic topic's soul (the render function) from the registry."""
+    return _topics.get(name)
+
+
+def list_all_topics() -> List[str]:
+    """Proclaims the full, unified list of all known Gnosis in the cosmos."""
+    # The two streams of Gnosis are unified into a single, sorted river.
+    all_known_souls = list(_artisans.keys()) + list(_topics.keys())
+    return sorted(all_known_souls)
+
+
+# =================================================================================
+# ==                             CODEX REGISTRUM                                 ==
+# =================================================================================
+#
+#               THIS IS THE GRAND SCRIPTURE OF THE GNOSTIC REGISTRY
+#
+#
+# ### I. THE PRIME DIRECTIVE: THE ANNIHILATION OF DUAL SCRIPTURES
+#
+# The `help` system of a lesser tool is a heresy. It creates a second, profane
+# scripture (e.g., a static `help_text.py`) that must be manually updated
+# whenever the tool's true scripture (its code) changes. This "dual scripture"
+# paradox inevitably leads to neglect, falsehood, and the erosion of the user's
+# trust.
+#
+# This Gnostic Registry is the key to annihilating that paradox.
+#
+# The Scaffold help system is a **LIVING ORACLE**. It does not *contain* help
+# text; it *perceives* it by gazing directly into the souls of the Artisans
+# themselves. This registry is the Oracle's divine index, its "Book of Souls,"
+# that tells it which Artisans have achieved self-awareness and are ready to be
+# perceived.
+#
+# To update the help for `weave`, you do not touch the Oracle. You simply add a
+# new comment to the `WeaveArtisan` class. The maintenance burden is zero.
+# The Gnosis is always pure.
+#
+#
+# ### II. THE SACRED CONTRACT: PROCLAMATION & PERCEPTION
+#
+# This registry establishes an unbreakable, two-fold contract:
+#
+# 1.  **The Artisan's Vow of Proclamation:** For an Artisan's Gnosis to be known,
+#     it MUST proclaim its existence to this registry using a sacred decorator.
+#     If it does not speak, it is a ghost in the machine, invisible to the Oracle.
+#
+# 2.  **The Oracle's Vow of Perception:** The Oracle (`help_cli.py`) vows to ONLY
+#     draw its knowledge from this registry. It will never contain its own static
+#     Gnosis. It is a pure conduit for the truths inscribed herein.
+#
+#
+# ### III. THE TWO PATHS TO IMMORTALITY: BESTOWING SELF-AWARENESS
+#
+# Any future Artisan or concept can be made immortal and discoverable by the
+# Oracle by walking one of two sacred paths.
+#
+# #### PATH 1: THE ARTISAN'S ASCENSION (For Complex Commands)
+#
+# This path is for complex, class-based commands like `weave` or `distill`.
+# To make a new `NewArtisan` discoverable, you must perform two rites:
+#
+# 1.  **Speak the Decorator:** Atop the class definition, speak the sacred
+#     decorator, giving the command its topic name.
+#
+# 2.  **Inscribe the Gnostic Markers:** In the class's docstring, inscribe
+#     the `@gnosis` markers that the Oracle's Gaze can perceive.
+#
+#     ```python
+#     # In scaffold/new_cli.py
+#     from .help_registry import register_artisan
+#
+#     @register_artisan("new_command")
+#     class NewArtisan:
+#         """
+#         @gnosis:title The Title for the Help Page
+#         @gnosis:summary A short, one-line summary.
+#         @gnosis:description
+#         The full, multi-line philosophical description of what this
+#         artisan does and why it exists.
+#         """
+#         # ... artisan's logic ...
+#     ```
+#
+# #### PATH 2: THE SCRIBE'S GNOSIS (For Simple Concepts)
+#
+# This path is for pure, conceptual Gnosis that isn't a command, such as
+# explaining the project's "philosophy" or the "variable system".
+#
+# 1.  **Forge a Scribe Function:** Create a simple, parameter-less function
+#     in a relevant file (or `help_cli.py` itself) that uses `rich` to render
+#     the help panel for that concept.
+#
+# 2.  **Speak the Decorator:** Atop the function, speak the `@register_gnosis`
+#     decorator. The Oracle will now know of this concept and will execute this
+#     function when the topic is summoned.
+#
+#     ```python
+#     # In scaffold/concepts.py (a new, optional file)
+#     from .help_registry import register_gnosis
+#
+#     @register_gnosis("philosophy")
+#     def render_philosophy_codex():
+#         # ... rich rendering logic ...
+#         console.print(Panel(...))
+#     ```
+#
+# This divine architecture ensures that the Scaffold engine can grow infinitely in
+# power and wisdom, yet its Oracle will remain eternally up-to-date, self-aware,
+# and effortless to maintain. This is the final word.
+# =================================================================================

velm/herald.py

@@ -0,0 +1,137 @@
+# Path: scaffold/herald.py
+
+"""
+=================================================================================
+== THE SACRED SANCTUM OF THE HERALD OF THE FUTURE (V-Ω-LEGENDARY++)            ==
+=================================================================================
+This scripture contains the living, unified soul of the Herald, the asynchronous
+Oracle that communes with the celestial PyPI registry to proclaim prophecies of
+new ascensions.
+=================================================================================
+"""
+import json
+import threading
+import time
+from pathlib import Path
+from typing import Dict
+
+import requests
+# --- The Divine Summons of the Celestial Allies ---
+from packaging.version import parse as parse_version
+
+from .constants import PACKAGE_NAME
+from .help_registry import register_gnosis
+from .logger import get_console
+
+RICH_AVAILABLE = False
+try:
+    from rich.panel import Panel
+    from rich.text import Text
+    from rich.console import Console
+
+    RICH_AVAILABLE = True
+except ImportError:
+    Console = object  # A humble placeholder
+
+
+
+
+class Herald:
+    """The God-Engine of Gnostic Communion and Prophecy."""
+
+    def __init__(self):
+        self.console = get_console()
+        self.cache_dir = Path.home() / ".scaffold" / "cache"
+        self.cache_file = self.cache_dir / "update_check.json"
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def _proclaim_ascension(self, release_data: Dict, current: str, is_reminder: bool = False):
+        """[THE LUMINOUS DOSSIER OF ASCENSION] Forges and proclaims the divine update notification."""
+        latest = release_data.get('version', 'Unknown')
+        summary = release_data.get('summary', '')
+
+        if not RICH_AVAILABLE:
+            self.console.print("--- Prophecy of Ascension ---")
+            self.console.print(f"A new ascension of Scaffold is available: {latest}")
+            if summary and not is_reminder: self.console.print(f'"{summary}"')
+            self.console.print(f"You have: {current}")
+            self.console.print(f"Speak the sacred edict to ascend: pip install --upgrade {PACKAGE_NAME}")
+            return
+
+        current_v, latest_v = parse_version(current), parse_version(latest)
+        latest_parts = []
+        has_diff = False
+        for i, part in enumerate(latest_v.release):
+            style = "bold green"
+            if not has_diff and (i >= len(current_v.release) or part > current_v.release[i]):
+                style, has_diff = "bold yellow on magenta", True
+            elif has_diff:
+                style = "bold green"
+
+            latest_parts.append((str(part), style))
+            if i < len(latest_v.release) - 1: latest_parts.append((".", "dim"))
+
+        latest_text = Text.assemble(*latest_parts)
+
+        title_text = "Reminder: A new ascension of Scaffold awaits!" if is_reminder else "A new ascension of Scaffold is available!"
+
+        proclamation = Text.assemble(
+            (title_text + "\n", "bold yellow"),
+            (f'"{summary}"\n\n', "italic") if summary and not is_reminder else ("\n", ""),
+            ("  You have: ", "dim"), (current, "red"),
+            ("\n  Celestial: ", "dim"), latest_text,
+            ("\n\nSpeak the sacred edict to ascend:\n", "white"),
+            (f"pip install --upgrade {PACKAGE_NAME}", "bold cyan")
+        )
+        self.console.print(Panel(proclamation, title="[yellow]Prophecy of Ascension[/yellow]", border_style="yellow"))
+
+    def _perform_plea(self):
+        """[THE HERALD'S SOUL] The divine, internal artisan that performs the actual communion."""
+        try:
+            from .. import __version__ as current_version
+
+            cache_data = {}
+            if self.cache_file.exists():
+                try:
+                    cache_data = json.loads(self.cache_file.read_text(encoding='utf-8'))
+                except json.JSONDecodeError:
+                    pass
+
+            last_checked = cache_data.get('last_checked', 0)
+
+            if (time.time() - last_checked) < 86400:
+                cached_release_data = cache_data.get('latest_release')
+                if cached_release_data and parse_version(cached_release_data.get('version', '0')) > parse_version(
+                        current_version):
+                    self._proclaim_ascension(cached_release_data, current_version, is_reminder=True)
+                return
+
+            response = requests.get(f"https://pypi.org/pypi/{PACKAGE_NAME}/json", timeout=3)
+            response.raise_for_status()
+            pypi_data = response.json()
+            release_info = pypi_data.get('info', {})
+            latest_version_str = release_info.get('version')
+
+            if not latest_version_str: return
+
+            cache_data['last_checked'] = time.time()
+            cache_data['latest_release'] = release_info
+            self.cache_file.write_text(json.dumps(cache_data), encoding='utf-8')
+
+            if parse_version(latest_version_str) > parse_version(current_version):
+                self._proclaim_ascension(release_info, current_version)
+
+        except Exception:
+            pass  # The Unbreakable Vow of Prudent Silence is absolute.
+
+    def check(self):
+        """[THE VOW OF UNSEEN GRACE] Conducts the communion in a parallel reality."""
+        update_thread = threading.Thread(target=self._perform_plea, daemon=True)
+        update_thread.start()
+
+
+@register_gnosis("check_for_updates")
+def check_for_updates():
+    """The public, Gnostic gateway to the Herald's soul."""
+    herald = Herald()
+    herald.check()