chemenu/instructions/kb-profiles.md

---
type: types/instruction.md
name: kb-profiles
description: Ready-made answers for kb/CONVENTIONS.md and each COLLECTION.md - the proven collection contracts and language profiles this stack has shipped, offered as a palette to adopt or adapt, never as a binding source.
manual: true
---
# Pick a profile for a collection or for this instance's conventions

**This page is a palette, not an enum.** Each `kb/<name>/COLLECTION.md` stays authoritative for
its own collection and `kb/CONVENTIONS.md` for the instance as a whole; an entry here is a
proven starting point, nothing more. Adopting one means *copying its text into* that file - not
pointing at this page and inheriting whatever it says later. Nothing in the stack reads this
document, and `profile:` in a contract's frontmatter records where the text came from, not where
it lives.

That direction is deliberate and it is the opposite of how this repo used to work. Language,
tone, naming and the relationship vocabulary sat in `kb/CONTRACT.md`, a file `dist export` ships
verbatim - so every instance that wanted something else edited a stack file, and an upstream
merge handed the stack's answer back. What binds is now the instance's; what ships is this
catalogue, and it binds nothing.

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

- [When to run](#when-to-run)
- [Steps](#steps)
- [Language profiles](#language-profiles)
  - [`german`](#german)
  - [`english`](#english)
  - [Writing a third one](#writing-a-third-one)
- [Collection profiles](#collection-profiles)
  - [`entities`](#entities)
  - [`concepts`](#concepts)
  - [`sources`](#sources)
  - [`comparisons`](#comparisons)
- [Decision points](#decision-points)
- [Scope](#scope)
<!-- /wikitool:toc -->

## When to run

- Setting up a new instance: the KB-language step of
  [setup-instance.md](setup-instance.md) sends you here to fill `kb/CONVENTIONS.md`.
- Adding a collection to an existing instance, and wanting a contract that already works rather
  than a blank one.
- Rewriting an existing `COLLECTION.md` or `kb/CONVENTIONS.md` and wanting to see what the
  alternatives were.

Not for changing what the *stack* enforces. That is [kb/CONTRACT.md](../kb/CONTRACT.md), and it
is not a profile.

## Steps

1. **Decide what you are filling.** Two different files, and they are not interchangeable:

   | File | Holds | Profiles below |
   |---|---|---|
   | `kb/CONVENTIONS.md` | Language, section headings, naming forms, tone, relationship labels, the hedging rule - once per instance | [Language profiles](#language-profiles) |
   | `kb/<name>/COLLECTION.md` | What one collection holds, its quality goal, its local linking and naming rules | [Collection profiles](#collection-profiles) |

2. **Copy the entry's text into the file**, then edit it until it is true of this instance.
   A profile you adopted and then changed is still that profile's `profile:` value - the field
   records the starting point, not a promise of fidelity.

3. **Record it.** `profile: <name>` in the file's frontmatter, or `profile: none` for a
   collection written from scratch. `wikitool docs verify` checks the field is there; it does
   not check the value against this page, because a collection an instance invented has no
   entry here to name.

4. **Set `required_by_stack:` on a collection - and set it correctly.** This one is *not* a
   choice: it says whether `wikitool` resolves against the collection by name, and
   `docs verify` checks it against the stack's own list. `sources` is `true`, everything else
   is `false`. See [kb/CONTRACT.md § Collections](../kb/CONTRACT.md#collections).

## Language profiles

A language profile answers all of `kb/CONVENTIONS.md` at once. There is one today, because one
is what this repo has actually run.

### `german`

The profile this repo's own instance uses, and the reason this catalogue exists: it was the
stack's hardcoded behaviour until the conventions file existed.

| Decides | Value |
|---|---|
| `language:` | `de` |
| `sections:` | `Beziehungen` / `Siehe auch` / `Fußnoten` |
| Naming | Human-readable titles with spaces; singular for entities; a decision named like any other concept, no `adr-NNN-` prefix; `X vs Y` for comparisons |
| Tone | Wikipedia register, with a German buzzword and filler list |
| Relationship labels | `hängt ab von` · `verwendet` · `implementiert` · `erweitert` · `ersetzt` · `steht in Konflikt mit` · `benötigt` · `erzeugt` · `konsumiert` · `besitzt` · `pflegt` · `läuft auf` · `verwandt mit` |
| Hedging | By source standing, not a score: `provenance: general` with no `sources:` says "im Allgemeinen"/"üblicherweise"; a claim rests on its weakest cited source's `authority` (`normative` vs. `opinion`); disagreement is named in prose ("möglicherweise", "laut X, aber Y widerspricht") |
| Terminology | [german-terminology.md](german-terminology.md) - which English terms stay English, and which have a settled German form |

**The full text to copy** is this repo's own [kb/CONVENTIONS.md](../kb/CONVENTIONS.md). An
instance adopting it takes that file, not this table; the table is what the profile *decides*,
so you can tell at a glance whether it is the one you want.

Adopting it also means keeping `german-terminology.md`. An instance on any other language
deletes or replaces that file - it is the profile's lookup material, not the stack's.

### `english`

What `kb/CONVENTIONS.md.template` ships as its default, so "adopt `english`" means "fill in the
template and change nothing structural". `sections:` are `Relationships` / `See Also` /
`Footnotes`, which are also the names this stack wrote before it had a conventions file - so a
corpus that predates the split needs no translation pass to adopt this profile.

There is no worked text for the rest of it. The template's placeholders are the questions;
`german` above is what a filled answer looks like.

### Writing a third one

A language profile is not a translation of `german`. Two of its sections are judgment about a
language rather than vocabulary in it - which foreign technical terms stay untranslated, and how
to phrase hedged and disagreeing claims - and those are exactly the two that read as awkward when
translated mechanically. Write them, do not convert them.

The one part that is mechanical: `section_aliases:`. Whatever the corpus used before goes in
that list, and the pages then migrate one at a time instead of all at once.

## Collection profiles

The four collections this repo runs. Each is a whole `COLLECTION.md`, and **the text to copy is
the file itself** - `dist export` ships each one as `kb/<name>/COLLECTION.md.template`, which a
new instance adopts by renaming. What follows is what each decides, so you can tell whether you
want it.

### `entities`

Concrete, pointable things: projects, deployed systems, tools, technologies, people.

- **Quality goal:** pointability plus currency - what the thing is, where it actually is, and
  whether that is still true.
- **Areas** driven by the `entity_type:` field: `projects/`, `systems/`, `tools/`,
  `technologies/`, `people/`. Areas, not collections - they inherit the contract and carry no
  `COLLECTION.md`.
- **Per-area emphasis** spelled out, so a system page is not written like a technology page.
- `required_by_stack: false`.

Take it when the wiki is about things that exist. Adapt the area list first: it is the part most
likely to be wrong for another domain.

### `concepts`

Ideas rather than things: architectures, patterns, protocols, workflows, recurring problems,
and the decisions taken about them.

- **Quality goal:** explanatory sufficiency - the page answers *why it is done this way* without
  the reader opening the entity pages that use it.
- Carries the **ADR shape**: context, decision, consequences, status, and the rule that a
  superseded decision is never rewritten.
- Routes head-to-head arguments out to `comparisons/` rather than hosting them.
- `required_by_stack: false`.

Take it whenever `entities` is taken - the split between the two is what keeps either from
becoming an essay.

### `sources`

One page per ingested source, carrying the `raw_files:` provenance every citation resolves
against.

- **Quality goal:** faithful compression - what *this source* said, not what was concluded from
  it. A source page improved beyond its source is no longer evidence.
- Titles carry the `Source - ` prefix, applied by `wikitool new source`.
- `required_by_stack: **true**`. `sources coverage`, `[^cite-id]` resolution and
  `kb/provenance.md` resolve against the name `sources`.

Not optional in the way the others are. An instance may rewrite its authoring rules and may not
rename or drop it.

**`source_type` is a palette too, and the part most likely to be wrong for another domain -
adapt its value list first**, the same way `entities`' area list is called out above. This
repo's own list (`transcript, analysis, article, document, notes, tracker, unclassified`)
describes *what a private-projects instance ingests*; it says nothing about what a source is in
a different domain. Two worked lists, to show how little the values carry over:

| Instance | Plausible `source_type` values |
|---|---|
| Handball club and federation | `satzung` (bylaws), `protokoll` (minutes), `korrespondenz`, `spielbericht` (match report), `verbandsmitteilung` |
| Tabletop game master | `regelwerk` (rulebook), `abenteuermodul` (module), `sessionlog`, `handout`, `weltenbau` (worldbuilding) |

Adopting one means copying the value list into `types/source.schema.yaml`'s enum and giving each
value a `layout:` line in `types/source.md` - the same "copy the text in, do not point at this
page" rule as every other profile here. Keep the visible catch-all value (`unclassified` above)
in whatever list is adopted: a subtype field without one silently reintroduces the old
`default:`-driven collection point this stack removed, the moment nobody names an edge case.
Growing the list later, or draining the catch-all, is
[evolve-subtypes.md](evolve-subtypes.md).

**Not up for choice: `fidelity` and `authority`.** Unlike `source_type`, these two capture
fields are stack vocabulary - `types/source.md`'s `capture_fields:` - because they held the same
few values across every domain this catalogue tried, where `source_type` did not. An instance
adapts the *value list* above; it does not touch `fidelity`'s or `authority`'s enums.

### `comparisons`

Structured head-to-head evaluations of two or more things that already have pages.

- **Quality goal:** decidability - named, checkable dimensions and a stated trade-off, so a
  reader with a concrete situation can choose.
- Every subject must already have a page; a comparison is a view over existing knowledge.
- **Exempt from the orphan check** - comparisons are reached through the catalog, not through
  inbound prose links.
- `required_by_stack: false`.

Skip it in a wiki that records rather than decides. It is the one of the four that is genuinely
optional.

## Decision points

- **A profile is almost right?** Copy and edit. There is no partial adoption and no override
  file - the copy *is* the mechanism, and `profile:` still records where it started.
- **Two collections want the same profile?** Fine. `profile:` is not unique, and two
  collections holding different subject matter under the same authoring rules is an ordinary
  outcome.
- **Changing `sections:` after pages exist?** That is a corpus migration, not an edit. Put the
  old names in `section_aliases:` first, then translate page by page - the tool keeps finding
  the old headings for as long as the alias stands. See
  [migrate-corpus.md](migrate-corpus.md).
- **Tempted to make this page binding** - to have `COLLECTION.md` say `profile: entities` and
  nothing else? Do not. That is the arrangement this split was written to end: the instance
  would be bound by a file the stack ships and upgrades, which is how an upstream merge changes
  an instance's authoring rules without anyone deciding to.

## Scope

Covers what an instance authors under `kb/`. It says nothing about what the stack enforces
([kb/CONTRACT.md](../kb/CONTRACT.md)), what a page structurally is
([types/type-spec.md](../types/type-spec.md)), or how a command behaves
([tools/CONTRACT.md](../tools/CONTRACT.md)). None of those are profiles, and none of them are
the instance's to change.