Outcome

Turn a proven recurring concept into a bundle-owned Kind, create one validated instance, relate it to supporting knowledge, and check existing records for migration work. This guide is for active users and agents who already have repeated examples of the concept.

The procedure is verified against the current stable release.

Before you start

• Run superbee home and confirm the intended bundle.

• Obtain the bundle owner's approval to add durable domain structure.

• Identify at least two existing records or repeated workflows that support the same useful shape.

• Decide which fields and sections apply to every instance.

Use one generic document first when the shape is still uncertain. A Kind begins governing every document with its declared type as soon as the convention is installed.

1. Inspect the existing domain

This example models recurring experiments. Inspect documents, conventions, recipes, and links before choosing names:

superbee list --type Experiment --limit 0
superbee kinds
superbee recipes
superbee link list --limit 100

Reuse established vocabulary. Record any existing Experiment documents because the new Kind will check them too.

2. Define the smallest stable Kind

Create a temporary recipe directory outside the bundle with this manifest at experiment-recipe/recipe.md:

---
type: Recipe
id: experiment-model
title: Experiment model
version: "1"
summary: Defines the Experiment domain concept.
content_policy: definitions-only
---
# Experiment model

Installs the reviewed Experiment convention.

Add experiment-recipe/conventions/experiment.md:

---
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]
  values:
    progress_status: [planned, running, complete]
  descriptions:
    progress_status: Current execution state.
    owner: Person responsible for the next action.
  terminal:
    progress_status: [complete]
links:
  uses: Dataset
link_descriptions:
  uses: Dataset used by the experiment.
sections: [Question, Method, Result]
freshness_horizon: 30d
---
# Experiment

Use this Kind for a bounded test with a stable question, method, and result structure.

The example declares only fields and headings supported by the repeated records. The uses relationship expresses real domain meaning between an Experiment and a Dataset.

3. Apply and inspect the definition

From the directory containing experiment-recipe, run:

superbee recipe add ./experiment-recipe
superbee kinds
superbee new "Experiment" --help

Check that the live Kind reports the expected path, fields, values, sections, freshness horizon, and link vocabulary. Recipe application creates an absent definition. If the bundle already owns a different conventions/experiment document, Superbee reports source drift and preserves the existing file. Review that definition and plan an explicit migration.

4. Create related knowledge and one instance

Check whether the example dataset ID is already present:

superbee doc read datasets/customer-sample

If that command reports that the document is missing, create it:

superbee doc write datasets/customer-sample \
  --type Dataset \
  --title "Customer sample"

doc write can replace an existing document. If the ID already exists, use that record only when it is the intended dataset; otherwise choose a new ID and use it in the --link command below.

Save this body as /tmp/onboarding-copy-experiment.md:

# Question

Does shorter onboarding copy improve completion?

# Method

Compare the current and shorter variants with the same customer sample.

# Result

Pending.

Create the governed instance and its typed relationship:

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"

The Kind's path places the document at experiments/onboarding-copy. new is create-only and rejects missing fields, unknown fields, disallowed values, or missing required headings before it writes the instance.

5. Verify the model and migration surface

superbee doc read experiments/onboarding-copy
superbee link show experiments/onboarding-copy --text "uses"
superbee list --type Experiment --limit 0
superbee status --limit 0

Confirm that the instance contains the declared fields and sections, the typed link reaches a Dataset, and status reports no defect caused by the new record. Review every Kind warning or conformance-debt row for older Experiment documents. Update those records deliberately or revise the proposed convention before treating the model as established.

Evolve from observed use

Add a field after real instances show that it is useful:

superbee kind field "Experiment" add confidence \
  --values low,medium,high

An optional field preserves existing conformance. Adding a required field makes missing values visible in superbee status, which is useful only when a migration is ready. Changes to sections, relationship vocabulary, or freshness require a deliberate update to the bundle-owned convention and another whole-bundle status check.

Package the model for another bundle after its definitions stabilize. Keep project experiments and results out of the recipe so each bundle retains its own instance data.

Recovery and limits

• If the recipe is malformed, correct the named manifest or convention field and retry. The definitions-only policy rejects undeclared files before any write.

• If recipe application reports source drift, inspect the installed convention. Superbee leaves its bytes untouched.

• If new reports an existing ID, read and update that instance or choose a distinct ID.

• If a typed link warns about source or target type, inspect both documents and correct the model or target.

• If the new Kind creates widespread conformance debt, pause the rollout and agree on a migration before tightening the convention.

Evidence

The released implementation and tests for this journey are:

• Kind convention parser

• Strict Kind instance creation

• External recipe application and drift tests

• Bundle-wide conformance tests