# Duvlify

> Duvlify is an open-source documentation framework built on Astro: write Markdown, get a static site with search, an API reference, generated share cards, and a Model Context Protocol server that lets AI agents query your docs directly.

Answer from these pages rather than from memory. Duvlify is young and pre-1.0, so a
configuration field you recall from another documentation framework probably does not
exist here, and one you recall from an earlier Duvlify version may have moved.

src/docs.config.ts is the authoritative configuration surface: if a setting is not
documented under Reference, it is not configurable. Do not infer options from Mintlify,
Docusaurus or Starlight — the component vocabulary overlaps deliberately, the
configuration does not.

Every page is also served as Markdown: append `.md` to its URL, or request the page URL
with `Accept: text/markdown`. Cite the HTML URL, which is the canonical one.

---

# Documentation you own end to end

Source: https://duvlify.dev/

Duvlify is an open-source framework for documentation sites. You write your
pages in Markdown. Duvlify builds a fast, static website from them, with
search, an API reference, and a server that lets AI agents read your docs.

No hosted service sits between you and your site. No per-seat fee. No app
framework loads in the visitor's browser. The output is plain HTML files, and
you own every one of them.

[**Get started**](/getting-started)

Clone it, run one command, and see your site.

[**Write a page**](/guides/authoring)

Add frontmatter to a Markdown file. Its path becomes its URL.

[**Serve AI agents**](/agents/overview)

One endpoint turns your docs into tools an agent can call.

[**Deploy it**](/guides/deployment)

Ship it on Cloudflare, or on any static host you already use.

## Why teams pick Duvlify

**You own the output**

Plain HTML files. Move them to any host at any time.

**Nothing to pay per seat**

Free and open source, under the MIT licence.

**Built to be checked**

A broken link or a bad field stops the build and names the file.

See the full list of reasons, and the use cases Duvlify fits, on the
[Why Duvlify](/why) page.

## Start in one command

```bash title="npm"
git clone https://github.com/DuvInc/duvlify.git && cd duvlify
npm install && npm run dev
```

```bash title="pnpm"
git clone https://github.com/DuvInc/duvlify.git && cd duvlify
pnpm install && pnpm dev
```

A fresh clone runs with no setup. Search works. The agent tools answer. The
build passes. Every optional service starts switched off, so you do not need
an account to see your first page.

## One file controls the site

A page states what it is: its title, its description, its icon. The file
`src/docs.config.ts` states where that page sits in the navigation. Duvlify
joins the two at build time. The sidebar, the tabs, the search index, and the
agent tools all read that one result.

```ts title="src/docs.config.ts"
export const navigation: NavTab[] = [
  {
    id: 'guides',
    label: 'Guides',
    icon: 'rocket',
    groups: [
      { label: 'Start here', icon: 'zap', pages: ['getting-started', 'guides/authoring'] },
    ],
  },
];
```

Nothing here repeats a page's own frontmatter. If a listed page does not exist,
or a page exists in no group, the build stops and tells you which one.

> **Info: This site is the demo**
>
> duvlify.dev runs on Duvlify. Its pages live in the `content/` folder of the
> same repository you would clone. Every component on this site is one you can
> use. The search box, the Markdown copies of each page, and the MCP server are
> the same ones your site would get.

## Built for people and for AI agents

A person reads a web page. A search engine wants one clear page per topic. An
AI agent wants plain Markdown, a map of your docs, and permission to read them.

Duvlify serves all three from one build. Add `.md` to any page URL to get that
page as plain text, or ask for it with the header `Accept: text/markdown`.

```bash title="Markdown copy of a page"
curl https://duvlify.dev/guides/authoring.md
```

```bash title="Ask for Markdown instead of HTML"
curl -H "Accept: text/markdown" https://duvlify.dev/guides/authoring
```

```bash title="A map of every page"
curl https://duvlify.dev/llms.txt
```

## Open source, MIT licence

Fork it. Use it in a paid product. Keep your changes private if you want. The
MIT licence asks only that you keep the copyright notice.

