diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
new file mode 100644
index 0000000..5fd3b8b
--- /dev/null
+++ b/.github/workflows/documentation.yml
@@ -0,0 +1,88 @@
+name: Documentation
+
+# Builds the docToolchain microsite from docs/ and publishes it to GitHub Pages.
+# Pull requests build the site but do not publish it.
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'docs/**'
+      - 'docToolchainConfig.groovy'
+      - 'dtcw4'
+      - '.github/workflows/documentation.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'docToolchainConfig.groovy'
+      - 'dtcw4'
+      - '.github/workflows/documentation.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Let a running deployment finish; queue the next one instead of cancelling it.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build microsite
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+
+      # The docToolchain runtime lives outside the repository. Installing it
+      # means a git clone plus a one-time Gradle build, so cache it: the key
+      # changes only when the wrapper (and with it the pinned version) changes.
+      - name: Cache docToolchain runtime
+        id: dtc-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.doctoolchain
+          key: doctoolchain-${{ runner.os }}-${{ hashFiles('dtcw4') }}
+
+      - name: Install docToolchain
+        if: steps.dtc-cache.outputs.cache-hit != 'true'
+        run: ./dtcw4 local install doctoolchain
+
+      - name: Generate site
+        run: ./dtcw4 local generateSite
+
+      - name: Fail if the landing page is missing
+        run: test -s build/docs/microsite/output/index.html
+
+      - name: Upload site as build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: microsite
+          path: build/docs/microsite/output
+          retention-days: 7
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/docs/microsite/output
+
+  deploy:
+    name: Publish to GitHub Pages
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/CLAUDE.md b/CLAUDE.md
index 3d1d9c9..9268517 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -278,3 +278,221 @@ Since responsible-vibe-mcp operates statelessly, provide:
 - **context**: Current situation and what you're trying to determine
 
 Remember: responsible-vibe-mcp guides the development process but relies on you to provide conversation context and follow its instructions precisely.
