@rotifer/playground 0.5.0-alpha.2 → 0.7.0

package/genes/seo-optimizer/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: seo-optimizer
+description: Optimize content for search engines. Improve keyword usage, meta descriptions, headings, and content structure for better ranking. Use when creating web content, blog posts, or any content intended for search discovery.
+---
+
+# SEO Optimizer
+
+**Goal**: Optimize content for search engine visibility and ranking.
+
+---
+
+## 1. Keyword Optimization
+
+### Keyword Placement
+
+```markdown
+## Required Positions
+
+1. Title tag - near the beginning
+2. H1 heading - include primary keyword
+3. First paragraph - within the first 100 words
+4. Subheadings (H2/H3) - include related keywords
+5. Conclusion - natural summary
+
+## Keyword Density
+
+- Primary keyword: 1-2%
+- Related keywords: naturally distributed
+- Avoid keyword stuffing
+```
+
+### Keyword Types
+
+| Type | Example | Purpose |
+|------|---------|---------|
+| Short-tail | SEO | Brand awareness |
+| Long-tail | how to optimize SEO | Targeted traffic |
+| Question | what is SEO | FAQ content |
+| Brand | company + product | Brand search |
+
+### Keyword Research
+
+```markdown
+## Tools
+
+- Google Keyword Planner
+- Ahrefs
+- SEMrush
+- Google Trends
+- Answer the Public
+
+## Selection Criteria
+
+1. Search volume: monthly search volume
+2. Competition: optimization difficulty
+3. Relevance: match with content
+4. Commercial value: conversion potential
+```
+
+---
+
+## 2. Title Optimization
+
+### Title Tag
+
+```markdown
+## Rules
+
+- Length: 50-60 characters
+- Include primary keyword
+- Brand name at the end
+- Compelling for clicks
+
+## Formula
+
+[Primary Keyword] - [Secondary Keyword/Value Prop] | [Brand]
+
+## Examples
+
+Good: Best Laptops 2025 - Top 10 Picks for Every Budget | TechReview
+Bad: Home Page | Company Name
+```
+
+### H1-H6 Structure
+
+```markdown
+## Hierarchy Rules
+
+H1: Main page title (only 1 per page)
+H2: Major sections
+H3: Subsections
+H4-H6: Further subdivisions
+
+## Example
+
+<h1>How to Learn Python Programming</h1>
+  <h2>Introduction to Python</h2>
+  <h2>Learning Path</h2>
+    <h3>Beginner Stage</h3>
+    <h3>Advanced Stage</h3>
+  <h2>Recommended Resources</h2>
+```
+
+---
+
+## 3. Meta Description
+
+### Rules
+
+```markdown
+## Length
+- Optimal: 150-160 characters
+- Mobile: 120 characters
+
+## Content Elements
+1. Include primary keyword
+2. Explain page value
+3. Include call to action
+4. Unique and compelling
+
+## Template
+
+[Problem/Pain point]? [Solution]. [Value statement]. [CTA]
+
+## Example
+
+Want to boost your website traffic? This article shares 10 practical SEO tips
+to help you increase organic search traffic by 50% in 3 months. Read now!
+```
+
+---
+
+## 4. Content Optimization
+
+### Content Structure
+
+```markdown
+## Ideal Structure
+
+1. Introduction (include keyword)
+2. Table of contents (anchor links)
+3. Body (organized with subheadings)
+4. Conclusion (keyword naturally included)
+5. CTA (related links/actions)
+
+## Content Length Guidelines
+
+| Type | Recommended Words |
+|------|-------------------|
+| News | 300-500 |
+| Blog post | 1000-2000 |
+| In-depth article | 2000-4000 |
+| Comprehensive guide | 4000+ |
+```
+
+### Readability for SEO
+
+```markdown
+## Recommendations
+
+- Paragraphs: 3-5 sentences
+- Sentences: 15-25 words
+- Use bullet lists
+- Add subheadings
+- Adequate whitespace
+```
+
+### Multimedia Optimization
+
+```markdown
+## Image Optimization
+
+1. File names: include keywords
+   Good: seo-optimization-tips.jpg
+   Bad: IMG_001.jpg
+
+2. Alt text: describe image + keyword
+   Good: alt="SEO optimization tips infographic"
+
+3. Compress images: reduce load time
+
+4. Use WebP format
+
+## Video Optimization
+
+- Add captions/transcripts
+- Optimize title and description
+- Add timestamps
+```
+
+---
+
+## 5. Link Strategy
+
+### Internal Links
+
+```markdown
+## Rules
+
+1. Link related pages to each other
+2. Anchor text includes keywords
+3. Links are natural and valuable
+4. Important pages receive more links
+
+## Anchor Text Types
+
+Good: Learn more about [SEO optimization tips]
+Good: Check out our [SEO beginner's guide]
+Bad: [Click here]
+Bad: Excessive exact-match anchors
+```
+
+### External Links
+
+```markdown
+## Principles
+
+1. Link to authoritative websites
+2. Add nofollow for ads/untrusted links
+3. Open external links in new window
+4. Regularly check for broken links
+```
+
+---
+
+## 6. Technical SEO
+
+### URL Optimization
+
+```markdown
+## Rules
+
+1. Include keywords
+2. Keep short and clear
+3. Use hyphens (-)
+4. Avoid special characters
+5. Use lowercase letters
+
+## Examples
+
+Good: /seo-optimization-guide
+Bad: /page?id=12345&category=seo
+Bad: /SEO_Optimization_Guide
+```
+
+### Page Speed
+
+```markdown
+## Core Web Vitals
+
+| Metric | Target | Description |
+|--------|--------|-------------|
+| LCP | <2.5s | Largest Contentful Paint |
+| FID | <100ms | First Input Delay |
+| CLS | <0.1 | Cumulative Layout Shift |
+
+## Optimization Methods
+
+1. Compress images
+2. Enable caching
+3. Reduce JavaScript
+4. Use CDN
+5. Optimize server response
+```
+
+---
+
+## 7. Checklist
+
+```markdown
+## SEO Optimization Checklist
+
+### Keywords
+- [ ] Primary keyword identified
+- [ ] Keyword appears in title
+- [ ] Keyword appears in first paragraph
+- [ ] Keyword density is moderate (1-3%)
+
+### Meta Information
+- [ ] Title tag optimized
+- [ ] Meta description optimized
+- [ ] H1-H6 hierarchy is correct
+
+### Content
+- [ ] Sufficient content length
+- [ ] Clear structure
+- [ ] Multimedia included
+- [ ] Good readability
+
+### Links
+- [ ] Appropriate internal links
+- [ ] Authoritative external links
+- [ ] No broken links
+
+### Technical
+- [ ] URL optimized
+- [ ] Images optimized
+- [ ] Mobile-friendly
+- [ ] Page speed meets targets
+```
+
+---
+
+## Quick Reference
+
+### SEO Writing Formulas
+
+```markdown
+1. Keyword + Number + Power word = Great title
+   Example: 7 SEO Tips to Double Your Traffic
+
+2. Problem + Solution + Value = Great description
+   Example: Struggling with SEO? 10 practical tips to boost your rankings
+
+3. Inverted pyramid = Great content
+   Conclusion → Arguments → Evidence
+```
+
+### Common Mistakes
+
+| Mistake | Impact | Fix |
+|---------|--------|-----|
+| Keyword stuffing | Penalty | Use naturally |
+| Thin content | Low ranking | Expand content |
+| Missing H1 | Poor structure | Add H1 |
+| No image alt | Poor accessibility | Add alt text |
+| Broken links | Bad UX | Regular audits |

