The short version

Superbee is a local, user-owned knowledge environment shared by humans and AI agents. It turns decisions, evidence, domain models, procedures, and useful representations that would otherwise disappear in chat into typed, linked Markdown that later sessions can inspect and extend.

The AI model remains the expert doing the work. Superbee preserves the results so later work can build on them.

This explanation describes behavior verified against the current stable release.

The core mental model

project
  -> bundle
      -> documents
          -> relationships
      -> optional Kinds and recipes
      -> human documents, Views, and artifacts

Bundle

A bundle is a folder of Open Knowledge Format Markdown and opaque artifacts. It is the unit that is kept local, shared, copied, reviewed, or published. The filesystem remains readable without Superbee; the CLI adds safe semantics and agent-friendly operations.

Document

A document preserves one meaningful thing. Every document has a type, may carry other structured fields, and has a Markdown body. A bundle can hold a decision, claim, experiment, interview, release, task, or a concept specific to the user's domain without Superbee adding a new subsystem.

Relationship

Relationships are ordinary Markdown links between documents. Superbee resolves and queries them, derives backlinks, and can validate link vocabulary declared by a Kind. The links remain useful in GitHub and ordinary editors.

Kind

A Kind is an optional convention document that makes a recurring domain concept consistent. It can declare fields, allowed values, required headings, freshness, and relationship vocabulary. A Kind does not replace the documents; it lets agents create and maintain repeated documents reliably.

Recipe

A recipe packages reusable definitions, including Kinds and, when declared, References or Views. Applying a recipe installs capability into the bundle; the resulting files belong to the bundle and remain inspectable. Recipes are useful when a stable structure should travel between projects.

Human representation

Documents render as Markdown pages. Registered Views are self-contained, explicitly trusted visual representations over bundle knowledge. Artifacts are produced outputs such as HTML meant to be shared with a human. The bundle's documents and evidence remain authoritative across all of these presentations.

Match structure to the project

Task tracking and roadmaps are optional. An agent should first understand the user's work and then add the smallest structure that removes repeated effort:

• one document when one important thing needs to persist;

• a relationship when two things need persistent context;

• a Kind when a domain concept recurs and inconsistency is costly;

• a recipe when stable definitions should be reused; or

• a View when humans repeatedly reconstruct the same overview.

The structure can evolve as the user's domain and questions change.

Humans and agents stay in control

Agents use the CLI because its structured, bounded output is predictable and economical. Humans can still read every Markdown file, inspect history through Git, and ask Superbee to open a specific document or View. Configuration and publication changes remain explicit human decisions.

Document writes are content-versioned and attributed. A stale writer receives a conflict, preserving the newer state. On a plain local filesystem, Git supplies longer history when the bundle is committed or shared.

Local, shared, and public are distinct

1. Local: superbee init creates a workspace on the current machine. This is the default.

2. Shared: superbee sync --establish is the separate explicit act that creates a shared board through a repository remote. Ordinary sync then exchanges board changes.

3. Public: a publication snapshot and site pipeline may expose a deliberately public bundle. Publishing is not implied by creating or cataloging it.

A private catalog provides explicit machine-local workspace selection. A catalog entry never makes that bundle the active context of an unrelated project.

Current maturity

Superbee is pre-1.0. The local bundle engine, agent-facing CLI, document presentation, Kinds, recipes, and Git sharing are functional, but commands and formats can still change. Release-specific pages identify the package they verify and keep unreleased source behavior separate.