### Install Mintlify CLI and start preview server

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/quickstart.mdx

Install the Mintlify CLI globally and start the preview server. After running these commands, open http://localhost:3000 to see your docs live. The preview updates automatically as you edit files.

```bash
npm i -g mint
```

```bash
mint dev
```

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

### Connect to OpenAI-compatible provider

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/cli/README.md

Start interactive setup for an OpenAI-compatible server (e.g., LM Studio).

```bash
btca connect --provider openai-compat
```

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

### Install btca CLI skill for guided setup

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/guides/quickstart.mdx

Runs the interactive skills.sh installer to install the btca CLI skill.

```bash
btca skill
```

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

### Install from source

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/cli/README.md

Clone the repository, install dependencies, and build the CLI.

```bash
git clone https://github.com/davis7dotsh/better-context.git
cd better-context
bun install
bun run --filter=@btca/cli build
```

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

### Install dependencies and run dev server from repo root

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/web/README.md

Run these commands from the repository root to install dependencies and start the web development server.

```sh
bun install
bun run dev:web
```

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

### Install from npm

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/cli/README.md

Install the CLI globally using Bun.

```bash
bun add -g @btca/cli
```

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

### Install Mintlify CLI

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/README.md

Install the Mintlify CLI globally to preview documentation changes locally.

```bash
npm i -g mint
```

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

### Example config.toml

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/server/README.md

Example config.toml showing provider, model, resourcesDirectory, and three resource types: local, git, and npm.

```toml
provider = "anthropic"
model = "claude-3-7-sonnet-20250219"
resourcesDirectory = "~/.btca/resources"

[[resources]]
type = "local"
name = "my-project"
path = "/path/to/my/project"

[[resources]]
type = "git"
name = "some-repo"
url = "https://github.com/user/repo"
branch = "main"

[[resources]]
type = "npm"
name = "react-npm"
package = "react"
version = "latest"
```

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

### Tabs for alternative content (macOS, Windows, Linux)

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/ai-tools/cursor.mdx

Tabbed example showing how to install Node.js and a package on macOS, Windows, and Linux, as part of the Mintlify Tabs component.

```bash
brew install node
npm install -g package-name
```

```powershell
choco install nodejs
npm install -g package-name
```

```bash
sudo apt install nodejs npm
npm install -g package-name
```

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

### Start server

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/cli/README.md

Start the btca server on default or custom port.

```bash
# Start on default port (8080)
btca serve
```

```bash
# Start on custom port
btca serve --port 3000
```

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

### Install dependencies with bun install

Source: https://github.com/davis7dotsh/better-context/blob/main/packages/shared/README.md

Installs the project dependencies using Bun.

```bash
bun install
```

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

### Install btca-server with Bun

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/server/README.md

Install the btca-server package using Bun, the required runtime (>= 1.1.0).

```bash
bun add btca-server
```

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

### Add resource examples

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/cli/README.md

Add git repositories, local directories, and npm packages.

```bash
# Add a git repository
btca add https://github.com/Effect-TS/effect --name effect --type git --branch main
```

```bash
# Add with search path (focus on specific subdirectory)
btca add https://github.com/sveltejs/svelte.dev --name svelte --type git --branch main --search-path apps/svelte.dev
```

```bash
# Add a local directory
btca add /path/to/project --name myproject --type local
```

```bash
# Add an npm package
btca add npm:react --name reactNpm --type npm
```

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

### btca.config.jsonc example with resources and provider settings

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/web/static/docs/SETUP_PROMPT.md

Example configuration file for btca. Shows the structure with resources array, model, provider, and timeout. The comment indicates that more resources would be added after approval.

