docs: page-material passages name subtype templates (#117)
CI / verify (push) Successful in 5m27s
CI / pwsh (push) Successful in 2m5s
Release / release (push) Successful in 35s

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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
This commit is contained in:
torbenandClaude Opus 5.5 committed 2026-10-03 17:07:52 +02:00
1 parent d8cb494d58
commit dd565d249f
6 files changed
+26 -12

No files matched your search

+2 -2
View File
@@ -47,8 +47,8 @@ that file's own `guidance:` frontmatter field.
- `tools/wikitool types describe <name>` 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/<name>.<value>.md`) are page material
---
+4 -3
View File
@@ -70,9 +70,9 @@ frontmatter before anyone drew it:
| `root: kb` (`entity`, `concept`, `source`, `comparison`, `project`) | A page **this instance** writes | The instance | `types/<name>.md.template` plus its `.schema.yaml.template` and any subtype template's `types/<name>.<value>.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/<name>.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/<name>.<value>.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)