chemenu/types/type-guidance.md

type, name, description, schema

type	name	description	schema
types/type-spec.md	type-guidance	Stack-owned authoring prose for a root:kb page type - the machine-independent half a type-spec's optional guidance: field links to	types/type-guidance.schema.yaml

Type Guidance

type-guidance describes the shape of one types/<name>.guidance.md file: the stack-owned half of a root: kb page type's contract. A page type-spec (types/type-spec.md § "Who owns a type-spec") splits at the audience line - what an agent needs to know to write a conforming page, versus what this instance's schema and template concretely are - and a guidance file is the machine-independent half of that split, linked from the type-spec it documents via that file's own guidance: frontmatter field.

When to Use

• Writing or improving the generic authoring rules for a root: kb type: when to choose it, when not to, and mechanism-level advice that holds regardless of which enum values, directory names or template text this instance chose - citation mechanics, provenance rules, what a conforming page does or does not claim
• Anything a later stack release would want every adopting instance to receive automatically, the way a fix to tools/ already does

When NOT to Use

• Enum values, layout: titles, directory names or template text. Those name this instance's choices and stay in the type-spec itself - the file guidance: points from, never the one it points to
• A type an instance writes entirely for itself. guidance: is optional; a type-spec that omits it is described from its own body alone, exactly as every type-spec worked before this type existed

Frontmatter

Field	Required	Use
type	Yes	types/type-guidance.md
name	Yes	The page type this documents, e.g. entity - matches that type-spec's own name:
description	Yes	Retrieval description for this guidance document

Conventions

• Linked from the type-spec it documents via that file's guidance: frontmatter field - a repo-relative path, resolved the same way schema: is
• 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 § File naming), like a type-spec's own authoring prose - only the type-spec's ## Template block and its layout: titles are page material

---

Relevant Notes:

• Ships verbatim with every distribution; the type-spec it documents ships only as a .template where root: kb - see docs/ownership-and-templates.md § "Where the file boundary used to strain"
• No ## Template section here: a guidance file's body is prose an author reads, not a body structure wikitool new would scaffold. type-guidance declares no base_dir: for the same reason lint-report does, and wikitool new type-guidance refuses for the same reason
• An instance that adopted its type-specs before this type existed sees nothing change until it takes the offered migration that adds guidance: to each one - see instructions/migrations/ for the document