docs: document Multi-Agent MCP architecture, Double-Evidence protocol, and Expandable Summaries

GEMINI.md

@@ -7,7 +7,7 @@ This file contains the accumulated instructions and long-term vision for the aut
 1.  **Information Preservation**: NEVER delete summaries, comments, or stars (🌟) accompanying links. The bot should only update the URL or reorganize the item's position, never delete the descriptive context.
 2.  **Persistent Learning**: Use `src/memory/health_learning.json` to store knowledge about domains (anti-bot blocks, successful strategies) and navigation patterns.
 3.  **Minimum Viable Quality (MVQ)**: For GitHub/GitLab repositories, the bot MUST check the last commit date. If the repository has had NO activity (commits) in more than **4 years**, it must receive a significantly lower `impact_score` and be deprioritized, even if the content remains technically relevant. This ensures Nubenetes stays fresh and focuses on maintained projects.
-4.  **Style Guide (Descriptive Summaries)**: All injected summaries MUST follow a **Descriptive** style. Avoid generic "clickbait" or action-oriented phrases (e.g., "Check this out"). Instead, provide a clear, neutral description of what the resource contains, its scope, and why it is technically significant for the Kubernetes ecosystem.
+4.  **Style Guide (High-Density Summaries)**: All injected summaries MUST follow a **High-Density Descriptive** style. Avoid generic "clickbait". Instead, apply the **Double-Evidence Synthesis Protocol**: contrast 'Curator Insight' with 'Live Grounding' (MCP) to provide a neutral, professional description of architectural value, key features, and technical significance. Summaries should be 2-5 sentences long and support multi-line Markdown formatting (bullet points).
 5.  **Semantic Interlinking**: The bot should identify related categories for each resource. While the full entry is injected into the primary category, a short reference (*"See also: [Title](URL) in [Category]"*) should be added to up to two related categories to improve site navigation.
 6.  **Visual Health Dashboard**: Every curation run MUST generate a local `report.html` (outside the repo) for visual validation of metrics, quality (MVQ), and AI decisions.
 7.  **Total Resilience**: The workflow must be able to continue even if there are individual errors in link or file validations. Prioritize generating a result (PR) even if it is partial.
@@ -47,7 +47,8 @@ This file contains the accumulated instructions and long-term vision for the aut
 20. **V2 Navigation Design**: The V2 top navigation bar MUST maintain a flat structure. All dimensions and categories must be top-level tabs in `v2-mkdocs.yml` to ensure direct discoverability and avoid nested groupings like "Categories".
 21. **V2 Impact-Driven Sorting**: The V2 portal MUST prioritize **relevance (Impact) over dates** within sections to provide high-density technical value. Sorting MUST follow: 1. Stars/Relevance (DESC), 2. Year (DESC). The mission statement and descriptions MUST reflect this impact-driven synthesis.
 22. **Unified Metadata Database (Local Storage & Persistence)**: All link metadata MUST be managed via the centralized [`data/inventory.yaml`](data/inventory.yaml).
-    - **`inventory.yaml`**: The single source of truth for years, stars (0-5), descriptions, physical locations (`v1_locations`, `v2_locations`), and visual formatting. This eliminates the need for external mapping files (like the legacy `structure_map.yaml`) and ensures full lifecycle visibility.
+    - **`inventory.yaml`**: The single source of truth for years, stars (0-5), descriptions, physical locations (`v1_locations`, `v2_locations`), and visual formatting. This eliminates the need for external mapping files and ensures full lifecycle visibility.
+    - **Scalable Multiline Support**: The inventory utilizes **YAML Block Scalars (`|`)** for fields like `ai_summary`, enabling the storage of complex technical summaries with paragraphs and bullet points without breaking the database structure.
     - **Platinum Lifecycle Metadata**: The inventory MUST track advanced engineering fields to empower context-aware automation:
         *   `content_hash`: SHA256 fingerprint to detect silent content updates.
         *   `health_score`: 0-100 reliability score based on check history (differentiates flaky from dead).
