From ef60e2984cf5f9d996a9532bcfd7114d31cfc95b Mon Sep 17 00:00:00 2001 From: Torben Nehmer Date: Tue, 15 Sep 2026 16:29:42 +0200 Subject: [PATCH] docs: ownership-and-templates benennt die gemischte Zustaendigkeit im Seiten-Type-Spec (Nachzug zu #99) Files changed: - docs/ownership-and-templates.md --- docs/ownership-and-templates.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/ownership-and-templates.md b/docs/ownership-and-templates.md index af2dbd0..068750d 100644 --- a/docs/ownership-and-templates.md +++ b/docs/ownership-and-templates.md @@ -16,6 +16,7 @@ overwriting them would silently erase a choice someone made on purpose. - [Why silent overwrite is the failure being designed against](#why-silent-overwrite-is-the-failure-being-designed-against) - [Why the boundary is a predicate rather than a list](#why-the-boundary-is-a-predicate-rather-than-a-list) - [Why a `.template`, not just an absent file](#why-a-template-not-just-an-absent-file) +- [Where the file boundary strains](#where-the-file-boundary-strains) - [The consequence in practice](#the-consequence-in-practice) @@ -91,6 +92,31 @@ also why `ENVIRONMENT.md` only warrants a WARN rather than a FAIL when absent - checkout among possibly several and is gitignored for that reason, so its absence is a normal state rather than a sign setup was skipped. +## Where the file boundary strains + +"The file itself already answers that" holds for every file above except one shape, and it is +worth naming rather than discovering: a `root: kb` type-spec has two audiences inside one file. + +Its authoring guidance - when to use this type, what each frontmatter field means, how to cite - +is instruction to an agent. It reads like the stack's own prose because it *is* the stack's own +prose: a later release that learns something about writing entity pages would want to improve it +everywhere. Its `## Template` block and its `layout:` titles are the opposite: they become the +literal headings of pages this instance writes, in the language this instance chose, and no +release has any business touching them. + +Ownership is per file, so the instance keeps both halves. The template half is correct that way. +The guidance half pays for it: an instance that adopted its type-specs at setup will never +receive an improvement to them again, because `dist upgrade` writes the `.template` beside the +adopted file and never the file itself. Nothing breaks, and nothing reports it - the instance +simply keeps reading the guidance it was handed the day it was created. + +This is not an argument against the per-file boundary; the boundary is what makes an upgrade +safe at all, and merging inside a shared file is the failure the whole section above is about. +It is an argument that this particular file is cut in the wrong place. Splitting it - the +template block into its own instance-owned file, the guidance staying stack-owned and shipping +verbatim - would put the boundary back where the audiences actually divide, and would cost a +migration for every instance that already adopted one. + ## The consequence in practice An upgrade sorts every shipped path into three categories, not two - and the third one only