Add docs site

.gitignore

@@ -2,4 +2,6 @@ node_modules/
 dist/
 coverage/
 *.tsbuildinfo
+docs/.vitepress/cache/
+docs/deploy
 .DS_Store

docs/.vitepress/config.ts

@@ -0,0 +1,117 @@
+import { defineConfig } from 'vitepress';
+
+export default defineConfig({
+  title: 'AFDocs',
+  description: 'Test your documentation site against the Agent-Friendly Documentation Spec',
+
+  sitemap: {
+    hostname: 'https://afdocs.dev',
+  },
+
+  head: [
+    ['link', { rel: 'icon', type: 'image/x-icon', href: '/favicons/favicon.ico' }],
+    [
+      'link',
+      { rel: 'icon', type: 'image/png', sizes: '32x32', href: '/favicons/favicon-32x32.png' },
+    ],
+    [
+      'link',
+      { rel: 'icon', type: 'image/png', sizes: '16x16', href: '/favicons/favicon-16x16.png' },
+    ],
+    [
+      'link',
+      { rel: 'apple-touch-icon', sizes: '180x180', href: '/favicons/apple-icon-180x180.png' },
+    ],
+  ],
+
+  themeConfig: {
+    siteTitle: 'AFDocs',
+    logo: {
+      light: '/logos/afdoc_logo_light.svg',
+      dark: '/logos/afdoc_logo_dark.svg',
+    },
+
+    nav: [
+      { text: 'Guide', link: '/what-is-agent-score' },
+      { text: 'Checks', link: '/checks/' },
+      { text: 'Reference', link: '/reference/cli' },
+    ],
+
+    sidebar: [
+      {
+        text: 'The Score',
+        items: [
+          { text: 'What Is the Agent Score?', link: '/what-is-agent-score' },
+          {
+            text: 'Why Agent-Friendliness Matters',
+            link: '/why-agent-friendliness-matters',
+          },
+          {
+            text: 'Score Calculation',
+            link: '/agent-score-calculation',
+          },
+          {
+            text: 'Interaction Diagnostics',
+            link: '/interaction-diagnostics',
+          },
+        ],
+      },
+      {
+        text: 'Get Started',
+        items: [
+          { text: 'Quick Start', link: '/quick-start' },
+          { text: 'Run Locally', link: '/run-locally' },
+          { text: 'Improve Your Score', link: '/improve-your-score' },
+          { text: 'CI Integration', link: '/ci-integration' },
+        ],
+      },
+      {
+        text: 'Checks Reference',
+        items: [
+          { text: 'Overview', link: '/checks/' },
+          {
+            text: 'Content Discoverability',
+            link: '/checks/content-discoverability',
+          },
+          {
+            text: 'Markdown Availability',
+            link: '/checks/markdown-availability',
+          },
+          { text: 'Page Size', link: '/checks/page-size' },
+          { text: 'Content Structure', link: '/checks/content-structure' },
+          { text: 'URL Stability', link: '/checks/url-stability' },
+          { text: 'Observability', link: '/checks/observability' },
+          { text: 'Authentication', link: '/checks/authentication' },
+        ],
+      },
+      {
+        text: 'API Reference',
+        items: [
+          { text: 'CLI', link: '/reference/cli' },
+          { text: 'Programmatic API', link: '/reference/programmatic-api' },
+          { text: 'Scoring API', link: '/reference/scoring-api' },
+          { text: 'Config File', link: '/reference/config-file' },
+        ],
+      },
+      {
+        text: 'About',
+        items: [{ text: 'About AFDocs', link: '/about' }],
+      },
+    ],
+
+    socialLinks: [
+      {
+        icon: 'github',
+        link: 'https://github.com/agent-ecosystem/afdocs',
+      },
+    ],
+
+    editLink: {
+      pattern: 'https://github.com/agent-ecosystem/afdocs/edit/main/docs/:path',
+    },
+
+    footer: {
+      message: 'Released under the MIT License.',
+    },
+  },
+});

docs/.vitepress/theme/HomeLayout.vue

@@ -0,0 +1,16 @@
+<script setup>
+import DefaultTheme from 'vitepress/theme';
+import HeroScorecard from './components/HeroScorecard.vue';
+import LlmsDirective from './components/LlmsDirective.vue';
+</script>
+
+<template>
+  <DefaultTheme.Layout>
+    <template #home-hero-image>
+      <HeroScorecard />
+    </template>
+    <template #layout-top>
+      <LlmsDirective />
+    </template>
+  </DefaultTheme.Layout>
+</template>

docs/.vitepress/theme/components/HeroScorecard.vue

