### Quick Start Locally

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/README.md

Install dependencies, optionally start a local PostgreSQL instance, build, and run the application locally. Use 'pnpm dev' for development mode with hot-reloading.

```bash
pnpm i

# (Optional) Start a local PostgreSQL instance
pnpm docker:pg

pnpm build:local && pnpm start

# (Recommended for most cases. Ensures correct cookie settings.)
# For development mode with hot-reloading and debugging, you can use:
pnpm dev
```

--------------------------------

### Quick Start with Docker Compose

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/README.md

Build and start all services, including PostgreSQL, using Docker Compose after installing dependencies. Ensure your .env file is configured.

```bash
pnpm i

pnpm docker-compose:up
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/docker.md

Clone the project repository and change into the project directory to begin setup.

```sh
git clone https://github.com/cgoinglove/better-chatbot
cd better-chatbot
```

--------------------------------

### Build and Start Docker Container

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/docker.md

Build the Docker image and start the application container in detached mode.

```sh
pnpm docker-compose:up
```

--------------------------------

### Setup PostgreSQL Database

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/CONTRIBUTING.md

Quickly set up a PostgreSQL database using Docker for end-to-end testing requirements.

```bash
pnpm docker:pg
```

--------------------------------

### Install pnpm Package Manager

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/README.md

Install pnpm globally if you don't have it. This is the recommended package manager for the project.

```bash
npm install -g pnpm
```

--------------------------------

### Install Playwright Browsers

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/CONTRIBUTING.md

Install the necessary browsers for running Playwright end-to-end tests.

```bash
pnpm playwright:install
```

--------------------------------

### Markdown Image Example

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/CONTRIBUTING.md

Illustrates how to include before/after and reference images in markdown for visual documentation.

```markdown
## Before

![before](./before-image.png)

## After

![after](./after-image.png)

## Reference

![reference](./reference-design.png)
```

--------------------------------

### Environment Variables Configuration

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/README.md

Example `.env` file content. Configure LLM provider API keys, database connection URLs, and other service credentials. The `.env` file is generated by `pnpm i`.

```dotenv
# === LLM Provider API Keys ===
# You only need to enter the keys for the providers you plan to use
GOOGLE_GENERATIVE_AI_API_KEY=****
OPENAI_API_KEY=****
XAI_API_KEY=****
ANTHROPIC_API_KEY=****
OPENROUTER_API_KEY=****
OLLAMA_BASE_URL=http://localhost:11434/api



# Secret for Better Auth (generate with: npx @better-auth/cli@latest secret)
BETTER_AUTH_SECRET=****

# (Optional)
# URL for Better Auth (the URL you access the app from)
BETTER_AUTH_URL=

# === Database ===
# If you don't have PostgreSQL running locally, start it with: pnpm docker:pg
POSTGRES_URL=postgres://your_username:your_password@localhost:5432/your_database_name

# (Optional)
# === Tools ===
# Exa AI for web search and content extraction (optional, but recommended for @web and research features)
EXA_API_KEY=your_exa_api_key_here


# Whether to use file-based MCP config (default: false)
FILE_BASED_MCP_CONFIG=false

# === File Storage ===
# Vercel Blob is the default storage driver (works in both local dev and production)
# Pull the token locally with `vercel env pull`
FILE_STORAGE_TYPE=vercel-blob
FILE_STORAGE_PREFIX=uploads
BLOB_READ_WRITE_TOKEN=

# -- S3 (coming soon) --
# FILE_STORAGE_TYPE=s3
# FILE_STORAGE_PREFIX=uploads
# FILE_STORAGE_S3_BUCKET=
# FILE_STORAGE_S3_REGION=

# (Optional)
# === OAuth Settings ===
# Fill in these values only if you want to enable Google/GitHub/Microsoft login

#GitHub
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

#Google
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
# Set to 1 to force account selection
GOOGLE_FORCE_ACCOUNT_SELECTION=


# Microsoft
MICROSOFT_CLIENT_ID=
MICROSOFT_CLIENT_SECRET=
# Optional Tenant Id
MICROSOFT_TENANT_ID=
# Set to 1 to force account selection
MICROSOFT_FORCE_ACCOUNT_SELECTION=

