Collections and types

Type: kb/types/note.md

Every authored artifact in Commonplace is governed by two independent contracts:

  • Its location selects a collection. The nearest containing COLLECTION.md supplies that collection's text contract: purpose, quality goal, title and description conventions, lifecycle, and outbound-link rules.
  • Its type: frontmatter points to a type spec. The type spec supplies the artifact's structural and semantic contract: frontmatter fields, required sections, schema, authoring guidance, and any template.

The collection answers what role the artifact serves in this part of the KB. The type answers what shape the artifact takes. A note in kb/notes/ is theoretical, while a note in kb/reference/ describes the shipped system; both use the same structural type contract. A collection does not redefine the meaning of a type's fields.

How an artifact uses a type

A typed artifact stores the path to its type spec directly:

---
description: Why this artifact is useful to a reader
type: kb/types/note.md
tags: []
---

The pointer may be repository-relative (kb/...) or file-relative (./... or ../...). It must end in .md, resolve beneath kb/, and identify a type-spec document. Absolute paths, URLs, repository-relative paths containing .., missing files, and kb/types/text.md as an explicit type all fail validation.

File-relative pointers keep collection-local types stable when shipped content moves under an installed namespace. For example, an ADR under kb/reference/adr/ can carry:

type: ../types/adr.md

The path is the type's identity. Two type specs with the same name: at different paths are different contracts.

For an existing artifact, an agent follows type: and opens that document; no catalogue lookup is needed. For a new artifact, a user or workflow may supply the exact type path. A shorthand name is resolved by inspecting type-spec frontmatter under the global and collection types/ directories and requiring one exact name: match; duplicate names remain ambiguous until a path is supplied. A general write with no supplied type defaults to kb/types/note.md. A workflow that requires another type supplies its exact path. Implicit text is an explicit choice to write frontmatter-free Markdown, not a fallback from failed type lookup.

Lookup identifies the contract but does not authorize it for a collection. For an artifact inside a declared collection, validation permits global specs under kb/types/ and local specs under that collection's own types/ directory. A peer collection's local type fails. The entire kb/work/ subtree is the lifecycle exception: a workshop may reference any valid type spec so that it can stage work for any target collection or test the real contract. Files outside declared collections retain referential validation only.

What a type spec contains

A type spec is itself a typed Markdown document. Its frontmatter has this shape:

---
type: kb/types/type-spec.md
name: adr
description: Architecture decision record for accepted or proposed system decisions
schema: ./adr.schema.yaml
---

The body contains the natural-language authoring contract and may include a template. schema: points to a JSON Schema sidecar expressed as YAML; schema: null means that the type has no structural schema. kb/types/type-spec.md is the self-referential root contract.

The type contract is consumed in two ways:

  1. commonplace-validate checks the artifact against the resolved schema and the framework's deterministic base rules.
  2. Type-conformance review uses the type spec's body as the semantic criterion, covering requirements that a schema cannot decide.

The collection contract is reviewed separately against the artifact's containing COLLECTION.md. This keeps structural type semantics independent from collection-specific writing and routing conventions.

Where type specs live

The filesystem is the live inventory. There are two normal locations:

Open those directories—or follow an artifact's type: pointer—to see the current definitions. A prose list elsewhere is only a snapshot and is not the authority for what exists.

Common examples

These examples illustrate the model; they are not an exhaustive catalogue.

Type Scope Typical use
text implicit A Markdown file with no frontmatter; capture without a selectable type: value.
note global The base structured knowledge artifact.
instruction global Procedures, skills, prompts, and work packets.
definition global Operational vocabulary definitions.
adr kb/reference/ Architecture decisions about the shipped system.
structured-claim kb/notes/ Developed arguments whose shape fits its Evidence and Reasoning contract.
snapshot kb/sources/.snapshots/ Local faithful captures of external source material.
connect-report kb/reports/ Discovery-only connection output under the reports collection's retention policy.

Each linked type spec, not this table, defines the type.

Authoring composition

The ordinary writing path composes three files at read time:

  1. the writing skill for the general procedure;
  2. the target collection's COLLECTION.md for its text and link contract;
  3. the selected type spec for artifact shape and type-specific guidance.

There is no generated write-context packet or resolver command. After writing, validation is authoritative for deterministic conformance.

Relevant documentation:

  • Collection and text contract — defined-in: the precise collection boundary and the binding local declaration in COLLECTION.md
  • Validation contract — part-of: deterministic base rules, type-owned schemas, and semantic conformance review
  • Collections never own frontmatter semantics — extends: why a type owns its fields while a collection owns text-level conventions
  • Architecture — part-of: where global and installed collection-local types sit in the shipped layout
  • Type system — see-also: theory explaining why document types exist and what they enable
  • ADR 018 — evidenced-by: the decision establishing path-valued type identity