> ## Documentation Index > Fetch the complete documentation index at: https://knowledge-bus.pdflowlabs.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Spec anatomy > A definition file describes the knowledge for a subject or area of work. A definition file describes the knowledge for a subject or area of work. The protocol calls this a **universe**. Companion guidance explains how to answer its questions well. User definitions live in `.knowledge-bus/` inside the folder they describe. See [Knowledge Bus Directory](https://knowledge-bus.pdflowlabs.io/docs/knowledge-bus-directory.md) for directory selection rules. ## Definition and guidance files The included example has two files: * [universe.kbp.yaml](https://github.com/SterlingJF/knowledge-bus/blob/main/universe-samples/product-development/universe.kbp.yaml): questions, document purposes, composition rules, and relationships. * [type-guidance.kbp.yaml](https://github.com/SterlingJF/knowledge-bus/blob/main/universe-samples/product-development/type-guidance.kbp.yaml): advice and sources attached to those definitions. Guidance is optional. The universe must remain valid without it. When guidance is supplied, the checker validates its structure and references, not whether its advice is correct. ## Field reference | Key | Purpose | | - | - | | `universe` | Identifies the definition set, its version, the protocol version it follows, and its ordering frame. May add an `overview` and, from `kbp/0.8`, `terms`. | | `elements` | Defines knowledge units by the questions their contents answer. | | `artifacts` | Defines document types by the action or decision they enable for someone, and lists their contents. | | `frames` | Defines context used to organize or select content. A frame can make content required, exclude it, or determine that no document is needed. | | `factors` | Declares context that applications can use, without giving it control over document composition in the universe. Guidance can use a factor to select advice. | | `relation_kinds`, `relations` | Names the kinds of connections and the definitions they connect, such as dependencies or distinctions. | | `statuses` | Declares the statuses an assertion can carry. | | `no_artifact` | Says when no artifact is needed: when each frame it names has one of the listed values, nothing needs writing down. `kbp/0.7` calls it `empty_composition`. | | `instances` | Holds asserted answers with their party, status, time, and other instance details. | The optional `terms` list names the universe's own words, each with the one meaning it has throughout the definitions: `{ term, means }`, each term once, compared case-insensitively. Terms carry no structure, and universes still correspond by question, not by term. For example, a frame could make a section required in one situation and unnecessary in another. A factor could select relevant writing advice without changing the required sections. A universe spec with elements names its ordering frame in the `universe` header. From `kbp/0.9`, a universe spec with no element, such as one declaring only factors, names no ordering frame. Guidance keyed to a factor is advice on presenting a document. An agent can apply the advice to the documents of any universe spec in the folder. The factor still adds or removes no section. The guidance file has a header (`guidance`), declared advice kinds (`guidance_kinds`), a source registry (`sources`), and entries attached to `elements`, `artifacts`, or `factors`. ## Defining elements and artifacts An element is identified by its question. Two candidate sections answering the same question refer to the same element, regardless of their headings. A document type is identified by the action or decision it enables and the actor who needs it. Its required contents are the information that actor needs to proceed. Other contents depend on the situation. Before adding a definition, compare it with existing questions and document purposes. You may need to clarify an existing definition rather than add another. `/kb-uncover-question` and `/kb-evolve` support that review. ## Stable codes Elements, artifact types, frames, and factors each carry a five-character code. The first character identifies the kind; the remaining characters have no encoded meaning. Codes do not encode meaning or order. People and agents use the readable id and question. Tools use the code to keep a stable reference when the same definition is renamed. Preserve its code and update references that use the changed id. Never reuse or reassign a retired code. From the repository root: ```bash theme={null} uv run kbp --mint element 3 path/to/project/.knowledge-bus/ ``` Replace the example path with your `.knowledge-bus/` directory. This generates three element codes checked against its definitions. Use `artifact`, `frame`, or `factor` for other kinds. See [Adapting the Example](https://knowledge-bus.pdflowlabs.io/docs/adapting-a-sample.md) for use with your own definitions. ## Requirements vs. recommendations Put declarations and structural rules in the universe file. Put recommendations and their reasoning in guidance. For example, a rule requiring a section belongs in the document's composition. Advice on writing that section clearly belongs in guidance. In the included guidance, conventions require registered sources. Other kinds, such as pitfalls and heuristics, may be marked `asserted`. Each guidance document declares which of its advice kinds require sources. ## Validation scope The checker validates supported structural rules in universe and guidance files. It does not yet fully validate instances or validate ingestion's separate `answers.yaml` format. See [Validation](https://knowledge-bus.pdflowlabs.io/docs/validation.md) for commands and limitations. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.