@elyracode/seo 0.7.8

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.7.8] - 2026-05-23
+
+### Added
+- `seo_audit` tool: analyze project files for SEO and LLM readability issues
+- `seo_generate_llms_txt` tool: generate `llms.txt` from project content
+- `seo_generate_schema` tool: generate JSON-LD structured data for pages
+- `seo_generate_meta` tool: audit and generate missing meta tags
+- `elyra-seo` skill: SEO and LLM optimization best practices

package/README.md

@@ -0,0 +1,56 @@
+# @elyracode/seo
+
+SEO and LLM optimization extension for Elyra. Audits your project for SEO issues, generates structured data, creates `llms.txt` files, and ensures your content is discoverable by both search engines and AI assistants.
+
+## Install
+
+```bash
+elyra install @elyracode/seo
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `seo_audit` | Analyze project files for SEO and LLM readability issues |
+| `seo_generate_llms_txt` | Generate `llms.txt` and `llms-full.txt` from project content |
+| `seo_generate_schema` | Generate or fix JSON-LD structured data for pages |
+| `seo_generate_meta` | Audit and generate missing meta tags, OpenGraph, and Twitter Cards |
+
+## Usage
+
+The extension activates automatically when your project contains HTML, JSX, TSX, Vue, or Blade template files.
+
+### Audit a project
+
+```
+Audit this site for SEO and LLM readability
+```
+
+The agent runs `seo_audit` and reports issues across all template files: missing meta tags, absent structured data, images without alt text, missing `llms.txt`, heading hierarchy problems, and LLM readability concerns.
+
+### Generate llms.txt
+
+```
+Generate an llms.txt for this project
+```
+
+Creates a `llms.txt` following the specification at llmstxt.org, with sections for documentation, API references, and key pages extracted from your project structure.
+
+### Add structured data
+
+```
+Add JSON-LD structured data to the product pages
+```
+
+The agent analyzes page content and generates appropriate schema.org markup (Product, Article, FAQPage, Organization, etc.).
+
+## Included Skill
+
+The `elyra-seo` skill provides the agent with knowledge about:
+
+- SEO best practices and common pitfalls
+- `llms.txt` specification and format
+- Schema.org types for web content
+- LLM optimization patterns (structured content, entity definition, citable text)
+- OpenGraph and Twitter Card meta tag requirements

package/extensions/index.ts

@@ -0,0 +1,746 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join, relative } from "node:path";
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+import { Type } from "typebox";
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+interface AuditIssue {
+	file: string;
+	line?: number;
+	severity: "critical" | "high" | "medium" | "low";
+	category: string;
+	message: string;
+}
+
+interface PageMeta {
+	file: string;
+	hasTitle: boolean;
+	hasDescription: boolean;
+	hasCanonical: boolean;
+	hasOgTitle: boolean;
+	hasOgDescription: boolean;
+	hasOgImage: boolean;
+	hasTwitterCard: boolean;
+	hasJsonLd: boolean;
+	hasH1: boolean;
+	h1Count: number;
+	imagesWithoutAlt: number;
+	headingLevels: number[];
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+const TEMPLATE_EXTENSIONS = new Set([
+	".html",
+	".htm",
+	".jsx",
+	".tsx",
+	".vue",
+	".svelte",
+	".astro",
+	".blade.php",
+	".ejs",
+	".hbs",
+	".njk",
+	".erb",
+]);
+
+function isTemplateFile(filePath: string): boolean {
+	const name = basename(filePath);
+	if (name.endsWith(".blade.php")) return true;
+	return TEMPLATE_EXTENSIONS.has(extname(filePath));
+}
+
+function walkDir(dir: string, maxDepth = 8): string[] {
+	const results: string[] = [];
+	const ignored = new Set(["node_modules", ".git", ".next", ".nuxt", "dist", "build", ".output", "vendor", "__pycache__"]);
+
+	function walk(current: string, depth: number): void {
+		if (depth > maxDepth) return;
+		let entries: string[];
+		try {
+			entries = readdirSync(current);
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (ignored.has(entry) || entry.startsWith(".")) continue;
+			const full = join(current, entry);
+			try {
+				const stat = statSync(full);
+				if (stat.isDirectory()) {
+					walk(full, depth + 1);
+				} else if (stat.isFile() && isTemplateFile(full)) {
+					results.push(full);
+				}
+			} catch {
+				// Skip inaccessible files
+			}
+		}
+	}
+	walk(dir, 0);
+	return results;
+}
+
+function analyzePage(filePath: string, content: string): PageMeta {
+	const lower = content.toLowerCase();
+
+	// Title
+	const hasTitle = /<title[\s>]/i.test(content) || /["']title["']\s*:/i.test(content);
+
+	// Meta description
+	const hasDescription =
+		/meta\s[^>]*name\s*=\s*["']description["']/i.test(content) ||
+		/description\s*:/i.test(content);
+
+	// Canonical
+	const hasCanonical = /rel\s*=\s*["']canonical["']/i.test(content);
+
+	// OpenGraph
+	const hasOgTitle = /property\s*=\s*["']og:title["']/i.test(content);
+	const hasOgDescription = /property\s*=\s*["']og:description["']/i.test(content);
+	const hasOgImage = /property\s*=\s*["']og:image["']/i.test(content);
+
+	// Twitter
+	const hasTwitterCard = /name\s*=\s*["']twitter:card["']/i.test(content);
+
+	// JSON-LD
+	const hasJsonLd = /application\/ld\+json/i.test(content);
+
+	// Headings
+	const h1Matches = content.match(/<h1[\s>]/gi) ?? [];
+	const hasH1 = h1Matches.length > 0;
+	const h1Count = h1Matches.length;
+
+	// Heading levels used
+	const headingLevels: number[] = [];
+	for (let i = 1; i <= 6; i++) {
+		if (new RegExp(`<h${i}[\\s>]`, "i").test(content)) {
+			headingLevels.push(i);
+		}
+	}
+
+	// Images without alt
+	const imgTags = content.match(/<img\s[^>]*>/gi) ?? [];
+	let imagesWithoutAlt = 0;
+	for (const img of imgTags) {
+		if (!/alt\s*=\s*["'][^"']+["']/i.test(img)) {
+			imagesWithoutAlt++;
+		}
+	}
+
+	return {
+		file: filePath,
+		hasTitle,
+		hasDescription,
+		hasCanonical,
+		hasOgTitle,
+		hasOgDescription,
+		hasOgImage,
+		hasTwitterCard,
+		hasJsonLd,
+		hasH1,
+		h1Count,
+		imagesWithoutAlt,
+		headingLevels,
+	};
+}
+
+function auditPage(filePath: string, relPath: string, content: string): AuditIssue[] {
+	const issues: AuditIssue[] = [];
+	const meta = analyzePage(filePath, content);
+
+	if (!meta.hasTitle) {
+		issues.push({ file: relPath, severity: "critical", category: "meta", message: "Missing <title> tag" });
+	}
+	if (!meta.hasDescription) {
+		issues.push({ file: relPath, severity: "high", category: "meta", message: "Missing meta description" });
+	}
+	if (!meta.hasCanonical) {
+		issues.push({ file: relPath, severity: "medium", category: "meta", message: "Missing canonical URL" });
+	}
+	if (!meta.hasH1) {
+		issues.push({ file: relPath, severity: "high", category: "headings", message: "Missing H1 tag" });
+	}
+	if (meta.h1Count > 1) {
+		issues.push({
+			file: relPath,
+			severity: "medium",
+			category: "headings",
+			message: `Multiple H1 tags (${meta.h1Count})`,
+		});
+	}
+
+	// Check heading hierarchy
+	const sorted = [...meta.headingLevels].sort();
+	for (let i = 1; i < sorted.length; i++) {
+		if (sorted[i] - sorted[i - 1] > 1) {
+			issues.push({
+				file: relPath,
+				severity: "low",
+				category: "headings",
+				message: `Skipped heading level: H${sorted[i - 1]} to H${sorted[i]}`,
+			});
+		}
+	}
+
+	if (meta.imagesWithoutAlt > 0) {
+		issues.push({
+			file: relPath,
+			severity: "medium",
+			category: "accessibility",
+			message: `${meta.imagesWithoutAlt} image(s) without alt text`,
+		});
+	}
+	if (!meta.hasJsonLd) {
+		issues.push({
+			file: relPath,
+			severity: "medium",
+			category: "structured-data",
+			message: "No JSON-LD structured data found",
+		});
+	}
+	if (!meta.hasOgTitle || !meta.hasOgDescription || !meta.hasOgImage) {
+		const missing: string[] = [];
+		if (!meta.hasOgTitle) missing.push("og:title");
+		if (!meta.hasOgDescription) missing.push("og:description");
+		if (!meta.hasOgImage) missing.push("og:image");
+		issues.push({
+			file: relPath,
+			severity: "low",
+			category: "social",
+			message: `Missing OpenGraph tags: ${missing.join(", ")}`,
+		});
+	}
+	if (!meta.hasTwitterCard) {
+		issues.push({
+			file: relPath,
+			severity: "low",
+			category: "social",
+			message: "Missing Twitter Card meta tags",
+		});
+	}
+
+	return issues;
+}
+
+function formatIssues(issues: AuditIssue[]): string {
+	if (issues.length === 0) return "No issues found.";
+
+	const bySeverity = { critical: 0, high: 0, medium: 0, low: 0 };
+	for (const issue of issues) {
+		bySeverity[issue.severity]++;
+	}
+
+	const lines: string[] = [];
+	lines.push("## Summary");
+	lines.push("");
+	const total = issues.length;
+	const parts: string[] = [];
+	if (bySeverity.critical > 0) parts.push(`${bySeverity.critical} critical`);
+	if (bySeverity.high > 0) parts.push(`${bySeverity.high} high`);
+	if (bySeverity.medium > 0) parts.push(`${bySeverity.medium} medium`);
+	if (bySeverity.low > 0) parts.push(`${bySeverity.low} low`);
+	lines.push(`${total} issues found: ${parts.join(", ")}`);
+	lines.push("");
+
+	// Group by file
+	const byFile = new Map<string, AuditIssue[]>();
+	for (const issue of issues) {
+		const list = byFile.get(issue.file) ?? [];
+		list.push(issue);
+		byFile.set(issue.file, list);
+	}
+
+	for (const [file, fileIssues] of byFile) {
+		lines.push(`### ${file}`);
+		lines.push("");
+		for (const issue of fileIssues) {
+			const icon =
+				issue.severity === "critical"
+					? "[CRITICAL]"
+					: issue.severity === "high"
+						? "[HIGH]"
+						: issue.severity === "medium"
+							? "[MEDIUM]"
+							: "[LOW]";
+			lines.push(`- ${icon} ${issue.message}`);
+		}
+		lines.push("");
+	}
+
+	return lines.join("\n");
+}
+
+function detectSiteStructure(
+	cwd: string,
+): { pages: Array<{ title: string; path: string }>; framework: string | null } {
+	const pages: Array<{ title: string; path: string }> = [];
+	let framework: string | null = null;
+
+	// Detect framework
+	const pkgPath = join(cwd, "package.json");
+	if (existsSync(pkgPath)) {
+		try {
+			const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as Record<string, unknown>;
+			const deps = {
+				...(pkg.dependencies as Record<string, string> | undefined),
+				...(pkg.devDependencies as Record<string, string> | undefined),
+			};
+			if (deps.next) framework = "Next.js";
+			else if (deps.nuxt) framework = "Nuxt";
+			else if (deps.astro) framework = "Astro";
+			else if (deps.svelte || deps["@sveltejs/kit"]) framework = "SvelteKit";
+			else if (deps.vue) framework = "Vue";
+			else if (deps.react) framework = "React";
+		} catch {
+			// ignore
+		}
+	}
+	if (!framework && existsSync(join(cwd, "composer.json"))) {
+		framework = "Laravel";
+	}
+
+	// Scan for page-like routes
+	const routeDirs = [
+		"src/app",
+		"src/pages",
+		"pages",
+		"app",
+		"src/routes",
+		"routes",
+		"resources/views",
+		"resources/views/pages",
+	];
+
+	for (const dir of routeDirs) {
+		const fullDir = join(cwd, dir);
+		if (!existsSync(fullDir)) continue;
+		try {
+			const files = walkDir(fullDir, 3);
+			for (const file of files) {
+				const rel = relative(cwd, file);
+				const name = basename(file, extname(file))
+					.replace(/\.(page|route|view|blade)$/i, "")
+					.replace(/[-_]/g, " ")
+					.replace(/\b\w/g, (c) => c.toUpperCase());
+				if (name.toLowerCase() === "index" || name.toLowerCase() === "layout") continue;
+				pages.push({ title: name, path: `/${relative(fullDir, file).replace(extname(file), "")}` });
+			}
+		} catch {
+			// ignore
+		}
+	}
+
+	return { pages, framework };
+}
+
+function generateLlmsTxt(
+	cwd: string,
+	siteUrl: string,
+): string {
+	const { pages, framework } = detectSiteStructure(cwd);
+
+	// Try to extract site name from package.json
+	let siteName = "My Site";
+	const pkgPath = join(cwd, "package.json");
+	if (existsSync(pkgPath)) {
+		try {
+			const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as Record<string, unknown>;
+			if (typeof pkg.name === "string") {
+				siteName = pkg.name
+					.replace(/^@[^/]+\//, "")
+					.replace(/[-_]/g, " ")
+					.replace(/\b\w/g, (c) => c.toUpperCase());
+			}
+			if (typeof pkg.description === "string") {
+				siteName = `${siteName}\n\n> ${pkg.description}`;
+			}
+		} catch {
+			// ignore
+		}
+	}
+
+	const lines: string[] = [];
+	lines.push(`# ${siteName}`);
+	lines.push("");
+
+	if (pages.length > 0) {
+		lines.push("## Pages");
+		for (const page of pages.slice(0, 30)) {
+			const url = siteUrl.replace(/\/$/, "") + page.path;
+			lines.push(`- [${page.title}](${url})`);
+		}
+		lines.push("");
+	}
+
+	lines.push("## Optional");
+	lines.push(`- [Sitemap](${siteUrl.replace(/\/$/, "")}/sitemap.xml)`);
+	lines.push("");
+
+	if (framework) {
+		lines.push(`<!-- Framework: ${framework} -->`);
+	}
+
+	return lines.join("\n");
+}
+
+function auditMetaTags(cwd: string, targetPath?: string): string {
+	const files = targetPath
+		? [join(cwd, targetPath)]
+		: walkDir(cwd);
+
+	if (files.length === 0) {
+		return "No template files found to audit.";
+	}
+
+	const results: string[] = [];
+	let totalMissing = 0;
+
+	for (const file of files.slice(0, 50)) {
+		if (!existsSync(file)) continue;
+		const content = readFileSync(file, "utf-8");
+		const relPath = relative(cwd, file);
+		const meta = analyzePage(file, content);
+
+		const missing: string[] = [];
+		if (!meta.hasTitle) missing.push("title");
+		if (!meta.hasDescription) missing.push("meta description");
+		if (!meta.hasCanonical) missing.push("canonical URL");
+		if (!meta.hasOgTitle) missing.push("og:title");
+		if (!meta.hasOgDescription) missing.push("og:description");
+		if (!meta.hasOgImage) missing.push("og:image");
+		if (!meta.hasTwitterCard) missing.push("twitter:card");
+
+		if (missing.length > 0) {
+			totalMissing += missing.length;
+			results.push(`### ${relPath}`);
+			results.push(`Missing: ${missing.join(", ")}`);
+			results.push("");
+		}
+	}
+
+	if (results.length === 0) {
+		return "All scanned files have complete meta tags.";
+	}
+
+	return `## Meta Tag Audit\n\n${totalMissing} missing meta tags across ${results.length} files:\n\n${results.join("\n")}`;
+}
+
+// ── Extension ───────────────────────────────────────────────────────────────
+
+export default function (elyra: ExtensionAPI): void {
+	let cwd = "";
+
+	elyra.on("session_start", async (_event, ctx) => {
+		cwd = ctx.cwd;
+	});
+
+	// ── seo_audit ────────────────────────────────────────────────────────
+
+	const auditSchema = Type.Object({
+		path: Type.Optional(
+			Type.String({ description: "Relative path to audit. Omit to audit the entire project." }),
+		),
+	});
+
+	elyra.registerTool({
+		name: "seo_audit",
+		label: "SEO Audit",
+		description:
+			"Analyze project files for SEO and LLM readability issues. Checks meta tags, headings, structured data, images, OpenGraph, Twitter Cards, and llms.txt. Returns a prioritized list of issues by severity.",
+		parameters: auditSchema,
+		promptSnippet: "Audit a project for SEO and LLM readability issues",
+		async execute(_toolCallId, params) {
+			try {
+				const targetDir = params.path ? join(cwd, params.path) : cwd;
+				const files = walkDir(targetDir);
+
+				if (files.length === 0) {
+					return { content: [{ type: "text", text: "No template files (HTML, JSX, Vue, etc.) found to audit." }] };
+				}
+
+				const allIssues: AuditIssue[] = [];
+
+				// Check for llms.txt
+				const llmsTxtPaths = ["public/llms.txt", "static/llms.txt", "llms.txt"];
+				const hasLlmsTxt = llmsTxtPaths.some((p) => existsSync(join(cwd, p)));
+				if (!hasLlmsTxt) {
+					allIssues.push({
+						file: "(project root)",
+						severity: "low",
+						category: "llm",
+						message: "No llms.txt found. Generate one with seo_generate_llms_txt for better LLM discoverability.",
+					});
+				}
+
+				// Audit each file (limit to 50 to avoid overwhelming output)
+				for (const file of files.slice(0, 50)) {
+					const content = readFileSync(file, "utf-8");
+					const relPath = relative(cwd, file);
+					const issues = auditPage(file, relPath, content);
+					allIssues.push(...issues);
+				}
+
+				const filesScanned = Math.min(files.length, 50);
+				const header = `Scanned ${filesScanned} template file${filesScanned === 1 ? "" : "s"}${files.length > 50 ? ` (${files.length} total, showing first 50)` : ""}.\n\n`;
+				const report = header + formatIssues(allIssues);
+
+				return { content: [{ type: "text", text: report }] };
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return { content: [{ type: "text", text: `Audit error: ${msg}` }], isError: true };
+			}
+		},
+	});
+
+	// ── seo_generate_llms_txt ────────────────────────────────────────────
+
+	const llmsTxtSchema = Type.Object({
+		site_url: Type.String({
+			description: "The base URL of the site (e.g. https://example.com). Used to construct page links.",
+		}),
+		output_path: Type.Optional(
+			Type.String({
+				description: "Output path relative to project root. Default: public/llms.txt",
+			}),
+		),
+	});
+
+	elyra.registerTool({
+		name: "seo_generate_llms_txt",
+		label: "Generate llms.txt",
+		description:
+			"Generate an llms.txt file for LLM discoverability. Scans the project structure to find pages and routes, then creates a formatted llms.txt following the llmstxt.org specification. The generated file should be reviewed and edited by the user before deploying.",
+		parameters: llmsTxtSchema,
+		promptSnippet: "Generate llms.txt from project structure",
+		async execute(_toolCallId, params) {
+			try {
+				const content = generateLlmsTxt(cwd, params.site_url);
+				const outputPath = params.output_path ?? "public/llms.txt";
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Generated llms.txt content for ${params.site_url}.\n\nSuggested path: ${outputPath}\n\n---\n\n${content}\n\n---\n\nReview and edit the content above, then write it to ${outputPath} using the write tool. Add descriptions to each page link for better LLM context.`,
+						},
+					],
+				};
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return { content: [{ type: "text", text: `Generation error: ${msg}` }], isError: true };
+			}
+		},
+	});
+
+	// ── seo_generate_schema ──────────────────────────────────────────────
+
+	const schemaSchema = Type.Object({
+		file: Type.String({ description: "Relative path to the template file to analyze" }),
+		type: Type.Optional(
+			Type.String({
+				description:
+					"Schema.org type to generate (Article, Product, FAQPage, Organization, HowTo, LocalBusiness, Event, SoftwareApplication, BreadcrumbList). If omitted, the tool will suggest an appropriate type.",
+			}),
+		),
+	});
+
+	elyra.registerTool({
+		name: "seo_generate_schema",
+		label: "Generate Schema.org",
+		description:
+			"Analyze a template file and generate appropriate JSON-LD structured data. Returns the JSON-LD script tag to add to the page. If a schema.org type is not specified, suggests one based on the page content.",
+		parameters: schemaSchema,
+		promptSnippet: "Generate JSON-LD structured data for a page",
+		async execute(_toolCallId, params) {
+			try {
+				const filePath = join(cwd, params.file);
+				if (!existsSync(filePath)) {
+					return { content: [{ type: "text", text: `File not found: ${params.file}` }], isError: true };
+				}
+
+				const content = readFileSync(filePath, "utf-8");
+				const lower = content.toLowerCase();
+
+				// Detect existing JSON-LD
+				const existingLd = content.match(/<script\s+type\s*=\s*["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi);
+				let existingInfo = "";
+				if (existingLd && existingLd.length > 0) {
+					existingInfo = `\n\nExisting JSON-LD found (${existingLd.length} block${existingLd.length > 1 ? "s" : ""}):\n${existingLd.join("\n")}`;
+				}
+
+				// Suggest type if not provided
+				let suggestedType = params.type;
+				if (!suggestedType) {
+					if (/article|blog|post|news/i.test(params.file) || /datePublished|author|article/i.test(content)) {
+						suggestedType = "Article";
+					} else if (/product|price|buy|shop|cart/i.test(lower)) {
+						suggestedType = "Product";
+					} else if (/faq|question|answer/i.test(lower) || /<details/i.test(content)) {
+						suggestedType = "FAQPage";
+					} else if (/about|company|organization|team/i.test(lower)) {
+						suggestedType = "Organization";
+					} else if (/how.to|tutorial|guide|step/i.test(lower)) {
+						suggestedType = "HowTo";
+					} else if (/contact|address|phone|location/i.test(lower)) {
+						suggestedType = "LocalBusiness";
+					} else if (/event|conference|meetup|webinar/i.test(lower)) {
+						suggestedType = "Event";
+					} else {
+						suggestedType = "WebPage";
+					}
+				}
+
+				// Generate a template
+				const templates: Record<string, string> = {
+					Article: `{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "PAGE TITLE",
+  "author": { "@type": "Person", "name": "AUTHOR NAME" },
+  "datePublished": "YYYY-MM-DD",
+  "dateModified": "YYYY-MM-DD",
+  "image": "IMAGE URL",
+  "description": "PAGE DESCRIPTION"
+}`,
+					Product: `{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "PRODUCT NAME",
+  "description": "PRODUCT DESCRIPTION",
+  "image": "IMAGE URL",
+  "offers": {
+    "@type": "Offer",
+    "price": "PRICE",
+    "priceCurrency": "USD",
+    "availability": "https://schema.org/InStock"
+  }
+}`,
+					FAQPage: `{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "QUESTION 1",
+      "acceptedAnswer": { "@type": "Answer", "text": "ANSWER 1" }
+    }
+  ]
+}`,
+					Organization: `{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "ORG NAME",
+  "url": "SITE URL",
+  "logo": "LOGO URL",
+  "contactPoint": {
+    "@type": "ContactPoint",
+    "email": "EMAIL",
+    "contactType": "customer service"
+  }
+}`,
+					HowTo: `{
+  "@context": "https://schema.org",
+  "@type": "HowTo",
+  "name": "HOW-TO TITLE",
+  "step": [
+    { "@type": "HowToStep", "name": "Step 1", "text": "STEP DESCRIPTION" }
+  ]
+}`,
+					LocalBusiness: `{
+  "@context": "https://schema.org",
+  "@type": "LocalBusiness",
+  "name": "BUSINESS NAME",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "STREET",
+    "addressLocality": "CITY",
+    "addressCountry": "COUNTRY"
+  },
+  "telephone": "PHONE"
+}`,
+					Event: `{
+  "@context": "https://schema.org",
+  "@type": "Event",
+  "name": "EVENT NAME",
+  "startDate": "YYYY-MM-DD",
+  "location": { "@type": "Place", "name": "VENUE", "address": "ADDRESS" }
+}`,
+					SoftwareApplication: `{
+  "@context": "https://schema.org",
+  "@type": "SoftwareApplication",
+  "name": "APP NAME",
+  "operatingSystem": "Web",
+  "applicationCategory": "CATEGORY",
+  "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" }
+}`,
+					BreadcrumbList: `{
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+    { "@type": "ListItem", "position": 1, "name": "Home", "item": "URL" },
+    { "@type": "ListItem", "position": 2, "name": "PAGE", "item": "URL" }
+  ]
+}`,
+					WebPage: `{
+  "@context": "https://schema.org",
+  "@type": "WebPage",
+  "name": "PAGE TITLE",
+  "description": "PAGE DESCRIPTION",
+  "url": "PAGE URL"
+}`,
+				};
+
+				const template = templates[suggestedType] ?? templates.WebPage;
+
+				const output = [
+					`Suggested schema.org type for ${params.file}: **${suggestedType}**`,
+					existingInfo,
+					"",
+					"JSON-LD template to add inside `<head>`:",
+					"",
+					"```html",
+					`<script type="application/ld+json">`,
+					template,
+					"</script>",
+					"```",
+					"",
+					"Replace the UPPERCASE placeholders with actual values from the page content, then add this to the page using the edit tool.",
+				].join("\n");
+
+				return { content: [{ type: "text", text: output }] };
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return { content: [{ type: "text", text: `Schema generation error: ${msg}` }], isError: true };
+			}
+		},
+	});
+
+	// ── seo_generate_meta ────────────────────────────────────────────────
+
+	const metaSchema = Type.Object({
+		path: Type.Optional(
+			Type.String({ description: "Relative path to a specific file or directory. Omit to audit the entire project." }),
+		),
+	});
+
+	elyra.registerTool({
+		name: "seo_generate_meta",
+		label: "Audit Meta Tags",
+		description:
+			"Audit template files for missing meta tags (title, description, canonical, OpenGraph, Twitter Cards). Returns a per-file report of missing tags with recommendations.",
+		parameters: metaSchema,
+		promptSnippet: "Audit and report missing meta tags across the project",
+		async execute(_toolCallId, params) {
+			try {
+				const report = auditMetaTags(cwd, params.path);
+				return { content: [{ type: "text", text: report }] };
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return { content: [{ type: "text", text: `Meta tag audit error: ${msg}` }], isError: true };
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@elyracode/seo",
+  "version": "0.7.8",
+  "description": "SEO and LLM optimization for Elyra -- audit, structured data, llms.txt, meta tags",
+  "type": "module",
+  "keywords": [
+    "elyra-package",
+    "seo",
+    "llm-optimization",
+    "structured-data",
+    "schema-org"
+  ],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/seo"
+  },
+  "elyra": {
+    "extensions": [
+      "./extensions/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@elyracode/coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  }
+}

package/skills/elyra-seo/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: elyra-seo
+description: SEO and LLM optimization. Use when the user asks about SEO, meta tags, structured data, schema.org, llms.txt, search engine optimization, or making content discoverable by AI assistants.
+---
+
+# SEO and LLM Optimization
+
+## When to Use
+
+Use SEO tools when:
+- The user asks to improve SEO or search visibility
+- The project has HTML/JSX/Vue/Blade templates that serve web pages
+- The user asks about llms.txt, structured data, or schema.org
+- The user wants content to be discoverable by AI assistants (ChatGPT, Perplexity, Google AI Overviews)
+- The user asks about meta tags, OpenGraph, or Twitter Cards
+
+## Available Tools
+
+| Tool | Use when |
+|------|----------|
+| `seo_audit` | Analyzing a project or specific files for SEO and LLM readability issues |
+| `seo_generate_llms_txt` | Creating or updating llms.txt for LLM discoverability |
+| `seo_generate_schema` | Adding or fixing JSON-LD structured data on pages |
+| `seo_generate_meta` | Auditing and generating missing meta tags |
+
+## llms.txt Specification
+
+The `llms.txt` file lives at the root of a website (like robots.txt) and helps LLMs understand site content.
+
+Format:
+```
+# Site Name
+
+> Brief description of the site.
+
+## Section Name
+- [Page Title](https://example.com/page): Short description
+- [Another Page](https://example.com/other): Short description
+
+## Optional
+- [Less important page](https://example.com/extra): Description
+```
+
+Place at `public/llms.txt` (Next.js, Vite), `static/llms.txt` (Nuxt), or the web root.
+
+Optionally create `llms-full.txt` with expanded content for each page.
+
+## Schema.org Structured Data
+
+Use JSON-LD format in a `<script type="application/ld+json">` tag. Common types:
+
+| Page type | Schema.org type | Key properties |
+|-----------|----------------|----------------|
+| Article/blog post | `Article` | headline, author, datePublished, image |
+| Product page | `Product` | name, description, offers, image, review |
+| FAQ page | `FAQPage` | mainEntity (array of Question/Answer) |
+| Organization/about | `Organization` | name, url, logo, contactPoint |
+| How-to guide | `HowTo` | name, step (array of HowToStep) |
+| Local business | `LocalBusiness` | name, address, telephone, openingHours |
+| Event | `Event` | name, startDate, location, offers |
+| Recipe | `Recipe` | name, recipeIngredient, recipeInstructions |
+| Software | `SoftwareApplication` | name, operatingSystem, offers |
+| Breadcrumbs | `BreadcrumbList` | itemListElement (array of ListItem) |
+
+Always validate generated JSON-LD with Google's Rich Results Test patterns.
+
+## Meta Tags Checklist
+
+Every page should have:
+
+### Essential
+- `<title>` — 50-60 characters, unique per page
+- `<meta name="description">` — 150-160 characters, unique per page
+- `<meta name="viewport">` — responsive design
+- `<link rel="canonical">` — prevent duplicate content
+
+### OpenGraph (social sharing)
+- `og:title` — page title for social
+- `og:description` — description for social
+- `og:image` — preview image (1200x630px recommended)
+- `og:url` — canonical URL
+- `og:type` — website, article, product, etc.
+- `og:site_name` — site name
+
+### Twitter Cards
+- `twitter:card` — summary, summary_large_image
+- `twitter:title` — title
+- `twitter:description` — description
+- `twitter:image` — preview image
+
+## LLM Readability Patterns
+
+Content is more likely to be cited by AI assistants when:
+
+1. **Clear heading hierarchy** — H1 > H2 > H3, no skipped levels
+2. **Structured answers** — FAQ sections with `<details>`/`<summary>` or schema.org FAQPage
+3. **Entity definitions** — clear "X is Y" statements early in content
+4. **Citable paragraphs** — self-contained statements that can be extracted as quotes
+5. **Lists and tables** — structured data that LLMs can parse directly
+6. **Consistent terminology** — use the same term for the same concept throughout
+
+## Common SEO Issues
+
+| Issue | Impact | Fix |
+|-------|--------|-----|
+| Missing `<title>` | Critical | Add unique, descriptive title per page |
+| Missing meta description | High | Add unique description per page |
+| Images without `alt` | Medium | Add descriptive alt text |
+| Missing H1 | High | Add exactly one H1 per page |
+| Multiple H1 tags | Medium | Use only one H1, use H2+ for subheadings |
+| Skipped heading levels | Low | Use sequential heading levels |
+| Missing canonical URL | Medium | Add `<link rel="canonical">` |
+| No structured data | Medium | Add JSON-LD for page type |
+| Missing OpenGraph | Low | Add og: meta tags |
+| No llms.txt | Low | Generate with `seo_generate_llms_txt` |
+
+## Framework-Specific Locations
+
+| Framework | Meta tags | Structured data | llms.txt |
+|-----------|-----------|-----------------|----------|
+| Next.js (App Router) | `metadata` export or `<head>` in layout | `<script>` in page/layout | `public/llms.txt` |
+| Next.js (Pages Router) | `<Head>` component | `<Head>` with `<script>` | `public/llms.txt` |
+| Nuxt 3 | `useHead()` or `<Head>` | `useHead()` with script | `public/llms.txt` |
+| Laravel/Blade | `@section('meta')` or `<head>` | `<script>` in blade | `public/llms.txt` |
+| Astro | frontmatter + `<head>` | `<script>` in `<head>` | `public/llms.txt` |
+| Vite/SPA | `index.html` `<head>` | `index.html` `<head>` | `public/llms.txt` |