werkator/docs/prs/2026-09-08-PR#36-llms-documentation.md

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).