feat: a subtype gets its own page skeleton from types/<type>.<value>.md (#117)

Files changed:
- AGENTS.md
- CHANGES.md
- README.md
- VERSION
- docs/ownership-and-templates.md
- instructions/evolve-subtypes.md
- instructions/setup-instance.md
- instructions/subtype-templates.md
- instructions/upgrade-instance.md
- tools/CONTRACT.md
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/new_page.py
- tools/chemenu/tests/test_dist_cmd.py
- tools/chemenu/tests/test_docs_verify.py
- tools/chemenu/tests/test_new_page.py
- tools/chemenu/tests/test_toc.py
- tools/chemenu/tests/test_type_resolver.py
- tools/chemenu/toc.py
- tools/chemenu/type_resolver.py
- types/concept.decision.md
- types/entity.guidance.md
- types/entity.md
- types/entity.person.md
- types/type-spec.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2

instructions/evolve-subtypes.md

@@ -102,6 +102,11 @@ choice of an instance's starting vocabulary - that is
 4. **Record it** with `tools/wikitool log append`, describing what moved and why, the same way
    any other corpus change is logged.
 
+5. **A newly added value scaffolds with the type's `## Template` block** until it has a subtype
+   template of its own. Whether its pages want a different skeleton is a separate judgment, made
+   against the pages once they exist, by the same ≥3-page rule as above:
+   [subtype-templates.md](subtype-templates.md).
+
 ## Decision points
 
 - **The catch-all is empty and lint reports nothing?** Nothing to do - an empty catch-all is the

instructions/setup-instance.md

@@ -146,6 +146,12 @@ one it needs before that.
       *this* instance writes, so they belong to it: frontmatter, template and language may all
       be rewritten. `instruction`, `lint-report`, `type-spec` and `type-guidance` describe stack
       artifacts and arrive unchanged - none of them ships as a `.template` in the first place.
+      The subtype templates beside them (`types/entity.person.md`, `types/concept.decision.md`:
+      the page skeleton `wikitool new` uses for that one subtype instead of the type's
+      `## Template` block) are adopted the same way and are page material like that block, so
+      they are translated with it. Whether this instance wants further ones is a question for
+      later, once pages exist to show it - [subtype-templates.md](subtype-templates.md), not
+      part of this setup.
 
       A `root: kb` type-spec's generic authoring guidance (when to use the type, when not to)
       is not part of this adoption at all: it lives in a sibling `types/<name>.guidance.md`

instructions/subtype-templates.md

@@ -0,0 +1,100 @@
+---
+type: types/instruction.md
+name: subtype-templates
+description: Interview the corpus and the user for page skeletons per subtype - find subtypes whose pages systematically depart from their type's template, propose a types/<type>.<value>.md for each, and write the ones the user accepts.
+manual: true
+---
+# Find the subtypes that need a page skeleton of their own
+
+A page type carries one `## Template` block for every value of its subtype field, and for most
+values that is enough. Where a subtype needs a different page shape - a person is not described by
+a version and a repository, a decision wants its context, alternatives and consequences - authors
+rebuild every scaffolded page by hand, and the corpus shows it. A **subtype template**,
+`types/<type>.<value>.md`, gives that subtype its own skeleton: `wikitool new` takes it instead of
+the block whenever the page's subtype field holds `<value>`. The file's shape and the checks on it
+are [types/type-spec.md](../types/type-spec.md) § "Anatomy of a type".
+
+This instruction is the interview that decides which subtypes get one. It reads the pages first
+and proposes from them, because a template written ahead of the material is a guess every later
+page is scaffolded into.
+
+## When to run
+
+- The user asks for it, by name or by describing the symptom: pages of one kind keep being
+  rebuilt after `wikitool new`.
+- After [evolve-subtypes.md](evolve-subtypes.md) added a value and its pages have accumulated.
+- After an upgrade delivered a subtype template as `.template` beside a type already adopted, and
+  the user wants to know whether to take it.
+
+Not for changing the `## Template` block every subtype shares - that is an edit to the type-spec
+itself. Not for adding a subtype value - that is [evolve-subtypes.md](evolve-subtypes.md).
+
+## Steps
+
+1. **List what there is to examine.** Every type-spec with a `subtype_field:`, every value its
+   schema allows, and which skeleton each value scaffolds today:
+
+   ```bash
+   tools/wikitool types list
+   tools/wikitool types describe <type>
+   ls types/
+   ```
+
+   A value scaffolds from `types/<type>.<value>.md` if that file exists, otherwise from the
+   type-spec's `## Template` block.
+
+2. **Hold each value's pages against the skeleton they were scaffolded from.** Find them and read
+   their `##` headings:
+
+   ```bash
+   tools/wikitool search --field <subtype_field>=<value>
+   ```
+
+   What counts is a departure several pages share: the same template section emptied or deleted,
+   the same section added under the same or an equivalent name, the same section replaced by
+   another. One page's own extra section is that page's business.
+
+3. **Apply the admission threshold of [evolve-subtypes.md](evolve-subtypes.md): at least three
+   pages of one subtype departing the same way.** A template is admitted after the material has
+   shown its shape, never in expectation of it. A smaller count is only ever an explicit exception
+   the user names, never a reason to lower the threshold.
+
+4. **Offer a shipped template as the starting point where one is lying ready.** A
+   `types/<type>.<value>.md.template` that was never adopted is the stack's proposal for that
+   subtype. Compare it with what the pages actually do, and propose it unchanged, adapted, or not
+   at all.
+
+5. **Put each candidate to the user, one at a time:** which pages, what they share, and a draft
+   of the template in the KB language (`kb/CONVENTIONS.md` `language:`) - the same variables and
+   filters the `## Template` block uses ([types/type-spec.md](../types/type-spec.md) § "Template
+   variables"), no frontmatter, no fence, no tool-owned section. The user decides per candidate:
+   accept, change, or reject.
+
+6. **Write each accepted template, then check it:**
+
+   ```bash
+   tools/wikitool dist adopt types/<type>.<value>.md.template   # only where step 4 took the shipped one unchanged
+   tools/wikitool docs verify
+   ```
+
+   Otherwise write `types/<type>.<value>.md` directly. `docs verify` refuses a file whose type has
+   no `subtype_field:`, whose value the schema does not allow, or which carries frontmatter.
+
+7. **Leave the existing pages as they are.** A template acts only on the next `wikitool new`;
+   reshaping existing pages to match it is ordinary page editing, decided per page, and not part
+   of this procedure.
+
+## Decision points
+
+- **The departures differ from page to page?** Then no template is warranted: a skeleton that
+  fits none of the pages well is not better than the one they already rebuild.
+- **All subtypes of a type depart the same way?** The `## Template` block itself is wrong, and
+  editing it is the fix - not one subtype template per value.
+- **The value is `guidance`?** It cannot have a template: `types/<type>.guidance.md` is always the
+  type's guidance file. Rename the value instead, through [evolve-subtypes.md](evolve-subtypes.md).
+
+## Scope
+
+Covers every page type that declares `subtype_field:` - in the shipped specs `entity`, `concept`,
+`source` and `project`. A type without one, such as `comparison`, has a single skeleton by
+construction. Does not move, rename or rewrite a page.

instructions/upgrade-instance.md

@@ -110,7 +110,12 @@ a further checkout of this one ([bootstrap.md](bootstrap.md)).
    - adopting it (copying it to the unsuffixed name) is the instance's own act, and where the
    stack *requires* that type the omission is what step 9's `docs verify` refuses. Step 2's
    **Breaking Change:** line says when a release is in that shape; step 9 has the repair.
-   `locally changed` is step 6. `removed` matters only if `--prune` is wanted, which is optional
+   One more shape of `new` needs no decision at all: a subtype template
+   `types/<type>.<value>.md.template` beside a type this instance has already adopted. Adopt it
+   (`tools/wikitool dist adopt types/<type>.<value>.md.template`) and `wikitool new` scaffolds
+   pages of that subtype from it; leave it lying and they keep the type's `## Template` block.
+   Both are valid - [subtype-templates.md](subtype-templates.md) is how to judge whether the
+   corpus wants it. `locally changed` is step 6. `removed` matters only if `--prune` is wanted, which is optional
    and never required.
 
 6. **Only if a file is reported as locally changed: decide whose file it is, then reconcile it.**