chemenu/kb/CONVENTIONS.md

---
language: de
profile: german
sections:
  links: Beziehungen
  footnotes: Fußnoten
---

# kb/ - Authoring Conventions of This Instance

The decisions [kb/CONTRACT.md](CONTRACT.md) deliberately does not make. The contract holds what
the code enforces and is identical in every instance; this file holds what *this* instance
chose, and no other instance has to agree with a word of it.

**It binds all the same.** Everything below applies to every page under `kb/`, exactly as the
contract does. The difference is ownership, not authority: a rule here is changed by editing
this file, a rule there by changing the stack.

Adopted from the `german` profile in
[instructions/kb-profiles.md](../instructions/kb-profiles.md). That catalogue is a palette, not
an enum - what is written here is what holds, whether or not a profile says the same thing.

The frontmatter above is the one machine-read part. `sections:` names the headings the two
**generated regions** render under - the links region `wikitool xref` owns and the footnotes
region `wikitool cite` owns. Each sits between a marker pair, and the marker is what the tool
locates it by, so the heading here is a display value: changing it re-renders the words above
those regions and nothing else. Nothing matches on this text.

<!-- wikitool:toc -->
## Contents

- [Language](#language)
  - [Section headings](#section-headings)
- [Naming](#naming)
- [Tone](#tone)
- [Relationship labels](#relationship-labels)
- [Hedging](#hedging)
- [Keeping this file honest](#keeping-this-file-honest)
<!-- /wikitool:toc -->

## Language

Pages are written in **German** - the `language:` in this file's own frontmatter, and the one
place that value is written down. This binds `kb/`, and inside the page type-specs
(`types/entity.md`, `types/concept.md`, `types/source.md`, `types/comparison.md`) exactly the
parts that become page text: each one's `## Template` block, and the `layout:` titles that head a
catalog section. Their authoring guidance around those is instruction to an agent, so it follows
the control plane and stays English - the same prose/identifier cut
[kb/CONTRACT.md](CONTRACT.md#language-and-identifiers) makes inside a page, applied one level up.
`raw/` is untouched ([raw/CONTRACT.md](../raw/CONTRACT.md)).

Two things follow from that value rather than being decided here, both stated once in
[AGENTS.md § File naming](../AGENTS.md#file-naming): the control plane stays English whatever an
instance writes its pages in, and an agent *speaks* the language named above.

The first of those is not a setting this file withholds - it is not a setting at all. `language:`
above is the only language value in the tree, and what it binds is page text; a control-plane
document is English even when this instance wrote it for itself and never ships it. Why that is
an architecture decision rather than an unset parameter:
[docs/language-boundaries.md](../docs/language-boundaries.md).

Which line is prose and which is an identifier - and therefore what is translated at all - is
the contract's rule, not this file's: see
[kb/CONTRACT.md § Language and identifiers](CONTRACT.md#language-and-identifiers).

Established English technical terms stay English inside German prose - "GitOps", "Ownership
Model", "Reverse Proxy", "Pull Request". Translate a term only where the German one is genuinely
the more common usage. A coined German equivalent nobody else writes makes the page harder to
find, not more idiomatic.

Which terms those are, which have a settled German form, and the register the prose is written
in: [instructions/german-terminology.md](../instructions/german-terminology.md). It is lookup
material, not a second rule - every entry in it is a decision that was made wrong once first.

### Section headings

The two generated regions render under `## Beziehungen` and `## Fußnoten`. An author never
writes inside them - they are rebuilt from frontmatter on every write, exactly like
`kb/index.md` - and never has to write the heading either. Any *other* heading on a page is
ordinary prose and is translated with the rest.

There is no `## Siehe auch` region any more. It was the reciprocal half of a bidirectional
`xref add`; under authored directional edges, `see-also` is a *label* inside the links region.

## Naming

- Human-readable titles with spaces: `Hybrid Search.md`, `Gitea Actions.md` - not kebab-case.
- Singular for entities: `HA Integration.md`, not `HA Integrations.md`.
- Comparison pages read as a comparison: `Go vs Rust.md`.
- A decision (`concept_type: decision`) is named like any other concept - no `adr-NNN-` prefix.
  See [kb/concepts/COLLECTION.md § Decisions](concepts/COLLECTION.md#decisions).
- Prefer readability over convention when the two conflict.

What to name a thing: projects use their repository or common name; systems a descriptive
name; tools the tool's own name; technologies their standard spelling and capitalization;
people a full name or common handle.

The one naming fact that is *not* a choice, and therefore lives in the contract: the filename
stem is the page title, and `[[wikilinks]]` must match it exactly.

## Tone

Wikipedia style: factual, neutral, specific.

- No buzzwords ("bahnbrechend", "hochmodern", "leistungsstark", "revolutioniert").
- No AI filler ("es sei angemerkt", "es ist wichtig zu betonen", "in der heutigen Zeit").
- No em-dash asides carrying parenthetical reasoning.

Good: "MQTT ist ein leichtgewichtiges Publish-Subscribe-Protokoll für Geräte mit knappen
Ressourcen."

Bad: "MQTT ist ein bahnbrechendes, hochmodernes Protokoll, das die IoT-Kommunikation
revolutioniert - und es sei angemerkt, dass es ein Publish-Subscribe-Muster verwendet."

The blockquote cap is not here: `wikitool lint` reports it, so it is the contract's.

## Relationship labels

**Not this file's to list, and not localized.** A label is a machine value in `related:`, drawn
from [instructions/link-taxonomy.md](../instructions/link-taxonomy.md) and authorised per
destination in each `kb/<name>/COLLECTION.md`'s `outbound:` block. `- **depends-on:** [[Hermes]]`
is what a German page carries, and that is deliberate: the label is an identifier, so translating
it would make the graph's semantics depend on the prose again.

## Hedging

No number stands in for this any more (Gitea #60): hedge according to what the sources actually
carry, not against a threshold.

- `provenance: general` with no `sources:` is general knowledge, and prose says so plainly -
  "im Allgemeinen", "üblicherweise" - rather than dressing it up as a sourced claim.
- A page citing an `opinion`-standing source does not speak in the tone of one citing a
  `normative` one (`raw/CONTRACT.md`'s `authority` axis names the difference). Weigh the
  weakest source actually relied on for a given sentence, not the page's strongest citation.
- Where the sources disagree or only partly support a claim, say so in prose -
  "möglicherweise", "laut X, aber Y widerspricht" - instead of picking a side silently.

This is `SOUL.md`'s existing standard ("Was nicht belegt ist, ist nicht gewusst, nur vermutet -
und wird auch so benannt"), applied to `kb/` without a number competing next to it.

## Keeping this file honest

Change it when a convention actually changes. `sections:` is safe to change at any time - the
regions are located by their markers and re-rendered under the new words on the next write.
`wikitool doctor` FAILs on a missing or unfilled file, and `wikitool docs verify` refuses a
`sections:` block that does not name both regions.