awesome-kubernetes: Instructions file for Gemini CLI

Nubenetes Intelligent Curation: Meta-Instructions & Learning Roadmap

This file contains the accumulated instructions and long-term vision for the autonomous maintenance of Nubenetes.com. AI agents must consult this document in every iteration to ensure learning continuity.

🧠 Core Mandates

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 (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 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.
8. Repository Consolidation & Deep-Link Preservation: In case of a failure (404) in a deep GitHub/GitLab link, the bot SHOULD try to validate the repository root before considering it dead. However, if a deep link (wiki, PR, tree) is ALIVE, it MUST be preserved. We prefer specific technical context in V1.
9. URL Expansion: All shortened links (t.co, bit.ly, buff.ly, etc.) MUST be expanded to their original long version before being evaluated or injected. This ensures inventory homogeneity and improves global deduplication precision.
10. Linguistic Diversity & Global Access:
    • Primary Language: English is the official language of the Nubenetes ecosystem.
    • Native Preservation (V1 Archive): For non-English resources (e.g., Spanish repositories, videos, or articles), the V1 description MUST remain in the resource's native language to preserve its original context and cater to native speakers.
    • Global Synthesis (V2 Portal): To ensure 100% global discoverability, the V2 Elite summaries (ai_summary) MUST always be in Professional English, regardless of the source language.
    • V1 Immutability: For links already present in the V1 archive, AI agents MUST NOT overwrite manually curated titles, stars, or additional descriptive comments. Only broken URLs or missing metadata fields (like year/language) should be updated.
    • Rich Metadata Enrichment: AI agents SHOULD attempt to extract technical authors, video durations (YouTube), and reading times (Blogs) to populate high-density dimensions in the V2 portal.
    • Safety Guard Validation: Every automated PR MUST undergo syntax validation and a test MkDocs build to prevent broken rendering or security vulnerabilities in the final site.
    • Explicit Language Tagging: All non-English resources in the V2 Portal MUST be explicitly tagged (e.g., [SPANISH CONTENT], [FRENCH CONTENT]) at the end of the entry to inform global users before they navigate.
    • English-First Exceptions: Global software projects (even if created by Spanish speakers) that use English as their primary interface should be curated entirely in English. Native preservation is for localized content like blogs, videos, and guides.
11. Workflow-Config Synchronization: The GitHub Actions curation workflow form (agentic_cron.yml) MUST remain perfectly synchronized with the curation sources configuration file (data/curation_sources.yaml). Any addition, removal, or renaming of topics/categories in the configuration file requires a corresponding update to the workflow's input fields (checkboxes) to ensure users can toggle those sources manually. This maintains consistency between data-driven sources and the UI trigger.
12. V2 Elite Maintenance: The Nubenetes V2 (Agentic Elite) edition is a derived view of the V1 archive. It is managed via the src/v2_optimizer.py script and stored in the v2-docs/ directory.
    • Surgical Cleanup: The optimizer MUST perform surgical garbage collection in v2-docs/ after each run, deleting only orphaned files that are no longer part of the current site architecture.
    • Synchronization: V2 is updated automatically whenever V1 (docs/) changes. Standard curation always targets V1 as the source of truth.
13. Detailed Logging for V2: When running the V2 Optimizer, agents MUST use unbuffered logging and detailed output messages. If the optimizer returns '0 links kept', the agent MUST investigate the logs to determine if it was due to AI selection or a parsing/API error.
14. Persistent V2 Caching: The V2 Optimizer MUST use a persistent cache file (data/centralized YAML inventory) to store AI evaluations (year, quality, category). This is mandatory to minimize API costs and ensure execution speed across 15k+ links.
15. GitHub Metadata Enrichment: For all github.com resources, the bot MUST attempt to fetch real-time metadata (stars, last commit) using the GitHub API. This data must be included in the V2 rendering to provide current context.
16. Resilient Link Health & Global Cleaning:
    • Health Checks: Every V2 generation and global cleaning cycle MUST perform asynchronous health checks using identity rotation (User-Agents) and multiple attempts (3x).
    • V1 Exhaustiveness: The IntelligentLinkChecker operating on V1 MUST preserve all technically valid links regardless of their age. Deletion is strictly reserved for definitively invalid links (404s, dead redirects, etc.).
    • V2 Elite Selection (MVQ): The V2VisionEngine MUST continue to apply the Minimum Viable Quality (MVQ) logic. GitHub repositories inactive for >4 years with low impact (stars < 30) are deprioritized or excluded ONLY from the V2 Elite edition to ensure freshness.
    • Foundational Protection: GitHub and 'Foundational' resources are exempt from automatic removal based on health, but may be flagged for review.
    • Consolidation & Policy: Truncation to root is strictly for dead links. Rules MUST follow data/link_rules.yaml.
17. Unified Curation Chronology: All curation workflows (V1 and V2) MUST utilize the same chronological and descriptive engine.
    • Extraction: Every new link MUST attempt to extract a publication year (URL, metadata, or AI inference).
    • Formatting: New links MUST follow the format - **(YYYY)** [Title](URL) 🌟 - Description. If year is 'N/A', the prefix is omitted.
    • Elite Descriptions: AI-generated descriptions MUST be professional, neutral, and focus on the technical value for a 2026 Cloud Architect.
18. Automated Branch Hygiene: To keep the repository clean and efficient, an automated cleanup MUST run every 15 days (1st and 15th) to delete remote branches already merged into develop. The branches master, develop, and gh-pages are strictly protected and MUST NEVER be deleted.
19. V1/V2 Asset Integrity & Rendering:
    • Source of Truth: V1 (docs/) is the absolute source of truth for assets. V2 portal (v2-docs/) MUST NOT duplicate folders; it uses symlinks or relative paths.
    • Rendering Fix (HTML in MD): All <center> tags MUST be defined as <center markdown="1"> and followed by a mandatory blank line before and after the content. This ensures MkDocs processes the Markdown within the HTML block.
    • Flat Asset Routing (SEO-Friendly): To prioritize SEO and clean URLs, both V1 (mkdocs.yml) and V2 (v2-mkdocs.yml) MUST have use_directory_urls: true. This ensures clean directory URLs (e.g., /kubernetes/ instead of /kubernetes.html). Standardize on root-relative paths for assets and <center markdown="1"> for HTML blocks to prevent any path breakages across directory levels.
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 (Fast-Track Single-File): All link metadata MUST be managed via the centralized file data/inventory.yaml.
    • Monolithic Efficiency: To maintain simplicity and speed in the "Fast-Track" mode, the inventory is kept as a single, high-density YAML file. This avoids the overhead of sharding and matrix management for standard runs.
    • 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).
      • source_provenance: Identifies the origin of the discovery (Twitter, RSS, Manual).
      • social_preview_url: OpenGraph/Social images to enrich the V2 visual experience.
      • mentions_count: Tracks resource popularity/rediscovery frequency.
      • addition_method: Tracks the resource addition origin ('manual' or 'automatic') to facilitate scaling metrics.
    • Persistence (MANDATORY): Every AI agent and workflow MUST load this file at startup, update it, and INJECT the modified YAML into the final PR payload if any change is detected. Discarding the database during a workflow run is a CRITICAL FAILURE.
    • Exhaustive Initialization: The system supports a FORCE_FULL_CHECK environment variable to bypass all caches (e.g., 21-day health cache) and force a full re-validation and re-enrichment of the entire 17k+ link archive.
    • No Trusted Bypassing: All domains, including high-trust ones (GitHub, Google, AWS), MUST be verified for link validity. Trusted status only grants a lower priority for aggressive scraper rotation, not a bypass for existence checks.
    • URL Protocol Integrity: All URLs MUST use the complete and correct protocol prefix (https:// or http://). AI agents MUST ensure that automated edits or mass cleanup tasks NEVER corrupt the protocol (e.g., by reducing https:// to https:/).
    • Manual Priority: AI agents MUST NOT overwrite existing manual descriptions or stars in the V1 archive files. Enrichment is strictly for the YAML database and the V2 portal.