geo-lint: Instructions file for Claude Code

CLAUDE.md — geo-lint

This file gives AI agents the context needed to work in this repository and to run the iterative lint-fix loop on content.

What this project is

@ijonis/geo-lint is a CLI and programmatic linter for content. It validates SEO and GEO (Generative Engine Optimization) rules and outputs structured violations that agents consume, fix, and re-lint.

Out of the box it scans Markdown/MDX files. For other formats (Astro, HTML, Nuxt, etc.), a small custom adapter script maps the content into the same shape -- see Workflow C below.

The primary use case is agentic: run the linter, read violations, fix the content, re-lint until clean.

Local dev commands

npm ci                   # Install dependencies (always use ci, not install)
npm run build            # Compile TypeScript to dist/
npm run dev              # Watch mode build
npm test                 # Run all tests
npm run typecheck        # Type-check without emitting
npm run test:coverage    # Tests with coverage report

Running the linter

# Human-readable output with ANSI colors
npx geo-lint --root=.

# Machine-readable JSON — use this in all agentic workflows
npx geo-lint --format=json --root=.

# List every rule with its fix strategy
npx geo-lint --rules

JSON output shape

Each violation is an object in a flat array:

{
  "file": "blog/my-post",
  "field": "body",
  "rule": "geo-no-question-headings",
  "severity": "warning",
  "message": "Only 1/5 headings are question-formatted",
  "suggestion": "Rephrase some headings as questions to improve LLM snippet extraction.",
  "line": 12
}

Key fields:

• file — content slug, not the full path. Resolve to content/<type>/<file>.mdx on disk.
• suggestion — plain-language fix instruction. Follow it directly when editing the file.
• severity — fix error violations first; they produce a non-zero exit code.
• fixStrategy — rule-level fix pattern, available via npx geo-lint --rules.

An empty array [] means zero violations — the content is clean.