@@ -119,14 +120,17 @@ This file contains the accumulated instructions and long-term vision for the aut
     - **License Monitoring**: Health agents MUST monitor the `LICENSE` field for all repository resources (GitHub/GitLab).
     - **Non-Free Transition Alert**: If a project transitions from a permissive license (e.g., Apache 2.0, MIT) to a non-free or restrictive license (e.g., BSL, SSPL), the resource MUST be flagged as `status: review_required`.
     - **Impact Adjustment**: Projects that move away from Open Source standards MUST receive an automatic star reduction and be deprioritized in the V2 portal to favor truly open alternatives.
-36. **V2 Elite Visual Standards**: All V2 content generation MUST apply the following visual hierarchy to highlight resource value:
+36. **V2 Elite Visual Standards**: All V2 content generation MUST apply the following visual hierarchy:
     - **Platinum Resources (5 stars)**: Use yellow highlighting for the link text (e.g., `==[Link Title]==`).
     - **Gold Resources (4 stars)**: Use bold formatting for the link text (e.g., `**[Link Title]**`).
-    - **Multi-Dimensional Tagging**: Every resource in V2 SHOULD have one or more maturity/type tags (e.g., `[DE FACTO STANDARD]`, `[GUIDE]`, `[CASE STUDY]`). The `[COMMUNITY-TOOL]` tag is the fallback for unclassified assets.
+    - **Multi-Dimensional Tagging**: Every resource in V2 SHOULD have one or more maturity/type tags.
+    - **Expandable Deep-Dives**: High-density summaries MUST be rendered within an **expandable block** (`??? info "Technical Deep-Dive"`) to keep the portal compact while providing depth on demand.
     - **Star Consistency**: Maintain the 1-5 star scale for technical impact. Resources with 0 stars are considered "Standard References" and do not display a star prefix/suffix in the V2 UI.
 38. **V2 Semantic Connectivity**: All V2 content generation MUST implement the **Semantic Cross-Linking Engine**. AI agents must autonomously identify related architectural patterns within the same strategic dimension and inject "💡 Explore Related" navigation blocks at the end of sections to facilitate a connected knowledge graph.
 39. **Industrial Learning Flow**: V2 documents MUST follow an O'Reilly-style technical progression. Organization within sections must move from foundational theory and standards to advanced implementation details and emerging patterns.
-40. **Robust AI-Driven Multi-Tagging**: Every resource evaluation MUST utilize **Real-time Web Grounding (MCP)** to assign 1 to 3 maturity/type tags from the official taxonomy. AI-assigned tags take precedence over static rules. Fallback to `[COMMUNITY-TOOL]` is only permitted after exhaustive classification failure or when no clear maturity signal is found.
+40. **Robust AI-Driven Multi-Tagging (Multi-Agent Protocol)**: Every resource evaluation MUST utilize a **Multi-Agent Analyst-Auditor workflow** with **Real-time Web Grounding (MCP)**:
+    - **Analyst Role**: Initial technical classification and initial evidence synthesis.
+    - **Auditor Role (Grounded)**: Selective verification of high-impact candidates ([DE FACTO STANDARD] or [ENTERPRISE-STABLE]) using Pro models to search for community reputation and stability. AI-assigned tags take precedence over static rules. Fallback to `[COMMUNITY-TOOL]` is only permitted after exhaustive classification failure.
 - **V2 Index Branding Protection**: The header and vision block of the V2 Elite Portal MUST NOT be modified. The title MUST remain "Nubenetes Elite Portal (V2) | Awesome Kubernetes & Cloud [![Awesome](https://cdn.jsdelivr.net/gh/sindresorhus/awesome@d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome)" and the abstract MUST use the "The High-Density Vision" text as hardcoded in the optimizer logic to maintain industrial-grade branding.
 - **V2 Index Visual Standard (Automotive Roots)**: The Nubenetes V2 Elite Portal index MUST feature a centered banner image linked to `kubernetes.io`, followed by the Horatio Nelson Jackson quote and the specific automotive container metaphor image (`images/container_with_cars_v2.png`). This image is a manually provided asset and MUST NOT be regenerated by AI to ensure the preservation of the project's established visual identity.
 - **V2 Index Footer Standard**: The V2 index MUST always conclude with the **Maturity Taxonomy** and **Technical Impact** explanation tables. These sections define the industrial-grade classification and visual code (Highlighting/Bold) used throughout the Elite portal and must be preserved across all automated regenerations.

