@olives/devos 2.1.0

package/.agents/skills/security-review/references/xss.md

@@ -0,0 +1,336 @@
+# Cross-Site Scripting (XSS) Prevention Reference
+
+## Overview
+
+XSS occurs when applications include untrusted data in web pages without proper validation or escaping. Attackers can execute scripts in victims' browsers to hijack sessions, deface websites, or redirect users to malicious sites.
+
+## XSS Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Reflected** | Malicious script from current HTTP request | URL parameter rendered in response |
+| **Stored** | Malicious script stored in target server | Comment field saved and displayed |
+| **DOM-based** | Vulnerability in client-side code | JavaScript reads URL and writes to DOM |
+
+## Output Encoding by Context
+
+### HTML Body Context
+
+```javascript
+// VULNERABLE: innerHTML with user data
+element.innerHTML = userInput;
+
+// SAFE: Use textContent
+element.textContent = userInput;
+
+// SAFE: Use createTextNode
+document.createTextNode(userInput);
+```
+
+**HTML Entity Encoding**
+| Character | Encoding |
+|-----------|----------|
+| `<` | `&lt;` |
+| `>` | `&gt;` |
+| `&` | `&amp;` |
+| `"` | `&quot;` |
+| `'` | `&#x27;` |
+
+### HTML Attribute Context
+
+```html
+<!-- VULNERABLE: Unquoted attribute -->
+<input value=${userInput}>
+
+<!-- VULNERABLE: Event handler with user data -->
+<button onclick="doSomething('${userInput}')">
+
+<!-- SAFE: Quoted attribute with encoding -->
+<input value="${htmlEncode(userInput)}">
+```
+
+**Rules:**
+- Always quote attribute values
+- Never place user input in event handlers (`onclick`, `onerror`, etc.)
+- Use `setAttribute()` which auto-encodes
+
+### JavaScript Context
+
+```javascript
+// VULNERABLE: eval with user input
+eval(userInput);
+
+// VULNERABLE: setTimeout with string
+setTimeout("doSomething('" + userInput + "')", 1000);
+
+// VULNERABLE: Function constructor
+new Function("return " + userInput)();
+
+// SAFE: JSON encoding for data
+const data = JSON.parse(jsonString);
+
+// SAFE: setTimeout with function
+setTimeout(() => doSomething(userInput), 1000);
+```
+
+**Safe JavaScript Locations** (with proper encoding):
+- Inside quoted string values only
+- Never directly in script blocks
+
+### URL Context
+
+```javascript
+// VULNERABLE: User input in href
+element.href = userInput;
+
+// VULNERABLE: javascript: URL scheme
+<a href="javascript:${userInput}">
+
+// SAFE: Validate URL scheme
+const url = new URL(userInput);
+if (url.protocol === 'https:' || url.protocol === 'http:') {
+    element.href = url.toString();
+}
+
+// SAFE: Encode URL parameters
+const encoded = encodeURIComponent(userInput);
+```
+
+### CSS Context
+
+```css
+/* VULNERABLE: User input in style */
+.element { background: url(${userInput}); }
+
+/* VULNERABLE: Expression in CSS */
+.element { behavior: expression(${userInput}); }
+```
+
+**Rules:**
+- Place user data only in CSS property values
+- Never allow user input in selectors or URLs
+
+---
+
+## Safe DOM Sinks
+
+**Use These:**
+```javascript
+elem.textContent = variable;
+elem.insertAdjacentText('beforeend', variable);
+elem.className = variable;  // for class names
+elem.setAttribute('data-value', variable);
+formField.value = variable;
+document.createTextNode(variable);
+```
+
+**Avoid These:**
+```javascript
+elem.innerHTML = variable;        // XSS
+elem.outerHTML = variable;        // XSS
+document.write(variable);         // XSS
+document.writeln(variable);       // XSS
+eval(variable);                   // Code execution
+setTimeout(variable);             // If string argument
+setInterval(variable);            // If string argument
+new Function(variable);           // Code execution
+elem.insertAdjacentHTML();        // XSS
+elem.onevent = variable;          // Event handler
+```
+
+---
+
+## Framework-Specific Considerations
+
+### React
+
+```jsx
+// SAFE: Auto-escaped by default
+<div>{userInput}</div>
+
+// VULNERABLE: dangerouslySetInnerHTML
+<div dangerouslySetInnerHTML={{__html: userInput}} />
+
+// SAFE: Sanitize before using dangerouslySetInnerHTML
+import DOMPurify from 'dompurify';
+<div dangerouslySetInnerHTML={{__html: DOMPurify.sanitize(userInput)}} />
+```
+
+### Angular
+
+```typescript
+// SAFE: Auto-escaped by default
+<div>{{ userInput }}</div>
+
+// VULNERABLE: bypassSecurityTrust*
+this.sanitizer.bypassSecurityTrustHtml(userInput);
+
+// Use bypassSecurityTrust* only with sanitized input
+```
+
+### Vue
+
+```html
+<!-- SAFE: Auto-escaped -->
+<div>{{ userInput }}</div>
+
+<!-- VULNERABLE: v-html directive -->
+<div v-html="userInput"></div>
+
+<!-- SAFE: Sanitize first -->
+<div v-html="sanitizedInput"></div>
+```
+
+### Django/Jinja2
+
+```django
+<!-- SAFE: Auto-escaped by default -->
+{{ user_input }}
+
+<!-- VULNERABLE: |safe filter -->
+{{ user_input|safe }}
+
+<!-- VULNERABLE: {% autoescape off %} -->
+{% autoescape off %}
+    {{ user_input }}
+{% endautoescape %}
+```
+
+---
+
+## HTML Sanitization
+
+When users must submit HTML (rich text editors), use a sanitization library.
+
+```javascript
+// Recommended: DOMPurify
+import DOMPurify from 'dompurify';
+
+const clean = DOMPurify.sanitize(dirty);
+
+// With configuration
+const clean = DOMPurify.sanitize(dirty, {
+    ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a'],
+    ALLOWED_ATTR: ['href']
+});
+```
+
+**Key Points:**
+- Keep sanitization libraries updated
+- Configure allowed tags/attributes based on needs
+- Sanitize on output, not just input
+
+---
+
+## Content Security Policy (CSP)
+
+CSP provides defense-in-depth but should not be the primary XSS defense.
+
+### Strict CSP (Recommended)
+
+```
+Content-Security-Policy:
+    default-src 'self';
+    script-src 'nonce-{RANDOM}' 'strict-dynamic';
+    object-src 'none';
+    base-uri 'none';
+```
+
+### Nonce-Based Approach
+
+```html
+<!-- Server generates unique nonce per request -->
+<script nonce="r4nd0m123">
+    // Allowed script
+</script>
+
+<script>
+    // Blocked - no nonce
+</script>
+```
+
+### Hash-Based Approach
+
+```
+Content-Security-Policy: script-src 'sha256-base64hash...'
+```
+
+---
+
+## DOM-based XSS Prevention
+
+### Dangerous Sources
+
+```javascript
+// Attacker-controllable sources
+location.hash
+location.search
+document.referrer
+window.name
+postMessage data
+```
+
+### Prevention
+
+```javascript
+// VULNERABLE: Direct use of source in sink
+element.innerHTML = location.hash.slice(1);
+
+// SAFE: Validate and encode
+const hash = location.hash.slice(1);
+if (/^[a-zA-Z0-9-]+$/.test(hash)) {
+    element.textContent = hash;
+}
+```
+
+---
+
+## Key Grep Patterns for Detection
+
+```bash
+# Dangerous DOM sinks
+grep -rn "innerHTML\|outerHTML\|document\.write" --include="*.js" --include="*.jsx"
+grep -rn "dangerouslySetInnerHTML" --include="*.jsx" --include="*.tsx"
+grep -rn "v-html" --include="*.vue"
+grep -rn "\|safe\|autoescape off" --include="*.html" --include="*.jinja"
+
+# Dangerous JavaScript
+grep -rn "eval(\|Function(\|setTimeout.*string\|setInterval.*string" --include="*.js"
+
+# Framework bypasses
+grep -rn "bypassSecurityTrust" --include="*.ts"
+grep -rn "mark_safe\|SafeString" --include="*.py"
+```
+
+---
+
+## Testing Payloads
+
+**Basic:**
+```
+<script>alert('XSS')</script>
+<img src=x onerror=alert('XSS')>
+<svg onload=alert('XSS')>
+```
+
+**Attribute Escape:**
+```
+" onmouseover="alert('XSS')
+' onclick='alert("XSS")
+```
+
+**JavaScript Context:**
+```
+';alert('XSS')//
+\';alert(\'XSS\')//
+</script><script>alert('XSS')</script>
+```
+
+---
+
+## References
+
+- [OWASP XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)
+- [OWASP DOM-based XSS Prevention](https://cheatsheetseries.owasp.org/cheatsheets/DOM_based_XSS_Prevention_Cheat_Sheet.html)
+- [OWASP CSP Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Content_Security_Policy_Cheat_Sheet.html)
+- [CWE-79: Cross-site Scripting](https://cwe.mitre.org/data/definitions/79.html)

package/.agents/skills/seo-aeo-best-practices/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: seo-aeo-best-practices
+description: SEO and AEO best practices for metadata, Open Graph, sitemaps, robots.txt, hreflang, JSON-LD structured data, EEAT, and content optimized for search engines and AI answer surfaces. Use this skill when implementing page SEO, technical SEO, schema markup, international SEO, AI-overview readiness, or improving content for Google, ChatGPT, Perplexity, and similar assistants.
+---
+
+# SEO & AEO Best Practices
+
+Principles for optimizing content for both traditional search engines (SEO) and AI-powered answer engines (AEO). Includes Google's EEAT guidelines and structured data implementation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Implementing metadata and Open Graph tags
+- Creating sitemaps and robots.txt
+- Adding JSON-LD structured data
+- Optimizing content for featured snippets
+- Preparing content for AI assistants (ChatGPT, Perplexity, etc.)
+- Evaluating content quality using EEAT principles
+
+## Core Concepts
+
+### SEO (Search Engine Optimization)
+Optimizing content to rank well in traditional search results (Google, Bing).
+
+### AEO (Answer Engine Optimization)
+Optimizing content to be selected as authoritative answers by AI systems.
+
+### EEAT (Experience, Expertise, Authoritativeness, Trustworthiness)
+Google's framework for evaluating content quality.
+
+## References
+
+Start with the one reference that matches the task, such as technical SEO, structured data, EEAT, or AI-answer readiness. See `references/` for detailed guidance:
+- `references/eeat-principles.md` — EEAT implementation and author schema
+- `references/structured-data.md` — JSON-LD patterns (Article, FAQ, Breadcrumb, Product)
+- `references/technical-seo.md` — Technical SEO checklist (metadata, sitemaps, hreflang, robots.txt)
+- `references/aeo-considerations.md` — AI/AEO considerations (AI Overviews, crawler management)

package/.agents/skills/seo-aeo-best-practices/references/aeo-considerations.md

@@ -0,0 +1,159 @@
+# AI/AEO Considerations
+
+Answer Engine Optimization (AEO) prepares content to be selected as authoritative answers by AI systems like ChatGPT, Perplexity, Google AI Overviews, and Bing Copilot.
+
+## How AI Selects Answers
+
+AI systems evaluate content based on:
+
+1. **Clarity:** Is the answer direct and easy to extract?
+2. **Authority:** Is the source trustworthy?
+3. **Comprehensiveness:** Does it fully address the question?
+4. **Recency:** Is the information up to date?
+5. **Structure:** Can the AI parse and understand it?
+
+## Content Structure for AI
+
+### Direct Answers First
+Lead with the answer, then explain.
+
+**Bad:**
+> The history of JavaScript dates back to 1995 when Brendan Eich... [500 words later] ...JavaScript runs in the browser.
+
+**Good:**
+> JavaScript is a programming language that runs in web browsers. It was created in 1995 by Brendan Eich...
+
+### Clear Headings
+Use descriptive H2/H3 headings that match user questions.
+
+**Bad:** "Overview" → "Details" → "More Information"
+**Good:** "What is X?" → "How does X work?" → "When should you use X?"
+
+### Lists and Tables
+AI extracts structured information more easily than prose.
+
+```markdown
+## Benefits of Structured Content
+
+- **Reusability:** Use content across channels
+- **Flexibility:** Change presentation without changing content
+- **Scalability:** Manage large content volumes
+```
+
+### FAQ Format
+Question-answer pairs are ideal for AI extraction.
+
+```typescript
+// Schema for AI-friendly FAQs
+defineType({
+  name: 'faq',
+  type: 'document',
+  fields: [
+    defineField({ name: 'question', type: 'string' }),
+    defineField({ name: 'answer', type: 'text' }),
+    defineField({ name: 'category', type: 'reference', to: [{ type: 'faqCategory' }] }),
+  ]
+})
+```
+
+## Technical Implementation
+
+### Structured Data (Critical)
+JSON-LD helps AI understand content type and relationships.
+
+```typescript
+// FAQ structured data
+const faqSchema = {
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  mainEntity: faqs.map(faq => ({
+    "@type": "Question",
+    name: faq.question,
+    acceptedAnswer: {
+      "@type": "Answer",
+      text: faq.answer
+    }
+  }))
+}
+```
+
+### Canonical Content
+Ensure AI finds your authoritative version, not copies.
+
+- Set canonical URLs
+- Avoid duplicate content across pages
+- Use `rel="canonical"` for syndicated content
+
+### Freshness Signals
+AI systems prefer current information.
+
+- Display publish and update dates prominently
+- Update content regularly with substantive changes (superficial updates like changing dates without meaningful edits can be counterproductive)
+- Use `dateModified` in structured data
+
+## Content Quality Signals
+
+### Author Credentials
+AI systems increasingly check author authority.
+
+- Display author name and credentials
+- Link to author profiles
+- Include author structured data
+
+### Citations and Sources
+Linking to authoritative sources increases trust.
+
+- Cite primary sources
+- Link to studies, documentation, official sources
+- Avoid circular citations (sites citing each other)
+
+### Comprehensive Coverage
+AI prefers content that fully answers questions.
+
+- Cover related questions users might have
+- Include definitions for technical terms
+- Address common misconceptions
+
+## Google AI Overviews
+
+Google's AI Overviews (formerly SGE) now appear in many search results. To optimize:
+
+- **Be the cited source:** AI Overviews cite specific pages. Concise, authoritative answers increase citation likelihood.
+- **Structure for extraction:** Use clear headings, direct answers, and lists that AI can easily parse.
+- **Cover follow-up questions:** AI Overviews often address related queries. Anticipate and answer them on the same page or link to dedicated pages.
+- **Monitor in Search Console:** Google Search Console provides data on AI Overview impressions and clicks.
+
+## AI Crawler Management
+
+Make conscious decisions about which AI systems can crawl your content:
+
+- **robots.txt directives:** Use `User-agent: GPTBot`, `ClaudeBot`, `PerplexityBot`, `Google-Extended` to control access.
+- **Allowing crawlers** increases chances of being cited as a source in AI responses.
+- **Blocking crawlers** prevents content from being used in AI training (but may reduce AI citations).
+- Review your policy regularly — this is one of the most actively evolving areas of SEO.
+
+## Measuring AEO Success
+
+### Monitor AI Mentions
+Track when AI assistants cite your content:
+- Use Google Search Console's AI Overview data for impression and click tracking
+- Monitor referral traffic from AI platforms (Perplexity, ChatGPT, Bing Copilot)
+- Search for your brand + "according to" in AI assistants
+- Consider third-party AEO tracking tools for comprehensive monitoring
+
+### Track Zero-Click Queries
+If AI answers questions directly, traditional rankings matter less.
+
+### Featured Snippet Capture
+Featured snippets often become AI answers. Track which you own.
+
+## AEO vs SEO Balance
+
+AEO and SEO largely align—quality content serves both. Key differences:
+
+| Aspect | SEO Focus | AEO Focus |
+|--------|-----------|-----------|
+| Goal | Rank on page 1 | Be THE answer |
+| Format | Varies | Direct, structured |
+| Length | Often longer | Concise + comprehensive |
+| Links | Link building | Source citations |

package/.agents/skills/seo-aeo-best-practices/references/eeat-principles.md

@@ -0,0 +1,127 @@
+# EEAT Principles
+
+Google's EEAT framework (Experience, Expertise, Authoritativeness, Trustworthiness) guides how content quality is evaluated. This applies to both SEO rankings and AI answer selection.
+
+## The Four Pillars
+
+### Experience
+First-hand or life experience with the topic.
+
+**Signals:**
+- Personal anecdotes and case studies
+- "I tested this" content
+- Real-world results and screenshots
+- User-generated reviews
+
+**Implementation:**
+- Include author bios with relevant experience
+- Add "About the Author" sections
+- Feature customer testimonials
+- Show real examples, not just theory
+
+### Expertise
+Knowledge and skill in the subject area.
+
+**Signals:**
+- Credentials and qualifications
+- Depth of content coverage
+- Technical accuracy
+- Citations to authoritative sources
+
+**Implementation:**
+- Display author credentials
+- Link to primary sources
+- Cover topics comprehensively
+- Keep content technically accurate and updated
+
+### Authoritativeness
+Recognition as a go-to source in the field.
+
+**Signals:**
+- Backlinks from respected sites
+- Mentions in industry publications
+- Social proof and follower counts
+- Brand recognition
+
+**Implementation:**
+- Build thought leadership content
+- Contribute to industry publications
+- Maintain consistent publishing
+- Develop recognizable brand voice
+
+### Trustworthiness
+Accuracy, transparency, and legitimacy.
+
+**Signals:**
+- Clear authorship and contact info
+- Accurate, fact-checked content
+- Secure website (HTTPS)
+- Privacy policy and terms
+
+**Implementation:**
+- Display clear author attribution
+- Include publication and update dates
+- Provide contact information
+- Use HTTPS and maintain security
+
+## Sanity Implementation
+
+```typescript
+// Author schema with EEAT signals
+defineType({
+  name: 'author',
+  type: 'document',
+  fields: [
+    defineField({ name: 'name', type: 'string' }),
+    defineField({ name: 'role', type: 'string' }),
+    defineField({ name: 'bio', type: 'text' }),
+    defineField({ name: 'credentials', type: 'array', of: [{ type: 'string' }] }),
+    defineField({ name: 'image', type: 'image' }),
+    // sameAs: used for schema.org Person structured data output
+    defineField({ name: 'sameAs', type: 'array', of: [{ type: 'url' }],
+      description: 'Canonical profile URLs (LinkedIn, Twitter, etc.) for schema.org Person'
+    }),
+    // socialLinks: used for display purposes (platform icons, labels)
+    defineField({
+      name: 'socialLinks',
+      type: 'array',
+      of: [{ type: 'object', fields: [
+        defineField({ name: 'platform', type: 'string' }),
+        defineField({ name: 'url', type: 'url' })
+      ]}],
+      description: 'Social links for display in the UI. Use sameAs for structured data output.'
+    }),
+  ]
+})
+
+// Content with EEAT metadata
+defineType({
+  name: 'post',
+  fields: [
+    defineField({ name: 'author', type: 'reference', to: [{ type: 'author' }] }),
+    defineField({ name: 'publishedAt', type: 'datetime' }),
+    defineField({ name: 'updatedAt', type: 'datetime' }),
+    defineField({ 
+      name: 'reviewedBy', 
+      type: 'reference', 
+      to: [{ type: 'author' }],
+      description: 'Expert reviewer for fact-checking'
+    }),
+    defineField({
+      name: 'sources',
+      type: 'array',
+      of: [{ type: 'url' }],
+      description: 'Citations and references'
+    }),
+  ]
+})
+```
+
+## YMYL Considerations
+
+"Your Money or Your Life" topics (health, finance, legal, safety) require extra EEAT rigor:
+
+- Medical content reviewed by healthcare professionals
+- Financial advice from certified experts
+- Legal content reviewed by attorneys
+- Clear disclaimers where appropriate