> **WARNING:** This document describes only the change applied in this PR.
> It may already be outdated once the next PR is merged.
> Historic PR-documentation is not maintained along with new PRs — treat it as a snapshot, not as current documentation.

## The Problem

Werkator is a complex build system with multiple components, configuration layers, build runtimes, and APIs.
AI coding agents working on the Werkator codebase need to understand its architecture, configuration, features, and interfaces to make informed changes and avoid breaking invariants.

Without dedicated documentation for agents, they must piece together understanding from scattered sources:
- The technical deep-dive in `AGENTS.md`
- User-facing guides like `configuration.md` and `bootstrapping.md`
- The ADR collection in `docs/adrs/`
- Source code inspection

This is inefficient and error-prone.
An agent might miss critical constraints like the branch-layer pinning rule, the hard invariants about worktree layout, or the multi-layer configuration merging strategy.

## Non-Goals

- Not a replacement for `configuration.md` — this is agent-focused, that is user-focused.
- Not a replacement for `AGENTS.md` — this covers what the system *does* and *exposes*, that covers how to *work* on it.
- Not a user guide or tutorial — agents do not need onboarding.
- No behavioral changes to Werkator itself.

## The Scenarios

### Feature: an agent can understand Werkator's architecture from one document

#### Scenario#36.01: An agent understands the system at a glance

So that it can navigate the codebase and predict where changes belong.

- **Given** an agent new to the Werkator codebase
- **When** it reads `docs/llms.md`
- **Then** it understands:
  - What Werkator does (git-centric CI/CD, builds on native/Docker/werkdock, status reporting)
  - Its dual-mode operation (CLI and Server)
  - The five-layer configuration merging strategy
  - The package structure and responsibilities
  - Hard invariants (no primary-checkout builds, one build per branch, RepoContext scope)

##### Verified by

- Manual review of the documentation structure and completeness.

#### Scenario#36.02: An agent can make configuration changes correctly

So that it does not accidentally set pinned keys, breaks inheritance rules, or misunderstands layer precedence.

- **Given** an agent tasked with modifying build configuration
- **When** it reads the configuration reference in `docs/llms.md`
- **Then** it knows:
  - Which keys belong to which config layer (instance, project, machine, branch)
  - Which keys are pinned and cannot be overridden by branches
  - How inheritance from `builds.default` works
  - The exact default values for every setting

##### Verified by

- Manual review of the configuration reference section.

#### Scenario#36.03: An agent understands build execution without reading source code

So that it can predict build behavior and troubleshoot failures.

- **Given** an agent debugging a build issue
- **When** it reads the "Build Execution" and "Build Definitions and Triggering" sections
- **Then** it understands:
  - How branch worktrees are created and reused
  - The three build runtimes and their differences
  - How `.git` is masked to prevent credential leaks
  - How trigger rules work (onPush, atTimes, branch selectors)
  - The pull-request gate and its implementation (git ls-remote, not API)

##### Verified by

- Manual review of the build execution documentation.

#### Scenario#36.04: An agent can interact with Werkator programmatically

So that it can query build status, retrieve artifacts, and trigger builds without reading the API implementation.

- **Given** an agent tasked with integrating another system with Werkator
- **When** it reads the "JSON API" and "Common Patterns for Agents" sections
- **Then** it knows:
  - The endpoint URLs and methods (GET, POST)
  - The response JSON structure and field meanings
  - How to query status, trigger builds, retrieve artifacts
  - How to detect build failures, understand build times, work with multi-build workflows

##### Verified by

- Manual review of the JSON API reference and patterns sections.

#### Scenario#36.05: An agent understands deployment without operator knowledge

So that it can make deployment-aware code changes (e.g., systemd service, runtime bundle).

- **Given** an agent tasked with modifying deployment behavior
- **When** it reads the "Deployment" section and the links to `deployment.md`
- **Then** it knows:
  - How Werkator is deployed (systemd service, reverse proxy, optional managed nginx)
  - The runtime bundle for hosts without Java
  - The Hostsharing-specific patterns

##### Verified by

- Manual review of the deployment section and links.

## The Solution

A single, dense, agent-focused document: `docs/llms.md`.

The document covers in this order:

1. **System Overview** — what Werkator is and does at a glance.
2. **Architecture** — package structure (all packages under `de.hoennig.werkator` with one-line purpose), key invariants (five hard rules that must never be violated).
3. **Configuration** — the five layers, config file locations (table), complete reference of every top-level key with defaults, runtime inspection commands.
4. **Features** — detailed description of each capability:
   - Build execution (three runtimes, worktree management, concurrency, git masking)
   - Build definitions and triggering (named builds, inheritance, pinning, trigger types)
   - Watcher (polling, startup recovery, per-context guards)
   - Artifacts (retention, latest-green links, serving)
   - Metrics (sampling, JSON API exposure)
   - Web UI (server-rendered, drop-down navigation, no auth)
5. **CLI Commands** — one heading per command (`init`, `build`, `retry`, `status`, `server`, `config:print`), with usage examples and what it does.
6. **JSON API** — endpoint table (URL, method, purpose), response format examples, fields explained.
7. **Common Patterns for Agents** — how to solve typical integration problems (detect failures, retrieve artifacts, check logs, understand timing, work with multi-builds).
8. **Deployment** — brief description, links to `deployment.md`.
9. **Testing and Debugging** — test commands, config inspection, build monitoring.
10. **ADRs** — quick reference to the major decisions and their numbers.
11. **Related Documentation** — links to existing docs that complement this one.

The document is technical and complete, written **for agents**: dense, no tutorials, every statement is precise and verifiable against the code.

## Additional Changes

- None beyond the new file.

## Follow-up PRs

- If new features are added to Werkator (e.g., new CLI commands, new config keys, new API endpoints), this document must be updated alongside the feature — it is part of the feature's public interface for agents.
- Consider adding `docs/llms.md` to the pre-commit CI checks to verify it stays in sync with configuration.md and ADRs (optional, deferred).