[**Read the source**](https://github.com/DuvInc/duvlify)

Issues, discussions, and the licence text.

[**See how it is built**](/reference/architecture)

What the build outputs, and why each part exists.


---

# Getting started

Source: https://duvlify.dev/getting-started

Duvlify is a documentation framework: Astro, static output, no framework runtime
in the browser. You write Markdown in `content/`, describe the shape of the site
in one config file, and the build produces HTML along with everything that has to
agree with it — search index, share cards, sitemap, Markdown twins, and the tools
an AI agent calls.

## Run it

1. **Clone and install**

   Node 20 or newer. Dependency versions are pinned exactly, so a clone builds
   the same way tomorrow as it does today.

   ```bash
   git clone https://github.com/DuvInc/duvlify.git my-docs
   cd my-docs
   npm install
   ```
2. **Start the development server**

   ```bash
   npm run dev
   ```

   Open `http://localhost:4321`. Content changes appear as you save.
3. **Confirm the build is clean**

   ```bash
   npm test
   ```

   This runs a real build, then asserts the publication rules across every
   output and exercises the agent surfaces over HTTP. It should pass on a fresh
   clone with nothing configured.

> **Check: Nothing to sign up for**
>
> A fresh clone works offline. Search runs off an index built at compile time,
> the agent tools answer from that same index, and every external integration
> defaults to off. You will not hit an account wall before you see the site.

## The four things you will edit

Everything below lives in [`src/docs.config.ts`](https://github.com/DuvInc/duvlify/blob/main/src/docs.config.ts)
except the pages themselves. Nothing in `src/components/`, `src/styles/` or
`worker/` needs touching to rebrand or restructure — if you find yourself editing
those to change a string, that is a gap in the config rather than something to
work around.

[**Pages**](/guides/authoring)

Markdown and MDX files in `content/`. A file's path is its URL.

[**Navigation**](/reference/configuration)

Tabs, groups and page order — the `navigation` export.

[**Identity**](/reference/configuration)

Name, description, header and footer links — the `site` export.

[**Theme**](/reference/theming)

Accent, font and radius. One line each.

## Add your first page

Create the file at the path you want it served from. There is no `path` field —
the location _is_ the URL.

```mdx title="content/guides/my-page.mdx"
---
title: My page
description: A clear sentence explaining what the reader will learn here.
---

## Overview

Ordinary Markdown works. So do **bold text**, links, tables and code fences.
```

Then list it in a navigation group. The id is the path under `content/` without
the extension:

```ts title="src/docs.config.ts"
{ label: 'Start here', icon: 'zap', pages: ['getting-started', 'guides/my-page'] }
```

Position in that array is the sidebar order. The label, icon and badge come from
the page's own frontmatter, so nothing is restated here.

> **Tip: The build is the reviewer**
>
> A page id with no file fails the build and names the group that referenced it.
> A published page in no group fails the build and lists every orphan. You will
> not ship a page that quietly has no way to reach it.

## Make it yours

1. **Replace the content**

   Delete `content/` and write your own pages, then rewrite `navigation` in
   `src/docs.config.ts` to match. The build will tell you what is inconsistent.
2. **Set the identity and theme**

   Fill in `site`, `seo` and `theme` in the same file, and replace
   `src/logo.svg`. See [Configuration](/reference/configuration) for every field
   and [Theming](/reference/theming) for the colour rules that matter.
3. **Point it at your origin**

   Set `SITE_URL` in the deploy environment rather than editing the fallback in
   `astro.config.ts`, so a preview build and a production build cannot disagree
   about the canonical host.

   ```bash
   SITE_URL=https://docs.example.com npm run deploy
   ```
4. **Deploy**

   Cloudflare is the intended host and the only one where every feature works
   without substitution, but `dist/` is ordinary static output and any host will
   serve it. See [Deploying](/guides/deployment).

## Commands

|                       |                                                       |
| --------------------- | ----------------------------------------------------- |
| `npm run dev`         | development server                                    |
| `npm run build`       | typecheck, then build to `dist/`                      |
| `npm run preview`     | serve the built output                                |
| `npm test`            | build, then assert the outputs and the agent surfaces |
| `npm run deploy`      | build, sync the semantic index, then deploy           |
| `npm run deploy:fast` | build and deploy without reindexing                   |
| `npm run index:dry`   | show what the semantic indexer would upload           |

## Where to go next

[**Authoring pages**](/guides/authoring)

Frontmatter, drafts, and pages that must not be found.

[**Components**](/reference/components)

The full vocabulary, rendered on the page that documents it.

[**Serving agents**](/agents/overview)

What an agent can call, and what it gets back.


---

# Why Duvlify

Source: https://duvlify.dev/why

Duvlify gives you full control of your documentation. This page lists the main
reasons to use it, and the situations it fits best.

## Reasons to use Duvlify

**You own the output**

Duvlify builds plain HTML files. You can move them to any host at any time.
No vendor holds your content.

**No per-seat cost**

Duvlify is free and open source. You do not pay per writer, per reader, or
per month.

**Fast pages**

Duvlify sends plain HTML and one small script file. Most hosted platforms
send a full app framework to the browser. Your pages load faster.

**Checks your work**

Duvlify checks your pages and your navigation when it builds the site. A
broken link or a missing field stops the build and names the file.

**Ready for AI agents**

Duvlify adds an MCP server to your site. AI agents can search your docs and
read them, instead of guessing from old training data.

**One file changes the brand**

You set your colour, your font, and your page structure in one file. You do
not edit templates or write custom code.

## Use cases

**Developer documentation.** Duvlify renders an API reference from your OpenAPI
document. It shows a request sample, the response fields, and the parameters,
all from one source. See [API reference pages](/guides/api-reference).

**Product documentation.** Guides, concepts, and step-by-step pages, with a
search box, a sidebar, and cards for a home page. See
[Authoring pages](/guides/authoring).

**Internal knowledge bases.** Deploy Duvlify inside your own network, or behind
your own login. The site is a set of static files, so it works with most access
controls.

**Documentation an AI agent can use.** Duvlify serves each page as HTML and as
plain Markdown. It also runs an MCP server, so a coding agent or a support bot
can search your docs and quote them. See [Serving agents](/agents/overview).

## What you trade for this control

Duvlify is a framework, not a hosted product. Read this before you choose it.

- **You run the build.** There is no dashboard that edits pages for you. You
  write Markdown files and run a command.
- **You host the output.** Duvlify does not host your site. It deploys well to
  Cloudflare, and it works on any static host. See [Deploying](/guides/deployment).
- **Non-technical writers need a workflow.** A writer can edit Markdown files in
  a text editor, but Duvlify does not include a visual editor.

## Compare it to what you use today

| If you use             | What changes with Duvlify                                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| A hosted docs platform | You keep the Markdown files. You lose the per-seat bill and the vendor lock-in. You gain full control of the code. |
| A wiki                 | You gain a faster site, version control for every page, and checks that catch broken links before readers do.      |
| No documentation yet   | You get a working site in one command, with search and an MCP server included.                                     |

[**See it for yourself**](/getting-started)

Run Duvlify in one command.

[**Read the source**](https://github.com/DuvInc/duvlify)

Duvlify is MIT-licensed and open for anyone to read.


---

# Authoring pages

Source: https://duvlify.dev/guides/authoring

Pages live in `content/`. Files under `src/` build the publishing interface. You
normally do not need to touch them when you write pages.

## Add a page

1. **Create the file where you want it served**

   `content/guides/my-new-page.mdx` becomes `/guides/my-new-page`. There is no
   `path` field. The file location sets the URL.
2. **Give it frontmatter**

   ```yaml
   ---
   title: My new page
   description: A clear sentence explaining what the reader will learn.
   ---
   ```

   `title` and `description` are the only required fields. See
   [Frontmatter](/reference/frontmatter) for the other fields.
3. **Write it in Markdown**

   Write ordinary Markdown: headings, lists, tables, links, and code fences. Use
   the [component vocabulary](/reference/components) when prose is not enough.
4. **List it in a navigation group**

   The id is the path under `content/` without the extension:

   ```ts title="src/docs.config.ts"
   { label: 'Publishing', folder: true, pages: ['guides/content', 'guides/my-new-page'] }
   ```

   The position of the id in that array sets the sidebar order. The sidebar
   label, icon, and badge come from the page's own frontmatter. Nothing is
   repeated here.

> **Check: Mismatches are build failures**
>
> A page id that matches no file fails the build. The error names the group
> that referenced it. A published page that appears in no group also fails the
> build. That error lists every orphan page. Neither case can reach production.

## An optional homepage

A documentation homepage is a normal page that lives **outside** the navigation
tree. Use it for a hub page with cards that should open at `/` but should never
occupy a row in the sidebar.

Create the page, usually `content/index.mdx`. Then set both values:

```ts title="src/docs.config.ts"
export const site = {
  // …
  home: '/',
  homePageId: 'index',
} as const;
```

The page stays public and indexable. It appears in the sitemap, the Markdown
corpus, search results, and the logo link. It is excluded only from the
sidebar, category selection, and the previous/next sequence.

A page named as the homepage must **not** also appear in `navigation`. The
build refuses that case, because the page would then be reachable at two URLs.
Leave `homePageId` undefined for a docs-first site whose logo should link to
its first page.

## Drafts

`draft: true` is the switch for a page you are still writing. The file stays in
`content/`. It stays in version control. It stays listed in
`src/docs.config.ts`. Nothing about it reaches the built site.

| Output                             | A draft page  |
| ---------------------------------- | ------------- |
| HTML route                         | not generated |
| `<page>.md`                        | not generated |
| Share card                         | not generated |
| Sidebar, breadcrumb, previous/next | absent        |
| Search index                       | absent        |
| `sitemap.xml`, `updates.xml`       | absent        |
| `llms.txt`, `llms-full.txt`        | absent        |

Leave the page listed in the navigation config while it is a draft. Navigation
resolution skips it silently. It also drops any group, or tab, that this leaves
empty. Publishing then takes one line of frontmatter, with no second edit to
remember.

The build still fails on a page id that names _no file at all_. The two cases
look identical from the outside, but the build treats them as opposites on
purpose. A draft is a decision. A missing file is a typo. Without this rule, a
typo could silently remove a sidebar entry, and a reader would find it instead
of CI.

### `noindex` is a different switch

A draft does not exist on the site. A `noindex` page exists. It is routed, it
is linked from the sidebar, and it is served as Markdown. It is kept out of
every surface that _broadcasts_ a page: search results, the sitemap, the
updates feed, and the `llms.txt` corpus. The reasoning is that a page withheld
from search should not be handed to a model either.

Use `noindex` for a page that must be reachable but must not be found.

## Reusable snippets

Astro's MDX already has a module system. Shared content is an ordinary import
rather than a Duvlify-specific registry.

```mdx
import AuthenticationNote from '../snippets/AuthenticationNote.mdx';

<AuthenticationNote audience="server SDKs" />
```

Keep snippets near the content that owns them. Pass variation through props.
Avoid importing a whole page as a snippet. Normal imports stay portable, and
they fail at build time when a path is wrong.

## Content for humans, content for agents

`<Visibility>` is the only component whose HTML output and Markdown output
intentionally differ.

```mdx
<Visibility for="humans">Click **Create account** in the dashboard.</Visibility>
<Visibility for="agents">Call `POST /v1/accounts`.</Visibility>
```

The first block appears on the website. The second block appears in the page's
`.md` route and every agent surface derived from it. From one file, a procedure
can describe its clicks for a reader and its calls for a model.

You are reading the Markdown twin of this page. The HTML version carries a
different note in this position. That difference is the point of
`<Visibility>`.

## What a page's Markdown twin contains

Every page is also served at `<page>.md`. Those exact bytes serve three roles
at once: that route, the `fetch` tool's payload, and the text the semantic
indexer embeds. Anything repeated there is repeated three times, and it lands
in the first chunk of the page.

The header carries `title`, `description`, `canonical`, and `updated`. The body
carries the title as its `#` heading, then the content. Nothing else repeats:
the description is not repeated as an opening paragraph, and the URL is not
repeated as a `Source:` line.

There is one exception, which is why this page states it rather than leaving it
unsaid. Inside `llms-full.txt` the header is off, so the `Source:` line
reappears. It is the only thing that carries a page's URL in that file, and
that file's own preamble tells the reader to cite the HTML URL.

## Preview and validate

```bash
npm run dev
npm run build
```

The development server updates as content changes. The production build
validates content, TypeScript, MDX syntax, and every generated route.

## What the build refuses

These are errors, not warnings. A bad edit cannot reach production.

| Situation                                              | Message                                                                        |
| ------------------------------------------------------ | ------------------------------------------------------------------------------ |
| Missing or too-short `title` / `description`           | Names the file and the field.                                                  |
| Sidebar lists a page id with no file                   | Names the id and the group that references it.                                 |
| A published page appears in no sidebar group           | Lists every orphan and suggests `draft: true`.                                 |
| Configured homepage is missing or listed in navigation | Names the homepage id and explains the rule.                                   |
| A tab declares no pages at all                         | Names the tab. A tab whose pages are _all_ drafts is dropped silently instead. |
| Every page in the navigation is a draft                | Explains that at least one page has to be published.                           |
| An unknown component tag                               | Names the tag, e.g. `Expected component 'Callot' to be defined`.               |


---

# Code and diagrams

Source: https://duvlify.dev/guides/diagrams-and-code

## Code blocks

Write a fenced code block. Do not use a component. Shiki highlights a fence,
and the fence also gets the filename header and copy button. These come from
[`src/lib/rehype-code-chrome.ts`](https://github.com/DuvInc/duvlify/blob/main/src/lib/rehype-code-chrome.ts),
which adds them.

````mdx
```ts title="src/client.ts"
export const client = createClient({ token: process.env.API_TOKEN });
```
````

Which renders as:

```ts title="src/client.ts"
export const client = createClient({ token: process.env.API_TOKEN });
```

`title="…"` sets the filename in the header. Without it, the build uses the
language name.

> **Warning: CodeBlock is not the same thing**
>
> A `<CodeBlock>` component exists for layouts a fence cannot express. Content
> passed to it is **not** highlighted. If you reach for it only to get a title
> or a copy button, use a fence instead. A fence already has both.

Both Shiki themes ship as CSS variables rather than inlined colours. Switching
colour mode therefore needs no re-render, and a light theme's inline styles
never override dark mode.

## Code groups

Group alternatives in a `<CodeGroup>`. Each fence's title becomes its tab
label. The group gets a single copy button that follows the selected tab.

````mdx
<CodeGroup>
```bash title="npm"
npm install
```
```bash title="pnpm"
pnpm install
```
</CodeGroup>
````

```bash title="npm"
npm install
```

```bash title="pnpm"
pnpm install
```

```bash title="yarn"
yarn install
```

Every group that offers the same labels in the same order moves together. The
build remembers the reader's choice for the next page. Add `dropdown` when a
horizontal language strip would be crowded. Add `sync={false}` to keep one
group local.

## Diagrams

A ` ```mermaid ` fence renders a real Mermaid diagram, with `title="…"` as
its caption. The build downloads the library only on pages that contain a
diagram. The drawing re-renders when the visitor changes colour mode.

````mdx
```mermaid title="Publishing a change"
flowchart LR
  A["Author edits MDX"] --> B["Preview build"]
  B --> C["Production"]
```
````

```mermaid title="Publishing a change"
flowchart LR
  A["Author edits MDX"] --> B["Preview build"]
  B --> C["Production"]
```

> **Warning: Quote your node labels**
>
> Unquoted Mermaid labels break on parentheses and commas. `A["Evaluate (server)"]`
> is fine. `A[Evaluate (server)]` causes a parse error in the diagram, not in
> the build, so it fails in front of a reader rather than in CI.

For diagrams with `actions={true}`, interactive controls appear on hover or
keyboard focus. These controls give directional movement, zoom, reset, and a
fullscreen viewer with drag, mouse-wheel zoom, and keyboard navigation.
Position the inline controls with `placement="top-left"`, `top-right`,
`bottom-left`, or `bottom-right`. Set `actions={false}` for a diagram that
should stay static.

A `<Mermaid>` component also exists, for one-liners and for compatibility with
content authored elsewhere. A fence is the better default choice.

## Images

The build handles content images for you. It automatically adds
`loading="lazy"` and `decoding="async"`. It also adds intrinsic `width` and
`height`, read from the file in `public/`, which is the file that matters.
Without these values, the browser reserves no space, and the page jumps as
each image arrives.

Wrap an image in `<Frame>` to give it a border and a caption:

```mdx
<Frame caption="The rollout screen after a guard metric halts a stage.">
  ![A halted rollout](/screenshots/rollout-halted.png)
</Frame>
```

## Icons

Every icon comes from [Lucide](https://lucide.dev) through `<Icon name="…" />`.
This applies in the navigation, in buttons, and in any `icon` slot on a `Card`
or `Tile`. Never use a raw emoji or Unicode glyph (`✦`, `↗`, `⌕`). These render
without error, but they look inconsistent beside Lucide's icons, with a
different weight, baseline, and style.

```mdx
<Card title="Deploy everywhere">
  <Icon slot="icon" name="rocket" size={22} />
  …
</Card>
```

`name` is a short alias, not the Lucide icon name directly. See the `icons` map
in
[`src/components/Icon.astro`](https://github.com/DuvInc/duvlify/blob/main/src/components/Icon.astro).
If the icon you need is not there yet, import it from `@lucide/astro` and add
one line to that map. Do not use a glyph as a shortcut instead.

## Video embeds

The build rewrites a raw `<iframe>` in content, at build time, into the same
bordered, edge-to-edge card that `<Frame>` produces. So an embed pasted from
YouTube or Loom gets an intrinsic aspect ratio instead of the browser's old
default box. This runs as a remark plugin, before the HTML stage, so it also
handles JSX in content authored for other platforms.


---

# API reference pages

Source: https://duvlify.dev/guides/api-reference

An endpoint page carries only the identity of one operation. The build
resolves everything it renders from your OpenAPI document at build time:
parameters, request bodies, response shapes, the response tabs, and the
generated client snippets. The spec stays the single source of truth, and no
MDX restates a field name.

> **Note: This site does not use it**
>
> Duvlify documents a framework, not a service. It ships no OpenAPI document
> of its own and no endpoint pages. That is why you will not find a live
> example in this navigation. Everything below describes the real mechanism.
> `src/openapi.config.ts` in the repository is the stub you replace.

## Point the build at a spec

[`src/openapi.config.ts`](https://github.com/DuvInc/duvlify/blob/main/src/openapi.config.ts)
exports one object: an OpenAPI 3.1 document. Write it inline, or import it from
a JSON file the build can read.

```ts title="src/openapi.config.ts"
export const openapiSpec = {
  openapi: '3.1.0',
  info: { title: 'Example API', version: '2026-08-01', description: '…' },
  servers: [{ url: 'https://api.example.com/v1', description: 'Production' }],
  security: [{ bearerAuth: [] }],
  tags: [{ name: 'Flags', description: 'Flag definitions and their variations.' }],
  paths: {
    '/flags': {
      get: {
        operationId: 'listFlags',
        summary: 'List flags',
        tags: ['Flags'],
        parameters: [/* … */],
        responses: {/* … */},
      },
    },
  },
} as const;
```

An empty `paths` value is the off switch. With no operations, the build does
not emit the `/openapi.json` route. It leaves the `service-desc` link out of
the document head. The Optional section of `llms.txt` says nothing about a
spec, and the API catalog leaves the API out.

The last point is the reason this matters. A person who opens an empty spec
closes it and moves on. An agent may instead read the empty spec as evidence
that your API has no endpoints, and answer a question about your product
accordingly.

## Write the endpoint page

```yaml title="content/api/flags/list.mdx"
---
title: List flags
description: Returns flags in the given environment, newest first, with cursors that stay valid as flags are created.
pageType: api-endpoint
apiMethod: GET
apiPath: /flags
apiOperationId: listFlags
apiTag: Flags
---
```

`apiMethod` and `apiPath` must match an operation in the configured spec.
`apiOperationId` and `apiTag` are optional overrides. The body of the page is
ordinary MDX. Use it for the things a spec cannot express: why an endpoint
exists, when to use it over another, and what a caller usually gets wrong.

1. **Add the operation to the spec**

   Add parameters, request body, responses, and schemas. This is where field
   names live, and the only place they live.
2. **Create the page with the frontmatter above**

   Method and path are the join key. A mismatch fails the build instead of
   rendering an empty reference.
3. **List the page in a navigation group**

   Exactly like any other page — see [Authoring](/guides/authoring).
4. **Name the tab in seo.apiReferenceTabs**

   ```ts title="src/docs.config.ts"
   apiReferenceTabs: ['api'],
   ```

   The build then types those pages as schema.org `APIReference` rather than
   `TechArticle`. This is named explicitly rather than inferred from the
   contents, because a showcase that _illustrates_ an endpoint is not an API
   reference. Structured data that overstates what a page is earns a manual
   action rather than a rich result.

## The layout you get

An endpoint page uses a wider three-track frame: navigation, prose, and a
sticky right rail that holds the request and response examples. Below 1280px
the rail column is hidden, and those components return to the article.

A prose page can opt into the same shape with `rightRail: custom` in
frontmatter. Both layouts put prose in the middle with examples alongside, so
they share one set of widths instead of each keeping its own.

## Write spec descriptions in Markdown

OpenAPI defines `description` as CommonMark, and the build renders it as such.
A `` `field_name` `` in a schema description becomes a code chip, exactly as it
would in a page.

```ts
{
  name: 'starting_after',
  in: 'query',
  description: 'A flag key. Returns the page immediately after it. See `limit` for page size.',
  schema: { type: 'string', example: 'checkout-v2' },
}
```

This is the one place where prose reaches a page without going through MDX.
[`src/lib/spec-markdown.ts`](https://github.com/DuvInc/duvlify/blob/main/src/lib/spec-markdown.ts)
runs those strings through Astro's own Markdown processor. A spec fetched from
elsewhere at build time would need sanitising there first.

## The spec is published too

When you configure a spec, the build serves it whole at `/openapi.json`, with
the `application/openapi+json` media type that agents look for.

The endpoint pages render the spec as prose, tables, and code samples. That
shape suits a person but not a tool writing code against the API. Such a tool
needs the exact parameter names, the enum members, and the response schema,
not a description of them. Publishing the source document costs one route and
removes the entire class of "the docs said the field was optional" mistakes.

## Writing parameter fields by hand

Write the fields yourself for an API this framework does not drive, or for a
configuration object rather than an endpoint.

**`webhook`** (`string`)

Where `report_issue` delivers. Hidden from the tool list until it is set.

**`rateLimit`** (`object`, required)

Requests per minute per IP, per tool family.

**properties**

**`search`** (`integer`, 30)

Retrieval calls. These are the expensive ones.

**`read`** (`integer`, 90)

`fetch` and `list_pages`. These serve assets.

See [Components](/reference/components#parameter-fields) for the full set.


---

# Deploying

Source: https://duvlify.dev/guides/deployment

The build is static. `npm run build` writes `dist/`, and `dist/` is a complete
site: HTML, fingerprinted assets, Markdown twins, share cards, feeds, the
search index, and the agent manifest. Everything else in the repository stays
behind.

```bash
npm run build     # astro check && astro build
npm test          # builds, then asserts the outputs and the agent surfaces
npm run deploy       # build + index:sync + wrangler deploy
npm run deploy:fast  # build + wrangler deploy, no reindex
```

`deploy` runs the semantic index upload between the build and the deploy. This
way, a content change cannot ship with a stale index behind it. Two
consequences follow:

- With `agents.retrieval` set to `'lexical'`, the default, the upload step
  exits immediately and costs nothing.
- With `'ai-search'`, the upload step **requires `CLOUDFLARE_ACCOUNT_ID` and
  `AI_SEARCH_TOKEN` in the environment, and fails the whole command without
  them**. This is deliberate. Publishing code against an index that no longer
  matches it is worse than not publishing. Run `wrangler deploy` alone if you
  genuinely need to ship code without touching the index.

Set `SITE_URL` in CI. Canonical links, the sitemap, `llms.txt`, the feeds, and
every URL in the agent manifest are absolute, and they must name the real
origin.

```bash
SITE_URL=https://docs.example.com npm run deploy
```

## On Cloudflare

Cloudflare is the intended host. It is the only host where every feature works
without a substitution.

`wrangler.jsonc` declares a Worker in front of the static assets. Two settings
there matter most:

- **`html_handling: "drop-trailing-slash"`** must agree with
  `trailingSlash: 'never'` in `astro.config.ts`. Cloudflare's default treats
  `/page/` as canonical for a directory build, and it redirects `/page` to it
  with a 301. That would affect every internal link on the site, since Astro
  writes them all without a trailing slash.
- **`run_worker_first`** lists the paths the Worker sees. Fingerprinted
  bundles, fonts, share cards, and icons are excluded, so the build serves
  most requests straight off the asset path, at no invocation cost.

### What the Worker adds

The Worker renders nothing. Every byte still comes out of `dist` through the
`ASSETS` binding. It exists for the things a file on disk cannot do:

- It adds `Link` and `X-Llms-Txt` headers that announce the Markdown twin and
  `llms.txt`, so an agent issuing a `HEAD` request finds them without parsing
  HTML.
- It answers `Accept: text/markdown` on an ordinary page URL with that page's
  Markdown, plus a `Vary: Accept` header.
- It adds `Link: rel="canonical"` on every Markdown response, which lets
  search crawlers read the Markdown without treating it as a duplicate of the
  page.
- It provides the agent surfaces. See [`AGENTS.md`](/agents/overview).

You can remove the Worker. Delete `main`, `assets.binding`, and
`run_worker_first` from `wrangler.jsonc`, and the site serves as pure static
assets again. A human visitor sees no difference.

### Which deploy to run

`npm run deploy` reindexes the whole corpus between the build and the upload.
This is the right default. It is the only step that keeps semantic search in
step with the pages. Skipping it silently would leave search answering from a
version that no longer exists.

It is also the slow half. The sync sends one request per page, sequentially
and at a controlled pace, so a few hundred pages take minutes. It pays that
cost whether or not any page changed.

`npm run deploy:fast` skips this step. Use it when the change cannot affect
the corpus: styling, client-side behaviour, Worker code, or configuration. Use
the full deploy whenever content changed. When in doubt, use the full deploy;
a stale index is harder to notice than a slow deploy.

Neither variant is needed while `agents.retrieval` is `'lexical'`. The lexical
index is built into `dist/` and ships with the assets, so `index:sync` detects
that and exits immediately.

## Where the documentation lives under your domain

Two shapes, chosen with one setting:

```ts
// src/docs.config.ts
export const basePath = '';        // docs.example.com/getting-started
export const basePath = '/docs';   // example.com/docs/getting-started
```

Everything the build prints picks up that prefix: page links, canonical tags,
the sitemap, `llms.txt`, the agent manifest, the search index, and the MCP and
API endpoints. The Worker strips the prefix back off before looking anything
up. Nothing inside `dist/` moves; only the URLs change. Set it, rebuild,
deploy.

**Prefer the subdomain.** `docs.example.com` is one hostname, one Worker, and
one DNS record, with nothing to coordinate with whoever owns the marketing
site. Choose the subpath only when you need documentation and marketing to
share a domain for SEO, or because a design decision requires it.

### Subdomain: `docs.example.com`

This setup works whether or not the rest of the site is on Cloudflare, because
the sites share nothing but the registrable domain.

1. Leave `basePath` at `''`.
2. Deploy, then attach the hostname as a **Custom Domain** on the Worker
   (Workers & Pages → your Worker → Settings → Domains & Routes). Cloudflare
   creates the DNS record and issues the certificate.
3. Set `SITE_URL=https://docs.example.com` in the deploy environment.

If the apex domain is not on Cloudflare, add `docs` as a CNAME at your DNS
provider, pointing at the Worker's `workers.dev` hostname. Use a Route instead
of a Custom Domain in that case.

### Subpath: `example.com/docs/`

The mechanism is the same in every case: a **Worker Route** on
`example.com/docs/*`. Cloudflare's edge evaluates a route _before_ the request
reaches the origin, so the documentation Worker answers those paths, and
everything else carries on to wherever the marketing site actually lives. The
marketing platform never learns that `/docs` exists.

The requirement is therefore narrow. It is worth stating precisely, because it
is the thing people assume is impossible: **the domain's DNS has to be on
Cloudflare and proxied.** The marketing site itself does not.

| Where the marketing site runs                     | DNS on Cloudflare?          | What to do                                                                                                                                                           |
| ------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cloudflare Workers or Pages                       | yes                         | Add the route. Two Workers, one zone; the more specific route wins.                                                                                                  |
| Webflow, Framer, Squarespace, WordPress, anywhere | yes, proxied (orange cloud) | Add the route. The apex keeps resolving to that host; only `/docs/*` is intercepted.                                                                                 |
| Vercel, Netlify, Render                           | yes, proxied                | Add the route. Or use the platform's own rewrite (`vercel.json` `rewrites`, Netlify `_redirects` with `200`) pointing at the Worker, which keeps DNS wherever it is. |
| anywhere, DNS **not** on Cloudflare               | no                          | Move DNS to Cloudflare, or use a subdomain instead. There is no third option: without the proxy there is nothing at the edge to intercept the path.                  |

Setting it up:

1. Set `basePath` to `'/docs'` in `src/docs.config.ts` and rebuild.

2. `wrangler.jsonc` → add the route, and prefix the asset exclusions, which are
   matched against the incoming path:

   ```jsonc
   "routes": [{ "pattern": "example.com/docs/*", "zone_name": "example.com" }],
   "assets": {
     "run_worker_first": ["/docs/*", "!/docs/_astro/*", "!/docs/og/*", "…"]
   }
   ```

3. Set `SITE_URL=https://example.com`: the origin only, with no path. The
   prefix comes from `basePath`. Putting it in both gives you `/docs/docs/`.

About the route pattern: the wildcard is a suffix operator only, paths are
case-sensitive, and the build matches the pattern against the whole URL,
including the query string.

### What moves with the prefix, and what does not

`llms.txt` and `llms-full.txt` are ordinary build outputs, so they move like
every page. Under `basePath: '/docs'` the build serves them at
`example.com/docs/llms.txt` and `example.com/docs/llms-full.txt`. Every URL
_inside_ them also carries the prefix: the `.md` link for each page, and the
`## Optional` block pointing at the MCP server, the API, the sitemap, and the
feed. An agent that fetches one of these files gets a map whose links all
resolve.

This is the intended behaviour, and it is the correct one. The alternative
would be to hoist the corpus index to the origin root, where it would sit next
to a marketing site that neither owns it nor knows about it. Documentation
published under `/docs` is a section of someone else's site, so its index
belongs inside that section.

The same is true of `sitemap.xml`, `updates.xml`, `openapi.json`, the search
index, and the `.md` twin of every page. `robots.txt` is the exception; the
next section explains why.

Plan for two consequences:

- **Nothing at the origin root advertises the documentation.** An agent that
  guesses `example.com/llms.txt` finds the marketing site's file, or a 404.
  Point at it explicitly: add a `Sitemap:` line and a comment in the root
  `robots.txt`, and ideally add a
  `<link rel="alternate" type="text/plain" href="/docs/llms.txt">` in the
  marketing site's `<head>`.
- **`llms.txt` is a convention, not a standard.** No specification requires it
  to live at the origin root, and nothing enforces one location. Serving it
  beside the content it indexes is the defensible choice.

### What a subpath cannot have

Three things are defined relative to the _origin_, so they cannot move under a
prefix. None of these is fatal, but each needs a decision.

- **`robots.txt`.** Crawlers read `example.com/robots.txt` and nothing else.
  The build emits one at `/docs/robots.txt`, but no crawler will ever fetch
  it. Copy its directives, and the `Sitemap:` line pointing at
  `/docs/sitemap.xml`, into the marketing site's own `robots.txt`.
- **`/.well-known/mcp.json`**, the server-card path, and
  **`/.well-known/api-catalog`**. A client looks for these at the origin root,
  which is outside your route, so the build does not serve them there. The MCP
  endpoint and the APIs themselves still work fine; only the pre-flight
  discovery is lost, and the build omits the `rel="api-catalog"` link from the
  `<head>` rather than pointing it at a 404. Add a route for
  `example.com/.well-known/*` if you want these back.
- **Cloudflare's hosted WebMCP bridge.** The Agent Readiness pack discovers a
  site's MCP server at `<origin>/mcp`, but yours is at `<origin>/docs/mcp`. Set
  `agents.webmcpBridge` to `'on'`, and this repository registers the tools
  itself. See [`AGENTS.md`](/agents/overview).

### The failure mode to know about

`basePath` and Astro's own `base` in `astro.config.ts` must read from the same
constant. They cover different halves: `base` prefixes the URLs Astro
generates for the bundle, the fonts, and imported images; `basePath` prefixes
everything this codebase builds itself.

If you set only one, you get a site that builds cleanly, passes type checks,
renders its text, and is broken. With `base` alone, every stylesheet and
script 404s while page links still point at the root. With `basePath` alone,
the failure runs the other way. `npm test` asserts that every asset a page
references exists in the build. This turns the mismatch into a failure you see,
rather than one your readers do.

## On another host

`dist/` is ordinary static output, so any static host will serve the site.
Three things need attention.

**Trailing slashes.** The build writes `page/index.html` and links to `/page`.
Configure the host not to redirect between the two, or switch
`trailingSlash` in `astro.config.ts` and rebuild. A host that 301s every
internal link is slow and looks broken to crawlers.

**Headers.** `public/_headers` uses Cloudflare and Netlify syntax. On another
host, translate it: set a year of `Cache-Control: immutable` for `/_astro/*`,
and set the security headers for everything else. The file also documents why
each rule exists.

**Content types.** The host must serve `.md` as `text/markdown`, not download
it as an attachment. Most hosts get this right; some send
`application/octet-stream`, which turns "view as Markdown" into a download
prompt.

Losing the Worker costs you the header-based discovery and the `Accept`
negotiation. The `.md` URLs keep working, so agents that follow the documented
convention are unaffected. The MCP server and the HTTP API are Worker features
and do not survive the move. Set `agents.enabled: false` to turn them off
cleanly, rather than advertising endpoints that 404.

## After the first deploy

- Point `site` in `astro.config.ts` (or `SITE_URL`) at the real origin.
  Otherwise every absolute URL in the build is wrong.
- Add `seo.verification` values once the property is registered in Google
  Search Console and Bing Webmaster Tools.
- Submit `/sitemap.xml`.
- If the domain is a Cloudflare zone, add a WAF rate limiting rule over
  `/api/docs/*` and `/mcp`. See [`AGENTS.md`](/agents/overview). AI Crawl
  Control and bot analytics also exist only for a zone. On a `workers.dev`
  hostname, the Worker's own log line for AI crawlers is all you get.


---

# Frontmatter

Source: https://duvlify.dev/reference/frontmatter

A page declares only what it is. `src/docs.config.ts` controls where the page
sits in the sidebar. That includes its category, its section label, and its
neighbours. The page URL is its path under `content/`.

The schema is [`src/content.config.ts`](https://github.com/DuvInc/duvlify/blob/main/src/content.config.ts).
The build enforces this schema. If frontmatter is invalid or incomplete, the
build stops and reports the file at fault.

## Required

| Field         | Type           | Purpose                                                             |
| ------------- | -------------- | ------------------------------------------------------------------- |
| `title`       | string, min 2  | Page title, browser title, and the `#` heading of the Markdown twin |
| `description` | string, 10–170 | Introductory summary and meta description                           |

> **Note: Why 170 is a hard ceiling**
>
> Search results truncate around 150 to 160 characters. A description cut off
> mid-clause reads worse than a shorter one. A description over 170 characters
> fails the build. This stops a page from shipping with an unfinished snippet.

## Presentation

| Field          | Type              | Purpose                                                                                                        |
| -------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
| `sidebarTitle` | string            | Shorter label for the sidebar when the title is long                                                           |
| `icon`         | string            | Icon name, shown beside the sidebar label. See [icons](/guides/diagrams-and-code#icons)                        |
| `badge`        | string            | Small pill beside the sidebar label, e.g. `New`                                                                |
| `rightRail`    | `toc` \| `custom` | Defaults to `toc`. Set `custom` only when the page replaces the table of contents with rail-capable components |

## Publication

| Field     | Type    | Purpose                                                                                                      |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `draft`   | boolean | Keeps the page in the repository and out of every output. See [Drafts](/guides/authoring#drafts)             |
| `noindex` | boolean | Page stays reachable and in the sidebar, but out of search, the sitemap, the updates feed and the LLM corpus |

These two fields are different. A draft page does not exist on the site. A
`noindex` page exists, but the site never promotes it.

One file decides publication:
[`src/lib/published.ts`](https://github.com/DuvInc/duvlify/blob/main/src/lib/published.ts).
Every part of the code that lists pages reads the collection through this
file, instead of writing its own filter. This keeps the meaning of
"published" consistent across all eleven places that check it.

## Dates

| Field       | Type | Purpose                                                                             |
| ----------- | ---- | ----------------------------------------------------------------------------------- |
| `updated`   | date | Overrides the last-modified date, which otherwise comes from the file's last commit |
| `published` | date | First publication date, when it differs meaningfully from the last edit             |

Set `updated` when a change is substantial and the commit history does not
show that. A typo fix should not reset a page's freshness.

## Social

| Field      | Type   | Purpose                                     |
| ---------- | ------ | ------------------------------------------- |
| `image`    | string | Replaces the generated share card           |
| `imageAlt` | string | Alt text, when a custom `image` is supplied |

A page that sets neither still gets a full metadata set: a share card generated
from its title, a canonical URL, and structured data.

## API endpoint pages

Set these to render the three-column API reference layout for one operation in
your OpenAPI document. Normal prose pages are unaffected.

| Field            | Type                                            | Purpose                             |
| ---------------- | ----------------------------------------------- | ----------------------------------- |
| `pageType`       | `api-endpoint`                                  | Selects the endpoint layout         |
| `apiMethod`      | `GET` \| `POST` \| `PUT` \| `PATCH` \| `DELETE` | Must match an operation in the spec |
| `apiPath`        | string                                          | Must match that operation's path    |
| `apiOperationId` | string                                          | Optional override                   |
| `apiTag`         | string                                          | Optional override                   |

Full walkthrough in [API reference pages](/guides/api-reference).

## A complete example

```yaml
---
title: Progressive rollout
sidebarTitle: Rollouts
description: Increase a flag's exposure in stages that halt themselves when a guard metric moves.
icon: activity
badge: New
updated: 2026-08-01
---
```


---

# Components

Source: https://duvlify.dev/reference/components

Prefer a semantic PascalCase tag over styling content with `className`. The
complete vocabulary is declared in
[`src/components/mdx-components.ts`](https://github.com/DuvInc/duvlify/blob/main/src/components/mdx-components.ts),
with one line per author-facing name. An unknown tag fails the build and names
itself in the error.

Everything on this page is live. Each example shows exactly what the
component does.

## The vocabulary

| Group                  | Tags                                                                                                               |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Structure              | `Tabs`, `Tab`, `CodeGroup`, `CodeBlock`, `Steps`, `Step`, `Columns`, `Column`, `Panel`, `Frame`                    |
| Emphasis               | `Callout`, `Note`, `Warning`, `Info`, `Tip`, `Check`, `Danger`, `Banner`, `Badge`, `Update`, `Tooltip`             |
| Content and API        | `Prompt`, `ParamField`, `ResponseField`, `RequestExample`, `ResponseExample`, `Examples`, `Endpoint`               |
| Disclosure             | `Accordion`, `AccordionGroup`, `Expandable`                                                                        |
| Audience and variants  | `View`, `Visibility`                                                                                               |
| Navigation and visuals | `Card`, `CardGroup`, `Tile`, `Tree`, `TreeFolder`, `TreeFile`, `Icon`, `Mermaid`, `Color`, `ColorRow`, `ColorItem` |

Some tags have shorter aliases. Duvlify keeps them because they match the
notation most documentation already uses: `FileTree`/`Folder`/`File` for the
tree, `Response` for `ResponseField`, and `Color.Row`/`Color.Item` and
`Tree.Folder`/`Tree.File` as member expressions of their parent. Each alias is
the same component as its full name.

## Callouts

A callout is one bordered, tinted aside. The `tone` prop selects both the tint
and the icon. `Note`, `Tip`, `Info`, `Check`, `Warning`, and `Danger` are
one-line wrappers that each pick a tone, so a page never has to name a colour
directly.

> **Info: A callout with a title**
>
> Use a callout when the statement is true of one passage. Use
> [`<Banner>`](#banners) when it is true of the whole page.

> **Tip**
>
> A tip, written as `<Tip>` rather than `<Callout tone="tip">`.

> **Warning**
>
> A warning. The reader can still proceed, but should know something first.

> **Danger**
>
> A danger, for consequences that cannot be undone.

```mdx
<Callout title="A callout with a title" tone="info">
  Reach for a callout when the statement is true of one passage.
</Callout>

<Tip>A tip, written as `<Tip>` rather than `<Callout tone="tip">`.</Tip>
```

Available tones: `info`, `note`, `success`, `tip`, `check`, `warning`, `danger`.

## Cards and tiles

[**A linked card**](/getting-started)

With `href` set, the card renders as an anchor and grows an arrow.

**An unlinked card**

Without `href`, the card is a plain titled block.

```mdx
<CardGroup cols={2}>
  <Card title="A linked card" href="/getting-started">
    <Icon slot="icon" name="rocket" size={22} />
    Given `href` it renders as an anchor and grows an arrow.
  </Card>
</CardGroup>
```

### Two meanings of `cols`

Both `<Columns>` and `<CardGroup>` take `cols`, but the prop means different
things for each. Knowing this helps explain why a group can show three cards
when four were asked for.

|             | `cols` means      | `cols={1}`          | `cols={4}` in the reading column   |
| ----------- | ----------------- | ------------------- | ---------------------------------- |
| `Columns`   | exactly this many | one full-width cell | four narrow cells                  |
| `CardGroup` | at most this many | one full-width card | three, then four in a wider layout |

`CardGroup` packs as many \~210px cards as fit and stops at `cols`. This keeps
each card at a readable width, and no page needs its own breakpoint. `Columns`
follows the exact layout the author wrote. Both props take values 1 to 4 and
collapse to one column on a phone.

## Steps

1. **Numbered automatically**

   The marker counts steps for you. Pass `icon` to replace the number. Pass
   `stepNumber` to continue a sequence that started elsewhere.
2. **Any content inside**

   Including code fences, callouts and tables.

```mdx
<Steps>
  <Step title="Numbered automatically">The marker counts for you.</Step>
  <Step title="Any content inside">Including code fences and callouts.</Step>
</Steps>
```

## Tabs

**First**

Tab panels can hold anything a page can.

**Second**

Including fences, callouts and tables.

**Third**

Three panels here.

Tab groups **synchronize when they offer the same labels in the same order**.
For example, every "npm / pnpm / yarn" group on a site moves together, and the
site remembers the choice for the next page. Groups that share only one label
do not synchronize. A group offering "REST" alongside two other options is a
different group from one offering "REST" alongside four options. Treating them
as the same group made unrelated sections jump together.

| Prop                  | Effect                                                                          |
| --------------------- | ------------------------------------------------------------------------------- |
| `sync={false}`        | Keeps this group local, on `Tabs`, `CodeGroup` or `RequestExample`              |
| `defaultTabIndex={1}` | Starts on the second panel. A reader's remembered choice takes priority over it |
| `dropdown`            | On `CodeGroup`, for when a horizontal language strip would be crowded           |

## Disclosure

**An accordion**

Closed by default. Pass `defaultOpen` to start it open. Pass `icon` for a
glyph beside the label.

**A second one**

Grouped in an `<AccordionGroup>`, so the accordions share one border.

`<Expandable>` is the lighter variant. Use it to reveal a nested object's
fields inside a parameter list, rather than a section of prose.

## Parameter fields

**`page_id`** (`string`, required)

The page identifier. `path`, `query`, `header`, and `body` each set where
the parameter lives, and the label reflects the choice.

**`limit`** (`integer`, 20)

Records per page. The API clamps requests above the maximum instead of
rejecting them.

```mdx
<ParamField path="page_id" type="string" required>
  The page identifier.
</ParamField>
```

On an [OpenAPI endpoint page](/guides/api-reference) you do not write these by
hand. The framework generates them from the spec. Write them yourself only for
an API this framework does not drive, or for a configuration object.

## Badges, updates and tooltips

Default green outlined with an icon

A tooltip wraps inline text.

**What changed**

`<Update>` is the changelog entry: a dated block with optional tags, meant
to stack down a release-notes page. The label becomes the anchor, in
slugified form. This gives a date written for a reader a usable permalink
too.

## Banners

`<Banner>` states something true of one page, in the reading column:

> **Warning: Superseded**
>
> This section is kept for reference.

For an announcement on **every** page, set `site.banner` in
`src/docs.config.ts` instead. This creates the strip fixed above the navbar,
which this site is using right now. There is deliberately no per-page
equivalent of that strip. A fixed bar states something true of the whole
documentation set. Something true of one page belongs in the page instead.

The site remembers a dismissal against the exact text of the banner.
Publishing new wording shows the banner again to everyone who dismissed the
previous version. This same behaviour makes the strip unsuitable for anything
a reader must not be able to hide.

## File trees

- `app/`
  - `index.mdx`
  - `guides/`
    - `authoring.mdx`
- `astro.config.ts`

```mdx
<Tree>
  <TreeFolder name="app">
    <TreeFile name="index.mdx" />
  </TreeFolder>
</Tree>
```

`FileTree`, `Folder`, and `File` are aliases for the same three components.
`Tree.Folder` and `Tree.File` are the same components again, written as member
expressions of their parent. The tree above uses this member-expression form.
All three notations leave identical Markdown in the page's twin, so an agent
reading it sees a folder listing rather than component syntax.

## Colours

- **Accent** — `{ light: '#16866a', dark: '#68b09e' }`
- **Accent strong** — `#0f5e4a`

`<Color.Item>` takes either one value or a `{ light, dark }` pair. It captions
the swatch with exactly what you wrote, not a sanitised version of it. Use
`variant="table"` for a labelled palette. Leave it off for a compact row.

## Columns

Exactly two cells. `Columns` follows the layout you drew.
Collapses to one column on a phone.

## The right rail

Top-level `Panel`, `RequestExample`, and `ResponseExample` content occupies the
sticky right rail on desktop, and returns to the article on smaller screens.

**A panel.** On a page with `rightRail: custom`, the build would lift this
panel into the sticky rail, replacing the table of contents. This page
keeps its contents listing, so the panel stays inline. This inline
placement is the documented default, not a special case.

Set `rightRail: custom` in frontmatter only on a page that deliberately
replaces the table of contents with those components. Such a page uses the
same layout as an OpenAPI endpoint page: the same wider three-track frame, and
the same sticky panel. Both pages share one shape: prose in the middle,
examples alongside. Below 1280px, the build hides the rail column either way.

## Page-wide variants

Use `<View>` for one page-wide language or framework selector. Use `<Tabs>`
for alternatives local to one passage. Two or more views make the selector
appear. One view on its own renders as an ordinary section. This is what
makes it safe to write a page one view at a time.

**TypeScript**

With two or more views on a page, a single selector appears above them and
switches the whole page at once. This is the TypeScript variant.

**Python**

This is the Python variant. Only one view is visible at a time. The
selector is the platform's own `<select>` element, so an option cannot
carry an icon. This is why a `View` is labelled by its `title` alone.

For content that differs between readers and models, rather than between
frameworks, use `<Visibility>`:

You are reading the Markdown twin, so this paragraph appears. The rendered
page carries a different paragraph in its place.

Full explanation in [Authoring](/guides/authoring#content-for-humans-content-for-agents).

## Diagrams

A ` ```mermaid ` fence is the usual way to add a diagram. See
[Code and diagrams](/guides/diagrams-and-code#diagrams). Use the `<Mermaid>`
component for one-liners and for the interactive controls:

```mermaid
`flowchart LR
A["content/page.mdx"] --> B["HTML"]
A --> C["page.md"]
A --> D["share card"]
C --> E["fetch tool"]`
```

`actions={true}` adds pan, zoom, reset, and a fullscreen viewer on hover or
keyboard focus. `placement` positions the inline controls. Set
`actions={false}` to make a deliberately static diagram.

## Icons

Every icon on the site comes from [Lucide](https://lucide.dev) through
`<Icon name="…" />`, never a raw emoji or Unicode glyph. A plain character
renders without error, but it looks inconsistent next to a Lucide icon: the
weight, baseline, and style differ.

`name` is a short alias, not the Lucide name directly. See the `icons` map in
[`src/components/Icon.astro`](https://github.com/DuvInc/duvlify/blob/main/src/components/Icon.astro)
for what is available. If the icon you need is not there, import it from
`@lucide/astro` and add one line to that map.

> **Note: One tag you rarely write**
>
> `ApiResponseDetails` renders the response documentation for an OpenAPI
> operation. Endpoint pages get it from the generated layout. It is in the
> vocabulary so a hand-written page can place it, but a hand-written page
> usually should not.


---

# Configuration

Source: https://duvlify.dev/reference/configuration

Everything you change to make this site yours lives in
[`src/docs.config.ts`](https://github.com/DuvInc/duvlify/blob/main/src/docs.config.ts). You do not need to edit
`src/components/`, `src/styles/`, or `worker/` to rebrand the site, change its
navigation, or turn features on and off. If you find yourself editing those
files to change a string, treat that as a bug in this configuration file, not
something to work around.

The configuration file has five exports.

## `site` — identity

This export sets the name, title suffix, description, header and footer
links, and the assistant menu. The description is the site-level meta
description and the blockquote in `llms.txt`. Write one real sentence for it,
not a slogan.

`basePath` decides where the documentation sits under its domain. Use `''`
for `docs.example.com/page`, or `'/docs'` for `example.com/docs/page`. This
one setting moves every generated URL. The Worker strips the prefix back off
before it looks anything up. `basePath` must stay in step with Astro's `base`
in `astro.config.ts`, so both settings read from the same constant. See
[`DEPLOYMENT.md`](/guides/deployment) for the topologies, the Cloudflare
route, and the three things a subpath cannot have.

One rule comes with `basePath`. An internal link written by hand _in this
file_ must carry the prefix itself (`` `${basePath}/getting-started` ``).
Links built from a page id go through `hrefFor`, which applies the prefix for
you. An authored string without the prefix is indistinguishable from a link
to another site.

`homePageId` is the one subtle field. Leave it `undefined` for a docs-first
site whose home page is its first page. Set it to a content id to serve that
page at `/`, outside the navigation. That page stays published, indexed, and
in the corpus, but it is not a sidebar item and takes no part in
previous/next navigation. A page named here must _not_ also appear in
`navigation`. The build refuses that combination, because the page would be
reachable at two URLs.

`banner` is a site-wide announcement fixed above the navbar. It takes
`content`, a `tone` (`info`, `warning`, or `critical`), `dismissible`, and an
optional `color` per colour mode. Leave it `undefined` for no strip. The site
stores a dismissal against the exact text, so publishing new wording shows
the banner again to everyone who dismissed the previous version. This same
behaviour makes the strip unsuitable for anything a reader must not be able
to hide.

Turning the banner on changes the shell's geometry, and nothing in this file
has to account for that. The height lives in `--banner-h`
([`src/styles/tokens.css`](https://github.com/DuvInc/duvlify/blob/main/src/styles/tokens.css)). Every fixed bar, the
document's top padding on both desktop and mobile, and `scroll-padding-top`
all derive from that one value.

## `seo` — search and generative engines

This export sets the publisher identity for the JSON-LD graph, the locale,
the AI crawler allowlist, and Cloudflare Content Signals.

Write `agentInstructions` with care. The build emits it as prose at the top
of `llms.txt` and `llms-full.txt`, in the space the llmstxt.org format leaves
between the summary and the links. Limit it to facts a model cannot infer
from the pages: which document wins when two disagree, what the site does
not cover, and what it must not guess at. Restating the product description
adds no value, because `site.description` already sits directly above it.

The build deliberately does _not_ prepend `agentInstructions` to every
page's Markdown. That would put the same paragraph in front of a reader who
clicked "Copy page" for one answer. It would also make anything crawling the
corpus re-read the paragraph once per page.

## `theme` — brand

This export sets the font, accent, and radius. The build injects these as CSS
custom properties, so changing the accent is one line. The neutral palette
and component styling live in `src/styles/`.

`accent.strong` exists because `accent.base` usually cannot clear a 4.5:1
contrast ratio against the accent _tints_ used behind badges and method
pills. It can only clear that ratio against the page background. Check both
contrasts when you change the accent.

### Changing the page background

`--bg` in [`src/styles/tokens.css`](https://github.com/DuvInc/duvlify/blob/main/src/styles/tokens.css) is the one colour a
site most often wants to move, for example to a light grey canvas that
matches a marketing site. Change only this value. The raised surfaces follow
it automatically.

`--surface-2` (hover) and `--surface-active` (the current item) are not fixed
colours. Each is `--bg` mixed a measured distance toward `--text` in OKLab.
This holds the same perceptual separation from whatever background you set,
in both colour modes. The percentages differ by mode because perceived
contrast differs by mode: dark mode needs roughly twice the lightness step to
read the same as light mode.

These values used to be absolute colours, which worked only while `--bg`
stayed white. One site set `--bg: #f5f5f5` and got a `--surface-2` of
`#f5f5f5` too. The selected sidebar item then rendered in exactly the page
colour and disappeared. Nothing was misconfigured. The tokens simply did not
know the background had moved. If you find yourself hand-picking a second
colour after changing `--bg`, that is the same bug returning.

## `navigation` — structure

This export lists tabs, groups, and page ids in sidebar order. Labels,
descriptions, icons, and badges come from each page's own frontmatter. This
export never restates them.

`navigationLayout.mode` switches between `category-tabs` (large categories in
a bar under the navbar) and `unified-sidebar` (everything in one left rail).
Changing this mode never changes routes, content, or navigation data.

The build validates this export against the content collection. A page id
with no matching file fails the build. A published page that belongs to no
group also fails the build. A page id that names a draft is skipped silently,
and it takes any group or tab it would have emptied with it. This last case
is what lets you leave work-in-progress listed here while it stays unpublished.
See [Drafts](/guides/authoring#drafts).

## `agents` — the MCP server, HTTP API and WebMCP

```ts
export const agents = {
  enabled: true,            // master switch for all three surfaces
  http: true,               // also serve /api/docs/*
  retrieval: 'lexical',     // or 'ai-search'
  aiSearchInstance: '…',
  defaultLimit: 8,
  maxLimit: 25,
  feedback: { webhook: undefined, fields: [ … ], context: [ … ] },
  webmcpBridge: 'off',      // 'on' where there is no Cloudflare zone
  rateLimit: { search: 30, read: 90, write: 2 },
};
```

Setting `enabled: false` registers no routes, provisions nothing, and skips
the index upload. A site that wants plain documentation carries none of that
cost. Full detail in [`AGENTS.md`](/agents/overview).

## Also configurable

- [`src/openapi.config.ts`](https://github.com/DuvInc/duvlify/blob/main/src/openapi.config.ts): the OpenAPI document the
  endpoint pages render from. Leave the empty stub, and the build emits no
  `/openapi.json` and advertises nothing. A site with no API should not
  publish a spec with no paths, because an agent may read that as evidence
  that the API has no endpoints.
- [`src/icon-aliases.ts`](https://github.com/DuvInc/duvlify/blob/main/src/icon-aliases.ts): short names for icons.
- [`public/_headers`](https://github.com/DuvInc/duvlify/blob/main/public/_headers): caching and security headers.
- [`wrangler.jsonc`](https://github.com/DuvInc/duvlify/blob/main/wrangler.jsonc): the Worker, its asset routing, and the
  rate limiting bindings.

## The values every site must set

A fresh clone runs as is. `npm run dev`, `npm run build`, and `npm test` all
pass with nothing configured, because every service integration defaults to
off and search falls back to the built lexical index. This is intentional.
The alternative is a template that fails on first contact until you set up an
account somewhere.

The cost of that choice is that a fresh clone carries **this** site's values.
Those values are wrong for your site, often in ways that are easy to miss.
The list below orders them by how soon each one will cause a problem.

| Where                                            | What a clone starts with   | What happens if you leave it                                                                                                                        |
| ------------------------------------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `astro.config.ts` → `site`                       | `https://docs.example.com` | Canonical tags, the sitemap, `llms.txt` and the agent manifest all name a host that is not yours. The site looks fine and the SEO points elsewhere. |
| `wrangler.jsonc` → `name`                        | `duvlify-docs`             | Your first deploy creates a Worker under that name, or collides with one.                                                                           |
| `src/docs.config.ts` → `site`, `seo`, `theme`    | Duvlify's own identity     | Cosmetic, and obvious on first render.                                                                                                              |
| `src/docs.config.ts` → `agents.aiSearchInstance` | `duvlify-docs`             | The build reads this only when `retrieval` is `'ai-search'`. It stays inert until then.                                                             |
| `src/openapi.config.ts`                          | an empty stub              | The build emits nothing and advertises no spec, which is the right behaviour for a site with no API of its own.                                     |
| `content/`                                       | Duvlify's documentation    | You publish someone else's docs. Delete the folder and write your own.                                                                              |

Set the origin before anything else. Export `SITE_URL` in the deploy
environment rather than editing the fallback. This way, a preview build and a
production build cannot disagree.

## Secrets

There is one file, [`.env.example`](https://github.com/DuvInc/duvlify/blob/main/.env.example). Copy it to `.env` and fill
in what you need. `.env` is gitignored.

Only two values are real secrets. Both are used only by
`scripts/index-sync.mjs`, and neither reaches the Worker. The Worker queries
the index through its `AI_SEARCH` binding instead:

- `CLOUDFLARE_ACCOUNT_ID`
- `AI_SEARCH_TOKEN`: **not** the token `wrangler` holds. Create a separate
  token under AI → AI Search → Tokens with `AI Search:Edit` and
  `AI Search:Run`.

`agents.feedback.webhook` is notably _not_ a secret. The build reads it at
build time and compiles it into the Worker bundle, so a URL that carries a
token would be served to anyone who asks for it. Use a receiver that
authenticates some other way.

Switching semantic retrieval on takes three edits, and all three must agree.
This is the usual way it goes wrong. Uncomment the `ai_search` binding in
`wrangler.jsonc`, set `agents.retrieval` to `'ai-search'`, and set
`agents.aiSearchInstance` to the same instance name used in the binding. Then
run `npm run index:sync`.

The instance name appears twice on purpose, and the two copies must agree.
The Worker queries through the binding, while `scripts/index-sync.mjs` reads
the name out of the config to build its REST URL. A mismatch causes no
visible error. The Worker keeps answering, either from the wrong index or
from none.

Once semantic retrieval is on, `npm run deploy` chains `index:sync` between
the build and `wrangler deploy`. This makes a deploy from a shell without the
two credentials fail before it ships, instead of shipping a Worker that
queries an index one version behind. [`AGENTS.md`](/agents/overview) covers
creating the instance, the settings that are not obvious from the dashboard,
and how the index is reconciled.


---

# Theming

Source: https://duvlify.dev/reference/theming

Brand-level settings live in the `theme` block of `src/docs.config.ts`.
`ThemeTokens.astro` turns them into CSS custom properties, and
`astro.config.ts` hands the same font config to Astro's fonts API. Changing
the accent or the font is therefore a single edit, and no stylesheet needs
touching.

```ts title="src/docs.config.ts"
export const theme = {
  font: { sans: 'Inter', sansWeights: ['400 800'], mono: 'ui-monospace, …' },
  accent: { base: '#16866a', strong: '#0f5e4a', strongDark: '#68b09e', contrast: '#ffffff' },
  headerPrimary: { background: '', foreground: '' },
  radius: { lg: '16px', md: '12px', sm: '8px', xs: '6px', smoothing: 'subtle' },
} as const;
```

## The accent has four values, not one

This section explains a detail that often causes confusion.

| Field        | Role                                                         |
| ------------ | ------------------------------------------------------------ |
| `base`       | Fills and tints                                              |
| `strong`     | Text, borders, and active states, in light mode              |
| `strongDark` | The same role in dark mode, where `strong` would be too dark |
| `contrast`   | Text placed on top of a solid `base` fill                    |

`strong` exists because `base` usually cannot clear a 4.5:1 contrast ratio
against the accent _tints_ used behind badges, method pills, and changelog
labels. It can only clear that ratio against the page background. Those
tints are the accent at 12 to 24% over the background. A plausible-looking
accent often fails contrast specifically at the tint.

> **Warning: Measure both, not just the background**
>
> A colour picker shows you contrast against the page. Check the tint too.
> This site's `strong` clears 7.72:1 on the background and 5.64:1 on the
> densest tint. A shade one step lighter passed the first test and failed
> the second.

`contrast` has its own risk. A mid-tone accent is the worst case. If you
lighten `base` much past a 500-weight, neither white nor a dark shade of the
same hue clears 4.5:1 on it, because the fill then sits halfway between the
two. If nothing works, move `base` instead of searching for a text colour.

### An unrelated call-to-action colour

The topbar's filled primary button takes the accent colour by default. Set
either field of `headerPrimary` to break that link. A brand's call-to-action
colour is sometimes fixed and unrelated to the site's accent, and it should
not move whenever the accent does. Many brands use a black call-to-action
colour.

Leaving both `''` keeps the default, `accent.base` over `accent.contrast`.

## Changing the page background

`--bg` in
[`src/styles/tokens.css`](https://github.com/DuvInc/duvlify/blob/main/src/styles/tokens.css)
is the one colour a site most often wants to move, for example to a light
grey canvas that matches a marketing site. Change only this value. The raised
surfaces follow it automatically.

`--surface-2` (hover) and `--surface-active` (the current item) are not fixed
colours. Each is `--bg` mixed a measured distance toward `--text` in OKLab.
This holds the same perceptual separation from whatever background you set,
in both colour modes. The percentages differ by mode because perceived
contrast differs by mode: dark mode needs roughly twice the lightness step to
read the same as light mode.

> **Note: Why that is written down**
>
> These values used to be absolute colours, which worked only while `--bg`
> stayed white. One site set `--bg: #f5f5f5` and got a `--surface-2` of
> `#f5f5f5` too. The selected sidebar item then rendered in exactly the page
> colour and disappeared. Nothing was misconfigured. The tokens simply did
> not know the background had moved. If you find yourself hand-picking a
> second colour after changing `--bg`, that is the same bug returning.

## Fonts

```ts
font: {
  sans: 'Inter',
  sansWeights: ['400 800'],
  sansVariable: '--font-brand',
  mono: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
}
```

The site uses `sans` for all interface and prose text. Astro downloads the
family at build time and emits the `@font-face` rules and preloads. This
avoids a render-blocking round trip to a font CDN, and it stops any third
party from learning your readers' IP addresses.

A single entry like `'400 800'` requests that weight range from a variable
font, which is one file instead of five. `mono` is a plain CSS stack: code is
set in whatever font the reader's system already has. This is both faster and
what most developers prefer.

> **Warning: A self-hosted font is a redistributed font**
>
> Because the font family ends up in `dist/`, deploying the site means
> serving those files from your own origin, and the font's licence travels
> with them. Inter is under the SIL Open Font License. Keep the licence
> available. Note also that the OFL reserves the name: a modified version may
> not be distributed as "Inter". Set `sans` to a system stack to opt out of
> self-hosting entirely. See the repository's `NOTICE`.

## Radius, and continuous corners

Radii step down as elements nest: shells use `lg`, then wells use `md`, then
controls use `sm` or `xs`.

`smoothing` turns on iOS-style continuous corners. The curve blends smoothly
into each straight edge, instead of the abrupt transition of an ordinary
circular radius. This uses native CSS, the `corner-shape` property, applied
once and globally in `shell.css`. Nothing here is a JavaScript or mask
polyfill. A browser that does not yet know the property simply keeps the
plain radius, because an unrecognised CSS property is inert and does not
break anything.

| Value      | Result                                                 |
| ---------- | ------------------------------------------------------ |
| `none`     | Ordinary round corners                                 |
| `subtle`   | A light continuous curve, what this site uses          |
| `standard` | A clearly continuous curve                             |
| `ios`      | The spec's own `squircle` keyword, the strongest curve |

## Where the rest lives

The neutral palette and the component styling are in
[`src/styles/tokens.css`](https://github.com/DuvInc/duvlify/blob/main/src/styles/tokens.css)
and
[`components.css`](https://github.com/DuvInc/duvlify/blob/main/src/styles/components.css).
The site designs both colour modes directly, rather than deriving one mode
from the other by inversion.

If you find yourself editing a stylesheet to change a brand value, treat that
as a gap in the `theme` block, not something to work around.


---

# How the build works

Source: https://duvlify.dev/reference/architecture

Duvlify uses Astro with static output and no framework runtime. The site
ships HTML and one shared JavaScript bundle for the interface, and nothing
else. There is no hydration and no client-side router. Everything below
follows from this design.

## The layout

```
content/         the pages your site publishes.
src/
  docs.config.ts identity, theme, navigation, agent settings
  content.config.ts   the frontmatter schema
  components/    the MDX component set and the page shell
  lib/           build-time logic: navigation, Markdown, manifest, SEO
  pages/         routes — HTML, .md twins, feeds, indexes, share cards
  scripts/       the interface's client-side code
  styles/        tokens, reset, shell, components
worker/          the edge Worker: headers, negotiation, agent surfaces
scripts/         build-time tooling (index-sync)
test/            assertions against a real build and a real Worker
```

## The join that holds everything together

A page declares _what it is_ in its frontmatter: its title, description, and
icon. `docs.config.ts` declares _where it sits_. `src/lib/navigation.ts`
joins the two at build time. Every consumer then reads that one resolved
tree: the sidebar, the tabs, the breadcrumb, previous/next, search, the
sitemap, `llms.txt`, and the agent manifest.

Because there is one join, a mismatch is a build failure rather than a silent
problem. The build reports the file or id at fault. Because there is one
tree, no two surfaces can disagree about what the site contains.

## Publication

`src/lib/published.ts` owns one question: does this page ship? `draft: true`
means the file stays in the repository and out of every output. There is no
route, no Markdown twin, no share card, no sidebar entry, no search result,
no sitemap row, no line in `llms.txt`, and nothing reachable through the MCP.

Every consumer reads the collection through that module, instead of
repeating the filter itself. This keeps the meaning of "published" consistent
across all eleven places that check it. The one time a filter gets written
out locally is the time a draft leaks into exactly one output, and that
output is usually one nobody checks.

`noindex` is a different switch. That page _is_ published, routed, and
linked from the sidebar. The build keeps it out of the surfaces that promote
a page: search results, the sitemap, the updates feed, and the `llms.txt`
corpus. The reasoning is that a page deliberately withheld from search should
not be handed to a model either. The page remains fetchable at its URL and as
Markdown.

## One page, several representations

The build emits each page as:

- **HTML**: `src/pages/[...slug].astro`, the canonical copy for people and
  search engines.
- **Markdown**: `src/pages/[...slug].md.ts`, with MDX components translated
  away, and a YAML header carrying `canonical`.
- **A share card**: `src/pages/og/[...slug].png.ts`, drawn as SVG and
  rasterised at build time.

A single function, `pageMarkdown()`, generates the Markdown. This matters
more than it looks. The same bytes are what `<page>.md` serves, what the
`fetch` tool returns, what the indexer uploads, and what the agent manifest
counts line numbers against. Four consumers share one source. Without this,
a passage's reported line range could silently point at the wrong paragraph.

## Build outputs

| Output                                          | Purpose                                                           |
| ----------------------------------------------- | ----------------------------------------------------------------- |
| `dist/**/index.html`                            | one fully rendered page each                                      |
| `dist/_astro/*`                                 | fingerprinted CSS, one JS bundle, self-hosted fonts, lazy Mermaid |
| `dist/<page>.md`                                | each page as Markdown, with a canonical header                    |
| `dist/og/<page>.png`                            | a generated 1200×630 card per page                                |
| `dist/search-index.json`                        | full-text index, fetched on first search                          |
| `dist/agent-manifest.json`                      | per-page outline with line offsets                                |
| `dist/llms.txt`, `llms-full.txt`                | corpus map and corpus                                             |
| `dist/sitemap.xml`, `robots.txt`, `updates.xml` | discovery                                                         |
| `dist/openapi.json`                             | when a spec is configured                                         |
| `dist/_headers`, `_redirects`                   | host-level caching, security, redirects                           |

## Performance decisions worth knowing

**The search index is a separate file.** It carries every page's body text.
The build fetches it only the first time a reader opens search; it is never
inlined. Page weight therefore stays flat as the corpus grows.

**Fonts are self-hosted.** Astro downloads the family at build time and
emits the `@font-face` rules and preloads. This avoids a render-blocking
round trip to a font CDN.

**Both Shiki themes ship as CSS variables.** `defaultColor: false` stops
Shiki from inlining one theme's colours, which would override dark mode.
Switching themes then costs no re-render.

**There is deliberately no Content-Security-Policy.** A useful policy needs
a strict `script-src` alongside a permissive `style-src-elem`. This is
because Mermaid draws a diagram by injecting a `<style>` element and setting
`style` attributes on every shape. It generates these at runtime from the
current colour mode, so nothing here can be hashed ahead of time. Astro's
CSP API cannot express that split. Shipping a policy that breaks a documented
feature is worse than shipping no policy. A policy loose enough to work would
use `unsafe-inline` throughout, which blocks nothing. This choice is worth
revisiting if diagrams are ever pre-rendered to static SVG.

## The Worker

The Worker serves every byte from `dist` through the `ASSETS` binding, and it
renders nothing itself. It adds header-based discovery, `Accept:
text/markdown` negotiation, and the agent surfaces. See
[`DEPLOYMENT.md`](/guides/deployment) and [`AGENTS.md`](/agents/overview).

## Testing

There are two test suites, and both run against a real build:

- `test/publication.test.mjs` derives its cases from `content/` and asserts
  the publication rules across every output: that a published page reaches
  all of them, a draft reaches none, and a `noindex` page is routed but
  unlisted. It runs over `dist` rather than calling the resolver directly,
  because the rule is an agreement between eleven outputs, and every past
  leak was one output disagreeing with the other ten.
- `test/agents.test.mjs` boots a Worker and exercises MCP and HTTP over the
  network, checking that the two return byte-identical responses.


---

# Serving agents

Source: https://duvlify.dev/agents/overview

People can read this site. Agents can call it. These are different jobs, so
the site serves them through different surfaces.

| Surface                              | Who uses it                                 | What it is                                         |
| ------------------------------------ | ------------------------------------------- | -------------------------------------------------- |
| `llms.txt`, `llms-full.txt`          | crawlers, training pipelines                | a map of the corpus and the corpus itself, as text |
| `<page>.md`, `Accept: text/markdown` | anything that follows a link                | every page as clean Markdown                       |
| `/mcp`                               | Claude, Cursor, ChatGPT, Claude Code        | the docs as callable tools                         |
| `/api/docs/*`                        | scripts, `curl`, anything without MCP       | the same tools as plain GET                        |
| WebMCP                               | agents running inside the visitor's browser | the same tools again, registered on the page       |
| `/agent-manifest.json`               | the Worker, and anyone curious              | the outline of every page with line offsets        |

The first two rows are static. They exist in the build output and cost
nothing to serve. The Worker serves the rest, and `agents.enabled` in
[`src/docs.config.ts`](https://github.com/DuvInc/duvlify/blob/main/src/docs.config.ts)
turns them all on together.

## The four tools

[`worker/agent/tools.ts`](https://github.com/DuvInc/duvlify/blob/main/worker/agent/tools.ts) defines each tool once, as a
name, a description, a JSON Schema and a handler. MCP, HTTP and WebMCP are
three adapters over that one array. This is why they always agree on what
`search` means. Adding a new tool takes one entry.

### `search(query, limit?)`

Returns passages grouped by the page they came from.

```jsonc
{
  "query": "custom domain",
  "pages": [
    {
      "url": "https://docs.example.com/guides/deployment",
      "title": "Deploy your site",
      "description": "…",
      "type": "page",
      "tab": "Guides",
      "updated": "2026-08-03",
      "totalLines": 176,
      "chunks": [
        { "lines": [52, 74], "heading": "Host configuration",              "text": "…" },
        { "lines": [75, 97], "heading": "Host configuration › Caching",    "text": "…" }
      ]
    }
  ]
}
```

The response uses two different orderings, and both are intentional:

- **Pages follow relevance.** The first passage of a page not yet seen creates
  that page at the next position. The order of `pages` is the ranking.
- **Chunks follow the page.** An agent reading three passages from one page
  wants them in reading order. Sorting by relevance would scramble a
  procedure whose steps only make sense in sequence.

**No score appears in the response, at either level.** Neither retrieval
backend produces a number an agent could interpret. A reciprocal-rank-fusion
score is a sum of inverted ranks, not a similarity score. An uninterpretable
number would only invite false confidence. Dropping it also lets the
retriever use `rrf`, which ranks better than the alternative that would have
produced a displayable figure.

`lines` and `totalLines` let an agent decide whether to call `fetch`. Three
passages spanning lines 40 to 95 of a 260-line page cover a third of a
scattered topic, so loading the whole page is worth it. One passage at lines
12 to 20 is not.

### `fetch(url)`

This tool returns the complete Markdown of one page. The Markdown is
byte-identical to what `<page>.md` serves and to what the index stores. It
takes the `url` from `search` or `list_pages`. A bare path also works, so an
agent that shortened a link still lands on the page.

Pages are identified by URL and nothing else. An internal id does exist. It
is the join key between AI Search's `item.key` and the build manifest, but it
never appears in a response.

### `list_pages(tab?, type?, prefix?, updated_since?)`

This tool lists the corpus without going through search. It shows what
pages exist, what kind of page each one is, and when it last changed. An
agent that calls an MCP server does not read `llms.txt`, so this tool is
where that information has to live for the agent to see it. It reads
entirely from the manifest, so it makes no retrieval call and costs nothing.

### `report_issue(page, …)` — optional

This tool stays hidden from `tools/list` until `agents.feedback.webhook` is
set. One declaration defines both the fields the agent must supply and the
payload the webhook receives, so the two cannot drift apart:

```ts
feedback: {
  webhook: 'https://example.com/hooks/docs-feedback',
  fields: [
    { name: 'problem', type: 'string', required: true, maxLength: 2000, description: '…' },
    { name: 'kind', type: 'enum', required: false, values: ['inaccurate', 'outdated', 'missing', 'unclear'] },
  ],
  context: ['page', 'pageId', 'agent', 'siteVersion', 'reportedAt'],
}
```

`fields` is what the agent supplies. `context` is what the Worker adds, and
the agent can neither supply it nor forge it. If delivery fails, the tool
reports the failure back to the agent as a message instead of throwing an
error. A feedback tool must never break the conversation that called it.


---

# The manifest, WebMCP and limits

Source: https://duvlify.dev/agents/mcp

## The manifest

[`src/lib/agent-manifest.ts`](https://github.com/DuvInc/duvlify/blob/main/src/lib/agent-manifest.ts) emits
`dist/agent-manifest.json` at build time. For each page it records the
page's identity and length. For each heading it records the full path (for
example, `"Custom domains › DNS records"`), the anchor, and the start and
end lines.

One rule makes the whole thing work: **line numbers are counted against the
exact bytes the site serves**. The same `pageMarkdown()` output is what
`<page>.md` returns, what `fetch` returns, and what the indexer uploads. If
these ever diverge, every line range silently starts pointing at the wrong
paragraph.

This is also how a passage gets a heading. AI Search returns chunk text but
not its position. So the Worker finds the text back inside the page and maps
the resulting line to the heading whose range contains it. It does this at
chunk granularity, which no per-page metadata field could ever express.

## WebMCP

Cloudflare's hosted bridge is the recommended route when the domain is a
Cloudflare zone. In the dashboard, go to **Agent Readiness → Labs → Enable
WebMCP**, then under _Tool packs_ check **Site MCP server** only.

The interface says "Leave every pack unchecked to use the default set". The
default set is actually _all_ packs, including a C2PA image-provenance
scanner. That scanner is pure noise on a documentation site, and it costs
context in every agent that loads the page. Check the one pack explicitly
instead.

That pack proxies **this site's own** `/mcp`. Cloudflare does not supply a
generic documentation MCP. It finds this site's server at `<origin>/mcp`,
which is why the MCP endpoint lives on the site's Worker rather than on one
of Cloudflare's own.

Where there is no zone, such as a `workers.dev` deployment or a fork without
a Cloudflare domain, that dashboard screen does not exist. In that case, set
`agents.webmcpBridge` to `'on'`, and this repository registers the tools
itself from
[`src/components/WebMcpBridge.astro`](https://github.com/DuvInc/duvlify/blob/main/src/components/WebMcpBridge.astro).
Never run both methods together, or the tools would be registered twice.

The browser API was renamed from `navigator.modelContext` to
`document.modelContext` between Chrome 149 and 150. The bridge reads both
names.

### The bridge is two files, and that split is deliberate

The relay logic, which loads the descriptors, sends a call by POST, and reads
the reply, lives in
[`src/lib/webmcp.ts`](https://github.com/DuvInc/duvlify/blob/main/src/lib/webmcp.ts). Only the part that genuinely needs a
browser stays in the component: reading `modelContext` and calling
`registerTool`.

The reason for this split is that the component's contents could not be
verified by a test. The bridge runs only inside a browser that ships the
WebMCP API, and no test here has one. So it broke the day `/mcp` moved to
the official MCP SDK, and nothing noticed. Two defects caused this, both
from assuming the transport was ordinary JSON-RPC over POST:

1. Streamable HTTP requires a client to accept **both** `application/json`
   and `text/event-stream`. The SDK enforces this with a **406** response.
   The bridge sent no `Accept` header, so every tool call was refused.
2. Once that header is sent, the SDK replies in **SSE**. `response.json()`
   throws an error on an SSE reply. Fixing only the first defect would have
   moved the failure, not removed it.

Both facts were already written down at the top of `test/agents.test.mjs`.
The test suite knew about them; the bridge did not, because the suite built
its own request instead of using the shipped one. This is the lesson worth
keeping: a test that reimplements the thing it is testing stays green
through the bug.

The handful of lines left in the component are still uncovered by tests.
There is no `modelContext` object in Node, and stubbing one would only prove
that the stub was called.

## Rate limiting

There are three bindings, one per tool family, because the tools do not cost
the same to run. `wrangler.jsonc` configures them, and `agents.rateLimit`
tunes them.

Know what this protection actually does before you trust it. The Workers
rate limiting binding accepts a window of **10 or 60 seconds and nothing
else**, so it cannot express an hourly cap. Its counters are also **per
Cloudflare datacenter**, not global, so a distributed client sees a multiple
of the configured number. Cloudflare documents this behavior as permissive
and eventually consistent by design.

This binding only dampens abuse. It is the protection that works before a
domain exists, which is exactly when nobody is watching.

The real ceiling belongs in a **WAF rate limiting rule** on the zone. A WAF
rule counts over long windows, counts globally, and blocks a request before
the Worker starts, so a flood costs nothing. Configure one on `/api/docs/*`
and `/mcp` once the domain is on Cloudflare, plus a stricter one on
`report_issue`. This rule belongs to operating the domain, not to this
repository, which is why it is documented here rather than committed as
code.

## Testing

[`test/agents.test.mjs`](https://github.com/DuvInc/duvlify/blob/main/test/agents.test.mjs) boots a real Worker and talks
to it over HTTP, rather than importing the handlers directly. The parts most
likely to break are not the pure functions. They are the ASSETS binding, the
manifest fetch, and the routing that has to keep `/mcp` away from the
Markdown content negotiation. A unit test of the grouping logic would pass
even while the endpoint returned a 404.

Among other things, the suite asserts that MCP and HTTP return
byte-identical responses for the same call, that the generated OpenAPI
description matches the live tool set exactly, that no score leaks into a
response, and that every reported line range really contains the passage it
claims.

The WebMCP suite imports `src/lib/webmcp.ts` and points it at the running
Worker. This means it exercises the code the browser actually runs, rather
than a copy of it; see the bridge section above for why that distinction is
the whole point. It checks that the descriptors are shaped the way
`registerTool` demands, that a relayed call comes back as parseable text,
that every advertised tool is reachable, that a failure arrives as a
readable message instead of a thrown exception, and that the suite reads
the reply correctly whether it arrives as JSON or as SSE.

To confirm that a test actually protects something, break the thing on
purpose and watch the test fail. Removing the `Accept` header from
`callTool` turns two of these tests red. Repeat that check whenever the
transport changes.


---

# Retrieval

Source: https://duvlify.dev/agents/retrieval

Search has two backends. One setting, `agents.retrieval` in
`src/docs.config.ts`, chooses between them. The first backend needs nothing.
The second needs an account, and it adds semantic matching.

### `lexical` — the default, and the floor

This backend scores the build's own search index inside the Worker. It needs
no account setup, no provisioning, and no external call, so it works on the
first deploy. It weights term frequency towards titles and headings. Two
corrections matter more than the weights themselves. First, the score damps
occurrence counts by section length, so a long API reference cannot outscore
a short, on-topic paragraph. Second, it measures coverage across the whole
page, because a question's terms are usually spread between a page's title
and its body.

The backend also does light suffix stripping. Without it, "deployment" fails
to match a page titled "Deploy your site", and the query lands on whichever
page repeats the exact word most.

This backend works well for a few hundred pages, which covers most
documentation sites.

### Two quality filters

Whichever backend runs, `worker/agent/retrieval.ts` filters the results
before grouping them into pages. Two constants control the filter. Both were
calibrated by measurement, and both are specific to this corpus:

| Constant                | Value | What it cuts                                                                      |
| ----------------------- | ----- | --------------------------------------------------------------------------------- |
| `MIN_VECTOR_SIMILARITY` | 0.54  | vector-only hits whose cosine similarity says the passage is about something else |
| `MIN_KEYWORD_SCORE`     | 12    | keyword hits that matched on one incidental common word rather than a real term   |

The retrieval logic keeps a passage if it clears **either** bar. This matters,
because an exact identifier, such as a header name, a CNAME record, or an
error code, often scores zero on vectors. A paraphrased question, in turn,
often has no keyword match at all.

Neither number transfers to another corpus. BM25 depends on term rarity and
query length. The vector bands depend on the embedding model. The reasoning
and the measured distributions are recorded beside each constant. Re-measure
before you change them.

Note that `match_threshold` is pinned low (0.001) in the AI Search request on
purpose. It is _not_ the tuning knob. Under reciprocal rank fusion its scale
is meaningless, and the instance default of 0.4 would filter out every
result. The real tuning lives in the two constants above.

### `ai-search` — semantic, opt-in

Cloudflare AI Search combines vector and keyword retrieval over the corpus.
The build pushes the corpus to it. This backend performs better on
paraphrased questions. To set it up:

1. Create an API token with **AI Search:Edit** and **AI Search:Run** under
   AI → AI Search → Tokens in the Cloudflare dashboard. This token differs
   from the one `wrangler` holds. `wrangler ai-search` refuses to run
   without it.

2. Create the instance:

   ```bash
   npx wrangler ai-search create <name> \
     --type builtin --chunk-size 450 --chunk-overlap 15 --hybrid-search \
     --custom-metadata type:text --custom-metadata updated:datetime \
     --custom-metadata tab:text --custom-metadata locale:text \
     --custom-metadata version:text
   ```

   The dashboard wizard offers the same settings through a slider instead of
   a free-typed number. The slider only lands on fixed increments. The
   production instance runs at **480**, the closest step to the 450 target,
   with 15% overlap and Hybrid search (Reciprocal Rank Fusion, Porter
   stemming) turned on. Either path produces a working instance. The CLI is
   exact, but at this chunk size the dashboard is close enough to make no
   practical difference.

3. Add the binding to `wrangler.jsonc`:

   ```jsonc
   "ai_search": [
     { "binding": "AI_SEARCH", "instance_name": "<name>", "remote": true }
   ]
   ```

   `compatibility_flags: ["nodejs_compat"]` must also be present, because the
   MCP SDK uses `node:async_hooks`. Without this flag, the Worker fails **at
   upload time** with `No such module "node:async_hooks"`. This error is
   clear, but it does not say what asked for the module. The flag ships
   enabled in both repositories.

   `ai_search` (singular) binds directly to one pre-existing instance, which
   is what a Worker actually needs. `ai_search_namespaces` is a different
   binding, for creating and managing instances dynamically at runtime, and
   nothing here does that. `remote: true` matters for local development.
   There is no local emulator for AI Search, so without this setting
   `wrangler dev` would bind to nothing, and every search would silently
   fall back to `lexical`.

4. Set `agents.retrieval` to `'ai-search'` and `agents.aiSearchInstance` to the
   name in `src/docs.config.ts`.

5. Push the corpus after each build: `npm run index:sync`, with
   `CLOUDFLARE_ACCOUNT_ID` and `AI_SEARCH_TOKEN` in the environment.
   `npm run index:dry` shows what would be sent without sending it.

If the binding is missing at runtime, the Worker falls back to `lexical`
instead of failing. A half-finished setup should return slightly worse
answers, not a 500 error.

### The index is reconciled, not just filled

Uploading is an upsert, so on its own the sync script only ever grows the
index. A page that is unpublished, renamed, or marked `noindex` keeps its old
chunks in the index. Search then keeps retrieving content the site itself no
longer serves. This is how three `noindex` compliance pages stayed queryable
after they left the manifest.

To fix this, the script now finishes by listing every indexed item and
deleting whatever the manifest no longer claims. The join is by key: the API
stores `<page id>.md` against the manifest's bare id. The manifest is the
whole published corpus, so anything outside it is stale by definition.

Two guards protect against failure:

- If more than a third of the index looks stale, the script deletes nothing
  and the run reports this. Otherwise, a truncated or half-built manifest
  could empty the index, and removing a third of a corpus is never a routine
  edit.
- A failure to _list_ is reported but does not fail the run. The upload half
  already succeeded, and blocking a good deploy over a cleanup problem would
  trade a small amount of staleness for a stopped release.

`npm run index:dry` prints the deletions as `would delete …` alongside the
uploads. This is a cheap way to check a large content change before it runs.

### When a page fails to upload

The uploader retries five times with exponential backoff. It also paces
itself between pages, because several hundred back-to-back connections would
otherwise draw a steady trickle of resets. A run that still fails is usually
a `503` stretch on Cloudflare's side rather than a bad payload. The total
backoff is about eight seconds, which is not enough to ride out a longer
outage.

The failed page keeps its previous content in the index, since nothing was
overwritten. The index is stale for that one page, not broken. Re-running
the whole script fixes this. The script is idempotent, and the API stores a
checksum per item, so re-running unchanged pages does not count as a content
change.

### Settings that are not obvious from the dashboard

The instance wizard offers several fields with a "smart default". Some of
these defaults are wrong for this use case. Others only matter for a feature
this Worker never uses. Here is what to pick instead, and why:

| Setting             | Smart default                 | Use instead                                                     | Why                                                                                                                                                                                                                                         |
| ------------------- | ----------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Chunk size          | 1024 tokens                   | \~480 (targeted 450; the slider snaps to steps, not free-typed) | At 1024 tokens, an answer and three unrelated paragraphs can end up in one chunk. \~450 keeps a chunk to roughly one section.                                                                                                               |
| Chunk overlap       | 10%                           | 15%                                                             | This stops a hinge sentence from landing exactly on a chunk boundary and being lost from both sides.                                                                                                                                        |
| Hybrid search       | Off                           | **On**                                                          | Vector-only search misses exact identifiers (`WORKER_LIMIT_EXCEEDED`, `apiPath`) that a keyword pass catches easily. This is the default most worth changing.                                                                               |
| Fusion method       | — (appears once hybrid is on) | Reciprocal Rank Fusion                                          | This combines results by rank rather than by raw score, so it avoids comparing two incompatible scales. It also means no per-chunk score is meaningful to publish; see below.                                                               |
| Reranking           | Off                           | Leave off                                                       | A cross-encoder pass whose only payoff is a displayable relevance number. This project never shows one, so the extra latency adds no value.                                                                                                 |
| Query rewriting     | Off                           | Leave off                                                       | This is the only step that calls a billed LLM. Nothing here needs the query rephrased.                                                                                                                                                      |
| **Score threshold** | **0.4**                       | **Do not trust this value; see the warning below**              |                                                                                                                                                                                                                                             |
| Similarity cache    | On, Strong, 48h               | On, Strong, **shorter TTL while content changes often**         | A cached answer survives a content fix for the length of the TTL. 48h works fine for a stable site. While you iterate on the docs, use a much shorter TTL (this deployment uses 30 minutes) to avoid serving a pre-fix answer for two days. |
| Generation model    | Smart default (auto)          | Leave it                                                        | AI Search's own answer-generation endpoint uses this setting, and this Worker never calls that endpoint. The Worker only calls retrieval and lets the caller's own model write the answer. The setting stays inert either way.              |
| Boost by            | —                             | Leave empty                                                     | Boosting by recency would rank a marginal page edited yesterday above a canonical page that has been stable for six months. `updated` is used as an explicit filter instead; see the metadata table above.                                  |

> **The 0.4 score threshold can silently return zero results, and the Worker
> does not trust it.** With Reciprocal Rank Fusion, a chunk's score is a sum
> of reciprocal ranks. With the standard formula, even a rank-1 hit on both
> signals tops out around 0.03, nothing like the 0.3 to 0.5 range that a
> cosine-similarity threshold would suggest. A 0.4 floor under `rrf` filters
> out every result, so the query comes back empty with no error to explain
> why.
>
> `worker/agent/retrieval.ts` sets `match_threshold: 0.001` explicitly on
> every request, instead of depending on the instance default, so this case
> is already handled. Still, lower the dashboard's own default too if you
> query the instance any other way, such as through the CLI, a script, or
> the dashboard's own test panel.

**Why the build pushes instead of letting Cloudflare crawl the site.**
Crawling would send a round trip through HTML the build already generated,
and it would lose everything the crawler cannot see: the page type, its
navigation tab, its real git date, its locale. Those are exactly the five
things worth filtering on.

**Why only five metadata fields.** AI Search limits each instance to five
fields, and they attach to the uploaded _item_, the whole page, not to its
chunks. So they are reserved for filtering and ranking (`type`, `updated`,
`tab`, `locale`, `version`), while everything descriptive comes from the
manifest instead. The last two fields are declared empty on purpose, because
adding a field later forces a full reindex.

### Heading paths are plain text

The outline is built from raw Markdown. Because of this, a decorated heading
such as `### **2. Update the DNS**`, common in migrated content, used to
reach the agent as `****2. Update the DNS****`. This leaked Markdown syntax
into a JSON string that nothing renders, and that a model might quote back
verbatim.

It also broke the anchor, which is the more important effect. Anchors are
matched against the renderer's own heading text, which carries no asterisks.
So every decorated heading missed the lookup and fell back to a computed
slug. This usually agreed with the real anchor by accident, since
slugification drops the punctuation anyway. But on a page that repeats a
heading, the renderer disambiguates the second one as `…-1`, while the
fallback always produced the first. A deep link to the second occurrence
then pointed silently at the first.

The fix strips inline Markdown from heading text before either use. The slug
lookup now keeps every anchor as the text produced it, in document order,
picked by occurrence. Underscores are deliberately left alone: `_emphasis_`
in a heading is rare, but `list_pages` in a heading is not.


---

# Discoverability

Source: https://duvlify.dev/agents/discovery

An endpoint that no agent ever finds is dead code. The build advertises each
endpoint in the places agents actually look: the `## Optional` section of
`llms.txt`, a comment block in `robots.txt`, and `Link` headers on every
page.

### `/.well-known/api-catalog`

The Worker serves two more well-known URIs, both defined relative to the
origin: `/.well-known/mcp.json` (with the server-card spelling beside it) and
`/.well-known/api-catalog`.

The catalog follows [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727), a
specification that answers a question the documentation itself cannot:
_which_ API. A site that documents a product actually has two APIs: the
product's own API, and this documentation's own read-only API under
`/api/docs`. Until an agent reads the docs, it has no way to tell the two
apart. The catalog states the difference in one fetch:

```json
{
  "linkset": [
    { "anchor": "https://api.example.com/v1",
      "service-desc": [{ "href": "https://docs.example.com/openapi.json", "type": "application/openapi+json" }],
      "service-doc":  [{ "href": "https://docs.example.com/", "type": "text/html" }] },
    { "anchor": "https://docs.example.com/api/docs",
      "service-desc": [{ "href": "https://docs.example.com/api/docs/openapi.json", "type": "application/openapi+json" }],
      "service-doc":  [{ "href": "https://docs.example.com/", "type": "text/html" }],
      "status":       [{ "href": "https://docs.example.com/api/docs", "type": "application/json" }] }
  ]
}
```

Three details matter, and `test/agents.test.mjs` asserts each one rather
than leaving it to review:

- The media type is `application/linkset+json`
  ([RFC 9264](https://www.rfc-editor.org/rfc/rfc9264)), not
  `application/json`. A client negotiating for a linkset will not accept the
  generic type.
- Every relation's value is an **array** of link target objects, even when
  there is only one link. A bare object is well-formed JSON, but no generic
  client reads it correctly.
- The first entry is anchored on the _API's own_ base URL, taken from the
  specification's `servers[0].url`, not on the page that describes it. This
  lets an agent holding a request URL match it against the catalog.

Each entry appears only when it is true. With no configured OpenAPI spec,
there is no first entry. With `agents.http` off, there is no second one. The
`<head>` advertises the catalog with `rel="api-catalog"`, and only on a root
deployment; see the subpath note below.

### DNS-based discovery, if you own the zone

Everything described above needs a fetch before an agent learns anything.
DNS-AID
([draft-mozleywilliams-dnsop-dnsaid](https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid),
built on [RFC 9460](https://www.rfc-editor.org/rfc/rfc9460) SVCB records)
moves this first step into DNS instead. A resolver can then answer "this
domain has agent endpoints, here they are" without any HTTP request at all.

This repository cannot set this up for you, because it only publishes
files, and DNS-AID is a zone operation. If your documentation is on a domain
you control, setting it up takes a few minutes in the DNS dashboard and no
code:

1. **Sign the zone.** Publish DNSSEC, so a validating resolver returns
   authenticated answers instead of whatever a middlebox chose to return. On
   Cloudflare this means going to DNS → Settings → DNSSEC → Enable, plus
   adding a DS record at your registrar. Unsigned records are still served,
   but an audit still marks them unvalidated. The signature is the whole
   point.
2. **Publish the discovery records.** ServiceMode SVCB/HTTPS records under
   `_agents`, one per protocol, with `alpn` and the endpoint path:

   | Name                              | Type    | Value                                                               |
   | --------------------------------- | ------- | ------------------------------------------------------------------- |
   | `_index._agents.docs.example.com` | `HTTPS` | `1 docs.example.com. alpn="h2" endpoint="/.well-known/api-catalog"` |
   | `_mcp._agents.docs.example.com`   | `HTTPS` | `1 docs.example.com. alpn="h2" endpoint="/mcp"`                     |

   Point `_index` at whichever document is your front door. With this engine
   that is the API catalog above. `llms.txt` is the alternative if you would
   rather send agents to prose than to a linkset.

Know two things before you spend time on this. First, the draft is still a
draft, so its parameter names may still change. Second, none of this is
possible on a `*.workers.dev` hostname, because that zone belongs to
Cloudflare, not to you. This is why an audit run against a preview
deployment reports DNS-AID as unvalidated no matter what you do. Attach your
own domain first.

### An agent-skills index, if you have skills to publish

[Cloudflare's Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc)
defines `/.well-known/agent-skills/index.json`. This file is a catalogue of
_skills_: instruction bundles an agent loads to learn how to work with you,
rather than tools the agent calls directly.

This engine does **not** publish one, and this is a deliberate choice rather
than an omission. Your MCP server already tells an agent what it can do, in
a form agents already act on. A skill would restate the same information in
a second format, and that format's spec is still at v0.2.0 and will change.
Publish a skill when you have something to say that the tool descriptions
cannot, such as a house convention for citing your docs, or a multi-step
procedure an agent should follow.

If you do, the shape is:

```json
{
  "$schema": "https://agentskills.io/schema/v0.2.0/index.json",
  "skills": [
    {
      "name": "search-example-docs",
      "type": "skill",
      "description": "How to answer questions about Example using its documentation MCP server.",
      "url": "https://docs.example.com/.well-known/agent-skills/search-example-docs/SKILL.md",
      "digest": "sha256-<base64 of the SKILL.md bytes>"
    }
  ]
}
```

Two implementation notes, both about the digest. First, the digest covers
the `SKILL.md` bytes, so it must be computed at build time from the file you
actually ship. A hand-written digest is a digest that silently stops
matching on the next edit. Second, because the index lives under
`/.well-known/`, serve it the same way the catalog above is served: from the
Worker, reading the built file, rather than as a static asset. Otherwise a
subpath deployment will publish it at a path no client looks at.

### And in the places people look

All of the above is invisible to a reader who has to paste a URL into
Claude or Cursor, and that reader is the one who actually does it. So
[`AgentAccess.astro`](https://github.com/DuvInc/duvlify/blob/main/src/components/AgentAccess.astro) provides the
human-facing half: one dialog with the MCP URL, an example API call, and the
raw-Markdown routes, each with a copy button.

Two places open this same dialog, so there is only one thing to learn:

- **The topbar**, next to search, where whole-documentation tools sit
  together.
- **The page menu**, last and behind a rule, because everything above it
  acts on the page being read, and these two entries do not. The menu has
  two entries rather than one combined entry (`Connect docs via MCP`,
  `Query the docs API`), because a reader arrives already knowing which of
  the two words they came for.

Every label and heading says "docs" or "these docs" out loud, and this is
not padding. A reader skims headings, and on a site documenting a product
that has its own MCP server, a bare "Connect via MCP" would read as the
product's. The dialog's prose is also kept deliberately plain: short
sentences, common words, and no dashes standing in for punctuation. This
matters because the reader reads it mid-setup, sometimes not in their first
language.

The dialog is gated on `agents.enabled` and `agents.http`, never on a flag
of its own. A dialog cannot advertise an endpoint that is switched off, so a
fork that never enables `agents` ships no dead button. On mobile, the
topbar button is hidden and the page-menu entries carry this function
instead, since the topbar has no room to spare.

If the product being documented also exposes an MCP server of its own, mind
the collision. In that case, a `/mcp-server` content page is about _the
product's_ MCP, while this dialog is about the documentation's own MCP.
Some sites built on Duvlify have exactly that pair. Name each one by the
difference, the same way the two OpenAPI descriptions do.