package/genes/seo-optimizer/index.ts

@@ -0,0 +1,206 @@
+interface SEOInput {
+  content: string;
+  targetKeyword?: string;
+  url?: string;
+}
+
+interface SEOIssue {
+  severity: "error" | "warning" | "info";
+  rule: string;
+  message: string;
+  suggestion: string;
+}
+
+interface SEOOutput {
+  score: number;
+  issues: SEOIssue[];
+  keywordDensity: number;
+  wordCount: number;
+  headingStructure: {
+    h1Count: number;
+    h2Count: number;
+    h3Count: number;
+    hasProperHierarchy: boolean;
+  };
+  metaAnalysis: {
+    titleLength: number;
+    hasMetaDescription: boolean;
+    descriptionLength: number;
+  };
+  readabilityScore: number;
+}
+
+function countOccurrences(text: string, keyword: string): number {
+  if (!keyword) return 0;
+  const lower = text.toLowerCase();
+  const kw = keyword.toLowerCase();
+  let count = 0;
+  let pos = 0;
+  while ((pos = lower.indexOf(kw, pos)) !== -1) {
+    count++;
+    pos += kw.length;
+  }
+  return count;
+}
+
+function extractHeadings(content: string): { h1: string[]; h2: string[]; h3: string[] } {
+  const h1 = [...content.matchAll(/<h1[^>]*>(.*?)<\/h1>/gi)].map((m) => m[1]);
+  const h2 = [...content.matchAll(/<h2[^>]*>(.*?)<\/h2>/gi)].map((m) => m[1]);
+  const h3 = [...content.matchAll(/<h3[^>]*>(.*?)<\/h3>/gi)].map((m) => m[1]);
+
+  const mdH1 = [...content.matchAll(/^#\s+(.+)$/gm)].map((m) => m[1]);
+  const mdH2 = [...content.matchAll(/^##\s+(.+)$/gm)].map((m) => m[1]);
+  const mdH3 = [...content.matchAll(/^###\s+(.+)$/gm)].map((m) => m[1]);
+
+  return {
+    h1: [...h1, ...mdH1],
+    h2: [...h2, ...mdH2],
+    h3: [...h3, ...mdH3],
+  };
+}
+
+function stripHTML(html: string): string {
+  return html.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function extractMeta(content: string): { title: string; description: string } {
+  const titleMatch = content.match(/<title[^>]*>(.*?)<\/title>/i);
+  const descMatch = content.match(/<meta\s+name=["']description["']\s+content=["'](.*?)["']/i);
+  return {
+    title: titleMatch ? titleMatch[1] : "",
+    description: descMatch ? descMatch[1] : "",
+  };
+}
+
+function fleschKincaid(text: string): number {
+  const words = text.split(/\s+/).filter((w) => w.length > 0);
+  const sentences = text.split(/[.!?]+/).filter((s) => s.trim().length > 0);
+  if (words.length === 0 || sentences.length === 0) return 0;
+
+  let totalSyllables = 0;
+  for (const word of words) {
+    const clean = word.toLowerCase().replace(/[^a-z]/g, "");
+    const vowelGroups = clean.match(/[aeiouy]+/g);
+    totalSyllables += vowelGroups ? Math.max(vowelGroups.length, 1) : 1;
+  }
+
+  return Math.max(
+    0,
+    Math.min(100, 206.835 - 1.015 * (words.length / sentences.length) - 84.6 * (totalSyllables / words.length))
+  );
+}
+
+/**
+ * SEO Optimizer Gene
+ *
+ * Analyzes content for search engine optimization metrics.
+ * Checks keyword density, heading structure, meta tags, and readability.
+ */
+export async function express(input: SEOInput): Promise<SEOOutput> {
+  const content = (input.content || "").trim();
+  const keyword = (input.targetKeyword || "").trim();
+  const issues: SEOIssue[] = [];
+
+  if (!content) {
+    return {
+      score: 0,
+      issues: [{ severity: "error", rule: "no-content", message: "No content provided", suggestion: "Provide text or HTML content to analyze" }],
+      keywordDensity: 0,
+      wordCount: 0,
+      headingStructure: { h1Count: 0, h2Count: 0, h3Count: 0, hasProperHierarchy: false },
+      metaAnalysis: { titleLength: 0, hasMetaDescription: false, descriptionLength: 0 },
+      readabilityScore: 0,
+    };
+  }
+
+  const plainText = stripHTML(content);
+  const words = plainText.split(/\s+/).filter((w) => w.length > 0);
+  const wordCount = words.length;
+
+  // Word count analysis
+  if (wordCount < 300) {
+    issues.push({ severity: "warning", rule: "thin-content", message: `Content has only ${wordCount} words`, suggestion: "Aim for at least 300 words for better SEO" });
+  } else if (wordCount >= 1000) {
+    issues.push({ severity: "info", rule: "long-content", message: `Good content length: ${wordCount} words`, suggestion: "Long-form content tends to rank better" });
+  }
+
+  // Keyword analysis
+  let keywordDensity = 0;
+  if (keyword) {
+    const kwCount = countOccurrences(plainText, keyword);
+    keywordDensity = wordCount > 0 ? (kwCount / wordCount) * 100 : 0;
+
+    if (kwCount === 0) {
+      issues.push({ severity: "error", rule: "keyword-missing", message: `Target keyword "${keyword}" not found in content`, suggestion: "Include the target keyword naturally in your content" });
+    } else if (keywordDensity > 3) {
+      issues.push({ severity: "warning", rule: "keyword-stuffing", message: `Keyword density is ${keywordDensity.toFixed(1)}% (too high)`, suggestion: "Keep keyword density between 1-3% to avoid over-optimization" });
+    } else if (keywordDensity < 0.5) {
+      issues.push({ severity: "warning", rule: "keyword-low", message: `Keyword density is ${keywordDensity.toFixed(1)}% (too low)`, suggestion: "Include the keyword a few more times naturally" });
+    }
+  }
+
+  // Heading structure
+  const headings = extractHeadings(content);
+  const h1Count = headings.h1.length;
+  const h2Count = headings.h2.length;
+  const h3Count = headings.h3.length;
+
+  if (h1Count === 0) {
+    issues.push({ severity: "error", rule: "missing-h1", message: "No H1 heading found", suggestion: "Add exactly one H1 heading as the main title" });
+  } else if (h1Count > 1) {
+    issues.push({ severity: "warning", rule: "multiple-h1", message: `Found ${h1Count} H1 headings`, suggestion: "Use only one H1 heading per page" });
+  }
+
+  if (h2Count === 0 && wordCount > 300) {
+    issues.push({ severity: "warning", rule: "missing-h2", message: "No H2 headings found", suggestion: "Break content into sections with H2 headings" });
+  }
+
+  const hasProperHierarchy = h1Count === 1 && (h2Count > 0 || wordCount < 300);
+
+  if (keyword && h1Count > 0) {
+    const h1HasKeyword = headings.h1.some((h) => h.toLowerCase().includes(keyword.toLowerCase()));
+    if (!h1HasKeyword) {
+      issues.push({ severity: "warning", rule: "keyword-not-in-h1", message: "Target keyword not found in H1", suggestion: "Include the target keyword in your main heading" });
+    }
+  }
+
+  // Meta analysis
+  const meta = extractMeta(content);
+  const titleLength = meta.title.length;
+  const hasMetaDescription = meta.description.length > 0;
+  const descriptionLength = meta.description.length;
+
+  if (titleLength > 0 && titleLength < 30) {
+    issues.push({ severity: "warning", rule: "title-short", message: `Title is too short (${titleLength} chars)`, suggestion: "Aim for 50-60 characters in the title" });
+  } else if (titleLength > 60) {
+    issues.push({ severity: "warning", rule: "title-long", message: `Title is too long (${titleLength} chars)`, suggestion: "Keep title under 60 characters to prevent truncation in search results" });
+  }
+
+  if (hasMetaDescription && descriptionLength < 120) {
+    issues.push({ severity: "warning", rule: "description-short", message: `Meta description is short (${descriptionLength} chars)`, suggestion: "Aim for 150-160 characters" });
+  } else if (hasMetaDescription && descriptionLength > 160) {
+    issues.push({ severity: "warning", rule: "description-long", message: `Meta description is long (${descriptionLength} chars)`, suggestion: "Keep meta description under 160 characters" });
+  }
+
+  // Readability
+  const readabilityScore = Math.round(fleschKincaid(plainText) * 100) / 100;
+
+  if (readabilityScore < 30) {
+    issues.push({ severity: "warning", rule: "readability-low", message: `Readability score is low (${readabilityScore})`, suggestion: "Simplify sentences and use common words for better accessibility" });
+  }
+
+  // Score calculation
+  const errorCount = issues.filter((i) => i.severity === "error").length;
+  const warningCount = issues.filter((i) => i.severity === "warning").length;
+  const score = Math.max(0, Math.min(100, 100 - errorCount * 15 - warningCount * 5));
+
+  return {
+    score,
+    issues,
+    keywordDensity: Math.round(keywordDensity * 100) / 100,
+    wordCount,
+    headingStructure: { h1Count, h2Count, h3Count, hasProperHierarchy },
+    metaAnalysis: { titleLength, hasMetaDescription, descriptionLength },
+    readabilityScore,
+  };
+}

package/genes/seo-optimizer/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/genes/seo-optimizer/phenotype.json

@@ -0,0 +1 @@
+{"domain":"content.seo","description":"Optimize content for search engines. Improve keyword usage, meta descriptions, headings, and content structure for better ranking. Use when creating web content, blog posts, or any content intended for search discovery.","inputSchema":{"type":"object","properties":{"content":{"type":"string","description":"Plain text or HTML content to analyze"},"targetKeyword":{"type":"string","description":"Target keyword for density and placement checks"},"url":{"type":"string","description":"Optional URL for context"}},"required":["content"]},"outputSchema":{"type":"object","properties":{"score":{"type":"number","description":"SEO score 0-100"},"issues":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning","info"]},"rule":{"type":"string"},"message":{"type":"string"},"suggestion":{"type":"string"}},"required":["severity","rule","message","suggestion"]}},"keywordDensity":{"type":"number","description":"Keyword density percentage"},"wordCount":{"type":"number","description":"Total word count"},"headingStructure":{"type":"object","properties":{"h1Count":{"type":"number"},"h2Count":{"type":"number"},"h3Count":{"type":"number"},"hasProperHierarchy":{"type":"boolean"}},"required":["h1Count","h2Count","h3Count","hasProperHierarchy"]},"metaAnalysis":{"type":"object","properties":{"titleLength":{"type":"number"},"hasMetaDescription":{"type":"boolean"},"descriptionLength":{"type":"number"}},"required":["titleLength","hasMetaDescription","descriptionLength"]},"readabilityScore":{"type":"number","description":"Flesch-Kincaid reading ease 0-100"}},"required":["score","issues","keywordDensity","wordCount","headingStructure","metaAnalysis","readabilityScore"]},"dependencies":[],"version":"0.2.0","author":"rotifer-team","createdAt":1771939405686,"fidelity":"Native","transparency":"Open","source":"skill"}

package/genes/source-linker/.cloud-manifest.json

@@ -0,0 +1,6 @@
+{
+  "cloud_id": "b5758719-b757-4c4b-8019-a6da9f5ee983",
+  "owner": "Rotifer Protocol",
+  "version": "0.1.0",
+  "published_at": "2026-03-17T14:13:39.466Z"
+}

package/genes/source-linker/index.ts

@@ -0,0 +1,88 @@
+/**
+ * source-linker Gene (Native)
+ *
+ * Maps raw source file paths (e.g. "docs/getting-started.md") to
+ * human-readable titles and browsable URLs on rotifer.dev.
+ *
+ * Pure mapping — no network calls, no external dependencies.
+ */
+
+interface SourceLinkerInput {
+  answer: string;
+  sources: string[];
+  confidence?: number;
+}
+
+interface SourceLink {
+  title: string;
+  url: string;
+}
+
+interface SourceLinkerOutput {
+  text: string;
+  links: SourceLink[];
+  confidence: number;
+}
+
+const BASE_URL = "https://rotifer.dev";
+
+const TITLE_MAP: Record<string, string> = {
+  "docs/getting-started.md": "Getting Started",
+  "docs/getting-started.zh.md": "快速开始",
+  "docs/architecture-decisions.md": "Architecture Decisions",
+  "docs/cloud-binding-api.md": "Cloud Binding API",
+  "spec/rotifer-protocol-specification.md": "Protocol Specification",
+  "spec/rotifer-protocol-specification.zh.md": "协议规范",
+  "spec/rotifer-ir-specification.md": "IR Specification",
+  "spec/rotifer-ir-specification.zh.md": "IR 规范",
+  "README.md": "Rotifer Protocol Overview",
+  "README.zh.md": "轮虫协议概览",
+  "CONTRIBUTING.md": "Contributing Guide",
+  "CHANGELOG.md": "Changelog",
+  "FAQ.md": "FAQ",
+};
+
+function pathToTitle(source: string): string {
+  if (TITLE_MAP[source]) return TITLE_MAP[source];
+
+  const filename = source.split("/").pop() || source;
+  return filename
+    .replace(/\.(md|mdx|ts|json)$/, "")
+    .replace(/[-_]/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function pathToUrl(source: string): string {
+  const slug = source
+    .replace(/^(playground\/)?docs\//, "docs/")
+    .replace(/^(playground\/)?spec\//, "spec/")
+    .replace(/\.(md|mdx)$/, "")
+    .replace(/\.zh$/, "")
+    .replace(/\s+/g, "-")
+    .toLowerCase();
+
+  return `${BASE_URL}/${slug}`;
+}
+
+export async function express(input: SourceLinkerInput): Promise<SourceLinkerOutput> {
+  const sources = input.sources || [];
+  const seen = new Set<string>();
+  const links: SourceLink[] = [];
+
+  for (const source of sources) {
+    const normalized = source.trim();
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+
+    links.push({
+      title: pathToTitle(normalized),
+      url: pathToUrl(normalized),
+    });
+  }
+
+  return {
+    text: input.answer || "",
+    links,
+    confidence: input.confidence ?? 0,
+  };
+}

package/genes/source-linker/phenotype.json

@@ -0,0 +1,45 @@
+{
+  "domain": "content.linking",
+  "description": "Maps source file paths to human-readable titles and browsable URLs. Pure mapping logic, no network dependency.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "answer": { "type": "string", "description": "The synthesized answer (passed through)" },
+      "sources": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Source file paths from answer-synthesizer"
+      },
+      "confidence": { "type": "number" }
+    },
+    "required": ["answer", "sources"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "text": {
+        "type": "string",
+        "description": "The answer text (renamed for grammar-checker compatibility)"
+      },
+      "links": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "title": { "type": "string" },
+            "url": { "type": "string" }
+          },
+          "required": ["title", "url"]
+        }
+      },
+      "confidence": { "type": "number" }
+    },
+    "required": ["text", "links"]
+  },
+  "dependencies": [],
+  "version": "0.1.0",
+  "author": "rotifer-team",
+  "createdAt": 1772236800000,
+  "fidelity": "Native",
+  "transparency": "Open"
+}

package/genes/style-optimizer/.cloud-manifest.json

@@ -0,0 +1,6 @@
+{
+  "cloud_id": "b4e8d20f-b77e-45d9-bcda-2a960a5061d7",
+  "owner": "Rotifer Protocol",
+  "version": "0.1.0",
+  "published_at": "2026-03-17T14:13:41.251Z"
+}

package/genes/style-optimizer/.gene-manifest.json

@@ -0,0 +1,8 @@
+{
+  "geneId": "e21277e13eb1038c2070805ffd27baaff1c2cd3d3cb6aeae854ff604ecaf8ccc",
+  "name": "style-optimizer",
+  "domain": "content.style",
+  "fidelity": "Wrapped",
+  "wrappedAt": "2026-02-24T13:23:19.974Z",
+  "fromSkill": "../.cursor/skills/style-optimizer/SKILL.md"
+}