```jsonc
{
	"$schema": "https://btca.dev/btca.schema.json",
	"resources": [
		{
			"name": "svelte",
			"type": "git",
			"url": "https://github.com/sveltejs/svelte.dev",
			"branch": "main",
			"searchPath": "apps/svelte.dev",
			"specialNotes": "Svelte docs website. Focus on content directory for markdown docs."
		},
		{
			"name": "tailwind",
			"type": "git",
			"url": "https://github.com/tailwindlabs/tailwindcss.com",
			"branch": "main",
			"searchPath": "src/docs"
		}
		// ... all approved resources
	],
	"model": "claude-haiku-4-5",
	"provider": "opencode",
	"providerTimeoutMs": 300000
}
```

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

### Example output from bun sandbox

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/sandbox/README.md

Example output from running `bun sandbox`. Shows the sandbox creation, version checks, server startup, and the public URL. The server is public and requires no auth token.

```text
Creating sandbox from snapshot: btca-sandbox
Sandbox created with ID: abc123...
bun version: 1.3.5
btca version: 1.0.21
Setting up btca configuration...
Starting btca server...
Server is healthy!

========================================
BTCA Sandbox is running!
========================================
Sandbox ID: abc123...
Server URL: https://3000-abc123.proxy.daytona.works
(Public - no auth token required)
========================================

Press Ctrl+C to stop the sandbox and clean up.
```

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

### Run a sandbox from the snapshot

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/sandbox/README.md

Starts a sandbox from the pre-built snapshot, uploads the default btca configuration, starts the btca server on port 3000, and outputs the public URL. Press Ctrl+C to stop and clean up.

```bash
bun sandbox
```

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

### Install btca CLI globally with Bun

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/guides/quickstart.mdx

Requires Bun. Installs the btca CLI globally.

```bash
bun add -g btca
```

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

### One-shot question examples

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/cli/README.md

Various examples of the ask command: single resource, GitHub repo, multiple resources, and @mentions.

```bash
# Single resource
btca ask --resource svelte --question "How do signals work?"
```

```bash
# One-shot GitHub repository (anonymous)
btca ask --resource https://github.com/sveltejs/svelte.dev -q "How do I setup a new sveltekit project?"
```

```bash
# Multiple resources
btca ask --resource react --resource typescript --question "How do I type useState?"
```

```bash
# Using @mentions in question
btca ask --question "@svelte @tailwind How do I style components?"
```

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

### Bun.serve frontend example with HTML imports and React

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/sandbox/AGENTS.md

Complete frontend example: server (index.ts) serves an HTML file that imports a React component (frontend.tsx). Run with `bun --hot ./index.ts`.

```ts
import index from "./index.html"

Bun.serve({
  routes: {
    "/": index,
    "/api/users/:id": {
      GET: (req) => {
        return new Response(JSON.stringify({ id: req.params.id }));
      },
    },
  },
  // optional websocket support
  websocket: {
    open: (ws) => {
      ws.send("Hello, world!");
    },
    message: (ws, message) => {
      ws.send(message);
    },
    close: (ws) => {
      // handle close
    }
  },
  development: {
    hmr: true,
    console: true,
  }
})
```

```html
<html>
  <body>
    <h1>Hello, world!</h1>
    <script type="module" src="./frontend.tsx"></script>
  </body>
</html>
```

```tsx
import React from "react";
import { createRoot } from "react-dom/client";

// import .css files directly and it works
import './index.css';

const root = createRoot(document.body);

export default function Frontend() {
  return <h1>Hello, world!</h1>;
}

root.render(<Frontend />);
```

```sh
bun --hot ./index.ts
```

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

### Install btca-local skill

Source: https://github.com/davis7dotsh/better-context/blob/main/README.md

Installs the btca-local skill from the better-context repository. Run this command to set up the skill for use with your coding agent.

```bash
npx skills add https://github.com/davis7dotsh/better-context --skill btca-local
```

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

### Bun test example (index.test.ts)

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/sandbox/AGENTS.md

Example test file using bun:test. Run with `bun test`.

```ts
import { test, expect } from "bun:test";

test("hello world", () => {
  expect(1).toBe(1);
});
```

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

### btca ask examples

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/guides/cli-reference.mdx

