CompanySite/.agents/seo-specialist/README.md

# SEO Specialist Agent - Structured Data Implementation

This directory contains documentation and tools for the structured data and rich snippets implementation on the WorkRoot IT Solutions website.

---

## Quick Links

📄 **[STRUCTURED_DATA.md](./STRUCTURED_DATA.md)** - Complete implementation documentation
✅ **[VALIDATION_CHECKLIST.md](./VALIDATION_CHECKLIST.md)** - Step-by-step validation guide
🔍 **[validate-structured-data.js](./validate-structured-data.js)** - Automated validation script

---

## Implementation Status

### ✅ Fully Implemented

All structured data and rich snippet requirements are **production-ready**:

| Feature | Status | Location |
|---------|--------|----------|
| **JSON-LD Schemas** | ✅ Complete | `src/layouts/BaseLayout.astro`, `src/components/SEO.astro` |
| **Open Graph Tags** | ✅ Complete | `src/layouts/BaseLayout.astro` |
| **Twitter Cards** | ✅ Complete | `src/layouts/BaseLayout.astro` |
| **Organization Schema** | ✅ Global | All pages |
| **WebSite Schema** | ✅ Global | All pages |
| **BlogPosting Schema** | ✅ Implemented | Blog posts |
| **BreadcrumbList Schema** | ✅ Implemented | Multiple pages |
| **FAQPage Schema** | ✅ Implemented | Homepage |
| **AboutPage Schema** | ✅ Implemented | About page |
| **ContactPage Schema** | ✅ Implemented | Contact page |
| **Service Schema** | ✅ Implemented | Services page |

---

## Quick Start

### Run Validation

After building the site, validate structured data:

```bash
# Build the site
npm run build

# Run validation
npm run validate:structured-data
```

Expected output:
```
✅ ALL VALIDATIONS PASSED!
Files Processed: 15
Total Schemas Found: 45
```

### Test in Production

After deployment, use these tools:

1. **Google Rich Results Test**
   ```
   https://search.google.com/test/rich-results
   Test URL: https://workroot.in/
   ```

2. **Schema.org Validator**
   ```
   https://validator.schema.org/
   Copy JSON-LD from page source
   ```

3. **Facebook Sharing Debugger**
   ```
   https://developers.facebook.com/tools/debug/
   Test URL: https://workroot.in/
   ```

4. **Twitter Card Validator**
   ```
   https://cards-dev.twitter.com/validator
   Test URL: https://workroot.in/
   ```

---

## Schema Types Overview

### Global Schemas (All Pages)

#### Organization Schema
```json
{
  "@type": "Organization",
  "name": "WorkRoot IT Solutions",
  "url": "https://workroot.in",
  "logo": {...},
  "aggregateRating": {
    "ratingValue": "4.9",
    "reviewCount": "127"
  }
}
```

#### WebSite Schema
```json
{
  "@type": "WebSite",
  "name": "WorkRoot IT Solutions",
  "potentialAction": {
    "@type": "SearchAction",
    "target": "https://workroot.in/blog?search={search_term_string}"
  }
}
```

### Page-Specific Schemas

| Schema | Used On | Purpose |
|--------|---------|---------|
| **BlogPosting** | Blog posts | Rich article cards with author, date, image |
| **BreadcrumbList** | Multiple pages | Navigation breadcrumbs in search results |
| **FAQPage** | Homepage | Expandable FAQ snippets in Google |
| **AboutPage** | About page | Enhanced about page listing |
| **ContactPage** | Contact page | Enhanced contact page listing |
| **Service** | Services page | Service offering details |

---

## SEO Benefits

### Traditional Search (Google, Bing)

✅ **Knowledge Graph** - Company info panel in search results
✅ **Sitelinks Search Box** - Direct site search from Google
✅ **Article Rich Results** - Blog posts with images, authors, dates
✅ **Breadcrumbs** - Navigation trail in SERPs
✅ **FAQ Snippets** - Expandable Q&A in search results
✅ **Star Ratings** - Review stars next to search results

### AI Search (ChatGPT, Claude, Perplexity)

✅ **Entity Recognition** - AI knows "WorkRoot IT Solutions" as a company
✅ **Citation Likelihood** - Structured data increases citation probability
✅ **Expertise Signals** - AI recognizes domain expertise areas
✅ **Fact Verification** - Structured data helps AI verify claims
✅ **Direct Answers** - FAQ schema provides extractable answers

---

## File Structure

```
.agents/seo-specialist/
├── README.md                      # This file
├── STRUCTURED_DATA.md             # Complete implementation docs
├── VALIDATION_CHECKLIST.md        # Post-deployment validation steps
└── validate-structured-data.js    # Automated validation script

src/
├── layouts/
│   └── BaseLayout.astro          # Global schemas + OG tags
├── components/
│   └── SEO.astro                 # Page-specific schemas component
└── pages/
    ├── index.astro               # Uses FAQPage schema
    ├── about.astro               # Uses AboutPage schema
    ├── contact.astro             # Uses ContactPage schema
    ├── services.astro            # Uses Service schema
    └── blog/
        └── [...slug].astro       # Uses BlogPosting schema
```

---

## Usage Examples

### Adding Schema to a New Page