README.md

@@ -306,10 +306,12 @@ graph TD
 
 ### 4.3. Adaptive AI Tiering and Real-time Grounding
 To ensure maximum throughput and industrial-grade precision, Nubenetes uses a proprietary **Multi-tier AI Orchestration** engine:
-- **Smart Batching (Anti-429)**: Instead of individual calls, the system groups up to **10-50 resources into a single AI prompt**. This reduces API traffic by 90% and is mandatory for exhaustive 17k+ link runs.
+- **Multi-Agent Analyst-Auditor Workflow**: Evaluation is split between a **Technical Analyst** (Flash model) for initial classification and a specialized **Elite Auditor** (Pro model) for selective verification of high-impact resources.
+- **Double-Evidence Synthesis Protocol**: Agents are mandated to contrast 'Curator Insight' (from original discovery) with 'Live Technical Grounding' (from search/MCP) before finalizing any technical summary.
 - **Real-time Web Grounding (MCP-Style)**: For high-fidelity tasks, the engine activates **Google Search Grounding**. This allows the AI to verify technical maturity, site migrations, and official documentation in real-time, providing a live data filter for all decisions.
-- **Dynamic Model Selection**: The system automatically toggles between **Gemini Pro** (for tasks requiring web research or deep reasoning) and **Gemini Flash** (for bulk enrichment).
-- **Global Back-off & Tier-down**: If a high-fidelity model (Pro) hits a rate limit (`API 429`), the engine automatically executes an exponential back-off and "tiers down" to a lighter model or rotates API keys to ensure workflow continuity.
+- **Smart Batching (Anti-429)**: Instead of individual calls, the system groups up to **10 resources into high-precision batches**. This optimizes grounding efficiency and minimizes rate limits.
+- **Dynamic Model Selection**: The system automatically toggles between **Gemini Pro** (for auditing and research) and **Gemini Flash** (for broad analysis).
+- **Global Back-off & Tier-down**: Automatic exponential back-off and model tier-down logic to ensure 100% workflow resilience.
 
 ### 4.4. Doc-as-Behavior Mandate Bridge
 Nubenetes implements a direct bridge between documentation and AI behavior:
@@ -337,6 +339,7 @@ Nubenetes operates with two distinct editions to serve different engineering nee
     - **Stars (🌟)**: Represent technical impact (1-5 scale).
     - **No stars**: Standard reference documentation and technical resources.
 - **Multi-Dimensional Tagging (1:N):** Every resource is classified with multiple semantic tags (e.g., `[DE FACTO STANDARD]`, `[GUIDE]`, `[CASE STUDY]`, `[EMERGING]`) providing deep technical context and maturity status.
+- **High-Density Expandable Summaries**: Resources feature a multi-line **"Technical Deep-Dive"** block (expandable with one click). These summaries use the **Double-Evidence Synthesis** protocol to provide verified architectural insights and key capabilities.
 - **Semantic Cross-Linking:** The portal autonomously identifies and links related categories within the same strategic dimension (e.g., suggesting `Flux` when reading about `Argo`), creating a cohesive **Industrial Knowledge Graph**.
 - **Executive Context**: Every strategic dimension features an AI-generated **State-of-the-Art Introduction** providing high-level architectural context and industry direction before the link listings.
 - **Source of Truth:** The `v2-docs/` directory (Derived from V1).