types/type-spec.md: Ownership und Sprache getrennt benannt (Nachzug zu #99)
CI / verify (push) Successful in 44s
Release / release (push) Successful in 36s

Files changed:
- CHANGES.md
- VERSION
- types/type-spec.md
This commit is contained in:
2026-09-15 16:31:08 +02:00
parent ef60e2984c
commit 05a75065ba
3 changed files with 38 additions and 5 deletions
+18 -3
View File
@@ -67,12 +67,27 @@ frontmatter before anyone drew it:
| `root: kb` (`entity`, `concept`, `source`, `comparison`) | A page **this instance** writes | The instance | `types/<name>.md.template` plus its `.schema.yaml.template`, adopted by a rename |
| `root: repo` (`instruction`), no `base_dir` (`lint-report`), and `type-spec` itself | A stack artifact | The stack | Verbatim |
A page type-spec's prose, its `## Template` body and its language are therefore the instance's
to rewrite — an instance writing its pages in another language simply translates the file, and
A page type-spec's prose and its `## Template` body are therefore the instance's to rewrite, and
an upgrade does not take that back. Improvements to a shipped default reach it as an *offered*
migration ([instructions/CONTRACT.md](../instructions/CONTRACT.md#instructionsmigrations)),
never by overwriting.
**Ownership and language are not the same question here**, and this is the one file in the tree
where they come apart. Owning the file means the instance may rewrite any of it; the language it
writes in still follows what the line is *for*, per
[AGENTS.md § File naming](../AGENTS.md#file-naming):
| Part of a page type-spec | Audience | Language |
|---|---|---|
| Authoring guidance, frontmatter table, when to use / not to use | An agent writing a page | The control plane's — English |
| The `## Template` body, and the `layout:` titles that head a catalog section | The page itself | The instance's KB language (`kb/CONVENTIONS.md` `language:`) |
| Field names, enum values, `dir:` values, `type:` paths | The machine | Neither — identifiers, never translated |
That is the same prose/identifier cut [kb/CONTRACT.md](../kb/CONTRACT.md#language-and-identifiers)
makes *inside* a page, applied one level up. It binds a type-spec an instance writes for itself
exactly as it binds the four shipped ones: a new page type is instance-owned end to end, which
settles who may change it, not which language each half is written in.
**What the stack still requires of the type layer is one line.** There must be a type-spec
declaring `name: source` whose schema requires `raw_files:` — the whole `raw/``kb/`
provenance path (`sources coverage`, `[^cite-id]` resolution, `kb/provenance.md`) asks
@@ -175,7 +190,7 @@ replace anyway. See `tools/chemenu/blocks.py`.
| Frontmatter fields, enums, defaults, required-ness | Provenance and citation mechanics | Quality goal and tone |
| Directory placement and title prefix | Linking mechanics and the orphan check | Naming conventions |
| Body skeleton (template) | The prose/identifier rule | Relationship vocabulary |
| When to use / not use this type | — | The KB language and its section-heading names |
| When to use / not use this type | — | The KB language value, and its section-heading names |
If a rule would be identical for every type *and* every instance, it belongs in
`kb/CONTRACT.md`. If every instance would answer it differently, it belongs in