diff --git a/CLAUDE.md b/CLAUDE.md
index a177524..6ceb46c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,7 +22,8 @@ java -jar build/libs/gittally-0.1.0-SNAPSHOT.jar init
 
 ## Architecture
 
-GitTally is a dual-mode application: **CLI** (interactive, status, config) and **Server** (HTTP, persistent). It is currently CLI-only; the server mode is not yet implemented.
+GitTally is a lightweight, declarative CI/CD build system.
+It is a dual-mode application: **CLI** (interactive, status, config) and **Server** (HTTP, persistent). It is currently CLI-only; the server mode is not yet implemented.
 
 ### Entry Point and CLI Wiring
 
@@ -42,9 +43,24 @@ commands/
 
 The web application type is set to `none` in `application.yml`. The `server` subcommand will need to restart the context with a web type when implemented.
 
+### Configuration System
+
+GitTally is configured by two YAML files, deep-merged by `ConfigLoader` (later wins):
+
+1. `.gittally.yml` at the repo root — committed, shared team settings.
+2. `.git/gittally/.gittally.yml` — not committed; machine-specific overrides and secrets (`git.account`, `git.token`).
+
+After merging, `branches.default` is merged into every other named branch entry as its fallback, then the result is bound to the `GitTallyConfig` data classes (`config/GitTallyConfig.kt`), which define the schema and all defaults.
+
+Three places must stay in sync when config keys change: the `GitTallyConfig` data classes, the commented templates generated by `InitCommand`, and the reference in `docs/configuration.md`.
+
+### Git Access
+
+`GitService` shells out to the `git` CLI via `ProcessBuilder` (no JGit). Commands that need repo information take it as a constructor dependency so tests can mock it.
+
 ### Package Structure
 
-All production code lives under `de.hoennig.gittally`. Commands are in the `commands` sub-package. Tests mirror this structure under `src/test/kotlin`.
+All production code lives under `de.hoennig.gittally`, with sub-packages `commands` (picocli subcommands), `config` (YAML config loading and schema), and `git` (git CLI access). Tests mirror this structure under `src/test/kotlin`.
 
 ## Testing Conventions
 
@@ -104,6 +120,12 @@ Write documentation in English in Markdown files.
 In Markdown, use a single line per sentence.
 Keep sentences short.
 
+## Documentation
+
+- `docs/GitTally-Konzept.md` — product concept and target architecture (in German): git-centric CI, builds in Docker, one instance per repository, status reported back to Gitea.
+- `docs/configuration.md` — configuration reference; keep in sync with `GitTallyConfig` and the `init` templates.
+- `docs/bootstrapping.md` — how `init` prepares a repository.
+
 ## Key Architectural Decisions
 
 All major decisions are in `docs/adrs/`. Run `adr-status` (after `source .envrc`) for a one-line summary of each. Decisions in force: