Architecture

BeeWeave has two important boundaries: repository source files and runtime workspace files.

Source Repository

beeweave/       # Python CLI and helpers
.skills/        # source skill definitions
bootstrap/      # agent bootstrap templates
extensions/     # browser extension assets
tests/          # pytest suite
openspec/       # proposed and active changes
docs/           # MkDocs source documentation

The Python package provides the bwe CLI. The wheel bundles source skills and bootstrap templates under package data so a package install can set up agents without a cloned repository.

Runtime Workspace

Runtime folders are created by bwe setup in the user-selected workspace:

project/
+-- vault/                  # durable Markdown knowledge
+-- workbench/              # captures, sources, drafts, and inbox material

These folders are user data. They are not source documentation and should not be committed to the BeeWeave repository root.

Main Components

• CLI lifecycle: beeweave/cli.py creates runtime context, dispatches parsed commands, runs cross-cutting notices, and maps expected failures.
• Command adapters: beeweave/commanding.py and beeweave/commands/ define an explicitly ordered argparse tree, interaction, and result presentation.
• Runtime infrastructure: runtime.py, configuration.py, and catalog.py provide immutable paths, profile/config rules, and typed resource metadata.
• Setup application: beeweave/setup/ separates selection, resource lookup, workspace initialization, installation, planning, execution, and status.
• Skills: .skills/wiki/ and .skills/workbench/ hold the source skill packages installed into agents.
• Bootstrap: bootstrap/ contains agent rules and instructions copied into user workspaces.
• Browser extension: extensions/brain-capture/ captures selected web content into the workbench inbox.
• OpenSpec: openspec/ records proposed changes before implementation.

The enforced dependency direction is:

cli -> command adapters -> application services -> domain/filesystem

Application and domain code has no argparse or terminal presentation dependency. AppContext is created at execution time and supplies only runtime environment data, not arbitrary services. Human results flow through ui.py; machine commands write only their documented JSON or plain-text payload to stdout.

Design Boundary

MkDocs builds this wiki from docs/ into site/. The site/ directory is a local build artifact and is deployed from CI to gh-pages; it is not maintained as source on main.