docs: align getting-started, guides, understand, and reference docs

Documentation/getting-started/first-slice.md

@@ -0,0 +1,85 @@
+---
+title: Run Your First Slice
+description: See a slice go from Planned to Done with the Eventmodelers Build Kit - Java
+tableOfContents: false
+---
+
+# Run Your First Slice
+
+This walkthrough shows a slice going from `Planned` on your Eventmodelers board to a tested, working Cratis vertical slice in your Java project — with no manual coding in between.
+
+## Prerequisites
+
+[Install the kit](install.md) and [connect it to a board](../guides/connect-a-board.md) first. The loop needs a running agent (`node .build-kit/ralph-claude.js`) and valid credentials in `.eventmodelers/config.json`.
+
+## Look at the example slice first
+
+Every install ships a working example under `SomeModule/SomeFeature/` — a `Registration` slice (a command and its event) and a `Listing` slice (a projection and read model). Open them before you build your own; they show every convention the kit's build skills reproduce:
+
+- One type per slice, with the command/event/reactor together
+- `@Command`/`@EventType`-style artifacts with a `handle()`-shaped method that returns the event
+- The React screen and command wiring in `.tsx`/`.ts` files beside them
+
+## Start the loop
+
+```bash
+node .build-kit/ralph-claude.js
+```
+
+The loop polls for two independent triggers — see [Understanding the Loop](../understand/the-loop.md) — and idles quietly until one fires.
+
+## 1. Mark a slice `Planned` on your board
+
+On [app.eventmodelers.ai](https://app.eventmodelers.ai), create or open a slice and set its status to `Planned`. For example, a "Register Author" slice might look like:
+
+```json
+{
+  "id": "slice-123",
+  "title": "Register Author",
+  "status": "Planned",
+  "contextName": "Authors",
+  "sliceType": "StateChange",
+  "commands": ["RegisterAuthor"],
+  "events": ["AuthorRegistered"],
+  "description": "Register a new author with name and email"
+}
+```
+
+## 2. The kit fetches and persists the slice
+
+The real-time subscription picks up the status change and saves the definition to `.build-kit/.slices/Authors/register-author/slice.json`.
+
+## 3. The kit generates the vertical slice
+
+Because the slice only carries `commands`/`events` (no `processors`, no `projections`/`queries`), the loop routes to the `build-state-change` skill, which generates `Authors/Registration/RegisterAuthor.java`:
+
+```java
+@Command
+@AllowAnonymous
+public record RegisterAuthor(@CommandKey String id, String name) {
+    public AuthorRegistered handle() {
+        return new AuthorRegistered(new AuthorName(name));
+    }
+}
+
+@EventType
+public record AuthorRegistered(AuthorName name) {
+}
+```
+
+## 4. The kit builds and tests the slice
+
+```bash
+./gradlew build
+./gradlew test
+```
+
+## 5. The kit updates the board to `Done`
+
+Once the build and tests pass, the kit calls back to the platform and marks the slice `Done` — closing the loop without you touching an editor.
+
+## What's next
+
+- Try a slice with `projections`/`readModel` set — it routes to `build-state-view` instead
+- Try a slice with `processors` set — it routes to `build-automation`
+- If a slice gets stuck in `InProgress`, check the loop's terminal output, confirm `./gradlew build` succeeds locally, then re-run the loop

Documentation/getting-started/install.md

@@ -29,12 +29,12 @@ npx github:Cratis/Eventmodelers-Build-Kit-Java install
 
 This will:
 
-1. Copy the **Cratis starter app** (Java backend with Arc + Chronicle, example slice, shared React frontend) into your project root
+1. Copy the **Cratis starter app** (Java backend with Arc + Chronicle, an example slice, and the shared React frontend) into your project root
 2. Create a `.build-kit/` directory with the agent loop and skills
 3. Install Node.js dependencies for the loop
 4. Add `.build-kit/` to your `.gitignore`
 5. Create `.eventmodelers/config.json` in your project root
-6. Configure MCP server in `.build-kit/.claude/settings.json`
+6. Configure the MCP server in `.build-kit/.claude/settings.json`
 
 ### Option 2: Upstream CLI with Git Stack
 
@@ -58,8 +58,8 @@ The installer prompts for your Eventmodelers credentials:
   Token:
 ```
 
-Get these from [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account). You can skip
-them and configure later — see the `connect` skill.
+Get these from [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account). You can skip any
+field and configure it later — see [Connect a Board](../guides/connect-a-board.md).
 
 ## After Installation
 
@@ -69,17 +69,79 @@ Start the agent loop:
 node .build-kit/ralph-claude.js
 ```
 
+Or, using a local Ollama model (run `ollama serve` first):
+
+```bash
+OLLAMA_MODEL=qwen3:8b node .build-kit/ralph-ollama.js
+```
+
 Verify the installation:
 
 ```bash
 npx github:Cratis/Eventmodelers-Build-Kit-Java status
 ```
 
-Build and run the starter:
+You should see:
+
+```
+.build-kit Status
+
+Kit dir:        ✅ installed
+Skills:         ✅ installed
+Config (root):  ✅ present
+Config (kit):   ✅ present
+
+Connected to: https://api.eventmodelers.ai
+Organization: <your-org-id>
+Board:        <your-board-id>
+```
+
+Build and run the starter app:
 
 ```bash
-docker-compose up -d   # Chronicle development kernel
-./gradlew build        # backend
-./gradlew bootRun      # run the backend (http://localhost:8080)
-npm install && npm run dev   # frontend dev server
+docker-compose up -d           # Chronicle development kernel
+./gradlew build                # backend
+./gradlew bootRun              # run the backend (http://localhost:8080)
+npm install && npm run dev     # frontend dev server (http://localhost:5173)
 ```
+
+## Next Steps
+
+Now that the kit is installed:
+
+1. [Connect your Eventmodelers board](../guides/connect-a-board.md)
+2. [Mark a slice as `Planned`](https://app.eventmodelers.ai) on your board
+3. [Run the kit](first-slice.md) to implement the slice
+
+## Troubleshooting
+
+### Installation Fails
+
+If installation fails:
+
+1. Check the Node.js version: `node --version` (should be 18+)
+2. Ensure you're in a valid project directory
+3. Check network connectivity
+4. Try running with elevated permissions if needed
+
+### Config Not Found
+
+If the kit can't find your config:
+
+1. Verify `.eventmodelers/config.json` exists in your project root
+2. Check that the JSON is valid: `cat .eventmodelers/config.json | jq .`
+3. Ensure your credentials are correct: [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account)
+
+### MCP Server Not Configured
+
+If MCP server configuration fails:
+
+1. Check that `.build-kit/.claude/settings.json` exists
+2. Verify the `mcpServers.eventmodelers` entry is present
+3. Restart Claude Code after installation
+
+## See Also
+
+- [Connect a Board](../guides/connect-a-board.md)
+- [Run Your First Slice](first-slice.md)
+- [CLI Commands](../reference/cli-commands.md)

Documentation/guides/connect-a-board.md

@@ -0,0 +1,94 @@
+---
+title: Connect a Board
+description: Set up Eventmodelers board credentials for the Build Kit - Java
+tableOfContents: false
+---
+
+# Connect a Board
+
+The kit needs three values to talk to your Eventmodelers board: an **organization ID**, a **board ID**, and an API **token**. This guide covers getting them, where they're stored, and how to change them later.
+
+## Get your credentials
+
+1. Sign in at [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account)
+2. Generate an API token in your workspace settings — it is a UUID and is **shown only once**, so copy it immediately
+3. Note your **organization ID** (from your organization settings) and the **board ID** (from the board's URL)
+
+## Option 1: During installation
+
+The installer asks for credentials interactively:
+
+```
+🔑 Enter your Eventmodelers credentials (press Enter to skip any field):
+
+  Organization ID:
+  Board ID:
+  Token:
+```
+
+Paste each value, or press Enter to skip and connect later.
+
+## Option 2: With the `connect` skill
+
+If you skipped credentials at install time, or need to change them later, use `/connect` inside Claude Code. The skill:
+
+1. Checks for inline overrides (`board=<uuid>`, `token=<uuid>`, `org=<uuid>`, `baseUrl=<url>`) in the prompt that invoked it
+2. Falls back to `.eventmodelers/config.json` for any value not overridden
+3. Asks you for anything still missing, one field at a time
+4. Writes the resolved config back to disk
+
+Every other skill in the kit (`build-state-change`, `build-state-view`, `build-automation`, `load-slice`, `update-slice-status`) calls `connect` first, so you never have to wire credentials into each one individually.
+
+## Where credentials live
+
+The installer writes the same config to two places:
+
+| Location | Purpose |
+|---|---|
+| `.eventmodelers/config.json` (project root) | The primary config, checked first |
+| `.build-kit/.eventmodelers/config.json` (kit directory) | An optional override, checked second |
+
+Resolution order is **inline parameter > project-root config > kit-directory config > ask the user**. Both files are excluded from version control automatically.
+
+The config shape is:
+
+```json
+{
+  "organizationId": "<uuid>",
+  "boardId": "<uuid>",
+  "token": "<uuid>",
+  "baseUrl": "https://api.eventmodelers.ai"
+}
+```
+
+`baseUrl` defaults to `https://api.eventmodelers.ai` and only needs to be set explicitly when pointing at a self-hosted or local instance.
+
+## Verify the connection
+
+```bash
+npx github:Cratis/Eventmodelers-Build-Kit-Java status
+```
+
+A working connection prints the organization and board the kit is currently pointed at:
+
+```
+Connected to: https://api.eventmodelers.ai
+Organization: <your-org-id>
+Board:        <your-board-id>
+```
+
+## Rotate or change credentials
+
+Run `/connect` again with an inline override to switch boards without editing files by hand:
+
+```
+/connect board=<new-board-uuid>
+```
+
+Or edit `.eventmodelers/config.json` directly and restart the loop.
+
+## See Also
+
+- [Install the Kit](../getting-started/install.md)
+- [Run Your First Slice](../getting-started/first-slice.md)
+- [CLI Commands](../reference/cli-commands.md)

Documentation/index.md

@@ -14,16 +14,17 @@ When a slice is marked `Planned` on your Eventmodelers board, this kit automatic
 
 1. **Connects** to the Eventmodelers Platform in real-time
 2. **Fetches** the slice definition and board context
-3. **Generates** a complete Cratis vertical slice (commands, events, read models, React components)
+3. **Generates** a complete Cratis vertical slice (commands, events, projections, read models, React components)
 4. **Builds** the slice with `./gradlew build` and runs tests with `./gradlew test`
 5. **Updates** the board status to `Done` when complete
 
 The entire process happens automatically, with your Claude agent implementing the slice according to Cratis best practices.
 
 ## Where to Start
 
-- **[Getting Started](getting-started/)** — Install the kit and run your first slice from Planned to Done
-- **[Install the Kit](getting-started/install.md)** — The installer, step by step
+- **[Install the Kit](getting-started/install.md)** — Get up and running in five minutes
+- **[Run Your First Slice](getting-started/first-slice.md)** — Watch a slice go from `Planned` to `Done`
+- **[Connect a Board](guides/connect-a-board.md)** — Wire the kit up to your Eventmodelers board
 
 ## How It Works
 
@@ -38,11 +39,15 @@ The kit implements the [Eventmodelers Build Kits platform contract](https://gith
    - `projections`/`queries`/`readModel` → `build-state-view` (read models)
    - Otherwise (`commands`/`events`) → `build-state-change` (commands/events)
 4. **Cratis conformance** — Generated slices follow Cratis best practices:
-   - One slice folder per slice (one public type per file) with `@Command` and `@EventType`
-   - `ConceptAs<T>` for identities and values in events and read models
-   - Read models exposed as Arc queries with `@Path`
+   - One public type per file (one slice folder per slice) — command, event, and reactor sit together
+   - `@Command` records carry a `handle()` method — no separate handler class
+   - `@EventType` records use past-tense, self-describing names
+   - `ConceptAs<T>` wraps identities and values in events and read models instead of raw primitives
+   - Read models are exposed as Arc queries annotated with `@Path`
    - Package mirrors the folder structure
 
+See [Understanding the Loop](understand/the-loop.md) for the full mechanics.
+
 ## Place in the Cratis Ecosystem
 
 This kit sits between the [Eventmodelers Platform](https://app.eventmodelers.ai) and [Cratis](https://cratis.dev):
@@ -61,6 +66,12 @@ Install from git (this package is private, so use the git install path):
 npx github:Cratis/Eventmodelers-Build-Kit-Java install
 ```
 
+Or use the upstream CLI with this repository as a git stack:
+
+```bash
+npx @eventmodelers/cli init --stack cratis-java --git https://github.com/Cratis/Eventmodelers-Build-Kit-Java
+```
+
 After installation, run:
 
 ```bash
@@ -70,6 +81,13 @@ node .build-kit/ralph-claude.js
 ## Next Steps
 
 1. [Install the kit](getting-started/install.md)
-2. Connect your Eventmodelers board credentials
-3. Mark a slice as `Planned` on your board
-4. Watch the kit automatically implement it as a Cratis vertical slice
+2. [Connect your Eventmodelers board](guides/connect-a-board.md)
+3. [Mark a slice as `Planned`](https://app.eventmodelers.ai) on your board
+4. Watch the kit automatically implement it as a Cratis vertical slice — see [Run Your First Slice](getting-started/first-slice.md)
+
+## See Also
+
+- [Understanding the Loop](understand/the-loop.md) — How the two triggers work independently
+- [CLI Commands](reference/cli-commands.md) — `install`, `uninstall`, and `status`
+- [Cratis Conventions](https://github.com/Cratis/Eventmodelers-Build-Kit-Java/tree/main/templates/.claude/skills/_shared/cratis-conventions.md) — The conventions the kit enforces, generated from the Cratis AI corpus
+- [Eventmodelers Build Kits platform contract](https://github.com/Nebulit-GmbH/Eventmodelers-Build-Kits) — The platform skills the kit uses