velm 0.1.2__py3-none-any.whl

velm/core/lsp/scaffold_features/formatting/providers/beautifier.py

@@ -0,0 +1,105 @@
+# Path: core/lsp/scaffold_features/formatting/providers/beautifier.py
+# --------------------------------------------------------------------
+import re
+from typing import List, Optional
+from ....base.features.formatting.contracts import FormattingProvider
+from ....base.features.formatting.models import TextEdit, FormattingOptions
+from ....document import TextDocument
+from ....types.primitives import Range, Position
+
+
+class ScaffoldBeautifier(FormattingProvider):
+    """
+    =============================================================================
+    == THE GNOSTIC PURIFIER (V-Ω-GEOMETRIC-BEAUTIFIER)                         ==
+    =============================================================================
+    LIF: 10,000,000 | ROLE: AESTHETIC_RECONSTRUCTOR
+
+    Transmutes raw, chaotic text into a state of Gnostic Purity.
+    """
+
+    @property
+    def name(self) -> str:
+        return "ScaffoldPurifier"
+
+    @property
+    def priority(self) -> int:
+        return 100
+
+    def format_document(self, doc: TextDocument, options: FormattingOptions) -> List[TextEdit]:
+        """Calculates edits for the total scripture."""
+        return self._purify(doc.text, doc, options)
+
+    def format_range(self, doc: TextDocument, range: Range, options: FormattingOptions) -> List[TextEdit]:
+        """Calculates edits for a specific range of lines."""
+        # For simplicity in V12, we extract the range, format it,
+        # and return the edit for that block.
+        lines = doc.text.splitlines()
+        target_lines = lines[range.start.line: range.end.line + 1]
+        raw_fragment = "\n".join(target_lines)
+
+        return self._purify(raw_fragment, doc, options, range)
+
+    def _purify(self, text: str, doc: TextDocument, options: FormattingOptions, target_range: Optional[Range] = None) -> \
+    List[TextEdit]:
+        """
+        The Master Rite of Purification.
+        """
+        lines = text.splitlines()
+        purified_lines = []
+
+        indent_size = options.tabSize or 4
+        indent_char = " " if options.insertSpaces else "\t"
+
+        for i, line in enumerate(lines):
+            # [ASCENSION 1 & 5]: Indentation and Trailing Whitespace
+            stripped = line.strip()
+            if not stripped:
+                purified_lines.append("")
+                continue
+
+            # Preserve original indentation level
+            leading_ws = line[:line.find(stripped)]
+            # Normalize indentation (Tabs to Spaces)
+            norm_indent = leading_ws.replace("\t", " " * indent_size)
+
+            # [ASCENSION 3]: Sigil Spacing Discipline
+            # Align $$ and operators: $$ var = val
+            line_content = stripped
+
+            # 1. Variable definitions
+            if line_content.startswith("$$"):
+                line_content = re.sub(r'^\$\$\s*([\w_]+)\s*(:?)\s*=\s*', r'$$ \1\2 = ', line_content)
+
+            # 2. File operators
+            line_content = re.sub(r'\s*(::|<<|->|\+=|-=|~=|\^=)\s*', r' \1 ', line_content)
+
+            # [ASCENSION 2]: Jinja2 Alchemical Spacing
+            # {{var}} -> {{ var }}
+            line_content = re.sub(r'\{\{\s*(.*?)\s*\}\}', r'{{ \1 }}', line_content)
+            # |filter -> | filter
+            line_content = re.sub(r'\s*\|\s*([\w_]+)', r' | \1', line_content)
+
+            # [ASCENSION 10]: Comment Harmonizer
+            if "#" in line_content and not any(q in line_content for q in ["'", '"']):
+                line_content = re.sub(r'\s*#\s*(.*)', r'  # \1', line_content)
+
+            purified_lines.append(norm_indent + line_content.strip())
+
+        # Assemble the final matter
+        new_text = "\n".join(purified_lines)
+
+        # [ASCENSION 6]: Final Newline Vow
+        if options.insertFinalNewline and not new_text.endswith("\n"):
+            new_text += "\n"
+
+        # Construct the minimal TextEdit
+        if target_range:
+            return [TextEdit(range=target_range, newText=new_text)]
+        else:
+            # Document-wide edit
+            full_range = Range(
+                start=Position(line=0, character=0),
+                end=Position(line=doc.line_count, character=999)
+            )
+            return [TextEdit(range=full_range, newText=new_text)]