# Set this to 1 to disable user sign-ups.
DISABLE_SIGN_UP=

# Set this to 1 to disallow adding MCP servers.
NOT_ALLOW_ADD_MCP_SERVERS=

```

--------------------------------

### Install Dependencies and Playwright Browsers

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

Installs project dependencies and Playwright browsers required for running end-to-end tests.

```bash
pnpm install

pnpm playwright:install
```

--------------------------------

### Clone the Repository

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/CONTRIBUTING.md

Clone your forked repository locally to start making changes.

```bash
git clone https://github.com/YOUR_USERNAME/better-chatbot.git
cd better-chatbot
```

--------------------------------

### Define MCP Servers in .mcp-config.json

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/mcp-server-setup-and-tool-testing.md

Example of defining MCP servers in a '.mcp-config.json' file for local development.

```jsonc
// .mcp-config.json
{
  "playwright": {
    "command": "npx",
    "args": ["@playwright/mcp@latest"]
  }
}
```

--------------------------------

### CI Configuration for E2E Tests

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/tests/PLAYWRIGHT-TEST-STRATEGY.md

Example GitHub Actions configuration to run the full E2E test suite in a CI environment. This ensures consistent testing of first-user assignment, standard functionality, admin features, and mobile responsiveness.

```yaml
# Example GitHub Actions
- name: Run E2E Tests
  run: |
    # Always run full suite in CI for consistency
    pnpm test:e2e:all
```

--------------------------------

### Docker Compose for DB Only

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/README.md

Start only the PostgreSQL service using Docker Compose and apply migrations. The application can then be run locally using 'pnpm dev' or 'pnpm build && pnpm start'.

```bash
# Start Postgres only via compose
# Ensure your .env includes: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB matching POSTGRES_URL
docker compose -f docker/compose.yml up -d postgres

# Apply migrations
pnpm db:migrate


# Run app locally
pnpm dev   # or: pnpm build && pnpm start
```

--------------------------------

### Run Only Standard E2E Tests

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/tests/PLAYWRIGHT-TEST-STRATEGY.md

Executes standard E2E tests, skipping the first-user setup. This command seeds test users if necessary and creates authentication states for subsequent tests.

```bash
pnpm test:e2e:standard
```

--------------------------------

### Run Development Server and Tests

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/CONTRIBUTING.md

Run the development server and execute unit tests to verify your changes.

```bash
pnpm dev
pnpm test
```

--------------------------------

### File System MCP Server Instructions

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/system-prompts-and-customization.md

Set default context for File System MCP servers, including the working directory and path preferences.

```text
Working directory: /Users/username/projects/my-app
Prefer relative paths in responses
Always backup before making destructive changes
```

--------------------------------

### Database Query Tool Instructions

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/system-prompts-and-customization.md

Set custom instructions for the Database Query tool, including default database and how to explain query results.

```text
Default database: production
Always explain query results in business terms
Include performance impact warnings for large queries
```

--------------------------------

### GitHub MCP Server Instructions

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/system-prompts-and-customization.md

Configure default context for GitHub MCP servers, such as the repository and branch to use.

```text
Default repository: owner/repo-name
Always use the main branch unless specified
Include issue labels when creating issues
```

--------------------------------

### Local Development with ngrok for Webhooks

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/file-storage.md

Use ngrok to expose your local development server to the internet, allowing Vercel Blob webhooks to reach it. Configure the `VERCEL_BLOB_CALLBACK_URL` in your `.env.local` file with the ngrok URL.

```bash
# Terminal 1: Start your app
pnpm dev

# Terminal 2: Start ngrok
ngrok http 3000

