feat: add documentation

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
           node-version: latest
       - run: corepack enable
       - run: pnpm install
-      - run: pnpm run build
+      - run: pnpm run build:packages
 
   lint:
     runs-on: ubuntu-latest

apps/docs/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+.nuxt
+.output
+.data
+dist

apps/docs/app/app.config.ts

@@ -0,0 +1,84 @@
+export default defineAppConfig({
+  name: 'GitHub Tools',
+  description: 'AI-native GitHub tooling for safe, production-ready workflows.',
+  landing: false,
+  socials: {
+    x: 'https://x.com/hugorcd',
+  },
+  github: {
+    rootDir: 'apps/docs',
+  },
+  assistant: {
+    faqQuestions: [
+      {
+        category: 'Tools',
+        items: [
+          'What tools are available in the SDK?',
+          'How do I use GitHub tools with generateText?',
+          'Which tools require write permissions?',
+        ],
+      },
+      {
+        category: 'Presets',
+        items: [
+          'What is the difference between presets?',
+          'How do I combine multiple presets?',
+          'Which preset should I use for a code review bot?',
+        ],
+      },
+      {
+        category: 'Agents',
+        items: [
+          'How do I create a reusable GitHub agent?',
+          'What is the difference between createGithubTools and createGithubAgent?',
+          'How do I add custom system instructions to an agent?',
+        ],
+      },
+      {
+        category: 'Safety',
+        items: [
+          'How does approval control work?',
+          'What token permissions do I need?',
+          'How do I run the SDK in read-only mode?',
+        ],
+      },
+    ],
+  },
+  ui: {
+    colors: {
+      primary: 'emerald',
+      neutral: 'zinc',
+    },
+    prose: {
+      h1: {
+        slots: {
+          root: 'scroll-m-20 text-3xl/9 font-semibold tracking-tight sm:text-4xl/10',
+        },
+      },
+      h2: {
+        slots: {
+          root: 'mt-10 text-2xl/8 font-semibold tracking-tight',
+        },
+      },
+      p: {
+        slots: {
+          root: 'text-base/7 text-toned',
+        },
+      },
+    },
+    pageFeature: {
+      slots: {
+        root: 'relative rounded-sm py-2',
+        title: 'text-base/7 text-pretty font-semibold text-highlighted',
+        description: 'mt-1 text-[15px]/7 text-pretty text-muted',
+      },
+      variants: {
+        orientation: {
+          horizontal: {
+            root: 'mb-3 flex items-start gap-3',
+          },
+        },
+      },
+    },
+  },
+})

apps/docs/app/assets/css/main.css

@@ -0,0 +1,27 @@
+@import "tailwindcss";
+@import "@nuxt/ui";
+
+@theme {
+  --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --ui-container: 96rem;
+
+  --color-primary-50: oklch(0.97 0.03 162);
+  --color-primary-100: oklch(0.93 0.05 162);
+  --color-primary-200: oklch(0.88 0.08 162);
+  --color-primary-300: oklch(0.81 0.12 162);
+  --color-primary-400: oklch(0.73 0.16 162);
+  --color-primary-500: oklch(0.65 0.18 162);
+  --color-primary-600: oklch(0.56 0.15 162);
+  --color-primary-700: oklch(0.46 0.12 162);
+  --color-primary-800: oklch(0.37 0.09 162);
+  --color-primary-900: oklch(0.29 0.07 162);
+}
+
+:root {
+  --ui-bg: oklch(0.15 0.01 255);
+  color-scheme: dark;
+}
+
+body {
+  background: var(--ui-bg);
+}

apps/docs/app/components/app/AppHeader.vue

@@ -0,0 +1,64 @@
+<script setup lang="ts">
+import { useDocusI18n } from '#imports'
+
+const appConfig = useAppConfig()
+const site = useSiteConfig()
+
+const { isEnabled: isAssistantEnabled } = useAssistant()
+const { localePath, isEnabled, locales } = useDocusI18n()
+
+const links = computed(() => appConfig.github && appConfig.github.url
+  ? [
+      {
+        'icon': 'i-simple-icons-github',
+        'to': appConfig.github.url,
+        'target': '_blank',
+        'aria-label': 'GitHub',
+      },
+    ]
+  : [])
+</script>
+
+<template>
+  <UHeader
+    :ui="{ center: 'flex-1' }"
+    :to="localePath('/')"
+    :title="appConfig.header?.title || site.name"
+  >
+    <AppHeaderCenter />
+
+    <template #title>
+      <AppHeaderLogo class="h-6 w-auto shrink-0" />
+    </template>
+
+    <template #right>
+      <AppHeaderCTA />
+
+      <template v-if="isAssistantEnabled">
+        <AssistantChat />
+      </template>
+
+      <UContentSearchButton class="lg:hidden" />
+
+      <template v-if="links?.length">
+        <UButton
+          v-for="(link, index) of links"
+          :key="index"
+          v-bind="{ color: 'neutral', variant: 'ghost', ...link }"
+        />
+      </template>
+    </template>
+
+    <template #toggle="{ open, toggle }">
+      <IconMenuToggle
+        :open="open"
+        class="lg:hidden"
+        @click="toggle"
+      />
+    </template>
+
+    <template #body>
+      <AppHeaderBody />
+    </template>
+  </UHeader>
+</template>

apps/docs/app/components/app/AppHeaderLogo.vue