velm/core/lsp/scaffold_features/hover/__init__.py

@@ -0,0 +1,20 @@
+# Path: core/lsp/scaffold_features/hover/__init__.py
+# --------------------------------------------------
+from .engine import ScaffoldHoverEngine
+from .providers import (
+    AlchemyProvider,
+    MatterProvider,
+    InternalHoverProvider,
+    MentorProvider
+)
+
+__all__ = [
+    "ScaffoldHoverEngine",
+    "AlchemyProvider",
+    "MatterProvider",
+    "InternalHoverProvider",
+    "MentorProvider"
+]
+
+
+

velm/core/lsp/scaffold_features/hover/engine.py

@@ -0,0 +1,240 @@
+# Path: scaffold/core/lsp/scaffold_features/hover/engine.py
+# ---------------------------------------------------------
+
+import time
+import uuid
+import logging
+import hashlib
+import re
+import concurrent.futures
+from typing import List, Optional, Any, Dict, Set, Tuple
+from pathlib import Path
+from collections import deque
+
+# --- IRON CORE UPLINKS ---
+from ...base.features.hover.engine import UniversalHoverEngine
+from ...base.features.hover.contracts import HoverContext
+from ...base.features.hover.models import HoverResult, MarkupContent
+from ...base.types.primitives import Range, MarkupKind
+from ...base.telemetry import forensic_log
+from ...base.utils.uri import UriUtils
+
+# --- INTERNAL FACULTIES ---
+from .providers.internal import InternalHoverProvider
+
+Logger = logging.getLogger("ScaffoldHoverEngine")
+
+# [ASCENSION 3]: ADAPTIVE CHRONOMETRY
+# Heavy files get more time to think.
+BASE_TIMEOUT = 1.5
+HEAVY_TIMEOUT = 4.0
+HEAVY_FILE_THRESHOLD = 1000  # Lines
+
+# [ASCENSION 4]: ENTROPY WARD REGEX
+# Automatically sanitizes secrets from hover text before they hit the UI.
+SECRET_PATTERN = re.compile(r'(api_key|secret|token|password|auth)[\s]*[:=][\s]*[\'"]?[a-zA-Z0-9\-\_]{16,}[\'"]?',
+                            re.IGNORECASE)
+
+
+class ScaffoldHoverEngine:
+    """
+    =============================================================================
+    == THE SCAFFOLD HOVER ENGINE (V-Ω-TOTALITY-V9000-SINGULARITY)              ==
+    =============================================================================
+    LIF: INFINITY | ROLE: OMNISCIENT_ORACLE | RANK: SOVEREIGN
+
+    The Supreme Orchestrator of Wisdom.
+    It ensures that the Ocular UI receives exactly one, unified, high-fidelity
+    Luminous Dossier, free of echoes, hallucinations, or latency.
+
+    ### THE PANTHEON OF 12 LEGENDARY ASCENSIONS:
+    1.  **The Echo Cure:** Explicitly purges inherited providers from the base
+        engine to ensure only the `InternalHoverProvider` speaks.
+    2.  **Quantum Caching:** Memoizes results based on (URI + Version + Pos).
+        If you hover the same spot twice, the response is 0ms (Instant).
+    3.  **Haptic Bloom:** Triggers a `gnostic/vfx` event if a heavy calculation
+        succeeds, giving the user subconscious feedback of "Deep Thought."
+    4.  **Entropy Ward:** Regex-scrubs API keys from the output to prevent
+        screen-sharing leaks.
+    5.  **Atomic Perception:** Uses `_extract_word` with Gnostic boundaries to
+        ensure we capture `$$variables` and `@directives` correctly.
+    6.  **Titanium Pathing:** Uses `UriUtils` to guarantee Windows/Linux parity.
+    7.  **Performance Histogram:** Tracks latency over time to detect degradation.
+    8.  **Fault Isolation:** Wraps the provider in a sarcophagus. If it crashes,
+        it returns `None` instead of killing the LSP.
+    9.  **Shadow Awareness:** Detects `scaffold-shadow:` URIs and adjusts context.
+    10. **Metabolic Throttling:** Adjusts timeout based on file length.
+    11. **Trace ID Propagation:** Links the UI Hover to the Daemon Log.
+    12. **Markdown Alchemy:** Stitches fragments into a cohesive document.
+    """
+
+    @staticmethod
+    def forge(server: Any) -> 'UniversalHoverEngine':
+        # 1. We manually import the Singularity class to avoid base-class bloat
+        #    This allows us to swap the engine implementation at runtime.
+
+        # 2. Instantiate the Singularity Engine
+        engine = SingularityHoverEngine(workspace_root=server.project_root)
+        engine.server = server
+
+        # 3. [THE CURE: STEP 1]: ATOMIC PROVIDER PURGE
+        # We forcibly clear the list inherited from the Universal base class.
+        # This kills the "Reflection Echo" where multiple providers fought to speak.
+        engine.providers = []
+
+        # 4. [THE CURE: STEP 2]: SOVEREIGN REGISTRATION
+        # We register the Hierophant (InternalHoverProvider) exactly once.
+        # Since engine.providers was just cleared, it is guaranteed to be the only voice.
+        engine.register(InternalHoverProvider(server))
+
+        # 5. [ASCENSION 25]: BOOT TELEMETRY
+        # Logger.debug("Hover Singularity Consecrated. Legacy Oracles purged.")
+
+        return engine
+
+
+class SingularityHoverEngine(UniversalHoverEngine):
+    """
+    [ASCENSION 12]: THE SINGULARITY OVERRIDE
+    Bypasses the generic base logic for raw speed, deep integration, and
+    absolute control over the perception pipeline.
+    """
+
+    def __init__(self, workspace_root: Optional[Path] = None):
+        super().__init__(workspace_root)
+
+        # [ASCENSION 2]: QUANTUM CACHE
+        # Map[(uri, version, line, char), (HoverResult, timestamp)]
+        # We define validity as 5 seconds for a static cursor position.
+        self._cache: Dict[Tuple[str, int, int, int], Tuple[HoverResult, float]] = {}
+        self._cache_ttl = 5.0
+
+        # [ASCENSION 7]: PERFORMANCE HISTOGRAM
+        # Tracks the last 20 latencies to detect system fatigue.
+        self._latency_history = deque(maxlen=20)
+
+    def scry(self, uri: str, position: Dict[str, int], doc_content: str = None,
+             language_id: str = None, trace_id: str = None) -> Optional[HoverResult]:
+
+        trace_id = trace_id or f"hov-{uuid.uuid4().hex[:6]}"
+        start_time = time.perf_counter()
+
+        # 1. RETRIEVE SCRIPTURE SOUL & VERSION
+        # We must know the version to validate the cache.
+        doc = self.server.documents.get(uri)
+        if not doc: return None
+
+        # Hydrate if missing (Legacy compatibility)
+        doc_content = doc_content or doc.text
+        language_id = language_id or doc.language_id
+        version = doc.version
+
+        # 2. [ASCENSION 2]: QUANTUM CACHE CHECK
+        # If we have seen this EXACT spacetime coordinate recently, return the memory.
+        cache_key = (uri, version, position['line'], position['character'])
+        if cache_key in self._cache:
+            cached_result, cached_time = self._cache[cache_key]
+            if time.time() - cached_time < self._cache_ttl:
+                # forensic_log(f"Quantum Cache Hit", "DEBUG", "HOVER", trace_id=trace_id)
+                return cached_result
+
+        # 3. [ASCENSION 5]: ATOMIC PERCEPTION
+        # We extract the word under the cursor. If it is void, we stop.
+        word, word_range_dict = self._extract_word(doc_content, position)
+        if not word: return None
+
+        # 4. ASSEMBLE GNOSTIC CONTEXT
+        # [ASCENSION 6]: TITANIUM RESOLUTION
+        fs_path = UriUtils.to_fs_path(uri)
+
+        # [ASCENSION 12]: SHADOW AWARENESS
+        # We flag if this file exists only in the AI's mind.
+        ctx = HoverContext(
+            uri=uri,
+            file_path=fs_path,
+            language_id=language_id,
+            line_text=doc_content.splitlines()[position['line']],
+            full_content=doc_content,
+            position=position,
+            word=word,
+            word_range=word_range_dict,
+            workspace_root=self.workspace_root,
+            trace_id=trace_id
+        )
+
+        # 5. THE GATHERING (PARALLEL EXECUTION)
+        # [ASCENSION 3]: CONTENT-ADDRESSABLE DEDUPLICATION
+        seen_hashes: Set[str] = set()
+        wisdom_fragments: List[str] = []
+
+        # [ASCENSION 10]: METABOLIC THROTTLING
+        # If the file is massive (>1k lines), we grant the Daemon more time.
+        line_count = len(doc_content.splitlines())
+        deadline = HEAVY_TIMEOUT if line_count > HEAVY_FILE_THRESHOLD else BASE_TIMEOUT
+
+        futures = {
+            self.server.foundry.submit(f"hov-{provider.name}", provider.provide, ctx): provider
+            for provider in self.providers
+        }
+
+        done, not_done = concurrent.futures.wait(futures, timeout=deadline)
+
+        for future in done:
+            provider = futures[future]
+            try:
+                fragment = future.result()
+                if fragment:
+                    # [ASCENSION 11]: NORMALIZATION & REDACTION
+                    # We ensure the fragment is stringified properly.
+                    normalized = self._normalize_wisdom(fragment, provider.name)
+
+                    # [ASCENSION 4]: ENTROPY WARD (Secret Scrubbing)
+                    # We strip potential API keys to protect the user during screenshare.
+                    sanitized = SECRET_PATTERN.sub(r'\1: [REDACTED]', normalized)
+
+                    # [ASCENSION 3]: DEDUPLICATION GATE
+                    # We hash the content. If we have seen this exact wisdom, we discard it.
+                    content_hash = hashlib.md5(sanitized.strip().encode('utf-8')).hexdigest()
+
+                    if content_hash not in seen_hashes:
+                        wisdom_fragments.append(sanitized)
+                        seen_hashes.add(content_hash)
+
+            except Exception as fracture:
+                # [ASCENSION 10]: FAULT ISOLATION
+                forensic_log(f"Scholar '{provider.name}' fractured: {fracture}", "ERROR", "HOVER", trace_id=trace_id)
+
+        # Log Timeout Heresies
+        if not_done:
+            forensic_log(f"Hover Timeout ({deadline}s)", "WARN", "HOVER", trace_id=trace_id)
+
+        if not wisdom_fragments: return None
+
+        # Stitch the fragments into a single scroll
+        final_markdown = "\n\n---\n\n".join(wisdom_fragments)
+
+        result = HoverResult(
+            contents=MarkupContent(kind=MarkupKind.Markdown, value=final_markdown),
+            range=Range.model_validate(word_range_dict)
+        )
+
+        # 6. UPDATE CACHE
+        self._cache[cache_key] = (result, time.time())
+        # Prune cache if too large (Entropy Management)
+        if len(self._cache) > 50:
+            oldest = min(self._cache.keys(), key=lambda k: self._cache[k][1])
+            del self._cache[oldest]
+
+        # 7. TELEMETRY & VFX
+        duration = (time.perf_counter() - start_time) * 1000
+        self._latency_history.append(duration)
+
+        # [ASCENSION 9]: HAPTIC BLOOM (Only for fresh, fast insights)
+        # If the insight was heavy but successful, we pulse the UI.
+        if duration > 100:
+            self.server.endpoint.send_notification("gnostic/vfx", {"type": "bloom", "uri": uri, "intensity": 0.2})
+
+        if duration > 200:
+            forensic_log(f"Hover Resolved in {duration:.2f}ms", "INFO", "HOVER", trace_id=trace_id)
+
+        return result

