Scope

This reference describes the Kind convention and recipe formats supported by the current stable release. It is for bundle authors, recipe authors, and integrators who need exact discovery, validation, and installation behavior. The current release evidence identifies the package, source tag, and verification boundary.

Kind discovery

Superbee builds a bundle's live Kind registry from ordinary OKF Markdown documents that meet both conditions:

• the document ID is under conventions/; and

• its frontmatter declares type: Convention.

The governs value is required and names the instance type. A Convention outside conventions/ is not discovered. Malformed declarations are skipped and reported as registry warnings. When multiple documents govern the same type, the first document by ID wins and the others produce KIND_DUPLICATE_GOVERNS warnings.

Inspect the active registry rather than inferring it from recipe history:

superbee kinds
superbee new "<Kind>" --help

kinds projects the schema into Superbee's authoring vocabulary and includes registry warnings. new "<Kind>" --help reports the exact required and optional fields, allowed values, ID prefix, headings, and link guidance for one declared Kind.

Convention document format

This example uses every supported declaration group in recipe-source syntax:

---
type: Convention
title: Experiment
governs: Experiment
description: A bounded test of a stated question and method.
path: experiments/
fields:
  required: [title, progress_status]
  optional: [owner, confidence]
  descriptions:
    owner: Person responsible for the next action.
  values:
    progress_status: [planned, running, complete]
    confidence: [low, medium, high]
  value_descriptions:
    confidence:
      low: Evidence is preliminary.
      high: Evidence has survived the planned checks.
  terminal:
    progress_status: [complete]
links:
  uses: Dataset
link_descriptions:
  uses: Dataset used by this experiment.
expects_inbound:
  contains: Program
sections: [Question, Method, Result]
freshness_horizon: 30d
browse_collapsed: true
---

Recipe application materializes the logical progress_status declaration to the bundle edition's physical field: status for v0.1 and superbee_progress_status for v0.2. When authoring a Convention directly inside a bundle, declare that edition-specific physical field in required, optional, values, value_descriptions, terminal, and descriptions. Agents still use the logical progress_status input when the Kind declares the physical coordinate. A direct progress_status declaration creates an ordinary field and disables this compatibility alias. See OKF compatibility for the lifecycle-field boundary.

The Markdown body is guidance for people and agents. The frontmatter fields below drive product behavior.

Keys under fields are limited to required, optional, values, value_descriptions, terminal, and descriptions. Unknown keys in that block produce warnings and are ignored. Unknown top-level frontmatter remains available to other OKF producers. The near-miss top-level keys enum, enums, values, and constraints produce warnings because enum constraints belong under fields.values.

Core filters type, dir, remote, json, help, body, and body-file from declared fields. The new command also consumes link and no-prefix as controls, so recipe authors should avoid those names for fields intended for superbee new. actor is a supported control-backed field: --actor <name> supplies mutation attribution and can satisfy a Kind that requires actor.

Validation modes

The same Kind validator checks required fields, enum membership and scalar arity, and declared level-one sections. The command determines whether findings warn or block.

Typed links use a teaching posture: link add warns when an exact declared link type has the wrong source or target Kind, while status applies the same rule across the bundle. expects_inbound also feeds the read-only missing_expected_links report.

Recipe folder format

A recipe packages definitions for installation into another bundle. The minimum folder contains a manifest and at least one valid Convention:

experiment-model/
  recipe.md
  conventions/
    experiment.md

A strict portable recipe may also carry declared Reference documents and View definitions. Recipe authors should make each View entry self-contained for portability:

experiment-model/
  recipe.md
  conventions/
    experiment.md
  references/
    operating-model.md
  views-registry/
    experiment-dashboard.md
  views/
    experiment-dashboard.html

The manifest for that shape is:

---
type: Recipe
id: experiment-model
title: Experiment model
version: "1"
summary: Defines the Experiment domain concept.
offer: organize repeated experiments consistently
content_policy: definitions-only
references:
  - references/operating-model.md
pages:
  - registry: views-registry/experiment-dashboard.md
    entry: views/experiment-dashboard.html