@@ -0,0 +1,10 @@
+<script setup lang="ts">
+const appConfig = useAppConfig()
+</script>
+
+<template>
+  <div class="flex items-center gap-2">
+    <UIcon name="i-simple-icons-github" class="size-5 text-white" />
+    <span class="font-semibold text-white">{{ appConfig.docus?.name || 'GitHub Tools' }}</span>
+  </div>
+</template>

apps/docs/app/pages/index.vue

@@ -0,0 +1,134 @@
+<script setup lang="ts">
+const layers = [
+  {
+    title: 'Tools',
+    description: '18 AI-callable GitHub operations — repositories, pull requests, issues, commits, and code search.',
+    to: '/api/tools-catalog',
+    icon: 'i-lucide-wrench',
+  },
+  {
+    title: 'Presets',
+    description: 'Curated tool subsets for focused workflows. Create specialized agents with separation of concerns.',
+    to: '/guide/presets',
+    icon: 'i-lucide-layers',
+  },
+  {
+    title: 'Agents',
+    description: 'Pre-configured agents with tools, presets, and system instructions ready to use.',
+    to: '/guide/examples',
+    icon: 'i-lucide-bot',
+  },
+]
+
+const guides = [
+  {
+    title: 'Quick Start',
+    description: 'Use GitHub tools in your first AI SDK call.',
+    to: '/guide/quick-start',
+    icon: 'i-lucide-play',
+  },
+  {
+    title: 'Control Write Safety',
+    description: 'Gate dangerous operations with approval policies.',
+    to: '/guide/approval-control',
+    icon: 'i-lucide-shield-check',
+  },
+  {
+    title: 'Configure Token Scopes',
+    description: 'Map GitHub token permissions to each preset.',
+    to: '/guide/token-permissions',
+    icon: 'i-lucide-key-round',
+  },
+  {
+    title: 'Examples',
+    description: 'Complete scripts you can copy and adapt.',
+    to: '/guide/examples',
+    icon: 'i-lucide-code',
+  },
+]
+
+const quickAccess = [
+  {
+    title: 'Installation',
+    to: '/getting-started/installation',
+    icon: 'i-lucide-download',
+  },
+  {
+    title: 'Tools Catalog',
+    to: '/api/tools-catalog',
+    icon: 'i-lucide-list-tree',
+  },
+  {
+    title: 'API Reference',
+    to: '/api/reference',
+    icon: 'i-lucide-braces',
+  },
+  {
+    title: 'Examples',
+    to: '/guide/examples',
+    icon: 'i-lucide-code',
+  },
+]
+</script>
+
+<template>
+  <NuxtLayout name="docs">
+    <section class="space-y-12 pt-8 pb-12 sm:pt-10">
+      <header class="space-y-3">
+        <h1 class="max-w-4xl text-3xl/9 font-semibold tracking-tight sm:text-4xl/10">GitHub Tools Documentation</h1>
+        <p class="max-w-4xl text-base/7 text-toned sm:text-lg/8">
+          AI-callable GitHub tools for <code class="text-sm">generateText</code>, <code class="text-sm">streamText</code>, and agent loops.
+        </p>
+      </header>
+
+      <section class="space-y-4">
+        <h2 class="text-xl/8 font-semibold tracking-tight sm:text-2xl/8">Three layers, one SDK</h2>
+        <div class="grid gap-4 lg:grid-cols-3">
+          <NuxtLink
+            v-for="item in layers"
+            :key="item.title"
+            :to="item.to"
+            class="group flex min-h-48 flex-col justify-between rounded-xl border border-default/60 bg-elevated/30 p-5 transition hover:-translate-y-0.5 hover:border-primary/35 hover:bg-elevated/80"
+          >
+            <UIcon :name="item.icon" class="size-5 text-toned transition group-hover:text-primary/90" />
+            <div class="space-y-2">
+              <p class="text-base/7 font-semibold">{{ item.title }}</p>
+              <p class="text-sm/6 text-toned">{{ item.description }}</p>
+            </div>
+          </NuxtLink>
+        </div>
+      </section>
+
+      <section class="space-y-4">
+        <h2 class="text-xl/8 font-semibold tracking-tight sm:text-2xl/8">Guides</h2>
+        <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
+          <NuxtLink
+            v-for="guide in guides"
+            :key="guide.title"
+            :to="guide.to"
+            class="group rounded-xl border border-default/60 bg-default/30 p-5 transition hover:border-primary/35 hover:bg-elevated/70"
+          >
+            <UIcon :name="guide.icon" class="size-4 text-toned transition group-hover:text-primary" />
+            <p class="mt-3 text-sm/6 font-medium">{{ guide.title }}</p>
+            <p class="mt-1 text-sm/6 text-toned">{{ guide.description }}</p>
+          </NuxtLink>
+        </div>
+      </section>
+
+      <section class="space-y-4">
+        <h2 class="text-xl/8 font-semibold tracking-tight sm:text-2xl/8">Quick access</h2>
+        <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
+          <NuxtLink
+            v-for="item in quickAccess"
+            :key="item.title"
+            :to="item.to"
+            class="group flex items-center gap-3 rounded-xl border border-default/60 bg-default/30 p-4 transition hover:border-primary/35 hover:bg-elevated/70"
+          >
+            <UIcon :name="item.icon" class="size-4 text-toned transition group-hover:text-primary" />
+            <span class="text-sm/6 font-medium">{{ item.title }}</span>
+          </NuxtLink>
+        </div>
+      </section>
+    </section>
+  </NuxtLayout>
+</template>

apps/docs/content/docs/1.getting-started/.navigation.yml

@@ -0,0 +1,2 @@
+title: Getting Started
+icon: i-lucide-rocket