Skip to content

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

make content ready for templating

Hugo Richardbb5a05ddfbcf
diff --git a/.agents/skills/add-bot-adapter.md b/.agents/skills/add-bot-adapter.md
new file mode 100644
index 0000000..7519f9d
--- /dev/null
+++ b/.agents/skills/add-bot-adapter.md
@@ -0,0 +1,83 @@
+# Add Bot Adapter
+
+Guide for adding a new platform adapter (Slack, Linear, etc.) to the Savoir bot system.
+
+## Architecture
+
+The bot system uses the [Vercel Chat SDK](https://github.com/vercel-labs/chat) for platform abstraction. Each adapter implements the Chat SDK interface.
+
+## Reference: Existing Adapters
+
+- **Discord**: Uses `@chat-adapter/discord` (official adapter)
+- **GitHub**: Uses `SavoirGitHubAdapter` (custom, in `apps/chat/server/utils/bot/`)
+
+The GitHub adapter is a good reference for building custom adapters.
+
+## Steps
+
+### 1. Create the Adapter
+
+Create `apps/chat/server/utils/bot/adapters/my-platform.ts`:
+
+```typescript
+import type { Adapter } from 'chat'
+
+export class MyPlatformAdapter implements Adapter {
+ name = 'my-platform'
+
+ // Implement required methods:
+ // - sendMessage(threadId, message)
+ // - editMessage(threadId, messageId, message)
+ // - deleteMessage(threadId, messageId)
+ // etc.
+}
+```
+
+See the Chat SDK documentation for the full `Adapter` interface.
+
+### 2. Register the Adapter
+
+In `apps/chat/server/utils/bot/index.ts`, add your adapter to the Chat instance:
+
+```typescript
+import { MyPlatformAdapter } from './adapters/my-platform'
+
+// Add to the Chat instance
+chat.addAdapter(new MyPlatformAdapter())
+```
+
+### 3. Create the Webhook Endpoint
+
+Create `apps/chat/server/api/webhooks/my-platform.post.ts`:
+
+```typescript
+export default defineEventHandler(async (event) => {
+ const body = await readBody(event)
+
+ // Verify webhook signature (platform-specific)
+ // Parse the incoming event
+ // Forward to the Chat SDK for processing
+
+ return { ok: true }
+})
+```
+
+### 4. Add Environment Variables
+
+Add platform-specific env vars to:
+- `apps/chat/.env.example`
+- `docs/ENVIRONMENT.md`
+- `apps/chat/nuxt.config.ts` (in `runtimeConfig`)
+
+### 5. Add Documentation
+
+Create `apps/chat/app/content/docs/my-platform-bot.md` following the pattern of `discord-bot.md` or `bot-setup.md`.
+
+## Thread ID Format
+
+Follow the convention: `{platform}:{identifier}:{type}:{id}`
+
+Examples:
+- GitHub: `github:owner/repo:issue:123`
+- Discord: `discord:guild:channel:thread`
+- Your platform: `my-platform:{workspace}:{channel}:{thread}`
diff --git a/.agents/skills/add-source.md b/.agents/skills/add-source.md
new file mode 100644
index 0000000..e8ddbcf
--- /dev/null
+++ b/.agents/skills/add-source.md
@@ -0,0 +1,59 @@
+# Add Source
+
+Guide for adding a new knowledge source to the Savoir instance.
+
+## Via Admin UI (recommended)
+
+1. Navigate to `/admin`
+2. Click **Add source**
+3. Fill in the fields:
+
+### GitHub Source
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | Yes | Unique identifier (e.g. `my-docs`) |
+| `label` | Yes | Display name (e.g. `My Docs`) |
+| `repo` | Yes | GitHub repository in `owner/repo` format |
+| `branch` | No | Branch to fetch (default: `main`) |
+| `contentPath` | No | Path to content directory (default: `docs`) |
+| `outputPath` | No | Output directory in snapshot (default: `id`) |
+| `readmeOnly` | No | Only fetch README.md (default: `false`) |
+
+### YouTube Source
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | Yes | Unique identifier |
+| `label` | Yes | Display name |
+| `channelId` | Yes | YouTube channel ID (starts with `UC`) |
+| `handle` | No | YouTube handle (e.g. `@MyChannel`) |
+| `maxVideos` | No | Maximum videos to fetch (default: `50`) |
+
+4. Click **Sync** to pull content into the knowledge base
+
+## Via API
+
+```bash
+# Create a GitHub source
+curl -X POST <your-url>/api/sources \
+ -H "Authorization: Bearer <admin-api-key>" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "id": "my-docs",
+ "type": "github",
+ "label": "My Docs",
+ "repo": "org/docs-repo",
+ "contentPath": "docs"
+ }'
+
+# Trigger sync
+curl -X POST <your-url>/api/sync \
+ -H "Authorization: Bearer <admin-api-key>"
+```
+
+## Notes
+
+- After adding sources, always trigger a **sync** to pull content
+- YouTube sources require `NUXT_YOUTUBE_API_KEY` to be set
+- Sources are stored in SQLite and can be managed from the admin UI at any time
diff --git a/.agents/skills/add-tool.md b/.agents/skills/add-tool.md
new file mode 100644
index 0000000..e5fa712
--- /dev/null
+++ b/.agents/skills/add-tool.md
@@ -0,0 +1,112 @@
+# Add AI Tool
+
+Guide for adding a new AI SDK tool to the `@savoir/agent` package.
+
+## Steps
+
+### 1. Create the Tool
+
+Create `packages/agent/src/tools/my-tool.ts`.
+
+Tools **must use `async function*` (generator)** and yield status updates so the frontend can display loading state and results automatically.
+
+```typescript
+import { tool } from 'ai'
+import { z } from 'zod'
+
+export const myTool = tool({
+ description: 'Clear description of what this tool does — the AI model reads this to decide when to use it',
+ inputSchema: z.object({
+ query: z.string().describe('What the parameter is for'),
+ }),
+ execute: async function* ({ query }) {
+ // 1. Yield loading state — the frontend shows a spinner
+ yield { status: 'loading' as const }
+ const start = Date.now()
+
+ try {
+ // 2. Your tool logic here
+ const result = await doSomething(query)
+
+ // 3. Yield done state with results — the frontend displays the output
+ yield {
+ status: 'done' as const,
+ durationMs: Date.now() - start,
+ text: result,
+ commands: [
+ {
+ title: `My tool: "${query}"`,
+ command: '',
+ stdout: result,
+ stderr: '',
+ exitCode: 0,
+ success: true,
+ },
+ ],
+ }
+ } catch (error) {
+ // 4. Yield error state
+ yield {
+ status: 'done' as const,
+ durationMs: Date.now() - start,
+ text: '',
+ commands: [
+ {
+ title: `My tool: "${query}"`,
+ command: '',
+ stdout: '',
+ stderr: error instanceof Error ? error.message : 'Failed',
+ exitCode: 1,
+ success: false,
+ },
+ ],
+ }
+ }
+ },
+})
+```
+
+### Key Points about Yield
+
+- **`yield { status: 'loading' }`** — Must be yielded first. The frontend uses this to show a loading indicator for the tool call.
+- **`yield { status: 'done', ... }`** — Must be yielded last. Contains the results displayed in the chat UI.
+- The `commands` array format matches the sandbox bash tool output, so the frontend renders it consistently.
+- See `packages/agent/src/tools/web-search.ts` for a complete real-world example.
+
+### 2. Export the Tool
+
+Add the export in `packages/agent/src/index.ts`:
+
+```typescript
+export { myTool } from './tools/my-tool'
+```
+
+### 3. Register in the Agent
+
+In the agent creation (e.g. `apps/chat/server/utils/chat/`), add the tool to the tools object:
+
+```typescript
+import { myTool } from '@savoir/agent'
+
+const tools = {
+ ...savoir.tools,
+ my_tool: myTool,
+}
+```
+
+### 4. Update Prompts (optional)
+
+If the tool needs specific instructions, update the relevant prompt in `packages/agent/src/prompts/`:
+
+```typescript
+// In chat.ts or bot.ts, add to the Available Tools section:
+// - **my_tool**: Description of when and how to use this tool
+```
+
+## Existing Tools
+
+| Tool | File | Description |
+|------|------|-------------|
+| `webSearchTool` | `tools/web-search.ts` | Web search for information not in the sandbox |
+| `bash` | `@savoir/sdk` | Execute bash commands in the sandbox |
+| `bash_batch` | `@savoir/sdk` | Execute multiple bash commands |
diff --git a/.agents/skills/rename-project.md b/.agents/skills/rename-project.md
new file mode 100644
index 0000000..70fabe9
--- /dev/null
+++ b/.agents/skills/rename-project.md
@@ -0,0 +1,107 @@
+# Rename Project
+
+Guide for fully renaming the project from "Savoir" to a custom name.
+
+## Workflow
+
+When the user wants to rename the project:
+
+1. **Ask the user** for the new name (e.g. "MyDocs") and optionally a new package namespace (e.g. `@mydocs`)
+2. **Replace ALL mentions** of "Savoir" across the entire project
+3. **Rename packages** if the user wants a custom namespace
+4. **Run `bun install`** to update the lockfile after package renames
+
+## Complete List of Files to Update
+
+### App Branding (UI-facing)
+
+| File | What to change |
+|------|---------------|
+| `apps/chat/app/app.config.ts` | `name: 'Savoir'` → new name, update `description`, update `icon` |
+| `apps/chat/app/assets/icons/custom/savoir.svg` | Replace with custom icon SVG, rename the file |
+
+### Package Metadata
+
+| File | What to change |
+|------|---------------|
+| `package.json` | `"name"`, `"description": "Monorepo for Savoir"` |
+| `packages/sdk/package.json` | `"name"`, `"description"`, `"repository.url"`, `"homepage"` |
+| `packages/agent/package.json` | `"name"`, `"description"` |
+| `apps/chat/package.json` | `"name"`, dependency references `@savoir/agent`, `@savoir/sdk` |
+
+### Source Code
+
+| File | What to change |
+|------|---------------|
+| `packages/sdk/src/index.ts` | `Savoir` interface name, `createSavoir` function name |
+| `packages/sdk/src/client.ts` | `SavoirClient` class name, error messages mentioning "Savoir" |
+| `packages/sdk/src/types.ts` | `SavoirConfig` type name, JSDoc comments |
+| `packages/agent/src/prompts/chat.ts` | `buildAdminSystemPrompt(appName = 'Savoir')` default value |
+| `apps/chat/server/utils/bot/adapters/github.ts` | `SavoirGitHubAdapter` class name |
+| `apps/chat/server/utils/bot/index.ts` | `SavoirGitHubAdapter` import and usage |
+| `apps/chat/server/utils/sandbox/git.ts` | `email: '[email protected]'`, `name: 'Savoir Bot'` |
+
+After renaming packages, update **all imports** across the codebase:
+
+```bash
+# Find all files importing @savoir/*
+grep -rl "@savoir/sdk" apps/ packages/ --include="*.ts" --include="*.vue"
+grep -rl "@savoir/agent" apps/ packages/ --include="*.ts" --include="*.vue"
+```
+
+Also check `package.json` scripts for `--filter=@savoir/*` references.
+
+### Documentation
+
+| File | What to change |
+|------|---------------|
+| `README.md` | Title, all mentions of "Savoir" |
+| `CONTRIBUTING.md` | Title, all mentions of "Savoir" |
+| `AGENTS.md` | Title |
+| `packages/sdk/README.md` | All mentions of "Savoir", `createSavoir`, `SavoirClient`, etc. |
+| `packages/agent/README.md` | All mentions of "Savoir" |
+| `docs/ARCHITECTURE.md` | All mentions of "Savoir" |
+| `docs/SOURCES.md` | All mentions of "Savoir" |
+| `docs/ENVIRONMENT.md` | All mentions of "Savoir", `SAVOIR_API_URL`, `SAVOIR_API_KEY` |
+| `docs/CUSTOMIZATION.md` | All mentions of "Savoir" |
+
+### In-App Documentation
+
+| File | What to change |
+|------|---------------|
+| `apps/chat/app/content/docs/getting-started.md` | All mentions of "Savoir" |
+| `apps/chat/app/content/docs/sdk.md` | All mentions of "Savoir" |
+| `apps/chat/app/content/docs/bot-setup.md` | "Savoir GitHub bot", "Savoir knowledge base" |
+| `apps/chat/app/content/docs/discord-bot.md` | "Savoir Discord bot" |
+| `apps/chat/app/content/docs/api-keys.md` | "authenticate with Savoir" |
+| `apps/chat/app/content/docs/admin-mode.md` | "Savoir uses" |
+
+### Skills
+
+| File | What to change |
+|------|---------------|
+| `agents/skills/add-source.md` | "Savoir instance" |
+| `agents/skills/add-bot-adapter.md` | "Savoir bot system" |
+
+## Quick Find & Replace
+
+To find all remaining mentions after manual updates:
+
+```bash
+grep -ri "savoir" --include="*.ts" --include="*.vue" --include="*.md" --include="*.json" \
+ --exclude-dir=node_modules --exclude-dir=.output --exclude-dir=dist --exclude-dir=.nuxt
+```
+
+## Checklist
+
+- [ ] `app.config.ts` — name, description, icon
+- [ ] Custom icon SVG
+- [ ] All `package.json` files — name, description, dependencies
+- [ ] All TypeScript source — class names, function names, error messages
+- [ ] All `@savoir/*` imports → new namespace
+- [ ] All documentation files (root `docs/`, `packages/*/README.md`)
+- [ ] All in-app docs (`apps/chat/app/content/docs/`)
+- [ ] All skill files (`agents/skills/`)
+- [ ] Git config (`server/utils/sandbox/git.ts`) — email and bot name
+- [ ] Run `bun install` to update lockfile
+- [ ] Run `bun run build` to verify everything compiles
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..eab71c3
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,75 @@
+# Contributing to Savoir
+
+Thank you for your interest in contributing to Savoir!
+
+## Reporting Bugs
+
+- Search [existing issues](https://github.com/vercel-labs/savoir/issues) before opening a new one
+- Include steps to reproduce, expected behavior, and actual behavior
+- Include your environment (Node version, OS, browser)
+
+## Suggesting Features
+
+- Open a [feature request issue](https://github.com/vercel-labs/savoir/issues/new)
+- Describe the use case and why it would be valuable
+- If possible, outline a proposed implementation
+
+## Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/vercel-labs/savoir.git
+cd savoir
+
+# Install dependencies
+bun install
+
+# Set up environment variables
+cp apps/chat/.env.example apps/chat/.env
+# Edit .env with your configuration
+
+# Start dev server
+bun run dev
+```
+
+## Project Structure
+
+```
+savoir/
+├── apps/chat/ # Nuxt application (chat UI + API + bots)
+├── packages/sdk/ # @savoir/sdk - AI SDK compatible tools
+├── packages/agent/ # @savoir/agent - Agent core (router, prompts, tools)
+└── docs/ # Documentation
+```
+
+## Making Changes
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feat/my-feature`)
+3. Make your changes
+4. Run checks:
+ ```bash
+ bun run lint:fix
+ bun run typecheck
+ bun run build
+ ```
+5. Commit with a descriptive message
+6. Open a pull request
+
+## Code Style
+
+- Follow the existing ESLint configuration (`@hrcd/eslint-config`)
+- See [docs/CODING-GUIDELINES.md](./docs/CODING-GUIDELINES.md) for detailed guidelines
+- Write TypeScript with proper types
+- Keep changes focused and minimal
+
+## Pull Request Process
+
+1. Ensure all checks pass (lint, typecheck, build)
+2. Update documentation if your change affects user-facing behavior
+3. Add a clear description of what changed and why
+4. Request review from maintainers
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](./LICENSE).
diff --git a/LICENSE b/LICENSE
index 40210c8..bbe09ab 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,201 +1,21 @@
- Apache License
- Version 2.0, January 2004
- http://www.apache.org/licenses/
-
- TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
- 1. Definitions.
-
- "License" shall mean the terms and conditions for use, reproduction,
- and distribution as defined by Sections 1 through 9 of this document.
-
- "Licensor" shall mean the copyright owner or entity authorized by
- the copyright owner that is granting the License.
-
- "Legal Entity" shall mean the union of the acting entity and all
- other entities that control, are controlled by, or are under common
- control with that entity. For the purposes of this definition,
- "control" means (i) the power, direct or indirect, to cause the
- direction or management of such entity, whether by contract or
- otherwise, or (ii) ownership of fifty percent (50%) or more of the
- outstanding shares, or (iii) beneficial ownership of such entity.
-
- "You" (or "Your") shall mean an individual or Legal Entity
- exercising permissions granted by this License.
-
- "Source" form shall mean the preferred form for making modifications,
- including but not limited to software source code, documentation
- source, and configuration files.
-
- "Object" form shall mean any form resulting from mechanical
- transformation or translation of a Source form, including but
- not limited to compiled object code, generated documentation,
- and conversions to other media types.
-
- "Work" shall mean the work of authorship, whether in Source or
- Object form, made available under the License, as indicated by a
- copyright notice that is included in or attached to the work
- (an example is provided in the Appendix below).
-
- "Derivative Works" shall mean any work, whether in Source or Object
- form, that is based on (or derived from) the Work and for which the
- editorial revisions, annotations, elaborations, or other modifications
- represent, as a whole, an original work of authorship. For the purposes
- of this License, Derivative Works shall not include works that remain
- separable from, or merely link (or bind by name) to the interfaces of,
- the Work and Derivative Works thereof.
-
- "Contribution" shall mean any work of authorship, including
- the original version of the Work and any modifications or additions
- to that Work or Derivative Works thereof, that is intentionally
- submitted to Licensor for inclusion in the Work by the copyright owner
- or by an individual or Legal Entity authorized to submit on behalf of
- the copyright owner. For the purposes of this definition, "submitted"
- means any form of electronic, verbal, or written communication sent
- to the Licensor or its representatives, including but not limited to
- communication on electronic mailing lists, source code control systems,
- and issue tracking systems that are managed by, or on behalf of, the
- Licensor for the purpose of discussing and improving the Work, but
- excluding communication that is conspicuously marked or otherwise
- designated in writing by the copyright owner as "Not a Contribution."
-
- "Contributor" shall mean Licensor and any individual or Legal Entity
- on behalf of whom a Contribution has been received by Licensor and
- subsequently incorporated within the Work.
-
- 2. Grant of Copyright License. Subject to the terms and conditions of
- this License, each Contributor hereby grants to You a perpetual,
- worldwide, non-exclusive, no-charge, royalty-free, irrevocable
- copyright license to reproduce, prepare Derivative Works of,
- publicly display, publicly perform, sublicense, and distribute the
- Work and such Derivative Works in Source or Object form.
-
- 3. Grant of Patent License. Subject to the terms and conditions of
- this License, each Contributor hereby grants to You a perpetual,
- worldwide, non-exclusive, no-charge, royalty-free, irrevocable
- (except as stated in this section) patent license to make, have made,
- use, offer to sell, sell, import, and otherwise transfer the Work,
- where such license applies only to those patent claims licensable
- by such Contributor that are necessarily infringed by their
- Contribution(s) alone or by combination of their Contribution(s)
- with the Work to which such Contribution(s) was submitted. If You
- institute patent litigation against any entity (including a
- cross-claim or counterclaim in a lawsuit) alleging that the Work
- or a Contribution incorporated within the Work constitutes direct
- or contributory patent infringement, then any patent licenses
- granted to You under this License for that Work shall terminate
- as of the date such litigation is filed.
-
- 4. Redistribution. You may reproduce and distribute copies of the
- Work or Derivative Works thereof in any medium, with or without
- modifications, and in Source or Object form, provided that You
- meet the following conditions:
-
- (a) You must give any other recipients of the Work or
- Derivative Works a copy of this License; and
-
- (b) You must cause any modified files to carry prominent notices
- stating that You changed the files; and
-
- (c) You must retain, in the Source form of any Derivative Works
- that You distribute, all copyright, patent, trademark, and
- attribution notices from the Source form of the Work,
- excluding those notices that do not pertain to any part of
- the Derivative Works; and
-
- (d) If the Work includes a "NOTICE" text file as part of its
- distribution, then any Derivative Works that You distribute must
- include a readable copy of the attribution notices contained
- within such NOTICE file, excluding those notices that do not
- pertain to any part of the Derivative Works, in at least one
- of the following places: within a NOTICE text file distributed
- as part of the Derivative Works; within the Source form or
- documentation, if provided along with the Derivative Works; or,
- within a display generated by the Derivative Works, if and
- wherever such third-party notices normally appear. The contents
- of the NOTICE file are for informational purposes only and
- do not modify the License. You may add Your own attribution
- notices within Derivative Works that You distribute, alongside
- or as an addendum to the NOTICE text from the Work, provided
- that such additional attribution notices cannot be construed
- as modifying the License.
-
- You may add Your own copyright statement to Your modifications and
- may provide additional or different license terms and conditions
- for use, reproduction, or distribution of Your modifications, or
- for any such Derivative Works as a whole, provided Your use,
- reproduction, and distribution of the Work otherwise complies with
- the conditions stated in this License.
-
- 5. Submission of Contributions. Unless You explicitly state otherwise,
- any Contribution intentionally submitted for inclusion in the Work
- by You to the Licensor shall be under the terms and conditions of
- this License, without any additional terms or conditions.
- Notwithstanding the above, nothing herein shall supersede or modify
- the terms of any separate license agreement you may have executed
- with Licensor regarding such Contributions.
-
- 6. Trademarks. This License does not grant permission to use the trade
- names, trademarks, service marks, or product names of the Licensor,
- except as required for reasonable and customary use in describing the
- origin of the Work and reproducing the content of the NOTICE file.
-
- 7. Disclaimer of Warranty. Unless required by applicable law or
- agreed to in writing, Licensor provides the Work (and each
- Contributor provides its Contributions) on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
- implied, including, without limitation, any warranties or conditions
- of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
- PARTICULAR PURPOSE. You are solely responsible for determining the
- appropriateness of using or redistributing the Work and assume any
- risks associated with Your exercise of permissions under this License.
-
- 8. Limitation of Liability. In no event and under no legal theory,
- whether in tort (including negligence), contract, or otherwise,
- unless required by applicable law (such as deliberate and grossly
- negligent acts) or agreed to in writing, shall any Contributor be
- liable to You for damages, including any direct, indirect, special,
- incidental, or consequential damages of any character arising as a
- result of this License or out of the use or inability to use the
- Work (including but not limited to damages for loss of goodwill,
- work stoppage, computer failure or malfunction, or any and all
- other commercial damages or losses), even if such Contributor
- has been advised of the possibility of such damages.
-
- 9. Accepting Warranty or Additional Liability. While redistributing
- the Work or Derivative Works thereof, You may choose to offer,
- and charge a fee for, acceptance of support, warranty, indemnity,
- or other liability obligations and/or rights consistent with this
- License. However, in accepting such obligations, You may act only
- on Your own behalf and on Your sole responsibility, not on behalf
- of any other Contributor, and only if You agree to indemnify,
- defend, and hold each Contributor harmless for any liability
- incurred by, or claims asserted against, such Contributor by reason
- of your accepting any such warranty or additional liability.
-
- END OF TERMS AND CONDITIONS
-
- APPENDIX: How to apply the Apache License to your work.
-
- To apply the Apache License to your work, attach the following
- boilerplate notice, with the fields enclosed by brackets "[]"
- replaced with your own identifying information. (Don't include
- the brackets!) The text should be enclosed in the appropriate
- comment syntax for the file format. We also recommend that a
- file or class name and description of purpose be included on the
- same "printed page" as the copyright notice for easier
- identification within third-party archives.
-
- Copyright 2024-present Hugo Richard
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
+MIT License
+
+Copyright (c) 2026-present Vercel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
index 2438c5d..df36d0a 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,26 @@
-# Savoir
-
-Build AI agents with real-time knowledge access.
+<p align="center">
+ <br>
+ <b>Savoir</b>
+ <br>
+ <i>Build AI agents with real-time knowledge access.</i>
+ <br>
+ <br>
+</p>
+
+<p align="center">
+ <a href="https://github.com/vercel-labs/savoir/actions/workflows/ci.yml"><img src="https://github.com/vercel-labs/savoir/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+ <a href="https://github.com/vercel-labs/savoir/actions/workflows/build.yml"><img src="https://github.com/vercel-labs/savoir/actions/workflows/build.yml/badge.svg" alt="Build"></a>
+ <a href="https://www.npmjs.com/package/@savoir/sdk"><img src="https://img.shields.io/npm/v/@savoir/sdk?color=0284c7&label=@savoir/sdk" alt="npm @savoir/sdk"></a>
+ <a href="https://www.npmjs.com/package/@savoir/agent"><img src="https://img.shields.io/npm/v/@savoir/agent?color=0284c7&label=@savoir/agent" alt="npm @savoir/agent"></a>
+ <a href="./LICENSE"><img src="https://img.shields.io/github/license/vercel-labs/savoir?color=0284c7" alt="License"></a>
+ <a href="https://github.com/vercel-labs/savoir/stargazers"><img src="https://img.shields.io/github/stars/vercel-labs/savoir?style=flat&color=0284c7" alt="GitHub Stars"></a>
+</p>
+
+<p align="center">
+ <b>Template.</b> Fork it, customize it, and deploy your own AI documentation assistant.
+</p>
+
+---
Savoir provides the infrastructure to create file-based AI agents (chatbots, Discord bots, GitHub bots, etc.) that can search and read from frequently updated knowledge bases. It combines a unified [Nuxt](https://nuxt.com) application for the chat interface and API with an SDK that provides [AI SDK](https://ai-sdk.dev)-compatible tools.
@@ -41,6 +61,7 @@ Savoir provides the infrastructure to create file-based AI agents (chatbots, Dis
| Package | Description |
|---------|-------------|
| [`@savoir/sdk`](./packages/sdk) | [AI SDK](https://ai-sdk.dev) compatible tools for agents |
+| [`@savoir/agent`](./packages/agent) | Agent core: router, prompts, tools, types |
| [`apps/chat`](./apps/chat) | Unified [Nuxt](https://nuxt.com) app (chat UI + API + bots) |
## Quick Start
@@ -60,7 +81,7 @@ const { text } = await generateText({
model: yourModel, // any AI SDK compatible model
tools: savoir.tools, // bash and bash_batch tools
maxSteps: 10,
- prompt: 'How do I configure authentication in Nuxt?',
+ prompt: 'How do I configure authentication?',
})
console.log(text)
@@ -108,6 +129,18 @@ NUXT_PUBLIC_SITE_URL=https://... # Public URL of your instance
See [ENVIRONMENT.md](./docs/ENVIRONMENT.md) for the full list of environment variables.
+## Customization
+
+Savoir is designed as a **reusable template**. See the [Customization Guide](./docs/CUSTOMIZATION.md) for how to:
+
+- Rename your instance (name, icon, description)
+- Add documentation sources (GitHub repos, YouTube channels)
+- Add custom AI tools
+- Add bot adapters (Slack, Linear, etc.)
+- Customize AI prompts
+- Theme the UI
+- Deploy to production
+
## Configuration
Sources are managed through the **admin interface** at `/admin`. You can add GitHub repositories and YouTube channels as knowledge sources, then trigger a sync from the UI.
@@ -163,6 +196,10 @@ bun run lint:fix
- [Drizzle ORM](https://orm.drizzle.team) - Type-safe database queries
- [Vercel Chat SDK](https://github.com/vercel-labs/chat) - Bot framework for GitHub and Discord
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved.
+
## License
[MIT](./LICENSE)
diff --git a/apps/chat/app/app.config.ts b/apps/chat/app/app.config.ts
index a591621..13edca0 100644
--- a/apps/chat/app/app.config.ts
+++ b/apps/chat/app/app.config.ts
@@ -1,4 +1,9 @@
export default defineAppConfig({
+ app: {
+ name: 'Savoir',
+ description: 'Your intelligent AI assistant for knowledge and insights.',
+ icon: 'i-custom-savoir',
+ },
ui: {
colors: {
primary: 'primary',
diff --git a/apps/chat/app/app.vue b/apps/chat/app/app.vue
index 12611d1..79d422b 100644
--- a/apps/chat/app/app.vue
+++ b/apps/chat/app/app.vue
@@ -1,6 +1,7 @@
<script setup lang="ts">
import { Analytics } from '@vercel/analytics/nuxt'
+const appConfig = useAppConfig()
const colorMode = useColorMode()
const color = computed(() => colorMode.value === 'dark' ? '#1b1718' : 'white')
@@ -11,28 +12,26 @@ useHead({
meta: [
{ charset: 'utf-8' },
{ name: 'viewport', content: 'width=device-width, initial-scale=1' },
- { key: 'theme-color', name: 'theme-color', content: color }
+ { key: 'theme-color', name: 'theme-color', content: color },
],
link: [{ rel: 'icon', href: '/favicon.ico' }],
htmlAttrs: {
- lang: 'en'
- }
+ lang: 'en',
+ },
})
-const description = 'Your intelligent AI assistant for knowledge and insights.'
-
useHead({
- titleTemplate: '%s - Savoir'
+ titleTemplate: `%s - ${appConfig.app.name}`,
})
useSeoMeta({
- title: 'Savoir',
- description,
- ogTitle: 'Savoir',
- ogDescription: description,
+ title: appConfig.app.name,
+ description: appConfig.app.description,
+ ogTitle: appConfig.app.name,
+ ogDescription: appConfig.app.description,
ogImage: '/og-image.png',
twitterImage: '/og-image.png',
- twitterCard: 'summary_large_image'
+ twitterCard: 'summary_large_image',
})
</script>
@@ -44,6 +43,7 @@ useSeoMeta({
<NuxtPage />
</NuxtLayout>
- <Analytics />
+ <!-- To enable Vercel Analytics, uncomment: -->
+ <!-- <Analytics /> -->
</UApp>
</template>
diff --git a/apps/chat/app/content/docs/bot-setup.md b/apps/chat/app/content/docs/bot-setup.md
index e47bc5f..06527b7 100644
--- a/apps/chat/app/content/docs/bot-setup.md
+++ b/apps/chat/app/content/docs/bot-setup.md
@@ -21,7 +21,7 @@ For the full setup, see [Getting Started > GitHub App Setup](/admin/docs/getting
| Variable | Description |
|----------|-------------|
-| `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_APP_NAME` | The GitHub App name (e.g. `your-bot-name`). 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. |
@@ -42,7 +42,7 @@ The app uses [installation access tokens](https://docs.github.com/en/apps/creati
Mention the bot in any issue comment:
```
-@savoir-bot How do I configure SSO?
+@your-bot-name How do I configure SSO?
```
The bot will:
@@ -58,8 +58,8 @@ The bot only responds when explicitly mentioned. It ignores its own comments to
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
+NUXT_PUBLIC_GITHUB_APP_NAME=your-bot-name
+NUXT_PUBLIC_GITHUB_BOT_TRIGGER=ask-ai # Users will @ask-ai instead of @your-bot-name
```
## Auto-Reply to New Issues
diff --git a/apps/chat/app/content/docs/discord-bot.md b/apps/chat/app/content/docs/discord-bot.md
index d8fe7ab..4ae8b13 100644
--- a/apps/chat/app/content/docs/discord-bot.md
+++ b/apps/chat/app/content/docs/discord-bot.md
@@ -49,7 +49,7 @@ The Discord bot is built on the [Vercel Chat SDK](https://github.com/vercel-labs
Mention the bot in any channel:
```
-@savoir-bot How do I use useAsyncData?
+@your-bot How do I configure authentication?
```
The bot will reply in the same channel with an answer from the knowledge base, using the same AI agent pipeline as the [chat interface](/admin/docs/getting-started#how-it-works) and [GitHub bot](/admin/docs/github-bot).
diff --git a/apps/chat/app/content/docs/getting-started.md b/apps/chat/app/content/docs/getting-started.md
index bcc4595..00c0b1c 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_APP_NAME` | GitHub App name (e.g. `savoir-bot`) |
+| `NUXT_PUBLIC_GITHUB_APP_NAME` | GitHub App name (e.g. `your-bot-name`) |
| `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 |
@@ -40,7 +40,7 @@ Savoir uses a single **GitHub App** for both **user authentication** (OAuth logi
1. Go to [**GitHub Settings > Developer settings > GitHub Apps > New GitHub App**](https://github.com/settings/apps/new)
2. Fill in the basic information:
- - **App name**: e.g. `savoir-bot`
+ - **App name**: e.g. `your-bot-name`
- **Homepage URL**: your Savoir instance URL
- **Callback URL**: `<your-url>/api/auth/callback/github` (for OAuth login)
- **Webhook URL**: `<your-url>/api/webhooks/github` (for the bot)
@@ -124,7 +124,7 @@ The app will be available at `http://localhost:3000`. Sign in with GitHub using
## Adding Sources
-Sources define the knowledge base that Savoir uses to answer questions. They are managed through the **admin interface**.
+Sources define the knowledge base the app uses to answer questions. They are managed through the **admin interface**.
1. Navigate to the admin panel at `/admin`
2. Go to the Sources section
diff --git a/apps/chat/app/content/docs/sdk.md b/apps/chat/app/content/docs/sdk.md
index 7772ac5..744bfec 100644
--- a/apps/chat/app/content/docs/sdk.md
+++ b/apps/chat/app/content/docs/sdk.md
@@ -81,13 +81,13 @@ The `savoir.client` property exposes the low-level `SavoirClient` for direct API
```typescript
// Execute bash command
-const result = await savoir.client.bash('grep -rl "useAsyncData" docs/')
+const result = await savoir.client.bash('grep -rl "authentication" docs/')
console.log(result.stdout)
// Execute multiple commands
const batchResult = await savoir.client.bashBatch([
'find docs/ -name "*.md" | head -10',
- 'cat docs/nuxt/getting-started/installation.md',
+ 'cat docs/my-framework/getting-started/installation.md',
])
// List all indexed sources
@@ -111,7 +111,7 @@ const result = await generateText({
model: yourModel,
tools: savoir.tools,
maxSteps: 10,
- prompt: 'How do I use Nuxt middleware?',
+ prompt: 'How do I configure middleware?',
})
// reportUsage accepts any AI SDK generate result
diff --git a/apps/chat/app/pages/login.vue b/apps/chat/app/pages/login.vue
index 59747f8..5425d8c 100644
--- a/apps/chat/app/pages/login.vue
+++ b/apps/chat/app/pages/login.vue
@@ -2,6 +2,8 @@
import { z } from 'zod'
import { Circle, DotGrid, Glow, Godrays, ProgressiveBlur, Saturation, Shader, SolidColor } from 'shaders/vue'
+const appConfig = useAppConfig()
+
definePageMeta({ layout: false, auth: 'guest' })
useSeoMeta({ title: 'Sign in' })
@@ -85,13 +87,13 @@ function onGitHub() {
<div class="w-full max-w-sm">
<div class="text-center mb-8">
<div class="inline-flex items-center justify-center mb-4">
- <UIcon name="i-custom-savoir" class="size-10 text-primary" />
+ <UIcon :name="appConfig.app.icon" class="size-10 text-primary" />
</div>
<h1 class="text-2xl font-semibold text-highlighted">
{{ mode === 'signin' ? 'Welcome back' : 'Create your account' }}
</h1>
<p class="mt-1.5 text-sm text-muted">
- {{ mode === 'signin' ? 'Sign in to your Savoir account.' : 'Get started with Savoir.' }}
+ {{ mode === 'signin' ? `Sign in to your ${appConfig.app.name} account.` : `Get started with ${appConfig.app.name}.` }}
</p>
</div>
diff --git a/apps/chat/app/pages/settings/api-keys.vue b/apps/chat/app/pages/settings/api-keys.vue
index 55bc7a4..f757141 100644
--- a/apps/chat/app/pages/settings/api-keys.vue
+++ b/apps/chat/app/pages/settings/api-keys.vue
@@ -75,7 +75,7 @@ function copyKey(key: string) {
</h1>
</div>
<p class="text-sm text-muted max-w-lg">
- Create personal API keys to authenticate with the Savoir SDK.
+ Create personal API keys to authenticate with the SDK.
</p>
</header>
diff --git a/apps/chat/app/pages/shared/[token].vue b/apps/chat/app/pages/shared/[token].vue
index 450467f..69cd60d 100644
--- a/apps/chat/app/pages/shared/[token].vue
+++ b/apps/chat/app/pages/shared/[token].vue
@@ -2,6 +2,8 @@
import type { DefineComponent } from 'vue'
import ProseStreamPre from '../../components/prose/PreStream.vue'
+const appConfig = useAppConfig()
+
const components = {
pre: ProseStreamPre as unknown as DefineComponent
}
@@ -81,8 +83,8 @@ onMounted(() => {
<header class="shrink-0 z-20 bg-default border-b border-default">
<div class="max-w-5xl mx-auto flex items-center justify-between px-4 h-12">
<NuxtLink to="/" class="flex items-center gap-2">
- <UIcon name="i-custom-savoir" class="size-6 text-primary" />
- <span class="text-lg font-bold font-pixel tracking-wide text-highlighted">Savoir</span>
+ <UIcon :name="appConfig.app.icon" class="size-6 text-primary" />
+ <span class="text-lg font-bold font-pixel tracking-wide text-highlighted">{{ appConfig.app.name }}</span>
</NuxtLink>
<div v-if="data?.title" class="hidden sm:flex items-center gap-2 text-sm text-muted truncate max-w-sm">
diff --git a/apps/chat/package.json b/apps/chat/package.json
index 8bda9c4..d83a2b6 100644
--- a/apps/chat/package.json
+++ b/apps/chat/package.json
@@ -1,6 +1,7 @@
{
"name": "@savoir/chat",
"private": true,
+ "license": "MIT",
"type": "module",
"scripts": {
"build": "nuxt build",
diff --git a/apps/chat/server/api/sources/ocr.post.ts b/apps/chat/server/api/sources/ocr.post.ts
index 03fa3f1..86b2920 100644
--- a/apps/chat/server/api/sources/ocr.post.ts
+++ b/apps/chat/server/api/sources/ocr.post.ts
@@ -1,7 +1,7 @@
import { generateText, Output } from 'ai'
import { z } from 'zod'
-import type { SourceOcrItem } from '~~/shared/utils/source-ocr'
-import { IMAGE_OPTIMIZATION_CONFIG } from '~~/shared/utils/file'
+import type { SourceOcrItem } from '#shared/utils/source-ocr'
+import { IMAGE_OPTIMIZATION_CONFIG } from '#shared/utils/file'
import { optimizeImage } from '~~/server/utils/image/optimize'
const bodySchema = z.object({
diff --git a/apps/chat/server/api/upload/[chatId].put.ts b/apps/chat/server/api/upload/[chatId].put.ts
index 3d6a029..256ac45 100644
--- a/apps/chat/server/api/upload/[chatId].put.ts
+++ b/apps/chat/server/api/upload/[chatId].put.ts
@@ -2,7 +2,7 @@ import { blob } from 'hub:blob'
import { db, schema } from '@nuxthub/db'
import { eq } from 'drizzle-orm'
import { z } from 'zod'
-import { IMAGE_OPTIMIZATION_CONFIG } from '~~/shared/utils/file'
+import { IMAGE_OPTIMIZATION_CONFIG } from '#shared/utils/file'
import { isOptimizableImage, optimizeImage } from '~~/server/utils/image/optimize'
interface FileData {
diff --git a/apps/chat/server/utils/chat/admin-tools/index.ts b/apps/chat/server/utils/chat/admin-tools/index.ts
index 35527a3..d54b656 100644
--- a/apps/chat/server/utils/chat/admin-tools/index.ts
+++ b/apps/chat/server/utils/chat/admin-tools/index.ts
@@ -7,7 +7,7 @@ import { getAgentConfigTool } from './get-agent-config'
import { queryLogsTool } from './query-logs'
import { logStatsTool } from './log-stats'
import { queryErrorsTool } from './query-errors'
-import { chartTool } from '~~/shared/utils/tools/chart'
+import { chartTool } from '#shared/utils/tools/chart'
export const adminTools = {
query_stats: queryStatsTool,
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index e75d796..9a7ee15 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -368,13 +368,13 @@ Used for file uploads (images, PDFs, CSVs attached to chats).
```
{GITHUB_SNAPSHOT_REPO}/
├── docs/
-│ ├── nuxt/
+│ ├── my-framework/
│ │ ├── getting-started/
│ │ └── composables/
-│ ├── nitro/
+│ ├── my-library/
│ └── ...
└── youtube/
- └── alex-lichter/
+ └── my-channel/
```
## Environment Variables
diff --git a/docs/CUSTOMIZATION.md b/docs/CUSTOMIZATION.md
new file mode 100644
index 0000000..fe125d3
--- /dev/null
+++ b/docs/CUSTOMIZATION.md
@@ -0,0 +1,149 @@
+# Customization Guide
+
+Savoir is designed as a reusable template. This guide covers how to customize your instance.
+
+## 1. Rename Your Instance
+
+Edit `apps/chat/app/app.config.ts` to change the branding:
+
+```typescript
+export default defineAppConfig({
+ app: {
+ name: 'My Assistant',
+ description: 'AI assistant for my documentation.',
+ icon: 'i-custom-savoir', // Replace with your own icon
+ },
+ // ...
+})
+```
+
+To use a custom icon:
+1. Replace `apps/chat/app/assets/icons/custom/savoir.svg` with your own SVG
+2. Update the `icon` value in `app.config.ts` to match (e.g. `i-custom-my-icon` for `my-icon.svg`)
+
+The name and description are used throughout the UI (login page, shared chats, SEO meta tags).
+
+## 2. Add Sources
+
+Sources define your knowledge base. Manage them through the **Admin UI**:
+
+1. Navigate to `/admin`
+2. Click **Add source**
+3. Configure a GitHub repository or YouTube channel
+4. Click **Sync** to pull content
+
+See [SOURCES.md](./SOURCES.md) for all source options.
+
+## 3. Add Custom AI Tools
+
+Tools are defined in `packages/agent/src/tools/`. Tools **must use generator functions** (`async function*`) and yield status updates so the frontend can display loading state and results automatically.
+
+1. Create a new file, e.g. `packages/agent/src/tools/my-tool.ts`:
+
+```typescript
+import { tool } from 'ai'
+import { z } from 'zod'
+
+export const myTool = tool({
+ description: 'Description of what this tool does',
+ inputSchema: z.object({
+ query: z.string().describe('The input query'),
+ }),
+ execute: async function* ({ query }) {
+ // Yield loading — frontend shows a spinner
+ yield { status: 'loading' as const }
+ const start = Date.now()
+
+ try {
+ const result = await doSomething(query)
+
+ // Yield done — frontend displays the output
+ yield {
+ status: 'done' as const,
+ durationMs: Date.now() - start,
+ text: result,
+ commands: [{
+ title: `My tool: "${query}"`,
+ command: '',
+ stdout: result,
+ stderr: '',
+ exitCode: 0,
+ success: true,
+ }],
+ }
+ } catch (error) {
+ yield {
+ status: 'done' as const,
+ durationMs: Date.now() - start,
+ text: '',
+ commands: [{
+ title: `My tool: "${query}"`,
+ command: '',
+ stdout: '',
+ stderr: error instanceof Error ? error.message : 'Failed',
+ exitCode: 1,
+ success: false,
+ }],
+ }
+ }
+ },
+})
+```
+
+2. Export it from `packages/agent/src/index.ts`
+3. Register it in the agent creation (e.g. in `apps/chat/server/utils/chat/`)
+
+See `packages/agent/src/tools/web-search.ts` for a complete real-world example. Tools are compatible with the [Vercel AI SDK tool format](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling).
+
+## 4. Add a Bot Adapter
+
+Bot adapters connect Savoir to messaging platforms. The project includes GitHub and Discord adapters. To add a new one (e.g. Slack, Linear):
+
+1. Look at `apps/chat/server/utils/bot/` for the existing adapter pattern
+2. The GitHub adapter (`SavoirGitHubAdapter`) is a good reference for custom adapters
+3. Create your adapter implementing the [Chat SDK](https://github.com/vercel-labs/chat) adapter interface
+4. Register the webhook endpoint in `apps/chat/server/api/webhooks/`
+5. Add the adapter to the bot instance in `apps/chat/server/utils/bot/`
+
+## 5. Customize AI Prompts
+
+Prompts are in `packages/agent/src/prompts/`:
+
+| File | Purpose |
+|------|---------|
+| `router.ts` | Question complexity classification |
+| `chat.ts` | Chat interface system prompt + admin prompt |
+| `bot.ts` | Bot system prompt (GitHub, Discord) |
+| `shared.ts` | Shared utilities (style, complexity hints) |
+
+You can also customize the agent behavior through the admin UI at `/admin/agent` without touching code — this includes response style, language, temperature, citation format, and additional instructions.
+
+## 6. Customize the UI Theme
+
+Edit `apps/chat/app/app.config.ts` to change colors:
+
+```typescript
+export default defineAppConfig({
+ // ...
+ ui: {
+ colors: {
+ primary: 'blue', // Any Tailwind color
+ neutral: 'slate',
+ },
+ // Override component slots as needed
+ }
+})
+```
+
+See the [Nuxt UI documentation](https://ui.nuxt.com) for all theming options.
+
+## 7. Deploy
+
+This project is designed to be deployed on [Vercel](https://vercel.com):
+
+1. Connect your repository to Vercel
+2. Set all required environment variables (see [ENVIRONMENT.md](./ENVIRONMENT.md))
+3. Deploy
+
+Vercel provides the full feature set: [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) for code execution, [Vercel Workflow](https://useworkflow.dev) for content sync, and serverless functions for bot webhooks.
+
diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.md
index 60e896d..376ca63 100644
--- a/docs/ENVIRONMENT.md
+++ b/docs/ENVIRONMENT.md
@@ -36,7 +36,7 @@ All environment variables for the Savoir project, organized by category.
| Variable | Required | Description |
|----------|----------|-------------|
-| `NUXT_PUBLIC_GITHUB_BOT_TRIGGER` | Yes* | Bot mention trigger (e.g. `@nuxt-agent`). Required if using the GitHub bot. |
+| `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 |
diff --git a/docs/SOURCES.md b/docs/SOURCES.md
index 12f7de8..0ea8e32 100644
--- a/docs/SOURCES.md
+++ b/docs/SOURCES.md
@@ -84,7 +84,7 @@ Content syncing is triggered from the **admin interface**. You can also trigger
await savoir.client.sync()
// Sync a specific source
-await savoir.client.syncSource('nuxt')
+await savoir.client.syncSource('my-docs')
```
### How Sync Works
@@ -129,13 +129,13 @@ The snapshot repository contains all aggregated content:
```
{NUXT_GITHUB_SNAPSHOT_REPO}/
├── docs/
-│ ├── nuxt/
+│ ├── my-framework/
│ │ ├── getting-started/
-│ │ └── composables/
-│ ├── nitro/
+│ │ └── api/
+│ ├── my-library/
│ └── ...
└── youtube/
- └── alex-lichter/
+ └── my-channel/
```
Configure via environment variable:
diff --git a/package.json b/package.json
index 2f06cc0..5572333 100644
--- a/package.json
+++ b/package.json
@@ -2,6 +2,7 @@
"name": "@savoir/monorepo",
"private": true,
"type": "module",
+ "license": "MIT",
"description": "Monorepo for Savoir",
"author": "HugoRCD",
"repository": {
diff --git a/packages/agent/README.md b/packages/agent/README.md
new file mode 100644
index 0000000..012db94
--- /dev/null
+++ b/packages/agent/README.md
@@ -0,0 +1,80 @@
+# @savoir/agent
+
+Framework-agnostic agent core for Savoir. Handles question routing, prompt management, agent creation, and AI tool definitions.
+
+## Overview
+
+This package provides the AI agent infrastructure used by Savoir's chat interface and bots. It is designed to be consumed by `apps/chat` but can also be used independently.
+
+## Components
+
+### Router
+
+The router classifies incoming questions by complexity and selects the appropriate model and step count.
+
+| Complexity | Max Steps | Model |
+|-----------|-----------|-------|
+| trivial | 4 | gemini-3-flash |
+| simple | 8 | gemini-3-flash |
+| moderate | 15 | claude-sonnet-4.6 |
+| complex | 25 | claude-opus-4.6 |
+
+```typescript
+import { routeQuestion } from '@savoir/agent'
+
+const config = await routeQuestion(question)
+// { complexity: 'moderate', maxSteps: 15, model: 'claude-sonnet-4.6', reasoning: '...' }
+```
+
+### Prompts
+
+System prompts for different contexts:
+
+| File | Function | Purpose |
+|------|----------|---------|
+| `router.ts` | `ROUTER_SYSTEM_PROMPT` | Question classification |
+| `chat.ts` | `buildChatSystemPrompt()` | Chat interface |
+| `chat.ts` | `buildAdminSystemPrompt()` | Admin assistant |
+| `bot.ts` | `buildBotSystemPrompt()` | Bot responses |
+| `shared.ts` | `applyAgentConfig()` | Config overlay (style, language, citations) |
+
+### Agents
+
+Pre-configured agent factories:
+
+- **`createAgent()`** — Base agent for chat and bot responses
+- **`createAdminAgent()`** — Admin assistant with stats/management tools
+- **`createSourceAgent()`** — Source-specific agent
+
+### Tools
+
+- **`webSearchTool`** — Web search tool for finding information not in the sandbox
+
+### Types
+
+Key types exported:
+
+```typescript
+import type {
+ AgentConfigData,
+ ThreadContext,
+ RoutingResult,
+ AgentExecutionContext,
+ CreateAgentOptions,
+ AgentCallOptions,
+ AgentConfig,
+} from '@savoir/agent'
+```
+
+## Customization
+
+To customize AI behavior:
+
+1. **Admin UI** — Change response style, language, temperature, etc. at `/admin/agent`
+2. **Prompts** — Edit files in `src/prompts/` for deeper customization
+3. **Router** — Modify `src/prompts/router.ts` to adjust complexity classification
+4. **Tools** — Add new tools in `src/tools/`
+
+## License
+
+MIT
diff --git a/packages/agent/package.json b/packages/agent/package.json
index c6a7611..37cd8be 100644
--- a/packages/agent/package.json
+++ b/packages/agent/package.json
@@ -1,6 +1,7 @@
{
"name": "@savoir/agent",
"version": "0.1.0",
+ "license": "MIT",
"description": "Framework-agnostic agent core for Savoir",
"type": "module",
"exports": {
diff --git a/packages/agent/src/index.ts b/packages/agent/src/index.ts
index 9f44c5b..e4438b4 100644
--- a/packages/agent/src/index.ts
+++ b/packages/agent/src/index.ts
@@ -20,6 +20,7 @@ export {
// Prompts
export { ROUTER_SYSTEM_PROMPT } from './prompts/router'
export { buildBotSystemPrompt, buildBotUserMessage } from './prompts/bot'
+export { buildAdminSystemPrompt, ADMIN_SYSTEM_PROMPT, buildChatSystemPrompt } from './prompts/chat'
// Types
export type {
diff --git a/packages/agent/src/prompts/bot.ts b/packages/agent/src/prompts/bot.ts
index 2ddb1e5..01a6988 100644
--- a/packages/agent/src/prompts/bot.ts
+++ b/packages/agent/src/prompts/bot.ts
@@ -67,8 +67,8 @@ You have access to a \`search_web\` tool for finding information NOT in the sand
## Response Style
- Be concise and helpful
-- **Contextualize your answer to the user's question.** If they ask about a feature "in Nuxt", show the Nuxt config (e.g. \`nuxt.config.ts\`) not the underlying library's config. Adapt code examples to the framework they're asking about.
-- When a topic spans multiple sources (e.g. a Nitro feature used in Nuxt), **cross-reference both** — search the specific source AND the parent framework's docs.
+- **Contextualize your answer to the user's question.** If they ask about a feature in a specific framework, show that framework's config — not the underlying library's config. Adapt code examples to the framework they're asking about.
+- When a topic spans multiple sources, **cross-reference both** — search the specific source AND related docs.
- Include code examples from the documentation
- Try to give a direct answer`
diff --git a/packages/agent/src/prompts/chat.ts b/packages/agent/src/prompts/chat.ts
index f1bf589..b40b3e4 100644
--- a/packages/agent/src/prompts/chat.ts
+++ b/packages/agent/src/prompts/chat.ts
@@ -1,7 +1,8 @@
import type { AgentConfigData } from '../types'
import { applyAgentConfig, applyTemporalContext } from './shared'
-export const ADMIN_SYSTEM_PROMPT = `You are an admin assistant for the Savoir application. You help administrators understand app usage, monitor performance, manage users, and debug issues.
+export function buildAdminSystemPrompt(appName = 'Savoir'): string {
+ return `You are an admin assistant for the ${appName} application. You help administrators understand app usage, monitor performance, manage users, and debug issues.
## Available Tools
@@ -39,6 +40,9 @@ You have access to admin tools that query the application's internal data:
- Use markdown formatting for readability.
- Be concise but thorough in your analysis.
`
+}
+
+export const ADMIN_SYSTEM_PROMPT = buildAdminSystemPrompt()
export const BASE_SYSTEM_PROMPT = `You are an AI assistant that answers questions using documentation available in a sandbox.
{{TEMPORAL_CONTEXT}}
@@ -118,8 +122,8 @@ You have access to a \`search_web\` tool for finding information NOT in the sand
## Response Style
- Be concise and helpful
-- **Contextualize your answer to the user's question.** If they ask about a feature "in Nuxt", show the Nuxt config (e.g. \`nuxt.config.ts\`) not the underlying library's config. Adapt code examples to the framework they're asking about.
-- When a topic spans multiple sources (e.g. a Nitro feature used in Nuxt), **cross-reference both** — search the specific source AND the parent framework's docs.
+- **Contextualize your answer to the user's question.** If they ask about a feature in a specific framework, show that framework's config — not the underlying library's config. Adapt code examples to the framework they're asking about.
+- When a topic spans multiple sources, **cross-reference both** — search the specific source AND related docs.
- Include relevant code examples when available
- Use markdown formatting
- Cite the source file path
diff --git a/packages/agent/src/prompts/router.ts b/packages/agent/src/prompts/router.ts
index 0b775cc..4f2f898 100644
--- a/packages/agent/src/prompts/router.ts
+++ b/packages/agent/src/prompts/router.ts
@@ -11,17 +11,17 @@ Analyze the user's question and determine the appropriate configuration for the
**simple** (maxSteps: 8, model: gemini-3-flash)
- Single concept lookups: "What is X?", "How to use Y?"
- Direct questions with likely one clear answer in one file
-- Examples: "What is useAsyncData?", "How to install Nuxt?", "What does definePageMeta do?"
+- Examples: "What is X?", "How do I install Y?", "What does Z do?"
**moderate** (maxSteps: 15, model: claude-sonnet-4.6)
- Comparisons or multi-concept questions requiring 2–5 file reads
- Integration questions requiring exploration of multiple sources
-- Examples: "Difference between useFetch and useAsyncData?", "How to use Nuxt Content with Nuxt UI?", "How to set up authentication?"
+- Examples: "Difference between X and Y?", "How to use X with Y?", "How to set up authentication?"
**complex** (maxSteps: 25, model: claude-opus-4.6)
- Debugging scenarios describing errors or unexpected behavior
- Architecture questions spanning multiple systems
- Deep analysis requiring cross-referencing many files
-- Examples: "My SSR hydration is failing with this error...", "How to build a multi-tenant app with NuxtHub?", "Design a full auth flow with sessions and roles"
+- Examples: "My deployment is failing with this error...", "How to build a multi-tenant app?", "Design a full auth flow with sessions and roles"
**Note:** Questions referencing current events, recent releases, or topics unlikely to be covered in the sandbox documentation should be classified as at least **moderate** to allow the agent enough steps for web search.`
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index eedfca5..6caeb27 100644
--- a/packages/sdk/README.md
+++ b/packages/sdk/README.md
@@ -38,7 +38,7 @@ const { text } = await generateText({
model: 'google/gemini-3-flash',
tools: savoir.tools,
maxSteps: 10,
- prompt: 'How do I use useAsyncData in Nuxt?',
+ prompt: 'How do I configure authentication?',
})
console.log(text)
diff --git a/savoir.config.ts b/savoir.config.ts
deleted file mode 100644
index 3f21f07..0000000
--- a/savoir.config.ts
+++ /dev/null
@@ -1,61 +0,0 @@
-/**
- * Savoir configuration file
- *
- * This file defines available sources as a reference.
- * Sources are stored in SQLite via NuxtHub and can be managed via the API:
- * GET/POST/PUT/DELETE /api/sources
- */
-export default {
- sources: {
- github: [
- // Nuxt Core
- {
- id: 'nuxt',
- label: 'Nuxt',
- repo: 'nuxt/nuxt',
- additionalSyncs: [{ repo: 'nuxt/nuxt.com', contentPath: 'content' }],
- },
- {
- id: 'nitro',
- label: 'Nitro',
- repo: 'nitrojs/nitro',
- branch: 'main',
- },
-
- // Nuxt Modules
- { id: 'nuxt-ui', label: 'Nuxt UI', repo: 'nuxt/ui', branch: 'v4', contentPath: 'docs/content' },
- { id: 'nuxt-hub', label: 'NuxtHub', repo: 'nuxt-hub/core', contentPath: 'docs/content' },
- { id: 'nuxt-content', label: 'Nuxt Content', repo: 'nuxt/content', contentPath: 'docs/content' },
- { id: 'nuxt-image', label: 'Nuxt Image', repo: 'nuxt/image', contentPath: 'docs/content' },
- { id: 'nuxt-i18n', label: 'Nuxt i18n', repo: 'nuxt-modules/i18n', contentPath: 'docs/content' },
- { id: 'nuxt-scripts', label: 'Nuxt Scripts', repo: 'nuxt/scripts', contentPath: 'docs/content' },
- { id: 'nuxt-fonts', label: 'Nuxt Fonts', repo: 'nuxt/fonts', contentPath: 'docs/content' },
- { id: 'nuxt-eslint', label: 'Nuxt ESLint', repo: 'nuxt/eslint', contentPath: 'docs/content' },
- { id: 'nuxt-devtools', label: 'Nuxt DevTools', repo: 'nuxt/devtools', contentPath: 'docs/content' },
- { id: 'mcp-toolkit', label: 'MCP Toolkit', repo: 'nuxt-modules/mcp-toolkit', contentPath: 'apps/docs/content' },
- { id: 'nuxt-studio', label: 'Nuxt Studio', repo: 'nuxt-content/nuxt-studio' },
-
- // README-only
- { id: 'nuxt-icon', label: 'Nuxt Icon', repo: 'nuxt/icon', readmeOnly: true },
- { id: 'nuxt-auth-utils', label: 'Nuxt Auth Utils', repo: 'atinux/nuxt-auth-utils', readmeOnly: true },
- { id: 'ofetch', label: 'ofetch', repo: 'unjs/ofetch', readmeOnly: true },
- { id: 'nuxt-a11y', label: 'Nuxt a11y', repo: 'nuxt/a11y', readmeOnly: true },
- { id: 'nuxt-hints', label: 'Nuxt Hints', repo: 'nuxt/hints', readmeOnly: true },
-
- // UnJS
- { id: 'h3', label: 'H3', repo: 'unjs/h3' },
- { id: 'unstorage', label: 'unstorage', repo: 'unjs/unstorage' },
- { id: 'unhead', label: 'Unhead', repo: 'unjs/unhead' },
-
- // SEO
- { id: 'nuxt-og-image', label: 'Nuxt OG Image', repo: 'nuxt-modules/og-image', contentPath: 'docs/content' },
- { id: 'nuxt-sitemap', label: 'Nuxt Sitemap', repo: 'nuxt-modules/sitemap', contentPath: 'docs/content' },
- { id: 'nuxt-robots', label: 'Nuxt Robots', repo: 'nuxt-modules/robots', contentPath: 'docs/content' },
- ],
-
- youtube: [
- { id: 'alex-lichter', label: 'Alexander Lichter', channelId: 'UCqFPgMzGbLjd-MX-h3Z5aQA', handle: '@TheAlexLichter', maxVideos: 100 },
- { id: 'learn-vue', label: 'LearnVue', channelId: 'UCGwuxdEeCf0TIA2RbPOj-8g', handle: '@LearnVue', maxVideos: 50 },
- ],
- },
-}