Bee Box

Bee Box is a personal assistant and operating system: agents process inputs, take actions, or ask questions. The filesystem is state, Git is history, and bbx is the command-line interface.

Design serves the values in spirit.md: if the architecture contradicts it, the architecture is wrong. docs/design/ explains why the system has its current shape.

bbx is the box agent's surface, not yours. Its verbs are what an agent running inside a box does there — read and write that box's cards, answer a question, run a procedure. Operators and the deploy scripts get bbx engine, a small permanent set that starts servers and manages the machine. End users get neither; they live in the web UI and chat. An agent developing Bee Box in this repository gets none of it: bbx health, bbx status, and bbx doctor are not developer diagnostics, and running them against a real box is touching someone's data to answer a question about your own code. Use the tests, the dev router, and the box's own files instead. src/cli/entry/surface-data.ts classifies every verb and says why.

Work only on the requested problem. Do not expand scope into adjacent cleanup, policy, schemas, UI, or workflows without the boxholder's approval. Read the relevant code, schema, and tests before changing a format or contract.

Never copy private box content or personal operational details into tracked source, docs, tests, or public issues. Follow the monorepo root's private-issues/ boundary, and ask when publication safety is uncertain.

Development

The monorepo root instructions own worktrees, the shared dev router, browser evidence, issues, privacy, landing, and deployment effects. Within this package:

• Use pnpm test:changed; it selects the tests implicated by the diff. Its first line gives the file count and an estimated time; an edit to a widely imported module can select half the suite and run 10 minutes or more, so when that line says to, run it in the background. node --import tsx ../bin/test-select.ts prints the same line and the list in about a second without running anything. Run a named test from beebox/ with pnpm exec tap test/<path>.test.ts; a frontend one is src/frontend/test/<path>. The hourly schedule runs the full pnpm test suite on main; do not run it in a worktree without a concrete reason.
• pnpm typecheck checks the backend and the separate frontend tsconfig. Run pnpm lint:changed during iteration; use full pnpm lint when changing broadly imported code. The pre-commit hook runs typecheck and lint. When lint:changed reports errors that pnpm exec eslint --no-cache <file> does not (run from beebox/ for backend files, from src/frontend/ for frontend files), its cache is stale: delete that directory's node_modules/.cache/eslint.
• pnpm layout-check enforces the file layout rules for module directories, re-exports, and test names. The pre-commit hook and pnpm lint:changed run it, finish-verify does not. Before adding a module or test file, read the rules; pnpm layout-check --explain <dir> prints that directory's unit graph.
• Write tests as .test.ts files that use t.check (reference). The testing guide explains test tiers and helpers. A selected failure is part of this change to investigate; do not dismiss it as pre-existing without evidence.
• Do not weaken or disable lint rules to pass. A true narrow false positive may use one eslint-disable-next-line <rule> -- <concrete justification>; other rule, severity, option, or suppression changes require explicit permission. max-lines and max-lines-per-function skip comments and blank lines, so trimming comments never passes them; split the module or function.
• Finish coordinated edits before responding to intermediate lint output, then resolve diagnostics introduced by or relevant to the change. Warnings, deprecations, and other unsolicited noise are actionable; routine success output belongs behind debug.

When committing, use plain git commit so hooks run, fix relevant failures, and leave no half-finished task changes. Never use --no-verify.

Production runs bundled dist/cli.mjs, not tsx. Resolve package assets through PACKAGE_ROOT in src/lib/package-root.ts. Deployment topology and rollback are in deploying.

Cards

Cards use YAML frontmatter plus a Markdown body and are named Name.<type>.card; the filename determines the schema. Attachments use the sibling Name.attach/ scope. Schemas live in src/schemas/, and boxes may add schemas through the public beebox/cards API. For format or attachment work, read the card format; for schema changes, the schema workflow; for changes to existing on-disk data, the migration runbook. The implemented RFC is design history, not the live manual.

Cards validate on load. When mutating existing card text, parse, change, and reserialize it; serialization follows schema field order and need not preserve the original frontmatter order. bbx validate and the hooks installed by bbx init provide broader validation; see card validation. Do not infer a card shape from an example when its schema is available.

