# AI access contract

This public interface is derived from the same published sources and rendered pages as the website. It never reads the private Obsidian vault, credentials, drafts, or arbitrary URLs. It does not grant rights to third-party media or promise search ranking.

## Reading order

1. `/llms.txt`: short, task-oriented guide, not the whole corpus.
2. `/ai/manifest.json`: version, coverage, collection links and capabilities.
3. `/ai/profile.json`: public artist identity, original bilingual biographies, CV links and cited canonical pages.
4. `/ai/catalog.json` or `/ai/collections/{kind}.json`: published page metadata; select a language rather than reading duplicate translations.
5. `/ai/pages/{id}.json` and `.md`: one full record; cite its canonical human URL. Original dialogue Markdown URLs remain available unchanged.
6. `/api/ai/search?q=...&lang=zh&kind=...&limit=5&offset=0` and `/api/ai/read?id=...&offset=0&limit=12000`: bounded lookup and transparent text pagination.
7. `/mcp`: official SDK, stateless read-only tools using the same search/read data. Official SDK v2 supports protocol `2026-07-28` discovery and `2025-11-25` stateless legacy clients; both are exercised by the client integration test.

## Shared data contract

- Page IDs: `sha256(canonical pathname).slice(0,16)` in lowercase hexadecimal, generated by the shared helper. Paths include trailing slash and language prefix.
- Catalog: `{schemaVersion:1, revision, total, items:[{id,url,path,title,description,lang,kind,alternates,markdownUrl,jsonUrl,contentHash,characters}]}`. All URLs are absolute, every path in the current public route manifest must be accounted for. `lang` is `en` or `zh`. `alternates` lists only real public translations.
- Record: catalog item fields plus `content` (complete Markdown), `source` (extraction method and canonical URL), optional `originalSources` (public originals), and source-grounded metadata. No generated summaries or conclusions inserted into dialogue content.
- Search index: `{schemaVersion:1, revision, items:[{id,title,description,lang,kind,url,text}]}`. `text` is complete extracted page text, not silently truncated. Response snippets are explicitly excerpts for discovery only.
- Kind: `page`, `profile`, `work`, `sketch`, `exhibition`, `project`, `dialogue`, `essay`, `music`, `press`, `research` according to route component; collection count assertions ensure no drops.
- Profile includes existing public Person identity, biographies and original CV references, not freshly inferred life facts or undated promotional statistics.
- Generation follows successful prerender. Missing/empty/unrendered pages fail the build, never fall back to metadata while claiming full content. Dialogue/essay records use published original Markdown where available, preserve speakers and provenance, and link readable canonical pages.
- The archive includes published page text and source links. It does not claim to transcribe audiovisual media, execute interactive works, or mirror third-party articles. Filtered/list pagination is represented by complete detail-page coverage and public catalog supplements.

## Operational boundaries

- Static exports have explicit MIME types, CORS for public readers, cache validators and discoverable links; JSON errors stay JSON, no SPA fallbacks for invalid API IDs.
- REST and MCP read only allowlisted generated files through Pages `env.ASSETS`; no arbitrary fetch, filesystem input, credentials, sessions, writes or inference costs.
- Request sizes, queries, limits and IDs are bounded. Pagination includes total, returned range, next offset and revision so clients can detect changes and fetch the entire record.
- Source HTML head includes guide, manifest, service description and per-page Markdown alternate. A visible footer link leads to `/ai/`; guides help discovery without hidden ranking instructions or fabricated Schema.org claims.
- Short term: full-route and original-text conservation, protocol/client integration tests, live MIME/header/error verification. Next: observed retrieval relevance improvements and asset-level provenance. Long term: a source-faithful public archive kept current by the normal website build.