Three examples of the btca ask command: using a configured resource, an anonymous one-off git repo, and an anonymous one-off npm package.

```bash
# Normal configured resource ask
btca ask -r svelte -q "How do runes work in Svelte 5?"
```

```bash
# Anonymous one-off git repo ask
btca ask -r https://github.com/sveltejs/svelte -q "Where is the implementation of writable stores?"
```

```bash
# Anonymous one-off npm package ask
btca ask -r npm:react@19.0.0 -q "How is useTransition exported?"
```

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

### Request/response example (cURL and JSON)

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/ai-tools/cursor.mdx

Request/response example showing a cURL POST request and the JSON success response, used to document API endpoints.

```bash
curl -X POST 'https://api.example.com/users' \
  -H 'Content-Type: application/json' \
  -d '{"name": "John Doe", "email": "john@example.com"}'
```

```json
{
  "id": "user_123",
  "name": "John Doe", 
  "email": "john@example.com",
  "created_at": "2024-01-15T10:30:00Z"
}
```

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

### btca.config.jsonc example

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/guides/configuration.mdx

Example btca.config.jsonc file showing provider, model, maxSteps, dataDirectory, OpenAI-compatible provider options, and resource definitions. JSONC comments and trailing commas are supported. Global config is loaded first; project config overrides conflicts. If a project config exists, dataDirectory resolves relative to the project, and resources are stored in ${dataDirectory}/resources.

```jsonc
{
	"$schema": "https://btca.dev/btca.schema.json",
	"provider": "opencode",
	"model": "claude-haiku-4-5",
	"maxSteps": 40,
	"dataDirectory": ".btca",
	"providerOptions": {
		// OpenAI-compatible providers (e.g., LM Studio)
		"openai-compat": {
			// Base URL of your OpenAI-compatible server
			"baseURL": "http://localhost:1234/v1",
			// Provider name used by the AI SDK
			"name": "lmstudio"
		}
	},
	"resources": [
		{
			"type": "git",
			"name": "svelte",
			"url": "https://github.com/sveltejs/svelte.dev",
			"branch": "main",
			"searchPath": "apps/svelte.dev",
			"specialNotes": "Focus on docs content"
		},
		{
			"type": "npm",
			"name": "reactNpm",
			"package": "react",
			"version": "latest"
		}
	]
}
```

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

### Start Mintlify dev server

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/README.md

Run the Mintlify development server at the root of your documentation where docs.json is located. View the local preview at http://localhost:3000.

```bash
mint dev
```

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

### Run dev server directly from apps/web

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/web/README.md

Run this command from the apps/web directory to start the development server.

```sh
bun run dev
```

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

### Start local server and set environment variables

Source: https://github.com/davis7dotsh/better-context/blob/main/SMOKE_TESTS.md

Start the btca server on port 8080 in Terminal A. In Terminal B, set the SERVER_URL and SMOKE_RESOURCE environment variables. Expected: Terminal A prints 'btca server running at http://localhost:8080'.

```bash
bun run apps/cli/src/index.ts serve --port 8080
```

```bash
export SERVER_URL=http://127.0.0.1:8080
export SMOKE_RESOURCE="smoke-local-$(date +%s)"
```

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

### Advanced configuration example

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/ai-tools/cursor.mdx

JavaScript object showing performance and security settings. Used in the 'Advanced configuration' accordion.

```javascript
const config = {
  performance: { cache: true, timeout: 30000 },
  security: { encryption: 'AES-256' }
};
```

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

### GET /resources

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/server/README.md

Lists all configured resources (local directories or git repositories).

```APIDOC
## GET /resources

### Description
Lists all configured resources (local directories or git repositories).

### Method
GET

### Endpoint
/resources

### Response
#### Success Response (200)
- **resources** (array) - List of configured resources

#### Response Example
{
  "resources": []
}
```

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

### Add a repository to btca

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/guides/quickstart.mdx