# Add to .env.local
VERCEL_BLOB_CALLBACK_URL=https://abc123.ngrok-free.app
```

--------------------------------

### Google Login Tool Instructions

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/system-prompts-and-customization.md

Configure specific instructions for the Google Login tool, like default email and authentication preferences.

```text
Default email: user@company.com
Prefer 2FA authentication when available
```

--------------------------------

### Migrate Database

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/docker.md

Run database migrations after configuring your external database connection.

```sh
pnpm db:migrate
```

--------------------------------

### Configure Stdio MCP Server

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/mcp-server-setup-and-tool-testing.md

Use this configuration for locally executed tools that run via a command-line interface. 'command' is required, and 'args' are optional.

```json
{
  "command": "npx",
  "args": ["@playwright/mcp@latest"]
}
```

--------------------------------

### Run All E2E Tests

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/tests/PLAYWRIGHT-TEST-STRATEGY.md

Executes both first-user and standard E2E tests. This command ensures a clean database for first-user tests and then proceeds with seeding users and running all standard tests.

```bash
pnpm test:e2e:all
# or just
pnpm test:e2e
```

--------------------------------

### Run Project Checks and Tests

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/CONTRIBUTING.md

Execute linting, type checking, unit tests, and end-to-end tests using pnpm. The e2e test suite is recommended for comprehensive validation.

```bash
pnpm check # lint, type check, and run unit tests
pnpm test:e2e # run comprehensive e2e test suite (recommended)
```

--------------------------------

### Complete .env File for Social Logins

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/oauth.md

Consolidated environment variables for Google, GitHub, and Microsoft authentication, including optional force account selection settings.

```env
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
# Set to 1 to force account selection
GOOGLE_FORCE_ACCOUNT_SELECTION=1

GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

# Microsoft
MICROSOFT_CLIENT_ID=your_microsoft_client_id
MICROSOFT_CLIENT_SECRET=your_microsoft_client_secret
# Optional Tenant Id
MICROSOFT_TENANT_ID=your_microsoft_tenant_id
# Set to 1 to force account selection
MICROSOFT_FORCE_ACCOUNT_SELECTION=1
```

--------------------------------

### Microsoft Credentials Environment Variables

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/oauth.md

Add your Microsoft Client ID, Client Secret, and optionally Tenant ID to your .env file for authentication.

```env
MICROSOFT_CLIENT_ID=your_client_id
MICROSOFT_CLIENT_SECRET=your_client_secret
MICROSOFT_TENANT_ID=your_tenant_id # Optional
```

--------------------------------

### Optional: Upload with curl

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/storage/s3-setup.md

This command demonstrates how to upload a file to S3 using a presigned URL obtained from the verification script. Replace '<url>' with the actual URL and specify the correct Content-Type.

```bash
curl -X PUT -H "Content-Type: image/png" --data-binary @file.png "<url>"
```

--------------------------------

### Google Credentials Environment Variables

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/oauth.md

Add your Google Client ID and Client Secret to your .env file for authentication.

```env
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
```

--------------------------------

### Authentication Settings Configuration

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/oauth.md

Optional environment variables to disable email/password sign-in or new user sign-ups.

```env
# Disable email/password sign-in (optional)
DISABLE_EMAIL_SIGN_IN=1

# Disable new user sign-ups (optional)
DISABLE_SIGN_UP=1
```

--------------------------------

### MCP OAuth Flow Sequence Diagram

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/mcp-oauth-flow.md

Visualizes the step-by-step process of the MCP OAuth flow, from server startup to successful token acquisition. It highlights participant interactions and conditional logic.

```mermaid
sequenceDiagram
  autonumber
  participant User as User
  participant UI as MCPCard/UI
  participant App as Next App (Server)
  participant Client as MCPClient
  participant Provider as PgOAuthClientProvider
  participant Repo as OAuthRepository(DB)
  participant OAuthSrv as OAuth Server(MCP)

  Note over App: Server boot → MCP manager init
  App->>Client: connect()
  Client->>Provider: attach OAuth provider if needed
  Provider->>Repo: find token session
  alt token session exists
    Provider-->>Client: use authenticated session
  else no token session
    Provider->>Repo: use in‑progress or create new state session
    Client-->>UI: status = authorizing (needs user action)
  end

  User->>UI: click Authorize
  UI->>App: authorizeMcpClientAction(id)
  App->>Client: refreshClient(id)
  Client-->>UI: authorizationUrl
  UI->>OAuthSrv: popup login/consent
  OAuthSrv-->>App: /api/mcp/oauth/callback?code&state
  App->>Repo: get session by state
  App->>Client: finishAuth(code)
  Client->>Provider: saveTokens(tokens)
  Provider->>Repo: saveTokensAndCleanup(mcpServerId, state)
  App->>Client: refreshClient(id)
  App-->>UI: postMessage(MCP_OAUTH_SUCCESS)
