From dd565d249f8a584ea1572fe3ec3738b79de8352e Mon Sep 17 00:00:00 2001 From: Torben Nehmer Date: Sat, 3 Oct 2026 17:07:52 +0200 Subject: [PATCH] docs: page-material passages name subtype templates (#117) Files changed: - CHANGES.md - VERSION - docs/language-boundaries.md - tools/chemenu/commands/dist_cmd.py - types/type-guidance.md - types/type-spec.md Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2 --- CHANGES.md | 13 ++++++++++++- VERSION | 2 +- docs/language-boundaries.md | 8 +++++--- tools/chemenu/commands/dist_cmd.py | 4 ++-- types/type-guidance.md | 4 ++-- types/type-spec.md | 7 ++++--- 6 files changed, 26 insertions(+), 12 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index f6331f5..c5481b9 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -59,7 +59,7 @@ concern - readable here, never shipped as something to parse. --- -## 8.0.0-beta.31 - 2026-10-03 - new: a subtype gets its own page skeleton from types/..md +## 8.0.0-beta.32 - 2026-10-03 - Page-material passages in type-spec.md, type-guidance.md and language-boundaries.md name subtype templates **Author:** Torben Nehmer @@ -142,8 +142,19 @@ concern - readable here, never shipped as something to parse. - raw fetch --html record and kb/CONTRACT.md path budget follow the folder accept - stack-close no longer records which model and effort ran each phase - lint: a wikilink wrapped across a line break is its own finding; rename and rm see it +- Page-material passages in type-spec.md, type-guidance.md and language-boundaries.md name subtype templates +### Page-material passages in type-spec.md, type-guidance.md and language-boundaries.md name subtype templates + +Found in the closing check of the change below: three documents listed what in `types/` is page +material - and therefore in the KB language and the instance's to rewrite - as the `## Template` +block and the `layout:` titles alone. `types/type-spec.md` (§ Who owns a type-spec, its prose and +its language table), `types/type-guidance.md` (§ Conventions) and +`docs/language-boundaries.md` now name the subtype templates `types/..md` among +them, and a comment in `dist_cmd` does the same for `dist adopt`'s scope. No behaviour change +(Gitea #117). + ### new: a subtype gets its own page skeleton from types/..md A type-spec carried one `## Template` block for every value of its subtype field, so `wikitool diff --git a/VERSION b/VERSION index f0d46d3..7b6daff 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -8.0.0-beta.31 +8.0.0-beta.32 diff --git a/docs/language-boundaries.md b/docs/language-boundaries.md index c39d10a..ad31ba9 100644 --- a/docs/language-boundaries.md +++ b/docs/language-boundaries.md @@ -90,7 +90,9 @@ Making the control plane English does not make the instance's language an implem experiences: - **Page text.** Every page under `kb/`, and inside the page type-specs exactly the parts that - become page text - each one's `## Template` block and its `layout:` titles. + become page text - each one's `## Template` block, its `layout:` titles, and the subtype + templates `types/..md` beside it, which are page text from the first line to the + last. - **What an agent says.** An agent speaks the KB language, whatever the file it just read was written in. An instruction that models a sentence for the operator writes that model in English, like the rest of the control plane, and the agent delivers it in the instance's @@ -103,8 +105,8 @@ English instructions. The English is what the machinery is written in, not what A page type's contract is where the two languages meet most closely, and it is worth knowing which part is which before editing any of it. Its authoring guidance addresses an agent and is -English; its `## Template` block and `layout:` titles become the literal headings of pages and -follow the KB language; its field names and enum values are identifiers and are translated in +English; its `## Template` block, `layout:` titles and subtype templates become the literal +headings of pages and follow the KB language; its field names and enum values are identifiers and are translated in neither direction. The language line did not move when the *file* line did. A `root: kb` type-spec may now put its diff --git a/tools/chemenu/commands/dist_cmd.py b/tools/chemenu/commands/dist_cmd.py index 4b9dbdd..50666c6 100644 --- a/tools/chemenu/commands/dist_cmd.py +++ b/tools/chemenu/commands/dist_cmd.py @@ -748,8 +748,8 @@ def run_export(target: Path, dry_run: bool = False, origin: Optional[Origin] = N # The other half of the `.template` split above: an instance takes the shipped # default as its own by copying it to the unsuffixed name. Only the templates # whose shipped text is a working default are in scope - each collection's -# contract and the page type-specs with their schemas. `kb/CONVENTIONS.md` and -# the personalization files ship as templates too, but carry a sentinel and +# contract and the page type-specs with their schemas and subtype templates. +# `kb/CONVENTIONS.md` and the personalization files ship as templates too, but carry a sentinel and # exist to be filled in, so a verbatim copy of them would only be a file # `doctor` refuses; the agent writes those itself. diff --git a/types/type-guidance.md b/types/type-guidance.md index 43f906a..2b6d601 100644 --- a/types/type-guidance.md +++ b/types/type-guidance.md @@ -47,8 +47,8 @@ that file's own `guidance:` frontmatter field. - `tools/wikitool types describe ` composes both halves into one answer; an agent asking for a type's contract never needs to know it comes from two files - Written in the control plane's English ([AGENTS.md](../AGENTS.md) § File naming), like a - type-spec's own authoring prose - only the type-spec's `## Template` block and its `layout:` - titles are page material + type-spec's own authoring prose - only the type-spec's `## Template` block, its `layout:` + titles and its subtype templates (`types/..md`) are page material --- diff --git a/types/type-spec.md b/types/type-spec.md index d3a6fd9..320eea7 100644 --- a/types/type-spec.md +++ b/types/type-spec.md @@ -70,9 +70,9 @@ frontmatter before anyone drew it: | `root: kb` (`entity`, `concept`, `source`, `comparison`, `project`) | A page **this instance** writes | The instance | `types/.md.template` plus its `.schema.yaml.template` and any subtype template's `types/..md.template`, adopted by a rename | | `root: repo` (`instruction`), no `base_dir` (`lint-report`), and `type-spec`/`type-guidance` themselves | A stack artifact | The stack | Verbatim | -A page type-spec's frontmatter configuration and its `## Template` body are therefore the -instance's to rewrite, and an upgrade does not take that back. Its generic authoring prose is the -opposite: where the type-spec declares `guidance:`, that prose lives in a separate, stack-owned +A page type-spec's frontmatter configuration and its `## Template` body - and any subtype +template beside it (§ "Anatomy of a type") - are therefore the instance's to rewrite, and an +upgrade does not take that back. Its generic authoring prose is the opposite: where the type-spec declares `guidance:`, that prose lives in a separate, stack-owned `types/.guidance.md` (§ "Anatomy of a type" below) that ships verbatim and is overwritten by an upgrade like any other machinery file - the type-spec it documents does not have to be re-adopted, or even touched, for that improvement to arrive. A type-spec that declares no @@ -96,6 +96,7 @@ owns that file: | When to use / not to use, authoring guidance | The `guidance:` file, where declared | An agent writing a page | The control plane's — English | | The frontmatter table documenting this instance's own fields | The type-spec itself | An agent writing a page | The control plane's — English | | The `## Template` body, and the `layout:` titles that head a catalog section | The type-spec itself | The page itself | The instance's KB language (`kb/CONVENTIONS.md` `language:`) | +| A subtype template's whole text | `types/..md` | The page itself | The instance's KB language | | Field names, enum values, `dir:` values, `type:` paths | Either file's frontmatter | The machine | Neither — identifiers, never translated | That is the same prose/identifier cut [kb/CONTRACT.md](../kb/CONTRACT.md#language-and-identifiers)