Runtime Bootstrap, Singleton Management, Test Isolation, and Tool Discovery

The project uses a four-stage lazy-loading architecture that keeps startup token cost near ~200 tokens (meta-tools only) while making the full ~5000-token tool suite available on demand. Understanding the layer boundaries is essential for knowing where to make changes when adding managers, tool categories, or writing tests. The wrong layer means silent failures — missing singletons, invisible tools, or broken test imports. The tool_index meta-tool (Procedure F) is the discovery layer that surfaces those lazily-loaded tools to agents.

Prerequisites

• Familiarity with the project's runtime.py, main.py, and tools/ directory layout. Each app has its own copy under apps/{app}/src/{package}/ (e.g., apps/network/src/unifi_network_mcp/runtime.py).
• make manifest available (run from repo root; uv run make manifest if outside the venv)
• Any new tool category module must be created on disk before regenerating the manifest
• For Procedure F (tool discovery): two implementation surfaces exist — local server (per-app handler, e.g. apps/access/src/unifi_access_mcp/tool_index.py, plus the shared packages/unifi-mcp-shared/src/unifi_mcp_shared/tool_index.py) and Worker cloud (apps/worker/worker/src/). Both must move together.

Procedure A: Understanding the Bootstrap Sequence and Layer Ownership

Bootstrap follows four stages in strict order: