stack: TOC-Scope auf types/ und docs/, Sprachregeln nach AGENTS.md zentralisiert, alle Templates auf Control-Plane-Sprache, --breaking akkumuliert (schliesst #99)

Files changed: - AGENTS.md - CHANGES.md - ENVIRONMENT.md.template - SOUL.md - SOUL.md.template - USER.md.template - VERSION - docs/ownership-and-templates.md - docs/version-model.md - instructions/CONTRACT.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md - instructions/dev/version-parts.md - instructions/setup-instance.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - kb/concepts/COLLECTION.md - kb/sources/COLLECTION.md - tools/CONTRACT.md - tools/chemenu/commands/types_cmd.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/tests/test_toc.py - tools/chemenu/tests/test_version_cmd.py - tools/chemenu/toc.py - tools/chemenu/version.py - types/comparison.md - types/concept.md - types/entity.md - types/lint-report.md - types/source.md
2026-09-15 16:21:02 +02:00
parent c0dc2129bb
commit c64479fe02
31 changed files with 1093 additions and 603 deletions
@@ -1,7 +1,7 @@
 ---
 type: types/type-spec.md
 name: comparison
-description: Strukturierter Typ für Vergleichsseiten, die mehrere Entities oder Ansätze gegenüberstellen
+description: Structured type for comparison pages that set several entities or approaches against one another
 schema: types/comparison.schema.yaml
 base_dir: comparisons
 page_ref_fields: [entities, related]
@@ -9,42 +9,46 @@ page_ref_fields: [entities, related]

 # Comparison

-`comparison` ist der Typ für Seiten, die mehrere Entities, Werkzeuge, Technologien oder Ansätze systematisch anhand festgelegter Kriterien gegenüberstellen. Vergleichsseiten stützen Entscheidungen und machen Zielkonflikte zwischen Alternativen sichtbar.
+`comparison` is the type for pages that set several entities, tools, technologies or approaches systematically against one another along fixed criteria. Comparison pages support decisions and make the trade-offs between alternatives visible.

-## Wann zu verwenden
+## When to use

- Vergleich mehrerer Technologien oder Frameworks für einen konkreten Einsatzzweck
- Analyse der Vor- und Nachteile verschiedener Werkzeuge oder Bibliotheken
- Bewertung alternativer Lösungswege für ein Problem
- Dokumentation eines Entscheidungsprozesses mit mehreren geprüften Optionen
+- Comparing several technologies or frameworks for a concrete purpose
+- Analysing the advantages and disadvantages of different tools or libraries
+- Evaluating alternative ways of solving a problem
+- Documenting a decision process with several options examined

-## Wann NICHT zu verwenden
+## When NOT to use

- Für die Dokumentation einer einzelnen Entity oder eines Concepts (dann `entity` bzw. `concept`)
- Für Zusammenfassungen von Quellmaterial (dann `source`)
- Für Seiten, die einen einzelnen Gegenstand behandeln statt mehrere zu vergleichen
+- For documenting a single entity or concept (use `entity` or `concept` respectively)
+- For summaries of source material (use `source`)
+- For pages covering a single subject rather than comparing several

 ## Frontmatter

-| Feld | Pflicht | Verwendung |
+| Field | Required | Use |
 |---|---:|---|
-| `type` | Ja | `types/comparison.md` |
-| `tags` | Nein | Navigations-Tags zur Kategorisierung |
-| `created` | Ja | Erstellungsdatum (YYYY-MM-DD) |
-| `entities` | Ja | Titel der verglichenen Entities |
-| `related` | Nein | Deklarierte ausgehende Kanten - je Subjekt eine `compares-with`-Kante, geschrieben von `wikitool xref add` |
-| `summary` | Ja | Einzeiler für `kb/index.md` |
+| `type` | Yes | `types/comparison.md` |
+| `tags` | No | Navigation tags for categorization |
+| `created` | Yes | Creation date (YYYY-MM-DD) |
+| `entities` | Yes | Titles of the entities compared |
+| `related` | No | Declared outbound edges - one `compares-with` edge per subject, written by `wikitool xref add` |
+| `summary` | Yes | One-liner for `kb/index.md` |

-## Autorenanweisungen
+## Authoring guidance

- Ein Titel, der den Vergleich benennt (z. B. "Go vs Rust", "Kubernetes vs Docker Swarm"); er folgt den etablierten Namen der verglichenen Gegenstände, nicht der KB-Sprache (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" und "Language")
- Klar darlegen, was verglichen wird und warum
- Eine Vergleichstabelle mit den Kriterien als Zeilen verwenden
- Eine Analyse, die die Tabelle auswertet statt sie zu wiederholen
- Eine Empfehlung, wo eine begründbar ist
+- A title that names the comparison (e.g. "Go vs Rust", "Kubernetes vs Docker Swarm"); it follows the established names of the subjects compared, not the KB language (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" and "Language")
+- State clearly what is being compared and why
+- Use a comparison table with the criteria as rows
+- An analysis that evaluates the table rather than repeating it
+- A recommendation wherever one can be justified

 ## Template

+The block below is page material, so it is written in this instance's KB language
+(`kb/CONVENTIONS.md` `language:`) rather than in the control plane's English - its headings
+become the headings of every page `wikitool new comparison` scaffolds.
+
 ```markdown
 # Comparison: {name}

@@ -67,16 +71,16 @@ TODO: Auswertung des Vergleichs. Welche Muster zeigen sich? Was sind die entsche
 TODO: Falls möglich - was wann und für wen zu verwenden ist. Unter welchen Umständen ist welche Option die beste?
 ```

-`# Comparison:` bleibt als Präfix stehen - anders als bei `source` ist es kein `title_prefix`,
-sondern reine Template-Konvention, und der Seitentitel selbst (`Go vs Rust`) trägt es nicht.
-Fügt `wikitool xref` eine Beziehung hinzu, entsteht der toolgeführte Querverweis-Abschnitt; wie
-er heißt, entscheidet die Instanz in `kb/CONVENTIONS.md` (`sections:`).
+`# Comparison:` stays as a prefix - unlike `source` it is no `title_prefix` but a pure template
+convention, and the page title itself (`Go vs Rust`) does not carry it. When `wikitool xref` adds
+a relationship, the tool-managed cross-reference section appears; what it is called is the
+instance's decision in `kb/CONVENTIONS.md` (`sections:`).

 ---

-Ergänzende Hinweise:
+Additional notes:

- Vergleichsseiten stützen Technologieauswahl und Architekturentscheidungen
- Die verglichenen Entities sollten alle als Wiki-Seiten existieren
- Die Kriterien sollten zur anstehenden Entscheidung passen
- Ein Vergleich bleibt auf einen konkreten Einsatzzweck oder Entscheidungskontext fokussiert
+- Comparison pages support technology selection and architecture decisions
+- The entities compared should all exist as wiki pages
+- The criteria should fit the decision at hand
+- A comparison stays focused on one concrete purpose or decision context
@@ -1,7 +1,7 @@
 ---
 type: types/type-spec.md
 name: concept
-description: Basistyp für Concept-Seiten - Architekturen, Muster, Protokolle, Abläufe, Entscheidungen oder Problemstellungen
+description: Base type for concept pages - architectures, patterns, protocols, workflows, decisions or problems
 schema: types/concept.schema.yaml
 subtype_field: concept_type
 base_dir: concepts
@@ -17,49 +17,63 @@ layout:

 # Concept

-`concept` ist der Typ für abstrakte Ideen, Methodiken, Muster und Architekturentscheidungen. Concepts liefern die theoretische und methodische Grundlage, die Entities umsetzen oder befolgen.
+`concept` is the type for abstract ideas, methodologies, patterns and architectural decisions. Concepts provide the theoretical and methodological ground that entities implement or follow.

-## Wann zu verwenden
+<!-- wikitool:toc -->
+## Contents

- Dokumentation eines Architekturmusters oder Entwurfsansatzes
- Erläuterung eines Entwurfsmusters oder einer Programmiermethodik
- Beschreibung eines Kommunikationsprotokolls oder Standards
- Festhalten eines Ablaufs oder Prozesses, der über Projekte hinweg wiederkehrt
- Dokumentation einer Architekturentscheidung (ADR) oder Entwurfsentscheidung
- Analyse eines wiederkehrenden Problems und seiner Lösungen
+- [When to use](#when-to-use)
+- [When NOT to use](#when-not-to-use)
+- [Frontmatter](#frontmatter)
+- [Authoring guidance](#authoring-guidance)
+- [Template](#template)
+<!-- /wikitool:toc -->

-## Wann NICHT zu verwenden
+## When to use

- Für konkrete Dinge wie Projekte, Systeme oder Werkzeuge (dann `entity`)
- Für Quelldokumente oder eingelesenes Material (dann `source`)
- Für vergleichende Analysen konkreter Gegenstände (dann `comparison`)
+- Documenting an architectural pattern or design approach
+- Explaining a design pattern or a programming methodology
+- Describing a communication protocol or standard
+- Recording a workflow or process that recurs across projects
+- Documenting an architectural decision (ADR) or design decision
+- Analysing a recurring problem and its solutions
+
+## When NOT to use
+
+- For concrete things such as projects, systems or tools (use `entity`)
+- For source documents or ingested material (use `source`)
+- For comparative analyses of concrete subjects (use `comparison`)

 ## Frontmatter

-| Feld | Pflicht | Verwendung |
+| Field | Required | Use |
 |---|---:|---|
-| `type` | Ja | `types/concept.md` |
-| `concept_type` | Ja | Eines von: architecture, pattern, protocol, workflow, decision, problem |
-| `tags` | Nein | Navigations-Tags zur Kategorisierung |
-| `created` | Ja | Erstellungsdatum (YYYY-MM-DD) |
-| `modified` | Ja | Datum der letzten Änderung (YYYY-MM-DD) |
-| `related` | Nein | Titel verwandter Concepts und Entities |
-| `sources` | Nein | Titel der Source-Seiten, die die Aussagen dieser Seite stützen |
-| `provenance` | Ja | sourced, general oder mixed |
-| `summary` | Ja | Einzeiler für `kb/index.md` |
+| `type` | Yes | `types/concept.md` |
+| `concept_type` | Yes | One of: architecture, pattern, protocol, workflow, decision, problem |
+| `tags` | No | Navigation tags for categorization |
+| `created` | Yes | Creation date (YYYY-MM-DD) |
+| `modified` | Yes | Date last changed (YYYY-MM-DD) |
+| `related` | No | Titles of related concepts and entities |
+| `sources` | No | Titles of the source pages backing this page's claims |
+| `provenance` | Yes | sourced, general or mixed |
+| `summary` | Yes | One-liner for `kb/index.md` |

-## Autorenanweisungen
+## Authoring guidance

- Der Titel ist der kanonische Name des Concepts und folgt der etablierten Fachbezeichnung, nicht der KB-Sprache (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" und "Language")
- Mit einer klaren Definition beginnen: was das Concept ist
- Beispiele geben, wo sie das Verständnis tragen
- Auf Entities verlinken, die das Concept umsetzen oder verwenden
- Bei `provenance: sourced` oder `mixed` harte Fakten inline mit einer `[^cite-id]`-Fußnote belegen -
-  `tools/wikitool cite add --page "<Title>" --source "Source - X"` erzeugt Id und Definition
- Wikipedia-Tonfall: sachlich, neutral, keine Werbesprache
+- The title is the concept's canonical name and follows the established term of art, not the KB language (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" and "Language")
+- Open with a clear definition: what the concept is
+- Give examples wherever they carry the understanding
+- Link to the entities that implement or use the concept
+- Under `provenance: sourced` or `mixed`, back hard facts inline with a `[^cite-id]` footnote -
+  `tools/wikitool cite add --page "<Title>" --source "Source - X"` mints the id and its definition
+- Wikipedia register: factual, neutral, no marketing language

 ## Template

+The block below is page material, so it is written in this instance's KB language
+(`kb/CONVENTIONS.md` `language:`) rather than in the control plane's English - its headings
+become the headings of every page `wikitool new concept` scaffolds.
+
 ```markdown
 # {name}

@@ -94,15 +108,15 @@ TODO: Anti-Muster, Warnungen oder Situationen, in denen es fehl am Platz ist
 - [[Related Concept 2]]
 ```

-Der Wert hinter `**Typ:**` bleibt der englische Enum-Wert - danach filtert `search --field`.
-Fügt `wikitool xref` eine Beziehung hinzu, entstehen zusätzlich die beiden toolgeführten
-Abschnitte für Beziehungen und Querverweise; wie sie heißen, entscheidet die Instanz in
+The value behind `**Typ:**` stays the English enum value - that is what `search --field` filters
+on. When `wikitool xref` adds a relationship, the two tool-managed sections for relationships and
+cross-references appear as well; what they are called is the instance's decision in
 `kb/CONVENTIONS.md` (`sections:`).

 ---

-Ergänzende Hinweise:
+Additional notes:

- Concept-Seiten tragen den theoretischen Unterbau des Wikis
- Jeder Concept-Typ steht für eine andere Kategorie abstrakten Wissens
- Concepts sollten von den Entities aus verlinkt sein, die sie umsetzen oder verwenden
+- Concept pages carry the wiki's theoretical underpinning
+- Each concept type stands for a different category of abstract knowledge
+- Concepts should be linked to from the entities that implement or use them
@@ -1,7 +1,7 @@
 ---
 type: types/type-spec.md
 name: entity
-description: Basistyp für Entity-Seiten - Projekte, Systeme, Werkzeuge, Technologien oder Personen
+description: Base type for entity pages - projects, systems, tools, technologies or people
 schema: types/entity.schema.yaml
 subtype_field: entity_type
 base_dir: entities
@@ -16,47 +16,61 @@ layout:

 # Entity

-`entity` ist der Typ für konkrete Dinge: Projekte, Systeme, Werkzeuge, Technologien oder Personen. Entities sind die primären Bausteine des Wissensgraphen.
+`entity` is the type for concrete things: projects, systems, tools, technologies or people. Entities are the primary building blocks of the knowledge graph.

-## Wann zu verwenden
+<!-- wikitool:toc -->
+## Contents

- Darstellung eines Softwareprojekts, einer Initiative oder eines Arbeitsvorhabens
- Dokumentation eines betriebenen Systems, Dienstes oder einer Infrastrukturkomponente
- Beschreibung eines CLI-Werkzeugs, Hilfsprogramms oder einer Programmbibliothek
- Festhalten von Informationen zu einer Sprache, einem Framework oder einem Protokoll
- Dokumentation einer Person, eines Teams oder einer Organisation
+- [When to use](#when-to-use)
+- [When NOT to use](#when-not-to-use)
+- [Frontmatter](#frontmatter)
+- [Authoring guidance](#authoring-guidance)
+- [Template](#template)
+<!-- /wikitool:toc -->

-## Wann NICHT zu verwenden
+## When to use

- Für abstrakte Konzepte, Muster oder Methodiken (dann `concept`)
- Für Quelldokumente oder eingelesenes Material (dann `source`)
- Für vergleichende Analysen (dann `comparison`)
+- Representing a software project, an initiative or a piece of work
+- Documenting a running system, service or infrastructure component
+- Describing a CLI tool, utility or software library
+- Recording information about a language, a framework or a protocol
+- Documenting a person, a team or an organization
+
+## When NOT to use
+
+- For abstract concepts, patterns or methodologies (use `concept`)
+- For source documents or ingested material (use `source`)
+- For comparative analyses (use `comparison`)

 ## Frontmatter

-| Feld | Pflicht | Verwendung |
+| Field | Required | Use |
 |---|---:|---|
-| `type` | Ja | `types/entity.md` |
-| `entity_type` | Ja | Eines von: project, system, tool, technology, person |
-| `tags` | Nein | Navigations-Tags zur Kategorisierung |
-| `created` | Ja | Erstellungsdatum (YYYY-MM-DD) |
-| `modified` | Ja | Datum der letzten Änderung (YYYY-MM-DD) |
-| `related` | Nein | Titel verwandter Seiten (Entities, Concepts, Sources) |
-| `sources` | Nein | Titel der Source-Seiten, die die Aussagen dieser Seite stützen |
-| `provenance` | Ja | sourced, general oder mixed |
-| `summary` | Ja | Einzeiler für `kb/index.md` |
+| `type` | Yes | `types/entity.md` |
+| `entity_type` | Yes | One of: project, system, tool, technology, person |
+| `tags` | No | Navigation tags for categorization |
+| `created` | Yes | Creation date (YYYY-MM-DD) |
+| `modified` | Yes | Date last changed (YYYY-MM-DD) |
+| `related` | No | Titles of related pages (entities, concepts, sources) |
+| `sources` | No | Titles of the source pages backing this page's claims |
+| `provenance` | Yes | sourced, general or mixed |
+| `summary` | Yes | One-liner for `kb/index.md` |

-## Autorenanweisungen
+## Authoring guidance

- Der Titel ist der kanonische Name der Entity und folgt der etablierten Bezeichnung des Gegenstands, nicht der KB-Sprache (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" und "Language")
- Die Hauptbeschreibung steht weit oben
- Auf verwandte Entities und Concepts verlinken, wo Beziehungen bestehen
- Bei `provenance: sourced` oder `mixed` harte Fakten inline mit einer `[^cite-id]`-Fußnote belegen -
-  `tools/wikitool cite add --page "<Title>" --source "Source - X"` erzeugt Id und Definition
- Wikipedia-Tonfall: sachlich, neutral, keine Werbesprache
+- The title is the entity's canonical name and follows the subject's established designation, not the KB language (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" and "Language")
+- The main description goes near the top
+- Link to related entities and concepts wherever relationships exist
+- Under `provenance: sourced` or `mixed`, back hard facts inline with a `[^cite-id]` footnote -
+  `tools/wikitool cite add --page "<Title>" --source "Source - X"` mints the id and its definition
+- Wikipedia register: factual, neutral, no marketing language

 ## Template

+The block below is page material, so it is written in this instance's KB language
+(`kb/CONVENTIONS.md` `language:`) rather than in the control plane's English - its headings
+become the headings of every page `wikitool new entity` scaffolds.
+
 ```markdown
 # {name}

@@ -84,15 +98,15 @@ TODO: Ausführliche Informationen, nach sinnvollen Abschnitten gegliedert
 - [{today}] - Page created via wikitool
 ```

-Der Beziehungsabschnitt steht bewusst **nicht** im Template: er ist eine generierte Region, die
-`wikitool xref` beim ersten Kanteneintrag zwischen Markern anlegt und aus `related:` neu
-rendert. Ein Autor schreibt dort nie hinein. Der Wert hinter `**Typ:**` bleibt der englische
-Enum-Wert - danach filtert `search --field`.
+The relationships section is deliberately **not** in the template: it is a generated region that
+`wikitool xref` creates between markers on the first edge entry and re-renders from `related:`.
+An author never writes into it. The value behind `**Typ:**` stays the English enum value - that is
+what `search --field` filters on.

 ---

-Ergänzende Hinweise:
+Additional notes:

- Entity-Seiten bilden den konkreten Bestand der Wissensbasis
- Jeder Entity-Typ (project, system, tool usw.) ist eine Ausprägung dieses Basistyps
- Die Beziehungen zwischen Entities tragen die Vernetzung des Wissensgraphen
+- Entity pages form the concrete inventory of the knowledge base
+- Every entity type (project, system, tool and so on) is a variant of this base type
+- The relationships between entities carry the knowledge graph's interconnection
@@ -65,4 +65,4 @@ Relevant Notes:
 - This type declares no `page_ref_fields:`: a report references pages in prose
  only, never through frontmatter.
 - It also declares no `base_dir:`, which is what keeps `reports/` out of `kb/`
-  and out of the index.
+  and out of the index.
@@ -1,7 +1,7 @@
 ---
 type: types/type-spec.md
 name: source
-description: Strukturierter Typ für Source-Seiten, die eingelesenes Rohmaterial erfassen und zusammenfassen
+description: Structured type for source pages that record and summarize ingested raw material
 schema: types/source.schema.yaml
 subtype_field: source_type
 base_dir: sources
@@ -20,71 +20,85 @@ layout:

 # Source

-`source` ist der Typ für Seiten, die eingelesenes Rohmaterial zusammenfassen und katalogisieren. Source-Seiten sind die Brücke zwischen der `raw/`-Schicht (unveränderliche Quelldateien) und der `kb/`-Schicht (kompiliertes Wissen). Eine Source-Seite steht für **eine logische Quelle**, die mehrere Raw-Dateien umfassen kann.
+`source` is the type for pages that summarize and catalogue ingested raw material. Source pages are the bridge between the `raw/` layer (immutable source files) and the `kb/` layer (compiled knowledge). One source page stands for **one logical source**, which may span several raw files.

-## Wann zu verwenden
+<!-- wikitool:toc -->
+## Contents

- Zusammenfassung eines einzelnen externen Artikels, Dokuments oder einer Spezifikation
- Erfassung mehrerer zusammengehöriger Notizen oder Gesprächsprotokolle als eine Quelle
- Dokumentation eines eingelesenen PDFs, Handbuchs oder sonstigen Dokuments
- Festhalten von Informationen zu einem Bild oder Diagramm
+- [When to use](#when-to-use)
+- [When NOT to use](#when-not-to-use)
+- [Frontmatter](#frontmatter)
+- [Authoring guidance](#authoring-guidance)
+- [Not Extracted](#not-extracted)
+- [Template](#template)
+<!-- /wikitool:toc -->

-## Wann NICHT zu verwenden
+## When to use

- Für kompiliertes Wissen (dann `entity` oder `concept`)
- Für vergleichende Analysen (dann `comparison`)
- Für originären Wiki-Inhalt, der nicht aus Rohmaterial abgeleitet ist
+- Summarizing a single external article, document or specification
+- Recording several related notes or meeting records as one source
+- Documenting an ingested PDF, manual or other document
+- Capturing information about an image or a diagram
+
+## When NOT to use
+
+- For compiled knowledge (use `entity` or `concept`)
+- For comparative analyses (use `comparison`)
+- For original wiki content not derived from raw material

 ## Frontmatter

-| Feld | Pflicht | Verwendung |
+| Field | Required | Use |
 |---|---:|---|
-| `type` | Ja | `types/source.md` |
-| `source_type` | Ja | Eines von: transcript, analysis, article, document, notes, tracker, unclassified - kein Default, siehe unten |
-| `author` | Ja | Urheber des Quellmaterials |
-| `raw_files` | Ja | Raw-Dateipfade, die diese Quelle **besitzt** - siehe "Eine Raw-Datei, ein Besitzer" unten |
-| `fidelity` | Ja (im Werkzeug, nicht im Schema) | Wie treu die *Erfassung* ist: `verbatim`, `published`, `secondhand`, `nontextual` - Capture-Feld, siehe unten |
-| `authority` | Ja (im Werkzeug, nicht im Schema) | Was das Material über seinen *Gegenstand* behaupten darf: `normative`, `reporting`, `opinion` - Capture-Feld, siehe unten |
-| `source_url` | Nein | Ursprungs-URL bei externen Quellen |
-| `source_language` | Nein | ISO-639-1-Code der Sprache des Rohmaterials, z. B. `de`, `en`, `fr` |
-| `date` | Ja | Veröffentlichungs- oder Erstellungsdatum (YYYY-MM-DD) |
-| `tags` | Nein | Navigations-Tags zur Kategorisierung |
-| `entities` | Nein | Titel der in dieser Quelle erwähnten Entities |
-| `concepts` | Nein | Titel der in dieser Quelle erwähnten Concepts |
-| `summary` | Ja | Einzeiler für `kb/index.md` |
+| `type` | Yes | `types/source.md` |
+| `source_type` | Yes | One of: transcript, analysis, article, document, notes, tracker, unclassified - no default, see below |
+| `author` | Yes | Originator of the source material |
+| `raw_files` | Yes | Raw file paths this source **owns** - see "One raw file, one owner" below |
+| `fidelity` | Yes (in the tool, not in the schema) | How faithful the *capture* is: `verbatim`, `published`, `secondhand`, `nontextual` - a capture field, see below |
+| `authority` | Yes (in the tool, not in the schema) | What the material may claim about its *subject*: `normative`, `reporting`, `opinion` - a capture field, see below |
+| `source_url` | No | Origin URL for external sources |
+| `source_language` | No | ISO 639-1 code of the raw material's language, e.g. `de`, `en`, `fr` |
+| `date` | Yes | Publication or creation date (YYYY-MM-DD) |
+| `tags` | No | Navigation tags for categorization |
+| `entities` | No | Titles of the entities mentioned in this source |
+| `concepts` | No | Titles of the concepts mentioned in this source |
+| `summary` | Yes | One-liner for `kb/index.md` |

-## Autorenanweisungen
+## Authoring guidance

- Der Titel beginnt mit "Source - ", gefolgt vom Namen der Quelle
- `source_type` hat **keinen Default** - `wikitool new source` verweigert ohne einen expliziten Wert. Ist die Kategorie unklar, `unclassified` setzen statt zu raten; das ist ein sichtbares Katalogfach mit beratendem `lint`-Befund, kein Sammelbecken. Was `analysis` von `document` trennt und welche Area welchen Wert hält: [kb/sources/COLLECTION.md](../kb/sources/COLLECTION.md)
- `raw_files` listet jede Raw-Datei, die diese Quelle abdeckt (eine Source-Seite pro logischer Quelle, nicht pro Datei)
- `fidelity` und `authority` sind **Capture-Felder** (`capture_fields:` oben): am Drop-Punkt erhoben, danach nicht mehr frei änderbar. `wikitool raw accept --fidelity <wert> --authority <wert>` verweigert ohne beide; ohne `--page` druckt es stattdessen die fertige `new source --set fidelity=... --set authority=...`-Zeile, die `new source` seinerseits ohne beide Werte verweigert. `wikitool touch --set fidelity=<wert>` schreibt nur, solange das Feld fehlt - steht bereits ein Wert, verweigert es und verweist auf `raw accept --replaces` als einzigen Korrekturweg (eine korrigierte Erfassung ist eine neue Edition, keine Bearbeitung). `unknown` ist backfill-only: nur `wikitool touch` darf es schreiben, nie `raw accept` oder `new source` - dieselbe Konstruktion wie bei `source_language` für Seiten, die vor dieser Regel entstanden sind. Was die Werte bedeuten und wie sie sich unterscheiden: [raw/CONTRACT.md](../raw/CONTRACT.md#getting-a-file-in-incoming)
- Bei externen Artikeln immer `source_url` auf die Ursprungs-URL setzen
- `source_language` auf die Sprache des Rohmaterials setzen, nicht auf die der Seite
- Die Seite wird in der KB-Sprache geschrieben, unabhängig von der Sprache der Quelle; wörtliche Passagen werden im Original zitiert (`kb/CONVENTIONS.md` § "Language")
- Kernaussagen im Abschnitt Summary zusammenfassen
- Handlungsbedarf in den Abschnitt Action Items
- Bewusst Weggelassenes in den Abschnitt Not Extracted - siehe unten
- Erwähnte Entities und Concepts unter Related Entities/Concepts verlinken
+- The title starts with "Source - ", followed by the name of the source
+- `source_type` has **no default** - `wikitool new source` refuses without an explicit value. Where the category is unclear, set `unclassified` rather than guessing; that is a visible catalog slot with an advisory `lint` finding, not a dumping ground. What separates `analysis` from `document`, and which area holds which value: [kb/sources/COLLECTION.md](../kb/sources/COLLECTION.md)
+- `raw_files` lists every raw file this source covers (one source page per logical source, not per file)
+- `fidelity` and `authority` are **capture fields** (`capture_fields:` above): recorded at the drop point and not freely changeable afterwards. `wikitool raw accept --fidelity <value> --authority <value>` refuses without both; without `--page` it instead prints the ready-made `new source --set fidelity=... --set authority=...` line, which `new source` in turn refuses without both values. `wikitool touch --set fidelity=<value>` only writes while the field is absent - where a value already stands, it refuses and points at `raw accept --replaces` as the one correction path (a corrected capture is a new edition, not an edit). `unknown` is backfill-only: only `wikitool touch` may write it, never `raw accept` or `new source` - the same construction as `source_language` uses for pages that predate this rule. What the values mean and how they differ: [raw/CONTRACT.md](../raw/CONTRACT.md#getting-a-file-in-incoming)
+- For external articles, always set `source_url` to the origin URL
+- Set `source_language` to the raw material's language, not the page's
+- The page is written in the KB language, whatever language the source is in; verbatim passages are quoted in the original (`kb/CONVENTIONS.md` § "Language")
+- Summarize the key claims in the summary section
+- Put anything actionable in the action items section
+- Put deliberate omissions in the not-extracted section - see below
+- Link the entities and concepts mentioned under related entities/concepts

 ## Not Extracted

-Die Entscheidung, dass Material *nicht* übernommen werden soll, ist nicht rekonstruierbar: nichts
-im Repository kann sie neu herleiten, und `sources coverage` weiß nur, ob eine Raw-Datei von
-irgendeiner Source-Seite beansprucht wird - nie, ob jemand über ihren Inhalt entschieden hat.
-Bleibt das unaufgeschrieben, wird dieselbe Quelle bei jedem späteren Durchgang neu verhandelt.
+The decision that material should *not* be taken over cannot be reconstructed: nothing in the
+repository can re-derive it, and `sources coverage` only knows whether a raw file is claimed by
+some source page - never whether anyone decided about its contents. Left unwritten, the same
+source is renegotiated on every later pass.

- Jede bewusste Auslassung mit **Begründung** festhalten, nicht nur mit Dateinamen.
- Pflicht, wenn der Ingest über `instructions/ingest-large-tree.md` lief - auf beiden Achsen:
-  beim Tree-Ingest hält der Abschnitt fest, was aus dem Baum nicht übernommen wurde, bei einer
-  thematisch breiten Einzelquelle, welche genannten Gegenstände keine eigene Seite bekommen
-  haben und warum. Optional bei einer einzelnen kleinen Datei - aber ein leerer Abschnitt ist
-  immer noch besser als ein fehlender.
- Gehört auf die Source-Seite, nicht in `kb/log.md`: es ist eine Aussage über *diese* Quelle,
-  und das Log ist chronologisch, nicht quellenbezogen.
+- Record every deliberate omission with a **reason**, not just a filename.
+- Mandatory where the ingest ran through `instructions/ingest-large-tree.md` - on both axes: for
+  a tree ingest the section records what was not taken from the tree; for a thematically broad
+  single source, which named subjects got no page of their own, and why. Optional for a single
+  small file - but an empty section still beats a missing one.
+- Belongs on the source page, not in `kb/log.md`: it is a statement about *this* source, and the
+  log is chronological rather than per-source.

 ## Template

+The block below is page material, so it is written in this instance's KB language
+(`kb/CONVENTIONS.md` `language:`) rather than in the control plane's English - its headings
+become the headings of every page `wikitool new source` scaffolds.
+
 ```markdown
 # Source: {name}

@@ -121,24 +135,18 @@ TODO: 2-3 Absätze zu den Kernaussagen des Quellmaterials.
 {concepts|bullets}
 ```

-`# Source:` bleibt als Präfix stehen - es spiegelt den `title_prefix` und damit den Titel, unter
-dem die Seite verlinkt und zitiert wird. Der Wert hinter `**Typ:**` bleibt der englische
-Enum-Wert. Fügt `wikitool cite` ein Zitat hinzu, entsteht am Seitenende der toolgeführte
-Fußnoten-Block; wie er heißt, entscheidet die Instanz in `kb/CONVENTIONS.md` (`sections:`).
+`# Source:` stays as a prefix - it mirrors the `title_prefix` and with it the title the page is
+linked and cited under. The value behind `**Typ:**` stays the English enum value. When
+`wikitool cite` adds a citation, the tool-managed footnote block appears at the end of the page;
+what it is called is the instance's decision in `kb/CONVENTIONS.md` (`sections:`).

 ---

-Ergänzende Hinweise:
+Additional notes:

- Source-Seiten sind der maßgebliche Katalog dessen, was an Rohmaterial eingelesen wurde
- **Eine Raw-Datei, ein Besitzer.** Eine Raw-Datei steht in genau einem `raw_files:` - diese Seite ist dafür verantwortlich, sie zusammengefasst zu halten. Beliebig viele Seiten dürfen sie per `[^cite-id]` **zitieren**; ein Zitat ist Wiederverwendung, `raw_files:` ist eine Wartungszuständigkeit. Bei zwei Anspruchstellern ist undefiniert, welche Seite bei einer Änderung der Raw-Datei nachgezogen werden muss - dann verrotten beide still
- Source-Seiten machen Wissen bis zum ursprünglichen Rohmaterial rückverfolgbar
- `raw_files:` enthält konkrete existierende Dateipfade, nie Verzeichnisse
- Eine `raw_files:`-Liste jenseits von etwa 15 Einträgen zeigt an, dass der Schnitt zu grob war -
-  die Quelle hätte per `instructions/ingest-large-tree.md` in mehrere Source-Seiten geteilt
-  werden müssen
- `entities:` plus `concepts:` jenseits von etwa 20 Einträgen ist das Gegenstück auf der anderen
-  Achse: nicht zu wenig geschnitten, sondern zu viel auf einmal kompiliert. Geteilt wird eine
-  solche Quelle nicht - eine Raw-Datei hat einen Besitzer -, sie hätte den Extract-Pass aus
-  `instructions/ingest-large-tree.md` § "A broad source is not cut" gebraucht, damit nicht jeder
-  genannte Gegenstand eine Seite bekommt
+- Source pages are the authoritative catalogue of what raw material has been ingested
+- **One raw file, one owner.** A raw file appears in exactly one `raw_files:` - that page is responsible for keeping it summarized. Any number of pages may **cite** it via `[^cite-id]`; a citation is reuse, `raw_files:` is a maintenance responsibility. With two claimants it is undefined which page has to be brought up to date when the raw file changes - and then both rot quietly
+- Source pages make knowledge traceable back to the original raw material
+- `raw_files:` holds concrete existing file paths, never directories
+- A `raw_files:` list beyond roughly 15 entries indicates the cut was too coarse - the source should have been split into several source pages via `instructions/ingest-large-tree.md`
+- `entities:` plus `concepts:` beyond roughly 20 entries is the counterpart on the other axis: not cut too little, but compiled too much at once. Such a source is not split - a raw file has one owner - it needed the extract pass from `instructions/ingest-large-tree.md` § "A broad source is not cut", so that not every named subject gets a page