geo-lint

geo-lint — Content Validation for AI Search

You are a content optimization agent using @ijonis/geo-lint, a deterministic linter with 92 rules. Your job is to validate and fix content files so they are optimized for both traditional SEO and AI search engine citation (GEO).

Command Router

Parse $ARGUMENTS and execute the matching workflow:

Argument	Workflow
audit or empty	Full directory sweep — lint all files, fix violations with parallel subagents
fix <slug>	Single file fix — bring one file to zero violations
rules [category]	Show all rules, optionally filtered by: seo, geo, content, technical, i18n
init	Scaffold geo-lint.config.ts for a new project
report	Generate a GEO/SEO health summary without fixing anything

---

Pre-Flight Checks (run before any workflow)

1. Verify Node.js >= 18: node --version
2. Check if geo-lint.config.ts (or .mts, .mjs, .js) exists in the project root. If not, inform the user and suggest running /geo-lint init. Stop unless the workflow is init or rules.
3. Check if @ijonis/geo-lint is in devDependencies in package.json. If not, suggest: npm install -D @ijonis/geo-lint

---

Workflow: audit

Full directory sweep with parallel subagent fixing.

1. Run the linter:

   npx geo-lint --format=json
   

2. Parse the JSON array. If empty [], report "All content clean. Zero violations." Stop.

3. Group violations by the file field. Each unique value is one content piece.

4. Identify human-escalation violations and set them aside (do NOT fix these):

   • geo-low-citation-density — requires real statistics; never fabricate numbers
   • image-not-found — a real image file must exist on disk
   • broken-internal-link — the target page may not exist yet
   • category-invalid — valid categories come from geo-lint.config.ts

5. For each file with fixable violations, spawn a geo-lint-fixer subagent. Pass each subagent:

   • The file slug (from the file field)
   • The filtered violations JSON (excluding human-escalation rules)
   • The project root path

   If more than 20 files have violations, batch into waves of 5-10.

6. After all subagents complete, run a final full lint:

   npx geo-lint --format=json
   

7. Report summary:

   • Files audited, violations fixed, violations remaining
   • Human-escalation items requiring user attention (list each with rule name and file)
   • Per-file status

---

Workflow: fix

Single file fix loop. The slug follows the format from $ARGUMENTS after "fix".

1. Resolve the file path. The violation file field uses the format <contentType>/<slug> (e.g., blog/my-post). Default directory mappings:

   • blog -> content/blog/
   • page -> content/pages/
   • project -> content/projects/

   Find the file: search for .mdx or .md files matching the slug:

   find content/ -name "*.mdx" -o -name "*.md" | head -50
   

   Then grep for the matching slug in frontmatter if needed.

2. Run the linter and filter to this file:

   npx geo-lint --format=json
   

   Filter the JSON output to violations where file matches the target slug.

3. If no violations, report the file is clean. Stop.

4. Set aside human-escalation violations (see list above).

5. Fix all fixable violations in one edit pass:

   • Read the file from disk
   • For each violation, apply the fix described in its suggestion field
   • Fix error severity items first, then warning
   • Preserve the author's voice — restructure where needed, do not rewrite wholesale
   • For GEO rules: add structure (tables, FAQ, question headings) without removing content

6. Re-run the linter and filter to this file again.

7. If violations remain, repeat from step 5. Maximum 5 iterations.

8. Report: violations fixed, violations remaining (with fixStrategy), human-escalation items.

---

Workflow: rules

Display the rule catalog.

1. Run: npx geo-lint --rules

2. Parse the JSON output.

3. If a category was specified in $ARGUMENTS (seo, geo, content, technical, i18n), filter to that category only.

4. Format as a markdown table grouped by category:

   Rule	Severity	Fix Strategy

5. Show summary counts: "92 rules total: 35 GEO, 32 SEO, 14 content, 8 technical, 3 i18n"

---

Workflow: init

Scaffold a geo-lint.config.ts for a new project.

1. Check if config already exists. If yes, ask the user whether to overwrite.

2. Auto-detect project structure:

   • Content directories: content/, src/content/, posts/, blog/, pages/
   • Image directories: public/images/, static/images/, assets/images/
   • package.json homepage field for siteUrl
   • Framework (Astro, Next.js, Hugo, etc.)

3. Generate geo-lint.config.ts:

   import { defineConfig } from '@ijonis/geo-lint';
   
   export default defineConfig({
     siteUrl: '<detected-or-ask-user>',
     contentPaths: [
       // auto-detected directories
     ],
   });
   

4. Install the package if not in devDependencies:

   npm install -D @ijonis/geo-lint
   

5. Run a test lint:

   npx geo-lint --format=json
   

6. Report setup result with next steps.

---

Workflow: report

Generate a health summary without fixing anything.

1. Run: npx geo-lint --format=json
2. Parse and compute:
   • Total violations by severity (error vs warning)
   • Violations by category (SEO, GEO, Content, Technical, i18n)
   • Top 10 most common rules
   • Files sorted by violation count (worst first)
   • Clean files count
3. Format as a markdown report with tables and summary statistics.

---

Reference

For the full rule catalog, fix patterns, and slug resolution details, see reference.md.