index-ai

Appearance

Read the spec

index-ai / Quickstart

Implement index-ai on your site

A complete, copy-pasteable walkthrough covering Level 2a conformance — ending with a validator verdict. Levels 2b and 3 are explained in the specification, but the walkthrough stops at what the validator can check today.

Add the AI Manifest ​

Create /.well-known/index-ai.json at your site root with your identity, publisher, and freshness. Copy this minimal example and adapt it:

json
{
  "spec_version": "1.0-rc2",
  "identity": {
    "name": "My Technical Blog",
    "description": "Personal blog on distributed systems, Rust, and backend architecture.",
    "domain": "myblog.dev",
    "category": ["blog", "developer-tools", "rust"]
  },
  "publisher": { "role": "blog" },
  "freshness": {
    "content_updated_at": "2025-05-20T00:00:00Z",
    "refresh_frequency": "monthly"
  }
}

Deploying under a sub-path (e.g. GitHub Project Pages)?

A project page under user.github.io/repo/ cannot serve /.well-known/index-ai.json at the origin root — that path belongs to the platform. Use scoped discovery (SPEC §5.2) instead: serve the manifest at any public HTTPS URL and advertise it from every page's <head> with a rel="agent-manifest" link, e.g.:

html
<link rel="agent-manifest" href="/index-ai/.well-known/index-ai.json" type="application/json">

Declare the Agent View relative to the sub-path too: "access": { "agent_index": "/index-ai/agent-index.json" }.

Expose clean content endpoints ​

For each page you want agents to reach, serve a clean text version — no HTML, no navigation. The convention is a ?format=markdown query parameter returning Content-Type: text/markdown:

markdown
# /blog/rust-lifetimes?format=markdown
---
title: Understanding Rust Lifetimes
url: /blog/rust-lifetimes
updated: 2025-04-15
---

## Understanding Rust Lifetimes

Explains Rust lifetime annotations from first principles... (8400 chars)

Build the Agent Index ​

Create /agent-index.json declaring your nodes, their llm_url, and their measured content_chars — the NFC code point count of the content at that endpoint, not a guess:

json
{
  "generated": "2025-05-28T10:00:00Z",
  "spec_version": "1.0-rc2",
  "total_nodes": 1,
  "nodes": [
    {
      "id": "article-rust-lifetimes",
      "type": "article",
      "content": {
        "llm_summary": "Explains Rust lifetime annotations from first principles…",
        "llm_url": "/blog/rust-lifetimes?format=markdown",
        "content_chars": 8400,
        "content_chars_mode": "exact"
      }
    }
  ]
}

Run the validator ​

Deploy, then validate your implementation with the reference validator. The validator is never embedded in this site — npx runs in your terminal against your deployed URL:

Run it against your deployed site — this block shows the four deterministic demo states:

$ npx @hardmachinelabs/index-ai-validator validate https://your-site.com
validator — https://your-site.com
✓ /.well-known/index-ai.json found (3.1 KB) ✓ Schema valid — Level 1 ✓ /agent-index.json found (24 KB) ✓ content_chars_mode present on all nodes with content_chars ✓ content_chars verified against llm_url (18,400 NFC code points, mode: exact) ✓ 6 nodes with content_chars and llm_url — Level 2a ⚠ publisher.verification_hint not set ✓ Conformance: Level 2a — valid to ship

Partial conformance is valid to ship

Passing Level 1 but not Level 2 is not failure — you ship Level 1, and the validator reports exactly which level you reached.

Already running llms.txt or robots.txt?

index-ai coexists with both — it is additive, never a replacement. See the comparison.