---
type: types/type-spec.md
name: type-guidance
description: "Stack-owned authoring prose for a root:kb page type - the machine-independent half a type-spec's optional guidance: field links to"
schema: 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](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](../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