diff --git a/GEMINI.md b/GEMINI.md index 1f688f8d..803834fd 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -84,14 +84,13 @@ This file contains the accumulated instructions and long-term vision for the aut - **Exhaustive Inclusion (V2)**: Unlike standard categories, V2 pages for Special Assets MUST include 100% of the ALIVE links from V1, bypassing standard impact filters. - **AI Curation Discovery (Autonomous)**: The discovery engine MUST periodically use **Grounding/MCP** to identify new high-quality curation sources (e.g., emerging "Awesome" repos, engineering blogs) and suggest them for inclusion in `curation_sources.yaml`. -28. **Sophisticated V2 Knowledge Architecture**: The V2 Portal MUST be structured like an advanced O'Reilly technical book: - - **Deep Hierarchical Classification**: Resources MUST be organized using the `hierarchy` metadata field (a list of up to 10 strings: Area > Topic > Subtopics). This structure is mandatory for both V1 reorganization and V2 generation to ensure perfect consistency. - - **Location-Aware Automation**: Workflows MUST utilize the location metadata in the inventory (`v1_locations`, `v2_locations`) to perform surgical updates without redundant repository scans. - - **Structural Intelligence Persistence**: All agents MUST store and reuse the `hierarchy` and location metadata in the centralized inventory. This ensures zero-cost structural updates and industrial-grade scalability. - - **O'Reilly Learning Flow**: The organization must facilitate knowledge assimilation, moving from foundational theory to advanced engineering internals in a logical, ordered sequence. - - **Dynamic Indexing**: Every V2 page MUST include a Table of Contents (TOC) with clickable anchors for all technical sub-sections. - - **AI Dimension Naming**: Prioritize industry-standard terms (e.g., "AI and Artificial Intelligence" instead of internal jargon) for top-level navigation. - - **Content Extraction**: High-value sub-topics may be extracted into dedicated documents (e.g., "Microservices" content extracted from `introduction.md` into `microservices.md`) to maintain high-density focus. +28. **Sophisticated V2 Knowledge Architecture & V1 Structural Stability**: The ecosystem maintains a strict separation of architectural philosophies between editions: + - **V1 (Archive Stability)**: The V1 archive (`docs/`) prioritized human curation and historical continuity. AI agents MUST NOT perform aggressive structural reorganization, section rebuilding, or automated TOC reconstruction in V1. Injection of new links must follow a "minimal disruption" pattern, placing resources within existing categories without altering the established manual structure. + - **V2 (O'Reilly Knowledge Flow)**: The V2 Portal (`v2-docs/`) is the innovation layer. It MUST be structured like an advanced technical book: + * **Deep Hierarchical Classification**: Resources are organized using the `hierarchy` field (Area > Topic > Subtopics). This is mandatory for V2 generation. + * **O'Reilly Learning Flow**: Organization must move from foundational theory to advanced engineering internals in a logical, ordered sequence. + * **Dynamic Indexing**: Every V2 page MUST include an automated Table of Contents (TOC) with clickable anchors for all sub-sections. + - **Location-Aware Automation**: Workflows utilize location metadata (`v1_locations`, `v2_locations`) to perform surgical updates. V1 locations are considered "Fixed Anchors," while V2 locations are "Dynamic Clusters." 29. **TOC & Structural Exceptions**: Certain files (configuration-heavy or technical tables like `mkdocs.md` or `matrix-table.md`) are exempt from TOC and deep-hierarchy requirements. These exceptions MUST be respected by all agents to avoid unnecessary structural clutter in non-navigational files as defined in [`data/link_rules.yaml`](data/link_rules.yaml). diff --git a/README.md b/README.md index 01546890..5159f093 100644 --- a/README.md +++ b/README.md @@ -280,7 +280,23 @@ Nubenetes operates with two distinct editions to serve different engineering nee - **Source of Truth:** The `v2-docs/` directory (Derived from V1). - **Deployment:** [nubenetes.com/v2/](https://nubenetes.com/v2/) -### 5.3. The Incremental Elite Engine +### 5.3. Architecture Comparison Matrix: V1 vs. V2 +To better understand the dual-nature of the project, the following matrix details the technical and philosophical differences between the two editions: + +| # | Feature / Aspect | V1: Exhaustive Archive (`docs/`) | V2: Agentic Elite Portal (`v2-docs/`) | +| :--- | :--- | :--- | :--- | +| **1** | **Primary Goal** | **Historical Preservation**: Exhaustive list of all technically valid resources since 2018. | **High-Density Synthesis**: Elite selection of top-tier tools for the 2026 Architect. | +| **2** | **Structural Logic** | **Manual Stability**: Flat or semi-structured categories based on manual curation. | **Recursive Hierarchy**: Deep nesting (up to 10 levels) based on Area > Topic > Subtopics. | +| **3** | **AI Intervention** | **Minimal Disruption**: AI only injects new links into existing sections. No rebuilding. | **Total Reconstruction**: AI rebuilds pages from scratch using O'Reilly-style learning flows. | +| **4** | **Inclusion Filter** | **Low Barrier**: Any ALIVE and technically relevant link is included. | **High Maturity (MVQ)**: Minimum stars (>30) and recent activity (commits < 4 years). | +| **5** | **TOC Policy** | **Manual/Static**: Table of Contents is manually maintained or triggered on request. | **Dynamic/Automated**: Clickable TOC is automatically generated and updated in every run. | +| **6** | **Metadata Density** | **Standard**: Title, URL, and descriptive summary. | **Platinum**: Author, Reading Time, Maturity Tag, and AI-generated Professional Summary. | +| **7** | **Organization Style** | **Thematic Folders**: Organized by file name and topic sections (##). | **Strategic Dimensions**: Grouped by high-level engineering domains (e.g., Platform Engineering). | +| **8** | **Content Format** | **Original Language**: Preserves V1 native descriptions (Spanish, French, etc.). | **Global English**: All summaries and UI are in Professional English for global access. | +| **9** | **Maintenance Type** | **Surgical Repair**: Dead links are removed or updated line-by-line. | **Full Refresh**: Orphaned files are pruned and content is re-indexed from the inventory. | +| **10** | **Target Audience** | **Researchers & Historians**: Looking for specific deep technical context. | **Architects & Decision Makers**: Looking for vetted, stable, and mature solutions. | + +### 5.4. The Incremental Elite Engine To maintain the high-density quality of V2 without redundant AI costs, the `V2VisionEngine` implements an incremental synchronization strategy: 1. **Intelligent Caching**: It utilizes the centralized YAML inventory to store previous AI evaluations. Only NEW links added to V1 are sent to Gemini for classification. 2. **Dynamic "Upgrading"**: Even for cached links, the engine performs real-time local updates: