diff --git a/CHANGELOG.md b/CHANGELOG.md
index 718b747..df3a197 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,12 @@ until 1.0, minor versions may contain breaking changes.
- **Factory versioning.** The current version is read from the tags on the forge, not from the checkout
(which kept tags that were deleted there and so counted from a stale version).
+## [Unreleased]
+
+### Changed
+
+- **README:** new "Code factory" section explaining phases, scope, planning chats, versions and releases.
+
## [v202611-00052] – 2026-11-17
### Fixed
diff --git a/README.md b/README.md
index b4c6287..0967554 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@
Models ·
Terminal client ·
Automations ·
+ Code factory ·
Integrations ·
Users ·
Statistics ·
@@ -219,6 +220,90 @@ read and continue it.
**Webhooks** start an automation from outside, e.g. on every push: the request is checked with a
shared secret or a Gitea/GitHub HMAC signature, and its JSON payload is handed to the agent.
+## Code factory
+
+The factory turns issues on your Git forge (Gitea, GitHub or GitLab) into reviewed, built, accepted and
+merged changes – with agents doing the work and you deciding at the points that matter. It is
+the **Factory** page in the sidebar; all chats it creates live in the sidebar folder *Factory*.
+
+```
+issue + label "factory"
+ │
+ ▼
+ review ──► question (the agent asks in the issue; you answer, it continues)
+ │ └──► rejected (not buildable as written)
+ ▼
+ approved ──► building ──► qa (acceptance) ──► done ──► PR merged ──► version + tag ──► closed
+ ▲ │
+ └── rework ◄──┘ (up to N rounds, then failed)
+```
+
+**Phases.** Each phase is a normal CodeCraft chat in the sandbox, so you can open and read it.
+The agent's answer ends with a JSON result that the factory parses; everything else is done by
+the server.
+
+1. **Review.** An agent reads the issue and the repository and decides: *approved*, *question*
+ (it comments in the issue and waits for your reply) or *rejected*. It also writes acceptance
+ scenarios. The scenarios are stored in the factory database and are **never shown to the
+ builder**, so the build cannot be tuned to the test.
+2. **Build.** The builder works in its own git worktree on the branch `factory/issue-`.
+ The server – not the agent – commits, pushes (never forced) and restores the spec file.
+3. **Acceptance.** A different agent checks the pushed branch in a clean checkout against the
+ scenarios, using the repository's `.factory/setup.json` to build and start the app. Each
+ scenario ends as `pass`, `fail`, `unverified` or `out_of_scope`; the verdict comes from these
+ results, not from the model's opinion, and a run without any pass or fail counts as failed.
+ On *pass* the factory opens the pull request (if none is open) and comments a result table
+ in the issue. On *fail* the issue goes back to the build with the findings (*rework*).
+4. **Done, merge, version.** You review the pull request in the factory (diff, description) and
+ merge it there. The factory then pulls the merge, gives the issue its version, commits
+ `VERSION`, pushes an annotated tag, comments on the issue and closes it.
+
+Issue text is treated as data, never as instructions for the factory itself.
+
+**Scope.** An issue body can contain `Spec: ` and `Scope: ` lines. Review,
+build and acceptance then restrict themselves to that deliverable, so a big specification is
+built in small steps instead of one huge run. Without a `Scope:` line the review picks the
+first unbuilt milestone of the spec. `Prerequisite:` lines name what must be merged first.
+
+**Planning with a model.** Three chats help you create issues, without the usual review loop:
+
+- **Spec chat** (*New project*): works out a specification with you and creates the repository
+ with `docs/specs/.md`, the factory setup and the first issues.
+- **Plan a feature**: you describe a feature or a bug; the model asks questions and ends with a
+ list of issues (title, description, scope, prerequisites).
+- **Cut a milestone**: the model splits a milestone of the spec into numbered deliverables
+ (`M2.1 – …`).
+
+*Create issues* shows the proposal for editing and files the issues on the forge. They get the
+`factory` label only if you tick *Start right away*; by default you set the label yourself,
+one after the other, because later issues build on the merged earlier ones.
+
+**Versions and releases.** Every issue that is merged raises the version of the repository
+(starting from the highest `vX.Y.Z` tag): a deliverable of a milestone raises the **patch**
+number (0.0.1, 0.0.2, …); the **last** open deliverable of a milestone (`M.`) raises the
+**minor** number and resets the patch (M1 complete → 0.1.0). Issues without a milestone
+(bugs, features) raise the patch number. The factory writes the `VERSION` file, pushes the tag
+`vX.Y.Z` and closes the issue. The **Release** button turns the current version into a
+release, e.g. 0.x → 1.0.0: it builds what the repository's `.factory/release.json` describes
+(Docker image for amd64 and arm64 pushed to your registry, a source zip, extra files by glob,
+shell commands), tags it and creates the release on the forge with notes from the git log and
+the files attached (Gitea and GitHub).
+
+**Settings per repository** (*Factory → Repositories*, *New repository*): forge connection and token, label
+(default `factory`), parallel runs, allowed issue authors (default: the token's owner), and per
+phase the model, agent (CodeCraft or Claude Code), permission mode, timeout and tries on
+technical failures, plus the number of rework rounds (default 2). Failed or rejected issues
+can be restarted from the board, finished ones are closed with a comment.
+
+**Files in the repository** (all optional, kept in `.factory/`):
+
+| File | Purpose |
+|---|---|
+| `setup.json` | How acceptance installs and starts the app: `install`, `start`, `url` |
+| `release.json` | Recipe for releases: image, platforms, Dockerfile, build args, commands, files |
+
+Repositories are cloned into a separate factory area, not into your workspace, and agents never see the forge API token.
+
## Integrations
- **Telegram:** connect your own bot (*Settings → Account → Telegram*) and use CodeCraft from
diff --git a/web/src/whatsnew.ts b/web/src/whatsnew.ts
index 8844797..3dd189c 100644
--- a/web/src/whatsnew.ts
+++ b/web/src/whatsnew.ts
@@ -3,6 +3,10 @@
* under "unreleased"; scripts/release.sh renames the key to the release version.
*/
export const WHATS_NEW: Record = {
+ unreleased: {
+ en: ["README: new section explaining the code factory"],
+ de: ["README: neuer Abschnitt zur Code-Factory"],
+ },
"202611-00053": {
en: ["Factory: the current version is read from the tags on the forge"],
de: ["Factory: die aktuelle Version wird aus den Tags im Forge gelesen"],