seo-graph AGENTS.md

AGENTS.md — seo-graph

This file is for AI coding agents (Claude Code, Cursor, Copilot, etc.) building sites that use @iannuttall/seo-graph-core and/or @iannuttall/seo-graph-astro. It explains what the library does, how the pieces fit together, and which schema.org entities to use for every common site type.

What this library does

seo-graph makes a site legible to AI agents and search engines from one toolkit, in two layers:

1. Schema graphs. Valid, linked schema.org JSON-LD @graph arrays from typed inputs. Instead of hand-writing JSON-LD (error-prone) or copying snippets from schema.org docs (inconsistent), you call piece builders that return strongly-typed entities, then wrap them in a @graph envelope.
2. Agent markdown. Deterministic Markdown representations of every page — rendered from the built HTML for arbitrary pages (with a strict exclusion contract so decorative markup never leaks) and straight from the source entry for content-collection pages — plus llms.txt, a route manifest, IndexNow, and an HTTP content-negotiation handler so agents can request Accept: text/markdown at the canonical URL.

Two packages:

• @iannuttall/seo-graph-core — Pure TypeScript, no framework dependency. Piece builders, ID factory, graph assembler, deduplication, the built-HTML → Markdown renderer, collection markdown renderer, route mapping, manifests, llms.txt, git-based lastmod, IndexNow manifest hashing. Use this from any runtime.
• @iannuttall/seo-graph-astro — Astro layer. agentMarkdown() build integration, collection markdown endpoints, schema endpoints and schema map, IndexNow key route, RFC 9727 api-catalog, Zod content helpers, and a Cloudflare Worker content-negotiation handler (./cloudflare subpath).

Portions of the schema layer derive from jdevalk/seo-graph (MIT, see NOTICE). The agent-markdown pipeline is original work first built for seoskill.dev.