+
+## Specification
+
+When we talk about a "specification" or "spec", we mean:
+- Persona Use Cases in Cockburn's Fully Dressed format (Primary Actor, Trigger, Main Success Scenario, Extensions, Postconditions) at User Goal level, with Business Rules (BR-IDs)
+- System Use Cases for each technical interface (API endpoint, CLI command, event, file format): input/validation, processing, output/status codes, error responses
+- Activity Diagrams for all flows (not just the happy path)
+- Acceptance criteria in Gherkin format (Given/When/Then)
+- Individual requirements in EARS syntax where applicable (When/While/If/Shall)
+- Supplementary Specifications as needed: Entity Model, State Machines, Interface Contracts, Validation Rules
+
+## Requirements Discovery
+
+Clarify requirements using the Socratic Method:
+- Ask at most 3 questions at a time, challenge assumptions
+- Use MECE to ensure questions cover all areas without overlap
+- Keep asking until you fully understand the requirements
+
+Frame the scope before writing it down:
+- Impact Mapping connects deliverables to business goals and actors — so you build what moves a goal, not just what was asked.
+- User Story Mapping lays stories along the user's journey and exposes a coherent first slice.
+
+Document the result as a PRD (problem, goals, personas, success criteria, scope).
+
+## Architecture Documentation
+
+Architecture documentation follows arc42. Diagrams are C4 via PlantUML's bundled C4-PlantUML standard library (the `!include <C4/...>` stdlib form), not Mermaid. Decisions are Nygard ADRs with a 3-point Pugh matrix. Quality requirements are six-part Quality Attribute Scenarios (Source, Stimulus, Artifact, Environment, Response, Response Measure) with a literal Response Measure.
+
+That is the shared vocabulary. The procedure for actually producing such a document — scaffolding the arc42 with-help template, the cross-section traceability rules, the Chapter 11 Risks-vs-Technical-Debt structure, the ADR-to-risk-ID wiring, and the Chapter 1.2-vs-10 quality-goal marking — lives in the arc42-documentation skill, loaded on demand.
+
+## Crosscutting Concepts
+
+arc42 leaves Chapter 8 open. We require five baseline crosscutting concepts, in this order:
+
+- 8.1 Threat Model — STRIDE; threats get IDs (T-001…).
+- 8.2 Security — every mitigation references the T-IDs it closes.
+- 8.3 Test — testing pyramid; tests trace to Use Cases and Business Rules.
+- 8.4 Observability — logs, metrics, traces, audit trails.
+- 8.5 Error Handling — retry, circuit breaker, fallback, recovery.
+
+Add further Chapter 8.x concepts (persistence, i18n, accessibility, configuration, performance) only when the system actually has that concern.
+
+## Layer Boundaries
+
+At every layer boundary:
+- Expose only well-defined DTOs and contracts — never domain entities
+- Use explicit mapping at every seam
+- Apply Anti-Corruption Layers when integrating external systems
+- Dependency direction points inward (DIP)
+
+## Backlog Management
+
+Create EPICs and User Stories as GitHub issues from the specification.
+- User Stories follow INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
+- Prioritize with MoSCoW (Must/Should/Could/Won't)
+- Mark dependencies between issues
+- Groom the backlog regularly as the project evolves
+
+## Vertical Slicing
+
+Build the first increment as a walking skeleton: a deployable end-to-end slice that wires every architectural layer together and does almost nothing else.
+
+Grow the system as thin vertical slices — each slice cuts through all layers and delivers one small piece of user value. Slices are tracer bullets: kept and refined, never thrown away.
+
+When a technical unknown blocks a slice, run a spike solution first — a timeboxed, throwaway experiment that removes the risk. Spike code is discarded; only its lesson carries into the slice.
+
+## Implement Next
+
+For each issue:
+- Create a feature branch for the EPIC
+- Select next issue from backlog (respect dependencies)
+- Analyze and document analysis as a comment on the issue
+- Implement using TDD (London or Chicago School as appropriate)
+- Each test references its Use Case ID for traceability
+- Beyond example-based tests, write invariant tests: name the property that connects a calculation's inputs to its output and test it over a range of values. Ask which of these tests would still fail if a change altered the units, the granularity, or the cardinality of an input
+- Commit with Conventional Commits, reference issue number
+- Verify the spec and architecture docs against the code: for each structural claim, confirm it still holds. Correct the document, never the code
+- When EPIC is complete, create a Pull Request
+
+## Refactoring
+
+Refactoring targets are named code smells, not a vague urge to "clean up".
+
+For any refactoring that does not complete in one step, use the Mikado Method: attempt the change, note what breaks, revert, and do the prerequisites first — never leave the build broken while you dig.
+
+Refactoring commits change structure only. Behaviour changes go in separate commits, and the test suite stays green at every commit.
+
+## Code Quality
+
+Our code follows:
+- SOLID principles
+- DRY, KISS
+- Ubiquitous Language from Domain-Driven Design (same terms in code as in the specification)
+
+## Quality Review
+
+Quality assurance follows three layers:
+- Code review using Fagan Inspection (structured, systematic, with defined phases)
+- Security review based on OWASP Top 10
+- Architecture review using ATAM (scenario-based tradeoff analysis against quality goals)
+- Use a different AI model or fresh session for reviews to avoid blind spots
+
+## Docs-as-Code
+
+Documentation follows Docs-as-Code according to Ralf D. Müller:
+- AsciiDoc as format, PlantUML for inline diagrams, built by docToolchain
+- Version-controlled, peer-reviewed, and built automatically
+- Plain English according to Strunk & White (or Gutes Deutsch nach Wolf Schneider)
+- Projects following this contract include the `dtcw` wrapper and `docToolchainConfig.groovy` so PlantUML / AsciiDoc actually render.
+
+## Socratic Code Theory Recovery
+
+Recover a program's "theory" (Naur 1985) from source code through recursive question refinement.
+
+- Start with 5 root questions: Q1 Problem/Users, Q2 Specification, Q3 Architecture, Q4 Quality Goals, Q5 Risks.
+
+- The second level of the tree is FIXED, not free. Every run emits exactly these nodes, in this order, even when a node's only leaf is [OPEN] or [ANSWERED: not applicable]:
+  - Q1.1-Q1.6: product identity, primary users, channels, why-built, success metrics, segment priority
+  - Q2.1-Q2.6: actors, use-case catalog, per-interface system specs, data/entity model, acceptance criteria, cross-cutting business rules
+  - Q3.1-Q3.12: the twelve arc42 chapters, in arc42 order
+  - Q4.1-Q4.8: the eight ISO/IEC 25010 characteristics; plus Q4.9: which characteristic has priority
+  - Q5.1-Q5.5: technical debt, security risks, operational risks, dependency/supply-chain risks, scaling/performance risks
+
+- Below the fixed second level, decompose adaptively and code-driven; a node is a leaf only when it can be answered from one specific file:line evidence (a directory is too coarse — decompose further) or definitively marked [OPEN]. Depth tracks code density: a small bounded context yields a shallow tree, a large one a deep tree, capped at four levels below a fixed node. Depth varies between runs — expected.
+
+- Q-IDs are stable: Q3.7 is always Deployment View, in every run, so trees from different runs can be diffed node-by-node.
+
+- Each leaf is [ANSWERED] (with file:line evidence) or [OPEN] (with Category, Ask role, and why it is unanswerable from code).
+
+- Quality is not wholly team knowledge. Derive quality scenarios for the Q4 branch and arc42 Chapter 10 from measurable code behaviour — literal thresholds, timeouts, budgets, the threat catalogue and test concept from Q3.8 — as [ANSWERED] with file:line; never invent target numbers. Only the quality-goal ranking (Q4.9) is [OPEN]. arc42 Chapter 10 carries the derivable scenarios, never just an [OPEN] pointer. Chapter 1.2 names only the top 3-5 quality goals; Chapter 10 covers all eight characteristics — mark each Chapter 10 entry as concretising a Chapter 1.2 top goal or as derived.
+
+- Open Questions are the handoff document: always emit one section per role (Product Owner, Architect, Developer, Domain Expert, Operations), even when a section is empty ("No open questions for this role").
+
+- Two-phase workflow: Phase 1 builds the tree; the team answers the Open Questions; Phase 2 synthesizes documentation from the answered tree.
+
+## Documentation Verification
+
+Verify the documentation against the code, in both directions.
+- Ask what implementation revealed that the documents do not yet say
+- For each structural claim in the architecture and specification documents, confirm that it holds today: module names, class names, file paths, table and column names, enum values, invariants, start commands, and claims of the form "the only place where X happens"
+- List every claim that no longer holds, with document location and code location
+- Never change the code to match the document. The document states an intention, the code states reality. Correct the document, or open an issue where the code is wrong
+- Report how many claims were checked and how many had drifted
+- Make structural claims mechanically verifiable where the project allows it: table names, column names, module paths, enum values. Traceability tooling that only runs forward (every rule has a test) never notices a documented column the schema does not have
+- A structural claim that no test can verify does not belong in the documentation. Either make it verifiable or delete it
+- Run the verification again after the bug-fix loop, before release: fixes change behaviour, and changed behaviour is what makes a correct claim stale
+
+## Concise Response (TLDR)
+
+Responses lead with the conclusion first (BLUF). Keep to essential points. No filler, no preamble. Use short sentences, active voice, and no unnecessary words (Strunk & White).
+
+## Simple Explanation (ELI5)
+
+Explain complex concepts using simple language and everyday analogies. When the explanation feels hard to write, that reveals gaps in understanding — study those areas first (Feynman Technique).
+
+## Explaining and Teaching
+
+When asked to explain or teach something (including "why does X…"), act as a teacher running a dialogue, not a lecture — your goal is that the learner can apply it afterwards, not that you delivered it.
+
+Start by having the learner restate what they already understand (Socratic Method), so you teach the gap, not the whole topic; adjust depth on request (ELI5 / ELI-intern). Keep a short running checklist of what they must grasp — the problem and why it exists, the solution with its design decisions and edge cases, and why it matters — a Definition of Done for understanding, worked one item at a time; for a long or multi-session explanation, persist that checklist as a file so it survives context loss and can be resumed.
+
+Take one small step per turn: fill the gap with questions, not answers; ask, or explain the next smallest piece in a few sentences and then check it — then stop and wait. Never stack several steps in one turn. Lead with why something matters before its mechanics (4MAT), and keep drilling into the why beneath the why — the reasoning behind the design, not just what it does (Naur); cover what and how too.
+
+Check by quizzing, never "makes sense?" — open or multiple-choice questions; for multiple choice, vary which option is correct and don't reveal the answer until the learner has committed. The sharpest check is having them explain it back in their own words (Feynman Technique) or apply it to a fresh case; use a concrete artifact (an example, code, a trace) when it helps. React to the actual answer: if they've got it, advance; if not, give a short targeted hint and re-ask. "Understood" means they can use it on a new case, not recite it (Bloom's Apply, not recall) — don't move on, and don't end, until they've shown that.
+
+Don't announce or walk through the method you're using — let it shape what you do, not what you say. Scale to the question: a small factual ask gets a one-line answer, and the learner can say "just tell me" anytime. If you're unsure of the topic, learn it before teaching.
+
+## Writing Style
+
+Writing follows Gutes Deutsch nach Wolf Schneider (or Plain English according to Strunk & White).
+
+Additionally:
+- Technical terms stay in English (LLM, Prompt, Token, Spec, etc.)
+- Address the reader directly, use first person sparingly but deliberately
+- Use analogies to human thinking to explain technical concepts
+- One thought per paragraph (5-8 sentences is fine)
+- Section headings are statements, not topic announcements
+- First sentence says what the paragraph is about
+- Show code and prompts, don't just claim things work
+- Conclusions make a clear statement — never end with 'it remains exciting'
+
+## TDD, Hamburg Style
+
+Design-led TDD recipe by Ralf Westphal — close the requirements/logic gap before writing code, then test at service boundaries with minimal mocking. Use it when the problem is too complex for pure micro-step Red-Green-Refactor.
+
+- **ACD cycle (Analyze → Design → Code)** precedes the test loop: first model the solution to close the gap between requirements and logic, only then code.
+- **"Right from the start" philosophy** — implement correctly the first time so refactoring is a correction, not routine cleanup.
+- **Service-level testing** — test behind the public API, independent of API technology.
+- **Minimal mocking** — closer to *TDD, Chicago School* than *London School*.
+- **IOSP (Integration Operation Segregation Principle)** — a function is either composition (Integration) or logic (Operation), never both; structural support for simple unit tests.
+- **Deep Work over Small Steps** — accept that some problems can't be sliced into tiny green increments; stay red longer when the design demands it.
+
+Composes: *TDD, London School*, *TDD, Chicago School*, *Red-Green-Refactor*, *IOSP*.
+Sources: https://ralfw.de/hamburg-style-tdd/, https://ralfw.de/tdd-how-it-can-be-done-right/
+
+## Strategic Architecture Analysis
+
+Strategic architecture analysis combines four lenses, each for a different question. Reach for it when evaluating build-vs-buy, assessing architecture fitness for changing requirements, or running a strategic technology-radar review.
+
+Map the value chain with Wardley Mapping to see how each component evolves — what is commodity, what is genesis, and where the strategic differentiation actually sits.
+
+Classify each challenge with the Cynefin Framework — Clear, Complicated, Complex, or Chaotic — so the response fits the domain instead of forcing one playbook onto every problem.
+
+When a decision has a wide solution space, lay the dimensions and their options out in a Morphological Box and combine them deliberately, rather than anchoring on the first design that comes to mind.
+
+Evaluate the shortlisted architectures against the quality goals with ATAM, naming the sensitivity points, the tradeoff points, and the risks each option carries.
+
+When the root cause of a problem stays unclear, drill down with the Five Whys before committing to a direction.
+
+## Presentation Planning
+
+When asked to plan a presentation or talk, act as a planning partner in dialogue, not a slide generator — the goal is a plan the speaker can deliver, built around one audience and one core message.
+
+Elicit the brief with the Socratic Method — a few questions at a time, not a form: who the audience is and what they already know and care about, the single change you want in them (the core message or call to action), the setting and time budget, and the hard constraints. Design against the Curse of Knowledge — assume the audience lacks your context; cut jargon or unpack it.
+
+Shape the content top-down with the Pyramid Principle: one governing message, supported by a few MECE argument groups — no overlap, no gaps. Give the talk a spine with a narrative arc (Three-Act Structure, or Story Circle for a more personal journey): a setup that sets the stakes, a middle that builds through the supporting points, and a resolution that lands the core message. Lead each section with why it matters before the detail (4MAT); open with the bottom line, not a wind-up (BLUF), then earn it.
+
+Produce a plan, not slides: the one-sentence core message, the audience, the arc, and per section the single takeaway plus its evidence and rough timing. Work one part at a time — propose the core message and audience first, check them, then the arc, then fill the sections; stop and wait between steps instead of dumping a full deck. If the speaker says "just draft it", give the whole outline at once. Don't announce the method — let it shape the plan, not the talk about it.
diff --git a/docToolchainConfig.groovy b/docToolchainConfig.groovy
new file mode 100644
index 0000000..6790af1
--- /dev/null
+++ b/docToolchainConfig.groovy
@@ -0,0 +1,53 @@
+// docToolchain configuration for the arc42-generator documentation
+// see https://doctoolchain.org/docToolchain/v4.0.x/ for all options
+
+outputPath = 'build/docs'
+
+inputPath = 'docs'
+
+inputFiles = [
+        [file: 'QUESTION_TREE-arc42-generator.adoc', formats: ['html']],
+        [file: 'OPEN_QUESTIONS-arc42-generator.adoc', formats: ['html']],
+        [file: 'arc42-requirements.adoc', formats: ['html']],
+        [file: 'arc42/arc42-arc42-generator.adoc', formats: ['html']],
+        [file: 'specs/prd-arc42-generator.adoc', formats: ['html']],
+        [file: 'specs/use-cases-arc42-generator.adoc', formats: ['html']],
+        [file: 'specs/backlog-arc42-generator.adoc', formats: ['html']],
+]
+
+taskInputsDirs = [:]
+
+// === microsite (task: generateSite) =========================================
+microsite = [:]
+
+// title in the upper left corner and fallback page title
+microsite.title = 'arc42-generator'
+
+// the landing page ships with the internal theme
+microsite.landingPage = 'landingpage.gsp'
+
+// footer and edit links
+microsite.footerGithub = 'https://github.com/LLM-Coding/arc42-generator'
+microsite.issueUrl = 'https://github.com/LLM-Coding/arc42-generator/issues/new'
+microsite.gitRepoUrl = 'https://github.com/LLM-Coding/arc42-generator/edit/master/docs/'
+microsite.footerText = '<small class="text-white">built with docToolchain</small>'
+
+// Menu entries come from the :jbake-menu: attribute of each document.
+// The include fragments below are rendered as pages but must not appear in the
+// menu: arc42 chapters, the help style and the ADR records all live inside
+// their parent document.
+microsite.menu = [
+        architecture : 'Architecture',
+        prd          : 'Product',
+        spec         : 'Specification',
+        backlog      : 'Backlog',
+        questiontree : 'Question Tree',
+        openquestions: 'Open Questions',
+        legacy       : 'arc42 Requirements',
+        src          : '-',
+        common       : '-',
+        adrs         : '-',
+        arc42        : '-',
+        specs        : '-',
+        doc          : '-',
+]
diff --git a/docs/OPEN_QUESTIONS-arc42-generator.adoc b/docs/OPEN_QUESTIONS-arc42-generator.adoc
new file mode 100644
index 0000000..cc9aeaf
--- /dev/null
+++ b/docs/OPEN_QUESTIONS-arc42-generator.adoc
@@ -0,0 +1,133 @@
+= Socratic Code Theory Recovery: Open Questions — arc42-generator
+:jbake-menu: openquestions
+:jbake-title: Open Questions
+:jbake-type: page
+:jbake-status: published
+:toc: left
+:sectnums:
+
+Bounded context:: `arc42-generator` (whole repository, working tree at commit `6672693`)
+Phase:: 1 of 2. These nine questions are the handoff. Phase 2 synthesizes PRD, specification,
+arc42 document and ADRs only after they are answered.
+Source:: Every question is copied verbatim from `QUESTION_TREE-arc42-generator.adoc`, where it
+carries its Q-ID and the code evidence around it.
+How to answer:: One to three sentences per question, written back into this file under the
+question.
+
+== Product Owner
+
+=== Q1.5.3 Adoption metric
+Category: business-context.
+
+No download counter, telemetry, or target figure exists anywhere in the repository. Whether
+success is measured in downloads, languages covered, or formats supported cannot be derived.
+
+*Answer:* Der Release-Aufwand ist die Kennzahl. Erfolgreich ist der Generator, wenn ein Maintainer ein
+neues Template-Release ohne Handarbeit und ohne Spezialwissen herausbringt. Download-Zahlen
+werden nicht erhoben.
+
+=== Q1.6.3 Why that ranking?
+Category: business-context.
+
+The code guards EN and DE (`test-discovery.groovy:79`) and validates only EN Markdown
+(`build-arc42.sh:89`); images are checked for five formats (`build-arc42.sh:124`). Which
+languages and formats the community actually uses — and therefore which ones must never break —
+is not derivable from the code.
+
+*Answer:* EN und DE sind die Referenz: Core-Committer pflegen sie, alle Übersetzungen richten sich nach
+ihnen. Deshalb sichern die Tests genau diese beiden ab. Community-Sprachen dürfen nachziehen.
+
+== Architect
+
+=== Q1.4.3 Why not simply keep Gradle?
+Category: design-rationale.
+
+The code records the outcome, never the decision. Whether speed, the "chicken-and-egg problem"
+mentioned in `CLAUDE.md:120`, or maintainer skill set drove the rewrite is not derivable.
+
+*Answer:* Gradle wurde in der alten Fassung falsch eingesetzt: der erste Durchlauf erzeugte die
+Build-Skripte für den zweiten. Diese Zwei-Stufen-Konstruktion trieb die Komplexität hoch und
+wurde deshalb beseitigt. Die Build-Zeit war Folge, nicht Grund.
+
+=== Q3.8.1.1 Is a threat catalogue present?
+Category: design-rationale.
+
+No STRIDE analysis, no threat IDs, no security section exists in any document in the repository.
+Which threats the build is expected to withstand — hostile template content, a compromised
+upstream repository, a poisoned Pandoc download — must come from you.
+
+*Answer:* Kein Threat-Katalog, bewusst. Security spielt für diesen Build eine sehr untergeordnete Rolle:
+Ein- und Ausgabe sind öffentliche Open-Source-Inhalte, der Build läuft auf Maintainer-Rechnern,
+und es gibt weder Nutzerdaten noch einen laufenden Dienst. Die im Code belegten Punkte
+(`SafeMode.UNSAFE`, ungeprüfte Downloads, `safe.directory '*'`) sind damit akzeptierte Risiken,
+keine offenen Befunde. Für arc42 Kapitel 8.1 heißt das: STRIDE-Katalog entfällt, die
+Risikoakzeptanz wird als Entscheidung dokumentiert.
+
+=== Q3.8.2.3 Why was UNSAFE chosen?
+Category: design-rationale.
+
+`SafeMode.UNSAFE` is set at all three AsciidoctorJ call sites (`lib/Converter.groovy:100`,
+`:132`, `:311`). Whether UNSAFE is required for the template's own includes or was chosen to
+avoid debugging path errors is not derivable.
+
+*Answer:* Bequemlichkeit. `SafeMode.UNSAFE` erspart das Debuggen von Pfad- und Safe-Mode-Fehlern; ob
+`SERVER` oder `SAFE` ebenfalls genügen würden, ist nie geprüft worden. Zusammen mit der
+Risikoakzeptanz aus Q3.8.1.1 bleibt die Einstellung, wie sie ist — als bewusste Entscheidung,
+nicht als Befund.
+
+=== Q4.9 Which characteristic has priority?
+Category: quality-goals.
+
+The code guards performance and functional suitability with measurements, and leaves security
+and reliability to defaults. Whether that ranking is intended or accidental cannot be read from
+the code.
+
+*Answer:* Zuverlässigkeit hat Vorrang. Ein Build, der still Kapitel verschluckt (`lib/Converter.groovy:345`)
+oder Erfolg meldet, obwohl Konvertierungen scheiterten (`lib/Converter.groovy:437-440` mit
+`build.groovy:211-215`), ist das größte Problem — schwerer als Build-Zeit. Die gemessene
+Performance bleibt ein erreichtes Nebenziel, nicht das oberste.
+
+== Developer
+
+=== Q3.2.2.5 Review and branching rules
+Category: design-rationale.
+
+`CLAUDE.md:350` and `:356` prescribe feature branches and Conventional Commits for future work,
+but the history mixes conventional and free-form subjects and no branch protection or template
+is stored in the repository. Which rule actually binds contributors is not derivable.
+
+*Answer:* `CLAUDE.md` gilt ab jetzt: Feature-Branch vom Main, Conventional Commits, Pull Request. Die
+Regel bindet alle neuen Beiträge; die gemischte Altlast in der Historie bleibt unangetastet.
+Technisch durchgesetzt (Branch Protection, Commit-Lint) ist sie nicht.
+
+== Domain Expert
+
+=== Q2.6.10 The declared but unused `example` feature
+Category: business-context.
+
+`buildconfig.groovy:7` declares `example` as a Golden Master feature and
+`buildconfig.groovy:13-14` keeps a `with-examples` style commented out with the note "no content
+yet". What an `arc42example` block should contain, and whether the examples flavor is still
+intended, is a question about arc42 itself and cannot be answered from this repository.
+
+*Answer:* Nie genutztes Feature. Der Golden Master (Stand 2026-09, flacher Klon von
+`arc42/arc42-template`) enthält `arc42example` null mal, `arc42help` dagegen 995 mal in 168
+`.adoc`-Dateien. Die Templates tragen ausschließlich Hilfetexte, die der Build für die
+`plain`-Variante ausblendet. `example` in `buildconfig.groovy:7` erzeugt daher bei jedem Lauf
+eine Regex in `lib/Templates.groovy:80`, die nie trifft. Sollte `with-examples` etwas anderes
+meinen als die Hilfetexte, ist es nie gebaut worden — Feature-Flag und auskommentierter Style
+sind Kandidaten zum Entfernen.
+
+== Operations
+
+=== Q5.5.5 Growth limit of the current design
+Category: future-direction.
+
+Conversion parallelises over templates only, not over formats (`lib/Converter.groovy:430-432`).
+No figure exists for how many languages or formats the pipeline must still handle comfortably,
+so the point at which one-dimensional parallelism stops being adequate cannot be derived.
+
+*Answer:* Zeitbudget statt Größe: ein voller Build darf bis zu 20 Minuten dauern. Heute liegt er bei
+17,4 s (`TEST-REPORT.md:365`), also mehr als zwei Größenordnungen darunter. Die einstufige
+Parallelität bleibt damit auf absehbare Zeit ausreichend; die sequentielle Format-Schleife wird
+erst zum Thema, wenn dieses Budget gerissen wird.
diff --git a/docs/QUESTION_TREE-arc42-generator.adoc b/docs/QUESTION_TREE-arc42-generator.adoc
new file mode 100644
index 0000000..df9ba1e
--- /dev/null
+++ b/docs/QUESTION_TREE-arc42-generator.adoc
@@ -0,0 +1,915 @@
+= Socratic Code Theory Recovery: Question Tree — arc42-generator
+:jbake-menu: questiontree
+:jbake-title: Question Tree
+:jbake-type: page
+:jbake-status: published
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectnumlevels: 1
+
+Bounded context:: `arc42-generator` (whole repository, working tree at commit `6672693`)
+Phase:: 1 of 2 — tree construction only. No PRD, no arc42 document, no ADRs.
+Method:: Naur (1985) theory recovery through recursive question refinement.
+Evidence rule:: A leaf is `[ANSWERED]` only with `file:line` evidence. A directory is not evidence.
+
+NOTE: The submodules `arc42-template/` and `req42-framework/` are not checked out in this
+working tree (both directories are empty). Every statement about Golden Master *content* is
+therefore derived from the generator's own code and configuration, never from template files.
+
+== Q1 — What problem does this bounded context solve, and for whom?
+
+=== Q1.1 Product identity
+
+==== Q1.1.1 What does the program produce?
+[ANSWERED] ZIP archives, one per (language, flavor, format) triple, named
+`arc42-template-<LANG>-<STYLE>-<FORMAT>.zip`.
+Evidence: `lib/Packager.groovy:83`; target directory `buildconfig.groovy:38`.
+
+==== Q1.1.2 From what input?
+[ANSWERED] A single AsciiDoc "Golden Master" per language: one main file plus a chapter
+directory plus images plus a version file.
+Evidence: `lib/Templates.groovy:213` (`arc42-template.adoc`), `lib/Templates.groovy:231-234`
+(`adoc/*.adoc`), `lib/Templates.groovy:194` (`version.properties`), `lib/Templates.groovy:102`
+(`images/`); source root `buildconfig.groovy:3`.
+
+==== Q1.1.3 What is explicitly not the product?
+[ANSWERED] The template itself. The README opens by sending template users away to
+arc42.org/download.
+Evidence: `README.adoc:3`, `README.adoc:132-133`.
+
+==== Q1.1.4 How large is the output space?
+[ANSWERED] 17 formats × 2 flavors × discovered languages.
+Evidence: `buildconfig.groovy:17-35` (17 format keys), `buildconfig.groovy:10-15` (`plain`,
+`with-help`; `with-examples` commented out), `build.groovy:220-223` (the product is computed
+and printed as languages × styles × formats).
+
+=== Q1.2 Primary users
+
+==== Q1.2.1 Who consumes the ZIPs?
+[ANSWERED] Architects and developers documenting a system; they never touch this repository,
+they download from arc42.org.
+Evidence: `README.adoc:3`; role definition `docs/arc42-requirements.adoc:95-97`.
+
+==== Q1.2.2 Who runs the build?
+[ANSWERED] Release maintainers: the build ends with instructions to commit and push the ZIPs
+into the template submodule.
+Evidence: `build-arc42.sh:198-205`; same workflow in `CLAUDE.md:202-207`.
+
+==== Q1.2.3 Who feeds the input?
+[ANSWERED] Translators and content contributors working in the separate template repository.
+Evidence: `docs/arc42_build_process_requirements.md:25-26`;
+`docs/arc42-requirements.adoc:99` (role "Contributor").
+
+=== Q1.3 Channels
+
+==== Q1.3.1 Delivery channel
+[ANSWERED] ZIPs are written into the `dist/` folder *of the template submodule* and pushed from
+there — the generator repository itself ships nothing.
+Evidence: `buildconfig.groovy:38`; `build-arc42.sh:200-204`.
+
+==== Q1.3.2 Invocation channel — container
+[ANSWERED] `docker compose up` runs `build-arc42.sh` in the container with the repository
+bind-mounted at `/workspace`.
+Evidence: `docker-compose.yml:6-9`; `README.adoc:39`.
+
+==== Q1.3.3 Invocation channel — direct CLI
+[ANSWERED] `groovy build.groovy [phase] [--format=X] [--parallel=false]`.
+Evidence: `build.groovy:16-21`.
+
+==== Q1.3.4 Invocation channel — cloud dev environment
+[ANSWERED] GitHub Codespaces, with write permission on `arc42/arc42-template` declared for the
+devcontainer.
+Evidence: `.devcontainer/devcontainer.json:4-9`; `README.adoc:53-61`.
+
+=== Q1.4 Why it was built
+
+==== Q1.4.1 What did it replace?
+[ANSWERED] A Gradle build. The replacement is the stated purpose of the current script.
+Evidence: `build.groovy:6`; `TEST-REPORT.md:1`.
+
+==== Q1.4.2 What was the stated gain?
+[ANSWERED] 17.4 s instead of ~90 s end-to-end, i.e. a claimed 5.2×.
+Evidence: `TEST-REPORT.md:365`; per-phase figures `TEST-REPORT.md:269-274`.
+
+==== Q1.4.3 Why not simply keep Gradle?
+[OPEN] Category: design-rationale. Ask role: Architect.
+The code records the outcome, never the decision. Whether speed, the "chicken-and-egg problem"
+mentioned in `CLAUDE.md:120`, or maintainer skill set drove the rewrite is not derivable.
+
+=== Q1.5 Success metrics
+
+==== Q1.5.1 Build-time metric
+[ANSWERED] Wall-clock duration is measured and printed for every phase and for the whole run.
+Evidence: `build.groovy:208-217`; `lib/Converter.groovy:463-470`; `lib/Packager.groovy:170-178`.
+
+==== Q1.5.2 Output-correctness metric
+[ANSWERED] Two gates: CommonMark validity of generated Markdown, and existence of every image
+referenced by `with-help` Markdown. Both are non-fatal.
+Evidence: `build-arc42.sh:97` (cmark), `build-arc42.sh:162-177` (reference check),
+`build-arc42.sh:109-111` and `build-arc42.sh:187-188` (explicitly non-fatal).
+
+==== Q1.5.3 Adoption metric
+[OPEN] Category: business-context. Ask role: Product Owner.
+No download counter, telemetry, or target figure exists anywhere in the repository. Whether
+success is measured in downloads, languages covered, or formats supported cannot be derived.
+
+=== Q1.6 Segment priority
+
+==== Q1.6.1 Which languages rank first?
+[ANSWERED] EN and DE. They are the only languages the discovery test asserts on, and EN is the
+only language whose Markdown output is validated.
+Evidence: `test-discovery.groovy:79`; `build-arc42.sh:89`.
+
+==== Q1.6.2 Which formats rank first?
+[ANSWERED] The five image-bearing text formats are the only ones whose images are checked.
+Evidence: `build-arc42.sh:124` (`markdown asciidoc textile rst html`).
+
+==== Q1.6.3 Why that ranking?
+[OPEN] Category: business-context. Ask role: Product Owner.
+The code shows which languages and formats are guarded, not which the community actually uses.
+
+== Q2 — What is the specification of this bounded context?
+
+=== Q2.1 Actors
+
+==== Q2.1.1 Human actor
+[ANSWERED] One: the person who starts the pipeline; no roles, no authentication, no
+authorization anywhere in the code.
+Evidence: `build-arc42.sh:84`; `build.groovy:45-52`.
+
+==== Q2.1.2 External system — AsciidoctorJ
+[ANSWERED] In-process library, one shared instance per `Converter`.
+Evidence: `lib/Converter.groovy:33`, invoked at `lib/Converter.groovy:106`,
+`lib/Converter.groovy:139`, `lib/Converter.groovy:313`.
+
+==== Q2.1.3 External system — Pandoc
+[ANSWERED] Out-of-process child process, invoked with an explicit argument vector and a UTF-8
+environment, working directory set to the DocBook output directory.
+Evidence: `lib/Converter.groovy:181-187`, `lib/Converter.groovy:208-217`.
+
+==== Q2.1.4 External system — Git / GitHub
+[ANSWERED] The submodule is re-initialised and pulled on every containerised run.
+Evidence: `build-arc42.sh:66-78`; remotes `.gitmodules:1-6`.
+
+==== Q2.1.5 External system — cmark
+[ANSWERED] Called once per generated Markdown file of `build/EN/markdown`.
+Evidence: `build-arc42.sh:94-104`.
+
+=== Q2.2 Use-case catalog
+
+==== Q2.2.1 UC-1 Generate templates from Golden Master
+[ANSWERED] Phase `templates`.
+Evidence: `build.groovy:129-137` → `lib/Templates.groovy:155-257`.
+
+==== Q2.2.2 UC-2 Discover generated templates
+[ANSWERED] Phase `convert`, first half; also re-entered by the distribution phase when run
+alone.
+Evidence: `build.groovy:145-162`; re-entry `build.groovy:188-191`.
+
+==== Q2.2.3 UC-3 Convert to formats
+[ANSWERED] Phase `convert`, second half.
+Evidence: `build.groovy:168-179` → `lib/Converter.groovy:410-472`.
+
+==== Q2.2.4 UC-4 Create distributions
+[ANSWERED] Phase `distribution`.
+Evidence: `build.groovy:185-202` → `lib/Packager.groovy:102-185`.
+
+==== Q2.2.5 UC-5 Full supervised pipeline
+[ANSWERED] Install Pandoc if absent, refresh the submodule, build, validate, print release
+instructions.
+Evidence: `build-arc42.sh:19-45`, `:48-79`, `:84`, `:86-189`, `:196-205`.
+
+==== Q2.2.6 UC-6 Switch the generator to req42
+[ANSWERED — broken] The script rewrites `build.gradle`, `settings.gradle` and `subBuild.gradle`
+and calls `./gradlew`; none of these files exist in the repository any more.
+Evidence: `switchToreq42.sh:1-4` and `:10-12`; absent from the file list — the only remaining
+build entry points are `build.groovy` and `build-arc42.sh`.
+
+=== Q2.3 Per-interface system specifications
+
+==== Q2.3.1 CLI — phase argument
+[ANSWERED] The first argument not starting with `--` is the phase; default `all`. Input is
+never validated: an unrecognised phase matches none of the four guards and the program prints
+"BUILD SUCCESSFUL" having done nothing.
+Evidence: `build.groovy:46`; guards `build.groovy:129`, `:145`, `:168`, `:185`; unconditional
+success banner `build.groovy:211-215`.
+
+==== Q2.3.2 CLI — `--format=`
+[ANSWERED] Value is taken verbatim, with no check against the configured format map. An unknown
+value reaches Pandoc as both reader target and file extension.
+Evidence: `build.groovy:48-51`; pass-through default `lib/Converter.groovy:400`.
+
+==== Q2.3.3 CLI — `--parallel=false`
+[ANSWERED] Exact-string opt-out; any other spelling leaves parallelism on.
+Evidence: `build.groovy:47`; consumed at `lib/Converter.groovy:427` and
+`lib/Packager.groovy:128`.
+
+==== Q2.3.4 CLI — exit codes
+[ANSWERED] `0` on success; `1` on config load failure, class load failure, and any phase
+exception; also `1` when discovery finds nothing.
+Evidence: `build.groovy:85`, `:116`, `:135`, `:152`, `:160`, `:177`, `:200`; test runner
+`run-all-tests.groovy:147-153`.
+
+==== Q2.3.5 Configuration file contract
+[ANSWERED] A Groovy `ConfigSlurper` script with three blocks: `goldenMaster`, `formats`,
+`distribution`. No schema validation; a missing key surfaces as a Groovy exception at use site.
+Evidence: `build.groovy:76`; `buildconfig.groovy:2-16`, `:17-35`, `:37-40`.
+
+==== Q2.3.6 Input file format contract
+[ANSWERED] Per language: `arc42-template.adoc`, `adoc/*.adoc`, `images/*`, `version.properties`;
+plus a shared `common/` tree copied per language.
+Evidence: `lib/Templates.groovy:213`, `:231-234`, `:102`, `:194`, `:177-190`.
+
+==== Q2.3.7 Output naming contract
+[ANSWERED] HTML `arc42-template.html`; DocBook `arc42-template.xml`; Pandoc single-page
+`arc42-template-<LANG>.<ext>`; multi-page one file per chapter, named after the chapter.
+Evidence: `lib/Converter.groovy:89`, `:122`, `:174`, `:338`.
+
+==== Q2.3.8 Pandoc error contract
+[ANSWERED — inconsistent] Single-page conversion raises `RuntimeException` on a non-zero exit;
+multi-page conversion only prints a warning and continues, so a failed chapter silently
+disappears from the output.
+Evidence: `lib/Converter.groovy:219-222` versus `lib/Converter.groovy:345`.
+
+==== Q2.3.9 AsciidoctorJ error contract
+[ANSWERED] In the multi-page path every conversion exception is swallowed with an inline
+comment, by design, to skip `config`-only files.
+Evidence: `lib/Converter.groovy:313`.
+
+=== Q2.4 Data / entity model
+
+==== Q2.4.1 Template metadata record
+[ANSWERED] A 13-field map: language, style, sourcePath, srcDir, imagesDir, hasImages, mainFile,
+mainFileName, adocFileCount, commonDir, versionProperties, revnumber.
+Evidence: `lib/Discovery.groovy:127-140`.
+
+==== Q2.4.2 Format descriptor record
+[ANSWERED] `[pandocFormat, extension, args]` per format, plus an identity fallback.
+Evidence: `lib/Converter.groovy:382-398`, fallback `:400`.
+
+==== Q2.4.3 AsciiDoc attribute record
+[ANSWERED] Seven fixed attributes plus up to three version attributes taken from
+`version.properties`.
+Evidence: `lib/Converter.groovy:357-365`, `:368-373`.
+
+==== Q2.4.4 Where does the entity model live?
+[ANSWERED] Nowhere as a type: all three records are untyped `Map`s passed between classes;
+there is no DTO, no class, no schema.
+Evidence: `lib/Discovery.groovy:43` (`List<Map>`), `lib/Converter.groovy:44` (`Map template`),
+`lib/Packager.groovy:102`.
+
+=== Q2.5 Acceptance criteria
+
+==== Q2.5.1 Feature-flag removal
+[ANSWERED] Help blocks and `ifdef` markers must be gone, non-help text must remain.
+Evidence: `test-templates.groovy:46-48`.
+
+==== Q2.5.2 Generated structure
+[ANSWERED] Every language must carry both styles with at least one `.adoc` file.
+Evidence: `test-templates.groovy:62-74`.
+
+==== Q2.5.3 Discovery completeness
+[ANSWERED] Both styles present; EN and DE must exist.
+Evidence: `test-discovery.groovy:49-50`, `:79`.
+
+==== Q2.5.4 Conversion smoke criteria
+[ANSWERED] HTML, DocBook, Markdown and DOCX files must exist after conversion; multi-page
+Markdown must yield more than one file.
+Evidence: `test-converter.groovy:47`, `:55`, `:70`, `:78`, `:89-90`.
+
+==== Q2.5.5 Post-build validation criteria
+[ANSWERED] Generated Markdown parses as CommonMark; every image directory exists and is
+non-empty; every Markdown image reference resolves.
+Evidence: `build-arc42.sh:97`, `:139-145`, `:174-177`.
+
+=== Q2.6 Cross-cutting business rules
+
+==== Q2.6.1 BR-1 Language directory naming
+[ANSWERED] A directory is a language exactly when its name matches `/^[A-Z]{2,}$/`. The rule is
+implemented twice, once on the input side and once on the generated side.
+Evidence: `lib/Templates.groovy:38`; `lib/Discovery.groovy:62`.
+
+==== Q2.6.2 BR-2 Flavor definition
+[ANSWERED] A flavor is a named list of features to keep; everything in `allFeatures` not listed
+is stripped.
+Evidence: `buildconfig.groovy:7-15`; subtraction at `lib/Templates.groovy:205`.
+
+==== Q2.6.3 BR-3 Feature removal mechanics
+[ANSWERED] Two mechanisms: delete `[role="arc42<feature>"]` delimited blocks; for `help` also
+delete the `ifdef::arc42help[]` / `endif::arc42help[]` marker lines while keeping their body.
+Evidence: `lib/Templates.groovy:80`, `:84-87`.
+
+==== Q2.6.4 BR-4 Image policy by flavor
+[ANSWERED] `plain` receives only `arc42-logo.png`; every other flavor receives all images.
+Evidence: `lib/Templates.groovy:114-133`.
+
+==== Q2.6.5 BR-5 Image policy by format
+[ANSWERED] Images are copied only for formats whose `imageFolder` flag is true; `epub` is the
+sole exception in the configuration. `mkdocs` variants receive them under `docs/images`.
+Evidence: `buildconfig.groovy:18-34`; `lib/Converter.groovy:54`; `lib/Converter.groovy:282`.
+
+==== Q2.6.6 BR-6 Include-path rewriting
+[ANSWERED] On generation, `include::adoc/` becomes `include::` and `include::../common/` becomes
+`include::../../../common/`; on AsciiDoc output, every `include::` gains a `src/` prefix.
+Evidence: `lib/Templates.groovy:68`, `:71`; `lib/Converter.groovy:265`.
+
+==== Q2.6.7 BR-7 Russian LaTeX font encoding
+[ANSWERED] LaTeX output for RU adds `fontenc=T1,T2A`.
+Evidence: `lib/Converter.groovy:195-197`.
+
+==== Q2.6.8 BR-8 mkdocsMP page suppression
+[ANSWERED] `config.md` and `about-arc42.md` are deleted from mkdocsMP output.
+Evidence: `lib/Converter.groovy:348`.
+
+==== Q2.6.9 BR-9 Flavor name normalisation in file names
+[ANSWERED] Non-letters are stripped from the style for the ZIP name, so `with-help` becomes
+`withhelp`.
+Evidence: `lib/Packager.groovy:80`, used at `:83`.
+
+==== Q2.6.10 BR-10 The declared but unused `example` feature
+[OPEN] Category: business-context. Ask role: Domain Expert.
+`buildconfig.groovy:7` declares `example` as a Golden Master feature and
+`buildconfig.groovy:13-14` keeps a `with-examples` style commented out with the note "no content
+yet". What an `arc42example` block should contain, and whether the examples flavor is still
+intended, is a question about arc42 itself and cannot be answered from this repository.
+
+== Q3 — What is the architecture of this bounded context?
+
+=== Q3.1 Requirements overview (arc42 ch. 1)
+
+==== Q3.1.1 Stated functional goal
+[ANSWERED] One source, many formats, many languages, two flavors, reproducible and extensible.
+Evidence: `docs/arc42_build_process_requirements.md:11-15`; `README.adoc:120-124`.
+
+==== Q3.1.2 Stated scope boundary
+[ANSWERED] The build repository owns build logic; the template repository owns content only.
+Evidence: `docs/arc42_build_process_requirements.md:86-104`.
+
+=== Q3.2 Architecture constraints (arc42 ch. 2)
+
+==== Q3.2.1 Technical constraints
+===== Q3.2.1.1 Runtime and language
+[ANSWERED] Groovy 5.0.3 on OpenJDK 21 JRE, Alpine 3.20.
+Evidence: `Dockerfile:23-26`, `:14`, `:29`, `:4`, `:50`.
+
+===== Q3.2.1.2 Pinned libraries
+[ANSWERED] AsciidoctorJ 2.5.10, AsciidoctorJ-Diagram 2.2.14, GPars 1.2.1, resolved by Grape at
+script start.
+Evidence: `lib/Converter.groovy:3-5`; pre-warmed at `init-groovy-deps.groovy:3-5`.
+
+===== Q3.2.1.3 Pinned external binary
+[ANSWERED] Pandoc 3.7.0.2, installed from a GitHub release `.deb` when missing.
+Evidence: `build-arc42.sh:26-27`, `:39-40`.
+
+===== Q3.2.1.4 Supported execution mode
+[ANSWERED] Docker is declared the only supported approach; local execution is explicitly
+unsupported.
+Evidence: `README.adoc:17`, `:19`, `:113`.
+
+===== Q3.2.1.5 Licence constraint
+[ANSWERED] MIT for the generator; open-source-only toolchain mandated for the build.
+Evidence: `LICENSE.txt:1-3`; `docs/arc42_build_process_requirements.md:190-199`.
+
+==== Q3.2.2 Organizational / process constraints
+===== Q3.2.2.1 Repository split
+[ANSWERED] Two repositories, template consumed as a Git submodule.
+Evidence: `docs/arc42_build_process_requirements.md:86-104`; `.gitmodules:1-6`.
+
+===== Q3.2.2.2 Release process
+[ANSWERED] Manual: build, inspect `arc42-template/dist/`, then commit and push inside the
+submodule.
+Evidence: `build-arc42.sh:198-205`; `CLAUDE.md:202-207`.
+
+===== Q3.2.2.3 CI process
+[ANSWERED — gap] The requirements demand example GitHub Actions workflows; the repository
+contains no `.github` directory at all, so every build is run by hand.
+Evidence: requirement `docs/arc42_build_process_requirements.md:229`; absence confirmed against
+the repository file list (no workflow file exists).
+
+===== Q3.2.2.4 Agent tool policy
+[ANSWERED] Bash and Write require confirmation; reading `.env*` and `secrets/**` is denied.
+Evidence: `settings.json:12-20`.
+
+===== Q3.2.2.5 Review and branching rules
+[OPEN] Category: design-rationale. Ask role: Developer.
+`CLAUDE.md:350` and `:356` prescribe feature branches and Conventional Commits for future work,
+but the history mixes conventional and free-form subjects and no branch protection or template
+is stored in the repository. Which rule actually binds contributors is not derivable.
+
+==== Q3.2.3 Conventional constraints
+===== Q3.2.3.1 Line endings
+[ANSWERED] LF enforced for shell, Docker and Groovy files; binary types excluded from
+normalisation.
+Evidence: `.gitattributes:2-10`, `:23-31`.
+
+===== Q3.2.3.2 Ignored artifacts
+[ANSWERED] `build`, `src_gen`, IDE files and `.gradle` are untracked.
+Evidence: `.gitignore:1-8`.
+
+===== Q3.2.3.3 Output directory layout
+[ANSWERED] `build/src_gen/<LANG>/asciidoc/<STYLE>/src`, then
+`build/<LANG>/<FORMAT>/<STYLE>`, then `arc42-template/dist/`.
+Evidence: `lib/Templates.groovy:206-207`; `lib/Converter.groovy:47`; `buildconfig.groovy:38`.
+
+===== Q3.2.3.4 Code layout convention
+[ANSWERED] One class per pipeline stage in `lib/`, loaded by file name from the orchestrator.
+Evidence: `build.groovy:101-111`.
+
+=== Q3.3 Context and scope (arc42 ch. 3)
+
+==== Q3.3.1 Input boundary — Golden Master
+[ANSWERED] Read-only file access under the configured source path, refreshed by Git.
+Evidence: `buildconfig.groovy:3`; `lib/Templates.groovy:31`; refresh `build-arc42.sh:68-69`.
+
+==== Q3.3.2 Output boundary — distribution
+[ANSWERED] Write access into the submodule's `dist/` directory.
+Evidence: `buildconfig.groovy:38`; `lib/Packager.groovy:84-86`.
+
+==== Q3.3.3 Process boundary — Pandoc
+[ANSWERED] `ProcessBuilder` with a fixed argument vector, a working directory and two
+environment variables.
+Evidence: `lib/Converter.groovy:208-216`.
+
+==== Q3.3.4 Process boundary — package manager and network
+[ANSWERED] The pipeline downloads and installs a `.deb` as root when Pandoc is missing.
+Evidence: `build-arc42.sh:39-41`.
+
+=== Q3.4 Solution strategy (arc42 ch. 4)
+
+==== Q3.4.1 Pivot-format strategy
+[ANSWERED] HTML and AsciiDoc are produced directly; every other format goes AsciiDoc → DocBook →
+Pandoc.
+Evidence: `lib/Converter.groovy:60-71`.
+
+==== Q3.4.2 Parallelisation strategy
+[ANSWERED] GPars pool sized to `availableProcessors`, parallel over templates for conversion and
+over (template, format) pairs for packaging.
+Evidence: `lib/Converter.groovy:429-431`; `lib/Packager.groovy:130-131`.
+
+==== Q3.4.3 Convention-over-configuration strategy
+[ANSWERED] Languages are discovered from the filesystem rather than configured, so a new
+translation needs no code and no config change.
+Evidence: `lib/Templates.groovy:37-40`.
+
+==== Q3.4.4 Caching strategy
+[ANSWERED] Discovery memoises its result for the process lifetime, with an explicit
+invalidation method.
+Evidence: `lib/Discovery.groovy:17`, `:45-47`, `:152`, `:159-161`.
+
+=== Q3.5 Building block view (arc42 ch. 5)
+
+==== Q3.5.1 Level 1 — orchestrator
+[ANSWERED] `build.groovy` parses arguments, loads config, loads four classes by file and runs
+four guarded phases.
+Evidence: `build.groovy:45-52`, `:76`, `:101-111`, `:129-202`.
+
+==== Q3.5.2 Level 2 — Templates
+[ANSWERED] Golden Master processing: discover languages, strip features, fix includes, copy
+images and common files.
+Evidence: `lib/Templates.groovy:30-48`, `:64-74`, `:75-90`, `:101-134`, `:155-257`.
+
+==== Q3.5.3 Level 2 — Discovery
+[ANSWERED] Scans the generated tree, validates structure, builds metadata, offers a query API.
+Evidence: `lib/Discovery.groovy:43-154`, `:168-210`, `:219-241`.
+
+==== Q3.5.4 Level 2 — Packager
+[ANSWERED] Zips one output directory per (language, style, format) into the dist folder.
+Evidence: `lib/Packager.groovy:35-60`, `:71-93`, `:102-185`.
+
+==== Q3.5.5 Level 3 — Converter, dispatch
+[ANSWERED] A four-way if-chain on the format name decides the conversion path.
+Evidence: `lib/Converter.groovy:60-71`.
+
+==== Q3.5.6 Level 3 — Converter, single-page Pandoc path
+[ANSWERED] Derives a sibling `docbook` directory from the output path, converts, copies images
+next to the XML, then runs Pandoc from that directory.
+Evidence: `lib/Converter.groovy:151-154`, `:157-170`, `:206-217`.
+
+==== Q3.5.7 Level 3 — Converter, multi-page path
+[ANSWERED] Converts each chapter file separately to DocBook, skipping the main file and
+`config.adoc`, then runs Pandoc per XML file.
+Evidence: `lib/Converter.groovy:303-315`, `:337-346`.
+
+==== Q3.5.8 Level 3 — Converter, post-processing
+[ANSWERED] LaTeX thin spaces are replaced by ordinary spaces; HTML gets a charset meta tag if
+none is present.
+Evidence: `lib/Converter.groovy:225-228`, `:231-238`.
+
+==== Q3.5.9 Level 4 — dead branch in post-processing
+[ANSWERED] The HTML fix-up at `lib/Converter.groovy:231-238` sits inside `convertViaPandoc`,
+which `html` never reaches, because `html` is routed to AsciidoctorJ one level up.
+Evidence: routing `lib/Converter.groovy:60-61`; unreachable branch `lib/Converter.groovy:231`.
+
+=== Q3.6 Runtime view (arc42 ch. 6)
+
+==== Q3.6.1 Happy path sequence
+[ANSWERED] generate → discover → convert → package, each phase guarded by the phase argument and
+each failure terminating the process.
+Evidence: `build.groovy:129-137`, `:145-162`, `:168-179`, `:185-202`.
+
+==== Q3.6.2 Conversion loop
+[ANSWERED] Outer parallel loop over templates, inner sequential loop over formats; counters are
+mutated inside a `synchronized(this)` block.
+Evidence: `lib/Converter.groovy:430-443`.
+
+==== Q3.6.3 Failure path inside the loop
+[ANSWERED] A failing conversion is caught per (template, format), logged with a stack trace,
+counted as failed, and the run continues; the exit code stays 0.
+Evidence: `lib/Converter.groovy:74-78`; counting `:437-440`; no rethrow before
+`build.groovy:211`.
+
+==== Q3.6.4 Submodule refresh path
+[ANSWERED] Three attempts, each deleting stale index locks first, with a 2 s pause and a hard
+exit after the third.
+Evidence: `build-arc42.sh:66-78`.
+
+=== Q3.7 Deployment view (arc42 ch. 7)
+
+==== Q3.7.1 Image build stage
+[ANSWERED] Alpine builder installs JRE, bash, git, wget, unzip, pandoc and cmark, then unpacks
+Groovy and pre-populates the Grape cache.
+Evidence: `Dockerfile:13-20`, `:23-26`, `:40-45`.
+
+==== Q3.7.2 Runtime stage
+[ANSWERED] Second Alpine stage with runtime packages only; Groovy and the Grape cache are copied
+from the builder; only the build scripts and `lib/` are copied in.
+Evidence: `Dockerfile:53-58`, `:64-68`, `:78-79`.
+
+==== Q3.7.3 Container execution contract
+[ANSWERED] Repository bind-mounted at `/workspace`, working directory `/workspace`, command
+`./build-arc42.sh`, image tagged `arc42-generator:9.1.0`.
+Evidence: `docker-compose.yml:4-9`; default command `Dockerfile:82`.
+
+==== Q3.7.4 Why the image copies only part of the repository
+[ANSWERED] `Dockerfile:78-79` copies four scripts and `lib/`; the test scripts are not in the
+image, so `run-all-tests.groovy` cannot run in the runtime container.
+Evidence: `Dockerfile:78-79` versus `run-all-tests.groovy:22-36`.
+
+=== Q3.8 Crosscutting concepts (arc42 ch. 8)
+
+==== Q3.8.1 Threat model
+===== Q3.8.1.1 Is a threat catalogue present?
+[OPEN] Category: design-rationale. Ask role: Architect.
+No STRIDE analysis, no threat IDs, no security section exists in any document in the repository.
+
+===== Q3.8.1.2 Which trust assumption does the code encode?
+[ANSWERED] The Golden Master is trusted completely: AsciiDoc is processed with
+`SafeMode.UNSAFE`, which permits arbitrary includes and file access from template content.
+Evidence: `lib/Converter.groovy:100`, `:132`, `:311`.
+
+===== Q3.8.1.3 Which Git trust assumption does the container encode?
+[ANSWERED] All directories are marked safe, disabling Git's ownership check inside the image.
+Evidence: `Dockerfile:61`; narrower variant at `build-arc42.sh:52-53`.
+
+==== Q3.8.2 Security concept
+===== Q3.8.2.1 What protection exists at all?
+[ANSWERED] Exactly one mechanism, and it protects the developer's agent session rather than the
+build: a deny list for `.env*` and `secrets/**`.
+Evidence: `settings.json:17-20`.
+
+===== Q3.8.2.2 Are downloads integrity-checked?
+[ANSWERED — no] Neither the Pandoc `.deb` nor the Groovy ZIP is verified by checksum or
+signature before being installed.
+Evidence: `build-arc42.sh:39-41`; `Dockerfile:23-25`.
+
+===== Q3.8.2.3 Why was UNSAFE chosen?
+[OPEN] Category: design-rationale. Ask role: Architect.
+Whether UNSAFE is required for the template's own includes or was chosen to avoid debugging
+path errors is not derivable.
+
+==== Q3.8.3 Test concept
+===== Q3.8.3.1 What layer do the tests sit on?
+[ANSWERED] Integration only. The report states the absence of unit tests as a deliberate choice.
+Evidence: `run-all-tests.groovy:21-37`; `TEST-REPORT.md:15`.
+
+===== Q3.8.3.2 How are tests executed?
+[ANSWERED] The runner spawns `groovy <script>` per suite and aggregates exit codes.
+Evidence: `run-all-tests.groovy:55-64`, `:147-153`.
+
+===== Q3.8.3.3 What is asserted about content?
+[ANSWERED] Existence, file counts and non-emptiness; no output is compared against an expected
+document.
+Evidence: `test-converter.groovy:38-47`, `:89-90`.
+
+===== Q3.8.3.4 Do tests trace to use cases?
+[ANSWERED — no] No test carries a use-case or rule identifier; suites are named after the class
+they exercise.
+Evidence: `run-all-tests.groovy:22-36`.
+
+==== Q3.8.4 Observability
+===== Q3.8.4.1 What is the logging mechanism?
+[ANSWERED] `println` to stdout only; no logging framework, no levels, no log file.
+Evidence: `build.groovy:61-67`; `lib/Converter.groovy:436-439`; `lib/Packager.groovy:141-145`.
+
+===== Q3.8.4.2 What is counted?
+[ANSWERED] Completed, failed and skipped counts plus durations per phase.
+Evidence: `lib/Converter.groovy:466-470`; `lib/Packager.groovy:173-178`.
+
+===== Q3.8.4.3 Is failure visible in the exit status?
+[ANSWERED — no] `lib/Packager.groovy:116` initialises `failed` and never increments it, so the
+summary at `lib/Packager.groovy:177` always prints `Failed: 0`; conversion failures are counted
+but never change the process exit code.
+Evidence: `lib/Packager.groovy:116`, `:177`; `lib/Converter.groovy:438`; `build.groovy:211-215`.
+
+==== Q3.8.5 Error handling
+===== Q3.8.5.1 Fail-fast boundary
+[ANSWERED] Configuration load, class load and each phase abort the process with exit 1.
+Evidence: `build.groovy:83-86`, `:113-117`, `:130-136`.
+
+===== Q3.8.5.2 Fail-soft boundary
+[ANSWERED] Individual conversions are isolated per (template, format) and never abort the run.
+Evidence: `lib/Converter.groovy:74-78`.
+
+===== Q3.8.5.3 Retry
+[ANSWERED] Exactly one retry loop exists, for the Git submodule update: three attempts, fixed
+2 s pause, lock cleanup before each attempt.
+Evidence: `build-arc42.sh:66-78`.
+
+===== Q3.8.5.4 Circuit breaker, fallback, recovery
+[ANSWERED — none] No breaker and no compensation exist. The only fallback is silent: an unknown
+format falls back to an identity Pandoc descriptor.
+Evidence: `lib/Converter.groovy:400`.
+
+==== Q3.8.6 Encoding and localisation
+===== Q3.8.6.1 How is encoding handled?
+[ANSWERED] UTF-8 is forced explicitly at every read and write, and in the Pandoc child
+environment.
+Evidence: `lib/Templates.groovy:199`, `:218`, `:226`, `:241`; `lib/Discovery.groovy:121`;
+`lib/Converter.groovy:213-214`.
+
+===== Q3.8.6.2 Is there any per-language special case?
+[ANSWERED] One: RU LaTeX font encoding.
+Evidence: `lib/Converter.groovy:195-197`.
+
+=== Q3.9 Architecture decisions (arc42 ch. 9)
+
+==== Q3.9.1 Decision: replace Gradle with plain Groovy
+[ANSWERED — outcome only] Recorded as a result with measurements, not as an ADR.
+Evidence: `build.groovy:6`; `TEST-REPORT.md:338-365`.
+
+==== Q3.9.2 Decision: two repositories, template as submodule
+[ANSWERED] Written down with rationale in prose.
+Evidence: `docs/arc42_build_process_requirements.md:86-104`.
+
+==== Q3.9.3 Decision: DocBook as pivot format
+[ANSWERED — outcome only] Implemented in the dispatch chain; no rationale recorded anywhere.
+Evidence: `lib/Converter.groovy:69-70`.
+
+==== Q3.9.4 Decision: Docker as the only supported environment
+[ANSWERED] Stated as policy in the README.
+Evidence: `README.adoc:17-19`.
+
+==== Q3.9.5 Are decisions recorded as ADRs?
+[ANSWERED — no] The repository contains no ADR directory and no decision record format; the four
+decisions above are recovered from prose and code.
+Evidence: documentation set is `docs/arc42-requirements.adoc`,
+`docs/arc42_build_process_requirements.md`, `docs/confluence.adoc`,
+`docs/export2confluence.adoc` — none of them is a decision record (see
+`docs/arc42_build_process_requirements.md:374-394`, which still lists the open decisions).
+
+=== Q3.10 Quality requirements (arc42 ch. 10)
+
+See the Q4 branch for the eight characteristics with their measurable evidence. Two documented
+requirements have no counterpart in code:
+
+==== Q3.10.1 Requirement: reproducible, network-free build
+[ANSWERED — contradicted] The requirement demands no network dependency at build time; Grape
+resolves three artifacts at script start, and Pandoc is downloaded when missing.
+Evidence: requirement `docs/arc42_build_process_requirements.md:323`; contradicting code
+`lib/Converter.groovy:3-5`, `build-arc42.sh:39-40`. The Docker image mitigates this by
+pre-populating the cache (`Dockerfile:40-45`).
+
+==== Q3.10.2 Requirement: plugin-like format adapters
+[ANSWERED — contradicted] Adding a format requires edits in three places: the config map, the
+dispatch chain and the Pandoc descriptor table.
+Evidence: requirement `docs/arc42_build_process_requirements.md:335-347`; implementation
+`buildconfig.groovy:17-35`, `lib/Converter.groovy:60-71`, `lib/Converter.groovy:382-398`.
+
+=== Q3.11 Risks and technical debt (arc42 ch. 11)
+
+See the Q5 branch. Every item there is recovered from code, not from a risk register — the
+repository contains no risk list.
+
+=== Q3.12 Glossary (arc42 ch. 12)
+
+==== Q3.12.1 Golden Master
+[ANSWERED] The authoritative AsciiDoc source tree, configured as `sourcePath`.
+Evidence: `buildconfig.groovy:2-3`.
+
+==== Q3.12.2 Style / flavor
+[ANSWERED] A named feature subset; the code says `style`, the README and requirements say
+`flavour`.
+Evidence: `buildconfig.groovy:10-15`; `README.adoc:123`;
+`docs/arc42_build_process_requirements.md:133`.
+
+==== Q3.12.3 MP format
+[ANSWERED] "Multi-page": one output file per chapter; four format names carry the suffix.
+Evidence: `lib/Converter.groovy:299`.
+
+==== Q3.12.4 Is the vocabulary consistent?
+[ANSWERED — no] `style` versus `flavour` and `plain` versus `Skeleton` name the same things in
+code and in the requirements.
+Evidence: `buildconfig.groovy:11` versus `docs/arc42-requirements.adoc:171`.
+
+== Q4 — What quality goals drive the design?
+
+Scenarios below use the six-part form where the code supplies a literal response measure. No
+target number is invented; every figure is quoted from the repository.
+
+=== Q4.1 Functional suitability
+[ANSWERED] Stimulus: a full build. Response: every discovered language is generated in two
+flavors and 17 formats. Measure: 18 templates and 306 conversions for nine languages, computed
+and printed by the build itself.
+Evidence: `buildconfig.groovy:17-35`; `build.groovy:220-223`; measured run `TEST-REPORT.md:119`.
+
+=== Q4.2 Performance efficiency
+[ANSWERED] Stimulus: full HTML build of 18 templates on a developer machine. Response: pipeline
+completes. Measure: 17.4 s total, 10.7 s template generation, 0.6 s packaging.
+Evidence: `TEST-REPORT.md:365`, `:102`, `:274`; mechanism `lib/Converter.groovy:429`.
+
+=== Q4.3 Compatibility
+[ANSWERED] Stimulus: a Markdown consumer parses the output. Response: the file parses as
+CommonMark. Measure: `cmark` exits 0 for every file in `build/EN/markdown`.
+Evidence: `build-arc42.sh:94-104`; format-level compatibility via the DocBook pivot
+`lib/Converter.groovy:69-70`.
+
+=== Q4.4 Interaction capability (usability)
+[ANSWERED] Stimulus: a maintainer wants all outputs. Response: one command. Measure: a single
+`docker compose up`, or one `groovy build.groovy` with an optional phase and format filter.
+Evidence: `docker-compose.yml:9`; `build.groovy:16-21`; progress line per conversion
+`lib/Converter.groovy:436`.
+
+=== Q4.5 Reliability
+[ANSWERED] Stimulus: one conversion fails. Response: the remaining conversions still run and the
+failure is reported. Measure: failure is isolated to one (template, format) pair; the run
+continues and validation failures are declared non-fatal.
+Evidence: `lib/Converter.groovy:74-78`; `build-arc42.sh:109-111`, `:187-188`; retry only for the
+submodule `build-arc42.sh:66-78`.
+
+=== Q4.6 Security
+[ANSWERED] Stimulus: the Golden Master contains a hostile include. Response: it is executed.
+Measure: `SafeMode.UNSAFE` on all three AsciidoctorJ call sites, `safe.directory '*'` in the
+image, and no checksum on any downloaded binary.
+Evidence: `lib/Converter.groovy:100`, `:132`, `:311`; `Dockerfile:61`; `build-arc42.sh:39-41`.
+
+=== Q4.7 Maintainability
+[ANSWERED] Stimulus: add a language versus add a format. Response: the first needs no code, the
+second needs three edits. Measure: language discovery is regex-driven at
+`lib/Templates.groovy:38`; a format touches `buildconfig.groovy:17-35`,
+`lib/Converter.groovy:60-71` and `lib/Converter.groovy:382-398`.
+Evidence: as cited; procedure documented at `CLAUDE.md:170-181`.
+
+=== Q4.8 Flexibility / portability
+[ANSWERED] Stimulus: run on amd64, arm64, macOS, Windows or Codespaces. Response: the same
+pipeline runs. Measure: architecture-specific Pandoc package selection, LF normalisation for
+scripts, and a Codespaces permission declaration.
+Evidence: `build-arc42.sh:23-36`; `.gitattributes:2-7`; `.devcontainer/devcontainer.json:4-9`.
+
+=== Q4.9 Which characteristic has priority?
+[OPEN] Category: quality-goals. Ask role: Architect.
+The code guards performance and functional suitability with measurements, and leaves security
+and reliability to defaults. Whether that ranking is intended or accidental cannot be read from
+the code.
+
+== Q5 — What risks and technical debt exist?
+
+=== Q5.1 Technical debt
+
+==== Q5.1.1 Dead migration script
+[ANSWERED] `switchToreq42.sh` rewrites Gradle files and calls `./gradlew`; none of those files
+exist after the Gradle removal, so the req42 path is broken.
+Evidence: `switchToreq42.sh:1-4`, `:10-12`.
+
+==== Q5.1.2 Dead counter
+[ANSWERED] `failed` is declared, printed, and never incremented.
+Evidence: `lib/Packager.groovy:116`, `:177`.
+
+==== Q5.1.3 Unreachable post-processing branch
+[ANSWERED] The HTML charset fix-up can never execute, because `html` never reaches
+`convertViaPandoc`.
+Evidence: `lib/Converter.groovy:231-238` versus routing at `:60-61`.
+
+==== Q5.1.4 Hard-coded absolute paths in a test
+[ANSWERED] `test-asciidoc-direct.groovy` points at `/workspaces/arc42-generator/...`, which only
+exists in Codespaces.
+Evidence: `test-asciidoc-direct.groovy:11-13`.
+
+==== Q5.1.5 Documentation drift in CLAUDE.md
+[ANSWERED] The language regex is documented as `/^[A-Z]{2}$/` but implemented as
+`/^[A-Z]{2,}$/`, so the document excludes three-letter codes such as `UKR` that the code
+accepts. The same file still carries responsible-vibe-mcp operating instructions although the
+server was removed in commit `2b28a31`.
+Evidence: `CLAUDE.md:52` versus `lib/Templates.groovy:38`; `CLAUDE.md:217-280`.
+
+==== Q5.1.6 Duplicated image-copy logic
+[ANSWERED] The same recursive copy is written four times with small variations.
+Evidence: `lib/Templates.groovy:127-131`; `lib/Converter.groovy:162-169`, `:287-294`, `:328-330`.
+
+==== Q5.1.7 Untyped data model
+[ANSWERED] All inter-class data is passed as `Map`, so a renamed key fails at runtime, not at
+compile time.
+Evidence: `lib/Discovery.groovy:127-140` consumed at `lib/Converter.groovy:86`, `:95`, `:157`.
+
+=== Q5.2 Security risks
+
+==== Q5.2.1 Unsafe AsciiDoc processing
+[ANSWERED] `SafeMode.UNSAFE` gives template content full file-system reach during conversion.
+Evidence: `lib/Converter.groovy:100`, `:132`, `:311`.
+
+==== Q5.2.2 Unverified binary installation
+[ANSWERED] A `.deb` is downloaded over the network and installed with `dpkg -i` without any
+integrity check; the Groovy ZIP is unpacked the same way.
+Evidence: `build-arc42.sh:39-41`; `Dockerfile:23-25`.
+
+==== Q5.2.3 Disabled Git ownership check
+[ANSWERED] The image marks every directory safe.
+Evidence: `Dockerfile:61`.
+
+==== Q5.2.4 Write access to a foreign repository
+[ANSWERED] The devcontainer requests write permission on `arc42/arc42-template`.
+Evidence: `.devcontainer/devcontainer.json:4-9`.
+
+=== Q5.3 Operational risks
+
+==== Q5.3.1 Destructive submodule refresh
+[ANSWERED] The containerised pipeline deletes the whole `arc42-template` directory before
+re-initialising it, so uncommitted local template work is lost.
+Evidence: `build-arc42.sh:57-60`.
+
+==== Q5.3.2 Green build despite failed conversions
+[ANSWERED] Conversion failures are counted but the process still exits 0 and prints
+"BUILD SUCCESSFUL".
+Evidence: `lib/Converter.groovy:437-440`; `build.groovy:211-215`.
+
+==== Q5.3.3 Silent no-op on a mistyped phase
+[ANSWERED] An unrecognised phase runs nothing and reports success.
+Evidence: `build.groovy:46` with guards at `:129`, `:145`, `:168`, `:185`.
+
+==== Q5.3.4 No automated pipeline
+[ANSWERED] No CI configuration exists, so nothing runs the test suite or the build on push.
+Evidence: no `.github` directory in the repository; requirement
+`docs/arc42_build_process_requirements.md:229`.
+
+==== Q5.3.5 Release requires manual push into the submodule
+[ANSWERED] Artifacts are written into the submodule working tree and must be committed there by
+hand.
+Evidence: `buildconfig.groovy:38`; `build-arc42.sh:200-204`.
+
+=== Q5.4 Dependency and supply-chain risks
+
+==== Q5.4.1 Runtime dependency resolution
+[ANSWERED] Grape resolves AsciidoctorJ, the diagram extension and GPars when the script starts,
+so a repository outage breaks the build outside Docker.
+Evidence: `lib/Converter.groovy:3-5`; `lib/Packager.groovy:3`.
+
+==== Q5.4.2 No lockfile, no checksums
+[ANSWERED] Versions are pinned in four separate places and nowhere verified.
+Evidence: `lib/Converter.groovy:3-5`; `init-groovy-deps.groovy:3-5`; `Dockerfile:23`;
+`build-arc42.sh:26-27`.
+
+==== Q5.4.3 Moving upstream inputs
+[ANSWERED] The build checks out `master` of the template and pulls, so the output depends on
+whatever upstream contains at build time rather than on the recorded submodule commit.
+Evidence: `build-arc42.sh:69`.
+
+==== Q5.4.4 Duplicate version pins that can drift
+[ANSWERED] The same three Grape coordinates appear in two files and must be changed together.
+Evidence: `lib/Converter.groovy:3-5` and `init-groovy-deps.groovy:3-5`.
+
+=== Q5.5 Scaling and performance risks
+
+==== Q5.5.1 Parallelism is one-dimensional
+[ANSWERED] Only the template loop is parallel; the 17 formats of one template run sequentially,
+so speed-up is capped by the number of templates, not by cores.
+Evidence: `lib/Converter.groovy:430-432`.
+
+==== Q5.5.2 Shared Asciidoctor instance across threads
+[ANSWERED] One instance is created per `Converter` and used from every parallel worker.
+Evidence: `lib/Converter.groovy:33` used at `:106`, `:139`, `:313` inside the parallel loop
+`:430`.
+
+==== Q5.5.3 Coarse lock on the progress counter
+[ANSWERED] Every worker synchronises on the same object to increment counters and print.
+Evidence: `lib/Converter.groovy:433`; `lib/Packager.groovy:136`.
+
+==== Q5.5.4 Repeated full image copies
+[ANSWERED] Images are copied once per format per template, and again into the DocBook working
+directory.
+Evidence: `lib/Converter.groovy:54` with `:287-294`; extra copy at `:157-169`.
+
+==== Q5.5.5 Growth limit of the current design
+[OPEN] Category: future-direction. Ask role: Operations.
+No figure exists for how many languages or formats the pipeline must still handle comfortably,
+so the point at which one-dimensional parallelism stops being adequate cannot be derived.
+
+== Recovery notes
+
+* Depth reached: four levels below a fixed node in the Q3.2 and Q3.8 branches, two to three
+  levels elsewhere — matching the code density of a 2,155-line build system.
+* The bounded context was small enough to recover in one pass; no node had to be abandoned at
+  the depth backstop.
+* Nine leaves are `[OPEN]`; they are collected in `OPEN_QUESTIONS-arc42-generator.adoc`.
+* Status 2026-09-14: all nine have been answered by the team. The answers live in that file
+  under each question; this tree keeps the questions as they stood at recovery time. Phase 2
+  synthesizes from both files together.
diff --git a/docs/arc42-requirements.adoc b/docs/arc42-requirements.adoc
index e90eb18..4f8bfa8 100644
--- a/docs/arc42-requirements.adoc
+++ b/docs/arc42-requirements.adoc
@@ -1,4 +1,8 @@
 = arc42 Template Requirements
+:jbake-menu: legacy
+:jbake-title: arc42 Requirements (legacy)
+:jbake-type: page
+:jbake-status: published
 :toc:
 :author: Gernot Starke
 :email: gernot.starke@innoq.com
diff --git a/docs/arc42/arc42-arc42-generator.adoc b/docs/arc42/arc42-arc42-generator.adoc
new file mode 100644
index 0000000..457e4e6
--- /dev/null
+++ b/docs/arc42/arc42-arc42-generator.adoc
@@ -0,0 +1,92 @@
+// header file for arc42-template,
+// including all help texts
+//
+// ====================================
+
+// configure EN settings for asciidoc
+include::src/config.adoc[]
+
+= image:arc42-logo.png[arc42] Architecture Documentation: arc42-generator
+:jbake-menu: architecture
+:jbake-title: Architecture (arc42)
+:jbake-type: page
+:jbake-status: published
+:revnumber: 1.0
+:revdate: 2026-09-14
+:revremark: recovered from the code; team answers marked in the text
+:toc-title: Table of Contents
+
+//additional style for arc42 help callouts
+include::common/styles/arc42-help-style.adoc[]
+
+
+
+include::src/about-arc42.adoc[]
+
+// horizontal line
+***
+
+ifdef::arc42help[]
+[role="arc42help"]
+****
+[NOTE]
+====
+This version of the template contains some help and explanations.
+It is used for familiarization with arc42 and the understanding of the concepts.
+For documentation of your own system you use better the _plain_ version.
+====
+****
+endif::arc42help[]
+
+// numbering from here on
+:numbered:
+
+<<<<
+// 1. Introduction and Goals
+include::src/01_introduction_and_goals.adoc[]
+
+<<<<
+// 2. Architecture Constraints
+include::src/02_architecture_constraints.adoc[]
+
+<<<<
+// 3. Context and Scope
+include::src/03_context_and_scope.adoc[]
+
+<<<<
+// 4. Solution Strategy
+include::src/04_solution_strategy.adoc[]
+
+<<<<
+// 5. Building Block View
+include::src/05_building_block_view.adoc[]
+
+<<<<
+// 6. Runtime View
+include::src/06_runtime_view.adoc[]
+
+<<<<
+// 7. Deployment View
+include::src/07_deployment_view.adoc[]
+
+<<<<
+// 8. Concepts
+include::src/08_concepts.adoc[]
+
+<<<<
+// 9. Architecture Decisions
+include::src/09_architecture_decisions.adoc[]
+
+<<<<
+// 10. Quality Requirements
+include::src/10_quality_requirements.adoc[]
+
+<<<<
+// 11. Technical Risks
+include::src/11_technical_risks.adoc[]
+
+<<<<
+// 12. Glossary
+include::src/12_glossary.adoc[]
+
+
diff --git a/docs/arc42/common/styles/arc42-help-style.adoc b/docs/arc42/common/styles/arc42-help-style.adoc
new file mode 100644
index 0000000..03186bf
--- /dev/null
+++ b/docs/arc42/common/styles/arc42-help-style.adoc
@@ -0,0 +1,14 @@
+// Arc42 help callout styling
+ifdef::backend-html5[]
+++++
+<style>
+.arc42help {font-size:small; width: 14px; height: 16px; overflow: hidden; position: absolute; right: 0; padding: 2px 0 3px 2px;}
+.arc42help::before {content: "?";}
+.arc42help:hover {width:auto; height: auto; z-index: 100; padding: 10px;}
+.arc42help:hover::before {content: "";}
+@media print {
+    .arc42help {display:none;}
+}
+</style>
+++++
+endif::backend-html5[]
\ No newline at end of file
diff --git a/docs/arc42/images/arc42-logo.png b/docs/arc42/images/arc42-logo.png
new file mode 100644
index 0000000..88c76d0
Binary files /dev/null and b/docs/arc42/images/arc42-logo.png differ
diff --git a/docs/arc42/src/01_introduction_and_goals.adoc b/docs/arc42/src/01_introduction_and_goals.adoc
new file mode 100644
index 0000000..b048e34
--- /dev/null
+++ b/docs/arc42/src/01_introduction_and_goals.adoc
@@ -0,0 +1,124 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-introduction-and-goals]]
+== Introduction and Goals
+
+The arc42-generator turns one source into many downloads.
+The arc42 template is maintained once, as AsciiDoc, in the `arc42-template` repository — the
+Golden Master.
+Readers want it as Word, Markdown, HTML, LaTeX and a dozen other formats, in their own language,
+with or without the embedded help texts.
+This generator produces every one of those combinations and packs each into a ZIP archive ready
+for download (`lib/Packager.groovy:83`).
+
+Nobody who merely uses an arc42 template needs this repository.
+The README says so in its first sentence (`README.adoc:3`): users download finished archives
+from arc42.org.
+This repository serves the people who produce those archives.
+
+=== Requirements Overview
+
+[cols="1,4,2",options="header"]
+|===
+|ID |Requirement |Evidence
+
+|R-1
+|The generator shall produce the template for every language directory found in the Golden
+Master, without a code or configuration change per language.
+|`lib/Templates.groovy:37-40`
+
+|R-2
+|The generator shall produce two content flavors: `plain` without help texts and `with-help`
+with them.
+|`buildconfig.groovy:10-15`, `lib/Templates.groovy:75-90`
+
+|R-3
+|The generator shall convert each flavor into all 17 configured output formats.
+|`buildconfig.groovy:17-35`, `lib/Converter.groovy:60-71`
+
+|R-4
+|The generator shall package each (language, flavor, format) combination as one ZIP archive in
+the distribution directory.
+|`lib/Packager.groovy:71-93`, `buildconfig.groovy:38`
+
+|R-5
+|The generator shall run as a single command, both in a container and as a plain Groovy script
+with phase and format filters.
+|`docker-compose.yml:9`, `build.groovy:16-21`
+
+|R-6
+|The generator shall validate its own output: generated Markdown parses as CommonMark, and every
+image referenced by a `with-help` Markdown file exists.
+|`build-arc42.sh:94-104`, `build-arc42.sh:151-182`
+|===
+
+Success is measured by release effort, not by downloads.
+The generator has done its job when a maintainer produces a complete template release without
+handwork and without special knowledge (team answer).
+
+=== Quality Goals
+
+These are the top goals, in order.
+Chapter 10 carries one concrete scenario per goal and covers the remaining ISO 25010
+characteristics as derived scenarios.
+
+[cols="1,2,4,1",options="header"]
+|===
+|ID |Quality Goal (ISO 25010) |Motivation |Scenario
+
+|QG-1
+|Reliability
+|A build that silently drops a chapter, or reports success although conversions failed, damages
+every downstream download. This outranks build speed (team answer).
+|<<QS-01>>
+
+|QG-2
+|Maintainability
+|A handful of volunteers maintain the generator beside their actual work. Adding a language must
+cost nothing; adding a format must stay cheap.
+|<<QS-02>>
+
+|QG-3
+|Functional Suitability
+|Every maintained language must appear in every supported format. Partial output is worse than a
+failed build.
+|<<QS-03>>
+
+|QG-4
+|Performance Efficiency
+|Speed is an achieved side goal, not the top one. The budget is generous: a full build may take
+up to 20 minutes (team answer), today it takes 17.4 s.
+|<<QS-04>>
+|===
+
+=== Stakeholders
+
+[cols="1,2,3",options="header"]
+|===
+|Role |Contact |Expectation
+
+|Template user
+|Anonymous, reaches the result through arc42.org/download
+|Finds a current, complete template in the format and language of choice. Never sees this
+repository (`README.adoc:3`).
+
+|Release maintainer
+|arc42 core committers
+|Produces a full release with one command and pushes the archives into the template repository
+(`build-arc42.sh:198-205`).
+
+|Translator / contributor
+|Community, per language
+|Works only in the template repository; the generator picks up a new language directory by
+itself (`lib/Templates.groovy:38`).
+
+|arc42 founders
+|Gernot Starke, Peter Hruschka
+|Guard the conceptual integrity of the template; decide what the template contains
+(`docs/arc42-requirements.adoc:101-102`).
+
+|Generator developer
+|Whoever changes this repository
+|Finds a build that is readable without build-tool knowledge, and a documented path for adding a
+format (`CLAUDE.md:170-181`).
+|===
diff --git a/docs/arc42/src/02_architecture_constraints.adoc b/docs/arc42/src/02_architecture_constraints.adoc
new file mode 100644
index 0000000..e8e8ff0
--- /dev/null
+++ b/docs/arc42/src/02_architecture_constraints.adoc
@@ -0,0 +1,99 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-architecture-constraints]]
+== Architecture Constraints
+
+Three kinds of constraint bind this build: what it may run on, how the project works, and what
+the code has to look like.
+
+=== Technical Constraints
+
+[cols="1,3,2",options="header"]
+|===
+|ID |Constraint |Evidence
+
+|C-T-1
+|Groovy 5.0.3 on an OpenJDK 21 JRE, Alpine Linux 3.20. No JDK, no build tool.
+|`Dockerfile:4`, `:14`, `:23-26`, `:29`
+
+|C-T-2
+|AsciidoctorJ 2.5.10, AsciidoctorJ-Diagram 2.2.14 and GPars 1.2.1, pinned and resolved by Grape.
+|`lib/Converter.groovy:3-5`, `init-groovy-deps.groovy:3-5`
+
+|C-T-3
+|Pandoc 3.7.0.2 as an external binary; installed from a GitHub release when missing.
+|`build-arc42.sh:26-27`, `:39-40`
+
+|C-T-4
+|Docker is the only supported execution mode. Local execution is explicitly unsupported.
+|`README.adoc:17`, `:19`, `:113`
+
+|C-T-5
+|Open-source tooling only; no proprietary converter may be required.
+|`docs/arc42_build_process_requirements.md:190-199`
+
+|C-T-6
+|MIT licence for the generator.
+|`LICENSE.txt:1-3`
+|===
+
+=== Organizational and Process Constraints
+
+[cols="1,3,2",options="header"]
+|===
+|ID |Constraint |Evidence
+
+|C-O-1
+|Two repositories: this one holds the build logic, `arc42-template` holds only content. The
+template is consumed as a Git submodule.
+|`docs/arc42_build_process_requirements.md:86-104`, `.gitmodules:1-6`
+
+|C-O-2
+|Release is manual: build, inspect `arc42-template/dist/`, then commit and push inside the
+submodule.
+|`build-arc42.sh:198-205`, `CLAUDE.md:202-207`
+
+|C-O-3
+|Feature branch off main, Conventional Commits, pull request — binding for all new
+contributions, not technically enforced (team answer).
+|`CLAUDE.md:350`, `:356`
+
+|C-O-4
+|CI covers the documentation only: one workflow builds and publishes the microsite. The template
+build and the test suite are still started by hand. See <<TD-6>>.
+|`.github/workflows/documentation.yml`, requirement `docs/arc42_build_process_requirements.md:229`
+
+|C-O-5
+|Agent tooling in this repository asks before Bash and Write, and may not read `.env*` or
+`secrets/**`.
+|`settings.json:12-20`
+|===
+
+=== Conventional Constraints
+
+[cols="1,3,2",options="header"]
+|===
+|ID |Constraint |Evidence
+
+|C-C-1
+|LF line endings for shell, Docker and Groovy files; binaries excluded from normalisation.
+|`.gitattributes:2-10`, `:23-31`
+
+|C-C-2
+|Generated artifacts stay untracked: `build`, `src_gen`, IDE files, `.gradle`.
+|`.gitignore:1-8`
+
+|C-C-3
+|Fixed output layout: `build/src_gen/<LANG>/asciidoc/<STYLE>/src`, then
+`build/<LANG>/<FORMAT>/<STYLE>`, then `arc42-template/dist/`.
+|`lib/Templates.groovy:206-207`, `lib/Converter.groovy:47`, `buildconfig.groovy:38`
+
+|C-C-4
+|One class per pipeline stage in `lib/`, loaded by file name from the orchestrator.
+|`build.groovy:101-111`
+
+|C-C-5
+|A language directory is recognised by the pattern `/^[A-Z]{2,}$/` — two or more uppercase
+letters, so `UKR` and `ZH` qualify.
+|`lib/Templates.groovy:38`, `lib/Discovery.groovy:62`
+|===
diff --git a/docs/arc42/src/03_context_and_scope.adoc b/docs/arc42/src/03_context_and_scope.adoc
new file mode 100644
index 0000000..e340651
--- /dev/null
+++ b/docs/arc42/src/03_context_and_scope.adoc
@@ -0,0 +1,109 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-context-and-scope]]
+== Context and Scope
+
+The generator sits between one content repository and one distribution directory.
+Everything else it touches is a tool it calls.
+
+=== Business Context
+
+[plantuml,03_business_context,svg]
+....
+@startuml
+!include <C4/C4_Context.puml>
+
+Person(maintainer, "Release maintainer", "arc42 core committer")
+Person(translator, "Translator", "community contributor")
+Person(user, "Template user", "architect, developer")
+
+System(generator, "arc42-generator", "Builds every template variant from the Golden Master")
+System_Ext(goldenmaster, "arc42-template repository", "AsciiDoc Golden Master and dist/ archives")
+System_Ext(site, "arc42.org/download", "Public download page")
+
+Rel(translator, goldenmaster, "contributes a translation")
+Rel(maintainer, generator, "starts the build")
+Rel(generator, goldenmaster, "reads the Golden Master, writes dist/*.zip")
+Rel(maintainer, goldenmaster, "commits and pushes the archives")
+Rel(site, goldenmaster, "links the archives")
+Rel(user, site, "downloads a template")
+@enduml
+....
+
+[cols="1,2,2",options="header"]
+|===
+|Partner |Input |Output
+
+|arc42-template repository
+|AsciiDoc sources per language, images, `version.properties`, shared `common/` files
+(`lib/Templates.groovy:194`, `:213`, `:231-234`)
+|ZIP archives in `dist/`, one per language, flavor and format (`buildconfig.groovy:38`)
+
+|Release maintainer
+|The decision to build, optionally a phase and a format filter (`build.groovy:16-21`)
+|Console log with counts and durations; the release instructions printed at the end
+(`build-arc42.sh:198-205`)
+
+|Translator
+|A new language directory matching `/^[A-Z]{2,}$/` in the Golden Master
+|Their language appears in the next build without any change here (`lib/Templates.groovy:38`)
+|===
+
+=== Technical Context
+
+[plantuml,03_technical_context,svg]
+....
+@startuml
+!include <C4/C4_Container.puml>
+
+Person(maintainer, "Release maintainer")
+
+System_Boundary(c, "Build host or container") {
+  Container(build, "build.groovy + lib/", "Groovy 5, JVM 21", "Pipeline orchestrator")
+  Container(asciidoctor, "AsciidoctorJ 2.5.10", "in-process library", "AsciiDoc to HTML and DocBook")
+  Container(pandoc, "Pandoc 3.7.0.2", "external process", "DocBook to every other format")
+  Container(cmark, "cmark", "external process", "CommonMark validation")
+  ContainerDb(fs, "Working tree", "file system", "build/src_gen, build/<LANG>/<FORMAT>, dist/")
+}
+
+System_Ext(git, "GitHub", "Golden Master submodule, Pandoc release")
+
+Rel(maintainer, build, "docker compose up / groovy build.groovy")
+Rel(build, asciidoctor, "Asciidoctor.Factory.create(), convertFile()")
+Rel(build, pandoc, "ProcessBuilder, UTF-8 environment")
+Rel(build, fs, "reads and writes")
+Rel(build, git, "submodule update, checkout master, pull")
+Rel(build, cmark, "validates generated Markdown")
+@enduml
+....
+
+[cols="1,2,3",options="header"]
+|===
+|Interface |Technical form |Evidence
+
+|Golden Master
+|Read-only file access below the configured source path, refreshed by Git before each
+containerised build
+|`buildconfig.groovy:3`, `lib/Templates.groovy:31`, `build-arc42.sh:68-69`
+
+|AsciidoctorJ
+|In-process library call, one shared instance per `Converter`, `SafeMode.UNSAFE`
+|`lib/Converter.groovy:33`, `:100`, `:106`
+
+|Pandoc
+|Child process with an explicit argument vector, working directory set to the DocBook output
+directory, `LC_ALL` and `LANG` forced to UTF-8
+|`lib/Converter.groovy:181-187`, `:208-217`
+
+|cmark
+|Child process per generated Markdown file of `build/EN/markdown`
+|`build-arc42.sh:94-104`
+
+|Package installation
+|`wget` plus `dpkg -i` as root when Pandoc is absent — the one place the build modifies its host
+|`build-arc42.sh:39-41`
+
+|Distribution
+|Write access into the submodule's `dist/` directory
+|`buildconfig.groovy:38`, `lib/Packager.groovy:84-86`
+|===
diff --git a/docs/arc42/src/04_solution_strategy.adoc b/docs/arc42/src/04_solution_strategy.adoc
new file mode 100644
index 0000000..e0d9fd6
--- /dev/null
+++ b/docs/arc42/src/04_solution_strategy.adoc
@@ -0,0 +1,57 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-solution-strategy]]
+== Solution Strategy
+
+Five decisions carry the design. Each one serves a quality goal from chapter 1.2 and is recorded
+as an ADR in chapter 9.
+
+[cols="1,3,1,1",options="header"]
+|===
+|Strategy |What it means |Serves |ADR
+
+|Plain script instead of a build tool
+|The pipeline is a Groovy script that loads four classes and runs four phases. No build tool, no
+generated build logic, no two-pass construction.
+|QG-2
+|<<ADR-001>>
+
+|DocBook as pivot format
+|HTML and AsciiDoc are produced directly; every other format goes AsciiDoc -> DocBook -> Pandoc.
+One pivot instead of seventeen converters.
+|QG-3, QG-2
+|<<ADR-003>>
+
+|Convention over configuration
+|Languages are discovered from the file system, not configured. A new translation needs no code
+and no config change.
+|QG-2
+|<<ADR-002>>
+
+|Parallelism where it is free
+|A GPars pool sized to the available processors converts templates concurrently and builds all
+archives concurrently.
+|QG-4
+|<<ADR-004>>
+
+|Container as the supported environment
+|All tools — JRE, Groovy, Pandoc, cmark — are pinned in one image, so a build behaves the same
+on any host.
+|QG-3, QG-4
+|<<ADR-005>>
+|===
+
+The pipeline itself is four phases in a fixed order, each guarded by the phase argument
+(`build.groovy:129-202`):
+
+. *Generate* — strip the unwanted features out of the Golden Master and write both flavors
+(`lib/Templates.groovy:155-257`).
+. *Discover* — scan the generated tree and build one metadata record per (language, flavor)
+(`lib/Discovery.groovy:43-154`).
+. *Convert* — run every template through every format (`lib/Converter.groovy:410-472`).
+. *Package* — zip each output directory into the distribution folder
+(`lib/Packager.groovy:102-185`).
+
+Discovery memoises its result for the lifetime of the process, with an explicit invalidation
+method, so the scan runs once even when two phases need it (`lib/Discovery.groovy:17`, `:45-47`,
+`:152`, `:159-161`).
diff --git a/docs/arc42/src/05_building_block_view.adoc b/docs/arc42/src/05_building_block_view.adoc
new file mode 100644
index 0000000..92ab51c
--- /dev/null
+++ b/docs/arc42/src/05_building_block_view.adoc
@@ -0,0 +1,168 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-building-block-view]]
+== Building Block View
+
+=== Whitebox Overall System
+
+The orchestrator owns the sequence; four classes own one pipeline stage each.
+`build.groovy` loads them by file name through a `GroovyClassLoader` and passes each one the
+parsed configuration (`build.groovy:101-123`).
+
+[plantuml,05_level1,svg]
+....
+@startuml
+!include <C4/C4_Component.puml>
+
+Container_Boundary(gen, "arc42-generator") {
+  Component(orch, "build.groovy", "Groovy script", "Parses CLI arguments, loads config and classes, runs four guarded phases")
+  Component(templates, "Templates", "Groovy class", "Golden Master to flavored AsciiDoc")
+  Component(discovery, "Discovery", "Groovy class", "Scans generated tree, builds metadata, memoises")
+  Component(converter, "Converter", "Groovy class", "AsciidoctorJ and Pandoc conversion, parallel")
+  Component(packager, "Packager", "Groovy class", "ZIP archives, parallel")
+  ComponentDb(config, "buildconfig.groovy", "ConfigSlurper script", "Flavors, formats, paths")
+}
+
+Rel(orch, config, "parses")
+Rel(orch, templates, "createFromGoldenMaster()")
+Rel(orch, discovery, "discoverTemplates()")
+Rel(orch, converter, "convertAll(templates, formats, parallel)")
+Rel(orch, packager, "createAllDistributions(...)")
+Rel(discovery, converter, "List<Map> template metadata")
+@enduml
+....
+
+==== build.groovy
+
+_Purpose:_ single entry point. Parses the phase, the format filter and the parallel switch, loads
+`buildconfig.groovy` through `ConfigSlurper`, instantiates the four classes and runs the phases
+that the argument selects.
+
+_Interface:_ `groovy build.groovy [templates|convert|distribution|all] [--format=X]
+[--parallel=false]` (`build.groovy:16-21`, `:45-52`).
+
+_Quality note:_ an unrecognised phase matches no guard and the script still prints
+"BUILD SUCCESSFUL" — see <<TD-3>>.
+
+==== Templates
+
+_Purpose:_ turns the Golden Master into flavored AsciiDoc below `build/src_gen/`.
+
+_Responsibilities:_ discover languages by regex (`lib/Templates.groovy:30-48`), remove unwanted
+features (`:75-90`), rewrite include paths for the flat output layout (`:64-74`), copy images by
+flavor and the shared `common/` tree (`:101-134`, `:177-190`).
+
+_Interface:_ `createFromGoldenMaster()`, plus `discoverLanguages()` and `removeFeatures()` which
+the tests call directly (`test-templates.groovy:21`, `:43`).
+
+==== Discovery
+
+_Purpose:_ finds what phase 1 produced and describes it.
+
+_Responsibilities:_ scan `build/src_gen/`, validate that each style has a `src/` directory with
+`.adoc` files, read `version.properties` as UTF-8, and build one 13-field metadata map per
+template (`lib/Discovery.groovy:43-154`).
+
+_Interface:_ `discoverTemplates()`, the query methods `getLanguages()`, `getStyles()`,
+`findByLanguage()`, `findByStyle()`, `findTemplate()`, and `validate()` (`:168-241`).
+
+==== Converter
+
+_Purpose:_ produces every output format. This is the largest block; see <<level2-converter>>.
+
+_Interface:_ `convertAll(List<Map> templates, List<String> formats, boolean parallel)`
+(`lib/Converter.groovy:410`).
+
+==== Packager
+
+_Purpose:_ one ZIP per (language, flavor, format).
+
+_Responsibilities:_ walk the output directory, write entries with paths relative to it
+(`lib/Packager.groovy:44-52`), normalise the flavor name for the file name so `with-help` becomes
+`withhelp` (`:80`), and write into the distribution directory (`:84-86`).
+
+_Interface:_ `createAllDistributions(...)`, `createDistribution(language, style, format)`,
+`cleanDistributions()`.
+
+==== Interface: template metadata
+
+The one data structure that crosses every stage boundary is an untyped `Map` with 13 keys —
+language, style, sourcePath, srcDir, imagesDir, hasImages, mainFile, mainFileName, adocFileCount,
+commonDir, versionProperties, revnumber (`lib/Discovery.groovy:127-140`).
+There is no DTO and no schema; a renamed key fails at runtime. See <<TD-7>>.
+
+[[level2-converter]]
+=== Level 2: Converter
+
+The format name decides the path. A four-way dispatch chain routes each conversion
+(`lib/Converter.groovy:60-71`).
+
+[plantuml,05_level2_converter,svg]
+....
+@startuml
+!include <C4/C4_Component.puml>
+
+Component_Ext(adoc, "AsciidoctorJ", "library")
+Component_Ext(pandoc, "Pandoc", "process")
+
+Container_Boundary(conv, "Converter") {
+  Component(dispatch, "convertTemplate()", "dispatch", "Four-way chain on the format name")
+  Component(html, "convertToHTML()", "direct", "AsciiDoc to HTML5")
+  Component(copy, "copyAsciidoc()", "direct", "Copies sources, prefixes includes with src/")
+  Component(db, "convertToDocBook()", "pivot", "AsciiDoc to DocBook XML")
+  Component(sp, "convertViaPandoc()", "single page", "DocBook to one output file")
+  Component(mp, "convertViaPandocMP()", "multi page", "One output file per chapter")
+  Component(attrs, "createAttributes()", "factory", "Seven fixed plus three version attributes")
+  Component(table, "getPandocConfig()", "table", "pandocFormat, extension, args per format")
+}
+
+Rel(dispatch, html, "format == html")
+Rel(dispatch, copy, "format == asciidoc")
+Rel(dispatch, db, "format == docbook")
+Rel(dispatch, sp, "everything else")
+Rel(dispatch, mp, "markdownMP, mkdocsMP, markdownMPStrict, gitHubMarkdownMP")
+Rel(sp, db, "produces the pivot")
+Rel(mp, db, "one XML per chapter")
+Rel(html, adoc, "convertFile")
+Rel(db, adoc, "convertFile")
+Rel(sp, pandoc, "ProcessBuilder")
+Rel(mp, pandoc, "ProcessBuilder per chapter")
+Rel(sp, table, "reads")
+Rel(db, attrs, "reads")
+@enduml
+....
+
+==== White Box `convertViaPandoc` (single page)
+
+Derives a sibling `docbook` directory from the output path, converts the template to DocBook
+there, copies the images next to the XML so Pandoc resolves relative paths, then runs Pandoc from
+that directory (`lib/Converter.groovy:151-154`, `:157-170`, `:206-217`).
+A non-zero Pandoc exit raises a `RuntimeException` (`:219-222`).
+
+Two post-processing steps follow: LaTeX thin spaces become ordinary spaces (`:225-228`), and an
+HTML charset tag would be added — a branch that can never run, because `html` is routed to
+AsciidoctorJ one level up. See <<TD-2>>.
+
+==== White Box `convertViaPandocMP` (multi page)
+
+Converts each chapter file separately to DocBook, skipping the main file and `config.adoc`, then
+runs Pandoc once per XML file (`lib/Converter.groovy:303-315`, `:337-346`).
+For `mkdocsMP` it deletes `config.md` and `about-arc42.md` afterwards (`:348`).
+
+Two failures are absorbed here: an AsciidoctorJ exception per chapter is swallowed on purpose, to
+skip config-only files (`:313`), and a failing Pandoc call only prints a warning (`:345`), so a
+failed chapter disappears from the output without any error. See <<R-1>>.
+
+=== Level 3: feature removal
+
+`removeFeatures` is the one place where a flavor becomes what it is
+(`lib/Templates.groovy:75-90`).
+It works in two ways: it deletes `[role="arc42<feature>"]` delimited blocks, and for `help` it
+additionally deletes the `ifdef::arc42help[]` and `endif::arc42help[]` marker lines while keeping
+their body.
+
+The feature list comes from `buildconfig.groovy:7`, the flavor definition from `:10-15`; a flavor
+is a list of features to keep, everything else is subtracted (`lib/Templates.groovy:205`).
+Of the two declared features only `help` exists in the Golden Master: a check of the template
+repository found `arc42example` zero times against 995 occurrences of `arc42help` in 168 files.
+The `example` branch therefore runs a regex over every file that never matches. See <<TD-1>>.
diff --git a/docs/arc42/src/06_runtime_view.adoc b/docs/arc42/src/06_runtime_view.adoc
new file mode 100644
index 0000000..02c1da5
--- /dev/null
+++ b/docs/arc42/src/06_runtime_view.adoc
@@ -0,0 +1,110 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-runtime-view]]
+== Runtime View
+
+Three scenarios matter: the full build, a conversion that fails, and the submodule refresh that
+precedes every containerised run.
+
+=== Full build
+
+[plantuml,06_full_build,svg]
+....
+@startuml
+actor Maintainer
+participant "build.groovy" as B
+participant "Templates" as T
+participant "Discovery" as D
+participant "Converter" as C
+participant "Packager" as P
+
+Maintainer -> B: groovy build.groovy
+B -> B: ConfigSlurper parses buildconfig.groovy
+B -> B: GroovyClassLoader loads four classes
+B -> T: createFromGoldenMaster()
+T -> T: discoverLanguages() by /^[A-Z]{2,}$/
+loop per language, per flavor
+  T -> T: removeFeatures(), adjustIncludePaths()
+  T -> T: copy images and common files
+end
+B -> D: discoverTemplates()
+D --> B: List<Map> metadata (memoised)
+B -> C: convertAll(templates, formats, parallel)
+loop parallel per template
+  loop sequential per format
+    C -> C: convertTemplate()
+  end
+end
+B -> P: createAllDistributions(templates, formats, parallel)
+loop parallel per (template, format)
+  P -> P: createZip()
+end
+B --> Maintainer: counts, durations, BUILD SUCCESSFUL
+@enduml
+....
+
+The parallelism is one-dimensional: the template loop runs in a GPars pool sized to the available
+processors, the format loop inside it is sequential (`lib/Converter.groovy:429-432`).
+Counters are incremented inside a `synchronized(this)` block (`:433`).
+
+=== A conversion fails
+
+[plantuml,06_failure,svg]
+....
+@startuml
+participant "Converter.convertAll" as A
+participant "convertTemplate" as T
+participant "Pandoc" as P
+
+A -> T: convertTemplate(template, format)
+T -> P: ProcessBuilder(pandoc ...)
+P --> T: exit code != 0
+T -> T: RuntimeException
+T -> T: catch, print message and stack trace
+T --> A: null
+A -> A: failed++
+note right of A
+  The run continues with the next format.
+  The process still exits with code 0.
+end note
+@enduml
+....
+
+Each conversion is isolated per (template, format) pair: the failure is logged, counted, and the
+run continues (`lib/Converter.groovy:74-78`, `:437-440`).
+Nothing propagates to the exit code, so a build with failed conversions still prints
+"BUILD SUCCESSFUL" (`build.groovy:211-215`). This is <<R-2>>, the most direct threat to QG-1.
+
+The multi-page path is quieter still: a failing Pandoc call there only prints a warning
+(`lib/Converter.groovy:345`), so the chapter is missing from the output and no counter notices.
+
+=== Submodule refresh
+
+[plantuml,06_submodule,svg]
+....
+@startuml
+participant "build-arc42.sh" as S
+participant "Git" as G
+
+S -> S: rm -rf arc42-template
+loop up to 3 attempts
+  S -> S: remove stale index.lock files
+  S -> G: submodule init, submodule update --force
+  S -> G: checkout master, pull
+  alt success
+    S -> S: break
+  else failure
+    S -> S: sleep 2
+  end
+end
+alt still failing after 3 attempts
+  S --> S: exit 1
+end
+@enduml
+....
+
+This is the only retry in the whole system (`build-arc42.sh:66-78`).
+It deletes the entire submodule directory first, which discards uncommitted template work —
+see <<R-3>>.
+It also checks out `master` and pulls, so the output follows whatever upstream holds at build
+time rather than the recorded submodule commit (`build-arc42.sh:69`, see <<R-4>>).
diff --git a/docs/arc42/src/07_deployment_view.adoc b/docs/arc42/src/07_deployment_view.adoc
new file mode 100644
index 0000000..2288ecf
--- /dev/null
+++ b/docs/arc42/src/07_deployment_view.adoc
@@ -0,0 +1,67 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-deployment-view]]
+== Deployment View
+
+=== Infrastructure Level 1
+
+[plantuml,07_deployment,svg]
+....
+@startuml
+!include <C4/C4_Deployment.puml>
+
+Deployment_Node(host, "Build host", "Linux, macOS, Windows or GitHub Codespaces") {
+  Deployment_Node(docker, "Docker Engine", "container runtime") {
+    Deployment_Node(img, "arc42-generator:9.1.0", "Alpine 3.20") {
+      Container(groovy, "Groovy 5.0.3 + JRE 21", "runtime", "Runs build.groovy and lib/")
+      Container(pandoc, "Pandoc 3.7.0.2", "binary", "DocBook to target formats")
+      Container(cmark, "cmark", "binary", "CommonMark validation")
+      Container(grapes, "Grape cache", "/root/.groovy", "AsciidoctorJ, GPars, pre-populated")
+    }
+  }
+  Deployment_Node(mount, "/workspace", "bind mount of the repository") {
+    ContainerDb(tree, "Working tree", "file system", "arc42-template/, build/, dist/")
+  }
+}
+
+Rel(groovy, tree, "reads and writes")
+Rel(groovy, pandoc, "child process")
+Rel(groovy, cmark, "child process")
+@enduml
+....
+
+_Motivation:_ every tool version is fixed in one image, so a build behaves the same on any host
+and no developer has to install Java, Groovy or Pandoc (`README.adoc:113`).
+
+_Mapping:_ the repository is bind-mounted at `/workspace`, the working directory is `/workspace`,
+and the container command is `./build-arc42.sh` (`docker-compose.yml:4-9`, `Dockerfile:82`).
+
+=== Infrastructure Level 2
+
+==== Builder stage
+
+Installs the JRE, bash, git, wget, unzip, Pandoc and cmark from the Alpine repositories, unpacks
+Groovy 5.0.3, then pre-populates the Grape cache and strips source and javadoc JARs from it
+(`Dockerfile:13-20`, `:23-26`, `:40-45`).
+
+==== Runtime stage
+
+A second Alpine stage with runtime packages only. Groovy and the Grape cache are copied from the
+builder; only `build.groovy`, `buildconfig.groovy`, `init-groovy-deps.groovy`, `build-arc42.sh`
+and `lib/` are copied in (`Dockerfile:53-58`, `:64-68`, `:78-79`).
+
+Consequence: the test scripts are not in the image, so `run-all-tests.groovy` cannot run inside
+the runtime container (`Dockerfile:78-79` against `run-all-tests.groovy:22-36`). See <<TD-5>>.
+
+==== GitHub Codespaces
+
+The devcontainer declares write permission on `arc42/arc42-template`, because the release step
+pushes archives into that repository (`.devcontainer/devcontainer.json:4-9`).
+Git ownership checks are disabled inside the image so bind-mounted trees work
+(`Dockerfile:61`, narrower variant at `build-arc42.sh:52-53`).
+
+==== Local execution without Docker
+
+Technically possible — Groovy 4+, a JRE 11+ and Pandoc 3+ suffice (`CLAUDE.md:126-132`) — but
+explicitly unsupported (`README.adoc:19`). Grape then resolves AsciidoctorJ and GPars over the
+network at script start (`lib/Converter.groovy:3-5`), which the container avoids.
diff --git a/docs/arc42/src/08_concepts.adoc b/docs/arc42/src/08_concepts.adoc
new file mode 100644
index 0000000..1346ce4
--- /dev/null
+++ b/docs/arc42/src/08_concepts.adoc
@@ -0,0 +1,173 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-concepts]]
+== Cross-cutting Concepts
+
+Six concepts cut across the building blocks. The first five are the baseline every system in
+this project documents; the sixth exists because the generator is a multilingual text pipeline.
+
+[[concept-threat-model]]
+=== Threat Model
+
+The trust boundary is wide on purpose. Input and output are public open-source content, the build
+runs on maintainer machines, there is no user data and no running service.
+The threats below are named so that the acceptance is explicit rather than silent; they are
+accepted, not mitigated (<<ADR-006>>).
+
+[cols="1,1,3,2,1",options="header"]
+|===
+|ID |STRIDE |Threat |Evidence |Status
+
+|T-001
+|Tampering, Elevation of Privilege
+|A malicious translation pull request adds AsciiDoc that reads or writes arbitrary files during
+conversion, because Asciidoctor runs unrestricted.
+|`lib/Converter.groovy:100`, `:132`, `:311`
+|accepted
+
+|T-002
+|Tampering
+|A compromised upstream template repository is pulled unverified and shipped as ZIP archives; the
+build follows `master`, not the recorded submodule commit.
+|`build-arc42.sh:69`
+|accepted
+
+|T-003
+|Tampering
+|The Pandoc `.deb` and the Groovy ZIP are downloaded and installed without checksum or signature.
+|`build-arc42.sh:39-41`, `Dockerfile:23-25`
+|accepted
+
+|T-004
+|Spoofing
+|The published archives carry neither signature nor checksum, so a downloader cannot verify their
+origin.
+|`lib/Packager.groovy:83`
+|accepted
+
+|T-005
+|Elevation of Privilege
+|Git ownership checks are disabled for every directory inside the image.
+|`Dockerfile:61`
+|accepted
+|===
+
+[[concept-security]]
+=== Security
+
+One control exists, and it protects the developer's agent session rather than the build: reading
+`.env*` and `secrets/**` is denied, and Bash and Write require confirmation
+(`settings.json:12-20`). It closes none of T-001 to T-005.
+
+For every threat above the decision is the same: accept it, because the assets are public and the
+blast radius ends at the maintainer's own machine.
+Should that change — a hosted build service, signed releases, or template content from
+unreviewed sources — T-001 to T-004 turn into open findings and this section needs mitigations.
+
+[[concept-test]]
+=== Test
+
+Testing is integration-level only, deliberately (`TEST-REPORT.md:15`).
+The pyramid is inverted: there are no unit tests, three end-to-end suites, and two post-build
+validations in the shell script.
+
+[cols="1,2,2,2",options="header"]
+|===
+|Level |What it covers |Runs |Evidence
+
+|Suite: template generation
+|Language discovery, feature removal, output structure per language and flavor
+|`groovy test-templates.groovy`
+|`test-templates.groovy:21`, `:43-48`, `:62-74`
+
+|Suite: discovery
+|Metadata completeness, both flavors present, EN and DE present
+|`groovy test-discovery.groovy`
+|`test-discovery.groovy:30-34`, `:49-50`, `:79`
+
+|Suite: conversion
+|HTML, DocBook, Markdown, DOCX produced; multi-page yields more than one file
+|`groovy test-converter.groovy`
+|`test-converter.groovy:47`, `:55`, `:70`, `:78`, `:89-90`
+
+|Validation: CommonMark
+|Generated Markdown parses; non-fatal
+|`./build-arc42.sh`
+|`build-arc42.sh:94-104`, `:109-111`
+
+|Validation: images
+|Image directories exist and are non-empty; every Markdown image reference resolves; non-fatal
+|`./build-arc42.sh`
+|`build-arc42.sh:139-145`, `:174-177`
+|===
+
+The runner spawns one `groovy` process per suite and aggregates exit codes
+(`run-all-tests.groovy:55-64`, `:147-153`).
+No test carries a requirement or business-rule identifier; suites are named after the class they
+exercise. Traceability back to chapter 1.1 is therefore manual today — see <<TD-8>>.
+
+[[concept-observability]]
+=== Observability
+
+`println` to standard output, nothing else. No logging framework, no levels, no log file
+(`build.groovy:61-67`, `lib/Converter.groovy:436-439`, `lib/Packager.groovy:141-145`).
+
+What the run reports: progress per conversion, counts of completed, failed and skipped items, and
+a duration per phase (`lib/Converter.groovy:466-470`, `lib/Packager.groovy:173-178`).
+
+What it does not report: failure in the exit status. Conversion failures are counted but never
+change the exit code, and the packager's `failed` counter is never incremented, so its summary
+always reads `Failed: 0` (`lib/Packager.groovy:116`, `:177`). Both are <<R-2>>.
+
+[[concept-error-handling]]
+=== Error Handling
+
+Two boundaries, one retry, no breaker.
+
+[cols="1,3,2",options="header"]
+|===
+|Pattern |Where it applies |Evidence
+
+|Fail fast
+|Configuration load, class load and any phase exception terminate the process with exit code 1.
+|`build.groovy:83-86`, `:113-117`, `:130-136`
+
+|Fail soft
+|A single conversion is isolated per (template, format); the failure is logged and counted, the
+run continues.
+|`lib/Converter.groovy:74-78`
+
+|Retry
+|Git submodule update: three attempts, stale lock cleanup before each, a fixed two-second pause,
+hard exit afterwards.
+|`build-arc42.sh:66-78`
+
+|Deliberate swallow
+|Per-chapter AsciidoctorJ exceptions in the multi-page path, to skip config-only files.
+|`lib/Converter.groovy:313`
+
+|Silent fallback
+|An unknown format falls back to an identity Pandoc descriptor instead of being rejected.
+|`lib/Converter.groovy:400`
+
+|Circuit breaker, compensation
+|Neither exists. Nothing throttles or reverses after repeated failures.
+|—
+|===
+
+Given QG-1, the two silent paths — the warning-only Pandoc failure at `lib/Converter.groovy:345`
+and the missing exit code — are the gap this concept has to close; they are tracked as <<R-1>>
+and <<R-2>>.
+
+[[concept-encoding]]
+=== Encoding and Localisation
+
+The pipeline is multilingual, so encoding is explicit everywhere rather than left to the platform
+default: every read and write names UTF-8 (`lib/Templates.groovy:199`, `:218`, `:226`, `:241`;
+`lib/Discovery.groovy:121`), and the Pandoc child process gets `LC_ALL` and `LANG` set to
+`en_US.UTF-8` (`lib/Converter.groovy:213-214`).
+
+One language-specific rule exists: LaTeX output for Russian adds the font encoding `T1,T2A`
+(`lib/Converter.groovy:195-197`).
+Version metadata — `revnumber`, `revdate`, `revremark` — travels per language from
+`version.properties` into the AsciiDoc attributes (`lib/Converter.groovy:368-373`).
diff --git a/docs/arc42/src/09_architecture_decisions.adoc b/docs/arc42/src/09_architecture_decisions.adoc
new file mode 100644
index 0000000..ce5bfd2
--- /dev/null
+++ b/docs/arc42/src/09_architecture_decisions.adoc
@@ -0,0 +1,24 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-design-decisions]]
+== Architecture Decisions
+
+Seven decisions shape this build. Each is recorded in Nygard form as its own file under
+`docs/specs/adrs/` and scored with a three-point Pugh matrix (`+1` better, `0` equal, `-1` worse)
+against the quality goals of chapter 1.2 and the maintenance effort. The baseline column is the
+option that was in place at the time.
+
+include::../../specs/adrs/arc42-generator-adr-001-groovy-instead-of-gradle.adoc[leveloffset=+2]
+
+include::../../specs/adrs/arc42-generator-adr-002-language-auto-discovery.adoc[leveloffset=+2]
+
+include::../../specs/adrs/arc42-generator-adr-003-docbook-pivot-format.adoc[leveloffset=+2]
+
+include::../../specs/adrs/arc42-generator-adr-004-parallelism-over-templates.adoc[leveloffset=+2]
+
+include::../../specs/adrs/arc42-generator-adr-005-docker-only-environment.adoc[leveloffset=+2]
+
+include::../../specs/adrs/arc42-generator-adr-006-accept-security-risk.adoc[leveloffset=+2]
+
+include::../../specs/adrs/arc42-generator-adr-007-golden-master-separate-repository.adoc[leveloffset=+2]
+
diff --git a/docs/arc42/src/10_quality_requirements.adoc b/docs/arc42/src/10_quality_requirements.adoc
new file mode 100644
index 0000000..2ce7648
--- /dev/null
+++ b/docs/arc42/src/10_quality_requirements.adoc
@@ -0,0 +1,148 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-quality-scenarios]]
+== Quality Requirements
+
+=== Quality Requirements Overview
+
+All eight ISO/IEC 25010 characteristics are covered. Four of them concretise a top goal from
+chapter 1.2; the remaining four are derived from measurable behaviour in the code.
+No target number here is invented — every response measure is quoted from the repository.
+
+[cols="1,2,1,1",options="header"]
+|===
+|ID |ISO 25010 characteristic |Relation to chapter 1.2 |Priority
+
+|<<QS-01>> |Reliability |concretises QG-1 |high
+|<<QS-02>> |Maintainability |concretises QG-2 |high
+|<<QS-03>> |Functional Suitability |concretises QG-3 |high
+|<<QS-04>> |Performance Efficiency |concretises QG-4 |medium
+|<<QS-05>> |Compatibility |derived |medium
+|<<QS-06>> |Interaction Capability |derived |medium
+|<<QS-07>> |Security |derived |low, accepted (<<ADR-006>>)
+|<<QS-08>> |Flexibility |derived |medium
+|===
+
+=== Quality Scenarios
+
+[[QS-01]]
+==== QS-01 A failed conversion must not pass as success (QG-1)
+
+[cols="1,4"]
+|===
+|Source |Pandoc or AsciidoctorJ, during a full build
+|Stimulus |One chapter, or one (template, format) conversion, fails
+|Artifact |`Converter.convertAll` and the exit path of `build.groovy`
+|Environment |Normal operation, full build of all languages and formats
+|Response |The failure is counted, named in the log, and visible in the process result
+|Response Measure |Today: the single-page path counts the failure (`lib/Converter.groovy:437-440`)
+but the process still exits 0 (`build.groovy:211-215`), and the multi-page path only prints a
+warning (`:345`). Target: exit code non-zero whenever `failed > 0`. Gap tracked as <<R-1>> and
+<<R-2>>.
+|===
+
+[[QS-02]]
+==== QS-02 Adding a language costs nothing, adding a format costs three edits (QG-2)
+
+[cols="1,4"]
+|===
+|Source |A translator, respectively a generator developer
+|Stimulus |A new language directory appears; or a new output format is requested
+|Artifact |`Templates.discoverLanguages`, respectively `buildconfig.groovy` and `Converter`
+|Environment |Development time
+|Response |The language is picked up without any change here; the format is added at the known
+places
+|Response Measure |Language: zero changed files (`lib/Templates.groovy:37-40`). Format: exactly
+three edits — `buildconfig.groovy:17-35`, the dispatch chain `lib/Converter.groovy:60-71`, and the
+descriptor table `:382-398`; procedure documented at `CLAUDE.md:170-181`.
+|===
+
+[[QS-03]]
+==== QS-03 Every maintained language appears in every format (QG-3)
+
+[cols="1,4"]
+|===
+|Source |Release maintainer
+|Stimulus |A full build for a release
+|Artifact |The whole pipeline
+|Environment |Container, all languages, all formats
+|Response |One ZIP archive exists per language, flavor and format
+|Response Measure |languages x 2 flavors x 17 formats, computed and printed by the build itself
+(`build.groovy:220-223`); last measured run: 18 templates from nine languages
+(`TEST-REPORT.md:119`), archives named per `lib/Packager.groovy:83`.
+|===
+
+[[QS-04]]
+==== QS-04 A full build stays well inside the time budget (QG-4)
+
+[cols="1,4"]
+|===
+|Source |Release maintainer
+|Stimulus |Full build, all languages and formats
+|Artifact |Conversion and packaging phases
+|Environment |Developer machine, parallelism enabled
+|Response |The build completes without manual intervention
+|Response Measure |Budget 20 minutes (team answer). Measured: 17.4 s end to end, of which 10.7 s
+template generation and 0.6 s packaging (`TEST-REPORT.md:365`, `:102`, `:274`) — more than two
+orders of magnitude inside the budget.
+|===
+
+[[QS-05]]
+==== QS-05 Generated Markdown parses as CommonMark (derived)
+
+[cols="1,4"]
+|===
+|Source |A downstream Markdown consumer, for example GitHub or MkDocs
+|Stimulus |Reads a generated Markdown file
+|Artifact |Pandoc output of the Markdown family of formats
+|Environment |Post-build validation in `build-arc42.sh`
+|Response |The file parses without error
+|Response Measure |`cmark` exits 0 for every file in `build/EN/markdown`
+(`build-arc42.sh:94-104`). The check is non-fatal (`:109-111`) and covers EN only.
+|===
+
+[[QS-06]]
+==== QS-06 One command produces everything (derived)
+
+[cols="1,4"]
+|===
+|Source |Release maintainer, possibly a first-time one
+|Stimulus |Wants all outputs, or just one format for a quick check
+|Artifact |CLI of `build.groovy` and the container entry point
+|Environment |Any host with Docker
+|Response |The build runs and reports progress line by line
+|Response Measure |One command: `docker compose up` (`docker-compose.yml:9`); optional narrowing
+by phase and format (`build.groovy:16-21`); one progress line per conversion
+(`lib/Converter.groovy:436`).
+|===
+
+[[QS-07]]
+==== QS-07 Hostile template content is executed, knowingly (derived)
+
+[cols="1,4"]
+|===
+|Source |A contributor with write access to the Golden Master
+|Stimulus |Template content contains an include or a macro that reads or writes files
+|Artifact |AsciidoctorJ conversion
+|Environment |Build on a maintainer machine
+|Response |The content is processed without restriction
+|Response Measure |`SafeMode.UNSAFE` at all three call sites (`lib/Converter.groovy:100`, `:132`,
+`:311`); no checksum on any download (`build-arc42.sh:39-41`). Accepted, see <<ADR-006>> and
+T-001 to T-005.
+|===
+
+[[QS-08]]
+==== QS-08 The same build runs on every supported host (derived)
+
+[cols="1,4"]
+|===
+|Source |A maintainer on Linux, macOS, Windows or GitHub Codespaces
+|Stimulus |Starts the build
+|Artifact |Container image, shell script, Git configuration
+|Environment |amd64 or arm64
+|Response |The pipeline runs and produces identical output
+|Response Measure |Architecture-specific Pandoc package selected at runtime
+(`build-arc42.sh:23-36`); LF enforced for scripts (`.gitattributes:2-7`); Codespaces permissions
+declared (`.devcontainer/devcontainer.json:4-9`); tool versions pinned in the image
+(`Dockerfile:13-26`).
+|===
diff --git a/docs/arc42/src/11_technical_risks.adoc b/docs/arc42/src/11_technical_risks.adoc
new file mode 100644
index 0000000..c82cf7d
--- /dev/null
+++ b/docs/arc42/src/11_technical_risks.adoc
@@ -0,0 +1,143 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-technical-risks]]
+== Risks and Technical Debts
+
+Risks threaten a quality goal in operation. Technical debt costs effort on every change but does
+not, by itself, break a build. Both lists come from the code, not from a risk register — the
+repository has none.
+
+=== Risks
+
+[cols="1,3,1,2,1",options="header"]
+|===
+|ID |Risk |Threatens |Evidence |Mitigation
+
+|[[R-1]]R-1
+|A chapter that Pandoc fails to convert disappears from multi-page output. The failure only
+prints a warning, no counter notices, and the archive is shipped incomplete.
+|QG-1
+|`lib/Converter.groovy:345`
+|Count the failure like the single-page path does and fail the phase. Open.
+
+|[[R-2]]R-2
+|A build with failed conversions still reports success. Failures are counted but never reach the
+exit code, and the packager's `failed` counter is never incremented, so its summary always reads
+`Failed: 0`.
+|QG-1
+|`lib/Converter.groovy:437-440`, `build.groovy:211-215`, `lib/Packager.groovy:116`, `:177`
+|Exit non-zero when `failed > 0`; increment or remove the dead counter. Open.
+
+|[[R-3]]R-3
+|The containerised pipeline deletes the whole `arc42-template` directory before re-initialising
+it, discarding uncommitted template work.
+|QG-1
+|`build-arc42.sh:57-60`
+|Refuse to delete a dirty submodule, or require an explicit flag. Open.
+
+|[[R-4]]R-4
+|The build checks out `master` and pulls, so the output follows whatever upstream holds at build
+time rather than the recorded submodule commit. Two runs of the same generator commit can produce
+different archives.
+|QG-3
+|`build-arc42.sh:69`
+|Build the pinned submodule commit; update it as an explicit step. Open, see <<ADR-006>> for the
+related trust decision.
+
+|[[R-5]]R-5
+|Outside the container, Grape resolves AsciidoctorJ, the diagram extension and GPars when the
+script starts, so a repository outage or rate limit breaks the build. This contradicts the stated
+requirement of a network-free build.
+|QG-3
+|`lib/Converter.groovy:3-5`, requirement `docs/arc42_build_process_requirements.md:323`
+|Mitigated inside the image by the pre-populated cache (`Dockerfile:40-45`); unmitigated locally.
+
+|[[R-6]]R-6
+|Parallelism runs over templates only, so the speed-up is capped by the number of templates. All
+workers share one Asciidoctor instance and one lock for the progress counter.
+|QG-4
+|`lib/Converter.groovy:429-433`, `:33`
+|None needed while the 20-minute budget holds (<<QS-04>>); revisit if it is breached.
+
+|[[R-7]]R-7
+|Releasing means committing generated archives inside the content repository by hand. A forgotten
+push leaves the download page stale, and there is no pipeline to catch it.
+|QG-1
+|`buildconfig.groovy:38`, `build-arc42.sh:198-205`
+|Automate the release once CI exists (<<TD-6>>). Open.
+|===
+
+=== Technical Debt
+
+[cols="1,3,2,1",options="header"]
+|===
+|ID |Debt |Evidence |Effort
+
+|[[TD-1]]TD-1
+|The `example` feature is declared and never used (team answer). A check of the Golden Master
+found `arc42example` zero times against 995 occurrences of `arc42help` in 168 files, so the feature
+regex runs over every file on every build and never matches. The `with-examples` flavor has been
+commented out with "no content yet" ever since.
+|`buildconfig.groovy:7`, `:13-14`, `lib/Templates.groovy:80`
+|small
+
+|[[TD-2]]TD-2
+|The HTML charset fix-up is unreachable: it lives in `convertViaPandoc`, but `html` is routed to
+AsciidoctorJ one level up.
+|`lib/Converter.groovy:231-238` against `:60-61`
+|small
+
+|[[TD-3]]TD-3
+|A mistyped phase argument matches no guard, so the build does nothing and prints
+"BUILD SUCCESSFUL". The CLI validates neither the phase nor the format.
+|`build.groovy:46`, `:129`, `:145`, `:168`, `:185`; format at `:48-51` with `lib/Converter.groovy:400`
+|small
+
+|[[TD-4]]TD-4
+|`switchToreq42.sh` rewrites `build.gradle`, `settings.gradle` and `subBuild.gradle` and calls
+`./gradlew`. None of those files exist since <<ADR-001>>; the req42 path is broken.
+|`switchToreq42.sh:1-4`, `:10-12`
+|medium
+
+|[[TD-5]]TD-5
+|The runtime image copies only the build scripts and `lib/`, so the test suite cannot run inside
+the container that the project declares as the only supported environment.
+|`Dockerfile:78-79` against `run-all-tests.groovy:22-36`
+|small
+
+|[[TD-6]]TD-6
+|CI runs the documentation build only (`.github/workflows/documentation.yml`). Nothing runs the
+test suite or the template build on push, although the requirements ask for it.
+|`docs/arc42_build_process_requirements.md:229`
+|medium
+
+|[[TD-7]]TD-7
+|All data between stages travels as untyped `Map`. A renamed key fails at runtime, not at compile
+time, and the 13-field record is documented only by its construction site.
+|`lib/Discovery.groovy:127-140`, consumed at `lib/Converter.groovy:86`, `:95`, `:157`
+|medium
+
+|[[TD-8]]TD-8
+|No test carries a requirement or business-rule identifier, so traceability from chapter 1.1 to
+the suites is manual.
+|`run-all-tests.groovy:22-36`
+|small
+
+|[[TD-9]]TD-9
+|`CLAUDE.md` documents the language pattern as `/^[A-Z]{2}$/` while the code implements
+`/^[A-Z]{2,}$/`, so the document excludes three-letter codes such as `UKR` that the build accepts.
+The same file still carries operating instructions for a removed MCP server.
+|`CLAUDE.md:52` against `lib/Templates.groovy:38`; `CLAUDE.md:217-280`
+|small
+
+|[[TD-10]]TD-10
+|The same recursive image copy is written four times with small variations.
+|`lib/Templates.groovy:127-131`, `lib/Converter.groovy:162-169`, `:287-294`, `:328-330`
+|small
+
+|[[TD-11]]TD-11
+|`test-asciidoc-direct.groovy` hard-codes absolute paths under `/workspaces/arc42-generator`,
+which exist only in Codespaces.
+|`test-asciidoc-direct.groovy:11-13`
+|small
+|===
diff --git a/docs/arc42/src/12_glossary.adoc b/docs/arc42/src/12_glossary.adoc
new file mode 100644
index 0000000..183928d
--- /dev/null
+++ b/docs/arc42/src/12_glossary.adoc
@@ -0,0 +1,54 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-glossary]]
+== Glossary
+
+[cols="1,4",options="header"]
+|===
+|Term |Definition
+
+|Golden Master
+|The authoritative AsciiDoc source of the arc42 template, kept in the separate `arc42-template`
+repository and consumed here as a submodule (`buildconfig.groovy:2-3`, <<ADR-007>>).
+
+|Flavor / style
+|A named subset of features to keep. `plain` keeps none, `with-help` keeps `help`; everything not
+kept is stripped (`buildconfig.groovy:10-15`). *Vocabulary warning:* the code says `style`, the
+README and the requirements say `flavour`, and `docs/arc42-requirements.adoc:172` calls the plain
+variant `Skeleton`. Three names, one concept.
+
+|Feature
+|A markable content class in the Golden Master, written as `[role="arc42<feature>"]` or as an
+`ifdef::arc42<feature>[]` block. Two are declared, `help` and `example`; only `help` exists in the
+content (<<TD-1>>).
+
+|Pivot format
+|DocBook XML, the intermediate every non-HTML, non-AsciiDoc format passes through
+(<<ADR-003>>).
+
+|MP format
+|"Multi-page": one output file per chapter instead of one file per template. Four format names
+carry the suffix: `markdownMP`, `mkdocsMP`, `markdownMPStrict`, `gitHubMarkdownMP`
+(`lib/Converter.groovy:299`).
+
+|Template metadata
+|The 13-field `Map` that Discovery builds per (language, flavor) and that every later stage reads
+(`lib/Discovery.groovy:127-140`).
+
+|Phase
+|One of `templates`, `convert`, `distribution`, `all` — the first CLI argument, selecting which
+part of the pipeline runs (`build.groovy:46`).
+
+|Grape
+|Groovy's dependency mechanism. `@Grab` annotations resolve AsciidoctorJ, the diagram extension
+and GPars at script start; the container pre-populates the cache
+(`lib/Converter.groovy:3-5`, `Dockerfile:40-45`).
+
+|dtcw4
+|The docToolchain v4 wrapper script that renders this documentation. `./dtcw4 local generateHTML`
+builds `build/docs/html5/` from `docs/`.
+
+|Distribution
+|The set of ZIP archives, one per language, flavor and format, written into the content
+repository's `dist/` directory (`lib/Packager.groovy:83`, `buildconfig.groovy:38`).
+|===
diff --git a/docs/arc42/src/about-arc42.adoc b/docs/arc42/src/about-arc42.adoc
new file mode 100644
index 0000000..a9d3ae4
--- /dev/null
+++ b/docs/arc42/src/about-arc42.adoc
@@ -0,0 +1,15 @@
+:homepage: https://arc42.org
+
+:keywords: software-architecture, documentation, template, arc42
+
+:numbered!:
+**About arc42**
+
+[role="lead"]
+arc42, the template for documentation of software and system architecture.
+
+Template Version {revnumber}. {revremark}, {revdate}
+
+Created, maintained and (C) by Dr. Peter Hruschka, Dr. Gernot Starke and contributors.
+See https://arc42.org.
+
diff --git a/docs/arc42/src/config.adoc b/docs/arc42/src/config.adoc
new file mode 100644
index 0000000..334d529
--- /dev/null
+++ b/docs/arc42/src/config.adoc
@@ -0,0 +1,9 @@
+// asciidoc settings for EN (English)
+// ==================================
+:toc-title: table of contents
+
+// enable table-of-contents
+:toc:
+
+// where are images located?
+:imagesdir: ./images
diff --git a/docs/specs/adrs/arc42-generator-adr-001-groovy-instead-of-gradle.adoc b/docs/specs/adrs/arc42-generator-adr-001-groovy-instead-of-gradle.adoc
new file mode 100644
index 0000000..3b3b8ea
--- /dev/null
+++ b/docs/specs/adrs/arc42-generator-adr-001-groovy-instead-of-gradle.adoc
@@ -0,0 +1,34 @@
+ifndef::imagesdir[:imagesdir: ../../arc42/images]
+
+[[ADR-001]]
+= ADR-001: A plain Groovy script replaces Gradle
+
+*Status:* accepted (implemented; the Gradle files are gone)
+
+*Context:* the previous build used Gradle in a two-pass construction — the first pass generated
+the build scripts for the second (team answer). That indirection, not the runtime, drove the
+complexity: a
+contributor had to understand generated build logic before changing anything.
+
+*Decision:* drop Gradle. `build.groovy` loads four classes and runs four phases; there is no
+build tool and nothing is generated (`build.groovy:101-123`, `:129-202`).
+
+*Consequences:* the pipeline is readable end to end and starts without build-tool overhead —
+17.4 s instead of roughly 90 s (`TEST-REPORT.md:365`). In exchange the project loses Gradle's
+dependency management and incremental build; dependencies are now resolved by Grape at script
+start (`lib/Converter.groovy:3-5`), which is <<R-5>>. A leftover script still rewrites the deleted
+Gradle files (`switchToreq42.sh:1-12`), which is <<TD-4>>.
+
+[cols="2,1,1,1",options="header"]
+|===
+|Criterion |Gradle two-pass (baseline) |Gradle single-pass |Plain Groovy script
+
+|QG-2 Maintainability |0 |+1 |+1
+|QG-4 Performance |0 |0 |+1
+|Dependency management |0 |0 |-1
+|Migration effort |0 |-1 |-1
+|*Sum* |*0* |*0* |*0*
+|===
+
+The matrix ties. Maintainability broke the tie, because it is the goal the two-pass construction
+hurt most directly.
diff --git a/docs/specs/adrs/arc42-generator-adr-002-language-auto-discovery.adoc b/docs/specs/adrs/arc42-generator-adr-002-language-auto-discovery.adoc
new file mode 100644
index 0000000..9737a74
--- /dev/null
+++ b/docs/specs/adrs/arc42-generator-adr-002-language-auto-discovery.adoc
@@ -0,0 +1,30 @@
+ifndef::imagesdir[:imagesdir: ../../arc42/images]
+
+[[ADR-002]]
+= ADR-002: Languages are discovered, not configured
+
+*Status:* accepted
+
+*Context:* translations arrive from the community. A configuration list means every new language
+needs a commit in this repository, by someone who may not be involved in the translation.
+
+*Decision:* a directory in the Golden Master whose name matches `/^[A-Z]{2,}$/` is a language
+(`lib/Templates.groovy:38`, mirrored for the generated tree at `lib/Discovery.groovy:62`).
+
+*Consequences:* adding a language costs nothing here (R-1). The price is an implicit contract:
+a directory named `EN-draft` is invisible, a directory named `DIST` would be mistaken for a
+language, and the rule lives in two places that must stay in step.
+
+[cols="2,1,1,1",options="header"]
+|===
+|Criterion |Explicit list (baseline) |Regex discovery |Manifest file in the Golden Master
+
+|QG-2 Maintainability |0 |+1 |+1
+|QG-3 Functional suitability |0 |0 |+1
+|Predictability |0 |-1 |+1
+|Effort in the template repository |0 |0 |-1
+|*Sum* |*0* |*0* |*+2*
+|===
+
+The manifest scores higher but was not chosen: it would put build metadata into the content
+repository, against <<ADR-007>>.
diff --git a/docs/specs/adrs/arc42-generator-adr-003-docbook-pivot-format.adoc b/docs/specs/adrs/arc42-generator-adr-003-docbook-pivot-format.adoc
new file mode 100644
index 0000000..0527ff1
--- /dev/null
+++ b/docs/specs/adrs/arc42-generator-adr-003-docbook-pivot-format.adoc
@@ -0,0 +1,27 @@
+ifndef::imagesdir[:imagesdir: ../../arc42/images]
+
+[[ADR-003]]
+= ADR-003: DocBook is the pivot format
+
+*Status:* accepted
+
+*Context:* 17 output formats from one AsciiDoc source. A direct converter per format is 17 code
+paths to maintain.
+
+*Decision:* HTML and AsciiDoc are produced directly; everything else goes AsciiDoc -> DocBook ->
+Pandoc (`lib/Converter.groovy:60-71`).
+
+*Consequences:* one well-supported pivot carries all remaining formats, and a new format is a
+table entry plus a dispatch branch. The cost is a second rendering step that can lose fidelity,
+plus an extra image copy into the DocBook directory (`lib/Converter.groovy:157-169`).
+
+[cols="2,1,1,1",options="header"]
+|===
+|Criterion |Direct converter per format (baseline) |DocBook pivot |HTML pivot
+
+|QG-2 Maintainability |0 |+1 |+1
+|QG-3 Functional suitability |0 |+1 |-1
+|Output fidelity |0 |-1 |-1
+|Speed |0 |-1 |0
+|*Sum* |*0* |*0* |*-1*
+|===
diff --git a/docs/specs/adrs/arc42-generator-adr-004-parallelism-over-templates.adoc b/docs/specs/adrs/arc42-generator-adr-004-parallelism-over-templates.adoc
new file mode 100644
index 0000000..8a459a2
--- /dev/null
+++ b/docs/specs/adrs/arc42-generator-adr-004-parallelism-over-templates.adoc
@@ -0,0 +1,27 @@
+ifndef::imagesdir[:imagesdir: ../../arc42/images]
+
+[[ADR-004]]
+= ADR-004: Parallelism over templates only
+
+*Status:* accepted
+
+*Context:* the work is 18 templates times 17 formats. Both loops could run concurrently.
+
+*Decision:* a GPars pool sized to the available processors runs the template loop; the format
+loop inside stays sequential (`lib/Converter.groovy:429-432`). Packaging parallelises over
+(template, format) pairs instead (`lib/Packager.groovy:130-131`).
+
+*Consequences:* the speed-up is capped by the number of templates, not by cores, and all workers
+share one Asciidoctor instance (`lib/Converter.groovy:33`) and one lock for the progress counter
+(`:433`). Within the 20-minute budget (team answer) this is ample — see <<QS-04>>; beyond it, <<R-6>>.
+
+[cols="2,1,1,1",options="header"]
+|===
+|Criterion |Sequential (baseline) |Parallel over templates |Parallel over both loops
+
+|QG-4 Performance |0 |+1 |+1
+|QG-1 Reliability |0 |0 |-1
+|QG-2 Maintainability |0 |0 |-1
+|Debuggability |0 |-1 |-1
+|*Sum* |*0* |*0* |*-2*
+|===
diff --git a/docs/specs/adrs/arc42-generator-adr-005-docker-only-environment.adoc b/docs/specs/adrs/arc42-generator-adr-005-docker-only-environment.adoc
new file mode 100644
index 0000000..536ad92
--- /dev/null
+++ b/docs/specs/adrs/arc42-generator-adr-005-docker-only-environment.adoc
@@ -0,0 +1,27 @@
+ifndef::imagesdir[:imagesdir: ../../arc42/images]
+
+[[ADR-005]]
+= ADR-005: Docker is the only supported environment
+
+*Status:* accepted
+
+*Context:* the build needs a JRE, Groovy, Pandoc and cmark in matching versions. Asking every
+contributor to install them invites version drift and unreproducible output.
+
+*Decision:* one image pins all of them; `docker compose up` is the supported entry point
+(`Dockerfile:13-26`, `docker-compose.yml:9`, `README.adoc:17`).
+
+*Consequences:* output is reproducible across hosts and the Grape cache ships inside the image,
+so no dependency is fetched at build time (`Dockerfile:40-45`). The price is Docker as a hard
+prerequisite and an image that must be rebuilt whenever a tool version moves.
+
+[cols="2,1,1,1",options="header"]
+|===
+|Criterion |Local toolchain (baseline) |Docker image |SDKMAN-scripted local setup
+
+|QG-3 Functional suitability |0 |+1 |0
+|Reproducibility |0 |+1 |0
+|Entry barrier |0 |-1 |+1
+|QG-2 Maintainability |0 |0 |-1
+|*Sum* |*0* |*+1* |*0*
+|===
diff --git a/docs/specs/adrs/arc42-generator-adr-006-accept-security-risk.adoc b/docs/specs/adrs/arc42-generator-adr-006-accept-security-risk.adoc
new file mode 100644
index 0000000..986e753
--- /dev/null
+++ b/docs/specs/adrs/arc42-generator-adr-006-accept-security-risk.adoc
@@ -0,0 +1,31 @@
+ifndef::imagesdir[:imagesdir: ../../arc42/images]
+
+[[ADR-006]]
+= ADR-006: Security risk is accepted, not mitigated
+
+*Status:* accepted
+
+*Context:* Asciidoctor runs with `SafeMode.UNSAFE`, downloads carry no checksum, and Git ownership
+checks are off inside the image. A threat model would name five threats (<<concept-threat-model>>).
+
+*Decision:* accept T-001 to T-005 (team answer). Input and output are public content, the build runs on
+maintainer machines, there is no user data and no exposed service. `SafeMode.UNSAFE` stays; it was
+chosen for convenience, and whether a stricter mode would also work has never been tested
+(team answer).
+
+*Consequences:* no hardening work, and no security review blocking a release. The decision is
+bound to its context: a hosted build service, signed releases, or content from unreviewed sources
+invalidate it and turn the accepted threats into findings.
+
+[cols="2,1,1,1",options="header"]
+|===
+|Criterion |Accept (baseline) |Stricter SafeMode |Checksums plus pinned submodule commit
+
+|Effort |0 |-1 |-1
+|Risk reduction |0 |+1 |+1
+|QG-3 Functional suitability |0 |-1 |0
+|QG-1 Reliability |0 |0 |+1
+|*Sum* |*0* |*-1* |*+1*
+|===
+
+The third option scores higher and is the natural first step should the context change.
diff --git a/docs/specs/adrs/arc42-generator-adr-007-golden-master-separate-repository.adoc b/docs/specs/adrs/arc42-generator-adr-007-golden-master-separate-repository.adoc
new file mode 100644
index 0000000..ee82edd
--- /dev/null
+++ b/docs/specs/adrs/arc42-generator-adr-007-golden-master-separate-repository.adoc
@@ -0,0 +1,29 @@
+ifndef::imagesdir[:imagesdir: ../../arc42/images]
+
+[[ADR-007]]
+= ADR-007: The Golden Master stays a separate repository
+
+*Status:* accepted
+
+*Context:* content and build logic have different audiences. Translators must not need build
+knowledge; release engineers must not wade through translations.
+
+*Decision:* two repositories. This one holds build logic and configuration, `arc42-template`
+holds only content, consumed as a Git submodule
+(`docs/arc42_build_process_requirements.md:86-104`, `.gitmodules:1-6`).
+
+*Consequences:* clean separation of concerns, and the same build can serve further templates such
+as req42. The price is submodule handling in every workflow, and a distribution directory that
+lives inside the content repository, so releasing means committing there
+(`buildconfig.groovy:38`, <<R-7>>).
+
+[cols="2,1,1,1",options="header"]
+|===
+|Criterion |Single repository (baseline) |Two repositories, submodule |Two repositories, scripted clone
+
+|Separation of concerns |0 |+1 |+1
+|QG-2 Maintainability |0 |+1 |+1
+|Workflow simplicity |0 |-1 |0
+|Version pinning |0 |+1 |0
+|*Sum* |*0* |*+2* |*+2*
+|===
diff --git a/docs/specs/backlog-arc42-generator.adoc b/docs/specs/backlog-arc42-generator.adoc
new file mode 100644
index 0000000..50d691a
--- /dev/null
+++ b/docs/specs/backlog-arc42-generator.adoc
@@ -0,0 +1,306 @@
+= Backlog: arc42-generator
+:jbake-menu: backlog
+:jbake-title: Backlog
+:jbake-type: page
+:jbake-status: published
+:toc: left
+:toclevels: 2
+:sectnums:
+:revnumber: 1.0
+:revdate: 2026-09-14
+
+Status:: Derived from the specification and the architecture documentation. Each entry is written
+to become one GitHub issue verbatim — EPICs first, then their user stories.
+The issue tracker of this repository is currently disabled, so the backlog lives here until it is
+switched on under Settings -> General -> Features -> Issues.
+
+Priorities:: MoSCoW. *Must* blocks the next release, *Should* is the following increment, *Could*
+is taken when it is cheap.
+
+Traceability:: Risk and debt IDs (R-x, TD-x) point into chapter 11 of
+`../arc42/arc42-arc42-generator.adoc`; requirement IDs (E-x, V-x) into
+`use-cases-arc42-generator.adoc`.
+
+== EPIC 1: The build tells the truth about its result (Must)
+
+*Goal:* what the build reports as finished is complete, and what fails is visible in the result,
+not only in the log.
+
+*Why:* reliability is the top quality goal (team answer). Today the code breaks it in three
+places: a failed conversion never reaches the exit code (`build.groovy:211-215`), a failed chapter
+of a multi-page format only prints a warning and vanishes from the output
+(`lib/Converter.groovy:345`), and the packager always reports `Failed: 0`
+(`lib/Packager.groovy:116`, `:177`). A release can go out incomplete without anyone noticing.
+
+*Definition of done:* all stories closed; `groovy run-all-tests.groovy` green; a build with a
+deliberately failing conversion exits non-zero; E-7, E-8 and E-10 satisfied.
+
+=== US-1 A failed conversion fails the build (Must)
+
+As a release maintainer I want the build to exit non-zero when any conversion failed, so that I
+never push an incomplete release.
+
+Depends on: none. Blocks: US-3.
+
+[source,gherkin]
+----
+Scenario: A failed conversion is visible in the result
+  Given a template whose conversion to docx fails
+  When the full build runs
+  Then the summary reports at least one failure
+  And the process exits with a non-zero code
+----
+
+Evidence: `lib/Converter.groovy:437-440`, `build.groovy:211-215`. Implements E-7, closes R-2 in
+part.
+
+=== US-2 A failed chapter of a multi-page format is counted (Must)
+
+As a release maintainer I want a chapter that Pandoc cannot convert to be counted like any other
+failure, so that an incomplete archive cannot pass as complete.
+
+Depends on: none. Related: US-1 (shares the failure path).
+
+[source,gherkin]
+----
+Scenario: A failed chapter of a multi-page format is counted
+  Given a chapter whose pandoc call fails
+  When the markdownMP conversion runs
+  Then the failure is counted like a single-page failure
+  And the build does not report success
+----
+
+Evidence: `lib/Converter.groovy:345` against `:219-222`. Implements E-8, closes R-1.
+
+=== US-3 The packager reports its real failure count (Must)
+
+As a release maintainer I want the distribution summary to show actual failures, so that
+`Failed: 0` means something.
+
+Depends on: US-1 (same exit-code decision).
+
+[source,gherkin]
+----
+Scenario: A failed archive is counted
+  Given an output directory that cannot be zipped
+  When the distribution phase runs
+  Then the summary reports one failure
+----
+
+Evidence: `lib/Packager.groovy:116`, `:177`. Closes R-2.
+
+=== US-4 The CLI rejects unknown phases and formats (Must)
+
+As a generator developer I want a mistyped argument to be rejected, so that a typo cannot look
+like a successful build.
+
+Depends on: none.
+
+[source,gherkin]
+----
+Scenario: An unknown phase is rejected
+  When the build is started with the phase 'covert'
+  Then the run stops with a message naming the valid phases
+  And the exit code is non-zero
+
+Scenario: An unknown format is rejected
+  When the build is started with '--format=wordperfect'
+  Then the run stops with a message naming the configured formats
+----
+
+Evidence: `build.groovy:46`, `:48-51`, guards `:129-185`, fallback `lib/Converter.groovy:400`.
+Implements E-10 and V-8, closes TD-3.
+
+== EPIC 2: Remove what is dead (Should)
+
+*Goal:* the code contains nothing that no longer runs or no longer applies.
+
+*Why:* every dead branch costs a reader time and misleads the next change. Five findings are
+documented as technical debt; none of them changes behaviour when removed.
+
+*Definition of done:* all stories closed; test suite green; no reference to a removed element
+remains in the documentation.
+
+=== US-5 Remove the unused `example` feature (Should)
+
+As a generator developer I want the `example` feature gone, so that the configuration describes
+what the build actually does.
+
+`example` is declared in `buildconfig.groovy:7` and the `with-examples` flavor is commented out
+with "no content yet" (`:13-14`). The Golden Master contains `arc42example` zero times against 995
+occurrences of `arc42help` in 168 files (team answer), so the removal regex in
+`lib/Templates.groovy:80` runs over every file on every build and never matches.
+
+Depends on: none. Note: confirm with the arc42 founders that the examples flavor is not merely
+dormant before deleting the flag.
+
+[source,gherkin]
+----
+Scenario: Feature removal handles only real features
+  Given the configuration lists only the feature 'help'
+  When both flavors are generated
+  Then the output is byte-identical to the previous release
+----
+
+Closes TD-1.
+
+=== US-6 Remove the unreachable HTML charset branch (Should)
+
+As a generator developer I want dead code removed, so that nobody debugs a branch that cannot run.
+
+The charset fix-up sits in `convertViaPandoc` (`lib/Converter.groovy:231-238`), but `html` is
+routed to AsciidoctorJ one level up (`:60-61`), so the branch is unreachable.
+
+Depends on: none. Closes TD-2.
+
+=== US-7 Repair or remove `switchToreq42.sh` (Should)
+
+As a generator developer I want the req42 path to either work or be gone, so that no script
+promises something it cannot deliver.
+
+The script rewrites `build.gradle`, `settings.gradle` and `subBuild.gradle` and calls `./gradlew`
+(`switchToreq42.sh:1-4`, `:10-12`). None of those exist since the Gradle build was dropped.
+
+Decision needed before implementation: revive req42 support against the Groovy pipeline, or delete
+the script.
+
+Depends on: none. Closes TD-4.
+
+=== US-8 Correct the drift in `CLAUDE.md` (Should)
+
+As a generator developer I want the project documentation to match the code, so that I can trust
+it.
+
+`CLAUDE.md:52` documents the language pattern as `/^[A-Z]{2}$/` while `lib/Templates.groovy:38`
+implements `/^[A-Z]{2,}$/`, so the document excludes three-letter codes such as `UKR` that the
+build accepts. The same file still carries operating instructions for an MCP server that was
+removed.
+
+Depends on: none. Closes TD-9.
+
+=== US-9 A typed record instead of an untyped map (Could)
+
+As a generator developer I want the template record to be a type, so that a renamed key fails at
+compile time rather than at runtime.
+
+The 13-field record is built at `lib/Discovery.groovy:127-140` and read at
+`lib/Converter.groovy:86`, `:95`, `:157`.
+
+Depends on: none, but touches every stage — schedule it alone. Closes TD-7.
+
+=== US-10 Tests carry requirement identifiers (Could)
+
+As a generator developer I want each test to name the requirement or business rule it covers, so
+that traceability is mechanical rather than manual.
+
+Suites are named after the class they exercise (`run-all-tests.groovy:22-36`); business rules
+BR-1 to BR-10 and requirements E-1 to E-12 exist in the specification.
+
+Depends on: none. Closes TD-8.
+
+=== US-11 One image copy instead of four (Could)
+
+As a generator developer I want the recursive image copy in one place, so that a fix applies
+everywhere.
+
+Four near-identical copies: `lib/Templates.groovy:127-131`, `lib/Converter.groovy:162-169`,
+`:287-294`, `:328-330`.
+
+Depends on: none. Refactoring only — behaviour must not change, and the commit must not contain
+anything else. Closes TD-10.
+
+== EPIC 3: A pipeline runs the build (Should)
+
+*Goal:* tests and build run automatically, not only when someone remembers.
+
+*Why:* the requirements ask for example GitHub Actions workflows
+(`docs/arc42_build_process_requirements.md:229`). A first workflow now exists — it builds the
+documentation microsite and publishes it to GitHub Pages
+(`.github/workflows/documentation.yml`) — but nothing runs the test suite or the template build.
+Without that, EPIC 1 has no place to prove itself.
+
+*Definition of done:* a push runs the test suite and a format-filtered build; a failing test turns
+the check red.
+
+=== US-12 A GitHub Actions workflow runs the test suite (Should)
+
+As a generator developer I want every push to run the tests, so that a regression is caught before
+review.
+
+Depends on: US-13 (the container must be able to run the tests).
+
+[source,gherkin]
+----
+Scenario: A broken change turns the check red
+  Given a change that breaks feature removal
+  When the workflow runs
+  Then the check fails and names the failing suite
+----
+
+Closes TD-6, satisfies constraint C-O-4.
+
+=== US-13 The test suite runs inside the container image (Should)
+
+As a generator developer I want to run the tests in the only supported environment, so that a
+green local run means something.
+
+The runtime image copies only the build scripts and `lib/` (`Dockerfile:78-79`), so
+`run-all-tests.groovy` and the four test scripts are missing (`run-all-tests.groovy:22-36`).
+
+Depends on: none. Blocks: US-12. Closes TD-5.
+
+=== US-14 Remove the hardcoded Codespaces paths from the direct test (Could)
+
+As a generator developer I want `test-asciidoc-direct.groovy` to run anywhere, so that it is
+usable outside Codespaces.
+
+Absolute paths under `/workspaces/arc42-generator` at `test-asciidoc-direct.groovy:11-13`.
+
+Depends on: none. Closes TD-11.
+
+== EPIC 4: Template work is safe (Should)
+
+*Goal:* the build never destroys content work, and a given generator commit produces a
+reproducible result.
+
+*Why:* the containerised pipeline deletes the whole submodule directory before refreshing it
+(`build-arc42.sh:57-60`), and it checks out `master` and pulls rather than building the recorded
+commit (`:69`). The first loses uncommitted translations, the second makes two runs of the same
+generator commit produce different archives.
+
+*Definition of done:* a dirty submodule is never deleted silently; the built commit is recorded in
+the build log.
+
+=== US-15 Refuse to wipe a dirty submodule (Should)
+
+As a translator I want my uncommitted work to survive a build, so that a colleague's release does
+not destroy it.
+
+[source,gherkin]
+----
+Scenario: A dirty submodule stops the refresh
+  Given uncommitted changes in arc42-template
+  When the containerised build starts
+  Then the build stops with a message naming the changed files
+  And no file is deleted
+----
+
+Depends on: none. Closes R-3.
+
+=== US-16 Build the pinned submodule commit (Could)
+
+As a release maintainer I want the build to use the recorded submodule commit, so that the same
+generator commit always produces the same archives.
+
+Updating the pin becomes an explicit, separate step.
+
+Evidence: `build-arc42.sh:69`. Closes R-4.
+
+== Not in the backlog
+
+* *Hardening against hostile template content.* Deliberately accepted, see ADR-006. Revisit only
+if the build becomes a hosted service or content arrives from unreviewed sources.
+* *Two-dimensional parallelism.* The 20-minute budget (team answer) is not under pressure — the
+build takes 17.4 s. Tracked as R-6, not scheduled.
+* *PDF output.* Named as desirable in the old requirements (`docs/arc42-requirements.adoc:142`),
+never configured. Needs a product decision first.
diff --git a/docs/specs/prd-arc42-generator.adoc b/docs/specs/prd-arc42-generator.adoc
new file mode 100644
index 0000000..a1939f6
--- /dev/null
+++ b/docs/specs/prd-arc42-generator.adoc
@@ -0,0 +1,172 @@
+= Product Requirements: arc42-generator
+:jbake-menu: prd
+:jbake-title: Product Requirements
+:jbake-type: page
+:jbake-status: published
+:toc: left
+:toclevels: 3
+:sectnums:
+:revnumber: 1.0
+:revdate: 2026-09-14
+
+Status:: Recovered, not newly invented. This PRD describes the product as the code defines it
+today, so that new work has a stated baseline to argue against. Facts that only the team could
+supply are marked (team answer).
+
+== The problem
+
+The arc42 template is maintained once and consumed in a dozen shapes.
+Its content lives as AsciiDoc in the `arc42-template` repository; its readers want Word, Markdown,
+HTML, LaTeX, EPUB and more, in their own language, with or without the embedded help texts.
+
+Producing those combinations by hand is impossible: eleven languages, two flavors and seventeen
+formats are almost four hundred artifacts, and every content change invalidates all of them.
+Without automation, either the template stops being updated or most formats fall behind.
+
+== Goals
+
+[cols="1,4",options="header"]
+|===
+|ID |Goal
+
+|G-1
+|One source, every shape: each language of the Golden Master is published in every supported
+format and both flavors.
+
+|G-2
+|A release costs one command. No handwork, no special knowledge, no per-format ritual.
+
+|G-3
+|Content contributors never touch the build. A new translation is picked up because it exists,
+not because someone registered it.
+
+|G-4
+|The output is trustworthy: what the build reports as done is complete and valid.
+|===
+
+G-4 is where the product falls short today, and it is the first goal of the current backlog
+(see chapter 11 of the architecture documentation, risks R-1 to R-3).
+
+== Personas
+
+[cols="1,2,3",options="header"]
+|===
+|Persona |Who they are |What they need from this product
+
+|*Rita, release maintainer*
+|arc42 core committer, does this beside her actual job, a few times a year
+|One command that produces everything, and a clear signal whether it worked. She must not have to
+read the build to find out that three chapters are missing.
+
+|*Tomás, translator*
+|Community contributor, maintains the Portuguese template, knows AsciiDoc, not Groovy
+|That his new directory shows up in the next release without anyone changing build code, and that
+his language is not silently dropped.
+
+|*Dana, generator developer*
+|Occasional contributor to this repository, adds a format or fixes a bug
+|A pipeline she can read in an afternoon, a documented place to add a format, and a test suite
+that tells her what she broke.
+
+|*Anonymous template user*
+|Architect or developer downloading from arc42.org
+|A complete, current archive in the chosen format and language. Never sees this repository.
+|===
+
+== Success criteria
+
+[cols="1,3,2",options="header"]
+|===
+|ID |Criterion |Measure today
+
+|S-1
+|Release effort: a maintainer produces a full release without handwork.
+|One command produces all archives (`docker-compose.yml:9`); the final push into the content
+repository is still manual (`build-arc42.sh:198-205`).
+
+|S-2
+|Completeness: every discovered language appears in both flavors and all formats.
+|languages x 2 x 17, printed by the build (`build.groovy:220-223`); last measured 18 templates
+from nine languages (`TEST-REPORT.md:119`).
+
+|S-3
+|Honesty: a failed conversion is visible in the result, not only in the log.
+|*Not met.* The process exits 0 regardless (`build.groovy:211-215`).
+
+|S-4
+|Cost of a new language: zero changed files in this repository.
+|Met (`lib/Templates.groovy:37-40`).
+
+|S-5
+|Build duration stays inside the budget of 20 minutes.
+|Met with room to spare: 17.4 s (`TEST-REPORT.md:365`).
+|===
+
+Downloads are deliberately not a success metric; nobody counts them and no target exists
+(team answer).
+
+== Scope
+
+*In scope*
+
+* Generating both flavors from the Golden Master, for every discovered language.
+* Converting to the seventeen configured formats, single-page and multi-page.
+* Packaging one ZIP per language, flavor and format into the content repository's `dist/`.
+* Post-build validation of generated Markdown and of image references.
+* Running the same pipeline locally in Docker and in GitHub Codespaces.
+
+*Out of scope*
+
+* The template content itself. What a chapter says is decided in the content repository by the
+arc42 founders.
+* Publishing. Uploading to arc42.org and announcing a release happen outside this product.
+* Rendering PDF. No PDF format is configured today (`buildconfig.groovy:17-35`), although the
+requirements list it as desirable (`docs/arc42-requirements.adoc:142`).
+* Hardening against hostile template content. Deliberately accepted, see ADR-006.
+
+*Explicitly deferred*
+
+* The `with-examples` flavor. The feature flag exists, the content does not: `arc42example`
+appears zero times in the Golden Master (technical debt TD-1).
+* req42 support. The switch script still targets the removed Gradle build (TD-4).
+
+== Constraints
+
+[cols="1,4",options="header"]
+|===
+|ID |Constraint
+
+|K-1
+|Docker is the only supported execution environment; local execution is explicitly unsupported
+(`README.adoc:17`, `:19`).
+
+|K-2
+|Only open-source tooling may be required
+(`docs/arc42_build_process_requirements.md:190-199`).
+
+|K-3
+|Build logic and template content live in separate repositories; the content is consumed as a Git
+submodule (`docs/arc42_build_process_requirements.md:86-104`, `.gitmodules:1-6`).
+
+|K-4
+|Releases are cut by hand: build, inspect, then commit and push inside the content repository
+(`build-arc42.sh:198-205`).
+
+|K-5
+|A full build may take up to 20 minutes (team answer).
+
+|K-6
+|Contributions follow feature branch, Conventional Commits and pull request; the rule is binding
+but not technically enforced (team answer).
+
+|K-7
+|Security is deliberately subordinate: the threats the build is exposed to are accepted rather
+than mitigated (team answer, see ADR-006).
+|===
+
+== Open questions
+
+None. All questions raised during the recovery were answered by the team; no item is deferred.
+The next decisions are backlog items rather than open questions: whether the `example` feature and
+the req42 switch script are removed or revived, and whether the manual release step is
+automated once a pipeline exists.
diff --git a/docs/specs/use-cases-arc42-generator.adoc b/docs/specs/use-cases-arc42-generator.adoc
new file mode 100644
index 0000000..142988c
--- /dev/null
+++ b/docs/specs/use-cases-arc42-generator.adoc
@@ -0,0 +1,815 @@
+= Specification: arc42-generator
+:jbake-menu: spec
+:jbake-title: Specification
+:jbake-type: page
+:jbake-status: published
+:toc: left
+:toclevels: 3
+:sectnums:
+:revnumber: 1.0
+:revdate: 2026-09-14
+
+Status:: Recovered from the code. Every statement describes the system as it behaves today and
+carries its evidence as `file:line`. Facts that only the team could supply are marked
+(team answer). Where today's behaviour contradicts a goal of the PRD, the text says so and names
+the risk ID from chapter 11 of the architecture documentation.
+
+Companion documents:: `prd-arc42-generator.adoc` (problem and goals),
+`../arc42/arc42-arc42-generator.adoc` (structure and decisions).
+
+== Actors
+
+[cols="1,1,3",options="header"]
+|===
+|Actor |Kind |Role in this system
+
+|Release maintainer
+|human, primary
+|Starts the build, inspects the result, pushes the archives (`build-arc42.sh:198-205`).
+
+|Generator developer
+|human, primary
+|Changes the pipeline: adds a format, fixes a defect (`CLAUDE.md:170-181`).
+
+|Translator
+|human, offstage
+|Adds a language directory in the content repository; never invokes this system
+(`lib/Templates.groovy:38`).
+
+|AsciidoctorJ
+|system, supporting
+|In-process conversion to HTML and DocBook (`lib/Converter.groovy:33`).
+
+|Pandoc
+|system, supporting
+|Child process converting DocBook to every other format (`lib/Converter.groovy:208-217`).
+
+|cmark
+|system, supporting
+|Validates generated Markdown (`build-arc42.sh:94-104`).
+
+|Git / GitHub
+|system, supporting
+|Supplies the Golden Master, receives the archives (`build-arc42.sh:66-78`).
+|===
+
+== Business Rules
+
+Each rule carries the code that implements it.
+
+[cols="1,4,2",options="header"]
+|===
+|ID |Rule |Evidence
+
+|BR-1
+|A directory of the Golden Master is a language exactly when its name matches `/^[A-Z]{2,}$/`.
+The rule is implemented twice, on the input side and on the generated side, and both must agree.
+|`lib/Templates.groovy:38`, `lib/Discovery.groovy:62`
+
+|BR-2
+|A flavor is a named list of features to keep. Everything in `allFeatures` that the flavor does
+not list is removed.
+|`buildconfig.groovy:7-15`, `lib/Templates.groovy:205`
+
+|BR-3
+|Feature removal works two ways: `[role="arc42<feature>"]` delimited blocks are deleted entirely;
+for `help`, the `ifdef::arc42help[]` and `endif::arc42help[]` marker lines are deleted while their
+body is kept.
+|`lib/Templates.groovy:80`, `:84-87`
+
+|BR-4
+|The `plain` flavor receives only `arc42-logo.png`; every other flavor receives all images of the
+language.
+|`lib/Templates.groovy:114-133`
+
+|BR-5
+|Images are copied only for formats whose `imageFolder` flag is true. `mkdocs` and `mkdocsMP`
+receive them under `docs/images`, all others under `images`.
+|`buildconfig.groovy:18-34`, `lib/Converter.groovy:54`, `:282`
+
+|BR-6
+|Include paths are rewritten twice: on generation `include::adoc/` becomes `include::` and
+`include::../common/` becomes `include::../../../common/`; on AsciiDoc output every `include::`
+gains a `src/` prefix.
+|`lib/Templates.groovy:68`, `:71`, `lib/Converter.groovy:265`
+
+|BR-7
+|LaTeX output for the language `RU` is generated with the font encoding `T1,T2A`.
+|`lib/Converter.groovy:195-197`
+
+|BR-8
+|`mkdocsMP` output must not contain `config.md` or `about-arc42.md`; both are deleted after
+conversion.
+|`lib/Converter.groovy:348`
+
+|BR-9
+|In an archive file name the flavor is reduced to letters, so `with-help` becomes `withhelp`.
+|`lib/Packager.groovy:80`, `:83`
+
+|BR-10
+|Only `help` is a real feature. `example` is declared but appears zero times in the Golden Master,
+so its removal step is a no-op on every file (team answer). Technical debt TD-1.
+|`buildconfig.groovy:7`, `:13-14`
+|===
+
+== Persona Use Cases
+
+=== UC-1 Release a complete template set
+
+[cols="1,4"]
+|===
+|Primary Actor |Release maintainer (Rita)
+|Scope |arc42-generator, whole pipeline
+|Level |User goal
+|Stakeholders |Template user wants complete archives; translator wants their language included;
+founders want the current content
+|Preconditions |Docker available; the repository is cloned; the content repository is reachable
+|Trigger |New or corrected content exists in the Golden Master and should reach arc42.org
+|Postconditions (success) |One ZIP archive per language, flavor and format exists in
+`arc42-template/dist/`, and the maintainer knows whether anything failed
+|Postconditions (failure) |No archive is published, and the reason is visible in the log
+|===
+
+*Main success scenario*
+
+. The maintainer runs `docker compose up` (`docker-compose.yml:9`).
+. The system ensures Pandoc is present, installing it if necessary (`build-arc42.sh:19-45`).
+. The system refreshes the Golden Master submodule (`build-arc42.sh:66-78`).
+. The system generates both flavors for every discovered language, applying BR-1 to BR-4 and BR-6
+(`lib/Templates.groovy:155-257`).
+. The system discovers the generated templates and builds one metadata record each
+(`lib/Discovery.groovy:43-154`).
+. The system converts every template into every configured format, applying BR-5, BR-7 and BR-8
+(`lib/Converter.groovy:410-472`).
+. The system packages each output directory as one archive, applying BR-9
+(`lib/Packager.groovy:102-185`).
+. The system validates the generated Markdown and the image references
+(`build-arc42.sh:86-189`).
+. The system prints counts, durations and the release instructions (`build-arc42.sh:192-205`).
+. The maintainer inspects `arc42-template/dist/` and pushes the archives from the content
+repository.
+
+*Extensions*
+
+[cols="1,4",options="header"]
+|===
+|Step |Alternative
+
+|2a
+|Pandoc is missing and the architecture is unsupported: the script aborts with a message and exit
+code 1 (`build-arc42.sh:28-35`).
+
+|3a
+|The submodule update fails: up to three attempts with lock cleanup and a two-second pause; after
+the third the script exits 1 (`build-arc42.sh:66-78`).
+
+|3b
+|The submodule directory contains uncommitted work: it is deleted without warning. Risk R-3
+(`build-arc42.sh:57-60`).
+
+|4a
+|No language directory is found: the phase throws and the build exits 1
+(`lib/Templates.groovy:42-44`).
+
+|6a
+|A single conversion fails: the error is logged and counted, the run continues with the next
+format (`lib/Converter.groovy:74-78`).
+
+|6b
+|A chapter of a multi-page format fails: a warning is printed, the chapter is missing from the
+output, and no counter records it. Risk R-1 (`lib/Converter.groovy:345`).
+
+|8a
+|Markdown does not parse, or an image reference does not resolve: a warning is printed and the
+build continues; both checks are non-fatal (`build-arc42.sh:109-111`, `:187-188`).
+
+|9a
+|Conversions failed in step 6: the summary still reads "BUILD SUCCESSFUL" and the exit code is 0.
+Risk R-2 — this violates goal G-4 of the PRD (`build.groovy:211-215`).
+|===
+
+[plantuml,uc1_activity,svg]
+....
+@startuml
+start
+:docker compose up;
+if (Pandoc present?) then (no)
+  if (architecture supported?) then (no)
+    :message;
+    stop
+  else (yes)
+    :download and install .deb;
+  endif
+else (yes)
+endif
+repeat
+  :remove stale index locks;
+  :submodule init/update, checkout master, pull;
+repeat while (failed and attempts < 3?) is (yes)
+if (still failing?) then (yes)
+  :exit 1;
+  stop
+endif
+:generate flavors per language;
+if (any language found?) then (no)
+  :exit 1;
+  stop
+endif
+:discover templates;
+fork
+  :convert template A to all formats;
+fork again
+  :convert template B to all formats;
+end fork
+:package archives;
+:validate Markdown and images (non-fatal);
+:print counts and durations;
+note right
+  Today the exit code is 0
+  even when conversions failed (R-2)
+end note
+stop
+@enduml
+....
+
+=== UC-2 Add a new language
+
+[cols="1,4"]
+|===
+|Primary Actor |Translator (Tomás), offstage for this system
+|Scope |arc42-generator, generation phase
+|Level |User goal
+|Preconditions |The translation exists in the content repository
+|Trigger |A new directory whose name matches BR-1 is merged into the Golden Master
+|Postconditions (success) |The language appears in the next build in both flavors and every
+format, without any change in this repository
+|===
+
+*Main success scenario*
+
+. The translator merges the directory `<LANG>/` with `arc42-template.adoc`, `adoc/*.adoc`,
+`images/` and `version.properties` into the content repository.
+. On the next build the system discovers the directory by BR-1 (`lib/Templates.groovy:37-40`).
+. The system generates, converts and packages it like every other language.
+
+*Extensions*
+
+[cols="1,4",options="header"]
+|===
+|Step |Alternative
+
+|1a
+|The directory name does not match BR-1, for example `pt-BR` or `EN-draft`: the language is
+ignored silently, with no warning (`lib/Templates.groovy:38`).
+
+|1b
+|`version.properties` is missing: generation continues, and the template is documented as version
+`unknown` (`lib/Discovery.groovy:139`).
+
+|2a
+|The language directory lacks an `adoc/` directory: only the main file is processed, and the
+template consists of one file (`lib/Templates.groovy:231-232`).
+
+|3a
+|Only EN and DE are asserted by the test suite, so a defect in another language is not caught by
+tests (`test-discovery.groovy:79`).
+|===
+
+=== UC-3 Add an output format
+
+[cols="1,4"]
+|===
+|Primary Actor |Generator developer (Dana)
+|Scope |arc42-generator, conversion phase
+|Level |User goal
+|Preconditions |Pandoc supports the target format, or a direct converter exists
+|Trigger |A format is requested that the configuration does not yet contain
+|Postconditions (success) |The format is produced for every template and packaged like the others
+|===
+
+*Main success scenario*
+
+. The developer adds the format to the configuration map with its `imageFolder` flag
+(`buildconfig.groovy:17-35`).
+. The developer adds a descriptor — Pandoc format, file extension, extra arguments — to the
+descriptor table (`lib/Converter.groovy:382-398`).
+. If the format needs its own path, the developer extends the dispatch chain
+(`lib/Converter.groovy:60-71`).
+. The developer verifies with `groovy build.groovy --format=<name>` (`build.groovy:48-51`).
+
+*Extensions*
+
+[cols="1,4",options="header"]
+|===
+|Step |Alternative
+
+|2a
+|The descriptor is forgotten: the format silently falls back to an identity descriptor, so Pandoc
+is called with the format name as both target and file extension
+(`lib/Converter.groovy:400`).
+
+|4a
+|The format name is misspelled on the command line: no validation happens and the same fallback
+applies (`build.groovy:48-51`).
+|===
+
+=== UC-4 Rebuild one format quickly
+
+[cols="1,4"]
+|===
+|Primary Actor |Generator developer (Dana)
+|Scope |arc42-generator, CLI
+|Level |User goal
+|Preconditions |The templates have been generated at least once
+|Trigger |A change is to be checked without a full build
+|Postconditions (success) |Only the requested phase and format run
+|===
+
+*Main success scenario*
+
+. The developer runs `groovy build.groovy convert --format=html` (`build.groovy:16-21`).
+. The system skips generation, discovers the existing templates, converts only HTML.
+
+*Extensions*
+
+[cols="1,4",options="header"]
+|===
+|Step |Alternative
+
+|2a
+|No templates have been generated yet: discovery fails with a hint to run the `templates` phase
+first, exit code 1 (`build.groovy:150-160`).
+
+|1a
+|The phase name is misspelled, for example `covert`: no guard matches, nothing runs, and the
+script reports success. Technical debt TD-3 (`build.groovy:46`, `:129-185`).
+|===
+
+== System Use Cases
+
+One per technical interface. Each states input and validation, processing, output and status, and
+error responses.
+
+=== SUC-1 CLI: `groovy build.groovy`
+
+*Input*
+
+[cols="1,2,2,1",options="header"]
+|===
+|Parameter |Form |Default |Validation
+
+|Phase
+|First argument not starting with `--`: `templates`, `convert`, `distribution`, `all`
+|`all`
+|*None.* An unknown value matches no guard (`build.groovy:46`).
+
+|Format filter
+|`--format=<name>`
+|all configured formats
+|*None.* The value is not checked against the format map (`build.groovy:48-51`).
+
+|Parallelism
+|`--parallel=false`
+|parallel on
+|Exact string comparison; any other spelling leaves parallelism on (`build.groovy:47`).
+|===
+
+*Processing:* load `buildconfig.groovy` through `ConfigSlurper`; load the four classes by file
+name; run the phases the argument selects (`build.groovy:76`, `:101-111`, `:129-202`).
+
+*Output and status*
+
+[cols="1,3,2",options="header"]
+|===
+|Exit code |Meaning |Evidence
+
+|0
+|All selected phases ran — *or* an unknown phase ran nothing — *or* conversions failed but the
+process still completed. See TD-3 and R-2.
+|`build.groovy:211-215`
+
+|1
+|Configuration could not be loaded; a helper class could not be loaded; a phase threw; discovery
+found no templates.
+|`build.groovy:85`, `:116`, `:135`, `:152`, `:160`, `:177`, `:200`
+|===
+
+*Error responses:* every failure prints a line starting with `✗` and, for exceptions, a stack
+trace. A discovery failure adds the hint to run the `templates` phase first
+(`build.groovy:157-159`).
+
+=== SUC-2 Container entry point: `build-arc42.sh`
+
+*Input:* none. Behaviour is fixed; environment is the container.
+
+*Processing:* ensure Pandoc; refresh the submodule with up to three attempts; run
+`groovy build.groovy`; validate Markdown with cmark; validate image directories and Markdown image
+references (`build-arc42.sh:19-45`, `:66-78`, `:84`, `:86-189`).
+
+*Output and status*
+
+[cols="1,3,2",options="header"]
+|===
+|Exit code |Meaning |Evidence
+
+|0
+|Pipeline completed. Validation warnings do not change this.
+|`build-arc42.sh:106-115`, `:184-189`
+
+|1
+|Unsupported architecture for the Pandoc package, or the submodule refresh failed three times, or
+`groovy build.groovy` exited non-zero (`set -e`).
+|`build-arc42.sh:11`, `:32-35`, `:72-75`
+|===
+
+*Error responses:* messages prefixed `⚠` for non-fatal findings, `✗` for fatal ones.
+
+=== SUC-3 Configuration file: `buildconfig.groovy`
+
+*Input:* a Groovy script read by `ConfigSlurper`, with three blocks.
+
+[cols="1,3,2",options="header"]
+|===
+|Key |Meaning |Evidence
+
+|`goldenMaster.sourcePath`
+|Path to the content repository
+|`buildconfig.groovy:3`
+
+|`goldenMaster.targetPath`
+|Where generated AsciiDoc is written
+|`buildconfig.groovy:4`
+
+|`goldenMaster.allFeatures`
+|All features the Golden Master may mark
+|`buildconfig.groovy:7`
+
+|`goldenMaster.templateStyles`
+|Flavor name to list of features kept (BR-2)
+|`buildconfig.groovy:10-15`
+
+|`formats`
+|Format name to `[imageFolder: boolean]` (BR-5)
+|`buildconfig.groovy:17-35`
+
+|`distribution.targetPath`
+|Where archives are written
+|`buildconfig.groovy:38`
+|===
+
+*Validation:* none. There is no schema; a missing key surfaces as a Groovy exception at its use
+site. A malformed file aborts the run with exit code 1 (`build.groovy:83-86`).
+
+=== SUC-4 Input contract: Golden Master
+
+*Expected structure per language directory `<LANG>/`* (BR-1):
+
+[cols="1,3,2",options="header"]
+|===
+|Element |Requirement |Evidence
+
+|`arc42-template.adoc`
+|Main file. If absent, the flavor is generated without a main file and the template consists of
+the chapter files only.
+|`lib/Templates.groovy:213-228`
+
+|`adoc/*.adoc`
+|Chapter files. Only the `.adoc` extension is processed; subdirectories are ignored.
+|`lib/Templates.groovy:231-244`
+
+|`images/*`
+|Images. For `plain` only `arc42-logo.png` is taken; if it is missing, a warning is printed
+(BR-4).
+|`lib/Templates.groovy:112-124`
+
+|`version.properties`
+|Optional. Read as UTF-8; `revnumber`, `revdate`, `revremark` become AsciiDoc attributes. Absent
+means version `unknown`.
+|`lib/Templates.groovy:194-201`, `lib/Discovery.groovy:117-124`, `:139`
+
+|`common/` (repository level)
+|Shared files, copied recursively per language.
+|`lib/Templates.groovy:177-190`
+|===
+
+*Error responses:* a missing source path or an empty language set raises `IllegalStateException`
+and the phase exits 1 (`lib/Templates.groovy:33-35`, `:42-44`).
+
+=== SUC-5 Output contract: distribution
+
+[cols="1,3,2",options="header"]
+|===
+|Property |Rule |Evidence
+
+|Archive name
+|`arc42-template-<LANG>-<STYLE>-<FORMAT>.zip`, flavor reduced to letters (BR-9)
+|`lib/Packager.groovy:80`, `:83`
+
+|Archive content
+|Everything below `build/<LANG>/<FORMAT>/<STYLE>/`, with paths relative to that directory
+|`lib/Packager.groovy:44-52`
+
+|Location
+|`arc42-template/dist/`, created if missing
+|`buildconfig.groovy:38`, `lib/Packager.groovy:84-86`
+
+|Missing source
+|If the output directory does not exist, the archive is skipped and counted as `⊘ not found`;
+this is not an error
+|`lib/Packager.groovy:75-77`, `:143-145`
+|===
+
+*Status:* the summary always prints `Failed: 0`, because the counter is never incremented
+(R-2, `lib/Packager.groovy:116`, `:177`).
+
+=== SUC-6 Process contract: Pandoc
+
+*Input:* argument vector `pandoc -r docbook -t <pandocFormat> -o <absolute output file>
+<relative XML file name>`, plus format-specific arguments, plus `-s` for the standalone family
+(`lib/Converter.groovy:181-204`).
+
+*Environment:* working directory is the DocBook output directory so relative image paths resolve;
+`LC_ALL` and `LANG` are set to `en_US.UTF-8` (`lib/Converter.groovy:208-214`).
+
+*Output and status*
+
+[cols="1,3,2",options="header"]
+|===
+|Case |Response |Evidence
+
+|Exit 0, single page
+|Output file written; LaTeX gets thin spaces replaced afterwards
+|`lib/Converter.groovy:225-228`
+
+|Exit non-zero, single page
+|`RuntimeException`, caught one level up, conversion counted as failed
+|`lib/Converter.groovy:219-222`, `:74-78`
+
+|Exit non-zero, multi page
+|Warning only. The chapter is missing from the output and nothing is counted. Risk R-1.
+|`lib/Converter.groovy:345`
+|===
+
+== Acceptance Criteria
+
+[source,gherkin]
+----
+Feature: Generating template flavors
+
+  Scenario: The plain flavor contains no help texts
+    Given a Golden Master chapter with an arc42help block and an ifdef::arc42help marker
+    When the plain flavor is generated
+    Then the output contains neither '[role="arc42help"]' nor 'ifdef::arc42help'
+    And the text outside those blocks is unchanged
+
+  Scenario: The plain flavor ships only the logo
+    Given a language directory with six images including arc42-logo.png
+    When the plain flavor is generated
+    Then the images directory of that flavor contains exactly arc42-logo.png
+
+  Scenario: A new language needs no code change
+    Given a new directory 'HU' in the Golden Master
+    When the build runs
+    Then 'HU' appears in both flavors and every configured format
+    And no file in this repository was changed
+
+  Scenario: A directory that does not match the pattern is ignored
+    Given a directory 'pt-BR' in the Golden Master
+    When the build runs
+    Then no template is generated for 'pt-BR'
+
+Feature: Format conversion
+
+  Scenario: Multi-page Markdown yields one file per chapter
+    Given the generated EN plain template
+    When it is converted to markdownMP
+    Then the output directory contains more than one .md file
+
+  Scenario: mkdocsMP drops the configuration pages
+    Given the generated EN with-help template
+    When it is converted to mkdocsMP
+    Then the output contains neither config.md nor about-arc42.md
+
+  Scenario: Russian LaTeX carries the Cyrillic font encoding
+    Given the generated RU plain template
+    When it is converted to latex
+    Then pandoc was called with '-V fontenc=T1,T2A'
+
+Feature: Honest build result
+
+  Scenario: A failed conversion is visible in the result
+    Given a template whose conversion to docx fails
+    When the full build runs
+    Then the summary reports at least one failure
+    And the process exits with a non-zero code
+
+  Scenario: A failed chapter of a multi-page format is counted
+    Given a chapter whose pandoc call fails
+    When the markdownMP conversion runs
+    Then the failure is counted like a single-page failure
+    And the build does not report success
+----
+
+NOTE: The two scenarios of the last feature fail today. They describe goal G-4 of the PRD and are
+tracked as risks R-1 and R-2.
+
+== Requirements in EARS Syntax
+
+[cols="1,4,2",options="header"]
+|===
+|ID |Requirement |Evidence / status
+
+|E-1
+|WHEN the generation phase runs, the system SHALL treat every directory of the Golden Master whose
+name matches `/^[A-Z]{2,}$/` as a language.
+|`lib/Templates.groovy:38`
+
+|E-2
+|WHEN a flavor is generated, the system SHALL remove every feature that the flavor does not list.
+|`lib/Templates.groovy:205`, `:80`
+
+|E-3
+|IF the flavor is `plain`, THEN the system SHALL copy only `arc42-logo.png`.
+|`lib/Templates.groovy:114-124`
+
+|E-4
+|IF a format declares `imageFolder: true`, THEN the system SHALL copy the language images into the
+output directory of that format.
+|`lib/Converter.groovy:54`
+
+|E-5
+|WHILE parallel execution is enabled, the system SHALL convert templates concurrently using a pool
+sized to the available processors.
+|`lib/Converter.groovy:429`
+
+|E-6
+|IF a conversion fails, THEN the system SHALL log the failure, count it, and continue with the next
+conversion.
+|`lib/Converter.groovy:74-78`
+
+|E-7
+|IF at least one conversion failed, THEN the system SHALL exit with a non-zero code.
+|*Not implemented.* Risk R-2 (`build.groovy:211-215`).
+
+|E-8
+|IF Pandoc fails for a chapter of a multi-page format, THEN the system SHALL count the failure.
+|*Not implemented.* Risk R-1 (`lib/Converter.groovy:345`).
+
+|E-9
+|WHEN the submodule refresh fails, the system SHALL retry up to three times with a two-second pause
+and SHALL exit with code 1 afterwards.
+|`build-arc42.sh:66-78`
+
+|E-10
+|IF the phase argument names no known phase, THEN the system SHALL reject it.
+|*Not implemented.* Technical debt TD-3 (`build.groovy:46`).
+
+|E-11
+|WHEN an archive is created, the system SHALL name it
+`arc42-template-<LANG>-<STYLE>-<FORMAT>.zip` with the flavor reduced to letters.
+|`lib/Packager.groovy:80`, `:83`
+
+|E-12
+|WHEN files are read or written, the system SHALL use UTF-8.
+|`lib/Templates.groovy:199`, `:218`, `lib/Discovery.groovy:121`, `lib/Converter.groovy:213-214`
+|===
+
+== Supplementary Specifications
+
+=== Entity Model
+
+[plantuml,spec_entities,svg]
+....
+@startuml
+hide circle
+entity "Language" as lang {
+  code : String <<BR-1>>
+  --
+  versionProperties : Properties
+}
+entity "Flavor" as flavor {
+  name : String
+  --
+  featuresKept : List<String> <<BR-2>>
+}
+entity "Format" as format {
+  name : String
+  --
+  imageFolder : boolean <<BR-5>>
+  pandocFormat : String
+  extension : String
+  args : List<String>
+}
+entity "Template" as tpl {
+  language, style
+  --
+  srcDir, imagesDir, mainFile
+  hasImages, adocFileCount
+  revnumber
+}
+entity "Distribution" as dist {
+  fileName <<BR-9>>
+  --
+  sourceDir
+}
+lang ||--o{ tpl
+flavor ||--o{ tpl
+tpl }o--o{ format
+tpl ||--o{ dist
+format ||--o{ dist
+@enduml
+....
+
+`Template` is the only record that crosses stage boundaries. It exists solely as an untyped `Map`
+with 13 keys (`lib/Discovery.groovy:127-140`); `Format` is split across two places, the
+configuration map and the descriptor table (`buildconfig.groovy:17-35`,
+`lib/Converter.groovy:382-398`). Both are technical debt TD-7 and a maintainability cost noted in
+QS-02.
+
+=== State Machine: a single conversion
+
+[plantuml,spec_states,svg]
+....
+@startuml
+[*] --> Dispatched
+Dispatched --> DirectHTML : format == html
+Dispatched --> CopiedAsciiDoc : format == asciidoc
+Dispatched --> Pivoted : every other format
+Pivoted --> PandocRunning : DocBook written
+PandocRunning --> Converted : exit 0
+PandocRunning --> Failed : exit != 0 (single page)
+PandocRunning --> SilentlyIncomplete : exit != 0 (multi page)
+DirectHTML --> Converted
+CopiedAsciiDoc --> Converted
+Converted --> [*]
+Failed --> [*] : counted, run continues
+SilentlyIncomplete --> [*] : warning only, nothing counted
+note bottom of SilentlyIncomplete
+  Risk R-1: this state is
+  indistinguishable from success
+  in the build result
+end note
+@enduml
+....
+
+=== Interface Contracts
+
+Summarised from SUC-1 to SUC-6:
+
+* *CLI* — three optional arguments, no validation, two exit codes.
+* *Configuration* — Groovy script, three blocks, no schema.
+* *Golden Master* — one main file, a chapter directory, images, an optional version file.
+* *Distribution* — one archive per triple, fixed name pattern, missing source is skipped silently.
+* *Pandoc* — argument vector plus UTF-8 environment; error handling differs between single-page
+and multi-page, which is R-1.
+* *AsciidoctorJ* — `SafeMode.UNSAFE`, base directory is the template source directory, attributes
+from `createAttributes` (`lib/Converter.groovy:95`, `:356-376`).
+
+=== Validation Rules
+
+[cols="1,3,2,1",options="header"]
+|===
+|ID |Rule |Evidence |Enforced
+
+|V-1
+|The Golden Master source path must exist.
+|`lib/Templates.groovy:33-35`
+|yes, fatal
+
+|V-2
+|At least one language directory must be found.
+|`lib/Templates.groovy:42-44`
+|yes, fatal
+
+|V-3
+|A generated flavor must contain a `src/` directory with at least one `.adoc` file, otherwise it
+is skipped with a warning.
+|`lib/Discovery.groovy:96-105`
+|yes, warning
+
+|V-4
+|Expected languages and flavors must be present.
+|`lib/Discovery.groovy:219-241`
+|only in tests
+
+|V-5
+|Generated Markdown must parse as CommonMark.
+|`build-arc42.sh:94-104`
+|yes, non-fatal, EN only
+
+|V-6
+|Every image directory of a `with-help` flavor must exist and be non-empty, for the five
+image-bearing formats.
+|`build-arc42.sh:124-149`
+|yes, non-fatal
+
+|V-7
+|Every image reference in a `with-help` Markdown file must resolve.
+|`build-arc42.sh:151-182`
+|yes, non-fatal
+
+|V-8
+|The phase and format arguments must name known values.
+|—
+|*no* — TD-3
+|===
diff --git a/dtcw4 b/dtcw4
new file mode 100755
index 0000000..68a39a0
--- /dev/null
+++ b/dtcw4
@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# Copyright 2024, Ralf D. Müller and the docToolchain contributors
+#
+# dtcw4 — wrapper for docToolchain v4
+#
+# Handles v4-specific installation (git clone main-4.x + packageLibs),
+# then delegates all task execution to the installed dtcw in
+# ~/.doctoolchain/docToolchain-<version>/dtcw.
+#
+# Only this script needs to live in your project directory.
+#
+# Usage:
+#   ./dtcw4 local install doctoolchain   — install v4 from source
+#   ./dtcw4 local generateHTML           — run a v4 task
+#   ./dtcw4 tasks                        — list available v4 tasks
+#   ./dtcw4 --version                    — show version info
+
+set -e
+set -u
+set -o pipefail
+
+DTC_VERSION=4.0.0
+export DTC_VERSION
+
+DTC_V4_BRANCH="${DTC_V4_BRANCH:-main-4.x}"
+GITHUB_PROJECT_URL=https://github.com/docToolchain/docToolchain
+
+DTC_ROOT="${HOME}/.doctoolchain"
+DTC_HOME="${DTC_ROOT}/docToolchain-${DTC_VERSION}"
+
+has() {
+    command -v "$1" 1>/dev/null 2>&1
+}
+
+error() {
+    echo "Error: $1" >&2
+}
+
+v4_install() {
+    local update_mode=false
+    if [ "${1:-}" = "--update" ]; then
+        update_mode=true
+    fi
+
+    if [ -d "${DTC_HOME}/lib" ] && [ -n "$(ls -A "${DTC_HOME}/lib/"*.jar 2>/dev/null)" ] && [ "${update_mode}" = false ]; then
+        echo "docToolchain v4 already installed in '${DTC_HOME}'."
+        echo ""
+        echo "To update, run:"
+        echo "  ./dtcw4 local install doctoolchain --update"
+        return 0
+    fi
+
+    if ! has git; then
+        error "git is required to install docToolchain v4 from source."
+        exit 1
+    fi
+
+    if ! has java; then
+        error "Java 17, 21 or 25 is required. Install with: ./dtcw4 local install java"
+        exit 1
+    fi
+
+    echo "Installing docToolchain v4 from branch '${DTC_V4_BRANCH}'..."
+    echo ""
+
+    if [ -d "${DTC_HOME}/.git" ]; then
+        echo "Updating existing clone..."
+        git -C "${DTC_HOME}" fetch origin "${DTC_V4_BRANCH}"
+        git -C "${DTC_HOME}" checkout "${DTC_V4_BRANCH}"
+        git -C "${DTC_HOME}" reset --hard "origin/${DTC_V4_BRANCH}"
+    else
+        # Remove non-git installation if it exists (e.g. from zip install)
+        if [ -d "${DTC_HOME}" ]; then
+            echo "Replacing existing installation with git clone..."
+            rm -rf "${DTC_HOME}"
+        fi
+        mkdir -p "${DTC_ROOT}"
+        echo "Cloning docToolchain (branch: ${DTC_V4_BRANCH})..."
+        git clone --branch "${DTC_V4_BRANCH}" --single-branch \
+            "${GITHUB_PROJECT_URL}.git" "${DTC_HOME}"
+    fi
+
+    echo ""
+    echo "Building v4 runtime libraries (one-time Gradle build, not needed at runtime)..."
+    (cd "${DTC_HOME}" && ./gradlew packageLibs --no-daemon --warning-mode=none -q)
+
+    local jar_count
+    jar_count=$(find "${DTC_HOME}/build/lib" -name '*.jar' 2>/dev/null | wc -l)
+
+    # Copy built libs to lib/ so dtcw can find them
+    mkdir -p "${DTC_HOME}/lib"
+    cp "${DTC_HOME}/build/lib/"*.jar "${DTC_HOME}/lib/"
+
+    echo ""
+    echo "docToolchain v4 installed successfully (${jar_count} JARs)."
+    echo ""
+    echo "Usage:"
+    echo "  ./dtcw4 tasks                  — list available tasks"
+    echo "  ./dtcw4 local generateHTML      — generate HTML"
+    echo "  ./dtcw4 local generatePDF       — generate PDF"
+    echo "  ./dtcw4 local generateSite      — generate microsite"
+    echo "  ./dtcw4 local downloadTemplate  — download arc42/req42 template"
+}
+
+# Intercept 'install doctoolchain' — delegate everything else to dtcw
+case "${1:-}" in
+    local)
+        if [ "${2:-}" = "install" ] && [ "${3:-}" = "doctoolchain" ]; then
+            v4_install "${4:-}"
+            exit 0
+        fi
+        if [ "${2:-}" = "install" ] && [ "${3:-}" = "java" ]; then
+            if [ ! -f "${DTC_HOME}/dtcw" ]; then
+                echo "Downloading dtcw to install Java..."
+                mkdir -p "${DTC_HOME}"
+                curl -sLo "${DTC_HOME}/dtcw" https://doctoolchain.org/dtcw
+                chmod +x "${DTC_HOME}/dtcw"
+            fi
+        fi
+        ;;
+    --help|-h)
+        echo "dtcw4 — docToolchain v4 wrapper"
+        echo ""
+        echo "Usage:"
+        echo "  ./dtcw4 local install doctoolchain [--update]"
+        echo "  ./dtcw4 [local] <task> [args...]"
+        echo "  ./dtcw4 tasks"
+        echo "  ./dtcw4 --version"
+        echo ""
+        echo "Environment variables:"
+        echo "  DTC_V4_BRANCH   Git branch to install from (default: main-4.x)"
+        echo ""
+        echo "Installation uses Gradle once to package runtime JARs."
+        echo "After that, all tasks run without Gradle (direct JVM execution)."
+        exit 0
+        ;;
+esac
+
+# For everything else, delegate to the installed dtcw
+DTCW="${DTC_HOME}/dtcw"
+if [ ! -f "${DTCW}" ]; then
+    error "docToolchain v4 is not installed. Run: ./dtcw4 local install doctoolchain"
+    exit 1
+fi
+
+exec "${DTCW}" "$@"