Adds a repository by name and URL. Example adds svelte-dev from GitHub.

```bash
btca add -n svelte-dev https://github.com/sveltejs/svelte.dev
```

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

### Run the local btca server

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/guides/quickstart.mdx

Starts the local HTTP API server on port 8080 by default.

```bash
btca serve
```

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

### YAML frontmatter example

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/ai-tools/cursor.mdx

Required YAML frontmatter for every documentation page, including title and description fields.

```yaml
---
title: 'Clear, specific, keyword-rich title'
description: 'Concise description explaining page purpose and value'
---
```

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

### OpenAPI property examples

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/essentials/settings.mdx

Shows three ways to set the openapi property: absolute URL, relative path, or an array of URLs/paths.

```json
"openapi": "https://example.com/openapi.json"
```

```json
"openapi": "/openapi.json"
```

```json
"openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
```

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

### Server options

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/cli/README.md

Use an existing server or specify port for auto-started server.

```bash
# Use an existing btca server
btca --server http://localhost:3000
```

```bash
# Specify port for auto-started server
btca --port 3001
```

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

### btca ask usage examples

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/web/static/docs/example-AGENTS-section.md

Examples of btca ask with single resource, multiple resources, and @mentions in the question.

```bash
# Single resource
btca ask -r svelte -q "How do stores work in Svelte 5?"

# Multiple resources  
btca ask -r svelte -r effect -q "How do I integrate Effect with Svelte?"

# Using @mentions in the question
btca ask -q "@svelte @tailwind How do I style components?"
```

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

### Create the btca-sandbox snapshot

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/sandbox/README.md

Creates a Debian-based snapshot named btca-sandbox with bun, btca CLI, and opencode CLI pre-installed. This is a one-time setup step; subsequent sandbox startups will be faster.

```bash
bun snapshot
```

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

### GET /providers response

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/btca.spec.md

Response for the GET /providers endpoint. Lists all supported providers and which ones are currently connected.

```json
{
	"all": [
		{ "id": "opencode", "models": {} },
		{ "id": "openrouter", "models": {} }
	],
	"connected": ["opencode"]
}
```

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

### Initialize btca in project

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/guides/quickstart.mdx

Run from repo root. The wizard creates btca.config.jsonc for local usage.

```bash
btca init
```

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

### footerSocials JSON example

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/essentials/settings.mdx

Example of the footerSocials property, an object mapping social media platform keys to account URLs.

```json
{
  "x": "https://x.com/mintlify",
  "website": "https://mintlify.com"
}
```

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

### GET /resources response

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/btca.spec.md

Response for the GET /resources endpoint. Lists configured resources with their type, location, and optional notes.

```json
{
	"resources": [
		{
			"name": "svelte",
			"type": "git",
			"url": "https://github.com/sveltejs/svelte.dev",
			"branch": "main",
			"searchPath": "apps/svelte.dev",
			"searchPaths": null,
			"specialNotes": "..."
		},
		{
			"name": "internal-docs",
			"type": "local",
			"path": "/abs/path/docs",
			"specialNotes": null
		}
	]
}
```

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

### Quick Copy-Paste Setup Prompt

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/web/static/docs/SETUP_PROMPT.md

Quick copy-paste prompt for setting up btca. Instructs the agent to scan package.json, present a resource list, wait for confirmation, then prepare btca.config.jsonc for approval before creating files.

```text
Set up btca for this project: scan package.json for major dependencies (frameworks, libraries, tools), then show me the full list of resources you'd suggest. Once I confirm the list, prepare the btca.config.jsonc with all resources and show it to me for approval before creating files. Work in batches, not one-by-one.
```

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

### Single code block example (config.js)

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/ai-tools/cursor.mdx

Example of a single code block in the rules file, showing a JavaScript configuration object for an API client.

```javascript
const apiConfig = {
	baseURL: 'https://api.example.com',
	timeout: 5000,
	headers: {
		Authorization: `Bearer ${process.env.API_TOKEN}`
	}
};
```

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

