Question answered

What is inside a Superbee workspace, and how do its parts remain portable while gaining useful structure?

This explanation describes behavior verified against the current stable release and new OKF v0.2 bundles.

A bundle is a portable workspace

A bundle is a directory with a root index.md declaring its Open Knowledge Format version. Concept documents are Markdown files; non-document artifacts retain their original bytes. The document ID is its bundle-relative path without .md.

The conventional project location is .superbee/. From a project subdirectory, Superbee walks up to discover that folder much like Git discovers .git.

Resolution remains explicit and deterministic:

1. an explicit --dir selects a local bundle;

2. an explicit --remote selects a wire-protocol service and cannot be combined with --dir;

3. a supported project binding can point to an out-of-tree local bundle;

4. otherwise conventional local discovery walks upward; and

5. a private catalog label must be deliberately resolved and selected. Catalog entries never become ambient project context.

If valid .superbee/ and legacy .agentstate-lite/ bundles compete at one project level, Superbee refuses to choose.

Documents carry meaning

Every non-reserved concept document has YAML frontmatter with a non-empty type, followed by a Markdown body. Common fields such as title and description help people and agents scan results. Kinds may declare additional fields, allowed values, and expected headings for a particular type.

The generic path remains available even when no Kind exists:

superbee doc write decisions/storage \
  --type Decision \
  --title "Keep storage local"

Use doc update to patch an existing document while preserving unspecified fields and body. Use doc read for model-sized inspection, or its byte-channel options when complete Markdown, body, or canonical rendered HTML should bypass model context.

Kinds are bundle-owned conventions

Kinds live under conventions/ as ordinary convention documents. They can describe:

• required and optional fields;

• enum values;

• required body headings;

• freshness horizons; and

• typed outbound and expected inbound relationships.

superbee kinds lists the conventions active in the selected bundle. superbee new "<Kind>" creates a strictly validated instance and can add declared links in the same operation.

A bundle without conventions remains valid. Add a Kind only after repeated documents demonstrate a real consistency or lifecycle need.

Recipes install reusable structure

superbee recipes lists the definitions shipped with the installed release. The current set includes:

• context-notes;

• work-tracking; and

• roadmap.

The default initialization applies context-notes; --recipe none creates a bare bundle. Applying another recipe is explicit and idempotent:

superbee recipe add <name-or-path>

A recipe installs reusable definitions. Project instances remain separate, and the bundle owns the installed content.

Relationships remain ordinary links

A Markdown link from one concept document to another is the stored edge. Superbee derives the reverse backlink; backlinks are never copied into frontmatter.

superbee link add decisions/storage evidence/local-first --text "supported by"
superbee link show decisions/storage
superbee link list --text "supported by"

Adding the same relationship again is a no-op. A Kind may describe allowed or expected relationship labels. The documents' links remain the stored graph, so no separate edge database is required.

Versions protect concurrent work

Each document state has a content-derived version token. Mutations use compare-and-swap semantics; callers that supply --expected-version fail on a stale head and preserve newer content. Writes may carry an actor identity, and history-keeping backends expose the attributed chain through doc history. A plain local filesystem reports its current content version; Git can preserve the broader file history.

Views and artifacts serve humans

doc open and ui render documents through Superbee's shared bounded Markdown renderer. Registered Views use a version-bound bundle registration and an explicit trust boundary for richer presentations. artifact create packages a produced HTML output and its record in one operation.

These are presentation and output surfaces. They do not change which document or evidence is authoritative.