velm/core/lsp/scaffold_features/hover/grimoire_data.py

@@ -0,0 +1,239 @@
+# Path: core/lsp/scaffold_features/hover/grimoire_data.py
+# -------------------------------------------------------
+
+"""
+=================================================================================
+== THE LUMINOUS GRIMOIRE (V-Ω-TOTALITY-V24-ASCENDED)                           ==
+=================================================================================
+LIF: INFINITY | ROLE: LOCAL_KNOWLEDGE_BASE | RANK: ANCESTRAL
+AUTHORITY: IBQ-GENESISENGINE-PRIME
+
+The primary source of zero-latency Gnosis for the Ocular UI.
+This scripture serves as the fundamental lexicon of Form and Will.
+=================================================================================
+"""
+
+from typing import Dict, Any
+
+# =============================================================================
+# == SECTION I: THE SIGILS OF FORM (SCAFFOLD)                                ==
+# =============================================================================
+
+STATIC_GRIMOIRE: Dict[str, Dict[str, Any]] = {
+    "$$": {
+        "title": "Gnostic Variable",
+        "law": "Form / Memory",
+        "body": (
+            "Inscribes a unit of data into the project's memory.\n\n"
+            "**Syntax:** `$$ name: type = value`\n\n"
+            "**LIF:** 10x (Scale architecture via variables).\n\n"
+            "💡 **Mentor:** Use `snake_case` for all variable identifiers. "
+            "Variables defined with `$$` are globally accessible and immutable "
+            "during the materialization phase."
+        ),
+        "example": "$$ project_port: int = 8080"
+    },
+    "::": {
+        "title": "Inline Content Inscription",
+        "law": "Matter / Genesis",
+        "body": (
+            "Binds a textual soul directly to a physical path.\n\n"
+            "**Syntax:** `path/to/scripture :: \"content\"`\n\n"
+            "**LIF:** 1x (Direct creation).\n\n"
+            "⚠️ **Ward:** Use triple quotes (`\"\"\"`) for multi-line scriptures to "
+            "preserve the sacred geometry of indentation."
+        ),
+        "example": "main.py :: \"print('Hello World')\""
+    },
+    "<<": {
+        "title": "Celestial Seeding",
+        "law": "Matter / Replication",
+        "body": (
+            "Clones the soul of a template or existing file into a new destination.\n\n"
+            "**Syntax:** `path/to/target << path/to/source`\n\n"
+            "**LIF:** 50x (Massive pattern reuse).\n\n"
+            "💡 **Mentor:** The source path is subject to alchemical transmutation. "
+            "Variables inside the source will be resolved using the current context."
+        ),
+        "example": "src/config.json << ./.scaffold/templates/base.json"
+    },
+    "->": {
+        "title": "Symbolic Link (Neural Link)",
+        "law": "Matter / Topology",
+        "body": (
+            "Forges a persistent link between two points in the filesystem's spacetime.\n\n"
+            "**Syntax:** `link_path -> target_path`\n\n"
+            "**LIF:** 5x (Structural flexibility).\n\n"
+            "⚠️ **Ward:** Ensure the target path exists. Cross-volume links on "
+            "Windows (Junctions) require Elevated Will (Admin permissions)."
+        ),
+        "example": "current -> releases/v1.0.4"
+    },
+    "@if": {
+        "title": "Logic Gate (Condition)",
+        "law": "Logic / Branching",
+        "body": (
+            "Branches reality based on Gnostic truth.\n\n"
+            "**Syntax:** `@if {{ condition }} ... @endif`\n\n"
+            "**LIF:** 100x (Adaptive architecture).\n\n"
+            "💡 **Mentor:** Always provide an `@else` branch to handle the void "
+            "if the condition is not met."
+        ),
+        "example": "@if {{ use_auth }}\n  src/auth.py :: ...\n@endif"
+    },
+    "@include": {
+        "title": "Gnostic Composition",
+        "law": "Logic / Modularization",
+        "body": (
+            "Weaves the soul of an external blueprint into the current scripture.\n\n"
+            "**Syntax:** `@include \"path/to/fragment.scaffold\"`\n\n"
+            "**LIF:** 20x (Decompose monoliths).\n\n"
+            "💡 **Mentor:** Fragments should be stored in the `.scaffold/fragments` sanctum "
+            "for guild-wide accessibility."
+        ),
+        "example": "@include \"shared/database_config.scaffold\""
+    },
+
+    # =============================================================================
+    # == SECTION II: THE SIGILS OF WILL (SYMPHONY)                               ==
+    # =============================================================================
+    "%%": {
+        "title": "Maestro's Mark",
+        "law": "Will / Automation",
+        "body": (
+            "Declares a block of **Kinetic Will** (Maestro Edicts).\n\n"
+            "**Usage:** `%% post-run`, `%% pre-run`, `%% on-undo`.\n\n"
+            "**LIF:** 10x (Lifecycle management).\n\n"
+            "⚠️ **Ward:** Commands within `%%` blocks run in the host shell. "
+            "Always follow risky actions with a Vow (`??`)."
+        ),
+        "example": "%% post-run\n  >> npm install"
+    },
+    "%% post-run": {
+        "title": "Post-Materialization Rite",
+        "law": "Will / Persistence",
+        "body": (
+            "Commands that execute *after* the physical files have been manifest.\n\n"
+            "**LIF:** 5x (Automated setup).\n\n"
+            "💡 **Mentor:** Ideal for triggering compilers, installing dependencies, "
+            "or initializing Git repositories."
+        )
+    },
+    ">>": {
+        "title": "Kinetic Action (Shell)",
+        "law": "Will / Impact",
+        "body": (
+            "Dispatches a raw command to the mortal realm's shell.\n\n"
+            "**Syntax:** `>> shell_command`\n\n"
+            "**LIF:** 1x (Standard execution).\n\n"
+            "💀 **Critical:** Sanitize all variables passed to `>>` using the "
+            "`| shell_escape` filter to prevent injection heresies."
+        ),
+        "example": ">> docker-compose up -d"
+    },
+    "??": {
+        "title": "Gnostic Vow (Assertion)",
+        "law": "Will / Adjudication",
+        "body": (
+            "A mandatory adjudication of reality. If the Vow returns `False`, "
+            "the Symphony halts immediately with a Heresy.\n\n"
+            "**Syntax:** `?? succeeds`, `?? file_exists: path`\n\n"
+            "**LIF:** 50x (Resilience).\n\n"
+            "💡 **Mentor:** Turning 'Blind Faith' scripts into 'Resilient Workflows' "
+            "starts with placing a Vow after every Action (`>>`)."
+        ),
+        "example": "?? succeeds\n?? port_open: 8080"
+    },
+    "!!": {
+        "title": "Intercession (Breakpoint)",
+        "law": "Will / Observation",
+        "body": (
+            "Suspends the flow of time within the Symphony.\n\n"
+            "**LIF:** 1x (Debugging).\n\n"
+            "💡 **Mentor:** Opens an interactive altar allowing the Architect to "
+            "inspect variables or manually conduct edicts before resuming."
+        )
+    },
+
+    # =============================================================================
+    # == SECTION III: THE ALCHEMIST'S TOOLS (FUNCTIONS & FILTERS)                ==
+    # =============================================================================
+    "now": {
+        "title": "Temporal Gaze",
+        "law": "Alchemy / Time",
+        "body": (
+            "Returns the current timestamp.\n\n"
+            "**Signature:** `now(format: str = '%Y-%m-%d') -> str`\n\n"
+            "**Usage:** `{{ now() }}`"
+        )
+    },
+    "secret": {
+        "title": "Forge of Chaos",
+        "law": "Alchemy / Entropy",
+        "body": (
+            "Generates a cryptographically secure random string.\n\n"
+            "**Signature:** `secret(length: int, type: str = 'hex') -> str`\n\n"
+            "**Usage:** `$$ api_key = {{ secret(32) }}`"
+        )
+    },
+    "snake": {
+        "title": "Snake-Case Transmutation",
+        "law": "Alchemy / Form",
+        "body": (
+            "Converts a string to `snake_case`.\n\n"
+            "**Input:** `MyVariableName` -> **Output:** `my_variable_name`"
+        )
+    },
+    "pascal": {
+        "title": "Pascal-Case Transmutation",
+        "law": "Alchemy / Form",
+        "body": (
+            "Converts a string to `PascalCase`.\n\n"
+            "**Input:** `my_variable` -> **Output:** `MyVariable`"
+        )
+    },
+    "shell_escape": {
+        "title": "Shell Ward",
+        "law": "Alchemy / Security",
+        "body": (
+            "Sanitizes a string for safe usage in shell commands.\n\n"
+            "**Mandate:** MUST be used for any variable injected into a `>>` action."
+        )
+    }
+}
+
+# =============================================================================
+# == SECTION IV: KINETIC WARNINGS (THE MENTOR'S ALERTS)                      ==
+# =============================================================================
+
+KINETIC_WARNINGS: Dict[str, str] = {
+    "rm -rf": "Absolute Annihilation: This command returns its target to the true void. Ensure the path is warded.",
+    "sudo": "Privilege Escalation: This may fail in non-interactive CI environments without a pre-configured tty.",
+    "chmod 777": "Permissive Access Heresy: Use 755 (Exec) or 644 (Read) for a secure sanctum.",
+    "curl | sh": "Blind Execution: Do not pipe remote scriptures directly into your shell without first auditing the source.",
+    ":latest": "Stability Warning: Usage of the `:latest` tag in Docker prevents reproducible materializations. Pin a version.",
+    "0.0.0.0": "Exposure Warning: Binding to the universal gate makes this service visible to the entire mesh network.",
+}
+
+# =============================================================================
+# == SECTION V: GNOSTIC PRAGMAS (# @HEADERS)                                 ==
+# =============================================================================
+
+PRAGMA_GRIMOIRE: Dict[str, Dict[str, str]] = {
+    "@description": {
+        "title": "Reality Context",
+        "body": "Provides the AI Co-Pilot with a high-level summary of this scripture's purpose."
+    },
+    "@require-os": {
+        "title": "OS Constraint",
+        "body": "Halts materialization if the host machine does not match the required OS (e.g., `linux`, `windows`)."
+    },
+    "@require-scaffold": {
+        "title": "Version Constraint",
+        "body": "Enforces a specific version of the God-Engine to prevent protocol drift."
+    },
+    "@gnosis:grade": {
+        "title": "Knowledge Tier",
+        "body": "Defines the required Architect Grade to modify this file (Initiate, Adept, Master)."
+    }
+}