```

--------------------------------

### Run Specific E2E Test Suites

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/CONTRIBUTING.md

Optionally, run specific end-to-end test suites by providing a path.

```bash
pnpm test:e2e -- tests/agents/
pnpm test:e2e -- tests/models/
```

--------------------------------

### Run All E2E Tests

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/CONTRIBUTING.md

Execute all end-to-end tests to ensure core functionality is working as expected.

```bash
pnpm test:e2e
```

--------------------------------

### Configure Environment Variables for E2E Tests

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

Set these environment variables to configure the testing environment, including database connection, authentication secrets, and LLM provider API keys. At least one LLM provider key is required.

```bash
# Database (required)
POSTGRES_URL=postgres://user:password@localhost:5432/database

# Authentication (required)
BETTER_AUTH_SECRET=your-secret-here

# At least one LLM provider (required)
OPENAI_API_KEY=your-openai-key
# OR
ANTHROPIC_API_KEY=your-anthropic-key
# OR
GOOGLE_GENERATIVE_AI_API_KEY=your-google-key

# Optional: Set default model for tests - will need to be corelated with API keys
E2E_DEFAULT_MODEL=openai/gpt-4o-mini
```

--------------------------------

### Commit and Push Changes

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/CONTRIBUTING.md

Stage all changes, commit them with an internal message, and push to your origin branch.

```bash
git add .
git commit -m "your internal message"
git push origin your-branch-name
```

--------------------------------

### Update Application

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/docker.md

Update the application to the latest version using the provided command.

```sh
pnpm docker-compose:update
```

--------------------------------

### Enable File-Based MCP Configuration

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/mcp-server-setup-and-tool-testing.md

Set this environment variable to true to enable file-based MCP configuration for local development.

```env
# Whether to use file-based MCP config (default: false)
FILE_BASED_MCP_CONFIG=true
```

--------------------------------

### GitHub Credentials Environment Variables

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/oauth.md

Add your GitHub Client ID and Client Secret to your .env file for authentication. Ensure the 'user:email' scope is included in your GitHub app.

```env
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
```

--------------------------------

### Run Only First-User E2E Tests

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/tests/PLAYWRIGHT-TEST-STRATEGY.md

Executes only the first-user E2E tests, which includes clearing the database and verifying the first user receives the admin role, followed by testing regular user roles.

```bash
pnpm test:e2e:first-user
```

--------------------------------

### Environment Variables for File Storage

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/file-storage.md

Configure storage driver, subdirectory prefix, and Vercel Blob or S3 specific credentials using these environment variables. Vercel Blob is the default.

```ini
# Storage driver selection (defaults to vercel-blob)
FILE_STORAGE_TYPE=vercel-blob # or s3 (coming soon)

# Optional: Subdirectory prefix for organizing files
FILE_STORAGE_PREFIX=uploads

# === Vercel Blob (FILE_STORAGE_TYPE=vercel-blob) ===
BLOB_READ_WRITE_TOKEN=<auto on Vercel>
VERCEL_BLOB_CALLBACK_URL= # Optional: For local webhook testing with ngrok

# === S3 (FILE_STORAGE_TYPE=s3, not yet implemented) ===
# FILE_STORAGE_S3_BUCKET=
# FILE_STORAGE_S3_REGION=
# AWS_ACCESS_KEY_ID=
# AWS_SECRET_ACCESS_KEY=

