bytechefhq / bytechefhq/bytechef
docs - Make docs.bytechef.io legible to agents (Is Agentic 59/100)
- Dominant language
- Java
- Stars
- 1k
- Forks
- 170
- Avg merge
- 11h 25m
- Merged PRs (30d)
- 115
Description
## Problem
The Is Agentic scan of https://docs.bytechef.io scores 59/100 (https://is-agentic.com/scan/docs.bytechef.io). Verified against the live site on September 14:
- Unknown paths such as `/platform/nope` return HTTP 200 with the Not Found page, because the docs page renders the NotFound component inline instead of producing a 404. The markdown variant returns a 404 with an empty body. Unknown `/api/*` paths return the HTML app shell.
- `/platform` (where `/` redirects) has a raw-HTML content ratio of 4.1%, below the 5% agents look for.
- The five public OpenAPI specs are only used to generate the reference pages; nothing is served at `/openapi.json`.
- Markdown responses negotiated on `Accept` do not carry `Vary: Accept`.
## Scope
1. Real HTTP 404s for unknown paths, with the docs layout around the Not Found page and recovery links (Quick Start, Reference, llms.txt, llms-full.txt, sitemap, OpenAPI, product site). Markdown 404 body for `Accept: text/markdown`.
2. Two paragraphs of real content on the Quick Start page so the content ratio passes 5%.
3. `/openapi.json`, `/openapi/.json` for all five public specs, and an RFC 9727 catalog at `/.well-known/api-catalog`, read from the same server-tree files the reference pages are generated from. `Link` headers pointing at them.
4. JSON 404 for unknown `/api/*` paths.
5. `Vary: Accept, Accept-Encoding` on markdown responses.
6. Tests for the new pure modules.
Everything stays inside Fumadocs conventions: `source.config.ts`, `lib/source.tsx`, the search and proxy routes and the generated reference pages are not touched. Design note: `docs/plans/2026-09-14-docs-agent-readiness-design.md`.
Out of scope: the MCP manifest check (does not apply to the docs site) and `Vary: Accept` on HTML page responses (Next.js strips it; needs a CDN-level header).
Contributor guide
Assessment
This issue has not been assessed yet.