@ijonis/geo-lint 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-10
+
+### Added
+- `seo-schema-sameas-incomplete` — flags Organization schema with fewer than 2 sameAs entries for entity verification
+- `geo-author-not-person` — flags blog posts with organization names as author instead of a person
+- `seo-service-page-no-schema` — flags service pages without Service structured data
+- `technical-no-feed` — flags sites without RSS/Atom/JSON feeds declared in config
+- `technical-no-llms-txt` — flags sites without /llms.txt endpoint declared in config
+- New config fields: `geo.organizationSameAs`, `geo.servicePagePatterns`
+- New `technical` config section with `feedUrls` and `llmsTxtUrl`
+
+### Changed
+- Rule count increased from 92 to 97
+- `schema-rules.ts` now uses factory pattern (`createSchemaRules`) for config-aware rules
+
+## [0.1.6] - 2026-03-03
+
+### Added
+- Claude Code skill plugin for ecosystem distribution — geo-lint is now installable as a Claude Code skill via `/install-skill`
+- `/content-creator` skill for self-configuring content pipelines — auto-detects project framework, generates adapter scripts, and runs iterative lint-fix loops
+
+## [0.1.5] - 2026-02-20
+
+### Fixed
+- CLI now always exits with code `0` regardless of violation severity — the linter is advisory-only and never blocks CI/CD pipelines. Error/warning labels are preserved for prioritization.
+
+## [0.1.4] - 2026-02-20
+
+### Added
+- Full English/German language parity across all analyzers
+  - Locale-aware Flesch Reading Ease: EN formula (`206.835 - 1.015*ASL - 84.6*ASW`) and DE formula (`180 - ASL - 58.5*ASW`) with per-locale interpretation bands
+  - `estimateSyllables()` applies silent-e discount for English and compound-word adjustment for German
+  - `defaultLocale` added to `RuleContext`, populated from `config.i18n`
+  - Unified locale fallback chain: `item.locale` → `context.defaultLocale` → hardcoded default
+  - Removed hardcoded German assumption in slug-resolver permalink generation
+- 15 new readability tests covering both language formulas
+
+## [0.1.3] - 2026-02-20
+
+### Changed
+- README "Why this exists" section rewritten with the real motivation: running multiple content-heavy sites with no deterministic SEO/GEO validation tool
+- Stronger value framing in `docs/geo-rules.md` and `docs/rules.md`
+
 ## [0.1.2] - 2026-02-20
 
 ### Fixed
@@ -43,6 +86,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - MDX/Markdown content adapter with `gray-matter`
 - CLI with `--format=json`, `--rules`, `--root`, `--config` flags
 
+[0.1.6]: https://github.com/IJONIS/geo-lint/releases/tag/v0.1.6
+[0.1.5]: https://github.com/IJONIS/geo-lint/releases/tag/v0.1.5
+[0.1.4]: https://github.com/IJONIS/geo-lint/releases/tag/v0.1.4
+[0.1.3]: https://github.com/IJONIS/geo-lint/releases/tag/v0.1.3
 [0.1.2]: https://github.com/IJONIS/geo-lint/releases/tag/v0.1.2
 [0.1.1]: https://github.com/IJONIS/geo-lint/releases/tag/v0.1.1
 [0.1.0]: https://github.com/IJONIS/geo-lint/releases/tag/v0.1.0

package/README.md