```astro
---
import BaseLayout from '../layouts/BaseLayout.astro';
import SEO from '../components/SEO.astro';
---

<BaseLayout
  title="Page Title"
  description="Page description"
>
  <SEO
    slot="head"
    type="WebPage"
    breadcrumbs={[
      { name: 'Home', url: '/' },
      { name: 'Page Title', url: '/page' }
    ]}
  />

  <!-- Page content -->
</BaseLayout>
```

### Adding FAQ Schema

```astro
<SEO
  slot="head"
  type="FAQPage"
  faq={[
    {
      question: "How do I get started?",
      answer: "Contact us via our contact form or email."
    },
    {
      question: "What services do you offer?",
      answer: "We offer web development, mobile apps, and AI solutions."
    }
  ]}
/>
```

### Adding Service Schema

```astro
<SEO
  slot="head"
  type="Service"
  service={{
    name: "Web Development",
    description: "Custom web applications built with modern frameworks"
  }}
/>
```

---

## Maintenance

### Regular Tasks

**Weekly (First Month):**
- Monitor Google Search Console for structured data errors
- Check rich result impressions
- Review indexed pages

**Monthly:**
- Validate key pages with Rich Results Test
- Update FAQ content if needed
- Check for broken schemas

**Quarterly:**
- Full structured data audit
- Update Organization schema (ratings, team, services)
- Validate all schema types
- Test social sharing across platforms

### Updating Schemas

#### Update Aggregate Rating

Location: `src/layouts/BaseLayout.astro` (line 153-159)

```javascript
"aggregateRating": {
  "@type": "AggregateRating",
  "ratingValue": "4.9",  // Update this
  "reviewCount": "127",  // Update this
  "bestRating": "5",
  "worstRating": "1"
}
```

#### Add New Team Member

Location: `src/layouts/BaseLayout.astro` (line 113-116)

```javascript
"founder": {
  "@type": "Person",
  "name": "Sarah Chen"
}
```

#### Update Social Media Links

Location: `src/layouts/BaseLayout.astro` (line 140-145)

```javascript
"sameAs": [
  "https://twitter.com/workroot",
  "https://linkedin.com/company/workroot",
  // Add more as needed
]
```

---

## Common Issues & Solutions

### Error: "Missing required field 'image'"

**Solution:** BlogPosting schema requires an image with dimensions
```json
"image": {
  "@type": "ImageObject",
  "url": "https://workroot.in/image.jpg",
  "width": 1200,
  "height": 675
}
```

### Error: "Invalid URL"

**Solution:** Always use absolute URLs
- ❌ `/images/logo.png`
- ✅ `https://workroot.in/images/logo.png`

### Warning: "Recommended field missing"

**Solution:** Add recommended fields for better rich results
```json
{
  "@type": "BlogPosting",
  "dateModified": "2024-03-15T10:00:00Z",  // Recommended
  "keywords": "web, development, React",    // Recommended
  "wordCount": 1500                        // Recommended
}
```

### Open Graph Image Not Showing

**Checklist:**
- [ ] Image is publicly accessible (test in incognito)
- [ ] Using HTTPS URL
- [ ] Image size: 1200x630px (optimal)
- [ ] og:image:secure_url is set
- [ ] Clear Facebook cache with Debugger tool

---

## Performance Impact

Total overhead per page: **~3-5 KB**

| Component | Size | Impact |
|-----------|------|--------|
| Organization schema | ~1.2 KB | Minimal |
| WebSite schema | ~0.3 KB | Minimal |
| BlogPosting schema | ~0.8 KB | Minimal |
| Open Graph tags | ~0.5 KB | Minimal |
| Twitter Card tags | ~0.4 KB | Minimal |

**Conclusion:** Negligible impact, massive SEO benefit.

---

## Resources

### Validation Tools
- [Google Rich Results Test](https://search.google.com/test/rich-results)
- [Schema.org Validator](https://validator.schema.org/)
- [Facebook Sharing Debugger](https://developers.facebook.com/tools/debug/)
- [Twitter Card Validator](https://cards-dev.twitter.com/validator)
- [LinkedIn Post Inspector](https://www.linkedin.com/post-inspector/)

### Documentation
- [Schema.org Documentation](https://schema.org/)
- [Google Search Central](https://developers.google.com/search/docs/appearance/structured-data)
- [Open Graph Protocol](https://ogp.me/)
- [Twitter Cards Guide](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards)

### Monitoring
- [Google Search Console](https://search.google.com/search-console)
- [Google Analytics](https://analytics.google.com/)

---

## Next Steps

### Immediate (After Deployment)
1. Run `npm run validate:structured-data`
2. Test with Google Rich Results Test
3. Validate social sharing (Facebook, Twitter, LinkedIn)
4. Submit sitemap to Google Search Console
5. Monitor for indexing errors

### Future Enhancements
- [ ] Add Review schema for individual testimonials
- [ ] Implement Product schema (if selling products/services)
- [ ] Add HowTo schema for tutorial content
- [ ] Add VideoObject schema for video content
- [ ] Consider LocalBusiness schema for local SEO

---

## Contact

**Agent:** seo-specialist
**Last Updated:** 2026-03-21
**Status:** ✅ Production Ready

For questions or issues:
1. Check [STRUCTURED_DATA.md](./STRUCTURED_DATA.md) for detailed docs
2. Review [VALIDATION_CHECKLIST.md](./VALIDATION_CHECKLIST.md) for testing
3. Run validation script to diagnose issues