```

--------------------------------

### Clean Test Data and Run E2E Tests

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/tests/PLAYWRIGHT-TEST-STRATEGY.md

Cleans all existing test data from the database and then runs the full E2E test suite. This is useful for troubleshooting 'User already exists' errors.

```bash
pnpm test:e2e:clean  # Clean all test data
pnpm test:e2e        # Run tests fresh
```

--------------------------------

### Generate Authentication Secret

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/docker.md

Generate a secret key for authentication using the provided command.

```sh
pnpx auth secret
```

--------------------------------

### Run E2E Tests with UI Mode

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/tests/PLAYWRIGHT-TEST-STRATEGY.md

Launches the Playwright UI mode, allowing for interactive running and debugging of any configured test suite.

```bash
pnpm test:e2e:ui
```

--------------------------------

### Verify S3 Upload URL Script Execution

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/storage/s3-setup.md

Execute this command to test the presigned S3 upload URL generation script. Ensure your AWS profile and environment variables are correctly set.

```bash
AWS_PROFILE=<your_profile> \
FILE_STORAGE_TYPE=s3 \
FILE_STORAGE_S3_BUCKET=better-chatbot-dev \
FILE_STORAGE_S3_REGION=us-east-2 \
pnpm tsx scripts/verify-s3-upload-url.ts
```

--------------------------------

### Run End-to-End Tests

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

Commands to execute all end-to-end tests, run them with a UI for interactive debugging, or target specific test files.

```bash
pnpm test:e2e

pnpm test:e2e:ui

pnpm test:e2e -- tests/agents/agent-creation.spec.ts

pnpm test:e2e:debug
```

--------------------------------

### Run Specific E2E Tests with Browser Visible

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

Execute a specific E2E test file with the browser UI visible for easier debugging. This command helps in visually inspecting test execution.

```bash
# Run specific test with browser visible
pnpm test:e2e -- tests/agents/agent-creation.spec.ts --headed
```

--------------------------------

### Run a Single E2E Test by Name

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

Execute a single E2E test case identified by a specific string. This is useful for quickly iterating on a particular test.

```bash
# Run single test
npx playwright test -g "should create agent"
```

--------------------------------

### Create a New Branch

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/CONTRIBUTING.md

Create a new branch for your feature or bug fix before implementing changes.

```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
```

--------------------------------

### Skip First-User Tests with Environment Variable

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/tests/PLAYWRIGHT-TEST-STRATEGY.md

Skips the first-user tests by setting the SKIP_FIRST_USER_TEST environment variable to 1. This is useful for faster testing cycles when auth logic is not being modified.

```bash
SKIP_FIRST_USER_TEST=1 pnpm test:e2e
```

--------------------------------

### Configure SSE/StreamableHTTP MCP Server

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/mcp-server-setup-and-tool-testing.md

Use this configuration for remote servers communicating via HTTP (SSE or streaming). 'url' is required, and 'headers' are optional.

```json
{
  "url": "https://api.example.com",
  "headers": {
    "Authorization": "Bearer sk-..."
  }
}
```

--------------------------------

### Simulate Multi-User Interaction in Tests

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

For tests requiring interaction between multiple users, create separate browser contexts for each user. This allows simulating concurrent actions, such as one user sharing an agent with another.

```typescript
import { TEST_USERS } from '../constants/test-users';
test.describe('Agent Sharing', () => {
  test('user sharing workflow', async ({ browser }) => {
    // User1 creates agent
    const user1Context = await browser.newContext({
      storageState: TEST_USERS.editor.authFile,
    });
    const user1Page = await user1Context.newPage();

    // User2 interacts with shared agent
    const user2Context = await browser.newContext({
      storageState: TEST_USERS.editor2.authFile,
    });
    const user2Page = await user2Context.newPage();
  });
});
```

--------------------------------

### Implement Reliable Waiting Strategies

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

Employ appropriate waiting strategies to ensure tests are robust. This includes waiting for network activity, specific API responses, or URL changes to prevent race conditions.

```typescript
// Wait for network activity to settle
await page.waitForLoadState('networkidle');
```

```typescript
// Wait for specific API responses
const responsePromise = page.waitForResponse(
  (response) => response.url().includes('/api/agent/') && response.request().method() === 'PUT'
);
await page.getByTestId('save-button').click();
await responsePromise;
```

```typescript
// Wait for navigation
await page.waitForURL('**/agents', { timeout: 10000 });
```

--------------------------------

### Base URL Configuration for OAuth

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/oauth.md

Set the BETTER_AUTH_URL environment variable to match your application's access URL for correct OAuth callback handling. Supports HTTPS and HTTP for local development and production.

```env
# For local development with HTTPS
BETTER_AUTH_URL=https://localhost:3000

# For local development with HTTP (default)
BETTER_AUTH_URL=http://localhost:3000

