geo-artifacts

name	geo-artifacts
description	Use when asked to generate or fix llms.txt, llms-full.txt or facts.json, make a site citable or ingestible by ChatGPT, Claude, Perplexity or Gemini, or publish machine-readable ground truth for AI crawlers.

GEO artifacts

Generate the three files that let generative engines ingest a site as ground truth: llms.txt (curated index), llms-full.txt (full corpus), and facts.json (structured facts). Each carries an explicit citation licence.

When to use

"Make us citable by AI", "generate llms.txt", "why doesn't Perplexity know about us", "update facts.json after publishing".

When NOT to use

• Diagnosing whether the files are already served correctly — that is audit.
• Page-level JSON-LD or AnswerBlocks — that is aeo-onpage (planned, not in v0.1.0).
• Submitting URLs to search engines — that is indexing (planned, not in v0.1.0).

Generation only writes the three artifacts. It never verifies they are actually served in production — that is audit, and the "After generating" section below.

Which path to take

Node, when the site's content lives in this repo. It consumes an already-materialized Page[] ({ url, title, description, answer }) that your own prebuild script gathers — e.g. from getPages(): Promise<Page[]> reading your CMS or database directly — so it sees draft flags, DB rows, and unpublished states a crawler cannot.

Python, for any other stack or an external site. It reconstructs the corpus itself by crawling the sitemap and the rendered HTML.

# Python / crawl path
python3 -m omnirank.cli geo --config omnirank.config.json --out public
# flags: url (optional, omit when using --config), --config PATH, --out DIR (default: public)

# Node / in-repo path — call generate(config, pages, outDir) from the site's own
# prebuild script, after gathering pages with your own getPages()

Both paths share the same field logic (licence block, sameAs null-dropping, the published gate on statistics) and were verified to emit byte-identical output for identical input, aside from generatedAt timestamp precision (Python emits microseconds, Node emits milliseconds — both valid RFC 3339 UTC).

Rules

1. These are physical files. Write them into publicDir at build time. Never serve them from a dynamic route — see references/serving-gotchas.md for the 403 this causes.
2. Wire generation into prebuild AND the deploy script. OpenNext runs next build, not npm run build, so a prebuild hook alone silently does nothing in production.
3. Never invent a statistic. facts.statistics carries only entries explicitly marked published: true. No published entries means the key is omitted entirely, not emitted empty.
4. Null sameAs values are dropped, not emitted as null. A null is an entity gap to fill, and offsite-entity (planned, not in v0.1.0) reports on it.
5. Never infer a content licence — but never refuse to generate either. geo.license has no default. These files are written into publicDir and published on the open web, so the licence text inside them is a real, standing grant of reuse rights over the site owner's content — not a suggestion OmniRank can guess. If geo.license is unset, generation treats it exactly like the explicit "none" opt-out: it proceeds and grants nothing, and (Python CLI only) omnirank geo prints a one-line notice to stderr naming the config key, so the "no rights" default isn't chosen silently. Set geo.license to a licence you have actually chosen (e.g. "CC-BY-4.0") to grant reuse rights, or to the explicit opt-out "none" (or JSON null) for sites that grant no reuse rights at all and to silence the notice — the citation block states plainly that no licence is granted instead of inventing one.

After generating

Verify the files actually serve — generation succeeding locally proves nothing about production:

curl -sI https://<site>/llms.txt      | head -1
curl -sI https://<site>/llms-full.txt | head -1
curl -sI https://<site>/facts.json    | head -1

All three must return 200. See references/facts-json.md for the schema and references/serving-gotchas.md for what a non-200 usually means.