---

composes, seeds, and requires are reserved manifest keys in this release. They produce a warning and have no application behavior.

With content_policy: definitions-only, every file must be a declared Convention, Reference, View registry, or View entry. Unsafe paths, missing declared files, duplicate governed types, malformed conventions, and undeclared files reject the recipe. Without that policy, legacy folders may carry ignored files outside conventions/; portable recipes should use the strict policy.

recipe add checks that each declared View entry is non-empty and matches a valid registry. It does not inspect the HTML for network dependencies, so self-containment remains a recipe-author portability responsibility.

Built-in and external recipes

superbee recipes lists the built-ins shipped with the CLI: context-notes, work-tracking, and roadmap. It can show that inventory before a bundle exists and reports whether each recipe's definitions are present when a bundle is available.

External recipes are addressed by path and are not included in the built-in inventory:

superbee recipe add ./experiment-model
superbee recipe add ~/shared-recipes/experiment-model

A bare name selects the built-in namespace. Prefix a local folder with ./ when its name contains no path separator. Filesystem loading resolves the recipe root, confines symlinks to that root, and rejects dot-prefixed paths under a strict portable recipe.

Application and safe evolution

Recipe application uses create-only writes for each definition. Reapplying identical definitions is an idempotent changed: false result. When an existing Convention differs from recipe source, Superbee reports source_differs, preserves the bundle-owned document, and points to an explicit version-checked promotion path. A recipe never overwrites a local definition merely because its manifest version changed.

Use this sequence when the domain model changes:

1. Run superbee kinds and superbee status --limit 0 to inspect the live schema and affected instances.

2. Add or remove one field with superbee kind field "<Kind>" add <name> or superbee kind field "<Kind>" remove <name>. New fields are optional unless --required is supplied, and --values <a,b,c> sets an enum on an added field.

3. For other convention changes, pull the current document, edit the frontmatter, and promote it with the version returned by the pull:

   superbee pull --doc-key conventions/experiment.md --out experiment.md
   superbee promote experiment.md \
     --doc-key conventions/experiment.md \
     --expected-version <version-from-pull>

4. Run superbee kinds and superbee status --limit 0 again. Update affected instances deliberately before tightening another constraint.

5. Update the reusable recipe only after the bundle-owned model and its instances prove the new shape. Reapplying the recipe reports drift for existing installations; it does not migrate them automatically in the current stable release.

Adding an optional field preserves conformance for existing instances. Adding a required field, narrowing an enum, or adding a required section can create conformance work immediately. The version-checked promotion prevents an unseen concurrent edit from being overwritten.

Instance creation

Create an instance from the live Kind, then inspect the saved document and bundle health:

superbee new "Experiment" onboarding-copy \
  --title "Shorter onboarding copy" \
  --progress_status running \
  --owner "Product research" \
  --body-file /tmp/onboarding-copy-experiment.md \
  --link "uses=datasets/customer-sample"

superbee doc read experiments/onboarding-copy
superbee status --limit 0

The declared path produces experiments/onboarding-copy. Pass --no-prefix when the requested ID is already intentional. Repeating a non-enum field flag creates an array; enum fields accept one value. A malformed --link value is rejected before the document write. A later link failure is reported separately because the create may already have succeeded.

Recovery

• Read registry_warnings from superbee kinds or superbee status when a Convention is absent from the live registry.

• Use superbee new "<Kind>" --help when an instance fails validation; it reports the live schema rather than a recipe's historical definition.

• Treat source_differs as a migration decision. Compare the installed Convention with recipe source before promoting any replacement.

• Run superbee status --limit 0 after schema changes and resolve the named instance IDs rather than assuming a successful definition write completed the migration.

Evidence

The pinned sources and tests governing this reference are:

• Kind parser and validator

• Kind registry discovery

• Kind-aware instance creation

• Recipe parser

• Recipe source resolution

• Filesystem recipe admission

• Recipe application

• Shared document mutation validation

• Kind behavior tests

• Recipe behavior tests

Related