@@ -5,11 +5,55 @@
 [![npm version](https://img.shields.io/npm/v/@ijonis/geo-lint)](https://www.npmjs.com/package/@ijonis/geo-lint)
 [![CI](https://img.shields.io/github/actions/workflow/status/ijonis/geo-lint/ci.yml?branch=main&label=CI)](https://github.com/IJONIS/geo-lint/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/IJONIS/geo-lint/blob/main/LICENSE)
+[![Claude Code Skill](https://img.shields.io/badge/Claude_Code-Skill-blueviolet)](https://github.com/IJONIS/geo-lint)
 
 ![geo-lint demo](docs/demo.gif)
 
 ---
 
+## Use with Claude Code
+
+Install the geo-lint skill in one command:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/IJONIS/geo-lint/main/install.sh | bash
+```
+
+Then in any Claude Code session:
+
+```
+/geo-lint audit        # Full sweep — find and fix all violations
+/geo-lint fix <slug>   # Fix a single content file
+/geo-lint rules        # Show all 97 rules with fix strategies
+/geo-lint init         # Set up geo-lint.config.ts for a new project
+/geo-lint report       # Generate a GEO/SEO health summary
+```
+
+The skill runs an autonomous lint-fix loop: scan your content, read structured violations, fix them using each violation's `suggestion` field, and re-lint until clean. Parallel subagents handle multiple files simultaneously.
+
+### Content Creation Pipeline
+
+The install also adds `/content-creator` -- a self-configuring content pipeline that creates SEO & GEO-optimized content matched to your project:
+
+```
+/content-creator setup      # Auto-discover your project + configure brand voice
+/content-creator create      # Create content with keyword research + validation
+/content-creator voice       # Analyze and adjust brand voice
+/content-creator calendar    # Plan monthly content calendar
+/content-creator refresh     # Update config when your project evolves
+```
+
+On first use, the skill scans your project to learn its framework, content schema, categories, and authors. It then asks a few questions about your brand voice and audience. From that point on, every piece of content is created with full project awareness and validated against geo-lint's 97 rules until clean -- zero manual intervention for mechanical quality.
+
+Or paste this into **any** AI agent (Claude Code, Cursor, Windsurf, Copilot):
+
+```
+Run npx geo-lint --format=json, then fix every violation using each
+violation's suggestion field. Re-run until the output is [].
+```
+
+---
+
 ## Why this exists
 
 I run multiple content-heavy sites and there was no deterministic way to validate whether my content was actually optimized -- not "probably fine," but actually checked against concrete rules. SEO linters exist, but they're either paid SaaS, not automatable, or completely ignore the structural patterns that AI search engines use when deciding what to cite.
@@ -18,7 +62,7 @@ So I built one. **GEO (Generative Engine Optimization)** is the practice of stru
 
 The goal was simple: install one tool, point your AI agent at it, and walk away. The agent runs the linter, reads the JSON violations, fixes the content, re-lints until clean -- across an entire site, no manual input. One command, both SEO and GEO validated.
 
-**92 rules: 35 GEO, 32 SEO, 14 content quality, 8 technical, 3 i18n.** Readability analysis inspired by Yoast SEO. We researched the current state of GEO and AEO to make sure the rules reflect what actually gets content cited -- not outdated advice.
+**97 rules: 36 GEO, 34 SEO, 14 content quality, 10 technical, 3 i18n.** Readability analysis inspired by Yoast SEO. We researched the current state of GEO and AEO to make sure the rules reflect what actually gets content cited -- not outdated advice.
 
 ---
 
@@ -117,15 +161,15 @@ components at build time.
 
 ---
 
-## All 92 Rules
+## All 97 Rules
 
 | Category | Rules | Severity Mix | Focus |
 |----------|-------|-------------|-------|
-| SEO | 32 | 6 errors, 26 warnings | Titles, descriptions, headings, slugs, OG images, canonical URLs, keywords, links, schema |
+| SEO | 34 | 6 errors, 28 warnings | Titles, descriptions, headings, slugs, OG images, canonical URLs, keywords, links, schema, sameAs, service pages |
 | Content | 14 | 2 errors, 12 warnings | Word count, readability, dates, categories, jargon density, repetition, vocabulary diversity, transition words, sentence variety |
-| Technical | 8 | 3 errors, 5 warnings | Broken links, image files, trailing slashes, external URLs, performance |
+| Technical | 10 | 3 errors, 7 warnings | Broken links, image files, trailing slashes, external URLs, performance, feeds, llms.txt |
 | i18n | 3 | 0 errors, 3 warnings | Translation pairs, locale metadata |
-| GEO | 35 | 0 errors, 35 warnings | AI citation readiness: E-E-A-T signals, content structure, freshness, RAG optimization |
+| GEO | 36 | 0 errors, 36 warnings | AI citation readiness: E-E-A-T signals, content structure, freshness, RAG optimization, author entity type |
 
 See the [complete rule reference](docs/rules.md) with descriptions and severity for every rule.
 
@@ -147,9 +191,13 @@ See the [complete rule reference](docs/rules.md) with descriptions and severity
 
 This linter is **deterministic** -- same content in, same violations out, every time. Your AI agent provides the creativity to fix the content; geo-lint provides the guardrails to verify it's correct. The loop runs until violations hit zero.
 
-### Try it now
+### Claude Code Plugin
 
-Paste this into **Claude Code**, **Cursor**, or any AI coding agent:
+Install the skill and use `/geo-lint audit` to validate and fix your entire content directory automatically. The skill runs the full lint-fix loop with parallel subagents -- one per file. See [Use with Claude Code](#use-with-claude-code) above.
+
+### Any AI Agent
+
+Paste this into **Cursor**, **Windsurf**, **Copilot**, or any AI coding agent:
 
 ```
 Run npx geo-lint --format=json, then fix every violation in the reported
@@ -265,6 +313,9 @@ Options:
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and how to add new rules. Changes are tracked in the [CHANGELOG](CHANGELOG.md).
 
+**Questions or ideas?** Open a [GitHub Discussion](https://github.com/IJONIS/geo-lint/discussions).
+**Bugs or feature requests?** Open a [GitHub Issue](https://github.com/IJONIS/geo-lint/issues).
+
 ## License
 
 [MIT](LICENSE)

package/dist/cli.cjs

@@ -179,7 +179,13 @@ var DEFAULT_CONFIG = {
       "Tabs",
       "Tab"
     ],
-    enabledContentTypes: ["blog"]
+    enabledContentTypes: ["blog"],
+    organizationSameAs: [],
+    servicePagePatterns: []
+  },
+  technical: {
+    feedUrls: [],
+    llmsTxtUrl: ""
   },
   i18n: {
     locales: ["de", "en"],
@@ -251,12 +257,18 @@ function mergeWithDefaults(user) {
       acronymAllowlist: user.geo?.acronymAllowlist ?? DEFAULT_CONFIG.geo.acronymAllowlist,
       vagueHeadings: user.geo?.vagueHeadings ?? DEFAULT_CONFIG.geo.vagueHeadings,
       genericAuthorNames: user.geo?.genericAuthorNames ?? DEFAULT_CONFIG.geo.genericAuthorNames,
-      allowedHtmlTags: user.geo?.allowedHtmlTags ?? DEFAULT_CONFIG.geo.allowedHtmlTags
+      allowedHtmlTags: user.geo?.allowedHtmlTags ?? DEFAULT_CONFIG.geo.allowedHtmlTags,
+      organizationSameAs: user.geo?.organizationSameAs ?? DEFAULT_CONFIG.geo.organizationSameAs,
+      servicePagePatterns: user.geo?.servicePagePatterns ?? DEFAULT_CONFIG.geo.servicePagePatterns
     },
     i18n: {
       locales: user.i18n?.locales ?? DEFAULT_CONFIG.i18n.locales,
       defaultLocale: user.i18n?.defaultLocale ?? DEFAULT_CONFIG.i18n.defaultLocale
     },
+    technical: {
+      feedUrls: user.technical?.feedUrls ?? DEFAULT_CONFIG.technical.feedUrls,
+      llmsTxtUrl: user.technical?.llmsTxtUrl ?? DEFAULT_CONFIG.technical.llmsTxtUrl
+    },
     rules: { ...DEFAULT_CONFIG.rules, ...user.rules ?? {} },
     thresholds: {
       title: { ...DEFAULT_CONFIG.thresholds.title, ...user.thresholds?.title ?? {} },
@@ -2607,12 +2619,72 @@ var datasetSchemaReadiness = {
     return results;
   }
 };
-var schemaRules = [
+var MIN_SAMEAS_ENTRIES = 2;
+function createSchemaSameAsRule(organizationSameAs) {
+  let hasFired = false;
+  return {
+    name: "seo-schema-sameas-incomplete",
+    severity: "warning",
+    category: "seo",
+    fixStrategy: "Add social profiles (LinkedIn, GitHub, Twitter), Wikidata QID, and Crunchbase URL to Organization schema sameAs array",
+    run: (_item) => {
+      if (hasFired) return [];
+      hasFired = true;
+      if (!organizationSameAs || organizationSameAs.length === 0) return [];
+      if (organizationSameAs.length < MIN_SAMEAS_ENTRIES) {
+        return [
+          {
+            file: "_site",
+            field: "schema",
+            rule: "seo-schema-sameas-incomplete",
+            severity: "warning",
+            message: `Organization sameAs has ${organizationSameAs.length} entry \u2014 include at least ${MIN_SAMEAS_ENTRIES} for entity verification`,
+            suggestion: "AI models use sameAs to verify entity identity. Include at least LinkedIn + one other profile (GitHub, Wikidata QID, Crunchbase)."
+          }
+        ];
+      }
+      return [];
+    }
+  };
+}
+function createServicePageSchemaRule(servicePagePatterns) {
+  return {
+    name: "seo-service-page-no-schema",
+    severity: "warning",
+    category: "seo",
+    fixStrategy: "Add Service structured data (JSON-LD) to service pages with name, description, provider, and areaServed.",
+    run: (item) => {
+      if (!servicePagePatterns || servicePagePatterns.length === 0) return [];
+      const matchesPattern = servicePagePatterns.some(
+        (pattern) => item.permalink.includes(pattern)
+      );
+      if (!matchesPattern) return [];
+      return [
+        {
+          file: getDisplayPath(item),
+          field: "schema",
+          rule: "seo-service-page-no-schema",
+          severity: "warning",
+          message: `Service page "${item.permalink}" should have Service structured data`,
+          suggestion: 'Service pages need schema markup to appear in AI answers for "[service] provider in [city]" queries. Add Service JSON-LD with name, description, provider, and areaServed.'
+        }
+      ];
+    }
+  };
+}
+var schemaStaticRules = [
   blogMissingSchemaFields,
   faqpageSchemaReadiness,
   breadcrumblistSchemaReadiness,
   datasetSchemaReadiness
 ];
+function createSchemaRules(geo) {
+  return [
+    ...schemaStaticRules,
+    createSchemaSameAsRule(geo.organizationSameAs),
+    createServicePageSchemaRule(geo.servicePagePatterns)
+  ];
+}
 
 // src/rules/keyword-coherence-rules.ts
 var MIN_SIGNIFICANT_WORDS = 2;
@@ -14644,6 +14716,58 @@ var geoMissingTldr = {
     return [];
   }
 };
+var ORG_AUTHOR_PATTERNS = [
+  /\bteam\b/i,
+  /\bredaktion\b/i,
+  /\beditorial\b/i,
+  /\beditors?\b/i,
+  /\bherausgeber\b/i,
+  /\bverlag\b/i,
+  /\bredaktionsteam\b/i
+];
+function createGeoAuthorNotPersonRule(brandName) {
+  return {
+    name: "geo-author-not-person",
+    severity: "warning",
+    category: "geo",
+    fixStrategy: "Replace organization name with individual author name. Use Person type in BlogPosting schema for stronger E-E-A-T signals.",
+    run: (item, context) => {
+      const geoTypes = context.geoEnabledContentTypes ?? ["blog"];
+      if (!geoTypes.includes(item.contentType)) return [];
+      if (!item.author || item.author.trim() === "") return [];
+      if (!brandName || brandName.trim() === "") return [];
+      const normalizedAuthor = item.author.trim().toLowerCase();
+      if (normalizedAuthor === brandName.trim().toLowerCase()) {
+        return [
+          {
+            file: getDisplayPath(item),
+            field: "author",
+            rule: "geo-author-not-person",
+            severity: "warning",
+            message: `Author "${item.author}" is the organization name \u2014 use a person's name instead`,
+            suggestion: "AI models cite named experts over faceless organizations. Use the actual author's name for stronger E-E-A-T signals."
+          }
+        ];
+      }
+      const matchesOrgPattern = ORG_AUTHOR_PATTERNS.some(
+        (pattern) => pattern.test(item.author)
+      );
+      if (matchesOrgPattern) {
+        return [
+          {
+            file: getDisplayPath(item),
+            field: "author",
+            rule: "geo-author-not-person",
+            severity: "warning",
+            message: `Author "${item.author}" appears to be an organization or team name`,
+            suggestion: "BlogPosting with author.@type: Person gets cited more than Organization. Use an individual person's name."
+          }
+        ];
+      }
+      return [];
+    }
+  };
+}
 var geoEeatStaticRules = [
   geoMissingSourceCitations,
   geoMissingExpertQuotes,
@@ -14656,7 +14780,8 @@ function createGeoEeatRules(geo) {
   return [
     ...geoEeatStaticRules,
     createGeoMissingAuthorRule(geo.genericAuthorNames ?? []),
-    createGeoHeadingTooVagueRule(geo.vagueHeadings ?? [])
+    createGeoHeadingTooVagueRule(geo.vagueHeadings ?? []),
+    createGeoAuthorNotPersonRule(geo.brandName)
   ];
 }
 
@@ -15645,6 +15770,68 @@ var contentQualityRules = [
   sentenceVariety
 ];
 
+// src/rules/technical-site-rules.ts
+function createNoFeedRule(feedUrls) {
+  let hasFired = false;
+  return {
+    name: "technical-no-feed",
+    severity: "warning",
+    category: "technical",
+    fixStrategy: "Add an RSS or JSON feed endpoint exposing blog posts with full content.",
+    run: (_item, _context) => {
+      if (hasFired) return [];
+      hasFired = true;
+      if (feedUrls === void 0) return [];
+      if (feedUrls.length === 0) {
+        return [
+          {
+            file: "_site",
+            field: "feed",
+            rule: "technical-no-feed",
+            severity: "warning",
+            message: "No RSS/Atom/JSON feed detected \u2014 AI systems lose a structured ingestion path",
+            suggestion: "Feeds provide a structured ingestion path for AI systems beyond crawler discovery. Add an RSS or JSON feed endpoint."
+          }
+        ];
+      }
+      return [];
+    }
+  };
+}
+function createNoLlmsTxtRule(llmsTxtUrl) {
+  let hasFired = false;
+  return {
+    name: "technical-no-llms-txt",
+    severity: "warning",
+    category: "technical",
+    fixStrategy: "Create a /llms.txt endpoint that maps your most important content for LLM consumption in Markdown format.",
+    run: (_item, _context) => {
+      if (hasFired) return [];
+      hasFired = true;
+      if (llmsTxtUrl === void 0) return [];
+      if (llmsTxtUrl.trim() === "") {
+        return [
+          {
+            file: "_site",
+            field: "llms-txt",
+            rule: "technical-no-llms-txt",
+            severity: "warning",
+            message: "No /llms.txt endpoint detected \u2014 missing the emerging standard for LLM content declaration",
+            suggestion: "llms.txt is the robots.txt equivalent for AI \u2014 trivial to add, future-proofs your site for LLM crawlers."
+          }
+        ];
+      }
+      return [];
+    }
+  };
+}
+function createTechnicalSiteRules(technical) {
+  return [
+    createNoFeedRule(technical.feedUrls),
+    createNoLlmsTxtRule(technical.llmsTxtUrl)
+  ];
+}
+
 // src/rules/index.ts
 function buildRules(config, linkExtractor) {
   const rules = [
@@ -15664,7 +15851,7 @@ function buildRules(config, linkExtractor) {
     ...createI18nRules(config.i18n),
     ...dateRules,
     ...config.categories.length > 0 ? createCategoryRules(config.categories) : [],
-    ...schemaRules,
+    ...createSchemaRules(config.geo),
     ...createGeoRules(config.geo),
     ...createGeoEeatRules(config.geo),
     ...geoStructureRules,
@@ -15672,7 +15859,8 @@ function buildRules(config, linkExtractor) {
     ...createGeoRagRules(config.geo),
     ...keywordCoherenceRules,
     ...createCanonicalRules(config.siteUrl),
-    ...contentQualityRules
+    ...contentQualityRules,
+    ...createTechnicalSiteRules(config.technical)
   ];
   return rules.map((rule) => applyRuleOverride(rule, config.rules));
 }
@@ -15856,8 +16044,7 @@ async function lint(options = {}) {
   } else {
     formatResults(results, lintableItems.length, excludedItems.length);
   }
-  const errorCount = results.filter((r) => r.severity === "error").length;
-  return errorCount > 0 ? 1 : 0;
+  return 0;
 }
 
 // src/cli.ts