Box Git trailers such as Created-By are structured metadata. Box commits use plain git commit so the installed pre-commit hook can run staged validation, link warnings, and the unlisted-binary guard.

Source Layout

Open the owner for the area being changed:

• Backend domain and orchestration: src/core/; reactor details: reactor design.
• Generic dependency-light helpers: src/lib/; browser/server shared code: src/shared/; CLI-domain helpers: src/cli/lib/; ambient declarations only: src/types/. The dependency rules and exact distinctions are in the module map.
• HTTP and tRPC: src/webapp/; use the API guide. tRPC is the default, including WebSocket subscriptions; raw Fastify routes are reserved for transports or authentication distinctions that do not fit tRPC.
• React UI: src/frontend/; read frontend.md before UI work. It owns primitives, semantic colors, source tagging, and the enforced className boundary.
• External dependencies: src/services/; read services guidance. Connectors live in src/connectors/; read connector guidance.
• Hub routing: src/hub/; read hub guidance. Tests mirror source paths under test/ and use helpers in test/helpers/.
• Schemas, developer tooling, deployment code, and validator plugins live in src/schemas/, src/dev/, deploy/, and plugins/ respectively.

Boxes live outside this repository. A box is one package and operational root with shapeVersion: 3; box code imports only public beebox/{cards,schema,view-widgets} specifiers and, for an activated plugin, beebox/plugins/<name>, never engine internals. Read the box layout before changing its on-disk shape, and box work before running anything against a box: the test box, a throwaway box, or production.

Key Concepts

bbx wakeup preprocesses intake, runs housekeeping and wakeup scripts, syncs connectors, runs the reactor over pending jobs, finalizes outbound work, and pushes the box. Recurrence belongs to bbx tick; see the scheduler. Services wrap external dependencies behind typed real and fake implementations. Connectors implement filesystem synchronization. Procedures are YAML-frontmatter workflows under a box's configuration; see the procedure guide.

Behavioral Notes

• Follow code-style.md. Preserve typed contracts and validate untrusted boundaries; do not add silent fallbacks for broken invariants.
• All box ref parsing and resolution goes through parseRef and resolveRefPath in src/shared/ref-path/core.ts. Never reproduce it with path.resolve, segment splitting, or manual fragment/query stripping. Resolution must fail closed when .. escapes the box.
• Use getBoxTime/getBoxTimeISO for timestamps so frozen scenario time works. Long-running timeouts use startAwakeTimeout; ordinary wall-clock timers expire across macOS sleep.
• Cross-process locks go through src/lib/file-lock.ts; never call proper-lockfile directly or create ad hoc lock files. Follow the more specific Git and same-card locking contracts in code-style.md.
• For frontend or iOS failures, inspect the box's .beebox/client-debug.log; [ios] identifies native entries. See the client debug log.
• Never change credentials to unblock testing. Ask the boxholder at a login wall. ~/.bbx-auth.json (or BBX_AUTH_FILE) is global across local boxes; bbx engine auth set-password revokes live sessions and cannot restore the old password. Mutating auth commands require --agent-confirmed, which means a human explicitly requested that credential change. Before writing any credential, token, or key, identify the actual store and scope. If a tool reports revocation, rotation, or invalidation, stop and verify what it affected.
• Keep shared source, prompts, schemas, rules, and docs generic. Use “the user” or “the boxholder”; personal names belong only where they are data. When an example needs names, use the fictional roster.

Improving These Instructions

When a correction exposes missing durable guidance, put a short rule at the narrowest accurate owner: this file for package-wide constraints, a nested AGENTS.md for an area, code-style.md or frontend.md for coding contracts, and docs/ for conditional reference material. New infrastructure must have a discoverable current owner. Do not use historical plans as live manuals.

Guides

Use the topic index to find a guide, and docs/README.md for documentation organization and naming. Common entry points are engineering principles, testing, cards, API endpoints, box layout, mobile contract, secrets, the production server, and deployment. Proposed work lives under docs/plans/; implemented plans and RFCs record history unless a current guide explicitly says otherwise.

@code-style.md