torbenandClaude Opus 5.5
d66a3f65f4
The seven explanation pages move to docs/explanation/ without a stub, DEVELOPMENT.md becomes docs/dev/development.md (translated to English), dist export leaves docs/dev/ out, docs verify rejects a file outside the five areas, and AGENTS.md states that the stack's human documentation is English. Required migration 9.0.0-docs-diataxis rewrites the old path in an instance's own kb/CONVENTIONS.md. Files changed: - .wikitool-kb.json - AGENTS.md - CHANGES.md - CLAUDE.md - DEVELOPMENT.md - INSTALL.md - README.md - VERSION - docs/dev/development.md - docs/explanation/README.md - docs/explanation/knowledge-and-commitment.md - docs/explanation/language-boundaries.md - docs/explanation/model-and-effort-selection.md - docs/explanation/ownership-and-templates.md - docs/explanation/pipeline-rationale.md - docs/explanation/version-model.md - docs/explanation/why-gates-are-code.md - docs/how-to/README.md - docs/knowledge-and-commitment.md - docs/language-boundaries.md - docs/model-and-effort-selection.md - docs/ownership-and-templates.md - docs/pipeline-rationale.md - docs/reference/README.md - docs/tutorials/README.md - docs/version-model.md - docs/why-gates-are-code.md - instructions/CONTRACT.md - instructions/dev/dev-setup.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-mode.md - instructions/gtd-weekly-review/SKILL.md - instructions/ingest-queue.md - instructions/migrations/6.0.0-type-guidance-split.md - instructions/migrations/9.0.0-docs-diataxis.md - instructions/upgrade-instance.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - tools/CONTRACT.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/new_page.py - tools/chemenu/commands/task_cmd.py - tools/chemenu/tasks/protocol.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_docs_verify.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_toc.py - types/type-guidance.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
3.2 KiB
3.2 KiB
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: kbtype: 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 fileguidance: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 wayschema: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
## Templateblock, itslayout:titles and its subtype templates (types/<name>.<value>.md) are page material
Relevant Notes:
- Ships verbatim with every distribution; the type-spec it documents ships only as a
.templatewhereroot: kb- seedocs/explanation/ownership-and-templates.md§ "Where the file boundary used to strain" - No
## Templatesection here: a guidance file's body is prose an author reads, not a body structurewikitool newwould scaffold.type-guidancedeclares nobase_dir:for the same reasonlint-reportdoes, andwikitool new type-guidancerefuses 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 - seeinstructions/migrations/for the document