torben/chemenu
1
1
Fork 0
Code Issues 26 Pull Requests Actions Packages Releases 32 Activity

feat: Autorenkonventionen nach Eigentum geschnitten - kb/CONVENTIONS.md, deklarierte Collections (3.0.0)
CI / verify (push) Successful in 53s
Details
Release / release (push) Successful in 38s
Details

Browse Source 
Files changed:
- .gitea/workflows/ci.yml
- .wikitool-kb.json
- AGENTS.md
- CHANGES.md
- INSTALL.md
- README.md
- VERSION
- instructions/CONTRACT.md
- instructions/dev/testing-conventions.md
- instructions/german-terminology.md
- instructions/kb-profiles.md
- instructions/migrations/3.0.0-authoring-conventions.md
- instructions/private-instance.md
- instructions/setup-instance.md
- instructions/wiki-ingest/SKILL.md
- instructions/wiki-manage/SKILL.md
- kb/CONTRACT.md
- kb/CONVENTIONS.md
- kb/CONVENTIONS.md.template
- kb/comparisons/COLLECTION.md
- kb/concepts/COLLECTION.md
- kb/entities/COLLECTION.md
- kb/sources/COLLECTION.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/doctor.py
- tools/chemenu/commands/new_page.py
- tools/chemenu/conventions.py
- tools/chemenu/kb_collections.py
- tools/chemenu/kb_scan.py
- tools/chemenu/provenance.py
- tools/chemenu/sections.py
- tools/chemenu/tests/conftest.py
- tools/chemenu/tests/test_conventions.py
- tools/chemenu/tests/test_dist_cmd.py
- tools/chemenu/tests/test_doctor.py
- tools/chemenu/tests/test_new_page.py
- tools/chemenu/tests/test_types_cmd.py
- types/comparison.md
- types/concept.md
- types/entity.md
- types/source.md
- types/type-spec.md
This commit is contained in:
Torben Nehmer
2026-09-02 15:02:10 +02:00
parent 9843df99d3
commit 502971d147
45 changed files with 1817 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files
instructions/kb-profiles.md
+191
View File
@@ -0,0 +1,191 @@
---
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.
## 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, confidence rubric - 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; `adr-NNN-` for decisions; `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` |
| Confidence rubric | 0.5 base, +0.2 per supporting source (max +0.6), recency and source-quality bonuses; hedge with "möglicherweise"/"kann" below 0.6, "unsicher"/"unbestätigt" below 0.4 |
| 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 hedge a low-confidence claim - 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.
### `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.