Skip to content

Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base

improve docs

Hugo Richard41d2014fea35
diff --git a/apps/chat/.env.example b/apps/chat/.env.example
index f94af47..d8962da 100644
--- a/apps/chat/.env.example
+++ b/apps/chat/.env.example
@@ -27,13 +27,15 @@ NUXT_GITHUB_SNAPSHOT_BRANCH=main
# --- GitHub Bot (optional) ---------------------------------------------------
-# NUXT_PUBLIC_GITHUB_BOT_TRIGGER=@your-bot-name
+# NUXT_PUBLIC_GITHUB_APP_NAME=your-bot-name # GitHub App name (used for install URL and bot username)
+# NUXT_PUBLIC_GITHUB_BOT_TRIGGER= # Override bot mention trigger (defaults to app name)
# NUXT_GITHUB_APP_ID=
# NUXT_GITHUB_APP_PRIVATE_KEY=
# NUXT_GITHUB_WEBHOOK_SECRET=
# --- Discord Bot (optional) --------------------------------------------------
+# NUXT_PUBLIC_DISCORD_BOT_URL= # Full Discord bot invite URL
# NUXT_DISCORD_BOT_TOKEN=
# NUXT_DISCORD_PUBLIC_KEY=
# NUXT_DISCORD_APPLICATION_ID=
diff --git a/apps/chat/app/components/DocToc.vue b/apps/chat/app/components/DocToc.vue
new file mode 100644
index 0000000..52fb328
--- /dev/null
+++ b/apps/chat/app/components/DocToc.vue
@@ -0,0 +1,160 @@
+<script setup lang="ts">
+interface TocLink {
+ id: string
+ text: string
+ depth: number
+ children?: TocLink[]
+}
+
+const props = defineProps<{
+ links: TocLink[]
+}>()
+
+const idMap = ref<Record<string, string>>({})
+const activeIds = ref<Set<string>>(new Set())
+const listEl = ref<HTMLElement>()
+const indicatorStyle = ref({ top: '0px', height: '0px', opacity: 0 })
+
+let cleanup: (() => void) | null = null
+let headingEls: HTMLElement[] = []
+let scrollContainer: HTMLElement | null = null
+
+function realId(tocId: string): string {
+ return idMap.value[tocId] || tocId
+}
+
+function isActive(tocId: string): boolean {
+ return activeIds.value.has(realId(tocId))
+}
+
+function discoverHeadings() {
+ if (!scrollContainer) return
+ headingEls = Array.from(scrollContainer.querySelectorAll<HTMLElement>('h2[id], h3[id]'))
+
+ const map: Record<string, string> = {}
+ let idx = 0
+ for (const link of props.links) {
+ if (idx < headingEls.length) map[link.id] = headingEls[idx++]!.id
+ for (const child of link.children || []) {
+ if (idx < headingEls.length) map[child.id] = headingEls[idx++]!.id
+ }
+ }
+ idMap.value = map
+}
+
+function updateActive() {
+ if (!scrollContainer || headingEls.length === 0) return
+ const containerRect = scrollContainer.getBoundingClientRect()
+
+ const visible = new Set<string>()
+
+ for (let i = 0; i < headingEls.length; i++) {
+ const el = headingEls[i]!
+ const nextEl = headingEls[i + 1]
+ const headingTop = el.getBoundingClientRect().top
+ const sectionBottom = nextEl?.getBoundingClientRect().top ?? Infinity
+
+ if (sectionBottom > containerRect.top && headingTop < containerRect.bottom) {
+ visible.add(el.id)
+ }
+ }
+
+ activeIds.value = visible
+ nextTick(updateIndicator)
+}
+
+function updateIndicator() {
+ if (!listEl.value) return
+
+ const buttons = listEl.value.querySelectorAll<HTMLElement>('[data-toc-active="true"]')
+ if (buttons.length === 0) {
+ indicatorStyle.value = { top: '0px', height: '0px', opacity: 0 }
+ return
+ }
+
+ const listRect = listEl.value.getBoundingClientRect()
+ const firstRect = buttons[0]!.getBoundingClientRect()
+ const lastRect = buttons[buttons.length - 1]!.getBoundingClientRect()
+
+ indicatorStyle.value = {
+ top: `${firstRect.top - listRect.top}px`,
+ height: `${lastRect.bottom - firstRect.top}px`,
+ opacity: 1,
+ }
+}
+
+function setup(): boolean {
+ if (cleanup) cleanup()
+
+ const tocTarget = document.getElementById('doc-toc-target')
+ scrollContainer = tocTarget?.previousElementSibling as HTMLElement | null
+ if (!scrollContainer) return false
+
+ discoverHeadings()
+ if (headingEls.length === 0) return false
+
+ updateActive()
+ scrollContainer.addEventListener('scroll', updateActive, { passive: true })
+ cleanup = () => scrollContainer?.removeEventListener('scroll', updateActive)
+ return true
+}
+
+onMounted(() => {
+ if (setup()) return
+
+ let attempts = 0
+ const interval = setInterval(() => {
+ attempts++
+ if (setup() || attempts > 20) clearInterval(interval)
+ }, 100)
+
+ onUnmounted(() => {
+ clearInterval(interval)
+ cleanup?.()
+ })
+})
+
+function scrollTo(id: string) {
+ const el = document.getElementById(id)
+ el?.scrollIntoView({ behavior: 'smooth', block: 'start' })
+}
+</script>
+
+<template>
+ <nav class="text-sm">
+ <p class="text-[10px] text-muted uppercase tracking-wide mb-3 font-pixel">
+ On this page
+ </p>
+
+ <ul ref="listEl" class="space-y-1 border-l border-default relative">
+ <div
+ class="absolute left-0 w-0.5 -ml-px bg-primary rounded-full transition-all duration-200"
+ :style="indicatorStyle"
+ />
+
+ <li v-for="link in links" :key="link.id">
+ <button
+ :data-toc-active="isActive(link.id)"
+ class="block w-full text-left pl-3 py-0.5 transition-colors text-xs"
+ :class="isActive(link.id) ? 'text-highlighted' : 'text-muted hover:text-highlighted'"
+ @click="scrollTo(realId(link.id))"
+ >
+ {{ link.text }}
+ </button>
+
+ <ul v-if="link.children?.length" class="space-y-0.5">
+ <li v-for="child in link.children" :key="child.id">
+ <button
+ :data-toc-active="isActive(child.id)"
+ class="block w-full text-left pl-6 py-0.5 transition-colors text-xs"
+ :class="isActive(child.id) ? 'text-highlighted' : 'text-muted hover:text-highlighted'"
+ @click="scrollTo(realId(child.id))"
+ >
+ {{ child.text }}
+ </button>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </nav>
+</template>
diff --git a/apps/chat/app/components/InstallBotCard.vue b/apps/chat/app/components/InstallBotCard.vue
index 38d28c1..26a1921 100644
--- a/apps/chat/app/components/InstallBotCard.vue
+++ b/apps/chat/app/components/InstallBotCard.vue
@@ -60,7 +60,6 @@ function onMouseLeave() {
@mouseenter="onMouseEnter"
@mouseleave="onMouseLeave"
>
- <!-- Animated border glow -->
<div
class="holo-border-shine"
:style="{
@@ -69,9 +68,7 @@ function onMouseLeave() {
}"
/>
- <!-- Inner card -->
<div class="holo-inner p-3 relative overflow-hidden">
- <!-- Surface shine -->
<div
class="holo-shine"
:style="{
diff --git a/apps/chat/app/composables/useInstallBot.ts b/apps/chat/app/composables/useInstallBot.ts
index 37b67eb..ce2e53d 100644
--- a/apps/chat/app/composables/useInstallBot.ts
+++ b/apps/chat/app/composables/useInstallBot.ts
@@ -12,14 +12,12 @@ export function useInstallBot() {
}
const githubUrl = computed(() => {
- const slug = config.public.github.appSlug
- if (!slug) return null
- return `https://github.com/apps/${slug}/installations/new`
+ const appName = (config.public.github.appName as string)?.replace(/^@/, '')
+ if (!appName) return null
+ return `https://github.com/apps/${appName}/installations/new`
})
- const discordUrl = computed(() => {
- return config.public.discordBotUrl || null
- })
+ const discordUrl = computed(() => config.public.discordBotUrl || null)
const hasAny = computed(() => !!githubUrl.value || !!discordUrl.value)
diff --git a/apps/chat/app/composables/useMarkdownToc.ts b/apps/chat/app/composables/useMarkdownToc.ts
new file mode 100644
index 0000000..b945177
--- /dev/null
+++ b/apps/chat/app/composables/useMarkdownToc.ts
@@ -0,0 +1,31 @@
+interface TocLink {
+ id: string
+ text: string
+ depth: number
+ children?: TocLink[]
+}
+
+export function useMarkdownToc(content: string): TocLink[] {
+ const headingRegex = /^(#{2,3})\s+(.+)$/gm
+ const links: TocLink[] = []
+ let match
+
+ while ((match = headingRegex.exec(content)) !== null) {
+ const depth = match[1].length
+ const text = match[2].trim()
+ const id = text
+ .toLowerCase()
+ .replace(/[^\w\s-]/g, '')
+ .replace(/\s+/g, '-')
+
+ const link: TocLink = { id, depth, text }
+
+ if (depth === 2) {
+ links.push({ ...link, children: [] })
+ } else if (depth === 3 && links.length > 0) {
+ links[links.length - 1].children!.push(link)
+ }
+ }
+
+ return links
+}
diff --git a/apps/chat/app/content/docs/bot-setup.md b/apps/chat/app/content/docs/bot-setup.md
index 63ec456..78675ff 100644
--- a/apps/chat/app/content/docs/bot-setup.md
+++ b/apps/chat/app/content/docs/bot-setup.md
@@ -19,7 +19,8 @@ For the full setup, see [Getting Started > GitHub App Setup](/admin/docs/getting
| Variable | Description |
|----------|-------------|
-| `NUXT_PUBLIC_GITHUB_BOT_TRIGGER` | The mention trigger for the bot (e.g. `@savoir-bot`). This must match the GitHub App name. |
+| `NUXT_PUBLIC_GITHUB_APP_NAME` | The GitHub App name (e.g. `savoir-bot`). Used to build the install URL and as the default bot username. |
+| `NUXT_PUBLIC_GITHUB_BOT_TRIGGER` | Optional override for the bot mention trigger. Defaults to the app name. |
| `NUXT_GITHUB_APP_ID` | The App ID from your [GitHub App settings](https://github.com/settings/apps) |
| `NUXT_GITHUB_APP_PRIVATE_KEY` | The private key (PEM format). Generate one from your app's settings page. Can be base64-encoded. |
| `NUXT_GITHUB_WEBHOOK_SECRET` | The webhook secret you set when creating the app |
@@ -30,6 +31,8 @@ For the full setup, see [Getting Started > GitHub App Setup](/admin/docs/getting
2. Select the repositories where the bot should be active
3. Confirm the installation
+Users can also install the app from the sidebar suggestion card or from the **Settings > Integrations** page.
+
The app uses [installation access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation) to interact with repositories -- no personal access token needed for the bot.
## Trigger the Bot
@@ -48,6 +51,15 @@ The bot will:
The bot only responds when explicitly mentioned. It ignores its own comments to prevent loops.
+## Custom Trigger Name
+
+By default, the bot responds to mentions matching the GitHub App name. If you want a different mention trigger, set `NUXT_PUBLIC_GITHUB_BOT_TRIGGER`:
+
+```bash
+NUXT_PUBLIC_GITHUB_APP_NAME=my-company-bot
+NUXT_PUBLIC_GITHUB_BOT_TRIGGER=ask-ai # Users will @ask-ai instead of @my-company-bot
+```
+
## Auto-Reply to New Issues
You can optionally configure the bot to reply to **all** new issues automatically, without requiring a mention. Set in `nuxt.config.ts`:
diff --git a/apps/chat/app/content/docs/getting-started.md b/apps/chat/app/content/docs/getting-started.md
index 25df887..71e5bfd 100644
--- a/apps/chat/app/content/docs/getting-started.md
+++ b/apps/chat/app/content/docs/getting-started.md
@@ -25,7 +25,7 @@ cp apps/chat/.env.example apps/chat/.env
| Variable | Description |
|----------|-------------|
-| `NUXT_PUBLIC_GITHUB_BOT_TRIGGER` | Bot mention trigger (e.g. `@nuxt-agent`) |
+| `NUXT_PUBLIC_GITHUB_APP_NAME` | GitHub App name (e.g. `savoir-bot`) |
| `NUXT_GITHUB_APP_ID` | GitHub App ID (same app as OAuth, see [GitHub App Setup](#github-app-setup)) |
| `NUXT_GITHUB_APP_PRIVATE_KEY` | GitHub App private key (PEM format) |
| `NUXT_GITHUB_WEBHOOK_SECRET` | Webhook secret for the GitHub App |
diff --git a/apps/chat/app/layouts/default.vue b/apps/chat/app/layouts/default.vue
index f2ab07c..d97f03e 100644
--- a/apps/chat/app/layouts/default.vue
+++ b/apps/chat/app/layouts/default.vue
@@ -369,8 +369,11 @@ defineShortcuts({
<div class="shrink-0 flex items-center justify-end sm:px-4 h-12">
<UColorModeButton />
</div>
- <div ref="adminContentArea" class="flex-1 overflow-y-auto">
- <slot />
+ <div class="flex-1 flex min-h-0">
+ <div ref="adminContentArea" class="flex-1 overflow-y-auto min-w-0">
+ <slot />
+ </div>
+ <div id="doc-toc-target" class="hidden xl:block shrink-0 overflow-y-auto" />
</div>
</template>
<slot v-else />
diff --git a/apps/chat/app/pages/admin/docs/admin-mode.vue b/apps/chat/app/pages/admin/docs/admin-mode.vue
index 1458240..52fd235 100644
--- a/apps/chat/app/pages/admin/docs/admin-mode.vue
+++ b/apps/chat/app/pages/admin/docs/admin-mode.vue
@@ -8,6 +8,8 @@ useSeoMeta({ title: 'Admin Mode - Admin' })
const components = {
pre: PreStream as unknown as DefineComponent,
}
+
+const tocLinks = useMarkdownToc(content)
</script>
<template>
@@ -21,4 +23,10 @@ const components = {
/>
</div>
</div>
+
+ <Teleport to="#doc-toc-target" defer>
+ <div class="w-56 py-8 pl-5 pr-8">
+ <DocToc :links="tocLinks" />
+ </div>
+ </Teleport>
</template>
diff --git a/apps/chat/app/pages/admin/docs/api-keys.vue b/apps/chat/app/pages/admin/docs/api-keys.vue
index f659a47..d049fb3 100644
--- a/apps/chat/app/pages/admin/docs/api-keys.vue
+++ b/apps/chat/app/pages/admin/docs/api-keys.vue
@@ -8,6 +8,8 @@ useSeoMeta({ title: 'API Keys Docs - Admin' })
const components = {
pre: PreStream as unknown as DefineComponent,
}
+
+const tocLinks = useMarkdownToc(content)
</script>
<template>
@@ -21,4 +23,10 @@ const components = {
/>
</div>
</div>
+
+ <Teleport to="#doc-toc-target" defer>
+ <div class="w-56 py-8 pl-5 pr-8">
+ <DocToc :links="tocLinks" />
+ </div>
+ </Teleport>
</template>
diff --git a/apps/chat/app/pages/admin/docs/discord-bot.vue b/apps/chat/app/pages/admin/docs/discord-bot.vue
index 80dfe91..b9d6840 100644
--- a/apps/chat/app/pages/admin/docs/discord-bot.vue
+++ b/apps/chat/app/pages/admin/docs/discord-bot.vue
@@ -8,6 +8,8 @@ useSeoMeta({ title: 'Discord Bot - Admin' })
const components = {
pre: PreStream as unknown as DefineComponent,
}
+
+const tocLinks = useMarkdownToc(content)
</script>
<template>
@@ -21,4 +23,10 @@ const components = {
/>
</div>
</div>
+
+ <Teleport to="#doc-toc-target" defer>
+ <div class="w-56 py-8 pl-5 pr-8">
+ <DocToc :links="tocLinks" />
+ </div>
+ </Teleport>
</template>
diff --git a/apps/chat/app/pages/admin/docs/getting-started.vue b/apps/chat/app/pages/admin/docs/getting-started.vue
index bb63f65..2de3b32 100644
--- a/apps/chat/app/pages/admin/docs/getting-started.vue
+++ b/apps/chat/app/pages/admin/docs/getting-started.vue
@@ -8,6 +8,8 @@ useSeoMeta({ title: 'Getting Started - Admin' })
const components = {
pre: PreStream as unknown as DefineComponent,
}
+
+const tocLinks = useMarkdownToc(content)
</script>
<template>
@@ -21,4 +23,10 @@ const components = {
/>
</div>
</div>
+
+ <Teleport to="#doc-toc-target" defer>
+ <div class="w-56 py-8 pl-5 pr-8">
+ <DocToc :links="tocLinks" />
+ </div>
+ </Teleport>
</template>
diff --git a/apps/chat/app/pages/admin/docs/github-bot.vue b/apps/chat/app/pages/admin/docs/github-bot.vue
index ffb4388..670bc65 100644
--- a/apps/chat/app/pages/admin/docs/github-bot.vue
+++ b/apps/chat/app/pages/admin/docs/github-bot.vue
@@ -8,6 +8,8 @@ useSeoMeta({ title: 'GitHub Bot - Admin' })
const components = {
pre: PreStream as unknown as DefineComponent,
}
+
+const tocLinks = useMarkdownToc(content)
</script>
<template>
@@ -21,4 +23,10 @@ const components = {
/>
</div>
</div>
+
+ <Teleport to="#doc-toc-target" defer>
+ <div class="w-56 py-8 pl-5 pr-8">
+ <DocToc :links="tocLinks" />
+ </div>
+ </Teleport>
</template>
diff --git a/apps/chat/app/pages/admin/docs/sdk.vue b/apps/chat/app/pages/admin/docs/sdk.vue
index c9de237..9aea902 100644
--- a/apps/chat/app/pages/admin/docs/sdk.vue
+++ b/apps/chat/app/pages/admin/docs/sdk.vue
@@ -8,6 +8,8 @@ useSeoMeta({ title: 'SDK - Admin' })
const components = {
pre: PreStream as unknown as DefineComponent,
}
+
+const tocLinks = useMarkdownToc(content)
</script>
<template>
@@ -21,4 +23,10 @@ const components = {
/>
</div>
</div>
+
+ <Teleport to="#doc-toc-target" defer>
+ <div class="w-56 py-8 pl-5 pr-8">
+ <DocToc :links="tocLinks" />
+ </div>
+ </Teleport>
</template>
diff --git a/apps/chat/app/pages/login.vue b/apps/chat/app/pages/login.vue
index 685eb9e..59747f8 100644
--- a/apps/chat/app/pages/login.vue
+++ b/apps/chat/app/pages/login.vue
@@ -79,7 +79,9 @@ function onGitHub() {
<template>
<div class="flex min-h-dvh bg-default">
- <div class="w-full lg:w-1/2 flex items-center justify-center p-8">
+ <div class="w-full lg:w-1/2 flex items-center justify-center p-8 relative">
+ <UColorModeButton class="absolute top-4 right-4" />
+
<div class="w-full max-w-sm">
<div class="text-center mb-8">
<div class="inline-flex items-center justify-center mb-4">
@@ -171,7 +173,7 @@ function onGitHub() {
</div>
</div>
- <div class="hidden lg:block w-1/2 m-2 rounded-lg relative overflow-hidden">
+ <div class="hidden lg:block w-1/2 m-2 rounded-lg border border-muted/50 relative overflow-hidden">
<ClientOnly>
<Shader class="absolute inset-0 size-full">
<Glow :intensity="2.69" :size="27.5" :threshold="0.37">
@@ -200,6 +202,7 @@ function onGitHub() {
</Glow>
</Shader>
</ClientOnly>
+ <div class="absolute inset-0 rounded-lg shadow-[inset_0_4px_30px_rgba(0,0,0,0.5),inset_0_0_80px_rgba(0,0,0,0.35),inset_0_-2px_20px_rgba(0,0,0,0.25)] pointer-events-none" />
</div>
</div>
</template>
diff --git a/apps/chat/nuxt.config.ts b/apps/chat/nuxt.config.ts
index 058b7b7..d3452b7 100644
--- a/apps/chat/nuxt.config.ts
+++ b/apps/chat/nuxt.config.ts
@@ -82,17 +82,21 @@ export default defineNuxtConfig({
blob: true
},
+ ssr: false,
+
routeRules: {
- // Shared chats are read-only, great ISR candidate
- '/shared/**': { isr: { expiration: 300 } },
+ // Login page: SSR for fast first paint
+ '/login': { ssr: true },
+ // Shared chats: SSR + ISR for public access and SEO
+ '/shared/**': { ssr: true, isr: { expiration: 300 } },
// Auth API routes should never be cached
'/api/auth/**': { isr: false, cache: false },
// Chat API responses are user-specific
'/api/chats/**': { isr: false, cache: false },
// Webhook routes should never be cached
'/api/webhooks/**': { isr: false, cache: false },
- // Admin pages are behind auth, skip ISR
- '/admin/**': { isr: false, cache: false, auth: { user: { role: 'admin' } } },
+ // Admin pages are behind auth
+ '/admin/**': { auth: { user: { role: 'admin' } } },
},
runtimeConfig: {
@@ -119,8 +123,8 @@ export default defineNuxtConfig({
public: {
siteUrl: '',
github: {
+ appName: '',
botTrigger: '',
- appSlug: '',
},
discordBotUrl: '',
},
diff --git a/apps/chat/server/utils/bot/index.ts b/apps/chat/server/utils/bot/index.ts
index 4c761f0..71ae6fd 100644
--- a/apps/chat/server/utils/bot/index.ts
+++ b/apps/chat/server/utils/bot/index.ts
@@ -91,16 +91,16 @@ ${error instanceof Error ? error.message : 'Unknown error'}
function createBot(): Chat {
const config = useRuntimeConfig()
- const botTrigger = config.public.github?.botTrigger as string
- if (!botTrigger) {
+ const appName = (config.public.github?.appName as string)?.replace(/^@/, '')
+ if (!appName) {
throw createError({
- message: 'Bot trigger not configured',
- why: 'NUXT_PUBLIC_GITHUB_BOT_TRIGGER is not set',
- fix: 'Set NUXT_PUBLIC_GITHUB_BOT_TRIGGER to the bot mention trigger (e.g. @nuxt-agent)',
+ message: 'GitHub App name not configured',
+ why: 'NUXT_PUBLIC_GITHUB_APP_NAME is not set',
+ fix: 'Set NUXT_PUBLIC_GITHUB_APP_NAME to the GitHub App name (e.g. savoir-bot)',
})
}
- const botUserName = botTrigger.replace('@', '')
+ const botUserName = (config.public.github?.botTrigger as string)?.replace(/^@/, '') || appName
const adapters: Record<string, Adapter> = {}