> ## Documentation Index
> Fetch the complete documentation index at: https://lab.pollack.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Install Bud and build your first Spring Boot project

## Prerequisites

* **Java 21+** on PATH
* **An agentic CLI** installed and authenticated (e.g., [Claude Code](https://claude.ai/code), Gemini CLI, Codex)
* **An ACP-compatible IDE** — JetBrains 2026.1+, Zed, VS Code, or any editor with ACP support

## Install from Release

Download the fat JAR from the [v0.4.0 release](https://github.com/markpollack/bud/releases/tag/v0.4.0):

* `bud-acp-server-0.4.0-jar-with-dependencies.jar` — the ACP agent

## Install from Source

```bash theme={null}
git clone https://github.com/markpollack/bud.git
cd bud
./mvnw package -DskipTests
```

This produces:

* `bud-acp-server/target/bud-acp-server-*-jar-with-dependencies.jar`

## Configure JetBrains

Create or edit `~/.jetbrains/acp.json`:

```json theme={null}
{
  "agent_servers": {
    "Bud": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/bud-acp-server-0.4.0-jar-with-dependencies.jar"
      ]
    }
  }
}
```

<Warning>
  Replace `/path/to` with the absolute path where you saved the JAR.
</Warning>

Restart your JetBrains IDE after editing the config.

## Your First Project

1. Open any project in IntelliJ
2. Open **AI Chat** tool window
3. Select **"Bud"** from the agent dropdown
4. Type: `create a REST app called hello-api in /tmp`

Bud will scaffold a complete Spring Boot REST project with:

* `GreetingController` with GET endpoint
* `GreetingService` with business logic
* `ProblemDetail` error handling
* Working tests
* Maven wrapper

## Verify

```bash theme={null}
cd /tmp/hello-api
./mvnw test
```

## What You Can Ask

Bud understands natural language and routes your request to the right approach. Here are tested prompts organized by what Bud does with them.

### Known patterns (instant, no LLM code gen)

These match one of Bud's 9 reference projects — Bud uses proven, working code directly:

| Prompt                                     | Reference Project        |
| ------------------------------------------ | ------------------------ |
| "create a simple spring boot app"          | `spring-boot-minimal`    |
| "create a basic spring boot application"   | `spring-boot-minimal`    |
| "create a greeting api"                    | `spring-boot-rest`       |
| "create a hello world rest service"        | `spring-boot-rest`       |
| "spring boot app with actuator"            | `spring-boot-actuator`   |
| "create an app with health checks"         | `spring-boot-actuator`   |
| "create a batch job"                       | `spring-boot-batch`      |
| "build a CSV processing batch application" | `spring-boot-batch`      |
| "create a scheduled task processor"        | `spring-boot-scheduling` |
| "rest api with security"                   | `spring-boot-security`   |
| "create a secure web application"          | `spring-boot-security`   |
| "create a spring boot app with JPA"        | `spring-boot-jpa`        |
| "create a rest api without database"       | `spring-boot-rest`       |
| "build an api with no database"            | `spring-boot-rest`       |

### Domain apps (LLM-expanded with real business code)

These have specific business entities — Bud scaffolds a base project and expands it with domain models, repositories, services, and controllers:

| Prompt                                         | Domain             |
| ---------------------------------------------- | ------------------ |
| "build a todo api"                             | Todo CRUD          |
| "build a customer management system"           | Customer entities  |
| "create a customer tracking system"            | Customer tracking  |
| "create an inventory management api"           | Inventory          |
| "build an order processing system with JPA"    | Order processing   |
| "create an employee directory application"     | Employee directory |
| "build a product catalog service"              | Product catalog    |
| "build a hotel reservation and booking system" | Reservations       |
| "build an e-commerce backend with payments"    | E-commerce         |

### Edge cases (handled gracefully)

| Prompt                                           | Behavior                                          |
| ------------------------------------------------ | ------------------------------------------------- |
| "spring boot management system"                  | Too vague — builds minimal app, no over-expansion |
| "create a spring boot app with JPA and security" | Multi-capability — picks best match               |

## How It Works

When you send a message to Bud in AI Chat:

1. JetBrains sends the prompt to Bud's ACP agent over stdio
2. Bud's LLM classifier (Sonnet, running on your approved CLI) analyzes the intent — capabilities, domain entities, best-fit reference project
3. The execution planner routes to the right tier:
   * **CACHE** — matches a reference project, uses working code directly
   * **INITIALIZR** — generates via start.spring.io (Boot 3.x, Gradle)
   * **EXPAND** — starts from a reference project, then AI generates domain-specific code
4. Tools execute deterministically — no LLM in the actual scaffolding. Your CLI is only used for classification and domain code generation.
5. Results stream back through ACP to your chat window

The first prompt may take 30-60 seconds (CLI startup + classification + MCP server startup). Subsequent prompts in the same session are faster.