# For production
BETTER_AUTH_URL=https://yourdomain.com
```

--------------------------------

### Browser Automation with Playwright MCP

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/README.md

Control a web browser using Microsoft's playwright-mcp tool. The LLM autonomously decides how to use tools from the MCP server, calling them multiple times to complete a multi-step task and return a final message.

```prompt
1. Use the @tool('web-search') to look up information about “modelcontetprotocol.”

2. Then, using : @mcp("playwright")
   - navigate Google (https://www.google.com)
   - Click the “Login” button
   - Enter my email address (neo.cgoing@gmail.com)
   - Clock the "Next"  button
   - Close the browser
```

--------------------------------

### Pull Environment Variables Locally

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/file-storage.md

Use this command to pull environment variables from your Vercel project, essential for local development with Vercel Blob.

```bash
vercel env pull
```

--------------------------------

### Enable Debug Mode for E2E Tests

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

Launch E2E tests in debug mode to allow for setting breakpoints and stepping through the code. This is crucial for in-depth troubleshooting.

```bash
# Debug mode with breakpoints
pnpm test:e2e:debug
```

--------------------------------

### Debug a Specific E2E Test

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/CONTRIBUTING.md

Run and debug a specific end-to-end test file in headed mode.

```bash
pnpm test:e2e -- tests/agents/agent-visibility.spec.ts --headed
```

--------------------------------

### Authenticate as a Specific User in Tests

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

Use the `test.use` method with `storageState` to authenticate tests as a specific user. This is crucial for testing multi-user functionalities. Available users include editor, editor2, regular, and admin.

```typescript
// Most tests use single user authentication
import { TEST_USERS } from '../constants/test-users';
test.describe('Agent Creation', () => {
  test.use({ storageState: TEST_USERS.editor.authFile });

  test('should create agent', async ({ page }) => {
    // Test logic here
  });
});
```

```typescript
import { TEST_USERS } from '../constants/test-users';
test.describe('Agent Creation', () => {
  test.use({ storageState: TEST_USERS.editor2.authFile });

  test('should create agent', async ({ page }) => {
    // Test logic here
  });
});
```

--------------------------------

### Playwright Multi-User Test Template

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

A template for testing workflows involving multiple users. It demonstrates setting up separate browser contexts for each user and performing actions.

```typescript
import { TEST_USERS } from '../constants/test-users';
test('multi-user workflow', async ({ browser }) => {
  const testId = Date.now().toString(36);

  // User1 setup
  const user1Context = await browser.newContext({
    storageState: TEST_USERS.editor.authFile,
  });
  const user1Page = await user1Context.newPage();

  try {
    // User1 actions
    await user1Page.goto('/create');
    // ... user1 workflow
  } finally {
    await user1Context.close();
  }

  // User2 verification
  const user2Context = await browser.newContext({
    storageState: 'tests/.auth/user2.json',
  });
  const user2Page = await user2Context.newPage();

  try {
    // User2 actions
    await user2Page.goto('/shared');
    // ... user2 workflow
  } finally {
    await user2Context.close();
  }
});
```

--------------------------------

### Server-Side File Upload

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/file-storage.md

Upload files programmatically from your server using the `serverFileStorage.upload` method. Ensure the buffer, filename, and content type are correctly provided.

```typescript
import { serverFileStorage } from "lib/file-storage";

const result = await serverFileStorage.upload(buffer, {
  filename: "generated-image.png",
  contentType: "image/png",
});

console.log("Public URL:", result.sourceUrl);
```

--------------------------------

### Generate E2E Test Report

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

Generate and display a test report after E2E tests have been executed. This report provides a summary of test results and can include detailed information.

```bash
# Generate test report
npx playwright show-report
```

--------------------------------

### Client-Side File Upload Component

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/file-storage.md

This component uses the useFileUpload hook to handle file selection and upload. It automatically manages the upload process and provides feedback on the upload status. Ensure the hook is correctly imported from 'hooks/use-presigned-upload'.

```tsx
"use client";

import { useFileUpload } from "hooks/use-presigned-upload";

function FileUploadComponent() {
  const { upload, isUploading } = useFileUpload();

  const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    const result = await upload(file);
    if (!result) return; // Upload failed (error shown via toast)

    // File uploaded successfully
    console.log("Public URL:", result.url);
    console.log("Pathname (key):", result.pathname);
  };

  return (
    <input type="file" onChange={handleFileChange} disabled={isUploading} />
  );
}

