Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base
update readme and docs
Hugo Richardeddf2580bb98
diff --git a/README.md b/README.mdindex 0aade80..8d442b1 100644--- a/README.md+++ b/README.md@@ -14,7 +14,7 @@</p><p align="center">- <a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fknowledge-agent-template&env=BETTER_AUTH_SECRET,GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET,AI_GATEWAY_API_KEY&envDescription=Required%20environment%20variables.%20See%20docs%2FENVIRONMENT.md%20for%20details.&envLink=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fknowledge-agent-template%2Fblob%2Fmain%2Fdocs%2FENVIRONMENT.md&project-name=knowledge-agent&repository-name=knowledge-agent"><img src="https://vercel.com/button" alt="Deploy with Vercel" /></a>+ <a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fchatsdk-knowledge-agent-template&env=BETTER_AUTH_SECRET,GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET,AI_GATEWAY_API_KEY&envDescription=Required%20environment%20variables.%20See%20docs%2FENVIRONMENT.md%20for%20details.&envLink=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fchatsdk-knowledge-agent-template%2Fblob%2Fmain%2Fdocs%2FENVIRONMENT.md&project-name=knowledge-agent&repository-name=knowledge-agent"><img src="https://vercel.com/button" alt="Deploy with Vercel" /></a></p>---@@ -120,7 +120,7 @@ console.log(text)### Deploy to Vercel-[](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fknowledge-agent-template&env=BETTER_AUTH_SECRET,GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET,AI_GATEWAY_API_KEY&envDescription=Required%20environment%20variables.%20See%20docs%2FENVIRONMENT.md%20for%20details.&envLink=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fknowledge-agent-template%2Fblob%2Fmain%2Fdocs%2FENVIRONMENT.md&project-name=knowledge-agent&repository-name=knowledge-agent)+[](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fchatsdk-knowledge-agent-template&env=BETTER_AUTH_SECRET,GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET,AI_GATEWAY_API_KEY&envDescription=Required%20environment%20variables.%20See%20docs%2FENVIRONMENT.md%20for%20details.&envLink=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fchatsdk-knowledge-agent-template%2Fblob%2Fmain%2Fdocs%2FENVIRONMENT.md&project-name=knowledge-agent&repository-name=knowledge-agent)### Self-hostingdiff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.mdindex 9a76b39..fd088db 100644--- a/docs/ENVIRONMENT.md+++ b/docs/ENVIRONMENT.md@@ -2,107 +2,155 @@> Back to [README](../README.md) | See also: [Architecture](./ARCHITECTURE.md), [Customization](./CUSTOMIZATION.md)-All environment variables for the Knowledge Agent Template project, organized by category.+Copy the example file and fill in the values:++```bash+cp apps/app/.env.example apps/app/.env+```++## Quick Start (minimum required)++| Variable | How to get it |+|----------|---------------|+| `BETTER_AUTH_SECRET` | Run `openssl rand -hex 32` in your terminal |+| `GITHUB_CLIENT_ID` | From your [GitHub App settings](https://github.com/settings/apps) → Client ID |+| `GITHUB_CLIENT_SECRET` | From your [GitHub App settings](https://github.com/settings/apps) → Generate a client secret |+| `AI_GATEWAY_API_KEY` | From the [Vercel AI Gateway dashboard](https://vercel.com/~/ai) → Create Gateway → Copy API key |++These four variables are all you need to run the app locally. Everything else is optional.## Authentication-| Variable | Required | Description |-|----------|----------|-------------|-| `BETTER_AUTH_SECRET` | Yes | Secret used to sign sessions and tokens |-| `GITHUB_CLIENT_ID` | Yes | GitHub OAuth app client ID |-| `GITHUB_CLIENT_SECRET` | Yes | GitHub OAuth app client secret |-| `NUXT_SESSION_PASSWORD` | No | Session encryption password |+### `BETTER_AUTH_SECRET` (required)++Random secret used by [Better Auth](https://www.better-auth.com/docs/installation#set-environment-variables) to sign sessions and tokens. Generate one with:++```bash+openssl rand -hex 32+```++### `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` (required)++GitHub OAuth credentials for user login. You need a **GitHub App** (not an OAuth App) — the same app can also power the GitHub bot later.++1. Go to [**GitHub Settings → Developer settings → GitHub Apps → New GitHub App**](https://github.com/settings/apps/new)+2. Fill in:+ - **App name**: your bot name (e.g. `my-agent`)+ - **Homepage URL**: your instance URL (or `http://localhost:3000` for dev)+ - **Callback URL**: `<your-url>/api/auth/callback/github`+3. Under **Account permissions**, set **Email addresses** → Read-only+4. Create the app, then from the app settings page:+ - Copy the **Client ID** → `GITHUB_CLIENT_ID`+ - Click **Generate a new client secret** → `GITHUB_CLIENT_SECRET`++> See the [Getting Started guide](https://github.com/vercel-labs/chatsdk-knowledge-agent-template/blob/main/apps/app/app/content/docs/getting-started.md#github-app-setup) for the full GitHub App setup with bot permissions.++### `NUXT_SESSION_PASSWORD` (optional)++Session encryption password. Auto-generated if not set.## AI-| Variable | Required | Description |-|----------|----------|-------------|-| `AI_GATEWAY_API_KEY` | Yes | Vercel AI Gateway API key (used by `@ai-sdk/gateway`) |+### `AI_GATEWAY_API_KEY` (required)++API key for [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) (used by `@ai-sdk/gateway` to route to any AI model).++1. Go to the [Vercel AI dashboard](https://vercel.com/~/ai)+2. Create a new Gateway (or use an existing one)+3. Copy the API key → `AI_GATEWAY_API_KEY`## Sandbox & Sync-| Variable | Required | Description |-|----------|----------|-------------|-| `NUXT_GITHUB_TOKEN` | No | Optional fallback override token for snapshot git operations. If omitted, the app uses GitHub App installation tokens by default. |-| `NUXT_GITHUB_SNAPSHOT_REPO` | No | Default snapshot repository in `owner/repo` format. Can be configured later from the admin sandbox UI. |-| `NUXT_GITHUB_SNAPSHOT_BRANCH` | No | Snapshot branch (default: `main`) |+These control how the app syncs knowledge sources into the sandbox. All are optional — you can configure them later from the admin UI.++| Variable | Default | Description |+|----------|---------|-------------|+| `NUXT_GITHUB_SNAPSHOT_REPO` | — | Snapshot repository in `owner/repo` format. Configurable from admin UI. |+| `NUXT_GITHUB_SNAPSHOT_BRANCH` | `main` | Branch to use for snapshots |+| `NUXT_GITHUB_TOKEN` | — | Fallback PAT for git operations. Only needed if GitHub App tokens are unavailable. |++## GitHub Bot (optional)++To enable the GitHub bot that responds to mentions in issues, add these from your [GitHub App settings page](https://github.com/settings/apps):++| Variable | Where to find it |+|----------|-----------------|+| `NUXT_PUBLIC_GITHUB_APP_NAME` | Your GitHub App name (e.g. `my-agent`) |+| `NUXT_PUBLIC_GITHUB_BOT_TRIGGER` | Override mention trigger (defaults to app name) |+| `NUXT_GITHUB_APP_ID` | App settings → **App ID** |+| `NUXT_GITHUB_APP_PRIVATE_KEY` | App settings → **Generate a private key** (PEM format, can be base64-encoded) |+| `NUXT_GITHUB_WEBHOOK_SECRET` | The secret you set when creating the app's webhook |++The webhook URL should be `<your-url>/api/webhooks/github`. Subscribe to **Issues** and **Issue comments** events.-## GitHub Bot+### Required GitHub App permissions for the bot-| Variable | Required | Description |-|----------|----------|-------------|-| `NUXT_PUBLIC_GITHUB_BOT_TRIGGER` | Yes* | Bot mention trigger (e.g. `@your-bot-name`). Required if using the GitHub bot. |-| `NUXT_GITHUB_APP_ID` | Yes* | GitHub App ID |-| `NUXT_GITHUB_APP_PRIVATE_KEY` | Yes* | GitHub App private key (PEM format, can be base64-encoded) |-| `NUXT_GITHUB_WEBHOOK_SECRET` | Yes* | Webhook secret set when creating the GitHub App |+| Permission | Access | Why |+|------------|--------|-----|+| Issues | Read & Write | Read issues and post replies |+| Metadata | Read-only | Required by GitHub for all apps |+| Contents | Read & Write | Push synced content (if using snapshot management) |+| Administration | Read & Write | Auto-create snapshot repos (optional, needs org approval) |-\* Required only if enabling the GitHub bot integration.+## Discord Bot (optional)-## GitHub App Permissions (Recommended)+To add a Discord bot, create an app in the [Discord Developer Portal](https://discord.com/developers/applications):-Use a GitHub App as the primary auth mechanism. Keep PAT usage optional.+| Variable | Where to find it |+|----------|-----------------|+| `NUXT_DISCORD_BOT_TOKEN` | Bot → **Reset Token** → copy |+| `NUXT_DISCORD_PUBLIC_KEY` | General Information → **Public Key** |+| `NUXT_DISCORD_APPLICATION_ID` | General Information → **Application ID** |+| `NUXT_DISCORD_MENTION_ROLE_IDS` | Comma-separated role IDs that can trigger the bot (optional) |-| Capability | Required permissions |-|----------|-----------------------|-| OAuth login + GitHub bot replies | `Issues: Read & Write`, `Metadata: Read-only`, account emails read |-| Snapshot repo sync (push docs/marker) | `Contents: Read & Write`, `Metadata: Read-only` |-| Auto-create snapshot repositories | `Administration: Read & Write` (plus org approval when applicable) |+Set the interactions endpoint URL to `<your-url>/api/webhooks/discord`.-`NUXT_GITHUB_TOKEN` should only be used as a fallback when GitHub App permissions are unavailable or temporarily misconfigured.+## YouTube (optional)-## Discord Bot+### `NUXT_YOUTUBE_API_KEY`-| Variable | Required | Description |-|----------|----------|-------------|-| `NUXT_DISCORD_BOT_TOKEN` | Yes* | Discord bot token |-| `NUXT_DISCORD_PUBLIC_KEY` | Yes* | Discord application public key |-| `NUXT_DISCORD_APPLICATION_ID` | Yes* | Discord application ID |-| `NUXT_DISCORD_MENTION_ROLE_IDS` | No | Comma-separated role IDs that can trigger the bot |+Required only if syncing YouTube sources (video transcripts).-\* Required only if enabling the Discord bot integration.+1. Go to the [Google Cloud Console](https://console.cloud.google.com/apis/credentials)+2. Create a project (or select an existing one)+3. Enable the [YouTube Data API v3](https://console.cloud.google.com/apis/library/youtube.googleapis.com)+4. Go to **Credentials** → **Create Credentials** → **API Key**+5. Copy the key → `NUXT_YOUTUBE_API_KEY`-## YouTube+## Storage (optional)-| Variable | Required | Description |-|----------|----------|-------------|-| `NUXT_YOUTUBE_API_KEY` | Yes* | YouTube Data API key for fetching video transcripts |+### `BLOB_READ_WRITE_TOKEN`-\* Required only if syncing YouTube sources.+[Vercel Blob](https://vercel.com/docs/storage/vercel-blob) token for file uploads. Auto-injected in Vercel deployments.-## Storage+To get one manually: [Vercel Dashboard](https://vercel.com) → your project → **Storage** → **Blob** → **Connect** → copy the token.-| Variable | Required | Description |-|----------|----------|-------------|-| `BLOB_READ_WRITE_TOKEN` | No | Vercel Blob token for file uploads |+## State (optional)-## Optional+### `REDIS_URL`-| Variable | Required | Description |-|----------|----------|-------------|-| `REDIS_URL` | No | Redis URL for bot state persistence. Falls back to in-memory state if not set. |-| `VERCEL_OIDC_TOKEN` | No | Vercel OIDC token (auto-injected in Vercel deployments) |+Redis connection URL for bot state persistence (tracks which threads the bot is subscribed to). Falls back to in-memory state if not set — fine for development, but state is lost on restart.++Any Redis-compatible provider works: [Upstash](https://upstash.com), [Redis Cloud](https://redis.io/cloud), etc.++### `VERCEL_OIDC_TOKEN`++Auto-injected in Vercel deployments. No action needed.## SDK (`@savoir/sdk`)When using the SDK from an external application:-| Variable | Required | Description |-|----------|----------|-------------|-| `SAVOIR_API_URL` | Yes | Base URL of your API |-| `SAVOIR_API_KEY` | No | API key for authentication (Better Auth API key) |+| Variable | Description |+|----------|-------------|+| `SAVOIR_API_URL` | Base URL of your deployed instance (e.g. `https://your-app.vercel.app`) |+| `SAVOIR_API_KEY` | API key generated from the admin panel at `/admin/api-keys` |## Database-Migrations run automatically when the application starts -- no manual `db:migrate` step is needed.+Migrations run automatically when the application starts — no manual step needed.```bash# Generate new migrations after schema changesbun run db:generate```--## Workflows--```bash-# Monitor workflow progress-bun run workflow:web-```