{"id":25,"type":"docs","title":"Public Content Contract v1","slug":"public-content-contract-v1","canonicalUrl":"https://docs.phatysd.me/content/public-content-contract-v1","status":"published","revision":2,"publishedAt":"2026-09-19T16:34:11.292Z","updatedAt":"2026-09-19T16:34:11.292Z","hierarchyPath":"Web Blog > Public Content","topics":["Content contract","Agent-readable content","API design"],"tags":["content","json","markdown","llms","api"],"related":[{"slug":"web-blog-agent-handbook","title":"Web Blog Agent Handbook","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/web-blog-agent-handbook"},{"slug":"building-agent-readable-knowledge-site","title":"Building an Agent-Readable Knowledge Site","type":"blog","canonicalUrl":"https://docs.phatysd.me/content/building-agent-readable-knowledge-site"}],"body":"# Public Content Contract v1\n\nThis is the stable contract for published Blog, Docs, and Template content on `docs.phatysd.me`. It is written for agents, integrations, and maintainers who need to discover and consume content without scraping the human UI.\n\n## Content types\n\n| Type | Purpose | Public route |\n| --- | --- | --- |\n| `blog` | Narrative articles, postmortems, and practical lessons | `/blog` and `/content/:slug` |\n| `docs` | Reference, runbook, contract, and how-to material | `/docs` and `/content/:slug` |\n| `template` | Structured design template with profile, tokens, and live examples | `/templates` and `/content/:slug` |\n\nThe type is part of the published identity. Do not silently change a document into a blog or template without an explicit content revision and metadata review.\n\n## Lifecycle\n\n| Status | Meaning | Publicly indexed? |\n| --- | --- | --- |\n| `draft` | Work in progress, editable by the owner | No |\n| `published` | Current public version | Yes |\n| `archived` | Intentionally withdrawn from public discovery | No |\n\nAll public queries filter for `status = 'published'`. A draft or archived record must not appear in the homepage, search results, hierarchy pages, sitemap, `llms.txt`, JSON, or Markdown representation.\n\n## Stable URLs\n\n```text\nHuman canonical page: /content/:slug\nMarkdown:            /content/:slug/markdown\nJSON:                /content/:slug/json\nXML discovery:       /sitemap.xml\nAgent discovery:     /llms.txt\n```\n\nThe human page is canonical. The Markdown and JSON representations describe the same published item and must preserve its identity, revision, freshness, and body. A slug is canonical after publication and must not be changed casually; create a deliberate redirect/migration plan if a slug is ever wrong.\n\n## JSON contract\n\nA successful JSON response contains:\n\n```json\n{\n  \"id\": 23,\n  \"type\": \"docs\",\n  \"title\": \"Public Content Contract v1\",\n  \"slug\": \"public-content-contract-v1\",\n  \"canonicalUrl\": \"https://docs.phatysd.me/content/public-content-contract-v1\",\n  \"status\": \"published\",\n  \"revision\": 1,\n  \"publishedAt\": \"2026-09-19T00:00:00.000Z\",\n  \"updatedAt\": \"2026-09-19T00:00:00.000Z\",\n  \"hierarchyPath\": \"Web Blog > Public Content\",\n  \"topics\": [\"Content contract\"],\n  \"tags\": [\"content\", \"json\"],\n  \"related\": [],\n  \"body\": \"# Public Content Contract v1\\n...\"\n}\n```\n\nTemplate items additionally expose validated `templateProfile`, `templateTokens`, and `templateExamples`. A consumer should ignore fields it does not understand and should not infer template semantics from arbitrary CSS.\n\nMissing content returns `404`. Never use `200` with an empty body for a missing slug. Public responses must not expose drafts, archived rows, owner-only fields, database credentials, or internal authorization decisions.\n\n## Markdown contract\n\nMarkdown begins with machine-readable front matter containing the same identity fields using snake_case names such as `canonical_url`, `published_at`, `updated_at`, and `revision`. The authored Markdown body follows unchanged. Agents that need a text-first representation should prefer this endpoint over parsing HTML.\n\n## Revision semantics\n\nPublishing a new version increments `revision`. The current row is updated and an immutable row is inserted into `content_revisions`. The revision number is monotonic per content item. Consumers can use it as a freshness signal, but should also compare `updatedAt`.\n\n## Discovery\n\n`llms.txt` is a compact index of published content. `sitemap.xml` is the search-engine-oriented index. Both should contain only canonical public URLs. An agent can start at `https://docs.phatysd.me/llms.txt`, follow a content URL, then choose `/markdown` or `/json` according to the task.\n\n## Source of truth\n\n- Repository sources: `docs/contracts/public-content.md`, `src/lib/agent-content.ts`, and `src/lib/public-content.ts`.\n- [Metadata and sitemap conventions](https://nextjs.org/docs/app/api-reference/file-conventions/metadata)\n- [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers)\n"}