Scope

Use this reference to determine which bundle a Superbee command will open, how a project can declare one local bundle, and how the private workspace catalog participates in explicit selection. The behavior is verified against the current stable release.

This page covers target selection. Bundle creation, synchronization, publication, and host setup have separate commands and safety decisions.

Selection summary

Remote and local selection use separate entry points:

The local precedence order is:

1. explicit --dir <path>;

2. the nearest present .superbee.json or compatible .agentstate.json project binding, which blocks resolution when malformed or unreadable; and

3. the nearest enclosing or conventional local bundle found by walking upward from the current directory.

The private workspace catalog does not participate in bare CLI resolution. An agent or user must resolve a catalog entry and pass its path with --dir, or select its label or ID through a catalog-aware MCP tool.

Inspect the resolved local target

Run the locator from the project and directory where the command will execute:

superbee bundle locate --json

A successful receipt has this shape:

{
  "schema_version": 1,
  "locator": {
    "kind": "local-path",
    "path": "/canonical/path/to/bundle"
  },
  "selected_by": "project-binding",
  "binding_file": "/path/to/project/.superbee.json",
  "available": true
}

binding_file appears only when a project binding selected the target. selected_by is one of explicit-dir, project-binding, or discovery. The locator path is canonical and can be passed back to an ordinary command with --dir.

bundle locate resolves local bundles only. It never reads or selects an HTTP remote.

Explicit local selection

Use --dir when one invocation must operate on a known local bundle:

superbee list --dir /path/to/bundle
superbee bundle locate --dir /path/to/bundle --json

An existing directory passed with --dir is an exact bundle boundary even when the optional root index.md is absent. A project directory can also serve as shorthand for its indexed direct .superbee/ or compatible .agentstate-lite/ child. An index.md in the explicitly named directory takes precedence over those children.

An unavailable explicit target fails. Superbee does not substitute an ancestor bundle for a misspelled or moved --dir path.

Project-local bindings

Place one .superbee.json file in the project when ordinary commands should use a local bundle at another path:

{
  "bundle": "../shared-knowledge/.superbee"
}

The binding rules are exact:

• bundle must be a non-empty filesystem path in a JSON object. The followed binding path must resolve to a bounded regular file; a symlink to such a file is accepted.

• A relative path resolves from the directory containing the binding file.

• Superbee walks upward from the current directory. The nearest binding wins.

• .agentstate.json remains accepted as a legacy project binding.

• Finding both binding filenames at the same directory level is a conflict, even when their targets match.

• A malformed or unreadable nearer binding blocks resolution. Superbee does not fall through to a farther binding or discovered bundle.

• A binding target is an exact declared directory and does not require index.md.

• URL values are rejected. Remote access requires --remote <url> on the command.

Project bindings are repository configuration. Commit a binding only when collaborators should use the same relative bundle relationship. Keep machine-specific absolute paths out of shared project configuration.

Local discovery

Without --dir or a project binding, Superbee walks from the current directory toward the filesystem root. At each directory level it checks, in order:

1. index.md in that directory, which identifies an enclosing bundle;

2. .superbee/index.md; and

3. .agentstate-lite/index.md for compatibility.

The nearest matching level wins. An enclosing bundle wins over a conventional child at the same level. If both conventional child directories are indexed at one level, resolution fails and asks the operator to choose which project bundle to keep.

Discovery requires index.md. Explicit --dir and project bindings can identify index-free bundle directories because the caller or repository already declared the boundary.

Explicit remote selection

Pass an HTTP or HTTPS service on every command that should use a remote bundle:

superbee list --remote https://example.invalid/superbee

Superbee normalizes the URL and opens the wire-protocol bundle named default on that service. Local project bindings, local discovery, and the private catalog do not override an explicit remote.

The retired AGENTSTATE_LITE_REMOTE environment variable cannot activate a remote. When no explicit target flag suppresses it, its presence produces a migration error directing the caller to --remote <url>.

For a gated remote, SUPERBEE_API_KEY supplies a session-specific credential. The compatible AGENTSTATE_LITE_API_KEY name remains accepted. Both names may be present only when their trimmed values agree; different non-empty values fail with USAGE before a request. If neither environment value is present, Superbee can use an already provisioned credential keyed by the remote origin. Credential selection does not change which bundle is selected.

Private workspace catalog

The catalog is an explicit address book for local bundles:

superbee catalog add research --dir /path/to/research/.superbee
superbee catalog list --json
superbee catalog resolve research --field path

catalog add resolves and records a canonical absolute local path. Labels use 1 to 64 lowercase letters, numbers, dots, dashes, or underscores. They begin and end with a letter or number, and the bnd_ prefix is reserved for generated IDs.

Catalog behavior has these boundaries:

• Registration is explicit. The catalog never scans for workspaces.

• Labels, IDs, and canonical paths are unique.

• catalog list derives current path availability without selecting an entry.

• catalog resolve accepts one label or generated ID, revalidates its path, and returns that exact entry.

• A resolved path must be passed to ordinary commands with --dir.

• A bare catalog-aware MCP server can list available entries and requires the selected workspace label or ID on workspace-scoped tools.

• Catalog entries do not change project bindings, synchronization state, or disclosure policy.

The catalog is user-scoped private operational state. Its relevant files are internal product data:

Superbee creates private-state directories and files with restricted permissions. Use Superbee commands and emitted recovery instructions instead of committing, copying, or casually editing these files. A project bundle must remain outside every guarded private-state root.

Failure and recovery table

The current stable catalog has no remove or relabel command. An unavailable entry therefore remains visible until its recorded path is restored or the private catalog is deliberately repaired. Use an explicit --dir path to continue bounded work without changing ambient project context.

Governing evidence

The package identity and stable verification boundary are recorded in the current release evidence. Bundle precedence, bindings, remote selection, and private-state exclusion are grounded in the tagged bundle.ts and bundle resolution tests. Locator receipts are grounded in the tagged bundle locate command and locator tests. Catalog storage, validation, and availability are grounded in the tagged catalog.ts, catalog command, and catalog tests. Private state and stored remote credentials are grounded in the tagged user-state.ts and credentials.ts.

Related