```

--------------------------------

### Stop Docker Container

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/docker.md

Stop the running application container.

```sh
pnpm docker-compose:down
```

--------------------------------

### Dev Public-Read Policy for Uploads Prefix

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/storage/s3-setup.md

This JSON policy grants public read access to objects within the 'uploads/' prefix of a development S3 bucket. Use this only if unauthenticated downloads are required.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowPublicReadForUploadsPrefix",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::better-chatbot-dev/uploads/*"
    }
  ]
}
```

--------------------------------

### Take Screenshots for Debugging

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

Capture screenshots during test execution to aid in debugging. This helps in visually identifying the state of the application when an issue occurs.

```typescript
// Take screenshots for debugging
await page.screenshot({ path: 'debug-agent-creation.png', fullPage: true });
```

--------------------------------

### Playwright Test Template

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

A basic template for writing a Playwright test. It includes navigation, user interaction, waiting for navigation, and assertion.

```typescript
import { test, expect } from '@playwright/test';
import { TEST_USERS } from '../constants/test-users';
test.describe('Your Feature', () => {
  test.use({ storageState: TEST_USERS.editor.authFile });

  test('should perform action', async ({ page }) => {
    // Navigate to page
    await page.goto('/your-feature');

    // Perform actions
    await page.getByTestId('input-field').fill('test value');
    await page.getByTestId('submit-button').click();

    // Wait for response
    await page.waitForURL('**/success', { timeout: 10000 });

    // Verify results
    await expect(page.getByTestId('success-message')).toBeVisible();
  });
});
```

--------------------------------

### Upload Completion Webhook Handler

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/file-storage.md

Implement the `onUploadCompleted` webhook to process file uploads after they are finished. This function is called by Vercel Blob and can be used to save file metadata to your database or trigger notifications.

```typescript
// src/app/api/storage/upload-url/route.ts

onUploadCompleted: async ({ blob, tokenPayload }) => {
  const { userId } = JSON.parse(tokenPayload);

  // Save to database
  await db.files.create({
    url: blob.url,
    pathname: blob.pathname,
    userId,
    size: blob.size,
    contentType: blob.contentType,
  });

  // Send notification
  // await sendNotification(userId, "File uploaded!");
}
```

--------------------------------

### Log Page Content for Debugging

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

Output debugging information to the console, such as the current URL or the number of elements found on the page. This aids in understanding the test environment and state.

```typescript
// Log page content
console.log('Current URL:', page.url());
const agents = await page.locator('[data-testid="agent-card-name"]').all();
console.log(`Found ${agents.length} agents`);
```

--------------------------------

### Use data-testid for Stable Selectors

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

Prefer `data-testid` attributes for selecting elements to ensure test stability and semantic clarity. Avoid selectors that are prone to breaking due to UI changes or language localization.

```typescript
// ✅ Good - stable and semantic
await page.getByTestId('agent-name-input').fill('My Agent');
await page.getByTestId('agent-save-button').click();

// ❌ Avoid - fragile and language-dependent
await page.locator('input[placeholder="Enter agent name"]').fill('My Agent');
await page.getByText('Save').click();
```

--------------------------------

### Generate Unique Test Data

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/docs/tips-guides/e2e-testing-guide.md

Create unique data for each test run to prevent conflicts and ensure data integrity. This is particularly useful for creating entities like agents.

```typescript
const testSuffix = Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
const agentName = `Test Agent ${testSuffix}`;
```

--------------------------------

### Add New Language to Supported Locales

Source: https://github.com/keinsaasforever/better-chatbot/blob/main/messages/language.md

Update the SUPPORTED_LOCALES array in src/lib/const.ts to include your new language. Ensure the code and name fields are correctly set.

```typescript
export const SUPPORTED_LOCALES = [
  {
    code: "en",
    name: "English 🇺🇸",
  },
  {
    code: "ko",
    name: "Korean 🇰🇷",
  },
  {
    code: "your-language-code",
    name: "Your Language Name 🏴",
  },
];
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.