Diagnose selected context

Requires Bee 1.0.0-beta.16 or later with context doctor. Check command availability with bee context doctor --help.

An agent can inspect the size and availability of selected rules and context files before putting their bodies into a prompt. Doctor also counts supported tool and hook declarations without running them. Use the separate context audit command to find duplicate Markdown candidates. Neither command edits rules or decides which obligations can be removed.

Try a disposable example

Run this in Bash or zsh. It creates synthetic files outside your checkout and a private empty Bee profile. pwd -P resolves the physical directory: on macOS a path through /tmp or /var may contain a symlink that the reader refuses. The example command in mcp.json is deliberately fictitious.

demo_dir="$(mktemp -d "${TMPDIR:-/tmp}/bee-doctor-demo.XXXXXX")"
demo_dir="$(cd "$demo_dir" && pwd -P)"
mkdir "$demo_dir/profile"
printf '# Review 🐝\nRead selected files, keep required checks, and ask for review before changing any shared rule.\n' > "$demo_dir/rules.md"
cp "$demo_dir/rules.md" "$demo_dir/comparison.md"
cat > "$demo_dir/mcp.json" <<'JSON'
{"mcpServers":{"example":{"command":"bee-docs-example-only","args":["DEMO"],"env":{"EXAMPLE_MODE":"demo"}}}}
JSON
cat > "$demo_dir/manifest.json" <<JSON
{
  "schemaVersion": 1,
  "snapshotId": "doctor-demo",
  "rootPath": "$demo_dir",
  "inputs": [
    {"id": "rules", "path": "rules.md", "dialect": "markdown-atx-v1"},
    {"id": "tools", "path": "mcp.json", "dialect": "mcp-servers-json-v1"}
  ]
}
JSON
chmod 444 "$demo_dir/rules.md" "$demo_dir/comparison.md" "$demo_dir/mcp.json" "$demo_dir/manifest.json"
printf '%s\n' "$demo_dir"

The preparation writes only the demonstration files. The following Bee commands read them; their permissions are read-only. comparison.md is not selected by the doctor manifest.

BEE_HOME="$demo_dir/profile" bee context doctor --help
BEE_HOME="$demo_dir/profile" bee context doctor --manifest "$demo_dir/manifest.json" --json --budget 16384

Both commands exit 0. The report contains a read row for rules with one section and a declared row for tools with one MCP server and one environment entry. The Markdown file has 109 UTF-8 bytes, 107 UTF-16 code units, and an estimate of 27 tokens. The bee emoji is one visible character but uses four UTF-8 bytes and two UTF-16 code units. File bodies, headings, command strings and environment values are absent from the report.

Select the source explicitly

--manifest takes an absolute path to a regular UTF-8 JSON file. Its rootPath is an absolute physical directory; each input path is relative to that root. Doctor has no --root option. It does not discover additional files, follow dependsOn to new paths, or search private logs. Leaving a file out means it is unmeasured.

The manifest needs schemaVersion: 1, a snapshotId, and 1–64 inputs with distinct IDs and paths. Optional dependsOn values reference selected IDs and must form an acyclic graph; they do not prove loading order. The optional strict source declaration identifies caller-supplied provenance. sourceBinding: caller_declared_not_verified_against_files is not a verified source or delivery receipt; omit source if you do not have the required declaration.

Dialect	What is observed
`markdown-atx-v1`	`.md` file sizes and physical ATX section count; fenced headings are not section boundaries
`mcp-servers-json-v1`	`.json` object containing only `mcpServers`; supported command/URL declarations, environment and header entry counts, including disabled declarations
`claude-hooks-json-v1`	`.json` object containing only `hooks`; command hooks for `SessionStart`, `UserPromptSubmit` and `PreToolUse`

These are restricted schemas, not readers for every native settings file. Unknown dialects give unsupported_dialect; unsupported configuration shapes give unsupported_config. Malformed JSON, duplicate decoded property names and invalid Unicode are refused. Select appropriate governance files: common credential names are rejected, but doctor is not a general secret detector. IDs and selected paths remain visible in output.

Read the findings before acting

Check each input’s status and errorCode. Missing or refused input has unknown units, represented by null, not zero. Available rows remain visible, but declaredDiskTotals is null if any selected row is unavailable. An empty selection is invalid. Do not treat partial observations as a complete inventory.

configuration.inclusion: declared_not_loaded counts declarations; it proves neither execution nor delivery to a model. Even a separately established delivery would not prove model adherence. utf16-ceil-div4 version 1 estimates each file as ceil(UTF-16 units / 4) and totals those per-file estimates. It is not actual provider consumption, billing or demonstrated savings. Provider residuals remain unknown; this CLI does not attach a usage log.

Bound output and handle exits

Output is one JSON document followed by a newline, even without --json. --budget accepts 512–262144 UTF-8 bytes including the final newline, default 262144. Count encoded bytes, not visible characters or UTF-16 units. This is an output-size limit, not a token hard cap.

BEE_HOME="$demo_dir/profile" bee context doctor --manifest "$demo_dir/manifest.json" --budget 512

For this fixture, exit 5 returns errorCode: output_limit. Doctor replaces the oversized report with a small complete error document; it does not silently omit rows or truncate JSON, and has no --limit. Increase the budget within the allowed range or explicitly select fewer inputs. Stream-write failures propagate without a second JSON publication.

Exit	Meaning and next action
`0`	Help or complete observations; inspect the reported units and limitations
`4`	Invalid usage; check required manifest, exact flags, duplicates and budget range
`5`	Invalid, missing, unsupported or refused data, cancellation, or output limit; inspect error codes and correct the selection

Keep the exact leading context doctor command. Flags are not duplicated; --json is a boolean, and a leading flag or -- is not normalized into the doctor route.

Reads are capped at 64 inputs, 262144 bytes per file, 1048576 selected bytes total, 64 sections per Markdown file and JSON depth 16. Traversal, symlinks/reparse points, hardlinks and nonregular files are refused. Retained handles and rechecks detect changes, but checked_unchanged_not_atomic does not promise an atomic snapshot.

The 10-second deadline is cooperative: cancellation is checked during reading, parsing and verification. It cannot forcibly interrupt a blocked synchronous filesystem call and does not bound a blocked output stream. It is not a guaranteed ten-second wall-clock exit.

Investigate duplicate candidates next

BEE_HOME="$demo_dir/profile" bee context audit --help --json
BEE_HOME="$demo_dir/profile" bee context audit --from "$demo_dir/rules.md" --against "$demo_dir/comparison.md" --root "$demo_dir" --json

The two Markdown files are identical, so audit exits 1 for a complete report with duplicate candidates. Audit exit 0 means complete with no candidates; 4 means invalid usage and 5 means incomplete. Inspect omittedFindings and sourceInventory.omittedSections before treating the result as exhaustive. A duplicate candidate is evidence for review, not permission to delete a rule. See context audit and its limits.

Use bee budget --measured with an explicitly selected supported session log when you need reported provider counters; doctor estimates cannot replace them. Keep response/history streams and missing evidence distinct. This slice does not provide rule preview, import, apply or recovery. It neither modifies rules automatically nor launches agents, hooks or declared tools.