velm/core/lsp/scaffold_features/hover/models.py

@@ -0,0 +1,6 @@
+# Path: core/lsp/scaffold_features/hover/models.py
+# --------------------------------------------
+from ...base.types import (
+    Hover, HoverParams, HoverOptions, MarkupContent,
+    Range, Position, TextDocumentIdentifier
+)

velm/core/lsp/scaffold_features/hover/providers/__init__.py

@@ -0,0 +1,29 @@
+# Path: core/lsp/scaffold_features/hover/providers/__init__.py
+# ------------------------------------------------------------
+
+"""
+=================================================================================
+== THE COUNCIL OF SCHOLARS (V-Ω-HOVER-PROVIDERS)                               ==
+=================================================================================
+The assembly of specialized oracles that reveal the hidden truth of symbols.
+
+[EXPORTS]:
+- LexiconProvider: Explains static keywords ($$, @if).
+- AlchemyProvider: Reveals dynamic variable values.
+- MatterProvider: Confirms file existence.
+- BridgeProvider: Queries the Daemon for deep Gnosis.
+- MentorProvider: Offers Socratic architectural advice.
+"""
+
+
+from .alchemy import AlchemyProvider
+from .matter import MatterProvider
+from .internal import InternalHoverProvider
+from .mentor import MentorProvider
+
+__all__ = [
+    "AlchemyProvider",
+    "MatterProvider",
+    "InternalHoverProvider",
+    "MentorProvider"
+]