### List resources

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/cli/README.md

List configured resources.

```bash
btca resources
```

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

### Install Claude Code globally

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/ai-tools/claude-code.mdx

Installs Claude Code globally via npm. Requires an active Claude subscription (Pro, Max, or API access).

```bash
npm install -g @anthropic-ai/claude-code
```

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

### Configure environment with .env file

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/ai-tools/cursor.mdx

Example of creating a .env file with an API key, shown inside a Step component. Includes a warning not to commit API keys to version control.

```bash
API_KEY=your_api_key_here
```

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

### Start and stop the BTCA server

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/server/README.md

Shows how to start the server with default options, custom port, quiet mode, and stop it. The default port is 8080 or process.env.PORT.

```typescript
import { startServer } from 'btca-server';

// Start with default options (port 8080 or process.env.PORT)
const server = await startServer();
console.log(`Server running at ${server.url}`);

// Start with custom port
const server = await startServer({ port: 3000 });

// Start with quiet mode (no logging)
const server = await startServer({ port: 3000, quiet: true });

// Stop the server when needed
server.stop();
```

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

### GET /config response

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/btca.spec.md

Response for the GET /config endpoint. Returns the current configuration including provider, model, timeout, resources directory, and resource count.

```json
{
	"provider": "opencode",
	"model": "claude-haiku-4-5",
	"providerTimeoutMs": 300000,
	"resourcesDirectory": "/abs/path/resources",
	"resourceCount": 3
}
```

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

### Resource List Presentation Format

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/web/static/docs/SETUP_PROMPT.md

Example output format for presenting the full resource list after scanning dependencies. Includes a note that resource names should be camelCase (e.g., drizzleOrm, not drizzle-orm).

```text
Found these dependencies that would benefit from btca:

1. svelte - Svelte framework docs and source
2. tailwind - Tailwind CSS documentation
3. effect - Effect-TS library docs
4. drizzleOrm - Drizzle ORM documentation
... etc

Note: Resource names should be camelCase (e.g., drizzleOrm, not drizzle-orm).

Does this list look good, or would you like to add/remove any?
```

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

### MCP tools/call Example Payload

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/btca.spec.md

Example JSON-RPC 2.0 payload for the MCP endpoint POST /api/mcp. The method is tools/call with the tool name ask, and arguments include a question, resources array, and project name.

```json
{
	"jsonrpc": "2.0",
	"id": 1700000000000,
	"method": "tools/call",
	"params": {
		"name": "ask",
		"arguments": {
			"question": "...",
			"resources": ["svelte"],
			"project": "default"
		}
	}
}
```

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

### btca ask command

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/web/static/docs/example-AGENTS-section.md

Query one or more configured resources. Replace <resource> with a resource name and <question> with your query.

```bash
btca ask -r <resource> -q "<question>"
```

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

### Add and list a local resource

Source: https://github.com/davis7dotsh/better-context/blob/main/SMOKE_TESTS.md

Add the current repo as a disposable local resource and list resources. Expect add to succeed without prompts/errors and the resource to show as (local) pointing at the repo.

```bash
bun run apps/cli/src/index.ts add . --name "$SMOKE_RESOURCE" --type local --server "$SERVER_URL"
bun run apps/cli/src/index.ts resources --server "$SERVER_URL"
```

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

### GET /

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/docs/btca.spec.md

Health check endpoint for the btca-server.

```APIDOC
## GET /

### Description
Health check endpoint for the btca-server.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates the service is running.
- **service** (string) - Service name.
- **version** (string) - Service version.

#### Response Example
{
  "ok": true,
  "service": "btca-server",
  "version": "0.0.1"
}
```

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

### Set model

Source: https://github.com/davis7dotsh/better-context/blob/main/apps/cli/README.md

Configure the provider and model using the connect command.

```bash
btca connect --provider opencode --model claude-haiku-4-5
```