@@ -0,0 +1,75 @@
+<template>
+  <div class="hero-scorecard">
+    <pre><code><span class="header">Agent-Friendly Docs Scorecard</span>
+<span class="divider">==============================</span>
+
+  Overall Score: <span class="score-c">72 / 100 (C)</span>
+
+  Category Scores:
+    Content Discoverability       <span class="score-c">72 / 100 (C)</span>
+    Markdown Availability         <span class="score-d">60 / 100 (D)</span>
+    Page Size &amp; Truncation Risk   <span class="score-f">45 / 100 (F)</span>
+    Content Structure             <span class="score-b">82 / 100 (B)</span>
+    URL Stability                 <span class="score-a">93 / 100 (A)</span>
+    Observability                 <span class="score-c">71 / 100 (C)</span>
+    Authentication                <span class="score-a">100 / 100 (A+)</span></code></pre>
+  </div>
+</template>
+
+<style scoped>
+.hero-scorecard {
+  width: 100%;
+  max-width: 440px;
+  margin: 0 auto;
+}
+
+.hero-scorecard pre {
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-border);
+  border-radius: 12px;
+  padding: 20px 24px;
+  font-size: 13px;
+  line-height: 1.6;
+  overflow-x: auto;
+  margin: 0;
+}
+
+.hero-scorecard code {
+  font-family: var(--vp-font-family-mono);
+  color: var(--vp-c-text-1);
+}
+
+.header {
+  font-weight: 700;
+  color: var(--vp-c-brand-1);
+}
+
+.divider {
+  color: var(--vp-c-text-3);
+}
+
+.score-a {
+  color: var(--vp-c-green-1);
+  font-weight: 600;
+}
+
+.score-b {
+  color: var(--vp-c-green-2);
+  font-weight: 600;
+}
+
+.score-c {
+  color: var(--vp-c-yellow-1);
+  font-weight: 600;
+}
+
+.score-d {
+  color: var(--vp-c-yellow-2);
+  font-weight: 600;
+}
+
+.score-f {
+  color: var(--vp-c-red-1);
+  font-weight: 600;
+}
+</style>

docs/.vitepress/theme/components/LlmsDirective.vue

@@ -0,0 +1,19 @@
+<template>
+  <div
+    class="sr-only"
+    style="
+      position: absolute;
+      width: 1px;
+      height: 1px;
+      padding: 0;
+      margin: -1px;
+      overflow: hidden;
+      clip: rect(0, 0, 0, 0);
+      white-space: nowrap;
+      border: 0;
+    "
+  >
+    For AI agents: a documentation index is available at /llms.txt — markdown versions of all pages
+    are available by appending .md to any URL path.
+  </div>
+</template>

docs/.vitepress/theme/index.ts

@@ -0,0 +1,7 @@
+import DefaultTheme from 'vitepress/theme';
+import HomeLayout from './HomeLayout.vue';
+
+export default {
+  extends: DefaultTheme,
+  Layout: HomeLayout,
+};

docs/about.md

@@ -0,0 +1,72 @@
+# About AFDocs
+
+<div class="about-intro">
+<div class="about-text">
+
+AFDocs is an open-source tool that tests documentation sites against the [Agent-Friendly Documentation Spec](https://agentdocsspec.com). The spec defines what makes documentation accessible to AI coding agents, based on observed behavior across real agent platforms. AFDocs automates those observations into 22 checks that produce a score and actionable fix suggestions.
+
+</div>
+<div class="about-logo">
+  <img class="light-only" src="/logos/afdoc_logo_light.svg" alt="afdocs logo" width="200" height="200">
+  <img class="dark-only" src="/logos/afdoc_logo_dark.svg" alt="afdocs logo" width="200" height="200">
+</div>
+</div>
+
+## The Agent-Friendly Documentation Spec
+
+The [Agent-Friendly Documentation Spec](https://agentdocsspec.com) is the foundation for everything AFDocs checks. It documents:
+
+- How agents actually discover, fetch, and consume documentation
+- What fails in practice (truncation, empty SPA shells, auth gates, broken redirects)
+- What works (llms.txt, markdown availability, content negotiation, proper status codes)
+- Specific agent behaviors observed across Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI, and others
+
+The spec is maintained at [github.com/agent-ecosystem/agent-docs-spec](https://github.com/agent-ecosystem/agent-docs-spec) and is open for contributions.
+
+AFDocs implements spec v0.3.0 (2026-03-31).
+
+## Status
+
+AFDocs is in early development (0.x). Check IDs, CLI flags, and output formats may change between minor versions. The tool is usable today, but don't build automation against specific output details until 1.0.
+
+## Contributing
+
+AFDocs is developed at [github.com/agent-ecosystem/afdocs](https://github.com/agent-ecosystem/afdocs). Issues, bug reports, and pull requests are welcome.
+
+If you've tested AFDocs against your docs site and found a check that doesn't accurately reflect agent behavior, or a failure mode that isn't covered, that's especially valuable feedback. The checks are based on observed behavior, and more observations make them better.
+
+## License
+
+MIT
+
+<style>
+.about-intro {
+  display: flex;
+  align-items: center;
+  gap: 4.5rem;
+}
+.about-text {
+  flex: 1;
+}
+.about-logo {
+  flex-shrink: 0;
+}
+.dark .light-only {
+  display: none;
+}
+.dark-only {
+  display: none;
+}
+.dark .dark-only {
+  display: block;
+}
+@media (max-width: 768px) {
+  .about-intro {
+    flex-direction: column;
+  }
+  .about-logo {
+    order: -1;
+    text-align: center;
+  }
+}
+</style>