fix(web): make the site legible to agents

[KacemMathlouthi]

npx is-agentic benday.kacemmathlouthi.dev scored the site 71/100: one essential failure, three recommended failures, four partials. This addresses everything that is fixable in this repository.

Markdown, for agents that would rather not parse HTML

Every route now builds a .md twin beside its HTML. vercel.json rewrites the page URL to it when the request accepts markdown, with Vary: Accept so a CDN cannot hand the HTML variant to a client that asked for markdown, and a <link rel="alternate" type="text/markdown"> points at the same file for clients that do not negotiate.

The prose lives in apps/web/content/*.md, but the preset catalogue and the prop table are substituted at build time from PRESETS and the rows the usage page renders, so the two representations cannot disagree about a default. That is why the prop table moved into src/lib/api.ts.

llms.txt is generated alongside, and leads with when to reach for benday and when not to.

Pages that say who is behind this

/about, /contact and /privacy. Privacy states what is true rather than what is customary: no analytics, no cookies, one localStorage key for the theme, the dropped logo never leaving the tab, and the one third-party request the site does make (the GitHub avatar in the footer).

Content a crawler can read

The homepage carried 1.7KB of prose inside 55KB of markup, most of it 21 live canvases. A short "How it works" section above the footer roughly doubles the readable text. The 404, which is served on every unknown URL, now lists every real page plus llms.txt, the sitemap and the registry payload in its body.

The homepage structured data described the author better than the project, so parsers picked out the Person. It now leads with SoftwareApplication, with the Person linked by @id carrying url and sameAs.

Two bugs found on the way

• turbo.json excluded **/*.md from the build hash. Now that content/*.md is a build input, a markdown-only edit was a cache hit and would have shipped stale pages. Narrowed to !*.md, which still keeps package-root READMEs and CHANGELOGs out.
• The generated files only existed after a build, so vite dev answered /llms.txt, /sitemap.xml and every .md with the SPA shell, which routes to the 404. The builders moved into src/lib/feeds.ts and a dev-only plugin serves them from the same module; output is byte-identical to the build.

Not addressed

Brand-name discoverability is off-site. The 404 stays HTML-only: serving it as markdown would mean either a 200, which tells agents every path exists, or a serverless function on an otherwise static site.

---

Summary by cubic

Serve markdown twins for every page and add an agent index so tools can consume the docs without parsing HTML. Also fix markdown-only cache misses and surface feeds in dev.

• Build outputs now include *.md per route, llms.txt, and sitemap.xml. vercel.json rewrites Accept: text/markdown requests to the page’s .md twin and sets Vary: Accept; <link rel="alternate" type="text/markdown"> is added to each page’s head.

• Move feed builders into src/lib/feeds.ts and add a dev-only Vite plugin to serve .md, llms.txt, and sitemap.xml byte-identically during vite dev. The SPA shell no longer swallows these URLs locally.

• Generate structured data that leads with SoftwareApplication (and links the Person by @id) so parsers identify the project, not only the author.

• Add /about, /contact, and /privacy; link them in the footer; expand the homepage with a short “How it works”; update the 404 to list all real pages plus llms.txt, the sitemap, and the registry payload.

• Unify the API prop table in src/lib/api.ts; the usage page and the markdown twin both render from the same source to avoid drift. Preset listings for markdown come from the runtime PRESETS.

• Centralize off-site URLs in src/lib/links.ts to keep references consistent across pages, footer, and structured data.

• Fix build caching: turbo.json now ignores only package-root *.md so edits in apps/web/content/*.md invalidate the build.

• Migration for new routes:

  • Add the route to PAGES in src/lib/seo.ts and create matching prose at apps/web/content/<file>.md (the prerender fails if missing).
  • Add the route to the markdown rewrite in both apps/web/vercel.json and the root vercel.json.

^{Written for commit 795b8f5. Summary will update on new commits.}