# Agent Instructions & Vibe Coding Guidelines

> [!IMPORTANT]
> **MANDATORY PRE-IMPLEMENTATION STEP**:
> Before writing, modifying, or testing any code in this repository, you MUST read:
> 1. This file: [GEMINI.md](file:///Users/sain/development/vibecodeguru/GEMINI.md)
> 2. The SEO checklist: [SEO.md](file:///Users/sain/development/vibecodeguru/SEO.md)

---

## 🚫 Common Vibe Coding Mistakes & SEO Traps

1. **Placeholder URL Leakage**
   - *Trap*: Leaving `https://example.com` in configuration (`site` key) or metadata layouts.
   - *Fix*: Keep configured site URL dynamic or set to the actual production domain.

2. **Div-Soup & Semantic Collapse**
   - *Trap*: Wrapping everything in generic nested `<div>` blocks instead of structural elements.
   - *Fix*: Use proper HTML5 semantic elements: `<header>`, `<nav>`, `<main>`, `<article>`, `<footer>`, `<aside>`, and clean hierarchy (`<h1>` down to `<h6>`).

3. **Relative Canonical Tags**
   - *Trap*: Writing relative paths like `<link rel="canonical" href="/blog">`.
   - *Fix*: Canonical URLs must be absolute (e.g., `https://vibecodeguru.com/blog`).

4. **Forgotten Alt/Sizing Attributes**
   - *Trap*: Omitting `alt`, `width`, or `height` tags on images, causing Layout Shifts (CLS).
   - *Fix*: Always use Astro's `<Image />` component with size/aspect ratios and descriptive alt text.

5. **Client-Side Rendering (CSR) Hydration Overuse**
   - *Trap*: Overusing `client:load` or `client:only` tags for simple static content, making it invisible to standard web crawlers.
   - *Fix*: Keep components static by default. Render on the server; hydrate only interactive parts.

6. **Invalid or Incomplete Schema Markup**
   - *Trap*: Writing invalid JSON-LD (e.g., trailing commas) or leaving out mandatory properties (like `author`, `datePublished`).
   - *Fix*: Double-check JSON-LD syntax and required schema properties.